@commercelayer/agent-cli 1.0.0-dev.13 → 1.0.0-dev.14

package/README.md

@@ -36,6 +36,7 @@ This is the 1.0.0 line, in development on the `clean-slate` branch. It replaces
 | `c11r auth login [--client-id] [--secret-file] [--keep-file]` | The human's own Commerce Layer login, from their Provisioning API application. See below. |
 | `c11r auth logout`, `auth switch <slug> [--global]` | Forgetting the login; the organization commands act on. |
 | `c11r shop profile\|search\|get\|ask <store>` | Reading a store that speaks UCP, as a shopping agent: what it offers, its catalog, a variant, a question. No organization. See below. |
+| `c11r skills sync` | Local copies of the Commerce Layer skills in `.claude/skills`, from the index at commercelayer.ai, listed in `AGENTS.md`. No organization. See below. |
 | `c11r shop checkout <store> [<checkout>]`, `shop order <store> <checkout>` | Buying there for the human: their details after their yes on what is shared, then the payment after their yes on the total, with the sandbox test handler only. |
 
 A loop runs a skill a Manage or Report noun's schema names in `loop.skill`, or in `loop.skills` for a noun with several (`manage-orders`, `manage-stock`, `report-sales`, `report-pending`, ...); a report loop allows no verb and only reports. create and update refuse any other skill, and any verb that loop does not list, with the allowed values. A loop policy allows verbs: a bare verb is the skill's own noun (`approve`), `<noun>.<verb>` another Manage noun's verb on the same item (`payments.capture`). Verbs that delete or return money are never open to a policy.
@@ -141,6 +142,16 @@ The CLI's own answers (help, loops.yml) have the same shape, with `state` null.
 - The CLI has no flag for card data. A store without the sandbox handler is `payment_handler_unsupported` before anything of the human's is sent, with the store's URL for the human to buy there in person.
 - With `--dry-run`, checkout answers what it would send and order the total it would pay: nothing is sent.
 
+## Skills
+
+`c11r skills sync` keeps copies of the skills in the project folder, where coding agents load them: `.claude/skills/<name>/SKILL.md`, one per skill as https://commercelayer.ai serves it, and in `AGENTS.md` a block between `<!-- c11r skills: start -->` and `<!-- c11r skills: end -->` listing them, for agents that read that file. Nothing outside the markers changes; without an `AGENTS.md`, sync creates one holding only the block, and says so with `agents_md: "created"`. The project folder is the one already holding the copies, else the one with `.c11r.json`, `store.yml` or `loops.yml`, else the git repository's root, else the current folder. It needs no organization and calls only commercelayer.ai, not the API.
+
+- It reads the index (`start.md`) with the ETag of the last sync, and fetches only the skills whose version changed. A skill the index dropped is removed. `.claude/skills/.c11r-skills.json` records what sync wrote, with each file's sha256; a folder sync did not write is never touched.
+- Every copy's sha256 is checked on each run, also when nothing new is in the index. A copy that is not what sync wrote is an edit: it is kept, neither replaced nor removed, and listed in `edited` with a `skill_edited` warning. `--yes`, on the human's yes, replaces or removes it.
+- `--except <skill>` (repeated) leaves a skill out, and later syncs remember it; `--include <skill>` takes it back.
+- A file whose name or version is not what the index says is not used (`skill_invalid`); a link off `commercelayer.ai/skills/` is skipped (`skill_skipped`).
+- The answer has `added`, `updated` (from and to), `removed`, `edited` and how many are `unchanged`. With `--dry-run` it reads only the index and writes nothing. When the site cannot be reached it is `site_unavailable` (exit 7), and the copies stay as they are.
+
 ## Environment
 
 | Variable | What it does |
@@ -152,5 +163,6 @@ The CLI's own answers (help, loops.yml) have the same shape, with `state` null.
 | `C11R_AUTH_URL` | Commerce Layer's token endpoint, `https://auth.commercelayer.io/oauth/token` by default: for tests. |
 | `C11R_TEST` | `1` marks a sandbox as a test organization, like a name starting `zztest`. |
 | `C11R_SCHEMA_CACHE` | `0` turns off the 10 minute schema cache in `~/.cache/c11r`. The cache records the `C11R-Schema` hash it was read under; an answer with another hash drops it, and a command the API refused on the old schema runs once more on the fresh one (without the header, after `confirmation_required`, `unknown_field` or `unknown_verb`). The second run asks what the fresh schema asks: it never adds `confirm=true` by itself. |
+| `C11R_SKILLS_URL` | The skills index, for a test site on localhost only: `https://commercelayer.ai/start.md` otherwise. |
 | `C11R_RETRY_CAP_S` | The longest the CLI waits before one retry, 30 by default. |
 | `C11R_TIMEOUT_MS` | How long a request may take, 30000 by default (sandbox create waits longer). |

package/dist/builtins/index.js

@@ -1,9 +1,10 @@
 // The nouns with code of their own. Each brings a schema document in the API's format, so help,
 // validation and confirmation are the engine's. report is a plain noun: the API's schema drives
-// it. skills (c11r skills sync) comes with deliverable 4.
+// it.
 import { auth } from './auth.js';
 import { loops } from './loops.js';
 import { sandbox, status } from './sandbox.js';
 import { shop } from './shop.js';
-export const builtins = { sandbox, status, loops, auth, shop };
+import { skills } from './skills.js';
+export const builtins = { sandbox, status, loops, auth, shop, skills };
 export { extensions } from './extensions.js';

package/dist/builtins/skills.js

@@ -0,0 +1,349 @@
+// c11r skills sync: local copies of the skills, from the index the site publishes (start.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/start.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;
+export const skills = {
+    schema: parseSchema({
+        noun: 'skills',
+        group: 'setup',
+        skill: 'start',
+        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.' },
+                ],
+                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, removed, edited 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 start = entries.find((e) => e.name === 'start');
+    const lines = [
+        START,
+        '## Commerce Layer skills',
+        '',
+        `Local copies of the Commerce Layer skills, kept up to date by \`c11r skills sync\`.${start ? ` Load [start](${link('start')}) first: it routes to the others.` : ''}`,
+        '',
+        ...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 ?? [];
+    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);
+    }
+    // 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);
+}
+function answer(data, warnings, edited, replaced) {
+    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

@@ -161,7 +161,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))))

package/dist/errors.js

@@ -66,6 +66,8 @@ const KIND = {
     store_unavailable: 'unavailable',
     store_refused: 'rejected',
     payment_handler_unsupported: 'rejected',
+    // The site that publishes the skills (c11r skills sync).
+    site_unavailable: 'unavailable',
 };
 /** For an API error whose code the CLI does not know: from the HTTP status. */
 export function kindOfStatus(status) {

package/package.json

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