@calltelemetry/cli 1.3.0 → 1.4.0

package/dist/lib/k8s/appliance-info.d.ts

@@ -0,0 +1,78 @@
+import { type Preferences } from '../prefs.js';
+import type { DeploymentMode } from '../deployment.js';
+import type { HelmfileEnvironment } from '../helmfile.js';
+export declare const APPLIANCE_INFO_SCHEMA_VERSION = 1;
+export declare const DEFAULT_APPLIANCE_HOSTNAME = "calltelemetry";
+export declare const APPLIANCE_DEPLOYMENT_MODES: readonly DeploymentMode[];
+export declare const APPLIANCE_HELMFILE_ENVIRONMENTS: readonly HelmfileEnvironment[];
+/** Non-secret image pins carried in the appliance `.env`. */
+export interface ApplianceVersions {
+    cli?: string;
+    web?: string;
+    vue?: string;
+    jtapi?: string;
+    ctMedia?: string;
+    syslog?: string;
+    traceroute?: string;
+}
+export interface ApplianceInfo {
+    schemaVersion: typeof APPLIANCE_INFO_SCHEMA_VERSION;
+    /** Stable installation identifier derived from the install dir + machine id. */
+    installationId: string;
+    installDir: string;
+    hostname: string;
+    deploymentMode: DeploymentMode;
+    k8sNamespace: string;
+    k8sEnvironment: HelmfileEnvironment;
+    versions: ApplianceVersions;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface ApplianceInfoValidation {
+    valid: boolean;
+    errors: string[];
+}
+export declare class ApplianceInfoValidationError extends Error {
+    readonly errors: string[];
+    constructor(errors: string[]);
+}
+/**
+ * Derive a stable, non-license installation identifier. This is not the
+ * licensing `CT-APP-*` identifier; it exists only so job receipts from the
+ * same install can be correlated.
+ */
+export declare function deriveInstallationId(installDir: string, machineId?: string): string;
+/** Map `.env` pin keys onto the non-secret appliance version record. */
+export declare function versionsFromEnv(env: Record<string, string>): ApplianceVersions;
+export declare function validateApplianceInfo(info: unknown): ApplianceInfoValidation;
+export declare function assertValidApplianceInfo(info: unknown): asserts info is ApplianceInfo;
+/** Resolve the persisted inventory path under the appliance k8s payload. */
+export declare function resolveApplianceInfoPath(installDir: string): string;
+/**
+ * Persist a validated inventory snapshot. The file is mode 0600 because it
+ * carries host placement details, even though it carries no credentials.
+ */
+export declare function saveApplianceInfo(info: ApplianceInfo, path?: string): Promise<void>;
+/** Load and validate an inventory snapshot. Missing files return null. */
+export declare function loadApplianceInfo(path: string): ApplianceInfo | null;
+export interface CollectApplianceInfoOptions {
+    installDir?: string;
+    hostname?: string;
+    machineId?: string;
+    env?: Record<string, string>;
+    prefs?: Preferences;
+    cliVersion?: string;
+    now?: Date;
+}
+/**
+ * Build a fresh snapshot from the appliance `.env`, paths, and preferences.
+ * The caller is responsible for persisting it with `saveApplianceInfo`.
+ */
+export declare function collectApplianceInfo(options?: CollectApplianceInfoOptions): ApplianceInfo;
+/**
+ * Refresh an existing snapshot in place. Identity (`installationId`,
+ * `installDir`, `createdAt`) is preserved; placement, versions, and
+ * `updatedAt` are replaced.
+ */
+export declare function refreshApplianceInfo(previous: ApplianceInfo, updates: Pick<ApplianceInfo, 'deploymentMode' | 'k8sNamespace' | 'k8sEnvironment' | 'versions' | 'hostname'>, now?: Date): ApplianceInfo;
+//# sourceMappingURL=appliance-info.d.ts.map

package/dist/lib/k8s/appliance-info.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"appliance-info.d.ts","sourceRoot":"","sources":["../../../src/lib/k8s/appliance-info.ts"],"names":[],"mappings":"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"}

package/dist/lib/k8s/appliance-info.js

