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

package/dist/builtins/skills.js

@@ -0,0 +1,355 @@
+// c11r skills sync: local copies of the skills, from the list the site publishes (skills.md), so
+// any coding agent in the project finds them. State none: no token, no organization, no call to
+// the API; only commercelayer.ai.
+//
+//   <project>/.claude/skills/<name>/SKILL.md   one per skill, as the site serves it
+//   <project>/.claude/skills/.c11r-skills.json  the manifest: what sync wrote, by version and hash
+//   <project>/AGENTS.md                         a marked block listing them, for other agents
+//
+// Only what the index version changed is fetched, with the index itself a conditional GET. A copy
+// whose bytes are not what sync wrote is the person's edit: it is never replaced or deleted
+// without --yes. Folders sync did not write are never touched.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { findUp, LINK_FILE } from '../config.js';
+import { CliError, fail } from '../errors.js';
+import { envelope } from '../http.js';
+import { parseSchema } from '../schema.js';
+import { USER_AGENT } from '../version.js';
+const INDEX_URL = 'https://commercelayer.ai/skills.md';
+const SKILLS_DIR = path.join('.claude', 'skills');
+const MANIFEST = '.c11r-skills.json';
+const AGENTS_FILE = 'AGENTS.md';
+const START = '<!-- c11r skills: start -->';
+const END = '<!-- c11r skills: end -->';
+const NAME = /^[a-z0-9][a-z0-9-]*$/;
+const TIMEOUT_MS = 30_000;
+/** Up to this many skills added, updated or removed are listed; past it, only the count unless --verbose. */
+const LISTED = 10;
+export const skills = {
+    schema: parseSchema({
+        noun: 'skills',
+        group: 'setup',
+        kind: 'task',
+        description: 'The local copies of the Commerce Layer skills, in the project folder, where coding agents load them: .claude/skills/<name>/SKILL.md, and a list of them in AGENTS.md.',
+        verbs: [
+            {
+                verb: 'sync',
+                method: 'POST',
+                path: '/skills/sync',
+                state: 'none',
+                live: false,
+                body: [
+                    { name: 'except', type: 'array', items: 'string', description: 'A skill not to keep a copy of, repeated. Remembered: later syncs leave it out too.' },
+                    { name: 'include', type: 'array', items: 'string', description: 'A skill left out with --except to keep a copy of again, repeated.' },
+                    { name: 'verbose', type: 'boolean', description: `Lists every skill added, updated and removed. Without it, a list longer than ${LISTED} is only its count.` },
+                ],
+                effect: 'Brings the copies up to date with the index at commercelayer.ai: fetches only the skills whose version changed, adds new ones, removes the ones the index dropped, and keeps the list in AGENTS.md (creating the file when there is none). A copy edited on this machine is kept as it is; replacing or removing it needs the human\'s yes. Answers added, updated and removed as a count with the skills when there are few, every edited copy, and how many are unchanged. With --dry-run it reads only the index and writes nothing.',
+            },
+        ],
+    }),
+    defaultVerb: 'sync',
+    async run(run) {
+        return sync(run);
+    },
+};
+// ---------- the site
+function indexUrl() {
+    const given = process.env.C11R_SKILLS_URL;
+    if (!given)
+        return INDEX_URL;
+    let u;
+    try {
+        u = new URL(given);
+    }
+    catch {
+        fail('invalid_config', `C11R_SKILLS_URL ${given} is not a URL.`);
+    }
+    if (!['localhost', '127.0.0.1'].includes(u.hostname))
+        fail('invalid_config', `C11R_SKILLS_URL is for a test site on localhost only, not ${u.host}.`);
+    return u.toString();
+}
+const unavailable = (message) => new CliError({ code: 'site_unavailable', message, required_state: null, required_plan: null, missing: null, path: null, next_step: { action: 'retry_later', command: null, url: null } }, 'unavailable');
+async function get(url, etag) {
+    let res;
+    try {
+        res = await fetch(url, { headers: { 'user-agent': USER_AGENT, accept: 'text/markdown', ...(etag ? { 'if-none-match': etag } : {}) }, signal: AbortSignal.timeout(TIMEOUT_MS) });
+    }
+    catch (e) {
+        throw unavailable(`${new URL(url).host} could not be reached: ${e.message}. The local copies are unchanged and still usable.`);
+    }
+    if (res.status !== 200 && res.status !== 304)
+        throw unavailable(`${url} answered ${res.status}. The local copies are unchanged and still usable.`);
+    return { status: res.status, etag: res.headers.get('etag'), text: res.status === 200 ? await res.text() : '' };
+}
+/** The index lines: - [name](url) VERSION, state ..., plan ...[, requires ...]: description. */
+function parseIndex(text, from) {
+    const origin = new URL(from).origin;
+    const entries = [];
+    const skipped = [];
+    for (const line of text.split('\n')) {
+        const m = line.match(/^- \[([^\]]+)\]\((\S+)\) (\d+\.\d+\.\d+\S*?),[^:]*: (.*)$/);
+        if (!m)
+            continue;
+        const [, name, link, version, description] = m;
+        let u = null;
+        try {
+            u = new URL(link, from);
+        }
+        catch {
+            u = null;
+        }
+        if (!NAME.test(name) || !u || u.origin !== origin || !u.pathname.startsWith('/skills/')) {
+            skipped.push(name);
+            continue;
+        }
+        if (!entries.some((e) => e.name === name))
+            entries.push({ name, version, url: u.toString(), description: description.trim() });
+    }
+    return { entries, version: frontmatter(text).version ?? null, skipped };
+}
+function frontmatter(text) {
+    const m = text.match(/^---\n([\s\S]*?)\n---/);
+    const out = {};
+    for (const line of m?.[1].split('\n') ?? []) {
+        const kv = line.match(/^([a-z_]+):\s*(.*)$/);
+        if (kv)
+            out[kv[1]] = kv[2].replace(/^"(.*)"$/, '$1').trim();
+    }
+    return out;
+}
+// ---------- this machine
+const sha = (s) => crypto.createHash('sha256').update(s).digest('hex');
+const readOr = (file) => {
+    try {
+        return fs.readFileSync(file, 'utf8');
+    }
+    catch {
+        return null;
+    }
+};
+function readManifest(file) {
+    const raw = readOr(file);
+    if (raw === null)
+        return null;
+    try {
+        const m = JSON.parse(raw);
+        return { index: { url: m.index?.url ?? INDEX_URL, version: m.index?.version ?? null, etag: m.index?.etag ?? null, entries: m.index?.entries ?? [] }, skills: m.skills ?? {}, except: m.except ?? [] };
+    }
+    catch {
+        fail('invalid_config', `${file} is not JSON: c11r skills sync writes it, and it was changed by hand.`);
+    }
+}
+function writeAtomic(file, text) {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const tmp = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, text);
+    fs.renameSync(tmp, file);
+}
+const firstSentence = (d) => {
+    const i = d.indexOf('. ');
+    return i === -1 ? d : d.slice(0, i + 1);
+};
+function agentsBlock(entries, rel) {
+    const link = (n) => `${rel}/${n}/SKILL.md`;
+    const lines = [
+        START,
+        '## Commerce Layer skills',
+        '',
+        `Local copies of the Commerce Layer skills, from ${INDEX_URL}, kept up to date by \`c11r skills sync\`. When a skill's task comes, load its copy.`,
+        '',
+        ...entries.map((e) => `- [${e.name}](${link(e.name)}): ${firstSentence(e.description)}`),
+        END,
+    ];
+    return lines.join('\n');
+}
+/** AGENTS.md with the block put in or replaced; nothing outside the markers changes. */
+function withBlock(current, block) {
+    if (current === null)
+        return `${block}\n`;
+    const a = current.indexOf(START);
+    const b = current.indexOf(END);
+    if (a !== -1 && b > a)
+        return current.slice(0, a) + block + current.slice(b + END.length);
+    return `${current.replace(/\n*$/, '')}\n\n${block}\n`;
+}
+// ---------- sync
+async function sync(run) {
+    const v = run.parsed.values;
+    const dryRun = run.globals.dryRun;
+    // The project root: where the copies already are, the folder's link or store files, a git
+    // repository's root, else here.
+    const root = findUp([path.join(SKILLS_DIR, MANIFEST)]) ?? findUp([LINK_FILE]) ?? findUp(['store.yml', 'loops.yml']) ?? findUp(['.git']) ?? process.cwd();
+    const dir = path.join(root, SKILLS_DIR);
+    const manifestFile = path.join(dir, MANIFEST);
+    const from = indexUrl();
+    const before = readManifest(manifestFile);
+    const manifest = before ?? { index: { url: from, version: null, etag: null, entries: [] }, skills: {}, except: [] };
+    const warnings = [];
+    const except = v.except ?? [];
+    const include = v.include ?? [];
+    const verbose = v.verbose === true;
+    for (const n of [...except, ...include])
+        if (!NAME.test(n))
+            fail('invalid_value', `${n} is not a skill name: lowercase letters, digits and dashes, as in manage-orders.`, { path: except.includes(n) ? 'except' : 'include' });
+    const excluded = new Set([...manifest.except.filter((n) => !include.includes(n)), ...except]);
+    // The index: a 304 means the one sync last read, whose entries the manifest keeps.
+    const sameUrl = manifest.index.url === from;
+    const idx = await get(from, sameUrl && manifest.index.entries.length ? manifest.index.etag : null);
+    let entries;
+    let indexVersion;
+    if (idx.status === 304) {
+        entries = manifest.index.entries;
+        indexVersion = manifest.index.version;
+    }
+    else {
+        const parsed = parseIndex(idx.text, from);
+        if (!parsed.entries.length)
+            throw unavailable(`${from} lists no skills: it may be mid-deploy. The local copies are unchanged.`);
+        entries = parsed.entries;
+        indexVersion = parsed.version;
+        for (const n of parsed.skipped)
+            warnings.push({ code: 'skill_skipped', message: `${n} links outside ${new URL(from).origin}/skills/ in the index: not copied.` });
+    }
+    for (const n of include)
+        if (!entries.some((e) => e.name === n))
+            warnings.push({ code: 'unknown_skill', message: `${n} is not in the index.` });
+    for (const n of except)
+        if (!entries.some((e) => e.name === n) && !manifest.skills[n])
+            warnings.push({ code: 'unknown_skill', message: `${n} is not in the index.` });
+    const wanted = entries.filter((e) => !excluded.has(e.name));
+    const fileOf = (n) => path.join(dir, n, 'SKILL.md');
+    const editedNow = (n) => {
+        const kept = manifest.skills[n];
+        const text = readOr(fileOf(n));
+        return Boolean(kept && text !== null && sha(text) !== kept.sha256);
+    };
+    const added = [];
+    const updated = [];
+    const removed = [];
+    const edited = [];
+    let unchanged = 0;
+    const toFetch = [];
+    for (const e of wanted) {
+        const kept = manifest.skills[e.name];
+        const present = readOr(fileOf(e.name)) !== null;
+        if (kept && present && kept.version === e.version) {
+            // Same version: still checked, since an edit there is not what the index says either.
+            if (editedNow(e.name))
+                edited.push({ name: e.name, local: kept.version, latest: e.version });
+            else
+                unchanged++;
+            continue;
+        }
+        if (kept && present && editedNow(e.name)) {
+            edited.push({ name: e.name, local: kept.version, latest: e.version });
+            continue;
+        }
+        // A file there that sync never wrote is the person's: kept, as an edit.
+        if (!kept && present) {
+            edited.push({ name: e.name, local: frontmatter(readOr(fileOf(e.name))).version ?? 'unknown', latest: e.version });
+            continue;
+        }
+        toFetch.push(e);
+    }
+    const gone = Object.values(manifest.skills).filter((k) => !wanted.some((e) => e.name === k.name));
+    const toRemove = [];
+    for (const k of gone) {
+        if (readOr(fileOf(k.name)) === null)
+            continue;
+        if (editedNow(k.name))
+            edited.push({ name: k.name, local: k.version, latest: null });
+        else
+            toRemove.push(k);
+    }
+    // Edits are replaced or removed only on the human's yes.
+    const replaceEdits = edited.length > 0 && !dryRun && run.globals.yes;
+    if (dryRun) {
+        for (const e of toFetch)
+            (manifest.skills[e.name] && readOr(fileOf(e.name)) !== null ? updated.push({ name: e.name, from: manifest.skills[e.name].version, to: e.version }) : added.push({ name: e.name, version: e.version }));
+        for (const k of toRemove)
+            removed.push({ name: k.name, version: k.version });
+        const agentsNow = readOr(path.join(root, AGENTS_FILE));
+        const agentsNext = withBlock(agentsNow, agentsBlock(wanted, SKILLS_DIR.split(path.sep).join('/')));
+        return answer({ dry_run: true, dir, index: { url: from, version: indexVersion }, added, updated, removed, edited, unchanged, agents_md: agentsNow === null ? 'created' : agentsNow === agentsNext ? 'unchanged' : 'updated' }, warnings, edited, replaceEdits, verbose);
+    }
+    // Fetch first, write after: a cut-off sync writes nothing.
+    if (replaceEdits)
+        for (const e of edited)
+            if (e.latest)
+                toFetch.push(wanted.find((w) => w.name === e.name));
+    const bodies = new Map();
+    for (const e of toFetch) {
+        const r = await get(e.url);
+        const fm = frontmatter(r.text);
+        if (fm.name !== e.name || fm.version !== e.version) {
+            warnings.push({ code: 'skill_invalid', message: `${e.url} is ${fm.name ?? 'no skill'} ${fm.version ?? ''}, not ${e.name} ${e.version} as the index says: the local copy is unchanged.`.replace('  ', ' ') });
+            continue;
+        }
+        bodies.set(e.name, r.text);
+    }
+    for (const e of toFetch) {
+        const text = bodies.get(e.name);
+        if (text === undefined)
+            continue;
+        const kept = manifest.skills[e.name];
+        const had = readOr(fileOf(e.name)) !== null;
+        writeAtomic(fileOf(e.name), text);
+        if (kept && had)
+            updated.push({ name: e.name, from: kept.version, to: e.version });
+        else
+            added.push({ name: e.name, version: e.version });
+        manifest.skills[e.name] = { ...e, sha256: sha(text) };
+    }
+    const removeOne = (name, version) => {
+        fs.rmSync(fileOf(name), { force: true });
+        try {
+            fs.rmdirSync(path.join(dir, name));
+        }
+        catch {
+            // The folder holds something of the person's: it stays.
+        }
+        removed.push({ name, version });
+        delete manifest.skills[name];
+    };
+    for (const k of toRemove)
+        removeOne(k.name, k.version);
+    for (const k of gone)
+        if (readOr(fileOf(k.name)) === null && manifest.skills[k.name])
+            delete manifest.skills[k.name];
+    if (replaceEdits)
+        for (const e of edited)
+            if (!e.latest)
+                removeOne(e.name, e.local);
+    // Unchanged entries take the index's description, which AGENTS.md lists.
+    for (const e of wanted)
+        if (manifest.skills[e.name] && manifest.skills[e.name].version === e.version)
+            manifest.skills[e.name] = { ...manifest.skills[e.name], url: e.url, description: e.description };
+    manifest.index = { url: from, version: indexVersion, etag: idx.status === 304 ? manifest.index.etag : idx.etag, entries };
+    manifest.except = [...excluded].sort();
+    writeAtomic(manifestFile, JSON.stringify(manifest, null, 2) + '\n');
+    const listed = wanted.filter((e) => manifest.skills[e.name] || readOr(fileOf(e.name)) !== null);
+    const agentsFile = path.join(root, AGENTS_FILE);
+    const agentsNow = readOr(agentsFile);
+    const agentsNext = withBlock(agentsNow, agentsBlock(listed, SKILLS_DIR.split(path.sep).join('/')));
+    const agents_md = agentsNow === null ? 'created' : agentsNow === agentsNext ? 'unchanged' : 'updated';
+    if (agents_md !== 'unchanged')
+        writeAtomic(agentsFile, agentsNext);
+    const stillEdited = replaceEdits ? [] : edited;
+    return answer({ dir, index: { url: from, version: indexVersion }, added, updated, removed, edited: stillEdited, unchanged, agents_md }, warnings, stillEdited, replaceEdits, verbose);
+}
+function answer(data, warnings, edited, replaced, verbose) {
+    for (const k of ['added', 'updated', 'removed']) {
+        const list = data[k];
+        data[k] = verbose || list.length <= LISTED ? { count: list.length, skills: list } : { count: list.length };
+    }
+    if (!replaced) {
+        for (const e of edited) {
+            warnings.push({ code: 'skill_edited', message: `${e.name} was edited on this machine: kept as it is${e.latest ? `, while the index has ${e.latest}` : ', though the index dropped it'}. Replacing it loses those edits: ask the human first, and on their yes run the sync again with --yes.` });
+        }
+    }
+    if (data.agents_md === 'created')
+        warnings.push({ code: 'agents_md_created', message: 'AGENTS.md was created, holding only the list of skills: tell the human in one line.' });
+    return envelope(data, { warnings, next: [] });
+}

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.
@@ -110,20 +112,37 @@ export function setDefaultOrg(org) {
         delete c.default_org;
     writeCredentials(c);
 }
