create-quiver 0.10.0 → 0.12.0

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

@@ -56,7 +56,7 @@ function parseWorktrees(text) {
   return entries;
 }
 
-function collectOverlapWarnings(repoRoot, currentBranchName, currentFiles) {
+function collectOverlapWarnings(repoRoot, currentBranchName, currentFiles, baseRef = 'origin/develop') {
   const sliceMap = new Map();
   walkSlices(path.join(repoRoot, 'specs'), sliceMap, repoRoot);
   walkSlices(path.join(repoRoot, 'specs-fix'), sliceMap, repoRoot);
@@ -79,7 +79,7 @@ function collectOverlapWarnings(repoRoot, currentBranchName, currentFiles) {
     }
 
     const dirty = statusPorcelain(worktreePath) !== '';
-    const aheadCount = revListCount(worktreePath, 'origin/develop..HEAD');
+    const aheadCount = revListCount(worktreePath, `${baseRef}..HEAD`);
     const active = dirty || aheadCount > 0;
 
     if (!active) {
@@ -95,6 +95,65 @@ function collectOverlapWarnings(repoRoot, currentBranchName, currentFiles) {
   return warnings;
 }
 
+function validateLocalSliceArtifacts(repoRoot, slice) {
+  const sliceDir = path.dirname(slice.sliceAbs);
+  for (const file of ['EXECUTION_BRIEF.md', 'CLOSURE_BRIEF.md']) {
+    ensureExists(path.join(sliceDir, file), `create-quiver: falta '${path.posix.join(path.dirname(slice.sliceRel), file)}'.`);
+  }
+  console.log('PASS: El slice local tiene EXECUTION_BRIEF.md y CLOSURE_BRIEF.md.');
+
+  if (!Array.isArray(slice.json.files) || slice.json.files.length === 0) {
+    throw new Error('create-quiver: slice.json debe declarar al menos un archivo en files para validacion local.');
+  }
+
+  const invalidFiles = slice.json.files.filter((file) => typeof file !== 'string' || file.trim().length === 0);
+  if (invalidFiles.length > 0) {
+    throw new Error('create-quiver: slice.json.files contiene entradas invalidas.');
+  }
+  console.log('PASS: slice.json declara archivos de alcance.');
+}
+
+function baseRecoveryMessage(remote, baseBranch) {
+  return `No se encontro la base '${baseBranch}' como rama local ni como '${remote}/${baseBranch}'. Para validacion estructural usa --local; para validacion contra otra base usa --base <branch>; o configura/fetchea el remoto '${remote}'.`;
+}
+
+function validateSliceDocumentedOnBase(repoRoot, slice, options = {}) {
+  const gate = options.gate || 'execution';
+  const remote = options.remote || 'origin';
+  const baseBranch = options.baseBranch || slice.baseBranch || 'develop';
+  const remoteRef = `${remote}/${baseBranch}`;
+  const hasRemoteBase = hasRemoteBranch(repoRoot, baseBranch, remote);
+  const hasLocalBase = hasLocalBranch(repoRoot, baseBranch);
+
+  if (hasRemoteBase && catFileExists(repoRoot, `${remoteRef}:${slice.sliceRel}`)) {
+    console.log(`PASS: El slice ya existe en ${remoteRef} (PR base documental mergeado).`);
+    return remoteRef;
+  }
+
+  if (hasLocalBase && catFileExists(repoRoot, `${baseBranch}:${slice.sliceRel}`)) {
+    console.log(`PASS: El slice ya existe en ${baseBranch} local (modo sin remote).`);
+    return baseBranch;
+  }
+
+  if (!hasRemoteBase && !hasLocalBase) {
+    const guidance = baseRecoveryMessage(remote, baseBranch);
+    if (gate === 'validation') {
+      console.log(`WARN: ${guidance}`);
+      return null;
+    }
+
+    throw new Error(`create-quiver: ${guidance}`);
+  }
+
+  const expectedBase = hasRemoteBase ? remoteRef : baseBranch;
+  if (gate === 'validation') {
+    console.log(`WARN: El slice no existe todavia en ${expectedBase}. El PR base documental sigue pendiente de merge. Podes abrir el PR del slice igual si el humano mergea en orden.`);
+    return expectedBase;
+  }
+
+  throw new Error(`create-quiver: el slice no existe en ${expectedBase}. Mergea primero el PR base documental o usa --local para validar solo estructura local.`);
+}
+
 function validateDeclaredDependencyContract(repoRoot, slice) {
   const declaredDependsOn = Array.isArray(slice.json.depends_on) ? slice.json.depends_on : null;
   const declaredParallelSafe = typeof slice.json.parallel_safe === 'string' ? slice.json.parallel_safe.trim() : '';
@@ -147,35 +206,43 @@ function validateDeclaredDependencyContract(repoRoot, slice) {
 
 function checkSliceReadiness(sliceInput, options = {}) {
   const gate = options.gate || 'execution';
+  const localMode = options.local === true;
   const strictOverlap = options.strictOverlap === true;
+  const remote = options.remote || 'origin';
   const repoRoot = runGit(['rev-parse', '--show-toplevel'], process.cwd());
   const slice = resolveSliceContext(repoRoot, sliceInput);
+  const baseBranch = options.baseBranch || slice.baseBranch || 'develop';
 
   for (const specFile of ['SPEC.md', 'STATUS.md', 'EVIDENCE_REPORT.md']) {
     ensureExists(path.join(repoRoot, slice.specDirRel, specFile), `create-quiver: falta '${slice.specDirRel}/${specFile}'.`);
   }
   console.log('PASS: El spec local tiene SPEC.md, STATUS.md y EVIDENCE_REPORT.md.');
 
-  if (catFileExists(repoRoot, `origin/develop:${slice.sliceRel}`)) {
-    console.log('PASS: El slice ya existe en origin/develop (PR base documental mergeado).');
-  } else if (catFileExists(repoRoot, `develop:${slice.sliceRel}`)) {
-    console.log('PASS: El slice ya existe en develop local (modo sin origin).');
-  } else if (gate === 'validation') {
-    console.log('WARN: El slice no existe todavia en origin/develop. El PR base documental sigue pendiente de merge. Podes abrir el PR del slice igual — el humano mergea en orden.');
+  let baseRef = null;
+  if (localMode) {
+    validateLocalSliceArtifacts(repoRoot, slice);
+    console.log(`INFO: Modo local: se omite validacion de existencia del slice en ${remote}/${baseBranch} o ${baseBranch}.`);
+    console.log('INFO: Modo local: se omite validacion de overlap contra worktrees activos basada en rama remota/base.');
   } else {
-    throw new Error('create-quiver: el slice no existe en origin/develop. Mergea primero el PR base documental.');
+    baseRef = validateSliceDocumentedOnBase(repoRoot, slice, {
+      baseBranch,
+      gate,
+      remote,
+    });
   }
 
-  const overlapWarnings = collectOverlapWarnings(repoRoot, currentBranch(repoRoot), slice.files);
-  if (overlapWarnings.length === 0) {
-    console.log('PASS: No se detecto overlap con worktrees activos.');
-  } else {
-    for (const warning of overlapWarnings) {
-      const [overlapBranch, overlapFiles] = warning.split('|');
-      if (strictOverlap) {
-        throw new Error(`create-quiver: Overlap con worktree activo '${overlapBranch}': ${overlapFiles}`);
+  if (!localMode) {
+    const overlapWarnings = collectOverlapWarnings(repoRoot, currentBranch(repoRoot), slice.files, baseRef || `${remote}/${baseBranch}`);
+    if (overlapWarnings.length === 0) {
+      console.log('PASS: No se detecto overlap con worktrees activos.');
+    } else {
+      for (const warning of overlapWarnings) {
+        const [overlapBranch, overlapFiles] = warning.split('|');
+        if (strictOverlap) {
+          throw new Error(`create-quiver: Overlap con worktree activo '${overlapBranch}': ${overlapFiles}`);
+        }
+        console.log(`WARN: Overlap con worktree activo '${overlapBranch}': ${overlapFiles}`);
       }
-      console.log(`WARN: Overlap con worktree activo '${overlapBranch}': ${overlapFiles}`);
     }
   }
 

package/src/create-quiver/lib/slice-graph.js

@@ -143,6 +143,7 @@ function readAllSlices(rootDir) {
           parallel_safe: typeof json.parallel_safe === 'string' ? json.parallel_safe : null,
           parallel_safe_reason: typeof json.parallel_safe_reason === 'string' ? json.parallel_safe_reason : null,
           status: typeof json.status === 'string' ? json.status : 'draft',
+          ticket: typeof json.ticket === 'string' ? json.ticket : '',
           title: typeof json.title === 'string' ? json.title : sliceId,
           json,
         });

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

@@ -74,19 +74,19 @@ function validateSliceMetaForStart(slice) {
     throw new Error('create-quiver: el bloque "git" debe incluir "branch_type", "base_branch", "branch_slug" y "branch_name".');
   }
 
-  const expectedBaseByType = {
-    feature: 'develop',
-    bugfix: 'develop',
-    hotfix: 'main',
+  const allowedBaseByType = {
+    feature: ['main', 'develop'],
+    bugfix: ['main', 'develop'],
+    hotfix: ['main'],
   };
 
-  if (!expectedBaseByType[slice.branchType]) {
+  if (!allowedBaseByType[slice.branchType]) {
     throw new Error(`create-quiver: git.branch_type invalido: "${slice.branchType}". Usa "feature", "bugfix" o "hotfix".`);
   }
 
-  const expectedBaseBranch = expectedBaseByType[slice.branchType];
-  if (slice.baseBranch !== expectedBaseBranch) {
-    throw new Error(`create-quiver: git.base_branch invalido para ${slice.branchType}. Esperado: "${expectedBaseBranch}".`);
+  const allowedBaseBranches = allowedBaseByType[slice.branchType];
+  if (!allowedBaseBranches.includes(slice.baseBranch)) {
+    throw new Error(`create-quiver: git.base_branch invalido para ${slice.branchType}. Usa "${allowedBaseBranches.join('" o "')}".`);
   }
 
   const expectedBranchName = `${slice.branchType}/${slice.ticket}-${slice.branchSlug}`;

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

@@ -0,0 +1,349 @@
+const fs = require('fs');
+const path = require('path');
+
+const {
+  currentBranch,
+  fetchRemote,
+  hasLocalBranch,
+  hasRemoteBranch,
+  isCleanWorktree,
+  lsRemoteHeads,
+  mergeBaseIsAncestor,
+  runGit,
+  statusPorcelain,
+  worktreeAdd,
+  worktreeList,
+  worktreePrune,
+  worktreeRemove,
+} = require('./git');
+const { parseJsonWithComments } = require('./json');
+const { safeBranchName, worktreesRootForRepo } = require('./slice');
+
+function formatError(message) {
+  return `create-quiver: ${message}`;
+}
+
+function toPosix(relativePath) {
+  return relativePath.split(path.sep).join('/');
+}
+
+function findSpecDir(repoRoot, specInput) {
+  const value = String(specInput || '').trim();
+  if (!value || value === '.') {
+    throw new Error(formatError('missing spec directory. Use: npx create-quiver spec status specs/<spec-slug>'));
+  }
+
+  const resolved = path.resolve(repoRoot, value);
+  if (!fs.existsSync(path.join(resolved, 'SPEC.md'))) {
+    throw new Error(formatError(`missing SPEC.md in ${toPosix(path.relative(repoRoot, resolved))}`));
+  }
+
+  return resolved;
+}
+
+function listSpecSlices(specDir) {
+  const slicesDir = path.join(specDir, 'slices');
+  if (!fs.existsSync(slicesDir)) {
+    return [];
+  }
+
+  return fs.readdirSync(slicesDir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => {
+      const slicePath = path.join(slicesDir, entry.name, 'slice.json');
+      if (!fs.existsSync(slicePath)) {
+        return null;
+      }
+      const json = parseJsonWithComments(fs.readFileSync(slicePath, 'utf8'));
+      return {
+        id: json.slice_id || entry.name,
+        path: slicePath,
+        status: String(json.status || 'draft'),
+        title: json.title || json.slice_id || entry.name,
+      };
+    })
+    .filter(Boolean)
+    .sort((left, right) => left.id.localeCompare(right.id));
+}
+
+function resolveSpecIdentity(repoRoot, specDir) {
+  const relativeSpecDir = toPosix(path.relative(repoRoot, specDir));
+  const specSlug = path.basename(specDir);
+  const branchName = `feature/${specSlug}`;
+  return {
+    branchName,
+    relativeSpecDir,
+    specSlug,
+    worktreePath: path.join(worktreesRootForRepo(repoRoot, branchName), safeBranchName(branchName)),
+  };
+}
+
+function findExistingWorktree(repoRoot, branchName) {
+  for (const entry of worktreeList(repoRoot)) {
+    const branchRef = entry.branch || '';
+    if (branchRef.replace('refs/heads/', '') === branchName) {
+      return entry.worktree;
+    }
+  }
+  return '';
+}
+
+function resolveBaseRef(repoRoot, preferred = '') {
+  const candidates = [preferred, 'main', 'develop'].filter(Boolean);
+  for (const candidate of candidates) {
+    if (hasLocalBranch(repoRoot, candidate)) {
+      return candidate;
+    }
+    if (hasRemoteBranch(repoRoot, candidate)) {
+      return `origin/${candidate}`;
+    }
+    if (lsRemoteHeads(repoRoot, candidate)) {
+      return `origin/${candidate}`;
+    }
+  }
+  throw new Error(formatError('missing base branch. Expected local or remote main/develop.'));
+}
+
+function resolveMergedBaseRef(repoRoot, preferred = '', remote = 'origin') {
+  const candidates = [preferred, 'main', 'develop'].filter(Boolean);
+  for (const candidate of candidates) {
+    if (hasRemoteBranch(repoRoot, candidate, remote)) {
+      return {
+        baseBranch: candidate,
+        baseRef: `${remote}/${candidate}`,
+        remote,
+      };
+    }
+    if (hasLocalBranch(repoRoot, candidate)) {
+      return {
+        baseBranch: candidate,
+        baseRef: candidate,
+        remote: '',
+      };
+    }
+  }
+  throw new Error(formatError('missing merge base branch. Expected local or remote main/develop.'));
+}
+
+function buildSpecStatus(repoRoot, specInput) {
+  const specDir = findSpecDir(repoRoot, specInput);
+  const identity = resolveSpecIdentity(repoRoot, specDir);
+  const slices = listSpecSlices(specDir);
+  const slice00 = slices.find((slice) => slice.id.startsWith('slice-00')) || null;
+  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;
+
+  return {
+    ...identity,
+    existingWorktree,
+    laterSlicesBlocked,
+    pendingSlices,
+    slice00,
+    slices,
+    specDir,
+    worktreeDirty,
+  };
+}
+
+function formatSpecStatus(status) {
+  const lines = [
+    'Spec worktree status',
+    `Spec: ${status.relativeSpecDir}`,
+    `Branch: ${status.branchName}`,
+    `Worktree: ${status.existingWorktree || status.worktreePath}`,
+    `Worktree dirty: ${status.worktreeDirty ? 'yes' : 'no'}`,
+    `slice-00: ${status.slice00 ? status.slice00.status : 'missing'}`,
+    `Later slices blocked: ${status.laterSlicesBlocked ? 'yes' : 'no'}`,
+    'Pending slices:',
+  ];
+
+  if (status.pendingSlices.length === 0) {
+    lines.push('- none');
+  } else {
+    for (const slice of status.pendingSlices) {
+      lines.push(`- ${slice.id}: ${slice.status}`);
+    }
+  }
+
+  return `${lines.join('\n')}\n`;
+}
+
+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}`));
+    }
+    return {
+      ...identity,
+      baseRef,
+      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 (!isCleanWorktree(repoRoot)) {
+    throw new Error(formatError('current checkout is not clean. Commit or stash before starting a spec worktree.'));
+  }
+
+  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 });
+  }
+
+  return {
+    ...identity,
+    baseRef,
+    currentBranch: currentBranch(repoRoot),
+    reused: false,
+    slice00,
+  };
+}
+
+function formatSpecStartResult(result) {
+  return `${[
+    'Spec worktree ready',
+    `Branch: ${result.branchName}`,
+    `Base: ${result.baseRef}`,
+    `Worktree: ${result.worktreePath}`,
+    `Reused: ${result.reused ? 'yes' : 'no'}`,
+    `slice-00: ${result.slice00 ? result.slice00.status : 'missing'}`,
+  ].join('\n')}\n`;
+}
+
+function closeSpecWorktree(repoRoot, specInput, options = {}) {
+  const specDir = findSpecDir(repoRoot, specInput);
+  const identity = resolveSpecIdentity(repoRoot, specDir);
+  const existingWorktree = findExistingWorktree(repoRoot, identity.branchName);
+  const discard = options.discard === true;
+  const dryRun = options.dryRun === true;
+  const force = options.force === true;
+  const remote = options.remote || 'origin';
+  const base = resolveMergedBaseRef(repoRoot, options.baseBranch, remote);
+
+  if (!existingWorktree) {
+    throw new Error(formatError(`missing spec worktree for branch ${identity.branchName}.`));
+  }
+
+  if (!discard && !isCleanWorktree(existingWorktree)) {
+    throw new Error(formatError(`spec worktree is dirty: ${existingWorktree}. Commit or stash before closing, or pass --discard intentionally.`));
+  }
+
+  if (!discard) {
+    const branch = currentBranch(repoRoot);
+    if (branch !== base.baseBranch) {
+      throw new Error(formatError(`spec close must run from ${base.baseBranch}. Current branch: ${branch || '(detached)'}.`));
+    }
+    if (statusPorcelain(repoRoot) !== '') {
+      throw new Error(formatError('main checkout is dirty. Commit or stash before closing the spec worktree.'));
+    }
+    if (base.remote) {
+      try {
+        fetchRemote(repoRoot, base.remote, [base.baseBranch]);
+      } catch {
+        // Local-only test repos and offline environments can still validate against the current remote ref.
+      }
+    }
+    if (hasLocalBranch(repoRoot, identity.branchName) && !mergeBaseIsAncestor(repoRoot, identity.branchName, base.baseRef)) {
+      throw new Error(formatError(`spec branch ${identity.branchName} is not merged into ${base.baseRef}. Merge the PR before cleanup, or pass --discard intentionally.`));
+    }
+  }
+
+  if (dryRun) {
+    return {
+      ...identity,
+      baseBranch: base.baseBranch,
+      baseRef: base.baseRef,
+      discarded: discard,
+      dryRun: true,
+      pulled: false,
+      remote: base.remote,
+      removed: false,
+      worktreePath: existingWorktree,
+    };
+  }
+
+  worktreeRemove(repoRoot, existingWorktree, force || discard);
+  if (!discard && base.remote) {
+    runGit(['pull', '--ff-only', remote, base.baseBranch], repoRoot);
+  }
+
+  return {
+    ...identity,
+    baseBranch: base.baseBranch,
+    baseRef: base.baseRef,
+    discarded: discard,
+    dryRun: false,
+    pulled: !discard && Boolean(base.remote),
+    remote: base.remote,
+    removed: true,
+    worktreePath: existingWorktree,
+  };
+}
+
+function formatSpecCloseResult(result) {
+  const lines = [
+    result.dryRun ? 'Spec close dry-run' : 'Spec worktree closed',
+    `Spec: ${result.relativeSpecDir}`,
+    `Branch: ${result.branchName}`,
+    `Base: ${result.baseRef}`,
+    `Worktree: ${result.worktreePath}`,
+    `Discard: ${result.discarded ? 'yes' : 'no'}`,
+  ];
+
+  if (result.dryRun) {
+    lines.push(`Would remove worktree: ${result.worktreePath}`);
+    if (!result.discarded && result.remote) {
+      lines.push(`Would pull: git pull --ff-only ${result.remote} ${result.baseBranch}`);
+    }
+  } else {
+    lines.push(`Removed worktree: ${result.removed ? 'yes' : 'no'}`);
+    lines.push(`Pulled main checkout: ${result.pulled ? 'yes' : 'no'}`);
+  }
+
+  return `${lines.join('\n')}\n`;
+}
+
+function ensureSpecSliceZeroComplete(repoRoot, specInput) {
+  const status = buildSpecStatus(repoRoot, specInput);
+  if (!status.slice00) {
+    throw new Error(formatError(`spec ${status.relativeSpecDir} requires slice-00 completed before starting later slices; slice-00 is missing.`));
+  }
+  if (status.slice00.status !== 'completed') {
+    throw new Error(formatError(`spec ${status.relativeSpecDir} requires slice-00 completed before starting later slices; current status: ${status.slice00.status}.`));
+  }
+  return status.slice00;
+}
+
+module.exports = {
+  buildSpecStatus,
+  closeSpecWorktree,
+  ensureSpecSliceZeroComplete,
+  findSpecDir,
+  findExistingWorktree,
+  formatSpecCloseResult,
+  formatSpecStartResult,
+  formatSpecStatus,
+  listSpecSlices,
+  resolveBaseRef,
+  resolveMergedBaseRef,
+  resolveSpecIdentity,
+  startSpecWorktree,
+};