@mx-space/cli 0.15.0 → 0.15.1

package/dist/src/services/Config.js

@@ -0,0 +1,359 @@
+import { FileSystem, Path } from '@effect/platform';
+import { Context, Effect, Layer } from 'effect';
+import { ConfigMissingApiUrl, Generic, ProfileNotFound } from '../domain/errors';
+// ---------------------------------------------------------------------------
+// Constants — keep wire-compatible with `src/core/config-store.ts`
+// ---------------------------------------------------------------------------
+export const DEFAULT_CLIENT_ID = 'mxs-cli';
+export const LEGACY_CONFIG_FIELDS = [
+    'api_base',
+    'auth_base',
+    'client_id',
+];
+export const LOCAL_DEV_ENV = 'MXS_CLI_LOCAL_DEV';
+export const LOCAL_DEV_API_URL_ENV = 'MXS_CLI_LOCAL_DEV_API_URL';
+export const LOCAL_DEV_PROFILE_NAME = 'local-dev';
+export const LOCAL_DEV_API_URL_DEFAULT = 'http://localhost:2333';
+export const isLocalDevEnabled = () => process.env[LOCAL_DEV_ENV] === '1';
+export const getLocalDevApiUrl = () => process.env[LOCAL_DEV_API_URL_ENV]?.trim() || LOCAL_DEV_API_URL_DEFAULT;
+export const shouldUseLocalDev = (input) => isLocalDevEnabled() &&
+    !input.profileOverride?.trim() &&
+    !input.envProfile?.trim() &&
+    !input.apiUrlOverride?.trim() &&
+    !input.envApiUrl?.trim();
+export const stripLegacyConfigFields = (cfg) => {
+    const out = { ...cfg };
+    for (const k of LEGACY_CONFIG_FIELDS)
+        delete out[k];
+    return out;
+};
+export const parseApiUrl = (input) => Effect.gen(function* () {
+    let url = input.trim();
+    if (!url) {
+        return yield* Effect.fail(new ConfigMissingApiUrl({ message: 'API URL is empty' }));
+    }
+    if (!/^https?:\/\//i.test(url)) {
+        const isLocal = /^(?:localhost|127\.0\.0\.1|::1)(?::\d+)?$/i.test(url);
+        url = isLocal ? `http://${url}` : `https://${url}`;
+    }
+    url = url.replace(/\/+$/, '');
+    const match = url.match(/^(.*)\/api\/v(\d+)$/);
+    if (match) {
+        return { baseUrl: match[1], apiVersion: Number(match[2]) };
+    }
+    // Accept a bare `/api` suffix too — many users habitually paste the API
+    // root rather than the site root. The probe lives at `/api/v{N}/auth/ok`,
+    // so a leftover `/api` would yield a `/api/api/v{N}/...` URL and 404.
+    const apiSuffix = url.match(/^(.*)\/api$/);
+    if (apiSuffix) {
+        return { baseUrl: apiSuffix[1] };
+    }
+    return { baseUrl: url };
+});
+export const normalizeApiUrl = (input) => Effect.map(parseApiUrl(input), (p) => p.baseUrl);
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+const PROFILES_SUBDIR = 'profiles';
+const getXdgConfigDir = (path) => {
+    const xdg = process.env.XDG_CONFIG_HOME;
+    const base = xdg && xdg.length > 0
+        ? xdg
+        : path.join(process.env.HOME || process.env.USERPROFILE || '~', '.config');
+    return path.join(base, 'mxs');
+};
+const isNotFound = (err) => {
+    if (typeof err === 'object' && err !== null) {
+        const e = err;
+        if (e._tag === 'SystemError' && e.reason === 'NotFound')
+            return true;
+        if (e.code === 'ENOENT')
+            return true;
+    }
+    return false;
+};
+const toGeneric = (err, message) => new Generic({ message, cause: err });
+const readJsonIfExists = (fs, filePath) => Effect.gen(function* () {
+    const raw = yield* fs.readFileString(filePath).pipe(Effect.map((s) => s), Effect.catchAll((err) => isNotFound(err)
+        ? Effect.succeed(null)
+        : Effect.fail(toGeneric(err, `failed to read ${filePath}: ${String(err)}`))));
+    if (raw === null)
+        return null;
+    try {
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        return yield* Effect.fail(new Generic({
+            message: `failed to parse ${filePath}: ${err.message}`,
+            cause: err,
+        }));
+    }
+});
+const writeJson = (fs, filePath, data, mode) => Effect.gen(function* () {
+    const text = `${JSON.stringify(data, null, 2)}`;
+    yield* fs
+        .writeFileString(filePath, text, { mode })
+        .pipe(Effect.catchAll((err) => Effect.fail(toGeneric(err, `failed to write ${filePath}`))));
+    // Best-effort chmod — silently ignore failures (Windows / unsupported FS).
+    yield* fs.chmod(filePath, mode).pipe(Effect.catchAll(() => Effect.void));
+});
+const ensureProfileDir = (fs, dir) => Effect.gen(function* () {
+    yield* fs
+        .makeDirectory(dir, { recursive: true, mode: 0o700 })
+        .pipe(Effect.catchAll((err) => Effect.fail(toGeneric(err, `failed to create ${dir}`))));
+    yield* fs.chmod(dir, 0o700).pipe(Effect.catchAll(() => Effect.void));
+});
+const make = Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    // Path helpers --------------------------------------------------------------
+    const configDir = () => getXdgConfigDir(path);
+    const profilesDir = () => path.join(configDir(), PROFILES_SUBDIR);
+    const profileDir = (name) => path.join(profilesDir(), name);
+    const profileConfigPath = (name) => path.join(profileDir(name), 'config.json');
+    const profileCredentialsPath = (name) => path.join(profileDir(name), 'credentials.json');
+    const legacyConfigPath = () => path.join(configDir(), 'config.json');
+    const legacyCredentialsPath = () => path.join(configDir(), 'credentials.json');
+    const currentPath = () => path.join(configDir(), 'current');
+    // Profile config IO ---------------------------------------------------------
+    const readProfileConfig = (name) => Effect.gen(function* () {
+        const raw = yield* readJsonIfExists(fs, profileConfigPath(name));
+        return stripLegacyConfigFields(raw ?? {});
+    });
+    const writeProfileConfig = (name, cfg) => Effect.gen(function* () {
+        yield* ensureProfileDir(fs, profileDir(name));
+        yield* writeJson(fs, profileConfigPath(name), cfg, 0o644);
+    });
+    const updateProfileConfig = (name, update) => Effect.gen(function* () {
+        const prev = yield* readProfileConfig(name);
+        const next = update(prev);
+        yield* writeProfileConfig(name, next);
+        return next;
+    });
+    // Credentials IO ------------------------------------------------------------
+    const enforceCredsMode = (p) => Effect.gen(function* () {
+        const info = yield* fs.stat(p).pipe(Effect.map((i) => i), Effect.catchAll((err) => isNotFound(err)
+            ? Effect.succeed(null)
+            : Effect.fail(toGeneric(err, `failed to stat ${p}`))));
+        if (info === null)
+            return;
+        const mode = info.mode & 0o777;
+        if (mode !== 0o600) {
+            process.stderr.write(`mxs: credentials file ${p} had mode ${mode.toString(8)}; chmod 600\n`);
+            yield* fs.chmod(p, 0o600).pipe(Effect.catchAll(() => Effect.void));
+        }
+    });
+    const readProfileCredentials = (name) => Effect.gen(function* () {
+        const p = profileCredentialsPath(name);
+        const data = yield* readJsonIfExists(fs, p);
+        if (data !== null) {
+            yield* enforceCredsMode(p);
+        }
+        return data;
+    });
+    const writeProfileCredentials = (name, creds) => Effect.gen(function* () {
+        yield* ensureProfileDir(fs, profileDir(name));
+        yield* writeJson(fs, profileCredentialsPath(name), creds, 0o600);
+    });
+    const deleteProfileCredentials = (name) => fs
+        .remove(profileCredentialsPath(name), { force: true })
+        .pipe(Effect.catchAll((err) => isNotFound(err)
+        ? Effect.void
+        : Effect.fail(toGeneric(err, `failed to remove credentials`))));
+    // Legacy IO -----------------------------------------------------------------
+    const readLegacyConfigRaw = readJsonIfExists(fs, legacyConfigPath());
+    const readLegacyCredentialsRaw = readJsonIfExists(fs, legacyCredentialsPath());
+    const readLegacyConfig = Effect.map(readLegacyConfigRaw, (raw) => (raw === null ? {} : stripLegacyConfigFields(raw)));
+    const deleteLegacyConfig = fs
+        .remove(legacyConfigPath(), { force: true })
+        .pipe(Effect.catchAll((err) => isNotFound(err)
+        ? Effect.void
+        : Effect.fail(toGeneric(err, 'failed to remove legacy config'))));
+    const deleteLegacyCredentials = fs
+        .remove(legacyCredentialsPath(), { force: true })
+        .pipe(Effect.catchAll((err) => isNotFound(err)
+        ? Effect.void
+        : Effect.fail(toGeneric(err, 'failed to remove legacy credentials'))));
+    // Current pointer -----------------------------------------------------------
+    const readCurrent = Effect.gen(function* () {
+        const raw = yield* fs.readFileString(currentPath()).pipe(Effect.map((s) => s), Effect.catchAll((err) => isNotFound(err)
+            ? Effect.succeed(null)
+            : Effect.fail(toGeneric(err, 'failed to read current pointer'))));
+        if (raw === null)
+            return null;
+        const name = raw.trim();
+        return name.length > 0 ? name : null;
+    });
+    const writeCurrent = (name) => Effect.gen(function* () {
+        yield* fs
+            .makeDirectory(configDir(), { recursive: true })
+            .pipe(Effect.catchAll((err) => Effect.fail(toGeneric(err, 'failed to create mxs config dir'))));
+        yield* fs
+            .writeFileString(currentPath(), `${name}\n`)
+            .pipe(Effect.catchAll((err) => Effect.fail(toGeneric(err, 'failed to write current pointer'))));
+    });
+    // Profile dir listing -------------------------------------------------------
+    const listProfileDirs = Effect.gen(function* () {
+        const dir = profilesDir();
+        const entries = yield* fs
+            .readDirectory(dir)
+            .pipe(Effect.map((arr) => arr), Effect.catchAll((err) => isNotFound(err)
+            ? Effect.succeed(null)
+            : Effect.fail(toGeneric(err, `failed to list ${dir}`))));
+        if (entries === null)
+            return [];
+        const visible = entries.filter((name) => !name.startsWith('.'));
+        // Filter out non-directory entries (files like `readme.txt`).
+        const out = [];
+        for (const name of visible) {
+            const info = yield* fs.stat(path.join(dir, name)).pipe(Effect.map((i) => i), Effect.catchAll(() => Effect.succeed(null)));
+            if (info && info.type === 'Directory')
+                out.push(name);
+        }
+        return out.sort();
+    });
+    const profileExists = (name) => fs.stat(profileDir(name)).pipe(Effect.map((info) => info.type === 'Directory'), Effect.catchAll((err) => isNotFound(err)
+        ? Effect.succeed(false)
+        : Effect.fail(toGeneric(err, `failed to stat profile ${name}`))));
+    const removeProfileDir = (name) => fs
+        .remove(profileDir(name), { recursive: true, force: true })
+        .pipe(Effect.catchAll((err) => Effect.fail(toGeneric(err, `failed to remove profile ${name}`))));
+    // Resolve ------------------------------------------------------------------
+    const buildLocalDevProfileConfig = () => Effect.gen(function* () {
+        const parsed = yield* parseApiUrl(getLocalDevApiUrl());
+        return {
+            api_url: parsed.baseUrl,
+            api_version: 2,
+            production: false,
+        };
+    });
+    const resolve = (overrides = {}) => Effect.gen(function* () {
+        const envApiUrl = process.env.MXS_API_URL?.trim();
+        const envToken = process.env.MXS_TOKEN?.trim();
+        const envApiKey = process.env.MXS_API_KEY?.trim();
+        const envProfile = process.env.MXS_PROFILE?.trim();
+        const urlOverridden = Boolean(overrides.apiUrl || envApiUrl);
+        const profileExplicit = Boolean(overrides.profile || envProfile);
+        const currentProfile = yield* readCurrent;
+        const useLocalDev = shouldUseLocalDev({
+            profileOverride: overrides.profile,
+            envProfile,
+            apiUrlOverride: overrides.apiUrl,
+            envApiUrl,
+            currentProfile,
+        });
+        const profileName = overrides.profile?.trim() ||
+            envProfile ||
+            (useLocalDev ? LOCAL_DEV_PROFILE_NAME : null) ||
+            currentProfile ||
+            null;
+        const useLocalDevEndpoint = isLocalDevEnabled() &&
+            !urlOverridden &&
+            profileName === LOCAL_DEV_PROFILE_NAME;
+        if (profileName && !urlOverridden && !useLocalDev) {
+            const exists = yield* profileExists(profileName);
+            if (!exists) {
+                return yield* Effect.fail(new ProfileNotFound({
+                    name: profileName,
+                    message: `profile '${profileName}' does not exist`,
+                    hint: 'run `mxs profile ls` to see configured profiles, or `mxs auth login --profile <name>` to create one',
+                }));
+            }
+        }
+        let profileConfig = {};
+        if (useLocalDev) {
+            profileConfig = yield* buildLocalDevProfileConfig();
+        }
+        else if (profileName) {
+            profileConfig = yield* readProfileConfig(profileName);
+        }
+        const rawApiUrl = overrides.apiUrl || envApiUrl || profileConfig.api_url;
+        if (!rawApiUrl) {
+            return yield* Effect.fail(new ConfigMissingApiUrl({
+                message: 'API URL is not configured',
+                hint: 'set MXS_API_URL or pass --api-url <url>, or run `mxs auth login` in an interactive shell',
+            }));
+        }
+        const parsed = yield* parseApiUrl(rawApiUrl);
+        const apiUrl = parsed.baseUrl;
+        const apiVersion = profileConfig.api_version ?? parsed.apiVersion ?? 2;
+        const apiBase = useLocalDevEndpoint
+            ? apiUrl
+            : `${apiUrl}/api/v${apiVersion}`;
+        const authBase = useLocalDevEndpoint
+            ? `${apiUrl}/auth`
+            : `${apiBase}/auth`;
+        let token;
+        if (urlOverridden) {
+            token = overrides.token || envToken || undefined;
+        }
+        else {
+            let profileCreds = null;
+            // Read credentials for the resolved profile, including the synthetic
+            // `local-dev` profile when auth login has written them. Skipping the
+            // read when `useLocalDev` is true was a bug — login writes
+            // credentials under `profiles/local-dev/`, so subsequent commands must
+            // pick them up.
+            if (profileName) {
+                profileCreds = yield* readProfileCredentials(profileName);
+            }
+            token = overrides.token || envToken || profileCreds?.access_token;
+        }
+        const apiKey = overrides.apiKey || envApiKey;
+        const isProduction = urlOverridden
+            ? false
+            : profileName
+                ? Boolean(profileConfig.production)
+                : false;
+        return {
+            apiUrl,
+            apiBase,
+            authBase,
+            apiVersion,
+            clientId: DEFAULT_CLIENT_ID,
+            token,
+            apiKey,
+            configPath: profileName
+                ? profileConfigPath(profileName)
+                : legacyConfigPath(),
+            credentialsPath: profileName
+                ? profileCredentialsPath(profileName)
+                : legacyCredentialsPath(),
+            profileName,
+            isProduction,
+            profileExplicit,
+            urlOverridden,
+        };
+    });
+    const svc = {
+        getConfigDir: Effect.sync(configDir),
+        getProfilesDir: Effect.sync(profilesDir),
+        getProfileDir: (name) => Effect.sync(() => profileDir(name)),
+        getProfileConfigPath: (name) => Effect.sync(() => profileConfigPath(name)),
+        getProfileCredentialsPath: (name) => Effect.sync(() => profileCredentialsPath(name)),
+        getCurrentPath: Effect.sync(currentPath),
+        getLegacyConfigPath: Effect.sync(legacyConfigPath),
+        getLegacyCredentialsPath: Effect.sync(legacyCredentialsPath),
+        readProfileConfig,
+        writeProfileConfig,
+        updateProfileConfig,
+        readProfileCredentials,
+        writeProfileCredentials,
+        deleteProfileCredentials,
+        readLegacyConfig,
+        readLegacyConfigRaw,
+        readLegacyCredentialsRaw,
+        deleteLegacyConfig,
+        deleteLegacyCredentials,
+        readCurrent,
+        writeCurrent,
+        listProfileDirs,
+        profileExists,
+        removeProfileDir,
+        resolve,
+    };
+    return svc;
+});
+export class Config extends Context.Tag('Config')() {
+    static Default = Layer.effect(Config, make);
+}

