idcmd 0.0.9 → 0.0.11

package/README.md

@@ -18,10 +18,24 @@ 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
 ```
 
+### 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 (V1)
 
 - `content/<slug>.md` -> `/<slug>/` (`index.md` -> `/`)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "idcmd",
-  "version": "0.0.9",
+  "version": "0.0.11",
   "repository": {
     "type": "git",
     "url": "https://github.com/rustydotwtf/idcmd"

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/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;
 }
 
@@ -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,
   };
 };
@@ -280,6 +314,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/main.ts

@@ -19,11 +19,11 @@ const usage = (): string =>
     "idcmd",
     "",
     "Usage:",
-    "  idcmd init [dir] [--yes] [--name <name>] [--description <text>] [--base-url <url>] [--port <port>] [--no-git]",
+    "  idcmd init [dir] [--yes] [--name <name>] [--description <text>] [--base-url <url>] [--port <port>] [--no-git] [--vercel|--fly|--railway]",
     "  idcmd dev [--port <port>]",
     "  idcmd build",
     "  idcmd preview [--port <port>]",
-    "  idcmd deploy",
+    "  idcmd deploy [--vercel|--fly|--railway]",
     "  idcmd client <add|update> <layout|right-rail|search-page|runtime|all> [--dry-run] [--yes]",
     "",
   ].join("\n");
@@ -34,9 +34,26 @@ const asStringFlag = (value: unknown): string | undefined =>
 const asBooleanFlag = (value: unknown): boolean =>
   value === true || value === "true";
 
+const asOptionalBooleanFlag = (value: unknown): boolean | undefined => {
+  if (value === false || value === "false") {
+    return false;
+  }
+  return asBooleanFlag(value) ? true : undefined;
+};
+
 const handleInit = (parsed: ParsedArgs): Promise<number> => {
   const [dir] = parsed.positionals;
-  return initCommand(dir, parsed.flags);
+  return initCommand(dir, {
+    "base-url": asStringFlag(parsed.flags["base-url"]),
+    description: asStringFlag(parsed.flags.description),
+    fly: asBooleanFlag(parsed.flags.fly),
+    git: asOptionalBooleanFlag(parsed.flags.git),
+    name: asStringFlag(parsed.flags.name),
+    port: asStringFlag(parsed.flags.port),
+    railway: asBooleanFlag(parsed.flags.railway),
+    vercel: asBooleanFlag(parsed.flags.vercel),
+    yes: asBooleanFlag(parsed.flags.yes),
+  });
 };
 
 const handleDev = (parsed: ParsedArgs): Promise<number> =>
@@ -49,7 +66,12 @@ const handlePreview = (parsed: ParsedArgs): Promise<number> => {
   return previewCommand(port);
 };
 
-const handleDeploy = (): Promise<number> => deployCommand();
+const handleDeploy = (parsed: ParsedArgs): Promise<number> =>
+  deployCommand({
+    fly: asBooleanFlag(parsed.flags.fly),
+    railway: asBooleanFlag(parsed.flags.railway),
+    vercel: asBooleanFlag(parsed.flags.vercel),
+  });
 
 const handleClient = (parsed: ParsedArgs): Promise<number> =>
   clientCommand(parsed.positionals, {
@@ -60,7 +82,7 @@ const handleClient = (parsed: ParsedArgs): Promise<number> =>
 const handlers: Record<string, (parsed: ParsedArgs) => Promise<number>> = {
   build: () => handleBuild(),
   client: (parsed) => handleClient(parsed),
-  deploy: () => handleDeploy(),
+  deploy: (parsed) => handleDeploy(parsed),
   dev: (parsed) => handleDev(parsed),
   init: (parsed) => handleInit(parsed),
   preview: (parsed) => handlePreview(parsed),

package/src/cli/prompt.ts

@@ -72,3 +72,108 @@ export const promptOptionalText = async (
   const trimmed = raw.trim();
   return trimmed.length > 0 ? trimmed : defaultValue;
 };
+
+export interface PromptSelectOption<T extends string> {
+  label: string;
+  value: T;
+}
+
+const parseNumericChoice = (
+  raw: string,
+  optionsLength: number
+): number | null => {
+  const parsed = Number(raw);
+  if (!Number.isInteger(parsed)) {
+    return null;
+  }
+  const index = parsed - 1;
+  if (index < 0 || index >= optionsLength) {
+    return null;
+  }
+  return index;
+};
+
+const findOptionByValue = <T extends string>(
+  options: readonly PromptSelectOption<T>[],
+  raw: string
+): PromptSelectOption<T> | null => {
+  const direct = options.find((option) => option.value === raw);
+  return direct ?? null;
+};
+
+const getDefaultOptionIndex = <T extends string>(
+  options: readonly PromptSelectOption<T>[],
+  defaultValue: T
+): number => {
+  if (options.length === 0) {
+    throw new Error("promptSelect requires at least one option.");
+  }
+  const defaultIndex = options.findIndex(
+    (option) => option.value === defaultValue
+  );
+  if (defaultIndex === -1) {
+    throw new Error(
+      `promptSelect default value "${defaultValue}" is not in options.`
+    );
+  }
+  return defaultIndex;
+};
+
+const printSelectPrompt = <T extends string>(args: {
+  defaultIndex: number;
+  options: readonly PromptSelectOption<T>[];
+  question: string;
+}): void => {
+  process.stdout.write(`${args.question}\n`);
+  for (const [index, option] of args.options.entries()) {
+    const suffix = index === args.defaultIndex ? " (default)" : "";
+    process.stdout.write(`  ${String(index + 1)}. ${option.label}${suffix}\n`);
+  }
+};
+
+const resolveSelectedValue = <T extends string>(args: {
+  defaultValue: T;
+  input: string;
+  options: readonly PromptSelectOption<T>[];
+}): T | null => {
+  if (args.input.length === 0) {
+    return args.defaultValue;
+  }
+  const numericChoice = parseNumericChoice(args.input, args.options.length);
+  if (numericChoice !== null) {
+    return args.options[numericChoice]?.value ?? args.defaultValue;
+  }
+  const valueChoice = findOptionByValue(args.options, args.input);
+  return valueChoice?.value ?? null;
+};
+
+const readSelection = async <T extends string>(args: {
+  defaultIndex: number;
+  defaultValue: T;
+  options: readonly PromptSelectOption<T>[];
+}): Promise<T> => {
+  while (true) {
+    const input = await readLine(
+      `Select [1-${String(args.options.length)}] (${String(args.defaultIndex + 1)}): `
+    );
+    const value = resolveSelectedValue({
+      defaultValue: args.defaultValue,
+      input: input.trim(),
+      options: args.options,
+    });
+    if (value !== null) {
+      return value;
+    }
+    process.stdout.write("Invalid selection. Enter a number from the list.\n");
+  }
+};
+
+export const promptSelect = <T extends string>(
+  question: string,
+  options: readonly PromptSelectOption<T>[],
+  defaultValue: T
+): Promise<T> => {
+  const defaultIndex = getDefaultOptionIndex(options, defaultValue);
+  printSelectPrompt({ defaultIndex, options, question });
+  return readSelection({ defaultIndex, defaultValue, options });
+};

package/src/cli/provider-files.ts

@@ -0,0 +1,225 @@
+import type { ResolvedCachePolicy } from "../site/cache";
+import type { DeployProvider } from "./provider";
+
+import { ensureDir } from "./fs";
+import { dirname, joinPath } from "./path";
+
+interface ProviderFileOptions {
+  cachePolicy: ResolvedCachePolicy;
+  packageName: string;
+  targetDir: string;
+}
+
+const DOCKERFILE_PATH = "Dockerfile";
+const DOCKERIGNORE_PATH = ".dockerignore";
+const FLY_CONFIG_PATH = "fly.toml";
+const RAILWAY_CONFIG_PATH = "railway.json";
+const VERCEL_CONFIG_PATH = "vercel.json";
+
+const DOCKERFILE = `FROM oven/bun:1
+
+WORKDIR /app
+
+COPY package.json bun.lock* ./
+RUN bun install --frozen-lockfile
+
+COPY . .
+
+RUN bun run build
+
+ENV NODE_ENV=production
+ENV PORT=8080
+
+EXPOSE 8080
+
+CMD ["bun", "src/server.ts"]
+`;
+
+const DOCKERIGNORE = `.git
+.github
+.gitignore
+node_modules
+public
+.env
+.env.*
+`;
+
+const sanitizeFlyAppName = (value: string): string => {
+  const normalized = value
+    .toLowerCase()
+    .replaceAll(/[^a-z0-9-]/g, "-")
+    .replaceAll(/-+/g, "-")
+    .replaceAll(/^-+|-+$/g, "");
+  if (normalized.length === 0) {
+    return "idcmd-app";
+  }
+  return normalized.slice(0, 63);
+};
+
+const buildCacheControl = (args: {
+  browserCacheControl: string;
+  edgeCacheControl: string | null;
+}): string =>
+  args.edgeCacheControl
+    ? `${args.browserCacheControl}, ${args.edgeCacheControl}`
+    : args.browserCacheControl;
+
+const createVercelHeaders = (
+  cachePolicy: ResolvedCachePolicy
+): {
+  headers: { key: string; value: string }[];
+  source: string;
+}[] => {
+  const htmlHeaders = [
+    {
+      key: "Cache-Control",
+      value: buildCacheControl({
+        browserCacheControl: cachePolicy.html.browserCacheControl,
+        edgeCacheControl: null,
+      }),
+    },
+  ];
+  if (cachePolicy.html.edgeCacheControl) {
+    htmlHeaders.push({
+      key: "Vercel-CDN-Cache-Control",
+      value: cachePolicy.html.edgeCacheControl,
+    });
+  }
+
+  return [
+    { headers: htmlHeaders, source: "/(.*)" },
+    {
+      headers: [
+        { key: "Cache-Control", value: cachePolicy.static.cacheControl },
+      ],
+      source: "/(.*\\..*)",
+    },
+  ];
+};
+
+const createVercelConfig = (cachePolicy: ResolvedCachePolicy): string =>
+  `${JSON.stringify(
+    {
+      $schema: "https://openapi.vercel.sh/vercel.json",
+      buildCommand: "bun run build",
+      bunVersion: "1.x",
+      headers: createVercelHeaders(cachePolicy),
+      installCommand: "bun install",
+      outputDirectory: "public",
+    },
+    null,
+    2
+  )}\n`;
+
+const createFlyToml = (packageName: string): string =>
+  `app = "${sanitizeFlyAppName(packageName)}"
+primary_region = "iad"
+
+[env]
+  NODE_ENV = "production"
+  PORT = "8080"
+
+[http_service]
+  internal_port = 8080
+  force_https = true
+  auto_stop_machines = "stop"
+  auto_start_machines = true
+  min_machines_running = 0
+  processes = ["app"]
+
+  [[http_service.checks]]
+    grace_period = "10s"
+    interval = "30s"
+    method = "GET"
+    timeout = "5s"
+    path = "/health"
+`;
+
+const createRailwayConfig = (): string =>
+  `${JSON.stringify(
+    {
+      $schema: "https://railway.com/railway.schema.json",
+      build: {
+        builder: "DOCKERFILE",
+      },
+      deploy: {
+        healthcheckPath: "/health",
+        healthcheckTimeout: 120,
+        restartPolicyMaxRetries: 10,
+        restartPolicyType: "ON_FAILURE",
+        startCommand: "bun src/server.ts",
+      },
+    },
+    null,
+    2
+  )}\n`;
+
+const writeFile = async (
+  targetDir: string,
+  relativePath: string,
+  text: string
+): Promise<void> => {
+  const path = joinPath(targetDir, relativePath);
+  await ensureDir(dirname(path));
+  await Bun.write(path, text);
+};
+
+const writeVercelFiles = async (
+  args: ProviderFileOptions
+): Promise<string[]> => {
+  await writeFile(
+    args.targetDir,
+    VERCEL_CONFIG_PATH,
+    createVercelConfig(args.cachePolicy)
+  );
+  return [VERCEL_CONFIG_PATH];
+};
+
+const writeFlyFiles = async (args: ProviderFileOptions): Promise<string[]> => {
+  await writeFile(args.targetDir, DOCKERFILE_PATH, DOCKERFILE);
+  await writeFile(args.targetDir, DOCKERIGNORE_PATH, DOCKERIGNORE);
+  await writeFile(
+    args.targetDir,
+    FLY_CONFIG_PATH,
+    createFlyToml(args.packageName)
+  );
+  return [DOCKERFILE_PATH, DOCKERIGNORE_PATH, FLY_CONFIG_PATH];
+};
+
+const writeRailwayFiles = async (
+  args: ProviderFileOptions
+): Promise<string[]> => {
+  await writeFile(args.targetDir, DOCKERFILE_PATH, DOCKERFILE);
+  await writeFile(args.targetDir, DOCKERIGNORE_PATH, DOCKERIGNORE);
+  await writeFile(args.targetDir, RAILWAY_CONFIG_PATH, createRailwayConfig());
+  return [DOCKERFILE_PATH, DOCKERIGNORE_PATH, RAILWAY_CONFIG_PATH];
+};
+
+export const generateProviderFiles = (args: {
+  cachePolicy: ResolvedCachePolicy;
+  packageName: string;
+  provider: DeployProvider;
+  targetDir: string;
+}): Promise<string[]> => {
+  const options = {
+    cachePolicy: args.cachePolicy,
+    packageName: args.packageName,
+    targetDir: args.targetDir,
+  };
+
+  if (args.provider === "vercel") {
+    return writeVercelFiles(options);
+  }
+  if (args.provider === "fly") {
+    return writeFlyFiles(options);
+  }
+  return writeRailwayFiles(options);
+};
+
+export const providerConfigPaths = {
+  dockerfile: DOCKERFILE_PATH,
+  dockerignore: DOCKERIGNORE_PATH,
+  flyToml: FLY_CONFIG_PATH,
+  railwayJson: RAILWAY_CONFIG_PATH,
+  vercelJson: VERCEL_CONFIG_PATH,
+} as const;

package/src/cli/provider.ts

@@ -0,0 +1,36 @@
+export type Provider = "none" | "vercel" | "fly" | "railway";
+export type DeployProvider = Exclude<Provider, "none">;
+
+export interface ProviderFlags {
+  fly?: boolean;
+  railway?: boolean;
+  vercel?: boolean;
+}
+
+const DEPLOY_PROVIDERS: readonly DeployProvider[] = [
+  "vercel",
+  "fly",
+  "railway",
+];
+
+const isFlagEnabled = (value: boolean | undefined): boolean => value === true;
+
+const selectedProviders = (flags: ProviderFlags): DeployProvider[] =>
+  DEPLOY_PROVIDERS.filter((provider) => isFlagEnabled(flags[provider]));
+
+const formatProviderFlags = (providers: readonly DeployProvider[]): string =>
+  providers.map((provider) => `--${provider}`).join(" ");
+
+export const resolveProviderFromFlags = (flags: ProviderFlags): Provider => {
+  const selected = selectedProviders(flags);
+  if (selected.length > 1) {
+    throw new Error(
+      `Choose exactly one provider. Received ${formatProviderFlags(selected)}.`
+    );
+  }
+  return selected[0] ?? "none";
+};
+
+export const isDeployProvider = (
+  provider: Provider
+): provider is DeployProvider => provider !== "none";

package/src/render/layout.tsx

@@ -151,7 +151,7 @@ const TopNavbar = ({
       <div class="flex items-center gap-4">
         <a
           href="/"
-          class="text-sm font-medium tracking-tight font-mono md:hidden"
+          class="text-sm font-medium tracking-tight font-mono lg:hidden"
           data-prefetch="hover"
         >
           <span class="text-muted-foreground">~/</span>

package/src/server/headers.ts

@@ -1,10 +1,29 @@
-export const createHtmlCacheHeaders = (isDev: boolean): HeadersInit => ({
+import type { ResolvedCachePolicy } from "../site/cache";
+
+const combineCacheControl = (args: {
+  browserCacheControl: string;
+  edgeCacheControl: string | null;
+}): string =>
+  args.edgeCacheControl
+    ? `${args.browserCacheControl}, ${args.edgeCacheControl}`
+    : args.browserCacheControl;
+
+export const createHtmlCacheHeaders = (
+  isDev: boolean,
+  cachePolicy: ResolvedCachePolicy
+): HeadersInit => ({
   "Cache-Control": isDev
     ? "no-cache"
-    : "s-maxage=60, stale-while-revalidate=3600",
+    : combineCacheControl({
+        browserCacheControl: cachePolicy.html.browserCacheControl,
+        edgeCacheControl: cachePolicy.html.edgeCacheControl,
+      }),
   "Content-Type": "text/html; charset=utf-8",
 });
 
-export const createStaticCacheHeaders = (isDev: boolean): HeadersInit => ({
-  "Cache-Control": isDev ? "no-cache" : "public, max-age=31536000, immutable",
+export const createStaticCacheHeaders = (
+  isDev: boolean,
+  cachePolicy: ResolvedCachePolicy
+): HeadersInit => ({
+  "Cache-Control": isDev ? "no-cache" : cachePolicy.static.cacheControl,
 });

package/src/server.ts

@@ -15,6 +15,8 @@ import {
 import { createLiveReload } from "./server/live-reload";
 import { serveStaticFile } from "./server/static";
 import { handleUserRouteRequest } from "./server/user-routes";
+import { resolveCachePolicy } from "./site/cache";
+import { loadSiteConfig } from "./site/config";
 import {
   getRedirectForCanonicalHtmlPath,
   isFileLikePathname,
@@ -30,9 +32,12 @@ const isDev = process.env.NODE_ENV !== "production";
 const LIVE_RELOAD_POLL_MS = 250;
 const MIN_SEARCH_QUERY_LENGTH = 2;
 const MAX_SEARCH_RESULTS = 50;
+const HEALTHCHECK_PATH = "/health";
 
-const cacheHeaders = createHtmlCacheHeaders(isDev);
-const staticCacheHeaders = createStaticCacheHeaders(isDev);
+const siteConfig = await loadSiteConfig();
+const cachePolicy = resolveCachePolicy(siteConfig.cache);
+const cacheHeaders = createHtmlCacheHeaders(isDev, cachePolicy);
+const staticCacheHeaders = createStaticCacheHeaders(isDev, cachePolicy);
 
 const withQueryString = (pathname: string, search: string): string =>
   search ? `${pathname}${search}` : pathname;
@@ -74,6 +79,20 @@ const handleLlmsTxt = async (path: string): Promise<Response | undefined> => {
   });
 };
 
+const handleHealthRequest = (path: string): Response | undefined => {
+  if (path !== HEALTHCHECK_PATH) {
+    return undefined;
+  }
+
+  return new Response("ok", {
+    headers: {
+      "Cache-Control": "no-cache",
+      "Content-Type": "text/plain; charset=utf-8",
+    },
+    status: 200,
+  });
+};
+
 const handleMarkdownRequest = async (
   path: string
 ): Promise<Response | undefined> => {
@@ -202,6 +221,7 @@ const handleRequest = async (
 
   return (
     liveReloadUpgrade ??
+    handleHealthRequest(path) ??
     (await handleLlmsTxt(path)) ??
     (await handleRobotsTxt(url, seoEnv)) ??
     (await handleSitemapXml(url, seoEnv)) ??

package/src/site/cache.ts

@@ -0,0 +1,108 @@
+import { z } from "zod";
+
+const MAX_EDGE_CACHE_SECONDS = 7 * 24 * 60 * 60;
+const MAX_STALE_SECONDS = 30 * 24 * 60 * 60;
+
+const HTML_REVALIDATE_CACHE_CONTROL = "public, max-age=0, must-revalidate";
+const STATIC_REVALIDATE_CACHE_CONTROL = "public, max-age=0, must-revalidate";
+const STATIC_IMMUTABLE_CACHE_CONTROL = "public, max-age=31536000, immutable";
+const NO_STORE_CACHE_CONTROL = "no-store";
+
+export const CachePresetSchema = z.enum(["fresh", "balanced", "static"]);
+export type CachePreset = z.infer<typeof CachePresetSchema>;
+
+export const CacheHtmlConfigSchema = z
+  .object({
+    sMaxAgeSeconds: z
+      .number()
+      .int()
+      .min(0)
+      .max(MAX_EDGE_CACHE_SECONDS)
+      .optional(),
+    staleWhileRevalidateSeconds: z
+      .number()
+      .int()
+      .min(0)
+      .max(MAX_STALE_SECONDS)
+      .optional(),
+  })
+  .strict();
+export type CacheHtmlConfig = z.infer<typeof CacheHtmlConfigSchema>;
+
+export const CacheConfigSchema = z
+  .object({
+    html: CacheHtmlConfigSchema.optional(),
+    preset: CachePresetSchema.optional(),
+  })
+  .strict();
+export type CacheConfig = z.infer<typeof CacheConfigSchema>;
+
+export interface ResolvedCachePolicy {
+  html: {
+    browserCacheControl: string;
+    edgeCacheControl: string | null;
+  };
+  preset: CachePreset;
+  static: {
+    cacheControl: string;
+  };
+}
+
+interface HtmlEdgePolicy {
+  sMaxAgeSeconds: number;
+  staleWhileRevalidateSeconds: number;
+}
+
+const DEFAULT_HTML_EDGE_POLICY: HtmlEdgePolicy = {
+  sMaxAgeSeconds: 60,
+  staleWhileRevalidateSeconds: 3600,
+};
+const DEFAULT_PRESET: CachePreset = "static";
+
+const formatEdgeCacheControl = (policy: HtmlEdgePolicy): string =>
+  `s-maxage=${String(policy.sMaxAgeSeconds)}, stale-while-revalidate=${String(policy.staleWhileRevalidateSeconds)}`;
+
+const resolveHtmlEdgePolicy = (
+  config: CacheConfig | undefined
+): HtmlEdgePolicy => ({
+  sMaxAgeSeconds:
+    config?.html?.sMaxAgeSeconds ?? DEFAULT_HTML_EDGE_POLICY.sMaxAgeSeconds,
+  staleWhileRevalidateSeconds:
+    config?.html?.staleWhileRevalidateSeconds ??
+    DEFAULT_HTML_EDGE_POLICY.staleWhileRevalidateSeconds,
+});
+
+const resolvePreset = (config: CacheConfig | undefined): CachePreset =>
+  config?.preset ?? DEFAULT_PRESET;
+
+export const resolveCachePolicy = (
+  config?: CacheConfig
+): ResolvedCachePolicy => {
+  const preset = resolvePreset(config);
+
+  if (preset === "fresh") {
+    return {
+      html: {
+        browserCacheControl: NO_STORE_CACHE_CONTROL,
+        edgeCacheControl: null,
+      },
+      preset,
+      static: { cacheControl: NO_STORE_CACHE_CONTROL },
+    };
+  }
+
+  const edgePolicy = resolveHtmlEdgePolicy(config);
+  return {
+    html: {
+      browserCacheControl: HTML_REVALIDATE_CACHE_CONTROL,
+      edgeCacheControl: formatEdgeCacheControl(edgePolicy),
+    },
+    preset,
+    static: {
+      cacheControl:
+        preset === "static"
+          ? STATIC_IMMUTABLE_CACHE_CONTROL
+          : STATIC_REVALIDATE_CACHE_CONTROL,
+    },
+  };
+};

package/src/site/config.ts

@@ -1,5 +1,9 @@
 import { ZodError, z } from "zod";
 
+import type { CacheConfig } from "./cache";
+
+import { CacheConfigSchema } from "./cache";
+
 export const SearchScopeSchema = z.enum([
   "full",
   "title",
@@ -64,6 +68,7 @@ export type GroupConfig = z.infer<typeof GroupConfigSchema>;
 export const SiteConfigSchema = z
   .object({
     baseUrl: z.string().url().optional(),
+    cache: CacheConfigSchema.optional(),
     description: z.string(),
     groups: z.array(GroupConfigSchema).optional(),
     name: z.string().min(1),
@@ -146,12 +151,31 @@ const normalizeBaseUrl = (baseUrl: string): string | undefined => {
   }
 };
 
-const resolveBaseUrlFromEnv = (): string | undefined => {
+const resolveExplicitBaseUrlFromEnv = (): string | undefined => {
   const explicit = process.env.SITE_BASE_URL;
   if (explicit) {
     return normalizeBaseUrl(explicit);
   }
+  return undefined;
+};
+
+const resolveRailwayBaseUrlFromEnv = (): string | undefined => {
+  const railwayDomain = process.env.RAILWAY_PUBLIC_DOMAIN;
+  if (railwayDomain) {
+    return normalizeBaseUrl(`https://${railwayDomain}`);
+  }
+  return undefined;
+};
+
+const resolveFlyBaseUrlFromEnv = (): string | undefined => {
+  const flyApp = process.env.FLY_APP_NAME;
+  if (flyApp) {
+    return normalizeBaseUrl(`https://${flyApp}.fly.dev`);
+  }
+  return undefined;
+};
 