-export function outWritten(org) {
-    return Boolean(readCredentials().out_written?.[org]);
+/** A record's secret went to an --out file: remembered so its delete can say that file stays. */
+export function markOutWritten(org, record) {
+    const keys = record.keys.filter(Boolean);
+    if (!keys.length)
+        return;
+    const c = readCredentials();
+    const all = { ...(c.out_written ?? {}) };
+    const list = (all[org] ?? []).filter((r) => !(r.noun === record.noun && r.keys.some((k) => keys.includes(k))));
+    all[org] = [...list, { noun: record.noun, keys }];
+    c.out_written = all;
+    writeCredentials(c);
 }
-export function markOutWritten(org, written) {
+/**
+ * After a delete: whether that record had a secret written with --out, which is then forgotten.
+ * With no record named, the organization goes (sandbox destroy).
+ */
+export function forgetOutWritten(org, record) {
     const c = readCredentials();
+    const list = c.out_written?.[org] ?? [];
+    const hit = (r) => !record || (r.noun === record.noun && r.keys.some((k) => record.keys.includes(k)));
+    if (!list.some(hit))
+        return false;
+    const rest = list.filter((r) => !hit(r));
     const all = { ...(c.out_written ?? {}) };
-    if (written === Boolean(all[org]))
-        return;
-    if (written)
-        all[org] = true;
+    if (rest.length)
+        all[org] = rest;
     else
         delete all[org];
     c.out_written = all;
     writeCredentials(c);
+    return true;
 }
 export function storedBooking(id) {
     const b = readCredentials().bookings?.[id];
@@ -144,7 +163,7 @@ export function storeBooking(id, booking) {
 /** The last four characters, as the API shows them. */
 export const hintOf = (token) => `${token.slice(0, 4)}...${token.slice(-4)}`;
 /** The nearest folder, from the current one up, that holds one of the files. */
-function findUp(names, from = process.cwd()) {
+export function findUp(names, from = process.cwd()) {
     let dir = path.resolve(from);
     for (;;) {
         if (names.some((n) => fs.existsSync(path.join(dir, n))))
@@ -174,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/confirm.js

@@ -1,6 +1,7 @@
 // Confirmation for destructive verbs. --yes skips it. With a terminal, it asks on stderr and
 // reads one line. With no terminal (an agent, a pipe, a schedule) it never waits: it fails with
-// confirmation_required, and the agent asks the human, then repeats the command with --yes.
+// confirmation_required, next_step confirm with the command and --yes: the agent asks the human,
+// and runs it only on their yes.
 import readline from 'node:readline';
 import { fail } from './errors.js';
 export const terminal = {
@@ -40,17 +41,27 @@ export const terminal = {
         });
     },
 };
+/** The command the human's yes runs: the same, with --yes. */
+export const withYes = (command) => (/\s(--yes|-y)(\s|$)/.test(command) ? command : `${command} --yes`);
+/**
+ * action names what needs a yes ("Destroy sandbox"). sentence, when given, is what the human is
+ * shown instead, whole ("Sharing with shop.example.com: Ada Lovelace, ..."), and details go with
+ * the error, so the agent can show the human the same.
+ */
 export async function confirm(action, command, opts) {
     if (opts.yes)
         return;
     const p = opts.prompter ?? terminal;
+    const said = opts.sentence ? `${opts.sentence.replace(/\.?$/, '.')} This` : action;
     if (!p.interactive) {
-        // The agent asks the human; on a yes it repeats the command with --yes.
-        fail('confirmation_required', `${action} needs confirmation, and there is no terminal to ask in. Ask the human whether to go ahead.`, {
-            next_step: { action: 'fix_request', command: `${command} --yes` },
+        // The agent asks the human, and runs the command, which carries --yes, only on their yes: the
+        // action confirm is the guard (contract section 3), never fix_request.
+        fail('confirmation_required', `${said} needs the human's yes, and there is no terminal to ask in. Ask the human first, and run the command only on their yes.`, {
+            next_step: { action: 'confirm', command: withYes(command) },
+            ...(opts.details ? { details: opts.details } : {}),
         });
     }
-    const answer = (await p.ask(`${action}. Go ahead? [y/N] `)).trim().toLowerCase();
+    const answer = (await p.ask(opts.sentence ? `${opts.sentence.replace(/\.?$/, '.')} Go ahead? [y/N] ` : `${action}. Go ahead? [y/N] `)).trim().toLowerCase();
     if (answer !== 'y' && answer !== 'yes')
-        fail('confirmation_declined', `${action}: not confirmed, nothing was changed.`);
+        fail('confirmation_declined', opts.sentence ? `${opts.sentence.replace(/\.?$/, '')}: not confirmed, nothing was sent.` : `${action}: not confirmed, nothing was changed.`);
 }