package/dist/src/services/Editor.d.ts

@@ -0,0 +1,28 @@
+import { FileSystem } from '@effect/platform';
+import { Context, Effect, Layer } from 'effect';
+import { Generic, ValidationFailed } from '../domain/errors';
+export interface EditorRoundTrip {
+    readonly filename: string;
+    readonly initialContent: string;
+    readonly editor?: string;
+}
+export interface EditorService {
+    /** Spawn `$EDITOR` against a tmp file seeded with `initialContent`. */
+    readonly openEditor: (opts: EditorRoundTrip) => Effect.Effect<string, Generic>;
+    /** Prompt for free-form input. */
+    readonly prompt: (message: string, opts?: {
+        readonly initialValue?: string;
+        readonly placeholder?: string;
+    }) => Effect.Effect<string, Generic>;
+    /** Yes/no confirmation. */
+    readonly confirm: (message: string, opts?: {
+        readonly initialValue?: boolean;
+    }) => Effect.Effect<boolean, Generic>;
+    /** Read a file path or stdin (`-` or no path). */
+    readonly readFileOrStdin: (path: string | undefined) => Effect.Effect<string, ValidationFailed | Generic>;
+}
+declare const Editor_base: Context.TagClass<Editor, "Editor", EditorService>;
+export declare class Editor extends Editor_base {
+    static Default: Layer.Layer<Editor, never, FileSystem.FileSystem>;
+}
+export {};

