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

package/dist/telemetry/stack/stack-agent.client.js

@@ -0,0 +1,208 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var StackAgentClient_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StackAgentClient = exports.stackServiceSchema = exports.STACK_SERVICE_HEALTH = exports.STACK_SERVICE_STATES = exports.STACK_AGENT_UP_TIMEOUT_MS = exports.STACK_AGENT_STATUS_TIMEOUT_MS = void 0;
+exports.describeFetchError = describeFetchError;
+const common_1 = require("@nestjs/common");
+const config_1 = require("@nestjs/config");
+const telemetry_1 = require("@marinoscar/platform-contract/telemetry");
+const zod_1 = require("zod");
+// =============================================================================
+// StackAgentClient — the API's side of the VPS `stack-agent` sidecar
+// (issue #567, epic #528)
+// =============================================================================
+//
+// On a VPS deployment a small sidecar (`stack-agent`) holds the Docker socket
+// and exposes, on the internal network only:
+//
+//   GET  /health              → { ok: true }                      (no auth)
+//   GET  /v1/telemetry        → { services: [{ name, state, health }] }
+//   POST /v1/telemetry/up     → 200 { ok, exitCode, output }  | 500 { ok: false, … }
+//                               409 { error: 'busy' } | 503 { error: 'not_configured' }
+//
+// This client is the ONLY code that talks to it. It never throws: every
+// outcome is a typed result, so callers (the admin status read, the deploy
+// job) decide what a failure means for them.
+//
+// CONFIGURATION IS DEPLOYMENT INFRASTRUCTURE. `STACK_AGENT_URL` and
+// `STACK_AGENT_TOKEN` (`configuration.ts` → `stackAgent`) are set by the
+// compose stack that runs both containers — like the database credentials,
+// not a runtime setting. Either missing (every development machine) means
+// `not_configured`, and no request is made.
+//
+// ⚠ THE TOKEN IS NEVER LOGGED, RETURNED OR PUT IN AN ERROR MESSAGE. It is read
+// once, here, and used only in the `Authorization` header. Messages carry the
+// URL's origin and the failure, never headers.
+// =============================================================================
+/** Ceiling on a status read. The admin page waits on it. */
+exports.STACK_AGENT_STATUS_TIMEOUT_MS = 5_000;
+/**
+ * Ceiling on `POST /v1/telemetry/up`. The agent may pull images, which can
+ * take up to ten minutes; one more minute of slack, and still well inside the
+ * deploy job's 15-minute `maxRuntimeMs`.
+ */
+exports.STACK_AGENT_UP_TIMEOUT_MS = 11 * 60 * 1000;
+// The container states and health values are part of the wire
+// (`GET /api/admin/telemetry/stack`), so they live in
+// `@marinoscar/platform-contract/telemetry` (#702).
+exports.STACK_SERVICE_STATES = telemetry_1.TELEMETRY_STACK_SERVICE_STATES;
+exports.STACK_SERVICE_HEALTH = telemetry_1.TELEMETRY_STACK_SERVICE_HEALTH;
+exports.stackServiceSchema = zod_1.z.object({
+    name: zod_1.z.string().min(1),
+    state: zod_1.z.enum(exports.STACK_SERVICE_STATES),
+    health: zod_1.z.enum(exports.STACK_SERVICE_HEALTH).nullable(),
+});
+const telemetryStatusBodySchema = zod_1.z.object({ services: zod_1.z.array(exports.stackServiceSchema) });
+const upBodySchema = zod_1.z.object({
+    ok: zod_1.z.boolean().optional(),
+    exitCode: zod_1.z.number().int().nullable().optional(),
+    output: zod_1.z.string().optional(),
+    error: zod_1.z.string().optional(),
+});
+let StackAgentClient = StackAgentClient_1 = class StackAgentClient {
+    logger = new common_1.Logger(StackAgentClient_1.name);
+    baseUrl;
+    token;
+    /** Overridable in tests; the Node 24 global otherwise. */
+    fetchImpl = (input, init) => fetch(input, init);
+    constructor(config) {
+        const raw = config.get('stackAgent') ?? {};
+        this.baseUrl = (raw.url ?? '').trim().replace(/\/+$/, '');
+        this.token = (raw.token ?? '').trim();
+    }
+    /** Both `STACK_AGENT_URL` and `STACK_AGENT_TOKEN` are set. */
+    isConfigured() {
+        return this.baseUrl !== '' && this.token !== '';
+    }
+    /** `GET /v1/telemetry` — the state of each telemetry service. Never throws. */
+    async telemetryStatus() {
+        const response = await this.request('GET', '/v1/telemetry', exports.STACK_AGENT_STATUS_TIMEOUT_MS);
+        if (!isResponse(response))
+            return response;
+        if (response.status === 401 || response.status === 403)
+            return unauthorized(response.status);
+        if (response.status === 503)
+            return notConfiguredByAgent();
+        if (!response.ok) {
+            return { ok: false, error: 'failed', message: `stack-agent answered HTTP ${response.status}` };
+        }
+        const parsed = telemetryStatusBodySchema.safeParse(await readJson(response));
+        if (!parsed.success) {
+            return { ok: false, error: 'failed', message: 'stack-agent returned an unexpected telemetry status body' };
+        }
+        return { ok: true, services: parsed.data.services };
+    }
+    /**
+     * `POST /v1/telemetry/up` — start (pulling if needed) the telemetry
+     * services. May take up to ten minutes. Never throws.
+     */
+    async telemetryUp() {
+        const response = await this.request('POST', '/v1/telemetry/up', exports.STACK_AGENT_UP_TIMEOUT_MS);
+        if (!isResponse(response))
+            return response;
+        if (response.status === 401 || response.status === 403)
+            return unauthorized(response.status);
+        if (response.status === 409) {
+            return { ok: false, error: 'busy', message: 'stack-agent is already running a deployment' };
+        }
+        if (response.status === 503)
+            return notConfiguredByAgent();
+        const parsed = upBodySchema.safeParse(await readJson(response));
+        const body = parsed.success ? parsed.data : {};
+        if (response.ok && body.ok !== false) {
+            return { ok: true, exitCode: body.exitCode ?? 0, output: body.output ?? '' };
+        }
+        return {
+            ok: false,
+            error: 'failed',
+            message: `stack-agent could not start the telemetry services (HTTP ${response.status}` +
+                (body.exitCode !== undefined && body.exitCode !== null ? `, exit code ${body.exitCode}` : '') +
+                ')',
+            exitCode: body.exitCode ?? null,
+            output: body.output ?? body.error ?? '',
+        };
+    }
+    // ---------------------------------------------------------------------------
+    async request(method, path, timeoutMs) {
+        if (!this.isConfigured()) {
+            return {
+                ok: false,
+                error: 'not_configured',
+                message: 'The stack agent is not configured on this deployment (STACK_AGENT_URL / STACK_AGENT_TOKEN).',
+            };
+        }
+        try {
+            return await this.fetchImpl(`${this.baseUrl}${path}`, {
+                method,
+                headers: { Authorization: `Bearer ${this.token}`, Accept: 'application/json' },
+                signal: AbortSignal.timeout(timeoutMs),
+            });
+        }
+        catch (error) {
+            const message = `stack-agent at ${this.origin()} is unreachable: ${describeFetchError(error, timeoutMs)}`;
+            this.logger.warn(`${method} ${path}: ${message}`);
+            return { ok: false, error: 'unreachable', message };
+        }
+    }
+    /** The URL's origin, for messages (never a path, query or credential). */
+    origin() {
+        try {
+            return new URL(this.baseUrl).origin;
+        }
+        catch {
+            return 'the configured URL';
+        }
+    }
+};
+exports.StackAgentClient = StackAgentClient;
+exports.StackAgentClient = StackAgentClient = StackAgentClient_1 = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [config_1.ConfigService])
+], StackAgentClient);
+function isResponse(value) {
+    return typeof value.status === 'number';
+}
+function unauthorized(status) {
+    return {
+        ok: false,
+        error: 'unauthorized',
+        message: `stack-agent refused the API's token (HTTP ${status}); STACK_AGENT_TOKEN does not match the agent's.`,
+    };
+}
+function notConfiguredByAgent() {
+    return {
+        ok: false,
+        error: 'not_configured',
+        message: 'stack-agent reports that it has no telemetry stack configured on this host.',
+    };
+}
+async function readJson(response) {
+    try {
+        return await response.json();
+    }
+    catch {
+        return null;
+    }
+}
+/** A fetch failure in words: a timeout, a DNS/connect error (its `cause`), or the message. */
+function describeFetchError(error, timeoutMs) {
+    if (error instanceof Error && (error.name === 'TimeoutError' || error.name === 'AbortError')) {
+        return `no answer within ${Math.round(timeoutMs / 1000)} s`;
+    }
+    const cause = error?.cause;
+    if (cause instanceof Error) {
+        const code = cause.code;
+        return typeof code === 'string' ? `${code} (${cause.message})` : cause.message;
+    }
+    return error instanceof Error ? error.message : String(error);
+}
+//# sourceMappingURL=stack-agent.client.js.map

