create-quiver 0.12.1 → 0.14.0

package/src/create-quiver/lib/spec-worktrees.js

@@ -6,6 +6,8 @@ const {
   fetchRemote,
   hasLocalBranch,
   hasRemoteBranch,
+  isGitWorktree,
+  isLinkedWorktree,
   isCleanWorktree,
   lsRemoteHeads,
   mergeBaseIsAncestor,
@@ -17,6 +19,7 @@ const {
   worktreeRemove,
 } = require('./git');
 const { parseJsonWithComments } = require('./json');
+const { acquireLock, releaseLock, withLockSync } = require('./locks');
 const { safeBranchName, worktreesRootForRepo } = require('./slice');
 
 function formatError(message) {
@@ -88,6 +91,89 @@ function findExistingWorktree(repoRoot, branchName) {
   return '';
 }
 
+function sameRealPath(left, right) {
+  try {
+    return fs.realpathSync(left) === fs.realpathSync(right);
+  } catch {
+    return path.resolve(left) === path.resolve(right);
+  }
+}
+
+function recoveryForMissingWorktree(branchName, worktreePath) {
+  return [
+    `registered spec worktree is missing or stale for ${branchName}: ${worktreePath}`,
+    'Recovery:',
+    '- Run `git worktree prune` from the main checkout, then retry `npx create-quiver spec start specs/<spec-slug>`.',
+    '- If the directory was moved manually, restore it or remove the stale git worktree registration intentionally.',
+    '- Do not create a nested replacement worktree from inside another worktree.',
+  ].join('\n');
+}
+
+function recoveryForNestedWorktree(branchName, existingWorktree = '') {
+  return [
+    `refusing to create a spec worktree from inside a linked worktree for ${branchName}.`,
+    'Recovery:',
+    existingWorktree
+      ? `- Use the existing spec worktree: ${existingWorktree}`
+      : '- Return to the main checkout and rerun the command.',
+    '- This prevents nested .worktrees paths and conflicting persistent spec worktrees.',
+  ].join('\n');
+}
+
+function assertExistingWorktreeUsable(branchName, worktreePath) {
+  if (!worktreePath) {
+    return;
+  }
+  if (!fs.existsSync(worktreePath) || !isGitWorktree(worktreePath)) {
+    throw new Error(formatError(recoveryForMissingWorktree(branchName, worktreePath)));
+  }
+  if (!isCleanWorktree(worktreePath)) {
+    throw new Error(formatError(`existing spec worktree is dirty: ${worktreePath}\nRecovery:\n- Commit or stash changes inside the spec worktree.\n- Then rerun the command.`));
+  }
+}
+
+function parseDirtyStatusFiles(rawStatus) {
+  return String(rawStatus || '')
+    .split('\n')
+    .map((line) => line.trimEnd())
+    .filter(Boolean)
+    .map((line) => {
+      if (line.startsWith('?? ')) {
+        return line.slice(3).trim();
+      }
+      const entry = (line[2] === ' ' ? line.slice(3) : line[1] === ' ' ? line.slice(2) : line.slice(3)).trim();
+      return entry.includes(' -> ') ? entry.split(' -> ').pop().trim() : entry;
+    })
+    .filter(Boolean);
+}
+
+function formatDirtyCheckoutRecovery(repoRoot) {
+  const files = parseDirtyStatusFiles(statusPorcelain(repoRoot));
+  const lines = [
+    'current checkout is not clean. Starting a spec worktree needs a clean main checkout.',
+  ];
+
+  if (files.length > 0) {
+    lines.push('Dirty files:');
+    for (const file of files.slice(0, 20)) {
+      lines.push(`- ${file}`);
+    }
+    if (files.length > 20) {
+      lines.push(`- ...and ${files.length - 20} more`);
+    }
+  }
+
+  lines.push(
+    'Safe options:',
+    '- Commit the current changes if they belong to the active slice.',
+    '- Stash changes manually after reviewing them.',
+    '- Move this work to a separate worktree before starting the spec.',
+    '- Abort and rerun from a clean checkout.',
+  );
+
+  return lines.filter((line) => line !== '').join('\n');
+}
+
 function resolveBaseRef(repoRoot, preferred = '') {
   const candidates = [preferred, 'main', 'develop'].filter(Boolean);
   for (const candidate of candidates) {
@@ -133,7 +219,11 @@ function buildSpecStatus(repoRoot, specInput) {
   const pendingSlices = slices.filter((slice) => slice.status !== 'completed');
   const laterSlicesBlocked = !slice00 || slice00.status !== 'completed';
   const existingWorktree = findExistingWorktree(repoRoot, identity.branchName);
-  const worktreeDirty = existingWorktree ? !isCleanWorktree(existingWorktree) : false;
+  const expectedPathExists = fs.existsSync(identity.worktreePath);
+  const expectedPathUnregistered = Boolean(!existingWorktree && expectedPathExists);
+  const worktreeMissing = Boolean(existingWorktree && (!fs.existsSync(existingWorktree) || !isGitWorktree(existingWorktree)))
+    || expectedPathUnregistered;
+  const worktreeDirty = existingWorktree && !worktreeMissing ? !isCleanWorktree(existingWorktree) : false;
 
   return {
     ...identity,
@@ -144,6 +234,8 @@ function buildSpecStatus(repoRoot, specInput) {
     slices,
     specDir,
     worktreeDirty,
+    worktreeExpectedPathUnregistered: expectedPathUnregistered,
+    worktreeMissing,
   };
 }
 
@@ -153,6 +245,9 @@ function formatSpecStatus(status) {
     `Spec: ${status.relativeSpecDir}`,
     `Branch: ${status.branchName}`,
     `Worktree: ${status.existingWorktree || status.worktreePath}`,
+    `Worktree missing/stale: ${status.worktreeMissing ? 'yes' : 'no'}`,
+    `Worktree registered: ${status.existingWorktree ? 'yes' : 'no'}`,
+    status.worktreeExpectedPathUnregistered ? 'Worktree note: expected path exists but is not registered in git worktree list.' : '',
     `Worktree dirty: ${status.worktreeDirty ? 'yes' : 'no'}`,
     `slice-00: ${status.slice00 ? status.slice00.status : 'missing'}`,
     `Later slices blocked: ${status.laterSlicesBlocked ? 'yes' : 'no'}`,
@@ -173,61 +268,82 @@ function formatSpecStatus(status) {
 function startSpecWorktree(repoRoot, specInput, options = {}) {
   const specDir = findSpecDir(repoRoot, specInput);
   const identity = resolveSpecIdentity(repoRoot, specDir);
-  const existingWorktree = findExistingWorktree(repoRoot, identity.branchName);
   const slices = listSpecSlices(specDir);
   const slice00 = slices.find((slice) => slice.id.startsWith('slice-00')) || null;
   const baseRef = resolveBaseRef(repoRoot, options.baseBranch);
 
-  if (existingWorktree) {
-    if (!isCleanWorktree(existingWorktree)) {
-      throw new Error(formatError(`existing spec worktree is dirty: ${existingWorktree}`));
+  const run = () => {
+    const existingWorktree = findExistingWorktree(repoRoot, identity.branchName);
+    const currentIsLinkedWorktree = isLinkedWorktree(repoRoot);
+
+    if (existingWorktree) {
+      assertExistingWorktreeUsable(identity.branchName, existingWorktree);
+      if (currentIsLinkedWorktree && !sameRealPath(repoRoot, existingWorktree)) {
+        throw new Error(formatError(recoveryForNestedWorktree(identity.branchName, existingWorktree)));
+      }
+      return {
+        ...identity,
+        baseRef,
+        dryRun: options.dryRun === true,
+        reused: true,
+        slice00,
+        worktreePath: existingWorktree,
+      };
     }
-    return {
-      ...identity,
-      baseRef,
-      dryRun: options.dryRun === true,
-      reused: true,
-      slice00,
-      worktreePath: existingWorktree,
-    };
-  }
 
-  if (fs.existsSync(identity.worktreePath)) {
-    throw new Error(formatError(`worktree path already exists and is not registered for ${identity.branchName}: ${identity.worktreePath}`));
-  }
+    if (currentIsLinkedWorktree) {
+      throw new Error(formatError(recoveryForNestedWorktree(identity.branchName)));
+    }
 
-  if (!isCleanWorktree(repoRoot)) {
-    throw new Error(formatError('current checkout is not clean. Commit or stash before starting a spec worktree.'));
-  }
+    if (fs.existsSync(identity.worktreePath)) {
+      throw new Error(formatError(`worktree path already exists and is not registered for ${identity.branchName}: ${identity.worktreePath}\nRecovery:\n- Inspect the path and move or remove it intentionally before rerunning.\n- Run \`git worktree list\` to verify registered worktrees.`));
+    }
+
+    if (!isCleanWorktree(repoRoot)) {
+      throw new Error(formatError(formatDirtyCheckoutRecovery(repoRoot)));
+    }
+
+    if (options.dryRun === true) {
+      return {
+        ...identity,
+        baseRef,
+        currentBranch: currentBranch(repoRoot),
+        dryRun: true,
+        reused: false,
+        slice00,
+      };
+    }
+
+    worktreePrune(repoRoot);
+    fs.mkdirSync(path.dirname(identity.worktreePath), { recursive: true });
+
+    if (hasLocalBranch(repoRoot, identity.branchName)) {
+      worktreeAdd(repoRoot, identity.worktreePath, identity.branchName);
+    } else {
+      worktreeAdd(repoRoot, identity.worktreePath, baseRef, { branch: identity.branchName });
+    }
 
-  if (options.dryRun === true) {
     return {
       ...identity,
       baseRef,
       currentBranch: currentBranch(repoRoot),
-      dryRun: true,
+      dryRun: false,
       reused: false,
       slice00,
     };
-  }
-
-  worktreePrune(repoRoot);
-  fs.mkdirSync(path.dirname(identity.worktreePath), { recursive: true });
+  };
 
-  if (hasLocalBranch(repoRoot, identity.branchName)) {
-    worktreeAdd(repoRoot, identity.worktreePath, identity.branchName);
-  } else {
-    worktreeAdd(repoRoot, identity.worktreePath, baseRef, { branch: identity.branchName });
+  if (options.dryRun === true) {
+    return run();
   }
 
-  return {
-    ...identity,
-    baseRef,
-    currentBranch: currentBranch(repoRoot),
-    dryRun: false,
-    reused: false,
-    slice00,
-  };
+  return withLockSync(repoRoot, `spec-worktree-${identity.specSlug}`, {
+    command: 'spec start',
+    metadata: {
+      branch: identity.branchName,
+      spec: identity.relativeSpecDir,
+    },
+  }, run);
 }
 
 function formatSpecStartResult(result) {
@@ -245,6 +361,14 @@ function formatSpecStartResult(result) {
 function closeSpecWorktree(repoRoot, specInput, options = {}) {
   const specDir = findSpecDir(repoRoot, specInput);
   const identity = resolveSpecIdentity(repoRoot, specDir);
+  const lock = options.dryRun === true ? null : acquireLock(repoRoot, `spec-worktree-${identity.specSlug}`, {
+    command: 'spec close',
+    metadata: {
+      branch: identity.branchName,
+      spec: identity.relativeSpecDir,
+    },
+  });
+  try {
   const existingWorktree = findExistingWorktree(repoRoot, identity.branchName);
   const discard = options.discard === true;
   const dryRun = options.dryRun === true;
@@ -256,6 +380,10 @@ function closeSpecWorktree(repoRoot, specInput, options = {}) {
     throw new Error(formatError(`missing spec worktree for branch ${identity.branchName}.`));
   }
 
+  if (!fs.existsSync(existingWorktree) || !isGitWorktree(existingWorktree)) {
+    throw new Error(formatError(recoveryForMissingWorktree(identity.branchName, existingWorktree)));
+  }
+
   if (!discard && !isCleanWorktree(existingWorktree)) {
     throw new Error(formatError(`spec worktree is dirty: ${existingWorktree}. Commit or stash before closing, or pass --discard intentionally.`));
   }
@@ -310,6 +438,9 @@ function closeSpecWorktree(repoRoot, specInput, options = {}) {
     removed: true,
     worktreePath: existingWorktree,
   };
+  } finally {
+    releaseLock(lock);
+  }
 }
 
 function formatSpecCloseResult(result) {

package/src/create-quiver/lib/statuses.js

@@ -0,0 +1,115 @@
+const CANONICAL_STATUSES = Object.freeze({
+  spec: Object.freeze(['draft', 'planned', 'approved', 'in-progress', 'blocked', 'review', 'done', 'archived']),
+  slice: Object.freeze(['planned', 'ready', 'in-progress', 'blocked', 'review', 'completed', 'skipped']),
+  run: Object.freeze(['draft', 'waiting-approval', 'approved', 'running', 'blocked', 'done', 'failed']),
+  approval: Object.freeze(['pending', 'approved', 'rejected', 'superseded']),
+  agent: Object.freeze(['idle', 'planning', 'reading', 'coding', 'reviewing', 'blocked', 'waiting-approval', 'done']),
+  dataset: Object.freeze(['ready', 'partial', 'empty', 'error']),
+});
+
+const STATUS_ALIASES = Object.freeze({
+  spec: Object.freeze({
+    active: 'in-progress',
+    complete: 'done',
+    completed: 'done',
+    closed: 'done',
+    done: 'done',
+    in_progress: 'in-progress',
+    pending: 'planned',
+  }),
+  slice: Object.freeze({
+    active: 'in-progress',
+    cancelled: 'skipped',
+    canceled: 'skipped',
+    closed: 'completed',
+    complete: 'completed',
+    done: 'completed',
+    draft: 'planned',
+    in_progress: 'in-progress',
+    pending: 'planned',
+  }),
+  run: Object.freeze({
+    active: 'running',
+    closed: 'done',
+    complete: 'done',
+    completed: 'done',
+    in_progress: 'running',
+    pending: 'draft',
+    stale: 'draft',
+  }),
+  approval: Object.freeze({
+    draft: 'pending',
+    review: 'pending',
+    reviewed: 'pending',
+    stale: 'pending',
+    unapproved: 'pending',
+  }),
+  agent: Object.freeze({
+    active: 'coding',
+    complete: 'done',
+    completed: 'done',
+    in_progress: 'coding',
+    waiting_approval: 'waiting-approval',
+  }),
+  dataset: Object.freeze({
+    ok: 'ready',
+    warning: 'partial',
+    missing: 'empty',
+    failed: 'error',
+  }),
+});
+
+function normalizeStatusToken(value) {
+  return String(value || '')
+    .trim()
+    .toLowerCase()
+    .replace(/\s+/g, '-')
+    .replace(/_/g, '-');
+}
+
+function normalizeStatus(kind, status, fallback = 'planned') {
+  const family = String(kind || '').trim().toLowerCase();
+  const catalog = CANONICAL_STATUSES[family];
+  if (!catalog) {
+    return normalizeStatusToken(status) || normalizeStatusToken(fallback);
+  }
+
+  const normalized = normalizeStatusToken(status) || normalizeStatusToken(fallback);
+  const aliasKey = normalized.replace(/-/g, '_');
+  const aliases = STATUS_ALIASES[family] || {};
+  const canonical = aliases[normalized] || aliases[aliasKey] || normalized;
+
+  if (catalog.includes(canonical)) {
+    return canonical;
+  }
+
+  const fallbackStatus = normalizeStatusToken(fallback);
+  return catalog.includes(fallbackStatus) ? fallbackStatus : catalog[0];
+}
+
+function isCompletedStatus(kind, status) {
+  const family = String(kind || '').trim().toLowerCase();
+  const canonical = normalizeStatus(family, status, family === 'slice' ? 'planned' : 'draft');
+
+  if (family === 'slice') {
+    return canonical === 'completed';
+  }
+
+  if (family === 'spec' || family === 'run' || family === 'agent') {
+    return canonical === 'done';
+  }
+
+  return canonical === 'approved';
+}
+
+function isBlockedStatus(kind, status, record = {}) {
+  return normalizeStatus(kind, status, 'planned') === 'blocked' || Boolean(record?.blocked_reason || record?.json?.blocked_reason);
+}
+
+module.exports = {
+  CANONICAL_STATUSES,
+  isBlockedStatus,
+  isCompletedStatus,
+  normalizeStatus,
+};
+