ardent-cli-beta 0.0.17 → 0.0.18

package/NOTICE

@@ -0,0 +1,4 @@
+Ardent CLI
+Copyright 2026 ArdentAI, Inc.
+
+Licensed under the Apache License, Version 2.0. See LICENSE.

package/README.md

@@ -13,7 +13,7 @@ the Ardent frontend and returns the approved API key through a loopback callback
 bound with PKCE. `ardent-beta login --token <token>` validates and stores an existing
 API token for CI and automation; `ARDENT_TOKEN` supplies the same flag
 non-interactively. `ardent-beta status` and `ardent-beta logout` inspect and remove that
-local session. The CLI always talks to Ardent's production control plane. Oclif
+local session. The CLI defaults to Ardent's production control plane. Oclif
 provides help, version, autocomplete, and native JSON command behavior. Resource
 context is retained from login. Project listing, creation, deletion, and local
 context switching are implemented. Organization member listing, invitation,
@@ -22,6 +22,14 @@ and registration are implemented; registration follows connector status, while
 credential delivery and replication readiness remain owed. Connector-scoped branch
 creation, deletion, listing, and local switching are implemented.
 
+[openapi.json](openapi.json) describes the HTTP endpoints used by the CLI and
+ships in the npm package. It is a documentation snapshot of the control-plane
+specification from source revision `fbd09a11b9f094ebd13a7d58bda75eb0bb45b016`,
+not proof of deployed compatibility. To refresh it, replace it with the reviewed
+control-plane specification, record its source revision here, and run `make ci`.
+The package test verifies archive contents; it does not detect upstream API
+changes. Ownership and snapshot limits are recorded in [docs/DECISIONS.md](docs/DECISIONS.md).
+
 Set `ARDENT_API_URL` to point the CLI at a development control plane. Without
 it, the CLI uses `https://production.tryardent.com`.
 
@@ -63,3 +71,9 @@ context. Create and delete follow the operation in an interactive terminal;
 non-interactive commands and `--json` return the accepted operation immediately.
 
 Before changing this repository, read [ARDENT_CLI_DEVELOPMENT.md](ARDENT_CLI_DEVELOPMENT.md).
+
+Running `npm test` or `make ci` requires Node 22+, npm and `tar`. The interactive
+tests also require macOS's system `script`, or Linux's util-linux `script` with
+`-e` and `-c` support, on `PATH`. These are test prerequisites; the installed CLI
+does not invoke `script`. The PTY tests skip other operating systems and fail on
+Linux if the required utility is missing or incompatible.

package/dist/api/client.d.ts

@@ -2,7 +2,10 @@ export declare const API_URL: string;
 export declare class APIError extends Error {
     readonly status: number;
     readonly code?: string | undefined;
-    constructor(message: string, status: number, code?: string | undefined);
+    readonly workflowID?: string | undefined;
+    readonly location?: string | undefined;
+    constructor(message: string, status: number, code?: string | undefined, workflowID?: string | undefined, location?: string | undefined);
 }
+export declare function requestDurableMutation<T>(token: string, path: string, init: RequestInit, refreshCommand: string): Promise<T>;
 export declare function request<T>(token: string, path: string, init?: RequestInit): Promise<T>;
 export declare function requestWithoutAuthentication<T>(path: string, init?: RequestInit): Promise<T>;

package/dist/api/client.js

@@ -1,12 +1,39 @@
+import { terminalText } from '../terminal.js';
 const DEFAULT_TIMEOUT_MS = 10_000;
