@clawscarf/cli 0.1.0-alpha.5 → 0.1.0-alpha.7

package/scripts/telemetry.js

@@ -0,0 +1,282 @@
+import packageInfo from "../package.json" with { type: "json" };
+import { randomUUID } from "node:crypto";
+import { mkdir, open, readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { PostHog } from "posthog-node";
+import { Agent, fetch } from "undici";
+import { z } from "zod";
+const destinationSchema = z.strictObject({
+    host: z.url().refine((value) => {
+        const url = new URL(value);
+        return (!url.username &&
+            !url.password &&
+            !url.search &&
+            !url.hash &&
+            url.pathname === "/" &&
+            (url.protocol === "https:" ||
+                (url.protocol === "http:" && url.hostname === "127.0.0.1")));
+    }),
+    projectToken: z.string().regex(/^phc_[A-Za-z0-9_-]+$/),
+});
+// Deliberately finite: remote errors and OperatorError.code can contain arbitrary text.
+const errorCodeSchema = z.enum([
+    "invalid_configuration",
+    "unsupported_platform",
+    "release_mismatch",
+    "stale_plan",
+    "change_unsupported",
+    "unavailable",
+    "operation_failed",
+    "invalid_arguments",
+    "operation_busy",
+    "invalid_team_configuration",
+    "upgrade_pending",
+    "upgrade_refused",
+    "upgrade_outcome_unknown",
+    "runtime_binding_changed",
+    "runtime_binding_unavailable",
+    "administrator_unverified",
+    "bootstrap_outcome_unknown",
+    "browser_unavailable",
+    "command_failed",
+    "configuration_changed",
+    "database_start_failed",
+    "executable_unavailable",
+    "incomplete_certificate",
+    "invalid_certificate",
+    "invalid_model_setup",
+    "model_credential_pending",
+    "invalid_connections_setup",
+    "connections_catalog_blocked",
+    "connections_configuration_pending",
+    "connections_configuration_refused",
+    "connections_configuration_unavailable",
+    "invalid_runtime_policy",
+    "native_unavailable",
+    "network_identity_changed",
+    "network_lookup_incomplete",
+    "network_outcome_unknown",
+    "network_unprepared",
+    "platform_unqualified",
+    "port_check_failed",
+    "port_in_use",
+    "private_directory_required",
+    "runtime_failed",
+    "runtime_identity_changed",
+    "runtime_lookup_incomplete",
+    "runtime_outcome_unknown",
+    "runtime_start_failed",
+    "runtime_stop_pending",
+    "startup_interrupted",
+    "startup_timed_out",
+    "unowned_directory",
+    "ownership_conflict",
+    "runtime_credentials_changed",
+    "database_setup_failed",
+    "outcome_unknown",
+    "unauthorized",
+    "forbidden",
+    "ENOENT",
+    "ENOTDIR",
+    "EACCES",
+    "EPERM",
+    "EEXIST",
+    "ELOOP",
+    "ENOSPC",
+]);
+/** One CLI invocation. No runtime, server, browser, or automatic exception instrumentation. */
+export class CliTelemetry {
+    environment;
+    destinationFile;
+    client;
+    dispatcher;
+    started;
+    startTime = 0;
+    distinctId = "";
+    command = "";
+    action;
+    interactive = false;
+    version = "";
+    invocationId = randomUUID();
+    outcome = "success";
+    mode;
+    configuration;
+    constructor(environment = process.env, destinationFile = new URL("../release/telemetry.json", import.meta.url)) {
+        this.environment = environment;
+        this.destinationFile = destinationFile;
+    }
+    async start(command) {
+        if (this.environment.CLAWSCARF_TELEMETRY_DISABLED === "1")
+            return;
+        try {
+            const destination = destinationSchema
+                .nullable()
+                .parse(JSON.parse(await readFile(this.destinationFile, "utf8")));
+            if (!destination)
+                return;
+            const manifest = z
+                .object({
+                version: z.string().regex(/^\d+\.\d+\.\d+(?:-[A-Za-z0-9.-]+)?$/),
+            })
+                .parse(packageInfo);
+            this.version = manifest.version;
+            const directory = join(this.environment.XDG_CONFIG_HOME || homedir(), this.environment.XDG_CONFIG_HOME ? "clawscarf" : ".config/clawscarf");
+            await mkdir(directory, { recursive: true, mode: 0o700 });
+            const file = join(directory, "telemetry-id");
+            try {
+                const handle = await open(file, "wx", 0o600);
+                try {
+                    await handle.writeFile(randomUUID() + "\n");
+                }
+                finally {
+                    await handle.close();
+                }
+                process.stderr.write("ClawScarf reports CLI usage and failure codes to PostHog. Disable with CLAWSCARF_TELEMETRY_DISABLED=1. Details: https://github.com/clawscarf/clawscarf/blob/main/deploy/deployment/installation.md#telemetry\n");
+            }
+            catch (error) {
+                if (!(error instanceof Error &&
+                    "code" in error &&
+                    error.code === "EEXIST"))
+                    throw error;
+            }
+            // A concurrent creator may still be writing. Skip this invocation if incomplete.
+            this.distinctId = z.uuid().parse((await readFile(file, "utf8")).trim());
+            const names = [];
+            for (let current = command; current.parent; current = current.parent)
+                names.unshift(current.name());
+            this.command = names.join(" ");
+            const options = command.optsWithGlobals();
+            this.interactive =
+                [process.stdin.isTTY, process.stdout.isTTY].every((isTTY) => isTTY) &&
+                    !options.nonInteractive;
+            if (this.command === "stop")
+                this.action = options.delete ? "delete" : "stop";
+            const dispatcher = new Agent({ connect: { timeout: 500 } });
+            this.dispatcher = dispatcher;
+            this.client = new PostHog(destination.projectToken, {
+                host: destination.host,
+                isServer: false,
+                disableGeoip: true,
+                enableExceptionAutocapture: false,
+                enableLocalEvaluation: false,
+                flushInterval: 0,
+                fetchRetryCount: 0,
+                requestTimeout: 500,
+                disableCompression: true,
+                fetch: async (url, options) => {
+                    // Only uncompressed event JSON is supported; never follow ingestion redirects.
+                    if (typeof options.body !== "string")
+                        throw Error("Expected event JSON");
+                    const response = await fetch(url, {
+                        method: options.method,
+                        headers: options.headers,
+                        body: options.body,
+                        dispatcher,
+                        redirect: "error",
+                        signal: AbortSignal.timeout(500),
+                    });
+                    const body = await response.text();
+                    return {
+                        status: response.status,
+                        headers: response.headers,
+                        text: () => Promise.resolve(body),
+                        json: () => Promise.resolve().then(() => JSON.parse(body)),
+                    };
+                },
+            });
+            this.startTime = performance.now();
+            this.started = this.capture("cli_command_started");
+        }
+        catch {
+            // Telemetry configuration/storage must never prevent a command from running.
+            await this.dispatcher?.destroy().catch(() => { });
+            this.client = undefined;
+        }
+    }
+    configurationMode(mode) {
+        this.mode = mode;
+    }
+    result(value) {
+        if (!value || typeof value !== "object")
+            return;
+        if ("state" in value && value.state === "cancelled")
+            this.outcome = "cancelled";
+        else if ("state" in value && value.state === "action_required")
+            this.outcome = "action_required";
+        else if (this.command === "configure" || this.command === "start") {
+            if ("ready" in value && value.ready === false)
+                this.outcome = "action_required";
+        }
+        if (this.command !== "configure")
+            return;
+        if ("ready" in value && value.ready === true)
+            this.configuration = "ready";
+        else if ("state" in value && value.state === "unchanged")
+            this.configuration = "unchanged";
+        else if ("state" in value && value.state === "prepared")
+            this.configuration = "saved";
+    }
+    async finish(exitCode, failureCode) {
+        if (!this.client)
+            return;
+        const outcome = exitCode === 130 || failureCode === "cancelled"
+            ? "cancelled"
+            : failureCode !== undefined ||
+                (exitCode !== undefined && Number(exitCode) !== 0)
+                ? "failure"
+                : this.outcome;
+        const code = errorCodeSchema.safeParse(failureCode);
+        try {
+            await Promise.all([
+                this.started,
+                this.capture("cli_command_finished", {
+                    outcome,
+                    duration_ms: Math.round(performance.now() - this.startTime),
+                    ...(outcome === "failure"
+                        ? {
+                            error_code: code.success ? code.data : "operation_failed",
+                            operation: this.command,
+                        }
+                        : {}),
+                    ...(this.mode ? { configuration_mode: this.mode } : {}),
+                    ...(this.configuration
+                        ? { configuration_outcome: this.configuration }
+                        : {}),
+                }),
+            ]);
+            await this.client.shutdown(1000);
+        }
+        catch {
+            // Best effort only: no retries, offline queue, output, or changed exit status.
+        }
+        finally {
+            await this.dispatcher?.destroy().catch(() => { });
+            this.client = undefined;
+        }
+    }
+    async capture(event, result = {}) {
+        try {
+            await this.client?.captureImmediate({
+                distinctId: this.distinctId,
+                event,
+                timestamp: new Date(),
+                properties: {
+                    command: this.command,
+                    invocation_id: this.invocationId,
+                    cli_version: this.version,
+                    os: process.platform,
+                    architecture: process.arch,
+                    interactive: this.interactive,
+                    ...(this.action ? { action: this.action } : {}),
+                    ...result,
+                    $process_person_profile: false,
+                    $ip: null,
+                },
+            });
+        }
+        catch {
+            // Never forward telemetry errors (including remote response bodies) to output.
+        }
+    }
+}

package/scripts/deployment/connection-policy.js

@@ -1,80 +0,0 @@
-import { isDeepStrictEqual } from "node:util";
-import { readFile, rm } from "node:fs/promises";
-import { join } from "node:path";
-import { z } from "zod";
-import { run } from "./process.js";
-import { resourceNames, writePrivate } from "./state.js";
-import { runtimeManager } from "./runtime.js";
-const ruleSchema = z.object({
-    name: z.string(),
-    endpoints: z.array(z.object({ host: z.string(), port: z.number(), tls: z.string() })),
-    binaries: z.array(z.object({ path: z.string() })),
-});
-const policySchema = z.looseObject({
-    network_policies: z.record(z.string(), z.unknown()),
-});
-/** Apply only the explicitly selected broker rule; never regenerate an operator's other policies. */
-export async function applyConnectionPolicy(directory, state, env, verify = false) {
-    const pending = join(directory, "private/connection-policy-change.json");
-    let text;
-    try {
-        text = await readFile(pending, "utf8");
-    }
-    catch (error) {
-        if (error instanceof Error && "code" in error && error.code === "ENOENT")
-            return;
-        throw error;
-    }
-    const change = z
-        .strictObject({
-        ownerId: z.literal(state.ownerId),
-        rule: ruleSchema.nullable(),
-    })
-        .parse(JSON.parse(text));
-    const base = join(directory, "private/runtime-policy.json");
-    const update = (policy) => {
-        if (change.rule)
-            policy.network_policies.connections_broker = change.rule;
-        else
-            delete policy.network_policies.connections_broker;
-        return policy;
-    };
-    const matches = (rule) => {
-        if (change.rule === null)
-            return rule === undefined;
-        const parsed = ruleSchema.safeParse(rule);
-        return parsed.success && isDeepStrictEqual(parsed.data, change.rule);
-    };
-    const name = resourceNames(state).sandbox;
-    if (!(await runtimeManager(directory, state, env, run).recorded()).receipt) {
-        if (verify)
-            throw Error("The configured runtime has not been recorded.");
-        await writePrivate(base, JSON.stringify(update(policySchema.parse(JSON.parse(await readFile(base, "utf8"))))));
-        return;
-    }
-    const observed = z
-        .object({
-        sandbox: z.literal(name),
-        policy_source: z.literal("sandbox"),
-        policy: policySchema,
-    })
-        .parse(JSON.parse(await run(state.input.openshellCli, [
-        "policy",
-        "get",
-        name,
-        "--gateway",
-        name,
-        "--base",
-        "--output",
-        "json",
-    ], { env })));
-    if (matches(observed.policy.network_policies.connections_broker)) {
-        if (verify)
-            await rm(pending);
-        return;
-    }
-    if (verify)
-        throw Error("The Connections network permission was not confirmed. The installation remains unavailable.");
-    await writePrivate(base, JSON.stringify(update(observed.policy)));
-    await run(state.input.openshellCli, ["policy", "set", name, "--gateway", name, "--policy", base], { env });
-}