@myapihq/cli 2.30.1 → 2.31.1

package/dist/commands/container-deploy-failure.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/commands/container-deploy-failure.test.js

@@ -0,0 +1,49 @@
+// A failed deploy has to say which half failed.
+//
+// One fixed sentence covered every failure: "Build/deploy failed — check
+// `myapi container logs <id>`". ImmoPilot read thirty lines of healthy nginx
+// after a ROLLOUT failure — the image had built, served two 200s to our own
+// startup probes, then taken a SIGTERM — and a second deploy of the same code
+// succeeded unchanged. The sentence sent them looking for a defect in code that
+// was fine.
+//
+// I hit the same message the day before, on a container the probe had already
+// deleted, so the logs it named did not exist either.
+//
+// The platform now returns error, error_stage and error_retryable, so the CLI
+// can stop guessing.
+import { describe, it, expect } from 'vitest';
+import { describeDeployFailure } from './container.js';
+const ID = 'c1';
+const base = { id: ID };
+describe('describeDeployFailure', () => {
+    it('leads with what the platform said, not our paraphrase', () => {
+        const out = describeDeployFailure({ ...base, error: 'Deployment failed after the image built.', error_stage: 'deploy' }, ID);
+        expect(out.split('\n')[0]).toBe('Deployment failed after the image built.');
+    });
+    it('on a rollout failure, says their application logs are the wrong place', () => {
+        // The whole point. "Check the logs" is what cost a customer a deploy.
+        const out = describeDeployFailure({ ...base, error_stage: 'deploy' }, ID);
+        expect(out).toMatch(/not the place to look/i);
+        expect(out).not.toContain(`myapi container logs ${ID}`);
+    });
+    it('on a build failure, sends them to the build logs', () => {
+        const out = describeDeployFailure({ ...base, error_stage: 'build' }, ID);
+        expect(out).toContain(`myapi container build-logs ${ID}`);
+    });
+    it('says so when the failure is ours and retrying is reasonable', () => {
+        const out = describeDeployFailure({ ...base, error_stage: 'deploy', error_retryable: true }, ID);
+        expect(out).toMatch(/retrying is reasonable/i);
+    });
+    it('does not invite a retry when the failure is theirs', () => {
+        // Telling someone to retry a broken build wastes four minutes per attempt.
+        const out = describeDeployFailure({ ...base, error_stage: 'build', error_retryable: false }, ID);
+        expect(out).not.toMatch(/retrying is reasonable/i);
+    });
+    it('offers both logs when the platform did not say which stage', () => {
+        // Older backends, and any future status that predates the field.
+        const out = describeDeployFailure(base, ID);
+        expect(out).toContain(`build-logs ${ID}`);
+        expect(out).toContain(`logs ${ID}`);
+    });
+});

package/dist/commands/container.d.ts

@@ -13,6 +13,7 @@ export declare function create(nameArg: string | undefined, flags: Flags): Promi
 export declare function list(flags: Flags): Promise<void>;
 export declare function get(id: string, flags: Flags): Promise<void>;
 export declare function healthCheck(id: string, flags: Flags): Promise<void>;
+export declare function describeDeployFailure(c: sdkContainer.Container, id: string): string;
 export declare function del(id: string, flags: Flags): Promise<void>;
 export declare function _checkProbePath(hc: string): string;
 export declare function _isTarball(p: string): boolean;

package/dist/commands/container.js

@@ -277,6 +277,39 @@ export async function healthCheck(id, flags) {
         ? `  The runtime now waits for ${value} to answer before sending traffic to a new revision.`
         : '  No startup probe: a new revision takes traffic as soon as the runtime reports it started.');
 }
