@uipath/common 1.205.0-preview.277 → 1.206.0-preview.279

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 (41) hide show
  1. package/dist/attachment-binding.d.ts +2 -2
  2. package/dist/catch-error.d.ts +1 -0
  3. package/dist/catch-error.js +146 -15
  4. package/dist/classified-failure.d.ts +15 -17
  5. package/dist/command-examples.d.ts +5 -1
  6. package/dist/concurrency.d.ts +7 -0
  7. package/dist/entity-field-rules.js +1 -17
  8. package/dist/entity-name-rules.js +1 -17
  9. package/dist/error-codes.d.ts +41 -0
  10. package/dist/error-handler.d.ts +18 -1
  11. package/dist/error-handler.js +283 -58
  12. package/dist/error-instructions.d.ts +2 -1
  13. package/dist/exit-code.d.ts +30 -3
  14. package/dist/formatter.d.ts +18 -44
  15. package/dist/guid.js +1 -17
  16. package/dist/http-status.d.ts +18 -0
  17. package/dist/index.browser.d.ts +6 -0
  18. package/dist/index.browser.js +4010 -3568
  19. package/dist/index.d.ts +6 -0
  20. package/dist/index.js +7931 -7202
  21. package/dist/named-second.d.ts +27 -0
  22. package/dist/pass-through-tail.d.ts +54 -0
  23. package/dist/polling/poll-failure-mapping.d.ts +10 -7
  24. package/dist/polling/types.d.ts +8 -2
  25. package/dist/project-telemetry.d.ts +84 -0
  26. package/dist/report-failure.d.ts +31 -0
  27. package/dist/result-types.d.ts +12 -0
  28. package/dist/sdk-user-agent.js +19 -2
  29. package/dist/telemetry/index.d.ts +2 -0
  30. package/dist/telemetry/index.js +1816 -1734
  31. package/dist/telemetry/project-identity.d.ts +35 -0
  32. package/dist/telemetry/ship-succeeded.d.ts +7 -1
  33. package/dist/telemetry/telemetry-config.d.ts +2 -0
  34. package/dist/telemetry/telemetry-dimensions.d.ts +19 -1
  35. package/dist/telemetry/telemetry-events.d.ts +1 -0
  36. package/dist/telemetry/telemetry-init.d.ts +9 -3
  37. package/dist/testing.d.ts +57 -0
  38. package/dist/testing.js +3623 -0
  39. package/dist/timings.d.ts +4 -3
  40. package/dist/zip.js +139 -115
  41. package/package.json +6 -2
