0101-agents 0.1.7 → 0.2.0

package/bin/cli.js

@@ -1,12 +1,14 @@
 #!/usr/bin/env node
-// 0101-agents CLI — installs and updates curated Claude Code agents.
+// 0101-agents CLI — installs and updates 0101 skillsets and agent templates.
 //
 // Commands:
 //   0101-agents login [<license-key>]
 //   0101-agents logout
 //   0101-agents whoami
-//   0101-agents install <agent> [--force]
-//   0101-agents update <agent> [-f]
+//   0101-agents install <set> --to <agent>      install a skillset into an agent
+//   0101-agents install base --as <name>        create a new agent from the base template
+//   0101-agents update  <set> --to <agent>      update a skillset inside an agent
+//   0101-agents update  <agent> [-f]            update an agent's template (preserves data/)
 //   0101-agents list
 //   0101-agents help
 
@@ -81,9 +83,14 @@ async function fetchManifest(agent) {
   if (res.status === 401) die('License invalid. Run: 0101-agents login')
   if (res.status === 403) {
     const body = await res.json().catch(() => ({}))
-    die(body.error || 'License does not cover this agent.')
+    die((body.error || 'License does not cover this artifact.') +
+        '\n  Skillsets must be added to your account first: https://0101.fyi/catalog')
+  }
+  if (res.status === 404) {
+    die(`Not found: ${agent}\n` +
+        '  Available skillsets: https://0101.fyi/catalog\n' +
+        '  New agent: 0101-agents install base --as <name>')
   }
-  if (res.status === 404) die(`Agent not found: ${agent}`)
   if (!res.ok) die(`Manifest fetch failed: ${res.status} ${res.statusText}`)
   return res.json()
 }
@@ -199,6 +206,138 @@ async function prompt(question) {
   try { return (await rl.question(question)).trim() } finally { rl.close() }
 }
 
