@chalksurf/cli 0.2.2 → 0.2.4

package/docs/agents.md

@@ -30,11 +30,16 @@ Prefer storing the token in the explicit agent profile for repeated Codex/CI run
 
 ## Command Contract
 
-For agent-driven imports, always use:
+For agent-driven workflows, always use:
+
+- `--json` so the response stays machine-readable
+- an explicit `--profile ENV-AGENT_TYPE`
+- an explicit selected organization through the profile, `--organization`, or `CHALKSURF_ORGANIZATION_ID`
+
+For agent-driven imports, also use:
 
 - `--manifest -` or a generated manifest file
 - `--wait` when the next step depends on parsed content being saved
-- `--json` so the response stays machine-readable
 
 Recommended invocation shape:
 
@@ -51,6 +56,121 @@ In `--json` mode:
 Wait-style failures still include a populated `result` payload, so agents can inspect partial outcomes on exit code `6` or `7`.
 When an import requests translations, `--wait` waits for the import job only. Follow-up translation jobs are listed under each completed import job's `translationJobs`.
 
+## Shared CLI/MCP Primitive Contract
+
+The CLI and MCP surface are backed by the same agent resource contracts in `packages/shared/src/agent-tools`. Prefer these primitives over UI-only assumptions or direct database access:
+
+- Read tools return complete resource details or focused repair queues.
+- Write tools return a `receipt` with `resource`, `operation`, `changedPaths`, `precondition`, `warnings`, and `details`.
+- Patch-style writes require `expectedUpdatedAt` from a fresh `get` call.
+- Exercise updates require shared-usage care. Use `exercise usage` first when the exercise might appear outside the target sheet.
+- Validate proposed LaTeX with `exercise validate-latex` before applying content updates.
+- No delete or transfer-between-organization agent primitive is intentionally exposed.
+
+Write receipts are the agent audit log. Preserve them in run notes or user-visible summaries when the user needs to double-check what changed.
+
+## CLI Resource Primitives
+
+Use these commands after authentication and organization selection:
+
+| Goal | CLI command |
+| --- | --- |
+| Fetch one sheet | `chalksurf sheet get SHEET_ID --json` |
+| Get a sheet repair queue | `chalksurf sheet issues SHEET_ID --json` |
+| Copy a sheet | `chalksurf sheet copy SHEET_ID "New name" --exercise-copy-mode keep_references --json` |
+| Create an editable variant sheet | `chalksurf sheet copy SHEET_ID "Variant name" --exercise-copy-mode copy_all_exercises --json` |
+| Append existing exercises to a sheet | `chalksurf sheet append SHEET_ID EXERCISE_ID... --json` |
+| Patch sheet metadata | `chalksurf sheet update SHEET_ID --expected-updated-at ISO --patch-json JSON --json` |
+| List folders | `chalksurf sheet folder list --json` |
+| Create a folder | `chalksurf sheet folder create "Folder name" --parent-id FOLDER_ID --json` |
+| Rename a folder | `chalksurf sheet folder rename FOLDER_ID "New name" --json` |
+| Fetch one exercise | `chalksurf exercise get EXERCISE_ID --json` |
+| Inspect exercise usage | `chalksurf exercise usage EXERCISE_ID --json` |
+| Copy one exercise | `chalksurf exercise copy EXERCISE_ID --json` |
+| Patch exercise fields | `chalksurf exercise update EXERCISE_ID --expected-updated-at ISO --patch-json JSON --json` |
+| Validate LaTeX snippets | `chalksurf exercise validate-latex --snippet "path=value" --json` |
+
+When appending private exercises to a public sheet, the CLI requires `--confirm-make-exercises-public` because the append makes those exercises public.
+
+## Repair Workflow: Fix LaTeX Errors In A Sheet
+
+1. Fetch the sheet and issue queue:
+
+```bash
+chalksurf --profile prod-codex sheet get SHEET_ID --json
+chalksurf --profile prod-codex sheet issues SHEET_ID --json
+```
+
+2. For each `invalid_latex` issue, use `patchPath` to identify the field to edit. The issue also includes the current validation details.
+3. Validate proposed replacements before writing:
+
+```bash
+chalksurf --profile prod-codex exercise validate-latex \
+  --snippet "translations.english.exercise_text=Find $x^2$." \
+  --json
+```
+
+4. Patch the owning exercise or sheet with the `updated_at` value from the latest `get` result:
+
+```bash
+chalksurf --profile prod-codex exercise update EXERCISE_ID \
+  --target-sheet-id SHEET_ID \
+  --expected-updated-at 2026-01-01T00:00:00.000Z \
+  --patch-json '{"translations":{"english":{"exercise_text":"Find $x^2$."}}}' \
+  --json
+```
+
+5. Re-run `sheet issues SHEET_ID --json` until the invalid LaTeX count is zero or the remaining items need human judgment.
+
+Do not pass `--allow-shared-exercise-update` unless the user has acknowledged that the same exercise is used outside the target sheet.
+
+## Variant Workflow: Create A Slightly Easier Sheet
+
+Use `copy_all_exercises` when the target is an editable variant. Shared public exercises often cannot be edited by the selected organization, so keeping references usually blocks variant edits.
+
+```bash
+chalksurf --profile prod-codex sheet copy SHEET_ID "Easier variant" \
+  --exercise-copy-mode copy_all_exercises \
+  --json
+```
+
+The copy receipt includes `details.exerciseIdMap`, with one row per source exercise and the copied exercise ID when a copy was made. Use that mapping to update the copied exercises, then re-run `sheet get` and `sheet issues` against the copied sheet.
+
+Use `keep_references` only when the user wants a new sheet arrangement that still points at the original exercises.
+
+## MCP Parity
+
+MCP clients should use tool discovery from the client. The ChalkSurf MCP endpoint exposes the same resource primitives under snake_case names:
+
+| CLI command | MCP tool |
+| --- | --- |
+| `auth status` | `get_auth_status` |
+| `org list` | `list_organizations` |
+| `exercise search` | `search_exercises` |
+| `exercise get` | `get_exercise` |
+| `exercise usage` | `get_exercise_usage` |
+| `exercise copy` | `copy_exercise` |
+| `exercise update` | `update_exercise` |
+| `exercise validate-latex` | `validate_latex_snippets` |
+| `exercise import` | `import_exercise` |
+| `exercise import-solution` | `import_exercise_solution` |
+| `sheet search` | `search_sheets` |
+| `sheet get` | `get_sheet` |
+| `sheet issues` | `get_sheet_issues` |
+| `sheet copy` | `copy_sheet` |
+| `sheet append` | `append_exercises_to_sheet` |
+| `sheet update` | `update_sheet` |
+| `sheet import` | `import_sheet` |
+| `sheet import-solutions` | `import_sheet_solutions` |
+| `sheet folder list` | `list_folders` |
+| `sheet folder create` | `create_folder` |
+| `sheet folder rename` | `rename_folder` |
+| `job list` | `list_jobs` |
+| `job get` | `get_job` |
+| `job wait` | `wait_for_jobs` |
+
+MCP calls authenticate through ChalkSurf OAuth, not CLI tokens. Read tools require `chalksurf:read`; write tools require `chalksurf:write` plus a write grant for the requested `organizationId`. Each organization-scoped MCP call must pass `organizationId`.
+
 ## Manifest Design
 
 Prefer manifests over large positional argument lists.
