nova-spec 1.0.6 → 1.0.7

package/lib/forge.js

@@ -2,20 +2,45 @@
 
 const { execSync } = require('child_process');
 
+function classifyRemote(remote) {
+  if (!remote) return null;
+  if (/github\.com[:/]/i.test(remote)) return 'github';
+  if (/gitlab[.-][\w.-]+[:/]|gitlab\.com[:/]/i.test(remote)) return 'gitlab';
+  if (/bitbucket\.org[:/]/i.test(remote)) return 'bitbucket';
+  return null;
+}
+
 function detectForge(cwd = process.cwd()) {
-  let remote = '';
+  // Try `origin` first (the common case).
   try {
-    remote = execSync('git remote get-url origin', { cwd, stdio: ['ignore', 'pipe', 'ignore'] })
+    const remote = execSync('git remote get-url origin', {
+      cwd,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    })
       .toString()
       .trim();
+    const hit = classifyRemote(remote);
+    if (hit) return hit;
   } catch (_) {
-    return null;
+    // fall through to multi-remote scan
+  }
+
+  // Fallback: walk every remote URL. Useful for fork workflows where the
+  // primary remote is named `upstream` or `gh` instead of `origin`.
+  try {
+    const lines = execSync('git remote -v', { cwd, stdio: ['ignore', 'pipe', 'ignore'] })
+      .toString()
+      .split('\n');
+    for (const line of lines) {
+      const m = line.match(/^\S+\s+(\S+)\s+\((fetch|push)\)$/);
+      if (!m) continue;
+      const hit = classifyRemote(m[1]);
+      if (hit) return hit;
+    }
+  } catch (_) {
+    /* not a git repo or git not available */
   }
 
-  if (!remote) return null;
-  if (/github\.com[:/]/i.test(remote)) return 'github';
-  if (/gitlab[.-][\w.-]+[:/]|gitlab\.com[:/]/i.test(remote)) return 'gitlab';
-  if (/bitbucket\.org[:/]/i.test(remote)) return 'bitbucket';
   return null;
 }
 

package/lib/installer.js

@@ -8,6 +8,7 @@ const {
   buildHookCommand,
   HOOK_MARKER,
   MANIFEST_FILE,
+  writeAtomic,
 } = require('./sync.js');
 const { detectForge } = require('./forge.js');
 const { listTransitionsAsync } = require('./jira.js');
