@tailor-platform/erp-kit 0.1.1 → 0.2.0

package/src/generator/parse-command-doc.ts

@@ -0,0 +1,116 @@
+import { fromMarkdown } from "mdast-util-from-markdown";
+import { toString } from "mdast-util-to-string";
+import type { Heading, List, Root, RootContent } from "mdast";
+
+export interface ParsedError {
+  code: string;
+  description: string;
+}
+
+export interface ParsedDependency {
+  module: string;
+  entity: string;
+}
+
+export interface ParsedCommandDoc {
+  commandName: string;
+  errors: ParsedError[];
+  externalDependencies: ParsedDependency[];
+}
+
+export function parseCommandDoc(fileName: string, markdown: string): ParsedCommandDoc {
+  const commandName = fileName.charAt(0).toLowerCase() + fileName.slice(1);
+  const tree = fromMarkdown(markdown);
+
+  return {
+    commandName,
+    errors: parseErrorScenarios(tree),
+    externalDependencies: parseExternalDependencies(tree),
+  };
+}
+
+export function errorCodeToClassName(code: string): string {
+  const pascal = code
+    .toLowerCase()
+    .split("_")
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+    .join("");
+  return pascal + "Error";
+}
+
+function isHeading(node: RootContent): node is Heading {
+  return node.type === "heading";
+}
+
+function isList(node: RootContent): node is List {
+  return node.type === "list";
+}
+
+function getNodesUnderHeading(tree: Root, headingText: string): RootContent[] {
+  const nodes: RootContent[] = [];
+  let collecting = false;
+
+  for (const node of tree.children) {
+    if (isHeading(node)) {
+      if (collecting) break;
+      if (node.depth === 2 && toString(node) === headingText) {
+        collecting = true;
+        continue;
+      }
+    }
+    if (collecting) {
+      nodes.push(node);
+    }
+  }
+
+  return nodes;
+}
+
+const ERROR_PATTERN = /^([A-Z_]+):\s*(.+)$/;
+
+function parseErrorScenarios(tree: Root): ParsedError[] {
+  const nodes = getNodesUnderHeading(tree, "Error Scenarios");
+  const errors: ParsedError[] = [];
+
+  for (const node of nodes) {
+    if (!isList(node)) continue;
+
+    for (const item of node.children) {
+      const text = toString(item);
+      const match = ERROR_PATTERN.exec(text);
+      if (match) {
+        errors.push({ code: match[1], description: match[2].trim() });
+      }
+    }
+  }
+
+  return errors;
+}
+
+const DEPENDENCY_PATTERN = /^([^:]+)::(.+)$/;
+
+function parseExternalDependencies(tree: Root): ParsedDependency[] {
+  const nodes = getNodesUnderHeading(tree, "External Dependencies");
+  const deps: ParsedDependency[] = [];
+
+  for (const node of nodes) {
+    if (!isList(node)) continue;
+
+    for (const item of node.children) {
+      const firstChild = item.children[0];
+      if (firstChild?.type !== "paragraph") continue;
+
+      for (const inline of firstChild.children) {
+        if (inline.type === "link" || inline.type === "linkReference") {
+          const linkText = toString(inline);
+          const match = DEPENDENCY_PATTERN.exec(linkText);
+          if (match) {
+            deps.push({ module: match[1], entity: match[2] });
+          }
+        }
+      }
+    }
+  }
+
+  return deps;
+}

package/src/integration.test.ts

