@chalksurf/cli 0.1.0

package/dist/lib/session.js

@@ -0,0 +1,45 @@
+import { CliCommandError } from './cli-error.js';
+import { chalksurfBaseUrlEnvVar, chalksurfOrganizationIdEnvVar, chalksurfTokenEnvVar, resolveBaseUrl, resolveToken, } from './config-store.js';
+const normalizeOptionalString = (value) => {
+    const trimmedValue = value?.trim();
+    return trimmedValue ? trimmedValue : undefined;
+};
+export const mapApiErrorToCliError = (error) => {
+    const message = error instanceof Error ? error.message : 'Unknown API error';
+    if (message.includes('UNAUTHORIZED')) {
+        return new CliCommandError('Authentication failed. The CLI token is invalid or revoked.', 3);
+    }
+    return new CliCommandError(`API request failed: ${message}`, 5);
+};
+export const requireResolvedBaseUrl = ({ flagValue, env, config, }) => {
+    const resolvedBaseUrl = resolveBaseUrl({ flagValue, env, config });
+    if (!resolvedBaseUrl.value) {
+        throw new CliCommandError(`Missing ChalkSurf base URL. Pass --base-url, set ${chalksurfBaseUrlEnvVar}, or log in first.`, 2);
+    }
+    return resolvedBaseUrl;
+};
+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);
+    }
+    return resolvedToken;
+};
+export const resolveRequestedOrganizationId = ({ config, env, fallbackValue, flagValue, }) => {
+    return (normalizeOptionalString(flagValue) ??
+        normalizeOptionalString(fallbackValue) ??
+        normalizeOptionalString(env[chalksurfOrganizationIdEnvVar]) ??
+        normalizeOptionalString(config.organizationId));
+};
+export const formatUserIdentity = (profile) => {
+    if (profile.name && profile.email) {
+        return `${profile.name} <${profile.email}>`;
+    }
+    if (profile.email) {
+        return profile.email;
+    }
+    if (profile.name) {
+        return profile.name;
+    }
+    return profile.id;
+};

package/dist/lib/source-resolver.js

