@nac3/forge-cli 0.2.0-alpha.3 → 0.2.0-alpha.30

package/dist/chat/tools/audit_consumers.js

@@ -0,0 +1,231 @@
+/**
+ * forge_audit_consumers -- internal Forge tool to prevent
+ * producer/consumer desynchronization (SQ Sec X "Producer/Consumer
+ * Symmetry").
+ *
+ * Forge calls this BEFORE committing any change that touches a
+ * shared data structure (vault slot, JSON key, env var, tool name,
+ * endpoint contract, type / interface name, file format). The tool
+ * does a deterministic grep across src/ + tests/ + docs/ and
+ * returns every location that reads or writes the concept, so
+ * Forge can verify all readers are in sync with the new writer
+ * shape (and, if not, fix them in the same commit).
+ *
+ * This tool is the operational arm of SQ Sec X. Forge is expected
+ * to use it autonomously -- the user is never prompted to interpret
+ * the output; Forge interprets it and acts.
+ *
+ * The grep is pure file-system + glob; no LLM, no external services.
+ * Runs in < 1 second on the Forge tree itself (~10k files).
+ *
+ * Background: on 2026-05-29 the BYOK keys_setup refactor (290db8a)
+ * introduced provider_keys.json as the canonical key writer, but
+ * three downstream readers (chat resolveApiKey, Google STT provider,
+ * Google TTS provider) were not updated in the same commit. Each
+ * was patched independently (alpha.6 -> alpha.7 -> alpha.8). Had
+ * Forge run forge_audit_consumers('anthropic_api_key') and
+ * ('google_stt_key' / 'google_tts_key') before alpha.4 publish,
+ * the desync would have been caught up-front.
+ *
+ * ASCII-only.
+ */
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+export const AUDIT_CONSUMERS_SPEC = {
+    name: 'forge_audit_consumers',
+    description: 'Enumerate every file in the project that reads OR writes the '
+        + 'given concept (env var name, JSON key, type identifier, tool '
+        + 'name, vault slot, etc). Use this BEFORE any commit that '
+        + 'changes a shared data structure to verify all consumers are '
+        + 'in sync with the new producer shape. Returns hits classified '
+        + 'as write / read / test / doc with file path and line number. '
+        + 'Pure grep, no LLM. Required by SQ Sec X "Producer/Consumer '
+        + 'Symmetry".',
+    input_schema: {
+        type: 'object',
+        properties: {
+            concept: {
+                type: 'string',
+                description: 'The identifier to grep for. Examples: '
+                    + '"anthropic_api_key" / "google_tts_key" / '
+                    + '"forge_git_commit" / "provider_keys.json" / '
+                    + 'an exported type name.',
+            },
+            include_tests: {
+                type: 'boolean',
+                description: 'Include tests/ in the search. Default true.',
+            },
+            include_docs: {
+                type: 'boolean',
+                description: 'Include docs/ in the search. Default true.',
+            },
+            max_hits: {
+                type: 'number',
+                description: 'Cap on hits returned. Default 200. If exceeded, Forge '
+                    + 'should narrow the concept (it may be too generic).',
+            },
+        },
+        required: ['concept'],
+    },
+    requires_approval: false,
+};
+const SCAN_ROOTS = ['src', 'tests', 'docs', 'packages', 'apps'];
+const SKIP_DIRS = new Set([
+    'node_modules', 'dist', 'build', '.git', '.next', '.expo', '.wrangler',
+    'coverage', '.cache', '.vitest', 'android', 'ios', '_deploy_stage',
+]);
+const TEXT_EXTS = new Set([
+    '.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs',
+    '.json', '.yml', '.yaml', '.md', '.html', '.css',
+    '.php', '.py', '.sql', '.sh', '.toml', '.env',
+]);
+const WRITE_PATTERNS = [
+    /\bwrite\b/i,
+    /\b(set|put|store|persist|save|insert|create)\b/i,
+    /=\s*$/, // assignment at end of line
+    /:\s*['"`]/, // JSON-like field setting
+];
+const READ_PATTERNS = [
+    /\b(read|get|fetch|load|parse|consume|use)\b/i,
+    /\bif\b.*\b(has|includes|in)\b/i,
+];
+function classifyHit(filePath, snippet) {
+    const lower = filePath.toLowerCase();
+    if (lower.includes('test') || lower.includes('spec'))
+        return 'test';
+    if (lower.startsWith('docs/') || lower.startsWith('docs\\')
+        || lower.endsWith('.md') || lower.endsWith('.html'))
+        return 'doc';
+    for (const re of WRITE_PATTERNS) {
+        if (re.test(snippet))
+            return 'write';
+    }
+    for (const re of READ_PATTERNS) {
+        if (re.test(snippet))
+            return 'read';
+    }
+    return 'unknown';
+}
+async function walkAndSearch(root, rel, needle, out, limit) {
+    if (out.length >= limit)
+        return;
+    let entries;
+    try {
+        entries = await fs.readdir(root, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        if (out.length >= limit)
+            return;
+        if (SKIP_DIRS.has(entry.name))
+            continue;
+        const childPath = path.join(root, entry.name);
+        const childRel = rel ? `${rel}/${entry.name}` : entry.name;
+        if (entry.isDirectory()) {
+            await walkAndSearch(childPath, childRel, needle, out, limit);
+            continue;
+        }
+        if (!entry.isFile())
+            continue;
+        const ext = path.extname(entry.name).toLowerCase();
+        if (!TEXT_EXTS.has(ext))
+            continue;
+        let contents;
+        try {
+            contents = await fs.readFile(childPath, 'utf-8');
+        }
+        catch {
+            continue;
+        }
+        if (!needle.test(contents))
+            continue;
+        needle.lastIndex = 0;
+        const lines = contents.split(/\r?\n/);
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i];
+            if (line === undefined)
+                continue;
+            if (!needle.test(line)) {
+                needle.lastIndex = 0;
+                continue;
+            }
+            needle.lastIndex = 0;
+            const snippet = line.length > 200 ? line.slice(0, 200) : line;
+            out.push({
+                file: childRel,
+                line: i + 1,
+                snippet,
+                kind: classifyHit(childRel, snippet),
+            });
+            if (out.length >= limit)
+                return;
+        }
+    }
+}
+/** Build a regex that matches the concept as a whole word.
+ *  Escapes regex metacharacters in the input so the user can
+ *  pass "provider_keys.json" or "forge.X" without issue. */
+function buildNeedle(concept) {
+    const escaped = concept.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    /* Word-boundary-like (\b does not work for things containing
+     *  underscores in modern JS, so use a manual class). */
+    return new RegExp(`(?:^|[^a-zA-Z0-9_])${escaped}(?:$|[^a-zA-Z0-9_])`, 'gm');
+}
+export async function runAuditConsumers(args, ctx) {
+    const concept = String(args.concept || '').trim();
+    if (concept === '') {
+        return {
+            tool: AUDIT_CONSUMERS_SPEC.name,
+            is_error: true,
+            result: { error: 'concept (non-empty string) required' },
+            display: 'bad input',
+        };
+    }
+    const includeTests = args.include_tests !== false;
+    const includeDocs = args.include_docs !== false;
+    const limit = typeof args.max_hits === 'number' && args.max_hits > 0
+        ? Math.floor(args.max_hits) : 200;
+    const needle = buildNeedle(concept);
+    const hits = [];
+    for (const root of SCAN_ROOTS) {
+        if (root === 'tests' && !includeTests)
+            continue;
+        if (root === 'docs' && !includeDocs)
+            continue;
+        const abs = path.join(ctx.projectRoot, root);
+        try {
+            await fs.access(abs);
+        }
+        catch {
+            continue;
+        }
+        await walkAndSearch(abs, root, needle, hits, limit + 1);
+    }
+    const truncated = hits.length > limit;
+    if (truncated)
+        hits.length = limit;
+    const summary = { write: 0, read: 0, test: 0, doc: 0, unknown: 0 };
+    for (const h of hits)
+        summary[h.kind] += 1;
+    const result = {
+        concept,
+        hits,
+        truncated,
+        summary,
+    };
+    const displayParts = [
+        `${hits.length} hit(s) on "${concept}"`,
+        `write=${summary.write} read=${summary.read} test=${summary.test} doc=${summary.doc}`,
+    ];
+    if (truncated)
+        displayParts.push('(truncated)');
+    return {
+        tool: AUDIT_CONSUMERS_SPEC.name,
+        is_error: false,
+        result: result,
+        display: displayParts.join(' / '),
+    };
+}
+//# sourceMappingURL=audit_consumers.js.map

