agentcraft 0.0.1 → 0.0.3

package/docs/plans/2026-02-22-soundpack-system-design.md

@@ -0,0 +1,121 @@
+# Sound Pack System Design
+
+**Date:** 2026-02-22
+**Status:** Approved
+
+## Problem
+
+The current `~/.agentcraft/sounds/` directory is a flat, monolithic library cloned from one repo. There is no way for users to add additional sound packs, no way to ship UI themes as separate installable units, and no concept of publisher or pack identity in assignment paths. The system assumes exactly one sound library exists.
+
+## Goal
+
+A pack system that:
+- Lets users install sound packs from any GitHub repo via `agentcraft pack install publisher/name`
+- Works drop-in: manually cloning a repo into the right directory is equivalent to installing
+- Keeps packs isolated — no file conflicts between publishers
+- Migrates the existing `agentcraft-sounds` library cleanly
+- Powers the `agentcraft` npm CLI (already registered at 0.0.1)
+
+## Directory Layout
+
+```
+~/.agentcraft/
+  assignments.json          — sound assignments (paths include pack prefix)
+  waveforms.json            — waveform cache
+  packs/
+    rohenaz/
+      agentcraft-sounds/    — official pack (migrated from ~/.agentcraft/sounds/)
+        sc2/
+        wc3/
+        ff7/
+        ff9/
+        apps/
+        classic-os/
+        phones/
+        ui/                 — UI theme sounds
+          sc2/
+          wc3/
+          ff7/
+          ff9/
+          sc-bigbox/
+    community-publisher/
+      halo-pack/            — example third-party pack
+        sounds/
+        ui/
+```
+
+No manifest file required. Any directory at depth `packs/<publisher>/<name>/` is a valid pack. A `pack.json` is optional metadata (name, description, version) for display purposes only.
+
+## Assignment Path Format
+
+Paths in `assignments.json` gain a pack prefix separated by `:`:
+
+```
+rohenaz/agentcraft-sounds:sc2/terran/session-start/scv-ready.mp3
+```
+
+The hook script resolves this to:
+```
+~/.agentcraft/packs/rohenaz/agentcraft-sounds/sc2/terran/session-start/scv-ready.mp3
+```
+
+Paths without a `:` prefix are legacy paths (from `~/.agentcraft/sounds/`) and fall back to that directory during a migration grace period.
+
+## Default Configuration
+
+The user's current configuration is saved as `defaults/assignments.json` in the `agentcraft-sounds` repo. On first install, if no `~/.agentcraft/assignments.json` exists, the CLI copies this file as the starting configuration.
+
+## CLI (`agentcraft` npm package)
+
+```bash
+agentcraft pack install rohenaz/agentcraft-sounds   # git clone into packs/
+agentcraft pack install rohenaz/agentcraft-sounds --branch dev  # specific branch
+agentcraft pack list                                # show all installed packs
+agentcraft pack remove rohenaz/agentcraft-sounds   # rm -rf
+agentcraft pack update rohenaz/agentcraft-sounds   # git pull
+agentcraft pack update --all                       # pull all packs
+agentcraft start                                   # launch dashboard on port 4040
+```
+
+Install resolves `publisher/name` to `https://github.com/publisher/name` and clones into `~/.agentcraft/packs/publisher/name/`.
+
+## Web UI Changes
+
+### Sound Browser
+- Groups sounds by pack in the category filter
+- Pack shown as top-level grouping: `rohenaz/agentcraft-sounds > sc2 > terran`
+- Search spans all packs
+
+### API Routes
+- `/api/sounds` — scans `~/.agentcraft/packs/` recursively, prefixes all paths with `publisher/name:`
+- `/api/audio/[...path]` — resolves `publisher/name:internal/path` to filesystem path
+- `/api/ui-sounds` — scans `ui/` directory across all installed packs
+
+### Migration
+- On startup, if `~/.agentcraft/sounds/` exists and `~/.agentcraft/packs/` does not, the server symlinks `~/.agentcraft/packs/rohenaz/agentcraft-sounds` → `~/.agentcraft/sounds/` automatically
+- Assignment paths without `:` prefix resolve against `rohenaz/agentcraft-sounds` as the default pack
+
+## `/agentcraft` Slash Command Changes
+
+The auto-clone on first run targets `~/.agentcraft/packs/rohenaz/agentcraft-sounds` instead of `~/.agentcraft/sounds/`. Uses `agentcraft pack install` if CLI is available, falls back to raw `git clone`.
+
+## `pack.json` (Optional)
+
+```json
+{
+  "name": "agentcraft-sounds",
+  "publisher": "rohenaz",
+  "version": "2.0.0",
+  "description": "Official AgentCraft sound library — SC2, WC3, FF7, FF9, phones, classic OS",
+  "types": ["sounds", "ui"]
+}
+```
+
+`types` is informational — the browser detects what's present by scanning the directory.
+
+## Out of Scope (Future)
+
+- Central pack registry / discovery
+- Pack ratings or featured packs
+- Signed packs / integrity verification
+- Pack versioning / lockfile

