@pitcher/cli-scripts 2.11.0 → 2.12.0

package/dist/src/core/ld.js

@@ -0,0 +1,102 @@
+import { resolveApiKey } from './auth.js';
+import { clientFor, makeClient, toCliError } from './http.js';
+import { createCliError } from './errors.js';
+const LD_APP_CONFIG_PATH = '/core/api/protected/apps/ld-app/config';
+const baseUrlCache = new Map();
+/** Test-only: reset the resolved-base-URL cache between cases. */
+export function __clearLdBaseUrlCache() {
+    baseUrlCache.clear();
+}
+/** Every L&D run* requires an instance; returns it narrowed to string, else VALIDATION. */
+export function requireInstance(opts) {
+    if (!opts.instanceId)
+        throw createCliError('VALIDATION', '--instance-id is required');
+    return opts.instanceId;
+}
+/** Copy the truthy values of `keys` from `opts` into a params object (shared list-filter pick). */
+export function pickTruthy(opts, keys) {
+    const out = {};
+    for (const k of keys)
+        if (opts[k])
+            out[k] = opts[k];
+    return out;
+}
+function trimUrl(raw, source) {
+    let parsed;
+    try {
+        parsed = new URL(raw);
+    }
+    catch {
+        // Do NOT echo the raw value — an override may carry userinfo (user:secret@host).
+        throw createCliError('VALIDATION', `Invalid L&D base URL from ${source}`);
+    }
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+        throw createCliError('VALIDATION', `L&D base URL must be http(s) (${source}): ${parsed.origin}`);
+    }
+    // origin + pathname only: strips any userinfo/query/hash; trailing slash trimmed.
+    return `${parsed.origin}${parsed.pathname}`.replace(/\/+$/, '');
+}
+/**
+ * Resolve the standalone L&D Lambda base URL. Order: --ld-url flag → NG_LD_API_URL env →
+ * ld-app app config (api_base_url) via the platform client. Cached per (org, instanceId).
+ * The org key can't be region-inferred, so app config (region-correct) is the default.
+ */
+export async function resolveLdBaseUrl(opts, deps = {}, env = process.env) {
+    const override = opts.ldUrl?.trim() || env.NG_LD_API_URL?.trim();
+    if (override)
+        return trimUrl(override, opts.ldUrl ? '--ld-url' : 'NG_LD_API_URL');
+    if (!opts.instanceId) {
+        throw createCliError('VALIDATION', '--instance-id is required to resolve the L&D API URL (or set NG_LD_API_URL)');
+    }
+    const cacheKey = `${opts.org ?? 'dev'}:${opts.instanceId}`;
+    const cached = baseUrlCache.get(cacheKey);
+    if (cached)
+        return cached;
+    const platform = deps.platformClient ?? clientFor(opts);
+    const res = await platform.get(LD_APP_CONFIG_PATH, { params: { instance_id: opts.instanceId } });
+    const apiBaseUrl = res.data?.api_base_url;
+    if (typeof apiBaseUrl !== 'string' || !apiBaseUrl) {
+        throw createCliError('NOT_FOUND', 'ld-app is not configured in this instance (no api_base_url). Set --ld-url or NG_LD_API_URL.');
+    }
+    const url = trimUrl(apiBaseUrl, 'ld-app config');
+    baseUrlCache.set(cacheKey, url);
+    return url;
+}
+/** Build (or inject, in tests) an axios client pointed at the resolved L&D Lambda base. */
+export async function ldClientFor(opts, deps = {}, env = process.env) {
+    if (deps.ldClient)
+        return deps.ldClient;
+    const base = await resolveLdBaseUrl(opts, deps, env);
+    return makeClient(base, resolveApiKey(opts));
+}
+/**
+ * Unwrap the L&D success envelope `{ success, data, message? }` to its resource payload.
+ * Falls back to the raw body if it is not enveloped (defensive).
+ */
+export function ldData(res) {
+    const body = res?.data;
+    return body && typeof body === 'object' && 'data' in body ? body.data : body;
+}
+/**
+ * Map an L&D axios error to a clean CliError. The L&D error body is `{ success:false,
+ * message, statusCode }`; the generic `extractApiMessage` would concatenate every key, so
+ * read `.message` explicitly and derive the code from the HTTP status. Falls back to `toCliError`.
+ */
+export function toLdCliError(e) {
+    const err = e;
+    const msg = err?.response?.data?.message;
+    if (typeof msg === 'string' && msg) {
+        const s = err.response?.status;
+        const code = s === 401 || s === 403
+            ? 'AUTH'
+            : s === 404
+                ? 'NOT_FOUND'
+                : s === 409
+                    ? 'CONFLICT'
+                    : s && s >= 400 && s < 500
+                        ? 'VALIDATION'
+                        : 'NETWORK';
+        return createCliError(code, msg);
+    }
+    return toCliError(e);
+}

