@delfini/cli 0.2.0 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +36 -70
  2. package/package.json +2 -2
package/README.md CHANGED
@@ -1,22 +1,17 @@
1
1
  # @delfini/cli
2
2
 
3
- The plumbing layer of the Delfini Skill — local drift detection inside your coding agent (Claude Code), using the agent's existing LLM tokens. The CLI is deterministic and **never calls an LLM**; the host coding agent does, via the skill protocol scaffolded by `delfini install`.
3
+ The command-line companion for the **Delfini Skill** — local documentation-drift detection inside your coding agent ([Claude Code](https://claude.com/claude-code)).
4
4
 
5
- ## Installation
5
+ [Delfini](https://github.com/Legends-of-Tech/delfini) detects when a code change has made your docs wrong and proposes the one-click fix. The Skill is the way to run that check *before you open a PR*, right in your editor. The CLI is deterministic and **never calls an LLM itself** — your coding agent does the analysis with its own tokens, which is why the Skill costs your team nothing new: no Delfini account, no API key, no GitHub App.
6
6
 
7
- **Recommended: `npx @delfini/cli`** — zero install, always resolves the latest published version, no global PATH pollution. Fits the run-on-each-PR cadence of `/delfini`.
7
+ ## Install
8
8
 
9
9
  ```bash
10
- # Recommended — zero-install per invocation
10
+ # Recommended — zero-install, always the latest version
11
11
  npx @delfini/cli <subcommand>
12
12
 
13
- # Alternative — global install (for offline / latency-sensitive teams)
13
+ # Or install globally
14
14
  npm install -g @delfini/cli
15
-
16
- # In-repo dev iteration (when working on @delfini/cli itself)
17
- pnpm install
18
- pnpm --filter @delfini/cli build # required once — bin/delfini.mjs imports from dist/
19
- pnpm exec tsx packages/cli/bin/delfini.mjs <subcommand>
20
15
  ```
21
16
 
22
17
  ## Quick start
@@ -25,86 +20,57 @@ pnpm exec tsx packages/cli/bin/delfini.mjs <subcommand>
25
20
  delfini install .
26
21
  ```
27
22
 
28
- That scaffolds `.claude/skills/delfini/SKILL.md`, appends a `/delfini` auto-invocation block to `CLAUDE.md` (creating it if absent), and adds `.delfini-trace/` to `.gitignore`. From then on, invoking `/delfini` inside Claude Code drives the skill protocol — the host agent runs `delfini local-prepare`, dispatches a Claude subagent against the prepared prompt, runs `delfini local-finalize` on the subagent's findings, renders the report, and offers an apply UX.
29
-
30
- ## Subcommand reference
31
-
32
- ### `delfini install <path> [--tool <agent>]`
23
+ This scaffolds `.claude/skills/delfini/SKILL.md` into your repo, offers to auto-invoke `/delfini` when you open a PR, and gitignores the per-run trace folder. From then on, running `/delfini` in Claude Code analyzes your working tree against your docs and offers to apply the fixes:
33
24
 
34
- Idempotently scaffold the Skill into a target repo.
35
-
36
- - `<path>` — repo root or any subdirectory; the install resolves up to the git root.
37
- - `--tool <agent>` — coding-agent target. **Only `CLAUDE` is valid in V1** (design-spec NG2 — Claude-only by design); `CLAUDE` is the default.
38
- - Writes: `.claude/skills/delfini/SKILL.md` (overwrites — the documented upgrade path); `CLAUDE.md` marker block (creates the file if absent; never duplicates on re-run); `.gitignore` appends `.delfini-trace/` if not already present.
39
- - Exit codes: `0` success; non-zero on `--tool` other than `CLAUDE`, on a target outside a git repo, or on a filesystem write failure.
25
+ ```
26
+ Apply all (a) / Pick subset (s) / Skip (n)?
27
+ ```
40
28
 
41
- ### `delfini local-prepare [--scope <paths>] [--base <ref>]`
29
+ Under the hood the coding agent runs `delfini local-prepare`, dispatches a subagent against the prepared prompt, runs `delfini local-finalize` on the findings, and applies the approved edits — all using your agent's existing tokens.
42
30
 
43
- Assemble the analysis input for the host agent to dispatch to a Claude subagent.
31
+ ## Commands
44
32
 
45
- - `--scope <paths>` — comma-separated list overriding the persisted `.claude/skills/delfini/doc-scope.json`. Per-run only — does not modify the persisted file.
46
- - `--base <ref>` — diff base ref. Defaults to `git merge-base HEAD origin/main`.
47
- - `--relevance-threshold <N>` — render only the doc **sections** scoring at/above N against the diff, most-relevant-first up to the prompt budget. See [`@delfini/drift-engine`](../drift-engine/README.md#relevance-gating-opt-in)'s relevance-gating documentation for the scoring contract. **Default: `5` (token-efficient retrieval on)** — a measured ~40%+ prompt-token reduction on doc-heavy runs. Pass `--relevance-threshold 0` to disable retrieval and embed every in-scope doc whole. Example: `delfini local-prepare --relevance-threshold 8`.
48
- - Writes three files to `.delfini-trace/`: `analysis-input.json`, `analysis-prompt.md`, `schema.json`.
49
- - Exit codes:
50
- - `0` — success.
51
- - `2` — no doc-scope configured AND no `--scope` flag (NFR47 mode 5).
52
- - `4` — non-doc prompt payload alone exceeds the budget — i.e. the filtered diff + schema + instructions do not fit, or no doc section fits after ranked-fill (NFR47 mode 4); emits a `prompt_too_large` JSON payload on stdout suggesting a narrower scope, a smaller PR, or a smaller diff. Doc-only overflow no longer hard-fails: when `--relevance-threshold` is set, retained sections that exceed the budget are ranked-filled (most-relevant-first) and the run exits `0` with a `dropped N section(s) — over prompt budget` line on stderr.
33
+ ### `delfini install <path>`
53
34
 
54
- ### `delfini local-finalize <findings.json>`
35
+ Scaffold the Skill into a repo (idempotent — safe to re-run).
55
36
 
56
- Validate the subagent's findings, reconcile line numbers, render the report.
37
+ - `<path>` — repo root or any subdirectory; resolves up to the git root.
38
+ - 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`.
57
39
 
58
- - `<findings.json>` — path to the subagent's output (the host agent writes it to `.delfini-trace/findings.json` per the skill protocol). Relative paths resolve against the repo root.
59
- - Reads `.delfini-trace/analysis-input.json` to recover the docs array.
60
- - Writes `.delfini-trace/report.md`; prints the same content to stdout.
61
- - Exit codes:
62
- - `0` — no apply-eligible findings (drift + additive both empty; clarifications may still be reported informationally).
63
- - `1` — at least one drift or additive finding.
64
- - `3` — schema validation failure (NFR47 mode 1); emits a `{"error":"schema_validation","issues":[...]}` payload on stderr.
40
+ ### `delfini local-prepare [--scope <paths>] [--base <ref>] [--relevance-threshold <N>]`
65
41
 
66
- ### `delfini --reset-scope`
42
+ Assemble the analysis input for the coding agent to dispatch.
67
43
 
68
- Delete `.claude/skills/delfini/doc-scope.json`. Silent no-op if the file is absent or the current directory is outside a git repo. Exit code: `0`.
44
+ - `--scope <paths>` — comma-separated paths overriding the persisted doc-scope, for this run only.
45
+ - `--base <ref>` — diff base ref. Defaults to `git merge-base HEAD origin/main`.
46
+ - `--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.
47
+ - Writes `analysis-input.json`, `analysis-prompt.md`, and `schema.json` to `.delfini-trace/`.
69
48
 
70
- ### `delfini --version`
49
+ ### `delfini local-finalize <findings.json>`
71
50
 
72
- Print the `@delfini/cli` version and exit. Exit code: `0`.
51
+ Validate the subagent's findings, reconcile line numbers, and render the report.
73
52
 
74
- ## Dev workflow
53
+ - Writes `.delfini-trace/report.md` and prints it to stdout.
54
+ - Exit code `0` when there are no drift/additive findings to apply, `1` when there are.
75
55
 
76
- ```bash
77
- # Build (required before running bin/delfini.mjs under node)
78
- pnpm --filter @delfini/cli build
56
+ ### `delfini diff-status`
79
57
 
80
- # Type-check
81
- pnpm --filter @delfini/cli typecheck
58
+ Report the branch's change state as JSON (used by the Skill protocol to choose what to analyze).
82
59
 
83
- # Lint
84
- pnpm --filter @delfini/cli lint
60
+ ### `delfini --reset-scope`
85
61
 
86
- # Run the unit + integration test suite (vitest)
87
- pnpm --filter @delfini/cli test
62
+ Delete the persisted `.claude/skills/delfini/doc-scope.json`.
88
63
 
89
- # Smoke-test the published artefact locally
90
- pnpm --filter @delfini/cli build
91
- cd packages/cli
92
- npm pack
93
- npm install -g ./delfini-cli-*.tgz
94
- delfini --version
95
- npm uninstall -g @delfini/cli
96
- ```
64
+ ### `delfini --version`
97
65
 
98
- The vitest suite targets the TypeScript source directly (no build required). The `node bin/delfini.mjs ...` path imports the compiled `dist/cli.js`, so a build is required for manual bin invocation between source edits.
66
+ Print the version.
99
67
 
100
68
  ## What the CLI does NOT do
101
69
 
102
- - **Never calls an LLM.** All LLM dispatch happens inside the skill protocol via the host coding agent's `Agent` tool (FR145). The CLI ships no Anthropic / OpenAI / LangChain client and reads no LLM API key.
103
- - Never pushes to a remote, never opens or comments on PRs, never modifies anything outside the working tree.
104
- - Never integrates with CI; the Delfini GitHub Action (`@delfini/action`) is a separate product that shares the underlying analysis algorithm via `@delfini/drift-engine`.
105
-
106
- ## Architecture
70
+ - **Never calls an LLM.** All analysis is dispatched by your coding agent; the CLI ships no Anthropic / OpenAI / LangChain client and reads no API key.
71
+ - **Never touches the remote.** It doesn't push, open PRs, or comment — it only reads your working tree and writes the doc fixes you approve.
72
+ - **Doesn't run in CI.** The Delfini [GitHub Action](https://github.com/Legends-of-Tech/delfini) is the CI surface; it shares the same analysis core ([`@delfini/drift-engine`](https://www.npmjs.com/package/@delfini/drift-engine)), so a finding the Skill surfaces locally matches what the Action would surface on the PR.
107
73
 
108
- The CLI is one of three Delfini surfaces — the Skill (this package + `packages/drift-engine`), the Action (`apps/action`), and the hosted Web platform (`apps/web`). The Skill and the Action share `@delfini/drift-engine` as their analysis core, so a finding the Skill surfaces locally matches the finding the Action would surface on the eventual PR.
74
+ ## License
109
75
 
110
- See the repository root README and the package source for the full design.
76
+ [Apache-2.0](https://github.com/Legends-of-Tech/delfini/blob/main/LICENSE)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@delfini/cli",
3
- "version": "0.2.0",
3
+ "version": "0.2.1",
4
4
  "license": "Apache-2.0",
5
5
  "repository": {
6
6
  "type": "git",
@@ -32,7 +32,7 @@
32
32
  "simple-git": "^3.27.0",
33
33
  "tinyglobby": "^0.2.16",
34
34
  "zod": "^3.24.0",
35
- "@delfini/drift-engine": "0.2.0"
35
+ "@delfini/drift-engine": "0.2.1"
36
36
  },
37
37
  "devDependencies": {
38
38
  "@types/node": "^22.10.2",