create-quiver 0.9.1 → 0.12.0

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

@@ -0,0 +1,148 @@
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { assertSupportedProvider, formatProviderList } = require('./ai/providers');
+const { quiverInternalPaths } = require('./init-layout');
+
+const AGENT_PROFILE_ROLES = Object.freeze(['planner', 'executor', 'reviewer', 'researcher']);
+const PROFILE_STATE_VERSION = 1;
+
+function formatError(message) {
+  return `create-quiver: ${message}`;
+}
+
+function agentProfilesPath(projectRoot) {
+  return path.join(quiverInternalPaths(projectRoot).root, 'agents', 'profiles.json');
+}
+
+function normalizeAgentProfileRole(role) {
+  const normalized = String(role || '').trim().toLowerCase();
+  if (!AGENT_PROFILE_ROLES.includes(normalized)) {
+    throw new Error(formatError(`unsupported agent profile role '${role}'. Expected one of: ${AGENT_PROFILE_ROLES.join(', ')}`));
+  }
+  return normalized;
+}
+
+function normalizeOptionalText(value, fieldName) {
+  if (value === undefined || value === null) {
+    return '';
+  }
+
+  const normalized = String(value).trim();
+  if (normalized.length > 160) {
+    throw new Error(formatError(`agent profile ${fieldName} is too long`));
+  }
+
+  assertNotSecretLike(normalized, fieldName);
+  return normalized;
+}
+
+function assertNotSecretLike(value, fieldName) {
+  const text = String(value || '');
+  const secretPatterns = [
+    /-----BEGIN [A-Z ]*PRIVATE KEY-----/,
+    /\bsk-[A-Za-z0-9_-]{16,}\b/,
+    /\bghp_[A-Za-z0-9_]{16,}\b/,
+    /\bgithub_pat_[A-Za-z0-9_]{16,}\b/,
+    /\bxox[baprs]-[A-Za-z0-9-]{16,}\b/,
+  ];
+
+  if (secretPatterns.some((pattern) => pattern.test(text))) {
+    throw new Error(formatError(`agent profile ${fieldName} looks like a secret; store provider credentials in the provider CLI, not in Quiver profiles`));
+  }
+}
+
+function emptyProfilesState() {
+  return {
+    version: PROFILE_STATE_VERSION,
+    profiles: {},
+  };
+}
+
+function readAgentProfiles(projectRoot) {
+  const filePath = agentProfilesPath(projectRoot);
+  if (!fs.existsSync(filePath)) {
+    return emptyProfilesState();
+  }
+
+  const state = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  return {
+    version: state.version || PROFILE_STATE_VERSION,
+    profiles: state.profiles && typeof state.profiles === 'object' ? state.profiles : {},
+  };
+}
+
+function writeAgentProfiles(projectRoot, state) {
+  const filePath = agentProfilesPath(projectRoot);
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, `${JSON.stringify(state, null, 2)}\n`);
+  return filePath;
+}
+
+function getAgentProfile(projectRoot, role) {
+  const normalizedRole = normalizeAgentProfileRole(role);
+  const state = readAgentProfiles(projectRoot);
+  return state.profiles[normalizedRole] || null;
+}
+
+function listAgentProfiles(projectRoot) {
+  const state = readAgentProfiles(projectRoot);
+  return AGENT_PROFILE_ROLES.map((role) => ({
+    role,
+    configured: Boolean(state.profiles[role]),
+    profile: state.profiles[role] || null,
+  }));
+}
+
+function setAgentProfile(projectRoot, role, options = {}) {
+  const normalizedRole = normalizeAgentProfileRole(role);
+  const provider = assertSupportedProvider(options.provider);
+  const model = normalizeOptionalText(options.model, 'model');
+  const label = normalizeOptionalText(options.label, 'label');
+  const context = normalizeOptionalText(options.context, 'context');
+  const state = readAgentProfiles(projectRoot);
+  const current = state.profiles[normalizedRole] || {};
+  const now = new Date().toISOString();
+  const profile = {
+    role: normalizedRole,
+    provider,
+    model: model || current.model || '',
+    label: label || current.label || '',
+    context: context || current.context || '',
+    updated_at: now,
+  };
+
+  state.version = PROFILE_STATE_VERSION;
+  state.profiles = {
+    ...state.profiles,
+    [normalizedRole]: profile,
+  };
+  state.updated_at = now;
+
+  const filePath = writeAgentProfiles(projectRoot, state);
+  return {
+    filePath,
+    profile,
+  };
+}
+
+function resolveProfileProvider(projectRoot, role, fallbackProvider) {
+  const profile = getAgentProfile(projectRoot, role);
+  if (profile?.provider) {
+    return assertSupportedProvider(profile.provider);
+  }
+  return assertSupportedProvider(fallbackProvider);
+}
+
+module.exports = {
+  AGENT_PROFILE_ROLES,
+  PROFILE_STATE_VERSION,
+  agentProfilesPath,
+  formatProviderList,
+  getAgentProfile,
+  listAgentProfiles,
+  normalizeAgentProfileRole,
+  readAgentProfiles,
+  resolveProfileProvider,
+  setAgentProfile,
+};

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

