@mx-space/cli 0.6.1 → 0.6.2

package/README.md

@@ -485,6 +485,20 @@ Example profile config:
 | `6`  | Server 5xx failure                                                           |
 | `7`  | Resource not found                                                           |
 
+## Preview
+
+`mxs preview <file>` renders a LiteXML fragment or `<mxpost>` / `<mxnote>` envelope to HTML and opens it in your default browser. Use it to sanity-check what the article will look like before publishing.
+
+```bash
+mxs preview ./post.xml                 # open in browser
+mxs preview - < note.xml               # read stdin
+mxs preview ./post.xml --theme dark    # dark theme
+mxs preview ./post.xml --save out.html # write HTML to file
+mxs preview ./post.xml --print         # emit HTML to stdout
+```
+
+The variant (`article` / `note`) is auto-detected from the envelope root. Override with `--variant` for raw LiteXML fragments. The command does not contact `mx-core` — it's a pure local render via `@haklex/rich-litexml-cli`.
+
 ## Skill bundle
 
 `mxs skill` exposes the bundled AI-agent documentation directly from the CLI binary. Chapters are shipped inside the published `@mx-space/cli` package; liteXML chapters are pulled live from `@haklex/rich-litexml` at runtime (requires `@haklex/rich-litexml@>=0.16.0`).

package/ROADMAP.md

