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

package/dist/project.js

@@ -0,0 +1,185 @@
+// The project folder's configuration files (contract section 45.2): store.yml and
+// price_lists/<code>.csv, written by config export and read by config plan and apply, and the
+// CLI's own notes about them in .c11r/:
+//
+//   .c11r/export.json  what the last export wrote: the organization, when, and each file's hash,
+//                      so the next export never overwrites a file changed since without --yes.
+//   .c11r/drift        the Configure writes made since, in a folder whose store.yml names the
+//                      same organization: config plan mentions them, config export clears them.
+//
+// Live is a mode of the same organization, with the same slug: store.yml, the export record and
+// the drift notes say which mode they are of, so test and live notes never mix.
+//
+// store.yml carries the export's meta ({ org, mode, exported_at }) as its first key; the CLI takes it
+// off before it sends the file, so the API sees { <noun>: [records] } only.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import YAML from 'yaml';
+import { projectDir } from './config.js';
+import { fail } from './errors.js';
+const sameSource = (a, b) => a.org !== null && a.org === b.org && a.mode === b.mode;
+export const STORE_FILE = 'store.yml';
+export const PRICE_LISTS_DIR = 'price_lists';
+const NOTES_DIR = '.c11r';
+const EXPORT_FILE = 'export.json';
+const DRIFT_FILE = 'drift';
+const hashOf = (text) => `sha256-${crypto.createHash('sha256').update(text).digest('hex')}`;
+const notes = (dir) => path.join(dir, NOTES_DIR);
+/** store.yml and the price list CSVs of the project folder, or store_not_found. */
+export function readStoreFiles(dir = projectDir()) {
+    const file = path.join(dir, STORE_FILE);
+    let text;
+    try {
+        text = fs.readFileSync(file, 'utf8');
+    }
+    catch {
+        fail('not_found', `There is no ${STORE_FILE} in ${dir}. c11r config export writes one from the organization.`, { path: 'store', next_step: { action: 'fix_request', command: 'c11r config export' } });
+    }
+    let doc;
+    try {
+        doc = YAML.parse(text) ?? {};
+    }
+    catch (e) {
+        fail('invalid_config', `${file} is not YAML: ${e.message}`, { path: 'store' });
+    }
+    if (!doc || typeof doc !== 'object' || Array.isArray(doc))
+        fail('invalid_config', `${file} holds no nouns: it is { <noun>: [records] }.`, { path: 'store' });
+    const { meta, ...store } = doc;
+    const org = meta && typeof meta === 'object' && typeof meta.org === 'string' ? meta.org : null;
+    const price_lists = {};
+    const csvDir = path.join(dir, PRICE_LISTS_DIR);
+    let names = [];
+    try {
+        names = fs.readdirSync(csvDir);
+    }
+    catch {
+        // No price lists: fine.
+    }
+    for (const n of names.sort())
+        if (n.endsWith('.csv'))
+            price_lists[n.slice(0, -4)] = fs.readFileSync(path.join(csvDir, n), 'utf8');
+    return { store, price_lists, org };
+}
+/** The organization and mode the folder's store.yml names; org null without one. */
+export function storeFileSource(dir = projectDir()) {
+    try {
+        const doc = YAML.parse(fs.readFileSync(path.join(dir, STORE_FILE), 'utf8'));
+        return { org: typeof doc?.meta?.org === 'string' ? doc.meta.org : null, mode: doc?.meta?.mode === 'live' ? 'live' : 'test' };
+    }
+    catch {
+        return { org: null, mode: 'test' };
+    }
+}
+/** Whether the folder's store.yml is of this organization in this mode. */
+export const storeFileIs = (org, mode, dir = projectDir()) => sameSource(storeFileSource(dir), { org, mode });
+/**
+ * Writes an export: store.yml (meta first) and price_lists/<code>.csv. A file there that differs
+ * from what the last export wrote (or that no export wrote) is the user's: without overwrite,
+ * nothing is written and the answer lists them. Price list files the last export wrote, unchanged
+ * since, and no longer in the organization, go.
+ */
+export function writeStoreFiles(data, opts) {
+    const dir = opts.dir ?? projectDir();
+    const last = readRecord(dir);
+    const meta = { org: data.meta?.org ?? null, mode: opts.mode, exported_at: data.meta?.exported_at ?? new Date().toISOString() };
+    const yaml = `# The organization's setup, written by c11r config export. Edit it, then c11r config plan and c11r config apply.\n${YAML.stringify({ meta, ...data.store }, { lineWidth: 0 })}`;
+    const files = { [STORE_FILE]: yaml };
+    for (const [code, csv] of Object.entries(data.price_lists ?? {}))
+        files[path.join(PRICE_LISTS_DIR, `${safeName(code)}.csv`)] = csv;
+    // Files of another organization or mode are not the last export's to replace: --yes first.
+    const other = last.org !== null && !sameSource(last, meta);
+    const changed = (rel) => {
+        const abs = path.join(dir, rel);
+        if (!fs.existsSync(abs))
+            return false;
+        if (other)
+            return true;
+        const now = hashOf(fs.readFileSync(abs, 'utf8'));
+        return last.files[rel] !== now;
+    };
+    const stale = Object.keys(last.files).filter((rel) => rel.startsWith(`${PRICE_LISTS_DIR}${path.sep}`) && !(rel in files) && fs.existsSync(path.join(dir, rel)));
+    const mine = [...Object.keys(files).filter((rel) => files[rel] !== readOr(path.join(dir, rel))), ...stale].filter(changed);
+    if (mine.length && !opts.overwrite) {
+        fail('conflict', `${mine.join(', ')} changed since the last export${last.exported_at ? ` (${last.exported_at})` : ''}, or no export wrote ${mine.length === 1 ? 'it' : 'them'}. c11r replaces ${mine.length === 1 ? 'it' : 'them'} only with --yes; c11r config plan shows what the files would change in the organization.`, {
+            path: 'store',
+            details: { files: mine.map((rel) => path.join(dir, rel)) },
+            next_step: { action: 'fix_request', command: 'c11r config plan' },
+        }, 'rejected');
+    }
+    const written = [];
+    for (const [rel, text] of Object.entries(files)) {
+        const abs = path.join(dir, rel);
+        fs.mkdirSync(path.dirname(abs), { recursive: true });
+        if (readOr(abs) !== text)
+            fs.writeFileSync(abs, text);
+        written.push(abs);
+    }
+    const removed = [];
+    for (const rel of stale) {
+        fs.rmSync(path.join(dir, rel), { force: true });
+        removed.push(path.join(dir, rel));
+    }
+    writeRecord(dir, { org: meta.org, mode: meta.mode, exported_at: meta.exported_at, files: Object.fromEntries(Object.entries(files).map(([rel, text]) => [rel, hashOf(text)])) });
+    clearDrift(dir);
+    return { written, removed, dir };
+}
+/**
+ * After a Configure write: in a folder whose store.yml names this organization, notes it in
+ * .c11r/drift and answers the warning. Elsewhere, nothing.
+ */
+export function markDrift(org, mode, entry, dir = projectDir()) {
+    if (!storeFileIs(org, mode, dir))
+        return null;
+    const list = readDrift(dir);
+    list.push({ ...entry, at: new Date().toISOString() });
+    fs.mkdirSync(notes(dir), { recursive: true });
+    // The first ones say since when; the last 50 say what.
+    const kept = list.length > 50 ? [list[0], ...list.slice(-49)] : list;
+    fs.writeFileSync(path.join(notes(dir), DRIFT_FILE), JSON.stringify(kept, null, 2) + '\n');
+    return driftWarning(kept);
+}
+/** The writes noted since the last export, oldest first. */
+export function readDrift(dir = projectDir()) {
+    try {
+        const v = JSON.parse(fs.readFileSync(path.join(notes(dir), DRIFT_FILE), 'utf8'));
+        return Array.isArray(v) ? v : [];
+    }
+    catch {
+        return [];
+    }
+}
+export function clearDrift(dir = projectDir()) {
+    fs.rmSync(path.join(notes(dir), DRIFT_FILE), { force: true });
+}
+export function driftWarning(list) {
+    const first = list[0];
+    const what = (e) => `${e.noun} ${e.verb}${e.id ? ` ${e.id}` : ''}`;
+    return {
+        code: 'config_drift',
+        message: `store.yml is now behind the organization, since ${first.at} (${what(first)}${list.length > 1 ? ` and ${list.length - 1} more` : ''}): c11r config export refreshes it.`,
+    };
+}
+function readRecord(dir) {
+    try {
+        const v = JSON.parse(fs.readFileSync(path.join(notes(dir), EXPORT_FILE), 'utf8'));
+        return { org: v.org ?? null, mode: v.mode === 'live' ? 'live' : 'test', exported_at: v.exported_at ?? null, files: v.files && typeof v.files === 'object' ? v.files : {} };
+    }
+    catch {
+        return { org: null, mode: 'test', exported_at: null, files: {} };
+    }
+}
+function writeRecord(dir, r) {
+    fs.mkdirSync(notes(dir), { recursive: true });
+    fs.writeFileSync(path.join(notes(dir), EXPORT_FILE), JSON.stringify(r, null, 2) + '\n');
+}
+function readOr(file) {
+    try {
+        return fs.readFileSync(file, 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
+/** A price list code as a file name: letters, digits, dot, dash and underscore. */
+const safeName = (code) => code.replace(/[^A-Za-z0-9._-]+/g, '-');

package/dist/schema.js

@@ -1,6 +1,6 @@
 // The schema of a noun, as the contract's schema document has it (section 5.1), and what the
 // engine makes of it: for every verb, the flags it takes and where each one goes (body, query or
-// filter). A plain noun (markets, orders, carts, about 60 of them) has no code in the CLI: its
+// filter). A plain noun (markets, orders, payments, about 60 of them) has no code in the CLI: its
 // schema is read from GET /v1/schema/<noun>. Built-in nouns (sandbox, loops, report) write theirs
 // in the same document format, so one reader serves both.
 import { closest, fail, fixWith } from './errors.js';
@@ -53,6 +53,7 @@ export function parseSchema(raw, expected) {
             method,
             id: v.path ? /\{[^}]+\}/.test(v.path) : !['list', 'create'].includes(name),
             destructive,
+            confirm: destructive || v.confirm === true,
             // A policy never deletes nor returns money, whatever else the document says.
             loopable: Boolean(v.loopable) && !v.deletes && !v.returns_money && name !== 'delete',
             live: v.live !== false,
@@ -102,7 +103,9 @@ function fileInputs(flags, fields, body) {
             type: 'string',
             to: 'local',
             input: { kind: 'document', target: k, required: Boolean(flags[k].required), target_type: flags[k].type },
-            description: `A JSON file with ${k}, in place of ${toFlag(k)}.`,
+            description: flags.format?.values?.includes('csv')
+                ? `A file with ${k}, in place of ${toFlag(k)}: JSON, or CSV with --format csv or a name ending in .csv.`
+                : `A JSON file with ${k}, in place of ${toFlag(k)}.`,
         };
     }
 }
@@ -115,7 +118,7 @@ function listFlags(flags, fields, doc) {
             if (op === 'in')
                 flags[key] = { ...base, type: 'array', items: f.type === 'array' ? f.items : f.type, filter: { field: f.name, op } };
             else if (op === 'null')
-                flags[key] = { ...base, type: 'boolean', values: undefined, filter: { field: f.name, op } };
+                flags[key] = { ...base, type: 'boolean', values: undefined, known: undefined, filter: { field: f.name, op } };
             else
                 flags[key] = { ...base, filter: { field: f.name, op } };
         }
@@ -144,11 +147,15 @@ function flag(f, to, required) {
         type: f.type,
         to,
         ...(f.values ? { values: f.values } : {}),
+        ...(Array.isArray(f.known) && f.known.length ? { known: f.known } : {}),
         ...(f.items ? { items: f.items } : {}),
-        ...(f.properties?.length ? { properties: Object.fromEntries(f.properties.map((p) => [p.name, { type: p.type, ...(p.values ? { values: p.values } : {}) }])) } : {}),
+        ...(f.properties?.length ? { properties: Object.fromEntries(f.properties.map((p) => [p.name, { type: p.type, ...(p.values ? { values: p.values } : {}), ...(p.required ? { required: true } : {}) }])) } : {}),
         ...(f.noun ? { noun: f.noun } : {}),
+        ...(f.nullable !== undefined ? { nullable: f.nullable } : {}),
         ...(required ? { required: true } : {}),
         ...(f.description ? { description: f.description } : {}),
+        ...(typeof f.repeat === 'string' && f.repeat ? { repeat: f.repeat } : {}),
+        ...(f.bare ? { bare: true } : {}),
     };
 }
 function bad(noun, why) {
@@ -180,3 +187,7 @@ export function verbOf(schema, verb) {
     }
     return v;
 }
