@chalksurf/cli 0.2.2 → 0.2.3

package/README.md

@@ -1,21 +1,19 @@
 # `@chalksurf/cli`
 
-Publishable ChalkSurf CLI package.
-
-Current internal release line: `0.2.2`. Expect breaking changes while the CLI is still only used internally.
+Publishable ChalkSurf CLI package. Expect breaking changes while the CLI is still only used internally.
 
 ## Installation
 
 Run the published CLI without a global install:
 
 ```bash
-npx @chalksurf/cli@0.2.2 --help
+npx @chalksurf/cli@ --help
 ```
 
 Install it globally when you want a persistent local binary:
 
 ```bash
-npm install -g @chalksurf/cli@0.2.2
+npm install -g @chalksurf/cli
 chalksurf --version
 ```
 
@@ -34,12 +32,12 @@ Headless or agent flow:
 
 ```bash
 CHALKSURF_TOKEN=cs_cli_... \
-printf '%s' "$CHALKSURF_TOKEN" | npx @chalksurf/cli@0.2.2 auth login \
+printf '%s' "$CHALKSURF_TOKEN" | npx @chalksurf/cli auth login \
   --profile prod-codex \
   --base-url https://chalksurf-api.fly.dev \
   --with-token
 
-npx @chalksurf/cli@0.2.2 --profile prod-codex sheet import --manifest - --wait --json < import.json
+npx @chalksurf/cli --profile prod-codex sheet import --manifest - --wait --json < import.json
 ```
 
 Sheet import manifests use top-level `sheets[]`, where each sheet has one `targetFolderPath` and one or more ordered `sources[]`. See [the canonical example](./packages/cli/docs/examples/sheet-import-manifest.json).
@@ -60,7 +58,7 @@ Sheet import manifests use top-level `sheets[]`, where each sheet has one `targe
 Use separate profiles so local, staging, production, human, and agent tokens do not overwrite each other:
 
 ```bash
-npm run cli-dev -- auth login --profile dev-cztamas --base-url http://localhost:8080
+npm run cli-dev -- auth login --profile dev-cztamas --base-url http://localhost:3101
 npm run cli-dev -- profile use dev-cztamas
 npm run cli-dev -- auth status --json
 npm run cli-dev -- sheet import ./fixtures/algebra.pdf --wait --json

package/dist/commands/sheet.js

@@ -10,6 +10,7 @@ import { cleanupResolvedSources, resolveSources } from '../lib/source-resolver.j
 import { resolveRequestedTranslateToLanguages, translationLanguages, } from '../lib/translation-languages.js';
 import { formatCliJobSummary, getWaitError, getWaitExitCode, throwSilentExitCode, waitForCliJobs, } from '../lib/user-jobs.js';
 const hasUniqueItems = (values) => new Set(values).size === values.length;
+const sheetImportComponentIdPattern = /^[a-zA-Z0-9_-]{1,80}$/;
 const isValidTargetFolderPath = (value) => {
     const normalizedSegments = value
         .replaceAll('\\', '/')
@@ -31,6 +32,32 @@ const assertValidSheetImportPlan = (plan) => {
         if (!hasUniqueItems(sheet.sourceIndexes)) {
             throw new CliCommandError('Invalid sheet import plan: sourceIndexes must be unique within a sheet.', 2);
         }
+        if (sheet.components) {
+            if (sheet.targetFolderPath !== undefined || sheet.titleOverride !== undefined || sheet.translateToLanguages) {
+                throw new CliCommandError('Invalid sheet import plan: targetFolderPath, titleOverride, and translateToLanguages must be set on components when components are provided.', 2);
+            }
+            if (!hasUniqueItems(sheet.components.map((component) => component.componentId))) {
+                throw new CliCommandError('Invalid sheet import plan: componentId values must be unique within a sheet.', 2);
+            }
+            sheet.components.forEach((component) => {
+                if (!sheetImportComponentIdPattern.test(component.componentId)) {
+                    throw new CliCommandError('Invalid sheet import plan: componentId must be 1-80 letters, numbers, underscores, or hyphens.', 2);
+                }
+                if (!component.description.trim()) {
+                    throw new CliCommandError('Invalid sheet import plan: component descriptions must be non-empty.', 2);
+                }
+                if (component.targetFolderPath != null && !isValidTargetFolderPath(component.targetFolderPath)) {
+                    throw new CliCommandError('Invalid sheet import plan: component targetFolderPath must be a normalized folder path without "." or ".." segments.', 2);
+                }
+                if (component.translateToLanguages && !hasUniqueItems(component.translateToLanguages)) {
+                    throw new CliCommandError('Invalid sheet import plan: component translateToLanguages must be unique.', 2);
+                }
+            });
+            return;
+        }
+        if (sheet.targetFolderPath === undefined) {
+            throw new CliCommandError('Invalid sheet import plan: targetFolderPath is required.', 2);
+        }
         if (sheet.targetFolderPath !== null && !isValidTargetFolderPath(sheet.targetFolderPath)) {
             throw new CliCommandError('Invalid sheet import plan: targetFolderPath must be a normalized folder path without "." or ".." segments.', 2);
         }
@@ -132,9 +159,21 @@ const resolveGroupedSourceIndexes = ({ groups, sourceIndexesByInputIndex, }) =>
         });
         return {
             sourceIndexes,
-            targetFolderPath: group.targetFolderPath,
-            titleOverride: group.title,
-            translateToLanguages: group.translateTo,
+            ...(group.components
+                ? {
+                    components: group.components.map((component) => ({
+                        componentId: component.componentId,
+                        description: component.description,
+                        targetFolderPath: component.targetFolderPath,
+                        titleOverride: component.title,
+                        translateToLanguages: component.translateTo,
+                    })),
+                }
+                : {
+                    targetFolderPath: group.targetFolderPath,
+                    titleOverride: group.title,
+                    translateToLanguages: group.translateTo,
+                }),
         };
     });
 };
