gipity 1.1.16 → 1.1.20

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 (60) hide show
  1. package/README.md +58 -75
  2. package/dist/adopt-cwd.js +2 -13
  3. package/dist/api.js +27 -45
  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 +12 -12
  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 +1631 -1517
  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/provider-docs.js +22 -25
  49. package/dist/realtime-bench.js +12040 -0
  50. package/dist/relay/agent-token.js +1 -1
  51. package/dist/relay/daemon.js +0 -1
  52. package/dist/relay/setup.js +13 -2
  53. package/dist/setup.js +11 -12
  54. package/dist/sync.js +3 -3
  55. package/dist/utils.js +1 -1
  56. package/package.json +10 -4
  57. package/dist/commands/agent.js +0 -251
  58. package/dist/commands/chat.js +0 -137
  59. package/dist/commands/claude.js +0 -1056
  60. package/dist/commands/plan.js +0 -93
@@ -18,6 +18,104 @@ async function inspectClient(url, waitMs, i) {
18
18
  }
19
19
  const MAX_HOLD_MS = 15_000; // keep each in-page await under the ~20s browser action timeout
20
20
  const MIN_HOLD_MS = 1_000;
21
+ // ── lifecycle actions (--at) ───────────────────────────────────────────────
22
+ // Freeze, hide, or take one client offline partway through the hold window, so
23
+ // an app can test what its peers do when a phone locks (host handoff) instead
24
+ // of only a clean leave. The server applies them in the browser over CDP; the
25
+ // CLI parses and validates the specs and shows the timeline.
26
+ export const LIFECYCLE_ACTIONS = ['freeze', 'wake', 'hide', 'show', 'offline', 'online'];
27
+ /** Sample value recorded for an observe slot the page's JS never got to run
28
+ * (it was frozen, or blocked, when the sample was due). */
29
+ export const PAUSED_SAMPLE = '(paused)';
30
+ /** How late a sample may run before it counts as slept through. */
31
+ export const PAUSE_SLACK_MS = 1500;
32
+ const AT_SYNTAX = '"<label|index>:<action>@<ms>", e.g. --at host:freeze@5000';
33
+ /** Parse the repeatable --at specs into per-client step lists (index-aligned
34
+ * with `labels`, one entry per client). A target matches every client with
35
+ * that label (so `phone:hide@3000` hides every phone), else a 0-based index.
36
+ * Throws a caller-facing error on bad syntax, an unknown client or action, a
37
+ * time outside the hold window, or an impossible sequence (wake without a
38
+ * freeze, ...). The server re-checks the sequence; this is the early error. */
39
+ export function parseAtSpecs(specs, labels, holdMs) {
40
+ const perClient = labels.map(() => []);
41
+ for (const raw of specs) {
42
+ const m = /^\s*([^:@\s]+)\s*:\s*([A-Za-z]+)\s*@\s*(\d+)\s*(?:ms)?\s*$/.exec(raw);
43
+ if (!m)
44
+ throw new Error(`--at "${raw}": expected ${AT_SYNTAX}`);
45
+ const [, target, rawAction, rawMs] = m;
46
+ const action = rawAction.toLowerCase();
47
+ if (!LIFECYCLE_ACTIONS.includes(action)) {
48
+ throw new Error(`--at "${raw}": unknown action "${rawAction}". Use one of: ${LIFECYCLE_ACTIONS.join(', ')}`);
49
+ }
50
+ const atMs = parseInt(rawMs, 10);
51
+ if (atMs >= holdMs) {
52
+ throw new Error(`--at "${raw}": ${atMs}ms is past the end of the ${holdMs}ms --hold window. Actions must happen inside it (raise --hold, max ${MAX_HOLD_MS}ms, or move the action earlier).`);
53
+ }
54
+ let targets = labels.flatMap((l, i) => (l === target ? [i] : []));
55
+ if (targets.length === 0 && /^\d+$/.test(target) && Number(target) < labels.length)
56
+ targets = [Number(target)];
57
+ if (targets.length === 0) {
58
+ throw new Error(`--at "${raw}": no client "${target}". Use a label (${[...new Set(labels)].join(', ')}) or an index 0-${labels.length - 1}.`);
59
+ }
60
+ for (const i of targets)
61
+ perClient[i].push({ atMs, action });
62
+ }
63
+ perClient.forEach((steps, i) => {
64
+ steps.sort((a, b) => a.atMs - b.atMs);
65
+ const err = sequenceError(steps);
66
+ if (err)
67
+ throw new Error(`--at for client ${i} (${labels[i]}): ${err}`);
68
+ });
69
+ return perClient;
70
+ }
71
+ /** First impossible transition in a time-ordered step list, or null. Freeze
72
+ * already hides the page (as a locking phone does), so hide/freeze don't stack. */
73
+ function sequenceError(steps) {
74
+ const on = { frozen: false, hidden: false, offline: false };
75
+ for (const { action, atMs } of steps) {
76
+ const at = `${action}@${atMs}`;
77
+ if (action === 'freeze') {
78
+ if (on.frozen)
79
+ return `${at}: already frozen`;
80
+ if (on.hidden)
81
+ return `${at}: the page is hidden; show it first (freeze hides the page on its own)`;
82
+ on.frozen = true;
83
+ }
84
+ else if (action === 'wake') {
85
+ if (!on.frozen)
86
+ return `${at}: not frozen (wake undoes freeze)`;
87
+ on.frozen = false;
88
+ }
89
+ else if (action === 'hide') {
90
+ if (on.hidden || on.frozen)
91
+ return `${at}: already ${on.frozen ? 'frozen, which hides the page' : 'hidden'}`;
92
+ on.hidden = true;
93
+ }
94
+ else if (action === 'show') {
95
+ if (!on.hidden)
96
+ return `${at}: not hidden (show undoes hide)`;
97
+ on.hidden = false;
98
+ }
99
+ else if (action === 'offline') {
100
+ if (on.offline)
101
+ return `${at}: already offline`;
102
+ on.offline = true;
103
+ }
104
+ else {
105
+ if (!on.offline)
106
+ return `${at}: not offline (online undoes offline)`;
107
+ on.offline = false;
108
+ }
109
+ }
110
+ return null;
111
+ }
112
+ function fmtTimeline(events) {
113
+ return events.map((e) => {
114
+ const when = e.appliedMs === null ? `@${e.atMs}ms` : `+${(e.appliedMs / 1000).toFixed(1)}s`;
115
+ const note = e.error ? clrError(` (failed: ${e.error})`) : e.auto ? muted(' (auto, end of hold)') : '';
116
+ return `${e.action} ${when}${note}`;
117
+ }).join(' → ');
118
+ }
21
119
  /** Splice per-client values into a user string (URL, --action, or --observe).
22
120
  * `{{label}}` → the client's label, `{{i}}` → its 0-based index. Plain string
23
121
  * replace (no regex) so the string's own characters are never treated as
@@ -43,12 +141,12 @@ function unknownTokens(...strings) {
43
141
  function warnUnknownTokens(unknown) {
44
142
  if (unknown.length === 0)
45
143
  return;
46
- console.error(warning(`⚠ Unrecognized placeholder ${unknown.join(', ')} left as-is — only {{i}} (0-based client index) and {{label}} are substituted per client. Set per-client values with --labels and reference them as {{label}}.`));
144
+ console.error(warning(`⚠ Unrecognized placeholder ${unknown.join(', ')} left as-is: only {{i}} (0-based client index) and {{label}} are substituted per client. Set per-client values with --labels and reference them as {{label}}.`));
47
145
  }
48
146
  /** Build the statement-body script one client runs: do the one-time action,
49
147
  * then sample `observe` `samples` times across `holdMs`, stamping in-page
50
148
  * start/end so the caller can confirm the clients overlapped. */
