@chalksurf/cli 0.1.0

package/README.md

@@ -0,0 +1,135 @@
+# `@chalksurf/cli`
+
+Publishable Chalksurf CLI package.
+
+Current internal release line: `0.1.0`. Expect breaking changes while the CLI is still only used internally.
+
+Current milestone scope:
+
+- package skeleton and build output
+- `chalksurf --help`
+- `chalksurf --version`
+- `chalksurf auth login --with-token`
+- `chalksurf auth status`
+- `chalksurf auth logout`
+- `chalksurf org list`
+- `chalksurf org use <organization-id>`
+- `chalksurf sheet import [sources...]`
+- `chalksurf job get <job-id>`
+- `chalksurf job wait <job-id> [<job-id>...]`
+- shared output helpers
+- shared HTTP client wrapper
+- secure local config persistence for CLI auth
+- source resolution for local files, directories, and URLs
+- manifest-driven imports and optional job waiting
+
+## Installation
+
+Run the published CLI without a global install:
+
+```bash
+npx @chalksurf/cli@0.1.0 --help
+```
+
+Install it globally when you want a persistent local binary:
+
+```bash
+npm install -g @chalksurf/cli@0.1.0
+chalksurf --version
+```
+
+## Usage
+
+Pipe a CLI token into the login command:
+
+```bash
+printf '%s' "$CHALKSURF_TOKEN" | chalksurf auth login --with-token --base-url https://api.chalksurf.com
+```
+
+Check the current session:
+
+```bash
+chalksurf auth status
+chalksurf org list
+```
+
+Select a default organization:
+
+```bash
+chalksurf org use org_123
+```
+
+For headless or CI usage, prefer environment variables:
+
+```bash
+export CHALKSURF_BASE_URL=https://api.chalksurf.com
+export CHALKSURF_TOKEN=cs_cli_...
+export CHALKSURF_ORGANIZATION_ID=org_123
+chalksurf auth status --json
+```
+
+Use the published package directly in agent or CI runs when you do not want a global install:
+
+```bash
+CHALKSURF_BASE_URL=https://api.chalksurf.com \
+CHALKSURF_TOKEN=cs_cli_... \
+CHALKSURF_ORGANIZATION_ID=org_123 \
+npx @chalksurf/cli@0.1.0 auth status --json
+```
+
+Import a local file:
+
+```bash
+chalksurf sheet import ./fixtures/algebra.pdf
+```
+
+Import a URL and override the stored default organization for this run:
+
+```bash
+chalksurf sheet import https://example.com/trig.docx \
+  --relative-path Imported/trig.docx \
+  --organization org_123
+```
+
+Import from a manifest and wait for the jobs to finish:
+
+```bash
+cat import.json | chalksurf sheet import --manifest - --wait --json
+```
+
+Wait on an existing job:
+
+```bash
+chalksurf job get job_123 --json
+chalksurf job wait job_123 job_124 --json
+```
+
+## Local And Staging Testing
+
+Use separate config files per environment so local and staging tokens do not overwrite each other:
+
+```bash
+npm run cli-dev -- --help
+```
+
+Run the CLI directly from source during local development:
+
+```bash
+export CHALKSURF_CONFIG_PATH=/tmp/chalksurf-local.json
+printf '%s' "$LOCAL_CLI_TOKEN" | npm run cli-dev -- auth login --with-token --base-url http://localhost:8080
+npm run cli-dev -- auth status --json
+npm run cli-dev -- org list --json
+npm run cli-dev -- sheet import ./fixtures/algebra.pdf --wait --json
+npm run cli-dev -- job get job_123 --json
+```
+
+```bash
+export CHALKSURF_CONFIG_PATH=/tmp/chalksurf-staging.json
+printf '%s' "$STAGING_CLI_TOKEN" | npm run cli-dev -- auth login --with-token --base-url https://staging-api.chalksurf.com
+npm run cli-dev -- auth status --json
+npm run cli-dev -- org list --json
+npm run cli-dev -- sheet import https://example.com/worksheet.docx --relative-path Imported/worksheet.docx --json
+npm run cli-dev -- job wait job_123 --json
+```
+
+For short-lived agent runs, skip local persistence and inject credentials through environment variables instead.