@@ -11,13 +11,11 @@ const REPO_ROOT = path.resolve(__dirname, "..", "..", "..");
 const skipReason = fs.existsSync(CLI_PATH) ? undefined : "Run `pnpm build` first";
 
 describe.skipIf(skipReason)("integration", () => {
-  it("check command runs against sdk-plugins modules", () => {
-    // mdschema may report validation errors in real docs, so we allow non-zero exit codes
-    // but verify the CLI itself doesn't crash with an unexpected error
+  it("module check command runs against erp-kit modules", () => {
     try {
       const result = execFileSync(
         "node",
-        [CLI_PATH, "check", "--modules-root", "packages/erp-kit/src/modules"],
+        [CLI_PATH, "module", "check", "--root", "packages/erp-kit/src/modules"],
         {
           cwd: REPO_ROOT,
           encoding: "utf-8",
@@ -33,11 +31,11 @@ describe.skipIf(skipReason)("integration", () => {
     }
   });
 
-  it("sync-check command runs against sdk-plugins modules", () => {
+  it("module sync-check command runs against erp-kit modules", () => {
     try {
       const result = execFileSync(
         "node",
-        [CLI_PATH, "sync-check", "--modules-root", "packages/erp-kit/src/modules"],
+        [CLI_PATH, "module", "sync-check", "--root", "packages/erp-kit/src/modules"],
         {
           cwd: REPO_ROOT,
           encoding: "utf-8",
@@ -57,7 +55,7 @@ describe.skipIf(skipReason)("integration", () => {
       encoding: "utf-8",
     });
     expect(result).toContain("erp-kit");
-    expect(result).toContain("check");
-    expect(result).toContain("scaffold");
+    expect(result).toContain("module");
+    expect(result).toContain("app");
   });
 });

package/src/module.ts

@@ -1,9 +1,10 @@
 // shared/internal
 export { defineCommand, type Command } from "./modules/shared/defineCommand";
+export { defineQuery, type Query } from "./modules/shared/defineQuery";
 export { definePermissions } from "./modules/shared/definePermissions";
 export { requirePermission } from "./modules/shared/requirePermission";
 export { createDomainError, InsufficientPermissionError } from "./modules/shared/errors";
-export type { CommandContext } from "./modules/shared/types";
+export type { CommandContext, QueryContext, ReadonlyDB } from "./modules/shared/types";
 export type {
   InferSchema,
   Selectable,
@@ -18,9 +19,9 @@ export {
   permissions as primitivesPermissions,
   own as primitivesOwn,
   all as primitivesAll,
-} from "./modules/primitives/permissions";
+} from "./modules/primitives/lib/permissions.generated";
 export {
-  UoMCategoryNotFoundError,
+  UomCategoryNotFoundError,
   UnitNotFoundError,
   IncompatibleUnitsError,
   InactiveUnitError,
@@ -35,21 +36,21 @@ export {
   DuplicateCategoryNameError,
   CategoryHasActiveUnitsError,
   UnitNotInCategoryError,
-  InvalidISOCodeError,
+  InvalidIsoCodeError,
   DuplicateCurrencyCodeError,
   InvalidDecimalPlacesError,
   CannotDeactivateBaseCurrencyError,
   CannotSetInactiveAsBaseCurrencyError,
   SameCurrencyPairError,
   InvalidExchangeRateError,
-} from "./modules/primitives/lib/errors";
-export { type ConvertQuantityInput } from "./modules/primitives/command/convertQuantity";
+} from "./modules/primitives/lib/errors.generated";
+export { type ConvertQuantityInput } from "./modules/primitives/query/convertQuantity";
 export { type ActivateCategoryInput } from "./modules/primitives/command/activateCategory";
 export { type DeactivateCategoryInput } from "./modules/primitives/command/deactivateCategory";
 export { type SetReferenceUnitInput } from "./modules/primitives/command/setReferenceUnit";
 export { type ActivateUnitInput } from "./modules/primitives/command/activateUnit";
 export { type DeactivateUnitInput } from "./modules/primitives/command/deactivateUnit";
-export { type ConvertAmountInput } from "./modules/primitives/command/convertAmount";
+export { type ConvertAmountInput } from "./modules/primitives/query/convertAmount";
 export { type ActivateCurrencyInput } from "./modules/primitives/command/activateCurrency";
 export { type DeactivateCurrencyInput } from "./modules/primitives/command/deactivateCurrency";
 export { type SetBaseCurrencyInput } from "./modules/primitives/command/setBaseCurrency";
@@ -59,7 +60,7 @@ export {
   permissions as userManagementPermissions,
   own as userManagementOwn,
   all as userManagementAll,
-} from "./modules/user-management/permissions";
+} from "./modules/user-management/lib/permissions.generated";
 export { AuditEventEventType, UserStatus } from "./modules/user-management/generated/enums";
 export {
   UserNotFoundError,
@@ -75,7 +76,7 @@ export {
   DuplicateRoleNameError,
   AssignmentNotFoundError,
   InvalidEventTypeError,
-} from "./modules/user-management/lib/errors";
+} from "./modules/user-management/lib/errors.generated";
 export { type ActivateUserInput } from "./modules/user-management/command/activateUser";
 export { type DeactivateUserInput } from "./modules/user-management/command/deactivateUser";
 export { type ReactivateUserInput } from "./modules/user-management/command/reactivateUser";

package/src/modules/item-management/README.md

@@ -0,0 +1,38 @@
+# README
+
+## Overview
+
+The Item Management module manages items — the fundamental SKU-level entity in the ERP system. Items are the sellable, purchasable, and trackable unit that all downstream modules (Sales, Purchasing, Inventory, Manufacturing) reference as the primary transactional entity.
+
+Each item has its own lifecycle (DRAFT → ACTIVE ↔ INACTIVE), unique SKU identity, and optional barcode. Items are classified through a flexible taxonomy system (many-to-many with TaxonomyNode) for hierarchical browsing and filtering.
+
+## Key Features
+
+- **Item Lifecycle**: The canonical SKU-level entity referenced by all operational modules. Lifecycle state management (DRAFT → ACTIVE ↔ INACTIVE), SKU and barcode assignment. Items can be created directly or generated from product templates
+- **Item Taxonomy**: Hierarchical taxonomy tree for multi-dimensional item classification (many-to-many). Items can belong to multiple taxonomy branches simultaneously
+
+## Module Scope
+
+### In Scope
+
+- Item master data management (create, update, delete, status transitions)
+- Item lifecycle state machine (DRAFT → ACTIVE ↔ INACTIVE)
+- SKU and barcode assignment and uniqueness enforcement
+- Unit of measure assignment per item
+- Hierarchical item taxonomy management (TaxonomyNode tree)
+- Item-to-taxonomy classification (many-to-many)
+
+### Out of Scope
+
+- Product template definitions and attribute schemas (product-management module)
+- Variant generation from attribute combinations (product-management module)
+- Sales price list and pricing rule management (pricing module)
+- Inventory tracking and stock levels (inventory module)
+- Lot and serial number management (inventory module)
+- Vendor/supplier management (supplier-management module)
+- Bill of Materials (manufacturing module)
+- Product images and digital asset management
+
+## Module Dependencies
+
+- [primitives](../primitives/README.md) — UoM definitions for item unit of measure

package/src/modules/item-management/command/activateItem.generated.ts

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

package/src/modules/item-management/command/activateItem.test.ts

@@ -0,0 +1,76 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../testing/index";
+import { type CommandContext } from "../../shared/internal";
+import { DB } from "../generated/kysely-tailordb";
+import { InvalidStateTransitionError, ItemNotFoundError } from "../lib/errors.generated";
+import { baseActiveItem, baseDraftItem, baseInactiveItem } from "../testing/fixtures";
+import { run } from "./activateItem";
+
+describe("activateItem", () => {
+  const ctx: CommandContext = {
+    actorId: "test-actor",
+    permissions: ["item-management:activateItem"],
+  };
+
+  it("returns error when item does not exist", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValue(undefined);
+
+    const result = await run(db, { id: "nonexistent" }, ctx);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(ItemNotFoundError);
+    }
+  });
+
+  it("returns error when item is not DRAFT", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(baseActiveItem);
+
+    const result = await run(db, { id: baseActiveItem.id }, ctx);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(InvalidStateTransitionError);
+    }
+  });
+
+  it("returns error when item is INACTIVE", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(baseInactiveItem);
+
+    const result = await run(db, { id: baseInactiveItem.id }, ctx);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(InvalidStateTransitionError);
+    }
+  });
+
+  it("activates a DRAFT item", async () => {
+    const { db, spies } = createMockDb<DB>();
+    const activatedItem = { ...baseDraftItem, status: "ACTIVE" };
+    spies.select.mockReturnValueOnce(baseDraftItem);
+    spies.update.mockReturnValue(activatedItem);
+
+    const result = await run(db, { id: baseDraftItem.id }, ctx);
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.item.status).toBe("ACTIVE");
+    }
+    expect(spies.update).toHaveBeenCalled();
+  });
+
+  it("activates from custom status when from is overridden", async () => {
+    const { db, spies } = createMockDb<DB>();
+    const activatedItem = { ...baseInactiveItem, status: "ACTIVE" };
+    spies.select.mockReturnValueOnce(baseInactiveItem);
+    spies.update.mockReturnValue(activatedItem);
+
+    const result = await run(db, { id: baseInactiveItem.id, from: ["DRAFT", "INACTIVE"] }, ctx);
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.item.status).toBe("ACTIVE");
+    }
+  });
+});

