@ascendkit/cli 0.3.0 → 0.3.1

package/dist/commands/platform.js

@@ -3,6 +3,8 @@ import { readdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { loadAuth, loadEnvContext, saveAuth, deleteAuth, saveEnvContext, ensureGitignore, } from "../utils/credentials.js";
 import { DEFAULT_API_URL, DEFAULT_PORTAL_URL } from "../constants.js";
+import { exitCli } from "../utils/exit.js";
+import { correlationHeaders } from "../utils/correlation.js";
 const POLL_INTERVAL_MS = 2000;
 const DEVICE_CODE_EXPIRY_MS = 300_000; // 5 minutes
 const IGNORE_DIRS = new Set([".git", "node_modules", ".next", "dist", "build"]);
@@ -339,7 +341,10 @@ function generateDeviceCode() {
     return code;
 }
 async function apiRequest(apiUrl, method, path, body, token, publicKey) {
-    const headers = { "Content-Type": "application/json" };
+    const headers = {
+        "Content-Type": "application/json",
+        ...correlationHeaders(),
+    };
     if (token)
         headers["Authorization"] = `Bearer ${token}`;
     if (publicKey)
@@ -471,7 +476,8 @@ function requireAuth() {
     const auth = loadAuth();
     if (!auth?.token) {
         console.error("Not initialized. Run: ascendkit init");
-        process.exit(1);
+        exitCli(1);
+        throw new Error("unreachable"); // exitCli terminates the process
     }
     return auth;
 }

package/dist/utils/correlation.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Correlation IDs for request tracing.
+ *
+ * - `invocationId`      — one UUID per CLI process (lazy-initialized)
+ * - `clientRequestId`   — fresh UUID per outbound HTTP request
+ * - `machineId`         — persisted at ~/.ascendkit/machine-id, generated once
+ */
+export declare function getInvocationId(): string;
+export declare function generateClientRequestId(): string;
+export declare function correlationHeaders(): Record<string, string>;
+export declare function getMachineId(): string;

package/dist/utils/correlation.js

@@ -0,0 +1,67 @@
+/**
+ * Correlation IDs for request tracing.
+ *
+ * - `invocationId`      — one UUID per CLI process (lazy-initialized)
+ * - `clientRequestId`   — fresh UUID per outbound HTTP request
+ * - `machineId`         — persisted at ~/.ascendkit/machine-id, generated once
+ */
+import { randomUUID } from "node:crypto";
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+// ---------------------------------------------------------------------------
+// Invocation ID — one per process
+// ---------------------------------------------------------------------------
+let _invocationId;
+export function getInvocationId() {
+    if (!_invocationId) {
+        _invocationId = randomUUID();
+    }
+    return _invocationId;
+}
+// ---------------------------------------------------------------------------
+// Client Request ID — one per outbound request
+// ---------------------------------------------------------------------------
+export function generateClientRequestId() {
+    return randomUUID();
+}
+// ---------------------------------------------------------------------------
+// Correlation headers (added to every AscendKit API call)
+// ---------------------------------------------------------------------------
+export function correlationHeaders() {
+    return {
+        "X-AscendKit-Invocation-Id": getInvocationId(),
+        "X-AscendKit-Client-Request-Id": generateClientRequestId(),
+    };
+}
+// ---------------------------------------------------------------------------
+// Machine ID — persisted in ~/.ascendkit/machine-id
+// ---------------------------------------------------------------------------
+const MACHINE_ID_DIR = join(homedir(), ".ascendkit");
+const MACHINE_ID_PATH = join(MACHINE_ID_DIR, "machine-id");
+let _machineId;
+export function getMachineId() {
+    if (_machineId)
+        return _machineId;
+    try {
+        const stored = readFileSync(MACHINE_ID_PATH, "utf-8").trim();
+        if (stored) {
+            _machineId = stored;
+            return _machineId;
+        }
+    }
+    catch {
+        // File doesn't exist yet — will create below.
+    }
+    _machineId = randomUUID();
+    try {
+        if (!existsSync(MACHINE_ID_DIR)) {
+            mkdirSync(MACHINE_ID_DIR, { recursive: true });
+        }
+        writeFileSync(MACHINE_ID_PATH, _machineId, "utf-8");
+    }
+    catch {
+        // Non-fatal — we still have the in-memory value for this session.
+    }
+    return _machineId;
+}

package/dist/utils/exit.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Centralized CLI exit handler.
+ *
+ * All CLI termination routes through `exitCli()` so that telemetry hooks
+ * (and any future cleanup) can run before the process exits.
+ */
+type ExitHook = (code: number, error?: Error) => void | Promise<void>;
+/**
+ * Register a callback that runs before the process exits.
+ * Hooks execute in registration order with a bounded timeout.
+ */
+export declare function onExit(callback: ExitHook): void;
+/**
+ * Central exit point for the CLI.
+ * Runs all registered hooks (with timeout), then calls `process.exit(code)`.
+ */
+export declare function exitCli(code: number, error?: Error): Promise<never>;
+/**
+ * Install global handlers for uncaught exceptions and unhandled rejections.
+ * Routes them through the central exit handler.
+ */
+export declare function installGlobalHandlers(): void;
+export {};

package/dist/utils/exit.js

@@ -0,0 +1,64 @@
+/**
+ * Centralized CLI exit handler.
+ *
+ * All CLI termination routes through `exitCli()` so that telemetry hooks
+ * (and any future cleanup) can run before the process exits.
+ */
+const hooks = [];
+let exiting = false;
+const EXIT_HOOK_TIMEOUT_MS = 3_000;
+/**
+ * Register a callback that runs before the process exits.
+ * Hooks execute in registration order with a bounded timeout.
+ */
+export function onExit(callback) {
+    hooks.push(callback);
+}
+/**
+ * Central exit point for the CLI.
+ * Runs all registered hooks (with timeout), then calls `process.exit(code)`.
+ */
+export async function exitCli(code, error) {
+    // Guard against re-entrant calls (e.g. hook triggers another exit)
+    if (exiting) {
+        process.exit(code);
+    }
+    exiting = true;
+    if (hooks.length > 0) {
+        try {
+            await Promise.race([
+                runHooks(code, error),
+                new Promise((resolve) => setTimeout(resolve, EXIT_HOOK_TIMEOUT_MS)),
+            ]);
+        }
+        catch {
+            // Hooks must never prevent exit
+        }
+    }
+    process.exit(code);
+}
+async function runHooks(code, error) {
+    for (const hook of hooks) {
+        try {
+            await hook(code, error);
+        }
+        catch {
+            // Individual hook failures are silently ignored
+        }
+    }
+}
+/**
+ * Install global handlers for uncaught exceptions and unhandled rejections.
+ * Routes them through the central exit handler.
+ */
+export function installGlobalHandlers() {
+    process.on("uncaughtException", (err) => {
+        console.error(err.message ?? err);
+        exitCli(1, err instanceof Error ? err : new Error(String(err)));
+    });
+    process.on("unhandledRejection", (reason) => {
+        const msg = reason instanceof Error ? reason.message : String(reason);
+        console.error(msg);
+        exitCli(1, reason instanceof Error ? reason : new Error(String(reason)));
+    });
+}

package/dist/utils/redaction.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Argument redaction for CLI telemetry.
+ *
+ * Strips secret-bearing flags and large payloads from argv before
+ * telemetry transport, while preserving AscendKit entity IDs that
+ * are useful for debugging.
+ */
+/**
+ * Redact command arguments for safe telemetry transport.
+ *
+ * - `--secret-flag value`   → `--secret-flag [REDACTED]`
+ * - `--secret-flag=value`   → `--secret-flag=[REDACTED]`
+ * - Long values (>100 chars) → `[REDACTED]`
+ * - AscendKit entity IDs are preserved regardless of length
+ */
+export declare function redactArgs(argv: string[]): string[];

package/dist/utils/redaction.js

@@ -0,0 +1,114 @@
+/**
+ * Argument redaction for CLI telemetry.
+ *
+ * Strips secret-bearing flags and large payloads from argv before
+ * telemetry transport, while preserving AscendKit entity IDs that
+ * are useful for debugging.
+ */
+/** Flags whose values must always be redacted. */
+const SECRET_FLAGS = new Set([
+    "secret-key",
+    "token",
+    "password",
+    "api-key",
+    "client-secret",
+    "client-secret-stdin",
+    "authorization",
+    "bearer",
+    "cookie",
+]);
+/** AscendKit entity ID prefixes — values matching these are safe to keep. */
+const ENTITY_ID_RE = /^(cli|mem|prj|usr|tpl|srv|inv|ses|env|whk|cpn)_[a-zA-Z0-9]+$/;
+const MAX_VALUE_LENGTH = 100;
+/**
+ * Returns true if a value looks like an AscendKit entity ID and is safe to keep.
+ */
+function isEntityId(value) {
+    return ENTITY_ID_RE.test(value);
+}
+/**
+ * Determines whether a plain (non-flag) value should be redacted.
+ * Entity IDs are preserved; long values are redacted.
+ */
+function shouldRedactValue(value) {
+    if (isEntityId(value))
+        return false;
+    return value.length > MAX_VALUE_LENGTH;
+}
+/**
+ * Extract the flag name from a `--flag` or `--flag=value` argument.
+ */
+function extractFlagName(arg) {
+    if (!arg.startsWith("--"))
+        return null;
+    const eqIdx = arg.indexOf("=");
+    return eqIdx === -1 ? arg.slice(2) : arg.slice(2, eqIdx);
+}
+/**
+ * Redact command arguments for safe telemetry transport.
+ *
+ * - `--secret-flag value`   → `--secret-flag [REDACTED]`
+ * - `--secret-flag=value`   → `--secret-flag=[REDACTED]`
+ * - Long values (>100 chars) → `[REDACTED]`
+ * - AscendKit entity IDs are preserved regardless of length
+ */
+export function redactArgs(argv) {
+    const result = [];
+    let redactNext = false;
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        // If the previous flag was a secret flag, redact this positional value
+        if (redactNext) {
+            redactNext = false;
+            result.push("[REDACTED]");
+            continue;
+        }
+        // Handle --flag=value form
+        const eqIdx = arg.indexOf("=");
+        if (arg.startsWith("--") && eqIdx !== -1) {
+            const flagName = arg.slice(2, eqIdx);
+            if (SECRET_FLAGS.has(flagName)) {
+                result.push(`--${flagName}=[REDACTED]`);
+            }
+            else {
+                const value = arg.slice(eqIdx + 1);
+                if (shouldRedactValue(value)) {
+                    result.push(`--${flagName}=[REDACTED]`);
+                }
+                else {
+                    result.push(arg);
+                }
+            }
+            continue;
+        }
+        // Handle --flag (next arg is the value)
+        if (arg.startsWith("--")) {
+            const flagName = extractFlagName(arg);
+            if (flagName && SECRET_FLAGS.has(flagName)) {
+                result.push(arg);
+                // Check if next arg is a value (not another flag)
+                if (i + 1 < argv.length && !argv[i + 1].startsWith("--")) {
+                    redactNext = true;
+                }
+            }
+            else {
+                result.push(arg);
+                // Check if next arg is a long value that needs redaction
+                if (i + 1 < argv.length &&
+                    !argv[i + 1].startsWith("--") &&
+                    shouldRedactValue(argv[i + 1])) {
+                    redactNext = true;
+                }
+            }
+            continue;
+        }
+        // Plain positional argument — redact if too long (but not entity IDs)
+        if (shouldRedactValue(arg)) {
+            result.push("[REDACTED]");
+        }
+        else {
+            result.push(arg);
+        }
+    }
+    return result;
+}

package/dist/utils/telemetry.d.ts

@@ -0,0 +1,32 @@
+/**
+ * CLI command telemetry.
+ *
+ * Best-effort delivery — telemetry failures are silently swallowed and
+ * never affect command outcome.
+ */
+export interface TelemetryRecord {
+    invocationId: string;
+    machineId: string;
+    clientType: "cli";
+    clientVersion: string;
+    command: string;
+    domain: string | null;
+    action: string | null;
+    args: string[];
+    dtEntered: string;
+    dtCompleted: string;
+    durationMs: number;
+    success: boolean;
+    errorMessage: string | null;
+    hostname: string;
+    os: string;
+    nodeVersion: string;
+}
+/**
+ * Send a telemetry record to the backend.
+ *
+ * Best-effort: uses a short timeout and catches all errors silently.
+ * Includes the bearer token when available so the server can attribute
+ * the record to a user, but works without authentication.
+ */
+export declare function captureTelemetry(record: TelemetryRecord): Promise<void>;

package/dist/utils/telemetry.js

@@ -0,0 +1,47 @@
+/**
+ * CLI command telemetry.
+ *
+ * Best-effort delivery — telemetry failures are silently swallowed and
+ * never affect command outcome.
+ */
+import { DEFAULT_API_URL } from "../constants.js";
+import { loadAuth } from "./credentials.js";
+import { correlationHeaders } from "./correlation.js";
+const TELEMETRY_TIMEOUT_MS = 5_000;
+const TELEMETRY_PATH = "/api/telemetry/cli-command";
+/**
+ * Send a telemetry record to the backend.
+ *
+ * Best-effort: uses a short timeout and catches all errors silently.
+ * Includes the bearer token when available so the server can attribute
+ * the record to a user, but works without authentication.
+ */
+export async function captureTelemetry(record) {
+    try {
+        const auth = loadAuth();
+        const baseUrl = auth?.apiUrl ?? DEFAULT_API_URL;
+        const headers = {
+            "Content-Type": "application/json",
+            ...correlationHeaders(),
+        };
+        if (auth?.token) {
+            headers["Authorization"] = `Bearer ${auth.token}`;
+        }
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), TELEMETRY_TIMEOUT_MS);
+        try {
+            await fetch(`${baseUrl}${TELEMETRY_PATH}`, {
+                method: "POST",
+                headers,
+                body: JSON.stringify(record),
+                signal: controller.signal,
+            });
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+    catch {
+        // Best-effort — silently ignore all errors
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ascendkit/cli",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "AscendKit CLI and MCP server",
   "author": "ascendkit.dev",
   "license": "MIT",