@miakapp/cli 4.0.0-alpha.3 → 4.0.0-alpha.4

package/dist/discovery.js

@@ -0,0 +1,389 @@
+/**
+ * Reading an installation that already exists.
+ *
+ * `docs/agent-guide.md` §3 tells an agent to characterize the house before
+ * designing anything. This module is the part of that work a program can do:
+ * it turns a Node-RED `flows.json` export into an inventory of brokers, flows,
+ * topics and the V3 MiakAPI surface, and it reports which V3 names are already
+ * legal V4 names.
+ *
+ * Three properties keep it honest:
+ *
+ * - **Offline and read-only.** It parses bytes handed to it. It opens no
+ *   socket, contacts no broker and writes nothing back into the export.
+ * - **It never drops a node silently.** Every unrecognized `type` is counted
+ *   and reported, because the value of an inventory is knowing what it missed.
+ * - **It never guesses semantics.** It reports what a node declares. Which
+ *   actions are physically consequential is a judgement the reader makes from
+ *   the listed surface; no keyword list decides it here.
+ *
+ * Field names come from the two schemas involved: Node-RED core `mqtt in`,
+ * `mqtt out` and `mqtt-broker` node definitions, and the `node-red-contrib-
+ * MiakAPI` v3 node definitions in `miakapi.html`.
+ */
+import { projectError } from './errors.js';
+import { isDottedName, utf8Bytes } from './internal/names.js';
+/**
+ * A generous ceiling for a local export. The strict parser in `internal/json.ts`
+ * is bounded for untrusted control-plane responses at 2,048 values, which a real
+ * house blows through in the first tab; a flows export is an operator-supplied
+ * local file, so the bound here is on bytes rather than on structure.
+ */
+export const MAXIMUM_FLOWS_BYTES = 33_554_432;
+/** Keys that would poison a prototype if a record were ever spread. */
+const FORBIDDEN_KEYS = new Set(['__proto__', 'prototype', 'constructor']);
+const MIAKAPI_V3_TYPES = new Set([
+    'initMiakapi',
+    'getHomeUsers',
+    'commitVariables',
+    'onHomeReady',
+    'onHomeUpdate',
+    'onUserLogin',
+    'onUserAction',
+    'sendPushNotif',
+    'reconnectMiakapi',
+]);
+function field(node, key) {
+    return Object.hasOwn(node, key) ? node[key] : undefined;
+}
+function text(node, key) {
+    const value = field(node, key);
+    return typeof value === 'string' ? value : '';
+}
+function flag(node, key) {
+    return field(node, key) === true;
+}
+/** Node-RED writes `port` as either a number or a numeric string. */
+function port(node) {
+    const value = field(node, 'port');
+    if (typeof value === 'number' && Number.isSafeInteger(value))
+        return value;
+    if (typeof value === 'string' && /^[0-9]{1,5}$/.test(value))
+        return Number(value);
+    return undefined;
+}
+function finding(kind, severity, detail, nodeId) {
+    return Object.freeze({ kind, severity, detail, nodeId });
+}
+/**
+ * Parses the export.
+ *
+ * A flows export is a flat array of node records; tabs, config nodes and wired
+ * nodes all sit at the same level and refer to each other by `id`.
+ */
+function parseFlows(source) {
+    if (source.byteLength > MAXIMUM_FLOWS_BYTES) {
+        throw projectError(`The flows export is larger than ${MAXIMUM_FLOWS_BYTES} bytes`, 'Export one Node-RED instance at a time.');
+    }
+    let decoded;
+    try {
+        decoded = new TextDecoder('utf-8', { fatal: true }).decode(source);
+    }
+    catch {
+        throw projectError('The flows export is not readable as UTF-8 text');
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(decoded);
+    }
+    catch {
+        throw projectError('The flows export is not valid JSON', 'Use the file Node-RED writes, or the Export > All flows download, not a screenshot of it.');
+    }
+    if (!Array.isArray(parsed)) {
+        throw projectError('The flows export is not a JSON array of nodes', 'A Node-RED export is a flat array; an object here is usually a single copied node.');
+    }
+    const nodes = [];
+    for (const entry of parsed) {
+        if (entry === null || typeof entry !== 'object' || Array.isArray(entry))
+            continue;
+        // Values are only ever read through `Object.hasOwn`, never spread, so a
+        // poisoned key cannot reach a prototype; it is dropped here regardless.
+        if (Reflect.ownKeys(entry).some((key) => FORBIDDEN_KEYS.has(String(key))))
+            continue;
+        if (typeof entry['type'] !== 'string')
+            continue;
+        nodes.push(entry);
+    }
+    return nodes;
+}
+function collectTabs(nodes) {
+    const counts = new Map();
+    for (const node of nodes) {
+        const parent = text(node, 'z');
+        if (parent !== '')
+            counts.set(parent, (counts.get(parent) ?? 0) + 1);
+    }
+    return nodes
+        .filter((node) => node['type'] === 'tab')
+        .map((node) => {
+        const id = text(node, 'id');
+        return Object.freeze({
+            id,
+            label: text(node, 'label'),
+            disabled: flag(node, 'disabled'),
+            nodeCount: counts.get(id) ?? 0,
+        });
+    });
+}
+function collectBrokers(nodes, findings) {
+    const subscribes = new Map();
+    const publishes = new Map();
+    for (const node of nodes) {
+        const type = node['type'];
+        if (type !== 'mqtt in' && type !== 'mqtt out')
+            continue;
+        const broker = text(node, 'broker');
+        const topic = text(node, 'topic');
+        if (broker === '')
+            continue;
+        if (topic === '') {
+            // `mqtt in` with `topicType: dynamic` takes its topic from a message, so
+            // the export cannot say which devices it will reach.
+            findings.push(finding('unmodelled_node', 'attention', `${String(type)} node has no static topic; its subscription is set at runtime`, text(node, 'id')));
+            continue;
+        }
+        const into = type === 'mqtt in' ? subscribes : publishes;
+        const set = into.get(broker) ?? new Set();
+        set.add(topic);
+        into.set(broker, set);
+        if (type === 'mqtt in' && (topic.includes('#') || topic.includes('+'))) {
+            findings.push(finding('wildcard_subscription', 'note', `Subscription ${topic} is a pattern, not one device; enumerate what it actually matches`, text(node, 'id')));
+        }
+    }
+    return nodes
+        .filter((node) => node['type'] === 'mqtt-broker')
+        .map((node) => {
+        const id = text(node, 'id');
+        const host = text(node, 'broker');
+        const tls = flag(node, 'usetls');
+        if (!tls) {
+            findings.push(finding('broker_without_tls', 'attention', `Broker ${host === '' ? id : host} is configured without TLS`, id));
+        }
+        return Object.freeze({
+            id,
+            name: text(node, 'name'),
+            host,
+            port: port(node),
+            tls,
+            subscribes: [...subscribes.get(id) ?? []].sort(),
+            publishes: [...publishes.get(id) ?? []].sort(),
+        });
+    });
+}
+function collectHomes(nodes, findings) {
+    return nodes
+        .filter((node) => node['type'] === 'initMiakapi')
+        .map((node) => {
+        const nodeId = text(node, 'id');
+        // `coordSecret` is declared in the node's `defaults`, not in its
+        // `credentials`, so Node-RED stores it in `flows.json` itself rather than
+        // in the encrypted `flows_cred.json`.
+        const secretInExport = text(node, 'coordSecret') !== '';
+        if (secretInExport) {
+            findings.push(finding('secret_in_export', 'critical', 'A coordinator secret is stored in cleartext in this export; treat it as leaked, '
+                + 'rotate it, and keep the export out of Git', nodeId));
+        }
+        return Object.freeze({
+            nodeId,
+            homeId: text(node, 'home'),
+            coordinatorId: text(node, 'coordID'),
+            secretInExport,
+        });
+    });
+}
+/**
+ * Why a V3 name is not a legal V4 dotted name, in the words of the rule it
+ * breaks. `isDottedName` answers yes or no; a reader who has to rename a path
+ * needs to know which constraint bit them.
+ */
+function illegalNameReason(value) {
+    if (value === '')
+        return 'it is empty';
+    if (value.includes('*'))
+        return 'it contains *, which V4 reserves for the trailing .* suffix';
+    if (/\p{Cc}/u.test(value))
+        return 'it contains a control character';
+    if (value.split('.').some((segment) => segment === '')) {
+        return 'it has an empty dotted segment';
+    }
+    return `it is ${utf8Bytes(value)} UTF-8 bytes, outside the 1..256 range`;
+}
+function variableSource(type) {
+    if (type === 'jsonata')
+        return 'jsonata';
+    if (type === 'env')
+        return 'env';
+    return 'literal';
+}
+function collectState(nodes, findings) {
+    const candidates = [];
+    for (const node of nodes) {
+        if (node['type'] !== 'commitVariables')
+            continue;
+        const values = field(node, 'values');
+        if (values === null || typeof values !== 'object' || Array.isArray(values))
+            continue;
+        const nodeId = text(node, 'id');
+        for (const path of Object.keys(values)) {
+            if (FORBIDDEN_KEYS.has(path))
+                continue;
+            const entry = values[path];
+            const type = entry !== null && typeof entry === 'object' && !Array.isArray(entry)
+                ? entry['type']
+                : undefined;
+            const legalV4Name = isDottedName(path);
+            if (!legalV4Name) {
+                findings.push(finding('name_needs_rename', 'attention', `Variable path ${path} is not a legal V4 state path: ${illegalNameReason(path)}; `
+                    + 'rename it before the household depends on it', nodeId));
+            }
+            candidates.push(Object.freeze({
+                path,
+                source: variableSource(type),
+                nodeId,
+                legalV4Name,
+            }));
+        }
+    }
+    return candidates.sort((left, right) => (left.path < right.path ? -1 : 1));
+}
+function collectActions(nodes, findings) {
+    const candidates = [];
+    for (const node of nodes) {
+        if (node['type'] !== 'onUserAction')
+            continue;
+        const nodeId = text(node, 'id');
+        const inputId = text(node, 'inputID');
+        const raw = field(node, 'allowedGroups');
+        const allowedGroups = Array.isArray(raw)
+            ? raw.filter((group) => typeof group === 'string')
+            : [];
+        // The v3 handler allows the action outright when no group is listed, so an
+        // empty list is a grant to every signed-in user, not a deny.
+        if (allowedGroups.length === 0) {
+            findings.push(finding('unrestricted_action', 'critical', `Action ${inputId === '' ? nodeId : inputId} lists no group, so every signed-in user `
+                + 'may invoke it; V4 needs an explicit rule for it', nodeId));
+        }
+        const legalV4Name = isDottedName(inputId);
+        if (!legalV4Name) {
+            findings.push(finding('name_needs_rename', 'attention', `Action id ${inputId === '' ? '(empty)' : inputId} is not a legal V4 function name: `
+                + illegalNameReason(inputId), nodeId));
+        }
+        candidates.push(Object.freeze({ inputId, allowedGroups, nodeId, legalV4Name }));
+    }
+    return candidates.sort((left, right) => (left.inputId < right.inputId ? -1 : 1));
+}
+function collectNotifications(nodes) {
+    return nodes
+        .filter((node) => node['type'] === 'sendPushNotif')
+        .map((node) => Object.freeze({
+        nodeId: text(node, 'id'),
+        name: text(node, 'name'),
+        adminOnly: flag(node, 'adminOnly'),
+        group: text(node, 'group'),
+    }));
+}
+function collectUnmodelled(nodes, findings) {
+    const modelled = new Set(['tab', 'mqtt in', 'mqtt out', 'mqtt-broker', ...MIAKAPI_V3_TYPES]);
+    const counts = new Map();
+    for (const node of nodes) {
+        const type = node['type'];
+        if (modelled.has(type))
+            continue;
+        counts.set(type, (counts.get(type) ?? 0) + 1);
+    }
+    const unmodelled = [...counts]
+        .map(([type, count]) => Object.freeze({ type, count }))
+        .sort((left, right) => right.count - left.count || (left.type < right.type ? -1 : 1));
+    if (unmodelled.length > 0) {
+        findings.push(finding('unmodelled_node', 'note', `${unmodelled.length} node type(s) are not modelled by this inventory; `
+            + 'read them yourself before assuming the house is fully described'));
+    }
+    return unmodelled;
+}
+/**
+ * Builds the inventory for one Node-RED export.
+ *
+ * The result is a pure function of the bytes: the same export always produces
+ * the same report, which is what makes it usable as a migration baseline that
+ * can be diffed between two runs.
+ */
+export function discoverFlows(source) {
+    const nodes = parseFlows(source);
+    const findings = [];
+    const flows = collectTabs(nodes);
+    const brokers = collectBrokers(nodes, findings);
+    const homes = collectHomes(nodes, findings);
+    const state = collectState(nodes, findings);
+    const actions = collectActions(nodes, findings);
+    const notifications = collectNotifications(nodes);
+    const unmodelled = collectUnmodelled(nodes, findings);
+    const order = { critical: 0, attention: 1, note: 2 };
+    return Object.freeze({
+        nodeCount: nodes.length,
+        flows,
+        brokers,
+        homes,
+        state,
+        actions,
+        notifications,
+        unmodelled,
+        findings: findings.sort((left, right) => order[left.severity] - order[right.severity]),
+    });
+}
+/** The JSON body of `miakapp discover --json`, with no secret value in it. */
+export function inventoryJson(inventory) {
+    return {
+        node_count: inventory.nodeCount,
+        flows: inventory.flows.map((tab) => ({
+            id: tab.id,
+            label: tab.label,
+            disabled: tab.disabled,
+            node_count: tab.nodeCount,
+        })),
+        brokers: inventory.brokers.map((broker) => ({
+            id: broker.id,
+            name: broker.name,
+            host: broker.host,
+            ...(broker.port === undefined ? {} : { port: broker.port }),
+            tls: broker.tls,
+            subscribes: broker.subscribes,
+            publishes: broker.publishes,
+        })),
+        homes: inventory.homes.map((home) => ({
+            node_id: home.nodeId,
+            home_id: home.homeId,
+            coordinator_id: home.coordinatorId,
+            // The flag says a secret is present. The secret itself is never read out.
+            secret_in_export: home.secretInExport,
+        })),
+        state: inventory.state.map((candidate) => ({
+            path: candidate.path,
+            source: candidate.source,
+            node_id: candidate.nodeId,
+            legal_v4_name: candidate.legalV4Name,
+        })),
+        actions: inventory.actions.map((candidate) => ({
+            input_id: candidate.inputId,
+            allowed_groups: candidate.allowedGroups,
+            node_id: candidate.nodeId,
+            legal_v4_name: candidate.legalV4Name,
+        })),
+        notifications: inventory.notifications.map((candidate) => ({
+            node_id: candidate.nodeId,
+            name: candidate.name,
+            admin_only: candidate.adminOnly,
+            group: candidate.group,
+        })),
+        unmodelled: inventory.unmodelled.map((entry) => ({
+            type: entry.type,
+            count: entry.count,
+        })),
+        findings: inventory.findings.map((item) => ({
+            kind: item.kind,
+            severity: item.severity,
+            detail: item.detail,
+            ...(item.nodeId === undefined || item.nodeId === '' ? {} : { node_id: item.nodeId }),
+        })),
+    };
+}
+//# sourceMappingURL=discovery.js.map