+// What to say when a deploy fails, and where to send them.
+//
+// One fixed sentence used to cover every failure: "Build/deploy failed — check
+// `myapi container logs <id>`". A customer read thirty lines of healthy nginx
+// after a ROLLOUT failure — the image had built, served two 200s to our own
+// startup probes, then taken a SIGTERM — and a second deploy of the same code
+// succeeded unchanged. The message sent them to look for a defect in code that
+// was fine.
+//
+// The platform now says which stage failed and whether it is worth retrying,
+// so the CLI can stop guessing. `build` is their image; `deploy` is our rollout
+// of an image that built, which is the case where their application logs are
+// the wrong place to look.
+export function describeDeployFailure(c, id) {
+    const lines = [c.error?.trim() || 'The deploy failed.'];
+    if (c.error_stage === 'build') {
+        lines.push(`  Your image did not build: myapi container build-logs ${id}`);
+    }
+    else if (c.error_stage === 'deploy') {
+        // Said explicitly, because "check the logs" is what cost the customer a
+        // deploy: the image built and ran, so the application logs look healthy.
+        lines.push('  The image built — this failed while we rolled it out, so your');
+        lines.push('  application logs will look healthy and are not the place to look.');
+    }
+    else {
+        lines.push(`  Build logs: myapi container build-logs ${id}`);
+        lines.push(`  Runtime logs: myapi container logs ${id}`);
+    }
+    if (c.error_retryable) {
+        lines.push('  This one is ours and retrying is reasonable: myapi container deploy ' + id + ' --source <dir>');
+    }
+    return lines.join('\n');
+}
 export async function del(id, flags) {
     const config = requireConfig();
     const orgId = requireOrg(flags, config, 'myapi container delete <id> [--yes] [--org <id>]');
@@ -421,7 +454,7 @@ export async function deploy(id, image, flags) {
                 check: () => sdkContainer.getContainer(config.api_key, orgId, id),
                 isDone: (c) => c.status === 'active',
                 isFailed: (c) => c.status === 'build_error' || c.status === 'deploy_error',
-                failedMessage: 'Build/deploy failed — check `myapi container logs ' + id + '`.',
+                failedMessage: (c) => describeDeployFailure(c, id),
                 timeoutMs: 600_000,
                 intervalMs: 5_000,
             });

package/dist/dispatch-in-process.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/dispatch-in-process.test.js

@@ -0,0 +1,83 @@
+// A command can be dispatched and its output read, without a subprocess.
+//
+// Everything in output.ts wrote to console and error() called process.exit(1),
+// so the only way to run a command and see what it produced was to spawn the
+// binary. That cost ~1-2s of node startup per call, and it is why the probe
+// shells out.
+//
+// It also decided the shape of anything embedding this CLI. An MCP server that
+// wanted to expose `myapi …` had two options: spawn a process per tool call, or
+// reimplement the dispatcher. The first is slow and hands a command string to a
+// shell; the second is a third client that drifts from the other two.
+//
+// Output is now a sink. The default is byte-for-byte the old behaviour — the
+// binary does not know this changed — and `withSink` lets an in-process caller
+// collect instead, with a failure thrown rather than the host killed.
+import { describe, it, expect, vi } from 'vitest';
+import { withSink, CommandFailed, success, error, info, banner, printJson } from './output.js';
+function collector() {
+    const out = [];
+    const err = [];
+    const sink = {
+        out: (l) => { out.push(l); },
+        err: (l) => { err.push(l); },
+        fail: (m) => { throw new CommandFailed(m); },
+    };
+    return { sink, out, err };
+}
+describe('output can be collected instead of printed', () => {
+    it('captures stdout writers', async () => {
+        const c = collector();
+        await withSink(c.sink, () => { success('done'); info('detail'); });
+        expect(c.out.join('\n')).toContain('done');
+        expect(c.out.join('\n')).toContain('detail');
+    });
+    it('keeps stderr separate, so --json output stays parseable', async () => {
+        // The org banner goes to stderr precisely so `--json | jq` works. An
+        // embedder needs that split preserved, not flattened.
+        const c = collector();
+        await withSink(c.sink, () => { printJson({ a: 1 }); banner('myapi: org=x'); });
+        expect(JSON.parse(c.out.join('\n'))).toEqual({ a: 1 });
+        expect(c.err.join('\n')).toContain('org=x');
+    });
+    it('turns a fatal into a throw instead of killing the host', async () => {
+        // error() is typed `never` and used to reach process.exit. In an embedder
+        // that would take the server down on a bad argument.
+        const c = collector();
+        await expect(withSink(c.sink, () => { error('bad argument'); }))
+            .rejects.toBeInstanceOf(CommandFailed);
+        expect(c.err.join('\n')).toContain('bad argument');
+    });
+    it('restores the previous sink even when the command throws', async () => {
+        // Otherwise one failed embedded call leaves the binary mute for the rest of
+        // its life — every later write lands in a collector nobody is reading.
+        //
+        // The assertion has to be about output written OUTSIDE any withSink. A
+        // first version compared two nested collectors, which passes whether or not
+        // the sink is restored, and a mutation that deleted the restore did not
+        // fail it.
+        const c = collector();
+        await withSink(c.sink, () => { error('boom'); }).catch(() => { });
+        const spy = vi.spyOn(console, 'log').mockImplementation(() => { });
+        info('outside any sink');
+        expect(spy, 'after a failed embedded call, output must go back to the process')
+            .toHaveBeenCalledWith('outside any sink');
+        expect(c.out, 'the abandoned collector must receive nothing more').toEqual([]);
+        spy.mockRestore();
+    });
+    it('dispatches a real command handler in-process', async () => {
+        // The point of all of it: run a handler, read what it produced, no process.
+        vi.doMock('@myapihq/sdk', () => ({
+            hq: { listOrgs: vi.fn(async () => [{ id: 'o1', name: 'Acme', created_at: '2026-01-01' }]) },
+        }));
+        vi.doMock('./config.js', () => ({
+            requireConfig: () => ({ api_key: 'k', account_id: 'a' }),
+            loadConfig: () => ({ api_key: 'k', account_id: 'a' }),
+            CONFIG_DIR: '/tmp/nowhere',
+        }));
+        const org = await import('./commands/org.js');
+        const c = collector();
+        await withSink(c.sink, () => org.list({ json: true }));
+        expect(c.out.join('\n')).toContain('Acme');
+    });
+});