@@ -8,9 +8,10 @@
 
 - Internal rewrite onto Effect-TS (`@effect/cli` + `@effect/platform`). User-facing CLI surface is unchanged — see [`README.md`](./README.md#v030-behavior-changes) for the small list of behavioral adjustments and [`docs/architecture.md`](./docs/architecture.md) for the new internal architecture.
 
-## Shipped in v0.7
+## Shipped in v0.6
 
 - `mxs skill` — bundled AI-agent documentation. List, get, all, search across chapters shipped inside the CLI (`packages/cli/skills/*.md`); liteXML chapters loaded live from the installed `@haklex/rich-litexml` package. Default output is raw markdown for direct context injection.
+- `mxs preview <file>` — local HTML preview of a LiteXML fragment or `<mxpost>` / `<mxnote>` envelope. Wraps `@haklex/rich-litexml-cli` so the output matches the editor renderer.
 
 ## Next — Comment moderation
 

package/dist/bin/mxs.mjs

@@ -1,3 +1,3 @@
 #!/usr/bin/env node
-import { t as run } from "../mxs-Bs_7ZKs9.mjs";
+import { t as run } from "../mxs-BxXhmqqF.mjs";
 export { run };

package/dist/index.mjs

@@ -1,2 +1,2 @@
-import { a as defaultMessageFor, c as tagToCode, i as codeForTag, l as toErrorEnvelope, n as defaultGlobalFlags, o as exitCodeForError, r as parseGlobalFlags, s as exitCodeForTag, t as run } from "./mxs-Bs_7ZKs9.mjs";
+import { a as defaultMessageFor, c as tagToCode, i as codeForTag, l as toErrorEnvelope, n as defaultGlobalFlags, o as exitCodeForError, r as parseGlobalFlags, s as exitCodeForTag, t as run } from "./mxs-BxXhmqqF.mjs";
 export { codeForTag, defaultGlobalFlags, defaultMessageFor, exitCodeForError, exitCodeForTag, parseGlobalFlags, run, tagToCode, toErrorEnvelope };

package/dist/{mxs-Bs_7ZKs9.mjs → mxs-BxXhmqqF.mjs}

@@ -24,7 +24,7 @@ import * as ChildProcess from "node:child_process";
 import childProcess, { execFile, spawn } from "node:child_process";
 import * as readline from "node:readline";
 import E from "node:readline";
-import V, { stdin, stdout } from "node:process";
+import process$1, { stdin, stdout } from "node:process";
 import "node:tty";
 //#region ../../node_modules/.pnpm/@effect+platform@0.96.1_effect@3.21.2/node_modules/@effect/platform/dist/esm/Error.js
 /**
@@ -9042,7 +9042,7 @@ function isInsideContainer() {
 //#endregion
 //#region ../../node_modules/.pnpm/is-wsl@3.1.1/node_modules/is-wsl/index.js
 const isWsl = () => {
-	if (V.platform !== "linux") return false;
+	if (process$1.platform !== "linux") return false;
 	if (os.release().toLowerCase().includes("microsoft")) {
 		if (isInsideContainer()) return false;
 		return true;
@@ -9053,11 +9053,11 @@ const isWsl = () => {
 	if (fs.existsSync("/proc/sys/fs/binfmt_misc/WSLInterop") || fs.existsSync("/run/WSL")) return !isInsideContainer();
 	return false;
 };
-var is_wsl_default = V.env.__IS_WSL_TEST__ ? isWsl : isWsl();
+var is_wsl_default = process$1.env.__IS_WSL_TEST__ ? isWsl : isWsl();
 //#endregion
 //#region ../../node_modules/.pnpm/powershell-utils@0.1.0/node_modules/powershell-utils/index.js
 const execFile$2 = promisify(childProcess.execFile);
-const powerShellPath$1 = () => `${V.env.SYSTEMROOT || V.env.windir || String.raw`C:\Windows`}\\System32\\WindowsPowerShell\\v1.0\\powershell.exe`;
+const powerShellPath$1 = () => `${process$1.env.SYSTEMROOT || process$1.env.windir || String.raw`C:\Windows`}\\System32\\WindowsPowerShell\\v1.0\\powershell.exe`;
 const executePowerShell = async (command, options = {}) => {
 	const { powerShellPath: psPath, ...execFileOptions } = options;
 	const encodedCommand = executePowerShell.encodeCommand(command);
@@ -9164,7 +9164,7 @@ function defineLazyProperty(object, propertyName, valueGetter) {
 //#region ../../node_modules/.pnpm/default-browser-id@5.0.1/node_modules/default-browser-id/index.js
 const execFileAsync$3 = promisify(execFile);
 async function defaultBrowserId() {
-	if (V.platform !== "darwin") throw new Error("macOS only");
+	if (process$1.platform !== "darwin") throw new Error("macOS only");
 	const { stdout } = await execFileAsync$3("defaults", [
 		"read",
 		"com.apple.LaunchServices/com.apple.launchservices.secure",
@@ -9178,7 +9178,7 @@ async function defaultBrowserId() {
 //#region ../../node_modules/.pnpm/run-applescript@7.1.0/node_modules/run-applescript/index.js
 const execFileAsync$2 = promisify(execFile);
 async function runAppleScript(script, { humanReadableOutput = true, signal } = {}) {
-	if (V.platform !== "darwin") throw new Error("macOS only");
+	if (process$1.platform !== "darwin") throw new Error("macOS only");
 	const outputArguments = humanReadableOutput ? [] : ["-ss"];
 	const execOptions = {};
 	if (signal) execOptions.signal = signal;
@@ -9289,14 +9289,14 @@ async function defaultBrowser$1(_execFileAsync = execFileAsync$1) {
 const execFileAsync = promisify(execFile);
 const titleize = (string) => string.toLowerCase().replaceAll(/(?:^|\s|-)\S/g, (x) => x.toUpperCase());
 async function defaultBrowser() {
-	if (V.platform === "darwin") {
+	if (process$1.platform === "darwin") {
 		const id = await defaultBrowserId();
 		return {
 			name: await bundleName(id),
 			id
 		};
 	}
-	if (V.platform === "linux") {
+	if (process$1.platform === "linux") {
 		const { stdout } = await execFileAsync("xdg-mime", [
 			"query",
 			"default",
@@ -9308,18 +9308,18 @@ async function defaultBrowser() {
 			id
 		};
 	}
-	if (V.platform === "win32") return defaultBrowser$1();
+	if (process$1.platform === "win32") return defaultBrowser$1();
 	throw new Error("Only macOS, Linux, and Windows are supported");
 }
 //#endregion
 //#region ../../node_modules/.pnpm/is-in-ssh@1.0.0/node_modules/is-in-ssh/index.js
-const isInSsh = Boolean(V.env.SSH_CONNECTION || V.env.SSH_CLIENT || V.env.SSH_TTY);
+const isInSsh = Boolean(process$1.env.SSH_CONNECTION || process$1.env.SSH_CLIENT || process$1.env.SSH_TTY);
 //#endregion
 //#region ../../node_modules/.pnpm/open@11.0.0/node_modules/open/index.js
 const fallbackAttemptSymbol = Symbol("fallbackAttempt");
 const __dirname = import.meta.url ? path.dirname(fileURLToPath(import.meta.url)) : "";
 const localXdgOpenPath = path.join(__dirname, "xdg-open");
-const { platform: platform$1, arch: arch$1 } = V;
+const { platform: platform$1, arch: arch$1 } = process$1;
 const tryEachApp = async (apps, opener) => {
 	if (apps.length === 0) return;
 	const errors = [];
@@ -9432,7 +9432,7 @@ const baseOpen = async (options) => {
 				await fs$1.access(localXdgOpenPath, constants.X_OK);
 				exeLocalXdgOpen = true;
 			} catch {}
-			command = V.versions.electron ?? (platform$1 === "android" || isBundled || !exeLocalXdgOpen) ? "xdg-open" : localXdgOpenPath;
+			command = process$1.versions.electron ?? (platform$1 === "android" || isBundled || !exeLocalXdgOpen) ? "xdg-open" : localXdgOpenPath;
 		}
 		if (appArguments.length > 0) cliArguments.push(...appArguments);
 		if (!options.wait) {
@@ -10889,7 +10889,7 @@ var ht$1 = class extends m {
 //#endregion
 //#region ../../node_modules/.pnpm/@clack+prompts@1.4.0/node_modules/@clack/prompts/dist/index.mjs
 function ee() {
-	return V.platform !== "win32" ? V.env.TERM !== "linux" : !!V.env.CI || !!V.env.WT_SESSION || !!V.env.TERMINUS_SUBLIME || V.env.ConEmuTask === "{cmd::Cmder}" || V.env.TERM_PROGRAM === "Terminus-Sublime" || V.env.TERM_PROGRAM === "vscode" || V.env.TERM === "xterm-256color" || V.env.TERM === "alacritty" || V.env.TERMINAL_EMULATOR === "JetBrains-JediTerm";
+	return process$1.platform !== "win32" ? process$1.env.TERM !== "linux" : !!process$1.env.CI || !!process$1.env.WT_SESSION || !!process$1.env.TERMINUS_SUBLIME || process$1.env.ConEmuTask === "{cmd::Cmder}" || process$1.env.TERM_PROGRAM === "Terminus-Sublime" || process$1.env.TERM_PROGRAM === "vscode" || process$1.env.TERM === "xterm-256color" || process$1.env.TERM === "alacritty" || process$1.env.TERMINAL_EMULATOR === "JetBrains-JediTerm";
 }
 const tt = ee(), w = (t, i) => tt ? t : i, Tt = w("◆", "*"), at = w("■", "x"), ut = w("▲", "x"), H = w("◇", "o");
 const $ = w("│", "|"), x = w("└", "—");
@@ -27683,14 +27683,14 @@ const decideWriteGate = (resolved, method) => {
 };
 //#endregion
 //#region src/domain/version.ts
-const requireFrom$3 = createRequire(import.meta.url);
+const requireFrom$4 = createRequire(import.meta.url);
 const resolveCliVersion$2 = () => {
 	for (const candidate of [
 		"../package.json",
 		"../../package.json",
 		"../../../package.json"
 	]) try {
-		const pkg = requireFrom$3(candidate);
+		const pkg = requireFrom$4(candidate);
 		if (pkg.name === "@mx-space/cli" && typeof pkg.version === "string") return pkg.version;
 	} catch {}
 	return "0.0.0-unknown";
@@ -31747,6 +31747,150 @@ const postCmd = make$13("post").pipe(withDescription(help$3.description), withSu
 	unpublish
 ]));
 //#endregion
+//#region src/cli/preview/index.ts
+registerCommandHelp({
+	name: "preview",
+	description: "render a LiteXML fragment or <mxpost>/<mxnote> envelope to HTML and open it in a browser",
+	isLeaf: true,
+	leafOptions: [
+		{
+			flag: "--theme <light|dark>",
+			description: "HTML theme; default: light"
+		},
+		{
+			flag: "--variant <article|note|comment>",
+			description: "HTML variant; auto-detected from envelope root, default: article"
+		},
+		{
+			flag: "--save <path>",
+			description: "write HTML to <path> instead of opening a browser"
+		},
+		{
+			flag: "--print",
+			description: "emit HTML to stdout instead of opening a browser"
+		}
+	]
+});
+const fileArg = text$3({ name: "file" }).pipe(optional$4);
+const themeOpt = choice("theme", ["light", "dark"]).pipe(optional$2);
+const variantOpt = choice("variant", [
+	"article",
+	"note",
+	"comment"
+]).pipe(optional$2);
+const saveOpt = text$1("save").pipe(optional$2);
+const printOpt = boolean("print").pipe(optional$2);
+const requireFrom$3 = createRequire(import.meta.url);
+const resolveLitexmlBin = () => {
+	try {
+		return requireFrom$3.resolve("@haklex/rich-litexml-cli/dist/cli.mjs");
+	} catch {}
+	const here = import.meta.url;
+	const filePath = here.startsWith("file://") ? here.slice(7) : here;
+	let dir = filePath.slice(0, Math.max(0, filePath.lastIndexOf("/")));
+	for (let i = 0; i < 8; i++) {
+		const candidate = `${dir}/node_modules/@haklex/rich-litexml-cli/dist/cli.mjs`;
+		try {
+			requireFrom$3(`${candidate}`);
+			return candidate;
+		} catch {}
+		const next = dir.slice(0, Math.max(0, dir.lastIndexOf("/")));
+		if (next === dir) break;
+		dir = next;
+	}
+	throw new Generic({
+		message: "cannot resolve @haklex/rich-litexml-cli binary",
+		hint: "reinstall mxs or run `pnpm install` so the dependency is present"
+	});
+};
+const detectVariant = (body) => {
+	const trimmed = body.trimStart();
+	if (trimmed.startsWith("<mxpost")) return {
+		contentXml: parseEnvelope(trimmed, "post").contentXml,
+		variant: "article"
+	};
+	if (trimmed.startsWith("<mxnote")) return {
+		contentXml: parseEnvelope(trimmed, "note").contentXml,
+		variant: "note"
+	};
+	return {
+		contentXml: body,
+		variant: "article"
+	};
+};
+const spawnLitexml = (bin, input, args, capture) => tryPromise({
+	try: () => new Promise((resolve, reject) => {
+		const child = spawn(process.execPath, [
+			bin,
+			"-",
+			...args
+		], { stdio: capture ? [
+			"pipe",
+			"pipe",
+			"inherit"
+		] : [
+			"pipe",
+			"inherit",
+			"inherit"
+		] });
+		const out = [];
+		if (capture && child.stdout) child.stdout.on("data", (chunk) => out.push(chunk));
+		child.on("error", reject);
+		child.on("exit", (code) => {
+			if (code === 0) resolve(capture ? Buffer.concat(out).toString("utf8") : "");
+			else reject(/* @__PURE__ */ new Error(`litexml exited with code ${code}`));
+		});
+		if (!child.stdin) {
+			reject(/* @__PURE__ */ new Error("failed to open litexml stdin"));
+			return;
+		}
+		child.stdin.write(input);
+		child.stdin.end();
+	}),
+	catch: (err) => new Generic({
+		message: err instanceof Error ? err.message : String(err),
+		cause: err
+	})
+});
+const previewCmd = make$13("preview", {
+	file: fileArg,
+	theme: themeOpt,
+	variant: variantOpt,
+	save: saveOpt,
+	print: printOpt
+}, ({ file, theme, variant, save, print }) => gen(function* () {
+	const editor = yield* Editor;
+	const renderer = yield* Renderer;
+	const filePath = getOrUndefined(file);
+	const raw = yield* editor.readFileOrStdin(filePath);
+	let body;
+	let detectedVariant = "article";
+	try {
+		const det = detectVariant(raw);
+		body = det.contentXml;
+		detectedVariant = det.variant;
+	} catch (err) {
+		return yield* fail$2(err instanceof ValidationXml ? err : new ValidationXml({ message: err instanceof Error ? err.message : String(err) }));
+	}
+	const resolvedVariant = getOrElse(variant, () => detectedVariant);
+	const resolvedTheme = getOrUndefined(theme);
+	const savePath = getOrUndefined(save);
+	const printMode = getOrElse(print, () => false);
+	const args = [
+		"--format",
+		"html",
+		"--variant",
+		resolvedVariant
+	];
+	if (resolvedTheme) args.push("--theme", resolvedTheme);
+	if (savePath) args.push("-o", savePath);
+	else if (!printMode) args.push("--open");
+	const html = yield* spawnLitexml(resolveLitexmlBin(), body, args, printMode);
+	if (printMode) process.stdout.write(html.endsWith("\n") ? html : `${html}\n`);
+	else if (savePath) yield* renderer.emitInfo(`wrote HTML preview to ${savePath}`);
+	else yield* renderer.emitInfo(`opened HTML preview (variant=${resolvedVariant})`);
+}));
+//#endregion
 //#region src/cli/profile/view.ts
 const profileListView = {
 	kind: "profile-list",
@@ -34500,6 +34644,7 @@ const GROUP_NAMES = [
 	"comment",
 	"config",
 	"skill",
+	"preview",
 	"update"
 ];
 const isGroupName = (s) => GROUP_NAMES.includes(s);
@@ -34703,7 +34848,11 @@ const PREFLIGHT_EXEMPT_COMMANDS = [{
 * 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`).
 */
-const PREFLIGHT_EXEMPT_TOPLEVEL = new Set(["update", "skill"]);
+const PREFLIGHT_EXEMPT_TOPLEVEL = new Set([
+	"update",
+	"skill",
+	"preview"
+]);
 /** Returns true if the command is exempt from the profile.none_active guard. */
 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);
@@ -34730,6 +34879,7 @@ const TOPLEVEL_COMMANDS = new Set([
 	"topic",
 	"config",
 	"skill",
+	"preview",
 	"update"
 ]);
 /**
@@ -35105,6 +35255,7 @@ const rootCmd = make$13("mxs", {}, () => flatMap$1(Renderer, (r) => r.emitInfo("
 	commentCmd,
 	configCmd,
 	skillCmd,
+	previewCmd,
 	updateCmd
 ]));
 const preflight = (flags) => gen(function* () {
@@ -35150,7 +35301,11 @@ const preflight = (flags) => gen(function* () {
 		parentName: invoked.parentName
 	}));
 });
-const LEAF_COMMANDS = new Set(["update", "skill"]);
+const LEAF_COMMANDS = new Set([
+	"update",
+	"skill",
+	"preview"
+]);
 const detectHelpTarget = (rest) => {
 	const args = rest.slice(2);
 	if (args.length === 0) return { kind: "root" };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mx-space/cli",
-  "version": "0.6.1",
+  "version": "0.6.2",
   "description": "Command line interface for mx-space (mx-core) — auth, content, configuration",
   "keywords": [
     "mx-space",
@@ -54,6 +54,7 @@
     "@effect/platform-node": "0.106.0",
     "@haklex/rich-headless": "0.13.0",
     "@haklex/rich-litexml": "0.15.2",
+    "@haklex/rich-litexml-cli": "0.15.2",
     "@lexical/headless": "^0.44.0",
     "better-auth": "^1.6.9",
     "effect": "3.21.2",

package/skills/commands-preview.md

@@ -0,0 +1,58 @@
+---
+slug: commands-preview
+title: Preview command
+description: render LiteXML / envelope to HTML and open it in a browser
+order: 39
+---
+
+# Preview command
+
+`mxs preview` renders a LiteXML fragment or `<mxpost>` / `<mxnote>` envelope to HTML and (by default) opens it in the system browser. It is a thin wrapper around the `@haklex/rich-litexml-cli` `litexml --format html` pipeline, so the output matches what the editor would render once published.
+
+| Command                                  | Behavior                                                                    |
+| ---------------------------------------- | --------------------------------------------------------------------------- |
+| `mxs preview <file>`                     | Render the file and open the preview in a browser.                          |
+| `mxs preview -`                          | Read LiteXML or envelope from stdin and open the preview.                   |
+| `mxs preview <file> --print`             | Emit HTML to stdout instead of opening a browser.                           |
+| `mxs preview <file> --save <out.html>`   | Write HTML to `<out.html>` instead of opening a browser.                    |
+
+## Flags
+
+| Flag                                       | Meaning                                                                                          |
+| ------------------------------------------ | ------------------------------------------------------------------------------------------------ |
+| `--theme <light\|dark>`                    | HTML theme. Default `light`.                                                                     |
+| `--variant <article\|note\|comment>`       | HTML variant. Auto-detected from the envelope root (`<mxpost>` → `article`, `<mxnote>` → `note`). |
+| `--save <path>`                            | Write HTML to a file instead of opening the browser. Mutually exclusive with `--print`.          |
+| `--print`                                  | Emit HTML to stdout. Mutually exclusive with `--save`.                                           |
+
+## Behavior notes
+
+- Input format is auto-detected. If the input starts with `<mxpost>` or `<mxnote>`, the envelope is parsed and only the `<content>` body is rendered (envelope `<meta>` such as title, category, tags is **not** reflected in the HTML preview — this command is for visualising the article body, not the listing card).
+- For raw LiteXML fragments (no envelope wrapper), the entire input is treated as the article body.
+- Variant detection only fires when an envelope is supplied. Override with `--variant` when previewing a raw fragment that should render as a note or comment.
+- The command does not contact the `mx-core` server and does not require an active profile.
+
+## Examples
+
+```bash
+# Open envelope file in browser
+mxs preview ./post.xml
+
+# Pipe from another tool
+some-generator | mxs preview -
+
+# Dark theme, save to file
+mxs preview ./note.xml --theme dark --save ./preview.html
+
+# Emit HTML to stdout (e.g. for CI)
+mxs preview ./post.xml --print > preview.html
+```
+
+## Failure modes
+
+| Symptom                                                  | Likely cause                                                                                   |
+| -------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| `cannot resolve @haklex/rich-litexml-cli binary`         | Installed dep is broken; reinstall `@mx-space/cli` or run `pnpm install`.                      |
+| `Cannot resolve @haklex/rich-compose asset "style.css"`  | Outdated `@haklex/rich-compose` (< 0.15.2). Upgrade or reinstall.                              |
+| `expected root <mxpost>` / `expected root <mxnote>`      | Input begins with the wrong envelope root, or the envelope is malformed. Check the root tag.   |
+| Browser does not open                                    | `--open` shells out to the system `open`/`xdg-open`/`start`. Use `--save` or `--print` instead. |

package/skills/overview.md

@@ -26,6 +26,7 @@ The audience is **AI agents**. Pass `--output llm` for raw markdown suitable for
 | Server-side options                           | `commands-config`                |
 | Authentication                                | `commands-auth`                  |
 | Local profile management                      | `commands-profile`               |
+| Browser preview of LiteXML / envelopes        | `commands-preview`               |
 | Profiles, env vars, target selection          | `auth-config`                    |
 | Output modes (`--json`, `--output llm`, …)    | `output-modes`                   |
 | Mutation safety, verification, exit codes     | `safety`                         |