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

package/dist/src/lib/codegen-shared/resolveCodegenSourceDir.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Shared source-directory resolution for the CLI codegen commands
+ * (`workflows codegen` #1442 and `databases codegen` #814, issue #1510).
+ *
+ * Both commands read a set of `*.toml` schemas out of a synced sub-directory
+ * (`workflows/` or `database-type-configs/`) and render `*.generated.ts` beside them.
+ * Historically each command located that source directory by scanning EVERY
+ * `.primitive/sync/<env>/<appId>/<subdir>` slot and either hard-erroring on
+ * more than one (`workflows`) or silently merging across environments
+ * (`databases`, via a `seenTypes` dedup). Neither did any environment
+ * resolution, so `PRIMITIVE_ENV=dev workflows codegen` would happily generate
+ * from the `alpha` TOML while `databases codegen` followed a different env —
+ * the two generated-type trees could come from different environments in one
+ * run.
+ *
+ * This helper resolves the source directory the same way every other CLI
+ * command targets an environment: `--env` → `PRIMITIVE_ENV` →
+ * `defaultEnvironment` → single-env → error. `--dir` and `--app` remain
+ * explicit overrides. It returns ONLY the resolved source directory; TOML
+ * collection, type filtering/dedup, and output-dir defaulting stay in each
+ * command.
+ *
+ * Design notes (binding, from the plan of record for #1510):
+ *   - Call `getCurrentEnvironment()` DIRECTLY when no `--dir` override is given.
+ *     `resolveSyncDir()`'s internal `safeEnv()` swallows the resolver's
+ *     ambiguity error and falls back to `./config`, so genuine ambiguity must
+ *     be surfaced here, not through `resolveSyncDir()`.
+ *   - Throw plain `Error`s; the calling commands keep their existing
+ *     `error(); process.exit(1)` convention (they catch at the boundary).
+ *   - Do NOT use `resolveAppId()` — it is auth-oriented and exits the process,
+ *     which is wrong for an offline codegen path.
+ *   - Preserve the `--app`-alone legacy fallback: when `--app` is given, NO
+ *     environment was explicitly requested, and env resolution fails (or there
+ *     is no project config / legacy bare-dir mode), scan
+ *     `.primitive/sync/<env>/<app>/<subdir>` for that specific app, resolving
+ *     when it appears under exactly one env and erroring (naming the candidate
+ *     envs) when it appears under more than one. This keeps the existing
+ *     integration contract
+ *     (`cli/tests/integration/workflows-codegen.test.ts`) intact.
+ *   - Do NOT fall through to that scan when an environment WAS explicitly named
+ *     (`--env` or `PRIMITIVE_ENV`) but is invalid/unknown: surface the
+ *     resolver's error instead, so an explicit env selection never silently
+ *     generates code from a different synced environment.
+ */
+export interface ResolveCodegenSourceDirOptions {
+    /** `--app <app-id>` override, if the user passed it. */
+    app?: string;
+    /** The resolved sync-directory override (`--dir <path>`), if the user passed it. */
+    syncDir?: string;
+}
+export interface ResolveCodegenSourceDirArgs {
+    /** The synced sub-directory to resolve, e.g. "workflows" or "database-type-configs". */
+    subdir: string;
+    /** Parsed command options (`--app`, plus the resolved `--dir` override). */
+    options: ResolveCodegenSourceDirOptions;
+    /**
+     * Working directory the legacy scan is rooted at. Defaults to
+     * `process.cwd()`; parameterised so unit tests can point it at a tmp tree
+     * (vitest workers can't `chdir`).
+     */
+    cwd?: string;
+}
+/**
+ * Resolves the single source directory a codegen command should read its
+ * `*.toml` schemas from. Throws a plain `Error` (with a user-facing message)
+ * when the directory can't be resolved unambiguously or doesn't exist.
+ */
+export declare function resolveCodegenSourceDir(args: ResolveCodegenSourceDirArgs): string;

package/dist/src/lib/codegen-shared/resolveCodegenSourceDir.js

@@ -0,0 +1,168 @@
+/**
+ * Shared source-directory resolution for the CLI codegen commands
+ * (`workflows codegen` #1442 and `databases codegen` #814, issue #1510).
+ *
+ * Both commands read a set of `*.toml` schemas out of a synced sub-directory
+ * (`workflows/` or `database-type-configs/`) and render `*.generated.ts` beside them.
+ * Historically each command located that source directory by scanning EVERY
+ * `.primitive/sync/<env>/<appId>/<subdir>` slot and either hard-erroring on
+ * more than one (`workflows`) or silently merging across environments
+ * (`databases`, via a `seenTypes` dedup). Neither did any environment
+ * resolution, so `PRIMITIVE_ENV=dev workflows codegen` would happily generate
+ * from the `alpha` TOML while `databases codegen` followed a different env —
+ * the two generated-type trees could come from different environments in one
+ * run.
+ *
+ * This helper resolves the source directory the same way every other CLI
+ * command targets an environment: `--env` → `PRIMITIVE_ENV` →
+ * `defaultEnvironment` → single-env → error. `--dir` and `--app` remain
+ * explicit overrides. It returns ONLY the resolved source directory; TOML
+ * collection, type filtering/dedup, and output-dir defaulting stay in each
+ * command.
+ *
+ * Design notes (binding, from the plan of record for #1510):
+ *   - Call `getCurrentEnvironment()` DIRECTLY when no `--dir` override is given.
+ *     `resolveSyncDir()`'s internal `safeEnv()` swallows the resolver's
+ *     ambiguity error and falls back to `./config`, so genuine ambiguity must
+ *     be surfaced here, not through `resolveSyncDir()`.
+ *   - Throw plain `Error`s; the calling commands keep their existing
+ *     `error(); process.exit(1)` convention (they catch at the boundary).
+ *   - Do NOT use `resolveAppId()` — it is auth-oriented and exits the process,
+ *     which is wrong for an offline codegen path.
+ *   - Preserve the `--app`-alone legacy fallback: when `--app` is given, NO
+ *     environment was explicitly requested, and env resolution fails (or there
+ *     is no project config / legacy bare-dir mode), scan
+ *     `.primitive/sync/<env>/<app>/<subdir>` for that specific app, resolving
+ *     when it appears under exactly one env and erroring (naming the candidate
+ *     envs) when it appears under more than one. This keeps the existing
+ *     integration contract
+ *     (`cli/tests/integration/workflows-codegen.test.ts`) intact.
+ *   - Do NOT fall through to that scan when an environment WAS explicitly named
+ *     (`--env` or `PRIMITIVE_ENV`) but is invalid/unknown: surface the
+ *     resolver's error instead, so an explicit env selection never silently
+ *     generates code from a different synced environment.
+ */
+import { existsSync, readdirSync } from "fs";
+import { basename, dirname, join } from "path";
+import { getCurrentEnvironment, getExplicitEnvName } from "../env-resolver.js";
+import { getCurrentAppId } from "../config.js";
+import { resolveSyncDir, assertSafePathComponent } from "../sync-paths.js";
+/**
+ * Resolves the single source directory a codegen command should read its
+ * `*.toml` schemas from. Throws a plain `Error` (with a user-facing message)
+ * when the directory can't be resolved unambiguously or doesn't exist.
+ */
+export function resolveCodegenSourceDir(args) {
+    const { subdir, options } = args;
+    const cwd = args.cwd ?? process.cwd();
+    // 1. --dir is an explicit override: use <dir>/<subdir> verbatim.
+    if (options.syncDir) {
+        return requireExisting(join(options.syncDir, subdir), subdir, undefined);
+    }
+    // 2. Resolve the active environment. Call getCurrentEnvironment() directly
+    //    (not via resolveSyncDir/safeEnv) so a genuinely ambiguous project
+    //    surfaces the resolver's "No environment selected… Available: …" error
+    //    with a non-zero exit — unless the caller narrowed the target with
+    //    --app AND did not name an environment, in which case we fall back to the
+    //    legacy per-app scan.
+    //
+    //    The `--app`-alone fallback only applies when NO environment was
+    //    explicitly requested (neither `--env` nor `PRIMITIVE_ENV`). When the
+    //    user DID name an env but it's invalid/unknown, getCurrentEnvironment()
+    //    throws; we must surface that error (non-zero exit) rather than silently
+    //    scanning the app under some OTHER synced environment — that would
+    //    generate code from the wrong env instead of honoring the explicit
+    //    selection.
+    const explicitEnvRequested = getExplicitEnvName() !== null || !!process.env.PRIMITIVE_ENV;
+    let env;
+    try {
+        env = getCurrentEnvironment();
+    }
+    catch (err) {
+        if (options.app && !explicitEnvRequested) {
+            return scanSyncTree({ subdir, appId: options.app, cwd });
+        }
+        throw err;
+    }
+    // 3. Project mode: resolve the app id and build the env/app-scoped path.
+    if (env) {
+        const appId = options.app ?? env.config.appId ?? getCurrentAppId();
+        if (!appId) {
+            throw new Error(`No app configured for environment "${env.name}" in .primitive/config.json ` +
+                `and no --app given. Add "appId" to the environment or pass --app <app-id>.`);
+        }
+        // resolveSyncDir re-reads the (cached) resolved env and guards appId via
+        // assertSafePathComponent, so an unsafe --app is rejected here.
+        const dir = join(resolveSyncDir({ appId }), subdir);
+        return requireExisting(dir, subdir, appId);
+    }
+    // 4. Legacy / bare-dir mode (no .primitive/config.json): scan the sync tree,
+    //    filtered to --app when given. This preserves the pre-#1510 behavior.
+    return scanSyncTree({ subdir, appId: options.app, cwd });
+}
+/**
+ * Legacy fallback: scan `<cwd>/.primitive/sync/<env>/<app>/<subdir>` for a
+ * source directory. When `appId` is given, only that app's slots are
+ * considered. Resolves to the single match; errors clearly on zero or on
+ * ambiguity (naming the candidate apps or envs).
+ */
+function scanSyncTree(args) {
+    const { subdir, appId, cwd } = args;
+    // Defence-in-depth: an --app value flows into a file-system path below, so
+    // reject separators / `..` before using it.
+    if (appId)
+        assertSafePathComponent(appId, "appId");
+    const root = join(cwd, ".primitive", "sync");
+    const found = [];
+    if (existsSync(root)) {
+        for (const envName of readdirSync(root)) {
+            const envDir = join(root, envName);
+            try {
+                for (const app of readdirSync(envDir)) {
+                    if (appId && app !== appId)
+                        continue;
+                    const candidate = join(envDir, app, subdir);
+                    if (existsSync(candidate))
+                        found.push(candidate);
+                }
+            }
+            catch {
+                // Not a directory (or unreadable) — skip.
+            }
+        }
+    }
+    if (found.length === 0) {
+        throw new Error(notFoundMessage(subdir, appId));
+    }
+    if (found.length > 1) {
+        if (appId) {
+            const envs = [
+                ...new Set(found.map((d) => basename(dirname(dirname(d))))),
+            ];
+            throw new Error(`App "${appId}" has a ${subdir}/ directory under multiple environments: ` +
+                `${envs.join(", ")}.\n` +
+                found.map((d) => `  ${d}`).join("\n") +
+                `\nPass --env <name> or --dir to select one.`);
+        }
+        const apps = [...new Set(found.map((d) => basename(dirname(d))))];
+        throw new Error(`Found ${subdir}/ directories for more than one app/env:\n` +
+            found.map((d) => `  ${d}`).join("\n") +
+            `\nCodegen writes into one output dir, so it must run against one app. ` +
+            `Pass --app <app-id> (found: ${apps.join(", ")}) or --dir to select one.`);
+    }
+    return found[0];
+}
+/** Verifies `dir` exists, throwing the standard "no source dir" error otherwise. */
+function requireExisting(dir, subdir, appId) {
+    if (!existsSync(dir)) {
+        throw new Error(notFoundMessage(subdir, appId));
+    }
+    return dir;
+}
+function notFoundMessage(subdir, appId) {
+    return appId
+        ? `No ${subdir}/ directory found for app "${appId}" under .primitive/sync/. ` +
+            `Check the --app id, pass --dir, or run \`primitive config pull\` first.`
+        : `No ${subdir}/ directory found. Pass --dir or run \`primitive config pull\` first.`;
+}
+//# sourceMappingURL=resolveCodegenSourceDir.js.map

package/dist/src/lib/codegen-shared/resolveCodegenSourceDir.js.map

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

package/dist/src/lib/config-object-descriptor.d.ts

@@ -0,0 +1,127 @@
+/**
+ * The configuration-object descriptor registry (issue #2645).
+ *
+ * Server-side configuration is authored in TOML and applied with `config push`.
+ * That makes the TOML field surface the thing an operator has to discover, so
+ * it needs a machine-readable definition — the job per-flag `--help` used to do.
+ * This registry is that definition, and it drives four commands:
+ *
+ *   - `config fields <type>`      lists a type's keys, types, required, default
+ *   - `config create <type> <key>`   scaffolds the type's file from `scaffold()`
+ *   - `config set <type>/<key>`   validates the dotted path being edited
+ *   - `config push --only <sel>`  resolves a selector to a type + key
+ *
+ * ── Deliberately a descriptor, never reflection ──────────────────────────
+ * The field list is declared here, not inferred from the pull serializers in
+ * `commands/sync.ts`. Reflection over emitted keys cannot report `required` or
+ * `default`, and an implicit field surface is exactly the drift #2644 exists to
+ * end. The workflow key set is CONSUMED from #2644's vendored definition
+ * (`config-surface.ts` / `generated-config-surfaces.ts`) and the app settings
+ * from `app-settings-descriptor.ts`, rather than restated, so there is still
+ * one definition per field.
+ *
+ * ── Drift guard ──────────────────────────────────────────────────────────
+ * `cli/tests/unit/config-object-descriptor.test.ts` cross-checks the registry
+ * against `SYNC_RESOURCE_TYPES` (every per-entity type has exactly one
+ * descriptor) and `PUSH_PRUNE_SPECS` (the declared identity path is a real
+ * field), and asserts each scaffold parses and carries every required field. A
+ * new sync resource type therefore fails a test rather than silently
+ * under-reporting from `config fields`.
+ *
+ * ── Relationship to #2644 ────────────────────────────────────────────────
+ * #2644 defines one shared field definition across the server, the TOML surface
+ * and CLI validation. These descriptors are sized to be ABSORBED by it: they
+ * carry only what the four commands above need, and no validation behavior.
+ */
+import { type SyncResourceType } from "./sync-resource-types.js";
+/** Value shape of a TOML key, as reported by `config fields`. */
+export type ConfigFieldType = "string" | "number" | "boolean" | "string[]" | "table" | "table[]" | "json";
+export interface ConfigFieldDescriptor {
+    /** Dotted TOML path, e.g. `workflow.status`, `verification.jwt`. */
+    path: string;
+    type: ConfigFieldType;
+    /** True when `config push` cannot apply the file without this key. */
+    required: boolean;
+    /**
+     * The value the server assumes when the key is absent. `undefined` means
+     * there is no default — an absent key leaves the field unset (or, for the
+     * TOML-owned fields, clears it).
+     */
+    default?: string | number | boolean;
+    /** One line, shown by `config fields`. */
+    description: string;
+}
+/**
+ * A second file the same object is authored across (issue #2645).
+ *
+ * A workflow's named configs are sidecar files (`workflows/<key>.configs/
+ * <name>.toml`, spec §Contracts/Named configs), authored by the same person as
+ * the workflow and pushed by the same command — but they are not keys of
+ * `workflows/<key>.toml`, so they cannot be fields of the descriptor without
+ * telling `config set` to write them into the wrong file. They are listed
+ * separately instead: `config fields` has to report the whole surface, because
+ * it is what replaced per-flag `--help` for the removed `workflows configs`
+ * verbs (criterion 7).
+ */
+export interface ConfigObjectCompanionFile {
+    /** Where the companion lives, e.g. `workflows/<key>.configs/<name>.toml`. */
+    fileHint: string;
+    /** One line saying what the file is and what names it. */
+    description: string;
+    fields: readonly ConfigFieldDescriptor[];
+}
+export interface ConfigObjectDescriptor {
+    /** Selector name: `workflow`, `webhook`, `app`, `var`. */
+    type: string;
+    /**
+     * Layout metadata for the 13 per-entity types. Absent for the two root
+     * singletons (`app.toml`, `vars.toml`), which `SYNC_RESOURCE_TYPES`
+     * deliberately excludes.
+     */
+    resourceType?: SyncResourceType;
+    /** Where the object is authored, for help text and error messages. */
+    fileHint: string;
+    /**
+     * Dotted path of the key that names the object, when it has one in-file.
+     * Types keyed purely by filename (transforms, rule-sets) declare none.
+     */
+    identity?: string;
+    /** One line describing what the object configures. */
+    description: string;
+    fields: readonly ConfigFieldDescriptor[];
+    /** Further files the object is authored across, listed but not `config set`-able. */
+    companionFiles?: readonly ConfigObjectCompanionFile[];
+    /**
+     * True when the file's root-level keys are the author's own rather than a
+     * fixed surface — `vars.toml` is a flat `KEY = "value"` table. There is no
+     * field list to declare, so `config set` accepts any single-segment path.
+     */
+    freeFormRootKeys?: boolean;
+    /** The file body `config create <type> <key>` writes. */
+    scaffold(key: string): string;
+}
+/** The identity path a descriptor declares, or `undefined` when keyed by filename. */
+export declare function describedIdentityPath(descriptor: ConfigObjectDescriptor): string | undefined;
+/**
+ * What the server assumes when a `[workflow]` key is absent.
+ *
+ * The vendored `WORKFLOW_TABLE` (#2644) carries key set and value shape but
+ * not defaults, so the defaults are stated here, next to the other types'.
+ * They are not free text: the `models.yaml` `WorkflowDefinition` defaults are
+ * the source of truth, and
+ * `cli/tests/unit/config-object-descriptor.test.ts` parses that model and fails
+ * when a default here disagrees or a newly-defaulted field is missing. Without
+ * them `config fields workflow` reported `default null` for the queueing and
+ * dispatch knobs — the command that replaced per-flag `--help` under-reporting
+ * exactly what the removed flags used to document (issue #2645).
+ *
+ * Exported because `config diff`'s workflow comparator needs exactly this table
+ * to normalize omitted-vs-defaulted fields, and kept a hand-mirrored second
+ * copy of it until #2731. Two tables can disagree; a guarded one cannot go
+ * stale unnoticed.
+ */
+export declare const WORKFLOW_FIELD_DEFAULTS: Record<string, string | number | boolean>;
+export declare const CONFIG_OBJECT_DESCRIPTORS: readonly ConfigObjectDescriptor[];
+/** Every selector type name, in registry order. */
+export declare const CONFIG_OBJECT_TYPES: readonly string[];
+export declare function getConfigObjectDescriptor(type: string): ConfigObjectDescriptor | undefined;