the-frame-ai 0.1.0

package/bin/the-frame

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { run } from '../src/cli.js';
+
+run(process.argv.slice(2));

package/bin/the-frame-ai

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { run } from '../src/cli.js';
+
+run(process.argv.slice(2));

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "the-frame-ai",
+  "version": "0.1.0",
+  "description": "FRAME — Framework for AI-Assisted Solo Development",
+  "type": "module",
+  "bin": {
+    "the-frame-ai": "./bin/the-frame-ai"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "templates/"
+  ],
+  "keywords": [
+    "claude",
+    "ai",
+    "development",
+    "framework",
+    "solo",
+    "tdd"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  }
+}

package/src/cli.js

@@ -0,0 +1,84 @@
+import { VERSION, log } from './manifest.js';
+import { resolveTarget } from './manifest.js';
+import { init } from './init.js';
+import { update } from './update.js';
+import { doctor } from './doctor.js';
+
+const HELP = `
+FRAME — Framework for AI-Assisted Solo Development v${VERSION}
+
+Usage:
+  the-frame init [target-dir]     Install FRAME into a project
+  the-frame update [target-dir]   Update FRAME files in a project
+  the-frame doctor [target-dir]   Check FRAME installation health
+  the-frame version               Show CLI version
+  the-frame help                  Show this help message
+
+Options:
+  --lang <code>   Set response language (e.g. en, ru, zh). Overrides FRAME_LANG env var.
+  --dry-run       (update only) Show what would be updated without making changes.
+
+Examples:
+  npx the-frame init              Install in current directory
+  npx the-frame init ../my-app    Install in specific directory
+  npx the-frame init --lang ru    Install with Russian language preset
+  npx the-frame update            Update in current directory
+  npx the-frame update --dry-run  Preview update without applying
+  npx the-frame doctor            Check health in current directory
+`;
+
+function parseFlags(args) {
+  const flags = { lang: null, dryRun: false, yes: false };
+  const rest = [];
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--lang' && args[i + 1]) {
+      flags.lang = args[++i];
+    } else if (args[i] === '--dry-run') {
+      flags.dryRun = true;
+    } else if (args[i] === '--yes' || args[i] === '-y') {
+      flags.yes = true;
+    } else {
+      rest.push(args[i]);
+    }
+  }
+  return { flags, rest };
+}
+
+export async function run(args) {
+  const [command, ...rest] = args;
+
+  switch (command) {
+    case 'init': {
+      const { flags, rest: r } = parseFlags(rest);
+      const target = resolveTarget(r);
+      await init(target, flags);
+      break;
+    }
+    case 'update': {
+      const { flags, rest: r } = parseFlags(rest);
+      const target = resolveTarget(r);
+      await update(target, flags);
+      break;
+    }
+    case 'doctor': {
+      const target = resolveTarget(rest);
+      await doctor(target);
+      break;
+    }
+    case 'version':
+    case '--version':
+    case '-v':
+      log(`the-frame v${VERSION}`);
+      break;
+    case 'help':
+    case '--help':
+    case '-h':
+    case undefined:
+      log(HELP);
+      break;
+    default:
+      log(`Unknown command: ${command}`);
+      log(HELP);
+      process.exit(1);
+  }
+}

package/src/doctor.js

