@tailor-platform/erp-kit 0.1.1 → 0.2.0

package/src/modules/user-management/command/revokePermissionFromRole.test.ts

@@ -1,10 +1,14 @@
 import { describe, expect, it } from "vitest";
-import { InsufficientPermissionError, type CommandContext } from "../../shared/internal";
+import { type CommandContext } from "../../shared/internal";
 import { createMockDb } from "../../testing/index";
 import { DB } from "../generated/kysely-tailordb";
-import { AssignmentNotFoundError, PermissionNotFoundError, RoleNotFoundError } from "../lib/errors";
+import {
+  AssignmentNotFoundError,
+  PermissionNotFoundError,
+  RoleNotFoundError,
+} from "../lib/errors.generated";
 import { baseAuditEvent, basePermission, baseRole, baseRolePermission } from "../testing/fixtures";
-import { revokePermissionFromRole } from "./revokePermissionFromRole";
+import { run } from "./revokePermissionFromRole";
 
 describe("revokePermissionFromRole", () => {
   const ctx: CommandContext = {
@@ -16,34 +20,38 @@ describe("revokePermissionFromRole", () => {
     const { db, spies } = createMockDb<DB>();
     spies.select.mockReturnValue(undefined);
 
-    await expect(
-      revokePermissionFromRole(
-        db,
-        {
-          roleId: "nonexistent-role",
-          permissionId: basePermission.id,
-          actorId: "actor-1",
-        },
-        ctx,
-      ),
-    ).rejects.toBeInstanceOf(RoleNotFoundError);
+    const result = await run(
+      db,
+      {
+        roleId: "nonexistent-role",
+        permissionId: basePermission.id,
+        actorId: "actor-1",
+      },
+      ctx,
+    );
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(RoleNotFoundError);
+    }
   });
 
   it("throws when permission does not exist", async () => {
     const { db, spies } = createMockDb<DB>();
     spies.select.mockReturnValueOnce(baseRole).mockReturnValueOnce(undefined);
 
-    await expect(
-      revokePermissionFromRole(
-        db,
-        {
-          roleId: baseRole.id,
-          permissionId: "nonexistent-permission",
-          actorId: "actor-1",
-        },
-        ctx,
-      ),
-    ).rejects.toBeInstanceOf(PermissionNotFoundError);
+    const result = await run(
+      db,
+      {
+        roleId: baseRole.id,
+        permissionId: "nonexistent-permission",
+        actorId: "actor-1",
+      },
+      ctx,
+    );
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(PermissionNotFoundError);
+    }
   });
 
   it("throws when assignment does not exist", async () => {
@@ -53,17 +61,19 @@ describe("revokePermissionFromRole", () => {
       .mockReturnValueOnce(basePermission)
       .mockReturnValueOnce(undefined);
 
-    await expect(
-      revokePermissionFromRole(
-        db,
-        {
-          roleId: baseRole.id,
-          permissionId: basePermission.id,
-          actorId: "actor-1",
-        },
-        ctx,
-      ),
-    ).rejects.toBeInstanceOf(AssignmentNotFoundError);
+    const result = await run(
+      db,
+      {
+        roleId: baseRole.id,
+        permissionId: basePermission.id,
+        actorId: "actor-1",
+      },
+      ctx,
+    );
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(AssignmentNotFoundError);
+    }
   });
 
   it("deletes RolePermission and logs PERMISSION_REVOKED event", async () => {
@@ -83,7 +93,7 @@ describe("revokePermissionFromRole", () => {
     spies.delete.mockReturnValue(baseRolePermission);
     spies.insert.mockReturnValue(createdAuditEvent);
 
-    const result = await revokePermissionFromRole(
+    const result = await run(
       db,
       {
         roleId: baseRole.id,
@@ -93,20 +103,11 @@ describe("revokePermissionFromRole", () => {
       ctx,
     );
 
-    expect(result.auditEvent.eventType).toBe("PERMISSION_REVOKED");
-    expect(result.auditEvent.targetId).toBe(baseRole.id);
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.auditEvent.eventType).toBe("PERMISSION_REVOKED");
+      expect(result.value.auditEvent.targetId).toBe(baseRole.id);
+    }
     expect(spies.delete).toHaveBeenCalled();
   });
-
-  it("throws when permission is missing", async () => {
-    const { db } = createMockDb<DB>();
-    const denied: CommandContext = { actorId: "test-actor", permissions: [] };
-    await expect(
-      revokePermissionFromRole(
-        db,
-        { roleId: "role-1", permissionId: "perm-1", actorId: "actor-1" },
-        denied,
-      ),
-    ).rejects.toBeInstanceOf(InsufficientPermissionError);
-  });
 });

package/src/modules/user-management/command/revokePermissionFromRole.ts

@@ -1,7 +1,10 @@
-import { defineCommand } from "../../shared/internal";
+import { ok, err, type CommandContext } from "../../shared/internal";
 import { DB } from "../generated/kysely-tailordb";
-import { AssignmentNotFoundError, PermissionNotFoundError, RoleNotFoundError } from "../lib/errors";
-import { permissions } from "../permissions";
+import {
+  AssignmentNotFoundError,
+  PermissionNotFoundError,
+  RoleNotFoundError,
+} from "../lib/errors.generated";
 
 export interface RevokePermissionFromRoleInput {
   roleId: string;
@@ -17,65 +20,65 @@ export interface RevokePermissionFromRoleInput {
  *
  * Note: Permissions for affected users are recomputed asynchronously via executor.
  */
-export const revokePermissionFromRole = defineCommand(
-  permissions.revokePermissionFromRole,
-  async (db: DB, input: RevokePermissionFromRoleInput) => {
-    const role = await db
-      .selectFrom("Role")
-      .selectAll()
-      .where("id", "=", input.roleId)
-      .executeTakeFirst();
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+export async function run(db: DB, input: RevokePermissionFromRoleInput, _ctx: CommandContext) {
+  const role = await db
+    .selectFrom("Role")
+    .selectAll()
+    .where("id", "=", input.roleId)
+    .executeTakeFirst();
 
-    if (!role) {
-      throw new RoleNotFoundError(input.roleId);
-    }
+  if (!role) {
+    return err(new RoleNotFoundError(input.roleId));
+  }
 
-    const permission = await db
-      .selectFrom("Permission")
-      .selectAll()
-      .where("id", "=", input.permissionId)
-      .executeTakeFirst();
+  const permission = await db
+    .selectFrom("Permission")
+    .selectAll()
+    .where("id", "=", input.permissionId)
+    .executeTakeFirst();
 
-    if (!permission) {
-      throw new PermissionNotFoundError(input.permissionId);
-    }
+  if (!permission) {
+    return err(new PermissionNotFoundError(input.permissionId));
+  }
 
-    const existingAssignment = await db
-      .selectFrom("RolePermission")
-      .selectAll()
-      .where("roleId", "=", input.roleId)
-      .where("permissionId", "=", input.permissionId)
-      .executeTakeFirst();
+  const existingAssignment = await db
+    .selectFrom("RolePermission")
+    .selectAll()
+    .where("roleId", "=", input.roleId)
+    .where("permissionId", "=", input.permissionId)
+    .executeTakeFirst();
 
-    if (!existingAssignment) {
-      throw new AssignmentNotFoundError("Role", input.roleId, "Permission", input.permissionId);
-    }
+  if (!existingAssignment) {
+    return err(
+      new AssignmentNotFoundError(`Role ${input.roleId} -> Permission ${input.permissionId}`),
+    );
+  }
 
-    // Permission recomputation for affected users is handled asynchronously by executor
-    await db
-      .deleteFrom("RolePermission")
-      .where("id", "=", existingAssignment.id)
-      .returningAll()
-      .executeTakeFirst();
+  // Permission recomputation for affected users is handled asynchronously by executor
+  await db
+    .deleteFrom("RolePermission")
+    .where("id", "=", existingAssignment.id)
+    .returningAll()
+    .executeTakeFirst();
 
-    const auditEvent = await db
-      .insertInto("AuditEvent")
-      .values({
-        eventType: "PERMISSION_REVOKED",
-        actorId: input.actorId,
-        targetId: input.roleId,
-        targetType: "Role",
-        payload: JSON.stringify({
-          roleId: input.roleId,
-          permissionId: input.permissionId,
-          permissionKey: permission.key,
-        }),
-        createdAt: new Date(),
-        updatedAt: null,
-      })
-      .returningAll()
-      .executeTakeFirst();
+  const auditEvent = await db
+    .insertInto("AuditEvent")
+    .values({
+      eventType: "PERMISSION_REVOKED",
+      actorId: input.actorId,
+      targetId: input.roleId,
+      targetType: "Role",
+      payload: JSON.stringify({
+        roleId: input.roleId,
+        permissionId: input.permissionId,
+        permissionKey: permission.key,
+      }),
+      createdAt: new Date(),
+      updatedAt: null,
+    })
+    .returningAll()
+    .executeTakeFirst();
 
-    return { auditEvent: auditEvent! };
-  },
-);
+  return ok({ auditEvent: auditEvent! });
+}

package/src/modules/user-management/command/revokeRoleFromUser.generated.ts

@@ -0,0 +1,6 @@
+// @generated — do not edit
+import { defineCommand } from "../../shared/internal";
+import { permissions } from "../lib/permissions.generated";
+import { run } from "./revokeRoleFromUser";
+
+export const revokeRoleFromUser = defineCommand(permissions.revokeRoleFromUser, run);

package/src/modules/user-management/command/revokeRoleFromUser.test.ts

@@ -1,10 +1,14 @@
 import { describe, expect, it } from "vitest";
-import { InsufficientPermissionError, type CommandContext } from "../../shared/internal";
+import { type CommandContext } from "../../shared/internal";
 import { createMockDb } from "../../testing/index";
 import { DB } from "../generated/kysely-tailordb";
-import { AssignmentNotFoundError, RoleNotFoundError, UserNotFoundError } from "../lib/errors";
+import {
+  AssignmentNotFoundError,
+  RoleNotFoundError,
+  UserNotFoundError,
+} from "../lib/errors.generated";
 import { activeUser, baseAuditEvent, baseRole, baseUserRole } from "../testing/fixtures";
-import { revokeRoleFromUser } from "./revokeRoleFromUser";
+import { run } from "./revokeRoleFromUser";
 
 describe("revokeRoleFromUser", () => {
   const ctx: CommandContext = {
@@ -16,34 +20,38 @@ describe("revokeRoleFromUser", () => {
     const { db, spies } = createMockDb<DB>();
     spies.select.mockReturnValue(undefined);
 
-    await expect(
-      revokeRoleFromUser(
-        db,
-        {
-          userId: "nonexistent-user",
-          roleId: baseRole.id,
-          actorId: "actor-1",
-        },
-        ctx,
-      ),
-    ).rejects.toBeInstanceOf(UserNotFoundError);
+    const result = await run(
+      db,
+      {
+        userId: "nonexistent-user",
+        roleId: baseRole.id,
+        actorId: "actor-1",
+      },
+      ctx,
+    );
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(UserNotFoundError);
+    }
   });
 
   it("throws when role does not exist", async () => {
     const { db, spies } = createMockDb<DB>();
     spies.select.mockReturnValueOnce(activeUser).mockReturnValueOnce(undefined);
 
-    await expect(
-      revokeRoleFromUser(
-        db,
-        {
-          userId: activeUser.id,
-          roleId: "nonexistent-role",
-          actorId: "actor-1",
-        },
-        ctx,
-      ),
-    ).rejects.toBeInstanceOf(RoleNotFoundError);
+    const result = await run(
+      db,
+      {
+        userId: activeUser.id,
+        roleId: "nonexistent-role",
+        actorId: "actor-1",
+      },
+      ctx,
+    );
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(RoleNotFoundError);
+    }
   });
 
   it("throws when assignment does not exist", async () => {
@@ -53,17 +61,19 @@ describe("revokeRoleFromUser", () => {
       .mockReturnValueOnce(baseRole)
       .mockReturnValueOnce(undefined);
 
-    await expect(
-      revokeRoleFromUser(
-        db,
-        {
-          userId: activeUser.id,
-          roleId: baseRole.id,
-          actorId: "actor-1",
-        },
-        ctx,
-      ),
-    ).rejects.toBeInstanceOf(AssignmentNotFoundError);
+    const result = await run(
+      db,
+      {
+        userId: activeUser.id,
+        roleId: baseRole.id,
+        actorId: "actor-1",
+      },
+      ctx,
+    );
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(AssignmentNotFoundError);
+    }
   });
 
   it("deletes UserRole and logs ROLE_REVOKED event", async () => {
@@ -86,7 +96,7 @@ describe("revokeRoleFromUser", () => {
     spies.insert.mockReturnValue(createdAuditEvent);
     spies.update.mockReturnValue(updatedUser);
 
-    const result = await revokeRoleFromUser(
+    const result = await run(
       db,
       {
         userId: activeUser.id,
@@ -96,17 +106,12 @@ describe("revokeRoleFromUser", () => {
       ctx,
     );
 
-    expect(result.auditEvent.eventType).toBe("ROLE_REVOKED");
-    expect(result.auditEvent.targetId).toBe(activeUser.id);
-    expect(result.user.permissions).toEqual([]);
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.auditEvent.eventType).toBe("ROLE_REVOKED");
+      expect(result.value.auditEvent.targetId).toBe(activeUser.id);
+      expect(result.value.user.permissions).toEqual([]);
+    }
     expect(spies.delete).toHaveBeenCalled();
   });
-
-  it("throws when permission is missing", async () => {
-    const { db } = createMockDb<DB>();
-    const denied: CommandContext = { actorId: "test-actor", permissions: [] };
-    await expect(
-      revokeRoleFromUser(db, { userId: "user-1", roleId: "role-1", actorId: "actor-1" }, denied),
-    ).rejects.toBeInstanceOf(InsufficientPermissionError);
-  });
 });

package/src/modules/user-management/command/revokeRoleFromUser.ts

@@ -1,8 +1,11 @@
-import { defineCommand } from "../../shared/internal";
+import { ok, err, type CommandContext } from "../../shared/internal";
 import { DB } from "../generated/kysely-tailordb";
-import { AssignmentNotFoundError, RoleNotFoundError, UserNotFoundError } from "../lib/errors";
+import {
+  AssignmentNotFoundError,
+  RoleNotFoundError,
+  UserNotFoundError,
+} from "../lib/errors.generated";
 import { recomputeUserPermissions } from "../lib/recomputeUserPermissions";
-import { permissions } from "../permissions";
 
 export interface RevokeRoleFromUserInput {
   userId: string;
@@ -16,66 +19,64 @@ export interface RevokeRoleFromUserInput {
  * Removes a role from a user.
  * Throws an error if the assignment does not exist.
  */
-export const revokeRoleFromUser = defineCommand(
-  permissions.revokeRoleFromUser,
-  async (db: DB, input: RevokeRoleFromUserInput) => {
-    const user = await db
-      .selectFrom("User")
-      .selectAll()
-      .where("id", "=", input.userId)
-      .executeTakeFirst();
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+export async function run(db: DB, input: RevokeRoleFromUserInput, _ctx: CommandContext) {
+  const user = await db
+    .selectFrom("User")
+    .selectAll()
+    .where("id", "=", input.userId)
+    .executeTakeFirst();
 
-    if (!user) {
-      throw new UserNotFoundError(input.userId);
-    }
+  if (!user) {
+    return err(new UserNotFoundError(input.userId));
+  }
 
-    const role = await db
-      .selectFrom("Role")
-      .selectAll()
-      .where("id", "=", input.roleId)
-      .executeTakeFirst();
+  const role = await db
+    .selectFrom("Role")
+    .selectAll()
+    .where("id", "=", input.roleId)
+    .executeTakeFirst();
 
-    if (!role) {
-      throw new RoleNotFoundError(input.roleId);
-    }
+  if (!role) {
+    return err(new RoleNotFoundError(input.roleId));
+  }
 
-    const existingAssignment = await db
-      .selectFrom("UserRole")
-      .selectAll()
-      .where("userId", "=", input.userId)
-      .where("roleId", "=", input.roleId)
-      .executeTakeFirst();
+  const existingAssignment = await db
+    .selectFrom("UserRole")
+    .selectAll()
+    .where("userId", "=", input.userId)
+    .where("roleId", "=", input.roleId)
+    .executeTakeFirst();
 
-    if (!existingAssignment) {
-      throw new AssignmentNotFoundError("User", input.userId, "Role", input.roleId);
-    }
+  if (!existingAssignment) {
+    return err(new AssignmentNotFoundError(`User ${input.userId} -> Role ${input.roleId}`));
+  }
 
-    await db
-      .deleteFrom("UserRole")
-      .where("id", "=", existingAssignment.id)
-      .returningAll()
-      .executeTakeFirst();
+  await db
+    .deleteFrom("UserRole")
+    .where("id", "=", existingAssignment.id)
+    .returningAll()
+    .executeTakeFirst();
 
-    const auditEvent = await db
-      .insertInto("AuditEvent")
-      .values({
-        eventType: "ROLE_REVOKED",
-        actorId: input.actorId,
-        targetId: input.userId,
-        targetType: "User",
-        payload: JSON.stringify({
-          userId: input.userId,
-          roleId: input.roleId,
-          roleName: role.name,
-        }),
-        createdAt: new Date(),
-        updatedAt: null,
-      })
-      .returningAll()
-      .executeTakeFirst();
+  const auditEvent = await db
+    .insertInto("AuditEvent")
+    .values({
+      eventType: "ROLE_REVOKED",
+      actorId: input.actorId,
+      targetId: input.userId,
+      targetType: "User",
+      payload: JSON.stringify({
+        userId: input.userId,
+        roleId: input.roleId,
+        roleName: role.name,
+      }),
+      createdAt: new Date(),
+      updatedAt: null,
+    })
+    .returningAll()
+    .executeTakeFirst();
 
-    const updatedUser = await recomputeUserPermissions(db, input.userId);
+  const updatedUser = await recomputeUserPermissions(db, input.userId);
 
-    return { user: updatedUser, auditEvent: auditEvent! };
-  },
-);
+  return ok({ user: updatedUser, auditEvent: auditEvent! });
+}

package/src/modules/user-management/docs/commands/CreatePermission.md

@@ -31,5 +31,5 @@ flowchart TD
 
 ## Error Scenarios
 
-- **INVALID_KEY_FORMAT**: Key does not match `resource:action` pattern - return validation error with format requirements
-- **PERMISSION_ALREADY_EXISTS**: Permission with the same key already exists - return conflict error with existing permission reference
+- **INVALID_PERMISSION_KEY_FORMAT**: Key does not match `resource:action` pattern
+- **DUPLICATE_PERMISSION_KEY**: Permission with the same key already exists

package/src/modules/user-management/docs/commands/CreateRole.md

@@ -32,4 +32,4 @@ flowchart TD
 ## Error Scenarios
 
 - **MISSING_REQUIRED_FIELD**: Role name not provided - return validation error indicating name is required
-- **ROLE_ALREADY_EXISTS**: Role with the same name already exists - return conflict error with existing role reference
+- **DUPLICATE_ROLE_NAME**: Role with the same name already exists

package/src/modules/user-management/docs/models/AuditEvent.md

@@ -16,6 +16,8 @@ AppendOnly
 
 - [logAuditEvent](../commands/LogAuditEvent.md)
 
+### Query Definitions
+
 ### Models
 
 - AuditEvent

package/src/modules/user-management/docs/models/Permission.md

@@ -16,6 +16,8 @@ Standard
 
 - [createPermission](../commands/CreatePermission.md)
 
+### Query Definitions
+
 ### Models
 
 - Permission

package/src/modules/user-management/docs/models/Role.md

@@ -16,6 +16,8 @@ Standard
 
 - [createRole](../commands/CreateRole.md)
 
+### Query Definitions
+
 ### Models
 
 - Role

package/src/modules/user-management/docs/models/RolePermission.md

@@ -17,6 +17,8 @@ Standard
 - [assignPermissionToRole](../commands/AssignPermissionToRole.md)
 - [revokePermissionFromRole](../commands/RevokePermissionFromRole.md)
 
+### Query Definitions
+
 ### Models
 
 - RolePermission

package/src/modules/user-management/docs/models/User.md

@@ -29,6 +29,8 @@ stateDiagram-v2
 - [deactivateUser](../commands/DeactivateUser.md)
 - [reactivateUser](../commands/ReactivateUser.md)
 
+### Query Definitions
+
 ### Models
 
 - User

package/src/modules/user-management/docs/models/UserRole.md

@@ -17,6 +17,8 @@ Standard
 - [assignRoleToUser](../commands/AssignRoleToUser.md)
 - [revokeRoleFromUser](../commands/RevokeRoleFromUser.md)
 
+### Query Definitions
+
 ### Models
 
 - UserRole