@mx-space/cli 0.15.0 → 0.15.1

package/dist/src/domain/payload.js

@@ -0,0 +1,237 @@
+import { FileSystem } from '@effect/platform';
+import { Effect } from 'effect';
+import { Lexical } from '../services/Lexical';
+import { readContentSpec, readJsonSpec, readStdin } from './content-spec';
+import { coerceMeta, parseEnvelope, } from './envelope';
+import { ValidationFailed, ValidationXml } from './errors';
+const messageOf = (err) => {
+    if (err instanceof Error)
+        return err.message;
+    if (typeof err === 'string')
+        return err;
+    return String(err);
+};
+// ---------------------------------------------------------------------------
+// Envelope loading
+// ---------------------------------------------------------------------------
+export const loadEnvelopeIfAny = (filePath, kind) => Effect.gen(function* () {
+    if (!filePath)
+        return null;
+    let xml;
+    if (filePath === '-' || filePath === 'stdin' || filePath === '/dev/stdin') {
+        xml = yield* readStdin;
+    }
+    else if (filePath.startsWith('file=')) {
+        const src = yield* readContentSpec(filePath);
+        xml = src?.text ?? '';
+    }
+    else {
+        const fs = yield* FileSystem.FileSystem;
+        xml = yield* fs.readFileString(filePath).pipe(Effect.mapError((err) => new ValidationFailed({
+            message: `failed to read ${filePath}: ${messageOf(err)}`,
+        })));
+    }
+    return yield* parseEnvelopeEffect(xml, kind);
+});
+// `parseEnvelope` throws `ValidationXml` — wrap in Effect.try so the error
+// surfaces through the channel.
+const parseEnvelopeEffect = (xml, kind) => Effect.try({
+    try: () => parseEnvelope(xml, kind),
+    catch: (err) => err instanceof ValidationXml
+        ? err
+        : new ValidationXml({
+            message: messageOf(err),
+            cause: err,
+        }),
+});
+// ---------------------------------------------------------------------------
+// Post payload
+// ---------------------------------------------------------------------------
+export const buildPostPayload = (flags) => Effect.gen(function* () {
+    const envelope = yield* loadEnvelopeIfAny(flags.file, 'post');
+    const envMeta = envelope ? coerceMeta(envelope.meta) : {};
+    const payload = {};
+    const title = flags.title ?? envMeta.title;
+    if (title !== undefined)
+        payload.title = title;
+    const slug = flags.slug ?? envMeta.slug;
+    if (slug !== undefined)
+        payload.slug = slug;
+    if (flags.category)
+        payload.__categoryName = flags.category;
+    else if (envMeta.category)
+        payload.__categoryName = envMeta.category;
+    const summary = flags.summary ?? envMeta.summary;
+    if (summary !== undefined)
+        payload.summary = summary;
+    const state = flags.state ?? envMeta.state;
+    if (state !== undefined)
+        payload.isPublished = state === 'publish';
+    const tags = flags.tags ?? envMeta.tags;
+    if (tags !== undefined)
+        payload.tags = tags;
+    const copyright = flags.copyright ?? envMeta.copyright;
+    if (copyright !== undefined)
+        payload.copyright = copyright;
+    const pin = flags.pin ?? envMeta.pin;
+    if (pin !== undefined)
+        payload.pin = pin;
+    const pinOrder = flags.pinOrder ?? envMeta.pinOrder;
+    if (pinOrder !== undefined)
+        payload.pinOrder = pinOrder;
+    const related = flags.related ?? envMeta.related;
+    if (related !== undefined)
+        payload.relatedId = related;
+    if (flags.meta !== undefined) {
+        payload.meta = yield* readJsonSpec(flags.meta);
+    }
+    const format = flags.format ?? envMeta.format ?? 'lexical';
+    payload.contentFormat = format;
+    const contentSrc = yield* resolveContent(flags.content, envelope, format);
+    if (contentSrc) {
+        payload.content = contentSrc.content;
+        payload.text = contentSrc.text;
+    }
+    return {
+        payload,
+        envelopeMeta: envMeta,
+        contentSource: contentSrc?.origin ?? 'none',
+    };
+});
+// ---------------------------------------------------------------------------
+// Note payload
+// ---------------------------------------------------------------------------
+export const buildNotePayload = (flags) => Effect.gen(function* () {
+    const envelope = yield* loadEnvelopeIfAny(flags.file, 'note');
+    const envMeta = envelope ? coerceMeta(envelope.meta) : {};
+    const payload = {};
+    const title = flags.title ?? envMeta.title ?? '无题';
+    payload.title = title;
+    const slug = flags.slug ?? envMeta.slug;
+    if (slug !== undefined)
+        payload.slug = slug;
+    if (flags.topic)
+        payload.__topicName = flags.topic;
+    else if (envMeta.topic)
+        payload.__topicName = envMeta.topic;
+    const state = flags.state ?? envMeta.state;
+    if (state !== undefined)
+        payload.isPublished = state === 'publish';
+    const mood = flags.mood ?? envMeta.mood;
+    if (mood !== undefined)
+        payload.mood = mood;
+    const weather = flags.weather ?? envMeta.weather;
+    if (weather !== undefined)
+        payload.weather = weather;
+    const publicAt = flags.publicAt ?? envMeta.publicAt;
+    if (publicAt !== undefined)
+        payload.publicAt = publicAt;
+    const password = flags.password ?? envMeta.password;
+    if (password !== undefined)
+        payload.password = password;
+    const bookmark = flags.bookmark ?? envMeta.bookmark;
+    if (bookmark !== undefined)
+        payload.bookmark = bookmark;
+    const location = flags.location ?? envMeta.location;
+    if (location !== undefined)
+        payload.location = location;
+    if (flags.coords) {
+        const [latRaw, lngRaw] = flags.coords.split(',').map((s) => s.trim());
+        const lat = Number(latRaw);
+        const lng = Number(lngRaw);
+        if (Number.isNaN(lat) || Number.isNaN(lng)) {
+            return yield* Effect.fail(new ValidationFailed({
+                message: `invalid --coords value "${flags.coords}", expected "lat,lng"`,
+            }));
+        }
+        payload.coordinates = { latitude: lat, longitude: lng };
+    }
+    if (flags.images !== undefined) {
+        payload.images = yield* readJsonSpec(flags.images);
+    }
+    if (flags.meta !== undefined) {
+        payload.meta = yield* readJsonSpec(flags.meta);
+    }
+    const format = flags.format ?? envMeta.format ?? 'lexical';
+    payload.contentFormat = format;
+    const contentSrc = yield* resolveContent(flags.content, envelope, format);
+    if (contentSrc) {
+        payload.content = contentSrc.content;
+        payload.text = contentSrc.text;
+    }
+    return {
+        payload,
+        envelopeMeta: envMeta,
+        contentSource: contentSrc?.origin ?? 'none',
+    };
+});
+// ---------------------------------------------------------------------------
+// Page payload — exported for W2-B's page commands to consume.
+// ---------------------------------------------------------------------------
+export const buildPagePayload = (flags) => Effect.gen(function* () {
+    // Pages reuse the `<mxpost>` envelope shape (per legacy behavior).
+    const envelope = yield* loadEnvelopeIfAny(flags.file, 'post');
+    const envMeta = envelope ? coerceMeta(envelope.meta) : {};
+    const payload = {};
+    const title = flags.title ?? envMeta.title;
+    if (title !== undefined)
+        payload.title = title;
+    const slug = flags.slug ?? envMeta.slug;
+    if (slug !== undefined)
+        payload.slug = slug;
+    const subtitle = flags.subtitle ?? envMeta.subtitle;
+    if (subtitle !== undefined)
+        payload.subtitle = subtitle;
+    const order = flags.order ?? envMeta.order;
+    if (order !== undefined)
+        payload.order = order;
+    if (flags.meta !== undefined) {
+        payload.meta = yield* readJsonSpec(flags.meta);
+    }
+    const format = flags.format ?? envMeta.format ?? 'lexical';
+    payload.contentFormat = format;
+    const contentSrc = yield* resolveContent(flags.content, envelope, format);
+    if (contentSrc) {
+        payload.content = contentSrc.content;
+        payload.text = contentSrc.text;
+    }
+    return {
+        payload,
+        envelopeMeta: envMeta,
+        contentSource: contentSrc?.origin ?? 'none',
+    };
+});
+const resolveContent = (flagSpec, envelope, format) => Effect.gen(function* () {
+    let source = null;
+    if (flagSpec !== undefined) {
+        const src = yield* readContentSpec(flagSpec);
+        if (src)
+            source = { text: src.text, origin: 'flag' };
+    }
+    else if (envelope) {
+        source = { text: envelope.contentXml, origin: 'envelope' };
+    }
+    if (!source)
+        return null;
+    if (format === 'markdown') {
+        return { content: source.text, text: source.text, origin: source.origin };
+    }
+    if (source.text.length === 0) {
+        return yield* Effect.fail(new ValidationFailed({
+            message: 'content is required when contentFormat is lexical',
+            details: { issues: [{ path: ['content'], message: 'required' }] },
+        }));
+    }
+    const lexical = yield* Lexical;
+    const state = yield* lexical.litexmlToPayload(source.text);
+    const lexicalJson = JSON.stringify(state);
+    const text = yield* lexical.lexicalJsonToMarkdown(state);
+    return { content: lexicalJson, text, origin: source.origin };
+});
+export const emptyPayload = (format) => Effect.gen(function* () {
+    if (format === 'markdown')
+        return { content: '', text: '' };
+    const lexical = yield* Lexical;
+    const state = yield* lexical.emptyState;
+    return { content: JSON.stringify(state), text: '' };
+});

