thachvd-kit 1.0.37 → 1.0.38

package/bin/spec-doctor.js

@@ -0,0 +1,251 @@
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const state = require('./spec-state');
+const links = require('./spec-link');
+
+const SYSTEM_SKILLS = ['system-discovery', 'system-reverse-engineer', 'system-spec-review'];
+
+function commandExists(command) {
+    const checker = process.platform === 'win32' ? 'where' : 'command';
+    const args = process.platform === 'win32' ? [command] : ['-v', command];
+    const result = spawnSync(checker, args, {
+        encoding: 'utf8',
+        shell: process.platform !== 'win32'
+    });
+    return result.status === 0;
+}
+
+function add(checks, level, name, message) {
+    checks.push({ level, name, message });
+}
+
+function runGit(cwd, args) {
+    const result = spawnSync('git', args, {
+        cwd,
+        encoding: 'utf8'
+    });
+    if (result.status !== 0) {
+        return {
+            ok: false,
+            error: (result.stderr || '').trim() || `git ${args.join(' ')} failed`
+        };
+    }
+    return { ok: true, stdout: (result.stdout || '').trim() };
+}
+
+function canonicalPath(value) {
+    const resolved = path.resolve(value);
+    try {
+        return fs.realpathSync.native ? fs.realpathSync.native(resolved) : fs.realpathSync(resolved);
+    } catch {
+        return resolved;
+    }
+}
+
+function inspectSpecStorage(workspaceRoot, manifest) {
+    const specRoot = canonicalPath(path.resolve(workspaceRoot, manifest.spec_root));
+    if (!fs.existsSync(specRoot)) {
+        return { ok: false, message: `spec root is missing: ${manifest.spec_root}` };
+    }
+
+    const top = runGit(specRoot, ['rev-parse', '--show-toplevel']);
+    if (!top.ok) {
+        return {
+            ok: false,
+            message: 'spec root is not inside a Git worktree; generated specs/provenance are not version-controlled'
+        };
+    }
+
+    const gitRoot = canonicalPath(top.stdout);
+    const required = [
+        path.join(specRoot, 'README.md'),
+        path.join(specRoot, '_meta', 'workspace.json'),
+        path.join(specRoot, 'architecture', 'capability-map.md'),
+        state.verificationPath(workspaceRoot, manifest),
+        state.reviewPath(workspaceRoot, manifest)
+    ].filter(filePath => fs.existsSync(filePath));
+
+    const untracked = [];
+    for (const filePath of required) {
+        const relative = path.relative(gitRoot, canonicalPath(filePath)).split(path.sep).join('/');
+        const tracked = runGit(gitRoot, ['ls-files', '--error-unmatch', '--', relative]);
+        if (!tracked.ok) untracked.push(relative);
+    }
+
+    const specRelative = path.relative(gitRoot, specRoot).split(path.sep).join('/') || '.';
+    const status = runGit(gitRoot, ['status', '--porcelain', '--', specRelative]);
+    if (!status.ok) return { ok: false, message: status.error };
+
+    if (untracked.length > 0 || status.stdout) {
+        const parts = [];
+        if (untracked.length > 0) parts.push(`${untracked.length} key spec file(s) are not tracked`);
+        if (status.stdout) parts.push('spec root has uncommitted changes');
+        return {
+            ok: false,
+            message: `${parts.join('; ')}. Commit reviewed specs/provenance before treating them as durable.`
+        };
+    }
+
+    return { ok: true, message: `spec root is clean and version-controlled in ${gitRoot}` };
+}
+
+function runDoctor(workspaceRoot, manifest, options = {}) {
+    const checks = [];
+    const binaryExists = options.commandExists || commandExists;
+
+    add(checks, 'ok', 'manifest', `.thachvd/system.json valid for ${manifest.name}; profile=${manifest.profile || 'auto'}; language=${manifest.language || 'en'}`);
+
+    if (binaryExists('codebase-memory-mcp')) {
+        add(checks, 'ok', 'codebase-memory', 'codebase-memory-mcp is installed');
+    } else {
+        add(checks, 'warn', 'codebase-memory', 'codebase-memory-mcp is not available on PATH');
+    }
+
+    const heads = state.captureRepoHeads(workspaceRoot, manifest, options);
+    for (const repo of manifest.repos) {
+        const repoRoot = path.resolve(workspaceRoot, repo.path);
+        if (!fs.existsSync(repoRoot)) {
+            add(checks, 'error', `repo:${repo.name}`, `repository path is missing: ${repo.path}`);
+            continue;
+        }
+        const head = heads[repo.name];
+        if (!head || !head.ok) {
+            add(checks, 'error', `repo:${repo.name}`, head ? head.error : 'Git HEAD unavailable');
+        } else {
+            add(checks, 'ok', `repo:${repo.name}`, `${repo.path} @ ${head.commit.slice(0, 12)}`);
+        }
+    }
+
+    for (const skill of SYSTEM_SKILLS) {
+        const missing = [];
+        for (const surface of ['.agents', '.claude']) {
+            const filePath = path.join(workspaceRoot, surface, 'skills', skill, 'SKILL.md');
+            if (!fs.existsSync(filePath)) missing.push(surface);
+        }
+        if (missing.length === 0) add(checks, 'ok', `skill:${skill}`, 'installed on agent + Claude surfaces');
+        else add(checks, 'warn', `skill:${skill}`, `missing from: ${missing.join(', ')}`);
+    }
+
+    const storage = inspectSpecStorage(workspaceRoot, manifest);
+    add(checks, storage.ok ? 'ok' : 'warn', 'spec-storage', storage.message);
+
+    const workspaceSnapshot = path.join(workspaceRoot, manifest.spec_root, '_meta', 'workspace.json');
+    if (!fs.existsSync(workspaceSnapshot)) {
+        add(checks, 'warn', 'workspace-snapshot', 'missing; rerun spec init --yes to create a durable topology snapshot');
+    } else {
+        try {
+            const snapshot = JSON.parse(fs.readFileSync(workspaceSnapshot, 'utf8'));
+            const comparable = value => JSON.stringify({
+                schema_version: value.schema_version,
+                name: value.name,
+                spec_root: value.spec_root,
+                language: value.language,
+                profile: value.profile || 'auto',
+                repos: value.repos
+            });
+            if (comparable(snapshot) === comparable(manifest)) {
+                add(checks, 'ok', 'workspace-snapshot', 'durable topology snapshot matches the active manifest');
+            } else {
+                add(checks, 'warn', 'workspace-snapshot', 'snapshot differs from .thachvd/system.json; refresh with spec init --yes');
+            }
+        } catch (error) {
+            add(checks, 'error', 'workspace-snapshot', `cannot parse workspace snapshot: ${error.message}`);
+        }
+    }
+
+    const capabilityMap = path.join(workspaceRoot, manifest.spec_root, 'architecture', 'capability-map.md');
+    if (fs.existsSync(capabilityMap)) add(checks, 'ok', 'capability-map', 'capability map exists');
+    else add(checks, 'warn', 'capability-map', 'missing; run spec discover + /system-discovery');
+
+    const progress = state.readProgress(workspaceRoot, manifest);
+    if (!progress) {
+        add(checks, 'warn', 'reverse-progress', 'not started');
+    } else if (progress.status === 'completed') {
+        const capabilityStates = Object.values(progress.capabilities || {});
+        const blocked = capabilityStates.filter(item => item.status === 'blocked').length;
+        add(checks, blocked > 0 ? 'warn' : 'ok', 'reverse-progress',
+            `completed; ${capabilityStates.length} capabilities, ${blocked} blocked`);
+    } else {
+        const capabilityStates = Object.values(progress.capabilities || {});
+        const completed = capabilityStates.filter(item => item.status === 'completed').length;
+        add(checks, 'warn', 'reverse-progress',
+            `${progress.status}; ${completed}/${capabilityStates.length || '?'} capabilities completed`);
+    }
+
+    let verification = null;
+    let verificationFailed = false;
+    try {
+        verification = state.readVerification(workspaceRoot, manifest);
+    } catch (error) {
+        verificationFailed = true;
+        add(checks, 'error', 'verification', error.message);
+    }
+
+    if (!verification && !verificationFailed) {
+        add(checks, 'warn', 'verification', 'not independently verified');
+    } else if (verification) {
+        try {
+            state.validateVerification(manifest, verification);
+            const statuses = Object.values(verification.capabilities || {});
+            const verified = statuses.filter(item => item.status === 'verified').length;
+            const unresolved = statuses.length - verified;
+            add(checks, unresolved === 0 ? 'ok' : 'warn', 'verification',
+                `${verified}/${statuses.length} capabilities verified; ${unresolved} unresolved`);
+
+            const reviewFile = state.reviewPath(workspaceRoot, manifest);
+            if (fs.existsSync(reviewFile)) add(checks, 'ok', 'review-report', 'review.md exists');
+            else add(checks, 'warn', 'review-report', 'verification exists but review.md is missing');
+
+            const drift = state.checkSpecDrift(workspaceRoot, manifest, verification, options);
+            add(checks, drift.stale_count === 0 ? 'ok' : 'warn', 'drift',
+                drift.stale_count === 0
+                    ? 'no stale/unknown verified capabilities detected'
+                    : `${drift.stale_count} stale/unknown capabilities detected; run spec check`);
+        } catch (error) {
+            add(checks, 'error', 'verification', error.message);
+        }
+    }
+
+    for (const repo of manifest.repos) {
+        const agentsPath = path.join(workspaceRoot, repo.path, 'AGENTS.md');
+        if (!fs.existsSync(agentsPath)) {
+            add(checks, 'warn', `agent-link:${repo.name}`, 'AGENTS.md missing or not linked');
+            continue;
+        }
+        const content = fs.readFileSync(agentsPath, 'utf8');
+        if (content.includes(links.START) && content.includes(links.END)) {
+            add(checks, 'ok', `agent-link:${repo.name}`, 'system spec managed block present');
+        } else {
+            add(checks, 'warn', `agent-link:${repo.name}`, 'system spec managed block missing; run spec link after verification');
+        }
+    }
+
+    const counts = {
+        ok: checks.filter(item => item.level === 'ok').length,
+        warn: checks.filter(item => item.level === 'warn').length,
+        error: checks.filter(item => item.level === 'error').length
+    };
+    return { checks, counts };
+}
+
+function formatDoctorReport(report) {
+    const label = { ok: 'OK', warn: 'WARN', error: 'ERROR' };
+    const lines = ['System spec doctor', ''];
+    for (const check of report.checks) {
+        lines.push(`${label[check.level]} ${check.name}: ${check.message}`);
+    }
+    lines.push('');
+    lines.push(`Summary: ${report.counts.ok} OK, ${report.counts.warn} WARN, ${report.counts.error} ERROR`);
+    return lines.join('\n');
+}
+
+module.exports = {
+    SYSTEM_SKILLS,
+    canonicalPath,
+    commandExists,
+    runGit,
+    inspectSpecStorage,
+    runDoctor,
+    formatDoctorReport
+};

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
+};