mfeflow 0.0.0-stage → 0.1.0

package/assets/features/env-t3/feature.json

@@ -0,0 +1,378 @@
+{
+  "name": "env-t3",
+  "version": "0.1.0",
+  "description": "Typed env with t3-env: env.ts per app fails the build on a missing variable, runtime-config schema checked before deploy, no validator or env value in the browser bundle.",
+  "requires": ["core", "tsconfig"],
+  "prompts": [
+    {
+      "name": "validator",
+      "type": "select",
+      "message": "Validator for env.ts and the runtime-config schema",
+      "choices": ["zod", "valibot", "arktype"],
+      "default": "zod"
+    }
+  ],
+  "files": [
+    {
+      "to": "env.ts",
+      "target": "root",
+      "from": "files/env.zod.ts",
+      "when": {
+        "validator": "zod"
+      }
+    },
+    {
+      "to": "env.ts",
+      "target": "root",
+      "from": "files/env.valibot.ts",
+      "when": {
+        "validator": "valibot"
+      }
+    },
+    {
+      "to": "env.ts",
+      "target": "root",
+      "from": "files/env.arktype.ts",
+      "when": {
+        "validator": "arktype"
+      }
+    },
+    {
+      "to": ".env.example",
+      "target": "root",
+      "from": "files/env.example"
+    },
+    {
+      "to": "scripts/check-runtime-config.ts",
+      "target": "root",
+      "from": "files/check-runtime-config.ts"
+    },
+    {
+      "to": "env.ts",
+      "target": "shell",
+      "from": "files/env.zod.ts",
+      "when": {
+        "validator": "zod"
+      }
+    },
+    {
+      "to": "env.ts",
+      "target": "shell",
+      "from": "files/env.valibot.ts",
+      "when": {
+        "validator": "valibot"
+      }
+    },
+    {
+      "to": "env.ts",
+      "target": "shell",
+      "from": "files/env.arktype.ts",
+      "when": {
+        "validator": "arktype"
+      }
+    },
+    {
+      "to": ".env.example",
+      "target": "shell",
+      "from": "files/env.example"
+    },
+    {
+      "to": "env.ts",
+      "target": "remotes",
+      "from": "files/env.zod.ts",
+      "when": {
+        "validator": "zod"
+      }
+    },
+    {
+      "to": "env.ts",
+      "target": "remotes",
+      "from": "files/env.valibot.ts",
+      "when": {
+        "validator": "valibot"
+      }
+    },
+    {
+      "to": "env.ts",
+      "target": "remotes",
+      "from": "files/env.arktype.ts",
+      "when": {
+        "validator": "arktype"
+      }
+    },
+    {
+      "to": ".env.example",
+      "target": "remotes",
+      "from": "files/env.example"
+    },
+    {
+      "to": "src/config/schema.ts",
+      "target": "shell",
+      "from": "files/schema.zod.ts",
+      "when": {
+        "validator": "zod"
+      }
+    },
+    {
+      "to": "src/config/schema.ts",
+      "target": "shell",
+      "from": "files/schema.valibot.ts",
+      "when": {
+        "validator": "valibot"
+      }
+    },
+    {
+      "to": "src/config/schema.ts",
+      "target": "shell",
+      "from": "files/schema.arktype.ts",
+      "when": {
+        "validator": "arktype"
+      }
+    },
+    {
+      "to": "src/config/runtime.ts",
+      "target": "shell",
+      "from": "files/runtime.ts.eta",
+      "template": true
+    },
+    {
+      "to": "public/config/runtime-config.dev.json",
+      "target": "shell",
+      "content": "{\n  \"environment\": \"dev\"\n}\n"
+    },
+    {
+      "to": "public/config/runtime-config.staging.json",
+      "target": "shell",
+      "content": "{\n  \"environment\": \"staging\"\n}\n"
+    },
+    {
+      "to": "public/config/runtime-config.prod.json",
+      "target": "shell",
+      "content": "{\n  \"environment\": \"prod\"\n}\n"
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "@t3-oss/env-core",
+      "range": "0.13.11",
+      "target": "root",
+      "dev": true
+    },
+    {
+      "name": "@t3-oss/env-core",
+      "range": "0.13.11",
+      "target": "shell",
+      "dev": true
+    },
+    {
+      "name": "@t3-oss/env-core",
+      "range": "0.13.11",
+      "target": "remotes",
+      "dev": true
+    },
+    {
+      "name": "zod",
+      "range": "4.6.7",
+      "target": "root",
+      "dev": true,
+      "when": {
+        "validator": "zod"
+      }
+    },
+    {
+      "name": "zod",
+      "range": "4.6.7",
+      "target": "shell",
+      "dev": true,
+      "when": {
+        "validator": "zod"
+      }
+    },
+    {
+      "name": "zod",
+      "range": "4.6.7",
+      "target": "remotes",
+      "dev": true,
+      "when": {
+        "validator": "zod"
+      }
+    },
+    {
+      "name": "valibot",
+      "range": "1.5.0",
+      "target": "root",
+      "dev": true,
+      "when": {
+        "validator": "valibot"
+      }
+    },
+    {
+      "name": "valibot",
+      "range": "1.5.0",
+      "target": "shell",
+      "dev": true,
+      "when": {
+        "validator": "valibot"
+      }
+    },
+    {
+      "name": "valibot",
+      "range": "1.5.0",
+      "target": "remotes",
+      "dev": true,
+      "when": {
+        "validator": "valibot"
+      }
+    },
+    {
+      "name": "arktype",
+      "range": "2.2.9",
+      "target": "root",
+      "dev": true,
+      "when": {
+        "validator": "arktype"
+      }
+    },
+    {
+      "name": "arktype",
+      "range": "2.2.9",
+      "target": "shell",
+      "dev": true,
+      "when": {
+        "validator": "arktype"
+      }
+    },
+    {
+      "name": "arktype",
+      "range": "2.2.9",
+      "target": "remotes",
+      "dev": true,
+      "when": {
+        "validator": "arktype"
+      }
+    },
+    {
+      "name": "@types/node",
+      "range": "26.6.6",
+      "target": "root",
+      "dev": true
+    }
+  ],
+  "scripts": [
+    {
+      "name": "check:runtime-config",
+      "command": "node --experimental-strip-types scripts/check-runtime-config.ts",
+      "target": "root"
+    },
+    {
+      "name": "typecheck:tooling",
+      "command": "tsc --noEmit",
+      "target": "root"
+    }
+  ],
+  "transforms": [
+    {
+      "op": "add-import",
+      "file": "rsbuild.config.ts",
+      "target": "shell",
+      "from": "./env"
+    },
+    {
+      "op": "add-import",
+      "file": "rsbuild.config.ts",
+      "target": "remotes",
+      "from": "./env"
+    },
+    {
+      "op": "add-boot-step",
+      "file": "src/bootstrap.tsx",
+      "target": "shell",
+      "call": "loadRuntimeConfig",
+      "from": "./config/runtime"
+    },
+    {
+      "op": "add-env-key",
+      "file": "src/config/schema.ts",
+      "target": "shell",
+      "key": "gtmId",
+      "scope": "runtime",
+      "schema": {
+        "zod": "z.string().regex(/^(GTM-[A-Z0-9]{4,12})?$/)",
+        "valibot": "v.pipe(v.string(), v.regex(/^(GTM-[A-Z0-9]{4,12})?$/))",
+        "arktype": "'/^(GTM-[A-Z0-9]{4,12})?$/'"
+      },
+      "value": "",
+      "configFiles": [
+        "public/config/runtime-config.dev.json",
+        "public/config/runtime-config.staging.json",
+        "public/config/runtime-config.prod.json"
+      ],
+      "when": {
+        "feature:analytics-gtm": true
+      }
+    },
+    {
+      "op": "add-env-key",
+      "file": "src/config/schema.ts",
+      "target": "shell",
+      "key": "otlpEndpoint",
+      "scope": "runtime",
+      "schema": {
+        "zod": "z.string().regex(/^(https?:[/][/][^\\s]+)?$/)",
+        "valibot": "v.pipe(v.string(), v.regex(/^(https?:[/][/][^\\s]+)?$/))",
+        "arktype": "\"'' | string.url\""
+      },
+      "value": "",
+      "configFiles": [
+        "public/config/runtime-config.dev.json",
+        "public/config/runtime-config.staging.json",
+        "public/config/runtime-config.prod.json"
+      ],
+      "when": {
+        "feature:telemetry-otel": true
+      }
+    },
+    {
+      "op": "add-env-key",
+      "file": "src/config/schema.ts",
+      "target": "shell",
+      "key": "traceSampleRatio",
+      "scope": "runtime",
+      "schema": {
+        "zod": "z.number().min(0).max(1)",
+        "valibot": "v.pipe(v.number(), v.minValue(0), v.maxValue(1))",
+        "arktype": "'0 <= number <= 1'"
+      },
+      "value": 1,
+      "configFiles": [
+        "public/config/runtime-config.dev.json",
+        "public/config/runtime-config.staging.json",
+        "public/config/runtime-config.prod.json"
+      ],
+      "when": {
+        "feature:telemetry-otel": true
+      }
+    },
+    {
+      "op": "add-env-key",
+      "file": "src/config/schema.ts",
+      "target": "shell",
+      "key": "propagateTraceHeaderCorsUrls",
+      "scope": "runtime",
+      "schema": {
+        "zod": "z.array(z.string())",
+        "valibot": "v.array(v.string())",
+        "arktype": "'string[]'"
+      },
+      "value": [],
+      "configFiles": [
+        "public/config/runtime-config.dev.json",
+        "public/config/runtime-config.staging.json",
+        "public/config/runtime-config.prod.json"
+      ],
+      "when": {
+        "feature:telemetry-otel": true
+      }
+    }
+  ]
+}

