@tailor-platform/erp-kit 0.5.1 → 0.6.0

package/src/commands/lib/sync-check-tests.ts

@@ -2,16 +2,16 @@ import path from "node:path";
 import fs from "node:fs";
 import fg from "fast-glob";
 import { parseTestCasesFromDoc, parseItDescriptionsFromTest } from "../parse-doc-test-cases";
-import { testCaseCategories } from "./discovery";
+import { moduleTestCaseCategories, appTestCaseCategories } from "./discovery";
 import type { CheckError } from "./sync-check-source";
 
 function toCamelCase(pascalCase: string): string {
   return pascalCase.charAt(0).toLowerCase() + pascalCase.slice(1);
 }
 
-export async function runTestCaseSyncCheck(root: string, cwd: string): Promise<CheckError[]> {
+export async function runModuleTestCaseSyncCheck(root: string, cwd: string): Promise<CheckError[]> {
   const errors: CheckError[] = [];
-  const categories = testCaseCategories(root);
+  const categories = moduleTestCaseCategories(root);
 
   for (const category of categories) {
     const docPaths = await fg(category.docPattern, { cwd });
@@ -67,3 +67,63 @@ export async function runTestCaseSyncCheck(root: string, cwd: string): Promise<C
 
   return errors;
 }
+
+function resolveStoryTestPath(docPath: string, testDir: string): string | null {
+  const regex = /^(.+)\/docs\/business-flow\/([^/]+)\/story\/([^/]+)\.md$/;
+  const match = regex.exec(docPath);
+  if (!match) return null;
+  const [, appPath, flow, name] = match;
+  return `${appPath}/${testDir}/${flow}/${name}.test.ts`;
+}
+
+export async function runAppTestCaseSyncCheck(appRoot: string, cwd: string): Promise<CheckError[]> {
+  const errors: CheckError[] = [];
+  const config = appTestCaseCategories(appRoot);
+  const docPaths = await fg(config.docPattern, { cwd });
+
+  for (const docPath of docPaths) {
+    const docFullPath = path.join(cwd, docPath);
+    const docContent = fs.readFileSync(docFullPath, "utf-8");
+    const docTestCases = parseTestCasesFromDoc(docContent);
+
+    if (docTestCases.length === 0) continue;
+
+    const testPath = resolveStoryTestPath(docPath, config.testDir);
+    if (!testPath) continue;
+
+    const testFullPath = path.join(cwd, testPath);
+    if (!fs.existsSync(testFullPath)) continue;
+
+    const testContent = fs.readFileSync(testFullPath, "utf-8");
+    const itDescriptions = parseItDescriptionsFromTest(testContent);
+
+    const docSet = new Set(docTestCases);
+    const testSet = new Set(itDescriptions);
+
+    for (const docCase of docSet) {
+      if (!testSet.has(docCase)) {
+        errors.push({
+          type: "missing-test-case",
+          category: config.name,
+          docPath,
+          sourcePath: testPath,
+          expectedBasename: docCase,
+        });
+      }
+    }
+
+    for (const testCase of testSet) {
+      if (!docSet.has(testCase)) {
+        errors.push({
+          type: "extra-test-case",
+          category: config.name,
+          docPath,
+          sourcePath: testPath,
+          expectedBasename: testCase,
+        });
+      }
+    }
+  }
+
+  return errors;
+}

package/src/commands/sync-check.ts

@@ -1,6 +1,6 @@
 import chalk from "chalk";
 import { runSourceSyncCheck, type SyncCheckResult, type CheckError } from "./lib/sync-check-source";
-import { runTestCaseSyncCheck } from "./lib/sync-check-tests";
+import { runModuleTestCaseSyncCheck, runAppTestCaseSyncCheck } from "./lib/sync-check-tests";
 
 export type { SyncCheckResult, CheckError } from "./lib/sync-check-source";
 
@@ -10,10 +10,14 @@ export async function runSyncCheck(
 ): Promise<SyncCheckResult> {
   const sourceResult = await runSourceSyncCheck(config, cwd);
   if (config.modulesRoot) {
-    const testCaseErrors = await runTestCaseSyncCheck(config.modulesRoot, cwd);
+    const testCaseErrors = await runModuleTestCaseSyncCheck(config.modulesRoot, cwd);
     sourceResult.errors.push(...testCaseErrors);
-    sourceResult.exitCode = sourceResult.errors.length > 0 ? 1 : 0;
   }
+  if (config.appRoot) {
+    const storyErrors = await runAppTestCaseSyncCheck(config.appRoot, cwd);
+    sourceResult.errors.push(...storyErrors);
+  }
+  sourceResult.exitCode = sourceResult.errors.length > 0 ? 1 : 0;
   return sourceResult;
 }
 

package/src/generator/generate-app-code.ts

@@ -1,29 +1,33 @@
-import fs from "node:fs";
+import fs, { globSync } from "node:fs";
 import path from "node:path";
+import { parseTestCasesFromDoc } from "../commands/parse-doc-test-cases";
+import { APP_PATHS } from "../commands/lib/paths";
 import { parseResolverDoc } from "./parse-resolver-doc";
-import { generateResolverStub, generateResolverTestStub } from "./generate-stubs";
+import {
+  generateResolverStub,
+  generateResolverTestStub,
+  generateStoryTestStub,
+} from "./generate-stubs";
 import { scaffoldAppBoilerplate } from "./scaffold";
 
 export function runGenerateAppCode(appPath: string): number {
   const appName = path.basename(appPath);
   scaffoldAppBoilerplate(appPath, appName);
 
-  const docsDir = path.join(appPath, "docs", "resolver");
-  const resolverDir = path.join(appPath, "backend", "src", "resolvers");
+  generateResolverStubs(appPath, appName);
+  generateStoryTestStubs(appPath, appName);
 
-  if (!fs.existsSync(docsDir)) {
-    console.log(`No docs/resolver/ directory found — skipping resolver generation`);
-    console.log(`Generated boilerplate for ${appName}`);
-    return 0;
-  }
+  return 0;
+}
+
+function generateResolverStubs(appPath: string, appName: string): void {
+  const docsDir = path.join(appPath, "docs", "resolver");
+  if (!fs.existsSync(docsDir)) return;
 
   const mdFiles = fs.readdirSync(docsDir).filter((f) => f.endsWith(".md"));
-  if (mdFiles.length === 0) {
-    console.log(`No resolver docs found — skipping resolver generation`);
-    console.log(`Generated boilerplate for ${appName}`);
-    return 0;
-  }
+  if (mdFiles.length === 0) return;
 
+  const resolverDir = path.join(appPath, "backend", "src", "resolvers");
   fs.mkdirSync(resolverDir, { recursive: true });
   let generated = 0;
 
@@ -46,6 +50,37 @@ export function runGenerateAppCode(appPath: string): number {
     }
   }
 
-  console.log(`Scaffolded ${generated} resolver(s) for ${appName}`);
-  return 0;
+  if (generated > 0) {
+    console.log(`Scaffolded ${generated} resolver(s) for ${appName}`);
+  }
+}
+
+function generateStoryTestStubs(appPath: string, appName: string): void {
+  const storyPattern = path.join(appPath, "docs/business-flow/*/story/*.md");
+  const storyDocs = globSync(storyPattern);
+  let generated = 0;
+
+  for (const storyDocPath of storyDocs) {
+    const content = fs.readFileSync(storyDocPath, "utf-8");
+    const testCases = parseTestCasesFromDoc(content);
+    if (testCases.length === 0) continue;
+
+    const regex = /\/docs\/business-flow\/([^/]+)\/story\/([^/]+)\.md$/;
+    const match = regex.exec(storyDocPath);
+    if (!match) continue;
+    const [, flow, storyName] = match;
+
+    const testDir = path.join(appPath, APP_PATHS.tests.stories, flow);
+    const testFile = path.join(testDir, `${storyName}.test.ts`);
+    if (fs.existsSync(testFile)) continue;
+
+    fs.mkdirSync(testDir, { recursive: true });
+    fs.writeFileSync(testFile, generateStoryTestStub(storyName, testCases));
+    console.log(`  scaffolded ${path.relative(appPath, testFile)}`);
+    generated++;
+  }
+
+  if (generated > 0) {
+    console.log(`Scaffolded ${generated} story test(s) for ${appName}`);
+  }
 }

package/src/generator/generate-stubs.ts

@@ -28,4 +28,8 @@ export function generateResolverTestStub(resolverName: string): string {
   return renderStub("resolverTest", resolverName);
 }
 
+export function generateStoryTestStub(name: string, testCases: string[]): string {
+  return renderStub("storyTest", name, testCases);
+}
+
 export { renderStub, type StubType } from "./stub-templates";

package/src/generator/stub-templates.test.ts

@@ -52,4 +52,15 @@ describe("renderStub", () => {
     expect(result).toContain('import("./createItem")');
     expect(result).toContain("resolver.default");
   });
+
+  it("storyTest: generates integration test with graphql client and test cases", () => {
+    const result = renderStub("storyTest", "admin--create-item", [
+      "creates item successfully",
+      "rejects duplicate SKU",
+    ]);
+    expect(result).toContain('describe("admin--create-item"');
+    expect(result).toContain("createGraphQLClient");
+    expect(result).toContain('it("creates item successfully"');
+    expect(result).toContain('it("rejects duplicate SKU"');
+  });
 });

