thachvd-kit 1.0.36 → 1.0.38

package/bin/spec-link.js

@@ -0,0 +1,97 @@
+const fs = require('fs');
+const path = require('path');
+
+const START = '<!-- thachvd-kit:system-specs:start -->';
+const END = '<!-- thachvd-kit:system-specs:end -->';
+
+function portable(value) {
+    return value.split(path.sep).join('/');
+}
+
+function relativeReference(fromDir, targetPath) {
+    const relative = portable(path.relative(fromDir, targetPath) || '.');
+    return relative.startsWith('.') ? relative : `./${relative}`;
+}
+
+function renderBlock(workspaceRoot, repoRoot, manifest) {
+    const specRoot = path.resolve(workspaceRoot, manifest.spec_root);
+    const manifestPath = path.join(workspaceRoot, '.thachvd', 'system.json');
+    const specRef = relativeReference(repoRoot, specRoot);
+    const manifestRef = relativeReference(repoRoot, manifestPath);
+    return `${START}
+## System Specifications
+
+This repository is part of the **${manifest.name}** documented system.
+
+- System manifest: \`${manifestRef}\`
+- System specs: \`${specRef}\`
+
+Before changing observable behavior:
+
+1. Read \`${specRef}/architecture/system-overview.md\`.
+2. Read \`${specRef}/architecture/capability-map.md\` and identify the affected capability.
+3. Read the relevant capability PRD/design and any cross-repository flow or contract it touches.
+4. If \`${specRef}/_meta/verification.json\` exists, run \`thachvd-kit spec check\` before relying on the spec; investigate STALE/UNKNOWN capabilities against code.
+5. Treat implementation and tests as the current source of truth. If code and reviewed spec disagree, report the drift; do not silently choose one.
+6. Update/re-verify reviewed specs when an approved behavior or contract change makes them stale.
+
+Do not infer business rationale from code when the rationale is undocumented.
+${END}`;
+}
+
+function upsertManagedBlock(content, block) {
+    const start = content.indexOf(START);
+    const end = content.indexOf(END);
+    if ((start >= 0) !== (end >= 0) || (start >= 0 && end < start)) {
+        throw new Error('Malformed thachvd-kit system-spec markers in AGENTS.md');
+    }
+    if (start >= 0 && end >= start) {
+        const after = end + END.length;
+        return content.slice(0, start) + block + content.slice(after);
+    }
+    const trimmed = content.replace(/\s+$/, '');
+    return `${trimmed}${trimmed ? '\n\n' : ''}${block}\n`;
+}
+
+function linkRepositories(workspaceRoot, manifest, options = {}) {
+    const results = [];
+    for (const repo of manifest.repos) {
+        const repoRoot = path.resolve(workspaceRoot, repo.path);
+        if (!fs.existsSync(repoRoot) || !fs.statSync(repoRoot).isDirectory()) {
+            results.push({ name: repo.name, ok: false, error: 'repository path is missing' });
+            continue;
+        }
+        const agentsPath = path.join(repoRoot, 'AGENTS.md');
+        const existing = fs.existsSync(agentsPath) ? fs.readFileSync(agentsPath, 'utf8') : '';
+        try {
+            const block = renderBlock(workspaceRoot, repoRoot, manifest);
+            const next = upsertManagedBlock(existing, block);
+            const changed = next !== existing;
+            if (changed && !options.dryRun) fs.writeFileSync(agentsPath, next, 'utf8');
+            results.push({
+                name: repo.name,
+                ok: true,
+                changed,
+                dryRun: options.dryRun === true,
+                path: portable(path.relative(workspaceRoot, agentsPath))
+            });
+        } catch (error) {
+            results.push({
+                name: repo.name,
+                ok: false,
+                path: portable(path.relative(workspaceRoot, agentsPath)),
+                error: error.message
+            });
+        }
+    }
+    return results;
+}
+
+module.exports = {
+    START,
+    END,
+    relativeReference,
+    renderBlock,
+    upsertManagedBlock,
+    linkRepositories
+};

package/bin/spec-recipe.js

