nova-spec 1.0.2 → 1.0.4

package/lib/jira.js

@@ -0,0 +1,138 @@
+'use strict';
+
+const https = require('https');
+const { URL } = require('url');
+
+function basicAuth(email, token) {
+  return Buffer.from(`${email}:${token}`).toString('base64');
+}
+
+function request({ url, method = 'GET', email, token, body = null }) {
+  return new Promise((resolve, reject) => {
+    let parsed;
+    try {
+      parsed = new URL(url);
+    } catch (_) {
+      return reject(new Error(`Invalid URL: ${url}`));
+    }
+
+    const options = {
+      method,
+      hostname: parsed.hostname,
+      port: parsed.port || 443,
+      path: parsed.pathname + parsed.search,
+      headers: {
+        Authorization: `Basic ${basicAuth(email, token)}`,
+        Accept: 'application/json',
+      },
+    };
+
+    if (body) {
+      options.headers['Content-Type'] = 'application/json';
+    }
+
+    const req = https.request(options, (res) => {
+      let data = '';
+      res.setEncoding('utf8');
+      res.on('data', (chunk) => (data += chunk));
+      res.on('end', () => {
+        const status = res.statusCode || 0;
+        if (status >= 400) {
+          const error = new Error(`Jira HTTP ${status}: ${data || res.statusMessage}`);
+          error.status = status;
+          return reject(error);
+        }
+        if (!data) return resolve(null);
+        try {
+          resolve(JSON.parse(data));
+        } catch (err) {
+          reject(new Error(`Invalid JSON from Jira: ${err.message}`));
+        }
+      });
+    });
+
+    req.on('error', (err) => reject(err));
+    if (body) req.write(JSON.stringify(body));
+    req.end();
+  });
+}
+
+async function getIssueAsync({ url, email, token, ticket }) {
+  const endpoint = `${url.replace(/\/$/, '')}/rest/api/3/issue/${encodeURIComponent(ticket)}`;
+  return request({ url: endpoint, email, token });
+}
+
+async function listTransitionsAsync({ url, email, token, ticket }) {
+  const endpoint = `${url.replace(/\/$/, '')}/rest/api/3/issue/${encodeURIComponent(ticket)}/transitions`;
+  const response = await request({ url: endpoint, email, token });
+  return (response && response.transitions) || [];
+}
+
+async function transitionAsync({ url, email, token, ticket, transitionId }) {
+  const endpoint = `${url.replace(/\/$/, '')}/rest/api/3/issue/${encodeURIComponent(ticket)}/transitions`;
+  return request({
+    url: endpoint,
+    method: 'POST',
+    email,
+    token,
+    body: { transition: { id: String(transitionId) } },
+  });
+}
+
+function runCli() {
+  // CLI mode: node lib/jira.js <command> [args...]
+  const [, , cmd, ...args] = process.argv;
+  const { JIRA_URL, JIRA_EMAIL, JIRA_API_TOKEN } = process.env;
+
+  if (!JIRA_URL || !JIRA_EMAIL || !JIRA_API_TOKEN) {
+    console.error('Missing env vars: JIRA_URL, JIRA_EMAIL, JIRA_API_TOKEN');
+    process.exit(2);
+  }
+
+  const baseArgs = { url: JIRA_URL, email: JIRA_EMAIL, token: JIRA_API_TOKEN };
+  let promise;
+
+  switch (cmd) {
+    case 'get':
+      if (!args[0]) {
+        console.error('Usage: nova-jira get <TICKET>');
+        process.exit(2);
+      }
+      promise = getIssueAsync({ ...baseArgs, ticket: args[0] });
+      break;
+    case 'transitions':
+      if (!args[0]) {
+        console.error('Usage: nova-jira transitions <TICKET>');
+        process.exit(2);
+      }
+      promise = listTransitionsAsync({ ...baseArgs, ticket: args[0] });
+      break;
+    case 'transition':
+      if (!args[0] || !args[1]) {
+        console.error('Usage: nova-jira transition <TICKET> <TRANSITION_ID>');
+        process.exit(2);
+      }
+      promise = transitionAsync({ ...baseArgs, ticket: args[0], transitionId: args[1] });
+      break;
+    default:
+      console.error('Commands: get <TICKET> | transitions <TICKET> | transition <TICKET> <ID>');
+      process.exit(2);
+  }
+
+  promise
+    .then((r) => {
+      if (r != null) console.log(JSON.stringify(r, null, 2));
+    })
+    .catch((err) => {
+      console.error(err.message);
+      process.exit(err.status === 401 ? 401 : err.status === 404 ? 404 : 1);
+    });
+}
+
+if (require.main === module) runCli();
+
+module.exports = {
+  getIssueAsync,
+  listTransitionsAsync,
+  transitionAsync,
+};