@@ -0,0 +1,226 @@
+/**
+ * Appliance inventory for the Kubernetes deployment path.
+ *
+ * This is the durable, validated record of *what this appliance is* — the
+ * installation identity, deployment mode, namespace/environment, and the
+ * image pins read from the appliance `.env`. It is deliberately separate
+ * from `~/.ct/preferences.json`: preferences are operator overrides, while
+ * this file is a generated snapshot that can be attached to a job receipt.
+ *
+ * The snapshot never contains credentials. Only non-secret image pins and
+ * placement settings are persisted; `.env` remains the source of truth for
+ * everything else.
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { mkdirSafe, writeFileSafe } from '../fs.js';
+import { getPaths } from '../paths.js';
+import { getPrefs } from '../prefs.js';
+import { isValidHostname } from '../identity.js';
+import { readEnvKeys } from '../env.js';
+export const APPLIANCE_INFO_SCHEMA_VERSION = 1;
+export const DEFAULT_APPLIANCE_HOSTNAME = 'calltelemetry';
+export const APPLIANCE_DEPLOYMENT_MODES = [
+    'docker-compose',
+    'k3s',
+];
+export const APPLIANCE_HELMFILE_ENVIRONMENTS = [
+    'ct-dev',
+    'ct-prod',
+    'ct-test',
+    'ct-appliance',
+];
+export class ApplianceInfoValidationError extends Error {
+    errors;
+    constructor(errors) {
+        super(`Invalid appliance info: ${errors.join('; ')}`);
+        this.name = 'ApplianceInfoValidationError';
+        this.errors = errors;
+    }
+}
+const DNS_LABEL = /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$/;
+const INSTALLATION_ID = /^[a-f0-9]{16,64}$/;
+const VERSION_VALUE = /^\S+$/;
+const MAX_VERSION_LENGTH = 128;
+function isIsoTimestamp(value) {
+    if (typeof value !== 'string' || value.length === 0)
+        return false;
+    const parsed = Date.parse(value);
+    return Number.isFinite(parsed);
+}
+function isScalarVersion(value) {
+    return (typeof value === 'string' &&
+        value.length > 0 &&
+        value.length <= MAX_VERSION_LENGTH &&
+        VERSION_VALUE.test(value) &&
+        // eslint-disable-next-line no-control-regex
+        !/[\u0000-\u001f\u007f]/.test(value));
+}
+/**
+ * Derive a stable, non-license installation identifier. This is not the
+ * licensing `CT-APP-*` identifier; it exists only so job receipts from the
+ * same install can be correlated.
+ */
+export function deriveInstallationId(installDir, machineId = '') {
+    return createHash('sha256')
+        .update(`${installDir}\u0000${machineId}`)
+        .digest('hex')
+        .slice(0, 16);
+}
+/** Map `.env` pin keys onto the non-secret appliance version record. */
+export function versionsFromEnv(env) {
+    const versions = {};
+    const mapping = [
+        ['cli', 'CT_CLI_VERSION'],
+        ['web', 'WEB_VERSION'],
+        ['vue', 'VUE_VERSION'],
+        ['jtapi', 'JTAPI_VERSION'],
+        ['ctMedia', 'CT_MEDIA_VERSION'],
+        ['syslog', 'CT_SYSLOG_INGEST_VERSION'],
+        ['traceroute', 'TRACEROUTE_VERSION'],
+    ];
+    for (const [field, key] of mapping) {
+        const value = env[key]?.trim();
+        if (value)
+            versions[field] = value;
+    }
+    return versions;
+}
+export function validateApplianceInfo(info) {
+    const errors = [];
+    if (typeof info !== 'object' || info === null || Array.isArray(info)) {
+        return { valid: false, errors: ['appliance info must be an object'] };
+    }
+    const value = info;
+    if (value.schemaVersion !== APPLIANCE_INFO_SCHEMA_VERSION) {
+        errors.push(`schemaVersion must be ${APPLIANCE_INFO_SCHEMA_VERSION}`);
+    }
+    if (typeof value.installationId !== 'string' || !INSTALLATION_ID.test(value.installationId)) {
+        errors.push('installationId must be a 16-64 character lowercase hex string');
+    }
+    if (typeof value.installDir !== 'string' || value.installDir.trim().length === 0) {
+        errors.push('installDir must be a non-empty string');
+    }
+    if (typeof value.hostname !== 'string' ||
+        !isValidHostname(value.hostname)) {
+        errors.push('hostname must be a valid RFC 1123 hostname');
+    }
+    if (typeof value.deploymentMode !== 'string' ||
+        !APPLIANCE_DEPLOYMENT_MODES.includes(value.deploymentMode)) {
+        errors.push(`deploymentMode must be one of ${APPLIANCE_DEPLOYMENT_MODES.join(', ')}`);
+    }
+    if (typeof value.k8sNamespace !== 'string' ||
+        !DNS_LABEL.test(value.k8sNamespace)) {
+        errors.push('k8sNamespace must be a valid DNS-1123 label');
+    }
+    if (typeof value.k8sEnvironment !== 'string' ||
+        !APPLIANCE_HELMFILE_ENVIRONMENTS.includes(value.k8sEnvironment)) {
+        errors.push(`k8sEnvironment must be one of ${APPLIANCE_HELMFILE_ENVIRONMENTS.join(', ')}`);
+    }
+    if (typeof value.versions !== 'object' || value.versions === null || Array.isArray(value.versions)) {
+        errors.push('versions must be an object');
+    }
+    else {
+        for (const [field, pin] of Object.entries(value.versions)) {
+            if (!['cli', 'web', 'vue', 'jtapi', 'ctMedia', 'syslog', 'traceroute'].includes(field)) {
+                errors.push(`versions.${field} is not a recognized component`);
+                continue;
+            }
+            if (pin !== undefined && !isScalarVersion(pin)) {
+                errors.push(`versions.${field} must be a non-empty single-token version string`);
+            }
+        }
+    }
+    if (!isIsoTimestamp(value.createdAt)) {
+        errors.push('createdAt must be an ISO timestamp');
+    }
+    if (!isIsoTimestamp(value.updatedAt)) {
+        errors.push('updatedAt must be an ISO timestamp');
+    }
+    else if (isIsoTimestamp(value.createdAt) && Date.parse(value.updatedAt) < Date.parse(value.createdAt)) {
+        errors.push('updatedAt must not be earlier than createdAt');
+    }
+    return { valid: errors.length === 0, errors };
+}
+export function assertValidApplianceInfo(info) {
+    const result = validateApplianceInfo(info);
+    if (!result.valid)
+        throw new ApplianceInfoValidationError(result.errors);
+}
+/** Resolve the persisted inventory path under the appliance k8s payload. */
+export function resolveApplianceInfoPath(installDir) {
+    return join(installDir, 'k8s', 'appliance-info.json');
+}
+/**
+ * Persist a validated inventory snapshot. The file is mode 0600 because it
+ * carries host placement details, even though it carries no credentials.
+ */
+export async function saveApplianceInfo(info, path = resolveApplianceInfoPath(info.installDir)) {
+    assertValidApplianceInfo(info);
+    await mkdirSafe(dirname(path));
+    await writeFileSafe(path, JSON.stringify(info, null, 2) + '\n', { mode: 0o600 });
+}
+/** Load and validate an inventory snapshot. Missing files return null. */
+export function loadApplianceInfo(path) {
+    if (!existsSync(path))
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, 'utf-8'));
+    }
+    catch (err) {
+        throw new ApplianceInfoValidationError([`could not parse ${path}: ${err.message}`]);
+    }
+    assertValidApplianceInfo(parsed);
+    return parsed;
+}
+/**
+ * Build a fresh snapshot from the appliance `.env`, paths, and preferences.
+ * The caller is responsible for persisting it with `saveApplianceInfo`.
+ */
+export function collectApplianceInfo(options = {}) {
+    const installDir = options.installDir ?? getPaths().installDir;
+    const env = options.env ?? readEnvKeys();
+    const prefs = options.prefs ?? getPrefs();
+    const now = options.now ?? new Date();
+    const timestamp = now.toISOString();
+    if (!prefs.deploymentMode || !APPLIANCE_DEPLOYMENT_MODES.includes(prefs.deploymentMode)) {
+        throw new ApplianceInfoValidationError(['preferences.deploymentMode is invalid']);
+    }
+    if (!prefs.k8sEnvironment || !APPLIANCE_HELMFILE_ENVIRONMENTS.includes(prefs.k8sEnvironment)) {
+        throw new ApplianceInfoValidationError(['preferences.k8sEnvironment is invalid']);
+    }
+    const versions = versionsFromEnv(env);
+    if (options.cliVersion)
+        versions.cli = options.cliVersion;
+    const info = {
+        schemaVersion: APPLIANCE_INFO_SCHEMA_VERSION,
+        installationId: deriveInstallationId(installDir, options.machineId),
+        installDir,
+        hostname: options.hostname ?? DEFAULT_APPLIANCE_HOSTNAME,
+        deploymentMode: prefs.deploymentMode,
+        k8sNamespace: prefs.k8sNamespace,
+        k8sEnvironment: prefs.k8sEnvironment,
+        versions,
+        createdAt: timestamp,
+        updatedAt: timestamp,
+    };
+    assertValidApplianceInfo(info);
+    return info;
+}
+/**
+ * Refresh an existing snapshot in place. Identity (`installationId`,
+ * `installDir`, `createdAt`) is preserved; placement, versions, and
+ * `updatedAt` are replaced.
+ */
+export function refreshApplianceInfo(previous, updates, now = new Date()) {
+    const next = {
+        ...previous,
+        ...updates,
+        updatedAt: now.toISOString(),
+    };
+    assertValidApplianceInfo(next);
+    return next;
+}
+//# sourceMappingURL=appliance-info.js.map

