@reticlehq/init 2.14.0

package/dist/preflight.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The two conditions that make every later phase fail, checked before anything is written.
+ *
+ * Both lived in setup/reticle.mjs and neither survived the port into `init`. What they buy is the
+ * distance between a failure and its cause: without them, an unwritable checkout arrives as EACCES
+ * in a stack trace at phase four, and a missing package manager arrives as `spawn pnpm ENOENT`
+ * inside "the dev server exited" — which sends the reader into their own dev script hunting a bug
+ * that is not there.
+ */
+/** The parts of the environment preflight reads, so the rules are testable without a filesystem. */
+export interface PreflightIo {
+    /** Absolute path of the directory init is running in. */
+    cwd(): string;
+    /** Can this process write into the project root. */
+    canWrite(): boolean;
+    /** Runs a command quietly for a yes/no check; true on exit code 0. */
+    probe(command: string, args: readonly string[]): boolean;
+}
+/**
+ * The refusal to print, or undefined when this machine can run the install.
+ *
+ * `packageManager` is the one init RESOLVED, never a raw lockfile check. An inherited
+ * `pnpm-lock.yaml` at a monorepo root does not mean the app in `frontend/` uses pnpm — that app's own
+ * installed tree outranks an ancestor lockfile, and detect.ts already works this out. Re-deriving it
+ * here from `exists('pnpm-lock.yaml')` refused an npm app sitting under a pnpm monorepo on a machine
+ * with no pnpm, which the install gate proves must succeed.
+ */
+export declare function preflightRefusal(io: PreflightIo, packageManager: string, options?: {
+    alreadyServed?: boolean;
+}): string | undefined;

package/dist/preflight.js

@@ -0,0 +1,52 @@
+/**
+ * The two conditions that make every later phase fail, checked before anything is written.
+ *
+ * Both lived in setup/reticle.mjs and neither survived the port into `init`. What they buy is the
+ * distance between a failure and its cause: without them, an unwritable checkout arrives as EACCES
+ * in a stack trace at phase four, and a missing package manager arrives as `spawn pnpm ENOENT`
+ * inside "the dev server exited" — which sends the reader into their own dev script hunting a bug
+ * that is not there.
+ */
+/**
+ * npm ships with node, so refusing for its absence would refuse on a machine that is fine.
+ */
+const ALWAYS_PRESENT = 'npm';
+/**
+ * The refusal to print, or undefined when this machine can run the install.
+ *
+ * `packageManager` is the one init RESOLVED, never a raw lockfile check. An inherited
+ * `pnpm-lock.yaml` at a monorepo root does not mean the app in `frontend/` uses pnpm — that app's own
+ * installed tree outranks an ancestor lockfile, and detect.ts already works this out. Re-deriving it
+ * here from `exists('pnpm-lock.yaml')` refused an npm app sitting under a pnpm monorepo on a machine
+ * with no pnpm, which the install gate proves must succeed.
+ */
+export function preflightRefusal(io, packageManager, options = {}) {
+    // First: on a read-only checkout nothing else matters, and one access check is cheaper and
+    // quieter than spawning a subprocess to discover the same thing.
+    if (!io.canWrite()) {
+        return (`${io.cwd()} is not writable, and init has to write into it (.reticle.json, the build config, ` +
+            'a capabilities file). Fix the permissions, or run init from a checkout you own.');
+    }
+    // What the project resolves to says nothing about what the machine HAS, and a project committed to
+    // pnpm on an npm-only box is an ordinary Monday.
+    //
+    // `alreadyServed` is `--url`, and skipping the check for it is the message keeping its own promise.
+    // This guard exists for the DEV SERVER — to stop `spawn pnpm ENOENT` surfacing inside "the dev
+    // server exited" — and `--url` says the app is already up, so init starts nothing and the failure
+    // it protects against cannot happen. Reported from the field as a circle: the refusal named `--url`
+    // as the way past it while `--url` was being passed, because the flag was parsed and then never
+    // handed to init at all.
+    //
+    // The dependency install can still fail without the package manager. That is one step reporting ⚠,
+    // which is what a step that cannot complete is for, and is a better outcome than writing nothing:
+    // the config, the connect module and `.reticle.json` all land, and the user is told the one thing
+    // left to do rather than being sent to install a package manager they were trying to avoid.
+    if (true !== options.alreadyServed &&
+        ALWAYS_PRESENT !== packageManager &&
+        !io.probe(packageManager, ['--version'])) {
+        return (`this project uses ${packageManager} (its lockfile says so) and ${packageManager} is not ` +
+            `installed on this machine. Install it (npm i -g ${packageManager}, or corepack enable), or ` +
+            'pass --url with the address the app already serves.');
+    }
+    return undefined;
+}

