@reeledge/agent-tools 0.1.2

package/dist/apps/claude-code.js

@@ -0,0 +1,40 @@
+import path from 'node:path';
+import { claudeMcpAddArgs } from '../mcp.js';
+import { writeSkillTree } from '../skills.js';
+import { APP_LABELS, CONNECTOR_NAME, } from './types.js';
+/**
+ * Claude Code adapter. Skills are per-skill `SKILL.md` directories under
+ * `~/.claude/skills/` (overridable via `--skills-dir`); the MCP connector is
+ * registered by spawning `claude mcp add --transport http …` (the documented
+ * Claude Code path), which embeds the bearer token in an `Authorization` header.
+ */
+/** Resolve the skills dir: explicit override, else `~/.claude/skills`. */
+function claudeSkillsDir(env) {
+    return env.skillsDirOverride ?? path.join(env.homeDir, '.claude', 'skills');
+}
+/** Construct the Claude Code adapter for the given environment. */
+export function makeClaudeCodeAdapter(env) {
+    const skillsDir = () => claudeSkillsDir(env);
+    return {
+        id: 'claude-code',
+        label: APP_LABELS['claude-code'],
+        skillsDir,
+        writeSkills(skills) {
+            return skills.flatMap((s) => writeSkillTree(skillsDir(), s.slug, s.files));
+        },
+        async configureMcp(serverUrl, token) {
+            await env.exec('claude', claudeMcpAddArgs(CONNECTOR_NAME, serverUrl, token));
+        },
+        dryRunPlan(serverUrl, token, skills) {
+            const lines = [];
+            for (const s of skills) {
+                for (const file of s.files) {
+                    lines.push(`would write ${path.join(skillsDir(), s.slug, file.path)}`);
+                }
+            }
+            const args = claudeMcpAddArgs(CONNECTOR_NAME, serverUrl, token);
+            lines.push(`would run: claude ${args.join(' ')}`);
+            return lines;
+        },
+    };
+}

package/dist/apps/codex.js

@@ -0,0 +1,122 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { mcpEndpoint } from '../mcp.js';
+import { writeSkillTree } from '../skills.js';
+import { APP_LABELS, CONNECTOR_NAME, } from './types.js';
+/**
+ * OpenAI Codex CLI adapter. Codex reads `~/.codex/config.toml` and registers
+ * MCP servers under `[mcp_servers.<name>]`; a remote Streamable-HTTP server is
+ * indicated by a `url` key (no `transport`), and a literal `Authorization`
+ * header goes in a static `http_headers` inline table. Codex also has a skills
+ * concept — per-skill `SKILL.md` directories under `~/.agents/skills/`.
+ *
+ * Verified against https://developers.openai.com/codex/mcp,
+ * https://developers.openai.com/codex/config-reference and
+ * https://developers.openai.com/codex/skills (Jun 2026).
+ */
+/** Absolute path to the Codex skills tree. */
+function codexSkillsDir(env) {
+    return path.join(env.homeDir, '.agents', 'skills');
+}
+/** Absolute path to the Codex config file. */
+function codexConfigPath(env) {
+    return path.join(env.homeDir, '.codex', 'config.toml');
+}
+/**
+ * The `[mcp_servers.<name>]` TOML block for a remote HTTP server with a static
+ * bearer header. Self-contained (token embedded) so it works without extra env
+ * setup — matching how the Claude Code connector embeds the token in its header.
+ */
+export function codexConfigBlock(name, endpoint, token) {
+    return [
+        `[mcp_servers.${name}]`,
+        `url = "${endpoint}"`,
+        `http_headers = { "Authorization" = "Bearer ${token}" }`,
+        '',
+    ].join('\n');
+}
+/** Split TOML into a preamble (top-level keys) + ordered `[table]` sections. */
+function splitSections(content) {
+    const preamble = [];
+    const sections = [];
+    let cur = null;
+    for (const line of content.split('\n')) {
+        if (line.trim().startsWith('[')) {
+            cur = { header: line.trim(), body: [] };
+            sections.push(cur);
+        }
+        else if (cur) {
+            cur.body.push(line);
+        }
+        else {
+            preamble.push(line);
+        }
+    }
+    return { preamble, sections };
+}
+/**
+ * Merge a generated `[mcp_servers.<name>]` block into an existing `config.toml`:
+ * replace the same-named section in place (preserving order + other servers) or
+ * append it. Output is normalised — sections separated by a blank line, single
+ * trailing newline. This is a targeted edit, not a full TOML parser, but it is
+ * exact for the simple blocks this installer writes.
+ */
+export function mergeCodexToml(existing, name, block) {
+    const header = `[mcp_servers.${name}]`;
+    const blockText = block.trim();
+    if (existing.trim() === '')
+        return `${blockText}\n`;
+    const { preamble, sections } = splitSections(existing);
+    const rendered = [];
+    let replaced = false;
+    for (const s of sections) {
+        if (s.header === header) {
+            rendered.push(blockText);
+            replaced = true;
+        }
+        else {
+            rendered.push(`${s.header}\n${s.body.join('\n')}`.trim());
+        }
+    }
+    if (!replaced)
+        rendered.push(blockText);
+    const blocks = [];
+    const pre = preamble.join('\n').trim();
+    if (pre !== '')
+        blocks.push(pre);
+    blocks.push(...rendered);
+    return `${blocks.join('\n\n')}\n`;
+}
+/** Construct the Codex adapter for the given environment. */
+export function makeCodexAdapter(env) {
+    const skillsDir = () => codexSkillsDir(env);
+    return {
+        id: 'codex',
+        label: APP_LABELS.codex,
+        skillsDir,
+        writeSkills(skills) {
+            return skills.flatMap((s) => writeSkillTree(skillsDir(), s.slug, s.files));
+        },
+        async configureMcp(serverUrl, token) {
+            const block = codexConfigBlock(CONNECTOR_NAME, mcpEndpoint(serverUrl), token);
+            const cfgPath = codexConfigPath(env);
+            const existing = fs.existsSync(cfgPath) ? fs.readFileSync(cfgPath, 'utf8') : '';
+            const merged = mergeCodexToml(existing, CONNECTOR_NAME, block);
+            fs.mkdirSync(path.dirname(cfgPath), { recursive: true });
+            fs.writeFileSync(cfgPath, merged, 'utf8');
+        },
+        dryRunPlan(serverUrl, token, skills) {
+            const lines = [];
+            for (const s of skills) {
+                for (const file of s.files) {
+                    lines.push(`would write ${path.join(skillsDir(), s.slug, file.path)}`);
+                }
+            }
+            lines.push(`would write ${codexConfigPath(env)} with section [mcp_servers.${CONNECTOR_NAME}]:`);
+            for (const l of codexConfigBlock(CONNECTOR_NAME, mcpEndpoint(serverUrl), token).trimEnd().split('\n')) {
+                lines.push(`    ${l}`);
+            }
+            return lines;
+        },
+    };
+}