package/dist/src/domain/preflight-guards.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Single source of truth for preflight exemptions (the `@effect/cli`
+ * equivalent of the v0.2.x `preAction` hook in `src/bin/mxs.ts`).
+ *
+ * Any subcommand registered in `cli/*` MUST match the names declared here —
+ * this is the contract. Ported from `src/core/preaction-guards.ts`.
+ */
+/** Parent command names whose entire subtree is exempt from the none_active guard. */
+export declare const PREFLIGHT_EXEMPT_PARENTS: ReadonlySet<string>;
+export interface ExemptCommand {
+    readonly parent: string;
+    readonly name: string;
+}
+/**
+ * Individual (parent, name) pairs that are exempt regardless of profile state.
+ * `auth login` is included unconditionally so a fresh install can bootstrap.
+ */
+export declare const PREFLIGHT_EXEMPT_COMMANDS: readonly ExemptCommand[];
+/**
+ * Top-level command names that are exempt from the profile.none_active guard.
+ * Used for commands that should work without a configured server (e.g. `mxs update`).
+ */
+export declare const PREFLIGHT_EXEMPT_TOPLEVEL: ReadonlySet<string>;
+export interface GuardInput {
+    readonly profileFlag: string | undefined;
+    readonly apiUrlFlag: string | undefined;
+    readonly envProfile: string | undefined;
+    readonly envApiUrl: string | undefined;
+    readonly currentProfile: string | null;
+    readonly parentName: string;
+    readonly commandName: string;
+}
+/** Returns true if the command is exempt from the profile.none_active guard. */
+export declare function isPreflightExempt(input: GuardInput): boolean;
+/**
+ * Returns true if the guard should throw profile.none_active.
+ * A resolved profile, any URL override, or an exempt command all suppress it.
+ */
+export declare function requiresActiveProfile(input: GuardInput): boolean;
+/** Set of valid top-level subcommand names. Used to walk `process.argv`. */
+export declare const TOPLEVEL_COMMANDS: ReadonlySet<string>;
+export interface InvokedCommand {
+    readonly parentName: string;
+    readonly commandName: string;
+}
+/**
+ * Inspect argv to determine which command is being invoked. Skips known
+ * global flags so `mxs --profile foo post list` resolves to (`post`,`list`).
+ *
+ * Returns an empty pair when no subcommand is on argv (e.g. `mxs --help`).
+ */
+export declare function detectInvokedCommand(argv: readonly string[], knownGlobalFlags?: ReadonlySet<string>): InvokedCommand;
+/** Known global flag names; used by `detectInvokedCommand` to skip their values. */
+export declare const DEFAULT_KNOWN_GLOBAL_FLAGS: ReadonlySet<string>;

