ultra11y 2.26.0 → 2.28.0

package/src/install/index.ts

@@ -0,0 +1,204 @@
+// `install` / `uninstall` / `status` — wiring the automatic review into an agent.
+//
+// Every function here is pure of console and process.exit: they take explicit paths and
+// return report objects. That is what lets the whole surface be driven from vitest against
+// a temporary HOME without spawning a process, and it is why the CLI layer above owns all
+// the printing.
+import { claudeCodeWired, installClaudeCode, uninstallClaudeCode } from "./claude-code.js";
+import { agentsMdPath, agentsMdWired, installAgentsMd, uninstallAgentsMd } from "./agents-md.js";
+import { codexHooksEnabled, codexWired, installCodex, uninstallCodex } from "./codex.js";
+import { installOpencode, opencodeWired, uninstallOpencode } from "./opencode.js";
+import {
+  bundledOpencodePlugin,
+  bundledSkillsDir,
+  claudeSettingsPath,
+  codexHome,
+  installedCliCommand,
+  opencodeConfigDir,
+  packageRoot,
+  pinnedEnginePath,
+} from "./paths.js";
+import { type EditReport, SettingsParseError } from "./json-edit.js";
+import { repoRoot } from "../init.js";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+export type Target = "claude-code" | "codex" | "opencode" | "agents-md";
+
+/** The harnesses `--all` covers.
+ *
+ *  `agents-md` is deliberately NOT in this list. It is the only target that writes a
+ *  TRACKED FILE INTO THE USER'S REPOSITORY; every other one edits a dotfile under their
+ *  home. `--all` must never hand someone an unexpected new file to review in `git status`,
+ *  so AGENTS.md is always an explicit ask. */
+export const ALL_TARGETS: readonly Target[] = ["claude-code", "codex", "opencode"];
+
+export interface TargetResult {
+  target: Target;
+  /** What was written, when anything was. */
+  reports: EditReport[];
+  /** Things the user has to know: a restart, a trust prompt, a limitation. */
+  guidance: string[];
+  error?: string;
+}
+
+export interface InstallOptions {
+  targets: readonly Target[];
+  /** Scope the install to the current project instead of the user's home, where supported. */
+  project?: boolean;
+  cwd?: string;
+  /** Render what would be written and touch nothing. */
+  dryRun?: boolean;
+  /** Copy the bundled skills into the harness's skills directory too (default: yes). */
+  skills?: boolean;
+}
+
+/** Parse `--claude-code --codex --opencode --agents-md --all` into a target list.
+ *  Returns `null` when nothing was selected, which the CLI turns into a usage error. */
+export function parseTargets(flags: Record<string, unknown>): Target[] | null {
+  const picked = new Set<Target>();
+  if (flags.all === true) for (const t of ALL_TARGETS) picked.add(t);
+  if (flags["claude-code"] === true) picked.add("claude-code");
+  if (flags.codex === true) picked.add("codex");
+  if (flags.opencode === true) picked.add("opencode");
+  if (flags["agents-md"] === true) picked.add("agents-md");
+  return picked.size ? [...picked] : null;
+}
+
+/** The repository the project-scoped targets act on. */
+function projectRoot(cwd: string): string {
+  return repoRoot() ?? cwd;
+}
+
+export function installForTargets(opts: InstallOptions): TargetResult[] {
+  const cwd = opts.cwd ?? process.cwd();
+  const out: TargetResult[] = [];
+  // Resolved once: it may pin a copy of the engine, which should happen at most once per run.
+  let command: string | null = null;
+  const cmd = () => (command ??= installedCliCommand());
+
+  for (const target of opts.targets) {
+    const r: TargetResult = { target, reports: [], guidance: [] };
+    try {
+      switch (target) {
+        case "claude-code": {
+          const settingsPath = claudeSettingsPath(opts.project === true, cwd);
+          if (!opts.dryRun) r.reports.push(installClaudeCode({ settingsPath, command: cmd() }));
+          else r.reports.push({ path: settingsPath, changed: false });
+          r.guidance.push(
+            "claude-code: the plugin route (`/plugin marketplace add maxgfr/ultra11y` then `/plugin install ultra11y@ultra11y`) ships the skills too — this settings hook only wires the gate.",
+            "claude-code: restart the session — hooks load at startup.",
+          );
+          break;
+        }
+        case "codex": {
+          // Codex reads hooks only from its own home; there is no project scope to honour.
+          if (opts.project === true) r.guidance.push("codex: --project is not supported (Codex reads hooks from its home only) — wiring the user scope.");
+          if (!opts.dryRun) {
+            const out = installCodex({ codexDir: codexHome(), command: cmd(), skillsSource: opts.skills === false ? null : bundledSkillsDir() });
+            r.reports.push(...out.reports);
+            r.guidance.push(...out.guidance);
+          } else r.reports.push({ path: join(codexHome(), "hooks.json"), changed: false });
+          break;
+        }
+        case "opencode": {
+          const source = bundledOpencodePlugin();
+          if (!source) {
+            r.error = "opencode: this engine was not run from a package carrying .opencode/plugins/ultra11y.js — install ultra11y from npm and retry.";
+            break;
+          }
+          const configDir = opts.project === true ? join(cwd, ".opencode") : opencodeConfigDir();
+          if (!opts.dryRun) {
+            const engine = existsSync(pinnedEnginePath()) ? pinnedEnginePath() : join(packageRoot() ?? "", "scripts", "ultra11y.mjs");
+            const out = installOpencode({
+              configDir,
+              pluginSource: source,
+              skillsSource: opts.skills === false ? null : bundledSkillsDir(),
+              enginePath: existsSync(engine) ? engine : null,
+            });
+            r.reports.push(...out.reports);
+            r.guidance.push(...out.guidance);
+          } else r.reports.push({ path: join(configDir, "plugin", "ultra11y.js"), changed: false });
+          break;
+        }
+        case "agents-md": {
+          const root = projectRoot(cwd);
+          if (!opts.dryRun) r.reports.push(installAgentsMd(root));
+          else r.reports.push({ path: agentsMdPath(root), changed: false });
+          r.guidance.push(
+            "agents-md: this is a tracked file in your repository — review it and commit it.",
+            "agents-md: it cannot make anything automatic (no hook API); `ultra11y init --hook` is what actually enforces the gate there.",
+          );
+          break;
+        }
+      }
+    } catch (e) {
+      r.error = e instanceof SettingsParseError ? e.message : `${target}: ${(e as Error).message}`;
+    }
+    out.push(r);
+  }
+  return out;
+}
+
+export function uninstallForTargets(opts: InstallOptions): TargetResult[] {
+  const cwd = opts.cwd ?? process.cwd();
+  const out: TargetResult[] = [];
+  for (const target of opts.targets) {
+    const r: TargetResult = { target, reports: [], guidance: [] };
+    try {
+      switch (target) {
+        case "claude-code":
+          r.reports.push(uninstallClaudeCode({ settingsPath: claudeSettingsPath(opts.project === true, cwd) }));
+          break;
+        case "codex": {
+          const out = uninstallCodex({ codexDir: codexHome() });
+          r.reports.push(...out.reports);
+          r.guidance.push(...out.guidance);
+          break;
+        }
+        case "opencode": {
+          const out = uninstallOpencode({ configDir: opts.project === true ? join(cwd, ".opencode") : opencodeConfigDir() });
+          r.reports.push(...out.reports);
+          r.guidance.push(...out.guidance);
+          break;
+        }
+        case "agents-md":
+          r.reports.push(uninstallAgentsMd(projectRoot(cwd)));
+          break;
+      }
+    } catch (e) {
+      r.error = e instanceof SettingsParseError ? e.message : `${target}: ${(e as Error).message}`;
+    }
+    out.push(r);
+  }
+  return out;
+}
+
+export interface StatusRow {
+  target: Target;
+  wired: boolean;
+  path: string;
+  note?: string;
+}
+
+/** The doctor. Never throws — a broken settings file is a row to report, not a crash. */
+export function statusReport(opts: { project?: boolean; cwd?: string } = {}): StatusRow[] {
+  const cwd = opts.cwd ?? process.cwd();
+  const claudePath = claudeSettingsPath(opts.project === true, cwd);
+  const root = projectRoot(cwd);
+  const codexDir = codexHome();
+  const ocDir = opts.project === true ? join(cwd, ".opencode") : opencodeConfigDir();
+  const codexOn = codexWired(codexDir) > 0;
+  return [
+    { target: "claude-code", wired: claudeCodeWired(claudePath) > 0, path: claudePath, note: "the plugin route wires this separately and does not show here" },
+    {
+      target: "codex",
+      wired: codexOn,
+      path: join(codexDir, "hooks.json"),
+      // A wired hook behind a disabled feature flag never fires and looks fine. Say so.
+      note: codexOn && !codexHooksEnabled(codexDir) ? "WIRED BUT INERT: `[features] hooks = true` is not set in config.toml" : undefined,
+    },
+    { target: "opencode", wired: opencodeWired(ocDir), path: join(ocDir, "plugin", "ultra11y.js") },
+    { target: "agents-md", wired: agentsMdWired(root), path: agentsMdPath(root) },
+  ];
+}

