@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,123 @@
1
+ import { randomBytes } from 'node:crypto';
2
+ // =============================================================================
3
+ // Pure helpers for environment values (PP-4.5, #706)
4
+ // =============================================================================
5
+ //
6
+ // Moved verbatim from the reference CLI's `deploy/env-metadata.ts`, which
7
+ // re-exports them so no import site in the app changes. They hold no state and
8
+ // read no file: generating a value, recognising a template placeholder and
9
+ // validating the few shapes the metadata asks for.
10
+ // =============================================================================
11
+ /**
12
+ * 32 bytes from the CSPRNG, standard base64 (AES-256 keys, JWT secrets).
13
+ *
14
+ * Never `Math.random`, and never a shelled-out `openssl`: a CLI cannot assume
15
+ * what is installed, and this must behave identically on a minimal container.
16
+ *
17
+ * @returns 44 base64 characters.
18
+ * @stability experimental
19
+ */
20
+ export function generateBase64Key() {
21
+ return randomBytes(32).toString('base64');
22
+ }
23
+ /**
24
+ * 32 bytes from the CSPRNG as 64 lowercase hex characters: `[0-9a-f]` only.
25
+ *
26
+ * @returns 64 hex characters.
27
+ * @stability experimental
28
+ */
29
+ export function generateHexKey() {
30
+ return randomBytes(32).toString('hex');
31
+ }
32
+ /**
33
+ * Generates a value of the given kind.
34
+ *
35
+ * @param kind - `hex-32` or `base64-32`.
36
+ * @returns A fresh random value.
37
+ * @stability experimental
38
+ */
39
+ export function generateValue(kind) {
40
+ return kind === 'hex-32' ? generateHexKey() : generateBase64Key();
41
+ }
42
+ /**
43
+ * True when a value is still a template placeholder rather than something
44
+ * anybody chose: the template's own default for the key, or the `change-me` /
45
+ * `your-` spellings `.env.example` uses for credentials.
46
+ *
47
+ * @param value - The current value.
48
+ * @param templateDefault - The template's default for the key, if any.
49
+ * @returns Whether the value is a placeholder.
50
+ * @stability experimental
51
+ */
52
+ export function isPlaceholderValue(value, templateDefault) {
53
+ if (templateDefault !== undefined && templateDefault !== '' && value === templateDefault) {
54
+ return true;
55
+ }
56
+ return /^change-me|^your-/i.test(value);
57
+ }
58
+ /**
59
+ * Whether an `autoGenerate` key's current value must be replaced: it is
60
+ * missing, blank or still a placeholder. A real value is never replaced.
61
+ *
62
+ * @param current - The current value, `undefined` when the key is absent.
63
+ * @param templateDefault - The template's default for the key, if any.
64
+ * @returns Whether to generate a new value.
65
+ * @stability experimental
66
+ */
67
+ export function needsAutoGenerate(current, templateDefault) {
68
+ return current === undefined || current === '' || isPlaceholderValue(current, templateDefault);
69
+ }
70
+ /**
71
+ * AES-256 needs exactly 32 bytes. A key that merely LOOKS like base64 passes
72
+ * startup and then fails the first time a credential is saved, which is a long
73
+ * way from where the mistake was made. Empty is allowed: the API boots without
74
+ * the key and only refuses to SAVE a credential.
75
+ *
76
+ * @param value - The candidate key.
77
+ * @returns A message when the value is unusable, `undefined` when it is fine.
78
+ * @stability experimental
79
+ */
80
+ export function validateBase64Key32(value) {
81
+ if (value === '')
82
+ return undefined;
83
+ let decoded;
84
+ try {
85
+ decoded = Buffer.from(value, 'base64');
86
+ }
87
+ catch {
88
+ return 'must be base64';
89
+ }
90
+ // Buffer.from is lenient, so round-trip to catch input that is not base64 at
91
+ // all rather than silently accepting a truncated decode.
92
+ if (decoded.toString('base64').replace(/=+$/, '') !== value.replace(/=+$/, '')) {
93
+ return 'must be valid base64 (generate with: openssl rand -base64 32)';
94
+ }
95
+ if (decoded.length !== 32) {
96
+ return `must decode to exactly 32 bytes for AES-256 (got ${decoded.length})`;
97
+ }
98
+ return undefined;
99
+ }
100
+ /**
101
+ * Accepts an email address.
102
+ *
103
+ * @param value - The candidate address.
104
+ * @returns A message when the value is not an address, `undefined` when it is.
105
+ * @stability experimental
106
+ */
107
+ export function validateEmail(value) {
108
+ return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value) ? undefined : 'must be an email address';
109
+ }
110
+ /**
111
+ * Accepts a TCP port number, 1 to 65535.
112
+ *
113
+ * @param value - The candidate port.
114
+ * @returns A message when the value is not a port, `undefined` when it is.
115
+ * @stability experimental
116
+ */
117
+ export function validatePort(value) {
118
+ const port = Number(value);
119
+ return Number.isInteger(port) && port > 0 && port < 65536
120
+ ? undefined
121
+ : 'must be a port number between 1 and 65535';
122
+ }
123
+ //# sourceMappingURL=env-values.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"env-values.js","sourceRoot":"","sources":["../../src/core/env-values.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAI1C,gFAAgF;AAChF,sDAAsD;AACtD,gFAAgF;AAChF,EAAE;AACF,0EAA0E;AAC1E,+EAA+E;AAC/E,2EAA2E;AAC3E,mDAAmD;AACnD,gFAAgF;AAEhF;;;;;;;;GAQG;AACH,MAAM,UAAU,iBAAiB;IAC/B,OAAO,WAAW,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;AAC5C,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc;IAC5B,OAAO,WAAW,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AACzC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,IAAkB;IAC9C,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,cAAc,EAAE,CAAC,CAAC,CAAC,iBAAiB,EAAE,CAAC;AACpE,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAa,EAAE,eAAwB;IACxE,IAAI,eAAe,KAAK,SAAS,IAAI,eAAe,KAAK,EAAE,IAAI,KAAK,KAAK,eAAe,EAAE,CAAC;QACzF,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,oBAAoB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AAC1C,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAA2B,EAAE,eAAwB;IACrF,OAAO,OAAO,KAAK,SAAS,IAAI,OAAO,KAAK,EAAE,IAAI,kBAAkB,CAAC,OAAO,EAAE,eAAe,CAAC,CAAC;AACjG,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAa;IAC/C,IAAI,KAAK,KAAK,EAAE;QAAE,OAAO,SAAS,CAAC;IAEnC,IAAI,OAAe,CAAC;IACpB,IAAI,CAAC;QACH,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IACzC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,gBAAgB,CAAC;IAC1B,CAAC;IACD,6EAA6E;IAC7E,yDAAyD;IACzD,IAAI,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,EAAE,CAAC;QAC/E,OAAO,+DAA+D,CAAC;IACzE,CAAC;IACD,IAAI,OAAO,CAAC,MAAM,KAAK,EAAE,EAAE,CAAC;QAC1B,OAAO,oDAAoD,OAAO,CAAC,MAAM,GAAG,CAAC;IAC/E,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,KAAa;IACzC,OAAO,4BAA4B,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,0BAA0B,CAAC;AAC3F,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAC,KAAa;IACxC,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;IAC3B,OAAO,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,IAAI,GAAG,CAAC,IAAI,IAAI,GAAG,KAAK;QACvD,CAAC,CAAC,SAAS;QACX,CAAC,CAAC,2CAA2C,CAAC;AAClD,CAAC"}
@@ -0,0 +1,6 @@
1
+ export { applyRegisteredCommands, listRegisteredCommands, registerCliCommand, resetCommandRegistryForTests, } from './command-registry.js';
2
+ export type { CliCommandRegistration } from './command-registry.js';
3
+ export { listEnvSpecFragments, registerEnvSpecFragment, resetEnvSpecRegistryForTests, resolveEnvMetadata, } from './env-spec-registry.js';
4
+ export type { DeriveContext, EnvSpecFragment, EnvVarMetadata, GenerateKind } from './env-spec-registry.js';
5
+ export { generateBase64Key, generateHexKey, generateValue, isPlaceholderValue, needsAutoGenerate, validateBase64Key32, validateEmail, validatePort, } from './env-values.js';
6
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,uBAAuB,EACvB,sBAAsB,EACtB,kBAAkB,EAClB,4BAA4B,GAC7B,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAEpE,OAAO,EACL,oBAAoB,EACpB,uBAAuB,EACvB,4BAA4B,EAC5B,kBAAkB,GACnB,MAAM,wBAAwB,CAAC;AAChC,YAAY,EAAE,aAAa,EAAE,eAAe,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAE3G,OAAO,EACL,iBAAiB,EACjB,cAAc,EACd,aAAa,EACb,kBAAkB,EAClB,iBAAiB,EACjB,mBAAmB,EACnB,aAAa,EACb,YAAY,GACb,MAAM,iBAAiB,CAAC"}
@@ -0,0 +1,6 @@
1
+ // `@marinoscar/platform-cli/core`: the CLI's registries and the pure helpers
2
+ // behind env-key metadata (PP-4.5, #706). The seed of #715.
3
+ export { applyRegisteredCommands, listRegisteredCommands, registerCliCommand, resetCommandRegistryForTests, } from './command-registry.js';
4
+ export { listEnvSpecFragments, registerEnvSpecFragment, resetEnvSpecRegistryForTests, resolveEnvMetadata, } from './env-spec-registry.js';
5
+ export { generateBase64Key, generateHexKey, generateValue, isPlaceholderValue, needsAutoGenerate, validateBase64Key32, validateEmail, validatePort, } from './env-values.js';
6
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,4DAA4D;AAE5D,OAAO,EACL,uBAAuB,EACvB,sBAAsB,EACtB,kBAAkB,EAClB,4BAA4B,GAC7B,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EACL,oBAAoB,EACpB,uBAAuB,EACvB,4BAA4B,EAC5B,kBAAkB,GACnB,MAAM,wBAAwB,CAAC;AAGhC,OAAO,EACL,iBAAiB,EACjB,cAAc,EACd,aAAa,EACb,kBAAkB,EAClB,iBAAiB,EACjB,mBAAmB,EACnB,aAAa,EACb,YAAY,GACb,MAAM,iBAAiB,CAAC"}
@@ -0,0 +1,11 @@
1
+ /**
2
+ * The npm name of this package, which holds CLI commands and TUI building blocks of the platform.
3
+ *
4
+ * A placeholder export so the build, the pack check and the smoke imports in
5
+ * CI have something to load end to end. Real slices arrive as subpath
6
+ * exports (`@marinoscar/platform-cli/<slice>`).
7
+ *
8
+ * @stability experimental
9
+ */
10
+ export declare const PLATFORM_PACKAGE: "@marinoscar/platform-cli";
11
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB,EAAG,0BAAmC,CAAC"}
package/dist/index.js ADDED
@@ -0,0 +1,11 @@
1
+ /**
2
+ * The npm name of this package, which holds CLI commands and TUI building blocks of the platform.
3
+ *
4
+ * A placeholder export so the build, the pack check and the smoke imports in
5
+ * CI have something to load end to end. Real slices arrive as subpath
6
+ * exports (`@marinoscar/platform-cli/<slice>`).
7
+ *
8
+ * @stability experimental
9
+ */
10
+ export const PLATFORM_PACKAGE = '@marinoscar/platform-cli';
11
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,0BAAmC,CAAC"}
@@ -0,0 +1,47 @@
1
+ import type { EnvSpecFragment, EnvVarMetadata } from '../core/index.js';
2
+ /**
3
+ * The feature group every telemetry key belongs to. A host CLI that gates
4
+ * keys by group must know it.
5
+ *
6
+ * @stability experimental
7
+ */
8
+ export type TelemetryEnvGroup = 'observability';
9
+ /**
10
+ * One telemetry key's annotation: the platform's `EnvVarMetadata`, always in
11
+ * {@link TelemetryEnvGroup}.
12
+ *
13
+ * @stability experimental
14
+ */
15
+ export interface TelemetryEnvVarMetadata extends EnvVarMetadata {
16
+ /** Always `observability`. */
17
+ group: TelemetryEnvGroup;
18
+ }
19
+ /**
20
+ * The shape of {@link telemetryEnvSpecFragment}: an `EnvSpecFragment` whose
21
+ * entries all name {@link TelemetryEnvGroup}, so a host can check at compile
22
+ * time that it knows the group.
23
+ *
24
+ * @stability experimental
25
+ */
26
+ export interface TelemetryEnvSpecFragment extends EnvSpecFragment {
27
+ /** Always `telemetry`. */
28
+ readonly id: 'telemetry';
29
+ /** Annotations by key; every entry carries `group: 'observability'`. */
30
+ readonly metadata: Readonly<Record<string, TelemetryEnvVarMetadata>>;
31
+ }
32
+ /**
33
+ * The env-spec fragment for the telemetry stack: the PostgreSQL monitor login,
34
+ * the OpenTelemetry exporter settings and the GreptimeDB store.
35
+ *
36
+ * Register it once with `registerEnvSpecFragment(telemetryEnvSpecFragment)`.
37
+ *
38
+ * @example
39
+ * ```ts
40
+ * registerEnvSpecFragment(telemetryEnvSpecFragment); // the reference CLI: platform-host/register.ts
41
+ * ```
42
+ *
43
+ * @extensionPoint option
44
+ * @stability experimental
45
+ */
46
+ export declare const telemetryEnvSpecFragment: TelemetryEnvSpecFragment;
47
+ //# sourceMappingURL=env-fragment.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"env-fragment.d.ts","sourceRoot":"","sources":["../../src/telemetry/env-fragment.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAYxE;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GAAG,eAAe,CAAC;AAEhD;;;;;GAKG;AACH,MAAM,WAAW,uBAAwB,SAAQ,cAAc;IAC7D,8BAA8B;IAC9B,KAAK,EAAE,iBAAiB,CAAC;CAC1B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,wBAAyB,SAAQ,eAAe;IAC/D,0BAA0B;IAC1B,QAAQ,CAAC,EAAE,EAAE,WAAW,CAAC;IACzB,wEAAwE;IACxE,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,uBAAuB,CAAC,CAAC,CAAC;CACtE;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,wBAAwB,EAAE,wBA2DtC,CAAC"}
@@ -0,0 +1,73 @@
1
+ /**
2
+ * The env-spec fragment for the telemetry stack: the PostgreSQL monitor login,
3
+ * the OpenTelemetry exporter settings and the GreptimeDB store.
4
+ *
5
+ * Register it once with `registerEnvSpecFragment(telemetryEnvSpecFragment)`.
6
+ *
7
+ * @example
8
+ * ```ts
9
+ * registerEnvSpecFragment(telemetryEnvSpecFragment); // the reference CLI: platform-host/register.ts
10
+ * ```
11
+ *
12
+ * @extensionPoint option
13
+ * @stability experimental
14
+ */
15
+ export const telemetryEnvSpecFragment = {
16
+ id: 'telemetry',
17
+ metadata: {
18
+ // The telemetry collector's PostgreSQL login (issue #598), a pg_monitor role
19
+ // that must already exist on the server - so never generated, only asked.
20
+ // Asked as a PAIR (both `essential`) because a password asked on its own
21
+ // would be paired with POSTGRES_USER, which it does not belong to. Blank is
22
+ // a real answer for both: telemetry.compose.yml then falls back to the
23
+ // API's own POSTGRES_USER / POSTGRES_PASSWORD, which works on any server
24
+ // without a new role. `allowBlank` is what keeps that blank from failing an
25
+ // unattended install, and from failing `deploy update` on a deployment
26
+ // written before these keys existed.
27
+ POSTGRES_MONITOR_USER: { group: 'observability', essential: true, allowBlank: true },
28
+ POSTGRES_MONITOR_PASSWORD: {
29
+ group: 'observability',
30
+ essential: true,
31
+ secret: true,
32
+ allowBlank: true,
33
+ },
34
+ OTEL_ENABLED: { group: 'observability' },
35
+ OTEL_EXPORTER_OTLP_ENDPOINT: { group: 'observability' },
36
+ OTEL_SERVICE_NAME: { group: 'observability' },
37
+ // GreptimeDB telemetry store (telemetry.compose.yml). Three accounts with
38
+ // three privileges: the collector writes, the explorer / AI assistant / BI
39
+ // tools read, and only the retention (TTL) setting uses the admin account.
40
+ //
41
+ // The passwords are generated, never asked (#567), and as hex: they are
42
+ // embedded in GreptimeDB's `user=password,...` provider string, so `,`, `=`
43
+ // and `:` must never appear in them.
44
+ GREPTIME_HOST: { group: 'observability' },
45
+ GREPTIME_HTTP_PORT: { group: 'observability' },
46
+ GREPTIME_PG_PORT: { group: 'observability' },
47
+ // Loopback host port vps.telemetry.compose.yml publishes the PG protocol on.
48
+ GREPTIME_BIND_PG_PORT: { group: 'observability' },
49
+ GREPTIME_DB: { group: 'observability' },
50
+ GREPTIME_WRITER_USER: { group: 'observability' },
51
+ GREPTIME_WRITER_PASSWORD: {
52
+ group: 'observability',
53
+ secret: true,
54
+ generate: 'hex-32',
55
+ autoGenerate: true,
56
+ },
57
+ GREPTIME_READER_USER: { group: 'observability' },
58
+ GREPTIME_READER_PASSWORD: {
59
+ group: 'observability',
60
+ secret: true,
61
+ generate: 'hex-32',
62
+ autoGenerate: true,
63
+ },
64
+ GREPTIME_ADMIN_USER: { group: 'observability' },
65
+ GREPTIME_ADMIN_PASSWORD: {
66
+ group: 'observability',
67
+ secret: true,
68
+ generate: 'hex-32',
69
+ autoGenerate: true,
70
+ },
71
+ },
72
+ };
73
+ //# sourceMappingURL=env-fragment.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"env-fragment.js","sourceRoot":"","sources":["../../src/telemetry/env-fragment.ts"],"names":[],"mappings":"AA6CA;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAA6B;IAChE,EAAE,EAAE,WAAW;IACf,QAAQ,EAAE;QACR,6EAA6E;QAC7E,0EAA0E;QAC1E,yEAAyE;QACzE,4EAA4E;QAC5E,uEAAuE;QACvE,yEAAyE;QACzE,4EAA4E;QAC5E,uEAAuE;QACvE,qCAAqC;QACrC,qBAAqB,EAAE,EAAE,KAAK,EAAE,eAAe,EAAE,SAAS,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE;QACpF,yBAAyB,EAAE;YACzB,KAAK,EAAE,eAAe;YACtB,SAAS,EAAE,IAAI;YACf,MAAM,EAAE,IAAI;YACZ,UAAU,EAAE,IAAI;SACjB;QAED,YAAY,EAAE,EAAE,KAAK,EAAE,eAAe,EAAE;QACxC,2BAA2B,EAAE,EAAE,KAAK,EAAE,eAAe,EAAE;QACvD,iBAAiB,EAAE,EAAE,KAAK,EAAE,eAAe,EAAE;QAE7C,0EAA0E;QAC1E,2EAA2E;QAC3E,2EAA2E;QAC3E,EAAE;QACF,wEAAwE;QACxE,4EAA4E;QAC5E,qCAAqC;QACrC,aAAa,EAAE,EAAE,KAAK,EAAE,eAAe,EAAE;QACzC,kBAAkB,EAAE,EAAE,KAAK,EAAE,eAAe,EAAE;QAC9C,gBAAgB,EAAE,EAAE,KAAK,EAAE,eAAe,EAAE;QAC5C,6EAA6E;QAC7E,qBAAqB,EAAE,EAAE,KAAK,EAAE,eAAe,EAAE;QACjD,WAAW,EAAE,EAAE,KAAK,EAAE,eAAe,EAAE;QACvC,oBAAoB,EAAE,EAAE,KAAK,EAAE,eAAe,EAAE;QAChD,wBAAwB,EAAE;YACxB,KAAK,EAAE,eAAe;YACtB,MAAM,EAAE,IAAI;YACZ,QAAQ,EAAE,QAAQ;YAClB,YAAY,EAAE,IAAI;SACnB;QACD,oBAAoB,EAAE,EAAE,KAAK,EAAE,eAAe,EAAE;QAChD,wBAAwB,EAAE;YACxB,KAAK,EAAE,eAAe;YACtB,MAAM,EAAE,IAAI;YACZ,QAAQ,EAAE,QAAQ;YAClB,YAAY,EAAE,IAAI;SACnB;QACD,mBAAmB,EAAE,EAAE,KAAK,EAAE,eAAe,EAAE;QAC/C,uBAAuB,EAAE;YACvB,KAAK,EAAE,eAAe;YACtB,MAAM,EAAE,IAAI;YACZ,QAAQ,EAAE,QAAQ;YAClB,YAAY,EAAE,IAAI;SACnB;KACF;CACF,CAAC"}
@@ -0,0 +1,6 @@
1
+ export { DEFAULT_MAX_QUEUED_SPANS, JobSpanRecorder, MAX_SPANS_PER_BATCH, NodeSpanRelay, errorTypeOf, } from './node-span-relay.js';
2
+ export type { NodeSpanRelayOptions } from './node-span-relay.js';
3
+ export type { NodeSpan, NodeSpanAttributes, NodeSpanName, NodeSpanSink } from './node-span.js';
4
+ export { telemetryEnvSpecFragment } from './env-fragment.js';
5
+ export type { TelemetryEnvGroup, TelemetryEnvSpecFragment, TelemetryEnvVarMetadata } from './env-fragment.js';
6
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/telemetry/index.ts"],"names":[],"mappings":"AAIA,OAAO,EACL,wBAAwB,EACxB,eAAe,EACf,mBAAmB,EACnB,aAAa,EACb,WAAW,GACZ,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AACjE,YAAY,EAAE,QAAQ,EAAE,kBAAkB,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC/F,OAAO,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAC;AAC7D,YAAY,EAAE,iBAAiB,EAAE,wBAAwB,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC"}
@@ -0,0 +1,6 @@
1
+ // `@marinoscar/platform-cli/telemetry`: the worker node's job-phase span relay
2
+ // and the telemetry stack's env-key metadata (PP-4.5, #706). #707 completes
3
+ // the slice.
4
+ export { DEFAULT_MAX_QUEUED_SPANS, JobSpanRecorder, MAX_SPANS_PER_BATCH, NodeSpanRelay, errorTypeOf, } from './node-span-relay.js';
5
+ export { telemetryEnvSpecFragment } from './env-fragment.js';
6
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/telemetry/index.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,4EAA4E;AAC5E,aAAa;AAEb,OAAO,EACL,wBAAwB,EACxB,eAAe,EACf,mBAAmB,EACnB,aAAa,EACb,WAAW,GACZ,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAC"}
@@ -0,0 +1,107 @@
1
+ import type { NodeSpan, NodeSpanAttributes, NodeSpanName, NodeSpanSink } from './node-span.js';
2
+ /**
3
+ * Spans the server accepts per request. Mirrors `MAX_NODE_SPANS_PER_REQUEST`.
4
+ *
5
+ * @stability experimental
6
+ */
7
+ export declare const MAX_SPANS_PER_BATCH = 50;
8
+ /**
9
+ * Spans held while waiting to send. Past this the OLDEST are dropped.
10
+ *
11
+ * @stability experimental
12
+ */
13
+ export declare const DEFAULT_MAX_QUEUED_SPANS = 500;
14
+ /**
15
+ * An identifier-shaped error type for `error`: its class name, plus an HTTP
16
+ * status (`ApiError.409`) or a string `code` (`Error.ECONNRESET`). Never its
17
+ * message. Characters outside `[A-Za-z0-9_.-]` are replaced, and the result
18
+ * is capped at 64. Never throws.
19
+ *
20
+ * An error with a numeric `status` is an HTTP failure: the status wins over
21
+ * any `code` it also carries (the reference CLI's `ApiError` has both, and its
22
+ * `code` is the server's, not a system errno).
23
+ *
24
+ * @param error - Anything thrown.
25
+ * @returns An identifier such as `ApiError.409` or `Error.ECONNREFUSED`.
26
+ * @stability experimental
27
+ */
28
+ export declare function errorTypeOf(error: unknown): string;
29
+ /**
30
+ * The spans of ONE job, recorded as it runs. Every method is synchronous and
31
+ * swallows its own faults: recording must never be the reason a job failed.
32
+ *
33
+ * @stability experimental
34
+ */
35
+ export declare class JobSpanRecorder {
36
+ readonly jobId: string;
37
+ private readonly now;
38
+ private readonly spans;
39
+ /**
40
+ * @param jobId - The job every recorded span belongs to.
41
+ * @param now - The clock, Unix epoch milliseconds. Defaults to `Date.now`.
42
+ */
43
+ constructor(jobId: string, now?: () => number);
44
+ /**
45
+ * Times `work` as phase `name`, recording `ok` or `error`, and returns (or
46
+ * rethrows) exactly what `work` did. `attributes` may be a function of the
47
+ * result, for a phase whose byte count is only known at the end.
48
+ */
49
+ phase<T>(name: NodeSpanName, work: () => Promise<T>, attributes?: NodeSpanAttributes | ((result: T) => NodeSpanAttributes | undefined)): Promise<T>;
50
+ /** Records a phase that has already happened. Never throws. */
51
+ record(name: NodeSpanName, startTimeUnixMs: number, status: 'ok' | 'error', errorType?: string, attributes?: NodeSpanAttributes): void;
52
+ /** Everything recorded so far, in order. */
53
+ drain(): NodeSpan[];
54
+ }
55
+ /**
56
+ * Options for {@link NodeSpanRelay}.
57
+ *
58
+ * @stability experimental
59
+ */
60
+ export interface NodeSpanRelayOptions {
61
+ /** The app's API client, or anything with its optional `telemetry` method. */
62
+ api: NodeSpanSink;
63
+ /** The node the spans are relayed for. */
64
+ nodeId: string;
65
+ /** Spans held while waiting to send. Defaults to `DEFAULT_MAX_QUEUED_SPANS`. */
66
+ maxQueuedSpans?: number | undefined;
67
+ /** Called ONCE, when a 404 disables the relay for this process. */
68
+ onDisabled?: ((reason: string) => void) | undefined;
69
+ }
70
+ /**
71
+ * The bounded, best-effort sender. One send in flight at a time; batches of at
72
+ * most `MAX_SPANS_PER_BATCH`; the oldest spans dropped when the queue is full.
73
+ *
74
+ * @example
75
+ * ```ts
76
+ * const relay = new NodeSpanRelay({ api: client, nodeId });
77
+ * const spans = new JobSpanRecorder(job.id);
78
+ * await spans.phase('job.execute', () => run(job));
79
+ * relay.enqueue(spans.drain()); // after the job settled; never awaited on its path
80
+ * ```
81
+ *
82
+ * @extensionPoint hook
83
+ * @stability experimental
84
+ */
85
+ export declare class NodeSpanRelay {
86
+ private readonly api;
87
+ private readonly nodeId;
88
+ private readonly maxQueuedSpans;
89
+ private readonly onDisabled;
90
+ private readonly queue;
91
+ private pumping;
92
+ private disabled;
93
+ /** Spans discarded because the queue was full. For tests and diagnostics. */
94
+ droppedForCapacity: number;
95
+ /** @param options - The client, the node id and the queue bound. */
96
+ constructor(options: NodeSpanRelayOptions);
97
+ /** False once the relay is off: no `telemetry` method, or a 404 seen. */
98
+ get enabled(): boolean;
99
+ /** Spans waiting to be sent. */
100
+ get queued(): number;
101
+ /** Queues `spans` and starts sending if idle. Never throws, never awaits. */
102
+ enqueue(spans: NodeSpan[]): void;
103
+ /** Resolves once the queue is empty (or the relay disabled). Never rejects. */
104
+ flush(): Promise<void>;
105
+ private pump;
106
+ }
107
+ //# sourceMappingURL=node-span-relay.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"node-span-relay.d.ts","sourceRoot":"","sources":["../../src/telemetry/node-span-relay.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,kBAAkB,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAwC/F;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,KAAK,CAAC;AAEtC;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,MAAM,CAAC;AAsB5C;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAwBlD;AAcD;;;;;GAKG;AACH,qBAAa,eAAe;IAQxB,QAAQ,CAAC,KAAK,EAAE,MAAM;IACtB,OAAO,CAAC,QAAQ,CAAC,GAAG;IARtB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAkB;IAExC;;;OAGG;gBAEQ,KAAK,EAAE,MAAM,EACL,GAAG,GAAE,MAAM,MAAiB;IAG/C;;;;OAIG;IACG,KAAK,CAAC,CAAC,EACX,IAAI,EAAE,YAAY,EAClB,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACtB,UAAU,CAAC,EAAE,kBAAkB,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,kBAAkB,GAAG,SAAS,CAAC,GAChF,OAAO,CAAC,CAAC,CAAC;IAmBb,+DAA+D;IAC/D,MAAM,CACJ,IAAI,EAAE,YAAY,EAClB,eAAe,EAAE,MAAM,EACvB,MAAM,EAAE,IAAI,GAAG,OAAO,EACtB,SAAS,CAAC,EAAE,MAAM,EAClB,UAAU,CAAC,EAAE,kBAAkB,GAC9B,IAAI;IAkBP,4CAA4C;IAC5C,KAAK,IAAI,QAAQ,EAAE;CAGpB;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,8EAA8E;IAC9E,GAAG,EAAE,YAAY,CAAC;IAClB,0CAA0C;IAC1C,MAAM,EAAE,MAAM,CAAC;IACf,gFAAgF;IAChF,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,mEAAmE;IACnE,UAAU,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC;CACrD;AAED;;;;;;;;;;;;;;GAcG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAyC;IACpE,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAkB;IACxC,OAAO,CAAC,OAAO,CAA4B;IAC3C,OAAO,CAAC,QAAQ,CAAU;IAE1B,6EAA6E;IAC7E,kBAAkB,SAAK;IAEvB,oEAAoE;gBACxD,OAAO,EAAE,oBAAoB;IAUzC,yEAAyE;IACzE,IAAI,OAAO,IAAI,OAAO,CAErB;IAED,gCAAgC;IAChC,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED,6EAA6E;IAC7E,OAAO,CAAC,KAAK,EAAE,QAAQ,EAAE,GAAG,IAAI;IAehC,+EAA+E;IACzE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;YAMd,IAAI;CAsBnB"}