@ninemind/agentgem 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ninemind.ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,112 @@
+<p align="center">
+  <a href="https://agentgem.ninemind.ai"><img src="docs/banner.svg" alt="AgentGem — your agent works locally. Gem it." width="100%"></a>
+</p>
+
+<p align="center">
+  <a href="https://github.com/ninemindai/agentgem/actions/workflows/ci.yml"><img src="https://github.com/ninemindai/agentgem/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-9a3324" alt="MIT license"></a>
+  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-LTS-1f6b4f" alt="Node LTS"></a>
+  <a href="https://agentback.dev"><img src="https://img.shields.io/badge/built_on-AgentBack-b08436" alt="Built on AgentBack"></a>
+  <a href="docs/concepts.md"><img src="https://img.shields.io/badge/MCP-native-211c15" alt="MCP-native"></a>
+</p>
+
+> A local web UI that introspects your coding-agent config, redacts secrets at
+> capture, and builds a portable, composable **Gem**.
+>
+> **[agentgem.ninemind.ai](https://agentgem.ninemind.ai)**
+
+AgentGem reads your coding-agent config — skills, MCP servers, and `CLAUDE.md` —
+**redacts secrets the moment they're read**, and produces a **Gem**: a manifest + lock
+archive you can publish to a GitHub-backed registry, merge with other Gems, and deploy to
+several targets. A browser can't read `~/.claude` (it's sandboxed), so AgentGem runs a
+small server on your machine; secrets never leave your device — what crosses any boundary
+is a config *shape* with `<redacted>` in place of every sensitive value.
+
+Built on [AgentBack](https://www.npmjs.com/org/agentback), ninemind's AI-native API/MCP
+framework: every operation is defined once as a Zod contract and exposed as a REST
+endpoint, an MCP tool, and an OpenAPI 3.1 document — so the web page and your local agent
+call exactly the same thing.
+
+## What it provides
+
+- **Secret-safe capture** — redaction by value and by key name, before anything reaches a
+  REST response, an MCP result, the live preview, or the built Gem.
+- **A neutral Gem source** — a manifest + lock archive that isn't tied to any runtime.
+  Build once; install into a local testbed, merge, publish, or compile to a target without
+  re-reading raw config.
+- **Composition** — the manifest/lock split lets small, focused Gems be reconciled into
+  larger agents with a single re-resolved lock, not a pile of overlapping config.
+- **Deploy targets** — Eve and OpenAI Sandbox (code-gen), Flue (materialize, deployable to
+  Cloudflare), and Bedrock AgentCore (managed backend); code-gen targets share a common
+  `compose` step.
+- **A GitHub-backed registry** — publish, resolve, merge, and install composable Gems over
+  the same archive format.
+- **An agent-native path** — every operation is also an MCP tool, so your local agent can
+  build Gems over `/mcp` with no browser involved.
+
+## Usage
+
+Requires Node.js ≥ 22 and a coding-agent config at `~/.claude`.
+
+```bash
+npx @ninemind/agentgem              # run without installing
+# or install the `agentgem` command globally:
+npm install -g @ninemind/agentgem
+agentgem                            # → http://127.0.0.1:4317
+agentgem --port 8080                # override the port (also honors $PORT)
+```
+
+The server starts on `127.0.0.1` (default port `4317`) and prints:
+
+```
+agentgem listening at http://127.0.0.1:4317
+  UI:       http://127.0.0.1:4317/
+  API:      http://127.0.0.1:4317/api/inventory  ·  POST http://127.0.0.1:4317/api/gem
+  Explorer: http://127.0.0.1:4317/explorer/
+  MCP:      http://127.0.0.1:4317/mcp
+```
+
+| Path        | What it is                                              |
+| ----------- | ------------------------------------------------------- |
+| `/`         | The Gem Builder web UI                                  |
+| `/explorer` | Swagger UI for the REST API (from the OpenAPI document) |
+| `/mcp`      | The MCP endpoint — the same contract, for your agent    |
+
+Open `/`, tick the skills / MCP servers / `CLAUDE.md` you want, name the Gem, and watch
+the live `gem.json` render with secrets already shown as `<redacted>`. Download it — that
+archive is what every target and the registry consume.
+
+Append `?dir=/path/to/.claude` to introspect a config directory other than the
+default `~/.claude`.
+
+### From source
+
+To hack on AgentGem, clone the repo and use [pnpm](https://pnpm.io/) (AgentBack
+uses legacy decorators, so it builds with `tsc`, then runs `dist/`):
+
+```bash
+pnpm install
+pnpm dev        # build + start in one step (→ node dist/index.js)
+pnpm test       # tsc -b && vitest run — tests run against compiled dist/
+pnpm clean      # rm -rf dist *.tsbuildinfo (run before testing after renames/moves)
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the full workflow.
+
+## Layering
+
+Depends on AgentBack: `@agentback/core` (lifecycle), `@agentback/rest` +
+`@agentback/rest-explorer` (HTTP + Swagger UI), `@agentback/mcp` + `@agentback/mcp-http`
+(MCP over HTTP), and `@agentback/openapi` (the OpenAPI 3.1 document). The web UI, the REST
+API, and the MCP endpoint are three boundaries over one set of Zod contracts —
+`src/index.ts` wires them onto a single `RestApplication`.
+
+For deeper reference, see [`docs/`](docs/index.md):
+[getting started](docs/getting-started.md) ·
+[concepts](docs/concepts.md) ·
+[targets & deploy](docs/targets.md) ·
+[registry](docs/registry.md).
+
+## License
+
+[MIT](LICENSE) © ninemind.ai

package/dist/cli.js

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+// src/cli.ts — the `agentgem` command. A thin wrapper over run() in index.ts:
+// parses a couple of flags and starts the local server. Published as the `bin`
+// entry so `npx @ninemind/agentgem` and a global install both work.
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { run } from "./index.js";
+function version() {
+    try {
+        const here = dirname(fileURLToPath(import.meta.url));
+        return JSON.parse(readFileSync(join(here, "..", "package.json"), "utf8")).version ?? "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+}
+const HELP = `agentgem — build secret-safe, composable Gems from your coding-agent config
+
+Usage:
+  agentgem [options]
+
+Options:
+  -p, --port <n>   Port to listen on (default: 4317, or $PORT)
+  -v, --version    Print version and exit
+  -h, --help       Show this help
+
+Once running, open the printed URL (default http://127.0.0.1:4317/). Append
+?dir=/path/to/.claude to introspect a config directory other than ~/.claude.`;
+async function main(argv) {
+    const has = (...names) => names.some((n) => argv.includes(n));
+    const opt = (...names) => {
+        for (const n of names) {
+            const i = argv.indexOf(n);
+            if (i >= 0)
+                return argv[i + 1];
+        }
+        return undefined;
+    };
+    if (has("-h", "--help"))
+        return void console.log(HELP);
+    if (has("-v", "--version"))
+        return void console.log(version());
+    const portArg = opt("-p", "--port");
+    const port = Number(portArg ?? process.env.PORT ?? 4317);
+    if (!Number.isInteger(port) || port < 0 || port > 65535) {
+        console.error(`agentgem: invalid port "${portArg}"`);
+        process.exit(1);
+    }
+    await run(port);
+}
+main(process.argv.slice(2)).catch((err) => {
+    console.error(err);
+    process.exit(1);
+});

package/dist/gem/agentcorePublish.js

@@ -0,0 +1,91 @@
+import { buildAgentcoreHarness } from "./targets.js";
+// CreateHarness returns while the harness is still CREATING; these gate the poll-to-terminal loop.
+const POLL_INTERVAL_MS = 3000;
+const POLL_MAX_ATTEMPTS = 40;
+const isTerminalHarnessStatus = (s) => /ready|fail/i.test(s);
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+// CreateHarness harnessName pattern: [a-zA-Z][a-zA-Z0-9_]{0,39}
+export function harnessNameFor(gem) {
+    let n = (gem.name || "agent").replace(/[^a-zA-Z0-9_]/g, "");
+    if (!/^[a-zA-Z]/.test(n))
+        n = "a" + n;
+    return n.slice(0, 40) || "agent";
+}
+export function buildCreateHarnessRequest(gem, opts) {
+    const { harness, skipped } = buildAgentcoreHarness(gem); // systemPrompt + tools + (path) skills + model
+    const skills = gem.artifacts.filter((a) => a.type === "skill");
+    for (const s of skills)
+        skipped.push({ artifact: s.name, type: "skill", reason: "AgentCore publish needs a git/s3 skill source; local skill not carried by the gem" });
+    const request = {
+        harnessName: harnessNameFor(gem),
+        executionRoleArn: opts.executionRoleArn,
+        model: harness.model,
+    };
+    if (harness.systemPrompt)
+        request.systemPrompt = harness.systemPrompt;
+    if (harness.tools)
+        request.tools = harness.tools;
+    // NOTE: harness.skills (local path-skills) are intentionally NOT forwarded — publish can't upload files.
+    return { request, skipped, vaultSecrets: gem.requiredSecrets };
+}
+export function agentcorePublishReady() {
+    const hasId = !!(process.env.AWS_ACCESS_KEY_ID || process.env.AWS_PROFILE);
+    const hasRegion = !!(process.env.AWS_REGION || process.env.AWS_DEFAULT_REGION);
+    return hasId && hasRegion && !!process.env.AGENTCORE_EXECUTION_ROLE_ARN;
+}
+export function realAgentcoreControlClient() {
+    return {
+        async createHarness(req) {
+            // Lazy import so the SDK isn't loaded unless a real publish runs.
+            const { BedrockAgentCoreControlClient, CreateHarnessCommand } = await import("@aws-sdk/client-bedrock-agentcore-control");
+            const client = new BedrockAgentCoreControlClient({});
+            const out = await client.send(new CreateHarnessCommand(req));
+            const h = out.harness ?? {};
+            return {
+                arn: String(h.arn ?? ""), harnessId: String(h.harnessId ?? ""), harnessName: String(h.harnessName ?? ""),
+                harnessVersion: String(h.harnessVersion ?? ""), status: String(h.status ?? ""), failureReason: h.failureReason,
+            };
+        },
+        async getHarness(harnessId) {
+            const { BedrockAgentCoreControlClient, GetHarnessCommand } = await import("@aws-sdk/client-bedrock-agentcore-control");
+            const client = new BedrockAgentCoreControlClient({});
+            const out = await client.send(new GetHarnessCommand({ harnessId }));
+            const h = out.harness ?? {};
+            return { status: String(h.status ?? ""), harnessVersion: String(h.harnessVersion ?? ""), failureReason: h.failureReason };
+        },
+        async deleteHarness(harnessId) {
+            const { BedrockAgentCoreControlClient, DeleteHarnessCommand } = await import("@aws-sdk/client-bedrock-agentcore-control");
+            const c = new BedrockAgentCoreControlClient({});
+            await c.send(new DeleteHarnessCommand({ harnessId }));
+        },
+    };
+}
+export async function undeployAgentcoreHarness(rec, client) {
+    if (rec.harnessId)
+        await client.deleteHarness(rec.harnessId);
+}
+export function previewAgentcorePublish(gem) {
+    const roleArn = process.env.AGENTCORE_EXECUTION_ROLE_ARN || "arn:aws:iam::ACCOUNT:role/REPLACE_WITH_HARNESS_ROLE";
+    const { request, skipped, vaultSecrets } = buildCreateHarnessRequest(gem, { executionRoleArn: roleArn });
+    return { kind: "agentcore-harness", request, skipped, vaultSecrets };
+}
+export async function deployAgentcorePublish(gem, _requestId, client = realAgentcoreControlClient()) {
+    const roleArn = process.env.AGENTCORE_EXECUTION_ROLE_ARN;
+    if (!roleArn)
+        throw new Error("AGENTCORE_EXECUTION_ROLE_ARN is not set — cannot create an AgentCore harness (execution role required).");
+    const { request, skipped, vaultSecrets } = buildCreateHarnessRequest(gem, { executionRoleArn: roleArn });
+    const h = await client.createHarness(request);
+    // Poll GetHarness until the harness reaches a terminal state (READY or *FAILED*); CreateHarness
+    // returns while still CREATING. Polls immediately (no leading sleep) and stops on terminal/attempts.
+    let status = h.status;
+    let harnessVersion = h.harnessVersion;
+    for (let i = 0; i < POLL_MAX_ATTEMPTS && !isTerminalHarnessStatus(status); i++) {
+        const g = await client.getHarness(h.harnessId);
+        status = g.status;
+        harnessVersion = g.harnessVersion || harnessVersion;
+        if (isTerminalHarnessStatus(status))
+            break;
+        await sleep(POLL_INTERVAL_MS);
+    }
+    return { kind: "agentcore-harness", harnessArn: h.arn, harnessId: h.harnessId, harnessName: h.harnessName, harnessVersion, status, skipped, vaultSecrets };
+}

package/dist/gem/agentcoreRun.js

@@ -0,0 +1,85 @@
+// src/gem/agentcoreRun.ts
+// Deploy a workspace's rendered AgentCore project via the `agentcore` CLI. Peer of run.ts;
+// reuses its ProcessRunner injection so command/state logic is unit-testable without a real CLI/AWS.
+import { existsSync, mkdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { workspaceDir } from "./workspaces.js";
+import { readGemArchive } from "./archive.js";
+import { readArchiveDir, writeArchiveDir } from "./archiveFs.js";
+import { materialize } from "./targets.js";
+import { pushLog, runToEnd, realRunner } from "./run.js";
+// Resolve the agentcore CLI: an explicit AGENTCORE_BIN, else the first `agentcore` on PATH.
+export function resolveAgentcoreBin() {
+    const explicit = process.env.AGENTCORE_BIN;
+    if (explicit && existsSync(explicit))
+        return explicit;
+    for (const dir of (process.env.PATH ?? "").split(":")) {
+        if (!dir)
+            continue;
+        const p = join(dir, "agentcore");
+        if (existsSync(p))
+            return p;
+    }
+    return null;
+}
+export function agentcoreReadiness() {
+    const hasId = !!(process.env.AWS_ACCESS_KEY_ID || process.env.AWS_PROFILE);
+    const hasRegion = !!(process.env.AWS_REGION || process.env.AWS_DEFAULT_REGION);
+    return { cli: !!resolveAgentcoreBin(), awsCreds: hasId && hasRegion };
+}
+// `agentcore deploy` prints the created harness ARN (and/or a console URL). Prefer the ARN.
+export function parseAgentcoreEndpoint(lines) {
+    for (const l of lines) {
+        const arn = l.match(/arn:aws:bedrock-agentcore:[^\s"']+harness[^\s"']*/);
+        if (arn)
+            return arn[0];
+    }
+    for (const l of lines) {
+        const u = l.match(/https?:\/\/[^\s"']+/);
+        if (u)
+            return u[0];
+    }
+    return undefined;
+}
+// Re-render the workspace's gem to the agentcore target into a stable .run/agentcore dir.
+export async function ensureAgentcoreProject(name, _runner, _log) {
+    const dir = workspaceDir(name);
+    if (!existsSync(join(dir, "gem.json")))
+        throw new Error(`no workspace '${name}'`);
+    const gem = readGemArchive(readArchiveDir(dir));
+    const { files } = materialize(gem, "agentcore");
+    const runDir = join(dir, ".run", "agentcore");
+    rmSync(runDir, { recursive: true, force: true }); // drop stale renders
+    mkdirSync(runDir, { recursive: true });
+    writeArchiveDir(runDir, files);
+    return runDir;
+}
+const registry = new Map();
+export async function deployAgentcore(name, runner = realRunner) {
+    const bin = resolveAgentcoreBin();
+    if (!bin)
+        throw new Error("agentcore CLI not found — install `@aws/agentcore@preview` or set AGENTCORE_BIN.");
+    if (!agentcoreReadiness().awsCreds)
+        throw new Error("AWS credentials/region not configured (set AWS_PROFILE or AWS_ACCESS_KEY_ID + AWS_REGION).");
+    const state = { state: "deploying", logTail: [] };
+    registry.set(name, state);
+    try {
+        const runDir = await ensureAgentcoreProject(name, runner, state.logTail);
+        const code = await runToEnd(runner, bin, ["deploy"], runDir, process.env, state.logTail);
+        if (code !== 0) {
+            state.state = "failed";
+            return state;
+        }
+        state.url = parseAgentcoreEndpoint(state.logTail);
+        state.state = "idle";
+        return state;
+    }
+    catch (err) {
+        state.state = "failed";
+        pushLog(state.logTail, err instanceof Error ? err.message : String(err));
+        return state;
+    }
+}
+export function getAgentcoreStatus(name) {
+    return registry.get(name) ?? { state: "idle", logTail: [] };
+}

package/dist/gem/archive.js

@@ -0,0 +1,185 @@
+import { createHash } from "node:crypto";
+import { safePathSegment } from "./targets.js";
+export const ARCHIVE_FORMAT_VERSION = 1;
+const MANIFEST_PATH = "gem.json";
+const LOCK_PATH = "gem.lock";
+function sha256(s) {
+    return "sha256:" + createHash("sha256").update(s, "utf8").digest("hex");
+}
+// Deterministic JSON: object keys sorted recursively, arrays keep order.
+function stableStringify(value) {
+    if (Array.isArray(value))
+        return "[" + value.map(stableStringify).join(",") + "]";
+    if (value && typeof value === "object") {
+        const keys = Object.keys(value).sort();
+        return "{" + keys.map((k) => JSON.stringify(k) + ":" + stableStringify(value[k])).join(",") + "}";
+    }
+    return JSON.stringify(value);
+}
+function fileHash(p, content) {
+    if (p === MANIFEST_PATH)
+        return sha256(stableStringify(JSON.parse(content)));
+    return sha256(content);
+}
+export function computeLock(files) {
+    const paths = Object.keys(files).filter((p) => p !== LOCK_PATH).sort();
+    const fileDigests = {};
+    const manifestCanonical = MANIFEST_PATH in files ? stableStringify(JSON.parse(files[MANIFEST_PATH])) : "";
+    for (const p of paths) {
+        fileDigests[p] = fileHash(p, files[p]);
+    }
+    const fileLines = paths.map((p) => `${p}:${fileDigests[p]}`).join("\n");
+    const gemDigest = sha256(manifestCanonical + "\n" + fileLines);
+    return { formatVersion: ARCHIVE_FORMAT_VERSION, files: fileDigests, gemDigest, signature: null };
+}
+export function verifyLock(files, lock) {
+    const present = Object.keys(files).filter((p) => p !== LOCK_PATH);
+    const mismatches = [];
+    for (const p of present)
+        if (p in lock.files && fileHash(p, files[p]) !== lock.files[p])
+            mismatches.push(p);
+    const missing = Object.keys(lock.files).filter((p) => !(p in files));
+    const extra = present.filter((p) => !(p in lock.files));
+    let ok = mismatches.length === 0 && missing.length === 0 && extra.length === 0;
+    if (ok && computeLock(files).gemDigest !== lock.gemDigest) {
+        mismatches.push("gemDigest");
+        ok = false;
+    }
+    return { ok, mismatches, missing, extra };
+}
+export function writeGemArchive(gem, opts = {}) {
+    const files = {};
+    const skipped = [];
+    const artifacts = [];
+    const withExt = (s, ext) => (s.endsWith(ext) ? s : s + ext);
+    const place = (path, content, name, type) => {
+        if (path in files) {
+            skipped.push({ artifact: name, type, reason: `path collision with an earlier ${type} at ${path}` });
+            return false;
+        }
+        files[path] = content;
+        return true;
+    };
+    for (const a of gem.artifacts) {
+        const seg = safePathSegment(a.name);
+        if (a.type === "skill") {
+            const path = `skills/${seg}/SKILL.md`;
+            if (place(path, a.content, a.name, "skill")) {
+                const e = { type: "skill", name: a.name, path, source: a.source };
+                if (a.description !== undefined)
+                    e.description = a.description;
+                artifacts.push(e);
+            }
+        }
+        else if (a.type === "instructions") {
+            const path = `instructions/${withExt(seg, ".md")}`;
+            if (place(path, a.content, a.name, "instructions"))
+                artifacts.push({ type: "instructions", name: a.name, path });
+        }
+        else if (a.type === "mcp_server") {
+            const path = `mcp/${withExt(seg, ".json")}`;
+            const body = { transport: a.transport, config: a.config };
+            if (a.source !== undefined)
+                body.source = a.source;
+            if (a.secretRefs !== undefined)
+                body.secretRefs = a.secretRefs;
+            if (place(path, JSON.stringify(body, null, 2), a.name, "mcp_server"))
+                artifacts.push({ type: "mcp_server", name: a.name, path });
+        }
+        else {
+            const path = `hooks/${withExt(seg, ".json")}`;
+            const body = { event: a.event, config: a.config };
+            if (a.matcher !== undefined)
+                body.matcher = a.matcher;
+            if (a.source !== undefined)
+                body.source = a.source;
+            if (a.secretRefs !== undefined)
+                body.secretRefs = a.secretRefs;
+            if (place(path, JSON.stringify(body, null, 2), a.name, "hook"))
+                artifacts.push({ type: "hook", name: a.name, path });
+        }
+    }
+    const checks = [];
+    for (const c of gem.checks) {
+        const path = `checks/${withExt(safePathSegment(c.name), ".json")}`;
+        if (path in files)
+            throw new Error(`check path collision: '${c.name}' sanitizes to ${path}, already taken`);
+        files[path] = JSON.stringify(c, null, 2);
+        checks.push({ name: c.name, path });
+    }
+    const manifest = {
+        formatVersion: ARCHIVE_FORMAT_VERSION,
+        name: gem.name,
+        version: opts.version ?? "0.1.0",
+        createdFrom: gem.createdFrom,
+        artifacts,
+        requiredSecrets: gem.requiredSecrets,
+        checks,
+        ...(opts.dependencies && opts.dependencies.length ? { dependencies: opts.dependencies } : {}),
+    };
+    files[MANIFEST_PATH] = JSON.stringify(manifest, null, 2);
+    files[LOCK_PATH] = JSON.stringify(computeLock(files), null, 2);
+    return { files, skipped };
+}
+export function readGemArchive(files) {
+    const manifestRaw = files[MANIFEST_PATH];
+    if (manifestRaw === undefined)
+        throw new Error("archive missing gem.json");
+    const lockRaw = files[LOCK_PATH];
+    if (lockRaw === undefined)
+        throw new Error("archive missing gem.lock");
+    const manifest = JSON.parse(manifestRaw);
+    const lock = JSON.parse(lockRaw);
+    const v = verifyLock(files, lock);
+    if (!v.ok) {
+        throw new Error(`gem.lock verification failed — mismatches:[${v.mismatches.join(",")}] missing:[${v.missing.join(",")}] extra:[${v.extra.join(",")}]`);
+    }
+    const body = (path) => {
+        const c = files[path];
+        if (c === undefined)
+            throw new Error(`manifest references missing file ${path}`);
+        return c;
+    };
+    const artifacts = manifest.artifacts.map((e) => {
+        if (e.type === "skill") {
+            const a = { type: "skill", name: e.name, source: e.source ?? "standalone", content: body(e.path) };
+            if (e.description !== undefined)
+                a.description = e.description;
+            return a;
+        }
+        if (e.type === "instructions") {
+            return { type: "instructions", name: e.name, content: body(e.path) };
+        }
+        if (e.type === "mcp_server") {
+            const o = JSON.parse(body(e.path));
+            const a = { type: "mcp_server", name: e.name, transport: o.transport, config: o.config };
+            if (o.source !== undefined)
+                a.source = o.source;
+            if (o.secretRefs !== undefined)
+                a.secretRefs = o.secretRefs;
+            return a;
+        }
+        const o = JSON.parse(body(e.path));
+        const a = { type: "hook", name: e.name, event: o.event, config: o.config };
+        if (o.matcher !== undefined)
+            a.matcher = o.matcher;
+        if (o.source !== undefined)
+            a.source = o.source;
+        if (o.secretRefs !== undefined)
+            a.secretRefs = o.secretRefs;
+        return a;
+    });
+    const checks = manifest.checks.map((c) => JSON.parse(body(c.path)));
+    return { name: manifest.name, createdFrom: manifest.createdFrom, artifacts, checks, requiredSecrets: manifest.requiredSecrets };
+}
+export function readGemMeta(files) {
+    const manifestRaw = files["gem.json"];
+    if (manifestRaw === undefined)
+        throw new Error("archive missing gem.json");
+    const lockRaw = files["gem.lock"];
+    if (lockRaw === undefined)
+        throw new Error("archive missing gem.lock");
+    const manifest = JSON.parse(manifestRaw);
+    const lock = JSON.parse(lockRaw);
+    return { name: manifest.name, version: manifest.version, dependencies: manifest.dependencies ?? [], gemDigest: lock.gemDigest };
+}

package/dist/gem/archiveFs.js

@@ -0,0 +1,28 @@
+// src/gem/archiveFs.ts
+import { mkdirSync, writeFileSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { dirname, join, relative, sep } from "node:path";
+// Write each relative path under `root`, creating parent dirs. Overwrites existing files.
+export function writeArchiveDir(root, files) {
+    for (const [rel, content] of Object.entries(files)) {
+        const abs = join(root, rel);
+        mkdirSync(dirname(abs), { recursive: true });
+        writeFileSync(abs, content, "utf8");
+    }
+}
+// Read every file under `root` into a FileTree keyed by POSIX-style relative path.
+export function readArchiveDir(root) {
+    const files = {};
+    const walk = (d) => {
+        for (const entry of readdirSync(d)) {
+            if (d === root && entry.startsWith("."))
+                continue; // skip .targets/, .git/, etc. (archive files are never dot-prefixed)
+            const abs = join(d, entry);
+            if (statSync(abs).isDirectory())
+                walk(abs);
+            else
+                files[relative(root, abs).split(sep).join("/")] = readFileSync(abs, "utf8");
+        }
+    };
+    walk(root);
+    return files;
+}

package/dist/gem/archiveTar.js

@@ -0,0 +1,66 @@
+// src/gem/archiveTar.ts
+// Bundle a FileTree into a single .tar.gz buffer and back — the archive's transport/shipping form
+// (the directory tree is the canonical form). Dependency-free: a minimal POSIX ustar writer/reader
+// over node:zlib gzip. In-process only (no disk/network), so the pure core stays pure.
+import { gzipSync, gunzipSync } from "node:zlib";
+const BLOCK = 512;
+// Write `value` as a NUL-terminated octal ASCII field of width `len` at `offset`.
+function writeOctal(buf, value, offset, len) {
+    const s = value.toString(8).padStart(len - 1, "0").slice(-(len - 1));
+    buf.write(s + "\0", offset, "latin1");
+}
+// Read a NUL-trimmed string field of width `len` at `offset`.
+function readStr(buf, offset, len) {
+    const slice = buf.subarray(offset, offset + len);
+    const nul = slice.indexOf(0);
+    return slice.subarray(0, nul === -1 ? len : nul).toString("utf8");
+}
+export function packTar(files) {
+    const blocks = [];
+    for (const path of Object.keys(files).sort()) {
+        const content = Buffer.from(files[path], "utf8");
+        const header = Buffer.alloc(BLOCK);
+        header.write(path, 0, "utf8"); // name (paths are short; prefix field unused)
+        writeOctal(header, 0o644, 100, 8); // mode
+        writeOctal(header, 0, 108, 8); // uid
+        writeOctal(header, 0, 116, 8); // gid
+        writeOctal(header, content.length, 124, 12); // size
+        writeOctal(header, 0, 136, 12); // mtime (fixed 0 -> deterministic header)
+        header[156] = 0x30; // typeflag '0' = regular file
+        header.write("ustar\0", 257, "latin1"); // magic
+        header.write("00", 263, "latin1"); // version
+        // checksum: sum all 512 bytes with the chksum field as spaces, then write it back.
+        for (let i = 148; i < 156; i++)
+            header[i] = 0x20;
+        let sum = 0;
+        for (let i = 0; i < BLOCK; i++)
+            sum += header[i];
+        header.write(sum.toString(8).padStart(6, "0").slice(-6) + "\0 ", 148, "latin1");
+        blocks.push(header, content);
+        const pad = (BLOCK - (content.length % BLOCK)) % BLOCK;
+        if (pad)
+            blocks.push(Buffer.alloc(pad));
+    }
+    blocks.push(Buffer.alloc(BLOCK * 2)); // two zero blocks terminate the archive
+    return gzipSync(Buffer.concat(blocks));
+}
+export function unpackTar(buf) {
+    const tar = gunzipSync(buf);
+    const files = {};
+    let off = 0;
+    while (off + BLOCK <= tar.length) {
+        const name = readStr(tar, off, 100);
+        if (name === "")
+            break; // zero block => end of archive
+        const prefix = readStr(tar, off + 345, 155);
+        const full = prefix ? `${prefix}/${name}` : name;
+        const size = parseInt(readStr(tar, off + 124, 12).trim() || "0", 8);
+        const typeflag = tar[off + 156];
+        off += BLOCK;
+        if (typeflag === 0x30 || typeflag === 0) {
+            files[full] = tar.subarray(off, off + size).toString("utf8");
+        }
+        off += Math.ceil(size / BLOCK) * BLOCK;
+    }
+    return files;
+}