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
@@ -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 };
@@ -432,7 +432,7 @@ GCC/Rust).
432
432
  console.error(clrError(`Scratch files are never mirrored into the sandbox, so it can't read: ${scratchReads.join(', ')}`));
433
433
  console.error(dim(` ${SCRATCH_IGNORE.join(', ')} are ignored by sync, so the sandbox never sees them.`));
434
434
  console.error(dim(' Stage the input at a real project path (src/, docs/, assets/) and delete it afterward.'));
435
- console.error(dim(' (Writing OUTPUT under tmp/ is fine — scratch outputs come back to your local tmp/.)'));
435
+ console.error(dim(' (Writing OUTPUT under tmp/ is fine: scratch outputs come back to your local tmp/.)'));
436
436
  process.exit(1);
437
437
  }
438
438
  }
@@ -468,8 +468,7 @@ GCC/Rust).
468
468
  // Pull sandbox-written outputs down to the local cwd automatically. The
469
469
  // server has already mirrored them into the project (VFS) and handed back
470
470
  // the exact list, so honoring it here means files land locally without a
471
- // manual `gipity sync` - same auto-pull contract `gipity chat` uses on its
472
- // `filesChanged` flag. Skip in one-off mode (no local project to sync into).
471
+ // manual `gipity sync`. Skip in one-off mode (no local project to sync into).
473
472
  const pulledLocal = !!(res.data.outputFiles?.length && getConfigPath());
