claudeforge-cli 1.0.0

package/src/commands/project.js

@@ -0,0 +1,123 @@
+'use strict';
+
+const path = require('path');
+const fs = require('fs-extra');
+const chalk = require('chalk');
+const { detect } = require('../stack-detector');
+const logger = require('../logger');
+
+async function project(description, options) {
+  const targetDir = path.resolve(options.dir || process.cwd());
+
+  if (!description || !description.trim()) {
+    logger.error('Please provide a project description.');
+    console.log(chalk.dim('  Example: claudeforge project "FastAPI REST API with PostgreSQL and Redis"'));
+    process.exit(1);
+  }
+
+  if (!await fs.pathExists(path.join(targetDir, '.claude'))) {
+    logger.error('No .claude/ directory found. Run `claudeforge init` first.');
+    process.exit(1);
+  }
+
+  // Detect tech stack from existing files
+  const { labels, context } = await detect(targetDir);
+
+  // Write SETUP_CONTEXT.md so the /setup-project slash command can read it
+  const contextContent = buildContextFile(description.trim(), labels, context, targetDir);
+  const contextPath = path.join(targetDir, 'SETUP_CONTEXT.md');
+  await fs.writeFile(contextPath, contextContent, 'utf8');
+
+  // Print onboarding guide
+  printGuide(description.trim(), labels, targetDir);
+}
+
+function buildContextFile(description, labels, context, targetDir) {
+  const lines = [
+    '# Project Setup Context',
+    '',
+    '> This file was generated by `claudeforge project`. It is read by the `/setup-project`',
+    '> slash command in Claude Code. Delete it once setup is complete.',
+    '',
+    '## Project Description',
+    '',
+    description,
+    '',
+  ];
+
+  if (labels.length > 0) {
+    lines.push('## Detected Tech Stack', '');
+    labels.forEach(l => lines.push(`- ${l}`));
+    lines.push('');
+  }
+
+  if (context) {
+    lines.push('## Key Project Files', '', '```', context, '```', '');
+  }
+
+  lines.push(
+    '## What `/setup-project` Should Do',
+    '',
+    'Fill in the following files with content tailored to the project description above:',
+    '',
+    '1. **`CLAUDE.md`** — project name, real commands for the stack, architecture, code style, env vars, gotchas',
+    '2. **`.claude/settings.json`** — add stack-appropriate permissions (test runner, build, linter)',
+    '3. **`.env.example`** — real environment variables for this stack with descriptions',
+    '4. **`.mcp.json`** — context7 plus any relevant MCP servers (database, browser, etc.)',
+    '5. **`memory/project_ai_workflow.md`** — AI conventions specific to this project',
+    '6. **New agents** in `.claude/agents/` — 2–4 specialized agents for this project type',
+    '7. **New commands** in `.claude/commands/` — 2–4 slash commands for the workflow',
+    '8. **`.gitignore`** — append tech-stack specific patterns',
+    '',
+    'Then delete this file (`SETUP_CONTEXT.md`) when done.',
+  );
+
+  return lines.join('\n') + '\n';
+}
+
+function printGuide(description, labels, targetDir) {
+  console.log('');
+  console.log(chalk.bold.cyan('  claudeforge') + chalk.dim('  —  Project Setup'));
+  console.log(chalk.dim('  ─────────────────────────────────────────'));
+  console.log('');
+  console.log(`  ${chalk.green('✓')} Written ${chalk.cyan('SETUP_CONTEXT.md')} with your project description`);
+
+  if (labels.length > 0) {
+    console.log(`  ${chalk.green('✓')} Detected stack: ${chalk.white(labels.join(', '))}`);
+  }
+
+  console.log('');
+  console.log(chalk.bold('  Next: open Claude Code and run the setup command'));
+  console.log('');
+  console.log(chalk.dim('  ┌─────────────────────────────────────────────────────────┐'));
+  console.log(chalk.dim('  │') + chalk.bold.white('  In the Claude Code chat window, type:                  ') + chalk.dim('│'));
+  console.log(chalk.dim('  │') + '                                                          ' + chalk.dim('│'));
+  console.log(chalk.dim('  │') + '  ' + chalk.cyan.bold('/setup-project') + chalk.white(` "${truncate(description, 38)}"`) + '    ' + chalk.dim('│'));
+  console.log(chalk.dim('  │') + '                                                          ' + chalk.dim('│'));
+  console.log(chalk.dim('  └─────────────────────────────────────────────────────────┘'));
+  console.log('');
+  console.log(chalk.dim('  Claude will read SETUP_CONTEXT.md and fill in:'));
+  console.log(chalk.dim('  • CLAUDE.md        — project commands, architecture, style'));
+  console.log(chalk.dim('  • settings.json    — stack-appropriate permissions'));
+  console.log(chalk.dim('  • .env.example     — real environment variables'));
+  console.log(chalk.dim('  • .mcp.json        — MCP servers for your stack'));
+  console.log(chalk.dim('  • agents/          — specialized sub-agents for your domain'));
+  console.log(chalk.dim('  • commands/        — slash commands for your workflow'));
+  console.log(chalk.dim('  • memory/          — project AI workflow conventions'));
+  console.log('');
+  console.log(chalk.dim('  Works with any Claude model — GitHub Copilot, Claude.ai, or'));
+  console.log(chalk.dim('  any IDE with Claude Code extension. No API key required.'));
+  console.log('');
+  console.log(chalk.dim('  ─────────────────────────────────────────'));
+  console.log(chalk.dim('  Other useful commands once in the IDE:'));
+  console.log(chalk.dim('  /project-health  — audit your setup and get improvement tips'));
+  console.log(chalk.dim('  /memory-sync     — update memory files after a work session'));
+  console.log(chalk.dim('  /standup         — generate a standup from recent commits'));
+  console.log('');
+}
+
+function truncate(str, max) {
+  return str.length > max ? str.slice(0, max - 1) + '…' : str;
+}
+
+module.exports = project;