package/dist/src/services/Editor.js

@@ -0,0 +1,95 @@
+import { spawn } from 'node:child_process';
+import os from 'node:os';
+import path from 'node:path';
+import * as Clack from '@clack/prompts';
+import { FileSystem } from '@effect/platform';
+import { Context, Effect, Layer } from 'effect';
+import { Generic, ValidationFailed } from '../domain/errors';
+const messageOf = (err) => {
+    if (err instanceof Error)
+        return err.message;
+    if (typeof err === 'string')
+        return err;
+    return String(err);
+};
+const spawnInteractive = (cmd, args) => new Promise((resolve, reject) => {
+    const child = spawn(cmd, args, { stdio: 'inherit', shell: true });
+    child.on('error', reject);
+    child.on('exit', (code) => {
+        if (code === 0)
+            resolve();
+        else
+            reject(new Error(`editor exited with code ${code}`));
+    });
+});
+const readStdinAll = () => new Promise((resolve, reject) => {
+    const stdin = process.stdin;
+    const chunks = [];
+    stdin.on('data', (chunk) => {
+        chunks.push(typeof chunk === 'string' ? Buffer.from(chunk) : chunk);
+    });
+    stdin.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
+    stdin.on('error', reject);
+    if (stdin.isPaused?.())
+        stdin.resume();
+});
+const makeService = (fs) => ({
+    openEditor: (opts) => Effect.tryPromise({
+        try: async () => {
+            const editor = opts.editor ?? process.env.EDITOR ?? process.env.VISUAL;
+            if (!editor) {
+                throw new Error('$EDITOR not set; export EDITOR=vim (or another editor) and try again');
+            }
+            const dir = await new Promise((resolve, reject) => import('node:fs').then(({ promises }) => promises
+                .mkdtemp(path.join(os.tmpdir(), 'mxs-'))
+                .then(resolve, reject)));
+            const tmpPath = path.join(dir, opts.filename);
+            const nodeFs = await import('node:fs');
+            await nodeFs.promises.writeFile(tmpPath, opts.initialContent, 'utf8');
+            await spawnInteractive(editor, [tmpPath]);
+            const next = await nodeFs.promises.readFile(tmpPath, 'utf8');
+            await nodeFs.promises.unlink(tmpPath).catch(() => undefined);
+            await nodeFs.promises.rmdir(dir).catch(() => undefined);
+            return next;
+        },
+        catch: (err) => new Generic({ message: messageOf(err), cause: err }),
+    }),
+    prompt: (message, opts) => Effect.tryPromise({
+        try: () => Clack.text({
+            message,
+            initialValue: opts?.initialValue,
+            placeholder: opts?.placeholder,
+        }),
+        catch: (err) => new Generic({ message: messageOf(err), cause: err }),
+    }).pipe(Effect.flatMap((value) => Clack.isCancel(value)
+        ? Effect.fail(new Generic({ message: 'cancelled by user' }))
+        : Effect.succeed(value))),
+    confirm: (message, opts) => Effect.tryPromise({
+        try: () => Clack.confirm({
+            message,
+            initialValue: opts?.initialValue,
+        }),
+        catch: (err) => new Generic({ message: messageOf(err), cause: err }),
+    }).pipe(Effect.flatMap((value) => Clack.isCancel(value)
+        ? Effect.fail(new Generic({ message: 'cancelled by user' }))
+        : Effect.succeed(value))),
+    readFileOrStdin: (p) => {
+        if (p === undefined || p === '-' || p === '') {
+            return Effect.tryPromise({
+                try: () => readStdinAll(),
+                catch: (err) => new ValidationFailed({
+                    message: `failed to read stdin: ${messageOf(err)}`,
+                }),
+            });
+        }
+        return fs.readFileString(p).pipe(Effect.mapError((err) => new ValidationFailed({
+            message: `failed to read ${p}: ${messageOf(err)}`,
+        })));
+    },
+});
+export class Editor extends Context.Tag('Editor')() {
+    static Default = Layer.effect(Editor, Effect.gen(function* () {
+        const fs = yield* FileSystem.FileSystem;
+        return makeService(fs);
+    }));
+}

