@b9g/shovel 0.2.9 → 0.2.11

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 All notable changes to Shovel will be documented in this file.
 
+## [0.2.9] - 2026-02-20
+
+### Features
+
+- **Dev server Ctrl+O** - Open the dev server URL in the default browser with `Ctrl+O`
+- **Dev server signal handling** - `Ctrl+Z` (suspend), `Ctrl+D` (quit), `Ctrl+\` (quit) now work correctly in raw mode instead of being silently swallowed
+- **Dev server input passthrough** - Typing, Enter, and Backspace now echo to stdout instead of being dropped
+
+### Dependencies
+
+- **`@logtape/logtape`** `^1.2.0` → `^2.0.0` across all packages
+- **`@logtape/file`** `^1.0.0` → `^2.0.0`
+- **`@b9g/filesystem`** `0.2.0` - Version bump
+- **`@b9g/filesystem-s3`** `0.2.0` - Version bump
+
+### Documentation
+
+- **`@b9g/filesystem` README rewritten** - All class names were fabricated in the previous README. Corrected to match actual exports: `MemoryDirectory`, `NodeFSDirectory`, `S3Directory`, `CustomDirectoryStorage`
+- Fixed inaccurate config options in `@b9g/assets` README
+- Fixed `PostMessageCache` constructor signature in `@b9g/cache` README
+- Fixed import paths in `@b9g/oauth2` README (`@b9g/auth` → `@b9g/oauth2`)
+
 ## [0.2.8] - 2026-02-10
 
 ### Bug Fixes

package/bin/create.js

@@ -26,10 +26,16 @@ function parseFlags(args) {
     const arg = args[i];
     if (arg === "--template" && args[i + 1])
       flags.template = args[++i];
+    else if (arg === "--framework" && args[i + 1])
+      flags.framework = args[++i];
     else if (arg === "--typescript")
       flags.typescript = true;
     else if (arg === "--no-typescript")
       flags.typescript = false;
+    else if (arg === "--jsx")
+      flags.jsx = true;
+    else if (arg === "--no-jsx")
+      flags.jsx = false;
     else if (arg === "--platform" && args[i + 1])
       flags.platform = args[++i];
   }
@@ -70,14 +76,11 @@ async function main() {
   }
   let template;
   let uiFramework = "vanilla";
-  if (flags.template === "crank") {
-    template = "static-site";
-    uiFramework = "crank";
-  } else if (flags.template) {
+  if (flags.template) {
     const valid = ["hello-world", "api", "static-site", "full-stack"];
     if (!valid.includes(flags.template)) {
       console.error(
-        `Error: Unknown template "${flags.template}". Valid options: ${valid.join(", ")}, crank`
+        `Error: Unknown template "${flags.template}". Valid options: ${valid.join(", ")}`
       );
       process.exit(1);
     }
@@ -114,38 +117,65 @@ async function main() {
     }
     template = templateResult;
   }
-  if (uiFramework === "vanilla" && (template === "static-site" || template === "full-stack")) {
-    const framework = await select({
-      message: "UI framework:",
-      initialValue: "crank",
-      options: [
-        {
-          value: "alpine",
-          label: "Alpine.js",
-          hint: "Lightweight reactivity with x-data directives"
-        },
-        {
-          value: "crank",
-          label: "Crank.js",
-          hint: "JSX components rendered on the server"
-        },
-        {
-          value: "htmx",
-          label: "HTMX",
-          hint: "HTML-driven interactions with hx- attributes"
-        },
-        {
-          value: "vanilla",
-          label: "Vanilla",
-          hint: "Plain HTML, no framework"
-        }
-      ]
-    });
-    if (typeof framework === "symbol") {
-      outro("Project creation cancelled");
-      process.exit(0);
+  if (template === "static-site" || template === "full-stack") {
+    if (flags.framework) {
+      const valid = ["vanilla", "htmx", "alpine", "crank"];
+      if (!valid.includes(flags.framework)) {
+        console.error(
+          `Error: Unknown framework "${flags.framework}". Valid options: ${valid.join(", ")}`
+        );
+        process.exit(1);
+      }
+      uiFramework = flags.framework;
+    } else {
+      const framework = await select({
+        message: "UI framework:",
+        initialValue: "crank",
+        options: [
+          {
+            value: "alpine",
+            label: "Alpine.js",
+            hint: "Lightweight reactivity with x-data directives"
+          },
+          {
+            value: "crank",
+            label: "Crank.js",
+            hint: "JSX components rendered on the server"
+          },
+          {
+            value: "htmx",
+            label: "HTMX",
+            hint: "HTML-driven interactions with hx- attributes"
+          },
+          {
+            value: "vanilla",
+            label: "Vanilla",
+            hint: "Plain HTML, no framework"
+          }
+        ]
+      });
+      if (typeof framework === "symbol") {
+        outro("Project creation cancelled");
+        process.exit(0);
+      }
+      uiFramework = framework;
+    }
+  }
+  let useJSX = true;
+  if (uiFramework === "crank") {
+    if (flags.jsx !== void 0) {
+      useJSX = flags.jsx;
+    } else {
+      const jsxResult = await confirm({
+        message: "Use JSX?",
+        initialValue: true
+      });
+      if (typeof jsxResult === "symbol") {
+        outro("Project creation cancelled");
+        process.exit(0);
+      }
+      useJSX = jsxResult;
     }
-    uiFramework = framework;
   }
   let typescript;
   if (flags.typescript !== void 0) {
@@ -205,7 +235,8 @@ async function main() {
     platform,
     template,
     typescript,
-    uiFramework
+    uiFramework,
+    useJSX
   };
   const s = spinner();
   s.start("Creating your Shovel project...");
@@ -213,12 +244,13 @@ async function main() {
     await createProject(config, projectPath);
     s.stop("Project created");
     console.info("");
-    outro("Your Shovel project is ready!");
+    outro("Your project is shovel-ready!");
+    const pm = platform === "bun" ? "bun" : "npm";
     console.info("");
     console.info("Next steps:");
     console.info(`  cd ${projectName}`);
-    console.info(`  npm install`);
-    console.info(`  npm run develop`);
+    console.info(`  ${pm} install`);
+    console.info(`  ${pm} run develop`);
     console.info("");
     console.info("Your app will be available at: http://localhost:7777");
     console.info("");
@@ -231,37 +263,55 @@ async function main() {
 async function createProject(config, projectPath) {
   await mkdir(projectPath, { recursive: true });
   await mkdir(join(projectPath, "src"), { recursive: true });
-  const ext = config.uiFramework === "crank" ? config.typescript ? "tsx" : "jsx" : config.typescript ? "ts" : "js";
+  const ext = config.uiFramework === "crank" && config.useJSX ? config.typescript ? "tsx" : "jsx" : config.typescript ? "ts" : "js";
+  const isCrank = config.uiFramework === "crank";
+  const entryFile = isCrank ? `src/server.${ext}` : `src/app.${ext}`;
   const startCmd = config.platform === "bun" ? "bun dist/server/supervisor.js" : "node dist/server/supervisor.js";
   const dependencies = {
     "@b9g/router": "^0.2.0",
     "@b9g/shovel": "^0.2.0"
   };
-  if (config.uiFramework === "crank") {
+  if (isCrank) {
     dependencies["@b9g/crank"] = "^0.7.2";
   }
+  const devDependencies = {};
+  if (config.typescript) {
+    devDependencies["@types/node"] = "^18.0.0";
+    devDependencies["typescript"] = "^5.0.0";
+  }
+  if (isCrank) {
+    devDependencies["eslint"] = "^9.0.0";
+    devDependencies["@eslint/js"] = "^9.0.0";
+  }
+  const scripts = {
+    develop: `shovel develop ${entryFile} --platform ${config.platform}`,
+    build: `shovel build ${entryFile} --platform ${config.platform}`,
+    start: startCmd
+  };
+  if (isCrank) {
+    scripts.lint = "eslint src/";
+  }
   const packageJson = {
     name: config.name,
     private: true,
     version: "0.0.1",
     type: "module",
-    scripts: {
-      develop: `shovel develop src/app.${ext} --platform ${config.platform}`,
-      build: `shovel build src/app.${ext} --platform ${config.platform}`,
-      start: startCmd
-    },
+    scripts,
     dependencies,
-    devDependencies: config.typescript ? {
-      "@types/node": "^18.0.0",
-      typescript: "^5.0.0"
-    } : {}
+    devDependencies
   };
   await writeFile(
     join(projectPath, "package.json"),
     JSON.stringify(packageJson, null, 2)
   );
-  const appFile = generateAppFile(config);
-  await writeFile(join(projectPath, `src/app.${ext}`), appFile);
+  const appResult = generateAppFile(config);
+  if (typeof appResult === "string") {
+    await writeFile(join(projectPath, `src/app.${ext}`), appResult);
+  } else {
+    for (const [filename, content] of Object.entries(appResult)) {
+      await writeFile(join(projectPath, `src/${filename}`), content);
+    }
+  }
   if (config.typescript) {
     const compilerOptions = {
       target: "ES2022",
@@ -274,12 +324,15 @@ async function createProject(config, projectPath) {
       forceConsistentCasingInFileNames: true,
       lib: ["ES2022", "WebWorker"]
     };
-    if (config.uiFramework === "crank") {
+    if (config.uiFramework === "crank" && config.useJSX) {
       compilerOptions.jsx = "react-jsx";
       compilerOptions.jsxImportSource = "@b9g/crank";
     }
     const tsConfig = {
-      compilerOptions,
+      compilerOptions: {
+        ...compilerOptions,
+        types: ["@b9g/platform/globals"]
+      },
       include: ["src/**/*"],
       exclude: ["node_modules", "dist"]
     };
@@ -287,18 +340,16 @@ async function createProject(config, projectPath) {
       join(projectPath, "tsconfig.json"),
       JSON.stringify(tsConfig, null, 2)
     );
-    const envDts = `/// <reference lib="WebWorker" />
-
-// Shovel runs your code in a ServiceWorker-like environment.
-// This augments the Worker types with ServiceWorker events
-// so self.addEventListener("fetch", ...) etc. are properly typed.
-interface WorkerGlobalScopeEventMap {
-  fetch: FetchEvent;
-  install: ExtendableEvent;
-  activate: ExtendableEvent;
-}
+  }
+  if (isCrank) {
+    const eslintConfig = `import js from "@eslint/js";
+
+export default [
+  js.configs.recommended,
+  { ignores: ["dist/"] },
+];
 `;
-    await writeFile(join(projectPath, "src/env.d.ts"), envDts);
+    await writeFile(join(projectPath, "eslint.config.js"), eslintConfig);
   }
   const readme = generateReadme(config);
   await writeFile(join(projectPath, "README.md"), readme);