package/dist/output.d.ts

@@ -1,3 +1,18 @@
+export declare class CommandFailed extends Error {
+    constructor(message: string);
+}
+export interface Sink {
+    out(line: string): void;
+    err(line: string): void;
+    /** Called by error(). The process sink exits; an embedded sink throws. */
+    fail(message: string): never;
+}
+/**
+ * Runs `fn` with output collected instead of printed, and a failure thrown
+ * instead of exiting. Restores the previous sink even if `fn` throws, so a
+ * caller cannot leave the binary mute.
+ */
+export declare function withSink<T>(custom: Sink, fn: () => Promise<T> | T): Promise<T>;
 export type TableFlags = {
     json?: boolean | string | number;
 } & Record<string, unknown>;

package/dist/output.js

@@ -1,16 +1,55 @@
+// Where output goes, and what "fail" does.
+//
+// Every writer here went straight to console and `error()` called
+// process.exit(1). That is right for a CLI process and it is the single thing
+// welding the command layer to one: a caller that wants to DISPATCH a command
+// and read the result — an MCP server, a test that drives a handler rather than
+// its parser — has to spawn a subprocess to do it.
+//
+// So the destination is a sink, swapped by the embedder. The default is exactly
+// the old behaviour, so nothing changes for the binary; `withSink` gives an
+// in-process caller somewhere to collect, and turns a fatal into a thrown
+// CommandFailed instead of killing the host.
+export class CommandFailed extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'CommandFailed';
+    }
+}
+const processSink = {
+    out: (l) => console.log(l),
+    err: (l) => process.stderr.write(l + '\n'),
+    fail: (m) => { process.exit(1); },
+};
+let sink = processSink;
+/**
+ * Runs `fn` with output collected instead of printed, and a failure thrown
+ * instead of exiting. Restores the previous sink even if `fn` throws, so a
+ * caller cannot leave the binary mute.
+ */
+export async function withSink(custom, fn) {
+    const previous = sink;
+    sink = custom;
+    try {
+        return await fn();
+    }
+    finally {
+        sink = previous;
+    }
+}
 const useColor = process.stdout.isTTY && !process.env.NO_COLOR;
 export function success(message) {
-    console.log(useColor ? `\x1b[32m✓\x1b[0m ${message}` : `✓ ${message}`);
+    sink.out(useColor ? `\x1b[32m✓\x1b[0m ${message}` : `✓ ${message}`);
 }
 export function error(message) {
-    console.error(useColor ? `\x1b[31m✗\x1b[0m ${message}` : `✗ ${message}`);
-    process.exit(1);
+    sink.err(useColor ? `\x1b[31m✗\x1b[0m ${message}` : `✗ ${message}`);
+    return sink.fail(message);
 }
 export function info(message) {
-    console.log(message);
+    sink.out(message);
 }
 export function banner(message) {
-    process.stderr.write(message + '\n');
+    sink.err(message);
 }
 let resolvedContext;
 export function setResolvedContextSource(fn) {
@@ -20,7 +59,7 @@ export function printJson(data) {
     const ctx = resolvedContext?.();
     const stampable = ctx && data !== null && typeof data === 'object' && !Array.isArray(data);
     const payload = stampable ? { ...data, _resolved: ctx } : data;
-    console.log(JSON.stringify(payload, null, 2));
+    sink.out(JSON.stringify(payload, null, 2));
 }
 // Spinner / line-clear primitives. Used by polling helpers (utils.pollJob)
 // and any handler that wants its own progress UI.
@@ -55,16 +94,16 @@ export function printTable(rows, opts = {}) {
         return;
     }
     if (rows.length === 0) {
-        console.log(opts.empty ?? 'No data found.');
+        sink.out(opts.empty ?? 'No data found.');
         return;
     }
     const columns = Object.keys(rows[0]);
     const colWidths = columns.map(col => Math.max(col.length, ...rows.map(row => String(row[col] ?? '').length)));
     const printRow = (row) => {
-        console.log(row.map((cell, i) => cell.padEnd(colWidths[i] + 2)).join(''));
+        sink.out(row.map((cell, i) => cell.padEnd(colWidths[i] + 2)).join(''));
     };
     printRow(columns);
-    console.log(colWidths.map(w => '-'.repeat(w + 2)).join(''));
+    sink.out(colWidths.map(w => '-'.repeat(w + 2)).join(''));
     for (const row of rows) {
         printRow(columns.map(col => String(row[col] ?? '')));
     }

package/dist/utils.d.ts

@@ -20,8 +20,15 @@ export interface PollOptions<T> {
     intervalMs?: number;
     /** Message shown via error() on timeout. Defaults to a generic phrase. */
     timeoutMessage?: string;
-    /** Message shown via error() when isFailed returns true. */
-    failedMessage?: string;
+    /**
+     * Message shown via error() when isFailed returns true.
+     *
+     * A function when the useful message depends on WHY it failed. `container
+     * deploy` printed one fixed sentence for every failure, so a rollout problem
+     * and a broken build read identically — a customer spent a deploy reading
+     * healthy nginx logs because the sentence sent them there.
+     */
+    failedMessage?: string | ((state: T) => string);
 }
 /**
  * Generic spinner+poll helper. Used wherever the CLI kicks off a long-running

package/dist/utils.js

@@ -46,7 +46,10 @@ export async function pollJob(opts) {
         }
         if (opts.isFailed && opts.isFailed(state)) {
             clearLine();
-            error(opts.failedMessage ?? `${opts.label} failed`);
+            const msg = typeof opts.failedMessage === 'function'
+                ? opts.failedMessage(state)
+                : opts.failedMessage;
+            error(msg ?? `${opts.label} failed`);
         }
         spinnerWrite(`\r${opts.label} ${spinnerFrame(i++)}`);
         await sleep(intervalMs);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@myapihq/cli",
   "license": "Apache-2.0",
-  "version": "2.30.1",
+  "version": "2.31.1",
   "description": "MyAPI command-line interface",
   "repository": {
     "type": "git",
@@ -47,7 +47,7 @@
     "lint:skills:strict": "node scripts/copy-skills.js && node scripts/lint-skills.js --strict"
   },
   "dependencies": {
-    "@myapihq/sdk": "^2.30.1"
+    "@myapihq/sdk": "^2.31.1"
   },
   "devDependencies": {
     "@types/node": "^25.6.0",