@ascendkit/cli 0.2.6 → 0.3.1

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/journey-format.d.ts

@@ -13,6 +13,11 @@ interface JourneyData {
     nodes: Record<string, {
         action?: {
             type?: string;
+            templateSlug?: string;
+            surveySlug?: string;
+            tagName?: string;
+            stageName?: string;
+            fromIdentityEmail?: string;
         };
         terminal?: boolean;
     }>;
@@ -83,6 +88,7 @@ interface NodeListItem {
         surveySlug?: string;
         tagName?: string;
         stageName?: string;
+        fromIdentityEmail?: string;
     };
     terminal: boolean;
     isEntryNode: boolean;

package/dist/utils/journey-format.js

@@ -32,7 +32,7 @@ export function formatJourneyWithGuidance(journey) {
     lines.push("");
     lines.push("Nodes:");
     for (const [name, node] of Object.entries(journey.nodes || {})) {
-        const action = node.action?.type || "none";
+        const action = formatActionLabel(node.action || {});
         const terminal = node.terminal ? " (terminal)" : "";
         const isEntry = name === journey.entryNode ? " [entry]" : "";
         lines.push(`  ${name}: ${action}${terminal}${isEntry}`);
@@ -70,7 +70,7 @@ export function formatJourneyWithGuidance(journey) {
         hints.push("Journey is active and enrolling users. Use journey_analytics to see user flow.");
     }
     else if (journey.status === "paused") {
-        hints.push("Journey is paused. Actions are queued. Use journey_activate to resume.");
+        hints.push("Journey is paused. Actions are queued. Use journey_resume to continue delivery.");
     }
     else if (journey.status === "archived") {
         hints.push("Journey is archived. No further enrollment or transitions.");
@@ -113,6 +113,8 @@ function formatActionLabel(action) {
     const type = action?.type || "none";
     if (type === "send_email") {
         const parts = [`send_email (${action.templateSlug || "?"})`];
+        if (action.fromIdentityEmail)
+            parts.push(`from: ${action.fromIdentityEmail}`);
         if (action.surveySlug)
             parts.push(`+ survey: ${action.surveySlug}`);
         return parts.join(" ");
@@ -131,7 +133,7 @@ function formatTriggerLabel(trigger) {
 export function formatNodeList(data) {
     const nodes = data.nodes || [];
     if (nodes.length === 0) {
-        return "No nodes. Use journey_add_node to add the first node.";
+        return "No nodes. Use journey_node_add to add the first node.";
     }
     const lines = [`${nodes.length} node(s):\n`];
     for (const n of nodes) {
@@ -150,7 +152,7 @@ export function formatSingleNode(data, action, nodeName) {
 export function formatTransitionList(data) {
     const transitions = data.transitions || [];
     if (transitions.length === 0) {
-        return "No transitions. Use journey_add_transition to connect nodes.";
+        return "No transitions. Use journey_transition_add to connect nodes.";
     }
     const lines = [`${transitions.length} transition(s):\n`];
     for (const t of transitions) {

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/survey-format.js

@@ -84,11 +84,11 @@ export function formatSurveyWithGuidance(survey) {
     // Next steps based on current state
     const hints = [];
     if (questionCount === 0) {
-        hints.push("This survey has no questions yet. Use survey_add_question to add questions, or survey_list_questions to see supported question types.");
+        hints.push("This survey has no questions yet. Use survey_question_add to add questions, or survey_question_list to see supported question types.");
     }
     else if (survey.status === "draft") {
         hints.push(`Survey has ${questionCount} question(s) and is in draft. Use survey_update with status 'active' to activate it for distribution.`);
-        hints.push("Use survey_list_questions to review the questions before activating.");
+        hints.push("Use survey_question_list to review the questions before activating.");
     }
     else if (survey.status === "active" && responseCount === 0) {
         hints.push("Survey is active and ready to distribute. Use survey_distribute with a list of user IDs to create personalized tracking links.");

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.2.6",
+  "version": "0.3.1",
   "description": "AscendKit CLI and MCP server",
   "author": "ascendkit.dev",
   "license": "MIT",
@@ -33,11 +33,11 @@
     "start": "node dist/cli.js"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.0.0",
-    "zod": "^3.23.0"
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "zod": "^3.25.76"
   },
   "devDependencies": {
-    "typescript": "^5.7.0",
-    "@types/node": "^22.0.0"
+    "@types/node": "^25.5.0",
+    "typescript": "^5.7.0"
   }
 }