@mx-space/cli 0.14.2 → 0.15.1

package/dist/src/domain/envelope-compat.js

@@ -0,0 +1,121 @@
+/**
+ * @deprecated Compat shim for the V2 → V3 mx-core wire-format transition.
+ *
+ * Remove this file once all deployments referenced by the CLI's user base are
+ * confirmed V3 (`API_VERSION = 3` in mx-core). Removal checklist:
+ *
+ *   1. Delete this file (`envelope-compat.ts`) and its test
+ *      (`test/domain/envelope-compat.test.ts`).
+ *   2. In `src/services/Api.ts`, `grep -n 'COMPAT:envelope'` and delete the
+ *      two normalizer calls + the `Ref<WireVersion>` field + verbose log
+ *      annotation.
+ *   3. In `src/services/Config.ts`, change `parsed.apiVersion ?? 2` to
+ *      `?? 3`.
+ *   4. In `test/integration/cli-post-list.test.ts` and
+ *      `test/integration/cli-error-envelope.test.ts`, drop the V2 `it`
+ *      block; keep only the V3 mock.
+ *   5. Run `pnpm -C packages/cli typecheck && pnpm -C packages/cli test` —
+ *      no references should remain.
+ *
+ * Full design: `packages/cli/docs/specs/2026-05-21-v2-v3-envelope-compat-layer.md`.
+ */
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+/**
+ * Sniff the wire version from a parsed response body. Returns `null` if the
+ * body is too small (raw scalar, FormData echo, dry-run synthetic) to decide.
+ * Callers must tolerate `null`.
+ *
+ * V3 markers (any one suffices):
+ *   - object has a `meta` key, OR
+ *   - object has `error.code` (string) or `error.message` (string).
+ *
+ * V2 markers (any one):
+ *   - object has a root-level `pagination` key, OR
+ *   - object has a root-level `message: string | string[]` and no `error` key.
+ *
+ * When both V2 and V3 markers are present, V3 wins.
+ */
+export const detectWireVersion = (body) => {
+    if (!isRecord(body))
+        return null;
+    // V3 markers win.
+    if ('meta' in body)
+        return 'v3';
+    if (isRecord(body.error)) {
+        const err = body.error;
+        if (typeof err.code === 'string' || typeof err.message === 'string') {
+            return 'v3';
+        }
+    }
+    // V2 markers.
+    if ('pagination' in body)
+        return 'v2';
+    if (!('error' in body) &&
+        (typeof body.message === 'string' ||
+            (Array.isArray(body.message) &&
+                body.message.every((m) => typeof m === 'string')))) {
+        return 'v2';
+    }
+    return null;
+};
+/**
+ * Normalize a 2xx response body to the V3 shape `{ data, meta? }`.
+ *
+ *   - V3 (`{ data, meta? }`)                  → returned as-is
+ *   - V2 paginated (`{ data, pagination }`)   → `{ data, meta: { pagination } }`
+ *   - V2 bare (`{ data }`)                    → returned as-is
+ *   - Anything else (arrays, scalars, non-object, already-unwrapped doc) → unchanged
+ *
+ * Shape-tolerant: unrecognized inputs pass through unchanged. Never mutates
+ * the input.
+ */
+export const normalizeSuccessBody = (body) => {
+    if (!isRecord(body))
+        return body;
+    // Already V3 (or carries a meta block) — pass through.
+    if ('meta' in body)
+        return body;
+    // V2 paginated: lift root `pagination` under `meta`.
+    if ('data' in body && 'pagination' in body) {
+        const { pagination, ...rest } = body;
+        return { ...rest, meta: { pagination } };
+    }
+    return body;
+};
+/**
+ * Normalize a non-2xx response body to a flat `{ code?, message?, details? }`
+ * tuple.
+ *
+ *   - V3 (`{ error: { code, message, details? } }`) → unwrapped
+ *   - V2 (`{ message: string | string[], code?, details? }`) → flattened.
+ *     Array messages join with `'; '` to match the legacy `extractMessage`
+ *     helper in `api-envelope.ts`.
+ *   - Non-object body → `{}`
+ *
+ * Never throws, never mutates.
+ */
+export const normalizeErrorBody = (body) => {
+    if (!isRecord(body))
+        return {};
+    // V3 shape.
+    if (isRecord(body.error)) {
+        const err = body.error;
+        return {
+            code: typeof err.code === 'string' ? err.code : undefined,
+            message: typeof err.message === 'string' ? err.message : undefined,
+            details: err.details,
+        };
+    }
+    // V2 shape — flat.
+    const rawMsg = body.message;
+    let message;
+    if (typeof rawMsg === 'string') {
+        message = rawMsg;
+    }
+    else if (Array.isArray(rawMsg) &&
+        rawMsg.every((m) => typeof m === 'string')) {
+        message = rawMsg.join('; ');
+    }
+    const code = typeof body.code === 'string' ? body.code : undefined;
+    return { code, message, details: body.details };
+};