package/hooks/play-sound.sh

@@ -1,7 +1,7 @@
 #!/bin/bash
 # AgentCraft hook - plays assigned sound for this event/agent/skill
 CONFIG="$HOME/.agentcraft/assignments.json"
-LIBRARY="$HOME/.agentcraft/sounds"
+PACKS="$HOME/.agentcraft/packs"
 
 # Read stdin with 2s timeout. 'timeout' isn't available by default on macOS,
 # so use perl's alarm() which is always present.
@@ -55,7 +55,18 @@ fi
 [ -z "$SOUND" ] && SOUND=$(jq -r --arg e "$EVENT" '.global[$e] // empty' "$CONFIG")
 [ -z "$SOUND" ] && exit 0
 
-FULL="$LIBRARY/$SOUND"
+# 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
 
 if [[ "$OSTYPE" == "darwin"* ]]; then

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentcraft",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "Assign sounds to AI coding agent lifecycle events. CLI for managing sound packs.",
   "license": "MIT",
   "author": "rohenaz",

package/web/app/api/assignments/route.ts

@@ -1,9 +1,7 @@
 import { NextRequest, NextResponse } from 'next/server';
 import { readFile, writeFile, mkdir } from 'fs/promises';
-import { join, dirname } from 'path';
-import { homedir } from 'os';
-
-const ASSIGNMENTS_PATH = join(homedir(), '.agentcraft', 'assignments.json');
+import { dirname } from 'path';
+import { ASSIGNMENTS_PATH } from '@/lib/packs';
 
 export async function GET() {
   try {

package/web/app/api/audio/[...path]/route.ts

@@ -1,9 +1,6 @@
 import { NextRequest, NextResponse } from 'next/server';
 import { readFile } from 'fs/promises';
-import { join } from 'path';
-import { homedir } from 'os';
-
-const SOUND_LIBRARY = join(homedir(), '.agentcraft', 'sounds');
+import { resolvePackPath } from '@/lib/packs';
 
 export async function GET(
   req: NextRequest,
@@ -11,23 +8,17 @@ export async function GET(
 ) {
   try {
     const { path: pathParts } = await params;
-    const relativePath = pathParts.join('/');
-
-    if (relativePath.includes('..')) {
+    const soundPath = decodeURIComponent(pathParts.join('/'));
+    if (soundPath.includes('..')) {
       return NextResponse.json({ error: 'Invalid path' }, { status: 400 });
     }
-
-    const fullPath = join(SOUND_LIBRARY, relativePath);
+    const fullPath = resolvePackPath(soundPath);
+    if (!fullPath) return NextResponse.json({ error: 'Invalid path' }, { status: 400 });
     const data = await readFile(fullPath);
-
-    const ext = relativePath.split('.').pop()?.toLowerCase();
+    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',
-      },
+      headers: { 'Content-Type': contentType, 'Cache-Control': 'public, max-age=86400' },
     });
   } catch {
     return NextResponse.json({ error: 'Audio file not found' }, { status: 404 });

package/web/app/api/packs/route.ts

@@ -0,0 +1,109 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { readdir, stat, readFile } from 'fs/promises';
+import { join } from 'path';
+import { homedir } from 'os';
+import { spawnSync } from 'child_process';
+
+const PACKS_DIR = join(homedir(), '.agentcraft', 'packs');
+
+interface PackInfo {
+  id: string;          // "publisher/name"
+  publisher: string;
+  name: string;
+  description?: string;
+  version?: string;
+}
+
+async function getInstalledPacks(): Promise<PackInfo[]> {
+  const packs: PackInfo[] = [];
+  let publishers: string[];
+  try {
+    publishers = await readdir(PACKS_DIR);
+  } catch {
+    return packs;
+  }
+  for (const publisher of publishers) {
+    const pubPath = join(PACKS_DIR, publisher);
+    const ps = await stat(pubPath).catch(() => null);
+    if (!ps?.isDirectory()) continue;
+    const names = await readdir(pubPath).catch(() => [] as string[]);
+    for (const name of names) {
+      const packPath = join(pubPath, name);
+      const ns = await stat(packPath).catch(() => null);
+      if (!ns?.isDirectory()) continue;
+      // Try to read pack.json for metadata
+      let description: string | undefined;
+      let version: string | undefined;
+      try {
+        const manifest = JSON.parse(await readFile(join(packPath, 'pack.json'), 'utf-8'));
+        description = manifest.description;
+        version = manifest.version;
+      } catch { /* no manifest, that's fine */ }
+      packs.push({ id: `${publisher}/${name}`, publisher, name, description, version });
+    }
+  }
+  return packs;
+}
+
+// GET — list installed packs
+export async function GET() {
+  const packs = await getInstalledPacks();
+  return NextResponse.json(packs);
+}
+
+// POST { repo: "publisher/name" } — install a pack
+export async function POST(req: NextRequest) {
+  try {
+    const { repo } = await req.json();
+    if (!repo || !/^[a-zA-Z0-9._-]+\/[a-zA-Z0-9._-]+$/.test(repo)) {
+      return NextResponse.json({ error: 'Invalid repo format' }, { status: 400 });
+    }
+    const [publisher, name] = repo.split('/');
+    const dest = join(PACKS_DIR, publisher, name);
+    const url = `https://github.com/${repo}`;
+    // mkdir publisher dir
+    spawnSync('mkdir', ['-p', join(PACKS_DIR, publisher)]);
+    const result = spawnSync('git', ['clone', url, dest], { timeout: 60000 });
+    if (result.status !== 0) {
+      return NextResponse.json({ error: 'Clone failed' }, { status: 500 });
+    }
+    return NextResponse.json({ ok: true });
+  } catch {
+    return NextResponse.json({ error: 'Install failed' }, { status: 500 });
+  }
+}
+
+// DELETE { repo: "publisher/name" } — remove a pack
+export async function DELETE(req: NextRequest) {
+  try {
+    const { repo } = await req.json();
+    if (!repo || !/^[a-zA-Z0-9._-]+\/[a-zA-Z0-9._-]+$/.test(repo)) {
+      return NextResponse.json({ error: 'Invalid repo format' }, { status: 400 });
+    }
+    const [publisher, name] = repo.split('/');
+    const dest = join(PACKS_DIR, publisher, name);
+    spawnSync('rm', ['-rf', dest]);
+    return NextResponse.json({ ok: true });
+  } catch {
+    return NextResponse.json({ error: 'Remove failed' }, { status: 500 });
+  }
+}
+
+// PATCH { repo: "publisher/name" } — update a pack (git pull)
+export async function PATCH(req: NextRequest) {
+  try {
+    const { repo } = await req.json();
+    if (!repo || !/^[a-zA-Z0-9._-]+\/[a-zA-Z0-9._-]+$/.test(repo)) {
+      return NextResponse.json({ error: 'Invalid repo format' }, { status: 400 });
+    }
+    const [publisher, name] = repo.split('/');
+    const dest = join(PACKS_DIR, publisher, name);
+    const result = spawnSync('git', ['-C', dest, 'pull'], { timeout: 30000 });
+    if (result.status !== 0) {
+      return NextResponse.json({ error: 'Update failed' }, { status: 500 });
+    }
+    return NextResponse.json({ ok: true });
+  } catch {
+    return NextResponse.json({ error: 'Update failed' }, { status: 500 });
+  }
+}

package/web/app/api/preview/route.ts

@@ -1,20 +1,16 @@
 import { NextRequest, NextResponse } from 'next/server';
 import { spawn } from 'child_process';
-import { join } from 'path';
-import { homedir } from 'os';
-
-const SOUND_LIBRARY = join(homedir(), '.agentcraft', 'sounds');
+import { resolvePackPath } from '@/lib/packs';
 
 export async function POST(req: NextRequest) {
   try {
     const { path } = await req.json();
-    if (!path || typeof path !== 'string' || path.includes('..')) {
+    if (!path || typeof path !== 'string') {
       return NextResponse.json({ error: 'Invalid path' }, { status: 400 });
     }
-
-    const fullPath = join(SOUND_LIBRARY, path);
+    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 });

package/web/app/api/sounds/route.ts

@@ -1,32 +1,22 @@
 import { NextResponse } from 'next/server';
-import { readdir, readFile, writeFile, mkdir } from 'fs/promises';
+import { readFile, writeFile, mkdir } from 'fs/promises';
 import { join, dirname } from 'path';
-import { homedir } from 'os';
 import { spawnSync } from 'child_process';
+import { listPacks, walkPackDir, WAVEFORM_CACHE } from '@/lib/packs';
 import type { SoundAsset } from '@/lib/types';
 
-const SOUND_LIBRARY = join(homedir(), '.agentcraft', 'sounds');
-const WAVEFORM_CACHE = join(homedir(), '.agentcraft', 'waveforms.json');
 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[] {
-  // Decode to mono f32le PCM at 1000 Hz (massively downsampled — fast, still accurate)
   const result = spawnSync('ffmpeg', [
-    '-i', filePath,
-    '-ac', '1',          // mono
-    '-ar', '1000',       // 1000 Hz sample rate
-    '-f', 'f32le',       // raw 32-bit float output
-    '-',                 // pipe to stdout
+    '-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; // 4 bytes per f32
+  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++) {
@@ -34,17 +24,13 @@ function computeWaveform(filePath: string): number[] {
     }
     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 {};
-  }
+  try { return JSON.parse(await readFile(WAVEFORM_CACHE, 'utf-8')); }
+  catch { return {}; }
 }
 
 async function saveCache(cache: Record<string, number[]>) {
@@ -52,53 +38,45 @@ async function saveCache(cache: Record<string, number[]>) {
   await writeFile(WAVEFORM_CACHE, JSON.stringify(cache), 'utf-8');
 }
 
-async function walkDir(dir: string, base: string): Promise<SoundAsset[]> {
-  const assets: SoundAsset[] = [];
-  const entries = await readdir(dir, { withFileTypes: true });
+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;
 
-  for (const entry of entries) {
-    const fullPath = join(dir, entry.name);
-    if (entry.isDirectory()) {
-      assets.push(...await walkDir(fullPath, base));
-    } else if (entry.name.match(/\.(mp3|wav|ogg|m4a)$/i)) {
-      const relativePath = fullPath.replace(base + '/', '');
-      const parts = relativePath.split('/');
-      // For flat dirs (depth 1): icq/uh-oh.mp3 → category=icq, subcategory=''
-      // For nested dirs (depth 2+): sc2/terran/session-start/scv.mp3 → category=sc2/terran, subcategory=session-start
-      const category = parts.length > 2 ? parts.slice(0, -2).join('/') : parts[0];
+    const results: SoundAsset[] = allFiles.map(({ relPath, absPath }) => {
+      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] : '';
-      assets.push({
-        id: relativePath.replace(/\.[^/.]+$/, ''),
+
+      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: relativePath,
-        waveform: FALLBACK,
-      });
-    }
-  }
-
-  return assets;
-}
-
-export async function GET() {
-  try {
-    const assets = await walkDir(SOUND_LIBRARY, SOUND_LIBRARY);
-    const cache = await loadCache();
-
-    let dirty = false;
-    const results = assets.map((asset) => {
-      if (cache[asset.path]) {
-        return { ...asset, waveform: cache[asset.path] };
-      }
-      const waveform = computeWaveform(join(SOUND_LIBRARY, asset.path));
-      cache[asset.path] = waveform;
-      dirty = true;
-      return { ...asset, waveform };
+        path: relPath,
+        waveform,
+      };
     });
 
     if (dirty) await saveCache(cache);
-
     return NextResponse.json(results);
   } catch {
     return NextResponse.json({ error: 'Failed to read sound library' }, { status: 500 });

package/web/app/api/ui-sounds/route.ts

@@ -1,44 +1,27 @@
 import { NextResponse } from 'next/server';
-import { readdir, stat } from 'fs/promises';
-import { join } from 'path';
-import { homedir } from 'os';
-
-const UI_DIR = join(homedir(), '.agentcraft', 'sounds', 'ui');
-const AUDIO_EXTS = new Set(['.mp3', '.wav', '.ogg', '.m4a']);
+import { listPacks, walkPackDir } from '@/lib/packs';
 
 interface UISound {
-  path: string;     // relative to ~/.agentcraft/sounds/, e.g. "ui/sc2/click.mp3"
-  filename: string; // e.g. "click.mp3"
-  group: string;    // e.g. "sc2"
+  path: string;
+  filename: string;
+  group: string;
 }
 
-async function scanDir(dir: string, base: string): Promise<UISound[]> {
+export async function GET() {
+  const packs = await listPacks();
   const results: UISound[] = [];
-  let entries: string[];
-  try {
-    entries = await readdir(dir);
-  } catch {
-    return results;
-  }
-  for (const entry of entries.sort()) {
-    const full = join(dir, entry);
-    const s = await stat(full).catch(() => null);
-    if (!s) continue;
-    if (s.isDirectory()) {
-      results.push(...await scanDir(full, `${base}/${entry}`));
-    } else {
-      const ext = entry.toLowerCase().slice(entry.lastIndexOf('.'));
-      if (AUDIO_EXTS.has(ext)) {
-        const rel = `${base}/${entry}`;
-        const group = base.replace('ui/', '');
-        results.push({ path: rel, filename: entry, group });
-      }
+
+  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);
+      const parts = internal.split('/');
+      if (parts[0] !== 'ui') continue;
+      const group = parts[1] ?? '';
+      results.push({ path: relPath, filename: parts[parts.length - 1], group });
     }
   }
-  return results;
-}
 
-export async function GET() {
-  const sounds = await scanDir(UI_DIR, 'ui');
-  return NextResponse.json(sounds);
+  return NextResponse.json(results);
 }

package/web/components/agent-roster-panel.tsx

@@ -3,6 +3,7 @@
 import { useState, useMemo } from 'react';
 import { HookSlot } from './hook-slot';
 import { AgentForm } from './agent-form';
+import { PacksPanel } from './packs-panel';
 import { playUISound } from '@/lib/ui-audio';
 import { getEventLabel } from '@/lib/utils';
 import type { HookEvent, SkillHookEvent, SoundAssignments, AgentInfo, SkillInfo, AgentFormData, SelectMode } from '@/lib/types';
@@ -220,7 +221,7 @@ interface AgentRosterPanelProps {
 }
 
 export function AgentRosterPanel({ assignments, agents, skills, onAssignmentChange, onPreview, onAgentsChange, selectMode, onSlotSelect }: AgentRosterPanelProps) {
-  const [activeView, setActiveView] = useState<'agents' | 'skills'>('agents');
+  const [activeView, setActiveView] = useState<'agents' | 'skills' | 'packs'>('agents');
   const [showForm, setShowForm] = useState(false);
   const [editingAgent, setEditingAgent] = useState<AgentInfo | undefined>();
   const [skillSearch, setSkillSearch] = useState('');
@@ -341,7 +342,7 @@ export function AgentRosterPanel({ assignments, agents, skills, onAssignmentChan
       {/* Tab bar header */}
       <div className="shrink-0 border-b" style={{ borderColor: 'var(--sf-border)', backgroundColor: 'var(--sf-panel)' }}>
         <div className="flex items-stretch">
-          {(['agents', 'skills'] as const).map((view) => (
+          {(['agents', 'skills', 'packs'] as const).map((view) => (
             <button
               key={view}
               data-sf-hover
@@ -359,7 +360,7 @@ export function AgentRosterPanel({ assignments, agents, skills, onAssignmentChan
                 backgroundColor: activeView === view ? 'rgba(0,229,255,0.04)' : 'transparent',
               }}
             >
-              {view === 'agents' ? 'AGENTS' : 'SKILLS'}
+              {view.toUpperCase()}
             </button>
           ))}
           {activeView === 'agents' && (
@@ -496,6 +497,8 @@ export function AgentRosterPanel({ assignments, agents, skills, onAssignmentChan
             })}
           </>
         )}
+
+        {activeView === 'packs' && <PacksPanel />}
       </div>
     </div>
   );