@tailor-platform/erp-kit 0.2.1 → 0.3.0

package/src/commands/scaffold.ts

@@ -1,140 +0,0 @@
-import path from "node:path";
-import fs from "node:fs";
-import { runMdschema } from "../mdschema";
-import { ALL_SCHEMAS } from "../schemas";
-import { getModuleSrcTemplates } from "./scaffold-templates";
-
-export const MODULE_TYPES = ["module", "feature", "command", "model", "query"] as const;
-export const APP_TYPES = [
-  "requirements",
-  "actors",
-  "business-flow",
-  "story",
-  "screen",
-  "resolver",
-] as const;
-export const ALL_TYPES = [...MODULE_TYPES, ...APP_TYPES] as const;
-
-export type ScaffoldType = (typeof ALL_TYPES)[number];
-
-const MODULE_DIR_MAP: Record<string, string> = {
-  feature: "docs/features",
-  command: "docs/commands",
-  model: "docs/models",
-  query: "docs/queries",
-};
-
-const APP_DIR_MAP: Record<string, string> = {
-  actors: "docs/actors",
-  "business-flow": "docs/business-flow",
-  screen: "docs/screen",
-  resolver: "docs/resolver",
-};
-
-export function isModuleType(type: string): boolean {
-  return (MODULE_TYPES as readonly string[]).includes(type);
-}
-
-export function resolveScaffoldPath(
-  type: ScaffoldType,
-  parentName: string,
-  name: string | undefined,
-  root: string,
-): string {
-  // Types that map to README.md (no name needed)
-  if (type === "module" || type === "requirements") {
-    return path.join(root, parentName, "README.md");
-  }
-
-  if (!name) {
-    throw new Error(`Name is required for scaffold type "${type}"`);
-  }
-
-  // business-flow produces a README inside a named directory
-  if (type === "business-flow") {
-    return path.join(root, parentName, "docs/business-flow", name, "README.md");
-  }
-
-  // story accepts "flow/story-name" to place under the correct flow directory
-  if (type === "story") {
-    const parts = name.split("/");
-    if (parts.length !== 2) {
-      throw new Error(
-        `Story name must be "<flow>/<story>" (e.g., "onboarding/admin--create-user")`,
-      );
-    }
-    return path.join(root, parentName, "docs/business-flow", parts[0], "story", `${parts[1]}.md`);
-  }
-
-  // Module sub-types
-  if (MODULE_DIR_MAP[type]) {
-    return path.join(root, parentName, MODULE_DIR_MAP[type], `${name}.md`);
-  }
-
-  // App sub-types
-  if (APP_DIR_MAP[type]) {
-    return path.join(root, parentName, APP_DIR_MAP[type], `${name}.md`);
-  }
-
-  throw new Error(`Unknown scaffold type: ${type}`);
-}
-
-export async function runScaffold(
-  type: ScaffoldType,
-  parentName: string,
-  name: string | undefined,
-  root: string,
-  cwd: string,
-): Promise<number> {
-  const outputPath = resolveScaffoldPath(type, parentName, name, root);
-  const absoluteOutput = path.resolve(cwd, outputPath);
-
-  if (fs.existsSync(absoluteOutput)) {
-    console.error(`File already exists: ${outputPath}`);
-    return 1;
-  }
-
-  const schemaPath = ALL_SCHEMAS[type];
-  if (!schemaPath) {
-    console.error(`No schema found for type: ${type}`);
-    return 2;
-  }
-
-  try {
-    fs.mkdirSync(path.dirname(absoluteOutput), { recursive: true });
-  } catch (err) {
-    console.error(
-      `Failed to create directory: ${err instanceof Error ? err.message : String(err)}`,
-    );
-    return 1;
-  }
-
-  const { exitCode, stdout, stderr } = await runMdschema(
-    ["generate", "--schema", schemaPath, "--output", absoluteOutput],
-    cwd,
-  );
-
-  if (stdout.trim()) console.log(stdout);
-  if (stderr.trim()) console.error(stderr);
-
-  if (exitCode !== 0) return exitCode;
-
-  if (type === "module") {
-    scaffoldModuleSrc(path.dirname(absoluteOutput), parentName);
-  }
-
-  return exitCode;
-}
-
-export function scaffoldModuleSrc(moduleDir: string, moduleName: string): void {
-  for (const entry of getModuleSrcTemplates()) {
-    const fullPath = path.join(moduleDir, entry.path);
-    if (entry.type === "dir") {
-      fs.mkdirSync(fullPath, { recursive: true });
-      fs.writeFileSync(path.join(fullPath, ".gitkeep"), "");
-    } else {
-      fs.mkdirSync(path.dirname(fullPath), { recursive: true });
-      fs.writeFileSync(fullPath, entry.content(moduleName));
-    }
-  }
-}