package/dist/telemetry/stack/stack-agent.client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stack-agent.client.js","sourceRoot":"","sources":["../../../src/telemetry/stack/stack-agent.client.ts"],"names":[],"mappings":";;;;;;;;;;;;;AAqOA,gDAaC;AAlPD,2CAAoD;AACpD,2CAA+C;AAC/C,uEAAyH;AACzH,6BAAwB;AAExB,gFAAgF;AAChF,qEAAqE;AACrE,0BAA0B;AAC1B,gFAAgF;AAChF,EAAE;AACF,8EAA8E;AAC9E,6CAA6C;AAC7C,EAAE;AACF,4EAA4E;AAC5E,wEAAwE;AACxE,qFAAqF;AACrF,wFAAwF;AACxF,EAAE;AACF,wEAAwE;AACxE,2EAA2E;AAC3E,6CAA6C;AAC7C,EAAE;AACF,oEAAoE;AACpE,yEAAyE;AACzE,2EAA2E;AAC3E,0EAA0E;AAC1E,4CAA4C;AAC5C,EAAE;AACF,+EAA+E;AAC/E,8EAA8E;AAC9E,+CAA+C;AAC/C,gFAAgF;AAEhF,4DAA4D;AAC/C,QAAA,6BAA6B,GAAG,KAAK,CAAC;AAEnD;;;;GAIG;AACU,QAAA,yBAAyB,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAExD,8DAA8D;AAC9D,sDAAsD;AACtD,oDAAoD;AACvC,QAAA,oBAAoB,GAAG,0CAA8B,CAAC;AACtD,QAAA,oBAAoB,GAAG,0CAA8B,CAAC;AAEtD,QAAA,kBAAkB,GAAG,OAAC,CAAC,MAAM,CAAC;IACzC,IAAI,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACvB,KAAK,EAAE,OAAC,CAAC,IAAI,CAAC,4BAAoB,CAAC;IACnC,MAAM,EAAE,OAAC,CAAC,IAAI,CAAC,4BAAoB,CAAC,CAAC,QAAQ,EAAE;CAChD,CAAC,CAAC;AAIH,MAAM,yBAAyB,GAAG,OAAC,CAAC,MAAM,CAAC,EAAE,QAAQ,EAAE,OAAC,CAAC,KAAK,CAAC,0BAAkB,CAAC,EAAE,CAAC,CAAC;AAEtF,MAAM,YAAY,GAAG,OAAC,CAAC,MAAM,CAAC;IAC5B,EAAE,EAAE,OAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;IAC1B,QAAQ,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;IAChD,MAAM,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC7B,KAAK,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAC7B,CAAC,CAAC;AAwBI,IAAM,gBAAgB,wBAAtB,MAAM,gBAAgB;IACV,MAAM,GAAG,IAAI,eAAM,CAAC,kBAAgB,CAAC,IAAI,CAAC,CAAC;IAC3C,OAAO,CAAS;IAChB,KAAK,CAAS;IAE/B,0DAA0D;IAChD,SAAS,GAAc,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IAErE,YAAY,MAAqB;QAC/B,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,CAAmC,YAAY,CAAC,IAAI,EAAE,CAAC;QAE7E,IAAI,CAAC,OAAO,GAAG,CAAC,GAAG,CAAC,GAAG,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;QAC1D,IAAI,CAAC,KAAK,GAAG,CAAC,GAAG,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IACxC,CAAC;IAED,8DAA8D;IAC9D,YAAY;QACV,OAAO,IAAI,CAAC,OAAO,KAAK,EAAE,IAAI,IAAI,CAAC,KAAK,KAAK,EAAE,CAAC;IAClD,CAAC;IAED,+EAA+E;IAC/E,KAAK,CAAC,eAAe;QACnB,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,eAAe,EAAE,qCAA6B,CAAC,CAAC;QAC3F,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC;YAAE,OAAO,QAAQ,CAAC;QAE3C,IAAI,QAAQ,CAAC,MAAM,KAAK,GAAG,IAAI,QAAQ,CAAC,MAAM,KAAK,GAAG;YAAE,OAAO,YAAY,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QAC7F,IAAI,QAAQ,CAAC,MAAM,KAAK,GAAG;YAAE,OAAO,oBAAoB,EAAE,CAAC;QAE3D,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;YACjB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,6BAA6B,QAAQ,CAAC,MAAM,EAAE,EAAE,CAAC;QACjG,CAAC;QAED,MAAM,MAAM,GAAG,yBAAyB,CAAC,SAAS,CAAC,MAAM,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC;QAC7E,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YACpB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,0DAA0D,EAAE,CAAC;QAC7G,CAAC;QAED,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC;IACtD,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,WAAW;QACf,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,kBAAkB,EAAE,iCAAyB,CAAC,CAAC;QAC3F,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC;YAAE,OAAO,QAAQ,CAAC;QAE3C,IAAI,QAAQ,CAAC,MAAM,KAAK,GAAG,IAAI,QAAQ,CAAC,MAAM,KAAK,GAAG;YAAE,OAAO,YAAY,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QAC7F,IAAI,QAAQ,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;YAC5B,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,6CAA6C,EAAE,CAAC;QAC9F,CAAC;QACD,IAAI,QAAQ,CAAC,MAAM,KAAK,GAAG;YAAE,OAAO,oBAAoB,EAAE,CAAC;QAE3D,MAAM,MAAM,GAAG,YAAY,CAAC,SAAS,CAAC,MAAM,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC;QAChE,MAAM,IAAI,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;QAE/C,IAAI,QAAQ,CAAC,EAAE,IAAI,IAAI,CAAC,EAAE,KAAK,KAAK,EAAE,CAAC;YACrC,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,IAAI,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,IAAI,EAAE,EAAE,CAAC;QAC/E,CAAC;QAED,OAAO;YACL,EAAE,EAAE,KAAK;YACT,KAAK,EAAE,QAAQ;YACf,OAAO,EACL,4DAA4D,QAAQ,CAAC,MAAM,EAAE;gBAC7E,CAAC,IAAI,CAAC,QAAQ,KAAK,SAAS,IAAI,IAAI,CAAC,QAAQ,KAAK,IAAI,CAAC,CAAC,CAAC,eAAe,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC7F,GAAG;YACL,QAAQ,EAAE,IAAI,CAAC,QAAQ,IAAI,IAAI;YAC/B,MAAM,EAAE,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,KAAK,IAAI,EAAE;SACxC,CAAC;IACJ,CAAC;IAED,8EAA8E;IAEtE,KAAK,CAAC,OAAO,CACnB,MAAsB,EACtB,IAAY,EACZ,SAAiB;QAEjB,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,EAAE,CAAC;YACzB,OAAO;gBACL,EAAE,EAAE,KAAK;gBACT,KAAK,EAAE,gBAAgB;gBACvB,OAAO,EAAE,6FAA6F;aACvG,CAAC;QACJ,CAAC;QAED,IAAI,CAAC;YACH,OAAO,MAAM,IAAI,CAAC,SAAS,CAAC,GAAG,IAAI,CAAC,OAAO,GAAG,IAAI,EAAE,EAAE;gBACpD,MAAM;gBACN,OAAO,EAAE,EAAE,aAAa,EAAE,UAAU,IAAI,CAAC,KAAK,EAAE,EAAE,MAAM,EAAE,kBAAkB,EAAE;gBAC9E,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,SAAS,CAAC;aACvC,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,OAAO,GAAG,kBAAkB,IAAI,CAAC,MAAM,EAAE,oBAAoB,kBAAkB,CAAC,KAAK,EAAE,SAAS,CAAC,EAAE,CAAC;YAC1G,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,MAAM,IAAI,IAAI,KAAK,OAAO,EAAE,CAAC,CAAC;YAElD,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,aAAa,EAAE,OAAO,EAAE,CAAC;QACtD,CAAC;IACH,CAAC;IAED,0EAA0E;IAClE,MAAM;QACZ,IAAI,CAAC;YACH,OAAO,IAAI,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC;QACtC,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,oBAAoB,CAAC;QAC9B,CAAC;IACH,CAAC;CACF,CAAA;AA9GY,4CAAgB;2BAAhB,gBAAgB;IAD5B,IAAA,mBAAU,GAAE;qCASS,sBAAa;GARtB,gBAAgB,CA8G5B;AAED,SAAS,UAAU,CAAC,KAAmC;IACrD,OAAO,OAAQ,KAA8B,CAAC,MAAM,KAAK,QAAQ,CAAC;AACpE,CAAC;AAED,SAAS,YAAY,CAAC,MAAc;IAClC,OAAO;QACL,EAAE,EAAE,KAAK;QACT,KAAK,EAAE,cAAc;QACrB,OAAO,EAAE,6CAA6C,MAAM,kDAAkD;KAC/G,CAAC;AACJ,CAAC;AAED,SAAS,oBAAoB;IAC3B,OAAO;QACL,EAAE,EAAE,KAAK;QACT,KAAK,EAAE,gBAAgB;QACvB,OAAO,EAAE,6EAA6E;KACvF,CAAC;AACJ,CAAC;AAED,KAAK,UAAU,QAAQ,CAAC,QAAkB;IACxC,IAAI,CAAC;QACH,OAAO,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;IAC/B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,8FAA8F;AAC9F,SAAgB,kBAAkB,CAAC,KAAc,EAAE,SAAiB;IAClE,IAAI,KAAK,YAAY,KAAK,IAAI,CAAC,KAAK,CAAC,IAAI,KAAK,cAAc,IAAI,KAAK,CAAC,IAAI,KAAK,YAAY,CAAC,EAAE,CAAC;QAC7F,OAAO,oBAAoB,IAAI,CAAC,KAAK,CAAC,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC;IAC9D,CAAC;IAED,MAAM,KAAK,GAAI,KAAoC,EAAE,KAAK,CAAC;IAC3D,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;QAC3B,MAAM,IAAI,GAAI,KAA4B,CAAC,IAAI,CAAC;QAEhD,OAAO,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,IAAI,KAAK,KAAK,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC;IACjF,CAAC;IAED,OAAO,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAChE,CAAC"}

