thachvd-kit 1.0.36 → 1.0.38

package/bin/config.js

@@ -0,0 +1,164 @@
+const fs = require('fs');
+const path = require('path');
+
+const CONFIG_RELATIVE_PATH = path.join('.thachvd', 'config.json');
+const SUPPORTED_SPEC_LANGUAGES = new Set(['en', 'vi']);
+const SUPPORTED_SPEC_PROFILES = new Set(['auto', 'backend', 'frontend', 'fullstack', 'mobile', 'infra']);
+
+function resolveHome(env = process.env) {
+    return env.USERPROFILE || env.HOME || null;
+}
+
+function configPath(homeDir) {
+    return path.join(homeDir, CONFIG_RELATIVE_PATH);
+}
+
+function readConfig(homeDir) {
+    if (!homeDir) return {};
+    const filePath = configPath(homeDir);
+    if (!fs.existsSync(filePath)) return {};
+    try {
+        const parsed = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+        return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
+    } catch (error) {
+        throw new Error(`Cannot parse ${filePath}: ${error.message}`);
+    }
+}
+
+function writeConfig(homeDir, config) {
+    if (!homeDir) throw new Error('Cannot determine home directory from USERPROFILE or HOME.');
+    const filePath = configPath(homeDir);
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, JSON.stringify(config, null, 2) + '\n', 'utf8');
+    return filePath;
+}
+
+function normalizeLanguage(value) {
+    const language = String(value || '').trim().toLowerCase();
+    if (!SUPPORTED_SPEC_LANGUAGES.has(language)) {
+        throw new Error(`Unsupported spec language: ${value}. Supported values: en, vi`);
+    }
+    return language;
+}
+
+function normalizeProfile(value) {
+    const profile = String(value || '').trim().toLowerCase();
+    if (!SUPPORTED_SPEC_PROFILES.has(profile)) {
+        throw new Error(`Unsupported spec profile: ${value}. Supported values: auto, backend, frontend, fullstack, mobile, infra`);
+    }
+    return profile;
+}
+
+function getDefaultSpecProfile(env = process.env) {
+    const homeDir = resolveHome(env);
+    if (!homeDir) return null;
+    const config = readConfig(homeDir);
+    return config.spec_profile ? normalizeProfile(config.spec_profile) : null;
+}
+
+function getDefaultSpecLanguage(env = process.env) {
+    const homeDir = resolveHome(env);
+    if (!homeDir) return null;
+    const config = readConfig(homeDir);
+    return config.spec_language ? normalizeLanguage(config.spec_language) : null;
+}
+
+function printHelp() {
+    console.log(`thachvd-kit config
+
+Usage:
+  thachvd-kit config show
+  thachvd-kit config set spec-language en|vi
+  thachvd-kit config unset spec-language
+  thachvd-kit config set spec-profile auto|backend|frontend|fullstack|mobile|infra
+  thachvd-kit config unset spec-profile
+
+The user-level config is stored at ~/.thachvd/config.json (or the platform-equivalent home directory).
+Project-level --language and --profile always override their user defaults.
+`);
+}
+
+function runConfigCommand(args, options = {}) {
+    const env = options.env || process.env;
+    const homeDir = options.homeDir || resolveHome(env);
+    const command = args[0] || 'show';
+
+    try {
+        if (command === '--help' || command === '-h' || command === 'help') {
+            printHelp();
+            return 0;
+        }
+
+        if (command === 'show') {
+            const config = readConfig(homeDir);
+            console.log(`Config: ${homeDir ? configPath(homeDir) : '(home unavailable)'}`);
+            console.log(`spec-language: ${config.spec_language || '(default: en)'}`);
+            console.log(`spec-profile: ${config.spec_profile || '(default: auto)'}`);
+            return 0;
+        }
+
+        if (command === 'set') {
+            if (!args[1] || !args[2]) {
+                throw new Error('Usage: thachvd-kit config set spec-language en|vi OR spec-profile auto|backend|frontend|fullstack|mobile|infra');
+            }
+            const config = readConfig(homeDir);
+            if (args[1] === 'spec-language') {
+                const language = normalizeLanguage(args[2]);
+                config.spec_language = language;
+                const filePath = writeConfig(homeDir, config);
+                console.log(`Updated ${filePath}`);
+                console.log(`spec-language: ${language}`);
+                return 0;
+            }
+            if (args[1] === 'spec-profile') {
+                const profile = normalizeProfile(args[2]);
+                config.spec_profile = profile;
+                const filePath = writeConfig(homeDir, config);
+                console.log(`Updated ${filePath}`);
+                console.log(`spec-profile: ${profile}`);
+                return 0;
+            }
+            throw new Error(`Unknown config key: ${args[1]}`);
+        }
+
+        if (command === 'unset') {
+            const config = readConfig(homeDir);
+            if (args[1] === 'spec-language') {
+                delete config.spec_language;
+                const filePath = writeConfig(homeDir, config);
+                console.log(`Updated ${filePath}`);
+                console.log('spec-language: (default: en)');
+                return 0;
+            }
+            if (args[1] === 'spec-profile') {
+                delete config.spec_profile;
+                const filePath = writeConfig(homeDir, config);
+                console.log(`Updated ${filePath}`);
+                console.log('spec-profile: (default: auto)');
+                return 0;
+            }
+            throw new Error('Usage: thachvd-kit config unset spec-language|spec-profile');
+        }
+
+        throw new Error(`Unknown config command: ${command}`);
+    } catch (error) {
+        console.error(`config ${command} failed: ${error.message}`);
+        process.exitCode = 1;
+        return 1;
+    }
+}
+
+module.exports = {
+    CONFIG_RELATIVE_PATH,
+    SUPPORTED_SPEC_LANGUAGES,
+    SUPPORTED_SPEC_PROFILES,
+    resolveHome,
+    configPath,
+    readConfig,
+    writeConfig,
+    normalizeLanguage,
+    normalizeProfile,
+    getDefaultSpecLanguage,
+    getDefaultSpecProfile,
+    runConfigCommand
+};

