@geraldmaron/construct 1.0.0 → 1.0.2

package/lib/cache-strategy.js

@@ -0,0 +1,91 @@
+/**
+ * lib/cache-strategy.js — Model-agnostic cache strategy layer.
+ *
+ * Follows embeddings-engine.js pattern:
+ *   - This file is the model-agnostic router.
+ *   - Provider-specific logic lives in cache-strategy-*.js adapters.
+ *   - All adapters return the same annotation shape.
+ *
+ * Consumes provider capabilities from provider-capabilities.js.
+ * Emits provider-specific annotations for the dispatch layer.
+ *
+ * Standard annotation interface (all adapters return this shape):
+ *   - messages: array (annotated message array ready for LLM API)
+ *   - annotations: array (provider-specific annotation metadata)
+ *   - expectedCacheWriteTokens: number | null
+ *   - expectedCacheReadTokens: number | null
+ */
+import { resolveProviderCapabilities } from './provider-capabilities.js';
+import { estimateTokens } from './token-engine.js';
+
+const ADAPTERS = {
+  anthropic: () => import('./cache-strategy-anthropic.js'),
+  google: () => import('./cache-strategy-google.js'),
+  openai: () => import('./cache-strategy-openai.js'),
+  none: () => import('./cache-strategy-none.js'),
+};
+
+function resolveAdapterKey(caps) {
+  const format = caps?.annotationFormat || 'none';
+  if (ADAPTERS[format]) return format;
+  return 'none';
+}
+
+/**
+ * Annotate a prompt structure with provider-specific cache annotations.
+ *
+ * @param {object} promptStructure - { system, messages, staticEndIndex, totalTokens }
+ * @param {string} modelId
+ * @returns {Promise<object>} - { messages, annotations, expectedCacheWriteTokens }
+ */
+export async function annotatePrompt(promptStructure, modelId) {
+  const caps = await resolveProviderCapabilities(modelId);
+  const adapterKey = resolveAdapterKey(caps);
+
+  try {
+    const { annotate } = await ADAPTERS[adapterKey]();
+    return await annotate(promptStructure, caps);
+  } catch {
+    // Fallback to none
+    const { annotate } = await ADAPTERS.none();
+    return await annotate(promptStructure, caps);
+  }
+}
+
+/**
+ * Estimate how many tokens should be cacheable from a prompt structure.
+ *
+ * @param {object} fragments - prompt fragments array
+ * @param {number} staticEndIndex - last index that is cacheable
+ * @param {object} opts - { modelId }
+ * @returns {Promise<number>}
+ */
+export async function estimateCacheableTokens(fragments, staticEndIndex, { modelId = '' } = {}) {
+  if (!Array.isArray(fragments) || staticEndIndex < 0) return 0;
+
+  let total = 0;
+  const endIdx = Math.min(staticEndIndex + 1, fragments.length);
+
+  for (let i = 0; i < endIdx; i++) {
+    const frag = fragments[i];
+    if (frag && frag.content) {
+      total += await estimateTokens(frag.content, { modelId });
+    }
+  }
+
+  return total;
+}
+
+/**
+ * Resolve cache TTL in tokens (not ms) for a given provider.
+ *
+ * @param {string} modelId
+ * @returns {Promise<{ ttl5m: number, ttl1h: number }>}
+ */
+export async function resolveCacheTTL(modelId) {
+  const caps = await resolveProviderCapabilities(modelId);
+  return {
+    ttl5m: caps?.cacheTTL?.['5m'] || 0,
+    ttl1h: caps?.cacheTTL?.['1h'] || 0,
+  };
+}

package/lib/claude-allow.mjs