@@ -0,0 +1,74 @@
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const MARKETPLACE = 'shinpr/claude-code-workflows';
+const MARKETPLACE_NAME = 'claude-code-workflows';
+
+function commandExists(command) {
+    const checker = process.platform === 'win32' ? 'where' : 'command';
+    const args = process.platform === 'win32' ? [command] : ['-v', command];
+    return spawnSync(checker, args, { encoding: 'utf8', shell: process.platform !== 'win32' }).status === 0;
+}
+
+function setupRecipePlugin(workspaceRoot, manifest, options = {}) {
+    const plugin = options.fullstack ? 'dev-workflows-fullstack' : 'dev-workflows';
+    const commands = [
+        ['plugin', 'marketplace', 'add', MARKETPLACE, '--scope', 'project'],
+        ['plugin', 'install', `${plugin}@${MARKETPLACE_NAME}`, '--scope', 'project']
+    ];
+    if (options.skipBinaryCheck !== true && !options.dryRun && !commandExists('claude')) {
+        return { ok: false, plugin, commands, error: 'Claude Code CLI is not installed; install the plugin manually or use another client.', results: [] };
+    }
+    const spawn = options.spawn || spawnSync;
+    const results = [];
+    for (const repo of manifest.repos) {
+        const cwd = path.resolve(workspaceRoot, repo.path);
+        if (!fs.existsSync(cwd) || !fs.statSync(cwd).isDirectory()) {
+            results.push({ name: repo.name, ok: false, error: 'repository path is missing' });
+            continue;
+        }
+        if (options.dryRun) {
+            results.push({ name: repo.name, ok: true, dryRun: true, cwd, commands });
+            continue;
+        }
+        let repoOk = true;
+        for (const args of commands) {
+            const result = spawn('claude', args, {
+                cwd,
+                encoding: 'utf8',
+                stdio: 'inherit',
+                shell: process.platform === 'win32'
+            });
+            if (result.status !== 0) {
+                results.push({ name: repo.name, ok: false, cwd, failedCommand: ['claude', ...args], status: result.status });
+                repoOk = false;
+                break;
+            }
+        }
+        if (repoOk) results.push({ name: repo.name, ok: true, cwd });
+    }
+    return {
+        ok: results.length === manifest.repos.length && results.every(result => result.ok),
+        plugin,
+        commands,
+        dryRun: options.dryRun === true,
+        results
+    };
+}
+
+function normalizeCapability(value) {
+    if (!value || typeof value !== 'string') throw new Error('Capability name is required');
+    const slug = value.trim().toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+    if (!slug) throw new Error('Capability name must contain letters or numbers');
+    return slug;
+}
+
+module.exports = {
+    MARKETPLACE,
+    MARKETPLACE_NAME,
+    setupRecipePlugin,
+    normalizeCapability
+};

package/bin/spec-state.js