package/dist/src/domain/envelope.d.ts

@@ -0,0 +1,34 @@
+export type EnvelopeKind = 'post' | 'note';
+export interface ParsedEnvelope {
+    readonly kind: EnvelopeKind;
+    readonly meta: Record<string, unknown>;
+    readonly contentXml: string;
+    readonly sourceMap: Record<string, number>;
+}
+export declare function flagToTag(flag: string): string;
+export declare function tagToFlag(tag: string): string;
+export declare function parseEnvelope(xml: string, kind: EnvelopeKind): ParsedEnvelope;
+export interface EnvelopeMeta {
+    title?: string;
+    slug?: string;
+    category?: string;
+    topic?: string;
+    state?: 'publish' | 'draft';
+    summary?: string;
+    copyright?: boolean;
+    pin?: string;
+    pinOrder?: number;
+    related?: string[];
+    tags?: string[];
+    mood?: string;
+    weather?: string;
+    publicAt?: string;
+    password?: string;
+    bookmark?: boolean;
+    location?: string;
+    subtitle?: string;
+    order?: number;
+    format?: 'lexical' | 'markdown';
+}
+export declare function coerceMeta(raw: Record<string, unknown>): EnvelopeMeta;
+export declare function listUnknownMetaKeys(raw: Record<string, unknown>, known: ReadonlyArray<string>): string[];

package/dist/src/domain/envelope.js

