agentic-sdd-framework 1.4.0

package/scripts/install-git-hooks.js

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+
+/**
+ * scripts/install-git-hooks.js
+ *
+ * Installs a pre-push hook that runs the quality gate on the commits being pushed
+ * (`quality-gate.js --push`), not on the working tree.
+ *
+ * The hook goes into the repository's own hooks directory (`git rev-parse --git-path
+ * hooks`, shared by linked worktrees). When core.hooksPath is set, the hooks directory is
+ * owned by a hook manager or shared across repositories, so nothing is installed and the
+ * command to add to that manager is printed instead. An existing unmanaged pre-push hook
+ * is preserved as pre-push.local and runs first.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { git, repoRoot } = require('./lib/git');
+
+const MARKER = 'sdd:managed';
+// Signature of the hook written by framework versions before the marker existed.
+const LEGACY_SIGNATURE = '# Pre-push hook: Agentic SDD Quality Gate';
+
+const toPosix = p => p.split(path.sep).join('/');
+
+function renderHook(gateScript, nodePath) {
+    return `#!/bin/sh
+# ${MARKER} pre-push hook installed by the Agentic SDD Framework.
+# A pre-existing hook, if any, was moved to pre-push.local and runs first.
+HOOK_DIR=$(dirname "$0")
+INPUT=$(cat)
+if [ -x "$HOOK_DIR/pre-push.local" ]; then
+    printf '%s\\n' "$INPUT" | "$HOOK_DIR/pre-push.local" "$@" || exit 1
+fi
+
+# GUI git clients may not have node on PATH; fall back to the node that installed the hook.
+NODE_BIN=node
+command -v node >/dev/null 2>&1 || NODE_BIN="${nodePath}"
+
+if ! printf '%s\\n' "$INPUT" | "$NODE_BIN" "${gateScript}" --push "$1"; then
+    echo "Quality gate failed. Push aborted." >&2
+    exit 1
+fi
+`;
+}
+
+function configuredHooksPath(root) {
+    try {
+        return git(['config', '--get', 'core.hooksPath'], root).trim();
+    } catch {
+        return '';
+    }
+}
+
+function install({ root = repoRoot(), gateScript = path.join(__dirname, 'quality-gate.js'), nodePath = process.execPath } = {}) {
+    // Git runs the hook from the real (symlink-resolved) worktree path, so the relative
+    // path must be computed between real paths too.
+    const relativeGate = toPosix(path.relative(fs.realpathSync(root), fs.realpathSync(gateScript)));
+    const hooksPath = configuredHooksPath(root);
+    if (hooksPath) {
+        throw new Error(
+            `core.hooksPath is set (${hooksPath}); that directory belongs to a hook manager or is shared by other repositories, so no hook was installed. ` +
+            `Add this to its pre-push hook, passing the hook's stdin: node ${relativeGate} --push "$1"`
+        );
+    }
+    let hooksDir;
+    try {
+        hooksDir = path.resolve(root, git(['rev-parse', '--git-path', 'hooks'], root).trim());
+    } catch {
+        throw new Error(`${root} is not a git repository.`);
+    }
+    fs.mkdirSync(hooksDir, { recursive: true });
+
+    const hookPath = path.join(hooksDir, 'pre-push');
+    const localPath = path.join(hooksDir, 'pre-push.local');
+    let preserved = false;
+    const current = fs.existsSync(hookPath) ? fs.readFileSync(hookPath, 'utf8') : null;
+    if (current !== null && !current.includes(MARKER) && !current.includes(LEGACY_SIGNATURE)) {
+        if (fs.existsSync(localPath)) {
+            throw new Error(`Both ${hookPath} and pre-push.local exist. Merge them manually, then rerun.`);
+        }
+        fs.renameSync(hookPath, localPath);
+        preserved = true;
+    }
+
+    // Git runs hooks from the worktree root, so a root-relative path works in every worktree.
+    fs.writeFileSync(hookPath, renderHook(relativeGate, toPosix(nodePath)), { mode: 0o755 });
+    fs.chmodSync(hookPath, 0o755);
+    return { hookPath, preserved };
+}
+
+if (require.main === module) {
+    try {
+        const { hookPath, preserved } = install();
+        if (preserved) console.log('ℹ️  Existing pre-push hook preserved as pre-push.local (runs first).');
+        console.log(`✅ Pre-push quality gate hook installed at ${hookPath}\n`);
+    } catch (error) {
+        console.error(`❌ ${error.message}`);
+        process.exit(1);
+    }
+}
+
+module.exports = { MARKER, install, renderHook };

package/scripts/lib/cli.js

@@ -0,0 +1,60 @@
+/**
+ * scripts/lib/cli.js
+ *
+ * Shared entry point for the check scripts: parses the source flags, prints the banner,
+ * and turns any thrown error into a failing exit code instead of a stack trace.
+ */
+
+const { repoRoot } = require('./git');
+
+const SOURCE_USAGE = '[--staged | --ref=<commit>]';
+
+// Strict flag parsing: --staged -> index, --ref=<commit> or --ref <commit> -> that commit,
+// no flag -> the working tree. With allowPush, --push [remote] selects pre-push mode.
+// Unknown flags are errors, so a typo never silently checks the working tree instead.
+function parseCheckArgs(argv, { allowPush = false } = {}) {
+    const usage = `Usage: ${SOURCE_USAGE}${allowPush ? ' | --push [remote]' : ''}`;
+    const options = { source: { kind: 'worktree' }, push: false, remoteName: '' };
+    const chosen = [];
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === '--staged') {
+            options.source = { kind: 'index' };
+            chosen.push(arg);
+        } else if (arg === '--ref' || arg.startsWith('--ref=')) {
+            const ref = arg === '--ref' ? argv[++i] : arg.slice('--ref='.length);
+            if (!ref || ref.startsWith('-')) throw new Error(`--ref needs a commit. ${usage}`);
+            options.source = { kind: 'ref', ref };
+            chosen.push('--ref');
+        } else if (allowPush && arg === '--push') {
+            options.push = true;
+            chosen.push(arg);
+            if (argv[i + 1] !== undefined && !argv[i + 1].startsWith('-')) options.remoteName = argv[++i];
+            // git passes the remote URL as a second argument to pre-push hooks.
+            if (argv[i + 1] !== undefined && !argv[i + 1].startsWith('-')) i++;
+        } else if (arg === '--help' || arg === '-h') {
+            throw new Error(usage);
+        } else {
+            throw new Error(`Unknown argument "${arg}". ${usage}`);
+        }
+    }
+    if (chosen.length > 1) throw new Error(`${chosen.join(' and ')} are separate modes. ${usage}`);
+    return options;
+}
+
+function runCheckCli(title, run, argv = process.argv.slice(2)) {
+    console.log('\n======================================================');
+    console.log(`  ${title}`);
+    console.log('======================================================\n');
+    let result;
+    try {
+        const { source } = parseCheckArgs(argv);
+        result = run({ root: repoRoot(), source });
+    } catch (error) {
+        result = { ok: false, report: `❌ ${error.message}` };
+    }
+    (result.ok ? console.log : console.error)(result.report + '\n');
+    process.exit(result.ok ? 0 : 1);
+}
+
+module.exports = { parseCheckArgs, runCheckCli };

