@myapihq/cli 2.15.2 → 2.16.0

package/dist/adopt-sole-org.test.js

@@ -0,0 +1,105 @@
+// adoptSoleOrg: choose the org for someone only when they had no choice.
+//
+// An org-locked key can reach exactly one org and the raw key encodes nothing,
+// so a developer handed one cannot learn which org it is for. Backend #124
+// narrows `GET /hq/orgs` to that single org, which is what makes adopting it
+// safe rather than presumptuous.
+//
+// Every guard here is a way this could go wrong quietly:
+//   - adopting when 2+ orgs exist picks a tenant on the user's behalf;
+//   - adopting on a refusal or a network blip invents an org from an error;
+//   - probing when --org was passed spends a round-trip to ignore the answer;
+//   - and the whole thing must degrade to today's behaviour on any failure,
+//     because it is a convenience and must never be the reason a command dies.
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+const KEY = 'hq_live_org_locked';
+let tmpHome;
+let realHome;
+function writeConfig(accounts) {
+    fs.writeFileSync(path.join(tmpHome, '.myapi', 'config.json'), JSON.stringify({ active: 0, accounts }));
+}
+function readAccounts() {
+    return JSON.parse(fs.readFileSync(path.join(tmpHome, '.myapi', 'config.json'), 'utf-8')).accounts;
+}
+async function freshHelpers() {
+    vi.resetModules();
+    return import('./helpers.js');
+}
+beforeEach(() => {
+    tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'myapi-adopt-'));
+    fs.mkdirSync(path.join(tmpHome, '.myapi'), { recursive: true });
+    realHome = process.env.HOME;
+    process.env.HOME = tmpHome;
+    process.env.MYAPI_API_KEY = KEY;
+});
+afterEach(() => {
+    if (realHome !== undefined)
+        process.env.HOME = realHome;
+    delete process.env.MYAPI_API_KEY;
+    fs.rmSync(tmpHome, { recursive: true, force: true });
+});
+describe('adoptSoleOrg', () => {
+    it('adopts and persists when the key reaches exactly one org', async () => {
+        writeConfig([{ api_key: KEY, account_id: '' }]);
+        const { adoptSoleOrg } = await freshHelpers();
+        await adoptSoleOrg('database', {}, async () => [{ id: 'org-only', name: 'ImmoPilot' }]);
+        const entry = readAccounts().find(a => a.api_key === KEY);
+        expect(entry.default_org).toBe('org-only');
+        expect(entry.org_names['org-only']).toBe('ImmoPilot');
+    });
+    it('does NOT adopt when the key reaches more than one', async () => {
+        // Two orgs is an account-wide key with a real choice to make. Picking one
+        // is exactly the silent wrong-tenant selection the rest of this file fights.
+        writeConfig([{ api_key: KEY, account_id: '' }]);
+        const { adoptSoleOrg } = await freshHelpers();
+        await adoptSoleOrg('database', {}, async () => [{ id: 'a', name: 'A' }, { id: 'b', name: 'B' }]);
+        expect(readAccounts()[0].default_org).toBeUndefined();
+    });
+    it('does NOT adopt when the call is refused', async () => {
+        // What a pre-#124 backend answers, and what a network failure looks like.
+        writeConfig([{ api_key: KEY, account_id: '' }]);
+        const { adoptSoleOrg } = await freshHelpers();
+        await adoptSoleOrg('database', {}, async () => { throw new Error('SCOPE_FORBIDDEN'); });
+        expect(readAccounts()[0].default_org).toBeUndefined();
+    });
+    it('does not probe at all when --org was given', async () => {
+        writeConfig([{ api_key: KEY, account_id: '' }]);
+        const { adoptSoleOrg } = await freshHelpers();
+        const listOrgs = vi.fn(async () => [{ id: 'org-only' }]);
+        await adoptSoleOrg('database', { org: 'org-explicit' }, listOrgs);
+        expect(listOrgs).not.toHaveBeenCalled();
+    });
+    it('does not probe when a default org is already configured', async () => {
+        writeConfig([{ api_key: KEY, account_id: '', default_org: 'org-known' }]);
+        const { adoptSoleOrg } = await freshHelpers();
+        const listOrgs = vi.fn(async () => [{ id: 'org-only' }]);
+        await adoptSoleOrg('database', {}, listOrgs);
+        expect(listOrgs).not.toHaveBeenCalled();
+    });
+    it('does not probe for commands that never need an org', async () => {
+        writeConfig([{ api_key: KEY, account_id: '' }]);
+        const { adoptSoleOrg } = await freshHelpers();
+        const listOrgs = vi.fn(async () => [{ id: 'org-only' }]);
+        for (const cmd of ['account', 'login', 'billing', 'status', 'org']) {
+            await adoptSoleOrg(cmd, {}, listOrgs);
+        }
+        expect(listOrgs).not.toHaveBeenCalled();
+    });
+    it('writes to its own key, never another account entry', async () => {
+        // The cross-tenant guard. saveConfig upserting by api_key is what makes
+        // this hold; writing by active index would put this org on the signed-in
+        // account instead.
+        writeConfig([
+            { api_key: 'hq_live_signed_in', account_id: 'acct-real', default_org: 'org-real' },
+            { api_key: KEY, account_id: '' },
+        ]);
+        const { adoptSoleOrg } = await freshHelpers();
+        await adoptSoleOrg('database', {}, async () => [{ id: 'org-only', name: 'ImmoPilot' }]);
+        const accounts = readAccounts();
+        expect(accounts.find(a => a.api_key === 'hq_live_signed_in').default_org).toBe('org-real');
+        expect(accounts.find(a => a.api_key === KEY).default_org).toBe('org-only');
+    });
+});