package/dist/bin/chalksurf.js

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+import { readFileSync, realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { hideBin } from 'yargs/helpers';
+import yargs from 'yargs/yargs';
+import { registerAuthCommands } from '../commands/auth.js';
+import { registerJobCommands } from '../commands/job.js';
+import { registerOrgCommands } from '../commands/org.js';
+import { registerSheetCommands } from '../commands/sheet.js';
+import { CliCommandError } from '../lib/cli-error.js';
+import { createConfigStore } from '../lib/config-store.js';
+import { createOutput } from '../lib/output.js';
+const packageJson = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8'));
+const createCli = ({ cwd, configPath, env, fetchImpl, now, output, sleep, stdin, }) => {
+    const commandContext = {
+        cwd,
+        configStore: createConfigStore({ configPath, env }),
+        env,
+        fetchImpl,
+        now,
+        output,
+        sleep,
+        stdin,
+    };
+    return yargs()
+        .scriptName('chalksurf')
+        .usage('$0 <command> [options]')
+        .version(false)
+        .option('json', {
+        type: 'boolean',
+        default: false,
+        describe: 'Write machine-readable JSON to stdout',
+    })
+        .option('base-url', {
+        type: 'string',
+        global: true,
+        describe: 'Base URL of the ChalkSurf API',
+    })
+        .option('organization', {
+        type: 'string',
+        global: true,
+        describe: 'Organization ID to use for this command',
+    })
+        .option('version', {
+        type: 'boolean',
+        alias: 'v',
+        describe: 'Show the CLI version',
+    })
+        .command('auth <subcommand>', 'Authentication commands', (authYargs) => registerAuthCommands(authYargs, commandContext), () => { })
+        .command('org <subcommand>', 'Organization commands', (orgYargs) => registerOrgCommands(orgYargs, commandContext), () => { })
+        .command('sheet <subcommand>', 'Exercise sheet commands', (sheetYargs) => registerSheetCommands(sheetYargs, commandContext), () => { })
+        .command('job <subcommand>', 'Job commands', (jobYargs) => registerJobCommands(jobYargs, commandContext), () => { })
+        .help()
+        .strict()
+        .exitProcess(false);
+};
+const hasFlag = (argv, flags) => {
+    return argv.some((argument) => flags.includes(argument));
+};
+export const runCli = async ({ argv, cwd = process.cwd(), configPath, env = process.env, fetchImpl = fetch, nowImpl = Date.now, sleepImpl = (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)), stdin = process.stdin, stdout = process.stdout, stderr = process.stderr, }) => {
+    const output = createOutput({
+        json: hasFlag(argv, ['--json']),
+        stdout,
+        stderr,
+    });
+    const cli = createCli({
+        cwd,
+        configPath,
+        env,
+        fetchImpl,
+        now: nowImpl,
+        output,
+        sleep: sleepImpl,
+        stdin,
+    });
+    if (argv.length === 0 || hasFlag(argv, ['--help', '-h'])) {
+        stdout.write(await cli.getHelp());
+        return 0;
+    }
+    if (hasFlag(argv, ['--version', '-v'])) {
+        output.print({ version: packageJson.version }, packageJson.version);
+        return 0;
+    }
+    try {
+        await cli.parseAsync(argv);
+        return 0;
+    }
+    catch (error) {
+        if (error instanceof CliCommandError) {
+            if (error.shouldReport && error.message) {
+                output.error(error.message);
+            }
+            return error.exitCode;
+        }
+        const message = error instanceof Error ? error.message : 'Unknown CLI error';
+        output.error(message);
+        return 1;
+    }
+};
+export const isDirectExecution = ({ importMetaUrl, processArgv1, }) => {
+    if (!processArgv1) {
+        return false;
+    }
+    try {
+        return realpathSync(fileURLToPath(importMetaUrl)) === realpathSync(processArgv1);
+    }
+    catch {
+        return false;
+    }
+};
+if (isDirectExecution({ importMetaUrl: import.meta.url, processArgv1: process.argv[1] })) {
+    void runCli({ argv: hideBin(process.argv) })
+        .then((exitCode) => {
+        process.exitCode = exitCode;
+    })
+        .catch((error) => {
+        const message = error instanceof Error ? error.message : 'Unknown CLI error';
+        process.stderr.write(`${message}\n`);
+        process.exitCode = 1;
+    });
+}

package/dist/commands/auth.js

