@marinoscar/platform-cli 0.0.0-stage → 0.1.0-next.3

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 (40) hide show
  1. package/CHANGELOG.md +20 -0
  2. package/LICENSE +21 -0
  3. package/README.md +87 -2
  4. package/dist/core/command-registry.d.ts +50 -0
  5. package/dist/core/command-registry.d.ts.map +1 -0
  6. package/dist/core/command-registry.js +97 -0
  7. package/dist/core/command-registry.js.map +1 -0
  8. package/dist/core/env-spec-registry.d.ts +119 -0
  9. package/dist/core/env-spec-registry.d.ts.map +1 -0
  10. package/dist/core/env-spec-registry.js +88 -0
  11. package/dist/core/env-spec-registry.js.map +1 -0
  12. package/dist/core/env-values.d.ts +75 -0
  13. package/dist/core/env-values.d.ts.map +1 -0
  14. package/dist/core/env-values.js +123 -0
  15. package/dist/core/env-values.js.map +1 -0
  16. package/dist/core/index.d.ts +6 -0
  17. package/dist/core/index.d.ts.map +1 -0
  18. package/dist/core/index.js +6 -0
  19. package/dist/core/index.js.map +1 -0
  20. package/dist/index.d.ts +11 -0
  21. package/dist/index.d.ts.map +1 -0
  22. package/dist/index.js +11 -0
  23. package/dist/index.js.map +1 -0
  24. package/dist/telemetry/env-fragment.d.ts +47 -0
  25. package/dist/telemetry/env-fragment.d.ts.map +1 -0
  26. package/dist/telemetry/env-fragment.js +73 -0
  27. package/dist/telemetry/env-fragment.js.map +1 -0
  28. package/dist/telemetry/index.d.ts +6 -0
  29. package/dist/telemetry/index.d.ts.map +1 -0
  30. package/dist/telemetry/index.js +6 -0
  31. package/dist/telemetry/index.js.map +1 -0
  32. package/dist/telemetry/node-span-relay.d.ts +107 -0
  33. package/dist/telemetry/node-span-relay.d.ts.map +1 -0
  34. package/dist/telemetry/node-span-relay.js +281 -0
  35. package/dist/telemetry/node-span-relay.js.map +1 -0
  36. package/dist/telemetry/node-span.d.ts +60 -0
  37. package/dist/telemetry/node-span.d.ts.map +1 -0
  38. package/dist/telemetry/node-span.js +10 -0
  39. package/dist/telemetry/node-span.js.map +1 -0
  40. package/package.json +64 -4
