liteagents 2.24.1 → 3.5.0

package/packages/droid/commands/remember/stub-check.cjs

@@ -0,0 +1,206 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * stub-check.cjs — asserts the two managed blocks in the tool config carry the
+ * CURRENT stub shape, and repairs the shape when it is wrong.
+ *
+ * Shape, not content. The blocks' prose is user-owned — step 5 writes it once
+ * and never re-imposes it, because users trim it deliberately. What this script
+ * touches is only the mechanism:
+ *
+ *   MEMORY block       @<PROJECT_DIR>/remember/MEMORY.md   — an @-include.
+ *                      A bare `@MEMORY.md` resolves relative to the file that
+ *                      contains it, so in a repo root it names a file that does
+ *                      not exist and hot memory silently never loads.
+ *
+ *   AGENT_RULES block  <PROJECT_DIR>/remember/AGENT_RULES.md — a PLAIN pointer.
+ *                      v2.19 demoted it from an @-include on purpose: it is a
+ *                      standards guide to consult when building something new,
+ *                      not hot context, and @-including it loads ~300 lines into
+ *                      every session. Measured 2026-09-03: 21 of 37 local repos
+ *                      still carried the pre-v2.19 @-include.
+ *
+ * Two deliberate limits:
+ *
+ *   - It only edits INSIDE a marker pair. A pointer elsewhere in the config is
+ *     the user's prose and is left alone.
+ *   - It never repoints the MEMORY include at a file that does not exist. An
+ *     un-migrated `.factory/memory/` repo has a live MEMORY.md at the old path;
+ *     rewriting it to the new one would break a working include to satisfy a
+ *     naming convention. That case is reported, not repaired.
+ *
+ * Missing marker pairs are not this script's business — step 5 creates them.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// The ONE pair of lines that differs across packages.
+const PROJECT_DIR = '.factory';
+const CONFIG_FILE = 'AGENTS.md';
+
+const MEM = { start: '<!-- MEMORY:START -->', end: '<!-- MEMORY:END -->' };
+const RULES = { start: '<!-- AGENT_RULES:START -->', end: '<!-- AGENT_RULES:END -->' };
+
+const MEMORY_REL = `${PROJECT_DIR}/remember/MEMORY.md`;
+const RULES_REL = `${PROJECT_DIR}/remember/AGENT_RULES.md`;
+
+/** lstat, not existsSync: existsSync follows links, so a DANGLING link reads
+ *  as absent and gets walked straight past. */
+function lexists(p) {
+  try { fs.lstatSync(p); return true; } catch (e) { return false; }
+}
+
+/**
+ * True when writing to `target` would land outside `repo`.
+ *
+ * There are two ways out and a guard on only one of them is false safety:
+ * `target` may itself be a symlink — including a dangling one, which reads as
+ * "the file is absent" and is still followed on write — or any parent
+ * directory may be a link pointing elsewhere. This runs across a whole fleet
+ * of repos, so a relative link only has to reach a sibling checkout.
+ *
+ * A link that stays INSIDE the repo is not an escape: a repo that keeps its
+ * rules or its config behind an in-repo symlink is an ordinary setup, and
+ * refusing it would strand that repo forever. So the leaf is followed by hand
+ * with readlink — which works on a dangling link, where realpath cannot — and
+ * each hop re-resolves the parents, because the file a link points at can sit
+ * behind a linked directory of its own.
+ */
+function escapesRepo(repo, target) {
+  let root;
+  try { root = fs.realpathSync(repo); } catch (e) { return true; }
+
+  let p = path.resolve(target);
+  for (let hop = 0; hop < 40; hop++) {
+    // Resolve the existing part of the path. Walk up to the deepest ancestor
+    // that exists; anything below it cannot be a link yet.
+    const tail = [];
+    let dir = path.dirname(p);
+    while (!lexists(dir)) {
+      tail.unshift(path.basename(dir));
+      const up = path.dirname(dir);
+      if (up === dir) return true;                  // walked off the filesystem root
+      dir = up;
+    }
+    try { p = path.join(fs.realpathSync(dir), ...tail, path.basename(p)); }
+    catch (e) { return true; }                      // an ancestor is a dangling link
+
+    let to;
+    try { to = fs.readlinkSync(p); } catch (e) {
+      return p !== root && !p.startsWith(root + path.sep);   // not a link: decide here
+    }
+    p = path.resolve(path.dirname(p), to);
+  }
+  return true;                                      // a link cycle: refuse
+}
+
+/** Index range of the lines strictly between a marker pair, or null. */
+function blockRange(lines, markers) {
+  const s = lines.findIndex((l) => l.trim() === markers.start);
+  if (s === -1) return null;
+  const e = lines.findIndex((l, i) => i > s && l.trim() === markers.end);
+  if (e === -1) return null;
+  return { from: s + 1, to: e };            // [from, to)
+}
+
+/**
+ * @returns {{fixes:string[], notes:string[], changed:boolean}}
+ *   fixes  — repairs written to disk
+ *   notes  — wrong shapes deliberately left alone, with the reason
+ */
+function check(repo) {
+  const config = path.join(repo, CONFIG_FILE);
+  const fixes = [];
+  const notes = [];
+
+  // Checked before the read, not just before the write: a repair decided
+  // from a followed link is already the wrong decision.
+  if (escapesRepo(repo, config)) {
+    return { fixes, notes: [`${CONFIG_FILE} not checked: it leaves the repo via a symlink`], changed: false };
+  }
+
+  let text;
+  try { text = fs.readFileSync(config, 'utf8'); } catch (e) {
+    return { fixes, notes, changed: false };  // no config: step 5 will create one
+  }
+
+  const lines = text.split('\n');
+  let changed = false;
+
+  // ── MEMORY block: must be an @-include naming the explicit path ────────────
+  const mem = blockRange(lines, MEM);
+  if (mem) {
+    const i = lines.findIndex(
+      (l, n) => n >= mem.from && n < mem.to && /^@\S*MEMORY\.md\s*$/.test(l.trim()));
+    if (i === -1) {
+      notes.push(`${CONFIG_FILE}: MEMORY block has no @-include — hot memory does not load`);
+    } else {
+      const want = `@${MEMORY_REL}`;
+      const have = lines[i].trim();
+      if (have !== want) {
+        if (fs.existsSync(path.join(repo, MEMORY_REL))) {
+          lines[i] = want;
+          changed = true;
+          fixes.push(`${CONFIG_FILE}: MEMORY include repaired, ${have} → ${want}`);
+        } else {
+          // The old path may be the only one with a file behind it.
+          notes.push(
+            `${CONFIG_FILE}: MEMORY include is ${have}, not ${want} — left as is, `
+            + `${MEMORY_REL} does not exist yet`);
+        }
+      }
+    }
+  }
+
+  // ── AGENT_RULES block: must be a PLAIN pointer, never an @-include ─────────
+  const rules = blockRange(lines, RULES);
+  if (rules) {
+    const i = lines.findIndex(
+      (l, n) => n >= rules.from && n < rules.to && /^@\S*AGENT_RULES\.md\s*$/.test(l.trim()));
+    if (i !== -1) {
+      // Demote in place. The path is kept as written — only the @ is dropped,
+      // because the @ is the defect and the path may be a deliberate variant.
+      const had = lines[i].trim();
+      lines[i] = had.slice(1);
+      changed = true;
+      fixes.push(
+        `${CONFIG_FILE}: AGENT_RULES pointer demoted from an @-include (${had} → ${had.slice(1)}) `
+        + `— it is a standards guide, not hot context`);
+    } else {
+      const hasPointer = lines
+        .slice(rules.from, rules.to)
+        .some((l) => /AGENT_RULES\.md/.test(l));
+      if (!hasPointer) {
+        notes.push(`${CONFIG_FILE}: AGENT_RULES block has no path pointer — nothing points at the rules`);
+      }
+    }
+  }
+
+  if (changed) {
+    try {
+      fs.writeFileSync(config, lines.join('\n'));
+    } catch (e) {
+      return { fixes: [], notes: [`${CONFIG_FILE} not repaired: ${e.message}`], changed: false };
+    }
+  }
+
+  return { fixes, notes, changed };
+}
+
+function main() {
+  const repo = process.argv[2] || process.cwd();
+  const r = check(repo);
+  for (const line of r.fixes) process.stdout.write(`${line}\n`);
+  for (const line of r.notes) process.stdout.write(`${line}\n`);
+  // Silent when the shape is already current — the common case.
+}
+
+if (require.main === module) {
+  // A passenger on /remember, like version-check.cjs and sync-rules.cjs: it
+  // never gets to fail the run it rides in.
+  try { main(); } catch (e) { /* silent */ }
+}
+
+module.exports = { check, PROJECT_DIR, CONFIG_FILE, MEMORY_REL, RULES_REL };