package/src/modules/shared/index.ts

@@ -1 +0,0 @@
-export { createContext } from "./createContext";

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

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

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

@@ -1,187 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { type CommandContext } from "../../shared/internal";
-import { createMockDb } from "../../testing/index";
-import { DB } from "../generated/kysely-tailordb";
-import { InvalidEventTypeError, MissingRequiredFieldError } from "../lib/errors.generated";
-import { baseAuditEvent } from "../testing/fixtures";
-import { run } from "./logAuditEvent";
-
-describe("logAuditEvent", () => {
-  const ctx: CommandContext = {
-    actorId: "test-actor",
-    permissions: ["user-management:logAuditEvent"],
-  };
-
-  it("throws when actorId is empty", async () => {
-    const { db } = createMockDb<DB>();
-
-    const result = await run(
-      db,
-      {
-        eventType: "USER_CREATED",
-        actorId: "",
-      },
-      ctx,
-    );
-    expect(result.ok).toBe(false);
-    if (!result.ok) {
-      expect(result.error).toBeInstanceOf(MissingRequiredFieldError);
-    }
-  });
-
-  it("throws when eventType is invalid", async () => {
-    const { db } = createMockDb<DB>();
-
-    const result = await run(
-      db,
-      {
-        eventType: "INVALID_EVENT" as "USER_CREATED",
-        actorId: "user-1",
-      },
-      ctx,
-    );
-    expect(result.ok).toBe(false);
-    if (!result.ok) {
-      expect(result.error).toBeInstanceOf(InvalidEventTypeError);
-    }
-  });
-
-  it("creates audit event with minimal fields", async () => {
-    const { db, spies } = createMockDb<DB>();
-    const createdEvent = {
-      ...baseAuditEvent,
-      id: "new-event-id",
-      eventType: "USER_CREATED" as const,
-      actorId: "user-1",
-      targetId: null,
-      targetType: null,
-      payload: null,
-    };
-
-    spies.insert.mockReturnValue(createdEvent);
-
-    const result = await run(
-      db,
-      {
-        eventType: "USER_CREATED",
-        actorId: "user-1",
-      },
-      ctx,
-    );
-
-    expect(result.ok).toBe(true);
-    if (result.ok) {
-      expect(result.value.auditEvent.eventType).toBe("USER_CREATED");
-      expect(result.value.auditEvent.actorId).toBe("user-1");
-    }
-    expect(spies.insert).toHaveBeenCalled();
-  });
-
-  it("creates audit event with target info", async () => {
-    const { db, spies } = createMockDb<DB>();
-    const createdEvent = {
-      ...baseAuditEvent,
-      id: "new-event-id",
-      eventType: "ROLE_ASSIGNED" as const,
-      actorId: "user-1",
-      targetId: "user-2",
-      targetType: "User",
-      payload: null,
-    };
-
-    spies.insert.mockReturnValue(createdEvent);
-
-    const result = await run(
-      db,
-      {
-        eventType: "ROLE_ASSIGNED",
-        actorId: "user-1",
-        targetId: "user-2",
-        targetType: "User",
-      },
-      ctx,
-    );
-
-    expect(result.ok).toBe(true);
-    if (result.ok) {
-      expect(result.value.auditEvent.eventType).toBe("ROLE_ASSIGNED");
-      expect(result.value.auditEvent.targetId).toBe("user-2");
-      expect(result.value.auditEvent.targetType).toBe("User");
-    }
-  });
-
-  it("creates audit event with payload", async () => {
-    const { db, spies } = createMockDb<DB>();
-    const payload = JSON.stringify({ roleId: "role-1", userId: "user-2" });
-    const createdEvent = {
-      ...baseAuditEvent,
-      id: "new-event-id",
-      eventType: "ROLE_ASSIGNED" as const,
-      actorId: "user-1",
-      targetId: "user-2",
-      targetType: "User",
-      payload,
-    };
-
-    spies.insert.mockReturnValue(createdEvent);
-
-    const result = await run(
-      db,
-      {
-        eventType: "ROLE_ASSIGNED",
-        actorId: "user-1",
-        targetId: "user-2",
-        targetType: "User",
-        payload,
-      },
-      ctx,
-    );
-
-    expect(result.ok).toBe(true);
-    if (result.ok) {
-      expect(result.value.auditEvent.payload).toBe(payload);
-    }
-  });
-
-  it("creates audit event for each valid event type", async () => {
-    const eventTypes = [
-      "USER_CREATED",
-      "USER_ACTIVATED",
-      "USER_DEACTIVATED",
-      "USER_REACTIVATED",
-      "ROLE_ASSIGNED",
-      "ROLE_REVOKED",
-      "PERMISSION_ASSIGNED",
-      "PERMISSION_REVOKED",
-    ] as const;
-
-    for (const eventType of eventTypes) {
-      const { db, spies } = createMockDb<DB>();
-      const createdEvent = {
-        ...baseAuditEvent,
-        id: "new-event-id",
-        eventType,
-        actorId: "user-1",
-        targetId: null,
-        targetType: null,
-        payload: null,
-      };
-
-      spies.insert.mockReturnValue(createdEvent);
-
-      const result = await run(
-        db,
-        {
-          eventType,
-          actorId: "user-1",
-        },
-        ctx,
-      );
-
-      expect(result.ok).toBe(true);
-      if (result.ok) {
-        expect(result.value.auditEvent.eventType).toBe(eventType);
-      }
-    }
-  });
-});

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