package/scripts/lib/config.js

@@ -0,0 +1,111 @@
+/**
+ * scripts/lib/config.js
+ *
+ * Loads and validates sdd.config.json against sdd.config.schema.json (same directory).
+ * A missing file yields an empty object so every check uses its documented defaults.
+ * An invalid file is an error: a typo must not silently switch a check off.
+ * Keys starting with "x-" are free-form extensions and are not validated.
+ */
+
+const path = require('path');
+const { readFile, WORKTREE } = require('./git');
+
+const SCHEMA = require('./sdd.config.schema.json');
+
+const canonical = value => value.replace(/\\/g, '/').split('/').filter(s => s && s !== '.').join('/');
+
+function typeOf(value) {
+    if (Array.isArray(value)) return 'array';
+    if (value === null) return 'null';
+    if (Number.isInteger(value)) return 'integer';
+    return typeof value;
+}
+
+// Validates the subset of JSON Schema used by sdd.config.schema.json.
+function validate(value, schema, at, errors) {
+    if (schema.enum && !schema.enum.includes(value)) {
+        errors.push(`${at}: ${JSON.stringify(value)} is not one of ${schema.enum.map(v => JSON.stringify(v)).join(', ')}`);
+        return;
+    }
+    if (schema.type) {
+        const actual = typeOf(value);
+        const ok = actual === schema.type || (schema.type === 'number' && actual === 'integer');
+        if (!ok) {
+            errors.push(`${at}: expected ${schema.type}, got ${actual}`);
+            return;
+        }
+    }
+    if (typeof schema.minLength === 'number' && typeof value === 'string' && value.length < schema.minLength) {
+        errors.push(`${at}: must not be empty`);
+    }
+    if (typeof schema.minimum === 'number' && typeof value === 'number' && value < schema.minimum) {
+        errors.push(`${at}: must be >= ${schema.minimum}`);
+    }
+    if (schema['x-relative-path'] && typeof value === 'string' && value !== '') {
+        // Paths are compared as written with Git's paths, so only the canonical form works:
+        // forward slashes, no ".", "..", or empty segments (a trailing "/" marks a directory).
+        const segments = value.replace(/\/$/, '').split('/');
+        if (path.isAbsolute(value) || /^[A-Za-z]:/.test(value) || segments.includes('..')) {
+            errors.push(`${at}: must be a path relative to the repository root, without ".."`);
+        } else if (value.includes('\\') || segments.some(s => s === '' || s === '.')) {
+            errors.push(`${at}: write the path in canonical form (forward slashes, no "./" or "//"), e.g. "${canonical(value)}"`);
+        } else if (schema['x-file-path'] && value.endsWith('/')) {
+            errors.push(`${at}: must not end with "/"`);
+        }
+    }
+    if (schema.items && Array.isArray(value)) {
+        value.forEach((item, i) => validate(item, schema.items, `${at}[${i}]`, errors));
+    }
+    if (schema.properties && typeOf(value) === 'object') {
+        for (const [key, child] of Object.entries(value)) {
+            const where = `${at}.${key}`;
+            // Own properties only: "toString" or "__proto__" must not resolve to Object.prototype.
+            if (Object.prototype.hasOwnProperty.call(schema.properties, key)) {
+                validate(child, schema.properties[key], where, errors);
+            } else if (schema.patternProperties && Object.keys(schema.patternProperties).some(p => new RegExp(p).test(key))) {
+                continue;
+            } else if (schema.additionalProperties === false) {
+                const known = Object.keys(schema.properties).join(', ');
+                errors.push(`${where}: unknown key (valid keys: ${known}; use an "x-" prefix for custom keys)`);
+            }
+        }
+    }
+}
+
+function validateConfig(config) {
+    const errors = [];
+    validate(config, SCHEMA, 'sdd.config.json', errors);
+    return errors;
+}
+
+function parseConfig(text) {
+    let config;
+    try {
+        config = JSON.parse(text.replace(/^\uFEFF/, ''));
+    } catch (error) {
+        throw new Error(`sdd.config.json is not valid JSON: ${error.message}`);
+    }
+    const errors = validateConfig(config);
+    if (errors.length > 0) {
+        throw new Error(`sdd.config.json is invalid:\n${errors.map(e => `  - ${e}`).join('\n')}`);
+    }
+    return config;
+}
+
+// Reads the configuration from the same source the checks read (working tree, index, commit).
+function loadConfig(root, source = WORKTREE) {
+    const buffer = readFile(root, 'sdd.config.json', source);
+    return buffer ? parseConfig(buffer.toString('utf8')) : {};
+}
+
+// getIn(config, 'capabilities.noAiSlop.enabled', true)
+function getIn(object, keyPath, fallback) {
+    let current = object;
+    for (const key of keyPath.split('.')) {
+        if (current === null || typeof current !== 'object' || !(key in current)) return fallback;
+        current = current[key];
+    }
+    return current === undefined ? fallback : current;
+}
+
+module.exports = { SCHEMA, validateConfig, parseConfig, loadConfig, getIn };

