diff --git a/app/docs.test.ts b/app/docs.test.ts index 149a713c..1f249e0b 100644 --- a/app/docs.test.ts +++ b/app/docs.test.ts @@ -184,8 +184,16 @@ test("portal exposes truthful access and machine discovery", () => { expect(llms).toContain("- @wrnexus/helpers"); expect(llms).toContain("redirectToLogin"); expect(llms).toContain("https://component.wrnexusjs.dev/"); + expect(llms).toContain("# Complete CLI command reference"); + expect(llms).toContain("wrnexus production [workspace-dir]"); + expect(llms).toContain("wrnexus compatibility "); + expect(llms).toContain("wrnexus inspect component "); + expect(llms).toContain("## CLI workflows with expected output"); + expect(llms).toContain("✓ Application types are valid"); const llmsFull = readFileSync(join(root, "public", "llms-full.txt"), "utf8"); expect(llmsFull).toContain("# Installed package documentation"); + expect(llmsFull).toContain("# Complete CLI command reference"); + expect(llmsFull).toContain(`@wrnexus/cli@${frameworkVersion}`); expect(llmsFull).toContain("# Complete @wrnexus/ui component reference and source contracts"); expect(llmsFull).toContain("### Complete .wrn source contract"); }); diff --git a/public/llms-full.txt b/public/llms-full.txt index 8f8cc667..0e155920 100644 --- a/public/llms-full.txt +++ b/public/llms-full.txt @@ -259,17 +259,7 @@ export const POST = async (ctx) => { ## CLI -``` -wrnexus dev . # dev server + HMR -wrnexus build . # production build → dist/server.js -bun dist/server.js # run the production server (or npm start) -wrnexus create # scaffold a new app -wrnexus update --latest # deps + syntax/config migrations + verification -wrnexus generate page # scaffold a page (aliases: g p) -wrnexus generate component | api | schema -wrnexus db migrate | rollback | status | new [--from-models] | generate | seed -wrnexus eject # copy a Wire UI component's .wrn into app/components to customize -``` +See the generated **Complete CLI command reference** below. It is sourced from the installed 0.8.7 executable so command names and options cannot drift. ## When asked to "create a page/component/feature" @@ -279,8 +269,430 @@ wrnexus eject # copy a Wire UI component's .wrn into app/compone 4. Style with Tailwind utility classes in the view, or theme tokens (`var(--wire-*)`), or `style { }`. 5. Never emit React/JSX, a manual router, or client-side island JS — the framework handles hydration. +# Complete CLI command reference + +This section is generated from the installed `@wrnexus/cli@0.8.7` executable. It is the canonical command inventory for this release. + +```text +wrnexus — WrNexus CLI + +Usage: + wrnexus dev [app-dir] [--port=3000] [--host=::] + Start the development server (live reload) + wrnexus dev [app-dir] --services Start local production-service simulators with the app + wrnexus dev [app-dir] --production-runtime + wrnexus dev [app-dir] --services [--services-port=3099] [--services-http] + Rebuild and reload the exact production artifact + wrnexus build [app-dir] Build a production server bundle + assets + wrnexus preview [app-dir] Serve the existing exact production output + wrnexus create Scaffold a new app + wrnexus workspace Scaffold a monorepo (apps/* + shared packages/*) + wrnexus workspace add [--domain=name.localhost] + Add an app to the current workspace + wrnexus gateway [--port=3000] Serve every workspace app behind one port, routed by domain + wrnexus production [workspace-dir] Build, migrate, and serve the complete production workspace + wrnexus [workspace-dir] Run a configured workspace environment (development/staging/custom) + wrnexus generate Scaffold a page | component | api | schema + wrnexus generate routes | docker | mobile + Generate routes or scaffold deployment targets + wrnexus generate types [app-dir] Generate application-wide route/component/key types + wrnexus routes [app-dir] Generate typed named routes + wrnexus typecheck [app-dir] Generate types and check TypeScript plus every .wrn file + wrnexus mobile add Install Capacitor or Expo native packages + wrnexus mobile compile Compile .wrn pages into native Expo routes + wrnexus native list List cross-platform native capabilities + wrnexus native add Install capability packages for the configured mobile mode + wrnexus eject Copy a Wire UI component into app/components + wrnexus update [dir] [--latest] Upgrade deps, migrate project files, and verify the app + wrnexus db Migrations: migrate | rollback | status | seed | generate | new + wrnexus authz Authorization: list | generate | init [--dialect=sqlite|postgres|mysql] + wrnexus test [level] [app-dir] [--watch] + Run unit | component | api | browser | visual | accessibility | performance + wrnexus profiles [app-dir] List config profiles (dev/prod/uat/…) and their env files + wrnexus doctor [app-dir] [--fix] Check project health; optionally apply safe repairs + wrnexus compatibility [app-dir] + Inspect or explicitly upgrade behavior defaults + wrnexus contracts [app-dir] + Detect breaking boundary contract changes + wrnexus security [app-dir] + Audit ASVS controls, inspect headers, or run abuse tests + wrnexus api [app-dir] Generate OpenAPI, docs, Postman, examples and SDKs + wrnexus sdk generate [app-dir] + Generate TypeScript, JavaScript, Java, Go, or Python SDK + wrnexus deploy [app-dir] Generate docker | kubernetes | systemd | railway | render | fly + wrnexus mcp [app-dir] Start the WRNexus MCP server over stdio + wrnexus i18n [app-dir] + Extract and audit translation keys + wrnexus report [app-dir] [--file=app/pages/page.wrn] + Create a sanitized reproduction bundle + wrnexus playground [--port=4173] Start the shareable WRN compiler playground + wrnexus config [app-dir] --explain Print the fully resolved profile configuration + wrnexus analyze [app-dir] Inspect dist/build-report.json and performance budgets + wrnexus explain [subject] [app-dir] + Explain compiler and production build decisions + wrnexus explain [app-dir] + Explain route caching or permission enforcement + wrnexus inspect [app-dir] Inspect packages | plugins | routes | assets | runtimes | styles | migrations | bundle + wrnexus inspect component [app-dir] + Inspect a component's typed public contract + wrnexus generate system Scaffold a complete framework-native package + +Profiles: pass --profile= to dev/build/db (or set WRNEXUS_PROFILE) to load +that profile's .env cascade and config overrides. e.g. wrnexus dev --profile=uat + +Workspace environments: configure protocol, rootDomain, port, hostname, runtime +(development|production), hmr, build, migrate, and profile in wrnexus.workspace.ts. +CLI overrides: --port, --host, --build/--no-build, --migrate/--no-migrate, +--profile, and --prepare-only. + +Update options: --dry-run previews changes; --no-verify skips post-update check/build. +``` + +## CLI workflows with expected output + +Commands below are copy-ready. Paths, ports, counts, and timings vary by project; the shown output identifies the success condition to check. + +### Create, check, build, and preview an application + +```bash +bunx @wrnexus/cli@0.8.7 create my-app +cd my-app +bun install +bunx wrnexus typecheck . +bunx wrnexus build . +bunx wrnexus preview . --port=3000 +``` + +Expected output: + +```text +✓ Application types are valid +✓ Runtime: .../dist/reactive.js +✓ Styles: .../dist/styles.css +✓ Server: .../dist/server.js +Run it: bun .../dist/server.js +``` + +### Generate framework files and committed application types + +```bash +bunx wrnexus generate page Dashboard +bunx wrnexus generate component status-card +bunx wrnexus generate api health +bunx wrnexus generate schema account +bunx wrnexus generate routes +bunx wrnexus generate types . +``` + +Expected output includes created source paths followed by: + +```text +✓ Generated app/routes.gen.ts (... routes) +✓ Generated .../app/types/wrnexus.generated.d.ts (... routes, ... components) +``` + +### Run development and production-runtime modes + +```bash +bunx wrnexus dev . --port=3000 +bunx wrnexus dev . --services --services-port=3099 +bunx wrnexus dev . --production-runtime --port=3000 +``` + +Expected output reports the active profile, discovered plugins/routes, generated cache path, and listening URL. Production-runtime mode rebuilds and reloads the exact production artifact. + +### Database lifecycle + +```bash +bunx wrnexus db status +bunx wrnexus db new create_accounts --from-models +bunx wrnexus db migrate +bunx wrnexus db generate +bunx wrnexus db seed +``` + +Expected output identifies the selected profile/dialect, migration state, applied migration names, and generated typed query files. Run `db rollback` only when intentionally reverting the latest migration. + +### Diagnose, inspect, and enforce contracts + +```bash +bunx wrnexus doctor . +bunx wrnexus typecheck . +bunx wrnexus compatibility check . +bunx wrnexus contracts check . +bunx wrnexus security audit . +bunx wrnexus inspect packages . +bunx wrnexus inspect routes . +bunx wrnexus inspect component Navbar . +bunx wrnexus analyze . +``` + +Successful checks exit with status 0. Inspect commands print the resolved package, route, component, asset, runtime, style, migration, or bundle contract without changing the application. + +### Tests, API artifacts, SDKs, and deployment manifests + +```bash +bunx wrnexus test unit . +bunx wrnexus test component . +bunx wrnexus test api . +bunx wrnexus test browser . +bunx wrnexus api generate . +bunx wrnexus api docs . +bunx wrnexus sdk generate typescript . +bunx wrnexus deploy docker . +``` + +Test commands return the underlying suite summary and a nonzero status on failure. API/SDK/deploy commands report each generated artifact; review and commit generated files after validation. + +### Workspaces and environments + +```bash +bunx wrnexus workspace company-platform +cd company-platform +bunx wrnexus workspace add reports --domain=reports.localhost +bunx wrnexus gateway --port=3000 +bunx wrnexus production . --prepare-only +bunx wrnexus staging . +``` + +Expected output lists created apps, domain mappings, selected environment/profile, build and migration decisions, and the gateway address. + +### Internationalization, native targets, MCP, and support bundles + +```bash +bunx wrnexus i18n extract . +bunx wrnexus i18n validate . +bunx wrnexus generate mobile +bunx wrnexus mobile compile +bunx wrnexus native list +bunx wrnexus mcp . +bunx wrnexus report . --file=app/pages/index.wrn +``` + +Expected output identifies extracted/validated translation keys, generated native routes, available capabilities, MCP stdio startup, or the sanitized reproduction archive. MCP uses stdio, so protocol messages—not a web URL—are its normal runtime output. + +### Safe upgrades + +```bash +bunx wrnexus update . --latest --dry-run +bunx wrnexus update . --latest +``` + +The dry run previews dependency and migration changes. A real update prints the source and target versions, backup directory, each migration action, installation result, and verification result. Commit or back up the application before upgrading. + Release: WRNexusJS 0.8.7 +# Complete CLI command reference + +This section is generated from the installed `@wrnexus/cli@0.8.7` executable. It is the canonical command inventory for this release. + +```text +wrnexus — WrNexus CLI + +Usage: + wrnexus dev [app-dir] [--port=3000] [--host=::] + Start the development server (live reload) + wrnexus dev [app-dir] --services Start local production-service simulators with the app + wrnexus dev [app-dir] --production-runtime + wrnexus dev [app-dir] --services [--services-port=3099] [--services-http] + Rebuild and reload the exact production artifact + wrnexus build [app-dir] Build a production server bundle + assets + wrnexus preview [app-dir] Serve the existing exact production output + wrnexus create Scaffold a new app + wrnexus workspace Scaffold a monorepo (apps/* + shared packages/*) + wrnexus workspace add [--domain=name.localhost] + Add an app to the current workspace + wrnexus gateway [--port=3000] Serve every workspace app behind one port, routed by domain + wrnexus production [workspace-dir] Build, migrate, and serve the complete production workspace + wrnexus [workspace-dir] Run a configured workspace environment (development/staging/custom) + wrnexus generate Scaffold a page | component | api | schema + wrnexus generate routes | docker | mobile + Generate routes or scaffold deployment targets + wrnexus generate types [app-dir] Generate application-wide route/component/key types + wrnexus routes [app-dir] Generate typed named routes + wrnexus typecheck [app-dir] Generate types and check TypeScript plus every .wrn file + wrnexus mobile add Install Capacitor or Expo native packages + wrnexus mobile compile Compile .wrn pages into native Expo routes + wrnexus native list List cross-platform native capabilities + wrnexus native add Install capability packages for the configured mobile mode + wrnexus eject Copy a Wire UI component into app/components + wrnexus update [dir] [--latest] Upgrade deps, migrate project files, and verify the app + wrnexus db Migrations: migrate | rollback | status | seed | generate | new + wrnexus authz Authorization: list | generate | init [--dialect=sqlite|postgres|mysql] + wrnexus test [level] [app-dir] [--watch] + Run unit | component | api | browser | visual | accessibility | performance + wrnexus profiles [app-dir] List config profiles (dev/prod/uat/…) and their env files + wrnexus doctor [app-dir] [--fix] Check project health; optionally apply safe repairs + wrnexus compatibility [app-dir] + Inspect or explicitly upgrade behavior defaults + wrnexus contracts [app-dir] + Detect breaking boundary contract changes + wrnexus security [app-dir] + Audit ASVS controls, inspect headers, or run abuse tests + wrnexus api [app-dir] Generate OpenAPI, docs, Postman, examples and SDKs + wrnexus sdk generate [app-dir] + Generate TypeScript, JavaScript, Java, Go, or Python SDK + wrnexus deploy [app-dir] Generate docker | kubernetes | systemd | railway | render | fly + wrnexus mcp [app-dir] Start the WRNexus MCP server over stdio + wrnexus i18n [app-dir] + Extract and audit translation keys + wrnexus report [app-dir] [--file=app/pages/page.wrn] + Create a sanitized reproduction bundle + wrnexus playground [--port=4173] Start the shareable WRN compiler playground + wrnexus config [app-dir] --explain Print the fully resolved profile configuration + wrnexus analyze [app-dir] Inspect dist/build-report.json and performance budgets + wrnexus explain [subject] [app-dir] + Explain compiler and production build decisions + wrnexus explain [app-dir] + Explain route caching or permission enforcement + wrnexus inspect [app-dir] Inspect packages | plugins | routes | assets | runtimes | styles | migrations | bundle + wrnexus inspect component [app-dir] + Inspect a component's typed public contract + wrnexus generate system Scaffold a complete framework-native package + +Profiles: pass --profile= to dev/build/db (or set WRNEXUS_PROFILE) to load +that profile's .env cascade and config overrides. e.g. wrnexus dev --profile=uat + +Workspace environments: configure protocol, rootDomain, port, hostname, runtime +(development|production), hmr, build, migrate, and profile in wrnexus.workspace.ts. +CLI overrides: --port, --host, --build/--no-build, --migrate/--no-migrate, +--profile, and --prepare-only. + +Update options: --dry-run previews changes; --no-verify skips post-update check/build. +``` + +## CLI workflows with expected output + +Commands below are copy-ready. Paths, ports, counts, and timings vary by project; the shown output identifies the success condition to check. + +### Create, check, build, and preview an application + +```bash +bunx @wrnexus/cli@0.8.7 create my-app +cd my-app +bun install +bunx wrnexus typecheck . +bunx wrnexus build . +bunx wrnexus preview . --port=3000 +``` + +Expected output: + +```text +✓ Application types are valid +✓ Runtime: .../dist/reactive.js +✓ Styles: .../dist/styles.css +✓ Server: .../dist/server.js +Run it: bun .../dist/server.js +``` + +### Generate framework files and committed application types + +```bash +bunx wrnexus generate page Dashboard +bunx wrnexus generate component status-card +bunx wrnexus generate api health +bunx wrnexus generate schema account +bunx wrnexus generate routes +bunx wrnexus generate types . +``` + +Expected output includes created source paths followed by: + +```text +✓ Generated app/routes.gen.ts (... routes) +✓ Generated .../app/types/wrnexus.generated.d.ts (... routes, ... components) +``` + +### Run development and production-runtime modes + +```bash +bunx wrnexus dev . --port=3000 +bunx wrnexus dev . --services --services-port=3099 +bunx wrnexus dev . --production-runtime --port=3000 +``` + +Expected output reports the active profile, discovered plugins/routes, generated cache path, and listening URL. Production-runtime mode rebuilds and reloads the exact production artifact. + +### Database lifecycle + +```bash +bunx wrnexus db status +bunx wrnexus db new create_accounts --from-models +bunx wrnexus db migrate +bunx wrnexus db generate +bunx wrnexus db seed +``` + +Expected output identifies the selected profile/dialect, migration state, applied migration names, and generated typed query files. Run `db rollback` only when intentionally reverting the latest migration. + +### Diagnose, inspect, and enforce contracts + +```bash +bunx wrnexus doctor . +bunx wrnexus typecheck . +bunx wrnexus compatibility check . +bunx wrnexus contracts check . +bunx wrnexus security audit . +bunx wrnexus inspect packages . +bunx wrnexus inspect routes . +bunx wrnexus inspect component Navbar . +bunx wrnexus analyze . +``` + +Successful checks exit with status 0. Inspect commands print the resolved package, route, component, asset, runtime, style, migration, or bundle contract without changing the application. + +### Tests, API artifacts, SDKs, and deployment manifests + +```bash +bunx wrnexus test unit . +bunx wrnexus test component . +bunx wrnexus test api . +bunx wrnexus test browser . +bunx wrnexus api generate . +bunx wrnexus api docs . +bunx wrnexus sdk generate typescript . +bunx wrnexus deploy docker . +``` + +Test commands return the underlying suite summary and a nonzero status on failure. API/SDK/deploy commands report each generated artifact; review and commit generated files after validation. + +### Workspaces and environments + +```bash +bunx wrnexus workspace company-platform +cd company-platform +bunx wrnexus workspace add reports --domain=reports.localhost +bunx wrnexus gateway --port=3000 +bunx wrnexus production . --prepare-only +bunx wrnexus staging . +``` + +Expected output lists created apps, domain mappings, selected environment/profile, build and migration decisions, and the gateway address. + +### Internationalization, native targets, MCP, and support bundles + +```bash +bunx wrnexus i18n extract . +bunx wrnexus i18n validate . +bunx wrnexus generate mobile +bunx wrnexus mobile compile +bunx wrnexus native list +bunx wrnexus mcp . +bunx wrnexus report . --file=app/pages/index.wrn +``` + +Expected output identifies extracted/validated translation keys, generated native routes, available capabilities, MCP stdio startup, or the sanitized reproduction archive. MCP uses stdio, so protocol messages—not a web URL—are its normal runtime output. + +### Safe upgrades + +```bash +bunx wrnexus update . --latest --dry-run +bunx wrnexus update . --latest +``` + +The dry run previews dependency and migration changes. A real update prints the source and target versions, backup directory, each migration action, installation result, and verification result. Commit or back up the application before upgrading. + # Canonical documentation locations - Framework and package documentation: https://wrnexusjs.dev/ diff --git a/public/llms.txt b/public/llms.txt index 006c1042..7a416535 100644 --- a/public/llms.txt +++ b/public/llms.txt @@ -259,17 +259,7 @@ export const POST = async (ctx) => { ## CLI -``` -wrnexus dev . # dev server + HMR -wrnexus build . # production build → dist/server.js -bun dist/server.js # run the production server (or npm start) -wrnexus create # scaffold a new app -wrnexus update --latest # deps + syntax/config migrations + verification -wrnexus generate page # scaffold a page (aliases: g p) -wrnexus generate component | api | schema -wrnexus db migrate | rollback | status | new [--from-models] | generate | seed -wrnexus eject # copy a Wire UI component's .wrn into app/components to customize -``` +See the generated **Complete CLI command reference** below. It is sourced from the installed 0.8.7 executable so command names and options cannot drift. ## When asked to "create a page/component/feature" @@ -279,6 +269,428 @@ wrnexus eject # copy a Wire UI component's .wrn into app/compone 4. Style with Tailwind utility classes in the view, or theme tokens (`var(--wire-*)`), or `style { }`. 5. Never emit React/JSX, a manual router, or client-side island JS — the framework handles hydration. +# Complete CLI command reference + +This section is generated from the installed `@wrnexus/cli@0.8.7` executable. It is the canonical command inventory for this release. + +```text +wrnexus — WrNexus CLI + +Usage: + wrnexus dev [app-dir] [--port=3000] [--host=::] + Start the development server (live reload) + wrnexus dev [app-dir] --services Start local production-service simulators with the app + wrnexus dev [app-dir] --production-runtime + wrnexus dev [app-dir] --services [--services-port=3099] [--services-http] + Rebuild and reload the exact production artifact + wrnexus build [app-dir] Build a production server bundle + assets + wrnexus preview [app-dir] Serve the existing exact production output + wrnexus create Scaffold a new app + wrnexus workspace Scaffold a monorepo (apps/* + shared packages/*) + wrnexus workspace add [--domain=name.localhost] + Add an app to the current workspace + wrnexus gateway [--port=3000] Serve every workspace app behind one port, routed by domain + wrnexus production [workspace-dir] Build, migrate, and serve the complete production workspace + wrnexus [workspace-dir] Run a configured workspace environment (development/staging/custom) + wrnexus generate Scaffold a page | component | api | schema + wrnexus generate routes | docker | mobile + Generate routes or scaffold deployment targets + wrnexus generate types [app-dir] Generate application-wide route/component/key types + wrnexus routes [app-dir] Generate typed named routes + wrnexus typecheck [app-dir] Generate types and check TypeScript plus every .wrn file + wrnexus mobile add Install Capacitor or Expo native packages + wrnexus mobile compile Compile .wrn pages into native Expo routes + wrnexus native list List cross-platform native capabilities + wrnexus native add Install capability packages for the configured mobile mode + wrnexus eject Copy a Wire UI component into app/components + wrnexus update [dir] [--latest] Upgrade deps, migrate project files, and verify the app + wrnexus db Migrations: migrate | rollback | status | seed | generate | new + wrnexus authz Authorization: list | generate | init [--dialect=sqlite|postgres|mysql] + wrnexus test [level] [app-dir] [--watch] + Run unit | component | api | browser | visual | accessibility | performance + wrnexus profiles [app-dir] List config profiles (dev/prod/uat/…) and their env files + wrnexus doctor [app-dir] [--fix] Check project health; optionally apply safe repairs + wrnexus compatibility [app-dir] + Inspect or explicitly upgrade behavior defaults + wrnexus contracts [app-dir] + Detect breaking boundary contract changes + wrnexus security [app-dir] + Audit ASVS controls, inspect headers, or run abuse tests + wrnexus api [app-dir] Generate OpenAPI, docs, Postman, examples and SDKs + wrnexus sdk generate [app-dir] + Generate TypeScript, JavaScript, Java, Go, or Python SDK + wrnexus deploy [app-dir] Generate docker | kubernetes | systemd | railway | render | fly + wrnexus mcp [app-dir] Start the WRNexus MCP server over stdio + wrnexus i18n [app-dir] + Extract and audit translation keys + wrnexus report [app-dir] [--file=app/pages/page.wrn] + Create a sanitized reproduction bundle + wrnexus playground [--port=4173] Start the shareable WRN compiler playground + wrnexus config [app-dir] --explain Print the fully resolved profile configuration + wrnexus analyze [app-dir] Inspect dist/build-report.json and performance budgets + wrnexus explain [subject] [app-dir] + Explain compiler and production build decisions + wrnexus explain [app-dir] + Explain route caching or permission enforcement + wrnexus inspect [app-dir] Inspect packages | plugins | routes | assets | runtimes | styles | migrations | bundle + wrnexus inspect component [app-dir] + Inspect a component's typed public contract + wrnexus generate system Scaffold a complete framework-native package + +Profiles: pass --profile= to dev/build/db (or set WRNEXUS_PROFILE) to load +that profile's .env cascade and config overrides. e.g. wrnexus dev --profile=uat + +Workspace environments: configure protocol, rootDomain, port, hostname, runtime +(development|production), hmr, build, migrate, and profile in wrnexus.workspace.ts. +CLI overrides: --port, --host, --build/--no-build, --migrate/--no-migrate, +--profile, and --prepare-only. + +Update options: --dry-run previews changes; --no-verify skips post-update check/build. +``` + +## CLI workflows with expected output + +Commands below are copy-ready. Paths, ports, counts, and timings vary by project; the shown output identifies the success condition to check. + +### Create, check, build, and preview an application + +```bash +bunx @wrnexus/cli@0.8.7 create my-app +cd my-app +bun install +bunx wrnexus typecheck . +bunx wrnexus build . +bunx wrnexus preview . --port=3000 +``` + +Expected output: + +```text +✓ Application types are valid +✓ Runtime: .../dist/reactive.js +✓ Styles: .../dist/styles.css +✓ Server: .../dist/server.js +Run it: bun .../dist/server.js +``` + +### Generate framework files and committed application types + +```bash +bunx wrnexus generate page Dashboard +bunx wrnexus generate component status-card +bunx wrnexus generate api health +bunx wrnexus generate schema account +bunx wrnexus generate routes +bunx wrnexus generate types . +``` + +Expected output includes created source paths followed by: + +```text +✓ Generated app/routes.gen.ts (... routes) +✓ Generated .../app/types/wrnexus.generated.d.ts (... routes, ... components) +``` + +### Run development and production-runtime modes + +```bash +bunx wrnexus dev . --port=3000 +bunx wrnexus dev . --services --services-port=3099 +bunx wrnexus dev . --production-runtime --port=3000 +``` + +Expected output reports the active profile, discovered plugins/routes, generated cache path, and listening URL. Production-runtime mode rebuilds and reloads the exact production artifact. + +### Database lifecycle + +```bash +bunx wrnexus db status +bunx wrnexus db new create_accounts --from-models +bunx wrnexus db migrate +bunx wrnexus db generate +bunx wrnexus db seed +``` + +Expected output identifies the selected profile/dialect, migration state, applied migration names, and generated typed query files. Run `db rollback` only when intentionally reverting the latest migration. + +### Diagnose, inspect, and enforce contracts + +```bash +bunx wrnexus doctor . +bunx wrnexus typecheck . +bunx wrnexus compatibility check . +bunx wrnexus contracts check . +bunx wrnexus security audit . +bunx wrnexus inspect packages . +bunx wrnexus inspect routes . +bunx wrnexus inspect component Navbar . +bunx wrnexus analyze . +``` + +Successful checks exit with status 0. Inspect commands print the resolved package, route, component, asset, runtime, style, migration, or bundle contract without changing the application. + +### Tests, API artifacts, SDKs, and deployment manifests + +```bash +bunx wrnexus test unit . +bunx wrnexus test component . +bunx wrnexus test api . +bunx wrnexus test browser . +bunx wrnexus api generate . +bunx wrnexus api docs . +bunx wrnexus sdk generate typescript . +bunx wrnexus deploy docker . +``` + +Test commands return the underlying suite summary and a nonzero status on failure. API/SDK/deploy commands report each generated artifact; review and commit generated files after validation. + +### Workspaces and environments + +```bash +bunx wrnexus workspace company-platform +cd company-platform +bunx wrnexus workspace add reports --domain=reports.localhost +bunx wrnexus gateway --port=3000 +bunx wrnexus production . --prepare-only +bunx wrnexus staging . +``` + +Expected output lists created apps, domain mappings, selected environment/profile, build and migration decisions, and the gateway address. + +### Internationalization, native targets, MCP, and support bundles + +```bash +bunx wrnexus i18n extract . +bunx wrnexus i18n validate . +bunx wrnexus generate mobile +bunx wrnexus mobile compile +bunx wrnexus native list +bunx wrnexus mcp . +bunx wrnexus report . --file=app/pages/index.wrn +``` + +Expected output identifies extracted/validated translation keys, generated native routes, available capabilities, MCP stdio startup, or the sanitized reproduction archive. MCP uses stdio, so protocol messages—not a web URL—are its normal runtime output. + +### Safe upgrades + +```bash +bunx wrnexus update . --latest --dry-run +bunx wrnexus update . --latest +``` + +The dry run previews dependency and migration changes. A real update prints the source and target versions, backup directory, each migration action, installation result, and verification result. Commit or back up the application before upgrading. + +# Complete CLI command reference + +This section is generated from the installed `@wrnexus/cli@0.8.7` executable. It is the canonical command inventory for this release. + +```text +wrnexus — WrNexus CLI + +Usage: + wrnexus dev [app-dir] [--port=3000] [--host=::] + Start the development server (live reload) + wrnexus dev [app-dir] --services Start local production-service simulators with the app + wrnexus dev [app-dir] --production-runtime + wrnexus dev [app-dir] --services [--services-port=3099] [--services-http] + Rebuild and reload the exact production artifact + wrnexus build [app-dir] Build a production server bundle + assets + wrnexus preview [app-dir] Serve the existing exact production output + wrnexus create Scaffold a new app + wrnexus workspace Scaffold a monorepo (apps/* + shared packages/*) + wrnexus workspace add [--domain=name.localhost] + Add an app to the current workspace + wrnexus gateway [--port=3000] Serve every workspace app behind one port, routed by domain + wrnexus production [workspace-dir] Build, migrate, and serve the complete production workspace + wrnexus [workspace-dir] Run a configured workspace environment (development/staging/custom) + wrnexus generate Scaffold a page | component | api | schema + wrnexus generate routes | docker | mobile + Generate routes or scaffold deployment targets + wrnexus generate types [app-dir] Generate application-wide route/component/key types + wrnexus routes [app-dir] Generate typed named routes + wrnexus typecheck [app-dir] Generate types and check TypeScript plus every .wrn file + wrnexus mobile add Install Capacitor or Expo native packages + wrnexus mobile compile Compile .wrn pages into native Expo routes + wrnexus native list List cross-platform native capabilities + wrnexus native add Install capability packages for the configured mobile mode + wrnexus eject Copy a Wire UI component into app/components + wrnexus update [dir] [--latest] Upgrade deps, migrate project files, and verify the app + wrnexus db Migrations: migrate | rollback | status | seed | generate | new + wrnexus authz Authorization: list | generate | init [--dialect=sqlite|postgres|mysql] + wrnexus test [level] [app-dir] [--watch] + Run unit | component | api | browser | visual | accessibility | performance + wrnexus profiles [app-dir] List config profiles (dev/prod/uat/…) and their env files + wrnexus doctor [app-dir] [--fix] Check project health; optionally apply safe repairs + wrnexus compatibility [app-dir] + Inspect or explicitly upgrade behavior defaults + wrnexus contracts [app-dir] + Detect breaking boundary contract changes + wrnexus security [app-dir] + Audit ASVS controls, inspect headers, or run abuse tests + wrnexus api [app-dir] Generate OpenAPI, docs, Postman, examples and SDKs + wrnexus sdk generate [app-dir] + Generate TypeScript, JavaScript, Java, Go, or Python SDK + wrnexus deploy [app-dir] Generate docker | kubernetes | systemd | railway | render | fly + wrnexus mcp [app-dir] Start the WRNexus MCP server over stdio + wrnexus i18n [app-dir] + Extract and audit translation keys + wrnexus report [app-dir] [--file=app/pages/page.wrn] + Create a sanitized reproduction bundle + wrnexus playground [--port=4173] Start the shareable WRN compiler playground + wrnexus config [app-dir] --explain Print the fully resolved profile configuration + wrnexus analyze [app-dir] Inspect dist/build-report.json and performance budgets + wrnexus explain [subject] [app-dir] + Explain compiler and production build decisions + wrnexus explain [app-dir] + Explain route caching or permission enforcement + wrnexus inspect [app-dir] Inspect packages | plugins | routes | assets | runtimes | styles | migrations | bundle + wrnexus inspect component [app-dir] + Inspect a component's typed public contract + wrnexus generate system Scaffold a complete framework-native package + +Profiles: pass --profile= to dev/build/db (or set WRNEXUS_PROFILE) to load +that profile's .env cascade and config overrides. e.g. wrnexus dev --profile=uat + +Workspace environments: configure protocol, rootDomain, port, hostname, runtime +(development|production), hmr, build, migrate, and profile in wrnexus.workspace.ts. +CLI overrides: --port, --host, --build/--no-build, --migrate/--no-migrate, +--profile, and --prepare-only. + +Update options: --dry-run previews changes; --no-verify skips post-update check/build. +``` + +## CLI workflows with expected output + +Commands below are copy-ready. Paths, ports, counts, and timings vary by project; the shown output identifies the success condition to check. + +### Create, check, build, and preview an application + +```bash +bunx @wrnexus/cli@0.8.7 create my-app +cd my-app +bun install +bunx wrnexus typecheck . +bunx wrnexus build . +bunx wrnexus preview . --port=3000 +``` + +Expected output: + +```text +✓ Application types are valid +✓ Runtime: .../dist/reactive.js +✓ Styles: .../dist/styles.css +✓ Server: .../dist/server.js +Run it: bun .../dist/server.js +``` + +### Generate framework files and committed application types + +```bash +bunx wrnexus generate page Dashboard +bunx wrnexus generate component status-card +bunx wrnexus generate api health +bunx wrnexus generate schema account +bunx wrnexus generate routes +bunx wrnexus generate types . +``` + +Expected output includes created source paths followed by: + +```text +✓ Generated app/routes.gen.ts (... routes) +✓ Generated .../app/types/wrnexus.generated.d.ts (... routes, ... components) +``` + +### Run development and production-runtime modes + +```bash +bunx wrnexus dev . --port=3000 +bunx wrnexus dev . --services --services-port=3099 +bunx wrnexus dev . --production-runtime --port=3000 +``` + +Expected output reports the active profile, discovered plugins/routes, generated cache path, and listening URL. Production-runtime mode rebuilds and reloads the exact production artifact. + +### Database lifecycle + +```bash +bunx wrnexus db status +bunx wrnexus db new create_accounts --from-models +bunx wrnexus db migrate +bunx wrnexus db generate +bunx wrnexus db seed +``` + +Expected output identifies the selected profile/dialect, migration state, applied migration names, and generated typed query files. Run `db rollback` only when intentionally reverting the latest migration. + +### Diagnose, inspect, and enforce contracts + +```bash +bunx wrnexus doctor . +bunx wrnexus typecheck . +bunx wrnexus compatibility check . +bunx wrnexus contracts check . +bunx wrnexus security audit . +bunx wrnexus inspect packages . +bunx wrnexus inspect routes . +bunx wrnexus inspect component Navbar . +bunx wrnexus analyze . +``` + +Successful checks exit with status 0. Inspect commands print the resolved package, route, component, asset, runtime, style, migration, or bundle contract without changing the application. + +### Tests, API artifacts, SDKs, and deployment manifests + +```bash +bunx wrnexus test unit . +bunx wrnexus test component . +bunx wrnexus test api . +bunx wrnexus test browser . +bunx wrnexus api generate . +bunx wrnexus api docs . +bunx wrnexus sdk generate typescript . +bunx wrnexus deploy docker . +``` + +Test commands return the underlying suite summary and a nonzero status on failure. API/SDK/deploy commands report each generated artifact; review and commit generated files after validation. + +### Workspaces and environments + +```bash +bunx wrnexus workspace company-platform +cd company-platform +bunx wrnexus workspace add reports --domain=reports.localhost +bunx wrnexus gateway --port=3000 +bunx wrnexus production . --prepare-only +bunx wrnexus staging . +``` + +Expected output lists created apps, domain mappings, selected environment/profile, build and migration decisions, and the gateway address. + +### Internationalization, native targets, MCP, and support bundles + +```bash +bunx wrnexus i18n extract . +bunx wrnexus i18n validate . +bunx wrnexus generate mobile +bunx wrnexus mobile compile +bunx wrnexus native list +bunx wrnexus mcp . +bunx wrnexus report . --file=app/pages/index.wrn +``` + +Expected output identifies extracted/validated translation keys, generated native routes, available capabilities, MCP stdio startup, or the sanitized reproduction archive. MCP uses stdio, so protocol messages—not a web URL—are its normal runtime output. + +### Safe upgrades + +```bash +bunx wrnexus update . --latest --dry-run +bunx wrnexus update . --latest +``` + +The dry run previews dependency and migration changes. A real update prints the source and target versions, backup directory, each migration action, installation result, and verification result. Commit or back up the application before upgrading. + # Canonical documentation locations - Framework and package documentation: https://wrnexusjs.dev/ diff --git a/scripts/generate-portal.ts b/scripts/generate-portal.ts index 62507cb1..584b5535 100644 --- a/scripts/generate-portal.ts +++ b/scripts/generate-portal.ts @@ -1,4 +1,5 @@ import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs"; +import { execFileSync } from "node:child_process"; import { join, resolve } from "node:path"; import { format } from "prettier"; @@ -15,6 +16,151 @@ const packageNames = [...Object.keys(pkg.dependencies), ...Object.keys(pkg.devDe .filter((name, index, all) => all.indexOf(name) === index) .sort(); const packageCount = packageNames.length; +const cliEntry = join(root, "node_modules", "@wrnexus", "cli", "dist", "index.js"); +const cliHelp = execFileSync(process.execPath, [cliEntry, "--help"], { + cwd: root, + encoding: "utf8", + env: { ...process.env, WRNEXUS_DISABLE_UPDATE_CHECK: "1" }, +}).trim(); +const cliReference = `# Complete CLI command reference + +This section is generated from the installed \`@wrnexus/cli@${version}\` executable. It is the canonical command inventory for this release. + +\`\`\`text +${cliHelp} +\`\`\` + +## CLI workflows with expected output + +Commands below are copy-ready. Paths, ports, counts, and timings vary by project; the shown output identifies the success condition to check. + +### Create, check, build, and preview an application + +\`\`\`bash +bunx @wrnexus/cli@${version} create my-app +cd my-app +bun install +bunx wrnexus typecheck . +bunx wrnexus build . +bunx wrnexus preview . --port=3000 +\`\`\` + +Expected output: + +\`\`\`text +✓ Application types are valid +✓ Runtime: .../dist/reactive.js +✓ Styles: .../dist/styles.css +✓ Server: .../dist/server.js +Run it: bun .../dist/server.js +\`\`\` + +### Generate framework files and committed application types + +\`\`\`bash +bunx wrnexus generate page Dashboard +bunx wrnexus generate component status-card +bunx wrnexus generate api health +bunx wrnexus generate schema account +bunx wrnexus generate routes +bunx wrnexus generate types . +\`\`\` + +Expected output includes created source paths followed by: + +\`\`\`text +✓ Generated app/routes.gen.ts (... routes) +✓ Generated .../app/types/wrnexus.generated.d.ts (... routes, ... components) +\`\`\` + +### Run development and production-runtime modes + +\`\`\`bash +bunx wrnexus dev . --port=3000 +bunx wrnexus dev . --services --services-port=3099 +bunx wrnexus dev . --production-runtime --port=3000 +\`\`\` + +Expected output reports the active profile, discovered plugins/routes, generated cache path, and listening URL. Production-runtime mode rebuilds and reloads the exact production artifact. + +### Database lifecycle + +\`\`\`bash +bunx wrnexus db status +bunx wrnexus db new create_accounts --from-models +bunx wrnexus db migrate +bunx wrnexus db generate +bunx wrnexus db seed +\`\`\` + +Expected output identifies the selected profile/dialect, migration state, applied migration names, and generated typed query files. Run \`db rollback\` only when intentionally reverting the latest migration. + +### Diagnose, inspect, and enforce contracts + +\`\`\`bash +bunx wrnexus doctor . +bunx wrnexus typecheck . +bunx wrnexus compatibility check . +bunx wrnexus contracts check . +bunx wrnexus security audit . +bunx wrnexus inspect packages . +bunx wrnexus inspect routes . +bunx wrnexus inspect component Navbar . +bunx wrnexus analyze . +\`\`\` + +Successful checks exit with status 0. Inspect commands print the resolved package, route, component, asset, runtime, style, migration, or bundle contract without changing the application. + +### Tests, API artifacts, SDKs, and deployment manifests + +\`\`\`bash +bunx wrnexus test unit . +bunx wrnexus test component . +bunx wrnexus test api . +bunx wrnexus test browser . +bunx wrnexus api generate . +bunx wrnexus api docs . +bunx wrnexus sdk generate typescript . +bunx wrnexus deploy docker . +\`\`\` + +Test commands return the underlying suite summary and a nonzero status on failure. API/SDK/deploy commands report each generated artifact; review and commit generated files after validation. + +### Workspaces and environments + +\`\`\`bash +bunx wrnexus workspace company-platform +cd company-platform +bunx wrnexus workspace add reports --domain=reports.localhost +bunx wrnexus gateway --port=3000 +bunx wrnexus production . --prepare-only +bunx wrnexus staging . +\`\`\` + +Expected output lists created apps, domain mappings, selected environment/profile, build and migration decisions, and the gateway address. + +### Internationalization, native targets, MCP, and support bundles + +\`\`\`bash +bunx wrnexus i18n extract . +bunx wrnexus i18n validate . +bunx wrnexus generate mobile +bunx wrnexus mobile compile +bunx wrnexus native list +bunx wrnexus mcp . +bunx wrnexus report . --file=app/pages/index.wrn +\`\`\` + +Expected output identifies extracted/validated translation keys, generated native routes, available capabilities, MCP stdio startup, or the sanitized reproduction archive. MCP uses stdio, so protocol messages—not a web URL—are its normal runtime output. + +### Safe upgrades + +\`\`\`bash +bunx wrnexus update . --latest --dry-run +bunx wrnexus update . --latest +\`\`\` + +The dry run previews dependency and migration changes. A real update prints the source and target versions, backup directory, each migration action, installation result, and verification result. Commit or back up the application before upgrading.`; const uiReferencePath = join(root, "node_modules", "@wrnexus", "ui", "component-reference.json"); const uiReference = existsSync(uiReferencePath) ? (JSON.parse(readFileSync(uiReferencePath, "utf8")) as { @@ -529,6 +675,10 @@ if (frameworkGuide.startsWith("# WRNexusJS documentation ")) { } else { frameworkGuide = `# WRNexusJS documentation ${version}\n\nStatus: Private Developer Preview. This site documents ${packageCount} release-aligned packages.\n\n${frameworkGuide}`; } +frameworkGuide = frameworkGuide.replace( + /\n## CLI\n[\s\S]*?\n## When asked to "create a page\/component\/feature"/, + `\n## CLI\n\nSee the generated **Complete CLI command reference** below. It is sourced from the installed ${version} executable so command names and options cannot drift.\n\n## When asked to "create a page/component/feature"`, +); const installedPackageDocs = packageNames .map((name) => { const packageRoot = join(root, "node_modules", "@wrnexus", name); @@ -558,11 +708,11 @@ const componentSources = .join("\n\n---\n\n") ?? ""; writeFileSync( join(pub, "llms.txt"), - `${frameworkGuide}\n\n# Canonical documentation locations\n\n- Framework and package documentation: https://wrnexusjs.dev/\n- Interactive UI component showcase and examples: https://component.wrnexusjs.dev/\n- Comprehensive AI reference: https://wrnexusjs.dev/llms-full.txt\n\n# Installed package index\n\n${packageIndex}\n\n# UI component catalog\n\nThe installed @wrnexus/ui ${version} release contains ${uiReference?.count ?? 0} documented components. The contracts below include every mount name, purpose, prop type, required/default status, slot, and event. Interactive examples live only on the dedicated component showcase.\n\n${uiReferenceText}\n`, + `${frameworkGuide}\n\n${cliReference}\n\n# Canonical documentation locations\n\n- Framework and package documentation: https://wrnexusjs.dev/\n- Interactive UI component showcase and examples: https://component.wrnexusjs.dev/\n- Comprehensive AI reference: https://wrnexusjs.dev/llms-full.txt\n\n# Installed package index\n\n${packageIndex}\n\n# UI component catalog\n\nThe installed @wrnexus/ui ${version} release contains ${uiReference?.count ?? 0} documented components. The contracts below include every mount name, purpose, prop type, required/default status, slot, and event. Interactive examples live only on the dedicated component showcase.\n\n${uiReferenceText}\n`, ); writeFileSync( join(pub, "llms-full.txt"), - `${frameworkGuide}\n\nRelease: WRNexusJS ${version}\n\n# Canonical documentation locations\n\n- Framework and package documentation: https://wrnexusjs.dev/\n- Interactive UI component showcase and examples: https://component.wrnexusjs.dev/\n\n${packageMarker}\n\nThe following README files and declarations come from the installed private ${version} release.\n\n${installedPackageDocs}\n\n# Complete @wrnexus/ui component reference and source contracts\n\n${componentSources}\n`, + `${frameworkGuide}\n\nRelease: WRNexusJS ${version}\n\n${cliReference}\n\n# Canonical documentation locations\n\n- Framework and package documentation: https://wrnexusjs.dev/\n- Interactive UI component showcase and examples: https://component.wrnexusjs.dev/\n\n${packageMarker}\n\nThe following README files and declarations come from the installed private ${version} release.\n\n${installedPackageDocs}\n\n# Complete @wrnexus/ui component reference and source contracts\n\n${componentSources}\n`, ); const auditDocs: Record = {