@pitcher/cli-scripts 2.11.0 → 2.13.0

package/README.md

@@ -12,7 +12,7 @@ p command --help
 
 ## MCP server
 
-Run `p mcp` to start a stdio [MCP](https://modelcontextprotocol.io) server that exposes this CLI's commands as tools to an MCP-capable host (Claude Desktop, Claude Code, etc). It wraps 50 tools, one per CLI `run*` function: every command above (including `dsr create` + `dsr bind-landing`) except the five local `scaffold` subcommands (which just print/write a starter file and make no request). `dev-sync` is exposed as a one-shot sync only; the continuous `watch` mode is not available as a tool.
+Run `p mcp` to start a stdio [MCP](https://modelcontextprotocol.io) server that exposes this CLI's commands as tools to an MCP-capable host (Claude Desktop, Claude Code, etc). It wraps 114 tools, one per CLI `run*` function: every command above (including `dsr create` + `dsr bind-landing` and the full `ld` surface) except the five local `scaffold` subcommands (which just print/write a starter file and make no request). `dev-sync` is exposed as a one-shot sync only; the continuous `watch` mode is not available as a tool.
 
 ```bash
 p mcp
@@ -55,7 +55,7 @@ yarn mcpb:pack        # → pitcher.mcpb (validated + packed)
 
 Install by double-clicking `pitcher.mcpb` (or Settings → Extensions → Install Extension). Claude Desktop prompts for the API key (stored in the OS keychain) and organization; both are editable afterward, so switching orgs needs no reinstall.
 
-The bundle reuses the same server as `p mcp` but registers a **content-tool subset (47)** — it omits the developer-only `publish-app` and `dev-sync`/`dev-sync-revert`. The `organization` field accepts a subdomain (`acme`), a bare hostname (`acme.my.pitcher.com`), or a full `https://` URL. Build details (esbuild single-file, version injection) live in `mcpb/` and `CLAUDE.md`.
+The bundle reuses the same server as `p mcp` but registers a **content-tool subset (111)** — it omits the developer-only `publish-app` and `dev-sync`/`dev-sync-revert`. The `organization` field accepts a subdomain (`acme`), a bare hostname (`acme.my.pitcher.com`), or a full `https://` URL. Build details (esbuild single-file, version injection) live in `mcpb/` and `CLAUDE.md`.
 
 This section is a reference only. For app-development conventions (modules, settings, mount points, SFDC), see the `pitcher-apps` skill, not this README.
 
@@ -360,6 +360,14 @@ p analytics org --api-key myapikey
 
 # Instance rollups (instance-admin or org-admin key required)
 p analytics instance --instance-id 01... --api-key myapikey
+
+# KPI metrics from the clickhouse analytics service (PIT-7647).
+# Access follows the key user's real role on the instance; --org/--url pick the
+# env exactly as for other commands (they route via x-original-domain).
+# Activity metrics need a date window; inventory counts (total-members, ...) do not.
+p analytics kpi --instance-id 01... --type total-members --api-key myapikey
+p analytics kpi --instance-id 01... --type total-active-users \
+  --start-date 2026-01-01 --end-date 2026-01-31 --api-key myapikey
 ```
 
 ## To run the `users` command:
@@ -491,3 +499,33 @@ p dsr scaffold --out share.json
 ```
 
 Creating needs a share-capable key; **binding a landing page currently needs an editor key** (PIT-7525 will open it to reps for their own DSRs) — a denied bind returns the link with a warning. Discover landing template IDs via `p dsr-landing list`.
+
+## To run the `ld` command:
+
+Author L&D (MicroLearn) content — courses, modules, certificates, and assessments — against the standalone L&D backend. The general form is `p ld <resource> <verb>`, plus the top-level `p ld create-canvas` recipe (create → set-canvas → publish in one step). `--instance-id` is required on every subcommand.
+
+Unlike the other commands, L&D targets a **separate backend** (not `<org>.my.pitcher.com`). The base URL is resolved automatically from the instance's `ld-app` config; override with `--ld-url` or the `NG_LD_API_URL` env var (e.g. for a region whose `ld-app` config is unavailable). Auth is the same org `x-api-key`. The surface is authoring-only — enrollment, attempts, progress, groups, and analytics are not exposed (the org key cannot reach them). `set-canvas` likewise has no `--require-recompletion`: the backend rejects that flag for API-key callers (the bulk rep-completion reset is human-admin-only), so it could only ever 403.
+
+```bash
+# headline: author a designed canvas course in one step (create → set-canvas → publish)
+p ld create-canvas --instance-id 01... --title "Onboarding 101" --canvas '{"content":{"data":[]}}' --publish
+
+# courses
+p ld course list --instance-id 01... --status draft
+p ld course create --instance-id 01... --title "Intro" --description "A short intro course." --level Beginner --duration 10 --sections-count 1
+p ld course set-canvas --instance-id 01... --id 01... --canvas-file ./canvas.json
+p ld course publish --instance-id 01... --id 01...
+p ld course add-to-modules --instance-id 01... --id 01... --module-ids m1,m2
+
+# modules / certificates / assessments
+p ld module create --instance-id 01... --title "Basics" --subtitle "Getting started" --description "Foundational module."
+p ld module add-courses --instance-id 01... --id m1 --course-ids c1,c2
+p ld cert create --instance-id 01... --title "Certified Rep"
+p ld assessment create --instance-id 01... --title "Quiz 1"
+p ld assessment add-question --instance-id 01... --id a1 --question '{"type":"true_false","questionText":"...","config":{},"points":1}'
+
+# override the L&D base URL (else resolved from ld-app config)
+NG_LD_API_URL=https://<lambda-host>/dev/api p ld course list --instance-id 01...
+```
+
+MCP: the same surface is exposed as `pitcher_ld_*` tools, plus a `create_ld_canvas_course` recipe prompt and a `pitcher://design/ld-canvas-course` resource. `NG_LD_API_URL` is the only way to override the L&D base URL under MCP (no per-call override, by design).

package/dist/index.js

@@ -25,6 +25,7 @@ import { createGroupsCommand } from './src/commands/groups.js';
 import { createRolesCommand } from './src/commands/roles.js';
 import { createMetadataTemplateCommand } from './src/commands/metadataTemplate.js';
 import { createDsrCommand } from './src/commands/dsr.js';
+import { createLdCommand } from './src/commands/ld.js';
 import { createMcpCommand } from './src/commands/mcp.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -56,6 +57,7 @@ program.addCommand(createGroupsCommand());
 program.addCommand(createRolesCommand());
 program.addCommand(createMetadataTemplateCommand());
 program.addCommand(createDsrCommand());
+program.addCommand(createLdCommand());
 program.addCommand(createOrgCommand());
 program.addCommand(createAnalyticsCommand());
 program.addCommand(createMcpCommand());

package/dist/src/commands/analytics.d.ts

@@ -9,4 +9,20 @@ export declare function runAnalyticsOrg(opts: CommonOpts, deps?: AnalyticsDeps):
 export declare function runAnalyticsInstance(opts: CommonOpts & {
     instanceId?: string;
 }, deps?: AnalyticsDeps): Promise<Envelope<unknown>>;
+export interface AnalyticsKpiOpts extends CommonOpts {
+    instanceId?: string;
+    type?: string;
+    startDate?: string;
+    endDate?: string;
+    groupIds?: string;
+    userEmails?: string;
+}
+/**
+ * KPI metrics from the clickhouse-api analytics service (PIT-7647). Unlike
+ * org/instance rollups (Django), this hits `clickhouse.pitcher.com` with the
+ * org api-key; the caller inherits the key user's real role. Dates are required
+ * by the server for activity-metric types (inventory counts like
+ * `total-members` need none) — that validation stays server-side.
+ */
+export declare function runAnalyticsKpi(opts: AnalyticsKpiOpts, deps?: AnalyticsDeps): Promise<Envelope<unknown>>;
 export declare function createAnalyticsCommand(): Command;

package/dist/src/commands/analytics.js

@@ -1,5 +1,5 @@
 import { Command } from 'commander';
-import { clientFor, toCliError } from '../core/http.js';
+import { clickhouseClientFor, clientFor, toCliError } from '../core/http.js';
 import { ok, fail } from '../core/envelope.js';
 import { createCliError } from '../core/errors.js';
 import { emitEnvelope } from '../core/output.js';
@@ -26,6 +26,37 @@ export async function runAnalyticsInstance(opts, deps = {}) {
         return fail(toCliError(e));
     }
 }
+/**
+ * KPI metrics from the clickhouse-api analytics service (PIT-7647). Unlike
+ * org/instance rollups (Django), this hits `clickhouse.pitcher.com` with the
+ * org api-key; the caller inherits the key user's real role. Dates are required
+ * by the server for activity-metric types (inventory counts like
+ * `total-members` need none) — that validation stays server-side.
+ */
+export async function runAnalyticsKpi(opts, deps = {}) {
+    try {
+        if (!opts.instanceId)
+            throw createCliError('VALIDATION', '--instance-id is required for analytics kpi');
+        const client = clickhouseClientFor(opts, deps);
+        const params = {
+            instance_id: opts.instanceId,
+            type: opts.type || 'all',
+        };
+        if (opts.startDate)
+            params.start_date = opts.startDate;
+        if (opts.endDate)
+            params.end_date = opts.endDate;
+        if (opts.groupIds)
+            params.group_ids = opts.groupIds;
+        if (opts.userEmails)
+            params.user_emails = opts.userEmails;
+        const res = await client.get('/analytics/kpi', { params });
+        return ok(res.data);
+    }
+    catch (e) {
+        return fail(toCliError(e));
+    }
+}
 export function createAnalyticsCommand() {
     const cmd = new Command('analytics').description('read rollup analytics totals (requires an org-admin API key)');
     withAuthFlags(cmd.command('org'))
@@ -41,5 +72,17 @@ export function createAnalyticsCommand() {
         const globals = command.optsWithGlobals();
         emitEnvelope(await runAnalyticsInstance({ ...options, quiet: globals.quiet }), globals);
     });
+    withAuthFlags(cmd.command('kpi'))
+        .option('--instance-id <id>', 'Instance ID (required)')
+        .option('--type <type>', "KPI type, e.g. total-members, total-active-users (default 'all')")
+        .option('--start-date <iso>', 'Window start (ISO date; required by the server for activity metrics)')
+        .option('--end-date <iso>', 'Window end (ISO date; required by the server for activity metrics)')
+        .option('--group-ids <csv>', 'Comma-separated distribution-group IDs to scope by')
+        .option('--user-emails <csv>', 'Comma-separated user emails to scope by')
+        .description('KPI metrics from the clickhouse analytics service (role follows the key user)')
+        .action(async (options, command) => {
+        const globals = command.optsWithGlobals();
+        emitEnvelope(await runAnalyticsKpi({ ...options, quiet: globals.quiet }), globals);
+    });
     return cmd;
 }

