specrails-core 5.2.3 → 5.3.0

package/dist/installer/util/errors.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Typed error hierarchy for the installer. Each subclass carries an
+ * `exitCode` which the CLI dispatcher translates to the process exit
+ * code so callers (shells, CI, specrails-desktop wizard) can distinguish
+ * failure modes without string-parsing stdout.
+ *
+ * Exit-code ranges:
+ *   0       — success
+ *   1       — generic runtime error
+ *   10-19   — prerequisite failures (missing tools, auth, etc.)
+ *   20-29   — filesystem / I/O errors
+ *   30-39   — git errors
+ *   40-49   — provider detection / resolution errors
+ *   50-59   — child-process errors (spawned command failed)
+ *   60      — user aborted a prompt (Ctrl+C or non-TTY with no default)
+ */
+export declare class InstallerError extends Error {
+    readonly exitCode: number;
+    constructor(message: string, exitCode?: number);
+}
+export declare class PrerequisiteError extends InstallerError {
+    constructor(message: string);
+}
+export declare class FilesystemError extends InstallerError {
+    readonly path: string | undefined;
+    constructor(message: string, path?: string);
+}
+export declare class GitError extends InstallerError {
+    readonly command: string | undefined;
+    constructor(message: string, command?: string);
+}
+export declare class ProviderError extends InstallerError {
+    constructor(message: string);
+}
+export declare class ExecError extends InstallerError {
+    readonly command: string;
+    readonly code: number | null;
+    readonly stdout: string;
+    readonly stderr: string;
+    constructor(command: string, code: number | null, stdout: string, stderr: string);
+}
+export declare class PromptAbortError extends InstallerError {
+    constructor(message?: string);
+}
+/** Runtime check used by the CLI to map a caught unknown to a typed error. */
+export declare function isInstallerError(err: unknown): err is InstallerError;

package/dist/installer/util/exec.d.ts

@@ -0,0 +1,41 @@
+export interface RunOptions {
+    /** Working directory for the child. Defaults to `process.cwd()`. */
+    cwd?: string;
+    /** Environment variables, merged on top of `process.env`. */
+    env?: NodeJS.ProcessEnv;
+    /** Stream stdio to the parent (default). When `false`, stdout/stderr are captured and returned. */
+    inherit?: boolean;
+    /** Hard timeout in milliseconds. Child is SIGKILL'd on timeout. Defaults to none. */
+    timeoutMs?: number;
+}
+export interface RunResult {
+    code: number;
+    stdout: string;
+    stderr: string;
+}
+/**
+ * Cross-platform spawn wrapper.
+ *
+ * - On Windows sets `shell: true` so `.cmd` / `.bat` shims (claude.cmd,
+ *   npm.cmd, gh.cmd) are executable. Required by Node.js since
+ *   CVE-2024-27980; without it, spawning a `.cmd` throws.
+ * - On POSIX sets `shell: false` to keep argv boundaries clean and
+ *   avoid shell-injection surface on user-provided args.
+ * - Streams stdio by default so long commands show progress. Set
+ *   `inherit: false` to capture stdout/stderr into the returned
+ *   {@link RunResult}.
+ * - Throws {@link ExecError} on non-zero exit (captured stdout/stderr
+ *   attached) unless the caller passed `inherit: true` (stream mode).
+ */
+export declare function runCommand(cmd: string, args: string[], opts?: RunOptions): Promise<RunResult>;
+/**
+ * Runs a command and returns whether it exited zero. Never throws.
+ * Useful for feature-detection style probes (`commandExists`,
+ * `git --version`).
+ */
+export declare function tryRunCommand(cmd: string, args: string[], opts?: RunOptions): Promise<boolean>;
+/**
+ * Cross-platform check for whether a command is on PATH. Uses `where`
+ * on Windows and `which` on POSIX.
+ */
+export declare function commandExists(cmd: string): Promise<boolean>;

package/dist/installer/util/fs.d.ts

