feat(ddb-publisher): document local DynamoDB usage and add sample config store

- add a short README for the ddb-publisher CLI
- document running the CLI against a local DynamoDB container
- add AWS CLI instructions to create the local supplier config table
- add a minimal example config store under tests/example-config-store
- rename the package script from start to cli for clearer CLI usage
- allow localhost DynamoDB endpoints to use default local fake credentials
- rename audit result field from blocking to blockingRecords for clarity
- update audit and run tests to match the new audit shape
- add coverage for local vs non-local endpoint credential handling

Author: m-houston

package.json

@@ -56,7 +56,6 @@
     "generate-dependencies": "npm run generate-dependencies --workspaces --if-present",
     "lint": "npm run lint --workspaces",
     "lint:fix": "npm run lint:fix --workspaces",
-    "start": "npm run start --workspace frontend",
     "test:unit": "npm run test:unit --workspaces",
     "typecheck": "npm run typecheck --workspaces --if-present"
   },

packages/ddb-publisher/README.md

@@ -0,0 +1,62 @@
+# ddb-publisher CLI
+
+`ddb-publisher` reads supplier config JSON files from a directory, validates them against the event schemas, audits existing records in DynamoDB, then publishes the records into the target table.
+
+## Run the publisher
+
+From this package directory:
+
+```bash
+npm run cli -- \
+  --source ../../tests/example-config-store \
+  --env draft \
+  --table supplier-config-draft \
+  --dry-run
+```
+
+## Local DynamoDB
+
+Start DynamoDB Local in Docker:
+
+```bash
+docker run --rm -d \
+  --name supplier-config-ddb-local \
+  -p 8000:8000 \
+  amazon/dynamodb-local
+```
+
+Create the config table with the AWS CLI:
+
+```bash
+AWS_ACCESS_KEY_ID=fakeMyKeyId \
+AWS_SECRET_ACCESS_KEY=fakeSecretAccessKey \
+AWS_REGION=eu-west-2 \
+aws dynamodb create-table \
+  --endpoint-url http://localhost:8000 \
+  --table-name supplier-config-draft \
+  --billing-mode PAY_PER_REQUEST \
+  --attribute-definitions AttributeName=pk,AttributeType=S AttributeName=sk,AttributeType=S \
+  --key-schema AttributeName=pk,KeyType=HASH AttributeName=sk,KeyType=RANGE
+```
+
+Then publish to the local table:
+
+```bash
+SUPPLIER_CONFIG_DDB_ENDPOINT_URL=http://localhost:8000 \
+npm run cli -- \
+  --source ../../tests/example-config-store \
+  --env draft \
+  --table supplier-config-draft
+```
+
+Stop the local container when you're done:
+
+```bash
+docker stop supplier-config-ddb-local
+```
+
+## Useful flags
+
+- `--dry-run` validates local config and schemas without AWS calls
+- `--force` bypasses the audit safety check
+- `--help` shows all options

packages/ddb-publisher/package.json

@@ -25,9 +25,9 @@
   "private": true,
   "scripts": {
     "bundle:release": "npm run generate-dependencies --workspaces --if-present && node ./scripts/bundle-release.mjs",
+    "cli": "tsx src/cli.ts",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
-    "start": "tsx src/cli.ts",
     "test:integration": "jest --config jest.integration.config.ts --runInBand",
     "test:unit": "jest",
     "typecheck": "tsc --noEmit"

packages/ddb-publisher/src/__tests__/audit-branches.test.ts

@@ -26,7 +26,7 @@ describe("auditBeforeLoad branch coverage", () => {
       localRecords: [],
     });
 
-    expect(result.blocking).toEqual([]);
+    expect(result.blockingRecords).toEqual([]);
   });
 
   it("should throw when pk/sk are not strings (and include pk/sk values)", async () => {

packages/ddb-publisher/src/__tests__/audit-local-presence-branch.test.ts

@@ -38,6 +38,6 @@ describe("auditBeforeLoad local.has branch", () => {
       localRecords: local,
     });
 
-    expect(result.blocking).toEqual([]);
+    expect(result.blockingRecords).toEqual([]);
   });
 });

packages/ddb-publisher/src/__tests__/audit-status-branch.test.ts

@@ -18,7 +18,7 @@ describe("auditBeforeLoad status branch", () => {
       localRecords: [],
     });
 
-    expect(result.blocking).toEqual([
+    expect(result.blockingRecords).toEqual([
       { pk: "ENTITY#supplier", sk: "ID#1", status: undefined },
     ]);
   });

packages/ddb-publisher/src/__tests__/audit.test.ts

