@mx-space/cli 0.6.1 → 0.6.3

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-Dj82UF06.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-Dj82UF06.mjs";
 export { codeForTag, defaultGlobalFlags, defaultMessageFor, exitCodeForError, exitCodeForTag, parseGlobalFlags, run, tagToCode, toErrorEnvelope };

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

@@ -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.3",
   "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.3",
     "@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`                         |