package/src/modules/item-management/command/activateItem.ts

@@ -0,0 +1,42 @@
+import { ok, err, type CommandContext } from "../../shared/internal";
+import { DB } from "../generated/kysely-tailordb";
+import { InvalidStateTransitionError, ItemNotFoundError } from "../lib/errors.generated";
+import { getItem } from "../query/getItem.generated";
+
+export interface ActivateItemInput {
+  id: string;
+  from?: string[];
+}
+
+/**
+ * Function: activateItem
+ *
+ * Transitions an item from DRAFT to ACTIVE status.
+ * Requires name, SKU, and UoM to be set.
+ */
+export async function run(db: DB, input: ActivateItemInput, ctx: CommandContext) {
+  const { id, from } = input;
+
+  // 1. Check item exists
+  const { item } = await getItem(db, { id }, ctx);
+
+  if (!item) {
+    return err(new ItemNotFoundError(id));
+  }
+
+  // 2. Check status is valid for activation
+  const validFromStatuses = from ?? ["DRAFT"];
+  if (!validFromStatuses.includes(item.status)) {
+    return err(new InvalidStateTransitionError(`${item.status} to ACTIVE`));
+  }
+
+  // 3. Update status to ACTIVE
+  const activatedItem = await db
+    .updateTable("Item")
+    .set({ status: "ACTIVE", updatedAt: new Date() })
+    .where("id", "=", id)
+    .returningAll()
+    .executeTakeFirstOrThrow();
+
+  return ok({ item: activatedItem });
+}

