@mx-space/cli 0.13.1 → 0.13.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mx-space/cli",
-  "version": "0.13.1",
+  "version": "0.13.3",
   "description": "Command line interface for mx-space (mx-core) — auth, content, configuration",
   "keywords": [
     "mx-space",
@@ -47,34 +47,33 @@
   "publishConfig": {
     "access": "public"
   },
-  "dependencies": {
-    "@clack/prompts": "^1.5.1",
+  "devDependencies": {
+    "@clack/prompts": "^1.6.0",
     "@effect/cli": "0.75.2",
-    "@effect/platform": "0.96.1",
+    "@effect/platform": "0.96.2",
     "@effect/platform-node": "0.107.0",
-    "@haklex/rich-headless": "0.27.0",
-    "@haklex/rich-litexml": "0.27.0",
-    "@haklex/rich-litexml-cli": "0.27.0",
-    "@lexical/headless": "^0.45.0",
-    "better-auth": "^1.6.16",
-    "effect": "3.21.3",
-    "fast-xml-parser": "5.8.0",
+    "@effect/vitest": "0.29.0",
+    "@haklex/rich-compose": "0.29.2",
+    "@haklex/rich-headless": "0.29.1",
+    "@haklex/rich-litexml": "0.29.0",
+    "@haklex/rich-litexml-cli": "0.29.3",
+    "@lexical/headless": "^0.46.0",
+    "@types/node": "26.0.1",
+    "@types/semver": "7.7.1",
+    "better-auth": "^1.6.23",
+    "effect": "3.21.4",
+    "fast-xml-parser": "5.9.3",
     "get-east-asian-width": "^1.6.0",
-    "lexical": "^0.45.0",
+    "lexical": "^0.46.0",
     "minisearch": "^7.2.0",
     "open": "^11.0.0",
-    "semver": "7.8.4",
-    "@mx-space/api-client": "5.3.1",
-    "@mx-space/editor": "0.1.0"
-  },
-  "devDependencies": {
-    "@effect/vitest": "0.29.0",
-    "@types/node": "25.9.3",
-    "@types/semver": "7.7.1",
-    "tsdown": "0.22.2",
+    "semver": "7.8.5",
+    "tsdown": "0.22.3",
     "tsx": "^4.22.4",
     "typescript": "6.0.3",
-    "vitest": "4.1.8"
+    "vitest": "4.1.9",
+    "@mx-space/editor": "0.2.0",
+    "@mx-space/api-client": "5.4.0"
   },
   "scripts": {
     "package": "rm -rf dist && tsdown",

package/skills/commands-ai.md

@@ -0,0 +1,115 @@
+---
+slug: commands-ai
+title: AI commands
+description: mxs ai — manage AI summary / translation / insights artifacts
+order: 45
+---
+
+# AI commands
+
+`mxs ai` manages every AI artifact the core server produces: per-article **summary**, per-article **translation**, per-article **insights**, plus the i18n **translation entries** dictionary used for category / topic / note metadata.
+
+Article references (`<id>`) accept a Snowflake id, a post slug, or a numeric note nid. The CLI resolves through post first, then note. Record references (`<recordId>`) are raw Snowflakes — they are NOT resolved.
+
+## Generate verbs (async)
+
+`summary regen`, `translate run`, `insights refresh` enqueue a task and poll `GET /tasks/:id` until terminal (`succeeded` / `failed` / `cancelled`, or the spec-2 `completed` / `partial_failed` aliases). Progress lines write to stderr. `--no-wait` returns immediately with `status: pending`. If the server reports `created: false`, an in-flight deduplicated task already exists; the CLI joins it instead of erroring. Polling cadence is 1000 ms by default; override with `MXS_AI_POLL_MS=<ms>` for tests.
+
+| Command                                              | Purpose                                                         |
+| ---------------------------------------------------- | --------------------------------------------------------------- |
+| `mxs ai summary regen <id> [--to <lang>...]`         | Regenerate an article's AI summary.                             |
+| `mxs ai translate run <id> --to <lang>...`           | Translate an article into one or more languages (`--to` required, repeatable). |
+| `mxs ai insights refresh <id> [--to <lang>...]`      | Refresh AI insights for an article.                             |
+
+Common flags on the three generate verbs:
+
+| Flag             | Effect                                                             |
+| ---------------- | ------------------------------------------------------------------ |
+| `--to <lang>`    | Target language code (repeatable). Forwarded as `targetLanguages`. |
+| `--no-wait`      | Return after task creation; print `status: pending` and exit 0.    |
+
+On success the CLI emits an `ai-task` view: `taskId`, `status`, `refId`, `targetLanguages`, `totalTokens`, `totalCost` (cents), `resultIds`.
+
+## Summary read / manage
+
+| Command                                                       | Purpose                                                       |
+| ------------------------------------------------------------- | ------------------------------------------------------------- |
+| `mxs ai summary list [--page <n>] [--size <n>] [--grouped]`   | List summaries (flat or grouped by article).                  |
+| `mxs ai summary get <recordId>`                               | Get one summary by record id.                                 |
+| `mxs ai summary by-article <id> [--lang <l>] [--only-db]`     | Show an article's summary; `--only-db` skips auto-generation. |
+| `mxs ai summary edit <recordId>`                              | Edit the `summary` field via `$EDITOR` (JSON envelope).       |
+| `mxs ai summary delete <recordId> [--force]`                  | Delete a summary record. `--force` required in non-TTY.       |
+
+## Translation read / manage
+
+There is no flat list endpoint for translations server-side. `mxs ai translate list` is always grouped by article.
+
+| Command                                                  | Purpose                                                  |
+| -------------------------------------------------------- | -------------------------------------------------------- |
+| `mxs ai translate list [--page <n>] [--size <n>]`        | List translations (grouped by article).                  |
+| `mxs ai translate get <recordId>`                        | Get one translation by record id.                        |
+| `mxs ai translate by-article <id> [--lang <l>]`          | Show an article's translations (single lang or all).     |
+| `mxs ai translate languages <id>`                        | List languages an article has been translated into.      |
+| `mxs ai translate edit <recordId>`                       | Edit translation fields via `$EDITOR` (JSON envelope).   |
+| `mxs ai translate delete <recordId> [--force]`           | Delete a translation record.                             |
+
+Edit envelope keys: `title`, `text`, `subtitle` (nullable), `summary`, `tags`, `content`. Only included keys are PATCHed.
+
+## Translation entries (i18n dictionary)
+
+The dictionary layer used for category / topic / note metadata translations. `--key-path` accepts ONLY the server-validated set: `category.name`, `topic.name`, `topic.introduce`, `topic.description`, `note.mood`, `note.weather`.
+
+| Command                                                                                     | Purpose                                                |
+| ------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
+| `mxs ai translate entries list [--page <n>] [--size <n>] [--key-path <p>] [--lang <l>]`     | List entries with optional filters.                    |
+| `mxs ai translate entries generate [--key-path <p>...] [--to <lang>...]`                    | Regenerate entries (synchronous on the server).        |
+| `mxs ai translate entries edit <recordId>`                                                  | Edit `translatedText` via `$EDITOR` (JSON envelope).   |
+| `mxs ai translate entries delete <recordId> [--force]`                                      | Delete an entry.                                       |
+
+## Insights read / manage
+
+| Command                                                       | Purpose                                                        |
+| ------------------------------------------------------------- | -------------------------------------------------------------- |
+| `mxs ai insights list [--page <n>] [--size <n>] [--grouped]`  | List insights (flat or grouped by article).                    |
+| `mxs ai insights get <recordId>`                              | Get one insights record by record id.                          |
+| `mxs ai insights by-article <id> [--lang <l>] [--only-db]`    | Show an article's insights; `--only-db` skips auto-generation. |
+| `mxs ai insights edit <recordId>`                             | Edit the `content` field via `$EDITOR` (JSON envelope).        |
+| `mxs ai insights delete <recordId> [--force]`                 | Delete an insights record.                                     |
+
+## Exit codes specific to `ai`
+
+| Code   | When                                                                                     |
+| ------ | ---------------------------------------------------------------------------------------- |
+| `0`    | Task reached `succeeded`/`completed`; or `--no-wait`; or read/edit/delete completed.     |
+| `1`    | `AiTaskCreateFailed` (no `taskId` in response) or `AiTaskFailed` (terminal `failed`/`cancelled`/`partial_failed`). |
+| `7`    | `AiRecordNotFound` (`get`/`edit`/`delete` against a missing record).                     |
+
+Network / auth / validation errors map per the global table — see `safety`.
+
+## Examples
+
+```bash
+# Regenerate an article's summary and wait for it
+mxs ai summary regen my-post --to en --to ja
+
+# Translate to Japanese, fire and forget
+mxs ai translate run my-post --to ja --no-wait
+
+# Refresh insights, then read the result
+mxs ai insights refresh my-post
+mxs ai insights by-article my-post --only-db
+
+# Inventory
+mxs ai summary list --grouped --output json | jq .
+mxs ai translate languages my-post
+
+# Patch a translation record through $EDITOR
+mxs ai translate edit 01HXXX...
+```
+
+## Notes for agents
+
+- Always pass `--output json` (or `--json`) for machine-parseable output. The default `readable` mode is for humans.
+- `created: false` is a normal join-existing path, NOT an error. Do not retry on it.
+- The polling loop has no hard timeout. For very long translation runs across many languages, prefer `--no-wait` plus periodic `mxs ai translate by-article` polls.
+- Edit envelopes are typed per resource. Unknown keys are rejected client-side before any PATCH is sent.

package/skills/commands-preview.md

@@ -7,7 +7,7 @@ order: 41
 
 # 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.
+`mxs preview` renders a LiteXML fragment or `<mxpost>` / `<mxnote>` envelope to HTML and (by default) opens it in the system browser. It uses the LiteXML preview renderer vendored into the published CLI bundle, so the output matches what the editor would render once published without requiring runtime package dependencies.
 
 | Command                                  | Behavior                                                                    |
 | ---------------------------------------- | --------------------------------------------------------------------------- |
@@ -56,7 +56,7 @@ mxs preview ./post.xml --print > preview.html
 
 | 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.                              |
+| `cannot resolve LiteXML preview renderer`               | Published package is incomplete; reinstall `@mx-space/cli` or rebuild the CLI package.          |
+| `Cannot resolve @haklex/rich-compose asset "style.css"`  | Vendored preview assets are missing; reinstall `@mx-space/cli` or rebuild the CLI package.      |
 | `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

@@ -25,6 +25,7 @@ The audience is **AI agents**. Pass `--output llm` for raw markdown suitable for
 | Categories                                    | `commands-category`              |
 | Topics                                        | `commands-topic`                 |
 | Snippets (server data / functions)            | `commands-snippet`               |
+| AI summary / translation / insights / entries | `commands-ai`                    |
 | Server-side options                           | `commands-config`                |
 | Authentication                                | `commands-auth`                  |
 | Local profile management                      | `commands-profile`               |