@chalksurf/cli 0.3.6 → 0.4.0

package/docs/migration-0.4.md

@@ -0,0 +1,79 @@
+# Migrating to CLI 0.4.0
+
+Version 0.4.0 groups content operations by resource, component and action. Removed names are rejected; they are not aliases. The release also changes content input and output formats. Source order and domain authorization remain enforced; update scripts and saved artifacts before using the new version.
+
+| Previous command | Replacement |
+| --- | --- |
+| `exercise import-solution` | `exercise solution import` |
+| `sheet import-solutions` | `sheet solution import` |
+| `exercise translate` | `exercise translation generate` |
+| `sheet generate-translation` | `sheet translation generate` |
+| `sheet import-translation` | `sheet translation import` |
+| `exercise versions` | `exercise version list` |
+| `exercise version` | `exercise version get` |
+| `exercise sources` | `exercise source list` |
+| `exercise source` | `exercise source get` |
+| `exercise labels` | `exercise label list` |
+| `exercise validate-latex` | `exercise latex validate` |
+| `exercise set-visibility` | `exercise visibility set` |
+| `sheet versions` | `sheet version list` |
+| `sheet version` | `sheet version get` |
+| `sheet set-visibility` | `sheet visibility set` |
+| `sheet append` | `sheet exercise append` |
+
+The JSON envelope's `command` field uses the replacement path. Update scripts that inspect that field as well as the command invocation. Use `--help` on the complete path to inspect its arguments, for example `chalksurf exercise solution import --help`.
+
+
+## Inputs and repeated operations
+
+Use `--input FILE|-` for a single structured request or patch and `--manifest FILE|-` for repeated requests. The affected content/update commands no longer accept `--input-json` or `--patch-json`. There is no bulk mode: repeat explicit IDs where supported, use `--sheet-id` for exercise generation, or provide one versioned manifest. Do not combine target/operation flags with a manifest.
+
+```json
+{
+  "schemaVersion": "v1",
+  "operation": "sheet.import",
+  "items": [{
+    "itemId": "round-1",
+    "title": "Round 1",
+    "targetLanguages": ["english"],
+    "sources": [{"kind": "local", "path": "paper.pdf", "sourceId": "official-paper"}]
+  }]
+}
+```
+
+Old top-level `sheets`, `sources`, `organizationId` and `wait` manifest fields are rejected. Choose organization through the CLI/profile and wait through `--wait`. Use `targetLanguages` in applicable manifest items and repeatable `--target-language` in direct commands; `translateTo` and `--translate-to` are removed. Authoritative sheet translation import takes exactly one target language. Role-bearing legacy source objects are no longer accepted.
+
+File paths now resolve relative to the input file, not the invocation directory. Stdin paths resolve relative to the invocation directory. JSON input/plan files are bounded to 16 MiB. Known expansion is limited to 100 mutation targets and 20 logical sheet-import groups; no truncation or automatic splitting occurs. Local import dry runs hash readable bytes; remote URLs remain unfetched and extraction counts stay unknown.
+
+## Plans replace bulk-update
+
+`sheet bulk-update`, `sheet bulk-update apply` and `sheet bulk-update verify` are removed:
+
+```sh
+chalksurf --profile prod-codex sheet update --manifest patches.json --dry-run --plan-out plan.json --json
+chalksurf --profile prod-codex plan show plan.json --json
+chalksurf --profile prod-codex plan apply plan.json --result-file applied.json --json
+chalksurf --profile prod-codex plan verify plan.json --json
+```
+
+An update manifest uses `schemaVersion`, `operation: "sheet.update"` (or `exercise.update`) and `items` containing `itemId`, `id`, `expectedUpdatedAt` and `patch`, plus applicable preconditions. Only updates and solution/description generation have executable plans. Translations and imports have read-only previews. `--plan-out` requires `--dry-run`; `plan apply` accepts no target, request-ID or policy overrides. Old dry-run result envelopes are not executable plans: regenerate from the original input.
+
+Sheet batch application remains atomic. Exercise entries are best effort after full initial revalidation. Reviewed blocked entries remain visible and cause nonzero status. A single safe operation generally needs no saved plan; repeated updates and generation that replaces existing content require review. Use `--replace-existing` for solutions and explicit shared-use acknowledgement when applicable.
+
+## Results, jobs and recovery
+
+Content results now contain operation/phase/request identity, `items[]` and `summary` (`total`, `successful`, `unsuccessful`, `unfinished`). Receipts and jobs belong to each item; waited snapshots and linked work appear under `observation`. Queued work is unfinished, not completed. Unrelated commands retain their previous result shapes.
+
+The outer JSON envelope remains v1. `--result-file` contains that complete envelope; stdout may contain a compact artifact path. Keep the full fallback if publication fails after execution: its original exit code remains authoritative.
+
+Before a write, the CLI privately persists attempt evidence under `operations/` beside its configuration, or at `--request-file`. Preserve the request ID and original input; signed source URL parameters are redacted from evidence. `--request-id` is only for intentional exact resends. The server returns prior accepted work and rejects changed input. The CLI never automatically retries a write.
+
+Use `job list --request-id ID` to inspect both live jobs and durable acceptance, including deleted-job tombstones. For saved plans, `plan verify FILE` reads current update state or recorded generation acceptance. Read failure cannot establish that a write failed. Current `desired` values do not prove authorship.
+
+Use generic `job cancel ID [ID..]` and `job dismiss ID [ID..]`; there is no `sheet translation cancel`. Cancellation stops active work when supported; dismissal only changes notifications. Published language removal is `sheet translation remove ID --target-language LANGUAGE --confirm-resource-id ID` and preserves the last ready language and exercise translations.
+
+Exit 6 means timeout, 7 unsuccessful-only outcomes (including cancelled/not-solved), 8 mixed outcomes, 9 uncertain acceptance and 130 local interruption. Observation failures use 5 and retain known state. Ordinary successful acceptance exits 0 without claiming completion. `job cancel --wait` treats requested cancellation as success. See [all exit codes](./exit-codes.md).
+
+## Server prerequisite
+
+The 0.4.0 content surface requires CLI protocol v1 and authorized guarded writes. If capability checks fail, the CLI stops without falling back to older mutation endpoints. Compatible API and job processors must be deployed before guarded-write activation and CLI publication. This release does not change MCP commands or inputs.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chalksurf/cli",
-  "version": "0.3.6",
+  "version": "0.4.0",
   "private": false,
   "type": "module",
   "engines": {
@@ -30,17 +30,20 @@
     "type-check": "tsgo --noEmit --project ./tsconfig.json --checkers 2",
     "test": "vitest --config ./vitest.config.ts --run --maxWorkers=1",
     "test:watch": "vitest --config ./vitest.config.ts --watch --maxWorkers=1",
-    "smoke-pack": "node --import tsx ./scripts/smoke-pack.ts"
+    "smoke-pack": "node --import tsx ./scripts/smoke-pack.ts",
+    "schemas:generate": "node --import tsx ./scripts/generate-content-schemas.ts",
+    "schemas:check": "node --import tsx ./scripts/generate-content-schemas.ts --check"
   },
   "dependencies": {
     "p-limit": "^6.2.0",
+    "pretty-bytes": "^7.1.3",
     "yargs": "^17.7.2",
     "zod": "^4.1.12"
   },
   "devDependencies": {
     "@types/node": "^24.10.1",
     "@types/yargs": "^17.0.35",
-    "@typescript/native-preview": "^7.0.0-dev.20260527.2",
+    "@typescript/native-preview": "^7.0.0-dev.20260707.2",
     "esbuild": "^0.27.0",
     "tsx": "^4.20.6",
     "typescript": "^6.0.3",