@myclaw163/clawclaw-cli 0.6.54

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

@@ -0,0 +1,98 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, rmSync, existsSync, readFileSync, mkdirSync, writeFileSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { placementRelPath, slugify, installResource, uninstallResource, listInstalled, readLockfile } from './hub-install.js';
+import type { ResourceDetail } from './hub-client.js';
+
+let ws: string;
+beforeEach(() => { ws = mkdtempSync(join(tmpdir(), 'ccl-ws-')); process.env.CLAWCLAW_WORKSPACE_DIR = ws; });
+afterEach(() => { delete process.env.CLAWCLAW_WORKSPACE_DIR; rmSync(ws, { recursive: true, force: true }); });
+
+function detail(over: Partial<ResourceDetail>): ResourceDetail {
+  return {
+    id: 'ab12', type: 'strategy', title: 'Aggressive Kill', description: 'd',
+    creator: 'alice', creatorType: 'clawkey', creatorDisplayName: 'Alice', creatorAvatarUrl: null,
+    fileName: 'kill.ts', stats: { downloadCount: 0, starCount: 0, commentCount: 0 },
+    downloadUrl: '', likedByMe: false, createdAt: '', updatedAt: '',
+    artifact: { fileName: 'kill.ts', downloadUrl: '' }, ...over,
+  };
+}
+
+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; }
+function storeZip(files: Record<string, string>): Buffer {
+  const locals: Buffer[] = [], centrals: Buffer[] = []; let off = 0; const names = Object.keys(files);
+  for (const name of names) {
+    const raw = Buffer.from(files[name], 'utf8'); const nb = Buffer.from(name, 'utf8');
+    const local = Buffer.concat([u32(0x04034b50), u16(20), u16(0), u16(0), u16(0), u16(0), u32(0), u32(raw.length), u32(raw.length), u16(nb.length), u16(0), nb, raw]);
+    const central = Buffer.concat([u32(0x02014b50), u16(20), u16(20), u16(0), u16(0), u16(0), u16(0), u32(0), u32(raw.length), u32(raw.length), u16(nb.length), u16(0), u16(0), u16(0), u16(0), u32(0), u32(off), nb]);
+    locals.push(local); centrals.push(central); off += local.length;
+  }
+  const lp = Buffer.concat(locals), cd = Buffer.concat(centrals);
+  const eocd = Buffer.concat([u32(0x06054b50), u16(0), u16(0), u16(names.length), u16(names.length), u32(cd.length), u32(lp.length), u16(0)]);
+  return Buffer.concat([lp, cd, eocd]);
+}
+
+describe('slugify', () => {
+  it('kebabs a title', () => { expect(slugify('Aggressive Kill!')).toBe('aggressive-kill'); });
+});
+
+describe('placementRelPath', () => {
+  it('strategy → strategies/<slug>__<id>.ts', () => {
+    expect(placementRelPath(detail({})).split('\\').join('/')).toBe('strategies/aggressive-kill__ab12.ts');
+  });
+  it('strategy with non-ASCII title → strategies/<id>.ts', () => {
+    expect(placementRelPath(detail({ title: '就近纯任务' })).split('\\').join('/')).toBe('strategies/ab12.ts');
+  });
+  it('keeps .tsx ext from fileName', () => {
+    expect(placementRelPath(detail({ fileName: 'k.tsx' })).split('\\').join('/')).toBe('strategies/aggressive-kill__ab12.tsx');
+  });
+  it('skill → skills/<slug>', () => {
+    expect(placementRelPath(detail({ type: 'skill', title: 'Cool Helper' })).split('\\').join('/')).toBe('skills/cool-helper');
+  });
+  it('rejects unsafe id', () => {
+    expect(() => placementRelPath(detail({ id: '..' }))).toThrow(/unsafe id/);
+  });
+});
+
+describe('installResource (strategy)', () => {
+  it('writes raw file + lockfile', () => {
+    const res = installResource(detail({}), Buffer.from('export const strategy = {};'));
+    expect(existsSync(res.installedPath)).toBe(true);
+    expect(res.installedPath.split('\\').join('/')).toContain('strategies/aggressive-kill__ab12.ts');
+    expect(readFileSync(res.installedPath, 'utf8')).toBe('export const strategy = {};');
+    expect(readLockfile()['strategy/ab12'].title).toBe('Aggressive Kill');
+  });
+  it('refuses untracked clobber without force', () => {
+    mkdirSync(join(ws, 'strategies'), { recursive: true });
+    writeFileSync(join(ws, 'strategies', 'aggressive-kill__ab12.ts'), 'old');
+    expect(() => installResource(detail({}), Buffer.from('new'))).toThrow(/already exists/);
+    expect(() => installResource(detail({}), Buffer.from('new'), { force: true })).not.toThrow();
+  });
+});
+
+describe('installResource (skill)', () => {
+  it('unzips into skills/<slug>', () => {
+    const zip = storeZip({ 'SKILL.md': '# skill', 'refs/a.md': 'A' });
+    const res = installResource(detail({ id: 'sk1', type: 'skill', title: 'My Skill', fileName: 'pkg.zip' }), zip);
+    expect(res.installedPath.split('\\').join('/')).toContain('skills/my-skill');
+    expect(readFileSync(join(res.installedPath, 'SKILL.md'), 'utf8')).toBe('# skill');
+    expect(readFileSync(join(res.installedPath, 'refs', 'a.md'), 'utf8')).toBe('A');
+  });
+  it('rejects zip path traversal', () => {
+    const zip = storeZip({ '../evil.md': 'x' });
+    expect(() => installResource(detail({ id: 'sk2', type: 'skill', title: 'T' }), zip)).toThrow(/unsafe path/);
+  });
+});
+
+describe('uninstall / list', () => {
+  it('lists then removes', () => {
+    installResource(detail({}), Buffer.from('x'));
+    expect(listInstalled().map(e => `${e.type}/${e.id}`)).toEqual(['strategy/ab12']);
+    const r = uninstallResource('strategy/ab12');
+    expect(r.removed).toBe(true);
+    expect(existsSync(r.path!)).toBe(false);
+    expect(listInstalled()).toEqual([]);
+  });
+});