package/dist/discovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.js","sourceRoot":"","sources":["../src/discovery.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAE9D;;;;;GAKG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,UAAU,CAAC;AAE9C,uEAAuE;AACvE,MAAM,cAAc,GAAG,IAAI,GAAG,CAAC,CAAC,WAAW,EAAE,WAAW,EAAE,aAAa,CAAC,CAAC,CAAC;AAE1E,MAAM,gBAAgB,GAAG,IAAI,GAAG,CAAC;IAC/B,aAAa;IACb,cAAc;IACd,iBAAiB;IACjB,aAAa;IACb,cAAc;IACd,aAAa;IACb,cAAc;IACd,eAAe;IACf,kBAAkB;CACnB,CAAC,CAAC;AAwFH,SAAS,KAAK,CAAC,IAAa,EAAE,GAAW;IACvC,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AAC1D,CAAC;AAED,SAAS,IAAI,CAAC,IAAa,EAAE,GAAW;IACtC,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IAC/B,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;AAChD,CAAC;AAED,SAAS,IAAI,CAAC,IAAa,EAAE,GAAW;IACtC,OAAO,KAAK,CAAC,IAAI,EAAE,GAAG,CAAC,KAAK,IAAI,CAAC;AACnC,CAAC;AAED,qEAAqE;AACrE,SAAS,IAAI,CAAC,IAAa;IACzB,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAClC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAC3E,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,cAAc,CAAC,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;IAClF,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,SAAS,OAAO,CACd,IAAiB,EACjB,QAAyB,EACzB,MAAc,EACd,MAAe;IAEf,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;AAC3D,CAAC;AAED;;;;;GAKG;AACH,SAAS,UAAU,CAAC,MAAkB;IACpC,IAAI,MAAM,CAAC,UAAU,GAAG,mBAAmB,EAAE,CAAC;QAC5C,MAAM,YAAY,CAChB,mCAAmC,mBAAmB,QAAQ,EAC9D,yCAAyC,CAC1C,CAAC;IACJ,CAAC;IACD,IAAI,OAAe,CAAC;IACpB,IAAI,CAAC;QACH,OAAO,GAAG,IAAI,WAAW,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IACrE,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,YAAY,CAAC,gDAAgD,CAAC,CAAC;IACvE,CAAC;IACD,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAY,CAAC;IAC1C,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,YAAY,CAChB,oCAAoC,EACpC,2FAA2F,CAC5F,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAC3B,MAAM,YAAY,CAChB,+CAA+C,EAC/C,oFAAoF,CACrF,CAAC;IACJ,CAAC;IACD,MAAM,KAAK,GAAc,EAAE,CAAC;IAC5B,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;YAAE,SAAS;QAClF,wEAAwE;QACxE,wEAAwE;QACxE,IAAI,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,cAAc,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;YAAE,SAAS;QACpF,IAAI,OAAQ,KAAiB,CAAC,MAAM,CAAC,KAAK,QAAQ;YAAE,SAAS;QAC7D,KAAK,CAAC,IAAI,CAAC,KAAgB,CAAC,CAAC;IAC/B,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,WAAW,CAAC,KAAyB;IAC5C,MAAM,MAAM,GAAG,IAAI,GAAG,EAAkB,CAAC;IACzC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QAC/B,IAAI,MAAM,KAAK,EAAE;YAAE,MAAM,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IACvE,CAAC;IACD,OAAO,KAAK;SACT,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,KAAK,CAAC;SACxC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;QACZ,MAAM,EAAE,GAAG,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAC5B,OAAO,MAAM,CAAC,MAAM,CAAC;YACnB,EAAE;YACF,KAAK,EAAE,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC;YAC1B,QAAQ,EAAE,IAAI,CAAC,IAAI,EAAE,UAAU,CAAC;YAChC,SAAS,EAAE,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC;SAC/B,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACP,CAAC;AAED,SAAS,cAAc,CAAC,KAAyB,EAAE,QAAmB;IACpE,MAAM,UAAU,GAAG,IAAI,GAAG,EAAuB,CAAC;IAClD,MAAM,SAAS,GAAG,IAAI,GAAG,EAAuB,CAAC;IAEjD,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC;QAC1B,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,UAAU;YAAE,SAAS;QACxD,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;QACpC,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QAClC,IAAI,MAAM,KAAK,EAAE;YAAE,SAAS;QAC5B,IAAI,KAAK,KAAK,EAAE,EAAE,CAAC;YACjB,yEAAyE;YACzE,qDAAqD;YACrD,QAAQ,CAAC,IAAI,CAAC,OAAO,CACnB,iBAAiB,EACjB,WAAW,EACX,GAAG,MAAM,CAAC,IAAI,CAAC,+DAA+D,EAC9E,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CACjB,CAAC,CAAC;YACH,SAAS;QACX,CAAC;QACD,MAAM,IAAI,GAAG,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS,CAAC;QACzD,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,IAAI,GAAG,EAAU,CAAC;QAClD,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACf,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QACtB,IAAI,IAAI,KAAK,SAAS,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;YACvE,QAAQ,CAAC,IAAI,CAAC,OAAO,CACnB,uBAAuB,EACvB,MAAM,EACN,gBAAgB,KAAK,mEAAmE,EACxF,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CACjB,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,OAAO,KAAK;SACT,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,aAAa,CAAC;SAChD,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;QACZ,MAAM,EAAE,GAAG,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAC5B,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;QAClC,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;QACjC,IAAI,CAAC,GAAG,EAAE,CAAC;YACT,QAAQ,CAAC,IAAI,CAAC,OAAO,CACnB,oBAAoB,EACpB,WAAW,EACX,UAAU,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,4BAA4B,EAC7D,EAAE,CACH,CAAC,CAAC;QACL,CAAC;QACD,OAAO,MAAM,CAAC,MAAM,CAAC;YACnB,EAAE;YACF,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC;YACxB,IAAI;YACJ,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC;YAChB,GAAG;YACH,UAAU,EAAE,CAAC,GAAG,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE;YAChD,SAAS,EAAE,CAAC,GAAG,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE;SAC/C,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACP,CAAC;AAED,SAAS,YAAY,CAAC,KAAyB,EAAE,QAAmB;IAClE,OAAO,KAAK;SACT,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,aAAa,CAAC;SAChD,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;QACZ,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAChC,iEAAiE;QACjE,0EAA0E;QAC1E,sCAAsC;QACtC,MAAM,cAAc,GAAG,IAAI,CAAC,IAAI,EAAE,aAAa,CAAC,KAAK,EAAE,CAAC;QACxD,IAAI,cAAc,EAAE,CAAC;YACnB,QAAQ,CAAC,IAAI,CAAC,OAAO,CACnB,kBAAkB,EAClB,UAAU,EACV,kFAAkF;kBAChF,2CAA2C,EAC7C,MAAM,CACP,CAAC,CAAC;QACL,CAAC;QACD,OAAO,MAAM,CAAC,MAAM,CAAC;YACnB,MAAM;YACN,MAAM,EAAE,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC;YAC1B,aAAa,EAAE,IAAI,CAAC,IAAI,EAAE,SAAS,CAAC;YACpC,cAAc;SACf,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACP,CAAC;AAED;;;;GAIG;AACH,SAAS,iBAAiB,CAAC,KAAa;IACtC,IAAI,KAAK,KAAK,EAAE;QAAE,OAAO,aAAa,CAAC;IACvC,IAAI,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,OAAO,6DAA6D,CAAC;IAC9F,IAAI,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,iCAAiC,CAAC;IACpE,IAAI,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,KAAK,EAAE,CAAC,EAAE,CAAC;QACvD,OAAO,gCAAgC,CAAC;IAC1C,CAAC;IACD,OAAO,SAAS,SAAS,CAAC,KAAK,CAAC,wCAAwC,CAAC;AAC3E,CAAC;AAED,SAAS,cAAc,CAAC,IAAa;IACnC,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IACzC,IAAI,IAAI,KAAK,KAAK;QAAE,OAAO,KAAK,CAAC;IACjC,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,SAAS,YAAY,CAAC,KAAyB,EAAE,QAAmB;IAClE,MAAM,UAAU,GAAqB,EAAE,CAAC;IACxC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,IAAI,CAAC,MAAM,CAAC,KAAK,iBAAiB;YAAE,SAAS;QACjD,MAAM,MAAM,GAAG,KAAK,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;QACrC,IAAI,MAAM,KAAK,IAAI,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;YAAE,SAAS;QACrF,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAChC,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;YACvC,IAAI,cAAc,CAAC,GAAG,CAAC,IAAI,CAAC;gBAAE,SAAS;YACvC,MAAM,KAAK,GAAI,MAAkB,CAAC,IAAI,CAAC,CAAC;YACxC,MAAM,IAAI,GAAG,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;gBAC/E,CAAC,CAAE,KAAiB,CAAC,MAAM,CAAC;gBAC5B,CAAC,CAAC,SAAS,CAAC;YACd,MAAM,WAAW,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;YACvC,IAAI,CAAC,WAAW,EAAE,CAAC;gBACjB,QAAQ,CAAC,IAAI,CAAC,OAAO,CACnB,mBAAmB,EACnB,WAAW,EACX,iBAAiB,IAAI,kCAAkC,iBAAiB,CAAC,IAAI,CAAC,IAAI;sBAChF,8CAA8C,EAChD,MAAM,CACP,CAAC,CAAC;YACL,CAAC;YACD,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC;gBAC5B,IAAI;gBACJ,MAAM,EAAE,cAAc,CAAC,IAAI,CAAC;gBAC5B,MAAM;gBACN,WAAW;aACZ,CAAC,CAAC,CAAC;QACN,CAAC;IACH,CAAC;IACD,OAAO,UAAU,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAC7E,CAAC;AAED,SAAS,cAAc,CAAC,KAAyB,EAAE,QAAmB;IACpE,MAAM,UAAU,GAAsB,EAAE,CAAC;IACzC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,IAAI,CAAC,MAAM,CAAC,KAAK,cAAc;YAAE,SAAS;QAC9C,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAChC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;QACtC,MAAM,GAAG,GAAG,KAAK,CAAC,IAAI,EAAE,eAAe,CAAC,CAAC;QACzC,MAAM,aAAa,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC;YACtC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,KAAK,EAAmB,EAAE,CAAC,OAAO,KAAK,KAAK,QAAQ,CAAC;YACnE,CAAC,CAAC,EAAE,CAAC;QACP,2EAA2E;QAC3E,6DAA6D;QAC7D,IAAI,aAAa,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC/B,QAAQ,CAAC,IAAI,CAAC,OAAO,CACnB,qBAAqB,EACrB,UAAU,EACV,UAAU,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,2CAA2C;kBACpF,iDAAiD,EACnD,MAAM,CACP,CAAC,CAAC;QACL,CAAC;QACD,MAAM,WAAW,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC;QAC1C,IAAI,CAAC,WAAW,EAAE,CAAC;YACjB,QAAQ,CAAC,IAAI,CAAC,OAAO,CACnB,mBAAmB,EACnB,WAAW,EACX,aAAa,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,oCAAoC;kBACnF,iBAAiB,CAAC,OAAO,CAAC,EAC5B,MAAM,CACP,CAAC,CAAC;QACL,CAAC;QACD,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC;IAClF,CAAC;IACD,OAAO,UAAU,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AACnF,CAAC;AAED,SAAS,oBAAoB,CAAC,KAAyB;IACrD,OAAO,KAAK;SACT,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,eAAe,CAAC;SAClD,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC;QAC3B,MAAM,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC;QACxB,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC;QACxB,SAAS,EAAE,IAAI,CAAC,IAAI,EAAE,WAAW,CAAC;QAClC,KAAK,EAAE,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC;KAC3B,CAAC,CAAC,CAAC;AACR,CAAC;AAED,SAAS,iBAAiB,CACxB,KAAyB,EACzB,QAAmB;IAEnB,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,CAAC,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,aAAa,EAAE,GAAG,gBAAgB,CAAC,CAAC,CAAC;IAC7F,MAAM,MAAM,GAAG,IAAI,GAAG,EAAkB,CAAC;IACzC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,CAAW,CAAC;QACpC,IAAI,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,SAAS;QACjC,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAChD,CAAC;IACD,MAAM,UAAU,GAAG,CAAC,GAAG,MAAM,CAAC;SAC3B,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;SACtD,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,CAAC,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACxF,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC1B,QAAQ,CAAC,IAAI,CAAC,OAAO,CACnB,iBAAiB,EACjB,MAAM,EACN,GAAG,UAAU,CAAC,MAAM,oDAAoD;cACtE,iEAAiE,CACpE,CAAC,CAAC;IACL,CAAC;IACD,OAAO,UAAU,CAAC;AACpB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,MAAkB;IAC9C,MAAM,KAAK,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC;IACjC,MAAM,QAAQ,GAAc,EAAE,CAAC;IAC/B,MAAM,KAAK,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC;IACjC,MAAM,OAAO,GAAG,cAAc,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IAChD,MAAM,KAAK,GAAG,YAAY,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IAC5C,MAAM,KAAK,GAAG,YAAY,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IAC5C,MAAM,OAAO,GAAG,cAAc,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IAChD,MAAM,aAAa,GAAG,oBAAoB,CAAC,KAAK,CAAC,CAAC;IAClD,MAAM,UAAU,GAAG,iBAAiB,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IACtD,MAAM,KAAK,GAAoC,EAAE,QAAQ,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;IACtF,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,SAAS,EAAE,KAAK,CAAC,MAAM;QACvB,KAAK;QACL,OAAO;QACP,KAAK;QACL,KAAK;QACL,OAAO;QACP,aAAa;QACb,UAAU;QACV,QAAQ,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;KACvF,CAAC,CAAC;AACL,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,aAAa,CAAC,SAAoB;IAChD,OAAO;QACL,UAAU,EAAE,SAAS,CAAC,SAAS;QAC/B,KAAK,EAAE,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;YACnC,EAAE,EAAE,GAAG,CAAC,EAAE;YACV,KAAK,EAAE,GAAG,CAAC,KAAK;YAChB,QAAQ,EAAE,GAAG,CAAC,QAAQ;YACtB,UAAU,EAAE,GAAG,CAAC,SAAS;SAC1B,CAAC,CAAC;QACH,OAAO,EAAE,SAAS,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;YAC1C,EAAE,EAAE,MAAM,CAAC,EAAE;YACb,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,GAAG,CAAC,MAAM,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC;YAC3D,GAAG,EAAE,MAAM,CAAC,GAAG;YACf,UAAU,EAAE,MAAM,CAAC,UAAU;YAC7B,SAAS,EAAE,MAAM,CAAC,SAAS;SAC5B,CAAC,CAAC;QACH,KAAK,EAAE,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;YACpC,OAAO,EAAE,IAAI,CAAC,MAAM;YACpB,OAAO,EAAE,IAAI,CAAC,MAAM;YACpB,cAAc,EAAE,IAAI,CAAC,aAAa;YAClC,0EAA0E;YAC1E,gBAAgB,EAAE,IAAI,CAAC,cAAc;SACtC,CAAC,CAAC;QACH,KAAK,EAAE,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;YACzC,IAAI,EAAE,SAAS,CAAC,IAAI;YACpB,MAAM,EAAE,SAAS,CAAC,MAAM;YACxB,OAAO,EAAE,SAAS,CAAC,MAAM;YACzB,aAAa,EAAE,SAAS,CAAC,WAAW;SACrC,CAAC,CAAC;QACH,OAAO,EAAE,SAAS,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;YAC7C,QAAQ,EAAE,SAAS,CAAC,OAAO;YAC3B,cAAc,EAAE,SAAS,CAAC,aAAa;YACvC,OAAO,EAAE,SAAS,CAAC,MAAM;YACzB,aAAa,EAAE,SAAS,CAAC,WAAW;SACrC,CAAC,CAAC;QACH,aAAa,EAAE,SAAS,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;YACzD,OAAO,EAAE,SAAS,CAAC,MAAM;YACzB,IAAI,EAAE,SAAS,CAAC,IAAI;YACpB,UAAU,EAAE,SAAS,CAAC,SAAS;YAC/B,KAAK,EAAE,SAAS,CAAC,KAAK;SACvB,CAAC,CAAC;QACH,UAAU,EAAE,SAAS,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;YAC/C,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,KAAK,EAAE,KAAK,CAAC,KAAK;SACnB,CAAC,CAAC;QACH,QAAQ,EAAE,SAAS,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;YAC1C,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,QAAQ,EAAE,IAAI,CAAC,QAAQ;YACvB,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,GAAG,CAAC,IAAI,CAAC,MAAM,KAAK,SAAS,IAAI,IAAI,CAAC,MAAM,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC;SACrF,CAAC,CAAC;KACJ,CAAC;AACJ,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Deterministic CLI outcomes.
+ *
+ * An agent drives this tool without reading prose, so every failure maps to
+ * exactly one stable exit code and one stable machine-readable kind. New kinds
+ * may be added; existing codes never change meaning.
+ */
+export declare const EXIT_CODE: {
+    readonly success: 0;
+    readonly usage: 1;
+    readonly project: 2;
+    readonly artifact: 3;
+    readonly authorization: 4;
+    readonly contract: 5;
+    readonly conflict: 6;
+    readonly unknown_outcome: 7;
+};
+export type CliFailureKind = Exclude<keyof typeof EXIT_CODE, 'success'>;
+/**
+ * `unknown_outcome` is reserved for a request whose effect on the control plane
+ * is undetermined. The caller must reconcile with a read before acting again;
+ * it must never blindly retry with a new capability.
+ */
+export declare class CliError extends Error {
+    readonly kind: CliFailureKind;
+    readonly exitCode: number;
+    readonly remedy: string | undefined;
+    constructor(kind: CliFailureKind, message: string, remedy?: string);
+}
+export declare function usageError(message: string, remedy?: string): CliError;
+export declare function projectError(message: string, remedy?: string): CliError;
+export declare function artifactError(message: string, remedy?: string): CliError;
+export declare function authorizationError(message: string, remedy?: string): CliError;
+export declare function contractError(message: string, remedy?: string): CliError;
+export declare function conflictError(message: string, remedy?: string): CliError;
+export declare function unknownOutcomeError(message: string, remedy: string): CliError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,eAAO,MAAM,SAAS;aACpB,OAAO,EAAE,CAAC;aACV,KAAK,EAAE,CAAC;aACR,OAAO,EAAE,CAAC;aACV,QAAQ,EAAE,CAAC;aACX,aAAa,EAAE,CAAC;aAChB,QAAQ,EAAE,CAAC;aACX,QAAQ,EAAE,CAAC;aACX,eAAe,EAAE,CAAC;CACV,CAAC;AAEX,MAAM,MAAM,cAAc,GAAG,OAAO,CAAC,MAAM,OAAO,SAAS,EAAE,SAAS,CAAC,CAAC;AAExE;;;;GAIG;AACH,qBAAa,QAAS,SAAQ,KAAK;IACjC,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IAEpC,YAAY,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,EAMjE;CACF;AAED,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,QAAQ,CAErE;AAED,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,QAAQ,CAEvE;AAED,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,QAAQ,CAExE;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,QAAQ,CAE7E;AAED,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,QAAQ,CAExE;AAED,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,QAAQ,CAExE;AAED,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,QAAQ,CAE7E"}

