@mx-space/cli 0.14.2 → 0.15.1

package/dist/src/cli/topic/index.js

@@ -0,0 +1,32 @@
+import { Command } from '@effect/cli';
+import { registerCommandHelp } from '../help/registry';
+import { create } from './create';
+import { del } from './delete';
+import { get } from './get';
+import { list } from './list';
+import { update } from './update';
+const help = registerCommandHelp({
+    name: 'topic',
+    description: 'manage topics',
+    skillChapter: 'commands-topic',
+    verbs: [
+        { name: 'list', description: 'list topics' },
+        { name: 'get', args: ['<slugOrId>'], description: 'show a single topic' },
+        {
+            name: 'create',
+            args: ['--name <n>', '--slug <s>', '[--description ...]', '[--icon ...]'],
+            description: 'create a topic',
+        },
+        {
+            name: 'update',
+            args: ['<slugOrId>', '[--name ...]', '...'],
+            description: 'update a topic',
+        },
+        {
+            name: 'delete',
+            args: ['<slugOrId>', '[--force]'],
+            description: 'delete a topic',
+        },
+    ],
+});
+export const topicCmd = Command.make('topic').pipe(Command.withDescription(help.description), Command.withSubcommands([list, get, create, update, del]));

package/dist/src/cli/topic/list.d.ts

@@ -0,0 +1,4 @@
+import { Command } from '@effect/cli';
+import { Api } from '../../services/Api';
+import { Renderer } from '../../services/Renderer';
+export declare const list: Command.Command<"list", Api | Renderer, import("../../services/Api").ApiError, {}>;

package/dist/src/cli/topic/list.js

@@ -0,0 +1,10 @@
+import { Command } from '@effect/cli';
+import { Effect } from 'effect';
+import { Api } from '../../services/Api';
+import { Renderer } from '../../services/Renderer';
+export const list = Command.make('list', {}, () => Effect.gen(function* () {
+    const api = yield* Api;
+    const renderer = yield* Renderer;
+    const res = yield* api.request('/topics/all');
+    yield* renderer.emitSuccess(res);
+}));

package/dist/src/cli/topic/update.d.ts

@@ -0,0 +1,11 @@
+import { Command } from '@effect/cli';
+import { Option } from 'effect';
+import { Api } from '../../services/Api';
+import { Renderer } from '../../services/Renderer';
+export declare const update: Command.Command<"update", Api | Renderer, import("../../services/Api").ApiError, {
+    readonly slugOrId: string;
+    readonly name: Option.Option<string>;
+    readonly slug: Option.Option<string>;
+    readonly description: Option.Option<string>;
+    readonly icon: Option.Option<string>;
+}>;

package/dist/src/cli/topic/update.js

@@ -0,0 +1,51 @@
+import { Args, Command, Options } from '@effect/cli';
+import { Effect, Option } from 'effect';
+import { ResourceNotFound } from '../../domain/errors';
+import { Api } from '../../services/Api';
+import { Renderer } from '../../services/Renderer';
+import { isSnowflakeId } from '../../services/Resolver';
+const slugOrId = Args.text({ name: 'slugOrId' });
+const name = Options.text('name').pipe(Options.optional);
+const slug = Options.text('slug').pipe(Options.optional);
+const description = Options.text('description').pipe(Options.optional);
+const icon = Options.text('icon').pipe(Options.optional);
+const resolveTopicId = (api, ref) => Effect.gen(function* () {
+    if (isSnowflakeId(ref))
+        return ref;
+    const res = yield* api
+        .request(`/topics/slug/${encodeURIComponent(ref)}`)
+        .pipe(Effect.catchAll(() => Effect.succeed(null)));
+    const id = (res && res.id) ??
+        (res && res.data?.id);
+    if (!id) {
+        return yield* Effect.fail(new ResourceNotFound({
+            kind: 'topic',
+            ref,
+            message: `topic not found: ${ref}`,
+        }));
+    }
+    return id;
+});
+export const update = Command.make('update', { slugOrId, name, slug, description, icon }, ({ slugOrId, name, slug, description, icon }) => Effect.gen(function* () {
+    const body = {};
+    const n = Option.getOrUndefined(name);
+    if (n)
+        body.name = n;
+    const s = Option.getOrUndefined(slug);
+    if (s)
+        body.slug = s;
+    const d = Option.getOrUndefined(description);
+    if (d)
+        body.description = d;
+    const ic = Option.getOrUndefined(icon);
+    if (ic)
+        body.icon = ic;
+    const api = yield* Api;
+    const renderer = yield* Renderer;
+    const id = yield* resolveTopicId(api, slugOrId);
+    const res = yield* api.request(`/topics/${id}`, {
+        method: 'PATCH',
+        body,
+    });
+    yield* renderer.emitSuccess(res);
+}));