package/dist/src/services/Lexical.d.ts

@@ -0,0 +1,27 @@
+import { Context, Effect, Layer } from 'effect';
+import { ValidationXml } from '../domain/errors';
+export interface LexicalState {
+    readonly root: {
+        readonly type: 'root';
+        readonly children: ReadonlyArray<unknown>;
+        readonly direction?: 'ltr' | 'rtl' | null;
+        readonly format?: string;
+        readonly indent?: number;
+        readonly version?: number;
+    };
+}
+export interface LexicalService {
+    /** Parse LiteXML into a Lexical editor state. */
+    readonly litexmlToPayload: (xml: string) => Effect.Effect<LexicalState, ValidationXml>;
+    /** Serialize a Lexical editor state back to LiteXML. */
+    readonly payloadToLitexml: (state: LexicalState) => Effect.Effect<string, ValidationXml>;
+    /** Derive a Markdown rendering from a Lexical state (used for `--output llm`). */
+    readonly lexicalJsonToMarkdown: (state: LexicalState) => Effect.Effect<string, ValidationXml>;
+    /** Convenience: a blank Lexical state for new-document scaffolds. */
+    readonly emptyState: Effect.Effect<LexicalState>;
+}
+declare const Lexical_base: Context.TagClass<Lexical, "Lexical", LexicalService>;
+export declare class Lexical extends Lexical_base {
+    static Default: Layer.Layer<Lexical>;
+}
+export {};

