@caperjs/core 0.5.1 → 0.6.0

package/cli/probe.mjs

@@ -0,0 +1,368 @@
+import { bgRed, bold, cyan, green, red, white, yellow } from 'kleur/colors';
+
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+/**
+ * `caper agent probe <url>` — drive a running Caper app through the
+ * `window.Caper.automation` Playwright bridge. Boot detection, action
+ * dispatch, state/context reads, and optional screenshot, all in one shot.
+ */
+
+const DEFAULT_TIMEOUT_MS = 15_000;
+const DEFAULT_VIEWPORT_W = 1280;
+const DEFAULT_VIEWPORT_H = 720;
+const DEFAULT_LOG_TAIL = 50;
+
+/**
+ * Parse the raw CLI arguments for `caper agent probe`.
+ *
+ * @param {string[]} args
+ * @returns {{
+ *   url: string,
+ *   actions: { name: string, data?: unknown }[],
+ *   until?: string,
+ *   waitMs: number,
+ *   timeoutMs: number,
+ *   appId?: string,
+ *   screenshot?: string,
+ *   headed: boolean,
+ *   json: boolean,
+ *   viewport: { width: number, height: number }
+ * }}
+ */
+export function parseProbeArgs(args) {
+  const result = {
+    url: '',
+    actions: [],
+    until: undefined,
+    waitMs: 0,
+    timeoutMs: DEFAULT_TIMEOUT_MS,
+    appId: undefined,
+    screenshot: undefined,
+    headed: false,
+    json: false,
+    viewport: { width: DEFAULT_VIEWPORT_W, height: DEFAULT_VIEWPORT_H },
+  };
+
+  let i = 0;
+  while (i < args.length) {
+    const arg = args[i];
+
+    if (arg === '--action') {
+      const next = args[++i];
+      if (!next) throw new Error('Missing value for --action');
+      const eq = next.indexOf('=');
+      const name = eq >= 0 ? next.slice(0, eq) : next;
+      const rawData = eq >= 0 ? next.slice(eq + 1) : undefined;
+      let data;
+      if (rawData !== undefined) {
+        try {
+          data = JSON.parse(rawData);
+        } catch {
+          throw new Error(`Invalid JSON data in --action ${JSON.stringify(next)}`);
+        }
+      }
+      result.actions.push(data !== undefined ? { name, data } : { name });
+    } else if (arg === '--until') {
+      const next = args[++i];
+      if (!next) throw new Error('Missing value for --until');
+      result.until = next;
+    } else if (arg === '--wait') {
+      const next = args[++i];
+      if (!next) throw new Error('Missing value for --wait');
+      const ms = Number(next);
+      if (!Number.isFinite(ms) || ms < 0) throw new Error(`Invalid --wait value: ${next}`);
+      result.waitMs = ms;
+    } else if (arg === '--timeout') {
+      const next = args[++i];
+      if (!next) throw new Error('Missing value for --timeout');
+      const ms = Number(next);
+      if (!Number.isFinite(ms) || ms < 0) throw new Error(`Invalid --timeout value: ${next}`);
+      result.timeoutMs = ms;
+    } else if (arg === '--app') {
+      const next = args[++i];
+      if (!next) throw new Error('Missing value for --app');
+      result.appId = next;
+    } else if (arg === '--screenshot') {
+      const next = args[++i];
+      if (!next) throw new Error('Missing value for --screenshot');
+      result.screenshot = next;
+    } else if (arg === '--headed') {
+      result.headed = true;
+    } else if (arg === '--json') {
+      result.json = true;
+    } else if (arg === '--viewport') {
+      const next = args[++i];
+      if (!next) throw new Error('Missing value for --viewport');
+      const match = next.match(/^(\d+)x(\d+)$/i);
+      if (!match) throw new Error(`Invalid --viewport value: ${next} (expected WxH)`);
+      result.viewport = { width: Number(match[1]), height: Number(match[2]) };
+    } else if (arg.startsWith('--')) {
+      throw new Error(`Unknown option: ${arg}`);
+    } else if (!result.url) {
+      result.url = arg;
+    } else {
+      throw new Error(`Unexpected positional argument: ${arg}`);
+    }
+
+    i++;
+  }
+
+  if (!result.url) {
+    throw new Error('Missing required <url> argument');
+  }
+
+  return result;
+}
+
+function printUsage() {
+  console.error(red('Usage: caper agent probe <url> [options]'));
+  console.error('');
+  console.error('Options:');
+  console.error('  --action <name>[=<json>]   dispatch action(s) in order');
+  console.error('  --until <js-predicate>     wait for state predicate to return true');
+  console.error('  --wait <ms>                sleep after actions (default 0)');
+  console.error('  --timeout <ms>             boot and until timeout (default 15000)');
+  console.error('  --app <id>                 target a specific app');
+  console.error('  --screenshot <path>        save a PNG screenshot');
+  console.error('  --headed                   run in headed mode');
+  console.error('  --json                     print JSON result only');
+  console.error('  --viewport WxH             viewport size (default 1280x720)');
+}
+
+async function resolvePlaywright() {
+  const pkgJson = path.join(process.cwd(), 'package.json');
+  const require = createRequire(pkgJson);
+  const resolved = require.resolve('playwright');
+  const mod = await import(pathToFileURL(resolved).href);
+  // Playwright's CJS entry re-exports via default when dynamically imported.
+  return mod.default ?? mod;
+}
+
+/**
+ * Run the `caper agent probe` command.
+ *
+ * @param {string[]} args
+ */
+export async function probe(args) {
+  let parsed;
+  try {
+    parsed = parseProbeArgs(args);
+  } catch (err) {
+    console.error(bold(bgRed(white(` ${err.message} `))));
+    printUsage();
+    process.exit(1);
+  }
+
+  const {
+    url,
+    actions,
+    until,
+    waitMs,
+    timeoutMs,
+    appId,
+    screenshot,
+    headed,
+    json,
+    viewport,
+  } = parsed;
+
+  let playwright;
+  try {
+    playwright = await resolvePlaywright();
+  } catch {
+    console.error(
+      red('playwright is not installed in the current project.'),
+      'Run:',
+      cyan('pnpm add -D playwright && npx playwright install chromium'),
+    );
+    process.exit(2);
+  }
+
+  const startTime = Date.now();
+  const pageErrors = [];
+  const consoleErrors = [];
+  const sentActions = [];
+  let bootTimedOut = false;
+  let browser;
+  let context;
+
+  try {
+    browser = await playwright.chromium.launch({ headless: !headed });
+    context = await browser.newContext({ viewport });
+    const page = await context.newPage();
+
+    page.on('pageerror', (err) => {
+      pageErrors.push(err.stack || err.message || String(err));
+    });
+    page.on('console', (msg) => {
+      if (msg.type() === 'error') {
+        consoleErrors.push(msg.text());
+      }
+    });
+
+    try {
+      await page.goto(url, { timeout: timeoutMs });
+      await page.waitForFunction(
+        () => window.Caper && window.Caper.__readyApps && window.Caper.__readyApps.size > 0,
+        null,
+        { timeout: timeoutMs },
+      );
+    } catch (err) {
+      bootTimedOut = true;
+      throw err;
+    }
+
+    const evalResult = await page.evaluate(
+      async ({ appId: requestedAppId, actions: actionsToSend, untilSrc, timeout, logTail }) => {
+        const caper = window.Caper;
+        const app = await caper.ready(requestedAppId || undefined);
+        const resolvedAppId = app.config?.id || app.id || 'unknown';
+        const automation = caper.automation?.[resolvedAppId];
+
+        if (!automation) {
+          return {
+            appId: resolvedAppId,
+            automation: false,
+            context: undefined,
+            state: undefined,
+            actions: [],
+            log: [],
+          };
+        }
+
+        const dispatched = [];
+        for (const { name, data } of actionsToSend) {
+          automation.action(name, data);
+          dispatched.push({ name, data });
+        }
+
+        if (untilSrc) {
+          const predicate = new Function('return (' + untilSrc + ')')();
+          await automation.waitFor(predicate, { timeoutMs: timeout });
+        }
+
+        const fullLog = automation.log || [];
+        const log = fullLog.slice(-logTail);
+
+        return {
+          appId: resolvedAppId,
+          automation: true,
+          context: automation.getContext(),
+          state: automation.getState(),
+          actions: dispatched,
+          log,
+        };
+      },
+      { appId, actions, untilSrc: until, timeout: timeoutMs, logTail: DEFAULT_LOG_TAIL },
+    );
+
+    sentActions.push(...evalResult.actions);
+
+    if (waitMs > 0) {
+      await new Promise((resolve) => setTimeout(resolve, waitMs));
+    }
+
+    if (screenshot) {
+      fs.mkdirSync(path.dirname(path.resolve(screenshot)), { recursive: true });
+      await page.screenshot({ path: screenshot, type: 'png' });
+    }
+
+    const result = {
+      url,
+      appId: evalResult.appId,
+      automation: evalResult.automation,
+      context: evalResult.context,
+      state: evalResult.state,
+      actions: sentActions,
+      log: evalResult.log,
+      pageErrors,
+      consoleErrors,
+      screenshot,
+      durationMs: Date.now() - startTime,
+    };
+
+    if (!screenshot) {
+      delete result.screenshot;
+    }
+
+    let failed = false;
+    let reason = '';
+    if (pageErrors.length > 0) {
+      failed = true;
+      reason = `${pageErrors.length} page error(s)`;
+    }
+
+    if (json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.log(green(bold('✓ Probed')) + ` ${cyan(url)}`);
+      console.log(`  ${yellow('app:')}        ${evalResult.appId}`);
+      console.log(`  ${yellow('automation:')} ${evalResult.automation}`);
+      console.log(`  ${yellow('actions:')}    ${sentActions.length}`);
+      console.log(`  ${yellow('log:')}        ${evalResult.log.length} entries`);
+      console.log(`  ${yellow('duration:')}   ${result.durationMs}ms`);
+      if (pageErrors.length > 0) {
+        console.error(red(`  ${pageErrors.length} page error(s)`));
+      }
+      if (consoleErrors.length > 0) {
+        console.error(red(`  ${consoleErrors.length} console error(s)`));
+      }
+      if (screenshot) {
+        console.log(`  ${yellow('screenshot:')} ${screenshot}`);
+      }
+      console.log('');
+      console.log(JSON.stringify(result, null, 2));
+    }
+
+    if (failed) {
+      console.error(red(`probe failed: ${reason}`));
+      process.exit(1);
+    }
+
+    return result;
+  } catch (err) {
+    const result = {
+      url,
+      appId: appId || undefined,
+      automation: false,
+      context: undefined,
+      state: undefined,
+      actions: sentActions,
+      log: [],
+      pageErrors,
+      consoleErrors,
+      durationMs: Date.now() - startTime,
+    };
+
+    if (bootTimedOut) {
+      result._reason = 'boot timed out';
+    } else if (until && err?.message?.includes('timed out')) {
+      result._reason = '--until predicate timed out';
+    } else {
+      result._reason = err?.message || String(err);
+    }
+
+    if (screenshot) {
+      result.screenshot = screenshot;
+    }
+
+    if (json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.error(bold(bgRed(white(` probe failed: ${result._reason} `))));
+      console.error(red(err?.stack || err?.message || String(err)));
+      if (pageErrors.length > 0) {
+        console.error(red(`  ${pageErrors.length} page error(s)`));
+      }
+    }
+
+    process.exit(1);
+  } finally {
+    if (context) await context.close().catch(() => {});
+    if (browser) await browser.close().catch(() => {});
+  }
+}