@@ -0,0 +1,355 @@
+import { ValidationXml } from './errors';
+const ROOT_TAGS = {
+    post: 'mxpost',
+    note: 'mxnote',
+};
+const ARRAY_TAGS = {
+    tags: 'tag',
+    related: 'id',
+};
+const SKIP_TEXT_RE = /^\s*$/;
+function kebabToCamel(name) {
+    return name.replaceAll(/-([a-z])/g, (_, c) => c.toUpperCase());
+}
+function camelToKebab(name) {
+    return name.replaceAll(/([A-Z])/g, (_, c) => `-${c.toLowerCase()}`);
+}
+export function flagToTag(flag) {
+    return kebabToCamel(flag.replace(/^--/, ''));
+}
+export function tagToFlag(tag) {
+    return `--${camelToKebab(tag)}`;
+}
+function tokenize(xml) {
+    const tokens = [];
+    let i = 0;
+    let line = 1;
+    while (i < xml.length) {
+        const ch = xml[i];
+        if (ch === '<') {
+            if (xml.startsWith('<!--', i)) {
+                const end = xml.indexOf('-->', i + 4);
+                if (end < 0) {
+                    throw new ValidationXml({
+                        message: 'unterminated XML comment',
+                        line,
+                        details: { line },
+                    });
+                }
+                line += countLines(xml.slice(i, end + 3));
+                i = end + 3;
+                continue;
+            }
+            if (xml.startsWith('<![CDATA[', i)) {
+                const end = xml.indexOf(']]>', i + 9);
+                if (end < 0) {
+                    throw new ValidationXml({
+                        message: 'unterminated CDATA',
+                        line,
+                        details: { line },
+                    });
+                }
+                const inner = xml.slice(i + 9, end);
+                tokens.push({ kind: 'cdata', text: inner, line });
+                line += countLines(xml.slice(i, end + 3));
+                i = end + 3;
+                continue;
+            }
+            const close = xml.indexOf('>', i);
+            if (close < 0) {
+                throw new ValidationXml({
+                    message: 'unterminated tag',
+                    line,
+                    details: { line },
+                });
+            }
+            const raw = xml.slice(i + 1, close).trim();
+            if (raw.startsWith('/')) {
+                tokens.push({ kind: 'close', name: raw.slice(1).trim(), line });
+            }
+            else if (raw.endsWith('/')) {
+                const name = raw.slice(0, -1).trim().split(/\s+/)[0] ?? '';
+                tokens.push({ kind: 'self', name, raw, line });
+            }
+            else {
+                const name = raw.split(/\s+/)[0] ?? '';
+                tokens.push({ kind: 'open', name, raw, line });
+            }
+            line += countLines(xml.slice(i, close + 1));
+            i = close + 1;
+        }
+        else {
+            const next = xml.indexOf('<', i);
+            const text = xml.slice(i, next < 0 ? xml.length : next);
+            tokens.push({ kind: 'text', text, line });
+            line += countLines(text);
+            i = next < 0 ? xml.length : next;
+        }
+    }
+    return tokens;
+}
+function countLines(s) {
+    let count = 0;
+    for (let i = 0; i < s.length; i++) {
+        if (s.charCodeAt(i) === 10)
+            count++;
+    }
+    return count;
+}
+function decodeXmlEntities(s) {
+    return s
+        .replaceAll('&lt;', '<')
+        .replaceAll('&gt;', '>')
+        .replaceAll('&quot;', '"')
+        .replaceAll('&apos;', "'")
+        .replaceAll('&amp;', '&');
+}
+export function parseEnvelope(xml, kind) {
+    const tokens = tokenize(xml);
+    const rootName = ROOT_TAGS[kind];
+    const rootStart = tokens.findIndex((t) => t.kind === 'open' && t.name === rootName);
+    if (rootStart < 0) {
+        throw new ValidationXml({
+            message: `expected root <${rootName}>`,
+            line: 1,
+            details: { line: 1 },
+        });
+    }
+    let depth = 0;
+    let rootEnd = -1;
+    for (let i = rootStart; i < tokens.length; i++) {
+        const t = tokens[i];
+        if (t.kind === 'open' && t.name === rootName)
+            depth++;
+        else if (t.kind === 'close' && t.name === rootName) {
+            depth--;
+            if (depth === 0) {
+                rootEnd = i;
+                break;
+            }
+        }
+    }
+    if (rootEnd < 0) {
+        throw new ValidationXml({
+            message: `unterminated <${rootName}>`,
+            line: tokens[rootStart]?.line ?? 1,
+            details: { line: tokens[rootStart]?.line ?? 1 },
+        });
+    }
+    const inner = tokens.slice(rootStart + 1, rootEnd);
+    const meta = {};
+    const sourceMap = {};
+    let contentXml = '';
+    let i = 0;
+    while (i < inner.length) {
+        const t = inner[i];
+        if (t.kind === 'text' || t.kind === 'cdata') {
+            i++;
+            continue;
+        }
+        if (t.kind === 'open' && t.name === 'meta') {
+            const closeIdx = findMatchingClose(inner, i, 'meta');
+            parseMeta(inner.slice(i + 1, closeIdx), meta, sourceMap);
+            i = closeIdx + 1;
+            continue;
+        }
+        if (t.kind === 'open' && t.name === 'content') {
+            const closeIdx = findMatchingClose(inner, i, 'content');
+            contentXml = renderInnerXml(inner.slice(i + 1, closeIdx));
+            sourceMap.content = t.line;
+            i = closeIdx + 1;
+            continue;
+        }
+        if (t.kind === 'self' && t.name === 'content') {
+            contentXml = '';
+            sourceMap.content = t.line;
+            i++;
+            continue;
+        }
+        if (t.kind === 'open' || t.kind === 'self') {
+            throw new ValidationXml({
+                message: `unexpected <${t.name}> at root`,
+                line: t.line,
+                details: { line: t.line },
+            });
+        }
+        i++;
+    }
+    return { kind, meta, contentXml, sourceMap };
+}
+function findMatchingClose(tokens, startOpen, name) {
+    let depth = 0;
+    for (let i = startOpen; i < tokens.length; i++) {
+        const t = tokens[i];
+        if (t.kind === 'open' && t.name === name)
+            depth++;
+        else if (t.kind === 'close' && t.name === name) {
+            depth--;
+            if (depth === 0)
+                return i;
+        }
+    }
+    throw new ValidationXml({
+        message: `unterminated <${name}>`,
+        line: tokens[startOpen]?.line ?? 1,
+        details: { line: tokens[startOpen]?.line ?? 1 },
+    });
+}
+function parseMeta(tokens, meta, sourceMap) {
+    let i = 0;
+    while (i < tokens.length) {
+        const t = tokens[i];
+        if (t.kind === 'text' || t.kind === 'cdata') {
+            i++;
+            continue;
+        }
+        if (t.kind === 'close') {
+            i++;
+            continue;
+        }
+        if (t.kind === 'self') {
+            const key = t.name;
+            meta[key] = '';
+            sourceMap[`meta.${key}`] = t.line;
+            i++;
+            continue;
+        }
+        if (t.kind === 'open') {
+            const name = t.name;
+            const closeIdx = findMatchingClose(tokens, i, name);
+            const inner = tokens.slice(i + 1, closeIdx);
+            if (ARRAY_TAGS[name]) {
+                const childTag = ARRAY_TAGS[name];
+                const items = [];
+                let j = 0;
+                while (j < inner.length) {
+                    const c = inner[j];
+                    if (c.kind === 'open' && c.name === childTag) {
+                        const cc = findMatchingClose(inner, j, childTag);
+                        items.push(textOf(inner.slice(j + 1, cc)));
+                        j = cc + 1;
+                    }
+                    else {
+                        j++;
+                    }
+                }
+                meta[name] = items;
+            }
+            else {
+                meta[name] = textOf(inner);
+            }
+            sourceMap[`meta.${name}`] = t.line;
+            i = closeIdx + 1;
+            continue;
+        }
+        i++;
+    }
+}
+function textOf(tokens) {
+    let s = '';
+    for (const t of tokens) {
+        if (t.kind === 'text' && t.text)
+            s += t.text;
+        else if (t.kind === 'cdata' && t.text)
+            s += t.text;
+    }
+    return decodeXmlEntities(s).trim();
+}
+function renderInnerXml(tokens) {
+    let out = '';
+    for (const t of tokens) {
+        if (t.kind === 'text')
+            out += t.text ?? '';
+        else if (t.kind === 'cdata')
+            out += `<![CDATA[${t.text ?? ''}]]>`;
+        else if (t.kind === 'open')
+            out += `<${t.raw ?? t.name}>`;
+        else if (t.kind === 'self')
+            out += `<${t.raw ?? `${t.name}/`}>`;
+        else if (t.kind === 'close')
+            out += `</${t.name}>`;
+    }
+    if (out.startsWith('\n'))
+        out = out.slice(1);
+    if (out.endsWith('\n'))
+        out = out.slice(0, -1);
+    if (SKIP_TEXT_RE.test(out))
+        return '';
+    return out;
+}
+export function coerceMeta(raw) {
+    const out = {};
+    const get = (key) => raw[key];
+    const title = get('title');
+    if (typeof title === 'string')
+        out.title = title;
+    const slug = get('slug');
+    if (typeof slug === 'string')
+        out.slug = slug;
+    const category = get('category');
+    if (typeof category === 'string')
+        out.category = category;
+    const topic = get('topic');
+    if (typeof topic === 'string')
+        out.topic = topic;
+    const summary = get('summary');
+    if (typeof summary === 'string')
+        out.summary = summary;
+    const state = get('state');
+    if (state === 'publish' || state === 'draft')
+        out.state = state;
+    const copyright = get('copyright');
+    if (typeof copyright === 'string') {
+        out.copyright = copyright === 'true';
+    }
+    const pin = get('pin');
+    if (typeof pin === 'string')
+        out.pin = pin;
+    const pinOrder = get('pinOrder');
+    if (typeof pinOrder === 'string' && pinOrder.length > 0) {
+        const n = Number(pinOrder);
+        if (!Number.isNaN(n))
+            out.pinOrder = n;
+    }
+    const tags = get('tags');
+    if (Array.isArray(tags))
+        out.tags = tags;
+    const related = get('related');
+    if (Array.isArray(related))
+        out.related = related;
+    const mood = get('mood');
+    if (typeof mood === 'string')
+        out.mood = mood;
+    const weather = get('weather');
+    if (typeof weather === 'string')
+        out.weather = weather;
+    const publicAt = get('publicAt');
+    if (typeof publicAt === 'string')
+        out.publicAt = publicAt;
+    const password = get('password');
+    if (typeof password === 'string')
+        out.password = password;
+    const bookmark = get('bookmark');
+    if (typeof bookmark === 'string') {
+        out.bookmark = bookmark === 'true';
+    }
+    const location = get('location');
+    if (typeof location === 'string')
+        out.location = location;
+    const subtitle = get('subtitle');
+    if (typeof subtitle === 'string')
+        out.subtitle = subtitle;
+    const order = get('order');
+    if (typeof order === 'string' && order.length > 0) {
+        const n = Number(order);
+        if (!Number.isNaN(n))
+            out.order = n;
+    }
+    const format = get('format');
+    if (format === 'lexical' || format === 'markdown')
+        out.format = format;
+    return out;
+}
+export function listUnknownMetaKeys(raw, known) {
+    return Object.keys(raw).filter((k) => !known.includes(k));
+}