package/dist/lib/k8s/appliance-info.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"appliance-info.js","sourceRoot":"","sources":["../../../src/lib/k8s/appliance-info.ts"],"names":[],"mappings":"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"}

package/dist/lib/k8s/appliance-job-logger.d.ts

@@ -0,0 +1,63 @@
+export declare const JOB_LOG_SCHEMA_VERSION = 1;
+export declare const DEFAULT_JOB_LOG_MAX_BYTES: number;
+export type ApplianceJobLogLevel = 'info' | 'warn' | 'error';
+export declare const APPLIANCE_JOB_LOG_LEVELS: readonly ApplianceJobLogLevel[];
+export type ApplianceJobLogDetail = string | number | boolean;
+export interface ApplianceJobLogEvent {
+    schemaVersion: typeof JOB_LOG_SCHEMA_VERSION;
+    jobId: string;
+    seq: number;
+    at: string;
+    level: ApplianceJobLogLevel;
+    phase: string;
+    message: string;
+    details?: Record<string, ApplianceJobLogDetail>;
+}
+export interface JobLogValidation {
+    valid: boolean;
+    errors: string[];
+}
+export interface JobLogReadResult {
+    events: ApplianceJobLogEvent[];
+    invalid: Array<{
+        line: number;
+        error: string;
+    }>;
+}
+export declare class JobLogValidationError extends Error {
+    readonly errors: string[];
+    constructor(errors: string[]);
+}
+/** Redact a single string value without changing non-secret text. */
+export declare function redactJobLogValue(value: string): string;
+/** Redact secret-looking keys and URL userinfo from a detail map. */
+export declare function redactJobLogDetails(details: Record<string, unknown> | undefined): Record<string, ApplianceJobLogDetail> | undefined;
+export declare function validateJobLogEvent(event: unknown): JobLogValidation;
+export declare function assertValidJobLogEvent(event: unknown): asserts event is ApplianceJobLogEvent;
+/** Build a fully populated, redacted event. */
+export declare function createJobLogEvent(input: {
+    jobId: string;
+    seq: number;
+    phase: string;
+    message: string;
+    level?: ApplianceJobLogLevel;
+    details?: Record<string, unknown>;
+    now?: Date;
+}): ApplianceJobLogEvent;
+export declare function resolveJobLogPath(installDir: string): string;
+/**
+ * Append one event as a single JSONL record. The file is created/kept mode
+ * 0600. A permission failure falls back to passwordless `sudo tee -a`, the
+ * same contract as `writeFileSafe`.
+ */
+export declare function appendJobLogEvent(logPath: string, event: ApplianceJobLogEvent): Promise<void>;
+/** Parse the log, reporting (but not throwing on) corrupt lines. */
+export declare function readJobLog(logPath: string): JobLogReadResult;
+/** Return the most recent valid events, preserving file order. */
+export declare function tailJobLog(logPath: string, limit?: number): ApplianceJobLogEvent[];
+/**
+ * Rotate an oversized log to `<path>.1`, keeping one previous generation.
+ * Returns true when a rotation happened.
+ */
+export declare function rotateJobLogIfNeeded(logPath: string, maxBytes?: number): boolean;
+//# sourceMappingURL=appliance-job-logger.d.ts.map

