@commercelayer/agent-cli 1.0.0-dev.21 → 1.0.0-dev.22

package/README.md

@@ -53,7 +53,7 @@ Two kinds of bearer. An **organization token** (`sbx_...` from `sandbox create`,
 
 Never from a flag or the environment. c11r exchanges the pair for a two hour token at Commerce Layer and sends only that token to the c11r API; the client secret never leaves this machine. Both are kept in `credentials.json`, mode 600, and never printed. `c11r status` shows the stored login as `cli.login`, `{ client_id, email, stored_at }`, or null: read on this machine, never the secret. `auth logout` forgets the login; its last token ends by itself within two hours. Organization tokens stay.
 
-`organizations create` and `organizations connect <slug>` answer an organization token once: it is stored like a sandbox token. `connect --revoke-others` also ends every other token of that organization, and asks for confirmation. With a login and no organization token for the organization named, an organization noun stops with `no_credentials` and the next step `c11r organizations connect <slug>`. `members` and `roles` with an organization token and no login are sent with that token, and the API says what is needed: a claim for a sandbox, a login for a claimed organization. `organizations` with no login stops here with `login_required`.
+`organizations create` and `organizations connect <slug>` answer an organization token once: it is stored like a sandbox token. `connect --revoke-others` also ends every other token of that organization, and asks for confirmation. On an organization c11r does not know (one of the human's own, made outside c11r), `connect` gives commercelayer.ai admin access to it in test mode: the API answers `428 confirmation_required` with the sentence naming that access until the command runs with `--yes` (the schema marks it `confirm_when: ["unknown_organization"]`); `--dry-run` answers the same sentence. The answer carries `connected: true`, `access`, `mode: test` and `payments.flow`, and `auth login` keeps `connected_with_c11r` beside `claimed_with_c11r` and `created_with_c11r` for each organization. With a login and no organization token for the organization named, an organization noun stops with `no_credentials` and the next step `c11r organizations connect <slug>`. `members` and `roles` with an organization token and no login are sent with that token, and the API says what is needed: a claim for a sandbox, a login for a claimed organization. `organizations` with no login stops here with `login_required`.
 
 `credentials create` and `credentials token` answer a secret once. c11r writes it to a file with mode 600 and prints the file, the format and a hint, never the value: by default `~/.config/c11r/secrets/<org>/<name>.env` (`<id>-token.env` for a token; a record with no name, such as a gift card, `gift-card-<id>.env` after the id it is given), or `--out <path>`, as `KEY=value` lines or with `--format json` one JSON object. The file is checked before the request is sent; one there already is replaced only with `--yes`. A file inside a git repository that git does not ignore gets the warning `secret_not_ignored`. With `--dry-run` nothing is written and `secret_file` says where it would go. Each file records the record it belongs to. A `delete` of a record whose noun answers secrets (`credentials`, `webhooks`) removes the files c11r wrote for it in `~/.config/c11r/secrets/<org>/` (a credential's secret and tokens, a webhook's shared secret), found by the id, name or code given, and lists them in `removed_files`; `sandbox destroy` removes the whole folder of that organization and names it in `forgotten.secrets`. A file written with `--out` is not tracked and stays: the warning `out_files_not_tracked` says so on the delete of the record whose secret went to `--out` on this machine, and on `sandbox destroy` of an organization that had one. Any other delete has no such warning. A token file carries `CL_BASE_ENDPOINT` beside the token. `sales-calls book` answers a cancel token once: it is kept in `credentials.json` and `sales-calls cancel <booking>` sends it.
 
@@ -77,7 +77,7 @@ Destructive verbs (deletes, `orders cancel`, `payments void` and `refund`, `sand
 - Without a login, nothing is checked on this machine: the request goes with the organization token this machine holds for the organization named, or with no token when it holds none (never `C11R_TOKEN`), and the API's answer (`login_required`, or `state_required` for an organization not claimed) comes through as it is. So do `live_unavailable` (a plan without live), `forbidden` (the login is not an active admin of it) and `not_supported` for a verb that comes with a later step of go-live.
 - A verb that never runs live (sandbox, plans, sales calls, `auth login`, `auth switch`, `shop`) stops on this machine with `state_required`.
 - `c11r events writes --live --org <slug>` (`--since 2026-11-12T00:00:00Z`, an ISO time, `--noun`, `--cursor`, `--limit`) is the audit of live writes, and runs only in live: without `--live` it is `missing_value` with the full command, before any call.
-- `c11r status --live --org <slug>` is the organization's live status, with `live_credential` and the warning `live_credential_held` while the API holds one.
+- `c11r status --live --org <slug>` is the organization's live status, with `live_credential` and the warning `live_credential_held` while the API holds one. On a connected organization the first live call answers `428 confirmation_required` before the live credential is made; `c11r status --live --org <slug> --yes` is the yes, sent as `confirm=true` on that read. A write's `--yes` never stands for it.
 - `c11r auth logout --live --org <slug>` revokes that credential in Commerce Layer (`DELETE /v1/auth/live`): `{ org, revoked, credential }`. The login stays on this machine. `--dry-run` says what it would revoke.
 - A verb that needs a yes is confirmed by the API in live, with a sentence naming the action, the amount and the mode (`Refunds EUR 1.00 on order N, in LIVE mode, real money.`): the CLI sends it without `confirm=true` and shows that `confirmation_required` as it is, with the API's next command, or asks it with those words in a terminal. `--yes` sends `confirm=true` on every live write, `payments capture` included.
 - A verb that answers a secret (`credentials create`) writes it in live only to the file the human chose with `--out`: without it, `missing_value` with the command and `--out FILE`. Never to c11r's secrets folder, never printed. A live delete leaves the test mode's secret files of the same organization alone.
@@ -90,7 +90,9 @@ Destructive verbs (deletes, `orders cancel`, `payments void` and `refund`, `sand
 `--org`, then `C11R_ORG`, then `.c11r.json` in the project folder (found by walking up, like `.git`), then the default set by `auth switch --global`, then the stored organization when exactly one is stored (never for a login noun's `?org=`). With several stored and nothing naming one, the command stops with `org_required` and lists them.
 
 - Tokens are only in `~/.config/c11r/credentials.json` (or under `XDG_CONFIG_HOME`), mode 600. The CLI never prints one, only its hint. Each token records the host that issued it: organization and cancel tokens the API base, the login the auth endpoint. One is used, listed and forgotten only while that host is the one in effect (`C11R_API_URL`, `C11R_AUTH_URL`), so a token never goes to another host. An entry that records no host is not used, and goes at the next write.
-- `.c11r.json` holds only `{ "org": "<slug>" }`: no secret, safe to commit. `sandbox create`, `organizations create` and `auth switch` write it, and `organizations connect` when the folder has no link; `reset` follows the new slug; `destroy` removes it when it names the destroyed organization.
+- `.c11r.json` holds only `{ "org": "<slug>" }`: no secret, safe to commit. `sandbox create` and `organizations create` write it in the current folder: a link found above is another project's, stays as it is (warning `parent_link_kept`), and its token is not sent. `auth switch` writes it too, and `organizations connect` when the folder has no link; `reset` follows the new slug; `destroy` removes it when it names the destroyed organization.
+- `c11r status` shows the link in `cli.link`, with `here`: true when the `.c11r.json` is in the current folder, false when it was found above.
+- `sandbox create` sends a token only when this folder's own link, `--org`, `C11R_ORG` or `C11R_TOKEN` names the sandbox: the API then finishes a failed seed there, or refuses a second sandbox with `409 conflict`. The default of `auth switch --global` and the one stored token are not sent.
 - The project folder is the one with `.c11r.json`, else the nearest with `store.yml` or `loops.yml`, else the current one. `loops.yml` goes there.
 
 ## The store's setup in files

package/dist/builtins/auth.js

@@ -70,6 +70,9 @@ export const auth = {
         return undefined;
     },
 };
+/** How the organization came to c11r, as the API marks it: at most one of the three is true. */
+const MARKERS = ['claimed_with_c11r', 'created_with_c11r', 'connected_with_c11r'];
+const markers = (o) => Object.fromEntries(MARKERS.filter((k) => o[k] !== undefined).map((k) => [k, o[k]]));
 async function login(run) {
     const v = run.parsed.values;
     const prompter = run.prompter ?? terminal;
@@ -114,7 +117,7 @@ async function login(run) {
             token: minted.token,
             expires_at: minted.expires_at,
             user: who.data?.user ?? null,
-            organizations: items.map((o) => ({ slug: o.slug, name: o.name, plan: o.plan ?? null, ...(o.claimed_with_c11r !== undefined ? { claimed_with_c11r: o.claimed_with_c11r } : {}) })),
+            organizations: items.map((o) => ({ slug: o.slug, name: o.name, plan: o.plan ?? null, ...markers(o) })),
             created_at: new Date().toISOString(),
         });
     }
@@ -168,7 +171,7 @@ async function switchOrg(run) {
         reached = items.map((o) => o.slug);
         const l = storedLogin();
         if (l)
-            storeLogin({ ...l, organizations: items.map((o) => ({ slug: o.slug, name: o.name, plan: o.plan ?? null })) });
+            storeLogin({ ...l, organizations: items.map((o) => ({ slug: o.slug, name: o.name, plan: o.plan ?? null, ...markers(o) })) });
     }
     if (!tokens[slug] && !reached.includes(slug)) {
         const known = [...new Set([...Object.keys(tokens), ...reached])];

package/dist/builtins/extensions.js

@@ -11,7 +11,7 @@ import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 import zlib from 'node:zlib';
-import { credentialsFile, forgetOrg, forgetOutWritten, hintOf, projectDir, readLink, removeLink, storeBooking, storedBooking, storedOrgs, storeOrg, writeLink } from '../config.js';
+import { credentialsFile, forgetOrg, forgetOutWritten, hintOf, projectDir, readLink, removeLink, parentLinkKept, storeBooking, storedBooking, storedOrgs, storeOrg, writeLink } from '../config.js';
 import { OUT_NOT_TRACKED, removeOrgSecrets } from '../secrets.js';
 import { confirm, terminal } from '../confirm.js';
 import { fail } from '../errors.js';
@@ -64,15 +64,20 @@ export const organizations = {
         })();
         let linked = null;
         if (run.verb.name === 'create' || !existing || existing.org === org) {
-            const link = writeLink(org);
+            // A create links this folder; a link found above stays as it is.
+            const create = run.verb.name === 'create';
+            const link = writeLink(org, { here: create });
             linked = link.file;
+            if (create && existing && !existing.here)
+                warnings.push(parentLinkKept(existing));
             if (link.previous)
                 warnings.push({ code: 'relinked', message: `${link.file} named ${link.previous}; it now names ${org}. The token of ${link.previous} stays stored.` });
         }
         else {
             warnings.push({ code: 'not_linked', message: `${existing.file} names ${existing.org}, so this folder stays linked to it. --org ${org}, or c11r auth switch ${org}, acts on ${org}.` });
         }
-        if (typeof data.revoked === 'number') {
+        // Only when --revoke-others asked: a first connect answers revoked: 0 as well.
+        if (typeof data.revoked === 'number' && run.parsed.values.revoke_others) {
             warnings.push({ code: 'tokens_revoked', message: data.revoked ? `${data.revoked} other organization token${data.revoked === 1 ? '' : 's'} of ${org} no longer work${data.revoked === 1 ? 's' : ''}, on whatever machine held them.` : `No other organization token of ${org} was in use.` });
         }
         return { ...r, data: { ...data, org, token_hint: hint, credentials: credentialsFile(), linked }, warnings };

package/dist/builtins/sandbox.js

@@ -4,7 +4,7 @@
 // reset moves both to the new organization; destroy forgets them. The token is printed never,
 // not even by create: only its hint.
 import crypto from 'node:crypto';
-import { credentialsFile, defaultOrg, forgetOutWritten, storedLogin, forgetOrg, LINK_FILE, readLink, removeLink, renameOrg, storedOrgs, storeOrg, writeLink, hintOf } from '../config.js';
+import { credentialsFile, defaultOrg, forgetOutWritten, storedLogin, forgetOrg, LINK_FILE, readLink, removeLink, renameOrg, parentLinkKept, storedOrgs, storeOrg, writeLink, hintOf } from '../config.js';
 import { CliError, fail } from '../errors.js';
 import { apiUrl, envelope, request } from '../http.js';
 import { parseSchema } from '../schema.js';
@@ -44,7 +44,7 @@ export const sandbox = {
                     SEED,
                     CATALOGUE,
                 ],
-                effect: 'Creates a sandbox, stores its token on this machine (never printed) and links this folder to it with .c11r.json. With --seed it answers once the seed and its storefront are in place, in about 20 seconds, with the shop link.',
+                effect: 'Creates a sandbox, stores its token on this machine (never printed) and links this folder to it with .c11r.json, in this folder: a link in a folder above is another project\'s and stays as it is. With --seed it answers once the seed and its storefront are in place, in about 20 seconds, with the shop link.',
             },
             { verb: 'get', method: 'GET', path: '/v1/sandbox', live: false, effect: 'Returns the sandbox: organization, expiry, whether it is seeded, the token hint and the claim status.' },
             {
@@ -92,10 +92,12 @@ async function create(run, values) {
     }
     const { seed, catalogue } = seedBody(values);
     const test = process.env.C11R_TEST === '1' || Boolean(name?.startsWith('zztest'));
-    // The token goes only when this folder, --org or C11R_ORG names a sandbox: the API then
-    // finishes a failed seed there, or answers 409 conflict naming it, rather than make a second
-    // one for the same folder. A token picked only because it is the one stored stays home.
-    const named = run.org.source === 'link' || run.org.source === 'flag' || run.org.source === 'env' || run.org.source === 'token_env';
+    // The token goes only when this folder's own link, --org, C11R_ORG or C11R_TOKEN names a
+    // sandbox: the API then finishes a failed seed there, or answers 409 conflict naming it, rather
+    // than make a second one for the same folder. A link found above is another project's, and a
+    // token picked as the default or as the only one stored stays home: the create makes a new one.
+    const above = readLink();
+    const named = (run.org.source === 'link' && above?.here === true) || run.org.source === 'flag' || run.org.source === 'env' || run.org.source === 'token_env';
     // A fresh key per create: after a 5xx or a lost connection the same create is repeated with it,
     // and the API answers the sandbox (and token) it made, rather than leave one with a lost token.
     const idempotencyKey = `c11r-${crypto.randomBytes(16).toString('base64url')}`;
@@ -107,9 +109,11 @@ async function create(run, values) {
         fail('invalid_response', 'The API created a sandbox without returning its org and token.', { next_step: { action: 'none' } });
     const hint = typeof data.token_hint === 'string' ? data.token_hint : hintOf(token);
     storeOrg(data.org, { token, token_hint: hint, expires_at: data.expires_at ?? null, created_at: new Date().toISOString(), api_url: apiUrl() });
-    const link = writeLink(data.org);
+    const link = writeLink(data.org, { here: true });
     // The API says to store the token: the CLI has, and printed none of it.
     const warnings = r.warnings.filter((w) => w.code !== 'token_shown_once');
+    if (above && !above.here)
+        warnings.push(parentLinkKept(above));
     if (link.previous)
         warnings.push({ code: 'relinked', message: `${link.file} named ${link.previous}; it now names ${data.org}. The token of ${link.previous} stays stored.` });
     return withShop({ ...r, data: { ...data, token_hint: hint, credentials: credentialsFile(), linked: link.file }, warnings }, data.store);
@@ -178,12 +182,14 @@ export const status = {
         noun: 'status',
         kind: 'task',
         description: 'c11r status: where this machine and folder stand. The organization picked and from where, its lifecycle state, plan, mode, limits, usage and what is waiting.',
-        verbs: [{ verb: 'get', method: 'GET', path: '/v1/status', state: 'none', effect: 'Returns the status. c11r status is the same as c11r status get.' }],
+        verbs: [{ verb: 'get', method: 'GET', path: '/v1/status', state: 'none', effect: 'Returns the status. c11r status is the same as c11r status get. With --live --yes it sends confirm=true: on an organization connected to c11r, the first live call asks for it once, before the live credential is made.' }],
     }),
     defaultVerb: 'get',
     async run(run) {
         // Status works at every state: an unresolved organization is shown, not raised.
-        const r = await run.send({ method: 'GET', path: '/status' });
+        // In live, --yes is the human's yes to the live credential of a connected organization
+        // (contract 49.4): only this read, confirmed, makes it, never a write's --yes.
+        const r = await run.send({ method: 'GET', path: '/status', ...(run.globals.live && run.globals.yes && !run.globals.dryRun ? { confirm: true } : {}) });
         const link = (() => {
             try {
                 return readLink();
@@ -198,7 +204,7 @@ export const status = {
             api_url: apiUrl(),
             org: run.org.org ? { slug: run.org.org, from: run.org.source } : null,
             ...(run.org.problem ? { org_problem: { code: run.org.problem.code, message: run.org.problem.message } } : {}),
-            link: link ? { file: link.file, org: link.org } : { file: null, name: LINK_FILE },
+            link: link ? { file: link.file, org: link.org, here: link.here } : { file: null, name: LINK_FILE, here: false },
             credentials: credentialsFile(),
             stored,
             login: (() => {

package/dist/config.js

@@ -6,6 +6,8 @@
 // A project folder links to its organization with .c11r.json, { "org": "<slug>" }: no secret,
 // safe to commit, found by walking up from the current folder like .git. The project folder is
 // the one with .c11r.json, else the nearest with store.yml or loops.yml, else the current one.
+// A link found above is the folder's for every command but a create: sandbox create and
+// organizations create link the current folder, and leave the link above as it is.
 //
 // The organization: --org, then C11R_ORG, then .c11r.json, then the stored one when exactly one
 // is stored. With several stored and nothing naming one, the command stops and names them.
@@ -191,15 +193,23 @@ export function readLink() {
     const org = raw?.org;
     if (typeof org !== 'string' || !org)
         fail('invalid_config', `${file} has no org.`, { path: `${LINK_FILE}.org` });
-    return { file, org };
+    return { file, org, here: dir === path.resolve(process.cwd()) };
 }
-/** Links the project folder to the organization; returns the file and the org it linked before. */
-export function writeLink(org) {
-    const existing = readLink();
+/**
+ * Links the project folder to the organization; returns the file and the org it linked before.
+ * With here, the current folder, whatever a folder above links: a create makes a new project.
+ */
+export function writeLink(org, opts = {}) {
+    const found = readLink();
+    const existing = opts.here && !found?.here ? null : found;
     const file = existing?.file ?? path.join(process.cwd(), LINK_FILE);
     fs.writeFileSync(file, JSON.stringify({ org }, null, 2) + '\n');
     return { file, previous: existing && existing.org !== org ? existing.org : null };
 }
+/** The warning of a create that linked this folder and left the link of a folder above as it is. */
+export function parentLinkKept(above) {
+    return { code: 'parent_link_kept', message: `The folder above links ${above.org} (${above.file}); it stays as it is, and this folder now has its own link. Tell the human only that the shop in the folder above stays as it is.` };
+}
 /** Removes the link, only when it names this organization. */
 export function removeLink(org) {
     const link = readLink();

package/dist/engine.js

@@ -132,8 +132,10 @@ async function executeOnce(argv, opts) {
     // amount and the mode ("Refunds EUR 1.00 on order N, in LIVE mode, real money."): the CLI sends
     // without confirm=true and shows that 428 as it is, or asks it in a terminal. --yes sends
     // confirm=true on every live write, payments capture included.
-    // So does a login verb (organizations disconnect), whose sentence names what stops answering.
-    const apiAsks = (live || verb.credential === 'login') && (verb.confirm || confirmFlags.length > 0);
+    // So does a login verb (organizations disconnect), whose sentence names what stops answering,
+    // and one the schema marks confirm_when: the API asks only in that state of the target
+    // (connect on an organization c11r does not know), with a sentence naming the access given.
+    const apiAsks = (live || verb.credential === 'login') && (verb.confirm || confirmFlags.length > 0 || verb.confirmWhen.length > 0);
     if (apiAsks && cmd.globals.yes && !cmd.globals.dryRun)
         confirmed = true;
     if (live && cmd.globals.yes && verb.method !== 'GET')

package/dist/schema.js

@@ -63,6 +63,7 @@ export function parseSchema(raw, expected) {
             secret: Boolean(v.secret),
             idAlternative: Array.isArray(v.id_alternative) ? v.id_alternative.filter((x) => typeof x === 'string' && flags[x]) : [],
             confirmIf: Array.isArray(v.confirm_if) ? v.confirm_if.filter((x) => typeof x === 'string') : [],
+            confirmWhen: Array.isArray(v.confirm_when) ? v.confirm_when.filter((x) => typeof x === 'string') : [],
             refused: v.served === false ? { by: v.refused_by ?? 'the API' } : null,
             path: v.path ? v.path.replace(/^\/v\d+(?=\/)/, '') : null,
             flags,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@commercelayer/agent-cli",
-  "version": "1.0.0-dev.21",
+  "version": "1.0.0-dev.22",
   "description": "c11r: the Commerce Layer CLI for coding agents. One grammar, c11r <noun> <verb>, from a sandbox to a running organization.",
   "homepage": "https://commercelayer.ai",
   "keywords": [