@reticlehq/server 2.13.0 → 2.14.0

package/dist/init/plan.d.ts

@@ -1,242 +0,0 @@
-/**
- * Pure assembly of the `reticle init` action plan. Given the detection result and the relevant file
- * contents, produce an ordered list of steps — each marked apply / manual / already / skip. The
- * runner performs the `write` side-effects; this module decides *what* should happen.
- */
-import { Framework, UiLibrary, type Detection } from './detect.js';
-import type { FoundStore } from './capabilities.js';
-import { McpClient } from './mcp-clients.js';
-/**
- * The dev-dependencies `reticle init` installs — kit (or sensor) first, build plugin next.
- *
- * `uiLibrary` matters because the framework does not always name the renderer. The rule below was
- * already written for Nuxt, correctly, and applied only there: a Vue app on plain Vite is
- * `Framework.VITE` and a SvelteKit app renders Svelte, and both were being handed the React kit
- * right after `init` had detected the real UI library and said so on screen.
- */
-export declare function frameworkPackages(framework: Framework, uiLibrary?: UiLibrary): readonly string[];
-/** Exported so the init telemetry can tell an MCP-registration failure from a dependency install. */
-export declare const MCP_TARGET = "global (claude user scope)";
-/** The step that runs the package manager — the other thing that commonly fails on a user's machine. */
-export declare const DEPS_TARGET = "package.json";
-export declare const RETICLE_CONFIG_FILE = ".reticle.json";
-export declare const StepStatus: {
-    readonly APPLY: "apply";
-    readonly MANUAL: "manual";
-    readonly ALREADY: "already";
-    readonly SKIP: "skip";
-    /**
-     * Something the user should KNOW, not something they must DO. The UNVERIFIED lines are the case:
-     * a Preact or SvelteKit app is wired and working, it just isn't covered by a gate. Reporting those
-     * as `manual` made "steps left to do" a number that could never reach zero, and made a release gate
-     * read two regressions that were not regressions.
-     */
-    readonly NOTICE: "notice";
-};
-export type StepStatus = (typeof StepStatus)[keyof typeof StepStatus];
-export interface Step {
-    title: string;
-    target: string;
-    status: StepStatus;
-    detail: string;
-    /** Present only when status is APPLY and a file must be written. */
-    write?: {
-        path: string;
-        content: string;
-    };
-    /** Present only when status is APPLY and a subprocess must run (the dependency install). */
-    exec?: {
-        command: string;
-        args: string[];
-        fallback: string;
-    };
-    /**
-     * A second, weaker attempt to run when `exec` fails, with what to tell the user if it succeeds.
-     *
-     * The pinned install is refused outright by pnpm's `minimumReleaseAge` for as long as its window
-     * lasts — so for ~48 hours after every release, a project with that setting could not install
-     * Reticle at all. An unpinned install still works there (it resolves the newest MATURE version), so
-     * the fallback trades an exact version for a working install and says which it did. It must never
-     * be silent: an older SDK against a newer daemon is the skew this pin exists to prevent.
-     */
-    retry?: {
-        command: string;
-        args: string[];
-        note: string;
-    };
-    /**
-     * This step wires the app to a package the install step provides. If that install fails, applying
-     * it anyway leaves the app importing a module that is not there — `next.config.ts` importing
-     * `@reticlehq/next` took a dev server down exactly this way. Installing Reticle must never be the
-     * reason an app stops booting.
-     */
-    dependsOnInstall?: boolean;
-}
-export interface Plan {
-    framework: Framework;
-    /**
-     * The renderer this app actually uses, carried so every consumer agrees on WHICH packages the
-     * plan installed. The retry guard checks node_modules for exactly those names; without this it
-     * looked for `@reticlehq/react` in a Vue app that had correctly been given the sensor, decided the
-     * install had failed, and skipped every wiring step on the retry.
-     */
-    uiLibrary: UiLibrary;
-    steps: Step[];
-}
-export interface PlanInput {
-    detection: Detection;
-    /**
-     * Write `captureNetworkBodies: true` into the app's config. Off unless the caller asked (#705).
-     *
-     * Optional so every existing caller and test keeps the safe default without naming it — the one
-     * direction a default about somebody else's data should be wrong in.
-     */
-    captureBodies?: boolean | undefined;
-    /**
-     * The CSP-bearing files this project actually has, keyed by path — read once in `gatherPlanInput`.
-     *
-     * Pre-read rather than given a reader, because `PlanInput` is the pure input to a pure planner and
-     * handing it an io would let any later step reach the disk from inside `buildPlan`.
-     */
-    cspSources?: Readonly<Record<string, string | undefined>> | undefined;
-    /** Whether the `claude` CLI is installed (so we can register the MCP server globally). */
-    claudeCli: boolean;
-    /** Whether an `reticle` MCP server is already registered with Claude (any scope) — idempotency. */
-    mcpExists: boolean;
-    /** `process.platform`. Injected so this module stays pure. Windows is the only branch. */
-    platform?: string;
-    /** Whether THIS project has a .cursor/ directory — the signal that Cursor works on this repo. */
-    cursorProjectPresent?: boolean | undefined;
-    /**
-     * Every OTHER MCP client detected on this machine, with its config path and current content.
-     *
-     * Claude Code and Cursor keep their own steps — Claude registers through its CLI, and Cursor's
-     * predates this. Everything else is uniform: read the file, merge, write.
-     */
-    detectedClients?: readonly {
-        id: McpClient;
-        configPath: string;
-        existing: string | null;
-    }[] | undefined;
-    /** Discovered Vite config: its path + source, or null if none found. */
-    viteConfig: {
-        path: string;
-        source: string;
-    } | null;
-    /** Discovered Astro config: its path + source, or null if none found. */
-    astroConfig?: {
-        path: string;
-        source: string;
-    } | null | undefined;
-    /**
-     * The single layout to instrument, or null when the choice is not obvious.
-     *
-     * WHICH page or layout to instrument is a real decision — so `init` only makes it when there is
-     * exactly one candidate. Zero or several falls back to the printed recipe rather than guessing at
-     * the file every page of the user's site inherits from.
-     */
-    astroLayout?: {
-        path: string;
-        source: string;
-    } | null | undefined;
-    /**
-     * Existing `src/env.d.ts` content, when present — where the Vite-define ambient declarations go
-     * so `astro check` can see `__RETICLE_TOKEN__` / `__RETICLE_ROOT__` (#677).
-     */
-    astroEnvDts?: string | null | undefined;
-    /** Discovered Next config filename (e.g. 'next.config.mjs'), or null. */
-    nextConfigFile: string | null;
-    /** Source of that Next config, so the export can be wrapped in withReticle. */
-    nextConfigSource?: string | null | undefined;
-    /** Discovered Next root layout: its path + source, or null (App Router only). */
-    nextLayout?: {
-        path: string;
-        source: string;
-    } | null | undefined;
-    /** Where the dev-only connect component goes — never inside `pages/`, which routes on presence. */
-    nextReticleDevPath?: string | undefined;
-    /** What the mount file should import — a sibling for App Router, `../components/…` for Pages. */
-    nextReticleDevImport?: string | undefined;
-    /** Whether the ReticleDev component file already exists. */
-    nextReticleDevExists: boolean;
-    /**
-     * The existing ReticleDev component's source, when there is one.
-     *
-     * Read so an install predating daemon discovery can be told apart from a current one. Undefined
-     * means NOT READ, and an unread file is reported as already-wired rather than as stale: inventing
-     * work from missing information is how a plan grows steps that can never be completed.
-     */
-    nextReticleDevSource?: string | null | undefined;
-    /** `data-testid` values scanned from the app's source, for the generated capabilities block. */
-    testids?: readonly string[] | undefined;
-    /** Ready-to-uncomment `registerStore` lines for the state libraries the app actually depends on. */
-    storeHints?: readonly string[] | undefined;
-    /** Store instances found in the app's own source — imported and registered outright, not hinted. */
-    foundStores?: readonly FoundStore[] | undefined;
-    /** The same stores, with specifiers resolved from Next's dev-module directory instead of `src/`. */
-    nextFoundStores?: readonly FoundStore[] | undefined;
-    /** Whether src/reticle-dev.ts already exists — it is the one generated file users are meant to edit. */
-    viteDevModuleExists?: boolean | undefined;
-    /** Whether src/hooks.client.ts already exists (SvelteKit idempotency). */
-    svelteKitHooksExists?: boolean;
-    /** CRA's bundled entry (src/index.tsx or .js) — where the connect import has to go. */
-    craEntry?: {
-        path: string;
-        source: string;
-    } | null;
-    /** Existing .env.development.local, so an unrelated variable in it survives. */
-    craEnv?: string | null;
-    /** The daemon's pairing token, inlined for CRA through the one channel it supports. */
-    pairingToken?: string;
-    /** Whether .reticle.json already exists in the project root (idempotency). */
-    reticleConfigExists?: boolean;
-    /**
-     * Its CONTENT, so an existing config can be checked instead of trusted.
-     *
-     * Existence alone said "a file is present" and was reported as "this is configured correctly" —
-     * see reticleConfigStep for the port that survived every re-run because of it.
-     */
-    reticleConfigSource?: string | null | undefined;
-    /** Current project-root CLAUDE.md content (for the idempotent agent-rule merge), or null/undefined. */
-    claudeMdContent?: string | null | undefined;
-    /** Current project-root AGENTS.md content (the cross-agent rule), or null/undefined. */
-    agentsMdContent?: string | null | undefined;
-    /** Current project-root RETICLE.md content (the full rules), or null when absent. */
-    reticleMdContent?: string | null | undefined;
-    /**
-     * Current .cursor/rules/reticle.mdc content, or null when absent.
-     *
-     * CONTENT, not existence. Gating on the file merely being there froze a Cursor project's rule at
-     * whatever release wrote it — so the CLAUDE.md path refreshed itself while the Cursor one never
-     * could, and a rule added later (`version_skew`) never reached a Cursor-only project at all.
-     */
-    cursorRuleContent?: string | null | undefined;
-    /** Current .claude/commands/reticle.md content, or null when absent (slash-command idempotency). */
-    claudeCommandContent?: string | null | undefined;
-    /** Current .cursor/commands/reticle.md content, or null when absent. */
-    cursorCommandContent?: string | null | undefined;
-    /**
-     * Absolute directory the AGENT runs in, when that is not the app's directory.
-     *
-     * The rule and command files are read by the agent, not by the app, so a monorepo whose app is a
-     * directory down must still get its `/reticle` where the human's session actually stands. Absent
-     * (the single-package case) leaves every path project-relative exactly as before.
-     */
-    agentFileRoot?: string | undefined;
-    /**
-     * Content of the `.reticle.json` already sitting at that agent root, or null/undefined when there
-     * is none. Content rather than existence, for the reason `reticleConfigSource` is: a root config
-     * that disagrees with the app's is worse than no root config, and only reading it can tell.
-     */
-    agentRootConfigSource?: string | null | undefined;
-    options: {
-        port: number | undefined;
-        mcp: boolean;
-        install: boolean;
-        /** Stable project identity derived at init (package.json name + root). Baked into snippets/.reticle.json. */
-        projectId?: string;
-        /** The CLI's own version, pinned onto the SDK install so a stale registry cache cannot skew it. */
-        sdkVersion?: string;
-    };
-}
-export declare function buildPlan(input: PlanInput): Plan;