primitive-admin 1.1.0-alpha.8 → 1.1.0-alpha.80

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

@@ -0,0 +1,122 @@
+/**
+ * Project-scoped configuration (primitive/config.json).
+ *
+ * This module handles loading, validating, and saving the project config file
+ * that lives inside the committed `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)
+ *   - `primitive/` is committed — the config plus each environment's TOML;
+ *     `.primitive/` is machine-local state and is gitignored whole (#3153).
+ *   - 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 one set of layout constants, owned by the resolver core so the CLI, the
+ * Vite plugin and the Swift script cannot disagree about where the tree is
+ * (#3153). Re-exported here because most of the CLI imports its config
+ * vocabulary from this module.
+ */
+export { PROJECT_TREE_DIR, PROJECT_LOCAL_STATE_DIR, PROJECT_CONFIG_FILENAME, PROJECT_CONFIG_DISPLAY_NAME, } from "./env-resolver-core.js";
+export interface ProjectEnvironment {
+    apiUrl: string;
+    /**
+     * The one app this environment names (#3152). Required: selecting an
+     * environment selects exactly one app, which is what lets the CLI drop its
+     * second, per-machine notion of "the current app".
+     */
+    appId: string;
+    appName?: string;
+    /**
+     * The app's web counterpart for this environment, as a normalized origin
+     * (`https://app.example.com`) — the deployment whose `/oauth/callback` the
+     * emailed sign-in link points at, and the origin an incoming universal link
+     * is trusted from (#2982). Per environment, because that deployment has to
+     * talk to the same backend and app as this entry.
+     */
+    webUrl?: string;
+    /**
+     * The iOS client's Apple app identifier for this environment —
+     * `<Application Identifier Prefix>.<bundle id>`, the prefix usually being the
+     * Team ID (#3081). Per environment, because an app with alpha and production
+     * has one bundle id each; declared beside `webUrl`, because the two halves
+     * name one cross-client link and the Vue template's deploy generates the
+     * `apple-app-site-association` document from the pair.
+     */
+    iosAppId?: 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`.
+ *
+ * One walk, not two: this delegates to the resolver core (#3153) so the CLI
+ * and every other reader refuse the pre-move layout identically — a second
+ * copy of the walk here is exactly how the stale-layout refusal would come to
+ * mean two different things.
+ */
+export declare function findProjectConfigPath(startDir?: string): string | null;
+/**
+ * Returns the project root directory (the parent of `primitive/`, which holds
+ * `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), and then
+ * the root is simply the containing directory.
+ */
+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,244 @@
+/**
+ * Project-scoped configuration (primitive/config.json).
+ *
+ * This module handles loading, validating, and saving the project config file
+ * that lives inside the committed `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)
+ *   - `primitive/` is committed — the config plus each environment's TOML;
+ *     `.primitive/` is machine-local state and is gitignored whole (#3153).
+ *   - 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 } from "path";
+import { detectInstall, installCommand, upgradeCommand, PRIMITIVE_CLI_PACKAGE, } from "./package-manager.js";
+import { findPrimitiveConfigPath, missingAppIdMessage, projectRootForConfigPath, PROJECT_CONFIG_DISPLAY_NAME, } from "./env-resolver-core.js";
+import { normalizeIosAppId, validateIosAppId } from "./ios-app-id.js";
+import { validateServerUrl } from "./server-url.js";
+import { normalizeWebUrl, validateWebUrl } from "./web-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 one set of layout constants, owned by the resolver core so the CLI, the
+ * Vite plugin and the Swift script cannot disagree about where the tree is
+ * (#3153). Re-exported here because most of the CLI imports its config
+ * vocabulary from this module.
+ */
+export { PROJECT_TREE_DIR, PROJECT_LOCAL_STATE_DIR, PROJECT_CONFIG_FILENAME, PROJECT_CONFIG_DISPLAY_NAME, } from "./env-resolver-core.js";
+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`.
+ *
+ * One walk, not two: this delegates to the resolver core (#3153) so the CLI
+ * and every other reader refuse the pre-move layout identically — a second
+ * copy of the walk here is exactly how the stale-layout refusal would come to
+ * mean two different things.
+ */
+export function findProjectConfigPath(startDir = process.cwd()) {
+    return findPrimitiveConfigPath({ cwd: startDir });
+}
+/**
+ * Returns the project root directory (the parent of `primitive/`, which holds
+ * `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), and then
+ * the root is simply the containing directory.
+ */
+export function findProjectRoot(startDir = process.cwd()) {
+    const path = findProjectConfigPath(startDir);
+    if (!path)
+        return null;
+    return projectRootForConfigPath(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);
+        }
+        // Every environment names exactly one app (#3152) — for EVERY environment
+        // in the file, not just the one this invocation resolves, because the file
+        // is what the criterion is about and because the Vite plugin, cf-deploy
+        // and the Swift pre-build script may each select a different one.
+        // Non-string and blank-after-trim are the same failure as absent: an app id
+        // no consumer could use.
+        const appId = typeof envObj.appId === "string" ? envObj.appId.trim() : "";
+        if (!appId) {
+            throw new ProjectConfigError(missingAppIdMessage(name, sourcePath), 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);
+        }
+        // An origin, not any URL: the emailed sign-in link is built from it, so a
+        // value the server's allow-list would refuse — or one whose callback path
+        // neither the web app nor the AASA component names — is a 400 or a dead
+        // link later rather than an error here (#2982).
+        if (envObj.webUrl !== undefined) {
+            if (typeof envObj.webUrl !== "string") {
+                throw new ProjectConfigError(`Environment "${name}": "webUrl" must be a string if set.`, sourcePath);
+            }
+            const problem = validateWebUrl(envObj.webUrl);
+            if (problem !== true) {
+                throw new ProjectConfigError(`Environment "${name}" has invalid webUrl: ${problem}`, sourcePath);
+            }
+        }
+        // The iOS half of the same cross-client link (#3081). Both or neither for
+        // an environment with an iOS client: an app id with no origin names an app
+        // for a domain this config does not know, and no deploy could serve the
+        // association document that pairs them.
+        if (envObj.iosAppId !== undefined) {
+            if (typeof envObj.iosAppId !== "string") {
+                throw new ProjectConfigError(`Environment "${name}": "iosAppId" must be a string if set.`, sourcePath);
+            }
+            const problem = validateIosAppId(envObj.iosAppId);
+            if (problem !== true) {
+                throw new ProjectConfigError(`Environment "${name}" has invalid iosAppId: ${problem}`, sourcePath);
+            }
+            if (envObj.webUrl === undefined) {
+                throw new ProjectConfigError(`Environment "${name}" sets "iosAppId" but no "webUrl". The association document that vouches for that app is served by the web app, so set "webUrl" to its origin — or drop "iosAppId" if this environment has no iOS client.`, sourcePath);
+            }
+        }
+        environments[name] = {
+            apiUrl: envObj.apiUrl.replace(/\/$/, ""),
+            appId,
+            appName: envObj.appName,
+            webUrl: envObj.webUrl === undefined
+                ? undefined
+                : normalizeWebUrl(envObj.webUrl),
+            iosAppId: envObj.iosAppId === undefined
+                ? undefined
+                : normalizeIosAppId(envObj.iosAppId),
+            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[];

package/dist/src/lib/query-operators.js

@@ -0,0 +1,80 @@
+/**
+ * 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 const FIELD_QUERY_OPERATORS = [
+    "$eq",
+    "$ne",
+    "$gt",
+    "$gte",
+    "$lt",
+    "$lte",
+    "$in",
+    "$nin",
+    "$exists",
+    "$contains",
+    "$startsWith",
+    "$endsWith",
+    "$containsText",
+];
+/** Logical combinators (arrays of sub-filters). */
+export const LOGICAL_QUERY_OPERATORS = ["$and", "$or"];
+/**
+ * Every operator the runtime query translator accepts. Any `$`-prefixed
+ * *key* inside a filter that is not in this set is unknown.
+ */
+export const SUPPORTED_QUERY_OPERATORS = new Set([
+    ...FIELD_QUERY_OPERATORS,
+    ...LOGICAL_QUERY_OPERATORS,
+]);
+/**
+ * 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 function collectUnknownOperators(value) {
+    const unknown = new Set();
+    walk(value, unknown);
+    return [...unknown];
+}
+function walk(value, unknown) {
+    if (Array.isArray(value)) {
+        for (const item of value)
+            walk(item, unknown);
+        return;
+    }
+    if (value !== null && typeof value === "object") {
+        for (const [key, child] of Object.entries(value)) {
+            if (key.startsWith("$") && !SUPPORTED_QUERY_OPERATORS.has(key)) {
+                unknown.add(key);
+            }
+            walk(child, unknown);
+        }
+    }
+}
+//# sourceMappingURL=query-operators.js.map

package/dist/src/lib/query-operators.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-operators.js","sourceRoot":"","sources":["../../../src/lib/query-operators.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,8DAA8D;AAC9D,MAAM,CAAC,MAAM,qBAAqB,GAAsB;IACtD,KAAK;IACL,KAAK;IACL,KAAK;IACL,MAAM;IACN,KAAK;IACL,MAAM;IACN,KAAK;IACL,MAAM;IACN,SAAS;IACT,WAAW;IACX,aAAa;IACb,WAAW;IACX,eAAe;CAChB,CAAC;AAEF,mDAAmD;AACnD,MAAM,CAAC,MAAM,uBAAuB,GAAsB,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;AAE1E;;;GAGG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAwB,IAAI,GAAG,CAAC;IACpE,GAAG,qBAAqB;IACxB,GAAG,uBAAuB;CAC3B,CAAC,CAAC;AAEH;;;;;;;;;GASG;AACH,MAAM,UAAU,uBAAuB,CAAC,KAAU;IAChD,MAAM,OAAO,GAAG,IAAI,GAAG,EAAU,CAAC;IAClC,IAAI,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IACrB,OAAO,CAAC,GAAG,OAAO,CAAC,CAAC;AACtB,CAAC;AAED,SAAS,IAAI,CAAC,KAAU,EAAE,OAAoB;IAC5C,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,KAAK,MAAM,IAAI,IAAI,KAAK;YAAE,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QAC9C,OAAO;IACT,CAAC;IACD,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAChD,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YACjD,IAAI,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,yBAAyB,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;gBAC/D,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YACnB,CAAC;YACD,IAAI,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QACvB,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/src/lib/record-filter.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Parse the shared `--filter` / `--filter-file` option pair used by the record
+ * read/query verbs on both surfaces: `databases records` (`query`, `count`,
+ * `aggregate`, `delete-all`) and `documents records` (`query`, `count`,
+ * `aggregate`).
+ *
+ * `--filter` takes an inline JSON object; `--filter-file` reads the filter from
+ * a JSON file, or a TOML file (either a top-level table or a `[filter]` section).
+ * The two options are mutually exclusive. All validation happens CLI-side so a
+ * malformed filter produces a clear error rather than a server 500.
+ *
+ * Exits the process with a clear message on bad input. Returns `undefined` when
+ * neither option is supplied.
+ */
+export declare function parseFilterOptions(options: {
+    filter?: string;
+    filterFile?: string;
+}): Record<string, any> | undefined;

package/dist/src/lib/record-filter.js

@@ -0,0 +1,55 @@
+import { readFileSync } from "fs";
+import { parseConfigToml } from "./config-toml.js";
+import { error } from "./output.js";
+/**
+ * Parse the shared `--filter` / `--filter-file` option pair used by the record
+ * read/query verbs on both surfaces: `databases records` (`query`, `count`,
+ * `aggregate`, `delete-all`) and `documents records` (`query`, `count`,
+ * `aggregate`).
+ *
+ * `--filter` takes an inline JSON object; `--filter-file` reads the filter from
+ * a JSON file, or a TOML file (either a top-level table or a `[filter]` section).
+ * The two options are mutually exclusive. All validation happens CLI-side so a
+ * malformed filter produces a clear error rather than a server 500.
+ *
+ * Exits the process with a clear message on bad input. Returns `undefined` when
+ * neither option is supplied.
+ */
+export function parseFilterOptions(options) {
+    if (options.filter && options.filterFile) {
+        error("Cannot use both --filter and --filter-file.");
+        process.exit(1);
+    }
+    if (options.filterFile) {
+        let content;
+        try {
+            content = readFileSync(options.filterFile, "utf-8");
+        }
+        catch (err) {
+            error(`Failed to read filter file: ${err.message}`);
+            process.exit(1);
+        }
+        try {
+            if (options.filterFile.endsWith(".toml")) {
+                const parsed = parseConfigToml(content);
+                return parsed.filter || parsed;
+            }
+            return JSON.parse(content);
+        }
+        catch (err) {
+            error(`Invalid filter file: ${err.message}`);
+            process.exit(1);
+        }
+    }
+    if (options.filter) {
+        try {
+            return JSON.parse(options.filter);
+        }
+        catch {
+            error("Invalid --filter JSON.");
+            process.exit(1);
+        }
+    }
+    return undefined;
+}
+//# sourceMappingURL=record-filter.js.map

package/dist/src/lib/record-filter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"record-filter.js","sourceRoot":"","sources":["../../../src/lib/record-filter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,IAAI,CAAC;AAClC,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAEpC;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAGlC;IACC,IAAI,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;QACzC,KAAK,CAAC,6CAA6C,CAAC,CAAC;QACrD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;QACvB,IAAI,OAAe,CAAC;QACpB,IAAI,CAAC;YACH,OAAO,GAAG,YAAY,CAAC,OAAO,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;QACtD,CAAC;QAAC,OAAO,GAAQ,EAAE,CAAC;YAClB,KAAK,CAAC,+BAA+B,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;YACpD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;QACD,IAAI,CAAC;YACH,IAAI,OAAO,CAAC,UAAU,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;gBACzC,MAAM,MAAM,GAAG,eAAe,CAAC,OAAO,CAAQ,CAAC;gBAC/C,OAAO,MAAM,CAAC,MAAM,IAAI,MAAM,CAAC;YACjC,CAAC;YACD,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QAC7B,CAAC;QAAC,OAAO,GAAQ,EAAE,CAAC;YAClB,KAAK,CAAC,wBAAwB,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;YAC7C,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;IACH,CAAC;IAED,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;QACnB,IAAI,CAAC;YACH,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QACpC,CAAC;QAAC,MAAM,CAAC;YACP,KAAK,CAAC,wBAAwB,CAAC,CAAC;YAChC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;IACH,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/src/lib/refresh-admin-credentials.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Shared helper for refreshing the admin access token via the CLI auth API.
+ *
+ * Why this module exists:
+ *
+ *   - `ApiClient.refreshToken()` already POSTs to /admin/api/auth/refresh
+ *     before every API call when the access token is near expiry.
+ *   - `primitive token` (issue #772) now needs the same exchange so it can
+ *     auto-refresh a stale token before printing it.
+ *   - `primitive login --token-stdin` does the same POST a third time to
+ *     bootstrap credentials from a refresh token piped from another CLI.
+ *
+ * Putting the HTTP exchange + response parsing in one place keeps the
+ * response-shape contract in a single spot (server returns both `jwt` and
+ * `accessToken` — see `src/index.ts:2349-2356`) and means future server
+ * changes to that endpoint require touching exactly one CLI file.
+ *
+ * Design notes:
+ *
+ *   - This module **does not** depend on `api-client.ts`. `ApiClient` imports
+ *     it, not the other way around — that prevents the avoidable module cycle
+ *     codex flagged in the design review.
+ *   - It defines its own `RefreshError` so callers can map failures to
+ *     whatever error type (or exit code) makes sense for their surface.
+ *     `ApiClient` translates these to `ApiError`; the `token` command
+ *     translates them to an `error()` + `process.exit(1)`.
+ *   - It **does not save** the refreshed credentials. The caller decides
+ *     whether to persist (the `token` command does; `ApiClient.refreshToken`
+ *     does). Keeping persistence caller-owned matches the existing
+ *     "storage is owned by `credentials-store.ts`" convention.
+ *   - It **does not print anything**. Output (success/failure messaging) is
+ *     the caller's responsibility — important because the `token` command
+ *     must keep stdout clean for piping.
+ */
+import type { Credentials } from "../types/index.js";
+/**
+ * Reasons a refresh attempt can fail. `unauthorized` covers any HTTP non-2xx
+ * response (typically a 401 from an expired/invalid refresh token).
+ * `network` covers transport-level failures (DNS, ECONNREFUSED, etc.).
+ * `missing-refresh-token` is a precondition failure — there's no token to
+ * send.
+ */
+export type RefreshFailureKind = "missing-refresh-token" | "unauthorized" | "network";
+export declare class RefreshError extends Error {
+    kind: RefreshFailureKind;
+    statusCode?: number;
+    cause?: unknown;
+    constructor(message: string, kind: RefreshFailureKind, statusCode?: number, cause?: unknown);
+}
+/**
+ * Exchange the stored refresh token for a fresh `accessToken`. Returns a new
+ * `Credentials` object — the caller is responsible for persistence via
+ * `saveCredentials()` (or whatever storage the caller owns).
+ *
+ * Server contract: `POST {serverUrl}/admin/api/auth/refresh` with
+ *   { refreshToken: string }
+ * Response (200):
+ *   { jwt, accessToken, refreshToken, expiresAt }
+ *
+ * We accept `accessToken` as the canonical field and fall back to `jwt` for
+ * forward-compat (the server currently emits both — see issue #772 codex
+ * cleanup #3). Login's legacy `data.token` form is dropped — no server
+ * version that's still in support emits that field.
+ */
+export declare function refreshAdminCredentials(credentials: Credentials): Promise<Credentials>;