@webjsdev/cli 0.10.49 → 0.10.51

package/lib/create.js

@@ -18,6 +18,7 @@ import { existsSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { spawnSync } from 'node:child_process';
 import { bunifyProse, bunifyDockerfile, bunifyCompose, bunifyCi } from './runtime-rewrite.js';
+import { assertValidAppName } from './app-name.js';
 
 /**
  * Detect which package manager invoked us. Reads `npm_config_user_agent`,
@@ -166,8 +167,11 @@ async function writeUiBootstrap(appDir) {
   );
   await writeFile(join(appDir, 'lib', 'utils', 'dom.ts'), domContent);
 
-  // 2) components.json: the same shape `webjsui init` writes for webjs
-  // projects (see packages/ui/src/utils/detect-project.js). The utils alias
+  // 2) components.json: byte for byte what `webjsui init` writes (see the
+  // DEFAULT_ALIASES / DEFAULT_TAILWIND_CSS constants in
+  // packages/ui/src/commands/init.js, which #1129 made the single source of
+  // these values). Keep the two in step: an app that scaffolds and one that
+  // runs `webjs ui init` must end up with the same config. The utils alias
   // is lib/utils/cn so get-config.js's `+ '.ts'` resolves to lib/utils/cn.ts.
   // The theme CSS lives at styles/globals.css, NOT app/globals.css: app/ is
   // routing-only, so a non-routing stylesheet does not belong there.
@@ -255,9 +259,15 @@ function assertUiRegistryAvailable() {
  * @param {string} cwd   Current working directory
  */
 export async function scaffoldApp(name, cwd, opts = {}) {
+  // Defence in depth, same as the template check below. `webjs create` already
+  // validates the name, but a programmatic caller can pass anything, and the
+  // name is interpolated into generated source as a template-literal value
+  // (#1066), so an unvalidated quote / backtick / `${` would emit a file that
+  // fails to parse. Throwing here happens before any directory is created.
+  assertValidAppName(name);
   const template = opts.template || 'full-stack';
-  // A human-friendly display title for the example home page. The npm `name`
-  // stays the raw slug (lowercase, hyphenated), but showing a hyphenated slug as
+  // A human-friendly display title for the example home page. The package
+  // `name` stays the raw slug as typed, but showing a hyphenated slug as
   // a hero title looks unpolished, so title-case it for display ("my-app" ->
   // "My App"). Replace this with your real brand anyway.
   const displayName = name.replace(/[-_]+/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase());
@@ -388,10 +398,12 @@ export async function scaffoldApp(name, cwd, opts = {}) {
       'test:browser': 'webjs test --browser',
       check: 'webjs check',
       typecheck: 'webjs typecheck',
-      // Onboarding/setup-verify: a contributor runs `npm run doctor` after
-      // cloning to assert the toolchain (Node floor, tsconfig flag, env drift,
-      // vendor pins, @webjsdev versions, git hook). Local tool, NOT a CI gate
-      // (its env-drift + network pin-freshness checks would make CI flaky).
+      // Project health: a contributor runs `npm run doctor` after cloning to
+      // assert the toolchain (Node floor, tsconfig flag, env drift, vendor
+      // pins, @webjsdev versions, git hook), and CI runs the same script. Which
+      // findings are FATAL comes from the `webjs.doctor.gate` block below, so
+      // the environment-shaped checks (env drift, pin freshness over the
+      // network, the git hook) stay warns and cannot make CI flaky.
       doctor: 'webjs doctor',
       'db:generate': 'webjs db generate',
       'db:migrate': 'webjs db migrate',
@@ -481,6 +493,17 @@ export async function scaffoldApp(name, cwd, opts = {}) {
         }),
       },
       start: { before: isApi ? ['webjs db migrate'] : ['webjs db migrate', cssBuildCmd] },
+      // Which doctor findings are FATAL is the app's own call (#1257), declared
+      // here rather than in the CI workflow so `npm run doctor` locally and the
+      // workflow step agree about what fails. UNMARKED_ASSET_LINKS starts at
+      // error because an un-versioned /public url is a real deploy-staleness
+      // bug (it shipped a visible regression on webjs.dev) and the generated
+      // layout already writes asset(), so a fresh app is green on day one.
+      // Two checks are fatal with no entry here at all, NODE_VERSION and
+      // TSCONFIG_ERASABLE, because either would 500 the app at runtime;
+      // everything else keeps its default warn. Add a code with "off" to
+      // silence it, or "error" to make it fatal too.
+      doctor: { gate: { UNMARKED_ASSET_LINKS: 'error' } },
     },
   }, null, 2) + '\n');
 
