@amsterdamdatalabs/enact-extensions 0.1.37 → 0.1.47

package/scripts/lib/ledger.mjs

@@ -1,163 +0,0 @@
-import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
-import { homedir } from "node:os";
-import { dirname, join } from "node:path";
-
-/**
- * Install ledger — a JSONL record of install/uninstall events.
- *
- * There is exactly ONE ledger location — the GLOBAL file:
- *   <home>/.enact/extensions/ledger.jsonl   (home defaults to os.homedir())
- *
- * The local-vs-global install distinction is tracked PURELY as the `scope`
- * FIELD inside each entry (scope:"local" | scope:"global"); BOTH scopes write
- * to this single global ledger. The `home` override exists so tests never touch
- * the real ~/.enact.
- *
- * Entry shape: { ts, action, name, version, platform, scope, home, path, marketplaceName }
- *
- * All file I/O is best-effort: failures throw a catchable error so callers
- * (the install path) can swallow + warn rather than aborting an install.
- */
-
-/**
- * Resolve the on-disk ledger path. Always the single global file.
- * @param {object} [opts]
- * @param {string} [opts.home] - home dir. Defaults to os.homedir().
- * @returns {string}
- */
-export function ledgerPath({ home } = {}) {
-  return join(home ?? homedir(), ".enact", "extensions", "ledger.jsonl");
-}
-
-/**
- * Append a single entry as one JSON line. Creates the parent dir if missing.
- * `ts` defaults to new Date().toISOString() when absent (an injected ts is kept).
- * Best-effort: throws a catchable error on I/O failure.
- *
- * @param {object} entry
- * @param {object} [opts] - { home }
- */
-export function appendEntry(entry, { home } = {}) {
-  const record = { ts: entry.ts ?? new Date().toISOString(), ...entry };
-  // Ensure ts wins even if entry has an explicit undefined.
-  if (!record.ts) record.ts = new Date().toISOString();
-  const path = ledgerPath({ home });
-  mkdirSync(dirname(path), { recursive: true });
-  appendFileSync(path, `${JSON.stringify(record)}\n`, "utf8");
-}
-
-/**
- * Read and parse all entries from the single global ledger.
- * Missing file → []. Malformed lines are skipped with a stderr warning.
- *
- * @param {object} [opts] - { home }
- * @returns {object[]}
- */
-export function readLedger({ home } = {}) {
-  const path = ledgerPath({ home });
-  if (!existsSync(path)) return [];
-  let raw;
-  try {
-    raw = readFileSync(path, "utf8");
-  } catch (err) {
-    process.stderr.write(
-      `[enact-extensions log] Warning: cannot read ledger ${path}: ${err instanceof Error ? err.message : String(err)}\n`,
-    );
-    return [];
-  }
-  const entries = [];
-  for (const line of raw.split("\n")) {
-    const trimmed = line.trim();
-    if (!trimmed) continue;
-    try {
-      entries.push(JSON.parse(trimmed));
-    } catch {
-      process.stderr.write(
-        `[enact-extensions log] Warning: skipping malformed ledger line in ${path}\n`,
-      );
-    }
-  }
-  return entries;
-}
-
-/**
- * Thin alias of {@link readLedger}, retained so existing callers keep working.
- * With the single-global ledger there is no merge to perform: global- and
- * local-scope entries are co-located in the one file.
- *
- * @param {object} [opts] - { home }
- * @returns {object[]}
- */
-export function readMerged({ home } = {}) {
-  return readLedger({ home });
-}
-
-/**
- * Compute the current install state for `name` by replaying install/uninstall
- * events in ts order across the single global ledger. Returns the set of
- * still-installed targets as { platform, scope, home, path }.
- *
- * A target is keyed by platform+scope+home+path so the same plugin installed to
- * multiple platforms/homes is tracked independently.
- *
- * @param {string} name
- * @param {object} [opts] - { home }
- * @returns {{ platform: string, scope: string, home: string, path: string }[]}
- */
-export function findInstalled(name, { home } = {}) {
-  const merged = readLedger({ home }).filter((e) => e && e.name === name);
-  // Stable sort by ts (string ISO compares chronologically).
-  merged.sort((a, b) => String(a.ts ?? "").localeCompare(String(b.ts ?? "")));
-
-  const state = new Map();
-  for (const e of merged) {
-    const key = `${e.platform} ${e.scope} ${e.home ?? ""} ${e.path ?? ""}`;
-    if (e.action === "install") {
-      state.set(key, { platform: e.platform, scope: e.scope, home: e.home, path: e.path });
-    } else if (e.action === "uninstall") {
-      state.delete(key);
-    }
-  }
-  return [...state.values()];
-}
-
-/**
- * Compute the current install state for ALL plugins by replaying install/uninstall
- * events in ts order across the single global ledger. Returns the set of
- * still-installed targets across all plugin names.
- *
- * Each returned entry carries the full ledger fields for the installed surface:
- *   { name, version, platform, scope, home, path, hash, marketplaceName }
- *
- * A target is keyed by name+platform+scope+home+path so the same plugin installed
- * to multiple platforms/homes/names is tracked independently.
- *
- * @param {object} [opts] - { home }
- * @returns {{ name: string, version: string, platform: string, scope: string, home: string, path: string, hash: string|null, marketplaceName: string|null }[]}
- */
-export function listInstalled({ home } = {}) {
-  const all = readLedger({ home });
-  // Stable sort by ts (string ISO compares chronologically).
-  all.sort((a, b) => String(a.ts ?? "").localeCompare(String(b.ts ?? "")));
-
-  const state = new Map();
-  for (const e of all) {
-    if (!e || !e.name) continue;
-    const key = `${e.name} ${e.platform ?? ""} ${e.scope ?? ""} ${e.home ?? ""} ${e.path ?? ""}`;
-    if (e.action === "install") {
-      state.set(key, {
-        name: e.name,
-        version: e.version ?? null,
-        platform: e.platform,
-        scope: e.scope,
-        home: e.home,
-        path: e.path,
-        hash: e.hash ?? null,
-        marketplaceName: e.marketplaceName ?? null,
-      });
-    } else if (e.action === "uninstall") {
-      state.delete(key);
-    }
-  }
-  return [...state.values()];
-}

