@cosmicdrift/kumiko-framework 0.6.0 → 0.8.0

package/src/env/__tests__/dry-run.test.ts

@@ -0,0 +1,121 @@
+import { describe, expect, it } from "vitest";
+import { z } from "zod";
+import { defineFeature } from "../../engine/define-feature";
+import { renderDryRun } from "../dry-run";
+import { composeEnvSchema } from "../index";
+
+function buildComposed() {
+  const secretsFeature = defineFeature("secrets", (r) => {
+    r.envSchema(
+      z.object({
+        KUMIKO_SECRETS_MASTER_KEY_V1: z
+          .string()
+          .describe("AES-256 master-key for tenant-secrets")
+          .meta({
+            kumiko: {
+              pulumi: {
+                name: "secretsMasterKey",
+                generator: "openssl rand -base64 32",
+                secret: true,
+              },
+            },
+          }),
+        KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION: z
+          .string()
+          .regex(/^\d+$/)
+          .default("1")
+          .describe("Active KEK version"),
+      }),
+    );
+  });
+  const authFeature = defineFeature("auth-email-password", (r) => {
+    r.envSchema(
+      z.object({
+        JWT_SECRET: z
+          .string()
+          .min(32)
+          .describe("Session JWT signing key (≥32 chars)")
+          .meta({
+            kumiko: { pulumi: { generator: "openssl rand -base64 48", secret: true } },
+          }),
+      }),
+    );
+  });
+  const smtpFeature = defineFeature("channel-email-smtp", (r) => {
+    r.envSchema(
+      z.object({
+        SMTP_HOST: z.string().optional().describe("Outbound SMTP host"),
+      }),
+    );
+  });
+  return composeEnvSchema({
+    features: [secretsFeature, authFeature, smtpFeature],
+    extend: z.object({
+      STUDIO_ADMIN_EMAIL: z.email().describe("Bootstrap admin user"),
+    }),
+  });
+}
+
+describe("renderDryRun", () => {
+  it("human mode groups by required / optional / defaulted with feature attribution", () => {
+    const composed = buildComposed();
+    const out = renderDryRun(composed, "human");
+    expect(out).toContain("Required env-vars:");
+    expect(out).toContain("Optional env-vars:");
+    expect(out).toContain("Defaulted env-vars:");
+    expect(out).toContain("JWT_SECRET");
+    expect(out).toContain("(auth-email-password)");
+    expect(out).toContain("Session JWT signing key");
+    expect(out).toContain("STUDIO_ADMIN_EMAIL");
+    expect(out).toContain("(app)");
+    expect(out).toContain("(channel-email-smtp)");
+    expect(out).toContain('[default: "1"]');
+  });
+
+  it("json mode emits structured data with pulumiName per entry", () => {
+    const composed = buildComposed();
+    const out = renderDryRun(composed, "json", { pulumiPrefix: "studio" });
+    const parsed = JSON.parse(out) as {
+      required: { name: string; feature: string; pulumiName: string; description?: string }[];
+      optional: { name: string }[];
+      withDefault: { name: string; default: unknown }[];
+    };
+    const jwt = parsed.required.find((r) => r.name === "JWT_SECRET");
+    expect(jwt?.feature).toBe("auth-email-password");
+    expect(jwt?.pulumiName).toBe("studioJwtSecret");
+    expect(jwt?.description).toContain("Session JWT");
+    const smtp = parsed.optional.find((r) => r.name === "SMTP_HOST");
+    expect(smtp).toBeDefined();
+    const ver = parsed.withDefault.find((r) => r.name.endsWith("CURRENT_VERSION"));
+    expect(ver?.default).toBe("1");
+  });
+
+  it("pulumi mode emits `pulumi config set` lines, omitting optional+defaulted", () => {
+    const composed = buildComposed();
+    const out = renderDryRun(composed, "pulumi", { pulumiPrefix: "studio" });
+    expect(out).toContain(
+      'pulumi config set --secret studioJwtSecret "$(openssl rand -base64 48)"',
+    );
+    expect(out).toContain(
+      'pulumi config set --secret studioSecretsMasterKey "$(openssl rand -base64 32)"',
+    );
+    expect(out).toContain('pulumi config set studioStudioAdminEmail "<set-me>"');
+    // Optional + default skipped:
+    expect(out).not.toContain("SMTP_HOST");
+    expect(out).not.toContain("CURRENT_VERSION");
+  });
+
+  it("k8s mode emits a Secret manifest", () => {
+    const composed = buildComposed();
+    const out = renderDryRun(composed, "k8s", {
+      k8sName: "studio-env",
+      k8sNamespace: "studio",
+    });
+    expect(out).toContain("apiVersion: v1");
+    expect(out).toContain("kind: Secret");
+    expect(out).toContain("name: studio-env");
+    expect(out).toContain("namespace: studio");
+    expect(out).toContain('JWT_SECRET: "<set-me>"');
+    expect(out).toContain('KUMIKO_SECRETS_MASTER_KEY_V1: "<set-me>"');
+  });
+});

