@chatlychat/cli 0.4.1 → 0.5.1

package/dist/pac/platform-document.d.ts

@@ -0,0 +1,65 @@
+/**
+ * `chatly.platform.json` — the platform document's schema.
+ *
+ * ═══ WHAT IT LOOKS LIKE ═══════════════════════════════════════════════════
+ *
+ *   {
+ *     "version": 1,
+ *     "platform": { "prefix": "cp_live_a1b2c3d4" },
+ *     "resources": {
+ *       "workspaces": [{ "slug": "acme", "name": "Acme Inc" }],
+ *       "users": [
+ *         { "workspace": "acme", "email": "ops@acme.test", "name": "Ops", "role": "admin" }
+ *       ],
+ *       "apiKeys": [
+ *         { "workspace": "acme", "name": "deploy", "scopes": ["conversations:read"] }
+ *       ],
+ *       "botCredentials": [{ "workspace": "acme", "name": "assistant" }],
+ *       "knowledgeSources": [
+ *         { "workspace": "acme", "label": "Docs", "url": "https://acme.test/docs" }
+ *       ]
+ *     }
+ *   }
+ *
+ * ═══ WHY FLAT SECTIONS AND NOT WORKSPACES THAT NEST THEIR CHILDREN ════════
+ *
+ * A nested shape reads better for one tenant and worse for the job this file
+ * exists for. The ask behind CHT-F04 is "four products were provisioned four
+ * slightly different ways", which is a question about CONSISTENCY ACROSS
+ * tenants: what every workspace's deploy key is scoped to, which of them has
+ * a bot credential nobody uses, whether the same two people are admins
+ * everywhere. Flat sections put each of those on one screen and make a
+ * diff-of-the-file readable; nesting buries them one indent deeper per
+ * tenant.
+ *
+ * It also means the engine is the same engine. `wac/diff.ts` and
+ * `wac/apply.ts` are untouched by this feature except for the path-parameter
+ * mechanism, and the dependency ordering a nested document would have had to
+ * re-invent (create the workspace, then everything that names it, and skip a
+ * child whose parent's create failed) is what `references` and `dependsOn`
+ * already do.
+ *
+ * ═══ THE GUARD ════════════════════════════════════════════════════════════
+ *
+ * `platform.prefix` against `GET /v1/platform/whoami`'s `prefix`, which is
+ * the identifying head of the `cp_` token. The workspace document guards on a
+ * workspace id for the same reason and the stakes here are higher: this
+ * document creates TENANTS, and running a staging file against a production
+ * reseller credential provisions real customers. Optional, because a document
+ * meant to be portable across two platform credentials cannot name one —
+ * and checked on `plan` as well as `apply`, because a plan is what somebody
+ * reads before they approve.
+ *
+ * It is the PREFIX and not the whole token: the prefix is published on every
+ * `whoami` and on every key row, it is not a credential, and a document in
+ * git must not contain one. `${env:…}` interpolation works here as it does
+ * everywhere else if somebody wants it out of the file entirely.
+ */
+import { addressOf } from '../wac/resource-def.js';
+import type { DocumentSchema } from '../wac/document.js';
+export { addressOf };
+/** The default filenames, in the order `--file`-less runs look for them. */
+export declare const PLATFORM_DEFAULT_FILES: string[];
+/** The platform document: six resource types, a `cp_` credential. */
+export declare const PLATFORM_SCHEMA: DocumentSchema;
+//# sourceMappingURL=platform-document.d.ts.map

package/dist/pac/platform-document.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform-document.d.ts","sourceRoot":"","sources":["../../src/pac/platform-document.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AAQH,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAEnD,OAAO,KAAK,EAAE,cAAc,EAAS,MAAM,oBAAoB,CAAC;AAEhE,OAAO,EAAE,SAAS,EAAE,CAAC;AAErB,4EAA4E;AAC5E,eAAO,MAAM,sBAAsB,UAIlC,CAAC;AAiFF,qEAAqE;AACrE,eAAO,MAAM,eAAe,EAAE,cAO7B,CAAC"}

