create-quiver 0.12.1 → 0.14.0

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

@@ -1,4 +1,6 @@
 const cp = require('child_process');
+const fs = require('fs');
+const path = require('path');
 
 function runGit(args, cwd, options = {}) {
   return cp.execFileSync('git', args, {
@@ -98,6 +100,9 @@ function currentBranch(repoRoot) {
 }
 
 function statusPorcelain(repoRoot) {
+  if (!repoRoot || !fs.existsSync(repoRoot)) {
+    return '__MISSING_WORKTREE__';
+  }
   return tryGit(['status', '--porcelain'], repoRoot);
 }
 
@@ -111,7 +116,37 @@ function hasRemote(repoRoot, remoteName = 'origin') {
 }
 
 function isCleanWorktree(repoRoot) {
-  return statusPorcelain(repoRoot) === '';
+  return Boolean(repoRoot && fs.existsSync(repoRoot) && isGitWorktree(repoRoot) && statusPorcelain(repoRoot) === '');
+}
+
+function isGitWorktree(repoRoot) {
+  return tryGit(['rev-parse', '--is-inside-work-tree'], repoRoot) === 'true';
+}
+
+function absoluteGitDir(repoRoot) {
+  return tryGit(['rev-parse', '--absolute-git-dir'], repoRoot);
+}
+
+function gitCommonDir(repoRoot) {
+  const value = tryGit(['rev-parse', '--git-common-dir'], repoRoot);
+  if (!value) {
+    return '';
+  }
+  return path.isAbsolute(value) ? path.resolve(value) : path.resolve(repoRoot, value);
+}
+
+function realpathOrResolve(value) {
+  try {
+    return fs.realpathSync(value);
+  } catch {
+    return path.resolve(value);
+  }
+}
+
+function isLinkedWorktree(repoRoot) {
+  const gitDir = absoluteGitDir(repoRoot);
+  const commonDir = gitCommonDir(repoRoot);
+  return Boolean(gitDir && commonDir && realpathOrResolve(gitDir) !== realpathOrResolve(commonDir));
 }
 
 function isDetachedHead(repoRoot) {
@@ -161,8 +196,12 @@ module.exports = {
   lsRemoteHeads,
   mergeBaseIsAncestor,
   hasRemote,
+  absoluteGitDir,
+  gitCommonDir,
   isCleanWorktree,
   isDetachedHead,
+  isGitWorktree,
+  isLinkedWorktree,
   revListCount,
   remoteList,
   runGit,

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

@@ -113,6 +113,46 @@ function validateBriefSections(text, kind) {
     .map((group) => group.label);
 }
 
+function headingGroupsForKind(kind) {
+  if (kind === 'handoff') {
+    return REQUIRED_HEADINGS.map((heading) => ({
+      label: heading.replace(/^##\s+/, '').toLowerCase(),
+      alternatives: [heading],
+    }));
+  }
+  return kind === 'closure-brief' ? CLOSURE_BRIEF_REQUIRED_HEADINGS : EXECUTION_BRIEF_REQUIRED_HEADINGS;
+}
+
+function formatAliasGuidance(kind) {
+  return headingGroupsForKind(kind)
+    .map((group) => `- ${group.label}: ${group.alternatives.join(' | ')}`)
+    .join('\n');
+}
+
+function canonicalHeadingForGroup(group) {
+  return group.alternatives[0] || `## ${group.label}`;
+}
+
+function formatMinimalTemplate(kind) {
+  const lines = [];
+  for (const group of headingGroupsForKind(kind)) {
+    lines.push(canonicalHeadingForGroup(group), '', 'TODO', '');
+  }
+  return lines.join('\n').trimEnd();
+}
+
+function formatMissingSectionsError(resolved, missingSections) {
+  return [
+    `create-quiver: ${resolved.label.toLowerCase()} is missing required sections: ${missingSections.join(', ')}`,
+    '',
+    'Accepted headings/aliases:',
+    formatAliasGuidance(resolved.kind),
+    '',
+    'Minimal template:',
+    formatMinimalTemplate(resolved.kind),
+  ].join('\n');
+}
+
 function checkHandoff(handoffInput, repoRoot = process.cwd()) {
   const resolved = resolveHandoffPath(repoRoot, handoffInput);
 
@@ -125,7 +165,7 @@ function checkHandoff(handoffInput, repoRoot = process.cwd()) {
     ? validateHandoffSections(text)
     : validateBriefSections(text, resolved.kind);
   if (missingSections.length > 0) {
-    throw new Error(`create-quiver: ${resolved.label.toLowerCase()} is missing required sections: ${missingSections.join(', ')}`);
+    throw new Error(formatMissingSectionsError(resolved, missingSections));
   }
 
   return resolved;
@@ -165,6 +205,8 @@ module.exports = {
   EXECUTION_BRIEF_REQUIRED_HEADINGS,
   REQUIRED_HEADINGS,
   checkHandoff,
+  formatAliasGuidance,
+  formatMinimalTemplate,
   readHandoffSections,
   scaffoldHandoff,
   resolveHandoffPath,

package/src/create-quiver/lib/init-docs.js

@@ -1092,6 +1092,15 @@ function installSelfAsDevDep(projectRoot, version) {
     return 'skipped-already-present';
   }
 
+  try {
+    execSync(formatInstallSelfCommand(projectRoot, version), { cwd: projectRoot, stdio: 'inherit' });
+    return 'installed';
+  } catch {
+    return 'failed';
+  }
+}
+
+function formatInstallSelfCommand(projectRoot, version) {
   const pm = detectPackageManager(projectRoot);
   const commands = {
     npm: `npm install -D create-quiver@${version}`,
@@ -1099,13 +1108,7 @@ function installSelfAsDevDep(projectRoot, version) {
     pnpm: `pnpm add -D create-quiver@${version}`,
     bun: `bun add -d create-quiver@${version}`,
   };
-
-  try {
-    execSync(commands[pm], { cwd: projectRoot, stdio: 'inherit' });
-    return 'installed';
-  } catch {
-    return 'failed';
-  }
+  return commands[pm] || commands.npm;
 }
 
 function normalizeSkippedReason(reason) {
@@ -1253,5 +1256,6 @@ module.exports = {
   writeFrontMatter,
   toProjectSlug,
   detectPackageManager,
+  formatInstallSelfCommand,
   installSelfAsDevDep,
 };

package/src/create-quiver/lib/init-layout.js

@@ -209,6 +209,7 @@ function resolveInitPackageScripts(profile, options = {}) {
     'quiver:spec:create': 'npx create-quiver spec create',
     'quiver:spec:start': 'npx create-quiver spec start',
     'quiver:spec:status': 'npx create-quiver spec status',
+    'quiver:spec:validate': 'npx create-quiver spec validate',
     'quiver:spec:close': 'npx create-quiver spec close',
     'quiver:start-slice': 'npx create-quiver start-slice',
     'quiver:check-slice': 'npx create-quiver check-slice',

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

@@ -1,8 +1,9 @@
 const fs = require('fs');
 const path = require('path');
-const { branchDelete, catFileExists, currentBranch, fetchBranch, fetchRemote, hasLocalBranch, hasRemoteBranch, lsRemoteHeads, mergeBaseIsAncestor, revListCount, runGit, statusPorcelain, worktreeAdd, worktreeList, worktreePrune, worktreeRemove } = require('./git');
+const { branchDelete, catFileExists, currentBranch, fetchBranch, fetchRemote, hasLocalBranch, hasRemoteBranch, isGitWorktree, isLinkedWorktree, lsRemoteHeads, mergeBaseIsAncestor, revListCount, runGit, statusPorcelain, worktreeAdd, worktreeList, worktreePrune, worktreeRemove } = require('./git');
 const { parseJsonWithComments } = require('./json');
 const { writeFrontMatter } = require('./init-docs');
+const { withLockSync } = require('./locks');
 const { relativePosixPath, resolveTargetRoot } = require('./paths');
 const { ensureSpecSliceZeroComplete } = require('./spec-worktrees');
 const { activeSlicePath, renderActiveSlice, resolveSliceContext, safeBranchName, toAlias, validateSliceMetaForStart, worktreesRootForRepo } = require('./slice');
@@ -295,6 +296,35 @@ function findExistingWorktreeForBranch(repoRoot, branchName) {
   return '';
 }
 
+function sameRealPath(left, right) {
+  try {
+    return fs.realpathSync(left) === fs.realpathSync(right);
+  } catch {
+    return path.resolve(left) === path.resolve(right);
+  }
+}
+
+function formatMissingSliceWorktree(branchName, worktreePath) {
+  return [
+    `create-quiver: registered slice worktree is missing or stale for ${branchName}: ${worktreePath}`,
+    'Recovery:',
+    '- Run `git worktree prune` from the main checkout, then retry the slice command.',
+    '- 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 formatNestedSliceWorktree(branchName, existingWorktreePath = '') {
+  return [
+    `create-quiver: refusing to create a slice worktree from inside a linked worktree for ${branchName}.`,
+    'Recovery:',
+    existingWorktreePath
+      ? `- Use the existing worktree: ${existingWorktreePath}`
+      : '- Return to the main checkout and rerun the command.',
+    '- This prevents nested .worktrees paths and conflicting slice worktrees.',
+  ].join('\n');
+}
+
 function startSlice(sliceInput, options = {}) {
   const allowDraft = options.allowDraft === true || process.env.ALLOW_DRAFT_SLICE === '1';
   const repoRoot = runGit(['rev-parse', '--show-toplevel'], process.cwd());
@@ -323,13 +353,25 @@ function startSlice(sliceInput, options = {}) {
     console.log('WARN: bootstrap intencional para un slice en draft.');
   }
 
+  return withLockSync(repoRoot, `slice-worktree-${slice.branchName}`, {
+    command: 'start-slice',
+    metadata: {
+      branch: slice.branchName,
+      slice: slice.sliceRel,
+    },
+  }, () => {
   const worktreesRoot = worktreesRootForRepo(repoRoot, slice.branchName);
   const worktreePath = path.join(worktreesRoot, safeBranchName(slice.branchName));
   const existingWorktreePath = findExistingWorktreeForBranch(repoRoot, slice.branchName);
 
-  worktreePrune(repoRoot);
+  if (existingWorktreePath && (!fs.existsSync(existingWorktreePath) || !isGitWorktree(existingWorktreePath))) {
+    throw new Error(formatMissingSliceWorktree(slice.branchName, existingWorktreePath));
+  }
 
-  if (existingWorktreePath && fs.existsSync(existingWorktreePath)) {
+  if (existingWorktreePath) {
+    if (isLinkedWorktree(repoRoot) && !sameRealPath(repoRoot, existingWorktreePath)) {
+      throw new Error(formatNestedSliceWorktree(slice.branchName, existingWorktreePath));
+    }
     writeWorktreeContext(existingWorktreePath, slice, slice.branchName);
     const activeSlice = writeActiveSlice(repoRoot, slice);
     if (activeSlice.replaced) {
@@ -349,6 +391,12 @@ function startSlice(sliceInput, options = {}) {
     return { worktreePath: existingWorktreePath, reused: true };
   }
 
+  if (isLinkedWorktree(repoRoot)) {
+    throw new Error(formatNestedSliceWorktree(slice.branchName));
+  }
+
+  worktreePrune(repoRoot);
+
   if (fs.existsSync(worktreePath) && !fs.existsSync(path.join(worktreePath, '.git'))) {
     throw new Error(`create-quiver: la ruta '${worktreePath}' ya existe y no parece un worktree git.`);
   }
@@ -395,6 +443,7 @@ function startSlice(sliceInput, options = {}) {
   console.log(`Worktree: ${worktreePath}`);
   console.log(`Contexto: ${worktreePath}/WORKTREE_CONTEXT.md`);
   return { worktreePath, reused: false };
+  });
 }
 
 function cleanupSlice(sliceInput, options = {}) {

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

@@ -0,0 +1,134 @@
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+
+const { quiverInternalPaths } = require('./init-layout');
+
+function formatError(message) {
+  return `create-quiver: ${message}`;
+}
+
+function toRelativePosix(root, filePath) {
+  return path.relative(root, filePath).split(path.sep).join('/');
+}
+
+function sanitizeLockName(value) {
+  return String(value || '')
+    .trim()
+    .replace(/[^a-zA-Z0-9._-]+/g, '-')
+    .replace(/^-+|-+$/g, '') || 'operation';
+}
+
+function lockPath(projectRoot, lockName) {
+  return path.join(quiverInternalPaths(projectRoot).locksDir, `${sanitizeLockName(lockName)}.lock`);
+}
+
+function readLock(projectRoot, lockName) {
+  const filePath = lockPath(projectRoot, lockName);
+  if (!fs.existsSync(filePath)) {
+    return null;
+  }
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return {
+      schema_version: 1,
+      lock_name: sanitizeLockName(lockName),
+      command: 'unknown',
+      created_at: 'unknown',
+      pid: 'unknown',
+    };
+  }
+}
+
+function appendUniqueLine(filePath, line) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const current = fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf8') : '';
+  const lines = current.split(/\r?\n/);
+  if (!lines.includes(line)) {
+    const prefix = current.endsWith('\n') || current.length === 0 ? current : `${current}\n`;
+    fs.writeFileSync(filePath, `${prefix}${line}\n`);
+  }
+}
+
+function ensureQuiverStateIgnored(projectRoot) {
+  try {
+    const gitDir = execFileSync('git', ['rev-parse', '--absolute-git-dir'], {
+      cwd: projectRoot,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+    if (gitDir) {
+      appendUniqueLine(path.join(gitDir, 'info', 'exclude'), '.quiver/');
+    }
+  } catch {
+    // Non-git fixtures can still use filesystem locks.
+  }
+}
+
+function acquireLock(projectRoot, lockName, options = {}) {
+  const filePath = lockPath(projectRoot, lockName);
+  const payload = {
+    schema_version: 1,
+    lock_name: sanitizeLockName(lockName),
+    pid: process.pid,
+    hostname: os.hostname(),
+    command: options.command || 'unknown',
+    created_at: (options.now || new Date()).toISOString(),
+    metadata: options.metadata || {},
+  };
+
+  ensureQuiverStateIgnored(projectRoot);
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+
+  try {
+    fs.writeFileSync(filePath, `${JSON.stringify(payload, null, 2)}\n`, { flag: 'wx' });
+  } catch (error) {
+    if (error.code === 'EEXIST') {
+      const existing = readLock(projectRoot, lockName);
+      throw new Error(formatError(`operation is locked: ${toRelativePosix(projectRoot, filePath)}\nLock owner: pid=${existing?.pid || 'unknown'} command=${existing?.command || 'unknown'} created_at=${existing?.created_at || 'unknown'}\nIf this process is gone, inspect the lock and remove it intentionally.`));
+    }
+    throw error;
+  }
+
+  return {
+    filePath,
+    lock: payload,
+    lockName: sanitizeLockName(lockName),
+  };
+}
+
+function releaseLock(handle) {
+  if (handle?.filePath && fs.existsSync(handle.filePath)) {
+    fs.rmSync(handle.filePath);
+  }
+}
+
+function withLockSync(projectRoot, lockName, options, callback) {
+  const handle = acquireLock(projectRoot, lockName, options);
+  try {
+    return callback(handle);
+  } finally {
+    releaseLock(handle);
+  }
+}
+
+async function withLock(projectRoot, lockName, options, callback) {
+  const handle = acquireLock(projectRoot, lockName, options);
+  try {
+    return await callback(handle);
+  } finally {
+    releaseLock(handle);
+  }
+}
+
+module.exports = {
+  acquireLock,
+  lockPath,
+  readLock,
+  releaseLock,
+  sanitizeLockName,
+  withLock,
+  withLockSync,
+};

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

@@ -13,6 +13,12 @@ const SAFETY_RULES = [
       return /(^|\/)\.npmrc$/.test(relativePath) || /(^|\/)\.npm(\/|$)/.test(relativePath);
     },
   },
+  {
+    code: 'ai-raw-artifact',
+    match(relativePath) {
+      return /(^|\/)\.quiver\/runs\/[^/]+\/raw(\/|$)/.test(relativePath);
+    },
+  },
   {
     code: 'ai-tool-state',
     match(relativePath) {
@@ -80,6 +86,7 @@ function collectPackageSafetyViolations(paths) {
         code: rule.code,
         path: normalizedPath,
       });
+      break;
     }
   }
 

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

@@ -1,4 +1,9 @@
 const path = require('path');
+const fs = require('fs');
+
+function formatError(message) {
+  return `create-quiver: ${message}`;
+}
 
 function resolveTargetRoot(cwd, targetDir, pathLib = path) {
   return pathLib.resolve(cwd, targetDir);
@@ -71,10 +76,79 @@ function specRelativePathFromPath(filePath, pathLib = path) {
   return parts.slice(specIndex).join('/');
 }
 
+function realpathOrResolve(filePath, pathLib = path) {
+  try {
+    return pathLib.resolve(fs.realpathSync(filePath));
+  } catch {
+    return pathLib.resolve(normalizeGitBashDrivePath(filePath, pathLib));
+  }
+}
+
+function isPathInsideRoot(root, target, pathLib = path) {
+  const rootPath = realpathOrResolve(root, pathLib);
+  const targetPath = realpathOrResolve(target, pathLib);
+  const windowsPath = pathLib === path.win32 || process.platform === 'win32';
+  const comparableRoot = windowsPath ? rootPath.toLowerCase() : rootPath;
+  const comparableTarget = windowsPath ? targetPath.toLowerCase() : targetPath;
+
+  if (comparableTarget === comparableRoot) {
+    return true;
+  }
+
+  const relative = pathLib.relative(comparableRoot, comparableTarget);
+  return Boolean(relative && !relative.startsWith('..') && !pathLib.isAbsolute(relative));
+}
+
+function assertPathInsideRoot(root, target, label = 'path', pathLib = path) {
+  if (!isPathInsideRoot(root, target, pathLib)) {
+    throw new Error(formatError(`${label} must stay inside the project root: ${toPosixPath(target, pathLib)}`));
+  }
+}
+
+function getProjectRelativePathIssue(filePath, pathLib = path) {
+  const original = String(filePath || '').trim();
+  if (!original) {
+    return 'empty-path';
+  }
+
+  if (/^file:/i.test(original)) {
+    return 'file-url';
+  }
+
+  const normalized = toPosixPath(normalizeGitBashDrivePath(original, pathLib), pathLib);
+  if (normalized.startsWith('/') || /^[A-Za-z]:\//.test(normalized) || pathLib.isAbsolute(original)) {
+    return 'absolute-path';
+  }
+
+  const segments = normalized.split('/').filter(Boolean);
+  if (segments.some((segment) => segment === '..')) {
+    return 'path-traversal';
+  }
+
+  return null;
+}
+
+function validateProjectRelativePath(filePath, fieldName = 'path', pathLib = path) {
+  const issue = getProjectRelativePathIssue(filePath, pathLib);
+  if (issue) {
+    throw new Error(formatError(`${fieldName} must be a project-relative path without traversal (got ${String(filePath || '<empty>')}; issue=${issue}).`));
+  }
+  return toPosixPath(normalizeGitBashDrivePath(String(filePath).trim(), pathLib), pathLib);
+}
+
+function validateProjectRelativePaths(paths, fieldName = 'paths', pathLib = path) {
+  return (Array.isArray(paths) ? paths : []).map((filePath) => validateProjectRelativePath(filePath, fieldName, pathLib));
+}
+
 module.exports = {
+  assertPathInsideRoot,
+  getProjectRelativePathIssue,
+  isPathInsideRoot,
   normalizeGitBashDrivePath,
   relativePosixPath,
   resolveTargetRoot,
   specRelativePathFromPath,
   toPosixPath,
+  validateProjectRelativePath,
+  validateProjectRelativePaths,
 };

package/src/create-quiver/lib/project-scan.js

@@ -49,6 +49,79 @@ function readProjectScanArtifact(projectRoot) {
   return null;
 }
 
+function statIso(filePath) {
+  try {
+    return fs.statSync(filePath).mtime.toISOString();
+  } catch {
+    return null;
+  }
+}
+
+function readProjectScanStatus(projectRoot) {
+  const { currentScanPath, legacyScanPath, projectMapPath } = projectScanPaths(projectRoot);
+  const projectMapExists = fs.existsSync(projectMapPath);
+  let artifact = null;
+  let artifactError = '';
+
+  try {
+    artifact = readProjectScanArtifact(projectRoot);
+  } catch (error) {
+    artifactError = error.message;
+  }
+
+  const scanPath = artifact?.path || (fs.existsSync(currentScanPath) ? currentScanPath : fs.existsSync(legacyScanPath) ? legacyScanPath : '');
+  const source = artifact?.source || (artifactError ? 'invalid' : 'missing');
+  const scanUpdatedAt = scanPath ? statIso(scanPath) : null;
+  const projectMapUpdatedAt = projectMapExists ? statIso(projectMapPath) : null;
+  const stale = Boolean(
+    scanUpdatedAt
+    && projectMapUpdatedAt
+    && Date.parse(projectMapUpdatedAt) + 1000 < Date.parse(scanUpdatedAt),
+  );
+  let status = 'missing';
+
+  if (artifactError) {
+    status = 'invalid';
+  } else if (artifact && projectMapExists && stale) {
+    status = 'stale';
+  } else if (artifact && projectMapExists && source === 'current') {
+    status = 'fresh';
+  } else if (artifact && projectMapExists && source === 'legacy') {
+    status = 'legacy';
+  } else if (artifact || projectMapExists) {
+    status = 'partial';
+  }
+
+  let summary;
+  if (status === 'fresh') {
+    summary = `${artifact.relativePath} (current, updated ${scanUpdatedAt})`;
+  } else if (status === 'legacy') {
+    summary = `${artifact.relativePath} (legacy scan, updated ${scanUpdatedAt})`;
+  } else if (status === 'stale') {
+    summary = `${artifact.relativePath} newer than docs/PROJECT_MAP.md; run analyze to refresh visible context`;
+  } else if (status === 'partial' && artifact && !projectMapExists) {
+    summary = `${artifact.relativePath} exists but docs/PROJECT_MAP.md is missing`;
+  } else if (status === 'partial' && !artifact && projectMapExists) {
+    summary = `docs/PROJECT_MAP.md exists but no scan artifact was found`;
+  } else if (status === 'invalid') {
+    summary = `scan artifact is invalid: ${artifactError}`;
+  } else {
+    summary = 'missing analysis artifacts; run npx create-quiver analyze';
+  }
+
+  return {
+    artifactPath: artifact?.relativePath || (scanPath ? toRelativeScanPath(projectRoot, scanPath) : null),
+    error: artifactError || null,
+    projectMapPath: projectMapExists ? PROJECT_MAP_RELATIVE_PATH : null,
+    projectMapUpdatedAt,
+    scanUpdatedAt,
+    source,
+    status,
+    stale,
+    summary,
+  };
+}
+
 function hasProjectScanArtifact(projectRoot) {
   const { currentScanPath, legacyScanPath } = projectScanPaths(projectRoot);
   return fs.existsSync(currentScanPath) || fs.existsSync(legacyScanPath);
@@ -61,6 +134,7 @@ module.exports = {
   hasProjectScanArtifact,
   projectScanPaths,
   readProjectScanArtifact,
+  readProjectScanStatus,
   toRelativeScanPath,
   writeProjectScanJson,
 };