@chalksurf/cli 0.1.0 → 0.2.0

package/README.md

@@ -1,28 +1,9 @@
 # `@chalksurf/cli`
 
-Publishable Chalksurf CLI package.
+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:
@@ -38,98 +19,51 @@ 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
-```
+## Quick Start
 
-Check the current session:
+Interactive operator flow:
 
 ```bash
-chalksurf auth status
+chalksurf auth login --base-url https://api.chalksurf.com
 chalksurf org list
+chalksurf sheet import ./fixtures/algebra.pdf --wait
 ```
 
-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:
+Headless or agent flow:
 
 ```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
+npx @chalksurf/cli@0.1.0 sheet import --manifest - --wait --json < import.json
 ```
 
-Import a local file:
+Sheet import manifests use top-level `sheets[]`, where each sheet has one `targetFolderPath` and one or more ordered `sources[]`. See [the canonical example](./docs/examples/sheet-import-manifest.json).
 
-```bash
-chalksurf sheet import ./fixtures/algebra.pdf
-```
+## Docs
 
-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
-```
+- [Manual operator guide](./docs/manual.md)
+- [Agent and Codex guide](./docs/agents.md)
+- [Manifest reference](./docs/manifest.md)
+- [Exit codes and JSON errors](./docs/exit-codes.md)
+- [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)
 
 ## 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 login --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 login --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
+npm run cli-dev -- sheet import https://example.com/worksheet.docx --single-sheet --target-folder Imported --json
 ```
-
-For short-lived agent runs, skip local persistence and inject credentials through environment variables instead.

package/dist/bin/chalksurf.js

@@ -4,21 +4,23 @@ import { fileURLToPath } from 'node:url';
 import { hideBin } from 'yargs/helpers';
 import yargs from 'yargs/yargs';
 import { registerAuthCommands } from '../commands/auth.js';
+import { registerExerciseCommands } from '../commands/exercise.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 { CliCommandError, createSerializableCliError, serializeCliError } from '../lib/cli-error.js';
 import { createConfigStore } from '../lib/config-store.js';
 import { createOutput } from '../lib/output.js';
+import { createPromptSecret } from '../lib/prompt-secret.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 createCli = ({ cwd, configPath, env, now, output, sleep, stdin, promptSecret, }) => {
     const commandContext = {
         cwd,
         configStore: createConfigStore({ configPath, env }),
         env,
-        fetchImpl,
         now,
         output,
+        promptSecret,
         sleep,
         stdin,
     };
@@ -48,37 +50,83 @@ const createCli = ({ cwd, configPath, env, fetchImpl, now, output, sleep, stdin,
     })
         .command('auth <subcommand>', 'Authentication commands', (authYargs) => registerAuthCommands(authYargs, commandContext), () => { })
         .command('org <subcommand>', 'Organization commands', (orgYargs) => registerOrgCommands(orgYargs, commandContext), () => { })
+        .command('exercise <subcommand>', 'Exercise commands', (exerciseYargs) => registerExerciseCommands(exerciseYargs, 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 parseCliWithCapturedOutput = async ({ cli, argv, stdout, }) => {
+    await new Promise((resolve, reject) => {
+        cli.parse(argv, (error, _parsedArgv, output) => {
+            if (output) {
+                stdout.write(output);
+            }
+            if (error) {
+                reject(error);
+                return;
+            }
+            resolve();
+        });
+    });
+};
 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 topLevelCommands = new Set(['auth', 'org', 'exercise', 'sheet', 'job']);
+const hasTopLevelCommand = (argv) => {
+    return argv.some((argument) => topLevelCommands.has(argument));
+};
+const resolveCommandName = (argv) => {
+    for (let index = 0; index < argv.length; index += 1) {
+        const argument = argv[index];
+        if (!topLevelCommands.has(argument)) {
+            continue;
+        }
+        const subcommand = argv
+            .slice(index + 1)
+            .find((candidate) => candidate.length > 0 && !candidate.startsWith('-') && !candidate.startsWith('http'));
+        return subcommand ? `${argument} ${subcommand}` : argument;
+    }
+    if (hasFlag(argv, ['--version', '-v'])) {
+        return 'chalksurf version';
+    }
+    return 'chalksurf';
+};
+export const runCli = async ({ argv, cwd = process.cwd(), configPath, env = process.env, nowImpl = Date.now, promptSecretImpl = createPromptSecret(), 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 commandName = resolveCommandName(argv);
     const cli = createCli({
         cwd,
         configPath,
         env,
-        fetchImpl,
         now: nowImpl,
         output,
+        promptSecret: promptSecretImpl,
         sleep: sleepImpl,
         stdin,
     });
-    if (argv.length === 0 || hasFlag(argv, ['--help', '-h'])) {
+    if (argv.length === 0 || (hasFlag(argv, ['--help', '-h']) && !hasTopLevelCommand(argv))) {
         stdout.write(await cli.getHelp());
         return 0;
     }
-    if (hasFlag(argv, ['--version', '-v'])) {
-        output.print({ version: packageJson.version }, packageJson.version);
+    if (hasFlag(argv, ['--help', '-h'])) {
+        await parseCliWithCapturedOutput({
+            cli,
+            argv,
+            stdout,
+        });
+        return 0;
+    }
+    if (hasFlag(argv, ['--version', '-v']) && !hasTopLevelCommand(argv)) {
+        output.print({ version: packageJson.version }, packageJson.version, {
+            command: commandName,
+        });
         return 0;
     }
     try {
@@ -88,12 +136,31 @@ export const runCli = async ({ argv, cwd = process.cwd(), configPath, env = proc
     catch (error) {
         if (error instanceof CliCommandError) {
             if (error.shouldReport && error.message) {
-                output.error(error.message);
+                if (output.json) {
+                    output.printError({
+                        command: commandName,
+                        error: serializeCliError(error),
+                    });
+                }
+                else {
+                    output.error(error.message);
+                }
             }
             return error.exitCode;
         }
         const message = error instanceof Error ? error.message : 'Unknown CLI error';
-        output.error(message);
+        if (output.json) {
+            output.printError({
+                command: commandName,
+                error: createSerializableCliError({
+                    exitCode: 1,
+                    message,
+                }),
+            });
+        }
+        else {
+            output.error(message);
+        }
         return 1;
     }
 };

package/dist/commands/auth.js

@@ -31,12 +31,15 @@ const formatOrganizationSummary = (organization) => {
 };
 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', {
+        .command('login', 'Read a CLI token from stdin or prompt for it interactively', (loginYargs) => {
+        return loginYargs
+            .option('with-token', {
             type: 'boolean',
-            demandOption: true,
-            describe: 'Read the token from stdin',
-        });
+            default: false,
+            describe: 'Read the token from stdin when piping input',
+        })
+            .example('chalksurf auth login --base-url https://api.chalksurf.com', 'Prompt for a CLI token and store it locally')
+            .example(`printf '%s' "$CHALKSURF_TOKEN" | chalksurf auth login --base-url https://api.chalksurf.com`, 'Read a CLI token from stdin instead of prompting');
     }, async (argv) => {
         const config = await context.configStore.load();
         const resolvedBaseUrl = requireResolvedBaseUrl({
@@ -44,17 +47,15 @@ export const registerAuthCommands = (authYargs, context) => {
             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);
+        const token = (isInteractiveStdin(context.stdin)
+            ? await context.promptSecret('CLI token: ')
+            : await readTokenFromStdin(context.stdin)).trim();
         if (!token) {
-            throw new CliCommandError('No token was provided on stdin.', 2);
+            throw new CliCommandError('No token was provided.', 2);
         }
         const apiClient = createApiClient({
             baseUrl: resolvedBaseUrl.value,
             token,
-            fetchImpl: context.fetchImpl,
         });
         let profile;
         try {
@@ -88,10 +89,19 @@ export const registerAuthCommands = (authYargs, context) => {
                 id: profile.id,
                 name: profile.name,
             },
-            warnings: resolvedOrganization.warnings,
-        }, (result) => `Logged in as ${formatUserIdentity(result.user)}.\n${formatOrganizationSummary(result.organization)}`);
+        }, (result) => `Logged in as ${formatUserIdentity(result.user)}.\n${formatOrganizationSummary(result.organization)}`, {
+            command: 'auth login',
+        });
     })
