codebyplan 1.13.64 → 1.13.66

package/dist/lib/eslint-generator.d.ts

@@ -0,0 +1,86 @@
+/**
+ * ESLint config generator.
+ *
+ * Takes ordered presets + user overrides and produces a standalone
+ * eslint.config.mjs file. Parses config_fragment TEXT fields from
+ * DB presets, deduplicates imports, and composes the final config.
+ */
+import type { EslintPreset } from "./types.js";
+/**
+ * Test-only hook to clear the module-level warning dedup set between
+ * describe blocks. Tests must call this in `beforeEach` of any block that
+ * relies on warnSpy call counts (Finding #5).
+ */
+export declare function __resetWarnedPresetNamesForTest(): void;
+/**
+ * Return the set of JS identifiers bound by the given import/setup lines.
+ * Used as a pre-emit guard: if the generator is about to emit a config
+ * object that references a binding (e.g., `jsxA11y`, `react`), it must
+ * confirm that binding was actually introduced by some preset's
+ * `config_fragment`. If the DB fragment is edited to drop the binding, the
+ * generator would otherwise emit a reference to an undefined variable and
+ * the generated eslint.config.mjs would throw at load time (Finding #3).
+ *
+ * Recognised forms:
+ *   import X from "..."
+ *   import { X, Y as Z } from "..."
+ *   const X = require("...")
+ */
+export declare function importedIdentifiers(importLines: string[]): Set<string>;
+export interface GeneratorInput {
+    /** Ordered list of resolved presets (display_order ascending). */
+    presets: EslintPreset[];
+    /** User-defined rule overrides to merge on top. */
+    ruleOverrides?: Record<string, unknown>;
+    /** Absolute or relative tsconfigRootDir for parser options. */
+    tsconfigRootDir?: string;
+    /** Files/patterns to ignore (self-ignore + user additions). */
+    ignorePatterns?: string[];
+}
+/**
+ * Collect all npm dependencies required by the given presets.
+ * Returns a Map of packageName -> version constraint.
+ */
+export declare function collectDependencies(presets: EslintPreset[]): Map<string, string>;
+/**
+ * Compute SHA256 hash of config content for drift detection.
+ */
+export declare function hashConfig(content: string): string;
+/**
+ * Classify merged preset rules by key prefix into plugin-scoped buckets so we
+ * can co-locate plugin-scoped rules with the block that registers their
+ * plugin.
+ *
+ * - `reactHooks`: react-hooks/, react-compiler/ — safe to emit in both the
+ *   React block AND the Next.js block (react-compiler is explicitly
+ *   registered in both; react-hooks is registered by the React preset block
+ *   or by eslint-config-next).
+ * - `reactOrA11y`: react/, jsx-a11y/ — registered by the React preset block
+ *   OR by eslint-config-next (undocumented). In the Next.js branch we emit
+ *   these in a SEPARATE trailing object that explicitly registers `jsxA11y`
+ *   and `react` as a defensive measure.
+ * - `importPlugin`: import/ — safe to co-locate inside the Next.js branch,
+ *   since eslint-config-next bundles eslint-plugin-import. When `hasNextJs`
+ *   is false, these keys are routed directly into `generic` at
+ *   classification time so they still land in the standalone overrides
+ *   block (Finding #2). The `hasNextJs` argument is a dependency of the
+ *   classification: import/ routing changes with it.
+ * - `generic`: everything else — emitted in the standalone `// Rule
+ *   overrides` block.
+ *
+ * @param rules - merged preset rules (user overrides already subtracted)
+ * @param hasNextJs - when false, import/* keys route to `generic` bucket instead of `importPlugin`
+ * @returns { reactHooks, reactOrA11y, importPlugin, generic } buckets
+ */
+export interface SplitRules {
+    reactHooks: Record<string, unknown>;
+    reactOrA11y: Record<string, unknown>;
+    importPlugin: Record<string, unknown>;
+    generic: Record<string, unknown>;
+}
+export declare function splitRulesByPlugin(rules: Record<string, unknown>, hasNextJs: boolean): SplitRules;
+/**
+ * Generate a complete eslint.config.mjs file from presets and options.
+ */
+export declare function generateEslintConfig(input: GeneratorInput): string;
+//# sourceMappingURL=eslint-generator.d.ts.map

