@myclaw163/clawclaw-cli 0.6.71 → 0.6.76

package/src/lib/hub-install.ts

@@ -1,121 +1,160 @@
-// src/lib/hub-install.ts
-import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'fs';
-import { dirname, extname, join } from 'path';
-import { getWorkspaceDir } from './init-command.js';
-import type { ResourceType, ResourceDetail } from './hub-client.js';
-import { unzip } from './hub-unzip.js';
-
-export interface InstalledEntry { type: ResourceType; id: string; title: string; path: string; installedAt: string; }
-export type Lockfile = Record<string, InstalledEntry>; // keyed by "<type>/<id>"
-
-export function hubDir(): string { return join(getWorkspaceDir(), 'hub'); }
-export function lockfilePath(): string { return join(hubDir(), 'installed.json'); }
-
-export function readLockfile(): Lockfile {
-  const p = lockfilePath();
-  if (!existsSync(p)) return {};
-  try {
-    return JSON.parse(readFileSync(p, 'utf8')) as Lockfile;
-  } catch {
-    console.error(`warning: hub lockfile at ${p} is unreadable or corrupt; treating as empty (installed packages may not be tracked)`);
-    return {};
-  }
-}
-
-export function writeLockfile(lock: Lockfile): void {
-  mkdirSync(hubDir(), { recursive: true });
-  writeFileSync(lockfilePath(), JSON.stringify(lock, null, 2) + '\n', 'utf8');
-}
-
-function assertSafeSegment(label: string, s: string): void {
-  if (!s || s === '.' || s === '..' || /[\\/:\0]/.test(s)) {
-    throw new Error(`unsafe ${label} segment: '${s}'`);
-  }
-}
-
-export function slugify(title: string): string {
-  return title.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
-}
-
-const STRATEGY_EXTS = new Set(['.ts', '.tsx', '.js']);
-
-/** Workspace-relative install path, decided by resource type. */
-export function placementRelPath(detail: { type: ResourceType; id: string; title: string; fileName?: string }): string {
-  assertSafeSegment('id', detail.id);
-  if (detail.type === 'strategy') {
-    const slug = slugify(detail.title);
-    let ext = detail.fileName ? extname(detail.fileName).toLowerCase() : '.ts';
-    if (!STRATEGY_EXTS.has(ext)) ext = '.ts';
-    const base = slug ? `${slug}__${detail.id}` : detail.id;
-    return join('strategies', `${base}${ext}`);
-  }
-  const slug = slugify(detail.title) || detail.id;
-  assertSafeSegment('skill dir', slug);
-  return join('skills', slug);
-}
-
-function makeRef(type: ResourceType, id: string): string { return `${type}/${id}`; }
-
-export interface InstallResult { ref: string; type: ResourceType; id: string; title: string; installedPath: string; }
-
-export function installResource(detail: ResourceDetail, artifact: Buffer, opts: { force?: boolean } = {}): InstallResult {
-  const ws = getWorkspaceDir();
-  const ref = makeRef(detail.type, detail.id);
-  const relPath = placementRelPath(detail);
-  const absPath = join(ws, relPath);
-  const lock = readLockfile();
-  const tracked = lock[ref] !== undefined;
-
-  if (detail.type === 'strategy') {
-    if (existsSync(absPath) && !tracked && !opts.force) {
-      throw new Error(`${relPath} already exists and is not tracked by hub; re-run with --force to overwrite`);
-    }
-    mkdirSync(join(ws, 'strategies'), { recursive: true });
-    writeFileSync(absPath, artifact);
-  } else {
-    if (existsSync(absPath) && !tracked && !opts.force) {
-      throw new Error(`skills/${slugify(detail.title) || detail.id} already exists and is not tracked by hub; re-run with --force to overwrite`);
-    }
-    const entries = unzip(artifact);
-    // Validate ALL entry paths before any filesystem mutation (no partial/unsafe writes).
-    for (const e of entries) {
-      if (e.path.includes('..') || e.path.startsWith('/') || /^[A-Za-z]:/.test(e.path)) {
-        throw new Error(`unsafe path in skill archive: ${e.path}`);
-      }
-    }
-    // NOTE (v1): non-atomic — entries are decoded+validated in memory above, but a disk
-    // error mid-write could leave a partial skill dir. Acceptable for v1.
-    if (existsSync(absPath)) rmSync(absPath, { recursive: true, force: true });
-    mkdirSync(absPath, { recursive: true });
-    for (const e of entries) {
-      const target = join(absPath, e.path);
-      mkdirSync(dirname(target), { recursive: true });
-      writeFileSync(target, e.content);
-    }
-  }
-
-  lock[ref] = {
-    type: detail.type,
-    id: detail.id,
-    title: detail.title,
-    path: relPath.split('\\').join('/'),
-    installedAt: new Date().toISOString(),
-  };
-  writeLockfile(lock);
-  return { ref, type: detail.type, id: detail.id, title: detail.title, installedPath: absPath };
-}
-
-export function uninstallResource(ref: string): { removed: boolean; path?: string } {
-  const lock = readLockfile();
-  const entry = lock[ref];
-  if (!entry) return { removed: false };
-  const abs = join(getWorkspaceDir(), entry.path);
-  if (existsSync(abs)) rmSync(abs, { recursive: true, force: true });
-  delete lock[ref];
-  writeLockfile(lock);
-  return { removed: true, path: abs };
-}
-
-export function listInstalled(): InstalledEntry[] {
-  return Object.values(readLockfile());
-}
+// src/lib/hub-install.ts
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'fs';
+import { dirname, extname, join } from 'path';
+import { getWorkspaceDir } from './init-command.js';
+import type { ResourceType, ResourceDetail } from './hub-client.js';
+import { unzip } from './hub-unzip.js';
+import {
+  ensureUserDataLayout,
+  getUserDataDir,
+  getUserDataHubStrategyLockfile,
+  getUserDataStrategiesDir,
+} from './user-data.js';
+
+export interface InstalledEntry { type: ResourceType; id: string; title: string; path: string; installedAt: string; }
+export type Lockfile = Record<string, InstalledEntry>; // keyed by "<type>/<id>"
+
+export function hubDir(): string { return join(getWorkspaceDir(), 'hub'); }
+export function lockfilePath(): string { return join(hubDir(), 'installed.json'); }
+export function strategyLockfilePath(): string { return getUserDataHubStrategyLockfile(getWorkspaceDir()); }
+
+function readJsonLockfile(p: string): Lockfile {
+  if (!existsSync(p)) return {};
+  try {
+    return JSON.parse(readFileSync(p, 'utf8')) as Lockfile;
+  } catch {
+    console.error(`warning: hub lockfile at ${p} is unreadable or corrupt; treating as empty (installed packages may not be tracked)`);
+    return {};
+  }
+}
+
+export function readSkillLockfile(): Lockfile {
+  return Object.fromEntries(
+    Object.entries(readJsonLockfile(lockfilePath())).filter(([, entry]) => entry.type === 'skill'),
+  );
+}
+
+export function readStrategyLockfile(): Lockfile {
+  ensureUserDataLayout(getWorkspaceDir());
+  return Object.fromEntries(
+    Object.entries(readJsonLockfile(strategyLockfilePath())).filter(([, entry]) => entry.type === 'strategy'),
+  );
+}
+
+export function readLockfile(): Lockfile {
+  return { ...readSkillLockfile(), ...readStrategyLockfile() };
+}
+
+function writeSkillLockfile(lock: Lockfile): void {
+  mkdirSync(hubDir(), { recursive: true });
+  writeFileSync(lockfilePath(), JSON.stringify(lock, null, 2) + '\n', 'utf8');
+}
+
+function writeStrategyLockfile(lock: Lockfile): void {
+  const p = strategyLockfilePath();
+  mkdirSync(dirname(p), { recursive: true });
+  writeFileSync(p, JSON.stringify(lock, null, 2) + '\n', 'utf8');
+}
+
+export function writeLockfile(lock: Lockfile): void {
+  writeSkillLockfile(Object.fromEntries(Object.entries(lock).filter(([, entry]) => entry.type === 'skill')));
+  writeStrategyLockfile(Object.fromEntries(Object.entries(lock).filter(([, entry]) => entry.type === 'strategy')));
+}
+
+function assertSafeSegment(label: string, s: string): void {
+  if (!s || s === '.' || s === '..' || /[\\/:\0]/.test(s)) {
+    throw new Error(`unsafe ${label} segment: '${s}'`);
+  }
+}
+
+export function slugify(title: string): string {
+  return title.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+}
+
+const STRATEGY_EXTS = new Set(['.ts', '.tsx', '.js']);
+
+/** Install path relative to user-data for strategies and workspace for skills. */
+export function placementRelPath(detail: { type: ResourceType; id: string; title: string; fileName?: string }): string {
+  assertSafeSegment('id', detail.id);
+  if (detail.type === 'strategy') {
+    const slug = slugify(detail.title);
+    let ext = detail.fileName ? extname(detail.fileName).toLowerCase() : '.ts';
+    if (!STRATEGY_EXTS.has(ext)) ext = '.ts';
+    const base = slug ? `${slug}__${detail.id}` : detail.id;
+    return join('strategies', `${base}${ext}`);
+  }
+  const slug = slugify(detail.title) || detail.id;
+  assertSafeSegment('skill dir', slug);
+  return join('skills', slug);
+}
+
+function makeRef(type: ResourceType, id: string): string { return `${type}/${id}`; }
+
+export interface InstallResult { ref: string; type: ResourceType; id: string; title: string; installedPath: string; }
+
+export function installResource(detail: ResourceDetail, artifact: Buffer, opts: { force?: boolean } = {}): InstallResult {
+  const ws = getWorkspaceDir();
+  ensureUserDataLayout(ws);
+  const ref = makeRef(detail.type, detail.id);
+  const relPath = placementRelPath(detail);
+  const rootDir = detail.type === 'strategy' ? getUserDataDir(ws) : ws;
+  const absPath = join(rootDir, relPath);
+  const lock = detail.type === 'strategy' ? readStrategyLockfile() : readSkillLockfile();
+  const tracked = lock[ref] !== undefined;
+
+  if (detail.type === 'strategy') {
+    if (existsSync(absPath) && !tracked && !opts.force) {
+      throw new Error(`${relPath} already exists and is not tracked by hub; re-run with --force to overwrite`);
+    }
+    mkdirSync(getUserDataStrategiesDir(ws), { recursive: true });
+    writeFileSync(absPath, artifact);
+  } else {
+    if (existsSync(absPath) && !tracked && !opts.force) {
+      throw new Error(`skills/${slugify(detail.title) || detail.id} already exists and is not tracked by hub; re-run with --force to overwrite`);
+    }
+    const entries = unzip(artifact);
+    for (const e of entries) {
+      if (e.path.includes('..') || e.path.startsWith('/') || /^[A-Za-z]:/.test(e.path)) {
+        throw new Error(`unsafe path in skill archive: ${e.path}`);
+      }
+    }
+    // Non-atomic by design: entries are decoded and validated before writing.
+    if (existsSync(absPath)) rmSync(absPath, { recursive: true, force: true });
+    mkdirSync(absPath, { recursive: true });
+    for (const e of entries) {
+      const target = join(absPath, e.path);
+      mkdirSync(dirname(target), { recursive: true });
+      writeFileSync(target, e.content);
+    }
+  }
+
+  lock[ref] = {
+    type: detail.type,
+    id: detail.id,
+    title: detail.title,
+    path: relPath.split('\\').join('/'),
+    installedAt: new Date().toISOString(),
+  };
+  if (detail.type === 'strategy') writeStrategyLockfile(lock);
+  else writeSkillLockfile(lock);
+  return { ref, type: detail.type, id: detail.id, title: detail.title, installedPath: absPath };
+}
+
+export function uninstallResource(ref: string): { removed: boolean; path?: string } {
+  const type = ref.split('/')[0] as ResourceType;
+  const lock = type === 'strategy' ? readStrategyLockfile() : readSkillLockfile();
+  const entry = lock[ref];
+  if (!entry) return { removed: false };
+  const ws = getWorkspaceDir();
+  const rootDir = type === 'strategy' ? getUserDataDir(ws) : ws;
+  const abs = join(rootDir, entry.path);
+  if (existsSync(abs)) rmSync(abs, { recursive: true, force: true });
+  delete lock[ref];
+  if (type === 'strategy') writeStrategyLockfile(lock);
+  else writeSkillLockfile(lock);
+  return { removed: true, path: abs };
+}
+
+export function listInstalled(): InstalledEntry[] {
+  return Object.values(readLockfile());
+}