+const resolveVercelBaseUrlFromEnv = (): string | undefined => {
   // Vercel provides hostnames without protocol.
   const vercelUrl =
     process.env.VERCEL_URL ??
@@ -161,10 +185,15 @@ const resolveBaseUrlFromEnv = (): string | undefined => {
   if (vercelUrl) {
     return normalizeBaseUrl(`https://${vercelUrl}`);
   }
-
   return undefined;
 };
 
+const resolveBaseUrlFromEnv = (): string | undefined =>
+  resolveExplicitBaseUrlFromEnv() ??
+  resolveRailwayBaseUrlFromEnv() ??
+  resolveFlyBaseUrlFromEnv() ??
+  resolveVercelBaseUrlFromEnv();
+
 const resolveBaseUrl = (baseUrl: string | undefined): string | undefined => {
   const normalizedConfigUrl = baseUrl ? normalizeBaseUrl(baseUrl) : undefined;
   const envUrl = resolveBaseUrlFromEnv();
@@ -190,7 +219,11 @@ const formatSiteConfigZodError = (
   return `${configPath} validation failed:\n${lines.join("\n")}`;
 };
 
-const DEFAULT_SITE_CONFIG: SiteConfig = { description: "", name: "idcmd" };
+const DEFAULT_SITE_CONFIG: SiteConfig = {
+  cache: { preset: "static" },
+  description: "",
+  name: "idcmd",
+};
 
 const parseSiteConfigJsonc = (configPath: string, text: string): unknown => {
   try {
@@ -229,8 +262,17 @@ export const loadSiteConfig = async (): Promise<SiteConfig> => {
   const text = await file.text();
   const raw = parseSiteConfigJsonc(configPath, text);
   const parsed = parseSiteConfigUnknown(configPath, raw);
-  return { ...parsed, baseUrl: resolveBaseUrl(parsed.baseUrl) };
+  return {
+    ...parsed,
+    baseUrl: resolveBaseUrl(parsed.baseUrl),
+    cache: resolveCacheConfig(parsed.cache),
+  };
 };
 
 export const getSearchScope = (siteConfig: SiteConfig): SearchScope =>
   siteConfig.search?.scope ?? "full";
+
+const resolveCacheConfig = (cache: CacheConfig | undefined): CacheConfig => ({
+  html: cache?.html,
+  preset: cache?.preset ?? "static",
+});

package/templates/default/README.md

@@ -43,10 +43,12 @@ idcmd client update runtime --yes
 These commands copy the latest baseline implementations from `idcmd` into `src/ui/` and `src/runtime/`.
 Runtime files in `src/runtime/` are compiled automatically by `idcmd dev` and `idcmd build`.
 
-## Deploy (Vercel static)
+## Deploy
 
 ```bash
-bun run build
+idcmd deploy --vercel
+idcmd deploy --fly
+idcmd deploy --railway
 ```
 
-This produces a static `public/` directory for Vercel.
+Use one provider flag at a time to generate deployment files.

package/templates/default/scripts/check.ts

@@ -32,7 +32,6 @@ const LINT_TARGETS = [
   "README.md",
   "package.json",
   "tsconfig.json",
-  "vercel.json",
   ".oxlintrc.json",
   ".oxfmtrc.jsonc",
   "scripts",

package/templates/default/site.jsonc

@@ -1,6 +1,16 @@
 {
   "name": "__IDCMD_SITE_NAME__",
   "description": "__IDCMD_SITE_DESCRIPTION__",
+  "cache": {
+    // "fresh" | "balanced" | "static"
+    "preset": "static",
+
+    // Optional HTML edge cache overrides
+    // "html": {
+    //   "sMaxAgeSeconds": 60,
+    //   "staleWhileRevalidateSeconds": 3600,
+    // },
+  },
   "baseUrl": "__IDCMD_SITE_BASE_URL__",
   "groups": [{ "id": "main", "label": "Navigation", "order": 1 }],
   "search": {

package/templates/default/src/ui/layout.tsx

@@ -104,7 +104,7 @@ const TopNavbar = ({
       <div class="flex items-center gap-4">
         <a
           href="/"
-          class="text-sm font-mono font-medium tracking-tight md:hidden"
+          class="text-sm font-mono font-medium tracking-tight lg:hidden"
           data-prefetch="hover"
         >
           <span class="text-muted-foreground">~/</span>

package/templates/default/styles/tailwind.css

@@ -151,7 +151,7 @@ header {
   display: none;
 }
 
-@media (min-width: 768px) {
+@media (min-width: 1024px) {
   .sidebar {
     position: fixed;
     top: 0;
@@ -185,7 +185,7 @@ header {
   flex-direction: column;
 }
 
-@media (min-width: 768px) {
+@media (min-width: 1024px) {
   .main-wrapper {
     margin-left: var(--sidebar-width);
   }

package/templates/default/vercel.json

@@ -1,7 +0,0 @@
-{
-  "$schema": "https://openapi.vercel.sh/vercel.json",
-  "buildCommand": "bun run build",
-  "outputDirectory": "public",
-  "installCommand": "bun install",
-  "bunVersion": "1.x"
-}