@@ -0,0 +1,153 @@
+import { Buffer } from 'node:buffer';
+/**
+ * `mkdir -p` equivalent. Idempotent — no-op when `dir` already exists.
+ * Wraps filesystem errors as {@link FilesystemError} so callers get
+ * a typed exit code via the CLI dispatcher.
+ */
+export declare function mkdirp(dir: string): void;
+/**
+ * True when the path exists at all (file, directory, symlink, …).
+ */
+export declare function pathExists(p: string): boolean;
+/**
+ * Writes `contents` to `filePath` after ensuring the parent directory
+ * exists and normalising line endings to LF. Normalisation rule:
+ * every `\r\n` → `\n`; lone `\r` left alone (very uncommon in our
+ * template inputs and more invasive to rewrite). Callers relying on
+ * strict LF-only output should pre-clean their strings.
+ */
+export declare function writeFileLf(filePath: string, contents: string): void;
+/**
+ * Reads a UTF-8 text file. Wraps failures as {@link FilesystemError}.
+ */
+export declare function readTextFile(filePath: string): string;
+/**
+ * Reads a file and returns its raw bytes. Used by the manifest hasher
+ * to avoid UTF-8 re-encoding round trips.
+ */
+export declare function readBytes(filePath: string): Buffer;
+/**
+ * Copies a single file, ensuring the destination directory exists.
+ */
+export declare function copyFile(src: string, dest: string): void;
+/**
+ * Recursively copies a directory. Overwrites existing files by default.
+ * Honours a `filter(src, relPath)` predicate — returning false skips
+ * the entry (and, if it's a directory, its subtree).
+ */
+export declare function copyDir(srcDir: string, destDir: string, options?: {
+    filter?: (src: string, relPath: string) => boolean;
+}): void;
+/**
+ * Lists the immediate entries (files + directories) of `dir`. Returns
+ * absolute paths. Empty array when `dir` does not exist.
+ */
+export declare function listDir(dir: string): string[];
+/**
+ * True when the target path exists and resolves to a regular file.
+ */
+export declare function isFile(p: string): boolean;
+/**
+ * True when the target path exists and resolves to a directory.
+ */
+export declare function isDir(p: string): boolean;
+/**
+ * True when `p` itself is a symbolic link (does NOT follow the link). Used by
+ * the bundled-framework assembly to detect (and re-create) the per-workspace
+ * provider subtree links. Returns false for a real dir/file or a missing path.
+ */
+export declare function isSymlink(p: string): boolean;
+/**
+ * Resolve a path through symlinks to its real on-disk location, falling back to
+ * the resolved-but-unreal path when the target does not exist yet (mirrors
+ * registry.ts's `realpathSafe`).
+ */
+export declare function realpathSafe(p: string): string;
+/**
+ * Remove a file, directory, or symlink at `p` if present. For a symlink the
+ * link itself is removed (the target is never followed/deleted). Best-effort:
+ * a missing path is a no-op. Used before (re-)creating a workspace link.
+ */
+export declare function removePath(p: string): void;
+/**
+ * Ensure `<linkPath>` resolves to `<target>` via a symbolic link, with the same
+ * junction→symlink→copy fallback dance specrails-desktop uses for the project
+ * link (`workspace-manager.ts ensureProjectLink`).
+ *
+ *   1. POSIX: a plain `symlinkSync(target, linkPath, type)`.
+ *   2. Windows: try a junction (dirs) / file symlink first, then a plain symlink.
+ *   3. Both failed (e.g. unprivileged Windows): COPY the target subtree verbatim.
+ *
+ * When `preferCopy` is true the symlink/junction attempts are SKIPPED entirely
+ * and the target is copied directly — used by the in-repo standalone install so
+ * the repo receives real, committable files instead of symlinks pointing into
+ * `$HOME/.specrails/framework`. (An existing correct symlink at `linkPath` is
+ * still honoured idempotently before the copy so a re-run of a relocated install
+ * does not thrash.)
+ *
+ * Returns the mechanism used so the caller can record it (copy-fallback loses the
+ * O(1) `current`-swap update path; the caller may warn). Idempotent: when the
+ * link already points at `target` it is left untouched and `'symlink'` returned.
+ */
+export declare function symlinkOrCopy(target: string, linkPath: string, preferCopy?: boolean): 'symlink' | 'junction' | 'copy';
+/**
+ * Atomically repoint `<linkPath>` at `<target>`: create a sibling temp link,
+ * then `renameSync` over the destination (rename of a symlink is atomic on
+ * POSIX; on Windows the temp+rename pattern still avoids a torn intermediate
+ * state). Used for the `framework/current` indirection swap.
+ */
+export declare function atomicSymlinkSwap(target: string, linkPath: string): void;
+/**
+ * One link found while snapshotting a protected surface.
+ *
+ * `rel` is the POSIX path of the link RELATIVE to the snapshot root, and is the
+ * empty string when the surface itself is a link.
+ */
+export interface LinkRecord {
+    rel: string;
+    target: string;
+}
+/**
+ * Copy `src` to `dest` for a rollback snapshot WITHOUT ever creating a link.
+ *
+ * `fs.cpSync(..., { dereference: false, verbatimSymlinks: true })` looks like the
+ * obvious primitive, but it does not copy a link — it RECREATES it with
+ * `symlinkSync(target, dest)` and never passes a `type`. Node then autodetects
+ * `'file'`/`'dir'`, never `'junction'`, and a `'file'`/`'dir'` symlink on Windows
+ * requires SeCreateSymbolicLinkPrivilege. On an ordinary account that raises
+ * EPERM, so merely BACKING UP a surface that contains a link (every
+ * `<frameworkDir>/current`, every assembled workspace provider dir) failed before
+ * the install had done anything at all.
+ *
+ * Links are therefore RECORDED, not reproduced: the returned records carry each
+ * link's target, and {@link restoreTree} puts them back through
+ * {@link symlinkOrCopy}, which already knows the junction-first, copy-fallback
+ * dance. Taking a snapshot needs no filesystem privilege on any platform.
+ *
+ * Inode types that are neither link, directory nor file are skipped — the same
+ * stance {@link copyDir} takes. Walking in JS also keeps these copies away from
+ * Node 22's native Unicode directory-copy defect on Windows (nodejs/node#61878),
+ * which the `cpSync` call this replaced had to work around explicitly.
+ */
+export declare function snapshotTree(src: string, dest: string): LinkRecord[];
+/**
+ * Put a snapshot taken by {@link snapshotTree} back at `target`.
+ *
+ * `skip(rel)` receives the same POSIX-relative paths the records use ('' for the
+ * root) and suppresses restoring that entry — the reserved-path rule, so a file
+ * the user created or edited while the install was running is never overwritten
+ * by a stale backup copy.
+ */
+export declare function restoreTree(saved: string, target: string, links: LinkRecord[], options?: {
+    skip?: (rel: string) => boolean;
+}): void;
+/**
+ * Recreate a recorded link at `linkPath`. Delegates to {@link symlinkOrCopy} so
+ * Windows gets a junction (no privilege required) and an unprivileged machine
+ * with no link mechanism at all still ends up with the right CONTENTS.
+ *
+ * A target that no longer exists cannot be copied, so the pointer is recreated
+ * verbatim where the platform allows a dangling link rather than failing the
+ * whole rollback.
+ */
+export declare function restoreLink(target: string, linkPath: string): void;

