@chalksurf/cli 0.2.1 → 0.2.3

package/dist/lib/manifest.js

@@ -19,6 +19,7 @@ const translationLanguageListSchema = z
     .refine((languages) => new Set(languages).size === languages.length, {
     message: 'translateTo languages must be unique.',
 });
+const sheetImportComponentIdPattern = /^[a-zA-Z0-9_-]{1,80}$/;
 const parseTranslateTo = ({ value, label }) => {
     if (value == null) {
         return undefined;
@@ -70,6 +71,52 @@ const parseTargetFolderPath = ({ value, label }) => {
     }
     return normalizedValue;
 };
+const parseOptionalTargetFolderPath = ({ value, label }) => {
+    if (value == null) {
+        return null;
+    }
+    return parseTargetFolderPath({ value, label });
+};
+const parseSheetImportComponents = ({ value, sheetIndex, }) => {
+    if (value == null) {
+        return undefined;
+    }
+    if (!Array.isArray(value) || value.length === 0) {
+        throw new CliCommandError(`Manifest sheet at index ${sheetIndex} components must be a non-empty array.`, 2);
+    }
+    const seenComponentIds = new Set();
+    return value.map((componentValue, componentIndex) => {
+        const label = `Manifest sheet at index ${sheetIndex} component at index ${componentIndex}`;
+        if (!isObject(componentValue)) {
+            throw new CliCommandError(`${label} must be an object.`, 2);
+        }
+        const componentId = normalizeOptionalString(componentValue.componentId);
+        if (!componentId || !sheetImportComponentIdPattern.test(componentId)) {
+            throw new CliCommandError(`${label} must include a componentId using 1-80 letters, numbers, underscores, or hyphens.`, 2);
+        }
+        if (seenComponentIds.has(componentId)) {
+            throw new CliCommandError(`Manifest sheet at index ${sheetIndex} componentId "${componentId}" must be unique.`, 2);
+        }
+        seenComponentIds.add(componentId);
+        const description = normalizeOptionalString(componentValue.description);
+        if (!description) {
+            throw new CliCommandError(`${label} must include a non-empty description.`, 2);
+        }
+        return {
+            componentId,
+            description,
+            targetFolderPath: parseOptionalTargetFolderPath({
+                value: componentValue.targetFolderPath,
+                label,
+            }),
+            title: normalizeOptionalString(componentValue.title),
+            translateTo: parseTranslateTo({
+                value: componentValue.translateTo,
+                label,
+            }),
+        };
+    });
+};
 const parseManifestMetadata = ({ parsedManifest, topLevelFields, }) => {
     const wait = typeof parsedManifest.wait === 'boolean' ? parsedManifest.wait : undefined;
     return {
@@ -161,6 +208,10 @@ const parseExerciseImportManifest = (manifestText) => {
             parsedManifest,
             topLevelFields: ['exerciseSheetId'],
         }),
+        translateTo: parseTranslateTo({
+            value: parsedManifest.translateTo,
+            label: 'Manifest',
+        }),
         sources,
     };
 };
@@ -176,6 +227,18 @@ const parseExerciseSolutionImportManifest = (manifestText) => {
         sources,
     };
 };