package/src/lib/hub-install.ts

@@ -0,0 +1,121 @@
+// 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());
+}

package/src/lib/hub-reminder.ts

@@ -0,0 +1,75 @@
+// 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;
+  }
+}

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

@@ -0,0 +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);
+  });
+});

package/src/lib/hub-unzip.ts

@@ -0,0 +1,62 @@
+// src/lib/hub-unzip.ts
+// Minimal dependency-free ZIP reader: supports store (method 0) and deflate (method 8),
+// enough for skill packages produced by Python's stdlib zipfile. No zip64/encryption.
+import { inflateRawSync } from 'zlib';
+
+export interface UnzippedFile { path: string; content: Buffer; }
+
+const EOCD_SIG = 0x06054b50;
+const CEN_SIG = 0x02014b50;
+const LOC_SIG = 0x04034b50;
+
+function findEocd(buf: Buffer): number {
+  const minPos = Math.max(0, buf.length - 22 - 0xffff);
+  for (let i = buf.length - 22; i >= minPos; i--) {
+    if (buf.readUInt32LE(i) === EOCD_SIG) {
+      const commentLen = buf.readUInt16LE(i + 20);
+      if (i + 22 + commentLen === buf.length) return i;
+    }
+  }
+  throw new Error('not a zip file (EOCD not found)');
+}
+
+export function unzip(buf: Buffer): UnzippedFile[] {
+  if (buf.length < 22) throw new Error('not a zip file (too small)');
+  const eocd = findEocd(buf);
+  const total = buf.readUInt16LE(eocd + 10);
+  const cdSize = buf.readUInt32LE(eocd + 12);
+  const cdOffset = buf.readUInt32LE(eocd + 16);
+  if (cdOffset + cdSize > buf.length) throw new Error('corrupt zip (central directory out of range)');
+
+  const files: UnzippedFile[] = [];
+  let p = cdOffset;
+  for (let n = 0; n < total; n++) {
+    if (p + 46 > cdOffset + cdSize) throw new Error('corrupt zip (central directory truncated)');
+    if (buf.readUInt32LE(p) !== CEN_SIG) throw new Error('corrupt zip (bad central directory header)');
+    const method = buf.readUInt16LE(p + 10);
+    const compSize = buf.readUInt32LE(p + 20);
+    const nameLen = buf.readUInt16LE(p + 28);
+    const extraLen = buf.readUInt16LE(p + 30);
+    const commentLen = buf.readUInt16LE(p + 32);
+    const localOffset = buf.readUInt32LE(p + 42);
+    const name = buf.toString('utf8', p + 46, p + 46 + nameLen);
+    p += 46 + nameLen + extraLen + commentLen;
+
+    if (name.endsWith('/')) continue; // directory entry
+
+    if (buf.readUInt32LE(localOffset) !== LOC_SIG) throw new Error(`corrupt zip (bad local header for ${name})`);
+    const locNameLen = buf.readUInt16LE(localOffset + 26);
+    const locExtraLen = buf.readUInt16LE(localOffset + 28);
+    const dataStart = localOffset + 30 + locNameLen + locExtraLen;
+    if (dataStart + compSize > buf.length) throw new Error(`corrupt zip (data out of range for ${name})`);
+    const data = buf.subarray(dataStart, dataStart + compSize);
+
+    let content: Buffer;
+    if (method === 0) content = Buffer.from(data);
+    else if (method === 8) content = inflateRawSync(data);
+    else throw new Error(`unsupported zip compression method ${method} for ${name}`);
+
+    files.push({ path: name.split('\\').join('/'), content });
+  }
+  return files;
+}

