@bleedingdev/modern-js-create 3.2.0-ultramodern.12 → 3.2.0-ultramodern.121

package/README.md

@@ -8,117 +8,212 @@
   A Progressive React Framework for modern web development.
 </p>
 
-## Getting Started
+## UltraModern.js Create
 
-Please follow [Quick Start](https://modernjs.dev/en/guides/get-started/quick-start) to get started with Modern.js.
-
-For UltraModern.js, use the BleedingDev create package. It defaults to the
-canonical SuperApp workspace and published BleedingDev package aliases:
+The BleedingDev create package has one supported generated product: an
+UltraModern SuperApp workspace.
 
 ```bash
-pnpm dlx @bleedingdev/modern-js-create my-super-app
+pnpm dlx @bleedingdev/modern-js-create my-workspace
 ```
 
-### Router Template
+The supported pnpm command contract is the scoped package specifier above:
+`pnpm dlx @bleedingdev/modern-js-create <target>`. Do not shorten it to
+`pnpm dlx modern-js-create`; there is no unscoped `modern-js-create` npm
+package. Release proof runs this scoped form from a temporary pnpm store/cache
+so it cannot pass because of a local link cache.
 
-You can scaffold a TanStack Router first template:
+To initialize the empty directory you are already in, pass `.` explicitly:
 
 ```bash
-npx @modern-js/create my-app --router tanstack
+pnpm dlx @bleedingdev/modern-js-create .
 ```
 
-### Tailwind Template
+The workspace starts shell-only so the first commit has no fake business
+domains to delete. It generates:
 
-You can scaffold Tailwind CSS v4 setup (PostCSS + starter utility classes):
+- `apps/shell-super-app` as the Module Federation host and topology owner.
+- `verticals/*` empty until a real domain is added with `--vertical`.
+- `packages/shared-*` placeholders for shared contracts, tokens, and Effect
+  API support.
+- `.modernjs/ultramodern-generated-contract.json` with Module Federation,
+  Effect, i18n, federated CSS, Cloudflare, route publicness, generated
+  public-surface, and Zephyr dependency metadata.
 
-```bash
-npx @modern-js/create my-app --tailwind
-```
-
-You can combine both options:
+Validate the generated workspace before making application changes:
 
 ```bash
-npx @modern-js/create my-app --router tanstack --tailwind
+cd my-workspace
+mise install
+pnpm install
+pnpm check
+pnpm build
 ```
 
-### BFF Runtime Template
+The generated toolchain baseline is Node `>=26` with pnpm `11.5.3`.
+`packageManager`, `.mise.toml`, generated validation, and CI should all agree
+on that baseline; do not reintroduce Corepack or older pnpm aliases.
 
-You can scaffold BFF APIs with the current default runtime:
+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. Generated
+lefthook config runs separate format and lint-fix commands on pre-commit, then
+runs the read-only primitive gates in parallel on pre-push.
 
-```bash
-npx @modern-js/create my-app --bff
-```
-
-You can explicitly scaffold Effect HttpApi runtime for BFF:
+For local monorepo dependency testing, add `--workspace`:
 
 ```bash
-npx @modern-js/create my-app --bff-runtime effect
+pnpm dlx @bleedingdev/modern-js-create my-workspace --workspace
 ```
 
-To scaffold Hono runtime explicitly:
-
-```bash
-npx @modern-js/create my-app --bff-runtime hono
-```
+For package-source validation outside the monorepo, pass explicit
+`--ultramodern-package-*` options.
 
-Generated starters expose `presetUltramodern(...)` as the public opinionated
-config wrapper when you want the full Ultramodern setup surface in
-`modern.config.ts`.
+## Vertical Workspace Recipes
 
-You can combine TanStack Router + Tailwind + Effect BFF in one command:
+Use the workspace add flow from the UltraModern workspace root. It derives the
+package path, package name, port, Module Federation name, topology entry, local
+overlay, ownership entry, Effect BFF surface, and root `dev:*` script from the
+requested vertical name.
 
 ```bash
-npx @modern-js/create my-app --router tanstack --tailwind --bff-runtime effect
+pnpm dlx @bleedingdev/modern-js-create catalog --vertical
 ```
 
-### Micro Vertical Workspace Recipes
-
-Use the existing create flags to scaffold packages inside a Micro Vertical
-workspace. The shell and remotes use TanStack Router; services use Effect by
-default, with Hono kept as an explicit compatibility lane.
+Use this decision table before adding a vertical:
+
+| Need | Keep inside current vertical | Create a new vertical |
+| --- | --- | --- |
+| Route or widget changes with the same product owner, release train, and fallback behavior | Yes | No |
+| Route subtree needs independent rollout, rollback, or incident ownership | No | `--vertical` |
+| UI and Effect BFF must version, deploy, and roll back together | No | `--vertical` |
+| Design tokens, primitives, generated clients, or domain-neutral utilities | Yes | Use an ordinary workspace package, not a vertical |
+| Feature composites or workflow state shared across verticals | No | Revisit ownership; do not hide it in shared code |
+
+## SuperApp Architecture Contracts
+
+The generated shell owns route assembly and policy. Each vertical added with
+`--vertical` owns its route subtree, Module Federation exposes, Effect BFF
+contract, generated client, `localisedUrls`, locale JSON, CSS layer, and
+Cloudflare Worker output. The shell consumes vertical UI through Module
+Federation manifests and vertical APIs through generated Effect clients
+exported by the vertical packages.
+
+Route metadata is route-owned and colocated in
+`src/routes/**/route.meta.ts`. The scaffold regenerates
+`src/routes/ultramodern-route-metadata.ts` as a compatibility manifest for
+Modern.js config, i18n, public head, and public surface contracts; authors
+should not hand-maintain it. Locale JSON is served from
+`/locales/{{lng}}/{{ns}}.json`; Czech and English routes are generated from the
+route owner, not from shell rewrites.
+
+Routes default to `privateByDefault: true` and
+`publicnessDefault: private-app-screen`. Public web artifacts are build/deploy
+outputs generated by `scripts/generate-public-surface-assets.mjs` into
+`dist/public` and `.output/public`, not source files under `config/public`.
+Generated public files use only explicit `public && indexable` route metadata,
+so private app screens publish only a disallowing `robots.txt` by default.
+JSON-LD is not inferred from route titles, descriptions, localized paths, app
+names, BFF APIs, or Module Federation metadata. To publish structured data,
+author `jsonLd` explicitly in route metadata for a `public && indexable` route;
+generated apps provide `src/routes/ultramodern-jsonld.ts` helpers for
+`WebPage`, `WebApplication`, `SoftwareApplication`, `BreadcrumbList`,
+`FAQPage`, and `Organization`, while raw JSON-LD remains possible for other
+schema types.
+
+Dynamic public routes can expand sitemap entries through route-owned,
+Node-safe ESM providers, normally `route.sitemap.mjs` beside the 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. Providers may export
+`entries`, `entries()`, or a default entries/loader returning sitemap entries;
+draft entries and `indexable: false` entries are omitted.
+
+CSS federation is explicit:
+
+- `packages/shared-design-tokens` exports `./tokens.css` and owns
+  `ultramodern-shared-tokens`.
+- The shell owns shell base and overlay CSS only.
+- Verticals own their vertical CSS layer and `[data-app-id="<vertical>"]`
+  root marker.
+- Tailwind CSS v4 is configured per app through `@tailwindcss/postcss`.
+- Duplicate base styles are forbidden; SSR first paint depends on shared token
+  CSS plus Modern/Rspack-emitted app CSS.
+
+## Public URL Environment Variables
+
+Generated 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 workspaces.
+
+| 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 |
+
+Asset URLs use this precedence: `MODERN_ASSET_PREFIX` →
+`ULTRAMODERN_ASSET_PREFIX` → origin-relative `/`. `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, asset paths are origin-relative (`/`), and the
+dev server uses `dev.assetPrefix: '/'` — so apps work through tunnels and
+reverse proxies (ngrok, cloudflared) without triggering Chrome's Local Network
+Access prompt or mixed-content errors. Shell-only workspaces can set
+`MODERN_PUBLIC_SITE_URL` for SEO output without changing where assets load
+from.
+
+## Cloudflare And Zephyr Proof
+
+Each generated workspace app has:
+
+- `cloudflare:build`, `cloudflare:deploy`, `cloudflare:preview`, and
+  `cloudflare:proof` scripts.
+- Cloudflare metadata in `.modernjs/ultramodern-generated-contract.json`.
+- `zephyr:dependencies` for any consumed verticals.
+- `zephyr-rspack-plugin` wired through the generated Modern.js Rspack bridge.
+
+Deploy first, 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
+Cloudflare Worker surface, including public-route sitemap/robots consistency,
+preview noindex behavior, unknown-route status, asset headers, byte budgets,
+and public sourcemap exposure. Shell-only workspaces only need the shell URL;
+added verticals use the same `ULTRAMODERN_PUBLIC_URL_<APP_ID>` pattern with
+hyphens converted to underscores and uppercased:
 
 ```bash
-npx @modern-js/create apps/shell --router tanstack --tailwind --workspace --sub
-npx @modern-js/create apps/remotes/catalog --router tanstack --tailwind --workspace --sub
-npx @modern-js/create apps/remotes/design-system --router tanstack --tailwind --workspace --sub
-npx @modern-js/create services/catalog-api --bff-runtime effect --workspace --sub
-npx @modern-js/create services/legacy-api --bff-runtime hono --workspace --sub
+pnpm cloudflare:deploy
+ULTRAMODERN_PUBLIC_URL_SHELL_SUPER_APP=https://shell-super-app.example.workers.dev \
+ULTRAMODERN_PUBLIC_URL_TRANSPORTATION=https://transportation.example.workers.dev \
+pnpm cloudflare:proof -- --require-public-urls
 ```
 
-When a design system needs independent deployment, treat it as a horizontal
-Module Federation remote with the same topology, trust, SSR, compatibility, and
-fallback expectations as feature remotes. Otherwise shared packages should be
-regular workspace packages for tokens, primitives, generated clients, or
-domain-neutral utilities. Keep feature composites and workflow logic owned by a
-shell, remote, or service package.
-
-See
-`docs/super-app-rfc-adr/WORKSPACE-0001-micro-vertical-workspace-scaffolding.md`
-for the canonical workspace topology and local orchestration model.
+Without public URLs and credentials, use local primitive gates and `pnpm build`
+evidence only; do not claim live Cloudflare or Zephyr selection has been
+proven.
 
-The published `@bleedingdev/modern-js-create` package is the preferred
-UltraModern.js entrypoint. The lower-level `--ultramodern-*` flags remain
-available for release engineering and local package-source testing, but users
-should not need them for normal app creation.
+## Troubleshooting
 
-### Local Monorepo Testing
+| 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 |
+| 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 env key from `.modernjs/ultramodern-generated-contract.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 |
 
-When testing unreleased Modern.js packages from a local monorepo checkout, use
-workspace protocol dependencies:
-
-```bash
-npx @modern-js/create my-app --router tanstack --bff-runtime effect --workspace
-```
-
-## Documentation
+## Modern.js Documentation
 
 - [English Documentation](https://modernjs.dev/en/)
 - [中文文档](https://modernjs.dev)
 
-## Contributing
-
-Please read the [Contributing Guide](https://github.com/web-infra-dev/modern.js/blob/main/CONTRIBUTING.md).
-
 ## License
 
 Modern.js is [MIT licensed](https://github.com/web-infra-dev/modern.js/blob/main/LICENSE).

package/dist/cjs/create-package-root.cjs

@@ -0,0 +1,63 @@
+"use strict";
+var __webpack_require__ = {};
+(()=>{
+    __webpack_require__.n = (module)=>{
+        var getter = module && module.__esModule ? ()=>module['default'] : ()=>module;
+        __webpack_require__.d(getter, {
+            a: getter
+        });
+        return getter;
+    };
+})();
+(()=>{
+    __webpack_require__.d = (exports1, getters, values)=>{
+        var define = (defs, kind)=>{
+            for(var key in defs)if (__webpack_require__.o(defs, key) && !__webpack_require__.o(exports1, key)) Object.defineProperty(exports1, key, {
+                enumerable: true,
+                [kind]: defs[key]
+            });
+        };
+        define(getters, "get");
+        define(values, "value");
+    };
+})();
+(()=>{
+    __webpack_require__.o = (obj, prop)=>Object.prototype.hasOwnProperty.call(obj, prop);
+})();
+(()=>{
+    __webpack_require__.r = (exports1)=>{
+        if ("u" > typeof Symbol && Symbol.toStringTag) Object.defineProperty(exports1, Symbol.toStringTag, {
+            value: 'Module'
+        });
+        Object.defineProperty(exports1, '__esModule', {
+            value: true
+        });
+    };
+})();
+var __webpack_exports__ = {};
+__webpack_require__.r(__webpack_exports__);
+__webpack_require__.d(__webpack_exports__, {
+    resolveCreatePackageRoot: ()=>resolveCreatePackageRoot
+});
+const external_node_fs_namespaceObject = require("node:fs");
+var external_node_fs_default = /*#__PURE__*/ __webpack_require__.n(external_node_fs_namespaceObject);
+const external_node_path_namespaceObject = require("node:path");
+var external_node_path_default = /*#__PURE__*/ __webpack_require__.n(external_node_path_namespaceObject);
+const MAX_WALK_UP_LEVELS = 5;
+function resolveCreatePackageRoot(fromDir) {
+    let candidate = fromDir;
+    for(let level = 0; level <= MAX_WALK_UP_LEVELS; level++){
+        if (external_node_fs_default().existsSync(external_node_path_default().join(candidate, 'package.json')) && external_node_fs_default().existsSync(external_node_path_default().join(candidate, 'template-workspace'))) return candidate;
+        const parent = external_node_path_default().dirname(candidate);
+        if (parent === candidate) break;
+        candidate = parent;
+    }
+    throw new Error(`Unable to resolve the @modern-js/create package root (a directory containing both package.json and template-workspace/) within ${MAX_WALK_UP_LEVELS} levels above ${fromDir}`);
+}
+exports.resolveCreatePackageRoot = __webpack_exports__.resolveCreatePackageRoot;
+for(var __rspack_i in __webpack_exports__)if (-1 === [
+    "resolveCreatePackageRoot"
+].indexOf(__rspack_i)) exports[__rspack_i] = __webpack_exports__[__rspack_i];
+Object.defineProperty(exports, '__esModule', {
+    value: true
+});