create-checkstack-plugin 0.1.0

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "create-checkstack-plugin",
+  "version": "0.1.0",
+  "description": "Scaffold a standalone Checkstack plugin workspace (common + backend + frontend) with concrete published versions, ready to `bun install && bun run dev`.",
+  "license": "Elastic-2.0",
+  "type": "module",
+  "checkstack": {
+    "type": "tooling"
+  },
+  "bin": {
+    "create-checkstack-plugin": "./src/cli.ts"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "typecheck": "tsgo -b"
+  },
+  "dependencies": {
+    "@checkstack/scripts": "0.3.4",
+    "inquirer": "^13.4.1",
+    "zod": "^4.2.1"
+  },
+  "devDependencies": {
+    "@checkstack/tsconfig": "0.0.7",
+    "@types/inquirer": "^8.2.10",
+    "typescript": "^5.0.0"
+  }
+}

package/src/cli-args.test.ts

@@ -0,0 +1,72 @@
+import { describe, it, expect } from "bun:test";
+import { parseCliArgs, validateBaseName, validateScope } from "./cli-args";
+
+describe("parseCliArgs", () => {
+  it("defaults: latest tag, git on, interactive", () => {
+    const args = parseCliArgs({ argv: [] });
+    expect(args.versionTag).toBe("latest");
+    expect(args.git).toBe(true);
+    expect(args.yes).toBe(false);
+    expect(args.targetDir).toBeUndefined();
+    expect(args.scope).toBeUndefined();
+  });
+
+  it("captures the positional target dir", () => {
+    expect(parseCliArgs({ argv: ["my-widget"] }).targetDir).toBe("my-widget");
+  });
+
+  it("parses --scope / --no-scope", () => {
+    expect(parseCliArgs({ argv: ["--scope", "acme"] }).scope).toBe("acme");
+    expect(parseCliArgs({ argv: ["--no-scope"] }).scope).toBe("");
+  });
+
+  it("parses --version-tag, --no-git, --yes", () => {
+    const args = parseCliArgs({
+      argv: ["w", "--version-tag", "next", "--no-git", "--yes"],
+    });
+    expect(args.versionTag).toBe("next");
+    expect(args.git).toBe(false);
+    expect(args.yes).toBe(true);
+    expect(args.targetDir).toBe("w");
+  });
+
+  it("registry flag overrides the env fallback", () => {
+    const args = parseCliArgs({
+      argv: ["--registry", "http://localhost:4873"],
+      env: { CHECKSTACK_SCAFFOLD_REGISTRY: "http://env:1111" },
+    });
+    expect(args.registry).toBe("http://localhost:4873");
+  });
+
+  it("falls back to CHECKSTACK_SCAFFOLD_REGISTRY when no flag given", () => {
+    const args = parseCliArgs({
+      argv: [],
+      env: { CHECKSTACK_SCAFFOLD_REGISTRY: "http://env:1111" },
+    });
+    expect(args.registry).toBe("http://env:1111");
+  });
+});
+
+describe("validateBaseName", () => {
+  it("accepts a kebab base name", () => {
+    expect(validateBaseName("my-widget").valid).toBe(true);
+  });
+  it("rejects uppercase, reserved, and bad shapes", () => {
+    expect(validateBaseName("Widget").valid).toBe(false);
+    expect(validateBaseName("common").valid).toBe(false);
+    expect(validateBaseName("-x").valid).toBe(false);
+    expect(validateBaseName("a--b").valid).toBe(false);
+  });
+});
+
+describe("validateScope", () => {
+  it("accepts empty (unscoped) and valid scopes", () => {
+    expect(validateScope("").valid).toBe(true);
+    expect(validateScope("acme").valid).toBe(true);
+    expect(validateScope("my-org").valid).toBe(true);
+  });
+  it("rejects a leading @ or uppercase", () => {
+    expect(validateScope("@acme").valid).toBe(false);
+    expect(validateScope("Acme").valid).toBe(false);
+  });
+});

package/src/cli-args.ts