package/dist/installer/util/git.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Low-level git wrapper. Every method shells out to the user's `git`
+ * binary (already a prerequisite — the installer refuses to run
+ * without a git repo). Failures surface as {@link GitError} so the
+ * CLI dispatcher translates them to exit code 30.
+ *
+ * We intentionally keep the surface minimal (the six operations used
+ * by the installer) rather than wrapping `simple-git` — that package
+ * is ~100 KB and wraps the same shell-out we do here.
+ */
+export declare function isGitRepo(cwd: string): Promise<boolean>;
+/**
+ * Returns the absolute path of the repository root containing `cwd`.
+ * Throws {@link GitError} if `cwd` is not inside a git repo.
+ */
+export declare function repoRoot(cwd: string): Promise<string>;
+/**
+ * Initialises a new git repository at `cwd` with an initial commit on
+ * the default branch name. Idempotent — no-op when `cwd` is already
+ * a repo.
+ */
+export declare function initRepo(cwd: string): Promise<void>;
+/**
+ * Porcelain working-tree status. Returns the raw short-format output
+ * (empty string when the tree is clean).
+ */
+export declare function status(cwd: string): Promise<string>;
+/**
+ * Stages the given pathspecs. Empty array stages nothing and returns
+ * without invoking git.
+ */
+export declare function add(cwd: string, pathspecs: string[]): Promise<void>;
+/**
+ * Creates a commit with the given message using the committer identity
+ * currently configured on the repo / globally. Does NOT attempt to
+ * install an identity — that is a prerequisite check.
+ */
+export declare function commit(cwd: string, message: string, opts?: {
+    allowEmpty?: boolean;
+}): Promise<void>;
+/**
+ * True when git is installed and on PATH.
+ */
+export declare function gitInstalled(): Promise<boolean>;