package/dist/pac/platform-document.js

@@ -0,0 +1,149 @@
+/**
+ * `chatly.platform.json` — the platform document's schema.
+ *
+ * ═══ WHAT IT LOOKS LIKE ═══════════════════════════════════════════════════
+ *
+ *   {
+ *     "version": 1,
+ *     "platform": { "prefix": "cp_live_a1b2c3d4" },
+ *     "resources": {
+ *       "workspaces": [{ "slug": "acme", "name": "Acme Inc" }],
+ *       "users": [
+ *         { "workspace": "acme", "email": "ops@acme.test", "name": "Ops", "role": "admin" }
+ *       ],
+ *       "apiKeys": [
+ *         { "workspace": "acme", "name": "deploy", "scopes": ["conversations:read"] }
+ *       ],
+ *       "botCredentials": [{ "workspace": "acme", "name": "assistant" }],
+ *       "knowledgeSources": [
+ *         { "workspace": "acme", "label": "Docs", "url": "https://acme.test/docs" }
+ *       ]
+ *     }
+ *   }
+ *
+ * ═══ WHY FLAT SECTIONS AND NOT WORKSPACES THAT NEST THEIR CHILDREN ════════
+ *
+ * A nested shape reads better for one tenant and worse for the job this file
+ * exists for. The ask behind CHT-F04 is "four products were provisioned four
+ * slightly different ways", which is a question about CONSISTENCY ACROSS
+ * tenants: what every workspace's deploy key is scoped to, which of them has
+ * a bot credential nobody uses, whether the same two people are admins
+ * everywhere. Flat sections put each of those on one screen and make a
+ * diff-of-the-file readable; nesting buries them one indent deeper per
+ * tenant.
+ *
+ * It also means the engine is the same engine. `wac/diff.ts` and
+ * `wac/apply.ts` are untouched by this feature except for the path-parameter
+ * mechanism, and the dependency ordering a nested document would have had to
+ * re-invent (create the workspace, then everything that names it, and skip a
+ * child whose parent's create failed) is what `references` and `dependsOn`
+ * already do.
+ *
+ * ═══ THE GUARD ════════════════════════════════════════════════════════════
+ *
+ * `platform.prefix` against `GET /v1/platform/whoami`'s `prefix`, which is
+ * the identifying head of the `cp_` token. The workspace document guards on a
+ * workspace id for the same reason and the stakes here are higher: this
+ * document creates TENANTS, and running a staging file against a production
+ * reseller credential provisions real customers. Optional, because a document
+ * meant to be portable across two platform credentials cannot name one —
+ * and checked on `plan` as well as `apply`, because a plan is what somebody
+ * reads before they approve.
+ *
+ * It is the PREFIX and not the whole token: the prefix is published on every
+ * `whoami` and on every key row, it is not a credential, and a document in
+ * git must not contain one. `${env:…}` interpolation works here as it does
+ * everywhere else if somebody wants it out of the file entirely.
+ */
+import { PLATFORM_RESOURCE_KEYS, PLATFORM_RESOURCE_TYPES, platformResourceDef, REFUSED_KEYS, } from './platform-resources.js';
+import { addressOf } from '../wac/resource-def.js';
+export { addressOf };
+/** The default filenames, in the order `--file`-less runs look for them. */
+export const PLATFORM_DEFAULT_FILES = [
+    'chatly.platform.json',
+    'chatly.platform.yaml',
+    'chatly.platform.yml',
+];
+const TOP_LEVEL_KEYS = ['version', 'platform', 'resources'];
+const PLATFORM_KEYS = ['prefix'];
+/**
+ * `platform: { prefix }`, validated.
+ *
+ * A nested object rather than a bare `platform: "cp_live_…"` string, because
+ * the two things that might reasonably join it later — a restriction echo and
+ * an environment name — are properties OF the credential rather than
+ * alternatives to it, and widening a string to an object afterwards is a
+ * breaking change to a file format. An unknown key inside it is refused by
+ * name like every other key in this document.
+ */
+function readGuard(raw, issues) {
+    const block = raw['platform'];
+    if (block === undefined) {
+        return undefined;
+    }
+    if (typeof block !== 'object' || block === null || Array.isArray(block)) {
+        issues.push({
+            path: 'platform',
+            message: 'must be an object: `"platform": { "prefix": "cp_live_…" }`, or left out. It is a ' +
+                'guard — `apply` refuses to run against any other platform credential, which is what ' +
+                'stops a staging file provisioning real tenants.',
+        });
+        return undefined;
+    }
+    const entries = block;
+    for (const key of Object.keys(entries)) {
+        if (!PLATFORM_KEYS.includes(key)) {
+            issues.push({
+                path: `platform.${key}`,
+                message: `unknown key "${key}". Valid: ${PLATFORM_KEYS.join(', ')}.`,
+            });
+        }
+    }
+    const prefix = entries['prefix'];
+    if (prefix === undefined) {
+        issues.push({
+            path: 'platform.prefix',
+            message: 'required when `platform` is present. It is the identifying head of the `cp_` token, ' +
+                'which `chatly api GET /v1/platform/whoami` reports as `prefix` — NOT the token ' +
+                'itself. Remove the whole `platform` block if this document is meant to be portable ' +
+                'across credentials.',
+        });
+        return undefined;
+    }
+    if (typeof prefix !== 'string' || prefix.length === 0) {
+        issues.push({ path: 'platform.prefix', message: 'must be a non-empty string.' });
+        return undefined;
+    }
+    /*
+     * A WHOLE token here is refused, loudly, rather than accepted and compared
+     * against the prefix it starts with.
+     *
+     * `platform-credentials.service.ts` mints `cp_<32 bytes base64url>` and
+     * stores only its hash and a short prefix. A document in git that carried
+     * the whole thing would be a reseller credential in a repository — the
+     * single worst secret this product has, since it creates tenants and mints
+     * their keys — and this file is the one file we KNOW is committed. Being
+     * tolerant here would be the convenience that makes that happen.
+     */
+    if (prefix.length > 24) {
+        issues.push({
+            path: 'platform.prefix',
+            message: 'that looks like a whole token, not a prefix. Put the PREFIX here — the short ' +
+                'identifying head `GET /v1/platform/whoami` reports — and never the token: a `cp_` ' +
+                'credential creates tenants and mints their API keys, and this document is a file in ' +
+                'git. Pass the token with --key or CHATLY_API_KEY, or interpolate it nowhere at all.',
+        });
+        return undefined;
+    }
+    return prefix;
+}
+/** The platform document: six resource types, a `cp_` credential. */
+export const PLATFORM_SCHEMA = {
+    topLevelKeys: TOP_LEVEL_KEYS,
+    resourceKeys: PLATFORM_RESOURCE_KEYS,
+    types: PLATFORM_RESOURCE_TYPES,
+    def: platformResourceDef,
+    refusedKeys: REFUSED_KEYS,
+    guard: readGuard,
+};
+//# sourceMappingURL=platform-document.js.map

