@delfini/cli 0.1.0-rc.0

package/dist/index.d.cts

@@ -0,0 +1,201 @@
+export { main } from './cli.cjs';
+
+declare const DOC_SCOPE_RELATIVE_PATH = ".claude/skills/delfini/doc-scope.json";
+declare const DOC_SCOPE_VERSION: 1;
+interface DocScope {
+    version: 1;
+    doc_scope: string[];
+}
+interface DocScopeWriteOptions {
+    repoRoot?: string;
+}
+interface DocScopeExpansionResult {
+    /** Absolute paths to files matched by the scope entries. Sorted, deduped. */
+    files: string[];
+    /** Original entries from `paths` that resolved to nothing on disk. */
+    missingPaths: string[];
+}
+declare class DocScopeVersionMismatchError extends Error {
+    readonly code: "DOC_SCOPE_VERSION_MISMATCH";
+    constructor(message?: string);
+}
+declare class DocScopeCorruptError extends Error {
+    readonly code: "DOC_SCOPE_CORRUPT";
+    constructor(message: string);
+}
+declare class DocScopeValidationError extends Error {
+    readonly code: "DOC_SCOPE_VALIDATION";
+    constructor(message: string);
+}
+declare function readDocScope(repoRoot?: string): Promise<DocScope | null>;
+declare function writeDocScope(paths: string[], options?: DocScopeWriteOptions): Promise<void>;
+declare function docScopeExists(repoRoot?: string): Promise<boolean>;
+declare function deleteDocScope(repoRoot?: string): Promise<void>;
+declare function expandDocScope(paths: string[], repoRoot?: string): Promise<DocScopeExpansionResult>;
+
+declare class RepoRootNotFoundError extends Error {
+    readonly code: "REPO_ROOT_NOT_FOUND";
+    constructor(cause?: unknown);
+}
+declare function getRepoRoot(cwd?: string): Promise<string>;
+
+declare function ensureTraceDir(repoRoot: string): string;
+declare function appendToGitignore(repoRoot: string): {
+    changed: boolean;
+};
+declare function writeTraceFile(repoRoot: string, filename: string, content: string): string;
+declare function writeRetryAttemptFile(repoRoot: string, attemptNumber: 1 | 2, content: string): string;
+
+interface InstallLogger {
+    log?: (...args: unknown[]) => void;
+}
+interface RunInstallOptions {
+    /** Coding agent target. V1 accepts only 'CLAUDE' (design-spec NG2). */
+    tool?: string;
+    /** Logger for INFO messages. Defaults to `console`. */
+    logger?: InstallLogger;
+    /**
+     * Resolves the auto-invoke opt-in. When provided, `runInstall` uses it
+     * directly (true → append the CLAUDE.md block; false → strip an existing
+     * block) and never prompts — this is the `--auto-invoke` / `--no-auto-invoke`
+     * CLI-flag path and the test seam. When omitted, `runInstall` prompts
+     * interactively on a TTY, or skips the CLAUDE.md mutation entirely on a
+     * non-TTY stdin (never blocks, never forces opt-in without consent).
+     */
+    confirmAutoInvoke?: () => Promise<boolean>;
+}
+declare class InstallToolNotSupportedError extends Error {
+    readonly code: "INSTALL_TOOL_NOT_SUPPORTED";
+    constructor(tool: string);
+}
+declare function runInstall(targetPath: string, options?: RunInstallOptions): Promise<void>;
+
+/** The diff sources selectable via `--diff-source` (FR141a). */
+type DiffSource = 'local' | 'committed' | 'both';
+declare const PROMPT_TOKEN_BUDGET = 150000;
+interface RunLocalPrepareOptions {
+    /**
+     * The `--scope <paths>` value. Accepts a comma-separated string OR a string[].
+     * When provided, overrides the persisted `.claude/skills/delfini/doc-scope.json`
+     * WITHOUT modifying that file (FR144 per-run override invariant).
+     */
+    scope?: string | string[];
+    /**
+     * The `--base <ref>` value. When provided, used as the diff base directly.
+     * When omitted, defaults to `git merge-base HEAD origin/main`.
+     */
+    base?: string;
+    /**
+     * Override the repo root used for all operations. Test seam — production
+     * callers omit this and let `getRepoRoot()` resolve via
+     * `git rev-parse --show-toplevel`.
+     */
+    repoRoot?: string;
+    /**
+     * Override the prompt-token budget. Test seam — production callers omit
+     * this and the module-level `PROMPT_TOKEN_BUDGET` constant applies.
+     */
+    promptTokenBudget?: number;
+    /**
+     * Stream sink for the warning + guidance output. Test seam — production
+     * callers omit this and `process.stderr` is used.
+     */
+    stderr?: NodeJS.WritableStream;
+    /**
+     * Stream sink for the `prompt_too_large` JSON payload. Test seam.
+     */
+    stdout?: NodeJS.WritableStream;
+    /**
+     * Opt-in doc-relevance gate. When set to a positive integer, docs whose
+     * relevance score (file-path overlap + identifier overlap + heading
+     * overlap + doc-path-in-diff) is below this threshold are dropped from
+     * the prompt before rendering. Default behaviour (undefined or 0) is
+     * observably no-op.
+     *
+     * Exposed via the `--relevance-threshold <N>` flag on `local-prepare`.
+     * Recommended starting value: 5 — covers Tier 1 (doc itself in diff) and
+     * single Tier 2 (one file path overlap).
+     */
+    relevanceThreshold?: number;
+    /**
+     * Opt-in deterministic diff pre-filter (Story P3.7.2 / FR151). When `true`,
+     * drops lockfile / generated / vendored / fixture paths plus pure
+     * whitespace-only and import-only hunks BEFORE prompt assembly. Default
+     * (`false` / undefined) is observably no-op — `analysis-input.json` is
+     * byte-identical and `buildPrompt` output is unchanged (NFR49(b) parity).
+     *
+     * When the gate runs the assembled `analysis-input.json` gains an additive
+     * `_filterResult: { droppedPaths, droppedHunks }` top-level sibling so the
+     * host agent and the maintainer can see what was dropped. Subagent
+     * consumers read only `diff`/`docs`/`prMetadata` and ignore `_filterResult`.
+     *
+     * Exposed via the `--enable-diff-prefilter` boolean flag on `local-prepare`.
+     */
+    enableDiffPreFilter?: boolean;
+    /**
+     * Which diff to analyse (FR141a). Default `local`:
+     *   - `local`     — working tree vs `HEAD` (`git diff HEAD`) + untracked files
+     *   - `committed` — `HEAD` vs `--base` (the feature branch's committed delta)
+     *   - `both`      — working tree vs `--base` (what an opened PR contains) + untracked
+     *
+     * On the default branch `both`/`committed` collapse to `local` by
+     * construction (base ≈ HEAD → empty committed range) — no special-casing.
+     * Exposed via the `--diff-source <local|committed|both>` flag.
+     */
+    diffSource?: DiffSource;
+}
+/**
+ * Returns an exit code (0 = success, 2 = no doc-scope, 4 = prompt-too-large).
+ * Does NOT call `process.exit` — the cli.ts router (Story P3.2.4) is the
+ * single owner of `process.exit`.
+ */
+declare function runLocalPrepare(options?: RunLocalPrepareOptions): Promise<number>;
+
+interface RunDiffStatusOptions {
+    /**
+     * The `--base <ref>` value. When omitted, defaults to
+     * `git merge-base HEAD origin/main` (with a fallback to `HEAD` on a
+     * remote-less sandbox — see `resolveBaseRef`).
+     */
+    base?: string;
+    /**
+     * Override the repo root. Test seam — production callers omit this and let
+     * `getRepoRoot()` resolve via `git rev-parse --show-toplevel`.
+     */
+    repoRoot?: string;
+    /** Stream sink for the JSON output. Test seam — defaults to process.stdout. */
+    stdout?: NodeJS.WritableStream;
+    /** Stream sink for errors + base-ref fallback warnings. Test seam. */
+    stderr?: NodeJS.WritableStream;
+}
+interface DiffStatus {
+    branch: string;
+    isDefaultBranch: boolean;
+    hasLocalChanges: boolean;
+    hasCommittedChanges: boolean;
+}
+/**
+ * Returns an exit code: `0` on success, non-zero on git failure (outside a
+ * git repo, or any other git error). On the error path it writes a message to
+ * stderr and emits NO JSON on stdout — consumers parse stdout only on exit 0.
+ */
+declare function runDiffStatus(options?: RunDiffStatusOptions): Promise<number>;
+
+interface RunLocalFinalizeOptions {
+    /** Positional argument — path to findings.json. Relative paths resolve against repoRoot. */
+    findingsPath: string;
+    /** Override the repo root. Test seam — production callers omit and let `getRepoRoot()` resolve via `git rev-parse --show-toplevel`. */
+    repoRoot?: string;
+    /** Stream sink for the rendered report. Test seam — production uses process.stdout. */
+    stdout?: NodeJS.WritableStream;
+    /** Stream sink for the schema_validation JSON payload. Test seam — production uses process.stderr. */
+    stderr?: NodeJS.WritableStream;
+}
+/**
+ * Returns an exit code (0 / 1 / 3 per AC3). Does NOT call `process.exit` —
+ * the cli.ts router is the single owner of `process.exit` (matches the
+ * pattern from `runLocalPrepare`).
+ */
+declare function runLocalFinalize(options: RunLocalFinalizeOptions): Promise<number>;
+
+export { DOC_SCOPE_RELATIVE_PATH, DOC_SCOPE_VERSION, type DiffSource, type DiffStatus, type DocScope, DocScopeCorruptError, type DocScopeExpansionResult, DocScopeValidationError, DocScopeVersionMismatchError, type DocScopeWriteOptions, type InstallLogger, InstallToolNotSupportedError, PROMPT_TOKEN_BUDGET, RepoRootNotFoundError, type RunDiffStatusOptions, type RunInstallOptions, type RunLocalFinalizeOptions, type RunLocalPrepareOptions, appendToGitignore, deleteDocScope, docScopeExists, ensureTraceDir, expandDocScope, getRepoRoot, readDocScope, runDiffStatus, runInstall, runLocalFinalize, runLocalPrepare, writeDocScope, writeRetryAttemptFile, writeTraceFile };