474
473
  if (pulledLocal) {
475
474
  await sync({ interactive: false, progress: opts.json ? undefined : createProgressReporter() });
@@ -2,7 +2,7 @@ import { Command } from 'commander';
2
2
  import { existsSync, readFileSync } from 'fs';
3
3
  import { join } from 'path';
4
4
  import { get } from '../api.js';
5
- import { resolveProjectContext, getProjectRoot } from '../config.js';
5
+ import { getProjectRoot } from '../config.js';
6
6
  import { error as clrError, bold, muted } from '../colors.js';
7
7
  import { run, printList } from '../helpers/index.js';
8
8
  /** Many kits ship a README but no skill doc. When `skill read <name>` misses
@@ -72,18 +72,53 @@ function tocText(sections) {
72
72
  .map(s => `${String(s.start).padStart(5)} ${' '.repeat(s.level - 1)}${s.slug}${muted(` - ${s.title}`)}`)
73
73
  .join('\n');
74
74
  }
75
- /** Apply --toc / --section / --grep to a doc. Returns the text to print, or
76
- * null when the filter matched nothing (caller reports it and exits 1). */
75
+ // Words that carry no meaning in a guessed slug (`functions-in-gipity-yaml`).
76
+ const SLUG_STOPWORDS = new Set(['a', 'an', 'and', 'the', 'in', 'of', 'on', 'to', 'for', 'with', 'via', 'how', 'from', 'your']);
77
+ function slugWords(slug) {
78
+ return slug.split('-').filter(w => w && !SLUG_STOPWORDS.has(w)).map(w => w.replace(/s$/, ''));
79
+ }
80
+ /** The section a guessed slug most plausibly means: the one sharing the most
81
+ * meaningful words with it (plural-insensitive, any order), provided it shares
82
+ * at least half of them and no other section ties. Slugs are only advertised
83
+ * by a full read or --toc, so an agent targeting a doc it hasn't read guesses
84
+ * (`functions-in-gipity-yaml` for `gipity-yaml-function-permissions`); serving
85
+ * the clear winner, labelled as such, saves the guess-and-correct turn. */
86
+ function closestSection(sections, want) {
87
+ const words = [...new Set(slugWords(want))];
88
+ if (words.length === 0)
89
+ return null;
90
+ const scored = sections.map(s => {
91
+ const have = new Set(slugWords(s.slug));
92
+ return { s, score: words.filter(w => have.has(w)).length };
93
+ }).sort((a, b) => b.score - a.score);
94
+ const [best, second] = scored;
95
+ if (!best || best.score * 2 < words.length || best.score === 0)
96
+ return null;
97
+ if (second && second.score === best.score)
98
+ return null;
99
+ return best.s;
100
+ }
101
+ /** Apply --toc / --section / --grep to a doc. Returns the text to print (plus a
102
+ * note when --section resolved to a closest match rather than the exact slug),
103
+ * or null when the filter matched nothing (caller reports it and exits 1). */
77
104
  function filterContent(content, sections, opts) {
78
105
  const lines = content.split('\n');
79
106
  if (opts.toc)
80
- return tocText(sections);
107
+ return { text: tocText(sections) };
81
108
  let hits = [];
109
+ let note;
82
110
  if (opts.section) {
83
111
  const want = slugify(opts.section);
84
112
  hits = sections.filter(s => s.slug === want);
85
113
  if (hits.length === 0)
86
114
  hits = sections.filter(s => s.slug.includes(want));
115
+ if (hits.length === 0) {
116
+ const closest = closestSection(sections, want);
117
+ if (closest) {
118
+ hits = [closest];
119
+ note = `No section "${opts.section}"; showing the closest match "${closest.slug}" (all slugs: --toc).`;
120
+ }
121
+ }
87
122
  }
88
123
  else if (opts.grep) {
89
124
  let re;
@@ -107,13 +142,13 @@ function filterContent(content, sections, opts) {
107
142
  hits = sections.filter(s => matched.has(s));
108
143
  }
109
144
  else {
110
- return content;
145
+ return { text: content };
111
146
  }
112
147
  if (hits.length === 0)
113
148
  return null;
114
149
  // Drop sections already contained in an outer hit so nothing prints twice.
115
150
  const outer = hits.filter(s => !hits.some(o => o !== s && o.start <= s.start && s.end <= o.end));
116
- return outer.map(s => sectionText(lines, s)).join('\n\n');
151
+ return { text: outer.map(s => sectionText(lines, s)).join('\n\n'), note };
117
152
  }
118
153
  export const skillCommand = new Command('skill')
119
154
  .description('Task docs - read the matching skill before building');
@@ -122,12 +157,7 @@ skillCommand
122
157
  .description('List skills')
123
158
  .option('--json', 'Output as JSON')
124
159
  .action((opts) => run('List', async () => {
125
- const { config } = await resolveProjectContext();
126
- if (!config.agentGuid) {
127
- console.error(clrError('No agent configured for this project. Run `gipity init` to refresh.'));
128
- process.exit(1);
129
- }
130
- const res = await get(`/skills?agent=${config.agentGuid}`);
160
+ const res = await get('/skills');
131
161
  const width = res.data.reduce((m, s) => Math.max(m, s.name.length), 0);
132
162
  printList(res.data, opts, 'No skills available.', s => ` ${bold(s.name.padEnd(width))} ${muted(s.description)}`, 'Read with `gipity skill read <name> [<name>...]` (one turn, many docs; `--toc`, `--section <slug>` or `--grep <term>` for one part):');
133
163
  }));
@@ -135,16 +165,11 @@ skillCommand
135
165
  .command('read <names...>')
136
166
  .description('Read one or more skills (whole doc, or one part with --toc/--section/--grep)')
137
167
  .option('--toc', 'Print the doc outline (section slugs + line numbers) instead of the content')
138
- .option('--section <slug>', 'Print only this section (slug or heading text; subsections included)')
168
+ .option('--section <slug>', 'Print only this section (slug or heading text; subsections included). A guess that clearly matches one section by its words prints that section')
139
169
  .option('--grep <term>', 'Print only the sections matching this term (case-insensitive regex)')
140
170
  .option('--json', 'Output as JSON')
141
171
  .action((names, opts) => run('Read', async () => {
142
- const { config } = await resolveProjectContext();
143
- if (!config.agentGuid) {
144
- console.error(clrError('No agent configured for this project. Run `gipity init` to refresh.'));
145
- process.exit(1);
146
- }
147
- const listRes = await get(`/skills?agent=${config.agentGuid}`);
172
+ const listRes = await get('/skills');
148
173
  const jsonDocs = [];
149
174
  let failed = false;
150
175
  let printed = 0;
@@ -154,7 +179,7 @@ skillCommand
154
179
  let detail;
155
180
  let note = null;
156
181
  if (match) {
157
- const res = await get(`/skills/${match.guid}?agent=${config.agentGuid}`);
182
+ const res = await get(`/skills/${match.guid}`);
158
183
  content = res.data.content;
159
184
  detail = { ...res.data };
160
185
  }
@@ -183,7 +208,8 @@ skillCommand
183
208
  if (opts.json) {
184
209
  jsonDocs.push({
185
210
  ...detail,
186
- content: filtered,
211
+ content: filtered.text,
212
+ ...(filtered.note ? { note: filtered.note } : {}),
187
213
  lines: lines.length,
188
214
  sections: sections.map(s => ({ slug: s.slug, title: s.title, level: s.level, line: s.start })),
189
215
  });
@@ -194,7 +220,9 @@ skillCommand
194
220
  if (note)
195
221
  console.log(note);
196
222
  console.log(mapLine(name, lines, sections));
197
- console.log(filtered);
223
+ if (filtered.note)
224
+ console.log(muted(filtered.note));
225
+ console.log(filtered.text);
198
226
  printed++;
199
227
  }
200
228
  if (opts.json) {
@@ -122,36 +122,34 @@ export const statusCommand = new Command('status')
122
122
  // --api-base, or a disallowed host being dropped to the default). Surface
123
123
  // the divergence rather than silently trusting the recorded value.
124
124
  if (apiBaseInUse !== config.apiBase) {
125
- console.log(`${muted('API (in use):')} ${warning(apiBaseInUse)} ${muted('(overrides .gipity.json — GIPITY_API_BASE / --api-base / allowlist)')}`);
125
+ console.log(`${muted('API (in use):')} ${warning(apiBaseInUse)} ${muted('(overrides .gipity.json: GIPITY_API_BASE / --api-base / allowlist)')}`);
126
126
  }
127
- if (config.agentGuid)
128
- console.log(`${muted('Agent:')} ${config.agentGuid}`);
129
127
  }
130
128
  if (usingEnvToken()) {
131
129
  console.log(`${muted('Auth:')} ${probe.state === 'rejected'
132
- ? warning('agent API token (GIPITY_TOKEN) rejected by the server — mint a new one: gipity skill read agent-deploy')
133
- : success('agent API token (GIPITY_TOKEN)')}${probe.state === 'unreachable' ? ` ${muted('(unverified — API unreachable)')}` : ''}`);
130
+ ? warning('agent API token (GIPITY_TOKEN) rejected by the server. Mint a new one: gipity skill read agent-deploy')
131
+ : success('agent API token (GIPITY_TOKEN)')}${probe.state === 'unreachable' ? ` ${muted('(unverified: API unreachable)')}` : ''}`);
134
132
  }
135
133
  else if (!auth) {
136
134
  console.log(`${muted('Auth:')} ${warning('not logged in. Run: gipity login')}`);
137
135
  }
138
136
  else if (probe.state === 'expired') {
139
- console.log(`${muted('Auth:')} ${warning(`session expired for ${auth.email}. Run: gipity login (headless/CI: set GIPITY_TOKEN — gipity skill read agent-deploy)`)}`);
137
+ console.log(`${muted('Auth:')} ${warning(`session expired for ${auth.email}. Run: gipity login (headless/CI: set GIPITY_TOKEN, see gipity skill read agent-deploy)`)}`);
140
138
  }
141
139
  else if (probe.state === 'rejected') {
142
140
  // Locally fresh but the server says no (refresh token rotated away or
143
141
  // revoked). Without the live probe this printed a green identity while
144
142
  // every authenticated command failed.
145
- console.log(`${muted('Auth:')} ${warning(`session for ${auth.email} was rejected by the server. Run: gipity login (headless/CI: set GIPITY_TOKEN — gipity skill read agent-deploy)`)}`);
143
+ console.log(`${muted('Auth:')} ${warning(`session for ${auth.email} was rejected by the server. Run: gipity login (headless/CI: set GIPITY_TOKEN, see gipity skill read agent-deploy)`)}`);
146
144
  }
147
145
  else {
148
- console.log(`${muted('Auth:')} ${success(auth.email)}${probe.state === 'unreachable' ? ` ${muted('(unverified — API unreachable)')}` : ''}`);
146
+ console.log(`${muted('Auth:')} ${success(auth.email)}${probe.state === 'unreachable' ? ` ${muted('(unverified: API unreachable)')}` : ''}`);
149
147
  }
150
148
  // Source-independent (session or GIPITY_TOKEN): a mismatch under an agent
151
149
  // token is the same wrong-account class and must not be hidden inside the
152
150
  // cascade above, which only special-cases 'rejected' for that source.
153
151
  if (accountMismatch) {
154
- console.log(`${muted('Account:')} ${warning(`logged-in account (${probe.account}) differs from this project's account (${config.accountSlug}). If you didn't expect this you may be logged into the wrong account — run: gipity login`)}`);
152
+ console.log(`${muted('Account:')} ${warning(`logged-in account (${probe.account}) differs from this project's account (${config.accountSlug}). If you didn't expect this you may be logged into the wrong account. Run: gipity login`)}`);
155
153
  console.log(muted('(If this project was shared with you via gipity rbac, this is expected.)'));
156
154
  }
157
155
  if (queueDelivered > 0) {
@@ -276,7 +276,7 @@ export const testCommand = new Command('test')
276
276
  testCommand
277
277
  .command('status')
278
278
  .alias('results')
279
- .description('Fetch a finished (or running) test run by GUID — full per-test results, no re-run')
279
+ .description('Fetch a finished (or running) test run by GUID: full per-test results, no re-run')
280
280
  .argument('<runGuid>', 'Test run GUID (e.g. tr_abc123)')
281
281
  .option('--json', 'Output as JSON')
282
282
  .option('--follow', 'Follow until complete (poll)')
@@ -320,7 +320,7 @@ testCommand
320
320
  // ── List subcommand (show test files without running) ─────────────────
321
321
  testCommand
322
322
  .command('list')
323
- .description('List the test files that would run — no run, optional path filter')
323
+ .description('List the test files that would run: no run, optional path filter')
324
324
  .argument('[path]', 'Test path filter (e.g. "api", "e2e/portal")')
325
325
  .option('--json', 'Output as JSON')
326
326
  // optsWithGlobals: see the status subcommand — `--json` lands on the parent.
@@ -28,7 +28,7 @@ tokenCommand
28
28
  body.expiresInDays = days;
29
29
  }
30
30
  const res = await post('/auth/agent-tokens', body);
31
- const { token, shortGuid, expiresAt } = res.data;
31
+ const { token, short_guid: shortGuid, expires_at: expiresAt } = res.data;
32
32
  if (opts.json) {
33
33
  console.log(JSON.stringify(res.data));
34
34
  return;
@@ -38,10 +38,10 @@ tokenCommand
38
38
  console.log('');
39
39
  console.log(token);
40
40
  console.log('');
41
- console.log(muted('Use it from an agent, script, or CI — no login needed:'));
41
+ console.log(muted('Use it from an agent, script, or CI (no login needed):'));
42
42
  console.log(` export GIPITY_TOKEN=${token}`);
43
43
  console.log('');
44
- console.log(warning('Copy it now — it will not be shown again.'));
44
+ console.log(warning('Copy it now. It will not be shown again.'));
45
45
  }));
46
46
  tokenCommand
47
47
  .command('list')
@@ -63,7 +63,7 @@ tokenCommand
63
63
  .action((shortGuid, opts) => run('Revoke', async () => {
64
64
  await del(`/auth/agent-tokens/${encodeURIComponent(shortGuid)}`);
65
65
  if (opts.json) {
66
- console.log(JSON.stringify({ shortGuid, revoked: true }));
66
+ console.log(JSON.stringify({ short_guid: shortGuid, revoked: true }));
67
67
  return;
68
68
  }
69
69
  console.log(success(`Revoked token ${bold(shortGuid)}.`));