@enter-pro/enter-cli 0.4.2 → 0.4.3

package/README.md

@@ -1,252 +1,167 @@
 # Enter CLI
 
-## Production login
+CLI for Enter projects, tasks and approval cards. Node 18+ is required.
+The [Enter Skill](skills/enter/SKILL.md) guides agents through the workflow;
+command options are available through `enter-cli <command> --help`.
 
-`enter-cli login` uses the production Auth0 tenant `auth.converge.ai` and the
-production API at `https://api.enter.pro/code/api`. The web app's
-`enter.converge.ai` domain is not the API base URL. Log in again if existing
-credentials were issued by the former `auth.enter.pro` tenant.
+## Authentication and configuration
 
+`enter-cli login` uses `auth.converge.ai` and the API at
+`https://api.enter.pro/code/api` (not the web domain `enter.converge.ai`).
+Log in again if credentials came from the former `auth.enter.pro` tenant.
 OAuth and API-key login verify the new token against `/v1/users/info` before
-saving credentials or reporting success. A rejected token leaves existing
-credentials unchanged.
+saving it; verification failure preserves existing credentials. Expired local
+OAuth credentials renew automatically. An already-sent renewal saves rotated
+credentials before honoring cancellation, so the next invocation can still log in.
 
-## Local verification
+`ENTER_API_KEY` takes precedence over local credentials. `login` saves local
+credentials but cannot switch an injected identity. `logout` clears local
+credentials only and reports `logged_out: false, auth_source: environment` when
+that variable remains set. Switch host-managed authentication in the host, or
+unset the variable in your shell.
 
-```sh
-npm ci
-npm test
-```
-
-Tests start HTTP fixture servers on loopback and execute the built CLI in child
-processes with a dummy API key. They do not start Work, connect to Enter, create
-cloud resources, or prove end-to-end Work behavior.
-
-### Interactive local simulator
-
-Requires Node 18+ and npm; no Docker, Work server, database, or credentials are
-needed. From this repository, build once and start the fixture server:
-
-```sh
-npm run build
-npm run mock:serve
-```
+`config get/set/list` supports `api_url`, `base_path`, and `output` (`json`, `yaml`,
+`table`). Environment overrides are `ENTER_API_URL`, `ENTER_BASE_PATH`, and
+`ENTER_OUTPUT`. Workspace IDs are explicit command arguments; the unused
+`default_workspace` setting is rejected and legacy entries are ignored.
 
-In another terminal in this repository:
+## Submit, observe and deliver
 
 ```sh
-npm run local:cli -- whoami
-npm run local:cli -- workspace list
-npm run local:cli -- thread status cloud
-npm run local:cli -- thread approve cloud cloud-action
-npm run local:cli -- thread wait cloud --timeout 3
-npm run local:cli -- project get cloud
+enter-cli --output json thread chat PROJECT_ID --file requirement.txt
+enter-cli --output json thread wait PROJECT_ID --task-id TASK_ID --timeout 10
+enter-cli --output json thread status PROJECT_ID --task-id TASK_ID
+enter-cli thread watch PROJECT_ID --task-id TASK_ID --timeout 60
 ```
 
-The server binds only to `127.0.0.1:43180`. Set `MOCK_ENTER_PORT` in both terminals
-to use another port. `local:cli` always targets loopback and injects only the
-dummy mock key, even if the shell has real `ENTER_API_URL` or `ENTER_API_KEY`
-values. Prefer this wrapper for manual simulation; the normal CLI still uses
-its ordinary configuration. Stop the server with Ctrl-C. Restarting resets all
-in-memory scenarios; no resources are written to Enter or cloud providers.
+`chat --stdin` also accepts multiline input. Submission returns immediately with
+`task_id`, `submission_status: accepted`, and continuation commands. Follow-ups
+can be submitted while Enter works; acceptance is not completion.
 
-| Project ID | Scenario |
+| Command | Output and default lifetime |
 | --- | --- |
