@checkstack/scripts 0.0.2 → 0.1.1

package/CHANGELOG.md

@@ -1,5 +1,81 @@
 # @checkstack/scripts
 
+## 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/scripts",
-  "version": "0.0.2",
+  "version": "0.1.1",
   "bin": {
     "checkstack-scripts": "./src/cli.ts"
   },
@@ -13,7 +13,7 @@
     "handlebars": "^4.7.8"
   },
   "devDependencies": {
-    "@checkstack/tsconfig": "workspace:*",
+    "@checkstack/tsconfig": "0.0.2",
     "@types/inquirer": "^8.2.10",
     "@types/handlebars": "^4.1.0",
     "typescript": "^5.0.0"

package/src/commands/create.ts

@@ -240,7 +240,7 @@ export async function createCommand() {
         break;
       }
       case "common": {
-        console.log(`  3. Define your permissions in src/permissions.ts`);
+        console.log(`  3. Define your access rules in src/access.ts`);
         console.log(`  4. Define your schemas in src/schemas.ts`);
         console.log(`  5. Define your contract in src/rpc-contract.ts`);
         break;

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

@@ -3,7 +3,7 @@ import {
   coreServices,
 } from "@checkstack/backend-api";
 import {
-  permissionList,
+  {{pluginNameCamel}}AccessRules,
   pluginMetadata,
   {{pluginNameCamel}}Contract,
 } from "@checkstack/{{pluginBaseName}}-common";
@@ -13,7 +13,7 @@ import { create{{pluginNamePascal}}Router } from "./router";
 export default createBackendPlugin({
   metadata: pluginMetadata,
   register(env) {
-    env.registerPermissions(permissionList);
+    env.registerAccessRules({{pluginNameCamel}}AccessRules);
 
     env.registerInit({
       schema,

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

@@ -1,15 +1,14 @@
 import { implement } from "@orpc/server";
-import { autoAuthMiddleware, type RpcContext } from "@checkstack/backend-api";
+import { autoAuthMiddleware, type RpcContext, type SafeDatabase } 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.
+ * Auth and access rules are automatically enforced via autoAuthMiddleware
+ * based on the contract's meta.userType and meta.access.
  */
 const os = implement({{pluginNameCamel}}Contract)
   .$context<RpcContext>()
@@ -18,7 +17,7 @@ const os = implement({{pluginNameCamel}}Contract)
 export function create{{pluginNamePascal}}Router({
   database,
 }: {
-  database: NodePgDatabase<typeof schema>;
+  database: SafeDatabase<typeof schema>;
 }) {
   const service = new {{pluginNamePascal}}Service(database);
 
@@ -28,7 +27,7 @@ export function create{{pluginNamePascal}}Router({
     }),
 
     getItem: os.getItem.handler(async ({ input }) => {
-      return await service.getItem(input);
+      return await service.getItem(input.id);
     }),
 
     createItem: os.createItem.handler(async ({ input }) => {
@@ -40,7 +39,7 @@ export function create{{pluginNamePascal}}Router({
     }),
 
     deleteItem: os.deleteItem.handler(async ({ input }) => {
-      await service.deleteItem(input);
+      await service.deleteItem(input.id);
     }),
   });
 }

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

@@ -1,4 +1,4 @@
-import type { NodePgDatabase } from "drizzle-orm/node-postgres";
+import type { SafeDatabase } from "@checkstack/backend-api";
 import { eq } from "drizzle-orm";
 import * as schema from "./schema";
 import { {{pluginNameCamel}}Items } from "./schema";
@@ -8,7 +8,7 @@ import type {
 } from "@checkstack/{{pluginBaseName}}-common";
 
 export class {{pluginNamePascal}}Service {
-  constructor(private readonly database: NodePgDatabase<typeof schema>) {}
+  constructor(private readonly database: SafeDatabase<typeof schema>) {}
 
   async getItems() {
     return await this.database.select().from({{pluginNameCamel}}Items);

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

@@ -2,8 +2,8 @@
 {{pluginNamePascal}}
 Common Common package for the
 {{pluginNamePascal}}
-plugin. Contains shared contracts, types, and permissions. ## Structure -
-`src/permissions.ts` - Permission definitions - `src/schemas.ts` - Zod schemas
+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 -

package/src/templates/common/src/access.ts.hbs

@@ -0,0 +1,27 @@
+import { accessPair } from "@checkstack/common";
+
+/**
+ * Access rules for the {{pluginBaseName}} plugin.
+ * Uses accessPair() to create read/manage access rule pairs.
+ */
+export const {{pluginNameCamel}}Access = {
+  /**
+   * Access rules for {{pluginBaseName}} data operations.
+   * - read: View {{pluginBaseName}} data (auto-assigned to authenticated users)
+   * - manage: Create, update, and delete {{pluginBaseName}} data
+   */
+  ...accessPair("{{pluginBaseName}}", {
+    read: {
+      description: "Read {{pluginBaseName}} data",
+      isDefault: true, // read is auto-assigned to "users" role
+    },
+    manage: {
+      description: "Manage {{pluginBaseName}} data",
+    },
+  }),
+};
+
+/**
+ * List of all access rules for registration.
+ */
+export const {{pluginNameCamel}}AccessRules = Object.values({{pluginNameCamel}}Access);

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

@@ -1,5 +1,5 @@
-// Export permissions
-export { permissions, permissionList } from "./permissions";
+// Export access rules
+export { {{pluginNameCamel}}Access, {{pluginNameCamel}}AccessRules } from "./access";
 
 // Export routes
 export { {{pluginNameCamel}}Routes } from "./routes";

package/src/templates/common/src/rpc-contract.ts.hbs

@@ -1,39 +1,45 @@
-import { oc } from "@orpc/contract";
-import { createClientDefinition, type ProcedureMetadata } from "@checkstack/common";
+import { createClientDefinition, proc } from "@checkstack/common";
 import { z } from "zod";
 import {
   {{pluginNamePascal}}ItemSchema,
   Create{{pluginNamePascal}}ItemSchema,
   Update{{pluginNamePascal}}ItemSchema,
 } from "./schemas";
-import { permissions } from "./permissions";
+import { {{pluginNameCamel}}Access } from "./access";
 import { pluginMetadata } from "./plugin-metadata";
 
-// Create base builder with ProcedureMetadata support
-// See: https://docs.checkstack.dev/common-plugins#contract-based-auth-enforcement
-const _base = oc.$meta<ProcedureMetadata>({});
-
 export const {{pluginNameCamel}}Contract = {
-  // List all items - requires authenticated user with read permission
-  getItems: _base
-    .meta({ userType: "user", permissions: [permissions.{{pluginNameCamel}}Read.id] })
-    .output(z.array({{pluginNamePascal}}ItemSchema)),
+  // List all items - requires authenticated user with read access
+  getItems: proc({
+    operationType: "query",
+    userType: "user",
+    access: [{{pluginNameCamel}}Access.read],
+  }).output(z.array({{pluginNamePascal}}ItemSchema)),
 
   // Get single item
-  getItem: _base
-    .meta({ userType: "user", permissions: [permissions.{{pluginNameCamel}}Read.id] })
-    .input(z.string())
+  getItem: proc({
+    operationType: "query",
+    userType: "user",
+    access: [{{pluginNameCamel}}Access.read],
+  })
+    .input(z.object({ id: z.string() }))
     .output({{pluginNamePascal}}ItemSchema),
 
   // Create item
-  createItem: _base
-    .meta({ userType: "user", permissions: [permissions.{{pluginNameCamel}}Manage.id] })
+  createItem: proc({
+    operationType: "mutation",
+    userType: "user",
+    access: [{{pluginNameCamel}}Access.manage],
+  })
     .input(Create{{pluginNamePascal}}ItemSchema)
     .output({{pluginNamePascal}}ItemSchema),
 
   // Update item
-  updateItem: _base
-    .meta({ userType: "user", permissions: [permissions.{{pluginNameCamel}}Manage.id] })
+  updateItem: proc({
+    operationType: "mutation",
+    userType: "user",
+    access: [{{pluginNameCamel}}Access.manage],
+  })
     .input(
       z.object({
         id: z.string(),
@@ -43,17 +49,21 @@ export const {{pluginNameCamel}}Contract = {
     .output({{pluginNamePascal}}ItemSchema),
 
   // Delete item
-  deleteItem: _base
-    .meta({ userType: "user", permissions: [permissions.{{pluginNameCamel}}Manage.id] })
-    .input(z.string())
+  deleteItem: proc({
+    operationType: "mutation",
+    userType: "user",
+    access: [{{pluginNameCamel}}Access.manage],
+  })
+    .input(z.object({ id: z.string() }))
     .output(z.void()),
 };
 
 // Export contract type
 export type {{pluginNamePascal}}Contract = typeof {{pluginNameCamel}}Contract;
 
-// Export client definition for type-safe forPlugin usage
-// Use: const client = rpcApi.forPlugin({{pluginNamePascal}}Api);
+// Export client definition for type-safe usePluginClient usage
+// Frontend: const client = usePluginClient({{pluginNamePascal}}Api);
+// Backend:  const client = rpcClient.forPlugin({{pluginNamePascal}}Api);
 export const {{pluginNamePascal}}Api = createClientDefinition(
   {{pluginNameCamel}}Contract,
   pluginMetadata

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

@@ -1,15 +1,9 @@
-import { createApiRef } from "@checkstack/frontend-api";
-import type { InferClient } from "@checkstack/common";
-import { {{pluginNamePascal}}Api } from "@checkstack/{{pluginBaseName}}-common";
-
-// Re-export types for convenience
+// Re-export types from common for convenience
 export type {
   {{pluginNamePascal}}Item,
   Create{{pluginNamePascal}}Item,
   Update{{pluginNamePascal}}Item,
 } from "@checkstack/{{pluginBaseName}}-common";
 
-// {{pluginNamePascal}}ApiClient is the client type inferred from the Api definition
-export type {{pluginNamePascal}}ApiClient = InferClient<typeof {{pluginNamePascal}}Api>;
-
-export const {{pluginNameCamel}}ApiRef = createApiRef<{{pluginNamePascal}}ApiClient>("{{pluginBaseName}}-api");
+// Re-export the Api definition for usePluginClient usage
+export { {{pluginNamePascal}}Api } from "@checkstack/{{pluginBaseName}}-common";

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

@@ -1,53 +1,55 @@
-import { useEffect, useState } from "react";
-import { useApi } from "@checkstack/frontend-api";
-import { {{pluginNameCamel}}ApiRef, type {{pluginNamePascal}}Item } from "../api";
-import { Button, Card } from "@checkstack/ui";
+import { usePluginClient } from "@checkstack/frontend-api";
+import { {{pluginNamePascal}}Api } from "@checkstack/{{pluginBaseName}}-common";
+import type { {{pluginNamePascal}}Item } from "../api";
+import { Button, Card, PageLayout } from "@checkstack/ui";
 import { useNavigate } from "react-router-dom";
+import { Boxes } from "lucide-react";
 
 export const {{pluginNamePascal}}ListPage = () => {
-  const api = useApi({{pluginNameCamel}}ApiRef);
+  const client = usePluginClient({{pluginNamePascal}}Api);
   const navigate = useNavigate();
-  const [items, setItems] = useState<{{pluginNamePascal}}Item[]>([]);
-  const [loading, setLoading] = useState(true);
-  const [error, setError] = useState<Error>();
 
-  useEffect(() => {
-    api
-      .getItems()
-      .then(setItems)
-      .catch(setError)
-      .finally(() => setLoading(false));
-  }, [api]);
+  // Query for items - automatic loading and error states
+  const { data: items = [], isLoading, error, refetch } = client.getItems.useQuery({});
 
-  const handleDelete = async (id: string) => {
-    try {
-      await api.deleteItem(id);
-      setItems(items.filter((item) => item.id !== id));
-    } catch (error) {
-      console.error("Failed to delete item:", error);
-    }
+  // Delete mutation with refetch on success
+  const deleteMutation = client.deleteItem.useMutation({
+    onSuccess: () => {
+      void refetch();
+    },
+  });
+
+  const handleDelete = (id: string) => {
+    deleteMutation.mutate({ id });
   };
 
-  if (loading) return <div className="p-6">Loading...</div>;
-  if (error) return <div className="p-6 text-red-500">Error: {error.message}</div>;
+  if (error) {
+    return (
+      <PageLayout title="{{pluginNamePascal}}" icon={Boxes}>
+        <div className="text-destructive">Error: {error.message}</div>
+      </PageLayout>
+    );
+  }
 
   return (
-    <div className="p-6">
-      <div className="flex justify-between items-center mb-4">
-        <h1 className="text-2xl font-bold">{{pluginNamePascal}} Items</h1>
+    <PageLayout
+      title="{{pluginNamePascal}}"
+      icon={Boxes}
+      loading={isLoading}
+      actions={
         <Button onClick={() => navigate("/{{pluginBaseName}}/new")}>
           Create Item
         </Button>
-      </div>
-
+      }
+    >
       <div className="grid gap-4">
-        {items.map((item) => (
+        {items.map((item: {{pluginNamePascal}}Item) => (
           <Card key={item.id} className="p-4">
             <div className="flex justify-between items-start">
               <div>
                 <h3 className="font-semibold">{item.name}</h3>
                 {item.description && (
-                  <p className="text-sm text-gray-600">{item.description}</p>
+                  <p className="text-sm text-muted-foreground">{item.description}</p>
                 )}
               </div>
               <div className="flex gap-2">
@@ -62,8 +64,9 @@ export const {{pluginNamePascal}}ListPage = () => {
                   variant="destructive"
                   size="sm"
                   onClick={() => handleDelete(item.id)}
+                  disabled={deleteMutation.isPending}
                 >
-                  Delete
+                  {deleteMutation.isPending ? "Deleting..." : "Delete"}
                 </Button>
               </div>
             </div>
@@ -71,11 +74,11 @@ export const {{pluginNamePascal}}ListPage = () => {
         ))}
 
         {items.length === 0 && (
-          <Card className="p-8 text-center text-gray-500">
+          <Card className="p-8 text-center text-muted-foreground">
             No items yet. Create your first item to get started.
           </Card>
         )}
       </div>
-    </div>
+    </PageLayout>
   );
 };

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

@@ -1,7 +1,6 @@
-import { createFrontendPlugin, rpcApiRef, type ApiRef } from "@checkstack/frontend-api";
-import { {{pluginNameCamel}}ApiRef, type {{pluginNamePascal}}ApiClient } from "./api";
+import { createFrontendPlugin } from "@checkstack/frontend-api";
 import { {{pluginNamePascal}}ListPage } from "./components/{{pluginNamePascal}}ListPage";
-import { {{pluginNameCamel}}Routes, {{pluginNamePascal}}Api, pluginMetadata, permissions } from "@checkstack/{{pluginBaseName}}-common";
+import { {{pluginNameCamel}}Routes, pluginMetadata, {{pluginNameCamel}}Access } from "@checkstack/{{pluginBaseName}}-common";
 
 export default createFrontendPlugin({
   metadata: pluginMetadata,
@@ -12,22 +11,9 @@ export default createFrontendPlugin({
       route: {{pluginNameCamel}}Routes.routes.home,
       element: <{{pluginNamePascal}}ListPage />,
       title: "{{pluginNamePascal}}",
-      permission: permissions.{{pluginNameCamel}}Read,
-    },
-  ],
-
-  // Register client API using oRPC
-  apis: [
-    {
-      ref: {{pluginNameCamel}}ApiRef,
-      factory: (deps: { get: <T>(ref: ApiRef<T>) => T }): {{pluginNamePascal}}ApiClient => {
-        const rpcApi = deps.get(rpcApiRef);
-        // Create type-safe client using the plugin's Api definition
-        return rpcApi.forPlugin({{pluginNamePascal}}Api);
-      },
+      accessRule: {{pluginNameCamel}}Access.read,
     },
   ],
 });
 
 export * from "./api";
-

package/src/templates/common/src/permissions.ts.hbs

@@ -1,17 +0,0 @@
-import { createPermission } from "@checkstack/common";
-
-export const permissions = {
-  {{pluginNameCamel}}Read: createPermission(
-    "{{pluginBaseName}}",
-    "read",
-    "Read {{pluginBaseName}} data",
-    { isAuthenticatedDefault: true } // Auto-assigned to "users" role
-  ),
-  {{pluginNameCamel}}Manage: createPermission(
-    "{{pluginBaseName}}",
-    "manage",
-    "Manage {{pluginBaseName}} data"
-  ),
-};
-
-export const permissionList = Object.values(permissions);