@nac3/forge-cli 0.2.0-alpha.9 → 0.2.1-alpha.60

package/dist/chat/graph_component_watcher.js

@@ -0,0 +1,225 @@
+/**
+ * Graph component watcher (alpha.59w).
+ *
+ * Watches src/components, src/hooks, src/lib, src/core for new
+ * or modified .ts(x) files. On change, regex-parses the file for
+ * `export ...` declarations and upserts a graph node per export
+ * with confidence='auto'. Promotes to 'verified' via
+ * `yf graph add-node` (upsert).
+ *
+ * Pablo's expectation #3 (2026-06-02): "A medida que voy
+ * incorporando mas componentes los suma automaticamente al graph".
+ *
+ * Tech choices:
+ * - fs.watch (nodejs native) -- no chokidar dep. Cross-platform
+ *   recursive=true (Windows/macOS supported; Linux degrades to
+ *   non-recursive + polling fallback).
+ * - Regex-based export extraction (not full AST). Covers the
+ *   common patterns:
+ *     export function NAME(
+ *     export const NAME = ... | : type
+ *     export class NAME
+ *     export default function NAME(
+ *     export default class NAME
+ *   Skips: export type / export interface / re-exports (those
+ *   are not runtime primitives the LLM should "use, not reinvent").
+ * - Debounce 2s -- batch many saves into one ingest. The IDE
+ *   often writes 4-5 file events for a single save.
+ *
+ * Failure mode: never throws. Errors logged, watcher stays alive.
+ *
+ * ASCII-only.
+ */
+import { promises as fs, watch } from 'node:fs';
+import path from 'node:path';
+import { upsertNodes } from '../semantic_graph/store.js';
+import { extractExportsAst } from '../semantic_graph/ast_extract.js';
+const WATCHED_DIRS = ['src/components', 'src/hooks', 'src/lib', 'src/core'];
+const ALLOWED_EXT = new Set(['.ts', '.tsx', '.js', '.jsx']);
+const DEBOUNCE_MS = 2000;
+/** PND-020 Phase 2a -- AST-based extraction. The earlier regex
+ *  implementation is gone; the public shape is preserved so callers
+ *  (including the watcher + the test suite) work unchanged. types
+ *  + interfaces are filtered here too (they aren't runtime
+ *  primitives). For the full picture call extractExportsAst. */
+export function extractExports(source, fileName = 'in.tsx') {
+    return extractExportsAst(source, fileName)
+        .filter((e) => e.kind !== 'type' && e.kind !== 'interface')
+        .map((e) => ({ name: e.name, kind: e.kind }));
+}
+/** Sanitise a file path to a stable graph node id. */
+function fileToNodeIdBase(projectRoot, fullPath) {
+    const rel = path.relative(projectRoot, fullPath).replace(/\\/g, '/');
+    return rel.replace(/[^a-z0-9\-_./]/gi, '-').replace(/[/.]+/g, '-').toLowerCase();
+}
+/** Build node payloads from a file change. PND-020 Phase 2a -- uses
+ *  the AST extractor for is_component / is_hook / jsdoc signals. */
+async function nodesForFile(projectRoot, _projectSlug, filePath) {
+    let src = '';
+    try {
+        src = await fs.readFile(filePath, 'utf-8');
+    }
+    catch {
+        return [];
+    }
+    /* Drop type + interface -- they aren't runtime primitives the
+     * LLM should "use, not reinvent". The AST extractor surfaces them
+     * for callers that want the full picture; the watcher filters. */
+    const exports = extractExportsAst(src, path.basename(filePath))
+        .filter((e) => e.kind !== 'type' && e.kind !== 'interface');
+    if (exports.length === 0)
+        return [];
+    const fileBase = fileToNodeIdBase(projectRoot, filePath);
+    const rel = path.relative(projectRoot, filePath).replace(/\\/g, '/');
+    const now = new Date().toISOString();
+    return exports.map((e) => {
+        /* Tighter classification: actually returns JSX, not just name +
+         * path heuristic. Hooks still come back as 'module' (they don't
+         * render); they get a 'hook' tag in solves so the LLM can find
+         * them via "use X" intent. */
+        const solves = [];
+        if (e.is_hook)
+            solves.push('hook');
+        if (e.is_component)
+            solves.push('component');
+        const purpose = e.jsdoc
+            ? e.jsdoc
+            : e.kind + ' exported from ' + rel + '. Auto-extracted via AST.';
+        return {
+            id: 'comp.' + fileBase + '-' + e.name.toLowerCase(),
+            kind: e.is_component ? 'component' : 'module',
+            name: e.name,
+            source: 'ast',
+            purpose,
+            solves,
+            do_not_invent: [],
+            api_surface: [e.name],
+            confidence: 'auto',
+            weight: e.is_component ? 0.6 : 0.5,
+            added_at: now,
+            updated_at: now,
+        };
+    });
+}
+/** Start watching the project's source dirs. Returns a handle
+ *  with .stop() to close all watchers on server shutdown.
+ *  NEVER throws. */
+export async function startComponentWatcher(opts) {
+    const log = opts.log ?? (() => undefined);
+    /* Env gate: YF_COMPONENT_WATCHER=0 disables. Default ON. */
+    const envOff = process.env.YF_COMPONENT_WATCHER;
+    if (envOff === '0' || envOff === 'false' || envOff === 'no') {
+        log('[component-watcher] disabled via YF_COMPONENT_WATCHER=0');
+        return { stop: async () => undefined };
+    }
+    const watchers = [];
+    let pendingFiles = new Set();
+    let debounceTimer = null;
+    async function flush() {
+        debounceTimer = null;
+        const files = Array.from(pendingFiles);
+        pendingFiles = new Set();
+        if (files.length === 0)
+            return;
+        log('[component-watcher] flushing ' + files.length + ' file(s)...');
+        const allNodes = [];
+        for (const f of files) {
+            try {
+                const nodes = await nodesForFile(opts.project_root, opts.project_slug, f);
+                for (const n of nodes)
+                    allNodes.push(n);
+            }
+            catch { /* skip individual file errors */ }
+        }
+        if (allNodes.length === 0) {
+            log('[component-watcher] no exports extracted from batch -- skip');
+            return;
+        }
+        try {
+            /* alpha.59z.182 -- write to the LOCAL SQLite store; no
+             * worker call. */
+            const r = await upsertNodes(opts.project_slug, allNodes);
+            log('[component-watcher] local OK added=' + r.inserted + ' updated=' + r.updated);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            log('[component-watcher] error: ' + msg);
+        }
+        /* GRAPH-1 (dogfood 2026-06-10) -- auto-regenerar el grafo de
+         * modulos + aristas en cada cambio de codigo (lo que Pablo
+         * pidio: "con cada cambio Forge regenera solo"). El debounce de
+         * 2s ya batchea; enrich=false para no pegar a npm en caliente. */
+        try {
+            const { regenerateAndPersist } = await import('../semantic_graph/derive.js');
+            const s = await regenerateAndPersist({ project_root: opts.project_root, project_slug: opts.project_slug, enrich: false });
+            log('[component-watcher] graph regen -> ' + (s.module_edges + s.lib_edges) + ' edges (' + s.pruned + ' pruned)');
+        }
+        catch (err) {
+            log('[component-watcher] regen error: ' + (err instanceof Error ? err.message : String(err)));
+        }
+    }
+    function enqueue(filePath) {
+        pendingFiles.add(filePath);
+        if (debounceTimer)
+            clearTimeout(debounceTimer);
+        debounceTimer = setTimeout(() => { void flush(); }, DEBOUNCE_MS);
+    }
+    for (const sub of WATCHED_DIRS) {
+        const dir = path.join(opts.project_root, sub);
+        try {
+            const st = await fs.stat(dir);
+            if (!st.isDirectory())
+                continue;
+        }
+        catch {
+            continue;
+        }
+        try {
+            /* recursive: true is supported on Windows + macOS; on Linux
+             * it silently degrades to non-recursive. We accept that for
+             * v1 -- Pablo dev environment is Windows. */
+            const w = watch(dir, { recursive: true }, (_ev, filename) => {
+                if (!filename)
+                    return;
+                const ext = path.extname(filename.toString());
+                if (!ALLOWED_EXT.has(ext))
+                    return;
+                const full = path.join(dir, filename.toString());
+                enqueue(full);
+            });
+            /* fs.FSWatcher emite 'error' (el dir se borra, problema del
+             * FS en Windows, restart durante reanchor). Sin handler, se
+             * propaga como uncaughtException y MATA el proceso. */
+            w.on('error', (err) => {
+                log('[component-watcher] watch error on ' + sub + ': ' + (err instanceof Error ? err.message : String(err)));
+                try {
+                    w.close();
+                }
+                catch { /* */ }
+            });
+            watchers.push(w);
+            log('[component-watcher] watching ' + sub);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            log('[component-watcher] could not watch ' + sub + ': ' + msg);
+        }
+    }
+    return {
+        stop: async () => {
+            if (debounceTimer) {
+                clearTimeout(debounceTimer);
+                debounceTimer = null;
+            }
+            for (const w of watchers) {
+                try {
+                    w.close();
+                }
+                catch { /* */ }
+            }
+        },
+    };
+}
+/** Test seam. */
+export const _internal = { fileToNodeIdBase, nodesForFile };
+//# sourceMappingURL=graph_component_watcher.js.map

