primitive-admin 1.0.53 → 1.0.55

package/dist/src/lib/app-settings-descriptor.js

@@ -0,0 +1,250 @@
+/**
+ * Shared field descriptor for app-settings TOML sync (issue #1033).
+ *
+ * A single source of truth describing every app setting that round-trips
+ * through `app.toml`. It drives BOTH directions:
+ *  - pull  (`serializeAppSettingsToToml`): server settings -> `app.toml` object
+ *  - push  (`parseTomlToAppSettings`):     `app.toml` object -> settings payload
+ *
+ * Driving serializer and parser from one table means the two can never drift
+ * apart, and a single drift test can assert the descriptor stays in step with
+ * the server's `GET /settings` response and `PUT /settings` allow-list. This
+ * generalizes the earlier hand-maintained `AUTH_BOOLEAN_KEYS` /
+ * `RECOGNIZED_AUTH_KEYS` pattern to every section, and fully replaces it.
+ *
+ * Design decisions of record (issue #1033):
+ *  - `googleClientSecret` is a secret: never written to `app.toml` on pull, and
+ *    a hard error (abort before any PUT) if hand-added on push. Non-secret
+ *    `googleClientId` syncs normally.
+ *  - `[cors]` is always emitted (the `mode` key is `emit: "always"`), even in
+ *    universal mode. A one-time diff on the next pull for existing apps is
+ *    acceptable.
+ *  - `[invitations]` is an additive table for the member-invitation fields.
+ *  - Legacy `passkeyRpId` / `passkeyRpName` are still writable server-side but
+ *    excluded from TOML (superseded by `passkeyRpConfig` -> `[auth.passkeys]`).
+ *    The coverage test classifies them as deprecated-writable exclusions, NOT
+ *    computed/read-only.
+ *  - Push type mismatches are field-named validation errors — no silent
+ *    coercion of a mistyped TOML value.
+ */
+/**
+ * Every field that round-trips through `app.toml`. 26 entries — the server's
+ * `PUT /settings` allow-list minus the two deprecated legacy passkey fields.
+ * `googleClientSecret` is present but flagged `secret` (excluded from TOML).
+ */
+export const APP_SETTINGS_DESCRIPTOR = [
+    // ---- [app] --------------------------------------------------------------
+    { field: "name", section: "app", key: "name", type: "string", emit: "always" },
+    { field: "mode", section: "app", key: "mode", type: "string", emit: "always" },
+    { field: "baseUrl", section: "app", key: "baseUrl", type: "string", emit: "whenSet" },
+    { field: "waitlistEnabled", section: "app", key: "waitlistEnabled", type: "boolean", emit: "always" },
+    { field: "waitlistNotifyAdmins", section: "app", key: "waitlistNotifyAdmins", type: "boolean", emit: "always" },
+    { field: "allowedDomains", section: "app", key: "allowedDomains", type: "string[]", emit: "whenSet" },
+    { field: "testAccountBaseEmails", section: "app", key: "testAccountBaseEmails", type: "string[]", emit: "whenSet" },
+    // ---- [auth] -------------------------------------------------------------
+    { field: "googleOAuthEnabled", section: "auth", key: "googleOAuthEnabled", type: "boolean", emit: "whenSet" },
+    { field: "googleClientId", section: "auth", key: "googleClientId", type: "string", emit: "whenSet" },
+    // Secret — omitted on pull, hard error on push. See GOOGLE_CLIENT_SECRET_PUSH_ERROR.
+    { field: "googleClientSecret", section: "auth", key: "googleClientSecret", type: "string", emit: "whenSet", secret: true },
+    { field: "passkeyEnabled", section: "auth", key: "passkeyEnabled", type: "boolean", emit: "always" },
+    { field: "magicLinkEnabled", section: "auth", key: "magicLinkEnabled", type: "boolean", emit: "always" },
+    { field: "appleSignInEnabled", section: "auth", key: "appleSignInEnabled", type: "boolean", emit: "whenSet" },
+    { field: "otpEnabled", section: "auth", key: "otpEnabled", type: "boolean", emit: "whenSet" },
+    { field: "appleAudiences", section: "auth", key: "appleAudiences", type: "string[]", emit: "whenSet" },
+    { field: "redirectUris", section: "auth", key: "redirectUris", type: "string[]", emit: "whenSet" },
+    // passkeyRpConfig <-> [auth.passkeys] (nested object of rpId -> { name }).
+    { field: "passkeyRpConfig", section: "auth", key: "passkeys", type: "object", emit: "whenSet" },
+    // ---- [cors] -------------------------------------------------------------
+    // `mode` is `always` so the [cors] table is always emitted (decision 3).
+    { field: "corsMode", section: "cors", key: "mode", type: "string", emit: "always" },
+    { field: "corsAllowedOrigins", section: "cors", key: "allowedOrigins", type: "string[]", emit: "whenSet" },
+    { field: "corsAllowCredentials", section: "cors", key: "allowCredentials", type: "boolean", emit: "whenSet" },
+    { field: "corsAllowedMethods", section: "cors", key: "allowedMethods", type: "string[]", emit: "whenSet" },
+    { field: "corsAllowedHeaders", section: "cors", key: "allowedHeaders", type: "string[]", emit: "whenSet" },
+    { field: "corsExposedHeaders", section: "cors", key: "exposedHeaders", type: "string[]", emit: "whenSet" },
+    { field: "corsMaxAge", section: "cors", key: "maxAge", type: "number", emit: "whenSet" },
+    // ---- [invitations] ------------------------------------------------------
+    { field: "memberInvitationsEnabled", section: "invitations", key: "enabled", type: "boolean", emit: "always" },
+    { field: "memberInvitationLimit", section: "invitations", key: "limit", type: "number", emit: "always" },
+];
+/** Section render order for a stable, diff-friendly `app.toml`. */
+export const APP_SETTINGS_SECTIONS = [
+    "app",
+    "auth",
+    "cors",
+    "invitations",
+];
+/**
+ * `GET /settings` keys that are computed/read-only and never sync (no server
+ * setter). The external coverage drift test classifies these here.
+ */
+export const IGNORED_GET_KEYS = new Set([
+    "appId",
+    "hasGoogleAuth",
+    "hasAppleAuth",
+    "hasPasskey",
+    "createdAt",
+    "modifiedAt",
+]);
+/**
+ * Fields that ARE still writable server-side (present in the `PUT /settings`
+ * allow-list) but are deliberately excluded from TOML because a newer field
+ * supersedes them. Kept distinct from `IGNORED_GET_KEYS` so the coverage test's
+ * "every allow-listed field is covered" claim stays true — these are excluded,
+ * not read-only. (Codex design-review concern #1.)
+ */
+export const DEPRECATED_WRITABLE_EXCLUDED = new Set([
+    "passkeyRpId",
+    "passkeyRpName",
+]);
+/** Push error for a hand-added `googleClientSecret` — points at a real command. */
+export const GOOGLE_CLIENT_SECRET_PUSH_ERROR = 'app.toml must not contain a "googleClientSecret" key under [auth]. ' +
+    "Secrets are excluded from synced config by design. Remove the key, then set " +
+    "the secret with:\n  primitive apps update <appId> --google-client-secret <secret>";
+const DESCRIPTOR_BY_SECTION = (() => {
+    const m = new Map();
+    for (const d of APP_SETTINGS_DESCRIPTOR) {
+        const list = m.get(d.section) ?? [];
+        list.push(d);
+        m.set(d.section, list);
+    }
+    return m;
+})();
+/** Descriptor `field` names, for parity/coverage tests. */
+export const DESCRIPTOR_FIELDS = new Set(APP_SETTINGS_DESCRIPTOR.map((d) => d.field));
+function typeOfValue(value) {
+    if (value === null || value === undefined)
+        return "null";
+    if (typeof value === "boolean")
+        return "boolean";
+    if (typeof value === "number")
+        return "number";
+    if (typeof value === "string")
+        return "string";
+    if (Array.isArray(value))
+        return "string[]";
+    if (typeof value === "object")
+        return "object";
+    return "unknown";
+}
+/** True if a value should be omitted under `emit: "whenSet"`. */
+function isEmptyForEmit(value, type) {
+    if (value === null || value === undefined)
+        return true;
+    if (type === "string")
+        return value === "";
+    if (type === "string[]")
+        return !Array.isArray(value) || value.length === 0;
+    if (type === "object")
+        return (typeof value !== "object" ||
+            value === null ||
+            Object.keys(value).length === 0);
+    return false; // booleans (false) and numbers (0) are meaningful, never empty
+}
+/**
+ * Validate a push value against its descriptor type. Returns an error string
+ * (field-named) on mismatch, or `null` when the value is acceptable. Arrays are
+ * checked element-by-element so a `["a", 1]` mistype is caught.
+ */
+function typeError(descriptor, value) {
+    const actual = typeOfValue(value);
+    if (actual === "null")
+        return null; // null clears; server owns clear semantics
+    if (descriptor.type === "string[]") {
+        if (!Array.isArray(value) || !value.every((v) => typeof v === "string")) {
+            return `[${descriptor.section}].${descriptor.key} must be an array of strings (got ${actual})`;
+        }
+        return null;
+    }
+    if (descriptor.type === "object") {
+        if (actual !== "object") {
+            return `[${descriptor.section}].${descriptor.key} must be a table (got ${actual})`;
+        }
+        return null;
+    }
+    if (actual !== descriptor.type) {
+        return `[${descriptor.section}].${descriptor.key} must be a ${descriptor.type} (got ${actual})`;
+    }
+    return null;
+}
+/**
+ * Build one `app.toml` section object from server settings (pull direction).
+ * Secret fields are never written. Applies each field's `emit` rule; a `null`
+ * value is always omitted (TOML cannot encode null).
+ */
+export function serializeSection(settings, section) {
+    const out = {};
+    for (const d of DESCRIPTOR_BY_SECTION.get(section) ?? []) {
+        if (d.secret)
+            continue;
+        const value = settings[d.field];
+        if (value === null || value === undefined)
+            continue;
+        if (d.emit === "whenSet" && isEmptyForEmit(value, d.type))
+            continue;
+        out[d.key] = value;
+    }
+    return out;
+}
+/**
+ * Build the full `app.toml` data object (all sections) from server settings.
+ * Empty sections are omitted, though in practice every section has at least one
+ * `emit: "always"` key so all four are present.
+ */
+export function serializeAppSettingsToToml(settings) {
+    const data = {};
+    for (const section of APP_SETTINGS_SECTIONS) {
+        const obj = serializeSection(settings, section);
+        if (Object.keys(obj).length > 0)
+            data[section] = obj;
+    }
+    return data;
+}
+/**
+ * Translate a parsed `app.toml` object into a `PUT /settings` payload (push
+ * direction). Only keys present in the TOML are forwarded — an omitted key
+ * never overwrites server state. Unknown keys warn; type mismatches and any
+ * secret key are hard errors that the caller must treat as abort-before-PUT.
+ *
+ * `isCrossAppPush` strips `name` so a cross-app push never overwrites the
+ * target app's name.
+ */
+export function parseTomlToAppSettings(tomlData, options = {}) {
+    const settings = {};
+    const warnings = [];
+    const errors = [];
+    for (const section of APP_SETTINGS_SECTIONS) {
+        const sectionData = tomlData?.[section];
+        if (sectionData === undefined || sectionData === null)
+            continue;
+        if (typeof sectionData !== "object" || Array.isArray(sectionData)) {
+            errors.push(`[${section}] must be a table`);
+            continue;
+        }
+        const descriptors = DESCRIPTOR_BY_SECTION.get(section) ?? [];
+        const byKey = new Map(descriptors.map((d) => [d.key, d]));
+        for (const key of Object.keys(sectionData)) {
+            const d = byKey.get(key);
+            if (!d) {
+                warnings.push(`Unrecognized [${section}] key "${key}" in app.toml — ignored. ` +
+                    `Recognized keys: ${descriptors.map((x) => x.key).join(", ")}.`);
+                continue;
+            }
+            if (d.secret) {
+                errors.push(GOOGLE_CLIENT_SECRET_PUSH_ERROR);
+                continue;
+            }
+            if (options.isCrossAppPush && d.field === "name")
+                continue;
+            const value = sectionData[key];
+            const err = typeError(d, value);
+            if (err) {
+                errors.push(err);
+                continue;
+            }
+            settings[d.field] = value;
+        }
+    }
+    return { settings, warnings, errors };
+}
+//# sourceMappingURL=app-settings-descriptor.js.map

