@reticlehq/server 2.13.0 → 2.14.0

package/dist/init/preflight.d.ts

@@ -1,28 +0,0 @@
-/**
- * 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): string | undefined;

package/dist/init/preflight.js

@@ -1,38 +0,0 @@
-/**
- * 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) {
-    // 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.
-    if (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/init/project-id.d.ts

@@ -1,12 +0,0 @@
-/**
- * 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/init/project-id.js

@@ -1,25 +0,0 @@
-/**
- * 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/init/refresh-rules.d.ts

@@ -1,39 +0,0 @@
-/**
- * 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

@@ -1,51 +0,0 @@
-/**
- * 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

@@ -1,117 +0,0 @@
-/**
- * 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 { InitOutcome } from '@reticlehq/core';
-/**
- * Resolve the lockfiles set used to pick the package manager. A lockfile in the project root wins;
- * otherwise we walk UP the directory tree (monorepos keep the lockfile at the workspace root, not in
- * each package) so `reticle init` in a sub-package suggests `pnpm add` instead of defaulting to `npm i`.
- *
- * The walk is skipped when the project has its own installed tree, because an INHERITED lockfile is
- * weaker evidence than a `node_modules` sitting right there — the ancestor describes the workspace,
- * the tree describes THIS package. Reported from the field: `init` in a `frontend/` app installed
- * with npm emitted `pnpm add -D` off a repo-root `pnpm-lock.yaml`, pnpm was not on PATH, and the
- * failed install took every downstream wiring step with it. A LOCAL lockfile still wins over the
- * tree — it is a deliberate statement about this package, not an inheritance.
- */
-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;
-    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;
-    /**
-     * 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;
-}
-/**
- * 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;
-}
-export declare function runInit(options: InitOptions, io: InitIo): InitResult;