package/dist/src/domain/preflight-guards.js

@@ -0,0 +1,130 @@
+/**
+ * Single source of truth for preflight exemptions (the `@effect/cli`
+ * equivalent of the v0.2.x `preAction` hook in `src/bin/mxs.ts`).
+ *
+ * Any subcommand registered in `cli/*` MUST match the names declared here —
+ * this is the contract. Ported from `src/core/preaction-guards.ts`.
+ */
+/** Parent command names whose entire subtree is exempt from the none_active guard. */
+export const PREFLIGHT_EXEMPT_PARENTS = new Set([
+    'profile',
+    'skill',
+]);
+/**
+ * Individual (parent, name) pairs that are exempt regardless of profile state.
+ * `auth login` is included unconditionally so a fresh install can bootstrap.
+ */
+export const PREFLIGHT_EXEMPT_COMMANDS = [
+    { parent: 'auth', name: 'login' },
+];
+/**
+ * Top-level command names that are exempt from the profile.none_active guard.
+ * Used for commands that should work without a configured server (e.g. `mxs update`).
+ */
+export const PREFLIGHT_EXEMPT_TOPLEVEL = new Set([
+    'update',
+    'skill',
+    'preview',
+]);
+/** Returns true if the command is exempt from the profile.none_active guard. */
+export function isPreflightExempt(input) {
+    return (PREFLIGHT_EXEMPT_PARENTS.has(input.parentName) ||
+        input.commandName === 'profile' ||
+        PREFLIGHT_EXEMPT_TOPLEVEL.has(input.commandName) ||
+        PREFLIGHT_EXEMPT_COMMANDS.some((c) => c.parent === input.parentName && c.name === input.commandName));
+}
+/**
+ * Returns true if the guard should throw profile.none_active.
+ * A resolved profile, any URL override, or an exempt command all suppress it.
+ */
+export function requiresActiveProfile(input) {
+    if (input.profileFlag || input.envProfile)
+        return false;
+    if (input.apiUrlFlag || input.envApiUrl)
+        return false;
+    if (input.currentProfile)
+        return false;
+    if (isPreflightExempt(input))
+        return false;
+    return true;
+}
+// ---------------------------------------------------------------------------
+// argv inspection — derive the (parentName, commandName) being invoked.
+// ---------------------------------------------------------------------------
+/** Set of valid top-level subcommand names. Used to walk `process.argv`. */
+export const TOPLEVEL_COMMANDS = new Set([
+    'auth',
+    'profile',
+    'post',
+    'note',
+    'page',
+    'category',
+    'topic',
+    'config',
+    'skill',
+    'preview',
+    'update',
+]);
+/**
+ * Inspect argv to determine which command is being invoked. Skips known
+ * global flags so `mxs --profile foo post list` resolves to (`post`,`list`).
+ *
+ * Returns an empty pair when no subcommand is on argv (e.g. `mxs --help`).
+ */
+export function detectInvokedCommand(argv, knownGlobalFlags = DEFAULT_KNOWN_GLOBAL_FLAGS) {
+    const positional = [];
+    // argv[0] = node, argv[1] = script — skip both.
+    for (let i = 2; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === '--')
+            break;
+        if (arg.startsWith('--')) {
+            const eq = arg.indexOf('=');
+            const name = eq === -1 ? arg : arg.slice(0, eq);
+            if (knownGlobalFlags.has(name) &&
+                eq === -1 &&
+                FLAG_TAKES_VALUE.has(name)) {
+                i++; // skip its value
+            }
+            continue;
+        }
+        if (arg.startsWith('-')) {
+            if (arg === '-q')
+                continue;
+            continue;
+        }
+        positional.push(arg);
+    }
+    if (positional.length === 0)
+        return { parentName: '', commandName: '' };
+    const first = positional[0];
+    if (!TOPLEVEL_COMMANDS.has(first))
+        return { parentName: '', commandName: first };
+    if (positional.length === 1)
+        return { parentName: '', commandName: first };
+    return { parentName: first, commandName: positional[1] };
+}
+/** Known global flag names; used by `detectInvokedCommand` to skip their values. */
+export const DEFAULT_KNOWN_GLOBAL_FLAGS = new Set([
+    '--json',
+    '--output',
+    '--api-url',
+    '--token',
+    '--api-key',
+    '--lang',
+    '--quiet',
+    '--verbose',
+    '--dry-run',
+    '--profile',
+    '--help',
+    '--version',
+]);
+/** Subset of global flags that take a value. */
+const FLAG_TAKES_VALUE = new Set([
+    '--output',
+    '--api-url',
+    '--token',
+    '--api-key',
+    '--lang',
+    '--profile',
+]);

