@delfini/cli 0.2.1 → 0.3.0

package/README.md

@@ -37,11 +37,12 @@ Scaffold the Skill into a repo (idempotent — safe to re-run).
 - `<path>` — repo root or any subdirectory; resolves up to the git root.
 - Writes `.claude/skills/delfini/SKILL.md`, appends a `/delfini` block to `CLAUDE.md` (creating it if absent, never duplicating), and adds `.delfini-trace/` to `.gitignore`.
 
-### `delfini local-prepare [--scope <paths>] [--base <ref>] [--relevance-threshold <N>]`
+### `delfini local-prepare [--scope <paths>] [--ignore-code-scope <paths>] [--base <ref>] [--relevance-threshold <N>]`
 
 Assemble the analysis input for the coding agent to dispatch.
 
-- `--scope <paths>` — comma-separated paths overriding the persisted doc-scope, for this run only.
+- `--scope <paths>` — comma-separated paths overriding the persisted `doc_scope`, for this run only.
+- `--ignore-code-scope <paths>` — comma-separated code paths whose changes are ignored for analysis (directories, files, or globs), overriding the persisted `ignore_code_scope` for this run only.
 - `--base <ref>` — diff base ref. Defaults to `git merge-base HEAD origin/main`.
 - `--relevance-threshold <N>` — render only the doc sections scoring at/above `N` against the diff, most-relevant-first up to the prompt budget. **Default `5`** (a measured ~40% prompt-token reduction on doc-heavy runs); pass `0` to embed every in-scope doc whole.
 - Writes `analysis-input.json`, `analysis-prompt.md`, and `schema.json` to `.delfini-trace/`.
@@ -59,7 +60,7 @@ Report the branch's change state as JSON (used by the Skill protocol to choose w
 
 ### `delfini --reset-scope`
 
-Delete the persisted `.claude/skills/delfini/doc-scope.json`.
+Delete the persisted `.claude/skills/delfini/delfini-config.json` (and any legacy `doc-scope.json`).
 
 ### `delfini --version`
 

package/dist/__engine-probe__.js

@@ -1,7 +1,7 @@
 import {
   buildPrompt,
   init_esm_shims
-} from "./chunk-LJKEHO6F.js";
+} from "./chunk-IUXS75FH.js";
 
 // src/__engine-probe__.ts
 init_esm_shims();

package/dist/{chunk-K5X5TSUR.js → chunk-IU4AWQKF.js}

@@ -10,7 +10,7 @@ import {
   normalizeDocScope,
   validateAndReconcile,
   validateDocScopeEntry
-} from "./chunk-LJKEHO6F.js";
+} from "./chunk-IUXS75FH.js";
 
 // src/cli.ts
 init_esm_shims();
@@ -170,46 +170,52 @@ import { dirname, join as join2, resolve } from "path";
 import { createInterface } from "readline/promises";
 import { fileURLToPath } from "url";
 
-// src/doc-scope.ts
+// src/config.ts
 init_esm_shims();
 import { promises as fs } from "fs";
 import path from "path";
 import { glob } from "tinyglobby";
-var DOC_SCOPE_RELATIVE_PATH = ".claude/skills/delfini/doc-scope.json";
-var DOC_SCOPE_VERSION = 1;
-var DOC_SCOPE_VERSION_MISMATCH_MESSAGE = "your doc-scope.json is for a newer @delfini/cli; please upgrade.";
+var DELFINI_CONFIG_RELATIVE_PATH = ".claude/skills/delfini/delfini-config.json";
+var LEGACY_DOC_SCOPE_RELATIVE_PATH = ".claude/skills/delfini/doc-scope.json";
+var DELFINI_CONFIG_VERSION = 1;
+var CONFIG_VERSION_MISMATCH_MESSAGE = "your delfini-config.json is for a newer @delfini/cli; please upgrade.";
 var REPO_ROOT_REL = ".";
