@commercelayer/agent-cli 0.5.1 → 0.7.0

package/dist/cursor.js

@@ -0,0 +1,31 @@
+// A small JSON state file under .commercelayer/ that a command rewrites on every run (the ops
+// cursor, the inbox cursor): read with defaults when missing or broken, kept out of git from
+// its first write, like the credentials.
+import fs from 'node:fs';
+import path from 'node:path';
+import { ignorePath } from './files.js';
+/** At most this many ids are remembered, newest first. */
+export const MAX_SEEN = 500;
+/** A cursor in `file`: parse turns what was read (or undefined when unreadable) into T. */
+export function jsonCursor(file, parse) {
+    return {
+        file,
+        read() {
+            try {
+                const raw = JSON.parse(fs.readFileSync(file, 'utf8'));
+                return parse(raw && typeof raw === 'object' && !Array.isArray(raw) ? raw : undefined);
+            }
+            catch {
+                return parse(undefined);
+            }
+        },
+        write(value) {
+            fs.mkdirSync(path.dirname(file), { recursive: true });
+            if (!fs.existsSync(file))
+                ignorePath(file);
+            fs.writeFileSync(file, JSON.stringify(value, null, 2) + '\n');
+        },
+    };
+}
+/** The strings of a list read back from a cursor file, at most MAX_SEEN. */
+export const strings = (v) => (Array.isArray(v) ? v.filter((x) => typeof x === 'string').slice(0, MAX_SEEN) : []);

package/dist/files.js

@@ -53,12 +53,14 @@ export function requireCredentials() {
     return c;
 }
 /** Make sure .gitignore lists the credentials file. Returns true if it changed. */
