@pitcher/cli-scripts 2.17.1 → 2.19.0

package/dist/src/core/archive.js

@@ -1,9 +1,9 @@
-import archiver from 'archiver';
+import { ZipArchive } from 'archiver';
 import fs from 'fs';
 export async function zipDirectoryToBuffer(dir) {
     return new Promise((resolve, reject) => {
         const chunks = [];
-        const archive = archiver('zip', { zlib: { level: 9 } });
+        const archive = new ZipArchive({ zlib: { level: 9 } });
         archive.on('data', (chunk) => chunks.push(chunk));
         archive.on('end', () => resolve(Buffer.concat(chunks)));
         archive.on('error', reject);
@@ -14,7 +14,7 @@ export async function zipDirectoryToBuffer(dir) {
 export async function zipDirectoryToFile(dir, outPath) {
     return new Promise((resolve, reject) => {
         const output = fs.createWriteStream(outPath);
-        const archive = archiver('zip', { zlib: { level: 9 } });
+        const archive = new ZipArchive({ zlib: { level: 9 } });
         output.on('close', () => resolve(archive.pointer()));
         output.on('error', reject);
         archive.on('error', reject);

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

@@ -0,0 +1,25 @@
+/**
+ * The credential a request is sent with. `apiKey` is the Knox key the CLI (and stdio `p mcp`) has
+ * always used; `bearer` is a user's Auth0 access token, used by the hosted MCP server (PIT-8912).
+ */
+export type Credential = {
+    kind: 'bearer';
+    token: string;
+} | {
+    kind: 'apiKey';
+    key: string;
+};
+/** The auth header(s) for a credential. Exactly one header, never both. */
+export declare function authHeaders(c: Credential): Record<string, string>;
+/**
+ * The ONE credential resolver every call site uses.
+ *
+ * An explicit `credential` always wins and never falls through: a bearer context must fail CLOSED,
+ * so it can never pick up `--api-key` or `NG_API_KEY` from the process env (the hosted server
+ * would otherwise act as whoever minted that key). Only when no credential is given (CLI / stdio)
+ * does this reach `resolveApiKey`, which reads `--api-key` then `NG_API_KEY`.
+ */
+export declare function credentialOf(opts: {
+    apiKey?: string;
+    credential?: Credential;
+}): Credential;

package/dist/src/core/credential.js

@@ -0,0 +1,25 @@
+import { resolveApiKey } from './auth.js';
+import { createCliError } from './errors.js';
+/** The auth header(s) for a credential. Exactly one header, never both. */
+export function authHeaders(c) {
+    return c.kind === 'bearer' ? { authorization: `Bearer ${c.token}` } : { 'x-api-key': c.key };
+}
+/**
+ * The ONE credential resolver every call site uses.
+ *
+ * An explicit `credential` always wins and never falls through: a bearer context must fail CLOSED,
+ * so it can never pick up `--api-key` or `NG_API_KEY` from the process env (the hosted server
+ * would otherwise act as whoever minted that key). Only when no credential is given (CLI / stdio)
+ * does this reach `resolveApiKey`, which reads `--api-key` then `NG_API_KEY`.
+ */
+export function credentialOf(opts) {
+    const c = opts.credential;
+    if (c) {
+        const value = c.kind === 'bearer' ? c.token : c.key;
+        if (typeof value !== 'string' || !value.trim()) {
+            throw createCliError('AUTH', `Empty ${c.kind === 'bearer' ? 'bearer token' : 'API key'} credential`);
+        }
+        return c;
+    }
+    return { kind: 'apiKey', key: resolveApiKey(opts) };
+}

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

@@ -1,8 +1,13 @@
 import { type AxiosInstance } from 'axios';
+import { type Credential } from './credential.js';
 import { type CliError } from './errors.js';
-export declare function makeClient(baseUrl: string, apiKey: string): AxiosInstance;
+export declare function makeClient(baseUrl: string, cred: Credential, opts?: {
+    maxRedirects?: number;
+}): AxiosInstance;
 export interface CommonOpts {
     apiKey?: string;
+    /** Explicit credential (hosted MCP: a user's bearer token). Wins over `apiKey`/`NG_API_KEY` — see `credentialOf`. */
+    credential?: Credential;
     org?: string;
     url?: string;
     quiet?: boolean;
@@ -24,7 +29,8 @@ export declare function clickhouseClientFor(opts: CommonOpts, deps?: {
 /**
  * Build a human-readable message from a server error body. Handles DRF shapes:
  * a `detail`/`error` string, `non_field_errors`, and field-level error arrays
- * (e.g. `{ version: ["already exists"] }`). Falls back to the raw body so the
+ * (e.g. `{ version: ["already exists"] }`), plus next-core's
+ * `{ error, details }` validation shape. Falls back to the raw body so the
  * full server response is visible in logs instead of a bare status line.
  */
 export declare function extractApiMessage(data: unknown, fallback: string): string;

package/dist/src/core/http.js

@@ -1,19 +1,20 @@
 import axios from 'axios';
-import { resolveApiKey } from './auth.js';
 import { resolveBaseUrl } from './baseUrl.js';
+import { authHeaders, credentialOf } from './credential.js';
 import { createCliError, isCliError } from './errors.js';
-export function makeClient(baseUrl, apiKey) {
+export function makeClient(baseUrl, cred, opts = {}) {
     return axios.create({
+        ...opts,
         baseURL: baseUrl,
         headers: {
             accept: 'application/json',
-            'x-api-key': apiKey,
+            ...authHeaders(cred),
         },
     });
 }
 /** Resolve auth + base URL into a client, or use an injected one (tests). */
 export function clientFor(opts, deps = {}) {
-    return deps.client ?? makeClient(resolveBaseUrl({ org: opts.org, url: opts.url }), resolveApiKey(opts));
+    return deps.client ?? makeClient(resolveBaseUrl({ org: opts.org, url: opts.url }), credentialOf(opts));
 }
 export const CLICKHOUSE_API_BASE_URL = 'https://clickhouse.pitcher.com';
 /**
@@ -30,15 +31,163 @@ export function clickhouseClientFor(opts, deps = {}) {
         baseURL: CLICKHOUSE_API_BASE_URL,
         headers: {
             accept: 'application/json',
-            'x-api-key': resolveApiKey(opts),
+            ...authHeaders(credentialOf(opts)),
             'x-original-domain': originalDomain,
         },
     });
 }
+/** Max number of `details` entries folded into a message before it is summarised. */
+const MAX_DETAIL_PARTS = 3;
+/** Max characters of joined `details` text, before the `(+N more)` marker is appended. */
+const MAX_DETAIL_CHARS = 200;
+/** How deep to walk a nested `details` value before falling back to JSON. */
+const MAX_DETAIL_DEPTH = 3;
+/**
+ * DRF envelope keys: the two places a serializer puts a message that names no field.
+ * next-core's `upstreamErrorMessage()` (`app/api/utils/upstream-error.ts`) reads `detail`
+ * first and sorts `non_field_errors` ahead of everything else, so a summary derived from a
+ * relayed upstream body is usually one of these two verbatim. Every other key IS a field
+ * name, and naming the field is the whole point of folding `details` in — so only a line
+ * from one of these keys may be dropped for merely repeating the summary.
+ */
+const ENVELOPE_KEYS = new Set(['detail', 'non_field_errors']);
+/**
+ * `JSON.stringify` throws on a circular structure and on a BigInt. This runs inside the
+ * error formatter, so a throw here would lose the API error entirely and print a raw
+ * stack instead — every failure has to collapse to a string.
+ */
+function safeDetailJson(val) {
+    try {
+        const text = JSON.stringify(val, (_key, entry) => (typeof entry === 'bigint' ? String(entry) : entry));
+        return text ?? '[unserializable]';
+    }
+    catch {
+        return '[unserializable]';
+    }
+}
+/**
+ * Whether an array entry already identifies itself in the output. A zod issue carries
+ * its own `path`, and an entry that renders as a single scalar (`{ title: ['Required'] }`)
+ * reads better bare; anything else gets an `[i]` so entries do not blur together.
+ */
+function labelsItself(entry) {
+    if (typeof entry !== 'object' || entry === null)
+        return true;
+    return typeof entry.message === 'string';
+}
+/**
+ * Flatten one `details` value into human-readable, path-prefixed lines.
+ *
+ * next-core emits several shapes for the same field: zod issues
+ * (`[{ path, message }]`, from `_4xx('Invalid request data', 400, { details: error.errors })`),
+ * a `zod.flatten()` object, a relayed upstream body (`{ details: error.response.data }`),
+ * a plain object (`{ details: { id } }`) and a bare string. All of them collapse to
+ * `path: message` lines here.
+ *
+ * The walk is total: every recursive branch sits below the depth guard, and the guard's
+ * own fallback cannot throw.
+ *
+ * `envelope` marks the lines that descend from a top-level `ENVELOPE_KEYS` key; it is what
+ * lets `renderDetails` drop a relay echo without dropping a labelled field error.
+ */
+function detailParts(val, prefix = '', depth = 0, envelope = false) {
+    if (val == null)
+        return [];
+    const part = (value) => value ? [{ text: prefix ? `${prefix}: ${value}` : value, value, envelope }] : [];
+    if (typeof val === 'string')
+        return part(val.trim());
+    if (typeof val === 'number' || typeof val === 'boolean')
+        return part(String(val));
+    if (typeof val !== 'object')
+        return [];
+    // zod issue shape: `{ path: ['canvas_id'], message: 'Invalid ULID format for canvas_id' }`.
+    // A leaf, so it is answered above the depth guard.
+    if (!Array.isArray(val)) {
+        const obj = val;
+        if (typeof obj.message === 'string' && obj.message.trim()) {
+            const path = Array.isArray(obj.path) ? obj.path.join('.') : '';
+            const scope = [prefix, path].filter(Boolean).join('.');
+            const value = obj.message.trim();
+            return [{ text: scope ? `${scope}: ${value}` : value, value, envelope }];
+        }
+    }
+    if (depth >= MAX_DETAIL_DEPTH)
+        return part(safeDetailJson(val));
+    if (Array.isArray(val)) {
+        return val.flatMap((entry, i) => detailParts(entry, labelsItself(entry) ? prefix : `${prefix}[${i}]`, depth + 1, envelope));
+    }
+    const obj = val;
+    return Object.entries(obj).flatMap(([key, entry]) => 
+    // Only a key at the root of `details` can be the envelope — `{ canvas: { detail: … } }`
+    // is a field named `canvas`, not a DRF envelope.
+    detailParts(entry, prefix ? `${prefix}.${key}` : key, depth + 1, envelope || (!prefix && ENVELOPE_KEYS.has(key))));
+}
+/** Cut `text` to `max` code points — never splitting a surrogate pair — and mark the cut. */
+function truncateDetails(text, max) {
+    const points = [...text];
+    if (points.length <= max)
+        return text;
+    return `${points.slice(0, max - 1).join('').trimEnd()}\u2026`;
+}
+/**
+ * Flatten a `details` value into one capped, de-duplicated line.
+ *
+ * When `summary` is given, two kinds of echo are suppressed, and only these two:
+ *   - a whole rendered line equal to the summary (`_400Validation` in next-core answers a
+ *     failed parse with `"<path>: <message>"`, which is exactly how the same issue renders
+ *     here), and
+ *   - a line from a DRF envelope key (`ENVELOPE_KEYS`) whose message equals the summary —
+ *     the relay path, where `next-core .../shared-links/route.ts` builds its summary with
+ *     `upstreamErrorMessage(body)` and then relays that same body as `details`, so the most
+ *     common `p dsr` 400 would otherwise print `Not found. | detail: Not found.`
+ *
+ * A *field* entry is never dropped for matching the summary, however: in
+ * `{ error: 'This field is required.', details: { canvas: [...], expires_at: [...] } }` the
+ * field path is the only thing telling the user which field, and dropping `canvas` there
+ * left the message actively misleading (PR #5570 review).
+ *
+ * Output is capped so a large validation payload cannot become a wall of text. The
+ * `(+N more)` marker is appended after the cap, so it is never cut into a wrong count.
+ */
+function renderDetails(details, summary) {
+    const seen = new Set();
+    const parts = [];
+    let dropped = 0;
+    for (const { text, value, envelope } of detailParts(details)) {
+        if (summary !== undefined && (text === summary || (envelope && value === summary)))
+            continue;
+        if (seen.has(text))
+            continue;
+        seen.add(text);
+        if (parts.length < MAX_DETAIL_PARTS)
+            parts.push(text);
+        else
+            dropped += 1;
+    }
+    if (!parts.length)
+        return '';
+    let text = truncateDetails(parts.join('; '), MAX_DETAIL_CHARS);
+    if (dropped > 0)
+        text += ` (+${dropped} more)`;
+    return text;
+}
+/**
+ * Fold an error body's `details` into the top-level summary so the user sees both
+ * halves on one line — next-core answers a failed schema parse with a generic
+ * `"Invalid request data"` and puts the only actionable text (the field and why it
+ * was rejected) in `details`, which used to be dropped entirely (PIT-7521).
+ */
+function withDetails(summary, details) {
+    if (details === undefined)
+        return summary;
+    const text = renderDetails(details, summary);
+    return text ? `${summary} | ${text}` : summary;
+}
 /**
  * Build a human-readable message from a server error body. Handles DRF shapes:
  * a `detail`/`error` string, `non_field_errors`, and field-level error arrays
- * (e.g. `{ version: ["already exists"] }`). Falls back to the raw body so the
+ * (e.g. `{ version: ["already exists"] }`), plus next-core's
+ * `{ error, details }` validation shape. Falls back to the raw body so the
  * full server response is visible in logs instead of a bare status line.
  */
 export function extractApiMessage(data, fallback) {
@@ -50,11 +199,22 @@ export function extractApiMessage(data, fallback) {
         return String(data);
     const obj = data;
     if (typeof obj.detail === 'string' && obj.detail)
-        return obj.detail;
+        return withDetails(obj.detail, obj.details);
     if (typeof obj.error === 'string' && obj.error)
-        return obj.error;
+        return withDetails(obj.error, obj.details);
     const parts = [];
     for (const [key, val] of Object.entries(obj)) {
+        // A body carrying `details` but no string `detail`/`error` summary lands here. next-core
+        // cannot produce that shape (`_4xx` always emits `{ error: message, ...data }`), but Django
+        // or another upstream can — and the generic rendering below would `join('; ')` structured
+        // entries into `details: [object Object]`, so walk it the same way `withDetails` does.
+        if (key === 'details') {
+            const rendered = renderDetails(val);
+            if (rendered) {
+                parts.push(rendered);
+                continue;
+            }
+        }
         const text = Array.isArray(val) ? val.join('; ') : typeof val === 'string' ? val : JSON.stringify(val);
         parts.push(key === 'non_field_errors' ? text : `${key}: ${text}`);
     }

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

@@ -1,4 +1,4 @@
-import type { AxiosInstance } from 'axios';
+import { type AxiosInstance } from 'axios';
 import { type CommonOpts } from './http.js';
 import { type CliError } from './errors.js';
 export interface LdCommonOpts extends CommonOpts {
@@ -8,7 +8,17 @@ export interface LdCommonOpts extends CommonOpts {
 export interface LdDeps {
     ldClient?: AxiosInstance;
     platformClient?: AxiosInstance;
+    /** Test seam for the bearer → L&D token exchange POST (`{ldBase}/auth/token`). */
+    ldAuthClient?: AxiosInstance;
 }
+/** The exact hosts a bearer credential may be sent to. An unusable `LD_ALLOWED_HOSTS` entry fails closed. */
+export declare function ldAllowedHosts(env?: NodeJS.ProcessEnv): Set<string>;
+/**
+ * Resolved L&D base URL per (platform host, instance). Bounded in TIME, not just per process: the
+ * hosted MCP server is one long-lived process, so an admin re-pointing an instance's ld-app
+ * `api_base_url` must take effect without a restart.
+ */
+export declare const LD_BASE_URL_TTL_MS: number;
 /** Test-only: reset the resolved-base-URL cache between cases. */
 export declare function __clearLdBaseUrlCache(): void;
 /** Every L&D run* requires an instance; returns it narrowed to string, else VALIDATION. */
@@ -29,7 +39,33 @@ export declare function pickTruthy<T extends object>(opts: T, keys: readonly (ke
  * over a credential the CLI actually holds.
  */
 export declare function resolveLdBaseUrl(opts: LdCommonOpts, deps?: LdDeps, env?: NodeJS.ProcessEnv): Promise<string>;
-/** Build (or inject, in tests) an axios client pointed at the resolved L&D Lambda base. */
+/** Max cached L&D tokens (one per distinct Pitcher token × L&D base). Oldest-used evicted first. */
+export declare const LD_TOKEN_CACHE_MAX = 500;
+/** Test-only: reset the L&D token-exchange cache between cases. */
+export declare function __clearLdTokenCache(): void;
+/** Test-only: current number of cached L&D tokens. */
+export declare function __ldTokenCacheSize(): number;
+/**
+ * The client that POSTs the user's token. `maxRedirects: 0` is load-bearing: axios follows 307/308 and
+ * RE-SENDS the body, so an allowlisted host answering 307 would forward the token to any host it names —
+ * straight past the allowlist. A 3xx is therefore a failed exchange (non-2xx), never followed.
+ */
+export declare function createLdAuthHttp(): AxiosInstance;
+/**
+ * Exchange a Pitcher (Auth0) access token for an L&D JWT at `POST {ldBase}/auth/token {token}`.
+ * The L&D envelope is `{ success, message, data: { token, refreshToken, user }, statusCode }`, so the
+ * JWT is at `res.data.data.token` (ld-app `authController.ts`).
+ *
+ * Cached until `min(L&D exp, Pitcher exp) − 60 s`: the L&D JWT embeds the Pitcher token, so it is
+ * useless once that expires, and its own lifetime is env-configurable (`JWT_EXPIRES_IN`), so neither
+ * is assumed. A token whose TTL cannot be read, or is already ≤ 0, is used once and not cached.
+ */
+export declare function exchangeLdToken(ldBase: string, pitcherToken: string, deps: LdDeps, env: NodeJS.ProcessEnv): Promise<string>;
+/**
+ * Build (or inject, in tests) an axios client pointed at the resolved L&D Lambda base.
+ * API key → sent as-is (`x-api-key`). Bearer → exchanged for an L&D JWT first (the Lambda does not
+ * accept an Auth0 token directly), and that JWT is sent as the bearer.
+ */
 export declare function ldClientFor(opts: LdCommonOpts, deps?: LdDeps, env?: NodeJS.ProcessEnv): Promise<AxiosInstance>;
 /**
  * Unwrap the L&D success envelope `{ success, data, message? }` to its resource payload.

package/dist/src/core/ld.js

@@ -1,4 +1,6 @@
-import { resolveApiKey } from './auth.js';
+import axios from 'axios';
+import { createHash } from 'crypto';
+import { credentialOf } from './credential.js';
 import { clientFor, makeClient, toCliError } from './http.js';
 import { resolveBaseUrl } from './baseUrl.js';
 import { createCliError } from './errors.js';
@@ -41,6 +43,50 @@ const LD_FALLBACK_BASE_URL = 'https://cgmfr9gjza.execute-api.eu-west-1.amazonaws
  * what points each instance at it — the fallback must never silently stand in.
  */
 const LD_FALLBACK_PLATFORM_ORIGIN = 'https://dev.my.pitcher.com';
+/**
+ * Bearer mode (the hosted MCP server) sends the USER's Pitcher Auth0 access token to
+ * `POST {ldBase}/auth/token`. `ldBase` can come from `metadata.api_base_url`, which any
+ * instance admin can write — so without a gate an admin could point it at a host they own and
+ * collect every user's token (plus SSRF from the server). In bearer mode the resolved base
+ * must therefore be `https:` on an EXACT allowlisted host (no port, no wildcard, no suffix
+ * match — anyone can mint a `*.execute-api` host). Default = the fallback Lambda's host;
+ * `LD_ALLOWED_HOSTS` (comma-separated exact hostnames) extends it. API-key mode is unchanged.
+ */
+const LD_DEFAULT_ALLOWED_HOST = new URL(LD_FALLBACK_BASE_URL).host;
+/** The exact hosts a bearer credential may be sent to. An unusable `LD_ALLOWED_HOSTS` entry fails closed. */
+export function ldAllowedHosts(env = process.env) {
+    const hosts = new Set([LD_DEFAULT_ALLOWED_HOST]);
+    for (const raw of (env.LD_ALLOWED_HOSTS ?? '').split(',')) {
+        const entry = raw.trim().toLowerCase();
+        if (!entry)
+            continue;
+        if (!/^[a-z0-9-]+(\.[a-z0-9-]+)+$/.test(entry)) {
+            throw createCliError('VALIDATION', `LD_ALLOWED_HOSTS entries must be exact hostnames (no wildcard/port/scheme): ${entry}`);
+        }
+        hosts.add(entry);
+    }
+    return hosts;
+}
+/**
+ * Fail CLOSED unless `url` is safe to receive a bearer token. The message names the host, never the
+ * token. Called at resolution AND immediately before the exchange POST (defence in depth).
+ */
+function assertBearerLdBase(url, env) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw createCliError('VALIDATION', 'LD_HOST_NOT_ALLOWED: the L&D base URL is not a valid URL');
+    }
+    if (parsed.protocol !== 'https:') {
+        throw createCliError('VALIDATION', `LD_HOST_NOT_ALLOWED: the L&D base URL must be https (got ${parsed.protocol})`);
+    }
+    if (!ldAllowedHosts(env).has(parsed.host)) {
+        throw createCliError('VALIDATION', `LD_HOST_NOT_ALLOWED: ${parsed.host} is not an allowed L&D host for a signed-in user. ` +
+            `Add it to LD_ALLOWED_HOSTS on the server if it is a genuine L&D deployment.`);
+    }
+}
 /**
  * Safety stop for the installed-apps scan. At 500 records/page this is 10k apps in one
  * instance — unreachable in practice, so tripping it means the server kept advertising a
@@ -51,6 +97,12 @@ const MAX_APP_PAGES = 20;
 function isRecord(v) {
     return typeof v === 'object' && v !== null && !Array.isArray(v);
 }
+/**
+ * Resolved L&D base URL per (platform host, instance). Bounded in TIME, not just per process: the
+ * hosted MCP server is one long-lived process, so an admin re-pointing an instance's ld-app
+ * `api_base_url` must take effect without a restart.
+ */
+export const LD_BASE_URL_TTL_MS = 10 * 60000;
 const baseUrlCache = new Map();
 /** Test-only: reset the resolved-base-URL cache between cases. */
 export function __clearLdBaseUrlCache() {
@@ -176,6 +228,13 @@ async function fetchLdAppMetadata(platform, instanceId) {
  * over a credential the CLI actually holds.
  */
 export async function resolveLdBaseUrl(opts, deps = {}, env = process.env) {
+    const url = await resolveLdBaseUrlUnchecked(opts, deps, env);
+    // Every source (flag, env, instance metadata, fallback, cache) is checked, on every call.
+    if (opts.credential?.kind === 'bearer')
+        assertBearerLdBase(url, env);
+    return url;
+}
+async function resolveLdBaseUrlUnchecked(opts, deps, 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');
@@ -186,8 +245,8 @@ export async function resolveLdBaseUrl(opts, deps = {}, env = process.env) {
     // different platform hosts collide on one cached L&D URL within a single process.
     const cacheKey = `${opts.url ?? opts.org ?? 'dev'}:${opts.instanceId}`;
     const cached = baseUrlCache.get(cacheKey);
-    if (cached)
-        return cached;
+    if (cached && cached.expiresAt > Date.now())
+        return cached.url;
     const platform = deps.platformClient ?? clientFor(opts);
     const metadata = await fetchLdAppMetadata(platform, opts.instanceId);
     if (!metadata) {
@@ -209,15 +268,112 @@ export async function resolveLdBaseUrl(opts, deps = {}, env = process.env) {
         }
         url = LD_FALLBACK_BASE_URL;
     }
-    baseUrlCache.set(cacheKey, url);
+    baseUrlCache.set(cacheKey, { url, expiresAt: Date.now() + LD_BASE_URL_TTL_MS });
     return url;
 }
-/** Build (or inject, in tests) an axios client pointed at the resolved L&D Lambda base. */
+/** Max cached L&D tokens (one per distinct Pitcher token × L&D base). Oldest-used evicted first. */
+export const LD_TOKEN_CACHE_MAX = 500;
+/** Safety margin subtracted from the earliest expiry, so a cached token is never used at the edge. */
+const LD_TOKEN_SKEW_MS = 60000;
+/**
+ * Bearer → L&D token cache, keyed `sha256(pitcherToken)|ldBase` (the raw token is never a key).
+ * A `Map` iterates in insertion order, so re-inserting on hit makes the first key the LRU one.
+ */
+const ldTokenCache = new Map();
+/** Test-only: reset the L&D token-exchange cache between cases. */
+export function __clearLdTokenCache() {
+    ldTokenCache.clear();
+}
+/** Test-only: current number of cached L&D tokens. */
+export function __ldTokenCacheSize() {
+    return ldTokenCache.size;
+}
+/** `exp` (seconds) of a JWT, read WITHOUT verification — only ever used to bound a cache TTL. */
+function jwtExpMs(token) {
+    const payload = token.split('.')[1];
+    if (!payload)
+        return undefined;
+    try {
+        const exp = JSON.parse(Buffer.from(payload, 'base64url').toString('utf8')).exp;
+        return typeof exp === 'number' && Number.isFinite(exp) ? exp * 1000 : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The client that POSTs the user's token. `maxRedirects: 0` is load-bearing: axios follows 307/308 and
+ * RE-SENDS the body, so an allowlisted host answering 307 would forward the token to any host it names —
+ * straight past the allowlist. A 3xx is therefore a failed exchange (non-2xx), never followed.
+ */
+export function createLdAuthHttp() {
+    return axios.create({ headers: { accept: 'application/json' }, timeout: 10000, maxRedirects: 0 });
+}
+/**
+ * Exchange a Pitcher (Auth0) access token for an L&D JWT at `POST {ldBase}/auth/token {token}`.
+ * The L&D envelope is `{ success, message, data: { token, refreshToken, user }, statusCode }`, so the
+ * JWT is at `res.data.data.token` (ld-app `authController.ts`).
+ *
+ * Cached until `min(L&D exp, Pitcher exp) − 60 s`: the L&D JWT embeds the Pitcher token, so it is
+ * useless once that expires, and its own lifetime is env-configurable (`JWT_EXPIRES_IN`), so neither
+ * is assumed. A token whose TTL cannot be read, or is already ≤ 0, is used once and not cached.
+ */
+export async function exchangeLdToken(ldBase, pitcherToken, deps, env) {
+    // Re-checked at the point the token leaves, independent of how `ldBase` was obtained.
+    assertBearerLdBase(ldBase, env);
+    const key = `${createHash('sha256').update(pitcherToken).digest('hex')}|${ldBase}`;
+    const hit = ldTokenCache.get(key);
+    if (hit) {
+        ldTokenCache.delete(key);
+        if (hit.expiresAt > Date.now()) {
+            ldTokenCache.set(key, hit);
+            return hit.token;
+        }
+    }
+    let ldToken;
+    try {
+        const http = deps.ldAuthClient ?? createLdAuthHttp();
+        const res = await http.post(`${ldBase}/auth/token`, { token: pitcherToken });
+        ldToken = res.data?.data?.token;
+    }
+    catch (e) {
+        const err = toLdCliError(e);
+        throw createCliError('AUTH', `L&D token exchange failed: ${err.message}`);
+    }
+    if (typeof ldToken !== 'string' || !ldToken) {
+        throw createCliError('AUTH', 'L&D token exchange failed: no token in the /auth/token response');
+    }
+    const ldExp = jwtExpMs(ldToken);
+    const pitcherExp = jwtExpMs(pitcherToken);
+    if (ldExp !== undefined && pitcherExp !== undefined) {
+        const expiresAt = Math.min(ldExp, pitcherExp) - LD_TOKEN_SKEW_MS;
+        if (expiresAt > Date.now()) {
+            ldTokenCache.set(key, { token: ldToken, expiresAt });
+            while (ldTokenCache.size > LD_TOKEN_CACHE_MAX) {
+                const oldest = ldTokenCache.keys().next().value;
+                if (oldest === undefined)
+                    break;
+                ldTokenCache.delete(oldest);
+            }
+        }
+    }
+    return ldToken;
+}
+/**
+ * Build (or inject, in tests) an axios client pointed at the resolved L&D Lambda base.
+ * API key → sent as-is (`x-api-key`). Bearer → exchanged for an L&D JWT first (the Lambda does not
+ * accept an Auth0 token directly), and that JWT is sent as the bearer.
+ */
 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));
+    const cred = credentialOf(opts);
+    if (cred.kind === 'apiKey')
+        return makeClient(base, cred);
+    // No redirects for a bearer either: the L&D JWT embeds the user's Pitcher token.
+    const ldToken = await exchangeLdToken(base, cred.token, deps, env);
+    return makeClient(base, { kind: 'bearer', token: ldToken }, { maxRedirects: 0 });
 }
 /**
  * Unwrap the L&D success envelope `{ success, data, message? }` to its resource payload.

package/dist/src/core/readInput.js

@@ -48,9 +48,16 @@ export function resolveTextInput(inline, file, label) {
 // 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.
+//
+// The "neither" test is `=== undefined`, NOT truthiness: `resolveTextInput` returns `''` for a
+// ZERO-BYTE file, and a falsy test would report that as "you did not pass the flag" when the
+// caller passed `--<label>-file empty.json` and the file is simply empty. An empty string is
+// content, so let it reach `JSON.parse` and be named for what it is — not valid JSON. (An empty
+// INLINE value still lands on the "neither" message: `resolveTextInput`'s own XOR is truthy-based,
+// so it returns undefined for `--<label> ''` before this line runs.)
 export function parseJsonInput(inline, file, label) {
     const raw = resolveTextInput(inline, file, label);
-    if (!raw)
+    if (raw === undefined)
         throw createCliError('VALIDATION', `provide --${label} (inline JSON) or --${label}-file`);
     try {
         return JSON.parse(raw);

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 123.
+// None are relevant to a non-technical adopter installing the extension. The CLI `p mcp` registers every tool.
 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/hosted.d.ts

@@ -0,0 +1,21 @@
+import type { BuildServerOptions } from './server.js';
+import type { ToolDescriptor } from './tools/types.js';
+/**
+ * The tool set served by the hosted (remote, OAuth) MCP server — PIT-8912.
+ *
+ * Differences from stdio `p mcp`:
+ * - the three disk-bound tools (`LOCAL_ONLY`) are dropped: they zip a folder on the server host;
+ * - every file-path input (`FILE_KEY`) is stripped from the schemas AND rejected at runtime, so a
+ *   hosted call can never make the server read its own disk; every one has an inline alternative;
+ * - descriptions that talk about local files are rewritten.
+ */
+export declare const LOCAL_ONLY: ReadonlySet<string>;
+/**
+ * A file-path input. Covers the 8 schema keys on main (`filePath`, `configFile`, `landingContextFile`,
+ * `htmlFile`, `cssFile`, `bodyFile`, `fromFile`, `sectionsFile`) AND command-layer keys no schema
+ * exposes today (`questionFile`, `answersFile`, `canvasFile`, `assessmentsFile`, `contentHtmlFile`).
+ */
+export declare const FILE_KEY: RegExp;
+/** Build options every hosted server uses: a write always asks the client to confirm. */
+export declare const HOSTED_BUILD_OPTIONS: Readonly<BuildServerOptions>;
+export declare const hostedTools: ToolDescriptor[];