+const parseExerciseSheetSolutionImportManifest = (manifestText) => {
+    const parsedManifest = parseSourceManifestObject(manifestText);
+    const sources = parsedManifest.sources.map((source, index) => parseBaseManifestSource(source, index));
+    assertUniqueSourceIds(sources);
+    return {
+        ...parseManifestMetadata({
+            parsedManifest,
+            topLevelFields: ['exerciseSheetId'],
+        }),
+        sources,
+    };
+};
 const parseSheetImportManifest = (manifestText) => {
     const parsedManifest = parseManifestObject(manifestText);
     if ('sources' in parsedManifest) {
@@ -199,6 +262,17 @@ const parseSheetImportManifest = (manifestText) => {
             sources.push(parsedSource);
             return flattenedSourceIndex;
         });
+        const components = parseSheetImportComponents({ value: sheetValue.components, sheetIndex });
+        if (components) {
+            if ('targetFolderPath' in sheetValue || 'title' in sheetValue || 'translateTo' in sheetValue) {
+                throw new CliCommandError(`Manifest sheet at index ${sheetIndex} must set targetFolderPath, title, and translateTo on components when components are provided.`, 2);
+            }
+            sheetGroups.push({
+                sourceInputIndexes,
+                components,
+            });
+            return;
+        }
         sheetGroups.push({
             sourceInputIndexes,
             targetFolderPath: parseTargetFolderPath({
@@ -261,6 +335,14 @@ export const loadExerciseSolutionImportManifest = async ({ cwd, manifestPath, st
         stdin,
     });
 };
+export const loadExerciseSheetSolutionImportManifest = async ({ cwd, manifestPath, stdin, }) => {
+    return await loadManifest({
+        cwd,
+        manifestPath,
+        parseManifest: parseExerciseSheetSolutionImportManifest,
+        stdin,
+    });
+};
 export const loadSheetImportManifest = async ({ cwd, manifestPath, stdin, }) => {
     return await loadManifest({
         cwd,

package/dist/lib/session.js

@@ -1,3 +1,4 @@
+import { createApiClient } from './api-client.js';
 import { CliCommandError } from './cli-error.js';
 import { chalksurfBaseUrlEnvVar, chalksurfOrganizationIdEnvVar, chalksurfTokenEnvVar, resolveBaseUrl, resolveToken, } from './config-store.js';
 const normalizeOptionalString = (value) => {
@@ -31,6 +32,32 @@ export const resolveRequestedOrganizationId = ({ config, env, fallbackValue, fla
         normalizeOptionalString(env[chalksurfOrganizationIdEnvVar]) ??
         normalizeOptionalString(config.organizationId));
 };
+export const createResolvedApiClient = async ({ context, baseUrlFlagValue, organizationFallbackValue, organizationFlagValue, profileName, }) => {
+    const config = await context.configStore.loadProfile({ profileName });
+    const resolvedBaseUrl = requireResolvedBaseUrl({
+        flagValue: baseUrlFlagValue,
+        env: context.env,
+        config,
+    });
+    const resolvedToken = requireResolvedToken({
+        env: context.env,
+        config,
+    });
+    const organizationId = resolveRequestedOrganizationId({
+        flagValue: organizationFlagValue,
+        fallbackValue: organizationFallbackValue,
+        env: context.env,
+        config,
+    });
+    return {
+        apiClient: createApiClient({
+            baseUrl: resolvedBaseUrl.value,
+            token: resolvedToken.value,
+            organizationId,
+        }),
+        organizationId,
+    };
+};
 export const formatUserIdentity = (profile) => {
     if (profile.name && profile.email) {
         return `${profile.name} <${profile.email}>`;

package/dist/lib/translation-languages.js

@@ -1 +1,16 @@
+import { CliCommandError } from './cli-error.js';
 export const translationLanguages = ['english', 'hungarian', 'german', 'french', 'spanish', 'italian'];
+export const resolveRequestedTranslateToLanguages = (rawValues) => {
+    if (!rawValues || rawValues.length === 0) {
+        return undefined;
+    }
+    const invalidLanguage = rawValues.find((value) => !translationLanguages.includes(value));
+    if (invalidLanguage) {
+        throw new CliCommandError(`--translate-to must be one of: ${translationLanguages.join(', ')}`, 2);
+    }
+    const languages = rawValues;
+    if (new Set(languages).size !== languages.length) {
+        throw new CliCommandError('--translate-to languages must be unique.', 2);
+    }
+    return languages;
+};

package/dist/lib/user-jobs.js

@@ -14,7 +14,14 @@ export const serializeCliJob = (job) => {
         exerciseId: job.result?.exerciseId,
         exerciseIds: job.result?.exerciseIds,
         exerciseSheetId: job.result?.exerciseSheetId,
+        eligibleExerciseCount: job.result?.eligibleExerciseCount,
+        nonUpdatableExerciseCount: job.result?.nonUpdatableExerciseCount,
         resultCode: job.result?.resultCode,
+        sheets: job.result?.sheets,
+        skippedExerciseCount: job.result?.skippedExerciseCount,
+        translationJobs: job.result?.translationJobs,
+        unmatchedImportedSolutionCount: job.result?.unmatchedImportedSolutionCount,
+        updatedExerciseCount: job.result?.updatedExerciseCount,
     };
 };
 export const formatCliJobSummary = (job) => {
@@ -22,6 +29,13 @@ export const formatCliJobSummary = (job) => {
         if (job.exerciseSheetId) {
             return `${job.id} completed -> ${job.exerciseSheetId}`;
         }
+        const importedSheets = job.sheets?.filter((sheet) => sheet.status === 'imported') ?? [];
+        if (importedSheets.length === 1) {
+            return `${job.id} completed -> ${importedSheets[0].exerciseSheetId}`;
+        }
+        if (importedSheets.length > 1) {
+            return `${job.id} completed -> ${importedSheets.length} sheets`;
+        }
         if (job.exerciseId) {
             return `${job.id} completed -> ${job.exerciseId}`;
         }

package/docs/agents.md

@@ -33,7 +33,7 @@ Prefer storing the token in the explicit agent profile for repeated Codex/CI run
 For agent-driven imports, always use:
 
 - `--manifest -` or a generated manifest file
-- `--wait` when the next step depends on completed imports
+- `--wait` when the next step depends on parsed content being saved
 - `--json` so the response stays machine-readable
 
 Recommended invocation shape:
@@ -49,6 +49,7 @@ In `--json` mode:
 - 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`.
+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`.
 
 ## Manifest Design
 
@@ -60,6 +61,8 @@ Why:
 - 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
+- exercise imports can carry top-level `translateTo` for every imported exercise
+- sheet solution imports can reconcile one or more solution files against all updatable exercises in one existing sheet
 - 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:
@@ -98,6 +101,7 @@ Further reference:
 - [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)
+- [Exercise sheet solution import schema](../schemas/exercise-sheet-solution-import-manifest.schema.json)
 
 ## JSON Result Shape
 
@@ -120,6 +124,7 @@ Each job includes:
 - `sourceIndexes`
 - `sourceIds`
 - `status`
+- `translationJobs` when requested translations were queued after import
 
 `summary` includes:
 
@@ -133,8 +138,9 @@ Each job includes:
 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.
+5. Inspect `ok`, `result.summary`, `result.jobs`, and any nested `translationJobs`.
+6. Use `job list`, `job wait`, `sheet search`, and `exercise search` to verify the created resources or translation jobs when needed.
+7. Retry only the failed or timed-out source set.
 
 For example:
 
@@ -163,6 +169,54 @@ On success, the envelope looks like:
 
 On timeout or job failure, `ok` becomes `false`, `error.code` is stable, and `result` still contains the normalized import data needed for retries.
 
+## Verification Commands
+
+Agents can inspect their own work without opening the web UI. Search commands default to `--ownership own`, which means the selected organization from `--organization`, `CHALKSURF_ORGANIZATION_ID`, or the active profile.
+
+List recent jobs, including jobs the UI tray has already viewed or dismissed:
+
+```bash
+chalksurf --profile prod-codex job list --include-viewed --include-dismissed --json
+```
+
+Find failed import jobs for retry:
+
+```bash
+chalksurf --profile prod-codex job list \
+  --status failed \
+  --type exercise_sheet_import \
+  --include-viewed \
+  --include-dismissed \
+  --json
+```
+
+Verify an imported private sheet by title:
+
+```bash
+chalksurf --profile prod-codex sheet search --text "OKTV 2014" --json
+```
+
+Verify imported exercises by text. Text search requires an explicit language:
+
+```bash
+chalksurf --profile prod-codex exercise search \
+  --text "binomial theorem" \
+  --language english \
+  --json
+```
+
+Import solutions for an already imported sheet when the solution key is separate:
+
+```bash
+chalksurf --profile prod-codex sheet import-solutions \
+  00000000-0000-4000-8000-000000000001 \
+  ./solutions.pdf \
+  --wait \
+  --json
+```
+
+Use `--ownership public` for public-library checks and `--ownership all` when the agent intentionally wants public results plus selected-organization results.
+
 ## Codex Workflow Example
 
 Target task:

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

@@ -1,6 +1,7 @@
 {
   "organizationId": "org_123",
   "exerciseSheetId": "00000000-0000-4000-8000-000000000111",
+  "translateTo": ["english"],
   "wait": true,
   "sources": [
     {

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

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

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

@@ -7,6 +7,7 @@ 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|->`
+- `chalksurf sheet import-solutions --manifest <path|->`
 
 Use `--manifest -` to pipe JSON on stdin.
 
@@ -17,9 +18,9 @@ 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. |
+| `wait` | boolean | no | Behaves like `--wait`. The CLI also accepts `--wait`, which wins if set. Requested translations run as follow-up jobs listed in the import result. |
 
-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[]`.
+Every source object supports these common fields. For `sheet import`, sources appear inside `sheets[].sources[]`. For the exercise import commands and `sheet import-solutions`, they appear in top-level `sources[]`.
 
 | Field | Type | Required | Notes |
 | --- | --- | --- | --- |
@@ -59,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 |
 | --- | --- | --- | --- |
@@ -72,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)
@@ -85,11 +107,12 @@ Top-level fields:
 | --- | --- | --- | --- |
 | `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`. |
+| `translateTo` | string[] | no | Target translation languages for every imported exercise. Must be unique and non-empty when present. |
 
 Per-source fields:
 
 - Only the common source fields are allowed.
-- `title` and `translateTo` are rejected for this command.
+- `title` and source-level `translateTo` are rejected for this command.
 
 Canonical example:
 
@@ -115,12 +138,34 @@ 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)
 
+### Exercise Sheet Solution Import
+
+Top-level fields:
+
+| Field | Type | Required | Notes |
+| --- | --- | --- | --- |
+| `sources` | array | yes | One or more source files containing solutions for some or all exercises in the target sheet. |
+| `exerciseSheetId` | string | no | Default target sheet for the imported solution files. The command still requires a sheet 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-sheet-solution-import-manifest.json](./examples/exercise-sheet-solution-import-manifest.json)
+- [schemas/exercise-sheet-solution-import-manifest.schema.json](../schemas/exercise-sheet-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.
+- 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.
 - `directory` imports must resolve to at least one file.

package/docs/manual.md

@@ -72,7 +72,7 @@ Import one sheet and wait for the background job to finish:
 chalksurf sheet import ./fixtures/algebra.pdf --wait
 ```
 
-Import one sheet, override its title, and request an English translation during import:
+Import one sheet, override its title, and request an English translation after import:
 
 ```bash
 chalksurf sheet import ./fixtures/algebra.pdf \
@@ -95,6 +95,7 @@ Import exercises into an existing sheet:
 ```bash
 chalksurf exercise import ./fixtures/problem-set.pdf \
   --sheet-id 00000000-0000-4000-8000-000000000001 \
+  --translate-to english \
   --wait
 ```
 
@@ -107,6 +108,15 @@ chalksurf exercise import-solution \
   --wait
 ```
 
+Import a separate solution file for an existing exercise sheet:
+
+```bash
+chalksurf sheet import-solutions \
+  00000000-0000-4000-8000-000000000001 \
+  ./fixtures/sheet-solutions.pdf \
+  --wait
+```
+
 Import from a remote URL:
 
 ```bash
@@ -126,6 +136,18 @@ Sheet import manifests use top-level `sheets[]`. Each sheet has one destination
 
 ## Working With Jobs
 
+List recent jobs:
+
+```bash
+chalksurf job list
+```
+
+Include jobs already viewed or dismissed in the web UI:
+
+```bash
+chalksurf job list --include-viewed --include-dismissed
+```
+
 Read one job:
 
 ```bash
@@ -138,7 +160,29 @@ Wait on one or more jobs later:
 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.
+`--wait` on an import command means the parsed content has been saved before the command exits. Requested translations run as separate jobs; use `--json` to capture their job IDs or `chalksurf job list` to inspect them later.
+
+## Searching From The CLI
+
+Search commands default to `--ownership own`, which means resources in the selected organization.
+
+Find exercise sheets by title:
+
+```bash
+chalksurf sheet search --text "OKTV 2014"
+```
+
+Find exercises by text:
+
+```bash
+chalksurf exercise search --text "binomial theorem" --language english
+```
+
+Search public resources instead:
+
+```bash
+chalksurf sheet search --text "OKTV" --ownership public
+```
 
 ## Troubleshooting
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chalksurf/cli",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "private": false,
   "type": "module",
   "engines": {

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

@@ -14,6 +14,14 @@
       "type": "string",
       "minLength": 1
     },
+    "translateTo": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": {
+        "$ref": "#/$defs/translateLanguage"
+      }
+    },
     "wait": {
       "type": "boolean"
     },
@@ -30,6 +38,10 @@
       "type": "string",
       "minLength": 1
     },
+    "translateLanguage": {
+      "type": "string",
+      "enum": ["english", "hungarian", "german", "french", "spanish", "italian"]
+    },
     "localSource": {
       "type": "object",
       "additionalProperties": false,