package/src/env/_zod-introspect.ts

@@ -0,0 +1,51 @@
+// Zod v4 runtime-introspection helpers. Each cast is a deliberate
+// schema-walk into Zod's internal shape (`_def`, `.meta()`, `.shape[k]`).
+// Centralised here so the as-cast audit's @cast-boundary schema-walk
+// markers live in one place rather than scattered through callers.
+//
+// All helpers accept the *runtime* Zod instance — TypeScript wrapper
+// (`z.ZodType`) and core (`$ZodType`) are the same object at runtime.
+
+import type { z } from "zod";
+
+export type ZodDef = {
+  readonly innerType?: z.ZodType;
+  readonly in?: z.ZodType;
+  readonly defaultValue?: unknown;
+};
+
+/** Read Zod v4 `.meta()` value. Undefined when no meta is set. */
+export function zodMeta(field: z.ZodType): unknown {
+  // @cast-boundary schema-walk
+  const fn = (field as { meta?: () => unknown }).meta;
+  return typeof fn === "function" ? fn.call(field) : undefined;
+}
+
+/** Read the `_def` slot used by ZodDefault/ZodOptional drilling. */
+export function zodDef(field: z.ZodType): ZodDef | undefined {
+  // @cast-boundary schema-walk
+  return (field as { _def?: ZodDef })._def;
+}
+
+/** Read the field-level `.describe()` value. */
+export function zodDescription(field: z.ZodType): string | undefined {
+  // @cast-boundary schema-walk
+  const desc = (field as { description?: string }).description;
+  return typeof desc === "string" && desc.length > 0 ? desc : undefined;
+}
+
+/** Treat a ZodObject's `shape` values as `z.ZodType`. Zod v4 typing
+ *  exposes them as `$ZodType` (core) — same runtime instance. */
+export function zodShape(schema: z.ZodObject<z.ZodRawShape>): Record<string, z.ZodType> {
+  // @cast-boundary schema-walk
+  return schema.shape as Record<string, z.ZodType>;
+}
+
+/** Look up a single field on a ZodObject's shape. */
+export function zodShapeField(
+  schema: z.ZodObject<z.ZodRawShape>,
+  name: string,
+): z.ZodType | undefined {
+  // @cast-boundary schema-walk
+  return schema.shape[name] as z.ZodType | undefined;
+}

package/src/env/dry-run.ts