package/dist/apps/droid.js

@@ -0,0 +1,81 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { mcpEndpoint } from '../mcp.js';
+import { writeSkillTree } from '../skills.js';
+import { APP_LABELS, CONNECTOR_NAME, } from './types.js';
+/** Absolute path to the Droid skills tree. */
+function droidSkillsDir(env) {
+    return path.join(env.homeDir, '.factory', 'skills');
+}
+/** Absolute path to the Droid MCP config file. */
+function droidConfigPath(env) {
+    return path.join(env.homeDir, '.factory', 'mcp.json');
+}
+/** The `mcpServers.<name>` entry for a remote HTTP server with a bearer header. */
+export function droidServerEntry(endpoint, token) {
+    return {
+        type: 'http',
+        url: endpoint,
+        headers: { Authorization: `Bearer ${token}` },
+    };
+}
+/**
+ * Merge a server entry into an existing `mcp.json` body (or `undefined` when no
+ * file exists). Malformed JSON is replaced with a fresh file (mirroring how the
+ * CLI's own config loader tolerates corruption). Other servers + top-level keys
+ * are preserved. Returns pretty-printed JSON with a trailing newline.
+ */
+export function mergeDroidConfig(existing, name, entry) {
+    let root = {};
+    if (existing && existing.trim() !== '') {
+        try {
+            const parsed = JSON.parse(existing);
+            if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                root = parsed;
+            }
+        }
+        catch {
+            root = {};
+        }
+    }
+    const servers = root.mcpServers && typeof root.mcpServers === 'object' && !Array.isArray(root.mcpServers)
+        ? root.mcpServers
+        : {};
+    servers[name] = entry;
+    root.mcpServers = servers;
+    return `${JSON.stringify(root, null, 2)}\n`;
+}
+/** Construct the Droid adapter for the given environment. */
+export function makeDroidAdapter(env) {
+    const skillsDir = () => droidSkillsDir(env);
+    return {
+        id: 'droid',
+        label: APP_LABELS.droid,
+        skillsDir,
+        writeSkills(skills) {
+            return skills.flatMap((s) => writeSkillTree(skillsDir(), s.slug, s.files));
+        },
+        async configureMcp(serverUrl, token) {
+            const entry = droidServerEntry(mcpEndpoint(serverUrl), token);
+            const cfgPath = droidConfigPath(env);
+            const existing = fs.existsSync(cfgPath) ? fs.readFileSync(cfgPath, 'utf8') : undefined;
+            const merged = mergeDroidConfig(existing, CONNECTOR_NAME, entry);
+            fs.mkdirSync(path.dirname(cfgPath), { recursive: true });
+            fs.writeFileSync(cfgPath, merged, 'utf8');
+        },
+        dryRunPlan(serverUrl, token, skills) {
+            const lines = [];
+            for (const s of skills) {
+                for (const file of s.files) {
+                    lines.push(`would write ${path.join(skillsDir(), s.slug, file.path)}`);
+                }
+            }
+            const entry = droidServerEntry(mcpEndpoint(serverUrl), token);
+            lines.push(`would write ${droidConfigPath(env)} with mcpServers.${CONNECTOR_NAME}:`);
+            for (const l of JSON.stringify(entry, null, 2).split('\n')) {
+                lines.push(`    ${l}`);
+            }
+            return lines;
+        },
+    };
+}

package/dist/apps/index.js