package/dist/chat/graph_component_watcher.js.map

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

package/dist/chat/graph_snapshot.d.ts

@@ -0,0 +1,38 @@
+export interface GraphSnapshotNode {
+    id: string;
+    kind: string;
+    label?: string;
+}
+export interface FetcherResult {
+    ok: boolean;
+    nodes: GraphSnapshotNode[];
+}
+export type SnapshotFetcher = (project_slug: string) => Promise<FetcherResult>;
+export interface BuildOpts {
+    project_slug: string;
+    fetcher: SnapshotFetcher;
+    /** Cap on the rendered text. When a kind's nodes would overflow
+     *  the budget, the list is truncated with "... +N more". */
+    max_tokens?: number;
+    /** TTL for the per-slug cache. Default 300s (5 min). */
+    ttl_ms?: number;
+    /** Override Date.now for deterministic tests. */
+    clock?: () => number;
+}
+export interface GraphSnapshotResult {
+    /** Whether the fetcher succeeded. ok=true with text="" means
+     *  "fetched, but no nodes yet" (empty project / fresh ingest). */
+    ok: boolean;
+    text: string;
+    hash: string;
+    nodes: GraphSnapshotNode[];
+    cached: boolean;
+}
+export declare function _resetSnapshotCacheForTests(): void;
+/**
+ * Build the snapshot section for a project, with per-slug hash cache.
+ * Failure mode: graceful -- never throws.
+ */
+export declare function buildGraphSnapshotSection(opts: BuildOpts): Promise<GraphSnapshotResult>;
+export declare function filterSnapshotForRole(snapshot: GraphSnapshotResult, role: string): string;
+//# sourceMappingURL=graph_snapshot.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"graph_snapshot.d.ts","sourceRoot":"","sources":["../../src/chat/graph_snapshot.ts"],"names":[],"mappings":"AAsBA,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAM,MAAM,CAAC;IACf,IAAI,EAAI,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAK,OAAO,CAAC;IACf,KAAK,EAAE,iBAAiB,EAAE,CAAC;CAC5B;AAED,MAAM,MAAM,eAAe,GAAG,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC,aAAa,CAAC,CAAC;AAE/E,MAAM,WAAW,SAAS;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAO,eAAe,CAAC;IAC9B;gEAC4D;IAC5D,UAAU,CAAC,EAAG,MAAM,CAAC;IACrB,wDAAwD;IACxD,MAAM,CAAC,EAAO,MAAM,CAAC;IACrB,iDAAiD;IACjD,KAAK,CAAC,EAAQ,MAAM,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,mBAAmB;IAClC;sEACkE;IAClE,EAAE,EAAM,OAAO,CAAC;IAChB,IAAI,EAAI,MAAM,CAAC;IACf,IAAI,EAAI,MAAM,CAAC;IACf,KAAK,EAAG,iBAAiB,EAAE,CAAC;IAC5B,MAAM,EAAE,OAAO,CAAC;CACjB;AA8BD,wBAAgB,2BAA2B,IAAI,IAAI,CAElD;AA6DD;;;GAGG;AACH,wBAAsB,yBAAyB,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAgC7F;AAcD,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,mBAAmB,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAgBzF"}

