{"_id":"@artisann-studios/omp-zvec-grep","name":"@artisann-studios/omp-zvec-grep","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@artisann-studios/omp-zvec-grep","version":"0.1.0","type":"module","description":"Native Oh My Pi zvec-grep search, indexing, and status tools","license":"Apache-2.0","publishConfig":{"access":"public"},"homepage":"https://github.com/ImArtisann/omp-zvec-grep","repository":{"type":"git","url":"git+https://github.com/ImArtisann/omp-zvec-grep.git"},"bugs":{"url":"https://github.com/ImArtisann/omp-zvec-grep/issues"},"keywords":["oh-my-pi","omp","extension","zvec-grep","semantic-search","code-search","local-first"],"engines":{"bun":">=1.4.2"},"omp":{"extensions":["./index.ts"]},"scripts":{"check":"bun run typecheck && bun run lint && bun run format:check","typecheck":"tsc --noEmit --strict","lint":"oxlint . --no-error-on-unmatched-pattern","format:check":"oxfmt --check .","format":"oxfmt --write .","test":"bun test","test:integration":"bun test test/integration","test:cli":"bun test/cli/smoke.ts","lint:fix":"oxlint --fix . --no-error-on-unmatched-pattern","prepare":"bunx --bun husky"},"peerDependencies":{"@oh-my-pi/pi-coding-agent":"18.1.11","@oh-my-pi/pi-tui":"18.1.11","@oh-my-pi/pi-utils":"18.1.11"},"devDependencies":{"@oh-my-pi/pi-coding-agent":"18.1.11","@oh-my-pi/pi-tui":"18.1.11","@oh-my-pi/pi-utils":"18.1.11","@oxlint/plugins":"1.77.0","@types/bun":"1.3.4","husky":"^9.1.7","lint-staged":"^17.5.0","oxfmt":"^0.66.0","oxlint":"1.77.0","oxlint-tsgolint":"7.0.2001","typescript":"7.0.2"},"gitHead":"ad05bba89411a1aa06b2244d840e83c26ae74055","_id":"@artisann-studios/omp-zvec-grep@0.1.0","_nodeVersion":"26.7.0","_npmVersion":"11.19.0","dist":{"integrity":"sha512-JEZpYHULPTUSeUJh/atmAfqZjNbgeBT7OodDNTBNtmfUn6UdTIpQ5qfONaDrqZqOO0y/VsEVMYeFIumQH7QuDQ==","shasum":"844eeca0956f4d52684e0bc79a9ece31f5ce0240","tarball":"https://registry.npmjs.org/@artisann-studios/omp-zvec-grep/-/omp-zvec-grep-0.1.0.tgz","fileCount":18,"unpackedSize":120848,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCICEnqKDUv+hz/mFucn1nVm7io5I01CbpN1cWJIh/n02gAiBWCekHrDZ7ydqfO6YvykKWyFAC30uRBPBOYHK+fq9S0A=="}]},"_npmUser":{"name":"artisann","email":"artisann@artisann.dev"},"directories":{},"maintainers":[{"name":"artisann","email":"artisann@artisann.dev"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/omp-zvec-grep_0.1.0_1788659956513_0.7006257411450802"},"_hasShrinkwrap":false}},"time":{"created":"2026-09-06T01:59:16.343Z","0.1.0":"2026-09-06T01:59:16.638Z","modified":"2026-09-06T01:59:16.826Z"},"maintainers":[{"name":"artisann","email":"artisann@artisann.dev"}],"description":"Native Oh My Pi zvec-grep search, indexing, and status tools","homepage":"https://github.com/ImArtisann/omp-zvec-grep","keywords":["oh-my-pi","omp","extension","zvec-grep","semantic-search","code-search","local-first"],"repository":{"type":"git","url":"git+https://github.com/ImArtisann/omp-zvec-grep.git"},"bugs":{"url":"https://github.com/ImArtisann/omp-zvec-grep/issues"},"license":"Apache-2.0","readme":"# omp-zvec-grep\n\nPrivate native [Oh My Pi](https://github.com/can1357/oh-my-pi) extension\nexposing local [zvec-grep](https://github.com/zvec-ai/zvec-grep) (`zg`) as\nagent-native discovery: hybrid lexical + vector search over an indexed\nworkspace, with explicit index lifecycle and status surfaces. Native OMP port of\n`pi-zvec-grep`; upstream history and attribution are retained (see\n[UPSTREAM.md](UPSTREAM.md), [LICENSE](LICENSE), and\n[docs/compatibility.md](docs/compatibility.md)).\n\n## Requirements\n\n- Oh My Pi `18.1.11` (pinned peer: `@oh-my-pi/pi-coding-agent`,\n  `@oh-my-pi/pi-tui`, `@oh-my-pi/pi-utils`).\n- The real `zg` CLI `0.2.1` preinstalled on `PATH` (`zg --version`). It is a\n  separate install — the extension never installs it:\n  `npm i -g @zvec/zvec-grep@0.2.1`. The first actual index build may download a\n  local embedding model; nothing downloads during extension load.\n- Bun `1.4.2` — the tested runtime: OMP's engine loads TS extensions on Bun, and\n  the development toolchain runs on Bun (`engines.bun` requires `>= 1.4.2`; CI\n  and local checks pin `1.4.2`).\n\nNo extension-load path spawns a subprocess, installs `zg` or models, makes\nnetwork requests, or mutates active host tools. Indexing, status, and search\nexecute the preinstalled `zg` binary with an explicit cwd, an abort signal, and\nper-action timeouts.\n\n## Install\n\nThe extension publishes to the npm registry as the **public** scoped package\n`@artisann-studios/omp-zvec-grep` — anyone can install it, no account or token\nneeded. The GitHub repository `https://github.com/ImArtisann/omp-zvec-grep` is\npublic too. Install from npm (public) or clone and link.\n\n**From npm (published artifact)** — the OMP 18.1.11 plugin CLI accepts npm\nspecs, so anyone installs the pinned release with:\n\n```sh\nomp plugin install @artisann-studios/omp-zvec-grep@0.1.0\n```\n\nThis is only available after the release has actually been published (see\n`docs/release-checklist.md`); nothing below claims a publish that has not run.\n\n**One-off session load** — from the checkout root, load the extension for that\nlaunch only (no persistent change):\n\n```sh\nomp --extension ./index.ts\n```\n\nThe `-e`/`--extension` flag takes an extension file, is repeatable, and accepts\nabsolute paths (`omp --extension /path/to/omp-zvec-grep/index.ts`).\n\n**Persistent plugin** — record a local checkout as a plugin (symlinked into\nOMP's plugins directory and persisted across sessions):\n\n```sh\nomp plugin link /absolute/path/to/omp-zvec-grep\n```\n\n`omp plugin link` resolves the path against the current directory, so pass an\nabsolute path; it reads `package.json` (this package is\n`name: \"@artisann-studios/omp-zvec-grep\"`). `omp plugin install /absolute/path`\nroutes local paths through the same link flow — either verb works for a\ndirectory. New sessions load the linked plugin.\n\n**From the GitHub repo** — clone (public, no auth needed), then link:\n\n```sh\ngit clone https://github.com/ImArtisann/omp-zvec-grep.git\ncd omp-zvec-grep\nomp plugin link \"$PWD\"\n```\n\n`/zg settings` requires the interactive TUI; in non-TUI modes it reports that it\nis unavailable.\n\n## Surface\n\n- `zvec_search` — hybrid semantic + keyword search over a locally indexed\n  workspace. Pass `query`, or explicit groups `queries` / `fts` / `vector`,\n  optional `fuse`, `limit` (default 7, hard cap 50), path `globs`, `fileTypes` /\n  `excludedFileTypes`, `symbolTypes` / `preferSymbol`, `modifiedAfter` /\n  `modifiedBefore`, and a `root` (defaults to the current working directory).\n  Use it for semantic, fuzzy, or location-unknown questions.\n- `zvec_index` — create/update the workspace index, or `mode: rebuild` /\n  `mode: drop` it. `rebuild` and `drop` are destructive and only run on explicit\n  request (drop passes `--yes`). Optional `embedding`, `globs`, file-type\n  filters, and `hidden`. `root` is required. A workspace must be indexed before\n  searching.\n- `zvec_status` — report index presence, coverage, and freshness. **Missing or\n  stale indices are normal status outcomes**, not tool failures.\n- `/zg <index|rebuild|drop|status|settings|help> [path]` — command surface with\n  argument completion. `path` is the whole remainder of the argument string and\n  may be quoted (`/zg status \"/path/with spaces\"`) when it contains spaces; bare\n  `/zg` or an unknown subcommand prints usage. `rebuild` and `drop` announce\n  themselves as explicit destructive operations before running. `/zg settings`\n  opens the interactive settings menu.\n\n### Semantic search or native tools?\n\n`zvec_search` answers meaning/fuzzy/unknown-location questions against an index.\nFor exact strings, regex, filenames, counts, file lists, or anything piped, use\nOMP's native `grep`/`glob` tools or the shell's `rg` instead — zg's managed `rg`\nsubset intentionally cannot do counts, file lists, or pipes. This routing is\nbaked into the tool descriptions so the agent picks the right surface.\n\n## Configuration\n\nTwo layers, both read fresh (cheap per-file mtime cache) so hand edits take\neffect immediately:\n\n- **User defaults**: `<agentDir>/omp-zvec-grep/config.json`, where `agentDir` is\n  OMP's public `getAgentDir()` (honors `PI_CODING_AGENT_DIR` and OMP profiles;\n  this is the native OMP location, not a legacy Pi agent dir shim). This file\n  holds values only — scope flags never apply from it, and stray legacy keys are\n  stripped on the next user-layer save.\n- **Workspace (project)**: `<workspace>/.zvec-grep/config.json`, anchored at the\n  current working directory with no walk-up. It is **self-contained**: built-in\n  defaults + its contents, with a boolean `projectScope` activation flag. `true`\n  makes this file authoritative **for this workspace only** (no user values\n  mixed in), so a committed file means the same on every machine and can never\n  flip another workspace. `false` (or a hand-written file without the flag)\n  leaves the values **dormant** and applies the user layer; deactivating project\n  scope preserves the parked values and unrelated keys. A legacy\n  `settingsScope: \"project\"` string is honored as `true` read-only (never\n  written).\n\nDefaults: `defaultLimit: 7` (valid range 1–50, hard cap 50) and\n`autoIndex: false`. Writes stay inside the resolved workspace and refuse\nsymlinked, redirected, or non-owned config paths.\n\n**Moving old Pi-era user settings** is an explicit opt-in, one-time step you run\nyourself — the extension has no automatic importer and never reads the old\n`pi-zvec-grep` user config.\n[docs/pi-config-migration.md](docs/pi-config-migration.md) documents a\nconservative copy-only snippet plus manual steps: only the user values\n`defaultLimit` and `autoIndex` are copied into\n`<agentDir>/omp-zvec-grep/config.json` (destination resolved via the public\n`getAgentDir()` under the project's Bun, honoring `PI_CODING_AGENT_DIR` and OMP\nprofiles, or an agent dir you supply), the destination must not already exist,\nscope flags are never copied, the old config is never deleted, and zg indexes\nare never rebuilt or dropped — zg 0.2.1 indexes at the same `.zvec-grep`\nworkspace location keep working.\n\n**Auto-index (default off)**: when enabled, every `session_start` runs a\nreadiness guard (`zg status --check-ready`) in the working directory; only a\nmissing or stale index triggers a background build (fire-and-forget,\nper-workspace deduplication, cancelled at session shutdown). A healthy index\ncosts one cheap guard call per start. Off by default because the first build can\ntake a while and may download the local embedding model.\n\n## Errors and rendering\n\n- **Missing index — expected, but status and search differ**: `zvec_status`\n  treats a missing or stale index as a normal outcome (a verdict line, never a\n  tool failure). `zvec_search` before any index exists is different: zg exits\n  nonzero, so the tool throws an error carrying zg's `WORKSPACE_INDEX_NOT_FOUND`\n  diagnostic; that error is the expected signal (the tool description tells the\n  agent to run `zvec_index` first), not an operational failure such as a missing\n  `zg` binary or a timeout.\n- **Operational failures**: `zg` not installed →\n  `<action> unavailable: zg CLI was not found`; a nonzero exit → the stderr/exit\n  code is surfaced; per-action timeouts (query 180s, index 600s, status 30s) →\n  `<action> timed out after Ns`; an agent abort/cancel → `<action> cancelled`.\n- **Rendering**: tools use native custom renderers (`renderCall` /\n  `renderResult`) with themed summary lines — e.g. hit/file counts with a stale\n  marker and the top hit headline for search, scanned/entity counts for\n  indexing, and a colored verdict line for status — with expandable previews\n  that clip long raw output instead of dumping it.\n\n## Development and CI\n\nRequires Bun `1.4.2+` and the OMP `18.1.11` dev pins. No command here publishes\nthe package; the public `@artisann-studios/omp-zvec-grep` release happens only\nthrough the explicit publish workflow (`.github/workflows/publish.yml`).\n\n```sh\nbun install --frozen-lockfile\nbun run check                 # typecheck + lint + format:check\nbun test                      # hermetic default: real host loader, deterministic fake zg\nbun run test:integration      # explicit hermetic integration suites\nbun run test:cli              # REAL zg contract smoke — explicit opt-in lane\nbun scripts/validate-pack.mjs # pack contents + out-of-tree install guard\n```\n\n- `bun test` and `test:integration` are hermetic: a deterministic fake `zg` on\n  `PATH`, disposable agent/workspace dirs, the real OMP SDK loader/runner\n  (`createAgentSession`) in isolated workers — no real zg, no network, no model,\n  no skip gates.\n- `test:cli` runs `test/cli/smoke.ts` against the **installed** `zg 0.2.1`\n  (help/version/rg/no-index contract; deliberately no model or network work\n  today). It is not part of the default hermetic command.\n- CI (`.github/workflows/ci.yml`) runs the frozen install, `check`, `bun test`,\n  `test:integration`, and pack validation on every branch push and pull request\n  on `ubuntu-latest` (Linux x64) and `macos-15` (GitHub-hosted Apple Silicon,\n  arm64). A separate `real-zg-smoke` job is manual-only (`workflow_dispatch`,\n  never push/PR): it pins Node 22 (the zg CLI requires `node >= 22`) and\n  installs the pinned upstream `@zvec/zvec-grep@0.2.1` CLI, then runs\n  `test:cli`; it stays opt-in because an index-building assertion would download\n  a local embedding model on first build.\n  `.github/workflows/release-validation.yml` is the manual release-candidate\n  gate (read-only, no publish).\n- Exercised locally on macOS arm64. The CI lanes (including Linux x64) are\n  defined but unverified until GitHub actually runs them — a skipped manual-only\n  job is not a result, and nothing here claims any CI lane has run or passed.\n\n## Provenance\n\nNative port of `pi-zvec-grep` v0.3.1\n(`db7b42db4a84dc724c3347fbcc2bdf32792882d6`), pinned against OMP `18.1.11`\n(`e3106be68f778635da3a17106835ce2e0e6992af`) and zg `0.2.1`\n(`426cd3bf9bf81f34a884945abafc58709897dadf`). Upstream Apache-2.0 license and\nnotices preserved in [LICENSE](LICENSE); provenance in\n[UPSTREAM.md](UPSTREAM.md); baseline and evidence in\n[docs/compatibility.md](docs/compatibility.md); cutover checklist in\n[docs/release-checklist.md](docs/release-checklist.md).\n","readmeFilename":"README.md","_rev":"1-ce96a848d86ba05009a4830f4c0a7d45"}