package/dist/project-id.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Project-identity for `reticle init` — the `.reticle.json` side of the scheme the Vite plugin
+ * stamps at build time. The RULE lives in `@reticlehq/core` (projectIdFrom) so both sides spell the
+ * id the same way by construction; this file supplies only the Node-only hashing it needs.
+ */
+export { slugifyPackageName } from '@reticlehq/core';
+/** Short, stable hex fingerprint of the absolute project root. */
+export declare function shortHash(input: string): string;
+/** Derive the stable projectId from the package name (may be undefined) and the absolute root path. */
+export declare function deriveProjectId(pkgName: string | undefined, rootPath: string): string;
+/** Pull a string `name` out of an already-parsed package.json object, or undefined. */
+export declare function packageName(pkg: unknown): string | undefined;

package/dist/project-id.js

@@ -0,0 +1,25 @@
+/**
+ * Project-identity for `reticle init` — the `.reticle.json` side of the scheme the Vite plugin
+ * stamps at build time. The RULE lives in `@reticlehq/core` (projectIdFrom) so both sides spell the
+ * id the same way by construction; this file supplies only the Node-only hashing it needs.
+ */
+import { createHash } from 'node:crypto';
+import { PROJECT_ID_HASH_LENGTH, projectIdFrom } from '@reticlehq/core';
+export { slugifyPackageName } from '@reticlehq/core';
+/** Short, stable hex fingerprint of the absolute project root. */
+export function shortHash(input) {
+    return createHash('sha1').update(input).digest('hex').slice(0, PROJECT_ID_HASH_LENGTH);
+}
+/** Derive the stable projectId from the package name (may be undefined) and the absolute root path. */
+export function deriveProjectId(pkgName, rootPath) {
+    return projectIdFrom(pkgName, rootPath, shortHash);
+}
+/** Pull a string `name` out of an already-parsed package.json object, or undefined. */
+export function packageName(pkg) {
+    if ('object' === typeof pkg && pkg !== null) {
+        const name = pkg['name'];
+        if ('string' === typeof name && name.length > 0)
+            return name;
+    }
+    return undefined;
+}

package/dist/refresh-rules.d.ts

@@ -0,0 +1,40 @@
+/**
+ * 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"];
+interface RuleFileIo {
+    read: (path: string) => string | null;
+    write: (path: string, content: string) => void;
+}
+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;
+export {};

package/dist/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/remember-project.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Record where this project lives, so a daemon started somewhere else can still find it.
+ *
+ * Called at the end of `init`, which is the one moment both halves are known for certain: the
+ * directory being initialised, and the projectId that was just written into its `.reticle.json`.
+ *
+ * Deliberately runs on EVERY init, not only the first. Most init runs report "already wired", and a
+ * re-run in a re-cloned or moved checkout is exactly when the remembered path has gone stale — so
+ * the run that would have been a no-op is the one that repairs the entry.
+ *
+ * Every failure is swallowed. This is a cache that makes a later resolution better; a read-only home
+ * directory, a full disk or a hand-mangled file must not turn a successful init into a failed one.
+ * The user's project is wired either way, and `init`'s report is the first thing a new user reads.
+ */
+/** The sync filesystem seam `init` already carries. Narrowed to what this needs. */
+export interface RegistryIo {
+    readFile(path: string): string | null;
+    writeFile(path: string, content: string): void;
+    exists(path: string): boolean;
+    homeDir(): string;
+}
+/** The `projectId` a `.reticle.json` declares, or undefined when it declares none we can use. */
+export declare function projectIdOf(configSource: string | null): string | undefined;
+export declare function rememberProjectOnDisk(io: RegistryIo, projectId: string, directory: string, now: number): boolean;

package/dist/remember-project.js

