@zigrivers/scaffold 3.27.0 → 3.29.0

package/dist/utils/fs.js

@@ -94,4 +94,17 @@ export function getPackageMethodologyDir(projectRoot) {
     }
     return path.join(getPackageRoot(), 'content', 'methodology');
 }
+/**
+ * Resolve the guides directory.
+ * If projectRoot is provided and contains content/guides/, use that (dev/test mode).
+ * Otherwise use the package's bundled content/guides/.
+ */
+export function getPackageGuidesDir(projectRoot) {
+    if (projectRoot) {
+        const local = path.join(projectRoot, 'content', 'guides');
+        if (fs.existsSync(local))
+            return local;
+    }
+    return path.join(getPackageRoot(), 'content', 'guides');
+}
 //# sourceMappingURL=fs.js.map

package/dist/utils/fs.js.map

@@ -1 +1 @@
-{"version":3,"file":"fs.js","sourceRoot":"","sources":["../../src/utils/fs.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"fs.js","sourceRoot":"","sources":["../../src/utils/fs.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAA;AACxB,OAAO,IAAI,MAAM,WAAW,CAAA;AAC5B,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AAExC;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,QAAgB,EAAE,OAAe;IAC/D,MAAM,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAA;IACjC,EAAE,CAAC,aAAa,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,CAAA;IAC1C,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAA;AAClC,CAAC;AAED,2CAA2C;AAC3C,MAAM,UAAU,UAAU,CAAC,QAAgB;IACzC,OAAO,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAA;AAChC,CAAC;AAED,oEAAoE;AACpE,MAAM,UAAU,SAAS,CAAC,OAAe;IACvC,EAAE,CAAC,SAAS,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;AAC5C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,cAAc;IAC5B,MAAM,QAAQ,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;IAC/C,2DAA2D;IAC3D,4CAA4C;IAC5C,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,CAAA;AACzD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CAAC,WAAoB;IACxD,IAAI,WAAW,EAAE,CAAC;QAChB,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,SAAS,EAAE,UAAU,CAAC,CAAA;QAC3D,IAAI,EAAE,CAAC,UAAU,CAAC,KAAK,CAAC;YAAE,OAAO,KAAK,CAAA;IACxC,CAAC;IACD,OAAO,IAAI,CAAC,IAAI,CAAC,cAAc,EAAE,EAAE,SAAS,EAAE,UAAU,CAAC,CAAA;AAC3D,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,sBAAsB,CAAC,WAAoB;IACzD,IAAI,WAAW,EAAE,CAAC;QAChB,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,SAAS,EAAE,WAAW,CAAC,CAAA;QAC5D,IAAI,EAAE,CAAC,UAAU,CAAC,KAAK,CAAC;YAAE,OAAO,KAAK,CAAA;IACxC,CAAC;IACD,OAAO,IAAI,CAAC,IAAI,CAAC,cAAc,EAAE,EAAE,SAAS,EAAE,WAAW,CAAC,CAAA;AAC5D,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,WAAoB;IACrD,IAAI,WAAW,EAAE,CAAC;QAChB,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,SAAS,EAAE,OAAO,CAAC,CAAA;QACxD,IAAI,EAAE,CAAC,UAAU,CAAC,KAAK,CAAC;YAAE,OAAO,KAAK,CAAA;IACxC,CAAC;IACD,OAAO,IAAI,CAAC,IAAI,CAAC,cAAc,EAAE,EAAE,SAAS,EAAE,OAAO,CAAC,CAAA;AACxD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,WAAoB;IACtD,IAAI,WAAW,EAAE,CAAC;QAChB,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAA;QACzD,IAAI,EAAE,CAAC,UAAU,CAAC,KAAK,CAAC;YAAE,OAAO,KAAK,CAAA;IACxC,CAAC;IACD,OAAO,IAAI,CAAC,IAAI,CAAC,cAAc,EAAE,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAA;AACzD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,wBAAwB,CAAC,WAAoB;IAC3D,IAAI,WAAW,EAAE,CAAC;QAChB,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,SAAS,EAAE,aAAa,CAAC,CAAA;QAC9D,IAAI,EAAE,CAAC,UAAU,CAAC,KAAK,CAAC;YAAE,OAAO,KAAK,CAAA;IACxC,CAAC;IACD,OAAO,IAAI,CAAC,IAAI,CAAC,cAAc,EAAE,EAAE,SAAS,EAAE,aAAa,CAAC,CAAA;AAC9D,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,WAAoB;IACtD,IAAI,WAAW,EAAE,CAAC;QAChB,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAA;QACzD,IAAI,EAAE,CAAC,UAAU,CAAC,KAAK,CAAC;YAAE,OAAO,KAAK,CAAA;IACxC,CAAC;IACD,OAAO,IAAI,CAAC,IAAI,CAAC,cAAc,EAAE,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAA;AACzD,CAAC"}

package/dist/validation/knowledge-frontmatter-validator.d.ts

@@ -0,0 +1,15 @@
+export interface KBValidationIssue {
+    message: string;
+    field?: string;
+}
+export interface KBValidationResult {
+    errors: KBValidationIssue[];
+    warnings: KBValidationIssue[];
+}
+export interface KBValidationOptions {
+    /** Project root used to locate `docs/knowledge-freshness/authoritative-sources.yaml`. */
+    projectRoot?: string;
+}
+export declare function validateKnowledgeFile(filePath: string, opts?: KBValidationOptions): KBValidationResult;
+export declare function validateKnowledgeDir(dir: string, opts?: KBValidationOptions): Map<string, KBValidationResult>;
+//# sourceMappingURL=knowledge-frontmatter-validator.d.ts.map

package/dist/validation/knowledge-frontmatter-validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-frontmatter-validator.d.ts","sourceRoot":"","sources":["../../src/validation/knowledge-frontmatter-validator.ts"],"names":[],"mappings":"AAqDA,MAAM,WAAW,iBAAiB;IAAG,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE;AACtE,MAAM,WAAW,kBAAkB;IAAG,MAAM,EAAE,iBAAiB,EAAE,CAAC;IAAC,QAAQ,EAAE,iBAAiB,EAAE,CAAA;CAAE;AAElG,MAAM,WAAW,mBAAmB;IAClC,yFAAyF;IACzF,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,GAAE,mBAAwB,GAAG,kBAAkB,CA8D1G;AAED,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE,mBAAwB,GAAG,GAAG,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAejH"}

package/dist/validation/knowledge-frontmatter-validator.js

@@ -0,0 +1,131 @@
+import fs from 'node:fs';
+import yaml from 'js-yaml';
+import { z } from 'zod';
+import { validateSourceUrl, loadAuthoritativeAllowlist, isAllowlistedSource, } from '../knowledge-freshness/source-url-validator.js';
+// Strict calendar-date refinement. A regex like /^\d{4}-\d{2}-\d{2}$/ accepts
+// "2026-99-99", which then becomes NaN at `new Date(...)` and silently breaks
+// cadence math in selectAuditCandidates (round-3 F-002). Require the parsed
+// Date to round-trip back to the same string.
+const isoDateSchema = z.string()
+    .regex(/^\d{4}-\d{2}-\d{2}$/, 'must be YYYY-MM-DD')
+    .refine((s) => {
+    const d = new Date(s + 'T00:00:00Z');
+    if (Number.isNaN(d.getTime()))
+        return false;
+    return d.toISOString().slice(0, 10) === s;
+}, 'must be a real calendar date');
+// Reject sources that the SSRF guard would refuse at fetch time. The schema
+// gate catches them earlier (CI) so a malformed/unsafe entry doesn't slip
+// into `main` and then surprise the daily cron (round-5 F-003).
+const safeSourceUrl = z.string().url().refine((u) => validateSourceUrl(u).ok, {
+    message: 'source URL would be refused by the SSRF guard (file:, ftp:, localhost, private/link-local IP, etc.)',
+});
+const sourceSchema = z.object({
+    url: safeSourceUrl,
+    // Anchors are appended to source.url literally by the audit meta-prompt, so
+    // they must include the leading "#" to produce a valid URL fragment.
+    anchor: z.string().regex(/^#/, 'anchor must start with "#"').optional(),
+    retrieved: isoDateSchema.optional(),
+    hash: z.string().optional(),
+});
+// Note: description has no max in the schema because some existing entries
+// already exceed 200 chars (e.g. content/knowledge/core/automated-review-tooling.md
+// is ~228). Overlong descriptions surface as a *warning* below, not an error,
+// so the Phase 1 CI gate doesn't break on day one.
+const kbSchema = z.object({
+    name: z.string().regex(/^[a-z][a-z0-9-]*$/),
+    description: z.string(),
+    topics: z.array(z.string()).default([]),
+    volatility: z.enum(['stable', 'evolving', 'fast-moving']).default('evolving'),
+    'last-reviewed': isoDateSchema.nullable().default(null),
+    'version-pin': z.string().nullable().default(null),
+    sources: z.array(sourceSchema).default([]),
+});
+const DESCRIPTION_SOFT_MAX = 200;
+export function validateKnowledgeFile(filePath, opts = {}) {
+    const errors = [];
+    const warnings = [];
+    const content = fs.readFileSync(filePath, 'utf8');
+    const lines = content.split('\n');
+    if (lines[0]?.trim() !== '---') {
+        errors.push({ message: 'missing frontmatter' });
+        return { errors, warnings };
+    }
+    let closeIdx = -1;
+    for (let i = 1; i < lines.length; i++) {
+        if (lines[i].trim() === '---') {
+            closeIdx = i;
+            break;
+        }
+    }
+    if (closeIdx === -1) {
+        errors.push({ message: 'unclosed frontmatter' });
+        return { errors, warnings };
+    }
+    let parsed;
+    try {
+        parsed = yaml.load(lines.slice(1, closeIdx).join('\n'), { schema: yaml.JSON_SCHEMA });
+    }
+    catch (e) {
+        errors.push({ message: `yaml parse error: ${e.message}` });
+        return { errors, warnings };
+    }
+    const result = kbSchema.safeParse(parsed ?? {});
+    if (!result.success) {
+        for (const issue of result.error.issues) {
+            errors.push({ message: `${issue.path.join('.')}: ${issue.message}`, field: String(issue.path[0] ?? '') });
+        }
+        return { errors, warnings };
+    }
+    const fm = result.data;
+    if (fm.description.length > DESCRIPTION_SOFT_MAX) {
+        warnings.push({
+            message: `description is ${fm.description.length} chars (>${DESCRIPTION_SOFT_MAX}); ` +
+                'consider trimming for downstream prompt token budgets',
+        });
+    }
+    if (fm.volatility === 'fast-moving' && fm.sources.length === 0) {
+        warnings.push({ message: 'fast-moving entry has empty sources — audit cannot run' });
+    }
+    if (!content.includes('## Deep Guidance')) {
+        warnings.push({ message: 'missing "## Deep Guidance" heading — assembly engine will fall back to full body' });
+    }
+    // Advisory: surface sources whose host is not in the authoritative-sources
+    // allowlist. Locked decision #4 — warn only, don't block (round-5 F-003).
+    if (opts.projectRoot && fm.sources.length > 0) {
+        const allowlist = loadAuthoritativeAllowlist(opts.projectRoot);
+        if (allowlist.hosts.length > 0 || allowlist.github_repos.length > 0) {
+            for (const src of fm.sources) {
+                try {
+                    const url = new URL(src.url);
+                    if (!isAllowlistedSource(url, allowlist)) {
+                        warnings.push({
+                            message: `source "${src.url}" host not in authoritative-sources.yaml allowlist (advisory)`,
+                            field: 'sources',
+                        });
+                    }
+                }
+                catch { /* unparseable URL already caught by schema */ }
+            }
+        }
+    }
+    return { errors, warnings };
+}
+export function validateKnowledgeDir(dir, opts = {}) {
+    const results = new Map();
+    function walk(d) {
+        for (const entry of fs.readdirSync(d, { withFileTypes: true })) {
+            const p = `${d}/${entry.name}`;
+            if (entry.isDirectory())
+                walk(p);
+            // Skip directory READMEs — the assembly engine excludes them
+            // (knowledge-loader.ts:138-139, :186-187), so we don't validate them either.
+            else if (entry.isFile() && p.endsWith('.md') && entry.name !== 'README.md') {
+                results.set(p, validateKnowledgeFile(p, opts));
+            }
+        }
+    }
+    walk(dir);
+    return results;
+}
+//# sourceMappingURL=knowledge-frontmatter-validator.js.map

package/dist/validation/knowledge-frontmatter-validator.js.map

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

package/dist/validation/knowledge-frontmatter-validator.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=knowledge-frontmatter-validator.test.d.ts.map

package/dist/validation/knowledge-frontmatter-validator.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-frontmatter-validator.test.d.ts","sourceRoot":"","sources":["../../src/validation/knowledge-frontmatter-validator.test.ts"],"names":[],"mappings":""}

package/dist/validation/knowledge-frontmatter-validator.test.js

@@ -0,0 +1,66 @@
+import { describe, it, expect, afterEach } from 'vitest';
+import { validateKnowledgeFile } from './knowledge-frontmatter-validator.js';
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+const tmpDirs = [];
+function tmpFile(content) {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'kb-test-'));
+    tmpDirs.push(dir);
+    const file = path.join(dir, 'entry.md');
+    fs.writeFileSync(file, content);
+    return file;
+}
+afterEach(() => {
+    while (tmpDirs.length) {
+        fs.rmSync(tmpDirs.pop(), { recursive: true, force: true });
+    }
+});
+describe('validateKnowledgeFile', () => {
+    it('passes a minimal valid entry', () => {
+        const file = tmpFile('---\nname: x\ndescription: y\n---\nbody');
+        const result = validateKnowledgeFile(file);
+        expect(result.errors).toEqual([]);
+    });
+    it('errors when last-reviewed is not an ISO date', () => {
+        const file = tmpFile('---\nname: x\ndescription: y\nlast-reviewed: \'last tuesday\'\n---\nbody');
+        const result = validateKnowledgeFile(file);
+        expect(result.errors[0].message).toMatch(/last-reviewed/);
+    });
+    it('errors when last-reviewed is shaped right but is not a real calendar date', () => {
+        // Round-3 F-002: "2026-99-99" passes the YYYY-MM-DD regex but is invalid.
+        // Cadence math (new Date(...)) becomes NaN and silently breaks selection.
+        const file = tmpFile('---\nname: x\ndescription: y\nlast-reviewed: \'2026-99-99\'\n---\nbody');
+        const result = validateKnowledgeFile(file);
+        expect(result.errors.some(e => /calendar date/.test(e.message))).toBe(true);
+    });
+    it('errors when source.retrieved is shaped right but is not a real calendar date', () => {
+        const file = tmpFile('---\nname: x\ndescription: y\nsources:\n  - url: https://x\n    retrieved: \'2026-13-01\'\n---\nbody');
+        const result = validateKnowledgeFile(file);
+        expect(result.errors.some(e => /calendar date/.test(e.message))).toBe(true);
+    });
+    it('errors when a source entry is missing url', () => {
+        const file = tmpFile('---\nname: x\ndescription: y\nsources:\n  - anchor: \'#a\'\n---\nbody');
+        const result = validateKnowledgeFile(file);
+        expect(result.errors[0].message).toMatch(/url/);
+    });
+    it('errors when source.url would be refused by the SSRF guard (file://)', () => {
+        // Round-5 F-003: z.string().url() accepts file:, ftp:, javascript:, and
+        // localhost URLs. The refined schema rejects them at CI rather than
+        // letting them slip through to the audit runtime.
+        const file = tmpFile('---\nname: x\ndescription: y\nsources:\n  - url: file:///etc/passwd\n---\nbody');
+        const result = validateKnowledgeFile(file);
+        expect(result.errors.some(e => /SSRF guard/.test(e.message))).toBe(true);
+    });
+    it('errors when source.url points at localhost', () => {
+        const file = tmpFile('---\nname: x\ndescription: y\nsources:\n  - url: http://localhost:8080/\n---\nbody');
+        const result = validateKnowledgeFile(file);
+        expect(result.errors.some(e => /SSRF guard/.test(e.message))).toBe(true);
+    });
+    it('warns when sources is empty and volatility is fast-moving', () => {
+        const file = tmpFile('---\nname: x\ndescription: y\nvolatility: fast-moving\nsources: []\n---\nbody');
+        const result = validateKnowledgeFile(file);
+        expect(result.warnings.some(w => /sources/.test(w.message))).toBe(true);
+    });
+});
+//# sourceMappingURL=knowledge-frontmatter-validator.test.js.map

package/dist/validation/knowledge-frontmatter-validator.test.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zigrivers/scaffold",
-  "version": "3.27.0",
+  "version": "3.29.0",
   "description": "AI-powered software project scaffolding pipeline",
   "type": "module",
   "workspaces": [
@@ -32,13 +32,13 @@
     "LICENSE"
   ],
   "engines": {
-    "node": ">=18"
+    "node": ">=18.17.0"
   },
   "bin": {
     "scaffold": "dist/index.js"
   },
   "scripts": {
-    "build": "tsc && cp src/core/knowledge/knowledge-update-template.md dist/core/knowledge/knowledge-update-template.md",
+    "build": "tsc && cp src/core/knowledge/knowledge-update-template.md dist/core/knowledge/knowledge-update-template.md && mkdir -p dist/guides && cp lib/dashboard-theme.css dist/guides/dashboard-theme.css",
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
     "test:e2e": "vitest run --config vitest.e2e.config.ts",
@@ -52,18 +52,26 @@
     "@babel/parser": "^7.29.0",
     "@babel/traverse": "^7.29.0",
     "@babel/types": "^7.29.0",
-    "postcss": "^8.5.8",
     "@inquirer/prompts": "^7.4.0",
     "js-yaml": "^4.1.0",
     "mdast-util-from-markdown": "^2.0.3",
+    "mdast-util-to-string": "^4.0.0",
     "minimatch": "^10.2.5",
+    "postcss": "^8.5.8",
     "proper-lockfile": "^4.1.2",
+    "rehype-raw": "^7.0.0",
+    "rehype-sanitize": "^6.0.0",
+    "rehype-stringify": "^10.0.1",
+    "remark-directive": "^3.0.1",
     "remark-gfm": "^4.0.1",
     "remark-parse": "^11.0.0",
+    "remark-rehype": "^11.1.2",
     "remark-stringify": "^11.0.0",
     "smol-toml": "^1.6.1",
     "ulid": "^3.0.2",
+    "undici": "^6.26.0",
     "unified": "^11.0.5",
+    "unist-util-visit": "^5.1.0",
     "uuid": "^14.0.0",
     "yaml": "^2.8.3",
     "yargs": "^17.7.2",
@@ -71,6 +79,7 @@
   },
   "devDependencies": {
     "@eslint/js": "^9.21.0",
+    "@mermaid-js/mermaid-cli": "^11.15.0",
     "@types/babel__traverse": "^7.28.0",
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^22.13.0",