@@ -69,7 +189,7 @@ Use `sourceId` whenever a browsing step or upstream scraper already has a stable
 
 ```json
 {
-  "organizationId": "org_123",
+  "organizationId": "00000000-0000-4000-8000-000000000001",
   "wait": true,
   "sheets": [
     {

package/docs/examples/sheet-import-manifest.json

@@ -28,6 +28,30 @@
           "path": "./practice-sheet.pdf"
         }
       ]
+    },
+    {
+      "sources": [
+        {
+          "sourceId": "combined-archive-file",
+          "kind": "local",
+          "path": "./combined-archive-file.pdf"
+        }
+      ],
+      "components": [
+        {
+          "componentId": "round_2_part_a",
+          "description": "The exercise sheet labeled Round 2, Part A.",
+          "targetFolderPath": "OKTV/2014",
+          "title": "OKTV 2014 Round 2 Part A",
+          "translateTo": ["english"]
+        },
+        {
+          "componentId": "round_2_part_b",
+          "description": "The exercise sheet labeled Round 2, Part B.",
+          "targetFolderPath": "OKTV/2014",
+          "title": "OKTV 2014 Round 2 Part B"
+        }
+      ]
     }
   ]
 }

package/docs/manifest.md

@@ -60,7 +60,7 @@ Top-level fields:
 | --- | --- | --- | --- |
 | `sheets` | array | yes | One or more sheets to import. Each sheet may contain one or more source files. |
 
-Sheet fields:
+Normal sheet fields:
 
 | Field | Type | Required | Notes |
 | --- | --- | --- | --- |
@@ -73,6 +73,27 @@ Sheet import metadata is sheet-level, not source-level. Do not put `title` or `t
 
 Source-level `relativePath` is only a source label or filename override. It does not choose the destination folder for grouped sheet imports; `targetFolderPath` is the only destination field.
 
