@nac3/forge-cli 1.0.58 → 1.0.59

package/dist/docs/doctrine/concurrency-scale.md

@@ -0,0 +1,54 @@
+# Concurrency & scale doctrine
+
+Every application Forge designs MUST be sized to its expected
+concurrency from day one. Scale is a RELEVAMIENTO input, not an
+afterthought bolted on when the app falls over.
+
+## 1. Ask it during requirements
+
+During the greenfield relevamiento -- and when scoping a corrective /
+evolutive change that touches a load-bearing path -- ASK, before
+choosing an architecture:
+
+- Peak SIMULTANEOUS users / requests? Give an order of magnitude:
+  tens, hundreds, thousands, 10k+.
+- Read-heavy or write-heavy? Steady or bursty (spikes)?
+- Latency budget: interactive (< ~200 ms) or batch/async?
+- Growth horizon: will it 10x within a year?
+- Consistency needs: strong (banking) or eventual (feeds)?
+
+If the user does not know, PROPOSE a reasonable default AND write the
+assumption explicitly in the spec / `<root>/.forge/sumi-context.md`.
+Never silently assume "a handful of users".
+
+## 2. Design a multi-layer architecture with no bottleneck at any tier
+
+Pick the layers that the target number actually needs, and make each
+one non-blocking:
+
+- Client: pagination, debounce, optimistic UI, local cache -- do not
+  fetch the world on every keystroke.
+- Edge / CDN: serve static + cacheable responses close to the user.
+- App tier: STATELESS request handlers so nodes scale horizontally.
+  No in-process session/user state that pins a user to one node
+  (put it in a shared store / signed token).
+- Concurrency control: connection pools sized to the DB; queues +
+  backpressure to absorb spikes; idempotency keys for retried writes;
+  rate limits / circuit breakers on hot paths.
+- Data tier (the usual bottleneck): indexed queries; read replicas
+  for read-heavy loads; a cache (Redis / KV) in front of hot reads;
+  async jobs for slow writes; partition / shard ONLY when the numbers
+  demand it.
+- Realtime: fan out via a broker (Redis pub/sub, a queue, a hub), not
+  an N-app-node polling loop.
+
+## 3. Proportionality (do not gold-plate)
+
+Match the architecture to the number. A 20-user internal tool gets a
+simple single-tier design -- adding sharding + a message broker there
+is a defect too. A 10k-concurrent public app gets the full multi-layer
+treatment. The rule is "no bottleneck AND no gold-plating", sized to
+the stated concurrency.
+
+Record the target concurrency and the tier decisions in the spec so
+they are traceable and can be revisited when the number changes.

package/dist/semantic_graph/last_change.d.ts

@@ -0,0 +1,9 @@
+/** relPath (posix slashes) -> unix seconds of the file's most recent commit.
+ *  Empty map when git is unavailable / not a repo (caller falls to mtime). */
+export declare function fileLastChangeMap(projectRoot: string): Promise<Map<string, number>>;
+/** Resolve a node's last-change ts: git map by path, else fs mtime, else 0. */
+export declare function nodeLastChange(projectRoot: string, relPath: string, gitMap: Map<string, number>): Promise<number>;
+/** Server-side twin of the panel's graphNodePath: the last path-like
+ *  parenthetical in a node's purpose/detail ("... (src/foo.py)."). */
+export declare function pathFromPurpose(purpose: string): string;
+//# sourceMappingURL=last_change.d.ts.map

package/dist/semantic_graph/last_change.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"last_change.d.ts","sourceRoot":"","sources":["../../src/semantic_graph/last_change.ts"],"names":[],"mappings":"AAaA;8EAC8E;AAC9E,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAoBnF;AAED,+EAA+E;AAC/E,wBAAsB,cAAc,CAClC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAChE,OAAO,CAAC,MAAM,CAAC,CAOjB;AAED;sEACsE;AACtE,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CA4BvD"}

package/dist/semantic_graph/last_change.js

