@chalksurf/cli 0.1.0 → 0.2.1

package/docs/agents.md

@@ -0,0 +1,203 @@
+# Agent And Codex Guide
+
+Use this flow when ChalkSurf is driven by Codex, CI, or another orchestration layer.
+
+## Authentication Strategy
+
+Agents must always use an explicit profile. The profile name must follow the
+`ENV-AGENT_TYPE` convention, such as `prod-codex`, `staging-codex`, `dev-claude`,
+or `prod-claude`.
+
+```bash
+chalksurf --profile prod-codex auth status --json
+```
+
+Do not rely on the default profile in agent-driven runs. The default profile is
+for the human operator's terminal workflow and may point at a different
+environment, user token, or selected organization.
+
+Create or refresh an agent profile explicitly:
+
+```bash
+printf '%s' "$CHALKSURF_TOKEN" | chalksurf auth login \
+  --profile prod-codex \
+  --base-url https://chalksurf-api.fly.dev \
+  --with-token
+```
+
+Use `CHALKSURF_TOKEN` only as the source for login or as a short-lived override.
+Prefer storing the token in the explicit agent profile for repeated Codex/CI runs.
+
+## Command Contract
+
+For agent-driven imports, always use:
+
+- `--manifest -` or a generated manifest file
+- `--wait` when the next step depends on completed imports
+- `--json` so the response stays machine-readable
+
+Recommended invocation shape:
+
+```bash
+chalksurf --profile prod-codex sheet import --manifest - --wait --json
+```
+
+In `--json` mode:
+
+- stdout contains a stable JSON envelope
+- known failures still produce JSON on stdout
+- stderr is reserved for unexpected runtime failures
+
+Wait-style failures still include a populated `result` payload, so agents can inspect partial outcomes on exit code `6` or `7`.
+
+## Manifest Design
+
+Prefer manifests over large positional argument lists.
+
+Why:
+
+- multi-source imports stay explicit
+- each logical source can carry a stable `sourceId`
+- sheet imports can group multiple source files into one resulting sheet
+- sheet imports carry `targetFolderPath`, `title`, and `translateTo` at the sheet level
+- agents can correlate import results back to the discovered source set
+
+Use `sourceId` whenever a browsing step or upstream scraper already has a stable identifier:
+
+```json
+{
+  "organizationId": "org_123",
+  "wait": true,
+  "sheets": [
+    {
+      "targetFolderPath": "OKTV/2014",
+      "title": "OKTV 2014 Round 1",
+      "translateTo": ["english"],
+      "sources": [
+        {
+          "sourceId": "oktv-2014-round-1-part-a",
+          "kind": "url",
+          "url": "https://example.com/oktv-2014-round-1-part-a.pdf"
+        },
+        {
+          "sourceId": "oktv-2014-round-1-part-b",
+          "kind": "url",
+          "url": "https://example.com/oktv-2014-round-1-part-b.pdf"
+        }
+      ]
+    }
+  ]
+}
+```
+
+For sheet imports, `targetFolderPath` is the destination of the resulting sheet. Use `null` for the root folder. Source-level `relativePath` is only a filename or source-label override and should not be used as a destination path.
+
+Further reference:
+
+- [Manifest reference](./manifest.md)
+- [Sheet import schema](../schemas/sheet-import-manifest.schema.json)
+- [Exercise import schema](../schemas/exercise-import-manifest.schema.json)
+- [Exercise solution import schema](../schemas/exercise-solution-import-manifest.schema.json)
+
+## JSON Result Shape
+
+Import commands normalize results around:
+
+- `request`
+- `sources`
+- `jobs`
+- `summary`
+
+Each resolved source includes stable correlation fields:
+
+- `sourceIndex`
+- `sourceInputIndex`
+- `sourceId`
+
+Each job includes:
+
+- `jobId`
+- `sourceIndexes`
+- `sourceIds`
+- `status`
+
+`summary` includes:
+
+- source and job counts
+- per-status counts
+- `timedOut`
+
+## Recommended Control Flow
+
+1. Discover candidate URLs or local files.
+2. Filter them to the target scope.
+3. Build a manifest with stable `sourceId` values.
+4. Pipe the manifest into the CLI with `--wait --json`.
+5. Inspect `ok`, `result.summary`, and `result.jobs`.
+6. Retry only the failed or timed-out source set.
+
+For example:
+
+```bash
+cat import.json | chalksurf --profile prod-codex sheet import --manifest - --wait --json
+```
+
+On success, the envelope looks like:
+
+```json
+{
+  "schemaVersion": "v1",
+  "command": "sheet import",
+  "ok": true,
+  "result": {
+    "request": {},
+    "sources": [],
+    "jobs": [],
+    "summary": {
+      "timedOut": false
+    }
+  },
+  "warnings": []
+}
+```
+
+On timeout or job failure, `ok` becomes `false`, `error.code` is stable, and `result` still contains the normalized import data needed for retries.
+
+## Codex Workflow Example
+
+Target task:
+
+Import all OKTV exercise sheets between 2010 and 2020 from an archive page, and translate the non-English sheets to English.
+
+Recommended workflow:
+
+1. Codex browses the archive page and collects the relevant links.
+2. Codex filters the links to years `2010` through `2020`.
+3. Codex builds a sheet-import manifest with one `sheets[]` entry per resulting sheet.
+4. Codex groups multiple source files inside one `sources[]` array when they belong to the same resulting sheet.
+5. Codex sets `translateTo: ["english"]` on the sheet entries that should produce an English translation.
+6. Codex runs `chalksurf --profile prod-codex sheet import --manifest - --wait --json`.
+7. Codex inspects `result.summary.failed`, `result.summary.timedOut`, and `jobs` to decide whether to retry or report failures.
+
+Minimal shell shape:
+
+```bash
+cat import.json | chalksurf --profile prod-codex sheet import --manifest - --wait --json
+```
+
+The discovery step belongs outside the ChalkSurf CLI. The CLI contract starts at a concrete manifest and ends at structured import results.
+
+## Failure Handling
+
+Use the exit code and JSON `error.code` together:
+
+- `2` / `usage_error`: the manifest or command input is invalid
+- `3` / `not_authenticated`: missing or invalid token
+- `4` / `source_resolution_failed`: local file, directory, or URL preparation failed
+- `5` / `api_error`: the ChalkSurf API rejected the request
+- `6` / `wait_timed_out`: jobs did not finish in time
+- `7` / `job_failed`: one or more jobs finished with failure
+
+Reference:
+
+- [Exit codes and JSON errors](./exit-codes.md)

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

