codebyplan 1.13.64 → 1.13.66

package/dist/lib/settings-merge.d.ts

@@ -0,0 +1,268 @@
+/**
+ * Settings.json hook-merge engine.
+ *
+ * The source-of-truth is `templates/hooks/hooks.json` — the nested
+ * Claude Code spec shape (`hooks.<event>[].matcher`, each containing a
+ * `hooks[]` of `{type, command}` command-entries with no provenance fields).
+ *
+ * On install:
+ *   - Walk every command-entry across every event/matcher block
+ *   - Tag each entry with `_owner: "codebyplan-claude"` + a `_hook_id`
+ *     derived from the script filename in the command string
+ *   - Rewrite the `${CLAUDE_PLUGIN_ROOT}/hooks/<file>` placeholder to the
+ *     repo-local `./.claude/hooks/<file>` path
+ *   - Upsert into the user's `.claude/settings.json` by `_hook_id` within
+ *     the SAME matcher block, preserving every non-owned entry byte-for-byte
+ *
+ * On uninstall: strip every entry whose `_owner === "codebyplan-claude"`,
+ * collapse now-empty matcher blocks and event arrays, drop a now-empty
+ * `hooks` key.
+ *
+ * Crucially, the SOURCE `hooks.json` is never mutated — placeholder rewrite
+ * and tagging happen at merge time on a structural clone of each command-entry.
+ */
+export declare const OWNER = "codebyplan-claude";
+/**
+ * Marks monorepo-internal hook registrations (e.g. cbp-canonical-templates-nudge.sh
+ * PreToolUse, verify-parity.sh SessionStart) that live ONLY in the canonical monorepo's
+ * .claude/settings.json and are intentionally absent from templates/hooks/hooks.json.
+ *
+ * Because stripOwnedHooksFromSettings strips `_owner === OWNER` and
+ * pruneMissingManagedHooks prunes `_owner === OWNER`, a distinct owner string is
+ * preserved through every managed-hook pass — so these internal registrations survive
+ * a strip+remerge cycle.
+ *
+ * Do NOT add INTERNAL_OWNER to any strip/prune allow-list — its distinctness IS the
+ * mechanism.
+ */
+export declare const INTERNAL_OWNER = "codebyplan-monorepo-internal";
+/**
+ * A single command-entry inside the nested Claude Code hook shape.
+ * Source entries (from templates/hooks/hooks.json) carry only `type` and
+ * `command`; entries written into settings.json by this merger ALSO carry
+ * `_owner` + `_hook_id` so uninstall can distinguish them from user-authored
+ * entries.
+ */
+export interface InnerHookCommand {
+    _owner?: string;
+    _hook_id?: string;
+    type: string;
+    command: string;
+    [extra: string]: unknown;
+}
+export interface MatcherBlock {
+    /** Optional: absent for event-level hooks e.g. UserPromptSubmit */
+    matcher?: string;
+    hooks: InnerHookCommand[];
+}
+export type HooksByEvent = Record<string, MatcherBlock[]>;
+/**
+ * Shape of a `statusLine` or `subagentStatusLine` entry. Both use the same
+ * structure — a command renderer invoked by Claude Code outside the hook
+ * lifecycle. Optional fields (`padding`, `refreshInterval`,
+ * `hideVimModeIndicator`) are preserved when present in user settings.
+ */
+export interface StatusLineSetting {
+    type: string;
+    command: string;
+    padding?: number;
+    refreshInterval?: number;
+    hideVimModeIndicator?: boolean;
+}
+export interface Settings {
+    hooks?: HooksByEvent;
+    statusLine?: StatusLineSetting;
+    subagentStatusLine?: StatusLineSetting;
+    enabledPlugins?: Record<string, boolean>;
+    [otherKey: string]: unknown;
+}
+export interface HooksJson {
+    hooks: HooksByEvent;
+}
+/**
+ * Shape of `templates/settings.project.base.json` — the top-level (non-hooks)
+ * settings the package owns. Every field is optional so the template can grow
+ * without forcing churn in this type.
+ *
+ * Scope comments:
+ *   // common       — appears in settings.project.base.json AND available for user settings
+ *   // project-only — appears in settings.project.base.json only (CBP project conventions)
+ *   // user-only    — NOT in settings.project.base.json; populated by user settings (e.g. TASK-3)
+ */
+export interface BaseSettings {
+    alwaysThinkingEnabled?: boolean;
+    autoUpdatesChannel?: string;
+    awaySummaryEnabled?: boolean;
+    disableAgentView?: boolean;
+    editorMode?: string;
+    outputStyle?: string;
+    preferredNotifChannel?: string;
+    prefersReducedMotion?: boolean;
+    respectGitignore?: boolean;
+    showTurnDuration?: boolean;
+    spinnerTipsEnabled?: boolean;
+    terminalProgressBarEnabled?: boolean;
+    viewMode?: string;
+    worktree?: {
+        baseRef?: string;
+        [k: string]: unknown;
+    };
+    autoScrollEnabled?: boolean;
+    cleanupPeriodDays?: number;
+    includeGitInstructions?: boolean;
+    showThinkingSummaries?: boolean;
+    disableSkillShellExecution?: boolean;
+    skipWebFetchPreflight?: boolean;
+    fastModePerSessionOptIn?: boolean;
+    autoMemoryEnabled?: boolean;
+    effortLevel?: string;
+    statusLine?: StatusLineSetting;
+    subagentStatusLine?: StatusLineSetting;
+    permissions?: {
+        defaultMode?: string;
+        deny?: string[];
+        ask?: string[];
+        allow?: string[];
+        skipDangerousModePermissionPrompt?: boolean;
+    };
+    attribution?: {
+        commit?: string;
+        pr?: string;
+    };
+    showClearContextOnPlanAccept?: boolean;
+    syntaxHighlightingDisabled?: boolean;
+}
+/**
+ * Merge the hook entries from `hooksJson` into `settings.hooks`, tagging each
+ * with the codebyplan-claude owner marker and rewriting the path placeholder.
+ *
+ * Returns the same `settings` reference (mutated in place) for caller
+ * convenience. The source `hooksJson` is NOT mutated — each command-entry is
+ * cloned before being tagged.
+ *
+ * Upsert semantics: within a single matcher block (same event, same matcher
+ * string), entries are keyed by `_hook_id`. An owned entry with a matching
+ * `_hook_id` is replaced in place (preserving its index); otherwise the new
+ * owned entry is appended. Non-owned entries (`_owner !== OWNER`) are NEVER
+ * touched — they stay at their original index.
+ */
+export declare function mergeHooksIntoSettings(settings: Settings, hooksJson: HooksJson): Settings;
+/**
+ * Merge top-level non-hook settings from `base` into `settings`. Semantics are
+ * conservative — the install must never clobber a user-customised value:
+ *
+ *   - Scalar fields (21 scalar-common + 3 project-only) in SCALAR_BASE_KEYS: set
+ *     only if absent. `worktree` is the 22nd common field and is handled
+ *     separately below via per-sub-key filling.
+ *   - `statusLine`: set only if absent (object, deep-set as a unit)
+ *   - `subagentStatusLine`: set only if absent (object, deep-set as a unit)
+ *   - `attribution`: set only if absent (object, deep-set as a unit)
+ *   - `worktree`: if absent, deep-clone base.worktree; if present, fill each
+ *     sub-key individually iff absent in settings.worktree
+ *   - `permissions.defaultMode`: set only if absent
+ *   - `permissions.skipDangerousModePermissionPrompt`: set only if absent
+ *   - `permissions.deny` / `permissions.ask` / `permissions.allow`: cross-tier
+ *     reconciliation followed by union (see scoped exception below).
+ *
+ * Cross-tier reconciliation (scoped exception to the otherwise union-only contract):
+ *   Before the union loop, a map is built from every entry in base.permissions.*
+ *   to its canonical tier. Any entry in the user's existing array that appears
+ *   in the map AND is sitting in the WRONG tier is removed from that array. The
+ *   subsequent union loop then places it in the correct (canonical) tier. This
+ *   enables both promotion (allow→ask) and demotion (ask→allow) for base-owned
+ *   entries. The removal is STRICTLY SCOPED: entries that are NOT present in any
+ *   base array (user-authored entries and legacy specifics such as
+ *   `Bash(git add .:*)` / `Bash(git add -A:*)`) are NEVER removed — the
+ *   union-only behavior is preserved for all non-base entries.
+ *
+ * Returns the same `settings` reference (mutated in place). Source `base` is
+ * NOT mutated — each StatusLineSetting is shallow-cloned before assignment,
+ * and the `permissions.deny` / `ask` / `allow` arrays are read-only iterated
+ * into a fresh `merged` array (never pushed into), so later mutations to
+ * `settings.statusLine` / `settings.subagentStatusLine` / `settings.permissions.*`
+ * do not bleed back into the template. Mirrors the clone-source guarantee
+ * documented on `mergeHooksIntoSettings`.
+ */
+export declare function mergeBaseSettingsIntoSettings(settings: Settings, base: BaseSettings): Settings;
+/**
+ * Strip package-owned top-level settings from `settings`, given the same `base`
+ * template the installer merged in. Conservative — only removes a field when
+ * it byte-equals the package default, so any user customisation is preserved:
+ *
+ *   - Scalar fields (21 scalar-common + 3 project-only) in SCALAR_BASE_KEYS:
+ *     deleted iff byte-equal to base value. `worktree` is the 22nd common field
+ *     and is handled separately below.
+ *   - `statusLine`: deleted iff deep-equal to `base.statusLine`
+ *   - `subagentStatusLine`: deleted iff deep-equal to `base.subagentStatusLine`
+ *   - `attribution`: deleted iff deep-equal to `base.attribution`
+ *   - `worktree`: each sub-key deleted iff equal to base sub-key; if worktree
+ *     becomes `{}` the key itself is deleted
+ *   - `permissions.defaultMode`: deleted iff equal to `base.permissions.defaultMode`
+ *   - `permissions.skipDangerousModePermissionPrompt`: deleted iff byte-equal
+ *   - `permissions.deny` / `permissions.ask` / `permissions.allow`: cross-tier
+ *     strip — every base-owned entry (present in ANY base array) is filtered out
+ *     of EVERY consumer array, regardless of which tier it currently sits in, so
+ *     a base entry that drifted into the wrong tier is still removed on uninstall
+ *     (mirrors the cross-tier reconciliation in mergeBaseSettingsIntoSettings).
+ *     User-added entries (absent from all base arrays) are preserved. An empty
+ *     array post-filter is dropped entirely.
+ *   - `permissions`: dropped entirely once it has no remaining keys.
+ *
+ * Returns the same `settings` reference (mutated in place).
+ */
+export declare function stripBaseSettingsFromSettings(settings: Settings, base: BaseSettings): Settings;
+/**
+ * Merge LSP plugin IDs into `settings.enabledPlugins`.
+ *
+ * For each plugin id in `plugins`, computes the settings key as
+ * `${plugin}@claude-plugins-official` and sets it to `true` ONLY when the key
+ * is absent from settings.enabledPlugins. Existing entries (true OR false) are
+ * never clobbered — a user who explicitly disabled a plugin (false) keeps that.
+ *
+ * Initializes `settings.enabledPlugins` to `{}` if undefined.
+ *
+ * NOTE: the uninstall strip path in `stripBaseSettingsFromSettings` does NOT
+ * touch `enabledPlugins` — LSP entries are intentionally left in place after
+ * uninstall. The user opted in by running `codebyplan lsp`; stripping the
+ * plugins on uninstall would silently degrade their editor experience.
+ *
+ * Returns the same `settings` reference (mutated in place).
+ */
+export declare function mergeEnabledPluginsIntoSettings(settings: Settings, plugins: string[]): Settings;
+/**
+ * Strip every command-entry whose `_owner === OWNER` from `settings.hooks`.
+ * Empty matcher blocks, empty event arrays, and a now-empty `hooks` object
+ * are pruned so the resulting settings.json is shaped like an unmodified
+ * user-only file.
+ *
+ * Returns the same `settings` reference (mutated in place).
+ */
+export declare function stripOwnedHooksFromSettings(settings: Settings): Settings;
+/**
+ * Remove managed hook entries whose `_hook_id` is no longer present in the
+ * current `hooksJson` template. Called immediately after `mergeHooksIntoSettings`
+ * on install and update so that hooks removed from the package template do not
+ * persist forever in consuming repos' settings.json.
+ *
+ * Semantics:
+ *   - Builds a per-event map of live `_hook_id` values by iterating every
+ *     event/matcher/command in `hooksJson` using the same `extractHookId`
+ *     the merge uses. Per-event keying ensures a hook id that moved from
+ *     one event to another is correctly pruned from the OLD event.
+ *   - In each event/matcher block, removes an entry ONLY when ALL of these
+ *     hold: `e._owner === OWNER`, `e._hook_id !== undefined`, and the id is
+ *     NOT in the per-event live set (events absent from the template get an
+ *     empty set, so all their owned entries are pruned).
+ *   - Calls `onPruned(hookId)` for each removed entry (optional callback —
+ *     used for verbose logging in install/update callers).
+ *   - Collapses now-empty blocks and event keys via `collapseEmptyHookBlocks`.
+ *
+ * Guarantees:
+ *   - NEVER removes a non-owned entry or an owned entry with undefined `_hook_id`.
+ *   - NEVER mutates `hooksJson`.
+ *   - Idempotent: a second call with the same arguments produces no further changes.
+ *
+ * Returns the same `settings` reference (mutated in place).
+ */
+export declare function pruneMissingManagedHooks(settings: Settings, hooksJson: HooksJson, onPruned?: (hookId: string) => void): Settings;
+//# sourceMappingURL=settings-merge.d.ts.map