package/dist/chat/graph_snapshot.js

@@ -0,0 +1,159 @@
+/**
+ * Project graph snapshot (Director sprint phase II, slice 11).
+ *
+ * Compact panoramic view of the project graph that the chat
+ * system prompt + every agent run receive every turn. Refresh is
+ * hash-based: when the rendered text didn't change, the cached
+ * string is reused without any system-prompt drift cost.
+ *
+ * This is the structural complement to the existing per-intent
+ * relevance injection in semantic_graph_inject.ts. The chat
+ * gets BOTH: this snapshot above (panorama) + the relevance
+ * section below (zoom). Agents only get this snapshot, filtered
+ * by their role -- they have no "user message" to rank against.
+ *
+ * Failure mode: graceful. If the fetcher returns ok=false or
+ * throws, the section is "" and the chat / agent continues
+ * without it.
+ *
+ * ASCII-only.
+ */
+import crypto from 'node:crypto';
+/* The kinds we render, in order. New worker-side kinds appear
+ * under "other" so the snapshot is forward-compatible. */
+const KIND_ORDER = [
+    { key: 'entity', label: 'entities' },
+    { key: 'endpoint', label: 'endpoints' },
+    { key: 'component', label: 'components' },
+    { key: 'utility', label: 'utilities' },
+    { key: 'agent', label: 'agents' },
+    { key: 'doctrine', label: 'doctrines' },
+    { key: 'template', label: 'templates' },
+];
+const FOOTER = [
+    '',
+    'When you reference a primitive from this snapshot, USE that ID.',
+    'Do NOT reinvent. For full schema of one primitive, call',
+    'yujin.semantic-graph.get({id}).',
+].join('\n');
+const CACHE = new Map();
+export function _resetSnapshotCacheForTests() {
+    CACHE.clear();
+}
+/** Approximate token budget into char budget (4 chars/token). */
+function tokenBudgetToChars(tokens) {
+    return tokens * 4;
+}
+function renderSnapshot(nodes, maxTokens, hash, fetchedAt) {
+    if (nodes.length === 0)
+        return '';
+    const lines = [];
+    /* Header carries the hash + a human time so the LLM (and a
+     * developer reading the prompt log) can tell at a glance when
+     * the snapshot was last refreshed. */
+    const ts = new Date(fetchedAt).toISOString().slice(11, 19);
+    lines.push('PROJECT GRAPH SNAPSHOT (fresh at ' + ts + ' UTC; hash ' + hash.slice(0, 8) + '):');
+    lines.push('');
+    const charBudget = Math.max(200, tokenBudgetToChars(maxTokens));
+    /* Reserve room for the footer + the header lines. */
+    let charsLeft = charBudget - FOOTER.length - lines.join('\n').length;
+    for (const { key, label } of KIND_ORDER) {
+        const kindNodes = nodes.filter((n) => n.kind === key);
+        if (kindNodes.length === 0)
+            continue;
+        const labels = kindNodes.map((n) => n.label || n.id);
+        /* Pad header label to a fixed width for alignment when read in
+         * raw text. */
+        const padded = (label + '          ').slice(0, 14);
+        let row = '  ' + padded + labels.join(', ');
+        if (row.length + 1 > charsLeft) {
+            /* Truncate the list, append "... +N more" so the LLM knows
+             * there are more nodes than rendered. */
+            const head = [];
+            let used = ('  ' + padded).length;
+            let kept = 0;
+            for (const lab of labels) {
+                const grow = head.length === 0 ? lab.length : 2 + lab.length;
+                if (used + grow + 12 > charsLeft)
+                    break;
+                head.push(lab);
+                used += grow;
+                kept += 1;
+            }
+            const remainder = labels.length - kept;
+            row = '  ' + padded + head.join(', ') + (remainder > 0 ? ', ... +' + remainder + ' more' : '');
+        }
+        lines.push(row);
+        charsLeft -= (row.length + 1);
+        if (charsLeft < 40)
+            break;
+    }
+    lines.push(FOOTER);
+    return lines.join('\n');
+}
+function hashNodes(nodes) {
+    /* Stable hash: sort by id+kind so reordering does not produce
+     * a fake mutation. */
+    const sorted = nodes.map((n) => n.kind + ':' + n.id).sort();
+    return crypto.createHash('sha256').update(sorted.join('\n')).digest('hex');
+}
+/**
+ * Build the snapshot section for a project, with per-slug hash cache.
+ * Failure mode: graceful -- never throws.
+ */
+export async function buildGraphSnapshotSection(opts) {
+    const slug = opts.project_slug;
+    const maxTk = opts.max_tokens ?? 400;
+    const ttl = opts.ttl_ms ?? 300_000;
+    const now = (opts.clock ?? Date.now)();
+    const cached = CACHE.get(slug);
+    if (cached && (now - cached.fetched_at) < ttl) {
+        return {
+            ok: true,
+            text: cached.text,
+            hash: cached.hash,
+            nodes: cached.nodes,
+            cached: true,
+        };
+    }
+    let fetched;
+    try {
+        fetched = await opts.fetcher(slug);
+    }
+    catch {
+        return { ok: false, text: '', hash: '', nodes: [], cached: false };
+    }
+    if (!fetched.ok) {
+        return { ok: false, text: '', hash: '', nodes: [], cached: false };
+    }
+    const hash = hashNodes(fetched.nodes);
+    const text = renderSnapshot(fetched.nodes, maxTk, hash, now);
+    CACHE.set(slug, { text, hash, nodes: fetched.nodes, fetched_at: now });
+    return { ok: true, text, hash, nodes: fetched.nodes, cached: false };
+}
+/* ============================================================
+ * Per-agent role filter.
+ * ============================================================ */
+const ROLE_KINDS = {
+    director: ['entity', 'endpoint', 'component', 'utility', 'agent', 'doctrine', 'template'],
+    analyst: ['entity', 'endpoint', 'doctrine'],
+    coder: ['component', 'utility', 'doctrine', 'template'],
+    tester: ['endpoint', 'doctrine'],
+    scaffolder: ['doctrine'],
+};
+export function filterSnapshotForRole(snapshot, role) {
+    const allowed = ROLE_KINDS[role];
+    /* Unknown role -> render the full set of nodes so a freshly
+     * added agent role still receives panorama. The maintainer can
+     * tighten the subset later by adding a ROLE_KINDS row. */
+    const nodes = allowed
+        ? snapshot.nodes.filter((n) => allowed.includes(n.kind))
+        : snapshot.nodes;
+    if (nodes.length === 0)
+        return '';
+    const hash = snapshot.hash || hashNodes(nodes);
+    const fakeNow = Date.now();
+    const body = renderSnapshot(nodes, 600, hash, fakeNow);
+    return body.replace(/PROJECT GRAPH SNAPSHOT \(fresh at[^)]+\):/, 'PROJECT GRAPH SNAPSHOT (filtered for ' + role + '):');
+}
+//# sourceMappingURL=graph_snapshot.js.map