@@ -1,56 +0,0 @@
-import { ok, err, type CommandContext } from "../../shared/internal";
-import { DB } from "../generated/kysely-tailordb";
-import { AuditEventEventType } from "../generated/enums";
-import { InvalidEventTypeError, MissingRequiredFieldError } from "../lib/errors.generated";
-
-export interface LogAuditEventInput {
-  eventType: AuditEventEventType;
-  actorId: string;
-  targetId?: string;
-  targetType?: string;
-  payload?: string;
-}
-
-const VALID_EVENT_TYPES = new Set<string>([
-  "USER_CREATED",
-  "USER_ACTIVATED",
-  "USER_DEACTIVATED",
-  "USER_REACTIVATED",
-  "ROLE_ASSIGNED",
-  "ROLE_REVOKED",
-  "PERMISSION_ASSIGNED",
-  "PERMISSION_REVOKED",
-]);
-
-/**
- * Function: logAuditEvent
- *
- * Creates an immutable audit record of a security-relevant event.
- * Records are created with timestamp and cannot be modified or deleted.
- */
-// eslint-disable-next-line @typescript-eslint/no-unused-vars
-export async function run(db: DB, input: LogAuditEventInput, _ctx: CommandContext) {
-  if (!input.actorId || input.actorId.trim() === "") {
-    return err(new MissingRequiredFieldError("actorId"));
-  }
-
-  if (!VALID_EVENT_TYPES.has(input.eventType)) {
-    return err(new InvalidEventTypeError(input.eventType));
-  }
-
-  const auditEvent = await db
-    .insertInto("AuditEvent")
-    .values({
-      eventType: input.eventType,
-      actorId: input.actorId,
-      targetId: input.targetId ?? null,
-      targetType: input.targetType ?? null,
-      payload: input.payload ?? null,
-      createdAt: new Date(),
-      updatedAt: null,
-    })
-    .returningAll()
-    .executeTakeFirst();
-
-  return ok({ auditEvent: auditEvent! });
-}

package/src/modules/user-management/db/auditEvent.ts