@@ -0,0 +1,93 @@
+/**
+ * Per-file "last change" timestamp for the galaxy graph colouring (Pablo,
+ * 2026-07-05). One `git log` pass yields the most-recent commit time per
+ * tracked file; the filesystem mtime is the fallback for untracked files.
+ * The panel normalises these across nodes and colours newest -> blue,
+ * oldest -> red (full spectrum).
+ *
+ * ASCII-only.
+ */
+import { execFile } from 'node:child_process';
+import { stat } from 'node:fs/promises';
+import { join } from 'node:path';
+/** relPath (posix slashes) -> unix seconds of the file's most recent commit.
+ *  Empty map when git is unavailable / not a repo (caller falls to mtime). */
+export function fileLastChangeMap(projectRoot) {
+    return new Promise((resolve) => {
+        execFile('git', ['log', '--format=%ct', '--name-only', '--no-renames'], { cwd: projectRoot, maxBuffer: 128 * 1024 * 1024, windowsHide: true }, (err, stdout) => {
+            const map = new Map();
+            if (err || !stdout) {
+                resolve(map);
+                return;
+            }
+            let ts = 0;
+            for (const raw of String(stdout).split('\n')) {
+                const line = raw.trim();
+                if (!line)
+                    continue;
+                if (/^\d+$/.test(line)) {
+                    ts = parseInt(line, 10);
+                    continue;
+                }
+                const rel = line.replace(/\\/g, '/');
+                if (!map.has(rel))
+                    map.set(rel, ts); // git log is newest-first: first wins
+            }
+            resolve(map);
+        });
+    });
+}
+/** Resolve a node's last-change ts: git map by path, else fs mtime, else 0. */
+export async function nodeLastChange(projectRoot, relPath, gitMap) {
+    if (!relPath)
+        return 0;
+    const rel = relPath.replace(/\\/g, '/');
+    const g = gitMap.get(rel);
+    if (g)
+        return g;
+    try {
+        const st = await stat(join(projectRoot, rel));
+        return Math.floor(st.mtimeMs / 1000);
+    }
+    catch {
+        return 0;
+    }
+}
+/** Server-side twin of the panel's graphNodePath: the last path-like
+ *  parenthetical in a node's purpose/detail ("... (src/foo.py)."). */
+export function pathFromPurpose(purpose) {
+    const d = String(purpose || '');
+    const cands = [];
+    let i = 0;
+    while (i < d.length) {
+        const open = d.indexOf('(', i);
+        if (open < 0)
+            break;
+        const close = d.indexOf(')', open + 1);
+        if (close < 0)
+            break;
+        cands.push(d.slice(open + 1, close).trim());
+        i = close + 1;
+    }
+    for (let k = cands.length - 1; k >= 0; k--) {
+        let inner = cands[k] || '';
+        if (!inner || inner.length > 240)
+            continue;
+        while (inner.length && '.,;'.indexOf(inner.charAt(inner.length - 1)) >= 0)
+            inner = inner.slice(0, -1);
+        const hasSep = inner.indexOf('/') >= 0 || inner.indexOf('\\') >= 0;
+        let hasExt = false;
+        const dot = inner.lastIndexOf('.');
+        if (dot > 0 && dot < inner.length - 1) {
+            const ext = inner.slice(dot + 1);
+            hasExt = ext.length <= 8 && /^[a-z0-9]+$/i.test(ext);
+        }
+        if (!hasSep && !hasExt)
+            continue;
+        if (inner.indexOf(' ') >= 0 && !hasSep)
+            continue;
+        return inner;
+    }
+    return '';
+}
+//# sourceMappingURL=last_change.js.map

package/dist/semantic_graph/last_change.js.map

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

package/dist/version.d.ts

@@ -2,5 +2,5 @@
  * Yujin Forge CLI version. Kept in sync with package.json by the npm
  * "version" lifecycle (scripts/sync_version.mjs) so the two never drift.
  */
-export declare const VERSION = "1.0.58";
+export declare const VERSION = "1.0.59";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -2,5 +2,5 @@
  * Yujin Forge CLI version. Kept in sync with package.json by the npm
  * "version" lifecycle (scripts/sync_version.mjs) so the two never drift.
  */
-export const VERSION = '1.0.58';
+export const VERSION = '1.0.59';
 //# sourceMappingURL=version.js.map

package/docs/doctrine/concurrency-scale.md

@@ -0,0 +1,54 @@
+# Concurrency & scale doctrine
+
+Every application Forge designs MUST be sized to its expected
+concurrency from day one. Scale is a RELEVAMIENTO input, not an
+afterthought bolted on when the app falls over.
+
+## 1. Ask it during requirements
+
+During the greenfield relevamiento -- and when scoping a corrective /
+evolutive change that touches a load-bearing path -- ASK, before
+choosing an architecture:
+
+- Peak SIMULTANEOUS users / requests? Give an order of magnitude:
+  tens, hundreds, thousands, 10k+.
+- Read-heavy or write-heavy? Steady or bursty (spikes)?
+- Latency budget: interactive (< ~200 ms) or batch/async?
+- Growth horizon: will it 10x within a year?
+- Consistency needs: strong (banking) or eventual (feeds)?
+
+If the user does not know, PROPOSE a reasonable default AND write the
+assumption explicitly in the spec / `<root>/.forge/sumi-context.md`.
+Never silently assume "a handful of users".
+
+## 2. Design a multi-layer architecture with no bottleneck at any tier
+
+Pick the layers that the target number actually needs, and make each
+one non-blocking:
+
+- Client: pagination, debounce, optimistic UI, local cache -- do not
+  fetch the world on every keystroke.
+- Edge / CDN: serve static + cacheable responses close to the user.
+- App tier: STATELESS request handlers so nodes scale horizontally.
+  No in-process session/user state that pins a user to one node
+  (put it in a shared store / signed token).
+- Concurrency control: connection pools sized to the DB; queues +
+  backpressure to absorb spikes; idempotency keys for retried writes;
+  rate limits / circuit breakers on hot paths.
+- Data tier (the usual bottleneck): indexed queries; read replicas
+  for read-heavy loads; a cache (Redis / KV) in front of hot reads;
+  async jobs for slow writes; partition / shard ONLY when the numbers
+  demand it.
+- Realtime: fan out via a broker (Redis pub/sub, a queue, a hub), not
+  an N-app-node polling loop.
+
+## 3. Proportionality (do not gold-plate)
+
+Match the architecture to the number. A 20-user internal tool gets a
+simple single-tier design -- adding sharding + a message broker there
+is a defect too. A 10k-concurrent public app gets the full multi-layer
+treatment. The rule is "no bottleneck AND no gold-plating", sized to
+the stated concurrency.
+
+Record the target concurrency and the tier decisions in the spec so
+they are traceable and can be revisited when the number changes.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nac3/forge-cli",
-  "version": "1.0.58",
+  "version": "1.0.59",
   "description": "Yujin Forge -- voice-first NAC-3 React development framework. CLI + chat panel + spec ingest + 10-format document reader + voice loop.",
   "license": "SEE LICENSE IN LICENSE",
   "author": "Pablo Kuschnirof <pablo@rpaforce.com>",