@@ -0,0 +1,40 @@
+import { join } from 'node:path';
+import { PROJECT_REGISTRY_FILE, ReticleDir, emptyProjectRegistry, parseProjectRegistry, rememberProject, } from '@reticlehq/core';
+/** The `projectId` a `.reticle.json` declares, or undefined when it declares none we can use. */
+export function projectIdOf(configSource) {
+    if (null === configSource || 0 === configSource.length)
+        return undefined;
+    try {
+        const parsed = JSON.parse(configSource);
+        if ('object' !== typeof parsed || null === parsed || Array.isArray(parsed))
+            return undefined;
+        const id = parsed['projectId'];
+        return 'string' === typeof id && id.length > 0 ? id : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function rememberProjectOnDisk(io, projectId, directory, now) {
+    if (0 === projectId.length || 0 === directory.length)
+        return false;
+    try {
+        const path = join(io.homeDir(), ReticleDir.ROOT, PROJECT_REGISTRY_FILE);
+        const existing = io.exists(path) ? io.readFile(path) : null;
+        const registry = null === existing ? emptyProjectRegistry() : parseProjectRegistry(safeJson(existing));
+        const next = rememberProject(registry, projectId, directory, now);
+        io.writeFile(path, `${JSON.stringify(next, null, 2)}\n`);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function safeJson(raw) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/run.d.ts

@@ -0,0 +1,122 @@
+/**
+ * The impure shell for `reticle init`: gather project files via an injected IO surface, build the
+ * 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 type { InitHost } from './host.js';
+import type { InitOutcome } from '@reticlehq/core/telemetry';
+import { resolveLockfiles } from './lockfiles.js';
+export { resolveLockfiles };
+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;
+    dryRun: boolean;
+    install: boolean;
+    /**
+     * Which app in a monorepo to wire, when several are found. Without it `init` refuses to guess, and
+     * "re-run inside the one you want" is not an instruction a script or an agent can follow.
+     */
+    app?: string;
+    /** Set on the recursive call after a workspace redirect, so the search happens at most once. */
+    redirected?: boolean;
+    /**
+     * `--url`: the address the app is ALREADY served on, so init starts nothing.
+     *
+     * Parsed by the CLI since the flag existed and never handed to `init`, which made the
+     * package-manager refusal name it as the escape hatch while being unable to see it. The value
+     * itself is not read here — only whether one was given — but it is typed as the URL rather than a
+     * boolean so the option means the same thing everywhere the flag does.
+     */
+    url?: string | undefined;
+    /**
+     * Where the human ran the command, carried across a workspace redirect.
+     *
+     * The agent rule and `/reticle` command files are read by the AGENT, whose session runs where the
+     * human started it — the repo root. Writing them beside the app instead is how a repo with its app
+     * at `src/admin` ended up with no `/reticle` at all (#318).
+     */
+    agentRoot?: string;
+    /**
+     * Hand the telemetry outcome back rather than emitting it here.
+     *
+     * `init` now stays to watch for an app to connect, and whether it saw one belongs on the SAME
+     * `init_completed` event — the funnel it exists to measure would be double-counted by a second
+     * emit and unjoinable as a second event kind. Only the CLI sets this; every other caller keeps
+     * 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. */
+    readFile(relPath: string): string | null;
+    /** Writes content, creating parent directories. Path is project-relative or absolute. */
+    writeFile(relPath: string, content: string): void;
+    exists(relPath: string): boolean;
+    /** The user's home directory (for global agent config like ~/.cursor/mcp.json). */
+    homeDir(): string;
+    /** Absolute path of the directory `init` is running in — the project's own root. */
+    cwd(): string;
+    /** Basenames present in the project root. */
+    rootFiles(): readonly string[];
+    /** Subdirectory names inside a project-relative directory; empty when it isn't one. */
+    listDirs(relPath: string): readonly string[];
+    /** File (non-directory) basenames inside a project-relative directory, including dotfiles. */
+    listFiles(relPath: string): readonly string[];
+    /** 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. */
+    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;
+    /**
+     * The capabilities only the daemon has: the release version's tracer, the outcome reporter, the
+     * bridge pairing token and the declared install channel. See host.ts for why they are carried
+     * here rather than as a second parameter, and why none of them is optional.
+     */
+    host: InitHost;
+}
+/**
+ * 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.
+ */
+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;
+}
+export declare function runInit(options: InitOptions, io: InitIo): InitResult;