@pitcher/cli-scripts 2.17.0 → 2.17.1

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

@@ -17,8 +17,16 @@ export declare function requireInstance(opts: LdCommonOpts): string;
 export declare function pickTruthy<T extends object>(opts: T, keys: readonly (keyof T)[]): Partial<Record<keyof T, unknown>>;
 /**
  * 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.
+ * the installed ld-app record's `metadata.api_base_url` → the ld-app built-in default.
+ * Cached per (org, instanceId).
+ *
+ * PIT-7546: this used to read `/core/api/protected/apps/ld-app/config`, which is a
+ * machine-to-machine route gated on an `x-integrations-token` shared secret. The CLI sends
+ * `x-api-key`, so next-core rejected every call with 'Invalid m2m integrations token' before
+ * the L&D Lambda was ever contacted — one root cause behind all 63 `pitcher_ld_*` failures.
+ * The replacement reads the same row that route's SQL reads (`pitcher_file` where
+ * `app_metadata->>'name' = 'ld-app'` and `instance_id = $2`, `type = 'app'`, not deleted)
+ * 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. */

package/dist/src/core/ld.js

@@ -1,7 +1,56 @@
 import { resolveApiKey } from './auth.js';
 import { clientFor, makeClient, toCliError } from './http.js';
+import { resolveBaseUrl } from './baseUrl.js';
 import { createCliError } from './errors.js';