@@ -947,10 +970,13 @@ export default cors({
 
 // A GET server action (#488): a read declares its HTTP semantics via reserved
 // sibling exports the framework reads statically. 'method' makes the call ride
-// the URL (cacheable, ETag/304-aware, SSR-seeded on first paint); 'cache' is the
-// max-age in seconds (private by default, do NOT add { public: true } unless the
-// data is identical for EVERY visitor); 'tags' label the cached entry so a
-// mutation can evict it. One function per file.
+// the URL and be ETag/304-aware; 'cache' is what makes the response cacheable at
+// all (the max-age in seconds, private by default, do NOT add { public: true }
+// unless the data is identical for EVERY visitor); 'tags' label the cached entry so a
+// mutation can evict it. All three shape the RPC endpoint a browser import hits,
+// so they do nothing for the in-process call in app/api/users/route.ts; they are
+// here as the idiom to carry into a client that imports the action. One function
+// per file.
 export const method = 'GET';
 export const cache = 30;
 export const tags = () => ['users'];
@@ -966,8 +992,12 @@ export async function listUsers() {
 
 // A mutation server action (#488). With no 'method' export it defaults to POST
 // (CSRF-protected, rich request body). 'invalidates' lists the cache tags to
-// evict on success, so the next listUsers() read refetches fresh instead of
-// serving a stale browser-cached value. One function per file.
+// evict once the action completes without throwing, so a client that read
+// listUsers() refetches fresh instead of serving a stale browser-cached value.
+// (A returned { success: false } envelope still evicts, since the action ran.)
+// It applies on the RPC endpoint a browser import hits. The route.ts in this
+// template calls the function directly, which is in-process, so the config
+// exports do not fire there. One function per file.
 export const invalidates = () => ['users'];
 export async function createUser(input: { name: string; email: string }) {
   // TODO: validate input, persist to database
@@ -977,6 +1007,13 @@ export async function createUser(input: { name: string; email: string }) {
     await writeFile(join(appDir, 'app', 'api', 'users', 'route.ts'), `/**
  * /api/users: thin route wrapper over typed server actions.
  * Business logic lives in modules/users/, not here.
+ *
+ * These calls are in-process, so the actions' config exports do NOT apply here.
+ * method / cache / tags / invalidates shape the RPC endpoint a browser import
+ * hits, and nothing else applies them, so this endpoint sets its own headers if
+ * it wants caching. The namespace form of the route() adapter from
+ * \@webjsdev/server (import * as q; export const GET = route(q)) picks up the
+ * declared validate and middleware, which are the two an endpoint can reuse.
  */
 import { listUsers } from '#modules/users/queries/list-users.server.ts';
 import { createUser } from '#modules/users/actions/create-user.server.ts';
@@ -1134,7 +1171,8 @@ ${uiThemeRaw}
     // or shed the whole gallery at once with `gallery:clear`.
     await copyGallery(appDir);
 
-  await writeFile(join(appDir, 'app', 'layout.ts'), `import { html, cspNonce } from '@webjsdev/core';
+  await writeFile(join(appDir, 'app', 'layout.ts'), `import { html, cspNonce, asset } from '@webjsdev/core';
+import type { LayoutProps } from '@webjsdev/core';
 import '#components/theme-toggle.ts';
 
 /**
@@ -1153,7 +1191,11 @@ import '#components/theme-toggle.ts';
 // lives at public/favicon.svg and serves at /public/favicon.svg.
 export const metadata = { icons: '/public/favicon.svg' };
 
-export default function RootLayout({ children }: { children: unknown }) {
+// LayoutProps types every layout argument (children, params, searchParams,
+// url) from the framework, so children is a TemplateResult rather than an
+// untyped value. Derive types like this everywhere instead of widening to
+// unknown; see .agents/skills/webjs/references/typescript.md.
+export default function RootLayout({ children }: LayoutProps) {
   // Read the in-flight request's CSP nonce so the theme-detection inline script
   // passes strict CSP. Returns '' when no CSP nonce is set.
   const nonce = cspNonce();
@@ -1212,9 +1254,16 @@ export default function RootLayout({ children }: { children: unknown }) {
          public/tailwind.css by css:build (run automatically by the dev and start
          tasks; in dev it is also recompiled on request when a source changes, so
          it never goes stale). A real stylesheet, so the app is fully styled with
-         JavaScript DISABLED (no in-browser compile). -->
+         JavaScript DISABLED (no in-browser compile).
+
+         asset() adds a content hash in production (/public/tailwind.css?v=...)
+         and the framework then serves it immutable for a year, so a deploy that
+         changes the CSS changes the url and no browser or CDN can serve the old
+         bytes. Mark the thing that FETCHES: do not wrap a <link rel="preload">
+         whose asset is really fetched by an @font-face url() in the CSS, or the
+         preload can never match the request and the file downloads twice. -->
 
-    <link rel="stylesheet" href="/public/tailwind.css">
+    <link rel="stylesheet" href=\${asset('/public/tailwind.css')}>
     <style>
       /* Design tokens: ONE definition per colour via light-dark(LIGHT, DARK), so
          a palette change lands in a single place (DRY). The token NAMES are