@checkstack/scripts 0.1.2 → 0.3.0

package/package.json

@@ -1,22 +1,34 @@
 {
   "name": "@checkstack/scripts",
-  "version": "0.1.2",
+  "version": "0.3.0",
+  "description": "Checkstack tooling: plugin scaffolding, codegen, and the plugin-pack CLI used by external plugin authors.",
+  "license": "Elastic-2.0",
+  "type": "module",
   "checkstack": {
     "type": "tooling"
   },
   "bin": {
     "checkstack-scripts": "./src/cli.ts"
   },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
     "sync": "bun run src/sync.ts",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsgo -b"
   },
   "dependencies": {
+    "@checkstack/common": "0.8.0",
     "inquirer": "^13.4.1",
-    "handlebars": "^4.7.8"
+    "handlebars": "^4.7.8",
+    "tar": "^7.4.3"
   },
   "devDependencies": {
-    "@checkstack/tsconfig": "0.0.3",
+    "@checkstack/tsconfig": "0.0.7",
     "@types/inquirer": "^8.2.10",
     "@types/handlebars": "^4.1.0",
     "typescript": "^5.0.0"

package/src/cli.ts

@@ -7,11 +7,12 @@ const command = process.argv[2];
 if (!command) {
   console.log("Usage: checkstack-scripts <command>");
   console.log("\nCommands:");
-  console.log("  create      - Create a new plugin interactively");
-  console.log("  sync        - Synchronize package configurations");
-  console.log("  generate    - Generate migrations and strip public schema");
-  console.log("  typecheck   - Run TypeScript type checking");
-  console.log("  lint        - Run linting checks");
+  console.log("  create        - Create a new plugin interactively");
+  console.log("  sync          - Synchronize package configurations");
+  console.log("  generate      - Generate migrations and strip public schema");
+  console.log("  plugin-pack   - Pack a plugin (or bundle) into a .tgz for distribution");
+  console.log("  typecheck     - Run TypeScript type checking");
+  console.log("  lint          - Run linting checks");
   process.exit(1);
 }
 
@@ -51,6 +52,20 @@ if (command === "generate") {
   process.exit(result.status ?? 0);
 }
 
+if (command === "plugin-pack") {
+  // Dispatch to the plugin-pack module. We invoke it via `bun run` so it
+  // works whether the user runs `bunx @checkstack/scripts plugin-pack`
+  // (resolves to node_modules), `bun run cli plugin-pack`
+  // (relative path from repo), or via the bin script.
+  const scriptPath = path.resolve(
+    new URL("commands/plugin-pack.ts", import.meta.url).pathname,
+  );
+  const result = spawnSync("bun", ["run", scriptPath, ...process.argv.slice(3)], {
+    stdio: "inherit",
+  });
+  process.exit(result.status ?? 0);
+}
+
 // Fallback for other scripts if we want to centralize their execution logic
 console.error(`Unknown command: ${command}`);
 process.exit(1);

package/src/commands/create.ts

@@ -1,6 +1,7 @@
 #!/usr/bin/env bun
 import inquirer from "inquirer";
 import path from "node:path";
+import { spawnSync } from "node:child_process";
 import {
   validatePluginName,
   pluginExists,
@@ -217,6 +218,22 @@ export async function createCommand() {
     }
 
     // Success message with next steps
+    // Refresh project-references in every package's tsconfig + the root
+    // solution tsconfig so the new package is wired into the typecheck
+    // graph. Affects only tsconfig.json files; safe to rerun any time.
+    console.log("\n🔗 Refreshing TypeScript project references...");
+    const refResult = spawnSync(
+      "bun",
+      ["run", "typecheck:references:generate"],
+      { stdio: "inherit" },
+    );
+    if (refResult.status !== 0) {
+      console.warn(
+        "⚠️  Failed to refresh references automatically. " +
+          "Run `bun run typecheck:references:generate` manually before typechecking.",
+      );
+    }
+
     console.log(
       `\n✅ ${
         locationLabel.charAt(0).toUpperCase() + locationLabel.slice(1)

package/src/commands/plugin-pack.ts

@@ -0,0 +1,397 @@
+#!/usr/bin/env bun
+import path from "node:path";
+import fs from "node:fs";
+import os from "node:os";
+import { spawnSync } from "node:child_process";
+import { create as tarCreate } from "tar";
+import {
+  installPackageMetadataSchema,
+  pluginBundleManifestSchema,
+  type InstallPackageMetadata,
+  type PluginBundleManifest,
+} from "@checkstack/common";
+
+/**
+ * `plugin-pack` CLI.
+ *
+ * Two modes:
+ *   - default (per-package): packs the cwd into a single `.tgz` matching what
+ *     `bun pm pack` would produce, with extra metadata validation. This is
+ *     what gets uploaded to npm.
+ *   - `--bundle`: packs the cwd's primary package + every sibling listed in
+ *     `package.json#checkstack.bundle`, then wraps them into an outer tarball
+ *     containing `bundle.json` + `packages/<name>-<version>.tgz`. This is the
+ *     artifact attached to a GitHub release / uploaded directly via the
+ *     plugin manager UI.
+ *
+ * Workspace-resolution: `workspace:*` deps in any sibling's `package.json` are
+ * rewritten to the matching package's actual version before packing. Resolution
+ * walks the nearest ancestor `package.json` containing a `workspaces` field;
+ * if none is found we treat the cwd as standalone (no rewriting needed).
+ */
+
+interface Args {
+  bundle: boolean;
+  outDir: string;
+  cwd: string;
+  validateOnly: boolean;
+}
+
+export async function runPluginPack(rawArgs: string[]): Promise<number> {
+  const args = parseArgs(rawArgs);
+
+  const pkg = readJson<InstallPackageMetadata>(
+    path.join(args.cwd, "package.json"),
+  );
+
+  // Validate metadata ABOVE pack so the user sees errors immediately.
+  const validation = installPackageMetadataSchema.safeParse(pkg);
+  if (!validation.success) {
+    console.error("❌ package.json failed validation:");
+    for (const issue of validation.error.issues) {
+      console.error(`   - ${issue.path.join(".")}: ${issue.message}`);
+    }
+    return 1;
+  }
+
+  if (args.validateOnly) {
+    console.log("✅ Metadata valid.");
+    return 0;
+  }
+
+  // Pre-pack hooks
+  if (!args.bundle) {
+    runScriptIfPresent({ cwd: args.cwd, script: "typecheck" });
+    runScriptIfPresent({ cwd: args.cwd, script: "lint" });
+  }
+
+  fs.mkdirSync(args.outDir, { recursive: true });
+
+  if (args.bundle) {
+    const bundleNames = pkg.checkstack.bundle ?? [];
+    if (bundleNames.length === 0) {
+      console.error(
+        "❌ --bundle requires `checkstack.bundle` to be set in package.json.",
+      );
+      return 1;
+    }
+
+    const workspaceMap = buildWorkspaceMap(args.cwd);
+
+    const primaryTarball = await packPackage({
+      pkgDir: args.cwd,
+      outDir: args.outDir,
+      workspaceMap,
+    });
+
+    const siblings: { name: string; version: string; tarball: string }[] = [
+      {
+        name: pkg.name,
+        version: pkg.version,
+        tarball: `packages/${path.basename(primaryTarball)}`,
+      },
+    ];
+
+    for (const sibName of bundleNames) {
+      if (sibName === pkg.name) continue;
+      const sibDir = workspaceMap.get(sibName);
+      if (!sibDir) {
+        console.error(
+          `❌ Bundle sibling '${sibName}' not found in workspace. ` +
+            `Make sure it's a peer of the primary package.`,
+        );
+        return 1;
+      }
+      const sibTarball = await packPackage({
+        pkgDir: sibDir,
+        outDir: args.outDir,
+        workspaceMap,
+      });
+      const sibPkg = readJson<InstallPackageMetadata>(
+        path.join(sibDir, "package.json"),
+      );
+      siblings.push({
+        name: sibPkg.name,
+        version: sibPkg.version,
+        tarball: `packages/${path.basename(sibTarball)}`,
+      });
+    }
+
+    const manifest: PluginBundleManifest = pluginBundleManifestSchema.parse({
+      bundleVersion: 1,
+      primary: pkg.name,
+      packages: siblings,
+    });
+
+    const outerTarball = path.join(
+      args.outDir,
+      `${safeFileName(pkg.name)}-${pkg.version}-bundle.tgz`,
+    );
+
+    // Lay out files in a tmpdir then `tar.create`.
+    const stage = fs.mkdtempSync(path.join(os.tmpdir(), "checkstack-bundle-"));
+    try {
+      fs.mkdirSync(path.join(stage, "packages"), { recursive: true });
+      for (const sib of siblings) {
+        fs.copyFileSync(
+          path.join(args.outDir, path.basename(sib.tarball)),
+          path.join(stage, sib.tarball),
+        );
+      }
+      fs.writeFileSync(
+        path.join(stage, "bundle.json"),
+        JSON.stringify(manifest, undefined, 2),
+      );
+      await tarCreate(
+        {
+          gzip: true,
+          file: outerTarball,
+          cwd: stage,
+        },
+        ["bundle.json", "packages"],
+      );
+    } finally {
+      fs.rmSync(stage, { recursive: true, force: true });
+    }
+
+    console.log(`✅ Bundle tarball: ${outerTarball}`);
+    return 0;
+  }
+
+  // Default mode — single per-package tarball
+  const workspaceMap = buildWorkspaceMap(args.cwd);
+  const tarball = await packPackage({
+    pkgDir: args.cwd,
+    outDir: args.outDir,
+    workspaceMap,
+  });
+  console.log(`✅ Tarball: ${tarball}`);
+  return 0;
+}
+
+function parseArgs(raw: string[]): Args {
+  const args: Args = {
+    bundle: false,
+    outDir: path.resolve("dist"),
+    cwd: process.cwd(),
+    validateOnly: false,
+  };
+  for (let i = 0; i < raw.length; i++) {
+    const a = raw[i];
+    switch (a) {
+    case "--bundle": {
+    args.bundle = true;
+    break;
+    }
+    case "--validate-only": {
+    args.validateOnly = true;
+    break;
+    }
+    case "--out-dir": {
+    args.outDir = path.resolve(raw[++i]);
+    break;
+    }
+    case "--cwd": {
+    args.cwd = path.resolve(raw[++i]);
+    break;
+    }
+    case "--help": 
+    case "-h": {
+      printHelp();
+      process.exit(0);
+    
+    break;
+    }
+    // No default
+    }
+  }
+  return args;
+}
+
+function printHelp(): void {
+  console.log(`Usage: checkstack-scripts plugin-pack [options]
+
+Packs a Checkstack plugin into a .tgz, validating package.json metadata
+along the way. Run from the directory containing the plugin's package.json.
+
+Options:
+  --bundle           Pack the primary plus every sibling declared in
+                     package.json#checkstack.bundle into a single outer
+                     tarball with a bundle.json manifest.
+  --out-dir <dir>    Output directory (default: ./dist)
+  --validate-only    Only validate metadata; do not pack.
+  --cwd <dir>        Run as if invoked from <dir> (default: process.cwd())
+  --help, -h         Show this message.
+`);
+}
+
+function runScriptIfPresent({
+  cwd,
+  script,
+}: {
+  cwd: string;
+  script: string;
+}): void {
+  const pkg = readJson<{ scripts?: Record<string, string> }>(
+    path.join(cwd, "package.json"),
+  );
+  if (!pkg.scripts?.[script]) return;
+  console.log(`▶ bun run ${script}`);
+  const r = spawnSync("bun", ["run", script], { cwd, stdio: "inherit" });
+  if (r.status !== 0) {
+    throw new Error(`bun run ${script} exited with status ${r.status}`);
+  }
+}
+
+/**
+ * Walk up from `cwd` to find the workspace root (`package.json` with a
+ * `workspaces` field), then scan every workspace package and build a
+ * `name -> dir` map. Returns an empty map when no workspace ancestor
+ * exists (standalone plugin repo).
+ */
+function buildWorkspaceMap(cwd: string): Map<string, string> {
+  const result = new Map<string, string>();
+  const root = findWorkspaceRoot(cwd);
+  if (!root) return result;
+
+  const rootPkg = readJson<{ workspaces?: string[] | { packages?: string[] } }>(
+    path.join(root, "package.json"),
+  );
+  const patterns = Array.isArray(rootPkg.workspaces)
+    ? rootPkg.workspaces
+    : (rootPkg.workspaces?.packages ?? []);
+
+  for (const pattern of patterns) {
+    // Bun/npm globs are typically `core/*` or `plugins/*`. We resolve the
+    // direct child layer; deeper nesting is uncommon and not supported here.
+    const baseDir = pattern.replace(/\/\*$/, "");
+    const absBase = path.join(root, baseDir);
+    if (!fs.existsSync(absBase)) continue;
+    for (const entry of fs.readdirSync(absBase, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+      const dir = path.join(absBase, entry.name);
+      const pkgJsonPath = path.join(dir, "package.json");
+      if (!fs.existsSync(pkgJsonPath)) continue;
+      const pkg = readJson<{ name?: string }>(pkgJsonPath);
+      if (pkg.name) result.set(pkg.name, dir);
+    }
+  }
+
+  return result;
+}
+
+function findWorkspaceRoot(start: string): string | undefined {
+  let dir = start;
+  while (dir !== path.dirname(dir)) {
+    const pkgJsonPath = path.join(dir, "package.json");
+    if (fs.existsSync(pkgJsonPath)) {
+      const pkg = readJson<{ workspaces?: unknown }>(pkgJsonPath);
+      if (pkg.workspaces) return dir;
+    }
+    dir = path.dirname(dir);
+  }
+  return undefined;
+}
+
+/**
+ * Pack a single package into a tarball under `outDir`.
+ *
+ * Steps:
+ *   1. Read package.json
+ *   2. Replace `workspace:*` deps with concrete versions from `workspaceMap`
+ *   3. Run `bun pm pack` (which produces a tarball using the rewritten
+ *      package.json)
+ *   4. Restore the original package.json on disk so the developer's source
+ *      tree is unchanged
+ */
+async function packPackage({
+  pkgDir,
+  outDir,
+  workspaceMap,
+}: {
+  pkgDir: string;
+  outDir: string;
+  workspaceMap: Map<string, string>;
+}): Promise<string> {
+  const pkgJsonPath = path.join(pkgDir, "package.json");
+  const original = fs.readFileSync(pkgJsonPath, "utf8");
+  const pkg = JSON.parse(original) as InstallPackageMetadata & {
+    devDependencies?: Record<string, string>;
+    peerDependencies?: Record<string, string>;
+  };
+
+  let rewritten = false;
+  for (const section of [
+    "dependencies",
+    "devDependencies",
+    "peerDependencies",
+  ] as const) {
+    const block = pkg[section];
+    if (!block) continue;
+    for (const [name, range] of Object.entries(block)) {
+      if (range.startsWith("workspace:")) {
+        const targetDir = workspaceMap.get(name);
+        if (!targetDir) {
+          throw new Error(
+            `Cannot resolve workspace dep '${name}' (declared in '${pkg.name}'). ` +
+              `Either move the package into the workspace or replace the workspace range with a concrete version.`,
+          );
+        }
+        const targetPkg = readJson<{ version: string }>(
+          path.join(targetDir, "package.json"),
+        );
+        block[name] = `^${targetPkg.version}`;
+        rewritten = true;
+      }
+    }
+  }
+
+  try {
+    if (rewritten) {
+      fs.writeFileSync(pkgJsonPath, JSON.stringify(pkg, undefined, 2));
+    }
+    const r = spawnSync(
+      "bun",
+      ["pm", "pack", "--destination", outDir],
+      { cwd: pkgDir, stdio: "inherit" },
+    );
+    if (r.status !== 0) {
+      throw new Error(`bun pm pack exited with status ${r.status}`);
+    }
+  } finally {
+    if (rewritten) fs.writeFileSync(pkgJsonPath, original);
+  }
+
+  // `bun pm pack` writes `<scope>-<name>-<version>.tgz` (scope-prefix collapsed).
+  const expectedName = `${safeFileName(pkg.name)}-${pkg.version}.tgz`;
+  const expected = path.join(outDir, expectedName);
+  if (!fs.existsSync(expected)) {
+    // Fall back: pick the most recently modified tgz in outDir.
+    const all = fs
+      .readdirSync(outDir)
+      .filter((f) => f.endsWith(".tgz"))
+      .map((f) => ({
+        name: f,
+        mtime: fs.statSync(path.join(outDir, f)).mtime.getTime(),
+      }))
+      .toSorted((a, b) => b.mtime - a.mtime);
+    if (all.length === 0) {
+      throw new Error(`bun pm pack produced no tarball in ${outDir}`);
+    }
+    return path.join(outDir, all[0].name);
+  }
+  return expected;
+}
+
+function safeFileName(name: string): string {
+  return name.replace(/^@/, "").replaceAll('/', "-");
+}
+
+function readJson<T>(p: string): T {
+  return JSON.parse(fs.readFileSync(p, "utf8")) as T;
+}
+
+if (import.meta.main) {
+  const code = await runPluginPack(process.argv.slice(2));
+  process.exit(code);
+}

package/src/templates/backend/package.json.hbs

@@ -1,12 +1,41 @@
-{ "name": "@checkstack/{{pluginName}}", "version": "0.0.1",
-"checkstack": { "type": "backend" },
-"description": "{{pluginDescription}}", "type": "module", "exports": { ".": {
-"import": "./src/index.ts" } }, "scripts": { "typecheck": "tsc --noEmit",
-"lint": "bun run lint:code", "lint:code": "eslint . --max-warnings 0", "test":
-"bun test" }, "dependencies": { "@checkstack/backend-api": "workspace:*",
-"@checkstack/common": "workspace:*", "@checkstack/{{pluginBaseName}}-common":
-"workspace:*", "@orpc/server": "^1.13.2", "drizzle-orm": "^0.45.1" },
-"devDependencies": { "@checkstack/tsconfig": "workspace:*",
-"drizzle-kit": "^0.28.1", "@checkstack/drizzle-helper": "workspace:*",
-"@checkstack/test-utils-backend": "workspace:*", "typescript": "^5.7.2" }
-}
+{
+  "name": "@checkstack/{{pluginName}}",
+  "version": "0.0.1",
+  "description": "{{pluginDescription}}",
+  "author": "Checkstack contributors",
+  "license": "Elastic-2.0",
+  "type": "module",
+  "main": "src/index.ts",
+  "exports": {
+    ".": { "import": "./src/index.ts" }
+  },
+  "checkstack": {
+    "type": "backend",
+    "pluginId": "{{pluginBaseName}}"
+  },
+  "scripts": {
+    "dev": "checkstack-dev",
+    "pack": "bunx @checkstack/scripts plugin-pack",
+    "typecheck": "tsgo -b",
+    "lint": "bun run lint:code",
+    "lint:code": "eslint . --max-warnings 0",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@checkstack/backend-api": "workspace:*",
+    "@checkstack/common": "workspace:*",
+    "@checkstack/{{pluginBaseName}}-common": "workspace:*",
+    "@orpc/server": "^1.13.2",
+    "drizzle-orm": "^0.45.1"
+  },
+  "devDependencies": {
+    "@checkstack/scripts": "workspace:*",
+    "@checkstack/dev-server": "workspace:*",
+    "@checkstack/backend": "workspace:*",
+    "@checkstack/tsconfig": "workspace:*",
+    "@checkstack/drizzle-helper": "workspace:*",
+    "@checkstack/test-utils-backend": "workspace:*",
+    "drizzle-kit": "^0.28.1",
+    "typescript": "^5.7.2"
+  }
+}

package/src/templates/common/package.json.hbs

@@ -1,8 +1,32 @@
-{ "name": "@checkstack/{{pluginName}}", "version": "0.0.1",
-"checkstack": { "type": "common" },
-"description": "{{pluginDescription}}", "type": "module", "exports": { ".": {
-"import": "./src/index.ts" } }, "scripts": { "typecheck": "tsc --noEmit",
-"lint": "bun run lint:code", "lint:code": "eslint . --max-warnings 0" },
-"dependencies": { "@checkstack/common": "workspace:*", "@orpc/contract":
-"^1.13.2", "zod": "^3.23.0" }, "devDependencies": {
-"@checkstack/tsconfig": "workspace:*", "typescript": "^5.7.2" } }
+{
+  "name": "@checkstack/{{pluginName}}",
+  "version": "0.0.1",
+  "description": "{{pluginDescription}}",
+  "author": "Checkstack contributors",
+  "license": "Elastic-2.0",
+  "type": "module",
+  "main": "src/index.ts",
+  "exports": {
+    ".": { "import": "./src/index.ts" }
+  },
+  "checkstack": {
+    "type": "common",
+    "pluginId": "{{pluginBaseName}}"
+  },
+  "scripts": {
+    "pack": "bunx @checkstack/scripts plugin-pack",
+    "typecheck": "tsgo -b",
+    "lint": "bun run lint:code",
+    "lint:code": "eslint . --max-warnings 0"
+  },
+  "dependencies": {
+    "@checkstack/common": "workspace:*",
+    "@orpc/contract": "^1.13.2",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@checkstack/scripts": "workspace:*",
+    "@checkstack/tsconfig": "workspace:*",
+    "typescript": "^5.7.2"
+  }
+}

package/src/templates/frontend/package.json.hbs

@@ -1,13 +1,43 @@
-{ "name": "@checkstack/{{pluginName}}", "version": "0.0.1",
-"checkstack": { "type": "frontend" },
-"description": "{{pluginDescription}}", "type": "module", "exports": { ".": {
-"import": "./src/index.tsx" } }, "scripts": { "typecheck": "tsc --noEmit",
-"lint": "bun run lint:code", "lint:code": "eslint . --max-warnings 0",
-"test:e2e": "bunx playwright test" }, "dependencies": {
-"@checkstack/frontend-api": "workspace:*", "@checkstack/common":
-"workspace:*", "@checkstack/{{pluginBaseName}}-common": "workspace:*",
-"@checkstack/ui": "workspace:*", "react": "^18.3.1", "react-router-dom":
-"^7.1.1", "lucide-react": "^0.469.0" }, "devDependencies": {
-"@checkstack/tsconfig": "workspace:*", "@types/react": "^18.3.1",
-"@playwright/test": "^1.49.0", "@checkstack/test-utils-frontend":
-"workspace:*", "typescript": "^5.7.2" } }
+{
+  "name": "@checkstack/{{pluginName}}",
+  "version": "0.0.1",
+  "description": "{{pluginDescription}}",
+  "author": "Checkstack contributors",
+  "license": "Elastic-2.0",
+  "type": "module",
+  "main": "src/index.tsx",
+  "exports": {
+    ".": { "import": "./src/index.tsx" }
+  },
+  "checkstack": {
+    "type": "frontend",
+    "pluginId": "{{pluginBaseName}}"
+  },
+  "scripts": {
+    "dev": "checkstack-dev",
+    "pack": "bunx @checkstack/scripts plugin-pack",
+    "typecheck": "tsgo -b",
+    "lint": "bun run lint:code",
+    "lint:code": "eslint . --max-warnings 0",
+    "test:e2e": "bunx playwright test"
+  },
+  "dependencies": {
+    "@checkstack/frontend-api": "workspace:*",
+    "@checkstack/common": "workspace:*",
+    "@checkstack/{{pluginBaseName}}-common": "workspace:*",
+    "@checkstack/ui": "workspace:*",
+    "react": "^18.3.1",
+    "react-router-dom": "^7.1.1",
+    "lucide-react": "^0.469.0"
+  },
+  "devDependencies": {
+    "@checkstack/scripts": "workspace:*",
+    "@checkstack/dev-server": "workspace:*",
+    "@checkstack/frontend": "workspace:*",
+    "@checkstack/tsconfig": "workspace:*",
+    "@checkstack/test-utils-frontend": "workspace:*",
+    "@types/react": "^18.3.1",
+    "@playwright/test": "^1.49.0",
+    "typescript": "^5.7.2"
+  }
+}

package/src/templates.test.ts

@@ -4,8 +4,9 @@ import {
   prepareTemplateData,
   registerHelpers,
 } from "./utils/template";
+import { installPackageMetadataSchema } from "@checkstack/common";
 import { execSync } from "node:child_process";
-import { rmSync, existsSync, mkdirSync } from "node:fs";
+import { rmSync, existsSync, mkdirSync, readFileSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -129,6 +130,70 @@ describe("CLI Template Scaffolding", () => {
         },
         { timeout: 30_000 }
       );
+
+      // ────────────────────────────────────────────────────────────
+      // Dev-server compatibility — one-click `bun run dev` works
+      // out of the box. These tests run synchronously against the
+      // rendered package.json; no further `bun install` needed
+      // because they only inspect static metadata.
+      // ────────────────────────────────────────────────────────────
+
+      it("renders a package.json that the install-time validator accepts", () => {
+        // Validate against the same schema dev-server and the runtime
+        // plugin installer use. Inlined here (rather than imported from
+        // dev-server) so `@checkstack/scripts` doesn't take a dep on
+        // `@checkstack/dev-server`.
+        const pkgJsonPath = path.join(targetDir, "package.json");
+        const raw = JSON.parse(readFileSync(pkgJsonPath, "utf8")) as unknown;
+        const result = installPackageMetadataSchema.safeParse(raw);
+        if (!result.success) {
+          throw new Error(
+            `Generated package.json fails install-time validation:\n${result.error.issues
+              .map((issue) => `${issue.path.join(".")}: ${issue.message}`)
+              .join("\n")}`,
+          );
+        }
+        // Sanity-check the metadata shape so a later schema change
+        // surfaces here too.
+        expect(result.data.name).toBe(`@checkstack/${pluginName}`);
+        expect(result.data.checkstack.type).toBe(pluginType);
+        expect(result.data.checkstack.pluginId).toBe(TEST_BASE_NAME);
+        expect(result.data.author).toBeDefined();
+        expect(result.data.license).toBe("Elastic-2.0");
+      });
+
+      it("includes the @checkstack/scripts devDependency so `bunx @checkstack/scripts plugin-pack` resolves", () => {
+        const pkg = JSON.parse(
+          readFileSync(path.join(targetDir, "package.json"), "utf8"),
+        ) as { devDependencies?: Record<string, string> };
+        expect(pkg.devDependencies?.["@checkstack/scripts"]).toBeDefined();
+      });
+
+      it("includes @checkstack/dev-server (backend/frontend only) so the local dev loop is one-click", () => {
+        const pkg = JSON.parse(
+          readFileSync(path.join(targetDir, "package.json"), "utf8"),
+        ) as { devDependencies?: Record<string, string> };
+        if (pluginType === "common") {
+          // Common packages have no runtime, so the dev server makes no
+          // sense for them.
+          expect(pkg.devDependencies?.["@checkstack/dev-server"]).toBeUndefined();
+        } else {
+          expect(pkg.devDependencies?.["@checkstack/dev-server"]).toBeDefined();
+        }
+      });
+
+      it("includes the `pack` script (and the `dev` script for backend/frontend)", () => {
+        const pkg = JSON.parse(
+          readFileSync(path.join(targetDir, "package.json"), "utf8"),
+        ) as { scripts?: Record<string, string> };
+        expect(pkg.scripts?.pack).toBe("bunx @checkstack/scripts plugin-pack");
+        if (pluginType !== "common") {
+          // Backend/frontend templates pin the dev script to the
+          // `checkstack-dev` bin (provided by `@checkstack/dev-server`,
+          // which the template adds as a devDependency).
+          expect(pkg.scripts?.dev).toBe("checkstack-dev");
+        }
+      });
     });
   }
 });