@@ -0,0 +1,21 @@
+import { makeClaudeCodeAdapter } from './claude-code.js';
+import { makeCodexAdapter } from './codex.js';
+import { makeDroidAdapter } from './droid.js';
+export { ALL_APP_IDS, APP_LABELS, CONNECTOR_NAME, parseAppSpec } from './types.js';
+/** Build the adapter for a single app id (throws on an unknown id). */
+export function makeAdapter(id, env) {
+    switch (id) {
+        case 'claude-code':
+            return makeClaudeCodeAdapter(env);
+        case 'codex':
+            return makeCodexAdapter(env);
+        case 'droid':
+            return makeDroidAdapter(env);
+        default:
+            throw new Error(`Unknown app: ${id}`);
+    }
+}
+/** Build adapters for a list of app ids, preserving order. */
+export function makeAdapters(ids, env) {
+    return ids.map((id) => makeAdapter(id, env));
+}

package/dist/apps/types.js

@@ -0,0 +1,44 @@
+/**
+ * App-target model: each agent the installer can configure (Claude Code, OpenAI
+ * Codex, Factory AI Droid) is described by a small {@link AppAdapter} so the
+ * orchestrator can write skills + wire the MCP connector uniformly. The pure
+ * `parseAppSpec` turns a `--app` flag (or interactive answer) into a list of
+ * ids; the side-effecting adapters live in the sibling files.
+ */
+/** Every supported app, in the canonical display/selection order. */
+export const ALL_APP_IDS = ['claude-code', 'codex', 'droid'];
+/** Human-readable label per app id. */
+export const APP_LABELS = {
+    'claude-code': 'Claude Code',
+    codex: 'Codex',
+    droid: 'Droid (Factory AI)',
+};
+/** The MCP connector name registered in every app. */
+export const CONNECTOR_NAME = 'reel-edge';
+/**
+ * Parse a `--app` value (or interactive answer) into a de-duplicated list of
+ * app ids. Accepts `all`, a single id, or a comma list. Case-insensitive;
+ * whitespace-tolerant. Throws on an unknown id or an empty spec.
+ */
+export function parseAppSpec(spec) {
+    const tokens = spec
+        .split(',')
+        .map((t) => t.trim().toLowerCase())
+        .filter((t) => t.length > 0);
+    if (tokens.length === 0) {
+        throw new Error('No app specified. Use --app claude-code|codex|droid|all (or a comma list).');
+    }
+    if (tokens.includes('all'))
+        return [...ALL_APP_IDS];
+    const known = new Set(ALL_APP_IDS);
+    const out = [];
+    for (const t of tokens) {
+        if (!known.has(t)) {
+            throw new Error(`Unknown app: ${t}. Valid: ${ALL_APP_IDS.join(', ')}, all.`);
+        }
+        const id = t;
+        if (!out.includes(id))
+            out.push(id);
+    }
+    return out;
+}

package/dist/config.js

@@ -0,0 +1,32 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+/** Config home — `REELEDGE_CONFIG_DIR` override, else `~/.reeledge`. */
+export function configDir() {
+    const override = process.env.REELEDGE_CONFIG_DIR;
+    if (override && override.trim() !== '')
+        return override;
+    return path.join(os.homedir(), '.reeledge');
+}
+/** Absolute path to `config.json`. */
+export function configPath() {
+    return path.join(configDir(), 'config.json');
+}
+/** Load the stored config, or `{}` if missing/unreadable/malformed. */
+export function loadConfig() {
+    try {
+        const raw = fs.readFileSync(configPath(), 'utf8');
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === 'object')
+            return parsed;
+        return {};
+    }
+    catch {
+        return {};
+    }
+}
+/** Persist the config (creating the dir), pretty-printed for hand-editing. */
+export function saveConfig(cfg) {
+    fs.mkdirSync(configDir(), { recursive: true });
+    fs.writeFileSync(configPath(), `${JSON.stringify(cfg, null, 2)}\n`, 'utf8');
+}

package/dist/connect.js

@@ -0,0 +1,26 @@
+import { httpErrorMessage } from './skills.js';
+function resolveFetch(deps) {
+    const f = deps?.fetch ?? globalThis.fetch;
+    if (!f)
+        throw new Error('No fetch implementation available (Node >=20 required).');
+    return f;
+}
+/**
+ * Hit `GET <serverUrl>/skills` with `Authorization: Bearer <token>` and classify
+ * the result. Never throws — failures come back as `{ ok: false, … }` so the
+ * caller can keep going (the check is non-fatal).
+ */
+export async function verifyConnection(serverUrl, token, deps) {
+    const url = `${serverUrl.replace(/\/+$/, '')}/skills`;
+    try {
+        const f = resolveFetch(deps);
+        const res = await f(url, { headers: { Authorization: `Bearer ${token}` } });
+        if (!res.ok)
+            return { ok: false, status: res.status, error: httpErrorMessage(res.status) };
+        const body = (await res.json());
+        return { ok: true, count: Array.isArray(body) ? body.length : 0 };
+    }
+    catch (err) {
+        return { ok: false, error: err.message };
+    }
+}

