primitive-admin 1.1.0-alpha.7 → 1.1.0-alpha.71

package/dist/src/lib/paginate.js

@@ -0,0 +1,95 @@
+/**
+ * Cursor-pagination helper used by the CLI's API client.
+ *
+ * The server exposes cursor-paginated endpoints (e.g. GET /admin/api/admins/me/apps)
+ * that return `{ items, nextCursor? }` pages. Callers historically only fetched
+ * the first page, silently truncating results (see issue #436). This helper
+ * walks every page and aggregates the items in order.
+ *
+ * Exported separately so the looping contract can be unit-tested without
+ * stubbing the full ApiClient.
+ */
+/**
+ * Normalize an endpoint's list response into the CLI's own output contract.
+ *
+ * The records read paths speak two different wire shapes: js-bao's Durable
+ * Object envelope (`{ data, hasMore, nextCursor?, prevCursor? }`) and the
+ * server's unified list payload (`{ items, hasMore, nextCursor, cursor }`).
+ * Both are collapsed here to `{ items, hasMore, nextCursor? }` so like verbs
+ * print like envelopes.
+ *
+ * Accepts `items` or `data` as the array key and `nextCursor` or the
+ * deprecated `cursor` alias as the cursor. Throws when neither array key is
+ * present so an error body is never coerced into an empty result.
+ *
+ * Named `normalizeCliListEnvelope` to keep it distinct from the JS client's
+ * `normalizeListEnvelope` (`src/client/internal/listEnvelope.ts`), whose
+ * cursor contract is the opposite: it *back-fills* the deprecated `cursor`
+ * alias so the client keeps working against pre-#1316 servers, while this one
+ * drops it so CLI consumers are already off it when #1982 lands. The two are
+ * unrelated — the client helper is not re-exported from `src/client/index.ts`
+ * and the CLI does not depend on the client package.
+ *
+ * Note: the list methods in `api-client.ts` that re-emit the deprecated
+ * `cursor` alias are deliberately NOT routed through this helper — they must
+ * keep dual-emitting until #1982 closes its deprecation window, which is the
+ * opposite of this contract. As of this writing that is eight methods (grep
+ * `cursor: nextCursor` in `api-client.ts` for the current set):
+ * `listInvitations`, `listWebhookEvents`, `listWorkflowRuns`,
+ * `listUserWorkflowRuns`, `listAllAdmins`, `listGroups`, `listGroupMembers`,
+ * `listBucketBlobs`. The `listCollection*` methods only *read* the alias and
+ * emit `nextCursor` alone, so they already match this contract.
+ *
+ * `databases operations execute` routes through here too, but conditionally: a
+ * registered operation is only sometimes a list, so
+ * `normalizeDatabaseOperationResult()` (`api-client.ts`) tests the result shape
+ * first and calls this helper only for a Durable Object query page (#2440).
+ */
+export function normalizeCliListEnvelope(raw) {
+    const page = raw;
+    const rawItems = page && typeof page === "object" && !Array.isArray(page)
+        ? (page.items ?? page.data)
+        : undefined;
+    if (!Array.isArray(rawItems)) {
+        throw new Error("Unexpected list response: expected an object with an `items` or `data` array.");
+    }
+    const nextCursor = page.nextCursor ?? page.cursor ?? undefined;
+    const envelope = {
+        items: rawItems,
+        hasMore: typeof page.hasMore === "boolean" ? page.hasMore : Boolean(nextCursor),
+    };
+    if (nextCursor)
+        envelope.nextCursor = nextCursor;
+    return envelope;
+}
+/**
+ * Walk every cursor page from `fetchPage` and return the concatenated items.
+ *
+ * Detects two failure modes that would otherwise hang the CLI:
+ *   - A cursor that repeats (server returned the same `nextCursor` twice).
+ *   - A cursor chain longer than `maxPages` (default 1000).
+ * Both throw so the caller fails loudly rather than looping forever.
+ */
+export async function paginateAll(fetchPage, options = {}) {
+    const maxPages = options.maxPages ?? 1000;
+    const all = [];
+    const seenCursors = new Set();
+    let cursor;
+    for (let page = 0; page < maxPages; page++) {
+        const resp = await fetchPage(cursor);
+        if (Array.isArray(resp.items)) {
+            all.push(...resp.items);
+        }
+        const next = resp.nextCursor ?? undefined;
+        if (!next) {
+            return all;
+        }
+        if (seenCursors.has(next)) {
+            throw new Error(`Pagination cursor did not advance (cursor ${next} repeated); aborting to avoid an infinite loop.`);
+        }
+        seenCursors.add(next);
+        cursor = next;
+    }
+    throw new Error(`Pagination exceeded ${maxPages} pages without terminating; server cursor may not be advancing.`);
+}
+//# sourceMappingURL=paginate.js.map

