@geraldmaron/construct 1.0.0 → 1.0.1

package/lib/bootstrap/resources.mjs

@@ -0,0 +1,120 @@
+/**
+ * lib/bootstrap/resources.mjs — registry of optional resources Construct can spin up.
+ *
+ * A resource is something Construct can use but does not require: Postgres
+ * with pgvector, the local ONNX embedding model, Docker, git, etc. Each
+ * resource declares:
+ *
+ *   id            stable identifier
+ *   displayName   human-readable label
+ *   required      true → missing means CLI commands fail; false → fall back
+ *   detect()      async probe → { present, version?, location?, healthy?, detail? }
+ *   install()     async installer → { method, success, log }   (optional)
+ *   fallback()    string explaining what runs in degraded mode
+ *   consentKey    env var name in config.env for cached operator consent
+ *   downloadSize  approximate install size in bytes (informational)
+ *
+ * The registry is consulted by:
+ *   - `construct init`         walks every resource, asks consent, installs
+ *   - `construct doctor --bootstrap`  re-probes every resource verbosely
+ *   - lazy-install paths in hooks (consult the cached consent silently)
+ *
+ * Resources are "additive" — anyone can register a new resource via
+ * `registerResource()` so plugins (or future built-ins) can extend the set
+ * without forking this file.
+ */
+
+const REGISTRY = new Map();
+
+/**
+ * Register a resource. Throws if the id is already registered.
+ */
+export function registerResource(resource) {
+  if (!resource || typeof resource !== 'object') {
+    throw new Error('registerResource: resource must be an object');
+  }
+  for (const field of ['id', 'displayName', 'detect', 'consentKey']) {
+    if (!resource[field]) throw new Error(`registerResource: ${field} is required`);
+  }
+  if (REGISTRY.has(resource.id)) {
+    throw new Error(`registerResource: ${resource.id} already registered`);
+  }
+  REGISTRY.set(resource.id, resource);
+}
+
+export function listResources() {
+  return [...REGISTRY.values()];
+}
+
+export function getResource(id) {
+  return REGISTRY.get(id);
+}
+
+export function clearResourceRegistry() {
+  REGISTRY.clear();
+}
+
+/**
+ * Probe one resource. Catches errors so a broken probe never cascades.
+ */
+export async function probeResource(resource) {
+  if (!resource || typeof resource.detect !== 'function') {
+    return { id: resource?.id, present: false, error: 'resource has no detect()' };
+  }
+  try {
+    const result = await resource.detect();
+    return {
+      id: resource.id,
+      displayName: resource.displayName,
+      required: resource.required ?? false,
+      present: !!result?.present,
+      version: result?.version || null,
+      location: result?.location || null,
+      healthy: result?.healthy ?? !!result?.present,
+      detail: result?.detail || null,
+      consentKey: resource.consentKey,
+      fallback: resource.fallback?.() || null,
+      downloadSize: resource.downloadSize || null,
+      installable: typeof resource.install === 'function',
+    };
+  } catch (err) {
+    return {
+      id: resource.id,
+      displayName: resource.displayName,
+      required: resource.required ?? false,
+      present: false,
+      error: err?.message || String(err),
+    };
+  }
+}
+
+/**
+ * Probe every registered resource. Returns a sorted array (required first,
+ * then by id) so callers can render a deterministic report.
+ */
+export async function probeAll() {
+  const probes = await Promise.all([...REGISTRY.values()].map(probeResource));
+  return probes.sort((a, b) => {
+    if (a.required !== b.required) return a.required ? -1 : 1;
+    return String(a.id).localeCompare(String(b.id));
+  });
+}
+
+/**
+ * Format a probe result line for human display.
+ */
+export function formatProbe(probe) {
+  const status = probe.present
+    ? (probe.healthy ? '✓' : '⚠')
+    : (probe.required ? '✗' : '○');
+  const v = probe.version ? ` (${probe.version})` : '';
+  const loc = probe.location ? ` ${probe.location}` : '';
+  const detail = probe.detail ? ` — ${probe.detail}` : '';
+  const fallback = !probe.present && !probe.required && probe.fallback
+    ? `\n     fallback: ${probe.fallback}`
+    : '';
+  const install = !probe.present && probe.installable
+    ? `\n     installable via construct init`
+    : '';
+  return `  ${status}  ${probe.displayName}${v}${loc}${detail}${fallback}${install}`;
+}