package/dist/src/lib/app-settings-descriptor.js.map

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

package/dist/src/lib/batch.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Shared helpers for the CLI's batch-import commands
+ * (`databases import` and `databases import-csv`).
+ */
+/** Split an array into fixed-size chunks. */
+export declare function chunk<T>(items: T[], size: number): T[][];
+export interface ParseBatchSizeOptions {
+    /** Largest batch size the caller will accept. */
+    max: number;
+    /** Message shown when the value exceeds `max`. */
+    overMaxMessage: string;
+}
+/**
+ * Parse and validate a `--batch-size` flag value.
+ *
+ * Returns the parsed integer on success, or a human-readable error message
+ * on failure (non-integer, `< 1`, or over the caller's ceiling). Callers
+ * decide how to surface the error — typically `error(msg); process.exit(1)`.
+ * Validating up front means a bad `--batch-size` fails before any write, so
+ * there are no partial imports.
+ */
+export declare function parseBatchSize(raw: string, opts: ParseBatchSizeOptions): {
+    value: number;
+} | {
+    error: string;
+};

package/dist/src/lib/batch.js

@@ -0,0 +1,32 @@
+/**
+ * Shared helpers for the CLI's batch-import commands
+ * (`databases import` and `databases import-csv`).
+ */
+/** Split an array into fixed-size chunks. */
+export function chunk(items, size) {
+    const out = [];
+    for (let i = 0; i < items.length; i += size) {
+        out.push(items.slice(i, i + size));
+    }
+    return out;
+}
+/**
+ * Parse and validate a `--batch-size` flag value.
+ *
+ * Returns the parsed integer on success, or a human-readable error message
+ * on failure (non-integer, `< 1`, or over the caller's ceiling). Callers
+ * decide how to surface the error — typically `error(msg); process.exit(1)`.
+ * Validating up front means a bad `--batch-size` fails before any write, so
+ * there are no partial imports.
+ */
+export function parseBatchSize(raw, opts) {
+    const n = Number(raw);
+    if (!Number.isInteger(n) || n < 1) {
+        return { error: "--batch-size must be a positive integer." };
+    }
+    if (n > opts.max) {
+        return { error: opts.overMaxMessage };
+    }
+    return { value: n };
+}
+//# sourceMappingURL=batch.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"batch.js","sourceRoot":"","sources":["../../../src/lib/batch.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,6CAA6C;AAC7C,MAAM,UAAU,KAAK,CAAI,KAAU,EAAE,IAAY;IAC/C,MAAM,GAAG,GAAU,EAAE,CAAC;IACtB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC;QAC5C,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC;IACrC,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AASD;;;;;;;;GAQG;AACH,MAAM,UAAU,cAAc,CAC5B,GAAW,EACX,IAA2B;IAE3B,MAAM,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;IACtB,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QAClC,OAAO,EAAE,KAAK,EAAE,0CAA0C,EAAE,CAAC;IAC/D,CAAC;IACD,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACjB,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC,cAAc,EAAE,CAAC;IACxC,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC;AACtB,CAAC"}

