@reticlehq/server 2.11.0 → 2.13.0

package/dist/init/refresh-rules.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Bring an already-installed project's agent rules up to the version that is running.
+ *
+ * `mergeMarkedInstruction` has always been able to do this: the managed block is marker-delimited,
+ * idempotence is decided by comparing CONTENT rather than by seeing a marker, and everything
+ * outside the markers is left exactly as the human wrote it. What was missing is anything that
+ * CALLS it after the first install.
+ *
+ * It is reachable only from `buildPlan`, so the rules refresh when somebody re-runs `init` and
+ * never otherwise. A project set up on an older release keeps that release's instructions forever,
+ * which means every improvement to them — what to do when a capabilities file registers nothing,
+ * that an install is not finished until a verdict exists, that intent is captured while building —
+ * reaches new projects only.
+ *
+ * That is the wrong way round. The people who most need better instructions are the ones already
+ * installed and not getting value, and `reticle update` is the moment they are already touching the
+ * install.
+ */
+/** The instruction files the managed block lives in. Cursor's rule file is regenerated whole. */
+export declare const RULE_FILES: readonly ["CLAUDE.md", "AGENTS.md"];
+export interface RuleFileIo {
+    read: (path: string) => string | null;
+    write: (path: string, content: string) => void;
+}
+export interface RefreshResult {
+    /** Files whose managed block was replaced with the current one. */
+    updated: string[];
+    /** Files that were already current, or that carry no Reticle block to update. */
+    unchanged: string[];
+}
+/**
+ * Refresh every instruction file that already carries a Reticle block.
+ *
+ * Deliberately does NOT create one where none exists. A project with no Reticle block in its
+ * CLAUDE.md either never ran `init` here or had the block removed on purpose, and `update` is not
+ * the place to make that decision for somebody — it is a version command, and quietly writing
+ * instructions into a file a user curates would be a surprise.
+ */
+export declare function refreshAgentRules(cwd: string, io: RuleFileIo): RefreshResult;

package/dist/init/refresh-rules.js

@@ -0,0 +1,51 @@
+/**
+ * Bring an already-installed project's agent rules up to the version that is running.
+ *
+ * `mergeMarkedInstruction` has always been able to do this: the managed block is marker-delimited,
+ * idempotence is decided by comparing CONTENT rather than by seeing a marker, and everything
+ * outside the markers is left exactly as the human wrote it. What was missing is anything that
+ * CALLS it after the first install.
+ *
+ * It is reachable only from `buildPlan`, so the rules refresh when somebody re-runs `init` and
+ * never otherwise. A project set up on an older release keeps that release's instructions forever,
+ * which means every improvement to them — what to do when a capabilities file registers nothing,
+ * that an install is not finished until a verdict exists, that intent is captured while building —
+ * reaches new projects only.
+ *
+ * That is the wrong way round. The people who most need better instructions are the ones already
+ * installed and not getting value, and `reticle update` is the moment they are already touching the
+ * install.
+ */
+import { join } from 'node:path';
+import { mergeMarkedInstruction, AgentRuleStatus, hasManagedBlock } from './agent-rules.js';
+/** The instruction files the managed block lives in. Cursor's rule file is regenerated whole. */
+export const RULE_FILES = ['CLAUDE.md', 'AGENTS.md'];
+/**
+ * Refresh every instruction file that already carries a Reticle block.
+ *
+ * Deliberately does NOT create one where none exists. A project with no Reticle block in its
+ * CLAUDE.md either never ran `init` here or had the block removed on purpose, and `update` is not
+ * the place to make that decision for somebody — it is a version command, and quietly writing
+ * instructions into a file a user curates would be a surprise.
+ */
+export function refreshAgentRules(cwd, io) {
+    const updated = [];
+    const unchanged = [];
+    for (const name of RULE_FILES) {
+        const path = join(cwd, name);
+        const existing = io.read(path);
+        if (null === existing || !hasManagedBlock(existing)) {
+            unchanged.push(name);
+            continue;
+        }
+        const result = mergeMarkedInstruction(existing);
+        if (AgentRuleStatus.APPLY === result.status && result.content !== existing) {
+            io.write(path, result.content);
+            updated.push(name);
+        }
+        else {
+            unchanged.push(name);
+        }
+    }
+    return { updated, unchanged };
+}

package/dist/init/run.d.ts

@@ -3,8 +3,6 @@
  * plan (pure), optionally write the apply-steps, and print a human-readable report. All filesystem
  * access goes through `InitIo` so the orchestration is unit-testable with an in-memory IO.
  */