@@ -173,6 +212,7 @@ const buildSheetImportJobs = ({ importResultJobs, sources, waitedJobsById, }) =>
     return importResultJobs.map((job, index) => {
         const sourceIndexes = job.sourceIndexes ?? (sources[index] ? [sources[index].sourceIndex] : []);
         const waitedJob = waitedJobsById?.get(job.jobId);
+        const importedSheetTranslationJobs = waitedJob?.sheets?.flatMap((sheet) => (sheet.status === 'imported' ? (sheet.translationJobs ?? []) : [])) ?? [];
         return {
             jobId: job.jobId,
             sourceIndexes,
@@ -181,8 +221,10 @@ const buildSheetImportJobs = ({ importResultJobs, sources, waitedJobsById, }) =>
                 .filter((sourceId) => sourceId != null))),
             status: waitedJob?.status ?? 'queued',
             error: waitedJob?.error,
+            componentIds: job.componentIds,
             exerciseSheetId: waitedJob?.exerciseSheetId,
-            translationJobs: waitedJob?.translationJobs,
+            sheets: waitedJob?.sheets,
+            translationJobs: waitedJob?.translationJobs ?? importedSheetTranslationJobs,
         };
     });
 };
@@ -255,6 +297,7 @@ const formatWaitedImportOutput = ({ jobs, summary, }) => {
                 updatedAt: '',
                 error: job.error,
                 exerciseSheetId: job.exerciseSheetId,
+                sheets: job.sheets,
             }),
             ...formatCliImportTranslationJobs(job.translationJobs),
         ]),

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 {
@@ -215,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({

package/dist/lib/user-jobs.js

@@ -17,6 +17,7 @@ export const serializeCliJob = (job) => {
         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,
@@ -28,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/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

@@ -60,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 |
 | --- | --- | --- | --- |
@@ -73,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)
@@ -142,6 +163,8 @@ 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.

package/package.json

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

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

@@ -40,6 +40,37 @@
       "type": "string",
       "enum": ["english", "hungarian", "german", "french", "spanish", "italian"]
     },
+    "componentId": {
+      "type": "string",
+      "pattern": "^[a-zA-Z0-9_-]{1,80}$"
+    },
+    "component": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["componentId", "description"],
+      "properties": {
+        "componentId": {
+          "$ref": "#/$defs/componentId"
+        },
+        "description": {
+          "$ref": "#/$defs/nonEmptyString"
+        },
+        "targetFolderPath": {
+          "$ref": "#/$defs/targetFolderPath"
+        },
+        "title": {
+          "$ref": "#/$defs/nonEmptyString"
+        },
+        "translateTo": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {
+            "$ref": "#/$defs/translateLanguage"
+          }
+        }
+      }
+    },
     "localSource": {
       "type": "object",
       "additionalProperties": false,
@@ -111,32 +142,57 @@
       ]
     },
     "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"
+      "oneOf": [
+        {
+          "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"
+              }
+            }
           }
         },
-        "sources": {
-          "type": "array",
-          "minItems": 1,
-          "items": {
-            "$ref": "#/$defs/source"
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["sources", "components"],
+          "properties": {
+            "sources": {
+              "type": "array",
+              "minItems": 1,
+              "items": {
+                "$ref": "#/$defs/source"
+              }
+            },
+            "components": {
+              "type": "array",
+              "minItems": 1,
+              "items": {
+                "$ref": "#/$defs/component"
+              }
+            }
           }
         }
-      }
+      ]
     }
   }
 }