@@ -1,47 +0,0 @@
-import {
-  db,
-  unsafeAllowAllGqlPermission,
-  unsafeAllowAllTypePermission,
-} from "@tailor-platform/sdk";
-
-export interface CreateAuditEventTypeParams {
-  fields?: Record<string, unknown>;
-  additionalEventTypes?: string[];
-}
-
-const BASE_EVENT_TYPES = [
-  "USER_CREATED",
-  "USER_ACTIVATED",
-  "USER_DEACTIVATED",
-  "USER_REACTIVATED",
-  "ROLE_ASSIGNED",
-  "ROLE_REVOKED",
-  "PERMISSION_ASSIGNED",
-  "PERMISSION_REVOKED",
-] as const;
-
-export function createAuditEventType(params: CreateAuditEventTypeParams) {
-  const eventTypes = [...BASE_EVENT_TYPES, ...(params.additionalEventTypes ?? [])] as [
-    string,
-    ...string[],
-  ];
-
-  return db
-    .type("AuditEvent", {
-      eventType: db.enum(eventTypes).description("Type of audit event"),
-      actorId: db.uuid().description("ID of the user who performed the action"),
-      targetId: db.uuid({ optional: true }).description("ID of the affected entity"),
-      targetType: db
-        .string({ optional: true })
-        .description("Type of the affected entity (User, Role, Permission)"),
-      payload: db
-        .string({ optional: true })
-        .description("JSON payload with additional event details"),
-      ...params.fields,
-      ...db.fields.timestamps(),
-    })
-    .permission(unsafeAllowAllTypePermission)
-    .gqlPermission(unsafeAllowAllGqlPermission);
-}
-
-export const auditEvent = createAuditEventType({});

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

@@ -1,37 +0,0 @@
-# LogAuditEvent
-
-## Overview
-
-LogAuditEvent creates an immutable record of a security-relevant event in the User Management module. This command captures the actor identity, timestamp, event type, and event details for compliance and security purposes.
-
-Typically, this command is triggered internally as a side effect of other commands (createUser, activateUser, assignRoleToUser, etc.) rather than being called directly.
-
-## Business Rules
-
-- Event type must be a valid event type (USER_CREATED, USER_ACTIVATED, USER_DEACTIVATED, USER_REACTIVATED, ROLE_ASSIGNED, ROLE_REVOKED, PERMISSION_ASSIGNED, PERMISSION_REVOKED)
-- Actor ID is required (identifies who performed the action)
-- Timestamp is auto-generated at creation
-- Event payload contains relevant details specific to the event type
-- Record is immutable once created (no updates or deletes allowed)
-
-## Process Flow
-
-```mermaid
-flowchart TD
-    A[Receive log request] --> B{Valid event type?}
-    B -->|No| C[Return error: INVALID_EVENT_TYPE]
-    B -->|Yes| D{Actor ID provided?}
-    D -->|No| E[Return error: MISSING_REQUIRED_FIELD]
-    D -->|Yes| F[Generate timestamp]
-    F --> G[Create AuditEvent record]
-    G --> H[Return created event]
-```
-
-## External Dependencies
-
-- None
-
-## Error Scenarios
-
-- **INVALID_EVENT_TYPE**: Event type is not one of the recognized types - return validation error with list of valid event types
-- **MISSING_REQUIRED_FIELD**: Actor ID not provided - return validation error indicating actor ID is required

package/src/modules/user-management/docs/features/audit-trail.md

