agentcraft 0.0.1 → 0.0.2

package/docs/plans/2026-02-22-soundpack-implementation.md

@@ -0,0 +1,667 @@
+# Sound Pack System Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Implement isolated, git-installable sound packs under `~/.agentcraft/packs/<publisher>/<name>/`, with a real `agentcraft` npm CLI and seamless migration from the old flat `~/.agentcraft/sounds/` layout.
+
+**Architecture:** Each pack is a bare directory at `~/.agentcraft/packs/<publisher>/<name>/` — no manifest required. Assignment paths gain a `publisher/name:internal/path` prefix. A shared `web/lib/packs.ts` module handles all resolution so API routes stay thin. The `agentcraft` npm CLI wraps git for install/update/remove and launches the dashboard.
+
+**Tech Stack:** Bun, Next.js 15 App Router, TypeScript, Bash, Node.js (CLI)
+
+---
+
+## Task 1: Save current config as defaults in agentcraft-sounds
+
+Save the user's current `assignments.json` as the starter config shipped with the official pack.
+
+**Files:**
+- Create: `~/.agentcraft/packs/rohenaz/agentcraft-sounds/defaults/assignments.json` (after Task 2 migration)
+- In agentcraft-sounds repo: create `defaults/assignments.json`
+
+**Step 1: Copy current assignments into the agentcraft-sounds repo**
+
+```bash
+mkdir -p ~/code/claude-sounds/defaults
+cp ~/.agentcraft/assignments.json ~/code/claude-sounds/defaults/assignments.json
+```
+
+**Step 2: Strip agent-specific hooks (keep only global + settings)**
+
+Edit `~/code/claude-sounds/defaults/assignments.json` — keep `global`, `settings`, `skills` but clear `agents` to `{}` since agent names are user-specific.
+
+**Step 3: Commit and push to agentcraft-sounds**
+
+```bash
+cd ~/code/claude-sounds
+git add defaults/assignments.json
+git commit -m "Add default assignments — starter configuration for new installs"
+git push
+```
+
+---
+
+## Task 2: Migrate local directory structure
+
+Move the existing `~/.agentcraft/sounds/` into the packs layout. The old path disappears; everything lives under `packs/` going forward.
+
+**Step 1: Create packs directory and move sounds**
+
+```bash
+mkdir -p ~/.agentcraft/packs/rohenaz
+mv ~/.agentcraft/sounds ~/.agentcraft/packs/rohenaz/agentcraft-sounds
+```
+
+**Step 2: Verify structure**
+
+```bash
+ls ~/.agentcraft/packs/rohenaz/agentcraft-sounds/
+# Expected: sc2  wc3  ff7  ff9  apps  classic-os  phones  ui  README.md
+```
+
+**Step 3: Update existing assignments.json paths to use pack prefix**
+
+Run this one-liner to prefix all sound paths:
+
+```bash
+cd ~/.agentcraft
+python3 -c "
+import json, re, sys
+
+with open('assignments.json') as f:
+    data = json.load(f)
+
+PREFIX = 'rohenaz/agentcraft-sounds:'
+
+def prefix_path(p):
+    if p and ':' not in p:
+        return PREFIX + p
+    return p
+
+def walk(obj):
+    if isinstance(obj, dict):
+        return {k: walk(v) for k, v in obj.items()}
+    if isinstance(obj, str) and obj.endswith(('.mp3', '.wav', '.ogg', '.m4a')):
+        return prefix_path(obj)
+    return obj
+
+result = walk(data)
+with open('assignments.json', 'w') as f:
+    json.dump(result, f, indent=2)
+print('Done')
+"
+```
+
+**Step 4: Verify assignments look correct**
+
+```bash
+cat ~/.agentcraft/assignments.json | grep -o '"rohenaz/agentcraft-sounds:[^"]*"' | head -5
+# Each sound path should now start with rohenaz/agentcraft-sounds:
+```
+
+---
+
+## Task 3: Create `web/lib/packs.ts` — shared pack resolution module
+
+All path logic lives here. API routes import from this module.
+
+**Files:**
+- Create: `web/lib/packs.ts`
+
+**Step 1: Write the module**
+
+```typescript
+// web/lib/packs.ts
+import { readdir, stat } from 'fs/promises';
+import { join } from 'path';
+import { homedir } from 'os';
+
+export const PACKS_DIR = join(homedir(), '.agentcraft', 'packs');
+export const ASSIGNMENTS_PATH = join(homedir(), '.agentcraft', 'assignments.json');
+export const WAVEFORM_CACHE = join(homedir(), '.agentcraft', 'waveforms.json');
+const AUDIO_EXTS = new Set(['.mp3', '.wav', '.ogg', '.m4a']);
+
+export interface Pack {
+  publisher: string;
+  name: string;
+  path: string; // absolute path to pack root
+  id: string;   // "publisher/name"
+}
+
+/** List all installed packs */
+export async function listPacks(): Promise<Pack[]> {
+  const packs: Pack[] = [];
+  let publishers: string[];
+  try {
+    publishers = await readdir(PACKS_DIR);
+  } catch {
+    return packs;
+  }
+  for (const publisher of publishers) {
+    const publisherPath = join(PACKS_DIR, publisher);
+    const ps = await stat(publisherPath).catch(() => null);
+    if (!ps?.isDirectory()) continue;
+    const names = await readdir(publisherPath).catch(() => [] as string[]);
+    for (const name of names) {
+      const packPath = join(publisherPath, name);
+      const ns = await stat(packPath).catch(() => null);
+      if (!ns?.isDirectory()) continue;
+      packs.push({ publisher, name, path: packPath, id: `${publisher}/${name}` });
+    }
+  }
+  return packs;
+}
+
+/**
+ * Resolve a pack-prefixed path to an absolute filesystem path.
+ * Format: "publisher/name:internal/path/to/sound.mp3"
+ * Legacy (no prefix): resolved against first installed pack that contains the file.
+ */
+export function resolvePackPath(soundPath: string): string | null {
+  if (!soundPath) return null;
+  const colonIdx = soundPath.indexOf(':');
+  if (colonIdx === -1) {
+    // Legacy path — assume rohenaz/agentcraft-sounds
+    return join(PACKS_DIR, 'rohenaz', 'agentcraft-sounds', soundPath);
+  }
+  const packId = soundPath.slice(0, colonIdx);
+  const internal = soundPath.slice(colonIdx + 1);
+  if (!packId || !internal || internal.includes('..')) return null;
+  const [publisher, name] = packId.split('/');
+  if (!publisher || !name) return null;
+  return join(PACKS_DIR, publisher, name, internal);
+}
+
+/**
+ * Walk a directory recursively, returning all audio files.
+ * Returns paths relative to `base`, prefixed with `packId:`.
+ */
+export async function walkPackDir(
+  dir: string,
+  base: string,
+  packId: string
+): Promise<Array<{ relPath: string; absPath: string }>> {
+  const results: Array<{ relPath: string; absPath: string }> = [];
+  let entries: Awaited<ReturnType<typeof readdir>>;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch {
+    return results;
+  }
+  for (const entry of entries) {
+    const abs = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...await walkPackDir(abs, base, packId));
+    } else {
+      const ext = entry.name.slice(entry.name.lastIndexOf('.')).toLowerCase();
+      if (AUDIO_EXTS.has(ext)) {
+        const rel = abs.slice(base.length + 1); // relative to pack root
+        results.push({ relPath: `${packId}:${rel}`, absPath: abs });
+      }
+    }
+  }
+  return results;
+}
+```
+
+**Step 2: Verify TypeScript compiles**
+
+```bash
+cd ~/code/agentcraft/web && bunx tsc --noEmit 2>&1 | grep packs
+# Should produce no errors
+```
+
+---
+
+## Task 4: Update `/api/sounds` route
+
+**Files:**
+- Modify: `web/app/api/sounds/route.ts`
+
+**Step 1: Rewrite to use packs.ts**
+
+Replace the entire file:
+
+```typescript
+import { NextResponse } from 'next/server';
+import { readFile, writeFile, mkdir } from 'fs/promises';
+import { join, dirname } from 'path';
+import { spawnSync } from 'child_process';
+import { listPacks, walkPackDir, WAVEFORM_CACHE } from '@/lib/packs';
+import type { SoundAsset } from '@/lib/types';
+
+const BARS = 16;
+const FALLBACK = [5, 7, 4, 9, 6, 8, 3, 7, 5, 8, 4, 6, 7, 5, 8, 4];
+
+function computeWaveform(filePath: string): number[] {
+  const result = spawnSync('ffmpeg', [
+    '-i', filePath, '-ac', '1', '-ar', '1000', '-f', 'f32le', '-',
+  ], { maxBuffer: 1024 * 1024 * 4 });
+  if (result.status !== 0 || !result.stdout?.length) return FALLBACK;
+  const buf = result.stdout as Buffer;
+  const samples = buf.length / 4;
+  const blockSize = Math.floor(samples / BARS);
+  const values: number[] = [];
+  for (let i = 0; i < BARS; i++) {
+    let sum = 0;
+    for (let j = 0; j < blockSize; j++) {
+      sum += Math.abs(buf.readFloatLE((i * blockSize + j) * 4));
+    }
+    values.push(sum / blockSize);
+  }
+  const max = Math.max(...values, 0.0001);
+  return values.map((v) => Math.max(1, Math.round((v / max) * 10)));
+}
+
+async function loadCache(): Promise<Record<string, number[]>> {
+  try { return JSON.parse(await readFile(WAVEFORM_CACHE, 'utf-8')); }
+  catch { return {}; }
+}
+
+async function saveCache(cache: Record<string, number[]>) {
+  await mkdir(dirname(WAVEFORM_CACHE), { recursive: true });
+  await writeFile(WAVEFORM_CACHE, JSON.stringify(cache), 'utf-8');
+}
+
+export async function GET() {
+  try {
+    const packs = await listPacks();
+    const allFiles: Array<{ relPath: string; absPath: string }> = [];
+    for (const pack of packs) {
+      const files = await walkPackDir(pack.path, pack.path, pack.id);
+      allFiles.push(...files);
+    }
+
+    const cache = await loadCache();
+    let dirty = false;
+
+    const results: SoundAsset[] = allFiles.map(({ relPath, absPath }) => {
+      // relPath: "rohenaz/agentcraft-sounds:sc2/terran/session-start/scv-ready.mp3"
+      const internal = relPath.slice(relPath.indexOf(':') + 1);
+      const parts = internal.split('/');
+      const packId = relPath.slice(0, relPath.indexOf(':'));
+      const category = parts.length > 2
+        ? `${packId}:${parts.slice(0, -2).join('/')}`
+        : `${packId}:${parts[0]}`;
+      const subcategory = parts.length > 2 ? parts[parts.length - 2] : '';
+
+      const waveform = cache[relPath] ?? (() => {
+        const wf = computeWaveform(absPath);
+        cache[relPath] = wf;
+        dirty = true;
+        return wf;
+      })();
+
+      return {
+        id: relPath.replace(/\.[^/.]+$/, ''),
+        filename: parts[parts.length - 1],
+        category,
+        subcategory,
+        path: relPath,
+        waveform,
+      };
+    });
+
+    if (dirty) await saveCache(cache);
+    return NextResponse.json(results);
+  } catch (e) {
+    return NextResponse.json({ error: 'Failed to read sound library' }, { status: 500 });
+  }
+}
+```
+
+**Step 2: Start dev server and verify sounds load**
+
+```bash
+cd ~/code/agentcraft/web && bun dev --port 4040 &
+sleep 5
+curl -s http://localhost:4040/api/sounds | jq '.[0]'
+# Expect: path starts with "rohenaz/agentcraft-sounds:"
+```
+
+---
+
+## Task 5: Update `/api/audio` and `/api/preview` routes
+
+**Files:**
+- Modify: `web/app/api/audio/[...path]/route.ts`
+- Modify: `web/app/api/preview/route.ts`
+
+**Step 1: Update audio route**
+
+```typescript
+import { NextRequest, NextResponse } from 'next/server';
+import { readFile } from 'fs/promises';
+import { resolvePackPath } from '@/lib/packs';
+
+export async function GET(
+  req: NextRequest,
+  { params }: { params: Promise<{ path: string[] }> }
+) {
+  try {
+    const { path: pathParts } = await params;
+    // Reconstruct the full pack path — URL encodes ":" as %3A
+    const soundPath = decodeURIComponent(pathParts.join('/'));
+    if (soundPath.includes('..')) {
+      return NextResponse.json({ error: 'Invalid path' }, { status: 400 });
+    }
+    const fullPath = resolvePackPath(soundPath);
+    if (!fullPath) return NextResponse.json({ error: 'Invalid path' }, { status: 400 });
+    const data = await readFile(fullPath);
+    const ext = soundPath.split('.').pop()?.toLowerCase();
+    const contentType = ext === 'mp3' ? 'audio/mpeg' : ext === 'wav' ? 'audio/wav' : 'audio/mpeg';
+    return new NextResponse(data, {
+      headers: { 'Content-Type': contentType, 'Cache-Control': 'public, max-age=86400' },
+    });
+  } catch {
+    return NextResponse.json({ error: 'Audio file not found' }, { status: 404 });
+  }
+}
+```
+
+**Step 2: Update preview route**
+
+```typescript
+import { NextRequest, NextResponse } from 'next/server';
+import { spawn } from 'child_process';
+import { resolvePackPath } from '@/lib/packs';
+
+export async function POST(req: NextRequest) {
+  try {
+    const { path } = await req.json();
+    if (!path || typeof path !== 'string') {
+      return NextResponse.json({ error: 'Invalid path' }, { status: 400 });
+    }
+    const fullPath = resolvePackPath(path);
+    if (!fullPath) return NextResponse.json({ error: 'Invalid path' }, { status: 400 });
+    spawn('afplay', [fullPath], { detached: true, stdio: 'ignore' }).unref();
+    return NextResponse.json({ ok: true });
+  } catch {
+    return NextResponse.json({ error: 'Playback failed' }, { status: 500 });
+  }
+}
+```
+
+---
+
+## Task 6: Update `/api/ui-sounds` route
+
+**Files:**
+- Modify: `web/app/api/ui-sounds/route.ts`
+
+**Step 1: Rewrite to scan ui/ in all packs**
+
+```typescript
+import { NextResponse } from 'next/server';
+import { listPacks, walkPackDir } from '@/lib/packs';
+
+interface UISound {
+  path: string;    // pack-prefixed, e.g. "rohenaz/agentcraft-sounds:ui/sc2/click.mp3"
+  filename: string;
+  group: string;   // e.g. "sc2"
+}
+
+export async function GET() {
+  const packs = await listPacks();
+  const results: UISound[] = [];
+
+  for (const pack of packs) {
+    const uiDir = `${pack.path}/ui`;
+    const files = await walkPackDir(uiDir, pack.path, pack.id).catch(() => []);
+    for (const { relPath } of files) {
+      const internal = relPath.slice(relPath.indexOf(':') + 1); // "ui/sc2/click.mp3"
+      const parts = internal.split('/');                         // ["ui", "sc2", "click.mp3"]
+      if (parts[0] !== 'ui') continue;
+      const group = parts[1] ?? '';                              // "sc2"
+      results.push({ path: relPath, filename: parts[parts.length - 1], group });
+    }
+  }
+
+  return NextResponse.json(results);
+}
+```
+
+---
+
+## Task 7: Update hook script to resolve pack paths
+
+**Files:**
+- Modify: `hooks/play-sound.sh`
+
+**Step 1: Replace `LIBRARY` constant and resolution logic**
+
+Replace the `LIBRARY` line and the `FULL=` line at the bottom:
+
+```bash
+PACKS="$HOME/.agentcraft/packs"
+
+# ...existing lookup logic unchanged...
+
+[ -z "$SOUND" ] && exit 0
+
+# Resolve pack-prefixed path: "publisher/name:internal/path"
+if echo "$SOUND" | grep -q ':'; then
+  PACK_ID="${SOUND%%:*}"
+  INTERNAL="${SOUND#*:}"
+  PUBLISHER="${PACK_ID%%/*}"
+  PACKNAME="${PACK_ID##*/}"
+  FULL="$PACKS/$PUBLISHER/$PACKNAME/$INTERNAL"
+else
+  # Legacy path — fall back to rohenaz/agentcraft-sounds
+  FULL="$PACKS/rohenaz/agentcraft-sounds/$SOUND"
+fi
+
+[ ! -f "$FULL" ] && exit 0
+```
+
+**Step 2: Test the hook manually**
+
+```bash
+echo '{"hook_event_name":"SessionStart","agent_type":""}' | bash ~/code/agentcraft/hooks/play-sound.sh
+# Should play the SessionStart sound
+```
+
+---
+
+## Task 8: Update slash command
+
+**Files:**
+- Modify: `commands/agentcraft.md`
+
+**Step 1: Update first-run check to use packs/ directory**
+
+Replace the sounds presence check and clone command:
+
+```markdown
+Check if the official sound pack is installed:
+```bash
+ls ~/.agentcraft/packs/rohenaz/agentcraft-sounds 2>/dev/null | head -1
+```
+
+If that returned nothing, install it:
+```bash
+agentcraft pack install rohenaz/agentcraft-sounds 2>/dev/null || \
+  git clone https://github.com/rohenaz/agentcraft-sounds ~/.agentcraft/packs/rohenaz/agentcraft-sounds
+```
+```
+
+Also add `Bash(agentcraft:*)` to `allowed-tools`.
+
+---
+
+## Task 9: Build real `agentcraft` CLI
+
+**Files:**
+- Modify: `bin/agentcraft.js`
+
+**Step 1: Write the full CLI**
+
+```javascript
+#!/usr/bin/env node
+'use strict';
+
+const { execSync, spawnSync } = require('child_process');
+const { existsSync, readdirSync, rmSync, statSync } = require('fs');
+const { join } = require('path');
+const { homedir } = require('os');
+
+const PACKS_DIR = join(homedir(), '.agentcraft', 'packs');
+const [,, cmd, sub, ...rest] = process.argv;
+
+function ensurePacksDir() {
+  require('fs').mkdirSync(PACKS_DIR, { recursive: true });
+}
+
+function parsePackId(arg) {
+  if (!arg || !arg.includes('/')) {
+    console.error(`Error: pack must be "publisher/name", got: ${arg}`);
+    process.exit(1);
+  }
+  const [publisher, name] = arg.split('/');
+  return { publisher, name, url: `https://github.com/${publisher}/${name}` };
+}
+
+function listPacks() {
+  if (!existsSync(PACKS_DIR)) { console.log('No packs installed.'); return []; }
+  const packs = [];
+  for (const publisher of readdirSync(PACKS_DIR)) {
+    const ppath = join(PACKS_DIR, publisher);
+    if (!statSync(ppath).isDirectory()) continue;
+    for (const name of readdirSync(ppath)) {
+      if (statSync(join(ppath, name)).isDirectory()) packs.push(`${publisher}/${name}`);
+    }
+  }
+  return packs;
+}
+
+if (cmd === 'pack') {
+  if (sub === 'install') {
+    const { publisher, name, url } = parsePackId(rest[0]);
+    const dest = join(PACKS_DIR, publisher, name);
+    if (existsSync(dest)) { console.log(`Already installed: ${publisher}/${name}`); process.exit(0); }
+    ensurePacksDir();
+    require('fs').mkdirSync(join(PACKS_DIR, publisher), { recursive: true });
+    console.log(`Installing ${publisher}/${name} from ${url}...`);
+    const r = spawnSync('git', ['clone', url, dest], { stdio: 'inherit' });
+    if (r.status !== 0) { console.error('Install failed.'); process.exit(1); }
+    console.log(`Installed: ${publisher}/${name}`);
+
+  } else if (sub === 'remove') {
+    const { publisher, name } = parsePackId(rest[0]);
+    const dest = join(PACKS_DIR, publisher, name);
+    if (!existsSync(dest)) { console.error(`Not installed: ${publisher}/${name}`); process.exit(1); }
+    rmSync(dest, { recursive: true, force: true });
+    console.log(`Removed: ${publisher}/${name}`);
+
+  } else if (sub === 'update') {
+    const all = rest[0] === '--all';
+    const targets = all ? listPacks() : [rest[0]];
+    for (const packId of targets) {
+      const { publisher, name } = parsePackId(packId);
+      const dest = join(PACKS_DIR, publisher, name);
+      if (!existsSync(dest)) { console.error(`Not installed: ${packId}`); continue; }
+      console.log(`Updating ${packId}...`);
+      spawnSync('git', ['-C', dest, 'pull'], { stdio: 'inherit' });
+    }
+
+  } else if (sub === 'list') {
+    const packs = listPacks();
+    if (!packs.length) { console.log('No packs installed.'); }
+    else { console.log('Installed packs:\n' + packs.map(p => `  ${p}`).join('\n')); }
+
+  } else {
+    console.log('Usage: agentcraft pack <install|remove|update|list> [publisher/name] [--all]');
+  }
+
+} else if (cmd === 'start') {
+  const pluginRoot = process.env.CLAUDE_PLUGIN_ROOT;
+  if (!pluginRoot) { console.error('CLAUDE_PLUGIN_ROOT not set. Run from the Claude Code plugin.'); process.exit(1); }
+  execSync(`cd "${pluginRoot}/web" && bun dev --port 4040`, { stdio: 'inherit' });
+
+} else {
+  console.log(`AgentCraft CLI
+
+Usage:
+  agentcraft pack install <publisher/name>   Install a sound pack
+  agentcraft pack remove  <publisher/name>   Remove a sound pack
+  agentcraft pack update  <publisher/name>   Update a pack (git pull)
+  agentcraft pack update  --all              Update all packs
+  agentcraft pack list                       List installed packs
+  agentcraft start                           Launch the dashboard
+
+Install the Claude Code plugin:
+  claude plugin install agentcraft@rohenaz
+`);
+}
+```
+
+**Step 2: Test locally**
+
+```bash
+node ~/code/agentcraft/bin/agentcraft.js pack list
+# Should list rohenaz/agentcraft-sounds
+
+node ~/code/agentcraft/bin/agentcraft.js
+# Should show usage
+```
+
+---
+
+## Task 10: Add `pack.json` to agentcraft-sounds
+
+**Files:**
+- Create: `~/code/claude-sounds/pack.json`
+
+```json
+{
+  "name": "agentcraft-sounds",
+  "publisher": "rohenaz",
+  "version": "2.0.0",
+  "description": "Official AgentCraft sound library — SC2, WC3, FF7, FF9, phones, apps, classic OS",
+  "types": ["sounds", "ui"]
+}
+```
+
+```bash
+cd ~/code/claude-sounds
+git add pack.json
+git commit -m "Add pack.json manifest"
+git push
+```
+
+---
+
+## Task 11: Bump versions and publish
+
+**Step 1: Bump Claude plugin to 0.0.9**
+
+In `.claude-plugin/plugin.json`: `"version": "0.0.9"`
+
+**Step 2: Publish npm CLI as 0.0.2**
+
+In `package.json`: `"version": "0.0.2"`
+
+```bash
+cd ~/code/agentcraft
+git add -A
+git commit -m "v0.0.9: Sound pack system — packs/, CLI pack commands, path migration"
+git push
+```
+
+Then publish with OTP.
+
+**Step 3: Update plugin**
+
+```bash
+CLAUDECODE=1 claude plugin update agentcraft@rohenaz
+```
+
+---
+
+## Task 12: Update README
+
+Update `README.md` to document the pack system:
+
+- Replace "Sound Library" section with "Sound Packs"
+- Show `agentcraft pack install` as the way to get sounds
+- Document `agentcraft pack list/update/remove`
+- Note that manual `git clone` into `~/.agentcraft/packs/publisher/name/` works identically