package/dist/installer/util/install-transaction.d.ts

@@ -0,0 +1,29 @@
+export declare const frameworkLifecycleLockPath: (frameworkDir: string) => string;
+export declare function withFrameworkLifecycleLock<T>(frameworkDir: string, apply: () => T | Promise<T>): Promise<T>;
+/**
+ * A surface the transaction protects.
+ *
+ * `snapshotContents: false` marks a surface whose CONTENTS must not be copied:
+ * the versioned framework store, which `installFramework` already rebuilds from
+ * a content-hash stamp and stages through a temp directory. Rollback still
+ * removes such a surface when the install CREATED it, and leaves a pre-existing
+ * one exactly as it stands — copying it bought no safety and cost a full copy of
+ * the framework store on every install.
+ */
+export type ProtectedSurface = string | {
+    path: string;
+    snapshotContents: boolean;
+};
+/** Snapshot only installer-owned surfaces; never follow links into a shared framework.
+ * Backups survive a failed rollback and their location is reported for recovery.
+ *
+ * Snapshotting requires NO filesystem privilege: links are recorded by target
+ * rather than recreated (see `snapshotTree`), so a protected surface that is —
+ * or contains — a Windows junction no longer fails the install on an account
+ * without SeCreateSymbolicLinkPrivilege.
+ */
+export declare function withInstallRollback<T>(paths: ProtectedSurface[], apply: () => Promise<T>): Promise<T>;
+export declare function compareCoreVersions(left: string, right: string): number | null;
+/** Refuse an implicit downgrade. Explicit swap-current is the rollback interface. */
+export declare function assertNoCoreDowngrade(current: string | null, target: string): void;
+export declare function currentFrameworkVersion(frameworkDir: string): string | null;

package/dist/installer/util/logger.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Coloured output helpers for the installer. The emoji prefixes match
+ * what the retired bash scripts printed (`✓ ⚠ ✗ →`) so existing user
+ * bug reports and screenshots still read the same.
+ *
+ * The logger writes to stdout by default; callers may override via
+ * {@link setLoggerStreams} (useful in tests that capture output).
+ */
+interface Streams {
+    out: NodeJS.WritableStream;
+    err: NodeJS.WritableStream;
+}
+export declare function setLoggerStreams(next: Partial<Streams>): void;
+/** Restore logger to process.stdout/stderr. */
+export declare function resetLoggerStreams(): void;
+/** Section heading — bold, no prefix, leading blank line. */
+export declare function step(title: string): void;
+/** Success line. Prefix: `  ✓ ` in green. */
+export declare function ok(msg: string): void;
+/** Warning line. Prefix: `  ⚠ ` in yellow. */
+export declare function warn(msg: string): void;
+/** Failure line, routed to stderr. Prefix: `  ✗ ` in red. */
+export declare function fail(msg: string): void;
+/** Info line. Prefix: `  → ` in blue. */
+export declare function info(msg: string): void;
+/** Print a fatal error and its hint, routed to stderr. */
+export declare function fatal(message: string, hint?: string): void;
+/** Primitive write for cases where the caller owns formatting. */
+export declare function rawOut(text: string): void;
+export declare function rawErr(text: string): void;
+export {};

package/dist/installer/util/paths.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Paths the installer MUST NOT create, modify, or delete. These hold
+ * user / team state that survives re-runs (profile JSON authored by
+ * specrails-desktop, custom agents authored by the user). Breaking this
+ * contract silently destroys user work.
+ *
+ * Audited by vitest spec `reserved-paths.test.ts`.
+ */
+export declare const RESERVED_PATHS: readonly [".specrails/profiles/", ".claude/agents/custom-", ".kimi-code/skills/custom-", ".kimi-code/skills/rails/custom-"];
+/**
+ * Returns true when a repo-relative path falls inside a reserved
+ * region. Accepts both POSIX (/) and Windows (\) separators; the
+ * check normalises internally so callers can pass a value straight
+ * from `path.relative()` without worrying about host platform.
+ */
+export declare function isReservedPath(relPath: string): boolean;
+/**
+ * Joins segments and forces POSIX separators. Use when a generated
+ * string is destined for a cross-platform artefact (JSON manifest,
+ * YAML config) rather than the local filesystem.
+ */
+export declare function toPosix(...segments: string[]): string;
+/**
+ * Joins segments using the host platform's separator. Use when the
+ * result goes directly to `fs.*` / `child_process.*` calls.
+ */
+export declare function toNative(...segments: string[]): string;
+/**
+ * Repository-relative representation of an absolute path. Returns a
+ * POSIX-style path so callers can store it in manifests without OS
+ * contamination. If `absPath` is outside `repoRoot`, returns the
+ * original absolute path unchanged (POSIX-normalised).
+ */
+export declare function repoRelative(repoRoot: string, absPath: string): string;