package/dist/lib/settings-merge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings-merge.d.ts","sourceRoot":"","sources":["../../src/lib/settings-merge.ts"],"names":[],"mappings":"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"}

package/dist/lib/ship.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Pure library: ship a feat branch to production via PR.
+ *
+ * Reads branch_config from .codebyplan/git.json to determine the base/production
+ * branch. Handles all git/gh mechanics: push, PR create-or-reuse, checks poll,
+ * merge, verify, cleanup.
+ *
+ * dryRun: true short-circuits BEFORE any mutating call (no push/create/merge/delete).
+ * Read-only operations (fetch, pr list, pr checks) may still run in dry-run for
+ * representative output.
+ */
+import { type BumpEntry } from "./bump.js";
+export type ShipOptions = {
+    /** Skip all mutating operations; return a representative dry-run result. */
+    dryRun?: boolean;
+    /** Write JSON to stdout. */
+    json?: boolean;
+    /** Do not delete the feat branch after merge. */
+    keepFeat?: boolean;
+    /**
+     * Path to a file containing the PR body markdown.
+     * If omitted, a default body is generated from the branch name.
+     */
+    bodyFile?: string;
+    /**
+     * Maximum seconds to poll gh pr checks before aborting. Default: 600.
+     */
+    timeoutSeconds?: number;
+    /** Override cwd for testing. */
+    cwd?: string;
+    /**
+     * Injectable sleep function for testing (avoids real timer waits).
+     * Defaults to real setTimeout-based sleep in production.
+     * @internal
+     */
+    _sleepMs?: (ms: number) => Promise<void>;
+    /** Patch-bump changed packages before push. Default: true. */
+    bump?: boolean;
+};
+export type ShipResult = {
+    pr_url: string;
+    merge_commit: string | null;
+    branch_deleted: boolean;
+    /** Present when dryRun=true. */
+    dry_run?: boolean;
+    /** Present when required checks failed. */
+    checks_failed?: boolean;
+    checks_failure_reason?: string;
+    feat_branch?: string;
+    base_branch?: string;
+    /** Bump entries from runBump (present when bump was attempted). */
+    bumps?: BumpEntry[];
+};
+type CheckEntry = {
+    name: string;
+    state: string;
+    bucket: string;
+};
+/**
+ * Evaluate a set of gh pr checks entries using the gh bucket model.
+ *
+ * gh pr checks returns a `bucket` field per check with one of:
+ *   pass | fail | pending | skipping | cancel
+ *
+ * Decision table (fail-safe):
+ *   - fail / cancel → block merge (returned in `failed[]`)
+ *   - pass / skipping → do NOT block (treated as passing)
+ *   - pending → wait for completion
+ *   - unknown / unrecognized / empty bucket → block merge (fail-safe; returned in `failed[]`)
+ *     A check is non-blocking ONLY when its bucket is explicitly "pass" or "skipping".
+ *     Any bucket value that is not in {pass, skipping, pending} — including future gh
+ *     bucket values and empty strings — is treated as blocking to prevent a fail-open merge.
+ *
+ * This is the canonical evaluator for pollChecks and is mirrored by the
+ * cbp-supabase-branch-check skill.
+ */
+export declare function evaluateChecks(checks: CheckEntry[]): {
+    passed: boolean;
+    pending: number;
+    failed: string[];
+};
+export declare function runShip(opts?: ShipOptions): Promise<ShipResult>;
+export {};
+//# sourceMappingURL=ship.d.ts.map