package/src/modules/item-management/command/assignItemToTaxonomy.generated.ts

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

package/src/modules/item-management/command/assignItemToTaxonomy.test.ts

@@ -0,0 +1,88 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../testing/index";
+import { type CommandContext } from "../../shared/internal";
+import { DB } from "../generated/kysely-tailordb";
+import {
+  DuplicateAssignmentError,
+  ItemNotFoundError,
+  NodeNotFoundError,
+} from "../lib/errors.generated";
+import { baseActiveItem, baseAssignment, baseChildNode } from "../testing/fixtures";
+import { run } from "./assignItemToTaxonomy";
+
+describe("assignItemToTaxonomy", () => {
+  const ctx: CommandContext = {
+    actorId: "test-actor",
+    permissions: ["item-management:assignItemToTaxonomy"],
+  };
+
+  it("returns error when item does not exist", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(undefined); // Item not found
+
+    const result = await run(db, { itemId: "nonexistent", taxonomyNodeId: baseChildNode.id }, ctx);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(ItemNotFoundError);
+    }
+  });
+
+  it("returns error when node does not exist", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select
+      .mockReturnValueOnce(baseActiveItem) // Item exists
+      .mockReturnValueOnce(undefined); // Node not found
+
+    const result = await run(db, { itemId: baseActiveItem.id, taxonomyNodeId: "nonexistent" }, ctx);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(NodeNotFoundError);
+    }
+  });
+
+  it("returns error when assignment already exists", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select
+      .mockReturnValueOnce(baseActiveItem) // Item exists
+      .mockReturnValueOnce(baseChildNode) // Node exists
+      .mockReturnValueOnce(baseAssignment); // Assignment exists
+
+    const result = await run(
+      db,
+      { itemId: baseActiveItem.id, taxonomyNodeId: baseChildNode.id },
+      ctx,
+    );
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(DuplicateAssignmentError);
+    }
+  });
+
+  it("creates assignment successfully", async () => {
+    const { db, spies } = createMockDb<DB>();
+    const createdAssignment = {
+      ...baseAssignment,
+      id: "new-assignment-id",
+      itemId: baseActiveItem.id,
+      taxonomyNodeId: baseChildNode.id,
+    };
+    spies.select
+      .mockReturnValueOnce(baseActiveItem) // Item exists
+      .mockReturnValueOnce(baseChildNode) // Node exists
+      .mockReturnValueOnce(undefined); // No existing assignment
+    spies.insert.mockReturnValue(createdAssignment);
+
+    const result = await run(
+      db,
+      { itemId: baseActiveItem.id, taxonomyNodeId: baseChildNode.id },
+      ctx,
+    );
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.assignment.itemId).toBe(baseActiveItem.id);
+      expect(result.value.assignment.taxonomyNodeId).toBe(baseChildNode.id);
+    }
+    expect(spies.insert).toHaveBeenCalled();
+  });
+});