package/dist/src/cli/ui/index.d.ts

@@ -0,0 +1,24 @@
+export { ANSI, isColorEnabled, visibleLen, wrap } from '../render';
+export declare const ok: (text: string, color: boolean) => string;
+export declare const fail: (text: string, color: boolean) => string;
+export declare const arrow: (text: string, color: boolean) => string;
+export declare const star: (text: string, color: boolean) => string;
+export declare const dot: (text: string, color: boolean) => string;
+export declare const dim: (text: string, color: boolean) => string;
+export declare const bold: (text: string, color: boolean) => string;
+export declare const roundedBox: (lines: string[]) => string;
+/** Indent every line of `text` by `pad` spaces. */
+export declare const indent: (text: string, pad: number) => string;
+export interface TableColumn {
+    readonly key: string;
+    readonly label: string;
+    /** Minimum column width (auto-grows to fit content). */
+    readonly minWidth?: number;
+}
+export declare const renderTable: (cols: readonly TableColumn[], rows: readonly Record<string, string>[], opts: {
+    readonly color: boolean;
+    readonly prefix?: (row: number) => string;
+}) => string;
+export declare const humanDuration: (seconds: number) => string;
+/** Format milliseconds-since-epoch as `<duration>` until that point. */
+export declare const humanUntil: (epochMs: number) => string;

package/dist/src/cli/ui/index.js

@@ -0,0 +1,83 @@
+// Small TTY-aware UI primitives for command-specific rendering.
+//
+// `renderMarkdownToAnsi` (in ../render) handles structured prose, but
+// some commands need bespoke layouts — boxed device-codes, fixed-width tables,
+// status badges. Those primitives live here. Each takes an explicit
+// `{ color: boolean }` so callers can opt out (NO_COLOR / non-TTY).
+import { ANSI, visibleLen, wrap } from '../render';
+export { ANSI, isColorEnabled, visibleLen, wrap } from '../render';
+// ---------------------------------------------------------------------------
+// Badges — leading icon + text, coloured when permitted.
+// ---------------------------------------------------------------------------
+export const ok = (text, color) => `${wrap(ANSI.green, '✓', color)} ${text}`;
+export const fail = (text, color) => `${wrap(ANSI.red, '✗', color)} ${text}`;
+export const arrow = (text, color) => `${wrap(ANSI.cyan, '→', color)} ${text}`;
+export const star = (text, color) => `${wrap(ANSI.yellow, '✦', color)} ${text}`;
+export const dot = (text, color) => `${wrap(ANSI.cyan, '●', color)} ${text}`;
+export const dim = (text, color) => wrap(ANSI.dim, text, color);
+export const bold = (text, color) => wrap(ANSI.bold, text, color);
+// ---------------------------------------------------------------------------
+// Rounded box — `╭─╮│╰─╯`. Always unicode; modern terminals handle it.
+// ---------------------------------------------------------------------------
+export const roundedBox = (lines) => {
+    const inner = lines.map((l) => l);
+    const width = inner.reduce((max, l) => Math.max(max, visibleLen(l)), 0);
+    const horizontal = '─'.repeat(width + 2);
+    const top = `╭${horizontal}╮`;
+    const bottom = `╰${horizontal}╯`;
+    const middle = inner.map((l) => {
+        const pad = ' '.repeat(width - visibleLen(l));
+        return `│ ${l}${pad} │`;
+    });
+    return [top, ...middle, bottom].join('\n');
+};
+/** Indent every line of `text` by `pad` spaces. */
+export const indent = (text, pad) => {
+    const prefix = ' '.repeat(pad);
+    return text
+        .split('\n')
+        .map((l) => `${prefix}${l}`)
+        .join('\n');
+};
+export const renderTable = (cols, rows, opts) => {
+    if (rows.length === 0) {
+        return dim('(no rows)', opts.color);
+    }
+    const widths = cols.map((c) => Math.max(c.label.length, c.minWidth ?? 0, ...rows.map((r) => visibleLen(r[c.key] ?? ''))));
+    const renderRow = (cells) => cells
+        .map((cell, i) => {
+        const padLen = widths[i] - visibleLen(cell);
+        return `${cell}${' '.repeat(Math.max(0, padLen))}`;
+    })
+        .join('  ');
+    const header = wrap(ANSI.dim, renderRow(cols.map((c) => c.label.toUpperCase())), opts.color);
+    const body = rows.map((row, idx) => {
+        const prefix = opts.prefix?.(idx) ?? ' ';
+        return `${prefix} ${renderRow(cols.map((c) => row[c.key] ?? ''))}`;
+    });
+    return [`  ${header}`, ...body].join('\n');
+};
+// ---------------------------------------------------------------------------
+// Human-readable duration — seconds → "30 min", "2h 14m", "45s".
+// ---------------------------------------------------------------------------
+export const humanDuration = (seconds) => {
+    if (seconds < 0)
+        return 'expired';
+    if (seconds < 60)
+        return `${seconds}s`;
+    const minutes = Math.floor(seconds / 60);
+    if (minutes < 60)
+        return `${minutes} min`;
+    const hours = Math.floor(minutes / 60);
+    const remMin = minutes % 60;
+    if (hours < 24)
+        return remMin ? `${hours}h ${remMin}m` : `${hours}h`;
+    const days = Math.floor(hours / 24);
+    const remH = hours % 24;
+    return remH ? `${days}d ${remH}h` : `${days}d`;
+};
+/** Format milliseconds-since-epoch as `<duration>` until that point. */
+export const humanUntil = (epochMs) => {
+    const seconds = Math.round((epochMs - Date.now()) / 1000);
+    return humanDuration(seconds);
+};

