@giftsofprometheus/cli 0.5.1 → 0.6.1

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.
package/README.md CHANGED
@@ -109,7 +109,7 @@ npx skills add timurkhakhalev/giftsofprometheus-cli
109
109
 
110
110
  ## Команды
111
111
 
112
- С флагом `--json` любая команда печатает компактный JSON. Ошибка тогда выглядит как `{"error":{"message","status"}}`, а код выхода — 1.
112
+ С флагом `--json` любая команда печатает компактный JSON. Ошибка тогда выглядит как `{"error":{"message","status","code","nextStep"}}`, а код выхода — 1: `code` и `nextStep` приходят от сервиса, когда он их знает. После обрыва соединения или ответа 502, 503 или 504 от прокси CLI сам повторяет запрос два раза.
113
113
 
114
114
  | Команда | Что делает | Аккаунт |
115
115
  |---|---|---|
package/dist/index.js CHANGED
@@ -46,11 +46,16 @@ async function stored() {
46
46
  const value = await storedAny();
47
47
  return value !== 'unreadable' && value?.base === base ? value : null;
48
48
  }
49
+ /** `code` and `nextStep` come from the service: the code is stable, the next step says what to do about it */
49
50
  class ApiError extends Error {
50
51
  status;
51
- constructor(message, status = 1) {
52
+ code;
53
+ nextStep;
54
+ constructor(message, status = 1, code, nextStep) {
52
55
  super(message);
53
56
  this.status = status;
57
+ this.code = code;
58
+ this.nextStep = nextStep;
54
59
  }
55
60
  }
56
61
  // Server text reaches a terminal: remove control characters so a response cannot inject ANSI or OSC escape sequences
@@ -96,21 +101,48 @@ async function request(path, method = 'GET', body, authenticated = true) {
96
101
  const headers = new Headers({ 'Content-Type': 'application/json', 'X-Knowledge-Client': 'agent', 'User-Agent': `giftsofprometheus/${version}` });
97
102
  if (credential)
98
103
  headers.set('Authorization', `Bearer ${credential.token}`);
99
- const response = await fetch(target, {
100
- method,
101
- headers,
102
- redirect: 'error',
103
- signal: AbortSignal.timeout(30_000),
104
- ...(body === undefined ? {} : { body: JSON.stringify(body) }),
105
- });
106
- const data = await response.json().catch(() => ({}));
107
- if (!response.ok) {
108
- const failure = z.object({ error_description: z.string().optional(), error: z.string().optional() }).safeParse(data);
104
+ for (let attempt = 1;; attempt++) {
105
+ let response;
106
+ try {
107
+ response = await fetch(target, {
108
+ method,
109
+ headers,
110
+ redirect: 'error',
111
+ signal: AbortSignal.timeout(30_000),
112
+ ...(body === undefined ? {} : { body: JSON.stringify(body) }),
113
+ });
114
+ }
115
+ catch (e) {
116
+ // A refused or reset connection never reached the service, so any method may repeat. A timeout may have, so it does not
117
+ if (attempt < RETRY_DELAYS_MS.length + 1 && !(e instanceof Error && e.name === 'TimeoutError')) {
118
+ await sleep(RETRY_DELAYS_MS[attempt - 1]);
119
+ continue;
120
+ }
121
+ throw new ApiError(`The service is unreachable: ${e instanceof Error ? e.message : 'network error'}. Try again in a minute.`);
122
+ }
123
+ const data = await response.json().catch(() => ({}));
124
+ if (response.ok)
125
+ return data;
126
+ const failure = z
127
+ .object({ error_description: z.string().optional(), error: z.string().optional(), code: z.string().optional(), nextStep: z.string().optional() })
128
+ .safeParse(data);
129
+ const code = failure.success ? failure.data.code : undefined;
130
+ // 502-504 without a service error code come from the proxy in front of the service: a restart or a dropped connection
131
+ if (GATEWAY_STATUSES.has(response.status) && code === undefined) {
132
+ if (attempt < RETRY_DELAYS_MS.length + 1) {
133
+ await sleep(RETRY_DELAYS_MS[attempt - 1]);
134
+ continue;
135
+ }
136
+ throw new ApiError(`The service is temporarily unavailable (HTTP ${response.status}). Try again in a minute.`, response.status);
137
+ }
109
138
  const message = failure.success ? failure.data.error_description || failure.data.error || `HTTP ${response.status}` : `HTTP ${response.status}`;
110
- throw new ApiError(printable(message).slice(0, 500), response.status);
139
+ const nextStep = failure.success && failure.data.nextStep ? printable(failure.data.nextStep).slice(0, 500) : undefined;
140
+ throw new ApiError(printable(message).slice(0, 500), response.status, code === undefined ? undefined : printable(code).slice(0, 100), nextStep);
111
141
  }
112
- return data;
113
142
  }
143
+ // Two repeats after a gateway error or a connection failure: a deploy switch or a dropped keep-alive connection passes in seconds
144
+ const RETRY_DELAYS_MS = [500, 1500];
145
+ const GATEWAY_STATUSES = new Set([502, 503, 504]);
114
146
  function out(value) {
115
147
  console.log(JSON.stringify(value, null, program.opts().json ? 0 : 2));
116
148
  }
@@ -136,10 +168,16 @@ function run(fn) {
136
168
  catch (e) {
137
169
  const message = e instanceof Error ? e.message : 'Unknown error';
138
170
  const status = e instanceof ApiError ? e.status : 1;
171
+ const code = e instanceof ApiError ? e.code : undefined;
172
+ // On 401 the CLI's own steps win: they say how to sign in from an agent, which the service cannot know
173
+ const nextStep = status === 401 ? SIGN_IN_STEPS : e instanceof ApiError ? e.nextStep : undefined;
139
174
  if (program.opts().json)
140
- console.log(JSON.stringify({ error: { message, status, ...(status === 401 ? { nextStep: SIGN_IN_STEPS } : {}) } }));
141
- else
175
+ console.log(JSON.stringify({ error: { message, status, ...(code ? { code } : {}), ...(nextStep ? { nextStep } : {}) } }));
176
+ else {
142
177
  console.error(printable(message));
178
+ if (nextStep)
179
+ console.error(`Next: ${printable(nextStep)}`);
180
+ }
143
181
  process.exitCode = 1;
144
182
  }
145
183
  };
@@ -488,7 +526,12 @@ talks
488
526
  .command('search')
489
527
  .argument('<query>')
490
528
  .option('--page <page>', 'page number', '1')
491
- .action(run((query, options) => request(`/api/knowledge/talks?q=${encodeURIComponent(query)}&page=${encodeURIComponent(options.page)}`)));
529
+ .action(run((query, options) => {
530
+ // The service answers an empty query with the whole catalog, which an agent would take for search results
531
+ if (!query.trim())
532
+ throw new ApiError('Empty search query. To browse the catalog, use: giftsofprometheus talks list');
533
+ return request(`/api/knowledge/talks?q=${encodeURIComponent(query)}&page=${encodeURIComponent(options.page)}`);
534
+ }));
492
535
  // The command a person typed, so a hint can be pasted back as is
493
536
  const launcher = /[\\/]_npx[\\/]/.test(packageRoot) ? 'npx @giftsofprometheus/cli' : 'giftsofprometheus';
494
537
  talks
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@giftsofprometheus/cli",
3
- "version": "0.5.1",
3
+ "version": "0.6.1",
4
4
  "description": "Search AI conference talks, read transcripts, and manage your Gifts of Prometheus favorites from the shell or an AI agent",
5
5
  "keywords": [
6
6
  "agents",
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  name: giftsofprometheus
3
3
  description: Find AI conference talks (AI Engineer, BAAI, Apsara and others) with Russian summaries, read their full transcripts, and manage the signed-in user's favorites, interests and personal feed through the giftsofprometheus CLI, and build a starting profile in the chat. Use when the user asks for talks, speakers or transcripts on an AI engineering topic, or wants to save, list or remove favorites on Gifts of Prometheus.
4
- allowed-tools: Bash(giftsofprometheus:*), Bash(npx -y @giftsofprometheus/cli:*)
4
+ allowed-tools: Bash(giftsofprometheus:*), Bash(npx -y @giftsofprometheus/cli:*), Bash(pnpm dlx @giftsofprometheus/cli:*), Bash(bunx @giftsofprometheus/cli:*)
5
5
  ---
6
6
 
7
7
  # Gifts of Prometheus
@@ -10,7 +10,11 @@ allowed-tools: Bash(giftsofprometheus:*), Bash(npx -y @giftsofprometheus/cli:*)
10
10
 
11
11
  ## Setup
12
12
 
13
- Run `command -v giftsofprometheus`. If it is missing, run every command below as `npx -y @giftsofprometheus/cli` with the same arguments instead of `giftsofprometheus`, and mention once that a permanent install is described in https://github.com/timurkhakhalev/giftsofprometheus-cli#install. Then run `giftsofprometheus --json doctor`:
13
+ Run `command -v giftsofprometheus`. If it is missing, run every command below as `npx -y @giftsofprometheus/cli` with the same arguments instead of `giftsofprometheus`, and mention once that a permanent install is described in https://github.com/timurkhakhalev/giftsofprometheus-cli#install. If `npx` is missing or disabled, use `pnpm dlx @giftsofprometheus/cli` or `bunx @giftsofprometheus/cli`. If none of them runs, ask the user to install the CLI and stop.
14
+
15
+ Use only the CLI. Do not call the site's API with `curl`, `fetch` or a script, even for public data: the service refuses any client other than the site and the CLI with `cli_required`, and its rules on `recId`, sign-in and feedback live in the CLI and this skill. For a path that no command covers, use `request` (see Read).
16
+
17
+ Then run `giftsofprometheus --json doctor`:
14
18
 
15
19
  - `reachable: false`: the service is unavailable; report it and stop.
16
20
  - `authenticated: false`: search, talk metadata and onboarding still work. Sign in only when a command needs it (see Sign in).
@@ -43,7 +47,7 @@ giftsofprometheus --json profile get # interests and curre
43
47
 
44
48
  - For questions about what speakers say, use `ask` with 2–3 formulations: English, Chinese and the original language. For names, titles, topics and conferences use `talks search`.
45
49
  - Open a found transcript with `talks content <slug> --rec-id <recId>` from the `ask` response. Summarize positions of different speakers and give the passage `url` links with timecodes.
46
- - If `ask` returns 503, try later or use `talks search`.
50
+ - If `ask` fails with code `passages_unavailable`, use `talks search`.
47
51
  - Lists are paginated: check `totalPages` and pass `--page`.
48
52
  - Search and use the returned `slug` or `id` for exact reads.
49
53
  - A transcript is in the talk's original language. Segment timecodes are in milliseconds from the start of the talk. When a talk is a part of a longer recording, `sourceRange` gives its bounds in that recording. A talk without a transcript returns an empty array.
@@ -112,4 +116,6 @@ giftsofprometheus --json profile update --interest agents=high --remove-interest
112
116
 
113
117
  ## Errors
114
118
 
115
- With `--json` a failure prints `{"error":{"message","status"}}` and exits with code 1. Status 401 means the session is missing, expired or revoked: sign in as described in Sign in and repeat the command.
119
+ With `--json` a failure prints `{"error":{"message","status","code","nextStep"}}` and exits with code 1. `code` and `nextStep` are present when the service sent them: decide by `code` (for example `talk_not_found`, `unknown_recommendation`, `rate_limited`), follow `nextStep`, and show `message` to the user as it is. Status 401 means the session is missing, expired or revoked: sign in as described in Sign in and repeat the command. Code `cli_required` means the request did not come from the CLI: run the command through the CLI as described in Setup.
120
+
121
+ The CLI repeats a request twice by itself after a connection failure or a 502, 503 or 504 from the proxy. If it still fails with "The service is temporarily unavailable" or "The service is unreachable", tell the user in one line, wait a minute and try once more before you stop.
@@ -53,5 +53,15 @@
53
53
  "version": "0.5.1",
54
54
  "hash": "a5decd76f9054068",
55
55
  "description": "description: Find AI conference talks (AI Engineer, BAAI, Apsara and others) with Russian summaries, read their full transcripts, and manage the signed-in user's favorites, interests and personal feed through the giftsofprometheus CLI, and build a starting profile in the chat. Use when the user asks for talks, speakers or transcripts on an AI engineering topic, or wants to save, list or remove favorites on Gifts of Prometheus."
56
+ },
57
+ {
58
+ "version": "0.6.0",
59
+ "hash": "04c1f4fd0b948e24",
60
+ "description": "description: Find AI conference talks (AI Engineer, BAAI, Apsara and others) with Russian summaries, read their full transcripts, and manage the signed-in user's favorites, interests and personal feed through the giftsofprometheus CLI, and build a starting profile in the chat. Use when the user asks for talks, speakers or transcripts on an AI engineering topic, or wants to save, list or remove favorites on Gifts of Prometheus."
61
+ },
62
+ {
63
+ "version": "0.6.1",
64
+ "hash": "fd663594e9d37fd3",
65
+ "description": "description: Find AI conference talks (AI Engineer, BAAI, Apsara and others) with Russian summaries, read their full transcripts, and manage the signed-in user's favorites, interests and personal feed through the giftsofprometheus CLI, and build a starting profile in the chat. Use when the user asks for talks, speakers or transcripts on an AI engineering topic, or wants to save, list or remove favorites on Gifts of Prometheus."
56
66
  }
57
67
  ]