@@ -0,0 +1,149 @@
+/**
+ * lib/claude-allow.mjs — read / mutate / audit ~/.claude/settings.json permissions.allow.
+ *
+ * Claude Code's auto-classifier denies tool calls the user hasn't pre-authorized
+ * via `permissions.allow`. Editing that file from within Claude Code is blocked
+ * (self-modification of the agent's own permissions). This module is the
+ * outside path: Construct's CLI + SessionStart hook use it to surface gaps,
+ * propose entries, and apply them atomically.
+ *
+ * Gap detection is heuristic, not authoritative. We look at recent git
+ * branch names and suggest force-push allowlist entries for prefixes the user
+ * actually uses but hasn't allowlisted. That's the single biggest source of
+ * classifier friction; broader heuristics would be guess-work.
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { execSync } from 'node:child_process';
+import { join, dirname } from 'node:path';
+import { homedir } from 'node:os';
+
+const DEFAULT_SETTINGS_PATH = join(homedir(), '.claude', 'settings.json');
+
+const SAFE_PREFIXES = ['feat', 'fix', 'chore', 'docs', 'refactor', 'perf', 'cleanup', 'test', 'build', 'ci', 'style'];
+const NEVER_PREFIXES = ['claude', 'agent', 'main', 'master', 'dev'];
+
+function readSettings(path = DEFAULT_SETTINGS_PATH) {
+  if (!existsSync(path)) return { exists: false, settings: {}, path };
+  try {
+    return { exists: true, settings: JSON.parse(readFileSync(path, 'utf8')), path };
+  } catch (err) {
+    return { exists: true, settings: {}, path, parseError: err.message };
+  }
+}
+
+function writeSettings(settings, path = DEFAULT_SETTINGS_PATH) {
+  mkdirSync(dirname(path), { recursive: true });
+  const text = `${JSON.stringify(settings, null, 2)}\n`;
+  writeFileSync(path, text, 'utf8');
+}
+
+export function listAllowEntries({ path = DEFAULT_SETTINGS_PATH } = {}) {
+  const { settings } = readSettings(path);
+  return Array.isArray(settings?.permissions?.allow) ? [...settings.permissions.allow] : [];
+}
+
+/**
+ * Add one or more allowlist patterns. Idempotent — duplicates are dropped.
+ * Returns { added: string[], existing: string[], total: number }.
+ */
+export function addAllowEntries(entries, { path = DEFAULT_SETTINGS_PATH } = {}) {
+  const incoming = (Array.isArray(entries) ? entries : [entries]).filter((e) => typeof e === 'string' && e.trim());
+  const { settings } = readSettings(path);
+  if (!settings.permissions) settings.permissions = {};
+  if (!Array.isArray(settings.permissions.allow)) settings.permissions.allow = [];
+
+  const existingSet = new Set(settings.permissions.allow);
+  const added = [];
+  const existing = [];
+  for (const entry of incoming) {
+    if (existingSet.has(entry)) existing.push(entry);
+    else { settings.permissions.allow.push(entry); existingSet.add(entry); added.push(entry); }
+  }
+
+  if (added.length > 0) writeSettings(settings, path);
+  return { added, existing, total: settings.permissions.allow.length, path };
+}
+
+/**
+ * Remove patterns. Returns { removed: string[], notFound: string[], total }.
+ */
+export function removeAllowEntries(entries, { path = DEFAULT_SETTINGS_PATH } = {}) {
+  const incoming = (Array.isArray(entries) ? entries : [entries]).filter((e) => typeof e === 'string' && e.trim());
+  const { settings } = readSettings(path);
+  if (!Array.isArray(settings?.permissions?.allow)) return { removed: [], notFound: incoming, total: 0, path };
+
+  const current = new Set(settings.permissions.allow);
+  const removed = [];
+  const notFound = [];
+  for (const entry of incoming) {
+    if (current.has(entry)) { current.delete(entry); removed.push(entry); }
+    else notFound.push(entry);
+  }
+
+  if (removed.length > 0) {
+    settings.permissions.allow = Array.from(current);
+    writeSettings(settings, path);
+  }
+  return { removed, notFound, total: settings.permissions.allow.length, path };
+}
+
+/**
+ * Scan recent local branches for prefix patterns the user actually uses.
+ * Returns the distinct safe prefixes present in the working tree, excluding
+ * NEVER_PREFIXES (main/master/dev/claude/agent).
+ */
+export function detectBranchPrefixes({ cwd = process.cwd(), limit = 200 } = {}) {
+  try {
+    const out = execSync(`git for-each-ref --count=${limit} --sort=-committerdate --format='%(refname:short)' refs/heads/`, {
+      cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    const branches = out.split('\n').map((s) => s.trim().replace(/^'|'$/g, '')).filter(Boolean);
+    const prefixes = new Set();
+    for (const b of branches) {
+      const idx = b.indexOf('/');
+      if (idx <= 0) continue;
+      const prefix = b.slice(0, idx);
+      if (NEVER_PREFIXES.includes(prefix)) continue;
+      if (!SAFE_PREFIXES.includes(prefix)) continue;
+      prefixes.add(prefix);
+    }
+    return Array.from(prefixes).sort();
+  } catch { return []; }
+}
+
+/**
+ * Compare branch prefixes against existing allowlist; return entries the user
+ * almost certainly wants but hasn't added. Conservative — only force-push
+ * entries, only for prefixes that are SAFE.
+ */
+export function detectAllowlistGaps({ cwd = process.cwd(), path = DEFAULT_SETTINGS_PATH } = {}) {
+  const allow = listAllowEntries({ path });
+  const have = new Set(allow);
+  const prefixes = detectBranchPrefixes({ cwd });
+  const gaps = [];
+  for (const prefix of prefixes) {
+    const pattern = `Bash(git push --force-with-lease origin ${prefix}/*)`;
+    if (!have.has(pattern)) gaps.push({ prefix, pattern });
+  }
+  return gaps;
+}
+
+/**
+ * One-line posture string for SessionStart injection. Keeps the surface small:
+ * count of current entries + at most 3 suggested gaps. Empty string when
+ * nothing to surface so the SessionStart banner stays clean.
+ */
+export function buildPermissionPostureLine({ cwd = process.cwd(), path = DEFAULT_SETTINGS_PATH } = {}) {
+  const allow = listAllowEntries({ path });
+  const gaps = detectAllowlistGaps({ cwd, path });
+  if (gaps.length === 0) return '';
+  const sample = gaps.slice(0, 3).map((g) => g.prefix).join(', ');
+  const more = gaps.length > 3 ? ` (+${gaps.length - 3} more)` : '';
+  return (
+    `\n## Permission posture\n` +
+    `Allowlist: ${allow.length} entr${allow.length === 1 ? 'y' : 'ies'} in ${path}.\n` +
+    `Suggested gaps: force-push allowlist missing for ${sample}${more}. ` +
+    `Close via \`construct claude:allow check --apply\`.\n`
+  );
+}