package/dist/src/commands/ld/assessment.d.ts

@@ -0,0 +1,61 @@
+import { Command } from 'commander';
+import { type LdCommonOpts, type LdDeps } from '../../core/ld.js';
+import { type Envelope } from '../../core/envelope.js';
+export declare function runLdAssessmentTags(opts: LdCommonOpts, deps?: LdDeps): Promise<Envelope<unknown>>;
+export declare function runLdAssessmentList(opts: LdCommonOpts & {
+    status?: string;
+    title?: string;
+    limit?: number;
+    offset?: number;
+}, deps?: LdDeps): Promise<Envelope<unknown>>;
+export declare function runLdAssessmentGet(opts: LdCommonOpts & {
+    id?: string;
+}, deps?: LdDeps): Promise<Envelope<unknown>>;
+export declare function runLdAssessmentCreate(opts: LdCommonOpts & {
+    title?: string;
+    description?: string;
+    passingScore?: number;
+    timeLimit?: number;
+    maxAttempts?: number;
+    tags?: string[];
+}, deps?: LdDeps): Promise<Envelope<unknown>>;
+export declare function runLdAssessmentUpdate(opts: LdCommonOpts & {
+    id?: string;
+} & Record<string, unknown>, deps?: LdDeps): Promise<Envelope<unknown>>;
+export declare function runLdAssessmentDelete(opts: LdCommonOpts & {
+    id?: string;
+}, deps?: LdDeps): Promise<Envelope<unknown>>;
+export declare function runLdAssessmentListQuestions(opts: LdCommonOpts & {
+    id?: string;
+}, deps?: LdDeps): Promise<Envelope<unknown>>;
+export declare function runLdAssessmentAddQuestion(opts: LdCommonOpts & {
+    id?: string;
+    question?: string;
+    questionFile?: string;
+}, deps?: LdDeps): Promise<Envelope<unknown>>;
+export declare function runLdAssessmentUpdateQuestion(opts: LdCommonOpts & {
+    id?: string;
+    questionId?: string;
+    question?: string;
+    questionFile?: string;
+}, deps?: LdDeps): Promise<Envelope<unknown>>;
+export declare function runLdAssessmentReorderQuestions(opts: LdCommonOpts & {
+    id?: string;
+    questionIds?: string[];
+}, deps?: LdDeps): Promise<Envelope<unknown>>;
+export declare function runLdAssessmentDeleteQuestion(opts: LdCommonOpts & {
+    id?: string;
+    questionId?: string;
+}, deps?: LdDeps): Promise<Envelope<unknown>>;
+export declare function runLdAssessmentPreviewStart(opts: LdCommonOpts & {
+    id?: string;
+}, deps?: LdDeps): Promise<Envelope<unknown>>;
+export declare function runLdAssessmentPreviewGrade(opts: LdCommonOpts & {
+    id?: string;
+    answers?: string;
+    answersFile?: string;
+}, deps?: LdDeps): Promise<Envelope<unknown>>;
+export declare function runLdAssessmentListCourses(opts: LdCommonOpts & {
+    id?: string;
+}, deps?: LdDeps): Promise<Envelope<unknown>>;
+export declare function createAssessmentSubcommand(): Command;