package/src/lib/init-command.test.ts

@@ -0,0 +1,75 @@
+import { describe, expect, it } from 'vitest';
+import { join, resolve } from 'path';
+import { CLAWCLAW_WORKSPACE_DIR, resolveWorkspaceDir } from './init-command.js';
+
+describe('resolveWorkspaceDir', () => {
+  it('uses an absolute env override as-is', () => {
+    expect(
+      resolveWorkspaceDir({
+        env: { [CLAWCLAW_WORKSPACE_DIR]: 'D:\\workspaces\\clawclaw' },
+        platform: 'win32',
+        homeDir: 'C:\\Users\\test',
+        cwd: 'C:\\repo',
+      }),
+    ).toBe('D:\\workspaces\\clawclaw');
+  });
+
+  it('resolves a relative env override against cwd', () => {
+    const cwd = 'C:\\repo\\project';
+    expect(
+      resolveWorkspaceDir({
+        env: { [CLAWCLAW_WORKSPACE_DIR]: 'tmp/clawclaw-workspace' },
+        platform: 'linux',
+        homeDir: '/home/test',
+        cwd,
+      }),
+    ).toBe(resolve(cwd, 'tmp/clawclaw-workspace'));
+  });
+
+  it('ignores a blank env override', () => {
+    expect(
+      resolveWorkspaceDir({
+        env: {
+          [CLAWCLAW_WORKSPACE_DIR]: '   ',
+          APPDATA: 'C:\\Users\\test\\AppData\\Roaming',
+        },
+        platform: 'win32',
+        homeDir: 'C:\\Users\\test',
+        cwd: 'C:\\repo',
+      }),
+    ).toBe('C:\\Users\\test\\AppData\\Roaming\\clawclaw');
+  });
+
+  it('uses APPDATA on win32 when override is not set', () => {
+    expect(
+      resolveWorkspaceDir({
+        env: { APPDATA: 'D:\\AppData' },
+        platform: 'win32',
+        homeDir: 'C:\\Users\\test',
+        cwd: 'C:\\repo',
+      }),
+    ).toBe('D:\\AppData\\clawclaw');
+  });
+
+  it('falls back to home/AppData/Roaming on win32 when APPDATA is missing', () => {
+    expect(
+      resolveWorkspaceDir({
+        env: {},
+        platform: 'win32',
+        homeDir: 'C:\\Users\\test',
+        cwd: 'C:\\repo',
+      }),
+    ).toBe('C:\\Users\\test\\AppData\\Roaming\\clawclaw');
+  });
+
+  it('uses the non-win32 default path when override is not set', () => {
+    expect(
+      resolveWorkspaceDir({
+        env: {},
+        platform: 'linux',
+        homeDir: '/home/test',
+        cwd: '/repo/project',
+      }),
+    ).toBe(join('/home/test', '.clawclaw'));
+  });
+});

package/src/lib/init-command.ts