package/dist/src/lib/paginate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paginate.js","sourceRoot":"","sources":["../../../src/lib/paginate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAqBH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,MAAM,UAAU,wBAAwB,CAAU,GAAY;IAC5D,MAAM,IAAI,GAAG,GAA6C,CAAC;IAC3D,MAAM,QAAQ,GACZ,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC;QACtD,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,IAAI,CAAC;QAC3B,CAAC,CAAC,SAAS,CAAC;IAEhB,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC7B,MAAM,IAAI,KAAK,CACb,+EAA+E,CAChF,CAAC;IACJ,CAAC;IAED,MAAM,UAAU,GAAG,IAAK,CAAC,UAAU,IAAI,IAAK,CAAC,MAAM,IAAI,SAAS,CAAC;IACjE,MAAM,QAAQ,GAAoB;QAChC,KAAK,EAAE,QAAe;QACtB,OAAO,EACL,OAAO,IAAK,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,IAAK,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC;KAC3E,CAAC;IACF,IAAI,UAAU;QAAE,QAAQ,CAAC,UAAU,GAAG,UAAU,CAAC;IACjD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAaD;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,SAAyB,EACzB,UAA2B,EAAE;IAE7B,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,IAAI,CAAC;IAC1C,MAAM,GAAG,GAAQ,EAAE,CAAC;IACpB,MAAM,WAAW,GAAG,IAAI,GAAG,EAAU,CAAC;IACtC,IAAI,MAA0B,CAAC;IAE/B,KAAK,IAAI,IAAI,GAAG,CAAC,EAAE,IAAI,GAAG,QAAQ,EAAE,IAAI,EAAE,EAAE,CAAC;QAC3C,MAAM,IAAI,GAAG,MAAM,SAAS,CAAC,MAAM,CAAC,CAAC;QACrC,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;YAC9B,GAAG,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC;QAC1B,CAAC;QACD,MAAM,IAAI,GAAG,IAAI,CAAC,UAAU,IAAI,SAAS,CAAC;QAC1C,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,OAAO,GAAG,CAAC;QACb,CAAC;QACD,IAAI,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YAC1B,MAAM,IAAI,KAAK,CACb,6CAA6C,IAAI,iDAAiD,CACnG,CAAC;QACJ,CAAC;QACD,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACtB,MAAM,GAAG,IAAI,CAAC;IAChB,CAAC;IAED,MAAM,IAAI,KAAK,CACb,uBAAuB,QAAQ,iEAAiE,CACjG,CAAC;AACJ,CAAC"}

