@therocketcode/gsd-core 1.4.0

package/gsd-core/bin/lib/active-workstream-store.cjs

@@ -0,0 +1,291 @@
+"use strict";
+/**
+ * Active Workstream Pointer Store Module
+ *
+ * Owns active workstream source precedence, session identity, and pointer IO:
+ * CLI --ws > GSD_WORKSTREAM env > stored active workstream pointer.
+ *
+ * ADR-457 build-at-publish: the hand-written bin/lib/active-workstream-store.cjs
+ * collapsed to a TypeScript source of truth. Behaviour is preserved
+ * byte-for-behaviour from the prior hand-written .cjs; only types are added.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_crypto_1 = __importDefault(require("node:crypto"));
+const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
+const workstream_name_policy_cjs_1 = require("./workstream-name-policy.cjs");
+const WORKSTREAM_SESSION_ENV_KEYS = [
+    'GSD_SESSION_KEY',
+    'CODEX_THREAD_ID',
+    'CLAUDE_SESSION_ID',
+    'CLAUDE_CODE_SSE_PORT',
+    'OPENCODE_SESSION_ID',
+    'GEMINI_SESSION_ID',
+    'CURSOR_SESSION_ID',
+    'WINDSURF_SESSION_ID',
+    'TERM_SESSION_ID',
+    'WT_SESSION',
+    'TMUX_PANE',
+    'ZELLIJ_SESSION_NAME',
+];
+let cachedControllingTtyToken = null;
+let didProbeControllingTtyToken = false;
+function planningRoot(cwd) {
+    return node_path_1.default.join(cwd, '.planning');
+}
+function validateWorkstreamName(name) {
+    return (0, workstream_name_policy_cjs_1.isValidActiveWorkstreamName)(name);
+}
+function sanitizeWorkstreamSessionToken(value) {
+    if (value === null || value === undefined)
+        return null;
+    const raw = typeof value === 'string' ? value : `${value}`;
+    const token = raw.trim().replace(/[^a-zA-Z0-9._-]+/g, '_').replace(/^_+|_+$/g, '');
+    return token ? token.slice(0, 160) : null;
+}
+function probeControllingTtyToken() {
+    if (didProbeControllingTtyToken)
+        return cachedControllingTtyToken;
+    didProbeControllingTtyToken = true;
+    if (!(process.stdin && process.stdin.isTTY)) {
+        return cachedControllingTtyToken;
+    }
+    const ttyPath = (0, shell_command_projection_cjs_1.probeTty)();
+    if (ttyPath) {
+        const token = sanitizeWorkstreamSessionToken(ttyPath.replace(/^\/dev\//, ''));
+        if (token)
+            cachedControllingTtyToken = `tty-${token}`;
+    }
+    return cachedControllingTtyToken;
+}
+function getControllingTtyToken() {
+    for (const envKey of ['TTY', 'SSH_TTY']) {
+        const token = sanitizeWorkstreamSessionToken(process.env[envKey]);
+        if (token)
+            return `tty-${token.replace(/^dev_/, '')}`;
+    }
+    return probeControllingTtyToken();
+}
+function getWorkstreamSessionKey() {
+    for (const envKey of WORKSTREAM_SESSION_ENV_KEYS) {
+        const raw = process.env[envKey];
+        const token = sanitizeWorkstreamSessionToken(raw);
+        if (token)
+            return `${envKey.toLowerCase().replace(/[^a-z0-9]+/g, '-')}-${token}`;
+    }
+    return getControllingTtyToken();
+}
+function getSessionScopedWorkstreamFile(cwd, fixedSessionKey) {
+    const sessionKey = fixedSessionKey || getWorkstreamSessionKey();
+    if (!sessionKey)
+        return null;
+    let planningAbs;
+    try {
+        planningAbs = node_fs_1.default.realpathSync.native(planningRoot(cwd));
+    }
+    catch {
+        planningAbs = node_path_1.default.resolve(planningRoot(cwd));
+    }
+    const projectId = node_crypto_1.default
+        .createHash('sha1')
+        .update(planningAbs)
+        .digest('hex')
+        .slice(0, 16);
+    const dirPath = node_path_1.default.join(node_os_1.default.tmpdir(), 'gsd-workstream-sessions', projectId);
+    return {
+        sessionKey,
+        dirPath,
+        filePath: node_path_1.default.join(dirPath, sessionKey),
+    };
+}
+function createSharedPointerAdapter(cwd) {
+    const filePath = node_path_1.default.join(planningRoot(cwd), 'active-workstream');
+    return {
+        read() {
+            const raw = (0, shell_command_projection_cjs_1.platformReadSync)(filePath);
+            return raw ? raw.trim() || null : null;
+        },
+        write(name) {
+            (0, shell_command_projection_cjs_1.platformWriteSync)(filePath, name + '\n');
+        },
+        clear() {
+            try {
+                node_fs_1.default.unlinkSync(filePath);
+            }
+            catch { }
+        },
+    };
+}
+function createSessionScopedPointerAdapter(cwd, fixedSessionKey) {
+    const scoped = getSessionScopedWorkstreamFile(cwd, fixedSessionKey);
+    if (!scoped)
+        return null;
+    return {
+        read() {
+            const raw = (0, shell_command_projection_cjs_1.platformReadSync)(scoped.filePath);
+            return raw ? raw.trim() || null : null;
+        },
+        write(name) {
+            (0, shell_command_projection_cjs_1.platformEnsureDir)(scoped.dirPath);
+            (0, shell_command_projection_cjs_1.platformWriteSync)(scoped.filePath, name + '\n');
+        },
+        clear() {
+            try {
+                node_fs_1.default.unlinkSync(scoped.filePath);
+            }
+            catch { }
+            try {
+                const remaining = node_fs_1.default.readdirSync(scoped.dirPath);
+                if (remaining.length === 0) {
+                    node_fs_1.default.rmdirSync(scoped.dirPath);
+                }
+            }
+            catch { }
+        },
+    };
+}
+function createMemoryPointerAdapter(initialName = null) {
+    let value = initialName;
+    return {
+        read() {
+            return value;
+        },
+        write(name) {
+            value = name;
+        },
+        clear() {
+            value = null;
+        },
+    };
+}
+function pickActiveWorkstreamAdapter(cwd, opts = {}) {
+    if (opts.activeWorkstreamAdapter) {
+        return opts.activeWorkstreamAdapter;
+    }
+    const sessionKey = getWorkstreamSessionKey();
+    if (sessionKey) {
+        if (opts.activeWorkstreamAdapters && opts.activeWorkstreamAdapters.session) {
+            return opts.activeWorkstreamAdapters.session;
+        }
+        return createSessionScopedPointerAdapter(cwd, sessionKey);
+    }
+    if (opts.activeWorkstreamAdapters && opts.activeWorkstreamAdapters.shared) {
+        return opts.activeWorkstreamAdapters.shared;
+    }
+    return createSharedPointerAdapter(cwd);
+}
+function getActiveWorkstream(cwd, opts = {}) {
+    const adapter = pickActiveWorkstreamAdapter(cwd, opts);
+    if (!adapter)
+        return null;
+    const name = adapter.read();
+    if (!name || !validateWorkstreamName(name)) {
+        adapter.clear();
+        return null;
+    }
+    const wsDir = node_path_1.default.join(planningRoot(cwd), 'workstreams', name);
+    if (!node_fs_1.default.existsSync(wsDir)) {
+        adapter.clear();
+        return null;
+    }
+    return name;
+}
+function setActiveWorkstream(cwd, name, opts = {}) {
+    const adapter = pickActiveWorkstreamAdapter(cwd, opts);
+    if (!adapter)
+        return;
+    if (!name) {
+        adapter.clear();
+        return;
+    }
+    if (!validateWorkstreamName(name)) {
+        throw new Error('Invalid workstream name: must be alphanumeric, hyphens, underscores, or dots');
+    }
+    const wsDir = node_path_1.default.join(planningRoot(cwd), 'workstreams', name);
+    (0, shell_command_projection_cjs_1.platformEnsureDir)(wsDir);
+    adapter.write(name);
+}
+function clearActiveWorkstream(cwd, opts = {}) {
+    const adapter = pickActiveWorkstreamAdapter(cwd, opts);
+    if (!adapter)
+        return;
+    adapter.clear();
+}
+function parseCliWorkstream(args) {
+    const wsEqArg = args.find((arg) => arg.startsWith('--ws='));
+    const wsIdx = args.indexOf('--ws');
+    if (wsEqArg) {
+        const value = wsEqArg.slice('--ws='.length).trim();
+        if (!value)
+            throw new Error('Missing value for --ws');
+        return {
+            value,
+            source: 'cli',
+            args: args.filter((arg) => arg !== wsEqArg),
+        };
+    }
+    if (wsIdx !== -1) {
+        const value = args[wsIdx + 1];
+        if (!value || value.startsWith('--'))
+            throw new Error('Missing value for --ws');
+        return {
+            value,
+            source: 'cli',
+            args: args.filter((_, idx) => idx !== wsIdx && idx !== wsIdx + 1),
+        };
+    }
+    return {
+        value: null,
+        source: null,
+        args: args.slice(),
+    };
+}
+function resolveActiveWorkstream(cwd, args, env = process.env, deps = {}) {
+    const parsed = parseCliWorkstream(args);
+    const getStored = deps.getStored || ((dir) => getActiveWorkstream(dir, deps));
+    let ws = null;
+    let source = 'none';
+    if (parsed.value) {
+        ws = parsed.value;
+        source = parsed.source ?? 'cli';
+    }
+    else if (env && typeof env['GSD_WORKSTREAM'] === 'string' && env['GSD_WORKSTREAM'].trim()) {
+        ws = env['GSD_WORKSTREAM'].trim();
+        source = 'env';
+    }
+    else {
+        ws = getStored(cwd) || null;
+        source = ws ? 'store' : 'none';
+    }
+    if (ws && !validateWorkstreamName(ws)) {
+        throw new Error('Invalid workstream name: must be alphanumeric, hyphens, underscores, or dots');
+    }
+    return {
+        ws,
+        source,
+        args: parsed.args,
+    };
+}
+function applyResolvedWorkstreamEnv(resolution, env = process.env) {
+    if (!resolution || !resolution.ws)
+        return;
+    env['GSD_WORKSTREAM'] = resolution.ws;
+}
+module.exports = {
+    validateWorkstreamName,
+    getWorkstreamSessionKey,
+    createSharedPointerAdapter,
+    createSessionScopedPointerAdapter,
+    createMemoryPointerAdapter,
+    pickActiveWorkstreamAdapter,
+    getActiveWorkstream,
+    setActiveWorkstream,
+    clearActiveWorkstream,
+    parseCliWorkstream,
+    resolveActiveWorkstream,
+    applyResolvedWorkstreamEnv,
+};

package/gsd-core/bin/lib/adr-parser.cjs

@@ -0,0 +1,399 @@
+"use strict";
+/**
+ * ADR Markdown parser — parses Architecture Decision Record documents into
+ * structured objects for downstream processing (adr command, gap checker, etc.).
+ *
+ * ADR-457 build-at-publish: the hand-written bin/lib/adr-parser.cjs collapsed
+ * to a TypeScript source of truth. Behaviour is preserved byte-for-behaviour
+ * from the prior hand-written .cjs; only types are added.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const security_cjs_1 = require("./security.cjs");
+const STATUS_REJECT_SET = new Set(['superseded', 'rejected', 'deprecated']);
+const CANONICAL_HEADERS = {
+    status: ['status', 'state', 'lifecycle', 'stage'],
+    goal: [
+        'context',
+        'background',
+        'problem statement',
+        'problem',
+        'situation',
+        'forces',
+        'motivation',
+        'issue',
+        'drivers',
+        'pain points',
+        'story',
+        'setting',
+        'premise',
+        'status quo',
+        'context and problem statement',
+    ],
+    decisions: [
+        'decision',
+        'decisions',
+        'resolution',
+        'conclusion',
+        'choice',
+        'we decided',
+        'direction',
+        'approach',
+        'solution',
+        'outcome',
+        'selected option',
+        'recommendation',
+        'strategy',
+        'decision outcome',
+    ],
+    considered_options: [
+        'considered options',
+        'alternatives',
+        'options',
+        'choices',
+        'candidates',
+        'approaches considered',
+        'variants',
+        'trade-offs',
+        'pros and cons of the options',
+        'discussion',
+    ],
+    risks: [
+        'risks',
+        'trade-offs',
+        'drawbacks',
+        'cost',
+        'tensions',
+        'liabilities',
+        'negative consequences',
+        'side effects',
+    ],
+    success_criteria: [
+        'success criteria',
+        'acceptance criteria',
+        'validation',
+        "how we'll know",
+        'metrics',
+        'kpis',
+        'verification',
+        'test strategy',
+        'compliance',
+        'definition of done',
+        'exit criteria',
+        'positive consequences',
+    ],
+    plan_sequence: [
+        'implementation plan',
+        'implementation notes',
+        'steps',
+        'tasks',
+        'roadmap',
+        'sequence',
+        'migration plan',
+        'plan',
+        'action items',
+        'work breakdown',
+        'phases',
+        'milestones',
+        'stages',
+    ],
+    key_files: [
+        'affected files',
+        'files touched',
+        'surface area',
+        'modules affected',
+        'code locations',
+        'file changes',
+        'diff summary',
+        'touched code',
+    ],
+    out_of_scope: [
+        'out of scope',
+        'non-goals',
+        'excluded',
+        'not in this adr',
+        'out of bounds',
+        "won't do",
+        "won't have",
+        'beyond scope',
+        'anti-goals',
+    ],
+    deferred: [
+        'future work',
+        'deferred',
+        'future',
+        'later',
+        'follow-up',
+        'next steps',
+    ],
+    dependencies: [
+        'dependencies',
+        'depends on',
+        'prerequisites',
+        'sequencing',
+        'order',
+        'blocked by',
+        'cross-cuts',
+        'related adrs',
+        'links',
+        'references',
+        'see also',
+        'upstream',
+        'inbound',
+    ],
+    update: [
+        'update',
+        'revision',
+        'amendment',
+        'locked design',
+        'final decision',
+        'post-grilling',
+        'addendum',
+    ],
+    consequences: [
+        'consequences',
+        'implications',
+        'impact',
+        'what this means',
+        'result',
+    ],
+};
+const CONSEQUENCE_NEGATIVE_HINTS = [
+    'negative',
+    'drawback',
+    'risk',
+    'cost',
+    'liability',
+    'trade-off',
+    'tension',
+    'side effect',
+];
+const CONSEQUENCE_POSITIVE_HINTS = [
+    'positive',
+    'success',
+    'metric',
+    'kpi',
+    'verification',
+    'acceptance',
+    'benefit',
+];
+function normalizeAdrHeader(raw) {
+    const s = typeof raw === 'string' ? raw : '';
+    return s
+        .trim()
+        .toLowerCase()
+        .replace(/[\s:._-]+/g, ' ')
+        .replace(/[^\w\s]/g, '')
+        .trim();
+}
+function classifyHeader(normalizedHeader) {
+    for (const [canonical, synonyms] of Object.entries(CANONICAL_HEADERS)) {
+        for (const synonym of synonyms) {
+            if (normalizedHeader === synonym)
+                return canonical;
+            if (normalizedHeader.startsWith(`${synonym} `))
+                return canonical;
+        }
+    }
+    return null;
+}
+function splitEntries(blockText) {
+    return (typeof blockText === 'string' ? blockText : '')
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .map((line) => line.replace(/^[-*+]\s+/, '').trim())
+        .filter(Boolean);
+}
+function parseSections(markdown) {
+    const lines = (typeof markdown === 'string' ? markdown : '').split(/\r?\n/);
+    const sections = [];
+    let current = { heading: null, body: [] };
+    for (const line of lines) {
+        const m = line.match(/^#{1,6}\s+(.*)$/);
+        if (m) {
+            if (current.heading || current.body.length)
+                sections.push(current);
+            current = { heading: m[1].trim(), body: [] };
+        }
+        else {
+            current.body.push(line);
+        }
+    }
+    if (current.heading || current.body.length)
+        sections.push(current);
+    return sections;
+}
+function parseStatusFromSections(sections) {
+    for (const section of sections) {
+        const canonical = classifyHeader(normalizeAdrHeader(section.heading));
+        if (canonical !== 'status')
+            continue;
+        const line = splitEntries(section.body.join('\n'))[0] || '';
+        const norm = normalizeAdrHeader(line);
+        if (!norm)
+            return '';
+        if (norm.includes('accepted'))
+            return 'accepted';
+        if (norm.includes('proposed'))
+            return 'proposed';
+        if (norm.includes('superseded'))
+            return 'superseded';
+        if (norm.includes('rejected'))
+            return 'rejected';
+        if (norm.includes('deprecated'))
+            return 'deprecated';
+        return norm;
+    }
+    return '';
+}
+function pushUnique(target, values) {
+    const seen = new Set(target);
+    for (const value of values) {
+        if (!seen.has(value)) {
+            target.push(value);
+            seen.add(value);
+        }
+    }
+}
+function parseConsequences(lines, out) {
+    for (const entry of lines) {
+        const lower = entry.toLowerCase();
+        if (CONSEQUENCE_NEGATIVE_HINTS.some((hint) => lower.includes(hint))) {
+            out.consequences_negative.push(entry);
+            continue;
+        }
+        if (CONSEQUENCE_POSITIVE_HINTS.some((hint) => lower.includes(hint))) {
+            out.consequences_positive.push(entry);
+            continue;
+        }
+        out.consequences_positive.push(entry);
+    }
+}
+function parseAdrMarkdown(markdown, { sourcePath = '', format = 'auto' } = {}) {
+    const sections = parseSections(markdown);
+    const titleLine = (typeof markdown === 'string' ? markdown : '').split(/\r?\n/).find((line) => /^#\s+/.test(line)) || '';
+    const title = titleLine.replace(/^#\s+/, '').trim();
+    const out = {
+        title,
+        status: parseStatusFromSections(sections) || 'accepted',
+        context: '',
+        decisions: [],
+        options_considered: [],
+        consequences_positive: [],
+        consequences_negative: [],
+        out_of_scope: [],
+        deferred: [],
+        dependencies: [],
+        updates: [],
+        source_path: sourcePath,
+        key_files: [],
+        plan_sequence: [],
+        format,
+        unmapped_headers: [],
+    };
+    for (const section of sections) {
+        const heading = section.heading || '';
+        if (!heading)
+            continue;
+        const canonical = classifyHeader(normalizeAdrHeader(heading));
+        const entries = splitEntries(section.body.join('\n'));
+        const prose = section.body.join('\n').trim();
+        if (!canonical) {
+            out.unmapped_headers.push(heading);
+            continue;
+        }
+        switch (canonical) {
+            case 'goal':
+                if (!out.context && prose)
+                    out.context = prose;
+                break;
+            case 'decisions':
+                pushUnique(out.decisions, entries);
+                break;
+            case 'considered_options':
+                pushUnique(out.options_considered, entries);
+                break;
+            case 'risks':
+                pushUnique(out.consequences_negative, entries);
+                break;
+            case 'success_criteria':
+                pushUnique(out.consequences_positive, entries);
+                break;
+            case 'plan_sequence':
+                pushUnique(out.plan_sequence, entries);
+                break;
+            case 'key_files':
+                pushUnique(out.key_files, entries);
+                break;
+            case 'out_of_scope':
+                pushUnique(out.out_of_scope, entries);
+                break;
+            case 'deferred':
+                pushUnique(out.deferred, entries);
+                break;
+            case 'dependencies':
+                pushUnique(out.dependencies, entries);
+                break;
+            case 'update':
+                out.updates.push({ heading, entries });
+                break;
+            case 'consequences':
+                parseConsequences(entries, out);
+                break;
+            default:
+                break;
+        }
+    }
+    return out;
+}
+function shouldRejectAdrStatus(status) {
+    return STATUS_REJECT_SET.has(normalizeAdrHeader(status));
+}
+function parseCliArgs(argv) {
+    const opts = { input: null, format: 'auto', projectDir: process.cwd() };
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === '--input') {
+            opts.input = argv[++i] || null;
+        }
+        else if (arg === '--format') {
+            opts.format = argv[++i] || 'auto';
+        }
+        else if (arg === '--project-dir') {
+            opts.projectDir = argv[++i] || process.cwd();
+        }
+        else {
+            throw new Error(`Unknown argument: ${arg}`);
+        }
+    }
+    if (!opts.input) {
+        throw new Error('Missing required --input <path>');
+    }
+    return opts;
+}
+function main(argv) {
+    const opts = parseCliArgs(argv);
+    const safePath = (0, security_cjs_1.requireSafePath)(opts.input, node_path_1.default.resolve(opts.projectDir), 'ADR input path', { allowAbsolute: true });
+    const content = node_fs_1.default.readFileSync(safePath, 'utf8');
+    const parsed = parseAdrMarkdown(content, { sourcePath: opts.input ?? undefined, format: opts.format });
+    process.stdout.write(JSON.stringify(parsed, null, 2));
+}
+if (require.main === module) {
+    try {
+        main(process.argv.slice(2));
+    }
+    catch (error) {
+        process.stderr.write(`Error: ${error.message}\n`);
+        process.exit(1);
+    }
+}
+module.exports = {
+    CANONICAL_HEADERS,
+    normalizeAdrHeader,
+    parseAdrMarkdown,
+    shouldRejectAdrStatus,
+};