primitive-admin 1.1.0-alpha.6 → 1.1.0-alpha.60

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

@@ -0,0 +1,262 @@
+/**
+ * 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 an ordinary `[auth]` key (#2256). It holds a whole
+ *    `{{secrets.KEY}}` reference rather than the secret itself, so it round-trips
+ *    through `app.toml` like any other string setting. It used to be excluded
+ *    from TOML entirely, back when the stored value WAS the credential.
+ *  - `[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.
+ */
+import { findUnknownDocumentKeys, requireConfigSurface, } from "./config-surface.js";
+/**
+ * The vendored `app-settings` definition (#2644) this module projects. Read
+ * once at load; a missing definition fails loudly rather than yielding an
+ * empty descriptor that would silently sync nothing.
+ */
+const APP_SETTINGS_SURFACE = requireConfigSurface("app-settings");
+/**
+ * Every field that round-trips through `app.toml` — DERIVED from the
+ * `app-settings` configuration-object definition (#2644), not listed.
+ *
+ * The definition already states each field's section (its table's TOML path),
+ * its `app.toml` key, its type and its `emit` rule, and the coverage guard
+ * holds it against the `App` model. Restating those 26 entries here made
+ * adding a setting two edits that a parity test then compared — the "two lists
+ * and a test they agree" shape the design gate rejected (2026-08-12). One edit
+ * in the definition now reaches the server allow-list
+ * (`settings-fields.ts`), this descriptor, and both directions of the sync.
+ *
+ * `json` in the definition is this module's `object` — the same shape under the
+ * name each side has always used for it.
+ */
+export const APP_SETTINGS_DESCRIPTOR = APP_SETTINGS_SURFACE.tables.flatMap((table) => table.fields.map((field) => ({
+    field: field.field,
+    section: table.tomlPath[0],
+    key: field.tomlKey,
+    type: (field.type === "json" ? "object" : field.type),
+    emit: field.emit,
+})));
+/**
+ * Section render order for a stable, diff-friendly `app.toml` — the
+ * definition's table order (#2644), so a new section is rendered by being
+ * declared there.
+ */
+export const APP_SETTINGS_SECTIONS = APP_SETTINGS_SURFACE.tables.map((table) => table.tomlPath[0]);
+/**
+ * `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",
+    // Deprecated presence flag for `googleClientSecret`, kept always-present on
+    // GET for one release (#2256 / #2193 decision of record). It is derived from
+    // `googleClientSecret` and has no server setter, so it never syncs — same
+    // classification as `hasGoogleAuth`. Remove this entry when the alias goes.
+    "googleClientSecretSet",
+    // How the server reads the stored `googleClientSecret` — `unset`,
+    // `reference`, `legacy-literal` for a row written before reference-only
+    // (#2256), or `malformed-reference` for a stored value carrying reference
+    // syntax that resolves to nothing (#2332). Derived and read-only: it exists
+    // so an operator can be told to remediate a value the server refuses to send
+    // back.
+    "googleClientSecretStatus",
+    "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(
+// Derived (#2644): `deprecated` is exactly "still writable, superseded by
+// another field", which is what this set has always meant.
+APP_SETTINGS_SURFACE.tables.flatMap((table) => Object.entries(table.notExposed)
+    .filter(([, classification]) => classification.kind === "deprecated")
+    .map(([field]) => field)));
+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).
+ * 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) ?? []) {
+        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. An unrecognized key or table and a type
+ * mismatch are both hard errors the caller must treat as abort-before-PUT
+ * (#2644 criterion 6: push rejects what it does not recognize, for every
+ * configuration surface, so a typo fails locally instead of being ignored).
+ *
+ * A `googleClientSecret` that is not a whole `{{secrets.KEY}}` reference is the
+ * server's rejection to make (#2256): the push forwards it and the `PUT` answers
+ * 400 with `GOOGLE_CLIENT_SECRET_MUST_BE_SECRET_REF`. Duplicating the shape rule
+ * here would put two definitions of "valid reference" in play.
+ *
+ * `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 = [];
+    // #2644 criterion 6 — a top-level table the definition does not declare is a
+    // hard error, the same posture every per-entity file has. Silently ignoring
+    // it made a typo'd header (`[curs]`) push as though the section it meant were
+    // absent, so the settings it carried were never applied.
+    for (const key of findUnknownDocumentKeys(tomlData, APP_SETTINGS_SURFACE)) {
+        errors.push(`app.toml: unrecognized top-level table [${key}]. Check the spelling ` +
+            `against the tables app.toml accepts (${APP_SETTINGS_SECTIONS.map((s) => `[${s}]`).join(", ")}), or upgrade the CLI if the server is newer than this one.`);
+    }
+    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) {
+                // #2644 criterion 6 — REJECTED, not warned-and-ignored. `app.toml` is a
+                // registered configuration surface like every other file, and an
+                // ignored key is a setting the author believes they changed.
+                errors.push(`app.toml: unrecognized key [${section}].${key}. Remove it or ` +
+                    `upgrade the CLI if the server is newer than this one. ` +
+                    `Recognized keys: ${descriptors.map((x) => x.key).join(", ")}.`);
+                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/auth-flow.d.ts

@@ -0,0 +1,8 @@
+import type { Credentials } from "../types/index.js";
+interface AuthResult {
+    success: boolean;
+    credentials?: Credentials;
+    error?: string;
+}
+export declare function browserLogin(serverUrl: string): Promise<AuthResult>;
+export {};

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;