@enter-pro/enter-cli 0.4.2 → 0.4.4

package/README.md

@@ -1,252 +1,249 @@
 # 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.
+
+`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.
+
+## Submit, observe and deliver
 
 ```sh
-npm ci
-npm test
+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 wait PROJECT_ID --task-id TASK_ID --stream --timeout 0
 ```
 
-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.
+`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.
 
-### Interactive local simulator
+| Command | Output and default lifetime |
+| --- | --- |
+| `status` | One JSON/YAML snapshot, 30-second deadline |
+| `wait --stream` | One continuous observer with batched NDJSON; unlimited by default, explicit --timeout bounds lifetime |
+| `wait` | One result on new narrative progress, a card, terminal state or timeout; 10 seconds |
+| `watch` | Changed snapshots as NDJSON, then `type: result`; 60 seconds; unlimited only with explicit `--timeout 0` |
+
+Use one observer per task. Hosts that buffer shell output use bounded `wait`;
+Helix uses `--timeout 10` to return control regularly. On timeout, first handle
+incoming user messages, then report the actual state and continue the returned command for the same task,
+without sleep, resubmission or repeated permission questions. Hosts that consume
+stdout incrementally should use `wait --stream`; unchanged successful observations emit a
+heartbeat every max(30 seconds, progress interval). Hosts own scheduling and interruption.
+
+`--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.
 
-Requires Node 18+ and npm; no Docker, Work server, database, or credentials are
-needed. From this repository, build once and start the fixture server:
+| 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 |
+
+`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/watch` return monitoring fields by default, excluding usage and unrelated metadata.
+Use `--full` for detailed sanitized metadata; `--compact` remains an explicit alias for the default.
+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 defaults to HTTP polling every 2 seconds after each read. Each
+snapshot query is bounded to 30 seconds. No WebSocket is opened by default.
+`--transport auto` opts in to WebSocket events with HTTP fallback; 401/403 on the
+stream stops reconnection but leaves state observation on HTTP. Raw message
+follow still fails with STREAM_AUTH_ERROR. HTTP authentication failures stop
+observation. WebSockets respect proxy variables and NO_PROXY.
+
+`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
+npm ci
+npm test
 npm run build
-npm run mock:serve
+npm pack
+npm run install:hosts -- --package /absolute/path/enter-pro-enter-cli-0.4.4.tgz
 ```
 
-In another terminal in this repository:
+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.
+
+For manual simulation, run `npm run mock:serve`, then in another terminal:
 
 ```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
-```
-
-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.
-
-| Project ID | Scenario |
-| --- | --- |
-| `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
 ```
 
-`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.
-
-### CLI: submit once, observe the returned task
-
-```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
+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.
+
+### Agent host integration
+
+All observers return `progress` from the selected task's HTTP message history:
+`source: assistant_messages`, `available`, a scoped `revision`, and the latest
+assistant text in `messages` (up to 1600 characters, marked `truncated` if clipped).
+Reasoning and raw tool arguments are excluded. `observed_at` timestamps the last
+successful state read; `emitted_at` timestamps watch output, including stale results.
+A narrative read failure is separate from authoritative task/action status.
+
+`wait` batches ordinary narrative for 10 seconds by default, keeping the latest text,
+and returns early when that interval has elapsed and progress changed.
+`--progress-interval <seconds>` controls batching; `0` opts into every change.
+Actions, terminal states and errors bypass batching. The overall `--timeout` still
+bounds the call and returns the latest observation even before the interval elapses.
+`status` remains an immediate read; no phase is guessed from narrative keywords. `workflow.next_action=report_progress` means relay the text first, then `after_reporting=observe`. Exit 0 means an observation result, not build completion. Execute the returned `wait_command`, including
+`--after-progress`, to wait for the next revision without replaying the same update.
+`watch` uses the same interval for ordinary narrative/metadata updates; state changes
+and final results are emitted immediately.
+These are latest-progress snapshots, not a lossless replay of every message.
+
+The host agent relays the supplied text, forwards questions, and executes the next
+command; it need not reason over logs or infer development phases. Relay new progress
+proactively, suppress repeated revisions/heartbeats, and answer user questions from
+the last observation before refreshing. Background hosts with only completion notifications fall back to bounded `wait`: batched progress ends the job and triggers that notification. Merely being able to read running stdout is insufficient for automatic `watch` delivery. For background jobs, read output nonblockingly
+or with a short bounded wait; a five-minute blocking job-output call defeats background
+execution. The CLI cannot schedule the host agent or interrupt its tool calls.
+
+Both `wait` and `watch` use HTTP by default. The CLI performs the polling;
+do not generate `sleep && enter-cli` or a loop of `thread status` commands.
+
+For hosts that return shell output only after the command exits, use `wait`.
+For the current Helix integration, use a short 10-second observation window
+to return control for incoming messages:
+
+```bash
 enter-cli --output json thread wait PROJECT_ID --task-id TASK_ID --timeout 10
 ```
 
-`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.
-
-| 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:
-
-```sh
-enter-cli thread messages PROJECT_ID --follow --timeout 60 --cursor EVENT_ID
-```
-
-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 CLI and Helix guidance both default to 10 seconds. A shell deadline alone
+does not guarantee responsiveness. On exit 2, handle incoming messages, report
+the returned Enter stage/status and execute the returned `wait_command` to keep observing.
+It preserves the task or pinned turn, chat, build requirement and observation
+timeout. Do not ask the user whether to continue, recreate the project or
+resubmit the build. A timeout ends observation, not the remote task. On
+`blocked`, forward the action and follow the continuation after answering;
+on `completed` or `failed`, consume the result.
+
+For hosts that notify the agent when incremental stdout arrives without blocking user interaction,
+use `watch_command` (60 seconds by default). Only explicitly select `--timeout 0`
+when the host can manage an unlimited background observer.
+`snapshot` contains actual Enter task/turn state, `heartbeat` confirms a
+successful observation without a state change, and `result` ends observation.
+This is stage/status progress, not generated percentages or a raw model-token
+log. Each snapshot query has a 30-second deadline. SIGINT/SIGTERM stop only
+the observer (130/143); the host owns background execution and reconnection.
+
+The current Helix sandbox adapter buffers stdout until command completion;
+therefore an indefinitely running `watch` is not its default integration path.
+Helix colleagues only need to update the actual sandbox CLI and the agent's
+usage instructions for the bounded `wait` path, then verify it in a fresh
+sandbox. Continuous in-flight display requires host-side incremental output
+support; local CLI tests do not prove that integration.
+
+State and pending-action reads run concurrently to avoid spending the observation
+budget on sequential independent requests. Failed turns do not wait for pending
+action reads. `QUERY_TIMEOUT` before the first snapshot means the observation
+deadline expired without a known task state; it does not locate the cause in the
+network or server. The overall deadline remains bounded. Usage changes are not
+progress; continue quietly when there is no new narrative or actionable state.
+
+### One background observer
+
+Use `enter-cli thread wait PROJECT_ID --task-id TASK_ID --stream --timeout 0`
+with a host that supports managed background execution and incremental output delivery.
+The CLI polls HTTP internally and emits batched progress until an action, terminal state,
+interruption or explicit deadline. Ordinary progress does not end this process.
+Consume events without blocking user interaction; do not restart it on report_progress.
+The returned `stream_argv` / `stream_command` starts this observer.
+`watch` remains a compatible streaming entry point.
+
+Without `--stream`, wait retains its bounded single-JSON contract for buffered hosts.
+This fallback can require repeated calls; CLI cannot enable host background scheduling.
+Do not detach with shell `&` or assume buffered Bash output is delivered incrementally.

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;
+}