package/lib/migrate-config.js

@@ -0,0 +1,59 @@
+'use strict';
+
+const fs = require('fs');
+
+// Each migration is { from: 'X.Y', to: 'X.Y', apply: (text) => text }.
+// They run in order; each one transforms the YAML text. Idempotent — applying
+// twice produces the same result. Detection is heuristic (presence/absence of
+// keys), not a version field, so old configs without `_schema:` migrate cleanly.
+const MIGRATIONS = [
+  {
+    name: 'add-forge-section',
+    detect: (text) => !/^forge:/m.test(text),
+    apply: (text) => {
+      const block = [
+        '',
+        'forge:',
+        '  type: auto              # auto | github | gitlab',
+        '  cli: auto               # auto | gh | glab',
+      ].join('\n');
+      return text.trimEnd() + '\n' + block + '\n';
+    },
+  },
+  {
+    name: 'rename-done-transition-id',
+    detect: (text) => /^\s*done_transition_id:/m.test(text) && !/^\s*transitions:/m.test(text),
+    apply: (text) => {
+      // Move done_transition_id under jira.transitions.done while keeping the
+      // legacy key as fallback so older skills don't break mid-migration.
+      return text.replace(
+        /^(\s*)done_transition_id:\s*"?([^"\n]+)"?\s*$/m,
+        (_, indent, value) =>
+          `${indent}done_transition_id: "${value}"\n${indent}transitions:\n${indent}  done: "${value}"`,
+      );
+    },
+  },
+];
+
+function migrateConfig(configPath) {
+  if (!fs.existsSync(configPath)) return { applied: [] };
+
+  const original = fs.readFileSync(configPath, 'utf8');
+  let current = original;
+  const applied = [];
+
+  for (const migration of MIGRATIONS) {
+    if (migration.detect(current)) {
+      current = migration.apply(current);
+      applied.push(migration.name);
+    }
+  }
+
+  if (current !== original) {
+    fs.writeFileSync(configPath, current);
+  }
+
+  return { applied };
+}
+
+module.exports = { migrateConfig, MIGRATIONS };

package/lib/sync.js

@@ -3,185 +3,246 @@
 const fs = require('fs');
 const path = require('path');
 const crypto = require('crypto');
+const os = require('os');
 
 const MANIFEST_FILE = '.nova-manifest.json';
+const HOOK_MARKER = '# nova-spec auto-sync';
+const FRAMEWORK_FILES = ['AGENTS.md', 'CLAUDE.md'];
+// Paths the user owns or that are auto-generated — never tracked or overwritten.
+const NEVER_TRACK = new Set(['novaspec/config.yml', `novaspec/${MANIFEST_FILE}`]);
 
 function hashFile(filePath) {
-  const content = fs.readFileSync(filePath);
-  return crypto.createHash('md5').update(content).digest('hex');
+  return crypto.createHash('sha256').update(fs.readFileSync(filePath)).digest('hex');
 }
 
