@checkstack/scripts 0.0.2

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @checkstack/scripts
+
+## 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/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@checkstack/scripts",
+  "version": "0.0.2",
+  "bin": {
+    "checkstack-scripts": "./src/cli.ts"
+  },
+  "scripts": {
+    "sync": "bun run src/sync.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "inquirer": "^8.1.0",
+    "handlebars": "^4.7.8"
+  },
+  "devDependencies": {
+    "@checkstack/tsconfig": "workspace:*",
+    "@types/inquirer": "^8.2.10",
+    "@types/handlebars": "^4.1.0",
+    "typescript": "^5.0.0"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,56 @@
+#!/usr/bin/env bun
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+
+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");
+  process.exit(1);
+}
+
+const rootDir = process.cwd();
+
+if (command === "sync") {
+  const result = spawnSync(
+    "bun",
+    ["run", path.join(rootDir, "core/scripts/src/sync.ts")],
+    {
+      stdio: "inherit",
+    }
+  );
+  process.exit(result.status ?? 0);
+}
+
+if (command === "create") {
+  const result = spawnSync(
+    "bun",
+    ["run", path.join(rootDir, "core/scripts/src/commands/create.ts")],
+    {
+      stdio: "inherit",
+    }
+  );
+  process.exit(result.status ?? 0);
+}
+
+if (command === "generate") {
+  const result = spawnSync(
+    "bun",
+    [path.join(rootDir, "core/scripts/src/commands/generate.ts")],
+    {
+      cwd: rootDir, // Keep cwd as root, script will handle paths
+      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

@@ -0,0 +1,259 @@
+#!/usr/bin/env bun
+import inquirer from "inquirer";
+import path from "node:path";
+import {
+  validatePluginName,
+  pluginExists,
+  packageExists,
+  extractBaseName,
+} from "../utils/validation";
+import {
+  registerHelpers,
+  copyTemplate,
+  prepareTemplateData,
+} from "../utils/template";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+interface PluginTypeChoice {
+  name: string;
+  value: string;
+  description: string;
+}
+
+interface LocationChoice {
+  name: string;
+  value: "core" | "plugins";
+  description: string;
+}
+
+const PACKAGE_LOCATIONS: LocationChoice[] = [
+  {
+    name: "core/    - Core platform component (essential, non-replaceable)",
+    value: "core",
+    description: "Core platform component",
+  },
+  {
+    name: "plugins/ - Replaceable provider (optional, swappable)",
+    value: "plugins",
+    description: "Replaceable provider plugin",
+  },
+];
+
+const PLUGIN_TYPES: PluginTypeChoice[] = [
+  {
+    name: "backend   - Backend plugin with oRPC router",
+    value: "backend",
+    description: "Backend plugin with oRPC router",
+  },
+  {
+    name: "frontend  - Frontend plugin with React components",
+    value: "frontend",
+    description: "Frontend plugin with React components",
+  },
+  {
+    name: "common    - Common plugin with contracts and types",
+    value: "common",
+    description: "Common plugin with contracts and types",
+  },
+  {
+    name: "node      - Node.js utility plugin",
+    value: "node",
+    description: "Node.js utility plugin",
+  },
+  {
+    name: "react     - React component library plugin",
+    value: "react",
+    description: "React component library plugin",
+  },
+];
+
+export async function createCommand() {
+  console.log("\n🚀 Checkstack Package Generator\n");
+
+  // Register Handlebars helpers
+  registerHelpers();
+
+  // Prompt for package location
+  const { packageLocation } = await inquirer.prompt<{
+    packageLocation: "core" | "plugins";
+  }>([
+    {
+      type: "list",
+      name: "packageLocation",
+      message: "Where should the package be created?",
+      choices: PACKAGE_LOCATIONS,
+    },
+  ]);
+
+  // Show guidance based on choice
+  if (packageLocation === "core") {
+    console.log(
+      "\n📦 Core packages are essential platform components that cannot be removed."
+    );
+    console.log(
+      "   Examples: auth, catalog, notifications, queue, healthcheck, theme\n"
+    );
+  } else {
+    console.log(
+      "\n🔌 Plugins are replaceable providers that can be swapped or removed."
+    );
+    console.log(
+      "   Examples: auth-github, auth-ldap, queue-bullmq, healthcheck-http\n"
+    );
+  }
+
+  // Prompt for plugin type
+  const { pluginType } = await inquirer.prompt<{ pluginType: string }>([
+    {
+      type: "list",
+      name: "pluginType",
+      message: "What type of package do you want to create?",
+      choices: PLUGIN_TYPES,
+    },
+  ]);
+
+  // Prompt for plugin name
+  const { pluginBaseName } = await inquirer.prompt<{ pluginBaseName: string }>([
+    {
+      type: "input",
+      name: "pluginBaseName",
+      message: `Package name (e.g., 'catalog' for 'catalog-${pluginType}'):`,
+      validate: (input: string) => {
+        const extracted = extractBaseName(input);
+        const validation = validatePluginName(extracted);
+        return validation.valid || validation.error || false;
+      },
+      filter: (input: string) => extractBaseName(input.trim()),
+    },
+  ]);
+
+  // Check if plugin already exists
+  const rootDir = process.cwd();
+  const existsInPlugins = pluginExists({
+    baseName: pluginBaseName,
+    pluginType,
+    rootDir,
+  });
+  const existsInPackages = packageExists({
+    baseName: pluginBaseName,
+    pluginType,
+    rootDir,
+  });
+
+  if (existsInPlugins || existsInPackages) {
+    const existingLocation = existsInPackages ? "core" : "plugins";
+    console.error(
+      `\n❌ Error: '${pluginBaseName}-${pluginType}' already exists in ${existingLocation}/!\n`
+    );
+    process.exit(1);
+  }
+
+  // Prompt for description
+  const { description } = await inquirer.prompt<{ description: string }>([
+    {
+      type: "input",
+      name: "description",
+      message: "Package description (optional):",
+      default: `${
+        pluginBaseName.charAt(0).toUpperCase() + pluginBaseName.slice(1)
+      } ${packageLocation === "core" ? "package" : "plugin"}`,
+    },
+  ]);
+
+  // Prepare template data
+  const templateData = prepareTemplateData({
+    baseName: pluginBaseName,
+    pluginType,
+    description,
+  });
+
+  // Confirm before generation
+  const locationLabel = packageLocation === "core" ? "package" : "plugin";
+  const { confirmed } = await inquirer.prompt<{ confirmed: boolean }>([
+    {
+      type: "confirm",
+      name: "confirmed",
+      message: `Create ${pluginType} ${locationLabel} '${templateData.pluginName}' in ${packageLocation}/?`,
+      default: true,
+    },
+  ]);
+
+  if (!confirmed) {
+    console.log("\n❌ Creation cancelled.\n");
+    process.exit(0);
+  }
+
+  // Generate plugin from template
+  console.log(
+    `\n📦 Creating ${pluginType} ${locationLabel}: ${templateData.pluginName}`
+  );
+
+  const templateDir = path.join(__dirname, "..", "templates", pluginType);
+  const targetDir = path.join(
+    rootDir,
+    packageLocation,
+    templateData.pluginName
+  );
+
+  try {
+    const createdFiles = copyTemplate({
+      templateDir,
+      targetDir,
+      data: templateData,
+    });
+
+    console.log(
+      `  ✓ Created directory: ${packageLocation}/${templateData.pluginName}`
+    );
+
+    // Show created files
+    const relativeFiles = createdFiles.map((file) =>
+      path.relative(targetDir, file)
+    );
+    for (const file of relativeFiles) {
+      console.log(`  ✓ Generated ${file}`);
+    }
+
+    // Success message with next steps
+    console.log(
+      `\n✅ ${
+        locationLabel.charAt(0).toUpperCase() + locationLabel.slice(1)
+      } created successfully!\n`
+    );
+    console.log("Next steps:");
+    console.log(`  1. cd ${packageLocation}/${templateData.pluginName}`);
+    console.log(`  2. bun install`);
+
+    // Type-specific instructions
+    switch (pluginType) {
+      case "backend": {
+        console.log(`  3. Update src/schema.ts with your database schema`);
+        console.log(`  4. Update src/router.ts with your RPC procedures`);
+        console.log(`  5. Generate migrations: bun run drizzle-kit generate`);
+        break;
+      }
+      case "frontend": {
+        console.log(`  3. Update src/api.ts with your API client`);
+        console.log(`  4. Create your page components in src/components/`);
+        break;
+      }
+      case "common": {
+        console.log(`  3. Define your permissions in src/permissions.ts`);
+        console.log(`  4. Define your schemas in src/schemas.ts`);
+        console.log(`  5. Define your contract in src/rpc-contract.ts`);
+        break;
+      }
+      // No additional steps for node and react types
+    }
+
+    console.log(`  6. Review the initial changeset in .changeset/initial.md\n`);
+  } catch (error) {
+    console.error(`\n❌ Error creating ${locationLabel}: ${error}\n`);
+    process.exit(1);
+  }
+}
+
+// Run the command when executed directly
+await createCommand();

package/src/sync.ts

@@ -0,0 +1,125 @@
+import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import path from "node:path";
+import { Glob } from "bun";
+
+function stripComments(text: string) {
+  return text.replaceAll(/\/\/.*|\/\*[\s\S]*?\*\//g, "");
+}
+
+const rootDir = process.cwd();
+
+// Standard scripts we want to share
+const STANDARD_SCRIPTS: Record<string, string> = {
+  typecheck: "tsc --noEmit",
+  lint: "bun run lint:code",
+  "lint:code": "eslint . --max-warnings 0",
+};
+
+const packageGlob = new Glob("{packages,plugins}/*/package.json");
+const packages = [...packageGlob.scanSync({ cwd: rootDir })];
+
+console.log(`Checking ${packages.length} packages for synchronization...`);
+
+for (const pkgPath of packages) {
+  const fullPkgPath = path.join(rootDir, pkgPath);
+  const pkgDir = path.join(rootDir, pkgPath.replaceAll("/package.json", ""));
+  const tsconfigPath = path.join(pkgDir, "tsconfig.json");
+
+  const pkgContent = readFileSync(fullPkgPath, "utf8");
+  let pkg;
+  try {
+    pkg = JSON.parse(pkgContent);
+  } catch {
+    console.error(`Failed to parse ${fullPkgPath}`);
+    continue;
+  }
+
+  if (
+    pkg.name === "@checkstack/scripts" ||
+    pkg.name === "@checkstack/tsconfig"
+  )
+    continue;
+
+  let pkgChanged = false;
+  pkg.scripts = pkg.scripts || {};
+  pkg.devDependencies = pkg.devDependencies || {};
+
+  // Ensure @checkstack/scripts is present
+  if (pkg.devDependencies["@checkstack/scripts"] !== "workspace:*") {
+    console.log(
+      `  [${pkg.name}] Adding @checkstack/scripts to devDependencies`
+    );
+    pkg.devDependencies["@checkstack/scripts"] = "workspace:*";
+    pkgChanged = true;
+  }
+
+  // Update scripts
+  for (const [name, script] of Object.entries(STANDARD_SCRIPTS)) {
+    if (pkg.scripts[name] !== script) {
+      console.log(`  [${pkg.name}] Updating script: ${name}`);
+      pkg.scripts[name] = script;
+      pkgChanged = true;
+    }
+  }
+
+  if (pkgChanged) {
+    writeFileSync(fullPkgPath, JSON.stringify(pkg, undefined, 2) + "\n");
+  }
+
+  // Manage tsconfig.json
+  if (existsSync(tsconfigPath)) {
+    const tsconfigContent = readFileSync(tsconfigPath, "utf8");
+    let tsconfig;
+    try {
+      tsconfig = JSON.parse(stripComments(tsconfigContent));
+    } catch {
+      continue;
+    }
+
+    let tsconfigChanged = false;
+
+    // Determine correct configType
+    let configType = "backend.json";
+    const isFrontend =
+      pkgPath.includes("frontend") ||
+      pkg.name.match(/frontend|ui|dashboard/) ||
+      (pkg.dependencies &&
+        (pkg.dependencies["react"] || pkg.dependencies["vite"]));
+    const isCommon = pkgPath.includes("common") || pkg.name.includes("common");
+
+    if (isFrontend) {
+      configType = "frontend.json";
+    } else if (isCommon) {
+      configType = "common.json";
+    }
+
+    const expectedExtends = `@checkstack/tsconfig/${configType}`;
+    if (tsconfig.extends !== expectedExtends) {
+      console.log(
+        `  [${pkg.name}] Updating tsconfig extends to ${expectedExtends}`
+      );
+      tsconfig.extends = expectedExtends;
+      tsconfigChanged = true;
+    }
+
+    // Repair corrupted include path
+    if (Array.isArray(tsconfig.include) && tsconfig.include.includes("src*")) {
+      console.log(
+        `  [${pkg.name}] Fixing corrupted include path in tsconfig.json`
+      );
+      tsconfig.include = tsconfig.include.map((i: string) =>
+        i === "src*" ? "src" : i
+      );
+      tsconfigChanged = true;
+    }
+
+    if (tsconfigChanged) {
+      writeFileSync(
+        tsconfigPath,
+        JSON.stringify(tsconfig, undefined, 2) + "\n"
+      );
+    }
+  }
+}
+
+console.log("Synchronization complete!");

package/src/templates/backend/.changeset/initial.md.hbs

@@ -0,0 +1,5 @@
+--- "@checkstack/{{pluginName}}": patch --- Initial release of
+{{pluginNamePascal}}
+backend plugin
+
+{{pluginDescription}}

package/src/templates/backend/README.md.hbs

@@ -0,0 +1,46 @@
+# {{pluginNamePascal}} Backend
+
+Backend plugin for {{pluginNamePascal}}. Implements the oRPC contract with database persistence.
+
+## Structure
+
+- `src/index.ts` - Plugin entry point
+- `src/router.ts` - oRPC router implementation
+- `src/service.ts` - Business logic layer
+- `src/schema.ts` - Drizzle database schema
+- `drizzle.config.ts` - Drizzle Kit configuration
+- `migrations/` - Database migrations (generated)
+
+## Development
+
+### Generate Migration
+
+After modifying `src/schema.ts`:
+
+```bash
+bun run drizzle-kit generate
+```
+
+### Run Migration
+
+```bash
+bun run drizzle-kit migrate
+```
+
+### Type Check
+
+```bash
+bun run typecheck
+```
+
+### Lint
+
+```bash
+bun run lint
+```
+
+## Testing
+
+```bash
+bun test
+```

package/src/templates/backend/drizzle.config.ts.hbs

@@ -0,0 +1,10 @@
+import { defineConfig } from "drizzle-kit";
+
+export default defineConfig({
+  schema: "./src/schema.ts",
+  out: "./migrations",
+  dialect: "postgresql",
+  dbCredentials: {
+    url: process.env.DATABASE_URL || "postgresql://localhost:5432/checkstack",
+  },
+});

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

@@ -0,0 +1,11 @@
+{ "name": "@checkstack/{{pluginName}}", "version": "0.0.1",
+"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" }
+}

package/src/templates/backend/src/index.ts.hbs

@@ -0,0 +1,35 @@
+import {
+  createBackendPlugin,
+  coreServices,
+} from "@checkstack/backend-api";
+import {
+  permissionList,
+  pluginMetadata,
+  {{pluginNameCamel}}Contract,
+} from "@checkstack/{{pluginBaseName}}-common";
+import * as schema from "./schema";
+import { create{{pluginNamePascal}}Router } from "./router";
+
+export default createBackendPlugin({
+  metadata: pluginMetadata,
+  register(env) {
+    env.registerPermissions(permissionList);
+
+    env.registerInit({
+      schema,
+      deps: {
+        rpc: coreServices.rpc,
+        logger: coreServices.logger,
+      },
+      init: async ({ database, rpc, logger }) => {
+        logger.debug("Initializing {{pluginNamePascal}} Backend...");
+
+        // Create and register router with plugin-scoped database
+        const router = create{{pluginNamePascal}}Router({ database });
+        rpc.registerRouter(router, {{pluginNameCamel}}Contract);
+
+        logger.debug("✅ {{pluginNamePascal}} Backend initialized.");
+      },
+    });
+  },
+});

package/src/templates/backend/src/router.ts.hbs

@@ -0,0 +1,46 @@
+import { implement } from "@orpc/server";
+import { autoAuthMiddleware, type RpcContext } from "@checkstack/backend-api";
+import { {{pluginNameCamel}}Contract } from "@checkstack/{{pluginBaseName}}-common";
+import type { NodePgDatabase } from "drizzle-orm/node-postgres";
+import type * as schema from "./schema";
+import { {{pluginNamePascal}}Service } from "./service";
+
+/**
+ * Creates the {{pluginBaseName}} router using contract-based implementation.
+ *
+ * Auth and permissions are automatically enforced via autoAuthMiddleware
+ * based on the contract's meta.userType and meta.permissions.
+ */
+const os = implement({{pluginNameCamel}}Contract)
+  .$context<RpcContext>()
+  .use(autoAuthMiddleware);
+
+export function create{{pluginNamePascal}}Router({
+  database,
+}: {
+  database: NodePgDatabase<typeof schema>;
+}) {
+  const service = new {{pluginNamePascal}}Service(database);
+
+  return os.router({
+    getItems: os.getItems.handler(async () => {
+      return await service.getItems();
+    }),
+
+    getItem: os.getItem.handler(async ({ input }) => {
+      return await service.getItem(input);
+    }),
+
+    createItem: os.createItem.handler(async ({ input }) => {
+      return await service.createItem(input);
+    }),
+
+    updateItem: os.updateItem.handler(async ({ input }) => {
+      return await service.updateItem(input.id, input.data);
+    }),
+
+    deleteItem: os.deleteItem.handler(async ({ input }) => {
+      await service.deleteItem(input);
+    }),
+  });
+}

package/src/templates/backend/src/schema.ts.hbs

@@ -0,0 +1,19 @@
+import { pgTable, text, timestamp, uuid } from "drizzle-orm/pg-core";
+
+/**
+ * Plugin database schema.
+ *
+ * Tables use `pgTable()` for schema-agnostic definitions.
+ * At runtime, the plugin's database connection uses `search_path`
+ * to route all queries to the plugin's isolated schema.
+ */
+export const {{pluginNameCamel}}Items = pgTable("items", {
+  id: uuid("id").primaryKey().defaultRandom(),
+  name: text("name").notNull(),
+  description: text("description"),
+  createdAt: timestamp("created_at").notNull().defaultNow(),
+  updatedAt: timestamp("updated_at").notNull().defaultNow(),
+});
+
+export type {{pluginNamePascal}}Item = typeof {{pluginNameCamel}}Items.$inferSelect;
+export type New{{pluginNamePascal}}Item = typeof {{pluginNameCamel}}Items.$inferInsert;