package/dist/src/lib/block-layout.d.ts

@@ -0,0 +1,160 @@
+/**
+ * Sync v2 "unified block" layout — issue #1183, Phase 3.
+ *
+ * The current (legacy) sync layout stores each managed block type in its own
+ * flat directory:
+ *
+ *   config/
+ *     prompts/<key>.toml
+ *     integrations/<key>.toml
+ *     workflows/<key>.toml
+ *     transforms/<name>.rhai            # scripts
+ *
+ * The v2 layout introduced by the unified block model groups every block type
+ * under one `blocks/` tree keyed by type and block key, with a single
+ * `block.toml` envelope per block (and a sibling `source.rhai` for scripts):
+ *
+ *   config/
+ *     blocks/
+ *       prompts/<key>/block.toml
+ *       integrations/<key>/block.toml
+ *       workflows/<key>/block.toml
+ *       scripts/<key>/block.toml
+ *       scripts/<key>/source.rhai
+ *
+ * Per the proposal (docs/proposals/unified-block-model.md, "Phase 3: Sync v2"),
+ * the CLI must:
+ *   - Read both legacy and v2 layouts.
+ *   - Preserve the legacy layout as the default until v2 is proven.
+ *   - Provide a migration command to convert legacy sync directories.
+ *
+ * This module is the pure, side-effect-light core of that work: the v2 path
+ * builders, the `block.toml` codec, layout detection, and the legacy -> v2
+ * migration. It stores the *verbatim* legacy TOML body under
+ * `[[versions]].spec`, so the transform is loss-free and a v2 block round-trips
+ * back to a byte-for-byte-equivalent legacy object (see `reconstructLegacyBlock`).
+ * That is what lets a later pass read a v2 directory through the same push path
+ * the legacy layout uses without re-deriving every type's field mapping.
+ */
+export type BlockType = "prompt" | "integration" | "workflow" | "script";
+export declare const BLOCK_TYPES: BlockType[];
+/** The `schemaVersion` string written at the top of every v2 `block.toml`. */
+export declare const BLOCK_SCHEMA_VERSION = "block/v1";
+/** The filename of the script body written next to a v2 script `block.toml`. */
+export declare const SCRIPT_SOURCE_FILENAME = "source.rhai";
+export declare function isBlockType(value: unknown): value is BlockType;
+/** `<configDir>/blocks` — the root of the v2 tree. */
+export declare function v2BlocksRoot(configDir: string): string;
+/** `<configDir>/blocks/<typeDir>/<key>` — a single v2 block's directory. */
+export declare function v2BlockDir(configDir: string, type: BlockType, key: string): string;
+/** `<configDir>/blocks/<typeDir>/<key>/block.toml`. */
+export declare function v2BlockTomlPath(configDir: string, type: BlockType, key: string): string;
+/** `<configDir>/blocks/scripts/<key>/source.rhai`. */
+export declare function v2ScriptSourcePath(configDir: string, key: string): string;
+/** `<configDir>/<legacyDir>` for a block type (flat layout). */
+export declare function legacyBlockDir(configDir: string, type: BlockType): string;
+export interface BlockVersionToml {
+    key: string;
+    status?: string;
+    contentHash?: string;
+    /** Verbatim type-native spec body (the legacy TOML object for this block). */
+    spec: Record<string, unknown>;
+}
+export interface BlockHeaderToml {
+    type: BlockType;
+    key: string;
+    displayName?: string;
+    description?: string;
+    status?: string;
+    activeVersion?: string;
+}
+export interface BlockToml {
+    schemaVersion: string;
+    block: BlockHeaderToml;
+    versions: BlockVersionToml[];
+}
+/**
+ * Serialize a v2 block into `block.toml` text. Key order is fixed
+ * (`schemaVersion`, `[block]`, `[[versions]]`) so a pull/migrate followed by a
+ * re-serialize is stable and produces no spurious diffs.
+ */
+export declare function serializeBlockToml(block: BlockToml): string;
+/**
+ * Parse `block.toml` text into a `BlockToml`. Throws with a clear message when
+ * the envelope is malformed (missing/invalid `[block].type`, no versions).
+ */
+export declare function parseBlockToml(text: string): BlockToml;
+/** `sha256:<hex>` content identity over the canonical JSON of a spec object. */
+export declare function specContentHash(spec: unknown): string;
+/**
+ * Wrap a parsed legacy block object into a v2 `BlockToml`. The full legacy
+ * object is stored verbatim as the single version's `spec`, so the transform
+ * loses nothing. The `[block]` header is a projection derived from the legacy
+ * header table for the unified vocabulary; the spec remains the source of truth
+ * for reconstructing the legacy file.
+ */
+export declare function legacyObjectToBlock(type: Exclude<BlockType, "script">, legacy: Record<string, unknown>, fallbackKey: string): BlockToml;
+/** Wrap a raw Rhai script body into a v2 script `BlockToml`. */
+export declare function scriptSourceToBlock(key: string, source: string): BlockToml;
+export interface ReconstructedLegacy {
+    /** For prompt/integration/workflow: the legacy `.toml` text. */
+    toml?: string;
+    /** For scripts: the raw `.rhai` body. */
+    rhai?: string;
+}
+/**
+ * Reverse `legacyObjectToBlock` / `scriptSourceToBlock`: rebuild the legacy
+ * on-disk content from a v2 block. This is the read half of dual-layout
+ * support — a v2 directory can be projected back to the exact legacy object a
+ * legacy consumer (e.g. the push path) expects. `sourceText` is required for
+ * scripts (the body lives in `source.rhai`, not the `block.toml`).
+ */
+export declare function reconstructLegacyBlock(block: BlockToml, sourceText?: string): ReconstructedLegacy;
+/**
+ * Report which layouts a config directory currently holds. A directory can
+ * hold both during/after a migration (legacy preserved, v2 written).
+ */
+export declare function detectLayout(configDir: string): {
+    legacy: boolean;
+    v2: boolean;
+};
+export interface V2BlockRef {
+    type: BlockType;
+    key: string;
+    tomlPath: string;
+    sourcePath?: string;
+}
+/** Enumerate every v2 block present under `<configDir>/blocks/`. */
+export declare function listV2Blocks(configDir: string): V2BlockRef[];
+export interface MigratedBlock {
+    type: BlockType;
+    key: string;
+    tomlPath: string;
+    sourcePath?: string;
+    /** Number of test-case files copied into the v2 block's `tests/` dir. */
+    testsCopied: number;
+}
+export interface SkippedBlock {
+    type: BlockType;
+    key: string;
+    reason: string;
+}
+export interface MigrationResult {
+    blocks: MigratedBlock[];
+    skipped: SkippedBlock[];
+    dryRun: boolean;
+}
+export interface MigrateOptions {
+    /** Report what would happen without writing anything. */
+    dryRun?: boolean;
+    /** Overwrite an existing v2 `block.toml` instead of skipping it. */
+    force?: boolean;
+}
+/**
+ * Convert a legacy sync directory into the v2 `blocks/<type>/<key>/block.toml`
+ * layout. Non-destructive: the legacy files are left in place (the legacy
+ * layout stays the default until v2 is proven). Test-case directories
+ * (`<key>.tests/`) are copied verbatim into `blocks/<type>/<key>/tests/` so a
+ * tested block migrates without losing its cases.
+ */
+export declare function migrateLegacyToV2(configDir: string, options?: MigrateOptions): MigrationResult;