+/** A body flag that null clears: a field marked nullable, or a ref unless marked nullable: false. */
+export function clearable(f) {
+    return f.to === 'body' && (f.nullable === true || (f.type === 'ref' && f.nullable !== false));
+}

package/dist/schemas.js

@@ -2,28 +2,91 @@
 // one (contract section 5), cached on disk for a few minutes so a command costs one request, not
 // two. Schemas are the same at every state, so no token is sent. C11R_SCHEMA_CACHE=0 turns the
 // cache off.
+//
+// A deploy can change a schema inside those minutes. Every answer carries C11R-Schema, the hash of
+// the schemas served: an entry records the one it was loaded with, and an answer with another
+// drops the cache. The engine then runs the command once more on fresh schemas when the API
+// refused it (refusedBySchema). Without the header, a refusal that a stale schema explains
+// (confirmation_required, unknown_field, unknown_verb) does the same.
 import crypto from 'node:crypto';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { CliError, closest, fail, fixWith } from './errors.js';
-import { apiUrl, request } from './http.js';
+import { apiUrl, request, watchSchemaHeader } from './http.js';
 import { parseSchema } from './schema.js';
 import { VERSION } from './version.js';
 const TTL_MS = 10 * 60_000;
-function cacheFile(key) {
+function cacheDir() {
     if (process.env.C11R_SCHEMA_CACHE === '0')
         return null;
     const base = process.env.XDG_CACHE_HOME || path.join(os.homedir(), '.cache');
     const host = crypto.createHash('sha256').update(apiUrl()).digest('hex').slice(0, 12);
-    return path.join(base, 'c11r', `schema-${VERSION}-${host}`, `${key}.json`);
+    return path.join(base, 'c11r', `schema-${VERSION}-${host}`);
+}
+/** This process: the header last seen, the versions of the cache entries used, and whether to skip the cache. */
+const seen = { header: null, used: new Set(), fromCache: false, stale: false, fresh: false, written: null };
+/** The hash the cache on disk was written under, in its own file: any answer can check it, whatever the command read. */
+const HASH_FILE = '_hash';
+watchSchemaHeader((version) => {
+    seen.header = version;
+    // Schemas this command read from the cache, under another hash: the refusal may be theirs.
+    if (seen.fromCache && [...seen.used].some((v) => v !== version))
+        seen.stale = true;
+    // The cache on disk, under another hash (or none recorded): gone, whatever this command read.
+    const dir = cacheDir();
+    if (!dir || seen.written === version)
+        return;
+    let names;
+    try {
+        names = fs.readdirSync(dir);
+    }
+    catch {
+        return;
+    }
+    const hash = names.includes(HASH_FILE) ? fs.readFileSync(path.join(dir, HASH_FILE), 'utf8').trim() : null;
+    if (hash !== version && names.some((n) => n.endsWith('.json')))
+        dropSchemaCache();
+});
+/** Every cached schema of this API, gone: the next command loads them again. */
+export function dropSchemaCache() {
+    const dir = cacheDir();
+    if (dir)
+        fs.rmSync(dir, { recursive: true, force: true });
+}
+/**
+ * Whether a refusal may come from a schema older than the API's: one was served from the cache,
+ * and the API's header says the schemas changed, or, with no header, the refusal is one a stale
+ * schema explains. The caller then refreshes (refreshSchemas) and runs the command once more.
+ */
+export function refusedBySchema(code) {
+    if (!seen.fromCache || seen.fresh)
+        return false;
+    if (seen.stale)
+        return true;
+    return seen.header === null && STALE_CODES.has(code);
+}
+const STALE_CODES = new Set(['confirmation_required', 'unknown_field', 'unknown_verb']);
+/** From now on, in this process, schemas come from the API, and the cache is rewritten. */
+export function refreshSchemas() {
+    dropSchemaCache();
+    seen.fresh = true;
+    seen.fromCache = false;
+    seen.used.clear();
 }
 async function cached(key, load) {
-    const file = cacheFile(key);
-    if (file) {
+    const dir = cacheDir();
+    const file = dir ? path.join(dir, `${key}.json`) : null;
+    if (file && !seen.fresh) {
         try {
-            if (Date.now() - fs.statSync(file).mtimeMs < TTL_MS)
-                return JSON.parse(fs.readFileSync(file, 'utf8'));
+            if (Date.now() - fs.statSync(file).mtimeMs < TTL_MS) {
+                const entry = JSON.parse(fs.readFileSync(file, 'utf8'));
+                if (entry && typeof entry === 'object' && 'value' in entry) {
+                    seen.fromCache = true;
+                    seen.used.add(entry.version ?? null);
+                    return entry.value;
+                }
+            }
         }
         catch {
             // Not cached, or unreadable: load it.
@@ -33,7 +96,18 @@ async function cached(key, load) {
     if (file) {
         try {
             fs.mkdirSync(path.dirname(file), { recursive: true });
-            fs.writeFileSync(file, JSON.stringify(value));
+            // Written under another hash than the files there: those go first, so the cache is one hash.
+            if (seen.header && seen.written !== seen.header) {
+                const hashFile = path.join(path.dirname(file), HASH_FILE);
+                const hash = fs.existsSync(hashFile) ? fs.readFileSync(hashFile, 'utf8').trim() : null;
+                if (hash !== seen.header) {
+                    dropSchemaCache();
+                    fs.mkdirSync(path.dirname(file), { recursive: true });
+                    fs.writeFileSync(hashFile, seen.header);
+                }
+                seen.written = seen.header;
+            }
+            fs.writeFileSync(file, JSON.stringify({ version: seen.header, value }));
         }
         catch {
             // A read-only home is fine: no cache.

package/dist/secrets.js

@@ -14,6 +14,8 @@ import os from 'node:os';
 import path from 'node:path';
 import { markOutWritten } from './config.js';
 import { fail } from './errors.js';
+/** Where the record's id goes in a file named after it, once the answer gives the id. */
+const ID_SLOT = '<id>';
 export function secretsDir() {
     const base = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config');
     return path.join(base, 'c11r', 'secrets');
@@ -23,10 +25,14 @@ const safe = (s) => s.toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^-+|
 export function planSecret(opts) {
     const out = opts.values.out;
     const format = opts.values.format ?? null;
-    const base = opts.verb === 'token' ? `${safe(opts.id ?? 'credential')}-token` : safe(String(opts.values.name ?? opts.id ?? 'credential'));
+    // By the name given, else the id given; a record with neither (a gift card) by the id it is
+    // given, so each has a file of its own: gift-card-<id>.env.
+    const named = opts.values.name ?? opts.id;
+    const byRecord = !out && opts.verb !== 'token' && (named === undefined || named === null || named === '');
+    const base = opts.verb === 'token' ? `${safe(opts.id ?? 'credential')}-token` : byRecord ? `${safe(opts.noun.replace(/s$/, ''))}-${ID_SLOT}` : safe(String(named));
     const file = out ? path.resolve(out) : path.join(secretsDir(), safe(opts.org ?? 'default'), base);
-    const plan = { file: out || !format ? file : `${file}.${format}`, format, fixed: Boolean(out), overwrite: opts.yes };
-    const candidates = plan.fixed || format ? [plan.file] : [`${file}.env`, `${file}.json`];
+    const plan = { file: out || !format ? file : `${file}.${format}`, format, fixed: Boolean(out), overwrite: opts.yes, byRecord };
+    const candidates = byRecord ? [] : plan.fixed || format ? [plan.file] : [`${file}.env`, `${file}.json`];
     for (const c of candidates) {
         let st = null;
         try {
@@ -43,7 +49,7 @@ export function planSecret(opts) {
             fail('conflict', `${c} exists. c11r replaces it only with --yes, or writes the secret elsewhere with --out.`, { path: 'out', next_step: { action: 'fix_request', command: null }, details: { file: c } }, 'rejected');
         }
     }
-    const dir = path.dirname(candidates[0]);
+    const dir = path.dirname(plan.file);
     const existing = nearestExisting(dir);
     try {
         fs.accessSync(existing, fs.constants.W_OK);
@@ -74,7 +80,7 @@ export function writeSecret(r, plan, ctx) {
     const credentialId = str(rec.id) ?? ctx.id;
     const record = { noun: ctx.noun, id: credentialId ?? null, name: str(rec.name), code: str(rec.code) };
     const format = plan.format ?? (secret.format === 'json' ? 'json' : 'env');
-    const file = plan.fixed || plan.format ? plan.file : `${plan.file}.${format}`;
+    const file = byRecordFile(plan.fixed || plan.format ? plan.file : `${plan.file}.${format}`, plan, credentialId);
     const env = secret.env && Object.keys(secret.env).length ? { ...secret.env } : { [`CL_${(secret.kind ?? 'secret').toUpperCase()}`]: String(secret.value ?? '') };
     // The endpoint goes with every secret, so the file is enough to call Commerce Layer.
     if (!env.CL_BASE_ENDPOINT && typeof data.base_endpoint === 'string')
@@ -97,9 +103,9 @@ export function writeSecret(r, plan, ctx) {
         const created = ctx.verb === 'create';
         fail('secret_not_written', `The API answered the ${secret.kind ?? 'secret'} of credential ${id} once, and c11r could not write it to ${file}: ${e.message}. It was not printed, and the API cannot show it again. ${created ? `c11r credentials token ${id} gives a working token now; for a new secret, create another credential and delete ${id}.` : `c11r credentials token ${id} gives another token.`}`, { path: 'out', next_step: { action: 'fix_request', command: `c11r credentials token ${id}` }, details: { credential_id: credentialId ?? null, file } });
     }
-    // An --out file is not removed with its credential: remember that one exists, for the warning.
+    // An --out file is not removed with its record: remember which record has one, for the warning.
     if (plan.fixed && ctx.org)
-        markOutWritten(ctx.org, true);
+        markOutWritten(ctx.org, { noun: ctx.noun, keys: [record.id, record.name, record.code, ctx.id].filter((k) => typeof k === 'string' && k !== '') });
     // The API says the secret is shown once: c11r kept it in the file, and printed none of it.
     const warnings = r.warnings.filter((w) => w.code !== 'secret_shown_once' && w.code !== 'token_shown_once');
     if (!ignoredByGit(file))
@@ -111,6 +117,18 @@ export function writeSecret(r, plan, ctx) {
         warnings,
     };
 }
+/** A file named after its record: the id in its slot, and a file there already left alone. */
+function byRecordFile(file, plan, id) {
+    if (!plan.byRecord)
+        return file;
+    // The id as the API gives it, case kept: ids are case-sensitive (lqgwUkXlBw).
+    const slot = (id ?? crypto.randomBytes(4).toString('hex')).replace(/[^A-Za-z0-9._-]+/g, '-').replace(/^[.-]+/, '') || crypto.randomBytes(4).toString('hex');
+    const named = file.replace(ID_SLOT, slot);
+    if (plan.overwrite || !fs.existsSync(named))
+        return named;
+    const ext = path.extname(named);
+    return `${named.slice(0, -ext.length || undefined)}-${crypto.randomBytes(3).toString('hex')}${ext}`;
+}
 /** What a dry run says about the file: where it would go and whether one is there. */
 export function describePlan(plan) {
     const files = plan.fixed || plan.format ? [plan.file] : [`${plan.file}.env`, `${plan.file}.json`];