@@ -0,0 +1,191 @@
+// Renderers for `KUMIKO_DRY_RUN_ENV=<mode>`. Operators run this against
+// a built app to discover the required env-vars without booting:
+//   - `human` — tabular, grouped by required/optional/withDefault
+//   - `json`  — machine-readable for CI / tooling
+//   - `pulumi`— `pulumi config set …`-lines for bootstrap
+//   - `k8s`   — Secret YAML stub
+//
+// The same schema introspection (`classifyField`, `readKumikoMeta`) used
+// by parseEnv drives the output here — single source of truth.
+
+import type { z } from "zod";
+import { zodShape } from "./_zod-introspect";
+import {
+  type ComposedEnvSchema,
+  classifyField,
+  type EnvFieldClass,
+  getDefaultValue,
+  getFieldDescription,
+  pulumiConfigKey,
+  readKumikoMeta,
+} from "./index";
+
+export type DryRunMode = "human" | "json" | "pulumi" | "k8s";
+
+export type DryRunOptions = {
+  /** From composeEnvSchema. Drives the per-row feature-attribution. */
+  readonly sources?: Readonly<Record<string, string>>;
+  /** Prefix for `pulumi config set <prefix>…` keys. Default "". */
+  readonly pulumiPrefix?: string;
+  /** k8s Secret name. Default "kumiko-env". */
+  readonly k8sName?: string;
+  /** k8s namespace. Default "default". */
+  readonly k8sNamespace?: string;
+};
+
+type EnvField = {
+  readonly name: string;
+  readonly field: z.ZodType;
+  readonly klass: EnvFieldClass;
+  readonly description?: string;
+  readonly defaultValue?: unknown;
+  readonly source: string; // feature name or "app" or "unknown"
+};
+
+function collectFields(
+  schema: z.ZodObject<z.ZodRawShape>,
+  sources: Readonly<Record<string, string>>,
+): readonly EnvField[] {
+  const out: EnvField[] = [];
+  for (const [name, field] of Object.entries(zodShape(schema))) {
+    const f = field;
+    const klass = classifyField(f);
+    out.push({
+      name,
+      field: f,
+      klass,
+      description: getFieldDescription(f),
+      ...(klass === "withDefault" ? { defaultValue: getDefaultValue(f) } : {}),
+      source: sources[name] ?? "unknown",
+    });
+  }
+  // Sort by class (required first), then by source, then by name. Stable
+  // ordering matters for snapshot-tests + grep-ability.
+  const order: Record<EnvFieldClass, number> = {
+    required: 0,
+    optional: 1,
+    withDefault: 2,
+  };
+  return out.sort((a, b) => {
+    if (order[a.klass] !== order[b.klass]) return order[a.klass] - order[b.klass];
+    if (a.source !== b.source) return a.source.localeCompare(b.source);
+    return a.name.localeCompare(b.name);
+  });
+}
+
+export function renderDryRun(
+  composed: ComposedEnvSchema,
+  mode: DryRunMode,
+  options: DryRunOptions = {},
+): string {
+  const sources = options.sources ?? composed.sources;
+  const fields = collectFields(composed.schema, sources);
+  switch (mode) {
+    case "human":
+      return renderHuman(fields);
+    case "json":
+      return renderJson(fields, options);
+    case "pulumi":
+      return renderPulumi(fields, options);
+    case "k8s":
+      return renderK8s(fields, options);
+  }
+}
+
+function renderHuman(fields: readonly EnvField[]): string {
+  const grouped: Record<EnvFieldClass, EnvField[]> = {
+    required: [],
+    optional: [],
+    withDefault: [],
+  };
+  for (const f of fields) grouped[f.klass].push(f);
+
+  const lines: string[] = [];
+  const sectionTitle: Record<EnvFieldClass, string> = {
+    required: "Required env-vars:",
+    optional: "Optional env-vars:",
+    withDefault: "Defaulted env-vars:",
+  };
+  const longest = fields.reduce((m, f) => Math.max(m, f.name.length), 0);
+  let first = true;
+  for (const klass of ["required", "optional", "withDefault"] as const) {
+    const items = grouped[klass];
+    if (items.length === 0) continue;
+    if (!first) lines.push("");
+    first = false;
+    lines.push(sectionTitle[klass]);
+    for (const f of items) {
+      const padded = f.name.padEnd(longest, " ");
+      const src = `(${f.source})`;
+      const dflt =
+        f.klass === "withDefault" && f.defaultValue !== undefined
+          ? ` [default: ${JSON.stringify(f.defaultValue)}]`
+          : "";
+      const desc = f.description ? ` — ${f.description}` : "";
+      lines.push(`  ${padded}  ${src}${dflt}${desc}`);
+    }
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+function renderJson(fields: readonly EnvField[], options: DryRunOptions): string {
+  const required = fields.filter((f) => f.klass === "required");
+  const optional = fields.filter((f) => f.klass === "optional");
+  const withDefault = fields.filter((f) => f.klass === "withDefault");
+
+  const toEntry = (f: EnvField) => ({
+    name: f.name,
+    feature: f.source,
+    ...(f.description ? { description: f.description } : {}),
+    ...(f.defaultValue !== undefined ? { default: f.defaultValue } : {}),
+    pulumiName: pulumiConfigKey(f.name, f.field, options.pulumiPrefix),
+  });
+
+  return `${JSON.stringify(
+    {
+      required: required.map(toEntry),
+      optional: optional.map(toEntry),
+      withDefault: withDefault.map(toEntry),
+    },
+    null,
+    2,
+  )}\n`;
+}
+
+function renderPulumi(fields: readonly EnvField[], options: DryRunOptions): string {
+  // Defaulted vars are skipped — the framework provides them, ops doesn't.
+  const lines: string[] = [];
+  for (const f of fields) {
+    if (f.klass === "withDefault") continue;
+    if (f.klass === "optional") continue;
+    const meta = readKumikoMeta(f.field);
+    const key = pulumiConfigKey(f.name, f.field, options.pulumiPrefix);
+    const secretFlag = meta.pulumi?.secret ? " --secret" : "";
+    const value = meta.pulumi?.generator ? `"$(${meta.pulumi.generator})"` : `"<set-me>"`;
+    const comment = f.description
+      ? ` # ${f.name} (${f.source}): ${f.description}`
+      : ` # ${f.name} (${f.source})`;
+    lines.push(`pulumi config set${secretFlag} ${key} ${value}${comment}`);
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+function renderK8s(fields: readonly EnvField[], options: DryRunOptions): string {
+  const name = options.k8sName ?? "kumiko-env";
+  const namespace = options.k8sNamespace ?? "default";
+  const lines: string[] = [
+    "apiVersion: v1",
+    "kind: Secret",
+    "metadata:",
+    `  name: ${name}`,
+    `  namespace: ${namespace}`,
+    "type: Opaque",
+    "stringData:",
+  ];
+  for (const f of fields) {
+    if (f.klass === "withDefault") continue;
+    if (f.klass === "optional") continue;
+    lines.push(`  ${f.name}: "<set-me>"`);
+  }
+  return `${lines.join("\n")}\n`;
+}