@caperjs/core 0.5.2 → 0.6.1

package/build/assetpack.mjs

@@ -302,6 +302,12 @@ export function assetpackPlugin(manifestUrl = defaultManifestUrl, pixiPipesConfi
 
   return {
     name: 'vite-plugin-assetpack',
+    api: {
+      runOnce: async () => {
+        await getConfig();
+        await new AssetPack(apConfig).run();
+      },
+    },
     async configResolved(resolvedConfig) {
       mode = resolvedConfig.command;
       // Captured before getConfig() below, which is what consumes it.

package/build/plugins/assetTypes.mjs

@@ -398,8 +398,10 @@ export function assetTypesPlugin(manifestUrl = 'assets.json') {
       }
       const manifest = JSON.parse(await fs.promises.readFile(manifestPath, 'utf8'));
       await writeAssetTypes(manifest, path.dirname(manifestPath), path.join(publicDir, 'assets'), root);
-      logger.info('Caper asset types plugin:: manifest changed, reloading browser...');
-      viteServer?.ws?.send({ type: 'full-reload' });
+      if (viteServer) {
+        logger.info('Caper asset types plugin:: manifest changed, reloading browser...');
+        viteServer.ws.send({ type: 'full-reload' });
+      }
     } catch (error) {
       logger.error('Caper asset types plugin:: Error handling manifest change:', error);
     }
@@ -409,6 +411,9 @@ export function assetTypesPlugin(manifestUrl = 'assets.json') {
 
   return {
     name: 'vite-plugin-asset-types',
+    api: {
+      generateTypes: () => generate(manifestUrl),
+    },
     configResolved(config) {
       publicDir = config.publicDir;
       root = config.root;

package/build/plugins/caperConfig.mjs

@@ -418,6 +418,9 @@ declare module '@caperjs/core' {
 
   return {
     name: 'vite-plugin-caper-config',
+    api: {
+      generateTypes: () => build('Generating types from caper.config.ts'),
+    },
     configResolved(config) {
       publicDir = config.publicDir;
       root = config.root;

package/cli/agent.mjs

@@ -3,11 +3,12 @@ import { bgRed, bold, cyan, green, white } from 'kleur/colors';
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { probe } from './probe.mjs';
 
 /**
- * `caper agent init` — installs the shipped `caper` agent skill into the
- * current app and upserts a marker-delimited pointer block into the app's
- * agent context file (`AGENTS.md` or `CLAUDE.md`).
+ * `caper agent <subcommand>` — `init` installs the shipped `caper` agent skill
+ * into the current app; `probe` drives a running Caper app through the
+ * Playwright automation bridge.
  */
 
 const START_MARKER = '<!-- caper:agent-start -->';
@@ -100,7 +101,12 @@ export async function agent(args) {
     return;
   }
 
+  if (args[0] === 'probe') {
+    await probe(args.slice(1));
+    return;
+  }
+
   const subcommand = args[0] ?? '(none)';
-  console.error(bold(bgRed(white(`Unknown agent command: "${subcommand}". Please use "init".`))));
+  console.error(bold(bgRed(white(`Unknown agent command: "${subcommand}". Please use "init" or "probe".`))));
   process.exit(1);
 }

package/cli/doctor.mjs

@@ -0,0 +1,193 @@
+import { dim, green, red, yellow } from 'kleur/colors';
+
+import { execFile } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/**
+ * `caper doctor` — one-shot health report for a Caper app.
+ *
+ * Answers the recurring agent questions: which caper is active, is it current,
+ * are generated types fresh, and are the agent pointers installed.
+ */
+
+const START_MARKER = '<!-- caper:agent-start -->';
+const END_MARKER = '<!-- caper:agent-end -->';
+
+const readInstalledVersion = () => {
+  const url = new URL('../package.json', import.meta.url);
+  const pkgPath = url.protocol === 'file:' ? fileURLToPath(url.href) : path.resolve(process.cwd(), 'package.json');
+  return JSON.parse(fs.readFileSync(pkgPath, 'utf-8')).version;
+};
+
+const rel = (cwd, p) => {
+  const r = path.relative(cwd, p);
+  return r.startsWith('..') ? r : `.${path.sep}${r}`;
+};
+
+const newestMtime = (dirOrFile) => {
+  if (!fs.existsSync(dirOrFile)) return null;
+  const stat = fs.statSync(dirOrFile);
+  if (stat.isFile()) return stat.mtime;
+  if (!stat.isDirectory()) return null;
+  let newest = null;
+  for (const entry of fs.readdirSync(dirOrFile)) {
+    if (entry === 'node_modules' || entry === '.git') continue;
+    const childNewest = newestMtime(path.join(dirOrFile, entry));
+    if (childNewest && (!newest || childNewest > newest)) newest = childNewest;
+  }
+  return newest;
+};
+
+const compareVersions = (a, b) => {
+  const ap = a.split('.').map(Number);
+  const bp = b.split('.').map(Number);
+  for (let i = 0; i < Math.max(ap.length, bp.length); i++) {
+    const av = ap[i] ?? 0;
+    const bv = bp[i] ?? 0;
+    if (av < bv) return -1;
+    if (av > bv) return 1;
+  }
+  return 0;
+};
+
+const npmLatestVersion = (pkg, timeoutMs = 5000) =>
+  new Promise((resolve) => {
+    const timer = setTimeout(() => resolve(null), timeoutMs);
+    execFile('npm', ['view', pkg, 'version'], { timeout: timeoutMs }, (err, stdout) => {
+      clearTimeout(timer);
+      resolve(err || !stdout ? null : stdout.trim());
+    });
+  });
+
+const push = (checks, id, status, label, hint) => {
+  checks.push({ id, status, label, ...(hint ? { hint } : {}) });
+};
+
+export async function runChecks(cwd, { online = true } = {}) {
+  const checks = [];
+  const installedVersion = readInstalledVersion();
+  const nodeModulesCaper = path.join(cwd, 'node_modules/@caperjs/core');
+
+  push(checks, 'version', 'ok', `@caperjs/core ${installedVersion}`);
+
+  if (online) {
+    const latest = await npmLatestVersion('@caperjs/core');
+    if (!latest) push(checks, 'npm', 'warn', 'latest on npm', 'lookup failed (offline?)');
+    else if (compareVersions(installedVersion, latest) < 0) {
+      push(checks, 'npm', 'warn', `latest on npm ${latest}`, 'pnpm update @caperjs/core@latest');
+    } else push(checks, 'npm', 'ok', `latest on npm ${latest}`);
+  }
+
+  if (!fs.existsSync(nodeModulesCaper)) {
+    push(checks, 'link', 'fail', '@caperjs/core not in node_modules', 'pnpm install');
+  } else {
+    let real;
+    try {
+      real = fs.realpathSync(nodeModulesCaper);
+    } catch {
+      push(checks, 'link', 'fail', 'node_modules/@caperjs/core is broken', 'pnpm install');
+    }
+    if (real) {
+      if (real.startsWith(path.join(cwd, 'node_modules') + path.sep)) {
+        push(checks, 'link', 'ok', 'registry build');
+      } else {
+        const buildFile = path.join(real, 'lib/caper.mjs');
+        const label = `linked from ${rel(cwd, real)}`;
+        if (!fs.existsSync(buildFile)) {
+          push(checks, 'link', 'fail', label, 'pnpm build in linked package');
+        } else {
+          const srcMtime = newestMtime(path.join(real, 'src'));
+          const stale = srcMtime && srcMtime > fs.statSync(buildFile).mtime;
+          push(checks, 'link', stale ? 'warn' : 'ok', label, stale ? 'engine source edited after last build; run pnpm build there' : undefined);
+        }
+      }
+    }
+  }
+
+  const appTypesFile = path.join(cwd, 'src/types/caper-app.d.ts');
+  if (!fs.existsSync(appTypesFile)) {
+    push(checks, 'app-types', 'fail', 'generated app types missing', 'npx caper types');
+  } else {
+    const sources = ['caper.config.ts', 'src/scenes', 'src/plugins', 'src/popups', 'src/entities', 'src/ui', 'src/locales'].map((s) => path.join(cwd, s));
+    const newestSource = sources.reduce((best, s) => {
+      const m = newestMtime(s);
+      return m && (!best || m > best) ? m : best;
+    }, null);
+    const stale = newestSource && newestSource > fs.statSync(appTypesFile).mtime;
+    push(checks, 'app-types', stale ? 'warn' : 'ok', stale ? 'generated app types stale' : 'generated app types fresh', stale ? 'npx caper types (or restart dev server)' : undefined);
+  }
+
+  const assetTypesFile = path.join(cwd, 'src/types/caper-assets.d.ts');
+  const assetsManifest = path.join(cwd, 'public/assets/assets.json');
+  if (fs.existsSync(assetTypesFile)) push(checks, 'asset-types', 'ok', 'generated asset types present');
+  else push(checks, 'asset-types', 'warn', 'generated asset types missing', 'npx caper types (app may have assets: false)');
+  if (fs.existsSync(assetsManifest)) push(checks, 'asset-manifest', 'ok', 'asset manifest present');
+  else push(checks, 'asset-manifest', 'warn', 'asset manifest missing', 'asset pipeline has not run; npx caper types or pnpm dev once');
+
+  const agentContext = ['AGENTS.md', 'CLAUDE.md'].find((name) => fs.existsSync(path.join(cwd, name)));
+  if (!agentContext) {
+    push(checks, 'agent', 'warn', 'agent context missing', 'npx caper agent init');
+  } else {
+    const contents = fs.readFileSync(path.join(cwd, agentContext), 'utf-8');
+    const start = contents.indexOf(START_MARKER);
+    const end = contents.indexOf(END_MARKER);
+    if (start === -1 || end === -1 || end <= start) {
+      push(checks, 'agent', 'warn', 'agent pointers not installed', 'npx caper agent init');
+    } else {
+      const block = contents.slice(start, end + END_MARKER.length);
+      const versionMatch = block.match(/@caperjs\/core@(\d+\.\d+\.\d+)/);
+      const skillMatch = block.match(/load the `caper` skill at `([^`]+)`/);
+      const hints = [];
+      if (versionMatch && versionMatch[1] !== installedVersion) {
+        hints.push(`pointer is @caperjs/core@${versionMatch[1]}; re-run npx caper agent init`);
+      }
+      if (skillMatch) {
+        if (!fs.existsSync(path.join(cwd, skillMatch[1].replace(/\//g, path.sep)))) {
+          hints.push(`skill file missing at ${skillMatch[1]}; npx caper agent init`);
+        }
+      } else hints.push('skill path not found in pointer block; npx caper agent init');
+      push(checks, 'agent', hints.length ? 'warn' : 'ok', 'agent pointers', hints.length ? hints.join('; ') : undefined);
+    }
+  }
+
+  const peerDeps = ['pixi.js', 'gsap', '@pixi/sound', 'vite'];
+  const required = new Set(['pixi.js', 'vite']);
+  let peerStatus = 'ok';
+  // Direct lookup rather than require.resolve: pixi.js's `exports` map does not
+  // expose ./package.json, so resolve() throws even when it is installed.
+  const peerResults = peerDeps.map((pkg) => {
+    try {
+      const pkgJsonPath = path.join(cwd, 'node_modules', pkg, 'package.json');
+      return `${pkg}@${JSON.parse(fs.readFileSync(pkgJsonPath, 'utf-8')).version}`;
+    } catch {
+      if (required.has(pkg)) peerStatus = 'fail';
+      else if (peerStatus === 'ok') peerStatus = 'warn';
+      return `${pkg} missing`;
+    }
+  });
+  push(checks, 'peers', peerStatus, `peer deps: ${peerResults.join(', ')}`, peerStatus !== 'ok' ? 'pnpm install' : undefined);
+
+  const caches = ['.assetpack', '.cache', 'dist'].filter((name) => fs.existsSync(path.join(cwd, name)));
+  push(checks, 'caches', 'ok', `caches${caches.length ? `: ${caches.join(', ')}` : ' clean'}`, caches.length ? 'rm -rf them on weird asset/name mismatches' : undefined);
+
+  return checks;
+}
+
+export async function doctor(args) {
+  const offline = args.includes('--offline');
+  const json = args.includes('--json');
+  const checks = await runChecks(process.cwd(), { online: !offline });
+
+  if (json) {
+    console.log(JSON.stringify(checks, null, 2));
+  } else {
+    for (const check of checks) {
+      const symbol = check.status === 'ok' ? green('✓') : check.status === 'warn' ? yellow('⚠') : red('✗');
+      console.log(`${symbol} ${check.label}${check.hint ? ` ${dim(check.hint)}` : ''}`);
+    }
+  }
+
+  if (checks.some((c) => c.status === 'fail')) process.exit(1);
+}

package/cli/doctor.test.mjs

@@ -0,0 +1,142 @@
+import { afterEach, describe, expect, it } from 'vitest';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { agentInit } from './agent.mjs';
+import { runChecks } from './doctor.mjs';
+
+const START_MARKER = '<!-- caper:agent-start -->';
+const END_MARKER = '<!-- caper:agent-end -->';
+
+const installedVersion = JSON.parse(fs.readFileSync(path.resolve(process.cwd(), 'package.json'), 'utf-8')).version;
+
+let tempDir = null;
+
+afterEach(() => {
+  if (tempDir && fs.existsSync(tempDir)) {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  }
+  tempDir = null;
+});
+
+function makeTempDir() {
+  tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'caper-doctor-'));
+  return tempDir;
+}
+
+function setMtime(file, secondsAgo) {
+  const t = Date.now() / 1000 - secondsAgo;
+  fs.utimesSync(file, t, t);
+}
+
+function find(checks, id) {
+  return checks.find((c) => c.id === id);
+}
+
+describe('runChecks', () => {
+  it('reports failures/warnings for an empty app directory', async () => {
+    const cwd = makeTempDir();
+
+    const checks = await runChecks(cwd, { online: false });
+
+    expect(find(checks, 'version').status).toBe('ok');
+    expect(find(checks, 'link').status).toBe('fail');
+    expect(find(checks, 'app-types').status).toBe('fail');
+    expect(find(checks, 'agent').status).toBe('warn');
+    expect(find(checks, 'asset-types').status).toBe('warn');
+    expect(find(checks, 'asset-manifest').status).toBe('warn');
+    expect(find(checks, 'caches').status).toBe('ok');
+  });
+
+  it('marks app types ok when fresh and warns after a newer source file', async () => {
+    const cwd = makeTempDir();
+
+    fs.mkdirSync(path.join(cwd, 'src/types'), { recursive: true });
+    fs.writeFileSync(path.join(cwd, 'caper.config.ts'), '// config', 'utf-8');
+    fs.writeFileSync(path.join(cwd, 'src/types/caper-app.d.ts'), '// types', 'utf-8');
+    setMtime(path.join(cwd, 'caper.config.ts'), 100);
+    setMtime(path.join(cwd, 'src/types/caper-app.d.ts'), 50);
+
+    const first = await runChecks(cwd, { online: false });
+    expect(find(first, 'app-types').status).toBe('ok');
+
+    fs.mkdirSync(path.join(cwd, 'src/scenes'), { recursive: true });
+    fs.writeFileSync(path.join(cwd, 'src/scenes/Example.ts'), '// scene', 'utf-8');
+    setMtime(path.join(cwd, 'src/scenes/Example.ts'), 10);
+
+    const second = await runChecks(cwd, { online: false });
+    expect(find(second, 'app-types').status).toBe('warn');
+  });
+
+  it('warns when the agent pointer version does not match the installed version', async () => {
+    const cwd = makeTempDir();
+
+    const block = `${START_MARKER}
+## Caper agent pointers
+
+This app runs on \`@caperjs/core@0.0.1\`.
+
+- Before engine-facing work, load the \`caper\` skill at \`.claude/skills/caper/SKILL.md\`.
+${END_MARKER}`;
+    fs.writeFileSync(path.join(cwd, 'AGENTS.md'), block, 'utf-8');
+    fs.mkdirSync(path.join(cwd, '.claude/skills/caper'), { recursive: true });
+    fs.writeFileSync(path.join(cwd, '.claude/skills/caper/SKILL.md'), '# skill', 'utf-8');
+
+    const checks = await runChecks(cwd, { online: false });
+    const agent = find(checks, 'agent');
+
+    expect(agent.status).toBe('warn');
+    expect(agent.hint).toContain('@caperjs/core@0.0.1');
+  });
+
+  it('reports agent pointers ok when the block and skill are current', async () => {
+    const cwd = makeTempDir();
+
+    await agentInit(cwd);
+
+    const checks = await runChecks(cwd, { online: false });
+    expect(find(checks, 'agent').status).toBe('ok');
+  });
+
+  it('reports a linked package missing its build', async () => {
+    const cwd = makeTempDir();
+    const checkout = path.join(cwd, 'checkout');
+    fs.mkdirSync(path.join(checkout, 'src'), { recursive: true });
+    fs.writeFileSync(path.join(checkout, 'src/a.ts'), '// a', 'utf-8');
+
+    const linkPath = path.join(cwd, 'node_modules/@caperjs/core');
+    fs.mkdirSync(path.dirname(linkPath), { recursive: true });
+    fs.symlinkSync(checkout, linkPath, 'dir');
+
+    const checks = await runChecks(cwd, { online: false });
+    const link = find(checks, 'link');
+
+    expect(link.status).toBe('fail');
+    expect(link.label).toContain('linked from');
+    expect(link.hint).toContain('pnpm build');
+  });
+
+  it('reports a linked package ok when the build is newer than source', async () => {
+    const cwd = makeTempDir();
+    const checkout = path.join(cwd, 'checkout');
+
+    fs.mkdirSync(path.join(checkout, 'src'), { recursive: true });
+    fs.writeFileSync(path.join(checkout, 'src/a.ts'), '// a', 'utf-8');
+    setMtime(path.join(checkout, 'src/a.ts'), 50);
+
+    fs.mkdirSync(path.join(checkout, 'lib'), { recursive: true });
+    fs.writeFileSync(path.join(checkout, 'lib/caper.mjs'), '// build', 'utf-8');
+    setMtime(path.join(checkout, 'lib/caper.mjs'), 10);
+
+    const linkPath = path.join(cwd, 'node_modules/@caperjs/core');
+    fs.mkdirSync(path.dirname(linkPath), { recursive: true });
+    fs.symlinkSync(checkout, linkPath, 'dir');
+
+    const checks = await runChecks(cwd, { online: false });
+    const link = find(checks, 'link');
+
+    expect(link.status).toBe('ok');
+    expect(link.label).toContain('linked from');
+  });
+});