-| `plan` | Plan approval (`plan-action`) with plan text |
-| `cloud` | Supabase dedicated enable flow (`cloud-action`) |
-| `ai` | AI capability dedicated enable flow (`ai-action`) |
-| `secret` | Secret input (`secret-action`); use fake values only |
-| `questions` | Structured question (`questions-action`) |
-| `subscription` | Feature enable returns `VIP_REQUIRED` |
-| `running` | Never completes; exercise wait timeout |
-| `failed` | Backend turn failed |
-| `http-error` | Backend HTTP 503 |
-| `stalled` | HTTP request never returns; exercise request deadline |
-
-Example input-card and timeout checks:
-
-```sh
-printf '%s\n' 'dummy-test-value' | npm run local:cli -- thread approve secret secret-action --secret-name LOCAL_TEST_KEY --secret-value-stdin
-npm run local:cli -- thread approve questions questions-action --skip-answers
-npm run local:cli -- thread wait running --timeout 1
-npm run local:cli -- thread wait stalled --timeout 1
-```
+| `status` | One JSON/YAML snapshot, 30-second deadline |
+| `wait` | One result on a card, terminal state or timeout; 10 seconds |
+| `watch` | Changed snapshots as NDJSON, then `type: result`; 60 seconds |
+
+Use one observer per task. In interactive agents, use the returned short wait,
+handle incoming user messages, then continue the same task. Normal observation
+timeout is not a reason to increase the wait or resubmit. Background watch is
+appropriate only with completion notifications and non-blocking output collection;
+do not immediately block on the job for minutes. CLI lifetime and host job-wait
+limits are separate upper bounds, not measured elapsed time. Hosts own message
+scheduling: CLI events cannot make a blocked host process new user input.
+
+`--task-id` follows exactly the submitted task, including queue time. `--turn N`
+selects a fixed turn instead; without either, observation pins the first turn.
+`--chat-id` scopes lookup and continuation. An interjection may return an external
+message ID that the backend cannot correlate to a turn: report `unknown`, inspect
+messages and the resulting change, and do not substitute the newest turn.
 
-`test/local-workflow.test.mjs` starts fresh ephemeral servers automatically and
-checks approval, simulated resource flags, continuation turns, rejection,
-subscription refusal, and errors. It is a CLI-to-simulator integration suite,
-not a real provisioning or Work UI test. The simulator intentionally supports
-only the listed workflows; unsupported routes fail instead of fabricating a
-successful response. It retains request methods/paths but never request bodies
-or secret values.
-
-For later real-backend testing, `.env.integration.example` documents the needed
-variables. Copy it to ignored `.env.integration.local` and configure a dedicated
-test backend only when ready. The file is not loaded automatically; neither the
-simulator nor the mock CLI wrapper reads it.
-
-## Agent integration: CLI + Skill
-
-The CLI executes Enter operations and streams structured state. The Skill guides
-agents on command selection, following tasks, presenting questions and handling
-approved actions. This works across agent hosts without host-specific hooks.
-Node 18+ is required. Authenticate with `enter-cli login`, or let the host inject
-`ENTER_API_KEY` through its secret environment mechanism.
+| Status | Meaning |
+| --- | --- |
+| `idle` | No turn yet |
+| `queued` | Selected task is queued |
+| `unknown` | Missing turn, unavailable status or uncorrelated submission |
+| `running` | Nonterminal turn with no pending action |
+| `blocked` | Inspect `actions` for input or approval |
+| `completed` | Turn completed; build and deployment are separate |
+| `failed` | Turn failed, errored or was cancelled |
 