package/cli/probe.test.mjs

@@ -0,0 +1,74 @@
+import { describe, expect, it } from 'vitest';
+import { parseProbeArgs } from './probe.mjs';
+
+describe('parseProbeArgs', () => {
+  it('parses the url positional argument', () => {
+    const result = parseProbeArgs(['http://localhost:4179/']);
+    expect(result.url).toBe('http://localhost:4179/');
+    expect(result.actions).toEqual([]);
+    expect(result.headed).toBe(false);
+    expect(result.json).toBe(false);
+  });
+
+  it('parses repeated --action with and without JSON data', () => {
+    const result = parseProbeArgs([
+      'http://localhost:4179/',
+      '--action',
+      'start',
+      '--action',
+      'submit={"value":42}',
+    ]);
+    expect(result.actions).toEqual([
+      { name: 'start' },
+      { name: 'submit', data: { value: 42 } },
+    ]);
+  });
+
+  it('parses --until predicate string', () => {
+    const result = parseProbeArgs(['http://localhost:4179/', '--until', "s => s && s.phase === 'resolved'"]);
+    expect(result.until).toBe("s => s && s.phase === 'resolved'");
+  });
+
+  it('parses numeric --wait and --timeout options', () => {
+    const result = parseProbeArgs(['http://localhost:4179/', '--wait', '500', '--timeout', '30000']);
+    expect(result.waitMs).toBe(500);
+    expect(result.timeoutMs).toBe(30000);
+  });
+
+  it('parses --viewport WxH', () => {
+    const result = parseProbeArgs(['http://localhost:4179/', '--viewport', '800x600']);
+    expect(result.viewport).toEqual({ width: 800, height: 600 });
+  });
+
+  it('parses boolean and string options', () => {
+    const result = parseProbeArgs([
+      'http://localhost:4179/',
+      '--app',
+      'demo',
+      '--screenshot',
+      '/tmp/out.png',
+      '--headed',
+      '--json',
+    ]);
+    expect(result.appId).toBe('demo');
+    expect(result.screenshot).toBe('/tmp/out.png');
+    expect(result.headed).toBe(true);
+    expect(result.json).toBe(true);
+  });
+
+  it('throws when url is missing', () => {
+    expect(() => parseProbeArgs(['--action', 'start'])).toThrow('Missing required <url> argument');
+  });
+
+  it('throws on invalid JSON in --action', () => {
+    expect(() => parseProbeArgs(['http://localhost:4179/', '--action', 'submit={not json}'])).toThrow(
+      'Invalid JSON data',
+    );
+  });
+
+  it('throws on invalid --viewport', () => {
+    expect(() => parseProbeArgs(['http://localhost:4179/', '--viewport', '800'])).toThrow(
+      'Invalid --viewport value',
+    );
+  });
+});