package/dist/src/domain/runtime-flags.d.ts

@@ -0,0 +1,33 @@
+import { FiberRef } from 'effect';
+import type { OutputMode } from '../services/Renderer';
+export interface GlobalFlags {
+    readonly json: boolean;
+    readonly output: OutputMode;
+    readonly apiUrl?: string;
+    readonly token?: string;
+    readonly apiKey?: string;
+    readonly lang?: string;
+    readonly quiet: boolean;
+    readonly verbose: boolean;
+    readonly dryRun: boolean;
+    readonly profile?: string;
+}
+export declare const defaultGlobalFlags: GlobalFlags;
+/**
+ * Walk `argv` once, extracting recognized global flags and returning both the
+ * resolved `GlobalFlags` and the residual `argv` (with those flags removed).
+ *
+ * Unknown flags pass through untouched — `@effect/cli` will surface them at
+ * the proper command layer.
+ *
+ * Notes:
+ *   - Both `--key value` and `--key=value` are supported for value flags.
+ *   - argv[0] (node) and argv[1] (script) pass through unchanged.
+ *   - We stop processing global flags at the first `--` (POSIX convention).
+ */
+export declare const parseGlobalFlags: (argv: readonly string[]) => {
+    readonly flags: GlobalFlags;
+    readonly rest: readonly string[];
+};
+export declare const currentDryRun: FiberRef.FiberRef<boolean>;
+export declare const currentProfileFlag: FiberRef.FiberRef<string | undefined>;