package/assets/features/env-t3/files/check-runtime-config.ts

@@ -0,0 +1,105 @@
+// Validates every public/config/runtime-config*.json against the schema in the same app's
+// src/config/schema.ts. Run it before a deploy: pnpm check:runtime-config [env ...]
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+interface Issue {
+  message: string;
+  path?: readonly unknown[];
+}
+
+type Result = { issues?: readonly Issue[] };
+
+interface StandardSchema {
+  '~standard': { validate: (value: unknown) => Result | Promise<Result> };
+}
+
+interface Outcome {
+  checked: number;
+  failures: string[];
+}
+
+const ENV_FILE = /^runtime-config(?:\.([a-z0-9-]+))?\.json$/;
+const root = process.cwd();
+const wanted = process.argv.slice(2);
+
+function isObject(value: unknown): value is object {
+  return (typeof value === 'object' || typeof value === 'function') && value !== null;
+}
+
+function isStandardSchema(value: unknown): value is StandardSchema {
+  if (!isObject(value) || !('~standard' in value)) return false;
+  const meta = value['~standard'];
+  return isObject(meta) && 'validate' in meta && typeof meta.validate === 'function';
+}
+
+function appDirs(): string[] {
+  const project: unknown = JSON.parse(fs.readFileSync(path.join(root, 'mfeflow.json'), 'utf8'));
+  const apps = isObject(project) && 'apps' in project ? project.apps : undefined;
+  if (!isObject(apps)) return [];
+  return Object.values(apps).flatMap((app: unknown) =>
+    isObject(app) && 'path' in app && typeof app.path === 'string'
+      ? [path.join(root, app.path)]
+      : [],
+  );
+}
+
+async function checkFile(schema: StandardSchema, file: string): Promise<string[]> {
+  const shown = path.relative(root, file);
+  let json: unknown;
+  try {
+    json = JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (error) {
+    return [`${shown}: not valid JSON (${error instanceof Error ? error.message : String(error)})`];
+  }
+  const { issues = [] } = await schema['~standard'].validate(json);
+  return issues.map((issue) => {
+    const at = (issue.path ?? []).map(String).join('.');
+    return `${shown}: ${at === '' ? '(root)' : at} ${issue.message}`;
+  });
+}
+
+async function checkApp(dir: string): Promise<Outcome> {
+  const schemaFile = path.join(dir, 'src', 'config', 'schema.ts');
+  const configDir = path.join(dir, 'public', 'config');
+  if (!fs.existsSync(schemaFile) || !fs.existsSync(configDir)) return { checked: 0, failures: [] };
+  const loaded: unknown = await import(pathToFileURL(schemaFile).href);
+  const schema =
+    isObject(loaded) && 'runtimeConfigSchema' in loaded ? loaded.runtimeConfigSchema : undefined;
+  if (!isStandardSchema(schema)) {
+    return {
+      checked: 0,
+      failures: [
+        `${path.relative(root, schemaFile)}: runtimeConfigSchema is not a Standard Schema`,
+      ],
+    };
+  }
+  const files = fs
+    .readdirSync(configDir)
+    .toSorted((a, b) => a.localeCompare(b))
+    .filter((name) => {
+      const match = ENV_FILE.exec(name);
+      return match !== null && (wanted.length === 0 || wanted.includes(match[1] ?? ''));
+    });
+  const results = await Promise.all(
+    files.map((name) => checkFile(schema, path.join(configDir, name))),
+  );
+  return { checked: files.length, failures: results.flat() };
+}
+
+const outcomes = await Promise.all(appDirs().map(checkApp));
+const checked = outcomes.reduce((sum, o) => sum + o.checked, 0);
+const failures = outcomes.flatMap((o) => o.failures);
+
+for (const line of failures) console.error(line);
+if (checked === 0 && failures.length === 0) {
+  console.error(
+    wanted.length > 0
+      ? `no runtime-config.<env>.json found for ${wanted.join(', ')}`
+      : 'no runtime-config files found',
+  );
+  process.exit(1);
+}
+if (failures.length > 0) process.exit(1);
+console.log(`runtime config ok (${String(checked)} file${checked === 1 ? '' : 's'})`);

package/assets/features/env-t3/files/env.arktype.ts

@@ -0,0 +1,12 @@
+import { createEnv } from '@t3-oss/env-core';
+import { type } from 'arktype';
+
+// Server and build-time variables, checked when a process that imports this file starts.
+// Add one: mfeflow add env-key API_ORIGIN --scope server --schema "type('string.url')"
+export const env = createEnv({
+  server: {
+    NODE_ENV: type("'development' | 'production' | 'test' | undefined"),
+  },
+  runtimeEnv: process.env,
+  emptyStringAsUndefined: true,
+});

package/assets/features/env-t3/files/env.example

@@ -0,0 +1 @@
+# Variables env.ts checks. Copy to .env and fill in; .env stays out of git.

package/assets/features/env-t3/files/env.valibot.ts

@@ -0,0 +1,12 @@
+import { createEnv } from '@t3-oss/env-core';
+import * as v from 'valibot';
+
+// Server and build-time variables, checked when a process that imports this file starts.
+// Add one: mfeflow add env-key API_ORIGIN --scope server --schema "v.pipe(v.string(), v.url())"
+export const env = createEnv({
+  server: {
+    NODE_ENV: v.optional(v.picklist(['development', 'production', 'test'])),
+  },
+  runtimeEnv: process.env,
+  emptyStringAsUndefined: true,
+});

package/assets/features/env-t3/files/env.zod.ts

@@ -0,0 +1,12 @@
+import { createEnv } from '@t3-oss/env-core';
+import { z } from 'zod';
+
+// Server and build-time variables, checked when a process that imports this file starts.
+// Add one: mfeflow add env-key API_ORIGIN --scope server --schema "z.url()"
+export const env = createEnv({
+  server: {
+    NODE_ENV: z.enum(['development', 'production', 'test']).optional(),
+  },
+  runtimeEnv: process.env,
+  emptyStringAsUndefined: true,
+});

package/assets/features/env-t3/files/runtime.ts.eta

@@ -0,0 +1,30 @@
+import { fetchRuntimeConfig, reportRemoteError } from '@mfeflow/runtime';
+import type { runtimeConfigSchema } from './schema';
+
+export type RuntimeConfig = NonNullable<
+  (typeof runtimeConfigSchema)['~standard']['types']
+>['output'];
+
+const KEY = '__MFE_RUNTIME_CONFIG__';
+
+/** The config the shell loaded. Typed from the schema; nothing is validated here, `pnpm check:runtime-config` does that before deploy. */
+export function getRuntimeConfig(): RuntimeConfig {
+  const config: unknown = Reflect.get(globalThis, KEY);
+  if (config === undefined) {
+    throw new Error('getRuntimeConfig() was called before the shell loaded the runtime config');
+  }
+  // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- the deploy check validated this file against the schema
+  return config as RuntimeConfig;
+}
+
+/**
+ * Fetches the runtime config once at boot, through the loader analytics and telemetry share, so the
+ * file is requested once. A failure is reported and leaves the config unset.
+ */
+export async function loadRuntimeConfig(url?: string): Promise<void> {
+  try {
+    await fetchRuntimeConfig(url);
+  } catch (error) {
+    reportRemoteError('<%= it.app.name %>', 'runtime-config', error);
+  }
+}

package/assets/features/env-t3/files/schema.arktype.ts

@@ -0,0 +1,8 @@
+import { type } from 'arktype';
+
+// The shape of public/config/runtime-config.<env>.json. The browser only imports this file's type
+// (see ./runtime), so the validator stays out of the bundle; `pnpm check:runtime-config` validates the files.
+// Add a key: mfeflow add env-key GTM_ID --scope runtime --schema "type('string > 0')"
+export const runtimeConfigSchema = type({
+  environment: "'dev' | 'staging' | 'prod'",
+});

package/assets/features/env-t3/files/schema.valibot.ts

@@ -0,0 +1,8 @@
+import * as v from 'valibot';
+
+// The shape of public/config/runtime-config.<env>.json. The browser only imports this file's type
+// (see ./runtime), so the validator stays out of the bundle; `pnpm check:runtime-config` validates the files.
+// Add a key: mfeflow add env-key GTM_ID --scope runtime --schema "v.pipe(v.string(), v.minLength(1))"
+export const runtimeConfigSchema = v.object({
+  environment: v.picklist(['dev', 'staging', 'prod']),
+});

package/assets/features/env-t3/files/schema.zod.ts

@@ -0,0 +1,8 @@
+import { z } from 'zod';
+
+// The shape of public/config/runtime-config.<env>.json. The browser only imports this file's type
+// (see ./runtime), so the validator stays out of the bundle; `pnpm check:runtime-config` validates the files.
+// Add a key: mfeflow add env-key GTM_ID --scope runtime --schema "z.string().min(1)"
+export const runtimeConfigSchema = z.object({
+  environment: z.enum(['dev', 'staging', 'prod']),
+});

package/assets/features/git-hooks/feature.json

@@ -0,0 +1,42 @@
+{
+  "name": "git-hooks",
+  "version": "0.1.0",
+  "description": "lefthook with commitlint: Conventional Commit messages, typecheck before push. Opt-in.",
+  "requires": ["core"],
+  "files": [
+    {
+      "to": "lefthook.yml",
+      "from": "files/lefthook.yml"
+    },
+    {
+      "to": "commitlint.config.js",
+      "from": "files/commitlint.config.js"
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "lefthook",
+      "range": "2.2.2",
+      "target": "root",
+      "dev": true
+    },
+    {
+      "name": "@commitlint/cli",
+      "range": "21.2.4",
+      "target": "root",
+      "dev": true
+    },
+    {
+      "name": "@commitlint/config-conventional",
+      "range": "21.2.4",
+      "target": "root",
+      "dev": true
+    }
+  ],
+  "scripts": [
+    {
+      "name": "prepare",
+      "command": "lefthook install"
+    }
+  ]
+}

package/assets/features/git-hooks/files/commitlint.config.js

@@ -0,0 +1 @@
+export default { extends: ['@commitlint/config-conventional'] };

package/assets/features/git-hooks/files/lefthook.yml

@@ -0,0 +1,9 @@
+commit-msg:
+  commands:
+    commitlint:
+      run: pnpm commitlint --edit {1}
+
+pre-push:
+  commands:
+    typecheck:
+      run: pnpm typecheck