package/dist/index.js

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+/**
+ * `@reeledge/agent-tools` — the `npx agent-tools install` / `update` CLI. Wires
+ * the Reel Edge MCP connector + skills into one or more local agents (Claude
+ * Code, OpenAI Codex, Factory AI Droid) using shared-token auth.
+ *
+ * Layout: `parseArgs` (command discriminant) + `parseOptions` (flags) feed the
+ * orchestrators `runInstall` / `runUpdate` (in install.ts), which compose the
+ * pure, separately-tested helpers in config.ts / skills.ts / mcp.ts via injected
+ * side-effecting `deps` (fetch / exec / prompt / log).
+ */
+import { spawn } from 'node:child_process';
+import { realpathSync } from 'node:fs';
+import { createInterface } from 'node:readline';
+import { fileURLToPath } from 'node:url';
+import checkbox from '@inquirer/checkbox';
+import { parseOptions } from './options.js';
+import { runInstall, runUpdate } from './install.js';
+export const USAGE = [
+    'Usage: agent-tools <command> [options]',
+    '',
+    'Commands:',
+    '  install    Install the Reel Edge MCP connector + skills into your agent(s)',
+    '  update     Re-fetch skills and re-configure an existing install',
+    '  help       Show this help',
+    '',
+    'Options (install / update):',
+    '  --server-url <url>   MCP server base URL (else stored config / prompt)',
+    '  --token <tok>        Shared bearer token (else stored config / prompt)',
+    '  --app <targets>      Agent(s) to configure: claude-code, codex, droid,',
+    '                       a comma list, or all (default: prompt, or all with --yes)',
+    '  --skills a,b         Install only these skill slugs',
+    '  --all                Install every skill the server offers',
+    '  --skills-dir <path>  Claude Code skills dir (default ~/.claude/skills)',
+    '  --reauth             Ignore saved credentials and re-prompt for URL + token',
+    '  --dry-run            Print the per-app plan; write nothing, exec nothing',
+    '  --yes                Non-interactive; never prompt',
+].join('\n');
+/** Parse argv (without node/script) into a discriminated command. */
+export function parseArgs(argv) {
+    const first = argv[0];
+    if (first === undefined || first === 'help' || first === '-h' || first === '--help') {
+        return { command: 'help' };
+    }
+    if (first === 'install')
+        return { command: 'install' };
+    if (first === 'update')
+        return { command: 'update' };
+    return { command: 'unknown', name: first };
+}
+/**
+ * Synchronous handler for the non-network commands (help / unknown). `install`
+ * and `update` are async and go through `main`; calling `run` for them just
+ * points the user at `main`/the usage (kept so existing callers/tests of the
+ * pure `run` keep working).
+ */
+export function run(argv, out = console.log) {
+    const parsed = parseArgs(argv);
+    switch (parsed.command) {
+        case 'install':
+        case 'update':
+            out(`Run \`agent-tools ${parsed.command}\` from a terminal.`);
+            out('');
+            out(USAGE);
+            return 0;
+        case 'help':
+            out(USAGE);
+            return 0;
+        case 'unknown':
+            out(`Unknown command: ${parsed.name}`);
+            out('');
+            out(USAGE);
+            return 1;
+    }
+}
+/** Default production deps: real fetch, spawn `claude`, readline prompt, stdout. */
+export function defaultDeps() {
+    return {
+        fetch: globalThis.fetch,
+        exec: (cmd, args) => new Promise((resolve, reject) => {
+            const child = spawn(cmd, args, { stdio: 'inherit' });
+            child.on('error', reject);
+            child.on('close', (code) => code === 0 ? resolve() : reject(new Error(`${cmd} exited with code ${code}`)));
+        }),
+        prompt: (question) => new Promise((resolve) => {
+            const rl = createInterface({ input: process.stdin, output: process.stdout });
+            rl.question(question, (answer) => {
+                rl.close();
+                resolve(answer);
+            });
+        }),
+        multiSelect: ({ message, choices }) => checkbox({
+            message,
+            choices: choices.map((c) => ({ name: c.name, value: c.value, checked: c.checked })),
+        }),
+        log: (line) => console.log(line),
+    };
+}
+/**
+ * Async entrypoint: dispatches install/update to the orchestrators with the
+ * given deps (production by default; tests inject fakes). Returns an exit code.
+ */
+export async function main(argv, deps = defaultDeps()) {
+    const parsed = parseArgs(argv);
+    if (parsed.command === 'install' || parsed.command === 'update') {
+        let opts;
+        try {
+            opts = parseOptions(argv.slice(1));
+        }
+        catch (err) {
+            deps.log(err.message);
+            deps.log('');
+            deps.log(USAGE);
+            return 1;
+        }
+        // Non-interactive automatically when stdin is not a TTY.
+        if (!process.stdin.isTTY)
+            opts.yes = opts.yes || true;
+        return parsed.command === 'install' ? runInstall(opts, deps) : runUpdate(opts, deps);
+    }
+    return run(argv, deps.log);
+}
+/**
+ * True when this module is the process entry point. Resolves symlinks (realpath)
+ * before comparing, so it works when launched through the `bin` symlink
+ * (`…/node_modules/.bin/agent-tools` → `dist/index.js`) under npx / global install.
+ * A plain string compare of `import.meta.url` to `argv[1]` is false there — argv[1]
+ * is the symlink — which silently skipped main() (ran but printed nothing).
+ */
+export function isMainModule(argv1, moduleUrl) {
+    if (!argv1)
+        return false;
+    try {
+        return realpathSync(argv1) === realpathSync(fileURLToPath(moduleUrl));
+    }
+    catch {
+        return false;
+    }
+}
+// Run only when invoked as a script (not when imported by tests).
+if (isMainModule(process.argv[1], import.meta.url)) {
+    main(process.argv.slice(2)).then((code) => process.exit(code));
+}

package/dist/install.js