package/dist/lib/ship.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ship.d.ts","sourceRoot":"","sources":["../../src/lib/ship.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAMH,OAAO,EAAW,KAAK,SAAS,EAAE,MAAM,WAAW,CAAC;AAMpD,MAAM,MAAM,WAAW,GAAG;IACxB,4EAA4E;IAC5E,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,4BAA4B;IAC5B,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,iDAAiD;IACjD,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;OAEG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,gCAAgC;IAChC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,QAAQ,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACzC,8DAA8D;IAC9D,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,cAAc,EAAE,OAAO,CAAC;IACxB,gCAAgC;IAChC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,2CAA2C;IAC3C,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mEAAmE;IACnE,KAAK,CAAC,EAAE,SAAS,EAAE,CAAC;CACrB,CAAC;AA0BF,KAAK,UAAU,GAAG;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,UAAU,EAAE,GAAG;IACpD,MAAM,EAAE,OAAO,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB,CASA;AA2HD,wBAAsB,OAAO,CAAC,IAAI,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CAySrE"}

package/dist/lib/slug.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Canonical branch slug helper.
+ *
+ * Replicates the slug rules from cbp-task-start Step 3.1:
+ *   lowercase → split on whitespace/punctuation → drop non-alphanumerics →
+ *   dash-join → truncate to 40 chars (no trailing dash after truncate).
+ *
+ * Handles bash-glob footgun titles safely: "[param] routes", "(group) layout",
+ * titles with slashes, quotes, unicode, and consecutive separators.
+ *
+ * No I/O — pure transform.
+ */
+/**
+ * Convert a human title to a git-safe branch slug.
+ *
+ * - Lowercase
+ * - Non-alphanumeric characters (including brackets, parens, slashes, quotes,
+ *   unicode combining marks, etc.) are treated as separators and replaced with
+ *   a single dash in the output
+ * - Consecutive separators collapse to a single dash
+ * - Leading/trailing dashes are stripped
+ * - Truncated to MAX_LENGTH characters with no trailing dash
+ * - Empty input → ""
+ */
+export declare function slugify(title: string): string;
+//# sourceMappingURL=slug.d.ts.map

