@chalksurf/cli 0.1.0 → 0.2.1

package/dist/lib/manifest.js

@@ -1,6 +1,8 @@
 import { readFile, stat } from 'node:fs/promises';
 import { resolve } from 'node:path';
+import { z } from 'zod';
 import { CliCommandError } from './cli-error.js';
+import { translationLanguages } from './translation-languages.js';
 const isObject = (value) => {
     return typeof value === 'object' && value !== null;
 };
@@ -11,6 +13,88 @@ const normalizeOptionalString = (value) => {
     const normalizedValue = value.trim();
     return normalizedValue.length > 0 ? normalizedValue : undefined;
 };
+const translationLanguageListSchema = z
+    .array(z.enum(translationLanguages))
+    .min(1, { message: 'translateTo must include at least one language.' })
+    .refine((languages) => new Set(languages).size === languages.length, {
+    message: 'translateTo languages must be unique.',
+});
+const parseTranslateTo = ({ value, label }) => {
+    if (value == null) {
+        return undefined;
+    }
+    const parsedLanguages = translationLanguageListSchema.safeParse(value);
+    if (!parsedLanguages.success) {
+        const issue = parsedLanguages.error.issues[0];
+        throw new CliCommandError(`${label} has invalid translateTo: ${issue?.message ?? 'Invalid languages.'}`, 2);
+    }
+    return parsedLanguages.data;
+};
+const parseManifestObject = (manifestText) => {
+    let parsedManifest;
+    try {
+        parsedManifest = JSON.parse(manifestText);
+    }
+    catch {
+        throw new CliCommandError('Manifest must be valid JSON.', 2);
+    }
+    if (!isObject(parsedManifest)) {
+        throw new CliCommandError('Manifest must be a JSON object.', 2);
+    }
+    return parsedManifest;
+};
+const parseSourceManifestObject = (manifestText) => {
+    const parsedManifest = parseManifestObject(manifestText);
+    if (!Array.isArray(parsedManifest.sources) || parsedManifest.sources.length === 0) {
+        throw new CliCommandError('Manifest must include a non-empty sources array.', 2);
+    }
+    return parsedManifest;
+};
+const isValidTargetFolderPath = (value) => {
+    const normalizedSegments = value
+        .replaceAll('\\', '/')
+        .split('/')
+        .filter((segment) => segment.length > 0);
+    return normalizedSegments.length > 0 && normalizedSegments.every((segment) => segment !== '.' && segment !== '..');
+};
+const parseTargetFolderPath = ({ value, label }) => {
+    if (value === null) {
+        return null;
+    }
+    const normalizedValue = normalizeOptionalString(value);
+    if (!normalizedValue) {
+        throw new CliCommandError(`${label} must include targetFolderPath as a string or null.`, 2);
+    }
+    if (!isValidTargetFolderPath(normalizedValue)) {
+        throw new CliCommandError(`${label} targetFolderPath must be a normalized folder path without "." or ".." segments.`, 2);
+    }
+    return normalizedValue;
+};
+const parseManifestMetadata = ({ parsedManifest, topLevelFields, }) => {
+    const wait = typeof parsedManifest.wait === 'boolean' ? parsedManifest.wait : undefined;
+    return {
+        organizationId: normalizeOptionalString(parsedManifest.organizationId),
+        wait,
+        ...(topLevelFields.includes('exerciseId')
+            ? { exerciseId: normalizeOptionalString(parsedManifest.exerciseId) }
+            : {}),
+        ...(topLevelFields.includes('exerciseSheetId')
+            ? { exerciseSheetId: normalizeOptionalString(parsedManifest.exerciseSheetId) }
+            : {}),
+    };
+};
+const assertUniqueSourceIds = (sources) => {
+    const seenSourceIds = new Set();
+    for (const source of sources) {
+        if (!source.sourceId) {
+            continue;
+        }
+        if (seenSourceIds.has(source.sourceId)) {
+            throw new CliCommandError(`Manifest sourceId "${source.sourceId}" must be unique.`, 2);
+        }
+        seenSourceIds.add(source.sourceId);
+    }
+};
 const isInteractiveStdin = (stdin) => {
     return stdin.isTTY === true;
 };
@@ -21,11 +105,15 @@ const readTextFromStdin = async (stdin) => {
     }
     return text;
 };
