cli-five 0.2.15 → 0.2.17

package/src/util/merge.mjs

@@ -0,0 +1,170 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, extname } from 'node:path';
+
+const JSON_EXTENSIONS = new Set(['.json']);
+
+/**
+ * Surgically merge a named block into an existing file **without touching the
+ * rest of it**. Unlike init's blunt overwrite gate (which replaces whole files),
+ * `mergeBlock` is designed for `cli-five add` against repos that are already
+ * scaffolded.
+ *
+ * Two strategies, chosen by file extension:
+ *
+ *   JSON (.json)
+ *     `content` (a plain object or a JSON string) is deep-merged into the file.
+ *     Existing keys are preserved; overlapping scalar/array keys are replaced.
+ *     Passing `fenceKey` nests the patch under that top-level key instead of
+ *     merging at the root (e.g. `{ fenceKey: 'mcp' }` for `opencode.json`).
+ *
+ *   Markdown / other text
+ *     `content` is wrapped in HTML-comment fences derived from `markerFence`:
+ *       <!-- NAME_START -->
+ *       ...content...
+ *       <!-- NAME_END -->
+ *     If the fences already exist the body between them is replaced in place;
+ *     otherwise the block is appended. Re-running is idempotent.
+ *
+ * @param {string} filePath              Absolute path to the target file.
+ * @param {string|{name?:string,start?:string,end?:string}} markerFence
+ *        Block name (e.g. "codegraph"), or explicit `{ start, end }` markers.
+ * @param {string|object} content        Markdown body, or object / JSON string.
+ * @param {object} [options]
+ * @param {boolean} [options.dryRun]     Compute but do not write.
+ * @param {string|null} [options.fenceKey] JSON only — nest the merge under this key.
+ * @param {boolean} [options.track]      JSON only — record the block name under `$cliFive`.
+ * @param {string} [options.metaKey]     JSON only — metadata key (default `$cliFive`).
+ * @returns {{path:string, block:string, action:'created'|'updated'|'unchanged', dryRun:boolean}}
+ */
+export function mergeBlock(filePath, markerFence, content, options = {}) {
+  const { dryRun = false, fenceKey = null, track = false, metaKey = '$cliFive' } = options;
+  const block = fenceName(markerFence);
+
+  const ext = extname(filePath).toLowerCase();
+  const result = JSON_EXTENSIONS.has(ext)
+    ? mergeJson(filePath, block, content, { fenceKey, track, metaKey })
+    : mergeText(filePath, markerFence, content);
+
+  if (!dryRun && (result.action === 'created' || result.action === 'updated')) {
+    mkdirSync(dirname(filePath), { recursive: true });
+    writeFileSync(filePath, result.contents);
+  }
+
+  return { path: filePath, block, action: result.action, dryRun };
+}
+
+// ── Markdown / text ───────────────────────────────────────────────────
+
+function mergeText(filePath, markerFence, content) {
+  const { start, end } = fenceMarkers(markerFence);
+  const body = String(content ?? '').replace(/\s+$/, '');
+  const core = `${start}\n${body}\n${end}`;
+
+  if (!existsSync(filePath)) {
+    return { contents: `${core}\n`, action: 'created' };
+  }
+
+  const existing = readFileSync(filePath, 'utf8');
+  if (existing.trim() === '') {
+    return { contents: `${core}\n`, action: 'created' };
+  }
+
+  const pattern = new RegExp(`${escapeRegExp(start)}[\\s\\S]*?${escapeRegExp(end)}`);
+  if (pattern.test(existing)) {
+    const next = existing.replace(pattern, core);
+    return { contents: next, action: next === existing ? 'unchanged' : 'updated' };
+  }
+
+  const next = `${existing.replace(/\s+$/, '')}\n\n${core}\n`;
+  return { contents: next, action: 'updated' };
+}
+
+function fenceMarkers(markerFence) {
+  if (isPlainObject(markerFence) && markerFence.start && markerFence.end) {
+    return { start: markerFence.start, end: markerFence.end };
+  }
+  const name = fenceName(markerFence).toUpperCase().replace(/[^A-Z0-9]+/g, '_').replace(/^_+|_+$/g, '');
+  return { start: `<!-- ${name}_START -->`, end: `<!-- ${name}_END -->` };
+}
+
+// ── JSON ──────────────────────────────────────────────────────────────
+
+function mergeJson(filePath, block, content, { fenceKey, track, metaKey }) {
+  let existing = {};
+  if (existsSync(filePath)) {
+    const raw = readFileSync(filePath, 'utf8').trim();
+    if (raw) {
+      try {
+        existing = JSON.parse(raw);
+      } catch (err) {
+        throw new Error(`mergeBlock: ${filePath} is not valid JSON: ${err.message}`);
+      }
+    }
+  }
+
+  if (!isPlainObject(existing)) {
+    throw new Error(`mergeBlock: ${filePath} must contain a JSON object at the root`);
+  }
+
+  let patch = content;
+  if (typeof patch === 'string') {
+    try {
+      patch = JSON.parse(patch);
+    } catch (err) {
+      throw new Error(`mergeBlock: content for ${filePath} is not valid JSON: ${err.message}`);
+    }
+  }
+  if (!isPlainObject(patch)) {
+    throw new Error(`mergeBlock: content for ${filePath} must be a JSON object`);
+  }
+
+  const before = JSON.stringify(existing);
+
+  const target = fenceKey
+    ? (isPlainObject(existing[fenceKey]) ? existing[fenceKey] : (existing[fenceKey] = {}))
+    : existing;
+  deepMerge(target, patch);
+
+  if (track) {
+    const meta = isPlainObject(existing[metaKey]) ? existing[metaKey] : (existing[metaKey] = {});
+    const blocks = Array.isArray(meta.blocks) ? meta.blocks : (meta.blocks = []);
+    if (!blocks.includes(block)) blocks.push(block);
+  }
+
+  const contents = `${JSON.stringify(existing, null, 2)}\n`;
+  const action = before === JSON.stringify(existing) && existsSync(filePath) ? 'unchanged' : (existsSync(filePath) ? 'updated' : 'created');
+  return { contents, action };
+}
+
+function deepMerge(target, patch) {
+  for (const [key, value] of Object.entries(patch)) {
+    if (isPlainObject(value) && isPlainObject(target[key])) {
+      deepMerge(target[key], value);
+    } else if (isPlainObject(value)) {
+      target[key] = deepMerge({}, value);
+    } else if (Array.isArray(value)) {
+      target[key] = [...value];
+    } else {
+      target[key] = value;
+    }
+  }
+  return target;
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────
+
+function fenceName(markerFence) {
+  if (typeof markerFence === 'string' && markerFence.trim()) return markerFence.trim();
+  if (isPlainObject(markerFence) && typeof markerFence.name === 'string' && markerFence.name.trim()) {
+    return markerFence.name.trim();
+  }
+  throw new Error('mergeBlock: markerFence must be a non-empty string or { name }');
+}
+
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/src/util/project.mjs

@@ -0,0 +1,140 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+// README variants checked in order. First match wins.
+const README_CANDIDATES = [
+  'README.md',
+  'readme.md',
+  'Readme.md',
+  'README.MD',
+  'README.markdown',
+  'README.txt',
+  'README',
+];
+
+/**
+ * Best-effort auto-extraction of a project name and one-liner from the
+ * workspace itself (package.json and/or README), used by the minimal init
+ * interview so it only has to ask when the answer is genuinely missing or
+ * ambiguous.
+ *
+ * Returns:
+ *   {
+ *     name:     { value, ambiguous, sources: [{ source, value }] },
+ *     oneLiner: { value, ambiguous, sources: [{ source, value }] },
+ *   }
+ *
+ * `value` is the first candidate (a safe fallback), `ambiguous` is true when
+ * two or more distinct candidates were found. Callers should ask the user
+ * whenever `ambiguous` is true or `value` is empty.
+ */
+export function autoProjectInfo(cwd) {
+  const nameSources = [];
+  const oneLinerSources = [];
+
+  const pkgPath = join(cwd, 'package.json');
+  if (existsSync(pkgPath)) {
+    try {
+      const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+      if (isNonEmptyString(pkg?.name)) {
+        nameSources.push({ source: 'package.json', value: pkg.name.trim() });
+      }
+      if (isNonEmptyString(pkg?.description)) {
+        oneLinerSources.push({ source: 'package.json', value: pkg.description.trim() });
+      }
+    } catch {
+      /* malformed package.json — ignore */
+    }
+  }
+
+  for (const file of README_CANDIDATES) {
+    const filePath = join(cwd, file);
+    if (!existsSync(filePath)) continue;
+
+    let content;
+    try {
+      content = readFileSync(filePath, 'utf8');
+    } catch {
+      continue;
+    }
+
+    const hints = extractReadmeHints(content);
+    if (hints.name) nameSources.push({ source: file, value: hints.name });
+    if (hints.oneLiner) oneLinerSources.push({ source: file, value: hints.oneLiner });
+
+    break; // first README found wins — don't blend multiple README variants
+  }
+
+  return {
+    name: summarize(nameSources),
+    oneLiner: summarize(oneLinerSources),
+  };
+}
+
+/** Pull a name (first H1) and one-liner (first prose line) out of a README. */
+export function extractReadmeHints(content) {
+  const lines = String(content || '').split('\n');
+  let name = '';
+  let oneLiner = '';
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i].trim();
+    if (!line) continue;
+
+    if (!name) {
+      const h1 = /^#\s+(.+?)\s*$/.exec(line);
+      if (h1) {
+        name = stripInlineMarkdown(h1[1]);
+        continue;
+      }
+    }
+
+    // Wait for the first H1 before reading prose — otherwise the README may
+    // start with a logo/badge that is not a name.
+    if (!name || oneLiner) continue;
+
+    if (isProseLine(line)) {
+      oneLiner = line.length > 120 ? `${line.slice(0, 117)}...` : line;
+    }
+  }
+
+  return { name, oneLiner };
+}
+
+function summarize(sources) {
+  if (sources.length === 0) {
+    return { value: '', ambiguous: false, sources: [] };
+  }
+
+  const distinct = [];
+  for (const entry of sources) {
+    if (!distinct.includes(entry.value)) distinct.push(entry.value);
+  }
+
+  return {
+    value: sources[0].value,
+    ambiguous: distinct.length > 1,
+    sources,
+  };
+}
+
+function isProseLine(line) {
+  // Skip headings, badges/images, code fences, lists, tables, blockquotes, HTML.
+  if (/^[#>|`*\-_]/.test(line)) return false;
+  if (/^\[!\[/.test(line)) return false;
+  if (/^!\[/.test(line)) return false;
+  if (/^<[a-zA-Z!/]/.test(line)) return false;
+  if (/^\|/.test(line)) return false;
+  return true;
+}
+
+function stripInlineMarkdown(value) {
+  return String(value)
+    .replace(/\[([^\]]+)\]\([^)]*\)/g, '$1') // [text](url) → text
+    .replace(/[*_`]/g, '')
+    .trim();
+}
+
+function isNonEmptyString(value) {
+  return typeof value === 'string' && value.trim().length > 0;
+}

package/templates/AGENTS.md.tmpl

@@ -24,4 +24,3 @@ and Copilot all read `AGENTS.md` per the [agents.md](https://agents.md) conventi
 4. Per-agent memory lives in `histories/<agent>.md`.
 5. Append a session summary to `agent-diary.md` when work completes.
 
-{{CODEGRAPH_BLOCK}}

package/templates/opencode/plugin/jev-tier-router/index.js

@@ -0,0 +1,187 @@
+// cli-five jev-tier-router plugin (OpenCode).
+//
+// Ships a `local_tier_heuristic` tool that classifies a task description into
+// cli-five's tier vocabulary: trivial | minor | major.
+//
+// TRUTHFUL NAMING: this is a LOCAL heuristic. It does NOT call Jev. As of
+// 2026-09-26, jev-harness's `route` subcommand exposes no custom-criteria
+// interface (it emits its own fixed tier vocabulary: deterministic /
+// lightweight_system2 / heavy_system2) and returns a constant confidence
+// (0.88) under its offline/mock engine, so it cannot be thresholded on.
+// The name `local_tier_heuristic` is deliberate — do not revive `jev_tier_route`
+// unless/until real Jev wiring is verified. See JEVR_SWAP_POINT below.
+//
+// Fail-open: if anything goes wrong the tool reports `available: false` and
+// tier "major" (the expensive tier), so the Planner falls back to its own
+// judgment. It never throws in a way that would break the Planner's turn.
+
+import { appendFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const CONFIDENCE_CUTOFF = 0.6;
+const FALLBACK_TIER = 'major';
+
+const TIERS = ['trivial', 'minor', 'major'];
+
+// Weighted signals. `strong` matches dominate; `moderate` accumulate.
+const SIGNALS = [
+  // trivial — mechanical, single-token, no reasoning
+  { tier: 'trivial', weight: 3, re: /\b(typo|typos|whitespace|lint|linting|format|formatting|rename|renaming|comment|comments|docstring|spelling|indent(ation)?)\b/i },
+  { tier: 'trivial', weight: 2, re: /\b(README|changelog|CHANGELOG|\.md\b|docs?)\b/i },
+  { tier: 'trivial', weight: 2, re: /\b(one[- ]?line|single[- ]?(file|line)|small tweak|quick fix|minor tweak)\b/i },
+  { tier: 'trivial', weight: 2, re: /\b(delete|remove)\b[\s\w]{0,20}\b(console\.log|stray|unused|dead code|tmp|temp file)\b/i },
+
+  // major — architectural, cross-cutting, ambiguous scope
+  { tier: 'major', weight: 3, re: /\b(architect(ure|ural)?|redesign|rearchitect|rewrite|overhaul|migrat(e|ion)|replatform|distributed|scalab(le|ility)|multi[- ]?(tenant|region|service))\b/i },
+  { tier: 'major', weight: 3, re: /\b(entire|whole|across (the )?(codebase|repo(sitory)?|project)|end[- ]to[- ]end|system[- ]wide)\b/i },
+  { tier: 'major', weight: 2, re: /\b(concurren(cy|t)|race condition|deadlock|transaction(al)?|consistency|eventual consistency|saga|retry (architecture|strategy)|queue|scheduler|orchestrat(e|ion))\b/i },
+  { tier: 'major', weight: 2, re: /\b(performance|latency|throughput|optimi[sz]e|profil(e|ing)|security|auth(entication|orization)?|encryption|compliance|HIPAA|SOC ?2|GDPR)\b/i },
+  { tier: 'major', weight: 1, re: /\b(design|feature|implement|build|add support for|new (module|service|system))\b/i },
+
+  // minor — bounded, local, incremental
+  { tier: 'minor', weight: 3, re: /\b(validation|validate|error handling|error message|edge case|bug ?fix|fix (a |the )?bug|patch|handle null|guard clause)\b/i },
+  { tier: 'minor', weight: 2, re: /\b(component|function|method|handler|endpoint|form|button|modal|tooltip|dropdown)\b/i },
+  { tier: 'minor', weight: 2, re: /\b(refactor|extract|rename (the )?(function|method|class|module)|tidy|clean ?up)\b/i },
+  { tier: 'minor', weight: 1, re: /\b(add|update|adjust|tweak|improve|tidy)\b/i },
+];
+
+/**
+ * Classify a task description locally.
+ *
+ * Returns { tier, confidence, rationale, available, source }.
+ * Ambiguity fails toward the expensive tier (major), never the cheap one.
+ */
+export function classifyTask(description) {
+  const text = String(description ?? '').trim();
+  if (!text) {
+    return {
+      tier: FALLBACK_TIER,
+      confidence: 0,
+      rationale: 'Empty task description; defaulting to the expensive tier.',
+      available: true,
+      source: 'local_heuristic',
+    };
+  }
+
+  const scores = { trivial: 0, minor: 0, major: 0 };
+  const hits = { trivial: [], minor: [], major: [] };
+
+  for (const signal of SIGNALS) {
+    if (signal.re.test(text)) {
+      scores[signal.tier] += signal.weight;
+      hits[signal.tier].push(signal.re.source.slice(0, 40));
+    }
+  }
+
+  // Length is a weak major signal: long, multi-clause prompts rarely stay local.
+  const words = text.split(/\s+/).filter(Boolean).length;
+  if (words > 25) scores.major += 1;
+  if (words > 60) scores.major += 1;
+
+  const ranked = TIERS.map((tier) => ({ tier, score: scores[tier] })).sort((a, b) => b.score - a.score);
+  const [top, second] = ranked;
+
+  if (top.score === 0) {
+    // Nothing matched — ambiguous. Fail toward the expensive tier.
+    return {
+      tier: FALLBACK_TIER,
+      confidence: 0.3,
+      rationale: 'No tier signals matched; ambiguous, so defaulting to the expensive tier.',
+      available: true,
+      source: 'local_heuristic',
+    };
+  }
+
+  const total = TIERS.reduce((sum, tier) => sum + scores[tier], 0);
+  const separation = (top.score - (second?.score ?? 0)) / top.score;
+  const share = top.score / total;
+  let confidence = 0.5 * share + 0.5 * separation;
+
+  // A single weak hit with no corroboration is not a confident call.
+  if (top.score <= 1) confidence = Math.min(confidence, 0.5);
+
+  confidence = Math.round(confidence * 100) / 100;
+
+  if (confidence < CONFIDENCE_CUTOFF) {
+    return {
+      tier: FALLBACK_TIER,
+      confidence,
+      rationale: `Low confidence (${confidence} < ${CONFIDENCE_CUTOFF}) between ${top.tier} and ${second?.tier ?? 'n/a'}; defaulting to the expensive tier.`,
+      available: true,
+      source: 'local_heuristic',
+    };
+  }
+
+  return {
+    tier: top.tier,
+    confidence,
+    rationale: `Matched ${hits[top.tier].length} ${top.tier} signal(s).`,
+    available: true,
+    source: 'local_heuristic',
+  };
+}
+
+// ── JEVR_SWAP_POINT ───────────────────────────────────────────────────
+// Real-Jev wiring would replace classifyTask() above with a shell-out to
+//   jev-harness route --json --task "<description>"
+// and map the returned `selected_tier` onto cli-five's tiers, thresholding on
+// `confidence`. It is NOT wired because, as of 2026-09-26, `route` exposes no
+// custom-criteria interface, emits a fixed vocabulary, and returns a constant
+// confidence under the offline engine. Re-verify before swapping.
+// Exact call site: the `execute` handler below that calls classifyTask().
+// ──────────────────────────────────────────────────────────────────────
+
+export const __testables = { classifyTask, CONFIDENCE_CUTOFF, FALLBACK_TIER };
+
+export default {
+  id: 'cli-five-jev-tier-router',
+  setup: async (ctx) => {
+    if (!ctx || !ctx.tool || typeof ctx.tool.transform !== 'function') return;
+
+    await ctx.tool.transform((tools) => {
+      tools.add({
+        name: 'local_tier_heuristic',
+        description:
+          'Classify a task description into cli-five\'s tier vocabulary (trivial | minor | major) using a local heuristic. ' +
+          'Call this once per task, before planning. Trust the returned tier when confidence >= 0.6; otherwise fall back to "major". ' +
+          'This is a local heuristic, not a Jev call.',
+        input: {
+          type: 'object',
+          properties: {
+            description: {
+              type: 'string',
+              description: 'The task to classify, verbatim (the user request or planning prompt).',
+            },
+          },
+          required: ['description'],
+          additionalProperties: false,
+        },
+        async execute(input) {
+          try {
+            const result = classifyTask(input?.description);
+            return { content: JSON.stringify(result) };
+          } catch (err) {
+            // Fail-open: never break the caller's turn.
+            try {
+              appendFileSync(
+                process.env.CLI_FIVE_LOGFILE || join(process.cwd(), '.opencode', 'journals', 'jev-tier-router.log'),
+                `${new Date().toISOString()} local_tier_heuristic fail-open: ${err?.message || err}\n`,
+              );
+            } catch {
+              /* logging is best-effort */
+            }
+            return {
+              content: JSON.stringify({
+                tier: FALLBACK_TIER,
+                confidence: 0,
+                rationale: 'Tier classifier unavailable; defaulting to the expensive tier.',
+                available: false,
+                source: 'local_heuristic',
+              }),
+            };
+          }
+        },
+      });
+    });
+  },
+};

package/templates/opencode/plugin/jev-tier-router/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "cli-five-jev-tier-router",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./index.js"
+  }
+}