create-quiver 0.15.4 → 0.17.0

package/src/create-quiver/lib/ai/analyze-project-schema.js

@@ -0,0 +1,92 @@
+const { z } = require('zod');
+
+const ANALYZE_PROJECT_SCHEMA_VERSION = 1;
+const ANALYZE_PROJECT_KIND = 'quiver-project-analysis';
+const MAX_ANALYZE_DOC_UPDATE_LENGTH = 400_000;
+const CONFIDENCE_LEVELS = ['confirmed', 'inferred', 'unknown', 'conflict'];
+const ALLOWED_ANALYZE_DOC_UPDATE_PATHS = [
+  'docs/CONTEXTO.md',
+  'docs/AI_CONTEXT.md',
+  'docs/ARCHITECTURE.md',
+  'docs/STATUS.md',
+  'docs/DECISIONS.md',
+  'docs/PROJECT_MAP.md',
+];
+
+const confidenceSchema = z.enum(CONFIDENCE_LEVELS);
+const evidencePathSchema = z.string().trim().min(1, 'evidence path is required');
+
+const evidenceClaimSchema = z.object({
+  claim: z.string().trim().min(1, 'claim is required').max(4_000),
+  confidence: confidenceSchema,
+  evidence: z.array(evidencePathSchema).default([]),
+  notes: z.string().trim().max(2_000).default(''),
+}).strict();
+
+const namedFindingSchema = z.object({
+  name: z.string().trim().min(1, 'name is required').max(500),
+  summary: z.string().trim().max(4_000).default(''),
+  confidence: confidenceSchema.default('unknown'),
+  evidence: z.array(evidencePathSchema).default([]),
+}).strict();
+
+const productSchema = z.object({
+  name: namedFindingSchema.optional(),
+  type: namedFindingSchema.optional(),
+  summary: z.string().trim().max(4_000).default(''),
+  claims: z.array(evidenceClaimSchema).default([]),
+}).strict().default({});
+
+const domainSchema = z.object({
+  roles: z.array(namedFindingSchema).default([]),
+  entities: z.array(namedFindingSchema).default([]),
+  actions: z.array(namedFindingSchema).default([]),
+  flows: z.array(namedFindingSchema).default([]),
+  incomplete_or_suspicious: z.array(namedFindingSchema).default([]),
+  claims: z.array(evidenceClaimSchema).default([]),
+}).strict().default({});
+
+const architectureSchema = z.object({
+  frontend: z.array(namedFindingSchema).default([]),
+  backend: z.array(namedFindingSchema).default([]),
+  auth: z.array(namedFindingSchema).default([]),
+  persistence: z.array(namedFindingSchema).default([]),
+  integrations: z.array(namedFindingSchema).default([]),
+  state: z.array(namedFindingSchema).default([]),
+  api: z.array(namedFindingSchema).default([]),
+  testing: z.array(namedFindingSchema).default([]),
+  deploy: z.array(namedFindingSchema).default([]),
+  risks: z.array(namedFindingSchema).default([]),
+  claims: z.array(evidenceClaimSchema).default([]),
+}).strict().default({});
+
+const questionSchema = z.object({
+  question: z.string().trim().min(1, 'question is required').max(2_000),
+  reason: z.string().trim().max(2_000).default(''),
+  evidence: z.array(evidencePathSchema).default([]),
+}).strict();
+
+const analyzeProjectSchema = z.object({
+  schema_version: z.literal(ANALYZE_PROJECT_SCHEMA_VERSION).default(ANALYZE_PROJECT_SCHEMA_VERSION),
+  kind: z.literal(ANALYZE_PROJECT_KIND).default(ANALYZE_PROJECT_KIND),
+  product: productSchema,
+  domain: domainSchema,
+  architecture: architectureSchema,
+  features: z.array(namedFindingSchema).default([]),
+  risks: z.array(namedFindingSchema).default([]),
+  questions: z.array(questionSchema).default([]),
+  claims: z.array(evidenceClaimSchema).default([]),
+  doc_updates: z.record(z.string().trim().min(1), z.string().max(MAX_ANALYZE_DOC_UPDATE_LENGTH)).default({}),
+}).strict();
+
+module.exports = {
+  ALLOWED_ANALYZE_DOC_UPDATE_PATHS,
+  ANALYZE_PROJECT_KIND,
+  ANALYZE_PROJECT_SCHEMA_VERSION,
+  CONFIDENCE_LEVELS,
+  MAX_ANALYZE_DOC_UPDATE_LENGTH,
+  analyzeProjectSchema,
+  confidenceSchema,
+  evidenceClaimSchema,
+  namedFindingSchema,
+};