package/cli/types.mjs

@@ -0,0 +1,101 @@
+import { bold, cyan, green, red, yellow } from 'kleur/colors';
+
+import path from 'node:path';
+import process from 'node:process';
+
+/**
+ * `caper types` — regenerate the generated `.d.ts` files without a dev server.
+ *
+ * Reads the project's `vite.config.ts` (which contains `caper()`), runs the
+ * asset pipeline once if present, then writes `src/types/caper-app.d.ts` and
+ * `src/types/caper-assets.d.ts`. Use `--no-assets` to skip the AssetPack run
+ * and asset type generation.
+ */
+
+const APP_DTS = 'caper-app.d.ts';
+const ASSET_DTS = 'caper-assets.d.ts';
+
+/**
+ * @param {string[]} args
+ * @returns {{ assets: boolean }}
+ */
+function parseArgs(args) {
+  return {
+    assets: !args.includes('--no-assets'),
+  };
+}
+
+/**
+ * Find a plugin by name in Vite's resolved (flat) plugin list.
+ *
+ * @param {import('vite').ResolvedConfig} config
+ * @param {string} name
+ */
+function findPlugin(config, name) {
+  return config.plugins.find((p) => p && p.name === name);
+}
+
+/**
+ * Generate `caper-app.d.ts` and optionally `caper-assets.d.ts` for a project.
+ *
+ * @param {string} root - project root (where vite.config.ts / caper.config.ts live)
+ * @param {{ assets?: boolean }} [options]
+ * @returns {Promise<{ appTypes: string, assetTypes: string | null }>}
+ */
+export async function generateTypes(root, { assets = true } = {}) {
+  const { resolveConfig } = await import('vite');
+  const config = await resolveConfig({ root, logLevel: 'warn' }, 'serve', 'development');
+
+  const caperConfigPlugin = findPlugin(config, 'vite-plugin-caper-config');
+  if (!caperConfigPlugin) {
+    throw new Error("caper() is not in this project's vite.config — nothing to generate");
+  }
+  if (!caperConfigPlugin.api?.generateTypes) {
+    throw new Error(
+      "the caper() preset in this project's vite.config predates `caper types` — the CLI and `@caperjs/core/vite` must come from the same @caperjs/core install (>= 0.6.0)",
+    );
+  }
+
+  const assetpackPlugin = findPlugin(config, 'vite-plugin-assetpack');
+  const assetTypesPlugin = findPlugin(config, 'vite-plugin-asset-types');
+
+  if (assets && assetpackPlugin) {
+    await assetpackPlugin.api.runOnce();
+  }
+
+  await caperConfigPlugin.api.generateTypes();
+
+  if (assets && assetTypesPlugin) {
+    await assetTypesPlugin.api.generateTypes();
+  }
+
+  const typesDir = path.resolve(root, 'src', 'types');
+  return {
+    appTypes: path.join(typesDir, APP_DTS),
+    assetTypes: assets && assetTypesPlugin ? path.join(typesDir, ASSET_DTS) : null,
+  };
+}
+
+/**
+ * CLI entry for `caper types`.
+ *
+ * @param {string[]} args
+ */
+export async function types(args) {
+  const { assets } = parseArgs(args);
+  const root = process.cwd();
+
+  try {
+    const { appTypes, assetTypes } = await generateTypes(root, { assets });
+
+    console.log(green(bold('✓ Generated types')) + ` ${cyan(path.relative(root, appTypes))}`);
+    if (assetTypes) {
+      console.log(green(bold('✓ Generated types')) + ` ${cyan(path.relative(root, assetTypes))}`);
+    } else if (!assets) {
+      console.log(`  ${yellow('Skipped asset types generation')} (use without --no-assets to include them)`);
+    }
+  } catch (error) {
+    console.error(red(`caper types: ${error.message}`));
+    process.exit(1);
+  }
+}