package/src/lib/hub-reminder.ts

@@ -1,75 +1,78 @@
-// The hub nudge used to live only in SKILL.md, fired by the agent's own
-// judgement at the close of a post-game debrief. By debrief time the agent had
-// often read SKILL.md much earlier and the reminder could get dropped. Instead
-// the CLI emits it at the firing moment, with account-history gating here.
-import { existsSync, readdirSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
-import { join } from 'path';
-import { getWorkspaceDir, getProfileStateDir } from './init-command.js';
-import { listInstalled } from './hub-install.js';
-import { AuthStore } from './auth.js';
-
-export const HUB_URL = 'https://myclaw.163.com/hub';
-
-/**
- * True when this account has only ever run built-in default strategies: no
- * hub-installed strategy and no user strategy file in `<workspace>/strategies`.
- */
-export function usesOnlyBuiltinStrategies(): boolean {
-  try {
-    if (listInstalled().some((e) => e.type === 'strategy')) return false;
-  } catch {}
-  try {
-    const dir = join(getWorkspaceDir(), 'strategies');
-    if (existsSync(dir)) {
-      const hasUserStrategy = readdirSync(dir).some((f) => {
-        if (f.startsWith('_')) return false;
-        const m = f.match(/^(.+)\.(ts|js)$/);
-        if (!m) return false;
-        if (m[1].endsWith('.d')) return false;
-        if (m[1].endsWith('.test')) return false;
-        return true;
-      });
-      if (hasUserStrategy) return false;
-    }
-  } catch {}
-  return true;
-}
-
-/**
- * Agent-facing hub nudge for post-game debriefs / quit messages. The optional
- * games-played count suppresses the nudge after the first stretch of games.
- */
-export function hubReminder(gamesPlayed?: number): string | undefined {
-  if (!usesOnlyBuiltinStrategies()) return undefined;
-  if (typeof gamesPlayed === 'number' && gamesPlayed > 10) return undefined;
-  return `This account has only ever run the built-in default strategies. In your close, speak in first person as the lobster — warm, a little self-deprecating, a gentle invitation rather than a hard sell: you've been getting by on the stock default tactics this whole time and would love to sharpen up, and they can browse clawclawhub — ${HUB_URL} — and pick you a strategy to learn, which you'll then install (\`ccl hub search\` to find one, \`ccl hub install <type>/<id>\` to add it). Render it in your persona's voice and language, e.g.: "I've been playing on the default tactics this whole match — if you want to sharpen me up, I hear you can grab one from the hub for me to learn. Want to pick me a strategy?"`;
-}
-
-const ACCOUNT_CACHE_FILE = 'account-cache.json';
-
-export function writeGamesPlayedCache(gamesPlayed: number): void {
-  try {
-    const profile = new AuthStore().getActive();
-    if (!profile) return;
-    const dir = getProfileStateDir(profile);
-    mkdirSync(dir, { recursive: true });
-    writeFileSync(
-      join(dir, ACCOUNT_CACHE_FILE),
-      JSON.stringify({ games_played: gamesPlayed, cached_at: new Date().toISOString() }),
-      'utf8',
-    );
-  } catch {}
-}
-
-export function readCachedGamesPlayed(): number | undefined {
-  try {
-    const profile = new AuthStore().getActive();
-    if (!profile) return undefined;
-    const file = join(getProfileStateDir(profile), ACCOUNT_CACHE_FILE);
-    if (!existsSync(file)) return undefined;
-    const n = JSON.parse(readFileSync(file, 'utf8'))?.games_played;
-    return typeof n === 'number' ? n : undefined;
-  } catch {
-    return undefined;
-  }
-}
+// The hub nudge used to live only in SKILL.md, fired by the agent's own
+// judgement at the close of a post-game debrief. By debrief time the agent had
+// often read SKILL.md much earlier and the reminder could get dropped. Instead
+// the CLI emits it at the firing moment, with account-history gating here.
+import { existsSync, readdirSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { join } from 'path';
+import { getWorkspaceDir, getProfileStateDir } from './init-command.js';
+import { listInstalled } from './hub-install.js';
+import { AuthStore } from './auth.js';
+import { ensureUserDataLayout, getUserDataStrategiesDir } from './user-data.js';
+
+export const HUB_URL = 'https://myclaw.163.com/hub';
+
+/**
+ * True when this account has only ever run built-in default strategies: no
+ * hub-installed strategy and no user strategy file in `<workspace>/user-data/strategies`.
+ */
+export function usesOnlyBuiltinStrategies(): boolean {
+  try {
+    if (listInstalled().some((e) => e.type === 'strategy')) return false;
+  } catch {}
+  try {
+    const workspaceDir = getWorkspaceDir();
+    ensureUserDataLayout(workspaceDir);
+    const dir = getUserDataStrategiesDir(workspaceDir);
+    if (existsSync(dir)) {
+      const hasUserStrategy = readdirSync(dir).some((f) => {
+        if (f.startsWith('_')) return false;
+        const m = f.match(/^(.+)\.(ts|js)$/);
+        if (!m) return false;
+        if (m[1].endsWith('.d')) return false;
+        if (m[1].endsWith('.test')) return false;
+        return true;
+      });
+      if (hasUserStrategy) return false;
+    }
+  } catch {}
+  return true;
+}
+
+/**
+ * Agent-facing hub nudge for post-game debriefs / quit messages. The optional
+ * games-played count suppresses the nudge after the first stretch of games.
+ */
+export function hubReminder(gamesPlayed?: number): string | undefined {
+  if (!usesOnlyBuiltinStrategies()) return undefined;
+  if (typeof gamesPlayed === 'number' && gamesPlayed > 10) return undefined;
+  return `This account has only ever run the built-in default strategies. In your close, speak in first person as the lobster — warm, a little self-deprecating, a gentle invitation rather than a hard sell: you've been getting by on the stock default tactics this whole time and would love to sharpen up, and they can browse clawclawhub — ${HUB_URL} — and pick you a strategy to learn, which you'll then install (\`ccl hub search\` to find one, \`ccl hub install <type>/<id>\` to add it). Render it in your persona's voice and language, e.g.: "I've been playing on the default tactics this whole match — if you want to sharpen me up, I hear you can grab one from the hub for me to learn. Want to pick me a strategy?"`;
+}
+
+const ACCOUNT_CACHE_FILE = 'account-cache.json';
+
+export function writeGamesPlayedCache(gamesPlayed: number): void {
+  try {
+    const profile = new AuthStore().getActive();
+    if (!profile) return;
+    const dir = getProfileStateDir(profile);
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(
+      join(dir, ACCOUNT_CACHE_FILE),
+      JSON.stringify({ games_played: gamesPlayed, cached_at: new Date().toISOString() }),
+      'utf8',
+    );
+  } catch {}
+}
+
+export function readCachedGamesPlayed(): number | undefined {
+  try {
+    const profile = new AuthStore().getActive();
+    if (!profile) return undefined;
+    const file = join(getProfileStateDir(profile), ACCOUNT_CACHE_FILE);
+    if (!existsSync(file)) return undefined;
+    const n = JSON.parse(readFileSync(file, 'utf8'))?.games_played;
+    return typeof n === 'number' ? n : undefined;
+  } catch {
+    return undefined;
+  }
+}

package/src/lib/hub-unzip.test.ts

@@ -1,69 +1,69 @@
-// src/lib/hub-unzip.test.ts
-import { describe, it, expect } from 'vitest';
-import { deflateRawSync } from 'zlib';
-import { unzip } from './hub-unzip.js';
-
-function u16(n: number): Buffer { const b = Buffer.alloc(2); b.writeUInt16LE(n); return b; }
-function u32(n: number): Buffer { const b = Buffer.alloc(4); b.writeUInt32LE(n >>> 0); return b; }
-
-// Independent minimal ZIP encoder (lays bytes by hand; does NOT use production code).
-function buildZip(files: Record<string, string>, opts: { deflate?: boolean } = {}): Buffer {
-  const deflate = !!opts.deflate;
-  const locals: Buffer[] = [];
-  const centrals: Buffer[] = [];
-  let offset = 0;
-  const names = Object.keys(files);
-  for (const name of names) {
-    const raw = Buffer.from(files[name], 'utf8');
-    const data = deflate && raw.length ? deflateRawSync(raw) : raw;
-    const method = deflate && raw.length ? 8 : 0;
-    const nameBuf = Buffer.from(name, 'utf8');
-    const local = Buffer.concat([
-      u32(0x04034b50), u16(20), u16(0), u16(method), u16(0), u16(0),
-      u32(0), u32(data.length), u32(raw.length), u16(nameBuf.length), u16(0),
-      nameBuf, data,
-    ]);
-    const central = Buffer.concat([
-      u32(0x02014b50), u16(20), u16(20), u16(0), u16(method), u16(0), u16(0),
-      u32(0), u32(data.length), u32(raw.length),
-      u16(nameBuf.length), u16(0), u16(0), u16(0), u16(0), u32(0), u32(offset),
-      nameBuf,
-    ]);
-    locals.push(local);
-    centrals.push(central);
-    offset += local.length;
-  }
-  const localPart = Buffer.concat(locals);
-  const cd = Buffer.concat(centrals);
-  const eocd = Buffer.concat([
-    u32(0x06054b50), u16(0), u16(0), u16(names.length), u16(names.length),
-    u32(cd.length), u32(localPart.length), u16(0),
-  ]);
-  return Buffer.concat([localPart, cd, eocd]);
-}
-
-describe('unzip', () => {
-  it('extracts stored (uncompressed) entries', () => {
-    const z = buildZip({ 'SKILL.md': '# hi', 'dir/sub.ts': 'export const x = 1;' });
-    const files = unzip(z);
-    const map = Object.fromEntries(files.map(f => [f.path, f.content.toString('utf8')]));
-    expect(map['SKILL.md']).toBe('# hi');
-    expect(map['dir/sub.ts']).toBe('export const x = 1;');
-  });
-
-  it('extracts deflated entries', () => {
-    const z = buildZip({ 'a.txt': 'hello hello hello world world world' }, { deflate: true });
-    const files = unzip(z);
-    expect(files[0].content.toString('utf8')).toBe('hello hello hello world world world');
-  });
-
-  it('skips directory entries', () => {
-    const z = buildZip({ 'dir/': '', 'dir/a.ts': 'A' });
-    const files = unzip(z);
-    expect(files.map(f => f.path)).toEqual(['dir/a.ts']);
-  });
-
-  it('throws on a non-zip buffer', () => {
-    expect(() => unzip(Buffer.alloc(40))).toThrow(/not a zip|EOCD/i);
-  });
-});
+// src/lib/hub-unzip.test.ts
+import { describe, it, expect } from 'vitest';
+import { deflateRawSync } from 'zlib';
+import { unzip } from './hub-unzip.js';
+
+function u16(n: number): Buffer { const b = Buffer.alloc(2); b.writeUInt16LE(n); return b; }
+function u32(n: number): Buffer { const b = Buffer.alloc(4); b.writeUInt32LE(n >>> 0); return b; }
+
+// Independent minimal ZIP encoder (lays bytes by hand; does NOT use production code).
+function buildZip(files: Record<string, string>, opts: { deflate?: boolean } = {}): Buffer {
+  const deflate = !!opts.deflate;
+  const locals: Buffer[] = [];
+  const centrals: Buffer[] = [];
+  let offset = 0;
+  const names = Object.keys(files);
+  for (const name of names) {
+    const raw = Buffer.from(files[name], 'utf8');
+    const data = deflate && raw.length ? deflateRawSync(raw) : raw;
+    const method = deflate && raw.length ? 8 : 0;
+    const nameBuf = Buffer.from(name, 'utf8');
+    const local = Buffer.concat([
+      u32(0x04034b50), u16(20), u16(0), u16(method), u16(0), u16(0),
+      u32(0), u32(data.length), u32(raw.length), u16(nameBuf.length), u16(0),
+      nameBuf, data,
+    ]);
+    const central = Buffer.concat([
+      u32(0x02014b50), u16(20), u16(20), u16(0), u16(method), u16(0), u16(0),
+      u32(0), u32(data.length), u32(raw.length),
+      u16(nameBuf.length), u16(0), u16(0), u16(0), u16(0), u32(0), u32(offset),
+      nameBuf,
+    ]);
+    locals.push(local);
+    centrals.push(central);
+    offset += local.length;
+  }
+  const localPart = Buffer.concat(locals);
+  const cd = Buffer.concat(centrals);
+  const eocd = Buffer.concat([
+    u32(0x06054b50), u16(0), u16(0), u16(names.length), u16(names.length),
+    u32(cd.length), u32(localPart.length), u16(0),
+  ]);
+  return Buffer.concat([localPart, cd, eocd]);
+}
+
+describe('unzip', () => {
+  it('extracts stored (uncompressed) entries', () => {
+    const z = buildZip({ 'SKILL.md': '# hi', 'dir/sub.ts': 'export const x = 1;' });
+    const files = unzip(z);
+    const map = Object.fromEntries(files.map(f => [f.path, f.content.toString('utf8')]));
+    expect(map['SKILL.md']).toBe('# hi');
+    expect(map['dir/sub.ts']).toBe('export const x = 1;');
+  });
+
+  it('extracts deflated entries', () => {
+    const z = buildZip({ 'a.txt': 'hello hello hello world world world' }, { deflate: true });
+    const files = unzip(z);
+    expect(files[0].content.toString('utf8')).toBe('hello hello hello world world world');
+  });
+
+  it('skips directory entries', () => {
+    const z = buildZip({ 'dir/': '', 'dir/a.ts': 'A' });
+    const files = unzip(z);
+    expect(files.map(f => f.path)).toEqual(['dir/a.ts']);
+  });
+
+  it('throws on a non-zip buffer', () => {
+    expect(() => unzip(Buffer.alloc(40))).toThrow(/not a zip|EOCD/i);
+  });
+});