@mx-space/cli 0.14.2 → 0.15.0

package/LICENSE

@@ -0,0 +1,33 @@
+** Mix Space Open Source License**
+
+This project is dual-licensed under different terms for different parts of the project. It is important for users and contributors to understand the licensing terms applicable to each part of the project.
+
+### For the `apps/` Directory
+
+**License:** GNU Affero General Public License v3.0 (AGPLv3) with Additional Terms (ADDITIONAL_TERMS).
+
+**Scope:** This license applies exclusively to all files within the `apps/` directory of this project.
+
+**Summary:**
+- The AGPLv3 is a free, copyleft license suitable for software that will be distributed over a network. It allows users to use, modify, and distribute the software and any modifications under the same terms.
+- The "Additional Terms" (ADDITIONAL_TERMS) are specific conditions that are added to the AGPLv3 license. These terms must be reviewed in the accompanying LICENSE file or documentation to understand any additional restrictions or permissions that apply to the software.
+
+### For Other Parts of the Project
+
+**License:** MIT License.
+
+**Scope:** This license applies to all parts of the project that are not included within the `apps/` directory.
+
+**Summary:**
+- The MIT License is a permissive open-source license that allows users considerable freedom. It permits use, copying, modification, merging, publishing, distribution, sublicensing, and/or selling copies of the software.
+- It also protects the authors by including a limitation of liability and a disclaimer of warranty.
+
+**General Conditions:**
+- Redistribution and use in source and binary forms, with or without modification, are permitted provided that the above license notices and this permission notice appear in all copies of the software.
+- The software is provided "as is", without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose, and noninfringement.
+
+**Contribution:**
+- Contributions to this project are accepted under the terms of the same license as the part of the project to which the contribution is made.
+
+**Notice:**
+- This summary is not the license itself and is not a substitute for reading the licenses in their entirety. All users and contributors are encouraged to read the full text of the licenses for a comprehensive understanding.

package/README.md

@@ -471,16 +471,17 @@ Use when authoring or reviewing any Postgres migration in this codebase.
 
 ## AI
 
-Manage AI artifacts (summary, translation, insights) produced by the core AI module. Article references accept Snowflake id, post slug, or note nid — the CLI resolves to an article id via post-then-note lookup. Record references (`<recordId>`) are raw Snowflakes.
+Manage AI artifacts (summary, translation, insights, tts, overview) produced by the core AI module. Article references accept Snowflake id, post slug, or note nid — the CLI resolves to an article id via post-then-note lookup. Record references (`<recordId>`) are raw Snowflakes.
 
-Generate verbs (`summary regen`, `translate run`, `insights refresh`) enqueue a task on the server, then poll `GET /tasks/:id` until the task reaches a terminal status (`completed`, `partial_failed`, `failed`, `cancelled`). Progress lines write to stderr. Pass `--no-wait` to return immediately with `status: pending` after the task is created. If the server reports `created: false`, an in-flight deduplicated task already exists and the CLI joins it instead of erroring. The polling cadence is 1000 ms by default; override via `MXS_AI_POLL_MS=<n>` for tests.
+Generate verbs (`summary regen`, `summary translate`, `translate run`, `insights refresh`, `insights translate`, `tts run`) enqueue a task on the server, then poll `GET /tasks/:id` until the task reaches a terminal status (`completed`, `partial_failed`, `failed`, `cancelled`). Progress lines write to stderr. Pass `--no-wait` to return immediately with `status: pending` after the task is created. If the server reports `created: false`, an in-flight deduplicated task already exists and the CLI joins it instead of erroring. Pass `--force` to regenerate even when an up-to-date result exists (without it the server skips languages that are already current). Target-language lists are capped at 8 per task server-side. The polling cadence is 1000 ms by default; override via `MXS_AI_POLL_MS=<n>` for tests.
 
 ### Summary
 
 | Command                                            | Description                                                       |
 | -------------------------------------------------- | ----------------------------------------------------------------- |
