pax8-cta 0.1.0

package/dist/lib/spinner.d.ts

@@ -0,0 +1,41 @@
+/**
+ * REPL-safe spinner wrapper.
+ *
+ * ora's spinner animation corrupts readline's terminal state,
+ * breaking subsequent prompts in the REPL. This module provides
+ * the same API but falls back to plain console.log when stdin
+ * is being shared with readline (i.e. in REPL / interactive mode).
+ *
+ * In quiet mode (--quiet flag or PAX8_CTA_QUIET=1) all spinners are
+ * replaced with a no-op implementation that produces zero output.
+ */
+export declare function setReplMode(enabled: boolean): void;
+/**
+ * Returns true when the process is running in quiet mode.
+ *
+ * Quiet mode is active when either:
+ *   - `--quiet` appears anywhere in the raw argv (catches global flag before
+ *     Commander has finished parsing subcommands), or
+ *   - the environment variable `PAX8_CTA_QUIET` is set to "1" or "true"
+ *     (allows CI pipelines to opt in without modifying every invocation).
+ */
+export declare function isQuietMode(): boolean;
+export interface Spinner {
+    text: string;
+    start(text?: string): Spinner;
+    stop(): Spinner;
+    succeed(text?: string): Spinner;
+    fail(text?: string): Spinner;
+    warn(text?: string): Spinner;
+    info(text?: string): Spinner;
+}
+/**
+ * Drop-in replacement for `ora(text).start()`.
+ *
+ * - In quiet mode returns a no-op spinner that produces zero output.
+ * - In REPL mode returns a plain-text spinner that won't corrupt readline.
+ * - Otherwise returns a real ora spinner with animation.
+ */
+export { createSpinner as spinner };
+export declare function createSpinner(text?: string): Spinner;
+//# sourceMappingURL=spinner.d.ts.map

package/dist/lib/spinner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spinner.d.ts","sourceRoot":"","sources":["../../src/lib/spinner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAOH,wBAAgB,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAElD;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,IAAI,OAAO,CAMrC;AAED,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAC9B,IAAI,IAAI,OAAO,CAAC;IAChB,OAAO,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAChC,IAAI,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAC7B,IAAI,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAC7B,IAAI,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CAC9B;AA2ED;;;;;;GAMG;AACH,OAAO,EAAE,aAAa,IAAI,OAAO,EAAE,CAAC;AAEpC,wBAAgB,aAAa,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAQpD"}

package/dist/lib/spinner.js