@@ -0,0 +1,164 @@
+import { join } from 'node:path';
+import { readFileSync, statSync, readdirSync } from 'node:fs';
+import { TEMPLATES_DIR, VERSION, log, logSuccess, logWarn, logError } from './manifest.js';
+import { fileExists } from './utils.js';
+
+const REQUIRED_DIRS = [
+  '.claude/commands',
+  '.claude/agents',
+  '.claude/hooks',
+  '.planning',
+  '.planning/memory',
+  '.frame',
+];
+
+const REQUIRED_FILES = [
+  'CLAUDE.md',
+  '.frame/config.json',
+  '.frame/.frame-version',
+  '.claude/settings.local.json',
+  '.planning/STATE.md',
+  '.planning/MAP.md',
+  '.planning/pause-state.json',
+];
+
+const HOOK_FILES = [
+  '.claude/hooks/safety-net.sh',
+  '.claude/hooks/git-safety.sh',
+  '.claude/hooks/quality-gate.sh',
+  '.claude/hooks/session-init.sh',
+];
+
+export async function doctor(target) {
+  log('\nFRAME Doctor — Checking installation health...\n');
+
+  let errors = 0;
+  let warnings = 0;
+
+  // Node version
+  log('Node.js:');
+  const [major] = process.versions.node.split('.').map(Number);
+  if (major >= 18) {
+    logSuccess(`  v${process.versions.node}`);
+  } else {
+    logError(`  v${process.versions.node} — requires >=18`);
+    errors++;
+  }
+
+  // Directories
+  log('\nDirectories:');
+  for (const dir of REQUIRED_DIRS) {
+    if (fileExists(join(target, dir))) {
+      logSuccess(`  ${dir}/`);
+    } else {
+      logError(`  ${dir}/ — MISSING`);
+      errors++;
+    }
+  }
+
+  // Files
+  log('\nFiles:');
+  for (const file of REQUIRED_FILES) {
+    if (fileExists(join(target, file))) {
+      logSuccess(`  ${file}`);
+    } else {
+      logError(`  ${file} — MISSING`);
+      errors++;
+    }
+  }
+
+  // config.json validation
+  const configPath = join(target, '.frame', 'config.json');
+  if (fileExists(configPath)) {
+    try {
+      const config = JSON.parse(readFileSync(configPath, 'utf-8'));
+      if (config.language) {
+        logSuccess(`  .frame/config.json — valid (language: ${config.language})`);
+      } else {
+        logWarn('  .frame/config.json — missing "language" field');
+        warnings++;
+      }
+    } catch {
+      logError('  .frame/config.json — invalid JSON');
+      errors++;
+    }
+  }
+
+  // Hooks executability
+  log('\nHooks:');
+  for (const hook of HOOK_FILES) {
+    const fullPath = join(target, hook);
+    if (!fileExists(fullPath)) {
+      logError(`  ${hook} — MISSING`);
+      errors++;
+      continue;
+    }
+    try {
+      const isExec = (statSync(fullPath).mode & 0o111) !== 0;
+      if (isExec) {
+        logSuccess(`  ${hook} — executable`);
+      } else {
+        logWarn(`  ${hook} — not executable`);
+        warnings++;
+      }
+    } catch {
+      logWarn(`  ${hook} — cannot check permissions`);
+      warnings++;
+    }
+  }
+
+  // Version
+  log('\nVersion:');
+  const installedVersion = fileExists(join(target, '.frame', '.frame-version'))
+    ? readFileSync(join(target, '.frame', '.frame-version'), 'utf-8').trim()
+    : 'unknown';
+
+  if (installedVersion === VERSION) {
+    logSuccess(`  Installed: ${installedVersion} (latest)`);
+  } else {
+    logWarn(`  Installed: ${installedVersion}, CLI: ${VERSION} — run \`the-frame update\``);
+    warnings++;
+  }
+
+  // Counts
+  log('\nComponents:');
+  const commandsDir = join(target, '.claude', 'commands');
+  if (fileExists(commandsDir)) {
+    const count = readdirSync(commandsDir).filter((f) => f.endsWith('.md')).length;
+    const templateCommandsDir = join(TEMPLATES_DIR, 'commands');
+    const expectedCount = fileExists(templateCommandsDir)
+      ? readdirSync(templateCommandsDir).filter((f) => f.endsWith('.md')).length
+      : count;
+    if (count >= expectedCount) {
+      logSuccess(`  Commands: ${count}/${expectedCount}`);
+    } else {
+      logWarn(`  Commands: ${count}/${expectedCount}`);
+      warnings++;
+    }
+  }
+
+  const agentsDir = join(target, '.claude', 'agents');
+  if (fileExists(agentsDir)) {
+    const count = readdirSync(agentsDir).filter((f) => f.endsWith('.md')).length;
+    const templateAgentsDir = join(TEMPLATES_DIR, 'agents');
+    const expectedAgents = fileExists(templateAgentsDir)
+      ? readdirSync(templateAgentsDir).filter((f) => f.endsWith('.md')).length
+      : count;
+    if (count >= expectedAgents) {
+      logSuccess(`  Agents: ${count}/${expectedAgents}`);
+    } else {
+      logWarn(`  Agents: ${count}/${expectedAgents}`);
+      warnings++;
+    }
+  }
+
+  // Summary
+  log('\n' + '─'.repeat(50));
+  if (errors === 0 && warnings === 0) {
+    logSuccess('All checks passed! FRAME is healthy.');
+  } else {
+    if (errors > 0) logError(`${errors} error(s) found`);
+    if (warnings > 0) logWarn(`${warnings} warning(s) found`);
+  }
+  log('');
+}