package/dist/commands/container.js

@@ -1,10 +1,10 @@
 import { spawnSync } from 'node:child_process';
 import { readFile, stat } from 'node:fs/promises';
-import { container as sdkContainer } from '@myapihq/sdk';
+import { container as sdkContainer, hq } from '@myapihq/sdk';
 import { requireConfig } from '../config.js';
 import { success, error, printTable, info, printJson, banner } from '../output.js';
 import { formatDate, pollJob } from '../utils.js';
-import { requireOrg, confirmDestructive } from '../helpers.js';
+import { requireOrg, requireExplicitOrg, confirmDestructive } from '../helpers.js';
 export const EXPOSES = [
     'GET /container/orgs/{org_id}/containers/{id}/build-logs',
     'POST /container/orgs/{org_id}/containers',
@@ -528,7 +528,9 @@ export async function logs(id, flags) {
 // container. The parent domain must be MyAPI-managed.
 export async function domain(id, domainArg, flags) {
     const config = requireConfig();
-    const orgId = requireOrg(flags, config, 'myapi container domain <id> <domain> [--org <id>]');
+    // Binds a live hostname to a container; the wrong org points a real domain
+    // at the wrong app.
+    const orgId = await requireExplicitOrg(flags, config, 'myapi container domain <id> <domain> [--org <id>]', 'bind this domain', key => hq.listOrgs(key));
     if (!id)
         error('Missing id.\nUsage: myapi container domain <id> <domain>   (or --remove to unbind)');
     if (flags.remove) {

package/dist/commands/domain.js

@@ -1,10 +1,10 @@
-import { domain as sdkDomain, email as sdkEmail } from '@myapihq/sdk';
+import { domain as sdkDomain, email as sdkEmail, hq } from '@myapihq/sdk';
 import { requireConfig } from '../config.js';
 import { success, error, info, printTable, printJson } from '../output.js';
 import { formatDate, retryFunds } from '../utils.js';
 import { resolveRegistrantForRegister } from '../registrant.js';
 import { confirm, isNonInteractive } from '../prompt.js';
-import { requireOrg, requireDomain } from '../helpers.js';
+import { requireOrg, requireExplicitOrg, requireDomain } from '../helpers.js';
 export const EXPOSES = [
     'GET /domain/orgs/{org_id}/list',
     'GET /domain/orgs/{org_id}/check/available/{name}',
@@ -234,7 +234,9 @@ current, targetOrgId, force) {
 }
 export async function assign(domainArg, flags) {
     const config = requireConfig();
-    const orgId = requireOrg(flags, config, 'myapi domain assign <domain> [--no-www] [--org <id>]');
+    // assign is also the REASSIGN path — re-running moves a domain already
+    // serving another org. Hit on x80security.com once already.
+    const orgId = await requireExplicitOrg(flags, config, 'myapi domain assign <domain> [--no-www] [--org <id>]', 'assign (or move) this domain', key => hq.listOrgs(key));
     if (!domainArg)
         error('Missing required arguments.\nUsage: myapi domain assign <domain> [--no-www] [--org <id>]');
     // Assign is also the reassign path: if the domain is currently bound to a

package/dist/commands/funnel.js

@@ -4,7 +4,7 @@ import { funnel as sdkFunnel, hq } from '@myapihq/sdk';
 import { requireConfig } from '../config.js';
 import { success, error, printTable, info, printJson } from '../output.js';
 import { formatDate } from '../utils.js';
-import { requireOrg, confirmDestructive } from '../helpers.js';
+import { requireOrg, requireExplicitOrg, confirmDestructive } from '../helpers.js';
 export const EXPOSES = [
     'POST /funnel/orgs/{org_id}/funnels',
     'GET /funnel/orgs/{org_id}/funnels',
@@ -251,7 +251,9 @@ export async function pages(funnelArg, flags) {
 }
 export async function push(slug, flags) {
     const config = requireConfig();
-    const orgId = requireOrg(flags, config, 'myapi funnel push [slug] [--funnel <id>] [--org <id>]');
+    // Overwrites whatever is live at the target. The demo-onto-a-live-site
+    // failure this repo documents starts exactly here, with an inherited default.
+    const orgId = await requireExplicitOrg(flags, config, 'myapi funnel push [slug] [--funnel <id>] [--org <id>]', 'overwrite a published page', key => hq.listOrgs(key));
     const rawSlug = slug || flags.slug || '/';
     const finalSlug = rawSlug.startsWith('/') ? rawSlug : `/${rawSlug}`;
     let funnelId = flags.funnel || config.default_funnel;

package/dist/commands/keys.js

@@ -1,7 +1,7 @@
 import { formatDate } from '../utils.js';
 import { hq } from '@myapihq/sdk';
 import { requireConfig } from '../config.js';
-import { success, error, printTable, info, printJson } from '../output.js';
+import { success, error, printTable, info, printJson, banner } from '../output.js';
 import { ask, confirm, isNonInteractive } from '../prompt.js';
 import { requireArg } from '../helpers.js';
 export const SCHEMA = {
@@ -115,6 +115,16 @@ export async function createNew(flags) {
     info(`Scope:  ${describeKey(key)}`);
     info('');
     info("Copy the key now — you won't be able to see it again.");
+    // An account-wide key is the default and is almost never what a workload
+    // wants. Org is otherwise an ambient setting, so a stale one on an
+    // account-wide key is a wrong-tenant write with nothing to stop it; locking
+    // the key makes that a 403 instead. Said here because this is the one moment
+    // the choice is being made, and `--org` cannot be added to a key later.
+    if (!opts.orgId) {
+        banner('› This key can reach EVERY org on the account. For an agent or CI job that');
+        banner('  works in one org, lock it: myapi keys create --name <n> --org <id> --grant \'*\'');
+        banner('  A locked key turns a wrong-org write into a 403 instead of a silent success.');
+    }
 }
 export async function list(flags) {
     const config = requireConfig();

package/dist/helpers.d.ts

@@ -1,14 +1,7 @@
 import { type Config } from './config.js';
 export type Flags = Record<string, string | boolean | number>;
 export declare function requireOrg(flags: Flags, config: Config, usage: string): string;
-/** The notice for a move, or undefined when there is nothing to say.
- *
- *  Pure and exported because both failure directions are silent in production:
- *  return a string always and it becomes noise everyone filters out; return
- *  undefined always and the wrong-org write it exists to catch goes through
- *  unannounced. Neither shows up as a broken build, so it is pinned by a test.
- */
-export declare function orgChangeNotice(previous: string | undefined, next: string, names?: Record<string, string>): string | undefined;
+export declare function orgLine(orgId: string, name: string | undefined, changedFrom?: string): string;
 /** The org this invocation resolved to, for `--json` consumers. */
 export declare function currentOrg(): {
     org_id: string;
@@ -20,6 +13,14 @@ export declare function rememberOrgNames(config: Config, orgs: Array<{
     id?: string;
     name?: string;
 }>): void;
+export declare function adoptSoleOrg(command: string | undefined, flags: Flags, listOrgs: (apiKey: string) => Promise<Array<{
+    id?: string;
+    name?: string;
+}>>): Promise<void>;
+export declare function requireExplicitOrg(flags: Flags, config: Config, usage: string, action: string, listOrgs?: (apiKey: string) => Promise<Array<{
+    id?: string;
+    name?: string;
+}>>): Promise<string>;
 export declare function requireDomain(arg: string | undefined, flags: Flags, config: Config, usage: string): string;
 export declare function requireArg(value: string | undefined, name: string, usage: string): string;
 export declare function confirmDestructive(flags: Flags, description: string, usage: string): Promise<void>;

package/dist/helpers.js

@@ -1,5 +1,5 @@
 import { error, banner } from './output.js';
-import { saveConfig } from './config.js';
+import { loadConfig, saveConfig } from './config.js';
 import { confirm, isNonInteractive } from './prompt.js';
 // error() returns `never`, so after `if (!x) error(...)` TS narrows x to a
 // non-falsy value and the casts disappear.
@@ -14,7 +14,7 @@ export function requireOrg(flags, config, usage) {
     if (!orgId) {
         error(`Missing required arguments.\nUsage: ${usage}\n(Or set default: myapi config set-org <id>)`);
     }
-    noticeOrgChanged(orgId, config);
+    announceOrg(orgId, config);
     recordResolvedOrg(orgId, config);
     return orgId;
 }
@@ -35,23 +35,35 @@ export function requireOrg(flags, config, usage) {
 // clean.
 let resolvedOrgId;
 let resolvedOrgName;
-/** The notice for a move, or undefined when there is nothing to say.
- *
- *  Pure and exported because both failure directions are silent in production:
- *  return a string always and it becomes noise everyone filters out; return
- *  undefined always and the wrong-org write it exists to catch goes through
- *  unannounced. Neither shows up as a broken build, so it is pinned by a test.
- */
-export function orgChangeNotice(previous, next, names = {}) {
-    if (!previous || previous === next)
-        return undefined;
-    const label = (id) => (names[id] ? `${names[id]} ` : '') + short(id);
-    return `→ org changed: ${label(previous)} → ${label(next)}`;
+// Announced ONCE per process, always, on stderr.
+//
+// This started as change-only, on the reasoning that a line which is always
+// there becomes noise. That holds for a human and fails for an agent: silence
+// then means "same org" OR "old CLI" OR "notice broke" OR "no org resolved",
+// and a signal whose absence has four meanings cannot be acted on. An agent
+// re-reads context cold every turn and never learns the convention.
+//
+// So it always fires, in a stable key=value shape that greps and parses without
+// being JSON, and costs ~10 tokens. Now silence carries information too: no
+// line means no org was resolved.
+//
+// stderr, so `--json | jq` and piped stdout are untouched.
+let announced = false;
+export function orgLine(orgId, name, changedFrom) {
+    const parts = [`myapi: org=${orgId}`];
+    if (name)
+        parts.push(`name=${JSON.stringify(name)}`);
+    if (changedFrom)
+        parts.push(`changed_from=${changedFrom}`);
+    return parts.join(' ');
 }
-function noticeOrgChanged(orgId, config) {
-    const msg = orgChangeNotice(config.last_org_used, orgId, config.org_names ?? {});
-    if (msg)
-        banner(msg);
+function announceOrg(orgId, config) {
+    if (announced)
+        return; // one line per invocation, however many times requireOrg runs
+    announced = true;
+    const previous = config.last_org_used;
+    const changed = previous && previous !== orgId ? previous : undefined;
+    banner(orgLine(orgId, config.org_names?.[orgId], changed));
 }
 function recordResolvedOrg(orgId, config) {
     resolvedOrgId = orgId;
@@ -93,6 +105,124 @@ export function rememberOrgNames(config, orgs) {
     }
     catch { /* advisory only */ }
 }
+// ── Adopting the org a key can reach ─────────────────────────────────────────
+//
+// An org-locked key (`keys create --org <id>`) can reach exactly one org, and
+// the raw key encodes nothing — so a developer handed one has no way to learn
+// which org it is for, and ends up pasting a UUID onto every command. Backend
+// #124 made `GET /hq/orgs` answer such a key with a list narrowed to its own
+// org, which is what makes the answer discoverable.
+//
+// So: when a command needs an org and nothing is configured, ask. Exactly one
+// result means there is no choice to make, and choosing for someone is only
+// safe when they had no alternative.
+//
+// Runs once, before dispatch, rather than inside requireOrg — requireOrg is
+// synchronous and called from dozens of sites, and making it async to serve a
+// first-run convenience would be a poor trade.
+const ORGLESS_COMMANDS = new Set([
+    // Commands that never need an org, or that exist to establish one. Probing
+    // here would add a round-trip to `myapi --help`-shaped work for nothing.
+    'account', 'login', 'setup', 'update', 'keys', 'billing', 'status', 'config', 'org', 'doctor',
+]);
+export async function adoptSoleOrg(command, flags, listOrgs) {
+    if (!command || ORGLESS_COMMANDS.has(command))
+        return;
+    if (flags.help || typeof flags.org === 'string')
+        return;
+    const config = loadConfig();
+    if (!config?.api_key || config.default_org)
+        return; // nothing to do, or already answered
+    let orgs;
+    try {
+        orgs = await listOrgs(config.api_key);
+    }
+    catch {
+        // An account-wide key on a backend without #124 gets a refusal here, and a
+        // network failure looks the same. Either way this is a convenience: fall
+        // through and let the command ask for --org as it always did.
+        return;
+    }
+    // Two or more means an account-wide key with a real choice to make, and the
+    // existing "which org?" error is the right answer. Zero means nothing to adopt.
+    if (!Array.isArray(orgs) || orgs.length !== 1)
+        return;
+    const only = orgs[0];
+    if (!only?.id)
+        return;
+    try {
+        config.default_org = only.id;
+        if (only.name)
+            config.org_names = { ...(config.org_names ?? {}), [only.id]: only.name };
+        // Safe to persist against the right entry only because saveConfig upserts
+        // by api_key — writing by active index would put this org on somebody
+        // else's account. See the comment there.
+        saveConfig(config);
+    }
+    catch { /* advisory; the command can still run with the in-memory value */ }
+    banner(`› Using org ${only.name ? `${only.name} ` : ''}(${short(only.id)}) — the only org this key can reach`);
+}
+// A displacing write must NAME the org it displaces something in.
+//
+// `--org` cannot be required everywhere: a read that inherits the default is
+// harmless, and an agent that must pass it on all fifty verbs will get it wrong
+// on the fifty-first. So the requirement is placed exactly where being wrong
+// costs something — a write that replaces or moves what is already live.
+//
+// Same shape as confirmDestructive, deliberately: non-interactive callers must
+// be explicit, humans get a prompt naming the org. An agent already passes
+// --yes to those verbs, so --org is the same habit rather than a new one.
+//
+// An org-locked key is exempt. It can only reach one org, so there is no wrong
+// org to reach and the friction would buy nothing — which is also the strongest
+// practical argument for handing agents one.
+export async function requireExplicitOrg(flags, config, usage, action, listOrgs) {
+    const orgId = requireOrg(flags, config, usage);
+    if (typeof flags.org === 'string' && flags.org)
+        return orgId; // stated outright
+    // Exactly one reachable org means the default cannot be the wrong one.
+    //
+    // `org_names` alone cannot answer this. It is populated only by `org list`
+    // and `status`, so an ordinary single-org user who has run neither has an
+    // EMPTY cache — and treating empty as "several" refused a write that carried
+    // no risk whatever. That is most users, on the least dangerous case.
+    //
+    // So an empty cache means unknown, not many, and unknown is worth one GET:
+    // a displacing write is rare and deliberate, the answer is cached onto the
+    // config for next time, and being wrong in either direction here is worse
+    // than a round-trip.
+    const cached = Object.keys(config.org_names ?? {});
+    if (cached.length === 1 && cached[0] === orgId)
+        return orgId;
+    if (cached.length === 0 && listOrgs) {
+        try {
+            const orgs = await listOrgs(config.api_key);
+            if (Array.isArray(orgs)) {
+                rememberOrgNames(config, orgs); // self-heals the cache
+                if (orgs.length === 1 && orgs[0]?.id === orgId)
+                    return orgId;
+            }
+        }
+        catch {
+            // Could not determine. Fall through and require --org: for a write that
+            // replaces something live, "I do not know which orgs this key reaches"
+            // is not a reason to proceed silently.
+        }
+    }
+    const label = config.org_names?.[orgId] ? `${config.org_names[orgId]} (${orgId})` : orgId;
+    if (isNonInteractive()) {
+        error(`Refusing to ${action} using an inherited default org.\n` +
+            `This would act on ${label}.\n\n` +
+            `→ Name it: --org ${orgId}\n` +
+            `  A displacing write should say which org it displaces something in — a stale\n` +
+            `  default looks exactly like a correct one.\n` +
+            `Usage: ${usage}`);
+    }
+    const ok = await confirm(`› ${action} in ${label}? (y/N) `, false);
+    if (!ok)
+        error('Aborted.');
+    return orgId;
+}
 export function requireDomain(arg, flags, config, usage) {
     const fromFlag = typeof flags.domain === 'string' ? flags.domain : '';
     const fromConfig = typeof config.default_domain === 'string' ? config.default_domain : '';

package/dist/index.js

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 import { error, info, success, banner, setResolvedContextSource } from './output.js';
 import { loadConfig } from './config.js';
-import { MyApiError, setUserAgent } from '@myapihq/sdk';
+import { MyApiError, setUserAgent, hq } from '@myapihq/sdk';
 import { friendlyError } from './errors.js';
-import { currentOrg } from './helpers.js';
+import { currentOrg, adoptSoleOrg } from './helpers.js';
 import * as fs from 'fs';
 import { parseFlags } from './flags.js';
 const pkgPath = new URL('../package.json', import.meta.url);
@@ -187,6 +187,11 @@ async function main() {
         process.exit(1);
     }
     const [command, subcommand, ...restArgs] = args;
+    // Before dispatch: if this key can reach exactly one org and nothing is
+    // configured, adopt it. Costs one GET on the first command a fresh
+    // org-locked key runs, and nothing afterwards — the answer is persisted.
+    // Never fatal; see adoptSoleOrg.
+    await adoptSoleOrg(command, flags, key => hq.listOrgs(key));
     try {
         switch (command) {
             case 'auth':

package/dist/org-line.test.d.ts

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

package/dist/org-line.test.js

@@ -0,0 +1,36 @@
+// The org line is emitted on EVERY command that resolves an org.
+//
+// It began as change-only, which is wrong for an agent: silence then meant
+// "same org" OR "old CLI" OR "broken notice" OR "no org resolved", and a signal
+// whose absence has four meanings cannot be acted on. Always-on makes silence
+// mean exactly one thing — no org was resolved.
+//
+// The shape is load-bearing too. Agents parse this, so `key=value` has to stay
+// stable and the id has to appear in full: a truncated id is unusable as an
+// assertion, which is the whole point of emitting it.
+import { describe, it, expect } from 'vitest';
+import { orgLine } from './helpers.js';
+const ID = '7f1aa7f1-f6eb-4a6d-87b7-1bbe6584f5d6';
+describe('orgLine', () => {
+    it('always produces a line — there is no silent case', () => {
+        expect(orgLine(ID, undefined)).toContain(`org=${ID}`);
+    });
+    it('carries the FULL org id, not a shortened one', () => {
+        // A human reads the name; a machine needs the id it can compare against.
+        expect(orgLine(ID, 'Acme')).toContain(ID);
+    });
+    it('includes the name when one is cached', () => {
+        expect(orgLine(ID, 'Acme')).toContain('name="Acme"');
+    });
+    it('omits name rather than emitting an empty value when unknown', () => {
+        expect(orgLine(ID, undefined)).not.toContain('name=');
+    });
+    it('flags a move without hiding the current org', () => {
+        const line = orgLine(ID, 'Acme', 'org-previous');
+        expect(line).toContain(`org=${ID}`);
+        expect(line).toContain('changed_from=org-previous');
+    });
+    it('quotes names so a space cannot break key=value parsing', () => {
+        expect(orgLine(ID, 'Demo Corp')).toContain('name="Demo Corp"');
+    });
+});

package/dist/skills/my-api-hq/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: my-api-hq
-version: 1.1.0
+version: 1.2.0
 description: >
   Auth, organizations, and billing hub. Start here to get an api_key and org_id — every other service depends on both.
 triggers: [api key, account, organization, org, billing, balance, topup, credits, setup, defaults, brand, sync brand, doctor, health check, is my org healthy]
-checksum: sha256-6f54c719facde1ddcdee04ffcf9527ed42550cbfc67679ced5aea55fc7adba7d
+checksum: sha256-ef7057aa3584c43f852415f25ca5d023ee372c8d00f915a5da68a5e70634e2b2
 ---
 
 # MyApiHQ
@@ -81,7 +81,10 @@ myapi org sync-brand acme.com
 myapi account switch 2
 ```
 
-If any service returns `402 INSUFFICIENT_FUNDS`, top up (`myapi billing topup`) — or enable `myapi billing auto-recharge` so it refills itself. With auto-recharge enabled, billable CLI commands (llm, image, email send, domain register/renew, git commit) handle a refill-in-flight automatically: they wait the server-hinted interval and retry instead of failing, so don't add your own retry loop. A `402 SPEND_CAP_EXCEEDED` is different: you hit a spend ceiling you set, so raise it with `myapi billing spend-cap` rather than topping up.
+`402 INSUFFICIENT_FUNDS` → top up, or enable auto-recharge. With it on, billable
+commands wait out a refill-in-flight and retry by themselves — **do not add your
+own retry loop**. `402 SPEND_CAP_EXCEEDED` is a ceiling you set, not an empty
+wallet: raise it with `myapi billing spend-cap`.
 
 Each org gets a free preview subdomain (`*.makeautonomous.com`) usable before registering a custom domain.
 <!-- llm:end -->
@@ -99,9 +102,7 @@ you can hand work a key that cannot exceed its job:
 
 ```bash
 myapi keys create --name agent --org <id> --grant '*'       # locked to ONE org
-myapi keys create --name ci --grant funnel:write,storage:read
-myapi keys create --name readonly --grant '*:read'          # read anything, write nothing
-myapi keys create --name billing-fn --org <id> --grant email --spend-cap 25
+myapi keys create --name ci --grant funnel:write,storage:read --spend-cap 25
 ```
 
 - `--org <id>` — **lock it to one org.** Omit for account-wide.
@@ -116,10 +117,20 @@ exactly like a correct one. That is how a demo lands on a live site. Locking
 turns a wrong-org write into a `403`. Keep your *own* key account-wide though:
 an org-locked one cannot create orgs or manage billing.
 
-Two more signals, no flags needed: resolving to a different org than last time
-prints `→ org changed: <from> → <to>` on stderr, once — silence means it has
-not moved. Under `--json`, object responses carry `_resolved: {org_id,
-org_name}`; assert on that rather than assuming.
+**Every command that resolves an org says so on stderr** — always, not only on
+change, so **no line means no org was resolved**:
+
+```
+myapi: org=7f1aa7f1-f6eb-4a6d-87b7-1bbe6584f5d6 name="Acme" [changed_from=…]
+```
+
+Stable `key=value`, full id, stderr only so `--json | jq` is untouched. Assert
+on it — object `--json` responses also carry `_resolved`, but arrays cannot.
+
+**Displacing writes refuse an inherited default.** `funnel push`,
+`domain assign` and `container domain` require `--org` in non-interactive runs,
+the same shape as `--yes`. A key that reaches one org is exempt — there is no
+wrong org for it to reach.
 
 ## Org profile fields
 

package/package.json

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

package/dist/org-notice.test.js

@@ -1,37 +0,0 @@
-// The org-change notice has two silent failure modes and no build breaks for
-// either: always-speak turns it into noise that gets filtered out within a day
-// (and costs tokens on every call in an agent loop), always-silent lets the
-// wrong-org write it exists to catch go through unannounced. Pin both edges.
-import { describe, it, expect } from 'vitest';
-import { orgChangeNotice } from './helpers.js';
-const NAMES = { 'org-a': 'Acme', 'org-b': 'Demo Corp' };
-describe('orgChangeNotice', () => {
-    it('says nothing in steady state — the same org twice', () => {
-        expect(orgChangeNotice('org-a', 'org-a', NAMES)).toBeUndefined();
-    });
-    it('says nothing on the first ever resolution', () => {
-        // No prior means nothing has moved; announcing here would fire on every
-        // fresh config and train the reader to ignore the line.
-        expect(orgChangeNotice(undefined, 'org-a', NAMES)).toBeUndefined();
-    });
-    it('speaks when the org moves, naming both sides', () => {
-        const msg = orgChangeNotice('org-a', 'org-b', NAMES);
-        expect(msg).toBeDefined();
-        expect(msg).toContain('Acme');
-        expect(msg).toContain('Demo Corp');
-    });
-    it('still speaks when no name is cached, falling back to the id', () => {
-        // The cache is populated opportunistically by `org list` / `status`, so an
-        // agent that never ran either still has to be told the target moved.
-        const msg = orgChangeNotice('org-a', 'org-b', {});
-        expect(msg).toBeDefined();
-        expect(msg).toContain('org-a');
-        expect(msg).toContain('org-b');
-    });
-    it('shortens long ids so the line stays scannable', () => {
-        const long = 'org-7f1aa7f1-f6eb-4a6d-87b7-1bbe6584f5d6';
-        const msg = orgChangeNotice(long, 'org-b', {});
-        expect(msg).not.toContain(long);
-        expect(msg).toContain('org-7f1a');
-    });
-});