package/dist/chat/graph_snapshot.js.map

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

package/dist/chat/ingest_session.d.ts

@@ -1,16 +1,24 @@
 /**
- * Spec ingest sessions (V1.40 of HITO 1).
+ * Spec ingest sessions (V1.40 of HITO 1 + Director sprint slice 9).
  *
  * Holds the NormalisedDocument + flattened-text + extracted
  * structure for every spec the user has dropped on the chat
- * panel. The data lives in memory while the chat server runs;
- * it is not persisted because the user has not yet approved
- * scaffolding (V1.42).
+ * panel.
  *
  * Module-scope so V1.38 ingest, V1.40 extract, V1.41 plan,
  * V1.42 approval, V1.43 scaffold can all see the same doc
  * without threading state through the HTTP layer.
  *
+ * Persistence (slice 9): every mutation flushes the affected
+ * session to ~/.yujin-forge/ingest/<project_slug>/<doc_id>.json.
+ * On boot the chat server calls loadProjectIngests(slug) to
+ * hydrate the in-memory map. This fixes the HITO 4 bug where
+ * extract+plan didn't survive a server restart.
+ *
+ * Back-compat: when the project slug is null (legacy callers,
+ * unit tests that did not set one), persistence is skipped --
+ * the module still works as a pure in-memory cache.
+ *
  * ASCII-only.
  */
 import type { NormalisedDocument } from '../reader/types.js';
@@ -72,6 +80,18 @@ export interface IngestSession {
  *  chars at ~4 chars/token = ~16K tokens, comfortably under
  *  Claude's input budget for the extraction call. */
 export declare const FLATTEN_MAX_CHARS: number;
+export declare function setProjectSlugForIngest(slug: string | null): void;
+export declare function ingestStoreRoot(): string;
+/** Wait for every queued persist to settle. The chat server calls
+ *  this from close() so that test teardowns (which fs.rm the home
+ *  directory immediately after close) do not race with in-flight
+ *  fire-and-forget writes. */
+export declare function flushPendingIngestWrites(): Promise<void>;
+/** Hydrate SESSIONS from disk for `<project_slug>`. Idempotent;
+ *  safe to call multiple times. Existing in-memory entries with
+ *  the same doc_id are overwritten by the disk copy (disk is the
+ *  source of truth across restarts). */
+export declare function loadProjectIngests(slug: string): Promise<void>;
 /** Build the flattened-text view of a NormalisedDocument. */
 export declare function flattenDocument(doc: NormalisedDocument): {
     text: string;

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

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