-### CLI: submit once, observe the returned task
+`project create --wait` uses the same observer and requires a matching successful
+build. For existing tasks use `--require-build`; stale builds cannot satisfy it.
+`build_matches_turn` checks commit identity. `status/wait` retain full metadata;
+`--compact` selects monitoring fields. `watch` is compact unless `--full` is set.
+The additive `workflow` projection supplies `state`, `task`, `next_action`,
+`observation`, build matching and action descriptors; full card details remain in
+`actions`. `use_existing_authorization` does not grant new permission.
+
+Exit 0 means observation succeeded (including a blocked card), not build success.
+Exit 2 means a wait timed out with work pending; exit 1 means failure, unknown
+state or query failure. `query_timed_out` marks a query deadline; retained state
+is the last complete snapshot. SIGINT/SIGTERM returns `interrupted: true` and
+130/143 without cancelling remote work. A cancelled turn can still have a queued
+backend operation; do not confuse it with completed cancellation or restoration.
+
+Completed snapshots include `messages_command`. Use
+`thread messages PROJECT_ID --turn N --text` to read Enter's delivery and validation
+summary. Report build success, saved configuration and real-service validation
+separately; do not replace Enter's validation with source keyword scans.
+
+## Transport and errors
+
+Observation uses authenticated WebSocket events, reconnects with `last_event_id`,
+deduplicates replay, and re-reads authoritative HTTP state. Healthy streams have a
+30-second safety refresh; unavailable streams fall back to 2-second HTTP checks.
+Text/argument deltas do not trigger full queries; card persistence gets a short
+reconciliation window. `--transport poll` forces HTTP, `--cursor` resumes events,
+and `transport/transport_reason/cursor` identify progress. Stream 401/403 fails explicitly;
+unsupported endpoints fall back without repeated reconnects. WebSockets respect
+proxy variables and `NO_PROXY`; `NODE_USE_ENV_PROXY=0` disables their proxy use.
+
+`thread messages PROJECT_ID --follow --timeout 60 --cursor EVENT_ID` emits raw
+NDJSON events with diagnostics on stderr. It supports `--max-events`, crosses turn
+boundaries, and does not synthesize HTTP state when the socket is unavailable.
+
+`--request-timeout SECONDS` covers API requests and response bodies, including
+downloads. Monitoring always has its own deadline. `project publish --timeout`
+validates before requests and bounds lookup, submission, observation and URL
+verification. After uncertain publication, query `project publish-status` first.
+Only transient observation reads retry automatically; mutations never do.
+`error.outcome_unknown: true` means inspect actual state before retrying a write.
+
+JSON execution errors go to stderr; observation errors accompany the last
+snapshot on stdout. Error fields are `code/message/retryable/outcome_unknown`.
+Keep stdout and stderr separate. JSON/YAML confirmations are structured;
+interactive login instructions use stderr. Known credential fields and encoded
+tool arguments are redacted in monitoring, approval, events and verbose bodies;
+ordinary content is not arbitrarily rewritten.
+
+## Approval cards
+
+Feature cards call the actual enable endpoint and verify action state; subscription
+refusal or enable failure remains an error. Plans require user approval. Questions
+carry their original text, options and selection mode: use that text as the answer
+key, not a host question ID. `thread approve --help` describes `selected_options`
+and `other_text`; skip only when the user requests it.
+
+Configuration cards expose required fields. Reuse authorized input, ask only for
+missing values, and use stdin from a secure input or user-provided file, or Enter's
+form. OAuth configuration is saved before credential-free approval; after form
+submission, check status because the form may already have approved the action.
+Provider fields, Secret/Stripe inputs and examples are in
+[configuration guidance](skills/enter/references/configuration.md).
+Do not echo secrets or embed them in shell text/build prompts: stdin does not
+protect earlier chat or tool logs. User-approved placeholders remain pending
+integrations; mock configuration does not prove real OAuth login or payment.
+
+## Development and host installation
 
 ```sh
-enter-cli --output json thread chat PROJECT_ID --file requirement.txt
-# Copy task_id from the receipt, including for queued follow-ups:
-enter-cli thread watch PROJECT_ID --task-id TASK_ID --timeout 60
-enter-cli --output json thread status PROJECT_ID --task-id TASK_ID
-enter-cli --output json thread wait PROJECT_ID --task-id TASK_ID --timeout 10
+npm ci
+npm test
+npm run build
+npm pack
+npm run install:hosts -- --package /absolute/path/enter-pro-enter-cli-0.4.3.tgz
 ```
 