package/dist/chat/tools/audit_consumers.js.map

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

package/dist/chat/tools/git.js

@@ -65,7 +65,7 @@ async function resolveRepoDir(repoDir, ctx) {
  * Specs
  * ============================================================ */
 export const GIT_COMMIT_SPEC = {
-    name: 'forge.git_commit',
+    name: 'forge_git_commit',
     description: 'Commit staged changes (or all tracked changes with `all`=true) in the given git checkout. Returns the commit hash on success.',
     input_schema: {
         type: 'object',
@@ -79,7 +79,7 @@ export const GIT_COMMIT_SPEC = {
     requires_approval: true,
 };
 export const GIT_PUSH_SPEC = {
-    name: 'forge.git_push',
+    name: 'forge_git_push',
     description: 'Push the current branch to the configured remote. Set `force`=true ONLY for force-push (irreversible -- gated by the V1.10 liveness check).',
     input_schema: {
         type: 'object',
@@ -94,7 +94,7 @@ export const GIT_PUSH_SPEC = {
     requires_approval: true,
 };
 export const GIT_PULL_SPEC = {
-    name: 'forge.git_pull',
+    name: 'forge_git_pull',
     description: 'Pull from the configured remote. Fast-forward only by default.',
     input_schema: {
         type: 'object',
@@ -108,7 +108,7 @@ export const GIT_PULL_SPEC = {
     requires_approval: true,
 };
 export const GIT_LOG_SPEC = {
-    name: 'forge.git_log',
+    name: 'forge_git_log',
     description: 'List the last N commits of the given checkout. Default 10, max 50.',
     input_schema: {
         type: 'object',

package/dist/chat/tools/github.js

@@ -32,7 +32,7 @@ const VAULT_SLOT = 'github_token';
 const GITHUB_API = 'https://api.github.com';
 /* ------------------ Tool specs ------------------ */
 export const CREATE_GITHUB_REPO_SPEC = {
-    name: 'forge.create_github_repo',
+    name: 'forge_create_github_repo',
     description: 'Create a new repository under the authenticated GitHub user. Requires vault slot github_token with repo scope. Returns the new repository metadata including clone_url.',
     input_schema: {
         type: 'object',
@@ -46,7 +46,7 @@ export const CREATE_GITHUB_REPO_SPEC = {
     requires_approval: true,
 };
 export const CLONE_REPO_SPEC = {
-    name: 'forge.clone_repo',
+    name: 'forge_clone_repo',
     description: 'Clone a remote git repository to a local directory. Public repos need no auth. Private repos use the github_token slot when present. Returns the resolved target_dir + the first commit hash.',
     input_schema: {
         type: 'object',
@@ -59,7 +59,7 @@ export const CLONE_REPO_SPEC = {
     requires_approval: true,
 };
 export const BRANCH_STATUS_SPEC = {
-    name: 'forge.branch_status',
+    name: 'forge_branch_status',
     description: 'Read the current git branch + dirty-tree status of a local checkout. Returns branch name, ahead/behind counters vs upstream when present, list of dirty files (max 50).',
     input_schema: {
         type: 'object',

package/dist/chat/tools/lifecycle.js

@@ -37,7 +37,7 @@ let active = null;
  * Specs
  * ============================================================ */
 export const RUN_APP_SPEC = {
-    name: 'forge.run_app',
+    name: 'forge_run_app',
     description: 'Launch the project dev server. Auto-detects the package manager (npm / yarn / pnpm) and the script (dev / start / serve). Returns pid + best-effort URL.',
     input_schema: {
         type: 'object',
@@ -51,7 +51,7 @@ export const RUN_APP_SPEC = {
     requires_approval: true,
 };
 export const STOP_APP_SPEC = {
-    name: 'forge.stop_app',
+    name: 'forge_stop_app',
     description: 'Stop the running app spawned by forge.run_app. Returns the final logs tail.',
     input_schema: {
         type: 'object',
@@ -63,7 +63,7 @@ export const STOP_APP_SPEC = {
     requires_approval: true,
 };
 export const RESTART_APP_SPEC = {
-    name: 'forge.restart_app',
+    name: 'forge_restart_app',
     description: 'Stop the running app + relaunch with the same (or new) options.',
     input_schema: {
         type: 'object',

package/dist/chat/tools/manual.js

@@ -47,7 +47,7 @@ const MANUAL_PATH_CANDIDATES = (lang) => {
     return manualBaseDirs().map((dir) => path.join(dir, fname));
 };
 export const MANUAL_OPEN_SPEC = {
-    name: 'forge.manual.open',
+    name: 'forge_manual_open',
     description: 'Open the Yujin Forge user manual in the requested language (default: current user language). Resolves to docs/manuals/manual.<lang>.html and opens it through the reader pipeline so the user can navigate by voice. Available languages: es, en, pt, fr, ja, zh, hi, ar, de, it.',
     input_schema: {
         type: 'object',

package/dist/chat/tools/reader.js

@@ -45,7 +45,7 @@ export function _resetReaderForTests() {
  * Specs
  * ============================================================ */
 export const READER_OPEN_SPEC = {
-    name: 'forge.reader.open',
+    name: 'forge_reader_open',
     description: 'Open a document for reading. Auto-detects format (txt / md / source / ...). Returns the doc_id + title + section count + first block.',
     input_schema: {
         type: 'object',
@@ -57,13 +57,13 @@ export const READER_OPEN_SPEC = {
     requires_approval: false,
 };
 export const READER_LIST_DOCS_SPEC = {
-    name: 'forge.reader.list_documents',
+    name: 'forge_reader_list_documents',
     description: 'List all documents currently open in this chat session.',
     input_schema: { type: 'object', properties: {}, required: [] },
     requires_approval: false,
 };
 export const READER_READ_SECTION_SPEC = {
-    name: 'forge.reader.read_section',
+    name: 'forge_reader_read_section',
     description: 'Return the blocks of a section. With no index, returns the current section under the cursor.',
     input_schema: {
         type: 'object',
@@ -76,7 +76,7 @@ export const READER_READ_SECTION_SPEC = {
     requires_approval: false,
 };
 export const READER_NEXT_BLOCK_SPEC = {
-    name: 'forge.reader.next_block',
+    name: 'forge_reader_next_block',
     description: 'Advance the reader cursor one block forward. Returns the new block contents.',
     input_schema: {
         type: 'object',
@@ -88,7 +88,7 @@ export const READER_NEXT_BLOCK_SPEC = {
     requires_approval: false,
 };
 export const READER_SEARCH_SPEC = {
-    name: 'forge.reader.search',
+    name: 'forge_reader_search',
     description: 'Full-text search across a document. Returns top hits sorted by match count.',
     input_schema: {
         type: 'object',
@@ -102,7 +102,7 @@ export const READER_SEARCH_SPEC = {
     requires_approval: false,
 };
 export const READER_BOOKMARK_SET_SPEC = {
-    name: 'forge.reader.bookmark_set',
+    name: 'forge_reader_bookmark_set',
     description: 'Set a named bookmark at the current cursor position.',
     input_schema: {
         type: 'object',
@@ -115,7 +115,7 @@ export const READER_BOOKMARK_SET_SPEC = {
     requires_approval: false,
 };
 export const READER_BOOKMARK_JUMP_SPEC = {
-    name: 'forge.reader.bookmark_jump',
+    name: 'forge_reader_bookmark_jump',
     description: 'Jump the cursor to a previously-set bookmark.',
     input_schema: {
         type: 'object',
@@ -128,7 +128,7 @@ export const READER_BOOKMARK_JUMP_SPEC = {
     requires_approval: false,
 };
 export const READER_RECAP_SPEC = {
-    name: 'forge.reader.recap',
+    name: 'forge_reader_recap',
     description: 'Return the last N spoken blocks from the reader playback buffer. Default window 10. mode="summary" returns a Claude-generated 1-2 sentence summary instead of literal blocks (charges tokens; gated by env YF_ENABLE_CLAUDE_RECAP=1).',
     input_schema: {
         type: 'object',

package/dist/chat/tools/workflow.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Chat tool surface for the PRODUCT_WORKFLOW.md state machine.
+ *
+ * Three tools that let Forge drive the entire 18-step methodology
+ * from inside the chat panel, without the user dropping to the CLI:
+ *
+ *   forge_workflow_state(scope?)     read workflow state (full or scoped)
+ *   forge_workflow_set(group, patch) persist a patch under workflow.<group>
+ *   forge_workflow_run_step(step)    run an autonomous step
+ *                                     (legacy_audit, coverage, manual_generate,
+ *                                      handoff, metrics) without prompts
+ *
+ * Design notes:
+ *  - State write goes through the same module the CLI verbs use
+ *    (`src/workflow/state.ts`), so a chat session and a CLI session
+ *    see the same yujin.forge.json.
+ *  - `forge_workflow_run_step` only handles steps that do NOT
+ *    require the user to answer questions (legacy_audit reads the
+ *    project; coverage greps tests; manual_generate emits markdown
+ *    from existing state). Interactive steps (triage, discover,
+ *    clarify, approve) stay CLI-driven OR are driven by Forge
+ *    asking the user in chat + calling forge_workflow_set with the
+ *    collected answers.
+ *  - Per SQ Sec 14, Forge calls forge_audit_consumers before any
+ *    structural commit; this surface is read-mostly + persistence-
+ *    safe so it does not trip that rule.
+ *
+ * ASCII-only.
+ */
+import type { ToolContext, ToolResult, ToolSpec } from '../tools.js';
+export declare const WORKFLOW_STATE_SPEC: ToolSpec;
+export declare function runWorkflowState(args: {
+    scope?: string;
+}, ctx: ToolContext): Promise<ToolResult>;
+export declare const WORKFLOW_SET_SPEC: ToolSpec;
+export declare function runWorkflowSet(args: {
+    group?: string;
+    patch?: Record<string, unknown>;
+    top_level?: boolean;
+}, ctx: ToolContext): Promise<ToolResult>;
+export declare const WORKFLOW_RUN_STEP_SPEC: ToolSpec;
+export declare function runWorkflowRunStep(args: {
+    step?: string;
+}, ctx: ToolContext): Promise<ToolResult>;
+//# sourceMappingURL=workflow.d.ts.map

package/dist/chat/tools/workflow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow.d.ts","sourceRoot":"","sources":["../../../src/chat/tools/workflow.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAYrE,eAAO,MAAM,mBAAmB,EAAE,QAqBjC,CAAC;AAEF,wBAAsB,gBAAgB,CACpC,IAAI,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,EACxB,GAAG,EAAE,WAAW,GACf,OAAO,CAAC,UAAU,CAAC,CA+BrB;AAMD,eAAO,MAAM,iBAAiB,EAAE,QAkC/B,CAAC;AAWF,wBAAsB,cAAc,CAClC,IAAI,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,SAAS,CAAC,EAAE,OAAO,CAAA;CAAE,EAC9E,GAAG,EAAE,WAAW,GACf,OAAO,CAAC,UAAU,CAAC,CA4DrB;AAMD,eAAO,MAAM,sBAAsB,EAAE,QAwBpC,CAAC;AAEF,wBAAsB,kBAAkB,CACtC,IAAI,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,EACvB,GAAG,EAAE,WAAW,GACf,OAAO,CAAC,UAAU,CAAC,CA0ErB"}