+Declared-component sheet fields:
+
+Use `components[]` when the same source group contains a known fixed set of component sheets. In this mode, do not put `targetFolderPath`, `title`, or `translateTo` on the sheet itself; put output metadata on each component.
+
+| Field | Type | Required | Notes |
+| --- | --- | --- | --- |
+| `sources` | array | yes | One or more source files that contain the declared components. |
+| `components` | array | yes | The explicitly requested component sheets to extract from the shared source group. |
+
+Component fields:
+
+| Field | Type | Required | Notes |
+| --- | --- | --- | --- |
+| `componentId` | string | yes | Stable key for this requested component. Must match `/^[a-zA-Z0-9_-]{1,80}$/` and be unique within the sheet group. |
+| `description` | string | yes | Matching instructions that identify this component in the source group. |
+| `targetFolderPath` | string \| null | no | Destination folder for this component. Omit or use `null` for the root folder. |
+| `title` | string | no | Overrides the imported component sheet title. |
+| `translateTo` | string[] | no | Target translation languages for this component. Must be unique and non-empty when present. |
+
+The model must return an explicit `import` or `not_present` decision for every declared `componentId`. Jobs complete when at least one component is imported and fail when all declared components are `not_present`.
+
 Canonical example:
 
 - [docs/examples/sheet-import-manifest.json](./examples/sheet-import-manifest.json)
@@ -142,6 +163,8 @@ The CLI validates more than the JSON schema can express on its own:
 
 - `sourceId` values must be unique within one manifest.
 - Sheet import `translateTo` values must be unique within one sheet.
+- Sheet import component `componentId` values must be unique within one sheet group.
+- Sheet import components require non-empty descriptions.
 - Exercise import top-level `translateTo` values must be unique.
 - `relativePath` cannot be empty or contain `..`.
 - Sheet import `targetFolderPath` must be `null` or a normalized folder path without `.` or `..` segments.

package/docs/manual.md