+// ─── sets ────────────────────────────────────────────────────────────────────
+
+function getFlag(args, name) {
+  const i = args.indexOf(name)
+  return i !== -1 && args[i + 1] && !args[i + 1].startsWith('-') ? args[i + 1] : null
+}
+
+// Per-agent record of installed sets: ~/0101/<agent>/.0101-sets.json
+// { "<set-slug>": { "version": "0.0.2", "skills": ["ad-creative", ...] } }
+// (Older entries may be plain version strings — normalized on read.)
+function readSetsFile(agent) {
+  try {
+    const raw = JSON.parse(readFileSync(join(agentInstallDir(agent), '.0101-sets.json'), 'utf8'))
+    for (const [k, v] of Object.entries(raw)) {
+      if (typeof v === 'string') raw[k] = { version: v, skills: [] }
+    }
+    return raw
+  } catch {
+    return {}
+  }
+}
+
+function setVersion(sets, slug) {
+  return sets[slug]?.version ?? null
+}
+
+function writeSetsFile(agent, sets) {
+  writeFileSync(
+    join(agentInstallDir(agent), '.0101-sets.json'),
+    JSON.stringify(sets, null, 2) + '\n',
+  )
+}
+
+// Fetch a set artifact and install its skills into the agent's .claude/skills/.
+//
+// Safety model:
+// - Each skillset OWNS the skill folders it shipped (recorded per-set in
+//   .0101-sets.json). On install/update those folders are clean-replaced
+//   (delete + copy), so files removed upstream don't linger.
+// - Skill folders the set DOESN'T ship are never touched — the agent's own
+//   skills and other skillsets are safe.
+// - Name collision (a folder exists that this set didn't previously own,
+//   e.g. a hand-made skill with the same name): backed up to
+//   ~/0101/.backups/ first, then replaced, with a warning.
+// - A skill the set used to ship but no longer does is removed (it was ours).
+async function installSetInto(setSlug, agent) {
+  const agentDir = agentInstallDir(agent)
+  if (!existsSync(agentDir)) {
+    die(`${agent} is not installed at ${agentDir}.\n` +
+        `  Create it first: 0101-agents install base --as ${agent}`)
+  }
+
+  const manifest = await fetchManifest(setSlug)
+  const zipPath = join(tmpdir(), `0101-set-${setSlug}-${manifest.latest}.zip`)
+  await downloadZip(manifest.download_url, zipPath)
+
+  const tmpDir = join(tmpdir(), `0101-set-${setSlug}-${Date.now()}`)
+  unzipInto(zipPath, tmpDir)
+  rmSync(zipPath, { force: true })
+
+  const skillsSrc = join(tmpDir, '.claude', 'skills')
+  if (!existsSync(skillsSrc)) {
+    rmSync(tmpDir, { recursive: true, force: true })
+    die(`${setSlug} is not a skillset (no .claude/skills/ in the artifact).`)
+  }
+
+  const newSkills = readdirSync(skillsSrc)
+    .filter(d => statSync(join(skillsSrc, d)).isDirectory())
+  const skillsDest = join(agentDir, '.claude', 'skills')
+  mkdirSync(skillsDest, { recursive: true })
+
+  const sets = readSetsFile(agent)
+  const prevSkills = sets[setSlug]?.skills ?? []
+
+  // Collisions: folders that exist but weren't shipped by this set before.
+  const foreign = newSkills.filter(
+    s => existsSync(join(skillsDest, s)) && !prevSkills.includes(s),
+  )
+  // Skills this set used to ship but no longer does (removed upstream).
+  const dropped = prevSkills.filter(
+    s => !newSkills.includes(s) && existsSync(join(skillsDest, s)),
+  )
+  // Back up anything we're about to replace-with-different or delete, so a
+  // hand-made collision or an upstream removal is always recoverable.
+  const toBackup = [...foreign, ...dropped]
+  if (toBackup.length) {
+    mkdirSync(BACKUPS_DIR, { recursive: true })
+    const ts = new Date().toISOString().replace(/[:.]/g, '-')
+    const backupPath = join(BACKUPS_DIR, `${agent}-skills-${ts}.tar.gz`)
+    execSync(
+      `tar -czf "${backupPath}" -C "${skillsDest}" ${toBackup.map(s => `"${s}"`).join(' ')}`,
+      { stdio: 'inherit' },
+    )
+    if (foreign.length) {
+      console.log(dim(`  ⚠ Replacing existing skill(s) ${foreign.join(', ')} ` +
+                      `(backed up → ${backupPath})`))
+    }
+    if (dropped.length) {
+      console.log(dim(`  Backup of removed skill(s) → ${backupPath}`))
+    }
+  }
+
+  // Clean-replace every skill this set ships.
+  for (const s of newSkills) {
+    rmSync(join(skillsDest, s), { recursive: true, force: true })
+    execSync(`cp -R "${join(skillsSrc, s)}" "${join(skillsDest, s)}"`)
+  }
+  // Remove skills this set used to ship but no longer does.
+  for (const s of prevSkills.filter(s => !newSkills.includes(s))) {
+    rmSync(join(skillsDest, s), { recursive: true, force: true })
+    console.log(dim(`  − removed ${s} (no longer part of ${setSlug})`))
+  }
+  rmSync(tmpDir, { recursive: true, force: true })
+
+  sets[setSlug] = { version: manifest.latest, skills: newSkills }
+  writeSetsFile(agent, sets)
+  return manifest.latest
+}
+
+// The 0101 agent manages itself (its own update skill) and is downloaded from
+// the website — it is deliberately NOT installable or updatable via this CLI,
+// so there's exactly one update mechanism per artifact.
+const SELF_MANAGED = new Set(['0101'])
+
+function rejectSelfManaged(agent, action) {
+  if (SELF_MANAGED.has(agent)) {
+    die(`The 0101 agent manages itself — it can't be ${action} via this CLI.\n` +
+        `  Download it at https://0101.fyi and open the folder in Claude Code;\n` +
+        `  it updates itself from inside.`)
+  }
+}
+
 // ─── commands ────────────────────────────────────────────────────────────────
 
 async function cmdLogin(args) {
@@ -230,21 +369,44 @@ async function cmdWhoami() {
 }
 
 async function cmdInstall(args) {
-  const agent = args[0]
-  if (!agent) die('Usage: 0101-agents install <agent> [--force]')
+  const slug = args[0] && !args[0].startsWith('-') ? args[0] : null
+  if (!slug) {
+    die('Usage: 0101-agents install <set> --to <agent>\n' +
+        '       0101-agents install base --as <name>')
+  }
+  rejectSelfManaged(slug, 'installed')
+  ensureUnzipAvailable()
+
+  // ── set into an existing agent ──
+  const to = getFlag(args, '--to')
+  if (to) {
+    info(`Installing set ${slug} into ${to}…`)
+    const v = await installSetInto(slug, to)
+    console.log('')
+    ok(`Set ${bold(slug)} ${v} → ${to}`)
+    info('New skills load at the agent’s next session start.')
+    return
+  }
+
+  // ── whole artifact: the base template (named via --as) or a legacy slug ──
+  const as = getFlag(args, '--as')
+  if (slug === 'base' && !as) {
+    die('The base template needs a name for the new agent:\n' +
+        '  0101-agents install base --as <name>')
+  }
+  const destName = as || slug
   const force = args.includes('--force')
 
-  ensureUnzipAvailable()
-  const installDir = agentInstallDir(agent)
+  const installDir = agentInstallDir(destName)
   if (existsSync(installDir) && !force) {
     die(`${installDir} already exists. Use --force to overwrite (will wipe data/).`)
   }
 
-  info(`Fetching manifest for ${agent}…`)
-  const manifest = await fetchManifest(agent)
+  info(`Fetching manifest for ${slug}…`)
+  const manifest = await fetchManifest(slug)
   info(`Latest: ${manifest.latest}`)
 
-  const zipPath = join(tmpdir(), `0101-${agent}-${manifest.latest}.zip`)
+  const zipPath = join(tmpdir(), `0101-${slug}-${manifest.latest}.zip`)
   info(`Downloading…`)
   await downloadZip(manifest.download_url, zipPath)
 
@@ -254,32 +416,75 @@ async function cmdInstall(args) {
   mkdirSync(installDir, { recursive: true })
   unzipInto(zipPath, installDir)
   rmSync(zipPath, { force: true })
-  const localManifest = readManifest(agent)
-  runPostInstall(agent, localManifest)
-  writeInstalledVersion(agent, manifest.latest)
+  const localManifest = readManifest(destName)
+  runPostInstall(destName, localManifest)
+  writeInstalledVersion(destName, manifest.latest)
 
   console.log('')
-  ok(`Installed ${bold(agent)} ${manifest.latest} → ${installDir}`)
-  info(`Start: 0101-agents start ${agent}`)
-  // The "open in Claude" hint only applies to agent folders. Artifacts with a
-  // custom launch (manifest.start, e.g. the runner) aren't opened in Claude.
-  if (!localManifest.start) info(`   or: cd ${installDir} && claude`)
+  ok(`Installed ${bold(destName)} ${manifest.latest} → ${installDir}`)
+  info(`Open it: cd ${installDir} && claude`)
+  if (as) info(`Add capabilities: 0101-agents install <set> --to ${destName}`)
 }
 
 async function cmdUpdate(args) {
-  const agent = args.find((a) => !a.startsWith('-'))
+  const slug = args[0] && !args[0].startsWith('-') ? args[0] : null
   const assumeYes = args.some((a) => ['-f', '--force', '-y', '--yes'].includes(a))
-  if (!agent) die('Usage: 0101-agents update <agent> [-f]')
-
+  if (!slug) {
+    die('Usage: 0101-agents update <set> --to <agent>\n' +
+        '       0101-agents update <agent> [-f]')
+  }
+  rejectSelfManaged(slug, 'updated')
   ensureUnzipAvailable()
+
+  // ── set inside an agent ──
+  const to = getFlag(args, '--to')
+  if (to) {
+    const sets = readSetsFile(to)
+    const current = setVersion(sets, slug)
+    if (!current) {
+      die(`${slug} is not installed in ${to}.\n` +
+          `  Install it: 0101-agents install ${slug} --to ${to}`)
+    }
+    info(`Installed: ${current}`)
+    const manifest = await fetchManifest(slug)
+    info(`Latest:    ${manifest.latest}`)
+    if (current === manifest.latest) {
+      ok('Already up to date.')
+      return
+    }
+    const v = await installSetInto(slug, to)
+    console.log('')
+    ok(`Updated set ${bold(slug)} ${current} → ${v} in ${to}`)
+    info('Updated skills load at the agent’s next session start.')
+    return
+  }
+
+  // ── whole agent: update its template, preserving data/ ──
+  // The remote slug comes from the installed manifest.json (a base-template
+  // agent named "ada" still updates from the "base" artifact). Falls back to
+  // the folder name for legacy installs.
+  //
+  // Discontinued persona agents migrate onto the base template on their next
+  // update: data/ (all memory) is preserved as always, the persona CLAUDE.md
+  // is replaced by the base skeleton, and the agent re-introduces itself in
+  // its next conversation. After migration the folder's manifest says "base",
+  // so every later update is a normal base update.
+  const LEGACY_TO_BASE = new Set(['marketer', 'developer', 'assistant', 'custom'])
+  const agent = slug
   const installDir = agentInstallDir(agent)
-  if (!existsSync(installDir)) die(`${agent} is not installed. Try: 0101-agents install ${agent}`)
+  if (!existsSync(installDir)) die(`${agent} is not installed.`)
+  let remoteSlug = readManifest(agent)?.name || agent
+  if (LEGACY_TO_BASE.has(remoteSlug)) {
+    info(`${remoteSlug} is discontinued — migrating ${agent} to the base template.`)
+    info('All memory (data/) is preserved; the agent re-introduces itself next chat.')
+    remoteSlug = 'base'
+  }
 
   const current = installedVersion(agent)
-  info(`Installed: ${current ?? 'unknown'}`)
+  info(`Installed: ${current ?? 'unknown'} (template: ${remoteSlug})`)
 
   info(`Fetching manifest…`)
-  const manifest = await fetchManifest(agent)
+  const manifest = await fetchManifest(remoteSlug)
   info(`Latest:    ${manifest.latest}`)
 
   if (current === manifest.latest) {
@@ -319,72 +524,75 @@ function cmdList() {
   const installed = listInstalled()
   if (installed.length === 0) {
     info('No agents installed.')
-    info(`Install one: 0101-agents install <name>`)
+    info(`Create one: 0101-agents install base --as <name>`)
     return
   }
   for (const name of installed) {
     const v = installedVersion(name) ?? dim('?')
     console.log(`  ${bold(name)} ${dim(v)}`)
+    const sets = readSetsFile(name)
+    for (const [set, rec] of Object.entries(sets)) {
+      console.log(`    ${dim('· skillset')} ${set} ${dim(rec.version)}`)
+    }
   }
 }
 
 async function cmdStart(args) {
   const agent = args[0]
-  if (!agent) die('Usage: 0101-agents start <agent> [-- <claude-args>]')
+  if (!agent) die('Usage: 0101-agents start <agent> [--tg] [-- <claude-args>]')
   const dir = agentInstallDir(agent)
   if (!existsSync(dir)) {
-    die(`${agent} is not installed. Try: 0101-agents install ${agent}`)
+    die(`${agent} is not installed.`)
   }
 
-  // Best-effort update check. Silently skipped if offline or the server
-  // misbehaves — never blocks the launch.
+  // Best-effort update nag. Needs a saved key (the releases API is gated);
+  // no key, offline, or any non-200 (revoked, lapsed, artifact not on the
+  // server) → skip silently. Launching NEVER depends on this — deliberately
+  // not fetchManifest(), whose die() on HTTP errors would kill the launch.
   try {
-    const manifest = await fetchManifest(agent)
-    const current = installedVersion(agent)
-    if (current && manifest.latest !== current) {
-      console.log(
-        dim(`⚠ ${agent} ${manifest.latest} available (run: 0101-agents update ${agent})`),
-      )
+    const key = readConfig().license_key
+    if (key) {
+      const remoteSlug = readManifest(agent)?.name || agent
+      const res = await fetch(`${apiBase()}/api/releases/${encodeURIComponent(remoteSlug)}`, {
+        headers: { Authorization: `Bearer ${key}` },
+      })
+      if (res.ok) {
+        const manifest = await res.json()
+        const current = installedVersion(agent)
+        if (current && manifest.latest !== current) {
+          console.log(
+            dim(`⚠ ${agent} ${manifest.latest} available (run: 0101-agents update ${agent})`),
+          )
+        }
+      }
     }
   } catch {
     // ignore
   }
 
   // Artifacts can declare how `start` launches via manifest.start. The runner
-  // sets "npm start"; agents leave it unset and fall through to launching
-  // Claude Code below.
-  //
-  // For the runner specifically we accept an optional `[slug] [cli]` so
-  // power users can run multiple bots in parallel terminals without touching
-  // .env. The runner derives STATE_DIR from AGENT_DIR, so per-agent state is
-  // automatic — we only need to override AGENT_DIR here.
+  // (fallback engine) sets "npm start"; agents leave it unset and fall through
+  // to launching Claude Code below.
   //
   //   start runner                    → npm start                  (Telegram, AGENT_DIR from .env)
-  //   start runner cli                → npm start -- --cli         (CLI, AGENT_DIR from .env)
-  //   start runner marketer           → npm start                  (Telegram, AGENT_DIR=~/0101/marketer)
-  //   start runner marketer cli       → npm start -- --cli         (CLI, AGENT_DIR=~/0101/marketer)
-  //   start runner --cli              → same as `start runner cli` (long-form flag)
-  //   start runner -- --cli           → same                        (explicit separator)
+  //   start runner cli                → npm start -- --cli         (CLI chat, AGENT_DIR from .env)
+  //   start runner <name>             → npm start                  (Telegram for that agent)
+  //   start runner <name> cli         → npm start -- --cli
   const startCmd = readManifest(agent).start
   if (startCmd) {
     let extra = args.slice(1)
     if (extra[0] === '--') extra = extra.slice(1)
 
-    // Optional [slug] [mode] positionals — `cli` is a reserved mode keyword
-    // (no real agent will ever be named "cli"). Anything else that doesn't
-    // start with `-` is treated as a slug. Verified installed before we spawn.
+    // Optional [name] [mode] positionals — `cli` is a reserved mode keyword.
     let slug = null
     if (extra[0] && extra[0] !== 'cli' && !extra[0].startsWith('-')) {
       slug = extra.shift()
       if (!existsSync(agentInstallDir(slug))) {
-        die(`${slug} is not installed. Try: 0101-agents install ${slug}`)
+        die(`${slug} is not installed.`)
       }
     }
     extra = extra.map(a => (a === 'cli' ? '--cli' : a))
 
-    // Override AGENT_DIR per invocation when a slug is given. The runner's
-    // config.ts derives STATE_DIR from basename(AGENT_DIR), so the per-agent
-    // state/lockfile/incoming dirs follow automatically.
     const childEnv = { ...process.env }
     if (slug) {
       childEnv.AGENT_DIR = agentInstallDir(slug)
@@ -398,10 +606,7 @@ async function cmdStart(args) {
     return
   }
 
-  // Everything after the agent name passes through to `claude`. Supports both:
-  //   0101-agents start marketer --resume
-  //   0101-agents start marketer -- --resume  (explicit separator)
-  // The `--` is optional; if present, we drop it.
+  // Everything after the agent name passes through to `claude`.
   let rest = args.slice(1)
   if (rest[0] === '--') rest = rest.slice(1)
 
@@ -419,8 +624,7 @@ async function cmdStart(args) {
     ]
   }
 
-  // Hand the terminal over to `claude` with cwd set to the agent dir. When
-  // claude exits, the user returns to their original shell location.
+  // Hand the terminal over to `claude` with cwd set to the agent dir.
   const child = spawn('claude', claudeArgs, { cwd: dir, stdio: 'inherit' })
   child.on('error', (e) => {
     if (e.code === 'ENOENT') {
@@ -432,28 +636,28 @@ async function cmdStart(args) {
 }
 
 function cmdHelp() {
-  console.log(`0101-agents — install and update Claude Code agents.
+  console.log(`0101-agents — install and update 0101 skillsets and agent templates.
 
 Commands:
-  ${bold('login')} [<key>]              Save your license key
-  ${bold('logout')}                     Forget your license key
-  ${bold('whoami')}                     Show current license
-  ${bold('install')} <agent> [--force]    Install an agent
-  ${bold('update')}  <agent> [-f]        Update an installed agent (preserves data/). -f skips the prompt
-  ${bold('start')}   <agent> [--tg] [-- args]  Open the agent (runs claude in its dir)
-                                       --tg adds the right flags to run as a
-                                       Telegram channel bot.
-  ${bold('list')}                       List installed agents
-  ${bold('help')}                       Show this message
+  ${bold('login')} [<key>]                    Save your license key
+  ${bold('logout')}                           Forget your license key
+  ${bold('whoami')}                           Show current license
+  ${bold('install')} <set> --to <agent>        Install a skillset into an agent
+  ${bold('install')} base --as <name>          Create a new agent from the base template
+  ${bold('update')}  <set> --to <agent>        Update a skillset inside an agent
+  ${bold('update')}  <agent> [-f]              Update an agent's template (preserves data/)
+  ${bold('start')}   <agent> [--tg] [-- args]   Open the agent (runs claude in its dir);
+                                           --tg runs it as a Telegram channel bot
+  ${bold('list')}                             List installed agents and their skillsets
+  ${bold('help')}                             Show this message
 
 Examples:
-  0101-agents start marketer                    Open in Claude Code
-  0101-agents start marketer --tg               Run as a Telegram channel bot via Claude Code
-  0101-agents start marketer --resume           Resume the last Claude Code session
-  0101-agents start runner                      Telegram bot via 0101-runner (uses .env)
-  0101-agents start runner cli                  Chat with the agent in this terminal
-  0101-agents start runner marketer             Run a Telegram bot for marketer (multi-bot)
-  0101-agents start runner marketer cli         Terminal chat for marketer
+  0101-agents install base --as ada                 New agent named "ada"
+  0101-agents install website-studio --to ada       Teach ada website skills
+  0101-agents update website-studio --to ada        Refresh that skillset
+  0101-agents update ada                            Update ada's base template
+
+Open an agent: cd ${INSTALL_ROOT}/<name> && claude
 
 Install dir: ${INSTALL_ROOT}
 Config:      ${CONFIG_PATH}`)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "0101-agents",
-  "version": "0.1.7",
+  "version": "0.2.0",
   "description": "",
   "bin": {
     "0101-agents": "./bin/cli.js"