@enter-pro/enter-cli 0.4.1 → 0.4.2

package/dist/errors.d.ts

@@ -1,3 +1,11 @@
+export declare class RequestError extends Error {
+    code: string;
+    retryable: boolean;
+    outcomeUnknown: boolean;
+    causeCode?: string | undefined;
+    constructor(code: string, message: string, retryable?: boolean, outcomeUnknown?: boolean, causeCode?: string | undefined);
+}
+export declare function errorEnvelope(error: unknown): Record<string, unknown>;
 export declare class APIError extends Error {
     code: number | string;
     detail: string;

package/dist/errors.js

@@ -1,3 +1,32 @@
+import { redactText } from "./safe-output.js";
+export class RequestError extends Error {
+    code;
+    retryable;
+    outcomeUnknown;
+    causeCode;
+    constructor(code, message, retryable = false, outcomeUnknown = false, causeCode) {
+        super(message);
+        this.code = code;
+        this.retryable = retryable;
+        this.outcomeUnknown = outcomeUnknown;
+        this.causeCode = causeCode;
+        this.name = "RequestError";
+    }
+}
+export function errorEnvelope(error) {
+    const e = error instanceof Error ? error : new Error(String(error));
+    const request = e instanceof RequestError ? e : undefined;
+    const api = e instanceof APIError ? e : undefined;
+    return { error: {
+            code: request?.code ?? api?.code ?? "CLI_ERROR",
+            message: redactText(e.message),
+            retryable: request?.retryable ?? api?.retryable ?? false,
+            outcome_unknown: request?.outcomeUnknown ?? false,
+            ...(request?.causeCode ? { cause_code: request.causeCode } : {}),
+            ...(request?.outcomeUnknown ? { hint: "The write may have reached Enter. Inspect task/action state before retrying; do not resubmit blindly." }
+                : api?.hint ? { hint: api.hint } : {}),
+        } };
+}
 export class APIError extends Error {
     code;
     detail;

package/dist/index.js

@@ -1,8 +1,9 @@
 #!/usr/bin/env node
 import { Command } from "commander";
 import { createRequire } from "module";
-import { setVerbose } from "./client.js";
+import { setVerbose, setRequestTimeout } from "./client.js";
 import { loadConfig } from "./config.js";
+import { errorEnvelope } from "./errors.js";
 const require = createRequire(import.meta.url);
 const { version } = require("../package.json");
 import { loginCmd } from "./commands/login.js";
@@ -21,10 +22,13 @@ program
     .version(version)
     .option("-o, --output <format>", "Output format: table, json, yaml")
     .option("-v, --verbose", "Verbose output (show HTTP requests)")
+    .option("--request-timeout <seconds>", "Optional HTTP deadline including observation read retries")
     .hook("preAction", () => {
     const opts = program.opts();
     if (opts.verbose)
         setVerbose(true);
+    if (opts.requestTimeout !== undefined)
+        setRequestTimeout(Number(opts.requestTimeout));
     if (!opts.output) {
         const cfg = loadConfig();
         program.setOptionValue("output", cfg.output);
@@ -40,6 +44,9 @@ program.addCommand(threadCmd);
 program.addCommand(domainCmd);
 program.addCommand(modelsCmd);
 program.parseAsync().catch((err) => {
-    console.error(`Error: ${err.message}`);
+    if ((program.opts().output ?? loadConfig().output) === "json")
+        console.error(JSON.stringify(errorEnvelope(err)));
+    else
+        console.error(`Error: ${err.message}`);
     process.exit(1);
 });

package/dist/safe-output.d.ts

@@ -0,0 +1,6 @@
+export declare function redactText(value: string): string;
+type OutputOptions = {
+    redactIdentifiers?: boolean;
+};
+export declare function safeOutput(value: unknown, options?: OutputOptions): unknown;
+export {};

package/dist/safe-output.js

@@ -0,0 +1,29 @@
+// Applied at output boundaries, never to requests or data used for execution.
+const credentialField = /^(?:.*[_-])?(?:access_token|refresh_token|id_token|token|password|secret|secret_value|secret_key|api_key|anon_key|service_role_key|private_key|client_secret|app_secret|authorization|credentials?)$/i;
+export function redactText(value) {
+    return value
+        .replace(/\bBearer\s+[^\s"'<>]+/gi, "Bearer [REDACTED]")
+        .replace(/\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/g, "[REDACTED]")
+        .replace(/\b(?:epk_|sk-)[A-Za-z0-9_-]+/g, "[REDACTED]")
+        .replace(/([?&](?:token|api_key|access_token)=)[^&\s"']+/gi, "$1[REDACTED]");
+}
+export function safeOutput(value, options = {}) {
+    if (Array.isArray(value))
+        return value.map(item => safeOutput(item, options));
+    if (value && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value).map(([key, item]) => [
+            key, credentialField.test(key.replace(/([a-z])([A-Z])/g, "$1_$2")) || (options.redactIdentifiers && /^(client_ids?|app_id)$/i.test(key)) ? "[REDACTED]" : safeField(key, item, options),
+        ]));
+    }
+    return typeof value === "string" ? redactText(value) : value;
+}
+function safeField(key, value, options) {
+    // Only decode known JSON-encoded tool fields, never arbitrary user content.
+    if (["full_arguments", "tool_call_args", "tool_result", "accumulated_arguments", "arguments"].includes(key) && typeof value === "string") {
+        try {
+            return JSON.stringify(safeOutput(JSON.parse(value), options));
+        }
+        catch { /* partial JSON */ }
+    }
+    return safeOutput(value, options);
+}

package/dist/thread-events.d.ts

@@ -0,0 +1,36 @@
+import { RequestError } from "./errors.js";
+export type ThreadEvent = Record<string, unknown>;
+export type StreamMode = "connecting" | "websocket" | "reconnecting" | "polling";
+export interface StreamOptions {
+    turn?: number;
+    chatId?: string;
+    cursor?: string;
+    stateOnly?: boolean;
+    signal: AbortSignal;
+    onEvent?: (event: ThreadEvent) => void;
+    onMode?: (mode: StreamMode) => void;
+}
+export declare function streamURL(base: string, projectId: string, options: Omit<StreamOptions, "signal">): URL;
+export declare class ThreadEvents {
+    private projectId;
+    private options;
+    mode: StreamMode;
+    cursor?: string;
+    reason?: string;
+    failure?: RequestError;
+    revision: number;
+    private socket?;
+    private retry?;
+    private stopped;
+    private failures;
+    private listeners;
+    private seen;
+    private abort;
+    constructor(projectId: string, options: StreamOptions);
+    private wake;
+    private setMode;
+    private connect;
+    wait(afterRevision: number, timeoutMs: number): Promise<void>;
+    close(): void;
+}
+export declare function isStateEvent(event: ThreadEvent): boolean;

package/dist/thread-events.js

@@ -0,0 +1,186 @@
+import WebSocket from "ws";
+import { HttpsProxyAgent } from "https-proxy-agent";
+import { getProxyForUrl } from "proxy-from-env";
+import { baseURL } from "./config.js";
+import { getToken } from "./auth.js";
+import { RequestError } from "./errors.js";
+export function streamURL(base, projectId, options) {
+    const url = new URL(`${base.replace(/\/$/, "")}/v1/projects/${encodeURIComponent(projectId)}/thread/stream`);
+    if (url.protocol === "https:")
+        url.protocol = "wss:";
+    else if (url.protocol === "http:")
+        url.protocol = "ws:";
+    else
+        throw new Error("Enter API URL must use HTTP or HTTPS");
+    if (options.turn)
+        url.searchParams.set("turn", String(options.turn));
+    if (options.chatId)
+        url.searchParams.set("chat_id", options.chatId);
+    if (options.cursor)
+        url.searchParams.set("last_event_id", options.cursor);
+    return url;
+}
+function laterCursor(current, next) {
+    if (typeof next !== "string" || !/^\d+-\d+$/.test(next))
+        return current;
+    if (!current || !/^\d+-\d+$/.test(current))
+        return next;
+    const a = current.split("-").map(BigInt), b = next.split("-").map(BigInt);
+    return b[0] > a[0] || (b[0] === a[0] && b[1] > a[1]) ? next : current;
+}
+// A socket is only a wake-up source. Callers still read authoritative action
+// state: a tool-start event can precede persistence of its approval card.
+export class ThreadEvents {
+    projectId;
+    options;
+    mode = "connecting";
+    cursor;
+    reason;
+    failure;
+    revision = 0;
+    socket;
+    retry;
+    stopped = false;
+    failures = 0;
+    listeners = new Set();
+    seen = new Set();
+    abort = () => this.close();
+    constructor(projectId, options) {
+        this.projectId = projectId;
+        this.options = options;
+        this.cursor = options.cursor;
+        options.signal.addEventListener("abort", this.abort, { once: true });
+        if (options.signal.aborted)
+            this.close();
+        else {
+            try {
+                this.connect();
+            }
+            catch (error) {
+                this.close();
+                throw error;
+            }
+        }
+    }
+    wake() {
+        this.revision++;
+        for (const listener of this.listeners)
+            listener();
+        this.listeners.clear();
+    }
+    setMode(mode, reason) {
+        if (this.mode === mode && this.reason === reason)
+            return;
+        this.mode = mode;
+        this.reason = reason;
+        this.options.onMode?.(mode);
+        this.wake();
+    }
+    connect() {
+        if (this.stopped)
+            return;
+        const url = streamURL(baseURL(), this.projectId, { ...this.options, cursor: this.cursor });
+        const token = getToken();
+        // proxy-from-env honors NO_PROXY, including loopback fixture servers.
+        const proxy = process.env.NODE_USE_ENV_PROXY === "0" ? "" : getProxyForUrl(url.toString().replace(/^ws/, "http"));
+        const socket = new WebSocket(url, {
+            headers: token ? { Authorization: `Bearer ${token}` } : {},
+            ...(proxy ? { agent: new HttpsProxyAgent(proxy) } : {}),
+            handshakeTimeout: 1500,
+            maxPayload: 8 * 1024 * 1024,
+            followRedirects: false,
+        });
+        this.socket = socket;
+        let opened = false;
+        let retryable = true;
+        let reason = "connection_lost";
+        socket.on("unexpected-response", (_request, response) => {
+            const status = response.statusCode ?? 0;
+            response.resume();
+            if ([401, 403].includes(status)) {
+                retryable = false;
+                reason = status === 401 ? "authentication_required" : "permission_denied";
+                this.failure = new RequestError("STREAM_AUTH_ERROR", "Enter event stream rejected access. Check authentication and project permissions.");
+            }
+            else if ([404, 405, 426, 501].includes(status)) {
+                retryable = false;
+                reason = "stream_unavailable";
+            }
+            else
+                reason = `stream_http_${status}`;
+            socket.terminate();
+        });
+        socket.on("open", () => { opened = true; this.setMode("websocket"); });
+        socket.on("message", raw => {
+            let event;
+            try {
+                const parsed = JSON.parse(raw.toString());
+                if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+                    return;
+                event = parsed;
+            }
+            catch {
+                retryable = false;
+                reason = "invalid_event";
+                socket.close();
+                return;
+            }
+            if (this.options.chatId && event.chat_id && event.chat_id !== this.options.chatId)
+                return;
+            const key = typeof event.event_id === "string" ? event.event_id : JSON.stringify(event);
+            if (this.seen.has(key))
+                return;
+            this.seen.add(key);
+            if (this.seen.size > 1024)
+                this.seen.delete(this.seen.values().next().value);
+            this.cursor = laterCursor(this.cursor, event.event_id);
+            this.failures = 0;
+            this.options.onEvent?.(event);
+            if (!this.options.stateOnly || isStateEvent(event))
+                this.wake();
+        });
+        // Do not expose raw URLs/errors (proxies and credentials can be embedded).
+        socket.on("error", () => { if (reason === "connection_lost" && !opened)
+            reason = "connection_failed"; });
+        socket.on("close", () => {
+            if (this.stopped)
+                return;
+            this.failures++;
+            this.setMode(opened && retryable ? "reconnecting" : "polling", reason);
+            if (!retryable)
+                return;
+            this.retry = setTimeout(() => this.connect(), Math.min(1000 * 2 ** Math.min(this.failures - 1, 4), 15000));
+        });
+    }
+    wait(afterRevision, timeoutMs) {
+        if (this.stopped || this.revision !== afterRevision)
+            return Promise.resolve();
+        return new Promise(resolve => {
+            const done = () => { clearTimeout(timer); this.listeners.delete(done); resolve(); };
+            const timer = setTimeout(done, timeoutMs);
+            this.listeners.add(done);
+        });
+    }
+    close() {
+        if (this.stopped)
+            return;
+        this.stopped = true;
+        clearTimeout(this.retry);
+        this.options.signal.removeEventListener("abort", this.abort);
+        this.socket?.terminate();
+        this.wake();
+    }
+}
+export function isStateEvent(event) {
+    const type = String(event.message_type ?? "");
+    if (/^(turn_|build_|sync_|agent_stopped|insufficient_credits)/.test(type))
+        return true;
+    const detail = event.detail;
+    const tool = detail?.[type];
+    // Legacy argument chunks carry tool_name too; they are not new card state.
+    if (["tool_call_arguments", "tool_call_arguments_delta", "tool_call_arguments_start"].includes(type))
+        return false;
+    if (tool?.tool_action_id)
+        return true;
+    return (type.startsWith("tool_call_") && /^(ask_user_question|confirm_plan_mode|supabase_|stripe_|enable_|i18n_enable)/.test(String(tool?.tool_name ?? "")));
+}

package/package.json

@@ -1,12 +1,21 @@
 {
   "name": "@enter-pro/enter-cli",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "Enter CLI - manage Enter platform resources from the command line",
   "type": "module",
   "main": "dist/index.js",
   "bin": {
     "enter-cli": "dist/index.js"
   },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "test": "npm run build && node --test",
+    "mock:serve": "node scripts/mock-enter.mjs",
+    "local:cli": "node scripts/local-cli.mjs",
+    "prepublishOnly": "npm run build"
+  },
   "files": [
     "dist"
   ],
@@ -25,17 +34,16 @@
   },
   "dependencies": {
     "commander": "^13.0.0",
-    "js-yaml": "^4.1.0"
+    "https-proxy-agent": "^7.0.6",
+    "js-yaml": "^4.3.2",
+    "proxy-from-env": "^1.1.0",
+    "ws": "^8.21.3"
   },
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^22.0.0",
+    "@types/proxy-from-env": "^1.0.4",
+    "@types/ws": "^8.18.1",
     "typescript": "^5.7.0"
-  },
-  "scripts": {
-    "build": "tsc",
-    "dev": "tsc --watch",
-    "start": "node dist/index.js",
-    "test": "npm run build && node --test"
   }
-}
+}