@@ -0,0 +1,13 @@
+{
+  "organizationId": "org_123",
+  "exerciseSheetId": "00000000-0000-4000-8000-000000000111",
+  "wait": true,
+  "sources": [
+    {
+      "sourceId": "problem-1",
+      "kind": "local",
+      "path": "./imports/problem-1.pdf",
+      "relativePath": "Problem Set/problem-1.pdf"
+    }
+  ]
+}

package/docs/examples/exercise-solution-import-manifest.json

@@ -0,0 +1,13 @@
+{
+  "organizationId": "org_123",
+  "exerciseId": "00000000-0000-4000-8000-000000000222",
+  "wait": true,
+  "sources": [
+    {
+      "sourceId": "problem-1-solution",
+      "kind": "local",
+      "path": "./imports/problem-1-solution.pdf",
+      "relativePath": "Solutions/problem-1.pdf"
+    }
+  ]
+}

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

@@ -0,0 +1,33 @@
+{
+  "organizationId": "org_123",
+  "wait": true,
+  "sheets": [
+    {
+      "targetFolderPath": "OKTV/2014",
+      "title": "OKTV 2014 Round 1",
+      "translateTo": ["english"],
+      "sources": [
+        {
+          "sourceId": "oktv-2014-round-1-part-a",
+          "kind": "url",
+          "url": "https://example.com/oktv-2014-round-1-part-a.pdf"
+        },
+        {
+          "sourceId": "oktv-2014-round-1-part-b",
+          "kind": "url",
+          "url": "https://example.com/oktv-2014-round-1-part-b.pdf"
+        }
+      ]
+    },
+    {
+      "targetFolderPath": null,
+      "sources": [
+        {
+          "sourceId": "practice-sheet",
+          "kind": "local",
+          "path": "./practice-sheet.pdf"
+        }
+      ]
+    }
+  ]
+}