package/src/init.js

@@ -0,0 +1,178 @@
+import { join, basename } from 'node:path';
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { TEMPLATES_DIR, VERSION, log, logSuccess, logWarn, logError, detectProjectName } from './manifest.js';
+import {
+  ensureDir,
+  copyDir,
+  makeExecutable,
+  fileExists,
+  listFilesRecursive,
+  writeFile,
+  applyVars,
+} from './utils.js';
+import { LANGUAGES, getLanguageInstruction, promptLanguage, promptConfig } from './languages.js';
+import { doctor } from './doctor.js';
+
+const PLANNING_DIRS = [
+  '.planning/memory',
+  '.planning/pause-history',
+  '.planning/reports/daily',
+  '.planning/reports/deps',
+  '.planning/reports/quality',
+  '.planning/reports/sprint',
+  '.planning/reports/cleanup',
+  '.planning/reviews',
+  '.planning/specs/archive',
+  '.planning/forensics',
+];
+
+const CLAUDE_DIRS = [
+  '.claude/commands',
+  '.claude/agents',
+  '.claude/hooks',
+  '.claude/skills',
+];
+
+// Files in templates/project/ that should be mapped to root-level destinations
+const ROOT_FILE_MAP = {
+  'CLAUDE.md': 'CLAUDE.md',
+  'settings.local.json': '.claude/settings.local.json',
+  'config.json': '.frame/config.json',
+  'STATE.md': '.planning/STATE.md',
+  'MAP.md': '.planning/MAP.md',
+};
+
+const SKIP_PROJECT_FILES = new Set(['CONTEXT.md']);
+
+
+export async function init(target, flags = {}) {
+  if (fileExists(join(target, '.frame', 'config.json'))) {
+    logWarn('FRAME already installed in this project.');
+    log('Use `the-frame update` to update framework files.');
+    return;
+  }
+
+  const projectName = detectProjectName(target);
+  log(`\nFRAME v${VERSION} — Initializing in ${basename(target)}...\n`);
+
+  const language = await promptLanguage(flags.lang, flags.yes);
+  const langLabel = LANGUAGES.find((l) => l.code === language)?.name || language;
+  logSuccess(`Language: ${langLabel}\n`);
+
+  // 1. Create directories
+  log('Creating directories...');
+  for (const dir of [...CLAUDE_DIRS, ...PLANNING_DIRS]) {
+    ensureDir(join(target, dir));
+  }
+
+  const defaultConfig = JSON.parse(readFileSync(join(TEMPLATES_DIR, 'project', 'config.json'), 'utf-8'));
+  const resolvedConfig = await promptConfig(defaultConfig, flags.yes);
+  const qualityVars = Object.fromEntries(
+    Object.entries(resolvedConfig.quality.commands).map(([k, v]) => [`quality.commands.${k}`, v])
+  );
+  const vars = { PROJECT_NAME: projectName, LANGUAGE: language };
+
+  // 2. Copy commands and apply quality.commands substitution
+  const commandsSrc = join(TEMPLATES_DIR, 'commands');
+  const commandsDest = join(target, '.claude', 'commands');
+  copyDir(commandsSrc, commandsDest);
+  for (const f of readdirSync(commandsDest).filter((f) => f.endsWith('.md'))) {
+    const p = join(commandsDest, f);
+    const replaced = applyVars(readFileSync(p, 'utf-8'), vars, qualityVars);
+    writeFile(p, replaced);
+  }
+  const commandCount = readdirSync(commandsSrc).filter((f) => f.endsWith('.md')).length;
+  logSuccess(`${commandCount} commands → .claude/commands/`);
+
+  // 3. Copy agents and apply quality.commands substitution
+  const agentsSrc = join(TEMPLATES_DIR, 'agents');
+  const agentsDest = join(target, '.claude', 'agents');
+  copyDir(agentsSrc, agentsDest);
+  for (const f of readdirSync(agentsDest).filter((f) => f.endsWith('.md'))) {
+    const p = join(agentsDest, f);
+    const replaced = applyVars(readFileSync(p, 'utf-8'), vars, qualityVars);
+    writeFile(p, replaced);
+  }
+  const agentCount = readdirSync(agentsSrc).filter((f) => f.endsWith('.md')).length;
+  logSuccess(`${agentCount} agents → .claude/agents/`);
+
+  // 4. Copy hooks
+  const hooksSrc = join(TEMPLATES_DIR, 'hooks');
+  const hooksDest = join(target, '.claude', 'hooks');
+  copyDir(hooksSrc, hooksDest);
+  const hookFiles = readdirSync(hooksSrc);
+  for (const hook of hookFiles) {
+    makeExecutable(join(hooksDest, hook));
+  }
+  logSuccess(`${hookFiles.length} hooks → .claude/hooks/`);
+
+  // 5. Copy planning templates
+  const pauseStateSrc = join(TEMPLATES_DIR, 'planning', 'pause-state.json');
+  if (fileExists(pauseStateSrc)) {
+    writeFile(join(target, '.planning', 'pause-state.json'), readFileSync(pauseStateSrc, 'utf-8'));
+  }
+
+  // 6. Generate project-specific files
+  const projectSrc = join(TEMPLATES_DIR, 'project');
+  const projectFiles = listFilesRecursive(projectSrc);
+
+  let fileCount = 0;
+  for (const srcPath of projectFiles) {
+    const relPath = srcPath.replace(projectSrc + '/', '');
+
+    if (SKIP_PROJECT_FILES.has(relPath)) continue;
+
+    // Determine destination
+    let destPath;
+    if (ROOT_FILE_MAP[relPath]) {
+      destPath = join(target, ROOT_FILE_MAP[relPath]);
+    } else {
+      destPath = join(target, relPath);
+    }
+
+    ensureDir(join(destPath, '..'));
+    const content = readFileSync(srcPath, 'utf-8');
+    const replaced = applyVars(content, vars, qualityVars);
+    writeFile(destPath, replaced);
+    fileCount++;
+  }
+
+  // 7. Write version tracking
+  writeFile(join(target, '.frame', '.frame-version'), VERSION);
+  logSuccess(`${fileCount} project files generated`);
+  logSuccess(`Version ${VERSION} recorded`);
+  logSuccess(`Language: ${langLabel}`);
+
+  // 8. Save resolved config (with user's stack choices + language)
+  const configPath = join(target, '.frame', 'config.json');
+  if (fileExists(configPath)) {
+    resolvedConfig.language = language;
+    writeFile(configPath, JSON.stringify(resolvedConfig, null, 2));
+  }
+
+  // 9. Inject language instruction into CLAUDE.md
+  const claudeMdPath = join(target, 'CLAUDE.md');
+  if (fileExists(claudeMdPath)) {
+    const content = readFileSync(claudeMdPath, 'utf-8');
+    writeFile(claudeMdPath, content + getLanguageInstruction(language));
+  }
+
+  // 10. Success
+  log('\n' + '═'.repeat(60));
+  log('  FRAME initialized successfully!');
+  log('═'.repeat(60));
+  log('');
+  log(`  Commands:  ${commandCount} in .claude/commands/`);
+  log(`  Agents:    ${agentCount} in .claude/agents/`);
+  log(`  Hooks:     ${hookFiles.length} in .claude/hooks/`);
+  log(`  Planning:  files in .planning/`);
+  log(`  Config:    .frame/config.json`);
+  log('');
+
+  // 11. Auto-run doctor
+  log('\n--- Проверка установки ---');
+  await doctor(target);
+
+  log('  Next step: open Claude Code and run `/frame:daily`');
+  log('');
+}