package/dist/src/commands/ld/assessment.js

@@ -0,0 +1,235 @@
+import { Command } from 'commander';
+import { ldClientFor, ldData, toLdCliError, requireInstance, pickTruthy } from '../../core/ld.js';
+import { ok, fail } from '../../core/envelope.js';
+import { createCliError } from '../../core/errors.js';
+import { parseJsonInput } from '../../core/readInput.js';
+import { listLimitOffsetParams } from '../../core/pagination.js';
+import { assertIntFlags } from '../../schema/content.js';
+import { csv, ldFlags, render } from './course.js';
+const ADMIN = '/admin/assessments';
+// ---- run* functions ----
+export async function runLdAssessmentTags(opts, deps = {}) {
+    try {
+        const instanceId = requireInstance(opts);
+        const client = await ldClientFor(opts, deps);
+        const res = await client.get(`${ADMIN}/tags`, { params: { instanceId } });
+        return ok(ldData(res));
+    }
+    catch (e) {
+        return fail(toLdCliError(e));
+    }
+}
+export async function runLdAssessmentList(opts, deps = {}) {
+    try {
+        const instanceId = requireInstance(opts);
+        assertIntFlags(opts);
+        const params = { instanceId, ...listLimitOffsetParams(opts), ...pickTruthy(opts, ['status', 'title']) };
+        const client = await ldClientFor(opts, deps);
+        const res = await client.get(ADMIN, { params });
+        return ok(ldData(res));
+    }
+    catch (e) {
+        return fail(toLdCliError(e));
+    }
+}
+export async function runLdAssessmentGet(opts, deps = {}) {
+    try {
+        const instanceId = requireInstance(opts);
+        if (!opts.id)
+            throw createCliError('VALIDATION', '--id is required');
+        const client = await ldClientFor(opts, deps);
+        const res = await client.get(`${ADMIN}/${opts.id}`, { params: { instanceId } });
+        return ok(ldData(res));
+    }
+    catch (e) {
+        return fail(toLdCliError(e));
+    }
+}
+// instanceId is REQUIRED in the body (validation parses req.body alone; the controller also
+// reads instanceId from the query but validation runs first). title required.
+export async function runLdAssessmentCreate(opts, deps = {}) {
+    try {
+        const instanceId = requireInstance(opts);
+        if (!opts.title)
+            throw createCliError('VALIDATION', '--title is required');
+        const body = { instanceId, title: opts.title };
+        if (opts.description !== undefined)
+            body.description = opts.description;
+        if (opts.passingScore !== undefined)
+            body.passingScore = opts.passingScore;
+        if (opts.timeLimit !== undefined)
+            body.timeLimit = opts.timeLimit;
+        if (opts.maxAttempts !== undefined)
+            body.maxAttempts = opts.maxAttempts;
+        if (opts.tags !== undefined)
+            body.tags = opts.tags;
+        const client = await ldClientFor(opts, deps);
+        const res = await client.post(ADMIN, body, { params: { instanceId } });
+        return ok(ldData(res));
+    }
+    catch (e) {
+        return fail(toLdCliError(e));
+    }
+}
+// Partial update — send only what changed. Publish via --status published.
+export async function runLdAssessmentUpdate(opts, deps = {}) {
+    try {
+        const instanceId = requireInstance(opts);
+        if (!opts.id)
+            throw createCliError('VALIDATION', '--id is required');
+        const body = {};
+        for (const k of ['title', 'description', 'passingScore', 'timeLimit', 'maxAttempts', 'status', 'tags']) {
+            if (opts[k] !== undefined)
+                body[k] = opts[k];
+        }
+        const client = await ldClientFor(opts, deps);
+        const res = await client.put(`${ADMIN}/${opts.id}`, body, { params: { instanceId } });
+        return ok(ldData(res));
+    }
+    catch (e) {
+        return fail(toLdCliError(e));
+    }
+}
+export async function runLdAssessmentDelete(opts, deps = {}) {
+    try {
+        const instanceId = requireInstance(opts);
+        if (!opts.id)
+            throw createCliError('VALIDATION', '--id is required');
+        const client = await ldClientFor(opts, deps);
+        const res = await client.delete(`${ADMIN}/${opts.id}`, { params: { instanceId } });
+        return ok(ldData(res) ?? { id: opts.id, deleted: true });
+    }
+    catch (e) {
+        return fail(toLdCliError(e));
+    }
+}
+export async function runLdAssessmentListQuestions(opts, deps = {}) {
+    try {
+        const instanceId = requireInstance(opts);
+        if (!opts.id)
+            throw createCliError('VALIDATION', '--id is required');
+        const client = await ldClientFor(opts, deps);
+        const res = await client.get(`${ADMIN}/${opts.id}/questions`, { params: { instanceId } });
+        return ok(ldData(res));
+    }
+    catch (e) {
+        return fail(toLdCliError(e));
+    }
+}
+export async function runLdAssessmentAddQuestion(opts, deps = {}) {
+    try {
+        const instanceId = requireInstance(opts);
+        if (!opts.id)
+            throw createCliError('VALIDATION', '--id is required');
+        const question = parseJsonInput(opts.question, opts.questionFile, 'question');
+        const client = await ldClientFor(opts, deps);
+        const res = await client.post(`${ADMIN}/${opts.id}/questions`, question, { params: { instanceId } });
+        return ok(ldData(res));
+    }
+    catch (e) {
+        return fail(toLdCliError(e));
+    }
+}
+export async function runLdAssessmentUpdateQuestion(opts, deps = {}) {
+    try {
+        const instanceId = requireInstance(opts);
+        if (!opts.id || !opts.questionId)
+            throw createCliError('VALIDATION', '--id and --question-id are required');
+        const question = parseJsonInput(opts.question, opts.questionFile, 'question');
+        const client = await ldClientFor(opts, deps);
+        const res = await client.put(`${ADMIN}/${opts.id}/questions/${opts.questionId}`, question, {
+            params: { instanceId },
+        });
+        return ok(ldData(res));
+    }
+    catch (e) {
+        return fail(toLdCliError(e));
+    }
+}
+export async function runLdAssessmentReorderQuestions(opts, deps = {}) {
+    try {
+        const instanceId = requireInstance(opts);
+        if (!opts.id)
+            throw createCliError('VALIDATION', '--id is required');
+        if (!opts.questionIds?.length)
+            throw createCliError('VALIDATION', '--question-ids is required (comma-separated)');
+        const client = await ldClientFor(opts, deps);
+        const res = await client.put(`${ADMIN}/${opts.id}/questions/reorder`, { questionIds: opts.questionIds }, { params: { instanceId } });
+        return ok(ldData(res));
+    }
+    catch (e) {
+        return fail(toLdCliError(e));
+    }
+}
+export async function runLdAssessmentDeleteQuestion(opts, deps = {}) {
+    try {
+        const instanceId = requireInstance(opts);
+        if (!opts.id || !opts.questionId)
+            throw createCliError('VALIDATION', '--id and --question-id are required');
+        const client = await ldClientFor(opts, deps);
+        const res = await client.delete(`${ADMIN}/${opts.id}/questions/${opts.questionId}`, { params: { instanceId } });
+        return ok(ldData(res) ?? { removed: true });
+    }
+    catch (e) {
+        return fail(toLdCliError(e));
+    }
+}
+export async function runLdAssessmentPreviewStart(opts, deps = {}) {
+    try {
+        const instanceId = requireInstance(opts);
+        if (!opts.id)
+            throw createCliError('VALIDATION', '--id is required');
+        const client = await ldClientFor(opts, deps);
+        const res = await client.post(`${ADMIN}/${opts.id}/preview/start`, {}, { params: { instanceId } });
+        return ok(ldData(res));
+    }
+    catch (e) {
+        return fail(toLdCliError(e));
+    }
+}
+export async function runLdAssessmentPreviewGrade(opts, deps = {}) {
+    try {
+        const instanceId = requireInstance(opts);
+        if (!opts.id)
+            throw createCliError('VALIDATION', '--id is required');
+        const answers = parseJsonInput(opts.answers, opts.answersFile, 'answers');
+        const client = await ldClientFor(opts, deps);
+        const res = await client.post(`${ADMIN}/${opts.id}/preview/grade`, answers, { params: { instanceId } });
+        return ok(ldData(res));
+    }
+    catch (e) {
+        return fail(toLdCliError(e));
+    }
+}
+export async function runLdAssessmentListCourses(opts, deps = {}) {
+    try {
+        const instanceId = requireInstance(opts);
+        if (!opts.id)
+            throw createCliError('VALIDATION', '--id is required');
+        const client = await ldClientFor(opts, deps);
+        const res = await client.get(`${ADMIN}/${opts.id}/courses`, { params: { instanceId } });
+        return ok(ldData(res));
+    }
+    catch (e) {
+        return fail(toLdCliError(e));
+    }
+}
+// ---- commander subcommand ----
+export function createAssessmentSubcommand() {
+    const cmd = new Command('assessment').description('Author L&D assessments');
+    ldFlags(cmd.command('tags')).action(render(runLdAssessmentTags));
+    ldFlags(cmd.command('list')).option('--status <s>').option('--title <t>').option('--limit <n>', '', Number).option('--offset <n>', '', Number).action(render(runLdAssessmentList));
+    ldFlags(cmd.command('get')).option('--id <id>', 'Assessment ID (required)').action(render(runLdAssessmentGet));
+    ldFlags(cmd.command('create')).option('--title <t>', 'required').option('--description <d>').option('--passing-score <n>', 'integer', Number).option('--time-limit <n>', 'minutes, integer', Number).option('--max-attempts <n>', 'integer', Number).option('--tags <t>', 'Comma-separated', csv).action(render(runLdAssessmentCreate));
+    ldFlags(cmd.command('update')).option('--id <id>', 'required').option('--title <t>').option('--description <d>').option('--passing-score <n>', '', Number).option('--time-limit <n>', '', Number).option('--max-attempts <n>', '', Number).option('--status <s>', "published to publish").option('--tags <t>', 'Comma-separated', csv).action(render(runLdAssessmentUpdate));
+    ldFlags(cmd.command('delete')).option('--id <id>', 'required').action(render(runLdAssessmentDelete));
+    ldFlags(cmd.command('list-questions')).option('--id <id>', 'required').action(render(runLdAssessmentListQuestions));
+    ldFlags(cmd.command('add-question')).option('--id <id>', 'required').option('--question <json>', 'Inline question JSON').option('--question-file <path>').action(render(runLdAssessmentAddQuestion));
+    ldFlags(cmd.command('update-question')).option('--id <id>', 'required').option('--question-id <id>', 'required').option('--question <json>', 'Inline question JSON').option('--question-file <path>').action(render(runLdAssessmentUpdateQuestion));
+    ldFlags(cmd.command('reorder-questions')).option('--id <id>', 'required').option('--question-ids <ids>', 'Comma-separated (required)', csv).action(render(runLdAssessmentReorderQuestions));
+    ldFlags(cmd.command('delete-question')).option('--id <id>', 'required').option('--question-id <id>', 'required').action(render(runLdAssessmentDeleteQuestion));
+    ldFlags(cmd.command('preview-start')).option('--id <id>', 'required').action(render(runLdAssessmentPreviewStart));
+    ldFlags(cmd.command('preview-grade')).option('--id <id>', 'required').option('--answers <json>', 'Inline answers JSON').option('--answers-file <path>').action(render(runLdAssessmentPreviewGrade));
+    ldFlags(cmd.command('list-courses')).option('--id <id>', 'required').action(render(runLdAssessmentListCourses));
+    return cmd;
+}

