idcmd 0.0.10 → 0.0.12

package/src/cli/main.ts

@@ -13,30 +13,233 @@ import { parsePort } from "./normalize";
 import { readPackageVersion } from "./version";
 
 const DEFAULT_PREVIEW_PORT = 4173;
+const DEFAULT_DEV_PORT = 4000;
 
-const usage = (): string =>
+type CommandName = "init" | "dev" | "build" | "preview" | "deploy" | "client";
+
+const isCommandName = (value: string): value is CommandName =>
+  value === "init" ||
+  value === "dev" ||
+  value === "build" ||
+  value === "preview" ||
+  value === "deploy" ||
+  value === "client";
+
+const globalHelp = (): string =>
   [
     "idcmd",
     "",
+    "Static docs site CLI optimized for agent workflows.",
+    "",
     "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]",
     "",
+    "Agent Quickstart:",
+    "  1. idcmd init my-docs --yes --no-git",
+    "  2. cd my-docs && bun install",
+    `  3. idcmd dev --port ${String(DEFAULT_DEV_PORT)}`,
+    "  4. idcmd build",
+    `  5. idcmd preview --port ${String(DEFAULT_PREVIEW_PORT)}`,
+    "  6. idcmd deploy --vercel|--fly|--railway",
+    "",
+    "Commands:",
+    "  init    Scaffold a new site in a target directory",
+    "  dev     Run SSR server + Tailwind/runtime watchers",
+    "  build   Generate static output in public/",
+    "  preview Serve public/ locally with canonical routing",
+    "  deploy  Build + generate provider config files",
+    "  client  Add/update local UI/runtime baseline files",
+    "",
+    "Help:",
+    "  idcmd --help",
+    "  idcmd <command> --help",
+    "  idcmd --version",
+    "",
+  ].join("\n");
+
+const initHelp = (): string =>
+  [
+    "idcmd init",
+    "",
+    "Scaffold a new idcmd site from the default template.",
+    "",
+    "Usage:",
+    "  idcmd init [dir] [--yes] [--name <name>] [--description <text>] [--base-url <url>] [--port <port>] [--no-git] [--vercel|--fly|--railway]",
+    "",
+    "Flags:",
+    "  --yes              Non-interactive defaults",
+    "  --name             Site name in site.jsonc",
+    "  --description      Site description in site.jsonc",
+    "  --base-url         Base URL for canonicals + sitemap",
+    `  --port             Default dev script port (default: ${String(DEFAULT_DEV_PORT)})`,
+    "  --no-git           Skip `git init` in target dir",
+    "  --vercel           Generate vercel.json",
+    "  --fly              Generate fly.toml + Docker files",
+    "  --railway          Generate railway.json + Docker files",
+    "",
+    "Side effects:",
+    "  - Writes template files into target directory",
+    "  - Fails if target directory is not empty",
+    "  - Runs `git init` unless --no-git is set",
+    "",
+    "Examples:",
+    "  idcmd init my-docs --yes --no-git",
+    "  idcmd init apps/docs --yes --base-url https://docs.example.com",
+    "",
+  ].join("\n");
+
+const devHelp = (): string =>
+  [
+    "idcmd dev",
+    "",
+    "Run local development: SSR server + Tailwind + runtime bundling in watch mode.",
+    "",
+    "Usage:",
+    "  idcmd dev [--port <port>]",
+    "",
+    "Flags:",
+    `  --port             HTTP port (default: ${String(DEFAULT_DEV_PORT)})`,
+    "",
+    "Side effects:",
+    "  - Writes compiled runtime scripts to public/_idcmd/*.js",
+    "  - Writes compiled CSS to public/styles.css",
+    "",
+    "Examples:",
+    "  idcmd dev",
+    "  idcmd dev --port 4010",
+    "",
   ].join("\n");
 