@@ -0,0 +1,170 @@
+const { filterContextPaths, shouldExcludeContextPath } = require('./safety');
+const { buildRolePrompt } = require('./prompts');
+const { readProjectScanArtifact } = require('../project-scan');
+
+const ROLES = Object.freeze({
+  PLANNER: 'planner',
+  EXECUTOR: 'executor',
+});
+
+const CONTEXT_PACKS = Object.freeze({
+  full: Object.freeze({
+    name: 'full',
+    description: 'Broad planner onboarding context.',
+    role: ROLES.PLANNER,
+    tokenBudgetHint: 14000,
+    roleGuidance: 'Use broad onboarding context, project map, workflow docs, and relevant specs.',
+  }),
+  planning: Object.freeze({
+    name: 'planning',
+    description: 'Focused planner context for acceptance criteria and technical planning.',
+    role: ROLES.PLANNER,
+    tokenBudgetHint: 8000,
+    roleGuidance: 'Use project map, workflow docs, and only the specs needed for the current planning step.',
+  }),
+  slice: Object.freeze({
+    name: 'slice',
+    description: 'Executor context for a single slice handoff.',
+    role: ROLES.EXECUTOR,
+    tokenBudgetHint: 3200,
+    roleGuidance: 'Use slice handoff, allowed files, acceptance criteria, and validation commands only.',
+  }),
+  minimal: Object.freeze({
+    name: 'minimal',
+    description: 'Smallest executor context for narrowly-scoped tasks.',
+    role: ROLES.EXECUTOR,
+    tokenBudgetHint: 1200,
+    roleGuidance: 'Use the smallest safe set of slice details and avoid onboarding context.',
+  }),
+});
+
+const DEFAULT_CONTEXT_PACK_BY_ROLE = Object.freeze({
+  [ROLES.PLANNER]: 'planning',
+  [ROLES.EXECUTOR]: 'slice',
+});
+
+const PACK_ORDER = ['full', 'planning', 'slice', 'minimal'];
+const CONTEXT_PREPARED_DOC_PATHS = Object.freeze([
+  'docs/AI_CONTEXT.md',
+  'docs/AI_ONBOARDING_PROMPT.md',
+  'docs/CONTEXTO.md',
+  'docs/STATUS.md',
+  'docs/DECISIONS.md',
+]);
+
+function normalizeRole(role) {
+  const value = String(role || '').trim().toLowerCase();
+  if (value === ROLES.PLANNER || value === ROLES.EXECUTOR) {
+    return value;
+  }
+  throw new Error(`create-quiver: unsupported role '${role}'. Expected planner or executor.`);
+}
+
+function normalizePackName(packName) {
+  const value = String(packName || '').trim().toLowerCase();
+  if (CONTEXT_PACKS[value]) {
+    return value;
+  }
+  throw new Error(`create-quiver: unsupported context pack '${packName}'. Expected one of: ${PACK_ORDER.join(', ')}`);
+}
+
+function getDefaultContextPack(role) {
+  const normalizedRole = normalizeRole(role);
+  return DEFAULT_CONTEXT_PACK_BY_ROLE[normalizedRole];
+}
+
+function getPreparedContextDocPaths() {
+  return CONTEXT_PREPARED_DOC_PATHS.slice();
+}
+
+function resolveContextPack({ role, packName } = {}) {
+  const normalizedRole = normalizeRole(role);
+  const defaultPack = getDefaultContextPack(normalizedRole);
+  const resolvedPackName = packName ? normalizePackName(packName) : defaultPack;
+
+  if (normalizedRole === ROLES.EXECUTOR && resolvedPackName === 'full') {
+    throw new Error('create-quiver: executor context cannot use the full pack by default.');
+  }
+
+  const pack = CONTEXT_PACKS[resolvedPackName];
+  if (pack.role !== normalizedRole && !(normalizedRole === ROLES.PLANNER && resolvedPackName === 'slice')) {
+    throw new Error(`create-quiver: context pack '${resolvedPackName}' is not valid for role '${normalizedRole}'.`);
+  }
+
+  return {
+    role: normalizedRole,
+    packName: resolvedPackName,
+    defaultPack,
+    isDefault: resolvedPackName === defaultPack,
+    tokenBudgetHint: pack.tokenBudgetHint,
+    pack,
+  };
+}
+
+function buildPackSelection({ role, packName, paths = [] } = {}) {
+  const resolved = resolveContextPack({ role, packName });
+  const { included, excluded } = filterContextPaths(paths);
+
+  return {
+    ...resolved,
+    includedPaths: included,
+    excludedPaths: excluded,
+  };
+}
+
+function resolveScanArtifactMetadata(repoRoot) {
+  if (!repoRoot) {
+    return null;
+  }
+
+  const artifact = readProjectScanArtifact(repoRoot);
+  if (!artifact) {
+    return null;
+  }
+
+  return {
+    path: artifact.relativePath,
+    source: artifact.source,
+  };
+}
+
+function buildContextPackMetadata(options = {}) {
+  const selection = buildPackSelection(options);
+
+  return {
+    role: selection.role,
+    packName: selection.packName,
+    isDefault: selection.isDefault,
+    tokenBudgetHint: selection.tokenBudgetHint,
+    description: selection.pack.description,
+    includedPaths: selection.includedPaths,
+    excludedPaths: selection.excludedPaths,
+    scanArtifact: resolveScanArtifactMetadata(options.repoRoot),
+    prompt: buildRolePrompt(selection.role, selection.pack),
+  };
+}
+
+function selectSafePaths(paths, options = {}) {
+  const selection = buildPackSelection({ ...options, paths });
+  return {
+    included: selection.includedPaths,
+    excluded: selection.excludedPaths,
+  };
+}
+
+module.exports = {
+  CONTEXT_PACKS,
+  DEFAULT_CONTEXT_PACK_BY_ROLE,
+  PACK_ORDER,
+  ROLES,
+  buildContextPackMetadata,
+  buildPackSelection,
+  getPreparedContextDocPaths,
+  getDefaultContextPack,
+  normalizePackName,
+  normalizeRole,
+  resolveScanArtifactMetadata,
+  resolveContextPack,
+  selectSafePaths,
+  shouldExcludeContextPath,
+};