-const parseManifestSource = (value, index) => {
+const parseBaseManifestSource = (value, index) => {
     if (!isObject(value)) {
         throw new CliCommandError(`Manifest source at index ${index} must be an object.`, 2);
     }
     const kind = normalizeOptionalString(value.kind);
+    const sourceId = normalizeOptionalString(value.sourceId);
+    if ('title' in value || 'translateTo' in value) {
+        throw new CliCommandError(`Manifest source at index ${index} cannot include title or translateTo for this command.`, 2);
+    }
     if (kind === 'local') {
         const path = normalizeOptionalString(value.path);
         if (!path) {
@@ -35,6 +123,7 @@ const parseManifestSource = (value, index) => {
             kind: 'local',
             path,
             relativePath: normalizeOptionalString(value.relativePath),
+            sourceId,
         };
     }
     if (kind === 'directory') {
@@ -46,6 +135,7 @@ const parseManifestSource = (value, index) => {
             kind: 'directory',
             path,
             relativeRoot: normalizeOptionalString(value.relativeRoot),
+            sourceId,
         };
     }
     if (kind === 'url') {
@@ -57,35 +147,85 @@ const parseManifestSource = (value, index) => {
             kind: 'url',
             url,
             relativePath: normalizeOptionalString(value.relativePath),
+            sourceId,
         };
     }
     throw new CliCommandError(`Manifest source at index ${index} has unsupported kind "${String(value.kind)}".`, 2);
 };
-const parseManifest = (manifestText) => {
-    let parsedManifest;
-    try {
-        parsedManifest = JSON.parse(manifestText);
-    }
-    catch {
-        throw new CliCommandError('Manifest must be valid JSON.', 2);
-    }
-    if (!isObject(parsedManifest)) {
-        throw new CliCommandError('Manifest must be a JSON object.', 2);
+const parseExerciseImportManifest = (manifestText) => {
+    const parsedManifest = parseSourceManifestObject(manifestText);
+    const sources = parsedManifest.sources.map((source, index) => parseBaseManifestSource(source, index));
+    assertUniqueSourceIds(sources);
+    return {
+        ...parseManifestMetadata({
+            parsedManifest,
+            topLevelFields: ['exerciseSheetId'],
+        }),
+        sources,
+    };
+};
+const parseExerciseSolutionImportManifest = (manifestText) => {
+    const parsedManifest = parseSourceManifestObject(manifestText);
+    const sources = parsedManifest.sources.map((source, index) => parseBaseManifestSource(source, index));
+    assertUniqueSourceIds(sources);
+    return {
+        ...parseManifestMetadata({
+            parsedManifest,
+            topLevelFields: ['exerciseId'],
+        }),
+        sources,
+    };
+};
+const parseSheetImportManifest = (manifestText) => {
+    const parsedManifest = parseManifestObject(manifestText);
+    if ('sources' in parsedManifest) {
+        throw new CliCommandError('Sheet import manifests must use top-level sheets[]. Top-level sources[] is no longer supported.', 2);
     }
-    if (!Array.isArray(parsedManifest.sources) || parsedManifest.sources.length === 0) {
-        throw new CliCommandError('Manifest must include a non-empty sources array.', 2);
+    if (!Array.isArray(parsedManifest.sheets) || parsedManifest.sheets.length === 0) {
+        throw new CliCommandError('Manifest must include a non-empty sheets array.', 2);
     }
-    const wait = typeof parsedManifest.wait === 'boolean' ? parsedManifest.wait : undefined;
+    const sources = [];
+    const sheetGroups = [];
+    parsedManifest.sheets.forEach((sheetValue, sheetIndex) => {
+        if (!isObject(sheetValue)) {
+            throw new CliCommandError(`Manifest sheet at index ${sheetIndex} must be an object.`, 2);
+        }
+        if (!Array.isArray(sheetValue.sources) || sheetValue.sources.length === 0) {
+            throw new CliCommandError(`Manifest sheet at index ${sheetIndex} must include a non-empty sources array.`, 2);
+        }
+        const sourceInputIndexes = sheetValue.sources.map((sourceValue) => {
+            const flattenedSourceIndex = sources.length;
+            const parsedSource = parseBaseManifestSource(sourceValue, flattenedSourceIndex);
+            sources.push(parsedSource);
+            return flattenedSourceIndex;
+        });
+        sheetGroups.push({
+            sourceInputIndexes,
+            targetFolderPath: parseTargetFolderPath({
+                value: sheetValue.targetFolderPath,
+                label: `Manifest sheet at index ${sheetIndex}`,
+            }),
+            title: normalizeOptionalString(sheetValue.title),
+            translateTo: parseTranslateTo({
+                value: sheetValue.translateTo,
+                label: `Manifest sheet at index ${sheetIndex}`,
+            }),
+        });
+    });
+    assertUniqueSourceIds(sources);
     return {
-        organizationId: normalizeOptionalString(parsedManifest.organizationId),
-        wait,
-        sources: parsedManifest.sources.map((source, index) => parseManifestSource(source, index)),
+        ...parseManifestMetadata({
+            parsedManifest,
+            topLevelFields: [],
+        }),
+        sources,
+        sheetGroups,
     };
 };
-export const loadSheetImportManifest = async ({ cwd, manifestPath, stdin, }) => {
+const loadManifest = async ({ cwd, manifestPath, parseManifest, stdin, }) => {
     if (manifestPath === '-') {
         if (isInteractiveStdin(stdin)) {
-            throw new CliCommandError('No manifest was piped on stdin. Pipe JSON into "chalksurf sheet import --manifest -".', 2);
+            throw new CliCommandError('No manifest was piped on stdin. Pipe JSON into "--manifest -".', 2);
         }
         return parseManifest(await readTextFromStdin(stdin));
     }
@@ -105,3 +245,27 @@ export const loadSheetImportManifest = async ({ cwd, manifestPath, stdin, }) =>
     }
     return parseManifest(await readFile(resolvedManifestPath, 'utf8'));
 };
+export const loadExerciseImportManifest = async ({ cwd, manifestPath, stdin, }) => {
+    return await loadManifest({
+        cwd,
+        manifestPath,
+        parseManifest: parseExerciseImportManifest,
+        stdin,
+    });
+};
+export const loadExerciseSolutionImportManifest = async ({ cwd, manifestPath, stdin, }) => {
+    return await loadManifest({
+        cwd,
+        manifestPath,
+        parseManifest: parseExerciseSolutionImportManifest,
+        stdin,
+    });
+};
+export const loadSheetImportManifest = async ({ cwd, manifestPath, stdin, }) => {
+    return await loadManifest({
+        cwd,
+        manifestPath,
+        parseManifest: parseSheetImportManifest,
+        stdin,
+    });
+};

package/dist/lib/output.js

@@ -1,3 +1,4 @@
+const cliJsonSchemaVersion = 'v1';
 const ensureTrailingNewline = (value) => {
     return value.endsWith('\n') ? value : `${value}\n`;
 };
@@ -5,16 +6,48 @@ const writeLine = (writer, value) => {
     writer.write(ensureTrailingNewline(value));
 };
 export const createOutput = ({ json, stdout, stderr, }) => {
+    let warnings = [];
+    const consumeWarnings = () => {
+        const nextWarnings = warnings;
+        warnings = [];
+        return nextWarnings;
+    };
     return {
-        print: (value, humanFormatter) => {
+        json,
+        print: (value, humanFormatter, options) => {
             if (json) {
-                writeLine(stdout, JSON.stringify(value, null, 2));
+                writeLine(stdout, JSON.stringify({
+                    schemaVersion: cliJsonSchemaVersion,
+                    command: options.command,
+                    ok: options.ok ?? true,
+                    result: value,
+                    ...(options.error ? { error: options.error } : {}),
+                    warnings: consumeWarnings(),
+                }, null, 2));
                 return;
             }
             const message = typeof humanFormatter === 'function' ? humanFormatter(value) : humanFormatter;
             writeLine(stdout, message);
         },
+        printError: ({ command, error, result }) => {
+            if (json) {
+                writeLine(stdout, JSON.stringify({
+                    schemaVersion: cliJsonSchemaVersion,
+                    command,
+                    ok: false,
+                    ...(result === undefined ? {} : { result }),
+                    error,
+                    warnings: consumeWarnings(),
+                }, null, 2));
+                return;
+            }
+            writeLine(stderr, error.message);
+        },
         info: (message) => {
+            if (json) {
+                warnings.push(message);
+                return;
+            }
             writeLine(stderr, message);
         },
         error: (message) => {

package/dist/lib/prompt-secret.js

@@ -0,0 +1,32 @@
+import { createInterface } from 'node:readline/promises';
+import { Writable } from 'node:stream';
+export const createPromptSecret = ({ input = process.stdin, output = process.stderr, } = {}) => {
+    return async (message) => {
+        let muted = false;
+        const maskedOutput = new Writable({
+            write(chunk, encoding, callback) {
+                if (!muted) {
+                    output.write(chunk, encoding);
+                }
+                callback();
+            },
+        });
+        const readline = createInterface({
+            input,
+            output: maskedOutput,
+            terminal: true,
+        });
+        try {
+            output.write(message);
+            muted = true;
+            const value = await readline.question('');
+            muted = false;
+            output.write('\n');
+            return value.trim();
+        }
+        finally {
+            muted = false;
+            readline.close();
+        }
+    };
+};

package/dist/lib/session.js

@@ -21,7 +21,7 @@ export const requireResolvedBaseUrl = ({ flagValue, env, config, }) => {
 export const requireResolvedToken = ({ env, config, }) => {
     const resolvedToken = resolveToken({ env, config });
     if (!resolvedToken.value) {
-        throw new CliCommandError(`Not authenticated. Set ${chalksurfTokenEnvVar} or run "chalksurf auth login --with-token".`, 3);
+        throw new CliCommandError(`Not authenticated. Set ${chalksurfTokenEnvVar} or run "chalksurf auth login".`, 3);
     }
     return resolvedToken;
 };

package/dist/lib/source-resolver.js

@@ -1,5 +1,5 @@
 import { createWriteStream } from 'node:fs';
-import { mkdtemp, readdir, rm, stat } from 'node:fs/promises';
+import { mkdtemp, open, readdir, rm, stat } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { basename, isAbsolute, relative, resolve } from 'node:path';
 import { Readable } from 'node:stream';
@@ -8,6 +8,8 @@ import pLimit from 'p-limit';
 import { CliCommandError } from './cli-error.js';
 const sourceResolutionExitCode = 4;
 const defaultMaxConcurrentUrlDownloads = 4;
+const htmlSniffBytes = 1024;
+const genericMimeTypes = new Set(['application/octet-stream', 'binary/octet-stream']);
 const createSourceResolutionError = (message) => {
     return new CliCommandError(message, sourceResolutionExitCode);
 };
@@ -85,7 +87,44 @@ const deriveRelativePathFromUrl = (url) => {
     }
     return fileName;
 };
-const resolveLocalFileSource = async ({ source, cwd, }) => {
+const normalizeMimeType = (contentTypeHeaderValue) => {
+    const mimeType = contentTypeHeaderValue?.split(';', 1)[0]?.trim().toLowerCase();
+    return mimeType || undefined;
+};
+const stripLeadingHtmlComments = (value) => {
+    let normalizedValue = value.trimStart();
+    while (normalizedValue.startsWith('<!--')) {
+        const commentEndIndex = normalizedValue.indexOf('-->');
+        if (commentEndIndex === -1) {
+            return normalizedValue;
+        }
+        normalizedValue = normalizedValue.slice(commentEndIndex + 3).trimStart();
+    }
+    return normalizedValue;
+};
+const looksLikeHtmlDocument = (value) => {
+    const normalizedValue = stripLeadingHtmlComments(value.replace(/^\uFEFF/, ''));
+    return /^<(?:!doctype html|html|head|body)\b/i.test(normalizedValue);
+};
+const sniffMimeType = async ({ filePath, responseMimeType }) => {
+    if (responseMimeType && !genericMimeTypes.has(responseMimeType)) {
+        return responseMimeType;
+    }
+    const fileHandle = await open(filePath, 'r');
+    try {
+        const buffer = Buffer.alloc(htmlSniffBytes);
+        const { bytesRead } = await fileHandle.read(buffer, 0, buffer.length, 0);
+        const filePrefix = buffer.subarray(0, bytesRead).toString('utf8');
+        if (looksLikeHtmlDocument(filePrefix)) {
+            return 'text/html';
+        }
+        return responseMimeType;
+    }
+    finally {
+        await fileHandle.close();
+    }
+};
+const resolveLocalFileSource = async ({ source, cwd, sourceInputIndex, }) => {
     const resolvedPath = resolve(cwd, source.path);
     await ensureExistingFile(resolvedPath, 'Local source');
     const relativePath = normalizeRelativePath(source.relativePath ?? basename(resolvedPath));
@@ -96,10 +135,12 @@ const resolveLocalFileSource = async ({ source, cwd, }) => {
             filePath: resolvedPath,
             fileName: basename(relativePath),
             relativePath,
+            sourceInputIndex,
+            sourceInput: source,
         },
     ];
 };
-const resolveDirectorySource = async ({ source, cwd, }) => {
+const resolveDirectorySource = async ({ source, cwd, sourceInputIndex, }) => {
     const resolvedDirectoryPath = resolve(cwd, source.path);
     const resolvedRelativeRoot = resolve(cwd, source.relativeRoot ?? source.path);
     await ensureExistingDirectory(resolvedDirectoryPath, 'Directory source');
@@ -119,10 +160,12 @@ const resolveDirectorySource = async ({ source, cwd, }) => {
             filePath,
             fileName: basename(relativePath),
             relativePath,
+            sourceInputIndex,
+            sourceInput: source,
         };
     });
 };
-const resolveUrlSource = async ({ source, fetchImpl, }) => {
+const resolveUrlSource = async ({ source, sourceInputIndex, }) => {
     let parsedUrl;
     try {
         parsedUrl = new URL(source.url);
@@ -137,22 +180,30 @@ const resolveUrlSource = async ({ source, fetchImpl, }) => {
     const downloadDirectoryPath = await mkdtemp(resolve(tmpdir(), 'chalksurf-cli-source-'));
     const downloadedFilePath = resolve(downloadDirectoryPath, basename(relativePath));
     try {
-        const response = await fetchImpl(source.url);
+        const response = await fetch(source.url);
         if (!response.ok) {
             throw createSourceResolutionError(`Failed to download "${source.url}": HTTP ${response.status}${response.statusText ? ` ${response.statusText}` : ''}.`);
         }
         if (!response.body) {
             throw createSourceResolutionError(`Failed to download "${source.url}": response body was empty.`);
         }
+        const responseMimeType = normalizeMimeType(response.headers.get('content-type'));
         await pipeline(Readable.fromWeb(response.body), createWriteStream(downloadedFilePath));
+        const mimeType = await sniffMimeType({
+            filePath: downloadedFilePath,
+            responseMimeType,
+        });
         return [
             {
                 kind: 'url',
                 input: source.url,
                 filePath: downloadedFilePath,
                 fileName: basename(relativePath),
+                mimeType,
                 relativePath,
+                sourceInputIndex,
                 cleanupPath: downloadDirectoryPath,
+                sourceInput: source,
             },
         ];
     }
@@ -182,16 +233,27 @@ export const cleanupResolvedSources = async (resolvedSources) => {
         await rm(cleanupPath, { force: true, recursive: true });
     }));
 };
-export const resolveSources = async ({ sources, cwd = process.cwd(), fetchImpl = fetch, maxConcurrentUrlDownloads = defaultMaxConcurrentUrlDownloads, }) => {
+export const resolveSources = async ({ sources, cwd = process.cwd(), maxConcurrentUrlDownloads = defaultMaxConcurrentUrlDownloads, }) => {
     const limitUrlDownloads = pLimit(Math.max(1, maxConcurrentUrlDownloads));
-    const settledSourceGroups = await Promise.allSettled(sources.map(async (source) => {
+    const settledSourceGroups = await Promise.allSettled(sources.map(async (source, sourceInputIndex) => {
         if (source.kind === 'local') {
-            return await resolveLocalFileSource({ source, cwd });
+            return await resolveLocalFileSource({
+                source: source,
+                cwd,
+                sourceInputIndex,
+            });
         }
         if (source.kind === 'directory') {
-            return await resolveDirectorySource({ source, cwd });
+            return await resolveDirectorySource({
+                source: source,
+                cwd,
+                sourceInputIndex,
+            });
         }
-        return await limitUrlDownloads(() => resolveUrlSource({ source, fetchImpl }));
+        return await limitUrlDownloads(() => resolveUrlSource({
+            source: source,
+            sourceInputIndex,
+        }));
     }));
     const resolvedSources = settledSourceGroups.flatMap((result) => (result.status === 'fulfilled' ? result.value : []));
     const firstRejectedResult = settledSourceGroups.find((result) => result.status === 'rejected');

package/dist/lib/translation-languages.js

@@ -0,0 +1 @@
+export const translationLanguages = ['english', 'hungarian', 'german', 'french', 'spanish', 'italian'];

package/dist/lib/user-jobs.js

@@ -1,4 +1,4 @@
-import { CliCommandError } from './cli-error.js';
+import { CliCommandError, createSerializableCliError } from './cli-error.js';
 import { mapApiErrorToCliError } from './session.js';
 const isTerminalJob = (job) => {
     return ['completed', 'failed'].includes(job.status);
@@ -41,6 +41,21 @@ export const getWaitExitCode = ({ jobs, timedOut }) => {
     }
     return 0;
 };
+export const getWaitError = ({ jobs, timedOut }) => {
+    if (timedOut) {
+        return createSerializableCliError({
+            exitCode: 6,
+            message: 'Timed out before all jobs completed.',
+        });
+    }
+    if (jobs.some((job) => job.status === 'failed')) {
+        return createSerializableCliError({
+            exitCode: 7,
+            message: 'One or more jobs failed.',
+        });
+    }
+    return undefined;
+};
 export const waitForCliJobs = async ({ getUserJob, jobIds, maxPollIntervalMs = 5000, now, sleep, timeoutMs = 300000, }) => {
     const startedAt = now();
     let nextPollDelayMs = 1000;