@amsterdamdatalabs/enact-extensions 0.1.0 → 0.1.3

package/extensions/enact-context/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "enact-context": {
+      "command": "enact-context",
+      "args": ["mcp", "."]
+    }
+  }
+}

package/extensions/enact-context/README.md

@@ -0,0 +1,25 @@
+# enact-context plugin
+
+Canonical ENACT-native plugin bundle for `enact-context`.
+
+This bundle is the single source of truth under `extensions/enact-context/.agents/plugin.json`.
+`enact-extensions sync`/`install` derives `.claude-plugin`, `.codex-plugin`, and `.cursor-plugin`
+from this file for deployment.
+
+## Scope
+
+- Targets: `claude`, `codex`, `cursor` only.
+- No other host-specific first-class manifest is included (no Kiro, no extra platform surfaces).
+
+## Files
+
+- `.agents/plugin.json` — canonical manifest for validation, sync, and install
+- `.mcp.json` — MCP server entry (`enact-context` command)
+- `skills/` — shared `enact-context` skill for Codex/Claude/Cursor
+- `assets/` — plugin icon and logo assets
+- `skills/enact-context/scripts/install.sh` — optional install helper from the SKILL docs
+
+## Canonical Install Path
+
+The canonical install entrypoint is `extensions/enact-context/.agents/plugin.json`.
+Host surfaces are generated by tooling and kept derived from that canonical source.

package/extensions/enact-context/hooks/hooks.json

@@ -0,0 +1,115 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume|clear",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "enact-context hook session-start",
+            "statusMessage": "Loading enact-context workspace memory",
+            "timeout": 15
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "enact-context hook observe"
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "enact-context hook pre-tool-use",
+            "statusMessage": "enact-context shell policy"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "enact-context hook observe"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "enact-context hook observe"
+          }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "enact-context hook session-end"
+          }
+        ]
+      },
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "enact-context hook observe"
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "enact-context hook session-end"
+          }
+        ]
+      },
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "enact-context hook observe"
+          }
+        ]
+      }
+    ],
+    "SubagentStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "enact-context hook subagent-start"
+          }
+        ]
+      }
+    ],
+    "SubagentStop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "enact-context hook subagent-stop"
+          }
+        ]
+      }
+    ]
+  }
+}