-`chat --stdin` also accepts multiline input without shell escaping or putting the
-message into process arguments. Submission returns immediately with `task_id`,
-`submission_status: accepted`, and ready-to-use monitoring commands. You can
-submit follow-ups while Enter is running; acceptance is not completion.
-
-- `status` reads one snapshot, with a 30-second total deadline by default.
-- `wait` waits for a pending card or terminal state and emits one JSON result.
-  Its default lifetime is 10 seconds.
-- `watch` emits NDJSON snapshots only when meaningful state changes, followed
-  by a final `type: result` record. Its default lifetime is 60 seconds.
-
-Waiting uses authenticated WebSocket events to trigger authoritative HTTP state
-reads. It reconnects with `last_event_id`, deduplicates replay, and uses HTTP
-polling if the stream is unavailable. Healthy streams have a 30-second safety
-refresh; fallback checks are every 2 seconds plus reconnect transitions. Text
-and argument deltas do not cause repeated full snapshot queries. After a card
-event, a short reconciliation window accounts for delayed card persistence.
-Use `--transport poll` to force HTTP-only operation; `--cursor EVENT_ID` resumes
-a prior stream. Returned `transport` and `cursor` make the active mode visible.
-`transport_reason` distinguishes temporary connection failure, unavailable
-streams, and invalid events. Unsupported endpoints stop reconnecting for the
-current call and use HTTP polling. HTTP 401/403 on the stream returns
-`STREAM_AUTH_ERROR` instead of silently reconnecting. WebSockets honor proxy environment variables and `NO_PROXY`; set
-`NODE_USE_ENV_PROXY=0` to disable proxy use for the stream.
-
-Use `--task-id` for submissions and continuation receipts. It follows the exact
-task through queueing, even if an older turn already completed. `--turn N` selects
-a fixed turn instead; the two selectors are mutually exclusive. With neither,
-waiting pins the first observed turn. `--chat-id` scopes chat submission, lookup,
-and continuation commands.
-
-Enter can interject a mid-turn message into the active turn and return an external
-message ID instead of a new task ID. The current API does not map that receipt to
-its owning turn. In that case `status --task-id` returns `unknown`, with separate
-`project_activity` and a `project_status_command`; that activity never claims the
-submission succeeded. Inspect the echoed message and resulting change. Do not
-resubmit blindly or infer correlation from the newest turn.
-
-`project create` returns continuation commands. `project create --wait` uses the
-same bounded event monitor, yields on cards, and requires a matching successful
-build. `thread wait/status/watch --require-build` enables that build check for an
-existing project; stale successful builds cannot satisfy it. A matching failed
-build returns failure, and timeout preserves progress without cancelling Enter.
+Tests use loopback HTTP/WebSocket fixtures and dummy credentials, not real cloud
+provisioning or host UI acceptance. The installer puts the same package and Skill
+into Codex/DSH, renders the wrapper, and records its SHA-256. `--host codex|dsh`
+selects one host; `--home` supports isolated installs. No checkout is needed at runtime.
 
-| Status | Meaning |
-| --- | --- |
-| `idle` | No turn exists yet |
-| `queued` | The selected task is in the backend queue |
-| `unknown` | The selected submission cannot be correlated; this is not completion |
-| `running` | Selected turn has not terminated and has no pending actions |
-| `blocked` | Inspect `actions` for questions or approval requirements |
-| `completed` | Turn completed; build and deployment remain separate |
-| `failed` | Turn failed, errored or was cancelled |
-| `unknown` | Explicit turn missing or status unavailable |
-
-The existing `status` and `wait` commands retain full metadata by default; use
-`--compact` for monitoring fields only. `watch` defaults to compact snapshots
-and accepts `--full`. `build_matches_turn` only becomes true when the build commit matches
-the selected turn's commit; an older successful preview does not prove the new
-turn built successfully. Known credential fields are redacted in monitoring, approval and event output,
-including known JSON-encoded tool argument fields. Ordinary command output and
-arbitrary JSON strings are not rewritten by this monitoring feature.
-
-Exit 0 means a successful observation (including `blocked`), not build success.
-Exit 2 means the observation deadline elapsed while work remained pending:
-`wait_timed_out: true`. Exit 1 means failure, unknown state or a failed query.
-A query timeout includes `query_timed_out: true`; retained state is only the last
-complete snapshot. SIGINT/SIGTERM during status/wait/watch returns
-`interrupted: true` with exit 130/143, without labelling it a timeout or cancelling
-remote work.
-
-For raw events rather than state snapshots:
+For manual simulation, run `npm run mock:serve`, then in another terminal:
 
 ```sh
-enter-cli thread messages PROJECT_ID --follow --timeout 60 --cursor EVENT_ID
+npm run local:cli -- thread status cloud
+npm run local:cli -- thread approve cloud cloud-action
+npm run local:cli -- thread wait cloud --timeout 3
 ```
 
