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

package/dist/builtins/sandbox.js

@@ -1,17 +1,30 @@
-// c11r sandbox create [--name] [--seed], get, reset, claim, destroy (contract section 4), and
+// c11r sandbox create [--name] [--seed [type]] [--catalogue file], get, reset, claim, destroy (contract sections 4 and 48), and
 // c11r status (section 5). They are built in for what happens on this machine: create stores the
 // sandbox token (mode 600, ~/.config/c11r/credentials.json) and links the folder (.c11r.json);
 // 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, markOutWritten, outWritten, 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';
 import { OUT_NOT_TRACKED, removeOrgSecrets } from '../secrets.js';
 import { VERSION } from '../version.js';
+import { readCatalogue, SEED_TYPES, withShop } from '../storefront.js';
 /** The longest sandbox name the API takes (contract: 422 invalid_argument past it). */
 const NAME_MAX = 25;
+const SEED = {
+    name: 'seed',
+    type: 'enum',
+    values: [...SEED_TYPES],
+    bare: true,
+    description: 'Loads a demo shop of this type: coffee, tshirts or games, six products each, or custom, the person\'s own from --catalogue. Each has two markets, shipping, a manual payment setting (Wire transfer) and a storefront on, enough to place a test order at once. --seed alone is coffee.',
+};
+const CATALOGUE = {
+    name: 'catalogue',
+    type: 'string',
+    description: 'With --seed custom: a YAML file with the shop\'s name, its products (name, description, prices in EUR and USD, code) and optionally its look. Checked here, then sent in the same call.',
+};
 export const sandbox = {
     schema: parseSchema({
         noun: 'sandbox',
@@ -28,9 +41,10 @@ export const sandbox = {
                 live: false,
                 body: [
                     { name: 'name', type: 'string', description: 'The organization name; without it, an invented one. A name starting zztest marks a test organization.' },
-                    { name: 'seed', type: 'boolean', description: 'Loads the demo dataset: two markets, six products, shipping and a test payment method, enough to place a test order at once.' },
+                    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 is applied, in about 20 seconds.',
+                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.' },
             {
@@ -39,8 +53,8 @@ export const sandbox = {
                 path: '/v1/sandbox/reset',
                 live: false,
                 destructive: true,
-                body: [{ name: 'seed', type: 'boolean', description: 'Seeds the fresh organization, or not; without it, as before.' }],
-                effect: 'Replaces the sandbox with a fresh organization behind the same token, seeded as before, and retires the old one. The slug changes; this machine and .c11r.json follow it.',
+                body: [{ ...SEED, description: 'Seeds the fresh organization with this type, or not (--seed false); without it, as before. custom needs --catalogue again.' }, CATALOGUE],
+                effect: 'Replaces the sandbox with a fresh organization behind the same token, seeded as before (its storefront on again), and retires the old one. The slug changes; this machine and .c11r.json follow it.',
             },
             { verb: 'claim', method: 'POST', path: '/v1/sandbox/claim', live: false, effect: 'Returns a one-time claim URL, valid 30 minutes, for the human to open: they sign in with Commerce Layer and pick a plan. The agent never opens it for them.' },
             {
@@ -76,16 +90,18 @@ async function create(run, values) {
     if (name !== undefined && (name.trim() === '' || name.length > NAME_MAX)) {
         fail('invalid_value', `--name ${JSON.stringify(name)} is ${name.trim() === '' ? 'empty' : `${name.length} characters`}: a sandbox name has 1 to ${NAME_MAX}.`, { path: 'name', next_step: { action: 'fix_request', command: null } });
     }
-    const seed = Boolean(values.seed);
+    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')}`;
-    const r = await request({ method: 'POST', path: '/sandboxes', body: { ...(name ? { name } : {}), seed, test }, dryRun: run.globals.dryRun, timeoutMs: seed ? 120_000 : 60_000, idempotencyKey }, { live: false, token: named ? run.org.token : null });
+    const r = await request({ method: 'POST', path: '/sandboxes', body: { ...(name ? { name } : {}), seed, ...(catalogue ? { catalogue } : {}), test }, dryRun: run.globals.dryRun, timeoutMs: seed ? 180_000 : 60_000, idempotencyKey }, { live: false, token: named ? run.org.token : null });
     if (run.globals.dryRun)
         return r;
     const { token, ...data } = r.data ?? {};
@@ -93,15 +109,35 @@ 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 { ...r, data: { ...data, token_hint: hint, credentials: credentialsFile(), linked: link.file }, warnings };
+    return withShop({ ...r, data: { ...data, token_hint: hint, credentials: credentialsFile(), linked: link.file }, warnings }, data.store);
+}
+/** --seed and --catalogue as the API takes them: custom only with a catalogue, a catalogue only with custom. */
+function seedBody(values) {
+    const seed = values.seed ?? false;
+    const file = values.catalogue;
+    if (seed === 'custom' && file === undefined) {
+        fail('missing_value', '--seed custom needs --catalogue: a YAML file with the shop\'s name and its products. Write it from what the human described, show it to them, then run the command with --catalogue <file>.', { path: 'catalogue', next_step: { action: 'fix_request', command: null } });
+    }
+    if (file !== undefined && seed !== 'custom')
+        fail('invalid_value', '--catalogue goes only with --seed custom: the other types bring their own products.', { path: 'catalogue', next_step: { action: 'fix_request', command: null } });
+    return { seed, catalogue: file === undefined ? undefined : readCatalogue(file) };
 }
 async function reset(run, values) {
-    const r = await run.send({ method: 'POST', path: '/sandbox/reset', body: values.seed === undefined ? {} : { seed: values.seed } });
+    const body = {};
+    if (values.seed !== undefined || values.catalogue !== undefined) {
+        const { seed, catalogue } = seedBody(values);
+        body.seed = seed;
+        if (catalogue)
+            body.catalogue = catalogue;
+    }
+    const r = await run.send({ method: 'POST', path: '/sandbox/reset', body });
     if (run.globals.dryRun)
         return r;
     const { org, previous_org: previous } = r.data ?? {};
@@ -112,7 +148,7 @@ async function reset(run, values) {
         if (link?.org === before)
             writeLink(org);
     }
-    return r;
+    return withShop(r, r.data?.store);
 }
 async function destroy(run) {
     let r;
@@ -124,8 +160,7 @@ async function destroy(run) {
         // here. The sandbox is gone either way, so this machine forgets it too.
         if (!(e instanceof CliError && e.code === 'unauthorized') || run.globals.dryRun || !run.org.org)
             throw e;
-        const out = outWritten(run.org.org);
-        markOutWritten(run.org.org, false);
+        const out = forgetOutWritten(run.org.org);
         forgetOrg(run.org.org);
         const link = removeLink(run.org.org);
         const secrets = removeOrgSecrets(run.org.org);
@@ -136,8 +171,7 @@ async function destroy(run) {
     const org = r.data?.org ?? run.org.org;
     if (!org)
         return r;
-    const out = outWritten(org);
-    markOutWritten(org, false);
+    const out = forgetOutWritten(org);
     forgetOrg(org);
     const link = removeLink(org);
     const secrets = removeOrgSecrets(org);
@@ -148,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();
@@ -168,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: (() => {