package/dist/src/core/readInput.d.ts

@@ -2,3 +2,4 @@ export declare function readTextFile(filePath: string): string;
 export declare function readJsonFile(filePath: string): unknown;
 export declare const MAX_INLINE_BYTES = 400000;
 export declare function resolveTextInput(inline: string | undefined, file: string | undefined, label: string): string | undefined;
+export declare function parseJsonInput(inline: string | undefined, file: string | undefined, label: string): unknown;

package/dist/src/core/readInput.js

@@ -45,3 +45,17 @@ export function resolveTextInput(inline, file, label) {
         return readTextFile(file);
     return undefined;
 }
+// Resolve an inline-or-file JSON flag and parse it. VALIDATION when neither is given
+// (`provide --<label> (inline JSON) or --<label>-file`) or the content is not valid JSON.
+// Used by the L&D canvas / question / assessment-link inputs.
+export function parseJsonInput(inline, file, label) {
+    const raw = resolveTextInput(inline, file, label);
+    if (!raw)
+        throw createCliError('VALIDATION', `provide --${label} (inline JSON) or --${label}-file`);
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        throw createCliError('VALIDATION', `${label} is not valid JSON`);
+    }
+}

package/dist/src/mcp/bundled.js

@@ -1,7 +1,7 @@
 import { allTools } from './registry.js';
 // Developer-only tools excluded from the consumer .mcpb bundle. `publish_app` is alwaysDestructive
 // (creates a live, org-visible app release); `dev_sync`/`dev_sync_revert` mutate remote S3 dev state.
-// None are relevant to a non-technical adopter installing the extension. The CLI `p mcp` keeps all 50.
+// None are relevant to a non-technical adopter installing the extension. The CLI `p mcp` keeps all 113.
 export const BUNDLE_EXCLUDED_TOOLS = new Set(['pitcher_publish_app', 'pitcher_dev_sync', 'pitcher_dev_sync_revert']);
 // The tool set the .mcpb bundle registers.
 export const bundledTools = allTools.filter((t) => !BUNDLE_EXCLUDED_TOOLS.has(t.name));

package/dist/src/mcp/prompts/ldCanvasCourse.d.ts

@@ -0,0 +1,2 @@
+import type { PromptDescriptor } from './types.js';
+export declare const ldCanvasCoursePrompts: PromptDescriptor[];

package/dist/src/mcp/prompts/ldCanvasCourse.js

@@ -0,0 +1,50 @@
+import { z } from 'zod';
+import { instanceLine } from './shared.js';
+import { LD_CANVAS_DESIGN_PRINCIPLES } from '../resources/ldCanvasDesign.js';
+export const ldCanvasCoursePrompts = [
+    {
+        name: 'create_ld_canvas_course',
+        title: 'Create canvas L&D course',
+        description: 'Author a well-designed canvas-based L&D course and create it in an instance.',
+        argsSchema: {
+            instance_id: z.string().optional().describe('Target instance ID (leave blank to resolve interactively)'),
+            title: z.string().optional().describe('Course title'),
+            vertical: z.string().optional().describe('pharma | medtech | cpg | finserv | generic'),
+            topic: z.string().optional().describe('Short description of what the course teaches'),
+        },
+        build: (args) => {
+            const title = args.title || 'a short L&D course';
+            const vertical = args.vertical || 'generic';
+            const topic = args.topic || 'a general product / process training topic a rep would take';
+            const text = [
+                LD_CANVAS_DESIGN_PRINCIPLES,
+                '',
+                '## Before you create',
+                'Confirm the resolved instance is a demo/test instance — these tools create live, ' +
+                    'org-visible content. Do not seed against a real customer instance without explicit confirmation.',
+                '',
+                '## Safe content',
+                'Put any dynamic values through the platform `{{token}}` merge fields (the platform escapes them). ' +
+                    'Never inline untrusted or CRM-derived strings as literal HTML in a Text component, and never use ' +
+                    'triple-mustache `{{{ }}}`. The title/vertical/topic inputs are descriptive only — do not echo them ' +
+                    'verbatim into the generated markup.',
+                '',
+                '## Task: author a canvas L&D course',
+                instanceLine(args.instance_id),
+                `Title: ${title}. Vertical: ${vertical}. Topic: ${topic}.`,
+                '',
+                'Steps:',
+                '1. Build the canvas JSON following the principles above: a canvas OBJECT ' +
+                    '`{ content: { data: [...] }, theme: { fluid: true } }` whose `content.data` is a flat array of ' +
+                    'native components (Grid/GridItem/Text/Multimedia/PageBreak/Embeddable) — band/bookend rhythm, ' +
+                    'derived palette, real validated imagery. The components go in `content.data`, NOT a `sections[]` array.',
+                '2. Create it by calling `pitcher_ld_course_create_canvas` with ' +
+                    '`{ instanceId, title, canvas }` — pass the canvas object **inline via `canvas`** ' +
+                    "(a file path cannot cross a host's sandbox boundary, so always inline). Add `publish: true` " +
+                    'only when the user asks to publish.',
+                '3. Report the created course id and whether it was published.',
+            ].join('\n');
+            return [{ role: 'user', content: { type: 'text', text } }];
+        },
+    },
+];