package/src/commands/status.js

@@ -0,0 +1,183 @@
+'use strict';
+
+const path = require('path');
+const fs = require('fs-extra');
+const chalk = require('chalk');
+
+async function status(options) {
+  const targetDir = path.resolve(options.dir || process.cwd());
+
+  console.log('');
+  console.log(chalk.bold.cyan('  claudeforge') + chalk.dim('  —  Project Status'));
+  console.log(chalk.dim('  ─────────────────────────────────────────'));
+  console.log('');
+
+  // ── Core scaffold check ───────────────────────────────────────────────────
+  const coreFiles = [
+    { path: 'CLAUDE.md',                    label: 'CLAUDE.md (project context)' },
+    { path: 'CLAUDE.local.md',              label: 'CLAUDE.local.md (personal context)' },
+    { path: '.claude/settings.json',        label: '.claude/settings.json' },
+    { path: '.claude/settings.local.json',  label: '.claude/settings.local.json' },
+    { path: '.mcp.json',                    label: '.mcp.json (MCP servers)' },
+    { path: '.env.example',                 label: '.env.example' },
+    { path: '.gitignore',                   label: '.gitignore' },
+    { path: 'memory/MEMORY.md',             label: 'memory/MEMORY.md (index)' },
+  ];
+
+  console.log(chalk.bold('  Core Files'));
+  for (const f of coreFiles) {
+    const exists = await fs.pathExists(path.join(targetDir, f.path));
+    const icon = exists ? chalk.green('✓') : chalk.red('✗');
+    const label = exists ? chalk.dim(f.label) : chalk.red(f.label + ' — missing');
+    console.log(`  ${icon}  ${label}`);
+  }
+
+  // ── Settings summary ──────────────────────────────────────────────────────
+  const settingsPath = path.join(targetDir, '.claude/settings.json');
+  if (await fs.pathExists(settingsPath)) {
+    try {
+      const settings = await fs.readJson(settingsPath);
+      console.log('');
+      console.log(chalk.bold('  Settings'));
+      console.log(chalk.dim('  Model:   ') + chalk.white(settings.model || chalk.yellow('(not set, using global default)')));
+
+      const allowCount = (settings.permissions?.allow || []).length;
+      const denyCount = (settings.permissions?.deny || []).length;
+      console.log(chalk.dim('  Perms:   ') + chalk.white(`${allowCount} allowed, ${denyCount} denied`));
+
+      const hookCount = Object.values(settings.hooks || {}).reduce((n, arr) => n + arr.length, 0);
+      console.log(chalk.dim('  Hooks:   ') + chalk.white(`${hookCount} hook rule(s) configured`));
+    } catch (_) {
+      console.log(chalk.yellow('  ⚠  Could not parse .claude/settings.json'));
+    }
+  }
+
+  // ── MCP servers ───────────────────────────────────────────────────────────
+  const mcpPath = path.join(targetDir, '.mcp.json');
+  if (await fs.pathExists(mcpPath)) {
+    try {
+      const mcp = await fs.readJson(mcpPath);
+      const servers = Object.keys(mcp.mcpServers || {});
+      console.log('');
+      console.log(chalk.bold('  MCP Servers'));
+      if (servers.length === 0) {
+        console.log(chalk.dim('  (none configured)'));
+      } else {
+        servers.forEach(s => console.log(chalk.dim('  •') + ' ' + chalk.white(s)));
+      }
+    } catch (_) {}
+  }
+
+  // ── Agents ────────────────────────────────────────────────────────────────
+  const agentsDir = path.join(targetDir, '.claude/agents');
+  if (await fs.pathExists(agentsDir)) {
+    const agents = (await fs.readdir(agentsDir)).filter(f => f.endsWith('.md'));
+    console.log('');
+    console.log(chalk.bold('  Agents') + chalk.dim(` (${agents.length})`));
+    if (agents.length === 0) {
+      console.log(chalk.dim('  (none — run `claudeforge add agent <name>`)'));
+    } else {
+      for (const agent of agents) {
+        const name = agent.replace('.md', '');
+        const desc = await readFrontmatterField(path.join(agentsDir, agent), 'description');
+        console.log(chalk.dim('  •') + ' ' + chalk.cyan(name) + (desc ? chalk.dim(` — ${truncate(desc, 60)}`) : ''));
+      }
+    }
+  }
+
+  // ── Slash Commands ────────────────────────────────────────────────────────
+  const commandsDir = path.join(targetDir, '.claude/commands');
+  if (await fs.pathExists(commandsDir)) {
+    const commands = (await fs.readdir(commandsDir)).filter(f => f.endsWith('.md'));
+    console.log('');
+    console.log(chalk.bold('  Slash Commands') + chalk.dim(` (${commands.length})`));
+    if (commands.length === 0) {
+      console.log(chalk.dim('  (none — run `claudeforge add command <name>`)'));
+    } else {
+      for (const cmd of commands) {
+        const name = cmd.replace('.md', '');
+        const desc = await readFrontmatterField(path.join(commandsDir, cmd), 'description');
+        console.log(chalk.dim('  •') + ' /' + chalk.cyan(name) + (desc ? chalk.dim(` — ${truncate(desc, 55)}`) : ''));
+      }
+    }
+  }
+
+  // ── Skills ────────────────────────────────────────────────────────────────
+  const skillsDir = path.join(targetDir, '.claude/skills');
+  if (await fs.pathExists(skillsDir)) {
+    const skills = await fs.readdir(skillsDir);
+    const skillDirs = [];
+    for (const s of skills) {
+      const sp = path.join(skillsDir, s, 'SKILL.md');
+      if (await fs.pathExists(sp)) skillDirs.push(s);
+    }
+    console.log('');
+    console.log(chalk.bold('  Skills') + chalk.dim(` (${skillDirs.length})`));
+    if (skillDirs.length === 0) {
+      console.log(chalk.dim('  (none — run `claudeforge add skill <name>`)'));
+    } else {
+      for (const skill of skillDirs) {
+        const desc = await readFrontmatterField(path.join(skillsDir, skill, 'SKILL.md'), 'description');
+        console.log(chalk.dim('  •') + ' ' + chalk.cyan(skill) + (desc ? chalk.dim(` — ${truncate(desc, 55)}`) : ''));
+      }
+    }
+  }
+
+  // ── Memory files ──────────────────────────────────────────────────────────
+  const memoryDir = path.join(targetDir, 'memory');
+  if (await fs.pathExists(memoryDir)) {
+    const memFiles = (await fs.readdir(memoryDir)).filter(f => f.endsWith('.md'));
+    console.log('');
+    console.log(chalk.bold('  Memory') + chalk.dim(` (${memFiles.length} files)`));
+    for (const f of memFiles) {
+      const size = (await fs.stat(path.join(memoryDir, f))).size;
+      const filled = size > 200 ? chalk.green('●') : chalk.yellow('○');
+      console.log(`  ${filled}  ${chalk.dim(f)}${size <= 200 ? chalk.yellow(' — empty template') : ''}`);
+    }
+  }
+
+  console.log('');
+  console.log(chalk.dim('  ─────────────────────────────────────────'));
+
+  // Contextual hints based on what's missing
+  const missingCore = [];
+  for (const f of coreFiles) {
+    if (!await fs.pathExists(path.join(targetDir, f.path))) missingCore.push(f.path);
+  }
+
+  if (missingCore.length > 0) {
+    console.log(chalk.yellow(`  ⚠  ${missingCore.length} core file(s) missing. Run: `) + chalk.cyan('claudeforge init'));
+    console.log('');
+  } else {
+    console.log('');
+    console.log(chalk.bold('  Productivity tips:'));
+    console.log('');
+    console.log(`  ${chalk.dim('›')} ${chalk.cyan('/setup-project "description"')}   ${chalk.dim('AI-fills CLAUDE.md, agents, commands in the IDE chat')}`);
+    console.log(`  ${chalk.dim('›')} ${chalk.cyan('/scaffold-structure')}             ${chalk.dim('creates src/, tests/, and starter files in IDE chat')}`);
+    console.log(`  ${chalk.dim('›')} ${chalk.cyan('/project-health')}                 ${chalk.dim('audits your setup and suggests improvements in IDE chat')}`);
+    console.log(`  ${chalk.dim('›')} ${chalk.cyan('claudeforge upgrade')}              ${chalk.dim('update hook scripts and built-in commands to latest')}`);
+    console.log('');
+  }
+}
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+async function readFrontmatterField(filePath, field) {
+  try {
+    const content = await fs.readFile(filePath, 'utf8');
+    const match = content.match(/^---\n([\s\S]*?)\n---/);
+    if (!match) return null;
+    const fm = match[1];
+    const fieldMatch = fm.match(new RegExp(`^${field}:\\s*(.+)$`, 'm'));
+    return fieldMatch ? fieldMatch[1].trim() : null;
+  } catch (_) {
+    return null;
+  }
+}
+
+function truncate(str, maxLen) {
+  if (!str) return '';
+  return str.length > maxLen ? str.slice(0, maxLen - 1) + '…' : str;
+}
+
+module.exports = status;