@@ -0,0 +1,126 @@
+/**
+ * REPL-safe spinner wrapper.
+ *
+ * ora's spinner animation corrupts readline's terminal state,
+ * breaking subsequent prompts in the REPL. This module provides
+ * the same API but falls back to plain console.log when stdin
+ * is being shared with readline (i.e. in REPL / interactive mode).
+ *
+ * In quiet mode (--quiet flag or PAX8_CTA_QUIET=1) all spinners are
+ * replaced with a no-op implementation that produces zero output.
+ */
+import ora from "ora";
+/** True when running inside the interactive REPL. */
+let replMode = false;
+export function setReplMode(enabled) {
+    replMode = enabled;
+}
+/**
+ * Returns true when the process is running in quiet mode.
+ *
+ * Quiet mode is active when either:
+ *   - `--quiet` appears anywhere in the raw argv (catches global flag before
+ *     Commander has finished parsing subcommands), or
+ *   - the environment variable `PAX8_CTA_QUIET` is set to "1" or "true"
+ *     (allows CI pipelines to opt in without modifying every invocation).
+ */
+export function isQuietMode() {
+    return (process.argv.includes("--quiet") ||
+        process.env.PAX8_CTA_QUIET === "1" ||
+        process.env.PAX8_CTA_QUIET === "true");
+}
+function createPlainSpinner(text) {
+    let currentText = text ?? "";
+    const self = {
+        get text() {
+            return currentText;
+        },
+        set text(t) {
+            currentText = t;
+        },
+        start(t) {
+            if (t)
+                currentText = t;
+            return self;
+        },
+        stop() {
+            return self;
+        },
+        succeed(t) {
+            console.error(`✔ ${t ?? currentText}`);
+            return self;
+        },
+        fail(t) {
+            console.error(`✖ ${t ?? currentText}`);
+            return self;
+        },
+        warn(t) {
+            console.error(`⚠ ${t ?? currentText}`);
+            return self;
+        },
+        info(t) {
+            console.error(`ℹ ${t ?? currentText}`);
+            return self;
+        },
+    };
+    return self;
+}
+/** No-op spinner used in quiet mode — produces zero output on any method call. */
+function createNoOpSpinner(text) {
+    let currentText = text ?? "";
+    const self = {
+        get text() {
+            return currentText;
+        },
+        set text(t) {
+            currentText = t;
+        },
+        start(t) {
+            if (t)
+                currentText = t;
+            return self;
+        },
+        stop() {
+            return self;
+        },
+        succeed(t) {
+            if (t)
+                currentText = t;
+            return self;
+        },
+        fail(t) {
+            if (t)
+                currentText = t;
+            return self;
+        },
+        warn(t) {
+            if (t)
+                currentText = t;
+            return self;
+        },
+        info(t) {
+            if (t)
+                currentText = t;
+            return self;
+        },
+    };
+    return self;
+}
+/**
+ * Drop-in replacement for `ora(text).start()`.
+ *
+ * - In quiet mode returns a no-op spinner that produces zero output.
+ * - In REPL mode returns a plain-text spinner that won't corrupt readline.
+ * - Otherwise returns a real ora spinner with animation.
+ */
+export { createSpinner as spinner };
+export function createSpinner(text) {
+    if (isQuietMode()) {
+        return createNoOpSpinner(text);
+    }
+    if (replMode) {
+        return createPlainSpinner(text);
+    }
+    return ora({ text, stream: process.stderr });
+}
+//# sourceMappingURL=spinner.js.map

package/dist/lib/spinner.js.map

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

package/dist/lib/telemetry.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Copyright 2024 Pax8, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Check if telemetry is enabled
+ */
+export declare function isTelemetryEnabled(): boolean;
+/**
+ * Enable telemetry
+ */
+export declare function enableTelemetry(): void;
+/**
+ * Disable telemetry
+ */
+export declare function disableTelemetry(): void;
+/**
+ * Check if first run notice has been shown
+ */
+export declare function hasShownFirstRunNotice(): boolean;
+/**
+ * Mark first run notice as shown
+ */
+export declare function markFirstRunNoticeShown(): void;
+/**
+ * Filesystem path to the Conf-managed telemetry preferences file.
+ * Used by `pax8-cta config` to surface where preferences live.
+ */
+export declare function getTelemetryConfigPath(): string;
+/**
+ * Stored telemetry preference (ignores env-var overrides).
+ *
+ * `isTelemetryEnabled()` factors in env-var opt-outs (DO_NOT_TRACK,
+ * PAX8_CTA_TELEMETRY_DISABLED, CI, missing PostHog key). This raw getter
+ * lets `config` distinguish a user's saved choice from a runtime override.
+ */
+export declare function getStoredTelemetryPreference(): boolean;
+/**
+ * Reason telemetry is currently disabled, if it is.
+ *
+ * Mirrors the precedence inside `isTelemetryEnabled()`:
+ *   1. PAX8_CTA_TELEMETRY_DISABLED env var
+ *   2. DO_NOT_TRACK env var
+ *   3. CI env var
+ *   4. Missing PostHog key
+ *   5. User preference (config file)
+ *
+ * Returns `null` when telemetry is enabled.
+ */
+export declare function getTelemetryDisabledSource(): "env" | "do-not-track" | "ci" | "no-key" | "config" | null;
+/**
+ * Shutdown telemetry client gracefully
+ */
+export declare function shutdownTelemetry(): Promise<void>;
+export type TelemetryEvent = "cli_command" | "cli_error" | "cli_not_found" | "cli_first_run";
+export interface CommandContext {
+    command: string;
+    subcommand?: string;
+    flags?: string[];
+    success: boolean;
+    durationMs: number;
+    errorType?: string;
+    demoMode?: boolean;
+}
+/**
+ * Track a CLI command execution
+ */
+export declare function trackCommand(ctx: CommandContext): void;
+/**
+ * Track a "not found" error (like a 404)
+ */
+export declare function trackNotFound(resource: "tenant" | "deployment" | "agent" | "command", query: string): void;
+/**
+ * Track an error (without sensitive details)
+ */
+export declare function trackError(errorType: string, command?: string): void;
+/**
+ * Track first run
+ */
+export declare function trackFirstRun(): void;
+/**
+ * Get the first run notice text
+ */
+export declare function getFirstRunNotice(): string;
+//# sourceMappingURL=telemetry.d.ts.map

