@vizalice/codegraph 1.5.0

package/dist/installer/targets/types.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Agent target abstraction for the installer.
+ *
+ * Each MCP-capable agent (Claude Code, Cursor, Codex CLI, opencode, ...)
+ * implements this interface so the installer orchestrator can write the
+ * right MCP-server config + instructions file + permissions for that
+ * agent without baking client-specific paths into core code. Adding a
+ * new agent = one new file in `targets/` + one entry in `registry.ts`.
+ *
+ * Closes the Claude-locked installer issue (upstream #137). The
+ * runtime MCP server is already agent-agnostic; this brings the
+ * installer to the same surface.
+ */
+export type Location = 'global' | 'local';
+/**
+ * Stable string id used in the `--target` CLI flag and the registry
+ * lookup. New targets add a value here when they're added to the
+ * registry. Keep these short and lowercase.
+ */
+export type TargetId = 'claude' | 'cursor' | 'codex' | 'opencode' | 'hermes' | 'gemini' | 'antigravity' | 'kiro' | 'copilot-vscode' | 'copilot-cli' | 'copilot-jetbrains' | 'zcode' | 'dsh';
+/**
+ * Result of `target.detect(location)`.
+ *
+ * `installed` is a best-effort heuristic that the agent's CLI / app /
+ * config dir is present on this system — used to default the
+ * multiselect prompt to "what's actually here." False positives are
+ * acceptable (we still write); false negatives just mean the user
+ * has to opt in manually.
+ *
+ * `alreadyConfigured` reports whether codegraph has already been
+ * wired into this target at this location — drives the
+ * "Updated"-vs-"Added" log line and lets `--check` exit 0/1.
+ */
+export interface DetectionResult {
+    installed: boolean;
+    alreadyConfigured: boolean;
+    /** Path inspected; surfaced in diagnostic / dry-run output. */
+    configPath?: string;
+}
+/**
+ * What `target.install(location)` actually changed on disk. The
+ * orchestrator renders one log line per file using `action`.
+ *
+ * `unchanged` means we touched the file but its contents were already
+ * what we'd write — used for byte-identical idempotent re-runs.
+ */
+export interface WriteResult {
+    files: Array<{
+        path: string;
+        action: 'created' | 'updated' | 'unchanged' | 'removed' | 'not-found' | 'kept';
+    }>;
+    /**
+     * Optional one-line notes the orchestrator surfaces verbatim — e.g.
+     * "Restart Cursor to apply." Keep these short; multi-line goes in
+     * the README.
+     */
+    notes?: string[];
+}
+export interface InstallOptions {
+    /**
+     * Whether to write the agent's permissions / auto-allow surface
+     * (Claude `settings.json`, others where applicable). When the
+     * target has no permissions concept this option is a no-op.
+     */
+    autoAllow: boolean;
+    /**
+     * Front-load prompt hook (Claude and ZCode both expose a
+     * `UserPromptSubmit` event) that injects codegraph_explore context for
+     * structural prompts. `true` installs it,
+     * `false` removes any prior install (so opt-out round-trips), `undefined`
+     * leaves it untouched. Targets without a prompt-hook concept ignore it.
+     */
+    promptHook?: boolean;
+}
+export interface AgentTarget {
+    /** Stable id; matches the `TargetId` union. */
+    readonly id: TargetId;
+    /** Human-readable name shown in clack prompts and log lines. */
+    readonly displayName: string;
+    /** Optional URL for "where do I learn more about this agent." */
+    readonly docsUrl?: string;
+    /**
+     * Whether this target supports the given install location.
+     *
+     * Some agents (Codex CLI as of 2026-05) have no project-local
+     * config concept — only a single `~/.codex/` dir. Returning false
+     * for an unsupported (target, location) pair lets the orchestrator
+     * skip cleanly with a clear message.
+     */
+    supportsLocation(loc: Location): boolean;
+    detect(loc: Location): DetectionResult;
+    install(loc: Location, opts: InstallOptions): WriteResult;
+    /**
+     * Inverse of install. Removes only what install would have written;
+     * preserves sibling MCP servers, sibling permissions, and unrelated
+     * markdown sections. Must be safe to call when nothing was ever
+     * installed (returns `not-found` actions).
+     */
+    uninstall(loc: Location): WriteResult;
+    /**
+     * Print the MCP-server snippet a user would paste manually for this
+     * target. Used by `codegraph install --print-config <id>` and by
+     * the README. Must NOT touch the filesystem.
+     */
+    printConfig(loc: Location): string;
+    /** Filesystem paths this target would write to at this location. */
+    describePaths(loc: Location): string[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/installer/targets/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/installer/targets/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,MAAM,QAAQ,GAAG,QAAQ,GAAG,OAAO,CAAC;AAE1C;;;;GAIG;AACH,MAAM,MAAM,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,OAAO,GAAG,UAAU,GAAG,QAAQ,GAAG,QAAQ,GAAG,aAAa,GAAG,MAAM,GAAG,gBAAgB,GAAG,aAAa,GAAG,mBAAmB,GAAG,OAAO,GAAG,KAAK,CAAC;AAE5L;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,OAAO,CAAC;IACnB,iBAAiB,EAAE,OAAO,CAAC;IAC3B,+DAA+D;IAC/D,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,KAAK,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,WAAW,GAAG,SAAS,GAAG,WAAW,GAAG,MAAM,CAAC;KAChF,CAAC,CAAC;IACH;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IACH,SAAS,EAAE,OAAO,CAAC;IACnB;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,WAAW;IAC1B,+CAA+C;IAC/C,QAAQ,CAAC,EAAE,EAAE,QAAQ,CAAC;IACtB,gEAAgE;IAChE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,iEAAiE;IACjE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;;;;OAOG;IACH,gBAAgB,CAAC,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC;IACzC,MAAM,CAAC,GAAG,EAAE,QAAQ,GAAG,eAAe,CAAC;IACvC,OAAO,CAAC,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,cAAc,GAAG,WAAW,CAAC;IAC1D;;;;;OAKG;IACH,SAAS,CAAC,GAAG,EAAE,QAAQ,GAAG,WAAW,CAAC;IACtC;;;;OAIG;IACH,WAAW,CAAC,GAAG,EAAE,QAAQ,GAAG,MAAM,CAAC;IACnC,oEAAoE;IACpE,aAAa,CAAC,GAAG,EAAE,QAAQ,GAAG,MAAM,EAAE,CAAC;CACxC"}

package/dist/installer/targets/types.js

@@ -0,0 +1,16 @@
+"use strict";
+/**
+ * Agent target abstraction for the installer.
+ *
+ * Each MCP-capable agent (Claude Code, Cursor, Codex CLI, opencode, ...)
+ * implements this interface so the installer orchestrator can write the
+ * right MCP-server config + instructions file + permissions for that
+ * agent without baking client-specific paths into core code. Adding a
+ * new agent = one new file in `targets/` + one entry in `registry.ts`.
+ *
+ * Closes the Claude-locked installer issue (upstream #137). The
+ * runtime MCP server is already agent-agnostic; this brings the
+ * installer to the same surface.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/installer/targets/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/installer/targets/types.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;GAYG"}

package/dist/installer/targets/zcode.d.ts

@@ -0,0 +1,106 @@
+/**
+ * ZCode target. Writes:
+ *
+ *   - MCP server entry to `~/.zcode/cli/config.json` (global) or
+ *     `./.zcode/config.json` (local) under the NESTED `mcp.servers.codegraph`
+ *     key — NOT Claude/Cursor's top-level `mcpServers`. Plain stdio shape
+ *     `{ type: 'stdio', command, args: ['serve', '--mcp'] }` that does not
+ *     proactively write `enabled` (absent means enabled). A user-set
+ *     `enabled` value (e.g. a manual `enabled: false` disable) is preserved
+ *     when an install rewrites the entry — see writeMcpEntry.
+ *   - Instructions to `~/.zcode/AGENTS.md` (global) or `./AGENTS.md`
+ *     (local — ZCode reads the project root file directly, not one under
+ *     `.zcode/`).
+ *   - Front-load prompt hook (global only) into the same config.json under
+ *     `hooks.events.UserPromptSubmit` (phase two, §7.1): a `process` hook
+ *     running `<node> <CLI entry js> prompt-hook --context-json`. ZCode is
+ *     the second client in the ecosystem with a UserPromptSubmit event, but
+ *     it parses hook stdout as STRICT JSON — hence the `--context-json`
+ *     envelope flag (see src/prompt-hook-output.ts). Workspace-level hooks
+ *     are IGNORED by the current ZCode (logged, never run), so a local
+ *     install with promptHook skips the hook and says so. The evidence is
+ *     mixed: the official web docs (zcode.z.ai/en/docs/hooks) state the
+ *     current version ignores workspace-level hooks, while the locally
+ *     installed zcode-guide documentation lists workspace config as a
+ *     legitimate hook source. Not verified empirically — global-only is
+ *     the conservative correct choice; if workspace hooks are ever
+ *     confirmed to run, extend this target with a local hook write.
+ *
+ * ZCode launches the MCP server with the correct project cwd (verified),
+ * so no `--path` correction is injected (Claude/Codex class, not Cursor).
+ * No permissions concept — a no-op like Codex.
+ *
+ * The config file is NEVER deleted on uninstall: it can carry `plugins` /
+ * `skills` / sibling servers. Uninstall only prunes `mcp.servers.codegraph`,
+ * any container (`mcp.servers`, `mcp`) that becomes empty, and our prompt
+ * hook entry — `hooks.enabled` is left alone (it may serve the user's own
+ * hooks), so even a fully emptied `hooks: { enabled: true }` survives.
+ */
+import { AgentTarget, WriteResult } from './types';
+import { resolveCodegraphCliEntry } from './shared';
+/**
+ * Resolve the `command` for the ZCode MCP entry (D1).
+ *
+ * On Windows the launcher on PATH is `codegraph.cmd`, and Node spawns `.cmd`
+ * shims only through a shell — a bare `codegraph` fails (the same lesson the
+ * Claude prompt hook learned, #1466). We scan PATH for `codegraph.cmd` and
+ * return its absolute path (the form already validated on this machine's
+ * hand-written ZCode entry); when it isn't found we fall back to the
+ * `codegraph.cmd` spelling. Other platforms use the bare `codegraph`.
+ *
+ * The absolute path is normalized to forward slashes: the hand-written entry
+ * form validated on this machine uses them, and ZCode/Node spawn both forms
+ * identically on Windows — but `jsonDeepEqual` does NOT, so keeping
+ * `path.join`'s backslashes would flag a byte-identical existing entry as
+ * `updated` instead of `unchanged` on first run.
+ *
+ * Exported so the unit tests can pin the PATH-scan and fallback behavior.
+ */
+export declare function resolveZcodeMcpCommand(): string;
+/**
+ * Historical alias for the CLI-entry derivation now lifted into
+ * `shared.ts` (the dsh target's hooks.json needs the same walk).
+ * Re-exported under the old name so existing imports — and the unit
+ * tests that pin the layout walk — keep working unchanged. See
+ * `resolveCodegraphCliEntry` in shared.ts for the rationale.
+ */
+export { resolveCodegraphCliEntry as resolveZcodeCliEntry };
+/**
+ * The ZCode prompt hook the installer writes (see
+ * writeZcodePromptHookEntry): `node <entry js> prompt-hook --context-json`.
+ * `type: "process"` (argv-direct execution, no shell — ZCode's documented
+ * recommendation). No matcher (it is meaningless for UserPromptSubmit) and
+ * no timeout (the 60s default is ample).
+ */
+export declare function buildZcodePromptHook(): {
+    type: string;
+    command: string;
+    args: string[];
+};
+/**
+ * Write the front-load `UserPromptSubmit` hook into the GLOBAL
+ * `~/.zcode/cli/config.json` — `hooks.enabled: true` (config-file hooks
+ * are disabled by default in ZCode) plus one matcher-group under
+ * `hooks.events.UserPromptSubmit`. Idempotent: an entry of ours already
+ * present (matched by args) gets command/args rewritten in place — a node
+ * or CLI-location change self-heals on the next install — and a
+ * byte-identical file is left untouched (`unchanged`). Sibling events,
+ * sibling hooks, and every other key (`mcp`, `plugins`, `skills`, ...) are
+ * preserved. Never called for `local`: ZCode ignores workspace-level hooks
+ * in the current version.
+ */
+export declare function writeZcodePromptHookEntry(): WriteResult['files'][number];
+/**
+ * Remove the front-load `UserPromptSubmit` hook this installer may have
+ * written (see writeZcodePromptHookEntry). Used by `uninstall` and by
+ * `install` when the user opts out, so the choice round-trips. Surgical at
+ * the entry level: only args matching ours are dropped, so the user's own
+ * hooks — even in the same event/group — survive. Empty groups are pruned,
+ * then events left with no groups; `hooks.enabled` is deliberately left
+ * untouched (it may serve the user's remaining hooks), so a config whose
+ * hooks we emptied keeps `hooks: { enabled: true }`. Global file only — we
+ * never write hooks at workspace scope.
+ */
+export declare function removeZcodePromptHookEntry(): WriteResult['files'][number];
+export declare const zcodeTarget: AgentTarget;
+//# sourceMappingURL=zcode.d.ts.map

package/dist/installer/targets/zcode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zcode.d.ts","sourceRoot":"","sources":["../../../src/installer/targets/zcode.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAKH,OAAO,EACL,WAAW,EAIX,WAAW,EACZ,MAAM,SAAS,CAAC;AACjB,OAAO,EAKL,wBAAwB,EAGzB,MAAM,UAAU,CAAC;AA4BlB;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,sBAAsB,IAAI,MAAM,CAW/C;AAOD;;;;;;GAMG;AACH,OAAO,EAAE,wBAAwB,IAAI,oBAAoB,EAAE,CAAC;AAE5D;;;;;;GAMG;AACH,wBAAgB,oBAAoB,IAAI;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE,CAMxF;AAmBD;;;;;;;;;;;GAWG;AACH,wBAAgB,yBAAyB,IAAI,WAAW,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,CAgDxE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,0BAA0B,IAAI,WAAW,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,CA2CzE;AAqLD,eAAO,MAAM,WAAW,EAAE,WAA+B,CAAC"}