package/bin/entry.js

@@ -11,7 +11,7 @@ function isInitInvocation(args) {
     if (args.includes('--help') || args.includes('-h') || args.includes('--version') || args.includes('-v')) {
         return false;
     }
-    // Note: 'upgrade' and 'global' are handled and returned above before this
+    // Note: 'upgrade', 'global', 'config', and 'spec' are handled and returned above before this
     // is ever called, so they never reach here.
     const first = args[0];
     return !first || first === 'init' || first.startsWith('-');
@@ -74,6 +74,16 @@ if (command === 'global') {
     return;
 }
 
+if (command === 'config') {
+    require('./config').runConfigCommand(args.slice(1));
+    return;
+}
+
+if (command === 'spec') {
+    require('./spec').runSpecCommand(args.slice(1));
+    return;
+}
+
 const shouldUpgradeGeneratedPolicy = isInitInvocation(args);
 const beforeSnapshot = shouldUpgradeGeneratedPolicy ? snapshotPolicyFiles(process.cwd()) : null;
 const force = args.includes('--yes') || args.includes('-y');

package/bin/native-skills.js

@@ -0,0 +1,183 @@
+const fs = require('fs');
+const path = require('path');
+
+const NATIVE_SKILLS = [
+    'using-git-worktrees',
+    'subagent-driven-development',
+    'finishing-a-development-branch',
+    'system-discovery',
+    'system-reverse-engineer',
+    'system-spec-review'
+];
+
+const SYSTEM_SPEC_SKILLS = [
+    'system-discovery',
+    'system-reverse-engineer',
+    'system-spec-review'
+];
+
+const NATIVE_SUPPORT_FILES = [
+    path.join('requesting-code-review', 'code-reviewer.md')
+];
+
+const NATIVE_SKILL_SURFACES = [
+    { id: 'agents', relativeDir: path.join('.agents', 'skills') },
+    { id: 'claude', relativeDir: path.join('.claude', 'skills') }
+];
+
+const nativeSkillsSourceDir = path.resolve(__dirname, '..', 'skills');
+
+function sourcePath(relativePath) {
+    return path.join(nativeSkillsSourceDir, relativePath);
+}
+
+function skillSourceDir(name) {
+    return sourcePath(name);
+}
+
+function collectFiles(directory, relative = '') {
+    const files = [];
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+        const entryRelative = path.join(relative, entry.name);
+        const entryPath = path.join(directory, entry.name);
+        if (entry.isDirectory()) files.push(...collectFiles(entryPath, entryRelative));
+        else if (entry.isFile()) files.push(entryRelative);
+    }
+    return files;
+}
+
+function ownedFiles() {
+    return [
+        ...NATIVE_SKILLS.flatMap(name => collectFiles(skillSourceDir(name), name)),
+        ...NATIVE_SUPPORT_FILES
+    ];
+}
+
+function ownedSkillFiles(name) {
+    return collectFiles(skillSourceDir(name), name);
+}
+
+function targetPath(targetDir, surface, relativePath) {
+    return path.join(targetDir, surface.relativeDir, relativePath);
+}
+
+function checkNativeSkills(targetDir) {
+    const surfaces = {};
+    const skills = {};
+
+    for (const surface of NATIVE_SKILL_SURFACES) {
+        const missingFiles = ownedFiles().filter(relativePath => !fs.existsSync(targetPath(targetDir, surface, relativePath)));
+        const installed = [];
+        const missing = [];
+        for (const name of NATIVE_SKILLS) {
+            (ownedSkillFiles(name).every(relativePath => fs.existsSync(targetPath(targetDir, surface, relativePath)))
+                ? installed
+                : missing).push(name);
+        }
+        const supportInstalled = NATIVE_SUPPORT_FILES.filter(relativePath => !missingFiles.includes(relativePath));
+        const supportMissing = NATIVE_SUPPORT_FILES.filter(relativePath => missingFiles.includes(relativePath));
+        surfaces[surface.id] = {
+            installed,
+            missing,
+            total: NATIVE_SKILLS.length,
+            missingFiles,
+            support: {
+                installed: supportInstalled,
+                missing: supportMissing,
+                total: NATIVE_SUPPORT_FILES.length
+            }
+        };
+    }
+
+    for (const name of NATIVE_SKILLS) {
+        skills[name] = {};
+        for (const surface of NATIVE_SKILL_SURFACES) {
+            skills[name][surface.id] = ownedSkillFiles(name).every(relativePath => fs.existsSync(targetPath(targetDir, surface, relativePath)));
+        }
+    }
+
+    const installed = NATIVE_SKILLS.filter(name => NATIVE_SKILL_SURFACES.every(surface => skills[name][surface.id]));
+    const missing = NATIVE_SKILLS.filter(name => !installed.includes(name));
+    const missingFiles = Object.fromEntries(NATIVE_SKILL_SURFACES.map(surface => [surface.id, surfaces[surface.id].missingFiles]));
+    return {
+        installed,
+        missing,
+        total: NATIVE_SKILLS.length,
+        allInstalled: missingFiles.agents.length === 0 && missingFiles.claude.length === 0,
+        surfaces,
+        skills,
+        missingFiles
+    };
+}
+
+function copyFile(source, destination) {
+    fs.mkdirSync(path.dirname(destination), { recursive: true });
+    fs.copyFileSync(source, destination);
+}
+
+function installNativeSkills(targetDir, options = {}) {
+    const dryRun = options.dryRun === true;
+    const operations = [];
+    for (const surface of NATIVE_SKILL_SURFACES) {
+        for (const relativePath of ownedFiles()) {
+            const source = sourcePath(relativePath);
+            const destination = targetPath(targetDir, surface, relativePath);
+            operations.push({ surface: surface.id, relativePath, source, destination });
+            if (!dryRun) copyFile(source, destination);
+        }
+    }
+    return {
+        ok: true,
+        dryRun,
+        operations,
+        results: NATIVE_SKILLS.map(name => ({ name, ok: true, dryRun })),
+        message: dryRun
+            ? `Dry run: would copy ${NATIVE_SKILLS.length} native skills to .agents/skills and .claude/skills`
+            : `installed ${NATIVE_SKILLS.length} thachvd-kit native skills to .agents/skills and .claude/skills`
+    };
+}
+
+function installSystemSpecSkills(targetDir, options = {}) {
+    const dryRun = options.dryRun === true;
+    const operations = [];
+    for (const surface of NATIVE_SKILL_SURFACES) {
+        for (const name of SYSTEM_SPEC_SKILLS) {
+            for (const relativePath of ownedSkillFiles(name)) {
+                const source = sourcePath(relativePath);
+                const destination = targetPath(targetDir, surface, relativePath);
+                operations.push({ surface: surface.id, relativePath, source, destination });
+                if (!dryRun) copyFile(source, destination);
+            }
+        }
+    }
+    return {
+        ok: true,
+        dryRun,
+        operations,
+        message: dryRun
+            ? `Dry run: would copy ${SYSTEM_SPEC_SKILLS.length} system-spec skills to workspace agent surfaces`
+            : `installed ${SYSTEM_SPEC_SKILLS.length} system-spec skills to workspace agent surfaces`
+    };
+}
+
+function updateNativeSkills(targetDir, options = {}) {
+    const result = installNativeSkills(targetDir, options);
+    return {
+        ...result,
+        message: result.dryRun
+            ? `Dry run: would refresh ${NATIVE_SKILLS.length} native skills from bundled copies`
+            : `updated ${NATIVE_SKILLS.length} thachvd-kit native skills from bundled copies`
+    };
+}
+
+module.exports = {
+    NATIVE_SKILLS,
+    SYSTEM_SPEC_SKILLS,
+    NATIVE_SUPPORT_FILES,
+    NATIVE_SKILL_SURFACES,
+    nativeSkillsSourceDir,
+    checkNativeSkills,
+    installNativeSkills,
+    installSystemSpecSkills,
+    updateNativeSkills
+};

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