@@ -0,0 +1,155 @@
+import { createApiClient } from '../lib/api-client.js';
+import { CliCommandError } from '../lib/cli-error.js';
+import { resolveOrganization } from '../lib/config-store.js';
+import { formatUserIdentity, mapApiErrorToCliError, requireResolvedBaseUrl, requireResolvedToken, } from '../lib/session.js';
+const isInteractiveStdin = (stdin) => {
+    return stdin.isTTY === true;
+};
+const readTokenFromStdin = async (stdin) => {
+    let token = '';
+    for await (const chunk of stdin) {
+        token += typeof chunk === 'string' ? chunk : Buffer.from(chunk).toString('utf8');
+    }
+    return token.trim();
+};
+const serializeOrganization = (organization) => {
+    if (!organization) {
+        return null;
+    }
+    return {
+        id: organization.organizationId,
+        name: organization.organizationName,
+        role: organization.role,
+        type: organization.organizationType,
+    };
+};
+const formatOrganizationSummary = (organization) => {
+    if (!organization) {
+        return 'No default organization selected.';
+    }
+    return `Default organization: ${organization.name} (${organization.id}).`;
+};
+export const registerAuthCommands = (authYargs, context) => {
+    return authYargs
+        .command('login', 'Read a CLI token from stdin and store it locally', (loginYargs) => {
+        return loginYargs.option('with-token', {
+            type: 'boolean',
+            demandOption: true,
+            describe: 'Read the token from stdin',
+        });
+    }, async (argv) => {
+        const config = await context.configStore.load();
+        const resolvedBaseUrl = requireResolvedBaseUrl({
+            flagValue: argv.baseUrl,
+            env: context.env,
+            config,
+        });
+        if (isInteractiveStdin(context.stdin)) {
+            throw new CliCommandError('No token was piped on stdin. Pipe a CLI token into "chalksurf auth login --with-token".', 2);
+        }
+        const token = await readTokenFromStdin(context.stdin);
+        if (!token) {
+            throw new CliCommandError('No token was provided on stdin.', 2);
+        }
+        const apiClient = createApiClient({
+            baseUrl: resolvedBaseUrl.value,
+            token,
+            fetchImpl: context.fetchImpl,
+        });
+        let profile;
+        try {
+            profile = await apiClient.getUserProfile();
+        }
+        catch (error) {
+            throw mapApiErrorToCliError(error);
+        }
+        const resolvedOrganization = resolveOrganization({
+            flagValue: argv.organization,
+            env: context.env,
+            config,
+            profile,
+        });
+        await context.configStore.update((currentConfig) => ({
+            ...currentConfig,
+            token,
+            baseUrl: resolvedBaseUrl.value,
+            organizationId: resolvedOrganization.organization?.organizationId,
+        }));
+        resolvedOrganization.warnings.forEach((warning) => {
+            context.output.info(warning);
+        });
+        context.output.print({
+            authenticated: true,
+            baseUrl: resolvedBaseUrl.value,
+            baseUrlSource: resolvedBaseUrl.source,
+            organization: serializeOrganization(resolvedOrganization.organization),
+            user: {
+                email: profile.email,
+                id: profile.id,
+                name: profile.name,
+            },
+            warnings: resolvedOrganization.warnings,
+        }, (result) => `Logged in as ${formatUserIdentity(result.user)}.\n${formatOrganizationSummary(result.organization)}`);
+    })
+        .command('status', 'Show the current authentication and organization state', () => { }, async (argv) => {
+        const config = await context.configStore.load();
+        const resolvedBaseUrl = requireResolvedBaseUrl({
+            flagValue: argv.baseUrl,
+            env: context.env,
+            config,
+        });
+        const resolvedToken = requireResolvedToken({
+            env: context.env,
+            config,
+        });
+        const apiClient = createApiClient({
+            baseUrl: resolvedBaseUrl.value,
+            token: resolvedToken.value,
+            fetchImpl: context.fetchImpl,
+        });
+        let profile;
+        try {
+            profile = await apiClient.getUserProfile();
+        }
+        catch (error) {
+            throw mapApiErrorToCliError(error);
+        }
+        const resolvedOrganization = resolveOrganization({
+            flagValue: argv.organization,
+            env: context.env,
+            config,
+            profile,
+        });
+        resolvedOrganization.warnings.forEach((warning) => {
+            context.output.info(warning);
+        });
+        context.output.print({
+            authenticated: true,
+            baseUrl: resolvedBaseUrl.value,
+            baseUrlSource: resolvedBaseUrl.source,
+            organization: serializeOrganization(resolvedOrganization.organization),
+            organizationSource: resolvedOrganization.source,
+            tokenSource: resolvedToken.source,
+            user: {
+                email: profile.email,
+                id: profile.id,
+                name: profile.name,
+            },
+            warnings: resolvedOrganization.warnings,
+        }, (result) => `Authenticated as ${formatUserIdentity(result.user)}.\n${formatOrganizationSummary(result.organization)}`);
+    })
+        .command('logout', 'Remove the locally stored CLI token', () => { }, async () => {
+        const config = await context.configStore.load();
+        const hadStoredToken = Boolean(config.token);
+        await context.configStore.update((currentConfig) => ({
+            ...currentConfig,
+            token: undefined,
+        }));
+        context.output.print({
+            clearedStoredToken: hadStoredToken,
+            loggedOut: true,
+        }, hadStoredToken ? 'Stored CLI token removed.' : 'No stored CLI token was present.');
+    })
+        .demandCommand(1)
+        .strict();
+};