package/packages/droid/commands/remember/sync-rules.cjs

@@ -0,0 +1,178 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * sync-rules.cjs — keeps a repo's AGENT_RULES.md current with the installed
+ * template, without ever destroying what was there.
+ *
+ * Run every /remember, from the target repo. Before this existed, the rules
+ * were bootstrapped once and never refreshed, so a measured 35 local repos
+ * drifted to a body many releases old and three hand sweeps failed to hold.
+ *
+ * Three outcomes, decided by a byte compare — not a stored hash, because the
+ * only question is "am I about to change this file?", which any careful copy
+ * asks anyway:
+ *
+ *   absent     copy it in and say so
+ *   identical  do nothing at all: no write, no backup, no output
+ *   differs    move the old body aside, copy the new one in, say so loudly
+ *
+ * THE BACKUP IS A SINGLE FILE and is overwritten on each differing run. A
+ * customised file therefore survives exactly one update: fold your changes
+ * into the new AGENT_RULES.md before the next release, or the next sync
+ * replaces the backup with a vanilla body. This is a deliberate trade — see
+ * docs/product/agent-rules-freshness-prd.md §5 — chosen over accumulating
+ * timestamped backups.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// Per-kit PROJECT dir. NOTE this is not always the global config dir: amp
+// installs to ~/.config/amp but writes .amp/ in a repo, and opencode likewise.
+// This is the ONE line that differs across packages.
+const PROJECT_DIR = '.factory';
+
+const RULES = 'AGENT_RULES.md';
+const BACKUP = 'AGENT_RULES.md.bak';   // keeps the origin name; not .md, so doc tooling ignores it
+
+/** lstat, not existsSync: existsSync follows links, so a DANGLING link reads
+ *  as absent and gets walked straight past. */
+function lexists(p) {
+  try { fs.lstatSync(p); return true; } catch (e) { return false; }
+}
+
+/**
+ * True when writing to `target` would land outside `repo`.
+ *
+ * There are two ways out and a guard on only one of them is false safety:
+ * `target` may itself be a symlink — including a dangling one, which reads as
+ * "the file is absent" and is still followed on write — or any parent
+ * directory may be a link pointing elsewhere. This runs across a whole fleet
+ * of repos, so a relative link only has to reach a sibling checkout.
+ *
+ * A link that stays INSIDE the repo is not an escape: a repo that keeps its
+ * rules or its config behind an in-repo symlink is an ordinary setup, and
+ * refusing it would strand that repo forever. So the leaf is followed by hand
+ * with readlink — which works on a dangling link, where realpath cannot — and
+ * each hop re-resolves the parents, because the file a link points at can sit
+ * behind a linked directory of its own.
+ */
+function escapesRepo(repo, target) {
+  let root;
+  try { root = fs.realpathSync(repo); } catch (e) { return true; }
+
+  let p = path.resolve(target);
+  for (let hop = 0; hop < 40; hop++) {
+    // Resolve the existing part of the path. Walk up to the deepest ancestor
+    // that exists; anything below it cannot be a link yet.
+    const tail = [];
+    let dir = path.dirname(p);
+    while (!lexists(dir)) {
+      tail.unshift(path.basename(dir));
+      const up = path.dirname(dir);
+      if (up === dir) return true;                  // walked off the filesystem root
+      dir = up;
+    }
+    try { p = path.join(fs.realpathSync(dir), ...tail, path.basename(p)); }
+    catch (e) { return true; }                      // an ancestor is a dangling link
+
+    let to;
+    try { to = fs.readlinkSync(p); } catch (e) {
+      return p !== root && !p.startsWith(root + path.sep);   // not a link: decide here
+    }
+    p = path.resolve(path.dirname(p), to);
+  }
+  return true;                                      // a link cycle: refuse
+}
+
+function templatePath() {
+  // Ships beside this script, so no path guessing and no dependence on where
+  // the kit was installed.
+  return path.join(__dirname, RULES);
+}
+
+function targetPath(repo) {
+  return path.join(repo, PROJECT_DIR, 'remember', RULES);
+}
+
+/**
+ * @returns {{action:string, detail?:string}} action is one of:
+ *   'no-template' | 'bootstrapped' | 'unchanged' | 'updated' | 'failed'
+ */
+function sync(repo) {
+  const tpl = templatePath();
+  let template;
+  try {
+    template = fs.readFileSync(tpl);
+  } catch (e) {
+    return { action: 'no-template', detail: tpl };
+  }
+
+  const target = targetPath(repo);
+  if (escapesRepo(repo, target)) return { action: 'escapes', detail: target };
+
+  let current = null;
+  try { current = fs.readFileSync(target); } catch (e) { /* absent */ }
+
+  // Byte compare. No normalisation on either side: the copy below is a plain
+  // byte write, so a mismatch here means the content really differs.
+  if (current && current.equals(template)) return { action: 'unchanged' };
+
+  try {
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    if (current) {
+      // Single backup, overwritten. rename() is atomic on the same filesystem
+      // and cannot leave a half-written backup the way copy+truncate could.
+      fs.renameSync(target, path.join(path.dirname(target), BACKUP));
+    }
+    fs.writeFileSync(target, template);
+  } catch (e) {
+    return { action: 'failed', detail: e.message };
+  }
+
+  return current ? { action: 'updated' } : { action: 'bootstrapped' };
+}
+
+function main() {
+  const repo = process.argv[2] || process.cwd();
+  const r = sync(repo);
+  const rel = path.join(PROJECT_DIR, 'remember', RULES);
+
+  switch (r.action) {
+    case 'unchanged':
+      break;                                  // silent: nothing happened
+    case 'bootstrapped':
+      process.stdout.write(`${rel} created from the installed template\n`);
+      break;
+    case 'updated':
+      process.stdout.write(
+        `${rel} updated from the installed template `
+        + `(previous body kept as ${BACKUP} — fold your changes in before the `
+        + `next release, it is a single file and the next update replaces it)\n`);
+      break;
+    case 'escapes':
+      // Loud, never repaired: the path is under the repo but does not stay
+      // there, so any write lands somewhere the run was not invited.
+      process.stdout.write(
+        `${rel} not synced: it leaves the repo via a symlink — refusing to `
+        + `write through it\n`);
+      break;
+    case 'no-template':
+      // Loud: this means the install is incomplete, not that nothing changed.
+      process.stdout.write(
+        `AGENT_RULES.md not synced: no template beside this script (${r.detail})\n`);
+      break;
+    case 'failed':
+      process.stdout.write(`AGENT_RULES.md not synced: ${r.detail}\n`);
+      break;
+  }
+}
+
+if (require.main === module) {
+  // A passenger on /remember, like version-check.cjs: it never gets to fail
+  // the run it rides in.
+  try { main(); } catch (e) { /* silent */ }
+}
+
+module.exports = { sync, PROJECT_DIR, RULES, BACKUP };

