@inbeat/standards 0.7.0

package/src/cli.ts

@@ -0,0 +1,85 @@
+#!/usr/bin/env bun
+import { resolve } from "node:path";
+import { create } from "./create";
+import { parseCreateArgs } from "./create-args";
+import { foundationProblems } from "./foundation";
+import { runMcp } from "./mcp";
+import { claudeFilesIgnoringAgents, staleFiles, write } from "./sync";
+
+const USAGE = [
+  "usage: ib <create <dir> [--local] | sync [app-dir] | check [app-dir] | mcp>",
+  "  create <dir>   start a new app",
+  "  mcp            write MCP server config for your AI tools; run `ib mcp` for the picker",
+  "  --local        write absolute file: paths to ib-toolkit tarballs; for toolkit development and CI only,",
+  "                 never commit that package.json",
+].join("\n");
+
+const [command = "help", ...args] = process.argv.slice(2);
+const appDir = resolve(args.find((arg) => !arg.startsWith("--")) ?? ".");
+
+const commands: Record<string, () => number | Promise<number>> = {
+  create: async () => {
+    let parsed: ReturnType<typeof parseCreateArgs>;
+    try {
+      parsed = parseCreateArgs(args);
+    } catch (error) {
+      console.error(`${error instanceof Error ? error.message : error}\n${USAGE}`);
+      return 1;
+    }
+    if (!parsed.dir) {
+      console.error(USAGE);
+      return 1;
+    }
+    await create(parsed.dir, { local: parsed.local });
+    return 0;
+  },
+  sync: () => {
+    const written = write(appDir);
+    console.info(written.length ? `updated:\n  ${written.join("\n  ")}` : "already up to date");
+    return 0;
+  },
+  check: () => {
+    const stale = staleFiles(appDir);
+    const ignoring = claudeFilesIgnoringAgents(appDir);
+    const problems = foundationProblems(appDir);
+    if (stale.length > 0) {
+      console.error(
+        `out of date with @inbeat/standards, run \`ib sync\`:\n  ${stale.join("\n  ")}`,
+      );
+    }
+    if (ignoring.length > 0) {
+      console.error(
+        "Claude Code ignores AGENTS.md when a CLAUDE.md exists; add a line `@AGENTS.md` to:\n" +
+          `  ${ignoring.join("\n  ")}`,
+      );
+    }
+    if (problems.length > 0) {
+      console.error(`not on the shared foundation:\n  ${problems.join("\n  ")}`);
+    }
+    return stale.length + ignoring.length + problems.length === 0 ? 0 : 1;
+  },
+  mcp: () =>
+    runMcp(args, {
+      cwd: process.cwd(),
+      stdin: process.stdin,
+      output: process.stdout,
+      isTTY: Boolean(process.stdin.isTTY),
+      out: console.info,
+      err: console.error,
+    }),
+  help: () => {
+    console.info(USAGE);
+    return 0;
+  },
+};
+
+const wantsHelp = args.some((arg) => arg === "--help" || arg === "-h");
+const handler = wantsHelp && command !== "mcp" ? commands.help : commands[command];
+if (!handler) console.error(USAGE);
+
+try {
+  process.exit(handler ? await handler() : 1);
+} catch (error) {
+  console.error(error instanceof Error ? error.message : error);
+  process.exit(1);
+}

package/src/create-args.ts

@@ -0,0 +1,10 @@
+export type CreateArgs = { dir: string | undefined; local: boolean };
+
+export function parseCreateArgs(args: string[]): CreateArgs {
+  const flags = args.filter((arg) => arg.startsWith("--"));
+  const unknown = flags.filter((flag) => flag !== "--local");
+  if (unknown.length > 0) throw new Error(`unknown option ${unknown.join(", ")}`);
+  const positional = args.filter((arg) => !arg.startsWith("--"));
+  if (positional.length > 1) throw new Error("create takes one directory");
+  return { dir: positional[0], local: flags.includes("--local") };
+}

