create-shibumi 0.0.1 → 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Shibumi Stack
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,5 +1,47 @@
 # create-shibumi
 
-Scaffold a new Shibumi Stack project.
+Scaffold a Shibumi Stack project: simple apps, whole stack, without React, build pipelines, or 600 MB of `node_modules`. Every generated project keeps its source, tests, and deployment config in your repository. No Shibumi runtime dependency.
 
-See [shibumistack.dev](https://shibumistack.dev) for more.
+```sh
+bun create shibumi@latest my-app
+cd my-app
+bun dev
+```
+
+## Three starting points
+
+1. **Static site**: publish a verified build directory such as `./dist`, `public`, `build`, or `out` from any framework.
+2. **Bun web**: Hono, HTML, CSS, Alpine, Zod, tests, and a health endpoint.
+3. **SQLite full stack**: the Bun web project plus Drizzle, migrations, persistent data, backup, and restore.
+
+All three deploy to a Linux VPS or homelab through [shibumi-server](https://server.shibumistack.dev). Other providers can wait until their generated projects pass the same artifact and deployment tests.
+
+## Flags
+
+```text
+--template <id>       static, web, or full-stack
+--yes, -y             non-interactive; requires name and --template
+--no-git              skip git init
+--no-install          skip dependency install
+--help, -h            show help
+--version             show version
+```
+
+Creation is atomic: the project is built in a temporary sibling directory and renamed into place. Failure or cancellation leaves nothing behind, and an existing destination is never touched. Git init stages and commits nothing; the first commit belongs to you.
+
+## Guidance for coding agents
+
+Generated projects include a root `agents.md`. It records route locations, data rules, available checks, and files that need extra care.
+
+## Development
+
+```sh
+bun install
+bun test        # CLI tests (parsing, atomicity, signals, E2E)
+bun check       # TypeScript
+bun sync:ship   # re-vendor the Ship client from its locked immutable snapshot
+```
+
+The vendored Ship client in `src/templates/ship.ts` is locked byte-for-byte to a published immutable snapshot via `scripts/ship.lock.json`; tests fail on any drift.
+
+Docs: <https://shibumistack.dev/docs>

package/package.json

@@ -1,9 +1,61 @@
 {
   "name": "create-shibumi",
-  "version": "0.0.1",
-  "description": "Scaffold a new Shibumi Stack project. See https://shibumistack.dev",
-  "keywords": ["shibumi", "stack", "create", "scaffold", "bun", "hono", "sqlite", "alpine", "typescript"],
+  "version": "0.2.1",
+  "description": "Scaffold a Shibumi Stack project: Bun, Hono, Zod, Drizzle, SQLite, Alpine",
+  "type": "module",
+  "bin": {
+    "create-shibumi": "./src/cli.ts"
+  },
+  "files": [
+    "src/cli.ts",
+    "src/args.ts",
+    "src/create.ts",
+    "src/templates/ship.ts",
+    "src/templates/shibumi.ts",
+    "scripts/ship.lock.json",
+    "scripts/shibumi.lock.json",
+    "src/templates/static/",
+    "src/templates/blog/",
+    "src/templates/full-stack/",
+    "src/templates/web/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "bun src/cli.ts",
+    "test": "bun test test",
+    "check": "tsc --noEmit",
+    "sync:ship": "bun scripts/sync-ship.ts",
+    "sync:extensions": "bun scripts/sync-extensions.ts",
+    "verify:packed": "bun scripts/verify-packed.ts"
+  },
+  "keywords": [
+    "shibumi",
+    "scaffold",
+    "cli",
+    "bun",
+    "hono",
+    "drizzle",
+    "alpine",
+    "zod",
+    "starter",
+    "template"
+  ],
+  "author": "Shibumi Stack",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/shibumistack/create-shibumi"
+  },
   "homepage": "https://shibumistack.dev",
-  "repository": "github:shibumistack/create-shibumi",
-  "license": "MIT"
+  "dependencies": {
+    "@clack/prompts": "1.7.0"
+  },
+  "devDependencies": {
+    "@types/bun": "1.4.0",
+    "typescript": "5.9.2"
+  },
+  "engines": {
+    "bun": ">=1.4.0"
+  }
 }

package/scripts/shibumi.lock.json

@@ -0,0 +1,22 @@
+{
+  "version": "0.2.0",
+  "extensions": [
+    {
+      "name": "admin",
+      "version": "1.0.1"
+    },
+    {
+      "name": "auth",
+      "version": "1.0.1"
+    },
+    {
+      "name": "email",
+      "version": "1.0.0"
+    },
+    {
+      "name": "uploads",
+      "version": "1.0.1"
+    }
+  ],
+  "sha256": "10386d9e6db61626780e85ef6bcc423e88402606b8ce9baa2c222e61cd32f134"
+}

package/scripts/ship.lock.json

@@ -0,0 +1,4 @@
+{
+  "url": "https://shibumistack.dev/ship/v45.ts",
+  "sha256": "d9bad68786b288d027bb00b2183583905e266069f4506c34e364d3e93ce77cb5"
+}

package/src/args.ts

@@ -0,0 +1,162 @@
+export const TEMPLATES = ["static", "web", "full-stack", "blog"] as const;
+export type TemplateId = (typeof TEMPLATES)[number];
+
+export interface ParsedArgs {
+  help: boolean;
+  version: boolean;
+  yes: boolean;
+  git: boolean;
+  install: boolean;
+  name?: string;
+  template?: TemplateId;
+}
+
+export type ParseResult =
+  | { ok: true; args: ParsedArgs }
+  | { ok: false; error: string };
+
+// Declared minimum Bun; template lockfiles use lockfileVersion 2, which
+// older Bun cannot parse, so scaffolding must refuse early and clearly.
+export const MINIMUM_BUN = "1.4.0";
+
+export function bunVersionProblem(version: string, minimum = MINIMUM_BUN): string | null {
+  const parse = (value: string) => value.split("-")[0]!.split(".").map((part) => Number(part) || 0);
+  const [major = 0, minor = 0, patch = 0] = parse(version);
+  const [minMajor = 0, minMinor = 0, minPatch = 0] = parse(minimum);
+  const current = major * 1_000_000 + minor * 1_000 + patch;
+  const floor = minMajor * 1_000_000 + minMinor * 1_000 + minPatch;
+  if (current >= floor) return null;
+  return `create-shibumi needs Bun ${minimum} or newer; you are running ${version}. Update with: bun upgrade`;
+}
+
+// Lowercase npm-style project names only; also the directory name.
+export const NAME_PATTERN = /^[a-z0-9][a-z0-9._-]*$/;
+
+const VALUE_FLAGS = new Set(["--template"]);
+const BOOLEAN_FLAGS = new Set([
+  "--help",
+  "-h",
+  "--version",
+  "--yes",
+  "-y",
+  "--no-git",
+  "--no-install",
+]);
+
+export function validateName(name: string): string | null {
+  if (!NAME_PATTERN.test(name)) {
+    return `Invalid project name "${name}". Use lowercase letters, digits, ".", "_" or "-", starting with a letter or digit.`;
+  }
+  if (name.length > 128) {
+    return `Project name too long (max 128 characters).`;
+  }
+  return null;
+}
+
+export function parseArgs(argv: string[]): ParseResult {
+  const args: ParsedArgs = {
+    help: false,
+    version: false,
+    yes: false,
+    git: true,
+    install: true,
+  };
+  const positionals: string[] = [];
+
+  for (let i = 0; i < argv.length; i++) {
+    const raw = argv[i]!;
+
+    if (!raw.startsWith("-")) {
+      positionals.push(raw);
+      continue;
+    }
+
+    let flag = raw;
+    let inlineValue: string | undefined;
+    const eq = raw.indexOf("=");
+    if (raw.startsWith("--") && eq !== -1) {
+      flag = raw.slice(0, eq);
+      inlineValue = raw.slice(eq + 1);
+    }
+
+    if (VALUE_FLAGS.has(flag)) {
+      let value = inlineValue;
+      if (value === undefined) {
+        const next = argv[i + 1];
+        if (next === undefined || next.startsWith("-")) {
+          return { ok: false, error: `${flag} requires a value.` };
+        }
+        value = next;
+        i++;
+      }
+      if (flag === "--template") {
+        if (!(TEMPLATES as readonly string[]).includes(value)) {
+          return {
+            ok: false,
+            error: `Unknown template "${value}". Available: ${TEMPLATES.join(", ")}.`,
+          };
+        }
+        args.template = value as TemplateId;
+      }
+      continue;
+    }
+
+    if (BOOLEAN_FLAGS.has(flag)) {
+      if (inlineValue !== undefined) {
+        return { ok: false, error: `${flag} does not take a value.` };
+      }
+      if (flag === "--help" || flag === "-h") args.help = true;
+      else if (flag === "--version") args.version = true;
+      else if (flag === "--yes" || flag === "-y") args.yes = true;
+      else if (flag === "--no-git") args.git = false;
+      else if (flag === "--no-install") args.install = false;
+      continue;
+    }
+
+    return { ok: false, error: `Unknown flag: ${flag}` };
+  }
+
+  if (args.help || args.version) {
+    return { ok: true, args };
+  }
+
+  if (positionals.length > 1) {
+    return {
+      ok: false,
+      error: `Unexpected argument "${positionals[1]}". Pass one project name.`,
+    };
+  }
+  if (positionals.length === 1) {
+    const err = validateName(positionals[0]!);
+    if (err) return { ok: false, error: err };
+    args.name = positionals[0]!;
+  }
+
+  if (args.yes) {
+    if (!args.name) {
+      return { ok: false, error: `--yes requires a project name.` };
+    }
+    if (!args.template) {
+      return { ok: false, error: `--yes requires --template (${TEMPLATES.join(", ")}).` };
+    }
+  }
+
+  return { ok: true, args };
+}
+
+export const HELP_TEXT = `create-shibumi: scaffold a Shibumi Stack project
+
+Usage
+  bun create shibumi@latest [name] [flags]
+  bunx create-shibumi [name] [flags]
+
+Flags
+  --template <id>       static, web, full-stack, or blog
+  --yes, -y             non-interactive; requires name and --template
+  --no-git              skip git init
+  --no-install          skip dependency install
+  --help, -h            show this help
+  --version             show version
+
+Docs: https://shibumistack.dev/docs
+`;

package/src/cli.ts

@@ -0,0 +1,232 @@
+#!/usr/bin/env bun
+
+import { cancel, confirm, intro, isCancel, log, outro, select, spinner, text } from "@clack/prompts";
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
+import { HELP_TEXT, bunVersionProblem, parseArgs, validateName, type TemplateId } from "./args";
+import { CreateError, createProject } from "./create";
+
+const VERSION = (
+  JSON.parse(readFileSync(join(import.meta.dir, "..", "package.json"), "utf8")) as {
+    version: string;
+  }
+).version;
+
+const CANCELLED = "Cancelled. Nothing was created.";
+
+function exitCancelled(): never {
+  cancel(CANCELLED);
+  process.exit(130);
+}
+
+// Emit the vendored extension installer so a generated project can re-vendor it
+// (`bun run shibumi update` runs `bunx create-shibumi@latest --print-installer`).
+// Verifies the checksum lock before printing, so a corrupt package cannot ship
+// a tampered installer through this path.
+async function printInstaller(): Promise<never> {
+  const installer = join(import.meta.dir, "templates", "shibumi.ts");
+  const lockPath = join(import.meta.dir, "..", "scripts", "shibumi.lock.json");
+  const lock = JSON.parse(readFileSync(lockPath, "utf8")) as { sha256: string };
+  const bytes = await Bun.file(installer).arrayBuffer();
+  const digest = new Bun.CryptoHasher("sha256").update(bytes).digest("hex");
+  if (digest !== lock.sha256) {
+    process.stderr.write("Vendored installer does not match its checksum lock; reinstall create-shibumi.\n");
+    process.exit(1);
+  }
+  process.stdout.write(readFileSync(installer, "utf8"));
+  process.exit(0);
+}
+
+async function main(): Promise<void> {
+  if (process.argv.slice(2).includes("--print-installer")) {
+    await printInstaller();
+  }
+  const bunProblem = bunVersionProblem(Bun.version);
+  if (bunProblem) {
+    process.stderr.write(`${bunProblem}\n`);
+    process.exit(2);
+  }
+  const parsed = parseArgs(process.argv.slice(2));
+  if (!parsed.ok) {
+    process.stderr.write(`${parsed.error}\nRun create-shibumi --help for usage.\n`);
+    process.exit(2);
+  }
+  const args = parsed.args;
+
+  if (args.help) {
+    process.stdout.write(HELP_TEXT);
+    process.exit(0);
+  }
+  if (args.version) {
+    process.stdout.write(`${VERSION}\n`);
+    process.exit(0);
+  }
+
+  const interactive = !args.yes;
+  if (interactive && !process.stdin.isTTY) {
+    process.stderr.write(
+      `No interactive terminal. Use --yes with a project name and --template.\n`
+    );
+    process.exit(2);
+  }
+
+  intro("渋み shibumi");
+
+  let name: string;
+  if (args.name) {
+    name = args.name;
+  } else {
+    const answer = await text({
+      message: "Project name?",
+      placeholder: "my-app",
+      validate: (value) => validateName(value ?? "") ?? undefined,
+    });
+    if (isCancel(answer)) exitCancelled();
+    name = answer;
+  }
+
+  let template: TemplateId;
+  if (args.template) {
+    template = args.template;
+  } else {
+    const dim = (value: string) => `\x1b[2m${value}\x1b[22m`;
+    const detail = (value: string) => `\n    ${dim(value)}`;
+    const answer = await select({
+      message: "What are you shipping?",
+      options: [
+        {
+          value: "full-stack" as TemplateId,
+          label: `Bun full-stack app ${dim("(recommended)")}${detail("Hono, Alpine, and SQLite with migrations and backups")}`,
+        },
+        {
+          value: "web" as TemplateId,
+          label: `Bun web app${detail("Hono, Alpine, and Zod; no database")}`,
+        },
+        {
+          value: "static" as TemplateId,
+          label: `Static site${detail("Any framework's build output: dist/, public/, _site/, or plain files")}`,
+        },
+      ],
+    });
+    if (isCancel(answer)) exitCancelled();
+    template = answer as TemplateId;
+    if (template === "static") {
+      const start = await select({
+        message: "Start from?",
+        options: [
+          {
+            value: "static" as TemplateId,
+            label: `Plain files${detail("index.html and friends in public/")}`,
+          },
+          {
+            value: "blog" as TemplateId,
+            label: `Astro blog${detail("posts, RSS, sitemap, SEO meta, llms.txt, markdown alternates")}`,
+          },
+        ],
+      });
+      if (isCancel(start)) exitCancelled();
+      template = start as TemplateId;
+      if (template === "static") {
+        log.info("Using a generator? Point bun ship:setup at its output directory later.");
+      }
+    }
+  }
+
+  let deployNow = false;
+  if (interactive) {
+    const answer = await confirm({
+      message: "Deploy to a VPS now?",
+      active: "Yes",
+      inactive: "Later",
+      initialValue: false,
+    });
+    if (isCancel(answer)) exitCancelled();
+    deployNow = answer;
+  }
+
+  const s = spinner();
+  s.start("Creating project");
+  let dest: string;
+  try {
+    const result = await createProject(
+      {
+        name,
+        parentDir: process.cwd(),
+        template,
+        git: args.git,
+        install: args.install,
+      },
+      undefined,
+      (step) => {
+        if (step === "git") s.message("Initializing git");
+        else if (step === "install") s.message("Installing dependencies");
+      }
+    );
+    dest = result.dest;
+    s.stop(`Created ${name}`);
+    // Receipt: the finished transcript documents what actually happened.
+    log.success("Template copied");
+    if (args.git) log.success("Git initialized; nothing committed, the first commit is yours");
+    else log.info("Git skipped; run git init when you want history");
+    if (args.install) log.success("Dependencies installed");
+    else log.info("Install skipped; run bun install inside the project");
+    if (existsSync(join(result.dest, "scripts", "ship.ts"))) {
+      log.success("Ship client vendored (scripts/ship.ts)");
+    }
+  } catch (err) {
+    if (err instanceof CreateError) {
+      s.stop("Failed");
+      process.stderr.write(`${err.message}\n`);
+      process.exit(err.exitCode);
+    }
+    throw err;
+  }
+
+  // Post-create phase: runs only after the atomic rename. Cancelling here
+  // leaves a complete, healthy project behind.
+  if (deployNow) {
+    const pkg = JSON.parse(readFileSync(join(dest, "package.json"), "utf8")) as {
+      scripts?: Record<string, string>;
+    };
+    if (pkg.scripts?.["ship:setup"] && existsSync(join(dest, "scripts", "ship.ts"))) {
+      const proc = Bun.spawn(["bun", "run", "ship:setup"], {
+        cwd: dest,
+        stdin: "inherit",
+        stdout: "inherit",
+        stderr: "inherit",
+      });
+      const code = await proc.exited;
+      if (code !== 0) {
+        process.stderr.write(
+          `ship:setup did not finish. Your project is intact; run "bun ship:setup" inside ${name} to retry.\n`
+        );
+        process.exit(1);
+      }
+    } else {
+      process.stdout.write(
+        `This template has no ship:setup yet. Run "bun ship:setup" inside ${name} once it does.\n`
+      );
+    }
+  }
+
+  const accent = (value: string) => `\x1b[38;5;208m${value}\x1b[0m`;
+  const dim = (value: string) => `\x1b[2m${value}\x1b[22m`;
+  log.message(
+    [
+      `${accent("next")}  cd ${name}`,
+      `      bun dev           ${dim("start the dev server (ctrl+c stops it)")}`,
+      deployNow
+        ? `      bun ship          ${dim("deploy your first commit")}`
+        : `      bun ship:setup    ${dim("connect your VPS when you're ready")}`,
+      "",
+      dim("agents.md tells your coding agent the house rules."),
+    ].join("\n")
+  );
+  outro(`Docs: ${accent("https://shibumistack.dev/docs")}`);
+}
+
+main().catch((err: unknown) => {
+  const message = err instanceof Error ? err.message : String(err);
+  process.stderr.write(`Something went wrong: ${message}\n`);
+  process.exit(1);
+});