create-quiver 0.9.1 → 0.12.0

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

@@ -0,0 +1,451 @@
+const fs = require('fs');
+const path = require('path');
+
+function formatError(message) {
+  return `create-quiver: ${message}`;
+}
+
+function toProjectSlug(projectName) {
+  return projectName
+    .normalize('NFKD')
+    .replace(/[\u0300-\u036f]/g, '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '') || 'quiver-project';
+}
+
+function toRelativePath(relativePath) {
+  return relativePath.split(path.sep).join('/');
+}
+
+const CORE_VISIBLE_DIRECTORIES = ['docs', 'docs/ai', '.quiver', '.quiver/scans'];
+const MINIMAL_VISIBLE_FILES = [
+  'README.md',
+  'AGENTS.md',
+  '.gitignore',
+  'docs/AI_CONTEXT.md',
+  'docs/AI_ONBOARDING_PROMPT.md',
+  'docs/COMMANDS.md',
+  'docs/WORKFLOW.md',
+  'docs/ai/PRINCIPLES.md',
+  'docs/ai/RULES.yaml',
+  'package.json',
+  '.quiver/state.json',
+  '.quiver/config.json',
+  '.quiver/.gitignore',
+];
+
+const DEFAULT_VISIBLE_EXTRAS = [
+  'docs/CONTEXTO.md',
+  'docs/DECISIONS.md',
+  'docs/INDEX.md',
+  'docs/STATUS.md',
+  'docs/SUPPORT_MATRIX.md',
+  'docs/TROUBLESHOOTING.md',
+  'docs/TESTING_GUIDE_FOR_AI.md',
+  'docs/GITFLOW_PR_GUIDE.md',
+  'docs/ai/LESSONS.md',
+];
+
+const FULL_VISIBLE_EXTRAS = [
+  'docs/SEARCH.md',
+  'docs/MULTI_AGENT_WORKFLOW.md',
+  'docs/MOCK_DATA_GUIDE.md',
+  'docs/UI_STANDARDS.md',
+  'docs/DOCUMENTATION_GUIDE.md',
+  'docs/examples/plan.md',
+  'docs/examples/graph.md',
+  'docs/examples/next.md',
+];
+
+const LEGACY_SCRIPT_FILES = [
+  'tools/scripts/start-slice.sh',
+  'tools/scripts/refresh-active-slices.sh',
+  'tools/scripts/check-slice-readiness.sh',
+  'tools/scripts/check-pr-readiness.sh',
+  'tools/scripts/cleanup-slice.sh',
+  'tools/scripts/check-scope.sh',
+  'tools/scripts/migrate-project.sh',
+];
+
+const FULL_DIRECTORIES = [
+  'docs-template',
+  'docs/examples',
+  'tools/scripts',
+];
+
+function quiverInternalPaths(projectRoot) {
+  const root = path.join(projectRoot, '.quiver');
+
+  return {
+    root,
+    cacheDir: path.join(root, 'cache'),
+    configPath: path.join(root, 'config.json'),
+    gitignorePath: path.join(root, '.gitignore'),
+    runsDir: path.join(root, 'runs'),
+    scansDir: path.join(root, 'scans'),
+    statePath: path.join(root, 'state.json'),
+    templatesDir: path.join(root, 'templates'),
+    worktreesDir: path.join(root, 'worktrees'),
+  };
+}
+
+function buildQuiverInternalGitignore() {
+  return [
+    'cache/',
+    'evidence/',
+    'runs/',
+    'worktrees/',
+    '',
+  ].join('\n');
+}
+
+function buildQuiverConfig(options = {}) {
+  return {
+    layout_version: options.layoutVersion || 1,
+    internal_root: '.quiver',
+    scan_path: '.quiver/scans/PROJECT_SCAN.json',
+    project_map_path: 'docs/PROJECT_MAP.md',
+    templates_path: '.quiver/templates',
+  };
+}
+
+function normalizeInitLayoutOptions(options = {}) {
+  const minimal = options.minimal === true;
+  const full = options.full === true;
+
+  if (minimal && full) {
+    throw new Error(formatError('init: --minimal and --full are mutually exclusive'));
+  }
+
+  return {
+    compatibilityAlias: options.compatibilityAlias === true,
+    dryRun: options.dryRun === true,
+    full,
+    includeTemplates: options.includeTemplates === true,
+    legacyScripts: options.legacyScripts === true,
+    minimal,
+    skipInstall: options.skipInstall === true,
+  };
+}
+
+function resolveInitProfile(normalizedOptions) {
+  if (normalizedOptions.full) {
+    return 'full';
+  }
+
+  if (normalizedOptions.minimal) {
+    return 'minimal';
+  }
+
+  return 'default';
+}
+
+function resolveInitVisibleFiles(profile, projectSlug) {
+  if (profile === 'minimal') {
+    return [...MINIMAL_VISIBLE_FILES];
+  }
+
+  if (profile === 'full') {
+    return [
+      ...MINIMAL_VISIBLE_FILES,
+      ...DEFAULT_VISIBLE_EXTRAS,
+      ...FULL_VISIBLE_EXTRAS,
+      `specs/${projectSlug}/SPEC.md`,
+      `specs/${projectSlug}/HANDOFF.md`,
+      `specs/${projectSlug}/STATUS.md`,
+      `specs/${projectSlug}/EVIDENCE_REPORT.md`,
+      `specs/${projectSlug}/slices/slice-template/slice.json`,
+      `specs/${projectSlug}/slices/slice-template/pr.md.template`,
+    ];
+  }
+
+  return [...MINIMAL_VISIBLE_FILES, ...DEFAULT_VISIBLE_EXTRAS];
+}
+
+function resolveInitVisibleDirectories(profile, projectSlug) {
+  const directories = [...CORE_VISIBLE_DIRECTORIES];
+
+  if (profile === 'full') {
+    directories.push(...FULL_DIRECTORIES);
+    directories.push(`specs/${projectSlug}`);
+    directories.push(`specs/${projectSlug}/slices`);
+    directories.push(`specs/${projectSlug}/slices/slice-template`);
+  }
+
+  return directories;
+}
+
+function resolveInitPackageScripts(profile, options = {}) {
+  const baseScripts = {
+    'quiver:migrate': 'npx create-quiver migrate',
+    'quiver:analyze': 'npx create-quiver analyze',
+    'quiver:flow': 'npx create-quiver flow',
+    'quiver:prepare': 'npx create-quiver prepare',
+    'quiver:plan': 'npx create-quiver plan',
+    'quiver:graph': 'npx create-quiver graph',
+    'quiver:next': 'npx create-quiver next',
+    'quiver:doctor': 'npx create-quiver doctor',
+    'quiver:evidence': 'npx create-quiver evidence',
+    'quiver:ai:agent': 'npx create-quiver ai agent',
+    'quiver:ai:onboard': 'npx create-quiver ai onboard',
+    'quiver:ai:prepare-context': 'npx create-quiver ai prepare-context',
+    'quiver:ai:plan': 'npx create-quiver ai plan',
+    'quiver:ai:review-plan': 'npx create-quiver ai review-plan',
+    'quiver:ai:approve': 'npx create-quiver ai approve',
+    'quiver:ai:prompt-slice': 'npx create-quiver ai prompt-slice',
+    'quiver:ai:execute-slice': 'npx create-quiver ai execute-slice',
+    'quiver:ai:execute-plan': 'npx create-quiver ai execute-plan',
+    'quiver:ai:pr': 'npx create-quiver ai pr',
+    'quiver:ai:doctor': 'npx create-quiver ai doctor',
+    '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:close': 'npx create-quiver spec close',
+    'quiver:start-slice': 'npx create-quiver start-slice',
+    'quiver:check-slice': 'npx create-quiver check-slice',
+    'quiver:check-pr': 'npx create-quiver check-pr',
+    'quiver:check-handoff': 'npx create-quiver check-handoff',
+    'check-handoff': 'npx create-quiver check-handoff',
+    'quiver:cleanup-slice': 'npx create-quiver cleanup-slice',
+    'quiver:check-scope': 'npx create-quiver check-scope',
+    'quiver:refresh-active-slices': 'npx create-quiver refresh-active-slices',
+  };
+
+  if (profile === 'full' || options.legacyScripts === true) {
+    return {
+      ...baseScripts,
+      'check:slice': 'bash tools/scripts/check-slice-readiness.sh',
+      'check:pr': 'bash tools/scripts/check-pr-readiness.sh',
+      'start:slice': 'bash tools/scripts/start-slice.sh',
+      'cleanup:slice': 'bash tools/scripts/cleanup-slice.sh',
+      'check:scope': 'bash tools/scripts/check-scope.sh',
+      'refresh:active-slices': 'bash tools/scripts/refresh-active-slices.sh',
+      migrate: 'bash tools/scripts/migrate-project.sh',
+    };
+  }
+
+  return baseScripts;
+}
+
+function pushPlannedOperation(operations, targetRoot, relativePath, kind, action, reason, profile, category) {
+  const absolutePath = path.join(targetRoot, relativePath);
+  const exists = fs.existsSync(absolutePath);
+  const effectiveAction = exists
+    ? (action === 'update' ? 'update' : 'preserve')
+    : 'create';
+
+  operations.push({
+    action: effectiveAction,
+    category,
+    kind,
+    path: toRelativePath(relativePath),
+    reason,
+    exists,
+    profile,
+  });
+}
+
+function pushStaticOperation(operations, relativePath, kind, action, reason, profile, category) {
+  operations.push({
+    action,
+    category,
+    kind,
+    path: toRelativePath(relativePath),
+    reason,
+    exists: false,
+    profile,
+  });
+}
+
+function buildInitLayout(projectRoot, options = {}) {
+  const normalized = normalizeInitLayoutOptions(options);
+  const profile = resolveInitProfile(normalized);
+  const projectName = options.projectName || path.basename(projectRoot) || 'Quiver Project';
+  const projectSlug = toProjectSlug(projectName);
+  const operations = [];
+  const risks = [];
+
+  const visibleDirectories = resolveInitVisibleDirectories(profile, projectSlug);
+  const visibleFiles = resolveInitVisibleFiles(profile, projectSlug);
+
+  for (const directory of visibleDirectories) {
+    pushPlannedOperation(operations, projectRoot, directory, 'directory', 'create', 'core visible contract directory', profile, 'visible');
+  }
+
+  for (const file of visibleFiles) {
+    const updateMode = file === 'package.json' || file === '.gitignore';
+    pushPlannedOperation(
+      operations,
+      projectRoot,
+      file,
+      'file',
+      updateMode ? 'update' : 'create',
+      updateMode ? 'prepare project metadata or ignored paths' : 'core visible contract file',
+      profile,
+      'visible',
+    );
+  }
+
+  if (profile === 'full') {
+    for (const file of LEGACY_SCRIPT_FILES) {
+      pushStaticOperation(operations, file, 'file', 'create', 'legacy Bash wrapper', profile, 'compatibility');
+    }
+  } else if (normalized.legacyScripts) {
+    for (const file of LEGACY_SCRIPT_FILES) {
+      pushStaticOperation(operations, file, 'file', 'create', 'legacy Bash wrapper', profile, 'compatibility');
+    }
+  }
+
+  if (normalized.includeTemplates) {
+    pushStaticOperation(operations, '.quiver/templates/', 'directory', 'create', 'export packaged templates into .quiver/templates', profile, 'internal');
+  }
+
+  const ignoredPaths = [];
+  if (profile !== 'full') {
+    ignoredPaths.push('docs-template/');
+    if (!normalized.legacyScripts) {
+      ignoredPaths.push('tools/scripts/');
+    }
+    ignoredPaths.push(`specs/${projectSlug}/`);
+  }
+
+  if (!normalized.includeTemplates) {
+    ignoredPaths.push('.quiver/templates/');
+  }
+
+  if (profile !== 'full') {
+    const visibleSet = new Set(visibleFiles);
+    for (const file of resolveInitVisibleFiles('full', projectSlug)) {
+      if (!visibleSet.has(file)) {
+        ignoredPaths.push(file);
+      }
+    }
+  }
+
+  if (normalized.compatibilityAlias) {
+    risks.push('compatibility alias path used: npx create-quiver --name');
+  }
+
+  if (normalized.dryRun) {
+    risks.push('dry-run prints the planned layout only; the write path remains unchanged in this slice');
+  }
+
+  const counts = operations.reduce((acc, operation) => {
+    acc[operation.action] = (acc[operation.action] || 0) + 1;
+    return acc;
+  }, {});
+
+  return {
+    profile,
+    projectName,
+    projectSlug,
+    targetRoot: path.resolve(projectRoot),
+    flags: normalized,
+    operations,
+    ignoredPaths: [...new Set(ignoredPaths)],
+    risks,
+    summary: {
+      create: counts.create || 0,
+      preserve: counts.preserve || 0,
+      update: counts.update || 0,
+      ignore: [...new Set(ignoredPaths)].length,
+    },
+  };
+}
+
+function formatInitLayoutPlan(plan) {
+  const lines = [];
+  const entryPoint = plan.flags.compatibilityAlias ? 'compatibility alias (--name)' : 'explicit init command';
+
+  lines.push('Init dry-run plan');
+  lines.push(`- Project: ${plan.projectName}`);
+  lines.push(`- Slug: ${plan.projectSlug}`);
+  lines.push(`- Target: ${plan.targetRoot}`);
+  lines.push(`- Profile: ${plan.profile}`);
+  lines.push(`- Entry point: ${entryPoint}`);
+  lines.push(`- Planned create: ${plan.summary.create}`);
+  lines.push(`- Planned update: ${plan.summary.update}`);
+  lines.push(`- Planned preserve: ${plan.summary.preserve}`);
+  lines.push(`- Planned ignore: ${plan.summary.ignore}`);
+  lines.push('');
+
+  const grouped = new Map([
+    ['create', []],
+    ['update', []],
+    ['preserve', []],
+    ['ignore', plan.ignoredPaths.map((relativePath) => ({ path: relativePath }))],
+  ]);
+
+  for (const operation of plan.operations) {
+    if (operation.action === 'create' || operation.action === 'update' || operation.action === 'preserve') {
+      grouped.get(operation.action).push(operation);
+    }
+  }
+
+  lines.push('Files and directories to create');
+  if (grouped.get('create').length > 0) {
+    for (const operation of grouped.get('create')) {
+      lines.push(`- ${operation.path}`);
+    }
+  } else {
+    lines.push('- none');
+  }
+
+  lines.push('');
+  lines.push('Files to update');
+  if (grouped.get('update').length > 0) {
+    for (const operation of grouped.get('update')) {
+      lines.push(`- ${operation.path}`);
+    }
+  } else {
+    lines.push('- none');
+  }
+
+  lines.push('');
+  lines.push('Files to preserve');
+  if (grouped.get('preserve').length > 0) {
+    for (const operation of grouped.get('preserve')) {
+      lines.push(`- ${operation.path}`);
+    }
+  } else {
+    lines.push('- none');
+  }
+
+  lines.push('');
+  lines.push('Paths intentionally ignored by this profile');
+  if (grouped.get('ignore').length > 0) {
+    for (const operation of grouped.get('ignore')) {
+      lines.push(`- ${operation.path}`);
+    }
+  } else {
+    lines.push('- none');
+  }
+
+  lines.push('');
+  lines.push('Risks');
+  if (plan.risks.length > 0) {
+    for (const risk of plan.risks) {
+      lines.push(`- ${risk}`);
+    }
+  } else {
+    lines.push('- none');
+  }
+
+  lines.push('');
+  return lines.join('\n');
+}
+
+module.exports = {
+  buildQuiverConfig,
+  buildQuiverInternalGitignore,
+  buildInitLayout,
+  formatInitLayoutPlan,
+  normalizeInitLayoutOptions,
+  resolveInitPackageScripts,
+  resolveInitVisibleDirectories,
+  resolveInitVisibleFiles,
+  quiverInternalPaths,
+  resolveInitProfile,
+  toProjectSlug,
+};

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

@@ -3,7 +3,8 @@ const path = require('path');
 const { branchDelete, catFileExists, currentBranch, fetchBranch, fetchRemote, hasLocalBranch, hasRemoteBranch, lsRemoteHeads, mergeBaseIsAncestor, revListCount, runGit, statusPorcelain, worktreeAdd, worktreeList, worktreePrune, worktreeRemove } = require('./git');
 const { parseJsonWithComments } = require('./json');
 const { writeFrontMatter } = require('./init-docs');
-const { resolveTargetRoot } = require('./paths');
+const { relativePosixPath, resolveTargetRoot } = require('./paths');
+const { ensureSpecSliceZeroComplete } = require('./spec-worktrees');
 const { activeSlicePath, renderActiveSlice, resolveSliceContext, safeBranchName, toAlias, validateSliceMetaForStart, worktreesRootForRepo } = require('./slice');
 
 function ensureDir(dirPath) {
@@ -73,7 +74,7 @@ function writeWorktreeContext(targetWorktree, slice, branchName) {
     '',
     '## Active Slice Brief',
     '',
-    `- ${activeSlicePath(slice.repoRoot)}`,
+    `- ${relativePosixPath(slice.repoRoot, activeSlicePath(slice.repoRoot))}`,
     '',
     '## Constraints',
     '',
@@ -299,6 +300,11 @@ function startSlice(sliceInput, options = {}) {
   const repoRoot = runGit(['rev-parse', '--show-toplevel'], process.cwd());
   const slice = resolveSliceContext(repoRoot, sliceInput);
   slice.repoRoot = repoRoot;
+
+  if (!slice.isBaseline) {
+    ensureSpecSliceZeroComplete(repoRoot, slice.specDirAbs);
+  }
+
   validateSliceMetaForStart(slice);
 
   if (slice.status === 'blocked') {

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

@@ -0,0 +1,117 @@
+const PACKAGE_PREFIX = 'package/';
+
+const SAFETY_RULES = [
+  {
+    code: 'env-file',
+    match(relativePath) {
+      return /(^|\/)\.env($|[./])/.test(relativePath);
+    },
+  },
+  {
+    code: 'npm-credentials',
+    match(relativePath) {
+      return /(^|\/)\.npmrc$/.test(relativePath) || /(^|\/)\.npm(\/|$)/.test(relativePath);
+    },
+  },
+  {
+    code: 'ai-tool-state',
+    match(relativePath) {
+      return /(^|\/)\.(claude|codex|quiver)(\/|$)/.test(relativePath);
+    },
+  },
+  {
+    code: 'worktree-state',
+    match(relativePath) {
+      return /(^|\/)\.worktrees(\/|$)/.test(relativePath);
+    },
+  },
+  {
+    code: 'worktree-context',
+    match(relativePath) {
+      return /(^|\/)WORKTREE_CONTEXT\.md$/.test(relativePath);
+    },
+  },
+  {
+    code: 'demo-output',
+    match(relativePath) {
+      return relativePath === 'quiver-spec-viewer' || relativePath.startsWith('quiver-spec-viewer/');
+    },
+  },
+];
+
+function normalizeTarballPath(inputPath) {
+  return String(inputPath || '')
+    .trim()
+    .replace(/\\/g, '/')
+    .replace(/^\.\//, '')
+    .replace(/\/{2,}/g, '/');
+}
+
+function stripPackagePrefix(inputPath) {
+  const normalizedPath = normalizeTarballPath(inputPath);
+
+  if (normalizedPath.startsWith(PACKAGE_PREFIX)) {
+    return normalizedPath.slice(PACKAGE_PREFIX.length);
+  }
+
+  return normalizedPath;
+}
+
+function collectPackageSafetyViolations(paths) {
+  const violations = [];
+  const seen = new Set();
+
+  for (const rawPath of paths || []) {
+    const normalizedPath = normalizeTarballPath(rawPath);
+    const relativePath = stripPackagePrefix(normalizedPath);
+
+    for (const rule of SAFETY_RULES) {
+      if (!rule.match(relativePath)) {
+        continue;
+      }
+
+      const key = `${rule.code}:${normalizedPath}`;
+      if (seen.has(key)) {
+        continue;
+      }
+
+      seen.add(key);
+      violations.push({
+        code: rule.code,
+        path: normalizedPath,
+      });
+    }
+  }
+
+  return violations;
+}
+
+function formatPackageSafetyViolations(violations) {
+  return violations
+    .map((violation) => `${violation.path} [${violation.code}]`)
+    .join(', ');
+}
+
+function assertPackageSafety(paths) {
+  const violations = collectPackageSafetyViolations(paths);
+
+  if (violations.length === 0) {
+    return {
+      ok: true,
+      violations,
+    };
+  }
+
+  const error = new Error(`PACKAGE_SAFETY_FAILED: unsafe tarball contents detected: ${formatPackageSafetyViolations(violations)}`);
+  error.code = 'PACKAGE_SAFETY_FAILED';
+  error.violations = violations;
+  throw error;
+}
+
+module.exports = {
+  assertPackageSafety,
+  collectPackageSafetyViolations,
+  formatPackageSafetyViolations,
+  normalizeTarballPath,
+  stripPackagePrefix,
+};

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

@@ -4,16 +4,77 @@ function resolveTargetRoot(cwd, targetDir, pathLib = path) {
   return pathLib.resolve(cwd, targetDir);
 }
 
+function normalizeGitBashDrivePath(filePath, pathLib = path) {
+  const value = String(filePath || '');
+  const normalized = value.replace(/\\/g, '/');
+  const withoutNamespace = normalized.replace(/^\/\/\?\/([A-Za-z]:\/)/, '$1');
+  const match = withoutNamespace.match(/^\/([A-Za-z])\/(.*)$/);
+  if (!match) {
+    if (withoutNamespace !== normalized && (pathLib === path.win32 || process.platform === 'win32')) {
+      return withoutNamespace;
+    }
+    return value;
+  }
+
+  if (pathLib !== path.win32 && process.platform !== 'win32') {
+    return value;
+  }
+
+  return `${match[1]}:/${match[2]}`;
+}
+
 function toPosixPath(filePath, pathLib = path) {
-  return filePath.split(pathLib.sep).join('/');
+  return String(filePath).split(pathLib.sep).join('/').replace(/\\/g, '/');
+}
+
+function stripTrailingSlashes(filePath) {
+  const value = String(filePath);
+  if (value === '/') {
+    return value;
+  }
+  if (/^[A-Za-z]:\/+$/.test(value)) {
+    return value.slice(0, 3);
+  }
+  return value.replace(/\/+$/, '');
 }
 
 function relativePosixPath(root, absolutePath, pathLib = path) {
-  return toPosixPath(pathLib.relative(root, absolutePath), pathLib);
+  const normalizedRoot = stripTrailingSlashes(toPosixPath(normalizeGitBashDrivePath(root, pathLib), pathLib));
+  const normalizedAbsolute = stripTrailingSlashes(toPosixPath(normalizeGitBashDrivePath(absolutePath, pathLib), pathLib));
+  const windowsPath = pathLib === path.win32 || process.platform === 'win32';
+  const comparableRoot = windowsPath ? normalizedRoot.toLowerCase() : normalizedRoot;
+  const comparableAbsolute = windowsPath ? normalizedAbsolute.toLowerCase() : normalizedAbsolute;
+
+  if (comparableAbsolute === comparableRoot) {
+    return '';
+  }
+
+  if (comparableAbsolute.startsWith(`${comparableRoot}/`)) {
+    return normalizedAbsolute.slice(normalizedRoot.length + 1);
+  }
+
+  return toPosixPath(pathLib.relative(
+    normalizeGitBashDrivePath(root, pathLib),
+    normalizeGitBashDrivePath(absolutePath, pathLib),
+  ), pathLib);
+}
+
+function specRelativePathFromPath(filePath, pathLib = path) {
+  const normalized = toPosixPath(normalizeGitBashDrivePath(filePath, pathLib), pathLib);
+  const parts = normalized.split('/').filter(Boolean);
+  const specIndex = parts.findIndex((part) => part === 'specs' || part === 'specs-fix');
+
+  if (specIndex === -1 || !parts[specIndex + 1]) {
+    return '';
+  }
+
+  return parts.slice(specIndex).join('/');
 }
 
 module.exports = {
+  normalizeGitBashDrivePath,
   relativePosixPath,
   resolveTargetRoot,
+  specRelativePathFromPath,
   toPosixPath,
 };