-import { Framework } from './detect.js';
-import { StepStatus } from './plan.js';
 import type { InitOutcome } from '@reticlehq/core';
 /**
  * Resolve the lockfiles set used to pick the package manager. A lockfile in the project root wins;
@@ -20,6 +18,8 @@ import type { InitOutcome } from '@reticlehq/core';
  */
 export declare function resolveLockfiles(rootFiles: ReadonlySet<string>, cwd: string, io: Pick<InitIo, 'exists'>, nodeModulesMarkers?: ReadonlySet<string>): Set<string>;
 export interface InitOptions {
+    /** `--capture-bodies`: write `captureNetworkBodies: true` into the app's config. Off by default (#705). */
+    captureBodies?: boolean | undefined;
     cwd: string;
     port: number | undefined;
     mcp: boolean;
@@ -49,6 +49,13 @@ export interface InitOptions {
      * today's fire-and-forget behaviour, so no path loses its event by forgetting to report.
      */
     deferOutcome?: boolean;
+    /**
+     * Whether the caller carries on into booting the app and driving it.
+     *
+     * Only affects the closing hint, which otherwise tells the reader to restart their dev server and
+     * drive a flow by hand — three lines before this command does both.
+     */
+    continuesToRuntime?: boolean;
 }
 export interface InitIo {
     /** Returns file content or null if it does not exist. Path is project-relative or absolute. */
@@ -72,49 +79,39 @@ export interface InitIo {
     exec(command: string, args: readonly string[]): boolean;
     /** 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. */
+    canWrite(): boolean;
     print(line: string): void;
 }
+/**
+ * What a run established, for a caller that means to continue where init stopped.
+ *
+ * Everything here was already computed and then thrown away. That was fine while init only wrote
+ * files: nobody downstream existed. A caller that goes on to boot the app needs the same answers,
+ * and re-deriving them is how two parts of one command end up disagreeing about which directory
+ * they are in — which is not hypothetical, because a monorepo redirect re-enters `runInit` with a
+ * different cwd and the outer caller never learns that it happened.
+ */
+export interface InitContext {
+    /** The directory actually wired, AFTER any monorepo redirect. */
+    readonly appDir: string;
+    readonly framework: string;
+    readonly packageManager: string;
+    /** The project's own dev command, when its scripts name one. Never composed. */
+    readonly devCommand?: string | undefined;
+    /** Set when init redirected into a workspace app, naming the one it chose. */
+    readonly redirectedTo?: string | undefined;
+}
 export interface InitResult {
     ok: boolean;
     applied: number;
     manual: number;
+    /** What this run established. Absent only where init exits before establishing anything. */
+    context?: InitContext;
     /**
      * The event body this run would report, handed to the caller instead of emitted, when
      * `deferOutcome` is set. Absent on a dry run and on the exits that report for themselves.
      */
     outcome?: InitOutcome;
 }
-/**
- * App directories under a workspace root.
- *
- * Running `reticle init` at the repo root is what people actually do, and in a monorepo the app is a
- * directory down — so init detected "no framework", printed a wall of manual HTML instructions, and
- * would have installed the SDK into the ROOT package.json. It already walks UP for the lockfile, so
- * it knows it is in a workspace; this is the matching walk DOWN.
- */
-export declare function findWorkspaceApps(io: Pick<InitIo, 'exists' | 'readFile' | 'listDirs'>): string[];
-/**
- * The standing ask, printed at the end of every `init`.
- *
- * Addressed to the agent as much as the human: whichever of them just ran this command is the one
- * holding the experience, and neither has a Reticle tool surface to file through at this point.
- *
- * Printed by the `runInit` wrapper, NOT by `report()` — see the comment there for why, and for how
- * the workspace redirect is kept from asking twice.
- */
-export declare const FEEDBACK_HINT: string;
-/**
- * The last two lines a user reads, and the order matters.
- *
- * This used to say only "Restart <dev server>, then ask your agent: List Reticle sessions" — and
- * asking the agent was the one thing that could not work yet. `init` registers the MCP server, but
- * an agent client reads its tool list when it STARTS and never re-reads it, so the session that
- * just ran `init` has no `reticle_*` tools however clean the install was. The user follows the
- * instruction, the agent answers "unknown tool", and the obvious conclusion is that the install
- * failed.
- *
- * So the reload is named FIRST, before the sentence that depends on it. Omitted entirely when this
- * run did not register MCP (`--no-mcp`), where it would be advice about something we did not do.
- */
-export declare function restartHint(framework: Framework, mcpStatus: StepStatus | undefined): string;
 export declare function runInit(options: InitOptions, io: InitIo): InitResult;