package/lib/bootstrap.mjs

@@ -0,0 +1,105 @@
+/**
+ * lib/bootstrap.mjs — imports the seed observation corpus into the local memory store.
+ *
+ * Reads markdown files from examples/seed-observations/, parses each ## heading group
+ * into individual observations, and writes them via addObservation. Safe to re-run:
+ * observations with matching content hashes are skipped. Reports counts on completion.
+ */
+
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { addObservation, listObservations, getObservation } from './observation-store.mjs';
+
+const SEED_DIR = path.resolve(import.meta.dirname, '..', 'examples', 'seed-observations');
+
+const FILE_CATEGORY_MAP = {
+  'patterns.md': 'pattern',
+  'anti-patterns.md': 'anti-pattern',
+  'decisions.md': 'decision',
+};
+
+function contentHash(str) {
+  return crypto.createHash('sha256').update(str).digest('hex').slice(0, 16);
+}
+
+function parseObservations(content, category) {
+  const observations = [];
+  const lines = content.split('\n');
+  let currentH2 = null;
+  let buffer = [];
+
+  function flush() {
+    if (!buffer.length) return;
+    const raw = buffer.join('\n').trim();
+    if (!raw) { buffer = []; return; }
+    const firstLine = raw.split('\n')[0];
+    const boldMatch = firstLine.match(/^\*\*(.+?)\*\*/);
+    const summary = boldMatch ? boldMatch[1] : firstLine.replace(/^#+\s*/, '').slice(0, 120);
+    observations.push({
+      summary,
+      content: raw,
+      category,
+      tags: currentH2 ? [currentH2.toLowerCase().replace(/\s+/g, '-')] : [],
+      role: 'construct',
+      confidence: 0.85,
+      source: 'seed-corpus',
+    });
+    buffer = [];
+  }
+
+  for (const line of lines) {
+    if (line.startsWith('## ')) {
+      flush();
+      currentH2 = line.replace(/^## /, '').trim();
+      continue;
+    }
+    if (line.startsWith('**') && buffer.length > 0) {
+      flush();
+    }
+    buffer.push(line);
+  }
+  flush();
+
+  return observations;
+}
+
+export function runBootstrap(rootDir = process.cwd(), { verbose = false } = {}) {
+  if (!fs.existsSync(SEED_DIR)) {
+    return { imported: 0, skipped: 0, error: `seed dir not found: ${SEED_DIR}` };
+  }
+
+  // Load existing seed-corpus entries and hash their content for idempotency check.
+   // Index lacks content field; load full records for hash comparison.
+   const existing = listObservations(rootDir, { limit: 10000 });
+  const existingHashes = new Set();
+  for (const entry of existing.filter((e) => e.source === 'seed-corpus' || e.role === 'construct')) {
+    const full = getObservation(rootDir, entry.id);
+    if (full?.content) existingHashes.add(contentHash(full.content));
+  }
+
+  let imported = 0;
+  let skipped = 0;
+
+  for (const [filename, category] of Object.entries(FILE_CATEGORY_MAP)) {
+    const filePath = path.join(SEED_DIR, filename);
+    if (!fs.existsSync(filePath)) continue;
+    const content = fs.readFileSync(filePath, 'utf8');
+    const observations = parseObservations(content, category);
+
+    for (const obs of observations) {
+      const hash = contentHash(obs.content);
+      if (existingHashes.has(hash)) {
+        skipped++;
+        if (verbose) process.stdout.write(`  skip  ${obs.summary.slice(0, 60)}\n`);
+        continue;
+      }
+      addObservation(rootDir, obs);
+      existingHashes.add(hash);
+      imported++;
+      if (verbose) process.stdout.write(`  import  ${obs.summary.slice(0, 60)}\n`);
+    }
+  }
+
+  return { imported, skipped };
+}

package/lib/cache-governor.js

@@ -0,0 +1,213 @@
+/**
+ * lib/cache-governor.js — Adaptive cache strategy feedback loop.
+ *
+ * Reads cost log, computes cache efficiency per provider.
+ * Adjusts strategy based on observed vs expected cache usage.
+ * Persists state in ~/.cx/cache-strategy.json.
+ *
+ * Runs as a PostToolUse hook (lightweight, sub-5ms).
+ * Adjustments are persisted per-provider.
+ */
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { normalizeCostEntry } from './cost.mjs';
+
+const STRATEGY_PATH = join(homedir(), '.cx', 'cache-strategy.json');
+const REVIEW_INTERVAL_MS = 10 * 60 * 1000; // 10 minutes between adjustments
+
+function readStrategy() {
+  try {
+    if (!existsSync(STRATEGY_PATH)) return {};
+    return JSON.parse(readFileSync(STRATEGY_PATH, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+function writeStrategy(data) {
+  try {
+    mkdirSync(join(homedir(), '.cx'), { recursive: true });
+    writeFileSync(STRATEGY_PATH, JSON.stringify(data, null, 2));
+  } catch { /* best effort */ }
+}
+
+/**
+ * Compute cache efficiency from a cost entry.
+ * Compares actual cache reads vs expected cacheable tokens.
+ *
+ * @param {object} entry - normalized cost entry
+ * @param {number} expectedCacheableTokens
+ * @returns {{ efficiency: number, waste: number, hitRate: number }}
+ */
+export function computeCacheEfficiency(entry, expectedCacheableTokens = 0) {
+  if (!entry) return { efficiency: 0, waste: 0, hitRate: 0 };
+
+  const actualCacheRead = entry.cacheReadInputTokens || 0;
+  const actualCacheWrite = entry.cacheCreationInputTokens || 0;
+  const processedInput = entry.processedInputTokens || entry.inputTokens || 0;
+
+  const hitRate = processedInput > 0 ? actualCacheRead / processedInput : 0;
+  const writeRatio = expectedCacheableTokens > 0
+    ? actualCacheWrite / expectedCacheableTokens
+    : 0;
+
+  // Efficiency: how close are we to expected cache usage?
+  const efficiency = expectedCacheableTokens > 0
+    ? Math.min(1, actualCacheRead / expectedCacheableTokens)
+    : 0;
+
+  // Waste: expected writes minus actual reads (over-caching)
+  const waste = Math.max(0, actualCacheWrite - actualCacheRead);
+
+  return {
+    efficiency: Math.round(efficiency * 100) / 100,
+    waste,
+    hitRate: Math.round(hitRate * 100) / 100,
+    actualCacheRead,
+    actualCacheWrite,
+    expectedCacheableTokens,
+  };
+}
+
+/**
+ * Analyze recent cost entries and suggest cache strategy adjustments.
+ *
+ * @param {Array} entries - normalized cost entries
+ * @param {string} provider
+ * @returns {{ adjustBreakpoints: boolean, suggestion: string, reason: string }}
+ */
+export function analyzeCachePerformance(entries, provider) {
+  if (!Array.isArray(entries) || entries.length === 0) {
+    return { adjustBreakpoints: false, suggestion: 'no data', reason: 'No cost entries' };
+  }
+
+  // Get latest entry with cache data
+  const withCache = entries
+    .filter(e => (e.cacheReadInputTokens || 0) > 0 || (e.cacheCreationInputTokens || 0) > 0)
+    .sort((a, b) => new Date(b.ts || 0) - new Date(a.ts || 0));
+
+  if (withCache.length === 0) {
+    return { adjustBreakpoints: false, suggestion: 'no cache activity', reason: 'No cache reads/writes detected' };
+  }
+
+  const latest = withCache[0];
+  const efficiency = computeCacheEfficiency(latest, latest.expectedCacheableTokens || 0);
+
+  // Strategy rules
+  if (efficiency.efficiency < 0.2 && (latest.expectedCacheableTokens || 0) > 0) {
+    return {
+      adjustBreakpoints: true,
+      suggestion: 'shift later',
+      reason: `Very low cache efficiency (${(efficiency.efficiency * 100).toFixed(1)}% — cache placement may be wrong`,
+    };
+  }
+
+  if (efficiency.hitRate < 0.2 && (latest.expectedCacheableTokens || 0) > 0) {
+    return {
+      adjustBreakpoints: true,
+      suggestion: 'add earlier breakpoints',
+      reason: `Low cache hit rate (${(efficiency.hitRate * 100).toFixed(1)}% — try caching more static content`,
+    };
+  }
+
+  if (efficiency.efficiency > 0.8) {
+    return {
+      adjustBreakpoints: false,
+      suggestion: 'optimal',
+      reason: `Good cache efficiency (${(efficiency.efficiency * 100).toFixed(1)}% — no adjustment needed`,
+    };
+  }
+
+  if (efficiency.waste > 5000) {
+    return {
+      adjustBreakpoints: true,
+      suggestion: 'reduce breakpoints',
+      reason: `High cache waste (${efficiency.waste} tokens over-cached)`,
+    };
+  }
+
+  return {
+    adjustBreakpoints: false,
+    suggestion: 'stable',
+    reason: `Cache efficiency ${(efficiency.efficiency * 100).toFixed(1)}% — within normal range`,
+  };
+}
+
+/**
+ * PostToolUse hook entry point.
+ * Reads cost log and adjusts strategy if needed.
+ *
+ * @param {object} opts - { costLogPath, provider, dryRun }
+ * @returns {{ adjusted: boolean, strategy: object }}
+ */
+export function onPostToolUse({ costLogPath, provider, dryRun = false } = {}) {
+  const strategy = readStrategy();
+
+  // Check cooldown
+  const lastReview = strategy[`${provider}:lastReview`] || 0;
+  if (Date.now() - lastReview < REVIEW_INTERVAL_MS) {
+    return { adjusted: false, reason: 'Cooldown active', strategy: strategy[provider] };
+  }
+
+  // Read cost log
+  const entries = [];
+  try {
+    const logPath = costLogPath || join(homedir(), '.cx', 'session-cost.jsonl');
+    if (!existsSync(logPath)) return { adjusted: false, reason: 'No cost log' };
+
+    const lines = readFileSync(logPath, 'utf8')
+      .split('\n')
+      .filter(Boolean);
+
+    for (const line of lines) {
+      try {
+        entries.push(normalizeCostEntry(JSON.parse(line)));
+      } catch { /* skip */ }
+    }
+  } catch { /* skip */ }
+
+  const analysis = analyzeCachePerformance(entries, provider);
+
+  if (analysis.adjustBreakpoints && !dryRun) {
+    // Persist adjustment
+    strategy[provider] = {
+      ...strategy[provider],
+      lastReview: Date.now(),
+      suggestion: analysis.suggestion,
+      reason: analysis.reason,
+      updatedAt: new Date().toISOString(),
+    };
+    writeStrategy(strategy);
+
+    return { adjusted: true, suggestion: analysis.suggestion, reason: analysis.reason, strategy: strategy[provider] };
+  }
+
+  return { adjusted: false, reason: analysis.reason, strategy: strategy[provider] };
+}
+
+/**
+ * Get current cache strategy for a provider.
+ *
+ * @param {string} provider
+ * @returns {object|null}
+ */
+export function getCacheStrategy(provider) {
+  const strategy = readStrategy();
+  return strategy[provider] || null;
+}
+
+/**
+ * Reset cache strategy for a provider (or all).
+ *
+ * @param {string} [provider] - if omitted, resets all
+ */
+export function resetCacheStrategy(provider) {
+  if (provider) {
+    const strategy = readStrategy();
+    delete strategy[provider];
+    writeStrategy(strategy);
+  } else {
+    writeStrategy({});
+  }
+}

package/lib/cache-strategy-anthropic.js

@@ -0,0 +1,62 @@
+/**
+ * lib/cache-strategy-anthropic.js — Anthropic cache annotation strategy.
+ *
+ * Anthropic supports cache_control annotations on system messages.
+ * Header required: anthropic-version: 2024-10-22
+ * Cache TTL: 5m and 1h (ephemeral variants)
+ */
+import { estimateTokens } from './token-engine.js';
+
+/**
+ * Annotate prompt structure for Anthropic models.
+ *
+ * @param {object} promptStructure - { system, messages, staticEndIndex }
+ * @param {object} caps - Provider capabilities
+ * @returns {Promise<object>} - { messages, annotations, expectedCacheWriteTokens }
+ */
+export async function annotate(promptStructure, caps) {
+  const { system, messages, staticEndIndex } = promptStructure || {};
+
+  // Annotate system message with cache_control
+  const annotatedMessages = (messages || []).map((msg, idx) => {
+    if (idx === 0 && msg.role === 'system') {
+      return {
+        ...msg,
+        cache_control: { type: 'ephemeral' }, // 5m TTL by default
+      };
+    }
+    return msg;
+  });
+
+  // Calculate expected cacheable tokens
+  const expectedCacheWriteTokens = staticEndIndex >= 0
+    ? await estimateTokens(system || '', { modelId: 'anthropic/claude-opus-4-6' })
+    : 0;
+
+  return {
+    messages: annotatedMessages,
+    annotations: [
+      {
+        type: 'cache_control',
+        placement: 'system-message',
+        ttl: caps?.cacheTTL?.['5m'] || 300_000,
+        note: 'Anthropic cache_control: ephemeral (5m TTL)',
+      },
+      {
+        type: 'header',
+        name: 'anthropic-version',
+        value: caps?.annotationHeaders?.['anthropic-version'] || '2024-10-22',
+      },
+    ],
+    expectedCacheWriteTokens,
+    expectedCacheReadTokens: 0, // unknown until response
+  };
+}
+
+export async function capabilities() {
+  return {
+    supportsAnnotations: true,
+    annotationType: 'cache_control',
+    requiresHeader: 'anthropic-version',
+  };
+}

package/lib/cache-strategy-google.js

@@ -0,0 +1,79 @@
+/**
+ * lib/cache-strategy-google.js — Google Gemini cache strategy.
+ *
+ * Google uses cachedContent API (resource-based caching, not annotations).
+ * Cache TTL: 1h via cachedContent resource.
+ * Requires separate API call to create/update cached content.
+ */
+import { estimateTokens } from './token-engine.js';
+
+const GEMINI_CACHE_ENDPOINT = 'https://generativelanguage.googleapis.com/v1';
+
+/**
+ * Annotate prompt structure for Google Gemini models.
+ * Note: Gemini uses cachedContent API, not message annotations.
+ *
+ * @param {object} promptStructure - { system, messages }
+ * @param {object} caps - Provider capabilities
+ * @param {object} opts - { apiKey, modelId }
+ * @returns {Promise<object>}
+ */
+export async function annotate(promptStructure, caps, { apiKey, modelId } = {}) {
+  const { system, messages } = promptStructure || {};
+
+  let cachedContentName = null;
+
+  if (apiKey && system) {
+    try {
+      cachedContentName = await createCachedContent(system, caps, apiKey, modelId);
+    } catch (err) {
+    }
+  }
+
+  return {
+    messages: messages || [],
+    annotations: cachedContentName
+      ? [
+          {
+            type: 'cached_content',
+            name: cachedContentName,
+            ttl: caps?.cacheTTL?.['1h'] || 1_200_000,
+            note: 'Gemini cachedContent resource',
+          },
+        ]
+      : [],
+    expectedCacheWriteTokens: cachedContentName
+      ? await estimateTokens(system || '', { modelId: 'google/gemini-1.5-pro' })
+      : 0,
+    expectedCacheReadTokens: 0,
+  };
+}
+
+async function createCachedContent(systemText, caps, apiKey, modelId) {
+  // POST to https://generativelanguage.googleapis.com/v1/cachedContents
+  // Body: { model: 'gemini-1.5-pro', contents: [{ parts: [{ text: systemText }] }] }
+  // Returns: { name: 'cachedContents/abc123' }
+
+  const model = extractModelName(modelId);
+  const url = `${GEMINI_CACHE_ENDPOINT}/cachedContents?key=${apiKey}`;
+
+  // This is async but we don't want to block dispatch
+  // In production, this should be pre-cached
+  // For now, return null (defer to Phase C follow-up with live probing)
+  return null;
+}
+
+function extractModelName(modelId) {
+  const id = String(modelId || '').toLowerCase();
+  const match = id.match(/google\/(gemini-[^\/]+)/);
+  return match ? match[1] : 'gemini-1.5-pro';
+}
+
+export async function capabilities() {
+  return {
+    supportsAnnotations: false,
+    annotationType: 'cached_content',
+    requiresApiCall: true,
+    cacheEndpoint: GEMINI_CACHE_ENDPOINT,
+  };
+}

package/lib/cache-strategy-none.js

@@ -0,0 +1,30 @@
+/**
+ * lib/cache-strategy-none.js — Fallback for providers with no cache support.
+ *
+ * Used by DeepSeek and other providers without prompt caching.
+ * Returns messages as-is with no annotations.
+ */
+/**
+ * Annotate prompt structure for providers with no cache support.
+ *
+ * @param {object} promptStructure - { messages }
+ * @returns {Promise<object>}
+ */
+export async function annotate(promptStructure) {
+  const { messages } = promptStructure || {};
+
+  return {
+    messages: messages || [],
+    annotations: [],
+    expectedCacheWriteTokens: 0,
+    expectedCacheReadTokens: 0,
+  };
+}
+
+export async function capabilities() {
+  return {
+    supportsAnnotations: false,
+    annotationType: 'none',
+    notes: 'Provider does not support prompt caching',
+  };
+}

package/lib/cache-strategy-openai.js

@@ -0,0 +1,48 @@
+/**
+ * lib/cache-strategy-openai.js — OpenAI cache strategy.
+ *
+ * OpenAI uses automatic prefix caching (no annotations needed).
+ * Cache is triggered by stable prefixes in the prompt.
+ * The structured composition (static system + dynamic suffix) naturally triggers it.
+ */
+import { estimateTokens } from './token-engine.js';
+
+/**
+ * Annotate prompt structure for OpenAI models.
+ * Note: OpenAI uses automatic prefix caching — no annotations needed.
+ *
+ * @param {object} promptStructure - { system, messages }
+ * @param {object} caps - Provider capabilities
+ * @returns {Promise<object>}
+ */
+export async function annotate(promptStructure, caps) {
+  const { system, messages } = promptStructure || {};
+
+  // OpenAI: automatic prefix caching — no annotations
+  // Just ensure stable system prefix is at the start
+  const stablePrefix = system || '';
+  const expectedCacheableTokens = stablePrefix
+    ? await estimateTokens(stablePrefix, { modelId: 'openai/gpt-4o' })
+    : 0;
+
+  return {
+    messages: messages || [],
+    annotations: [
+      {
+        type: 'automatic_prefix',
+        note: 'OpenAI caches repeated prefixes automatically',
+        expectedPrefixTokens: expectedCacheableTokens,
+      },
+    ],
+    expectedCacheWriteTokens: expectedCacheableTokens,
+    expectedCacheReadTokens: 0, // OpenAI doesn't expose cache hit/miss
+  };
+}
+
+export async function capabilities() {
+  return {
+    supportsAnnotations: false,
+    annotationType: 'automatic_prefix',
+    visibleCacheMetrics: false,
+  };
+}