npm.io
1.0.50 • Published 5d agoCLI

@nac3/forge-cli

Licence
SEE LICENSE IN LICENSE
Version
1.0.50
Deps
16
Size
7.7 MB
Vulns
0
Weekly
0
SummaryDependencyVersions

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.59z.92 (2026-06-04). 100% manifest verb coverage: every one of the 72 declared NAC-3 verbs has at least one fake-scripted scenario asserting it gets invoked (or refuses to) in the right intent. Brain matrix QA harness at 168 scenarios (+68 since z.61); 22 new verbs in the arc (8 misc + git.status/branch-list + office.excel.append-sheet

  • 12 others); 8 helper CLIs under yf qa (run, scenarios list/show/validate/stats, verbs coverage/sample, brain-matrix-compare); 5 ops docs (SECURITY, CONTRIBUTING, TESTING_GUIDE, DEPLOYMENT, CI_PIPELINE); 2 new doctrines (verb-composition, explain-results); 2 new invariant kinds (min_text_length, verb_invoked_in_order) + structural fixture validator + lefthook pre-commit gate. F101 MCP bridge backend complete (slice 3 panel UI pending); F106 office.* + F107 a11y.* verbs shipped; HITO 5 agent orchestrator design draft awaiting Pablo clarification.

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/ 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

# Install
npm install -g @nac3/forge-cli@latest

# Guided first run: activates your license (auto-synced) + sets your
# AI key (BYOK). One command, it walks you through the rest.
yf onboard

# 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 for every flag and worked examples.

How decoration works

A vanilla HTML/JS app starts like:

<button onclick="digit('7')">7</button>

After yf migrate --ai-silent:

<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:

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 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 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.

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 was driven by a custom harness; the React SDK in @yujin/nac-react 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

See also

Keywords

nacnac-3reactframeworkclaude-codeyujinvoicewhisperelevenlabsttssttdocument-readerpdfdocxepubspec-ingestscaffoldingaccessibilityvoice-firstadip