package/src/commands/upgrade.js

@@ -0,0 +1,114 @@
+'use strict';
+
+const path = require('path');
+const chalk = require('chalk');
+const scaffolder = require('../scaffolder');
+const logger = require('../logger');
+const fs = require('fs-extra');
+
+/**
+ * Files that are infrastructure templates (always safe to upgrade).
+ * User-edited files like CLAUDE.md are excluded by default.
+ */
+const UPGRADEABLE = [
+  // Infrastructure — always safe to re-apply
+  { src: 'claude/settings.local.json.tpl',  dest: '.claude/settings.local.json' },
+  { src: 'claude/README.md.tpl',            dest: '.claude/README.md' },
+  { src: 'claude/hooks/pre-tool-use.sh.tpl',  dest: '.claude/hooks/pre-tool-use.sh' },
+  { src: 'claude/hooks/post-tool-use.sh.tpl', dest: '.claude/hooks/post-tool-use.sh' },
+  { src: 'claude/rules/no-sensitive-files.md.tpl', dest: '.claude/rules/no-sensitive-files.md' },
+  { src: 'claude/skills/project-conventions/SKILL.md.tpl', dest: '.claude/skills/project-conventions/SKILL.md' },
+  { src: 'memory/MEMORY.md.tpl',            dest: 'memory/MEMORY.md' },
+  // Built-in AI slash commands — safe to upgrade (project-specific ones in USER_OWNED)
+  { src: 'claude/commands/setup-project.md.tpl',    dest: '.claude/commands/setup-project.md' },
+  { src: 'claude/commands/memory-sync.md.tpl',      dest: '.claude/commands/memory-sync.md' },
+  { src: 'claude/commands/project-health.md.tpl',   dest: '.claude/commands/project-health.md' },
+  { src: 'claude/commands/standup.md.tpl',          dest: '.claude/commands/standup.md' },
+  { src: 'claude/commands/explain-codebase.md.tpl', dest: '.claude/commands/explain-codebase.md' },
+  { src: 'claude/commands/fix-issue.md.tpl',        dest: '.claude/commands/fix-issue.md' },
+  { src: 'claude/commands/scaffold-structure.md.tpl', dest: '.claude/commands/scaffold-structure.md' },
+];
+
+/**
+ * User-owned files — only upgraded with --all flag.
+ */
+const USER_OWNED = [
+  { src: 'CLAUDE.md.tpl',               dest: 'CLAUDE.md' },
+  { src: 'CLAUDE.local.md.tpl',         dest: 'CLAUDE.local.md' },
+  { src: '.env.example.tpl',            dest: '.env.example' },
+  { src: 'mcp.json.tpl',                dest: '.mcp.json' },
+  { src: '.gitignore.tpl',              dest: '.gitignore' },
+  { src: 'claude/settings.json.tpl',    dest: '.claude/settings.json' },
+  { src: 'claude/agents/code-reviewer.md.tpl', dest: '.claude/agents/code-reviewer.md' },
+  { src: 'claude/commands/commit.md.tpl',     dest: '.claude/commands/commit.md' },
+  { src: 'claude/commands/review-pr.md.tpl',  dest: '.claude/commands/review-pr.md' },
+  { src: 'memory/feedback_communication.md.tpl', dest: 'memory/feedback_communication.md' },
+  { src: 'memory/project_ai_workflow.md.tpl',   dest: 'memory/project_ai_workflow.md' },
+  { src: 'memory/user_profile.md.tpl',          dest: 'memory/user_profile.md' },
+];
+
+async function upgrade(options) {
+  const targetDir = path.resolve(options.dir || process.cwd());
+  const includeAll = options.all || false;
+  const dryRun = options.dryRun || false;
+
+  if (!await fs.pathExists(path.join(targetDir, '.claude'))) {
+    logger.error('No .claude/ directory found. Run `claudeforge init` first.');
+    process.exit(1);
+  }
+
+  console.log('');
+  console.log(chalk.bold.cyan('  claudeforge') + chalk.dim('  —  Upgrade Templates'));
+  console.log(chalk.dim('  ─────────────────────────────────────────'));
+  if (dryRun) console.log(chalk.bold.yellow('  [DRY RUN] No files will be written'));
+  if (includeAll) console.log(chalk.yellow('  [--all] Including user-owned files (CLAUDE.md, settings.json, etc.)'));
+  console.log('');
+
+  const templatesDir = path.join(__dirname, '../../templates');
+  const manifest = includeAll ? [...UPGRADEABLE, ...USER_OWNED] : UPGRADEABLE;
+
+  const stats = { updated: 0, skipped: 0 };
+
+  for (const entry of manifest) {
+    const srcAbs = path.join(templatesDir, entry.src);
+    const destAbs = path.join(targetDir, entry.dest);
+
+    const result = await scaffolder.writeFile(srcAbs, destAbs, { force: true, dryRun });
+
+    if (dryRun) {
+      console.log(`  ${chalk.cyan('~')}  ${chalk.dim(entry.dest)}  ${chalk.cyan('would update')}`);
+    } else {
+      console.log(`  ${chalk.yellow('↺')}  ${chalk.dim(entry.dest)}`);
+    }
+    stats.updated++;
+  }
+
+  // Re-chmod hooks
+  if (!dryRun) {
+    await scaffolder.chmod(path.join(targetDir, '.claude/hooks/pre-tool-use.sh'), 0o755);
+    await scaffolder.chmod(path.join(targetDir, '.claude/hooks/post-tool-use.sh'), 0o755);
+  }
+
+  console.log('');
+  console.log(chalk.dim('  ─────────────────────────────────────────'));
+
+  if (dryRun) {
+    console.log(chalk.cyan(`  Dry run: ${stats.updated} file(s) would be updated.`));
+    console.log('');
+  } else {
+    console.log(chalk.green(`  ✓ ${stats.updated} infrastructure file(s) updated to latest templates.`));
+    if (!includeAll) {
+      console.log('');
+      console.log(chalk.dim('  User-owned files (CLAUDE.md, settings.json, agents, commands) were NOT touched.'));
+      console.log(chalk.dim('  Use --all to force-update everything (will overwrite your edits).'));
+    }
+    console.log('');
+    console.log(chalk.bold('  What to do next:'));
+    console.log('');
+    console.log(`  ${chalk.dim('›')} ${chalk.cyan('/project-health')}     ${chalk.dim('audit your setup to see if anything else needs attention')}`);
+    console.log(`  ${chalk.dim('›')} ${chalk.cyan('claudeforge status')}      ${chalk.dim('verify the updated files look correct')}`);
+    console.log('');
+  }
+}
+
+module.exports = upgrade;