-| `mxs ai summary regen <id> [--to <lang>...]`       | Regenerate an article's summary (optionally for given languages). |
-| `mxs ai summary list [--page <n>] [--size <n>] [--grouped]` | List summaries (flat or grouped by article).             |
+| `mxs ai summary regen <id> [--to <lang>...] [--force]` | Regenerate an article's summary (optionally for given languages). |
+| `mxs ai summary translate <id> --to <lang> [--force]` | Translate the existing base summary into one language (fails with a hint when no base summary exists). |
+| `mxs ai summary list [--page <n>] [--size <n>] [--grouped] [--search <q>]` | 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-generate. |
 | `mxs ai summary edit <recordId>`                   | Edit the `summary` field via `$EDITOR` (JSON envelope).           |
@@ -490,8 +491,8 @@ Generate verbs (`summary regen`, `translate run`, `insights refresh`) enqueue a
 
 | Command                                                  | Description                                                   |
 | -------------------------------------------------------- | ------------------------------------------------------------- |
-| `mxs ai translate run <id> --to <lang>... [--no-wait]`   | Translate an article into one or more languages (`--to` required, repeatable). |
-| `mxs ai translate list [--page <n>] [--size <n>]`        | List translations (always grouped by article — no flat list server-side). |
+| `mxs ai translate run <id> --to <lang>... [--force] [--no-wait]` | Translate an article into one or more languages (`--to` required, repeatable). |
+| `mxs ai translate list [--page <n>] [--size <n>] [--search <q>]` | List translations (always grouped by article — no flat list server-side). |
 | `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.           |
@@ -513,18 +514,41 @@ The i18n dictionary entries layer used by category / topic / note metadata. `--k
 
 | Command                                                | Description                                                         |
 | ------------------------------------------------------ | ------------------------------------------------------------------- |
-| `mxs ai insights refresh <id> [--no-wait]`             | Refresh AI insights for an article.                                 |
-| `mxs ai insights list [--page <n>] [--size <n>] [--grouped]` | List insights (flat or grouped by article).                   |
+| `mxs ai insights refresh <id> [--to <lang>...] [--force] [--no-wait]` | Refresh AI insights for an article; `--to` also translates the result once generated. |
+| `mxs ai insights translate <id> --to <lang> [--force]` | Translate the existing base insights into one language (fails with a hint when no base insights exist). |
+| `mxs ai insights list [--page <n>] [--size <n>] [--grouped] [--search <q>]` | 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-generate.    |
 | `mxs ai insights edit <recordId>`                      | Edit the `content` field via `$EDITOR` (JSON envelope).             |
 | `mxs ai insights delete <recordId> [--force]`          | Delete an insights record.                                          |
 
+### TTS (narrations)
+
+| Command                                                | Description                                                         |
+| ------------------------------------------------------ | ------------------------------------------------------------------- |
+| `mxs ai tts run <id> [--to <lang>...] [--force] [--no-wait]` | Generate AI narration for an article (per language).          |
+| `mxs ai tts list [--page <n>] [--size <n>] [--grouped] [--search <q>]` | List narrations (flat or grouped by article).       |
+| `mxs ai tts by-article <id>`                           | Show all narration rows for an article.                             |
+| `mxs ai tts voices --provider <id> --model <m>`        | Discover TTS voices for a provider/model pair (both required).      |
+| `mxs ai tts delete <recordId> [--force]`               | Delete a narration record.                                          |
+
+### Overview
+
+Read-only board aggregating each article's AI artifact state (summary / translation / insights coverage).
+
+| Command                                                | Description                                                         |
+| ------------------------------------------------------ | ------------------------------------------------------------------- |
+| `mxs ai overview list [--page <n>] [--size <n>] [--search <q>] [--type post\|note\|page]` | List the per-article AI overview board. |
+| `mxs ai overview by-article <id>`                      | Show the AI artifact overview for one article.                      |
+
 ```bash
-mxs ai summary regen my-post --to en --to ja
+mxs ai summary regen my-post --to en --to ja --force
+mxs ai summary translate my-post --to ja
 mxs ai translate run my-post --to en
-mxs ai insights refresh my-post
-mxs ai summary list --grouped
+mxs ai insights refresh my-post --to en
+mxs ai tts run my-post --to zh
+mxs ai summary list --grouped --search hello
+mxs ai overview list --type post
 mxs ai translate languages my-post
 ```