@@ -1,80 +0,0 @@
-# Audit Trail
-
-## Overview
-
-The Audit Trail captures immutable records of all security-relevant events in the User Management module. Every user lifecycle change, role assignment, and permission modification is logged with the actor identity, timestamp, and event details. These records cannot be modified or deleted, ensuring a trustworthy history for compliance and security investigations.
-
-This feature provides the foundation for regulatory compliance and security forensics across the ERP system.
-
-## Business Purpose
-
-Organizations require audit trails for multiple reasons:
-
-- **Regulatory Compliance**: SOX, GDPR, HIPAA, and other regulations mandate tracking of access and authorization changes
-- **Security Investigations**: When incidents occur, audit logs reveal who did what and when
-- **Access Reviews**: Periodic reviews of who has access to what rely on historical assignment data
-- **Accountability**: Users knowing their actions are logged encourages responsible behavior
-- **Change Tracking**: Understanding how access evolved over time supports troubleshooting and planning
-
-## Process Flow
-
-```mermaid
-flowchart TD
-    A[Security Event Occurs] --> B[Capture Event Details]
-    B --> C[Record Actor Identity]
-    C --> D[Record Timestamp]
-    D --> E[Record Event Type]
-    E --> F[Record Event Payload]
-    F --> G[Store Immutable Record]
-    G --> H[Available for Query]
-
-    subgraph Event Types
-    I[USER_CREATED]
-    J[USER_ACTIVATED]
-    K[USER_DEACTIVATED]
-    L[USER_REACTIVATED]
-    M[ROLE_ASSIGNED]
-    N[ROLE_REVOKED]
-    O[PERMISSION_ASSIGNED]
-    P[PERMISSION_REVOKED]
-    end
-
-    subgraph Immutability
-    G --> Q[No UPDATE Allowed]
-    G --> R[No DELETE Allowed]
-    end
-```
-
-## Scenario Patterns
-
-- **User Creation Audit**: When admin creates new user, system logs USER_CREATED event with admin ID, new user details, and timestamp. Provides accountability for onboarding.
-- **Status Transition Audit**: User activation logs USER_ACTIVATED with old status (PENDING) and new status (ACTIVE). Complete state change history maintained.
-- **Role Assignment Audit**: Assigning "Sales Manager" role to user logs ROLE_ASSIGNED with assigner ID, user ID, role ID, and timestamp. Tracks who granted elevated access.
-- **Permission Change Audit**: Adding permission to role logs PERMISSION_ASSIGNED. Even though permission affects many users through the role, the change itself is tracked.
-- **Compliance Query**: Auditor requests all access changes for specific user over past year. System returns chronological list of all role assignments and revocations.
-- **Incident Investigation**: Security team investigates unauthorized data access. Audit trail reveals user's roles at time of access and who assigned those roles.
-- **Bulk Operations**: Even bulk operations (e.g., deactivating multiple users) generate individual audit entries for each user affected.
-
-## Test Cases
-
-- Creating a user should generate USER_CREATED audit entry
-- Activating a user should generate USER_ACTIVATED entry with previous status
-- Deactivating a user should generate USER_DEACTIVATED entry with previous status
-- Reactivating a user should generate USER_REACTIVATED entry with previous status
-- Assigning role to user should generate ROLE_ASSIGNED entry
-- Revoking role from user should generate ROLE_REVOKED entry
-- Assigning permission to role should generate PERMISSION_ASSIGNED entry
-- Revoking permission from role should generate PERMISSION_REVOKED entry
-- Audit entries should include actor ID (who performed the action)
-- Audit entries should include timestamp (when action occurred)
-- Audit entries should be immutable (no update operation allowed)
-- Audit entries should be immutable (no delete operation allowed)
-- Querying audit by user ID should return all entries related to that user
-- Querying audit by date range should return entries within range
-- Querying audit by event type should filter appropriately
-
-## Reference Links
-
-- [OWASP Logging Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Logging_Cheat_Sheet.html)
-- [NIST Audit and Accountability](https://csrc.nist.gov/publications/detail/sp/800-53/rev-5/final)
-- [SOX Compliance Requirements](https://www.soxlaw.com/)

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

@@ -1,36 +0,0 @@
-# AuditEvent
-
-## Description
-
-AuditEvent captures immutable records of all security-relevant events in the User Management module. Every user lifecycle change, role assignment, and permission modification is logged with the actor identity, timestamp, and event details. These records cannot be modified or deleted, ensuring a trustworthy history for compliance and security investigations.
-
-Event types include: USER_CREATED, USER_ACTIVATED, USER_DEACTIVATED, USER_REACTIVATED, ROLE_ASSIGNED, ROLE_REVOKED, PERMISSION_ASSIGNED, PERMISSION_REVOKED.
-
-## Domain Model Definitions
-
-### Model type
-
-AppendOnly
-
-### Command Definitions
-
-- [logAuditEvent](../commands/LogAuditEvent.md)
-
-### Query Definitions
-
-### Models
-
-- AuditEvent
-
-### Invariants
-
-- Event type must be a valid event type (USER_CREATED, USER_ACTIVATED, USER_DEACTIVATED, USER_REACTIVATED, ROLE_ASSIGNED, ROLE_REVOKED, PERMISSION_ASSIGNED, PERMISSION_REVOKED)
-- Actor ID is required (identifies who performed the action)
-- Timestamp is required (auto-generated at creation)
-- Records cannot be updated after creation
-- Records cannot be deleted
-
-### Relationships
-
-- **References User as Actor**: Each event records which user performed the action
-- **References Target Entity**: Each event references the affected entity (user, role, or permission depending on event type)