51
- function buildHarness(action, observe, label, holdMs, samples) {
149
+ export function buildHarness(action, observe, label, holdMs, samples) {
52
150
  const n = Math.max(2, samples);
53
151
  const interval = Math.max(0, Math.floor(holdMs / (n - 1)));
54
152
  const lines = [
@@ -58,11 +156,17 @@ function buildHarness(action, observe, label, holdMs, samples) {
58
156
  if (action && action.trim()) {
59
157
  lines.push(`try{ ${action} }catch(__e){ return {label:__label,startedAt:__t0,endedAt:Date.now(),samples:[],actionError:String((__e&&__e.message)||__e)}; }`);
60
158
  }
61
- lines.push(`const __s=[];`, `for(let __k=0;__k<${n};__k++){`, ` let __v; try{ __v=(${observe}); }catch(__e){ __v='ObserveError: '+String((__e&&__e.message)||__e); }`, ` __s.push(__v);`, ` if(__k<${n - 1}) await new Promise(function(r){setTimeout(r,${interval});});`, `}`, `return {label:__label,startedAt:__t0,endedAt:Date.now(),samples:__s};`);
159
+ // Samples are due on a fixed schedule from the first one. A page that could
160
+ // not run when a sample was due (frozen by --at, or blocked) records
161
+ // PAUSED_SAMPLE for each slot it reached more than PAUSE_SLACK_MS late,
162
+ // instead of a stale reading taken the moment it resumes. The slack keeps a
163
+ // hidden page's throttled (about 1/s) timers from reading as paused. The
164
+ // last slot always takes a reading.
165
+ lines.push(`const __s=[]; const __ts=Date.now();`, `for(let __k=0;__k<${n};__k++){`, ` const __w=__ts+__k*${interval}-Date.now();`, ` if(__w>0) await new Promise(function(r){setTimeout(r,__w);});`, ` if(__k<${n - 1}&&Date.now()>__ts+__k*${interval}+${PAUSE_SLACK_MS}){ __s.push(${JSON.stringify(PAUSED_SAMPLE)}); continue; }`, ` let __v; try{ __v=(${observe}); }catch(__e){ __v='ObserveError: '+String((__e&&__e.message)||__e); }`, ` __s.push(__v);`, `}`, `return {label:__label,startedAt:__t0,endedAt:Date.now(),samples:__s};`);
62
166
  return lines.join('\n');
63
167
  }
64
168
  /** Kick off and poll one client's eval job, then parse the harness payload. */
65
- async function observeClient(url, expr, i, label, settleMs, holdMs, waitForSelector) {
169
+ async function observeClient(url, expr, i, label, settleMs, holdMs, waitForSelector, lifecycle) {
66
170
  const base = { i, label, samples: [], startedAt: 0, endedAt: 0 };
67
171
  try {
68
172
  const kickoff = await post('/tools/browser/eval', {
@@ -71,6 +175,9 @@ async function observeClient(url, expr, i, label, settleMs, holdMs, waitForSelec
71
175
  waitMs: settleMs,
72
176
  waitForSelector: waitForSelector || undefined,
73
177
  waitForTimeoutMs: waitForSelector ? 5000 : undefined,
178
+ // Timed from the start of the observe window; the server restores
179
+ // anything still applied at the end of the hold so the harness finishes.
180
+ lifecycle: lifecycle?.length ? { steps: lifecycle, untilMs: holdMs } : undefined,
74
181
  });
75
182
  // Server work ≈ nav + settle + the in-page hold; pollEvalResult adds 60s headroom.
76
183
  const d = await pollEvalResult(kickoff.data.evalJobId, settleMs + holdMs);
@@ -88,13 +195,34 @@ async function observeClient(url, expr, i, label, settleMs, holdMs, waitForSelec
88
195
  if (parsed.actionError) {
89
196
  return { ...base, error: `action failed: ${parsed.actionError}` };
90
197
  }
91
- return {
198
+ const startedAt = typeof parsed.startedAt === 'number' ? parsed.startedAt : 0;
199
+ const out = {
92
200
  i,
93
201
  label: typeof parsed.label === 'string' ? parsed.label : label,
94
202
  samples: Array.isArray(parsed.samples) ? parsed.samples : [],
95
- startedAt: typeof parsed.startedAt === 'number' ? parsed.startedAt : 0,
203
+ startedAt,
96
204
  endedAt: typeof parsed.endedAt === 'number' ? parsed.endedAt : 0,
97
205
  };
206
+ if (lifecycle?.length) {
207
+ // A step that silently didn't happen would make "the handoff works" a
208
+ // false positive, so a missing or failed step fails the client.
209
+ const report = d.lifecycle;
210
+ out.lifecycle = (report?.events ?? []).map((e) => ({
211
+ action: e.action,
212
+ atMs: e.atMs,
213
+ appliedMs: typeof e.appliedAt === 'number' && startedAt > 0 ? e.appliedAt - startedAt : null,
214
+ ...(e.auto ? { auto: true } : {}),
215
+ ...(e.error ? { error: e.error } : {}),
216
+ }));
217
+ const failed = out.lifecycle.find((e) => e.error);
218
+ if (!report)
219
+ out.error = 'lifecycle actions were not applied (the server did not report them; it may need updating)';
220
+ else if (report.error)
221
+ out.error = `lifecycle actions failed: ${report.error}`;
222
+ else if (failed)
223
+ out.error = `lifecycle ${failed.action}@${failed.atMs} failed: ${failed.error}`;
224
+ }
225
+ return out;
98
226
  }
99
227
  catch (err) {
100
228
  return { ...base, error: err instanceof Error ? err.message : String(err) };
@@ -111,6 +239,22 @@ function overlapMs(results) {
111
239
  const end = Math.min(...live.map((r) => r.endedAt));
112
240
  return Math.max(0, end - start);
113
241
  }
242
+ /** One explanation for an --observe expression that threw, printed once under
243
+ * the client blocks. The bare `ObserveError: Cannot read properties of null`
244
+ * sample reads like a quirk of the harness, so it got waved off as "the observe
245
+ * context is different" when it was a real selector (or app) bug on the live
246
+ * page. Exported for tests. */
247
+ export function observeErrorHint(results) {
248
+ const thrown = results.flatMap((r) => r.samples)
249
+ .find((v) => typeof v === 'string' && v.startsWith('ObserveError:'));
250
+ if (!thrown)
251
+ return null;
252
+ const nullRead = /of null|of undefined/.test(thrown)
253
+ ? ' "of null" means a querySelector in it matched nothing at that moment: the element is missing, renamed, or not rendered yet.'
254
+ : '';
255
+ return `ObserveError = your --observe expression threw. It runs against the live deployed page, the same DOM \`page eval\` sees, so this is the page's real state, not a harness quirk.${nullRead} ` +
256
+ "Check the selector with `gipity page eval <url> \"!!document.querySelector('<selector>')\"`, or gate the run on it with --wait-for '<selector>'.";
257
+ }
114
258
  function fmtSamples(samples) {
115
259
  if (samples.length === 0)
116
260
  return muted('(no samples)');
@@ -124,7 +268,7 @@ async function runInteractive(url, observe, opts) {
124
268
  if (rawHold > MAX_HOLD_MS) {
125
269
  // Surface the clamp (to stderr, so --json stdout stays clean) instead of
126
270
  // leaving the agent to infer it from the printed "hold Nms" line.
127
- console.error(warning(`--hold ${rawHold}ms exceeds the ${MAX_HOLD_MS}ms per-client cap (each client samples inside one browser eval, bounded by the server's eval budget) — using ${MAX_HOLD_MS}ms. ` +
271
+ console.error(warning(`--hold ${rawHold}ms exceeds the ${MAX_HOLD_MS}ms per-client cap (each client samples inside one browser eval, bounded by the server's eval budget): using ${MAX_HOLD_MS}ms. ` +
128
272
  `Co-launch every role in this one command (put {{label}}/{{i}} in the URL) so all clients overlap for the whole window; a separately-started background client overlaps only the sliver of its window that lines up.`));
129
273
  }
130
274
  const samples = Math.min(30, Math.max(2, parseInt(opts.samples, 10) || 6));
@@ -135,9 +279,13 @@ async function runInteractive(url, observe, opts) {
135
279
  // (a natural guess like {{name}} or {{index}}) so it isn't sent literally to
136
280
  // every client — the silent wrong-behavior trap of identical clients.
137
281
  warnUnknownTokens(unknownTokens(url, opts.action, observe));
282
+ const atSpecs = opts.at ?? [];
283
+ const lifecycle = parseAtSpecs(atSpecs, Array.from({ length: clients }, (_, i) => labelFor(i)), hold);
138
284
  if (!opts.json) {
139
285
  console.log(`${brand('Page test')} ${muted('(interactive)')} ${bold(url)}`);
140
286
  console.log(muted(`${clients} client(s), stagger ${stagger}s, hold ${hold}ms, ${samples} samples each`));
287
+ if (atSpecs.length)
288
+ console.log(muted(`lifecycle (ms into each client's hold): ${atSpecs.map((s) => s.trim()).join(', ')}`));
141
289
  }
142
290
  const runs = [];
143
291
  for (let i = 0; i < clients; i++) {
@@ -150,7 +298,7 @@ async function runInteractive(url, observe, opts) {
150
298
  // and the overlap check still confirms they coexisted.
151
299
  const clientUrl = subst(url, labelFor(i), i);
152
300
  const expr = buildHarness(opts.action ? subst(opts.action, labelFor(i), i) : undefined, subst(observe, labelFor(i), i), labelFor(i), hold, samples);
153
- return observeClient(clientUrl, expr, i, labelFor(i), settle, hold, opts.waitFor);
301
+ return observeClient(clientUrl, expr, i, labelFor(i), settle, hold, opts.waitFor, lifecycle[i]);
154
302
  })());
155
303
  }
156
304
  const results = (await Promise.all(runs)).sort((a, b) => a.i - b.i);
@@ -160,6 +308,7 @@ async function runInteractive(url, observe, opts) {
160
308
  if (opts.json) {
161
309
  console.log(JSON.stringify({
162
310
  url, mode: 'interactive', clients, stagger, hold, samples,
311
+ ...(atSpecs.length ? { at: atSpecs.map((s) => s.trim()) } : {}),
163
312
  overlapMs: ovl, overlapped, results,
164
313
  }));
165
314
  if (errored.length > 0 || (clients > 1 && !overlapped))
@@ -168,24 +317,29 @@ async function runInteractive(url, observe, opts) {
168
317
  }
169
318
  for (const r of results) {
170
319
  console.log(`\n${bold(`=== client ${r.i} (${r.label}) ===`)}`);
320
+ if (r.lifecycle?.length)
321
+ console.log(`${muted('timeline:')} ${fmtTimeline(r.lifecycle)}`);
171
322
  if (r.error) {
172
323
  console.log(clrError(`✗ ${r.error}`));
173
324
  continue;
174
325
  }
175
326
  console.log(`${muted('samples:')} ${fmtSamples(r.samples)}`);
176
327
  }
328
+ const observeHint = observeErrorHint(results);
329
+ if (observeHint)
330
+ console.log(`\n${warning(observeHint)}`);
177
331
  console.log('');
178
332
  if (errored.length > 0) {
179
333
  console.log(clrError(`⚠ ${errored.length} client(s) failed (see above)`));
180
334
  }
181
335
  if (clients < 2) {
182
- console.log(muted('Note: a single client cannot verify cross-client visibility — run with --clients 2+.'));
336
+ console.log(muted('Note: a single client cannot verify cross-client visibility: run with --clients 2+.'));
183
337
  }
184
338
  else if (overlapped) {
185
- console.log(success(`✓ all clients overlapped for ~${(ovl / 1000).toFixed(1)}s — genuine concurrency, so the readings above are trustworthy`));
339
+ console.log(success(`✓ all clients overlapped for ~${(ovl / 1000).toFixed(1)}s: genuine concurrency, so the readings above are trustworthy`));
186
340
  }
187
341
  else {
188
- console.log(clrError('⚠ clients did NOT overlap in time — each ran in isolation, so any shared-state reading here is a FALSE NEGATIVE, not proof the app is broken.'));
342
+ console.log(clrError('⚠ clients did NOT overlap in time: each ran in isolation, so any shared-state reading here is a FALSE NEGATIVE, not proof the app is broken.'));
189
343
  console.log(muted(' Likely causes: --stagger ≥ --hold, or more --clients than free browser slots (they queued). Lower --stagger / raise --hold / fewer --clients and retry.'));
190
344
  }
191
345
  if (errored.length > 0 || (clients > 1 && !overlapped))
@@ -272,13 +426,14 @@ export const pageTestCommand = new Command('test')
272
426
  .option('--hold <ms>', `Interactive: total observe window per client (${MIN_HOLD_MS}-${MAX_HOLD_MS}ms)`, '8000')
273
427
  .option('--samples <k>', 'Interactive: number of observations across the hold window (2-30)', '6')
274
428
  .option('--wait-for <selector>', 'Interactive: wait for this CSS selector before running --action (deterministic readiness gate)')
429
+ .option('--at <spec>', `Interactive: lifecycle action on one client mid-run, "<label|index>:<action>@<ms>" (ms into that client's hold window). Actions: freeze|wake (locked phone: JS stops, socket stays open), hide|show (backgrounded tab), offline|online (network drop). Repeatable; anything still applied at the end of --hold is restored.`, (v, prev = []) => [...prev, v])
275
430
  .option('--json', 'Output as JSON')
276
431
  .addHelpText('after', `
277
432
  Examples:
278
433
  # Passive: load in 3 staggered clients, flag console errors
279
434
  gipity page test "https://dev.gipity.ai/me/app/" --clients 3 --stagger 8
280
435
 
281
- # Per-client URL params: each client joins under a distinct name (Bot0, Bot1, …)
436
+ # Per-client URL params: each client joins under a distinct name (Bot0, Bot1, ...)
282
437
  gipity page test "https://dev.gipity.ai/me/app/?name=Bot{{i}}" --clients 2
283
438
 
284
439
  # Interactive: two concurrent clients each join with a name, then watch the
@@ -290,11 +445,30 @@ Examples:
290
445
 
291
446
  # Asymmetric roles in ONE invocation: {{label}} in the URL routes client 0 to
292
447
  # host and client 1 to join. They overlap in time (verified), so the joiner
293
- # observes the live state the host is driving — no background-process dance.
448
+ # observes the live state the host is driving: no background-process dance.
294
449
  gipity page test "https://dev.gipity.ai/me/app/?test-action={{label}}" --clients 2 \\
295
450
  --labels host,join \\
296
- --observe "document.querySelector('[data-screen]')?.dataset.screen"`)
451
+ --observe "document.querySelector('[data-screen]')?.dataset.screen"
452
+
453
+ # Host handoff: lock the host's phone 5s in (its JS stops, its socket stays
454
+ # open, so nobody sees a leave) and watch who the phones think is host.
455
+ gipity page test "https://dev.gipity.ai/me/app/?role={{label}}" --clients 3 \\
456
+ --labels host,phone,phone --hold 15000 --at host:freeze@5000 --at host:wake@12000 \\
457
+ --observe "window.game?.hostId"
458
+
459
+ freeze: the page's JS stops (timers, rendering, message handlers) and it fires
460
+ visibilitychange (hidden) then freeze, like a phone locking. Its WebSocket stays
461
+ open, so the server sees no leave. On wake the page resumes and Chrome drops that
462
+ socket (close code 1006), so the app's reconnect path runs. Samples due while a
463
+ client was frozen read (paused).
464
+ hide: backgrounded tab (document.hidden, rAF stops, timers throttle to ~1/s); JS
465
+ and the socket keep running.
466
+ offline: navigator.onLine false, new requests fail, and an open WebSocket stalls
467
+ without closing; online delivers the held traffic.`)
297
468
  .action((url, opts) => run('Page test', async () => {
469
+ if (opts.at?.length && !opts.observe) {
470
+ throw new Error('--at needs interactive mode: add --observe "<expr>" to watch what the other clients do while one is frozen, hidden, or offline');
471
+ }
298
472
  if (opts.observe) {
299
473
  await runInteractive(url, opts.observe, opts);
300
474
  }
@@ -15,7 +15,7 @@ function renderStatus(status) {
15
15
  console.log(` Payouts: ${payouts}`);
16
16
  console.log(` Onboarding: ${status.details_submitted ? 'complete' : 'incomplete'}`);
17
17
  if (!status.charges_enabled) {
18
- console.log(muted('\nCharges are not enabled yet — finish Stripe onboarding via `gipity payments connect`.'));
18
+ console.log(muted('\nCharges are not enabled yet: finish Stripe onboarding via `gipity payments connect`.'));
19
19
  }
20
20
  }
21
21
  export const paymentsCommand = new Command('payments')
@@ -23,7 +23,7 @@ export const paymentsCommand = new Command('payments')
23
23
  .addHelpText('after', '\nAccept one-time purchases and subscriptions. Set up with `gipity payments connect`.');
24
24
  paymentsCommand
25
25
  .command('connect')
26
- .description('Start (or resume) Stripe onboarding for this app — prints a link to finish in your browser')
26
+ .description('Start (or resume) Stripe onboarding for this app: prints a link to finish in your browser')
27
27
  .option('--return-url <url>', 'Where Stripe redirects after onboarding')
28
28
  .option('--json', 'Output as JSON')
29
29
  .action((opts) => run('Payments', async () => {
@@ -10,8 +10,11 @@ import { run, printList, printResult } from '../helpers/index.js';
10
10
  import { getProjectsRoot } from '../relay/paths.js';
11
11
  import { finalizeLocalProject } from '../project-setup.js';
12
12
  import * as relayState from '../relay/state.js';
13
+ const AUTH_MODES = ['gipity', 'app', 'both'];
13
14
  export const projectCommand = new Command('project')
14
15
  .description('Manage projects')
16
+ // Options after a subcommand (`project auth --json`) belong to it, not to `project`.
17
+ .enablePositionalOptions()
15
18
  .argument('[name]', 'Switch to project by name/slug')
16
19
  .option('--json', 'Output as JSON')
17
20
  .action((name, opts) => run('Project', async () => {
@@ -68,7 +71,8 @@ projectCommand
68
71
  .option('--json', 'Output as JSON')
69
72
  .action((name, opts) => run('Create', async () => {
70
73
  const slug = opts.slug || slugify(name);
71
- // Auto-chat so the project surfaces at the top of both picker lists -
74
+ // On a paired relay device, pre-create the placeholder claude_code chat
75
+ // so the project surfaces at the top of both picker lists -
72
76
  // `projects.dal.ts` orders by most recent conversation activity. Same
73
77
  // shape `gipity claude` uses for its picker-created projects.
74
78
  // When spawned inside a web-CLI-dispatched Claude Code turn, the relay
@@ -84,9 +88,6 @@ projectCommand
84
88
  if (isDispatch)
85
89
  body.origin = 'dispatch';
86
90
  }
87
- else {
88
- body.autoChat = 'gip';
89
- }
90
91
  const res = await post('/projects', body);
91
92
  const project = res.data;
92
93
  // Materialize a local dir and link it. We write `.gipity.json` directly
@@ -96,25 +97,15 @@ projectCommand
96
97
  const dir = join(getProjectsRoot(), project.slug);
97
98
  mkdirSync(dir, { recursive: true });
98
99
  const accountSlug = await getAccountSlug();
99
- // Resolve the first assigned agent (if any) - not fatal if missing.
100
- let agentGuid = '';
101
- try {
102
- const agents = await get(`/projects/${project.short_guid}/agents`);
103
- if (agents.data.length > 0)
104
- agentGuid = agents.data[0].short_guid;
105
- }
106
- catch {
107
- // offline or no agents - non-fatal
108
- }
109
100
  const { applied } = await finalizeLocalProject({
110
101
  dir,
111
102
  projectGuid: project.short_guid,
112
103
  projectSlug: project.slug,
113
104
  projectName: project.name,
114
105
  accountSlug,
115
- agentGuid,
116
106
  sync: 'soft',
117
107
  interactive: false,
108
+ json: !!opts.json,
118
109
  });
119
110
  if (opts.json) {
120
111
  console.log(JSON.stringify({
@@ -174,8 +165,68 @@ projectCommand
174
165
  console.log(`GUID: ${p.short_guid}`);
175
166
  console.log(`Live: ${liveUrl(config)}`);
176
167
  console.log(`Created: ${new Date(p.created_at).toLocaleDateString()}`);
168
+ console.log(`Sign-in: ${p.auth_mode}`);
177
169
  if (p.description)
178
170
  console.log(`Desc: ${p.description}`);
179
171
  }
180
172
  }));
173
+ projectCommand
174
+ .command('auth [mode]')
175
+ .description('Show or set who can sign in to the deployed app: gipity, app (Steam / guest players), or both')
176
+ .addHelpText('after', `
177
+ Modes:
178
+ gipity Sign in with Gipity only (default)
179
+ app Players sign in to this app alone, without a Gipity account:
180
+ Steam (POST /api/<guid>/auth/steam) or a guest device (POST /api/<guid>/auth/guest)
181
+ both Either
182
+
183
+ --unique-names on|off
184
+ On: no two players of this app can have the same display name (case and
185
+ lookalike letters ignored). A taken name is refused with DISPLAY_NAME_TAKEN;
186
+ GET /api/<guid>/auth/player/name-available?name=... checks one and suggests
187
+ free alternatives. Players who already share a name keep it, and sign in with
188
+ nameConflict: true until they rename. Off by default.
189
+
190
+ Steam also needs the Steamworks publisher key and AppID:
191
+ gipity secrets set STEAM_WEB_API_KEY <key>
192
+ gipity secrets set STEAM_APP_ID <appid>
193
+ See: gipity skill read steam-game`)
194
+ .option('--unique-names <on|off>', 'Require unique player display names in this app')
195
+ .option('--json', 'Output as JSON')
196
+ .action((mode, opts) => run('Auth', async () => {
197
+ const config = requireConfig();
198
+ const body = {};
199
+ if (mode !== undefined) {
200
+ if (!AUTH_MODES.includes(mode)) {
201
+ console.error(clrError(`Unknown mode "${mode}". Use one of: ${AUTH_MODES.join(', ')}.`));
202
+ process.exit(1);
203
+ }
204
+ body.auth_mode = mode;
205
+ }
206
+ if (opts.uniqueNames !== undefined) {
207
+ if (opts.uniqueNames !== 'on' && opts.uniqueNames !== 'off') {
208
+ console.error(clrError(`--unique-names takes "on" or "off", not "${opts.uniqueNames}".`));
209
+ process.exit(1);
210
+ }
211
+ body.unique_player_names = opts.uniqueNames === 'on';
212
+ }
213
+ if (Object.keys(body).length === 0) {
214
+ const res = await get(`/projects/${config.projectGuid}`);
215
+ const p = res.data;
216
+ printResult(`Sign-in: ${p.auth_mode}\nUnique names: ${p.unique_player_names ? 'on' : 'off'}`, opts, { auth_mode: p.auth_mode, unique_player_names: p.unique_player_names });
217
+ return;
218
+ }
219
+ const res = await put(`/projects/${config.projectGuid}`, body);
220
+ const lines = [];
221
+ if (body.auth_mode)
222
+ lines.push(success(`Sign-in set to "${body.auth_mode}".`));
223
+ if (body.unique_player_names !== undefined) {
224
+ lines.push(success(`Unique names ${body.unique_player_names ? 'on' : 'off'}.`));
225
+ const sharing = res.data.players_sharing_names ?? 0;
226
+ if (sharing > 0) {
227
+ lines.push(muted(`${sharing} existing player${sharing === 1 ? '' : 's'} share${sharing === 1 ? 's' : ''} a name with an earlier player. They keep it, and sign in with nameConflict: true until they rename.`));
228
+ }
229
+ }
230
+ printResult(lines.join('\n'), opts, { ...body, ...(res.data.players_sharing_names !== undefined ? { players_sharing_names: res.data.players_sharing_names } : {}) });
231
+ }));
181
232
  //# sourceMappingURL=project.js.map
@@ -1,7 +1,8 @@
1
1
  import { existsSync } from 'fs';
2
2
  import { dirname, resolve } from 'path';
3
+ import { fileURLToPath, pathToFileURL } from 'url';
3
4
  import { Command, Option } from 'commander';
4
- import { get, post, del } from '../api.js';
5
+ import { get, post, del, getBaseUrl } from '../api.js';
5
6
  import { requireConfig, getConfigPath } from '../config.js';
6
7
  import { error as clrError, success, muted, bold } from '../colors.js';
7
8
  import { run, printList } from '../helpers/index.js';
@@ -24,6 +25,10 @@ const roomCommand = new Command('room')
24
25
  .addOption(new Option('--type <type>', 'Room type for create').choices(['state', 'relay']).default('state'))
25
26
  .addOption(new Option('--auth <level>', 'Auth level for create').choices(['public', 'user']).default('public'))
26
27
  .option('--max-clients <n>', 'max clients for create (1-200)')
28
+ .option('--seat-hold <seconds>', 'create: how long a dropped client keeps its seat (0-300, default 30)')
29
+ .option('--host-hold <seconds>', 'create: how long the host role waits for a dropped or reloading host (0-600, default 60)')
30
+ .option('--host-handoff', 'create: move the host role to another player when the host is gone')
31
+ .option('--host-grace <seconds>', 'create: with handoff, how long the host may be unreachable before the role moves (1-60, default 5)')
27
32
  .option('--json', 'Output as JSON')
28
33
  .action((action, name, opts) => run('Realtime room', async () => {
29
34
  const config = requireConfig();
@@ -43,6 +48,14 @@ const roomCommand = new Command('room')
43
48
  const body = { name, room_type: opts.type, auth_level: opts.auth };
44
49
  if (opts.maxClients !== undefined)
45
50
  body.max_clients = Number(opts.maxClients);
51
+ if (opts.seatHold !== undefined)
52
+ body.seat_hold_seconds = Number(opts.seatHold);
53
+ if (opts.hostHold !== undefined)
54
+ body.host_hold_seconds = Number(opts.hostHold);
55
+ if (opts.hostHandoff)
56
+ body.host_handoff = true;
57
+ if (opts.hostGrace !== undefined)
58
+ body.host_grace_seconds = Number(opts.hostGrace);
46
59
  const res = await post(base, body);
47
60
  if (opts.json) {
48
61
  console.log(JSON.stringify(res.data));
@@ -93,7 +106,9 @@ const roomCommand = new Command('room')
93
106
  console.log(`Type: ${room.room_type}`);
94
107
  console.log(`Auth: ${room.auth_level}`);
95
108
  console.log(`Max clients: ${room.max_clients}`);
96
- console.log(`Live: ${live ? `${live.instances} instance(s), ${live.clients} client(s)` : muted('Colyseus server unreachable')}`);
109
+ console.log(`Seat hold: ${room.config?.seat_hold_seconds ?? 30}s (host ${room.config?.host_hold_seconds ?? 60}s)`);
110
+ console.log(`Handoff: ${room.config?.host_handoff ? `on, after ${room.config?.host_grace_seconds ?? 5}s` : 'off'}`);
111
+ console.log(`Live: ${live ? `${live.instances} instance(s), ${live.clients} client(s)` : muted('Gipity Realtime unreachable')}`);
97
112
  }
98
113
  break;
99
114
  }
@@ -103,7 +118,84 @@ const roomCommand = new Command('room')
103
118
  process.exit(1);
104
119
  }
105
120
  }));
121
+ /**
122
+ * dist/realtime-bench.js, found from wherever this code runs: inlined into the
123
+ * dist/index.js bundle, or as the unbundled dist/commands/realtime.js. Loaded
124
+ * by URL so esbuild leaves it out of the main bundle.
125
+ */
126
+ export function benchModulePath() {
127
+ const here = dirname(fileURLToPath(import.meta.url));
128
+ for (const candidate of [resolve(here, 'realtime-bench.js'), resolve(here, '..', 'realtime-bench.js')]) {
129
+ if (existsSync(candidate))
130
+ return pathToFileURL(candidate).href;
131
+ }
132
+ throw new Error('realtime-bench.js is missing from this CLI build; reinstall the gipity CLI');
133
+ }
134
+ const benchCommand = new Command('bench')
135
+ .description('Measure controller-to-host latency in a live room: 1 host + N simulated controllers')
136
+ .argument('<room>', 'a provisioned room of this project (joins a fresh scope, so real players are never disturbed)')
137
+ .option('--clients <n>', 'simulated controllers', '8')
138
+ .option('--rate <n>', 'inputs per second per controller', '20')
139
+ .option('--duration <seconds>', 'how long to send', '10')
140
+ .option('--latency <ms>', 'added one-way delay per input', '0')
141
+ .option('--jitter <ms>', 'random +/- extra delay per input', '0')
142
+ .option('--drop <fraction>', 'share of inputs never sent (0-1), to simulate loss', '0')
143
+ .option('--ws-url <url>', 'realtime endpoint', 'wss://rt.gipity.ai')
144
+ .option('--json', 'Output as JSON')
145
+ .addHelpText('after', `
146
+ Each controller syncs its clock with the server, then sends small inputs to the
147
+ host (the screen). The host measures each input's age on arrival: controller ->
148
+ Gipity Realtime -> host, end to end. Needs Node 22+ (built-in WebSocket).
149
+
150
+ Example: gipity realtime bench couch --clients 8 --rate 20 --latency 30 --jitter 15`)
151
+ .action((roomName, opts) => run('Realtime bench', async () => {
152
+ const config = requireConfig();
153
+ if (typeof globalThis.WebSocket !== 'function') {
154
+ console.error(clrError('gipity realtime bench needs Node 22 or newer (built-in WebSocket).'));
155
+ process.exit(1);
156
+ }
157
+ const info = await get(`/projects/${config.projectGuid}/realtime-rooms/${encodeURIComponent(roomName)}`);
158
+ const num = (v, name, min, max) => {
159
+ const n = Number(v);
160
+ if (!Number.isFinite(n) || n < min || n > max) {
161
+ console.error(clrError(`--${name} must be between ${min} and ${max}`));
162
+ process.exit(1);
163
+ }
164
+ return n;
165
+ };
166
+ const { runBench } = await import(benchModulePath());
167
+ const report = await runBench({
168
+ apiBase: getBaseUrl(),
169
+ wsUrl: opts.wsUrl,
170
+ appGuid: config.projectGuid,
171
+ room: roomName,
172
+ roomType: info.data.room.room_type === 'relay' ? 'relay' : 'state',
173
+ clients: num(opts.clients, 'clients', 1, 199),
174
+ rate: num(opts.rate, 'rate', 1, 100),
175
+ durationMs: num(opts.duration, 'duration', 1, 120) * 1000,
176
+ latencyMs: num(opts.latency, 'latency', 0, 5000),
177
+ jitterMs: num(opts.jitter, 'jitter', 0, 5000),
178
+ dropRate: num(opts.drop, 'drop', 0, 1),
179
+ onProgress: opts.json ? undefined : (line) => console.log(muted(line)),
180
+ });
181
+ if (opts.json) {
182
+ console.log(JSON.stringify(report));
183
+ return;
184
+ }
185
+ const fmt = (p) => p ? `p50 ${p.p50} p95 ${p.p95} p99 ${p.p99} max ${p.max} ms` : 'no samples';
186
+ console.log('');
187
+ console.log(bold(`${report.room}: ${report.controllers} controllers`));
188
+ console.log(`Input age (controller -> host): ${fmt(report.inputAgeMs)}`);
189
+ console.log(`Server -> host leg: ${fmt(report.serverToHostMs)}`);
190
+ console.log(`Round trip to the server: ${fmt(report.rttMs)}`);
191
+ console.log(`Delivered ${report.delivered}/${report.sent} sent`
192
+ + (report.simulatedDrops ? `, ${report.simulatedDrops} dropped by --drop` : '')
193
+ + `, lost ${report.lost}, out of order ${report.outOfOrder}`);
194
+ if (report.lost || report.outOfOrder)
195
+ process.exitCode = 1;
196
+ }));
106
197
  export const realtimeCommand = new Command('realtime')
107
- .description('Manage realtime (multiplayer) rooms')
108
- .addCommand(roomCommand);
198
+ .description('Manage realtime (multiplayer) rooms and measure their latency')
199
+ .addCommand(roomCommand)
200
+ .addCommand(benchCommand);
109
201
  //# sourceMappingURL=realtime.js.map
@@ -4,7 +4,6 @@ import { getAuth } from '../auth.js';
4
4
  import { requireConfig } from '../config.js';
5
5
  import { bold, muted } from '../colors.js';
6
6
  import { run, printList, printResult } from '../helpers/index.js';
7
- import { confirm } from '../utils.js';
8
7
  // All commands hit the app API (https://a.gipity.ai/api/<guid>/records/...),
9
8
  // which authorizes the logged-in owner via their Bearer token. (The native
10
9
  // Records API is the only records surface that exists server-side; there is no
@@ -180,6 +179,10 @@ recordsCommand
180
179
  // wiring, so `--purge` (the server's ?purge=1) is the one call that really
181
180
  // removes it. The plain success line says which of the two happened and names
182
181
  // the escape hatch, so nobody has to go spelunking through gipity.js to find it.
182
+ // No confirmation prompt: the call names exactly one row (table + id), the same
183
+ // precision as `records update`, which overwrites without asking. A prompt there
184
+ // only cost every headless cleanup a `--yes` retry (cli#192); prompts stay on the
185
+ // commands with a wide blast radius (a whole function, database or project).
183
186
  recordsCommand
184
187
  .command('delete <table> <id>')
185
188
  .description('Delete a record (soft-delete when the table declares one; --purge removes it for good)')
@@ -187,11 +190,6 @@ recordsCommand
187
190
  .option(ANON_FLAG, ANON_HELP)
188
191
  .option('--json', 'Output as JSON')
189
192
  .action((table, id, opts) => run('Delete', async () => {
190
- const what = opts.purge ? `Purge record ${id} from "${table}" (also erases its history)?` : `Delete record ${id} from "${table}"?`;
191
- if (!await confirm(what)) {
192
- printResult('Cancelled.', opts, { table, id, deleted: false, cancelled: true });
193
- return;
194
- }
195
193
  const api = await recordsHttp(opts);
196
194
  const res = await api.del(`/api/${api.guid}/records/${table}/${id}${opts.purge ? '?purge=1' : ''}`);
197
195
  const data = res?.data ?? { table, id, deleted: true, purged: !!opts.purge };