package/dist/src/cli/update/index.d.ts

@@ -0,0 +1,10 @@
+import { Command } from '@effect/cli';
+import { Option } from 'effect';
+import { Renderer } from '../../services/Renderer';
+export declare const updateCmd: Command.Command<"update", Renderer, import("../../services/UpdateNotifier").RunUpdateError, {
+    readonly check: Option.Option<boolean>;
+    readonly prerelease: Option.Option<boolean>;
+    readonly pm: Option.Option<"npm" | "pnpm" | "yarn" | "bun">;
+    readonly force: Option.Option<boolean>;
+    readonly yes: Option.Option<boolean>;
+}>;

package/dist/src/cli/update/index.js

@@ -0,0 +1,142 @@
+import { createRequire } from 'node:module';
+import { Command, Options } from '@effect/cli';
+import { Effect, Option } from 'effect';
+import { Renderer } from '../../services/Renderer';
+import { make as makeUpdater, } from '../../services/UpdateNotifier';
+import { registerCommandHelp } from '../help/registry';
+import { bold, dim, fail, ok, star } from '../ui';
+registerCommandHelp({
+    name: 'update',
+    description: 'install the newest mxs release (auto, no prompt)',
+    isLeaf: true,
+    leafOptions: [
+        { flag: '--check', description: 'compare versions only; do not install' },
+        { flag: '--prerelease', description: 'use the `next` dist-tag channel' },
+        {
+            flag: '--pm <name>',
+            description: 'force package manager (one of: npm, pnpm, yarn, bun)',
+        },
+        { flag: '--force', description: 'bypass the 24h passive-check cache' },
+        {
+            flag: '--yes',
+            description: 'deprecated no-op (kept for back-compat; updates run without a prompt by default)',
+        },
+    ],
+});
+// Read package version once at module load. Walks up to find the cli
+// package.json so the lookup works for both dev (`tsx src/...`) and the
+// bundled `dist/*.mjs` layouts.
+const requireFrom = createRequire(import.meta.url);
+const resolveCliVersion = () => {
+    const candidates = [
+        '../package.json',
+        '../../package.json',
+        '../../../package.json',
+    ];
+    for (const candidate of candidates) {
+        try {
+            const pkg = requireFrom(candidate);
+            if (pkg.name === '@mx-space/cli' && typeof pkg.version === 'string') {
+                return pkg.version;
+            }
+        }
+        catch {
+            // try next candidate
+        }
+    }
+    return '0.0.0-unknown';
+};
+const CLI_VERSION = resolveCliVersion();
+const check = Options.boolean('check').pipe(Options.optional);
+const prerelease = Options.boolean('prerelease').pipe(Options.optional);
+const pm = Options.choice('pm', ['npm', 'pnpm', 'yarn', 'bun']).pipe(Options.optional);
+const force = Options.boolean('force').pipe(Options.optional);
+const yes = Options.boolean('yes').pipe(Options.optional);
+const optBool = (opt) => Option.getOrUndefined(opt);
+export const updateCmd = Command.make('update', { check, prerelease, pm, force, yes }, ({ check, prerelease, pm, force, yes }) => Effect.gen(function* () {
+    const renderer = yield* Renderer;
+    const outOpts = yield* renderer.options;
+    // Auto-install: `mxs update` no longer prompts. Foreground runs go
+    // through the same notifier as the passive background path; we do not
+    // wire `Editor.confirm` here because `runUpdate` itself stopped calling
+    // any confirmImpl.
+    const updater = makeUpdater();
+    const opts = {
+        currentVersion: CLI_VERSION,
+        check: optBool(check),
+        prerelease: optBool(prerelease),
+        pm: Option.getOrUndefined(pm),
+        force: optBool(force),
+        yes: optBool(yes),
+        json: outOpts.json,
+    };
+    const result = yield* updater.runUpdate(opts);
+    // The UpdateNotifier already streams `emitInfo` lines via deps.emitInfo
+    // (default: process.stderr). The renderer.emitSuccess emits the final
+    // structured result for JSON consumers + a closing info line in TTY.
+    const command = result.command ?? null;
+    if (result.upToDate) {
+        yield* renderer.emitView({
+            current: result.fromVersion,
+            latest: result.toVersion,
+            channel: result.channel,
+            up_to_date: true,
+        }, ({ color }) => ok(`up to date · ${bold(result.fromVersion, color)} ${dim(`(${result.channel})`, color)}`, color));
+        return;
+    }
+    if (result.cancelled) {
+        yield* renderer.emitView({
+            current: result.fromVersion,
+            latest: result.toVersion,
+            channel: result.channel,
+            pm: result.pm,
+            command,
+            cancelled: true,
+        }, ({ color }) => fail(`update cancelled · ${dim(`${result.fromVersion} → ${result.toVersion}`, color)}`, color));
+        return;
+    }
+    if (result.upgraded) {
+        yield* renderer.emitView({
+            current: result.fromVersion,
+            latest: result.toVersion,
+            channel: result.channel,
+            pm: result.pm,
+            upgraded: true,
+        }, ({ color }) => ok(`upgraded · ${bold(`${result.fromVersion} → ${result.toVersion}`, color)} ${dim(`(${result.channel}, ${result.pm})`, color)}`, color));
+        return;
+    }
+    // --check path: not up to date, but no install ran.
+    if (opts.check) {
+        yield* renderer.emitView({
+            current: result.fromVersion,
+            latest: result.toVersion,
+            channel: result.channel,
+            pm: result.pm,
+            up_to_date: false,
+        }, ({ color }) => {
+            const head = star('update available', color);
+            const versions = `   ${bold(result.fromVersion, color)}  →  ${bold(result.toVersion, color)}   ${dim(result.channel, color)}`;
+            const cmd = command
+                ? `\n\n   ${dim('run:', color)} ${bold(command, color)}`
+                : '';
+            return `${head}\n\n${versions}${cmd}`;
+        });
+        return;
+    }
+    // --dry-run path
+    yield* renderer.emitView({
+        current: result.fromVersion,
+        latest: result.toVersion,
+        channel: result.channel,
+        pm: result.pm,
+        command,
+        dry_run: true,
+    }, ({ color }) => {
+        const head = star('would upgrade', color);
+        const versions = `   ${bold(result.fromVersion, color)}  →  ${bold(result.toVersion, color)}   ${dim(result.channel, color)}`;
+        const cmd = command
+            ? `\n\n   ${dim('would run:', color)} ${bold(command, color)}`
+            : '';
+        return `${head}\n\n${versions}${cmd}`;
+    });
+}));