@@ -125,7 +126,7 @@ async function init() {
 
   // Manifest reflects what we just shipped from the package.
   const manifest = generateManifest(PACKAGE_ROOT);
-  fs.writeFileSync(
+  writeAtomic(
     path.join(destDir, 'novaspec', MANIFEST_FILE),
     JSON.stringify(manifest, null, 2) + '\n',
   );
@@ -396,13 +397,13 @@ function writeClaudeSettings(claudeDir) {
     settings.hooks.SessionStart.push({ hooks: [novaHook] });
   }
 
-  fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+  writeAtomic(settingsPath, JSON.stringify(settings, null, 2) + '\n');
 }
 
 function writeOpenCodeSettings(opencodeDir) {
   const settingsPath = path.join(opencodeDir, 'settings.local.json');
   if (fs.existsSync(settingsPath)) return;
-  fs.writeFileSync(
+  writeAtomic(
     settingsPath,
     JSON.stringify(
       {
@@ -454,7 +455,7 @@ function writeConfig(destDir, { ticketSystem, jiraConfig, baseBranch, forgeType
     `    done: ${yamlString(jiraConfig.done_transition_id)}`,
   ].join('\n') + '\n';
 
-  fs.writeFileSync(configPath, content);
+  writeAtomic(configPath, content);
 }
 
 function ensureGitignore(destDir) {

package/lib/migrate-config.js

@@ -1,6 +1,7 @@
 'use strict';
 
 const fs = require('fs');
+const { writeAtomic } = require('./sync.js');
 
 // Each migration is { from: 'X.Y', to: 'X.Y', apply: (text) => text }.
 // They run in order; each one transforms the YAML text. Idempotent — applying
@@ -26,10 +27,13 @@ const MIGRATIONS = [
     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.
+      // The value capture is intentionally non-greedy and strips trailing
+      // whitespace + an optional inline `# comment` so users who hand-edited
+      // the file with annotations don't get their comment merged into the value.
       return text.replace(
-        /^(\s*)done_transition_id:\s*"?([^"\n]+)"?\s*$/m,
+        /^(\s*)done_transition_id:\s*"?([^"#\n]+?)"?\s*(?:#[^\n]*)?$/m,
         (_, indent, value) =>
-          `${indent}done_transition_id: "${value}"\n${indent}transitions:\n${indent}  done: "${value}"`,
+          `${indent}done_transition_id: "${value.trim()}"\n${indent}transitions:\n${indent}  done: "${value.trim()}"`,
       );
     },
   },
@@ -50,7 +54,7 @@ function migrateConfig(configPath) {
   }
 
   if (current !== original) {
-    fs.writeFileSync(configPath, current);
+    writeAtomic(configPath, current);
   }
 
   return { applied };

package/lib/sync.js

@@ -10,7 +10,29 @@ 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}`]);
 
+// Write content to a file via tmp + rename, so partial writes (SIGKILL,
+// disk-full mid-write) never leave a half-written file behind. Critical for
+// the manifest and settings.local.json — corrupted JSON there kills the
+// framework or the IDE startup.
+function writeAtomic(filePath, content) {
+  const tmp = `${filePath}.tmp.${process.pid}.${Date.now()}`;
+  fs.writeFileSync(tmp, content);
+  try {
+    fs.renameSync(tmp, filePath);
+  } catch (err) {
+    try { fs.unlinkSync(tmp); } catch (_) {}
+    throw err;
+  }
+}
+
 function hashFile(filePath) {
+  // Refuse to follow symlinks. If the user replaced a tracked file with a
+  // symlink, hash the link target STRING (not the resolved file) so the
+  // change is detected as "modified" and the framework leaves it alone.
+  const stat = fs.lstatSync(filePath);
+  if (stat.isSymbolicLink()) {
+    return crypto.createHash('sha256').update(fs.readlinkSync(filePath)).digest('hex');
+  }
   return crypto.createHash('sha256').update(fs.readFileSync(filePath)).digest('hex');
 }
 
@@ -69,9 +91,18 @@ function readManifest(manifestPath) {
     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);
+    // Corrupt manifest → back it up and continue with empty. Combined with the
+    // conservative sync rule (no previousShipped → SKIP), this preserves every
+    // local file. Replaces a hard process.exit that left users stuck.
+    const backup = `${manifestPath}.corrupt.${Date.now()}`;
+    try {
+      fs.renameSync(manifestPath, backup);
+      console.warn(`  ⚠ Manifest was corrupt; backed up to ${path.basename(backup)} and continuing.`);
+      console.warn('     Until the manifest is rebuilt, sync will skip every file that differs from the package.');
+    } catch (renameErr) {
+      console.warn(`  ⚠ Manifest is corrupt and could not be backed up: ${renameErr.message}`);
+    }
+    return { files: {} };
   }
 }
 
@@ -94,6 +125,11 @@ async function sync(destDir = process.cwd()) {
   const removed = [];
   const skippedRemoved = [];
 
+  // Migrate config.yml BEFORE writing the manifest, so a crash here doesn't
+  // leave the manifest claiming "new version applied" while config is stale.
+  const { migrateConfig } = require('./migrate-config.js');
+  migrateConfig(path.join(novaspecDest, 'config.yml'));
+
   // Update / create / skip files
   for (const [rel, srcAbs] of Object.entries(sources)) {
     const destAbs = path.join(destDir, rel);
@@ -114,8 +150,6 @@ async function sync(destDir = process.cwd()) {
     // Only overwrite when we KNOW the user didn't touch it: previousShipped
     // must be recorded AND match the current disk hash. If the manifest is
     // missing or doesn't mention this file, treat as user-owned and skip.
-    // This preserves edits when the manifest is deleted/corrupt/merged-away,
-    // at the cost of needing /nova-diff to apply the new version.
     if (previousShipped && currentHash === previousShipped) {
       fs.copyFileSync(srcAbs, destAbs);
       updated.push(rel);
@@ -148,11 +182,11 @@ async function sync(destDir = process.cwd()) {
   for (const rel of skippedRemoved) {
     if (oldManifest.files[rel]) newManifest.files[rel] = oldManifest.files[rel];
   }
-  fs.writeFileSync(manifestPath, JSON.stringify(newManifest, null, 2) + '\n');
+  writeAtomic(manifestPath, JSON.stringify(newManifest, null, 2) + '\n');
 
-  // Migrate config.yml (idempotent)
-  const { migrateConfig } = require('./migrate-config.js');
-  migrateConfig(path.join(novaspecDest, 'config.yml'));
+  // Refresh runtime dirs: re-link .claude/{commands,skills,agents} if a previous
+  // install on Windows fell back to copy. Idempotent — no-op when already linked.
+  refreshRuntimeLinks(destDir);
 
   // Refresh SessionStart hook in any installed runtime
   ensureSessionStartHook(destDir);
@@ -205,6 +239,12 @@ function ensureSessionStartHook(destDir) {
     path.join(destDir, '.opencode', 'settings.local.json'),
   ].filter(p => fs.existsSync(path.dirname(p)));
 
+  // Any hook command running `npx nova-spec[@<tag>] sync` is OURS, even if
+  // it doesn't carry the modern marker (older installs from before v1.0.2).
+  // Strip all of them and append one canonical entry — guaranteed dedupe.
+  const isNovaHook = (h) =>
+    h && typeof h.command === 'string' && /\bnpx\s+nova-spec(@\S+)?\s+sync\b/.test(h.command);
+
   for (const settingsPath of targets) {
     let settings = {};
     if (fs.existsSync(settingsPath)) {
@@ -220,24 +260,73 @@ function ensureSessionStartHook(destDir) {
     settings.hooks = settings.hooks || {};
     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 (!Array.isArray(group.hooks)) continue;
+      group.hooks = group.hooks.filter((h) => !isNovaHook(h));
     }
+    // Drop groups whose hooks array is now empty
+    settings.hooks.SessionStart = settings.hooks.SessionStart.filter(
+      (g) => Array.isArray(g.hooks) && g.hooks.length > 0,
+    );
+
+    settings.hooks.SessionStart.push({ hooks: [novaHook] });
 
-    if (!updated) {
-      settings.hooks.SessionStart.push({ hooks: [novaHook] });
+    writeAtomic(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+  }
+}
+
+function refreshRuntimeLinks(destDir) {
+  // Re-establish symlinks under .claude/ and .opencode/ if a previous install
+  // copied them instead (Windows EPERM fallback). On systems where symlinks
+  // are permitted this is a no-op; on Windows without Developer Mode it
+  // refreshes the copy with the latest content.
+  const novaspecDir = path.join(destDir, 'novaspec');
+  if (!fs.existsSync(novaspecDir)) return;
+
+  const runtimeDirs = ['.claude', '.opencode']
+    .map((d) => path.join(destDir, d))
+    .filter((d) => fs.existsSync(d));
+
+  for (const rt of runtimeDirs) {
+    for (const name of ['commands', 'skills', 'agents']) {
+      const link = path.join(rt, name);
+      const target = path.relative(rt, path.join(novaspecDir, name));
+
+      let isLink = false;
+      try {
+        isLink = fs.lstatSync(link).isSymbolicLink();
+      } catch (_) {
+        /* doesn't exist — fall through to create */
+      }
+
+      if (isLink) continue; // already linked, nothing to do
+
+      // It's a directory of copied files (Windows fallback) or missing.
+      // Try to make it a symlink; if that fails, refresh the copy.
+      fs.rmSync(link, { recursive: true, force: true });
+      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' || err.code === 'EACCES') {
+          copyTreeShallow(path.join(novaspecDir, name), link);
+        } else {
+          throw err;
+        }
+      }
     }
+  }
+}
 
-    fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+function copyTreeShallow(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    if (entry.isSymbolicLink()) continue;
+    const s = path.join(src, entry.name);
+    const d = path.join(dest, entry.name);
+    if (entry.isDirectory()) copyTreeShallow(s, d);
+    else fs.copyFileSync(s, d);
   }
 }
 
@@ -248,6 +337,8 @@ module.exports = {
   buildHookCommand,
   readManifest,
   collectPackageFiles,
+  refreshRuntimeLinks,
+  writeAtomic,
   HOOK_MARKER,
   FRAMEWORK_FILES,
   MANIFEST_FILE,

package/novaspec/commands/nova-build.md

@@ -6,7 +6,7 @@ You execute `tasks.md` in order, task by task.
 
 ## Guardrail
 
-`checklist.md` → 1, 3 (branch-pattern, tasks-exist)
+`checklist.md` → 0, 1, 2, 3 (nova-installed, branch-pattern, proposal-exists, tasks-exist)
 
 ## Precondition
 
@@ -54,10 +54,19 @@ Show the user:
 **If tasks remain**: continue with the next one without asking permission.
 
 **Stop only if**:
-- There's a blocker (error, unhandled exception)
+- There's a blocker (error, unhandled exception, test fails you can't fix)
 - There's an open decision in the spec
 - You have a question only the user can answer
 
+**When you stop on a failed task**, before stopping:
+1. Mark the failing task in `tasks.md` as `- [!]` (instead of `- [x]` or `- [ ]`)
+2. Append a one-line note next to it explaining why
+3. Tell the user what failed and what they need to decide
+
+This way, when the user later re-runs `/nova-build`, the framework picks
+up at the failed task (not from the first `- [ ]` after it) and the user
+can see at a glance what blocked the flow.
+
 **If it was the last one**:
 > "All complete. Run `/nova-review`."
 

package/novaspec/commands/nova-review.md

@@ -6,7 +6,7 @@ Final reviewer before closing the ticket.
 
 ## Guardrail
 
-`checklist.md` → 1, 4 (branch-pattern, all-tasks-done)
+`checklist.md` → 0, 1, 2, 4 (nova-installed, branch-pattern, proposal-exists, all-tasks-done)
 
 ## Steps
 

package/novaspec/commands/nova-spec.md

@@ -6,7 +6,7 @@ You are responsible for generating the technical spec of the current ticket.
 
 ## Guardrail
 
-`checklist.md` → 1 (branch-pattern)
+`checklist.md` → 0, 1 (nova-installed, branch-pattern)
 
 ## Precondition
 

package/novaspec/config.example.yml

@@ -15,10 +15,18 @@ branch:
   ticket_case: upper    # upper | lower
   base: main            # base branch of the flow
 
+forge:
+  type: auto            # auto | github | gitlab | none
+  cli: auto             # auto | gh | glab
+
+ticket_system: jira     # jira | none
+
 jira:
-  skill: ""                        # set to "jira-integration" to enable Jira
+  skill: jira-integration            # set to "" to disable Jira
   url: https://your-workspace.atlassian.net
   project: PROJ
   email: you@example.com
-  token: ${JIRA_API_TOKEN}         # create at id.atlassian.com/manage-profile/security/api-tokens
-  done_transition_id: "41"         # find via GET /rest/api/3/issue/<TICKET>/transitions
+  token: ${JIRA_API_TOKEN}            # create at id.atlassian.com/manage-profile/security/api-tokens
+  done_transition_id: "41"            # legacy, kept for backward-compat fallback
+  transitions:
+    done: "41"                        # structured form — read first by /nova-wrap

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nova-spec",
-  "version": "1.0.6",
+  "version": "1.0.7",
   "description": "Spec-Driven Development framework for Claude Code and OpenCode",
   "bin": {
     "nova-spec": "bin/nova-spec.js"