idcmd 0.0.4 → 0.0.6

package/templates/default/README.md

@@ -2,6 +2,8 @@
 
 Everything you edit lives in `site/`.
 
+This starter is intentionally opinionated for AI-friendly markdown sites.
+
 ## Quickstart
 
 ```bash
@@ -9,14 +11,35 @@ bun install
 bun run dev
 ```
 
+## CI Smoke
+
+```bash
+bun run check
+bun run smoke
+```
+
 ## Layout
 
 - `site/content/` markdown pages (`index.md` -> `/`, `about.md` -> `/about/`)
+- `site/client/` local UI implementation (`layout.tsx`, `right-rail.tsx`, `search-page.tsx`)
+- `site/client/runtime/` local browser runtime TS (`*_idcmd` scripts compile from here)
 - `site/styles/tailwind.css` Tailwind entrypoint (compiled to `site/public/styles.css`)
 - `site/public/` static assets
 - `site/server/routes/` file-based server routes (dev/server-host only)
 - `site/site.jsonc` site configuration
 
+## Sync Local Client Files
+
+```bash
+idcmd client add all
+idcmd client update all --dry-run
+idcmd client update layout --yes
+idcmd client update runtime --yes
+```
+
+These commands copy the latest baseline implementations from `idcmd` into `site/client/`.
+Runtime files in `site/client/runtime/` are compiled automatically by `idcmd dev` and `idcmd build`.
+
 ## Deploy (Vercel static)
 
 ```bash

package/templates/default/package.json

@@ -7,7 +7,8 @@
     "build": "idcmd build",
     "preview": "idcmd preview",
     "deploy": "idcmd deploy",
-    "check": "ultracite check && bun run typecheck && bun run test",
+    "check": "bun run scripts/check.ts",
+    "smoke": "bun run scripts/smoke.ts",
     "test": "bun test",
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "fix": "ultracite fix"

package/templates/default/scripts/check-internal.ts

@@ -0,0 +1,56 @@
+interface InternalCheck {
+  description: string;
+  run: () => Promise<boolean>;
+}
+
+const fileExists = (path: string): Promise<boolean> => Bun.file(path).exists();
+
+const checks: InternalCheck[] = [
+  {
+    description: "package.json must exist at the project root",
+    run: () => fileExists("package.json"),
+  },
+  {
+    description: "site config must exist (site/site.jsonc or site.jsonc)",
+    run: async () =>
+      (await fileExists("site/site.jsonc")) || (await fileExists("site.jsonc")),
+  },
+  {
+    description:
+      "tailwind input must exist (site/styles/tailwind.css or content/styles.css)",
+    run: async () =>
+      (await fileExists("site/styles/tailwind.css")) ||
+      (await fileExists("content/styles.css")),
+  },
+];
+
+const runInternalChecks = async (): Promise<string[]> => {
+  const failures: string[] = [];
+
+  for (const check of checks) {
+    // eslint-disable-next-line no-await-in-loop
+    const ok = await check.run();
+    if (!ok) {
+      failures.push(check.description);
+    }
+  }
+
+  return failures;
+};
+
+const main = async (): Promise<number> => {
+  const failures = await runInternalChecks();
+  if (failures.length === 0) {
+    console.log("Internal checks passed.");
+    return 0;
+  }
+
+  console.error("Internal checks failed:");
+  for (const failure of failures) {
+    console.error(`- ${failure}`);
+  }
+  return 1;
+};
+
+const code = await main();
+process.exit(code);

package/templates/default/scripts/check.ts

@@ -0,0 +1,318 @@
+type StepStatus = "pass" | "fail";
+
+export interface CheckStep {
+  command: string[];
+  id: string;
+  name: string;
+}
+
+export interface StepResult {
+  durationMs: number;
+  output: string;
+  status: StepStatus;
+  step: CheckStep;
+}
+
+interface TruncatedOutput {
+  omittedLines: number;
+  text: string;
+}
+
+interface StepCounts {
+  failed: number;
+  passed: number;
+  status: StepStatus;
+}
+
+const LINT_CONFIG_ERROR =
+  "No linter configuration found. Run `bun x ultracite init` once in this project.";
+const NO_TESTS_MESSAGE = "No tests found; skipping test step.";
+const MAX_OUTPUT_LINES = 120;
+const ROOT_TEST_FILE_PATTERNS = [
+  "*.test.ts",
+  "*.test.tsx",
+  "*.test.js",
+  "*.test.jsx",
+  "*_test_*.ts",
+  "*_test_*.tsx",
+  "*_test_*.js",
+  "*_test_*.jsx",
+  "*.spec.ts",
+  "*.spec.tsx",
+  "*.spec.js",
+  "*.spec.jsx",
+  "*_spec_*.ts",
+  "*_spec_*.tsx",
+  "*_spec_*.js",
+  "*_spec_*.jsx",
+];
+const NESTED_TEST_FILE_PATTERNS = [
+  "**/*.test.ts",
+  "**/*.test.tsx",
+  "**/*.test.js",
+  "**/*.test.jsx",
+  "**/*_test_*.ts",
+  "**/*_test_*.tsx",
+  "**/*_test_*.js",
+  "**/*_test_*.jsx",
+  "**/*.spec.ts",
+  "**/*.spec.tsx",
+  "**/*.spec.js",
+  "**/*.spec.jsx",
+  "**/*_spec_*.ts",
+  "**/*_spec_*.tsx",
+  "**/*_spec_*.js",
+  "**/*_spec_*.jsx",
+];
+const TEST_SOURCE_DIRS = ["site", "scripts", "src", "tests"];
+
+const buildScopedTestFilePatterns = (): string[] => {
+  const patterns = [...ROOT_TEST_FILE_PATTERNS];
+
+  for (const dir of TEST_SOURCE_DIRS) {
+    for (const nestedPattern of NESTED_TEST_FILE_PATTERNS) {
+      patterns.push(`${dir}/${nestedPattern}`);
+    }
+  }
+
+  return patterns;
+};
+const SCOPED_TEST_FILE_PATTERNS = buildScopedTestFilePatterns();
+
+const steps: CheckStep[] = [
+  {
+    command: [process.execPath, "scripts/check-internal.ts"],
+    id: "internal",
+    name: "Internal",
+  },
+  {
+    command: [process.execPath, "x", "ultracite", "check"],
+    id: "lint",
+    name: "Lint",
+  },
+  {
+    command: [process.execPath, "run", "typecheck"],
+    id: "typecheck",
+    name: "Typecheck",
+  },
+  {
+    command: [process.execPath, "run", "test"],
+    id: "tests",
+    name: "Tests",
+  },
+];
+
+const hasAnyLinterConfig = async (): Promise<boolean> => {
+  const candidates = [
+    ".oxlintrc.json",
+    "eslint.config.js",
+    "eslint.config.cjs",
+    "eslint.config.mjs",
+    "eslint.config.ts",
+    "eslint.config.cts",
+    "eslint.config.mts",
+  ];
+
+  for (const file of candidates) {
+    // eslint-disable-next-line no-await-in-loop
+    if (await Bun.file(file).exists()) {
+      return true;
+    }
+  }
+
+  return false;
+};
+
+const hasAnyFilesMatching = async (pattern: string): Promise<boolean> => {
+  const glob = new Bun.Glob(pattern);
+  for await (const _path of glob.scan(".")) {
+    return true;
+  }
+  return false;
+};
+
+const hasAnyTestFiles = async (): Promise<boolean> => {
+  for (const pattern of SCOPED_TEST_FILE_PATTERNS) {
+    // eslint-disable-next-line no-await-in-loop
+    if (await hasAnyFilesMatching(pattern)) {
+      return true;
+    }
+  }
+  return false;
+};
+
+const isFailure = (result: StepResult): boolean => result.status === "fail";
+
+const runCommandStep = async (step: CheckStep): Promise<StepResult> => {
+  const startedAt = performance.now();
+  const child = Bun.spawn(step.command, {
+    cwd: process.cwd(),
+    stderr: "pipe",
+    stdout: "pipe",
+  });
+
+  const [stdout, stderr, exitCode] = await Promise.all([
+    new Response(child.stdout).text(),
+    new Response(child.stderr).text(),
+    child.exited,
+  ]);
+
+  return {
+    durationMs: Math.round(performance.now() - startedAt),
+    output: `${stdout}${stderr}`.trim(),
+    status: exitCode === 0 ? "pass" : "fail",
+    step,
+  };
+};
+
+const lintConfigFailure = (step: CheckStep): StepResult => ({
+  durationMs: 0,
+  output: LINT_CONFIG_ERROR,
+  status: "fail",
+  step,
+});
+
+const skippedTestsResult = (step: CheckStep): StepResult => ({
+  durationMs: 0,
+  output: NO_TESTS_MESSAGE,
+  status: "pass",
+  step,
+});
+
+const runStep = async (step: CheckStep): Promise<StepResult> => {
+  if (step.id === "lint" && !(await hasAnyLinterConfig())) {
+    return lintConfigFailure(step);
+  }
+  if (step.id === "tests" && !(await hasAnyTestFiles())) {
+    return skippedTestsResult(step);
+  }
+
+  return runCommandStep(step);
+};
+
+const runSteps = async (): Promise<StepResult[]> => {
+  const results: StepResult[] = [];
+
+  for (const step of steps) {
+    // eslint-disable-next-line no-await-in-loop
+    const result = await runStep(step);
+    results.push(result);
+
+    if (isFailure(result)) {
+      break;
+    }
+  }
+
+  return results;
+};
+
+export const truncateOutput = (
+  output: string,
+  maxLines = MAX_OUTPUT_LINES
+): TruncatedOutput => {
+  const normalized = output.trim();
+  if (normalized.length === 0) {
+    return { omittedLines: 0, text: "" };
+  }
+
+  const lines = normalized.split("\n");
+  if (lines.length <= maxLines) {
+    return { omittedLines: 0, text: normalized };
+  }
+
+  return {
+    omittedLines: lines.length - maxLines,
+    text: lines.slice(0, maxLines).join("\n"),
+  };
+};
+
+const getCounts = (results: StepResult[]): StepCounts => {
+  const failed = results.filter(isFailure).length;
+  const passed = results.length - failed;
+  return {
+    failed,
+    passed,
+    status: failed === 0 ? "pass" : "fail",
+  };
+};
+
+const buildHeaderLines = (results: StepResult[]): string[] => {
+  const counts = getCounts(results);
+  return [
+    "# Check Report",
+    "",
+    `- status: ${counts.status}`,
+    `- steps_total: ${results.length}`,
+    `- steps_passed: ${counts.passed}`,
+    `- steps_failed: ${counts.failed}`,
+    "",
+  ];
+};
+
+const buildFailureOutputLines = (output: string): string[] => {
+  if (output.length === 0) {
+    return [];
+  }
+
+  const truncated = truncateOutput(output);
+  const lines = ["", "### Output", "", "```text", truncated.text];
+
+  if (truncated.omittedLines > 0) {
+    lines.push(`[truncated: omitted ${truncated.omittedLines} lines]`);
+  }
+
+  lines.push("```");
+  return lines;
+};
+
+const buildStepLines = (result: StepResult): string[] => {
+  const lines = [
+    `## ${result.step.name}`,
+    "",
+    `- status: ${result.status}`,
+    `- duration_ms: ${result.durationMs}`,
+  ];
+
+  if (isFailure(result)) {
+    lines.push(...buildFailureOutputLines(result.output));
+  }
+
+  lines.push("");
+  return lines;
+};
+
+const buildSummaryRows = (results: StepResult[]): string[] =>
+  results.map(
+    (result) =>
+      `| ${result.step.name} | ${result.status.toUpperCase()} | ${String(
+        result.durationMs
+      )} |`
+  );
+
+const buildSummaryLines = (results: StepResult[]): string[] => [
+  "## Summary",
+  "",
+  "| Step | Status | Duration (ms) |",
+  "| --- | --- | ---: |",
+  ...buildSummaryRows(results),
+];
+
+export const renderReport = (results: StepResult[]): string => {
+  const lines = [
+    ...buildHeaderLines(results),
+    ...results.flatMap(buildStepLines),
+    ...buildSummaryLines(results),
+  ];
+  return `${lines.join("\n")}\n`;
+};
+
+const runCheck = async (): Promise<number> => {
+  const results = await runSteps();
+  process.stdout.write(renderReport(results));
+  return results.some(isFailure) ? 1 : 0;
+};
+
+if (import.meta.main) {
+  const code = await runCheck();
+  process.exit(code);
+}