package/dist/lib/k8s/appliance-job-logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"appliance-job-logger.d.ts","sourceRoot":"","sources":["../../../src/lib/k8s/appliance-job-logger.ts"],"names":[],"mappings":"AAuBA,eAAO,MAAM,sBAAsB,IAAI,CAAC;AACxC,eAAO,MAAM,yBAAyB,QAAkB,CAAC;AAEzD,MAAM,MAAM,oBAAoB,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAC7D,eAAO,MAAM,wBAAwB,EAAE,SAAS,oBAAoB,EAA8B,CAAC;AAEnG,MAAM,MAAM,qBAAqB,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAE9D,MAAM,WAAW,oBAAoB;IACnC,aAAa,EAAE,OAAO,sBAAsB,CAAC;IAC7C,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,oBAAoB,CAAC;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,qBAAqB,CAAC,CAAC;CACjD;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,oBAAoB,EAAE,CAAC;IAC/B,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACjD;AAED,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC;gBAEd,MAAM,EAAE,MAAM,EAAE;CAK7B;AA2BD,qEAAqE;AACrE,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED,qEAAqE;AACrE,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAC3C,MAAM,CAAC,MAAM,EAAE,qBAAqB,CAAC,GAAG,SAAS,CAenD;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,gBAAgB,CA0DpE;AAED,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,KAAK,IAAI,oBAAoB,CAG5F;AAED,+CAA+C;AAC/C,wBAAgB,iBAAiB,CAAC,KAAK,EAAE;IACvC,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,oBAAoB,CAAC;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ,GAAG,oBAAoB,CAcvB;AAED,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED;;;;GAIG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,oBAAoB,GAC1B,OAAO,CAAC,IAAI,CAAC,CAmBf;AAED,oEAAoE;AACpE,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,gBAAgB,CAsB5D;AAED,kEAAkE;AAClE,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,SAAK,GAAG,oBAAoB,EAAE,CAM9E;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,EACf,QAAQ,SAA4B,GACnC,OAAO,CAKT"}