package/dist/src/commands/ld/canvasCourse.d.ts

@@ -0,0 +1,20 @@
+import { Command } from 'commander';
+import { type Envelope } from '../../core/envelope.js';
+import { type LdCommonOpts, type LdDeps } from '../../core/ld.js';
+/**
+ * One-call canvas-course flow: create a draft (contentSource: canvas) → set the canvas
+ * content → optionally publish. The L&D backend has no transaction across these calls, so
+ * on a later-step failure we surface the created courseId in the error for recovery.
+ * NOTE: not idempotent — re-running creates a NEW draft each time; on a set-canvas/publish
+ * failure the created draft is left in place (recoverable via the returned courseId).
+ * createCourseSchema requires description/level/duration/sectionsCount, so we default them
+ * (a canvas course carries its content in the LearningCanvas, not sections/html).
+ */
+export declare function runLdCourseCreateCanvas(opts: LdCommonOpts & {
+    title?: string;
+    description?: string;
+    canvas?: string;
+    canvasFile?: string;
+    publish?: boolean;
+} & Record<string, unknown>, deps?: LdDeps): Promise<Envelope<unknown>>;
+export declare function createCanvasCourseSubcommand(): Command;

package/dist/src/commands/ld/canvasCourse.js

@@ -0,0 +1,69 @@
+import { Command } from 'commander';
+import { ok, fail } from '../../core/envelope.js';
+import { createCliError } from '../../core/errors.js';
+import { parseJsonInput } from '../../core/readInput.js';
+import { emitEnvelope } from '../../core/output.js';
+import { withAuthFlags } from '../withAuth.js';
+import { withInstanceFlag } from '../withInstance.js';
+import { toLdCliError } from '../../core/ld.js';
+import { runLdCourseCreate, runLdCourseSetCanvas, runLdCoursePublish } from './course.js';
+/**
+ * One-call canvas-course flow: create a draft (contentSource: canvas) → set the canvas
+ * content → optionally publish. The L&D backend has no transaction across these calls, so
+ * on a later-step failure we surface the created courseId in the error for recovery.
+ * NOTE: not idempotent — re-running creates a NEW draft each time; on a set-canvas/publish
+ * failure the created draft is left in place (recoverable via the returned courseId).
+ * createCourseSchema requires description/level/duration/sectionsCount, so we default them
+ * (a canvas course carries its content in the LearningCanvas, not sections/html).
+ */
+export async function runLdCourseCreateCanvas(opts, deps = {}) {
+    // Fail fast: validate the canvas JSON BEFORE creating the draft, so a missing/malformed
+    // --canvas doesn't mint an orphan draft that then fails at the set-canvas step.
+    try {
+        parseJsonInput(opts.canvas, opts.canvasFile, 'canvas');
+    }
+    catch (e) {
+        return fail(toLdCliError(e));
+    }
+    // Step 1: create the draft as a canvas course, defaulting the schema-required fields.
+    const created = await runLdCourseCreate({
+        ...opts,
+        contentSource: 'canvas',
+        description: opts.description || `Canvas course: ${opts.title ?? ''}`.trim(),
+        level: opts.level || 'Beginner',
+        duration: opts.duration ?? 5,
+        sectionsCount: opts.sectionsCount ?? 1,
+    }, deps);
+    if (!created.ok)
+        return created;
+    const courseId = created.data?._id ?? created.data?.id;
+    if (!courseId)
+        return fail(createCliError('UNKNOWN', 'course create returned no id'));
+    // Step 2: set the canvas content.
+    const setRes = await runLdCourseSetCanvas({ ...opts, id: courseId }, deps);
+    if (!setRes.ok) {
+        return fail(createCliError(setRes.error.code, `set-canvas failed for course ${courseId}: ${setRes.error.message}`));
+    }
+    // Step 3: optional publish.
+    if (opts.publish) {
+        const pub = await runLdCoursePublish({ ...opts, id: courseId }, deps);
+        if (!pub.ok) {
+            return fail(createCliError(pub.error.code, `publish failed for course ${courseId}: ${pub.error.message}`));
+        }
+    }
+    return ok({ courseId, published: Boolean(opts.publish), course: created.data });
+}
+export function createCanvasCourseSubcommand() {
+    // Leaf command: auth + instance flags go directly on it. NEVER .requiredOption (house rule);
+    // the run* enforces --title / --instance-id via VALIDATION guards.
+    const cmd = withInstanceFlag(withAuthFlags(new Command('create-canvas')))
+        .description('Create a canvas-based course in one step (create → set-canvas → publish)')
+        .option('--ld-url <url>', 'Override L&D API base URL (CLI only)')
+        .option('--title <t>', 'Course title (required)')
+        .option('--description <d>')
+        .option('--canvas <json>', 'Inline canvas JSON: object { content: { data: [...] }, theme? } (a bare content.data array is auto-wrapped)')
+        .option('--canvas-file <path>')
+        .option('--publish', 'Publish after authoring');
+    cmd.action(async (o, c) => emitEnvelope(await runLdCourseCreateCanvas({ ...c.optsWithGlobals(), ...o }), c.optsWithGlobals()));
+    return cmd;
+}

