@reticlehq/init 3.2.0 → 3.4.0

package/dist/plan/stop-hook-step.js

@@ -0,0 +1,49 @@
+/**
+ * `init --hooks`: the print-only Claude Code Stop hook, merged into `.claude/settings.json`.
+ *
+ * Opt-in, because it writes into a file the user and other tools own. When the agent stops without a
+ * single claim having held, the hook prints one line saying so; it never blocks the agent. The line
+ * itself is `reticle report --hook`, which reads the session journal on disk.
+ */
+import { RETICLE_NPM_PACKAGE } from '../version.js';
+import { StepStatus } from './plan-types.js';
+export const CLAUDE_SETTINGS_PATH = '.claude/settings.json';
+export const STOP_HOOK_COMMAND = `npx ${RETICLE_NPM_PACKAGE} report --hook`;
+const TITLE = 'Claude Code Stop hook';
+const STOP_EVENT = 'Stop';
+const HOOK_ENTRY = { hooks: [{ type: 'command', command: STOP_HOOK_COMMAND }] };
+const isObject = (value) => 'object' === typeof value && null !== value && !Array.isArray(value);
+/** The settings as an object, or undefined when the text is not one. */
+function parseSettings(text) {
+    try {
+        const parsed = JSON.parse(text);
+        return isObject(parsed) ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function stopHookStep(path, existing) {
+    const settings = null === existing || undefined === existing ? {} : parseSettings(existing);
+    if (settings === undefined) {
+        return {
+            title: TITLE,
+            target: path,
+            status: StepStatus.MANUAL,
+            detail: `${CLAUDE_SETTINGS_PATH} is not a JSON object, so it was left alone. Add a Stop hook running \`${STOP_HOOK_COMMAND}\``,
+        };
+    }
+    const hooks = isObject(settings['hooks']) ? settings['hooks'] : {};
+    const stop = Array.isArray(hooks[STOP_EVENT]) ? hooks[STOP_EVENT] : [];
+    if (JSON.stringify(stop).includes(STOP_HOOK_COMMAND)) {
+        return { title: TITLE, target: path, status: StepStatus.ALREADY, detail: 'hook already installed' };
+    }
+    const merged = { ...settings, hooks: { ...hooks, [STOP_EVENT]: [...stop, HOOK_ENTRY] } };
+    return {
+        title: TITLE,
+        target: path,
+        status: StepStatus.APPLY,
+        detail: 'print one line when the agent stops without a claim that held; never blocks it',
+        write: { path, content: `${JSON.stringify(merged, null, 2)}\n`, expect: [STOP_HOOK_COMMAND] },
+    };
+}

package/dist/project/agent-rules.js

@@ -19,6 +19,7 @@
  */
 import { NPX } from '../register/mcp.js';
 import { RETICLE_NPM_PACKAGE } from '../version.js';
+import { DISCOVERY_CALL_URL, DISCOVERY_EMAIL_COMMAND } from '@reticlehq/core';
 /** Project-root instruction files the agent re-reads every session. */
 export const CLAUDE_MD_PATH = 'CLAUDE.md';
 export const AGENTS_MD_PATH = 'AGENTS.md';
@@ -206,6 +207,7 @@ Finish that file when you see it. It is what lets you check what the app BELIEVE
 - **Working around a Reticle defect in silence is the one thing not to do.** A silent workaround is how the same defect survives to the next user.
 - **Report defects in *Reticle*, not in the app under test.** A bug you find in this app is Reticle working as intended; that one belongs in your report to the user.
 - **Never include app source, secrets, user data, or customer records** in a report.
+- **When the person you work with is stuck, or Reticle got in their way, offer them a call with the founder** (${DISCOVERY_CALL_URL}) or leaving an email with \`${DISCOVERY_EMAIL_COMMAND}\`. That conversation is where Reticle's direction comes from. Offer it; never book a call or submit an email for them.
 
 ## More
 

package/dist/register/mcp-clients.d.ts

@@ -37,6 +37,19 @@ export interface ClientSpec {
     /** Where the shape came from, so the next person can re-check it rather than trust this file. */
     docs: string;
 }
+/**
+ * Claude Code's project-scope MCP config, which needs no CLI on PATH.
+ *
+ * Named here beside the client specs because it IS one of Claude Code's two config routes, and a
+ * free string for it is the reason nobody noticed the other route existed when the CLI one failed.
+ */
+export declare const CLAUDE_PROJECT_CONFIG = ".mcp.json";
+/**
+ * Claude Code's project-scope registration, as a client spec so it goes through the same merge
+ * (already / manual / apply) as every other client. Not in `MCP_CLIENTS`: that list is DETECTED by
+ * its config existing, and this one is only ever written from inside Claude Code (see plan.ts).
+ */
+export declare const CLAUDE_PROJECT_SPEC: ClientSpec;
 export declare const MCP_CLIENTS: readonly ClientSpec[];
 export declare function clientSpec(id: McpClient): ClientSpec;
 export declare const ClientMergeStatus: {

package/dist/register/mcp-clients.js

@@ -53,6 +53,28 @@ function commandArgsEntry() {
 function openCodeEntry() {
     return { type: 'local', command: [NPX, ...npxServerArgs()], enabled: true };
 }
+/**
+ * Claude Code's project-scope MCP config, which needs no CLI on PATH.
+ *
+ * Named here beside the client specs because it IS one of Claude Code's two config routes, and a
+ * free string for it is the reason nobody noticed the other route existed when the CLI one failed.
+ */
+export const CLAUDE_PROJECT_CONFIG = '.mcp.json';
+/**
+ * Claude Code's project-scope registration, as a client spec so it goes through the same merge
+ * (already / manual / apply) as every other client. Not in `MCP_CLIENTS`: that list is DETECTED by
+ * its config existing, and this one is only ever written from inside Claude Code (see plan.ts).
+ */
+export const CLAUDE_PROJECT_SPEC = {
+    id: McpClient.CLAUDE_CODE,
+    label: 'Claude Code, project',
+    scope: ConfigScope.PROJECT,
+    relPath: CLAUDE_PROJECT_CONFIG,
+    format: ConfigFormat.JSON,
+    serversKey: 'mcpServers',
+    entry: commandArgsEntry,
+    docs: 'https://docs.claude.com/en/docs/claude-code/mcp: project scope, .mcp.json at the project root',
+};
 export const MCP_CLIENTS = [
     {
         id: McpClient.CLAUDE_CODE,

package/dist/register/mcp.d.ts

@@ -66,11 +66,24 @@ interface ClaudeAddCommand {
 }
 /** `claude mcp add reticle -s user -- npx @reticlehq/server mcp` — registers globally for all projects (portless). */
 export declare function claudeAddCommand(): ClaudeAddCommand;
-/** Probe args that tell us whether an `reticle` server already exists in any scope (exit 0 = exists). */
-export declare function claudeExistsProbe(): {
-    command: string;
-    args: string[];
-};
+/**
+ * Is a `reticle` server already registered with Claude Code, in any scope this project sees?
+ *
+ * READ FROM CLAUDE'S OWN CONFIG, never asked of the CLI. `claude mcp get reticle` health-checks the
+ * entry by LAUNCHING it — `npx @reticlehq/server mcp` in the project — which starts a daemon on
+ * whatever `.reticle.json` says before `init` has rewritten it. A re-run moving the port brought the
+ * old-port daemon back about two seconds after it was stopped. `claude mcp list` health-checks
+ * every server the same way.
+ *
+ * The three scopes `claude mcp add` writes: user (`mcpServers` at the top of the state file), local
+ * (`projects[<dir>].mcpServers`, keyed by absolute path) and project (`<dir>/.mcp.json`). Without a
+ * project directory only user scope is looked at. An unreadable file answers "not registered",
+ * which costs at worst a `claude mcp add` that reports the entry already exists.
+ */
+export declare function claudeHasReticle(io: {
+    readFile(path: string): string | null;
+    homeDir(): string;
+}, projectDir: string | undefined, configDir?: string | undefined): boolean;
 /** Probe args for whether the `claude` CLI is installed at all. */
 export declare function claudeAvailableProbe(): {
     command: string;
@@ -83,4 +96,12 @@ export declare function claudeAvailableProbe(): {
  */
 export declare function mcpWindowsNote(): string;
 /** Printed when the `claude` CLI isn't available — register Reticle globally once, by hand. */
+/**
+ * Claude Code's PROJECT-scope config, which needs no CLI on PATH.
+ *
+ * The remedy a reporter had to work out for themselves: inside a Claude Code VS Code extension
+ * session the `claude` binary is not on PATH, so every CLI-based route is shut and `.mcp.json` in
+ * the project root is the one that still works.
+ */
+export declare function claudeProjectMcpJson(): string;
 export declare function mcpManual(): string;

package/dist/register/mcp.js

@@ -11,11 +11,13 @@
  * project's `.reticle.json` in its CWD (see cli-port.ts). The port belongs to the project, not the
  * global agent config.
  */
+import { join } from 'node:path';
 import { RETICLE_NPM_PACKAGE } from '../version.js';
 // The name is a wire identity and lives in the contract; re-exported here so the registration writers
 // below (and their tests) keep reading it from the module that USES it.
 export { MCP_SERVER_NAME } from '@reticlehq/core';
 import { MCP_SERVER_NAME } from '@reticlehq/core';
+import { CLAUDE_PROJECT_CONFIG } from './mcp-clients.js';
 /**
  * The registered command is STILL bare `npx` on every platform, deliberately.
  *
@@ -86,14 +88,53 @@ export function claudeAddCommand() {
     const args = [MCP_SUBCOMMAND, 'add', MCP_SERVER_NAME, '-s', 'user', '--', ...tail];
     return { command: CLAUDE_CLI, args, display: `${CLAUDE_CLI} ${args.join(' ')}` };
 }
-/** Probe args that tell us whether an `reticle` server already exists in any scope (exit 0 = exists). */
-export function claudeExistsProbe() {
-    // NO `-s`: `claude mcp get` takes no options at all, so passing one exits 1 with "unknown option
-    // '-s'" — the probe answered "not registered" on EVERY machine, init then ran `claude mcp add`,
-    // which exits 1 with "already exists", and a re-run reported `[⚠] step failed` plus a manual
-    // command that fails the same way. A false positive from a project-scoped entry costs one skipped
-    // registration; the flag cost every re-run a failed step.
-    return { command: CLAUDE_CLI, args: [MCP_SUBCOMMAND, 'get', MCP_SERVER_NAME] };
+/** Where Claude Code keeps its state: `$CLAUDE_CONFIG_DIR/.claude.json`, else `~/.claude.json`. */
+const CLAUDE_STATE_FILE = '.claude.json';
+/** `mcpServers` holds a `reticle` entry. */
+function namesReticle(scope) {
+    if ('object' !== typeof scope || null === scope)
+        return false;
+    const servers = scope.mcpServers;
+    return 'object' === typeof servers && null !== servers && MCP_SERVER_NAME in servers;
+}
+function parsed(source) {
+    if (null === source)
+        return undefined;
+    try {
+        return JSON.parse(source);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Is a `reticle` server already registered with Claude Code, in any scope this project sees?
+ *
+ * READ FROM CLAUDE'S OWN CONFIG, never asked of the CLI. `claude mcp get reticle` health-checks the
+ * entry by LAUNCHING it — `npx @reticlehq/server mcp` in the project — which starts a daemon on
+ * whatever `.reticle.json` says before `init` has rewritten it. A re-run moving the port brought the
+ * old-port daemon back about two seconds after it was stopped. `claude mcp list` health-checks
+ * every server the same way.
+ *
+ * The three scopes `claude mcp add` writes: user (`mcpServers` at the top of the state file), local
+ * (`projects[<dir>].mcpServers`, keyed by absolute path) and project (`<dir>/.mcp.json`). Without a
+ * project directory only user scope is looked at. An unreadable file answers "not registered",
+ * which costs at worst a `claude mcp add` that reports the entry already exists.
+ */
+export function claudeHasReticle(io, projectDir, configDir = process.env['CLAUDE_CONFIG_DIR']) {
+    const state = parsed(io.readFile(join(configDir ?? io.homeDir(), CLAUDE_STATE_FILE)));
+    if (namesReticle(state))
+        return true;
+    if (projectDir === undefined)
+        return false;
+    const projects = 'object' === typeof state && null !== state
+        ? state.projects
+        : undefined;
+    if ('object' === typeof projects && null !== projects) {
+        if (namesReticle(projects[projectDir]))
+            return true;
+    }
+    return namesReticle(parsed(io.readFile(join(projectDir, CLAUDE_PROJECT_CONFIG))));
 }
 /** Probe args for whether the `claude` CLI is installed at all. */
 export function claudeAvailableProbe() {
@@ -112,12 +153,27 @@ does not gate:
   "${MCP_SERVER_NAME}": { "command": "${WINDOWS_SHELL}", "args": ${JSON.stringify([WINDOWS_SHELL_C, NPX, ...serverInvocation().slice(1)])} }`;
 }
 /** Printed when the `claude` CLI isn't available — register Reticle globally once, by hand. */
+/**
+ * Claude Code's PROJECT-scope config, which needs no CLI on PATH.
+ *
+ * The remedy a reporter had to work out for themselves: inside a Claude Code VS Code extension
+ * session the `claude` binary is not on PATH, so every CLI-based route is shut and `.mcp.json` in
+ * the project root is the one that still works.
+ */
+export function claudeProjectMcpJson() {
+    const [command, ...args] = serverInvocation();
+    return `${CLAUDE_PROJECT_CONFIG} (project root):
+
+  { "mcpServers": { "${MCP_SERVER_NAME}": { "command": "${command ?? NPX}", "args": ${JSON.stringify(args)} } } }`;
+}
 export function mcpManual() {
     const tail = serverInvocation().join(' ');
     return `Register the Reticle MCP server ONCE, globally (so every project gets it):
 
   ${CLAUDE_CLI} ${MCP_SUBCOMMAND} add ${MCP_SERVER_NAME} -s user -- ${tail}
 
+Or, in Claude Code with no \`claude\` on PATH (a VS Code extension session), write ${claudeProjectMcpJson()}
+
 Or, for another agent, add this to its global MCP config (e.g. Cursor's ~/.cursor/mcp.json):
 
   "${MCP_SERVER_NAME}": { "command": "${NPX}", "args": ${JSON.stringify(serverInvocation().slice(1))} }

package/dist/run-types.d.ts

@@ -10,6 +10,8 @@ import type { InitOutcome } from '@reticlehq/core/telemetry';
 export interface InitOptions {
     /** `--capture-bodies`: write `captureNetworkBodies: true` into the app's config. Off by default (#705). */
     captureBodies?: boolean | undefined;
+    /** `--hooks`: also install the print-only Claude Code Stop hook. Off by default. */
+    hooks?: boolean | undefined;
     cwd: string;
     port: number | undefined;
     mcp: boolean;
@@ -76,6 +78,14 @@ export interface InitIo {
     scoped(relPath: string): InitIo;
     /** Runs a subprocess to completion (inherits stdio); returns true on exit code 0. */
     exec(command: string, args: readonly string[]): boolean;
+    /**
+     * Runs a subprocess quietly and returns its combined output — for a failure whose text names its
+     * cause (see explainInstallFailure). Optional: without it the generic failure text stands.
+     */
+    capture?(command: string, args: readonly string[]): {
+        ok: boolean;
+        output: string;
+    };
     /** Runs a subprocess quietly (no stdio) for a yes/no check; returns true on exit code 0. */
     probe(command: string, args: readonly string[]): boolean;
     /** Can this process write into the project root — see preflight.ts. */