package/dist/src/domain/runtime-flags.js

@@ -0,0 +1,166 @@
+import { FiberRef } from 'effect';
+export const defaultGlobalFlags = {
+    json: false,
+    output: 'readable',
+    quiet: false,
+    verbose: false,
+    dryRun: false,
+};
+const VALID_OUTPUT_MODES = new Set([
+    'pretty-json',
+    'json',
+    'readable',
+    'llm',
+    'xml',
+]);
+const isOutputMode = (s) => VALID_OUTPUT_MODES.has(s);
+/** Long-name flags that take a value (consume the next argv slot if no `=`). */
+const VALUE_FLAGS = new Set([
+    '--output',
+    '--api-url',
+    '--token',
+    '--api-key',
+    '--lang',
+    '--profile',
+]);
+/** Long-name boolean flags (no value). */
+const BOOL_FLAGS = new Set([
+    '--json',
+    '--quiet',
+    '--verbose',
+    '--dry-run',
+]);
+/** Aliases handled separately because they share the leading dash. */
+const SHORT_BOOL_FLAGS = {
+    '-q': 'quiet',
+};
+/**
+ * Walk `argv` once, extracting recognized global flags and returning both the
+ * resolved `GlobalFlags` and the residual `argv` (with those flags removed).
+ *
+ * Unknown flags pass through untouched — `@effect/cli` will surface them at
+ * the proper command layer.
+ *
+ * Notes:
+ *   - Both `--key value` and `--key=value` are supported for value flags.
+ *   - argv[0] (node) and argv[1] (script) pass through unchanged.
+ *   - We stop processing global flags at the first `--` (POSIX convention).
+ */
+export const parseGlobalFlags = (argv) => {
+    const rest = [];
+    let json = false;
+    let output = 'readable';
+    let apiUrl;
+    let token;
+    let apiKey;
+    let lang;
+    let quiet = false;
+    let verbose = false;
+    let dryRun = false;
+    let profile;
+    // Preserve argv[0] (node) and argv[1] (script).
+    if (argv.length > 0)
+        rest.push(argv[0]);
+    if (argv.length > 1)
+        rest.push(argv[1]);
+    let passThrough = false;
+    for (let i = 2; i < argv.length; i++) {
+        const arg = argv[i];
+        if (passThrough) {
+            rest.push(arg);
+            continue;
+        }
+        if (arg === '--') {
+            passThrough = true;
+            rest.push(arg);
+            continue;
+        }
+        if (arg.startsWith('--')) {
+            const eqIdx = arg.indexOf('=');
+            const name = eqIdx === -1 ? arg : arg.slice(0, eqIdx);
+            const inlineValue = eqIdx === -1 ? undefined : arg.slice(eqIdx + 1);
+            if (BOOL_FLAGS.has(name)) {
+                if (name === '--json')
+                    json = true;
+                else if (name === '--quiet')
+                    quiet = true;
+                else if (name === '--verbose')
+                    verbose = true;
+                else if (name === '--dry-run')
+                    dryRun = true;
+                continue;
+            }
+            if (VALUE_FLAGS.has(name)) {
+                const value = inlineValue !== undefined
+                    ? inlineValue
+                    : i + 1 < argv.length
+                        ? argv[++i]
+                        : undefined;
+                if (value === undefined)
+                    continue;
+                if (name === '--output') {
+                    if (isOutputMode(value))
+                        output = value;
+                }
+                else if (name === '--api-url') {
+                    apiUrl = value;
+                }
+                else if (name === '--token') {
+                    token = value;
+                }
+                else if (name === '--api-key') {
+                    apiKey = value;
+                }
+                else if (name === '--lang') {
+                    lang = value;
+                }
+                else if (name === '--profile') {
+                    profile = value;
+                }
+                continue;
+            }
+            // Unknown long flag → pass through.
+            rest.push(arg);
+            continue;
+        }
+        // Short flags.
+        if (arg.startsWith('-') && arg.length > 1 && !arg.startsWith('--')) {
+            const target = SHORT_BOOL_FLAGS[arg];
+            if (target === 'quiet') {
+                quiet = true;
+                continue;
+            }
+            rest.push(arg);
+            continue;
+        }
+        rest.push(arg);
+    }
+    return {
+        flags: {
+            json,
+            output: json ? 'json' : output,
+            apiUrl,
+            token,
+            apiKey,
+            lang,
+            quiet,
+            verbose,
+            dryRun,
+            profile,
+        },
+        rest,
+    };
+};
+// ---------------------------------------------------------------------------
+// FiberRef: --dry-run. Read by `Api.layer({...})` at construction time;
+// surfaced as a FiberRef as well so individual handlers can introspect when
+// they need bespoke dry-run behaviour (none today; placeholder for v2/v3).
+// ---------------------------------------------------------------------------
+export const currentDryRun = FiberRef.unsafeMake(false);
+// ---------------------------------------------------------------------------
+// FiberRef: --profile. The flag is already threaded into `Api.layer` via
+// `StoreOverrides`, but commands that talk to the Profile/Config services
+// directly (notably `auth login`, which creates profiles) need to read it
+// without re-parsing argv. Set once in `bin/mxs.ts` after `parseGlobalFlags`.
+// ---------------------------------------------------------------------------
+export const currentProfileFlag = FiberRef.unsafeMake(undefined);

