enact-extensions

Multi-surface plugin manifest tooling for Enact: schemas, validation, sync, and the plugin-dev toolkit for ENACT-native bundles plus derived Claude Code, Codex, and Cursor projections.

• Repository: https://dev.azure.com/amsterdamdatalabs/Enact/_git/enact-extensions
• Package: @amsterdamdatalabs/enact-extensions
• CLI: enact-extensions

What this repo is

This package owns the manifest tooling and a set of self-contained plugin bundles under extensions/:

• spec/ — JSON schemas (enact.json canonical; per-host schemas for claude/codex/cursor)
• src/ — TypeScript library for manifest derivation (create/), validation (validate/), and repo-local projection (projection.ts)
• scripts/ — CLI: enact-extensions (validate | sync | list | index | install --repo | uninstall --repo | doctor enact-repo --repo)
• extensions/<plugin>/ — one bundle per plugin (e.g. plugin-dev, enact-core, enact-factory, net-revenue-management), each with a canonical .agents/plugin.json

Scope: repo-local agent setup only. enact-extensions install <bundle> --repo <path> projects host files from .agents/plugin.json into a git repository as committed, relative files. This package never installs into host global homes (~/.claude, ~/.codex, ~/.cursor, ~/.kimi-code, ~/.enact), keeps no global install ledger, and never rewrites global agent files (CLAUDE.md / AGENTS.md); everything global belongs to enact-vps, whose global surface sweep also removes legacy global installs made by older versions of this CLI. There is no npm postinstall.

Surface contract

Each extensions/<plugin>/.agents/plugin.json is the canonical source. sync derives the generated plugin-root projections (.claude-plugin/, .codex-plugin/, .cursor-plugin/, and .kimi-plugin/) in the bundle source for the explicit global plugin path owned by enact-vps. Repo-local install --repo does not derive, register, or write any plugin root or marketplace; it writes only the native project files below.

Author skills so they are valid on all projected surfaces by default. Use surface-neutral workflow language, treat .agents/plugin.json as the source of truth, and isolate host-specific details only when required.

Install / build

git clone https://[email protected]/amsterdamdatalabs/Enact/_git/enact-extensions
cd enact-extensions
npm install
npm run build

Tests

npm test

This runs the full validation suite: principle checks, hook checks, TypeScript build, skill standard validation, and the Node test suite.

Usage

Validate, sync, or list bundles:

npm run build

node scripts/enact-extensions.mjs validate extensions/net-revenue-management
node scripts/enact-extensions.mjs sync extensions/plugin-dev

node scripts/enact-extensions.mjs list

install / uninstall / doctor accept any bundle resolvable by bare name or explicit plugin path, and only in repo-local --repo <path> form. bundled-extensions.json names the default bundle set; it is not an install or doctor allow-list. An unknown or unresolvable bundle fails clearly before anything is touched.

Repo-local install (--repo)

Install a bundle into a git repository as committed, relative files, following each host's documented project-scope standard. Nothing is written under $HOME, and no absolute path is written into any file. (This replaces the removed --local fake-home scope.)

enact-extensions install enact-repo --repo <path> [--host claude,codex,cursor,kimi,opencode] [--force]
enact-extensions install enact-repo --repo <path> --dry-run    # preview; writes nothing
enact-extensions uninstall enact-repo --repo <path> [--purge]
enact-extensions uninstall enact-repo --repo <path> --dry-run [--purge]   # preview; writes nothing
enact-extensions doctor enact-repo --repo <path> [--json]      # read-only health check

<path> must be the git repository root (not a subdirectory, not $HOME) and must already contain a regular, non-symlink root enact-config.toml. Install is reconciliation, never enrollment: an unmarked repository is refused before any file is read or written. --host defaults to every repo host the bundle targets.

--dry-run prints exactly what would be deleted or rebuilt — one line per file, naming the action and reason — and exits with the same success/failure a real run would, without touching the filesystem. install --force is an explicit, announced request for the same authoritative repair performed by a normal install; it never enables a merge, preservation, or restore path.

doctor enact-repo --repo <path> is read-only. It reports the installed and current bundle versions, lock integrity and drift, and each host's lock-owned native paths. It also reports Codex and Kimi trust notes, Cursor MCP approval, Kimi's global-hook status, required global binaries, the root enact-config.toml marker and whether its [extensions] roster is present, an optional enact-hook doctor --repo result, and the per-repo hook logs. A pre-existing regular marker without [extensions] is valid for doctor; install adds this extension's roster declaration. Doctor never writes; it exits non-zero only for a hard requirement such as a missing install, lock-integrity failure, missing required binary, or missing/invalid root marker.