package/dist/index.d.ts

@@ -0,0 +1,201 @@
+export { main } from './cli.js';
+
+declare const DOC_SCOPE_RELATIVE_PATH = ".claude/skills/delfini/doc-scope.json";
+declare const DOC_SCOPE_VERSION: 1;
+interface DocScope {
+    version: 1;
+    doc_scope: string[];
+}
+interface DocScopeWriteOptions {
+    repoRoot?: string;
+}
+interface DocScopeExpansionResult {
+    /** Absolute paths to files matched by the scope entries. Sorted, deduped. */
+    files: string[];
+    /** Original entries from `paths` that resolved to nothing on disk. */
+    missingPaths: string[];
+}
+declare class DocScopeVersionMismatchError extends Error {
+    readonly code: "DOC_SCOPE_VERSION_MISMATCH";
+    constructor(message?: string);
+}
+declare class DocScopeCorruptError extends Error {
+    readonly code: "DOC_SCOPE_CORRUPT";
+    constructor(message: string);
+}
+declare class DocScopeValidationError extends Error {
+    readonly code: "DOC_SCOPE_VALIDATION";
+    constructor(message: string);
+}
+declare function readDocScope(repoRoot?: string): Promise<DocScope | null>;
+declare function writeDocScope(paths: string[], options?: DocScopeWriteOptions): Promise<void>;
+declare function docScopeExists(repoRoot?: string): Promise<boolean>;
+declare function deleteDocScope(repoRoot?: string): Promise<void>;
+declare function expandDocScope(paths: string[], repoRoot?: string): Promise<DocScopeExpansionResult>;
+
+declare class RepoRootNotFoundError extends Error {
+    readonly code: "REPO_ROOT_NOT_FOUND";
+    constructor(cause?: unknown);
+}
+declare function getRepoRoot(cwd?: string): Promise<string>;
+
+declare function ensureTraceDir(repoRoot: string): string;
+declare function appendToGitignore(repoRoot: string): {
+    changed: boolean;
+};
+declare function writeTraceFile(repoRoot: string, filename: string, content: string): string;
+declare function writeRetryAttemptFile(repoRoot: string, attemptNumber: 1 | 2, content: string): string;
+
+interface InstallLogger {
+    log?: (...args: unknown[]) => void;
+}
+interface RunInstallOptions {
+    /** Coding agent target. V1 accepts only 'CLAUDE' (design-spec NG2). */
+    tool?: string;
+    /** Logger for INFO messages. Defaults to `console`. */
+    logger?: InstallLogger;
+    /**
+     * Resolves the auto-invoke opt-in. When provided, `runInstall` uses it
+     * directly (true → append the CLAUDE.md block; false → strip an existing
+     * block) and never prompts — this is the `--auto-invoke` / `--no-auto-invoke`
+     * CLI-flag path and the test seam. When omitted, `runInstall` prompts
+     * interactively on a TTY, or skips the CLAUDE.md mutation entirely on a
+     * non-TTY stdin (never blocks, never forces opt-in without consent).
+     */
+    confirmAutoInvoke?: () => Promise<boolean>;
+}
+declare class InstallToolNotSupportedError extends Error {
+    readonly code: "INSTALL_TOOL_NOT_SUPPORTED";
+    constructor(tool: string);
+}
+declare function runInstall(targetPath: string, options?: RunInstallOptions): Promise<void>;
+
+/** The diff sources selectable via `--diff-source` (FR141a). */
+type DiffSource = 'local' | 'committed' | 'both';
+declare const PROMPT_TOKEN_BUDGET = 150000;
+interface RunLocalPrepareOptions {
+    /**
+     * The `--scope <paths>` value. Accepts a comma-separated string OR a string[].
+     * When provided, overrides the persisted `.claude/skills/delfini/doc-scope.json`
+     * WITHOUT modifying that file (FR144 per-run override invariant).
+     */
+    scope?: string | string[];
+    /**
+     * The `--base <ref>` value. When provided, used as the diff base directly.
+     * When omitted, defaults to `git merge-base HEAD origin/main`.
+     */
+    base?: string;
+    /**
+     * Override the repo root used for all operations. Test seam — production
+     * callers omit this and let `getRepoRoot()` resolve via
+     * `git rev-parse --show-toplevel`.
+     */
+    repoRoot?: string;
+    /**
+     * Override the prompt-token budget. Test seam — production callers omit
+     * this and the module-level `PROMPT_TOKEN_BUDGET` constant applies.
+     */
+    promptTokenBudget?: number;
+    /**
+     * Stream sink for the warning + guidance output. Test seam — production
+     * callers omit this and `process.stderr` is used.
+     */
+    stderr?: NodeJS.WritableStream;
+    /**
+     * Stream sink for the `prompt_too_large` JSON payload. Test seam.
+     */
+    stdout?: NodeJS.WritableStream;
+    /**
+     * Opt-in doc-relevance gate. When set to a positive integer, docs whose
+     * relevance score (file-path overlap + identifier overlap + heading
+     * overlap + doc-path-in-diff) is below this threshold are dropped from
+     * the prompt before rendering. Default behaviour (undefined or 0) is
+     * observably no-op.
+     *
+     * Exposed via the `--relevance-threshold <N>` flag on `local-prepare`.
+     * Recommended starting value: 5 — covers Tier 1 (doc itself in diff) and
+     * single Tier 2 (one file path overlap).
+     */
+    relevanceThreshold?: number;
+    /**
+     * Opt-in deterministic diff pre-filter (Story P3.7.2 / FR151). When `true`,
+     * drops lockfile / generated / vendored / fixture paths plus pure
+     * whitespace-only and import-only hunks BEFORE prompt assembly. Default
+     * (`false` / undefined) is observably no-op — `analysis-input.json` is
+     * byte-identical and `buildPrompt` output is unchanged (NFR49(b) parity).
+     *
+     * When the gate runs the assembled `analysis-input.json` gains an additive
+     * `_filterResult: { droppedPaths, droppedHunks }` top-level sibling so the
+     * host agent and the maintainer can see what was dropped. Subagent
+     * consumers read only `diff`/`docs`/`prMetadata` and ignore `_filterResult`.
+     *
+     * Exposed via the `--enable-diff-prefilter` boolean flag on `local-prepare`.
+     */
+    enableDiffPreFilter?: boolean;
+    /**
+     * Which diff to analyse (FR141a). Default `local`:
+     *   - `local`     — working tree vs `HEAD` (`git diff HEAD`) + untracked files
+     *   - `committed` — `HEAD` vs `--base` (the feature branch's committed delta)
+     *   - `both`      — working tree vs `--base` (what an opened PR contains) + untracked
+     *
+     * On the default branch `both`/`committed` collapse to `local` by
+     * construction (base ≈ HEAD → empty committed range) — no special-casing.
+     * Exposed via the `--diff-source <local|committed|both>` flag.
+     */
+    diffSource?: DiffSource;
+}
+/**
+ * Returns an exit code (0 = success, 2 = no doc-scope, 4 = prompt-too-large).
+ * Does NOT call `process.exit` — the cli.ts router (Story P3.2.4) is the
+ * single owner of `process.exit`.
+ */
+declare function runLocalPrepare(options?: RunLocalPrepareOptions): Promise<number>;
+
+interface RunDiffStatusOptions {
+    /**
+     * The `--base <ref>` value. When omitted, defaults to
+     * `git merge-base HEAD origin/main` (with a fallback to `HEAD` on a
+     * remote-less sandbox — see `resolveBaseRef`).
+     */
+    base?: string;
+    /**
+     * Override the repo root. Test seam — production callers omit this and let
+     * `getRepoRoot()` resolve via `git rev-parse --show-toplevel`.
+     */
+    repoRoot?: string;
+    /** Stream sink for the JSON output. Test seam — defaults to process.stdout. */
+    stdout?: NodeJS.WritableStream;
+    /** Stream sink for errors + base-ref fallback warnings. Test seam. */
+    stderr?: NodeJS.WritableStream;
+}
+interface DiffStatus {
+    branch: string;
+    isDefaultBranch: boolean;
+    hasLocalChanges: boolean;
+    hasCommittedChanges: boolean;
+}
+/**
+ * Returns an exit code: `0` on success, non-zero on git failure (outside a
+ * git repo, or any other git error). On the error path it writes a message to
+ * stderr and emits NO JSON on stdout — consumers parse stdout only on exit 0.
+ */
+declare function runDiffStatus(options?: RunDiffStatusOptions): Promise<number>;
+
+interface RunLocalFinalizeOptions {
+    /** Positional argument — path to findings.json. Relative paths resolve against repoRoot. */
+    findingsPath: string;
+    /** Override the repo root. Test seam — production callers omit and let `getRepoRoot()` resolve via `git rev-parse --show-toplevel`. */
+    repoRoot?: string;
+    /** Stream sink for the rendered report. Test seam — production uses process.stdout. */
+    stdout?: NodeJS.WritableStream;
+    /** Stream sink for the schema_validation JSON payload. Test seam — production uses process.stderr. */
+    stderr?: NodeJS.WritableStream;
+}
+/**
+ * Returns an exit code (0 / 1 / 3 per AC3). Does NOT call `process.exit` —
+ * the cli.ts router is the single owner of `process.exit` (matches the
+ * pattern from `runLocalPrepare`).
+ */
+declare function runLocalFinalize(options: RunLocalFinalizeOptions): Promise<number>;
+
+export { DOC_SCOPE_RELATIVE_PATH, DOC_SCOPE_VERSION, type DiffSource, type DiffStatus, type DocScope, DocScopeCorruptError, type DocScopeExpansionResult, DocScopeValidationError, DocScopeVersionMismatchError, type DocScopeWriteOptions, type InstallLogger, InstallToolNotSupportedError, PROMPT_TOKEN_BUDGET, RepoRootNotFoundError, type RunDiffStatusOptions, type RunInstallOptions, type RunLocalFinalizeOptions, type RunLocalPrepareOptions, appendToGitignore, deleteDocScope, docScopeExists, ensureTraceDir, expandDocScope, getRepoRoot, readDocScope, runDiffStatus, runInstall, runLocalFinalize, runLocalPrepare, writeDocScope, writeRetryAttemptFile, writeTraceFile };