package/src/install/json-edit.ts

@@ -0,0 +1,97 @@
+// Editing files that belong to the USER — their ~/.claude/settings.json, their
+// ~/.codex/hooks.json, their AGENTS.md. Three rules govern everything here, and they are
+// the reason this module exists instead of a few writeFileSync calls:
+//
+//  1. NEVER lose data. Anything pre-existing is backed up under a timestamped name before
+//     it is touched, and writes are atomic (tmp + rename) so an interrupted install cannot
+//     leave a half-written settings file that breaks the user's agent on next launch.
+//  2. NEVER surprise. A no-op edit writes nothing and takes no backup, so running `install`
+//     twice does not litter the directory with copies of an unchanged file.
+//  3. NEVER guess. A settings file that does not parse is reported, not overwritten — the
+//     user has hand-edited JSON in there and silently replacing it would be data loss.
+import { copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+
+/** What an edit did. `changed: false` means the file already said what we wanted. */
+export interface EditReport {
+  path: string;
+  changed: boolean;
+  /** Path of the backup taken before overwriting, when one was needed. */
+  backup?: string;
+}
+
+/** A user file we refuse to touch because we cannot read it. Carries the path so the CLI
+ *  can tell the user exactly what to fix rather than "install failed". */
+export class SettingsParseError extends Error {
+  constructor(
+    readonly path: string,
+    cause: string,
+  ) {
+    super(`${path} is not valid JSON (${cause}) — fix or move it, then run install again. It has NOT been modified.`);
+    this.name = "SettingsParseError";
+  }
+}
+
+/** A timestamp safe for a filename on every platform. */
+function stamp(): string {
+  return new Date().toISOString().replaceAll(/[:.]/g, "-");
+}
+
+/** Write `content` to `path` atomically, backing up any existing file first. The tmp file
+ *  is created in the SAME directory so the rename is a same-filesystem move (an atomic
+ *  operation) rather than a copy that can be observed half-done. */
+export function writeTextWithBackup(path: string, content: string, marker = "ultra11y"): EditReport {
+  if (existsSync(path) && readFileSync(path, "utf8") === content) return { path, changed: false };
+  mkdirSync(dirname(path), { recursive: true });
+  let backup: string | undefined;
+  if (existsSync(path)) {
+    backup = `${path}.${marker}-backup-${stamp()}`;
+    copyFileSync(path, backup);
+  }
+  const tmp = `${path}.${process.pid}.tmp`;
+  try {
+    writeFileSync(tmp, content, { mode: 0o644 });
+    renameSync(tmp, path);
+  } catch (e) {
+    rmSync(tmp, { force: true });
+    throw e;
+  }
+  return { path, changed: true, backup };
+}
+
+/** Read a JSON object, let `mutate` change it in place, write it back only if that
+ *  actually changed something. A missing file starts from `{}`; a malformed one throws
+ *  SettingsParseError rather than being clobbered. */
+export function editJsonFile(path: string, mutate: (root: Record<string, unknown>) => void): EditReport {
+  let root: Record<string, unknown> = {};
+  if (existsSync(path)) {
+    const raw = readFileSync(path, "utf8");
+    if (raw.trim()) {
+      let parsed: unknown;
+      try {
+        parsed = JSON.parse(raw);
+      } catch (e) {
+        throw new SettingsParseError(path, (e as Error).message);
+      }
+      if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new SettingsParseError(path, "the top level is not an object");
+      }
+      root = parsed as Record<string, unknown>;
+    }
+  }
+  const before = JSON.stringify(root);
+  mutate(root);
+  if (JSON.stringify(root) === before && existsSync(path)) return { path, changed: false };
+  return writeTextWithBackup(path, `${JSON.stringify(root, null, 2)}\n`);
+}
+
+/** Read a JSON object, or `null` when it is missing or unreadable. For `status`, which must
+ *  report on a broken file rather than throw on it. */
+export function readJsonSafe(path: string): Record<string, unknown> | null {
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? (parsed as Record<string, unknown>) : null;
+  } catch {
+    return null;
+  }
+}

