ardent-cli-beta 0.0.18 → 0.0.19

package/dist/commands/connector/create.js

@@ -1,4 +1,5 @@
 import { randomUUID } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
 import { Args, Flags, ux } from '@oclif/core';
 import { loadSession } from '../../auth/credentials.js';
 import { ArdentCommand } from '../../command.js';
@@ -14,6 +15,8 @@ export default class ConnectorCreate extends ArdentCommand {
     static flags = {
         environment: Flags.string({ description: 'Environment ID (defaults to Ardent Cloud)' }),
         name: Flags.string({ char: 'n', description: 'Connector name' }),
+        'tls-client-cert': Flags.string({ description: 'PEM client certificate file (requires sslmode=require in the URL)' }),
+        'tls-client-key': Flags.string({ description: 'PEM client private-key file (requires sslmode=require in the URL)' }),
     };
     async run() {
         const { args, flags } = await this.parse(ConnectorCreate);
@@ -32,6 +35,21 @@ export default class ConnectorCreate extends ArdentCommand {
         const environmentID = flags.environment?.trim();
         if (flags.environment !== undefined && !environmentID)
             this.error('Environment ID cannot be empty.');
+        if (Boolean(flags['tls-client-cert']) !== Boolean(flags['tls-client-key']))
+            this.error('--tls-client-cert and --tls-client-key must be supplied together.');
+        let tlsClientCertificate = '';
+        let tlsClientKey = '';
+        if (flags['tls-client-cert'] && flags['tls-client-key']) {
+            try {
+                ;
+                [tlsClientCertificate, tlsClientKey] = await Promise.all([readFile(flags['tls-client-cert'], 'utf8'), readFile(flags['tls-client-key'], 'utf8')]);
+            }
+            catch {
+                this.error('Could not read the TLS client certificate pair.');
+            }
+            if (tlsClientCertificate.length > 64 * 1024 || tlsClientKey.length > 64 * 1024)
+                this.error('TLS client certificate files must each be at most 64 KiB.');
+        }
         const interactive = !this.jsonEnabled() && ux.action.type === 'spinner';
         if (interactive) {
             ux.action.start(`${terminalText(name)} in ${terminalText(session.selectedProject.name)}`, 'registering');
@@ -39,7 +57,7 @@ export default class ConnectorCreate extends ArdentCommand {
         else if (!this.jsonEnabled()) {
             this.log(`Registering connector ${terminalText(name)} for project ${terminalText(session.selectedProject.name)}...`);
         }
-        const registration = await createConnector(session.token, session.organization.id, session.selectedProject.id, environmentID, name, args.url);
+        const registration = await createConnector(session.token, session.organization.id, session.selectedProject.id, environmentID, name, args.url, tlsClientCertificate, tlsClientKey);
         if (!interactive) {
             if (!this.jsonEnabled()) {
                 this.log(`Connector registration started (${terminalText(registration.connector_id)}).`);
@@ -50,7 +68,7 @@ export default class ConnectorCreate extends ArdentCommand {
             ux.action.status = status;
         });
         ux.action.stop(ux.colorize('green', '✓ registered'));
-        this.log('Credential delivery and replication readiness are still pending.');
+        this.log('Replication readiness is still pending.');
         return { connector_id: registration.connector_id, status: 'registered' };
     }
 }

package/dist/commands/connector/delete.d.ts

@@ -0,0 +1,10 @@
+import { ArdentCommand } from '../../command.js';
+import { type ConnectorStatus } from '../../connectors/client.js';
+export default class ConnectorDelete extends ArdentCommand {
+    static args: {
+        name: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static description: string;
+    static helpGroup: string;
+    run(): Promise<ConnectorStatus>;
+}

package/dist/commands/connector/delete.js

@@ -0,0 +1,62 @@
+import { Args, ux } from '@oclif/core';
+import { loadSession, updateSession } from '../../auth/credentials.js';
+import { ArdentCommand } from '../../command.js';
+import { deleteConnector, listConnectors, waitForConnectorDeletion } from '../../connectors/client.js';
+import { terminalText } from '../../terminal.js';
+export default class ConnectorDelete extends ArdentCommand {
+    static args = { name: Args.string({ description: 'Connector name', required: true }) };
+    static description = 'Delete a connector in the selected project after its branches are deleted';
+    static helpGroup = 'Connectors';
+    async run() {
+        const { args } = await this.parse(ConnectorDelete);
+        const name = args.name.trim();
+        if (!name)
+            this.error('Connector name cannot be empty.');
+        const session = await loadSession(this.config.configDir);
+        if (!session?.organization)
+            this.error('You must be logged in to run this command. Run ardent-beta login.');
+        if (!session.selectedProject)
+            this.error('No project selected. Run ardent-beta project list, then ardent-beta project switch <name>.');
+        const connectors = await listConnectors(session.token, session.organization.id, session.selectedProject.id);
+        const connector = connectors.find((candidate) => candidate.name === name);
+        if (!connector)
+            this.error(`Connector ${terminalText(JSON.stringify(name))} not found in the selected project.`);
+        const interactive = !this.jsonEnabled() && ux.action.type === 'spinner';
+        const target = `${terminalText(connector.name)} (${terminalText(connector.id)}) in project ${terminalText(session.selectedProject.name)}`;
+        if (interactive)
+            ux.action.start(`Deleting connector ${target}`);
+        else if (!this.jsonEnabled())
+            this.log(`Deleting connector ${target}...`);
+        try {
+            await deleteConnector(session.token, connector.id);
+            if (!interactive) {
+                if (!this.jsonEnabled()) {
+                    this.log(`Connector deletion started (${terminalText(connector.id)}).`);
+                    this.log(`Run ardent-beta connector status ${terminalText(connector.id)} to check its state.`);
+                }
+                return { connector_id: connector.id, status: 'deleting' };
+            }
+            const result = await waitForConnectorDeletion(session.token, connector.id, (status) => { ux.action.status = status; });
+            await updateSession(this.config.configDir, (current) => {
+                if (!current || current.token !== session.token || current.organization?.id !== session.organization?.id || current.selectedProject?.id !== session.selectedProject?.id)
+                    return;
+                const updated = { ...current, connectors: current.connectors?.filter(({ id }) => id !== connector.id) };
+                if (updated.selectedConnector?.id === connector.id) {
+                    delete updated.selectedConnector;
+                    delete updated.branches;
+                    delete updated.selectedBranch;
+                }
+                return updated;
+            });
+            ux.action.stop(ux.colorize('green', '✓ deleted'));
+            if (result.failure)
+                this.warn(`Source cleanup residue: ${terminalText(result.failure)}. Check the source database for remaining capture objects.`);
+            return result;
+        }
+        catch (error) {
+            if (interactive)
+                ux.action.stop('failed');
+            throw error;
+        }
+    }
+}

package/dist/commands/connector/status.d.ts

@@ -0,0 +1,10 @@
+import { ArdentCommand } from '../../command.js';
+import { type ConnectorStatus } from '../../connectors/client.js';
+export default class ConnectorStatusCommand extends ArdentCommand {
+    static args: {
+        id: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static description: string;
+    static helpGroup: string;
+    run(): Promise<ConnectorStatus>;
+}

package/dist/commands/connector/status.js

@@ -0,0 +1,28 @@
+import { Args } from '@oclif/core';
+import { loadSession } from '../../auth/credentials.js';
+import { ArdentCommand } from '../../command.js';
+import { getConnectorStatus } from '../../connectors/client.js';
+import { terminalText } from '../../terminal.js';
+export default class ConnectorStatusCommand extends ArdentCommand {
+    static args = { id: Args.string({ description: 'Connector ID returned by create or delete', required: true }) };
+    static description = 'Show connector registration or deletion status by ID';
+    static helpGroup = 'Connectors';
+    async run() {
+        const { args } = await this.parse(ConnectorStatusCommand);
+        const id = args.id.trim();
+        if (!id)
+            this.error('Connector ID cannot be empty.');
+        const session = await loadSession(this.config.configDir);
+        if (!session?.organization)
+            this.error('You must be logged in to run this command. Run ardent-beta login.');
+        const result = await getConnectorStatus(session.token, id);
+        if (!this.jsonEnabled()) {
+            this.log(`Connector ${terminalText(result.connector_id)}: ${result.status}`);
+            if (result.phase)
+                this.log(`Phase: ${terminalText(result.phase)}`);
+            if (result.failure)
+                this.log(`${result.status === 'deleted' ? 'Source cleanup residue' : 'Failure'}: ${terminalText(result.failure)}`);
+        }
+        return result;
+    }
+}

package/dist/commands/connector/switch.d.ts

@@ -0,0 +1,12 @@
+import { ArdentCommand } from '../../command.js';
+export default class ConnectorSwitch extends ArdentCommand {
+    static args: {
+        name: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static description: string;
+    static helpGroup: string;
+    run(): Promise<{
+        id: string;
+        name: string;
+    }>;
+}

package/dist/commands/connector/switch.js

@@ -0,0 +1,45 @@
+import { Args } from '@oclif/core';
+import { loadSession, updateSession } from '../../auth/credentials.js';
+import { ArdentCommand } from '../../command.js';
+import { listConnectors } from '../../connectors/client.js';
+import { terminalText } from '../../terminal.js';
+export default class ConnectorSwitch extends ArdentCommand {
+    static args = { name: Args.string({ description: 'Connector name', required: true }) };
+    static description = 'Switch to a connector in the selected project';
+    static helpGroup = 'Connectors';
+    async run() {
+        const { args } = await this.parse(ConnectorSwitch);
+        const name = args.name.trim();
+        if (!name)
+            this.error('Connector name cannot be empty.');
+        const session = await loadSession(this.config.configDir);
+        if (!session?.organization)
+            this.error('You must be logged in to run this command. Run ardent-beta login.');
+        if (!session.selectedProject)
+            this.error('No project selected. Run ardent-beta project list, then ardent-beta project switch <name>.');
+        const connectors = await listConnectors(session.token, session.organization.id, session.selectedProject.id);
+        const connector = connectors.find((candidate) => candidate.name === name);
+        if (!connector)
+            this.error(`Connector ${terminalText(JSON.stringify(name))} not found in the selected project.`);
+        // Decide before persisting: a refused switch must preserve the existing target.
+        const switched = await updateSession(this.config.configDir, (current) => {
+            if (!current || current.token !== session.token || current.organization?.id !== session.organization?.id || current.selectedProject?.id !== session.selectedProject?.id)
+                return;
+            const updated = {
+                ...current,
+                connectors: connectors.map(({ id, name, project_id }) => ({ id, name, project_id })),
+                selectedConnector: { id: connector.id, name: connector.name, project_id: connector.project_id },
+            };
+            if (current.selectedConnector?.id !== connector.id) {
+                delete updated.branches;
+                delete updated.selectedBranch;
+            }
+            return updated;
+        });
+        if (!switched)
+            this.error('Local context changed during connector discovery. Retry the switch in your current project.');
+        if (!this.jsonEnabled())
+            this.log(`✓ Switched to connector ${terminalText(connector.name)}`);
+        return { id: connector.id, name: connector.name };
+    }
+}

package/dist/commands/login.js

@@ -11,7 +11,13 @@ export default class Login extends ArdentCommand {
     };
     async run() {
         const { flags } = await this.parse(Login);
-        const organizations = flags.token
+        // Oclif discards an empty environment value, so without this an ARDENT_TOKEN
+        // that expands to nothing, such as a missing CI secret, would start a
+        // 30-minute browser login instead of failing.
+        if (flags.token === undefined && process.env.ARDENT_TOKEN !== undefined) {
+            this.error('ARDENT_TOKEN is set but empty. Set it to an Ardent API token, or unset it to log in with the browser.');
+        }
+        const organizations = flags.token !== undefined
             ? await loginWithToken(this.config.configDir, flags.token)
             : await loginWithBrowser(this.config.configDir, {
                 onAuthorizationURL: (url, opened) => {

package/dist/commands/project/switch.js

@@ -33,7 +33,7 @@ export default class ProjectSwitch extends ArdentCommand {
             // non-zero having quietly selected a different project underneath.
             project = projects.find((candidate) => candidate.name === name);
             if (!project) {
-                this.error(`Project ${JSON.stringify(name)} not found in organization ${JSON.stringify(session.organization.name)}.`);
+                this.error(`Project ${JSON.stringify(name)} not found in organization ${terminalText(JSON.stringify(session.organization.name))}.`);
             }
             session = await replaceProjectCache(this.config.configDir, session, projects);
         }

package/dist/connectors/client.d.ts

@@ -15,11 +15,15 @@ export interface Connector {
 export interface ConnectorRegistration {
     connector_id: string;
 }
-export interface ConnectorRegistrationStatus {
+export interface ConnectorStatus {
     connector_id: string;
     failure?: string;
-    status: 'deleted' | 'deleting' | 'failed' | 'registered' | 'registering';
+    phase?: string;
+    status: 'deleted' | 'deleting' | 'failed' | 'halted' | '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>;
-export declare function waitForConnectorRegistration(token: string, connectorID: string, onStatus?: (status: ConnectorRegistrationStatus['status']) => void): Promise<ConnectorRegistrationStatus>;
+export declare function createConnector(token: string, organizationID: string, projectID: string, environmentID: string | undefined, name: string, url: string, tlsClientCertificate?: string, tlsClientKey?: string): Promise<ConnectorRegistration>;
+export declare function waitForConnectorRegistration(token: string, connectorID: string, onStatus?: (status: ConnectorStatus['status']) => void): Promise<ConnectorStatus>;
+export declare function deleteConnector(token: string, connectorID: string): Promise<ConnectorRegistration>;
+export declare function getConnectorStatus(token: string, connectorID: string, signal?: AbortSignal): Promise<ConnectorStatus>;
+export declare function waitForConnectorDeletion(token: string, connectorID: string, onStatus?: (status: ConnectorStatus['status']) => void): Promise<ConnectorStatus>;

package/dist/connectors/client.js

@@ -1,6 +1,6 @@
 import { randomUUID } from 'node:crypto';
 import { setTimeout as delay } from 'node:timers/promises';
-import { request } from '../api/client.js';
+import { APIError, request, requestDurableMutation } 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 });
@@ -13,7 +13,7 @@ export async function listConnectors(token, organizationID, projectID) {
     }
     return connectors;
 }
-export async function createConnector(token, organizationID, projectID, environmentID, name, url) {
+export async function createConnector(token, organizationID, projectID, environmentID, name, url, tlsClientCertificate, tlsClientKey) {
     const requestID = randomUUID();
     const registration = await request(token, '/connectors', {
         body: JSON.stringify({
@@ -23,6 +23,7 @@ export async function createConnector(token, organizationID, projectID, environm
             project_id: projectID,
             request_id: requestID,
             url,
+            ...(tlsClientCertificate ? { tls_client_certificate: tlsClientCertificate, tls_client_key: tlsClientKey } : {}),
         }),
         method: 'POST',
     });
@@ -31,32 +32,79 @@ export async function createConnector(token, organizationID, projectID, environm
     return registration;
 }
 export async function waitForConnectorRegistration(token, connectorID, onStatus) {
+    return waitForConnectorStatus(token, connectorID, 'registered', onStatus);
+}
+export async function deleteConnector(token, connectorID) {
+    const result = await requestDurableMutation(token, `/connectors/${encodeURIComponent(connectorID)}`, {
+        method: 'DELETE',
+    }, `ardent-beta connector status ${terminalText(connectorID)}`);
+    if (!isConnectorRegistration(result) || result.connector_id !== connectorID) {
+        throw new Error(`The Ardent API accepted the connector deletion request but returned no matching connector; completion is unknown. Run ardent-beta connector status ${terminalText(connectorID)} before retrying.`);
+    }
+    return result;
+}
+export async function getConnectorStatus(token, connectorID, signal) {
+    const result = await request(token, `/connectors/${encodeURIComponent(connectorID)}`, { signal });
+    if (!isConnectorStatus(result, connectorID))
+        throw new Error('Ardent API returned an invalid connector status.');
+    return {
+        connector_id: result.connector_id,
+        status: result.status,
+        ...(result.phase === undefined ? {} : { phase: result.phase }),
+        ...(result.failure === undefined ? {} : { failure: result.failure }),
+    };
+}
+export async function waitForConnectorDeletion(token, connectorID, onStatus) {
+    return waitForConnectorStatus(token, connectorID, 'deleted', onStatus);
+}
+async function waitForConnectorStatus(token, connectorID, expected, onStatus) {
     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)]),
-            });
+            const status = await getConnectorStatus(token, connectorID, 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')
+            if (status.status === expected)
                 return status;
+            if (expected === 'deleted') {
+                if (status.status !== 'deleting' || status.failure === 'connector_deletion_failed') {
+                    const reason = status.failure ? `: ${terminalText(status.failure)}` : '';
+                    throw new Error(`Connector ${terminalText(connectorID)} is ${status.status}${reason}. Deletion is not confirmed.`);
+                }
+                await delay(2000, undefined, { signal: deadline.signal });
+                continue;
+            }
             if (status.status === 'failed')
                 throw new Error(terminalText(status.failure || 'Connector registration failed.'));
+            if (status.status === 'halted') {
+                // Not success, and not polled through: docs/REQUIREMENTS.md section 7's
+                // "a halt does not clear by being polled".
+                const reason = status.failure ? `: ${terminalText(status.failure)}` : '';
+                throw new Error(`Connector ${terminalText(connectorID)} is halted${reason}. Run ardent-beta connector list to check its state.`);
+            }
             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.`);
+                const reason = status.failure ? `: ${terminalText(status.failure)}` : '';
+                // connector list leaves deleted connectors out, so it can only check a
+                // connector that is still deleting.
+                const next = status.status === 'deleting' ? 'Run ardent-beta connector list to check its state.' : 'It will not appear in ardent-beta connector list.';
+                throw new Error(`Connector ${terminalText(connectorID)} is ${status.status}${reason}. ${next}`);
             }
             await delay(2000, undefined, { signal: deadline.signal });
         }
     }
     catch (error) {
         if (deadline.signal.aborted) {
+            if (expected === 'deleted')
+                throw new Error(`Timed out waiting for connector ${terminalText(connectorID)} deletion. Its outcome is unknown. Run ardent-beta connector status ${terminalText(connectorID)} before retrying.`);
             throw new Error(`Timed out waiting for connector ${terminalText(connectorID)} registration. Its outcome is unknown. Run ardent-beta connector list to check its state.`);
         }
+        if (expected === 'deleted') {
+            if (error instanceof APIError)
+                throw new APIError(`${error.message} Run ardent-beta connector status ${terminalText(connectorID)} to confirm the deletion outcome before retrying.`, error.status, error.code);
+            const reason = error instanceof Error ? terminalText(error.message) : 'The status request failed.';
+            throw new Error(`${reason} Run ardent-beta connector status ${terminalText(connectorID)} to confirm the deletion outcome before retrying.`);
+        }
         throw error;
     }
     finally {
@@ -91,11 +139,12 @@ function isConnectorRegistration(value) {
     const registration = value;
     return typeof registration.connector_id === 'string' && registration.connector_id.length > 0;
 }
-function isConnectorRegistrationStatus(value, connectorID) {
+function isConnectorStatus(value, connectorID) {
     if (typeof value !== 'object' || value === null)
         return false;
     const status = value;
     return (status.connector_id === connectorID &&
-        (status.status === 'registering' || status.status === 'registered' || status.status === 'failed' || status.status === 'deleting' || status.status === 'deleted') &&
-        (status.failure === undefined || typeof status.failure === 'string'));
+        (status.status === 'registering' || status.status === 'registered' || status.status === 'failed' || status.status === 'halted' || status.status === 'deleting' || status.status === 'deleted') &&
+        (status.failure === undefined || typeof status.failure === 'string') &&
+        (status.phase === undefined || typeof status.phase === 'string'));
 }

package/dist/terminal.d.ts

@@ -1 +1,2 @@
 export declare function terminalText(value: string): string;
+export declare function shellWord(value: string): string;

package/dist/terminal.js

@@ -7,3 +7,10 @@ export function terminalText(value) {
         return `\\u${codePoint.toString(16).padStart(4, '0')}`;
     });
 }
+// shellWord renders a value as one POSIX shell word, for a command a reader is
+// meant to copy. Anything beyond a conservative safe set is single-quoted.
+export function shellWord(value) {
+    if (/^[A-Za-z0-9_.,:\/@%+=-]+$/.test(value))
+        return value;
+    return `'${value.replaceAll("'", "'\\''")}'`;
+}