-This emits NDJSON on stdout, transport diagnostics on stderr, and supports
-`--max-events N`. It continues across turn boundaries until its deadline or limit.
-Unlike `watch`, raw follow does not synthesize HTTP state when the socket is down.
-
-### Skill and host responsibilities
-
-The Skill should direct agents to submit once, follow the returned task ID, and
-use bounded `thread watch` or `thread wait` calls. Forward questions with their
-options and selection mode, and approve only within the user's authorization.
-Provide secrets through Enter's secure form or direct CLI stdin.
-
-The host remains responsible for scheduling observation and handling incoming
-user messages concurrently. CLI events cannot wake an agent
-whose host has stopped the task. Continue bounded watch calls while work remains
-pending; if the host supports background tasks, schedule a watcher there. Forward
-questions without silently selecting answers, and continue with the task ID
-returned by approval. Do not auto-approve based only on `input_kind: none`.
-
-### Errors and retry boundaries
-
-`--request-timeout SECONDS` optionally bounds JSON API requests, including
-response bodies. Without this explicit option, ordinary operations retain their
-existing request lifetime; monitoring commands always enforce their own total
-`--timeout`. Transient network errors and HTTP 502/503/504 retry once only for
-thread observation reads (turns, actions, messages and queued tasks).
-Mutations are never automatically replayed. A timed-out write can already have
-reached Enter: `error.outcome_unknown: true` tells the caller to inspect task or
-action state before resubmitting.
-
-In JSON mode, command execution errors are JSON on stderr. Status/watch query
-errors accompany their last observed snapshot on stdout. Error fields include
-`code`, `message`, `retryable`, and `outcome_unknown`. Never infer success from a
-missing stderr message.
-
-`test/agent-ux.test.mjs` uses local HTTP/WebSocket fixtures to cover event-triggered
-cards, delayed persistence, reconnect and cursor replay, queue tracking, polling
-fallback, deadlines, safe read retries and redaction. These are protocol/CLI integration tests,
-not production cloud-provisioning or a host UI acceptance test.
-
-## Approval inputs
-
-Feature enable cards use the dedicated feature endpoint and verify that the
-selected action becomes approved. A failed enable request, subscription refusal,
-or failed action must remain an error. Secret cards require both a name and a
-nonempty value; question cards require `--answers` or an explicit `--skip-answers`.
-
-OAuth cards (`supabase_configure_auth_provider`) resolve their provider from the
-matching tool call. If the provider was already configured through Enter's secure
-form, ordinary `thread approve PROJECT_ID ACTION_ID` verifies it and submits only
-`auth_provider_result: {provider}`. Otherwise, `--auth-config-stdin` accepts a JSON
-object, saves it through the auth configuration endpoint, then requests approval.
-The backend verifies the stored configuration before accepting the action.
-
-| Provider | Configuration fields |
-| --- | --- |
-| `google` | `client_ids`, `client_secret`, optional `skip_nonce_checks` |
-| `wechat` | `client_id`, `client_secret` |
-| `alipay` | `app_id`, `private_key` |
-| `feishu` | `app_id`, `app_secret` |
-
-Use a secure input mechanism to supply stdin, or complete the secure form in
-Enter. Do not request credentials in ordinary agent chat or place them in process
-arguments. Verbose request logging redacts credential fields. Approval payloads
-contain no OAuth credentials. The host needs a secure input path or a link to Enter's
-form to make these cards usable from its UI.
-
-`test/auth-provider-approve.test.mjs` exercises all four provider contracts against
-local HTTP fixtures, including save failures, backend verification failures,
-incorrect provider binding, malformed inputs, and verbose output redaction.
-These tests do not validate a live OAuth login or cloud provisioning.
+The server binds loopback port 43180 (`MOCK_ENTER_PORT` overrides it). The wrapper
+forces loopback and a dummy key even if production environment variables exist.
+Scenarios: `plan`, `cloud`, `ai`, `secret`, `questions`, `subscription`, `running`,
+`failed`, `http-error`, `stalled`. Card IDs are `<scenario>-action`. Restart to reset;
+unsupported routes fail, and request bodies/secrets are not retained. Only use
+fake values. `.env.integration.example` lists real-test variables; its ignored
+`.env.integration.local` counterpart is never loaded automatically.