package/dist/telemetry/stack/telemetry-stack-deploy.handler.d.ts

@@ -0,0 +1,43 @@
+import { OnModuleInit } from '@nestjs/common';
+import { type TelemetryJobExecutionProfile, type TelemetryJobHandler, type TelemetryJobRecord as Job, type TelemetryJobsPort } from '../ports';
+import { TelemetryConnectionService } from '../connection/telemetry-connection.service';
+import { TelemetrySettingsService } from '../telemetry-settings.service';
+import { StackAgentClient } from './stack-agent.client';
+/**
+ * The job type. PERMANENT once rows of it exist.
+ *
+ * @stability stable
+ */
+export declare const TELEMETRY_STACK_DEPLOY_TYPE = "telemetry.stack.deploy";
+/** Cap on the stored agent output, in UTF-8 bytes. */
+export declare const STACK_DEPLOY_OUTPUT_MAX_BYTES = 4096;
+/** What a deploy job records on `payload.result`. */
+export interface TelemetryStackDeployResult {
+    ok: boolean;
+    exitCode: number | null;
+    output: string;
+}
+/**
+ * The last `maxBytes` bytes of `output` (UTF-8), prefixed with an ellipsis
+ * line when anything was cut. Never splits a multi-byte character.
+ */
+export declare function capOutput(output: string, maxBytes?: number): string;
+export declare class TelemetryStackDeployHandler implements TelemetryJobHandler, OnModuleInit {
+    private readonly agent;
+    private readonly jobs;
+    private readonly connection;
+    private readonly settings;
+    private readonly logger;
+    readonly type = "telemetry.stack.deploy";
+    /** An image pull can take ten minutes; never retried automatically. */
+    readonly profile: TelemetryJobExecutionProfile;
+    constructor(agent: StackAgentClient, jobs: TelemetryJobsPort, connection: TelemetryConnectionService, settings: TelemetrySettingsService);
+    onModuleInit(): void;
+    /** Throws to fail; the row's `payload.result` is written either way when the agent answered. */
+    process(job: Job): Promise<void>;
+    /** Merges `result` into the job's own payload. Best effort: never fails the job by itself. */
+    private recordResult;
+    /** So the admin page turns green quickly. See the header; nothing here may throw. */
+    private nudgeTelemetry;
+}
+//# sourceMappingURL=telemetry-stack-deploy.handler.d.ts.map