@@ -0,0 +1,233 @@
+import os from 'node:os';
+import { loadConfig, saveConfig } from './config.js';
+import { ALL_APP_IDS, APP_LABELS, CONNECTOR_NAME, makeAdapters as defaultMakeAdapters, } from './apps/index.js';
+import { verifyConnection } from './connect.js';
+import { checkHealth, fetchSkillFiles, fetchSkillList, selectSkills } from './skills.js';
+/**
+ * Hardcoded production server. The CLI never prompts for the server URL: it
+ * resolves `--server-url` flag → stored config → this default, so a normal
+ * install needs only a token. `--server-url` still overrides (e.g. local dev,
+ * `http://localhost:3000`).
+ */
+export const DEFAULT_SERVER_URL = 'https://reeledge-mcp.onrender.com';
+/**
+ * Resolve `{ serverUrl, token }`. The server URL is resolved silently —
+ * `--server-url` flag → stored config → `DEFAULT_SERVER_URL` — so it is NEVER
+ * prompted (a normal install needs only a token). The token still resolves
+ * flag → stored config → interactive prompt. Returns null (after logging what's
+ * missing) when the token can't be resolved without prompting (`--yes` /
+ * non-TTY).
+ *
+ * NOTE: this no longer persists anything. The credentials are saved only AFTER
+ * the first successful authenticated call (in `run`), so a token that later
+ * 401s never gets written to `~/.reeledge/config.json` and locks the user out.
+ *
+ * `fromStore` is true only when BOTH values came silently from the stored
+ * config (no flag, no fresh prompt, no default) — the caller uses it to surface
+ * a "Using saved connection…" line so reuse is never invisible.
+ *
+ * `--reauth` ignores the stored config entirely and forces a fresh token prompt
+ * (a `--token` flag still wins; the URL falls back to the default). It is a
+ * contradiction with `--yes` / non-TTY (no way to prompt) → abort with a clear
+ * message.
+ */
+async function resolveCredentials(opts, deps) {
+    if (opts.reauth && opts.yes) {
+        deps.log('Cannot --reauth without an interactive prompt (running with --yes or a non-TTY). ' +
+            'Re-run in a terminal.');
+        return null;
+    }
+    const stored = opts.reauth ? {} : loadConfig();
+    const serverFromStore = opts.serverUrl === undefined && stored.serverUrl !== undefined;
+    const tokenFromStore = opts.token === undefined && stored.token !== undefined;
+    const serverUrl = opts.serverUrl ?? stored.serverUrl ?? DEFAULT_SERVER_URL;
+    let token = opts.token ?? stored.token;
+    if (!token) {
+        if (opts.yes) {
+            deps.log('Missing required value: --token (and none stored). Aborting.');
+            return null;
+        }
+        token = (await deps.prompt('Reel Edge bearer token: ')).trim();
+        if (!token) {
+            deps.log('No token provided. Aborting.');
+            return null;
+        }
+    }
+    return { serverUrl, token, fromStore: serverFromStore && tokenFromStore };
+}
+/**
+ * Resolve which apps to configure: `--app` if given, else `all` under `--yes`
+ * (non-interactive), else an interactive checkbox multi-select (all apps
+ * pre-checked). Confirming with nothing checked logs a clear message and
+ * returns `[]`, which the caller treats as an abort.
+ */
+async function resolveApps(opts, deps) {
+    if (opts.apps && opts.apps.length > 0)
+        return opts.apps;
+    if (opts.yes)
+        return [...ALL_APP_IDS];
+    const selected = await deps.multiSelect({
+        message: 'Which app(s) to configure? (↑/↓ move, SPACE toggle, ENTER confirm)',
+        choices: ALL_APP_IDS.map((id) => ({ name: APP_LABELS[id], value: id, checked: true })),
+    });
+    if (selected.length === 0) {
+        deps.log('No apps selected. Aborting.');
+        return [];
+    }
+    return selected;
+}
+/**
+ * Shared flow for both `install` and `update`: resolve creds + target apps,
+ * fetch the skill list (clamped to `allowedSkills` if provided), fetch each
+ * body once, then per app write its skills + wire the MCP connector (or print
+ * the plan under --dry-run), and finally run an authenticated connection test.
+ */
+async function run(opts, deps, mode, allowedSkills) {
+    const creds = await resolveCredentials(opts, deps);
+    if (!creds)
+        return 1;
+    const { serverUrl, token } = creds;
+    // Make silent reuse of stored credentials visible (never print the token).
+    if (creds.fromStore) {
+        deps.log(`Using saved connection to ${serverUrl} (token ✓).`);
+    }
+    const appIds = await resolveApps(opts, deps);
+    if (appIds.length === 0)
+        return 1;
+    const env = {
+        homeDir: deps.homeDir ?? os.homedir(),
+        exec: deps.exec,
+        skillsDirOverride: opts.skillsDir,
+    };
+    const adapters = (deps.makeAdapters ?? defaultMakeAdapters)(appIds, env);
+    // 1. Fetch the catalog. This is the first authenticated call — only once it
+    //    succeeds do we persist the credentials (so a token that 401s is never
+    //    written and can't silently lock the user out on the next run).
+    let list;
+    try {
+        list = await fetchSkillList(serverUrl, token, deps);
+    }
+    catch (err) {
+        deps.log(`Could not fetch the skill list: ${err.message}`);
+        return 1;
+    }
+    saveConfig({ serverUrl, token });
+    // 2. Select which skills to install. Interactive `install` (no flags, on a
+    //    TTY) gets a checkbox of every offered skill (all pre-checked); otherwise
+    //    flags decide. `update` defaults to "all" so an existing install is
+    //    refreshed wholesale even without --all.
+    let slugs;
+    const interactiveSkills = mode === 'install' &&
+        !opts.yes &&
+        !opts.all &&
+        !(opts.skills && opts.skills.length > 0);
+    if (interactiveSkills) {
+        const allowed = allowedSkills !== undefined ? new Set(allowedSkills) : null;
+        const candidates = allowed ? list.filter((s) => allowed.has(s.slug)) : list;
+        slugs = await deps.multiSelect({
+            message: 'Which skill(s) to install? (↑/↓ move, SPACE toggle, ENTER confirm)',
+            choices: candidates.map((s) => ({
+                name: `${s.name} (${s.slug})`,
+                value: s.slug,
+                checked: true,
+            })),
+        });
+    }
+    else {
+        const selectOpts = mode === 'update' && !opts.all && !(opts.skills && opts.skills.length > 0)
+            ? { all: true, allowedSkills }
+            : { all: opts.all, skills: opts.skills, allowedSkills };
+        slugs = selectSkills(list, selectOpts);
+    }
+    if (slugs.length === 0) {
+        deps.log('No skills selected. Use --all or --skills <a,b>. Available:');
+        for (const s of list)
+            deps.log(`  - ${s.slug}: ${s.name}`);
+        return 1;
+    }
+    // 3. Fetch every selected skill's full file tree once (SKILL.md + references/**;
+    //    shared across apps). Fetched even under --dry-run so the plan can enumerate
+    //    every file. Skipped only when no selected app has a skills concept. An older
+    //    server without the /files route is handled by fetchSkillFiles' single-body
+    //    fallback.
+    const anySkills = adapters.some((a) => a.skillsDir() !== null);
+    let skills = slugs.map((slug) => ({ slug, files: [] }));
+    if (anySkills) {
+        skills = [];
+        for (const slug of slugs) {
+            let files;
+            try {
+                files = await fetchSkillFiles(serverUrl, token, slug, deps);
+            }
+            catch (err) {
+                // err.message already reads `Couldn't fetch skill "<slug>": <reason>`
+                // (slug kept, no URL) — log it as-is to avoid a double "fetch…fetch".
+                deps.log(`  ${err.message}`);
+                return 1;
+            }
+            skills.push({ slug, files });
+        }
+    }
+    const verb = mode === 'install' ? 'Installing' : 'Updating';
+    deps.log(`${verb} ${slugs.length} skill(s) for ${adapters.length} app(s): ${slugs.join(', ')}`);
+    // 4. Per app: write skills + configure the MCP connector (or print the plan).
+    for (const app of adapters) {
+        deps.log('');
+        deps.log(`== ${app.label} ==`);
+        if (opts.dryRun) {
+            for (const line of app.dryRunPlan(serverUrl, token, skills))
+                deps.log(`  [dry-run] ${line}`);
+            continue;
+        }
+        if (app.skillsDir() === null) {
+            deps.log('  skills: N/A for this app (MCP server only)');
+        }
+        else {
+            for (const file of app.writeSkills(skills))
+                deps.log(`  wrote ${file}`);
+        }
+        try {
+            await app.configureMcp(serverUrl, token);
+            deps.log(`  configured MCP connector "${CONNECTOR_NAME}"`);
+        }
+        catch (err) {
+            deps.log(`  Warning: configuring the MCP connector for ${app.label} failed ` +
+                `(${err.message}). Re-run with --dry-run to see the exact ` +
+                `command/config to apply manually.`);
+        }
+    }
+    // 5. Liveness ping (unauthenticated) — warn, never fail.
+    const healthy = await checkHealth(serverUrl, deps);
+    if (!healthy) {
+        deps.log('');
+        deps.log('Warning: the Reel Edge server health check failed — the server may be down.');
+    }
+    // 6. Authenticated connection test (PRD step 7) — non-fatal.
+    deps.log('');
+    if (opts.dryRun) {
+        deps.log(`[dry-run] would verify the connection: GET ${serverUrl.replace(/\/+$/, '')}/skills with the bearer token.`);
+    }
+    else {
+        const result = await verifyConnection(serverUrl, token, deps);
+        if (result.ok) {
+            deps.log(`Connected — ${result.count} skill(s) available.`);
+        }
+        else {
+            const why = result.status ? `HTTP ${result.status}` : (result.error ?? 'unknown error');
+            deps.log(`Could not connect (${why}). Double-check the server URL and token.`);
+        }
+    }
+    // 7. Summary.
+    deps.log('');
+    deps.log(`Done. ${mode === 'install' ? 'Installed' : 'Updated'} ${slugs.length} skill(s) ` +
+        `for ${adapters.map((a) => a.label).join(', ')}: ${slugs.join(', ')}.`);
+    if (opts.dryRun)
+        deps.log('(dry-run — nothing was written or executed.)');
+    return 0;
+}
+export function runInstall(opts, deps, allowedSkills) {
+    return run(opts, deps, 'install', allowedSkills);
+}
+export function runUpdate(opts, deps, allowedSkills) {
+    return run(opts, deps, 'update', allowedSkills);
+}