package/dist/src/commands/ld/cert.d.ts

@@ -0,0 +1,93 @@
+import { Command } from 'commander';
+import { type LdCommonOpts, type LdDeps } from '../../core/ld.js';
+import { type Envelope } from '../../core/envelope.js';
+export declare function runLdCertTags(opts: LdCommonOpts, deps?: LdDeps): Promise<Envelope<unknown>>;
+export declare function runLdCertList(opts: LdCommonOpts & {
+    status?: string;
+    title?: string;
+    tags?: string[];
+    limit?: number;
+    offset?: number;
+}, deps?: LdDeps): Promise<Envelope<unknown>>;
+export declare function runLdCertGet(opts: LdCommonOpts & {
+    id?: string;
+}, deps?: LdDeps): Promise<Envelope<unknown>>;
+export declare function runLdCertCreate(opts: LdCommonOpts & {
+    title?: string;
+    description?: string;
+    tags?: string[];
+    validityPeriod?: number;
+}, deps?: LdDeps): Promise<Envelope<unknown>>;
+export declare function runLdCertUpdate(opts: LdCommonOpts & {
+    id?: string;
+    title?: string;
+    description?: string;
+    tags?: string[];
+    validityPeriod?: number;
+}, deps?: LdDeps): Promise<Envelope<unknown>>;
+export declare function runLdCertDelete(opts: LdCommonOpts & {
+    id?: string;
+}, deps?: LdDeps): Promise<Envelope<unknown>>;
+export declare function runLdCertTrainingMaterials(opts: LdCommonOpts & {
+    id?: string;
+}, deps?: LdDeps): Promise<Envelope<unknown>>;
+export declare function runLdCertListModules(opts: LdCommonOpts & {
+    id?: string;
+}, deps?: LdDeps): Promise<Envelope<unknown>>;
+export declare function runLdCertAddModules(opts: LdCommonOpts & {
+    id?: string;
+    moduleIds?: string[];
+}, deps?: LdDeps): Promise<Envelope<unknown>>;
+export declare function runLdCertReorderModules(opts: LdCommonOpts & {
+    id?: string;
+    itemId?: string;
+    newOrder?: number;
+}, deps?: LdDeps): Promise<Envelope<unknown>>;
+export declare function runLdCertUpdateModule(opts: LdCommonOpts & {
+    id?: string;
+    moduleId?: string;
+    isRequired?: boolean;
+}, deps?: LdDeps): Promise<Envelope<unknown>>;
+export declare function runLdCertRemoveModule(opts: LdCommonOpts & {
+    id?: string;
+    moduleId?: string;
+}, deps?: LdDeps): Promise<Envelope<unknown>>;
+export declare function runLdCertListCourses(opts: LdCommonOpts & {
+    id?: string;
+}, deps?: LdDeps): Promise<Envelope<unknown>>;
+export declare function runLdCertAddCourses(opts: LdCommonOpts & {
+    id?: string;
+    courseIds?: string[];
+}, deps?: LdDeps): Promise<Envelope<unknown>>;
+export declare function runLdCertReorderCourses(opts: LdCommonOpts & {
+    id?: string;
+    itemId?: string;
+    newOrder?: number;
+}, deps?: LdDeps): Promise<Envelope<unknown>>;
+export declare function runLdCertUpdateCourse(opts: LdCommonOpts & {
+    id?: string;
+    courseId?: string;
+    isRequired?: boolean;
+}, deps?: LdDeps): Promise<Envelope<unknown>>;
+export declare function runLdCertRemoveCourse(opts: LdCommonOpts & {
+    id?: string;
+    courseId?: string;
+}, deps?: LdDeps): Promise<Envelope<unknown>>;
+export declare function runLdCertListAssessments(opts: LdCommonOpts & {
+    id?: string;
+}, deps?: LdDeps): Promise<Envelope<unknown>>;
+export declare function runLdCertAddAssessments(opts: LdCommonOpts & {
+    id?: string;
+    assessments?: string;
+    assessmentsFile?: string;
+}, deps?: LdDeps): Promise<Envelope<unknown>>;
+export declare function runLdCertUpdateAssessment(opts: LdCommonOpts & {
+    id?: string;
+    assessmentId?: string;
+    isRequired?: boolean;
+}, deps?: LdDeps): Promise<Envelope<unknown>>;
+export declare function runLdCertRemoveAssessment(opts: LdCommonOpts & {
+    id?: string;
+    assessmentId?: string;
+}, deps?: LdDeps): Promise<Envelope<unknown>>;
+export declare function createCertSubcommand(): Command;