+const buildHelp = (): string =>
+  [
+    "idcmd build",
+    "",
+    "Build static site output in public/.",
+    "",
+    "Usage:",
+    "  idcmd build",
+    "",
+    "What it does:",
+    "  - Compiles runtime assets from src/runtime/ to public/_idcmd/",
+    "  - Builds Tailwind CSS to public/styles.css",
+    "  - Renders markdown pages and metadata outputs (llms.txt, search index, sitemap/robots when baseUrl is set)",
+    "",
+    "Examples:",
+    "  idcmd build",
+    "",
+  ].join("\n");
+
+const previewHelp = (): string =>
+  [
+    "idcmd preview",
+    "",
+    "Serve generated public/ output locally with canonical route behavior.",
+    "",
+    "Usage:",
+    "  idcmd preview [--port <port>]",
+    "",
+    "Flags:",
+    `  --port             HTTP port (default: ${String(DEFAULT_PREVIEW_PORT)})`,
+    "",
+    "Notes:",
+    "  - Requires public/index.html (run idcmd build first)",
+    "",
+    "Examples:",
+    "  idcmd preview",
+    "  idcmd preview --port 5000",
+    "",
+  ].join("\n");
+
+const deployHelp = (): string =>
+  [
+    "idcmd deploy",
+    "",
+    "Build project and print provider-specific deployment guidance.",
+    "",
+    "Usage:",
+    "  idcmd deploy [--vercel|--fly|--railway]",
+    "",
+    "Flags (choose one provider):",
+    "  --vercel           Generate vercel.json",
+    "  --fly              Generate fly.toml + Docker files",
+    "  --railway          Generate railway.json + Docker files",
+    "",
+    "Side effects:",
+    "  - Runs idcmd build first",
+    "  - May write provider config files in project root",
+    "",
+    "Examples:",
+    "  idcmd deploy --vercel",
+    "  idcmd deploy --fly",
+    "",
+  ].join("\n");
+
+const clientHelp = (): string =>
+  [
+    "idcmd client",
+    "",
+    "Copy baseline local implementation files into src/ui/ and src/runtime/.",
+    "",
+    "Usage:",
+    "  idcmd client <add|update> <layout|right-rail|search-page|runtime|all> [--dry-run] [--yes]",
+    "",
+    "Flags:",
+    "  --dry-run          Preview changes without writing files",
+    "  --yes              Skip overwrite prompts for update mode",
+    "",
+    "Side effects:",
+    "  - add: creates missing files only",
+    "  - update: overwrites selected files (requires --yes unless --dry-run)",
+    "",
+    "Examples:",
+    "  idcmd client add all",
+    "  idcmd client update runtime --dry-run",
+    "  idcmd client update layout --yes",
+    "",
+  ].join("\n");
+
+const HELP_BUILDERS: Record<CommandName, () => string> = {
+  build: buildHelp,
+  client: clientHelp,
+  deploy: deployHelp,
+  dev: devHelp,
+  init: initHelp,
+  preview: previewHelp,
+};
+
+const commandHelp = (command: CommandName): string => HELP_BUILDERS[command]();
+
 const asStringFlag = (value: unknown): string | undefined =>
   typeof value === "string" ? value : 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 +252,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 +268,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),
@@ -72,6 +280,53 @@ const isHelpCommand = (cmd: string | null): boolean =>
 const isVersionCommand = (cmd: string): boolean =>
   cmd === "--version" || cmd === "-v";
 
+const hasSubcommandHelpFlag = (parsed: ParsedArgs): boolean =>
+  parsed.flags.help === true ||
+  parsed.positionals.includes("--help") ||
+  parsed.positionals.includes("-h");
+
+const maybeHandleGeneralHelp = (cmd: string | null): number | null => {
+  if (!isHelpCommand(cmd)) {
+    return null;
+  }
+  console.log(globalHelp());
+  return 0;
+};
+
+const maybeHandleVersion = async (
+  cmd: string | null
+): Promise<number | null> => {
+  if (!cmd || !isVersionCommand(cmd)) {
+    return null;
+  }
+  console.log(await readPackageVersion());
+  return 0;
+};
+
+const maybeHandleHelpCommand = (parsed: ParsedArgs): number | null => {
+  if (parsed.command !== "help") {
+    return null;
+  }
+  const [topic] = parsed.positionals;
+  if (topic && isCommandName(topic)) {
+    console.log(commandHelp(topic));
+    return 0;
+  }
+  console.log(globalHelp());
+  return 0;
+};
+
+const maybeHandleSubcommandHelp = (parsed: ParsedArgs): number | null => {
+  if (!parsed.command || !isCommandName(parsed.command)) {
+    return null;
+  }
+  if (!hasSubcommandHelpFlag(parsed)) {
+    return null;
+  }
+  console.log(commandHelp(parsed.command));
+  return 0;
+};
+
 export const main = async (argv: string[]): Promise<void> => {
   try {
     const code = await runMain(argv);
@@ -87,7 +342,7 @@ const runMain = async (argv: string[]): Promise<number> => {
   const parsed = parseArgs(argv);
   const cmd = parsed.command;
 
-  const metaCode = await maybeHandleMetaCommand(cmd);
+  const metaCode = await maybeHandleMetaCommand(parsed);
   if (metaCode !== null) {
     return metaCode;
   }
@@ -101,19 +356,16 @@ const runMain = async (argv: string[]): Promise<number> => {
 };
 
 const maybeHandleMetaCommand = async (
-  cmd: string | null
+  parsed: ParsedArgs
 ): Promise<number | null> => {
-  if (isHelpCommand(cmd)) {
-    console.log(usage());
-    return 0;
-  }
-
-  if (cmd && isVersionCommand(cmd)) {
-    console.log(await readPackageVersion());
-    return 0;
-  }
+  const cmd = parsed.command;
 
-  return null;
+  return (
+    maybeHandleGeneralHelp(cmd) ??
+    (await maybeHandleVersion(cmd)) ??
+    maybeHandleHelpCommand(parsed) ??
+    maybeHandleSubcommandHelp(parsed)
+  );
 };
 
 const resolveCommandHandler = (
@@ -127,6 +379,6 @@ const resolveCommandHandler = (
 
 const handleUnknownCommand = (cmd: string | null): number => {
   console.error(`Unknown command: ${cmd ?? "(none)"}`);
-  console.log(usage());
+  console.log(globalHelp());
   return 1;
 };

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;