package/dist/lib/slug.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"slug.d.ts","sourceRoot":"","sources":["../../src/lib/slug.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH;;;;;;;;;;;GAWG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAwB7C"}

package/dist/lib/spawn.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `spawnSyncOrThrow` — run a command with an argv array (NO shell, so no
+ * command-injection surface) while preserving execSync-like ergonomics:
+ * throw on a spawn error or a non-zero exit, otherwise return stdout as a string.
+ *
+ * Use this anywhere a `git`/`gh`/etc. invocation previously used
+ * `execSync(`cmd ${interpolated}`)` — the interpolated value can no longer reach
+ * a shell. The no-restricted-syntax lint rule enforces this package-wide.
+ */
+import { type SpawnSyncOptions } from "node:child_process";
+export declare function spawnSyncOrThrow(file: string, args: string[], opts?: SpawnSyncOptions): string;
+//# sourceMappingURL=spawn.d.ts.map

package/dist/lib/spawn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spawn.d.ts","sourceRoot":"","sources":["../../src/lib/spawn.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAa,KAAK,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAEtE,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EAAE,EACd,IAAI,GAAE,gBAAqB,GAC1B,MAAM,CAaR"}

package/dist/lib/state-client.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Backend write HTTP client for the local-first state layer.
+ *
+ * Provides `apiBackendPost` and `apiBackendPatch` for the NestJS backend at
+ * `getBackendBase()` (CODEBYPLAN_BACKEND_URL ?? "https://api.codebyplan.com").
+ * Auth is via `getAuthHeaders()` (OAuth bearer or legacy API key).
+ *
+ * Throws `BackendError` on non-2xx responses so callers can distinguish
+ * 4xx (reject-reconcile: revert local) from 5xx (keep local + write _pending/).
+ *
+ * 409 Conflict is surfaced distinctly via `isConflict` so callers implementing
+ * OCC retry loops can detect it without inspecting the raw status code.
+ */
+/**
+ * Thrown by `apiBackendPost` / `apiBackendPatch` on non-2xx responses.
+ * Callers should inspect `status` to decide reconciliation strategy:
+ *   - 4xx → reject: revert the optimistic local write
+ *   - 5xx → degrade: keep local, write `_pending/<id>.json` marker
+ *   - 409 specifically → OCC conflict: re-read row and retry (use isConflict)
+ */
+export declare class BackendError extends Error {
+    status: number;
+    constructor(message: string, status: number);
+}
+/**
+ * Returns true when the thrown error is a BackendError with status 409.
+ *
+ * Use in OCC retry loops:
+ *
+ * ```ts
+ * try {
+ *   await apiBackendPatch(path, body);
+ * } catch (err) {
+ *   if (isConflict(err)) {
+ *     // re-read the row, merge intent, retry
+ *   }
+ *   throw err;
+ * }
+ * ```
+ */
+export declare function isConflict(err: unknown): err is BackendError;
+/**
+ * POST to the NestJS backend.
+ * @throws {BackendError} on non-2xx response
+ * @throws {Error} on network / timeout failure
+ */
+export declare function apiBackendPost<T>(path: string, body: unknown): Promise<T>;
+/**
+ * PATCH to the NestJS backend.
+ * @throws {BackendError} on non-2xx response (including 409 Conflict — use isConflict())
+ * @throws {Error} on network / timeout failure
+ */
+export declare function apiBackendPatch<T>(path: string, body: unknown): Promise<T>;
+//# sourceMappingURL=state-client.d.ts.map