@@ -184,6 +184,48 @@ Search public resources instead:
 chalksurf sheet search --text "OKTV" --ownership public
 ```
 
+## Inspecting And Editing Resources
+
+Fetch full sheet or exercise details:
+
+```bash
+chalksurf sheet get 00000000-0000-4000-8000-000000000001 --json
+chalksurf exercise get 00000000-0000-4000-8000-000000000002 --json
+```
+
+List sheet issues that are useful for repair workflows:
+
+```bash
+chalksurf sheet issues 00000000-0000-4000-8000-000000000001 --json
+```
+
+Copy a sheet for a variant workflow. Use `copy_all_exercises` when you want editable exercise copies:
+
+```bash
+chalksurf sheet copy 00000000-0000-4000-8000-000000000001 "Easier variant" \
+  --exercise-copy-mode copy_all_exercises \
+  --json
+```
+
+Patch an exercise with an optimistic update precondition:
+
+```bash
+chalksurf exercise update 00000000-0000-4000-8000-000000000002 \
+  --expected-updated-at 2026-01-01T00:00:00.000Z \
+  --patch-json '{"translations":{"english":{"exercise_text":"Find $x^2$."}}}' \
+  --json
+```
+
+Write commands return a receipt with the affected resource, changed paths, warnings, and operation-specific details. Fetch the resource first and use its current `updated_at` value for patch commands.
+
+Manage folders:
+
+```bash
+chalksurf sheet folder list --json
+chalksurf sheet folder create "Practice Sets" --json
+chalksurf sheet folder rename 00000000-0000-4000-8000-000000000003 "Variant Sheets" --json
+```
+
 ## Troubleshooting
 
 Missing auth:
@@ -209,5 +251,6 @@ chalksurf job wait job_123 --json
 Further reference:
 
 - [Agent and Codex guide](./agents.md)
+- [MCP guide](./mcp.md)
 - [Manifest reference](./manifest.md)
 - [Exit codes and JSON errors](./exit-codes.md)

package/docs/mcp.md

@@ -0,0 +1,88 @@
+# MCP Guide
+
+ChalkSurf exposes a remote MCP endpoint for agent workflows that need the same capabilities as the CLI without shelling out to `chalksurf`.
+
+## Endpoint And Auth
+
+- Endpoint: `/mcp` on the ChalkSurf API host.
+- Authentication: OAuth access tokens issued through the ChalkSurf MCP authorization flow.
+- CLI tokens and browser session tokens are rejected on `/mcp`.
+- Read tools require the `chalksurf:read` scope.
+- Write tools require the `chalksurf:write` scope and a write grant for the requested organization.
+- Organization-scoped tools require an explicit `organizationId` argument.
+
+MCP clients should use their built-in tool listing/search. ChalkSurf does not expose a second search abstraction just to rediscover tools.
+
+## Shared Contract
+
+The MCP tools and CLI commands are backed by the same agent resource contracts in `packages/shared/src/agent-tools`.
+
+Read tools return structured resource data. Write tools return a structured `receipt`:
+
+- `resource`: the resource type and ID affected by the write
+- `operation`: the stable operation name, such as `update_exercise`
+- `changedPaths`: field paths changed by the operation
+- `precondition`: optimistic update status, including `expectedUpdatedAt` and `actualUpdatedAt`
+- `warnings`: non-fatal conditions the agent should surface
+- `details`: operation-specific audit data, such as exercise copy mappings
+
+Treat write receipts as an agent audit log. They are suitable for user-visible summaries after an agent edits a sheet.
+
+## Tool Surface
+
+| Tool | Permission | Purpose |
+| --- | --- | --- |
+| `get_auth_status` | read | Confirm the authenticated ChalkSurf user and selected organization. |
+| `list_organizations` | read | List organizations granted to the MCP client. |
+| `search_exercises` | read | Search exercises by text, labels, status, ownership, age, difficulty, or semantic query. |
+| `get_exercise` | read | Fetch full details for one visible exercise. |
+| `get_exercise_usage` | read | Inspect which sheets use one visible exercise. |
+| `copy_exercise` | write | Copy one visible exercise into the selected organization. |
+| `update_exercise` | write | Patch exercise fields with an `updated_at` precondition and shared-usage acknowledgement. |
+| `import_exercise` | write | Queue an exercise import from MCP files or HTTPS URLs. |
+| `import_exercise_solution` | write | Queue a solution import for one exercise. |
+| `search_sheets` | read | Search visible sheets, optionally by readiness issues. |
+| `get_sheet` | read | Fetch full details for one visible sheet. |
+| `get_sheet_issues` | read | Fetch actionable sheet issues: invalid LaTeX, missing translations, missing solutions, and missing scores. |
+| `copy_sheet` | write | Copy a visible sheet, either keeping exercise references or copying all visible exercises. |
+| `update_sheet` | write | Patch sheet metadata with an `updated_at` precondition. |
+| `append_exercises_to_sheet` | write | Append existing visible exercises to the end of one writable sheet. |
+| `list_folders` | read | List sheet folders in the selected organization. |
+| `create_folder` | write | Create a sheet folder. |
+| `rename_folder` | write | Rename a sheet folder. |
+| `validate_latex_snippets` | read | Validate proposed LaTeX snippets before writing. |
+| `import_sheet` | write | Queue sheet imports from MCP files or HTTPS URLs. |
+| `import_sheet_solutions` | write | Queue solution import for an existing sheet. |
+| `list_jobs` | read | List jobs in the granted organization. |
+| `get_job` | read | Fetch one job. |
+| `wait_for_jobs` | read | Wait for one or more jobs to complete. |
+
+No MCP tool currently deletes resources or transfers resources between organizations.
+
+## Common Workflows
+
+### Fix LaTeX Errors In A Sheet
+
+1. Call `get_sheet` for current resource details and `updated_at` values.
+2. Call `get_sheet_issues` and filter `issues` to `type: "invalid_latex"`.
+3. Use each issue's `patchPath` to build the smallest exercise or sheet patch.
+4. Call `validate_latex_snippets` with the proposed replacement text.
+5. Call `update_exercise` or `update_sheet` with the latest `expectedUpdatedAt`.
+6. Call `get_sheet_issues` again and stop when the relevant issue count is zero.
+
+For exercise updates, pass `targetSheetId` when the repair belongs to one sheet. Only pass `allowSharedExerciseUpdate: true` after the user acknowledges that the exercise may be used elsewhere.
+
+### Create A Slightly Easier Variant Sheet
+
+1. Call `copy_sheet` with `exerciseCopyMode: "copy_all_exercises"`.
+2. Read `receipt.resource.id` for the copied sheet ID.
+3. Read `receipt.details.exerciseIdMap` to map source exercise IDs to editable copied exercise IDs.
+4. Call `get_sheet` on the copied sheet.
+5. Apply focused `update_exercise` patches to the copied exercises.
+6. Call `get_sheet_issues` before reporting completion.
+
+Use `exerciseCopyMode: "keep_references"` only when the user wants a new sheet that still points at the original exercises.
+
+## CLI Mapping
+
+The closest CLI equivalents are documented in [the agent guide](./agents.md). Use the CLI when a workflow already runs in a shell or CI job; use MCP when the agent host has native MCP support and can complete ChalkSurf OAuth.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chalksurf/cli",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "private": false,
   "type": "module",
   "engines": {
@@ -25,7 +25,7 @@
   "scripts": {
     "dev": "node --import tsx ./src/bin/chalksurf.ts",
     "prepack": "npm run build",
-    "build": "tsc --project ./tsconfig.build.json",
+    "build": "node --import tsx ./scripts/build.ts",
     "lint": "eslint .",
     "type-check": "tsc --noEmit --project ./tsconfig.json",
     "test": "vitest --config ./vitest.config.ts --run --maxWorkers=1",
@@ -40,6 +40,7 @@
   "devDependencies": {
     "@types/node": "^24.10.1",
     "@types/yargs": "^17.0.35",
+    "esbuild": "^0.27.0",
     "tsx": "^4.20.6",
     "typescript": "^5.0.0",
     "vitest": "^4.1.2"

package/schemas/sheet-import-manifest.schema.json

@@ -40,6 +40,37 @@
       "type": "string",
       "enum": ["english", "hungarian", "german", "french", "spanish", "italian"]
     },
+    "componentId": {
+      "type": "string",
+      "pattern": "^[a-zA-Z0-9_-]{1,80}$"
+    },
+    "component": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["componentId", "description"],
+      "properties": {
+        "componentId": {
+          "$ref": "#/$defs/componentId"
+        },
+        "description": {
+          "$ref": "#/$defs/nonEmptyString"
+        },
+        "targetFolderPath": {
+          "$ref": "#/$defs/targetFolderPath"
+        },
+        "title": {
+          "$ref": "#/$defs/nonEmptyString"
+        },
+        "translateTo": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {
+            "$ref": "#/$defs/translateLanguage"
+          }
+        }
+      }
+    },
     "localSource": {
       "type": "object",
       "additionalProperties": false,
@@ -111,32 +142,57 @@
       ]
     },
     "sheet": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": ["targetFolderPath", "sources"],
-      "properties": {
-        "targetFolderPath": {
-          "$ref": "#/$defs/targetFolderPath"
-        },
-        "title": {
-          "$ref": "#/$defs/nonEmptyString"
-        },
-        "translateTo": {
-          "type": "array",
-          "minItems": 1,
-          "uniqueItems": true,
-          "items": {
-            "$ref": "#/$defs/translateLanguage"
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["targetFolderPath", "sources"],
+          "properties": {
+            "targetFolderPath": {
+              "$ref": "#/$defs/targetFolderPath"
+            },
+            "title": {
+              "$ref": "#/$defs/nonEmptyString"
+            },
+            "translateTo": {
+              "type": "array",
+              "minItems": 1,
+              "uniqueItems": true,
+              "items": {
+                "$ref": "#/$defs/translateLanguage"
+              }
+            },
+            "sources": {
+              "type": "array",
+              "minItems": 1,
+              "items": {
+                "$ref": "#/$defs/source"
+              }
+            }
           }
         },
-        "sources": {
-          "type": "array",
-          "minItems": 1,
-          "items": {
-            "$ref": "#/$defs/source"
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["sources", "components"],
+          "properties": {
+            "sources": {
+              "type": "array",
+              "minItems": 1,
+              "items": {
+                "$ref": "#/$defs/source"
+              }
+            },
+            "components": {
+              "type": "array",
+              "minItems": 1,
+              "items": {
+                "$ref": "#/$defs/component"
+              }
+            }
           }
         }
-      }
+      ]
     }
   }
 }