@bleedingdev/modern-js-ultramodern-create 3.8.3-ultramodern.2

package/template-workspace/README.md.handlebars

@@ -0,0 +1,229 @@
+# {{packageName}}
+
+Generated UltraModern SuperApp workspace.
+
+This workspace keeps `presetUltramodern(...)` as the single public
+UltraModern.js 3.0 SuperApp surface and starts with an explicit shell:
+
+- `apps/shell-super-app` owns shell route assembly, Module Federation host
+  wiring, shared SSR/i18n runtime setup, and the boundary debugger.
+- `packages/shared-*` provide placeholders for cross-workspace contracts and
+  design tokens.
+- `verticals/*` is intentionally empty until a real business domain is added.
+
+Add a full-stack MicroVertical when the product needs one:
+
+```bash
+pnpm dlx @bleedingdev/modern-js-ultramodern-create transportation --vertical
+pnpm dlx @bleedingdev/modern-js-ultramodern-create payments --vertical
+```
+
+Each added vertical owns its UI/routes, browser-safe Module Federation exposes,
+private-first route metadata, localized URLs, public-route opt-ins, CSS prefix,
+Effect BFF handlers, local API contract, and typed client surface. Server
+handlers and Effect client/contract modules stay out of browser exposes.
+
+## Generated config policy
+
+Each generated `modern.config.ts` calls
+`presetUltramodern(appConfig, presetOptions)`. A bare config materialized by
+`createPresetUltramodernConfig()` uses `appId: 'app'` and has no
+`deliveryUnit`. Generated apps instead keep their app-specific `appId` and
+stamped `deliveryUnit` in `presetOptions`. Other strict defaults come from the
+preset, so do not copy an expanded defaults object or spread one config over
+another.
+
+Telemetry stays enabled, but exporters have no endpoint by default. Set
+`MODERN_TELEMETRY_OTLP_ENDPOINT` to enable only OTLP, or
+`MODERN_TELEMETRY_VICTORIA_ENDPOINT` to enable only VictoriaMetrics. Set both
+to enable both exporters. Leaving both unset configures neither exporter.
+
+Keep the generated identity options and use typed preset options for opt-outs:
+
+- `enableTelemetryExporters: false` disables all exporters.
+- `enableTelemetry: false` disables the telemetry contract.
+- `enableBffRequestId: false` and `enableModuleFederationSSR: false` disable
+  their matching preset contracts.
+
+Use the first `appConfig` argument for app-owned overrides such as
+`server.telemetry.failLoudStartup`. Nested records merge through the Modern.js
+config merger, so sibling preset fields remain intact.
+
+## Private-First Public Surfaces
+
+Generated app routes are private and non-indexable by default. Author route
+metadata in colocated `src/routes/**/route.meta.ts` files; the scaffold
+regenerates `src/routes/ultramodern-route-metadata.ts` as a compatibility
+manifest for config, i18n, public head, and public surface contracts. Private
+app, auth, tenant, dashboard, and internal routes publish no discovery output
+unless route metadata explicitly marks them `public && indexable`. The default
+scaffold therefore emits only a disallowing `robots.txt`; sitemap, web
+manifest, `llms.txt`, API catalog, security.txt, and JSON-LD output stay
+omitted until a safe public route or public docs/help/product surface exists.
+Structured data is never inferred automatically. Add `jsonLd` explicitly in
+route metadata for `public && indexable` routes and use
+`src/routes/ultramodern-jsonld.ts` when the route fits the generated `WebPage`,
+`WebApplication`, `SoftwareApplication`, `BreadcrumbList`, `FAQPage`, or
+`Organization` helpers. Private or non-indexable routes emit no JSON-LD even
+when they have localized paths, titles, descriptions, BFF APIs, or Module
+Federation boundaries.
+
+Public web artifacts are build/deploy outputs generated into `dist/public` and
+`.output/public`, not hand-authored source files under `config/public`. Dynamic
+public routes can expand sitemap entries through route-owned, Node-safe
+`route.sitemap.mjs` providers beside route metadata. The public-surface
+generator discovers those providers for dynamic public routes and still honors
+explicit `routes.publicSurface.contentSources` entries in the generated
+compatibility manifest.
+
+Run the scaffold validator before adding business code and after every
+`--vertical` mutation:
+
+```bash
+mise install
+pnpm install
+pnpm check
+pnpm build
+```
+
+The generated toolchain baseline is Node `>=26` with pnpm `{{pnpmVersion}}`.
+`packageManager`, `.mise.toml`, generated validation, and CI should all agree
+on that baseline; do not reintroduce Corepack or older pnpm aliases.
+
+Generated CI does not call the local aggregate. It runs format, lint,
+typecheck, skills, i18n boundary validation, contract validation, and build as
+separate matrix jobs so failures are isolated and parallelizable.
+
+Type checking is TS7-first. `pnpm typecheck` runs
+`scripts/ultramodern-typecheck.mts` in TS-Go build mode over
+`tsconfig.json` project references, with `--checkers` and `--builders`
+enabled by default. The stable `typescript` package is pinned to TS7 so
+Modern/Rspack type checking uses TS-Go by default.
+
+Read-only agent reference repositories under `repos/` (Effect and
+UltraModern.js source lookup using squashed git subtrees) are an explicit
+opt-in step: run `pnpm agents:refs:install` when you want them. `pnpm install`
+never clones repositories.
+
+Codex skill bodies are lockfile-pinned in `.codex/skills-lock.json` and
+repo-owned under `.codex/skills`. `pnpm install` runs the bootstrap by default:
+vendored pinned skills are copied locally, clone-backed public skills are
+fetched when network access is available, and offline clone failures remain
+advisory. Existing unrelated `.codex/skills/*` directories are preserved. Set
+`ULTRAMODERN_SKIP_CODEX_SKILLS=1` or `ULTRAMODERN_CODEX_SKILLS=0` to opt out.
+`pnpm skills:check` is advisory when local skill bodies are missing so offline
+CI can still run the normal gate.
+
+The topology and ownership metadata are generated under `topology/`. The
+workspace also ships `.github/workflows/ultramodern-workspace-gates.yml` and
+`.github/renovate.json` with read-only workflow permissions, commit-pinned
+actions, frozen installs, StepSecurity audit-mode runner hardening, dependency
+dashboard review, one-day release age, grouped updates, and manual approval for
+major upgrades.
+
+Package source provenance is recorded in `.modernjs/ultramodern.json`. The
+default strategy keeps UltraModern.js runtime and tooling packages on
+`workspace:*` for monorepo development. To create a workspace that can install
+those packages outside the monorepo, generate with
+`--ultramodern-package-source install`; generated shared packages still use
+`workspace:*` because they are part of this workspace.
+
+## Public URL Environment Variables
+
+This workspace's apps must not bake absolute `http://localhost:<port>` URLs
+into asset configuration. Public URL and asset prefix environment variables
+have distinct roles, and stale aliases should not be carried forward when
+regenerating or updating the workspace.
+
+| Variable | Role | Feeds |
+| --- | --- | --- |
+| `MODERN_PUBLIC_SITE_URL` | Canonical site origin for public SEO output only | Canonical, hreflang, sitemap `<loc>`, robots `Sitemap:` |
+| `MODERN_ASSET_PREFIX` | Preferred JS/CSS/static asset prefix | Modern/Rspack-emitted asset URLs |
+| `ULTRAMODERN_ASSET_PREFIX` | UltraModern compatibility asset prefix | Modern/Rspack-emitted asset URLs when `MODERN_ASSET_PREFIX` is unset |
+| `ULTRAMODERN_PUBLIC_URL_<APP_ID>` | Per-app deployment/proof URL | Cloudflare proof inputs and Module Federation remote URLs |
+
+Shell asset URLs use this precedence: `MODERN_ASSET_PREFIX` →
+`ULTRAMODERN_ASSET_PREFIX` → origin-relative `/`. Module Federation remotes use
+the same env precedence, then fall back to their per-app public origin:
+configured public URL, inferred workers.dev URL, or local dev port.
+`MODERN_PUBLIC_SITE_URL` is canonical/SEO-only and must not be used as an
+asset-prefix fallback.
+SEO output uses `MODERN_PUBLIC_SITE_URL`; if it is unset, generated local and
+preview outputs remain non-public until deployment proof provides explicit
+public URLs.
+
+Without public URLs configured, shell asset paths are origin-relative (`/`).
+Remote dev manifests publish their own local origin so host shells load
+`remoteEntry.js` and exposed chunks from the remote dev server. Shell-only
+workspaces can set `MODERN_PUBLIC_SITE_URL` for SEO output without changing
+where assets load from.
+
+## Cloudflare Proof
+
+Deploy the generated apps, then pass each deployed app's generated public URL
+env key into the proof step. The proof script reads the generated contract and
+checks the live Worker surface, including public-route sitemap/robots
+consistency, preview noindex behavior, unknown-route status, asset headers,
+byte budgets, and public sourcemap exposure. A shell-only workspace only needs
+the shell URL; added verticals use the same `ULTRAMODERN_PUBLIC_URL_<APP_ID>`
+pattern with hyphens converted to underscores and uppercased.
+
+```bash
+pnpm cloudflare:deploy
+pnpm exec cross-env ULTRAMODERN_PUBLIC_URL_SHELL_SUPER_APP=https://shell-super-app.example.workers.dev pnpm cloudflare:proof --require-public-urls
+```
+
+## Strict Effect API
+
+Generated HTTP APIs use the direct strict Effect topology only:
+
+- API contracts live at `shared/api.ts`.
+- Runtime entries live at `api/index.ts`.
+- Browser clients live under `src/api/*-client.ts`.
+- `modern.config.ts` uses `bff.runtimeFramework: 'effect'`,
+  `bff.effect.entry: './api/index'`, and
+  `bff.effect.strictEffectApproach: true`.
+
+Do not add `api/effect`, `api/lambda`, `shared/effect`, `src/effect`, Hono
+server imports, raw request handlers, manual `request.json()` parsing, or
+manual `new Response(...)` construction inside generated API modules.
+`pnpm api:check` and Oxlint enforce this. Model requests, responses, and typed
+errors with concrete Effect `Schema` values; generic JSON shortcuts such as
+`Schema.UnknownFromJsonString`, `Schema.Unknown`, and `Schema.Any` are rejected
+in API modules.
+
+Generated pnpm overrides pin the framework-compatible Effect cohort. Keep
+`effect` and `@effect/vitest` aligned with `pnpm-workspace.yaml`; do not add
+new direct package-level Effect versions unless the whole UltraModern cohort is
+upgraded. The generated pnpm policy intentionally excludes the matching
+`effect` and `@effect/opentelemetry` cohort versions from the
+minimum-release-age and no-downgrade checks while Effect's beta publishes move
+from trusted-publisher metadata to provenance attestations.
+
+For older generated workspaces, run the framework migration command first:
+
+```bash
+pnpm dlx @bleedingdev/modern-js-ultramodern-create@3.5.0-ultramodern.10 ultramodern \
+  migrate-strict-effect --version 3.5.0-ultramodern.10
+pnpm api:check
+pnpm contract:check
+```
+
+The command updates generated package-source metadata, Modern package aliases,
+framework-owned toolchain pins, direct API topology metadata, strict Effect pnpm
+overrides/trust policy, and the lockfile. Remaining failures are source
+migration work; fix the owning API files instead of adding compatibility shims.
+
+## Troubleshooting
+
+| Symptom | Current check | Owner |
+| --- | --- | --- |
+| Package cohort mismatch | Regenerate with one package source strategy, run `mise install`, then rerun `pnpm install` from the activated shell. | Generated workspace package source metadata |
+| Effect runtime cohort mismatch | Keep `effect` and `@effect/vitest` on the generated pnpm override versions, then rerun `pnpm install`. | Generated workspace dependency policy |
+| Old nested API path | Run `pnpm api:check`, move code to `api/index.ts`, `shared/api.ts`, and `src/api/*`, then delete `api/effect`, `api/lambda`, `shared/effect`, and `src/effect`. | API owner |
+| Install failure | Check the active Node/pnpm from `mise install`; rerun `pnpm install` after the shell sees the pinned versions. | Toolchain setup |
+| Build failure | Run the matching primitive gate (`pnpm lint`, `pnpm typecheck`, `pnpm i18n:boundaries`, `pnpm contract:check`) before `pnpm build`; fix the owning failure first. | Owning package or generated contract |
+| Missing public URL | Set the app public URL env key recorded in `.modernjs/ultramodern.json`, for example `ULTRAMODERN_PUBLIC_URL_SHELL_SUPER_APP`. | Deployment operator |
+| Cloudflare credentials | Confirm Wrangler credentials before `pnpm cloudflare:deploy`; local checks do not prove live Worker access. | Deployment operator |
+| Asset or CSS 404 | Rebuild with `pnpm build` or `pnpm cloudflare:deploy` and inspect emitted Modern/Rspack asset paths instead of hardcoding CSS URLs. | Framework/runtime asset pipeline |
+| Federation manifest failure | Run the shell and vertical build scripts, then check each deployed `/mf-manifest.json` URL used by the shell. | Module Federation owner |