package/docs/exit-codes.md

@@ -0,0 +1,57 @@
+# Exit Codes And JSON Errors
+
+The CLI uses stable exit codes so automation can branch without parsing human text.
+
+## Exit Codes
+
+| Exit code | Error code | Meaning |
+| --- | --- | --- |
+| `0` | n/a | Success |
+| `1` | `unexpected_error` | Unhandled runtime failure |
+| `2` | `usage_error` | Invalid arguments, invalid manifest, or missing required config such as `--base-url` |
+| `3` | `not_authenticated` | Missing token or rejected CLI token |
+| `4` | `source_resolution_failed` | Local file, directory, URL, or relative path resolution failed |
+| `5` | `api_error` | The ChalkSurf API returned a non-auth failure |
+| `6` | `wait_timed_out` | Waiting ended before all jobs reached a terminal state |
+| `7` | `job_failed` | One or more jobs completed with failure |
+
+These same codes are mirrored in `error.exitCode` and `error.code` inside the JSON envelope.
+
+## JSON Envelope
+
+In `--json` mode, stdout contains a stable envelope:
+
+```json
+{
+  "schemaVersion": "v1",
+  "command": "sheet import",
+  "ok": true,
+  "result": {},
+  "warnings": []
+}
+```
+
+Known failures also return JSON on stdout:
+
+```json
+{
+  "schemaVersion": "v1",
+  "command": "sheet import",
+  "ok": false,
+  "result": {},
+  "error": {
+    "code": "source_resolution_failed",
+    "message": "Local source \"/tmp/imports/missing.pdf\" does not exist.",
+    "exitCode": 4,
+    "retryable": false
+  },
+  "warnings": []
+}
+```
+
+## Contract Notes
+
+- `warnings` contains informational messages that would otherwise be printed for humans.
+- In `--json` mode, stderr is reserved for unexpected runtime failures only.
+- Wait-style commands and imports keep their `result` payload even when `ok` is `false`.
+- Import commands normalize their `result` payloads around `request`, `sources`, `jobs`, and `summary`.

package/docs/manifest.md