package/src/install/opencode.ts

@@ -0,0 +1,90 @@
+// Wiring the gate into OpenCode.
+//
+// OpenCode loads plugins as JS modules, so unlike the hook-based harnesses there is no
+// config to edit: the install IS the file at ~/.config/opencode/plugin/ultra11y.js. The
+// alternative route — pinning `"plugin": ["ultra11y@latest"]` in opencode.json — resolves
+// the npm package's `main`, which points at the same source file. Both end up running
+// .opencode/plugins/ultra11y.js; this one just copies it somewhere OpenCode already looks.
+//
+// The copy is refused if a file is already there without our ownership marker: a user's own
+// ultra11y.js is theirs, and silently replacing it would be data loss.
+import { existsSync, readFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { type EditReport, editJsonFile, writeTextWithBackup } from "./json-edit.js";
+import { copySkillsInto } from "./paths.js";
+
+export const OPENCODE_MARKER = "ULTRA11Y_OPENCODE_PLUGIN";
+
+export interface OpencodeInstall {
+  configDir: string;
+  /** The plugin source to copy (.opencode/plugins/ultra11y.js in this package). */
+  pluginSource: string;
+  /** Copy the two skills into ~/.config/opencode/skills/ as well. */
+  skillsSource?: string | null;
+  /** The engine the copied plugin should resolve. Written beside it so the plugin's
+   *  `<here>/ultra11y.mjs` candidate hits — the copy sits far from any package root, so
+   *  its npm-pin candidate cannot resolve. */
+  enginePath?: string | null;
+}
+
+function pluginTarget(configDir: string): string {
+  return join(configDir, "plugin", "ultra11y.js");
+}
+
+export function installOpencode({ configDir, pluginSource, skillsSource, enginePath }: OpencodeInstall): { reports: EditReport[]; guidance: string[] } {
+  const target = pluginTarget(configDir);
+  if (existsSync(target) && !readFileSync(target, "utf8").includes(OPENCODE_MARKER)) {
+    throw new Error(`refusing to overwrite ${target}: it is not a file ultra11y wrote. Remove it manually if you want the plugin here.`);
+  }
+  const reports: EditReport[] = [writeTextWithBackup(target, readFileSync(pluginSource, "utf8"))];
+
+  // The plugin's own resolution order looks here first after $ULTRA11Y_BIN.
+  if (enginePath && existsSync(enginePath)) {
+    reports.push(writeTextWithBackup(join(configDir, "plugin", "ultra11y.mjs"), readFileSync(enginePath, "utf8")));
+  }
+  if (skillsSource) reports.push(...copySkillsInto(skillsSource, join(configDir, "skills")));
+
+  return {
+    reports,
+    guidance: [
+      "opencode: restart the session — plugins load at startup.",
+      'opencode: the alternative is an npm pin — add "plugin": ["ultra11y@latest"] to ~/.config/opencode/opencode.json and drop this file.',
+      "opencode: the gate surfaces as a blocked tool call whose error message carries the findings (OpenCode has no permission-decision channel).",
+    ],
+  };
+}
+
+export function uninstallOpencode({ configDir }: { configDir: string }): { reports: EditReport[]; guidance: string[] } {
+  const reports: EditReport[] = [];
+  const target = pluginTarget(configDir);
+  if (existsSync(target) && readFileSync(target, "utf8").includes(OPENCODE_MARKER)) {
+    rmSync(target, { force: true });
+    rmSync(join(configDir, "plugin", "ultra11y.mjs"), { force: true });
+    reports.push({ path: target, changed: true });
+  }
+  // Also drop an npm pin, if the user wired it that way instead.
+  const configPath = join(configDir, "opencode.json");
+  if (existsSync(configPath)) {
+    reports.push(
+      editJsonFile(configPath, (root) => {
+        if (!Array.isArray(root.plugin)) return;
+        const kept = (root.plugin as unknown[]).filter((p) => !/^ultra11y(@|$)/.test(String(p)));
+        if (kept.length > 0) root.plugin = kept;
+        else delete root.plugin;
+      }),
+    );
+  }
+  return { reports, guidance: [] };
+}
+
+export function opencodeWired(configDir: string): boolean {
+  const target = pluginTarget(configDir);
+  if (existsSync(target) && readFileSync(target, "utf8").includes(OPENCODE_MARKER)) return true;
+  // The npm-pin route leaves no file of ours, so check the config too.
+  try {
+    const cfg = JSON.parse(readFileSync(join(configDir, "opencode.json"), "utf8"));
+    return Array.isArray(cfg.plugin) && cfg.plugin.some((p: unknown) => /^ultra11y(@|$)/.test(String(p)));
+  } catch {
+    return false;
+  }
+}

package/src/install/paths.ts

@@ -0,0 +1,132 @@
+// Where each harness keeps its configuration, and where the engine should be invoked from.
+//
+// Every path is computed from the environment rather than hard-coded, so the whole install
+// surface can be driven against a temporary HOME in tests without spawning anything.
+import { copyFileSync, cpSync, existsSync, mkdirSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+/** `~/.codex`, or `$CODEX_HOME` when set. */
+export function codexHome(): string {
+  return process.env.CODEX_HOME || join(homedir(), ".codex");
+}
+
+/** `~/.config/opencode`, honouring `$XDG_CONFIG_HOME`. */
+export function opencodeConfigDir(): string {
+  const xdg = process.env.XDG_CONFIG_HOME;
+  return join(xdg && xdg !== "" ? xdg : join(homedir(), ".config"), "opencode");
+}
+
+/** Claude Code's settings file: the user's, or the project's under `--project`. */
+export function claudeSettingsPath(project: boolean, cwd = process.cwd()): string {
+  return project ? join(cwd, ".claude", "settings.json") : join(homedir(), ".claude", "settings.json");
+}
+
+/** Where the pinned copy of the engine lives once installed. */
+export function pinnedEnginePath(): string {
+  return join(homedir(), ".ultra11y", "bin", "ultra11y.mjs");
+}
+
+/** The `node <path>` command to bake into a harness's hook config.
+ *
+ *  A hook command has to keep working long after `install` returned, from a process whose
+ *  cwd is the user's repo and whose PATH we do not control. That rules out two tempting
+ *  options: a relative path (wrong cwd) and `npx -y ultra11y` (an npx resolution on every
+ *  shell call, inside a PreToolUse hook, is a tax nobody would accept).
+ *
+ *  So: use the running bundle where it is stable, and otherwise pin a copy under
+ *  `~/.ultra11y/bin/`. The pin is what makes `npx ultra11y install` work at all — its own
+ *  argv[1] lives in a temp directory npm will delete. */
+export function installedCliCommand(): string {
+  const override = process.env.ULTRA11Y_BIN;
+  if (override) return `node ${JSON.stringify(override)}`;
+
+  const argv1 = process.argv[1];
+  let source: string | null = null;
+  try {
+    if (argv1) source = realpathSync(argv1);
+  } catch {
+    /* argv[1] is gone or unreadable — fall through to the pin */
+  }
+  // An npx cache path is temporary by construction; anything under it must be copied out.
+  const ephemeral = !source || /[/\\](?:_npx|\.npm[/\\]_npx|npm-cache|Temp|tmp)[/\\]/.test(source);
+  if (source && !ephemeral) return `node ${JSON.stringify(source)}`;
+
+  const pin = pinnedEnginePath();
+  if (source) {
+    mkdirSync(join(pin, ".."), { recursive: true });
+    copyFileSync(source, pin);
+  }
+  return `node ${JSON.stringify(pin)}`;
+}
+
+/** True when a pinned engine is already in place. */
+export function hasPinnedEngine(): boolean {
+  return existsSync(pinnedEnginePath());
+}
+
+/** The root of the ultra11y package this engine was run from — where `skills/` and
+ *  `.opencode/plugins/` live. Found by walking up from the running bundle looking for the
+ *  marker directories rather than from `import.meta.url`, because the bundle is a single
+ *  file that may sit at the package root (`scripts/ultra11y.mjs`) or inside a skill
+ *  (`skills/review-a11y/scripts/ultra11y.mjs`). Returns null when nothing looks right,
+ *  which the callers turn into "skip the optional copies" rather than an error. */
+export function packageRoot(): string | null {
+  let dir: string;
+  try {
+    dir = dirname(realpathSync(process.argv[1] ?? ""));
+  } catch {
+    return null;
+  }
+  for (let i = 0; i < 6 && dir && dir !== "/"; i++) {
+    if (existsSync(join(dir, "skills", "review-a11y", "SKILL.md"))) return dir;
+    dir = dirname(dir);
+  }
+  return null;
+}
+
+/** The two skills, as a directory to copy from — or null when this engine was not run from
+ *  a package that carries them (a bare `scripts/ultra11y.mjs` downloaded on its own). */
+export function bundledSkillsDir(): string | null {
+  const root = packageRoot();
+  const p = root ? join(root, "skills") : null;
+  return p && existsSync(p) ? p : null;
+}
+
+/** The OpenCode plugin source shipped in this package. */
+export function bundledOpencodePlugin(): string | null {
+  const root = packageRoot();
+  const p = root ? join(root, ".opencode", "plugins", "ultra11y.js") : null;
+  return p && existsSync(p) ? p : null;
+}
+
+/** Copy each skill directory into `dest`, reporting a change only when there actually was
+ *  one — so a second `install` says "already wired" instead of claiming work it did not do.
+ *
+ *  Freshness is decided on SKILL.md and the embedded engine: the engine is what goes stale
+ *  on an upgrade, and SKILL.md is what goes stale on a re-word. Copying is `cpSync` rather
+ *  than a symlink so the skill survives the source being moved or an npx cache pruned. */
+export function copySkillsInto(source: string, dest: string): Array<{ path: string; changed: boolean }> {
+  const out: Array<{ path: string; changed: boolean }> = [];
+  for (const name of ["ultra11y", "review-a11y"]) {
+    const from = join(source, name);
+    if (!existsSync(from)) continue;
+    const to = join(dest, name);
+    const same = ["SKILL.md", join("scripts", "ultra11y.mjs")].every((f) => {
+      const a = join(from, f);
+      const b = join(to, f);
+      try {
+        return existsSync(b) && statSync(a).size === statSync(b).size && readFileSync(a).equals(readFileSync(b));
+      } catch {
+        return false;
+      }
+    });
+    if (same) {
+      out.push({ path: to, changed: false });
+      continue;
+    }
+    cpSync(from, to, { recursive: true });
+    out.push({ path: to, changed: true });
+  }
+  return out;
+}

package/src/install/text-edit.ts

@@ -0,0 +1,54 @@
+// Managed blocks in files the user also writes in — their AGENTS.md, their config.toml.
+//
+// The contract is the marker pair, not the content: whatever sits between the markers is
+// ours to rewrite, and everything outside them is theirs and is never touched. That is what
+// lets `install` be idempotent against a file a human keeps editing, and what lets
+// `uninstall` remove exactly what was added rather than the whole file.
+import { existsSync, readFileSync, rmSync } from "node:fs";
+import { type EditReport, writeTextWithBackup } from "./json-edit.js";
+
+export const BLOCK_BEGIN = "<!-- BEGIN ultra11y (managed by `ultra11y install --agents-md`; edit outside this block) -->";
+export const BLOCK_END = "<!-- END ultra11y -->";
+
+/** Everything from the begin marker to the end marker, inclusive. Non-greedy so a file that
+ *  somehow carries two blocks loses only the first, rather than everything between them. */
+const blockRe = () => new RegExp(`${escapeRe(BLOCK_BEGIN)}[\\s\\S]*?${escapeRe(BLOCK_END)}\\n?`);
+
+function escapeRe(s: string): string {
+  return s.replaceAll(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/** Put `body` in the file's managed block: replace it if the markers are there, append it
+ *  after a blank line otherwise, create the file if it is missing. The user's own prose is
+ *  never rewritten — only the region between the markers. */
+export function upsertManagedBlock(path: string, body: string): EditReport {
+  const block = `${BLOCK_BEGIN}\n${body.trim()}\n${BLOCK_END}\n`;
+  if (!existsSync(path)) return writeTextWithBackup(path, block);
+  const current = readFileSync(path, "utf8");
+  if (blockRe().test(current)) return writeTextWithBackup(path, current.replace(blockRe(), block));
+  // Appending, not rewriting: whatever the user wrote stays byte-identical above.
+  const sep = current.endsWith("\n\n") ? "" : current.endsWith("\n") ? "\n" : "\n\n";
+  return writeTextWithBackup(path, `${current}${sep}${block}`);
+}
+
+/** Remove the managed block. Deletes the file only when nothing but whitespace is left —
+ *  i.e. when the block was all it ever held. */
+export function removeManagedBlock(path: string): EditReport {
+  if (!existsSync(path)) return { path, changed: false };
+  const current = readFileSync(path, "utf8");
+  if (!blockRe().test(current)) return { path, changed: false };
+  const rest = current.replace(blockRe(), "");
+  if (rest.trim() === "") {
+    rmSync(path, { force: true });
+    return { path, changed: true };
+  }
+  // Collapse the trailing run of newlines to exactly one, so removing a block that was
+  // APPENDED (and therefore carries the blank-line separator we inserted) restores the
+  // user's file byte-for-byte rather than leaving it slowly growing blank lines.
+  return writeTextWithBackup(path, rest.replace(/\n+$/, "\n"));
+}
+
+/** True when the file currently carries our block. */
+export function hasManagedBlock(path: string): boolean {
+  return existsSync(path) && blockRe().test(readFileSync(path, "utf8"));
+}

package/src/types.ts

@@ -1,6 +1,6 @@
 // Single source of truth for shared types + the embedded version. sync-version.mjs
 // rewrites VERSION at release time (kept in lockstep with package.json + SKILL.md).
-export const VERSION = "2.26.0";
+export const VERSION = "2.28.0";
 export const SCHEMA_VERSION = 2;
 
 // Lang = the UI FRAME's language — the `L` localization tables each module (report,

package/src/vendor/codeindex-engine.d.mts

@@ -1,6 +1,6 @@
-declare const ENGINE_VERSION = "2.22.0";
+declare const ENGINE_VERSION = "2.24.2";
 declare const SCHEMA_VERSION = 5;
-declare const EXTRACTOR_VERSION = 11;
+declare const EXTRACTOR_VERSION = 12;
 type FileKind = "code" | "doc" | "config" | "asset" | "other";
 type EdgeKind = "contains" | "doc-link" | "import" | "call" | "extends" | "implements" | "use" | "mention";
 type Tier = 0 | 1 | 2;
@@ -397,7 +397,7 @@ declare function tagsQueryStatus(key: string): TagsQueryStatus;
  */
 declare function extractTags(ext: string, content: string): TagDefinition[];
 
-declare const DEFAULT_GRAMMARS_URL = "https://github.com/maxgfr/codeindex/releases/download/v2.22.0/grammars-2.22.0.tar.gz";
+declare const DEFAULT_GRAMMARS_URL = "https://github.com/maxgfr/codeindex/releases/download/v2.24.2/grammars-2.24.2.tar.gz";
 interface GrammarsPullTarget {
     url: string;
     sha256Url?: string;

package/src/vendor/codeindex-engine.mjs

@@ -14,9 +14,9 @@ var ENGINE_VERSION, SCHEMA_VERSION, EXTRACTOR_VERSION;
 var init_types = __esm({
   "src/types.ts"() {
     "use strict";
-    ENGINE_VERSION = "2.22.0";
+    ENGINE_VERSION = "2.24.2";
     SCHEMA_VERSION = 5;
-    EXTRACTOR_VERSION = 11;
+    EXTRACTOR_VERSION = 12;
   }
 });
 
@@ -993,6 +993,18 @@ var init_js_ts = __esm({
       { re: /^\s*module\.exports\.(?<name>[\w$]+)\s*=/, kind: "const", exported: true },
       // top-level const arrow function (not exported)
       { re: /^\s*(?:const|let)\s+(?<name>[\w$]+)\s*=\s*(?:async\s*)?\([^)]*\)\s*(?::[^=]+)?=>/, kind: "const", exported: false },
+      // A module constant bound to a VALUE, not exported: `const RE = /href=/g`.
+      // The AST tier indexes these (a top-level binding is a declaration, only an
+      // in-function one is a local), and a fallback tier that answers "no such
+      // symbol" for every module constant diverges from the engine it stands in for.
+      //
+      // Anchored at column 0, unlike every rule above it: a line scanner cannot see
+      // scope, so `^\s*` here would sweep in each `const x = 1` inside every function
+      // body — the locals-flood the AST tier's inFunctionBody filter exists to
+      // prevent, and the surplus this project criticises in a flat tags file. Column
+      // 0 is the one module-scope proxy a line can carry. Must stay AFTER the arrow
+      // and export rules: `scan()` keeps the first rule that matches a line.
+      { re: /^(?:const|let|var)\s+(?<name>[\w$]+)\s*[:=]/, kind: "const", exported: false },
       // `export default Foo;` — a class/const declared above and exported by reference.
       { re: /^\s*export\s+default\s+(?<name>[A-Za-z_$][\w$]*)\s*;?\s*$/, kind: "default", exported: true }
     ];
@@ -6069,7 +6081,15 @@ var init_specs = __esm({
         "arguments",
         "arrow_function",
         "function_expression",
-        "function"
+        "function",
+        // The IIFE's own link: `(function () { … })()` parses as
+        // expression_statement → call_expression → parenthesized_expression →
+        // function_expression, and without the parens listed the descent stopped one
+        // node short — the same break the statement containers above were added for.
+        // Whole categories of file are written inside one (browser scripts, UMD and
+        // loader bundles), so for those the index held no functions at all. Named by
+        // the ctags differential on a real loader script.
+        "parenthesized_expression"
       ]),
       exported: neverExport,
       // export is tracked structurally; see LangSpec.exportMarkers

package/src/vendor/engine.meta.json

@@ -1,9 +1,9 @@
 {
-  "tag": "v2.22.0",
-  "engineVersion": "2.22.0",
+  "tag": "v2.24.2",
+  "engineVersion": "2.24.2",
   "sha256": {
-    "codeindex-engine.mjs": "97cf34f1fcee485a9163fab4f6357b2d8871a9bfa199f4527d28e02a3f8889cb",
-    "codeindex-engine.d.mts": "ee9589e36691679c854553e6f4e3fa158052da92c85501f34a8911834801f210"
+    "codeindex-engine.mjs": "209509d1e757d15cb0ac5c6b52a2e47c3f1cb17630c895a72140e0b3a8193ee6",
+    "codeindex-engine.d.mts": "0c744308646ec98c78afdbfcd9febf48532394101ace541a5c1f432549ad2397"
   },
-  "syncedAt": "2026-07-31T09:30:22.297Z"
+  "syncedAt": "2026-08-01T08:55:39.105Z"
 }