package/dist/lib/eslint-generator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"eslint-generator.d.ts","sourceRoot":"","sources":["../../src/lib/eslint-generator.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAc/C;;;;GAIG;AACH,wBAAgB,+BAA+B,IAAI,IAAI,CAEtD;AAMD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,GAAG,CAAC,MAAM,CAAC,CAuBtE;AAMD,MAAM,WAAW,cAAc;IAC7B,kEAAkE;IAClE,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,mDAAmD;IACnD,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACxC,+DAA+D;IAC/D,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,+DAA+D;IAC/D,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B;AA8ED;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,YAAY,EAAE,GACtB,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAerB;AAMD;;GAEG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAElD;AA0BD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,WAAW,UAAU;IACzB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,SAAS,EAAE,OAAO,GACjB,UAAU,CAuBZ;AAiBD;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,cAAc,GAAG,MAAM,CAwWlE"}

package/dist/lib/file-lock.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Best-effort cross-process advisory file lock.
+ *
+ * `withFileLock` runs a callback while holding an exclusive on-disk lock.
+ * Acquisition uses `O_EXCL` (the `"wx"` open flag): exactly one process can
+ * create the lock file, so concurrent CLI invocations / hook subprocesses
+ * serialize through it. The original use case is OAuth token refresh — a
+ * rotating refresh token must not be spent by two processes at once.
+ *
+ * Liveness over strictness: a lock whose mtime is older than `staleMs` (the
+ * holder crashed without cleanup) is stolen, and a lock still held at
+ * `timeoutMs` is stolen as a last resort so a wedged lock never deadlocks the
+ * CLI. To keep a steal from corrupting the new holder, release is
+ * OWNERSHIP-CHECKED: each acquire writes a unique holder id into the lock file
+ * and only deletes the lock on release if it still holds that id — so a holder
+ * whose lock was stolen will NOT delete the thief's lock (which would otherwise
+ * let a third waiter run concurrently with the new holder). The lock is always
+ * released in a `finally`, including when the callback throws (the original
+ * error propagates).
+ */
+export interface FileLockOptions {
+    /**
+     * Max time to spend waiting for a live lock before stealing it (ms).
+     * Default 15000.
+     */
+    timeoutMs?: number;
+    /**
+     * A lock whose mtime is older than this is treated as abandoned (holder
+     * crashed) and stolen immediately. Default 30000.
+     */
+    staleMs?: number;
+    /** Poll interval between acquisition attempts (ms). Default 100. */
+    retryMs?: number;
+    /** Injected sleep — tests pass a no-op / fake-timer variant. */
+    sleep?: (ms: number) => Promise<void>;
+    /** Injected clock — tests pass a controllable monotonic source. */
+    now?: () => number;
+}
+/**
+ * Run `fn` while holding an exclusive lock at `lockPath`. Returns whatever `fn`
+ * returns. Never deadlocks: stale and wedged locks are stolen.
+ */
+export declare function withFileLock<T>(lockPath: string, fn: () => Promise<T>, opts?: FileLockOptions): Promise<T>;
+//# sourceMappingURL=file-lock.d.ts.map

package/dist/lib/file-lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-lock.d.ts","sourceRoot":"","sources":["../../src/lib/file-lock.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAOH,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oEAAoE;IACpE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gEAAgE;IAChE,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,mEAAmE;IACnE,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAKD;;;GAGG;AACH,wBAAsB,YAAY,CAAC,CAAC,EAClC,QAAQ,EAAE,MAAM,EAChB,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,IAAI,GAAE,eAAoB,GACzB,OAAO,CAAC,CAAC,CAAC,CAgEZ"}

package/dist/lib/flags.d.ts