package/src/modules/item-management/command/assignItemToTaxonomy.ts

@@ -0,0 +1,63 @@
+import { ok, err, type CommandContext } from "../../shared/internal";
+import { DB } from "../generated/kysely-tailordb";
+import {
+  DuplicateAssignmentError,
+  ItemNotFoundError,
+  NodeNotFoundError,
+} from "../lib/errors.generated";
+import { getItem } from "../query/getItem.generated";
+import { getTaxonomyNode } from "../query/getTaxonomyNode.generated";
+import { getItemTaxonomyAssignment } from "../query/getItemTaxonomyAssignment.generated";
+
+export interface AssignItemToTaxonomyInput {
+  itemId: string;
+  taxonomyNodeId: string;
+}
+
+/**
+ * Function: assignItemToTaxonomy
+ *
+ * Creates a link between an item and a taxonomy node for many-to-many classification.
+ */
+export async function run(db: DB, input: AssignItemToTaxonomyInput, ctx: CommandContext) {
+  const { itemId, taxonomyNodeId } = input;
+
+  // 1. Check item exists
+  const { item } = await getItem(db, { id: itemId }, ctx);
+
+  if (!item) {
+    return err(new ItemNotFoundError(itemId));
+  }
+
+  // 2. Check node exists
+  const { node } = await getTaxonomyNode(db, { id: taxonomyNodeId }, ctx);
+
+  if (!node) {
+    return err(new NodeNotFoundError(taxonomyNodeId));
+  }
+
+  // 3. Check for duplicate assignment
+  const { assignment: existing } = await getItemTaxonomyAssignment(
+    db,
+    { itemId, taxonomyNodeId },
+    ctx,
+  );
+
+  if (existing) {
+    return err(new DuplicateAssignmentError(`${itemId} in ${taxonomyNodeId}`));
+  }
+
+  // 4. Create assignment
+  const assignment = await db
+    .insertInto("ItemTaxonomyAssignment")
+    .values({
+      itemId,
+      taxonomyNodeId,
+      createdAt: new Date(),
+      updatedAt: null,
+    })
+    .returningAll()
+    .executeTakeFirstOrThrow();
+
+  return ok({ assignment: assignment });
+}

package/src/modules/item-management/command/createItem.generated.ts

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