@equipt/cli 0.1.0

package/README.md

@@ -0,0 +1,16 @@
+# @equipt/cli
+
+Install curated [Equipt](https://github.com/Salah-XD/equipt) skills & agents into your project's `.claude/`.
+
+```bash
+npx @equipt/cli init                     # scaffold ./.claude + equipt.json (interactive in a terminal)
+npx @equipt/cli add equipt-engineering   # install a whole plugin
+npx @equipt/cli add code-reviewer        # install a single skill/agent
+npx @equipt/cli list                     # browse the catalog (with Readiness + tier)
+```
+
+Run in a terminal, `init` opens an interactive plugin picker, and `add` asks before overwriting an existing file. In non-interactive contexts (CI, pipes) it stays quiet — `init` just scaffolds and `add` skips conflicts unless you pass `--force`.
+
+Flags: `--global` (target `~/.claude`), `--force` (overwrite without asking), `--from <path>` (use a local Equipt checkout), `--plugin <name>` (scope `list`), `--yes` (non-interactive `init`).
+
+> While the Equipt repo is private, the GitHub source is unavailable — pass `--from <path-to-equipt-checkout>` to install from a local clone.

package/bin/equipt.mjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { run } from '../src/cli.mjs';
+run().then((code) => { process.exitCode = code ?? 0; });

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@equipt/cli",
+  "version": "0.1.0",
+  "description": "Install curated Equipt skills & agents into your project.",
+  "type": "module",
+  "bin": {
+    "equipt": "./bin/equipt.mjs"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test \"test/**/*.test.mjs\""
+  },
+  "keywords": [
+    "equipt",
+    "claude",
+    "claude-code",
+    "skills",
+    "agents",
+    "ai",
+    "cli",
+    "marketplace"
+  ],
+  "author": "Salah-XD",
+  "license": "MIT",
+  "homepage": "https://equipt-agent.vercel.app",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Salah-XD/equipt.git",
+    "directory": "cli"
+  },
+  "bugs": {
+    "url": "https://github.com/Salah-XD/equipt/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.5.1",
+    "commander": "^15.0.0",
+    "picocolors": "^1.1.1",
+    "tar": "^7.4.3"
+  }
+}

package/src/cli.mjs