package/dist/mcp.js

@@ -0,0 +1,33 @@
+/**
+ * Pure helpers for wiring the Reel Edge MCP connector into Claude Code via the
+ * `claude mcp add` subcommand. Kept side-effect-free so they're exhaustively
+ * unit-tested; the actual `child_process` exec is a thin wrapper in install.ts.
+ */
+/** Normalise a server URL to its Streamable-HTTP `/mcp` endpoint. */
+export function mcpEndpoint(serverUrl) {
+    const trimmed = serverUrl.replace(/\/+$/, '');
+    return trimmed.endsWith('/mcp') ? trimmed : `${trimmed}/mcp`;
+}
+/**
+ * argv (after the `claude` binary) for:
+ *   claude mcp add --scope user --transport http <name> <serverUrl>/mcp \
+ *     --header "Authorization: Bearer <token>"
+ *
+ * `--scope user` registers the connector GLOBALLY (user scope) rather than the
+ * `claude mcp add` default of `local` (per-project), so the connector matches
+ * the globally-installed skills instead of being scoped to one project.
+ */
+export function claudeMcpAddArgs(name, serverUrl, token) {
+    return [
+        'mcp',
+        'add',
+        '--scope',
+        'user',
+        '--transport',
+        'http',
+        name,
+        mcpEndpoint(serverUrl),
+        '--header',
+        `Authorization: Bearer ${token}`,
+    ];
+}