package/cli/types.test.mjs

@@ -0,0 +1,58 @@
+/**
+ * `caper types` — command-line type generation without a dev server.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { generateTypes } from './types.mjs';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const fixtureRoot = path.resolve(here, '../test/fixtures/app');
+const caperBuildUrl = pathToFileURL(path.resolve(here, '../build/index.mjs')).href;
+
+let root;
+
+beforeEach(() => {
+  root = fs.mkdtempSync(path.join(os.tmpdir(), 'caper-types-'));
+});
+
+afterEach(() => {
+  fs.rmSync(root, { recursive: true, force: true });
+});
+
+function scaffoldApp(options = { assets: false }) {
+  fs.cpSync(fixtureRoot, root, { recursive: true });
+  fs.writeFileSync(
+    path.join(root, 'vite.config.ts'),
+    `import { caper } from '${caperBuildUrl}';
+
+export default {
+  plugins: [caper(${JSON.stringify(options)})],
+};
+`,
+    'utf-8',
+  );
+}
+
+describe('generateTypes', () => {
+  it('writes caper-app.d.ts and returns null assetTypes when assets are disabled', async () => {
+    scaffoldApp({ assets: false });
+
+    const result = await generateTypes(root, { assets: false });
+
+    const dtsPath = path.join(root, 'src', 'types', 'caper-app.d.ts');
+    expect(fs.existsSync(dtsPath)).toBe(true);
+    const content = fs.readFileSync(dtsPath, 'utf-8');
+    expect(content).toContain("'main'");
+    expect(result.appTypes).toBe(dtsPath);
+    expect(result.assetTypes).toBeNull();
+  });
+
+  it('throws when caper() is not present in vite.config', async () => {
+    fs.writeFileSync(path.join(root, 'vite.config.ts'), 'export default { plugins: [] };', 'utf-8');
+
+    await expect(generateTypes(root)).rejects.toThrow("caper() is not in this project's vite.config");
+  });
+});

package/cli.mjs

@@ -5,10 +5,13 @@ import { bgRed, bold, green, red, white } from 'kleur/colors';
 import fs from 'node:fs';
 import process from 'node:process';
 import { add } from './cli/add.mjs';
+import { agent } from './cli/agent.mjs';
 import { generateCaptions } from './cli/audio/cc.mjs';
 import { compress } from './cli/audio/index.mjs';
 import { create } from './cli/create.mjs';
+import { doctor } from './cli/doctor.mjs';
 import { installPeerDeps } from './cli/install-peerdeps.mjs';
+import { types } from './cli/types.mjs';
 import { update } from './cli/update.mjs';
 import { generateVoiceoverCSV } from './cli/voiceover/index.mjs';
 
@@ -64,6 +67,15 @@ switch (args[0]) {
   case 'add':
     await add(args.slice(1));
     break;
+  case 'agent':
+    await agent(args.slice(1));
+    break;
+  case 'types':
+    await types(args.slice(1));
+    break;
+  case 'doctor':
+    await doctor(args.slice(1));
+    break;
   case 'create': {
     let packageManager = 'npm'; // Default to npm
     let projectPath = '.'; // Default to current directory