package/dist/src/domain/admin-link.d.ts

@@ -0,0 +1,12 @@
+import { Effect } from 'effect';
+import { Api } from '../services/Api';
+import { Renderer } from '../services/Renderer';
+export type AdminEditKind = 'posts' | 'notes' | 'pages' | 'projects';
+/**
+ * Resolve the server's admin URL from `/options/url`, build the admin
+ * edit-page URL for the given resource, and open it in the user's browser.
+ * Non-fatal: missing admin_url or browser-launch failures emit a warning
+ * and the parent effect continues.
+ */
+export declare const openAdminEdit: (kind: AdminEditKind, id: string) => Effect.Effect<void, import("../services/Api").ApiError, Api | Renderer>;
+export declare const openAdminDraftEdit: (kind: AdminEditKind, draftId: string, refId?: string) => Effect.Effect<void, import("../services/Api").ApiError, Api | Renderer>;

package/dist/src/domain/admin-link.js

@@ -0,0 +1,45 @@
+import { Effect } from 'effect';
+import open from 'open';
+import { Api } from '../services/Api';
+import { Renderer } from '../services/Renderer';
+const buildEditUrl = (adminUrl, kind, id) => {
+    // Admin uses hash-based react-router. posts/notes/pages route at
+    // `#/<kind>/edit?id=<id>`; projects route at `#/projects/<id>`.
+    const base = adminUrl.replace(/\/+$/, '');
+    if (kind === 'projects') {
+        return `${base}#/projects/${encodeURIComponent(id)}`;
+    }
+    return `${base}#/${kind}/edit?id=${encodeURIComponent(id)}`;
+};
+const buildDraftEditUrl = (adminUrl, kind, draftId, refId) => {
+    const base = adminUrl.replace(/\/+$/, '');
+    const params = new URLSearchParams();
+    params.set('draftId', draftId);
+    if (refId)
+        params.set('id', refId);
+    return `${base}#/${kind}/edit?${params.toString()}`;
+};
+const openAdminUrl = (buildUrl) => Effect.gen(function* () {
+    const renderer = yield* Renderer;
+    const api = yield* Api;
+    const opts = yield* api.request('/options/url');
+    const adminUrl = opts.data?.admin_url ?? opts.admin_url;
+    if (!adminUrl) {
+        yield* renderer.emitWarn('admin_url is not configured on the server; skipping --open');
+        return;
+    }
+    const url = buildUrl(adminUrl);
+    yield* renderer.emitInfo(`opening admin: ${url}`);
+    yield* Effect.tryPromise({
+        try: () => open(url),
+        catch: () => new Error('failed to launch browser'),
+    }).pipe(Effect.catchAll((e) => renderer.emitWarn(`could not launch browser: ${e instanceof Error ? e.message : String(e)}`)));
+});
+/**
+ * Resolve the server's admin URL from `/options/url`, build the admin
+ * edit-page URL for the given resource, and open it in the user's browser.
+ * Non-fatal: missing admin_url or browser-launch failures emit a warning
+ * and the parent effect continues.
+ */
+export const openAdminEdit = (kind, id) => openAdminUrl((adminUrl) => buildEditUrl(adminUrl, kind, id));
+export const openAdminDraftEdit = (kind, draftId, refId) => openAdminUrl((adminUrl) => buildDraftEditUrl(adminUrl, kind, draftId, refId));

