gipity 1.1.16 → 1.1.19

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (59) hide show
  1. package/README.md +58 -75
  2. package/dist/adopt-cwd.js +2 -13
  3. package/dist/api.js +26 -44
  4. package/dist/auth.js +1 -1
  5. package/dist/banner.js +3 -7
  6. package/dist/catalog.js +8 -7
  7. package/dist/commands/add.js +26 -9
  8. package/dist/commands/approval.js +1 -1
  9. package/dist/commands/ask.js +112 -0
  10. package/dist/commands/bug.js +5 -5
  11. package/dist/commands/build.js +10 -35
  12. package/dist/commands/credits.js +3 -3
  13. package/dist/commands/doctor.js +7 -8
  14. package/dist/commands/email.js +6 -56
  15. package/dist/commands/generate.js +4 -4
  16. package/dist/commands/init.js +40 -30
  17. package/dist/commands/key.js +1 -1
  18. package/dist/commands/load.js +2 -12
  19. package/dist/commands/logs.js +2 -2
  20. package/dist/commands/memory.js +5 -17
  21. package/dist/commands/notify.js +1 -1
  22. package/dist/commands/page-eval.js +55 -38
  23. package/dist/commands/page-inspect.js +6 -6
  24. package/dist/commands/page-screenshot.js +51 -54
  25. package/dist/commands/page-test.js +188 -14
  26. package/dist/commands/payments.js +2 -2
  27. package/dist/commands/project.js +66 -15
  28. package/dist/commands/realtime.js +96 -4
  29. package/dist/commands/records.js +4 -6
  30. package/dist/commands/sandbox.js +2 -3
  31. package/dist/commands/skill.js +50 -22
  32. package/dist/commands/status.js +7 -9
  33. package/dist/commands/test.js +2 -2
  34. package/dist/commands/token.js +4 -4
  35. package/dist/commands/workflow.js +45 -8
  36. package/dist/config.js +22 -6
  37. package/dist/flag-aliases.js +75 -18
  38. package/dist/help-skills.js +2 -2
  39. package/dist/hooks/capture-runner.js +5 -3
  40. package/dist/index.js +1616 -1498
  41. package/dist/knowledge.js +24 -21
  42. package/dist/login-flow.js +4 -4
  43. package/dist/net.js +91 -0
  44. package/dist/opencode-setup.js +2 -2
  45. package/dist/page-fixtures.js +3 -3
  46. package/dist/project-setup.js +2 -3
  47. package/dist/prompts.js +1 -1
  48. package/dist/realtime-bench.js +12040 -0
  49. package/dist/relay/agent-token.js +1 -1
  50. package/dist/relay/daemon.js +0 -1
  51. package/dist/relay/setup.js +13 -2
  52. package/dist/setup.js +11 -12
  53. package/dist/sync.js +3 -3
  54. package/dist/utils.js +1 -1
  55. package/package.json +10 -4
  56. package/dist/commands/agent.js +0 -251
  57. package/dist/commands/chat.js +0 -137
  58. package/dist/commands/claude.js +0 -1056
  59. package/dist/commands/plan.js +0 -93
@@ -64,7 +64,7 @@ and its own error message), use the per-call log instead:
64
64
  }));
65
65
  logsCommand
66
66
  .command('app')
67
- .description('Unified recent activity for this app — JS errors, failed function calls, failed services, network failures. Designed for agents debugging a deployed app.')
67
+ .description('Unified recent activity for this app: JS errors, failed function calls, failed services, network failures. Designed for agents debugging a deployed app.')
68
68
  .option('--since <window>', "Window: 5m / 10m / 30m / 1h / 6h / 24h / 7d", '10m')
69
69
  .addOption(new Option('--severity <level>', 'Severity filter').choices(['error', 'warn', 'network', 'all']).default('all'))
70
70
  .option('--type <list>', "Comma-separated: errors,functions,services,traffic. Default excludes traffic (high volume).")
@@ -138,7 +138,7 @@ Examples:
138
138
  }
139
139
  }
140
140
  if (truncated) {
141
- console.log(`\n${muted(`(truncated at ${limit} entries — bump --limit or narrow --filter)`)}`);
141
+ console.log(`\n${muted(`(truncated at ${limit} entries: bump --limit or narrow --filter)`)}`);
142
142
  }
143
143
  }));
144
144
  //# sourceMappingURL=logs.js.map
@@ -5,30 +5,24 @@ import { error as clrError, muted } from '../colors.js';
5
5
  import { run, printList, printResult } from '../helpers/index.js';
6
6
  import { confirm } from '../utils.js';
7
7
  export const memoryCommand = new Command('memory')
8
- .description('Read or write memory');
8
+ .description("Read or write this project's memory: notes by topic that workflow llm steps read and write with the memory tool");
9
9
  memoryCommand
10
10
  .command('list')
11
11
  .description('List topics')
12
- .option('--project', 'List project memory (default is agent memory)')
13
12
  .option('--json', 'Output as JSON')
14
13
  .action((opts) => run('List', async () => {
15
14
  const { config } = await resolveProjectContext();
16
- const endpoint = opts.project
17
- ? `/projects/${config.projectGuid}/memory`
18
- : `/agents/${config.agentGuid}/memory`;
15
+ const endpoint = `/projects/${config.projectGuid}/memory`;
19
16
  const res = await get(endpoint);
20
17
  printList(res.data, opts, 'No memory topics.', m => `${m.topic} ${muted(`(${new Date(m.updated_at).toLocaleDateString()})`)}`);
21
18
  }));
22
19
  memoryCommand
23
20
  .command('read <topic>')
24
21
  .description('Read a topic')
25
- .option('--project', 'Read project memory')
26
22
  .option('--json', 'Output as JSON')
