idcmd 0.0.10 → 0.0.12

package/README.md

@@ -18,11 +18,33 @@ idcmd init [dir]   # scaffold a new site
 idcmd dev          # tailwind watch + SSR dev server
 idcmd build        # static public/
 idcmd preview      # serve public/ locally
-idcmd deploy       # build + validate Vercel static deploy config
+idcmd deploy       # build + generate deploy files (Vercel/Fly/Railway)
 idcmd client ...   # add/update local src implementations
 ```
 
-## Layout (V1)
+For full command docs (flags, examples, side effects), use:
+
+```bash
+idcmd --help
+idcmd init --help
+idcmd deploy --help
+```
+
+### Deploy targets
+
+```bash
+idcmd init my-docs --fly
+idcmd init my-docs --railway
+idcmd init my-docs --vercel
+
+idcmd deploy --fly
+idcmd deploy --railway
+idcmd deploy --vercel
+```
+
+`idcmd init --yes` is provider-neutral by default (no provider files generated).
+
+## Layout
 
 - `content/<slug>.md` -> `/<slug>/` (`index.md` -> `/`)
 - `src/ui/*` is local UI source code (you own and edit these files)
@@ -66,7 +88,7 @@ This is a new page.
 
 It renders at `/hello/`.
 
-## Custom Server Routes (V1)
+## Custom Server Routes
 
 Add `src/routes/api/hello.ts`:
 
@@ -76,9 +98,9 @@ export const GET = (): Response => Response.json({ ok: true });
 
 It responds at `/api/hello`.
 
-## V1 Definition Of Done
+## Definition Of Done
 
-`tickets/ROADMAP.md` is the source of truth. For V1, we explicitly target:
+We explicitly target:
 
 - Content routes ship `0` bytes of JavaScript by default (both SSR output and built HTML).
 - Content routes ship a small, opinionated JavaScript runtime by default (prefetch + optional right-rail behavior).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "idcmd",
-  "version": "0.0.10",
+  "version": "0.0.12",
   "repository": {
     "type": "git",
     "url": "https://github.com/rustydotwtf/idcmd"
@@ -35,8 +35,7 @@
     "prepare": "lefthook install"
   },
   "dependencies": {
-    "preact": "^10.28.3",
-    "preact-render-to-string": "^6.6.5",
+    "@kitajs/html": "^4.2.13",
     "shiki": "^3.22.0",
     "zod": "^3.24.0"
   },

package/src/cli/commands/build.ts

@@ -25,7 +25,8 @@ export const buildCommand = async (): Promise<number> => {
   const cssProc = Bun.spawn(
     [
       "bunx",
-      "@tailwindcss/cli",
+      "--no-install",
+      "tailwindcss",
       "-i",
       tailwindInput,
       "-o",

package/src/cli/commands/deploy.ts

@@ -1,5 +1,16 @@
+import { resolveCachePolicy } from "../../site/cache";
+import { loadSiteConfig } from "../../site/config";
+import { basename } from "../path";
+import { isDeployProvider, resolveProviderFromFlags } from "../provider";
+import { generateProviderFiles, providerConfigPaths } from "../provider-files";
 import { buildCommand } from "./build";
 
+export interface DeployFlags {
+  fly?: boolean;
+  railway?: boolean;
+  vercel?: boolean;
+}
+
 const readJsonFile = async (path: string): Promise<unknown> => {
   const file = Bun.file(path);
   if (!(await file.exists())) {
@@ -9,22 +20,81 @@ const readJsonFile = async (path: string): Promise<unknown> => {
   return JSON.parse(text) as unknown;
 };
 
+const readPackageName = async (): Promise<string> => {
+  const raw = await readJsonFile("package.json");
+  if (raw && typeof raw === "object") {
+    const pkg = raw as { name?: unknown };
+    if (typeof pkg.name === "string" && pkg.name.length > 0) {
+      return pkg.name;
+    }
+  }
+  return basename(process.cwd());
+};
+
+const warn = (message: string): void => {
+  // eslint-disable-next-line no-console
+  console.warn(`Warning: ${message}`);
+};
+
+const warnIfFileMissing = async (
+  path: string,
+  context: string
+): Promise<void> => {
+  if (await Bun.file(path).exists()) {
+    return;
+  }
+  warn(`${path} not found (${context}).`);
+};
+
 const warnIfVercelMisconfigured = async (): Promise<void> => {
-  const raw = await readJsonFile("vercel.json");
+  const raw = await readJsonFile(providerConfigPaths.vercelJson);
   if (!raw) {
-    // eslint-disable-next-line no-console
-    console.warn(
-      "Warning: vercel.json not found. Vercel static deploy expects public/ output."
-    );
+    warn("vercel.json not found. Run `idcmd deploy --vercel` to generate it.");
     return;
   }
 
   const record = raw as Record<string, unknown>;
   const out = record.outputDirectory;
   if (out !== "public") {
-    // eslint-disable-next-line no-console
-    console.warn(
-      `Warning: vercel.json outputDirectory is not "public" (got ${JSON.stringify(out)}).`
+    warn(
+      `vercel.json outputDirectory is not "public" (got ${JSON.stringify(out)}).`
+    );
+  }
+};
+
+const warnIfFlyMisconfigured = async (): Promise<void> => {
+  await warnIfFileMissing(
+    providerConfigPaths.flyToml,
+    "required for Fly.io deploy"
+  );
+  await warnIfFileMissing(
+    providerConfigPaths.dockerfile,
+    "required for Fly.io deploy"
+  );
+};
+
+const warnIfRailwayMisconfigured = async (): Promise<void> => {
+  await warnIfFileMissing(
+    providerConfigPaths.railwayJson,
+    "required for Railway deploy"
+  );
+  await warnIfFileMissing(
+    providerConfigPaths.dockerfile,
+    "required for Railway deploy"
+  );
+
+  const raw = await readJsonFile(providerConfigPaths.railwayJson);
+  if (!raw || typeof raw !== "object") {
+    return;
+  }
+
+  const config = raw as {
+    build?: { builder?: unknown };
+  };
+  const builder = config.build?.builder;
+  if (builder !== undefined && builder !== "DOCKERFILE") {
+    warn(
+      `railway.json build.builder is ${JSON.stringify(builder)}; expected "DOCKERFILE".`
     );
   }
 };
@@ -40,33 +110,78 @@ const warnIfBaseUrlMissing = async (): Promise<void> => {
       baseUrl?: unknown;
     };
     if (!cfg.baseUrl) {
-      // eslint-disable-next-line no-console
-      console.warn(
-        "Warning: site.jsonc missing baseUrl; sitemap.xml and robots.txt will be skipped."
+      warn(
+        "site.jsonc missing baseUrl; sitemap.xml and robots.txt will be skipped."
       );
     }
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
-    // eslint-disable-next-line no-console
-    console.warn(`Warning: Failed to parse site.jsonc: ${message}`);
+    warn(`Failed to parse site.jsonc: ${message}`);
   }
 };
 
-export const deployCommand = async (): Promise<number> => {
-  const code = await buildCommand();
-  if (code !== 0) {
-    return code;
+const warnIfProviderMisconfigured = async (
+  provider: "vercel" | "fly" | "railway"
+): Promise<void> => {
+  if (provider === "vercel") {
+    await warnIfVercelMisconfigured();
+    return;
   }
+  if (provider === "fly") {
+    await warnIfFlyMisconfigured();
+    return;
+  }
+  await warnIfRailwayMisconfigured();
+};
 
-  await warnIfVercelMisconfigured();
-  await warnIfBaseUrlMissing();
+const printGeneratedFiles = (files: readonly string[]): void => {
+  if (files.length === 0) {
+    return;
+  }
+  // eslint-disable-next-line no-console
+  console.log("");
+  // eslint-disable-next-line no-console
+  console.log("Generated files:");
+  for (const path of files) {
+    // eslint-disable-next-line no-console
+    console.log(`  - ${path}`);
+  }
+};
 
-  printDeployInstructions();
+const generateProviderFilesForProject = async (
+  provider: "vercel" | "fly" | "railway"
+): Promise<void> => {
+  const siteConfig = await loadSiteConfig();
+  const packageName = await readPackageName();
+  const files = await generateProviderFiles({
+    cachePolicy: resolveCachePolicy(siteConfig.cache),
+    packageName,
+    provider,
+    targetDir: process.cwd(),
+  });
+  printGeneratedFiles(files);
+};
 
-  return 0;
+const printNeutralDeployInstructions = (): void => {
+  // eslint-disable-next-line no-console
+  console.log("");
+  // eslint-disable-next-line no-console
+  console.log("Deploy:");
+  // eslint-disable-next-line no-console
+  console.log("  1. Choose a provider");
+  // eslint-disable-next-line no-console
+  console.log("  2. Generate provider files:");
+  // eslint-disable-next-line no-console
+  console.log("     idcmd deploy --vercel");
+  // eslint-disable-next-line no-console
+  console.log("     idcmd deploy --fly");
+  // eslint-disable-next-line no-console
+  console.log("     idcmd deploy --railway");
+  // eslint-disable-next-line no-console
+  console.log("");
 };
 
-const printDeployInstructions = (): void => {
+const printVercelInstructions = (): void => {
   // eslint-disable-next-line no-console
   console.log("");
   // eslint-disable-next-line no-console
@@ -80,3 +195,74 @@ const printDeployInstructions = (): void => {
   // eslint-disable-next-line no-console
   console.log("");
 };
+
+const printFlyInstructions = (): void => {
+  // eslint-disable-next-line no-console
+  console.log("");
+  // eslint-disable-next-line no-console
+  console.log("Deploy (Fly.io):");
+  // eslint-disable-next-line no-console
+  console.log("  1. Install flyctl and run `fly auth login`");
+  // eslint-disable-next-line no-console
+  console.log("  2. Set `app` in fly.toml to your Fly app name");
+  // eslint-disable-next-line no-console
+  console.log("  3. Run `fly deploy`");
+  // eslint-disable-next-line no-console
+  console.log("");
+};
+
+const printRailwayInstructions = (): void => {
+  // eslint-disable-next-line no-console
+  console.log("");
+  // eslint-disable-next-line no-console
+  console.log("Deploy (Railway):");
+  // eslint-disable-next-line no-console
+  console.log("  1. Connect this repo in Railway (or use `railway up`)");
+  // eslint-disable-next-line no-console
+  console.log("  2. Railway will build from Dockerfile");
+  // eslint-disable-next-line no-console
+  console.log(
+    "  3. Ensure required env vars are set (for example SITE_BASE_URL)"
+  );
+  // eslint-disable-next-line no-console
+  console.log("");
+};
+
+const printDeployInstructions = (
+  provider: "none" | "vercel" | "fly" | "railway"
+): void => {
+  if (provider === "none") {
+    printNeutralDeployInstructions();
+    return;
+  }
+  if (provider === "vercel") {
+    printVercelInstructions();
+    return;
+  }
+  if (provider === "fly") {
+    printFlyInstructions();
+    return;
+  }
+  printRailwayInstructions();
+};
+
+export const deployCommand = async (
+  flags: DeployFlags = {}
+): Promise<number> => {
+  const provider = resolveProviderFromFlags(flags);
+  const code = await buildCommand();
+  if (code !== 0) {
+    return code;
+  }
+
+  await warnIfBaseUrlMissing();
+
+  if (isDeployProvider(provider)) {
+    await generateProviderFilesForProject(provider);
+    await warnIfProviderMisconfigured(provider);
+  }
+
+  printDeployInstructions(provider);
+
+  return 0;
+};

package/src/cli/commands/dev.ts

@@ -38,7 +38,8 @@ const spawnCssProcess = (
   Bun.spawn(
     [
       "bunx",
-      "@tailwindcss/cli",
+      "--no-install",
+      "tailwindcss",
       "-i",
       tailwindInput,
       "-o",

package/src/cli/commands/init.ts

@@ -1,3 +1,4 @@
+import { resolveCachePolicy } from "../../site/cache";
 import { copyDir, ensureDir, isDirEmpty, replaceInFile } from "../fs";
 import {
   normalizeOptionalString,
@@ -5,7 +6,9 @@ import {
   toPackageName,
 } from "../normalize";
 import { basename, dirname, joinPath } from "../path";
-import { promptOptionalText, promptText } from "../prompt";
+import { promptOptionalText, promptSelect, promptText } from "../prompt";
+import { isDeployProvider, resolveProviderFromFlags } from "../provider";
+import { generateProviderFiles } from "../provider-files";
 import { run } from "../run";
 import { readPackageVersion } from "../version";
 
@@ -14,9 +17,12 @@ const DEFAULT_PORT = 4000;
 export interface InitFlags {
   "base-url"?: string;
   description?: string;
+  fly?: boolean;
   git?: boolean;
   name?: string;
   port?: string;
+  railway?: boolean;
+  vercel?: boolean;
   yes?: boolean;
 }
 
@@ -110,7 +116,7 @@ const fillPackageJson = (args: {
     .replaceAll("__IDCMD_IDCMD_VERSION__", `^${args.idcmdVersion}`)
     .replaceAll("__IDCMD_DEV_PORT__", String(args.port));
 
-const fillReadme = (args: { siteName: string; text: string }): string =>
+const fillSiteNameTokens = (args: { siteName: string; text: string }): string =>
   args.text
     .replaceAll("__IDCMD_SITE_NAME__", args.siteName)
     .replaceAll("IDCMD_SITE_NAME", args.siteName);
@@ -125,14 +131,41 @@ interface InitInputs {
   baseUrl: string | null;
   description: string;
   port: number;
+  provider: "none" | "vercel" | "fly" | "railway";
   siteName: string;
 }
 
+const promptProviderChoice = (): Promise<
+  "none" | "vercel" | "fly" | "railway"
+> =>
+  promptSelect(
+    "Deploy provider (optional)",
+    [
+      { label: "None (self-host / decide later)", value: "none" },
+      { label: "Vercel", value: "vercel" },
+      { label: "Fly.io", value: "fly" },
+      { label: "Railway", value: "railway" },
+    ],
+    "none"
+  );
+
+const resolveInitProvider = (
+  flags: InitFlags,
+  yes: boolean
+): Promise<"none" | "vercel" | "fly" | "railway"> => {
+  const provider = resolveProviderFromFlags(flags);
+  if (provider !== "none" || yes) {
+    return Promise.resolve(provider);
+  }
+  return promptProviderChoice();
+};
+
 const readInitInputs = async (
   flags: InitFlags,
   defaults: InitDefaults
 ): Promise<InitInputs> => {
   const yes = flags.yes === true;
+  const provider = await resolveInitProvider(flags, yes);
 
   const siteName = yes
     ? (flags.name ?? defaults.defaultSiteName)
@@ -157,6 +190,7 @@ const readInitInputs = async (
     baseUrl: normalizeOptionalString(baseUrlRaw),
     description,
     port,
+    provider,
     siteName,
   };
 };
@@ -219,7 +253,14 @@ const applySubstitutions = async (args: {
   );
 
   await replaceInFile(joinPath(args.targetDir, "README.md"), (text) =>
-    fillReadme({
+    fillSiteNameTokens({
+      siteName: args.siteName,
+      text,
+    })
+  );
+
+  await replaceInFile(joinPath(args.targetDir, "content", "index.md"), (text) =>
+    fillSiteNameTokens({
       siteName: args.siteName,
       text,
     })
@@ -248,7 +289,9 @@ const printNextSteps = (dir: string): void => {
 const assertEmptyTargetDir = async (targetDir: string): Promise<void> => {
   const empty = await isDirEmpty(targetDir);
   if (!empty) {
-    throw new Error(`Target directory is not empty: ${targetDir}`);
+    throw new Error(
+      `Target directory is not empty: ${targetDir}\nUse an empty directory or run \`idcmd init <new-directory>\`.`
+    );
   }
 };
 
@@ -280,6 +323,15 @@ const scaffoldAndConfigure = async (args: {
     siteName: args.inputs.siteName,
     targetDir: args.targetDir,
   });
+
+  if (isDeployProvider(args.inputs.provider)) {
+    await generateProviderFiles({
+      cachePolicy: resolveCachePolicy(),
+      packageName: args.defaults.packageName,
+      provider: args.inputs.provider,
+      targetDir: args.targetDir,
+    });
+  }
 };
 
 export const initCommand = async (

package/src/cli/commands/preview.ts

@@ -6,12 +6,15 @@ import {
 const stripLeadingSlash = (pathname: string): string =>
   pathname.startsWith("/") ? pathname.slice(1) : pathname;
 
-const tryServeFile = async (relativePath: string): Promise<Response | null> => {
+const tryServeFile = async (
+  relativePath: string,
+  status = 200
+): Promise<Response | null> => {
   const file = Bun.file(`public/${stripLeadingSlash(relativePath)}`);
   if (!(await file.exists())) {
     return null;
   }
-  return new Response(file);
+  return new Response(file, { status });
 };
 
 const toHtmlEntryPath = (canonicalPathname: string): string =>
@@ -32,10 +35,36 @@ const serveHtml = async (pathname: string): Promise<Response> => {
     return served;
   }
 
-  const notFound = await tryServeFile("404.html");
+  const notFound = await tryServeFile("404.html", 404);
   return notFound ?? new Response("Not Found", { status: 404 });
 };
 
+type ShutdownSignal = "SIGINT" | "SIGTERM";
+
+const waitForShutdownSignal = (): Promise<ShutdownSignal> => {
+  const { promise, resolve } = Promise.withResolvers<ShutdownSignal>();
+
+  const handleSigInt = (): void => {
+    cleanup();
+    resolve("SIGINT");
+  };
+
+  const handleSigTerm = (): void => {
+    cleanup();
+    resolve("SIGTERM");
+  };
+
+  const cleanup = (): void => {
+    process.off("SIGINT", handleSigInt);
+    process.off("SIGTERM", handleSigTerm);
+  };
+
+  process.on("SIGINT", handleSigInt);
+  process.on("SIGTERM", handleSigTerm);
+
+  return promise;
+};
+
 export const previewCommand = async (port: number): Promise<number> => {
   const exists = await Bun.file("public/index.html").exists();
   if (!exists) {
@@ -56,5 +85,9 @@ export const previewCommand = async (port: number): Promise<number> => {
 
   // eslint-disable-next-line no-console
   console.log(`Preview running at http://localhost:${server.port}`);
+
+  await waitForShutdownSignal();
+  server.stop(true);
+
   return 0;
 };