package/dist/src/services/Lexical.js

@@ -0,0 +1,56 @@
+import { deserializeMxLitexmlToLexical, mxLexicalToMarkdown, serializeMxLexicalToLitexml, stripMxLitexmlDocWrapper, } from '@mx-space/editor';
+import { Context, Effect, Layer } from 'effect';
+import { ValidationXml } from '../domain/errors';
+const messageOf = (err) => {
+    if (err instanceof Error)
+        return err.message;
+    if (typeof err === 'string')
+        return err;
+    return String(err);
+};
+const makeService = () => ({
+    litexmlToPayload: (xml) => Effect.try({
+        try: () => {
+            const wrapped = xml.includes('<doc') ? xml : `<doc>${xml}</doc>`;
+            return deserializeMxLitexmlToLexical(wrapped);
+        },
+        catch: (err) => new ValidationXml({
+            message: `failed to parse LiteXML: ${messageOf(err)}`,
+            cause: err,
+        }),
+    }),
+    payloadToLitexml: (state) => Effect.try({
+        try: () => {
+            const xml = serializeMxLexicalToLitexml(state, {
+                compact: false,
+            });
+            return stripMxLitexmlDocWrapper(xml).trim();
+        },
+        catch: (err) => new ValidationXml({
+            message: `failed to serialize Lexical state: ${messageOf(err)}`,
+            cause: err,
+        }),
+    }),
+    lexicalJsonToMarkdown: (state) => Effect.try({
+        try: () => {
+            return mxLexicalToMarkdown(state);
+        },
+        catch: (err) => new ValidationXml({
+            message: `failed to render Markdown: ${messageOf(err)}`,
+            cause: err,
+        }),
+    }),
+    emptyState: Effect.sync(() => ({
+        root: {
+            type: 'root',
+            children: [],
+            direction: 'ltr',
+            format: '',
+            indent: 0,
+            version: 1,
+        },
+    })),
+});
+export class Lexical extends Context.Tag('Lexical')() {
+    static Default = Layer.succeed(Lexical, makeService());
+}