package/dist/index.js

@@ -0,0 +1,56 @@
+import {
+  DOC_SCOPE_RELATIVE_PATH,
+  DOC_SCOPE_VERSION,
+  DocScopeCorruptError,
+  DocScopeValidationError,
+  DocScopeVersionMismatchError,
+  InstallToolNotSupportedError,
+  PROMPT_TOKEN_BUDGET,
+  RepoRootNotFoundError,
+  appendToGitignore,
+  deleteDocScope,
+  docScopeExists,
+  ensureTraceDir,
+  expandDocScope,
+  getRepoRoot,
+  main,
+  readDocScope,
+  runDiffStatus,
+  runInstall,
+  runLocalFinalize,
+  runLocalPrepare,
+  writeDocScope,
+  writeRetryAttemptFile,
+  writeTraceFile
+} from "./chunk-UGNHP6L5.js";
+import {
+  init_esm_shims
+} from "./chunk-MUW24ZC4.js";
+
+// src/index.ts
+init_esm_shims();
+export {
+  DOC_SCOPE_RELATIVE_PATH,
+  DOC_SCOPE_VERSION,
+  DocScopeCorruptError,
+  DocScopeValidationError,
+  DocScopeVersionMismatchError,
+  InstallToolNotSupportedError,
+  PROMPT_TOKEN_BUDGET,
+  RepoRootNotFoundError,
+  appendToGitignore,
+  deleteDocScope,
+  docScopeExists,
+  ensureTraceDir,
+  expandDocScope,
+  getRepoRoot,
+  main,
+  readDocScope,
+  runDiffStatus,
+  runInstall,
+  runLocalFinalize,
+  runLocalPrepare,
+  writeDocScope,
+  writeRetryAttemptFile,
+  writeTraceFile
+};