27
23
  .action((topic, opts) => run('Read', async () => {
28
24
  const { config } = await resolveProjectContext();
29
- const endpoint = opts.project
30
- ? `/projects/${config.projectGuid}/memory`
31
- : `/agents/${config.agentGuid}/memory`;
25
+ const endpoint = `/projects/${config.projectGuid}/memory`;
32
26
  const res = await get(endpoint);
33
27
  const match = res.data.find(m => m.topic === topic);
34
28
  if (!match) {
@@ -45,20 +39,16 @@ memoryCommand
45
39
  memoryCommand
46
40
  .command('write <topic> <content>')
47
41
  .description('Write a topic')
48
- .option('--project', 'Write to project memory')
49
42
  .option('--json', 'Output as JSON')
50
43
  .action((topic, content, opts) => run('Write', async () => {
51
44
  const { config } = await resolveProjectContext();
52
- const endpoint = opts.project
53
- ? `/projects/${config.projectGuid}/memory/${encodeURIComponent(topic)}`
54
- : `/agents/${config.agentGuid}/memory/${encodeURIComponent(topic)}`;
45
+ const endpoint = `/projects/${config.projectGuid}/memory/${encodeURIComponent(topic)}`;
55
46
  await put(endpoint, { content });
56
47
  printResult(`Wrote "${topic}".`, opts, { success: true, topic });
57
48
  }));
58
49
  memoryCommand
59
50
  .command('delete <topic>')
60
51
  .description('Delete a topic')
61
- .option('--project', 'Delete project memory')
62
52
  .option('--json', 'Output as JSON')
63
53
  .action((topic, opts) => run('Delete', async () => {
64
54
  if (!await confirm(`Delete memory "${topic}"?`)) {
@@ -66,9 +56,7 @@ memoryCommand
66
56
  return;
67
57
  }
68
58
  const { config } = await resolveProjectContext();
69
- const endpoint = opts.project
70
- ? `/projects/${config.projectGuid}/memory/${encodeURIComponent(topic)}`
71
- : `/agents/${config.agentGuid}/memory/${encodeURIComponent(topic)}`;
59
+ const endpoint = `/projects/${config.projectGuid}/memory/${encodeURIComponent(topic)}`;
72
60
  await del(endpoint);
73
61
  printResult(`Deleted "${topic}".`, opts, { success: true, topic });
74
62
  }));
@@ -30,7 +30,7 @@ notifyCommand
30
30
  if (sent > 0)
31
31
  console.log(success(`✓ Sent to ${sent} device${sent === 1 ? '' : 's'}.`));
32
32
  else
33
- console.log(warning('No devices received it — has anyone enabled notifications in the app yet? (gipity notify subs)'));
33
+ console.log(warning('No devices received it: has anyone enabled notifications in the app yet? (gipity notify subs)'));
34
34
  if (pruned)
35
35
  console.log(muted(` pruned ${pruned} expired subscription${pruned === 1 ? '' : 's'}`));
36
36
  if (failed)
@@ -13,7 +13,7 @@ import { uploadPublicFixture, uploadCameraFeed, assertCameraFile, deleteFixture
13
13
  // expression is auto-returned SERVER-side before this can fire — so this is the
14
14
  // residue: block/loop endings, explicit undefined returns, DOM nodes, functions.)
15
15
  export const EVAL_NO_VALUE_HINT = 'The eval ran but returned no JSON-serializable value. A body ending in a loop/if-block, a `return` of undefined, or a DOM node/function all serialize to null. ' +
16
- 'End the script with an expression — or an explicit `return` — that yields plain data, e.g. `return { label: input.value, count: items.length }` or `return JSON.stringify(payload)`.';
16
+ 'End the script with an expression (or an explicit `return`) that yields plain data, e.g. `return { label: input.value, count: items.length }` or `return JSON.stringify(payload)`.';
17
17
  /** Normalize a raw eval result for display. The eval can come back as a useful
18
18
  * serialized value, the literal `null`/`undefined`/empty string, or — when the
19
19
  * script returns undefined — agent-browser's raw envelope leaking through
@@ -43,17 +43,20 @@ export function normalizeEvalResult(raw) {
43
43
  return { result: typeof inner === 'string' ? inner : JSON.stringify(inner), noValue: false };
44
44
  }
45
45
  }
46
- catch { /* not the envelope — fall through and show the raw value */ }
46
+ catch { /* not the envelope: fall through and show the raw value */ }
47
47
  }
48
48
  return { result: raw, noValue: false };
49
49
  }
50
+ // Named on every signed-in run that did not ask for the database undo.
51
+ export const RESTORE_DB_TIP = 'Driving a write flow (submit, add, edit, delete)? Add --restore-db: the app database is checkpointed before the ' +
52
+ 'script and rolled back after, so test rows never land in the real data and no cleanup step is needed.';
50
53
  // Shown when a run returns a structurally empty value ({}, [], or an object whose
51
54
  // every field is null/''). That is NOT the same as "no value": the script ran and
52
55
  // read the page — it just read it at an instant where the state it wanted did not
53
56
  // exist. A fixed --wait samples ONE moment, and transient state (a round result,
54
57
  // a toast, a frame's detection) may have already been cleared by then, so the run
55
58
  // looks like a pass and the agent has to reason its way to "I sampled too late".
56
- export const EVAL_EMPTY_STATE_HINT = 'The eval returned an empty value — the script ran, but the state it read was not there at that instant. ' +
59
+ export const EVAL_EMPTY_STATE_HINT = 'The eval returned an empty value: the script ran, but the state it read was not there at that instant. ' +
57
60
  'A fixed --wait samples ONE moment; transient state (a round result, a toast, a detection) can be gone by then. ' +
58
61
  'Poll INSIDE the body and return the moment the condition holds (raise --timeout if the sequence needs longer), ' +
59
62
  "or gate the read on the app's own signal with --wait-for '<selector>'.";
@@ -64,7 +67,8 @@ export const EVAL_EMPTY_STATE_HINT = 'The eval returned an empty value — the s
64
67
  // notices something is off.
65
68
  const CAMERA_FRAME_CHECK = "in the eval body, run the model on the frame YOURSELF (grab the app's <video> element, or the app's own "
66
69
  + "detector on it) and return its RAW output alongside the app's state. Model saw nothing => the frame is at fault: "
67
- + 'regenerate it (subject filling the frame, plain background, even light), do not re-run the same one. '
70
+ + 'regenerate it framed the way a webcam would see it (objects: the scene in view, even light; hands or poses: a '
71
+ + 'person in frame with the hand raised beside the shoulder, never a close-up of the hand alone), do not re-run the same one. '
68
72
  + "Model saw it but the app's state is empty => the bug is in the app's wiring, not the picture.";
69
73
  // A camera run that comes back empty must NOT be sent down the generic
70
74
  // "raise --timeout and poll harder" path below: on a looped still frame that is
@@ -72,9 +76,9 @@ const CAMERA_FRAME_CHECK = "in the eval body, run the model on the frame YOURSEL
72
76
  // is the single most expensive way a vision app gets verified. Give it the
73
77
  // verdict and the disambiguating experiment instead.
74
78
  export const EVAL_CAMERA_EMPTY_HINT = 'The eval returned an empty value on a --camera run. --camera loops ONE still image, and the model is deterministic '
75
- + 'on it, so a longer --wait/--timeout re-runs the identical inference and returns the identical nothing — do not escalate. '
79
+ + 'on it, so a longer --wait/--timeout re-runs the identical inference and returns the identical nothing: do not escalate. '
76
80
  + `Two suspects: the frame, or the app's wiring. Tell them apart in one run: ${CAMERA_FRAME_CHECK} `
77
- + "(If the app only starts its pipeline on a click, a headless run never clicks — start it on load and gate this eval on "
81
+ + "(If the app only starts its pipeline on a click, a headless run never clicks: start it on load and gate this eval on "
78
82
  + "the app's own ready signal with --wait-for '<selector>'.)";
79
83
  /** True when the eval came back with a structurally empty container: `{}`, `[]`,
80
84
  * or an object whose every value is null/undefined/''. Exported for tests. */
@@ -127,7 +131,7 @@ export function capWaitMs(rawWait, url) {
127
131
  const wait = Number.isFinite(parsed) && parsed >= 0 ? parsed : 500;
128
132
  if (wait <= MAX_WAIT_MS)
129
133
  return wait;
130
- console.error(warning(`--wait ${wait}ms exceeds the ${MAX_WAIT_MS}ms cap (one browser session is held open synchronously; longer trips the gateway timeout) — using ${MAX_WAIT_MS}ms. ` +
134
+ console.error(warning(`--wait ${wait}ms exceeds the ${MAX_WAIT_MS}ms cap (one browser session is held open synchronously; longer trips the gateway timeout): using ${MAX_WAIT_MS}ms. ` +
131
135
  `To watch an app that keeps changing past 30s, cover the span with staggered windows in one command: gipity page test "${url}" --clients N --stagger S.`));
132
136
  return MAX_WAIT_MS;
133
137
  }
@@ -144,7 +148,7 @@ export function capWaitForTimeoutMs(raw) {
144
148
  const ms = Number.isFinite(parsed) && parsed >= 0 ? parsed : 5_000;
145
149
  if (ms <= WAIT_FOR_MAX_MS)
146
150
  return ms;
147
- console.error(warning(`--wait-timeout ${ms}ms exceeds the ${WAIT_FOR_MAX_MS}ms cap on the selector gate — using ${WAIT_FOR_MAX_MS}ms. ` +
151
+ console.error(warning(`--wait-timeout ${ms}ms exceeds the ${WAIT_FOR_MAX_MS}ms cap on the selector gate: using ${WAIT_FOR_MAX_MS}ms. ` +
148
152
  `A state that takes longer than that to appear is not a settling delay: have the page reach it on load, ` +
149
153
  `or watch for it INSIDE the script (--timeout ${EVAL_SCRIPT_BUDGET_MAX_MS}).`));
150
154
  return WAIT_FOR_MAX_MS;
@@ -218,7 +222,7 @@ export function capScriptBudgetMs(rawTimeout, hasMedia) {
218
222
  if (!Number.isFinite(parsed) || parsed <= 0)
219
223
  return fallback;
220
224
  if (parsed > EVAL_SCRIPT_BUDGET_MAX_MS) {
221
- console.error(warning(`--timeout ${parsed}ms exceeds the ${EVAL_SCRIPT_BUDGET_MAX_MS}ms max in-page budget — using ${EVAL_SCRIPT_BUDGET_MAX_MS}ms. ` +
225
+ console.error(warning(`--timeout ${parsed}ms exceeds the ${EVAL_SCRIPT_BUDGET_MAX_MS}ms max in-page budget: using ${EVAL_SCRIPT_BUDGET_MAX_MS}ms. ` +
222
226
  `A body that needs longer than that is doing its waiting in the wrong place: start the slow work on page load and ` +
223
227
  `absorb it in the pre-eval window (--wait-for '<ready-selector>'), keeping the body to a quick read.`));
224
228
  return EVAL_SCRIPT_BUDGET_MAX_MS;
@@ -255,7 +259,7 @@ export function budgetOverrunHint(reason, usedBudgetMs) {
255
259
  `(--wait-for '<ready-selector>' --wait-timeout ${MAX_WAIT_MS}), and keep the body to a quick read.`;
256
260
  }
257
261
  return `That budget was ${Math.round(usedBudgetMs / 1000)}s. Raise it with --timeout <ms> ` +
258
- `(up to ${EVAL_SCRIPT_BUDGET_MAX_MS}), e.g. --timeout ${EVAL_SCRIPT_BUDGET_MAX_MS} — ` +
262
+ `(up to ${EVAL_SCRIPT_BUDGET_MAX_MS}), e.g. --timeout ${EVAL_SCRIPT_BUDGET_MAX_MS}: ` +
259
263
  `or gate on a ready signal instead: --wait-for '<selector>' --wait-timeout ${MAX_WAIT_MS}.`;
260
264
  }
261
265
  /** The server aborts a script whose page navigated out from under it, and tells
@@ -306,14 +310,14 @@ export function slowRenderMessage(fps, o) {
306
310
  return `${warning('⚠ Slow render:')} page painted at ${fps} fps, so the app's vision pipeline ran on roughly `
307
311
  + `${bold(`${frames} frame${frames === 1 ? '' : 's'}`)} during the ${Math.round(o.waitMs / 1000)}s before this eval `
308
312
  + `(it infers once per painted frame). ${bold('That is enough:')} --camera loops your still image, so every one of `
309
- + `those frames is the SAME pixels and the model returns the SAME answer on each — re-running with a bigger `
313
+ + `those frames is the SAME pixels and the model returns the SAME answer on each: re-running with a bigger `
310
314
  + `--wait/--timeout cannot change the result. ${bold('Do not escalate the wait.')} If a detection landed, it is real. `
311
- + `If nothing was detected, the suspect is the ${bold('frame')} (a model needs the whole subject in shot — a tight crop, `
312
- + `an odd angle or a busy background reads as nothing) or the ${bold('app')} (frames never reach the model) — never the frame rate. `
315
+ + `If nothing was detected, the suspect is the ${bold('frame')} (a model needs the whole subject in shot: a tight crop, `
316
+ + `an odd angle or a busy background reads as nothing) or the ${bold('app')} (frames never reach the model): never the frame rate. `
313
317
  + `Settle it in ONE run: ${CAMERA_FRAME_CHECK}`;
314
318
  }
315
319
  return `${warning('⚠ Slow render:')} page painted at ${fps} fps. `
316
- + `Waiting on real time (setTimeout) advances animation/physics time far slower than it looks — `
320
+ + `Waiting on real time (setTimeout) advances animation/physics time far slower than it looks: `
317
321
  + `assertions after a wall-clock wait can report a false negative. `
318
322
  + `Step the app's own loop deterministically instead (3D templates: ${bold('core.advance(seconds)')}; `
319
323
  + `2D/Phaser template: ${bold("(await import('./js/config.js')).advance(seconds)")}).`;
@@ -351,10 +355,10 @@ export async function pollEvalResult(evalJobId, expectedWorkMs) {
351
355
  // big" is the one thing it is NOT. Never advise lowering --wait: on a camera /
352
356
  // vision run the wait is what lets the model load, so that "fix" swaps a
353
357
  // timeout for a silently empty read, which is worse.
354
- throw new ApiError(504, 'EVAL_TIMEOUT', `the browser did not report back within ${Math.round((expectedWorkMs + 60_000) / 1000)}s — that budget already ` +
358
+ throw new ApiError(504, 'EVAL_TIMEOUT', `the browser did not report back within ${Math.round((expectedWorkMs + 60_000) / 1000)}s: that budget already ` +
355
359
  `covers --wait, --wait-for, the eval body and any --camera setup, so this is the browser itself being slow or ` +
356
360
  `stuck (a cold sandbox, a heavy page), not your expression being too big. Lowering --wait does NOT help and on ` +
357
- `a --camera run actively hurts (the wait is what lets the vision model load — cut it and the eval reads an ` +
361
+ `a --camera run actively hurts (the wait is what lets the vision model load: cut it and the eval reads an ` +
358
362
  `empty page instead). Just run the same command again: the sandbox is warm on the second hit.`);
359
363
  }
360
364
  /** When the script's own runtime overruns the in-page budget, agent-browser can
@@ -376,11 +380,11 @@ export function evalExecTimeoutMessage(result, budgetMs) {
376
380
  if (!/CDP command timed out:\s*Runtime\.evaluate/i.test(parsed.error))
377
381
  return null;
378
382
  const budget = Math.round(budgetMs / 1000);
379
- return (`the script hit its ${budget}s in-page budget — the body (including its own await/setTimeout ` +
383
+ return (`the script hit its ${budget}s in-page budget: the body (including its own await/setTimeout ` +
380
384
  `pauses) ran longer than that. --wait sleeps BEFORE the script and does not extend it.\n` +
381
385
  (budgetOverrunHint('in-page budget', budgetMs) ?? '') + '\n' +
382
386
  `If the slow part is a ONE-TIME page init (a WASM/model download, a big asset, a first-frame ` +
383
- `pipeline warm-up), do NOT split the body across several 'page eval' calls — every call is a fresh ` +
387
+ `pipeline warm-up), do NOT split the body across several 'page eval' calls: every call is a fresh ` +
384
388
  `page load that re-pays that init, so each one hits this same wall. Have the page kick it off on ` +
385
389
  `load (not behind a click) and absorb it in the pre-eval window instead.`);
386
390
  }
@@ -406,19 +410,19 @@ const JS_DECOY_FLAGS = ['--js', '--javascript', '--script', '--code', '--expr',
406
410
  export const pageEvalCommand = new Command('eval')
407
411
  .description('Evaluate JS in a real browser on a page (DOM, computed styles, element rects; inline expr or --file script). ONE client per call - to verify realtime/presence across concurrent clients use `page test --observe` instead')
408
412
  .argument('<url>', 'URL to load')
409
- .argument('[expr]', `JavaScript to evaluate in page context (inline expression or statement body; await works, and the trailing expression is returned automatically — REPL-style — so no explicit return is needed; result is JSON-serialized). Omit when using --file. Time budget: the body has ${EVAL_SCRIPT_BUDGET_MS / 1000}s to finish after page load (${EVAL_SCRIPT_BUDGET_CAMERA_MS / 1000}s with --camera) - raise it with --timeout, max ${EVAL_SCRIPT_BUDGET_MAX_MS / 1000}s.`)
413
+ .argument('[expr]', `JavaScript to evaluate in page context (inline expression or statement body; await works, and the trailing expression is returned automatically (REPL-style) so no explicit return is needed; result is JSON-serialized). Omit when using --file. Time budget: the body has ${EVAL_SCRIPT_BUDGET_MS / 1000}s to finish after page load (${EVAL_SCRIPT_BUDGET_CAMERA_MS / 1000}s with --camera) - raise it with --timeout, max ${EVAL_SCRIPT_BUDGET_MAX_MS / 1000}s.`)
410
414
  .option('--file <path>', `Read the script body from a file instead of the inline <expr> arg (mutually exclusive), or --file - to read it from stdin (pipe a heredoc: --file - <<'EOF' ... EOF) with no tmp file. Runs as an async function body, so top-level return/await work. Same post-load budget as <expr> (--timeout).`)
411
- .option('--step <expr>', `Run another expression against the SAME loaded page, after <expr> (repeat, max ${MAX_EVAL_STEPS}). Whatever that page load paid for — a vision model coming up, a game booting, a socket connecting — stays up for every step, so an N-part check costs ONE page load instead of N. Each step gets its own in-page budget and its own reported result.`, (val, prev) => [...prev, val], [])
415
+ .option('--step <expr>', `Run another expression against the SAME loaded page, after <expr> (repeat, max ${MAX_EVAL_STEPS}). Whatever that page load paid for (a vision model coming up, a game booting, a socket connecting) stays up for every step, so an N-part check costs ONE page load instead of N. Each step gets its own in-page budget and its own reported result.`, (val, prev) => [...prev, val], [])
412
416
  .option('--fixture <path>', 'Host a local file and expose it to the eval as `fixtureUrl` (and under `fixtures` by basename) to fetch in-page. For verifying a render/parse path against a real binary (an MP3, an image) - no size limit, auto-deleted after the run. The hosted URL has permissive CORS, so `new Image(); img.crossOrigin="anonymous"; img.src=fixtureUrl` decodes untainted for a canvas/pixel read - this is the UPLOAD analog of --camera: feed a known photo/video to a file-upload vision app (web-vision-detect) and run its detector, no need to deploy a throwaway test asset into the app. Repeat for several files (single-value so it never swallows the inline <expr>).', (val, prev) => [...prev, val], [])
413
417
  .option('--reload <expr>', 'After the first eval, reload the page IN PLACE (localStorage/sessionStorage/cookies preserved) and evaluate this second expression against the post-reload DOM. One command verifies persisted state survives a reload ("remember it when I come back"): seed/assert state with <expr>, then assert the restored UI here. This is the ONLY way to check that - reloading inside the body aborts the eval (the result is lost with the old page), and two separate `page eval` calls are two fresh browser profiles, so the second starts from empty storage.')
414
418
  .option('--reload-file <path>', 'Read the post-reload expression from a file instead of inline --reload (mutually exclusive)')
415
419
  .option('--camera <path>', `Play a local image or video (.png/.jpg/.webp/.mp4/.webm/.y4m/.mjpeg) as the browser's WEBCAM feed, so a camera app's real pipeline (getUserMedia → MediaPipe/YOLOX → your app logic) runs headlessly on a frame you choose. Implies --fake-media and waits ${CAMERA_DEFAULT_WAIT_MS / 1000}s for the vision model to load. No frame handy? gipity generate image "a hand making a closed fist, palm to camera".`)
416
- .option('--fake-media', 'Grant a synthetic microphone + camera and auto-accept the getUserMedia prompt, so a voice/camera app runs headlessly instead of hitting its no-camera path. The feed is a built-in test pattern (and a tone) — nothing a vision model can recognize; to drive a vision app use --camera <path> instead.')
420
+ .option('--fake-media', 'Grant a synthetic microphone + camera and auto-accept the getUserMedia prompt, so a voice/camera app runs headlessly instead of hitting its no-camera path. The feed is a built-in test pattern (and a tone): nothing a vision model can recognize; to drive a vision app use --camera <path> instead.')
417
421
  .option('--wait <ms>', 'Sleep this many ms after DOMContentLoaded before evaluating (lets late async work settle; max 30000). With --wait-for, it elapses AFTER the selector appears - gate, then settle.', '500')
418
422
  .option('--wait-for <selector>', `Wait until this CSS selector appears before evaluating, then evaluate (deterministic - beats guessing a --wait). Gate on the state you are ASSERTING, not just a ready flag: '#verdict:not(:empty)' returns the instant the round lands, where a fixed wait snapshots mid-sequence. Same flag on page inspect/screenshot. Max ${WAIT_FOR_MAX_MS}ms (--wait-timeout).`)
419
423
  .option('--wait-timeout <ms>', `Max ms to wait for --wait-for before giving up (max ${WAIT_FOR_MAX_MS})`, '5000')
420
- .option('--timeout <ms>', `How long the script itself may run IN the page. Bare number = MILLISECONDS (so 90s = 90000, NOT 90); or pass an explicit unit that means the same on both this and \`sandbox run --timeout\` — --timeout 90s. Its own await/setTimeout pauses count (default ${EVAL_SCRIPT_BUDGET_MS}, ${EVAL_SCRIPT_BUDGET_CAMERA_MS} with --camera/--fake-media; floor 1000 - a bare number under it is rejected as a unit mix-up, a suffixed one just floors; max ${EVAL_SCRIPT_BUDGET_MAX_MS}). Raise it to trace a sequence that unfolds over time (a game round, an animation). Distinct from --wait, which only sleeps BEFORE the script.`)
421
- .option('--auth', 'Evaluate signed in as you (your Gipity account), so a page behind a Sign-in-with-Gipity login is reachable. Only works for apps using Sign in with Gipity, hosted on *.gipity.ai. Without this flag the page loads as a genuinely anonymous, signed-out visitor — nothing carries over from earlier --auth runs.')
424
+ .option('--timeout <ms>', `How long the script itself may run IN the page. Bare number = MILLISECONDS (so 90s = 90000, NOT 90); or pass an explicit unit that means the same on both this and \`sandbox run --timeout\`: --timeout 90s. Its own await/setTimeout pauses count (default ${EVAL_SCRIPT_BUDGET_MS}, ${EVAL_SCRIPT_BUDGET_CAMERA_MS} with --camera/--fake-media; floor 1000 - a bare number under it is rejected as a unit mix-up, a suffixed one just floors; max ${EVAL_SCRIPT_BUDGET_MAX_MS}). Raise it to trace a sequence that unfolds over time (a game round, an animation). Distinct from --wait, which only sleeps BEFORE the script.`)
425
+ .option('--auth', 'Evaluate signed in as you (your Gipity account), so a page behind a Sign-in-with-Gipity login is reachable. Only works for apps using Sign in with Gipity, hosted on *.gipity.ai. Without this flag the page loads as a genuinely anonymous, signed-out visitor: nothing carries over from earlier --auth runs.')
422
426
  .option('--restore-db', "Snapshot the app database before the script runs and roll it back after, so a write-path check (click Approve, submit the form, edit a row) leaves the real data untouched. Use this whenever the eval WRITES - it is the undo for driving the deployed app against real project data. Same snapshot/undo standalone: gipity db checkpoint / gipity db restore.")
423
427
  .option('--json', 'Output as JSON')
424
428
  .action((url, exprArg, opts) => run('Page eval', async () => {
@@ -426,7 +430,7 @@ export const pageEvalCommand = new Command('eval')
426
430
  // positional <expr> precisely, before the inline/--file shape checks fire.
427
431
  const decoy = JS_DECOY_FLAGS.find((f) => opts[f.slice(2)] !== undefined);
428
432
  if (decoy) {
429
- pageEvalCommand.error(`error: ${decoy} is not a flag — pass the JavaScript as the positional <expr> argument ` +
433
+ pageEvalCommand.error(`error: ${decoy} is not a flag. Pass the JavaScript as the positional <expr> argument ` +
430
434
  `(or --file <path> for a saved script), e.g. gipity page eval "<url>" 'document.title'`);
431
435
  }
432
436
  // Arg-shape errors go through commander's error() so the enableHelpAfterError
@@ -445,8 +449,8 @@ export const pageEvalCommand = new Command('eval')
445
449
  const flatUrl = url.replace(/\s+/g, ' ').trim();
446
450
  const shownUrl = flatUrl.length > 60 ? `${flatUrl.slice(0, 57)}...` : flatUrl;
447
451
  pageEvalCommand.error(exprArg !== undefined && /^https?:\/\//i.test(exprArg)
448
- ? `error: arguments are swapped — the URL is the FIRST positional: gipity page eval "${exprArg}" '<expr>'`
449
- : `error: <url> must be an absolute http(s) URL (got: "${shownUrl}") — usage: gipity page eval <url> [expr]`);
452
+ ? `error: arguments are swapped. The URL is the FIRST positional: gipity page eval "${exprArg}" '<expr>'`
453
+ : `error: <url> must be an absolute http(s) URL (got: "${shownUrl}"). Usage: gipity page eval <url> [expr]`);
450
454
  }
451
455
  let expr = exprArg;
452
456
  if (opts.file) {
@@ -475,7 +479,7 @@ export const pageEvalCommand = new Command('eval')
475
479
  }
476
480
  const steps = opts.step ?? [];
477
481
  if (steps.length > MAX_EVAL_STEPS) {
478
- pageEvalCommand.error(`error: at most ${MAX_EVAL_STEPS} --step expressions ride on one page load (got ${steps.length}) — ` +
482
+ pageEvalCommand.error(`error: at most ${MAX_EVAL_STEPS} --step expressions ride on one page load (got ${steps.length}): ` +
479
483
  `do more per step, or split this into two evals`);
480
484
  }
481
485
  // --timeout is native MILLISECONDS here but native SECONDS on the sibling
@@ -515,7 +519,7 @@ export const pageEvalCommand = new Command('eval')
515
519
  // option list as "it rejected me with help" and misses the one-line fix.
516
520
  // Throw instead: `run()` prints just the targeted message, nothing else.
517
521
  throw new Error(`--timeout is in MILLISECONDS (got ${t}, under the ${EVAL_SCRIPT_BUDGET_MIN_MS}ms in-page floor). ` +
518
- `Unlike \`sandbox run --timeout\` (seconds), page eval's is ms — or pass an explicit unit that means the ` +
522
+ `Unlike \`sandbox run --timeout\` (seconds), page eval's is ms; or pass an explicit unit that means the ` +
519
523
  `same on both: --timeout ${t}s. ${t} looks like seconds, so for ${t} second${t === 1 ? '' : 's'} pass ` +
520
524
  `--timeout ${t}s (= ${asMs}ms)` +
521
525
  `${overMax ? ` (${t}s is over the ${EVAL_SCRIPT_BUDGET_MAX_MS / 1000}s max, so this is the ceiling)` : ''}.`);
@@ -536,7 +540,7 @@ export const pageEvalCommand = new Command('eval')
536
540
  if (opts.camera && !chosenWait) {
537
541
  waitMs = CAMERA_DEFAULT_WAIT_MS;
538
542
  console.error(muted(`--camera: waiting ${CAMERA_DEFAULT_WAIT_MS / 1000}s before the eval so the camera and the app's ` +
539
- `vision model finish loading (they cannot warm up inside the eval body — that has a ` +
543
+ `vision model finish loading (they cannot warm up inside the eval body: that has a ` +
540
544
  `${scriptBudgetMs / 1000}s budget of its own, --timeout to change it). Override with --wait <ms>, or use ` +
541
545
  `--wait-for '<ready-selector>' to stop as soon as the app is ready.`));
542
546
  }
@@ -708,7 +712,12 @@ export const pageEvalCommand = new Command('eval')
708
712
  const who = getAuth()?.email;
709
713
  console.log(d.auth.established
710
714
  ? `${muted('Auth:')} ${success('session established')}${who ? muted(` as ${who}`) : ''} ${muted('(what the page renders with it is app-defined)')}`
711
- : `${warning('Auth: session NOT established')}${d.auth.detail ? ` — ${d.auth.detail}` : ''} ${muted('(this is the anonymous view)')}`);
715
+ : `${warning('Auth: session NOT established')}${d.auth.detail ? `: ${d.auth.detail}` : ''} ${muted('(this is the anonymous view)')}`);
716
+ // A signed-in run is how a write flow gets driven (add, edit, submit,
717
+ // delete), and every such run writes real rows. Agents found --auth but
718
+ // not the undo, then hand-scrubbed leaked rows that skewed the next run.
719
+ if (d.auth.established && !opts.restoreDb)
720
+ console.log(muted(RESTORE_DB_TIP));
712
721
  }
713
722
  else {
714
723
  console.log(muted('Auth: anonymous visitor (signed out; pass --auth to run as your Gipity account)'));
@@ -733,7 +742,7 @@ export const pageEvalCommand = new Command('eval')
733
742
  console.log(muted(EVAL_NO_VALUE_HINT));
734
743
  }
735
744
  if (reload) {
736
- console.log(`\n${bold('After reload')} ${muted('(page reloaded in place — storage preserved)')}`);
745
+ console.log(`\n${bold('After reload')} ${muted('(page reloaded in place: storage preserved)')}`);
737
746
  console.log(reload.result.trim() ? reload.result : muted('(empty result)'));
738
747
  if (reload.noValue)
739
748
  console.log(muted(EVAL_NO_VALUE_HINT));
@@ -756,7 +765,7 @@ export const pageEvalCommand = new Command('eval')
756
765
  await deleteFixture(projectGuid, h.guid);
757
766
  }
758
767
  catch (err) {
759
- console.error(warning(`⚠ Could not auto-delete fixture "${h.name}" (${h.guid}) — still hosted at ${h.url}: ${err.message}`));
768
+ console.error(warning(`⚠ Could not auto-delete fixture "${h.name}" (${h.guid}): still hosted at ${h.url}: ${err.message}`));
760
769
  }
761
770
  }
762
771
  }
@@ -797,7 +806,7 @@ Examples:
797
806
  --reload "({ restored: localStorage.getItem('todo'), heading: document.querySelector('h1')?.textContent })"
798
807
 
799
808
  # Camera app (MediaPipe / YOLOX / any getUserMedia app): play a real image as
800
- # the webcam so the app's OWN pipeline runs on a frame you control — no need to
809
+ # the webcam so the app's OWN pipeline runs on a frame you control: no need to
801
810
  # stub the model or export internals just to test around a missing camera.
802
811
  # --camera waits ${CAMERA_DEFAULT_WAIT_MS / 1000}s before evaluating (model load + first frame); the script
803
812
  # itself then gets ${EVAL_SCRIPT_BUDGET_CAMERA_MS / 1000}s in the page (--timeout, max ${EVAL_SCRIPT_BUDGET_MAX_MS / 1000}s).
@@ -829,18 +838,26 @@ Examples:
829
838
 
830
839
  Module resolution: dynamic import() specifiers starting with ./ or ../ resolve
831
840
  against the PAGE URL, so import('./packages/i18n/index.js') loads the app's own
832
- module without hand-building the deployed /account/project/ path. Absolute paths
833
- and full URLs pass through unchanged.
841
+ module without hand-building the deployed /account/project/ path. On app.gipity.ai
842
+ and dev.gipity.ai a root path means the APP root: import('/js/core.js') loads
843
+ /account/project/js/core.js. Full URLs pass through unchanged.
844
+
845
+ Driving a form or a write flow: the body can fill and submit the real form
846
+ (form.requestSubmit()) and poll for the app's status in the same run. If the run
847
+ fails with "a <form> was submitted and nothing called event.preventDefault()",
848
+ the submit handler was not wired yet (gate with --wait-for on the app's ready
849
+ signal) or prevents default only after an await. Writes go to the real app
850
+ database: add --restore-db and they are rolled back when the run ends.
834
851
 
835
852
  Time budget: the script runs under a ${EVAL_SCRIPT_BUDGET_MS / 1000}s in-page budget (${EVAL_SCRIPT_BUDGET_CAMERA_MS / 1000}s with --camera/--fake-media),
836
853
  counting its own await/setTimeout pauses. Two separate knobs:
837
- --timeout <ms> how long the SCRIPT may run in the page (max ${EVAL_SCRIPT_BUDGET_MAX_MS}) — raise this to
854
+ --timeout <ms> how long the SCRIPT may run in the page (max ${EVAL_SCRIPT_BUDGET_MAX_MS}): raise this to
838
855
  trace a sequence that unfolds over time (a game round, an animation)
839
- --wait / --wait-for how long to settle BEFORE the script runs — a blind sleep, a
856
+ --wait / --wait-for how long to settle BEFORE the script runs: a blind sleep, a
840
857
  selector gate, or both (gate first, then sleep). Neither extends --timeout.
841
858
  Which one:
842
859
  - waiting for the app to REACH a state before you read it → --wait-for '<selector>'
843
- (gate on the end state — '#verdict:not(:empty)' — not just a ready flag; a bare
860
+ (gate on the end state ('#verdict:not(:empty)') not just a ready flag; a bare
844
861
  --wait samples one arbitrary instant and can land mid-sequence). Passing both means
845
862
  gate first, then settle --wait ms.
846
863
  - watching state evolve (poll until a result lands, record a trace) → --timeout
@@ -43,7 +43,7 @@ export const pageInspectCommand = new Command('inspect')
43
43
  .option('--all', 'Include render-blocking, large resources, oversized images, overflow culprits, and LCP detail')
44
44
  .option('--no-fake-media', "Inspect with NO camera or microphone present, so a getUserMedia app takes its no-device error path (use this only when that fallback IS what you're inspecting)")
45
45
  .option('--device <name>', `Inspect as a real touch device: ${INSPECT_DEVICES.join(', ')}. Emulates touch events, mobile user-agent and DPR, so a touch-gated mobile layout is what gets inspected.`)
46
- .option('--auth', 'Load the page signed in as you (your Gipity account), so pages behind a Sign-in-with-Gipity login are reachable. Only works for apps using Sign in with Gipity, hosted on *.gipity.ai. Without this flag the page loads as a genuinely anonymous, signed-out visitor — nothing carries over from earlier --auth runs.')
46
+ .option('--auth', 'Load the page signed in as you (your Gipity account), so pages behind a Sign-in-with-Gipity login are reachable. Only works for apps using Sign in with Gipity, hosted on *.gipity.ai. Without this flag the page loads as a genuinely anonymous, signed-out visitor: nothing carries over from earlier --auth runs.')
47
47
  // Hidden redirect: agents reach for `page inspect --screenshot`. We don't take
48
48
  // an image here (`page screenshot` is the single path for that) — just point there.
49
49
  .addOption(new Option('--screenshot [path]', 'Capture a screenshot').hideHelp())
@@ -94,7 +94,7 @@ export async function inspectPage(url, opts = {}) {
94
94
  return;
95
95
  }
96
96
  console.log(`${brand('Inspecting')} ${bold(url)}`);
97
- console.log(warning('Captured no page data — the page returned an empty response.'));
97
+ console.log(warning('Captured no page data: the page returned an empty response.'));
98
98
  console.log(muted('The page may have failed to load, redirected away, or rendered nothing server-side. Retry once; if it persists pass --wait-for <selector> to wait for a specific element to appear, or --auth if it is behind Sign in with Gipity.'));
99
99
  return;
100
100
  }
@@ -188,7 +188,7 @@ export async function inspectPage(url, opts = {}) {
188
188
  const who = getAuth()?.email;
189
189
  console.log(b.auth.established
190
190
  ? `${muted('Auth:')} ${success('session established')}${who ? muted(` as ${who}`) : ''} ${muted('(what the page renders with it is app-defined)')}`
191
- : `${warning('Auth: session NOT established')}${b.auth.detail ? ` — ${b.auth.detail}` : ''} ${muted('(this is the anonymous view)')}`);
191
+ : `${warning('Auth: session NOT established')}${b.auth.detail ? `: ${b.auth.detail}` : ''} ${muted('(this is the anonymous view)')}`);
192
192
  }
193
193
  else {
194
194
  console.log(muted('Auth: anonymous visitor (signed out; pass --auth to load as your Gipity account)'));
@@ -202,7 +202,7 @@ export async function inspectPage(url, opts = {}) {
202
202
  // real story is "client render or auth gate produced nothing yet." Flag it
203
203
  // so the agent knows to wait for the render or sign in, not to trust silence.
204
204
  if ((b.elementCount || 0) === 0 && !b.title) {
205
- console.log(`${warning('⚠ Rendered no DOM (0 elements, no title)')} ${muted('— the client-side render likely had not run yet (try --wait-for <selector>), the page failed to load, or it is behind a sign-in gate (try --auth).')}`);
205
+ console.log(`${warning('⚠ Rendered no DOM (0 elements, no title)')} ${muted('The client-side render likely had not run yet (try --wait-for <selector>), the page failed to load, or it is behind a sign-in gate (try --auth).')}`);
206
206
  }
207
207
  // ── Timing ──
208
208
  console.log(`\n${bold('Timing:')}`);
@@ -228,12 +228,12 @@ export async function inspectPage(url, opts = {}) {
228
228
  for (const line of transientErrors) {
229
229
  console.log(muted(line));
230
230
  }
231
- console.log(muted('One-time cold-load artifact (first hit of freshly-deployed assets) — not reproducible, not in your app code. Ignore unless it recurs.'));
231
+ console.log(muted('One-time cold-load artifact (first hit of freshly-deployed assets): not reproducible, not in your app code. Ignore unless it recurs.'));
232
232
  }
233
233
  // ── Cross-origin console errors (message-less; source hidden by the browser) ──
234
234
  if (crossOriginErrors.length > 0) {
235
235
  console.log(`\n${bold('Cross-origin console errors')} ${muted(`(${crossOriginErrors.length}, source hidden by the browser)`)}:`);
236
- console.log(muted("Message-less — the throwing <script> lacks CORS, so the browser hides its source and there's no own-code stack to chase. Gipity's injected SDK is itself cross-origin, so if your app loads no third-party CDN scripts these are platform noise — ignore them. If your app DOES load a third-party <script>, add crossorigin=\"anonymous\" to that tag to surface the real error."));
236
+ console.log(muted("Message-less: the throwing <script> lacks CORS, so the browser hides its source and there's no own-code stack to chase. Gipity's injected SDK is itself cross-origin, so if your app loads no third-party CDN scripts these are platform noise; ignore them. If your app DOES load a third-party <script>, add crossorigin=\"anonymous\" to that tag to surface the real error."));
237
237
  }
238
238
  // ── Failed Resources ──
239
239
  // Browsers auto-request /favicon.ico at the site root for every page, so a