create-quiver 0.6.0 → 0.8.0

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

@@ -0,0 +1,195 @@
+const fs = require('fs');
+const path = require('path');
+const { parseJsonWithComments } = require('./json');
+const { resolveTargetRoot, toPosixPath } = require('./paths');
+
+function readJson(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+}
+
+function canonicalizePath(dirPath) {
+  try {
+    return fs.realpathSync(dirPath);
+  } catch {
+    return path.resolve(dirPath);
+  }
+}
+
+function toAlias(ticket) {
+  const parts = String(ticket || '').split('-').filter(Boolean);
+  const prefix = (parts[0] || 'GEN').replace(/[^A-Za-z0-9]/g, '').toUpperCase();
+  const suffix = (parts[parts.length - 1] || '00').replace(/[^A-Za-z0-9]/g, '').toUpperCase();
+  const short = prefix.length <= 3 ? prefix : prefix.slice(0, 3);
+  return `${short || 'GEN'}-${suffix || '00'}`;
+}
+
+function resolveSlicePath(sliceInput) {
+  if (!fs.existsSync(sliceInput)) {
+    throw new Error(`create-quiver: no existe el slice '${sliceInput}'.`);
+  }
+
+  return canonicalizePath(sliceInput);
+}
+
+function readSliceMeta(slicePath) {
+  const json = parseJsonWithComments(fs.readFileSync(slicePath, 'utf8'));
+  const ticket = typeof json.ticket === 'string' ? json.ticket.trim() : '';
+  const git = json.git ?? {};
+  const branchType = typeof git.branch_type === 'string' ? git.branch_type.trim() : '';
+  const baseBranch = typeof git.base_branch === 'string' ? git.base_branch.trim() : '';
+  const branchSlug = typeof git.branch_slug === 'string' ? git.branch_slug.trim() : '';
+  const branchName = typeof git.branch_name === 'string' ? git.branch_name.trim() : '';
+  const sliceId = typeof json.slice_id === 'string' ? json.slice_id.trim() : '';
+  const status = String(json.status || 'draft').trim() || 'draft';
+
+  return {
+    acceptance: Array.isArray(json.acceptance) ? json.acceptance : [],
+    baseBranch,
+    branchName,
+    branchSlug,
+    branchType,
+    files: Array.isArray(json.files) ? json.files : [],
+    git,
+    isBaseline: sliceId.startsWith('slice-00'),
+    json,
+    sliceId,
+    slicePath,
+    specFamily: null,
+    specSlug: null,
+    status,
+    tests: Array.isArray(json.tests) ? json.tests : [],
+    ticket,
+  };
+}
+
+function validateSliceMetaForStart(slice) {
+  if (!slice.sliceId) {
+    throw new Error('create-quiver: falta "slice_id" en el slice.');
+  }
+  if (!slice.ticket) {
+    throw new Error('create-quiver: falta "ticket" en el slice.');
+  }
+  if (!slice.branchType || !slice.baseBranch || !slice.branchSlug || !slice.branchName) {
+    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',
+  };
+
+  if (!expectedBaseByType[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 expectedBranchName = `${slice.branchType}/${slice.ticket}-${slice.branchSlug}`;
+  if (slice.branchName !== expectedBranchName) {
+    throw new Error(`create-quiver: git.branch_name invalido. Esperado: "${expectedBranchName}".`);
+  }
+}
+
+function resolveSliceContext(repoRoot, slicePath) {
+  const absSlicePath = resolveSlicePath(slicePath);
+  const relSlicePath = toPosixPath(path.relative(repoRoot, absSlicePath));
+  const parts = relSlicePath.split('/');
+
+  if (parts[0] !== 'specs' && parts[0] !== 'specs-fix') {
+    throw new Error('create-quiver: el slice debe vivir dentro de specs/ o specs-fix/.');
+  }
+
+  const specFamily = parts[0];
+  const specSlug = parts[1];
+  const specDirRel = `${specFamily}/${specSlug}`;
+  const specDirAbs = path.join(repoRoot, specDirRel);
+  const slice = readSliceMeta(absSlicePath);
+  slice.specFamily = specFamily;
+  slice.specSlug = specSlug;
+  slice.specDirRel = specDirRel;
+  slice.specDirAbs = specDirAbs;
+  slice.sliceRel = relSlicePath;
+  slice.sliceAbs = absSlicePath;
+  slice.prPath = path.join(path.dirname(absSlicePath), 'pr.md');
+  return slice;
+}
+
+function activeSlicePath(repoRoot) {
+  return path.join(repoRoot, 'docs', 'ai', 'ACTIVE_SLICE.md');
+}
+
+function renderActiveSlice(slice) {
+  const lines = [
+    '# Active Slice',
+    '',
+    '## Slice ID',
+    '',
+    slice.sliceId || 'slice-unknown',
+    '',
+    '## Title',
+    '',
+    slice.json.title || slice.sliceId || 'Untitled slice',
+    '',
+    '## Objective',
+    '',
+    slice.json.objective || 'Sin objetivo declarado.',
+    '',
+    '## allowed_files',
+  ];
+
+  if (Array.isArray(slice.files) && slice.files.length > 0) {
+    for (const file of slice.files) {
+      lines.push(`- ${file}`);
+    }
+  } else {
+    lines.push('- n/a');
+  }
+
+  lines.push('', '## Validation Commands');
+  if (Array.isArray(slice.tests) && slice.tests.length > 0) {
+    for (const command of slice.tests) {
+      lines.push(`- ${command}`);
+    }
+  } else {
+    lines.push('- n/a');
+  }
+
+  lines.push('', '## Definition of Done');
+  if (Array.isArray(slice.acceptance) && slice.acceptance.length > 0) {
+    for (const item of slice.acceptance) {
+      lines.push(`- ${item}`);
+    }
+  } else {
+    lines.push('- n/a');
+  }
+
+  lines.push('', '## Prohibition', '', 'Do not edit any file outside allowed_files.', '');
+
+  return `${lines.join('\n')}\n`;
+}
+
+function worktreesRootForRepo(repoRoot, branchName) {
+  const repoName = path.basename(repoRoot);
+  const repoParent = path.dirname(repoRoot);
+  return process.env.SLICE_WORKTREES_DIR || path.join(repoParent, '.worktrees', repoName);
+}
+
+function safeBranchName(branchName) {
+  return String(branchName || '').replace(/[^A-Za-z0-9._-]/g, '-');
+}
+
+module.exports = {
+  canonicalizePath,
+  readSliceMeta,
+  resolveSliceContext,
+  safeBranchName,
+  activeSlicePath,
+  renderActiveSlice,
+  toAlias,
+  validateSliceMetaForStart,
+  worktreesRootForRepo,
+};

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

@@ -0,0 +1,139 @@
+const fs = require('fs');
+const path = require('path');
+
+function statePath(projectRoot) {
+  return path.join(projectRoot, '.quiver', 'state.json');
+}
+
+function ensureDir(dirPath) {
+  fs.mkdirSync(dirPath, { recursive: true });
+}
+
+function readState(projectRoot) {
+  const filePath = statePath(projectRoot);
+
+  if (!fs.existsSync(filePath)) {
+    return null;
+  }
+
+  return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+}
+
+function hasInitializedStateMetadata(state) {
+  return Boolean(
+    state
+    && typeof state.initialized_version === 'string'
+    && state.initialized_version.length > 0
+    && typeof state.last_initialized_at === 'string'
+    && state.last_initialized_at.length > 0,
+  );
+}
+
+function hasGeneratedProjectSpec(projectRoot) {
+  const specsDir = path.join(projectRoot, 'specs');
+  if (!fs.existsSync(specsDir)) {
+    return false;
+  }
+
+  return fs.readdirSync(specsDir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .filter((entry) => entry !== '[project-name]' && !entry.startsWith('quiver-'))
+    .some((entry) => (
+      fs.existsSync(path.join(specsDir, entry, 'SPEC.md'))
+      && fs.existsSync(path.join(specsDir, entry, 'STATUS.md'))
+      && fs.existsSync(path.join(specsDir, entry, 'EVIDENCE_REPORT.md'))
+      && fs.existsSync(path.join(specsDir, entry, 'slices', 'slice-template', 'slice.json'))
+    ));
+}
+
+function hasLegacyQuiverInitializationEvidence(projectRoot) {
+  const requiredPaths = [
+    'docs-template/scripts/init-docs.sh',
+    'tools/scripts/start-slice.sh',
+    'tools/scripts/check-slice-readiness.sh',
+    '.github/pull_request_template.md',
+    'docs/INDEX.md',
+  ];
+
+  return requiredPaths.every((relativePath) => fs.existsSync(path.join(projectRoot, relativePath)))
+    && hasGeneratedProjectSpec(projectRoot);
+}
+
+function hasQuiverInitializationEvidence(projectRoot) {
+  const state = readState(projectRoot);
+  return hasInitializedStateMetadata(state) || hasLegacyQuiverInitializationEvidence(projectRoot);
+}
+
+function writeState(projectRoot, nextState) {
+  const stateDir = path.join(projectRoot, '.quiver');
+  ensureDir(stateDir);
+  fs.writeFileSync(statePath(projectRoot), `${JSON.stringify(nextState, null, 2)}\n`);
+  return statePath(projectRoot);
+}
+
+function updateStateForInit(projectRoot, projectName, cliVersion) {
+  const currentState = readState(projectRoot) || {};
+  const now = new Date().toISOString();
+  const nextState = {
+    ...currentState,
+    quiver_version: cliVersion,
+    project_name: projectName || currentState.project_name || '',
+    initialized_version: currentState.initialized_version || cliVersion,
+    migrated_version: currentState.migrated_version ?? null,
+    last_initialized_at: currentState.last_initialized_at || now,
+    last_migration_at: currentState.last_migration_at ?? null,
+    last_analysis_at: currentState.last_analysis_at ?? null,
+  };
+
+  writeState(projectRoot, nextState);
+  return nextState;
+}
+
+function updateStateForMigrate(projectRoot, projectName, cliVersion) {
+  const currentState = readState(projectRoot) || {};
+  const now = new Date().toISOString();
+  const nextState = {
+    ...currentState,
+    quiver_version: cliVersion,
+    project_name: projectName || currentState.project_name || '',
+    initialized_version: currentState.initialized_version ?? null,
+    migrated_version: cliVersion,
+    last_initialized_at: currentState.last_initialized_at ?? null,
+    last_migration_at: now,
+    last_analysis_at: currentState.last_analysis_at ?? null,
+  };
+
+  writeState(projectRoot, nextState);
+  return nextState;
+}
+
+function updateStateForAnalyze(projectRoot, cliVersion) {
+  const currentState = readState(projectRoot);
+
+  if (!currentState) {
+    return null;
+  }
+
+  const nextState = {
+    ...currentState,
+    quiver_version: cliVersion,
+    last_analysis_at: new Date().toISOString(),
+  };
+
+  writeState(projectRoot, nextState);
+  return nextState;
+}
+
+module.exports = {
+  hasGeneratedProjectSpec,
+  hasInitializedStateMetadata,
+  hasLegacyQuiverInitializationEvidence,
+  hasQuiverInitializationEvidence,
+  readState,
+  statePath,
+  updateStateForAnalyze,
+  updateStateForInit,
+  updateStateForMigrate,
+  writeState,
+};