package/extensions/enact-context/skills/enact-context/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: enact-context
+description: Context Runtime for AI Agents — 63 MCP tools, 10 read modes, 90+ shell patterns, tree-sitter AST for 18 languages. Compresses LLM context by up to 99%. Use when reading files, running shell commands, searching code, or exploring directories. Auto-installs if not present.
+---
+
+# Enact Context — Context Runtime for AI Agents
+
+Enact Context optimizes LLM context through 63 MCP tools, 90+ shell compression patterns, and tree-sitter AST parsing for 18 languages. It provides adaptive file reading, cross-session memory (CCP), task-conditioned relevance scoring, and a feedback loop for learning optimal compression.
+
+## Setup (run first)
+
+Before using enact-context, verify it is installed:
+
+```bash
+which enact-context || bash scripts/install.sh
+```
+
+If the install script is not available locally, install manually:
+
+```bash
+curl -fsSL https://amsterdamdatalabs.com/install.sh | sh
+```
+
+After installation, configure the MCP server:
+
+```bash
+enact-context init --global
+enact-context doctor --fix
+```
+
+## When to use enact-context
+
+Always prefer `enact-context -c <command>` over running commands directly when:
+- The command produces verbose output (build logs, git diffs, dependency trees, test results)
+- You are reading files and only need the structure or API surface
+- You want to check token savings for the current session
+
+## Shell commands (use instead of raw exec)
+
+```bash
+enact-context -c git status          # Compressed git output
+enact-context -c git diff            # Only meaningful diff lines
+enact-context -c git log --oneline -10
+enact-context -c npm install         # Strips progress bars, noise
+enact-context -c cargo build
+enact-context -c cargo test
+enact-context -c docker ps
+enact-context -c kubectl get pods
+enact-context -c aws ec2 describe-instances
+enact-context -c helm list
+enact-context -c prisma migrate dev
+enact-context -c curl -s <url>       # JSON schema extraction
+enact-context -c ls -la <dir>        # Grouped directory listing
+```
+
+Supported: git, npm, pnpm, yarn, bun, deno, cargo, docker, kubectl, helm, gh, pip, ruff, go, eslint, prettier, tsc, aws, psql, mysql, prisma, swift, zig, cmake, ansible, composer, mix, bazel, systemd, terraform, make, maven, dotnet, flutter, poetry, rubocop, playwright, curl, wget, and more.
+
+## File reading (compressed modes)
+
+```bash
+enact-context read <file>                    # Full content with structured header
+enact-context read <file> -m map             # Dependency graph + exports + API (~5-15% tokens)
+enact-context read <file> -m signatures      # Function/class signatures only (~10-20% tokens)
+enact-context read <file> -m aggressive      # Syntax-stripped (~30-50% tokens)
+enact-context read <file> -m entropy         # Shannon entropy filtered (~20-40% tokens)
+enact-context read <file> -m diff            # Only changed lines since last read
+```
+
+Use `map` mode when you need to understand what a file does without reading every line.
+Use `signatures` mode when you need the API surface of a module (tree-sitter for 18 languages).
+Use `full` mode only when you will edit the file.
+
+## AI Tool Integration
+
+```bash
+enact-context init --global          # Install shell aliases
+enact-context init --agent claude    # Claude Code PreToolUse hook
+enact-context init --agent cursor    # Cursor hooks.json
+enact-context init --agent gemini    # Gemini CLI BeforeTool hook
+enact-context init --agent codex     # Codex AGENTS.md
+enact-context init --agent windsurf  # .windsurfrules
+enact-context init --agent cline     # .clinerules
+enact-context init --agent crush     # Crush MCP config
+enact-context init --agent copilot   # VS Code / Copilot .vscode/mcp.json
+```
+
+## Multi-Agent & Knowledge
+
+MCP tools:
+- `ctx_knowledge(action="remember", category, key, value)` — persistent cross-session project knowledge store
+- `ctx_knowledge(action="recall", query)` — search stored facts by text or category
+- `ctx_knowledge(action="consolidate")` — extract session findings into permanent knowledge
+- `ctx_agent(action="register", agent_type, role)` — multi-agent context sharing with scratchpad messaging
+- `ctx_agent(action="post", message, tags)` — share findings/warnings between concurrent agents
+- `ctx_agent(action="read")` — read messages from other agents
+- `ctx_agent(action="handoff", to_agent, message)` — transfer task to another agent
+- `ctx_agent(action="sync")` — multi-agent sync status (active agents, pending messages, shared contexts)
+- `ctx_share(action="push", paths, to_agent, message)` — push cached file contexts to another agent
+- `ctx_share(action="pull")` — pull shared contexts from other agents
+- `ctx_share(action="list")` — list all shared contexts
+- `ctx_share(action="clear")` — remove contexts shared by this agent
+
+## Additional Intelligence Tools
+
+- `ctx_edit(path, old_string, new_string)` — search-and-replace file editing without native Read/Edit
+- `ctx_overview(task)` — task-relevant project map at session start
+- `ctx_preload(task)` — proactive context loader, caches task-relevant files
+- `ctx_semantic_search(query)` — BM25 code search by meaning across the project
+- `ctx_intent` now supports multi-intent detection and complexity classification
+- Semantic cache: TF-IDF + cosine similarity for finding similar files across reads
+
+## Session Continuity (CCP)
+
+```bash
+enact-context sessions list          # List all CCP sessions
+enact-context sessions show          # Show latest session state
+ enact-context gain --wrapped         # Weekly savings report card
+ enact-context gain --wrapped --period=month  # Monthly savings report card
+enact-context benchmark run          # Real project benchmark (terminal output)
+enact-context benchmark run --json   # Machine-readable JSON output
+enact-context benchmark report       # Shareable Markdown report
+```
+
+MCP tools for CCP:
+- `ctx_session status` — show current session state (~400 tokens)
+- `ctx_session load` — restore previous session (cross-chat memory)
+- `ctx_session task "description"` — set current task
+- `ctx_session finding "file:line — summary"` — record key finding
+- `ctx_session decision "summary"` — record architectural decision
+- `ctx_session save` — force persist session to disk
+- `ctx_gain(action="wrapped")` — generate savings report card in chat
+
+## Analytics
+
+```bash
+enact-context gain                   # Visual token savings dashboard
+enact-context dashboard              # Web dashboard at localhost:43205
+enact-context session                # Adoption statistics
+enact-context discover               # Find uncompressed commands in shell history
+```
+
+## Tips
+
+- The output suffix `[enact-context: 5029→197 tok, -96%]` shows original vs compressed token count
+- For large outputs, enact-context automatically truncates while preserving relevant context
+- JSON responses from curl/wget are reduced to schema outlines
+- Build errors are grouped by type with counts
+- Test results show only failures with summary counts
+- Cached re-reads cost only ~13 tokens