+const DURABLE_MUTATION_TIMEOUT_MS = 90_000;
 export const API_URL = process.env.ARDENT_API_URL || 'https://production.tryardent.com';
 export class APIError extends Error {
     status;
     code;
-    constructor(message, status, code) {
+    workflowID;
+    location;
+    constructor(message, status, code, workflowID, location) {
         super(message);
         this.status = status;
         this.code = code;
+        this.workflowID = workflowID;
+        this.location = location;
+    }
+}
+export async function requestDurableMutation(token, path, init, refreshCommand) {
+    // The API can await its durable workflow for 75 seconds. Allow response transit
+    // time too, without replacing an explicit caller deadline or retrying a write.
+    try {
+        return await request(token, path, {
+            ...init,
+            signal: init.signal ?? AbortSignal.timeout(DURABLE_MUTATION_TIMEOUT_MS),
+        });
+    }
+    catch (error) {
+        if (error instanceof APIError) {
+            if (error.status !== 503 || error.code !== 'workflow_result_timeout')
+                throw error;
+            const workflow = error.workflowID ? ` Workflow: ${terminalText(error.workflowID)}.` : '';
+            const location = error.location ? ` Check its status with an authenticated GET ${terminalText(error.location)}.` : '';
+            error.message = `The mutation was still running when the API stopped waiting.${workflow}${location} Run ${refreshCommand} to refresh resource state; confirm the workflow outcome before retrying.`;
+            throw error;
+        }
+        throw new Error(`The mutation response was not received completely; completion is unknown and work may still be running. Run ${refreshCommand} to refresh resource state and confirm the outcome before retrying.`, { cause: error });
     }
 }
 export async function request(token, path, init = {}) {
@@ -39,14 +66,15 @@ async function requestJSON(path, init) {
     }
     const text = await response.text();
     if (!response.ok) {
-        let detail = {};
+        let detail;
         try {
             detail = JSON.parse(text);
         }
         catch {
             // Plain-text errors still receive the status-based fallback below.
         }
-        throw new APIError(detail.message ?? `Ardent API request failed with HTTP ${response.status}.`, response.status, detail.error);
+        const fields = typeof detail === 'object' && detail !== null ? detail : {};
+        throw new APIError(typeof fields.message === 'string' ? fields.message : `Ardent API request failed with HTTP ${response.status}.`, response.status, typeof fields.error === 'string' ? fields.error : undefined, typeof fields.workflow_id === 'string' ? fields.workflow_id : undefined, response.headers.get('Location') ?? undefined);
     }
     if (response.status === 204)
         return undefined;

package/dist/command.d.ts

@@ -1,4 +1,5 @@
 import { Command } from '@oclif/core';
 export declare abstract class ArdentCommand extends Command {
     static enableJsonFlag: boolean;
+    protected catch(error: Error): Promise<void>;
 }

package/dist/command.js

@@ -1,4 +1,14 @@
 import { Command } from '@oclif/core';
+import { APIError } from './api/client.js';
+import { terminalText } from './terminal.js';
 export class ArdentCommand extends Command {
     static enableJsonFlag = true;
+    async catch(error) {
+        if (error instanceof APIError && !this.jsonEnabled()) {
+            const displayError = new APIError(terminalText(error.message), error.status, error.code === undefined ? undefined : terminalText(String(error.code)));
+            displayError.stack = error.stack?.replace(error.message, () => displayError.message);
+            return super.catch(displayError);
+        }
+        return super.catch(error);
+    }
 }

package/dist/commands/login.js

@@ -2,6 +2,7 @@ import { Flags } from '@oclif/core';
 import { loginWithBrowser } from '../auth/browser.js';
 import { loginWithToken } from '../auth/token.js';
 import { ArdentCommand } from '../command.js';
+import { terminalText } from '../terminal.js';
 export default class Login extends ArdentCommand {
     static description = 'Log in to Ardent';
     static helpGroup = 'Authentication';
@@ -20,7 +21,7 @@ export default class Login extends ArdentCommand {
             });
         this.log('✓ Logged in to Ardent');
         if (organizations.length === 1)
-            this.log(`  Organization: ${organizations[0].name} (${organizations[0].id})`);
+            this.log(`  Organization: ${terminalText(organizations[0].name)} (${terminalText(organizations[0].id)})`);
         else
             this.log(`  Organizations: ${organizations.length}`);
         return { authenticated: true, organizations };

package/dist/connectors/client.d.ts

@@ -18,7 +18,7 @@ export interface ConnectorRegistration {
 export interface ConnectorRegistrationStatus {
     connector_id: string;
     failure?: string;
-    status: 'failed' | 'registered' | 'registering';
+    status: 'deleted' | 'deleting' | 'failed' | 'registered' | 'registering';
 }
 export declare function listConnectors(token: string, organizationID: string, projectID: string): Promise<Connector[]>;
 export declare function createConnector(token: string, organizationID: string, projectID: string, environmentID: string | undefined, name: string, url: string): Promise<ConnectorRegistration>;

package/dist/connectors/client.js

@@ -1,5 +1,7 @@
 import { randomUUID } from 'node:crypto';
+import { setTimeout as delay } from 'node:timers/promises';
 import { request } from '../api/client.js';
+import { terminalText } from '../terminal.js';
 export async function listConnectors(token, organizationID, projectID) {
     const query = new URLSearchParams({ organization_id: organizationID, project_id: projectID });
     const connectors = await request(token, `/connectors?${query}`);
@@ -29,17 +31,36 @@ export async function createConnector(token, organizationID, projectID, environm
     return registration;
 }
 export async function waitForConnectorRegistration(token, connectorID, onStatus) {
-    for (;;) {
-        const status = await request(token, `/connectors/${encodeURIComponent(connectorID)}`);
-        if (!isConnectorRegistrationStatus(status, connectorID)) {
-            throw new Error('Ardent API returned an invalid connector registration status.');
+    const deadline = new AbortController();
+    const timer = setTimeout(() => deadline.abort(), 30 * 60 * 1000);
+    try {
+        for (;;) {
+            const status = await request(token, `/connectors/${encodeURIComponent(connectorID)}`, {
+                signal: AbortSignal.any([deadline.signal, AbortSignal.timeout(10_000)]),
+            });
+            deadline.signal.throwIfAborted();
+            if (!isConnectorRegistrationStatus(status, connectorID)) {
+                throw new Error('Ardent API returned an invalid connector registration status.');
+            }
+            onStatus?.(status.status);
+            if (status.status === 'registered')
+                return status;
+            if (status.status === 'failed')
+                throw new Error(terminalText(status.failure || 'Connector registration failed.'));
+            if (status.status === 'deleting' || status.status === 'deleted') {
+                throw new Error(`Connector ${terminalText(connectorID)} is ${status.status}. Run ardent-beta connector list to check its state.`);
+            }
+            await delay(2000, undefined, { signal: deadline.signal });
         }
-        onStatus?.(status.status);
-        if (status.status === 'registered')
-            return status;
-        if (status.status === 'failed')
-            throw new Error(status.failure || 'Connector registration failed.');
-        await new Promise((resolve) => setTimeout(resolve, 2000));
+    }
+    catch (error) {
+        if (deadline.signal.aborted) {
+            throw new Error(`Timed out waiting for connector ${terminalText(connectorID)} registration. Its outcome is unknown. Run ardent-beta connector list to check its state.`);
+        }
+        throw error;
+    }
+    finally {
+        clearTimeout(timer);
     }
 }
 function isConnector(value, projectID) {
@@ -75,6 +96,6 @@ function isConnectorRegistrationStatus(value, connectorID) {
         return false;
     const status = value;
     return (status.connector_id === connectorID &&
-        (status.status === 'registering' || status.status === 'registered' || status.status === 'failed') &&
+        (status.status === 'registering' || status.status === 'registered' || status.status === 'failed' || status.status === 'deleting' || status.status === 'deleted') &&
         (status.failure === undefined || typeof status.failure === 'string'));
 }

package/dist/members/client.js

@@ -1,5 +1,5 @@
 import { randomUUID } from 'node:crypto';
-import { APIError, request } from '../api/client.js';
+import { APIError, request, requestDurableMutation } from '../api/client.js';
 const sharedReadScopes = [
     'organizations.read',
     'organization_memberships.read',
@@ -60,22 +60,22 @@ export async function listReadableInvitations(token, organizationID) {
     }
 }
 export async function inviteMember(token, organizationID, email, role) {
-    const invitation = await request(token, `/organizations/${encodeURIComponent(organizationID)}/invitations`, {
+    const invitation = await requestDurableMutation(token, `/organizations/${encodeURIComponent(organizationID)}/invitations`, {
         body: JSON.stringify({ email, role_display_name: role, scopes: standardRoleScopes[role] }),
         headers: { 'Idempotency-Key': randomUUID() },
         method: 'POST',
-    });
+    }, 'ardent-beta member list');
     if (!isInvitation(invitation, organizationID))
         throw new Error('Ardent API returned an invalid invitation response.');
     return invitation;
 }
 export async function deleteMembership(token, organizationID, userID) {
-    const response = await request(token, `/organizations/${encodeURIComponent(organizationID)}/memberships/${encodeURIComponent(userID)}`, { method: 'DELETE' });
+    const response = await requestDurableMutation(token, `/organizations/${encodeURIComponent(organizationID)}/memberships/${encodeURIComponent(userID)}`, { method: 'DELETE' }, 'ardent-beta member list');
     if (response !== undefined)
         throw new Error('Ardent API did not confirm member deletion. Run ardent-beta member list before retrying.');
 }
 export async function deleteInvitation(token, organizationID, invitationID) {
-    const response = await request(token, `/organizations/${encodeURIComponent(organizationID)}/invitations/${encodeURIComponent(invitationID)}`, { method: 'DELETE' });
+    const response = await requestDurableMutation(token, `/organizations/${encodeURIComponent(organizationID)}/invitations/${encodeURIComponent(invitationID)}`, { method: 'DELETE' }, 'ardent-beta member list');
     if (response !== undefined)
         throw new Error('Ardent API did not confirm invitation cancellation. Run ardent-beta member list before retrying.');
 }

package/dist/projects/client.js

@@ -1,5 +1,5 @@
 import { randomUUID } from 'node:crypto';
-import { request } from '../api/client.js';
+import { request, requestDurableMutation } from '../api/client.js';
 export async function listProjects(token, organizationID) {
     const projects = await request(token, `/projects?organization_id=${encodeURIComponent(organizationID)}`);
     if (!Array.isArray(projects) ||
@@ -11,17 +11,17 @@ export async function listProjects(token, organizationID) {
     return projects;
 }
 export async function createProject(token, organizationID, name) {
-    const project = await request(token, '/projects', {
+    const project = await requestDurableMutation(token, '/projects', {
         body: JSON.stringify({ name, organization_id: organizationID }),
         headers: { 'Idempotency-Key': randomUUID() },
         method: 'POST',
-    });
+    }, 'ardent-beta project list');
     if (!isProject(project, organizationID))
         throw new Error('Ardent API returned an invalid project response.');
     return project;
 }
 export async function deleteProject(token, organizationID, projectID) {
-    const response = await request(token, `/projects/${encodeURIComponent(projectID)}?organization_id=${encodeURIComponent(organizationID)}`, { method: 'DELETE' });
+    const response = await requestDurableMutation(token, `/projects/${encodeURIComponent(projectID)}?organization_id=${encodeURIComponent(organizationID)}`, { method: 'DELETE' }, 'ardent-beta project list');
     if (response !== undefined) {
         throw new Error('Ardent API did not confirm project deletion. Run ardent-beta project list before retrying.');
     }

package/oclif.manifest.json

@@ -574,5 +574,5 @@
       ]
     }
   },
-  "version": "0.0.17"
+  "version": "0.0.18"
 }