@@ -0,0 +1,129 @@
+# Manifest Reference
+
+ChalkSurf uses JSON manifests for batch and agent-driven imports.
+
+One manifest file is passed to exactly one command:
+
+- `chalksurf sheet import --manifest <path|->`
+- `chalksurf exercise import --manifest <path|->`
+- `chalksurf exercise import-solution --manifest <path|->`
+
+Use `--manifest -` to pipe JSON on stdin.
+
+## Common Fields
+
+Every manifest is a JSON object with these shared metadata fields:
+
+| Field | Type | Required | Notes |
+| --- | --- | --- | --- |
+| `organizationId` | string | no | Overrides the default organization for this invocation. |
+| `wait` | boolean | no | Behaves like `--wait`. The CLI also accepts `--wait`, which wins if set. |
+
+Every source object supports these common fields. For `sheet import`, sources appear inside `sheets[].sources[]`. For the exercise import commands, they appear in top-level `sources[]`.
+
+| Field | Type | Required | Notes |
+| --- | --- | --- | --- |
+| `sourceId` | string | no | Optional stable identifier for correlating source inputs to results. Must be unique within the manifest. |
+| `kind` | `local` \| `directory` \| `url` | yes | Selects the source shape. |
+
+### Source Kinds
+
+`local`
+
+| Field | Type | Required | Notes |
+| --- | --- | --- | --- |
+| `path` | string | yes | Local file path relative to `cwd` unless already absolute. |
+| `relativePath` | string | no | Stored path shown to ChalkSurf. Defaults to the basename of `path`. |
+
+`directory`
+
+| Field | Type | Required | Notes |
+| --- | --- | --- | --- |
+| `path` | string | yes | Directory to expand recursively. |
+| `relativeRoot` | string | no | Base directory used to compute stored relative paths. Defaults to `path`. |
+
+`url`
+
+| Field | Type | Required | Notes |
+| --- | --- | --- | --- |
+| `url` | string | yes | HTTP(S) URL to download before import. |
+| `relativePath` | string | no | Stored path shown to ChalkSurf. Defaults to the filename derived from the URL. |
+
+## Command-Specific Fields
+
+### Sheet Import
+
+Top-level fields:
+
+| Field | Type | Required | Notes |
+| --- | --- | --- | --- |
+| `sheets` | array | yes | One or more sheets to import. Each sheet may contain one or more source files. |
+
+Sheet fields:
+
+| Field | Type | Required | Notes |
+| --- | --- | --- | --- |
+| `targetFolderPath` | string \| null | yes | Destination folder for the resulting sheet. Use `null` for the root folder. |
+| `sources` | array | yes | One or more source files that belong to this sheet, in import order. |
+| `title` | string | no | Overrides the imported sheet title. |
+| `translateTo` | string[] | no | Target translation languages. Must be unique and non-empty when present. |
+
+Sheet import metadata is sheet-level, not source-level. Do not put `title` or `translateTo` on individual sources inside `sheets[].sources[]`.
+
+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.
+
+Canonical example:
+
+- [docs/examples/sheet-import-manifest.json](./examples/sheet-import-manifest.json)
+- [schemas/sheet-import-manifest.schema.json](../schemas/sheet-import-manifest.schema.json)
+
+### Exercise Import
+
+Top-level fields:
+
+| Field | Type | Required | Notes |
+| --- | --- | --- | --- |
+| `sources` | array | yes | One or more import sources. |
+| `exerciseSheetId` | string | no | Default target sheet for the imported exercises. Can still be overridden by `--sheet-id`. |
+
+Per-source fields:
+
+- Only the common source fields are allowed.
+- `title` and `translateTo` are rejected for this command.
+
+Canonical example:
+
+- [docs/examples/exercise-import-manifest.json](./examples/exercise-import-manifest.json)
+- [schemas/exercise-import-manifest.schema.json](../schemas/exercise-import-manifest.schema.json)
+
+### Exercise Solution Import
+
+Top-level fields:
+
+| Field | Type | Required | Notes |
+| --- | --- | --- | --- |
+| `sources` | array | yes | One or more import sources. |
+| `exerciseId` | string | no | Default target exercise for the imported solution files. The command still requires an exercise id overall, either here or positionally. |
+
+Per-source fields:
+
+- Only the common source fields are allowed.
+- `title` and `translateTo` are rejected for this command.
+
+Canonical example:
+
+- [docs/examples/exercise-solution-import-manifest.json](./examples/exercise-solution-import-manifest.json)
+- [schemas/exercise-solution-import-manifest.schema.json](../schemas/exercise-solution-import-manifest.schema.json)
+
+## Validation Notes
+
+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.
+- `relativePath` cannot be empty or contain `..`.
+- Sheet import `targetFolderPath` must be `null` or a normalized folder path without `.` or `..` segments.
+- `directory` imports must resolve to at least one file.
+- URL imports must use `http` or `https`.
+
+Treat the schema files as a reference format and the CLI as the final validator.

package/docs/manual.md