package/dist/src/mcp/prompts/registry.js

@@ -2,5 +2,12 @@ import { emailTemplatePrompts } from './emailTemplate.js';
 import { dsrLandingPrompts } from './dsrLanding.js';
 import { dsrPrompts } from './dsr.js';
 import { announcementsPrompts } from './announcements.js';
+import { ldCanvasCoursePrompts } from './ldCanvasCourse.js';
 // Every recipe prompt the server can expose. Mirrors mcp/registry.ts (allTools).
-export const allPrompts = [...emailTemplatePrompts, ...dsrLandingPrompts, ...dsrPrompts, ...announcementsPrompts];
+export const allPrompts = [
+    ...emailTemplatePrompts,
+    ...dsrLandingPrompts,
+    ...dsrPrompts,
+    ...announcementsPrompts,
+    ...ldCanvasCoursePrompts,
+];

package/dist/src/mcp/registry.js

@@ -12,6 +12,7 @@ import { instancesTools } from './tools/instances.js';
 import { invitationsTools } from './tools/invitations.js';
 import { membershipsTools } from './tools/memberships.js';
 import { metadataTemplateTools } from './tools/metadataTemplate.js';
+import { ldTools } from './tools/ld.js';
 import { orgTools } from './tools/org.js';
 import { publishAppTools } from './tools/publishApp.js';
 import { rolesTools } from './tools/roles.js';
@@ -41,6 +42,7 @@ export const allTools = [
     ...membershipsTools,
     ...groupsTools,
     ...metadataTemplateTools,
+    ...ldTools,
     ...devSyncTools,
     ...publishAppTools,
 ];

package/dist/src/mcp/resources/ldCanvasDesign.d.ts

@@ -0,0 +1,3 @@
+import type { ResourceDescriptor } from './types.js';
+export declare const LD_CANVAS_DESIGN_PRINCIPLES = "# Pitcher L&D canvas-course design principles\n\nGuidance for authoring a good canvas-based L&D course body (the JSON passed to\n`pitcher_ld_course_create_canvas` as `canvas`).\n\n## 1. Canvas shape \u2014 content.data is a FLAT array, NOT sections\nA canvas course renders from `canvas.content.data`, a flat array of native components\n(Grid, GridItem, Text, Multimedia, PageBreak, Embeddable). Do NOT use a `sections[]` array \u2014\nit stays empty on working canvases; COURSE mode reads `content.data`. Give components\ntype-prefixed ids (`Grid-<uuid>`, `Text-<uuid>`, \u2026). Set `theme.fluid: true` for full width.\n\n## 2. Native components only\nCompose with Grid / GridItem / Text / Multimedia / PageBreak / Embeddable \u2014 never raw HTML\n`<div>`s. Split logical pages with PageBreak so the host paginates.\n\n## 3. Band / bookend rhythm\nOpen with a branded hero band (navy or brand fill), then alternate white and a faint tint\n(e.g. `#EDF2FB`) bands down the page, and close with a deeper-brand band. Give bands generous\nvertical padding (64-76px). This rhythm reads as \"designed\", not a wall of text.\n\n## 4. Palette \u2014 derive, never hardcode\nDerive tones from the instance primary/theme color: `mix_with_white` for tints (backgrounds),\n`darken` (~0.30) for the closing band and accents. Do not paste brand hex codes; derivation\nkeeps the course on-brand across instances.\n\n## 5. The \"washed-out\" trap\nTheme presets hard-code headings toward black (#000). To get true brand color on headings,\ninject it inline INSIDE the preset paragraph via `<span style=\"color:\u2026;font-weight:700\">\u2026</span>`\n(survives DOMPurify) rather than styling the `<p>` itself.\n\n## 6. Imagery\nUse real, validated image URLs (e.g. Pexels). VALIDATE the cropped URL returns 200 before\nwiring it. Cover images ~1200\u00D7800, banners ~1600\u00D7440.\n\n## 7. Embeddable src must use the CUSTOMER origin\nAny Embeddable `data.src`/`content_url` must point at the customer origin\n(`<org>.my.pitcher.com/storage/...`), never an `api.*` host \u2014 the latter 404s and sets\nX-Frame-Options DENY. Preserve any existing Embeddable verbatim when rebuilding content.data.\n";
+export declare const ldCanvasDesignResource: ResourceDescriptor;