package/dist/installer/util/prompts.d.ts

@@ -0,0 +1,23 @@
+export interface TextOptions {
+    message: string;
+    /** Value used when stdin is non-TTY. Absence here in non-TTY mode throws. */
+    default?: string;
+    /** Returns error message when invalid, or `true` / undefined when valid. */
+    validate?: (value: string) => string | true | undefined;
+}
+export declare function text(opts: TextOptions): Promise<string>;
+export interface ConfirmOptions {
+    message: string;
+    default?: boolean;
+}
+export declare function confirmYesNo(opts: ConfirmOptions): Promise<boolean>;
+export interface SelectOptions<T> {
+    message: string;
+    choices: Array<{
+        name: string;
+        value: T;
+        description?: string;
+    }>;
+    default?: T;
+}
+export declare function chooseOne<T>(opts: SelectOptions<T>): Promise<T>;

package/dist/installer/util/registry.d.ts

@@ -0,0 +1,174 @@
+/**
+ * Shared artifact registry — the contract that lets specrails-core place,
+ * and specrails-desktop read, a repo's relocated artifacts OUTSIDE the repo,
+ * under `$HOME/.specrails/projects/<slug>/workspace`.
+ *
+ * Single source of truth: `$HOME/.specrails/registry.json`, an inspectable,
+ * schema-versioned JSON file keyed by the **canonical realpath of the repo**.
+ * specrails-desktop is the primary writer (a projection of its `desktop.sqlite`);
+ * specrails-core reads it and, when run standalone, allocates its own entry.
+ *
+ * Design contract: `docs/internals/global-artifacts-alignment-contract.md`
+ * (in the specrails-desktop repo). The slug algorithm, canonical-key rule,
+ * atomic-write rule and lock protocol here MUST stay byte-identical to the
+ * desktop-side implementation — the correctness of the cross-tool contract
+ * depends on both tools resolving the same repo to the same paths.
+ *
+ * Everything in this module is synchronous to fit the installer's sync flow.
+ */
+/** Registry schema version. A reader that sees a higher value MUST treat all
+ *  entries as absent (legacy fallback), never mis-parse. */
+export declare const REGISTRY_SCHEMA_VERSION = 1;
+/** Who owns/allocated an entry. Encodes the single-writer-at-a-time rule. */
+export type RegistrySource = 'desktop' | 'core-standalone';
+/** One repo's relocated-artifact locations. All paths are absolute and in the
+ *  host platform's native separator; consumers treat them as opaque. */
+export interface ProjectEntry {
+    /** The canonical realpath of the repo (mirror of the map key). */
+    repoPath: string;
+    /** Shared slug — MUST equal desktop.sqlite `projects.slug` for the same repo. */
+    slug: string;
+    /** `$HOME/.specrails/projects/<slug>/workspace` — root of all relocated artifacts. */
+    workspaceDir: string;
+    /** The dir core treats as its `.specrails`/install root instead of repoRoot (= workspaceDir). */
+    artifactRoot: string;
+    /** Always the repo (= repoPath); carries the `openspec/**` + worktree carve-outs. */
+    codeRoot: string;
+    /** Runtime-state base (agent-memory, pipeline-state, …). Injected as SPECRAILS_STATE_DIR. */
+    stateDir: string;
+    /** Absolute path to the relocated local-tickets.json. Injected as SPECRAILS_TICKETS_PATH. */
+    ticketsPath: string;
+    /** Absolute path to backlog-config.json (Jira read-only switch). Injected as SPECRAILS_BACKLOG_CONFIG_PATH. */
+    backlogConfigPath: string;
+    /** Relocated `.specrails/profiles/`. Injected as SPECRAILS_PROFILES_DIR. */
+    profilesDir: string;
+    /** Relocated `.specrails/plugins/` (desktop-only; present for inspectability). */
+    pluginsStateDir: string;
+    /** Relocated `.specrails/file-summaries/` (desktop-only). */
+    fileSummariesDir: string;
+    /** Installed providers; mirror of desktop.sqlite `projects.providers`. */
+    providers: string[];
+    /** providers[0]; mirror of desktop.sqlite `projects.provider`. */
+    primaryProvider: string;
+    /** The `specrails-version` pin (name/format frozen; only location moved). */
+    coreVersion?: string;
+    createdAt?: string;
+    lastInstallAt?: string;
+    /** Single-owner-at-a-time marker; governs reconciliation. */
+    source: RegistrySource;
+    /** desktop.sqlite projects.id when source='desktop', for robust repo-move re-link. */
+    desktopProjectId?: string;
+}
+/** On-disk shape of `registry.json`. */
+export interface RegistryFile {
+    schemaVersion: number;
+    generator?: string;
+    updatedAt?: string;
+    /** Map: canonical-repo-key -> ProjectEntry. */
+    projects: Record<string, ProjectEntry>;
+}
+/** The flattened result both tools consume. */
+export interface Resolution {
+    /** Normalized map key. */
+    key: string;
+    repoPath: string;
+    slug: string;
+    workspaceDir: string;
+    artifactRoot: string;
+    codeRoot: string;
+    stateDir: string;
+    ticketsPath: string;
+    backlogConfigPath: string;
+    profilesDir: string;
+    pluginsStateDir: string;
+    fileSummariesDir: string;
+    providers: string[];
+    primaryProvider: string;
+    source: RegistrySource | 'legacy';
+    /** True when there is no registry entry and we fell back to the in-repo layout. */
+    isLegacy: boolean;
+}
+export interface ResolveOptions {
+    /** When true, allocate + persist an entry if none exists. Readers pass false. */
+    allocate?: boolean;
+    /** Who is allocating (only consulted when allocate=true). Default 'core-standalone'. */
+    allocator?: RegistrySource;
+    /** Override `$HOME` (tests). Default `os.homedir()`. */
+    home?: string;
+    /** Providers to record on allocation. Default ['claude']. */
+    providers?: string[];
+    coreVersion?: string;
+    desktopProjectId?: string;
+    /** Override timestamp (tests). */
+    now?: string;
+}
+/**
+ * Slug derivation — byte-identical to specrails-desktop's `slugify`
+ * (`server/desktop-router.ts`). Do not "improve" it; parity is the contract.
+ */
+export declare function slugify(name: string): string;
+/** `$HOME` for the registry, overridable for tests. */
+export declare function resolveHome(home?: string): string;
+/** Absolute path to `registry.json`. */
+export declare function registryPath(home?: string): string;
+/**
+ * Absolute path to the versioned framework store
+ * (`<home>/.specrails/framework`). The bundled-framework split materializes the
+ * provider-invariant subtree to `<frameworkDir>/<version>/<providerDir>/` once
+ * and every workspace symlinks `<frameworkDir>/current/<providerDir>/...`. Shares
+ * the SAME home as the registry so framework, registry, and workspaces co-locate
+ * (and tests pinning `SPECRAILS_REGISTRY_HOME` redirect all three together).
+ */
+export declare function frameworkRoot(home?: string): string;
+/** Absolute path to the advisory lock file. */
+export declare function lockPath(home?: string): string;
+/** `fs.realpathSync` that falls back to the resolved-but-unreal path on error
+ *  (the path may not exist yet, or be on a volume that rejects realpath). */
+export declare function realpathSafe(abs: string): string;
+/** Case-fold the key on case-insensitive platforms (macOS, Windows) so two
+ *  spellings of the same path map to one entry. The stored `repoPath` keeps
+ *  its canonical case; only the index key is folded. */
+export declare function normalizeKey(canon: string): string;
+/** Canonical repo path: resolve to absolute, then realpath (collapses symlinks). */
+export declare function canonicalizeRepoPath(repoPathInput: string): string;
+/** The per-project sub-path layout under a workspace dir. Single source of the
+ *  layout so writer and (allocation) reader never disagree. */
+export declare function workspaceLayout(home: string, slug: string, canon: string, primaryProvider?: string): Omit<ProjectEntry, 'providers' | 'primaryProvider' | 'coreVersion' | 'createdAt' | 'lastInstallAt' | 'source' | 'desktopProjectId'>;
+/** The in-repo layout, used when there is no registry entry (legacy fallback). */
+export declare function legacyResolution(canon: string): Resolution;
+/** Flatten a stored entry into a Resolution. */
+export declare function entryToResolution(key: string, entry: ProjectEntry): Resolution;
+/**
+ * Total, fail-open read. A missing file, a parse error, or a `schemaVersion`
+ * greater than we understand all yield an empty registry, so a caller treats
+ * it as "no entry" and (if allocating) writes a fresh, understood entry rather
+ * than crashing. Biases toward availability over strict consistency — correct
+ * for a local, inspectable file.
+ */
+export declare function readRegistryOrEmpty(home?: string): RegistryFile;
+/** Write `data` to `filePath` atomically: temp file in the same dir, fsync,
+ *  rename. A reader (even without the lock) only ever sees a complete old or
+ *  new file — the lock serialises writers, the rename protects readers. */
+export declare function atomicWrite(filePath: string, data: string): void;
+/**
+ * Run `fn` while holding an advisory lock over the registry. Mutual exclusion
+ * is an exclusive-create lock file (`open(..., 'wx')`) with bounded spin-retry
+ * and stale-lock breaking (a lock whose mtime exceeds the TTL is reclaimed —
+ * covers a crashed writer). Read-only callers never take the lock.
+ */
+export declare function withFileLock<T>(home: string | undefined, fn: () => T): T;
+/** Deterministic slug allocation: basename-derived, `-N` dedup suffix. Both
+ *  tools implement this identically so they only ever diverge on the suffix,
+ *  which read-before-allocate resolves. */
+export declare function allocateSlug(canon: string, existing: ReadonlySet<string>): string;
+/**
+ * The shared resolver both tools run. Given a repo path, returns where that
+ * repo's artifacts live. With `allocate:true`, creates + persists an entry when
+ * none exists (under the lock, with a re-read double-check); readers pass
+ * `allocate:false` and fall back to the in-repo legacy layout when absent.
+ */
+export declare function resolveArtifacts(repoPathInput: string, opts?: ResolveOptions): Resolution;
+/** Commit version metadata only after successful materialization and assembly.
+ * Desktop-owned entries remain the host's responsibility; never claim ownership.
+ */
+export declare function recordSuccessfulInstall(repoPath: string, opts: Pick<ResolveOptions, 'home' | 'providers' | 'coreVersion' | 'now'>): void;