package/scripts/lib/migrate-artifacts.mjs

@@ -1,144 +0,0 @@
-/**
- * Idempotent migration for global factory/loop markdown artifacts to YYMMDDHH-<slug>.md.
- */
-
-import { existsSync, readdirSync, renameSync, statSync } from "node:fs";
-import { join } from "node:path";
-import { homedir } from "node:os";
-
-const TIMESTAMPED_RE = /^(\d{8})-(.+\.md)$/;
-const ISO_DATE_RE = /^(20\d{2})-(\d{2})-(\d{2})-(.+)$/;
-
-export function timestampPrefixFromDate(date) {
-  const yy = String(date.getFullYear()).slice(2);
-  const mm = String(date.getMonth() + 1).padStart(2, "0");
-  const dd = String(date.getDate()).padStart(2, "0");
-  const hh = String(date.getHours()).padStart(2, "0");
-  return `${yy}${mm}${dd}${hh}`;
-}
-
-export function targetNameForLegacy(fileName, mtimeMs, fallbackHour = "00") {
-  if (TIMESTAMPED_RE.test(fileName)) return null;
-
-  const iso = ISO_DATE_RE.exec(fileName);
-  if (iso) {
-    const [, yyyy, mm, dd, rest] = iso;
-    return `${yyyy.slice(2)}${mm}${dd}${fallbackHour}-${rest}`;
-  }
-
-  const mtime = new Date(mtimeMs);
-  return `${timestampPrefixFromDate(mtime)}-${fileName}`;
-}
-
-/**
- * @param {string} dir
- * @param {{ dryRun?: boolean, fallbackHour?: string }} [opts]
- */
-export function migrateMarkdownDir(dir, opts = {}) {
-  const dryRun = Boolean(opts.dryRun);
-  const fallbackHour = opts.fallbackHour ?? "00";
-  const renamed = [];
-  const skipped = [];
-  const fallbacks = [];
-
-  if (!existsSync(dir)) return { renamed, skipped, fallbacks };
-
-  for (const name of readdirSync(dir)) {
-    if (!name.endsWith(".md")) continue;
-    if (TIMESTAMPED_RE.test(name)) {
-      skipped.push(name);
-      continue;
-    }
-
-    const target = targetNameForLegacy(name, statSync(join(dir, name)).mtimeMs, fallbackHour);
-    if (!target || target === name) {
-      skipped.push(name);
-      continue;
-    }
-
-    const targetPath = join(dir, target);
-    if (existsSync(targetPath)) {
-      skipped.push(name);
-      continue;
-    }
-
-    if (ISO_DATE_RE.test(name)) {
-      fallbacks.push({ from: name, to: target, reason: "iso-date-hour-fallback" });
-    }
-
-    if (!dryRun) {
-      renameSync(join(dir, name), targetPath);
-    }
-    renamed.push({ from: name, to: target });
-  }
-
-  return { renamed, skipped, fallbacks };
-}
-
-/**
- * @param {{ dryRun?: boolean, factoryRoot?: string, loopRoot?: string }} [opts]
- */
-export function migrateGlobalArtifacts(opts = {}) {
-  const dryRun = Boolean(opts.dryRun);
-  const factoryRoot = opts.factoryRoot ?? join(homedir(), ".enact", "factory", "projects");
-  const loopRoot = opts.loopRoot ?? join(homedir(), ".enact", "loop", "projects");
-  const report = {
-    dryRun,
-    factory: [],
-    loop: [],
-    fallbacks: [],
-  };
-
-  if (existsSync(factoryRoot)) {
-    for (const project of readdirSync(factoryRoot, { withFileTypes: true })) {
-      if (!project.isDirectory()) continue;
-      const plansDir = join(factoryRoot, project.name, "plans");
-      const researchDir = join(factoryRoot, project.name, "research");
-      for (const dir of [plansDir, researchDir]) {
-        const result = migrateMarkdownDir(dir, { dryRun });
-        if (result.renamed.length || result.skipped.length) {
-          report.factory.push({ project: project.name, dir, ...result });
-        }
-        report.fallbacks.push(...result.fallbacks.map((f) => ({ ...f, project: project.name, dir })));
-      }
-    }
-  }
-
-  if (existsSync(loopRoot)) {
-    for (const project of readdirSync(loopRoot, { withFileTypes: true })) {
-      if (!project.isDirectory()) continue;
-      const stateDir = join(loopRoot, project.name, "state");
-      const legacy = join(stateDir, "summary.md");
-      if (!existsSync(legacy)) continue;
-
-      const hasTimestamped = readdirSync(stateDir).some((name) =>
-        /^\d{8}-loop-summary\.md$/.test(name),
-      );
-      if (hasTimestamped) {
-        report.loop.push({
-          project: project.name,
-          dir: stateDir,
-          renamed: [],
-          skipped: ["summary.md"],
-          fallbacks: [],
-        });
-        continue;
-      }
-
-      const mtime = statSync(legacy).mtimeMs;
-      const target = `${timestampPrefixFromDate(new Date(mtime))}-loop-summary.md`;
-      if (!dryRun) {
-        renameSync(legacy, join(stateDir, target));
-      }
-      report.loop.push({
-        project: project.name,
-        dir: stateDir,
-        renamed: [{ from: "summary.md", to: target }],
-        skipped: [],
-        fallbacks: [],
-      });
-    }
-  }
-
-  return report;
-}