package/dist/lib/telemetry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.d.ts","sourceRoot":"","sources":["../../src/lib/telemetry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAqFH;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,OAAO,CA8B5C;AAED;;GAEG;AACH,wBAAgB,eAAe,IAAI,IAAI,CAMtC;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,IAAI,CAMvC;AAED;;GAEG;AACH,wBAAgB,sBAAsB,IAAI,OAAO,CAMhD;AAED;;GAEG;AACH,wBAAgB,uBAAuB,IAAI,IAAI,CAM9C;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,IAAI,MAAM,CAE/C;AAED;;;;;;GAMG;AACH,wBAAgB,4BAA4B,IAAI,OAAO,CAMtD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,0BAA0B,IACtC,KAAK,GACL,cAAc,GACd,IAAI,GACJ,QAAQ,GACR,QAAQ,GACR,IAAI,CAYP;AA2CD;;GAEG;AACH,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC,CAcvD;AAMD,MAAM,MAAM,cAAc,GAAG,aAAa,GAAG,WAAW,GAAG,eAAe,GAAG,eAAe,CAAC;AAE7F,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,cAAc,GAAG,IAAI,CA6BtD;AAED;;GAEG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,QAAQ,GAAG,YAAY,GAAG,OAAO,GAAG,SAAS,EACvD,KAAK,EAAE,MAAM,GACZ,IAAI,CA0BN;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAsBpE;AAED;;GAEG;AACH,wBAAgB,aAAa,IAAI,IAAI,CAqBpC;AAMD;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAU1C"}

package/dist/lib/telemetry.js