package/scripts/lib/git.js

@@ -0,0 +1,211 @@
+/**
+ * scripts/lib/git.js
+ *
+ * Git access for the quality gate checks. Every check reads files from a *source*:
+ *
+ *   { kind: 'worktree' }          tracked files as they are on disk (default)
+ *   { kind: 'index' }             the staged content (what the next commit will contain)
+ *   { kind: 'ref', ref: '<sha>' } the content of a commit (used by the pre-push hook)
+ *
+ * Failures are errors, never empty results: a check that cannot read the repository
+ * must fail instead of reporting "0 files, all clean".
+ */
+
+const { execFileSync, spawnSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+const MAX_BUFFER = 256 * 1024 * 1024;
+const WORKTREE = Object.freeze({ kind: 'worktree' });
+const GITLINK_MODE = '160000';
+
+function git(args, cwd, options = {}) {
+    return execFileSync('git', args, {
+        cwd,
+        encoding: 'utf8',
+        maxBuffer: MAX_BUFFER,
+        stdio: ['ignore', 'pipe', 'pipe'],
+        ...options
+    });
+}
+
+function describeGitError(error) {
+    const stderr = error.stderr ? error.stderr.toString().trim() : '';
+    return stderr || error.message;
+}
+
+function repoRoot(cwd = process.cwd()) {
+    try {
+        return git(['rev-parse', '--show-toplevel'], cwd).trim();
+    } catch (error) {
+        throw new Error(`Not inside a usable git repository (${cwd}): ${describeGitError(error)}`);
+    }
+}
+
+function describeSource(source = WORKTREE) {
+    if (source.kind === 'index') return 'staged changes';
+    if (source.kind === 'ref') return `commit ${source.ref.slice(0, 12)}`;
+    return 'working tree';
+}
+
+// Parses `ls-files -s -z` ("<mode> <oid> <stage>\t<path>") or `ls-tree -r -z`
+// ("<mode> <type> <oid>\t<path>") output. Paths may contain any byte except NUL.
+function parseEntries(output, format) {
+    const entries = [];
+    for (const record of output.split('\0')) {
+        if (!record) continue;
+        const tab = record.indexOf('\t');
+        const fields = record.slice(0, tab).split(' ');
+        const entry = format === 'ls-tree'
+            ? { mode: fields[0], oid: fields[2], stage: '0', path: record.slice(tab + 1) }
+            : { mode: fields[0], oid: fields[1], stage: fields[2], path: record.slice(tab + 1) };
+        if (entry.mode !== GITLINK_MODE) entries.push(entry);
+    }
+    return entries;
+}
+
+// Path -> blob id for every tracked file in an index or commit source. During a merge
+// conflict the index holds several stages; stage 0 wins, otherwise "ours" (stage 2).
+function entriesOf(root, source) {
+    let entries;
+    try {
+        entries = source.kind === 'ref'
+            ? parseEntries(git(['ls-tree', '-r', '-z', source.ref], root), 'ls-tree')
+            : parseEntries(git(['ls-files', '-s', '-z'], root), 'ls-files');
+    } catch (error) {
+        throw new Error(`Cannot list files from the ${describeSource(source)}: ${describeGitError(error)}`);
+    }
+    const byPath = new Map();
+    for (const entry of entries) {
+        const current = byPath.get(entry.path);
+        if (!current || entry.stage === '0' || (current.stage !== '0' && entry.stage === '2')) byPath.set(entry.path, entry);
+    }
+    return byPath;
+}
+
+// Files a check should look at. Submodule entries (gitlinks) are not files and are skipped.
+// For the index, only files the next commit changes; use listTrackedFiles for all of them.
+function listFiles(root, source = WORKTREE, { changedOnly = true } = {}) {
+    const paths = [...entriesOf(root, source).keys()];
+    if (source.kind !== 'index' || !changedOnly) return paths;
+    let names;
+    try {
+        // T: a symlink or submodule replaced by a regular file is new content too.
+        names = git(['diff', '--cached', '--name-only', '-z', '--diff-filter=ACMRT'], root);
+    } catch (error) {
+        throw new Error(`Cannot list staged changes: ${describeGitError(error)}`);
+    }
+    const staged = new Set(names.split('\0').filter(Boolean));
+    return paths.filter(p => staged.has(p));
+}
+
+// Every tracked file in the source (for the index: the full staged tree).
+function listTrackedFiles(root, source = WORKTREE) {
+    return listFiles(root, source, { changedOnly: false });
+}
+
+function readWorktreeFile(root, file) {
+    const full = path.join(root, file);
+    let stat;
+    try {
+        stat = fs.lstatSync(full);
+    } catch (error) {
+        if (error.code === 'ENOENT') return null; // tracked but deleted in the working tree
+        throw new Error(`Cannot read ${file}: ${error.message}`);
+    }
+    // Git stores a symlink as its target path; read that, never the file it points to.
+    if (stat.isSymbolicLink()) return Buffer.from(fs.readlinkSync(full));
+    if (!stat.isFile()) return null;
+    try {
+        return fs.readFileSync(full);
+    } catch (error) {
+        throw new Error(`Cannot read ${file}: ${error.message}`);
+    }
+}
+
+function catFile(root, mode, oids, maxBuffer) {
+    const proc = spawnSync('git', ['cat-file', mode], { cwd: root, input: oids.join('\n') + '\n', maxBuffer });
+    if (proc.error || proc.status !== 0) {
+        throw new Error(`git cat-file failed: ${proc.error ? proc.error.message : proc.stderr.toString().trim()}`);
+    }
+    return proc.stdout;
+}
+
+// Object sizes from `cat-file --batch-check`, so blobs can be read in bounded batches.
+function blobSizes(root, oids, maxBuffer) {
+    const lines = catFile(root, '--batch-check', oids, maxBuffer).toString().split('\n');
+    return oids.map((oid, i) => {
+        const [gotOid, type, size] = (lines[i] || '').split(' ');
+        if (gotOid !== oid || type !== 'blob') {
+            throw new Error(`git cat-file returned "${lines[i]}" for object ${oid}; the repository may be corrupt.`);
+        }
+        return Number(size);
+    });
+}
+
+// Reads blobs by object id with `git cat-file --batch`, in batches of about BATCH_BYTES so
+// the output always fits the buffer (a larger blob gets a batch of its own). Object ids
+// never contain newlines, so arbitrary file names cannot desynchronize the batch; every
+// response is checked against the id that was requested.
+const BATCH_BYTES = 32 * 1024 * 1024;
+
+function readBlobs(root, oids, { batchBytes = BATCH_BYTES, maxBuffer = MAX_BUFFER } = {}) {
+    const result = new Map();
+    const unique = [...new Set(oids)];
+    if (unique.length === 0) return result;
+    const sizes = blobSizes(root, unique, maxBuffer);
+    let batch = [];
+    let bytes = 0;
+    const flush = () => {
+        if (batch.length === 0) return;
+        readBatch(root, batch, Math.max(maxBuffer, bytes + 1024 * 1024), result);
+        batch = [];
+        bytes = 0;
+    };
+    unique.forEach((oid, i) => {
+        if (batch.length > 0 && bytes + sizes[i] > batchBytes) flush();
+        batch.push(oid);
+        bytes += sizes[i] + 128; // header and trailing newline
+    });
+    flush();
+    return result;
+}
+
+function readBatch(root, oids, maxBuffer, result) {
+    const out = catFile(root, '--batch', oids, maxBuffer);
+    let offset = 0;
+    for (const oid of oids) {
+        const newline = out.indexOf(10, offset);
+        const header = newline === -1 ? '' : out.subarray(offset, newline).toString();
+        const [gotOid, type, sizeText] = header.split(' ');
+        if (gotOid !== oid || type !== 'blob') {
+            throw new Error(`git cat-file returned "${header}" for object ${oid}; the repository may be corrupt.`);
+        }
+        const size = Number(sizeText);
+        offset = newline + 1;
+        result.set(oid, out.subarray(offset, offset + size));
+        offset += size + 1;
+    }
+}
+
+// Map<file, Buffer|null>; null means the file does not exist in that source.
+function readFiles(root, files, source = WORKTREE) {
+    if (source.kind === 'worktree') {
+        return new Map(files.map(f => [f, readWorktreeFile(root, f)]));
+    }
+    const entries = entriesOf(root, source);
+    const blobs = readBlobs(root, files.filter(f => entries.has(f)).map(f => entries.get(f).oid));
+    return new Map(files.map(f => [f, entries.has(f) ? blobs.get(entries.get(f).oid) : null]));
+}
+
+function readFile(root, file, source = WORKTREE) {
+    return readFiles(root, [file], source).get(file);
+}
+
+function isBinary(buffer) {
+    return buffer.subarray(0, 8000).includes(0);
+}
+
+module.exports = {
+    WORKTREE, git, describeGitError, repoRoot, describeSource, listFiles, listTrackedFiles, readFiles, readFile, readBlobs, isBinary
+};

package/scripts/lib/markdown.js

@@ -0,0 +1,46 @@
+/**
+ * scripts/lib/markdown.js
+ *
+ * Minimal Markdown helpers shared by the prose linter and the spec parser.
+ */
+
+// Normalizes CRLF/CR line endings so line-anchored regexes behave the same on Windows.
+function normalizeEol(text) {
+    return text.replace(/\r\n?/g, '\n');
+}
+
+function detectEol(text) {
+    return text.includes('\r\n') ? '\r\n' : '\n';
+}
+
+// Tracks fenced code blocks. A fence closes only with the same character repeated at
+// least as many times as the opening fence, and nothing else on the line (CommonMark).
+// Any number of spaces is accepted because fences nested in list items are indented.
+function createFenceTracker() {
+    let open = null;
+    return {
+        get inside() {
+            return open !== null;
+        },
+        // Returns true when the line is a fence delimiter (opening or closing).
+        update(line) {
+            // Only spaces may precede a fence (CommonMark); a tab or other whitespace makes
+            // it something else, which the spec parser reports separately.
+            const match = line.match(/^ *(`{3,}|~{3,})(.*)$/);
+            if (!match) return false;
+            const [, marker, rest] = match;
+            if (open === null) {
+                if (marker[0] === '`' && rest.includes('`')) return false;
+                open = marker;
+                return true;
+            }
+            if (marker[0] === open[0] && marker.length >= open.length && rest.trim() === '') {
+                open = null;
+                return true;
+            }
+            return false;
+        }
+    };
+}
+
+module.exports = { normalizeEol, detectEol, createFenceTracker };