@@ -0,0 +1,415 @@
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const META_DIR = '_meta';
+const VERIFICATION_FILE = 'verification.json';
+const REVIEW_FILE = 'review.md';
+const PROGRESS_FILE = 'reverse-progress.json';
+const VERIFICATION_SCHEMA_VERSION = 1;
+const PROGRESS_SCHEMA_VERSION = 1;
+
+function portable(value) {
+    return value.split(path.sep).join('/');
+}
+
+function nowIso() {
+    return new Date().toISOString();
+}
+
+function metaRoot(workspaceRoot, manifest) {
+    return path.join(workspaceRoot, manifest.spec_root, META_DIR);
+}
+
+function verificationPath(workspaceRoot, manifest) {
+    return path.join(metaRoot(workspaceRoot, manifest), VERIFICATION_FILE);
+}
+
+function reviewPath(workspaceRoot, manifest) {
+    return path.join(metaRoot(workspaceRoot, manifest), REVIEW_FILE);
+}
+
+function progressSlug(capability) {
+    if (!capability) return null;
+    const slug = String(capability).trim().toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+    if (!slug) throw new Error('Capability name must contain letters or numbers');
+    return slug;
+}
+
+function progressFileName(capability = null) {
+    const slug = progressSlug(capability);
+    return slug ? `reverse-progress-${slug}.json` : PROGRESS_FILE;
+}
+
+function progressPath(workspaceRoot, manifest, capability = null) {
+    return path.join(metaRoot(workspaceRoot, manifest), progressFileName(capability));
+}
+
+function ensureMetaRoot(workspaceRoot, manifest) {
+    const directory = metaRoot(workspaceRoot, manifest);
+    fs.mkdirSync(directory, { recursive: true });
+    return directory;
+}
+
+function runGit(repoRoot, args, options = {}) {
+    const spawn = options.spawn || spawnSync;
+    const result = spawn('git', args, {
+        cwd: repoRoot,
+        encoding: 'utf8'
+    });
+    if (result.status !== 0) {
+        const stderr = typeof result.stderr === 'string' ? result.stderr.trim() : '';
+        return { ok: false, error: stderr || `git ${args.join(' ')} failed`, status: result.status };
+    }
+    return { ok: true, stdout: typeof result.stdout === 'string' ? result.stdout.trim() : '' };
+}
+
+function getRepoHead(repoRoot, options = {}) {
+    const result = runGit(repoRoot, ['rev-parse', 'HEAD'], options);
+    if (!result.ok) return result;
+    return { ok: true, commit: result.stdout };
+}
+
+function captureRepoHeads(workspaceRoot, manifest, options = {}) {
+    const heads = {};
+    for (const repo of manifest.repos) {
+        const repoRoot = path.resolve(workspaceRoot, repo.path);
+        if (!fs.existsSync(repoRoot)) {
+            heads[repo.name] = { ok: false, path: repo.path, error: 'repository path is missing' };
+            continue;
+        }
+        const head = getRepoHead(repoRoot, options);
+        heads[repo.name] = head.ok
+            ? { ok: true, path: repo.path, commit: head.commit }
+            : { ok: false, path: repo.path, error: head.error };
+    }
+    return heads;
+}
+
+function readJsonFile(filePath, label) {
+    if (!fs.existsSync(filePath)) return null;
+    try {
+        return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    } catch (error) {
+        throw new Error(`Cannot parse ${label}: ${error.message}`);
+    }
+}
+
+function readVerification(workspaceRoot, manifest) {
+    const filePath = verificationPath(workspaceRoot, manifest);
+    const data = readJsonFile(filePath, `${manifest.spec_root}/${META_DIR}/${VERIFICATION_FILE}`);
+    if (!data) return null;
+    if (data.schema_version !== VERIFICATION_SCHEMA_VERSION) {
+        throw new Error(`Unsupported verification schema_version: ${data.schema_version}`);
+    }
+    if (data.system && data.system !== manifest.name) {
+        throw new Error(`verification system mismatch: expected ${manifest.name}, got ${data.system}`);
+    }
+    if (!data.repositories || typeof data.repositories !== 'object') {
+        throw new Error('verification.json requires repositories');
+    }
+    if (!data.capabilities || typeof data.capabilities !== 'object') {
+        throw new Error('verification.json requires capabilities');
+    }
+    return data;
+}
+
+function normalizeSourcePath(value) {
+    if (typeof value !== 'string' || !value.trim()) return null;
+    const raw = value.trim().replace(/\\/g, '/');
+    if (raw.startsWith('/') || /^[A-Za-z]:\//.test(raw)) {
+        throw new Error(`source path must be repository-relative: ${value}`);
+    }
+    const normalized = raw.replace(/^\.\//, '').replace(/\/+/g, '/').replace(/\/$/, '');
+    if (!normalized || normalized === '.' || normalized === '..' || normalized.startsWith('../') || normalized.includes('/../')) {
+        throw new Error(`source path must stay inside the repository: ${value}`);
+    }
+    return normalized;
+}
+
+function normalizeSourcePaths(value) {
+    if (!Array.isArray(value)) return [];
+    return [...new Set(value
+        .map(normalizeSourcePath)
+        .filter(Boolean))];
+}
+
+function validateVerification(manifest, data) {
+    if (!data || typeof data !== 'object') throw new Error('verification data must be an object');
+    if (data.schema_version !== VERIFICATION_SCHEMA_VERSION) {
+        throw new Error(`verification schema_version must be ${VERIFICATION_SCHEMA_VERSION}`);
+    }
+    if (data.system && data.system !== manifest.name) {
+        throw new Error(`verification system mismatch: expected ${manifest.name}, got ${data.system}`);
+    }
+    const repoNames = new Set(manifest.repos.map(repo => repo.name));
+    for (const repo of manifest.repos) {
+        if (!data.repositories || !data.repositories[repo.name]) {
+            throw new Error(`verification is missing repository: ${repo.name}`);
+        }
+    }
+    for (const [repoName, repoState] of Object.entries(data.repositories || {})) {
+        if (!repoNames.has(repoName)) throw new Error(`verification references unknown repository: ${repoName}`);
+        if (!repoState || typeof repoState.commit !== 'string' || !/^[0-9a-f]{40}$/i.test(repoState.commit.trim())) {
+            throw new Error(`verification repository ${repoName} requires a full Git commit SHA`);
+        }
+    }
+    const capabilityEntries = Object.entries(data.capabilities || {});
+    if (capabilityEntries.length === 0) throw new Error('verification requires at least one capability');
+    for (const [slug, capability] of capabilityEntries) {
+        if (!capability || typeof capability !== 'object') throw new Error(`invalid capability verification: ${slug}`);
+        if (!['verified', 'needs_review', 'blocked'].includes(capability.status)) {
+            throw new Error(`invalid verification status for ${slug}: ${capability.status}`);
+        }
+        capability.source_paths = capability.source_paths || {};
+        capability.verified_commits = capability.verified_commits || {};
+        for (const [repoName, sourcePaths] of Object.entries(capability.source_paths)) {
+            if (!repoNames.has(repoName)) throw new Error(`capability ${slug} references unknown repository: ${repoName}`);
+            capability.source_paths[repoName] = normalizeSourcePaths(sourcePaths);
+            const commit = capability.verified_commits[repoName];
+            if (capability.status === 'verified' && (!commit || !/^[0-9a-f]{40}$/i.test(commit))) {
+                throw new Error(`verified capability ${slug} requires verified_commits.${repoName}`);
+            }
+        }
+        for (const [repoName, commit] of Object.entries(capability.verified_commits)) {
+            if (!repoNames.has(repoName)) throw new Error(`capability ${slug} verified_commits references unknown repository: ${repoName}`);
+            if (!/^[0-9a-f]{40}$/i.test(String(commit))) {
+                throw new Error(`capability ${slug} has invalid verified commit for ${repoName}`);
+            }
+        }
+
+        if (capability.status === 'verified') {
+            const sourceCount = Object.values(capability.source_paths)
+                .reduce((sum, paths) => sum + paths.length, 0);
+            if (sourceCount === 0) {
+                throw new Error(`verified capability ${slug} requires at least one source path`);
+            }
+            if (!capability.evidence || typeof capability.evidence !== 'object') {
+                throw new Error(`verified capability ${slug} requires evidence counts`);
+            }
+            const requiredCounts = [
+                'implementation_claims_checked',
+                'test_claims_checked',
+                'unsupported_claims',
+                'potential_gaps',
+                'broken_anchors'
+            ];
+            for (const key of requiredCounts) {
+                const value = capability.evidence[key];
+                if (!Number.isInteger(value) || value < 0) {
+                    throw new Error(`verified capability ${slug} requires non-negative integer evidence.${key}`);
+                }
+            }
+            for (const key of ['unsupported_claims', 'potential_gaps', 'broken_anchors']) {
+                if (capability.evidence[key] !== 0) {
+                    throw new Error(`verified capability ${slug} cannot have ${key} > 0; use needs_review instead`);
+                }
+            }
+        }
+    }
+    return data;
+}
+
+function createProgress(manifest, capability = null) {
+    return {
+        schema_version: PROGRESS_SCHEMA_VERSION,
+        system: manifest.name,
+        mode: capability ? 'targeted' : 'full',
+        target: capability || null,
+        started_at: nowIso(),
+        updated_at: nowIso(),
+        status: 'pending',
+        capabilities: {}
+    };
+}
+
+function readProgress(workspaceRoot, manifest, capability = null) {
+    const filePath = progressPath(workspaceRoot, manifest, capability);
+    const data = readJsonFile(filePath, `${manifest.spec_root}/${META_DIR}/${progressFileName(capability)}`);
+    if (!data) return null;
+    if (data.schema_version !== PROGRESS_SCHEMA_VERSION) {
+        throw new Error(`Unsupported reverse progress schema_version: ${data.schema_version}`);
+    }
+    return data;
+}
+
+function ensureProgress(workspaceRoot, manifest, capability = null, options = {}) {
+    ensureMetaRoot(workspaceRoot, manifest);
+    const filePath = progressPath(workspaceRoot, manifest, capability);
+    const existing = readProgress(workspaceRoot, manifest, capability);
+    if (existing && !options.reset) {
+        const sameMode = existing.mode === (capability ? 'targeted' : 'full');
+        const sameTarget = (existing.target || null) === (capability || null);
+        if (sameMode && sameTarget && existing.status !== 'completed') {
+            return { path: filePath, progress: existing, created: false, resumed: true };
+        }
+        if (sameMode && sameTarget && existing.status === 'completed') {
+            return { path: filePath, progress: existing, created: false, resumed: false, completed: true };
+        }
+    }
+    const progress = createProgress(manifest, capability);
+    fs.writeFileSync(filePath, JSON.stringify(progress, null, 2) + '\n', 'utf8');
+    return { path: filePath, progress, created: true, resumed: false };
+}
+
+function pathMatches(changedFile, sourcePath) {
+    const changed = portable(changedFile).replace(/^\.\//, '');
+    const source = portable(sourcePath).replace(/^\.\//, '').replace(/\/$/, '');
+    return changed === source || changed.startsWith(source + '/') || source.startsWith(changed + '/');
+}
+
+function changedFilesSince(repoRoot, baseCommit, options = {}) {
+    const head = getRepoHead(repoRoot, options);
+    if (!head.ok) return { ok: false, error: head.error };
+
+    const ancestry = runGit(repoRoot, ['cat-file', '-e', `${baseCommit}^{commit}`], options);
+    if (!ancestry.ok) {
+        return { ok: false, commit: head.commit, error: `verified commit is unavailable locally: ${baseCommit}` };
+    }
+
+    const changed = new Set();
+    if (head.commit !== baseCommit) {
+        const diff = runGit(repoRoot, ['diff', '--name-only', '--no-renames', `${baseCommit}..${head.commit}`], options);
+        if (!diff.ok) return { ok: false, commit: head.commit, error: diff.error };
+        for (const file of diff.stdout ? diff.stdout.split(/\r?\n/).filter(Boolean) : []) changed.add(portable(file));
+    }
+
+    for (const args of [
+        ['diff', '--name-only', '--no-renames', 'HEAD'],
+        ['diff', '--name-only', '--no-renames', '--cached'],
+        ['ls-files', '--others', '--exclude-standard']
+    ]) {
+        const result = runGit(repoRoot, args, options);
+        if (!result.ok) return { ok: false, commit: head.commit, error: result.error };
+        for (const file of result.stdout ? result.stdout.split(/\r?\n/).filter(Boolean) : []) changed.add(portable(file));
+    }
+
+    return { ok: true, commit: head.commit, changed: [...changed].sort() };
+}
+
+function checkSpecDrift(workspaceRoot, manifest, verification, options = {}) {
+    validateVerification(manifest, verification);
+    const repoStates = {};
+    for (const repo of manifest.repos) {
+        const verified = verification.repositories[repo.name];
+        const repoRoot = path.resolve(workspaceRoot, repo.path);
+        const head = getRepoHead(repoRoot, options);
+        repoStates[repo.name] = head.ok
+            ? { ok: true, path: repo.path, verified_commit: verified.commit, commit: head.commit }
+            : { ok: false, path: repo.path, verified_commit: verified.commit, error: head.error };
+    }
+
+    const capabilities = {};
+    const deltaCache = new Map();
+    for (const [slug, capability] of Object.entries(verification.capabilities)) {
+        if (capability.status !== 'verified') {
+            capabilities[slug] = {
+                status: capability.status,
+                stale: true,
+                reason: `verification status is ${capability.status}`,
+                changed_files: {}
+            };
+            continue;
+        }
+
+        let stale = false;
+        let unknown = false;
+        const changedFiles = {};
+        const reasons = [];
+
+        for (const repo of manifest.repos) {
+            const repoState = repoStates[repo.name];
+            const sourcePaths = normalizeSourcePaths((capability.source_paths || {})[repo.name]);
+            if (sourcePaths.length === 0) continue;
+
+            if (!repoState || !repoState.ok) {
+                unknown = true;
+                reasons.push(`${repo.name}: ${repoState ? repoState.error : 'missing repository state'}`);
+                continue;
+            }
+
+            const baseline = (capability.verified_commits || {})[repo.name]
+                || verification.repositories[repo.name].commit;
+            const repoRoot = path.resolve(workspaceRoot, repo.path);
+            const cacheKey = `${repo.name}:${baseline}`;
+            let delta = deltaCache.get(cacheKey);
+            if (!delta) {
+                delta = changedFilesSince(repoRoot, baseline, options);
+                deltaCache.set(cacheKey, delta);
+            }
+            if (!delta.ok) {
+                unknown = true;
+                reasons.push(`${repo.name}: ${delta.error}`);
+                continue;
+            }
+
+            const relevant = delta.changed.filter(file => sourcePaths.some(source => pathMatches(file, source)));
+            if (relevant.length > 0) {
+                stale = true;
+                changedFiles[repo.name] = relevant;
+            }
+        }
+
+        capabilities[slug] = {
+            status: unknown ? 'unknown' : (stale ? 'stale' : 'current'),
+            stale: stale || unknown,
+            reason: reasons.join('; ') || null,
+            changed_files: changedFiles
+        };
+    }
+
+    return {
+        checked_at: nowIso(),
+        repositories: repoStates,
+        capabilities,
+        stale_count: Object.values(capabilities).filter(item => item.stale).length
+    };
+}
+
+function formatDriftReport(report) {
+    const lines = ['System spec drift check', ''];
+    for (const [slug, result] of Object.entries(report.capabilities)) {
+        const marker = result.status === 'current' ? 'OK' : result.status.toUpperCase();
+        lines.push(`${marker} ${slug}`);
+        if (result.reason) lines.push(`  ${result.reason}`);
+        for (const [repoName, files] of Object.entries(result.changed_files || {})) {
+            lines.push(`  ${repoName}: ${files.length} relevant changed file(s)`);
+            for (const file of files.slice(0, 10)) lines.push(`    - ${file}`);
+            if (files.length > 10) lines.push(`    - ... ${files.length - 10} more`);
+        }
+    }
+    lines.push('');
+    lines.push(`Potentially stale/unknown capabilities: ${report.stale_count}`);
+    return lines.join('\n');
+}
+
+module.exports = {
+    META_DIR,
+    VERIFICATION_FILE,
+    REVIEW_FILE,
+    PROGRESS_FILE,
+    VERIFICATION_SCHEMA_VERSION,
+    PROGRESS_SCHEMA_VERSION,
+    metaRoot,
+    verificationPath,
+    reviewPath,
+    progressSlug,
+    progressFileName,
+    progressPath,
+    ensureMetaRoot,
+    getRepoHead,
+    captureRepoHeads,
+    readVerification,
+    validateVerification,
+    createProgress,
+    readProgress,
+    ensureProgress,
+    normalizeSourcePath,
+    normalizeSourcePaths,
+    pathMatches,
+    changedFilesSince,
+    checkSpecDrift,
+    formatDriftReport
+};