thufir 2.1.0

package/dist/scaffold.js

@@ -0,0 +1,352 @@
+import { readFileSync, writeFileSync, mkdirSync, existsSync, appendFileSync } from 'node:fs';
+import { join, dirname, basename } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { execSync } from 'node:child_process';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+function getTemplatesDir() {
+    const distTemplates = join(__dirname, 'templates');
+    if (existsSync(distTemplates))
+        return distTemplates;
+    return join(__dirname, '..', 'src', 'templates');
+}
+function readTemplate(relativePath) {
+    return readFileSync(join(getTemplatesDir(), relativePath), 'utf-8');
+}
+const TRAIT_FILES = {
+    'mentat-core': 'traits/mentat-core.md',
+    'consultant': 'traits/consultant.md',
+    'psychology': 'traits/psychology.md',
+    // Legacy trait IDs (map to new packages for backward compat)
+    'thufir': 'traits/mentat-core.md',
+    'first-principles': 'traits/mentat-core.md',
+    'mbb': 'traits/consultant.md',
+    'zelazny': 'traits/consultant.md',
+    'top-down': 'traits/consultant.md',
+    'compassion': 'traits/psychology.md',
+    'systemic': 'traits/psychology.md',
+    'parts': 'traits/psychology.md',
+};
+const SKILL_FILES = {
+    'superpowers': 'skills/superpowers.md',
+    'gstack': 'skills/gstack.md',
+};
+const TRIGGER_LINES = {
+    'brainstorming': { situation: 'Creative work starting — new feature, component, or behavior change', skill: 'Brainstorming', how: 'Use the brainstorming skill before writing any code' },
+    'plans': { situation: 'Multi-step task with a spec or requirements', skill: 'Implementation Plans', how: 'Create a detailed implementation plan before coding' },
+    'ceo-review': { situation: 'Reviewing product requirements or finding better solutions', skill: 'CEO/Product Review', how: '`/plan-ceo-review` — founder-mode review, finds the 10-star product' },
+    'eng-review': { situation: 'Locking architecture, mapping edge cases', skill: 'Engineering Review', how: '`/plan-eng-review` — architecture and technical planning' },
+    'tdd': { situation: 'Implementing a feature or bugfix', skill: 'Test-Driven Development', how: 'Write failing tests first, then implement' },
+    'code-review': { situation: 'Completing a task or receiving feedback', skill: 'Code Review', how: 'Review work against requirements; verify feedback before implementing' },
+    'verification': { situation: 'About to claim work is complete', skill: 'Verification', how: 'Run verification commands, confirm output before claiming success' },
+    'debugging': { situation: 'Bug, test failure, or unexpected behavior', skill: 'Systematic Debugging', how: "Follow the debugging skill's scientific method" },
+    'browse': { situation: 'Need to test a frontend feature or verify a deployment', skill: 'Browser Automation', how: '`/gstack` or `/browse` — opens persistent headless browser' },
+    'qa': { situation: 'Frontend feature complete, needs systematic testing', skill: 'QA Testing', how: '`/qa` — tests app, finds bugs, fixes them, re-verifies' },
+    'design-review': { situation: 'Design audit needed', skill: 'Design Audit', how: '`/plan-design-review` — 80-item design audit' },
+    'shipping': { situation: 'Ready to create a PR and ship', skill: 'Shipping', how: '`/ship` — runs tests, resolves comments, pushes, opens PR' },
+    'parallel': { situation: '2+ independent tasks that can run in parallel', skill: 'Parallel Agents', how: 'Use subagents for independent work streams' },
+    'retro': { situation: 'Want a development retrospective', skill: 'Retrospective', how: '`/retro` — analyzes commit history, work patterns, per-person metrics' },
+};
+function buildTraitsSection(selectedTraits) {
+    // Always include mentat-core
+    const allTraits = ['mentat-core', ...selectedTraits.filter(t => t !== 'mentat-core')];
+    // Deduplicate file paths (legacy IDs may map to same file)
+    const seen = new Set();
+    const traitContents = allTraits
+        .filter((t) => t in TRAIT_FILES)
+        .filter((t) => {
+        const file = TRAIT_FILES[t];
+        if (seen.has(file))
+            return false;
+        seen.add(file);
+        return true;
+    })
+        .map((t) => readTemplate(TRAIT_FILES[t]).trim())
+        .join('\n\n');
+    if (!traitContents)
+        return '';
+    return `---
+
+## Personality & Thinking
+
+These traits guide how your AI colleague thinks and communicates.
+
+${traitContents}
+
+`;
+}
+function buildSkillTriggersSection(selectedPackages, selectedTriggers) {
+    if (!selectedPackages || selectedPackages.length === 0)
+        return '';
+    if (!selectedTriggers || selectedTriggers.length === 0)
+        return '';
+    const hasSP = selectedPackages.includes('superpowers');
+    const hasGS = selectedPackages.includes('gstack');
+    // Categorize triggers
+    const planningTriggers = ['brainstorming', 'plans', 'ceo-review', 'eng-review'].filter(t => selectedTriggers.includes(t));
+    const qualityTriggers = ['tdd', 'code-review', 'verification', 'debugging'].filter(t => selectedTriggers.includes(t));
+    const browserTriggers = ['browse', 'qa', 'design-review'].filter(t => selectedTriggers.includes(t));
+    const workflowTriggers = ['shipping', 'parallel', 'retro'].filter(t => selectedTriggers.includes(t));
+    // Filter to only triggers relevant to selected packages
+    // superpowers: brainstorming, plans, tdd, code-review, verification, debugging, parallel
+    // gstack: ceo-review, eng-review, browse, qa, design-review, shipping, retro
+    // Some triggers are useful with either package
+    const spTriggers = new Set(['brainstorming', 'plans', 'tdd', 'code-review', 'verification', 'debugging', 'parallel']);
+    const gsTriggers = new Set(['ceo-review', 'eng-review', 'browse', 'qa', 'design-review', 'shipping', 'retro']);
+    const isRelevant = (t) => (hasSP && spTriggers.has(t)) || (hasGS && gsTriggers.has(t));
+    let content = '---\n\n## Skill Invocation Guide\n\nWhen these situations arise, invoke the relevant skill:\n\n';
+    const sections = [
+        { name: 'Planning & Strategy', triggers: planningTriggers.filter(isRelevant) },
+        { name: 'Code Quality', triggers: qualityTriggers.filter(isRelevant) },
+        { name: 'Browser & Testing', triggers: browserTriggers.filter(isRelevant) },
+        { name: 'Workflow', triggers: workflowTriggers.filter(isRelevant) },
+    ];
+    let hasContent = false;
+    for (const section of sections) {
+        if (section.triggers.length === 0)
+            continue;
+        hasContent = true;
+        content += `### ${section.name}\n\n`;
+        content += '| Situation | Skill to invoke | How |\n';
+        content += '|-----------|----------------|-----|\n';
+        for (const id of section.triggers) {
+            const t = TRIGGER_LINES[id];
+            if (t)
+                content += `| ${t.situation} | ${t.skill} | ${t.how} |\n`;
+        }
+        content += '\n';
+    }
+    if (!hasContent)
+        return '';
+    if (hasGS) {
+        content += '**Note:** gstack requires Bun. Run: `git clone https://github.com/garrytan/gstack.git ~/.claude/skills/gstack && cd ~/.claude/skills/gstack && ./setup`\n\n';
+    }
+    return content;
+}
+function substitute(content, answers) {
+    const date = new Date().toISOString().split('T')[0];
+    const traitsSection = buildTraitsSection(answers.traits);
+    const skillTriggersSection = buildSkillTriggersSection(answers.skillPackages, answers.skillTriggers);
+    return content
+        .replace(/\{\{colleague_name\}\}/g, answers.colleagueName)
+        .replace(/\{\{user_name\}\}/g, answers.userName)
+        .replace(/\{\{project_description\}\}/g, answers.projectDescription)
+        .replace(/\{\{project_type\}\}/g, answers.projectFocus)
+        .replace(/\{\{traits_section\}\}/g, traitsSection)
+        .replace(/\{\{skill_triggers_section\}\}/g, skillTriggersSection)
+        .replace(/\{\{created_date\}\}/g, date);
+}
+function writeFile(cwd, relativePath, content) {
+    const fullPath = join(cwd, relativePath);
+    mkdirSync(dirname(fullPath), { recursive: true });
+    writeFileSync(fullPath, content, 'utf-8');
+}
+/** Files that are always Thufir-managed and safe to overwrite */
+const THUFIR_MANAGED_FILES = ['AGENTS.md', 'CLAUDE.md', '.cursorrules'];
+/** Doc files that should be skipped during realign if they already exist (user content) */
+const USER_CONTENT_DOCS = [
+    'business/overview.md',
+    'business/audience.md',
+    'decisions/001-project-kickoff.md',
+];
+/** Doc files that are always regenerated (indexes, Thufir content) */
+const THUFIR_DOCS = [
+    '_meta.md',
+    'business/_meta.md',
+    'decisions/_meta.md',
+    'plans/_meta.md',
+    'workflows/_meta.md',
+    'workflows/getting-started.md',
+];
+export function scaffold(cwd, answers, analysis, isRealign = false) {
+    const files = [];
+    let gitInitialized = false;
+    if (!analysis.isGitRepo) {
+        execSync('git init', { cwd, stdio: 'ignore' });
+        gitInitialized = true;
+    }
+    // AGENTS.md
+    const agentsTemplate = readTemplate('agents/base.md');
+    writeFile(cwd, 'AGENTS.md', substitute(agentsTemplate, answers));
+    files.push('AGENTS.md');
+    // CLAUDE.md
+    writeFile(cwd, 'CLAUDE.md', readTemplate('claude-md.md'));
+    files.push('CLAUDE.md');
+    // .cursorrules
+    writeFile(cwd, '.cursorrules', readTemplate('cursorrules.md'));
+    files.push('.cursorrules');
+    // .gitignore
+    const gitignorePath = join(cwd, '.gitignore');
+    const gitignoreContent = readTemplate('gitignore.md');
+    if (existsSync(gitignorePath)) {
+        const existing = readFileSync(gitignorePath, 'utf-8');
+        if (!existing.includes('# Thufir defaults')) {
+            appendFileSync(gitignorePath, '\n# Thufir defaults\n' + gitignoreContent + '\n');
+        }
+        // Ensure .thufir.local is gitignored
+        if (!existing.includes('.thufir.local')) {
+            appendFileSync(gitignorePath, '\n# Thufir local config (tokens)\n.thufir.local\n');
+        }
+    }
+    else {
+        writeFile(cwd, '.gitignore', gitignoreContent + '\n\n# Thufir local config (tokens)\n.thufir.local\n');
+    }
+    files.push('.gitignore');
+    // docs/ structure
+    if (isRealign) {
+        // During realign: always regenerate indexes and Thufir content
+        for (const docFile of THUFIR_DOCS) {
+            const template = readTemplate('docs/' + docFile);
+            writeFile(cwd, 'docs/' + docFile, substitute(template, answers));
+            files.push('docs/' + docFile);
+        }
+        // Only create user content docs if they don't already exist
+        for (const docFile of USER_CONTENT_DOCS) {
+            if (!existsSync(join(cwd, 'docs', docFile))) {
+                const template = readTemplate('docs/' + docFile);
+                writeFile(cwd, 'docs/' + docFile, substitute(template, answers));
+                files.push('docs/' + docFile);
+            }
+        }
+    }
+    else {
+        // Fresh install: create everything
+        const allDocFiles = [...THUFIR_DOCS, ...USER_CONTENT_DOCS];
+        for (const docFile of allDocFiles) {
+            const template = readTemplate('docs/' + docFile);
+            writeFile(cwd, 'docs/' + docFile, substitute(template, answers));
+            files.push('docs/' + docFile);
+        }
+    }
+    // .thufir marker — full settings
+    const date = new Date().toISOString().split('T')[0];
+    const marker = JSON.stringify({
+        version: '1.3.0',
+        initialized: isRealign ? answers._originalInitialized || date : date,
+        last_realigned: date,
+        colleague_name: answers.colleagueName,
+        user_name: answers.userName,
+        project_mode: answers.projectMode,
+        project_focus: answers.projectFocus,
+        project_description: answers.projectDescription,
+        traits: answers.traits,
+        skillPackages: answers.skillPackages,
+        skillTriggers: answers.skillTriggers,
+    }, null, 2);
+    writeFile(cwd, '.thufir', marker);
+    files.push('.thufir');
+    // .thufir.local — token storage (not committed)
+    const localConfig = JSON.stringify({ token: answers.token }, null, 2);
+    writeFile(cwd, '.thufir.local', localConfig);
+    return { filesCreated: files, gitInitialized };
+}
+export function backupAgentFiles(cwd) {
+    const backupDir = join(cwd, '.thufir-backup');
+    mkdirSync(backupDir, { recursive: true });
+    const filesToBackup = ['AGENTS.md', 'CLAUDE.md', '.cursorrules', '.cursor/rules/onboarding.mdc', '.cursor/rules/documentation.mdc', '.cursor/rules/project-context.mdc'];
+    const backedUp = [];
+    for (const file of filesToBackup) {
+        const src = join(cwd, file);
+        if (existsSync(src)) {
+            const dest = join(backupDir, file.replace(/\//g, '__'));
+            const content = readFileSync(src, 'utf-8');
+            writeFileSync(dest, content, 'utf-8');
+            backedUp.push(file);
+        }
+    }
+    // Also backup any existing docs/_meta.md files
+    const docsDir = join(cwd, 'docs');
+    if (existsSync(docsDir)) {
+        try {
+            const metaContent = readFileSync(join(docsDir, '_meta.md'), 'utf-8');
+            writeFileSync(join(backupDir, 'docs___meta.md'), metaContent, 'utf-8');
+            backedUp.push('docs/_meta.md');
+        }
+        catch { }
+    }
+    return backedUp;
+}
+export function generateMergePrompt(cwd, answers, backedUpFiles) {
+    const backupDir = join(cwd, '.thufir-backup');
+    // Read all backup contents to include in the prompt
+    let backupSummary = '';
+    for (const file of backedUpFiles) {
+        const backupPath = join(backupDir, file.replace(/\//g, '__'));
+        if (existsSync(backupPath)) {
+            const content = readFileSync(backupPath, 'utf-8');
+            backupSummary += `\n### Original ${file}\n\`\`\`\n${content.slice(0, 3000)}\n\`\`\`\n`;
+        }
+    }
+    return `# Thufir Merge — Reorganization Plan
+
+You are helping merge Thufir conventions into this existing repository. Thufir has already:
+1. Backed up the original agent files to \`.thufir-backup/\`
+2. Written new Thufir-managed files (AGENTS.md, CLAUDE.md, .cursorrules)
+3. Created the docs/ structure with entity system
+
+## Your Task
+
+Review the backed-up original files and merge their intentions into the new Thufir structure. The original files contain valuable context that should NOT be lost.
+
+## Backed-Up Original Files
+${backupSummary}
+
+## What to Do
+
+1. **Read the new AGENTS.md** that Thufir just created. It has the standard structure.
+
+2. **Read each backed-up file** in \`.thufir-backup/\`. Extract:
+   - Custom instructions and rules the user had
+   - Project-specific context (tech stack, conventions, preferences)
+   - Any documented workflows or procedures
+   - References to specific files, APIs, or tools
+
+3. **Merge extracted content into the new structure:**
+   - Custom instructions → Add to AGENTS.md in the appropriate section (e.g., "When the Project Needs Code" for tech stack info)
+   - Workflows → Create files in \`docs/workflows/\`
+   - Project context → Update \`docs/business/overview.md\`
+   - Decision-like content → Create decision records in \`docs/decisions/\`
+
+4. **Preserve the Thufir structure.** The new AGENTS.md sections must stay intact. Add custom content WITHIN sections, don't restructure.
+
+5. **Minimal reorganization.** Keep things where they make sense. Don't move files unless they clearly belong elsewhere.
+
+## Key Principle
+
+The user's original agent files had intentions — they wrote those instructions for a reason. Every instruction should find a home in the new structure. Nothing should be lost.
+
+## Colleague Details
+- Name: ${answers.colleagueName}
+- User: ${answers.userName}
+- Project: ${answers.projectDescription}
+- Focus: ${answers.projectFocus}
+
+## When Done
+
+After merging, check:
+- [ ] All original custom instructions are preserved somewhere in the new structure
+- [ ] AGENTS.md is coherent and not duplicated
+- [ ] docs/ structure has _meta.md indexes updated
+- [ ] No files were deleted (only reorganized)
+
+Commit your changes with: \`git add -A && git commit -m "feat: merge Thufir conventions into existing repo"\`
+`;
+}
+export function createInitialCommit(cwd, files, colleagueName) {
+    for (const file of files) {
+        execSync('git add "' + file + '"', { cwd, stdio: 'ignore' });
+    }
+    execSync('git commit -m "feat: initialize ' + colleagueName + ' AI colleague"', { cwd, stdio: 'ignore' });
+}
+export function setupGitHub(cwd, mode, repoName) {
+    try {
+        if (mode === 'create') {
+            const name = repoName || basename(cwd);
+            execSync('gh repo create ' + name + ' --private --source=. --push', { cwd, stdio: 'inherit' });
+            return true;
+        }
+        return false;
+    }
+    catch {
+        return false;
+    }
+}