package/dist/src/domain/schema/api-envelope.d.ts

@@ -0,0 +1,67 @@
+import { Schema } from 'effect';
+/**
+ * Wire-format error envelope emitted by `Renderer.emitError` (and consumed
+ * by tests as a regression oracle). Mirrors `MxsError.toJSON()` from the
+ * v0.2.x core, plus the `tagToCode` table in `domain/errors.ts`.
+ */
+export declare const ErrorEnvelopeSchema: Schema.Struct<{
+    ok: Schema.Literal<[false]>;
+    code: typeof Schema.String;
+    message: typeof Schema.String;
+    details: Schema.optional<typeof Schema.Unknown>;
+    hint: Schema.optional<typeof Schema.String>;
+}>;
+export type ErrorEnvelope = Schema.Schema.Type<typeof ErrorEnvelopeSchema>;
+/**
+ * Server-side pagination block. mx-core servers emit `page/size/total` —
+ * the CLI also accepts the legacy aliases (`currentPage`/`pageSize`/
+ * `totalCount`) for back-compat with old fixtures.
+ */
+export declare const PaginationSchema: Schema.Struct<{
+    page: Schema.optional<typeof Schema.Number>;
+    size: Schema.optional<typeof Schema.Number>;
+    total: Schema.optional<typeof Schema.Number>;
+    totalPage: Schema.optional<typeof Schema.Number>;
+    currentPage: Schema.optional<typeof Schema.Number>;
+    pageSize: Schema.optional<typeof Schema.Number>;
+    totalCount: Schema.optional<typeof Schema.Number>;
+}>;
+export type Pagination = Schema.Schema.Type<typeof PaginationSchema>;
+/**
+ * `{ data, pagination }` envelope — produced by paginator-decorated
+ * controllers in mx-core (`ResponseInterceptor`).
+ */
+export declare const paginatedEnvelopeSchema: <A, I, R>(item: Schema.Schema<A, I, R>) => Schema.Struct<{
+    data: Schema.Array$<Schema.Schema<A, I, R>>;
+    pagination: Schema.optional<Schema.Struct<{
+        page: Schema.optional<typeof Schema.Number>;
+        size: Schema.optional<typeof Schema.Number>;
+        total: Schema.optional<typeof Schema.Number>;
+        totalPage: Schema.optional<typeof Schema.Number>;
+        currentPage: Schema.optional<typeof Schema.Number>;
+        pageSize: Schema.optional<typeof Schema.Number>;
+        totalCount: Schema.optional<typeof Schema.Number>;
+    }>>;
+}>;
+/**
+ * `{ data: [...] }` envelope — produced by array responses without
+ * paginator decoration.
+ */
+export declare const dataArrayEnvelopeSchema: <A, I, R>(item: Schema.Schema<A, I, R>) => Schema.Struct<{
+    data: Schema.Array$<Schema.Schema<A, I, R>>;
+}>;
+/**
+ * Common server error body shape — used to extract the human `message`
+ * when mapping non-2xx responses to `TaggedError`s.
+ */
+export declare const ServerErrorBodySchema: Schema.Struct<{
+    message: Schema.optional<Schema.Union<[typeof Schema.String, Schema.Array$<typeof Schema.String>]>>;
+    code: Schema.optional<typeof Schema.String>;
+    details: Schema.optional<typeof Schema.Unknown>;
+}>;
+export type ServerErrorBody = Schema.Schema.Type<typeof ServerErrorBodySchema>;
+/**
+ * Extract a flattened `message` string from an arbitrary error body,
+ * matching the legacy `extractMessage` helper in `api-client.ts`.
+ */
+export declare const extractServerMessage: (body: unknown) => string | null;