create-quiver 0.14.0 → 0.15.0

package/src/create-quiver/lib/agent-profiles.js

@@ -5,7 +5,7 @@ const { assertSupportedProvider, formatProviderList } = require('./ai/providers'
 const { quiverInternalPaths } = require('./init-layout');
 
 const AGENT_PROFILE_ROLES = Object.freeze(['planner', 'executor', 'reviewer', 'doctor']);
-const PROFILE_STATE_VERSION = 1;
+const PROFILE_STATE_VERSION = 2;
 
 function formatError(message) {
   return `create-quiver: ${message}`;
@@ -56,9 +56,46 @@ function emptyProfilesState() {
   return {
     version: PROFILE_STATE_VERSION,
     profiles: {},
+    profile_sets: {},
   };
 }
 
+function profileSetKey(role) {
+  return `${normalizeAgentProfileRole(role)}s`;
+}
+
+function normalizeProfileId(value, fallback = 'default') {
+  const source = String(value || fallback || 'default').trim().toLowerCase();
+  const normalized = source
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+  return normalized || 'default';
+}
+
+function resolveAgentProfileDisplayName(profile = {}) {
+  return profile.displayName || profile.model || profile.provider || profile.role || '';
+}
+
+function normalizeStoredProfile(profile, role, fallbackId = 'default') {
+  const normalizedRole = normalizeAgentProfileRole(role || profile?.role);
+  const provider = profile?.provider ? assertSupportedProvider(profile.provider) : '';
+  const normalized = {
+    id: normalizeProfileId(profile?.id || profile?.label, fallbackId),
+    role: normalizedRole,
+    provider,
+    model: normalizeOptionalText(profile?.model, 'model'),
+    label: normalizeOptionalText(profile?.label, 'label'),
+    displayName: normalizeOptionalText(profile?.displayName || profile?.display_name, 'displayName'),
+    context: normalizeOptionalText(profile?.context, 'context'),
+    default: profile?.default === true,
+    updated_at: profile?.updated_at || '',
+  };
+  if (!normalized.displayName) {
+    normalized.displayName = resolveAgentProfileDisplayName(normalized);
+  }
+  return normalized;
+}
+
 function readAgentProfiles(projectRoot) {
   const filePath = agentProfilesPath(projectRoot);
   if (!fs.existsSync(filePath)) {
@@ -69,6 +106,8 @@ function readAgentProfiles(projectRoot) {
   return {
     version: state.version || PROFILE_STATE_VERSION,
     profiles: state.profiles && typeof state.profiles === 'object' ? state.profiles : {},
+    profile_sets: state.profile_sets && typeof state.profile_sets === 'object' ? state.profile_sets : {},
+    updated_at: state.updated_at || undefined,
   };
 }
 
@@ -80,18 +119,53 @@ function writeAgentProfiles(projectRoot, state) {
 }
 
 function getAgentProfile(projectRoot, role) {
+  const normalizedRole = normalizeAgentProfileRole(role);
+  const profiles = getAgentProfilesForRole(projectRoot, normalizedRole);
+  if (profiles.length === 0) return null;
+  return profiles.find((profile) => profile.default) || profiles[0];
+}
+
+function getAgentProfileById(projectRoot, role, profileId) {
+  const normalizedRole = normalizeAgentProfileRole(role);
+  const normalizedId = normalizeProfileId(profileId);
+  return getAgentProfilesForRole(projectRoot, normalizedRole)
+    .find((profile) => profile.id === normalizedId) || null;
+}
+
+function getAgentProfilesForRole(projectRoot, role) {
   const normalizedRole = normalizeAgentProfileRole(role);
   const state = readAgentProfiles(projectRoot);
-  return state.profiles[normalizedRole] || null;
+  const setKey = profileSetKey(normalizedRole);
+  const fromSet = Array.isArray(state.profile_sets[setKey])
+    ? state.profile_sets[setKey].map((profile, index) => normalizeStoredProfile(profile, normalizedRole, index === 0 ? 'default' : `${normalizedRole}-${index + 1}`))
+    : [];
+  const legacy = state.profiles[normalizedRole]
+    ? normalizeStoredProfile({ ...state.profiles[normalizedRole], default: true }, normalizedRole, 'default')
+    : null;
+  const merged = new Map();
+
+  if (legacy) merged.set(legacy.id, legacy);
+  for (const profile of fromSet) {
+    merged.set(profile.id, profile);
+  }
+
+  const profiles = Array.from(merged.values()).filter((profile) => profile.provider);
+  if (profiles.length > 0 && !profiles.some((profile) => profile.default)) {
+    profiles[0].default = true;
+  }
+  return profiles;
 }
 
 function listAgentProfiles(projectRoot) {
-  const state = readAgentProfiles(projectRoot);
-  return AGENT_PROFILE_ROLES.map((role) => ({
-    role,
-    configured: Boolean(state.profiles[role]),
-    profile: state.profiles[role] || null,
-  }));
+  return AGENT_PROFILE_ROLES.map((role) => {
+    const profiles = getAgentProfilesForRole(projectRoot, role);
+    return {
+      role,
+      configured: profiles.length > 0,
+      profile: profiles.find((profile) => profile.default) || profiles[0] || null,
+      profiles,
+    };
+  });
 }
 
 function setAgentProfile(projectRoot, role, options = {}) {
@@ -109,23 +183,47 @@ function buildAgentProfileState(projectRoot, role, options = {}) {
   const provider = assertSupportedProvider(options.provider);
   const model = normalizeOptionalText(options.model, 'model');
   const label = normalizeOptionalText(options.label, 'label');
+  const displayName = normalizeOptionalText(options.displayName || options.display_name, 'displayName');
   const context = normalizeOptionalText(options.context, 'context');
   const state = readAgentProfiles(projectRoot);
-  const current = state.profiles[normalizedRole] || {};
+  const currentProfiles = getAgentProfilesForRole(projectRoot, normalizedRole);
+  const currentDefault = currentProfiles.find((profile) => profile.default) || currentProfiles[0] || {};
+  const id = normalizeProfileId(options.id || currentDefault.id || label || model || provider);
+  const current = currentProfiles.find((profile) => profile.id === id) || {};
   const now = options.now instanceof Date ? options.now.toISOString() : new Date().toISOString();
+  const shouldBeDefault = options.default === true || currentProfiles.length === 0 || (options.default !== false && current.default === true);
   const profile = {
+    id,
     role: normalizedRole,
     provider,
     model: model || current.model || '',
     label: label || current.label || '',
+    displayName: displayName || current.displayName || model || label || provider,
     context: context || current.context || '',
+    default: shouldBeDefault,
     updated_at: now,
   };
 
   state.version = PROFILE_STATE_VERSION;
+  const setKey = profileSetKey(normalizedRole);
+  const nextProfiles = currentProfiles
+    .filter((item) => item.id !== id)
+    .map((item) => ({
+      ...item,
+      default: shouldBeDefault ? false : item.default === true,
+    }))
+    .concat(profile);
+  if (!nextProfiles.some((item) => item.default)) {
+    nextProfiles[0].default = true;
+  }
+  state.profile_sets = {
+    ...state.profile_sets,
+    [setKey]: nextProfiles,
+  };
+  const defaultProfile = nextProfiles.find((item) => item.default) || profile;
   state.profiles = {
     ...state.profiles,
-    [normalizedRole]: profile,
+    [normalizedRole]: defaultProfile,
   };
   state.updated_at = now;
 
@@ -149,6 +247,9 @@ module.exports = {
   AGENT_PROFILE_ROLES,
   PROFILE_STATE_VERSION,
   agentProfilesPath,
+  getAgentProfileById,
+  getAgentProfilesForRole,
+  resolveAgentProfileDisplayName,
   formatProviderList,
   buildAgentProfileState,
   getAgentProfile,

package/src/create-quiver/lib/ai/context-proposal.js

@@ -0,0 +1,389 @@
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { redactSensitiveLocalValues } = require('./artifacts');
+const { getPreparedContextDocPaths } = require('./context-packs');
+const { contextProposalSchema } = require('./context-proposal.schema');
+const { quiverInternalPaths } = require('../init-layout');
+const {
+  getProjectRelativePathIssue,
+  validateProjectRelativePath,
+} = require('../paths');
+
+const INVALID_PROPOSAL_ARTIFACT_SCHEMA_VERSION = 1;
+
+function formatError(message) {
+  return `create-quiver: ${message}`;
+}
+
+class ContextProposalError extends Error {
+  constructor(message, issues = []) {
+    super(formatError(message));
+    this.name = 'ContextProposalError';
+    this.code = 'AI_CONTEXT_PROPOSAL_INVALID';
+    this.issues = issues;
+    this.safeNextSteps = [
+      'Run deterministic prepare-context without --with-planner if you need the safest fallback.',
+      'Rerun with --with-planner --print-prompt and ask the planner to return only valid JSON.',
+      'Review the blocked paths and keep proposal writes limited to approved docs-only context files.',
+    ];
+  }
+}
+
+function normalizeProposalShape(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    return value;
+  }
+
+  const proposal = { ...value };
+  if (!proposal.docs && Array.isArray(proposal.files)) {
+    proposal.docs = proposal.files;
+    delete proposal.files;
+  }
+  if (proposal.schemaVersion && !proposal.schema_version) {
+    proposal.schema_version = proposal.schemaVersion;
+    delete proposal.schemaVersion;
+  }
+  if (proposal.nextSteps && !proposal.next_steps) {
+    proposal.next_steps = proposal.nextSteps;
+    delete proposal.nextSteps;
+  }
+  if (proposal.omittedPaths && !proposal.omitted_paths) {
+    proposal.omitted_paths = proposal.omittedPaths;
+    delete proposal.omittedPaths;
+  }
+
+  return proposal;
+}
+
+function getAllowedContextProposalPaths() {
+  return getPreparedContextDocPaths();
+}
+
+function classifyDisallowedContextPath(relativePath) {
+  const normalized = String(relativePath || '').replace(/\\/g, '/').toLowerCase();
+
+  if (/^(src|app|apps|packages|lib|server|client|web)\//.test(normalized)) {
+    return 'product-code';
+  }
+  if (/^(package(?:-lock)?|npm-shrinkwrap)\.json$/.test(normalized)
+    || /^pnpm-lock\.yaml$/.test(normalized)
+    || /^yarn\.lock$/.test(normalized)
+    || /^bun\.lockb?$/.test(normalized)) {
+    return 'dependency-or-lockfile';
+  }
+  if (/^(vite|next|webpack|rollup|tsconfig|jsconfig|babel|postcss|tailwind|eslint|prettier|turbo|vercel|netlify|dockerfile|compose)(\.|$)/i.test(normalized)) {
+    return 'build-or-runtime-config';
+  }
+  if (/^(dist|build|coverage|out|generated|gen|artifacts|reports)\//.test(normalized)) {
+    return 'generated-output';
+  }
+  if (/^\.quiver\//.test(normalized)) {
+    return 'quiver-internal-state';
+  }
+  if (!normalized.startsWith('docs/')) {
+    return 'not-a-context-doc';
+  }
+  return 'unapproved-context-doc';
+}
+
+function validateContextProposalPath(filePath, options = {}) {
+  const issue = getProjectRelativePathIssue(filePath, options.pathLib);
+  if (issue) {
+    return {
+      ok: false,
+      path: String(filePath || ''),
+      issue,
+      message: `path must be project-relative and stay inside the repository (issue=${issue})`,
+    };
+  }
+
+  let normalized;
+  try {
+    normalized = validateProjectRelativePath(filePath, 'planner proposal path', options.pathLib);
+  } catch (error) {
+    return {
+      ok: false,
+      path: String(filePath || ''),
+      issue: 'invalid-project-relative-path',
+      message: error.message,
+    };
+  }
+
+  const allowed = new Set(options.allowedPaths || getAllowedContextProposalPaths());
+  if (!allowed.has(normalized)) {
+    const issueName = classifyDisallowedContextPath(normalized);
+    return {
+      ok: false,
+      path: normalized,
+      issue: issueName,
+      message: `path is not approved for planner context writes (${issueName}). Allowed paths: ${Array.from(allowed).join(', ')}`,
+    };
+  }
+
+  return {
+    ok: true,
+    path: normalized,
+  };
+}
+
+function extractBalancedJsonObject(text) {
+  const input = String(text || '');
+  const start = input.indexOf('{');
+  if (start === -1) {
+    return null;
+  }
+
+  let depth = 0;
+  let quote = null;
+  let escaping = false;
+
+  for (let index = start; index < input.length; index += 1) {
+    const char = input[index];
+
+    if (escaping) {
+      escaping = false;
+      continue;
+    }
+    if (char === '\\') {
+      escaping = true;
+      continue;
+    }
+    if (quote) {
+      if (char === quote) {
+        quote = null;
+      }
+      continue;
+    }
+    if (char === '"' || char === "'") {
+      quote = char;
+      continue;
+    }
+    if (char === '{') {
+      depth += 1;
+    }
+    if (char === '}') {
+      depth -= 1;
+      if (depth === 0) {
+        return input.slice(start, index + 1);
+      }
+    }
+  }
+
+  return null;
+}
+
+function parseJsonCandidate(jsonText, source) {
+  try {
+    return {
+      ok: true,
+      source,
+      value: JSON.parse(jsonText),
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      source,
+      error,
+    };
+  }
+}
+
+function parsePlannerProposalJson(text) {
+  const input = String(text || '').trim();
+  if (!input) {
+    throw new ContextProposalError('planner proposal output is empty', [
+      { path: null, issue: 'empty-output', message: 'The planner returned no proposal JSON.' },
+    ]);
+  }
+
+  const direct = parseJsonCandidate(input, 'raw-json');
+  if (direct.ok) {
+    return direct;
+  }
+
+  const fencedMatches = Array.from(input.matchAll(/```(?:json)?\s*([\s\S]*?)```/gi));
+  const parseFailures = [direct];
+  for (const match of fencedMatches) {
+    const parsed = parseJsonCandidate(match[1].trim(), 'fenced-json');
+    if (parsed.ok) {
+      return parsed;
+    }
+    parseFailures.push(parsed);
+  }
+
+  const balanced = extractBalancedJsonObject(input);
+  if (balanced) {
+    const parsed = parseJsonCandidate(balanced, 'embedded-json');
+    if (parsed.ok) {
+      return parsed;
+    }
+    parseFailures.push(parsed);
+  }
+
+  const firstError = parseFailures.find((item) => item.error)?.error;
+  throw new ContextProposalError('planner proposal output is not valid JSON', [
+    {
+      path: null,
+      issue: 'malformed-json',
+      message: firstError ? firstError.message : 'No JSON object or fenced JSON block could be parsed.',
+    },
+  ]);
+}
+
+function mapZodIssues(error) {
+  return error.issues.map((issue) => ({
+    path: issue.path.length > 0 ? issue.path.join('.') : null,
+    issue: issue.code,
+    message: issue.message,
+  }));
+}
+
+function normalizeStrings(values) {
+  return Array.from(new Set((Array.isArray(values) ? values : [])
+    .map((item) => String(item || '').trim())
+    .filter(Boolean)));
+}
+
+function normalizeContextProposal(value, options = {}) {
+  const proposal = normalizeProposalShape(value);
+  const parsed = contextProposalSchema.safeParse(proposal);
+  if (!parsed.success) {
+    throw new ContextProposalError('planner context proposal does not match the required schema', mapZodIssues(parsed.error));
+  }
+
+  const issues = [];
+  const seenPaths = new Set();
+  const docs = [];
+
+  for (const [index, doc] of parsed.data.docs.entries()) {
+    const pathResult = validateContextProposalPath(doc.path, options);
+    if (!pathResult.ok) {
+      issues.push({
+        index,
+        path: pathResult.path,
+        issue: pathResult.issue,
+        message: pathResult.message,
+      });
+      continue;
+    }
+
+    if (seenPaths.has(pathResult.path)) {
+      issues.push({
+        index,
+        path: pathResult.path,
+        issue: 'duplicate-path',
+        message: 'planner proposal contains multiple updates for the same context doc path',
+      });
+      continue;
+    }
+    seenPaths.add(pathResult.path);
+
+    if (doc.action !== 'skip' && !doc.content.trim()) {
+      issues.push({
+        index,
+        path: pathResult.path,
+        issue: 'missing-content',
+        message: 'create/update proposal entries require non-empty content',
+      });
+      continue;
+    }
+
+    docs.push({
+      path: pathResult.path,
+      action: doc.action,
+      content: doc.content,
+      reason: doc.reason,
+      assumptions: normalizeStrings(doc.assumptions),
+      risks: normalizeStrings(doc.risks),
+      source: 'planner-proposal',
+    });
+  }
+
+  if (issues.length > 0) {
+    throw new ContextProposalError('planner context proposal contains unsafe or ambiguous writes', issues);
+  }
+
+  return {
+    schemaVersion: parsed.data.schema_version,
+    kind: parsed.data.kind,
+    summary: parsed.data.summary,
+    assumptions: normalizeStrings(parsed.data.assumptions),
+    risks: normalizeStrings(parsed.data.risks),
+    omittedPaths: normalizeStrings(parsed.data.omitted_paths),
+    nextSteps: normalizeStrings(parsed.data.next_steps),
+    docs,
+    writePlan: docs
+      .filter((doc) => doc.action !== 'skip')
+      .map((doc) => ({
+        path: doc.path,
+        content: doc.content,
+        reason: doc.reason,
+        source: doc.source,
+      })),
+  };
+}
+
+function parseContextProposalOutput(text, options = {}) {
+  const parsed = parsePlannerProposalJson(text);
+  return {
+    ...normalizeContextProposal(parsed.value, options),
+    parseSource: parsed.source,
+  };
+}
+
+function safeArtifactName(now = new Date()) {
+  return `${now.toISOString()
+    .replace(/\.\d{3}Z$/, 'z')
+    .replace(/[^0-9a-z]+/gi, '-')
+    .toLowerCase()
+    .replace(/^-+|-+$/g, '')}-invalid-context-proposal.json`;
+}
+
+function writeInvalidContextProposalArtifact(projectRoot, runId, rawOutput, error, options = {}) {
+  if (!projectRoot) {
+    throw new Error(formatError('missing project root for invalid context proposal artifact'));
+  }
+  if (!runId) {
+    throw new Error(formatError('missing AI run id for invalid context proposal artifact'));
+  }
+
+  const now = options.now || new Date();
+  const artifactDir = path.join(quiverInternalPaths(projectRoot).runsDir, String(runId), 'raw');
+  const filePath = path.join(artifactDir, safeArtifactName(now));
+  const artifact = {
+    schema_version: INVALID_PROPOSAL_ARTIFACT_SCHEMA_VERSION,
+    kind: 'invalid-context-proposal',
+    created_at: now.toISOString(),
+    ok: false,
+    error: {
+      code: error?.code || 'AI_CONTEXT_PROPOSAL_INVALID',
+      message: error?.message || String(error || 'unknown error'),
+      issues: Array.isArray(error?.issues) ? error.issues : [],
+      safe_next_steps: Array.isArray(error?.safeNextSteps) ? error.safeNextSteps : [],
+    },
+    raw_output: redactSensitiveLocalValues(rawOutput, { projectRoot }),
+  };
+
+  fs.mkdirSync(artifactDir, { recursive: true });
+  fs.writeFileSync(filePath, `${JSON.stringify(artifact, null, 2)}\n`);
+
+  return {
+    filePath,
+    path: path.relative(projectRoot, filePath).split(path.sep).join('/'),
+    artifact,
+  };
+}
+
+module.exports = {
+  INVALID_PROPOSAL_ARTIFACT_SCHEMA_VERSION,
+  ContextProposalError,
+  classifyDisallowedContextPath,
+  extractBalancedJsonObject,
+  getAllowedContextProposalPaths,
+  normalizeContextProposal,
+  parseContextProposalOutput,
+  parsePlannerProposalJson,
+  validateContextProposalPath,
+  writeInvalidContextProposalArtifact,
+};

package/src/create-quiver/lib/ai/context-proposal.schema.js

@@ -0,0 +1,31 @@
+const { z } = require('zod');
+
+const CONTEXT_PROPOSAL_SCHEMA_VERSION = 1;
+const MAX_DOC_CONTENT_LENGTH = 400_000;
+
+const contextProposalDocSchema = z.object({
+  path: z.string().trim().min(1, 'doc path is required'),
+  action: z.enum(['create', 'update', 'skip']).default('update'),
+  content: z.string().max(MAX_DOC_CONTENT_LENGTH).default(''),
+  reason: z.string().trim().max(2_000).default('Planner proposed this documentation update.'),
+  assumptions: z.array(z.string().trim().min(1)).default([]),
+  risks: z.array(z.string().trim().min(1)).default([]),
+});
+
+const contextProposalSchema = z.object({
+  schema_version: z.literal(CONTEXT_PROPOSAL_SCHEMA_VERSION).default(CONTEXT_PROPOSAL_SCHEMA_VERSION),
+  kind: z.literal('quiver-context-proposal').default('quiver-context-proposal'),
+  summary: z.string().trim().max(4_000).default(''),
+  assumptions: z.array(z.string().trim().min(1)).default([]),
+  risks: z.array(z.string().trim().min(1)).default([]),
+  docs: z.array(contextProposalDocSchema).min(1, 'at least one docs update is required'),
+  omitted_paths: z.array(z.string().trim().min(1)).default([]),
+  next_steps: z.array(z.string().trim().min(1)).default([]),
+}).strict();
+
+module.exports = {
+  CONTEXT_PROPOSAL_SCHEMA_VERSION,
+  MAX_DOC_CONTENT_LENGTH,
+  contextProposalDocSchema,
+  contextProposalSchema,
+};