package/dist/auth.d.ts

@@ -11,3 +11,6 @@ export declare function loadCredentials(): Credentials | null;
 export declare function clearCredentials(): void;
 export declare function getToken(): string;
 export declare function isAuthenticated(): boolean;
+export declare const OAUTH_TOKEN_URL = "https://auth.converge.ai/oauth/token";
+export declare const OAUTH_CLIENT_ID = "anCisSaaIA36fTZ2DUMiTMro3bYuptrf";
+export declare function getValidToken(signal?: AbortSignal): Promise<string>;

package/dist/auth.js

@@ -1,4 +1,6 @@
-import { readFileSync, writeFileSync, unlinkSync, mkdirSync } from "fs";
+import { readFileSync, writeFileSync, unlinkSync, mkdirSync, renameSync, rmdirSync } from "fs";
+import { setTimeout as delay } from "node:timers/promises";
+import { randomUUID } from "node:crypto";
 import { join } from "path";
 import { baseURL, configDir } from "./config.js";
 const CREDENTIALS_FILE = "credentials.json";
@@ -7,9 +9,17 @@ function credentialsPath() {
 }
 export function saveCredentials(creds) {
     mkdirSync(configDir(), { recursive: true, mode: 0o700 });
-    writeFileSync(credentialsPath(), JSON.stringify(creds, null, 2), {
-        mode: 0o600,
-    });
+    const temporary = `${credentialsPath()}.${randomUUID()}.tmp`;
+    try {
+        writeFileSync(temporary, JSON.stringify(creds, null, 2), { mode: 0o600 });
+        renameSync(temporary, credentialsPath());
+    }
+    finally {
+        try {
+            unlinkSync(temporary);
+        }
+        catch { /* already renamed */ }
+    }
 }
 // Validate the newly issued token, not an older saved token or ENTER_API_KEY.
 // Do not persist it or claim login success until the configured API accepts it.
