railcode 0.1.13 → 0.1.16

package/dist/manifest.js

@@ -0,0 +1,695 @@
+// Pure helpers for the app manifest (`manifest.yaml`) — local strict parsing so
+// `railcode manifest validate` and `railcode deploy` fail fast with named
+// errors before any upload. The SERVER parse is authoritative (PyYAML +
+// org-resource existence checks); this parser is dependency-free and pinned to
+// the server's accept/reject decisions for the manifest grammar — a shallow
+// mapping with string lists and one nested map:
+//
+//   run_as: app            # or "user"
+//   saved_queries:
+//     - my_orders
+//   connectors:
+//     stripe:
+//       - GET /v1/balance
+//       - GET /v1/customers/*
+//   llm: true
+//   adhoc_sql:
+//     - warehouse
+//
+// Also supported, matching PyYAML: flow lists (`saved_queries: [a, b]`), a flow
+// map for connectors (`connectors: {stripe: [GET /v1/balance]}`), a whole-
+// document flow mapping (`{run_as: app, llm: true}`), quotes with YAML escape
+// decoding (`''` in single quotes, C-style `\n`/`\uXXXX`/… in double quotes),
+// comments, blank lines, a leading `---` document-start marker, a trailing
+// `...` document-end marker, and duplicate mapping keys (the last value wins —
+// though a superseded value must still be well-formed YAML, as on the server).
+// Bare scalars that YAML resolves to non-strings (`123`, `true`, `null`, …) are
+// rejected where the manifest wants a name, exactly like the server. YAML
+// anchors/aliases are the one known divergence: the server expands them, this
+// parser rejects them with a named error. The shared battery in
+// test/manifest-fixtures.json (also run by
+// backend/tests/test_manifest_parse_fixtures.py) keeps the two parsers pinned.
+export const APP_MANIFEST_NAME = "manifest.yaml";
+const ALLOWED_KEYS = ["run_as", "saved_queries", "connectors", "llm", "adhoc_sql"];
+const HTTP_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"];
+const SAVED_QUERY_NAME = /^[a-z0-9_]{1,80}$/;
+// PyYAML's YAML 1.1 plain-scalar resolver: a bare (unquoted) scalar matching one
+// of these resolves to a non-string (bool/null/int/float/timestamp), and the
+// server rejects a non-string wherever the manifest wants a name. The quirks are
+// deliberate — e.g. "1e3" IS a string, because PyYAML's float exponent requires
+// an explicit sign.
+const YAML_TRUE = /^(?:yes|Yes|YES|true|True|TRUE|on|On|ON)$/;
+const YAML_FALSE = /^(?:no|No|NO|false|False|FALSE|off|Off|OFF)$/;
+const YAML_NON_STRING = [
+    YAML_TRUE,
+    YAML_FALSE,
+    /^(?:~|null|Null|NULL)$/,
+    /^[-+]?(?:0b[0-1_]+|0[0-7_]+|(?:0|[1-9][0-9_]*)|0x[0-9a-fA-F_]+|[1-9][0-9_]*(?::[0-5]?[0-9])+)$/,
+    /^(?:[-+]?[0-9][0-9_]*\.[0-9_]*(?:[eE][-+][0-9]+)?|\.[0-9_]+(?:[eE][-+][0-9]+)?|[-+]?[0-9][0-9_]*(?::[0-5]?[0-9])+\.[0-9_]*|[-+]?\.(?:inf|Inf|INF)|\.(?:nan|NaN|NAN))$/,
+    /^\d{4}-\d\d-\d\d$|^\d{4}-\d\d?-\d\d?(?:[Tt]|[ \t]+)\d\d?:\d\d:\d\d(?:\.\d*)?(?:[ \t]*(?:Z|[-+]\d\d?(?::\d\d)?))?$/,
+];
+function isYamlNonString(value) {
+    return YAML_NON_STRING.some((re) => re.test(value));
+}
+export class ManifestParseError extends Error {
+    line;
+    constructor(message, line) {
+        super(line > 0 ? `${message} (line ${line})` : message);
+        this.line = line;
+    }
+}
+function significantLines(source) {
+    const out = [];
+    source.split(/\r?\n/).forEach((raw, i) => {
+        const withoutComment = stripComment(raw);
+        if (!withoutComment.trim())
+            return;
+        const indent = withoutComment.length - withoutComment.trimStart().length;
+        if (withoutComment.slice(0, indent).includes("\t")) {
+            throw new ManifestParseError("Use spaces for indentation, not tabs", i + 1);
+        }
+        out.push({ indent, text: withoutComment.trim(), num: i + 1 });
+    });
+    return out;
+}
+function stripComment(line) {
+    // A "#" starts a comment at line start or after whitespace — good enough for
+    // this grammar (no scalar we accept legitimately contains " #").
+    let inSingle = false;
+    let inDouble = false;
+    for (let i = 0; i < line.length; i += 1) {
+        const ch = line[i];
+        if (ch === "\\" && inDouble)
+            i += 1; // \" does not close a double-quoted scalar
+        else if (ch === "'" && !inDouble)
+            inSingle = !inSingle;
+        else if (ch === '"' && !inSingle)
+            inDouble = !inDouble;
+        else if (ch === "#" && !inSingle && !inDouble && (i === 0 || /\s/.test(line[i - 1]))) {
+            return line.slice(0, i);
+        }
+    }
+    return line;
+}
+// PyYAML's double-quote escape table (scanner.ESCAPE_REPLACEMENTS) — an escape
+// outside this set (plus \x/\u/\U) is a YAML error, as on the server.
+const DOUBLE_QUOTE_ESCAPES = {
+    "0": "\0",
+    a: "\x07",
+    b: "\b",
+    t: "\t",
+    "\t": "\t",
+    n: "\n",
+    v: "\v",
+    f: "\f",
+    r: "\r",
+    e: "\x1b",
+    " ": " ",
+    '"': '"',
+    "/": "/",
+    "\\": "\\",
+    N: "\u0085",
+    _: "\u00a0",
+    L: "\u2028",
+    P: "\u2029",
+};
+function unquote(value, num) {
+    const v = value.trim();
+    if (v.startsWith("'"))
+        return decodeSingleQuoted(v, num);
+    if (v.startsWith('"'))
+        return decodeDoubleQuoted(v, num);
+    return v;
+}
+// YAML single-quoted scalar: the ONLY escape is '' → a literal '; a backslash
+// is a plain character.
+function decodeSingleQuoted(v, num) {
+    let out = "";
+    let i = 1;
+    while (i < v.length) {
+        const ch = v[i];
+        if (ch === "'") {
+            if (v[i + 1] === "'") {
+                out += "'";
+                i += 2;
+                continue;
+            }
+            if (i !== v.length - 1) {
+                throw new ManifestParseError(`Unexpected content after closing quote in "${v}"`, num);
+            }
+            return out;
+        }
+        out += ch;
+        i += 1;
+    }
+    throw new ManifestParseError(`Unterminated quote in "${v}"`, num);
+}
+// YAML double-quoted scalar: C-style escapes, decoded the way PyYAML does.
+function decodeDoubleQuoted(v, num) {
+    let out = "";
+    let i = 1;
+    while (i < v.length) {
+        const ch = v[i];
+        if (ch === '"') {
+            if (i !== v.length - 1) {
+                throw new ManifestParseError(`Unexpected content after closing quote in "${v}"`, num);
+            }
+            return out;
+        }
+        if (ch === "\\") {
+            const esc = v[i + 1];
+            if (esc === undefined)
+                break; // dangling backslash → unterminated
+            if (esc === "x" || esc === "u" || esc === "U") {
+                const len = esc === "x" ? 2 : esc === "u" ? 4 : 8;
+                const hex = v.slice(i + 2, i + 2 + len);
+                if (hex.length !== len || !/^[0-9a-fA-F]+$/.test(hex)) {
+                    throw new ManifestParseError(`Invalid \\${esc} escape in "${v}"`, num);
+                }
+                out += String.fromCodePoint(parseInt(hex, 16));
+                i += 2 + len;
+                continue;
+            }
+            const mapped = DOUBLE_QUOTE_ESCAPES[esc];
+            if (mapped === undefined) {
+                throw new ManifestParseError(`Unknown escape "\\${esc}" in "${v}"`, num);
+            }
+            out += mapped;
+            i += 2;
+            continue;
+        }
+        out += ch;
+        i += 1;
+    }
+    throw new ManifestParseError(`Unterminated quote in "${v}"`, num);
+}
+function scalar(raw, num) {
+    const v = raw.trim();
+    if (v.startsWith("&") || v.startsWith("*")) {
+        throw new ManifestParseError(`YAML anchors/aliases are not supported here ("${v}") — write the value out literally`, num);
+    }
+    return { value: unquote(v, num), quoted: v.startsWith('"') || v.startsWith("'") };
+}
+// Split a flow body on top-level commas — commas inside [], {} or quotes don't
+// separate entries. A trailing comma is allowed (YAML flow grammar); an empty
+// entry anywhere else is a YAML error, as on the server.
+function splitFlowEntries(inner, num, what) {
+    const parts = [];
+    let depth = 0;
+    let quote = null;
+    let current = "";
+    for (let i = 0; i < inner.length; i += 1) {
+        const ch = inner[i];
+        if (quote !== null) {
+            if (ch === "\\" && quote === '"') {
+                current += ch + (inner[i + 1] ?? "");
+                i += 1;
+                continue;
+            }
+            if (ch === quote)
+                quote = null;
+        }
+        else if (ch === '"' || ch === "'") {
+            quote = ch;
+        }
+        else if (ch === "[" || ch === "{") {
+            depth += 1;
+        }
+        else if (ch === "]" || ch === "}") {
+            depth -= 1;
+            if (depth < 0) {
+                throw new ManifestParseError(`Unbalanced "${ch}" in ${what}`, num);
+            }
+        }
+        else if (ch === "," && depth === 0) {
+            parts.push(current);
+            current = "";
+            continue;
+        }
+        current += ch;
+    }
+    parts.push(current);
+    if (parts.length > 1 && parts[parts.length - 1].trim() === "")
+        parts.pop();
+    for (const part of parts) {
+        if (!part.trim())
+            throw new ManifestParseError(`Empty entry in ${what}`, num);
+    }
+    return parts.map((p) => p.trim());
+}
+// A flow collection ("[...]"/"{...}") must balance its delimiters, terminate
+// its quotes, and consume the whole value — trailing content after the final
+// closing delimiter is a YAML error. This is the well-formedness the server's
+// loader enforces even on values a later duplicate key supersedes.
+function checkFlowBalanced(value, num) {
+    const closers = [];
+    let quote = null;
+    for (let i = 0; i < value.length; i += 1) {
+        const ch = value[i];
+        if (quote !== null) {
+            if (ch === "\\" && quote === '"')
+                i += 1;
+            else if (ch === quote)
+                quote = null;
+            continue;
+        }
+        if (ch === '"' || ch === "'")
+            quote = ch;
+        else if (ch === "[")
+            closers.push("]");
+        else if (ch === "{")
+            closers.push("}");
+        else if (ch === "]" || ch === "}") {
+            if (closers.pop() !== ch) {
+                throw new ManifestParseError(`Unbalanced "${ch}" in flow collection`, num);
+            }
+            if (closers.length === 0) {
+                const rest = value.slice(i + 1).trim();
+                if (rest) {
+                    throw new ManifestParseError(`Unexpected content after flow collection: "${rest}"`, num);
+                }
+            }
+        }
+    }
+    if (quote !== null) {
+        throw new ManifestParseError(`Unterminated quote in "${value}"`, num);
+    }
+    if (closers.length > 0) {
+        throw new ManifestParseError(`Unterminated flow collection in "${value}" (missing "${closers[closers.length - 1]}")`, num);
+    }
+}
+// Syntactic (not semantic) validation of one collected value: a flow
+// collection must balance, a quoted scalar must terminate. Applied to EVERY
+// entry — including ones a later duplicate key supersedes — because the
+// server's yaml.safe_load parses the whole document before last-wins applies.
+function checkValueSyntax(value, num) {
+    if (!value)
+        return;
+    if (value.startsWith("[") || value.startsWith("{"))
+        checkFlowBalanced(value, num);
+    else if (value.startsWith('"') || value.startsWith("'"))
+        unquote(value, num);
+}
+function checkEntrySyntax(entry) {
+    checkValueSyntax(entry.inline, entry.keyLine.num);
+    for (const child of entry.children) {
+        let v = child.text;
+        if (v.startsWith("- ")) {
+            v = v.slice(2).trim();
+        }
+        else {
+            const m = v.match(CONNECTOR_BLOCK_ENTRY);
+            if (m)
+                v = (m[2] ?? "").trim();
+        }
+        checkValueSyntax(v, child.num);
+    }
+}
+function parseFlowList(value, num) {
+    const inner = value.slice(1, -1).trim();
+    if (!inner)
+        return [];
+    return splitFlowEntries(inner, num, "flow list").map((part) => scalar(part, num));
+}
+// One string-list entry (saved_queries / adhoc_sql): must be a YAML *string* —
+// a bare number/bool/null is a different type and the server rejects it.
+function listString(s, key, num) {
+    if (!s.quoted && isYamlNonString(s.value)) {
+        throw new ManifestParseError(`"${s.value}" under "${key}" is not a YAML string — quote it ("${s.value}") if you mean the name`, num);
+    }
+    const value = s.value.trim();
+    if (!value)
+        throw new ManifestParseError(`Empty list item under "${key}"`, num);
+    return value;
+}
+function parseBool(s, num) {
+    // A quoted scalar is a STRING even if it spells a boolean — as on the server.
+    if (!s.quoted) {
+        if (YAML_TRUE.test(s.value))
+            return true;
+        if (YAML_FALSE.test(s.value))
+            return false;
+    }
+    throw new ManifestParseError(`"llm" must be true or false (got "${s.value}")`, num);
+}
+// Strip the optional document markers: one leading "---" and one trailing "..."
+// are no-ops. Anything more is a multi-document stream, which the server
+// (yaml.safe_load) refuses too — including a trailing "---", which starts an
+// empty second document.
+function documentLines(source) {
+    let lines = significantLines(source);
+    if (lines.length > 0 && lines[0].indent === 0 && lines[0].text === "---") {
+        lines = lines.slice(1);
+    }
+    const last = lines[lines.length - 1];
+    if (last !== undefined && last.indent === 0 && last.text === "...") {
+        lines = lines.slice(0, -1);
+    }
+    for (const line of lines) {
+        if (line.indent === 0 && (line.text === "---" || line.text === "...")) {
+            throw new ManifestParseError("manifest.yaml must be a single YAML document (unexpected document marker)", line.num);
+        }
+    }
+    return lines;
+}
+// A block-context key: the colon must be followed by whitespace or end the
+// line ("llm:true" is a plain SCALAR in block YAML, not a mapping). In flow
+// context the colon may also sit directly before a flow opener — PyYAML
+// accepts "{stripe:[GET /x]}" but reads "{llm:true}" as the key "llm:true".
+const BLOCK_KEY = /^([A-Za-z_][A-Za-z0-9_]*)\s*:(?:\s+(.*))?$/;
+const FLOW_KEY = /^([A-Za-z_][A-Za-z0-9_]*)\s*:(?=$|[\s[{])\s*(.*)$/;
+export function parseManifestYaml(source) {
+    const lines = documentLines(source);
+    // Pass 1: split the top level into key entries. The document is either a
+    // block mapping or one flow mapping ("{...}", possibly spanning lines) —
+    // both are dicts to the server. A duplicate key is legal YAML: the last
+    // value wins (as on the server), and a superseded value gets syntactic
+    // checks only — the server never validates it semantically either.
+    const first = lines[0];
+    let entries;
+    if (first !== undefined && first.indent === 0 && first.text.startsWith("{")) {
+        entries = collectRootFlowEntries(lines);
+    }
+    else if (first !== undefined && first.indent === 0 && first.text.startsWith("[")) {
+        throw new ManifestParseError("manifest.yaml must be a mapping of keys — see the manifest docs", first.num);
+    }
+    else {
+        entries = collectBlockEntries(lines);
+    }
+    // Pass 2: parse each (winning) entry.
+    const doc = {
+        run_as: "user",
+        saved_queries: [],
+        connectors: {},
+        llm: false,
+        adhoc_sql: [],
+    };
+    for (const [key, entry] of entries) {
+        if (key === "run_as") {
+            const value = inlineScalar(entry, key).value;
+            if (value !== "app" && value !== "user") {
+                throw new ManifestParseError(`"run_as" must be "app" or "user" (got "${value}")`, entry.keyLine.num);
+            }
+            doc.run_as = value;
+        }
+        else if (key === "llm") {
+            doc.llm = parseBool(inlineScalar(entry, key), entry.keyLine.num);
+        }
+        else if (key === "connectors") {
+            doc.connectors = parseConnectors(entry);
+        }
+        else {
+            // saved_queries / adhoc_sql: a list of names.
+            const items = parseStringList(entry, key);
+            if (key === "saved_queries")
+                doc.saved_queries = items;
+            else
+                doc.adhoc_sql = items;
+        }
+    }
+    validateDoc(doc, lines);
+    return doc;
+}
+function collectBlockEntries(lines) {
+    const entries = new Map();
+    let i = 0;
+    while (i < lines.length) {
+        const line = lines[i];
+        if (line.indent !== 0) {
+            throw new ManifestParseError(`Unexpected indentation before "${line.text}"`, line.num);
+        }
+        const match = line.text.match(BLOCK_KEY);
+        if (!match) {
+            throw new ManifestParseError(`Expected "key: value" or "key:" at "${line.text}"`, line.num);
+        }
+        const key = match[1];
+        if (!ALLOWED_KEYS.includes(key)) {
+            throw new ManifestParseError(`Unknown manifest key "${key}" — allowed keys: ${ALLOWED_KEYS.join(", ")}`, line.num);
+        }
+        i += 1;
+        const children = [];
+        while (i < lines.length && lines[i].indent > 0) {
+            children.push(lines[i]);
+            i += 1;
+        }
+        const entry = { keyLine: line, inline: (match[2] ?? "").trim(), children };
+        checkEntrySyntax(entry);
+        entries.set(key, entry);
+    }
+    return entries;
+}
+// The whole document is one flow mapping, e.g. `{run_as: app, llm: true}` —
+// PyYAML reads it as a dict, so the server accepts it. Flow collections may
+// span lines, so the lines are joined before scanning.
+function collectRootFlowEntries(lines) {
+    const keyLine = lines[0];
+    const joined = lines.map((l) => l.text).join(" ");
+    checkFlowBalanced(joined, keyLine.num); // also rejects content after the "}"
+    const entries = new Map();
+    const inner = joined.slice(1, joined.lastIndexOf("}")).trim();
+    if (!inner)
+        return entries;
+    for (const part of splitFlowEntries(inner, keyLine.num, "the manifest flow mapping")) {
+        // A part that isn't "key: value" is a lone scalar key with a null value
+        // (e.g. "{run_as}" or the no-space "{llm:true}") — name it like the server.
+        const match = part.match(FLOW_KEY);
+        const key = match ? match[1] : part;
+        if (!ALLOWED_KEYS.includes(key)) {
+            throw new ManifestParseError(`Unknown manifest key "${key}" — allowed keys: ${ALLOWED_KEYS.join(", ")}`, keyLine.num);
+        }
+        entries.set(key, { keyLine, inline: match ? match[2].trim() : "", children: [] });
+    }
+    return entries;
+}
+function requireNoChildren(entry, key) {
+    const extra = entry.children[0];
+    if (extra !== undefined) {
+        throw new ManifestParseError(`Unexpected indented block under "${key}"`, extra.num);
+    }
+}
+function inlineScalar(entry, key) {
+    requireNoChildren(entry, key);
+    return scalar(entry.inline, entry.keyLine.num);
+}
+function parseStringList(entry, key) {
+    const { keyLine, inline, children } = entry;
+    if (inline) {
+        requireNoChildren(entry, key);
+        if (inline.startsWith("[") && inline.endsWith("]")) {
+            return parseFlowList(inline, keyLine.num).map((s) => listString(s, key, keyLine.num));
+        }
+        throw new ManifestParseError(`"${key}" must be a list of names — e.g.\n${key}:\n  - some_name`, keyLine.num);
+    }
+    if (children.length === 0) {
+        throw new ManifestParseError(`"${key}" must list at least one name`, keyLine.num);
+    }
+    const itemIndent = children[0].indent;
+    return children.map((item) => {
+        if (item.indent !== itemIndent) {
+            throw new ManifestParseError(`Inconsistent indentation in the "${key}" list — every "- " item must line up`, item.num);
+        }
+        if (!item.text.startsWith("- ") && item.text !== "-") {
+            throw new ManifestParseError(`Expected a "- name" list item under "${key}" (got "${item.text}")`, item.num);
+        }
+        return listString(scalar(item.text.slice(1), item.num), key, item.num);
+    });
+}
+// A connector name entry. In block context the colon must be followed by
+// whitespace or end the line; in flow context PyYAML also allows the colon to
+// sit directly before a flow opener ("{stripe:[GET /x]}").
+const CONNECTOR_BLOCK_ENTRY = /^("[^"]*"|'[^']*'|[^"':\s][^":]*?)\s*:(?:\s+(.*))?$/;
+const CONNECTOR_FLOW_ENTRY = /^("[^"]*"|'[^']*'|[^"':\s][^":]*?)\s*:(?=$|[\s[{])\s*(.*)$/;
+function connectorName(raw, num) {
+    const s = scalar(raw, num);
+    const name = s.value.trim();
+    if (!name)
+        throw new ManifestParseError("Connector names must be non-empty", num);
+    if (!s.quoted && isYamlNonString(name)) {
+        throw new ManifestParseError(`Connector names under "connectors" must be strings (got "${name}")`, num);
+    }
+    return name;
+}
+function parseConnectors(entry) {
+    const { keyLine, inline, children } = entry;
+    if (inline) {
+        requireNoChildren(entry, "connectors");
+        if (inline.startsWith("{") && inline.endsWith("}")) {
+            return parseConnectorsFlowMap(inline, keyLine.num);
+        }
+        throw new ManifestParseError('"connectors" takes an indented block (or a {flow map}): connector names, each with a list of endpoints', keyLine.num);
+    }
+    if (children.length === 0) {
+        throw new ManifestParseError('"connectors" must map at least one connector to its endpoints', keyLine.num);
+    }
+    const connectors = {};
+    const nameIndent = children[0].indent;
+    let i = 0;
+    while (i < children.length) {
+        const nameLine = children[i];
+        if (nameLine.indent !== nameIndent) {
+            throw new ManifestParseError('Inconsistent indentation under "connectors" — every connector name must line up', nameLine.num);
+        }
+        const match = nameLine.text.match(CONNECTOR_BLOCK_ENTRY);
+        if (!match) {
+            throw new ManifestParseError(`Expected a connector name (e.g. "stripe:") under "connectors" (got "${nameLine.text}")`, nameLine.num);
+        }
+        const name = connectorName(match[1], nameLine.num);
+        const inlineValue = (match[2] ?? "").trim();
+        i += 1;
+        let endpoints = [];
+        if (inlineValue) {
+            const extra = children[i];
+            if (extra !== undefined && extra.indent > nameIndent) {
+                throw new ManifestParseError(`Unexpected indented block under "${name}" after an inline value`, extra.num);
+            }
+            if (!(inlineValue.startsWith("[") && inlineValue.endsWith("]"))) {
+                throw new ManifestParseError(`"${name}" must list its endpoints as "- <METHOD> </path>" lines or a [flow list]`, nameLine.num);
+            }
+            endpoints = parseFlowList(inlineValue, nameLine.num);
+        }
+        else {
+            const first = children[i];
+            const endpointIndent = first !== undefined && first.indent > nameIndent ? first.indent : 0;
+            while (i < children.length && children[i].indent > nameIndent) {
+                const item = children[i];
+                if (item.indent !== endpointIndent) {
+                    throw new ManifestParseError(`Inconsistent indentation in the endpoint list under "${name}"`, item.num);
+                }
+                if (!item.text.startsWith("- ")) {
+                    throw new ManifestParseError(`Expected a "- <METHOD> </path>" endpoint under "${name}" (got "${item.text}")`, item.num);
+                }
+                endpoints.push(scalar(item.text.slice(1), item.num));
+                i += 1;
+            }
+        }
+        if (endpoints.length === 0) {
+            throw new ManifestParseError(`"${name}" must list at least one "<METHOD> </path>" endpoint`, nameLine.num);
+        }
+        // A repeated connector name is legal YAML — the last mapping wins.
+        connectors[name] = endpoints.map((e) => normalizeEndpoint(name, e.value, nameLine.num));
+    }
+    return connectors;
+}
+function parseConnectorsFlowMap(value, num) {
+    const connectors = {};
+    const inner = value.slice(1, -1).trim();
+    if (!inner)
+        return connectors; // {} is a valid empty mapping, as on the server
+    for (const part of splitFlowEntries(inner, num, '"connectors" flow map')) {
+        const match = part.match(CONNECTOR_FLOW_ENTRY);
+        if (!match) {
+            throw new ManifestParseError(`Expected "connector: [endpoints]" in the "connectors" flow map (got "${part}")`, num);
+        }
+        const name = connectorName(match[1], num);
+        const endpointsValue = match[2].trim();
+        if (!(endpointsValue.startsWith("[") && endpointsValue.endsWith("]"))) {
+            throw new ManifestParseError(`"${name}" must list its endpoints as a [flow list] in the "connectors" flow map`, num);
+        }
+        const endpoints = parseFlowList(endpointsValue, num);
+        if (endpoints.length === 0) {
+            throw new ManifestParseError(`"${name}" must list at least one "<METHOD> </path>" endpoint`, num);
+        }
+        connectors[name] = endpoints.map((e) => normalizeEndpoint(name, e.value, num));
+    }
+    return connectors;
+}
+function normalizeEndpoint(connector, entry, num) {
+    const parts = entry.split(/\s+/);
+    if (parts.length !== 2) {
+        throw new ManifestParseError(`"${entry}" under "${connector}" is not a valid endpoint — use "<METHOD> </path>", e.g. "GET /v1/balance"`, num);
+    }
+    const method = parts[0].toUpperCase();
+    const path = parts[1];
+    if (!HTTP_METHODS.includes(method)) {
+        throw new ManifestParseError(`"${parts[0]}" is not an HTTP method — use one of: ${HTTP_METHODS.join(", ")}`, num);
+    }
+    if (!path.startsWith("/")) {
+        throw new ManifestParseError(`"${path}" must start with "/" — e.g. "GET /v1/balance"`, num);
+    }
+    if (path.includes("*") && (!path.endsWith("/*") || path.slice(0, -1).includes("*"))) {
+        throw new ManifestParseError(`"${path}" has an unsupported wildcard — only a trailing "/*" segment is allowed (no mid-path globs)`, num);
+    }
+    const segments = path.replace(/\*$/, "").split("/");
+    if (segments.some((seg) => seg === "." || seg === "..")) {
+        throw new ManifestParseError(`"${path}" must not contain "." or ".." path segments`, num);
+    }
+    return `${method} ${path}`;
+}
+function validateDoc(doc, lines) {
+    const lineOf = (token) => lines.find((l) => l.text.includes(token))?.num ?? 0;
+    for (const name of doc.saved_queries) {
+        if (!SAVED_QUERY_NAME.test(name)) {
+            throw new ManifestParseError(`"${name}" is not a valid saved-query name — 1-80 lowercase letters, digits or underscores`, lineOf(name));
+        }
+    }
+    doc.saved_queries = [...new Set(doc.saved_queries)].sort();
+    doc.adhoc_sql = [...new Set(doc.adhoc_sql)].sort();
+    for (const name of Object.keys(doc.connectors)) {
+        doc.connectors[name] = [...new Set(doc.connectors[name])].sort();
+    }
+}
+export function documentOperations(doc) {
+    const ops = [];
+    for (const name of doc.saved_queries) {
+        ops.push({ type: "saved_query", id: name, label: `saved query "${name}"` });
+    }
+    for (const [connector, endpoints] of Object.entries(doc.connectors)) {
+        for (const endpoint of endpoints) {
+            ops.push({
+                type: "sc_endpoint",
+                id: `${connector}:${endpoint}`,
+                label: `"${endpoint}" on "${connector}"`,
+            });
+        }
+    }
+    if (doc.llm)
+        ops.push({ type: "llm", id: "*", label: "LLM access" });
+    for (const name of doc.adhoc_sql) {
+        ops.push({ type: "connector", id: name, label: `ad-hoc SQL on "${name}"` });
+    }
+    return ops;
+}
+export function renderManifestSummary(doc) {
+    const lines = [];
+    lines.push(doc.run_as === "app"
+        ? "run_as: app — runs with its ratified authority (diffs need ratification)"
+        : "run_as: user — runs as each caller; no borrowed authority, nothing to ratify");
+    const ops = documentOperations(doc);
+    if (ops.length === 0) {
+        lines.push("operations: none declared");
+    }
+    else {
+        lines.push(`operations (${ops.length}):`);
+        for (const op of ops)
+            lines.push(`  - ${op.label}`);
+    }
+    if (doc.adhoc_sql.length > 0) {
+        lines.push("warning: adhoc_sql grants ad-hoc SQL authority — scarce by design; prefer saved queries");
+    }
+    return lines.join("\n");
+}
+export function renderManifestDeployOutcome(m) {
+    const lines = [];
+    for (const warning of m.warnings)
+        lines.push(`warning: ${warning}`);
+    switch (m.action) {
+        case "none":
+            break; // no manifest, nothing to say
+        case "unchanged":
+            lines.push("Manifest unchanged.");
+            break;
+        case "ratified":
+            lines.push(m.added.length > 0
+                ? `Manifest ratified (you hold: ${m.added.join(", ")}).`
+                : "Manifest ratified.");
+            if (m.removed.length > 0)
+                lines.push(`Removed: ${m.removed.join(", ")}.`);
+            break;
+        case "removed":
+            lines.push("Manifest removed — the app is back to pass-through (runs as each caller).");
+            if (m.removed.length > 0)
+                lines.push(`Shed: ${m.removed.join(", ")}.`);
+            break;
+    }
+    return lines;
+}