package/src/index.js

@@ -0,0 +1,6 @@
+'use strict';
+
+// Public API — useful if someone requires('claudeforge') programmatically
+const init = require('./commands/init');
+
+module.exports = { init };

package/src/logger.js

@@ -0,0 +1,90 @@
+'use strict';
+
+const chalk = require('chalk');
+
+const ICONS = { created: '✓', skipped: '○', overwritten: '↺', dir: '⌂' };
+const COLORS = {
+  created: chalk.green,
+  skipped: chalk.gray,
+  overwritten: chalk.yellow,
+  dir: chalk.blue,
+};
+
+function banner(dryRun) {
+  console.log('');
+  console.log(chalk.bold.cyan('  claudeforge') + chalk.dim('  —  Claude Code Project Scaffolder'));
+  console.log(chalk.dim('  ─────────────────────────────────────────'));
+  if (dryRun) console.log(chalk.bold.yellow('  [DRY RUN] No files will be written'));
+  console.log('');
+}
+
+function info(msg) {
+  console.log(chalk.dim('  →') + ' ' + chalk.white(msg));
+}
+
+function fileResult(result, relPath, dryRun) {
+  if (dryRun && result !== 'skipped') {
+    console.log(`  ${chalk.cyan('~')}  ${chalk.dim(relPath)}  ${chalk.cyan('would create')}`);
+    return;
+  }
+  const icon = COLORS[result](ICONS[result]);
+  console.log(`  ${icon}  ${chalk.dim(relPath)}  ${chalk.dim(result)}`);
+}
+
+function dirResult(relPath, dryRun) {
+  if (dryRun) {
+    console.log(`  ${chalk.cyan('~')}  ${chalk.dim(relPath + '/')}  ${chalk.cyan('dir')}`);
+    return;
+  }
+  console.log(`  ${COLORS.dir(ICONS.dir)}  ${chalk.dim(relPath + '/')}  ${chalk.blue('dir')}`);
+}
+
+function summary(stats, dryRun) {
+  console.log('');
+  console.log(chalk.dim('  ─────────────────────────────────────────'));
+
+  if (dryRun) {
+    console.log(chalk.cyan(`  Dry run complete.  ${stats.created} file(s) would be created,  ${stats.skipped} would be skipped.`));
+    console.log('');
+    return;
+  }
+
+  console.log(
+    chalk.green('  Done!') +
+    chalk.dim(`  ${stats.created} created,  ${stats.overwritten} overwritten,  ${stats.skipped} skipped.`)
+  );
+  console.log('');
+  _hints('What to do next:', [
+    { cmd: 'claudeforge project "describe your project"', note: 'prepares AI context for the IDE' },
+    { cmd: '/setup-project "describe your project"',          note: 'run in Claude Code chat — fills in everything' },
+    { cmd: '/scaffold-structure',                             note: 'run in Claude Code chat — creates src/, tests/, etc.' },
+    { cmd: 'claudeforge status',                          note: 'see everything configured so far' },
+  ]);
+}
+
+function error(msg) {
+  console.error(chalk.red('  ✗  Error: ') + msg);
+}
+
+// ── Shared hint box ───────────────────────────────────────────────────────────
+
+/**
+ * Print a contextual "What's next?" hint box.
+ * @param {string} title
+ * @param {Array<{cmd: string, note: string}>} hints
+ */
+function hints(title, hintList) {
+  _hints(title, hintList);
+}
+
+function _hints(title, hintList) {
+  console.log(chalk.bold(`  ${title}`));
+  console.log('');
+  for (const h of hintList) {
+    console.log(`  ${chalk.dim('›')} ${chalk.cyan(h.cmd)}`);
+    if (h.note) console.log(`    ${chalk.dim(h.note)}`);
+  }
+  console.log('');
+}
+
+module.exports = { banner, info, fileResult, dirResult, summary, error, hints };

