@amsterdamdatalabs/enact-extensions 0.1.0 → 0.1.3

package/scripts/hooks/session-start-drift-check.mjs

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+/**
+ * session-start-drift-check.mjs — Enact Extensions session-start drift hook.
+ *
+ * Registered as a session-start hook for Claude, Codex, Cursor, and Enact.
+ * Checks whether any installed enact-extensions plugins have drifted from
+ * their canonical source (i.e. are outdated) and prints a concise advisory
+ * if so.
+ *
+ * Design constraints:
+ *   - FAIL-SILENT: wrap everything in try/catch; never throw; always exit 0.
+ *   - FAST: imports computeOutdated directly (no subprocess) for speed.
+ *   - READ-ONLY: never writes any state.
+ *   - NO OUTPUT on success (or error): only print when there are outdated entries.
+ *   - DEPENDENCY-FREE: only node builtins + enact-extensions own modules.
+ */
+
+import { dirname, resolve, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+// Navigate from scripts/hooks/ up to the repo root so we can import lib modules.
+const REPO_ROOT = resolve(__dirname, "..", "..");
+
+try {
+  // Dynamically import so any module-load failure is caught by the outer try/catch.
+  const { computeOutdated } = await import(join(REPO_ROOT, "scripts", "lib", "outdated.mjs"));
+
+  let entries;
+  try {
+    entries = computeOutdated();
+  } catch {
+    // computeOutdated threw (ledger missing, I/O error, etc.) — stay silent.
+    process.exit(0);
+  }
+
+  // Filter to only outdated entries (not fresh, not orphaned).
+  const outdated = (entries ?? []).filter((e) => e && e.status === "outdated");
+
+  if (outdated.length === 0) {
+    // Nothing to report.
+    process.exit(0);
+  }
+
+  // Build a concise list of (plugin, surface) pairs.
+  const pairs = outdated
+    .map((e) => `${e.name}/${e.platform}`)
+    .join(", ");
+
+  // Single advisory line to stdout.
+  process.stdout.write(
+    `[enact-extensions] ${outdated.length} plugin surface${outdated.length === 1 ? "" : "s"} outdated: ${pairs}. Run: enact-extensions update --all\n`,
+  );
+} catch {
+  // Any top-level error (import failure, parse error, etc.) — silent exit 0.
+}
+
+process.exit(0);

package/scripts/lib/build-index.mjs

@@ -0,0 +1,50 @@
+import { relative } from "node:path";
+import { listBundles } from "./list-bundles.mjs";
+
+/**
+ * Build a discovery index of all plugin bundles.
+ *
+ * The index is a generated artifact — it is NEVER committed. The schema
+ * contract lives in spec/index.json.
+ *
+ * @param {string[]} roots         - Absolute paths to scan for plugin bundles
+ *                                   (passed directly to listBundles).
+ * @param {object}  [opts]
+ * @param {string|null} [opts.now] - ISO timestamp to stamp on generatedAt.
+ *                                   Pass a fixed value for deterministic tests.
+ *                                   Defaults to null when omitted — this lib is
+ *                                   pure and never calls new Date(). The CLI
+ *                                   boundary computes the live timestamp and
+ *                                   passes it in as `now`.
+ * @param {string}  [opts.packageRoot] - Absolute package root used to compute
+ *                                       repo-relative paths. Defaults to the
+ *                                       directory two levels above this file.
+ * @returns {{ generatedAt: string|null, count: number, plugins: object[] }}
+ */
+export function buildIndex(roots, opts = {}) {
+  const { now = null, packageRoot } = opts;
+
+  // Resolve package root: two levels up from this file (scripts/lib/ → repo root)
+  const pkgRoot =
+    packageRoot ??
+    new URL("../../", import.meta.url).pathname.replace(/\/$/, "");
+
+  // Source bundles via the canonical list-bundles helper (deduplicated, resilient).
+  const entries = listBundles(roots);
+
+  const plugins = entries.map((entry) => ({
+    name: entry.name,
+    version: entry.version,
+    category: entry.category,
+    description: entry.description,
+    targets: entry.targets,
+    // Make path repo-relative so the artifact is portable.
+    path: relative(pkgRoot, entry.path),
+  }));
+
+  return {
+    generatedAt: now,
+    count: plugins.length,
+    plugins,
+  };
+}

package/scripts/lib/bundle-hash.mjs

@@ -0,0 +1,137 @@
+/**
+ * bundle-hash.mjs — deterministic content hash for a plugin bundle.
+ *
+ * bundleHash(pluginRoot) → sha256 hex string
+ *
+ * The hash covers the CANONICAL bundle content only:
+ *   - .agents/plugin.json (the manifest itself)
+ *   - Component dirs/files referenced in the manifest:
+ *       skills, mcpServers, apps, commands, hooks, agents, _agents, rules
+ *   - .mcp.json (if present at pluginRoot root)
+ *
+ * EXCLUDED (generated / derived surfaces, never present in canonical source):
+ *   - .claude-plugin/
+ *   - .codex-plugin/
+ *   - .cursor-plugin/
+ *
+ * Algorithm:
+ *   1. Collect the set of paths to include (manifest + referenced component paths).
+ *   2. Walk each path recursively; collect all (relativePath, bytes) pairs.
+ *   3. Sort by relative path (order-independence).
+ *   4. Feed path + bytes for each file into a single sha256 digest.
+ *   5. Return the hex digest.
+ *
+ * Pure, no writes, synchronous.
+ */
+
+import { createHash } from "node:crypto";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+
+// ---------------------------------------------------------------------------
+// Canonical component field names (mirrors pathFieldsFromManifest in install.ts)
+// ---------------------------------------------------------------------------
+const COMPONENT_FIELDS = [
+  "skills",
+  "mcpServers",
+  "apps",
+  "commands",
+  "hooks",
+  "agents",
+  "_agents",
+  "rules",
+];
+
+// Generated platform dirs — always excluded from the canonical hash.
+const EXCLUDED_DIRS = new Set([".claude-plugin", ".codex-plugin", ".cursor-plugin"]);
+
+/**
+ * Recursively collect all file entries under `root`.
+ * Returns an array of { rel: string, abs: string } sorted by rel.
+ * Silently skips non-file, non-directory entries.
+ *
+ * @param {string} abs - absolute path to walk
+ * @param {string} base - the pluginRoot (for computing relative paths)
+ * @param {string[]} acc - accumulator
+ */
+function walkFiles(abs, base, acc) {
+  if (!existsSync(abs)) return;
+  const stat = statSync(abs);
+  if (stat.isFile()) {
+    acc.push(relative(base, abs));
+    return;
+  }
+  if (!stat.isDirectory()) return;
+  const entries = readdirSync(abs).sort(); // sort for determinism
+  for (const name of entries) {
+    walkFiles(join(abs, name), base, acc);
+  }
+}
+
+/**
+ * Collect the canonical set of relative paths to include in the hash.
+ *
+ * @param {string} pluginRoot
+ * @param {object} manifest - parsed .agents/plugin.json
+ * @returns {string[]} sorted relative paths (relative to pluginRoot)
+ */
+function canonicalPaths(pluginRoot, manifest) {
+  // Always include the manifest itself.
+  const collected = [];
+
+  // 1. Always walk .agents/plugin.json (the manifest).
+  walkFiles(join(pluginRoot, ".agents", "plugin.json"), pluginRoot, collected);
+
+  // 2. Walk each component path that exists.
+  for (const field of COMPONENT_FIELDS) {
+    const raw = manifest[field];
+    if (typeof raw !== "string" || !raw.trim()) continue;
+    // Normalise: strip leading ./ and trailing /
+    const cleaned = raw.replace(/^\.\//, "").replace(/\/+$/, "");
+    if (!cleaned || cleaned.startsWith("../")) continue;
+    // Refuse to hash generated platform dirs even if the manifest references them.
+    const topSegment = cleaned.split("/")[0];
+    if (EXCLUDED_DIRS.has(topSegment)) continue;
+    walkFiles(join(pluginRoot, cleaned), pluginRoot, collected);
+  }
+
+  // 3. .mcp.json at pluginRoot root (included if present, regardless of manifest field)
+  walkFiles(join(pluginRoot, ".mcp.json"), pluginRoot, collected);
+
+  // Sort for order-independence, then deduplicate.
+  const unique = [...new Set(collected)].sort();
+  return unique;
+}
+
+/**
+ * Compute a deterministic sha256 hex hash of the canonical plugin bundle.
+ *
+ * @param {string} pluginRoot - absolute path to the bundle root
+ * @returns {string} sha256 hex digest (64 lowercase hex chars)
+ * @throws {Error} if the manifest cannot be read (ENOENT, parse error, etc.)
+ */
+export function bundleHash(pluginRoot) {
+  // Read and parse the manifest first — this is the anchor; if it's missing
+  // we cannot know which component paths to include, so we throw.
+  const manifestPath = join(pluginRoot, ".agents", "plugin.json");
+  if (!existsSync(manifestPath)) {
+    throw new Error(`Cannot compute bundle hash: manifest not found at ${manifestPath}`);
+  }
+  const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+
+  // Collect the sorted list of relative paths.
+  const paths = canonicalPaths(pluginRoot, manifest);
+
+  // Hash all paths and their contents in sorted order.
+  const hash = createHash("sha256");
+  for (const rel of paths) {
+    const abs = join(pluginRoot, rel);
+    // Feed the relative path as a NUL-terminated string to make path changes
+    // visible even when content is identical.
+    hash.update(rel + "\0", "utf8");
+    // Feed the file bytes.
+    hash.update(readFileSync(abs));
+  }
+
+  return hash.digest("hex");
+}