@commercelayer/agent-cli 1.0.0-dev.0 → 1.0.0-dev.10

package/dist/project.js

@@ -0,0 +1,175 @@
+// 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.
+//
+// store.yml carries the export's meta ({ org, 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';
+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 the folder's store.yml names, or null without one. */
+export function storeFileOrg(dir = projectDir()) {
+    try {
+        const doc = YAML.parse(fs.readFileSync(path.join(dir, STORE_FILE), 'utf8'));
+        return typeof doc?.meta?.org === 'string' ? doc.meta.org : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 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, 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;
+    const changed = (rel) => {
+        const abs = path.join(dir, rel);
+        if (!fs.existsSync(abs))
+            return false;
+        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, 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, entry, dir = projectDir()) {
+    if (storeFileOrg(dir) !== org)
+        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, exported_at: v.exported_at ?? null, files: v.files && typeof v.files === 'object' ? v.files : {} };
+    }
+    catch {
+        return { org: null, 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/resources.js

@@ -21,13 +21,14 @@ export function resourceRequest(noun, verb, id, values) {
         else if (flag.to === 'local')
             continue;
         else if (flag.to === 'filter')
-            query[`filter[${flag.filter.field}][${flag.filter.op}]`] = text(value);
+            query[`filter[${flag.filter.field}][${flag.filter.op}]`] = flag.filter.op === 'in' ? inList(value) : text(value);
         else
             query[key] = text(value);
     }
     // The schema's own route when it gives one (/plans/current, /members/invite), else the grammar.
     const path = verb.path
-        ? verb.path.replace(/\{[^}]+\}/, id === undefined ? '' : encodeURIComponent(id))
+        ? // No id (one given by its id_alternative flags): the segment goes, /prices/{id}/tiers is /prices/tiers.
+            verb.path.replace(/\/\{[^}]+\}/, id === undefined ? '' : `/${encodeURIComponent(id)}`)
         : ['list', 'get', 'create', 'update', 'delete'].includes(verb.name)
             ? verb.name === 'list' || verb.name === 'create'
                 ? base
@@ -38,4 +39,7 @@ export function resourceRequest(noun, verb, id, values) {
         req.body = body;
     return req;
 }
+// An in list is joined by commas, or sent as a JSON array of strings when a value has a comma of its
+// own ("UK VAT, manual"), so the API keeps each value whole (contract 28.4).
+const inList = (v) => (Array.isArray(v) && v.some((x) => typeof x === 'string' && x.includes(',')) ? JSON.stringify(v.map(String)) : text(v));
 const text = (v) => (Array.isArray(v) ? v.join(',') : typeof v === 'object' && v !== null ? JSON.stringify(v) : String(v));

package/dist/schema.js

@@ -1,13 +1,12 @@
 // 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';
 const FIELD_TYPES = ['string', 'integer', 'number', 'money', 'boolean', 'date', 'datetime', 'enum', 'object', 'array', 'ref'];
 export const FILTER_OPS = ['eq', 'in', 'gt', 'gte', 'lt', 'lte', 'start', 'cont', 'null'];
-/** The contract's names; sandbox, the first proposal's name for an organization token, still reads. */
-const CREDENTIALS = { none: 'none', organization: 'organization', login: 'login', 'organization|login': 'organization|login', sandbox: 'organization', 'sandbox|login': 'organization|login' };
+const CREDENTIALS = { none: 'none', organization: 'organization', login: 'login', 'organization|login': 'organization|login' };
 const STANDARD = ['list', 'get', 'create', 'update', 'delete'];
 const METHOD = { list: 'GET', get: 'GET', create: 'POST', update: 'PATCH', delete: 'DELETE' };
 export function parseSchema(raw, expected) {
@@ -39,6 +38,7 @@ export function parseSchema(raw, expected) {
                 flags[f.name] = flag(f, method === 'GET' ? 'query' : 'body', Boolean(f.required || (name === 'create' && f.create === 'required')));
         for (const f of own(v.query))
             flags[f.name] = flag(f, 'query', Boolean(f.required));
+        fileInputs(flags, fields, own(v.body));
         if (v.secret) {
             flags.out = { type: 'string', to: 'local', description: 'The file the secret is written to, mode 600. By default one under ~/.config/c11r/secrets/<org>/.' };
             flags.format = { type: 'enum', to: 'local', values: ['env', 'json'], description: 'env: KEY=value lines, for a .env file; json: one JSON object. By default as the API answers it.' };
@@ -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,
@@ -60,6 +61,7 @@ export function parseSchema(raw, expected) {
             plan: v.plan ?? null,
             credential: v.credential ? CREDENTIALS[v.credential] : state === 'none' ? 'none' : 'organization',
             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') : [],
             refused: v.served === false ? { by: v.refused_by ?? 'the API' } : null,
             path: v.path ? v.path.replace(/^\/v\d+(?=\/)/, '') : null,
@@ -77,6 +79,35 @@ export function parseSchema(raw, expected) {
         doc,
     };
 }
+/**
+ * A secret field gets --<name>-file in place of its own flag: the value never sits in a command
+ * line or a shell history. A document field keeps its flag (inline JSON) and gets --file, or
+ * --<name>-file when the verb has more than one.
+ */
+function fileInputs(flags, fields, body) {
+    const doc = (k) => fields.find((f) => f.name === k) ?? body.find((f) => f.name === k);
+    const keys = Object.keys(flags).filter((k) => flags[k].to === 'body' || flags[k].to === 'query');
+    for (const k of keys.filter((k) => doc(k)?.secret_input)) {
+        const f = flags[k];
+        delete flags[k];
+        flags[`${k}_file`] = {
+            type: 'string',
+            to: 'local',
+            input: { kind: 'secret', target: k, required: Boolean(f.required), target_type: f.type },
+            description: `${f.description ? `${f.description.replace(/\.?$/, '.')} ` : ''}A file with ${k}, as JSON or KEY=value lines, readable only by its owner (mode 600). Never given as a flag value; without the file, c11r asks in a terminal. Never printed.`,
+        };
+    }
+    const docs = keys.filter((k) => flags[k] && doc(k)?.file_input);
+    for (const k of docs) {
+        flags[docs.length === 1 ? 'file' : `${k}_file`] = {
+            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)}.`,
+        };
+    }
+}
+const toFlag = (key) => `--${key.replace(/_/g, '-')}`;
 function listFlags(flags, fields, doc) {
     for (const f of fields) {
         for (const op of f.filter ?? []) {
@@ -115,8 +146,9 @@ function flag(f, to, required) {
         to,
         ...(f.values ? { values: f.values } : {}),
         ...(f.items ? { items: f.items } : {}),
-        ...(f.properties?.length ? { properties: Object.fromEntries(f.properties.map((p) => [p.name, p.type])) } : {}),
+        ...(f.properties?.length ? { properties: Object.fromEntries(f.properties.map((p) => [p.name, { type: p.type, ...(p.values ? { values: p.values } : {}) }])) } : {}),
         ...(f.noun ? { noun: f.noun } : {}),
+        ...(f.nullable !== undefined ? { nullable: f.nullable } : {}),
         ...(required ? { required: true } : {}),
         ...(f.description ? { description: f.description } : {}),
     };
@@ -150,3 +182,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);
@@ -63,21 +69,32 @@ function nearestExisting(dir) {
     }
     return d;
 }
+const RECORD_LINE = '# c11r-record: ';
 /** Writes data.secret to its file and answers the envelope without the value. */
 export function writeSecret(r, plan, ctx) {
     const data = (r.data ?? {});
     const secret = data.secret;
-    const credentialId = data.credential?.id ?? data.id ?? ctx.id;
+    // credentials answer { credential: {...}, secret }, other nouns the record itself and secret.
+    const rec = (data.credential && typeof data.credential === 'object' ? data.credential : data);
+    const str = (v) => (typeof v === 'string' || typeof v === 'number' ? String(v) : null);
+    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')
         env.CL_BASE_ENDPOINT = data.base_endpoint;
     const written = new Date().toISOString();
     const content = format === 'json'
-        ? JSON.stringify({ org: ctx.org, credential_id: credentialId ?? null, kind: secret.kind ?? null, value: secret.value ?? null, expires_at: secret.expires_at ?? null, env, written_at: written }, null, 2) + '\n'
-        : [`# ${secret.kind ?? 'secret'} of credential ${credentialId ?? '?'} in ${ctx.org ?? '?'}, written by c11r at ${written}.`, '# Keep it out of git.', ...Object.entries(env).map(([k, v]) => `${k}=${v}`), ''].join('\n');
+        ? JSON.stringify({ org: ctx.org, record, kind: secret.kind ?? null, value: secret.value ?? null, expires_at: secret.expires_at ?? null, env, written_at: written }, null, 2) + '\n'
+        : [
+            `# ${secret.kind ?? 'secret'} of ${ctx.noun} ${credentialId ?? '?'} in ${ctx.org ?? '?'}, written by c11r at ${written}.`,
+            `${RECORD_LINE}${JSON.stringify({ org: ctx.org, ...record })}`,
+            '# Keep it out of git.',
+            ...Object.entries(env).map(([k, v]) => `${k}=${v}`),
+            '',
+        ].join('\n');
     try {
         atomicWrite(file, content, plan.overwrite);
     }
@@ -86,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))
@@ -100,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`];
@@ -128,13 +157,25 @@ function ignoredByGit(file) {
 }
 /** The folder of an organization's secret files. */
 export const orgSecretsDir = (org) => path.join(secretsDir(), safe(org));
+/** The record a file in the secrets folder belongs to, or null when c11r did not write it. */
+function recordOf(text) {
+    const line = text.split('\n').find((l) => l.startsWith(RECORD_LINE));
+    try {
+        const v = line ? JSON.parse(line.slice(RECORD_LINE.length)) : JSON.parse(text).record;
+        return v && typeof v === 'object' && typeof v.noun === 'string' ? v : null;
+    }
+    catch {
+        return null;
+    }
+}
 /**
- * After credentials delete: the files c11r wrote in the organization's secrets folder for that
- * credential (its secret and its tokens), found by the credential id each file records. Files
- * written with --out elsewhere are not tracked.
+ * After a delete: the files c11r wrote in the organization's secrets folder for that record (a
+ * credential's secret and tokens, a webhook's shared secret), found by the noun and the id, name
+ * or code each file records. Files written with --out elsewhere are not tracked.
  */
-export function removeCredentialFiles(org, credentialId) {
+export function removeRecordFiles(org, noun, keys) {
     const dir = orgSecretsDir(org);
+    const wanted = new Set(keys.filter((k) => typeof k === 'string' && k !== ''));
     let names;
     try {
         names = fs.readdirSync(dir);
@@ -154,26 +195,18 @@ export function removeCredentialFiles(org, credentialId) {
         catch {
             continue;
         }
-        let mine = text.startsWith('#') && new RegExp(`^# \\S+ of credential ${credentialId.replace(/[^\w-]/g, '')} in `).test(text);
-        if (!mine) {
-            try {
-                mine = JSON.parse(text).credential_id === credentialId;
-            }
-            catch {
-                // Not JSON, not ours.
-            }
-        }
-        if (mine) {
-            fs.rmSync(file);
-            removed.push(file);
-        }
+        const rec = recordOf(text);
+        if (!rec || rec.noun !== noun || ![rec.id, rec.name, rec.code].some((k) => k !== null && wanted.has(k)))
+            continue;
+        fs.rmSync(file);
+        removed.push(file);
     }
     if (removed.length) {
         try {
             fs.rmdirSync(dir);
         }
         catch {
-            // Not empty: other credentials' files stay.
+            // Not empty: other records' files stay.
         }
     }
     return removed;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@commercelayer/agent-cli",
-  "version": "1.0.0-dev.0",
+  "version": "1.0.0-dev.10",
   "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": [