@delfini/cli 0.2.0 → 0.3.0

package/dist/index.d.ts

@@ -1,36 +1,78 @@
 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 {
+declare const DELFINI_CONFIG_RELATIVE_PATH = ".claude/skills/delfini/delfini-config.json";
+declare const LEGACY_DOC_SCOPE_RELATIVE_PATH = ".claude/skills/delfini/doc-scope.json";
+declare const DELFINI_CONFIG_VERSION: 1;
+interface DelfiniConfig {
     version: 1;
     doc_scope: string[];
+    /** Always present after `readConfig` (defaulted to `[]` when absent on disk). */
+    ignore_code_scope: string[];
 }
-interface DocScopeWriteOptions {
+interface ConfigWriteOptions {
     repoRoot?: string;
 }
+/** Partial update applied on top of any existing config by `writeConfig`. */
+interface ConfigUpdate {
+    /** Replace `doc_scope`. Must be non-empty after normalisation. */
+    doc_scope?: string[];
+    /** Replace `ignore_code_scope`. May be empty (means "ignore nothing"). */
+    ignore_code_scope?: 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";
+declare class ConfigVersionMismatchError extends Error {
+    readonly code: "CONFIG_VERSION_MISMATCH";
     constructor(message?: string);
 }
-declare class DocScopeCorruptError extends Error {
-    readonly code: "DOC_SCOPE_CORRUPT";
+declare class ConfigCorruptError extends Error {
+    readonly code: "CONFIG_CORRUPT";
     constructor(message: string);
 }
-declare class DocScopeValidationError extends Error {
-    readonly code: "DOC_SCOPE_VALIDATION";
+declare class ConfigValidationError extends Error {
+    readonly code: "CONFIG_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>;
+/**
+ * Read the effective Delfini config, or null if none is configured.
+ *
+ * Resolution order: `delfini-config.json` first, then a legacy
+ * `doc-scope.json` fallback (read-only — migration to the new filename happens
+ * on the next `writeConfig`). `ignore_code_scope` is defaulted to `[]` when
+ * absent so callers never branch on undefined.
+ */
+declare function readConfig(repoRoot?: string): Promise<DelfiniConfig | null>;
+/**
+ * Persist a partial config update, merging over any existing config and
+ * preserving the scope not being edited. Writes `delfini-config.json` and
+ * removes a legacy `doc-scope.json` if present (one-time rename migration).
+ *
+ * `doc_scope` is required to be non-empty in the final config (a Delfini run
+ * with no docs is meaningless); `ignore_code_scope` may be empty.
+ */
+declare function writeConfig(update: ConfigUpdate, options?: ConfigWriteOptions): Promise<void>;
+/**
+ * Persist the doc scope, preserving any existing `ignore_code_scope`. Thin
+ * wrapper over `writeConfig` kept for the install / first-run callers whose
+ * only job is to seed the docs Delfini tracks.
+ */
+declare function writeDocScope(paths: string[], options?: ConfigWriteOptions): Promise<void>;
+/**
+ * True iff a Delfini config exists — the new `delfini-config.json` OR a legacy
+ * `doc-scope.json`. Used by `delfini install` to avoid clobbering an existing
+ * committed, team-shared config.
+ */
+declare function configExists(repoRoot?: string): Promise<boolean>;
+/**
+ * Delete the Delfini config — both the new `delfini-config.json` and any legacy
+ * `doc-scope.json` (`delfini --reset-scope`). Idempotent: absent files are a
+ * silent no-op.
+ */
+declare function deleteConfig(repoRoot?: string): Promise<void>;
 declare function expandDocScope(paths: string[], repoRoot?: string): Promise<DocScopeExpansionResult>;
 
 declare class RepoRootNotFoundError extends Error {
@@ -66,11 +108,11 @@ interface RunInstallOptions {
     /**
      * Resolves the doc-scope path list. When provided, `runInstall` uses it
      * directly (the `--scope` CLI flag and the test seam) and never prompts —
-     * a non-empty list is persisted to `doc-scope.json` (overwriting any
+     * a non-empty list is persisted to `delfini-config.json` doc_scope (overwriting any
      * existing file, since an explicit `--scope` is intent-to-overwrite); an
      * empty list is a no-op. When omitted, `runInstall` prompts interactively
-     * on a TTY only if no `doc-scope.json` exists yet; on a non-TTY stdin, or
-     * when a scope is already configured, it leaves `doc-scope.json` untouched.
+     * on a TTY only if no config exists yet; on a non-TTY stdin, or
+     * when a scope is already configured, it leaves the config untouched.
      * Invalid paths (rejected by `writeDocScope`) warn-and-skip — the scaffold
      * always completes; the SKILL.md first-run prompt re-seeds the scope later.
      */
@@ -88,10 +130,18 @@ 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`
+     * When provided, overrides the persisted `delfini-config.json` doc_scope
      * WITHOUT modifying that file (FR144 per-run override invariant).
      */
     scope?: string | string[];
+    /**
+     * The `--ignore-code-scope <paths>` value. Accepts a comma-separated string
+     * OR a string[]. When provided, overrides the persisted `delfini-config.json`
+     * `ignore_code_scope` WITHOUT modifying that file (per-run override). Changed
+     * files matching any entry are dropped from the analysed diff. Empty/omitted
+     * → use the persisted `ignore_code_scope` (or none).
+     */
+    ignoreCodeScope?: string | string[];
     /**
      * The `--base <ref>` value. When provided, used as the diff base directly.
      * When omitted, defaults to `git merge-base HEAD origin/main`.
@@ -210,4 +260,4 @@ interface RunLocalFinalizeOptions {
  */
 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 };
+export { ConfigCorruptError, type ConfigUpdate, ConfigValidationError, ConfigVersionMismatchError, type ConfigWriteOptions, DELFINI_CONFIG_RELATIVE_PATH, DELFINI_CONFIG_VERSION, type DelfiniConfig, type DiffSource, type DiffStatus, type DocScopeExpansionResult, type InstallLogger, InstallToolNotSupportedError, LEGACY_DOC_SCOPE_RELATIVE_PATH, PROMPT_TOKEN_BUDGET, RepoRootNotFoundError, type RunDiffStatusOptions, type RunInstallOptions, type RunLocalFinalizeOptions, type RunLocalPrepareOptions, appendToGitignore, configExists, deleteConfig, ensureTraceDir, expandDocScope, getRepoRoot, readConfig, runDiffStatus, runInstall, runLocalFinalize, runLocalPrepare, writeConfig, writeDocScope, writeRetryAttemptFile, writeTraceFile };

package/dist/index.js

@@ -1,55 +1,59 @@
 import {
-  DOC_SCOPE_RELATIVE_PATH,
-  DOC_SCOPE_VERSION,
-  DocScopeCorruptError,
-  DocScopeValidationError,
-  DocScopeVersionMismatchError,
+  ConfigCorruptError,
+  ConfigValidationError,
+  ConfigVersionMismatchError,
+  DELFINI_CONFIG_RELATIVE_PATH,
+  DELFINI_CONFIG_VERSION,
   InstallToolNotSupportedError,
+  LEGACY_DOC_SCOPE_RELATIVE_PATH,
   PROMPT_TOKEN_BUDGET,
   RepoRootNotFoundError,
   appendToGitignore,
-  deleteDocScope,
-  docScopeExists,
+  configExists,
+  deleteConfig,
   ensureTraceDir,
   expandDocScope,
   getRepoRoot,
   main,
-  readDocScope,
+  readConfig,
   runDiffStatus,
   runInstall,
   runLocalFinalize,
   runLocalPrepare,
+  writeConfig,
   writeDocScope,
   writeRetryAttemptFile,
   writeTraceFile
-} from "./chunk-K5X5TSUR.js";
+} from "./chunk-IU4AWQKF.js";
 import {
   init_esm_shims
-} from "./chunk-LJKEHO6F.js";
+} from "./chunk-IUXS75FH.js";
 
 // src/index.ts
 init_esm_shims();
 export {
-  DOC_SCOPE_RELATIVE_PATH,
-  DOC_SCOPE_VERSION,
-  DocScopeCorruptError,
-  DocScopeValidationError,
-  DocScopeVersionMismatchError,
+  ConfigCorruptError,
+  ConfigValidationError,
+  ConfigVersionMismatchError,
+  DELFINI_CONFIG_RELATIVE_PATH,
+  DELFINI_CONFIG_VERSION,
   InstallToolNotSupportedError,
+  LEGACY_DOC_SCOPE_RELATIVE_PATH,
   PROMPT_TOKEN_BUDGET,
   RepoRootNotFoundError,
   appendToGitignore,
-  deleteDocScope,
-  docScopeExists,
+  configExists,
+  deleteConfig,
   ensureTraceDir,
   expandDocScope,
   getRepoRoot,
   main,
-  readDocScope,
+  readConfig,
   runDiffStatus,
   runInstall,
   runLocalFinalize,
   runLocalPrepare,
+  writeConfig,
   writeDocScope,
   writeRetryAttemptFile,
   writeTraceFile

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@delfini/cli",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -32,7 +32,7 @@
     "simple-git": "^3.27.0",
     "tinyglobby": "^0.2.16",
     "zod": "^3.24.0",
-    "@delfini/drift-engine": "0.2.0"
+    "@delfini/drift-engine": "0.3.0"
   },
   "devDependencies": {
     "@types/node": "^22.10.2",

package/templates/SKILL.md

@@ -41,15 +41,28 @@ If `delfini` is not on PATH:
 3. On `y` → run `npm i -g @delfini/cli`, then re-verify with `delfini --version`.
 4. On `n` or on install failure → fall back to `npx @delfini/cli` for the rest of this session. Substitute `npx @delfini/cli` for every `delfini` invocation in the remaining steps.
 
-## Load doc-scope
+## Load config
 
-Read `.claude/skills/delfini/doc-scope.json`.
+Read `.claude/skills/delfini/delfini-config.json` (the committed, team-shared Delfini config). For repos set up before the rename, also accept a legacy `.claude/skills/delfini/doc-scope.json` — the CLI reads it as a fallback and migrates it to `delfini-config.json` on the next config write.
+
+The config shape (v1) is:
+
+```json
+{
+  "version": 1,
+  "doc_scope": ["docs/", "packages/*/README.md"],
+  "ignore_code_scope": ["src/generated/**", "db/migrations/"]
+}
+```
+
+- `doc_scope` — the source-of-truth docs Delfini analyses (directories scanned recursively for `.md`, single files, or globs).
+- `ignore_code_scope` — **optional.** Code paths whose CHANGES Delfini ignores: a changed file matching any entry (directory, file, or glob — same dialect as `doc_scope`) is dropped from the analysed diff, as if it had not changed. Omit it (or leave it empty) to analyse all changed code.
 
 If the file exists, parse it and continue.
 
-If the file is missing AND the user did not pass `--scope <paths>` to `/delfini`, prompt the user in a single turn:
+If no config exists AND the user did not pass `--scope <paths>` to `/delfini`, prompt the user in a single turn:
 
-> "No `doc-scope.json` found. Which docs should Delfini analyse? Provide one or more paths — directories (recursive `.md` scan), single files, or globs. Example: `docs/ specs/architecture.md packages/*/README.md`."
+> "No `delfini-config.json` found. Which docs should Delfini analyse? Provide one or more paths — directories (recursive `.md` scan), single files, or globs. Example: `docs/ specs/architecture.md packages/*/README.md`."
 
 Validate each path the user supplies:
 
@@ -57,9 +70,9 @@ Validate each path the user supplies:
 - Reject any path that resolves outside the repo root.
 - For non-existent paths, warn the user but keep the path in scope (a teammate may have deleted a file in a different branch).
 
-Write the validated scope to `.claude/skills/delfini/doc-scope.json` in the shape `{"version": 1, "doc_scope": [<paths>]}`. The file is committed to git — team-shared by construction.
+Write the validated scope to `.claude/skills/delfini/delfini-config.json` in the shape `{"version": 1, "doc_scope": [<paths>]}`. The file is committed to git — team-shared by construction. (`ignore_code_scope` is configured by hand-editing this file; the first-run prompt only seeds `doc_scope`.)
 
-If the user passed `--scope <paths>` to `/delfini`, run that invocation against the override list without touching the persisted file.
+If the user passed `--scope <paths>` to `/delfini`, run that invocation against the override list without touching the persisted file. Likewise `--ignore-code-scope <paths>` overrides `ignore_code_scope` for a single run without modifying the file.
 
 ## Resolve the diff source
 
@@ -100,7 +113,7 @@ Run `delfini local-prepare --diff-source <resolved>` (the value resolved in "Res
 
 Branch on non-zero exit codes:
 
-- **Exit `2` (no doc-scope set AND no `--scope` provided)** → fall back to the "Load doc-scope" first-run prompt, write `doc-scope.json`, then re-run `delfini local-prepare --diff-source <resolved>`.
+- **Exit `2` (no doc-scope set AND no `--scope` provided)** → fall back to the "Load config" first-run prompt, write `delfini-config.json`, then re-run `delfini local-prepare --diff-source <resolved>`.
 - **Exit `4` (non-doc prompt payload exceeds budget — diff + schema + instructions alone do not fit, or no doc section fits after ranked-fill)** → surface two options to the user:
   1. Re-invoke with a narrower scope: `/delfini --scope <narrower-paths>`.
   2. Split the PR into smaller changes.