package/dist/commands/job.js

@@ -0,0 +1,94 @@
+import { createApiClient } from '../lib/api-client.js';
+import { CliCommandError } from '../lib/cli-error.js';
+import { mapApiErrorToCliError, requireResolvedBaseUrl, requireResolvedToken, resolveRequestedOrganizationId, } from '../lib/session.js';
+import { formatCliJobSummary, getWaitExitCode, serializeCliJob, throwSilentExitCode, waitForCliJobs, } from '../lib/user-jobs.js';
+const normalizeTimeoutMs = (timeoutMs) => {
+    const normalizedTimeoutMs = timeoutMs ?? 300000;
+    if (!Number.isFinite(normalizedTimeoutMs) || normalizedTimeoutMs <= 0) {
+        throw new CliCommandError('--timeout-ms must be a positive number.', 2);
+    }
+    return normalizedTimeoutMs;
+};
+export const registerJobCommands = (jobYargs, context) => {
+    return jobYargs
+        .command('get <jobId>', 'Fetch a single job', (getYargs) => getYargs.positional('jobId', {
+        type: 'string',
+        describe: 'Job ID to fetch',
+    }), async (argv) => {
+        const config = await context.configStore.load();
+        const resolvedBaseUrl = requireResolvedBaseUrl({
+            flagValue: argv.baseUrl,
+            env: context.env,
+            config,
+        });
+        const resolvedToken = requireResolvedToken({
+            env: context.env,
+            config,
+        });
+        const organizationId = resolveRequestedOrganizationId({
+            flagValue: argv.organization,
+            env: context.env,
+            config,
+        });
+        const apiClient = createApiClient({
+            baseUrl: resolvedBaseUrl.value,
+            token: resolvedToken.value,
+            organizationId,
+            fetchImpl: context.fetchImpl,
+        });
+        let job;
+        try {
+            job = await apiClient.getUserJob(String(argv.jobId));
+        }
+        catch (error) {
+            throw mapApiErrorToCliError(error);
+        }
+        const serializedJob = serializeCliJob(job);
+        context.output.print({ job: serializedJob }, (result) => formatCliJobSummary(result.job));
+    })
+        .command('wait <jobIds..>', 'Poll jobs until they complete, fail, or time out', (waitYargs) => waitYargs
+        .positional('jobIds', {
+        array: true,
+        type: 'string',
+        describe: 'One or more job IDs to wait for',
+    })
+        .option('timeout-ms', {
+        type: 'number',
+        default: 300000,
+        describe: 'Maximum time to wait before timing out',
+    }), async (argv) => {
+        const config = await context.configStore.load();
+        const resolvedBaseUrl = requireResolvedBaseUrl({
+            flagValue: argv.baseUrl,
+            env: context.env,
+            config,
+        });
+        const resolvedToken = requireResolvedToken({
+            env: context.env,
+            config,
+        });
+        const organizationId = resolveRequestedOrganizationId({
+            flagValue: argv.organization,
+            env: context.env,
+            config,
+        });
+        const apiClient = createApiClient({
+            baseUrl: resolvedBaseUrl.value,
+            token: resolvedToken.value,
+            organizationId,
+            fetchImpl: context.fetchImpl,
+        });
+        const timeoutMs = normalizeTimeoutMs(argv.timeoutMs);
+        const waitResult = await waitForCliJobs({
+            getUserJob: async (jobId) => await apiClient.getUserJob(jobId),
+            jobIds: (argv.jobIds ?? []).map(String),
+            now: context.now,
+            sleep: context.sleep,
+            timeoutMs,
+        });
+        context.output.print(waitResult, (result) => result.jobs.map((job) => formatCliJobSummary(job)).join('\n'));
+        throwSilentExitCode(getWaitExitCode(waitResult));
+    })
+        .demandCommand(1)
+        .strict();
+};