package/dist/telemetry/stack/telemetry-stack-deploy.handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry-stack-deploy.handler.d.ts","sourceRoot":"","sources":["../../../src/telemetry/stack/telemetry-stack-deploy.handler.ts"],"names":[],"mappings":"AAuCA,OAAO,EAA8B,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAE1E,OAAO,EAEL,KAAK,4BAA4B,EACjC,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,IAAI,GAAG,EAC9B,KAAK,iBAAiB,EACvB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,0BAA0B,EAAE,MAAM,4CAA4C,CAAC;AAExF,OAAO,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AACzE,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAExD;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,2BAA2B,CAAC;AAEpE,sDAAsD;AACtD,eAAO,MAAM,6BAA6B,OAAO,CAAC;AAElD,qDAAqD;AACrD,MAAM,WAAW,0BAA0B;IACzC,EAAE,EAAE,OAAO,CAAC;IACZ,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,SAAgC,GAAG,MAAM,CAc1F;AAED,qBACa,2BAA4B,YAAW,mBAAmB,EAAE,YAAY;IAWjF,OAAO,CAAC,QAAQ,CAAC,KAAK;IACE,OAAO,CAAC,QAAQ,CAAC,IAAI;IAC7C,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAb3B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgD;IAEvE,QAAQ,CAAC,IAAI,4BAA+B;IAE5C,uEAAuE;IACvE,QAAQ,CAAC,OAAO,EAAE,4BAA4B,CAAoD;gBAK/E,KAAK,EAAE,gBAAgB,EACC,IAAI,EAAE,iBAAiB,EAC/C,UAAU,EAAE,0BAA0B,EACtC,QAAQ,EAAE,wBAAwB;IAGrD,YAAY,IAAI,IAAI;IAIpB,gGAAgG;IAC1F,OAAO,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC;IAsBtC,8FAA8F;YAChF,YAAY;IAe1B,qFAAqF;YACvE,cAAc;CAgB7B"}

