@chalksurf/cli 0.2.3 → 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/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.3",
+  "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/dist/commands/auth.js

@@ -1,174 +0,0 @@
-import { createApiClient } from '../lib/api-client.js';
-import { CliCommandError } from '../lib/cli-error.js';
-import { resolveOrganization } from '../lib/config-store.js';
-import { formatUserIdentity, mapApiErrorToCliError, requireResolvedBaseUrl, requireResolvedToken, } from '../lib/session.js';
-const isInteractiveStdin = (stdin) => {
-    return stdin.isTTY === true;
-};
-const readTokenFromStdin = async (stdin) => {
-    let token = '';
-    for await (const chunk of stdin) {
-        token += typeof chunk === 'string' ? chunk : Buffer.from(chunk).toString('utf8');
-    }
-    return token.trim();
-};
-const serializeOrganization = (organization) => {
-    if (!organization) {
-        return null;
-    }
-    return {
-        id: organization.organizationId,
-        name: organization.organizationName,
-        role: organization.role,
-        type: organization.organizationType,
-    };
-};
-const formatOrganizationSummary = (organization) => {
-    if (!organization) {
-        return 'No default organization selected.';
-    }
-    return `Default organization: ${organization.name} (${organization.id}).`;
-};
-export const registerAuthCommands = (authYargs, context) => {
-    return authYargs
-        .command('login', 'Read a CLI token from stdin or prompt for it interactively', (loginYargs) => {
-        return loginYargs
-            .option('with-token', {
-            type: 'boolean',
-            default: false,
-            describe: 'Read the token from stdin when piping input',
-        })
-            .example('chalksurf auth login --profile prod-cztamas --base-url https://chalksurf-api.fly.dev', 'Prompt for a CLI token and store it in the prod-cztamas profile')
-            .example(`printf '%s' "$CHALKSURF_TOKEN" | chalksurf auth login --profile prod-codex --base-url https://chalksurf-api.fly.dev`, 'Read a CLI token from stdin into an explicit profile');
-    }, async (argv) => {
-        const config = await context.configStore.loadProfile({ profileName: argv.profile });
-        const resolvedBaseUrl = requireResolvedBaseUrl({
-            flagValue: argv.baseUrl,
-            env: context.env,
-            config,
-        });
-        const token = (isInteractiveStdin(context.stdin)
-            ? await context.promptSecret('CLI token: ')
-            : await readTokenFromStdin(context.stdin)).trim();
-        if (!token) {
-            throw new CliCommandError('No token was provided.', 2);
-        }
-        const apiClient = createApiClient({
-            baseUrl: resolvedBaseUrl.value,
-            token,
-        });
-        let profile;
-        try {
-            profile = await apiClient.getUserProfile();
-        }
-        catch (error) {
-            throw mapApiErrorToCliError(error);
-        }
-        const resolvedOrganization = resolveOrganization({
-            flagValue: argv.organization,
-            env: context.env,
-            config,
-            profile,
-        });
-        await context.configStore.update({ profileName: argv.profile }, (currentConfig) => ({
-            ...currentConfig,
-            token,
-            baseUrl: resolvedBaseUrl.value,
-            organizationId: resolvedOrganization.organization?.organizationId,
-        }));
-        resolvedOrganization.warnings.forEach((warning) => {
-            context.output.info(warning);
-        });
-        context.output.print({
-            authenticated: true,
-            baseUrl: resolvedBaseUrl.value,
-            baseUrlSource: resolvedBaseUrl.source,
-            organization: serializeOrganization(resolvedOrganization.organization),
-            profile: config.profileName,
-            profileSource: config.profileSource,
-            user: {
-                email: profile.email,
-                id: profile.id,
-                name: profile.name,
-            },
-        }, (result) => `Logged in as ${formatUserIdentity(result.user)}.\n${formatOrganizationSummary(result.organization)}`, {
-            command: 'auth login',
-        });
-    })
-        .command('status', 'Show the current authentication and organization state', (statusYargs) => statusYargs
-        .example('chalksurf auth status', 'Show the current authenticated user and default organization')
-        .example('chalksurf --profile prod-codex auth status --json', 'Inspect a specific profile in machine-readable mode')
-        .epilogue([
-        'Resolution order:',
-        '  profile: --profile, then CHALKSURF_PROFILE, then stored default profile',
-        '  base URL: --base-url, then CHALKSURF_BASE_URL, then active profile',
-        '  token: CHALKSURF_TOKEN, then active profile',
-        '  organization: --organization, then CHALKSURF_ORGANIZATION_ID, then active profile',
-    ].join('\n')), async (argv) => {
-        const config = await context.configStore.loadProfile({ profileName: argv.profile });
-        const resolvedBaseUrl = requireResolvedBaseUrl({
-            flagValue: argv.baseUrl,
-            env: context.env,
-            config,
-        });
-        const resolvedToken = requireResolvedToken({
-            env: context.env,
-            config,
-        });
-        const apiClient = createApiClient({
-            baseUrl: resolvedBaseUrl.value,
-            token: resolvedToken.value,
-        });
-        let profile;
-        try {
-            profile = await apiClient.getUserProfile();
-        }
-        catch (error) {
-            throw mapApiErrorToCliError(error);
-        }
-        const resolvedOrganization = resolveOrganization({
-            flagValue: argv.organization,
-            env: context.env,
-            config,
-            profile,
-        });
-        resolvedOrganization.warnings.forEach((warning) => {
-            context.output.info(warning);
-        });
-        context.output.print({
-            authenticated: true,
-            baseUrl: resolvedBaseUrl.value,
-            baseUrlSource: resolvedBaseUrl.source,
-            organization: serializeOrganization(resolvedOrganization.organization),
-            organizationSource: resolvedOrganization.source,
-            profile: config.profileName,
-            profileSource: config.profileSource,
-            tokenSource: resolvedToken.source,
-            user: {
-                email: profile.email,
-                id: profile.id,
-                name: profile.name,
-            },
-        }, (result) => `Authenticated as ${formatUserIdentity(result.user)}.\n${formatOrganizationSummary(result.organization)}`, {
-            command: 'auth status',
-        });
-    })
-        .command('logout', 'Remove the locally stored CLI token', (logoutYargs) => logoutYargs.example('chalksurf auth logout', 'Remove the stored CLI token from local config'), async (argv) => {
-        const config = await context.configStore.loadProfile({ profileName: argv.profile });
-        const hadStoredToken = Boolean(config.token);
-        await context.configStore.update({ profileName: argv.profile }, (currentConfig) => ({
-            ...currentConfig,
-            token: undefined,
-        }));
-        context.output.print({
-            clearedStoredToken: hadStoredToken,
-            loggedOut: true,
-            profile: config.profileName,
-            profileSource: config.profileSource,
-        }, hadStoredToken ? 'Stored CLI token removed.' : 'No stored CLI token was present.', {
-            command: 'auth logout',
-        });
-    })
-        .demandCommand(1)
-        .strict();
-};