package/template-workspace/lefthook.yml

@@ -0,0 +1,24 @@
+pre-commit:
+  commands:
+    format:
+      run: pnpm format
+      stage_fixed: true
+    lint-fix:
+      run: pnpm lint:fix
+      stage_fixed: true
+
+pre-push:
+  parallel: true
+  commands:
+    format:
+      run: pnpm format:check
+    lint:
+      run: pnpm lint
+    typecheck:
+      run: pnpm typecheck
+    skills:
+      run: pnpm skills:check
+    i18n-boundaries:
+      run: pnpm i18n:boundaries
+    contract:
+      run: pnpm contract:check

package/template-workspace/oxfmt.config.ts

@@ -0,0 +1,20 @@
+import { defineConfig } from 'oxfmt';
+import ultracite from 'ultracite/oxfmt';
+
+export default defineConfig({
+  ...ultracite,
+  ignorePatterns: [
+    '.agents',
+    '.codex/skills',
+    '.output',
+    '**/*.json',
+    'dist',
+    'node_modules',
+    'repos/**',
+    '.modern',
+    '.modernjs',
+    '**/modern-tanstack/**',
+    '**/routeTree.gen.*',
+  ],
+  singleQuote: true,
+});

package/template-workspace/oxlint.config.ts

@@ -0,0 +1,38 @@
+import { defineConfig } from 'oxlint';
+import core from 'ultracite/oxlint/core';
+import react from 'ultracite/oxlint/react';
+
+export default defineConfig({
+  env: {
+    browser: true,
+    node: true,
+  },
+  extends: [core, react],
+  rules: {
+    'func-style': [
+      'error',
+      'declaration',
+      {
+        allowArrowFunctions: true,
+      },
+    ],
+    'react/function-component-definition': [
+      'error',
+      {
+        namedComponents: ['function-declaration', 'arrow-function'],
+      },
+    ],
+  },
+  ignorePatterns: [
+    '.agents',
+    '.codex/skills',
+    '.output',
+    'dist',
+    'node_modules',
+    'repos/**',
+    '.modern',
+    '.modernjs',
+    '**/modern-tanstack/**',
+    '**/routeTree.gen.*',
+  ],
+});