package/dist/lib/state-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-client.d.ts","sourceRoot":"","sources":["../../src/lib/state-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAWH;;;;;;GAMG;AACH,qBAAa,YAAa,SAAQ,KAAK;IACrC,MAAM,EAAE,MAAM,CAAC;gBAEH,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAK5C;AAMD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,YAAY,CAE5D;AAkDD;;;;GAIG;AACH,wBAAsB,cAAc,CAAC,CAAC,EACpC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,OAAO,GACZ,OAAO,CAAC,CAAC,CAAC,CAEZ;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CAAC,CAAC,EACrC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,OAAO,GACZ,OAAO,CAAC,CAAC,CAAC,CAEZ"}

package/dist/lib/state-store.d.ts

@@ -0,0 +1,153 @@
+/**
+ * @module state-store
+ *
+ * Core read/write layer for the `.codebyplan/state/` local mirror.
+ *
+ * ## Directory layout
+ *
+ * ```
+ * .codebyplan/state/
+ *   _cursor.json                                  — sync cursor (seq + hash map)
+ *   checkpoints/<checkpointId>.json               — checkpoint row
+ *   checkpoints/<checkpointId>/
+ *     tasks/<taskId>.json                         — task row
+ *     tasks/<taskId>/
+ *       rounds/<roundId>.json                     — round row
+ *   standalone_tasks/<taskId>.json                — standalone task row (FLAT,
+ *                                                   no checkpoint partitioning;
+ *                                                   write-through only — not
+ *                                                   hydrated by runSync)
+ *   session/
+ *     current.json                                — active session_log row
+ *     state.json                                  — session_state row (write-through-only;
+ *                                                   populated by `codebyplan session update-state`;
+ *                                                   never written by runSync — session_state is
+ *                                                   not a sync_seq table and is absent from /sync)
+ *   todos.json                                    — todos snapshot
+ *   _pending/
+ *     <entityId>.json                             — pending-write marker (5xx path)
+ * ```
+ *
+ * ## Server-side deletion propagation
+ *
+ * `pruneEntityTree` runs on full hydrate (`since=0`) to drop entities absent
+ * from the server response. Delta syncs (warm path) propagate server-side
+ * removals via tombstones: the backend `/sync` endpoint returns a `deleted[]`
+ * array (sourced from the `sync_tombstones` table + after-delete triggers), and
+ * `runSync` prunes the matching local per-id files on every delta — not only on
+ * `--full` (CHK-222 TASK-4).
+ *
+ * ## Write-through-only fields
+ *
+ * `session/state.json` is WRITE-THROUGH-ONLY: it is populated solely by
+ * `codebyplan session update-state` (which PATCHes the backend and overwrites
+ * the local file with the server response). `runSync` never hydrates it — the
+ * `/sync` endpoint does not return session_state because it is not a sync_seq
+ * table. A future local-first `get_session_state` reader (TASK-7/8) must not
+ * assume `sync --full` populates `session/state.json`.
+ *
+ * `port_allocations` is present in every `/sync` payload (it IS a sync_seq table)
+ * but `runSync` intentionally does NOT mirror it to `.codebyplan/state/`. Port
+ * allocations are managed by `codebyplan ports` and persisted to
+ * `server.json`/`server.local.json`. Persisting them a second time under
+ * `state/` would create a second source of truth for port data.
+ *
+ * ## Advisory / non-fatal contract
+ *
+ * All functions swallow errors and warn to stderr. A state-store failure
+ * must never abort the caller's primary work (MCP write, sync invocation, etc.).
+ */
+/**
+ * Sync cursor stored at `.codebyplan/state/_cursor.json`.
+ * Tracks the last successfully synced sequence number and per-entity
+ * content hashes (sha256 of JSON.stringify(row)) for change detection.
+ */
+export interface Cursor {
+    /** Last `max_seq` value returned by the backend `/sync` endpoint. */
+    sync_seq: number;
+    /** ISO-8601 timestamp of the last successful sync. */
+    synced_at: string;
+    /**
+     * Map of entity_id → sha256(JSON.stringify(row)).
+     * Used to detect whether a local file is up-to-date without re-reading
+     * every file on every delta sync.
+     */
+    entity_hashes: Record<string, string>;
+    /** `synced` = all pages complete; `partial` = interrupted mid-sync. */
+    sync_status: "synced" | "partial";
+}
+export declare function checkpointPath(repoRoot: string, checkpointId: string): string;
+export declare function taskPath(repoRoot: string, checkpointId: string, taskId: string): string;
+export declare function roundPath(repoRoot: string, checkpointId: string, taskId: string, roundId: string): string;
+export declare function standaloneTaskPath(repoRoot: string, taskId: string): string;
+export declare function sessionLogPath(repoRoot: string): string;
+export declare function todosPath(repoRoot: string): string;
+/**
+ * Absolute path to the `_pending/` outbox directory under `.codebyplan/state/`.
+ * Pending-write markers (5xx path) are stored here as `<entityId>.json`.
+ * Use `listEntityFiles(pendingDir(repoRoot))` to scan for markers to replay.
+ */
+export declare function pendingDir(repoRoot: string): string;
+export declare function pendingMarkerPath(repoRoot: string, entityId: string): string;
+/**
+ * Compute sha256(serializeEntity(row)) for entity_hashes tracking.
+ * Uses the same pretty-printed + trailing-newline form as writeEntityFile
+ * so hashes are byte-identical whether produced by the sync path or the
+ * CLI-verb path.
+ */
+export declare function hashEntity(row: unknown): string;
+/**
+ * Read the sync cursor from `.codebyplan/state/_cursor.json`.
+ * Returns `null` (silently) when absent or corrupt.
+ * Never throws.
+ */
+export declare function readCursor(repoRoot: string): Promise<Cursor | null>;
+/**
+ * Write the sync cursor to `.codebyplan/state/_cursor.json`.
+ * Creates the state directory recursively if absent.
+ * Never throws; errors are swallowed with a stderr warning.
+ */
+export declare function writeCursor(repoRoot: string, cursor: Cursor): Promise<void>;
+/**
+ * Read an entity file at the given absolute path.
+ * Returns `null` when absent (ENOENT) or when JSON parse fails.
+ * Never throws.
+ */
+export declare function readEntityFile<T = unknown>(filePath: string): Promise<T | null>;
+/**
+ * Write an entity row to `filePath`, creating parent directories recursively.
+ * Also computes and returns the sha256 hash of the serialized row.
+ * Never throws; errors are swallowed with a stderr warning.
+ */
+export declare function writeEntityFile(filePath: string, row: unknown): Promise<string>;
+/**
+ * Delete an entity file at `filePath`.
+ * Silently ignores ENOENT. Never throws.
+ */
+export declare function deleteEntityFile(filePath: string): Promise<void>;
+/**
+ * List all `.json` files recursively under `dirPath`.
+ * Returns an empty array when the directory does not exist.
+ * Never throws.
+ */
+export declare function listEntityFiles(dirPath: string): Promise<string[]>;
+/**
+ * Tables tracked in the local state mirror.
+ */
+export type StateTable = "checkpoints" | "tasks" | "rounds" | "session_logs" | "todos";
+/**
+ * Remove local entity files whose IDs are absent from the server's hydrate
+ * response. Only called on full hydrate (since=0); delta syncs never prune.
+ *
+ * `knownIdsByTable` maps each table name to the set of IDs the backend returned.
+ * Any local file whose basename (without `.json`) is not in the known set is
+ * deleted. The `_cursor.json`, `_pending/`, and top-level collection files
+ * (`todos.json`) are handled separately and are NOT pruned
+ * by per-table ID matching.
+ *
+ * Never throws.
+ */
+export declare function pruneEntityTree(repoRoot: string, knownIdsByTable: Partial<Record<StateTable, Set<string>>>): Promise<{
+    pruned: string[];
+}>;
+//# sourceMappingURL=state-store.d.ts.map