package/src/scaffolder.js

@@ -0,0 +1,45 @@
+'use strict';
+
+const fs = require('fs-extra');
+
+/**
+ * Ensures a directory exists (no-op in dry-run).
+ */
+async function ensureDir(destAbs, dryRun) {
+  if (!dryRun) {
+    await fs.ensureDir(destAbs);
+  }
+}
+
+/**
+ * Writes a template file to its destination.
+ * Returns 'created' | 'skipped' | 'overwritten'
+ */
+async function writeFile(srcAbs, destAbs, { force, dryRun }) {
+  const exists = await fs.pathExists(destAbs);
+
+  if (exists && !force) {
+    return 'skipped';
+  }
+
+  if (!dryRun) {
+    const content = await fs.readFile(srcAbs, 'utf8');
+    await fs.ensureFile(destAbs);
+    await fs.writeFile(destAbs, content, 'utf8');
+  }
+
+  return exists ? 'overwritten' : 'created';
+}
+
+/**
+ * Makes a file executable (silently ignores errors, e.g. on Windows).
+ */
+async function chmod(filePath, mode) {
+  try {
+    await fs.chmod(filePath, mode);
+  } catch (_) {
+    // Non-fatal — Windows doesn't support Unix permissions
+  }
+}
+
+module.exports = { ensureDir, writeFile, chmod };