package/dist/src/services/Migration.d.ts

@@ -0,0 +1,31 @@
+import { FileSystem } from '@effect/platform';
+import { Context, Effect, Layer } from 'effect';
+import { ConfigMigrationFailed, type Generic } from '../domain/errors';
+import { Config } from './Config';
+export interface MigrationResult {
+    readonly profile: string | null;
+    readonly production: boolean;
+    readonly cleanedStaleLegacy: boolean;
+}
+export interface MigrationOptions {
+    /** Defaults to process.stdin.isTTY && process.stdout.isTTY. */
+    readonly isTTY?: boolean;
+    /**
+     * Injected for tests. Called when TTY + legacy api_url present. Resolves
+     * `true` to set production. May resolve a symbol (treated as cancel → false).
+     */
+    readonly promptIsProduction?: (apiUrl: string) => Promise<boolean | symbol>;
+    /**
+     * Where to emit status messages. Defaults to `process.stderr`. Pass `null`
+     * to suppress entirely.
+     */
+    readonly report?: ((line: string) => void) | null;
+}
+export interface MigrationService {
+    readonly runLegacyMigrationIfNeeded: (opts?: MigrationOptions) => Effect.Effect<MigrationResult | null, ConfigMigrationFailed | Generic>;
+}
+declare const Migration_base: Context.TagClass<Migration, "Migration", MigrationService>;
+export declare class Migration extends Migration_base {
+    static Default: Layer.Layer<Migration, never, Config | FileSystem.FileSystem>;
+}
+export {};