package/dist/options.js

@@ -0,0 +1,79 @@
+import os from 'node:os';
+import path from 'node:path';
+import { parseAppSpec } from './apps/types.js';
+/** Default skills directory for Claude Code: `~/.claude/skills`. */
+export function defaultSkillsDir() {
+    return path.join(os.homedir(), '.claude', 'skills');
+}
+const VALUE_FLAGS = new Set(['--server-url', '--token', '--app', '--skills', '--skills-dir']);
+const BOOL_FLAGS = new Set(['--all', '--dry-run', '--yes', '--reauth']);
+/**
+ * Parse the flag portion of argv (i.e. argv WITHOUT the leading command token).
+ * Supports `--flag value` and `--flag=value`. Throws on an unknown flag so a
+ * typo fails loudly rather than being silently ignored.
+ */
+export function parseOptions(argv) {
+    const opts = {
+        all: false,
+        skillsDir: defaultSkillsDir(),
+        dryRun: false,
+        yes: false,
+        reauth: false,
+    };
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        let flag = arg;
+        let inlineValue;
+        const eq = arg.indexOf('=');
+        if (arg.startsWith('--') && eq !== -1) {
+            flag = arg.slice(0, eq);
+            inlineValue = arg.slice(eq + 1);
+        }
+        const readValue = () => {
+            if (inlineValue !== undefined)
+                return inlineValue;
+            const next = argv[i + 1];
+            if (next === undefined)
+                throw new Error(`Flag ${flag} requires a value.`);
+            i++;
+            return next;
+        };
+        if (BOOL_FLAGS.has(flag)) {
+            if (flag === '--all')
+                opts.all = true;
+            else if (flag === '--dry-run')
+                opts.dryRun = true;
+            else if (flag === '--yes')
+                opts.yes = true;
+            else if (flag === '--reauth')
+                opts.reauth = true;
+            continue;
+        }
+        if (VALUE_FLAGS.has(flag)) {
+            const value = readValue();
+            switch (flag) {
+                case '--server-url':
+                    opts.serverUrl = value;
+                    break;
+                case '--token':
+                    opts.token = value;
+                    break;
+                case '--app':
+                    opts.apps = parseAppSpec(value);
+                    break;
+                case '--skills':
+                    opts.skills = value
+                        .split(',')
+                        .map((s) => s.trim())
+                        .filter((s) => s.length > 0);
+                    break;
+                case '--skills-dir':
+                    opts.skillsDir = value;
+                    break;
+            }
+            continue;
+        }
+        throw new Error(`Unknown flag: ${flag}`);
+    }
+    return opts;
+}

package/dist/skills.js