@@ -1,18 +1,149 @@
1
- var __defProp = Object.defineProperty;
2
- var __returnValue = (v) => v;
3
- function __exportSetter(name, newValue) {
4
- this[name] = __returnValue.bind(null, newValue);
5
- }
6
- var __export = (target, all) => {
7
- for (var name in all)
8
- __defProp(target, name, {
9
- get: all[name],
10
- enumerable: true,
11
- configurable: true,
12
- set: __exportSetter.bind(all, name)
13
- });
1
+ // src/telemetry/telemetry-dimensions.ts
2
+ var BaseDimensions = {
3
+ ApplicationName: "ApplicationName",
4
+ ProductVersion: "ProductVersion",
5
+ InstallationId: "InstallationId",
6
+ CloudUserId: "CloudUserId",
7
+ CloudTenantId: "CloudTenantId",
8
+ CloudOrganizationId: "CloudOrganizationId",
9
+ IsInternalUser: "IsInternalUser",
10
+ Environment: "Environment",
11
+ BaseUrl: "BaseUrl",
12
+ Region: "Region",
13
+ Agent: "Agent",
14
+ AgentVersion: "AgentVersion",
15
+ AgentModel: "AgentModel",
16
+ ToolName: "ToolName",
17
+ ToolVersion: "ToolVersion",
18
+ ExecutionContext: "ExecutionContext",
19
+ CiProvider: "CiProvider",
20
+ SessionIdSource: "SessionIdSource",
21
+ SessionId: "SessionId"
14
22
  };
15
- var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
23
+ var CommandDimensions = {
24
+ IsCommand: "IsCommand",
25
+ IsReexec: "IsReexec",
26
+ CommandName: "CommandName",
27
+ ExitCode: "ExitCode",
28
+ TerminalOutcome: "TerminalOutcome",
29
+ ErrorClass: "ErrorClass",
30
+ TerminalSignal: "TerminalSignal",
31
+ ErrorMessage: "ErrorMessage",
32
+ SkillName: "SkillName",
33
+ ProductArea: "ProductArea",
34
+ Mode: "Mode"
35
+ };
36
+ var ProjectDimensions = {
37
+ ProjectKey: "ProjectKey",
38
+ ProjectType: "ProjectType",
39
+ ProjectIdentityStatus: "ProjectIdentityStatus",
40
+ SolutionKey: "SolutionKey",
41
+ SolutionProjectKey: "SolutionProjectKey",
42
+ SolutionIdentityStatus: "SolutionIdentityStatus",
43
+ PreviousSolutionKey: "PreviousSolutionKey"
44
+ };
45
+ var GUID_KEY_DIMENSIONS = new Set([
46
+ ProjectDimensions.ProjectKey,
47
+ ProjectDimensions.SolutionKey,
48
+ ProjectDimensions.SolutionProjectKey,
49
+ ProjectDimensions.PreviousSolutionKey
50
+ ]);
51
+ var ShipDimensions = {
52
+ ShipKind: "ShipKind",
53
+ Target: "Target",
54
+ ProjectType: "ProjectType",
55
+ ProjectTypes: "ProjectTypes",
56
+ ArtifactCorrelationKey: "ArtifactCorrelationKey",
57
+ PackageName: "PackageName",
58
+ PackageVersion: "PackageVersion",
59
+ PackageVersionKey: "PackageVersionKey",
60
+ DeploymentKey: "DeploymentKey",
61
+ SolutionId: "SolutionId",
62
+ FolderKey: "FolderKey",
63
+ FeedId: "FeedId"
64
+ };
65
+ var ErrorDimensions = {
66
+ Result: "Result",
67
+ ErrorCode: "ErrorCode",
68
+ Retry: "Retry",
69
+ ErrorMessage: "ErrorMessage",
70
+ HttpStatus: "HttpStatus",
71
+ UpstreamErrorCode: "UpstreamErrorCode"
72
+ };
73
+ var AuthDimensions = {
74
+ AuthenticationMethod: "AuthenticationMethod",
75
+ Success: "Success",
76
+ Reason: "Reason"
77
+ };
78
+ var SkillsDimensions = {
79
+ SchemaVersion: "SchemaVersion",
80
+ AgentType: "AgentType",
81
+ SkillsVersion: "SkillsVersion",
82
+ UipSubcommand: "UipSubcommand",
83
+ FileExtension: "FileExtension",
84
+ SubagentModel: "SubagentModel",
85
+ SubagentType: "SubagentType",
86
+ PermissionMode: "PermissionMode",
87
+ EffortLevel: "EffortLevel",
88
+ SessionSource: "SessionSource",
89
+ Outcome: "Outcome",
90
+ DurationMs: "DurationMs",
91
+ Source: "Source"
92
+ };
93
+ var PackagerDimensions = {
94
+ ProjectId: "ProjectId",
95
+ ProjectType: "ProjectType",
96
+ SolutionId: "SolutionId"
97
+ };
98
+ var ScopeDimensions = {
99
+ FolderId: "FolderId"
100
+ };
101
+ var ID_DIMENSIONS = new Set([
102
+ BaseDimensions.CloudUserId,
103
+ BaseDimensions.CloudTenantId,
104
+ BaseDimensions.CloudOrganizationId,
105
+ BaseDimensions.InstallationId,
106
+ ShipDimensions.ArtifactCorrelationKey,
107
+ ShipDimensions.PackageVersionKey,
108
+ ShipDimensions.DeploymentKey,
109
+ ShipDimensions.SolutionId,
110
+ ShipDimensions.FolderKey,
111
+ ShipDimensions.FeedId,
112
+ PackagerDimensions.ProjectId
113
+ ]);
114
+ var RESERVED_DIMENSION_NAMES = new Set([
115
+ ...Object.values(BaseDimensions),
116
+ ...Object.values(CommandDimensions),
117
+ ...Object.values(ShipDimensions),
118
+ ...Object.values(ProjectDimensions),
119
+ ...Object.values(ErrorDimensions),
120
+ ...Object.values(AuthDimensions),
121
+ ...Object.values(SkillsDimensions),
122
+ ...Object.values(PackagerDimensions),
123
+ ...Object.values(ScopeDimensions)
124
+ ]);
125
+ var CURATED_DIMENSIONS = new Set([
126
+ BaseDimensions.ApplicationName,
127
+ BaseDimensions.ProductVersion,
128
+ BaseDimensions.InstallationId,
129
+ BaseDimensions.CloudUserId,
130
+ BaseDimensions.CloudTenantId,
131
+ BaseDimensions.CloudOrganizationId,
132
+ BaseDimensions.IsInternalUser,
133
+ BaseDimensions.Environment,
134
+ BaseDimensions.BaseUrl,
135
+ BaseDimensions.Region,
136
+ BaseDimensions.Agent,
137
+ BaseDimensions.AgentVersion,
138
+ BaseDimensions.ToolVersion,
139
+ BaseDimensions.ExecutionContext,
140
+ BaseDimensions.CiProvider,
141
+ BaseDimensions.SessionIdSource,
142
+ BaseDimensions.SessionId,
143
+ ...Object.values(CommandDimensions),
144
+ ...Object.values(ShipDimensions),
145
+ ...Object.values(ProjectDimensions)
146
+ ]);
16
147
 
17
148
  // src/telemetry/pseudonymize.ts
18
149
  var SHA256_K = new Uint32Array([
@@ -290,6 +421,63 @@ function settlePromiseLike(thenable) {
290
421
  return Promise.resolve(thenable).then((data) => [undefined, data]).catch((error) => [toError(error), undefined]);
291
422
  }
292
423
 
424
+ // src/error-codes.ts
425
+ var CLI_ERROR_CODES = [
426
+ "invalid_argument",
427
+ "authentication_required",
428
+ "permission_denied",
429
+ "local_permission_denied",
430
+ "not_found",
431
+ "rate_limited",
432
+ "network_error",
433
+ "timeout",
434
+ "server_error",
435
+ "method_not_allowed",
436
+ "not_supported",
437
+ "configuration_error",
438
+ "execution_failed",
439
+ "unknown_error"
440
+ ];
441
+ var RETRY_HINTS = [
442
+ "RetryWillNotFix",
443
+ "RetryLater",
444
+ "RetryAfter1Second",
445
+ "RetryAfter10Seconds",
446
+ "RetryAfter30Seconds",
447
+ "RetryAfter60Seconds"
448
+ ];
449
+ var CLI_ERROR_CODE_VALUES = new Set(CLI_ERROR_CODES);
450
+ var RETRY_HINT_VALUES = new Set(RETRY_HINTS);
451
+ function isCliErrorCode(value) {
452
+ return typeof value === "string" && CLI_ERROR_CODE_VALUES.has(value);
453
+ }
454
+ function isRetryHint(value) {
455
+ return typeof value === "string" && RETRY_HINT_VALUES.has(value);
456
+ }
457
+ function carriedErrorCode(error) {
458
+ if (!error || typeof error !== "object")
459
+ return;
460
+ const code = error.errorCode;
461
+ return isCliErrorCode(code) ? code : undefined;
462
+ }
463
+ function carriedRetry(error) {
464
+ if (!error || typeof error !== "object")
465
+ return;
466
+ const retry = error.retry;
467
+ return isRetryHint(retry) ? retry : undefined;
468
+ }
469
+ function defaultRetryForErrorCode(errorCode) {
470
+ switch (errorCode) {
471
+ case "network_error":
472
+ case "rate_limited":
473
+ case "server_error":
474
+ case "timeout":
475
+ return "RetryLater";
476
+ default:
477
+ return "RetryWillNotFix";
478
+ }
479
+ }
480
+
293
481
  // src/error-graph.ts
294
482
  function* walkErrorGraph(error) {
295
483
  const queue = [error];
@@ -334,6 +522,40 @@ function findHttpStatusInGraph(error) {
334
522
  return;
335
523
  }
336
524
 
525
+ // src/http-status.ts
526
+ function classifyHttpStatus(status) {
527
+ if (status === undefined)
528
+ return;
529
+ if (status === 400 || status === 409 || status === 413 || status === 422) {
530
+ return { errorCode: "invalid_argument", retry: "RetryWillNotFix" };
531
+ }
532
+ if (status === 401) {
533
+ return {
534
+ errorCode: "authentication_required",
535
+ retry: "RetryWillNotFix"
536
+ };
537
+ }
538
+ if (status === 403) {
539
+ return { errorCode: "permission_denied", retry: "RetryWillNotFix" };
540
+ }
541
+ if (status === 404) {
542
+ return { errorCode: "not_found", retry: "RetryWillNotFix" };
543
+ }
544
+ if (status === 405) {
545
+ return { errorCode: "method_not_allowed", retry: "RetryWillNotFix" };
546
+ }
547
+ if (status === 408) {
548
+ return { errorCode: "timeout", retry: "RetryLater" };
549
+ }
550
+ if (status === 429) {
551
+ return { errorCode: "rate_limited", retry: "RetryLater" };
552
+ }
553
+ if (status >= 500 && status < 600) {
554
+ return { errorCode: "server_error", retry: "RetryLater" };
555
+ }
556
+ return;
557
+ }
558
+
337
559
  // src/local-permission-codes.ts
338
560
  var LOCAL_PERMISSION_ERROR_CODES = new Set([
339
561
  "EACCES",
@@ -346,6 +568,8 @@ var DEFAULT_401 = "Unauthorized (401). The session is missing or expired, or its
346
568
  var DEFAULT_403 = "Forbidden (403). The account lacks permission for this operation, or the token carries no scope for this API. Run `uip login status --detailed` to see the token's scopes.";
347
569
  var DEFAULT_405 = "Method Not Allowed (405). The endpoint may not exist or the base URL may be incorrect.";
348
570
  var DEFAULT_413 = "Payload too large (413). The upload exceeded the server or CDN size limit. Reduce the package size — for example, exclude unused dependencies or remove large files from the project — and try again.";
571
+ var CLOUDFLARE_BLOCK_403 = "Forbidden (403) by Cloudflare, in front of the service: the answer is a Cloudflare HTML page, not the service's JSON, so the service did not see the request and did not check the account's roles or the token's scopes. Cloudflare blocks a request when its content matches a firewall rule (text that looks like SQL or script code, for example) or when it comes from a network the firewall does not allow.";
572
+ var CLOUDFLARE_BLOCK_403_INSTRUCTIONS = "If the request carries text that looks like code, change that text and try again. Otherwise send the time of the request and the Cloudflare Ray ID, when the message gives one, to the owner of the service or UiPath support.";
349
573
  var HTML_RESPONSE_MESSAGE = "Received HTML instead of the expected JSON response.";
350
574
  var NETWORK_ERROR_CODES = new Set([
351
575
  "ECONNREFUSED",
@@ -468,6 +692,20 @@ function localPermissionPath(path, message) {
468
692
  return path;
469
693
  return message ? /'([^']+)'/.exec(message)?.[1] : undefined;
470
694
  }
695
+ function readHeader(response, name) {
696
+ const headers = response?.headers;
697
+ if (!headers || typeof headers !== "object")
698
+ return;
699
+ if (typeof headers.get === "function") {
700
+ const value = headers.get(name);
701
+ if (value)
702
+ return value;
703
+ }
704
+ const plain = headers;
705
+ const key = Object.keys(plain).find((k) => k.toLowerCase() === name.toLowerCase());
706
+ const value = key === undefined ? undefined : plain[key];
707
+ return typeof value === "string" && value !== "" ? value : undefined;
708
+ }
471
709
  function isHtmlDocument(body) {
472
710
  return /^\s*(<!doctype html|<html\b)/i.test(body);
473
711
  }
@@ -484,36 +722,9 @@ function retryHintForRetryAfter(seconds) {
484
722
  return "RetryAfter60Seconds";
485
723
  }
486
724
  function classifyError(status, error) {
487
- if (status === 400 || status === 409 || status === 422) {
488
- return { errorCode: "invalid_argument", retry: "RetryWillNotFix" };
489
- }
490
- if (status === 401) {
491
- return {
492
- errorCode: "authentication_required",
493
- retry: "RetryWillNotFix"
494
- };
495
- }
496
- if (status === 403) {
497
- return { errorCode: "permission_denied", retry: "RetryWillNotFix" };
498
- }
499
- if (status === 404) {
500
- return { errorCode: "not_found", retry: "RetryWillNotFix" };
501
- }
502
- if (status === 405) {
503
- return { errorCode: "method_not_allowed", retry: "RetryWillNotFix" };
504
- }
505
- if (status === 413) {
506
- return { errorCode: "invalid_argument", retry: "RetryWillNotFix" };
507
- }
508
- if (status === 408) {
509
- return { errorCode: "timeout", retry: "RetryLater" };
510
- }
511
- if (status === 429) {
512
- return { errorCode: "rate_limited", retry: "RetryLater" };
513
- }
514
- if (status !== undefined && status >= 500 && status < 600) {
515
- return { errorCode: "server_error", retry: "RetryLater" };
516
- }
725
+ const byStatus = classifyHttpStatus(status);
726
+ if (byStatus)
727
+ return byStatus;
517
728
  if (status === undefined && describePermissionError(error)) {
518
729
  return {
519
730
  errorCode: "local_permission_denied",
@@ -529,6 +740,20 @@ function classifyError(status, error) {
529
740
  }
530
741
  return { errorCode: "unknown_error", retry: "RetryWillNotFix" };
531
742
  }
743
+ function withCarriedClass(inferred, error) {
744
+ const errorCode = carriedErrorCode(error);
745
+ const retry = carriedRetry(error);
746
+ if (errorCode === undefined || errorCode === inferred.errorCode) {
747
+ return {
748
+ errorCode: inferred.errorCode,
749
+ retry: retry ?? inferred.retry
750
+ };
751
+ }
752
+ return { errorCode, retry: retry ?? defaultRetryForErrorCode(errorCode) };
753
+ }
754
+ function classifyThrownError(error) {
755
+ return withCarriedClass(classifyError(findHttpStatusInGraph(error), error), error);
756
+ }
532
757
  function formatHttpStatusMessage(status, rawMessage, extractedMessage, inferredStatus) {
533
758
  if (extractedMessage) {
534
759
  return `HTTP ${status}: ${extractedMessage}`;
@@ -584,9 +809,14 @@ async function extractErrorDetails(error, options) {
584
809
  const classificationStatus = status ?? findHttpStatusInGraph(error);
585
810
  const classification = classifyError(classificationStatus, error);
586
811
  let retry = classification.retry;
812
+ const htmlForbidden = status === 403 && rawBody !== undefined && isHtmlDocument(rawBody);
813
+ const rayId = htmlForbidden ? readHeader(response, "cf-ray") : undefined;
814
+ const cloudflareBlock = htmlForbidden && (rayId !== undefined || /\bcloudflare\b/i.test(readHeader(response, "server") ?? ""));
587
815
  if (status === 401) {
588
816
  message = DEFAULT_401;
589
817
  result = "AuthenticationError";
818
+ } else if (cloudflareBlock) {
819
+ message = rayId ? `${CLOUDFLARE_BLOCK_403} Cloudflare Ray ID: ${rayId}.` : CLOUDFLARE_BLOCK_403;
590
820
  } else if (status === 403) {
591
821
  message = options?.forbiddenMessage ?? DEFAULT_403;
592
822
  result = "AuthenticationError";
@@ -634,7 +864,9 @@ async function extractErrorDetails(error, options) {
634
864
  }
635
865
  }
636
866
  let details = rawMessage;
637
- if (rawBody) {
867
+ if (htmlForbidden) {
868
+ details = cloudflareBlock ? CLOUDFLARE_BLOCK_403_INSTRUCTIONS : HTML_RESPONSE_MESSAGE;
869
+ } else if (rawBody) {
638
870
  if (parsedBody) {
639
871
  const extra = {};
640
872
  if (parsedBody.errorCode)
@@ -668,6 +900,8 @@ async function extractErrorDetails(error, options) {
668
900
  }
669
901
  if (parsedBody?.requestId && typeof parsedBody.requestId === "string") {
670
902
  context.requestId = parsedBody.requestId;
903
+ } else if (cloudflareBlock && rayId) {
904
+ context.requestId = rayId;
671
905
  }
672
906
  if (parsedBody?.traceId && typeof parsedBody.traceId === "string") {
673
907
  context.traceId = parsedBody.traceId;
@@ -676,16 +910,7 @@ async function extractErrorDetails(error, options) {
676
910
  context.path = permission.path;
677
911
  }
678
912
  if (status === 429) {
679
- const resp = response;
680
- const headersObj = resp?.headers;
681
- let retryAfterValue;
682
- if (headersObj && typeof headersObj === "object" && typeof headersObj.get === "function") {
683
- retryAfterValue = headersObj.get("retry-after") ?? undefined;
684
- }
685
- if (!retryAfterValue && headersObj && typeof headersObj === "object") {
686
- const headers = headersObj;
687
- retryAfterValue = headers["retry-after"] ?? headers["Retry-After"];
688
- }
913
+ const retryAfterValue = readHeader(response, "retry-after");
689
914
  if (retryAfterValue) {
690
915
  const seconds = Number(retryAfterValue);
691
916
  if (!Number.isNaN(seconds)) {
@@ -719,9 +944,8 @@ async function extractErrorDetails(error, options) {
719
944
  }
720
945
  return {
721
946
  result,
722
- errorCode: classification.errorCode,
947
+ ...withCarriedClass({ errorCode: classification.errorCode, retry }, error),
723
948
  message,
724
- retry,
725
949
  details,
726
950
  ...hasContext ? { context } : {},
727
951
  ...parsedErrors ? { parsedErrors } : {}
@@ -747,6 +971,7 @@ function extractErrorMessageSync(error) {
747
971
  }
748
972
  export {
749
973
  carriedInstructions,
974
+ classifyThrownError,
750
975
  describeConnectivityError,
751
976
  describePermissionError,
752
977
  extractErrorDetails,
@@ -757,4 +982,4 @@ export {
757
982
  parseHttpStatusFromMessage
758
983
  };
759
984
 
760
- //# debugId=3365B45717D61F5364756E2164756E21
985
+ //# debugId=96D7F037EEEC724764756E2164756E21
@@ -1,2 +1,3 @@
1
- export type ErrorInstructionContext = "auth" | "identity" | "input-parse" | "input-validate" | "flag-format" | "backend" | "permissions";
1
+ export type ErrorInstructionContext = "auth" | "auth-configuration" | "identity" | "input-parse" | "input-validate" | "flag-format" | "backend" | "permissions";
2
+ export declare function hasIdentityInstructionContext(err: unknown): boolean;
2
3
  export declare function instructionsFor(ctx: ErrorInstructionContext, err?: unknown): string;
@@ -11,6 +11,9 @@
11
11
  * takes the child's) call {@link setExitCode} directly. Everything inside a
12
12
  * command handler goes through `context.exit`.
13
13
  *
14
+ * Every write also lands in the invocation's `UIP_TIMINGS` report, so the code
15
+ * it prints is the one the process settles on, whichever path wrote it.
16
+ *
14
17
  * `bun scripts/lint-exit-code.ts` (part of `bun run lint`) keeps this the only
15
18
  * writer: an assignment to `process.exitCode` in any other package file fails.
16
19
  */
@@ -18,11 +21,35 @@
18
21
  * Record `code` as the process exit code.
19
22
  *
20
23
  * Last write wins, which is what the scattered assignments did: an explicit
21
- * `exit(code)` is the caller's final word. A caller that must not overwrite an
22
- * earlier failure with success — the exit(0) at the end of a run — checks
23
- * {@link getExitCode} first; the CLI host's `context.exit` does exactly that.
24
+ * `exit(code)` is the caller's final word. A host's `context.exit` goes through
25
+ * {@link recordHostExit}, so the exit(0) at the end of a run cannot overwrite
26
+ * an earlier failure with success.
24
27
  */
25
28
  export declare function setExitCode(code: number): void;
29
+ /**
30
+ * Record the code a command passed to `context.exit(code)`.
31
+ *
32
+ * Same as {@link setExitCode}, except a generic failure (`1`) does not replace
33
+ * a non-zero code already recorded. `OutputFormatter.error()` records the code
34
+ * its `Result` maps to — 2 for `AuthenticationError`, 3 for `ValidationError`,
35
+ * 4 for `TimeoutError` — and handlers have always followed it with `exit(1)`.
36
+ * Last-write-wins turned every one of those into a plain 1, so the exit codes
37
+ * `docs/reference/cli-contracts.md` documents never reached the shell.
38
+ *
39
+ * Any other code is still the caller's final word: `exit(0)` clears a failure
40
+ * (a host's own trailing `exit(0)` goes through {@link recordHostExit}
41
+ * instead), and a specific code such as `exit(2)` replaces whatever was there.
42
+ */
43
+ export declare function recordCommandExit(code: number): void;
44
+ /**
45
+ * Record the code a host's `context.exit(code)` was given: the standalone CLI
46
+ * and the MCP bridge both.
47
+ *
48
+ * {@link recordCommandExit}, except `0` never clears a failure. A host has no
49
+ * `process.exit()` to stop a run, so it calls `exit(0)` once the command has
50
+ * returned, after a handler may already have recorded its failure.
51
+ */
52
+ export declare function recordHostExit(code: number): void;
26
53
  /**
27
54
  * The recorded exit code; `0` when nothing has set one.
28
55
  *
@@ -1,6 +1,10 @@
1
+ import { type CliErrorCode, type RetryHint } from "./error-codes";
1
2
  import { isOutputFormat, OUTPUT_FORMATS, type OutputFormat } from "./output-formats";
3
+ import type { FailureResultType, ResultType } from "./result-types";
4
+ import { RESULTS } from "./result-types";
2
5
  import { type CommandErrorClass, type TerminalOutcome } from "./telemetry/command-terminal.js";
3
- export { isOutputFormat, OUTPUT_FORMATS, type OutputFormat };
6
+ export { CLI_ERROR_CODES, type CliErrorCode, carriedErrorCode, carriedRetry, isCliErrorCode, isRetryHint, RETRY_HINTS, type RetryHint, } from "./error-codes";
7
+ export { type FailureResultType, isOutputFormat, OUTPUT_FORMATS, type OutputFormat, RESULTS, type ResultType, };
4
8
  /**
5
9
  * Per-row highlight for interactive TABLE output only. Applied line-level
6
10
  * AFTER column padding, so width math never sees escape bytes; json/yaml/plain
@@ -9,49 +13,6 @@ export { isOutputFormat, OUTPUT_FORMATS, type OutputFormat };
9
13
  export type TableRowStyle = "red" | "dim";
10
14
  /** Chooses a highlight for a (PascalCase-normalized) table row, or none. */
11
15
  export type TableRowStyleFn = (row: Record<string, unknown>) => TableRowStyle | undefined;
12
- export type ResultType = "Success" | "Failure" | "ConfigError" | "AuthenticationError" | "ValidationError" | "TimeoutError";
13
- export type FailureResultType = Exclude<ResultType, "Success">;
14
- export declare const CLI_ERROR_CODES: readonly ["invalid_argument", "authentication_required", "permission_denied", "local_permission_denied", "not_found", "rate_limited", "network_error", "timeout", "server_error", "method_not_allowed", "not_supported", "configuration_error", "execution_failed", "unknown_error"];
15
- export type CliErrorCode = (typeof CLI_ERROR_CODES)[number];
16
- export declare const RETRY_HINTS: readonly ["RetryWillNotFix", "RetryLater", "RetryAfter1Second", "RetryAfter10Seconds", "RetryAfter30Seconds", "RetryAfter60Seconds"];
17
- export type RetryHint = (typeof RETRY_HINTS)[number];
18
- /**
19
- * Narrow an arbitrary value to a {@link CliErrorCode}.
20
- *
21
- * Codes read off a caught error (or any other value the CLI did not produce
22
- * itself) have to be checked rather than cast, or an unrecognised string
23
- * reaches the output as an ErrorCode no consumer knows how to branch on.
24
- */
25
- export declare function isCliErrorCode(value: unknown): value is CliErrorCode;
26
- /** Narrow an arbitrary value to a {@link RetryHint}. See {@link isCliErrorCode}. */
27
- export declare function isRetryHint(value: unknown): value is RetryHint;
28
- /**
29
- * The `ErrorCode` an error carries, when it classified itself.
30
- *
31
- * Companion to `carriedInstructions` (error-handler): a thrower that knows its
32
- * failure mode can say so, and the renderer uses it instead of defaulting to
33
- * `unknown_error`. Duck-typed and validated for the same reason — the error may
34
- * have crossed a bundle boundary, and an unrecognised string must not reach the
35
- * envelope as a code no consumer can branch on.
36
- *
37
- * Lives here, beside {@link isCliErrorCode}, rather than next to
38
- * `carriedInstructions`: error-handler reaches formatter type-only on purpose,
39
- * and a runtime edge from there pulls this module's telemetry imports into the
40
- * browser bundle, which cannot require node builtins.
41
- */
42
- export declare function carriedErrorCode(error: unknown): CliErrorCode | undefined;
43
- /** The `Retry` hint an error carries. See {@link carriedErrorCode}. */
44
- export declare function carriedRetry(error: unknown): RetryHint | undefined;
45
- /** Canonical string constants for {@link ResultType} values. */
46
- export declare const RESULTS: {
47
- readonly Success: "Success";
48
- readonly Failure: "Failure";
49
- readonly ConfigError: "ConfigError";
50
- readonly AuthenticationError: "AuthenticationError";
51
- readonly ValidationError: "ValidationError";
52
- /** A wait the caller bounded with --timeout ran out (e.g. `tm testsets clone`); exit 4. */
53
- readonly TimeoutError: "TimeoutError";
54
- };
55
16
  /**
56
17
  * Maps each {@link ResultType} to a numeric process exit code.
57
18
  *
@@ -71,6 +32,11 @@ export declare const EXIT_CODES: {
71
32
  readonly ValidationError: 3;
72
33
  readonly TimeoutError: 4;
73
34
  };
35
+ /**
36
+ * The exit code a failure envelope's `Result` maps to in {@link EXIT_CODES},
37
+ * and `1` for a value outside it (an unchecked string at runtime).
38
+ */
39
+ export declare function exitCodeForResult(result: FailureResultType): number;
74
40
  /** Widened record type that accepts interface types (which lack an implicit
75
41
  * index signature in TypeScript) while still representing keyed objects. */
76
42
  export type DataRecord = Record<string, unknown> | (object & Record<never, never>);
@@ -97,6 +63,14 @@ export declare class Pagination {
97
63
  nextPage?: string;
98
64
  });
99
65
  }
66
+ /**
67
+ * For rows the API already windowed, so the total is unknown. Without --limit
68
+ * the server may still cap the page, so any non-empty page reports HasMore.
69
+ */
70
+ export declare function apiPagination(returned: number, options: {
71
+ limit?: number;
72
+ offset: number;
73
+ }): Pagination | undefined;
100
74
  export declare class SuccessOutput {
101
75
  Result: "Success";
102
76
  Code: string;
package/dist/guid.js CHANGED
@@ -1,19 +1,3 @@
1
- var __defProp = Object.defineProperty;
2
- var __returnValue = (v) => v;
3
- function __exportSetter(name, newValue) {
4
- this[name] = __returnValue.bind(null, newValue);
5
- }
6
- var __export = (target, all) => {
7
- for (var name in all)
8
- __defProp(target, name, {
9
- get: all[name],
10
- enumerable: true,
11
- configurable: true,
12
- set: __exportSetter.bind(all, name)
13
- });
14
- };
15
- var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
16
-
17
1
  // src/guid.ts
18
2
  var GUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
19
3
  function isGuid(value) {
@@ -23,4 +7,4 @@ export {
23
7
  isGuid
24
8
  };
25
9
 
26
- //# debugId=13FF8B3F125159DD64756E2164756E21
10
+ //# debugId=F25023E1915C1B3664756E2164756E21
@@ -1,3 +1,4 @@
1
+ import type { CliErrorCode, RetryHint } from "./error-codes";
1
2
  /**
2
3
  * The HTTP status an SDK error carries — from the `Response` a generated
3
4
  * client attaches, or from the error's own `status` — and `undefined` when it
@@ -5,3 +6,20 @@
5
6
  * status, such as a 404 "no such record", from every other failure.
6
7
  */
7
8
  export declare function httpStatusOf(error: unknown): number | undefined;
9
+ /** The error code and retry hint an HTTP status classifies as. */
10
+ export interface HttpStatusClassification {
11
+ errorCode: CliErrorCode;
12
+ retry: RetryHint;
13
+ }
14
+ /**
15
+ * Classify an HTTP status into the `ErrorCode` and `Retry` that agents branch
16
+ * on, or `undefined` for a status with no specific code (the caller falls back
17
+ * to its own default).
18
+ *
19
+ * The one table for every reader: `extractErrorDetails`, classifying a caught
20
+ * error; the defaults `OutputFormatter.error()` fills into an envelope that
21
+ * names a status but no `ErrorCode`; and the error class command telemetry
22
+ * derives from that `ErrorCode`. They kept separate copies until the copies
23
+ * disagreed on 413.
24
+ */
25
+ export declare function classifyHttpStatus(status: number | undefined): HttpStatusClassification | undefined;
@@ -1,8 +1,10 @@
1
1
  export * from "./catch-error";
2
+ export * from "./classified-failure";
2
3
  export * from "./command-examples";
3
4
  export * from "./command-help";
4
5
  export * from "./command-walker";
5
6
  export * from "./completer";
7
+ export * from "./concurrency";
6
8
  export { installConsoleGuard, restoreConsole } from "./console-guard";
7
9
  export * from "./constants";
8
10
  export * from "./content-hash";
@@ -23,7 +25,10 @@ export * from "./output-format-context";
23
25
  export * from "./output-formats";
24
26
  export * from "./output-sink";
25
27
  export * from "./package-metadata-options";
28
+ export * from "./pass-through-tail";
26
29
  export * from "./polling";
30
+ export { configureProjectContextTelemetry, configureProjectTelemetry, createIdentityCommandResolver, createProjectCommandResolver, findStaleProjectTargetRules, getProjectTelemetryCapture, isProjectTelemetryDisabled, type ProjectContextTelemetryResolver, type ProjectTargetRule, type ProjectTelemetryCapture, type ProjectTelemetryInput, type ProjectTelemetryResolver, } from "./project-telemetry.js";
31
+ export * from "./result-types";
27
32
  export * from "./screen-logger";
28
33
  export * from "./sdk-user-agent";
29
34
  export * from "./singleton";
@@ -32,6 +37,7 @@ export * from "./telemetry/command-attribution.js";
32
37
  export * from "./telemetry/command-terminal.js";
33
38
  export { ConsoleTelemetryProvider } from "./telemetry/console-telemetry-provider.js";
34
39
  export type { IContextStorage } from "./telemetry/context-storage.js";
40
+ export * from "./telemetry/project-identity.js";
35
41
  export { getConfiguredTelemetrySessionId, getTelemetrySessionId, getTelemetrySessionSource, TELEMETRY_SESSION_ID_ENV, TELEMETRY_SESSION_SOURCE_PROPERTY, } from "./telemetry/session-id.js";
36
42
  export * from "./telemetry/telemetry-dimensions.js";
37
43
  export * from "./telemetry/telemetry-events.js";