package/dist/telemetry/stack/telemetry-stack-deploy.handler.js

@@ -0,0 +1,159 @@
+"use strict";
+// =============================================================================
+// `telemetry.stack.deploy` job handler (issue #567, epic #528)
+// =============================================================================
+//
+// Asks the VPS `stack-agent` sidecar to start the telemetry services
+// (GreptimeDB and the OTel collector) — `POST /v1/telemetry/up` — and records
+// what it said. Enqueued only by `POST /api/admin/telemetry/stack/deploy`
+// ("Deploy GreptimeDB" on /admin/settings/telemetry).
+//
+// A JOB, NOT AN HTTP CALL: the agent may pull images, which can take up to
+// ten minutes — far longer than an admin request may stay open (CLAUDE.md,
+// queue rule 1). The admin page polls `GET /api/admin/telemetry/stack`, which
+// reads this job's row.
+//
+// SINGLE-FLIGHT: enqueued with no subject, so its dedup key is constant for the
+// type and `jobs_active_dedup_uniq_idx` guarantees at most one pending/running
+// deploy; a second click returns the job already in flight.
+//
+// THE RESULT is written onto the job's own `payload.result` as
+// `{ ok, exitCode, output }` — `output` capped at `STACK_DEPLOY_OUTPUT_MAX_BYTES`,
+// keeping the TAIL (where compose prints what went wrong). A failure is also
+// thrown, so the row ends `failed` with the reason in `lastError`.
+//
+// NEVER AUTO-RETRIED (`maxAttempts: 1`): a failed `up` is a deployment problem
+// an administrator must read, and re-running a ten-minute pull on the queue's
+// retry budget would only hide it.
+//
+// SERVER-ONLY, PERMANENTLY: no `nodeResultSchema`/`persistNodeResult`. The
+// stack-agent listens only on the deployment's internal network, which a
+// worker node cannot reach, and its bearer token controls the host's Docker
+// daemon — a node must never hold it (CLAUDE.md, queue rule 3). Do not add a
+// `nodeSecretBroker` either.
+//
+// AFTER A SUCCESSFUL DEPLOY the telemetry connection is nudged so the admin
+// page turns green on its next poll: the connection snapshot is re-read, the
+// export gate re-applied, and a `telemetry.retention.apply` job queued (a new
+// GreptimeDB has no TTL yet). All best effort — none can fail the deploy.
+// =============================================================================
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+var TelemetryStackDeployHandler_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TelemetryStackDeployHandler = exports.STACK_DEPLOY_OUTPUT_MAX_BYTES = exports.TELEMETRY_STACK_DEPLOY_TYPE = void 0;
+exports.capOutput = capOutput;
+const common_1 = require("@nestjs/common");
+const ports_1 = require("../ports");
+const telemetry_connection_service_1 = require("../connection/telemetry-connection.service");
+const telemetry_retention_handler_1 = require("../handlers/telemetry-retention.handler");
+const telemetry_settings_service_1 = require("../telemetry-settings.service");
+const stack_agent_client_1 = require("./stack-agent.client");
+/**
+ * The job type. PERMANENT once rows of it exist.
+ *
+ * @stability stable
+ */
+exports.TELEMETRY_STACK_DEPLOY_TYPE = 'telemetry.stack.deploy';
+/** Cap on the stored agent output, in UTF-8 bytes. */
+exports.STACK_DEPLOY_OUTPUT_MAX_BYTES = 4096;
+/**
+ * The last `maxBytes` bytes of `output` (UTF-8), prefixed with an ellipsis
+ * line when anything was cut. Never splits a multi-byte character.
+ */
+function capOutput(output, maxBytes = exports.STACK_DEPLOY_OUTPUT_MAX_BYTES) {
+    const bytes = Buffer.from(output, 'utf8');
+    if (bytes.length <= maxBytes)
+        return output;
+    const marker = '…(truncated)\n';
+    const budget = maxBytes - Buffer.byteLength(marker, 'utf8');
+    let tail = bytes.subarray(bytes.length - budget);
+    // Skip UTF-8 continuation bytes (10xxxxxx) so the tail starts on a character.
+    let skip = 0;
+    while (skip < tail.length && (tail[skip] & 0xc0) === 0x80)
+        skip += 1;
+    tail = tail.subarray(skip);
+    return marker + tail.toString('utf8');
+}
+let TelemetryStackDeployHandler = TelemetryStackDeployHandler_1 = class TelemetryStackDeployHandler {
+    agent;
+    jobs;
+    connection;
+    settings;
+    logger = new common_1.Logger(TelemetryStackDeployHandler_1.name);
+    type = exports.TELEMETRY_STACK_DEPLOY_TYPE;
+    /** An image pull can take ten minutes; never retried automatically. */
+    profile = { maxRuntimeMs: 15 * 60 * 1000, maxAttempts: 1 };
+    // Deliberately NO `nodeResultSchema` / `persistNodeResult` — see the header.
+    constructor(agent, jobs, connection, settings) {
+        this.agent = agent;
+        this.jobs = jobs;
+        this.connection = connection;
+        this.settings = settings;
+    }
+    onModuleInit() {
+        this.jobs.registerHandler(this);
+    }
+    /** Throws to fail; the row's `payload.result` is written either way when the agent answered. */
+    async process(job) {
+        const outcome = await this.agent.telemetryUp();
+        if (!outcome.ok) {
+            if (outcome.error === 'failed') {
+                await this.recordResult(job, {
+                    ok: false,
+                    exitCode: outcome.exitCode ?? null,
+                    output: capOutput(outcome.output ?? ''),
+                });
+            }
+            throw new Error(`Deploying the telemetry services failed (${outcome.error}): ${outcome.message}`);
+        }
+        await this.recordResult(job, { ok: true, exitCode: outcome.exitCode, output: capOutput(outcome.output) });
+        this.logger.log(`Telemetry services started by stack-agent (job ${job.id})`);
+        await this.nudgeTelemetry();
+    }
+    /** Merges `result` into the job's own payload. Best effort: never fails the job by itself. */
+    async recordResult(job, result) {
+        const base = job.payload && typeof job.payload === 'object' && !Array.isArray(job.payload)
+            ? job.payload
+            : {};
+        try {
+            await this.jobs.updatePayload(job.id, { ...base, result: { ...result } });
+        }
+        catch (error) {
+            this.logger.warn(`Could not record the deploy result on job ${job.id}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /** So the admin page turns green quickly. See the header; nothing here may throw. */
+    async nudgeTelemetry() {
+        try {
+            await this.connection.refreshSafely();
+            await this.settings.refreshGate();
+        }
+        catch (error) {
+            this.logger.warn(`Telemetry refresh after deploy failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        await this.jobs.enqueueHousekeepingJob({
+            logger: this.logger,
+            type: telemetry_retention_handler_1.TELEMETRY_RETENTION_TYPE,
+            what: 'telemetry retention',
+        });
+    }
+};
+exports.TelemetryStackDeployHandler = TelemetryStackDeployHandler;
+exports.TelemetryStackDeployHandler = TelemetryStackDeployHandler = TelemetryStackDeployHandler_1 = __decorate([
+    (0, common_1.Injectable)(),
+    __param(1, (0, common_1.Inject)(ports_1.TELEMETRY_JOBS)),
+    __metadata("design:paramtypes", [stack_agent_client_1.StackAgentClient, Object, telemetry_connection_service_1.TelemetryConnectionService,
+        telemetry_settings_service_1.TelemetrySettingsService])
+], TelemetryStackDeployHandler);
+//# sourceMappingURL=telemetry-stack-deploy.handler.js.map

package/dist/telemetry/stack/telemetry-stack-deploy.handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry-stack-deploy.handler.js","sourceRoot":"","sources":["../../../src/telemetry/stack/telemetry-stack-deploy.handler.ts"],"names":[],"mappings":"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"}

package/dist/telemetry/stack/telemetry-stack.controller.d.ts

@@ -0,0 +1,14 @@
+import { Type } from '@nestjs/common';
+import type { ResolvedTelemetryModuleOptions } from '../telemetry.options';
+/**
+ * Creates the `TelemetryStackController` class for one set of module options: its routes
+ * guarded by the app's access decorators (`options.host.access`), the caller
+ * resolved by `options.actorId`. `TelemetryModule.forRoot()` calls it.
+ *
+ * @param options - the resolved module options.
+ * @returns the controller class.
+ *
+ * @stability experimental
+ */
+export declare function createTelemetryStackController(options: ResolvedTelemetryModuleOptions): Type<unknown>;
+//# sourceMappingURL=telemetry-stack.controller.d.ts.map

package/dist/telemetry/stack/telemetry-stack.controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry-stack.controller.d.ts","sourceRoot":"","sources":["../../../src/telemetry/stack/telemetry-stack.controller.ts"],"names":[],"mappings":"AAAA,OAAO,EAAuD,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAM3F,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,sBAAsB,CAAC;AAiB3E;;;;;;;;;GASG;AACH,wBAAgB,8BAA8B,CAAC,OAAO,EAAE,8BAA8B,GAAG,IAAI,CAAC,OAAO,CAAC,CAiDrG"}

package/dist/telemetry/stack/telemetry-stack.controller.js

@@ -0,0 +1,107 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createTelemetryStackController = createTelemetryStackController;
+const common_1 = require("@nestjs/common");
+const swagger_1 = require("@nestjs/swagger");
+const index_1 = require("../../core/index");
+const telemetry_stack_dto_1 = require("./dto/telemetry-stack.dto");
+const telemetry_stack_service_1 = require("./telemetry-stack.service");
+const telemetry_permissions_1 = require("../telemetry.permissions");
+// =============================================================================
+// TelemetryStackController (issue #567, epic #528)
+// =============================================================================
+//
+//   GET  /api/admin/telemetry/stack          system_settings:read
+//   POST /api/admin/telemetry/stack/deploy   system_settings:write  (202, idempotent)
+//
+// WHY `system_settings:*` AND NOT `telemetry:*`: starting containers on the
+// host through the stack-agent is a DEPLOYMENT action, not a telemetry policy
+// edit — the same reach as the rest of the deployment-wide system settings.
+// The Telemetry services section of /admin/settings/telemetry gates its
+// content and its "Deploy GreptimeDB" button on these exact strings.
+// =============================================================================
+/**
+ * Creates the `TelemetryStackController` class for one set of module options: its routes
+ * guarded by the app's access decorators (`options.host.access`), the caller
+ * resolved by `options.actorId`. `TelemetryModule.forRoot()` calls it.
+ *
+ * @param options - the resolved module options.
+ * @returns the controller class.
+ *
+ * @stability experimental
+ */
+function createTelemetryStackController(options) {
+    const access = options.host.access;
+    const ActorId = options.actorIdParam;
+    let TelemetryStackController = class TelemetryStackController {
+        stack;
+        constructor(stack) {
+            this.stack = stack;
+        }
+        async getStatus() {
+            return this.stack.getStatus();
+        }
+        async deploy(userId) {
+            return this.stack.deploy(userId);
+        }
+    };
+    __decorate([
+        (0, common_1.Get)(),
+        (access.requirePermissions([telemetry_permissions_1.TELEMETRY_HOST_PERMISSIONS.SYSTEM_SETTINGS_READ])),
+        (0, swagger_1.ApiOperation)({
+            summary: 'Get the telemetry services status (Admin only)',
+            description: 'The state of each telemetry container (GreptimeDB, the OTel collector) as reported by the ' +
+                'deployment\'s stack agent, and the most recent `telemetry.stack.deploy` job.\n\n' +
+                '**Always 200.** `agent` is `available` (the agent answered), `unavailable` (configured ' +
+                'but unreachable within five seconds, or an unexpected answer), `unauthorized` (it refused ' +
+                'the API\'s token) or `not_configured` (this deployment has no stack agent). `agentError` ' +
+                'says why the agent is `unavailable` or `unauthorized` (never the token), else null. `services` is ' +
+                'empty unless `agent` is `available`. `deploy` is null when no deploy was ever requested; ' +
+                '`deploy.output` is the tail (at most 4 KB) of what the agent printed.',
+        }),
+        (0, swagger_1.ApiResponse)({ status: 200, description: 'The telemetry services status', type: telemetry_stack_dto_1.TelemetryStackStatusDto }),
+        __metadata("design:type", Function),
+        __metadata("design:paramtypes", []),
+        __metadata("design:returntype", Promise)
+    ], TelemetryStackController.prototype, "getStatus", null);
+    __decorate([
+        (0, common_1.Post)('deploy'),
+        (access.requirePermissions([telemetry_permissions_1.TELEMETRY_HOST_PERMISSIONS.SYSTEM_SETTINGS_WRITE])),
+        (0, common_1.HttpCode)(common_1.HttpStatus.ACCEPTED),
+        (0, swagger_1.ApiOperation)({
+            summary: 'Deploy the telemetry services (Admin only)',
+            description: 'Queues a `telemetry.stack.deploy` job, which asks the stack agent to start GreptimeDB and ' +
+                'the OTel collector (pulling their images if needed — up to ten minutes), and returns at ' +
+                'once with **202**. Poll `GET /api/admin/telemetry/stack` for `deploy.status`.\n\n' +
+                '**Idempotent:** while a deploy is pending or running, the call returns that job\'s id ' +
+                'instead of queueing another. **409** with `details.reason` `STACK_AGENT_NOT_CONFIGURED` ' +
+                'when this deployment has no stack agent.',
+        }),
+        (0, swagger_1.ApiResponse)({ status: 202, description: 'The deploy job (new, or the one already in flight)', type: telemetry_stack_dto_1.TelemetryStackDeployStartedDto }),
+        (0, swagger_1.ApiResponse)({ status: 409, description: '`STACK_AGENT_NOT_CONFIGURED`', type: index_1.ErrorDto }),
+        __param(0, ActorId()),
+        __metadata("design:type", Function),
+        __metadata("design:paramtypes", [String]),
+        __metadata("design:returntype", Promise)
+    ], TelemetryStackController.prototype, "deploy", null);
+    TelemetryStackController = __decorate([
+        (0, swagger_1.ApiTags)('Telemetry'),
+        (0, common_1.Controller)('admin/telemetry/stack'),
+        __param(0, (0, common_1.Inject)(telemetry_stack_service_1.TelemetryStackService)),
+        __metadata("design:paramtypes", [telemetry_stack_service_1.TelemetryStackService])
+    ], TelemetryStackController);
+    return TelemetryStackController;
+}
+//# sourceMappingURL=telemetry-stack.controller.js.map

package/dist/telemetry/stack/telemetry-stack.controller.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry-stack.controller.js","sourceRoot":"","sources":["../../../src/telemetry/stack/telemetry-stack.controller.ts"],"names":[],"mappings":";;;;;;;;;;;;;;AAiCA,wEAiDC;AAlFD,2CAA2F;AAC3F,6CAAqE;AAErE,4CAA4C;AAC5C,mEAAoG;AACpG,uEAAkE;AAElE,oEAAsE;AAEtE,gFAAgF;AAChF,mDAAmD;AACnD,gFAAgF;AAChF,EAAE;AACF,kEAAkE;AAClE,sFAAsF;AACtF,EAAE;AACF,4EAA4E;AAC5E,8EAA8E;AAC9E,4EAA4E;AAC5E,wEAAwE;AACxE,qEAAqE;AACrE,gFAAgF;AAEhF;;;;;;;;;GASG;AACH,SAAgB,8BAA8B,CAAC,OAAuC;IACpF,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC;IACnC,MAAM,OAAO,GAAG,OAAO,CAAC,YAAY,CAAC;IAErC,IAEM,wBAAwB,GAF9B,MAEM,wBAAwB;QACgC;QAA5D,YAA4D,KAA4B;YAA5B,UAAK,GAAL,KAAK,CAAuB;QAAG,CAAC;QAiBtF,AAAN,KAAK,CAAC,SAAS;YACb,OAAO,IAAI,CAAC,KAAK,CAAC,SAAS,EAAE,CAAC;QAChC,CAAC;QAiBK,AAAN,KAAK,CAAC,MAAM,CAAY,MAAc;YACpC,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QACnC,CAAC;KACF,CAAA;IAtBO;QAfL,IAAA,YAAG,GAAE;QACL,CAAC,MAAM,CAAC,kBAAkB,CAAC,CAAC,kDAA0B,CAAC,oBAAoB,CAAC,CAAC,CAAC;QAC9E,IAAA,sBAAY,EAAC;YACZ,OAAO,EAAE,gDAAgD;YACzD,WAAW,EACT,4FAA4F;gBAC5F,kFAAkF;gBAClF,yFAAyF;gBACzF,4FAA4F;gBAC5F,2FAA2F;gBAC3F,oGAAoG;gBACpG,2FAA2F;gBAC3F,uEAAuE;SAC1E,CAAC;QACD,IAAA,qBAAW,EAAC,EAAE,MAAM,EAAE,GAAG,EAAE,WAAW,EAAE,+BAA+B,EAAE,IAAI,EAAE,6CAAuB,EAAE,CAAC;;;;6DAGzG;IAiBK;QAfL,IAAA,aAAI,EAAC,QAAQ,CAAC;QACd,CAAC,MAAM,CAAC,kBAAkB,CAAC,CAAC,kDAA0B,CAAC,qBAAqB,CAAC,CAAC,CAAC;QAC/E,IAAA,iBAAQ,EAAC,mBAAU,CAAC,QAAQ,CAAC;QAC7B,IAAA,sBAAY,EAAC;YACZ,OAAO,EAAE,4CAA4C;YACrD,WAAW,EACT,4FAA4F;gBAC5F,0FAA0F;gBAC1F,mFAAmF;gBACnF,wFAAwF;gBACxF,0FAA0F;gBAC1F,0CAA0C;SAC7C,CAAC;QACD,IAAA,qBAAW,EAAC,EAAE,MAAM,EAAE,GAAG,EAAE,WAAW,EAAE,oDAAoD,EAAE,IAAI,EAAE,oDAA8B,EAAE,CAAC;QACrI,IAAA,qBAAW,EAAC,EAAE,MAAM,EAAE,GAAG,EAAE,WAAW,EAAE,8BAA8B,EAAE,IAAI,EAAE,gBAAQ,EAAE,CAAC;QAC5E,WAAA,OAAO,EAAE,CAAA;;;;0DAEtB;IAvCG,wBAAwB;QAF7B,IAAA,iBAAO,EAAC,WAAW,CAAC;QACpB,IAAA,mBAAU,EAAC,uBAAuB,CAAC;QAErB,WAAA,IAAA,eAAM,EAAC,+CAAqB,CAAC,CAAA;yCAAyB,+CAAqB;OADpF,wBAAwB,CAwC7B;IAED,OAAO,wBAAwB,CAAC;AAClC,CAAC"}

package/dist/telemetry/stack/telemetry-stack.service.d.ts

@@ -0,0 +1,19 @@
+import { type TelemetryAuditSink, type TelemetryJobRecord, type TelemetryJobsPort } from '../ports';
+import type { TelemetryStackDeploy, TelemetryStackStatus } from './dto/telemetry-stack.dto';
+import { StackAgentClient } from './stack-agent.client';
+export declare const TELEMETRY_STACK_DEPLOY_AUDIT_ACTION = "telemetry:stack_deploy";
+export declare class TelemetryStackService {
+    private readonly agent;
+    private readonly jobs;
+    private readonly auditSink;
+    private readonly logger;
+    constructor(agent: StackAgentClient, jobs: TelemetryJobsPort, auditSink: TelemetryAuditSink);
+    getStatus(): Promise<TelemetryStackStatus>;
+    /** Queues a deploy (or returns the one in flight) and audits the request. */
+    deploy(userId: string): Promise<{
+        jobId: string;
+    }>;
+}
+/** The API shape of one deploy job. `output` comes from the handler's `payload.result`. */
+export declare function toDeploy(job: Pick<TelemetryJobRecord, 'id' | 'status' | 'createdAt' | 'finishedAt' | 'lastError' | 'payload'>): TelemetryStackDeploy;
+//# sourceMappingURL=telemetry-stack.service.d.ts.map

package/dist/telemetry/stack/telemetry-stack.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry-stack.service.d.ts","sourceRoot":"","sources":["../../../src/telemetry/stack/telemetry-stack.service.ts"],"names":[],"mappings":"AAEA,OAAO,EAGL,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACvB,MAAM,UAAU,CAAC;AAClB,OAAO,KAAK,EAA4B,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AACtH,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAoBxD,eAAO,MAAM,mCAAmC,2BAA2B,CAAC;AAE5E,qBACa,qBAAqB;IAI9B,OAAO,CAAC,QAAQ,CAAC,KAAK;IACE,OAAO,CAAC,QAAQ,CAAC,IAAI;IACf,OAAO,CAAC,QAAQ,CAAC,SAAS;IAL1D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA0C;gBAG9C,KAAK,EAAE,gBAAgB,EACC,IAAI,EAAE,iBAAiB,EACjB,SAAS,EAAE,kBAAkB;IAGxE,SAAS,IAAI,OAAO,CAAC,oBAAoB,CAAC;IAwBhD,6EAA6E;IACvE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;CA+BzD;AAED,2FAA2F;AAC3F,wBAAgB,QAAQ,CACtB,GAAG,EAAE,IAAI,CAAC,kBAAkB,EAAE,IAAI,GAAG,QAAQ,GAAG,WAAW,GAAG,YAAY,GAAG,WAAW,GAAG,SAAS,CAAC,GACpG,oBAAoB,CActB"}