@nac3/forge-cli 0.2.0-alpha.1

package/LICENSE

@@ -0,0 +1,45 @@
+YUJIN FORGE -- COMMERCIAL SOFTWARE LICENSE
+
+Copyright (c) 2026 Pablo Kuschnirof / Yujin (rpaforce.com).
+
+PRELIMINARY LICENSE NOTICE -- DAY 0
+====================================
+
+This repository is the day-0 planning anchor for Yujin Forge.
+Source code shipped here today (this LICENSE, README.md, the
+SPEC.md draft) is published under the Apache License, Version
+2.0, the same as the rest of the Yujin open-source surface.
+
+When Yujin Forge ships its commercial features (test corpus
+generator, mock generator, embedded Claude Code with NAC-aware
+tools, migration EXECUTION, voice-driven scaffolder, `yf ship`
+deploy gate), those features will ship under a separate
+COMMERCIAL LICENSE issued by Yujin (rpaforce.com) on a per-seat
+or per-organisation basis. The commercial license will be
+incorporated by reference into this file at that time.
+
+The migration AUDIT tool, the chat-panel-without-Forge-tools
+(vanilla Claude Code), and the empty-project scaffolder will
+remain Apache-2.0 even after commercial features ship.
+
+THIS LICENSING REGIME IS PRELIMINARY. The final shape may
+adjust based on community feedback during the v1.0 development
+cycle (2026-Q2 through 2026-Q4). Any change will be announced
+on the project's GitHub Discussions before taking effect.
+
+UNTIL THE COMMERCIAL LICENSE LANDS, THIS REPOSITORY'S CONTENTS
+ARE LICENSED UNDER APACHE-2.0:
+
+   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.
+
+Full Apache-2.0 text: see http://www.apache.org/licenses/LICENSE-2.0

package/README.md