package/dist/lib/state-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-store.d.ts","sourceRoot":"","sources":["../../src/lib/state-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AAkBH;;;;GAIG;AACH,MAAM,WAAW,MAAM;IACrB,qEAAqE;IACrE,QAAQ,EAAE,MAAM,CAAC;IACjB,sDAAsD;IACtD,SAAS,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,uEAAuE;IACvE,WAAW,EAAE,QAAQ,GAAG,SAAS,CAAC;CACnC;AAcD,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAE7E;AAED,wBAAgB,QAAQ,CACtB,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM,GACb,MAAM,CAQR;AAED,wBAAgB,SAAS,CACvB,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,GACd,MAAM,CAUR;AAED,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAE3E;AAED,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAElD;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE5E;AAkBD;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAE/C;AAMD;;;;GAIG;AACH,wBAAsB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAczE;AAED;;;;GAIG;AACH,wBAAsB,WAAW,CAC/B,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC,CAUf;AAMD;;;;GAIG;AACH,wBAAsB,cAAc,CAAC,CAAC,GAAG,OAAO,EAC9C,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAanB;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,OAAO,GACX,OAAO,CAAC,MAAM,CAAC,CAYjB;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAWtE;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAaxE;AA8BD;;GAEG;AACH,MAAM,MAAM,UAAU,GAClB,aAAa,GACb,OAAO,GACP,QAAQ,GACR,cAAc,GACd,OAAO,CAAC;AAEZ;;;;;;;;;;;GAWG;AACH,wBAAsB,eAAe,CACnC,QAAQ,EAAE,MAAM,EAChB,eAAe,EAAE,OAAO,CAAC,MAAM,CAAC,UAAU,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,GACxD,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CAmE/B"}