@@ -0,0 +1,169 @@
+# Manual Operator Guide
+
+Use this flow when a person is driving the CLI directly from a terminal.
+
+## Authentication
+
+Interactive login stores the token and base URL in a named profile:
+
+```bash
+chalksurf auth login --profile prod-cztamas --base-url https://chalksurf-api.fly.dev
+```
+
+The same command also works with piped stdin:
+
+```bash
+printf '%s' "$CHALKSURF_TOKEN" | chalksurf auth login \
+  --profile prod-cztamas \
+  --base-url https://chalksurf-api.fly.dev \
+  --with-token
+```
+
+Set the profile you want to use by default in your terminal workflow:
+
+```bash
+chalksurf profile use prod-cztamas
+```
+
+Check what the CLI will use for the current session:
+
+```bash
+chalksurf auth status
+```
+
+Config resolution rules:
+
+- `--profile` overrides `CHALKSURF_PROFILE`, which overrides the stored default profile.
+- `--base-url` overrides `CHALKSURF_BASE_URL`, which overrides the active profile.
+- `CHALKSURF_TOKEN` overrides the active profile token.
+- `--organization` overrides manifest `organizationId`, which overrides `CHALKSURF_ORGANIZATION_ID`, which overrides the active profile.
+
+## Organization Selection
+
+List organizations visible to the current token:
+
+```bash
+chalksurf org list
+```
+
+Store a default organization for future commands:
+
+```bash
+chalksurf org use org_123
+```
+
+Store a default organization in a different profile without changing your default profile:
+
+```bash
+chalksurf --profile prod-codex org use org_456
+```
+
+Override it for one command:
+
+```bash
+chalksurf sheet import ./fixtures/algebra.pdf --organization org_456
+```
+
+## Common Import Flows
+
+Import one sheet and wait for the background job to finish:
+
+```bash
+chalksurf sheet import ./fixtures/algebra.pdf --wait
+```
+
+Import one sheet, override its title, and request an English translation during import:
+
+```bash
+chalksurf sheet import ./fixtures/algebra.pdf \
+  --title "OKTV 2014 Round 1" \
+  --translate-to english \
+  --wait
+```
+
+Import one sheet assembled from multiple source files:
+
+```bash
+chalksurf sheet import ./fixtures/round-1-a.pdf ./fixtures/round-1-b.pdf \
+  --single-sheet \
+  --target-folder "OKTV/2014" \
+  --wait
+```
+
+Import exercises into an existing sheet:
+
+```bash
+chalksurf exercise import ./fixtures/problem-set.pdf \
+  --sheet-id 00000000-0000-4000-8000-000000000001 \
+  --wait
+```
+
+Import a solution into an existing exercise:
+
+```bash
+chalksurf exercise import-solution \
+  00000000-0000-4000-8000-000000000001 \
+  ./fixtures/solution.pdf \
+  --wait
+```
+
+Import from a remote URL:
+
+```bash
+chalksurf sheet import https://example.com/trig.docx \
+  --single-sheet \
+  --target-folder Imported \
+  --wait
+```
+
+Use a manifest for multi-source imports or when each resulting sheet needs explicit metadata:
+
+```bash
+chalksurf sheet import --manifest ./import.json --wait
+```
+
+Sheet import manifests use top-level `sheets[]`. Each sheet has one destination `targetFolderPath`, optional `title` and `translateTo`, and one or more ordered `sources[]`.
+
+## Working With Jobs
+
+Read one job:
+
+```bash
+chalksurf job get job_123
+```
+
+Wait on one or more jobs later:
+
+```bash
+chalksurf job wait job_123 job_124
+```
+
+`--wait` on an import command means the requested import work is complete before the command exits. For sheet imports, that includes requested translations.
+
+## Troubleshooting
+
+Missing auth:
+
+```bash
+chalksurf auth status
+```
+
+Use profiles when switching between local, staging, production, humans, and agents:
+
+```bash
+chalksurf auth login --profile staging-cztamas --base-url https://chalksurf-api-staging.fly.dev
+chalksurf auth login --profile prod-cztamas --base-url https://chalksurf-api.fly.dev
+chalksurf profile use prod-cztamas
+```
+
+Use JSON mode when you need exact machine-readable output:
+
+```bash
+chalksurf job wait job_123 --json
+```
+
+Further reference:
+
+- [Agent and Codex guide](./agents.md)
+- [Manifest reference](./manifest.md)
+- [Exit codes and JSON errors](./exit-codes.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chalksurf/cli",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "private": false,
   "type": "module",
   "engines": {
@@ -8,7 +8,9 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "docs",
+    "schemas"
   ],
   "bin": {
     "chalksurf": "dist/bin/chalksurf.js"
@@ -26,12 +28,14 @@
     "build": "tsc --project ./tsconfig.build.json",
     "lint": "eslint .",
     "type-check": "tsc --noEmit --project ./tsconfig.json",
-    "test": "vitest --config ./vitest.config.ts --run",
+    "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"
   },
   "dependencies": {
     "p-limit": "^6.2.0",
-    "yargs": "^17.7.2"
+    "yargs": "^17.7.2",
+    "zod": "^4.1.12"
   },
   "devDependencies": {
     "@types/node": "^24.10.1",