@@ -41,8 +51,9 @@ export function clearCredentials() {
     try {
         unlinkSync(credentialsPath());
     }
-    catch {
-        // ignore if file doesn't exist
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
     }
 }
 export function getToken() {
@@ -55,3 +66,100 @@ export function getToken() {
 export function isAuthenticated() {
     return getToken() !== "";
 }
+// Same OAuth client as interactive login. Environment keys (including Work's
+// transparent placeholder) must never fall back to a personal OAuth identity.
+export const OAUTH_TOKEN_URL = "https://auth.converge.ai/oauth/token";
+export const OAUTH_CLIENT_ID = "anCisSaaIA36fTZ2DUMiTMro3bYuptrf";
+let refreshing;
+function needsRefresh(creds) {
+    return !!creds.expires_at && Date.parse(creds.expires_at) <= Date.now() + 60000;
+}
+async function refreshCredentials(signal) {
+    const lock = join(configDir(), "credentials-refresh.lock");
+    const deadline = Date.now() + 20000;
+    // Serialize separate CLI processes too: rotating refresh tokens are single use.
+    while (true) {
+        signal?.throwIfAborted();
+        try {
+            mkdirSync(lock, { mode: 0o700 });
+            break;
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            if (Date.now() >= deadline)
+                throw new Error("Another CLI is refreshing login. Retry after it finishes; if it crashed, remove ~/.enter/credentials-refresh.lock.");
+            await delay(100, undefined, { signal });
+        }
+    }
+    try {
+        const creds = loadCredentials();
+        if (!creds?.access_token)
+            return "";
+        if (!needsRefresh(creds))
+            return creds.access_token;
+        if (!creds.refresh_token)
+            throw new Error("Login expired. Run `enter-cli login` to sign in again.");
+        let response;
+        try {
+            response = await fetch(OAUTH_TOKEN_URL, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({ grant_type: "refresh_token", client_id: OAUTH_CLIENT_ID, refresh_token: creds.refresh_token }),
+                signal: AbortSignal.timeout(15000),
+            });
+        }
+        catch {
+            throw new Error("Could not refresh login. Check connectivity and retry; saved credentials were preserved.");
+        }
+        if (!response.ok) {
+            if ([400, 401, 403].includes(response.status))
+                throw new Error("Login renewal was rejected. Run `enter-cli login` to sign in again.");
+            throw new Error(`Login renewal failed (HTTP ${response.status}). Retry later.`);
+        }
+        let tokens;
+        try {
+            tokens = await response.json();
+        }
+        catch {
+            throw new Error("Login renewal returned an invalid response.");
+        }
+        if (typeof tokens?.access_token !== "string" || !tokens.access_token ||
+            typeof tokens.expires_in !== "number" || !Number.isFinite(tokens.expires_in) || tokens.expires_in <= 0 ||
+            (tokens.refresh_token !== undefined && (typeof tokens.refresh_token !== "string" || !tokens.refresh_token))) {
+            throw new Error("Login renewal returned an invalid response.");
+        }
+        // Persist rotation immediately; an API outage after renewal must not discard
+        // the new refresh token and strand the next invocation with the consumed one.
+        saveCredentials({
+            ...creds, access_token: tokens.access_token,
+            refresh_token: tokens.refresh_token ?? creds.refresh_token,
+            token_type: typeof tokens.token_type === "string" ? tokens.token_type : creds.token_type,
+            expires_at: new Date(Date.now() + tokens.expires_in * 1000).toISOString(),
+        });
+        return tokens.access_token;
+    }
+    finally {
+        rmdirSync(lock);
+    }
+}
+export async function getValidToken(signal) {
+    signal?.throwIfAborted();
+    if (process.env.ENTER_API_KEY)
+        return process.env.ENTER_API_KEY;
+    const creds = loadCredentials();
+    if (!creds?.access_token)
+        return "";
+    if (!needsRefresh(creds))
+        return creds.access_token;
+    // Cancelable callers use the same filesystem lock without canceling another
+    // caller's renewal. Once sent, renewal must finish and persist token rotation.
+    if (signal) {
+        const token = await refreshCredentials(signal);
+        signal.throwIfAborted();
+        return token;
+    }
+    if (!refreshing)
+        refreshing = refreshCredentials().finally(() => { refreshing = undefined; });
+    return refreshing;
+}

package/dist/client.d.ts

@@ -3,10 +3,7 @@ export declare function setVerbose(v: boolean): void;
 export declare function get(path: string, params?: Record<string, string>, signal?: AbortSignal): Promise<unknown>;
 export declare function post(path: string, body?: unknown, signal?: AbortSignal): Promise<unknown>;
 export declare function del(path: string): Promise<unknown>;
-export declare function put(path: string, body?: unknown): Promise<unknown>;
 export declare function patch(path: string, body?: unknown): Promise<unknown>;
 export declare function workGet(path: string, params?: Record<string, string>): Promise<unknown>;
 export declare function workPost(path: string, body?: unknown): Promise<unknown>;
-export declare function workPatch(path: string, body?: unknown): Promise<unknown>;
-export declare function workDel(path: string): Promise<unknown>;
-export declare function getRaw(path: string): Promise<Response>;
+export declare function getRaw(path: string): Promise<ArrayBuffer>;