@@ -600,16 +651,50 @@ ${css}
 }
 function generateStaticSiteCrank(config) {
   const t = config.typescript;
-  return `import {renderer} from "@b9g/crank/html";
+  const ext = config.useJSX ? config.typescript ? "tsx" : "jsx" : config.typescript ? "ts" : "js";
+  if (config.useJSX) {
+    return {
+      [`server.${ext}`]: `import {renderer} from "@b9g/crank/html";
+import {Router} from "@b9g/router";
+import {Page} from "./components";
 
-// ${config.name} - Static Site with Crank.js
-// Server-rendered HTML with JSX components
+const router = new Router();
 
-const css = \`
+router.route("/").get(async () => {
+  const html = await renderer.render(
+    <Page title="Home">
+      <h1>Welcome to ${config.name}</h1>
+      <p>Edit <code>src/server.${ext}</code> to get started.</p>
+      <p><a href="/about">About</a></p>
+    </Page>
+  );
+  return new Response("<!DOCTYPE html>" + html, {
+    headers: { "Content-Type": "text/html" },
+  });
+});
+
+router.route("/about").get(async () => {
+  const html = await renderer.render(
+    <Page title="About">
+      <h1>About</h1>
+      <p>This is a static site built with <strong>Shovel</strong> and <strong>Crank.js</strong>.</p>
+      <p><a href="/">Home</a></p>
+    </Page>
+  );
+  return new Response("<!DOCTYPE html>" + html, {
+    headers: { "Content-Type": "text/html" },
+  });
+});
+
+self.addEventListener("fetch", (event) => {
+  event.respondWith(router.handle(event.request));
+});
+`,
+      [`components.${ext}`]: `const css = \`
 ${css}
 \`;
 
-function Page({title, children}${t ? ": {title: string, children: unknown}" : ""}) {
+export function Page({title, children}${t ? ": {title: string, children: unknown}" : ""}) {
   return (
     <html lang="en">
       <head>
@@ -624,40 +709,70 @@ function Page({title, children}${t ? ": {title: string, children: unknown}" : ""
     </html>
   );
 }
+`
+    };
+  }
+  return {
+    [`server.${ext}`]: `import {jsx} from "@b9g/crank/standalone";
+import {renderer} from "@b9g/crank/html";
+import {Router} from "@b9g/router";
+import {Page} from "./components";
 
-self.addEventListener("fetch", (event) => {
-  event.respondWith(handleRequest(event.request));
-});
-
-async function handleRequest(request${t ? ": Request" : ""})${t ? ": Promise<Response>" : ""} {
-  const url = new URL(request.url);
-  let html${t ? ": string" : ""};
+const router = new Router();
 
-  if (url.pathname === "/") {
-    html = await renderer.render(
-      <Page title="Home">
-        <h1>Welcome to ${config.name}</h1>
-        <p>Edit <code>src/app.${t ? "tsx" : "jsx"}</code> to get started.</p>
-        <p><a href="/about">About</a></p>
-      </Page>
-    );
-  } else if (url.pathname === "/about") {
-    html = await renderer.render(
-      <Page title="About">
-        <h1>About</h1>
-        <p>This is a static site built with <strong>Shovel</strong> and <strong>Crank.js</strong>.</p>
-        <p><a href="/">Home</a></p>
-      </Page>
-    );
-  } else {
-    return new Response("Not Found", { status: 404 });
-  }
+router.route("/").get(async () => {
+  const html = await renderer.render(jsx\`
+    <\${Page} title="Home">
+      <h1>Welcome to ${config.name}</h1>
+      <p>Edit <code>src/server.${ext}</code> to get started.</p>
+      <p><a href="/about">About</a></p>
+    </\${Page}>
+  \`);
+  return new Response("<!DOCTYPE html>" + html, {
+    headers: { "Content-Type": "text/html" },
+  });
+});
 
+router.route("/about").get(async () => {
+  const html = await renderer.render(jsx\`
+    <\${Page} title="About">
+      <h1>About</h1>
+      <p>This is a static site built with <strong>Shovel</strong> and <strong>Crank.js</strong>.</p>
+      <p><a href="/">Home</a></p>
+    </\${Page}>
+  \`);
   return new Response("<!DOCTYPE html>" + html, {
     headers: { "Content-Type": "text/html" },
   });
+});
+
+self.addEventListener("fetch", (event) => {
+  event.respondWith(router.handle(event.request));
+});
+`,
+    [`components.${ext}`]: `import {jsx} from "@b9g/crank/standalone";
+
+const css = \`
+${css}
+\`;
+
+export function Page({title, children}${t ? ": {title: string, children: unknown}" : ""}) {
+  return jsx\`
+    <html lang="en">
+      <head>
+        <meta charset="UTF-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+        <title>\${title} - ${config.name}</title>
+        <style>\${css}</style>
+      </head>
+      <body>
+        <main>\${children}</main>
+      </body>
+    </html>
+  \`;
 }
-`;
+`
+  };
 }
 function generateFullStack(config) {
   switch (config.uiFramework) {
@@ -895,18 +1010,69 @@ self.addEventListener("fetch", (event) => {
 }
 function generateFullStackCrank(config) {
   const t = config.typescript;
-  return `import { Router } from "@b9g/router";
-import { logger } from "@b9g/router/middleware";
-import {renderer} from "@b9g/crank/html";
+  const ext = config.useJSX ? config.typescript ? "tsx" : "jsx" : config.typescript ? "ts" : "js";
+  if (config.useJSX) {
+    return {
+      [`server.${ext}`]: `import {renderer} from "@b9g/crank/html";
+import {Router} from "@b9g/router";
+import {logger} from "@b9g/router/middleware";
+import {Page} from "./components";
 
 const router = new Router();
 router.use(logger());
 
-const css = \`
+// API routes
+router.route("/api/hello").get(() => {
+  return Response.json({
+    message: "Hello from the API!",
+    timestamp: new Date().toISOString(),
+  });
+});
+
+router.route("/api/echo").post(async (req) => {
+  const body = await req.json();
+  return Response.json({ echo: body });
+});
+
+// HTML pages
+router.route("/").get(async () => {
+  const html = await renderer.render(
+    <Page title="Home">
+      <h1>Welcome to ${config.name}</h1>
+      <p>Edit <code>src/server.${ext}</code> to get started.</p>
+      <ul>
+        <li><a href="/about">About</a></li>
+        <li><a href="/api/hello">API: /api/hello</a></li>
+      </ul>
+    </Page>
+  );
+  return new Response("<!DOCTYPE html>" + html, {
+    headers: { "Content-Type": "text/html" },
+  });
+});
+
+router.route("/about").get(async () => {
+  const html = await renderer.render(
+    <Page title="About">
+      <h1>About</h1>
+      <p>This is a full-stack app built with <strong>Shovel</strong> and <strong>Crank.js</strong>.</p>
+      <p><a href="/">Home</a></p>
+    </Page>
+  );
+  return new Response("<!DOCTYPE html>" + html, {
+    headers: { "Content-Type": "text/html" },
+  });
+});
+
+self.addEventListener("fetch", (event) => {
+  event.respondWith(router.handle(event.request));
+});
+`,
+      [`components.${ext}`]: `const css = \`
 ${css}
 \`;
 
-function Page({title, children}${t ? ": {title: string, children: unknown}" : ""}) {
+export function Page({title, children}${t ? ": {title: string, children: unknown}" : ""}) {
   return (
     <html lang="en">
       <head>
@@ -921,6 +1087,18 @@ function Page({title, children}${t ? ": {title: string, children: unknown}" : ""
     </html>
   );
 }
+`
+    };
+  }
+  return {
+    [`server.${ext}`]: `import {jsx} from "@b9g/crank/standalone";
+import {renderer} from "@b9g/crank/html";
+import {Router} from "@b9g/router";
+import {logger} from "@b9g/router/middleware";
+import {Page} from "./components";
+
+const router = new Router();
+router.use(logger());
 
 // API routes
 router.route("/api/hello").get(() => {
@@ -937,29 +1115,29 @@ router.route("/api/echo").post(async (req) => {
 
 // HTML pages
 router.route("/").get(async () => {
-  const html = await renderer.render(
-    <Page title="Home">
+  const html = await renderer.render(jsx\`
+    <\${Page} title="Home">
       <h1>Welcome to ${config.name}</h1>
-      <p>Edit <code>src/app.${t ? "tsx" : "jsx"}</code> to get started.</p>
+      <p>Edit <code>src/server.${ext}</code> to get started.</p>
       <ul>
         <li><a href="/about">About</a></li>
         <li><a href="/api/hello">API: /api/hello</a></li>
       </ul>
-    </Page>
-  );
+    </\${Page}>
+  \`);
   return new Response("<!DOCTYPE html>" + html, {
     headers: { "Content-Type": "text/html" },
   });
 });
 
 router.route("/about").get(async () => {
-  const html = await renderer.render(
-    <Page title="About">
+  const html = await renderer.render(jsx\`
+    <\${Page} title="About">
       <h1>About</h1>
       <p>This is a full-stack app built with <strong>Shovel</strong> and <strong>Crank.js</strong>.</p>
       <p><a href="/">Home</a></p>
-    </Page>
-  );
+    </\${Page}>
+  \`);
   return new Response("<!DOCTYPE html>" + html, {
     headers: { "Content-Type": "text/html" },
   });
@@ -968,7 +1146,30 @@ router.route("/about").get(async () => {
 self.addEventListener("fetch", (event) => {
   event.respondWith(router.handle(event.request));
 });
-`;
+`,
+    [`components.${ext}`]: `import {jsx} from "@b9g/crank/standalone";
+
+const css = \`
+${css}
+\`;
+
+export function Page({title, children}${t ? ": {title: string, children: unknown}" : ""}) {
+  return jsx\`
+    <html lang="en">
+      <head>
+        <meta charset="UTF-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+        <title>\${title} - ${config.name}</title>
+        <style>\${css}</style>
+      </head>
+      <body>
+        <main>\${children}</main>
+      </body>
+    </html>
+  \`;
+}
+`
+  };
 }
 function generateReadme(config) {
   const templateDescriptions = {
@@ -983,7 +1184,24 @@ function generateReadme(config) {
     alpine: " using [Alpine.js](https://alpinejs.dev)",
     crank: " using [Crank.js](https://crank.js.org)"
   };
-  const ext = config.uiFramework === "crank" ? config.typescript ? "tsx" : "jsx" : config.typescript ? "ts" : "js";
+  const ext = config.uiFramework === "crank" && config.useJSX ? config.typescript ? "tsx" : "jsx" : config.typescript ? "ts" : "js";
+  const isCrank = config.uiFramework === "crank";
+  let projectTree;
+  if (isCrank) {
+    projectTree = `${config.name}/
+\u251C\u2500\u2500 src/
+\u2502   \u251C\u2500\u2500 server.${ext}       # Application entry point
+\u2502   \u2514\u2500\u2500 components.${ext}   # Page components
+\u251C\u2500\u2500 eslint.config.js
+\u251C\u2500\u2500 package.json
+${config.typescript ? "\u251C\u2500\u2500 tsconfig.json\n" : ""}\u2514\u2500\u2500 README.md`;
+  } else {
+    projectTree = `${config.name}/
+\u251C\u2500\u2500 src/
+\u2502   \u2514\u2500\u2500 app.${ext}    # Application entry point
+\u251C\u2500\u2500 package.json
+${config.typescript ? "\u251C\u2500\u2500 tsconfig.json\n" : ""}\u2514\u2500\u2500 README.md`;
+  }
   return `# ${config.name}
 
 ${templateDescriptions[config.template]}${frameworkDescriptions[config.uiFramework]}, built with [Shovel](https://github.com/bikeshaving/shovel).
@@ -1001,16 +1219,12 @@ Open http://localhost:7777
 
 - \`npm run develop\` - Start development server
 - \`npm run build\` - Build for production
-- \`npm start\` - Run production build
+- \`npm start\` - Run production build${isCrank ? "\n- `npm run lint` - Lint source files" : ""}
 
 ## Project Structure
 
 \`\`\`
-${config.name}/
-\u251C\u2500\u2500 src/
-\u2502   \u2514\u2500\u2500 app.${ext}    # Application entry point
-\u251C\u2500\u2500 package.json
-${config.typescript ? "\u251C\u2500\u2500 tsconfig.json\n" : ""}\u2514\u2500\u2500 README.md
+${projectTree}
 \`\`\`
 
 ## Learn More

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@b9g/shovel",
-  "version": "0.2.9",
+  "version": "0.2.11",
   "description": "ServiceWorker-first universal deployment platform. Write ServiceWorker apps once, deploy anywhere (Node/Bun/Cloudflare). Registry-based multi-app orchestration.",
   "license": "MIT",
   "repository": {
@@ -35,7 +35,7 @@
   "devDependencies": {
     "@b9g/assets": "^0.2.1",
     "@b9g/crank": "^0.7.2",
-    "@b9g/libuild": "^0.1.22",
+    "@b9g/libuild": "^0.1.24",
     "@b9g/router": "^0.2.2",
     "@logtape/file": "^2.0.0",
     "@types/bun": "^1.3.4",
@@ -53,19 +53,19 @@
     "./package.json": "./package.json",
     "./bin/cli": {
       "types": "./src/undefined.d.ts",
-      "import": "./dist/bin/cli.js"
+      "import": "./bin/cli.js"
     },
     "./bin/cli.js": {
       "types": "./src/undefined.d.ts",
-      "import": "./dist/bin/cli.js"
+      "import": "./bin/cli.js"
     },
     "./bin/create": {
-      "types": "./dist/bin/create.d.ts",
-      "import": "./dist/bin/create.js"
+      "types": "./bin/create.d.ts",
+      "import": "./bin/create.js"
     },
     "./bin/create.js": {
-      "types": "./dist/bin/create.d.ts",
-      "import": "./dist/bin/create.js"
+      "types": "./bin/create.d.ts",
+      "import": "./bin/create.js"
     }
   }
 }