@dypt/cli 0.1.17 → 0.1.18

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
@@ -173,6 +173,51 @@ dypt task list --limit 10 --json
173
173
  dypt task get 123 --json
174
174
  ```
175
175
 
176
+ ### Maintenance responses
177
+
178
+ If dypt is in maintenance mode, API-backed commands stop after the first `503`
179
+ response and exit with code `75` (`EX_TEMPFAIL`). Mutations are never retried
180
+ automatically. Human output explains that no change was applied and includes
181
+ the server's `Retry-After` guidance when available.
182
+
183
+ The canonical server response combines HTTP `503`,
184
+ `X-Dypt-Maintenance: true`, `Retry-After`, and the stable
185
+ `DYPT_MAINTENANCE` response code. The CLI also normalizes an accidental HTML
186
+ `503` from a break-glass rewrite instead of reporting a JSON parse failure.
187
+
188
+ Commands invoked with `--json` write this stable retryable classification to
189
+ standard error and also exit `75`:
190
+
191
+ ```json
192
+ {
193
+ "error": {
194
+ "code": "DYPT_MAINTENANCE",
195
+ "message": "dypt is temporarily under maintenance.",
196
+ "retryable": true,
197
+ "retryAfter": "120",
198
+ "retryAfterSeconds": 120,
199
+ "noChangeApplied": true
200
+ }
201
+ }
202
+ ```
203
+
204
+ Agents may retry after the indicated delay. They should not revoke credentials,
205
+ start a new login flow, or assume that an interrupted mutation was applied.
206
+
207
+ ### Read-query throttling
208
+
209
+ Authenticated reads use an account-level weighted budget that is shared across
210
+ all CLI tokens. Normal pagination and agent inspection workflows fit within the
211
+ budget, while sustained task list, tree, search, summary, and planning traffic
212
+ consumes it faster than bounded point reads.
213
+
214
+ When the server returns `CLI_READ_RATE_LIMITED`, wait at least the reported
215
+ `retryAfterSeconds`, add backoff or jitter, and continue from the last cursor.
216
+ Rotating credentials does not increase capacity. The CLI exits with temporary
217
+ failure code `75`; `--json` emits a stable retryable error object. Read
218
+ throttling is independent of mutation throttling and per-request filter/input
219
+ bounds.
220
+
176
221
  ## Agent guidance
177
222
 
178
223
  Install or inspect dypt agent guidance for supported AI coding tools:
package/dist/index.js CHANGED
@@ -9,7 +9,7 @@ import { Argument, Command, Option } from "commander";
9
9
  // package.json
10
10
  var package_default = {
11
11
  name: "@dypt/cli",
12
- version: "0.1.17",
12
+ version: "0.1.18",
13
13
  description: "Command-line interface for dypt task management",
14
14
  license: "SEE LICENSE IN LICENSE",
15
15
  homepage: "https://dypt.app",
@@ -242,6 +242,156 @@ async function clearCliToken(baseUrl = getBaseUrl(), filePath = getScopedTokenFi
242
242
  // src/lib/trpc.ts
243
243
  import { createTRPCProxyClient, httpBatchLink } from "@trpc/client";
244
244
  import superjson from "superjson";
245
+
246
+ // src/lib/maintenance.ts
247
+ var DYPT_MAINTENANCE_CODE = "DYPT_MAINTENANCE";
248
+ var DYPT_MAINTENANCE_EXIT_CODE = 75;
249
+ var MAINTENANCE_HEADER = "x-dypt-maintenance";
250
+ var DyptMaintenanceError = class extends Error {
251
+ constructor(retryAfter, retryAfterSeconds) {
252
+ super("dypt is temporarily under maintenance.");
253
+ this.retryAfter = retryAfter;
254
+ this.retryAfterSeconds = retryAfterSeconds;
255
+ this.code = DYPT_MAINTENANCE_CODE;
256
+ this.retryable = true;
257
+ this.noChangeApplied = true;
258
+ this.name = "DyptMaintenanceError";
259
+ }
260
+ };
261
+ function parseRetryAfterSeconds(value) {
262
+ if (value === null) return null;
263
+ const seconds = Number(value);
264
+ if (Number.isInteger(seconds) && seconds >= 0) return seconds;
265
+ const timestamp = Date.parse(value);
266
+ if (Number.isNaN(timestamp)) return null;
267
+ return Math.max(0, Math.ceil((timestamp - Date.now()) / 1e3));
268
+ }
269
+ async function hasMaintenanceCode(response) {
270
+ const contentType = response.headers.get("content-type") ?? "";
271
+ if (!contentType.toLowerCase().includes("json")) return false;
272
+ try {
273
+ const body = await response.clone().json();
274
+ return body.code === DYPT_MAINTENANCE_CODE || typeof body.error === "object" && body.error?.code === DYPT_MAINTENANCE_CODE;
275
+ } catch {
276
+ return false;
277
+ }
278
+ }
279
+ async function getMaintenanceError(response) {
280
+ if (response.status !== 503) return null;
281
+ const hasHeader = response.headers.get(MAINTENANCE_HEADER)?.toLowerCase() === "true";
282
+ const hasCode = await hasMaintenanceCode(response);
283
+ const isHtml = (response.headers.get("content-type") ?? "").toLowerCase().includes("text/html");
284
+ if (!hasHeader && !hasCode && !isHtml) return null;
285
+ const retryAfter = response.headers.get("retry-after");
286
+ return new DyptMaintenanceError(
287
+ retryAfter,
288
+ parseRetryAfterSeconds(retryAfter)
289
+ );
290
+ }
291
+ async function fetchWithMaintenanceCheck(input, init) {
292
+ const response = await globalThis.fetch(input, init);
293
+ const maintenanceError = await getMaintenanceError(response);
294
+ if (maintenanceError) throw maintenanceError;
295
+ return response;
296
+ }
297
+ function findCliReadRateLimitError(error) {
298
+ const seen = /* @__PURE__ */ new Set();
299
+ const pending = [error];
300
+ while (pending.length > 0) {
301
+ const current = pending.shift();
302
+ if (!current || seen.has(current) || typeof current !== "object") continue;
303
+ seen.add(current);
304
+ const candidate = current;
305
+ if (candidate.code === "CLI_READ_RATE_LIMITED" && candidate.retryable === true && typeof candidate.retryAfterSeconds === "number") {
306
+ return candidate;
307
+ }
308
+ pending.push(
309
+ candidate.cause,
310
+ candidate.data,
311
+ candidate.shape,
312
+ candidate.cliError
313
+ );
314
+ }
315
+ return null;
316
+ }
317
+ function findMaintenanceError(error) {
318
+ const seen = /* @__PURE__ */ new Set();
319
+ let current = error;
320
+ while (current && !seen.has(current)) {
321
+ seen.add(current);
322
+ if (current instanceof DyptMaintenanceError) return current;
323
+ if (typeof current !== "object") return null;
324
+ const candidate = current;
325
+ if (candidate.code === DYPT_MAINTENANCE_CODE && candidate.retryable === true) {
326
+ return new DyptMaintenanceError(
327
+ typeof candidate.retryAfter === "string" ? candidate.retryAfter : null,
328
+ typeof candidate.retryAfterSeconds === "number" ? candidate.retryAfterSeconds : null
329
+ );
330
+ }
331
+ current = candidate.cause;
332
+ }
333
+ return null;
334
+ }
335
+ function formatRetryGuidance(error) {
336
+ if (error.retryAfterSeconds !== null) {
337
+ const unit = error.retryAfterSeconds === 1 ? "second" : "seconds";
338
+ return ` Retry after ${error.retryAfterSeconds} ${unit}.`;
339
+ }
340
+ if (error.retryAfter) return ` Retry after ${error.retryAfter}.`;
341
+ return " Retry later.";
342
+ }
343
+ function formatCliFailure(error, json) {
344
+ const maintenanceError = findMaintenanceError(error);
345
+ const readRateLimitError = findCliReadRateLimitError(error);
346
+ if (readRateLimitError) {
347
+ const message = "CLI read budget exhausted.";
348
+ if (json) {
349
+ return {
350
+ exitCode: DYPT_MAINTENANCE_EXIT_CODE,
351
+ output: JSON.stringify({
352
+ error: {
353
+ code: readRateLimitError.code,
354
+ message,
355
+ retryable: true,
356
+ retryAfterSeconds: readRateLimitError.retryAfterSeconds
357
+ }
358
+ })
359
+ };
360
+ }
361
+ const unit = readRateLimitError.retryAfterSeconds === 1 ? "second" : "seconds";
362
+ return {
363
+ exitCode: DYPT_MAINTENANCE_EXIT_CODE,
364
+ output: `${message} Retry after ${readRateLimitError.retryAfterSeconds} ${unit} with backoff.`
365
+ };
366
+ }
367
+ if (!maintenanceError) {
368
+ return {
369
+ exitCode: 1,
370
+ output: error instanceof Error ? error.message : String(error)
371
+ };
372
+ }
373
+ if (json) {
374
+ return {
375
+ exitCode: DYPT_MAINTENANCE_EXIT_CODE,
376
+ output: JSON.stringify({
377
+ error: {
378
+ code: maintenanceError.code,
379
+ message: maintenanceError.message,
380
+ retryable: maintenanceError.retryable,
381
+ retryAfter: maintenanceError.retryAfter,
382
+ retryAfterSeconds: maintenanceError.retryAfterSeconds,
383
+ noChangeApplied: maintenanceError.noChangeApplied
384
+ }
385
+ })
386
+ };
387
+ }
388
+ return {
389
+ exitCode: DYPT_MAINTENANCE_EXIT_CODE,
390
+ output: `${maintenanceError.message} No change was applied.${formatRetryGuidance(maintenanceError)}`
391
+ };
392
+ }
393
+
394
+ // src/lib/trpc.ts
245
395
  function resolveBaseUrl(baseUrl) {
246
396
  return (baseUrl ?? getBaseUrl()).replace(/\/$/, "");
247
397
  }
@@ -260,6 +410,7 @@ async function createCliTrpcClient(options = {}) {
260
410
  httpBatchLink({
261
411
  url: `${baseUrl}/api/trpc`,
262
412
  transformer: superjson,
413
+ fetch: fetchWithMaintenanceCheck,
263
414
  headers() {
264
415
  return accessToken ? {
265
416
  Authorization: `Bearer ${accessToken}`
@@ -270,13 +421,16 @@ async function createCliTrpcClient(options = {}) {
270
421
  });
271
422
  }
272
423
  async function postJson(path4, body, options = {}) {
273
- const response = await fetch(new URL(path4, resolveBaseUrl(options.baseUrl)), {
274
- method: "POST",
275
- headers: {
276
- "content-type": "application/json"
277
- },
278
- body: JSON.stringify(body)
279
- });
424
+ const response = await fetchWithMaintenanceCheck(
425
+ new URL(path4, resolveBaseUrl(options.baseUrl)),
426
+ {
427
+ method: "POST",
428
+ headers: {
429
+ "content-type": "application/json"
430
+ },
431
+ body: JSON.stringify(body)
432
+ }
433
+ );
280
434
  return {
281
435
  status: response.status,
282
436
  json: await response.json()
@@ -431,6 +585,7 @@ import {
431
585
  mkdtemp,
432
586
  readFile as readFile2,
433
587
  readdir,
588
+ realpath,
434
589
  rm as rm2,
435
590
  stat,
436
591
  writeFile as writeFile2
@@ -676,6 +831,11 @@ async function installAgentSkill(input) {
676
831
  const source = await resolveSource(input.source, fetchFn);
677
832
  try {
678
833
  const exists = await pathExists(targetPath);
834
+ if (exists && input.source.type === "local" && await realpath(source.skillPath) === await realpath(targetPath)) {
835
+ throw new Error(
836
+ "Local toolkit source must differ from the install path."
837
+ );
838
+ }
679
839
  const action = exists ? "update" : "install";
680
840
  const metadata = exists ? await readMetadata(targetPath) : null;
681
841
  if (exists && !input.force && !input.backup) {
@@ -1122,6 +1282,20 @@ async function runTaskGet(input, deps) {
1122
1282
  }
1123
1283
 
1124
1284
  // src/commands/task/list.ts
1285
+ function getArchivedTagFilterWarnings(result) {
1286
+ if (typeof result !== "object" || result === null) return [];
1287
+ const warnings = result.warnings;
1288
+ if (!Array.isArray(warnings)) return [];
1289
+ return warnings.filter(
1290
+ (warning) => typeof warning === "object" && warning !== null && warning.code === "archived-tag-filter" && Array.isArray(warning.tagNames) && warning.tagNames.every(
1291
+ (tagName) => typeof tagName === "string"
1292
+ )
1293
+ );
1294
+ }
1295
+ function formatArchivedTagFilterWarning(tagNames) {
1296
+ const formattedNames = tagNames.map((name) => `"${name}"`).join(", ");
1297
+ return tagNames.length === 1 ? `Archived tag ${formattedNames} was ignored. Restore it before filtering.` : `Archived tags ${formattedNames} were ignored. Restore them before filtering.`;
1298
+ }
1125
1299
  async function runTaskList(input, deps) {
1126
1300
  const result = await deps.listTasks({
1127
1301
  parent: input.parent,
@@ -1156,6 +1330,9 @@ async function runTaskList(input, deps) {
1156
1330
  deps.printJson(result);
1157
1331
  return;
1158
1332
  }
1333
+ for (const warning of getArchivedTagFilterWarnings(result)) {
1334
+ deps.printWarning(formatArchivedTagFilterWarning(warning.tagNames));
1335
+ }
1159
1336
  deps.printTable({
1160
1337
  ...typeof result === "object" && result !== null ? result : {},
1161
1338
  meta: {
@@ -2567,6 +2744,10 @@ function printTable(value) {
2567
2744
  process.stdout.write(`${formatHumanOutput(value)}