package/dist/errors.js

@@ -0,0 +1,56 @@
+/**
+ * Deterministic CLI outcomes.
+ *
+ * An agent drives this tool without reading prose, so every failure maps to
+ * exactly one stable exit code and one stable machine-readable kind. New kinds
+ * may be added; existing codes never change meaning.
+ */
+export const EXIT_CODE = {
+    success: 0,
+    usage: 1,
+    project: 2,
+    artifact: 3,
+    authorization: 4,
+    contract: 5,
+    conflict: 6,
+    unknown_outcome: 7,
+};
+/**
+ * `unknown_outcome` is reserved for a request whose effect on the control plane
+ * is undetermined. The caller must reconcile with a read before acting again;
+ * it must never blindly retry with a new capability.
+ */
+export class CliError extends Error {
+    kind;
+    exitCode;
+    remedy;
+    constructor(kind, message, remedy) {
+        super(message);
+        this.name = 'MiakappCliError';
+        this.kind = kind;
+        this.exitCode = EXIT_CODE[kind];
+        this.remedy = remedy;
+    }
+}
+export function usageError(message, remedy) {
+    return new CliError('usage', message, remedy);
+}
+export function projectError(message, remedy) {
+    return new CliError('project', message, remedy);
+}
+export function artifactError(message, remedy) {
+    return new CliError('artifact', message, remedy);
+}
+export function authorizationError(message, remedy) {
+    return new CliError('authorization', message, remedy);
+}
+export function contractError(message, remedy) {
+    return new CliError('contract', message, remedy);
+}
+export function conflictError(message, remedy) {
+    return new CliError('conflict', message, remedy);
+}
+export function unknownOutcomeError(message, remedy) {
+    return new CliError('unknown_outcome', message, remedy);
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG;IACvB,OAAO,EAAE,CAAC;IACV,KAAK,EAAE,CAAC;IACR,OAAO,EAAE,CAAC;IACV,QAAQ,EAAE,CAAC;IACX,aAAa,EAAE,CAAC;IAChB,QAAQ,EAAE,CAAC;IACX,QAAQ,EAAE,CAAC;IACX,eAAe,EAAE,CAAC;CACV,CAAC;AAIX;;;;GAIG;AACH,MAAM,OAAO,QAAS,SAAQ,KAAK;IACxB,IAAI,CAAiB;IACrB,QAAQ,CAAS;IACjB,MAAM,CAAqB;IAEpC,YAAY,IAAoB,EAAE,OAAe,EAAE,MAAe;QAChE,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;QAC9B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,QAAQ,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;QAChC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF;AAED,MAAM,UAAU,UAAU,CAAC,OAAe,EAAE,MAAe;IACzD,OAAO,IAAI,QAAQ,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;AAChD,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,OAAe,EAAE,MAAe;IAC3D,OAAO,IAAI,QAAQ,CAAC,SAAS,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;AAClD,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,OAAe,EAAE,MAAe;IAC5D,OAAO,IAAI,QAAQ,CAAC,UAAU,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;AACnD,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,OAAe,EAAE,MAAe;IACjE,OAAO,IAAI,QAAQ,CAAC,eAAe,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;AACxD,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,OAAe,EAAE,MAAe;IAC5D,OAAO,IAAI,QAAQ,CAAC,UAAU,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;AACnD,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,OAAe,EAAE,MAAe;IAC5D,OAAO,IAAI,QAAQ,CAAC,UAAU,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;AACnD,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,OAAe,EAAE,MAAc;IACjE,OAAO,IAAI,QAAQ,CAAC,iBAAiB,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;AAC1D,CAAC"}

package/dist/internal/http.d.ts

@@ -0,0 +1,35 @@
+import { type JsonValue } from './json.js';
+/** RFC 0004 §4.2: one response body is at most 64 KiB outside the stated exceptions. */
+export declare const MAXIMUM_RESPONSE_BYTES = 65536;
+/** RFC 0004 §4.2: one request body is at most 16 KiB. */
+export declare const MAXIMUM_REQUEST_BYTES = 16384;
+export type FetchLike = (input: string, init: RequestInit) => Promise<Response>;
+export interface HttpsEndpoint {
+    readonly url: string;
+    readonly pathname: string;
+}
+/**
+ * Every control-plane URL is an exact absolute HTTPS identifier with no user
+ * information, query or fragment. A value that does not round-trip through
+ * `URL` is rejected rather than normalized.
+ *
+ * One deviation from byte-for-byte equality is required rather than convenient.
+ * RFC 0004 §3 states that `issuer` has no trailing slash, and its own example
+ * issuer is the bare origin `https://control.example.test`. `URL` serializes
+ * that back with a trailing slash, so demanding exact equality would reject
+ * every origin-only issuer the RFC describes and force an arbitrary path
+ * segment onto every deployment. An empty path is therefore accepted in either
+ * spelling; nothing else is relaxed, so a stray query, a default port or a
+ * non-normalized path is still refused.
+ */
+export declare function canonicalHttpsUrl(value: unknown, label: string): string;
+export declare function cancelBody(response: Response | undefined): void;
+export declare function readBoundedBody(response: Response, maximumBytes: number): Promise<Uint8Array>;
+export declare function readJsonBody(response: Response): Promise<JsonValue>;
+export declare function requestBody(value: unknown): string;
+/**
+ * A control-plane request never follows a redirect, never carries a cookie and
+ * never negotiates compression for an exact identifier.
+ */
+export declare function jsonRequestInit(method: 'GET' | 'POST', token: string, body: string | undefined, signal: AbortSignal): RequestInit;
+//# sourceMappingURL=http.d.ts.map

package/dist/internal/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/internal/http.ts"],"names":[],"mappings":"AACA,OAAO,EAAa,KAAK,SAAS,EAAE,MAAM,WAAW,CAAC;AAEtD,wFAAwF;AACxF,eAAO,MAAM,sBAAsB,QAAS,CAAC;AAE7C,yDAAyD;AACzD,eAAO,MAAM,qBAAqB,QAAS,CAAC;AAE5C,MAAM,MAAM,SAAS,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;AAEhF,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAsBvE;AAED,wBAAgB,UAAU,CAAC,QAAQ,EAAE,QAAQ,GAAG,SAAS,GAAG,IAAI,CAO/D;AAED,wBAAsB,eAAe,CACnC,QAAQ,EAAE,QAAQ,EAClB,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,UAAU,CAAC,CAmCrB;AAED,wBAAsB,YAAY,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,SAAS,CAAC,CAIzE;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAMlD;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,KAAK,GAAG,MAAM,EACtB,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,MAAM,EAAE,WAAW,GAClB,WAAW,CAab"}