-        .command('status', 'Show the current authentication and organization state', () => { }, async (argv) => {
+        .command('status', 'Show the current authentication and organization state', (statusYargs) => statusYargs
+        .example('chalksurf auth status', 'Show the current authenticated user and default organization')
+        .example('CHALKSURF_BASE_URL=https://api.chalksurf.com CHALKSURF_TOKEN=cs_cli_... chalksurf auth status --json', 'Inspect the active session in machine-readable mode')
+        .epilogue([
+        'Resolution order:',
+        '  base URL: --base-url, then CHALKSURF_BASE_URL, then stored config',
+        '  token: CHALKSURF_TOKEN, then stored config',
+        '  organization: --organization, then CHALKSURF_ORGANIZATION_ID, then stored config',
+    ].join('\n')), async (argv) => {
         const config = await context.configStore.load();
         const resolvedBaseUrl = requireResolvedBaseUrl({
             flagValue: argv.baseUrl,
@@ -105,7 +115,6 @@ export const registerAuthCommands = (authYargs, context) => {
         const apiClient = createApiClient({
             baseUrl: resolvedBaseUrl.value,
             token: resolvedToken.value,
-            fetchImpl: context.fetchImpl,
         });
         let profile;
         try {
@@ -135,10 +144,11 @@ export const registerAuthCommands = (authYargs, context) => {
                 id: profile.id,
                 name: profile.name,
             },
-            warnings: resolvedOrganization.warnings,
-        }, (result) => `Authenticated as ${formatUserIdentity(result.user)}.\n${formatOrganizationSummary(result.organization)}`);
+        }, (result) => `Authenticated as ${formatUserIdentity(result.user)}.\n${formatOrganizationSummary(result.organization)}`, {
+            command: 'auth status',
+        });
     })
-        .command('logout', 'Remove the locally stored CLI token', () => { }, async () => {
+        .command('logout', 'Remove the locally stored CLI token', (logoutYargs) => logoutYargs.example('chalksurf auth logout', 'Remove the stored CLI token from local config'), async () => {
         const config = await context.configStore.load();
         const hadStoredToken = Boolean(config.token);
         await context.configStore.update((currentConfig) => ({
@@ -148,7 +158,9 @@ export const registerAuthCommands = (authYargs, context) => {
         context.output.print({
             clearedStoredToken: hadStoredToken,
             loggedOut: true,
-        }, hadStoredToken ? 'Stored CLI token removed.' : 'No stored CLI token was present.');
+        }, hadStoredToken ? 'Stored CLI token removed.' : 'No stored CLI token was present.', {
+            command: 'auth logout',
+        });
     })
         .demandCommand(1)
         .strict();