package/template-workspace/patches/@module-federation__bridge-react@2.9.0.patch

@@ -0,0 +1,47 @@
+diff --git a/dist/lazy/wrapNoSSR.d.ts b/dist/lazy/wrapNoSSR.d.ts
+--- a/dist/lazy/wrapNoSSR.d.ts
++++ b/dist/lazy/wrapNoSSR.d.ts
+@@ -6,4 +6,4 @@ export declare function wrapNoSSR<T, E extends keyof T>(createLazyComponentFn:
+     key?: React.Key | null;
+ } : {
+     key?: React.Key | null;
+-}) => import("node_modules/@types/react").JSX.Element;
++}) => import("react").JSX.Element;
+diff --git a/dist/provider/versions/v18.d.ts b/dist/provider/versions/v18.d.ts
+--- a/dist/provider/versions/v18.d.ts
++++ b/dist/provider/versions/v18.d.ts
+@@ -12,7 +12,7 @@ export interface Root {
+     unmount(): void;
+ }
+ export declare function createReact18Root(container: Element | DocumentFragment, options?: CreateRootOptions): Root;
+-export declare function hydrateReact18Root(container: Element | DocumentFragment, initialChildren: React.ReactNode, options?: CreateRootOptions): import("node_modules/@types/react-dom/client").Root;
++export declare function hydrateReact18Root(container: Element | DocumentFragment, initialChildren: React.ReactNode, options?: CreateRootOptions): import("react-dom/client").Root;
+ export declare function createBridgeComponent<T = any>(bridgeInfo: Omit<ProviderFnParams<T>, 'createRoot'>): () => {
+     render(info: import("../..").RenderParams): Promise<void>;
+     destroy(info: import("../..").DestroyParams): void;
+diff --git a/dist/remote/base-component/create.d.ts b/dist/remote/base-component/create.d.ts
+--- a/dist/remote/base-component/create.d.ts
++++ b/dist/remote/base-component/create.d.ts
+@@ -1,7 +1,7 @@
+ import { type LazyRemoteComponentInfo } from '../createHelpers';
+ export type { LazyRemoteComponentInfo };
+-declare const createLazyRemoteComponent: <T = Record<string, unknown>, E extends keyof T = keyof T>(info: LazyRemoteComponentInfo<T, E>) => import("node_modules/@types/react").LazyExoticComponent<import("node_modules/@types/react").ForwardRefExoticComponent<Omit<import("../..").RemoteComponentProps<Record<string, unknown>>, "ref"> & import("node_modules/@types/react").RefAttributes<HTMLDivElement>>>;
+-export declare const createRemoteAppComponent: <T = Record<string, unknown>, E extends keyof T = keyof T>(info: LazyRemoteComponentInfo<T, E>) => import("node_modules/@types/react").ForwardRefExoticComponent<Omit<import("../..").RemoteComponentProps<Record<string, unknown>>, "ref"> & import("node_modules/@types/react").RefAttributes<HTMLDivElement>>;
++declare const createLazyRemoteComponent: <T = Record<string, unknown>, E extends keyof T = keyof T>(info: LazyRemoteComponentInfo<T, E>) => import("react").LazyExoticComponent<import("react").ForwardRefExoticComponent<Omit<import("../..").RemoteComponentProps<Record<string, unknown>>, "ref"> & import("react").RefAttributes<HTMLDivElement>>>;
++export declare const createRemoteAppComponent: <T = Record<string, unknown>, E extends keyof T = keyof T>(info: LazyRemoteComponentInfo<T, E>) => import("react").ForwardRefExoticComponent<Omit<import("../..").RemoteComponentProps<Record<string, unknown>>, "ref"> & import("react").RefAttributes<HTMLDivElement>>;
+ /**
+  * @deprecated createRemoteComponent is deprecated, please use createRemoteAppComponent instead!
+  */
+diff --git a/dist/remote/router-component/create.d.ts b/dist/remote/router-component/create.d.ts
+--- a/dist/remote/router-component/create.d.ts
++++ b/dist/remote/router-component/create.d.ts
+@@ -1,7 +1,7 @@
+ import { type LazyRemoteComponentInfo } from '../createHelpers';
+ export type { LazyRemoteComponentInfo };
+-declare const createLazyRemoteComponent: <T = Record<string, unknown>, E extends keyof T = keyof T>(info: LazyRemoteComponentInfo<T, E>) => import("node_modules/@types/react").LazyExoticComponent<import("node_modules/@types/react").ForwardRefExoticComponent<Omit<import("../..").RemoteComponentProps<Record<string, unknown>>, "ref"> & import("node_modules/@types/react").RefAttributes<HTMLDivElement>>>;
+-export declare const createRemoteAppComponent: <T = Record<string, unknown>, E extends keyof T = keyof T>(info: LazyRemoteComponentInfo<T, E>) => import("node_modules/@types/react").ForwardRefExoticComponent<Omit<import("../..").RemoteComponentProps<Record<string, unknown>>, "ref"> & import("node_modules/@types/react").RefAttributes<HTMLDivElement>>;
++declare const createLazyRemoteComponent: <T = Record<string, unknown>, E extends keyof T = keyof T>(info: LazyRemoteComponentInfo<T, E>) => import("react").LazyExoticComponent<import("react").ForwardRefExoticComponent<Omit<import("../..").RemoteComponentProps<Record<string, unknown>>, "ref"> & import("react").RefAttributes<HTMLDivElement>>>;
++export declare const createRemoteAppComponent: <T = Record<string, unknown>, E extends keyof T = keyof T>(info: LazyRemoteComponentInfo<T, E>) => import("react").ForwardRefExoticComponent<Omit<import("../..").RemoteComponentProps<Record<string, unknown>>, "ref"> & import("react").RefAttributes<HTMLDivElement>>;
+ /**
+  * @deprecated createRemoteComponent is deprecated, please use createRemoteAppComponent instead!
+  */

package/template-workspace/patches/@module-federation__dts-plugin@2.9.0.patch

@@ -0,0 +1,26 @@
+diff --git a/dist/esm/expose-rpc-B0rqtOKP.mjs b/dist/esm/expose-rpc-B0rqtOKP.mjs
+index 1692a3e..1c99630 100644
+--- a/dist/esm/expose-rpc-B0rqtOKP.mjs
++++ b/dist/esm/expose-rpc-B0rqtOKP.mjs
+@@ -1415,7 +1415,7 @@ const formatCompilerError = (error) => {
+ const getDependentFilesWithTsc = (rootFiles, rootDir, resolvedTsConfigPath, compilerOptions, context, typeScriptContext) => {
+ 	if (!rootFiles.length) return [];
+ 	const typeScriptPackageInfo = getTypeScriptPackageInfo(typeScriptContext);
+-	const listFilesTsConfigPath = writeListFilesTsConfig(rootFiles, resolvedTsConfigPath, context, compilerOptions);
++	const listFilesTsConfigPath = writeListFilesTsConfig(rootFiles, resolvedTsConfigPath, context, { ...compilerOptions, rootDir });
+ 	try {
+ 		const dependentFiles = execFileSync(process.execPath, [
+ 			typeScriptPackageInfo.tscBinPath,
+diff --git a/dist/expose-rpc-jaGpsAVL.js b/dist/expose-rpc-jaGpsAVL.js
+index 55f07d8..7828615 100644
+--- a/dist/expose-rpc-jaGpsAVL.js
++++ b/dist/expose-rpc-jaGpsAVL.js
+@@ -1404,7 +1404,7 @@ const formatCompilerError = (error) => {
+ const getDependentFilesWithTsc = (rootFiles, rootDir, resolvedTsConfigPath, compilerOptions, context, typeScriptContext) => {
+ 	if (!rootFiles.length) return [];
+ 	const typeScriptPackageInfo = getTypeScriptPackageInfo(typeScriptContext);
+-	const listFilesTsConfigPath = writeListFilesTsConfig(rootFiles, resolvedTsConfigPath, context, compilerOptions);
++	const listFilesTsConfigPath = writeListFilesTsConfig(rootFiles, resolvedTsConfigPath, context, { ...compilerOptions, rootDir });
+ 	try {
+ 		const dependentFiles = (0, child_process.execFileSync)(process.execPath, [
+ 			typeScriptPackageInfo.tscBinPath,