@@ -0,0 +1,143 @@
+import fs from 'node:fs';
+import path from 'node:path';
+function resolveFetch(deps) {
+    const f = deps?.fetch ?? globalThis.fetch;
+    if (!f)
+        throw new Error('No fetch implementation available (Node >=20 required).');
+    return f;
+}
+function baseUrl(serverUrl) {
+    return serverUrl.replace(/\/+$/, '');
+}
+function authHeaders(token) {
+    return { Authorization: `Bearer ${token}` };
+}
+/**
+ * Map an HTTP status to a user-facing, non-leaky message. Deliberately omits the
+ * request URL/endpoint so server internals never surface in CLI output: a 401/403
+ * points the user at re-authing; anything else is a generic "couldn't reach"
+ * with just the status code.
+ */
+export function httpErrorMessage(status) {
+    if (status === 401 || status === 403) {
+        return 'Unauthorized — invalid or missing authorization credentials. Re-run and provide a valid token (or --token).';
+    }
+    return `Couldn't reach the Reel Edge server (HTTP ${status}).`;
+}
+/** `GET /skills` → the skill catalog. Throws on a non-2xx response. */
+export async function fetchSkillList(serverUrl, token, deps) {
+    const f = resolveFetch(deps);
+    const url = `${baseUrl(serverUrl)}/skills`;
+    const res = await f(url, { headers: authHeaders(token) });
+    if (!res.ok) {
+        throw new Error(httpErrorMessage(res.status));
+    }
+    return (await res.json());
+}
+/** `GET /skills/:slug` → the markdown body. Throws on a non-2xx response. */
+export async function fetchSkillBody(serverUrl, token, slug, deps) {
+    const f = resolveFetch(deps);
+    const url = `${baseUrl(serverUrl)}/skills/${slug}`;
+    const res = await f(url, { headers: authHeaders(token) });
+    if (!res.ok) {
+        throw new Error(`Couldn't fetch skill "${slug}": ${httpErrorMessage(res.status)}`);
+    }
+    return res.text();
+}
+/**
+ * `GET /skills/:slug/files` → the full file tree (`SKILL.md` + `references/**`).
+ *
+ * On a 404 (an older server without the `/files` route, OR a genuinely unknown
+ * slug) we fall back to `fetchSkillBody`: that succeeds on an old server (→ a
+ * single-file tree) and 404s again for an unknown slug (→ a clean throw). Any
+ * other non-2xx throws a non-leaky `Couldn't fetch skill "<slug>": …`.
+ */
+export async function fetchSkillFiles(serverUrl, token, slug, deps) {
+    const f = resolveFetch(deps);
+    const url = `${baseUrl(serverUrl)}/skills/${slug}/files`;
+    const res = await f(url, { headers: authHeaders(token) });
+    if (res.status === 404) {
+        const body = await fetchSkillBody(serverUrl, token, slug, deps);
+        return [{ path: 'SKILL.md', content: body }];
+    }
+    if (!res.ok) {
+        throw new Error(`Couldn't fetch skill "${slug}": ${httpErrorMessage(res.status)}`);
+    }
+    const data = (await res.json());
+    return data.files;
+}
+/**
+ * Resolve a skill-relative file path to an absolute path INSIDE the skill dir,
+ * rejecting anything that would escape it (absolute paths or `..` traversal) so a
+ * malicious manifest can never write outside `<skillsDir>/<slug>/`.
+ */
+function resolveSkillFilePath(skillDir, relPath) {
+    if (path.isAbsolute(relPath)) {
+        throw new Error(`Unsafe skill file path (absolute path not allowed): ${relPath}`);
+    }
+    const dest = path.resolve(skillDir, relPath);
+    const rel = path.relative(skillDir, dest);
+    if (rel === '' || rel === '..' || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel)) {
+        throw new Error(`Unsafe skill file path (escapes the skill directory): ${relPath}`);
+    }
+    return dest;
+}
+/**
+ * Write a skill's full file tree under `<skillsDir>/<slug>/`, preserving each
+ * file's relative path (e.g. `references/x.md`) and creating directories. Every
+ * path is validated up-front, so a malicious manifest aborts before any write.
+ * Returns the written absolute file paths.
+ */
+export function writeSkillTree(skillsDir, slug, files) {
+    const skillDir = path.join(skillsDir, slug);
+    // Validate the WHOLE tree before touching disk (atomic-ish: reject as a unit).
+    const planned = files.map((file) => ({
+        dest: resolveSkillFilePath(skillDir, file.path),
+        content: file.content,
+    }));
+    const written = [];
+    for (const { dest, content } of planned) {
+        fs.mkdirSync(path.dirname(dest), { recursive: true });
+        fs.writeFileSync(dest, content, 'utf8');
+        written.push(dest);
+    }
+    return written;
+}
+/** Write `<skillsDir>/<slug>/SKILL.md`, creating dirs. Returns the file path. */
+export function writeSkill(skillsDir, slug, body) {
+    return writeSkillTree(skillsDir, slug, [{ path: 'SKILL.md', content: body }])[0];
+}
+/**
+ * Resolve which slugs to install from the available catalog. `all` wins; else
+ * an explicit `skills` list filtered to (and ordered by) the catalog; else [].
+ *
+ * `allowedSkills` is a forward-compat seam: when a future login step restricts a
+ * user to a subset of skills, pass it here and selection is clamped to that set
+ * before `all`/`skills` apply. `undefined` (the default) means every skill the
+ * server returned is allowed; `[]` means none are.
+ */
+export function selectSkills(available, opts) {
+    let slugs = available.map((s) => s.slug);
+    if (opts.allowedSkills !== undefined) {
+        const allowed = new Set(opts.allowedSkills);
+        slugs = slugs.filter((s) => allowed.has(s));
+    }
+    if (opts.all)
+        return slugs;
+    if (opts.skills && opts.skills.length > 0) {
+        const wanted = new Set(opts.skills);
+        return slugs.filter((s) => wanted.has(s));
+    }
+    return [];
+}
+/** `GET /healthz` → true if reachable and 2xx, false otherwise (never throws). */
+export async function checkHealth(serverUrl, deps) {
+    try {
+        const f = resolveFetch(deps);
+        const res = await f(`${baseUrl(serverUrl)}/healthz`);
+        return res.ok;
+    }
+    catch {
+        return false;
+    }
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@reeledge/agent-tools",
+  "version": "0.1.2",
+  "private": false,
+  "description": "Reel Edge agent-tools installer CLI — installs/updates the Reel Edge MCP connector + skills for Claude Code / Codex / Droid.",
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "agent-tools": "dist/index.js"
+  },
+  "files": [
+    "dist/**/*.js"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@inquirer/checkbox": "^5.2.1"
+  },
+  "devDependencies": {
+    "@types/node": "^26.0.0",
+    "tsx": "^4.22.4",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.9"
+  }
+}