package/src/generator/stub-templates.ts

@@ -133,6 +133,22 @@ describe("${name}", () => {
     expect(resolver.default.name).toBe("${name}");
   });
 });
+`;
+    },
+  },
+  storyTest: {
+    render: (name: string, testCases: string[]) => {
+      const its = testCases
+        .map((tc) => `  it("${tc}", async () => {\n    // TODO: implement\n  });`)
+        .join("\n\n");
+      return `import { describe, expect, inject, it } from "vitest";
+import { createGraphQLClient } from "@/tests/utils/graphql-client";
+
+describe("${name}", () => {
+  const graphQLClient = createGraphQLClient(inject("url"), inject("token"));
+
+${its}
+});
 `;
     },
   },
@@ -140,6 +156,11 @@ describe("${name}", () => {
 
 export type StubType = keyof typeof templates;
 
-export function renderStub(type: StubType, name: string): string {
+export function renderStub(type: "storyTest", name: string, testCases: string[]): string;
+export function renderStub(type: Exclude<StubType, "storyTest">, name: string): string;
+export function renderStub(type: StubType, name: string, testCases?: string[]): string {
+  if (type === "storyTest") {
+    return templates.storyTest.render(name, testCases!);
+  }
   return templates[type].render(name);
 }

package/src/modules/inventory/docs/features/inventory-adjustment.md

@@ -39,7 +39,7 @@ flowchart TD
 - **Shrinkage / theft**: Periodic checks or count results show missing inventory with no corresponding shipment. A negative adjustment with reason code "Shrinkage" records the loss.
 - **Counting error correction**: A cycle count reveals more units on the shelf than the system shows. A positive adjustment with reason code "Counting Error" increases the on-hand balance.
 - **Receiving error correction**: Goods receipt recorded the wrong quantity. A positive or negative adjustment with reason code "Receiving Error" corrects the discrepancy.
-- **Production variance**: Actual yield differs from the expected output of a manufacturing process. An adjustment with reason code "Production Variance" reconciles the difference.
+- **Production variance fallback**: Actual yield differs from expected output, but the site is not using the manufacturing module or the discrepancy is discovered with no resolvable production-order or work-order source document. In that limited case, a direct adjustment with reason code "Production Variance" reconciles the difference.
 - **Threshold-based approval**: An adjustment exceeding a configured quantity or value limit is routed to a supervisor for approval before confirmation.
 - **Bulk post-count adjustment**: After a full physical inventory count, the system generates one adjustment record per variance line, allowing batch review, reason-code assignment, and confirmation.
 
@@ -56,6 +56,7 @@ flowchart TD
 - Adjustments originating from an inventory count link back to the count session for traceability
 - Confirmed adjustments update inventory valuation consistent with the organization's costing method
 - Adjustments are immutable after confirmation; corrections require a new, offsetting adjustment
+- A direct adjustment with reason code `Production Variance` must be rejected or rerouted when a resolvable manufacturing `productionOrderReference` or `workOrderReference` exists; those cases must enter inventory through `ManufacturingScrapHandoff`
 
 ## Reference Links
 

package/src/modules/inventory/docs/features/scrap-management.md

@@ -2,10 +2,12 @@
 
 ## Overview
 
-Scrap management handles the controlled removal of damaged, expired, defective, or obsolete stock from usable inventory. Scrap is modeled as an InventoryAdjustment with `adjustmentType = SCRAP`. When confirmed, the adjustment moves stock from the source storage location to a virtual "scrap" location, effectively removing it from available stock and reducing inventory valuation.
+Scrap management handles the controlled removal of damaged, expired, defective, or obsolete stock from usable inventory. Scrap is modeled as an `InventoryAdjustment` with `adjustmentType = SCRAP`. When confirmed, the adjustment moves stock from the source storage location to a virtual "scrap" location, effectively removing it from available stock and reducing inventory valuation.
 
 Organizations may enforce approval workflows for scrap adjustments that exceed a defined value threshold, ensuring proper oversight of material losses. Scrap adjustments follow the same approval workflow as correction adjustments (DRAFT → PENDING_APPROVAL → CONFIRMED). Once confirmed, the adjustment is immutable — if scrap was created in error, a new CORRECTION adjustment with a positive quantityDelta can restore the stock.
 
+Inventory accepts scrap input both from direct inventory users and from upstream manufacturing execution. Manufacturing-originated scrap enters inventory through the `ManufacturingScrapHandoff` contract defined in manufacturing `work-order-execution.md`, after which inventory creates or updates the `InventoryAdjustment` that owns stock and valuation effects.
+
 ## Business Purpose
 
 - Remove physically damaged, expired, or quality-rejected stock from available inventory so it is not accidentally picked, sold, or consumed
@@ -38,9 +40,42 @@ flowchart TD
 - **Quality failure scrap**: Items that fail incoming or in-process quality inspection are immediately scrapped, with the quality rejection linked as the scrap reason
 - **Obsolescence write-off**: Slow-moving or discontinued items are scrapped as part of a periodic inventory review to reflect their true recoverable value
 - **High-value approval scrap**: A scrap adjustment exceeds the organization's value threshold, triggering a manager approval step before the stock movement is executed
+- **Manufacturing-originated scrap**: A work order reports scrap and sends `ManufacturingScrapHandoff`; inventory resolves the source location, creates a SCRAP adjustment, and runs the same approval policy as any other scrap event
 - **Scrap error correction**: A scrap adjustment is found to have been created in error; a new CORRECTION adjustment with positive quantityDelta restores the stock to the source location
 - **Lot/serial-tracked scrap**: Specific lots or serial numbers are scrapped, maintaining full traceability from receipt through disposal. Serial numbers transition to SCRAPPED state on confirmation.
 
+Inventory accepts `ManufacturingScrapHandoff` from manufacturing work-order execution with the following minimum fields:
+
+- `productionOrderReference`
+- `workOrderReference`
+- `itemReference`
+- `scrapQuantity`
+- `unitOfMeasure`
+- `scrapReasonCode`
+- `siteReference`
+- `postingDate`
+
+Optional and conditional fields:
+
+- `sourceStorageLocationReference`: optional when inventory can derive the source location from prior issue, backflush, or site-level manufacturing scrap policy; otherwise required
+- `inventoryLotReference`: required when the scrapped item is lot-tracked
+- `serialReferences`: required when the scrapped item is serial-tracked
+- `scrapDispositionCode`: optional classification retained for downstream analysis
+
+Inventory maps the handoff into an inventory-owned `InventoryAdjustment` as follows:
+
+- `adjustmentType = SCRAP`
+- `itemReference`, `siteReference`, `postingDate`, and reason fields come directly from the handoff
+- `productionOrderReference` and `workOrderReference` are retained as source-document traceability fields on the adjustment
+- `sourceStorageLocationReference` is taken from the payload when present; otherwise inventory must derive it from manufacturing issue history, staging-location policy, or other site-level configuration before the adjustment can proceed
+- `inventoryLotReference` and `serialReferences` flow into the same lot or serial validation rules used by direct inventory scrap
+
+Approval and confirmation rules are inventory-owned:
+
+- If the resulting scrap value exceeds the configured approval threshold, inventory creates the adjustment in `PENDING_APPROVAL`
+- If the threshold is not exceeded, inventory may confirm the adjustment immediately
+- If location, lot, serial, or quantity resolution fails, inventory rejects the handoff and does not mutate stock
+
 ## Test Cases
 
 - Creating a SCRAP adjustment with positive quantityDelta is rejected
@@ -55,6 +90,9 @@ flowchart TD
 - Scrapped items cannot re-enter available stock without a new CORRECTION adjustment
 - Scrap reason is mandatory and must be one of the defined reason categories
 - Listing adjustments filtered by `adjustmentType = SCRAP` returns only scrap records
+- A valid `ManufacturingScrapHandoff` must create or update a SCRAP adjustment that preserves the production-order and work-order references for traceability
+- Manufacturing-originated scrap must follow the same approval threshold policy as manually entered scrap adjustments
+- If inventory cannot resolve the source storage location required for `ManufacturingScrapHandoff`, the handoff must be rejected without mutating stock
 
 ## Reference Links
 

package/src/modules/manufacturing/README.md

@@ -0,0 +1,63 @@
+# README
+
+## Overview
+
+The Manufacturing module manages production planning and execution from recipe and process definition through order release, shop-floor progress tracking, completion, and cost capture. It owns the master and transactional records that explain what should be produced, how it should be produced, where capacity exists to produce it, what work is in progress, what quantities were consumed or completed, and how actual manufacturing results differ from the plan.
+
+Manufacturing sits between upstream demand or supply signals and downstream stock or finance execution. It references items from item-management, company and site context from organization, units and currencies from primitives, and coordinates with inventory for component issue, finished-goods receipt, and scrap posting. That coordination includes named cross-module contracts such as `ManufacturingReceiptHandoff`, `ManufacturingScrapHandoff`, `InventoryIssueOutcomeEvent`, and `ManufacturingCostSettlementAcknowledgment`, which let inventory and downstream accounting remain the owners of stock movement, valuation, and settlement while manufacturing remains the owner of production intent and variance analysis. It may prepare cost and account-reference data for downstream accounting, but journal posting and ledger ownership remain outside the module.
+
+## Key Features
+
+- **[Bill of Material Management](docs/features/bill-of-material-management.md)**: Define versioned multi-level bills of material for finished goods and subassemblies, including component quantities, scrap assumptions, effectivity, and default selection rules used by production orders
+- **[Routing and Work Center Definition](docs/features/routing-and-work-center-definition.md)**: Define routings as ordered manufacturing steps and configure work centers with capacity, calendars, standard times, and cost rates used for planning and execution
+- **[Production Order Lifecycle](docs/features/production-order-lifecycle.md)**: Create, schedule, release, reschedule, cancel, complete, technically complete, and close production orders with BOM and routing snapshots plus progress visibility from planned order through settled closeout
+- **[Work Order Execution](docs/features/work-order-execution.md)**: Execute operation-level work orders with start, pause, report, complete, material issue or backflush, scrap capture, and finished or intermediate receipt handoff to inventory
+- **[Manufacturing Cost and Variance](docs/features/manufacturing-cost-and-variance.md)**: Capture planned versus actual component, labor, machine, and overhead cost at production-order level and classify manufacturing variances for downstream accounting consumption
+
+## Module Scope
+
+### In Scope
+
+- Bill of material ownership, including component lines, versioning, effectivity windows, multi-level subassembly references, and `bomType` semantics for `MANUFACTURE`, `PHANTOM`, and `KIT`
+- Routing ownership, including ordered operations, standard setup or run times, operation instructions, and work-center assignment
+- Work center master data, including company or site scope, availability calendar, capacity assumptions, and standard cost rates
+- Production order planning and control, including creation, scheduling, BOM or routing selection, release, cancellation, completion, technical completion, and closeout
+- Work order execution at operation level, including start, pause, resume, quantity reporting, time capture, scrap reporting, and exception notes
+- Material requirement handoff to inventory for reservation, issue, backflush, finished-goods receipt, intermediate receipt, and scrap posting
+- Planned-versus-actual manufacturing cost rollup using component issue values from inventory plus labor or machine rates from work centers, with explicit variance categories and downstream account references
+- Production status, progress, and auditability scoped by company and site
+
+### Out of Scope
+
+- Forecasting, MRP netting, replenishment proposals, and automated procurement planning
+- Advanced finite-capacity optimization, drag-and-drop scheduling boards, and AI or rules-based sequencing
+- Quality inspection plans, nonconformance, CAPA, rework loops, and regulated electronic batch record workflows
+- Subcontracting, outside processing, contract manufacturing, and supplier-operated work centers
+- Co-products, by-products, and joint-production costing
+- Detailed operator kiosk UX, barcode device workflows, PLC or IoT machine integration, and MES hardware connectivity
+- Warehouse ownership, stock balances, lot or serial master records, and inventory valuation logic
+- Journal entry posting, WIP settlement, period close, and general-ledger balance ownership
+- Preventive maintenance, OEE analytics, and HR or payroll-driven labor management
+
+### Scope Decision Rationale
+
+Manufacturing is scoped to the **production definition and execution layer**: product recipe, process steps, capacity context, production order control, and operation-level reporting. These concepts depend on one another and change together, so they belong in one module rather than being split prematurely across planning, execution, and costing.
+
+Inventory remains the owner of **physical stock state**. Manufacturing decides that materials should be issued, scrap should be recorded, or finished goods should be received, but inventory owns the resulting stock movement, lot or serial handling, warehouse location state, and valuation basis. Manufacturing can request issue execution, but actual material cost becomes manufacturing-visible only when inventory returns the named `InventoryIssueOutcomeEvent` after inventory-owned valuation is complete. This keeps manufacturing focused on production intent and progress rather than warehouse internals.
+
+Sales and purchase remain the owners of **commercial demand and supply commitments**. Manufacturing can consume sales demand, open supply status, or manual planner input when creating production orders, but it must not own customer orders, purchase orders, or supplier receipts. That separation preserves clean module boundaries and allows manufacturing to serve both make-to-stock and make-to-order flows without duplicating commercial logic.
+
+Accounting remains the owner of **financial posting and settlement**. Manufacturing can capture planned and actual production cost, classify variances into price, usage, rate, efficiency, scrap, and yield categories, and reference WIP or variance accounts from coa-management, but posting journal entries and enforcing period-close rules belong to downstream accounting modules. This keeps cost insight in manufacturing without pulling ledger behavior into the shop-floor domain.
+
+## Module Dependencies
+
+- [item-management](../item-management/README.md) — Finished goods, subassemblies, raw materials, and consumables are referenced as Items or SKUs
+- [organization](../organization/README.md) — Company and Site scope for BOM defaults, work centers, and production execution context
+- [primitives](../primitives/README.md) — Unit-of-measure conversions for component and output quantities plus currency references for costing
+- [inventory](../inventory/README.md) — Downstream execution of component issue, backflush, finished-goods receipt, intermediate receipt, scrap, lot assignment, and actual material cost sourcing through `InventoryIssueOutcomeEvent`
+- [user-management](../user-management/README.md) — Permissions for create, release, reschedule, start, complete, technically complete, cancel, close, and cost-review actions
+- [audit](../audit/README.md) — Immutable audit trail for BOM revisions, routing changes, order transitions, and execution events
+- [coa-management](../coa-management/README.md) — WIP, absorption, material price, material usage, labor rate, labor efficiency, machine rate, machine efficiency, scrap, and yield account references for downstream cost posting
+- [sales](../sales/README.md) — Optional demand signal source for make-to-order or priority-driven production planning
+- [purchase](../purchase/README.md) — Optional material availability and ETA signal source for release decisions and shortage visibility
+- [product-management](../product-management/README.md) — Optional product or variant metadata source when aligning commercial catalog structure to manufacturing definitions

package/src/modules/manufacturing/command/activateBillOfMaterial.generated.ts

@@ -0,0 +1,6 @@
+// @generated — do not edit
+import { permissions } from "../lib/permissions.generated";
+import { run } from "./activateBillOfMaterial";
+import { defineCommand } from "@tailor-platform/erp-kit/module";
+
+export const activateBillOfMaterial = defineCommand(permissions.activateBillOfMaterial, run);

package/src/modules/manufacturing/command/activateBillOfMaterial.test.ts

@@ -0,0 +1,166 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  BomNotFoundError,
+  BomNotActivatableError,
+  ComponentLineRequiredError,
+  ComponentItemInactiveError,
+  CircularBomReferenceError,
+  EffectivityConflictError,
+} from "../lib/errors.generated";
+import { baseDraftBom, baseActiveBom, baseBomLine } from "../testing/fixtures";
+import { run } from "./activateBillOfMaterial";
+import type { CommandContext } from "@tailor-platform/erp-kit/module";
+
+describe("activateBillOfMaterial", () => {
+  const ctx: CommandContext = {
+    actorId: "test-actor",
+    permissions: ["manufacturing:activateBillOfMaterial"],
+  };
+
+  it("activates a valid draft BOM", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const activatedBom = { ...baseDraftBom, status: "ACTIVE" as const };
+
+    // BOM exists and is DRAFT
+    spies.select.mockReturnValueOnce(baseDraftBom);
+    // lines exist
+    spies.select.mockReturnValueOnce([baseBomLine]);
+    // component item exists (active)
+    spies.select.mockReturnValueOnce({ id: "item-2" });
+    // no conflicting active BOM
+    spies.select.mockReturnValueOnce(undefined);
+    // update to ACTIVE
+    spies.update.mockReturnValue(activatedBom);
+
+    const result = await run(db, { id: "bom-1" }, ctx);
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.billOfMaterial.status).toBe("ACTIVE");
+    }
+    expect(spies.update).toHaveBeenCalled();
+  });
+
+  it("returns error when the BOM does not exist", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+
+    spies.select.mockReturnValueOnce(undefined);
+
+    const result = await run(db, { id: "bom-nonexistent" }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(BomNotFoundError);
+    }
+  });
+
+  it("returns error when the BOM is not in DRAFT", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+
+    spies.select.mockReturnValueOnce(baseActiveBom);
+
+    const result = await run(db, { id: "bom-2" }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(BomNotActivatableError);
+    }
+  });
+
+  it("returns error when the BOM has no component lines", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+
+    // BOM exists and is DRAFT
+    spies.select.mockReturnValueOnce(baseDraftBom);
+    // no lines
+    spies.select.mockReturnValueOnce([]);
+
+    const result = await run(db, { id: "bom-1" }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(ComponentLineRequiredError);
+    }
+  });
+
+  it("returns error when a component item is inactive", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+
+    // BOM exists and is DRAFT
+    spies.select.mockReturnValueOnce(baseDraftBom);
+    // lines exist
+    spies.select.mockReturnValueOnce([baseBomLine]);
+    // component item not found (inactive)
+    spies.select.mockReturnValueOnce(undefined);
+
+    const result = await run(db, { id: "bom-1" }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(ComponentItemInactiveError);
+    }
+  });
+
+  it("returns error when a circular manufactured-item structure is detected", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const bomWithSubassembly = {
+      ...baseDraftBom,
+    };
+    const subassemblyLine = {
+      ...baseBomLine,
+      isSubassembly: true,
+      itemId: "item-sub",
+    };
+
+    // BOM exists and is DRAFT
+    spies.select.mockReturnValueOnce(bomWithSubassembly);
+    // lines with subassembly
+    spies.select.mockReturnValueOnce([subassemblyLine]);
+    // component item exists
+    spies.select.mockReturnValueOnce({ id: "item-sub" });
+    // child BOMs exist for subassembly item (execute returns array)
+    spies.select.mockReturnValueOnce([
+      {
+        ...baseDraftBom,
+        id: "child-bom",
+        parentItemId: "item-sub",
+      },
+    ]);
+    // child BOM lines reference back to parent item (circular)
+    spies.select.mockReturnValueOnce([{ ...baseBomLine, itemId: "item-1" }]);
+
+    const result = await run(db, { id: "bom-1" }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(CircularBomReferenceError);
+    }
+  });
+
+  it("returns error when activation would create an effectivity conflict", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+
+    // BOM exists and is DRAFT with default selection
+    spies.select.mockReturnValueOnce(baseDraftBom);
+    // lines exist
+    spies.select.mockReturnValueOnce([baseBomLine]);
+    // component item exists
+    spies.select.mockReturnValueOnce({ id: "item-2" });
+    // conflicting active BOM with same parent + default selection + no date bounds
+    spies.select.mockReturnValueOnce({
+      ...baseActiveBom,
+      defaultSelection: true,
+      effectivityStartDate: null,
+      effectivityEndDate: null,
+    });
+
+    const result = await run(db, { id: "bom-1" }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(EffectivityConflictError);
+    }
+  });
+});