package/dist/src/lib/platform-owned.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Shared predicate for platform-owned workflows (#1660).
+ *
+ * The platform owns workflow keys in the reserved `__internal.` namespace (see
+ * the server's `src/workflows/reserved-workflow-keys.ts`). These rows are
+ * created and managed by the platform, never authored in an app's config tree:
+ *
+ *   - `config pull` must not export them (they have no local TOML),
+ *   - `config diff` must not report them (they are not app config),
+ *   - `config push` must not upload them (the hollow export can't round-trip),
+ *   - `workflows codegen` must not generate an invoker for them.
+ *
+ * The CLI cannot import from `src/`, so this module mirrors the server's prefix
+ * policy in ONE place. The codegen skip and the sync filters both call it, so
+ * they can never drift from each other or from the server.
+ *
+ * The generic cross-resource `isPlatformOwnedEntity` abstraction is deliberately
+ * NOT here — it is deferred until a second resource type has a platform-owned
+ * contract (human decision, 2026-07-17).
+ */
+/** Prefix marking a platform-owned workflow key (mirrors the server). */
+export declare const INTERNAL_WORKFLOW_KEY_PREFIX = "__internal.";
+/**
+ * True when `key` is in the platform-owned `__internal.` namespace. Trims and
+ * lowercases first (mirrors the server's `isReservedWorkflowKey`) so a padded
+ * or upper-cased value such as `  __Internal.Foo ` can't slip past the filter.
+ */
+export declare function isPlatformOwnedWorkflowKey(key: unknown): boolean;
+/**
+ * True when a workflow list/detail item is platform-owned.
+ *
+ * Prefers the server's derived `platformOwned` flag (#1660) when present, then
+ * falls back to the key prefix so an older server that doesn't emit the flag is
+ * still filtered (edge case 1). `workflowKey` is the admin list-item field;
+ * `key` covers a locally-parsed `[workflow]` table.
+ */
+export declare function isPlatformOwnedWorkflow(item: any): boolean;
+/**
+ * Why the authoring surface refuses a platform-owned key (#2645).
+ *
+ * `config create`, `config set` and `config push --only` all name an object by
+ * `<type>/<key>`, and `config push` skips the reserved namespace — so scaffolding
+ * or selecting one produces a file that is never uploaded, or a push that
+ * reports success having applied nothing. With configuration authored in TOML
+ * only, those are the two failures the surface has to make impossible: a flag
+ * that was rejected was visible, a file that is silently ignored is not.
+ *
+ * Returns the operator-facing reason, or `undefined` when the key is authorable.
+ * Pure, so every caller can be unit-tested without a live server.
+ */
+export declare function platformOwnedAuthoringError(type: string, key: string): string | undefined;
+/**
+ * Why the authoring surface refuses `<type>/<key>` — or `undefined` when it
+ * doesn't.
+ *
+ * The same question `config create`, `config set` and `config push --only`
+ * each ask before touching a file, now with two answers: a platform-owned
+ * workflow key (#1660/#2645) and a retired email type (#2884). Both fail the
+ * same way if unchecked — a file that is written locally and then either
+ * skipped silently or refused at the far end of a push — so both are refused
+ * at the point the key is named, with the sentence that says what to do.
+ */
+export declare function configAuthoringError(type: string, key: string): string | undefined;

package/dist/src/lib/platform-owned.js

@@ -0,0 +1,85 @@
+/**
+ * Shared predicate for platform-owned workflows (#1660).
+ *
+ * The platform owns workflow keys in the reserved `__internal.` namespace (see
+ * the server's `src/workflows/reserved-workflow-keys.ts`). These rows are
+ * created and managed by the platform, never authored in an app's config tree:
+ *
+ *   - `config pull` must not export them (they have no local TOML),
+ *   - `config diff` must not report them (they are not app config),
+ *   - `config push` must not upload them (the hollow export can't round-trip),
+ *   - `workflows codegen` must not generate an invoker for them.
+ *
+ * The CLI cannot import from `src/`, so this module mirrors the server's prefix
+ * policy in ONE place. The codegen skip and the sync filters both call it, so
+ * they can never drift from each other or from the server.
+ *
+ * The generic cross-resource `isPlatformOwnedEntity` abstraction is deliberately
+ * NOT here — it is deferred until a second resource type has a platform-owned
+ * contract (human decision, 2026-07-17).
+ */
+import { isRetiredEmailType, retiredEmailTypeGuidance, } from "./generated-config-surfaces.js";
+/** Prefix marking a platform-owned workflow key (mirrors the server). */
+export const INTERNAL_WORKFLOW_KEY_PREFIX = "__internal.";
+/**
+ * True when `key` is in the platform-owned `__internal.` namespace. Trims and
+ * lowercases first (mirrors the server's `isReservedWorkflowKey`) so a padded
+ * or upper-cased value such as `  __Internal.Foo ` can't slip past the filter.
+ */
+export function isPlatformOwnedWorkflowKey(key) {
+    return (typeof key === "string" &&
+        key.trim().toLowerCase().startsWith(INTERNAL_WORKFLOW_KEY_PREFIX));
+}
+/**
+ * True when a workflow list/detail item is platform-owned.
+ *
+ * Prefers the server's derived `platformOwned` flag (#1660) when present, then
+ * falls back to the key prefix so an older server that doesn't emit the flag is
+ * still filtered (edge case 1). `workflowKey` is the admin list-item field;
+ * `key` covers a locally-parsed `[workflow]` table.
+ */
+export function isPlatformOwnedWorkflow(item) {
+    if (item && item.platformOwned === true)
+        return true;
+    const key = item?.workflowKey ?? item?.key;
+    return isPlatformOwnedWorkflowKey(key);
+}
+/**
+ * Why the authoring surface refuses a platform-owned key (#2645).
+ *
+ * `config create`, `config set` and `config push --only` all name an object by
+ * `<type>/<key>`, and `config push` skips the reserved namespace — so scaffolding
+ * or selecting one produces a file that is never uploaded, or a push that
+ * reports success having applied nothing. With configuration authored in TOML
+ * only, those are the two failures the surface has to make impossible: a flag
+ * that was rejected was visible, a file that is silently ignored is not.
+ *
+ * Returns the operator-facing reason, or `undefined` when the key is authorable.
+ * Pure, so every caller can be unit-tested without a live server.
+ */
+export function platformOwnedAuthoringError(type, key) {
+    if (type !== "workflow" || !isPlatformOwnedWorkflowKey(key))
+        return undefined;
+    return `'${key}' is a platform-owned workflow — the reserved '${INTERNAL_WORKFLOW_KEY_PREFIX}' namespace is managed by the platform. 'config pull' does not export these and 'config push' skips them, so a file here would never reach the server.`;
+}
+/**
+ * Why the authoring surface refuses `<type>/<key>` — or `undefined` when it
+ * doesn't.
+ *
+ * The same question `config create`, `config set` and `config push --only`
+ * each ask before touching a file, now with two answers: a platform-owned
+ * workflow key (#1660/#2645) and a retired email type (#2884). Both fail the
+ * same way if unchecked — a file that is written locally and then either
+ * skipped silently or refused at the far end of a push — so both are refused
+ * at the point the key is named, with the sentence that says what to do.
+ */
+export function configAuthoringError(type, key) {
+    const platformOwned = platformOwnedAuthoringError(type, key);
+    if (platformOwned)
+        return platformOwned;
+    if (type === "email-template" && isRetiredEmailType(key)) {
+        return retiredEmailTypeGuidance(key);
+    }
+    return undefined;
+}
+//# sourceMappingURL=platform-owned.js.map

package/dist/src/lib/platform-owned.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform-owned.js","sourceRoot":"","sources":["../../../src/lib/platform-owned.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EACL,kBAAkB,EAClB,wBAAwB,GACzB,MAAM,gCAAgC,CAAC;AAExC,yEAAyE;AACzE,MAAM,CAAC,MAAM,4BAA4B,GAAG,aAAa,CAAC;AAE1D;;;;GAIG;AACH,MAAM,UAAU,0BAA0B,CAAC,GAAY;IACrD,OAAO,CACL,OAAO,GAAG,KAAK,QAAQ;QACvB,GAAG,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,UAAU,CAAC,4BAA4B,CAAC,CAClE,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,uBAAuB,CAAC,IAAS;IAC/C,IAAI,IAAI,IAAI,IAAI,CAAC,aAAa,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACrD,MAAM,GAAG,GAAG,IAAI,EAAE,WAAW,IAAI,IAAI,EAAE,GAAG,CAAC;IAC3C,OAAO,0BAA0B,CAAC,GAAG,CAAC,CAAC;AACzC,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,2BAA2B,CACzC,IAAY,EACZ,GAAW;IAEX,IAAI,IAAI,KAAK,UAAU,IAAI,CAAC,0BAA0B,CAAC,GAAG,CAAC;QAAE,OAAO,SAAS,CAAC;IAC9E,OAAO,IAAI,GAAG,kDAAkD,4BAA4B,wJAAwJ,CAAC;AACvP,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,oBAAoB,CAClC,IAAY,EACZ,GAAW;IAEX,MAAM,aAAa,GAAG,2BAA2B,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IAC7D,IAAI,aAAa;QAAE,OAAO,aAAa,CAAC;IACxC,IAAI,IAAI,KAAK,gBAAgB,IAAI,kBAAkB,CAAC,GAAG,CAAC,EAAE,CAAC;QACzD,OAAO,wBAAwB,CAAC,GAAG,CAAC,CAAC;IACvC,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/src/lib/project-config.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Project-scoped configuration (.primitive/config.json).
+ *
+ * This module handles loading, validating, and saving the project config file
+ * that lives inside the .primitive/ directory at the project root. The config
+ * defines named environments (dev, prod, staging, etc.) with their API URLs
+ * and app IDs.
+ *
+ * Design:
+ *   - Config file: .primitive/config.json (or any ancestor directory)
+ *   - The .primitive/ directory groups the committable config and the
+ *     gitignored local state (credentials, sync data) in one place.
+ *   - Format: JSON
+ *   - Schema is versioned (currently 1). Future versions use semver-ish
+ *     caret range compatibility: we accept any config where major version
+ *     matches CURRENT_CONFIG_VERSION.
+ *   - Invalid configs throw — we do NOT silently ignore malformed files.
+ */
+/**
+ * Current schema version. Increment the major version when making
+ * backward-incompatible changes. Older configs will be rejected.
+ */
+export declare const CURRENT_CONFIG_VERSION = 1;
+/**
+ * The config file lives inside the .primitive/ directory, not at the
+ * project root. This keeps the project root clean and groups all
+ * Primitive state (config, credentials, sync data) under one directory.
+ */
+export declare const PROJECT_CONFIG_DIR = ".primitive";
+export declare const PROJECT_CONFIG_FILENAME = "config.json";
+/** Display name used in user-facing messages. */
+export declare const PROJECT_CONFIG_DISPLAY_NAME = ".primitive/config.json";
+export interface ProjectEnvironment {
+    apiUrl: string;
+    appId?: string;
+    appName?: string;
+    /** Optional notes about this environment. */
+    description?: string;
+}
+export interface ProjectConfig {
+    /** Schema version (currently 1). */
+    version: number;
+    /**
+     * Default environment name to use when --env is not specified and
+     * PRIMITIVE_ENV is unset.
+     */
+    defaultEnvironment?: string;
+    /**
+     * Named environments keyed by short name (e.g. "dev", "prod", "staging").
+     */
+    environments: Record<string, ProjectEnvironment>;
+}
+export declare class ProjectConfigError extends Error {
+    readonly path?: string;
+    constructor(message: string, path?: string);
+}
+/**
+ * Walks upward from `startDir` looking for a `.primitive/config.json` file.
+ * Returns the absolute path to the config file, or null if not found.
+ *
+ * Allows running `primitive` commands from subdirectories of a project,
+ * much like `git` walks up to find `.git`.
+ */
+export declare function findProjectConfigPath(startDir?: string): string | null;
+/**
+ * Returns the project root directory (the parent of .primitive/ that contains
+ * .primitive/config.json), or null if no project config is found.
+ *
+ * When the PRIMITIVE_PROJECT_CONFIG env var override is active, the config
+ * file may not live inside a `.primitive/` directory (e.g. in tests), so
+ * we simply go up one level from the file.
+ */
+export declare function findProjectRoot(startDir?: string): string | null;
+/**
+ * Validates a raw parsed object against the ProjectConfig schema.
+ * Throws ProjectConfigError with a helpful message on any problem.
+ */
+export declare function validateProjectConfig(raw: unknown, sourcePath?: string): ProjectConfig;
+/**
+ * Loads and validates the project config from a specific file path.
+ * Throws ProjectConfigError on I/O errors, JSON parse errors, or schema
+ * validation failures — we deliberately do NOT swallow these, because a
+ * broken config should be noisy so the user can fix it.
+ */
+export declare function loadProjectConfigFromPath(path: string): ProjectConfig;
+/**
+ * Loads the project config by searching upward from the current directory.
+ * Returns null (not an error) if no .primitive/config.json is found anywhere.
+ * Still throws ProjectConfigError if a config IS found but is invalid.
+ */
+export declare function loadProjectConfig(startDir?: string): ProjectConfig | null;
+/**
+ * Writes a project config to disk as pretty-printed JSON. Callers are
+ * responsible for ensuring the parent directory exists — this function
+ * does not try to be clever about location.
+ */
+export declare function saveProjectConfig(path: string, config: ProjectConfig): void;

package/dist/src/lib/project-config.js

@@ -0,0 +1,217 @@
+/**
+ * Project-scoped configuration (.primitive/config.json).
+ *
+ * This module handles loading, validating, and saving the project config file
+ * that lives inside the .primitive/ directory at the project root. The config
+ * defines named environments (dev, prod, staging, etc.) with their API URLs
+ * and app IDs.
+ *
+ * Design:
+ *   - Config file: .primitive/config.json (or any ancestor directory)
+ *   - The .primitive/ directory groups the committable config and the
+ *     gitignored local state (credentials, sync data) in one place.
+ *   - Format: JSON
+ *   - Schema is versioned (currently 1). Future versions use semver-ish
+ *     caret range compatibility: we accept any config where major version
+ *     matches CURRENT_CONFIG_VERSION.
+ *   - Invalid configs throw — we do NOT silently ignore malformed files.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { dirname, join, resolve } from "path";
+import { detectInstall, installCommand, upgradeCommand, PRIMITIVE_CLI_PACKAGE, } from "./package-manager.js";
+import { validateServerUrl } from "./server-url.js";
+/**
+ * The command that upgrades the running CLI. Falls back to the first-time
+ * install command when the running copy can't be upgraded by a package
+ * manager (a source checkout).
+ */
+function cliUpgradeCommand() {
+    return (upgradeCommand(detectInstall(), PRIMITIVE_CLI_PACKAGE, "latest") ??
+        installCommand(PRIMITIVE_CLI_PACKAGE));
+}
+/**
+ * Current schema version. Increment the major version when making
+ * backward-incompatible changes. Older configs will be rejected.
+ */
+export const CURRENT_CONFIG_VERSION = 1;
+/**
+ * The config file lives inside the .primitive/ directory, not at the
+ * project root. This keeps the project root clean and groups all
+ * Primitive state (config, credentials, sync data) under one directory.
+ */
+export const PROJECT_CONFIG_DIR = ".primitive";
+export const PROJECT_CONFIG_FILENAME = "config.json";
+/** Display name used in user-facing messages. */
+export const PROJECT_CONFIG_DISPLAY_NAME = ".primitive/config.json";
+export class ProjectConfigError extends Error {
+    path;
+    constructor(message, path) {
+        super(message);
+        this.path = path;
+        this.name = "ProjectConfigError";
+    }
+}
+/**
+ * Walks upward from `startDir` looking for a `.primitive/config.json` file.
+ * Returns the absolute path to the config file, or null if not found.
+ *
+ * Allows running `primitive` commands from subdirectories of a project,
+ * much like `git` walks up to find `.git`.
+ */
+export function findProjectConfigPath(startDir = process.cwd()) {
+    // Allow override via env var for testing / unusual setups.
+    if (process.env.PRIMITIVE_PROJECT_CONFIG) {
+        const forced = resolve(process.env.PRIMITIVE_PROJECT_CONFIG);
+        return existsSync(forced) ? forced : null;
+    }
+    let current = resolve(startDir);
+    // Walk up until we hit filesystem root.
+    while (true) {
+        const candidate = join(current, PROJECT_CONFIG_DIR, PROJECT_CONFIG_FILENAME);
+        if (existsSync(candidate))
+            return candidate;
+        const parent = dirname(current);
+        if (parent === current)
+            return null;
+        current = parent;
+    }
+}
+/**
+ * Returns the project root directory (the parent of .primitive/ that contains
+ * .primitive/config.json), or null if no project config is found.
+ *
+ * When the PRIMITIVE_PROJECT_CONFIG env var override is active, the config
+ * file may not live inside a `.primitive/` directory (e.g. in tests), so
+ * we simply go up one level from the file.
+ */
+export function findProjectRoot(startDir = process.cwd()) {
+    const path = findProjectConfigPath(startDir);
+    if (!path)
+        return null;
+    // When using the env var override, the file could be anywhere — just go
+    // up one level. In the normal case the path ends with .primitive/config.json
+    // so dirname(dirname(path)) gives the project root.
+    if (process.env.PRIMITIVE_PROJECT_CONFIG) {
+        return dirname(path);
+    }
+    return dirname(dirname(path));
+}
+/**
+ * Validates a raw parsed object against the ProjectConfig schema.
+ * Throws ProjectConfigError with a helpful message on any problem.
+ */
+export function validateProjectConfig(raw, sourcePath) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        throw new ProjectConfigError(`${PROJECT_CONFIG_DISPLAY_NAME} must contain a JSON object at the top level.`, sourcePath);
+    }
+    const obj = raw;
+    // Version is required.
+    if (typeof obj.version !== "number" || !Number.isInteger(obj.version)) {
+        throw new ProjectConfigError(`${PROJECT_CONFIG_DISPLAY_NAME} is missing required integer field "version".`, sourcePath);
+    }
+    const version = obj.version;
+    // Caret-range compatibility: accept any config whose major version matches.
+    // For version 1.x this is simply version === 1; when we ship v2 we'll
+    // reject v1 configs and tell the user to migrate.
+    if (version !== CURRENT_CONFIG_VERSION) {
+        if (version > CURRENT_CONFIG_VERSION) {
+            throw new ProjectConfigError(`${PROJECT_CONFIG_DISPLAY_NAME} has version ${version}, but this CLI only understands version ${CURRENT_CONFIG_VERSION}. Please upgrade the CLI: ${cliUpgradeCommand()}`, sourcePath);
+        }
+        throw new ProjectConfigError(`${PROJECT_CONFIG_DISPLAY_NAME} has unsupported version ${version}. This CLI expects version ${CURRENT_CONFIG_VERSION}.`, sourcePath);
+    }
+    // environments is required.
+    if (!obj.environments || typeof obj.environments !== "object" || Array.isArray(obj.environments)) {
+        throw new ProjectConfigError(`${PROJECT_CONFIG_DISPLAY_NAME} is missing required "environments" object.`, sourcePath);
+    }
+    const environments = {};
+    for (const [name, envRaw] of Object.entries(obj.environments)) {
+        if (!name.match(/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/)) {
+            throw new ProjectConfigError(`Invalid environment name "${name}" in ${PROJECT_CONFIG_DISPLAY_NAME}. Names must be alphanumeric with optional dashes/underscores.`, sourcePath);
+        }
+        if (!envRaw || typeof envRaw !== "object" || Array.isArray(envRaw)) {
+            throw new ProjectConfigError(`Environment "${name}" must be an object in ${PROJECT_CONFIG_DISPLAY_NAME}.`, sourcePath);
+        }
+        const envObj = envRaw;
+        if (typeof envObj.apiUrl !== "string" || !envObj.apiUrl) {
+            throw new ProjectConfigError(`Environment "${name}" must have a non-empty "apiUrl" string in ${PROJECT_CONFIG_DISPLAY_NAME}.`, sourcePath);
+        }
+        if (validateServerUrl(envObj.apiUrl) !== true) {
+            throw new ProjectConfigError(`Environment "${name}" has invalid apiUrl: ${envObj.apiUrl}`, sourcePath);
+        }
+        if (envObj.appId !== undefined && typeof envObj.appId !== "string") {
+            throw new ProjectConfigError(`Environment "${name}": "appId" must be a string if set.`, sourcePath);
+        }
+        if (envObj.appName !== undefined && typeof envObj.appName !== "string") {
+            throw new ProjectConfigError(`Environment "${name}": "appName" must be a string if set.`, sourcePath);
+        }
+        if (envObj.description !== undefined && typeof envObj.description !== "string") {
+            throw new ProjectConfigError(`Environment "${name}": "description" must be a string if set.`, sourcePath);
+        }
+        environments[name] = {
+            apiUrl: envObj.apiUrl.replace(/\/$/, ""),
+            appId: envObj.appId,
+            appName: envObj.appName,
+            description: envObj.description,
+        };
+    }
+    // defaultEnvironment is optional but must refer to a real environment.
+    let defaultEnvironment;
+    if (obj.defaultEnvironment !== undefined) {
+        if (typeof obj.defaultEnvironment !== "string") {
+            throw new ProjectConfigError(`"defaultEnvironment" must be a string if set.`, sourcePath);
+        }
+        if (obj.defaultEnvironment && !environments[obj.defaultEnvironment]) {
+            throw new ProjectConfigError(`"defaultEnvironment" is set to "${obj.defaultEnvironment}" but no such environment is defined.`, sourcePath);
+        }
+        defaultEnvironment = obj.defaultEnvironment || undefined;
+    }
+    return { version, defaultEnvironment, environments };
+}
+/**
+ * Loads and validates the project config from a specific file path.
+ * Throws ProjectConfigError on I/O errors, JSON parse errors, or schema
+ * validation failures — we deliberately do NOT swallow these, because a
+ * broken config should be noisy so the user can fix it.
+ */
+export function loadProjectConfigFromPath(path) {
+    let raw;
+    try {
+        raw = readFileSync(path, "utf-8");
+    }
+    catch (err) {
+        throw new ProjectConfigError(`Failed to read ${PROJECT_CONFIG_DISPLAY_NAME}: ${err.message}`, path);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new ProjectConfigError(`Failed to parse ${PROJECT_CONFIG_DISPLAY_NAME}: ${err.message}`, path);
+    }
+    return validateProjectConfig(parsed, path);
+}
+/**
+ * Loads the project config by searching upward from the current directory.
+ * Returns null (not an error) if no .primitive/config.json is found anywhere.
+ * Still throws ProjectConfigError if a config IS found but is invalid.
+ */
+export function loadProjectConfig(startDir = process.cwd()) {
+    const path = findProjectConfigPath(startDir);
+    if (!path)
+        return null;
+    return loadProjectConfigFromPath(path);
+}
+/**
+ * Writes a project config to disk as pretty-printed JSON. Callers are
+ * responsible for ensuring the parent directory exists — this function
+ * does not try to be clever about location.
+ */
+export function saveProjectConfig(path, config) {
+    const dir = dirname(path);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    const serialized = JSON.stringify(config, null, 2) + "\n";
+    writeFileSync(path, serialized);
+}
+//# sourceMappingURL=project-config.js.map

package/dist/src/lib/project-config.js.map

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

package/dist/src/lib/query-operators.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Shared constant for the query operators an operation `filter` may use,
+ * plus a helper to find operator keys that aren't in the supported set.
+ *
+ * Background (issue #1255): a database-operation `filter` uses Mongo-style
+ * operators (`$gte`, `$in`, ...). A typo like `$gt` → `$gte` or an invented
+ * `$foo` silently passes `config push` (the server only validates `filter` is
+ * an object) and then throws `InvalidOperatorError` at *query execution*.
+ * The CLI can warn about unknown operators at push time so the author fixes
+ * it before it reaches runtime.
+ *
+ * The set mirrors the runtime translator
+ * (`packages/js-bao/src/query/JsonQueryTranslator.ts`): field operators
+ * (`translateFieldCondition` / substring ops) plus the two logical
+ * combinators special-cased in `translateFilter` (`$and` / `$or`).
+ *
+ * `$not` is intentionally NOT included — it is not a runtime operator; the
+ * translator only special-cases `$and` / `$or`, so `$not` would throw at
+ * execution just like any other unknown operator (codex review, #1255).
+ *
+ * This is deliberately a single source of truth so the validator and any
+ * future emitter/detector agree on what "known" means.
+ */
+/** Field-level comparison / membership / string operators. */
+export declare const FIELD_QUERY_OPERATORS: readonly string[];
+/** Logical combinators (arrays of sub-filters). */
+export declare const LOGICAL_QUERY_OPERATORS: readonly string[];
+/**
+ * Every operator the runtime query translator accepts. Any `$`-prefixed
+ * *key* inside a filter that is not in this set is unknown.
+ */
+export declare const SUPPORTED_QUERY_OPERATORS: ReadonlySet<string>;
+/**
+ * Recursively collect the distinct `$`-prefixed *keys* used in a filter (or
+ * any nested value) that are not in {@link SUPPORTED_QUERY_OPERATORS}.
+ *
+ * Only object *keys* are considered operators — matching the runtime
+ * convention (`walk-operation.ts`: `$`-prefixed keys are operators). String
+ * *values* like `$params.activeSince` are substitution references, never
+ * operators, so they are never flagged. `$and` / `$or` values are arrays of
+ * sub-filter objects and are walked recursively.
+ */
+export declare function collectUnknownOperators(value: any): string[];