@chalksurf/cli 0.3.3 → 0.3.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/README.md +5 -4
  2. package/dist/bin/chalksurf.js +410 -274
  3. package/docs/agents.md +12 -20
  4. package/docs/manual.md +23 -4
  5. package/docs/mcp.md +22 -10
  6. package/package.json +1 -1
package/docs/agents.md CHANGED
@@ -81,6 +81,7 @@ Use these commands after authentication and organization selection:
81
81
 
82
82
  | Goal | CLI command |
83
83
  | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
84
+ | List organization-owned sheets | `chalksurf sheet list --limit 100 --json` |
84
85
  | Fetch one sheet | `chalksurf sheet get SHEET_ID --json` |
85
86
  | List owned sheet versions | `chalksurf sheet versions SHEET_ID --json` |
86
87
  | Fetch one owned sheet version | `chalksurf sheet version SHEET_ID VERSION_ID --json` |
@@ -90,8 +91,8 @@ Use these commands after authentication and organization selection:
90
91
  | Create an editable variant sheet | `chalksurf sheet copy SHEET_ID "Variant name" --exercise-copy-mode copy_all_exercises --json` |
91
92
  | Append existing exercises to a sheet | `chalksurf sheet append SHEET_ID EXERCISE_ID... --json` |
92
93
  | Patch sheet metadata | `chalksurf sheet update SHEET_ID --expected-updated-at ISO --patch-json JSON --json` |
93
- | List valid sheet-series paths | `chalksurf sheet series list --json` |
94
- | Validate/apply bulk sheet patches | `chalksurf sheet bulk-update --input-json JSON --json` |
94
+ | List valid sheet-series paths | `chalksurf sheet series list --subject math --json` |
95
+ | Validate/apply bulk sheet patches | `chalksurf sheet bulk-update --input batch.json --json` |
95
96
  | Set sheet visibility | `chalksurf sheet set-visibility SHEET_ID --public --expected-updated-at ISO --confirm-make-public-resource-id SHEET_ID --json` |
96
97
  | Delete a sheet | `chalksurf sheet delete SHEET_ID --expected-updated-at ISO --confirm-resource-id SHEET_ID --json` |
97
98
  | List folders | `chalksurf sheet folder list --json` |
@@ -103,8 +104,7 @@ Use these commands after authentication and organization selection:
103
104
  | Inspect exercise usage | `chalksurf exercise usage EXERCISE_ID --json` |
104
105
  | Inspect figure building blocks | `chalksurf figure capabilities --json` |
105
106
  | Render a draft figure | `chalksurf figure render-draft --input-json JSON --output figure.png --json` |
106
- | Upload a figure image | `chalksurf exercise figure upload ./figure.png --figure-type text --json` |
107
- | Attach figures to an exercise | `chalksurf exercise figure attach EXERCISE_ID --expected-updated-at ISO --figure-json JSON --json` |
107
+ | Upload and attach a figure image | `chalksurf exercise figure upload EXERCISE_ID ./figure.png --figure-type text --json` |
108
108
  | Create an exercise | `chalksurf exercise create --input-json JSON --json` |
109
109
  | Copy one exercise | `chalksurf exercise copy EXERCISE_ID --json` |
110
110
  | Patch exercise fields | `chalksurf exercise update EXERCISE_ID --expected-updated-at ISO --patch-json JSON --json` |
@@ -118,6 +118,8 @@ Pass `folderId` in the `sheet create --input-json` payload to place a new sheet
118
118
 
119
119
  When appending private exercises to a public sheet, the CLI requires `--confirm-make-exercises-public` because the append makes those exercises public.
120
120
 
121
+ For reviewed bulk sheet updates, prefer `--input batch.json` or pipe the same object through `--input -`. Keep `--input-json` for short inline payloads. Submit the unchanged update list in dry-run and apply modes, copy the returned `confirmationDigest` into the apply object, and preserve both outputs and the apply receipt.
122
+
121
123
  For `--private`, visibility commands do not require `--confirm-make-public-resource-id`. If visibility controls are disabled for the selected organization/user, the CLI and MCP return `feature_disabled`.
122
124
 
123
125
  For deletes, fetch the resource immediately before deleting, use that `updated_at` as `--expected-updated-at`, and pass the target ID again as `--confirm-resource-id`. Exercise deletes fail while the exercise is used by any active sheet. Folder deletes fail unless the folder has no child folders and no active child sheets.
@@ -171,26 +173,14 @@ chalksurf --profile prod-codex figure render-draft \
171
173
  --json
172
174
  ```
173
175
 
174
- 3. Upload the reviewed image:
176
+ 3. Upload and attach the reviewed image to its exercise:
175
177
 
176
178
  ```bash