package/dist/pac/platform-document.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform-document.js","sourceRoot":"","sources":["../../src/pac/platform-document.ts"],"names":[],"mappings":"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"}

package/dist/pac/platform-live.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Reading the live platform surface. Every call here is a GET.
+ *
+ * ═══ THE ONE DECISION THAT SHAPES THIS FILE ═══════════════════════════════
+ *
+ * **A platform document is a SUBSET of the tenants a credential owns, so a
+ * workspace the file does not mention is not drift.**
+ *
+ * `wac/diff.ts`'s first rule says the same thing one level down — "a server
+ * field the file says nothing about is unmanaged and is never mentioned" —
+ * and the consequence here is bigger. A reseller with four hundred tenants
+ * and a document describing one would otherwise get a plan whose first four
+ * hundred lines are "on the server, not in this document", and a plan nobody
+ * reads is worse than no plan because it gets approved. Worse, the shape
+ * would invite `--prune` at a tenant, which is why `workspaces.remove` is
+ * `null` as a second lock.
+ *
+ * So this reader filters the workspace list down to the slugs the document
+ * names, and says in a WARNING how many it left alone. That is the honest
+ * middle: the number is visible, and it is not presented as something to fix.
+ *
+ * It also bounds the request count. Children are nested under a workspace
+ * id, so reading them for every tenant a credential owns is four reads per
+ * tenant — twelve hundred GETs to plan a one-tenant document, against a
+ * `platform-provision` throttle of 20/minute on the writes and no reason to
+ * find out what the reads' limit is.
+ *
+ * ═══ WHICH SLUGS COUNT AS DECLARED ════════════════════════════════════════
+ *
+ * The union of the `workspaces:` section's keys AND every `workspace:` a
+ * child row names. The second half matters: adopting an existing tenant —
+ * adding a deploy key to a workspace somebody else created — is a document
+ * with an `apiKeys` row and no `workspaces` row at all, and that is a shape
+ * to support rather than refuse. The reference resolves against the live
+ * list, and if the slug is not there `diff.ts` blocks the row with "neither
+ * on the server nor created by this plan".
+ *
+ * ═══ WHY THE DETAIL ROUTE IS FETCHED ONCE ═════════════════════════════════
+ *
+ * `users` has no list route of its own: members come back as `users[]` on
+ * `GET /v1/platform/workspaces/{id}`. If a second resource ever reads from
+ * that same route, declaring it is enough — `GET`s are memoised by path
+ * within one call, so two resources over one route cost one request.
+ */
+import type { LiveSection } from '../wac/diff.js';
+import type { WacDocument } from '../wac/document.js';
+import type { ChatlyClient } from '@chatlychat/sdk-node';
+export interface PlatformLive {
+    readonly live: Map<string, LiveSection>;
+    /** Observations about the surface, merged into the plan's own warnings. */
+    readonly warnings: ReadonlyArray<string>;
+}
+/** Every workspace slug this document refers to, declared or referenced. */
+export declare function declaredSlugs(doc: WacDocument): Set<string>;
+/**
+ * The live rows for every type the document mentions, and nothing else.
+ *
+ * All through `chatly.request` — the escape hatch `packages/sdk-spec/CONTRACT.md`
+ * defines — so auth, retries and the typed errors are the same ones every
+ * other command gets, and `apps/cli` still adds no HTTP of its own. There is
+ * no SDK method for any of these: `surface.json` holds no `/v1/platform` path
+ * at all, which the manifest's own note records.
+ */
+export declare function readPlatformLive(chatly: ChatlyClient, doc: WacDocument): Promise<PlatformLive>;
+//# sourceMappingURL=platform-live.d.ts.map