@@ -0,0 +1,115 @@
+export interface CliConfig {
+    repoId: string;
+    worktreeId?: string;
+    projectPath: string;
+}
+/**
+ * Walk up from `startDir` looking for the `.codebyplan/repo.json` sentinel
+ * (new layout), falling back to the legacy `.codebyplan.json` for ONE
+ * release window.
+ *
+ * Returns `{ path, contents }` on first hit where `path` is the discovered
+ * file path and `contents` is the parsed JSON (sentinel JSON for new layout,
+ * full JSON for legacy). Returns `null` if the walk exhausts without a match.
+ *
+ * Probe-style: ENOENT (or any read failure) at each level is treated as
+ * "not here, keep walking". The filesystem-root guard (`parent === cursor`)
+ * stops the walk when `..` stops changing.
+ *
+ * CHK-120: sentinel changed from `.codebyplan.json` to `.codebyplan/repo.json`.
+ * Legacy `.codebyplan.json` fallback is present for ONE release window only —
+ * all writers now use the new `.codebyplan/` directory layout.
+ */
+export declare function findCodebyplanConfig(startDir: string, maxDepth?: number): Promise<{
+    path: string;
+    contents: {
+        repo_id?: string;
+        worktree_id?: string;
+    };
+} | null>;
+/**
+ * Parse CLI flags from process.argv (starting at startIndex).
+ */
+export declare function parseFlags(startIndex: number): Record<string, string>;
+/**
+ * Parse CLI flags from an explicit args array (e.g. process.argv.slice(N)).
+ * Supports both value flags (`--key value`) and boolean flags (`--flag`).
+ * Value flags consume the next element when it does not start with `--`.
+ * Boolean flags are collected in a separate Set.
+ */
+export declare function parseFlagsFromArgs(args: string[]): {
+    flags: Record<string, string>;
+    booleans: Set<string>;
+};
+/**
+ * Check if a boolean flag is present.
+ */
+export declare function hasFlag(name: string, startIndex: number): boolean;
+/**
+ * Derive the repo root directory from a `.codebyplan` config file path.
+ *
+ * Strips the config-file suffix to recover the directory that contains
+ * `.codebyplan/` (new multi-file layout) or `.codebyplan.json` (legacy flat
+ * layout). Also handles the bare-directory forms that can appear in edge cases
+ * (e.g. a path ending in `/.codebyplan` or `/.codebyplan/`).
+ *
+ * Supported forms:
+ *   /some/path/.codebyplan/repo.json   → /some/path   (new layout)
+ *   /some/path/.codebyplan.json        → /some/path   (legacy flat)
+ *   /some/path/.codebyplan/            → /some/path   (dir form, trailing slash)
+ *   /some/path/.codebyplan             → /some/path   (dir form, no slash)
+ *
+ * @param configPath  The path returned by `findCodebyplanConfig().path`.
+ * @returns The absolute directory path that is the repo root.
+ */
+export declare function deriveRepoRoot(configPath: string): string;
+/**
+ * Convert every top-level key from kebab-case to snake_case.
+ * Returns a NEW object; values are copied unchanged.
+ * No recursion into nested objects.
+ *
+ * Example: { "task-id": "x", "is-claude-written": true }
+ *       → { task_id: "x", is_claude_written: true }
+ */
+export declare function kebabToSnakeKeys(obj: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Coerce string values to their correct runtime types for a CLOSED ENUM of
+ * known column names. Runs AFTER kebabToSnakeKeys (keys already snake_case).
+ * Returns a NEW object; unrecognised keys and already-typed values pass through
+ * unchanged.
+ *
+ * JSON fields  (JSON.parse; SyntaxError → keep original string):
+ *   files_changed, context, qa, research, resources,
+ *   context_development, ideas, plan, handoff
+ *
+ * Boolean field (string 'true'→true, 'false'→false, other strings unchanged):
+ *   is_claude_written
+ *
+ * Numeric fields (Number(v) when result is not NaN; NaN → keep original string):
+ *   number, day_number, duration_minutes, session_number
+ */
+export declare function coerceFieldValues(obj: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Resolve repo_id and project path from flags, env vars, and config file.
+ *
+ * Priority for repo_id:
+ *   1. --repo-id flag
+ *   2. CODEBYPLAN_REPO_ID env var
+ *   3. .codebyplan/repo.json (or legacy .codebyplan.json) in projectPath or any ancestor
+ *
+ * Priority for worktree_id (legacy only — new layout does not store worktree_id in files;
+ * consumers must compute it via the resolver):
+ *   1. --worktree-id flag
+ *   2. CODEBYPLAN_WORKTREE_ID env var
+ *   3. Legacy .codebyplan.json in projectPath or any ancestor (new repo.json never has this)
+ *
+ * Priority for project path:
+ *   1. --path flag
+ *   2. process.cwd()
+ *
+ * Note: `projectPath` is NOT re-homed to the discovered config's directory.
+ * The walk-up is only used to resolve repo_id/worktree_id. Downstream code
+ * still operates relative to `projectPath` (the flag or cwd).
+ */
+export declare function resolveConfig(flags: Record<string, string>): Promise<CliConfig>;
+//# sourceMappingURL=flags.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"flags.d.ts","sourceRoot":"","sources":["../../src/lib/flags.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,oBAAoB,CACxC,QAAQ,EAAE,MAAM,EAChB,QAAQ,SAAK,GACZ,OAAO,CAAC;IACT,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACtD,GAAG,IAAI,CAAC,CAiCR;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAarE;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG;IAClD,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,QAAQ,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CACvB,CAiBA;AAED;;GAEG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAEjE;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAIzD;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC3B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAMzB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC3B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAgDzB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,aAAa,CACjC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC5B,OAAO,CAAC,SAAS,CAAC,CA2BpB"}

package/dist/lib/gh-required-checks.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Library for `codebyplan ci enforce-check`.
+ *
+ * Reads and writes `.codebyplan/ci.json` atomically, and enforces the CI
+ * required status check on a GitHub branch via `gh api`
+ * (node:child_process execSync).
+ *
+ * Idempotent: if `ci.json workflow.required_check_enforced === true`, returns
+ * `already_enforced` immediately. Mirrors the pattern used in
+ * `.codebyplan/shipment.json` `branching_configured.required_check_enforced`.
+ *
+ * On any non-zero `gh api` exit, prints a manual GitHub-UI fallback checklist
+ * and returns `manual_required` rather than throwing.
+ */
+import type { CiConfig } from "./types.js";
+/**
+ * Read `.codebyplan/ci.json` from the project directory.
+ * Returns a minimal default CiConfig if the file is absent or malformed.
+ */
+export declare function readCiJson(projectDir: string): CiConfig;
+/**
+ * Write `config` to `.codebyplan/ci.json` atomically using a tmp-file rename.
+ * Writes the full config object so no sibling keys are lost.
+ */
+export declare function writeCiJsonAtomic(projectDir: string, config: CiConfig): void;
+export interface EnforceRequiredCheckOptions {
+    /** Branch to enforce the required check on (default: "main"). */
+    branch?: string;
+    /**
+     * Name of the CI status check as it appears in GitHub PR checks. Defaults to
+     * "Lint + typecheck + test + build" to match `jobs.ci.name` in the generated
+     * ci.yml template — they MUST stay in sync, or GitHub shows the required
+     * check as perpetually pending and blocks every merge.
+     */
+    checkName?: string;
+    /** Override the project root directory (default: process.cwd()). */
+    projectDir?: string;
+    /** Preview the action without calling `gh api` or writing ci.json. */
+    dryRun?: boolean;
+}
+export type EnforceRequiredCheckResult = {
+    status: "enforced";
+    path: string;
+} | {
+    status: "already_enforced";
+    path: string;
+} | {
+    status: "dry_run";
+    path: string;
+} | {
+    status: "manual_required";
+    path: string;
+    instructions: string;
+};
+/**
+ * Enforce the CI required status check on a GitHub branch via `gh api`.
+ *
+ * Steps:
+ *   1. Read `.codebyplan/ci.json`. Return `already_enforced` if already done.
+ *   2. Probe whether branch protection already exists.
+ *   3a. If it exists → POST the check name to
+ *       `.../protection/required_status_checks/contexts` (a SURGICAL add that
+ *       leaves every other protection setting — required_linear_history,
+ *       lock_branch, PR reviews, etc. — untouched). A full PUT /protection is a
+ *       whole-object REPLACE and would silently wipe unrelated settings, so it
+ *       is deliberately avoided here.
+ *   3b. If it does not exist → PUT a minimal protection rule requiring just the
+ *       CI check (nothing to preserve).
+ *   4. Update `ci.json workflow.required_check_enforced = true` (atomic write).
+ *
+ * On any non-zero `gh api` exit → return `manual_required` with a GitHub UI
+ * checklist fallback. With `dryRun`, prints the intended action and returns
+ * `dry_run` without calling `gh api` or writing ci.json.
+ */
+export declare function enforceRequiredCheck(opts?: EnforceRequiredCheckOptions): EnforceRequiredCheckResult;
+//# sourceMappingURL=gh-required-checks.d.ts.map

package/dist/lib/gh-required-checks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gh-required-checks.d.ts","sourceRoot":"","sources":["../../src/lib/gh-required-checks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAKH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAO3C;;;GAGG;AACH,wBAAgB,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,QAAQ,CAkBvD;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,GAAG,IAAI,CAG5E;AAMD,MAAM,WAAW,2BAA2B;IAC1C,iEAAiE;IACjE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oEAAoE;IACpE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,sEAAsE;IACtE,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,MAAM,0BAA0B,GAClC;IAAE,MAAM,EAAE,UAAU,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACpC;IAAE,MAAM,EAAE,kBAAkB,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC5C;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACnC;IAAE,MAAM,EAAE,iBAAiB,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,CAAC;AAMtE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,CAAC,EAAE,2BAA2B,GACjC,0BAA0B,CA0H5B"}

package/dist/lib/git-utils.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Shared git configuration helpers.
+ *
+ * Extracted from ship.ts so that bump.ts (and future callers) can reuse
+ * the same base-branch resolution logic without duplicating it.
+ */
+/**
+ * Resolve the current git branch name for `cwd`.
+ * Tries `git symbolic-ref --short HEAD` first, falling back to
+ * `git rev-parse --abbrev-ref HEAD` (which yields "HEAD" on a detached HEAD).
+ * THROWS if both git invocations fail (no repo / git absent) — callers keep
+ * their existing try/catch + fallback value, so behavior is preserved.
+ */
+export declare function getCurrentBranch(cwd?: string): string;
+/**
+ * Read branch_config.base (production branch) from .codebyplan/git.json.
+ * Falls back gracefully when the file is missing or branch_config is absent.
+ * Default: "main".
+ *
+ * Resolution order:
+ *   1. branch_config.base  (explicit base field)
+ *   2. branch_config.production
+ *   3. "main"
+ */
+export declare function readBaseBranch(cwd: string): Promise<string>;
+/**
+ * Resolve the configured base branch NAME to the git ref the bump engine should
+ * actually compare against.
+ *
+ * The local `<base>` branch (e.g. `main`) is frequently stale relative to the
+ * remote — `git fetch` updates `origin/<base>`, not the local branch. Comparing
+ * against a stale local ref produces BOTH false positives (a stale merge-base
+ * widens the three-dot diff to include files already on the remote) and false
+ * negatives (idempotency wrongly skips a package whose version merely exceeds
+ * the stale local version). So prefer the remote-tracking ref `origin/<base>`
+ * when it exists.
+ *
+ * Repo-agnostic: when no `origin/<base>` remote-tracking ref exists (offline,
+ * no remote, detached fork), fall back to the local branch name. This function
+ * never fetches — keeping the resolution side-effect-free; the caller (ship /
+ * merge-main) owns freshness.
+ *
+ * @returns `origin/<base>` when that ref resolves, otherwise `<base>` unchanged.
+ */
+export declare function resolveBaseRef(cwd: string, baseBranch: string): string;
+//# sourceMappingURL=git-utils.d.ts.map

package/dist/lib/git-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-utils.d.ts","sourceRoot":"","sources":["../../src/lib/git-utils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAOH;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,GAAE,MAAsB,GAAG,MAAM,CAcpE;AAED;;;;;;;;;GASG;AACH,wBAAsB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CA8CjE;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAiBtE"}

package/dist/lib/gitignore-block.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The canonical set of codebyplan-managed .gitignore entries.
+ * Single source of truth — install/update/uninstall and setup all use this.
+ */
+export declare const CANONICAL_GITIGNORE_ENTRIES: readonly string[];
+export declare const GITIGNORE_BLOCK_START = "# >>> codebyplan (managed) >>>";
+export declare const GITIGNORE_BLOCK_END = "# <<< codebyplan <<<";
+export type GitignoreBlockAction = "created" | "appended" | "refreshed" | "unchanged" | "removed";
+/**
+ * Ensure the managed block (start marker, the canonical entries, end marker)
+ * exists in `<projectDir>/.gitignore`.
+ *
+ * - file absent            → "created"  (write file with just the block)
+ * - file present, no block → "appended" (preserve existing content + append)
+ * - file present, block differs → "refreshed" (replace only the block lines)
+ * - file present, block matches → "unchanged" (no write)
+ *
+ * CRLF-safe: detects dominant newline and writes block with same newline.
+ * Trailing-newline-safe: ensures a separating newline before the appended block.
+ * dryRun: computes action but does NOT write.
+ */
+export declare function ensureManagedGitignoreBlock(projectDir: string, dryRun?: boolean): Promise<GitignoreBlockAction>;
+/**
+ * Remove the managed block (start marker, body, end marker) from
+ * `<projectDir>/.gitignore`.
+ *
+ * - block present → removes it, collapses stray double-blank-lines → "removed"
+ * - block absent or file missing → "unchanged"
+ * dryRun: computes action but does NOT write.
+ */
+export declare function removeManagedGitignoreBlock(projectDir: string, dryRun?: boolean): Promise<GitignoreBlockAction>;
+//# sourceMappingURL=gitignore-block.d.ts.map

package/dist/lib/gitignore-block.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gitignore-block.d.ts","sourceRoot":"","sources":["../../src/lib/gitignore-block.ts"],"names":[],"mappings":"AAGA;;;GAGG;AACH,eAAO,MAAM,2BAA2B,EAAE,SAAS,MAAM,EAWxD,CAAC;AAEF,eAAO,MAAM,qBAAqB,mCAAmC,CAAC;AACtE,eAAO,MAAM,mBAAmB,yBAAyB,CAAC;AAE1D,MAAM,MAAM,oBAAoB,GAC5B,SAAS,GACT,UAAU,GACV,WAAW,GACX,WAAW,GACX,SAAS,CAAC;AAEd;;;;;;;;;;;;GAYG;AACH,wBAAsB,2BAA2B,CAC/C,UAAU,EAAE,MAAM,EAClB,MAAM,UAAQ,GACb,OAAO,CAAC,oBAAoB,CAAC,CAoG/B;AAED;;;;;;;GAOG;AACH,wBAAsB,2BAA2B,CAC/C,UAAU,EAAE,MAAM,EAClB,MAAM,UAAQ,GACb,OAAO,CAAC,oBAAoB,CAAC,CAqE/B"}

package/dist/lib/gitignore-detect.d.ts

@@ -0,0 +1,117 @@
+export type SettingsIgnoredSkipReason = "non-git" | "not-ignored" | "managed-block" | "user-declined";
+export interface DetectAndHealResult {
+    healed: boolean;
+    skipped?: SettingsIgnoredSkipReason;
+}
+export interface DetectAndHealOpts {
+    /** When true, auto-accept removal without prompting (equivalent to --yes). */
+    yes: boolean;
+    /** When true, report what would happen but do NOT write anything. */
+    dryRun: boolean;
+}
+/** Injectable deps — swap out in tests. */
+export interface DetectAndHealDeps {
+    /**
+     * Run `git check-ignore -v -- .claude/settings.json` in projectDir.
+     * Returns { exitCode, stdout, stderr }.
+     * exitCode 0 → ignored; exitCode 1 → not ignored; exitCode 128 → not in a git repo.
+     */
+    gitCheckIgnore?: (projectDir: string) => GitCheckIgnoreResult;
+    /**
+     * Run `git ls-files --error-unmatch -- .claude/settings.json` in projectDir.
+     * Returns exit code (0 = tracked, 1 = untracked, 128 = non-git / git absent).
+     */
+    gitLsFiles?: (projectDir: string) => number;
+    /** Read a file as UTF-8. Defaults to node:fs/promises readFile. */
+    readFileFn?: (p: string) => Promise<string>;
+    /** Write a file as UTF-8. Defaults to node:fs/promises writeFile. */
+    writeFileFn?: (p: string, content: string) => Promise<void>;
+    /** Prompt the user for a remove/keep decision. Returns true = accept removal. */
+    promptRemoveIgnore?: (displayLine: string, opts: DetectAndHealOpts) => Promise<boolean>;
+    /** Print a one-line warning to stdout. */
+    printWarning?: (msg: string) => void;
+    /** Print a one-line informational notice to stdout. */
+    printInfo?: (msg: string) => void;
+}
+export interface GitCheckIgnoreResult {
+    exitCode: number | null;
+    stdout: string;
+    stderr: string;
+}
+/**
+ * Parse a single `git check-ignore -v` stdout line.
+ *
+ * Format: `<source>:<linenum>:<pattern>\t<path>`
+ *
+ * Returns null when the line does not match the expected format.
+ */
+export interface CheckIgnoreParsed {
+    sourceFile: string;
+    lineNum: number;
+    pattern: string;
+    matchedPath: string;
+}
+/**
+ * True when a gitignore pattern specifically targets `settings.json` —
+ * i.e. its final path segment is exactly `settings.json` (no globs, not a
+ * directory pattern). Specific patterns are removed automatically without a
+ * prompt; broad patterns (e.g. `.claude/`) merely *match* settings.json and
+ * still require user consent, since removing them affects other files.
+ */
+export declare function patternTargetsSettingsJson(pattern: string): boolean;
+export declare function parseCheckIgnoreLine(line: string): CheckIgnoreParsed | null;
+/**
+ * Detect whether `.claude/settings.json` is matched by a gitignore rule and
+ * heal the violation: a pattern that specifically targets settings.json is
+ * removed automatically (no prompt — settings.json must be committed); a
+ * broad pattern that merely matches it (e.g. `.claude/`) prompts the user,
+ * since removing the line affects other files.
+ *
+ * Returns `{ healed: true }` when the line was removed.
+ * Returns `{ healed: false, skipped: reason }` for all other outcomes.
+ *
+ * Never throws — all error paths return a structured skipped reason.
+ */
+export declare function detectAndHealSettingsGitignore(projectDir: string, opts: DetectAndHealOpts, deps?: DetectAndHealDeps): Promise<DetectAndHealResult>;
+export interface SettingsIgnoredInfo {
+    sourceFile: string;
+    lineNum: number;
+    pattern: string;
+}
+export type DetectSettingsIgnoredResult = {
+    status: "ignored";
+    info: SettingsIgnoredInfo;
+} | {
+    status: "not-ignored";
+} | {
+    status: "non-git";
+};
+/**
+ * Detect whether `.claude/settings.json` is matched by a gitignore rule.
+ * Non-mutating: no file reads, no writes, no prompts.
+ *
+ * Returns:
+ *   { status: "ignored", info }  — matched by a gitignore rule
+ *   { status: "not-ignored" }    — file is not gitignored
+ *   { status: "non-git" }        — not in a git repo / git absent
+ */
+export declare function detectSettingsIgnored(projectDir: string, deps?: {
+    gitCheckIgnore?: (projectDir: string) => GitCheckIgnoreResult;
+}): DetectSettingsIgnoredResult;
+/**
+ * Check whether `.claude/settings.json` is tracked by git.
+ * Prints a one-line reminder when it is untracked. Non-fatal outside git.
+ *
+ * Returns:
+ *   'tracked'   — git knows the file
+ *   'untracked' — file exists but not added to git index
+ *   'non-git'   — not in a git repo / git absent
+ */
+export type UntrackedStatus = "tracked" | "untracked" | "non-git";
+export declare function checkSettingsUntracked(projectDir: string, deps?: {
+    gitLsFiles?: (projectDir: string) => number;
+}): UntrackedStatus;
+export declare function warnIfSettingsUntracked(projectDir: string, deps?: {
+    gitLsFiles?: (projectDir: string) => number;
+}): void;
+//# sourceMappingURL=gitignore-detect.d.ts.map

package/dist/lib/gitignore-detect.d.ts.map

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

package/dist/lib/handoff-file.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Pure handoff-file library — no file I/O.
+ *
+ * All functions take content/paths as parameters so they are trivially
+ * unit-testable without touching the filesystem.
+ *
+ * Handoff layout under `.codebyplan/handoff/`:
+ *   repo        → handoff/repo.md              (per-worktree ## sections)
+ *   checkpoint  → handoff/checkpoint/<NNN>.md  (3-digit zero-padded)
+ *   task        → handoff/task/<NNN>-<T>.md
+ *   standalone  → handoff/standalone/<N>.md
+ */
+export declare const HANDOFF_LEVELS: readonly ["repo", "checkpoint", "task", "standalone"];
+export type HandoffLevel = (typeof HANDOFF_LEVELS)[number];
+export interface HandoffPathOpts {
+    /** Checkpoint number (required for level "checkpoint" and "task"). */
+    checkpoint?: number;
+    /** Task number within the checkpoint (required for level "task"). */
+    task?: number;
+    /** Standalone task number (required for level "standalone"). */
+    number?: number;
+}
+/**
+ * Return the absolute path for a handoff file at the given level.
+ *
+ * - repo:        <projectDir>/.codebyplan/handoff/repo.md
+ * - checkpoint:  <projectDir>/.codebyplan/handoff/checkpoint/<NNN>.md
+ * - task:        <projectDir>/.codebyplan/handoff/task/<NNN>-<T>.md
+ * - standalone:  <projectDir>/.codebyplan/handoff/standalone/<N>.md
+ *
+ * Checkpoint numbers are zero-padded to 3 digits.
+ */
+export declare function handoffPath(projectDir: string, level: HandoffLevel, opts?: HandoffPathOpts): string;
+/**
+ * Returns true when content is absent (undefined/null), empty, or
+ * whitespace-only. A file is considered "empty" only in these cases.
+ */
+export declare function isHandoffEmpty(content: string | null | undefined): boolean;
+/**
+ * Extract the body of the `## <sectionLabel>` block from repo.md content.
+ *
+ * Returns the text between this heading and the next `## ` heading (or EOF),
+ * trimmed of leading/trailing blank lines. Returns null if the section is not
+ * found.
+ */
+export declare function readHandoffSection(fileContent: string, sectionLabel: string): string | null;
+/**
+ * Upsert a `## <sectionLabel>` section in repo.md content.
+ *
+ * - If the section already exists, its body is replaced with `body`.
+ * - If it does not exist, it is appended at the end.
+ * - An empty `body` removes the section (delegates to removeHandoffSection).
+ *
+ * Returns the updated file content.
+ */
+export declare function replaceHandoffSection(fileContent: string, sectionLabel: string, body: string): string;
+/**
+ * Remove the `## <sectionLabel>` section from repo.md content.
+ *
+ * Returns the resulting file content (may be empty string if no sections remain).
+ */
+export declare function removeHandoffSection(fileContent: string, sectionLabel: string): string;
+//# sourceMappingURL=handoff-file.d.ts.map

package/dist/lib/handoff-file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handoff-file.d.ts","sourceRoot":"","sources":["../../src/lib/handoff-file.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAQH,eAAO,MAAM,cAAc,uDAKjB,CAAC;AAEX,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAC;AAE3D,MAAM,WAAW,eAAe;IAC9B,sEAAsE;IACtE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qEAAqE;IACrE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gEAAgE;IAChE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAMD;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CACzB,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,YAAY,EACnB,IAAI,GAAE,eAAoB,GACzB,MAAM,CAmCR;AAMD;;;GAGG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAG1E;AAMD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,GACnB,MAAM,GAAG,IAAI,CA4Bf;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CACnC,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,MAAM,GACX,MAAM,CAsCR;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,GACnB,MAAM,CAkCR"}

package/dist/lib/hash.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Compute a sha256 digest of the given input and return it as
+ * `sha256:<hex>`. The prefix is required so manifest entries are
+ * self-describing (forward-compatible if we ever switch algorithms).
+ *
+ * Accepts either a Buffer (typical for file reads) or a string (utf8).
+ */
+export declare function sha256(input: Buffer | string): string;
+//# sourceMappingURL=hash.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"hash.d.ts","sourceRoot":"","sources":["../../src/lib/hash.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAGrD"}