-const LD_APP_CONFIG_PATH = '/core/api/protected/apps/ld-app/config';
+import { MAX_PAGE_SIZE } from './pagination.js';
+const LD_APP_NAME = 'ld-app';
+const FILES_LIST_PATH = '/api/v1/files/';
+/**
+ * Sparse fieldset for the installed-apps scan (`FileViewSet.get_serializer` forwards `?fields=`
+ * to `AlwaysIncludeIdFieldMixin`, which also re-adds `id`). Without it the full `FileSerializer`
+ * renders `content_url`/`thumbnail_url`/`zip_url`/`original_url` for every row — each one a
+ * CloudFront signing — on every single `p ld` invocation, since the cache is per-process.
+ * Measured on a 59-app instance: 153,837 -> 77,402 bytes and no signed URLs.
+ */
+const LD_APP_FIELDS = 'app_metadata,metadata';
+/**
+ * Fallback L&D base URL, kept byte-identical to the ld-app frontend's own default
+ * (`ng-production-apps/ld-app/src/lib/apiClient.ts`). `api_base_url` is an OPTIONAL
+ * per-instance override (`app.config.json`, `is_required: false`), so on every instance
+ * that has never set it the app falls back to this single deployed Lambda.
+ *
+ * ONLY usable from the platform host below — see LD_FALLBACK_PLATFORM_ORIGIN.
+ */
+const LD_FALLBACK_BASE_URL = 'https://cgmfr9gjza.execute-api.eu-west-1.amazonaws.com/dev/api';
+/**
+ * The one platform host the fallback Lambda authenticates against, so the only one whose
+ * API key may travel to it.
+ *
+ * The Lambda lives in the IaC Test account with `DefaultAuthorizer: NONE` (ld-app README
+ * section 2) and validates an incoming `x-api-key` by relaying it verbatim to
+ * `https://dev.my.pitcher.com/api/v1` (`ld-app/server/src/config/index.ts` →
+ * `resolvePitcherApiBaseUrl`, `providers/pitcherApiProvider.ts` → `credentialHeaders`).
+ * Defaulting any other environment's org key onto it would ship that credential into a
+ * test account and then fail validation, surfacing as a misleading AUTH — and `ldClientFor`
+ * sends exactly that key. The L&D server refuses the mirror-image default for the same
+ * stated reason ("would send credential validation and org-membership probes to the wrong
+ * environment"), so the CLI matches it rather than re-deciding.
+ *
+ * The frontend precedent does NOT extend here: it carries a short-lived per-user JWT, not
+ * the org-wide authoring key. Once a prod L&D stack exists, per-instance `api_base_url` is
+ * what points each instance at it — the fallback must never silently stand in.
+ */
+const LD_FALLBACK_PLATFORM_ORIGIN = 'https://dev.my.pitcher.com';
+/**
+ * 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
+ * `next` page. Fail loudly rather than spin: a silent break would look identical to
+ * "ld-app is not installed", which is the exact misreport paging is here to prevent.
+ */
+const MAX_APP_PAGES = 20;
+function isRecord(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
 const baseUrlCache = new Map();
 /** Test-only: reset the resolved-base-URL cache between cases. */
 export function __clearLdBaseUrlCache() {
@@ -36,10 +85,95 @@ function trimUrl(raw, source) {
     // origin + pathname only: strips any userinfo/query/hash; trailing slash trimmed.
     return `${parsed.origin}${parsed.pathname}`.replace(/\/+$/, '');
 }
+/**
+ * Find the installed `ld-app` file record for an instance and return its per-instance
+ * config (`pitcher_file.metadata`), or undefined when the app is not installed.
+ *
+ * Django's `FileFilter` (ng-rest-api `pitcher/views/fileviews.py`) has NO filter on
+ * `app_metadata` — its declared filters and `Meta.fields` cover `name`, `type`, `tags__in`
+ * etc., and `name` is the file's DISPLAY name ('L&D'), not `app_metadata->>'name'`
+ * ('ld-app'). So the name match has to happen client-side, which in turn means paging to
+ * exhaustion: a first-page-only match would report 'not installed' on an instance that
+ * simply has more apps than one page holds.
+ *
+ * If an instance somehow carries two ld-app records, the first in server order wins. That
+ * order is `-modified_at` (`fileviews.py` FileViewSet.ordering), so the most-recently-modified
+ * one does — strictly more deterministic than the `LIMIT 1` with no ORDER BY in the m2m route
+ * this replaces. No dev instance has more than one (measured across all 20 that have it).
+ */
+async function fetchLdAppMetadata(platform, instanceId) {
+    let scanned = 0;
+    let named = 0;
+    let exhausted = false;
+    for (let page = 1; page <= MAX_APP_PAGES; page += 1) {
+        const res = await platform.get(FILES_LIST_PATH, {
+            params: { instance_id: instanceId, type__in: 'app', fields: LD_APP_FIELDS, page, page_size: MAX_PAGE_SIZE },
+        });
+        const body = res.data;
+        // Fail loudly on an unexpected body rather than coercing it to an empty page: that would
+        // surface as 'ld-app is not installed', the exact misreport the paging below is here to
+        // prevent, and it would be indistinguishable from the real thing.
+        if (!isRecord(body) || !Array.isArray(body.results)) {
+            throw createCliError('UNKNOWN', `Unexpected response shape from ${FILES_LIST_PATH} (expected a paginated body)`);
+        }
+        scanned += body.results.length;
+        for (const row of body.results) {
+            const file = row;
+            // A single nameless row is DATA, not a bad response — `app_metadata` is a JSONField
+            // defaulting to `{}`, and such a row is definitively not ld-app, so skipping it is
+            // correct. It also cannot hide ld-app, which has a name and is found by scanning every
+            // row. Hard-failing on it would take out `p ld` for an instance over one junk record.
+            if (typeof file?.app_metadata?.name !== 'string')
+                continue;
+            named += 1;
+            if (file.app_metadata.name !== LD_APP_NAME)
+                continue;
+            // Behaviourally this is just null-safety: the sole consumer reads `.api_base_url`, which
+            // is undefined on a string or array anyway, so `isRecord` and `?? {}` are equivalent for
+            // every input. It is written this way because it narrows without an `as` cast — do not
+            // read the strictness as a contract. What DOES matter is never returning a nullish value:
+            // the caller treats that as "ld-app not installed".
+            return isRecord(file.metadata) ? file.metadata : {};
+        }
+        // DRF's pagination contract for `next` is a non-empty URL string, `null`, or absent.
+        // Anything else means we cannot trust our own stopping condition: a truthy non-string
+        // would otherwise page all the way to the cap before failing, and an empty string would
+        // read as "exhausted" and land on NOT_FOUND. Fail immediately and accurately instead.
+        const next = body.next;
+        if (next !== undefined && next !== null && (typeof next !== 'string' || !next)) {
+            throw createCliError('UNKNOWN', `Unexpected \`next\` in the ${FILES_LIST_PATH} response (expected a URL, null or absent)`);
+        }
+        if (!next) {
+            exhausted = true;
+            break;
+        }
+    }
+    // Ran out of pages before the server ran out of `next`. Throw rather than return: a silent
+    // give-up is indistinguishable from "not installed", the exact misreport paging prevents.
+    if (!exhausted) {
+        throw createCliError('UNKNOWN', `Gave up looking for ${LD_APP_NAME} after ${MAX_APP_PAGES} pages of installed apps. Set --ld-url or NG_LD_API_URL.`);
+    }
+    // The systemic case IS a shape problem: rows came back but not one carried
+    // `app_metadata.name`, so the field we match on is missing wholesale (a dropped `?fields=`
+    // entry, a serializer change). Reporting NOT_FOUND there would claim "ld-app is not
+    // installed" on an instance that has it — the misreport this whole scan is built to avoid.
+    if (scanned > 0 && named === 0) {
+        throw createCliError('UNKNOWN', `No app row from ${FILES_LIST_PATH} carried app_metadata.name (${scanned} scanned) — the files list may no longer return it`);
+    }
+    return undefined;
+}
 /**
  * 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.
+ * the installed ld-app record's `metadata.api_base_url` → the ld-app built-in default.
+ * Cached per (org, instanceId).
+ *
+ * PIT-7546: this used to read `/core/api/protected/apps/ld-app/config`, which is a
+ * machine-to-machine route gated on an `x-integrations-token` shared secret. The CLI sends
+ * `x-api-key`, so next-core rejected every call with 'Invalid m2m integrations token' before
+ * the L&D Lambda was ever contacted — one root cause behind all 63 `pitcher_ld_*` failures.
+ * The replacement reads the same row that route's SQL reads (`pitcher_file` where
+ * `app_metadata->>'name' = 'ld-app'` and `instance_id = $2`, `type = 'app'`, not deleted)
+ * over a credential the CLI actually holds.
  */
 export async function resolveLdBaseUrl(opts, deps = {}, env = process.env) {
     const override = opts.ldUrl?.trim() || env.NG_LD_API_URL?.trim();
@@ -48,17 +182,33 @@ export async function resolveLdBaseUrl(opts, deps = {}, env = process.env) {
     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}`;
+    // `--url` outranks `--org` in resolveBaseUrl (baseUrl.ts), so keying on org alone lets two
+    // 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;
     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 metadata = await fetchLdAppMetadata(platform, opts.instanceId);
+    if (!metadata) {
+        throw createCliError('NOT_FOUND', 'ld-app is not configured in this instance (not installed). Set --ld-url or NG_LD_API_URL.');
+    }
+    // `api_base_url` is an optional override; absent means "use the app's own default" —
+    // but only where that default's credential environment matches ours (see the constant).
+    const apiBaseUrl = metadata.api_base_url;
+    let url;
+    if (typeof apiBaseUrl === 'string' && apiBaseUrl.trim()) {
+        url = trimUrl(apiBaseUrl.trim(), `ld-app config (metadata.api_base_url on instance ${opts.instanceId})`);
+    }
+    else {
+        const platformOrigin = resolveBaseUrl({ org: opts.org, url: opts.url });
+        if (platformOrigin !== LD_FALLBACK_PLATFORM_ORIGIN) {
+            throw createCliError('NOT_FOUND', `ld-app has no api_base_url configured on this instance, and the built-in default only serves ` +
+                `${LD_FALLBACK_PLATFORM_ORIGIN} (this run targets ${platformOrigin}). Set metadata.api_base_url ` +
+                `on the instance, or pass --ld-url / NG_LD_API_URL.`);
+        }
+        url = LD_FALLBACK_BASE_URL;
     }
-    const url = trimUrl(apiBaseUrl, 'ld-app config');
     baseUrlCache.set(cacheKey, url);
     return url;
 }

package/dist/src/mcp/tools/analytics.js

@@ -160,7 +160,8 @@ export const analyticsTools = [
         title: 'DSR per-viewer session timeline',
         description: 'Per-viewer session event timeline for a DSR canvas (drill-down for one viewer). Returns the raw, ' +
             'uncapped event list (not summarized). Works with a member key. Requires canvasId and userEmail — ' +
-            'get both from pitcher_analytics_viewers.',
+            'get both from pitcher_analytics_viewers: pass its `normalized_email` (or its `email`) VERBATIM. ' +
+            'Do not tidy the address — the stored identity carries an ` (External)` suffix.',
         inputShape: {
             instanceId: z.string().describe('Instance ID (required)'),
             canvasId: z.string().describe('Canvas ID (required)'),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pitcher/cli-scripts",
-  "version": "2.17.0",
+  "version": "2.17.1",
   "description": "The Pitcher CLI for various tasks in its ecosystem.",
   "author": "Pitcher AG",
   "license": "MIT",