package/src/languages.js

@@ -0,0 +1,141 @@
+import { createInterface } from 'node:readline';
+
+function ask(rl, question) {
+  return new Promise((resolve) => rl.question(question, resolve));
+}
+
+export const LANGUAGES = [
+  { code: 'auto', name: 'Auto-detect', label: 'Auto-detect (mirror user language)' },
+  { code: 'en', name: 'English', label: 'English' },
+  { code: 'es', name: 'Español', label: 'Español (Spanish)' },
+  { code: 'de', name: 'Deutsch', label: 'Deutsch (German)' },
+  { code: 'ru', name: 'Russian', label: 'Русский (Russian)' },
+  { code: 'zh', name: 'Chinese', label: '中文 (Chinese)' },
+  { code: 'pt', name: 'Portuguese', label: 'Português (Portuguese)' },
+];
+
+const LANGUAGE_NAMES = {
+  en: 'English',
+  es: 'Spanish',
+  de: 'German',
+  ru: 'Russian',
+  zh: 'Chinese',
+  pt: 'Portuguese',
+};
+
+export function getLanguageInstruction(language) {
+  if (language === 'auto') {
+    return `
+## Response Language
+
+Respond in the same language the user writes in. Mirror their language automatically.
+Always match the language of the current user message.
+`;
+  }
+
+  const langName = LANGUAGE_NAMES[language] || language;
+  return `
+## Response Language
+
+Always respond in ${langName}. Write all specs, plans, reports, comments, and generated files in ${langName}.
+`;
+}
+
+export async function promptLanguage(langOverride, yes = false) {
+  if (langOverride) return langOverride;
+  if (process.env.FRAME_LANG) return process.env.FRAME_LANG;
+  if (!process.stdin.isTTY || yes) return 'auto';
+
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+
+  const prompt = '\n? Select response language:\n\n';
+  const options = LANGUAGES.map((l, i) => `  ${i + 1}) ${l.label}`).join('\n');
+  const footer = `\n  Enter number [1-${LANGUAGES.length}] (or press Enter for auto): `;
+
+  return new Promise((resolve) => {
+    rl.on('close', () => resolve('auto'));
+
+    rl.question(prompt + options + footer, (answer) => {
+      const choice = answer.trim();
+      if (choice === '' || choice === '1') {
+        rl.close();
+        return resolve('auto');
+      }
+
+      const idx = parseInt(choice, 10) - 1;
+      if (idx >= 0 && idx < LANGUAGES.length) {
+        rl.close();
+        return resolve(LANGUAGES[idx].code);
+      }
+
+      rl.question('  Enter custom language code (e.g., "ja", "ko", "fr"): ', (code) => {
+        rl.close();
+        resolve(code.trim().toLowerCase() || 'auto');
+      });
+    });
+  });
+}
+
+const STACK_PRESETS = {
+  typescript: { typecheck: 'npx tsc --noEmit', test: 'npx vitest run', lint: 'npx eslint .', build: 'npm run build' },
+  javascript: { typecheck: '', test: 'npx vitest run', lint: 'npx eslint .', build: 'npm run build' },
+  python: { typecheck: 'mypy .', test: 'pytest', lint: 'ruff check .', build: '' },
+  go: { typecheck: 'go vet ./...', test: 'go test ./...', lint: 'golangci-lint run', build: 'go build ./...' },
+  rust: { typecheck: 'cargo check', test: 'cargo test', lint: 'cargo clippy', build: 'cargo build' },
+};
+
+const MODEL_DESCRIPTIONS = {
+  opus: 'opus   — best quality, slower (recommended for architecture/security)',
+  sonnet: 'sonnet — faster, good for most tasks',
+};
+
+export async function promptConfig(defaultConfig, yes = false) {
+  if (!process.stdin.isTTY || yes) return defaultConfig;
+
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  const config = JSON.parse(JSON.stringify(defaultConfig));
+
+  console.log('\n? Project stack:\n');
+  const stacks = Object.keys(STACK_PRESETS);
+  stacks.forEach((s, i) => console.log(`  ${i + 1}) ${s}`));
+  console.log(`  ${stacks.length + 1}) custom`);
+
+  const stackAnswer = (await ask(rl, `\n  Enter number [1-${stacks.length + 1}] (or press Enter for typescript): `)).trim();
+  const stackIdx = parseInt(stackAnswer, 10) - 1;
+
+  if (stackIdx >= 0 && stackIdx < stacks.length) {
+    const preset = STACK_PRESETS[stacks[stackIdx]];
+    Object.assign(config.quality.commands, preset);
+    console.log(`\x1b[32m✓\x1b[0m Stack: ${stacks[stackIdx]}`);
+    console.log('');
+    console.log('  Quality commands that will be used:');
+    for (const [k, v] of Object.entries(config.quality.commands)) {
+      if (v) console.log(`    ${k}: ${v}`);
+    }
+    const confirm = (await ask(rl, '\n  Looks good? [Y/n]: ')).trim().toLowerCase();
+    if (confirm === 'n') {
+      for (const key of ['typecheck', 'test', 'lint', 'build']) {
+        const current = config.quality.commands[key];
+        const val = (await ask(rl, `  ${key} command [${current}]: `)).trim();
+        if (val) config.quality.commands[key] = val;
+      }
+    }
+  } else if (stackIdx === stacks.length) {
+    for (const key of ['typecheck', 'test', 'lint', 'build']) {
+      const current = config.quality.commands[key];
+      const val = (await ask(rl, `  ${key} command [${current}]: `)).trim();
+      if (val) config.quality.commands[key] = val;
+    }
+  }
+
+  console.log('\n? Preferred model for agents:\n');
+  Object.values(MODEL_DESCRIPTIONS).forEach((d, i) => console.log(`  ${i + 1}) ${d}`));
+  const modelAnswer = (await ask(rl, '\n  Enter number [1-2] (or press Enter for opus): ')).trim().toLowerCase();
+  if (modelAnswer === '2' || modelAnswer === 'sonnet') {
+    // Note: model preference is stored for future use when agent routing is implemented
+    console.log('\x1b[32m✓\x1b[0m Model preference: sonnet');
+  }
+
+  rl.close();
+  return config;
+}