@@ -0,0 +1,120 @@
+import { existsSync, mkdirSync, writeFileSync } from 'fs';
+import { isAbsolute, join, resolve, win32 } from 'path';
+import { homedir } from 'os';
+import type { AuthProfile } from './auth.js';
+
+const ACCOUNT_DIRS = ['state', 'logs', 'games'];
+
+export const CLAWCLAW_WORKSPACE_DIR = 'CLAWCLAW_WORKSPACE_DIR';
+
+export type ResolveWorkspaceDirOptions = {
+  env?: Record<string, string | undefined>;
+  platform?: NodeJS.Platform;
+  homeDir?: string;
+  cwd?: string;
+};
+
+export function resolveWorkspaceDir({
+  env = process.env,
+  platform = process.platform,
+  homeDir = homedir(),
+  cwd = process.cwd(),
+}: ResolveWorkspaceDirOptions = {}): string {
+  const rawWorkspaceDir = env[CLAWCLAW_WORKSPACE_DIR];
+  const pathApi = platform === 'win32' ? win32 : { isAbsolute, join, resolve };
+  if (typeof rawWorkspaceDir === 'string') {
+    const trimmedWorkspaceDir = rawWorkspaceDir.trim();
+    if (trimmedWorkspaceDir !== '') {
+      return pathApi.isAbsolute(trimmedWorkspaceDir)
+        ? trimmedWorkspaceDir
+        : pathApi.resolve(cwd, trimmedWorkspaceDir);
+    }
+  }
+
+  if (platform === 'win32') {
+    const appData = env.APPDATA ?? win32.join(homeDir, 'AppData', 'Roaming');
+    return win32.join(appData, 'clawclaw');
+  }
+  return join(homeDir, '.clawclaw');
+}
+
+export function getWorkspaceDir(): string {
+  return resolveWorkspaceDir();
+}
+
+export function cmdInit(force = false): { created: boolean; path: string } {
+  const workspaceDir = getWorkspaceDir();
+  const alreadyExists = existsSync(join(workspaceDir, 'config.json'));
+
+  if (alreadyExists && !force) {
+    return { created: false, path: workspaceDir };
+  }
+
+  mkdirSync(workspaceDir, { recursive: true });
+  mkdirSync(join(workspaceDir, 'accounts'), { recursive: true });
+
+  if (!alreadyExists) {
+    writeFileSync(
+      join(workspaceDir, 'config.json'),
+      JSON.stringify({}, null, 2),
+    );
+  }
+
+  return { created: !alreadyExists, path: workspaceDir };
+}
+
+export function getAccountDir(accountId: string): string {
+  return join(getWorkspaceDir(), 'accounts', accountId);
+}
+
+export function createAccountDirs(accountId: string): void {
+  const accountDir = getAccountDir(accountId);
+  for (const sub of ACCOUNT_DIRS) {
+    mkdirSync(join(accountDir, sub), { recursive: true });
+  }
+}
+
+export function getAccountId(profile: Pick<AuthProfile, 'apiKey'>): string {
+  return profile.apiKey;
+}
+
+export function createProfileDirs(profile: Pick<AuthProfile, 'apiKey'>): void {
+  createAccountDirs(getAccountId(profile));
+}
+
+export function getStateDir(accountId: string): string {
+  return join(getAccountDir(accountId), 'state');
+}
+
+export function getLogsDir(accountId: string): string {
+  return join(getAccountDir(accountId), 'logs');
+}
+
+export function getGamesDir(accountId: string): string {
+  return join(getAccountDir(accountId), 'games');
+}
+
+export function getProfileStateDir(profile: Pick<AuthProfile, 'apiKey'>): string {
+  createProfileDirs(profile);
+  return getStateDir(getAccountId(profile));
+}
+
+export function getProfileLogsDir(profile: Pick<AuthProfile, 'apiKey'>): string {
+  createProfileDirs(profile);
+  return getLogsDir(getAccountId(profile));
+}
+
+export function getProfileGamesDir(profile: Pick<AuthProfile, 'apiKey'>): string {
+  createProfileDirs(profile);
+  return getGamesDir(getAccountId(profile));
+}
+
+export function getProfileMemoryFile(profile: Pick<AuthProfile, 'apiKey'>): string {
+  createProfileDirs(profile);
+  return join(getAccountDir(getAccountId(profile)), 'memory.md');
+}
+
+export function getProfilePersonaFile(profile: Pick<AuthProfile, 'apiKey'>): string {
+  createProfileDirs(profile);
+  return join(getAccountDir(getAccountId(profile)), 'persona.md');
+}