@checkstack/catalog-common 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,80 @@
 # @checkstack/catalog-common
 
+## 1.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,
+  ```
+
+### Patch Changes
+
+- Updated dependencies [9faec1f]
+- Updated dependencies [f533141]
+  - @checkstack/common@0.2.0
+  - @checkstack/frontend-api@0.1.0
+
 ## 1.0.0
 
 ### Major Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/catalog-common",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "type": "module",
   "exports": {
     ".": {

package/src/access.ts

@@ -0,0 +1,69 @@
+import { accessPair } from "@checkstack/common";
+
+/**
+ * Access rules for the Catalog plugin.
+ *
+ * Systems have instance-level access control (team-based filtering).
+ * Groups and views are global (no team-based filtering).
+ */
+export const catalogAccess = {
+  /**
+   * System access with team-based filtering.
+   * - Read: View systems (filtered by team grants if no global access)
+   * - Manage: Create, update, delete systems
+   */
+  system: accessPair(
+    "system",
+    {
+      read: "View systems in catalog",
+      manage: "Create, update, and delete systems",
+    },
+    {
+      idParam: "systemId",
+      listKey: "systems",
+      readIsDefault: true,
+      readIsPublic: true,
+    }
+  ),
+
+  /**
+   * Group access (global, no team-based filtering).
+   */
+  group: accessPair(
+    "group",
+    {
+      read: "View groups",
+      manage: "Create, update, and delete groups",
+    },
+    {
+      readIsDefault: true,
+      readIsPublic: true,
+    }
+  ),
+
+  /**
+   * View access (global, user-only).
+   */
+  view: accessPair(
+    "view",
+    {
+      read: "View saved views",
+      manage: "Manage saved views",
+    },
+    {
+      readIsDefault: true,
+    }
+  ),
+};
+
+/**
+ * All access rules for registration with the plugin system.
+ */
+export const catalogAccessRules = [
+  catalogAccess.system.read,
+  catalogAccess.system.manage,
+  catalogAccess.group.read,
+  catalogAccess.group.manage,
+  catalogAccess.view.read,
+  catalogAccess.view.manage,
+];

package/src/index.ts

@@ -1,4 +1,4 @@
-export { permissions, permissionList } from "./permissions";
+export { catalogAccess, catalogAccessRules } from "./access";
 export * from "./rpc-contract";
 export * from "./types";
 export * from "./slots";

package/src/rpc-contract.ts

@@ -1,22 +1,16 @@
 import { oc } from "@orpc/contract";
 import {
   createClientDefinition,
-  createResourceAccess,
-  createResourceAccessList,
   type ProcedureMetadata,
 } from "@checkstack/common";
 import { pluginMetadata } from "./plugin-metadata";
 import { z } from "zod";
 import { SystemSchema, GroupSchema, ViewSchema } from "./types";
-import { permissions } from "./permissions";
+import { catalogAccess } from "./access";
 
 // Base builder with full metadata support
 const _base = oc.$meta<ProcedureMetadata>({});
 
-// Resource access configurations for team-based access control
-const systemAccess = createResourceAccess("system", "systemId");
-const systemListAccess = createResourceAccessList("system", "systems");
-
 // Input schemas that match the service layer expectations
 const CreateSystemInputSchema = z.object({
   name: z.string(),
@@ -57,14 +51,13 @@ const CreateViewInputSchema = z.object({
 // Catalog RPC Contract using oRPC's contract-first pattern
 export const catalogContract = {
   // ==========================================================================
-  // ENTITY READ ENDPOINTS (userType: "public" - accessible by anyone with permission)
+  // ENTITY READ ENDPOINTS (userType: "public" - accessible by anyone with access)
   // ==========================================================================
 
   getEntities: _base
     .meta({
       userType: "public",
-      permissions: [permissions.catalogRead.id],
-      resourceAccess: [systemListAccess],
+      access: [catalogAccess.system.read],
     })
     .output(
       z.object({
@@ -76,32 +69,30 @@ export const catalogContract = {
   getSystems: _base
     .meta({
       userType: "public",
-      permissions: [permissions.catalogRead.id],
-      resourceAccess: [systemListAccess],
+      access: [catalogAccess.system.read],
     })
     .output(z.object({ systems: z.array(SystemSchema) })),
 
   getSystem: _base
     .meta({
       userType: "public",
-      permissions: [permissions.catalogRead.id],
-      resourceAccess: [systemAccess],
+      access: [catalogAccess.system.read],
     })
     .input(z.object({ systemId: z.string() }))
     .output(SystemSchema.nullable()),
 
   getGroups: _base
-    .meta({ userType: "public", permissions: [permissions.catalogRead.id] })
+    .meta({ userType: "public", access: [catalogAccess.group.read] })
     .output(z.array(GroupSchema)),
 
   // ==========================================================================
-  // SYSTEM MANAGEMENT (userType: "authenticated" with manage permission)
+  // SYSTEM MANAGEMENT (userType: "authenticated" with manage access)
   // ==========================================================================
 
   createSystem: _base
     .meta({
       userType: "authenticated",
-      permissions: [permissions.catalogManage.id],
+      access: [catalogAccess.system.manage],
     })
     .input(CreateSystemInputSchema)
     .output(SystemSchema),
@@ -109,7 +100,7 @@ export const catalogContract = {
   updateSystem: _base
     .meta({
       userType: "authenticated",
-      permissions: [permissions.catalogManage.id],
+      access: [catalogAccess.system.manage],
     })
     .input(UpdateSystemInputSchema)
     .output(SystemSchema),
@@ -117,19 +108,19 @@ export const catalogContract = {
   deleteSystem: _base
     .meta({
       userType: "authenticated",
-      permissions: [permissions.catalogManage.id],
+      access: [catalogAccess.system.manage],
     })
     .input(z.string())
     .output(z.object({ success: z.boolean() })),
 
   // ==========================================================================
-  // GROUP MANAGEMENT (userType: "authenticated" with manage permission)
+  // GROUP MANAGEMENT (userType: "authenticated" with manage access)
   // ==========================================================================
 
   createGroup: _base
     .meta({
       userType: "authenticated",
-      permissions: [permissions.catalogManage.id],
+      access: [catalogAccess.group.manage],
     })
     .input(CreateGroupInputSchema)
     .output(GroupSchema),
@@ -137,7 +128,7 @@ export const catalogContract = {
   updateGroup: _base
     .meta({
       userType: "authenticated",
-      permissions: [permissions.catalogManage.id],
+      access: [catalogAccess.group.manage],
     })
     .input(UpdateGroupInputSchema)
     .output(GroupSchema),
@@ -145,19 +136,19 @@ export const catalogContract = {
   deleteGroup: _base
     .meta({
       userType: "authenticated",
-      permissions: [permissions.catalogManage.id],
+      access: [catalogAccess.group.manage],
     })
     .input(z.string())
     .output(z.object({ success: z.boolean() })),
 
   // ==========================================================================
-  // SYSTEM-GROUP RELATIONSHIPS (userType: "authenticated" with manage permission)
+  // SYSTEM-GROUP RELATIONSHIPS (userType: "authenticated" with manage access)
   // ==========================================================================
 
   addSystemToGroup: _base
     .meta({
       userType: "authenticated",
-      permissions: [permissions.catalogManage.id],
+      access: [catalogAccess.system.manage],
     })
     .input(
       z.object({
@@ -170,7 +161,7 @@ export const catalogContract = {
   removeSystemFromGroup: _base
     .meta({
       userType: "authenticated",
-      permissions: [permissions.catalogManage.id],
+      access: [catalogAccess.system.manage],
     })
     .input(
       z.object({
@@ -185,11 +176,11 @@ export const catalogContract = {
   // ==========================================================================
 
   getViews: _base
-    .meta({ userType: "user", permissions: [permissions.catalogRead.id] })
+    .meta({ userType: "user", access: [catalogAccess.view.read] })
     .output(z.array(ViewSchema)),
 
   createView: _base
-    .meta({ userType: "user", permissions: [permissions.catalogManage.id] })
+    .meta({ userType: "user", access: [catalogAccess.view.manage] })
     .input(CreateViewInputSchema)
     .output(ViewSchema),
 

package/src/permissions.ts

@@ -1,17 +0,0 @@
-import { createPermission } from "@checkstack/common";
-
-export const permissions = {
-  catalogRead: createPermission(
-    "catalog",
-    "read",
-    "Read Catalog (Systems and Groups)",
-    { isAuthenticatedDefault: true, isPublicDefault: true }
-  ),
-  catalogManage: createPermission(
-    "catalog",
-    "manage",
-    "Full management of Catalog (Systems and Groups)"
-  ),
-};
-
-export const permissionList = Object.values(permissions);