-function walkDir(dir, base = dir) {
-  const results = {};
-  if (!fs.existsSync(dir)) return results;
+function collectPackageFiles(packageRoot) {
+  // Returns a flat map of relPath -> absSrcPath for every file we would ship.
+  const out = {};
+  const novaspec = path.join(packageRoot, 'novaspec');
+  walk(novaspec, packageRoot, out);
+  for (const f of FRAMEWORK_FILES) {
+    const abs = path.join(packageRoot, f);
+    if (fs.existsSync(abs)) out[f] = abs;
+  }
+  return out;
+}
+
+function walk(dir, base, out) {
+  if (!fs.existsSync(dir)) return;
   for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
-    const fullPath = path.join(dir, entry.name);
-    const relPath = path.relative(base, fullPath);
+    if (entry.isSymbolicLink()) continue;
+    if (entry.name === 'node_modules') continue;
+    if (entry.name === MANIFEST_FILE) continue;
+    if (entry.name === '.gitkeep') continue;
+
+    const abs = path.join(dir, entry.name);
+    const rel = path.relative(base, abs).replace(/\\/g, '/');
+
+    if (NEVER_TRACK.has(rel)) continue;
+
     if (entry.isDirectory()) {
-      Object.assign(results, walkDir(fullPath, base));
-    } else {
-      results[relPath] = hashFile(fullPath);
+      walk(abs, base, out);
+    } else if (entry.isFile()) {
+      out[rel] = abs;
     }
   }
-  return results;
 }
 