177
- chalksurf --profile prod-codex exercise figure upload figure.png \
179
+ chalksurf --profile prod-codex exercise figure upload EXERCISE_ID figure.png \
178
180
  --figure-type text \
179
181
  --json
180
182
  ```
181
183
 
182
- 4. Fetch the exercise, then attach the returned `result.figure` with the latest `updated_at`:
183
-
184
- ```bash
185
- chalksurf --profile prod-codex exercise get EXERCISE_ID --json
186
- chalksurf --profile prod-codex exercise figure attach EXERCISE_ID \
187
- --expected-updated-at 2026-01-01T00:00:00.000Z \
188
- --figure-json '{"type":"text","url":"https://...","widthInCm":6}' \
189
- --json
190
- ```
191
-
192
- Use `--mode replace_type --figure-type text` to replace only exercise-text figures, or `--mode replace_all` to replace the full figure list. Attach uses the same shared-exercise acknowledgement rules as `exercise update`.
193
-
194
184
  ## Variant Workflow: Create A Slightly Easier Sheet
195
185
 
196
186
  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.
@@ -220,7 +210,6 @@ MCP clients should use tool discovery from the client. The ChalkSurf MCP endpoin
220
210
  | `figure capabilities` | `figure_get_capabilities` |
221
211
  | `figure render-draft` | `figure_render_draft` |
222
212
  | `exercise figure upload` | `upload_exercise_figure` |
223
- | `exercise figure attach` | `attach_exercise_figures` |
224
213
  | `exercise create` | `create_exercise` |
225
214
  | `exercise copy` | `copy_exercise` |
226
215
  | `exercise update` | `update_exercise` |
@@ -230,6 +219,7 @@ MCP clients should use tool discovery from the client. The ChalkSurf MCP endpoin
230
219
  | `exercise validate-latex` | `validate_latex_snippets` |
231
220
  | `exercise import` | `import_exercise` |
232
221
  | `exercise import-solution` | `import_exercise_solution` |
222
+ | `sheet list` | `list_sheets` |
233
223
  | `sheet search` | `search_sheets` |
234
224
  | `sheet get` | `get_sheet` |
235
225
  | `sheet versions` | `list_sheet_versions` |
@@ -256,7 +246,9 @@ MCP clients should use tool discovery from the client. The ChalkSurf MCP endpoin
256
246
  | `feedback user` | `send_user_feedback` |
257
247
  | `feedback agent` | `send_agent_feedback` |
258
248
 
259
- 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`.
249
+ `sheet bulk-update` file/stdin handling is a CLI transport convenience. MCP clients pass the same strict object directly to `bulk_update_sheets`; the dry-run, confirmation-digest, batch limit, and atomic-apply contract is identical.
250
+
251
+ MCP calls authenticate through ChalkSurf OAuth, not CLI tokens. Tools advertise `chalksurf:read` or `chalksurf:write` during authorization, while the editable MCP grant's current per-organization permission is the authoritative runtime read/write boundary. For normal execution, each organization-scoped MCP call must pass a full `organizationId` from `get_auth_status` or `list_organizations`. If it is unknown, pass `organizationId: null`; no operation runs, and the response returns the complete current organization catalog for retry. `organization_selection_required` means a UUID must be selected, while `organization_access_denied` means the supplied UUID is not currently usable. Grant and membership edits take effect on the next HTTP request without reloading tools or issuing a new access token. Never infer the organization from a resource ID. Organization-independent tools omit the field, though `list_exercise_labels`, `list_sheet_series`, and `validate_latex_snippets` temporarily ignore an optional legacy UUID from cached tool definitions. ChalkSurf serves modern MCP `2026-07-28` and stateless legacy `2025-11-25` on the same endpoint.
260
252
 
261
253
  ## Feedback
262
254
 
package/docs/manual.md CHANGED
@@ -175,12 +175,31 @@ Add `--wait` to either translate command to wait for the queued translation job
175
175
 
176
176
  Search commands default to `--ownership own`, which means resources in the selected organization.
177
177
 
178
+ List every sheet owned by the selected organization, including folder paths and current series assignments:
179
+
180
+ ```bash
181
+ chalksurf sheet list --limit 100 --json
182
+ chalksurf sheet list --folder-id FOLDER_ID --include-descendants --json
183
+ ```
184
+
185
+ `sheet list` is for folder-hierarchy inventory. Use `sheet search` for text, subject, ownership, readiness, series, or edition-year predicates.
186
+
178
187
  Find exercise sheets by title:
179
188
 
180
189
  ```bash
181
190
  chalksurf sheet search --text "OKTV 2014"
182
191
  ```
183
192
 
193
+ Find sheets from one series and edition-year range:
194
+
195
+ ```bash
196
+ chalksurf sheet search \
197
+ --series-path hungary.oktv.mathematics \
198
+ --from-year 1980 \
199
+ --to-year 1990 \
200
+ --json
201
+ ```
202
+
184
203
  Find exercises by text:
185
204
 
186
205
  ```bash
@@ -237,12 +256,12 @@ Write commands return a receipt with the affected resource, changed paths, warni
237
256
  Admin-only sheet-series labeling supports a two-step bulk flow:
238
257
 
239
258
  ```bash
240
- chalksurf sheet series list --json
241
- chalksurf sheet bulk-update --input-json '{"mode":"dry_run","updates":[...]}' --json
242
- chalksurf sheet bulk-update --input-json '{"mode":"apply","updates":[...],"confirmationDigest":"..."}' --json
259
+ chalksurf sheet series list --subject math --json
260
+ chalksurf sheet bulk-update --input batch-001.dry-run.json --json
261
+ chalksurf sheet bulk-update --input batch-001.apply.json --json
243
262
  ```
244
263
 
245
- The exact same update list must be submitted in both calls. A batch contains at most 100 sheets, applies atomically, and cannot update sheets outside the selected organization.
264
+ Use `--input -` to read the object from stdin, or `--input-json` for short inline JSON. Exactly one input option is required. The exact same update list must be submitted in both calls; only change `mode` and add the returned `confirmationDigest`. A batch contains at most 100 sheets, applies atomically, and cannot update sheets outside the selected organization.
246
265
 
247
266
  Manage folders:
248
267
 
package/docs/mcp.md CHANGED
@@ -5,11 +5,23 @@ ChalkSurf exposes a remote MCP endpoint for agent workflows that need the same c
5
5
  ## Endpoint And Auth
6
6
 
7
7
  - Endpoint: `/mcp` on the ChalkSurf API host.
8
+ - Protocols: modern `2026-07-28` and stateless legacy `2025-11-25` are both supported on the same endpoint.
8
9
  - Authentication: OAuth access tokens issued through the ChalkSurf MCP authorization flow.
9
10
  - CLI tokens and browser session tokens are rejected on `/mcp`.
10
- - Read tools require the `chalksurf:read` scope.
11
- - Write tools require the `chalksurf:write` scope and a write grant for the requested organization.
12
- - Organization-scoped tools require an explicit `organizationId` argument.
11
+ - Tools advertise `chalksurf:read` or `chalksurf:write` during OAuth authorization. The editable MCP grant's current
12
+ per-organization permission is the authoritative runtime read/write boundary, so changing the grant does not require
13
+ issuing a new access token.
14
+ - Organization-scoped tools require an explicit `organizationId` argument for normal execution.
15
+
16
+ Pass the full organization UUID returned by `get_auth_status` or `list_organizations`. If the organization is unknown,
17
+ pass `organizationId: null`; the tool performs no operation and returns `organization_selection_required` with the
18
+ complete current organization catalog. A supplied UUID that is no longer usable returns `organization_access_denied`
19
+ with the same catalog. Retry the same tool with the selected UUID. Grant and membership changes are loaded on the next
20
+ HTTP request, so clients do not need to reload tool definitions. Never infer an organization from a resource ID.
21
+
22
+ `get_auth_status`, `list_organizations`, `list_exercise_labels`, `list_sheet_series`, `validate_latex_snippets`, and the
23
+ figure capability/rendering tools are organization-independent. The three newly global tools temporarily accept and
24
+ ignore an optional UUID from cached legacy tool definitions.
13
25
 
14
26
  MCP clients should use their built-in tool listing/search. ChalkSurf does not expose a second search abstraction just to rediscover tools.
15
27
 
@@ -63,16 +75,15 @@ Use `error.agentErrorDetails.results[].patchPath` and `validation.issues[]` to r
63
75
 
64
76
  | Tool | Permission | Purpose |
65
77
  | ----------------------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------- |
66
- | `get_auth_status` | read | Confirm the authenticated ChalkSurf user and selected organization. |
67
- | `list_organizations` | read | List organizations granted to the MCP client. |
78
+ | `get_auth_status` | read | Confirm the authenticated user and return the complete current organization catalog. |
79
+ | `list_organizations` | read | Return the complete current organizations usable through the MCP grant and membership. |
68
80
  | `search_exercises` | read | Search exercises by text, labels, status, ownership, age, difficulty, or semantic query. |
69
81
  | `get_exercise` | read | Fetch full details for one visible exercise. |
70
82
  | `list_exercise_labels` | read | List the canonical exercise label taxonomy agents may write to exercises. |
71
83
  | `get_exercise_usage` | read | Inspect which sheets use one visible exercise. |
72
84
  | `figure_get_capabilities` | read | Inspect supported semantic 2D figure objects, construction definitions, assertions, limits, and snippets. |
73
85
  | `figure_render_draft` | read | Render a semantic figure draft to SVG/PNG metadata, PNG image content, diagnostics, assertions, and review hints. |
74
- | `upload_exercise_figure` | write | Upload one reviewed image from a ChatGPT file parameter, HTTPS image, base64 image, or rendered figure into exercise-image storage. |
75
- | `attach_exercise_figures` | write | Append, replace one figure type, or replace all figures on one writable exercise with an `updated_at` precondition. |
86
+ | `upload_exercise_figure` | write | Upload and attach one reviewed image from a ChatGPT file parameter, HTTPS image, base64 image, or rendered figure to an exercise. |
76
87
  | `create_exercise` | write | Create one exercise in the selected organization. |
77
88
  | `copy_exercise` | write | Copy one visible exercise into the selected organization. |
78
89
  | `delete_exercise` | write | Soft-delete one unused writable exercise after `updated_at` and exact-ID confirmation checks. |
@@ -81,7 +92,8 @@ Use `error.agentErrorDetails.results[].patchPath` and `validation.issues[]` to r
81
92
  | `generate_exercise_translation_job` | write | Queue translation generation for one writable exercise. |
82
93
  | `import_exercise` | write | Queue an exercise import from ChatGPT file parameters or HTTPS URLs. |
83
94
  | `import_exercise_solution` | write | Queue a solution import for one exercise. |
84
- | `search_sheets` | read | Search visible sheets, optionally by readiness issues. |
95
+ | `search_sheets` | read | Search visible sheets by text, subject, ownership, readiness, series, or edition year. |
96
+ | `list_sheets` | read | List sheets owned by the selected organization, including folder paths and current series assignments. |
85
97
  | `get_sheet` | read | Fetch full details for one visible sheet. |
86
98
  | `list_sheet_series` | read | List the authoritative sheet-series hierarchy and valid assignment paths. |
87
99
  | `list_sheet_versions` | read | List version history for one sheet owned by the granted organization. |
@@ -110,13 +122,13 @@ Use `error.agentErrorDetails.results[].patchPath` and `validation.issues[]` to r
110
122
 
111
123
  For `create_sheet`, pass `folderId` to create the sheet in a target folder. Omit it or pass `null` to create the sheet at the organization root.
112
124
 
113
- Sheet-series writes are currently restricted to admin users and sheets owned by the selected organization. Use `list_sheet_series`, then call `bulk_update_sheets` with `mode: "dry_run"`. Apply the unchanged batch with the returned `confirmationDigest`; no idempotency key or separate idempotency table is used.
125
+ Sheet-series writes are currently restricted to admin users and sheets owned by the selected organization. Use `list_sheet_series`, then call `bulk_update_sheets` with `mode: "dry_run"`. Apply the unchanged batch with the returned `confirmationDigest`; no idempotency key or separate idempotency table is used. CLI `--input` and stdin support are transport conveniences only: MCP clients pass the same strict bulk object directly.
114
126
 
115
127
  Delete tools require exact `confirmResourceId` matching the target ID. Exercise and sheet deletes also require the latest `expectedUpdatedAt`. Exercise deletes fail while the exercise is used by an active sheet, and folder deletes fail unless the folder is empty.
116
128
 
117
129
  Visibility tools respect the existing ChalkSurf visibility feature flag. If visibility controls are disabled, they return `feature_disabled`. Publicization requires `confirmMakePublicResourceId`; private visibility changes do not.
118
130
 
119
- Figure tools are available for agents to create and attach figures to exercises. The recommended flow is `figure_get_capabilities`, then one or more `figure_render_draft` calls with visual review, then `upload_exercise_figure`, then `attach_exercise_figures` using a fresh `get_exercise.updated_at` value. Figure drafts support semantic 2D constructions such as midpoints, projections, selected intersections, triangle centers, parallel/perpendicular lines, angle bisectors, incircles, diameter circles, and tangent circles; use assertions such as `angleBisected`, `tangent`, `pointOnSegment`, and `concurrent` to verify the intended relationships before upload.
131
+ Figure tools are available for agents to create and attach figures to exercises. The recommended flow is `figure_get_capabilities`, then one or more `figure_render_draft` calls with visual review, then `upload_exercise_figure` with the target `exerciseId`. Upload and attachment are one operation. Figure drafts support semantic 2D constructions such as midpoints, projections, selected intersections, triangle centers, parallel/perpendicular lines, angle bisectors, incircles, diameter circles, and tangent circles; use assertions such as `angleBisected`, `tangent`, `pointOnSegment`, and `concurrent` to verify the intended relationships before upload.
120
132
 
121
133
  ### File Parameters
122
134
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@chalksurf/cli",
3
- "version": "0.3.3",
3
+ "version": "0.3.4",
4
4
  "private": false,
5
5
  "type": "module",
6
6
  "engines": {