package/dist/pac/platform-live.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform-live.d.ts","sourceRoot":"","sources":["../../src/pac/platform-live.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAIH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAiBzD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IACxC,2EAA2E;IAC3E,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;CAC1C;AASD,4EAA4E;AAC5E,wBAAgB,aAAa,CAAC,GAAG,EAAE,WAAW,GAAG,GAAG,CAAC,MAAM,CAAC,CA2B3D;AAED;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,YAAY,EACpB,GAAG,EAAE,WAAW,GACf,OAAO,CAAC,YAAY,CAAC,CAgFvB"}

package/dist/pac/platform-live.js

@@ -0,0 +1,263 @@
+/**
+ * Reading the live platform surface. Every call here is a GET.
+ *
+ * ═══ THE ONE DECISION THAT SHAPES THIS FILE ═══════════════════════════════
+ *
+ * **A platform document is a SUBSET of the tenants a credential owns, so a
+ * workspace the file does not mention is not drift.**
+ *
+ * `wac/diff.ts`'s first rule says the same thing one level down — "a server
+ * field the file says nothing about is unmanaged and is never mentioned" —
+ * and the consequence here is bigger. A reseller with four hundred tenants
+ * and a document describing one would otherwise get a plan whose first four
+ * hundred lines are "on the server, not in this document", and a plan nobody
+ * reads is worse than no plan because it gets approved. Worse, the shape
+ * would invite `--prune` at a tenant, which is why `workspaces.remove` is
+ * `null` as a second lock.
+ *
+ * So this reader filters the workspace list down to the slugs the document
+ * names, and says in a WARNING how many it left alone. That is the honest
+ * middle: the number is visible, and it is not presented as something to fix.
+ *
+ * It also bounds the request count. Children are nested under a workspace
+ * id, so reading them for every tenant a credential owns is four reads per
+ * tenant — twelve hundred GETs to plan a one-tenant document, against a
+ * `platform-provision` throttle of 20/minute on the writes and no reason to
+ * find out what the reads' limit is.
+ *
+ * ═══ WHICH SLUGS COUNT AS DECLARED ════════════════════════════════════════
+ *
+ * The union of the `workspaces:` section's keys AND every `workspace:` a
+ * child row names. The second half matters: adopting an existing tenant —
+ * adding a deploy key to a workspace somebody else created — is a document
+ * with an `apiKeys` row and no `workspaces` row at all, and that is a shape
+ * to support rather than refuse. The reference resolves against the live
+ * list, and if the slug is not there `diff.ts` blocks the row with "neither
+ * on the server nor created by this plan".
+ *
+ * ═══ WHY THE DETAIL ROUTE IS FETCHED ONCE ═════════════════════════════════
+ *
+ * `users` has no list route of its own: members come back as `users[]` on
+ * `GET /v1/platform/workspaces/{id}`. If a second resource ever reads from
+ * that same route, declaring it is enough — `GET`s are memoised by path
+ * within one call, so two resources over one route cost one request.
+ */
+import { addressOf } from '../wac/resource-def.js';
+/**
+ * The cap `KbIngestService.list` applies, and the bound the two
+ * `@PaginationExempt`-shaped credential lists sit behind.
+ *
+ * `wac/workspace-as-code.ts` uses the same number for the same reason: a bare
+ * array that comes back at exactly its cap MAY be truncated, and a row past
+ * the cap is invisible rather than absent — which would make it an orphan and
+ * then, with `--prune`, a deletion. `diff.ts` refuses prune for a type in
+ * that state.
+ */
+const EXEMPT_LIST_CAP = 200;
+/** How many pages of `GET /v1/platform/workspaces` to walk before stopping. */
+const PAGE_GUARD = 200;
+function asRows(value) {
+    return Array.isArray(value) ? value : [];
+}
+/** Every workspace slug this document refers to, declared or referenced. */
+export function declaredSlugs(doc) {
+    const out = new Set();
+    for (const section of doc.sections) {
+        if (section.def.parent === undefined) {
+            for (const row of section.rows) {
+                out.add(row.key);
+            }
+            continue;
+        }
+        const { field } = section.def.parent;
+        for (const row of section.rows) {
+            /*
+             * Off the ROW rather than off `row.refs`, because a row whose parent
+             * field was missing or malformed never reaches here — `parseDocument`
+             * throws before this is called. The ref map is keyed by the WIRE name
+             * and holds the same value; reading the source field keeps this
+             * readable against the document rather than against the request.
+             */
+            const named = row.body[field] ?? row.refs[field];
+            const fromRefs = Object.values(row.refs).find((r) => r.type === section.def.parent?.type);
+            const slug = typeof named === 'string' ? named : fromRefs?.key;
+            if (typeof slug === 'string' && slug.length > 0) {
+                out.add(slug);
+            }
+        }
+    }
+    return out;
+}
+/**
+ * The live rows for every type the document mentions, and nothing else.
+ *
+ * All through `chatly.request` — the escape hatch `packages/sdk-spec/CONTRACT.md`
+ * defines — so auth, retries and the typed errors are the same ones every
+ * other command gets, and `apps/cli` still adds no HTTP of its own. There is
+ * no SDK method for any of these: `surface.json` holds no `/v1/platform` path
+ * at all, which the manifest's own note records.
+ */
+export async function readPlatformLive(chatly, doc) {
+    const warnings = [];
+    const live = new Map();
+    const wanted = declaredSlugs(doc);
+    const workspaces = await readWorkspaces(chatly, wanted, warnings);
+    // Always set: a document with no `workspaces:` section still resolves its
+    // children's `workspace:` against these rows. The command passes them to
+    // `buildPlan` as `referenced` in that case, so they are never planned.
+    live.set('workspaces', { rows: [...workspaces.values()] });
+    /** `GET`s already made in this call, by path. See the header. */
+    const fetched = new Map();
+    const get = async (path) => {
+        const cached = fetched.get(path);
+        if (cached !== undefined) {
+            return cached;
+        }
+        const answer = await chatly.request('GET', path);
+        fetched.set(path, answer);
+        return answer;
+    };
+    for (const section of doc.sections) {
+        const { def } = section;
+        if (def.parent === undefined) {
+            continue;
+        }
+        const rows = [];
+        let truncated = false;
+        /*
+         * A SINGLETON child — one per workspace, named by the workspace itself
+         * (`settings`: `childKey` IS the parent field). Its key is `<slug>/<slug>`
+         * on both sides, and it is read only for the workspaces this section
+         * declares: a tenant's settings exist whether or not the file mentions
+         * them, so reading the others would report each one as an orphan.
+         */
+        const singleton = def.parent.childKey === def.parent.field;
+        for (const [slug, workspace] of workspaces) {
+            const id = workspace['id'];
+            if (typeof id !== 'string' || id.length === 0) {
+                continue;
+            }
+            if (singleton && !section.rows.some((r) => r.key === addressOf(slug, slug))) {
+                continue;
+            }
+            const path = def.list.path.replaceAll(`{${def.parent.wire}}`, encodeURIComponent(id));
+            const answer = await get(path);
+            const found = def.rowsFrom === undefined ? asRows(answer) : [...def.rowsFrom(answer)];
+            if (def.rowsFrom === undefined && found.length >= EXEMPT_LIST_CAP) {
+                truncated = true;
+            }
+            for (const row of found) {
+                /*
+                 * The two stamps, and they are what let the shared engine plan a
+                 * nested surface without knowing about one.
+                 *
+                 * `address` is the synthetic natural key — `<slug>/<child>` — which
+                 * `indexLive` matches on and `diff.ts` never compares, because it
+                 * skips the natural key. `workspaceId` is the parent id a nested
+                 * write path needs; stamped onto every row so an ORPHAN, which has
+                 * no document row to resolve a reference from, still carries the id
+                 * its DELETE path requires.
+                 */
+                rows.push({
+                    ...row,
+                    [def.naturalKey]: addressOf(slug, singleton ? slug : String(row[def.parent.childKey] ?? '')),
+                    [def.parent.wire]: id,
+                });
+            }
+            warnings.push(...expiryWarnings(def, slug, found));
+        }
+        live.set(def.type, truncated ? { rows, possiblyTruncated: true } : { rows });
+    }
+    return { live, warnings };
+}
+/**
+ * The workspace list, walked to the end, kept down to the declared slugs.
+ *
+ * Paged since 2026-10-23 — it was a bare array behind a `@PaginationExempt`
+ * whose own schema docblock now calls the exemption unsound. Walked by hand
+ * rather than through `autoPaginate` because the envelope matters: this one
+ * answers `{ items, nextCursor, hasMore }` while its `@PaginationExempt`
+ * neighbours on the same surface answer bare arrays, and conflating the two
+ * is the bug CLAUDE.md records two SDKs shipping.
+ *
+ * `?status=` is deliberately NOT passed. Omitting it answers everything that
+ * is not soft-deleted, suspended tenants included, which is the right set: a
+ * suspended workspace exists and there is no platform route that un-suspends
+ * it, so matching the document row to it and reporting `noop` is true. A
+ * soft-deleted one is absent, so its document row is a `create` — and that
+ * create 409s on the slug, which is a better answer than silently adopting a
+ * tenant that is counting down to purge.
+ */
+async function readWorkspaces(chatly, wanted, warnings) {
+    const out = new Map();
+    let total = 0;
+    let cursor;
+    for (let guard = 0; guard < PAGE_GUARD; guard += 1) {
+        const page = await chatly.request('GET', '/v1/platform/workspaces', { query: cursor === undefined ? {} : { cursor } });
+        const items = asRows(page.items);
+        total += items.length;
+        for (const row of items) {
+            const slug = row['slug'];
+            if (typeof slug === 'string' && wanted.has(slug)) {
+                out.set(slug, row);
+            }
+        }
+        const next = page.nextCursor;
+        if (typeof next !== 'string' || next.length === 0 || next === cursor) {
+            break;
+        }
+        cursor = next;
+    }
+    const unmentioned = total - out.size;
+    if (unmentioned > 0) {
+        warnings.push(`${String(unmentioned)} workspace(s) this credential owns are not in this document. They ` +
+            'are not listed below and are not drift: a platform document describes a SUBSET of a ' +
+            "reseller's tenants, so `--prune` is never offered one — and `DELETE " +
+            '/v1/platform/workspaces/{id}` soft-deletes every conversation in it.');
+    }
+    return out;
+}
+/**
+ * A credential in the list that has EXPIRED, named rather than matched on.
+ *
+ * `ignoreLive` drops a REVOKED key, because `revokedAt` is a fact on the row
+ * and needs no clock. Expiry does need one, and `buildPlan` is pure — no
+ * transport, no filesystem, no clock, which is half the proof that `plan`
+ * writes nothing. Putting `Date.now()` inside it would buy a slightly better
+ * match and spend that property, so the check lives here, in the reader,
+ * which is already doing HTTP.
+ *
+ * The consequence is honest and stated: an expired key still MATCHES its
+ * document row and still reports `noop`. The warning is what tells you the
+ * row the plan called unchanged authenticates nothing. `expiresAt` is
+ * readable, so a document that declares it sees the drift directly — this is
+ * for the common case of a document that omits it and takes the route's
+ * 365-day default.
+ */
+function expiryWarnings(def, slug, rows) {
+    if (!def.secrets.includes('token')) {
+        return [];
+    }
+    const now = Date.now();
+    const dead = rows
+        .filter((row) => {
+        if (def.ignoreLive?.(row) === true) {
+            return false;
+        }
+        const at = row['expiresAt'];
+        return typeof at === 'string' && Number.isFinite(Date.parse(at)) && Date.parse(at) <= now;
+    })
+        .map((row) => String(row['name'] ?? '(unnamed)'));
+    if (dead.length === 0) {
+        return [];
+    }
+    return [
+        `${def.type}: ${dead.map((n) => `\`${slug}/${n}\``).join(', ')} ` +
+            `${dead.length === 1 ? 'has' : 'have'} expired and ${dead.length === 1 ? 'is' : 'are'} ` +
+            'still listed, so the plan below reports them as unchanged — the row exists and matches ' +
+            'the document. They authenticate nothing. Rename them in the document to mint ' +
+            'replacements and orphan these, or revoke them with ' +
+            `\`chatly api DELETE ${def.remove?.path ?? ''}\`.`,
+    ];
+}
+//# sourceMappingURL=platform-live.js.map

package/dist/pac/platform-live.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform-live.js","sourceRoot":"","sources":["../../src/pac/platform-live.ts"],"names":[],"mappings":"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"}