@delfini/cli 0.1.2 → 0.2.1

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,22 +1,17 @@
 # @delfini/cli
 
-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`.
+The command-line companion for the **Delfini Skill** — local documentation-drift detection inside your coding agent ([Claude Code](https://claude.com/claude-code)).
 
-## Installation
+[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.
 
-**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`.
+## Install
 
 ```bash
-# Recommended — zero-install per invocation
+# Recommended — zero-install, always the latest version
 npx @delfini/cli <subcommand>
 
-# Alternative — global install (for offline / latency-sensitive teams)
+# Or install globally
 npm install -g @delfini/cli
-
-# In-repo dev iteration (when working on @delfini/cli itself)
-pnpm install
-pnpm --filter @delfini/cli build      # required once — bin/delfini.mjs imports from dist/
-pnpm exec tsx packages/cli/bin/delfini.mjs <subcommand>
 ```
 
 ## Quick start
@@ -25,86 +20,57 @@ pnpm exec tsx packages/cli/bin/delfini.mjs <subcommand>
 delfini install .
 ```
 
-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.
-
-## Subcommand reference
-
-### `delfini install <path> [--tool <agent>]`
+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:
 
-Idempotently scaffold the Skill into a target repo.
-
-- `<path>` — repo root or any subdirectory; the install resolves up to the git root.
-- `--tool <agent>` — coding-agent target. **Only `CLAUDE` is valid in V1** (design-spec NG2 — Claude-only by design); `CLAUDE` is the default.
-- 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.
-- Exit codes: `0` success; non-zero on `--tool` other than `CLAUDE`, on a target outside a git repo, or on a filesystem write failure.
+```
+Apply all (a) / Pick subset (s) / Skip (n)?
+```
 
-### `delfini local-prepare [--scope <paths>] [--base <ref>]`
+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.
 
-Assemble the analysis input for the host agent to dispatch to a Claude subagent.
+## Commands
 
-- `--scope <paths>` — comma-separated list overriding the persisted `.claude/skills/delfini/doc-scope.json`. Per-run only — does not modify the persisted file.
-- `--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. 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`.
-- Writes three files to `.delfini-trace/`: `analysis-input.json`, `analysis-prompt.md`, `schema.json`.
-- Exit codes:
-  - `0` — success.
-  - `2` — no doc-scope configured AND no `--scope` flag (NFR47 mode 5).
-  - `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.
+### `delfini install <path>`
 
-### `delfini local-finalize <findings.json>`
+Scaffold the Skill into a repo (idempotent — safe to re-run).
 
-Validate the subagent's findings, reconcile line numbers, render the report.
+- `<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`.
 
-- `<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.
-- Reads `.delfini-trace/analysis-input.json` to recover the docs array.
-- Writes `.delfini-trace/report.md`; prints the same content to stdout.
-- Exit codes:
-  - `0` — no apply-eligible findings (drift + additive both empty; clarifications may still be reported informationally).
-  - `1` — at least one drift or additive finding.
-  - `3` — schema validation failure (NFR47 mode 1); emits a `{"error":"schema_validation","issues":[...]}` payload on stderr.
+### `delfini local-prepare [--scope <paths>] [--base <ref>] [--relevance-threshold <N>]`
 
-### `delfini --reset-scope`
+Assemble the analysis input for the coding agent to dispatch.
 
-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`.
+- `--scope <paths>` — comma-separated paths overriding the persisted doc-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/`.
 
-### `delfini --version`
+### `delfini local-finalize <findings.json>`
 
-Print the `@delfini/cli` version and exit. Exit code: `0`.
+Validate the subagent's findings, reconcile line numbers, and render the report.
 
-## Dev workflow
+- Writes `.delfini-trace/report.md` and prints it to stdout.
+- Exit code `0` when there are no drift/additive findings to apply, `1` when there are.
 
-```bash
-# Build (required before running bin/delfini.mjs under node)
-pnpm --filter @delfini/cli build
+### `delfini diff-status`
 
-# Type-check
-pnpm --filter @delfini/cli typecheck
+Report the branch's change state as JSON (used by the Skill protocol to choose what to analyze).
 
-# Lint
-pnpm --filter @delfini/cli lint
+### `delfini --reset-scope`
 
-# Run the unit + integration test suite (vitest)
-pnpm --filter @delfini/cli test
+Delete the persisted `.claude/skills/delfini/doc-scope.json`.
 
-# Smoke-test the published artefact locally
-pnpm --filter @delfini/cli build
-cd packages/cli
-npm pack
-npm install -g ./delfini-cli-*.tgz
-delfini --version
-npm uninstall -g @delfini/cli
-```
+### `delfini --version`
 
-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.
+Print the version.
 
 ## What the CLI does NOT do
 
-- **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.
-- Never pushes to a remote, never opens or comments on PRs, never modifies anything outside the working tree.
-- Never integrates with CI; the Delfini GitHub Action (`@delfini/action`) is a separate product that shares the underlying analysis algorithm via `@delfini/drift-engine`.
-
-## Architecture
+- **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.
+- **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.
+- **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.
 
-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.
+## License
 
-See `_bmad-output/planning-artifacts/architecture.md` §`Skill — packages/drift-engine + packages/cli` for the full design.
+[Apache-2.0](https://github.com/Legends-of-Tech/delfini/blob/main/LICENSE)

package/dist/__engine-probe__.cjs

@@ -20,9 +20,9 @@ var __copyProps = (to, from, except, desc) => {
 };
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
-// ../../node_modules/.pnpm/tsup@8.5.1_jiti@2.6.1_postcss@8.5.9_tsx@4.21.0_typescript@5.9.3/node_modules/tsup/assets/cjs_shims.js
+// ../../node_modules/.pnpm/tsup@8.5.1_postcss@8.5.15_tsx@4.22.4_typescript@5.9.3/node_modules/tsup/assets/cjs_shims.js
 var init_cjs_shims = __esm({
-  "../../node_modules/.pnpm/tsup@8.5.1_jiti@2.6.1_postcss@8.5.9_tsx@4.21.0_typescript@5.9.3/node_modules/tsup/assets/cjs_shims.js"() {
+  "../../node_modules/.pnpm/tsup@8.5.1_postcss@8.5.15_tsx@4.22.4_typescript@5.9.3/node_modules/tsup/assets/cjs_shims.js"() {
     "use strict";
   }
 });

package/dist/__engine-probe__.js

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