package/extensions/enact-context/skills/enact-context/scripts/install.sh

@@ -0,0 +1,69 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+INSTALL_DIR="${HOME}/.local/bin"
+
+already_installed() {
+    command -v enact-context >/dev/null 2>&1
+}
+
+detect_platform() {
+    local os arch
+    os="$(uname -s)"
+    arch="$(uname -m)"
+
+    case "$os" in
+        Darwin) os="apple-darwin" ;;
+        Linux)  os="unknown-linux-musl" ;;
+        *)      echo "ERROR: unsupported OS: $os" >&2; exit 1 ;;
+    esac
+
+    case "$arch" in
+        x86_64|amd64)   arch="x86_64" ;;
+        arm64|aarch64)  arch="aarch64" ;;
+        *)              echo "ERROR: unsupported arch: $arch" >&2; exit 1 ;;
+    esac
+
+    echo "${arch}-${os}"
+}
+
+install_binary() {
+    local platform="$1"
+    echo "Installing enact-context for ${platform} via the Amsterdam Data Labs installer..."
+    curl -fsSL "https://amsterdamdatalabs.com/install.sh" | sh
+}
+
+ensure_path() {
+    case ":${PATH}:" in
+        *":${INSTALL_DIR}:"*) ;;
+        *) export PATH="${INSTALL_DIR}:${PATH}"
+           echo "Added ${INSTALL_DIR} to PATH for this session."
+           echo "Add to your shell profile: export PATH=\"${INSTALL_DIR}:\$PATH\""
+           ;;
+    esac
+}
+
+setup_mcp() {
+    echo "Configuring enact-context MCP server..."
+    enact-context init --global 2>/dev/null || true
+    enact-context doctor --fix 2>/dev/null || true
+}
+
+main() {
+    if already_installed; then
+        local current
+        current="$(enact-context --version 2>/dev/null | head -1 || echo 'unknown')"
+        echo "enact-context already installed: ${current}"
+        echo "Run 'enact-context doctor' to verify configuration."
+        exit 0
+    fi
+
+    local platform
+    platform="$(detect_platform)"
+    install_binary "$platform"
+    ensure_path
+    setup_mcp
+    echo "enact-context installed and configured."
+}
+
+main "$@"

package/extensions/enact-factory/.agents/plugin.json

@@ -0,0 +1,42 @@
+{
+  "name": "enact-factory",
+  "version": "0.1.0",
+  "description": "Enact Factory governance plugin — MCP server registration and factory-facing workflow tools.",
+  "author": {
+    "name": "amsterdamdatalabs"
+  },
+  "homepage": "https://amsterdamdatalabs.com",
+  "repository": "https://dev.azure.com/amsterdamdatalabs/enact/_git/enact-os",
+  "license": "UNLICENSED",
+  "keywords": [
+    "enact-factory",
+    "governance",
+    "workitem",
+    "pipeline",
+    "mcp"
+  ],
+  "targets": [
+    "claude",
+    "codex",
+    "cursor"
+  ],
+  "mcpServers": "./.mcp.json",
+  "interface": {
+    "displayName": "Enact Factory",
+    "shortDescription": "Factory MCP server and governance skills for pipeline and WorkItem management.",
+    "longDescription": "Registers the enact-factory MCP server and exposes governance-facing workflow skills for pipeline orchestration and WorkItem tracking.",
+    "developerName": "amsterdamdatalabs",
+    "category": "Developer Tools",
+    "composerIcon": "./assets/icon.png",
+    "logo": "./assets/logo.png",
+    "capabilities": [
+      "mcp tools",
+      "workitem management",
+      "pipeline governance"
+    ]
+  },
+  "factory": {
+    "firstParty": true,
+    "operatorScope": "global"
+  }
+}

package/extensions/enact-factory/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "enact-factory": {
+      "command": "enact-factory",
+      "args": ["mcp", "."]
+    }
+  }
+}

