ardent-cli-beta 0.0.17 → 0.0.19

package/dist/branches/recovery.js

@@ -0,0 +1,211 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { link, open, readFile, readdir, rename, unlink, writeFile } from 'node:fs/promises';
+import { createConnection, createServer } from 'node:net';
+import { dirname, join } from 'node:path';
+import { API_URL } from '../api/client.js';
+import { issueBranchCredential, refusedBeforeIssuance, revokeBranchCredential, validSourceRole } from './credentials.js';
+export class CredentialRecoveryCleanupError extends Error {
+    stage;
+    constructor(stage, cause) {
+        super(`Could not ${stage === 'remove' ? 'remove' : 'sync'} the local credential recovery record.`, { cause });
+        this.stage = stage;
+    }
+}
+const prefix = 'branch-connect-recovery-';
+const filename = /^branch-connect-recovery-(.+)-([0-9a-f]{32})-([0-9a-f]{32})-([1-9][0-9]*)-([0-9a-f-]{36})\.json$/;
+function digest(value) {
+    return createHash('sha256').update(value).digest('hex').slice(0, 32);
+}
+function recoveryPath(directory, branchID, token, port, requestID) {
+    const branch = Buffer.from(branchID, 'utf8').toString('base64url');
+    return join(directory, `${prefix}${branch}-${digest(new URL(API_URL).origin)}-${digest(token)}-${port}-${requestID}.json`);
+}
+async function syncDirectory(file) {
+    const directory = await open(dirname(file), 'r');
+    try {
+        await directory.sync();
+    }
+    finally {
+        await directory.close();
+    }
+}
+export async function openCredentialWitness(requestID) {
+    const server = createServer((socket) => {
+        let received = '';
+        socket.setTimeout(1000, () => socket.destroy());
+        socket.setEncoding('utf8');
+        socket.on('data', (chunk) => {
+            received += chunk;
+            if (received === `${requestID}\n`)
+                socket.end(`ardent-branch-connect-live:${requestID}\n`);
+            else if (received.length > 64)
+                socket.destroy();
+        });
+    });
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(0, '127.0.0.1', resolve);
+    });
+    const address = server.address();
+    if (!address || typeof address === 'string')
+        throw new Error('Could not reserve a local branch connection witness.');
+    return {
+        port: address.port,
+        close: () => new Promise((resolve) => server.close(() => resolve())),
+    };
+}
+async function witnessState(port, requestID) {
+    return new Promise((resolve) => {
+        const socket = createConnection({ host: '127.0.0.1', port });
+        let settled = false;
+        let response = '';
+        const finish = (state) => {
+            if (settled)
+                return;
+            settled = true;
+            socket.destroy();
+            resolve(state);
+        };
+        socket.setTimeout(1000, () => finish('unknown'));
+        socket.once('connect', () => socket.write(`${requestID}\n`));
+        socket.on('data', (chunk) => {
+            response += chunk.toString('utf8');
+            if (response.includes('\n'))
+                finish(response === `ardent-branch-connect-live:${requestID}\n` ? 'live' : 'dead');
+            else if (response.length > 128)
+                finish('dead');
+        });
+        socket.once('end', () => finish('dead'));
+        socket.once('error', (error) => finish(error.code === 'ECONNREFUSED' ? 'dead' : 'unknown'));
+    });
+}
+async function writeRecord(file, record, replace) {
+    const temporary = `${file}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(temporary, `${JSON.stringify(record)}\n`, { flag: 'wx', mode: 0o600 });
+        const handle = await open(temporary, 'r');
+        try {
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        if (replace)
+            await rename(temporary, file);
+        else
+            await link(temporary, file);
+        await syncDirectory(file);
+    }
+    finally {
+        await unlink(temporary).catch((error) => {
+            if (error.code !== 'ENOENT')
+                throw error;
+        });
+    }
+}
+export async function rememberCredentialRequest(directory, branchID, token, port, requestID, sourceRole) {
+    const file = recoveryPath(directory, branchID, token, port, requestID);
+    await writeRecord(file, { request_id: requestID, ...(sourceRole === undefined ? {} : { source_role: sourceRole }) }, false);
+    return { file, branchID, requestID, sourceRole };
+}
+export async function rememberCredentialIssuance(recovery, issuanceID) {
+    recovery.issuanceID = issuanceID;
+    await writeRecord(recovery.file, { request_id: recovery.requestID, issuance_id: issuanceID, ...(recovery.sourceRole === undefined ? {} : { source_role: recovery.sourceRole }) }, true);
+}
+// forgetCredentialRecovery removes a record and syncs its directory. A record
+// already removed, by an earlier attempt whose sync failed, is removed; the
+// sync is still retried.
+export async function forgetCredentialRecovery(recovery) {
+    try {
+        await unlink(recovery.file);
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw new CredentialRecoveryCleanupError('remove', error);
+    }
+    try {
+        await syncDirectory(recovery.file);
+    }
+    catch (error) {
+        throw new CredentialRecoveryCleanupError('sync', error);
+    }
+}
+export async function recoverBranchCredentials(directory, token) {
+    let names;
+    try {
+        names = await readdir(directory);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return 0;
+        throw error;
+    }
+    let recovered = 0;
+    const failures = [];
+    for (const name of names.filter((entry) => entry.startsWith(prefix) && entry.endsWith('.json')).sort()) {
+        const match = filename.exec(name);
+        if (!match) {
+            failures.push(`Unrecognized branch credential recovery file ${name}.`);
+            continue;
+        }
+        const [, encodedBranch, originHash, tokenHash, portText, requestID] = match;
+        const branchID = Buffer.from(encodedBranch, 'base64url').toString('utf8');
+        if (!branchID || Buffer.from(branchID, 'utf8').toString('base64url') !== encodedBranch) {
+            failures.push(`Invalid branch credential recovery file ${name}.`);
+            continue;
+        }
+        const file = join(directory, name);
+        let record;
+        try {
+            record = JSON.parse(await readFile(file, 'utf8'));
+        }
+        catch {
+            failures.push(`Cannot read branch credential recovery file ${name}.`);
+            continue;
+        }
+        if (!record || typeof record !== 'object' || record.request_id !== requestID ||
+            (record.issuance_id !== undefined && (typeof record.issuance_id !== 'string' || !/^[A-Za-z0-9_-]{1,128}$/.test(record.issuance_id))) ||
+            (record.source_role !== undefined && (typeof record.source_role !== 'string' || !validSourceRole(record.source_role)))) {
+            failures.push(`Invalid branch credential recovery file ${name}.`);
+            continue;
+        }
+        if (originHash !== digest(new URL(API_URL).origin) || tokenHash !== digest(token)) {
+            const id = record.issuance_id ? ` issuance ${record.issuance_id}` : ` request ${requestID}`;
+            failures.push(`Pending branch credential${id} belongs to another API target or login; restore those settings to revoke it.`);
+            continue;
+        }
+        const port = Number(portText);
+        const state = Number.isSafeInteger(port) && port <= 65535 ? await witnessState(port, requestID) : 'unknown';
+        if (state !== 'dead') {
+            failures.push(`Branch credential ${record.issuance_id ?? `request ${requestID}`} has a ${state === 'live' ? 'running session' : 'session whose state is unknown'}; finish or resolve that session before connecting again.`);
+            continue;
+        }
+        const recovery = { file, branchID, requestID, issuanceID: record.issuance_id, sourceRole: record.source_role };
+        try {
+            if (!recovery.issuanceID) {
+                let issuanceID;
+                try {
+                    issuanceID = await issueBranchCredential(token, branchID, requestID, recovery.sourceRole);
+                }
+                catch (error) {
+                    // The API refuses a source role before it records an issuance and
+                    // after it replays one, so this request created nothing to revoke.
+                    if (!refusedBeforeIssuance(error))
+                        throw error;
+                    await forgetCredentialRecovery(recovery);
+                    continue;
+                }
+                await rememberCredentialIssuance(recovery, issuanceID);
+            }
+            await revokeBranchCredential(token, recovery.issuanceID);
+            await forgetCredentialRecovery(recovery);
+            recovered++;
+        }
+        catch {
+            failures.push(`Could not confirm cleanup of branch credential issuance ${recovery.issuanceID ?? `from request ${requestID}`}; retry with the same API target and login, or revoke it manually.`);
+        }
+    }
+    if (failures.length)
+        throw new Error(failures.join(' '));
+    return recovered;
+}

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/branch/connect.d.ts

@@ -0,0 +1,12 @@
+import { type PrintedConnection } from '../../branches/connection.js';
+import { ArdentCommand } from '../../command.js';
+export default class BranchConnect extends ArdentCommand {
+    static description: string;
+    static flags: {
+        driver: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        print: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        role: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    static helpGroup: string;
+    run(): Promise<PrintedConnection | void>;
+}

package/dist/commands/branch/connect.js

@@ -0,0 +1,87 @@
+import { Flags } from '@oclif/core';
+import { API_URL } from '../../api/client.js';
+import { loadSession } from '../../auth/credentials.js';
+import { listBranches } from '../../branches/client.js';
+import { connectToBranch } from '../../branches/connection.js';
+import { validSourceRole } from '../../branches/credentials.js';
+import { DRIVERS, validDriver } from '../../branches/drivers.js';
+import { checkPsql } from '../../branches/psql.js';
+import { recoverBranchCredentials } from '../../branches/recovery.js';
+import { ArdentCommand } from '../../command.js';
+import { shellWord, terminalText } from '../../terminal.js';
+export default class BranchConnect extends ArdentCommand {
+    static description = 'Connect to the selected active branch with psql, or print a connection string for your driver';
+    static flags = {
+        driver: Flags.string({
+            default: 'libpq',
+            description: 'The driver --print writes a connection string for: libpq (psql, psycopg, pgx), node (node-postgres, postgres.js), jdbc (pgjdbc) or prisma (Prisma)',
+            options: [...DRIVERS],
+        }),
+        print: Flags.boolean({ description: 'Print a connection string for --driver and keep the credential active, instead of opening psql' }),
+        role: Flags.string({ description: 'Sign in as this source role on the branch (for example postgres), with a fresh password that works on this branch only' }),
+    };
+    static helpGroup = 'Branches';
+    async run() {
+        const { flags } = await this.parse(BranchConnect);
+        const sourceRole = flags.role;
+        const print = flags.print;
+        if (!validDriver(flags.driver))
+            this.error(`--driver must be one of ${DRIVERS.join(', ')}.`);
+        const driver = flags.driver;
+        // psql is a libpq client: only the libpq form opens it, and any other form
+        // is for an application, so it is only printed.
+        if (!print && driver !== 'libpq')
+            this.error(`psql connects with the libpq form. Add --print to output the ${driver} connection string instead.`);
+        // Checked before anything is recorded or sent: an empty value would
+        // otherwise ask for an ordinary credential, and a mistyped one would be
+        // kept in a recovery record.
+        if (sourceRole !== undefined && !validSourceRole(sourceRole)) {
+            this.error(`--role must name a source role as a lower-case PostgreSQL identifier that begins with neither pg_ nor ardent; got ${JSON.stringify(terminalText(sourceRole))}.`);
+        }
+        if (this.jsonEnabled() && !print)
+            this.error('branch connect opens interactive psql and supports --json only with --print.');
+        // With --print, stdout carries the connection string alone; everything
+        // else goes to stderr.
+        const say = (message) => { if (print)
+            this.logToStderr(message);
+        else
+            this.log(message); };
+        const session = await loadSession(this.config.configDir);
+        if (!session)
+            this.error('Log in before connecting to a branch.');
+        const recovered = await recoverBranchCredentials(this.config.configDir, session.token);
+        if (recovered)
+            say(`Revoked ${recovered} credential issuance(s) left by an earlier branch connect.`);
+        if (!session.selectedConnector || !session.selectedBranch) {
+            this.error('Select a branch first with ardent-beta branch switch <name>.');
+        }
+        const branch = session.selectedBranch;
+        const connector = session.selectedConnector;
+        const branches = await listBranches(session.token, connector.id);
+        const current = branches.find((candidate) => candidate.id === branch.id && candidate.name === branch.name);
+        if (current?.state === 'PARKED') {
+            const parked = 'The selected branch is parked, and a parked branch refuses connections until it is woken.';
+            // A name terminalText would alter cannot be printed as a command to copy:
+            // the copy would name a different branch.
+            if (terminalText(branch.name) !== branch.name) {
+                this.error(`${parked} Its name contains terminal control characters (shown escaped: ${terminalText(branch.name)}), so no command is printed to copy; run ardent-beta branch wake with that exact name.`);
+            }
+            // -- ends option parsing, so a name such as --json stays the name. The
+            // command sits alone on its own line with no trailing punctuation, so a
+            // copy names exactly this branch.
+            this.error(`${parked} To wake it, run:\n  ardent-beta branch wake -- ${shellWord(branch.name)}`);
+        }
+        if (current?.state !== 'ACTIVE') {
+            this.error('The selected branch is not active. Run ardent-beta branch list to refresh its status.');
+        }
+        if (!print)
+            await checkPsql();
+        const as = sourceRole === undefined ? '' : ` as source role ${sourceRole}, with a new branch-only password,`;
+        const verb = print ? `Issuing a ${driver} connection string for` : 'Connecting to';
+        say(`${verb} branch ${terminalText(branch.name)} in connector ${terminalText(connector.name)}${as} via ${terminalText(new URL(API_URL).origin)}...`);
+        return connectToBranch({
+            configDir: this.config.configDir, token: session.token, branchID: branch.id, sourceRole, print, driver,
+            json: this.jsonEnabled(), say, log: (message) => this.log(message), warn: (message) => this.warn(message),
+        });
+    }
+}

package/dist/commands/branch/create.d.ts

@@ -1,11 +1,19 @@
 import { ArdentCommand } from '../../command.js';
 import { type BranchOperation } from '../../branches/client.js';
+import { type PrintedConnection } from '../../branches/connection.js';
 export default class BranchCreate extends ArdentCommand {
     static args: {
         name: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
     };
     static strict: boolean;
     static description: string;
+    static flags: {
+        driver: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        print: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'to-env': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
     static helpGroup: string;
-    run(): Promise<BranchOperation>;
+    run(): Promise<BranchOperation & {
+        credential: PrintedConnection;
+    }>;
 }

package/dist/commands/branch/create.js

@@ -1,38 +1,96 @@
-import { Args, ux } from '@oclif/core';
+import { Args, Flags, ux } from '@oclif/core';
+import { APIError, API_URL } from '../../api/client.js';
+import { updateSession } from '../../auth/credentials.js';
 import { ArdentCommand } from '../../command.js';
-import { branchName, createBranch, waitForBranchOperation } from '../../branches/client.js';
-import { replaceBranchCache } from '../../branches/context.js';
+import { branchName, createBranch, listBranches, waitForBranchOperation } from '../../branches/client.js';
+import { connectToBranch } from '../../branches/connection.js';
+import { DRIVERS, validDriver } from '../../branches/drivers.js';
+import { writeBranchEnv } from '../../branches/env.js';
+import { recoverBranchCredentials } from '../../branches/recovery.js';
 import { requireConnector } from '../../connectors/context.js';
 import { terminalText } from '../../terminal.js';
 export default class BranchCreate extends ArdentCommand {
     static args = { name: Args.string({ description: 'Branch name', required: true }) };
     static strict = false;
-    static description = 'Create a branch in the selected connector';
+    static description = 'Create a branch in the selected connector and print its connection URL when ready';
+    static flags = {
+        driver: Flags.string({ default: 'libpq', options: [...DRIVERS], description: 'Connection string format: libpq, node, jdbc or prisma' }),
+        print: Flags.boolean({ description: 'Print the connection string when ready (the default behavior)' }),
+        'to-env': Flags.boolean({ description: 'Write DATABASE_URL to .env instead of printing it', exclusive: ['print', 'json'] }),
+    };
     static helpGroup = 'Branches';
     async run() {
-        const { argv } = await this.parse(BranchCreate);
+        const { argv, flags } = await this.parse(BranchCreate);
         const name = branchName(argv);
+        if (!validDriver(flags.driver))
+            this.error(`--driver must be one of ${DRIVERS.join(', ')}.`);
         const session = await requireConnector(this.config.configDir, !this.jsonEnabled());
+        const say = (message) => { if (!this.jsonEnabled())
+            this.logToStderr(message); };
+        const recovered = await recoverBranchCredentials(this.config.configDir, session.token);
+        if (recovered)
+            say(`Revoked ${recovered} credential issuance(s) left by an earlier command.`);
         const interactive = !this.jsonEnabled() && ux.action.type === 'spinner';
-        const target = `${terminalText(name)} in connector ${terminalText(session.selectedConnector.name)}`;
+        const target = `${terminalText(name)} in connector ${terminalText(session.selectedConnector.name)} via ${terminalText(new URL(API_URL).origin)}`;
         if (interactive)
             ux.action.start(`Creating branch ${target}`);
-        else if (!this.jsonEnabled())
-            this.log(`Creating branch ${target}...`);
+        else
+            say(`Creating branch ${target}...`);
+        let accepted;
         try {
             const result = await createBranch(session.token, session.selectedConnector.id, name);
-            await replaceBranchCache(this.config.configDir, session, [...(session.branches ?? []).filter(({ id, name }) => id !== result.branch.id && name !== result.branch.name), result.branch]);
-            if (interactive) {
-                await waitForBranchOperation(session.token, result.operation.workflow_id, (status) => { ux.action.status = status; });
-                ux.action.stop(ux.colorize('green', '✓ created'));
-            }
+            accepted = result;
+            const credential = await connectToBranch({
+                configDir: this.config.configDir, token: session.token, branchID: result.branch.id,
+                print: true, driver: flags.driver, json: true, say, log: (message) => this.log(message), warn: (message) => this.warn(message),
+                deliver: flags['to-env'] ? writeBranchEnv : undefined,
+                serving: async () => {
+                    await waitForBranchOperation(session.token, result.operation.workflow_id, (status) => { if (interactive)
+                        ux.action.status = status; }, 'retry');
+                    const branches = await listBranches(session.token, session.selectedConnector.id);
+                    const branch = branches.find(({ id, name }) => id === result.branch.id && name === result.branch.name);
+                    if (branch?.state !== 'ACTIVE')
+                        throw new Error('The created branch is not active. Run ardent-beta branch list to check its state.');
+                    result.branch = branch;
+                    // A long-running create must not undo a switch or logout in another
+                    // terminal. Read and conditionally write under the session writer lock.
+                    const selected = await updateSession(this.config.configDir, (current) => {
+                        if (!current || current.token !== session.token ||
+                            current.organization?.id !== session.organization?.id ||
+                            current.selectedProject?.id !== session.selectedProject?.id ||
+                            current.selectedConnector?.id !== session.selectedConnector.id ||
+                            current.selectedBranch?.id !== session.selectedBranch?.id)
+                            return;
+                        const identities = branches.map(({ id, name, connector_id }) => ({ id, name, connector_id }));
+                        return { ...current, branches: identities, selectedBranch: { id: branch.id, name: branch.name, connector_id: branch.connector_id } };
+                    });
+                    if (!selected)
+                        say('Local context changed while creating the branch; its selection was left unchanged.');
+                    if (interactive)
+                        ux.action.status = 'preparing connection URL';
+                },
+            });
+            if (!credential)
+                throw new Error('No connection URL was returned.');
+            if (interactive)
+                ux.action.stop(ux.colorize('green', '✓ ready'));
+            else
+                say(`Branch ${terminalText(name)} is ready.`);
+            if (flags['to-env'])
+                say('Wrote DATABASE_URL to .env.');
             else if (!this.jsonEnabled())
-                this.log(`Branch creation started (${terminalText(result.branch.id)}).`);
-            return result;
+                this.log(credential.connection_string);
+            return { ...result, credential };
         }
         catch (error) {
             if (interactive)
                 ux.action.stop('failed');
+            if (accepted) {
+                const message = `Branch creation was accepted (branch ${terminalText(accepted.branch.id)}, workflow ${terminalText(accepted.operation.workflow_id)}). ${error instanceof Error ? error.message : 'Connection setup failed.'} Run ardent-beta branch list to check its state before retrying creation.`;
+                if (error instanceof APIError)
+                    throw new APIError(message, error.status, error.code);
+                throw new Error(this.jsonEnabled() ? message : terminalText(message));
+            }
             throw error;
         }
     }

package/dist/commands/branch/recover.d.ts

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

package/dist/commands/branch/recover.js

@@ -0,0 +1,37 @@
+import { Args, ux } from '@oclif/core';
+import { ArdentCommand } from '../../command.js';
+import { branchName, transitionBranch, waitForBranchOperation } from '../../branches/client.js';
+import { requireConnector } from '../../connectors/context.js';
+import { terminalText } from '../../terminal.js';
+export default class BranchRecover extends ArdentCommand {
+    static args = { name: Args.string({ description: 'Branch name', required: true }) };
+    static strict = false;
+    static description = 'Recover a failed branch in the selected connector on its retained disk';
+    static helpGroup = 'Branches';
+    async run() {
+        const { argv } = await this.parse(BranchRecover);
+        const name = branchName(argv);
+        const session = await requireConnector(this.config.configDir, !this.jsonEnabled());
+        const interactive = !this.jsonEnabled() && ux.action.type === 'spinner';
+        const target = `${terminalText(name)} in connector ${terminalText(session.selectedConnector.name)}`;
+        if (interactive)
+            ux.action.start(`Recovering branch ${target}`);
+        else if (!this.jsonEnabled())
+            this.log(`Recovering branch ${target}...`);
+        try {
+            const result = await transitionBranch(session.token, session.selectedConnector.id, name, 'recover');
+            if (interactive) {
+                await waitForBranchOperation(session.token, result.operation.workflow_id, (status) => { ux.action.status = status; });
+                ux.action.stop(ux.colorize('green', '✓ active'));
+            }
+            else if (!this.jsonEnabled())
+                this.log(`Branch recovery started (${terminalText(result.branch.id)}).`);
+            return result;
+        }
+        catch (error) {
+            if (interactive)
+                ux.action.stop('failed');
+            throw error;
+        }
+    }
+}

package/dist/commands/branch/suspend.d.ts

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

package/dist/commands/branch/suspend.js

@@ -0,0 +1,37 @@
+import { Args, ux } from '@oclif/core';
+import { ArdentCommand } from '../../command.js';
+import { branchName, transitionBranch, waitForBranchOperation } from '../../branches/client.js';
+import { requireConnector } from '../../connectors/context.js';
+import { terminalText } from '../../terminal.js';
+export default class BranchSuspend extends ArdentCommand {
+    static args = { name: Args.string({ description: 'Branch name', required: true }) };
+    static strict = false;
+    static description = 'Park a branch in the selected connector; it refuses connections until woken';
+    static helpGroup = 'Branches';
+    async run() {
+        const { argv } = await this.parse(BranchSuspend);
+        const name = branchName(argv);
+        const session = await requireConnector(this.config.configDir, !this.jsonEnabled());
+        const interactive = !this.jsonEnabled() && ux.action.type === 'spinner';
+        const target = `${terminalText(name)} in connector ${terminalText(session.selectedConnector.name)}`;
+        if (interactive)
+            ux.action.start(`Suspending branch ${target}`);
+        else if (!this.jsonEnabled())
+            this.log(`Suspending branch ${target}...`);
+        try {
+            const result = await transitionBranch(session.token, session.selectedConnector.id, name, 'suspend');
+            if (interactive) {
+                await waitForBranchOperation(session.token, result.operation.workflow_id, (status) => { ux.action.status = status; });
+                ux.action.stop(ux.colorize('green', '✓ parked'));
+            }
+            else if (!this.jsonEnabled())
+                this.log(`Branch suspension started (${terminalText(result.branch.id)}).`);
+            return result;
+        }
+        catch (error) {
+            if (interactive)
+                ux.action.stop('failed');
+            throw error;
+        }
+    }
+}

package/dist/commands/branch/switch.js

@@ -18,7 +18,7 @@ export default class BranchSwitch extends ArdentCommand {
         const updated = await replaceBranchCache(this.config.configDir, session, branches);
         const branch = branches.find((candidate) => candidate.name === name);
         if (!branch)
-            this.error(`Branch ${JSON.stringify(name)} not found in connector ${JSON.stringify(session.selectedConnector.name)}.`);
+            this.error(`Branch ${JSON.stringify(name)} not found in connector ${terminalText(JSON.stringify(session.selectedConnector.name))}.`);
         await saveSession(this.config.configDir, { ...updated, selectedBranch: { id: branch.id, name: branch.name, connector_id: branch.connector_id } });
         if (!this.jsonEnabled())
             this.log(`✓ Switched to branch ${terminalText(name)} in connector ${terminalText(session.selectedConnector.name)}`);

package/dist/commands/branch/wake.d.ts

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

package/dist/commands/branch/wake.js

@@ -0,0 +1,37 @@
+import { Args, ux } from '@oclif/core';
+import { ArdentCommand } from '../../command.js';
+import { branchName, transitionBranch, waitForBranchOperation } from '../../branches/client.js';
+import { requireConnector } from '../../connectors/context.js';
+import { terminalText } from '../../terminal.js';
+export default class BranchWake extends ArdentCommand {
+    static args = { name: Args.string({ description: 'Branch name', required: true }) };
+    static strict = false;
+    static description = 'Wake a parked branch in the selected connector; a parked branch refuses connections until woken';
+    static helpGroup = 'Branches';
+    async run() {
+        const { argv } = await this.parse(BranchWake);
+        const name = branchName(argv);
+        const session = await requireConnector(this.config.configDir, !this.jsonEnabled());
+        const interactive = !this.jsonEnabled() && ux.action.type === 'spinner';
+        const target = `${terminalText(name)} in connector ${terminalText(session.selectedConnector.name)}`;
+        if (interactive)
+            ux.action.start(`Waking branch ${target}`);
+        else if (!this.jsonEnabled())
+            this.log(`Waking branch ${target}...`);
+        try {
+            const result = await transitionBranch(session.token, session.selectedConnector.id, name, 'wake');
+            if (interactive) {
+                await waitForBranchOperation(session.token, result.operation.workflow_id, (status) => { ux.action.status = status; });
+                ux.action.stop(ux.colorize('green', '✓ active'));
+            }
+            else if (!this.jsonEnabled())
+                this.log(`Branch wake started (${terminalText(result.branch.id)}).`);
+            return result;
+        }
+        catch (error) {
+            if (interactive)
+                ux.action.stop('failed');
+            throw error;
+        }
+    }
+}

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

@@ -13,6 +13,8 @@ export default class ConnectorCreate extends ArdentCommand {
     static flags: {
         environment: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         name: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'tls-client-cert': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'tls-client-key': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
     };
     run(): Promise<ConnectorCreation>;
 }