@@ -0,0 +1,130 @@
+/**
+ * Argument parsing for the `create-checkstack-plugin` CLI.
+ *
+ * Kept pure (no IO) so it can be unit-tested. Supports:
+ *   - a positional target directory (the repo to create);
+ *   - `--scope <name>` / `--no-scope` to control the npm scope;
+ *   - `--version-tag <tag>` (default `latest`) for the dist-tag to resolve;
+ *   - `--registry <url>` (env fallback `CHECKSTACK_SCAFFOLD_REGISTRY`);
+ *   - `--no-git` to skip `git init`;
+ *   - `--yes` to accept defaults non-interactively (used by the e2e test).
+ */
+
+export interface CliArgs {
+  /** Positional target directory, if given. */
+  targetDir?: string;
+  /** Explicit scope (without `@`), or "" if `--no-scope`, or undefined. */
+  scope?: string;
+  versionTag: string;
+  registry?: string;
+  git: boolean;
+  /** Skip prompts and use defaults / provided flags. */
+  yes: boolean;
+  help: boolean;
+}
+
+export function parseCliArgs({
+  argv,
+  env = {},
+}: {
+  argv: string[];
+  env?: Record<string, string | undefined>;
+}): CliArgs {
+  const args: CliArgs = {
+    versionTag: "latest",
+    registry: env.CHECKSTACK_SCAFFOLD_REGISTRY,
+    git: true,
+    yes: false,
+    help: false,
+  };
+
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    switch (a) {
+      case "--scope": {
+        args.scope = argv[++i];
+        break;
+      }
+      case "--no-scope": {
+        args.scope = "";
+        break;
+      }
+      case "--version-tag": {
+        args.versionTag = argv[++i];
+        break;
+      }
+      case "--registry": {
+        args.registry = argv[++i];
+        break;
+      }
+      case "--no-git": {
+        args.git = false;
+        break;
+      }
+      case "--yes":
+      case "-y": {
+        args.yes = true;
+        break;
+      }
+      case "--help":
+      case "-h": {
+        args.help = true;
+        break;
+      }
+      default: {
+        if (!a.startsWith("-") && args.targetDir === undefined) {
+          args.targetDir = a;
+        }
+        break;
+      }
+    }
+  }
+
+  return args;
+}
+
+/**
+ * Validate a base plugin name (lowercase, hyphen-separated, no reserved
+ * words). Mirrors the monorepo `validatePluginName` rules.
+ */
+export function validateBaseName(name: string): {
+  valid: boolean;
+  error?: string;
+} {
+  if (!name || name.trim().length === 0) {
+    return { valid: false, error: "Plugin name cannot be empty" };
+  }
+  if (name !== name.toLowerCase()) {
+    return { valid: false, error: "Plugin name must be lowercase" };
+  }
+  if (!/^[\da-z-]+$/.test(name)) {
+    return {
+      valid: false,
+      error: "Plugin name can only contain lowercase letters, numbers, and hyphens",
+    };
+  }
+  if (name.startsWith("-") || name.endsWith("-")) {
+    return { valid: false, error: "Plugin name cannot start or end with a hyphen" };
+  }
+  if (name.includes("--")) {
+    return { valid: false, error: "Plugin name cannot contain consecutive hyphens" };
+  }
+  if (new Set(["checkstack", "core", "api", "common"]).has(name)) {
+    return { valid: false, error: `'${name}' is a reserved name` };
+  }
+  return { valid: true };
+}
+
+/** Validate an npm scope (without the leading `@`). Empty is allowed (unscoped). */
+export function validateScope(scope: string): { valid: boolean; error?: string } {
+  if (scope === "") return { valid: true };
+  if (!/^[a-z\d][a-z\d._-]*$/.test(scope)) {
+    return {
+      valid: false,
+      error:
+        "Scope must start with a lowercase letter or digit and contain only " +
+        "lowercase letters, digits, '.', '_', or '-' (no leading '@').",
+    };
+  }
+  return { valid: true };
+}

package/src/cli.ts