@@ -0,0 +1,367 @@
+/**
+ * Copyright 2024 Pax8, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import Conf from "conf";
+import { createHash } from "crypto";
+import { hostname } from "os";
+// ============================================================================
+// Configuration
+// ============================================================================
+const CLI_VERSION = "0.1.0";
+// PostHog project key - safe to be public, only allows event ingestion
+const POSTHOG_KEY = process.env.PAX8_CTA_POSTHOG_KEY || process.env.NEXT_PUBLIC_POSTHOG_KEY || "";
+const POSTHOG_HOST = process.env.PAX8_CTA_POSTHOG_HOST || "https://us.i.posthog.com";
+// Config store for telemetry preferences
+const config = new Conf({
+    projectName: "pax8-cta-cli",
+    defaults: {
+        telemetryEnabled: false, // Opt-in: disabled by default, enable with `pax8-cta telemetry on`
+        firstRunShown: false,
+        machineId: "",
+    },
+});
+// ============================================================================
+// Machine ID (anonymous)
+// ============================================================================
+/**
+ * Get or create an anonymous machine ID.
+ * This is a one-way hash - cannot be reversed to identify the machine.
+ */
+function getMachineId() {
+    let machineId = config.get("machineId");
+    if (!machineId) {
+        // Create anonymous hash from hostname + random salt
+        const salt = Math.random().toString(36).substring(2);
+        const raw = `${hostname()}-${salt}-${Date.now()}`;
+        machineId = createHash("sha256").update(raw).digest("hex").substring(0, 16);
+        config.set("machineId", machineId);
+    }
+    return machineId;
+}
+// ============================================================================
+// Telemetry State
+// ============================================================================
+/**
+ * Check if telemetry is enabled
+ */
+export function isTelemetryEnabled() {
+    // Environment variable override (highest priority)
+    if (process.env.PAX8_CTA_TELEMETRY_DISABLED === "1" ||
+        process.env.PAX8_CTA_TELEMETRY_DISABLED === "true") {
+        return false;
+    }
+    // Respect DO_NOT_TRACK convention (https://consoledonottrack.com)
+    if (process.env.DO_NOT_TRACK === "1") {
+        return false;
+    }
+    // CI environments - disable by default
+    if (process.env.CI === "true" || process.env.CI === "1") {
+        return false;
+    }
+    // No PostHog key configured
+    if (!POSTHOG_KEY) {
+        return false;
+    }
+    // User preference
+    try {
+        return config.get("telemetryEnabled");
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Enable telemetry
+ */
+export function enableTelemetry() {
+    try {
+        config.set("telemetryEnabled", true);
+    }
+    catch {
+        // Non-fatal: telemetry preference persistence should not break CLI.
+    }
+}
+/**
+ * Disable telemetry
+ */
+export function disableTelemetry() {
+    try {
+        config.set("telemetryEnabled", false);
+    }
+    catch {
+        // Non-fatal: telemetry preference persistence should not break CLI.
+    }
+}
+/**
+ * Check if first run notice has been shown
+ */
+export function hasShownFirstRunNotice() {
+    try {
+        return config.get("firstRunShown");
+    }
+    catch {
+        return true;
+    }
+}
+/**
+ * Mark first run notice as shown
+ */
+export function markFirstRunNoticeShown() {
+    try {
+        config.set("firstRunShown", true);
+    }
+    catch {
+        // Non-fatal: telemetry preference persistence should not break CLI.
+    }
+}
+/**
+ * Filesystem path to the Conf-managed telemetry preferences file.
+ * Used by `pax8-cta config` to surface where preferences live.
+ */
+export function getTelemetryConfigPath() {
+    return config.path;
+}
+/**
+ * Stored telemetry preference (ignores env-var overrides).
+ *
+ * `isTelemetryEnabled()` factors in env-var opt-outs (DO_NOT_TRACK,
+ * PAX8_CTA_TELEMETRY_DISABLED, CI, missing PostHog key). This raw getter
+ * lets `config` distinguish a user's saved choice from a runtime override.
+ */
+export function getStoredTelemetryPreference() {
+    try {
+        return config.get("telemetryEnabled");
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Reason telemetry is currently disabled, if it is.
+ *
+ * Mirrors the precedence inside `isTelemetryEnabled()`:
+ *   1. PAX8_CTA_TELEMETRY_DISABLED env var
+ *   2. DO_NOT_TRACK env var
+ *   3. CI env var
+ *   4. Missing PostHog key
+ *   5. User preference (config file)
+ *
+ * Returns `null` when telemetry is enabled.
+ */
+export function getTelemetryDisabledSource() {
+    if (process.env.PAX8_CTA_TELEMETRY_DISABLED === "1" ||
+        process.env.PAX8_CTA_TELEMETRY_DISABLED === "true") {
+        return "env";
+    }
+    if (process.env.DO_NOT_TRACK === "1")
+        return "do-not-track";
+    if (process.env.CI === "true" || process.env.CI === "1")
+        return "ci";
+    if (!POSTHOG_KEY)
+        return "no-key";
+    if (!getStoredTelemetryPreference())
+        return "config";
+    return null;
+}
+// ============================================================================
+// PostHog Client
+// ============================================================================
+let client = null;
+let clientPromise = null;
+async function getClient() {
+    if (!isTelemetryEnabled()) {
+        return null;
+    }
+    if (client) {
+        return client;
+    }
+    // De-duplicate concurrent initializations
+    if (!clientPromise) {
+        clientPromise = (async () => {
+            try {
+                // Lazy-load posthog-node so the dependency isn't pulled into
+                // every cold start (telemetry is opt-in; most invocations skip this).
+                const mod = await import("posthog-node");
+                const PostHogCtor = mod.PostHog;
+                client = new PostHogCtor(POSTHOG_KEY, {
+                    host: POSTHOG_HOST,
+                    flushAt: 10,
+                    flushInterval: 30000, // 30 seconds
+                });
+                return client;
+            }
+            catch {
+                // posthog-node may not be installed (e.g. trimmed bundle).
+                // Telemetry should silently no-op rather than break the CLI.
+                return null;
+            }
+        })();
+    }
+    return clientPromise;
+}
+/**
+ * Shutdown telemetry client gracefully
+ */
+export async function shutdownTelemetry() {
+    try {
+        // If a client init is still in flight, wait for it so we can flush.
+        if (clientPromise) {
+            await clientPromise;
+        }
+        if (client) {
+            await client.shutdown();
+            client = null;
+        }
+        clientPromise = null;
+    }
+    catch {
+        // Telemetry should never affect CLI functionality
+    }
+}
+/**
+ * Track a CLI command execution
+ */
+export function trackCommand(ctx) {
+    // Fast-path: avoid even kicking off the dynamic import if telemetry is off.
+    if (!isTelemetryEnabled())
+        return;
+    void (async () => {
+        try {
+            const posthog = await getClient();
+            if (!posthog)
+                return;
+            posthog.capture({
+                distinctId: getMachineId(),
+                event: "cli_command",
+                properties: {
+                    command: ctx.command,
+                    subcommand: ctx.subcommand,
+                    flags: ctx.flags,
+                    success: ctx.success,
+                    duration_ms: ctx.durationMs,
+                    error_type: ctx.errorType,
+                    demo_mode: ctx.demoMode,
+                    cli_version: CLI_VERSION,
+                    os: process.platform,
+                    node_version: process.version,
+                },
+            });
+        }
+        catch {
+            // Telemetry should never affect CLI functionality
+        }
+    })();
+}
+/**
+ * Track a "not found" error (like a 404)
+ */
+export function trackNotFound(resource, query) {
+    if (!isTelemetryEnabled())
+        return;
+    // Hash the query synchronously so we don't hold a reference to the raw value.
+    const queryHash = createHash("sha256").update(query).digest("hex").substring(0, 8);
+    void (async () => {
+        try {
+            const posthog = await getClient();
+            if (!posthog)
+                return;
+            // Don't track the actual query value for privacy - just the resource type
+            posthog.capture({
+                distinctId: getMachineId(),
+                event: "cli_not_found",
+                properties: {
+                    resource_type: resource,
+                    query_hash: queryHash,
+                    cli_version: CLI_VERSION,
+                    os: process.platform,
+                },
+            });
+        }
+        catch {
+            // Telemetry should never affect CLI functionality
+        }
+    })();
+}
+/**
+ * Track an error (without sensitive details)
+ */
+export function trackError(errorType, command) {
+    if (!isTelemetryEnabled())
+        return;
+    void (async () => {
+        try {
+            const posthog = await getClient();
+            if (!posthog)
+                return;
+            posthog.capture({
+                distinctId: getMachineId(),
+                event: "cli_error",
+                properties: {
+                    error_type: errorType,
+                    command,
+                    cli_version: CLI_VERSION,
+                    os: process.platform,
+                },
+            });
+        }
+        catch {
+            // Telemetry should never affect CLI functionality
+        }
+    })();
+}
+/**
+ * Track first run
+ */
+export function trackFirstRun() {
+    if (!isTelemetryEnabled())
+        return;
+    void (async () => {
+        try {
+            const posthog = await getClient();
+            if (!posthog)
+                return;
+            posthog.capture({
+                distinctId: getMachineId(),
+                event: "cli_first_run",
+                properties: {
+                    cli_version: CLI_VERSION,
+                    os: process.platform,
+                    node_version: process.version,
+                },
+            });
+        }
+        catch {
+            // Telemetry should never affect CLI functionality
+        }
+    })();
+}
+// ============================================================================
+// First Run Notice
+// ============================================================================
+/**
+ * Get the first run notice text
+ */
+export function getFirstRunNotice() {
+    return `
+┌────────────────────────────────────────────────────────────────────────────┐
+│  Pax8 CTA CLI can collect anonymous usage data to help improve the tool.  │
+│                                                                           │
+│  Telemetry is disabled by default. To opt in:                             │
+│  • Run 'telemetry on'                                                     │
+│  • Learn more: github.com/pax8labs/pax8-cta/tree/main/packages/cli       │
+└────────────────────────────────────────────────────────────────────────────┘
+`;
+}
+//# sourceMappingURL=telemetry.js.map

package/dist/lib/telemetry.js.map

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