@@ -0,0 +1,210 @@
+import { createWriteStream } from 'node:fs';
+import { mkdtemp, 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';
+import { pipeline } from 'node:stream/promises';
+import pLimit from 'p-limit';
+import { CliCommandError } from './cli-error.js';
+const sourceResolutionExitCode = 4;
+const defaultMaxConcurrentUrlDownloads = 4;
+const createSourceResolutionError = (message) => {
+    return new CliCommandError(message, sourceResolutionExitCode);
+};
+const normalizeRelativePath = (relativePath) => {
+    const normalizedSegments = relativePath
+        .replaceAll('\\', '/')
+        .split('/')
+        .filter((segment) => segment.length > 0 && segment !== '.');
+    if (normalizedSegments.some((segment) => segment === '..')) {
+        throw createSourceResolutionError(`Relative path "${relativePath}" cannot contain "..".`);
+    }
+    const normalizedRelativePath = normalizedSegments.join('/');
+    if (!normalizedRelativePath) {
+        throw createSourceResolutionError('Relative path cannot be empty.');
+    }
+    return normalizedRelativePath;
+};
+const ensureExistingFile = async (filePath, label) => {
+    let fileStats;
+    try {
+        fileStats = await stat(filePath);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            throw createSourceResolutionError(`${label} "${filePath}" does not exist.`);
+        }
+        throw error;
+    }
+    if (!fileStats.isFile()) {
+        throw createSourceResolutionError(`${label} "${filePath}" is not a file.`);
+    }
+};
+const ensureExistingDirectory = async (directoryPath, label) => {
+    let directoryStats;
+    try {
+        directoryStats = await stat(directoryPath);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            throw createSourceResolutionError(`${label} "${directoryPath}" does not exist.`);
+        }
+        throw error;
+    }
+    if (!directoryStats.isDirectory()) {
+        throw createSourceResolutionError(`${label} "${directoryPath}" is not a directory.`);
+    }
+};
+const isContainedWithin = ({ childPath, parentPath }) => {
+    const relativePath = relative(parentPath, childPath);
+    if (!relativePath) {
+        return true;
+    }
+    return !relativePath.startsWith('..') && !isAbsolute(relativePath);
+};
+const collectFilesRecursively = async (directoryPath) => {
+    const directoryEntries = await readdir(directoryPath, { withFileTypes: true });
+    const sortedEntries = directoryEntries.sort((leftEntry, rightEntry) => leftEntry.name.localeCompare(rightEntry.name));
+    const filePaths = [];
+    for (const directoryEntry of sortedEntries) {
+        const entryPath = resolve(directoryPath, directoryEntry.name);
+        if (directoryEntry.isDirectory()) {
+            filePaths.push(...(await collectFilesRecursively(entryPath)));
+            continue;
+        }
+        if (directoryEntry.isFile()) {
+            filePaths.push(entryPath);
+        }
+    }
+    return filePaths;
+};
+const deriveRelativePathFromUrl = (url) => {
+    const fileName = basename(decodeURIComponent(url.pathname));
+    if (!fileName) {
+        throw createSourceResolutionError(`URL source "${url.toString()}" does not include a file name. Pass a relative path explicitly.`);
+    }
+    return fileName;
+};
+const resolveLocalFileSource = async ({ source, cwd, }) => {
+    const resolvedPath = resolve(cwd, source.path);
+    await ensureExistingFile(resolvedPath, 'Local source');
+    const relativePath = normalizeRelativePath(source.relativePath ?? basename(resolvedPath));
+    return [
+        {
+            kind: 'local',
+            input: source.path,
+            filePath: resolvedPath,
+            fileName: basename(relativePath),
+            relativePath,
+        },
+    ];
+};
+const resolveDirectorySource = async ({ source, cwd, }) => {
+    const resolvedDirectoryPath = resolve(cwd, source.path);
+    const resolvedRelativeRoot = resolve(cwd, source.relativeRoot ?? source.path);
+    await ensureExistingDirectory(resolvedDirectoryPath, 'Directory source');
+    await ensureExistingDirectory(resolvedRelativeRoot, 'Directory relativeRoot');
+    if (!isContainedWithin({ childPath: resolvedDirectoryPath, parentPath: resolvedRelativeRoot })) {
+        throw createSourceResolutionError(`Directory source "${resolvedDirectoryPath}" is not contained within relativeRoot "${resolvedRelativeRoot}".`);
+    }
+    const filePaths = await collectFilesRecursively(resolvedDirectoryPath);
+    if (filePaths.length === 0) {
+        throw createSourceResolutionError(`Directory source "${resolvedDirectoryPath}" does not contain any files.`);
+    }
+    return filePaths.map((filePath) => {
+        const relativePath = normalizeRelativePath(relative(resolvedRelativeRoot, filePath));
+        return {
+            kind: 'local',
+            input: filePath,
+            filePath,
+            fileName: basename(relativePath),
+            relativePath,
+        };
+    });
+};
+const resolveUrlSource = async ({ source, fetchImpl, }) => {
+    let parsedUrl;
+    try {
+        parsedUrl = new URL(source.url);
+    }
+    catch {
+        throw createSourceResolutionError(`URL source "${source.url}" is not a valid URL.`);
+    }
+    if (!['http:', 'https:'].includes(parsedUrl.protocol)) {
+        throw createSourceResolutionError(`URL source "${source.url}" must use http or https.`);
+    }
+    const relativePath = normalizeRelativePath(source.relativePath ?? deriveRelativePathFromUrl(parsedUrl));
+    const downloadDirectoryPath = await mkdtemp(resolve(tmpdir(), 'chalksurf-cli-source-'));
+    const downloadedFilePath = resolve(downloadDirectoryPath, basename(relativePath));
+    try {
+        const response = await fetchImpl(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.`);
+        }
+        await pipeline(Readable.fromWeb(response.body), createWriteStream(downloadedFilePath));
+        return [
+            {
+                kind: 'url',
+                input: source.url,
+                filePath: downloadedFilePath,
+                fileName: basename(relativePath),
+                relativePath,
+                cleanupPath: downloadDirectoryPath,
+            },
+        ];
+    }
+    catch (error) {
+        await rm(downloadDirectoryPath, { force: true, recursive: true });
+        if (error instanceof CliCommandError) {
+            throw error;
+        }
+        const message = error instanceof Error ? error.message : 'Unknown download error';
+        throw createSourceResolutionError(`Failed to download "${source.url}": ${message}`);
+    }
+};
+const assertUniqueRelativePaths = (resolvedSources) => {
+    const seenRelativePaths = new Set();
+    for (const resolvedSource of resolvedSources) {
+        if (seenRelativePaths.has(resolvedSource.relativePath)) {
+            throw createSourceResolutionError(`Resolved sources contain duplicate relative path "${resolvedSource.relativePath}".`);
+        }
+        seenRelativePaths.add(resolvedSource.relativePath);
+    }
+};
+export const cleanupResolvedSources = async (resolvedSources) => {
+    const cleanupPaths = Array.from(new Set(resolvedSources
+        .map((resolvedSource) => resolvedSource.cleanupPath)
+        .filter((cleanupPath) => cleanupPath !== undefined)));
+    await Promise.all(cleanupPaths.map(async (cleanupPath) => {
+        await rm(cleanupPath, { force: true, recursive: true });
+    }));
+};
+export const resolveSources = async ({ sources, cwd = process.cwd(), fetchImpl = fetch, maxConcurrentUrlDownloads = defaultMaxConcurrentUrlDownloads, }) => {
+    const limitUrlDownloads = pLimit(Math.max(1, maxConcurrentUrlDownloads));
+    const settledSourceGroups = await Promise.allSettled(sources.map(async (source) => {
+        if (source.kind === 'local') {
+            return await resolveLocalFileSource({ source, cwd });
+        }
+        if (source.kind === 'directory') {
+            return await resolveDirectorySource({ source, cwd });
+        }
+        return await limitUrlDownloads(() => resolveUrlSource({ source, fetchImpl }));
+    }));
+    const resolvedSources = settledSourceGroups.flatMap((result) => (result.status === 'fulfilled' ? result.value : []));
+    const firstRejectedResult = settledSourceGroups.find((result) => result.status === 'rejected');
+    if (firstRejectedResult?.status === 'rejected') {
+        await cleanupResolvedSources(resolvedSources);
+        throw firstRejectedResult.reason;
+    }
+    try {
+        assertUniqueRelativePaths(resolvedSources);
+        return resolvedSources;
+    }
+    catch (error) {
+        await cleanupResolvedSources(resolvedSources);
+        throw error;
+    }
+};

package/dist/lib/user-jobs.js

@@ -0,0 +1,78 @@
+import { CliCommandError } from './cli-error.js';
+import { mapApiErrorToCliError } from './session.js';
+const isTerminalJob = (job) => {
+    return ['completed', 'failed'].includes(job.status);
+};
+export const serializeCliJob = (job) => {
+    return {
+        id: job.id,
+        status: job.status,
+        type: job.type,
+        createdAt: job.createdAt,
+        updatedAt: job.updatedAt,
+        error: job.result?.error,
+        exerciseId: job.result?.exerciseId,
+        exerciseIds: job.result?.exerciseIds,
+        exerciseSheetId: job.result?.exerciseSheetId,
+        resultCode: job.result?.resultCode,
+    };
+};
+export const formatCliJobSummary = (job) => {
+    if (job.status === 'completed') {
+        if (job.exerciseSheetId) {
+            return `${job.id} completed -> ${job.exerciseSheetId}`;
+        }
+        if (job.exerciseId) {
+            return `${job.id} completed -> ${job.exerciseId}`;
+        }
+        return `${job.id} completed`;
+    }
+    if (job.status === 'failed') {
+        return `${job.id} failed -> ${job.error ?? 'Unknown error'}`;
+    }
+    return `${job.id} ${job.status}`;
+};
+export const getWaitExitCode = ({ jobs, timedOut }) => {
+    if (timedOut) {
+        return 6;
+    }
+    if (jobs.some((job) => job.status === 'failed')) {
+        return 7;
+    }
+    return 0;
+};
+export const waitForCliJobs = async ({ getUserJob, jobIds, maxPollIntervalMs = 5000, now, sleep, timeoutMs = 300000, }) => {
+    const startedAt = now();
+    let nextPollDelayMs = 1000;
+    let latestJobs = [];
+    while (true) {
+        try {
+            latestJobs = await Promise.all(jobIds.map(async (jobId) => await getUserJob(jobId)));
+        }
+        catch (error) {
+            throw mapApiErrorToCliError(error);
+        }
+        if (latestJobs.every(isTerminalJob)) {
+            return {
+                jobs: latestJobs.map(serializeCliJob),
+                timedOut: false,
+            };
+        }
+        const elapsedMs = now() - startedAt;
+        if (elapsedMs >= timeoutMs) {
+            return {
+                jobs: latestJobs.map(serializeCliJob),
+                timedOut: true,
+            };
+        }
+        const remainingMs = timeoutMs - elapsedMs;
+        await sleep(Math.max(0, Math.min(nextPollDelayMs, remainingMs)));
+        nextPollDelayMs = Math.min(nextPollDelayMs * 2, maxPollIntervalMs);
+    }
+};
+export const throwSilentExitCode = (exitCode) => {
+    if (exitCode === 0) {
+        return;
+    }
+    throw new CliCommandError('', exitCode, false);
+};

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@chalksurf/cli",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "bin": {
+    "chalksurf": "dist/bin/chalksurf.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/knowledge-maps/chalksurf.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "dev": "node --import tsx ./src/bin/chalksurf.ts",
+    "prepack": "npm run build",
+    "build": "tsc --project ./tsconfig.build.json",
+    "lint": "eslint .",
+    "type-check": "tsc --noEmit --project ./tsconfig.json",
+    "test": "vitest --config ./vitest.config.ts --run",
+    "smoke-pack": "node --import tsx ./scripts/smoke-pack.ts"
+  },
+  "dependencies": {
+    "p-limit": "^6.2.0",
+    "yargs": "^17.7.2"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.1",
+    "@types/yargs": "^17.0.35",
+    "tsx": "^4.20.6",
+    "typescript": "^5.0.0",
+    "vitest": "^4.1.2"
+  }
+}