package/src/create-quiver/lib/ai/analyze-project-validation.js

@@ -0,0 +1,309 @@
+const fs = require('node:fs');
+const path = require('node:path');
+
+const {
+  ANALYZE_MANAGED_END,
+  ANALYZE_MANAGED_START,
+  normalizeAnalyzeProjectDocProposal,
+} = require('./analyze-project-docs');
+const { normalizeAnalyzeProjectAnalysis } = require('./analyze-project-parser');
+
+const VALIDATION_KIND = 'quiver-analyze-project-post-write-validation';
+
+const PLACEHOLDER_PATTERNS = [
+  { issue: 'placeholder-todo', pattern: /\bTODO\b/i },
+  { issue: 'placeholder-fixme', pattern: /\bFIXME\b/i },
+  { issue: 'placeholder-tbd', pattern: /\bTBD\b/i },
+  { issue: 'placeholder-template-token', pattern: /\{\{[^}\n]+\}\}/ },
+  { issue: 'placeholder-bracket-token', pattern: /\[(?:TODO|TBD|PLACEHOLDER|REPLACE|INSERT)[^\]\n]*\]/i },
+  { issue: 'placeholder-angle-token', pattern: /<(?:TODO|TBD|PLACEHOLDER|REPLACE|INSERT)[^>\n]*>/i },
+  { issue: 'placeholder-unfinished', pattern: /to be completed after implementation/i },
+];
+
+const FACT_KEY_ALIASES = new Map([
+  ['app', 'product'],
+  ['application', 'product'],
+  ['auth', 'auth'],
+  ['authentication', 'auth'],
+  ['backend', 'backend'],
+  ['database', 'database'],
+  ['db', 'database'],
+  ['frontend', 'frontend'],
+  ['framework', 'framework'],
+  ['package manager', 'package_manager'],
+  ['package_manager', 'package_manager'],
+  ['persistence', 'database'],
+  ['product', 'product'],
+  ['stack', 'stack'],
+]);
+
+function toPosix(filePath) {
+  return String(filePath || '').replace(/\\/g, '/');
+}
+
+function makeIssue(pathName, issue, message, extra = {}) {
+  return {
+    path: pathName || null,
+    issue,
+    message,
+    ...extra,
+  };
+}
+
+function extractManagedBlock(content) {
+  const text = String(content || '');
+  const start = text.indexOf(ANALYZE_MANAGED_START);
+  const end = text.indexOf(ANALYZE_MANAGED_END);
+  if (start < 0 || end <= start) {
+    return {
+      ok: false,
+      content: '',
+      issue: start < 0 && end < 0 ? 'managed-block-missing' : 'managed-block-unbalanced',
+    };
+  }
+  return {
+    ok: true,
+    content: text.slice(start + ANALYZE_MANAGED_START.length, end),
+    issue: '',
+  };
+}
+
+function readRelativeFile(repoRoot, relativePath) {
+  const normalized = toPosix(relativePath);
+  const absolute = path.resolve(repoRoot, normalized);
+  const repo = path.resolve(repoRoot);
+  const relative = path.relative(repo, absolute);
+  if (relative.startsWith('..') || path.isAbsolute(relative)) {
+    return {
+      ok: false,
+      path: normalized,
+      content: '',
+      issue: 'path-outside-repo',
+      message: `path is outside repository: ${normalized}`,
+    };
+  }
+  if (!fs.existsSync(absolute)) {
+    return {
+      ok: false,
+      path: normalized,
+      content: '',
+      issue: 'missing-written-doc',
+      message: `written doc is missing: ${normalized}`,
+    };
+  }
+  return {
+    ok: true,
+    path: normalized,
+    content: fs.readFileSync(absolute, 'utf8'),
+  };
+}
+
+function collectChangedDocPaths(report) {
+  const fromWritten = Array.isArray(report?.written_docs) ? report.written_docs : [];
+  const fromPlan = Array.isArray(report?.write_plan)
+    ? report.write_plan.filter((item) => item.action && item.action !== 'skip').map((item) => item.path)
+    : [];
+  return [...new Set([...fromWritten, ...fromPlan].map(toPosix).filter(Boolean))].sort();
+}
+
+function addSchemaValidation(report, errors) {
+  try {
+    normalizeAnalyzeProjectAnalysis(report.analysis, {
+      selectedFiles: report.selected_files || [],
+      promptFiles: report.prompt?.files || [],
+    });
+  } catch (error) {
+    for (const issue of error.issues || []) {
+      errors.push(makeIssue(issue.path, issue.issue || 'analysis-schema-invalid', issue.message || error.message));
+    }
+  }
+
+  try {
+    normalizeAnalyzeProjectDocProposal(report.doc_proposal);
+  } catch (error) {
+    for (const issue of error.issues || []) {
+      errors.push(makeIssue(issue.path || issue.pathName, issue.issue || 'doc-proposal-schema-invalid', issue.message || error.message));
+    }
+  }
+}
+
+function addManifestValidation(repoRoot, report, errors) {
+  if (!report?.snapshot?.manifestPath) {
+    errors.push(makeIssue('snapshot.manifestPath', 'snapshot-manifest-missing', 'snapshot manifest path is missing from write report.'));
+    return;
+  }
+
+  const manifest = readRelativeFile(repoRoot, report.snapshot.manifestPath);
+  if (!manifest.ok) {
+    errors.push(makeIssue(manifest.path, manifest.issue, manifest.message));
+    return;
+  }
+
+  try {
+    const parsed = JSON.parse(manifest.content);
+    const expectedPaths = collectChangedDocPaths(report);
+    const manifestPaths = new Set((parsed.entries || []).map((entry) => toPosix(entry.path)));
+    for (const expectedPath of expectedPaths) {
+      if (!manifestPaths.has(expectedPath)) {
+        errors.push(makeIssue(expectedPath, 'snapshot-manifest-entry-missing', `snapshot manifest does not contain an entry for ${expectedPath}.`));
+      }
+    }
+  } catch (error) {
+    errors.push(makeIssue(report.snapshot.manifestPath, 'snapshot-manifest-invalid-json', error.message));
+  }
+}
+
+function addPlaceholderValidation(docPath, managedContent, errors) {
+  for (const { issue, pattern } of PLACEHOLDER_PATTERNS) {
+    if (pattern.test(managedContent)) {
+      errors.push(makeIssue(docPath, issue, `critical placeholder remains in generated managed block: ${issue}`));
+    }
+  }
+}
+
+function normalizeFactValue(value) {
+  return String(value || '')
+    .replace(/[`*_]/g, '')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .replace(/[.;,]+$/g, '')
+    .toLowerCase();
+}
+
+function isUnknownFactValue(value) {
+  const normalized = normalizeFactValue(value);
+  return !normalized
+    || normalized === 'unknown'
+    || normalized === 'none'
+    || normalized === 'n/a'
+    || normalized === 'needs confirmation'
+    || normalized === 'needs_confirmation'
+    || normalized === 'to confirm'
+    || normalized === 'not confirmed';
+}
+
+function extractFactEntries(docPath, managedContent) {
+  const facts = new Map();
+  const lines = String(managedContent || '').split(/\r?\n/);
+
+  for (const [index, rawLine] of lines.entries()) {
+    const line = rawLine
+      .replace(/^#+\s*/, '')
+      .replace(/^[-*]\s*/, '')
+      .trim();
+    const match = line.match(/^([A-Za-z _-]{2,32})\s*:\s*(.+)$/);
+    if (!match) {
+      continue;
+    }
+
+    const rawKey = match[1].trim().toLowerCase().replace(/[-\s]+/g, ' ');
+    const key = FACT_KEY_ALIASES.get(rawKey);
+    if (!key) {
+      continue;
+    }
+
+    const value = match[2].trim();
+    if (isUnknownFactValue(value)) {
+      continue;
+    }
+
+    if (!facts.has(key)) {
+      facts.set(key, []);
+    }
+    facts.get(key).push({
+      path: docPath,
+      line: index + 1,
+      value,
+      normalized: normalizeFactValue(value),
+    });
+  }
+
+  return facts;
+}
+
+function addFactConflicts(docsByPath, warnings, errors, options = {}) {
+  const projectMap = docsByPath.get('docs/PROJECT_MAP.md');
+  if (!projectMap?.managedBlock?.ok) {
+    return;
+  }
+
+  const projectFacts = extractFactEntries('docs/PROJECT_MAP.md', projectMap.managedBlock.content);
+  const contextPaths = ['docs/CONTEXTO.md', 'docs/AI_CONTEXT.md'];
+
+  for (const contextPath of contextPaths) {
+    const contextDoc = docsByPath.get(contextPath);
+    if (!contextDoc?.managedBlock?.ok) {
+      continue;
+    }
+    const contextFacts = extractFactEntries(contextPath, contextDoc.managedBlock.content);
+    for (const [key, entries] of contextFacts.entries()) {
+      const mapEntries = projectFacts.get(key) || [];
+      for (const contextEntry of entries) {
+        for (const mapEntry of mapEntries) {
+          if (contextEntry.normalized === mapEntry.normalized) {
+            continue;
+          }
+          const issue = makeIssue(contextPath, 'deterministic-doc-conflict', `${contextPath} says ${key}=${contextEntry.value}, but docs/PROJECT_MAP.md says ${key}=${mapEntry.value}.`, {
+            key,
+            project_map_value: mapEntry.value,
+            context_value: contextEntry.value,
+          });
+          if (options.strict === true) {
+            errors.push(issue);
+          } else {
+            warnings.push(issue);
+          }
+        }
+      }
+    }
+  }
+}
+
+function validateAnalyzeProjectPostWrite(repoRoot, report, options = {}) {
+  const errors = [];
+  const warnings = [];
+  const checkedDocs = [];
+  const docsByPath = new Map();
+
+  addSchemaValidation(report || {}, errors);
+  addManifestValidation(repoRoot, report || {}, errors);
+
+  for (const docPath of collectChangedDocPaths(report || {})) {
+    const file = readRelativeFile(repoRoot, docPath);
+    checkedDocs.push(docPath);
+    if (!file.ok) {
+      errors.push(makeIssue(file.path, file.issue, file.message));
+      continue;
+    }
+
+    const managedBlock = extractManagedBlock(file.content);
+    docsByPath.set(docPath, {
+      content: file.content,
+      managedBlock,
+    });
+    if (!managedBlock.ok) {
+      errors.push(makeIssue(docPath, managedBlock.issue, `Quiver managed block is missing or unbalanced in ${docPath}.`));
+      continue;
+    }
+    addPlaceholderValidation(docPath, managedBlock.content, errors);
+  }
+
+  addFactConflicts(docsByPath, warnings, errors, { strict: options.strict === true });
+
+  return {
+    schema_version: 1,
+    kind: VALIDATION_KIND,
+    strict: options.strict === true,
+    ok: errors.length === 0,
+    checked_docs: checkedDocs,
+    errors,
+    warnings,
+  };
+}
+
+module.exports = {
+  VALIDATION_KIND,
+  extractFactEntries,
+  extractManagedBlock,
+  validateAnalyzeProjectPostWrite,
+};

package/src/create-quiver/lib/ai/artifacts.js

@@ -33,7 +33,10 @@ function escapeRegExp(value) {
 }
 
 function redactSensitiveLocalValues(text, options = {}) {
-  let result = redactSecrets(text);
+  let result = redactSecrets(text)
+    .replace(/\bsk-[A-Za-z0-9_-]{16,}\b/g, '[REDACTED]')
+    .replace(/\bghp_[A-Za-z0-9_]{16,}\b/g, '[REDACTED]')
+    .replace(/\bgithub_pat_[A-Za-z0-9_]{16,}\b/g, '[REDACTED]');
   const replacements = [];
 
   if (options.projectRoot) {

package/src/create-quiver/lib/ai/github.js

@@ -3,7 +3,7 @@ const os = require('node:os');
 const path = require('node:path');
 const { spawnSync } = require('node:child_process');
 
-const { currentBranch, hasRemote, isCleanWorktree } = require('../git');
+const { currentBranch, hasRemote, isCleanWorktree, resolveBaseBranchName } = require('../git');
 const { createTranslator } = require('../i18n/catalog');
 const { parseJsonWithComments } = require('../json');
 const { formatActionableError } = require('../actionable-error');
@@ -510,7 +510,10 @@ function buildPrCreateArgs(plan) {
 function buildPrCreatePlan(repoRoot, preflightReport, options = {}) {
   const prBody = readPrBody(repoRoot, options.prBodyPath || options.input);
   ensureNoOpenSlicesForPrBody(repoRoot, prBody.path);
-  const baseBranch = String(options.baseBranch || 'main').trim() || 'main';
+  const baseBranch = resolveBaseBranchName(repoRoot, {
+    explicitBaseBranch: options.baseBranch,
+    remote: preflightReport.remote || DEFAULT_REMOTE,
+  });
   const title = String(options.title || '').trim() || extractPrTitle(prBody.body, preflightReport.branchName);
   const plan = {
     baseBranch,

package/src/create-quiver/lib/ai/spec-templates.js

@@ -289,6 +289,25 @@ function buildPrMarkdown(manifest) {
     '',
     'Generate the spec foundation, slice-00, implementation slices, execution plan, and PR body from the approved planning input.',
     '',
+    '## PR Policy',
+    '',
+    '- [ ] One slice only.',
+    '- [ ] Grouped PR exception: at most 2-3 slices, all docs-only, research-only, or low-risk mechanical cleanup.',
+    '- [ ] No behavior changes in a grouped PR.',
+    '- [ ] No mixed docs with UI, backend, refactor, or performance work.',
+    '- [ ] Separate evidence for each included slice.',
+    '- [ ] Whole PR is revertible without leaving partial state.',
+    '',
+    'Individual PR required when the slice includes functional code, UI/UX, Supabase, Edge Functions, auth, storage, preview, performance/code-splitting, refactors, or tests/CI changes that affect gates.',
+    '',
+    '### Merge Policy',
+    '',
+    '- [ ] Human merge expected.',
+    '- [ ] Assisted auto-merge explicitly authorized for this PR or documented category.',
+    '- [ ] Assisted auto-merge conditions met: docs-only or chore-only, low risk, no runtime changes, no production configuration changes, green checks, and no pending comments.',
+    '',
+    'Assisted auto-merge is prohibited for UI, Supabase, Edge Functions, auth, storage, preview, performance, refactors, and changes with doubtful rollback.',
+    '',
     '## Scope',
     '',
     '- `SPEC.md`',

package/src/create-quiver/lib/cli/command-registry.js

@@ -0,0 +1,72 @@
+const SUPPORTED_COMMAND_MODES = new Set([
+  'init',
+  'version',
+  'changelog',
+  'flow',
+  'dashboard',
+  'plan',
+  'graph',
+  'next',
+  'doctor',
+  'prepare',
+  'analyze',
+  'migrate',
+  'slice',
+  'handoff',
+  'start-slice',
+  'check-slice',
+  'check-pr',
+  'check-handoff',
+  'new-handoff',
+  'cleanup-slice',
+  'check-scope',
+  'config',
+  'refresh-active-slices',
+  'spec',
+  'evidence',
+  'demo',
+  'ai',
+]);
+
+const SUPPORTED_AI_COMMANDS = new Set([
+  'active-slice',
+  'agent',
+  'analyze-project',
+  'approve',
+  'approval-status',
+  'approvals',
+  'doctor',
+  'execute-plan',
+  'execute-slice',
+  'executor-prompt',
+  'export',
+  'inspect',
+  'onboard',
+  'plan',
+  'prepare-context',
+  'pr',
+  'prompt-slice',
+  'repair-plan',
+  'review-plan',
+  'revise',
+  'resume',
+  'run',
+  'slices',
+  'specs',
+  'status',
+  'trace',
+]);
+
+const SUPPORTED_SPEC_COMMANDS = new Set(['close', 'create', 'start', 'status', 'validate']);
+const SUPPORTED_DEMO_COMMANDS = new Set(['create']);
+const SUPPORTED_CONFIG_SECTIONS = new Set(['language']);
+const SUPPORTED_CONFIG_LANGUAGE_COMMANDS = new Set(['show', 'set']);
+
+module.exports = {
+  SUPPORTED_AI_COMMANDS,
+  SUPPORTED_COMMAND_MODES,
+  SUPPORTED_CONFIG_LANGUAGE_COMMANDS,
+  SUPPORTED_CONFIG_SECTIONS,
+  SUPPORTED_DEMO_COMMANDS,
+  SUPPORTED_SPEC_COMMANDS,
+};

package/src/create-quiver/lib/cli/parser.js

@@ -0,0 +1,14 @@
+function parseCliArgs(argv, options = {}) {
+  const legacyParseArgs = options.legacyParseArgs;
+  if (typeof legacyParseArgs !== 'function') {
+    throw new TypeError('parseCliArgs requires a legacyParseArgs adapter');
+  }
+
+  return legacyParseArgs(argv, {
+    language: options.language,
+  });
+}
+
+module.exports = {
+  parseCliArgs,
+};