@@ -0,0 +1,281 @@
1
+ // =============================================================================
2
+ // Job phase spans, recorded here and relayed to the server (issue #608)
3
+ // =============================================================================
4
+ // Moved from the reference CLI's `node/node-span-relay.ts` by PP-4.5 (#706).
5
+ // It reads an HTTP status STRUCTURALLY (a numeric `status` on the error), so it
6
+ // needs no app error class: the app's `ApiError` classifies exactly as before.
7
+ //
8
+ // A worker records WHEN each phase of a job ran (download, execute, upload,
9
+ // submit, secret) and hands those timings to `POST /api/nodes/:id/telemetry`.
10
+ // The server re-emits them as OpenTelemetry spans under the job's enqueuing
11
+ // trace. The node never talks to a collector, holds no exporter endpoint, and
12
+ // takes no new dependency: a span here is five numbers and a name.
13
+ //
14
+ // ⚠ TELEMETRY NEVER DELAYS OR FAILS A JOB. Recording is synchronous
15
+ // arithmetic that cannot throw into the job; SENDING happens after the job has
16
+ // settled, off the job's promise, through a bounded queue. Every failure of
17
+ // the relay is swallowed:
18
+ //
19
+ // - 404: the server predates the relay (or forgot this node). Span sending
20
+ // is DISABLED for the rest of the process and announced once — retrying a
21
+ // route that does not exist on every job would be a steady trickle of
22
+ // pointless requests.
23
+ // - 400 / 403 / 429 / anything else: this batch is dropped, silently. A 400
24
+ // is a contract mismatch no retry fixes; a 429 is the server asking for
25
+ // less, and resending is the opposite.
26
+ //
27
+ // ⚠ NO MESSAGE EVER LEAVES AS A SPAN. An errored phase carries `errorType` —
28
+ // the error's class name, plus an HTTP status or an errno-style code when
29
+ // there is one — sanitised to the server's identifier-only shape. Messages
30
+ // carry paths, hosts and signed URLs; the server would refuse them anyway,
31
+ // and this side does not offer.
32
+ //
33
+ // ⚠ INTEGER-ONLY, ALLOWLISTED ATTRIBUTES. `bytes`, `attempt`, `exitCode` and
34
+ // `httpStatus`, each range-checked (`cleanAttributes`); anything else, and
35
+ // any value the server would refuse, is dropped before it is queued. There is
36
+ // no string attribute, so no URL, path or credential can ride along in one.
37
+ // =============================================================================
38
+ /**
39
+ * Spans the server accepts per request. Mirrors `MAX_NODE_SPANS_PER_REQUEST`.
40
+ *
41
+ * @stability experimental
42
+ */
43
+ export const MAX_SPANS_PER_BATCH = 50;
44
+ /**
45
+ * Spans held while waiting to send. Past this the OLDEST are dropped.
46
+ *
47
+ * @stability experimental
48
+ */
49
+ export const DEFAULT_MAX_QUEUED_SPANS = 500;
50
+ /** Mirrors the server's `NODE_SPAN_ERROR_TYPE_PATTERN` and length cap. */
51
+ const ERROR_TYPE_MAX_LENGTH = 64;
52
+ /** The server's `durationMs` ceiling (one day). */
53
+ const MAX_DURATION_MS = 24 * 60 * 60 * 1000;
54
+ /**
55
+ * The HTTP status an error carries, read structurally: a numeric `status`
56
+ * property, as the reference CLI's `ApiError` has. `undefined` otherwise.
57
+ */
58
+ function httpStatusOf(error) {
59
+ if (typeof error !== 'object' || error === null)
60
+ return undefined;
61
+ const status = error.status;
62
+ return typeof status === 'number' ? status : undefined;
63
+ }
64
+ function errorClassName(error) {
65
+ return error.name && error.name !== 'Error' ? error.name : error.constructor?.name || 'Error';
66
+ }
67
+ /**
68
+ * An identifier-shaped error type for `error`: its class name, plus an HTTP
69
+ * status (`ApiError.409`) or a string `code` (`Error.ECONNRESET`). Never its
70
+ * message. Characters outside `[A-Za-z0-9_.-]` are replaced, and the result
71
+ * is capped at 64. Never throws.
72
+ *
73
+ * An error with a numeric `status` is an HTTP failure: the status wins over
74
+ * any `code` it also carries (the reference CLI's `ApiError` has both, and its
75
+ * `code` is the server's, not a system errno).
76
+ *
77
+ * @param error - Anything thrown.
78
+ * @returns An identifier such as `ApiError.409` or `Error.ECONNREFUSED`.
79
+ * @stability experimental
80
+ */
81
+ export function errorTypeOf(error) {
82
+ try {
83
+ let name = 'Error';
84
+ let suffix;
85
+ if (error instanceof Error) {
86
+ name = errorClassName(error);
87
+ const status = httpStatusOf(error);
88
+ if (status !== undefined) {
89
+ suffix = String(status);
90
+ }
91
+ else {
92
+ const code = error.code;
93
+ if (typeof code === 'string' || typeof code === 'number')
94
+ suffix = String(code);
95
+ }
96
+ }
97
+ else {
98
+ name = typeof error;
99
+ }
100
+ const raw = suffix === undefined ? name : `${name}.${suffix}`;
101
+ const clean = raw.replace(/[^A-Za-z0-9_.-]/g, '_').slice(0, ERROR_TYPE_MAX_LENGTH);
102
+ return clean.length > 0 ? clean : 'Error';
103
+ }
104
+ catch {
105
+ return 'Error';
106
+ }
107
+ }
108
+ /** Keeps only safe, non-negative-where-required integers the server will take. */
109
+ function cleanAttributes(attributes) {
110
+ if (attributes === undefined)
111
+ return undefined;
112
+ const out = {};
113
+ const { bytes, attempt, exitCode, httpStatus } = attributes;
114
+ if (Number.isSafeInteger(bytes) && bytes >= 0)
115
+ out.bytes = bytes;
116
+ if (Number.isSafeInteger(attempt) && attempt >= 0 && attempt <= 10_000)
117
+ out.attempt = attempt;
118
+ if (Number.isSafeInteger(exitCode) && Math.abs(exitCode) <= 1024)
119
+ out.exitCode = exitCode;
120
+ if (Number.isSafeInteger(httpStatus) && httpStatus >= 100 && httpStatus <= 599)
121
+ out.httpStatus = httpStatus;
122
+ return Object.keys(out).length > 0 ? out : undefined;
123
+ }
124
+ /**
125
+ * The spans of ONE job, recorded as it runs. Every method is synchronous and
126
+ * swallows its own faults: recording must never be the reason a job failed.
127
+ *
128
+ * @stability experimental
129
+ */
130
+ export class JobSpanRecorder {
131
+ jobId;
132
+ now;
133
+ spans = [];
134
+ /**
135
+ * @param jobId - The job every recorded span belongs to.
136
+ * @param now - The clock, Unix epoch milliseconds. Defaults to `Date.now`.
137
+ */
138
+ constructor(jobId, now = Date.now) {
139
+ this.jobId = jobId;
140
+ this.now = now;
141
+ }
142
+ /**
143
+ * Times `work` as phase `name`, recording `ok` or `error`, and returns (or
144
+ * rethrows) exactly what `work` did. `attributes` may be a function of the
145
+ * result, for a phase whose byte count is only known at the end.
146
+ */
147
+ async phase(name, work, attributes) {
148
+ const start = this.now();
149
+ let result;
150
+ try {
151
+ result = await work();
152
+ }
153
+ catch (error) {
154
+ this.record(name, start, 'error', errorTypeOf(error), typeof attributes === 'function' ? undefined : attributes);
155
+ throw error;
156
+ }
157
+ let resolved;
158
+ try {
159
+ resolved = typeof attributes === 'function' ? attributes(result) : attributes;
160
+ }
161
+ catch {
162
+ resolved = undefined;
163
+ }
164
+ this.record(name, start, 'ok', undefined, resolved);
165
+ return result;
166
+ }
167
+ /** Records a phase that has already happened. Never throws. */
168
+ record(name, startTimeUnixMs, status, errorType, attributes) {
169
+ try {
170
+ const durationMs = Math.min(MAX_DURATION_MS, Math.max(0, Math.round(this.now() - startTimeUnixMs)));
171
+ const clean = cleanAttributes(attributes);
172
+ this.spans.push({
173
+ jobId: this.jobId,
174
+ name,
175
+ startTimeUnixMs: Math.round(startTimeUnixMs),
176
+ durationMs,
177
+ status,
178
+ ...(status === 'error' && errorType !== undefined ? { errorType } : {}),
179
+ ...(clean !== undefined ? { attributes: clean } : {}),
180
+ });
181
+ }
182
+ catch {
183
+ // Best-effort; see the header.
184
+ }
185
+ }
186
+ /** Everything recorded so far, in order. */
187
+ drain() {
188
+ return this.spans.splice(0, this.spans.length);
189
+ }
190
+ }
191
+ /**
192
+ * The bounded, best-effort sender. One send in flight at a time; batches of at
193
+ * most `MAX_SPANS_PER_BATCH`; the oldest spans dropped when the queue is full.
194
+ *
195
+ * @example
196
+ * ```ts
197
+ * const relay = new NodeSpanRelay({ api: client, nodeId });
198
+ * const spans = new JobSpanRecorder(job.id);
199
+ * await spans.phase('job.execute', () => run(job));
200
+ * relay.enqueue(spans.drain()); // after the job settled; never awaited on its path
201
+ * ```
202
+ *
203
+ * @extensionPoint hook
204
+ * @stability experimental
205
+ */
206
+ export class NodeSpanRelay {
207
+ api;
208
+ nodeId;
209
+ maxQueuedSpans;
210
+ onDisabled;
211
+ queue = [];
212
+ pumping;
213
+ disabled;
214
+ /** Spans discarded because the queue was full. For tests and diagnostics. */
215
+ droppedForCapacity = 0;
216
+ /** @param options - The client, the node id and the queue bound. */
217
+ constructor(options) {
218
+ this.api = options.api;
219
+ this.nodeId = options.nodeId;
220
+ this.maxQueuedSpans = Math.max(1, options.maxQueuedSpans ?? DEFAULT_MAX_QUEUED_SPANS);
221
+ this.onDisabled = options.onDisabled;
222
+ // A client without the method (a test fake, an embedding that opted
223
+ // out) is simply a relay that is off.
224
+ this.disabled = typeof this.api.telemetry !== 'function';
225
+ }
226
+ /** False once the relay is off: no `telemetry` method, or a 404 seen. */
227
+ get enabled() {
228
+ return !this.disabled;
229
+ }
230
+ /** Spans waiting to be sent. */
231
+ get queued() {
232
+ return this.queue.length;
233
+ }
234
+ /** Queues `spans` and starts sending if idle. Never throws, never awaits. */
235
+ enqueue(spans) {
236
+ if (this.disabled || spans.length === 0)
237
+ return;
238
+ this.queue.push(...spans);
239
+ const overflow = this.queue.length - this.maxQueuedSpans;
240
+ if (overflow > 0) {
241
+ this.queue.splice(0, overflow);
242
+ this.droppedForCapacity += overflow;
243
+ }
244
+ if (this.pumping === undefined) {
245
+ this.pumping = this.pump().finally(() => {
246
+ this.pumping = undefined;
247
+ });
248
+ }
249
+ }
250
+ /** Resolves once the queue is empty (or the relay disabled). Never rejects. */
251
+ async flush() {
252
+ while (this.pumping !== undefined) {
253
+ await this.pumping;
254
+ }
255
+ }
256
+ async pump() {
257
+ while (!this.disabled && this.queue.length > 0) {
258
+ const batch = this.queue.splice(0, MAX_SPANS_PER_BATCH);
259
+ try {
260
+ await this.api.telemetry(this.nodeId, { spans: batch });
261
+ }
262
+ catch (error) {
263
+ const status = httpStatusOf(error);
264
+ if (status === 404) {
265
+ this.disabled = true;
266
+ this.queue.length = 0;
267
+ const serverMessage = error.serverMessage;
268
+ try {
269
+ this.onDisabled?.(`${status}: ${typeof serverMessage === 'string' ? serverMessage : 'Not Found'}`);
270
+ }
271
+ catch {
272
+ // An observer must not break the relay.
273
+ }
274
+ return;
275
+ }
276
+ // Any other failure: this batch is gone. See the header.
277
+ }
278
+ }
279
+ }
280
+ }
281
+ //# sourceMappingURL=node-span-relay.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"node-span-relay.js","sourceRoot":"","sources":["../../src/telemetry/node-span-relay.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,60 @@
1
+ /**
2
+ * The phase spans a node may relay. Mirrors the server's `NODE_SPAN_NAMES`:
3
+ * an enum on the server, so a name not listed here is a 400 for the whole
4
+ * batch. Never add one on this side first.
5
+ *
6
+ * @stability experimental
7
+ */
8
+ export type NodeSpanName = 'job.download' | 'job.execute' | 'job.upload' | 'job.submit' | 'job.secret';
9
+ /**
10
+ * Integer-only, allowlisted span attributes. Mirrors the server's `.strict()`
11
+ * `nodeSpanAttributesSchema`: there is deliberately no string attribute, so no
12
+ * URL, path or credential can ride along in one.
13
+ *
14
+ * @stability experimental
15
+ */
16
+ export interface NodeSpanAttributes {
17
+ /** Bytes moved by the phase. Non-negative. */
18
+ bytes?: number | undefined;
19
+ /** The job's attempt number. 0 to 10,000. */
20
+ attempt?: number | undefined;
21
+ /** A child process's exit code. -1024 to 1024. */
22
+ exitCode?: number | undefined;
23
+ /** The HTTP status of the phase's request. 100 to 599. */
24
+ httpStatus?: number | undefined;
25
+ }
26
+ /**
27
+ * One phase of one job, as `POST /nodes/:id/telemetry` takes it.
28
+ *
29
+ * @stability experimental
30
+ */
31
+ export interface NodeSpan {
32
+ /** The job the phase belongs to. */
33
+ jobId: string;
34
+ /** Which phase. */
35
+ name: NodeSpanName;
36
+ /** When the phase started, Unix epoch milliseconds. */
37
+ startTimeUnixMs: number;
38
+ /** How long it ran, milliseconds, capped at one day. */
39
+ durationMs: number;
40
+ /** Whether the phase succeeded. */
41
+ status: 'ok' | 'error';
42
+ /** An error CLASS or CODE (`MissingJobInputError`, `ApiError.409`), never a message. */
43
+ errorType?: string | undefined;
44
+ /** Integer-only attributes; see {@link NodeSpanAttributes}. */
45
+ attributes?: NodeSpanAttributes | undefined;
46
+ }
47
+ /**
48
+ * What the relay needs from the app's API client: one optional method. An app
49
+ * client whose `telemetry` posts to `/nodes/:id/telemetry` satisfies it
50
+ * structurally. A client without the method is a relay that is off.
51
+ *
52
+ * @stability experimental
53
+ */
54
+ export interface NodeSpanSink {
55
+ /** Sends one batch of at most `MAX_SPANS_PER_BATCH` spans for `nodeId`. */
56
+ telemetry?(nodeId: string, body: {
57
+ spans: NodeSpan[];
58
+ }): Promise<unknown>;
59
+ }
60
+ //# sourceMappingURL=node-span.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"node-span.d.ts","sourceRoot":"","sources":["../../src/telemetry/node-span.ts"],"names":[],"mappings":"AASA;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GAAG,cAAc,GAAG,aAAa,GAAG,YAAY,GAAG,YAAY,GAAG,YAAY,CAAC;AAEvG;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IACjC,8CAA8C;IAC9C,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,6CAA6C;IAC7C,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,kDAAkD;IAClD,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,0DAA0D;IAC1D,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACjC;AAED;;;;GAIG;AACH,MAAM,WAAW,QAAQ;IACvB,oCAAoC;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,mBAAmB;IACnB,IAAI,EAAE,YAAY,CAAC;IACnB,uDAAuD;IACvD,eAAe,EAAE,MAAM,CAAC;IACxB,wDAAwD;IACxD,UAAU,EAAE,MAAM,CAAC;IACnB,mCAAmC;IACnC,MAAM,EAAE,IAAI,GAAG,OAAO,CAAC;IACvB,wFAAwF;IACxF,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,+DAA+D;IAC/D,UAAU,CAAC,EAAE,kBAAkB,GAAG,SAAS,CAAC;CAC7C;AAED;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC3B,2EAA2E;IAC3E,SAAS,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE;QAAE,KAAK,EAAE,QAAQ,EAAE,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC3E"}
@@ -0,0 +1,10 @@
1
+ // =============================================================================
2
+ // The span shapes a worker node relays (issue #608; moved by PP-4.5, #706)
3
+ // =============================================================================
4
+ //
5
+ // Mirrors of the server's `POST /api/nodes/:id/telemetry` contract. They live
6
+ // here, not in the app's API client, so the relay needs no app type at all:
7
+ // what it needs from the client is one optional method (`NodeSpanSink`).
8
+ // =============================================================================
9
+ export {};
10
+ //# sourceMappingURL=node-span.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"node-span.js","sourceRoot":"","sources":["../../src/telemetry/node-span.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,4EAA4E;AAC5E,gFAAgF;AAChF,EAAE;AACF,8EAA8E;AAC9E,4EAA4E;AAC5E,yEAAyE;AACzE,gFAAgF"}
package/package.json CHANGED
@@ -1,6 +1,66 @@
1
1
  {
2
2
  "name": "@marinoscar/platform-cli",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.0-next.3",
4
+ "description": "CLI commands and TUI building blocks of the platform (ESM).",
5
+ "license": "MIT",
6
+ "type": "module",
7
+ "sideEffects": false,
8
+ "engines": {
9
+ "node": ">=20"
10
+ },
11
+ "repository": {
12
+ "type": "git",
13
+ "url": "git+https://github.com/marinoscar/EnterpriseAppBase.git",
14
+ "directory": "packages/platform-cli"
15
+ },
16
+ "publishConfig": {
17
+ "access": "public"
18
+ },
19
+ "main": "./dist/index.js",
20
+ "types": "./dist/index.d.ts",
21
+ "exports": {
22
+ ".": {
23
+ "types": "./dist/index.d.ts",
24
+ "default": "./dist/index.js"
25
+ },
26
+ "./core": {
27
+ "types": "./dist/core/index.d.ts",
28
+ "default": "./dist/core/index.js"
29
+ },
30
+ "./telemetry": {
31
+ "types": "./dist/telemetry/index.d.ts",
32
+ "default": "./dist/telemetry/index.js"
33
+ },
34
+ "./package.json": "./package.json"
35
+ },
36
+ "files": [
37
+ "dist",
38
+ "README.md",
39
+ "CHANGELOG.md",
40
+ "LICENSE"
41
+ ],
42
+ "scripts": {
43
+ "prebuild": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
44
+ "prepack": "node ../../scripts/copy-license.mjs",
45
+ "build": "tsc -p tsconfig.build.json",
46
+ "dev": "tsc -p tsconfig.build.json --watch --preserveWatchOutput",
47
+ "typecheck": "tsc --noEmit",
48
+ "docs": "typedoc --options typedoc.json",
49
+ "test": "vitest",
50
+ "test:run": "vitest run"
51
+ },
52
+ "peerDependencies": {
53
+ "commander": "^14.0.2",
54
+ "ink": "^7.1.1",
55
+ "react": "^19.2.8"
56
+ },
57
+ "devDependencies": {
58
+ "@types/node": "^22.15.32",
59
+ "@types/react": "^19.2.18",
60
+ "commander": "^14.0.2",
61
+ "ink": "^7.1.1",
62
+ "react": "^19.2.8",
63
+ "typescript": "^6.0.3",
64
+ "vitest": "^4.1.8"
65
+ }
66
+ }