-var DocScopeVersionMismatchError = class extends Error {
-  code = "DOC_SCOPE_VERSION_MISMATCH";
-  constructor(message = DOC_SCOPE_VERSION_MISMATCH_MESSAGE) {
+var ConfigVersionMismatchError = class extends Error {
+  code = "CONFIG_VERSION_MISMATCH";
+  constructor(message = CONFIG_VERSION_MISMATCH_MESSAGE) {
     super(message);
-    this.name = "DocScopeVersionMismatchError";
+    this.name = "ConfigVersionMismatchError";
   }
 };
-var DocScopeCorruptError = class extends Error {
-  code = "DOC_SCOPE_CORRUPT";
+var ConfigCorruptError = class extends Error {
+  code = "CONFIG_CORRUPT";
   constructor(message) {
     super(message);
-    this.name = "DocScopeCorruptError";
+    this.name = "ConfigCorruptError";
   }
 };
-var DocScopeValidationError = class extends Error {
-  code = "DOC_SCOPE_VALIDATION";
+var ConfigValidationError = class extends Error {
+  code = "CONFIG_VALIDATION";
   constructor(message) {
     super(message);
-    this.name = "DocScopeValidationError";
+    this.name = "ConfigValidationError";
   }
 };
-var docScopeSchemaV1 = external_exports.object({
+var configSchemaV1 = external_exports.object({
   version: external_exports.literal(1),
-  doc_scope: external_exports.array(external_exports.string().min(1))
+  doc_scope: external_exports.array(external_exports.string().min(1)),
+  ignore_code_scope: external_exports.array(external_exports.string().min(1)).optional()
 });
 var versionProbeSchema = external_exports.object({
   version: external_exports.number().int().positive()
 });
-async function readDocScope(repoRoot) {
+async function readConfig(repoRoot) {
   const root = repoRoot ?? await getRepoRoot();
-  const target = path.join(root, DOC_SCOPE_RELATIVE_PATH);
+  const primary = await readConfigFile(path.join(root, DELFINI_CONFIG_RELATIVE_PATH));
+  if (primary !== null) return primary;
+  return readConfigFile(path.join(root, LEGACY_DOC_SCOPE_RELATIVE_PATH));
+}
+async function readConfigFile(target) {
   let raw;
   try {
     raw = await fs.readFile(target, "utf8");
@@ -221,54 +227,96 @@ async function readDocScope(repoRoot) {
   try {
     parsed = JSON.parse(raw);
   } catch (err) {
-    throw new DocScopeCorruptError(
-      `${DOC_SCOPE_RELATIVE_PATH} is malformed: ${err.message}`
+    throw new ConfigCorruptError(
+      `${path.basename(target)} is malformed: ${err.message}`
     );
   }
   const probe = versionProbeSchema.safeParse(parsed);
-  if (probe.success && probe.data.version > DOC_SCOPE_VERSION) {
-    throw new DocScopeVersionMismatchError();
+  if (probe.success && probe.data.version > DELFINI_CONFIG_VERSION) {
+    throw new ConfigVersionMismatchError();
   }
-  const result = docScopeSchemaV1.safeParse(parsed);
+  const result = configSchemaV1.safeParse(parsed);
   if (!result.success) {
-    throw new DocScopeCorruptError(
-      `${DOC_SCOPE_RELATIVE_PATH} is malformed: ${result.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ")}`
+    throw new ConfigCorruptError(
+      `${path.basename(target)} is malformed: ${result.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ")}`
     );
   }
-  return result.data;
+  return {
+    version: DELFINI_CONFIG_VERSION,
+    doc_scope: result.data.doc_scope,
+    ignore_code_scope: result.data.ignore_code_scope ?? []
+  };
 }
-async function writeDocScope(paths, options) {
+async function writeConfig(update, options) {
   const root = options?.repoRoot ?? await getRepoRoot();
+  const existing = await readConfig(root);
+  let docScope = existing?.doc_scope ?? [];
+  let ignoreCodeScope = existing?.ignore_code_scope ?? [];
+  if (update.doc_scope !== void 0) {
+    docScope = validateAndNormalize(update.doc_scope, "doc_scope", { requireNonEmpty: true });
+  }
+  if (update.ignore_code_scope !== void 0) {
+    ignoreCodeScope = validateAndNormalize(update.ignore_code_scope, "ignore_code_scope", {
+      requireNonEmpty: false
+    });
+  }
+  if (docScope.length === 0) {
+    throw new ConfigValidationError(
+      `${DELFINI_CONFIG_RELATIVE_PATH}: doc_scope requires at least one path`
+    );
+  }
+  const payload = {
+    version: DELFINI_CONFIG_VERSION,
+    doc_scope: docScope
+  };
+  if (ignoreCodeScope.length > 0) {
+    payload.ignore_code_scope = ignoreCodeScope;
+  }
+  const target = path.join(root, DELFINI_CONFIG_RELATIVE_PATH);
+  await fs.mkdir(path.dirname(target), { recursive: true });
+  await fs.writeFile(target, `${JSON.stringify(payload, null, 2)}
+`, "utf8");
+  await removeLegacyDocScope(root);
+}
+async function writeDocScope(paths, options) {
   if (!Array.isArray(paths) || paths.length === 0) {
-    throw new DocScopeValidationError("at least one path is required");
+    throw new ConfigValidationError("at least one path is required");
   }
+  await writeConfig({ doc_scope: paths }, options);
+}
+function validateAndNormalize(paths, field, opts) {
   const errors = [];
   for (const entry of paths) {
     const err = validateDocScopeEntry(entry, REPO_ROOT_REL);
     if (err !== null) errors.push(err);
   }
   if (errors.length > 0) {
-    throw new DocScopeValidationError(
-      `${DOC_SCOPE_RELATIVE_PATH}: invalid path(s):
+    throw new ConfigValidationError(
+      `${DELFINI_CONFIG_RELATIVE_PATH}: invalid ${field} path(s):
 ${errors.map((e) => `  - ${e}`).join("\n")}`
     );
   }
   const normalised = normalizeDocScope(paths);
-  if (normalised.length === 0) {
-    throw new DocScopeValidationError(
-      `${DOC_SCOPE_RELATIVE_PATH}: every entry collapses to an empty scope after normalisation (e.g. '.', './', 'docs/..') \u2014 provide at least one concrete path`
+  if (opts.requireNonEmpty && normalised.length === 0) {
+    throw new ConfigValidationError(
+      `${DELFINI_CONFIG_RELATIVE_PATH}: every ${field} entry collapses to an empty scope after normalisation (e.g. '.', './', 'docs/..') \u2014 provide at least one concrete path`
     );
   }
-  const target = path.join(root, DOC_SCOPE_RELATIVE_PATH);
-  await fs.mkdir(path.dirname(target), { recursive: true });
-  const payload = { version: DOC_SCOPE_VERSION, doc_scope: normalised };
-  const json = `${JSON.stringify(payload, null, 2)}
-`;
-  await fs.writeFile(target, json, "utf8");
+  return normalised;
 }
-async function docScopeExists(repoRoot) {
+async function removeLegacyDocScope(root) {
+  const legacy = path.join(root, LEGACY_DOC_SCOPE_RELATIVE_PATH);
+  try {
+    await fs.unlink(legacy);
+  } catch (err) {
+    if (!isNoEntError(err)) throw err;
+  }
+}
+async function configExists(repoRoot) {
   const root = repoRoot ?? await getRepoRoot();
-  const target = path.join(root, DOC_SCOPE_RELATIVE_PATH);
+  return await isFile(path.join(root, DELFINI_CONFIG_RELATIVE_PATH)) || await isFile(path.join(root, LEGACY_DOC_SCOPE_RELATIVE_PATH));
+}
+async function isFile(target) {
   try {
     const st = await fs.stat(target);
     return st.isFile();
@@ -276,13 +324,14 @@ async function docScopeExists(repoRoot) {
     return false;
   }
 }
-async function deleteDocScope(repoRoot) {
+async function deleteConfig(repoRoot) {
   const root = repoRoot ?? await getRepoRoot();
-  const target = path.join(root, DOC_SCOPE_RELATIVE_PATH);
-  try {
-    await fs.unlink(target);
-  } catch (err) {
-    if (!isNoEntError(err)) throw err;
+  for (const rel of [DELFINI_CONFIG_RELATIVE_PATH, LEGACY_DOC_SCOPE_RELATIVE_PATH]) {
+    try {
+      await fs.unlink(path.join(root, rel));
+    } catch (err) {
+      if (!isNoEntError(err)) throw err;
+    }
   }
 }
 async function expandDocScope(paths, repoRoot) {
@@ -489,24 +538,24 @@ function sanitiseScope(paths) {
   return paths.map((entry) => entry.trim()).filter((entry) => entry.length > 0);
 }
 async function applyDocScope(repoRoot, logger, provideDocScope) {
-  const target = join2(repoRoot, DOC_SCOPE_RELATIVE_PATH);
+  const target = join2(repoRoot, DELFINI_CONFIG_RELATIVE_PATH);
   if (provideDocScope) {
     const paths2 = sanitiseScope(await provideDocScope());
     if (paths2.length === 0) {
-      log(logger, `doc-scope.json \u2192 ${target} (no paths provided, no change)`);
+      log(logger, `delfini-config.json \u2192 ${target} (no paths provided, no change)`);
       return;
     }
     await persistDocScope(repoRoot, logger, target, paths2);
     return;
   }
-  if (await docScopeExists(repoRoot)) {
-    log(logger, `doc-scope.json \u2192 ${target} (already configured, no change)`);
+  if (await configExists(repoRoot)) {
+    log(logger, `delfini-config.json \u2192 ${target} (already configured, no change)`);
     return;
   }
   if (!process.stdin.isTTY) {
     log(
       logger,
-      `doc-scope.json \u2192 ${target} (non-interactive shell: scope prompt skipped, no change)`
+      `delfini-config.json \u2192 ${target} (non-interactive shell: scope prompt skipped, no change)`
     );
     return;
   }
@@ -514,7 +563,7 @@ async function applyDocScope(repoRoot, logger, provideDocScope) {
   if (paths.length === 0) {
     log(
       logger,
-      `doc-scope.json \u2192 ${target} (no paths provided, no change \u2014 first /delfini run will prompt)`
+      `delfini-config.json \u2192 ${target} (no paths provided, no change \u2014 first /delfini run will prompt)`
     );
     return;
   }
@@ -534,12 +583,12 @@ async function promptDocScope() {
 async function persistDocScope(repoRoot, logger, target, paths) {
   try {
     await writeDocScope(paths, { repoRoot });
-    log(logger, `doc-scope.json \u2192 ${target} (wrote ${paths.length} path(s))`);
+    log(logger, `delfini-config.json \u2192 ${target} (wrote ${paths.length} path(s))`);
   } catch (err) {
-    if (err instanceof DocScopeValidationError) {
+    if (err instanceof ConfigValidationError) {
       log(
         logger,
-        `doc-scope.json \u2192 ${target} (skipped \u2014 ${err.message}). Fix the path(s) and re-run \`delfini install\`, edit the file directly, or set the scope on the first /delfini run.`
+        `delfini-config.json \u2192 ${target} (skipped \u2014 ${err.message}). Fix the path(s) and re-run \`delfini install\`, edit the file directly, or set the scope on the first /delfini run.`
       );
       return;
     }
@@ -965,13 +1014,15 @@ async function runLocalPrepare(options = {}) {
     );
   }
   const repoRoot = options.repoRoot ?? await getRepoRoot();
-  const scopePaths = await resolveScopePaths(options.scope, repoRoot);
+  const config = await readConfig(repoRoot);
+  const scopePaths = resolveScopePaths(options.scope, config);
   if (scopePaths === null) {
     stderr.write(
-      "No doc-scope configured. Pass `--scope <paths>` or run the skill\nfirst-run setup to create `.claude/skills/delfini/doc-scope.json`.\n"
+      "No doc-scope configured. Pass `--scope <paths>` or run the skill\nfirst-run setup to create `.claude/skills/delfini/delfini-config.json`.\n"
     );
     return 2;
   }
+  const ignoreCodeScope = resolveIgnoreCodeScope(options.ignoreCodeScope, config);
   const expansion = await expandDocScope(scopePaths, repoRoot);
   for (const missing of expansion.missingPaths) {
     stderr.write(formatMissingPathWarning(missing));
@@ -981,8 +1032,12 @@ async function runLocalPrepare(options = {}) {
   const rawDiff = await computeDiff(git, repoRoot, baseRef, diffSource);
   let diff = rawDiff;
   let filterResult = null;
-  if (options.enableDiffPreFilter === true) {
-    filterResult = filterDiff(rawDiff);
+  const enableBuiltins = options.enableDiffPreFilter === true;
+  if (enableBuiltins || ignoreCodeScope.length > 0) {
+    filterResult = filterDiff(rawDiff, {
+      builtins: enableBuiltins,
+      ignorePaths: ignoreCodeScope
+    });
     diff = filterResult.keptDiff;
   }
   const docs = await readDocs(expansion.files, repoRoot, stderr);
@@ -1031,7 +1086,7 @@ async function runLocalPrepare(options = {}) {
 `);
   return 0;
 }
-async function resolveScopePaths(scopeOption, repoRoot) {
+function resolveScopePaths(scopeOption, config) {
   if (scopeOption !== void 0) {
     const normalised = normaliseScopeOption(scopeOption);
     if (normalised.length === 0) {
@@ -1039,11 +1094,16 @@ async function resolveScopePaths(scopeOption, repoRoot) {
     }
     return normalised;
   }
-  const persisted = await readDocScope(repoRoot);
-  if (persisted === null) {
+  if (config === null) {
     return null;
   }
-  return persisted.doc_scope;
+  return config.doc_scope;
+}
+function resolveIgnoreCodeScope(ignoreOption, config) {
+  if (ignoreOption !== void 0) {
+    return normaliseScopeOption(ignoreOption);
+  }
+  return config?.ignore_code_scope ?? [];
 }
 function normaliseScopeOption(scope) {
   const raw = Array.isArray(scope) ? scope : scope.split(",");
@@ -1243,7 +1303,7 @@ function readPackageJson() {
 }
 async function main(argv) {
   const program = new Command();
-  program.name("delfini").description("Delfini Skill CLI \u2014 deterministic, never calls an LLM.").version(pkg.version, "-V, --version", "print the @delfini/cli version").option("--reset-scope", "delete the persisted doc-scope.json").exitOverride();
+  program.name("delfini").description("Delfini Skill CLI \u2014 deterministic, never calls an LLM.").version(pkg.version, "-V, --version", "print the @delfini/cli version").option("--reset-scope", "delete the persisted delfini-config.json (and any legacy doc-scope.json)").exitOverride();
   program.action(async (opts) => {
     if (opts.resetScope) {
       await handleResetScope();
@@ -1253,7 +1313,7 @@ async function main(argv) {
     "Scaffold .claude/skills/delfini/SKILL.md + CLAUDE.md auto-invoke + .gitignore append"
   ).option("--tool <agent>", "Coding agent target (only 'CLAUDE' supported in V1)", "CLAUDE").option("--auto-invoke", "append the CLAUDE.md auto-invoke block without prompting").option("--no-auto-invoke", "strip the CLAUDE.md auto-invoke block without prompting").option(
     "--scope <paths>",
-    "Seed doc-scope.json with these paths (space- or comma-separated; overwrites any existing scope) without prompting. Omit to be prompted interactively on a TTY."
+    "Seed delfini-config.json doc_scope with these paths (space- or comma-separated; overwrites any existing scope) without prompting. Omit to be prompted interactively on a TTY."
   ).action(
     async (targetPath, opts) => {
       const confirmAutoInvoke = opts.autoInvoke === void 0 ? void 0 : () => Promise.resolve(opts.autoInvoke);
@@ -1263,7 +1323,10 @@ async function main(argv) {
   );
   program.command("local-prepare").description(
     "Compute diff + doc-scope + prompt + token-budget gate; write .delfini-trace/"
-  ).option("--scope <paths>", "Comma-separated doc-scope paths (overrides doc-scope.json)").option("--base <ref>", "Diff base ref (default: git merge-base HEAD origin/main)").option(
+  ).option("--scope <paths>", "Comma-separated doc-scope paths (overrides delfini-config.json doc_scope)").option(
+    "--ignore-code-scope <paths>",
+    "Comma-separated code paths whose changes are ignored for analysis (overrides delfini-config.json ignore_code_scope). Each entry is a directory, file, or glob."
+  ).option("--base <ref>", "Diff base ref (default: git merge-base HEAD origin/main)").option(
     "--diff-source <source>",
     "Which diff to analyse: 'local' (default), 'committed', or 'both'",
     "local"
@@ -1292,6 +1355,7 @@ async function main(argv) {
     async (opts) => {
       const exitCode = await runLocalPrepare({
         scope: opts.scope,
+        ignoreCodeScope: opts.ignoreCodeScope,
         base: opts.base,
         diffSource: opts.diffSource,
         relevanceThreshold: opts.relevanceThreshold,
@@ -1321,7 +1385,7 @@ async function main(argv) {
 }
 async function handleResetScope() {
   try {
-    await deleteDocScope();
+    await deleteConfig();
   } catch (err) {
     if (err instanceof RepoRootNotFoundError) {
       return;
@@ -1334,15 +1398,17 @@ export {
   RepoRootNotFoundError,
   getRepoRoot,
   runDiffStatus,
-  DOC_SCOPE_RELATIVE_PATH,
-  DOC_SCOPE_VERSION,
-  DocScopeVersionMismatchError,
-  DocScopeCorruptError,
-  DocScopeValidationError,
-  readDocScope,
+  DELFINI_CONFIG_RELATIVE_PATH,
+  LEGACY_DOC_SCOPE_RELATIVE_PATH,
+  DELFINI_CONFIG_VERSION,
+  ConfigVersionMismatchError,
+  ConfigCorruptError,
+  ConfigValidationError,
+  readConfig,
+  writeConfig,
   writeDocScope,
-  docScopeExists,
-  deleteDocScope,
+  configExists,
+  deleteConfig,
   expandDocScope,
   ensureTraceDir,
   appendToGitignore,

package/dist/{chunk-LJKEHO6F.js → chunk-IUXS75FH.js}

@@ -6444,6 +6444,18 @@ function classifyEntry(entry) {
     return "dir";
   return lastSegment.includes(".") ? "file" : "dir";
 }
+function isFileInDocScope(filePath, scope) {
+  const file = posixNormalize(toPosix(filePath).replace(/^\/+/, ""));
+  if (file === "" || file === ".")
+    return false;
+  const entries = normalizeDocScope(scope);
+  for (const entry of entries) {
+    const pattern = classifyEntry(entry) === "dir" ? `${entry}/**` : entry;
+    if ((0, import_picomatch.default)(pattern, { dot: false, nocase: true })(file))
+      return true;
+  }
+  return false;
+}
 function toPosix(p) {
   return p.split("\\").join("/");
 }
@@ -6477,7 +6489,10 @@ function posixNormalize(input) {
 
 // ../drift-engine/dist/diff-filter.js
 init_esm_shims();
-function filterDiff(diff) {
+function filterDiff(diff, options = {}) {
+  const builtins = options.builtins ?? true;
+  const ignorePaths = options.ignorePaths ?? [];
+  const hasIgnore = ignorePaths.length > 0;
   const droppedPaths = [];
   const droppedHunks = [];
   const files = parseDiffIntoFiles(diff);
@@ -6486,6 +6501,14 @@ function filterDiff(diff) {
     keptParts.push(files.preamble);
   }
   for (const file of files.files) {
+    if (hasIgnore && isFileInDocScope(file.path, ignorePaths)) {
+      droppedPaths.push({ path: file.path, reason: "ignored" });
+      continue;
+    }
+    if (!builtins) {
+      keptParts.push(file.rawSlice);
+      continue;
+    }
     const pathReason = classifyPath(file.path);
     if (pathReason !== null) {
       droppedPaths.push({ path: file.path, reason: pathReason });