package/templates/default/scripts/smoke.ts

@@ -0,0 +1,193 @@
+interface CommandResult {
+  code: number;
+  stderr: string;
+  stdout: string;
+}
+
+const BASE_URL = process.env.IDCMD_SMOKE_BASE_URL ?? "http://127.0.0.1:4000";
+const CURL_MAX_TIME_SECONDS = "5";
+const READY_TIMEOUT_MS = 60_000;
+const READY_INTERVAL_MS = 500;
+const SHUTDOWN_TIMEOUT_MS = 5000;
+
+const delay = (ms: number): Promise<void> => Bun.sleep(ms);
+
+const runCommand = async (command: string[]): Promise<CommandResult> => {
+  const proc = Bun.spawn(command, {
+    cwd: process.cwd(),
+    stderr: "pipe",
+    stdout: "pipe",
+  });
+  const [stdout, stderr, code] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+    proc.exited,
+  ]);
+  return { code, stderr, stdout };
+};
+
+const runCurl = (path: string): Promise<CommandResult> =>
+  runCommand([
+    "curl",
+    "-fsS",
+    "--max-time",
+    CURL_MAX_TIME_SECONDS,
+    `${BASE_URL}${path}`,
+  ]);
+
+const assertCommandOk = (label: string, result: CommandResult): void => {
+  if (result.code === 0) {
+    return;
+  }
+  throw new Error(
+    [
+      `${label} failed with exit code ${String(result.code)}.`,
+      "stdout:",
+      result.stdout.trim() || "(empty)",
+      "stderr:",
+      result.stderr.trim() || "(empty)",
+    ].join("\n")
+  );
+};
+
+const expectIncludes = (args: {
+  haystack: string;
+  label: string;
+  needle: string;
+}): void => {
+  if (args.haystack.includes(args.needle)) {
+    return;
+  }
+  throw new Error(`Expected ${args.label} to include ${args.needle}.`);
+};
+
+const waitForReady = async (): Promise<void> => {
+  const startedAt = Date.now();
+  let lastFailure = "(no attempts yet)";
+
+  while (Date.now() - startedAt < READY_TIMEOUT_MS) {
+    const ready = await runCurl("/");
+    if (ready.code === 0) {
+      return;
+    }
+    lastFailure = ready.stderr.trim() || ready.stdout.trim() || "curl failed";
+    await delay(READY_INTERVAL_MS);
+  }
+
+  throw new Error(
+    `dev server did not become ready within ${String(
+      READY_TIMEOUT_MS
+    )}ms. Last curl failure: ${lastFailure}`
+  );
+};
+
+const shutdownDev = async (
+  proc: ReturnType<typeof Bun.spawn>
+): Promise<void> => {
+  try {
+    proc.kill("SIGTERM");
+  } catch {
+    return;
+  }
+
+  const didExit = await Promise.race([
+    proc.exited.then(() => true),
+    delay(SHUTDOWN_TIMEOUT_MS).then(() => false),
+  ]);
+  if (!didExit) {
+    try {
+      proc.kill("SIGKILL");
+    } catch {
+      // ignore
+    }
+    await proc.exited;
+  }
+};
+
+const assertHomeResponse = async (): Promise<void> => {
+  const home = await runCurl("/");
+  assertCommandOk("curl /", home);
+  expectIncludes({ haystack: home.stdout, label: "/", needle: "<html" });
+};
+
+const assertAboutResponse = async (): Promise<void> => {
+  const about = await runCurl("/about/");
+  assertCommandOk("curl /about/", about);
+  if (!about.stdout.includes("# About") && !about.stdout.includes(">About<")) {
+    throw new Error("Expected /about/ response to include About heading.");
+  }
+};
+
+const assertLlmsResponse = async (): Promise<void> => {
+  const llms = await runCurl("/llms.txt");
+  assertCommandOk("curl /llms.txt", llms);
+  if (llms.stdout.trim().length === 0 || !llms.stdout.includes("about.md")) {
+    throw new Error("Expected /llms.txt to be non-empty and include about.md.");
+  }
+};
+
+const assertApiResponse = async (): Promise<void> => {
+  const api = await runCurl("/api/hello");
+  assertCommandOk("curl /api/hello", api);
+  const payload = JSON.parse(api.stdout) as { message?: string; ok?: boolean };
+  if (payload.ok !== true || payload.message !== "Hello from idcmd route!") {
+    throw new Error("Expected /api/hello payload to match template route.");
+  }
+};
+
+const runSmokeChecks = async (): Promise<void> => {
+  await assertHomeResponse();
+  await assertAboutResponse();
+  await assertLlmsResponse();
+  await assertApiResponse();
+};
+
+const startDev = (): {
+  devProc: ReturnType<typeof Bun.spawn>;
+  devStderr: Promise<string>;
+  devStdout: Promise<string>;
+} => {
+  const devProc = Bun.spawn([process.execPath, "run", "dev"], {
+    cwd: process.cwd(),
+    stderr: "pipe",
+    stdout: "pipe",
+  });
+  return {
+    devProc,
+    devStderr: new Response(devProc.stderr).text(),
+    devStdout: new Response(devProc.stdout).text(),
+  };
+};
+
+const logDevFailure = async (args: {
+  error: unknown;
+  stderr: Promise<string>;
+  stdout: Promise<string>;
+}): Promise<void> => {
+  const [stdout, stderr] = await Promise.all([args.stdout, args.stderr]);
+  const message =
+    args.error instanceof Error ? args.error.message : String(args.error);
+  console.error(message);
+  console.error("dev stdout:");
+  console.error(stdout.trim() || "(empty)");
+  console.error("dev stderr:");
+  console.error(stderr.trim() || "(empty)");
+};
+
+const main = async (): Promise<number> => {
+  const { devProc, devStderr, devStdout } = startDev();
+
+  try {
+    await waitForReady();
+    await runSmokeChecks();
+    return 0;
+  } catch (error) {
+    await logDevFailure({ error, stderr: devStderr, stdout: devStdout });
+    return 1;
+  } finally {
+    await shutdownDev(devProc);
+  }
+};
+
+const code = await main();
+process.exit(code);