@myapihq/cli 2.31.0 → 2.31.2

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

@@ -1,6 +1,7 @@
 export type FlagType = 'string' | 'boolean' | 'number' | 'list';
 export type FlagSchema = Record<string, FlagType>;
 export declare const GLOBAL_FLAGS: FlagSchema;
+export declare const DISPATCH_FLAGS: ReadonlySet<string>;
 export interface ParsedArgs {
     args: string[];
     flags: Record<string, string | boolean | number>;

package/dist/flags.js

@@ -5,13 +5,37 @@
 // utils.ts — adding a new value flag without registering it would silently
 // turn it into a boolean (e.g. `--html '<p>'` becoming `flags.html === true`).
 // Flags every command understands.
+//
+// `org` belongs here rather than in each command's own schema. Ten commands
+// declared it individually and the other nineteen did not, so the same flag
+// refused a duplicate on `myapi pixel` and silently kept the last value on
+// `myapi funnel push` — see the duplicate check in parseFlags for why last-wins
+// is the one outcome you cannot recover from. For the tenant selector it picks
+// the organisation your write lands in, which makes it the worst flag in the
+// CLI to resolve silently.
 export const GLOBAL_FLAGS = {
     help: 'boolean',
     json: 'boolean',
     verbose: 'boolean',
     yes: 'boolean',
     y: 'boolean',
+    version: 'boolean',
+    org: 'string',
 };
+// Short aliases are consumed as `-h` / `-v` / `-V` before the `--flag` branch,
+// so they never appear as keys in `merged` and need no type — but they do land
+// in `flags` (as help/version), so the dispatcher must still tolerate them.
+const SHORT_ALIASES = ['h', 'v', 'V'];
+// What the dispatcher tolerates on any command, derived from the list above so
+// the two cannot disagree. They previously drifted: `--org` was missing here
+// while being honoured, so the CLI announced "unknown flag --org (took value
+// …)" and then switched organisation anyway. A user who believed the warning
+// and dropped the flag would have written to whatever org the config pointed
+// at (ImmoPilot, 2026-08-22).
+export const DISPATCH_FLAGS = new Set([
+    ...Object.keys(GLOBAL_FLAGS),
+    ...SHORT_ALIASES,
+]);
 // `quiet` suppresses the unknown-flag note. The dispatcher parses twice — once
 // to learn the command, once under that command's own schema — and only the
 // second pass knows which flags are genuinely foreign, so the first must stay

package/dist/flags.test.js

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { parseFlags } from './flags.js';
+import { parseFlags, GLOBAL_FLAGS, DISPATCH_FLAGS } from './flags.js';
 const SCHEMA = {
     org: 'string',
     name: 'string',
@@ -190,3 +190,29 @@ describe('parseFlags — repeated flags are never silently collapsed', () => {
         expect(flags.name).toBe('prod');
     });
 });
+// ImmoPilot, 2026-08-22: `--org` was honoured while being announced as an
+// unknown flag, because the dispatcher's tolerated-flag list and the parser's
+// typed-flag list were maintained separately and disagreed. DISPATCH_FLAGS is
+// now derived from GLOBAL_FLAGS, so this asserts the derivation holds rather
+// than re-checking a hand-written list.
+describe('global flag lists cannot drift', () => {
+    it('every globally-typed flag is tolerated by the dispatcher', () => {
+        for (const key of Object.keys(GLOBAL_FLAGS)) {
+            expect(DISPATCH_FLAGS.has(key)).toBe(true);
+        }
+    });
+    it('org is typed globally, so every command refuses a duplicate', () => {
+        // Ten commands declared `org` in their own schema and got this guard; the
+        // other nineteen silently kept the last value. Parse with an empty schema
+        // to stand in for a command that declares nothing of its own.
+        expect(() => parseFlags(['--org', 'ORG_A', '--org', 'ORG_B'], {}, true)).toThrow(/--org was given more than once/);
+    });
+    it('a single --org still parses to its value under an empty schema', () => {
+        const { flags } = parseFlags(['--org', 'ORG_A'], {}, true);
+        expect(flags.org).toBe('ORG_A');
+    });
+    it('--org is not reported as a foreign flag', () => {
+        const { unknownFlags } = parseFlags(['--org', 'ORG_A'], {}, true);
+        expect(unknownFlags ?? []).not.toContain('--org');
+    });
+});

package/dist/index.js

@@ -5,7 +5,7 @@ import { MyApiError, setUserAgent, hq } from '@myapihq/sdk';
 import { friendlyError } from './errors.js';
 import { currentOrg, adoptSoleOrg } from './helpers.js';
 import * as fs from 'fs';
-import { parseFlags } from './flags.js';
+import { parseFlags, DISPATCH_FLAGS } from './flags.js';
 const pkgPath = new URL('../package.json', import.meta.url);
 const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
 // Identify the CLI (and its version) on every outbound request. Without this
@@ -100,8 +100,7 @@ const COMMAND_SCHEMAS = {
     webhook: webhookCmd.SCHEMA,
     workflow: workflowCmd.SCHEMA,
 };
-// Flags the dispatcher itself consumes, valid on any command.
-const DISPATCH_FLAGS = new Set(['help', 'h', 'json', 'verbose', 'yes', 'y', 'version', 'v', 'V', 'org']);
+// Flags the dispatcher itself consumes are derived from GLOBAL_FLAGS in flags.ts.
 function warnForeignFlags(command, flags) {
     if (!command || process.env.MYAPI_QUIET_UNKNOWN_FLAGS)
         return;

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.31.0",
+  "version": "2.31.2",
   "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.31.0"
+    "@myapihq/sdk": "^2.31.2"
   },
   "devDependencies": {
     "@types/node": "^25.6.0",