package/packages/droid/commands/remember/version-check.cjs

@@ -0,0 +1,214 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * version-check.cjs — tells the user their liteagents install is behind the
+ * registry, and nothing else.
+ *
+ * Run as step 0 of /remember, alongside friction.cjs. It rides along with a
+ * memory consolidation run, so the only hard requirement is that it can never
+ * cost that run anything: it exits 0 on every path, prints at most one line,
+ * writes nothing but its own cache, and is bounded in wall-clock time.
+ *
+ * Deliberately NOT part of friction.cjs: that file mines friction signals, and
+ * a registry lookup is an unrelated concern.
+ *
+ * A POC (2026-09-03) found the one non-obvious defect guarded here:
+ * req.setTimeout is a socket-INACTIVITY timeout and does not bound connect
+ * time. Against an unroutable host a 2000ms budget overran to 5146ms. Only an
+ * explicit deadline bounds the total, so both are set.
+ *
+ * Environment:
+ *   npm_config_registry            registry base (npm sets this; mirrors work)
+ *   LITEAGENTS_INSTALLED_VERSION   skip local version discovery
+ *   LITEAGENTS_SKIP_NPM_LOOKUP     skip the `npm ls -g` fallback (it is slow)
+ *
+ * Installed version is resolved in cost order: the installer's manifest stamp
+ * (a file read), then our own package.json when run from a checkout, then
+ * `npm ls -g` as a last resort. The last one costs ~500ms on EVERY run, which
+ * is why the installer stamps the manifest at all.
+ */
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const PKG = 'liteagents';
+// Per-kit config dir. This is the ONE line that differs across packages.
+const CONFIG_DIR = '.factory';
+const TTL_MS = 24 * 60 * 60 * 1000;
+const DEADLINE_MS = 2000;
+const NPM_LOOKUP_MS = 3000;
+
+// --- version comparison --------------------------------------------------
+
+/**
+ * Is `b` a newer release than `a`? Numeric per component, so 2.9.0 < 2.10.0 —
+ * a string compare gets that backwards. A prerelease suffix is stripped, so
+ * 2.24.2-beta.1 counts as newer than 2.24.1: it is still a later release, and
+ * a user on it does not need advice about 2.24.1.
+ */
+function isNewer(a, b) {
+  const parse = (v) => String(v).trim().replace(/^v/, '').split('-')[0]
+    .split('.').map((n) => parseInt(n, 10) || 0);
+  const [x, y] = [parse(a), parse(b)];
+  for (let i = 0; i < 3; i++) {
+    const d = (y[i] || 0) - (x[i] || 0);
+    if (d !== 0) return d > 0;
+  }
+  return false;
+}
+
+// --- installed version ---------------------------------------------------
+
+// Walk up from this file looking for our own package.json. Finds it when
+// running from a checkout; finds nothing when installed into ~/.factory, which
+// is why the npm fallback exists.
+function versionFromPackageJson() {
+  let dir = __dirname;
+  for (let i = 0; i < 8; i++) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8'));
+      if (pkg && pkg.name === PKG && pkg.version) return String(pkg.version);
+    } catch (e) { /* keep walking */ }
+    const up = path.dirname(dir);
+    if (up === dir) break;
+    dir = up;
+  }
+  return null;
+}
+
+// The installer stamps the release it wrote into <install root>/manifest.json.
+// version-check.cjs sits at <root>/<skills|commands|command>/remember/, so the root
+// two levels up. This is the fast path: reading a file beats spawning npm.
+function versionFromManifest() {
+  try {
+    const m = JSON.parse(fs.readFileSync(
+      path.join(__dirname, '..', '..', 'manifest.json'), 'utf8'));
+    // NOT m.version -- that is the manifest schema version, a different thing.
+    return m && m.liteagents_version ? String(m.liteagents_version) : null;
+  } catch (e) { return null; }
+}
+
+function versionFromNpm() {
+  if (process.env.LITEAGENTS_SKIP_NPM_LOOKUP) return null;
+  try {
+    const r = require('child_process').spawnSync(
+      'npm', ['ls', '-g', PKG, '--depth=0', '--json'],
+      { encoding: 'utf8', timeout: NPM_LOOKUP_MS }
+    );
+    if (!r.stdout) return null;
+    const deps = JSON.parse(r.stdout).dependencies || {};
+    return deps[PKG] && deps[PKG].version ? String(deps[PKG].version) : null;
+  } catch (e) { return null; }
+}
+
+function installedVersion() {
+  const env = (process.env.LITEAGENTS_INSTALLED_VERSION || '').trim();
+  if (env) return env;
+  return versionFromManifest() || versionFromPackageJson() || versionFromNpm();
+}
+
+// --- cache ---------------------------------------------------------------
+
+// Home-scoped, not per-repo: it describes the global install, so a per-repo
+// cache would make every repo fetch the same answer.
+function cachePath() {
+  return path.join(os.homedir(), CONFIG_DIR, `.${PKG}-version.json`);
+}
+
+function readCache() {
+  try {
+    const c = JSON.parse(fs.readFileSync(cachePath(), 'utf8'));
+    if (typeof c.checked_at !== 'number' || typeof c.latest !== 'string') return null;
+    if (Date.now() - c.checked_at > TTL_MS) return null;
+    return c.latest;
+  } catch (e) { return null; }
+}
+
+// Best effort. An unwritable cache dir means we re-fetch next run, never that
+// we withhold the advice we already have.
+function writeCache(latest) {
+  try {
+    fs.mkdirSync(path.dirname(cachePath()), { recursive: true });
+    fs.writeFileSync(cachePath(), JSON.stringify({ checked_at: Date.now(), latest }));
+  } catch (e) { /* not worth a word */ }
+}
+
+// --- registry ------------------------------------------------------------
+
+function fetchLatest(cb) {
+  let base = process.env.npm_config_registry || 'https://registry.npmjs.org/';
+  if (!/\/$/.test(base)) base += '/';
+  const url = `${base}${PKG}/latest`;
+
+  let mod;
+  try { mod = url.startsWith('http://') ? require('http') : require('https'); }
+  catch (e) { return cb(null); }
+
+  let settled = false;
+  let req = null;
+  const finish = (v) => {
+    if (settled) return;
+    settled = true;
+    clearTimeout(deadline);
+    if (v === null && req) { try { req.destroy(); } catch (e) { /* */ } }
+    cb(v);
+  };
+
+  // The hard bound. req.setTimeout below does not cover connect time.
+  const deadline = setTimeout(() => finish(null), DEADLINE_MS);
+
+  try {
+    req = mod.get(url, { headers: { accept: 'application/json' } }, (res) => {
+      if (res.statusCode !== 200) { res.resume(); return finish(null); }
+      let body = '';
+      res.setEncoding('utf8');
+      res.on('data', (c) => {
+        body += c;
+        if (body.length > 1e6) finish(null); // a packument this big is not ours
+      });
+      res.on('end', () => {
+        try {
+          const v = JSON.parse(body).version;
+          finish(typeof v === 'string' && v ? v : null);
+        } catch (e) { finish(null); }
+      });
+      res.on('error', () => finish(null));
+    });
+    req.setTimeout(DEADLINE_MS, () => finish(null));
+    req.on('error', () => finish(null));
+  } catch (e) { finish(null); }
+}
+
+// --- main ----------------------------------------------------------------
+
+function advise(installed, latest) {
+  if (!installed || !latest) return;            // never guess
+  if (!isNewer(installed, latest)) return;      // current, or ahead of the registry
+  process.stdout.write(
+    `liteagents ${installed} -> ${latest} available: `
+    + `npm i -g ${PKG}@latest && ${PKG}\n`
+  );
+}
+
+function main() {
+  const installed = installedVersion();
+
+  const cached = readCache();
+  if (cached) return advise(installed, cached);
+
+  fetchLatest((latest) => {
+    if (!latest) return;                        // offline, slow, or broken: silent
+    writeCache(latest);
+    advise(installed, latest);
+  });
+}
+
+if (require.main === module) {
+  // Every failure is silent by contract. This command is a passenger; it does
+  // not get to fail the run it is riding in.
+  try { main(); } catch (e) { /* silent */ }
+} 
+
+module.exports = { isNewer };