-function generateManifest(novaspecDir) {
-  const coreDir = novaspecDir;
-  const hashes = {};
-
-  for (const section of ['commands', 'skills', 'agents']) {
-    const sectionDir = path.join(coreDir, section);
-    if (!fs.existsSync(sectionDir)) continue;
-    for (const entry of fs.readdirSync(sectionDir, { withFileTypes: true })) {
-      if (!entry.isDirectory() && !entry.name.endsWith('.md')) continue;
-      const name = entry.name.replace('.md', '');
-      const fullPath = path.join(sectionDir, entry.name);
-      if (entry.isDirectory()) {
-        hashes[`${section}/${name}`] = walkDir(fullPath);
-      } else {
-        hashes[`${section}/${name}`] = hashFile(fullPath);
-      }
-    }
+function generateManifest(packageRoot) {
+  // Hashes everything WE ship, not what's on the consumer's disk. The manifest
+  // records "what we last delivered to this user", so the next sync can detect
+  // local edits via hash-compare.
+  const files = {};
+  const sources = collectPackageFiles(packageRoot);
+  for (const [rel, abs] of Object.entries(sources)) {
+    files[rel] = hashFile(abs);
   }
-
-  const manifest = {
+  return {
     version: require('../package.json').version,
     generated_at: new Date().toISOString(),
-    hashes,
-    outdated_customs: [],
+    files,
   };
+}
 
-  const manifestPath = path.join(novaspecDir, MANIFEST_FILE);
-  fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + '\n');
-  return manifest;
+function readManifest(manifestPath) {
+  if (!fs.existsSync(manifestPath)) return { files: {} };
+  try {
+    const data = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+    return { files: data.files || {}, version: data.version };
+  } catch (err) {
+    console.error(`  ✗ Could not parse ${manifestPath}: ${err.message}`);
+    console.error('     Aborting sync to avoid clobbering project state.');
+    process.exit(1);
+  }
 }
 
 async function sync(destDir = process.cwd()) {
   const novaspecDest = path.join(destDir, 'novaspec');
-  const manifestPath = path.join(novaspecDest, MANIFEST_FILE);
 
   if (!fs.existsSync(novaspecDest)) {
     console.error('  ✗ nova-spec not installed in this directory. Run: npx nova-spec init');
     process.exit(1);
   }
 
-  // Read existing manifest
-  const oldManifest = fs.existsSync(manifestPath)
-    ? JSON.parse(fs.readFileSync(manifestPath, 'utf8'))
-    : { hashes: {} };
-
-  // Update core files from package
   const PACKAGE_ROOT = path.join(__dirname, '..');
-  const NOVASPEC_SRC = path.join(PACKAGE_ROOT, 'novaspec');
-
-  // Backup config.yml
-  const configPath = path.join(novaspecDest, 'config.yml');
-  let configBackup = null;
-  if (fs.existsSync(configPath)) {
-    configBackup = fs.readFileSync(configPath, 'utf8');
-  }
+  const manifestPath = path.join(novaspecDest, MANIFEST_FILE);
+  const oldManifest = readManifest(manifestPath);
+
+  const sources = collectPackageFiles(PACKAGE_ROOT);
+  const created = [];
+  const updated = [];
+  const skipped = [];
+  const removed = [];
+  const skippedRemoved = [];
+
+  // Update / create / skip files
+  for (const [rel, srcAbs] of Object.entries(sources)) {
+    const destAbs = path.join(destDir, rel);
+    const newStockHash = hashFile(srcAbs);
+
+    if (!fs.existsSync(destAbs)) {
+      fs.mkdirSync(path.dirname(destAbs), { recursive: true });
+      fs.copyFileSync(srcAbs, destAbs);
+      created.push(rel);
+      continue;
+    }
 
-  copyDirSync(NOVASPEC_SRC, novaspecDest);
+    const currentHash = hashFile(destAbs);
+    if (currentHash === newStockHash) continue; // already up to date
 
-  // Restore config
-  if (configBackup) fs.writeFileSync(configPath, configBackup);
+    const previousShipped = oldManifest.files[rel];
+    const isUntouched = !previousShipped || currentHash === previousShipped;
 
-  // Update AGENTS.md and CLAUDE.md (always overwrite — these are framework files)
-  for (const file of ['AGENTS.md', 'CLAUDE.md']) {
-    const src = path.join(PACKAGE_ROOT, file);
-    const dest = path.join(destDir, file);
-    if (fs.existsSync(src) && fs.existsSync(dest)) {
-      fs.copyFileSync(src, dest);
+    if (isUntouched) {
+      fs.copyFileSync(srcAbs, destAbs);
+      updated.push(rel);
+    } else {
+      skipped.push(rel);
     }
   }
 
-  // Regenerate manifest with new hashes
-  const newManifest = generateManifest(novaspecDest);
-
-  // Check custom overrides
-  const customDir = path.join(novaspecDest, 'custom');
-  const outdated = [];
-
-  if (fs.existsSync(customDir)) {
-    for (const section of ['commands', 'skills', 'agents']) {
-      const customSection = path.join(customDir, section);
-      if (!fs.existsSync(customSection)) continue;
-      for (const entry of fs.readdirSync(customSection, { withFileTypes: true })) {
-        const name = entry.name.replace('.md', '');
-        const key = `${section}/${name}`;
-        const oldHash = oldManifest.hashes[key];
-        const newHash = newManifest.hashes[key];
-        if (oldHash && newHash && JSON.stringify(oldHash) !== JSON.stringify(newHash)) {
-          outdated.push(name);
-        }
-      }
+  // Detect upstream removals
+  for (const rel of Object.keys(oldManifest.files)) {
+    if (sources[rel]) continue; // still shipped
+    const destAbs = path.join(destDir, rel);
+    if (!fs.existsSync(destAbs)) continue; // already gone
+
+    const currentHash = hashFile(destAbs);
+    if (currentHash === oldManifest.files[rel]) {
+      fs.unlinkSync(destAbs);
+      removed.push(rel);
+    } else {
+      skippedRemoved.push(rel);
     }
   }
 
-  // Save outdated list in manifest
-  newManifest.outdated_customs = outdated;
+  // Build new manifest: stock hashes for everything shipped, but keep the OLD
+  // hash for files we skipped (so future syncs still detect their modification).
+  const newManifest = generateManifest(PACKAGE_ROOT);
+  for (const rel of skipped) {
+    if (oldManifest.files[rel]) newManifest.files[rel] = oldManifest.files[rel];
+  }
+  for (const rel of skippedRemoved) {
+    if (oldManifest.files[rel]) newManifest.files[rel] = oldManifest.files[rel];
+  }
   fs.writeFileSync(manifestPath, JSON.stringify(newManifest, null, 2) + '\n');
 
-  // Ensure SessionStart hook is present (idempotent)
+  // Migrate config.yml (idempotent)
+  const { migrateConfig } = require('./migrate-config.js');
+  migrateConfig(path.join(novaspecDest, 'config.yml'));
+
+  // Refresh SessionStart hook in any installed runtime
   ensureSessionStartHook(destDir);
 
-  // Report
-  console.log('\n  ✓ nova-spec core updated to v' + newManifest.version + '\n');
+  printReport({ version: newManifest.version, created, updated, skipped, removed, skippedRemoved });
+}
 
-  if (outdated.length > 0) {
-    console.log('  ⚠️  Custom overrides with upstream changes:');
-    for (const name of outdated) {
-      console.log(`     - ${name} → run /nova-diff ${name} to review`);
-    }
-  } else {
-    console.log('  ✓ No custom overrides affected.');
+function printReport({ version, created, updated, skipped, removed, skippedRemoved }) {
+  console.log(`\n  ✓ nova-spec synced to v${version}\n`);
+
+  if (created.length) {
+    console.log(`  + ${created.length} new file(s):`);
+    for (const f of created) console.log(`     ${f}`);
+  }
+  if (updated.length) {
+    console.log(`  ↻ ${updated.length} file(s) updated (untouched locally):`);
+    for (const f of updated) console.log(`     ${f}`);
+  }
+  if (skipped.length) {
+    console.log(`  ⚠ ${skipped.length} file(s) NOT updated (you have local edits):`);
+    for (const f of skipped) console.log(`     ${f}  → /nova-diff ${f}`);
+  }
+  if (removed.length) {
+    console.log(`  − ${removed.length} file(s) removed upstream:`);
+    for (const f of removed) console.log(`     ${f}`);
+  }
+  if (skippedRemoved.length) {
+    console.log(`  ⚠ ${skippedRemoved.length} file(s) removed upstream but kept (you edited them):`);
+    for (const f of skippedRemoved) console.log(`     ${f}`);
+  }
+  if (!created.length && !updated.length && !skipped.length && !removed.length && !skippedRemoved.length) {
+    console.log('  ✓ Already up to date.');
   }
   console.log('');
 }
 
-function copyDirSync(src, dest) {
-  fs.mkdirSync(dest, { recursive: true });
-  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
-    if (entry.name === 'config.yml') continue;
-    if (entry.name === 'custom') continue; // never overwrite custom/
-    if (entry.name === MANIFEST_FILE) continue;
-    const srcPath = path.join(src, entry.name);
-    const destPath = path.join(dest, entry.name);
-    if (entry.isDirectory()) {
-      copyDirSync(srcPath, destPath);
-    } else {
-      fs.copyFileSync(srcPath, destPath);
-    }
-  }
+function buildHookCommand() {
+  const logPath = path.join(os.homedir(), '.nova-spec.log');
+  return `npx nova-spec@latest sync >> ${logPath} 2>&1 || true ${HOOK_MARKER}`;
 }
 
 function ensureSessionStartHook(destDir) {
-  const hook = {
-    type: 'command',
-    command: 'npx nova-spec@latest sync 2>/dev/null || true',
-    timeout: 30,
-  };
+  const hookCommand = buildHookCommand();
+  const novaHook = { type: 'command', command: hookCommand, timeout: 30 };
 
   const targets = [
     path.join(destDir, '.claude', 'settings.local.json'),
     path.join(destDir, '.opencode', 'settings.local.json'),
-  ].filter(p => fs.existsSync(path.dirname(p))); // only if runtime dir exists
+  ].filter(p => fs.existsSync(path.dirname(p)));
 
   for (const settingsPath of targets) {
     let settings = {};
     if (fs.existsSync(settingsPath)) {
-      try { settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8')); } catch (_) {}
+      try {
+        settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+      } catch (err) {
+        console.error(`  ⚠ Could not parse ${settingsPath}: ${err.message}`);
+        console.error('     Skipping hook update for this file. Fix the JSON and re-run sync.');
+        continue;
+      }
     }
 
-    const existing = settings.hooks?.SessionStart?.[0]?.hooks?.[0];
-    if (existing?.command === hook.command) continue; // already up to date
-
-    // Overwrite if missing or using outdated command (e.g. without @latest)
     settings.hooks = settings.hooks || {};
-    settings.hooks.SessionStart = [{ hooks: [hook] }];
+    settings.hooks.SessionStart = settings.hooks.SessionStart || [];
+
+    let updated = false;
+    for (const group of settings.hooks.SessionStart) {
+      group.hooks = group.hooks || [];
+      for (let i = 0; i < group.hooks.length; i++) {
+        if (group.hooks[i]?.command?.includes(HOOK_MARKER)) {
+          if (group.hooks[i].command !== hookCommand) {
+            group.hooks[i] = novaHook;
+          }
+          updated = true;
+        }
+      }
+    }
+
+    if (!updated) {
+      settings.hooks.SessionStart.push({ hooks: [novaHook] });
+    }
+
     fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
   }
 }
 
-module.exports = { sync, generateManifest };
+module.exports = {
+  sync,
+  generateManifest,
+  ensureSessionStartHook,
+  buildHookCommand,
+  readManifest,
+  collectPackageFiles,
+  HOOK_MARKER,
+  FRAMEWORK_FILES,
+};

package/novaspec/agents/context-loader.md

@@ -27,7 +27,7 @@ If `context/` doesn't exist, return:
 ## Loaded context
 **Services**: not documented (context/ missing)
 **Decisions**: none
-**Gaps**: context/ structure not initialized — run install.sh
+**Gaps**: context/ structure not initialized — run `npx nova-spec init`
 **Questions**: none
 ```
 And stop.

package/novaspec/guardrails/nova-installed.sh

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+# Guardrail: verify nova-spec is properly installed in this project.
+#
+# Usage: bash novaspec/guardrails/nova-installed.sh
+# Exits 0 if installed, 1 if not.
+
+set -euo pipefail
+
+ok=1
+
+if [ ! -f "novaspec/config.yml" ]; then
+  echo "✗ novaspec/config.yml not found — run: npx nova-spec init" >&2
+  ok=0
+fi
+
+if [ ! -d "context/" ]; then
+  echo "✗ context/ directory missing — run: npx nova-spec init" >&2
+  ok=0
+fi
+
+[ "$ok" -eq 1 ]

package/novaspec/guardrails/proposal-closed.sh

@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+# Guardrail: verify the proposal has no open requirements.
+#
+# Usage: bash novaspec/guardrails/proposal-closed.sh <ticket-id>
+# Exits 0 if proposal is closed, 1 if it has open markers, 2 if missing.
+
+set -euo pipefail
+
+if [ -z "${1:-}" ]; then
+  echo "Usage: $0 <ticket-id>" >&2
+  exit 2
+fi
+
+ticket="$1"
+proposal="context/changes/active/${ticket}/proposal.md"
+
+if [ ! -f "$proposal" ]; then
+  echo "✗ Proposal not found: $proposal" >&2
+  exit 2
+fi
+
+# Patterns that indicate unresolved questions or placeholders.
+# Word-boundary checks avoid matching e.g. "TODOS" inside a real word.
+patterns=(
+  '\bTBD\b'
+  '\bTODO\b'
+  '\bFIXME\b'
+  '\?\?\?'
+  '<placeholder>'
+  '\[ \] decision'
+)
+
+found=0
+for pat in "${patterns[@]}"; do
+  if grep -nE "$pat" "$proposal" >/dev/null 2>&1; then
+    if [ $found -eq 0 ]; then
+      echo "✗ Proposal has open markers — close them before /nova-plan:"
+      found=1
+    fi
+    grep -nE "$pat" "$proposal" | sed 's/^/   /'
+  fi
+done
+
+if [ $found -eq 1 ]; then
+  exit 1
+fi
+
+echo "✓ Proposal is closed."
+exit 0