package/CHANGELOG.md

@@ -1,89 +0,0 @@
-# @checkstack/scripts
-
-## 0.1.2
-
-### Patch Changes
-
-- 67158e2: Standardize package metadata, unify AJV versions to 8.18.0, and enforce monorepo architecture rules via updated ESLint configuration. This ensures consistent package discovery and runtime dependency safety across the platform.
-
-## 0.1.1
-
-### Patch Changes
-
-- 0b9fc58: Fix workspace:\* protocol resolution in published packages
-
-  Published packages now correctly have resolved dependency versions instead of `workspace:*` references. This is achieved by using `bun publish` which properly resolves workspace protocol references.
-
-## 0.1.0
-
-### Minor Changes
-
-- 9faec1f: # Unified AccessRule Terminology Refactoring
-
-  This release completes a comprehensive terminology refactoring from "permission" to "accessRule" across the entire codebase, establishing a consistent and modern access control vocabulary.
-
-  ## Changes
-
-  ### Core Infrastructure (`@checkstack/common`)
-
-  - Introduced `AccessRule` interface as the primary access control type
-  - Added `accessPair()` helper for creating read/manage access rule pairs
-  - Added `access()` builder for individual access rules
-  - Replaced `Permission` type with `AccessRule` throughout
-
-  ### API Changes
-
-  - `env.registerPermissions()` → `env.registerAccessRules()`
-  - `meta.permissions` → `meta.access` in RPC contracts
-  - `usePermission()` → `useAccess()` in frontend hooks
-  - Route `permission:` field → `accessRule:` field
-
-  ### UI Changes
-
-  - "Roles & Permissions" tab → "Roles & Access Rules"
-  - "You don't have permission..." → "You don't have access..."
-  - All permission-related UI text updated
-
-  ### Documentation & Templates
-
-  - Updated 18 documentation files with AccessRule terminology
-  - Updated 7 scaffolding templates with `accessPair()` pattern
-  - All code examples use new AccessRule API
-
-  ## Migration Guide
-
-  ### Backend Plugins
-
-  ```diff
-  - import { permissionList } from "./permissions";
-  - env.registerPermissions(permissionList);
-  + import { accessRules } from "./access";
-  + env.registerAccessRules(accessRules);
-  ```
-
-  ### RPC Contracts
-
-  ```diff
-  - .meta({ userType: "user", permissions: [permissions.read.id] })
-  + .meta({ userType: "user", access: [access.read] })
-  ```
-
-  ### Frontend Hooks
-
-  ```diff
-  - const canRead = accessApi.usePermission(permissions.read.id);
-  + const canRead = accessApi.useAccess(access.read);
-  ```
-
-  ### Routes
-
-  ```diff
-  - permission: permissions.entityRead.id,
-  + accessRule: access.read,
-  ```
-
-## 0.0.2
-
-### Patch Changes
-
-- d20d274: Initial release of all @checkstack packages. Rebranded from Checkmate to Checkstack with new npm organization @checkstack and domain checkstack.dev.

package/tsconfig.json

@@ -1,6 +0,0 @@
-{
-  "extends": "@checkstack/tsconfig/backend.json",
-  "include": [
-    "src"
-  ]
-}