package/dist/src/domain/content-spec.d.ts

@@ -0,0 +1,20 @@
+import { FileSystem, Path } from '@effect/platform';
+import { Effect } from 'effect';
+import { ValidationFailed } from './errors';
+export interface ContentSource {
+    readonly text: string;
+    readonly origin: 'inline' | 'file' | 'stdin';
+    readonly path?: string;
+}
+/**
+ * Resolve a content spec — one of:
+ *  - `undefined` → returns `null`
+ *  - `"-"` or `"stdin"` → reads stdin
+ *  - `"file=<path>"` → reads that file (relative to cwd)
+ *  - any other value → inline literal
+ */
+export declare const readContentSpec: (spec: string | undefined, opts?: {
+    readonly cwd?: string;
+}) => Effect.Effect<ContentSource | null, ValidationFailed, FileSystem.FileSystem | Path.Path>;
+export declare const readJsonSpec: (spec: string | undefined) => Effect.Effect<unknown, ValidationFailed, FileSystem.FileSystem | Path.Path>;
+export declare const readStdin: Effect.Effect<string, ValidationFailed>;

package/dist/src/domain/content-spec.js

@@ -0,0 +1,78 @@
+import { FileSystem, Path } from '@effect/platform';
+import { Effect } from 'effect';
+import { ValidationFailed } from './errors';
+const messageOf = (err) => {
+    if (err instanceof Error)
+        return err.message;
+    if (typeof err === 'string')
+        return err;
+    return String(err);
+};
+/**
+ * Resolve a content spec — one of:
+ *  - `undefined` → returns `null`
+ *  - `"-"` or `"stdin"` → reads stdin
+ *  - `"file=<path>"` → reads that file (relative to cwd)
+ *  - any other value → inline literal
+ */
+export const readContentSpec = (spec, opts = {}) => Effect.gen(function* () {
+    if (spec === undefined)
+        return null;
+    if (spec === '-' || spec === 'stdin') {
+        const text = yield* readStdin;
+        return { text, origin: 'stdin' };
+    }
+    if (spec.startsWith('file=')) {
+        const path = yield* Path.Path;
+        const fs = yield* FileSystem.FileSystem;
+        const p = path.resolve(opts.cwd ?? process.cwd(), spec.slice('file='.length));
+        const text = yield* fs.readFileString(p).pipe(Effect.mapError((err) => new ValidationFailed({
+            message: `failed to read ${p}: ${messageOf(err)}`,
+        })));
+        return { text, origin: 'file', path: p };
+    }
+    return { text: spec, origin: 'inline' };
+});
+export const readJsonSpec = (spec) => Effect.gen(function* () {
+    if (spec === undefined)
+        return undefined;
+    if (spec.startsWith('file=')) {
+        const path = yield* Path.Path;
+        const fs = yield* FileSystem.FileSystem;
+        const p = path.resolve(process.cwd(), spec.slice('file='.length));
+        const text = yield* fs.readFileString(p).pipe(Effect.mapError((err) => new ValidationFailed({
+            message: `failed to read JSON from ${p}: ${messageOf(err)}`,
+        })));
+        return yield* Effect.try({
+            try: () => JSON.parse(text),
+            catch: (err) => new ValidationFailed({
+                message: `failed to parse JSON: ${messageOf(err)}`,
+            }),
+        });
+    }
+    return yield* Effect.try({
+        try: () => JSON.parse(spec),
+        catch: (err) => new ValidationFailed({
+            message: `failed to parse JSON: ${messageOf(err)}`,
+        }),
+    });
+});
+export const readStdin = Effect.gen(function* () {
+    if (process.stdin.isTTY) {
+        return yield* Effect.fail(new ValidationFailed({
+            message: 'requested stdin content but stdin is a TTY',
+        }));
+    }
+    return yield* Effect.tryPromise({
+        try: async () => {
+            const chunks = [];
+            for await (const chunk of process.stdin) {
+                chunks.push(typeof chunk === 'string' ? Buffer.from(chunk) : chunk);
+            }
+            return Buffer.concat(chunks).toString('utf8');
+        },
+        catch: (err) => new ValidationFailed({
+            message: `failed to read stdin: ${messageOf(err)}`,
+        }),
+    });
+});

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

@@ -0,0 +1,68 @@
+/**
+ * @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`.
+ */
+export type WireVersion = 'v2' | 'v3';
+/**
+ * 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 declare const detectWireVersion: (body: unknown) => WireVersion | 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 declare const normalizeSuccessBody: (body: unknown) => unknown;
+export interface NormalizedError {
+    code?: string;
+    message?: string;
+    details?: unknown;
+}
+/**
+ * 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 declare const normalizeErrorBody: (body: unknown) => NormalizedError;