package/extensions/enact-factory/hooks/user-prompt-submit.mjs

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+
+function readStdin() {
+  try {
+    return JSON.parse(readFileSync(0, "utf8") || "{}");
+  } catch {
+    return {};
+  }
+}
+
+function findWorkspaceRoot() {
+  let current = resolve(process.cwd());
+  while (true) {
+    if (existsSync(join(current, "config.toml"))) {
+      return current;
+    }
+    const parent = dirname(current);
+    if (parent === current) {
+      throw new Error(`Workspace config.toml not found while walking up from ${process.cwd()}`);
+    }
+    current = parent;
+  }
+}
+
+function expandPath(raw, sourceDir) {
+  const trimmed = raw.trim();
+  if (trimmed === "~") return process.env.HOME ?? trimmed;
+  if (trimmed.startsWith("~/")) return join(process.env.HOME ?? "", trimmed.slice(2));
+  if (isAbsolute(trimmed)) return trimmed;
+  return resolve(sourceDir, trimmed);
+}
+
+function readFactoryStorage(root) {
+  const configPath = join(root, "config.toml");
+  const raw = readFileSync(configPath, "utf8");
+  const match = raw.match(/^\[factory\][\s\S]*?^\s*storage\s*=\s*"([^"]+)"/m);
+  if (!match?.[1]) {
+    throw new Error(`Missing [factory].storage in ${configPath}`);
+  }
+  return expandPath(match[1], root);
+}
+
+function writeJson(path, data) {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(data, null, 2)}\n`, "utf8");
+}
+
+const payload = readStdin();
+const prompt = payload?.prompt ?? payload?.user_prompt ?? payload?.input ?? payload?.message ?? "";
+if (typeof prompt !== "string") {
+  process.exit(0);
+}
+
+const normalized = prompt.toLowerCase();
+if (!normalized.includes("$workitem-triage") && !normalized.includes("$enact-factory:workitem-triage")) {
+  process.exit(0);
+}
+
+const root = findWorkspaceRoot();
+const factoryStorage = readFactoryStorage(root);
+writeJson(join(factoryStorage, "state", "factory-active-skill.json"), {
+  activeSkill: "workitem-triage",
+  activatedAt: new Date().toISOString(),
+  activatedBy: "factory-hook-user-prompt-submit",
+});

package/extensions/enact-factory/skills/testing-strategy/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: testing-strategy
+description: >
+  Defines when and how to write tests in the enact-gateway codebase. Trigger
+  keywords: testing, write a test, TDD, bug fix, regression test, live test,
+  e2e, integration test, test harness, evidence, red-green, scenario, validate.
+---
+
+# testing-strategy
+
+## Purpose
+
+Enforce a consistent, lightweight approach across the three testing modes used
+in `enact-gateway`. The mode is determined by the behavior under test — not by
+preference. Pick once, follow the contract for that mode.
+
+---
+
+## Decision Rule
+
+| Situation | Mode |
+|-----------|------|
+| Pure function or isolated logic | Mode 0 — plain unit test |
+| Bug fix (any scope) | Mode 1 — TDD + `_evidence` |
+| Bug fix where behavior is runtime / live / cross-service (gateway → observe / iggy / questdb) | Mode 1 RED→GREEN + the regression test is a Mode-2 harness scenario |
+| New live-provider, cross-service, or e2e behavior | Mode 2 — harness scenario under `tests/integration/` or `tests/e2e/` |
+
+---
+
+## Mode 0 — Plain Unit Tests
+
+Use for: pure functions, simple transformations, isolated module logic.
+
+- File location: co-located with the source file, e.g. `src/foo/bar.spec.ts`.
+- Stack: Jest + ts-jest (resolved from `packages/backend`).
+- No harness ceremony. No fixtures directory. No `output/` directory.
+- Run: `npm run test --workspace=packages/backend` (or `npx jest <pattern>`).
+
+Do NOT force the harness onto plain unit tests. Co-located `.spec.ts` is
+sufficient and preferred.
+
+---
+
+## Mode 1 — Bug Fix: TDD with Captured `_evidence`
+
+### Contract
+
+1. **RED** — write a failing test that reproduces the bug before touching
+   implementation code. Capture the failure output:
+   ```
+   _evidence/<scenario>/red.txt
+   ```
+2. **Fix** — implement the minimal change that makes the test pass.
+3. **GREEN** — capture the passing output:
+   ```
+   _evidence/<scenario>/green.txt
+   ```
+
+`_evidence/` is **gitignored** — it is local proof, never committed source.
+
+### Regression test placement
+
+- If the bug is in pure/isolated logic, a co-located `.spec.ts` is sufficient.
+- If the bug involves runtime behavior — real provider calls, streaming,
+  cross-service interaction (gateway → observe / iggy / questdb) — the
+  regression test **must** be a Mode-2 harness scenario, not an ad-hoc script.
+
+### AzDO closure gate
+
+A bug work item in Azure DevOps (area `Enact\<leaf>`) must not be closed until:
+- A regression test exists (either `.spec.ts` or harness scenario).
+- `_evidence/<scenario>/red.txt` and `green.txt` are present locally.
+- The AzDO "Tests passing" Build boolean is green.
+
+---
+
+## Mode 2 — Live / Integration Test Harness
+
+### Directory layout
+
+```
+tests/
+  integration/<scenario>/      # harness scenarios (non-billable, require a live gateway)
+    fixtures/
+      input.json               # request body POSTed to the gateway
+    run.py (or run.ts)         # sends the request, writes output/<timestamp>.json
+    validate.py (or validate.ts) # reads latest output, prints PASS:/FAIL: per check
+    output/                    # gitignored; populated by run.py
+  e2e/                         # live, billable suites — OPT-IN only
+    <suite>.e2e-spec.ts        # Jest spec; skipped unless ENACT_LIVE_PROVIDER_TESTS=1
+    <scenario>/                # standalone scenario dirs (same run.py/validate.py shape)
+  lib/                         # shared harness helpers (import from here, do not duplicate)
+```
+
+> **Known issue:** `cli.py` currently globs `domains/*/*` but scenarios are
+> now laid out flat at `tests/integration/<scenario>/`. This mismatch is being
+> fixed; do not work around it by restructuring existing scenarios.
+
+### Scenario contract
+
+**`fixtures/input.json`** — the full JSON request body. Secrets are never
+stored here; only structure.
+
+**`run.py`** — self-contained runner:
+- Reads `ENACT_GATEWAY_BASE_URL` (default `http://127.0.0.1:43201`).
+- Reads `ENACT_GATEWAY_API_KEY` or `GATEWAY_API_KEY` for the bearer token.
+  If absent, writes `status: "skip"` and exits 0 — no tokens spent.
+- Reads `ENACT_GATEWAY_TIMEOUT_SECS` (default `30`).
+- POSTs `fixtures/input.json` to `<base_url>/v1/responses`.
+- Writes `output/<YYYYMMDDTHHmmss>.json` with one of:
+  - `{"status": "ok", "http_status": 200, "response_body": {...}, ...}`
+  - `{"status": "http_error", "http_status": <N>, "reason": "...", ...}`
+  - `{"status": "skip", "reason": "...", ...}`
+- Prints the output path and exits 0 (even for `http_error` — validate decides).
+
+**`validate.py`** — assertion layer:
+- Reads the latest file in `output/` (sort by name, take last).
+- If `status == "skip"`: prints `SKIP: <reason>` and exits 0.
+- If `status != "ok"`: prints `FAIL: ...` and exits 1.
+- For each behavioral check: prints `PASS: <label>` or `FAIL: <label>`.
+- Exits non-zero if any check failed.
+
+Secrets are **only ever passed by env-var name**, never committed to fixtures or
+source.
+
+### Task runner
+
+```bash
+# from tests/integration/
+uv run tasks list                              # list all discovered scenarios
+uv run tasks run <scenario>                    # run + validate
+uv run tasks run <scenario> --run-only         # skip validate
+uv run tasks run <scenario> --validate-only    # skip run (re-validate last output)
+uv run tasks run --all                         # run every scenario
+```
+
+### Live / billable suites (`tests/e2e/`)
+
+Live tests make **real, billable upstream calls**. They are OPT-IN and skipped
+in all normal / CI runs unless the flag is set explicitly:
+
+```bash
+# from packages/backend
+ENACT_LIVE_PROVIDER_TESTS=1 \
+LIVE_GATEWAY_URL=http://127.0.0.1:43201 \
+LIVE_KEY_ENACT_CODING=engw_... \
+LIVE_KEY_OPENCODE_GO=engw_... \
+LIVE_KEY_NANOGPT=engw_... \
+LIVE_KEY_OPENROUTER=engw_... \
+  npx jest --config ../../tests/e2e/jest-e2e.json --runInBand
+```
+
+Each `describe` block gates on its own key env-var, so individual profiles can
+be run in isolation by omitting the others.
+
+---
+
+## Output / Definition of Done
+
+A test is complete when:
+
+| Mode | Done when |
+|------|-----------|
+| Mode 0 | `npx jest <file>` exits 0; coverage covers the changed logic |
+| Mode 1 | `_evidence/<scenario>/red.txt` captured before fix; `green.txt` captured after; regression test in place |
+| Mode 2 — harness | `uv run tasks run <scenario>` exits 0 with all `PASS:` lines printed; or `SKIP:` when key absent (acceptable in CI) |
+| Mode 2 — live suite | Suite exits 0 under `ENACT_LIVE_PROVIDER_TESTS=1` with a live gateway; CI skips without the flag |