@geraldmaron/construct 1.0.2 → 1.0.3

package/lib/install/first-invocation.mjs

@@ -10,7 +10,7 @@
  *   2. Otherwise, run `probeAll()` from lib/bootstrap/resources.mjs.
  *   3. If everything's healthy → silent, set BOOTSTRAP_CHECKED=1.
  *   4. If anything's missing → print the status table to stderr; on TTY,
- *      prompt to run `construct setup` now. Always set BOOTSTRAP_CHECKED=1
+ *      prompt to run `construct init` now. Always set BOOTSTRAP_CHECKED=1
  *      so we don't re-prompt on subsequent commands.
  *
  * Skipped entirely for hook invocations (would corrupt hook output), for
@@ -71,14 +71,14 @@ export async function maybeFirstInvocationProbe({
   for (const probe of probes) stdout.write(formatProbeFn(probe) + '\n');
 
   if (missingRequired.length > 0) {
-    stdout.write(`\n[construct] ${missingRequired.length} required resource(s) missing. Run \`construct setup\` to install.\n\n`);
+    stdout.write(`\n[construct] ${missingRequired.length} required resource(s) missing. Run \`construct init\` to install.\n\n`);
   } else {
-    stdout.write(`\n[construct] ${missingOptional.length} optional resource(s) missing. Run \`construct setup\` to install (Postgres, telemetry, embedding model), or continue in degraded mode.\n\n`);
+    stdout.write(`\n[construct] ${missingOptional.length} optional resource(s) missing. Run \`construct init\` to install (Postgres, telemetry, embedding model), or continue in degraded mode.\n\n`);
   }
 
   if (stdin.isTTY && stdout.isTTY !== false) {
     const wants = await promptYesNo({
-      question: 'Run `construct setup` now?',
+      question: 'Run `construct init` now?',
       defaultYes: missingRequired.length > 0,
       readlineModule,
       stdin,

package/lib/intake/queue.mjs

@@ -73,7 +73,7 @@ export function createIntakeQueue(rootDir, env = process.env, opts = {}) {
   if (backend === 'postgres') {
     const sql = opts.sql ?? createSqlClient(env);
     if (!sql) {
-      throw new Error('Postgres intake queue requires a configured DATABASE_URL (or sql client). Run `construct setup` or set CONSTRUCT_INTAKE_QUEUE_BACKEND=filesystem.');
+      throw new Error('Postgres intake queue requires a configured DATABASE_URL (or sql client). Run `construct init` or set CONSTRUCT_INTAKE_QUEUE_BACKEND=filesystem.');
     }
     const project = opts.project ?? resolveProject(rootDir, env);
     const tenantId = opts.tenantId ?? env?.[INTAKE_TENANT_ENV_KEY] ?? null;

package/lib/integrations/intake-integrations.mjs

@@ -222,7 +222,7 @@ function buildLabels(t) {
 // ── Jira ─────────────────────────────────────────────────────────────────
 
 /**
- * Create a Jira ticket from an intake packet.
+ * Create a Jira work item from an intake packet.
  *
  * @param {object} packet - Intake packet with triage, excerpt
  * @param {object} [opts]
@@ -276,8 +276,7 @@ export async function createJiraTicket(packet, { host, email, token, project, is
 
     const json = await res.json();
 
-    // We don't have the browse URL directly from the create response,
-    // so construct it from the host + issue key
+    // Browse URL is absent from the create response — construct from host + issue key
     const issueKey = json.key;
     const browseUrl = `${resolvedHost.replace(/\/$/, '')}/browse/${issueKey}`;
 
@@ -474,8 +473,8 @@ async function updateConfluencePage(artifact, { host, email, token, space, fetch
 }
 
 /**
- * Minimal markdown to Confluence storage format conversion.
- * Handles the subset of markdown used by Construct artifacts.
+ * Converts the subset of markdown common to Construct artifacts into
+ * Confluence storage format.
  */
 function markdownToConfluenceStorage(md) {
   if (!md) return '';

package/lib/knowledge/rag.mjs

@@ -155,6 +155,21 @@ function loadSnapshotChunks(rootDir) {
   return chunks;
 }
 
+/**
+ * Load ingested knowledge files from .cx/knowledge/ subdirectories.
+ */
+function loadKnowledgeChunks(rootDir) {
+  const knowledgeRoot = path.resolve(rootDir, '.cx/knowledge');
+  const subdirs = ['internal', 'external', 'decisions', 'how-tos', 'reference'];
+  const chunks = [];
+  for (const subdir of subdirs) {
+    const full = path.join(knowledgeRoot, subdir);
+    if (!fs.existsSync(full)) continue;
+    chunks.push(...loadMarkdownChunks(full, 'knowledge'));
+  }
+  return chunks;
+}
+
 // ── Index builder ──────────────────────────────────────────────────────────
 
 /**
@@ -166,6 +181,7 @@ export function buildCorpus(rootDir = process.cwd()) {
     ...loadObservationChunks(rootDir),
     ...loadArtifactChunks(rootDir),
     ...loadSnapshotChunks(rootDir),
+    ...loadKnowledgeChunks(rootDir),
   ];
 
   // Embed each chunk

package/lib/model-cheapest-provider.mjs

@@ -0,0 +1,231 @@
+/**
+ * lib/model-cheapest-provider.mjs — cheapest configured provider selection.
+ *
+ * Evaluates all configured providers, looks up their per-tier model pricing,
+ * and returns the lowest-cost option. Local providers (Ollama, local) rank
+ * first since they are $0.
+ *
+ * Pricing data comes from getPricingForModels() in model-pricing.mjs, which
+ * has a 5-minute cache from the OpenRouter API. Static tables cover
+ * Anthropic/OpenAI first-party models.
+ *
+ * Usage:
+ *   selectCheapestProvider('standard')          // cheapest for one tier
+ *   rankConfiguredProvidersByCost('fast')       // full ranked list
+ *   isCheapestProviderEnabled()                 // check opt-in preference
+ *   formatCheapestProviderMessage(result)       // user-facing output
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { getProviderModelCatalog, PROVIDER_FAMILY_TIERS } from './model-router.mjs';
+import { getPricingForModels, formatPricingLabel } from './model-pricing.mjs';
+
+const CHEAPEST_PREF_KEY = 'CHEAPEST_PROVIDER_ENABLED';
+const CHEAPEST_CHECKED_KEY = 'CHEAPEST_PROVIDER_CHECKED';
+const ENV_PATH = path.join(os.homedir(), '.construct', 'config.env');
+
+/**
+ * Resolve the cheapest configured provider for a given tier.
+ *
+ * @param {string} tier - One of "reasoning", "standard", "fast"
+ * @param {object} [opts]
+ * @param {object} [opts.env] - Environment object (default: process.env)
+ * @param {string} [opts.envPath] - Path to config.env (default: ~/.construct/config.env)
+ * @param {Function} [opts.getPricingForModels] - Injectable pricing fetcher
+ * @returns {Promise<{
+ *   providerId: string|null,
+ *   providerLabel: string|null,
+ *   modelId: string|null,
+ *   inputPrice: number|null,
+ *   outputPrice: number|null,
+ *   isLocal: boolean,
+ *   configuredProviders: string[],
+ *   rankedList: Array<{providerId, providerLabel, modelId, inputPrice, outputPrice, totalPer1M, isLocal}>
+ * }>}
+ */
+export async function selectCheapestProvider(tier, opts = {}) {
+  if (!['reasoning', 'standard', 'fast'].includes(tier)) {
+    return { providerId: null, providerLabel: null, modelId: null, configuredProviders: [], rankedList: [] };
+  }
+
+  const env = opts.env || process.env;
+  const catalog = getProviderModelCatalog({ env });
+  const configured = catalog.providers.filter((p) => p.configured);
+
+  if (configured.length === 0) {
+    return {
+      providerId: null, providerLabel: null, modelId: null,
+      inputPrice: null, outputPrice: null, isLocal: false,
+      configuredProviders: [], rankedList: [],
+    };
+  }
+
+  // Collect tier-specific model IDs from all configured providers
+  const modelIds = [];
+  for (const p of configured) {
+    const modelId = p.tiers[tier];
+    if (modelId) modelIds.push(modelId);
+  }
+
+  const needsRemote = modelIds.filter((id) => /^openrouter\//.test(id));
+  const hasRemote = needsRemote.length > 0;
+
+  // Fetch pricing (uses 5-min cache internally)
+  let pricingMap = {};
+  if (hasRemote) {
+    try {
+      pricingMap = await getPricingForModels(modelIds, {
+        getPricingForModels: opts.getPricingForModels,
+      });
+    } catch { /* pricing unavailable — fall back to nulls */ }
+  }
+
+  // Score each provider
+  const scored = configured.map((p) => {
+    const modelId = p.tiers[tier];
+    const pricing = hasRemote ? pricingMap[modelId] : null;
+    const inputPrice = pricing ? (Number(pricing.input) || 0) : 0;
+    const outputPrice = pricing ? (Number(pricing.output) || 0) : 0;
+    return {
+      providerId: p.id,
+      providerLabel: p.label,
+      modelId,
+      inputPrice,
+      outputPrice,
+      totalPer1M: inputPrice + outputPrice,
+      isLocal: p.local === true,
+    };
+  });
+
+  // Sort ascending by total cost (local/$0 first)
+  scored.sort((a, b) => a.totalPer1M - b.totalPer1M);
+
+  const cheapest = scored[0];
+  return {
+    providerId: cheapest.providerId,
+    providerLabel: cheapest.providerLabel,
+    modelId: cheapest.modelId,
+    inputPrice: cheapest.inputPrice,
+    outputPrice: cheapest.outputPrice,
+    isLocal: cheapest.isLocal,
+    configuredProviders: configured.map((p) => p.id),
+    rankedList: scored,
+  };
+}
+
+/**
+ * Get all configured providers ranked by cost for a tier.
+ *
+ * @param {string} tier
+ * @param {object} [opts]
+ * @returns {Promise<Array<{providerId, providerLabel, modelId, inputPrice, outputPrice, totalPer1M, isLocal}>>}
+ */
+export async function rankConfiguredProvidersByCost(tier, opts = {}) {
+  const result = await selectCheapestProvider(tier, opts);
+  return result.rankedList;
+}
+
+/**
+ * Check if the user has opted into cheapest-provider selection.
+ *
+ * @param {string} [envPath] - Path to config.env (default: ~/.construct/config.env)
+ * @param {object} [opts.env] - Environment override
+ * @returns {boolean}
+ */
+export function isCheapestProviderEnabled(envPath, opts = {}) {
+  const pathToUse = envPath || ENV_PATH;
+  const env = opts.env || process.env;
+
+  // Check env var first
+  if (env[CHEAPEST_PREF_KEY]) {
+    return env[CHEAPEST_PREF_KEY].toLowerCase() === 'yes';
+  }
+
+  // Check config.env file
+  try {
+    const content = fs.readFileSync(pathToUse, 'utf8');
+    const match = content.match(new RegExp(`^${CHEAPEST_PREF_KEY}=(.+)$`, 'm'));
+    if (match) {
+      return match[1].trim().toLowerCase() === 'yes';
+    }
+  } catch { /* file doesn't exist */ }
+
+  return false;
+}
+
+/**
+ * Persist the cheapest-provider opt-in preference.
+ *
+ * @param {string} envPath - Path to config.env
+ * @param {boolean} enabled
+ */
+export function setCheapestProviderPreference(envPath, enabled) {
+  const pathToUse = envPath || ENV_PATH;
+  const existing = fs.existsSync(pathToUse) ? fs.readFileSync(pathToUse, 'utf8') : '';
+  const lines = existing.split('\n');
+  const keyLine = `${CHEAPEST_PREF_KEY}=${enabled ? 'yes' : 'no'}`;
+
+  // Replace existing key or append
+  const idx = lines.findIndex((l) => l.startsWith(`${CHEAPEST_PREF_KEY}=`));
+  if (idx >= 0) {
+    lines[idx] = keyLine;
+  } else {
+    lines.push(keyLine);
+  }
+
+  fs.mkdirSync(path.dirname(pathToUse), { recursive: true });
+  fs.writeFileSync(pathToUse, lines.join('\n'));
+}
+
+/**
+ * Format the cheapest provider selection into a user-facing message.
+ *
+ * @param {object} result - Output from selectCheapestProvider
+ * @param {object} [opts]
+ * @param {boolean} [opts.showRanking] - Include full ranked list
+ * @returns {string}
+ */
+export function formatCheapestProviderMessage(result, opts = {}) {
+  const { providerId, providerLabel, modelId, inputPrice, outputPrice, isLocal, rankedList } = result;
+
+  if (!providerId) {
+    return 'No configured providers found. Set API keys or install Ollama to enable model selection.';
+  }
+
+  const label = formatPricingLabel({ input: inputPrice, output: outputPrice, source: isLocal ? 'local' : 'openrouter' });
+  let msg = `Cheapest provider for this tier:\n`;
+  msg += `  Provider:  ${providerLabel}\n`;
+  msg += `  Model:     ${modelId}\n`;
+  msg += `  Pricing:   ${label}`;
+
+  if (opts.showRanking && rankedList && rankedList.length > 0) {
+    msg += `\n\nConfigured providers ranked by cost:\n`;
+    for (let i = 0; i < rankedList.length; i++) {
+      const r = rankedList[i];
+      const rLabel = formatPricingLabel({
+        input: r.inputPrice,
+        output: r.outputPrice,
+        source: r.isLocal ? 'local' : 'openrouter',
+      });
+      const marker = i === 0 ? '→' : ' ';
+      msg += `  ${marker} ${r.providerLabel.padEnd(28)} ${r.modelId.padEnd(40)} ${rLabel}\n`;
+    }
+  }
+
+  return msg;
+}
+
+/**
+ * Get all tier-specific cheapest selections.
+ *
+ * @param {object} [opts]
+ * @returns {Promise<{reasoning, standard, fast}>}
+ */
+export async function selectCheapestForAllTiers(opts = {}) {
+  const reasoning = await selectCheapestProvider('reasoning', opts);
+  const standard = await selectCheapestProvider('standard', opts);
+  const fast = await selectCheapestProvider('fast', opts);
+  return { reasoning, standard, fast };
+}

package/lib/model-router.mjs

@@ -217,9 +217,8 @@ const PROVIDER_FAMILY_TIERS = [
 export { PROVIDER_FAMILY_TIERS };
 
 /**
- * Map provider family IDs to the env var(s) that indicate the provider
- * is configured (has credentials). Used by getProviderModelCatalog to
- * mark which providers are available.
+ * Maps provider family IDs to the env var(s) that confirm credentials are present.
+ * Consumed by getProviderModelCatalog to mark which providers are available.
  */
 const PROVIDER_ENV_MAP = {
   'anthropic': ['ANTHROPIC_API_KEY'],
@@ -254,14 +253,14 @@ function isProviderConfigured(familyId, env) {
     } catch { /* not available */ }
   }
 
-  // 1. Check passed env (usually process.env)
+  // Check passed env (usually process.env)
   const anyInEnv = varNames.some(name => {
     const val = env?.[name];
     return val && typeof val === 'string' && val.length > 0;
   });
   if (anyInEnv) return true;
 
-  // 2. Check construct config.env
+  // Check construct config.env
   try {
     const homeDir = process.env.HOME || process.env.USERPROFILE || '/tmp';
     const cfgPath = path.join(homeDir, '.construct', 'config.env');
@@ -276,7 +275,7 @@ function isProviderConfigured(familyId, env) {
     }
   } catch { /* skip */ }
 
-  // 3. Special case: GitHub Copilot via gh CLI
+  // GitHub Copilot: detect via gh CLI auth status
   if (familyId === 'github-copilot') {
     try {
       const r = spawnSync('gh', ['auth', 'status'], { encoding: 'utf8', timeout: 3000 });
@@ -284,7 +283,7 @@ function isProviderConfigured(familyId, env) {
     } catch { return false; }
   }
 
-  // 4. Check ~/.env
+  // Check ~/.env
   try {
     const homeEnv = path.join(process.env.HOME || process.env.USERPROFILE || '/tmp', '.env');
     if (fs.existsSync(homeEnv)) {
@@ -298,7 +297,7 @@ function isProviderConfigured(familyId, env) {
     }
   } catch { /* skip */ }
 
-  // 5. Check shell rc files for op:// refs (1Password CLI integration)
+  // Check shell rc files for op:// refs (1Password CLI integration)
   try {
     const homeDir = process.env.HOME || process.env.USERPROFILE || '/tmp';
     const shellFiles = ['.zshrc', '.bashrc', '.bash_profile', '.profile'].map(f => path.join(homeDir, f));

package/lib/project-profile.mjs

@@ -8,7 +8,7 @@
  *
  * The profile is written to `<cwd>/.cx/project-profile.json` and consumed by:
  *   - `construct skills scope` — reports relevant vs irrelevant skills
- *   - `construct setup` — runs detection on bootstrap
+ *   - `construct init` — runs detection on bootstrap
  *   - future per-host filter generators (.claude/settings.json filter,
  *     .opencode/construct-skills.json sidecars, etc.)
  */

package/lib/roles/catalog.mjs

@@ -0,0 +1,133 @@
+/**
+ * lib/roles/catalog.mjs — role listing and display helpers.
+ *
+ * Reads agents/registry.json to produce a list of available roles with
+ * optional department grouping and consolidated-role views. Consumed by the
+ * `roles:list` CLI command.
+ */
+
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const REGISTRY_PATH = join(__dirname, '..', '..', 'agents', 'registry.json');
+
+let cached = null;
+
+function loadRegistry() {
+  if (cached) return cached;
+  cached = JSON.parse(readFileSync(REGISTRY_PATH, 'utf8'));
+  return cached;
+}
+
+/**
+ * Return a list of role descriptors.
+ *
+ * @param {object}  opts
+ * @param {boolean} opts.departments   Group by department when true.
+ * @param {boolean} opts.consolidated  Return consolidated 12-role view when true.
+ * @returns {Array<object>}
+ */
+export function listRoles({ departments = false, consolidated = false } = {}) {
+  const registry = loadRegistry();
+
+  if (consolidated) {
+    const c = registry.consolidatedRoles || {};
+    return (c.roles || []).map((r) => ({
+      id: r.id,
+      absorbs: r.absorbs || [],
+      whenToUse: r.whenToUse || '',
+    }));
+  }
+
+  const agents = Array.isArray(registry.agents)
+    ? registry.agents
+    : Object.values(registry.agents || {});
+
+  if (!departments) {
+    return agents.map((a) => ({
+      id: a.name,
+      name: `cx-${a.name}`,
+      description: a.description || '',
+      internal: !!a.internal,
+    }));
+  }
+
+  // Group by department based on subDepartment membership in registry.departments
+  const depts = registry.departments || {};
+  const grouped = {};
+  for (const [deptId, dept] of Object.entries(depts)) {
+    grouped[deptId] = {
+      name: dept.name || deptId,
+      roles: [],
+    };
+  }
+  grouped._ungrouped = { name: 'Other', roles: [] };
+
+  for (const agent of agents) {
+    let placed = false;
+    for (const [deptId, dept] of Object.entries(depts)) {
+      const subs = dept.subDepartments || {};
+      for (const sub of Object.values(subs)) {
+        if ((sub.roles || []).includes(agent.name) || (sub.roles || []).includes(`cx-${agent.name}`)) {
+          grouped[deptId].roles.push({ id: agent.name, name: `cx-${agent.name}`, description: agent.description || '' });
+          placed = true;
+          break;
+        }
+      }
+      if (placed) break;
+    }
+    if (!placed) {
+      grouped._ungrouped.roles.push({ id: agent.name, name: `cx-${agent.name}`, description: agent.description || '' });
+    }
+  }
+
+  return Object.entries(grouped)
+    .filter(([, g]) => g.roles.length > 0)
+    .map(([id, g]) => ({ departmentId: id, departmentName: g.name, roles: g.roles }));
+}
+
+/**
+ * Format the role list as a human-readable string.
+ *
+ * @param {object}  opts  Same options as listRoles.
+ * @returns {string}
+ */
+export function formatRoleList({ departments = false, consolidated = false } = {}) {
+  const roles = listRoles({ departments, consolidated });
+  const lines = [];
+
+  if (consolidated) {
+    lines.push('Consolidated Roles (12-role simplified structure)');
+    lines.push('=================================================');
+    for (const r of roles) {
+      lines.push(`\n${r.id}`);
+      lines.push(`  Absorbs: ${r.absorbs.join(', ')}`);
+      lines.push(`  Use when: ${r.whenToUse}`);
+    }
+    lines.push('');
+    return lines.join('\n');
+  }
+
+  if (departments) {
+    lines.push('Available Roles by Department');
+    lines.push('=============================');
+    for (const group of roles) {
+      lines.push(`\n${group.departmentName}`);
+      for (const role of group.roles) {
+        lines.push(`  ${role.name.padEnd(30)} ${role.description}`);
+      }
+    }
+    lines.push('');
+    return lines.join('\n');
+  }
+
+  lines.push('Available Roles');
+  lines.push('===============');
+  for (const role of roles) {
+    lines.push(`  ${role.name.padEnd(30)} ${role.description}`);
+  }
+  lines.push('');
+  return lines.join('\n');
+}

package/lib/roles/preference.mjs

@@ -0,0 +1,74 @@
+/**
+ * lib/roles/preference.mjs — per-user primary/secondary role preferences.
+ *
+ * Persists role preferences to ~/.construct/config.env under the keys
+ * CONSTRUCT_ROLE_PRIMARY and CONSTRUCT_ROLE_SECONDARY. Consumed by the
+ * `roles:set` CLI command and the orchestration layer.
+ */
+
+import os from 'node:os';
+import path from 'node:path';
+
+import { getUserEnvPath, ensureUserConfigDir, writeEnvValues, parseEnvFile } from '../env-config.mjs';
+
+const ENV_KEYS = {
+  primary: 'CONSTRUCT_ROLE_PRIMARY',
+  secondary: 'CONSTRUCT_ROLE_SECONDARY',
+};
+
+/**
+ * Read the stored role preference for the given slot.
+ *
+ * @param {'primary'|'secondary'} slot
+ * @returns {string|null}  The stored role id, or null if unset.
+ */
+export function getRolePreference(slot) {
+  const envKey = ENV_KEYS[slot];
+  if (!envKey) return null;
+
+  // Env var takes priority (allows per-session override)
+  if (process.env[envKey]) return process.env[envKey];
+
+  const envPath = getUserEnvPath(os.homedir());
+  const stored = parseEnvFile(envPath);
+  return stored[envKey] || null;
+}
+
+/**
+ * Persist a role preference for the given slot.
+ *
+ * @param {'primary'|'secondary'} slot
+ * @param {string} role  Role id (e.g. "cx-engineer" or "engineer").
+ * @returns {{ slot: string, role: string }}
+ */
+export function setRolePreference(slot, role) {
+  const envKey = ENV_KEYS[slot];
+  if (!envKey) throw new Error(`Unknown role slot "${slot}". Use "primary" or "secondary".`);
+
+  // Normalise: accept both "engineer" and "cx-engineer"
+  const normalised = role.startsWith('cx-') ? role : `cx-${role}`;
+
+  ensureUserConfigDir(os.homedir());
+  const envPath = getUserEnvPath(os.homedir());
+  writeEnvValues(envPath, { [envKey]: normalised });
+
+  // Also set in current process so the change is visible immediately
+  process.env[envKey] = normalised;
+
+  return { slot, role: normalised };
+}
+
+/**
+ * Clear a stored role preference.
+ *
+ * @param {'primary'|'secondary'} slot
+ */
+export function clearRolePreference(slot) {
+  const envKey = ENV_KEYS[slot];
+  if (!envKey) return;
+
+  delete process.env[envKey];
+
+  const envPath = getUserEnvPath(os.homedir());
+  writeEnvValues(envPath, { [envKey]: '' });
+}