package/src/create.ts

@@ -0,0 +1,240 @@
+import { spawnSync } from "node:child_process";
+import {
+  cpSync,
+  existsSync,
+  readdirSync,
+  readFileSync,
+  realpathSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { basename, dirname, join, relative, resolve } from "node:path";
+import { PACKAGE_ROOT, VERSION, write } from "./sync";
+import { isShipped, restoreDotfileName, templateEntries } from "./template";
+
+const DEPENDENCY_FIELDS = ["dependencies", "devDependencies", "peerDependencies"] as const;
+
+type Dependencies = Record<string, string>;
+export type Manifest = {
+  name: string;
+  overrides?: Dependencies;
+  dependencies?: Dependencies;
+  devDependencies?: Dependencies;
+  peerDependencies?: Dependencies;
+  [field: string]: unknown;
+};
+
+export const TEMPLATE_DIR = join(PACKAGE_ROOT, "template");
+
+export function projectName(dir: string): string {
+  return basename(resolve(dir))
+    .replace(/([a-z\d])([A-Z])/g, "$1-$2")
+    .toLowerCase()
+    .replace(/[^a-z\d]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+export function validateProjectName(name: string): void {
+  const isValid =
+    name.length > 0 &&
+    name.length <= 214 &&
+    /^[a-z0-9][a-z0-9-]*$/.test(name) &&
+    !["node_modules", "favicon.ico"].includes(name);
+  if (!isValid) {
+    throw new Error(
+      `"${name}" cannot be an npm package name; use a folder name of lowercase letters, digits and dashes, e.g. my-app.`,
+    );
+  }
+}
+
+export function findConflicts(targetDir: string, templateEntries: string[]): string[] {
+  return templateEntries
+    .map(restoreDotfileName)
+    .filter((entry) => existsSync(join(targetDir, entry)));
+}
+
+export function rewriteManifest(
+  manifest: Manifest,
+  options: { name: string; version: string; tarballs?: Dependencies },
+): Manifest {
+  const { name, version, tarballs } = options;
+  const resolveRange = (dependency: string, range: string): string => {
+    if (!range.startsWith("workspace:")) return range;
+    return tarballs?.[dependency] ?? `^${version}`;
+  };
+  const resolved = Object.fromEntries(
+    DEPENDENCY_FIELDS.filter((field) => manifest[field]).map((field) => [
+      field,
+      Object.fromEntries(
+        Object.entries(manifest[field] as Dependencies).map(([dependency, range]) => [
+          dependency,
+          resolveRange(dependency, range),
+        ]),
+      ),
+    ]),
+  );
+  return {
+    ...manifest,
+    ...resolved,
+    name,
+    ...(tarballs && { overrides: tarballs }),
+  };
+}
+
+export function findToolkitRoot(from: string = PACKAGE_ROOT): string | null {
+  const manifestPath = join(from, "package.json");
+  const isToolkit =
+    existsSync(join(from, "scripts", "pack-local.ts")) &&
+    existsSync(manifestPath) &&
+    JSON.parse(readFileSync(manifestPath, "utf8")).name === "ib-toolkit";
+  if (isToolkit) return from;
+  const parent = dirname(from);
+  return parent === from ? null : findToolkitRoot(parent);
+}
+
+export type Runner = (command: string, args: string[], cwd: string) => void;
+
+type ToolkitScripts = {
+  toolkitPackages(): { name: string; shortName: string }[];
+  packTarballPath(pkg: { shortName: string }): string;
+};
+
+// Loaded from the checkout at runtime: scripts/ only exists there, never in the published package.
+async function localTarballs(toolkitRoot: string): Promise<Dependencies> {
+  const scripts: ToolkitScripts = await import(join(toolkitRoot, "scripts", "packages.ts"));
+  return Object.fromEntries(
+    scripts.toolkitPackages().map((pkg) => [pkg.name, `file:${scripts.packTarballPath(pkg)}`]),
+  );
+}
+
+export const runCommand: Runner = (command, args, cwd) => {
+  const { status, error } = spawnSync(command, args, { cwd, stdio: "inherit" });
+  if (status !== 0) {
+    throw new Error(
+      `\`${[command, ...args].join(" ")}\` failed${error ? `: ${error.message}` : ""}`,
+    );
+  }
+};
+
+function isInsideGitRepo(dir: string): boolean {
+  return (
+    spawnSync("git", ["rev-parse", "--is-inside-work-tree"], { cwd: dir, stdio: "ignore" })
+      .status === 0
+  );
+}
+
+function resolveToolkitRoot(local: boolean, targetDir: string): string | null {
+  if (findToolkitRoot(targetDir)) {
+    throw new Error(`${targetDir} is inside the ib-toolkit checkout; create projects elsewhere.`);
+  }
+  if (local) {
+    const toolkitRoot = findToolkitRoot();
+    if (!toolkitRoot) {
+      throw new Error(
+        "--local only works from an ib-toolkit checkout (run the checkout's src/cli.ts).",
+      );
+    }
+    return toolkitRoot;
+  }
+  return null;
+}
+
+export type CreateOptions = {
+  local: boolean;
+  templateDir?: string;
+  run?: Runner;
+};
+
+function populate(targetDir: string, templateDir: string, manifest: Manifest, run: Runner): void {
+  for (const entry of templateEntries(templateDir)) {
+    cpSync(join(templateDir, entry), join(targetDir, restoreDotfileName(entry)), {
+      recursive: true,
+      filter: (path) => isShipped(relative(templateDir, path)),
+    });
+  }
+  const manifestPath = join(targetDir, "package.json");
+  writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+
+  const envLocalPath = join(targetDir, ".env.local");
+  if (!existsSync(envLocalPath)) cpSync(join(targetDir, ".env.example"), envLocalPath);
+
+  if (!isInsideGitRepo(targetDir)) run("git", ["init"], targetDir);
+  write(targetDir);
+  run("bun", ["install"], targetDir);
+}
+
+function removeWrittenPaths(targetDir: string, preexisting: Set<string> | null): string {
+  if (!preexisting) {
+    rmSync(targetDir, { recursive: true, force: true });
+    return `removed ${targetDir}`;
+  }
+  const written = readdirSync(targetDir).filter((entry) => !preexisting.has(entry));
+  for (const entry of written) rmSync(join(targetDir, entry), { recursive: true, force: true });
+  return `removed from ${targetDir}: ${written.join(", ")}`;
+}
+
+function assertNoConflicts(targetDir: string, plannedEntries: string[]): void {
+  const conflicts = findConflicts(targetDir, plannedEntries);
+  if (conflicts.length > 0) {
+    throw new Error(`${targetDir} already contains template paths:\n  ${conflicts.join("\n  ")}`);
+  }
+}
+
+export function locationStep(cwd: string, targetDir: string): string | null {
+  const location = relative(cwd, targetDir);
+  if (!location) return null;
+  return `cd ${location.startsWith("..") ? targetDir : location}`;
+}
+
+export function formatNextSteps(steps: string[]): string {
+  return ["Next steps:", ...[...steps, "bun dev"].map((step) => `  ${step}`)].join("\n");
+}
+
+/** Everything that can be rejected before the template is built or anything is written. */
+function preflight(
+  dir: string,
+  options: Pick<CreateOptions, "local" | "templateDir">,
+): { targetDir: string; name: string; toolkitRoot: string | null } {
+  const { local, templateDir = TEMPLATE_DIR } = options;
+  const targetDir = resolve(dir);
+  const name = projectName(targetDir);
+  validateProjectName(name);
+  const toolkitRoot = resolveToolkitRoot(local, targetDir);
+  if (existsSync(templateDir)) assertNoConflicts(targetDir, templateEntries(templateDir));
+  return { targetDir, name, toolkitRoot };
+}
+
+export async function create(dir: string, options: CreateOptions): Promise<void> {
+  const { templateDir = TEMPLATE_DIR, run = runCommand } = options;
+  const { targetDir, name, toolkitRoot } = preflight(dir, options);
+  if (toolkitRoot) run("bun", ["run", "pack:local"], toolkitRoot);
+
+  if (!existsSync(templateDir)) {
+    throw new Error(
+      "template missing from @inbeat/standards; run `bun run build:packages` in ib-toolkit.",
+    );
+  }
+  assertNoConflicts(targetDir, templateEntries(templateDir));
+
+  const manifest = rewriteManifest(
+    JSON.parse(readFileSync(join(templateDir, "package.json"), "utf8")),
+    {
+      name,
+      version: VERSION,
+      tarballs: toolkitRoot ? await localTarballs(toolkitRoot) : undefined,
+    },
+  );
+  const preexisting = existsSync(targetDir) ? new Set(readdirSync(targetDir)) : null;
+  try {
+    populate(targetDir, templateDir, manifest, run);
+  } catch (error) {
+    const cleanup = removeWrittenPaths(targetDir, preexisting);
+    throw new Error(`create failed: ${error instanceof Error ? error.message : error}\n${cleanup}`);
+  }
+
+  const location = locationStep(process.cwd(), targetDir);
+  const steps = location ? [location] : [];
+  console.info(
+    `\nSuccess! Created ${name} at ${realpathSync(targetDir)}\n\n${formatNextSteps(steps)}`,
+  );
+}

package/src/foundation.ts

@@ -0,0 +1,42 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+type Requirement = {
+  files: string[];
+  message: string;
+  satisfiedBy: (contents: string) => boolean;
+};
+
+// biome.jsonc and tsconfig.json are JSONC (comments, trailing commas), so match the quoted preset
+// name instead of parsing.
+const mentionsPreset = (preset: string) => (contents: string) => contents.includes(`"${preset}"`);
+
+const REQUIREMENTS: Requirement[] = [
+  {
+    files: ["biome.json", "biome.jsonc"],
+    message: "biome.json (or biome.jsonc) must extend @inbeat/config/biome",
+    satisfiedBy: mentionsPreset("@inbeat/config/biome"),
+  },
+  {
+    files: ["tsconfig.json"],
+    message: "tsconfig.json must extend @inbeat/config/tsconfig/nextjs.json",
+    satisfiedBy: mentionsPreset("@inbeat/config/tsconfig/nextjs.json"),
+  },
+  {
+    files: [".dependency-cruiser.cjs"],
+    message: ".dependency-cruiser.cjs must use @inbeat/config/dependency-cruiser",
+    satisfiedBy: mentionsPreset("@inbeat/config/dependency-cruiser"),
+  },
+  {
+    files: ["vitest.config.ts"],
+    message: "vitest.config.ts must import from @inbeat/config/vitest",
+    satisfiedBy: mentionsPreset("@inbeat/config/vitest"),
+  },
+];
+
+export function foundationProblems(appDir: string): string[] {
+  return REQUIREMENTS.filter(({ files, satisfiedBy }) => {
+    const path = files.map((file) => join(appDir, file)).find(existsSync);
+    return !path || !satisfiedBy(readFileSync(path, "utf8"));
+  }).map(({ message }) => message);
+}

package/src/mcp-servers.ts

@@ -0,0 +1,8 @@
+export const CURATED_SERVERS: Record<string, string> = {
+  vercel: "https://mcp.vercel.com",
+  github: "https://api.githubcopilot.com/mcp/readonly",
+  sentry: "https://mcp.sentry.dev/mcp",
+  neon: "https://mcp.neon.tech/mcp",
+  clerk: "https://mcp.clerk.com/mcp",
+  cloudflare: "https://mcp.cloudflare.com/mcp",
+};