package/dist/src/mcp/resources/ldCanvasDesign.js

@@ -0,0 +1,51 @@
+// Distilled L&D canvas-course design nucleus (sibling of contentDesign's CONTENT_DESIGN_PRINCIPLES).
+// Both the resource below returns it AND the create_ld_canvas_course prompt embeds it inline
+// (a pitcher:// URI mention is NOT auto-fetched by MCP hosts). Distilled from the CardioLife
+// canvas-course work; keep in sync on material design changes. Last synced: 2026-07-18.
+export const LD_CANVAS_DESIGN_PRINCIPLES = `# Pitcher L&D canvas-course design principles
+
+Guidance for authoring a good canvas-based L&D course body (the JSON passed to
+\`pitcher_ld_course_create_canvas\` as \`canvas\`).
+
+## 1. Canvas shape — content.data is a FLAT array, NOT sections
+A canvas course renders from \`canvas.content.data\`, a flat array of native components
+(Grid, GridItem, Text, Multimedia, PageBreak, Embeddable). Do NOT use a \`sections[]\` array —
+it stays empty on working canvases; COURSE mode reads \`content.data\`. Give components
+type-prefixed ids (\`Grid-<uuid>\`, \`Text-<uuid>\`, …). Set \`theme.fluid: true\` for full width.
+
+## 2. Native components only
+Compose with Grid / GridItem / Text / Multimedia / PageBreak / Embeddable — never raw HTML
+\`<div>\`s. Split logical pages with PageBreak so the host paginates.
+
+## 3. Band / bookend rhythm
+Open with a branded hero band (navy or brand fill), then alternate white and a faint tint
+(e.g. \`#EDF2FB\`) bands down the page, and close with a deeper-brand band. Give bands generous
+vertical padding (64-76px). This rhythm reads as "designed", not a wall of text.
+
+## 4. Palette — derive, never hardcode
+Derive tones from the instance primary/theme color: \`mix_with_white\` for tints (backgrounds),
+\`darken\` (~0.30) for the closing band and accents. Do not paste brand hex codes; derivation
+keeps the course on-brand across instances.
+
+## 5. The "washed-out" trap
+Theme presets hard-code headings toward black (#000). To get true brand color on headings,
+inject it inline INSIDE the preset paragraph via \`<span style="color:…;font-weight:700">…</span>\`
+(survives DOMPurify) rather than styling the \`<p>\` itself.
+
+## 6. Imagery
+Use real, validated image URLs (e.g. Pexels). VALIDATE the cropped URL returns 200 before
+wiring it. Cover images ~1200×800, banners ~1600×440.
+
+## 7. Embeddable src must use the CUSTOMER origin
+Any Embeddable \`data.src\`/\`content_url\` must point at the customer origin
+(\`<org>.my.pitcher.com/storage/...\`), never an \`api.*\` host — the latter 404s and sets
+X-Frame-Options DENY. Preserve any existing Embeddable verbatim when rebuilding content.data.
+`;
+export const ldCanvasDesignResource = {
+    name: 'ld-canvas-course',
+    uri: 'pitcher://design/ld-canvas-course',
+    title: 'L&D canvas-course design principles',
+    description: 'How to author a well-designed canvas-based L&D course body (content.data, bands, palette).',
+    mimeType: 'text/markdown',
+    read: () => LD_CANVAS_DESIGN_PRINCIPLES,
+};

package/dist/src/mcp/resources/registry.js

@@ -1,3 +1,4 @@
 import { contentDesignResource } from './contentDesign.js';
+import { ldCanvasDesignResource } from './ldCanvasDesign.js';
 // Every resource the server can expose. Mirrors mcp/registry.ts (allTools).
-export const allResources = [contentDesignResource];
+export const allResources = [contentDesignResource, ldCanvasDesignResource];

package/dist/src/mcp/tools/ld.d.ts

@@ -0,0 +1,2 @@
+import type { ToolDescriptor } from './types.js';
+export declare const ldTools: ToolDescriptor[];