package/dist/installer/util/template.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Small in-house template renderer. Replaces the bash heredocs the
+ * retired install.sh / update.sh used to emit manifests and config
+ * files.
+ *
+ * Syntax (intentionally minimal):
+ *   ${VAR_NAME}                  — value interpolation
+ *   {{#if FLAG}}block{{/if}}     — conditional block, rendered when
+ *                                  FLAG is truthy in the context
+ *   {{#ifnot FLAG}}block{{/ifnot}} — conditional block when FLAG is falsy
+ *
+ * Nested blocks are NOT supported. If a template outgrows this
+ * capability we switch to mustache — but every heredoc we've audited
+ * fits inside these three forms.
+ */
+export type TemplateContext = Record<string, string | boolean | number | null | undefined>;
+/**
+ * Renders `template` by evaluating its directives against `context`.
+ * Missing interpolation variables render as the empty string rather
+ * than throwing — the bash scripts behaved the same way (`${X:-}` in
+ * a heredoc). Unknown flags in an `{{#if}}` are treated as falsy.
+ */
+export declare function render(template: string, context: TemplateContext): string;

package/docs/README.md

@@ -18,6 +18,7 @@ Welcome to the SpecRails docs. This guide will take you from zero to a fully aut
 | [Plugin Architecture](plugin-architecture.md) | Plugin vs scaffold, what lives where, how updates work |
 | [Agents](agents.md) | Every agent explained — role, when it runs, why it exists |
 | [Workflows & Commands](workflows.md) | How to use `/specrails:implement`, `/specrails:get-backlog-specs`, and more |
+| [Programmatic Agent Runtime](agent-runtime.md) | LangGraph phases, Claude/Codex/Gemini/Kimi and local providers, CLI/API configuration, recovery and host delivery |
 | [Customization](customization.md) | Adapt agents, rules, personas, and conventions to your project |
 | [Updating](updating.md) | Keep SpecRails up to date without losing your customizations |