@usecanary/cli 0.2.0 → 0.4.0

package/README.md

@@ -108,7 +108,8 @@ await saveScreenshot(await page.screenshot(), "signed-in.png");   // saveScreens
 - **Files** (sandboxed to `~/.canary/tmp/`) — `saveScreenshot(buffer, name)`, `writeFile(name, data)`,
   `readFile(name)` to pass values between steps.
 
-The engine documents the same API — run `canary-browser --help`, or read the
+The full reference is built into this CLI — run `canary --help` or `canary run --help`
+(the engine's `canary-browser --help` documents the same API), or read the
 [canary-scripting reference](https://github.com/usecanary/canary/blob/main/skills/canary-scripting/references/REFERENCE.md).
 
 ## Artifacts

package/dist/cli.cjs

@@ -7462,15 +7462,15 @@ var require_help = __commonJS({
        * @return {string}
        *
        */
-      wrap(str, width, indent, minColumnWidth = 40) {
+      wrap(str, width, indent2, minColumnWidth = 40) {
         const indents = " \\f\\t\\v\xA0\u1680\u2000-\u200A\u202F\u205F\u3000\uFEFF";
         const manualIndent = new RegExp(`[\\n][${indents}]+`);
         if (str.match(manualIndent)) return str;
-        const columnWidth = width - indent;
+        const columnWidth = width - indent2;
         if (columnWidth < minColumnWidth) return str;
-        const leadingStr = str.slice(0, indent);
-        const columnText = str.slice(indent).replace("\r\n", "\n");
-        const indentString = " ".repeat(indent);
+        const leadingStr = str.slice(0, indent2);
+        const columnText = str.slice(indent2).replace("\r\n", "\n");
+        const indentString = " ".repeat(indent2);
         const zeroWidthSpace = "\u200B";
         const breaks = `\\s${zeroWidthSpace}`;
         const regex = new RegExp(
@@ -9967,6 +9967,181 @@ function createLogger(opts = {}) {
 
 // ../../packages/cli-kit/src/index.ts
 var import_pino_pretty = __toESM(require_pino_pretty(), 1);
+
+// ../../packages/cli-kit/src/snippets.generated.ts
+var API_BROWSER = "- `browser.getPage(nameOrId)` \u2014 get-or-create a named page, or attach to an existing tab by the\n  `id` from `listPages()`. Named pages persist across steps in a session \u2014 call with the same\n  name to reuse the tab.\n- `browser.newPage()` \u2014 an anonymous page, auto-closed when the script ends; does not persist.\n- `browser.listPages()` \u2014 list every open tab: `[{ id, url, title, name }]` (`name` is `null`\n  for tabs you never named).\n- `browser.closePage(name)` \u2014 close and forget a named page.";
+var API_CONSOLE = "- `console.log` / `console.info` write to stdout; `console.warn` / `console.error` write to\n  stderr. Top-level `console.log` is your script's output channel.\n- `console.log` inside `page.evaluate(() => \u2026)` runs in the page and is captured into the\n  session's console artifact instead.";
+var API_FILE_HELPERS = 'All file I/O is async (await it), sandboxed to `~/.canary/tmp/` (no filesystem escape), and\nreturns the full path to the file:\n\n- `saveScreenshot(buffer, name)` \u2014 persist a screenshot buffer; buffer first:\n  `const path = await saveScreenshot(await page.screenshot(), "home.png");`\n- `writeFile(name, data)` \u2014 write a small file (e.g. JSON state):\n  `await writeFile("results.json", JSON.stringify(data));`\n- `readFile(name)` \u2014 read it back (returns the contents as a string):\n  `const data = JSON.parse(await readFile("results.json"));`';
+var API_GLOBALS = "Every script gets these globals:\n\n- `browser` \u2014 pre-connected browser handle (see the script API)\n- `console` \u2014 `log` / `info` / `warn` / `error`, captured per run\n- `setTimeout` / `clearTimeout` \u2014 basic timers\n- `saveScreenshot(buffer, name)` \u2014 save a screenshot buffer (async \u2014 await it)\n- `writeFile(name, data)` / `readFile(name)` \u2014 small-file persistence (async \u2014 await them)";
+var API_PLAYWRIGHT_METHODS = '- `page.goto(url, { waitUntil: "domcontentloaded" })` \u2014 navigate; `waitUntil` is `"load"` /\n  `"domcontentloaded"` / `"networkidle"` (prefer `"domcontentloaded"` on dev servers)\n- `page.title()` / `page.url()` \u2014 current title / URL\n- `page.snapshotForAI(options)` \u2014 AI-optimized page outline; returns `{ full, incremental? }`;\n  options `{ track?, depth?, timeout? }`\n- `page.getByRole(role, { name })` / `page.getByText(text)` \u2014 semantic locators (survive re-renders)\n- `page.textContent(sel)` / `page.innerText(sel)` / `page.innerHTML(sel)` /\n  `page.getAttribute(sel, name)` \u2014 read by selector\n- `page.inputValue(sel)` / `page.isChecked(sel)` / `page.isVisible(sel)` / `page.isHidden(sel)` \u2014\n  input and visibility state\n- `page.fill(sel, value)` / `page.click(sel)` / `page.type(sel, text)` / `page.press(sel, key)` \u2014\n  act on elements\n- `page.waitForSelector(sel, { state, timeout })` (`state`: `"attached"` / `"visible"` /\n  `"hidden"` / `"detached"`) / `page.waitForURL(pattern)` / `page.waitForLoadState(state)` /\n  `page.waitForFunction(fn)` / `page.waitForTimeout(ms)` \u2014 waiting\n- `page.screenshot({ fullPage })` \u2014 capture a screenshot Buffer; save it with `saveScreenshot(...)`\n- `page.evaluate(fn[, arg])` / `page.$eval(sel, fn)` / `page.$$eval(sel, fn)` \u2014 run plain\n  JavaScript in the page context (real DOM; args/returns must be serializable)\n- `page.locator(sel)` \u2014 a Locator for chained actions (`.click()`, `.fill(value)`,\n  `.textContent()`, `.first()`, \u2026)\n- `page.keyboard.press/type/down/up(...)` / `page.mouse.move/click/down/up(...)` \u2014 low-level input\n- `page.reload()` / `page.goBack()` / `page.goForward()` \u2014 history;\n  `page.content()` / `page.setContent(html)` \u2014 full HTML\n- `page.on("console", handler)` \u2014 observe page console events';
+var API_PLAYWRIGHT_NOTE = "Pages returned by `browser.getPage()` and `browser.newPage()` are full Playwright Page objects \u2014\nthe same API (`goto`, `click`, `fill`, `locator`, `evaluate`, `getByRole`, `waitForSelector`, \u2026):\nhttps://playwright.dev/docs/api/class-page";
+var API_SANDBOX_ENV = "Scripts execute inside a QuickJS WASM sandbox with no arbitrary access to the host system.\nThis is NOT Node.js \u2014 there is no module system and no Node API:\n\n- `require()` / `import()` \u2014 no module loading; inline any helpers in the script\n- `process`, `fs` / `path` / `os` \u2014 no process or direct filesystem access (use the file helpers)\n- `fetch` / `WebSocket` \u2014 no direct network access (the page does the networking)\n- `__dirname` / `__filename` \u2014 no path globals\n\nMemory and CPU limits are enforced, and both CPU time and wall-clock time are bounded \u2014 infinite\nloops or never-settling promises abort the script. Values crossing `evaluate` / `$eval` must be\nJSON-serializable.";
+var API_SNAPSHOT = '- `page.snapshotForAI()` returns `{ full, incremental? }` \u2014 `full` is an aria outline of the\n  page: roles, accessible names, `[ref=eN]` markers on actionable nodes. Read it to pick a\n  semantic selector \u2014 `page.getByRole("button", { name: "Continue" })`,\n  `page.getByText("Sign in")` \u2014 then act.\n- Options `{ track?, depth?, timeout? }`: re-run `page.snapshotForAI({ track: "main" })` after\n  the page changes to get just the `incremental` diff; `{ depth: N }` caps the tree on huge\n  pages; `timeout` bounds the walk.\n- `page.locator("aria-ref=e12")` works for an immediate action in the same script only \u2014 refs go\n  stale across steps and after navigations. Prefer re-deriving a semantic selector.';
+var EX_INSPECT_TABS = "const tabs = await browser.listPages();\nconsole.log(JSON.stringify(tabs, null, 2));";
+var EX_SNAPSHOT = 'const page = await browser.getPage("main");\nconst snap = await page.snapshotForAI(); // { full, incremental? }\nconsole.log(page.url(), await page.title());\nconsole.log(snap.full); // aria outline \u2014 pick a role/text selector from this\n// then act: await page.getByRole("button", { name: "Continue" }).click();\n// after changes, page.snapshotForAI({ track: "main" }) returns just the incremental diff';
+var RULE_DATA_PASSING = '- Browser state persists across steps: named pages (and their cookies) stay open between scripts\n  within a session \u2014 reuse the same page name so each step picks up where the last left off.\n- Anonymous `newPage()` tabs are closed when each script ends.\n- To pass values between steps: `writeFile("state.json", JSON.stringify(x))` in one step,\n  `JSON.parse(await readFile("state.json"))` in the next.';
+var RULE_DEV_SERVER = 'For local dev servers (Next.js, Vite, \u2026) prefer\n`await page.goto(url, { waitUntil: "domcontentloaded" })` \u2014 the default `"load"` wait can hang\non HMR, streaming, or other long-lived dev-server connections. Use `"load"` only when you\nspecifically need every subresource to finish loading.';
+var RULE_FAIL_FAST = "- End each script by logging the state you need for the next decision \u2014 stdout is your\n  observation channel.\n- Use short timeouts (`canary run --timeout 10`) so a step fails fast instead of hanging on a\n  missing element.\n- In assertion / extraction steps, degrade gracefully \u2014 log a `WARN` / `FAIL` line instead of\n  crashing, so the step still records its evidence. While exploring, a missed selector means\n  look again (snapshot, fix, retry as a new step), not a silent fallback.\n- End before you stop: `canary stop` shuts the daemon down and aborts any live session,\n  skipping its report.html \u2014 always `canary session end <id>` first.";
+var RULE_OBSERVE_FIRST = "- Unknown page? Snapshot first, then act: read `(await page.snapshotForAI()).full` to see what\n  is there, pick a semantic selector from it (`getByRole`, `getByText`), then interact. Never\n  guess selectors blind.\n- Known page or selectors? Skip the snapshot and use direct selectors \u2014 faster and more reliable.";
+var RULE_SCREENSHOT = "After each `canary run --step`, the daemon auto-captures ONE screenshot of the step's\nlast-opened tab and binds it to that step in the report. So:\n\n- Keep one primary named page per step \u2014 the report screenshot is always the page you mean.\n- If a step opens several tabs, open the one you want featured last.\n- `saveScreenshot(...)` images land in `~/.canary/tmp/` and are NOT in the report \u2014 they're\n  extras for debugging.";
+
+// ../../packages/cli-kit/src/scripting-help.ts
+var indent = (text, prefix) => text.split("\n").map((line) => line.length > 0 ? prefix + line : line).join("\n");
+var SANDBOX_ENVIRONMENT = `SANDBOX ENVIRONMENT:
+${indent(API_SANDBOX_ENV, "  ")}
+
+${indent(API_GLOBALS, "  ")}`;
+var SCRIPT_API = `Script API available inside every script:
+${indent(API_BROWSER, "  ")}
+
+${indent(API_FILE_HELPERS, "  ")}
+
+${indent(API_CONSOLE, "  ")}`;
+var PLAYWRIGHT_PAGE_NOTE = API_PLAYWRIGHT_NOTE;
+function sandboxReference() {
+  return `${SANDBOX_ENVIRONMENT}
+
+${SCRIPT_API}
+
+${PLAYWRIGHT_PAGE_NOTE}`;
+}
+var sessionExample = (scriptBody, opts) => [
+  `canary run --session "$id" --step ${opts?.step ?? "<name>"} <<'EOF'`,
+  scriptBody,
+  "EOF"
+].join("\n");
+var INSPECT_PAGE_BODY = `const page = await browser.getPage("TARGET_ID_HERE");
+console.log(JSON.stringify({
+  url: page.url(),
+  title: await page.title(),
+}, null, 2));`;
+var SCREENSHOT_BODY = `const page = await browser.getPage("main");
+const buf = await page.screenshot();
+const path = await saveScreenshot(buf, "debug.png");
+console.log(path);`;
+var WAITING_BODY = `const page = await browser.getPage("search-results");
+await page.waitForSelector(".results");
+await page.waitForURL("**/success");
+console.log(JSON.stringify({
+  url: page.url(),
+  title: await page.title(),
+}, null, 2));`;
+var ERROR_RECOVERY_BODY = `const page = await browser.getPage("checkout");
+const path = await saveScreenshot(await page.screenshot(), "debug.png");
+console.log(JSON.stringify({
+  screenshot: path,
+  url: page.url(),
+  title: await page.title(),
+}, null, 2));`;
+var POWERSHELL_BLOCK = `  On Windows/PowerShell, use here-strings to pipe multiline scripts:
+    @"
+    const page = await browser.getPage("main");
+    console.log(await page.title());
+    "@ | canary-browser --connect`;
+var CONNECTING_SECTION = `  Connecting to a running Chrome instance:
+    Auto-discover Chrome with debugging enabled:
+      canary-browser --connect <<'EOF'
+        const page = await browser.getPage("main");
+        console.log(await page.title());
+      EOF
+
+    Connect to a specific CDP endpoint:
+      canary-browser --connect http://localhost:9222 <<'EOF'
+        const page = await browser.getPage("main");
+        console.log(await page.title());
+      EOF
+
+    To launch Chrome with debugging enabled:
+      chrome.exe --remote-debugging-port=9222
+      google-chrome --remote-debugging-port=9222
+
+    Or visit chrome://inspect/#remote-debugging to configure.`;
+function buildScriptingGuide(options) {
+  const { heading, example } = options;
+  const browserExtras = options.browserExtras === true;
+  const intro = [
+    `${heading}`,
+    "  Write small, focused scripts. Each script should do ONE thing: navigate, click, fill, or check.",
+    "  End each script by logging the state you need for the next decision.",
+    '  Use descriptive page names like "login", "checkout", or "results" instead of "page1".',
+    '  Named pages from browser.getPage("name") persist between script runs, so you usually do not need to re-navigate.',
+    "  Inside page.evaluate(...), write plain JavaScript only - no TypeScript syntax in the browser context.",
+    ...browserExtras ? [POWERSHELL_BLOCK] : []
+  ].join("\n");
+  const quickInspection = [
+    "  Quick inspection:",
+    indent(
+      example(EX_INSPECT_TABS, { step: "inspect", connect: true }),
+      "    "
+    ),
+    "",
+    indent(
+      example(INSPECT_PAGE_BODY, { step: "inspect", connect: true }),
+      "    "
+    )
+  ].join("\n");
+  const aiSnapshots = [
+    "  AI snapshots for element discovery:",
+    indent(example(EX_SNAPSHOT, { step: "discover" }), "    "),
+    "",
+    indent(API_SNAPSHOT, "    ")
+  ].join("\n");
+  const choosingApproach = [
+    "  Choosing your approach:",
+    indent(RULE_OBSERVE_FIRST, "    ")
+  ].join("\n");
+  const screenshots = [
+    "  Screenshots for visual state:",
+    indent(example(SCREENSHOT_BODY, { step: "capture" }), "    ")
+  ].join("\n");
+  const waiting = [
+    "  Waiting patterns:",
+    indent(example(WAITING_BODY, { step: "wait" }), "    ")
+  ].join("\n");
+  const devServer = [
+    "  Dev server navigation:",
+    indent(RULE_DEV_SERVER, "    ")
+  ].join("\n");
+  const errorRecovery = [
+    "  Error recovery:",
+    "    If a script fails, the page usually stays where it stopped.",
+    "    Reconnect to the same page name, take a screenshot, and log the URL/title:",
+    indent(example(ERROR_RECOVERY_BODY, { step: "recover" }), "    ")
+  ].join("\n");
+  const playwrightMethods = [
+    "  Common Playwright Page methods:",
+    indent(API_PLAYWRIGHT_METHODS, "    ")
+  ].join("\n");
+  const tips = [
+    "  Tips:",
+    "    - Use console.log(JSON.stringify(...)) for structured output.",
+    "    - Prefer page.snapshotForAI() for structure; use screenshots when visual layout or styling matters.",
+    "    - Keep page names stable across scripts so you can resume work after failures.",
+    ...browserExtras ? [
+      "    - Each --browser name maps to a separate daemon-managed browser instance.",
+      "    - Use --connect to attach to an existing browser; omit the URL to auto-discover Chrome with debugging enabled."
+    ] : [],
+    "    - Use short timeouts (--timeout 10) so scripts fail fast instead of hanging on missing elements.",
+    ...browserExtras ? [
+      "    - Add --headless for unattended automation; omit it when you want to watch the browser window."
+    ] : []
+  ].join("\n");
+  return [
+    intro,
+    quickInspection,
+    aiSnapshots,
+    choosingApproach,
+    screenshots,
+    waiting,
+    devServer,
+    errorRecovery,
+    playwrightMethods,
+    ...browserExtras ? [CONNECTING_SECTION] : [],
+    tips
+  ].join("\n\n");
+}
+
+// ../../packages/cli-kit/src/index.ts
 function requestId(prefix) {
   return `${prefix}-${Date.now()}-${process.pid}`;
 }
@@ -15034,19 +15209,19 @@ WHAT IS CAPTURED (per session; toggle on \`session start\`):
   screenshots  one per step, auto-captured from the step's last-opened page
 
 Artifacts live under ~/.canary/sessions/<id>/ (session.json, results.json, report.html, trace.zip, \u2026).
-Scripts use the same sandboxed API as the engine \u2014 see \`canary-browser --help\` for the full reference.`;
+Scripts run in a QuickJS sandbox (not Node.js) with a pre-connected \`browser\` global \u2014 the full
+reference follows; the SCRIPTING GUIDE after the command list has worked examples.
+
+${sandboxReference()}`;
 var USAGE_GUIDE = `SESSION WORKFLOW GUIDE:
   Structure a session as a sequence of small steps \u2014 one script per step (open, act, assert).
   Each \`canary run --step <name>\` is one step in the report, with its own trace group and ONE
-  auto-captured screenshot (taken from the LAST page opened during that step). So:
-    - Use ONE primary named page per step.
-    - Reuse the same page name across steps to "click through" like a user \u2014 named pages persist
-      across steps within a session.
-    - If a step opens extra tabs, open the one you want featured in the report LAST.
+  auto-captured screenshot.
+
+${indent(RULE_SCREENSHOT, "  ")}
 
   Passing data between steps:
-    - Browser state (named pages, cookies) persists across steps automatically.
-    - For values: writeFile("state.json", JSON.stringify(x)) in one step, readFile it in the next.
+${indent(RULE_DATA_PASSING, "    ")}
 
   Reading results:
     canary session list                       List sessions (table; --json for machine output)
@@ -15054,12 +15229,18 @@ var USAGE_GUIDE = `SESSION WORKFLOW GUIDE:
     open ~/.canary/sessions/<id>/report.html  The self-contained report
     canary ui                                 Browse, search, and organize all sessions
 
+  Step discipline:
+${indent(RULE_FAIL_FAST, "    ")}
+
   Tips:
     - \`--json\` (global) emits machine-readable JSON on stdout; \`-v\`/\`--verbose\` raises stderr logging.
-    - \`canary run --timeout 30\` fails a step fast instead of hanging on a missing element.
     - \`canary session end --stop-daemon\` shuts the daemon down if nothing else is using it.
-    - \`canary stop\` shuts the whole background daemon down (and every browser it's running).
-    - Need a quick one-off with NO recording? Use \`canary-browser run\` instead of a session.`;
+    - Need a quick one-off with NO recording? Use \`canary-browser run\` instead of a session.
+
+${buildScriptingGuide({
+  example: sessionExample,
+  heading: "SCRIPTING GUIDE:"
+})}`;
 var SESSION_START_LONG_ABOUT = `Start a capture-enabled session and print its id.
 
 Capture is on by default \u2014 disable per stream with --no-trace / --no-video / --no-har / --no-console.
@@ -15069,10 +15250,15 @@ Use --headless for unattended runs; omit it to watch the browser window.
   id=$(canary session start --name "smoke" --headless --no-video)`;
 var RUN_LONG_ABOUT = `Run a script as one step inside a session.
 
-The script (a FILE, or stdin if omitted) executes in the sandbox the same way \`canary-browser run\`
-does \u2014 top-level await, with \`browser\` and \`console\`. The step's name labels it in the report and
-owns one auto-captured screenshot (from the last page opened during the step).
+The script (a FILE, or stdin if omitted) executes as top-level JavaScript with \`await\` in a
+sandboxed QuickJS runtime \u2014 full reference below. The step's name labels it in the report and
+owns ONE auto-captured screenshot (taken from the LAST page opened during the step). Named
+pages persist across steps within the session, so each step picks up where the last left off;
+pass values between steps with writeFile/readFile.
+
+${sandboxReference()}
 
+Examples:
   canary run open.js --session "$id" --step open
   echo 'const p = await browser.getPage("home"); await p.goto("https://example.com");' \\
     | canary run --session "$id" --step home --timeout 30`;
@@ -17036,26 +17222,25 @@ function findWorkspaceUiDir() {
 async function resolveUiServer() {
   const override = process.env.CANARY_UI_SERVER;
   if (override && await isFile(override)) {
-    return { kind: "standalone", serverJs: override };
+    return { kind: "standalone", serverEntry: override };
   }
   const workspaceDir = findWorkspaceUiDir();
   if (!workspaceDir) {
     return null;
   }
-  const serverJs = import_node_path9.default.join(
+  const serverEntry = import_node_path9.default.join(workspaceDir, "dist", "server", "entry.mjs");
+  if (await isFile(serverEntry)) {
+    return { kind: "standalone", serverEntry };
+  }
+  const astroBin = import_node_path9.default.join(
     workspaceDir,
-    ".next",
-    "standalone",
-    "apps",
-    "canary-ui",
-    "server.js"
+    "node_modules",
+    "astro",
+    "bin",
+    "astro.mjs"
   );
-  if (await isFile(serverJs)) {
-    return { kind: "standalone", serverJs };
-  }
-  const nextBin = import_node_path9.default.join(workspaceDir, "node_modules", ".bin", "next");
-  if (await isFile(nextBin)) {
-    return { kind: "dev", nextBin, workspaceDir };
+  if (await isFile(astroBin)) {
+    return { kind: "dev", astroBin, workspaceDir };
   }
   return null;
 }
@@ -17116,9 +17301,10 @@ async function uiCommand(args) {
   const baseEnv = { ...process.env, CANARY_UI_ROOT: root };
   let child;
   if (resolved.kind === "standalone") {
-    child = (0, import_node_child_process4.spawn)(process.execPath, [resolved.serverJs], {
-      cwd: import_node_path10.default.dirname(resolved.serverJs),
-      env: { ...baseEnv, HOSTNAME: host, PORT: String(port) },
+    child = (0, import_node_child_process4.spawn)(process.execPath, [resolved.serverEntry], {
+      cwd: import_node_path10.default.dirname(resolved.serverEntry),
+      // Astro's node adapter reads HOST (the old Next server read HOSTNAME).
+      env: { ...baseEnv, HOST: host, PORT: String(port) },
       stdio: ["ignore", "inherit", "inherit"]
     });
   } else {
@@ -17127,7 +17313,7 @@ async function uiCommand(args) {
     );
     child = (0, import_node_child_process4.spawn)(
       process.execPath,
-      [resolved.nextBin, "dev", "-p", String(port), "-H", host],
+      [resolved.astroBin, "dev", "--port", String(port), "--host", host],
       {
         cwd: resolved.workspaceDir,
         env: baseEnv,
@@ -17175,7 +17361,7 @@ async function uiCommand(args) {
 
 // src/cli.ts
 var { Command: Command2, InvalidArgumentError: InvalidArgumentError2 } = esm_exports;
-var VERSION = "0.2.0";
+var VERSION = "0.4.0";
 var ExitCodeError = class extends Error {
   code;
   constructor(code) {