@chalksurf/cli 0.1.0 → 0.2.0

package/docs/manual.md

@@ -0,0 +1,152 @@
+# 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 the local CLI config:
+
+```bash
+chalksurf auth login --base-url https://api.chalksurf.com
+```
+
+The same command also works with piped stdin:
+
+```bash
+printf '%s' "$CHALKSURF_TOKEN" | chalksurf auth login --base-url https://api.chalksurf.com
+```
+
+Check what the CLI will use for the current session:
+
+```bash
+chalksurf auth status
+```
+
+Config resolution rules:
+
+- `--base-url` overrides `CHALKSURF_BASE_URL`, which overrides the stored config.
+- `CHALKSURF_TOKEN` overrides the stored config token.
+- `--organization` overrides manifest `organizationId`, which overrides `CHALKSURF_ORGANIZATION_ID`, which overrides the stored config.
+
+## 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
+```
+
+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 a separate config file when switching between local, staging, and production:
+
+```bash
+export CHALKSURF_CONFIG_PATH=/tmp/chalksurf-staging.json
+chalksurf auth login --base-url https://staging-api.chalksurf.com
+```
+
+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.0",
   "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",

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

@@ -0,0 +1,104 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/knowledge-maps/chalksurf/blob/main/packages/cli/schemas/exercise-import-manifest.schema.json",
+  "title": "ChalkSurf Exercise Import Manifest",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["sources"],
+  "properties": {
+    "organizationId": {
+      "type": "string",
+      "minLength": 1
+    },
+    "exerciseSheetId": {
+      "type": "string",
+      "minLength": 1
+    },
+    "wait": {
+      "type": "boolean"
+    },
+    "sources": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "$ref": "#/$defs/source"
+      }
+    }
+  },
+  "$defs": {
+    "nonEmptyString": {
+      "type": "string",
+      "minLength": 1
+    },
+    "localSource": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "path"],
+      "properties": {
+        "sourceId": {
+          "$ref": "#/$defs/nonEmptyString"
+        },
+        "kind": {
+          "const": "local"
+        },
+        "path": {
+          "$ref": "#/$defs/nonEmptyString"
+        },
+        "relativePath": {
+          "$ref": "#/$defs/nonEmptyString"
+        }
+      }
+    },
+    "directorySource": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "path"],
+      "properties": {
+        "sourceId": {
+          "$ref": "#/$defs/nonEmptyString"
+        },
+        "kind": {
+          "const": "directory"
+        },
+        "path": {
+          "$ref": "#/$defs/nonEmptyString"
+        },
+        "relativeRoot": {
+          "$ref": "#/$defs/nonEmptyString"
+        }
+      }
+    },
+    "urlSource": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "url"],
+      "properties": {
+        "sourceId": {
+          "$ref": "#/$defs/nonEmptyString"
+        },
+        "kind": {
+          "const": "url"
+        },
+        "url": {
+          "$ref": "#/$defs/nonEmptyString"
+        },
+        "relativePath": {
+          "$ref": "#/$defs/nonEmptyString"
+        }
+      }
+    },
+    "source": {
+      "oneOf": [
+        {
+          "$ref": "#/$defs/localSource"
+        },
+        {
+          "$ref": "#/$defs/directorySource"
+        },
+        {
+          "$ref": "#/$defs/urlSource"
+        }
+      ]
+    }
+  }
+}

package/schemas/exercise-solution-import-manifest.schema.json

@@ -0,0 +1,104 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/knowledge-maps/chalksurf/blob/main/packages/cli/schemas/exercise-solution-import-manifest.schema.json",
+  "title": "ChalkSurf Exercise Solution Import Manifest",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["sources"],
+  "properties": {
+    "organizationId": {
+      "type": "string",
+      "minLength": 1
+    },
+    "exerciseId": {
+      "type": "string",
+      "minLength": 1
+    },
+    "wait": {
+      "type": "boolean"
+    },
+    "sources": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "$ref": "#/$defs/source"
+      }
+    }
+  },
+  "$defs": {
+    "nonEmptyString": {
+      "type": "string",
+      "minLength": 1
+    },
+    "localSource": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "path"],
+      "properties": {
+        "sourceId": {
+          "$ref": "#/$defs/nonEmptyString"
+        },
+        "kind": {
+          "const": "local"
+        },
+        "path": {
+          "$ref": "#/$defs/nonEmptyString"
+        },
+        "relativePath": {
+          "$ref": "#/$defs/nonEmptyString"
+        }
+      }
+    },
+    "directorySource": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "path"],
+      "properties": {
+        "sourceId": {
+          "$ref": "#/$defs/nonEmptyString"
+        },
+        "kind": {
+          "const": "directory"
+        },
+        "path": {
+          "$ref": "#/$defs/nonEmptyString"
+        },
+        "relativeRoot": {
+          "$ref": "#/$defs/nonEmptyString"
+        }
+      }
+    },
+    "urlSource": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "url"],
+      "properties": {
+        "sourceId": {
+          "$ref": "#/$defs/nonEmptyString"
+        },
+        "kind": {
+          "const": "url"
+        },
+        "url": {
+          "$ref": "#/$defs/nonEmptyString"
+        },
+        "relativePath": {
+          "$ref": "#/$defs/nonEmptyString"
+        }
+      }
+    },
+    "source": {
+      "oneOf": [
+        {
+          "$ref": "#/$defs/localSource"
+        },
+        {
+          "$ref": "#/$defs/directorySource"
+        },
+        {
+          "$ref": "#/$defs/urlSource"
+        }
+      ]
+    }
+  }
+}

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

@@ -0,0 +1,142 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/knowledge-maps/chalksurf/blob/main/packages/cli/schemas/sheet-import-manifest.schema.json",
+  "title": "ChalkSurf Sheet Import Manifest",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["sheets"],
+  "properties": {
+    "organizationId": {
+      "type": "string",
+      "minLength": 1
+    },
+    "wait": {
+      "type": "boolean"
+    },
+    "sheets": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "$ref": "#/$defs/sheet"
+      }
+    }
+  },
+  "$defs": {
+    "nonEmptyString": {
+      "type": "string",
+      "minLength": 1
+    },
+    "targetFolderPath": {
+      "oneOf": [
+        {
+          "type": "null"
+        },
+        {
+          "$ref": "#/$defs/nonEmptyString"
+        }
+      ]
+    },
+    "translateLanguage": {
+      "type": "string",
+      "enum": ["english", "hungarian", "german", "french", "spanish", "italian"]
+    },
+    "localSource": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "path"],
+      "properties": {
+        "sourceId": {
+          "$ref": "#/$defs/nonEmptyString"
+        },
+        "kind": {
+          "const": "local"
+        },
+        "path": {
+          "$ref": "#/$defs/nonEmptyString"
+        },
+        "relativePath": {
+          "$ref": "#/$defs/nonEmptyString"
+        }
+      }
+    },
+    "directorySource": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "path"],
+      "properties": {
+        "sourceId": {
+          "$ref": "#/$defs/nonEmptyString"
+        },
+        "kind": {
+          "const": "directory"
+        },
+        "path": {
+          "$ref": "#/$defs/nonEmptyString"
+        },
+        "relativeRoot": {
+          "$ref": "#/$defs/nonEmptyString"
+        }
+      }
+    },
+    "urlSource": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "url"],
+      "properties": {
+        "sourceId": {
+          "$ref": "#/$defs/nonEmptyString"
+        },
+        "kind": {
+          "const": "url"
+        },
+        "url": {
+          "$ref": "#/$defs/nonEmptyString"
+        },
+        "relativePath": {
+          "$ref": "#/$defs/nonEmptyString"
+        }
+      }
+    },
+    "source": {
+      "oneOf": [
+        {
+          "$ref": "#/$defs/localSource"
+        },
+        {
+          "$ref": "#/$defs/directorySource"
+        },
+        {
+          "$ref": "#/$defs/urlSource"
+        }
+      ]
+    },
+    "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"
+          }
+        },
+        "sources": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "$ref": "#/$defs/source"
+          }
+        }
+      }
+    }
+  }
+}