@nac3/forge-cli 0.2.0-alpha.9 → 1.0.0

package/dist/bin/yf.js

@@ -27,14 +27,51 @@ 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 { registerPendingCommand } from '../commands/pending.js';
+import { registerWorkflowCommand } from '../commands/workflow.js';
+import { registerWiringCommand } from '../commands/wiring.js';
+import { registerTestAgentCommand } from '../commands/test_agent.js';
+import { registerLessonsCommand } from '../commands/lessons.js';
+import { registerDoctrinesCommand } from '../commands/doctrines.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 { registerKeysSetupCommand } from '../commands/keys_setup.js';
+import { registerBrainCommand } from '../commands/brain.js';
+import { registerLimitsCommand } from '../commands/limits.js';
+import { registerQaCommand } from '../commands/qa.js';
+import { registerDoctrineCommand } from '../commands/doctrine.js';
+import { registerManifestCommand } from '../commands/manifest-cli.js';
 import { registerRepoCommand } from '../commands/repo.js';
 import { registerMobileCommand } from '../commands/mobile.js';
 import { registerLogCommand } from '../commands/log.js';
+import { registerTriageCommand } from '../commands/triage.js';
+import { registerDiscoverCommand } from '../commands/discover.js';
+import { registerLegacyAuditCommand } from '../commands/legacy-audit.js';
+import { registerClarifyCommand } from '../commands/clarify.js';
+import { registerSpecCommand } from '../commands/spec.js';
+import { registerApproveCommand } from '../commands/approve.js';
+import { registerBootstrapCommand } from '../commands/bootstrap.js';
+import { registerOnboardCommand } from '../commands/onboard.js';
+import { registerBlockCommand } from '../commands/block.js';
+import { registerCoverageCommand } from '../commands/workflow-coverage.js';
+import { registerOperateCommand } from '../commands/operate.js';
+import { registerSupportCommand } from '../commands/support.js';
+import { registerGraphCommand } from '../commands/graph.js';
+import { registerMcpCommand } from '../commands/mcp.js';
+import { registerNac3Command } from '../commands/nac3.js';
+import { registerAgentCommand } from '../commands/agent.js';
+/* `yf director` CLI removed (redesign/sumi-forge 2026-06-05): the
+ * build-side multi-agent orchestrator is gone. The Director +
+ * Analyst + Coder + Tester + Scaffolder agent roles were the wrong
+ * consumer of the agentic infrastructure. The infrastructure
+ * itself (bridge, runtime, store, runner, iterative_step,
+ * delegate, real_step_factory, cli_real) survives as a library
+ * for product-side agents -- agents the generated software
+ * dispatches on the user's machine. See
+ * docs/PAPER_SUMI_VS_AGENTIC.md for the rationale. */
+import { ensureLicenseFresh, topLevelName, shouldAutoSync } from '../license/auto_sync.js';
 import { VERSION } from '../version.js';
 export function buildProgram() {
     const program = new Command();
@@ -44,6 +81,18 @@ export function buildProgram() {
         .version(VERSION, '-v, --version', 'print the Forge CLI version')
         .helpOption('-h, --help', 'show help')
         .showHelpAfterError('(run "yf --help" for available commands)');
+    /* Zero-friction license: before any command runs, silently refresh
+     * the Polar license from HITO 4 so the user never types
+     * `yf license sync`. Best-effort + time-boxed + throttled; skips the
+     * license subtree itself to avoid recursion. See license/auto_sync.ts. */
+    program.hook('preAction', async (_thisCommand, actionCommand) => {
+        try {
+            const top = topLevelName(actionCommand);
+            if (shouldAutoSync(top))
+                await ensureLicenseFresh();
+        }
+        catch { /* never block a command on auto-sync */ }
+    });
     registerNewCommand(program);
     registerMigrateCommand(program);
     registerChatCommand(program);
@@ -61,6 +110,12 @@ export function buildProgram() {
     registerReviewScreensCommand(program);
     registerPublishCommand(program);
     registerProjectsCommand(program);
+    registerPendingCommand(program);
+    registerWorkflowCommand(program);
+    registerWiringCommand(program);
+    registerTestAgentCommand(program);
+    registerLessonsCommand(program);
+    registerDoctrinesCommand(program);
     registerTunnelCommand(program);
     registerDeployCommand(program);
     registerAppCommand(program);
@@ -68,9 +123,51 @@ export function buildProgram() {
     /* `yf keys setup` -- BYOK provider keys (brain + voice) + sync. */
     const keys = program.command('keys').description('BYOK provider keys (brain + voice).');
     registerKeysSetupCommand(keys);
+    /* `yf brain` -- alpha.51 brain tier configuration (eco / frontier
+     *  provider+model + which workflow phase escalates). */
+    registerBrainCommand(program);
+    /* `yf limits` -- alpha.59c runtime caps (max tool rounds per
+     *  verb family, timeouts, classifier budget). */
+    registerLimitsCommand(program);
+    /* `yf qa` -- alpha.59y.0 brain-matrix QA harness. */
+    registerQaCommand(program);
+    /* `yf doctrine` -- enumerate + preview doctrines on disk
+     *  (z.67). */
+    registerDoctrineCommand(program);
+    /* `yf manifest` -- list NAC-3 verbs by namespace (z.67). */
+    registerManifestCommand(program);
     registerRepoCommand(program);
     registerMobileCommand(program);
     registerLogCommand(program);
+    /* PRODUCT_WORKFLOW.md commands (Phase I onwards). */
+    registerTriageCommand(program);
+    registerDiscoverCommand(program);
+    registerLegacyAuditCommand(program);
+    registerClarifyCommand(program);
+    registerSpecCommand(program);
+    registerApproveCommand(program);
+    registerBootstrapCommand(program);
+    /* `yf onboard` -- guided first-run: license (auto-synced) + BYOK key. */
+    registerOnboardCommand(program);
+    registerBlockCommand(program);
+    registerCoverageCommand(program);
+    registerOperateCommand(program);
+    registerSupportCommand(program);
+    /* `yf graph` -- alpha.59p semantic graph CRUD + relevance
+     *  preview. Spec: docs/SEMANTIC_GRAPH_SPEC_2026_06_02.md. */
+    registerGraphCommand(program);
+    /* `yf mcp` -- alpha.59p.3 MCP bridge feature flag (default
+     *  OFF). Bridge runtime lands in alpha.60. Spec:
+     *  docs/MCP_BRIDGE_PLAN.md v2. */
+    registerMcpCommand(program);
+    /* `yf nac3` -- NAC-3 v3.x backend tools CLI (task #23 slice 3).
+     *  Inspect + validate + invoke app.* tools declared in
+     *  yujin.forge.json:nac3_backend.tools[].
+     *  Spec: docs/NAC3_SPEC_V3_BACKEND_TOOLS.md. */
+    registerNac3Command(program);
+    /* `yf agent` -- HITO 5 slice 1 read-only surface (list / show /
+     *  doctor). Runner + bridge land in subsequent slices. */
+    registerAgentCommand(program);
     return program;
 }
 async function main() {
@@ -82,8 +179,28 @@ async function main() {
 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));
+    main().catch(async (err) => {
+        /* alpha.59z.14 F104 -- if the error carries a forge_error
+         * payload (attached by deeper layers like resolveAnthropicKey
+         * or HTTP responses with body.forge_error), format it via the
+         * CLI renderer for the friendly what/why/fix triple. Falls
+         * back to the legacy message string when no forge_error is
+         * present. */
+        const fe = err.forge_error;
+        if (fe && typeof fe === 'object') {
+            try {
+                const { formatForgeErrorCli } = await import('../core/error_formatter.js');
+                process.stderr.write(formatForgeErrorCli(fe));
+            }
+            catch {
+                /* Formatter import failed (build issue?). Fall through to
+                 * legacy message so we never lose the error. */
+                console.error(err instanceof Error ? err.message : String(err));
+            }
+        }
+        else {
+            console.error(err instanceof Error ? err.message : String(err));
+        }
         process.exit(1);
     });
 }

package/dist/bin/yf.js.map

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

package/dist/chat/claude.d.ts

@@ -1,4 +1,5 @@
 import type { ToolSpec } from './tools.js';
+import { type UsageKind } from '../telemetry/usage.js';
 export declare class ConfigurationError extends Error {
     constructor(message: string);
 }
@@ -9,6 +10,25 @@ export declare class ClaudeApiError extends Error {
 export interface ChatMessage {
     role: 'user' | 'assistant';
     content: string;
+    /** alpha.56 -- tier the assistant turn was served by. Persisted
+     *  in the store so the next turn's reasoning_gate can apply
+     *  sticky-tier inertia (a follow-up to a frontier turn should
+     *  stay in frontier unless the new message has strong eco
+     *  signals). Optional + ignored by callers that pre-date the
+     *  sticky path. */
+    brain_tier?: 'eco' | 'frontier';
+    /** alpha.56 -- set to true when the assistant turn invoked a
+     *  doc-loading verb (yujin.reader.open, yujin.fs.read-file,
+     *  yujin.fs.read-project-file, etc). The next turn's router
+     *  treats this as a signal to stay in frontier even if the
+     *  user message looks short / simple, because the user is
+     *  almost certainly about to ask the model to reason over
+     *  that doc. */
+    doc_loaded?: boolean;
+    /** alpha.56 -- hidden synthetic user message (e.g. modal
+     *  approval continuation). Set by the panel when injecting
+     *  follow-up turns the user did not type. Not rendered. */
+    hidden?: boolean;
 }
 /** One round of tool dispatch recorded for the chat panel's action
  *  trace. The caller serialises these into the response so the UI
@@ -48,6 +68,42 @@ export interface ClaudeChatRequest {
     /** Maximum tool-use loop iterations. Default 5. Stops with a
         `tool_loop_exhausted` ClaudeApiError when reached. */
     maxToolRounds?: number;
+    /** Usage kind for telemetry. Defaults to `claude.chat`. Callers
+        issuing spec / clarify / triage calls pass the matching kind
+        so cost reports group correctly. */
+    usageKind?: UsageKind;
+    /** Free-text label for the usage event (e.g. "spec.rfp",
+        "clarify.functional"). Optional. */
+    usageLabel?: string;
+    /** Project root associated with this call. Optional. */
+    projectRoot?: string;
+    /** Optional progress hook for clients that drive their tool loop
+     *  inside the .chat() call (subprocess providers). The chat server
+     *  passes its `sseEmit` here so the panel sees `tool_round_start` /
+     *  `tool_round_done` events for tools the subprocess invoked,
+     *  matching the feedback cadence of the HTTP path's runTool seam.
+     *  Implementations that own the tool loop externally (runTool
+     *  callback path) can ignore this. */
+    onStreamEvent?: (event: string, data: unknown) => void;
+    /** Interrupt signal. When aborted, the tool loop stops at the next
+     *  round boundary (controlled fall) and the in-flight request is
+     *  cancelled; the response comes back with `interrupted: true`. */
+    signal?: AbortSignal;
+    /** Working directory for the turn. Only the claude-code-cli (Plan)
+     *  provider uses it: the `claude -p` subprocess spawns here so it
+     *  operates in the ACTIVE project, not the launch cwd. Follows a hot
+     *  project switch. (Pablo 2026-06-15) */
+    cwd?: string;
+    /** alpha.59z.163 PND-027 -- dynamic suffix appended to the system
+     *  prompt that should NOT be part of the cached prefix. Content
+     *  here changes per turn (e.g. relevance-ranked graph snippets,
+     *  current workflow phase, intent-specific hints), so caching it
+     *  would invalidate the prefix every turn and defeat the purpose.
+     *  When set, the HTTP client emits the system as two content
+     *  blocks: { stable, cache_control: ephemeral } then { dynamic }.
+     *  The CLI client concatenates them since `claude -p` cannot
+     *  receive structured system content. */
+    systemDynamic?: string;
 }
 export interface ClaudeChatResponse {
     text: string;
@@ -57,6 +113,29 @@ export interface ClaudeChatResponse {
     /** Per-round audit of tool dispatches. Empty when no tools were
         provided or the model did not call any. */
     toolRounds: ToolRound[];
+    /** alpha.59z.14 F104 -- truncation detection. Populated when
+     *  the LAST round's output_tokens landed within
+     *  TRUNCATION_MARGIN_TOKENS of max_tokens, OR when the provider
+     *  explicitly reported stop_reason=max_tokens|length. Callers
+     *  should surface a ForgeError(E_RESPONSE_TRUNCATED) when this
+     *  is true. */
+    truncation?: {
+        truncated: boolean;
+        reason: string;
+        output_tokens: number;
+        max_tokens: number;
+    };
+    /** PND-055 (CR-D11) -- present solo en el cliente claude-code-cli.
+     *  El proposito del modo CLI es facturar contra la suscripcion
+     *  (apiKeySource="none"). Si el entorno del usuario forzo
+     *  ANTHROPIC_API_KEY, `claude -p` factura contra Console (dinero
+     *  real). Cuando billedToConsole=true el server avisa al usuario
+     *  en vez de cobrar en silencio. */
+    billedToConsole?: boolean;
+    /** True when the turn was stopped by an interrupt (panel "Detener"
+     *  or a relay control command). The text/toolRounds hold whatever
+     *  completed before the stop. */
+    interrupted?: boolean;
 }
 export interface ClaudeClientOptions {
     apiKey?: string;
@@ -65,6 +144,28 @@ export interface ClaudeClientOptions {
     /** Test injection for fetch (Node 18+ has global fetch). */
     fetchImpl?: typeof fetch;
 }
+/**
+ * Common surface every Forge chat client implements. Today two
+ * concrete impls exist:
+ *
+ *   - `ClaudeClient` (HTTP) -- direct Anthropic /v1/messages with the
+ *     full multi-turn tool-use loop owned in this process.
+ *   - `ClaudeCliClient` (subprocess) -- spawns `claude -p`, billed
+ *     against the user's Claude Code subscription; the subprocess
+ *     owns the tool-use loop and reports a single text result back.
+ *
+ *  Both can be substituted at the `let claude: ChatLLMClient` site in
+ *  `server.ts` and at the `Ctx.claude` field consumed by request
+ *  handlers, which only ever call `.chat()` on it. Use this type at
+ *  every wiring site so future providers (e.g. a managed-brain
+ *  fallback) can drop in without `as unknown` casts.
+ *
+ *  Source of truth for the message + tool + response shapes lives in
+ *  this file (ChatMessage / ClaudeChatRequest / ClaudeChatResponse).
+ */
+export interface ChatLLMClient {
+    chat(req: ClaudeChatRequest): Promise<ClaudeChatResponse>;
+}
 /**
  * Resolve the Anthropic API key.
  *
@@ -87,7 +188,7 @@ export interface ClaudeClientOptions {
  * users who configured Forge pre-BYOK.
  */
 export declare function resolveApiKey(injected?: string): Promise<string>;
-export declare class ClaudeClient {
+export declare class ClaudeClient implements ChatLLMClient {
     private apiKey;
     private fetchImpl;
     private defaultModel;

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

@@ -1 +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;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,aAAa,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAgEtE;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;CA0IhE"}
+{"version":3,"file":"claude.d.ts","sourceRoot":"","sources":["../../src/chat/claude.ts"],"names":[],"mappings":"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"}