package/dist/lib/k8s/appliance-job-logger.js

@@ -0,0 +1,228 @@
+/**
+ * Durable job log for appliance Kubernetes orchestration.
+ *
+ * Each job appends one JSON object per line. The log is intentionally
+ * append-only and self-describing so a failed `ct k8s sync` can be audited
+ * after the process exits, and corrupt/truncated tails are skipped rather
+ * than making the whole log unreadable.
+ *
+ * Log records never contain credentials: secret-looking detail keys and
+ * URL userinfo are redacted before the record is validated and written.
+ */
+import { appendFileSync, chmodSync, existsSync, readFileSync, renameSync, statSync, } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { execa } from 'execa';
+import { mkdirSafe } from '../fs.js';
+export const JOB_LOG_SCHEMA_VERSION = 1;
+export const DEFAULT_JOB_LOG_MAX_BYTES = 5 * 1024 * 1024;
+export const APPLIANCE_JOB_LOG_LEVELS = ['info', 'warn', 'error'];
+export class JobLogValidationError extends Error {
+    errors;
+    constructor(errors) {
+        super(`Invalid job log event: ${errors.join('; ')}`);
+        this.name = 'JobLogValidationError';
+        this.errors = errors;
+    }
+}
+const JOB_ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+const PHASE = /^[a-z][a-z0-9._-]{0,63}$/;
+const DETAIL_KEY = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+const SECRET_KEY = /(password|passwd|secret|token|credential|api[-_]?key|private[-_]?key|authorization)/i;
+const URL_USERINFO = /(:\/\/)([^/@\s:]+):([^/@\s]+)@/g;
+const MAX_MESSAGE_LENGTH = 4096;
+const MAX_DETAIL_STRING_LENGTH = 1024;
+const MAX_DETAIL_KEYS = 50;
+const REDACTED = '[redacted]';
+function isIsoTimestamp(value) {
+    return typeof value === 'string' && Number.isFinite(Date.parse(value));
+}
+function hasControlCharacter(value) {
+    // eslint-disable-next-line no-control-regex
+    return /[\u0000-\u001f\u007f]/.test(value);
+}
+function isScalarDetail(value) {
+    if (typeof value === 'number')
+        return Number.isFinite(value);
+    if (typeof value === 'boolean')
+        return true;
+    return typeof value === 'string';
+}
+/** Redact a single string value without changing non-secret text. */
+export function redactJobLogValue(value) {
+    return value.replace(URL_USERINFO, `$1$2:${REDACTED}@`);
+}
+/** Redact secret-looking keys and URL userinfo from a detail map. */
+export function redactJobLogDetails(details) {
+    if (!details)
+        return undefined;
+    const redacted = {};
+    for (const [key, raw] of Object.entries(details)) {
+        if (SECRET_KEY.test(key)) {
+            redacted[key] = REDACTED;
+            continue;
+        }
+        if (typeof raw === 'string') {
+            redacted[key] = redactJobLogValue(raw);
+        }
+        else if (typeof raw === 'number' || typeof raw === 'boolean') {
+            redacted[key] = raw;
+        }
+    }
+    return redacted;
+}
+export function validateJobLogEvent(event) {
+    const errors = [];
+    if (typeof event !== 'object' || event === null || Array.isArray(event)) {
+        return { valid: false, errors: ['event must be an object'] };
+    }
+    const value = event;
+    if (value.schemaVersion !== JOB_LOG_SCHEMA_VERSION) {
+        errors.push(`schemaVersion must be ${JOB_LOG_SCHEMA_VERSION}`);
+    }
+    if (typeof value.jobId !== 'string' || !JOB_ID.test(value.jobId)) {
+        errors.push('jobId must be a 1-128 character identifier');
+    }
+    if (!Number.isInteger(value.seq) || (value.seq ?? -1) < 0) {
+        errors.push('seq must be a non-negative integer');
+    }
+    if (!isIsoTimestamp(value.at)) {
+        errors.push('at must be an ISO timestamp');
+    }
+    if (typeof value.level !== 'string' || !APPLIANCE_JOB_LOG_LEVELS.includes(value.level)) {
+        errors.push(`level must be one of ${APPLIANCE_JOB_LOG_LEVELS.join(', ')}`);
+    }
+    if (typeof value.phase !== 'string' || !PHASE.test(value.phase)) {
+        errors.push('phase must be a lowercase phase identifier');
+    }
+    if (typeof value.message !== 'string' ||
+        value.message.length === 0 ||
+        value.message.length > MAX_MESSAGE_LENGTH ||
+        hasControlCharacter(value.message)) {
+        errors.push(`message must be a single line of 1-${MAX_MESSAGE_LENGTH} characters`);
+    }
+    if (value.details !== undefined) {
+        if (typeof value.details !== 'object' || value.details === null || Array.isArray(value.details)) {
+            errors.push('details must be an object');
+        }
+        else {
+            const entries = Object.entries(value.details);
+            if (entries.length > MAX_DETAIL_KEYS)
+                errors.push(`details must have at most ${MAX_DETAIL_KEYS} keys`);
+            for (const [key, detail] of entries) {
+                if (!DETAIL_KEY.test(key) || ['__proto__', 'constructor', 'prototype'].includes(key)) {
+                    errors.push(`details.${key} is not a valid key`);
+                    continue;
+                }
+                if (!isScalarDetail(detail)) {
+                    errors.push(`details.${key} must be a string, number, or boolean`);
+                }
+                else if (typeof detail === 'string' &&
+                    (detail.length > MAX_DETAIL_STRING_LENGTH || hasControlCharacter(detail))) {
+                    errors.push(`details.${key} must be a single line of at most ${MAX_DETAIL_STRING_LENGTH} characters`);
+                }
+            }
+        }
+    }
+    return { valid: errors.length === 0, errors };
+}
+export function assertValidJobLogEvent(event) {
+    const result = validateJobLogEvent(event);
+    if (!result.valid)
+        throw new JobLogValidationError(result.errors);
+}
+/** Build a fully populated, redacted event. */
+export function createJobLogEvent(input) {
+    const event = {
+        schemaVersion: JOB_LOG_SCHEMA_VERSION,
+        jobId: input.jobId,
+        seq: input.seq,
+        at: (input.now ?? new Date()).toISOString(),
+        level: input.level ?? 'info',
+        phase: input.phase,
+        message: redactJobLogValue(input.message),
+    };
+    const details = redactJobLogDetails(input.details);
+    if (details)
+        event.details = details;
+    assertValidJobLogEvent(event);
+    return event;
+}
+export function resolveJobLogPath(installDir) {
+    return join(installDir, 'k8s', 'jobs.jsonl');
+}
+/**
+ * Append one event as a single JSONL record. The file is created/kept mode
+ * 0600. A permission failure falls back to passwordless `sudo tee -a`, the
+ * same contract as `writeFileSafe`.
+ */
+export async function appendJobLogEvent(logPath, event) {
+    assertValidJobLogEvent(event);
+    const line = JSON.stringify(event) + '\n';
+    await mkdirSafe(dirname(logPath));
+    try {
+        appendFileSync(logPath, line, { encoding: 'utf-8', mode: 0o600 });
+        try {
+            chmodSync(logPath, 0o600);
+        }
+        catch {
+            /* chmod is best-effort on filesystems that do not support modes */
+        }
+    }
+    catch (err) {
+        if (err?.code !== 'EACCES' && err?.code !== 'EPERM')
+            throw err;
+        await execa('sudo', ['-n', 'tee', '-a', logPath], {
+            input: line,
+            stdout: 'ignore',
+            stderr: 'pipe',
+        });
+    }
+}
+/** Parse the log, reporting (but not throwing on) corrupt lines. */
+export function readJobLog(logPath) {
+    if (!existsSync(logPath))
+        return { events: [], invalid: [] };
+    const events = [];
+    const invalid = [];
+    const lines = readFileSync(logPath, 'utf-8').split('\n');
+    lines.forEach((line, index) => {
+        if (!line.trim())
+            return;
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch (err) {
+            invalid.push({ line: index + 1, error: `invalid JSON: ${err.message}` });
+            return;
+        }
+        const result = validateJobLogEvent(parsed);
+        if (!result.valid) {
+            invalid.push({ line: index + 1, error: result.errors.join('; ') });
+            return;
+        }
+        events.push(parsed);
+    });
+    return { events, invalid };
+}
+/** Return the most recent valid events, preserving file order. */
+export function tailJobLog(logPath, limit = 50) {
+    if (!Number.isInteger(limit) || limit < 0) {
+        throw new Error('limit must be a non-negative integer');
+    }
+    const { events } = readJobLog(logPath);
+    return limit === 0 ? [] : events.slice(-limit);
+}
+/**
+ * Rotate an oversized log to `<path>.1`, keeping one previous generation.
+ * Returns true when a rotation happened.
+ */
+export function rotateJobLogIfNeeded(logPath, maxBytes = DEFAULT_JOB_LOG_MAX_BYTES) {
+    if (!existsSync(logPath))
+        return false;
+    if (statSync(logPath).size <= maxBytes)
+        return false;
+    renameSync(logPath, `${logPath}.1`);
+    return true;
+}
+//# sourceMappingURL=appliance-job-logger.js.map

package/dist/lib/k8s/appliance-job-logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"appliance-job-logger.js","sourceRoot":"","sources":["../../../src/lib/k8s/appliance-job-logger.ts"],"names":[],"mappings":"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"}