-export function ignoreCredentials() {
+export const ignoreCredentials = () => ignorePath(paths.credentials);
+/** Add a path to .gitignore unless it is there; whether it was added. */
+export function ignorePath(file) {
     const existing = fs.existsSync('.gitignore') ? fs.readFileSync('.gitignore', 'utf8') : '';
-    if (existing.split('\n').includes(paths.credentials))
+    if (existing.split('\n').includes(file))
         return false;
     const sep = existing && !existing.endsWith('\n') ? '\n' : '';
-    fs.appendFileSync('.gitignore', `${sep}${paths.credentials}\n`);
+    fs.appendFileSync('.gitignore', `${sep}${file}\n`);
     return true;
 }
 /** The note that sends a future agent in this repo to the skills. No skill names: it never goes stale. */

package/dist/inbox/cursor.js

@@ -0,0 +1,11 @@
+// What the inbox commands remember between runs, in .commercelayer/inbox.json (gitignored):
+// when the inbox was last listed, and the messages already pulled, by Message-ID (or by id
+// when a message has none), so inbox list marks only the others as new.
+import path from 'node:path';
+import { jsonCursor, MAX_SEEN, strings } from '../cursor.js';
+import { paths } from '../files.js';
+const cursor = () => jsonCursor(path.join(paths.dir, 'inbox.json'), (c) => ({ last_check: typeof c?.last_check === 'string' ? c.last_check : null, seen: strings(c?.seen) }));
+export const readInboxCursor = () => cursor().read();
+export const writeInboxCursor = (c) => cursor().write({ last_check: c.last_check, seen: c.seen.slice(0, MAX_SEEN) });
+/** The key a message is remembered by. */
+export const seenKey = (m) => m.message_id ?? `id:${m.id}`;

package/dist/inbox/fake.js

@@ -0,0 +1,95 @@
+// A mailbox for tests (C11R_IMAP_FAKE=<dir>): the .eml files in the folder are the messages,
+// their id the file name's number (or the position), and flags.json keeps what IMAP would: seen,
+// labels, the folder a message was moved to. "gmail": true in flags.json makes labels Gmail
+// labels; "keywords": false makes a server with neither, which can only move.
+import fs from 'node:fs';
+import path from 'node:path';
+import { fail } from '../output.js';
+import { keywordOk } from './mailbox.js';
+import { parseMessage } from './message.js';
+export function openFake(dir, folder) {
+    const stateFile = path.join(dir, 'flags.json');
+    const read = () => {
+        const s = fs.existsSync(stateFile) ? JSON.parse(fs.readFileSync(stateFile, 'utf8')) : {};
+        return { ...s, messages: s.messages ?? {} };
+    };
+    const save = (s) => fs.writeFileSync(stateFile, JSON.stringify(s, null, 2) + '\n');
+    const files = () => fs
+        .readdirSync(dir)
+        .filter((f) => f.endsWith('.eml'))
+        .sort()
+        .map((f, i) => ({ id: /^\d+\.eml$/.test(f) ? String(Number(f.slice(0, -4))) : String(i + 1), file: path.join(dir, f) }));
+    const here = (s) => files().filter((m) => (s.messages[m.id]?.folder ?? 'INBOX') === folder);
+    const one = (id) => {
+        const s = read();
+        const m = here(s).find((x) => x.id === id);
+        return { s, m, st: (s.messages[id] ??= { flags: [], labels: [] }) };
+    };
+    const labelsOf = (s, id) => (s.gmail ? (s.messages[id]?.labels ?? []) : (s.messages[id]?.flags ?? []).filter((f) => !f.startsWith('\\')));
+    return {
+        host: 'fake',
+        user: 'orders@example.com',
+        folder,
+        async check() {
+            const s = read();
+            const all = here(s);
+            return { exists: all.length, unseen: all.filter((m) => !s.messages[m.id]?.flags.includes('\\Seen')).length };
+        },
+        async list({ unseen, since, limit }) {
+            const s = read();
+            const out = [];
+            for (const m of here(s)) {
+                const seen = s.messages[m.id]?.flags.includes('\\Seen') ?? false;
+                if (unseen && seen)
+                    continue;
+                const p = await parseMessage(fs.readFileSync(m.file));
+                if (since && p.date && Date.parse(p.date) < since.getTime())
+                    continue;
+                out.push({ id: m.id, message_id: p.message_id, from: p.from, subject: p.subject, date: p.date, seen, labels: labelsOf(s, m.id), size: fs.statSync(m.file).size });
+            }
+            return out.sort((a, b) => Number(b.id) - Number(a.id)).slice(0, limit);
+        },
+        async fetch(id) {
+            const { s, m } = one(id);
+            return m ? { raw: fs.readFileSync(m.file), labels: labelsOf(s, id) } : null;
+        },
+        async tag(id, t) {
+            const { s, m, st } = one(id);
+            if (!m)
+                fail('not_found', `There is no message ${id} in ${folder}.`, 'Run `c11r inbox list` for the ids.');
+            const r = { id, labels_as: null, labeled: [], unlabeled: [], seen: false };
+            if (t.label.length || t.unlabel.length) {
+                if (s.gmail) {
+                    r.labels_as = 'gmail_label';
+                    st.labels = [...new Set([...st.labels, ...t.label])].filter((l) => !t.unlabel.includes(l));
+                }
+                else if (s.keywords !== false) {
+                    const bad = [...t.label, ...t.unlabel].find((l) => !keywordOk(l));
+                    if (bad)
+                        fail('invalid_argument', `${bad} cannot be a keyword on fake: no spaces, parentheses, quotes or backslashes.`, 'Use a one-word label (ordered, order-pending), or --move <folder>.');
+                    r.labels_as = 'keyword';
+                    st.flags = [...new Set([...st.flags, ...t.label])].filter((l) => !t.unlabel.includes(l));
+                }
+                else if (!t.move)
+                    fail('labels_unsupported', `fake keeps no labels or keyword flags in ${folder}.`, 'Move the email to a folder instead: c11r inbox tag <id> --move <folder> [--seen].');
+                else
+                    r.notes = [`fake keeps no labels or keywords: the email was moved to ${t.move} instead${t.unlabel.length ? ', and there was nothing to remove' : ''}.`];
+                if (r.labels_as) {
+                    r.labeled = t.label;
+                    r.unlabeled = t.unlabel;
+                }
+            }
+            if (t.seen) {
+                st.flags = [...new Set([...st.flags, '\\Seen'])];
+                r.seen = true;
+            }
+            if (t.move) {
+                st.folder = t.move;
+                r.moved_to = t.move;
+            }
+            save(s);
+            return r;
+        },
+        async close() { },
+    };
+}

package/dist/inbox/imap.js

@@ -0,0 +1,139 @@
+// The inbox over IMAP with imapflow, loaded only here: the other commands never pay for it.
+// Gmail keeps labels (X-GM-EXT-1); other servers keep keyword flags when the folder allows any
+// (\*); a server with neither can only move the message to a folder.
+import { fail } from '../output.js';
+import { keywordOk } from './mailbox.js';
+const who = (list) => {
+    const a = list?.[0];
+    if (!a?.address)
+        return null;
+    return a.name ? `${a.name} <${a.address}>` : a.address;
+};
+export async function openImap(s) {
+    const { ImapFlow } = await import('imapflow');
+    // What an error may say: never the password, even if a server echoes it.
+    const clean = (msg) => (s.password ? msg.split(s.password).join('***') : msg);
+    const unreachable = (e) => {
+        const err = e;
+        const reason = clean(err.responseText || err.message || String(e));
+        const auth = err.authenticationFailed || /auth|credentials|login/i.test(reason);
+        fail('inbox_unreachable', `Could not open ${s.folder} on ${s.host}:${s.port} as ${s.user}: ${reason}`, auth
+            ? 'Check C11R_IMAP_USER and C11R_IMAP_PASSWORD in .commercelayer/credentials with the human: Gmail needs IMAP on and an app password (https://myaccount.google.com/apppasswords), not the account password.'
+            : 'Check C11R_IMAP_HOST and C11R_IMAP_PORT (993) in .commercelayer/credentials, and that this machine is online.');
+    };
+    const client = new ImapFlow({ host: s.host, port: s.port, secure: s.port !== 143, auth: { user: s.user, pass: s.password }, logger: false });
+    // An error after connecting (a dropped socket) must not crash the process.
+    client.on('error', () => { });
+    try {
+        await client.connect();
+    }
+    catch (e) {
+        unreachable(e);
+    }
+    let lock;
+    try {
+        lock = await client.getMailboxLock(s.folder);
+    }
+    catch (e) {
+        await client.logout().catch(() => { });
+        fail('inbox_unreachable', `There is no folder ${s.folder} on ${s.host} for ${s.user}: ${clean(e.message)}`, 'Set C11R_IMAP_FOLDER in .commercelayer/credentials to an existing folder, or leave it out for INBOX.');
+    }
+    const gmail = client.capabilities.has('X-GM-EXT-1');
+    const mailbox = () => (client.mailbox ? client.mailbox : undefined);
+    const envelopeOf = (m) => ({
+        id: String(m.uid),
+        message_id: m.envelope?.messageId ?? null,
+        from: who(m.envelope?.from),
+        subject: m.envelope?.subject ?? null,
+        date: m.envelope?.date ? new Date(m.envelope.date).toISOString() : null,
+        seen: m.flags?.has('\\Seen') ?? false,
+        labels: gmail ? [...(m.labels ?? [])] : [...(m.flags ?? [])].filter((f) => !f.startsWith('\\') && !f.startsWith('$')),
+        ...(m.size ? { size: m.size } : {}),
+    });
+    const uidOf = (id) => {
+        if (!/^\d+$/.test(id))
+            fail('invalid_argument', `${id} is not a message id.`, 'Use the id inbox list prints (a number).');
+        return id;
+    };
+    return {
+        host: s.host,
+        user: s.user,
+        folder: s.folder,
+        async check() {
+            const st = await client.status(s.folder, { messages: true, unseen: true });
+            return { exists: st ? (st.messages ?? 0) : 0, unseen: st ? (st.unseen ?? 0) : 0 };
+        },
+        async list({ unseen, since, limit }) {
+            const query = unseen ? { seen: false } : { all: true };
+            if (since)
+                query.since = since;
+            const found = await client.search(query, { uid: true });
+            const uids = (Array.isArray(found) ? found : []).sort((a, b) => b - a).slice(0, limit);
+            if (!uids.length)
+                return [];
+            const out = [];
+            for await (const m of client.fetch(uids.join(','), { uid: true, envelope: true, flags: true, size: true, ...(gmail ? { labels: true } : {}) }, { uid: true }))
+                out.push(envelopeOf(m));
+            return out.sort((a, b) => Number(b.id) - Number(a.id));
+        },
+        async fetch(id) {
+            const m = await client.fetchOne(uidOf(id), { uid: true, source: true, flags: true, ...(gmail ? { labels: true } : {}) }, { uid: true });
+            if (!m || !m.source)
+                return null;
+            return { raw: m.source, labels: envelopeOf(m).labels };
+        },
+        async tag(id, t) {
+            const uid = uidOf(id);
+            if (!(await client.fetchOne(uid, { uid: true }, { uid: true })))
+                fail('not_found', `There is no message ${id} in ${s.folder}.`, 'Run `c11r inbox list` for the ids.');
+            const result = { id, labels_as: null, labeled: [], unlabeled: [], seen: false };
+            const notes = [];
+            if (t.label.length || t.unlabel.length) {
+                const keywords = mailbox()?.permanentFlags?.has('\\*') ?? false;
+                if (gmail) {
+                    result.labels_as = 'gmail_label';
+                    if (t.label.length)
+                        await client.messageFlagsAdd(uid, t.label, { uid: true, useLabels: true });
+                    if (t.unlabel.length)
+                        await client.messageFlagsRemove(uid, t.unlabel, { uid: true, useLabels: true });
+                }
+                else if (keywords) {
+                    const bad = [...t.label, ...t.unlabel].find((l) => !keywordOk(l));
+                    if (bad)
+                        fail('invalid_argument', `${bad} cannot be a keyword on ${s.host}: no spaces, parentheses, quotes or backslashes.`, 'Use a one-word label (ordered, order-pending), or --move <folder>.');
+                    result.labels_as = 'keyword';
+                    if (t.label.length)
+                        await client.messageFlagsAdd(uid, t.label, { uid: true });
+                    if (t.unlabel.length)
+                        await client.messageFlagsRemove(uid, t.unlabel, { uid: true });
+                }
+                else if (!t.move) {
+                    fail('labels_unsupported', `${s.host} keeps no labels or keyword flags in ${s.folder}.`, 'Move the email to a folder instead: c11r inbox tag <id> --move <folder> [--seen].');
+                }
+                else
+                    notes.push(`${s.host} keeps no labels or keywords: the email was moved to ${t.move} instead${t.unlabel.length ? ', and there was nothing to remove' : ''}.`);
+                if (result.labels_as) {
+                    result.labeled = t.label;
+                    result.unlabeled = t.unlabel;
+                }
+            }
+            if (t.seen) {
+                await client.messageFlagsAdd(uid, ['\\Seen'], { uid: true });
+                result.seen = true;
+            }
+            // Last: once moved, the message has another id in another folder.
+            if (t.move) {
+                if (!(await client.messageMove(uid, t.move, { uid: true })))
+                    fail('inbox_unreachable', `${s.host} did not move message ${id} to ${t.move}.`, 'Check that the folder exists (create it in the mail app), then try again.');
+                result.moved_to = t.move;
+            }
+            if (notes.length)
+                result.notes = notes;
+            return result;
+        },
+        async close() {
+            lock.release();
+            await client.logout().catch(() => { });
+        },
+    };
+}

package/dist/inbox/mailbox.js

@@ -0,0 +1,25 @@
+// The inbox the merchant receives orders in, over IMAP: what inbox check, list, pull and tag
+// work on. The connection details are in .commercelayer/credentials (gitignored) or the
+// environment; the password is never printed, not even in an error. C11R_IMAP_FAKE=<dir> reads
+// a folder of .eml files instead (tests).
+import { credential } from '../files.js';
+import { fail } from '../output.js';
+const CREDENTIALS_HINT = 'Ask the human to add them to .commercelayer/credentials (gitignored), one per line: C11R_IMAP_HOST=imap.gmail.com, C11R_IMAP_USER=<their address>, C11R_IMAP_PASSWORD=<an app password>, and optionally C11R_IMAP_PORT (993) and C11R_IMAP_FOLDER (INBOX). For Gmail: turn on 2-Step Verification, then create an app password at https://myaccount.google.com/apppasswords; never the account password. They write the password into the file themselves: never ask for it in the chat.';
+export function imapSettings() {
+    const missing = ['C11R_IMAP_HOST', 'C11R_IMAP_USER', 'C11R_IMAP_PASSWORD'].filter((k) => !credential(k));
+    if (missing.length)
+        fail('missing_credentials', `The inbox is not set up: ${missing.join(', ')} ${missing.length === 1 ? 'is' : 'are'} missing.`, CREDENTIALS_HINT);
+    const rawPort = credential('C11R_IMAP_PORT') ?? '993';
+    const port = Number(rawPort);
+    if (!Number.isInteger(port) || port < 1 || port > 65535)
+        fail('invalid_credentials', `C11R_IMAP_PORT is ${rawPort}, not a port.`, 'Use 993 (IMAP over TLS), the usual one, or leave it out.');
+    return { host: credential('C11R_IMAP_HOST'), port, user: credential('C11R_IMAP_USER'), password: credential('C11R_IMAP_PASSWORD'), folder: credential('C11R_IMAP_FOLDER') ?? 'INBOX' };
+}
+export async function openMailbox() {
+    const fake = process.env.C11R_IMAP_FAKE;
+    if (fake)
+        return (await import('./fake.js')).openFake(fake, credential('C11R_IMAP_FOLDER') ?? 'INBOX');
+    return (await import('./imap.js')).openImap(imapSettings());
+}
+/** An IMAP keyword is one atom: no spaces, parentheses, quotes or backslashes. */
+export const keywordOk = (name) => /^[^\s(){}%*"\\\]]+$/.test(name);

package/dist/inbox/message.js

@@ -0,0 +1,88 @@
+// One email as the agent reads it: parsed with postal-mime (loaded only here, on first use) and
+// written to .commercelayer/inbox/<id>/: message.json (headers, text, the attachments' files),
+// body.txt (the text, or the HTML as text) and attachments/ with each file as it came. The
+// CLI does not read PDFs or sheets: the agent opens them with its own abilities.
+import fs from 'node:fs';
+import path from 'node:path';
+import { ignorePath, paths } from '../files.js';
+export const MAX_ATTACHMENT = 25 * 1024 * 1024;
+export const inboxDir = () => path.join(paths.dir, 'inbox');
+const who = (a) => (a.group ? a.group.flatMap(who) : a.address ? [a.name ? `${a.name} <${a.address}>` : a.address] : []);
+/** The HTML of a message as plain text, for one with no text part. */
+export function htmlText(html) {
+    return html
+        .replace(/<(script|style|head)[^>]*>[\s\S]*?<\/\1>/gi, '')
+        .replace(/<br\s*\/?>/gi, '\n')
+        .replace(/<\/(p|div|tr|li|h[1-6]|table)>/gi, '\n')
+        .replace(/<(td|th)[^>]*>/gi, '\t')
+        .replace(/<[^>]+>/g, '')
+        .replace(/&nbsp;/g, ' ')
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&quot;/g, '"')
+        .replace(/&#39;/g, "'")
+        .replace(/&amp;/g, '&')
+        .replace(/[ \t]+\n/g, '\n')
+        .replace(/\n{3,}/g, '\n\n')
+        .trim();
+}
+export async function parseMessage(raw) {
+    const { default: PostalMime } = await import('postal-mime');
+    const m = await PostalMime.parse(raw, { attachmentEncoding: 'arraybuffer' });
+    const text = m.text?.trim() ? m.text : m.html ? htmlText(m.html) : '';
+    return {
+        message_id: m.messageId ?? null,
+        from: m.from ? (who(m.from)[0] ?? null) : null,
+        to: (m.to ?? []).flatMap((a) => who(a)),
+        subject: m.subject ?? null,
+        date: m.date ?? null,
+        text,
+        ...(m.html ? { html: m.html } : {}),
+        attachments: m.attachments.map((a) => ({
+            name: a.filename,
+            content_type: a.mimeType,
+            bytes: typeof a.content === 'string' ? new TextEncoder().encode(a.content) : new Uint8Array(a.content),
+            inline: a.related === true || (a.disposition === 'inline' && !!a.contentId && a.mimeType.startsWith('image/')),
+        })),
+    };
+}
+const EXT = { 'application/pdf': 'pdf', 'text/plain': 'txt', 'text/csv': 'csv', 'image/png': 'png', 'image/jpeg': 'jpg', 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet': 'xlsx', 'application/vnd.ms-excel': 'xls', 'application/vnd.openxmlformats-officedocument.wordprocessingml.document': 'docx', 'application/msword': 'doc' };
+/** A file name safe on every system: no folders, no control characters, never empty. */
+export function safeName(name, i, type) {
+    // Slashes become underscores: "PO 2026/114.pdf" keeps its whole name and stays in its folder.
+    const base = (name ?? '').replace(/[/\\\u0000-\u001f<>:"|?*]+/g, '_').replace(/^[._]+/, '').trim().slice(0, 120);
+    return base || `attachment-${i + 1}${EXT[type] ? `.${EXT[type]}` : ''}`;
+}
+/** Write a parsed message under .commercelayer/inbox/<id>/; the folder is gitignored on first use. */
+export function writeMessage(id, m, labels) {
+    const root = inboxDir();
+    if (!fs.existsSync(root))
+        ignorePath(`${root}/`);
+    const dir = path.join(root, id.replace(/[^A-Za-z0-9._-]+/g, '_'));
+    fs.mkdirSync(dir, { recursive: true });
+    const warnings = [];
+    const attachments = [];
+    const used = new Set();
+    m.attachments.forEach((a, i) => {
+        if (a.inline)
+            return;
+        if (a.bytes.length > MAX_ATTACHMENT) {
+            warnings.push(`${a.name ?? `attachment ${i + 1}`} is over 25 MB and was not saved: open the email in the mail app.`);
+            return;
+        }
+        let name = safeName(a.name, i, a.content_type);
+        for (let n = 2; used.has(name.toLowerCase()); n++)
+            name = name.replace(/(?: \(\d+\))?(\.[^.]*)?$/, ` (${n})$1`);
+        used.add(name.toLowerCase());
+        fs.mkdirSync(path.join(dir, 'attachments'), { recursive: true });
+        const file = path.join(dir, 'attachments', name);
+        fs.writeFileSync(file, a.bytes);
+        attachments.push({ file, name: a.name, content_type: a.content_type, size: a.bytes.length });
+    });
+    const body = path.join(dir, 'body.txt');
+    fs.writeFileSync(body, m.text.endsWith('\n') ? m.text : `${m.text}\n`);
+    const message = path.join(dir, 'message.json');
+    const json = { id, message_id: m.message_id, from: m.from, to: m.to, subject: m.subject, date: m.date, labels, text: m.text, ...(m.html ? { html: m.html } : {}), attachments: attachments.map(({ file, name, content_type, size }) => ({ file, name, content_type, size })) };
+    fs.writeFileSync(message, JSON.stringify(json, null, 2) + '\n');
+    return { id, dir, message, body, subject: m.subject, from: m.from, message_id: m.message_id, attachments, ...(warnings.length ? { warnings } : {}) };
+}

package/dist/ops.js

@@ -0,0 +1,190 @@
+// The merchant agent running the store on a schedule: what is new since the last run, what the
+// policy approves and captures, what it holds for the human, what is stuck. The policy is the
+// human's, read here and never sent to the API; the cursor (.commercelayer/ops.json) keeps a
+// run from reporting the same order twice. Shipping and cancelling stay with the human.
+import fs from 'node:fs';
+import path from 'node:path';
+import YAML from 'yaml';
+import { jsonCursor, MAX_SEEN, strings } from './cursor.js';
+import { paths } from './files.js';
+import { fail } from './output.js';
+import { minorUnits } from './ucp/platform.js';
+// ---------- the policy
+/**
+ * Where the policy is read from: .commercelayer/ops.yml, the whole file (key null). Committed
+ * with the store and agreed with the human; never sent to the API.
+ */
+export const POLICY_SOURCE = { file: 'ops.yml', key: null };
+export const DEFAULT_POLICY = { auto_approve: false, auto_capture: false, review_above: null, hold_countries: [], stuck_days: 2, transit_days: 7, mail_orders: { auto_place: false, labels: { pending: 'pending', ordered: 'ordered', declined: 'declined' } } };
+const POLICY_KEYS = Object.keys(DEFAULT_POLICY);
+export const policyPath = () => path.join(paths.dir, POLICY_SOURCE.file);
+/** The policy, the defaults where it says nothing; invalid_policy with the fix when it is wrong. */
+export function loadPolicy() {
+    const file = policyPath();
+    if (!fs.existsSync(file))
+        return { ...DEFAULT_POLICY, source: null };
+    let doc;
+    try {
+        doc = YAML.parse(fs.readFileSync(file, 'utf8'));
+    }
+    catch (e) {
+        fail('invalid_policy', `${file} is not valid YAML: ${e.message.split('\n')[0]}`, 'Fix the YAML, then run the command again.');
+    }
+    const raw = POLICY_SOURCE.key ? doc?.[POLICY_SOURCE.key] : doc;
+    const where = POLICY_SOURCE.key ? `${POLICY_SOURCE.key} in ${file}` : file;
+    return { ...checkPolicy(raw, where), source: file };
+}
+export function checkPolicy(raw, where) {
+    if (raw === undefined || raw === null)
+        return { ...DEFAULT_POLICY };
+    const bad = (what, hint) => fail('invalid_policy', `${where}: ${what}`, hint);
+    if (typeof raw !== 'object' || Array.isArray(raw))
+        bad('the policy is not a set of settings.', `Write it as settings, one per line: auto_approve: true, review_above: 500, … (${POLICY_KEYS.join(', ')}).`);
+    const p = raw;
+    const unknown = Object.keys(p).filter((k) => !POLICY_KEYS.includes(k));
+    if (unknown.length)
+        bad(`${unknown.join(', ')} ${unknown.length === 1 ? 'is not a setting' : 'are not settings'} of the policy.`, `The settings are ${POLICY_KEYS.join(', ')}.`);
+    const out = { ...DEFAULT_POLICY, mail_orders: { auto_place: false, labels: { ...DEFAULT_POLICY.mail_orders.labels } } };
+    for (const k of ['auto_approve', 'auto_capture']) {
+        if (p[k] === undefined)
+            continue;
+        if (typeof p[k] !== 'boolean')
+            bad(`${k} is ${JSON.stringify(p[k])}, not true or false.`, `Write ${k}: true or ${k}: false.`);
+        out[k] = p[k];
+    }
+    if (p.review_above !== undefined && p.review_above !== null) {
+        if (typeof p.review_above !== 'number' || !Number.isFinite(p.review_above) || p.review_above < 0)
+            bad(`review_above is ${JSON.stringify(p.review_above)}, not an amount.`, 'Give it in major units of the order\'s currency, for example review_above: 500, or leave it out to hold none for their total.');
+        out.review_above = p.review_above;
+    }
+    if (p.hold_countries !== undefined) {
+        const list = p.hold_countries;
+        if (!Array.isArray(list) || list.some((c) => typeof c !== 'string' || !/^[A-Za-z]{2}$/.test(c)))
+            bad(`hold_countries is ${JSON.stringify(list)}, not a list of country codes.`, 'Write ISO 3166 codes: hold_countries: [US, CA].');
+        out.hold_countries = list.map((c) => c.toUpperCase());
+    }
+    for (const k of ['stuck_days', 'transit_days']) {
+        if (p[k] === undefined)
+            continue;
+        const n = p[k];
+        if (typeof n !== 'number' || !Number.isFinite(n) || n <= 0)
+            bad(`${k} is ${JSON.stringify(n)}, not a number of days.`, `Write a number of days above 0, for example ${k}: ${DEFAULT_POLICY[k]}.`);
+        out[k] = n;
+    }
+    if (p.mail_orders !== undefined && p.mail_orders !== null) {
+        const m = p.mail_orders;
+        const fix = 'Write it as mail_orders: { auto_place: false, labels: { pending: pending, ordered: ordered, declined: declined } }; every setting is optional.';
+        if (typeof m !== 'object' || Array.isArray(m))
+            bad(`mail_orders is ${JSON.stringify(m)}, not a set of settings.`, fix);
+        const extra = Object.keys(m).filter((k) => k !== 'auto_place' && k !== 'labels');
+        if (extra.length)
+            bad(`mail_orders.${extra[0]} is not a setting: mail_orders has auto_place and labels.`, fix);
+        if (m.auto_place !== undefined && typeof m.auto_place !== 'boolean')
+            bad(`mail_orders.auto_place is ${JSON.stringify(m.auto_place)}, not true or false.`, fix);
+        out.mail_orders.auto_place = m.auto_place === true;
+        if (m.labels !== undefined && m.labels !== null) {
+            const l = m.labels;
+            if (typeof l !== 'object' || Array.isArray(l))
+                bad(`mail_orders.labels is ${JSON.stringify(l)}, not a set of names.`, fix);
+            const names = Object.keys(DEFAULT_POLICY.mail_orders.labels);
+            const other = Object.keys(l).filter((k) => !names.includes(k));
+            if (other.length)
+                bad(`mail_orders.labels.${other[0]} is not a label: the labels are ${names.join(', ')}.`, fix);
+            for (const k of names) {
+                const v = l[k];
+                if (v === undefined)
+                    continue;
+                if (typeof v !== 'string' || !v.trim() || v.length > 50 || v.startsWith('\\'))
+                    bad(`mail_orders.labels.${k} is ${JSON.stringify(v)}, not a label name.`, 'A label is a name of 1 to 50 characters, not starting with a backslash (\\Seen and the like are IMAP flags).');
+                out.mail_orders.labels[k] = v;
+            }
+        }
+    }
+    return out;
+}
+export const cursorPath = () => path.join(paths.dir, 'ops.json');
+// Machine state, rewritten on every run: kept out of git like the credentials.
+const cursor = () => jsonCursor(cursorPath(), (c) => ({ last_run: typeof c?.last_run === 'string' ? c.last_run : null, seen: strings(c?.seen) }));
+export const readCursor = () => cursor().read();
+export const writeCursor = (c) => cursor().write({ last_run: c.last_run, seen: c.seen.slice(0, MAX_SEEN) });
+// ---------- time
+const UNITS = { h: 3600_000, d: 86_400_000, w: 7 * 86_400_000 };
+/** "24h", "7d", "2w" or an ISO date or time: the instant it means, relative to now. */
+export function parseSince(raw, flag, now = Date.now()) {
+    const rel = raw.trim().match(/^(\d+(?:\.\d+)?)\s*([hdw])$/i);
+    if (rel)
+        return new Date(now - Number(rel[1]) * UNITS[rel[2].toLowerCase()]);
+    const t = Date.parse(raw);
+    if (!/^\d{4}-\d{2}-\d{2}/.test(raw.trim()) || Number.isNaN(t))
+        fail('invalid_argument', `--${flag} ${raw} is not a time.`, `Use a span back from now (24h, 7d, 30d) or an ISO date (2026-11-01, 2026-11-01T09:00:00Z).`);
+    return new Date(t);
+}
+const DAY = 86_400_000;
+const days = (ms) => Math.round((ms / DAY) * 10) / 10;
+const brief = (o) => ({ id: o.id, number: o.number, placed_at: o.placed_at, country: o.country, channel: o.channel, email: o.email, items: o.items, total: o.total, payment_status: o.payment_status });
+/** Why the policy holds an order for the human, if it does. */
+export function holdReason(o, p) {
+    const reasons = [];
+    if (p.review_above !== null && o.total.major > p.review_above)
+        reasons.push(`its total ${o.total.display} is above ${o.currency} ${p.review_above.toFixed(2)} (review_above)`);
+    if (o.country && p.hold_countries.includes(o.country.toUpperCase()))
+        reasons.push(`it ships to ${o.country.toUpperCase()} (hold_countries)`);
+    return reasons.length ? reasons.join(' and ') : undefined;
+}
+/** What the policy does with a placed order. */
+export function decidePlaced(o, p) {
+    const held = holdReason(o, p);
+    if (held)
+        return { order: brief(o), action: 'hold', reason: held };
+    if (!p.auto_approve)
+        return { order: brief(o), action: 'wait', reason: 'auto_approve is off: the human approves orders' };
+    if (p.auto_capture && o.payment_status === 'authorized')
+        return { order: brief(o), action: 'approve_capture' };
+    return { order: brief(o), action: 'approve' };
+}
+/** What the policy does with an approved order whose payment is only authorized. */
+export function decideApproved(o, p) {
+    if (!p.auto_capture)
+        return { order: brief(o), action: 'wait', reason: 'auto_capture is off: the human says when to take the payment' };
+    return { order: brief(o), action: 'capture' };
+}
+/** Picking, packing or ready to ship for too long is stuck; on hold is the merchant's choice, never stuck. */
+const WORKING = ['picking', 'packing', 'ready_to_ship'];
+/** A stuck shipment as ops prints it, from its row and its age in days. */
+export function stuckView(s, age, p) {
+    const since = s.status_changed_at ?? s.dates?.[`${s.status}_at`] ?? '';
+    const reason = s.status === 'shipped' ? `shipped ${age} days ago and not delivered (transit_days ${p.transit_days})` : `${s.status.replace(/_/g, ' ')} for ${age} days (stuck_days ${p.stuck_days})`;
+    return { shipment: { id: s.id, number: s.number, status: s.status, order: s.order, country: s.country, tracking: s.tracking }, days: age, since, reason };
+}
+/**
+ * The same as the API's snapshot, for an API without it: shipments picking, packing or ready to
+ * ship longer than stuck_days, or shipped longer than transit_days, from when they entered it.
+ */
+export function stuckShipments(list, p, now = Date.now()) {
+    const out = [];
+    for (const s of list) {
+        const d = (s.dates ?? {});
+        const entered = Date.parse(s.status_changed_at ?? d[`${s.status}_at`] ?? '');
+        if (Number.isNaN(entered))
+            continue;
+        const age = days(now - entered);
+        if ((WORKING.includes(s.status) && now - entered > p.stuck_days * DAY) || (s.status === 'shipped' && now - entered > p.transit_days * DAY))
+            out.push(stuckView(s, age, p));
+    }
+    return out.sort((a, b) => b.days - a.days);
+}
+// ---------- words
+/** "EUR 20.00 + USD 12.00": money in several currencies, summed per currency. */
+export function totalsByCurrency(list) {
+    const by = new Map();
+    for (const m of list)
+        by.set(m.currency, (by.get(m.currency) ?? 0) + m.amount);
+    return [...by].map(([currency, amount]) => {
+        const unit = minorUnits(currency);
+        const major = amount / unit;
+        return { amount, currency, major, display: `${currency} ${major.toFixed(Math.round(Math.log10(unit)))}` };
+    });
+}
+export const moneyText = (list) => (list.length ? list.map((m) => m.display).join(' + ') : '0');
+export const numbers = (list) => list.map((d) => `#${d.order.number}`).join(', ');
+export const plural = (n, one, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;