2568
2745
  `);
2569
2746
  }
2747
+ function printWarning(message) {
2748
+ process.stderr.write(`Warning: ${message}
2749
+ `);
2750
+ }
2570
2751
  async function confirmAction(message, deps = {}) {
2571
2752
  if (deps.isTty === false) {
2572
2753
  return false;
@@ -3219,7 +3400,8 @@ function buildCli() {
3219
3400
  });
3220
3401
  }),
3221
3402
  printJson,
3222
- printTable
3403
+ printTable,
3404
+ printWarning
3223
3405
  }
3224
3406
  );
3225
3407
  }
@@ -3465,7 +3647,8 @@ function buildCli() {
3465
3647
  deadline: options.deadline ? parseDateOption(options.deadline, "start") : void 0,
3466
3648
  expectedTimeTaken: parseIntegerOption(
3467
3649
  options.expectedTime,
3468
- "expected-time"
3650
+ "expected-time",
3651
+ 1
3469
3652
  ),
3470
3653
  note: options.note,
3471
3654
  timeBeforeDeadline: options.reminder ? parseReminderTimings(options.reminder) : void 0,
@@ -3585,11 +3768,13 @@ function buildCli() {
3585
3768
  deadline: input.deadline ? new Date(String(input.deadline)) : void 0,
3586
3769
  expectedTimeTaken: parseIntegerOption(
3587
3770
  input.expectedTimeTaken,
3588
- "expected-time"
3771
+ "expected-time",
3772
+ 1
3589
3773
  ),
3590
3774
  actualTimeTaken: parseIntegerOption(
3591
3775
  input.actualTimeTaken,
3592
- "actual-time"
3776
+ "actual-time",
3777
+ 1
3593
3778
  ),
3594
3779
  archivedAt: input.archivedAt,
3595
3780
  parentId: await resolveParentId(
@@ -3607,11 +3792,13 @@ function buildCli() {
3607
3792
  deadline: input.deadline ? new Date(String(input.deadline)) : void 0,
3608
3793
  expectedTimeTaken: parseIntegerOption(
3609
3794
  input.expectedTimeTaken,
3610
- "expected-time"
3795
+ "expected-time",
3796
+ 1
3611
3797
  ),
3612
3798
  actualTimeTaken: parseIntegerOption(
3613
3799
  input.actualTimeTaken,
3614
- "actual-time"
3800
+ "actual-time",
3801
+ 1
3615
3802
  ),
3616
3803
  archivedAt: input.archivedAt,
3617
3804
  parentId: await resolveParentId(
@@ -3687,11 +3874,13 @@ function buildCli() {
3687
3874
  deadline: input.deadline ? new Date(String(input.deadline)) : void 0,
3688
3875
  expectedTimeTaken: parseIntegerOption(
3689
3876
  input.expectedTimeTaken,
3690
- "expected-time"
3877
+ "expected-time",
3878
+ 1
3691
3879
  ),
3692
3880
  actualTimeTaken: parseIntegerOption(
3693
3881
  input.actualTimeTaken,
3694
- "actual-time"
3882
+ "actual-time",
3883
+ 1
3695
3884
  ),
3696
3885
  archivedAt: input.archivedAt,
3697
3886
  parentId: await resolveParentId(
@@ -3711,11 +3900,13 @@ function buildCli() {
3711
3900
  deadline: input.deadline ? new Date(String(input.deadline)) : void 0,
3712
3901
  expectedTimeTaken: parseIntegerOption(
3713
3902
  input.expectedTimeTaken,
3714
- "expected-time"
3903
+ "expected-time",
3904
+ 1
3715
3905
  ),
3716
3906
  actualTimeTaken: parseIntegerOption(
3717
3907
  input.actualTimeTaken,
3718
- "actual-time"
3908
+ "actual-time",
3909
+ 1
3719
3910
  ),
3720
3911
  archivedAt: input.archivedAt,
3721
3912
  parentId: await resolveParentId(
@@ -4052,12 +4243,6 @@ async function runCli(argv) {
4052
4243
  await cli.parseAsync(argv);
4053
4244
  return 0;
4054
4245
  }
4055
- function formatCliError(error) {
4056
- if (error instanceof Error) {
4057
- return error.message;
4058
- }
4059
- return String(error);
4060
- }
4061
4246
  function isCliEntrypoint(invokedPath, moduleUrl) {
4062
4247
  if (!invokedPath) {
4063
4248
  return false;
@@ -4072,13 +4257,21 @@ function isCliEntrypoint(invokedPath, moduleUrl) {
4072
4257
  return pathToFileURL(invokedPath).href === moduleUrl;
4073
4258
  }
4074
4259
  }
4260
+ async function runCliEntrypoint(argv, deps = {}) {
4261
+ try {
4262
+ return await (deps.run ?? runCli)(argv);
4263
+ } catch (error) {
4264
+ const failure = formatCliFailure(error, argv.includes("--json"));
4265
+ (deps.writeError ?? ((output) => process.stderr.write(`${output}
4266
+ `)))(
4267
+ failure.output
4268
+ );
4269
+ return failure.exitCode;
4270
+ }
4271
+ }
4075
4272
  if (isCliEntrypoint(process.argv[1], import.meta.url)) {
4076
- void runCli(process.argv).then((exitCode) => {
4273
+ void runCliEntrypoint(process.argv).then((exitCode) => {
4077
4274
  process.exitCode = exitCode;
4078
- }).catch((error) => {
4079
- process.stderr.write(`${formatCliError(error)}
4080
- `);
4081
- process.exitCode = 1;
4082
4275
  });
4083
4276
  }
4084
4277
  export {
@@ -4086,6 +4279,7 @@ export {
4086
4279
  isCliEntrypoint,
4087
4280
  resolveParentId,
4088
4281
  resolveTaskRefFromSearchMatches,
4089
- runCli
4282
+ runCli,
4283
+ runCliEntrypoint
4090
4284
  };
4091
4285
  //# sourceMappingURL=index.js.map