@reticlehq/init 3.6.0 → 3.7.0

package/dist/project/agent-rules.js

@@ -118,13 +118,21 @@ This app is instrumented by **Reticle**, an in-app verification layer exposed as
 
 **Do not reach for Reticle when the change cannot show up in the running app.** It costs tool calls and the user's patience, and a verdict over an unrelated flow proves nothing about what you changed. Skip it for: documentation, comments, tests, build config, CI, dependency bumps with no user-facing effect, backend or CLI work with no UI surface, and any change to a project that is not a running web app. Say in one line that you skipped verification and why, rather than silently not doing it.
 
-**How to verify:**
-
-- Drive the flow with \`reticle_act_and_wait({ ref, action, until })\`. It names the consequence you expect BEFORE the action, which is the difference between a check and a rationalisation.
-- Batch a multi-step journey (a login, a form) into one \`reticle_act { steps: [...] }\` rather than one round trip per field.
-- Read the surrounding evidence with \`reticle_look { action: "page" | "state" }\` and \`reticle_observe { action: "network" | "console" }\`.
-- **Only \`reticle_act_and_wait\` and \`reticle_assert\` produce a verdict.** \`reticle_act\` and everything else move or read the app and prove nothing, so a session ending without one of those two has no result however many tools it used.
-- Covered flows: \`${CLI} gate\` reports which recorded flows the changed files affect and whether they still pass.
+**How to verify — the rules to keep in mind on every call:**
+
+1. **Only \`verified: "yes"\` is a pass.** \`"no-fault"\` (nothing was declared — you omitted \`until\`) and \`"unknown"\` (Reticle could not tell; \`verifiedReason\` says why) are not a pass: report them as not proved, never as working.
+2. **Name the consequence BEFORE acting:** \`reticle_act_and_wait({ target, action, until })\` (add \`durable: true\` if it must survive a reload). Only it, \`reticle_assert\` and \`reticle_act { steps }\` produce a verdict; everything else proves nothing.
+3. **A journey is one call:** \`reticle_act { steps: [{ target, action, expect }] }\` runs every step and stops at the first \`expect\` that fails. The last step's \`expect\` is the end state you were asked to deliver.
+4. **Text checks are exact-case.** Add \`ignoreCase: true\` only when case truly does not matter.
+5. **Target by \`{ testid }\` or \`{ role, name }\`.** An ambiguous target is refused, never guessed.
+6. **On a failure, read \`expected\` / \`observed\` / the nearest candidates before retrying.** Never weaken a check to make it green.
+7. **Open \`screenshot.path\` only when the look matters;** \`reticle_observe { since }\` has the rest.
+8. **Predicates:** \`{ kind: "signal", name }\` · \`{ kind: "net", method, urlContains, status }\` · \`{ kind: "route", pathname }\` · \`{ kind: "state", path, equals }\` · \`{ kind: "element", query: { role, name } }\` · \`{ kind: "text", contains }\` · \`allOf\` / \`anyOf\` / \`not\`.
+9. **No session?** \`reticle_session { action: "list" }\` and do its \`next_action\`. **No app connected at all?** Run \`${CLI} init\` in the app's own folder yourself. **A version-skew warning?** \`${CLI} stop\`, then retry.
+10. **End with the Reticle result block the server gives you**, verbatim.
+11. **If your context was compacted or you lost track, run \`${CLI} context --compact\` first.** It is the daemon's own record of what was proved, what failed and what is still owed.
+
+Covered flows: \`${CLI} gate\` reports which recorded flows the changed files affect and whether they still pass.
 
 **Setting Reticle up? You are mid-sequence — do not stop until a verdict exists.** The whole of it
 is: instrument the app → get a dev server running → open the app in a browser → drive one flow →
@@ -136,7 +144,7 @@ carries the recovery ladder; never report the install as finished without a verd
 
 ${DEV_SERVER_POLICY}
 
-A dev server that is already running does not pick up an edited build config or a newly created plugin file — restart it and hard-reload the tab. And if a server IS listening and still nothing connects, the cause is the SDK not loading in the page, not a missing dev server; do not tell the user to start one they are already running.
+If a server IS listening and still nothing connects, the cause is the SDK not loading in the page, not a missing dev server; do not tell the user to start one they are already running.
 
 **Finish \`src/reticle-dev.ts\` before you claim setup is done.** \`init\` writes it and cannot always fill it in: a store that needs an argument only reading the code supplies (Jotai atoms, an XState actor, a TanStack \`queryClient\`) is left as a commented \`registerStore\` line. A file that registers nothing looks exactly like a finished one, and \`reticle_look { action: "state" }\` then returns empty forever — which is indistinguishable from an app that has nothing to report, so it reads as success. Uncomment the line, complete it, and prove it by driving one flow and seeing your keys come back. If \`init\` told you to restart your client, this is the job waiting for you on the other side of that restart.
 
@@ -146,9 +154,6 @@ A dev server that is already running does not pick up an edited build config or
 
 **Honesty, which is the whole point:**
 
-- **\`verified: "unknown"\` is not a pass.** It means Reticle drove the app and could not tell what happened; \`verifiedReason\` says which clause decided that. Report it as unknown, never as working.
-- **\`verified: "no-fault"\` is not a pass either.** It means nothing was DECLARED to prove: the page settled and no channel complained, but you asserted nothing, so there is no verification. You get it whenever \`until\` is omitted. Name a consequence the action changes — a signal, a request, a route, or store state — and call again.
-- **Never weaken a check to make it green.** Downgrading, skipping or deleting an assertion is a finding, not a fix.
 - **If Reticle cannot run** (no daemon, or this is not a running web app), say so. Do not skip verification silently.
 - **Setup is not finished until one real flow has been driven and produced a verdict.** \`init\` exiting 0, the tools appearing, and a session being listed are all things that happen before anything has been verified.
 

package/dist/register/codex-toml.d.ts

@@ -8,3 +8,15 @@
 export declare function codexServerTokens(existing: string | null, serversKey: string): string[];
 /** Does this config already declare a Reticle server under our name? */
 export declare function codexDeclaresOurServer(existing: string | null, serversKey: string): boolean;
+/**
+ * Does this config NAME a Reticle server at all, in any shape?
+ *
+ * Wider than {@link codexDeclaresOurServer}, which asks whether the entry holds a command we can
+ * read. A `url` entry, one that only has an `env` table, or an inline `mcp_servers = { … }` has no
+ * command and args, so it reads as absent there. `codex mcp add reticle` REPLACES such an entry
+ * without a word and exits 0, so anything that registers through that command has to ask this.
+ *
+ * Structural rather than a substring match: a project called `reticle`, under
+ * `[projects."/home/u/reticle"]`, does not name a server.
+ */
+export declare function codexNamesOurServer(existing: string | null, serversKey: string): boolean;

package/dist/register/codex-toml.js

@@ -142,3 +142,47 @@ export function codexServerTokens(existing, serversKey) {
 export function codexDeclaresOurServer(existing, serversKey) {
     return 0 < codexServerTokens(existing, serversKey).length;
 }
+/**
+ * Our key, as a KEY, inside an inline table's text: `reticle = …`, `"reticle" = …`, or the dotted
+ * `reticle.command = …`. A key follows the `{` or a `,`, and its quotes match, so a value that merely
+ * starts with the name (`command = "reticle.js"`) is not one.
+ */
+const OUR_KEY_INLINE = new RegExp(`(?:^|[{,])\\s*(?:${MCP_SERVER_NAME}|"${MCP_SERVER_NAME}"|'${MCP_SERVER_NAME}')\\s*[.=]`);
+/**
+ * Does this config NAME a Reticle server at all, in any shape?
+ *
+ * Wider than {@link codexDeclaresOurServer}, which asks whether the entry holds a command we can
+ * read. A `url` entry, one that only has an `env` table, or an inline `mcp_servers = { … }` has no
+ * command and args, so it reads as absent there. `codex mcp add reticle` REPLACES such an entry
+ * without a word and exits 0, so anything that registers through that command has to ask this.
+ *
+ * Structural rather than a substring match: a project called `reticle`, under
+ * `[projects."/home/u/reticle"]`, does not name a server.
+ */
+export function codexNamesOurServer(existing, serversKey) {
+    if (null === existing)
+        return false;
+    const want = ourTablePath(serversKey);
+    const isOurs = (path) => want.every((segment, i) => path[i] === segment);
+    let table = [];
+    for (const rawLine of existing.split(/\r?\n/)) {
+        const line = withoutComment(rawLine).trim();
+        const header = /^\[{1,2}([^\]]+)\]{1,2}$/.exec(line);
+        if (null !== header) {
+            table = keyPath(header[1] ?? '');
+            if (isOurs(table))
+                return true;
+            continue;
+        }
+        const assignment = /^([^=]+)=(.*)$/.exec(line);
+        if (null === assignment)
+            continue;
+        const path = [...table, ...keyPath(assignment[1] ?? '')];
+        if (isOurs(path))
+            return true;
+        // `mcp_servers = { reticle = { … } }`: the whole table is one inline value, our key inside it.
+        if (samePath(path, [serversKey]) && OUR_KEY_INLINE.test(assignment[2] ?? ''))
+            return true;
+    }
+    return false;
+}

package/dist/register/mcp.d.ts

@@ -58,14 +58,14 @@ export declare function npxServerArgs(): string[];
  * @param tokens every string in the entry's command + args, in any of the client shapes.
  */
 export declare function isReticleRegistration(tokens: readonly string[]): boolean;
-interface ClaudeAddCommand {
+interface CliAddCommand {
     command: string;
     args: string[];
     /** Human-readable form of the same command, for reports and manual fallback. */
     display: string;
 }
 /** `claude mcp add reticle -s user -- npx @reticlehq/server mcp` — registers globally for all projects (portless). */
-export declare function claudeAddCommand(): ClaudeAddCommand;
+export declare function claudeAddCommand(): CliAddCommand;
 /**
  * Is a `reticle` server already registered with Claude Code, in any scope this project sees?
  *
@@ -89,6 +89,19 @@ export declare function claudeAvailableProbe(): {
     command: string;
     args: string[];
 };
+/**
+ * `codex mcp add reticle -- npx @reticlehq/server mcp` — Codex keeps the entry in its own
+ * `~/.codex/config.toml`, shared by the desktop app and the CLI, so one registration covers both.
+ *
+ * It REPLACES an existing entry of the same name and still exits 0, so callers run it only when the
+ * config names no `reticle` server at all (see `codexNamesOurServer`).
+ */
+export declare function codexAddCommand(): CliAddCommand;
+/** Probe args for whether the `codex` CLI is installed at all. */
+export declare function codexAvailableProbe(): {
+    command: string;
+    args: string[];
+};
 /**
  * The Windows `cmd /c npx` registration. Printed on every Windows init, not only when the `claude`
  * CLI is missing — a successful `claude mcp add` of bare `npx` is exactly the failure that reported

package/dist/register/mcp.js

@@ -36,6 +36,7 @@ export const NPX = 'npx';
 const RETICLE_PACKAGE = RETICLE_NPM_PACKAGE;
 const MCP_SUBCOMMAND = 'mcp';
 const CLAUDE_CLI = 'claude';
+const CODEX_CLI = 'codex';
 /** Windows `cmd /c` — the spawn that PowerShell's execution policy does not gate. */
 const WINDOWS_SHELL = 'cmd';
 const WINDOWS_SHELL_C = '/c';
@@ -140,6 +141,21 @@ export function claudeHasReticle(io, projectDir, configDir = process.env['CLAUDE
 export function claudeAvailableProbe() {
     return { command: CLAUDE_CLI, args: ['--version'] };
 }
+/**
+ * `codex mcp add reticle -- npx @reticlehq/server mcp` — Codex keeps the entry in its own
+ * `~/.codex/config.toml`, shared by the desktop app and the CLI, so one registration covers both.
+ *
+ * It REPLACES an existing entry of the same name and still exits 0, so callers run it only when the
+ * config names no `reticle` server at all (see `codexNamesOurServer`).
+ */
+export function codexAddCommand() {
+    const args = [MCP_SUBCOMMAND, 'add', MCP_SERVER_NAME, '--', ...serverInvocation()];
+    return { command: CODEX_CLI, args, display: `${CODEX_CLI} ${args.join(' ')}` };
+}
+/** Probe args for whether the `codex` CLI is installed at all. */
+export function codexAvailableProbe() {
+    return { command: CODEX_CLI, args: ['--version'] };
+}
 /**
  * The Windows `cmd /c npx` registration. Printed on every Windows init, not only when the `claude`
  * CLI is missing — a successful `claude mcp add` of bare `npx` is exactly the failure that reported

package/dist/run-types.d.ts

@@ -41,6 +41,8 @@ export interface InitOptions {
      * at `src/admin` ended up with no `/reticle` at all (#318).
      */
     agentRoot?: string;
+    /** The agent root is a workspace with several apps: it is pinned to none of them. */
+    severalApps?: boolean;
     /**
      * Hand the telemetry outcome back rather than emitting it here.
      *
@@ -74,6 +76,8 @@ export interface InitIo {
     listDirs(relPath: string): readonly string[];
     /** File (non-directory) basenames inside a project-relative directory, including dotfiles. */
     listFiles(relPath: string): readonly string[];
+    /** Whether a project-relative path is a symbolic link. Optional: an IO without it reads none. */
+    isSymlink?(relPath: string): boolean;
     /** The same IO re-rooted at a project-relative subdirectory (used for the workspace redirect). */
     scoped(relPath: string): InitIo;
     /** Runs a subprocess to completion (inherits stdio); returns true on exit code 0. */
@@ -138,4 +142,6 @@ export interface InitResult {
      * `deferOutcome` is set. Absent on a dry run and on the exits that report for themselves.
      */
     outcome?: InitOutcome;
+    /** No app where init ran; it listed the apps below instead. Reported as `no_package_json`. */
+    listedAppsBelow?: true;
 }

package/dist/run.d.ts

@@ -1,5 +1,5 @@
 import type { InitOptions, InitIo, InitResult } from './run-types.js';
-export type { InitOptions, InitIo, InitResult } from './run-types.js';
 import { resolveLockfiles } from './detect/lockfiles.js';
+export type { InitOptions, InitIo, InitResult } from './run-types.js';
 export { resolveLockfiles };
 export declare function runInit(options: InitOptions, io: InitIo): InitResult;