@@ -0,0 +1,177 @@
+#!/usr/bin/env bun
+import path from "node:path";
+import fs from "node:fs";
+import inquirer from "inquirer";
+import {
+  parseCliArgs,
+  validateBaseName,
+  validateScope,
+  type CliArgs,
+} from "./cli-args";
+import {
+  scaffoldStandaloneWorkspace,
+  localSiblingNames,
+} from "./scaffold-standalone";
+import { createNpmViewResolver } from "./npm-view-resolver";
+import { initGitRepo } from "./git";
+
+/**
+ * `create-checkstack-plugin` — a thin standalone bootstrapper.
+ *
+ * Resolves a target dir + base name + scope (via flags or interactive
+ * prompts), resolves concrete published `@checkstack/*` versions from the
+ * registry's `latest` dist-tag, renders the standalone trio workspace via
+ * the `@checkstack/scripts` engine, then `git init`s the result. All the
+ * heavy lifting lives in `@checkstack/scripts`; this package only adds the
+ * prompts, version resolution, and git wiring so `bun create
+ * checkstack-plugin` / `bunx create-checkstack-plugin` work ergonomically.
+ */
+
+interface Answers {
+  baseName: string;
+  scope: string;
+  targetDir: string;
+}
+
+async function gatherAnswers(args: CliArgs): Promise<Answers> {
+  if (args.yes) {
+    const baseName = args.targetDir
+      ? path.basename(path.resolve(args.targetDir))
+      : "widget";
+    const baseCheck = validateBaseName(baseName);
+    if (!baseCheck.valid) {
+      throw new Error(`Invalid plugin name '${baseName}': ${baseCheck.error}`);
+    }
+    return {
+      baseName,
+      scope: args.scope ?? "",
+      targetDir: path.resolve(args.targetDir ?? baseName),
+    };
+  }
+
+  const { baseName } = await inquirer.prompt<{ baseName: string }>([
+    {
+      type: "input",
+      name: "baseName",
+      message: "Plugin base name (e.g. 'widget' for 'widget-backend'):",
+      default: args.targetDir
+        ? path.basename(path.resolve(args.targetDir))
+        : undefined,
+      validate: (input: string) => {
+        const check = validateBaseName(input.trim());
+        return check.valid || check.error || false;
+      },
+      filter: (input: string) => input.trim(),
+    },
+  ]);
+
+  let scope = args.scope;
+  if (scope === undefined) {
+    const { scopeInput } = await inquirer.prompt<{ scopeInput: string }>([
+      {
+        type: "input",
+        name: "scopeInput",
+        message:
+          "npm scope without '@' (leave blank to publish unscoped):",
+        default: "",
+        validate: (input: string) => {
+          const check = validateScope(input.trim());
+          return check.valid || check.error || false;
+        },
+        filter: (input: string) => input.trim(),
+      },
+    ]);
+    scope = scopeInput;
+  }
+
+  const targetDir = path.resolve(args.targetDir ?? baseName);
+  return { baseName, scope, targetDir };
+}
+
+export async function run({
+  argv,
+  env,
+}: {
+  argv: string[];
+  env: Record<string, string | undefined>;
+}): Promise<number> {
+  const args = parseCliArgs({ argv, env });
+  if (args.help) {
+    printHelp();
+    return 0;
+  }
+
+  const { baseName, scope, targetDir } = await gatherAnswers(args);
+
+  if (fs.existsSync(targetDir) && fs.readdirSync(targetDir).length > 0) {
+    console.error(`Target directory '${targetDir}' already exists and is not empty.`);
+    return 1;
+  }
+
+  const description = `${baseName.charAt(0).toUpperCase()}${baseName.slice(1)} plugin`;
+
+  const resolveVersion = createNpmViewResolver({
+    registry: args.registry,
+    versionTag: args.versionTag,
+    localSiblings: localSiblingNames({ baseName, packageScope: scope }),
+  });
+
+  console.log(`\nScaffolding ${baseName} plugin in ${targetDir} ...`);
+
+  await scaffoldStandaloneWorkspace({
+    rootDir: targetDir,
+    baseName,
+    description,
+    packageScope: scope,
+    resolveVersion,
+  });
+
+  console.log("Wrote the workspace root and the common/backend/frontend trio.");
+
+  if (args.git) {
+    initGitRepo({ dir: targetDir });
+  }
+
+  printNextSteps({ targetDir, baseName });
+  return 0;
+}
+
+function printNextSteps({
+  targetDir,
+  baseName,
+}: {
+  targetDir: string;
+  baseName: string;
+}): void {
+  const rel = path.relative(process.cwd(), targetDir) || ".";
+  console.log("\nDone. Next steps:");
+  console.log(`  1. cd ${rel}`);
+  console.log("  2. Start Postgres (see README.md)");
+  console.log("  3. bun install");
+  console.log("  4. bun run dev");
+  console.log(`  5. POST http://localhost:3000/api/${baseName}/getItems\n`);
+}
+
+function printHelp(): void {
+  console.log(`Usage: create-checkstack-plugin [target-dir] [options]
+
+Scaffold a standalone Checkstack plugin workspace (common + backend +
+frontend) with concrete published @checkstack/* versions, ready to
+\`bun install && bun run dev\`.
+
+Options:
+  --scope <name>        npm scope without '@' (e.g. acme). Prompted if omitted.
+  --no-scope            Publish the trio unscoped (widget-backend, ...).
+  --version-tag <tag>   dist-tag to resolve versions from (default: latest).
+  --registry <url>      Registry for version resolution
+                        (env: CHECKSTACK_SCAFFOLD_REGISTRY).
+  --no-git              Do not run \`git init\`.
+  --yes, -y             Accept defaults without prompting.
+  --help, -h            Show this message.
+`);
+}
+
+if (import.meta.main) {
+  const code = await run({ argv: process.argv.slice(2), env: process.env });
+  process.exit(code);
+}