package/dist/commands/org.js

@@ -0,0 +1,106 @@
+import { createApiClient } from '../lib/api-client.js';
+import { CliCommandError } from '../lib/cli-error.js';
+import { resolveOrganization } from '../lib/config-store.js';
+import { mapApiErrorToCliError, requireResolvedBaseUrl, requireResolvedToken } from '../lib/session.js';
+const serializeOrganization = ({ organizationId, organizationName, organizationType, role, selected, }) => {
+    return {
+        id: organizationId,
+        name: organizationName,
+        role,
+        selected,
+        type: organizationType,
+    };
+};
+export const registerOrgCommands = (orgYargs, context) => {
+    return orgYargs
+        .command('list', 'List organizations available to the authenticated user', () => { }, async (argv) => {
+        const config = await context.configStore.load();
+        const resolvedBaseUrl = requireResolvedBaseUrl({
+            flagValue: argv.baseUrl,
+            env: context.env,
+            config,
+        });
+        const resolvedToken = requireResolvedToken({
+            env: context.env,
+            config,
+        });
+        const apiClient = createApiClient({
+            baseUrl: resolvedBaseUrl.value,
+            token: resolvedToken.value,
+            fetchImpl: context.fetchImpl,
+        });
+        let profile;
+        try {
+            profile = await apiClient.getUserProfile();
+        }
+        catch (error) {
+            throw mapApiErrorToCliError(error);
+        }
+        const resolvedOrganization = resolveOrganization({
+            flagValue: argv.organization,
+            env: context.env,
+            config,
+            profile,
+        });
+        resolvedOrganization.warnings.forEach((warning) => {
+            context.output.info(warning);
+        });
+        const organizations = profile.organizationMemberships.map((membership) => serializeOrganization({
+            ...membership,
+            selected: membership.organizationId === resolvedOrganization.organization?.organizationId,
+        }));
+        context.output.print({
+            organizations,
+            selectedOrganizationId: resolvedOrganization.organization?.organizationId ?? null,
+            selectedOrganizationSource: resolvedOrganization.source,
+            warnings: resolvedOrganization.warnings,
+        }, (result) => result.organizations
+            .map((organization) => `${organization.selected ? '*' : ' '} ${organization.name} (${organization.id}) [${organization.type}, ${organization.role}]`)
+            .join('\n'));
+    })
+        .command('use <organizationId>', 'Set the default organization used by the CLI', (useYargs) => {
+        return useYargs.positional('organizationId', {
+            type: 'string',
+            describe: 'Organization ID to store as the default',
+        });
+    }, async (argv) => {
+        const config = await context.configStore.load();
+        const resolvedBaseUrl = requireResolvedBaseUrl({
+            flagValue: argv.baseUrl,
+            env: context.env,
+            config,
+        });
+        const resolvedToken = requireResolvedToken({
+            env: context.env,
+            config,
+        });
+        const apiClient = createApiClient({
+            baseUrl: resolvedBaseUrl.value,
+            token: resolvedToken.value,
+            fetchImpl: context.fetchImpl,
+        });
+        let profile;
+        try {
+            profile = await apiClient.getUserProfile();
+        }
+        catch (error) {
+            throw mapApiErrorToCliError(error);
+        }
+        const organization = profile.organizationMemberships.find((membership) => membership.organizationId === String(argv.organizationId));
+        if (!organization) {
+            throw new CliCommandError(`Organization "${String(argv.organizationId)}" is not accessible to the current user.`, 2);
+        }
+        await context.configStore.update((currentConfig) => ({
+            ...currentConfig,
+            organizationId: organization.organizationId,
+        }));
+        context.output.print({
+            organization: serializeOrganization({
+                ...organization,
+                selected: true,
+            }),
+        }, (result) => `Default organization set to ${result.organization.name} (${result.organization.id}).`);
+    })
+        .demandCommand(1)
+        .strict();
+};