@amsterdamdatalabs/enact-extensions 0.1.42 → 0.1.48

package/scripts/lib/ups-router.mjs

@@ -1,392 +0,0 @@
-/**
- * ups-router.mjs — pure, testable module for the UserPromptSubmit keyword-router.
- *
- * Discovers plugin bundles and their skills, extracts explicit trigger phrases
- * from SKILL.md frontmatter, and routes a user prompt to matching skills.
- *
- * Two exports:
- *   buildSkillCatalog(extensionsDir)  → CatalogEntry[]
- *   routePrompt(prompt, catalog)      → RouteResult
- *
- * Both are deterministic and side-effect free (no network, no writes, no clock).
- */
-import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
-import { join, resolve } from "node:path";
-
-// ---------------------------------------------------------------------------
-// Types (JSDoc)
-// ---------------------------------------------------------------------------
-
-/**
- * @typedef {{ skill: string, plugin: string, keywords: string[], invoke: string }} CatalogEntry
- * @typedef {{ skill: string, plugin: string, invoke: string, reason: string }} RouteMatch
- * @typedef {{ matches: RouteMatch[], additionalContext: string|null }} RouteResult
- */
-
-// ---------------------------------------------------------------------------
-// Stop-word list — short or trivial tokens that should never fire a match.
-// The list is intentionally broad: we want precision over recall in the router
-// so that only genuinely skill-relevant keywords generate matches.
-// ---------------------------------------------------------------------------
-
-const STOP_WORDS = new Set([
-  // articles, conjunctions, prepositions
-  "a", "an", "the", "and", "or", "but", "in", "on", "at", "to", "for",
-  "of", "with", "by", "from", "up", "as", "via", "per",
-  // pronouns / determiners
-  "it", "its", "this", "that", "these", "those", "i", "we", "you", "he",
-  "she", "they", "my", "our", "your", "their", "its", "all", "any", "both",
-  // copula / auxiliaries
-  "is", "are", "was", "were", "be", "been", "being", "have", "has", "had",
-  "do", "does", "did", "will", "would", "could", "should", "may", "might",
-  "can", "shall", "must",
-  // high-frequency verbs that are not skill identifiers
-  "get", "set", "put", "let", "run", "use", "add", "see", "say", "ask",
-  "go", "give", "make", "take", "want", "need", "know", "keep", "find",
-  "call", "read", "work", "look", "show", "used", "each", "also", "into",
-  "when", "then", "than", "just", "more", "most", "only", "such", "even",
-  "now", "new", "not", "no", "so", "if", "how", "what", "which", "where",
-  "who", "why", "over", "after", "before", "about", "like",
-  // generic nouns too broad to be useful keywords
-  "task", "work", "file", "data", "code", "tool", "type", "name", "list",
-  "item", "part", "case", "time", "step", "way", "mode", "form", "end",
-  "start", "path", "user", "output", "input", "result", "context", "note",
-  "example", "reason", "detail", "value", "field", "key", "state", "stage",
-]);
-
-/**
- * Return true when token should be excluded as a keyword.
- * Tokens shorter than 3 characters, or pure stop-words, are excluded.
- *
- * @param {string} token
- * @returns {boolean}
- */
-function isStopWord(token) {
-  if (token.length < 3) return true;
-  return STOP_WORDS.has(token.toLowerCase());
-}
-
-// ---------------------------------------------------------------------------
-// Frontmatter parsing
-// ---------------------------------------------------------------------------
-
-/**
- * Extract the YAML frontmatter block from a Markdown file's text.
- * Returns null when no frontmatter block is found.
- *
- * @param {string} text
- * @returns {string|null}
- */
-function extractFrontmatterBlock(text) {
-  if (!text.startsWith("---")) return null;
-  const m = /^---\n([\s\S]*?)\n---/.exec(text);
-  return m ? m[1] : null;
-}
-
-/**
- * Parse a specific scalar field from a raw YAML frontmatter block.
- * Handles both single-line `field: "value"` and block-scalar `field: >\n  val`.
- *
- * @param {string} block  Raw frontmatter text (between the --- delimiters).
- * @param {string} field  Field name to extract.
- * @returns {string|null}
- */
-function parseFrontmatterField(block, field) {
-  // Match single-line scalar: field: value  (quoted or bare).
-  // After extracting the value, skip it when it is a block-scalar indicator
-  // (">", ">-", "|", "|-", etc.) so those fall through to the block-scalar branch.
-  const singleLine = new RegExp(`(?:^|\\n)${field}:\\s*(?:["']([^"'\\n]*)["']|(.+))`, "m");
-  const sl = singleLine.exec(block);
-  if (sl) {
-    const raw = (sl[1] ?? sl[2] ?? "").trim();
-    // Reject YAML block-scalar indicators so we fall through to the block branch.
-    if (raw && !/^[>|]-?$/.test(raw)) {
-      return raw || null;
-    }
-  }
-
-  // Match block scalar (folded or literal): field: >-\n  line1\n  line2
-  const blockScalar = new RegExp(`(?:^|\\n)${field}:\\s*[>|]-?\\n((?:  [^\\n]*\\n?)+)`, "m");
-  const bs = blockScalar.exec(block);
-  if (bs) {
-    return bs[1]
-      .split("\n")
-      .map((l) => l.replace(/^  /, "").trim())
-      .filter(Boolean)
-      .join(" ")
-      .trim() || null;
-  }
-
-  return null;
-}
-
-// ---------------------------------------------------------------------------
-// Keyword extraction from a SKILL.md description
-// ---------------------------------------------------------------------------
-
-/**
- * Extract explicit trigger keywords from a skill description.
- * Looks for quoted phrases after "Triggers on" (e.g. Triggers on "foo", "bar").
- *
- * @param {string} description
- * @returns {string[]}
- */
-function extractExplicitTriggers(description) {
-  const triggerSection = /[Tt]riggers?\s+on\s+(.*)/;
-  const m = triggerSection.exec(description);
-  if (!m) return [];
-  const section = m[1];
-  // Extract all double-quoted tokens from the trigger section.
-  const quoted = [];
-  const re = /"([^"]+)"/g;
-  let hit;
-  while ((hit = re.exec(section)) !== null) {
-    const phrase = hit[1].trim().toLowerCase();
-    if (phrase && !isStopWord(phrase)) quoted.push(phrase);
-  }
-  return quoted;
-}
-
-/**
- * Derive the full keyword set for a single skill.
- * Only explicit `Triggers on "..."` phrases and the skill name are used.
- * Do not mine arbitrary words from descriptions; that makes everyday prompts
- * like "change this contract" trigger unrelated skill hints.
- *
- * @param {string} skillName
- * @param {string|null} description
- * @returns {string[]}
- */
-function deriveKeywords(skillName, description) {
-  const seen = new Set();
-  const push = (kw) => {
-    const k = kw.toLowerCase().trim();
-    if (k && !seen.has(k) && !isStopWord(k)) { seen.add(k); }
-  };
-
-  // Always include the skill name itself (unless it is a stop-word).
-  if (skillName) push(skillName);
-
-  if (description) {
-    // Explicit triggers have highest priority.
-    for (const t of extractExplicitTriggers(description)) push(t);
-  }
-
-  return [...seen];
-}
-
-// ---------------------------------------------------------------------------
-// Directory helpers
-// ---------------------------------------------------------------------------
-
-function isDir(p) {
-  try { return statSync(p).isDirectory(); } catch { return false; }
-}
-
-// ---------------------------------------------------------------------------
-// buildSkillCatalog
-// ---------------------------------------------------------------------------
-
-/**
- * Discover all plugin bundles under extensionsDir, read each bundle's
- * skills/<name>/SKILL.md, and build a catalog of { skill, plugin, keywords, invoke }.
- *
- * - Skips bundles without a .agents/plugin.json.
- * - Skips skill dirs without a SKILL.md.
- * - Skips malformed manifests / SKILL.md files without throwing.
- * - Invocation form: "$<skill>" (the canonical invocation for all surfaces).
- *
- * @param {string} extensionsDir  Absolute path to the extensions/ directory.
- * @returns {CatalogEntry[]}
- */
-export function buildSkillCatalog(extensionsDir) {
-  const dir = resolve(extensionsDir);
-  if (!existsSync(dir)) return [];
-
-  let bundleNames;
-  try {
-    bundleNames = readdirSync(dir);
-  } catch {
-    return [];
-  }
-
-  const catalog = [];
-
-  for (const bundleName of bundleNames) {
-    const bundleDir = join(dir, bundleName);
-    if (!isDir(bundleDir)) continue;
-
-    const manifestPath = join(bundleDir, ".agents", "plugin.json");
-    if (!existsSync(manifestPath)) continue;
-
-    let manifest;
-    try {
-      manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
-    } catch {
-      // malformed manifest — skip silently
-      continue;
-    }
-
-    const pluginName = (typeof manifest.name === "string" ? manifest.name : null) ?? bundleName;
-
-    const skillsDir = join(bundleDir, "skills");
-    if (!isDir(skillsDir)) continue;
-
-    let skillNames;
-    try {
-      skillNames = readdirSync(skillsDir);
-    } catch {
-      continue;
-    }
-
-    for (const skillName of skillNames) {
-      const skillDir = join(skillsDir, skillName);
-      if (!isDir(skillDir)) continue;
-
-      const skillMdPath = join(skillDir, "SKILL.md");
-      if (!existsSync(skillMdPath)) continue;
-
-      let skillText;
-      try {
-        skillText = readFileSync(skillMdPath, "utf8");
-      } catch {
-        continue;
-      }
-
-      const fmBlock = extractFrontmatterBlock(skillText);
-
-      // `name` from frontmatter (fall back to directory name).
-      const fmName = fmBlock ? parseFrontmatterField(fmBlock, "name") : null;
-      const resolvedName = fmName ?? skillName;
-
-      // `description` from frontmatter — both "description" and "desc" keys.
-      let description = null;
-      if (fmBlock) {
-        description = parseFrontmatterField(fmBlock, "description") ?? parseFrontmatterField(fmBlock, "desc");
-      }
-
-      const keywords = deriveKeywords(resolvedName, description ?? "");
-      const invoke = `$${resolvedName}`;
-
-      catalog.push({ skill: resolvedName, plugin: pluginName, keywords, invoke });
-    }
-  }
-
-  return catalog;
-}
-
-// ---------------------------------------------------------------------------
-// routePrompt
-// ---------------------------------------------------------------------------
-
-/**
- * Route a user prompt against the skill catalog.
- *
- * Matching strategy:
- *   1. Explicit mention — `/skill-name` or `$skill-name` in the prompt (strong).
- *   2. Keyword match — any non-stop-word keyword appears as a word-boundary token.
- *
- * Returns all matched skills (de-duplicated by skill name).
- * No match → additionalContext: null (passthrough).
- *
- * @param {string|null|undefined} prompt
- * @param {CatalogEntry[]} catalog
- * @returns {RouteResult}
- */
-export function routePrompt(prompt, catalog) {
-  if (!prompt || typeof prompt !== "string") {
-    return { matches: [], additionalContext: null };
-  }
-
-  const promptLower = prompt.toLowerCase();
-
-  // Normalise catalog: skip bogus entries.
-  const validCatalog = (Array.isArray(catalog) ? catalog : []).filter(
-    (e) => e && typeof e.skill === "string" && Array.isArray(e.keywords),
-  );
-
-  const matchMap = new Map(); // skill → RouteMatch
-
-  for (const entry of validCatalog) {
-    if (matchMap.has(entry.skill)) continue; // already matched
-
-    const { skill, plugin, keywords, invoke } = entry;
-
-    // 1. Explicit /skill or $skill mention.
-    const explicitPatterns = [`/${skill.toLowerCase()}`, `$${skill.toLowerCase()}`];
-    for (const pat of explicitPatterns) {
-      if (promptLower.includes(pat)) {
-        matchMap.set(skill, {
-          skill,
-          plugin,
-          invoke: invoke ?? `$${skill}`,
-          reason: `explicit mention of "${pat}"`,
-        });
-        break;
-      }
-    }
-    if (matchMap.has(skill)) continue;
-
-    // 2. Keyword word-boundary match.
-    for (const kw of keywords) {
-      if (!kw || isStopWord(kw)) continue;
-      // Word-boundary check: kw must appear as a whole token (not substring of another word).
-      // Use a simple regex with \b-equivalent: check that surrounding chars are non-word.
-      const kwLower = kw.toLowerCase();
-      // Build a word-boundary regex. Escape regex metacharacters in kw.
-      const escaped = kwLower.replace(/[-[\]{}()*+?.,\\^$|#\s]/g, "\\$&");
-      const re = new RegExp(`(?<![a-z0-9_-])${escaped}(?![a-z0-9_-])`, "i");
-      if (re.test(promptLower)) {
-        matchMap.set(skill, {
-          skill,
-          plugin,
-          invoke: invoke ?? `$${skill}`,
-          reason: `keyword match on "${kw}"`,
-        });
-        break;
-      }
-    }
-  }
-
-  const matches = [...matchMap.values()];
-
-  if (matches.length === 0) {
-    return { matches: [], additionalContext: null };
-  }
-
-  const additionalContext = buildAdditionalContext(matches);
-  return { matches, additionalContext };
-}
-
-// ---------------------------------------------------------------------------
-// additionalContext builder
-// ---------------------------------------------------------------------------
-
-/**
- * Build a human-readable additionalContext string that points the agent at
- * the matching skills and how to invoke them.
- *
- * @param {RouteMatch[]} matches
- * @returns {string}
- */
-function buildAdditionalContext(matches) {
-  const lines = [
-    "<!-- enact-extensions: UserPromptSubmit keyword-router -->",
-    `The following skill${matches.length === 1 ? "" : "s"} appear${matches.length === 1 ? "s" : ""} relevant to the user's prompt:`,
-    "",
-  ];
-
-  for (const m of matches) {
-    lines.push(`- **${m.skill}** (plugin: ${m.plugin})`);
-    lines.push(`  Invoke with: \`${m.invoke}\``);
-    lines.push(`  Matched because: ${m.reason}`);
-    lines.push("");
-  }
-
-  lines.push(
-    "If the user's intent aligns with one of these skills, invoke it using the form shown above.",
-    "If unsure, proceed with the default behaviour and ignore this hint.",
-  );
-
-  return lines.join("\n");
-}

package/scripts/postinstall.mjs

@@ -1,101 +0,0 @@
-#!/usr/bin/env node
-/**
- * postinstall.mjs — TTY-aware npm postinstall script for enact-extensions.
- *
- * CI-SAFETY CONTRACT (most important property):
- *   - If NOT a TTY → print one-line notice and exit 0. NEVER hang.
- *   - If CI env var is set → print one-line notice and exit 0.
- *   - If ENACT_EXTENSIONS_NO_POSTINSTALL is set → print one-line notice and exit 0.
- *   - If interactive TTY (and not CI) → install `enact-core` across host surfaces.
- *   - Entire script is wrapped in try/catch → ALWAYS process.exit(0).
- *     A postinstall that throws would break `npm ci` in CI.
- *
- * The CI/TTY guards ensure this script is fully safe in:
- *   - Docker CI environments (CI=1, no TTY)
- *   - npm ci / npm install in CI pipelines
- *   - Automated install tooling (pipes, scripts)
- *   - Developer machines with interactive TTY (triggers enact-core install)
- */
-
-try {
-  const { stdin, env } = process;
-
-  const isCI = !!(env.CI || env.CONTINUOUS_INTEGRATION || env.BUILD_ID || env.GITHUB_ACTIONS);
-  const isNoPostinstall = !!(env.ENACT_EXTENSIONS_NO_POSTINSTALL);
-  const isTTY = !!(stdin.isTTY);
-
-  const NOTICE = `Run \`enact-extensions install enact-core --platform all\` to enable session-start drift checks.\n`;
-
-  if (!isTTY || isCI || isNoPostinstall) {
-    // Non-interactive or CI: print notice and exit immediately.
-    process.stdout.write(NOTICE);
-    process.exit(0);
-  }
-
-  // Interactive TTY (non-CI): install enact-core, which now owns SessionStart.
-  // We spawn a child process rather than importing directly to keep postinstall
-  // isolated from any import-time side-effects in the CLI modules.
-  const { spawnSync } = await import("node:child_process");
-  const { dirname, join, resolve } = await import("node:path");
-  const { fileURLToPath } = await import("node:url");
-
-  const __dirname = dirname(fileURLToPath(import.meta.url));
-  const CLI = join(resolve(__dirname, ".."), "scripts", "enact-extensions.mjs");
-
-  // Spawn with stdio inherited so the interactive readline prompt is visible.
-  // We spawn and ignore the exit code — postinstall must always exit 0.
-  spawnSync(process.execPath, [CLI, "install", "enact-core", "--platform", "all"], {
-    stdio: "inherit",
-    env: { ...process.env },
-  });
-
-  // Offer a drift refresh if any installed plugins are outdated.
-  const { offerDriftRefresh } = await import("./lib/postinstall-offer.mjs");
-  const { computeOutdated } = await import("./lib/outdated.mjs");
-  const { runUpdate } = await import("./lib/run-update.mjs");
-  const { createInterface } = await import("node:readline");
-
-  /**
-   * promptYesNo — asks a yes/no question on stdin/stdout.
-   * Default is YES: empty input / "y" / "yes" (case-insensitive) → true.
-   * EOF (Ctrl-D) resolves as false (decline) via the 'close' event so the
-   * script can never hang waiting for a promise that will never settle.
-   * @param {string} question
-   * @returns {Promise<boolean>}
-   */
-  function promptYesNo(question) {
-    const rl = createInterface({ input: process.stdin, output: process.stdout });
-    return new Promise((resolve) => {
-      // EOF / Ctrl-D fires 'close' before the question callback — treat as decline.
-      rl.once("close", () => resolve(false));
-      rl.question(question, (answer) => {
-        rl.close();
-        const t = (answer ?? "").trim().toLowerCase();
-        resolve(t === "" || t === "y" || t === "yes");
-      });
-    });
-  }
-
-  await offerDriftRefresh({
-    isTTY: true,
-    // User opt-in: ENACT_EXTENSIONS_AUTO_UPDATE=1 applies drift refreshes without prompting.
-    autoYes: !!env.ENACT_EXTENSIONS_AUTO_UPDATE,
-    computeOutdatedFn: () => computeOutdated(),
-    runUpdateFn: (opts) => runUpdate(opts),
-    write: (s) => process.stdout.write(s),
-    promptYesNo,
-  });
-
-  process.exit(0);
-} catch {
-  // CRITICAL: never let an error propagate from postinstall.
-  // Printing to stderr is best-effort (safe to fail).
-  try {
-    process.stderr.write(
-      "[enact-extensions postinstall] Non-fatal error during enact-core install. Run `enact-extensions install enact-core --platform all` manually.\n",
-    );
-  } catch {
-    // Even stderr.write failed — just exit 0.
-  }
-  process.exit(0);
-}

package/scripts/setup-enact-context.sh

@@ -1,28 +0,0 @@
-#!/usr/bin/env bash
-# Install enact-context through the enact-extensions plugin system.
-#
-# This intentionally does NOT run `enact-context setup` or `doctor --fix`.
-# Those commands write direct host artifacts such as ~/.codex/AGENTS.md,
-# ~/.codex/hooks.json, and ~/.codex/skills/enact-context, bypassing plugin
-# enable/disable and uninstall semantics.
-set -euo pipefail
-
-ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
-
-cd "$ROOT"
-npm run build
-node scripts/enact-extensions.mjs validate extensions/enact-context
-
-echo ""
-echo "Installing enact-context via enact-extensions plugin registration..."
-if [[ " $* " == *" --platform "* ]]; then
-  node scripts/enact-extensions.mjs install enact-context "$@"
-else
-  node scripts/enact-extensions.mjs install enact-context --platform "${ENACT_CONTEXT_PLATFORM:-codex}" "$@"
-fi
-
-if ! command -v enact-context >/dev/null 2>&1; then
-  echo ""
-  echo "Note: enact-context runtime binary is not on PATH."
-  echo "Install the runtime separately; do not use 'enact-context setup' for Codex registration."
-fi