@ucsandman/legcli 0.8.0 → 0.9.0

package/src/harness/vendor/agnostic-ai/engine/harness/common.cjs

@@ -0,0 +1,375 @@
+/**
+ * engine/harness/common.cjs — helpers shared by every source and target adapter.
+ *
+ * Nothing here knows a client. Paths, guarded writes, directory links, managed
+ * regions inside user-owned files, frontmatter, TOML string escaping, and the
+ * secret detector that keeps token values out of generated config.
+ */
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const crypto = require('crypto');
+const { spawnSync } = require('child_process');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+
+// ---------------------------------------------------------------------------
+// Embedding configuration
+//
+// The engine runs as this repo's own CLI and as a library inside another
+// product. Everything a host may need to own is here, and the defaults are
+// exactly what the repo did before this object existed:
+//   brand.mark    the ownership claim written into every generated file (and
+//                 the string makeWriter looks for to recognise a file as ours)
+//   brand.region  the name inside managed-region markers
+//   brand.id      a safe identifier for a key a host owns inside a user file
+//   secretPatterns  regexes replacing core/safety/guards.json (null = read it)
+//   shimPath      the hook shim targets point at (null = engine/hooks/shim.cjs)
+// `configure()` merges; `GENERATED_MARK` below is a live getter over it.
+// ---------------------------------------------------------------------------
+const config = {
+  brand: { id: 'agnostic-ai', mark: 'GENERATED by agnostic-ai', region: 'agnostic-ai' },
+  secretPatterns: null,
+  shimPath: null,
+  // Directories besides the user's home that a rules `@import` may resolve into
+  // (null = this repo). A host that ships no importable rules passes [].
+  importRoots: null,
+};
+
+let patternCache = null;
+
+function configure(opts = {}) {
+  if (opts.brand) config.brand = Object.assign({}, config.brand, opts.brand);
+  if (opts.secretPatterns !== undefined) { config.secretPatterns = opts.secretPatterns; patternCache = null; }
+  if (opts.shimPath !== undefined) config.shimPath = opts.shimPath;
+  if (opts.importRoots !== undefined) config.importRoots = opts.importRoots;
+  return config;
+}
+
+function importRoots() {
+  return Array.isArray(config.importRoots) ? config.importRoots : [ROOT];
+}
+
+function expandPath(p, home = os.homedir()) {
+  if (!p) return '';
+  let resolved = String(p).replace(/%([^%]+)%/g, (_, n) => process.env[n] || '');
+  if (resolved === '~') return home;
+  if (resolved.startsWith('~/') || resolved.startsWith('~\\')) return path.join(home, resolved.slice(2));
+  if (!path.isAbsolute(resolved)) return path.join(ROOT, resolved);
+  return resolved;
+}
+
+// Path comparison folds case where the filesystem does (Windows, macOS) and
+// keeps it where two spellings are two files (Linux).
+const foldCase = (s) => (process.platform === 'linux' ? s : s.toLowerCase());
+
+/** Render an absolute path back to `~/...` for display and for generated headers. */
+function tildePath(p, home = os.homedir()) {
+  const norm = (s) => foldCase(path.resolve(s).replace(/\\/g, '/'));
+  const abs = path.resolve(p).replace(/\\/g, '/');
+  return norm(p).startsWith(norm(home) + '/') ? '~' + abs.slice(path.resolve(home).length) : abs;
+}
+
+const readText = (p) => { try { return fs.readFileSync(p, 'utf8'); } catch (_) { return null; } };
+const readJSON = (p) => { const raw = readText(p); if (raw == null) return null; try { return JSON.parse(raw); } catch (_) { return undefined; } };
+const sha = (text) => crypto.createHash('sha256').update(String(text), 'utf8').digest('hex');
+
+// ---------------------------------------------------------------------------
+// Secret detection (patterns from core/safety/guards.json, fail closed)
+// ---------------------------------------------------------------------------
+const FALLBACK_SENSITIVE = [
+  '(?i)sk-[0-9a-zA-Z]{20,}', '(?i)ghp_[0-9a-zA-Z]{36}', '(?i)xox[baprs]-[0-9a-zA-Z-]{10,}',
+  '(?i)AIza[0-9A-Za-z-_]{35}', '(?i)-----BEGIN [A-Z ]*PRIVATE KEY-----', '(?i)bearer\\s+[a-zA-Z0-9_\\-\\.]{20,}',
+];
+
+const toRegExp = (p) => (p instanceof RegExp ? p : new RegExp(String(p).replace(/^\(\?i\)/, ''), String(p).startsWith('(?i)') ? 'i' : ''));
+
+// Compiled once per configuration: looksSecret() runs on every config value a
+// capture sees, and re-reading guards.json for each one showed up in a host's
+// hand-off timing.
+function sensitivePatterns() {
+  if (patternCache) return patternCache;
+  if (Array.isArray(config.secretPatterns) && config.secretPatterns.length) {
+    patternCache = config.secretPatterns.map(toRegExp);
+    return patternCache;
+  }
+  const guards = readJSON(path.join(ROOT, 'core', 'safety', 'guards.json'));
+  const list = guards && guards.guards && guards.guards.secretScan && guards.guards.secretScan.sensitivePatterns;
+  patternCache = (list && list.length ? list : FALLBACK_SENSITIVE).map(toRegExp);
+  return patternCache;
+}
+
+/**
+ * True when a config VALUE looks like a credential: matches a known token
+ * shape, or its key names a secret and the value is long and high-entropy.
+ */
+const SECRET_KEY = /(key|token|secret|password|passwd|pwd|credential|auth|dsn)/i;
+const charClasses = (v) => [/[a-z]/, /[A-Z]/, /\d/, /[^A-Za-z0-9]/].filter((re) => re.test(v)).length;
+// A long, space-free, non-path value that is all hex or mixes three classes
+// is a credential shape whatever its key is called.
+function highEntropy(v) {
+  if (v.length < 32 || /\s/.test(v) || /[\\/]/.test(v)) return false;
+  if (/^[0-9a-f]+$/i.test(v)) return true;
+  return charClasses(v) >= 3;
+}
+// A URL carries a credential in its userinfo password or in a query value
+// that is itself secret-shaped.
+function urlSecret(v, keyed) {
+  let u;
+  try { u = new URL(v); } catch (_) { return false; }
+  if (u.password) return true;
+  for (const [k, val] of u.searchParams) if (SECRET_KEY.test(k) && val.length >= 16) return true;
+  // under a secret-named key, a long mixed path segment is the credential (a
+  // webhook URL, a signed link); under any other key a URL is an address
+  if (keyed) for (const seg of u.pathname.split('/')) if (seg.length >= 16 && /\d/.test(seg) && /[a-z]/i.test(seg)) return true;
+  return false;
+}
+
+function looksSecret(key, value) {
+  if (typeof value !== 'string' || !value) return false;
+  if (/^\$\{[A-Za-z0-9_]+\}$/.test(value) || /^\$[A-Za-z0-9_]+$/.test(value)) return false; // already a reference
+  if (sensitivePatterns().some((re) => re.test(value))) return true;
+  if (/^[a-z][a-z0-9+.-]*:\/\//i.test(value)) return urlSecret(value, SECRET_KEY.test(String(key || '')));
+  if (highEntropy(value)) return true;
+  if (!SECRET_KEY.test(String(key || ''))) return false;
+  if (value.length < 16) return false;
+  if (/^(true|false|\d+)$/i.test(value)) return false;
+  if (/\s/.test(value)) return false;
+  // under a secret-named key, one class is enough once the value is long
+  return charClasses(value) >= 2 || value.length >= 32;
+}
+
+/** An MCP server URL that carries a credential in its userinfo, its query or a long token-like path segment. */
+const urlCarriesCredential = (v) => typeof v === 'string' && urlSecret(v, true);
+
+/** Every span of `text` that matches a known token shape, for scanning free text. */
+function findSecrets(text) {
+  const out = [];
+  const s = String(text == null ? '' : text);
+  for (const re of sensitivePatterns()) {
+    const g = new RegExp(re.source, re.flags.includes('g') ? re.flags : re.flags + 'g');
+    let m;
+    while ((m = g.exec(s)) !== null) { out.push(m[0]); if (m[0].length === 0) g.lastIndex++; }
+  }
+  // two patterns matching one span (a host's list beside this one) is one secret
+  return [...new Set(out)];
+}
+
+/** The same text with every token shape replaced; used before a capture is saved. */
+function redactSecrets(text) {
+  let s = String(text == null ? '' : text);
+  for (const re of sensitivePatterns()) s = s.replace(new RegExp(re.source, re.flags.includes('g') ? re.flags : re.flags + 'g'), '[REDACTED]');
+  return s;
+}
+
+// ---------------------------------------------------------------------------
+// Guarded writes (same semantics as engine/sync/sync.cjs::writeGuarded)
+// ---------------------------------------------------------------------------
+function backupFile(backupsDir, tag, targetPath) {
+  fs.mkdirSync(backupsDir, { recursive: true });
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const dest = path.join(backupsDir, `${tag}-${path.basename(targetPath)}-${stamp}.bak`);
+  fs.copyFileSync(targetPath, dest);
+  return dest;
+}
+
+/**
+ * Build the `write(path, content, opts)` function handed to adapters.
+ *   state.files[path] = sha of what we last wrote
+ *   state.drift[path] = sha of a hand edit we already backed up (backup once)
+ * A file whose first line still carries GENERATED_MARK (or the given `header`)
+ * is ours to overwrite whatever touched it: the header IS the ownership claim.
+ */
+function makeWriter({ state, backupsDir, tag, check, force, log }) {
+  state.files = state.files || {};
+  state.drift = state.drift || {};
+  return function write(targetPath, content, opts = {}) {
+    const exists = fs.existsSync(targetPath);
+    const existing = exists ? fs.readFileSync(targetPath, 'utf8') : null;
+    if (existing === content) {
+      state.files[targetPath] = sha(content);
+      return { action: 'unchanged', backup: null };
+    }
+    const recorded = Object.prototype.hasOwnProperty.call(state.files, targetPath);
+    // The ownership claim is the GENERATED mark inside the preamble (a title
+    // line usually comes first). A title alone is not a claim: a user who keeps
+    // the title and deletes the mark has taken the file over.
+    const headLines = existing === null ? [] : existing.split(/\r?\n/, 6).slice(0, 5);
+    const stillOurs = Boolean(existing !== null && headLines.some((l) => l.includes(config.brand.mark)));
+    const managedRegion = Boolean(opts.region); // caller only replaces a marked region; the rest is the user's
+    const drifted = Boolean(exists && recorded && state.files[targetPath] !== sha(existing) && !stillOurs && !managedRegion);
+    if (check) return { action: drifted ? 'skipped-hand-edited' : 'would-write', backup: null };
+    let backup = null;
+    if (drifted) {
+      if (state.drift[targetPath] !== sha(existing)) {
+        backup = backupFile(backupsDir, tag, targetPath);
+        state.drift[targetPath] = sha(existing);
+      }
+      if (!force) {
+        if (log) log(`  ! skipped (hand-edited): ${targetPath}${backup ? ` (backup ${backup})` : ''}`);
+        return { action: 'skipped-hand-edited', backup };
+      }
+    } else if (exists) {
+      backup = backupFile(backupsDir, tag, targetPath);
+    }
+    fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+    fs.writeFileSync(targetPath, content, 'utf8');
+    state.files[targetPath] = sha(content);
+    delete state.drift[targetPath];
+    return { action: 'written', backup };
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Managed regions inside files the user also owns
+// ---------------------------------------------------------------------------
+const regionMarkers = (component, comment = '#') => ({
+  start: `${comment} >>> ${config.brand.region} ${component} start (generated, do not edit)`,
+  end: `${comment} <<< ${config.brand.region} ${component} end`,
+});
+
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+/** Replace (or append) the marked region; everything outside is preserved byte for byte. */
+function replaceRegion(text, markers, body) {
+  const re = new RegExp(`\\n*${escapeRe(markers.start)}[\\s\\S]*?${escapeRe(markers.end)}\\n?`, 'g');
+  const region = body.trim() ? `${markers.start}\n${body.trimEnd()}\n${markers.end}\n` : '';
+  const base = (text || '').replace(re, '\n');
+  if (!region) return base.replace(/\n{3,}/g, '\n\n');
+  return base.replace(/\n{3,}/g, '\n\n').replace(/\s*$/, base.trim() ? '\n\n' : '') + region;
+}
+
+function readRegion(text, markers) {
+  const re = new RegExp(`${escapeRe(markers.start)}\\n([\\s\\S]*?)${escapeRe(markers.end)}`);
+  const m = (text || '').match(re);
+  return m ? m[1] : null;
+}
+
+// ---------------------------------------------------------------------------
+// Directory links (junction on Windows, symlink elsewhere). Never replaces a real dir.
+// ---------------------------------------------------------------------------
+const plainPath = (p) => foldCase(path.resolve(String(p).replace(/^\\\\\?\\/, '')).replace(/\\/g, '/'));
+
+function readLinkTarget(p) {
+  try { return fs.readlinkSync(p); } catch (_) { return null; }
+}
+
+function link(src, dest, { check } = {}) {
+  const current = readLinkTarget(dest);
+  if (current && plainPath(current) === plainPath(src)) return { action: 'unchanged' };
+  // A real directory is never replaced, in check mode or otherwise; report the
+  // same verdict both ways so --check after a clean apply stays clean.
+  if (!current && fs.existsSync(dest)) return { action: 'skipped-real-directory' };
+  if (check) return { action: 'would-link' };
+  if (current) fs.rmSync(dest, { recursive: true, force: true });
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  try {
+    fs.symlinkSync(src, dest, 'junction');
+  } catch (err) {
+    if (process.platform !== 'win32') throw err;
+    // cmd.exe re-parses its command line whatever spawnSync was given, so a
+    // path carrying one of its metacharacters is refused rather than quoted
+    // and hoped for; the adapter reports the skill as not linked.
+    if (/[&|^<>()%!"]/.test(dest) || /[&|^<>()%!"]/.test(src)) throw new Error(`refusing mklink fallback: a path carries a cmd metacharacter (${err.message})`);
+    const r = spawnSync('cmd', ['/c', 'mklink', '/J', dest, src], { stdio: 'pipe', windowsHide: true, encoding: 'utf8' });
+    if (r.status !== 0) throw new Error(`mklink /J failed: ${(r.stderr || r.stdout || '').trim() || err.message}`);
+  }
+  return { action: 'linked' };
+}
+
+function unlinkIfLink(dest) {
+  if (readLinkTarget(dest) === null) return false;
+  fs.rmSync(dest, { recursive: true, force: true });
+  return true;
+}
+
+// ---------------------------------------------------------------------------
+// Markdown frontmatter + TOML strings
+// ---------------------------------------------------------------------------
+function parseFrontmatter(md) {
+  const m = String(md).match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
+  if (!m) return { meta: {}, body: String(md) };
+  const meta = {};
+  let key = null;
+  for (const line of m[1].split(/\r?\n/)) {
+    const kv = line.match(/^([A-Za-z_][A-Za-z0-9_-]*):\s*(.*)$/);
+    if (kv) { key = kv[1]; meta[key] = kv[2].trim().replace(/^["'](.*)["']$/, '$1'); }
+    else if (key && /^\s+\S/.test(line)) meta[key] = `${meta[key]} ${line.trim()}`.trim(); // folded continuation
+  }
+  return { meta, body: m[2] };
+}
+
+/**
+ * Quote a frontmatter value when YAML would otherwise read it as something
+ * else: `[a b]` is a flow sequence, `{}` a map, `yes`/`no`/`true`/`1.5` typed
+ * scalars, a leading `*`, `&`, `!`, `%`, `@`, `` ` ``, `|`, `>`, `'`, `"`, `#`
+ * or a `: ` / ` #` inside changes the parse. Bit 2026-09-06: an argument-hint
+ * of `[text to translate]` was emitted bare and became a one-item list.
+ */
+function yamlScalar(v) {
+  const s = String(v);
+  // Typed scalars (true, 12, null) are left bare on purpose: `readonly: true`
+  // and `alwaysApply: true` must stay booleans for the client that reads them.
+  const risky = /^[[\]{}*&!%@`|>'"#,?-]|: | #|^\s|\s$/;
+  return risky.test(s) ? JSON.stringify(s) : s;
+}
+
+function renderFrontmatter(meta, body) {
+  const lines = ['---'];
+  for (const [k, v] of Object.entries(meta)) if (v !== undefined && v !== null && v !== '') lines.push(`${k}: ${yamlScalar(v)}`);
+  lines.push('---');
+  return `${lines.join('\n')}\n\n${String(body).trim()}\n`;
+}
+
+const tomlStr = (s) => JSON.stringify(String(s)); // TOML basic strings share JSON escaping
+function tomlMultiline(s) {
+  return '"""\n' + String(s).replace(/\\/g, '\\\\').replace(/"""/g, '\\"\\"\\"') + '\n"""';
+}
+
+/**
+ * Remove whole `## <title>` sections from a markdown document. Used by every
+ * target that drops source-client-only sections (core/port.json
+ * rules.dropSectionsForTargets); engine/sync/sync.cjs shares it.
+ */
+function stripSections(markdown, sectionTitles) {
+  let result = String(markdown);
+  for (const title of sectionTitles || []) {
+    // `$(?![\s\S])` is end-of-input; a bare `$` under /m would stop at the first newline.
+    const regex = new RegExp(`(^##\\s+${escapeRe(String(title))}\\b[\\s\\S]*?)(?=^##\\s|$(?![\\s\\S]))`, 'm');
+    result = result.replace(regex, '');
+  }
+  return result.replace(/\n{3,}/g, '\n\n').trim();
+}
+
+/** The hook shim every non-Codex target points its ported hooks at. */
+function shimPath() {
+  return config.shimPath || path.join(ROOT, 'engine', 'hooks', 'shim.cjs');
+}
+
+/** List the skill directories (entries holding a SKILL.md) under a dir. Follows links. */
+function listSkills(dir) {
+  const out = [];
+  let entries;
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch (_) { return out; }
+  for (const e of entries) {
+    if (e.name.startsWith('.')) continue;
+    const full = path.join(dir, e.name);
+    let isDir = e.isDirectory();
+    if (e.isSymbolicLink()) { try { isDir = fs.statSync(full).isDirectory(); } catch (_) { isDir = false; } }
+    if (isDir && fs.existsSync(path.join(full, 'SKILL.md'))) out.push({ name: e.name, path: full, link: readLinkTarget(full) });
+  }
+  return out.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+module.exports = {
+  ROOT, config, configure, shimPath, importRoots, expandPath, tildePath, readText, readJSON, sha,
+  looksSecret, sensitivePatterns, findSecrets, redactSecrets, urlCarriesCredential,
+  makeWriter, backupFile,
+  regionMarkers, replaceRegion, readRegion, escapeRe, stripSections,
+  link, unlinkIfLink, readLinkTarget, plainPath, listSkills,
+  parseFrontmatter, renderFrontmatter, yamlScalar, tomlStr, tomlMultiline,
+};
+// Live: every adapter reads `common.GENERATED_MARK` at call time, so a host that
+// calls configure() before its first capture/apply brands every generated file.
+Object.defineProperty(module.exports, 'GENERATED_MARK', { enumerable: true, get: () => config.brand.mark });

package/src/harness/vendor/agnostic-ai/engine/harness/index.cjs

@@ -0,0 +1,55 @@
+/**
+ * engine/harness/index.cjs — the port engine as a library.
+ *
+ * This is the one file a host product requires. Everything a host may need to
+ * own is an option, never a repo path:
+ *
+ *   const engine = require('agnostic-ai/engine/harness/index.cjs');
+ *   engine.configure({ brand: { id, mark, region }, secretPatterns, shimPath });
+ *   const registry = engine.loadRegistry(home, { targets: myTargets });
+ *   const { bundle, warnings } = engine.capture({ from: 'claude', home, outDir, registry, port });
+ *   const report = engine.apply({ bundle, home, registry, port, storageDir, to: ['codex'] });
+ *   engine.status({ bundle, home, registry, port, storageDir });
+ *
+ * Nothing here reads `core/port.json`, `core/templates/targets.json` or
+ * `core/safety/guards.json` when the host passes `port`, `registry` and
+ * `secretPatterns`. The engine's own CLI (cli.cjs) is a thin caller of the
+ * same functions with the repo's files as defaults.
+ *
+ * Node's ESM loader imports this file directly (`import engine from
+ * '.../index.cjs'`), which is how a zero-dependency ESM host embeds it
+ * without a build step.
+ */
+
+const common = require('./common.cjs');
+const bundle = require('./bundle.cjs');
+const capture = require('./capture.cjs');
+const apply = require('./apply.cjs');
+const status = require('./status.cjs');
+const toml = require('./toml.cjs');
+
+module.exports = {
+  // configuration
+  configure: common.configure,
+  config: common.config,
+  // the pipeline
+  capture: capture.capture,
+  apply: apply.apply,
+  status: status.status,
+  // registry and policy
+  loadRegistry: capture.loadRegistry,
+  loadPort: capture.loadPort,
+  detectSource: capture.detectSource,
+  selectTargets: apply.selectTargets,
+  // reporting helpers
+  formatTable: apply.formatTable,
+  formatDropped: status.formatDropped,
+  renderHtml: status.renderHtml,
+  readState: apply.readState,
+  // the modules themselves, for a host that needs the details
+  common,
+  bundle,
+  toml,
+  COMPONENTS: bundle.COMPONENTS,
+  GLYPH: apply.GLYPH,
+};