@@ -0,0 +1,371 @@
+# Yujin Forge
+
+**A voice-first NAC-3 development framework + build tool.** Forge
+gives a developer (or an institution like ADIP teaching kids to
+code) a single CLI + chat panel that covers the full app-creation
+loop: read design specs by voice, generate code scaffolds from
+those specs, decorate vanilla HTML into NAC-3, drive existing apps
+via voice + chat.
+
+> Status: **v0.2.0-alpha (HITO 0 + HITO 1 closed)**, 2026-05-23.
+>
+> **HITO 0 -- credentials vault.** AES-256-GCM at-rest encryption
+> with machine fingerprint binding, atomic writes (0o600), one-shot
+> reveal, vault modal in chat panel. Slots: anthropic / openai /
+> google_voice / elevenlabs / github_token.
+>
+> **HITO 1 -- voice + reader + spec ingest.** Bidirectional voice
+> (Whisper + Google STT, ElevenLabs + Google + Yujin Cloud TTS) with
+> chunked pipelined playback (~600 ms first audio on long sections).
+> Voiceprint enrolment + 5-layer trust model + liveness challenge on
+> irreversible ops. Document reader for **txt / md / source / html /
+> rtf / csv / epub / pdf / docx / xlsx** (10 formats) with voice-
+> driven navigation (open / next / search / bookmark / recap). Spec
+> drag-drop: drop a PDF/DOCX/etc into chat -> Forge parses ->
+> Claude extracts requirements/entities/endpoints/components ->
+> generates a file plan -> writes the scaffold after explicit
+> approval -> rollback on demand.
+>
+> **Fase F -- 10-language i18n + manuals.** Panel UI + voice intent
+> matcher + HTML user manuals all available in
+> **es / en / pt / fr / ja / zh / hi / ar / de / it**. Globe button
+> in the chat panel swaps the active language; the new
+> `forge.manual.open` tool routes "abrime el manual" / "open the
+> manual" / "マニュアルを開いて" / etc to the right HTML manual
+> served through the reader pipeline. Catalog-lint refuses to
+> publish if any locale is missing keys.
+>
+> Earlier work still shipping: G1 (AST migrator robustness) + G2
+> (LLM retry loop) + G3 (multi-page HTML) + G4 (--dry-run for ai
+> modes) + G5 (SPEC sync) + G6 (Figma scaffolder alpha) + the v0.3.0
+> chat tool-use loop (`forge.read_manifest`,
+> `forge.consult_nac_spec`, plus the V1.11..V1.13 github/git/
+> lifecycle tools and the V1.28 + V1.32 reader tools).
+>
+> **988 vitest cases green** across 63 suites (Linux + macOS +
+> Windows CI). AI decorator validated on calc fixture (15/15
+> dispatch tasks OK) + Conduit-NAC3 (178/180 cross-lang at N=3).
+> See [yujin.app/nac-spec/migration/](https://yujin.app/nac-spec/migration/)
+> for the migration paper, `docs/HITO_1_ARCHITECTURE.md` for the
+> voice+reader internals, and `docs/EVOLUTION_PLAN.md` for what is
+> next.
+
+## What it is
+
+Four things in one:
+
+1. **An AI-powered NAC-3 decorator.** `yf migrate <dir> --ai-silent`
+   calls Claude Sonnet 4.6 with the HTML + JS source, gets back a
+   fully-decorated HTML + JSON manifest, post-processes the output to
+   bake in the NAC3 runtime + contract bridge + inline `NAC.register`.
+   Takes ~25 s and ~$0.05 per app.
+
+2. **A Pilot installer.** `yf pilot install <dir>` injects the
+   embedded chat + voice + multi-model bundle into any
+   Forge-decorated app. The same UI works against any NAC-3-compliant
+   page, regardless of how it was decorated.
+
+3. **A React/AST migration scaffold (planned).** `yf migrate
+   <existing-react-repo>` audits the codebase, proposes the migration
+   path screen-by-screen, executes the diff. The audit + apply flow
+   is in place; the React-specific AST migrator is in flight.
+
+4. **A voice-first developer assistant (HITO 1).** `yf chat`
+   launches a local panel with bidirectional voice, a 10-format
+   document reader, and drag-drop spec ingest. Drop a PDF / DOCX /
+   HTML spec into chat -> Forge extracts requirements via Claude ->
+   generates a file scaffold plan -> writes the project after you
+   approve. Reverse the scaffold with one click. Aimed at solo
+   developers + institutional teams (ADIP) who want the full
+   "read spec out loud, then write the code" cycle without leaving
+   the keyboard or the headset. See "Voice cockpit + spec ingest"
+   below.
+
+## Quick start
+
+```bash
+# Install
+npm install -g @yujin/forge
+
+# Decorate a vanilla HTML app (one shot, no human input)
+yf migrate ./my-app --ai-silent --ai-out ./my-app-decorated
+
+# Same, but include Yujin Pilot (the embedded chat + voice cockpit)
+yf migrate ./my-app --ai-silent --with-pilot --ai-out ./my-app-decorated
+
+# Install Pilot into an already-decorated app
+yf pilot install ./my-app-decorated
+
+# Open it
+xdg-open ./my-app-decorated/index.html
+```
+
+The decorated output is **drop-in NAC3-ready**: no CDN dependencies
+at runtime, the manifest is registered inline at boot, every action
+button is wired through `NAC.bindAction`, the floating Pilot button
+appears bottom-right. Click it, paste an API key (Anthropic / OpenAI
+/ Google / DeepSeek / Groq), and drive the page by voice or text.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `yf new <slug>` | Bootstrap a new Yujin Forge React app from `templates/react-app/`. |
+| `yf migrate <repo>` | Default mode: audit a project for NAC migration without writing. |
+| `yf migrate <repo> --apply` | Execute the proposed React/AST migration on `.tsx`/`.jsx`. |
+| `yf migrate <repo> --html` | Silent HTML walker -- auto-apply on `.html` files (rule-based, no LLM). |
+| `yf migrate <repo> --assisted` | HTML walker with CLI prompts for ambiguous elements (rule-based, no LLM). |
+| `yf migrate <repo> --ai-silent` | **AI-powered.** Claude one-shot decoration of an HTML file (paid seat). |
+| `yf migrate <repo> --ai-assisted` | AI-powered with ambiguity-resolution round. |
+| `yf migrate <repo> --with-pilot` | Inject Yujin Pilot bundle into the decorated output. |
+| `yf pilot install <dir>` | Inject Pilot into an already-decorated NAC-3 app. |
+| `yf chat` | Launch the embedded Claude Code voice+text panel hooked to the current project. |
+| `yf test` | Run the auto-generated test corpus + mocks + report coverage by NAC pipeline stage. |
+| `yf ship` | Gate: tests green + NAC-3 validate clean + LLM review pass + license valid -> deploy hook. |
+| `yf doctor` | Diagnose the local Forge install + license + dependencies. |
+| `yf validate` | Validate a NAC manifest against the spec schema. |
+| `yf license` | Manage license tokens. |
+
+See [docs/USAGE.md](docs/USAGE.md) for every flag and worked examples.
+
+## How decoration works
+
+A vanilla HTML/JS app starts like:
+
+```html
+<button onclick="digit('7')">7</button>
+```
+
+After `yf migrate --ai-silent`:
+
+```html
+<body data-nac-plugin="calc">
+  ...
+  <button onclick="digit('7')"
+          data-nac-id="calc.action.digit_7"
+          data-nac-role="action"
+          data-nac-action="digit_7">7</button>
+  ...
+  <script src="nac.browser.js"></script>
+  <script src="calc.js"></script>
+  <script src="nac-bridge.js"></script>
+  <script>
+    (function () {
+      var manifest = { "plugin_slug": "calc", ... };
+      window.NAC.register(manifest);
+    })();
+  </script>
+</body>
+```
+
+Any LLM driver can now call:
+
+```js
+await NAC.click_by_verb('calc', 'digit_7');
+```
+
+and the host's existing `digit('7')` handler runs **plus** the
+`nac:action:succeeded` contract event fires (because `nac-bridge.js`
+re-wired the inline onclick via `NAC.bindAction`).
+
+## How Pilot works
+
+Pilot is a single-file IIFE bundle + companion stylesheet that lives
+in `yujin-pilot/dist/`. `yf pilot install` (or `yf migrate
+--with-pilot`) copies both into the target directory and inserts the
+script tags before `</body>`.
+
+At runtime, Pilot mounts a floating sumi-e branch button at
+bottom-right. Click it: chat panel opens. Click again: switches to
+the "pizarra" mode (chat + voice + action trace). Configure: paste
+API keys for any subset of {Anthropic, OpenAI, Google, DeepSeek,
+Groq}. Each provider supports all the models the
+[NAC3 v2.3 benchmark](https://yujin.app/nac-spec/benchmark/) exercised.
+
+Pilot reads `window.NAC.list_registered_plugins()` to get the active
+manifest, sends it to the selected LLM with the user's utterance,
+parses the JSON action chain, dispatches each via
+`NAC.click_by_verb`, reads back any configured status probe, then
+speaks the result via Web Speech / ElevenLabs / Google Cloud TTS.
+
+Config persists in `localStorage` under `yujin_pilot.config`. Keys
+never leave the browser. (Production deployments belong behind a
+server proxy.)
+
+See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the full
+internal architecture.
+
+## Voice cockpit + spec ingest (HITO 1)
+
+`yf chat` opens a local panel with three views (globito / mini /
+full). The full view has a chat stream on the left and a "pizarra"
+trace on the right that shows every tool the system invoked to
+answer.
+
+What it covers end-to-end:
+
+- **Vault** -- modal accessible via the Keys button. Slots for
+  `anthropic`, `openai`, `google_voice`, `elevenlabs`,
+  `github_token`. Values are encrypted at rest with the machine
+  fingerprint; shown once on entry, never again.
+
+- **Voice in / voice out.** Press the mic, speak; the panel
+  records via `MediaRecorder`, ships the audio to the configured
+  STT provider, and either dispatches a recognised reader command
+  directly or feeds the transcript to the chat loop. Replies are
+  spoken back via the configured TTS provider with chunked
+  prefetch (first audio in ~600 ms even on long answers).
+
+- **Voiceprint trust.** Enroll your voice once -- subsequent voice
+  commands are gated by a 5-layer trust model
+  (unknown / heard / recognised / trusted / authorised). Irreversible
+  actions (force push, branch delete, deploy) ALWAYS require a
+  liveness challenge regardless of trust level: a random Spanish/
+  English phrase plus a random number you have to read back.
+
+- **Document reader.** Open any file in the project root and
+  navigate by voice: "abrime el readme", "siguiente", "buscar
+  pricing", "marcame aqui como inicio", "volver a marca inicio",
+  "recap". Supports **10 formats**: txt, md, source code (.ts / .py
+  / .rs / 80+ extensions), HTML, RTF, CSV/TSV, EPUB, **PDF**
+  (via pdfjs-dist), **DOCX** (via mammoth), **XLSX** (via sheetjs).
+  All format detection happens automatically.
+
+- **Spec drag-drop.** Drag a spec file onto the chat panel; an
+  overlay appears + the file uploads. Forge parses it through the
+  same reader pipeline, then a Claude call extracts structured
+  requirements, entities, endpoints, and UI components. A second
+  Claude call turns the extraction into a concrete file scaffold
+  plan (which files to create + where + what kind + which
+  requirement each serves + open questions for clarification).
+  Nothing is written until you POST `{approve: true}`. On approve,
+  the scaffolder writes the planned files with hand-rolled
+  templates per kind (model / api / component / test / doc) and
+  records a rollback log -- one click undoes the whole scaffold.
+
+- **Reader recap modes.** Default `literal` mode joins recent
+  spoken blocks into a TTS-friendly narrative for "que dijiste".
+  Optional `summary` mode calls Claude for a 1-2 sentence
+  compression; gated by env var `YF_ENABLE_CLAUDE_RECAP=1` so it
+  cannot fire by accident and charge tokens. Cost model in
+  `docs/RECAP_CLAUDE_COSTS.md`.
+
+### ADIP voice-first demo loop
+
+```
+User: (mic) "abrime el plan.md"
+  -> reader.open    -> TTS "El Plan"
+User: (mic) "siguiente"
+  -> reader.next    -> TTS "Primer paso"
+User: (mic) "buscar pricing"
+  -> reader.search  -> TTS top snippet
+```
+
+Drag a spec PDF onto the panel:
+
+```
+panel             -> spec ingested. Title: ADIP Spec. 4 sections.
+                     First lines:
+                     - The system MUST register patients.
+                     - ...
+panel (via Claude)-> extraction: 1 requirement, 1 entity (Paciente),
+                     1 endpoint (POST /patients), 1 component
+                     (PatientCard).
+panel (via Claude)-> plan: src/models/Paciente.ts +
+                     src/api/patients.ts +
+                     src/components/PatientCard.tsx + README.md.
+                     Open question: authentication unspecified.
+user clicks       -> approve.
+scaffolder        -> 4 files written, rollback log captured.
+```
+
+If anything looks off: one `POST /api/forge/ingest/rollback` and
+the project is back to its prior state.
+
+### Architecture pointer
+
+The full step-by-step voice loop, reader pipeline, voiceprint
+state machine, and "how to add a parser / intent / trust class"
+recipes live in [docs/HITO_1_ARCHITECTURE.md](docs/HITO_1_ARCHITECTURE.md).
+
+## Why a separate product
+
+NAC (the spec) is Apache-2.0 free forever. The reference runtime
+`nac-spec` on npm is Apache-2.0 free forever. **Yujin Forge is the
+commercial build layer:**
+
+- The AI decorator (`--ai-silent` / `--ai-assisted`) burns Anthropic
+  tokens on your behalf; the seat license is what funds that.
+- The chat panel, React scaffolder, test corpus generator, and mock
+  generator are all license-gated.
+- The static-rule HTML walker (`--html`, `--assisted`) is open and
+  works offline.
+
+The Apache spec attracts the ecosystem; Forge monetises the delivery
+experience for teams that want to skip the per-app plumbing.
+
+## What Forge gives an app (under the hood)
+
+Every decorated output ships:
+
+1. `index.html` -- decorated, drop-in NAC3-ready
+2. `manifest.json` -- the NAC3 manifest, version-pinnable
+3. `nac.browser.js` -- the NAC3 runtime (copied locally, no CDN dep)
+4. `nac-bridge.js` -- ~50 lines, wires `NAC.bindAction` for every
+   action element so the host's existing handlers stay intact AND the
+   contract events fire
+5. **With `--with-pilot`:** `pilot.bundle.js` + `pilot.css` -- the
+   embedded chat + voice cockpit
+
+After running Forge, your app is ready to be driven by any LLM agent
+that understands NAC-3. Pilot is one such driver; the
+[600-run benchmark](https://yujin.app/nac-spec/benchmark/) was driven
+by a custom harness; the React SDK in
+[`@yujin/nac-react`](https://www.npmjs.com/package/nac-spec) is
+another.
+
+## Where this lives in the Yujin ecosystem
+
+```
+NAC (Apache-2.0)              -- pkuschnirof/rpaforce-crm + yujin.app/nac-spec
+  spec + reference runtime + nac-spec NPM package
+       |
+       | depends on
+       v
+Yujin Forge (closed core)     -- yujinapp/yujin-forge           (build NAC apps)
+  AI decorator, React scaffolder, license gating, this repo
+       |  sibling product
+       v
+Yujin Pilot (closed core)     -- yujinapp/yujin-pilot           (drive NAC apps)
+  Embedded chat + voice + multi-model cockpit
+       |
+       | downstream adopter
+       v
+Customer apps
+```
+
+## Documentation
+
+- [README.md](README.md) -- this file
+- [PROJECT.md](PROJECT.md) -- topology + governance + slice/HITO process (mandatory read before touching code)
+- [docs/SQ.md](docs/SQ.md) -- quality standards + deliverables + pre-development checklist (Spanish, mandatory)
+- [docs/QUICKSTART_ADIP.md](docs/QUICKSTART_ADIP.md) -- step-by-step setup guide for the ADIP institutional rollout (Spanish)
+- [docs/USAGE.md](docs/USAGE.md) -- every command + flag + worked examples
+- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) -- internals of the AI decorator + wiring + Pilot integration
+- [docs/HITO_1_ARCHITECTURE.md](docs/HITO_1_ARCHITECTURE.md) -- HITO 1 voice + reader + spec ingest reference
+- [docs/LANGUAGE_POLICY.md](docs/LANGUAGE_POLICY.md) -- the 10-canonical-languages rule + catalog-lint mechanism
+- [docs/manuals/manual.es.html](docs/manuals/manual.es.html) -- end-user manual (10 languages: es/en/pt/fr/ja/zh/hi/ar/de/it)
+- [docs/RECAP_CLAUDE_COSTS.md](docs/RECAP_CLAUDE_COSTS.md) -- cost model + lock mechanism for the Claude recap mode
+- [docs/ROADMAP_VOICE_FORGE_2026_05_23.md](docs/ROADMAP_VOICE_FORGE_2026_05_23.md) -- HITO 0/1/2/3 roadmap with decisions taken
+- [docs/TECHNICAL_MANUAL.md](docs/TECHNICAL_MANUAL.md) -- living manual updated at each slice close
+- [docs/SPEC.md](docs/SPEC.md) -- the contract Forge makes with adopting teams
+- [docs/COMMERCIAL_PLAN.md](docs/COMMERCIAL_PLAN.md) -- pricing + licensing model
+- [docs/SESSION_HANDOFF_2026_05_23_AT_DOCTOR.md](docs/SESSION_HANDOFF_2026_05_23_AT_DOCTOR.md) -- state at last session boundary
+
+## See also
+
+- [NAC spec](https://yujin.app/nac-spec/SPEC.html)
+- [NAC3 v2.3 benchmark](https://yujin.app/nac-spec/benchmark/) -- 600 runs across 5 models + 3 protocols
+- [Migration paper](https://yujin.app/nac-spec/migration/) -- Forge silent vs assisted vs Sumi manual on a calculator
+- [Yujin Pilot](https://github.com/yujinapp/yujin-pilot) -- the sibling driver product
+- [Yujin CRM](https://github.com/pkuschnirof/rpaforce-crm) -- the first adopter of the full stack

package/dist/bin/yf.d.ts

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import 'dotenv/config';
+import { Command } from 'commander';
+export declare function buildProgram(): Command;
+//# sourceMappingURL=yf.d.ts.map

package/dist/bin/yf.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"yf.d.ts","sourceRoot":"","sources":["../../src/bin/yf.ts"],"names":[],"mappings":";AAUA,OAAO,eAAe,CAAC;AACvB,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA2BpC,wBAAgB,YAAY,IAAI,OAAO,CAmCtC"}

package/dist/bin/yf.js

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+/*
+ * Yujin Forge CLI -- entry point.
+ *
+ * Each command lives in src/commands/<verb>.ts and exports a
+ * `register(program)` function that attaches itself to the
+ * Commander program. The entry point is intentionally thin so
+ * tests can load individual commands without bootstrapping the
+ * whole CLI.
+ */
+import 'dotenv/config';
+import { Command } from 'commander';
+import { registerNewCommand } from '../commands/new.js';
+import { registerMigrateCommand } from '../commands/migrate.js';
+import { registerChatCommand } from '../commands/chat.js';
+import { registerTestCommand } from '../commands/test.js';
+import { registerShipCommand } from '../commands/ship.js';
+import { registerLicenseCommand } from '../commands/license.js';
+import { registerDoctorCommand } from '../commands/doctor.js';
+import { registerValidateCommand } from '../commands/validate.js';
+import { registerPilotCommand } from '../commands/pilot.js';
+import { registerGenTestsCommand } from '../commands/gen-tests.js';
+import { registerGenFlowTestsCommand } from '../commands/gen-flow-tests.js';
+import { registerFigmaCommand } from '../commands/figma.js';
+import { registerVaultCommand } from '../commands/vault.js';
+import { registerScenariosCommand } from '../commands/scenarios.js';
+import { registerReviewScreensCommand } from '../commands/review-screens.js';
+import { registerPublishCommand } from '../commands/publish.js';
+import { registerProjectsCommand } from '../commands/projects.js';
+import { registerTunnelCommand } from '../commands/tunnel.js';
+import { registerDeployCommand } from '../commands/deploy.js';
+import { registerAppCommand } from '../commands/app.js';
+import { registerVoiceCommand } from '../commands/voice.js';
+import { registerRepoCommand } from '../commands/repo.js';
+import { registerMobileCommand } from '../commands/mobile.js';
+import { registerLogCommand } from '../commands/log.js';
+import { VERSION } from '../version.js';
+export function buildProgram() {
+    const program = new Command();
+    program
+        .name('yf')
+        .description('Yujin Forge -- commercial NAC-3 React development framework.')
+        .version(VERSION, '-v, --version', 'print the Forge CLI version')
+        .helpOption('-h, --help', 'show help')
+        .showHelpAfterError('(run "yf --help" for available commands)');
+    registerNewCommand(program);
+    registerMigrateCommand(program);
+    registerChatCommand(program);
+    registerTestCommand(program);
+    registerShipCommand(program);
+    registerLicenseCommand(program);
+    registerDoctorCommand(program);
+    registerValidateCommand(program);
+    registerPilotCommand(program);
+    registerGenTestsCommand(program);
+    registerGenFlowTestsCommand(program);
+    registerFigmaCommand(program);
+    registerVaultCommand(program);
+    registerScenariosCommand(program);
+    registerReviewScreensCommand(program);
+    registerPublishCommand(program);
+    registerProjectsCommand(program);
+    registerTunnelCommand(program);
+    registerDeployCommand(program);
+    registerAppCommand(program);
+    registerVoiceCommand(program);
+    registerRepoCommand(program);
+    registerMobileCommand(program);
+    registerLogCommand(program);
+    return program;
+}
+async function main() {
+    const program = buildProgram();
+    await program.parseAsync(process.argv);
+}
+// ESM module-detection: only invoke main when executed directly,
+// not when imported by tests.
+const isDirect = import.meta.url === `file://${process.argv[1]}`
+    || (process.argv[1] !== undefined && import.meta.url.endsWith('/' + process.argv[1].split(/[/\\]/).pop()));
+if (isDirect) {
+    main().catch((err) => {
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    });
+}
+//# sourceMappingURL=yf.js.map

package/dist/bin/yf.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"yf.js","sourceRoot":"","sources":["../../src/bin/yf.ts"],"names":[],"mappings":"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"}

package/dist/chat/claude.d.ts

@@ -0,0 +1,100 @@
+import type { ToolSpec } from './tools.js';
+export declare class ConfigurationError extends Error {
+    constructor(message: string);
+}
+export declare class ClaudeApiError extends Error {
+    status: number;
+    constructor(message: string, status: number);
+}
+export interface ChatMessage {
+    role: 'user' | 'assistant';
+    content: string;
+}
+/** One round of tool dispatch recorded for the chat panel's action
+ *  trace. The caller serialises these into the response so the UI
+ *  can render the steps Claude took. */
+export interface ToolRound {
+    tool: string;
+    /** The args block the model emitted. */
+    input: Record<string, unknown>;
+    /** What runTool returned (passed back to Claude as tool_result). */
+    result: unknown;
+    /** True when the tool reported a graceful failure. */
+    is_error?: boolean;
+    /** Anthropic-side id, kept so the audit can match assistant
+        blocks against the corresponding tool_result. */
+    tool_use_id: string;
+}
+export interface ClaudeChatRequest {
+    /** Conversation history, oldest first. Tool turns are not part
+        of this -- the loop manages them internally. */
+    messages: ChatMessage[];
+    /** System prompt. */
+    system?: string;
+    /** Hard cap on output tokens per round. */
+    maxTokens?: number;
+    /** Override the default model. */
+    model?: string;
+    /** Tool catalog the model can call. When present, the response
+        may contain tool_use blocks that this client dispatches
+        automatically. */
+    tools?: ToolSpec[];
+    /** Callback the client invokes when the model emits a tool_use.
+        Required when `tools` is set. */
+    runTool?: (name: string, input: Record<string, unknown>) => Promise<{
+        result: unknown;
+        is_error?: boolean;
+    }>;
+    /** Maximum tool-use loop iterations. Default 5. Stops with a
+        `tool_loop_exhausted` ClaudeApiError when reached. */
+    maxToolRounds?: number;
+}
+export interface ClaudeChatResponse {
+    text: string;
+    tokensIn: number;
+    tokensOut: number;
+    model: string;
+    /** Per-round audit of tool dispatches. Empty when no tools were
+        provided or the model did not call any. */
+    toolRounds: ToolRound[];
+}
+export interface ClaudeClientOptions {
+    apiKey?: string;
+    /** Default model. */
+    defaultModel?: string;
+    /** Test injection for fetch (Node 18+ has global fetch). */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Resolve the Anthropic API key.
+ *
+ * Priority order (first match wins):
+ *   1. Explicitly injected key (test seam).
+ *   2. Vault slot `anthropic` -- the canonical path going
+ *      forward.
+ *   3. process.env.YUJIN_ANTHROPIC_API_KEY -- legacy env var.
+ *   4. process.env.ANTHROPIC_API_KEY -- standard Anthropic env.
+ *   5. ~/.yujin-forge/api-key.txt -- legacy file path.
+ *
+ * Throws ConfigurationError when nothing is found. The error
+ * message lists all the options so the user has a single place
+ * to read where to put the key.
+ *
+ * The vault check is short-circuiting: if the slot exists, the
+ * env vars and the file are ignored. This makes vault-configured
+ * setups deterministic and unaffected by stray env vars.
+ *
+ * The other three paths stay as back-compat for existing users
+ * who already configured Forge via env or file before V0.4
+ * landed. They are NOT deprecated -- they keep working
+ * indefinitely. The vault is just the recommended path.
+ */
+export declare function resolveApiKey(injected?: string): Promise<string>;
+export declare class ClaudeClient {
+    private apiKey;
+    private fetchImpl;
+    private defaultModel;
+    constructor(opts?: ClaudeClientOptions);
+    chat(req: ClaudeChatRequest): Promise<ClaudeChatResponse>;
+}
+//# sourceMappingURL=claude.d.ts.map

package/dist/chat/claude.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude.d.ts","sourceRoot":"","sources":["../../src/chat/claude.ts"],"names":[],"mappings":"AA6BA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C,qBAAa,kBAAmB,SAAQ,KAAK;gBAC/B,OAAO,EAAE,MAAM;CAI5B;AAED,qBAAa,cAAe,SAAQ,KAAK;IACvC,MAAM,EAAE,MAAM,CAAC;gBACH,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAK5C;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;wCAEwC;AACxC,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,wCAAwC;IACxC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,oEAAoE;IACpE,MAAM,EAAE,OAAO,CAAC;IAChB,sDAAsD;IACtD,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;wDACoD;IACpD,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,iBAAiB;IAChC;uDACmD;IACnD,QAAQ,EAAE,WAAW,EAAE,CAAC;IACxB,qBAAqB;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,2CAA2C;IAC3C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kCAAkC;IAClC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;yBAEqB;IACrB,KAAK,CAAC,EAAE,QAAQ,EAAE,CAAC;IACnB;wCACoC;IACpC,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC;QAClE,MAAM,EAAE,OAAO,CAAC;QAChB,QAAQ,CAAC,EAAE,OAAO,CAAC;KACpB,CAAC,CAAC;IACH;6DACyD;IACzD,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd;kDAC8C;IAC9C,UAAU,EAAE,SAAS,EAAE,CAAC;CACzB;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qBAAqB;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,4DAA4D;IAC5D,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,aAAa,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAuCtE;AAmBD,qBAAa,YAAY;IACvB,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,SAAS,CAAe;IAChC,OAAO,CAAC,YAAY,CAAS;gBAEjB,IAAI,GAAE,mBAAwB;IAMpC,IAAI,CAAC,GAAG,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC;CAuHhE"}