package/src/stack-detector.js

@@ -0,0 +1,62 @@
+'use strict';
+
+const path = require('path');
+const fs = require('fs-extra');
+
+/**
+ * Maps indicator files → tech stack labels and relevant metadata.
+ */
+const INDICATORS = [
+  { file: 'package.json',       label: 'Node.js',      readFile: true  },
+  { file: 'requirements.txt',   label: 'Python',        readFile: true  },
+  { file: 'pyproject.toml',     label: 'Python',        readFile: true  },
+  { file: 'go.mod',             label: 'Go',            readFile: true  },
+  { file: 'Cargo.toml',         label: 'Rust',          readFile: true  },
+  { file: 'pom.xml',            label: 'Java/Maven',    readFile: false },
+  { file: 'build.gradle',       label: 'Java/Gradle',   readFile: false },
+  { file: 'Gemfile',            label: 'Ruby',          readFile: false },
+  { file: 'composer.json',      label: 'PHP',           readFile: false },
+  { file: 'tsconfig.json',      label: 'TypeScript',    readFile: false },
+  { file: 'next.config.js',     label: 'Next.js',       readFile: false },
+  { file: 'next.config.ts',     label: 'Next.js',       readFile: false },
+  { file: 'vite.config.ts',     label: 'Vite',          readFile: false },
+  { file: 'vite.config.js',     label: 'Vite',          readFile: false },
+  { file: 'docker-compose.yml', label: 'Docker',        readFile: false },
+  { file: 'docker-compose.yaml','label': 'Docker',      readFile: false },
+  { file: 'Dockerfile',         label: 'Docker',        readFile: false },
+  { file: '.terraform',         label: 'Terraform',     readFile: false },
+];
+
+/**
+ * Detects the tech stack and returns labels + key file contents for context.
+ * @param {string} targetDir
+ * @returns {{ labels: string[], context: string }}
+ */
+async function detect(targetDir) {
+  const labels = new Set();
+  const contextParts = [];
+
+  for (const indicator of INDICATORS) {
+    const filePath = path.join(targetDir, indicator.file);
+    const exists = await fs.pathExists(filePath);
+    if (!exists) continue;
+
+    labels.add(indicator.label);
+
+    if (indicator.readFile) {
+      try {
+        const content = await fs.readFile(filePath, 'utf8');
+        // Truncate to avoid bloating the prompt
+        const trimmed = content.slice(0, 1500);
+        contextParts.push(`--- ${indicator.file} ---\n${trimmed}`);
+      } catch (_) {}
+    }
+  }
+
+  return {
+    labels: [...labels],
+    context: contextParts.join('\n\n'),
+  };
+}
+
+module.exports = { detect };

package/templates/.env.example.tpl

@@ -0,0 +1,21 @@
+# ──────────────────────────────────────────────────────────────────────────────
+# Environment Variables
+#
+# Copy this file to .env and fill in the values.
+# NEVER commit .env to git — it is listed in .gitignore.
+# ──────────────────────────────────────────────────────────────────────────────
+
+# ── Application ──────────────────────────────────────────────────────────────
+NODE_ENV=development
+PORT=3000
+LOG_LEVEL=info
+
+# ── Database ──────────────────────────────────────────────────────────────────
+# DATABASE_URL=postgresql://user:password@localhost:5432/dbname
+
+# ── External APIs ─────────────────────────────────────────────────────────────
+# API_KEY=your-key-here
+
+# ── Claude / Anthropic API (if your app calls the Claude API) ─────────────────
+# ANTHROPIC_API_KEY=sk-ant-...
+# ANTHROPIC_MODEL=claude-sonnet-4-6