nova-spec 1.0.2 → 1.0.4

package/lib/installer.js

@@ -3,17 +3,23 @@
 const fs = require('fs');
 const path = require('path');
 const { select, input, confirm } = require('@inquirer/prompts');
-const { generateManifest } = require('./sync.js');
+const {
+  generateManifest,
+  buildHookCommand,
+  HOOK_MARKER,
+} = require('./sync.js');
+const { detectForge } = require('./forge.js');
+const { listTransitionsAsync } = require('./jira.js');
 
 const PACKAGE_ROOT = path.join(__dirname, '..');
 const NOVASPEC_SRC = path.join(PACKAGE_ROOT, 'novaspec');
 const AGENTS_SRC = path.join(PACKAGE_ROOT, 'AGENTS.md');
 const CLAUDE_MD_SRC = path.join(PACKAGE_ROOT, 'CLAUDE.md');
+const MANIFEST_FILE = '.nova-manifest.json';
 
 async function init() {
   console.log('\n  nova-spec installer\n  ───────────────────\n');
 
-  // 1. Scope: global or project
   const scope = await select({
     message: 'Where do you want to install nova-spec?',
     choices: [
@@ -23,9 +29,13 @@ async function init() {
     ],
   });
 
-  const destDir = scope === 'global'
-    ? path.join(process.env.HOME || process.env.USERPROFILE, '.claude')
-    : process.cwd();
+  const home = process.env.HOME || process.env.USERPROFILE;
+  if (scope === 'global' && !home) {
+    console.error('  ✗ HOME / USERPROFILE not set; cannot resolve global install path.');
+    process.exit(1);
+  }
+
+  const destDir = scope === 'global' ? path.join(home, '.claude') : process.cwd();
 
   if (scope === 'update') {
     const { sync } = require('./sync.js');
@@ -33,7 +43,6 @@ async function init() {
     return;
   }
 
-  // 2. Runtime
   const runtime = await select({
     message: 'Which AI runtime do you use?',
     choices: [
@@ -43,36 +52,41 @@ async function init() {
     ],
   });
 
-  // 3. Jira
-  const useJira = await confirm({ message: 'Do you use Jira?', default: true });
+  if (scope === 'global' && runtime !== 'claude') {
+    console.warn('\n  ⚠ Global install currently only supports Claude Code.');
+    console.warn('     For OpenCode, use a project install.\n');
+  }
 
-  let jiraConfig = { skill: '', url: '', project: '', email: '', token: '${JIRA_API_TOKEN}', done_transition_id: '41' };
+  const ticketSystem = await select({
+    message: 'Ticket system:',
+    choices: [
+      { name: 'Jira', value: 'jira' },
+      { name: 'None  (paste tickets manually)', value: 'none' },
+    ],
+  });
 
-  if (useJira) {
-    jiraConfig.skill = 'jira-integration';
-    jiraConfig.url = await input({
-      message: 'Jira URL:',
-      default: 'https://your-workspace.atlassian.net',
-    });
-    jiraConfig.project = await input({ message: 'Jira project key:', default: 'PROJ' });
-    jiraConfig.email = await input({ message: 'Your Jira email:' });
-    jiraConfig.done_transition_id = await input({
-      message: 'Jira "Done" transition ID (find it via GET /rest/api/3/issue/<TICKET>/transitions):',
-      default: '41',
-    });
-    console.log('\n  Tip: set JIRA_API_TOKEN in your environment.');
-    console.log('  Get your token at: https://id.atlassian.com/manage-profile/security/api-tokens\n');
-  }
+  const jiraConfig = await collectJiraConfig(ticketSystem === 'jira');
 
-  // 4. Branch config
   const baseBranch = await input({ message: 'Base branch:', default: 'main' });
 
-  // 5. Confirm
+  const detectedForge = scope === 'project' ? detectForge(destDir) : null;
+  const forgeType = await select({
+    message: detectedForge ? `Forge (detected: ${detectedForge}):` : 'Forge:',
+    choices: [
+      { name: 'Auto-detect from git remote', value: 'auto' },
+      { name: 'GitHub  (gh)', value: 'github' },
+      { name: 'GitLab  (glab)', value: 'gitlab' },
+      { name: 'None / manual', value: 'none' },
+    ],
+    default: detectedForge || 'auto',
+  });
+
   console.log('\n  Summary:');
-  console.log(`  → Scope:   ${scope === 'global' ? 'Global (~/.claude)' : 'Project (' + destDir + ')'}`);
-  console.log(`  → Runtime: ${runtime}`);
-  console.log(`  → Jira:    ${useJira ? jiraConfig.url + ' / ' + jiraConfig.project : 'disabled'}`);
-  console.log(`  → Branch:  ${baseBranch}\n`);
+  console.log(`  → Scope:    ${scope === 'global' ? 'Global (' + destDir + ')' : 'Project (' + destDir + ')'}`);
+  console.log(`  → Runtime:  ${runtime}`);
+  console.log(`  → Tickets:  ${ticketSystem === 'jira' ? jiraConfig.url + ' / ' + jiraConfig.project : 'manual'}`);
+  console.log(`  → Forge:    ${forgeType}`);
+  console.log(`  → Branch:   ${baseBranch}\n`);
 
   const ok = await confirm({ message: 'Install with these settings?', default: true });
   if (!ok) {
@@ -80,125 +94,306 @@ async function init() {
     return;
   }
 
-  // 6. Install
   installFiles(destDir, runtime, scope);
-  writeConfig(destDir, { jiraConfig, baseBranch });
-  generateManifest(path.join(destDir, 'novaspec'));
+  writeConfig(destDir, { ticketSystem, jiraConfig, baseBranch, forgeType });
+
+  // Manifest reflects what we just shipped from the package.
+  const manifest = generateManifest(PACKAGE_ROOT);
+  fs.writeFileSync(
+    path.join(destDir, 'novaspec', MANIFEST_FILE),
+    JSON.stringify(manifest, null, 2) + '\n',
+  );
 
   console.log('\n  ✓ nova-spec installed!\n');
   console.log('  Next step: open Claude Code or OpenCode in this directory and run:');
   console.log('    /nova-start TICKET-123\n');
 }
 
+async function collectJiraConfig(useJira) {
+  const config = {
+    skill: '',
+    url: '',
+    project: '',
+    email: '',
+    token: '${JIRA_API_TOKEN}',
+    done_transition_id: '41',
+  };
+
+  if (!useJira) return config;
+
+  config.skill = 'jira-integration';
+  config.url = await input({
+    message: 'Jira URL:',
+    default: 'https://your-workspace.atlassian.net',
+  });
+  config.project = await input({ message: 'Jira project key:', default: 'PROJ' });
+  config.email = await input({ message: 'Your Jira email:' });
+
+  console.log('\n  Tip: set JIRA_API_TOKEN in your environment.');
+  console.log('  Get your token at: https://id.atlassian.com/manage-profile/security/api-tokens\n');
+
+  const token = process.env.JIRA_API_TOKEN;
+  if (token && config.email && config.url) {
+    const validate = await confirm({
+      message: 'Validate Jira "Done" transition by listing transitions of an existing ticket?',
+      default: true,
+    });
+    if (validate) {
+      const sampleKey = await input({
+        message: `Sample ticket key (e.g. ${config.project}-1):`,
+        default: `${config.project}-1`,
+      });
+      try {
+        const transitions = await listTransitionsAsync({
+          url: config.url,
+          email: config.email,
+          token,
+          ticket: sampleKey,
+        });
+        if (transitions.length === 0) {
+          console.warn('  ⚠ No transitions returned. Falling back to manual entry.');
+        } else {
+          const choice = await select({
+            message: 'Which transition closes a ticket as Done?',
+            choices: transitions.map((t) => ({
+              name: `${t.name}  (id: ${t.id})`,
+              value: t.id,
+            })),
+          });
+          config.done_transition_id = choice;
+          return config;
+        }
+      } catch (err) {
+        console.warn(`  ⚠ Could not validate via API: ${err.message}`);
+        console.warn('     Falling back to manual entry.\n');
+      }
+    }
+  }
+
+  config.done_transition_id = await input({
+    message: 'Jira "Done" transition ID:',
+    default: '41',
+  });
+
+  return config;
+}
+
 function installFiles(destDir, runtime, scope) {
-  // Copy novaspec/
   const destNovaspec = path.join(destDir, 'novaspec');
-  const destNovaspecConfig = path.join(destNovaspec, 'config.yml');
 
-  // Backup existing config.yml
-  let configBackup = null;
-  if (fs.existsSync(destNovaspecConfig)) {
-    configBackup = fs.readFileSync(destNovaspecConfig, 'utf8');
-  }
+  // Backup config.yml in case copyTree ever changes
+  const destConfigPath = path.join(destNovaspec, 'config.yml');
+  const configBackup = fs.existsSync(destConfigPath)
+    ? fs.readFileSync(destConfigPath, 'utf8')
+    : null;
 
-  copyDir(NOVASPEC_SRC, destNovaspec);
+  copyTree(NOVASPEC_SRC, destNovaspec, { exclude: ['config.yml', MANIFEST_FILE] });
 
-  // Restore config.yml if it existed (user's config wins)
-  if (configBackup) {
-    fs.writeFileSync(destNovaspecConfig, configBackup);
-  }
+  if (configBackup) fs.writeFileSync(destConfigPath, configBackup);
 
-  // Copy AGENTS.md and CLAUDE.md
+  // Framework files at top level
   if (fs.existsSync(AGENTS_SRC)) fs.copyFileSync(AGENTS_SRC, path.join(destDir, 'AGENTS.md'));
-  if (fs.existsSync(CLAUDE_MD_SRC)) fs.copyFileSync(CLAUDE_MD_SRC, path.join(destDir, 'CLAUDE.md'));
+  if (fs.existsSync(CLAUDE_MD_SRC) && !fs.existsSync(path.join(destDir, 'CLAUDE.md'))) {
+    fs.copyFileSync(CLAUDE_MD_SRC, path.join(destDir, 'CLAUDE.md'));
+  }
 
-  // Create context/ structure (only for project scope)
   if (scope === 'project') {
-    for (const dir of [
-      'context/decisions/archived',
-      'context/gotchas',
-      'context/services',
-      'context/changes/active',
-      'context/changes/archive',
-    ]) {
-      fs.mkdirSync(path.join(destDir, dir), { recursive: true });
-    }
-    const gitkeep = path.join(destDir, 'context/changes/active/.gitkeep');
-    if (!fs.existsSync(gitkeep)) fs.writeFileSync(gitkeep, '');
-
-    // notes.md
-    const notes = path.join(destDir, 'notes.md');
-    if (!fs.existsSync(notes)) fs.writeFileSync(notes, '');
+    scaffoldContext(destDir);
   }
 
-  // Runtime symlinks / settings
   if (runtime === 'claude' || runtime === 'both') {
-    createSymlinks(destDir, '.claude');
-    writeClaudeSettings(path.join(destDir, '.claude'));
+    const linkDir = scope === 'global' ? destDir : path.join(destDir, '.claude');
+    createSymlinks(linkDir, destNovaspec);
+    writeClaudeSettings(linkDir);
   }
   if (runtime === 'opencode' || runtime === 'both') {
-    createSymlinks(destDir, '.opencode');
-    writeOpenCodeSettings(path.join(destDir, '.opencode'));
+    if (scope === 'global') {
+      console.warn('  ⚠ Skipping OpenCode global setup (use project install instead).');
+    } else {
+      const linkDir = path.join(destDir, '.opencode');
+      createSymlinks(linkDir, destNovaspec);
+      writeOpenCodeSettings(linkDir);
+    }
   }
 
-  // .gitignore
   ensureGitignore(destDir);
 }
 
-function createSymlinks(destDir, dotDir) {
-  const dir = path.join(destDir, dotDir);
-  fs.mkdirSync(dir, { recursive: true });
+function scaffoldContext(destDir) {
+  for (const dir of [
+    'context/decisions/archived',
+    'context/gotchas',
+    'context/services',
+    'context/changes/active',
+    'context/changes/archive',
+  ]) {
+    fs.mkdirSync(path.join(destDir, dir), { recursive: true });
+  }
+  const gitkeep = path.join(destDir, 'context/changes/active/.gitkeep');
+  if (!fs.existsSync(gitkeep)) fs.writeFileSync(gitkeep, '');
+
+  const notes = path.join(destDir, 'notes.md');
+  if (!fs.existsSync(notes)) fs.writeFileSync(notes, '');
+
+  // Top-level scaffolding files explaining their purpose
+  writeIfMissing(path.join(destDir, 'context/stack.md'), STACK_TEMPLATE);
+  writeIfMissing(path.join(destDir, 'context/conventions.md'), CONVENTIONS_TEMPLATE);
+}
+
+function writeIfMissing(filePath, content) {
+  if (!fs.existsSync(filePath)) fs.writeFileSync(filePath, content);
+}
+
+const STACK_TEMPLATE = `<!--
+  context/stack.md — describe the technology stack of this project.
+
+  Loaded by nova-spec at the start of every ticket so the agent knows what
+  language, frameworks, and key dependencies you use. Keep it short and factual:
+  versions matter, philosophy doesn't.
+
+  Edit freely. Update it whenever you upgrade a major dependency.
+-->
+
+# Stack
+
+## Language & runtime
+- e.g. Node.js 20.x  /  Ruby 3.3  /  Python 3.12
+
+## Framework
+- e.g. Next.js 14 (App Router)  /  Rails 7.1  /  FastAPI 0.110
+
+## Key dependencies
+- e.g. PostgreSQL 16, Redis 7, Sidekiq 7
+- e.g. tailwindcss, prisma, vitest
+
+## Infrastructure
+- e.g. AWS (ECS, RDS), GitHub Actions, Cloudflare Workers
+`;
+
+const CONVENTIONS_TEMPLATE = `<!--
+  context/conventions.md — house rules and patterns for this codebase.
+
+  Loaded by nova-spec at the start of every ticket so the agent writes code
+  that matches your team's style without you having to repeat yourself. List
+  things that are NOT obvious from reading the code.
+
+  Edit freely. One line per rule is fine.
+-->
+
+# Conventions
+
+## Code style
+- e.g. 2-space indent, single quotes, trailing commas
+- e.g. functional components only; no class components
+- e.g. no default exports
+
+## Patterns we follow
+- e.g. service layer for all DB access; controllers stay thin
+- e.g. errors as values, not thrown (Result/Either)
+- e.g. one component per file
+
+## Patterns we avoid
+- e.g. no global mutable state
+- e.g. no \`any\` in TypeScript
+- e.g. no inline styles
+
+## Tests
+- e.g. characterization tests before refactoring
+- e.g. one assertion per test
+- e.g. fixtures in \`__fixtures__/\`, not inline
+`;
+
+function createSymlinks(linkDir, novaspecDir) {
+  fs.mkdirSync(linkDir, { recursive: true });
   for (const name of ['commands', 'skills', 'agents']) {
-    const link = path.join(dir, name);
-    const target = path.join('..', 'novaspec', name);
+    const link = path.join(linkDir, name);
+    const target = path.relative(linkDir, path.join(novaspecDir, name));
     fs.rmSync(link, { recursive: true, force: true });
-    fs.symlinkSync(target, link);
+    const symlinkType = process.platform === 'win32' ? 'junction' : null;
+    try {
+      if (symlinkType) {
+        fs.symlinkSync(target, link, symlinkType);
+      } else {
+        fs.symlinkSync(target, link);
+      }
+    } catch (err) {
+      if (err.code === 'EPERM' && process.platform === 'win32') {
+        console.warn(`  ⚠ Could not symlink ${name} (Windows needs Developer Mode).`);
+        console.warn(`     Falling back to copy. Re-run sync to refresh.`);
+        copyTree(path.join(novaspecDir, name), link);
+      } else {
+        throw err;
+      }
+    }
+  }
+}
+
+function copyTree(src, dest, { exclude = [] } = {}) {
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    if (exclude.includes(entry.name)) continue;
+    if (entry.isSymbolicLink()) continue;
+    if (entry.name === 'node_modules') continue;
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyTree(srcPath, destPath, { exclude });
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
   }
 }
 
 function writeClaudeSettings(claudeDir) {
   const settingsPath = path.join(claudeDir, 'settings.local.json');
-  const hook = {
-    hooks: {
-      SessionStart: [
-        {
-          hooks: [
-            {
-              type: 'command',
-              command: 'npx nova-spec@latest sync 2>/dev/null || true',
-              timeout: 30,
-            },
-          ],
-        },
-      ],
-    },
-  };
+  const novaHook = { type: 'command', command: buildHookCommand(), timeout: 30 };
 
+  let settings = {};
   if (fs.existsSync(settingsPath)) {
-    const existing = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
-    if (existing.hooks?.SessionStart) return; // already configured
-    existing.hooks = existing.hooks || {};
-    existing.hooks.SessionStart = hook.hooks.SessionStart;
-    fs.writeFileSync(settingsPath, JSON.stringify(existing, null, 2) + '\n');
-  } else {
-    fs.writeFileSync(settingsPath, JSON.stringify(hook, null, 2) + '\n');
+    try {
+      settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+    } catch (err) {
+      console.warn(`  ⚠ Could not parse ${settingsPath}: ${err.message}`);
+      console.warn('     Skipping hook setup. Fix the JSON and run /nova-sync.');
+      return;
+    }
   }
+
+  settings.hooks = settings.hooks || {};
+  settings.hooks.SessionStart = settings.hooks.SessionStart || [];
+
+  const alreadyHasNovaHook = settings.hooks.SessionStart.some((g) =>
+    (g.hooks || []).some((h) => h?.command?.includes(HOOK_MARKER)),
+  );
+
+  if (!alreadyHasNovaHook) {
+    settings.hooks.SessionStart.push({ hooks: [novaHook] });
+  }
+
+  fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
 }
 
 function writeOpenCodeSettings(opencodeDir) {
   const settingsPath = path.join(opencodeDir, 'settings.local.json');
-  if (!fs.existsSync(settingsPath)) {
-    fs.writeFileSync(settingsPath, JSON.stringify({
-      $schema: 'https://opencode.ai/config.json',
-      permission: { skill: { '*': 'allow' } },
-    }, null, 2) + '\n');
-  }
+  if (fs.existsSync(settingsPath)) return;
+  fs.writeFileSync(
+    settingsPath,
+    JSON.stringify(
+      {
+        $schema: 'https://opencode.ai/config.json',
+        permission: { skill: { '*': 'allow' } },
+      },
+      null,
+      2,
+    ) + '\n',
+  );
 }
 
-function writeConfig(destDir, { jiraConfig, baseBranch }) {
+function writeConfig(destDir, { ticketSystem, jiraConfig, baseBranch, forgeType }) {
   const configPath = path.join(destDir, 'novaspec', 'config.yml');
-  if (fs.existsSync(configPath)) return; // already restored from backup
+  if (fs.existsSync(configPath)) return;
 
+  const yamlString = (s) => JSON.stringify(s ?? '');
   const content = [
     '# nova-spec — project configuration',
     '# This file is gitignored — do not push it to the repo.',
@@ -214,15 +409,23 @@ function writeConfig(destDir, { jiraConfig, baseBranch }) {
     '    chore: chore',
     '    architecture: arch',
     '  ticket_case: upper',
-    `  base: ${baseBranch}`,
+    `  base: ${yamlString(baseBranch)}`,
+    '',
+    'forge:',
+    `  type: ${forgeType || 'auto'}`,
+    '  cli: auto',
+    '',
+    `ticket_system: ${ticketSystem || 'jira'}`,
     '',
     'jira:',
-    `  skill: "${jiraConfig.skill}"`,
-    `  url: ${jiraConfig.url}`,
-    `  project: ${jiraConfig.project}`,
-    `  email: ${jiraConfig.email}`,
-    `  token: ${jiraConfig.token}`,
-    `  done_transition_id: "${jiraConfig.done_transition_id}"`,
+    `  skill: ${yamlString(jiraConfig.skill)}`,
+    `  url: ${yamlString(jiraConfig.url)}`,
+    `  project: ${yamlString(jiraConfig.project)}`,
+    `  email: ${yamlString(jiraConfig.email)}`,
+    `  token: ${yamlString(jiraConfig.token)}`,
+    `  done_transition_id: ${yamlString(jiraConfig.done_transition_id)}`,
+    '  transitions:',
+    `    done: ${yamlString(jiraConfig.done_transition_id)}`,
   ].join('\n') + '\n';
 
   fs.writeFileSync(configPath, content);
@@ -237,11 +440,13 @@ function ensureGitignore(destDir) {
     if (content.includes(marker)) return;
   }
 
-  const block = [
+  // Project-install gitignore: only the personal/secret bits. Templates,
+  // commands, skills, agents are committed so the team shares customizations.
+  const lines = [
     '',
-    '# nova-spec (local)',
+    marker,
     'novaspec/config.yml',
-    'novaspec/custom/',
+    `novaspec/${MANIFEST_FILE}`,
     '.env',
     'notes.md',
     '.claude/settings.local.json',
@@ -250,23 +455,9 @@ function ensureGitignore(destDir) {
     '.DS_Store',
     '# /nova-spec',
     '',
-  ].join('\n');
+  ];
 
-  fs.appendFileSync(gitignorePath, block);
-}
-
-function copyDir(src, dest) {
-  fs.mkdirSync(dest, { recursive: true });
-  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
-    const srcPath = path.join(src, entry.name);
-    const destPath = path.join(dest, entry.name);
-    if (entry.name === 'config.yml') continue; // never overwrite user config
-    if (entry.isDirectory()) {
-      copyDir(srcPath, destPath);
-    } else {
-      fs.copyFileSync(srcPath, destPath);
-    }
-  }
+  fs.appendFileSync(gitignorePath, lines.join('\n'));
 }
 
 module.exports = { init };