@@ -56,8 +56,8 @@ describe("auditBeforeLoad", () => {
       localRecords: local,
     });
 
-    expect(result.blocking).toHaveLength(1);
-    expect(result.blocking[0]).toMatchObject({
+    expect(result.blockingRecords).toHaveLength(1);
+    expect(result.blockingRecords[0]).toMatchObject({
       pk: pkForEntity("supplier"),
       sk: skForId("2"),
       status: "ACTIVE",
@@ -104,7 +104,7 @@ describe("auditBeforeLoad pagination and filtering", () => {
       localRecords: local,
     });
 
-    const actual = result.blocking
+    const actual = result.blockingRecords
       .map((b) => b.sk)
       .sort((a, b) => a.localeCompare(b));
     const expected = [skForId("2"), skForId("4")].sort((a, b) =>

packages/ddb-publisher/src/__tests__/run-branches.test.ts

@@ -81,7 +81,7 @@ describe("runPublisher branch coverage", () => {
     fileStore.validateConfigStore.mockReturnValue({ ok: true, issues: [] });
 
     audit.auditBeforeLoad.mockResolvedValue({
-      blocking: [{ pk: "ENTITY#supplier", sk: "ID#1" }],
+      blockingRecords: [{ pk: "ENTITY#supplier", sk: "ID#1" }],
     });
 
     await expect(

packages/ddb-publisher/src/__tests__/run.test.ts

@@ -115,7 +115,7 @@ describe("runPublisher", () => {
     fileStore.validateConfigStore.mockReturnValue({ ok: true, issues: [] });
 
     audit.auditBeforeLoad.mockResolvedValue({
-      blocking: [{ pk: "ENTITY#supplier", sk: "ID#1", status: "ACTIVE" }],
+      blockingRecords: [{ pk: "ENTITY#supplier", sk: "ID#1", status: "ACTIVE" }],
     });
 
     await expect(
@@ -140,7 +140,7 @@ describe("runPublisher", () => {
     fileStore.validateConfigStore.mockReturnValue({ ok: true, issues: [] });
 
     audit.auditBeforeLoad.mockResolvedValue({
-      blocking: [{ pk: "ENTITY#supplier", sk: "ID#1", status: "ACTIVE" }],
+      blockingRecords: [{ pk: "ENTITY#supplier", sk: "ID#1", status: "ACTIVE" }],
     });
 
     await runPublisher({
@@ -163,7 +163,7 @@ describe("runPublisher", () => {
     fileStore.validateConfigStore.mockReturnValue({ ok: true, issues: [] });
 
     audit.auditBeforeLoad.mockResolvedValue({
-      blocking: [],
+      blockingRecords: [],
     });
 
     await runPublisher({
@@ -231,7 +231,7 @@ describe("runPublisher", () => {
 
     fileStore.loadConfigStore.mockResolvedValue(store);
     fileStore.validateConfigStore.mockReturnValue({ ok: true, issues: [] });
-    audit.auditBeforeLoad.mockResolvedValue({ blocking: [] });
+    audit.auditBeforeLoad.mockResolvedValue({ blockingRecords: [] });
 
     process.env.SUPPLIER_CONFIG_DDB_ENDPOINT_URL = "http://127.0.0.1:8000";
 
@@ -246,6 +246,69 @@ describe("runPublisher", () => {
 
       expect(awsClient.DynamoDBClient).toHaveBeenCalledWith({
         endpoint: "http://127.0.0.1:8000",
+        region: "eu-west-2",
+        credentials: {
+          accessKeyId: "fakeMyKeyId",
+          secretAccessKey: "fakeSecretAccessKey",
+        },
+      });
+    } finally {
+      delete process.env.SUPPLIER_CONFIG_DDB_ENDPOINT_URL;
+    }
+  });
+
+  it("should not inject fake credentials for non-local custom endpoints", async () => {
+    const store: LoadedConfigStore = {
+      rootPath: "/tmp",
+      records: [],
+    };
+
+    fileStore.loadConfigStore.mockResolvedValue(store);
+    fileStore.validateConfigStore.mockReturnValue({ ok: true, issues: [] });
+    audit.auditBeforeLoad.mockResolvedValue({ blockingRecords: [] });
+
+    process.env.SUPPLIER_CONFIG_DDB_ENDPOINT_URL = "https://dynamodb.eu-west-2.amazonaws.com";
+
+    try {
+      await runPublisher({
+        sourcePath: "/tmp",
+        env: "draft",
+        tableName: "tbl",
+        dryRun: false,
+        force: false,
+      });
+
+      expect(awsClient.DynamoDBClient).toHaveBeenCalledWith({
+        endpoint: "https://dynamodb.eu-west-2.amazonaws.com",
+      });
+    } finally {
+      delete process.env.SUPPLIER_CONFIG_DDB_ENDPOINT_URL;
+    }
+  });
+
+  it("should not inject fake credentials when the custom endpoint is not a valid URL", async () => {
+    const store: LoadedConfigStore = {
+      rootPath: "/tmp",
+      records: [],
+    };
+
+    fileStore.loadConfigStore.mockResolvedValue(store);
+    fileStore.validateConfigStore.mockReturnValue({ ok: true, issues: [] });
+    audit.auditBeforeLoad.mockResolvedValue({ blockingRecords: [] });
+
+    process.env.SUPPLIER_CONFIG_DDB_ENDPOINT_URL = "not-a-url";
+
+    try {
+      await runPublisher({
+        sourcePath: "/tmp",
+        env: "draft",
+        tableName: "tbl",
+        dryRun: false,
+        force: false,
+      });
+
+      expect(awsClient.DynamoDBClient).toHaveBeenCalledWith({
+        endpoint: "not-a-url",
       });
     } finally {
       delete process.env.SUPPLIER_CONFIG_DDB_ENDPOINT_URL;

packages/ddb-publisher/src/ddb/audit.ts

@@ -1,15 +1,15 @@
-import { ScanCommand } from "@aws-sdk/client-dynamodb";
+import {ScanCommand} from "@aws-sdk/client-dynamodb";
 import type {
   AttributeValue,
   ScanCommandOutput,
 } from "@aws-sdk/client-dynamodb";
-import { DynamoDBDocumentClient } from "@aws-sdk/lib-dynamodb";
-import { z } from "zod";
+import {DynamoDBDocumentClient} from "@aws-sdk/lib-dynamodb";
+import {z} from "zod";
 
-import type { ConfigRecord } from "@supplier-config/file-store";
+import type {ConfigRecord} from "@supplier-config/file-store";
 
-import type { AuditRecord, AuditResult } from "../types";
-import { pkForEntity, skForId } from "./keys";
+import type {AuditRecord, AuditResult} from "../types";
+import {pkForEntity, skForId} from "./keys";
 
 function localKeySet(records: ConfigRecord[]): Set<string> {
   const set = new Set<string>();
@@ -19,23 +19,35 @@ function localKeySet(records: ConfigRecord[]): Set<string> {
   return set;
 }
 
+/**
+ * Schema matching the DDB scan projection used in the audit.
+ */
 const scannedItemSchema = z.object({
   pk: z.string().min(1),
   sk: z.string().min(1),
   status: z.string().optional(),
 });
 
+/**
+ * Find any records in DynamoDB that would block loading the provided local records
+ * (i.e. records that exist in DynamoDB with the same pk/sk but are not DISABLED,
+ * or records that exist in DynamoDB but not in the local set at all).
+ * @param params
+ */
 async function auditBeforeLoad(params: {
   ddb: DynamoDBDocumentClient;
   tableName: string;
+
+  /** Local records to load into ddb/tableName */
   localRecords: ConfigRecord[];
 }): Promise<AuditResult> {
   const local = localKeySet(params.localRecords);
 
-  const blocking: AuditRecord[] = [];
+  const blockingRecords: AuditRecord[] = [];
 
   let lastEvaluatedKey: Record<string, AttributeValue> | null = null;
 
+  // Scan all records in the table (projecting only keys used for validation)
   do {
     const page: ScanCommandOutput = await params.ddb.send(
       new ScanCommand({
@@ -49,8 +61,8 @@ async function auditBeforeLoad(params: {
     );
 
     for (const rawItem of page.Items ?? []) {
+      // Check basic structure of the item before processing
       const parsed = scannedItemSchema.safeParse(rawItem);
-
       if (!parsed.success) {
         const raw = rawItem as Record<string, unknown> | null;
         const rawPk = raw && "pk" in raw ? String((raw as any).pk) : "<missing>";
@@ -61,20 +73,20 @@ async function auditBeforeLoad(params: {
         );
       }
 
-      const { pk, sk, status } = parsed.data;
-
+      // Check for blocking records
+      const {pk, sk, status} = parsed.data;
       const key = `${pk}|${sk}`;
       const isDisabled = status === "DISABLED";
 
       if (!isDisabled && !local.has(key)) {
-        blocking.push({ pk, sk, status });
+        blockingRecords.push(parsed.data);
       }
     }
 
     lastEvaluatedKey = page.LastEvaluatedKey ?? null;
   } while (lastEvaluatedKey);
 
-  return { blocking };
+  return {blockingRecords};
 }
 
-export { auditBeforeLoad };
+export {auditBeforeLoad};