| Host | Canonical files rebuilt in the repo | | --- | --- | | Claude Code | .claude/agents/*.md, .claude/skills/<skill>/, root .mcp.json, and .claude/settings.json. Trust the folder before loading the project configuration. | | Codex | .codex/agents/*.toml, .agents/skills/<skill>/, .codex/config.toml MCP tables, and .codex/hooks.json. Trust the exact project path and review hooks with /hooks. | | Cursor | .cursor/agents/*.md, .cursor/skills/<skill>/, .cursor/mcp.json, and .cursor/hooks.json. | | Kimi Code | .kimi-code/agents/*.md, .kimi-code/skills/<skill>/, and .kimi-code/mcp.json. Kimi hooks remain global-only and are installed by enact-vps, never by this repo-local command. | | OpenCode | .opencode/agents/*.md, .opencode/skills/<skill>/, and root opencode.json. The repo-local installer also removes the retired .opencode/plugins root. |

Skills are installed at each host's native project discovery path: .agents/skills/ for Codex and .claude/skills/, .cursor/skills/, .kimi-code/skills/, or .opencode/skills/ for the other hosts. These paths are components of authoritative roots, so stale, foreign, or drifted entries are deleted and regenerated from the bundle on every reconciliation.

lean-ctx config: regardless of --host, the bundle's baseline lean-ctx/config.toml and lean-ctx/layout.toml are installed as canonical whole files at .agents/lean-ctx/config/lean-ctx/ — every host's .mcp.json/hooks equivalent runs enact-hook lean-ctx ..., which resolves its config from this repo-local path. Drift is repaired by replacing the owned file; uninstall does not restore prior content.

Install text-surgeries only the pre-existing root enact-config.toml's [extensions] scope and the bare [extensions.<name>] declaration for the installed bundle. The shared file's tables have one owner: version/[hooks]/[rules]/[repo] are enact-hook, [extensions] is enact-extensions, and [controls] is enact-repo-controls. The installer edits only its own block, removes the legacy marker-only [skills] block, and never writes [hooks]. It also manages the baseline lean-ctx config, .agents/.gitignore runtime entries, and .agents/enact-repo.lock.json. Commit all of it except what .gitignore excludes.

The lock records every canonical managed file (sha256), the owned roots, and the plugin version, all as relative paths. Its reconciliation contract is:

• Re-runs are idempotent. An unchanged bundle produces byte-identical owned files.
• Roots are rebuilt, never merged. .agents, .claude, .codex, .cursor, .kimi-code, and .opencode are Enact-owned roots. Reconciliation deletes their contents and writes only the canonical projection; it also deletes retired .claude-plugin, .codex-plugin, .cursor-plugin, .kimi-plugin, and .opencode/plugins roots.
• Runtime boundaries are explicit. .agents/hooks/ and .agents/lean-ctx/{data,cache,state,bin}/ remain outside Enact ownership; their writers retain them through install and both uninstall modes.
• Uninstall removes the authoritative deployment. It removes Enact-owned native roots and the extension declaration, without restoring foreign or prior files. enact-config.toml remains a pre-existing central marker; --purge additionally cuts an [extensions] block this installer appended, using text-level surgery only.

Install the CLI itself globally (the CLI binary only — no plugins, no host config):

bash dev-install-and-run.sh        # npm install, build, npm pack + npm install -g, verify
enact-extensions doctor enact-repo --repo <path>

The published package ships bundled-extensions.json, dist/, spec/, the CLI scripts, and extensions/enact-repo only (tests/package-contents.test.mjs pins this and installs the packed tarball into a temp prefix).

Layout

enact-extensions/
├── src/ spec/ scripts/   # manifest library + CLI
├── generated/            # gitignored discovery artifacts
└── extensions/           # self-contained plugin bundles

enact-os integration

enact-os submodules this repo at enact-extensions/ for manifest tooling and separately submodules product packages at top level. This package is repo-local agent setup only (enact-repo — see bundled-extensions.json); anything global belongs to enact-vps. Repo-local commands such as enact-factory setup manage runtime state.