@@ -0,0 +1,169 @@
+import { Command, CommanderError } from 'commander';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { join, dirname } from 'node:path';
+import * as clack from '@clack/prompts';
+import { init } from './commands/init.mjs';
+import { add } from './commands/add.mjs';
+import { list } from './commands/list.mjs';
+import { resolveSource, SourceError } from './lib/source.mjs';
+import { loadCatalog } from './lib/catalog.mjs';
+import { pc, tierColor, statusColor, kindLabel } from './lib/log.mjs';
+
+const VERSION = JSON.parse(
+  readFileSync(join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json'), 'utf8'),
+).version;
+
+// Interactive only when attached to a real terminal and not explicitly opted out.
+const isInteractive = (opts) => Boolean(process.stdout.isTTY) && !opts.yes;
+
+async function runInit(opts) {
+  const { targetDir } = await init({ global: opts.global });
+
+  if (!isInteractive(opts)) {
+    console.log(pc.green(`Initialized Equipt in ${targetDir}`));
+    return 0;
+  }
+
+  clack.intro(pc.bold('equipt'));
+  let catalog;
+  try {
+    const { dir } = await resolveSource({ from: opts.from });
+    catalog = await loadCatalog(dir);
+  } catch (err) {
+    clack.note(err instanceof SourceError ? err.message : String(err), 'Source unavailable');
+    clack.outro(`Initialized ${targetDir} (no plugins installed).`);
+    return 0;
+  }
+
+  const counts = {};
+  for (const a of catalog.assets) counts[a.plugin] = (counts[a.plugin] ?? 0) + 1;
+  const picks = await clack.multiselect({
+    message: 'Install which plugins? (space to toggle, enter to confirm)',
+    options: catalog.plugins.map((p) => ({ value: p, label: p, hint: `${counts[p] ?? 0} assets` })),
+    required: false,
+  });
+  if (clack.isCancel(picks)) {
+    clack.cancel('Cancelled.');
+    return 0;
+  }
+  for (const p of picks) {
+    const out = await add(p, { global: opts.global, from: opts.from, force: true });
+    clack.log.success(`${p} — ${out.results.length} assets`);
+  }
+  clack.outro(pc.green(`Equipt ready in ${targetDir}`));
+  return 0;
+}
+
+async function runAdd(target, opts) {
+  if (!target) {
+    console.error('usage: equipt add <plugin|name>');
+    return 1;
+  }
+  const shouldOverwrite =
+    isInteractive(opts) && !opts.force
+      ? async (asset) => {
+          const r = await clack.confirm({ message: `Overwrite ${asset.name}?`, initialValue: false });
+          return !clack.isCancel(r) && r === true;
+        }
+      : undefined;
+
+  const out = await add(target, {
+    global: opts.global,
+    force: opts.force,
+    from: opts.from,
+    shouldOverwrite,
+  });
+  if (out.error) {
+    console.error(pc.red(out.error));
+    return 1;
+  }
+  for (const r of out.results) {
+    console.log(`  ${statusColor(r.status)} ${kindLabel(r.kind)} ${r.name}`);
+  }
+  console.log(pc.dim(`Done → ${out.targetDir}`));
+  return 0;
+}
+
+async function runList(opts) {
+  const out = await list({ plugin: opts.plugin, from: opts.from });
+  for (const a of out.assets) {
+    const score =
+      a.readiness != null ? `  ${pc.dim(`R${a.readiness}`)} ${tierColor(a.tier)}` : '';
+    console.log(`  ${kindLabel(a.kind)}  ${pc.bold(`${a.plugin}/${a.name}`)}${score}`);
+  }
+  return 0;
+}
+
+function buildProgram(setCode) {
+  const program = new Command();
+  program
+    .name('equipt')
+    .description('Install curated Equipt skills & agents into your project.')
+    .version(VERSION, '-v, --version');
+
+  program
+    .command('init')
+    .description('scaffold ./.claude + equipt.json (interactive when run in a terminal)')
+    .option('--global', 'target ~/.claude instead of ./.claude')
+    .option('--from <path>', 'use a local Equipt checkout instead of GitHub')
+    .option('--yes', 'non-interactive (just scaffold)')
+    .action(async (opts) => {
+      const code = await runInit(opts);
+      if (code) setCode(code);
+    });
+
+  program
+    .command('add')
+    .description('install a plugin or a single asset')
+    .argument('[target]', 'plugin name or asset name')
+    .option('--global', 'target ~/.claude instead of ./.claude')
+    .option('--force', 'overwrite existing files without asking')
+    .option('--from <path>', 'use a local Equipt checkout instead of GitHub')
+    .action(async (target, opts) => {
+      const code = await runAdd(target, opts);
+      if (code) setCode(code);
+    });
+
+  program
+    .command('list')
+    .description('list available assets with Readiness + tier')
+    .option('--plugin <name>', 'scope to one plugin')
+    .option('--from <path>', 'use a local Equipt checkout instead of GitHub')
+    .action(async (opts) => {
+      const code = await runList(opts);
+      if (code) setCode(code);
+    });
+
+  return program;
+}
+
+export async function run(argv = process.argv.slice(2)) {
+  let code = 0;
+  const program = buildProgram((c) => {
+    code = c;
+  });
+  program.exitOverride();
+  program.configureOutput({ writeOut: (s) => process.stdout.write(s), writeErr: (s) => process.stderr.write(s) });
+
+  if (argv.length === 0) {
+    program.outputHelp();
+    return 1;
+  }
+
+  try {
+    await program.parseAsync(argv, { from: 'user' });
+  } catch (err) {
+    if (err instanceof SourceError) {
+      console.error(pc.red(err.message));
+      return 2;
+    }
+    if (err instanceof CommanderError) {
+      if (['commander.helpDisplayed', 'commander.help', 'commander.version'].includes(err.code)) return 0;
+      return err.exitCode ?? 1;
+    }
+    console.error(err?.stack || String(err));
+    return 1;
+  }
+  return code;
+}

package/src/commands/add.mjs

@@ -0,0 +1,29 @@
+import { resolveSource } from '../lib/source.mjs';
+import { loadCatalog, resolveTarget } from '../lib/catalog.mjs';
+import { resolveTargetDir } from '../lib/paths.mjs';
+import { installAsset } from '../lib/install.mjs';
+import { readManifest, writeManifest } from '../lib/manifest.mjs';
+
+export async function add(query, { global = false, force = false, from, cwd = process.cwd(), shouldOverwrite } = {}) {
+  if (!query) return { error: 'usage: equipt add <plugin|name>' };
+
+  const { dir } = await resolveSource({ from, cwd });
+  const catalog = await loadCatalog(dir);
+  const r = resolveTarget(catalog, query);
+
+  if (r.kind === 'none') return { error: `no plugin or asset named "${query}". Try: equipt list` };
+  if (r.kind === 'ambiguous') return { error: `"${query}" is ambiguous: ${r.matches.join(', ')}. Qualify as <plugin>/<name>.` };
+
+  const targetDir = resolveTargetDir({ global, cwd });
+  const manifest = await readManifest(targetDir);
+  const results = [];
+  for (const asset of r.matches) {
+    const res = await installAsset(asset, { targetDir, force, shouldOverwrite });
+    if (res.status !== 'skipped') {
+      manifest.installed[asset.name] = { plugin: asset.plugin, kind: asset.kind, addedAt: new Date().toISOString() };
+    }
+    results.push({ name: asset.name, kind: asset.kind, status: res.status });
+  }
+  await writeManifest(targetDir, manifest);
+  return { targetDir, results };
+}

package/src/commands/init.mjs

@@ -0,0 +1,12 @@
+import { mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { resolveTargetDir } from '../lib/paths.mjs';
+import { readManifest, writeManifest } from '../lib/manifest.mjs';
+
+export async function init({ global = false, cwd = process.cwd() } = {}) {
+  const targetDir = resolveTargetDir({ global, cwd });
+  await mkdir(join(targetDir, 'skills'), { recursive: true });
+  await mkdir(join(targetDir, 'agents'), { recursive: true });
+  await writeManifest(targetDir, await readManifest(targetDir));
+  return { targetDir };
+}

package/src/commands/list.mjs

@@ -0,0 +1,9 @@
+import { resolveSource } from '../lib/source.mjs';
+import { loadCatalog } from '../lib/catalog.mjs';
+
+export async function list({ plugin, from, cwd = process.cwd() } = {}) {
+  const { dir } = await resolveSource({ from, cwd });
+  const catalog = await loadCatalog(dir);
+  const assets = plugin ? catalog.assets.filter((a) => a.plugin === plugin) : catalog.assets;
+  return { plugins: catalog.plugins, assets };
+}

package/src/lib/catalog.mjs

@@ -0,0 +1,72 @@
+import { readdir, readFile } from 'node:fs/promises';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+function nameFromFrontmatter(file, fallback) {
+  try {
+    const fm = readFileSync(file, 'utf8').match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    if (fm) {
+      const nm = fm[1].match(/^name:\s*["']?(.+?)["']?\s*$/m);
+      if (nm) return nm[1].trim();
+    }
+  } catch {}
+  return fallback;
+}
+
+async function safeReaddir(dir) {
+  try { return await readdir(dir, { withFileTypes: true }); }
+  catch (err) { if (err.code === 'ENOENT') return []; throw err; }
+}
+
+export async function loadCatalog(sourceDir) {
+  const pluginsDir = join(sourceDir, 'plugins');
+  let plugins = [];
+  try {
+    const cfg = JSON.parse(await readFile(join(sourceDir, 'plugins.config.json'), 'utf8'));
+    plugins = Object.keys(cfg.plugins ?? {});
+  } catch {
+    plugins = (await safeReaddir(pluginsDir)).filter((e) => e.isDirectory()).map((e) => e.name);
+  }
+
+  const assets = [];
+  for (const plugin of plugins) {
+    const skillsBase = join(pluginsDir, plugin, 'skills');
+    for (const e of await safeReaddir(skillsBase)) {
+      if (!e.isDirectory()) continue;
+      const src = join(skillsBase, e.name);
+      assets.push({ plugin, name: nameFromFrontmatter(join(src, 'SKILL.md'), e.name), kind: 'skill', src });
+    }
+    const agentsBase = join(pluginsDir, plugin, 'agents');
+    for (const e of await safeReaddir(agentsBase)) {
+      if (!e.isFile() || !e.name.endsWith('.md') || e.name === 'README.md') continue;
+      const src = join(agentsBase, e.name);
+      assets.push({ plugin, name: nameFromFrontmatter(src, e.name.replace(/\.md$/, '')), kind: 'agent', src });
+    }
+  }
+
+  try {
+    const idx = JSON.parse(await readFile(join(sourceDir, 'scores', 'index.json'), 'utf8'));
+    const byKey = new Map(idx.assets.map((a) => [`${a.plugin}/${a.name}`, a]));
+    for (const a of assets) {
+      const s = byKey.get(`${a.plugin}/${a.name}`);
+      if (s) { a.readiness = s.readiness; a.tier = s.tier; }
+    }
+  } catch {}
+
+  return { plugins, assets };
+}
+
+export function resolveTarget(catalog, query) {
+  if (query.includes('/')) {
+    const [p, n] = query.split('/');
+    const m = catalog.assets.filter((a) => a.plugin === p && a.name === n);
+    return m.length ? { kind: 'asset', matches: m } : { kind: 'none', matches: [] };
+  }
+  if (catalog.plugins.includes(query)) {
+    return { kind: 'plugin', matches: catalog.assets.filter((a) => a.plugin === query) };
+  }
+  const named = catalog.assets.filter((a) => a.name === query);
+  if (named.length === 1) return { kind: 'asset', matches: named };
+  if (named.length > 1) return { kind: 'ambiguous', matches: named.map((a) => `${a.plugin}/${a.name}`) };
+  return { kind: 'none', matches: [] };
+}

package/src/lib/install.mjs

@@ -0,0 +1,19 @@
+import { cp, mkdir, access } from 'node:fs/promises';
+import { join } from 'node:path';
+
+async function exists(p) { try { await access(p); return true; } catch { return false; } }
+
+export async function installAsset(asset, { targetDir, force = false, shouldOverwrite }) {
+  const parent = join(targetDir, asset.kind === 'skill' ? 'skills' : 'agents');
+  const dest = asset.kind === 'skill' ? join(parent, asset.name) : join(parent, `${asset.name}.md`);
+
+  const already = await exists(dest);
+  if (already && !force) {
+    // Non-interactive (no callback) preserves the original behavior: skip.
+    if (!shouldOverwrite || !(await shouldOverwrite(asset))) return { status: 'skipped', dest };
+  }
+
+  await mkdir(parent, { recursive: true });
+  await cp(asset.src, dest, { recursive: true, force: true });
+  return { status: already ? 'overwritten' : 'installed', dest };
+}

package/src/lib/log.mjs

@@ -0,0 +1,22 @@
+import pc from 'picocolors';
+
+// picocolors auto-disables when stdout is not a TTY or NO_COLOR is set,
+// so these are safe to use unconditionally (no manual stripping needed).
+export { pc };
+
+export function tierColor(tier) {
+  if (tier === 'field-ready') return pc.green('field-ready');
+  if (tier === 'certified') return pc.yellow('certified');
+  return pc.dim(tier || 'provisional');
+}
+
+export function statusColor(status) {
+  const label = status.padEnd(11);
+  if (status === 'installed') return pc.green(label);
+  if (status === 'overwritten') return pc.yellow(label);
+  return pc.dim(label);
+}
+
+export function kindLabel(kind) {
+  return kind === 'skill' ? pc.cyan('skill') : pc.magenta('agent');
+}

package/src/lib/manifest.mjs

@@ -0,0 +1,23 @@
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+
+const SOURCE = 'Salah-XD/equipt';
+
+export function defaultManifest() {
+  return { source: SOURCE, installed: {} };
+}
+
+export async function readManifest(targetDir) {
+  try {
+    const m = JSON.parse(await readFile(join(targetDir, 'equipt.json'), 'utf8'));
+    return { source: m.source ?? SOURCE, installed: m.installed ?? {} };
+  } catch (err) {
+    if (err.code === 'ENOENT') return defaultManifest();
+    throw err;
+  }
+}
+
+export async function writeManifest(targetDir, manifest) {
+  await mkdir(targetDir, { recursive: true });
+  await writeFile(join(targetDir, 'equipt.json'), JSON.stringify(manifest, null, 2) + '\n');
+}

package/src/lib/paths.mjs

@@ -0,0 +1,6 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+export function resolveTargetDir({ global = false, cwd = process.cwd() } = {}) {
+  return global ? join(homedir(), '.claude') : join(cwd, '.claude');
+}

package/src/lib/source.mjs

@@ -0,0 +1,51 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { readFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { tmpdir } from 'node:os';
+import { x } from 'tar';
+
+export class SourceError extends Error {}
+
+export function findLocalSource(cwd) {
+  let dir = cwd;
+  for (let i = 0; i < 12; i++) {
+    try { readFileSync(join(dir, 'plugins.config.json')); return dir; } catch {}
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+export async function extractTarball(tgzPath, destDir) {
+  await mkdir(destDir, { recursive: true });
+  await x({ file: tgzPath, cwd: destDir, strip: 1 });
+  return destDir;
+}
+
+async function defaultDownload(url) {
+  const res = await fetch(url);
+  if (!res.ok) throw new Error(`HTTP ${res.status}`);
+  return Buffer.from(await res.arrayBuffer());
+}
+
+export async function resolveSource({ from, cwd = process.cwd(), ref = 'main', download = defaultDownload } = {}) {
+  if (from) return { dir: from, cleanup: async () => {} };
+  const local = findLocalSource(cwd);
+  if (local) return { dir: local, cleanup: async () => {} };
+
+  const url = `https://codeload.github.com/Salah-XD/equipt/tar.gz/refs/heads/${ref}`;
+  let buf;
+  try { buf = await download(url); }
+  catch (err) {
+    throw new SourceError(
+      `Could not download Equipt from GitHub (${err.message}). The repo may be private — pass --from <path> to a local checkout.`,
+    );
+  }
+  const tgz = join(tmpdir(), `equipt-${ref}.tgz`);
+  await mkdir(dirname(tgz), { recursive: true });
+  await writeFile(tgz, buf);
+  const dir = join(tmpdir(), 'equipt-cli', ref);
+  await extractTarball(tgz, dir);
+  return { dir, cleanup: async () => {} };
+}