@checkstack/scripts 0.3.3 → 0.4.0

package/src/templates/backend/drizzle/meta/0000_snapshot.json

@@ -0,0 +1,65 @@
+{
+  "id": "00000000-0000-0000-0000-000000000001",
+  "prevId": "00000000-0000-0000-0000-000000000000",
+  "version": "7",
+  "dialect": "postgresql",
+  "tables": {
+    "public.items": {
+      "name": "items",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "uuid",
+          "primaryKey": true,
+          "notNull": true,
+          "default": "gen_random_uuid()"
+        },
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "description": {
+          "name": "description",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    }
+  },
+  "enums": {},
+  "schemas": {},
+  "sequences": {},
+  "roles": {},
+  "policies": {},
+  "views": {},
+  "_meta": {
+    "columns": {},
+    "schemas": {},
+    "tables": {}
+  }
+}

package/src/templates/backend/drizzle/meta/_journal.json

@@ -0,0 +1,13 @@
+{
+  "version": "7",
+  "dialect": "postgresql",
+  "entries": [
+    {
+      "idx": 0,
+      "version": "7",
+      "when": 1748736000000,
+      "tag": "0000_init",
+      "breakpoints": true
+    }
+  ]
+}

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

@@ -2,7 +2,11 @@ import { defineConfig } from "drizzle-kit";
 
 export default defineConfig({
   schema: "./src/schema.ts",
-  out: "./migrations",
+  // The platform's plugin loader applies migrations from `<plugin>/drizzle`,
+  // so generated SQL must land there (NOT `./migrations`). The scaffold ships
+  // an initial `0000_init` migration for the example `items` table; running
+  // `bunx drizzle-kit generate` after editing the schema appends here.
+  out: "./drizzle",
   dialect: "postgresql",
   dbCredentials: {
     url: process.env.DATABASE_URL || "postgresql://localhost:5432/checkstack",

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

@@ -1,5 +1,5 @@
 {
-  "name": "@checkstack/{{pluginName}}",
+  "name": "{{scoped pluginName}}",
   "version": "0.0.1",
   "description": "{{pluginDescription}}",
   "author": "Checkstack contributors",
@@ -11,7 +11,11 @@
   },
   "checkstack": {
     "type": "backend",
-    "pluginId": "{{pluginBaseName}}"
+    "pluginId": "{{pluginBaseName}}",
+    "bundle": [
+      "{{scoped pluginBaseName}}-common",
+      "{{scoped pluginBaseName}}-frontend"
+    ]
   },
   "scripts": {
     "dev": "checkstack-dev",
@@ -24,7 +28,7 @@
   "dependencies": {
     "@checkstack/backend-api": "workspace:*",
     "@checkstack/common": "workspace:*",
-    "@checkstack/{{pluginBaseName}}-common": "workspace:*",
+    "{{scoped pluginBaseName}}-common": "workspace:*",
     "@orpc/server": "^1.13.2",
     "drizzle-orm": "^0.45.1"
   },

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

@@ -6,7 +6,7 @@ import {
   {{pluginNameCamel}}AccessRules,
   pluginMetadata,
   {{pluginNameCamel}}Contract,
-} from "@checkstack/{{pluginBaseName}}-common";
+} from "{{scoped pluginBaseName}}-common";
 import * as schema from "./schema";
 import { create{{pluginNamePascal}}Router } from "./router";
 

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

@@ -1,6 +1,6 @@
 import { implement } from "@orpc/server";
 import { autoAuthMiddleware, correlationMiddleware, type RpcContext, type SafeDatabase } from "@checkstack/backend-api";
-import { {{pluginNameCamel}}Contract } from "@checkstack/{{pluginBaseName}}-common";
+import { {{pluginNameCamel}}Contract } from "{{scoped pluginBaseName}}-common";
 import type * as schema from "./schema";
 import { {{pluginNamePascal}}Service } from "./service";
 

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

@@ -5,7 +5,7 @@ import { {{pluginNameCamel}}Items } from "./schema";
 import type {
   Create{{pluginNamePascal}}Item,
   Update{{pluginNamePascal}}Item,
-} from "@checkstack/{{pluginBaseName}}-common";
+} from "{{scoped pluginBaseName}}-common";
 
 export class {{pluginNamePascal}}Service {
   constructor(private readonly database: SafeDatabase<typeof schema>) {}

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

@@ -1,4 +1,4 @@
---- "@checkstack/{{pluginName}}": patch --- Initial release of
+--- "{{scoped pluginName}}": patch --- Initial release of
 {{pluginNamePascal}}
 plugin
 

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

@@ -1,11 +1,28 @@
-#
-{{pluginNamePascal}}
-Common Common package for the
-{{pluginNamePascal}}
-plugin. Contains shared contracts, types, and access rules. ## Structure -
-`src/access.ts - Access rule definitions - `src/schemas.ts` - Zod schemas
-and type definitions - `src/rpc-contract.ts` - oRPC contract definition -
-`src/index.ts` - Barrel exports ## Usage This package is consumed by both: -
-`@checkstack/{{pluginBaseName}}-backend` - Implements the contract -
-`@checkstack/{{pluginBaseName}}-frontend` - Consumes the contract ##
-Development ```bash # Type check bun run typecheck # Lint bun run lint ```
+# {{pluginNamePascal}} Common
+
+Common package for the {{pluginNamePascal}} plugin. Contains shared
+contracts, types, and access rules.
+
+## Structure
+
+- `src/access.ts` - Access rule definitions
+- `src/schemas.ts` - Zod schemas and type definitions
+- `src/rpc-contract.ts` - oRPC contract definition
+- `src/index.ts` - Barrel exports
+
+## Usage
+
+This package is consumed by both:
+
+- `{{scoped pluginBaseName}}-backend` - Implements the contract
+- `{{scoped pluginBaseName}}-frontend` - Consumes the contract
+
+## Development
+
+```bash
+# Type check
+bun run typecheck
+
+# Lint
+bun run lint
+```

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

@@ -1,5 +1,5 @@
 {
-  "name": "@checkstack/{{pluginName}}",
+  "name": "{{scoped pluginName}}",
   "version": "0.0.1",
   "description": "{{pluginDescription}}",
   "author": "Checkstack contributors",

package/src/templates/common/src/plugin-metadata.ts.hbs

@@ -3,4 +3,4 @@ metadata for the
 {{pluginNamePascal}}
 plugin. * Exported from the common package so both backend and frontend can *
 reference it. */ export const pluginMetadata = definePluginMetadata({ pluginId:
-"{{pluginId}}", });
+"{{pluginBaseName}}", });

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

@@ -1,4 +1,4 @@
---- "@checkstack/{{pluginName}}": patch --- Initial release of
+--- "{{scoped pluginName}}": patch --- Initial release of
 {{pluginNamePascal}}
 frontend plugin
 

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

@@ -1,5 +1,5 @@
 {
-  "name": "@checkstack/{{pluginName}}",
+  "name": "{{scoped pluginName}}",
   "version": "0.0.1",
   "description": "{{pluginDescription}}",
   "author": "Checkstack contributors",
@@ -24,7 +24,7 @@
   "dependencies": {
     "@checkstack/frontend-api": "workspace:*",
     "@checkstack/common": "workspace:*",
-    "@checkstack/{{pluginBaseName}}-common": "workspace:*",
+    "{{scoped pluginBaseName}}-common": "workspace:*",
     "@checkstack/ui": "workspace:*",
     "react": "^18.3.1",
     "react-router-dom": "^7.1.1",

package/src/templates/frontend/src/api.ts.hbs

@@ -3,7 +3,7 @@ export type {
   {{pluginNamePascal}}Item,
   Create{{pluginNamePascal}}Item,
   Update{{pluginNamePascal}}Item,
-} from "@checkstack/{{pluginBaseName}}-common";
+} from "{{scoped pluginBaseName}}-common";
 
 // Re-export the Api definition for usePluginClient usage
-export { {{pluginNamePascal}}Api } from "@checkstack/{{pluginBaseName}}-common";
+export { {{pluginNamePascal}}Api } from "{{scoped pluginBaseName}}-common";

package/src/templates/frontend/src/components/{{pluginNamePascal}}ListPage.tsx.hbs

@@ -1,5 +1,5 @@
 import { usePluginClient } from "@checkstack/frontend-api";
-import { {{pluginNamePascal}}Api } from "@checkstack/{{pluginBaseName}}-common";
+import { {{pluginNamePascal}}Api } from "{{scoped pluginBaseName}}-common";
 import type { {{pluginNamePascal}}Item } from "../api";
 import { Button, Card, PageLayout } from "@checkstack/ui";
 import { useNavigate } from "react-router-dom";

package/src/templates/frontend/src/index.tsx.hbs

@@ -1,15 +1,21 @@
 import { createFrontendPlugin } from "@checkstack/frontend-api";
-import { {{pluginNamePascal}}ListPage } from "./components/{{pluginNamePascal}}ListPage";
-import { {{pluginNameCamel}}Routes, pluginMetadata, {{pluginNameCamel}}Access } from "@checkstack/{{pluginBaseName}}-common";
+import { {{pluginNameCamel}}Routes, pluginMetadata, {{pluginNameCamel}}Access } from "{{scoped pluginBaseName}}-common";
 
 export default createFrontendPlugin({
   metadata: pluginMetadata,
 
-  // Register routes using typed route definitions
+  // Register routes using typed route definitions. Each route declares a `load`
+  // thunk: the framework code-splits the page and wraps it in Suspense + a
+  // per-plugin error boundary, so the page chunk is fetched on navigation
+  // (never in the initial app load). Use `load` for pages; light, always-on
+  // slot extensions (navbar/user-menu) use eager `component` instead.
   routes: [
     {
       route: {{pluginNameCamel}}Routes.routes.home,
-      element: <{{pluginNamePascal}}ListPage />,
+      load: () =>
+        import("./components/{{pluginNamePascal}}ListPage").then((m) => ({
+          default: m.{{pluginNamePascal}}ListPage,
+        })),
       title: "{{pluginNamePascal}}",
       accessRule: {{pluginNameCamel}}Access.read,
     },

package/src/templates/standalone-root/.changeset/config.json.hbs

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://unpkg.com/@changesets/config@3.1.2/schema.json",
+  "changelog": "@changesets/cli/changelog",
+  "commit": false,
+  "fixed": [],
+  "linked": [],
+  "access": "public",
+  "baseBranch": "main",
+  "updateInternalDependencies": "patch",
+  "ignore": []
+}

package/src/templates/standalone-root/.changeset/initial.md.hbs

@@ -0,0 +1,9 @@
+---
+"{{scoped pluginBaseName}}-common": patch
+"{{scoped pluginBaseName}}-backend": patch
+"{{scoped pluginBaseName}}-frontend": patch
+---
+
+Initial release of the {{pluginNamePascal}} plugin.
+
+{{pluginDescription}}

package/src/templates/standalone-root/README.md.hbs

@@ -0,0 +1,75 @@
+# {{pluginNamePascal}} plugin
+
+{{pluginDescription}}
+
+This is a standalone [Checkstack](https://enyineer.github.io/checkstack/)
+plugin workspace generated by `create-checkstack-plugin`. It contains a
+`common` contract package, a `backend` package implementing it, and a
+`frontend` package consuming it.
+
+## Prerequisites
+
+- [Bun](https://bun.sh) 1.1 or newer.
+- A local Postgres database. The dev server defaults to
+  `postgresql://checkstack:checkstack@localhost:5432/checkstack`. A quick
+  way to get one:
+
+  ```bash
+  docker run --name checkstack-pg -e POSTGRES_USER=checkstack \
+    -e POSTGRES_PASSWORD=checkstack -e POSTGRES_DB=checkstack \
+    -p 5432:5432 -d postgres:16-alpine
+  ```
+
+No Redis is required: the dev server auto-loads in-memory queue and cache
+providers.
+
+## Install
+
+```bash
+bun install
+```
+
+## Develop
+
+```bash
+bun run dev
+```
+
+This boots the Checkstack dev server with synthetic dev auth enabled, runs
+the backend with hot reload, and starts the frontend Vite dev server. Every
+access rule the plugin registers is auto-granted to a `dev-user`, so no
+login is needed.
+
+Once it is up, the plugin's CRUD API is served under `/api/{{pluginBaseName}}/*`.
+For example, list the example `items`:
+
+```bash
+curl -X POST http://localhost:3000/api/{{pluginBaseName}}/getItems \
+  -H 'content-type: application/json' \
+  -d '{}'
+```
+
+## What is in the box
+
+- `packages/{{pluginBaseName}}-common` - the oRPC contract, Zod schemas, and
+  access rules shared by backend and frontend.
+- `packages/{{pluginBaseName}}-backend` - a single `items` table (Drizzle)
+  plus CRUD procedures (`getItems`, `getItem`, `createItem`, `updateItem`,
+  `deleteItem`).
+- `packages/{{pluginBaseName}}-frontend` - one list page wired to the typed
+  client.
+
+> The default skeleton deliberately omits a reactive `defineEntity`
+> state machine to keep first boot minimal. See the Checkstack docs on
+> reactive entities when you are ready to add one.
+
+## Pack for distribution
+
+```bash
+bun run pack
+```
+
+This produces a bundle tarball under
+`packages/{{pluginBaseName}}-backend/dist/` containing the backend primary
+plus the `-common` and `-frontend` siblings, ready to upload via the Plugin
+Manager.

package/src/templates/standalone-root/eslint.config.mjs.hbs

@@ -0,0 +1,37 @@
+import js from "@eslint/js";
+import tseslint from "typescript-eslint";
+import reactHooks from "eslint-plugin-react-hooks";
+
+// Standalone Checkstack plugin lint config. Mirrors the subset of the
+// monorepo's rules that apply to plugin source. The monorepo-only custom
+// `checkstack/*` rules and the project-references plumbing are intentionally
+// omitted - they depend on the monorepo's internal tooling.
+export default tseslint.config(
+  {
+    ignores: [
+      "**/node_modules/**",
+      "**/dist/**",
+      "**/.tsbuild/**",
+      "**/drizzle/**",
+      "**/*.test.ts",
+      "**/*.test.tsx",
+      "**/*.e2e.ts",
+    ],
+  },
+  js.configs.recommended,
+  ...tseslint.configs.recommended,
+  {
+    plugins: {
+      "react-hooks": reactHooks,
+    },
+    rules: {
+      "@typescript-eslint/no-explicit-any": "error",
+      "@typescript-eslint/no-unused-vars": [
+        "error",
+        { argsIgnorePattern: "^_", varsIgnorePattern: "^_" },
+      ],
+      "react-hooks/rules-of-hooks": "error",
+      "react-hooks/exhaustive-deps": "warn",
+    },
+  },
+);

package/src/templates/standalone-root/package.json.hbs

@@ -0,0 +1,27 @@
+{
+  "name": "{{pluginBaseName}}-plugin",
+  "version": "0.0.1",
+  "description": "{{pluginDescription}}",
+  "private": true,
+  "license": "Elastic-2.0",
+  "type": "module",
+  "workspaces": [
+    "packages/*"
+  ],
+  "scripts": {
+    "dev": "bun run --filter '{{scoped pluginBaseName}}-backend' dev",
+    "pack": "bun run --filter '{{scoped pluginBaseName}}-backend' pack -- --bundle",
+    "typecheck": "bun run --filter '*' typecheck",
+    "lint": "bun run --filter '*' lint",
+    "test": "bun run --filter '*' test",
+    "changeset": "changeset"
+  },
+  "devDependencies": {
+    "@changesets/cli": "^2.31.0",
+    "@eslint/js": "^9.39.4",
+    "eslint": "^9.39.4",
+    "eslint-plugin-react-hooks": "^7.1.1",
+    "typescript": "^5.7.2",
+    "typescript-eslint": "^8.59.3"
+  }
+}

package/src/templates/standalone-root/tsconfig.json.hbs

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "noEmit": true,
+    "composite": false
+  },
+  "files": [],
+  "include": [],
+  "references": [
+    { "path": "./packages/{{pluginBaseName}}-common" },
+    { "path": "./packages/{{pluginBaseName}}-backend" },
+    { "path": "./packages/{{pluginBaseName}}-frontend" }
+  ]
+}

package/src/templates.test.ts

@@ -200,6 +200,26 @@ describe("CLI Template Scaffolding", () => {
           expect(pkg.scripts?.dev).toBe("checkstack-dev");
         }
       });
+
+      if (pluginType === "common") {
+        // Regression guard (#251 Phase 3): the common package's
+        // `definePluginMetadata({ pluginId })` MUST be the bare base name —
+        // the same value the backend's `checkstack.pluginId` uses for
+        // `/api/<pluginId>/*` routing. If this drifts to `<base>-common`
+        // (the `pluginName`), the plugin-metadata registry is keyed
+        // differently from the route and every request 500s with
+        // "Plugin metadata not found in registry". The end-to-end
+        // `*.it.test.ts` lane catches it too, but this pins it in the fast
+        // lane so the fix can't silently regress.
+        it("declares the routing pluginId (base name) in plugin-metadata.ts", () => {
+          const metaSrc = readFileSync(
+            path.join(targetDir, "src", "plugin-metadata.ts"),
+            "utf8",
+          );
+          expect(metaSrc).toContain(`pluginId:\n"${TEST_BASE_NAME}"`);
+          expect(metaSrc).not.toContain(`"${TEST_BASE_NAME}-common"`);
+        });
+      }
     });
   }
 });

package/src/tui/components.test.tsx

@@ -0,0 +1,28 @@
+import { describe, it, expect } from "bun:test";
+import React from "react";
+import { renderToString } from "ink";
+import { Spinner, SPINNER_FRAMES } from "./components.tsx";
+
+describe("Spinner", () => {
+  it("renders the glyph for the given frame", () => {
+    expect(renderToString(<Spinner frame={0} />)).toContain(SPINNER_FRAMES[0]);
+    expect(renderToString(<Spinner frame={1} />)).toContain(SPINNER_FRAMES[1]);
+  });
+
+  it("wraps the frame index over the frame set", () => {
+    const len = SPINNER_FRAMES.length;
+    expect(renderToString(<Spinner frame={len} />)).toContain(
+      SPINNER_FRAMES[0],
+    );
+    expect(renderToString(<Spinner frame={len + 2} />)).toContain(
+      SPINNER_FRAMES[2],
+    );
+  });
+
+  it("is safe for a negative frame", () => {
+    // Should not throw or render `undefined`.
+    const frame = renderToString(<Spinner frame={-1} />);
+    expect(frame).toContain(SPINNER_FRAMES[SPINNER_FRAMES.length - 1]);
+    expect(frame).not.toContain("undefined");
+  });
+});