package/scripts/lib/outdated.mjs

@@ -1,144 +0,0 @@
-/**
- * outdated.mjs — compute freshness drift between installed plugins and their
- * canonical source bundles.
- *
- * computeOutdated({ home?, cwd? }) → OutdatedEntry[]
- *
- * For each currently-installed (plugin, platform, scope, home) surface from the
- * ledger, resolves the canonical source bundle (extensions/<name>) and classifies:
- *
- *   fresh    — canonical source exists and its hash matches the ledger's recorded hash.
- *   outdated — canonical source exists but hash differs (or ledger hash is null/missing),
- *              or the recorded version differs (future: not currently used for the flag,
- *              but hash comparison is the primary signal).
- *   orphaned — canonical source does NOT exist on disk; cannot refresh.
- *
- * Returns a sorted array of OutdatedEntry objects:
- *   { name, platform, scope, home, status, installedHash, currentHash, version }
- *
- * Pure-ish: reads ledger + canonical bundle; no writes.
- */
-
-import { homedir } from "node:os";
-import { cwd as processCwd } from "node:process";
-import { bundleHash } from "./bundle-hash.mjs";
-import { listInstalled } from "./ledger.mjs";
-import { resolveBundlePath } from "./resolve-bundle.mjs";
-
-/**
- * @typedef {object} OutdatedEntry
- * @property {string} name
- * @property {string} platform
- * @property {string} scope
- * @property {string} home
- * @property {"fresh"|"outdated"|"orphaned"} status
- * @property {string|null} installedHash  — hash recorded at install time (may be null)
- * @property {string|null} currentHash    — hash of canonical source now (null if orphaned)
- * @property {string|null} version        — version recorded in the ledger
- */
-
-/**
- * Safely compute the canonical bundle hash for a given bundle root.
- * Returns null on any error (missing manifest, I/O error, etc.).
- *
- * @param {string} bundleRoot
- * @returns {string|null}
- */
-function safeHash(bundleRoot) {
-  try {
-    return bundleHash(bundleRoot);
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Resolve the canonical bundle path for a plugin name.
- * Returns null when the canonical source cannot be found (so caller can
- * classify as orphaned rather than crashing).
- *
- * @param {string} name
- * @param {string} cwd
- * @returns {string|null}
- */
-function safeResolveBundlePath(name, cwd) {
-  try {
-    return resolveBundlePath(name, { cwd });
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Compute freshness status for all currently-installed plugin surfaces.
- *
- * @param {object} [opts]
- * @param {string} [opts.home]   — ledger home override (defaults to os.homedir())
- * @param {string} [opts.cwd]   — working directory for bundle resolution (defaults to process.cwd())
- * @returns {OutdatedEntry[]} sorted by name, then platform, then scope
- */
-export function computeOutdated({ home, cwd } = {}) {
-  const resolvedHome = home ?? homedir();
-  const resolvedCwd = cwd ?? processCwd();
-
-  // Get all currently-installed entries (install replayed over uninstall).
-  const installed = listInstalled({ home: resolvedHome });
-
-  /** @type {OutdatedEntry[]} */
-  const results = [];
-
-  for (const entry of installed) {
-    const { name, platform, scope, home: entryHome, version, hash: installedHash } = entry;
-
-    // Resolve canonical source bundle for this plugin name.
-    const canonicalPath = safeResolveBundlePath(name, resolvedCwd);
-
-    if (!canonicalPath) {
-      // Canonical source does not exist → orphaned.
-      results.push({
-        name,
-        platform,
-        scope,
-        home: entryHome,
-        status: "orphaned",
-        installedHash: installedHash ?? null,
-        currentHash: null,
-        version: version ?? null,
-      });
-      continue;
-    }
-
-    // Canonical source exists — compute its current hash.
-    const currentHash = safeHash(canonicalPath);
-
-    let status;
-    if (installedHash == null || currentHash == null || installedHash !== currentHash) {
-      // No recorded hash, or canonical hash is uncomputable, or hashes differ.
-      status = "outdated";
-    } else {
-      status = "fresh";
-    }
-
-    results.push({
-      name,
-      platform,
-      scope,
-      home: entryHome,
-      status,
-      installedHash: installedHash ?? null,
-      currentHash,
-      version: version ?? null,
-    });
-  }
-
-  // Deterministic sort: name → platform → scope
-  results.sort((a, b) => {
-    const n = String(a.name ?? "").localeCompare(String(b.name ?? ""));
-    if (n !== 0) return n;
-    const p = String(a.platform ?? "").localeCompare(String(b.platform ?? ""));
-    if (p !== 0) return p;
-    return String(a.scope ?? "").localeCompare(String(b.scope ?? ""));
-  });
-
-  return results;
-}

package/scripts/lib/postinstall-offer.mjs

@@ -1,83 +0,0 @@
-/**
- * postinstall-offer.mjs — interactive drift-refresh offer shown at postinstall.
- *
- * Exports ONE function:
- *   offerDriftRefresh({ isTTY, computeOutdatedFn, promptYesNo, runUpdateFn, write })
- *
- * Contract:
- *   - non-TTY                → silent; return { offered: false, updated: false }
- *   - TTY + zero outdated    → silent; return { offered: false, updated: false }
- *   - TTY + outdated entries → write summary, then:
- *       - autoYes set → apply WITHOUT prompting; return { offered: true, updated: true }
- *       - else prompt:
- *           - user yes → runUpdateFn({ all: true }); return { offered: true, updated: true }
- *           - user no  → write manual command hint; return { offered: true, updated: false }
- *   - Any error              → fail-silent; return { offered: false, updated: false }
- *                              (except: if runUpdateFn throws after a yes answer,
- *                               return { offered: true, updated: false })
- *
- * `autoYes` is the USER's opt-in (callers derive it from
- * process.env.ENACT_EXTENSIONS_AUTO_UPDATE); this module never reads env itself.
- */
-
-/**
- * Offer the user a drift refresh if any installed plugins are outdated.
- *
- * @param {object} opts
- * @param {boolean} opts.isTTY - whether the terminal is interactive
- * @param {boolean} [opts.autoYes] - when true, apply without prompting (user opt-in)
- * @param {() => Promise<import("./outdated.mjs").OutdatedEntry[]>} opts.computeOutdatedFn
- * @param {(question: string) => Promise<boolean>} opts.promptYesNo
- * @param {(opts: { all: boolean }) => void | Promise<void>} opts.runUpdateFn
- * @param {(msg: string) => void} opts.write
- * @returns {Promise<{ offered: boolean, updated: boolean }>}
- */
-export async function offerDriftRefresh({ isTTY, autoYes, computeOutdatedFn, promptYesNo, runUpdateFn, write }) {
-  try {
-    // Non-interactive: exit immediately without any work.
-    if (!isTTY) {
-      return { offered: false, updated: false };
-    }
-
-    // Compute outdated entries and filter to status === "outdated" only.
-    const entries = await computeOutdatedFn();
-    const outdated = entries.filter((e) => e.status === "outdated");
-
-    // Nothing to do.
-    if (outdated.length === 0) {
-      return { offered: false, updated: false };
-    }
-
-    // Write summary line listing the outdated name/platform pairs.
-    const pairs = outdated.map((e) => `${e.name}/${e.platform}`).join(", ");
-    write(`\nenact-extensions: ${outdated.length} plugin(s) have drifted from their source: ${pairs}\n`);
-
-    // Opt-in auto-apply: skip the prompt and refresh directly.
-    if (autoYes) {
-      try {
-        await runUpdateFn({ all: true });
-        return { offered: true, updated: true };
-      } catch {
-        return { offered: true, updated: false };
-      }
-    }
-
-    // Prompt user.
-    const yes = await promptYesNo("Update all now? [Y/n] ");
-
-    if (yes) {
-      try {
-        await runUpdateFn({ all: true });
-        return { offered: true, updated: true };
-      } catch {
-        return { offered: true, updated: false };
-      }
-    } else {
-      write(`Run \`enact-extensions update --all\` to update manually.\n`);
-      return { offered: true, updated: false };
-    }
-  } catch {
-    // Fail-silent: never throw from postinstall-related code.
-    return { offered: false, updated: false };
-  }
-}

package/scripts/lib/principles.mjs

@@ -1,109 +0,0 @@
-/**
- * principles.mjs — Operating-principles block injection for host agent files.
- *
- * Surfaces: claude, codex, cursor, enact
- * Writes managed blocks into CLAUDE.md / AGENTS.md (not settings.json).
- */
-
-import {
-  applyBlock,
-  checkBlock,
-  removeBlock,
-  renderBlock,
-  resolveHostFile,
-  SUPPORTED_PRINCIPLES_SURFACES,
-} from "../../dist/index.js";
-
-export { SUPPORTED_PRINCIPLES_SURFACES };
-
-/**
- * @param {string} surface
- * @param {object} [opts]
- * @returns {{ surface: string, path: string, result: string, action?: string }}
- */
-export function setupPrinciples(surface, opts = {}) {
-  const hostFile = resolveHostFile(surface, opts);
-  const block = renderBlock(opts.doctrinePath);
-  const { action } = applyBlock(hostFile, block);
-  return {
-    surface,
-    path: hostFile,
-    result: action === "noop" ? "already_present" : "applied",
-    action,
-  };
-}
-
-/**
- * @param {string} surface
- * @param {object} [opts]
- * @returns {{ surface: string, path: string, result: string }}
- */
-export function removePrinciples(surface, opts = {}) {
-  const hostFile = resolveHostFile(surface, opts);
-  const { removed } = removeBlock(hostFile);
-  return {
-    surface,
-    path: hostFile,
-    result: removed ? "removed" : "not_found",
-  };
-}
-
-/**
- * @param {string} surface
- * @param {object} [opts]
- * @returns {{ surface: string, path: string, status: string }}
- */
-export function checkPrinciples(surface, opts = {}) {
-  const hostFile = resolveHostFile(surface, opts);
-  const block = renderBlock(opts.doctrinePath);
-  const status = checkBlock(hostFile, block);
-  return { surface, path: hostFile, status };
-}
-
-/**
- * @param {string} surface
- * @param {object} [opts]
- * @returns {{ surface: string, path: string, status: string, action?: string, result?: string }}
- */
-export function fixPrinciples(surface, opts = {}) {
-  const check = checkPrinciples(surface, opts);
-  if (check.status === "present") {
-    return { ...check, result: "already_present", action: "noop" };
-  }
-  const setup = setupPrinciples(surface, opts);
-  const after = checkPrinciples(surface, opts);
-  return {
-    surface,
-    path: setup.path,
-    status: after.status,
-    action: setup.action,
-    result: setup.result,
-  };
-}
-
-/**
- * @param {string[]} surfaces
- * @param {object} [opts]
- * @param {boolean} [opts.fix]
- * @returns {{ rows: object[], drift: boolean, exitCode: number }}
- */
-export function runDoctor(surfaces, opts = {}) {
-  const rows = [];
-  let exitCode = 0;
-
-  for (const surface of surfaces) {
-    try {
-      const row = opts.fix ? fixPrinciples(surface, opts) : checkPrinciples(surface, opts);
-      rows.push(row);
-      if (row.status !== "present") {
-        exitCode = 1;
-      }
-    } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-      rows.push({ surface, path: "", status: "error", error: message });
-      exitCode = 1;
-    }
-  }
-
-  return { rows, drift: exitCode !== 0, exitCode };
-}

package/scripts/lib/provision-mcp.mjs

@@ -1,16 +0,0 @@
-/**
- * CLI/runtime wrapper over the typed library provisioning API.
- *
- * The script-layer helpers remain for backwards compatibility with tests and
- * the CLI wrapper, but the source of truth now lives in src/provision.ts and is
- * exported from dist/index.js for in-process consumers.
- */
-import {
-  provisionMcp as provisionMcpCore,
-  readMcpServers as readMcpServersCore,
-  summarizeProvision as summarizeProvisionCore,
-} from "../../dist/index.js";
-
-export const readMcpServers = readMcpServersCore;
-export const provisionMcp = provisionMcpCore;
-export const summarizeProvision = summarizeProvisionCore;

package/scripts/lib/resolve-plugin-root.mjs

@@ -1,9 +0,0 @@
-import { resolve } from "node:path";
-import { cwd } from "node:process";
-
-/**
- * Resolve plugin root: explicit path arg or current working directory.
- */
-export function resolvePluginRoot(pathArg) {
-  return resolve(pathArg ?? cwd());
-}