package/src/manifest.js

@@ -0,0 +1,55 @@
+import { readFileSync, existsSync } from 'node:fs';
+import { join, dirname, basename } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT = join(__dirname, '..');
+
+export const VERSION = JSON.parse(
+  readFileSync(join(ROOT, 'package.json'), 'utf-8')
+).version;
+
+export const TEMPLATES_DIR = join(ROOT, 'templates');
+
+export function resolveTarget(args) {
+  const target = args[0] || process.cwd();
+  let dir = target;
+  while (true) {
+    if (existsSync(join(dir, '.git'))) return target;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  console.error(`Error: ${target} is not inside a git repository.`);
+  console.error('FRAME requires git history for checkpoints and rollbacks.');
+  console.error('Run: git init && git commit --allow-empty -m "init"');
+  console.error('(The empty commit is needed so FRAME has a base point for checkpoints.)');
+  process.exit(1);
+}
+
+export function detectProjectName(target) {
+  const pkgPath = join(target, 'package.json');
+  if (existsSync(pkgPath)) {
+    try {
+      const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+      if (pkg.name) return pkg.name;
+    } catch {}
+  }
+  return basename(target);
+}
+
+export function log(msg) {
+  console.log(msg);
+}
+
+export function logSuccess(msg) {
+  console.log(`\x1b[32m✓\x1b[0m ${msg}`);
+}
+
+export function logWarn(msg) {
+  console.log(`\x1b[33m⚠\x1b[0m ${msg}`);
+}
+
+export function logError(msg) {
+  console.error(`\x1b[31m✗\x1b[0m ${msg}`);
+}