@unchainedshop/platform 5.0.0-alpha.5 → 5.0.0-alpha.8

package/README.md

@@ -3,146 +3,116 @@
 
 # @unchainedshop/platform
 
-Umbrella package for the Unchained Engine. Provides complete platform setup including database initialization, API server, migrations, templates, and runtime configuration.
+Umbrella package for the Unchained Engine. Initializes the database, core modules and services, plugins, GraphQL server, message templates, and work queue.
 
 ## Installation
 
 ```bash
-npm install @unchainedshop/platform
+npm install @unchainedshop/platform express
 ```
 
-## Usage
+## Quick start
+
+Register plugins, initialize the platform, and connect it to your HTTP server:
 
 ```typescript
-import { startPlatform } from '@unchainedshop/platform';
 import express from 'express';
+import { startPlatform } from '@unchainedshop/platform';
+import { connect } from '@unchainedshop/api/express';
+import { registerBasePlugins } from '@unchainedshop/plugins/presets/base';
 
-const app = express();
+registerBasePlugins();
 
-const { unchainedAPI, graphqlHandler } = await startPlatform({
-  express: app,
-  options: {
-    // Platform options
-  },
-});
+const app = express();
+const platform = await startPlatform({});
+await connect(app, platform);
 
-// Platform is ready
+const products = await platform.unchainedAPI.modules.products.findProducts({});
 app.listen(4010);
 ```
 
-## API Overview
+For Fastify, use `connect` from `@unchainedshop/api/fastify` with a Fastify instance. `connect()` mounts GraphQL, MCP, and registered plugin routes. Pass `{ adminUI: true }` as its third argument to serve an installed `@unchainedshop/admin-ui` package.
 
-### Platform Setup
-
-| Export | Description |
-|--------|-------------|
-| `startPlatform` | Initialize complete Unchained platform |
-| `runMigrations` | Run database migrations |
-| `printRuntimeConfiguration` | Log registered templates, events, and adapters |
-
-### Context Helpers
-
-| Export | Description |
-|--------|-------------|
-| `setAccessToken` | Set access token for user session |
-| `getAccessToken` | Get current access token |
-| `invalidateAccessToken` | Invalidate/logout access token |
-
-### Templates
-
-| Export | Description |
-|--------|-------------|
-| `MessageTypes` | Available message/notification types |
-| `setupTemplates` | Register message templates |
-
-### Message Types
-
-| Type | Description |
-|------|-------------|
-| `ACCOUNT_ACTION` | Account verification, password reset |
-| `DELIVERY` | Delivery notifications |
-| `ORDER_CONFIRMATION` | Order confirmation emails |
-| `ORDER_REJECTION` | Order rejection notifications |
-| `QUOTATION_STATUS` | Quotation status updates |
-| `ENROLLMENT_STATUS` | Subscription status updates |
-| `FORWARD_DELIVERY` | Forward delivery notifications |
-
-## Quick Start
-
-```typescript
-import express from 'express';
-import { startPlatform, MessageTypes } from '@unchainedshop/platform';
-
-const app = express();
-
-const { unchainedAPI, graphqlHandler } = await startPlatform({
-  express: app,
-  options: {
-    modules: {
-      // Module-specific configuration
-    },
-    plugins: [
-      // Plugin imports
-    ],
-  },
-  workQueueConfig: {
-    // Worker queue configuration
-  },
-});
-
-// Access unchained API
-const products = await unchainedAPI.modules.products.findProducts({});
-
-// Start server
-app.use('/graphql', graphqlHandler);
-app.listen(4010);
-```
+Before startup, set `ROOT_URL`, `EMAIL_WEBSITE_NAME`, `EMAIL_WEBSITE_URL`, `EMAIL_FROM`, and `UNCHAINED_TOKEN_SECRET` (at least 32 characters). Set `MONGO_URL` for an external MongoDB; otherwise the database package starts a local instance.
 
 ## Configuration
 
 ```typescript
 const platform = await startPlatform({
-  express: app,
   options: {
-    modules: {
-      orders: {
-        // Order module options
-      },
-      products: {
-        // Product module options
-      },
-    },
-    services: {
-      // Custom services
+    orders: {
+      // Order module settings
     },
-    bulkImporter: {
-      handlers: {
-        // Custom import handlers
-      },
+    products: {
+      // Product module settings
     },
   },
-  workQueueConfig: {
-    batchSize: 10,
-    pollInterval: 1000,
+  modules: {
+    // Custom modules with a configure({ db, migrationRepository, options }) function
+  },
+  services: {
+    // Custom services
+  },
+  bulkImporter: {
+    handlers: {
+      // Custom import handlers
+    },
   },
-  context: (defaultResolver) => async (props, req, res) => {
-    const context = await defaultResolver(props, req, res);
-    return {
-      ...context,
-      // Custom context properties
-    };
+  workQueueOptions: {
+    skipInvalidationOnStartup: true,
   },
+  context: (defaultResolver) => async (props, req, res) => ({
+    ...(await defaultResolver(props, req, res)),
+    // Additional request context
+  }),
 });
 ```
 
-## Returns
+`PlatformOptions` combines core configuration with GraphQL server options, `rolesOptions`, `workQueueOptions`, and `auditLog`. Built-in modules are included automatically. Module settings are direct properties of `options`; module/service overrides and import/export handlers are top-level options.
+
+The work queue runs migrations and starts queue managers during startup unless workers are disabled. See [work queue options](src/setup/setupWorkqueue.ts) and [platform initialization](src/startPlatform.ts) for the current options.
+
+## Download documentation for coding assistants
+
+```bash
+npx --package @unchainedshop/platform unchained download-llm-docs
+```
+
+Requires Git. Downloads docs into `.unchained-docs/` for the installed platform
+version's tag, falling back to `master` when the tag is unavailable. Updates a
+managed file index in existing `CLAUDE.md` and `AGENTS.md` files (legacy `agents.md`
+is also supported), or creates `CLAUDE.md` if none exists. Re-running replaces the
+downloaded docs and index while preserving surrounding instructions. Add
+`.unchained-docs/` to your project's `.gitignore`.
+
+## Exports
+
+| Export | Description |
+|--------|-------------|
+| `startPlatform` | Initialize the platform |
+| `PlatformOptions` | Platform configuration type |
+| `runMigrations` | Run registered database migrations |
+| `printRuntimeConfiguration` | Log registered templates, events, and adapters |
+| `MessageTypes` | Built-in message type constants |
+
+The package also exports the [built-in template resolvers](src/templates/index.ts). Platform startup registers them automatically; custom templates use `MessagingDirector.registerTemplate()` from `@unchainedshop/core`.
+
+| Message type | Purpose |
+|--------------|---------|
+| `ACCOUNT_ACTION` | Email verification and password reset |
+| `DELIVERY` | Forward delivery notifications |
+| `ORDER_CONFIRMATION` | Order confirmations |
+| `ORDER_REJECTION` | Order rejections |
+| `QUOTATION_STATUS` | Quotation status updates |
+| `ENROLLMENT_STATUS` | Enrollment status updates |
+| `ERROR_REPORT` | Error reports |
 
-The `startPlatform` function returns:
+## Return value
 
 | Property | Description |
 |----------|-------------|
-| `unchainedAPI` | Complete Unchained core API instance |
-| `graphqlHandler` | GraphQL Yoga server instance for Express/Fastify |
+| `unchainedAPI` | Core modules, services, bulk importer/exporter, and options |
+| `graphqlHandler` | GraphQL Yoga server instance |
 | `db` | MongoDB database instance |
 
 ## License

package/bin/unchained.js

@@ -0,0 +1,164 @@
+#!/usr/bin/env node
+
+import { execFileSync } from 'node:child_process';
+import {
+  cpSync,
+  existsSync,
+  mkdtempSync,
+  readFileSync,
+  readdirSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
+import { join, relative } from 'node:path';
+import { tmpdir } from 'node:os';
+import { createRequire } from 'node:module';
+
+const GITHUB_REPO = 'https://github.com/unchainedshop/unchained.git';
+const DOCS_SUBPATH = 'docs/docs';
+const DOCS_DIR = join(process.cwd(), '.unchained-docs');
+const INDEX_START = '<!-- UNCHAINED_DOCS_INDEX:BEGIN -->';
+const INDEX_END = '<!-- UNCHAINED_DOCS_INDEX:END -->';
+
+const command = process.argv[2];
+
+if (command !== 'download-llm-docs') {
+  console.log(`Usage: unchained <command>
+
+Commands:
+  download-llm-docs   Download Unchained Engine docs for LLM coding assistants
+                      (Claude Code, Cursor, etc.) and inject a file index into
+                      CLAUDE.md and/or AGENTS.md`);
+  process.exit(command ? 1 : 0);
+}
+
+// Resolve version from own package.json
+const require = createRequire(import.meta.url);
+const pkg = require('../package.json');
+const version = pkg.version;
+
+// Determine git ref: try tag first, fallback to master
+function tagExists(tag) {
+  try {
+    execFileSync('git', ['ls-remote', '--tags', '--exit-code', GITHUB_REPO, `refs/tags/${tag}`], {
+      stdio: 'pipe',
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+const tag = `v${version}`;
+const ref = tagExists(tag) ? tag : 'master';
+if (ref === 'master') {
+  console.log(`Tag ${tag} not found on remote, falling back to master branch.`);
+}
+
+// Clone docs using sparse-checkout into a temp directory
+const tempDir = mkdtempSync(join(tmpdir(), 'unchained-docs-'));
+console.log(`Cloning docs from ${ref} using sparse-checkout ...`);
+try {
+  execFileSync(
+    'git',
+    [
+      'clone',
+      '--filter=blob:none',
+      '--no-checkout',
+      '--depth',
+      '1',
+      '--branch',
+      ref,
+      GITHUB_REPO,
+      tempDir,
+    ],
+    { stdio: 'inherit' },
+  );
+  execFileSync('git', ['-C', tempDir, 'sparse-checkout', 'set', DOCS_SUBPATH], {
+    stdio: 'inherit',
+  });
+  execFileSync('git', ['-C', tempDir, 'checkout'], { stdio: 'inherit' });
+} catch {
+  rmSync(tempDir, { recursive: true, force: true });
+  console.error('Failed to clone docs repository.');
+  process.exit(1);
+}
+
+// Copy docs/docs/ contents to .unchained-docs/
+const sourceDir = join(tempDir, DOCS_SUBPATH);
+if (!existsSync(sourceDir)) {
+  rmSync(tempDir, { recursive: true, force: true });
+  console.error(`Docs directory not found at ${DOCS_SUBPATH} in the repository.`);
+  process.exit(1);
+}
+
+rmSync(DOCS_DIR, { recursive: true, force: true });
+cpSync(sourceDir, DOCS_DIR, { recursive: true });
+rmSync(tempDir, { recursive: true, force: true });
+
+// Scan for markdown files
+const markdownsByDir = Map.groupBy(
+  readdirSync(DOCS_DIR, { withFileTypes: true, recursive: true }).filter(
+    (e) => e.isFile() && (e.name.endsWith('.md') || e.name.endsWith('.mdx')),
+  ),
+  (e) => relative(DOCS_DIR, e.parentPath) || '.',
+);
+
+const fileCount = [...markdownsByDir.values()].flat().length;
+console.log(`Found ${fileCount} markdown files in .unchained-docs/`);
+
+// Build compact pipe-delimited index
+const indexSnippet = [
+  INDEX_START,
+  [
+    `[Unchained Engine v${version} Docs Index]`,
+    'root: ./.unchained-docs',
+    'Search these docs before answering Unchained questions.',
+    'If docs missing, run: npx --package @unchainedshop/platform unchained download-llm-docs',
+    ...[...markdownsByDir]
+      .sort(([a], [b]) => a.localeCompare(b))
+      .map(
+        ([dir, entries]) =>
+          `${dir}:{${entries
+            .map((e) => e.name)
+            .sort()
+            .join(',')}}`,
+      ),
+  ].join('|'),
+  INDEX_END,
+].join('');
+
+// Upsert index into target files
+function upsertIndex(filePath) {
+  const content = readFileSync(filePath, 'utf-8');
+  const [before, ...afterParts] = content.split(INDEX_START);
+  const after =
+    afterParts.length > 0
+      ? afterParts.join(INDEX_START).split(INDEX_END).slice(1).join(INDEX_END)
+      : undefined;
+
+  writeFileSync(
+    filePath,
+    after !== undefined ? before + indexSnippet + after : `${content.trimEnd()}\n${indexSnippet}\n`,
+  );
+  console.log(`Updated ${relative(process.cwd(), filePath)} with docs index.`);
+}
+
+const claudeMdPath = join(process.cwd(), 'CLAUDE.md');
+const agentsMdPath = join(process.cwd(), 'AGENTS.md');
+const legacyAgentsMdPath = join(process.cwd(), 'agents.md');
+const claudeExists = existsSync(claudeMdPath);
+const agentsExists = existsSync(agentsMdPath);
+const legacyAgentsExists = !agentsExists && existsSync(legacyAgentsMdPath);
+
+if (claudeExists) upsertIndex(claudeMdPath);
+if (agentsExists) upsertIndex(agentsMdPath);
+if (legacyAgentsExists) upsertIndex(legacyAgentsMdPath);
+
+if (!claudeExists && !agentsExists && !legacyAgentsExists) {
+  writeFileSync(claudeMdPath, `${indexSnippet}\n`);
+  console.log('Created CLAUDE.md with docs index.');
+}
+
+// Remind about .gitignore
+console.log('\nDone! Remember to add .unchained-docs to your .gitignore.');

package/lib/migrations/createMigrationRunner.js

@@ -35,14 +35,8 @@ export const createMigrationRunner = ({ currentId, logger = console, migrationRe
             .map(this.operationFactory('up'));
     },
     async run() {
-        try {
-            const migrations = this.migrateToLatest();
-            const mostRecentId = await migrations.reduce((idPromise, migration) => Promise.resolve(idPromise).then(migration), currentId);
-            return [mostRecentId, migrations.length];
-        }
-        catch (e) {
-            logger.error(`Migration failed: ${e.name} - ${e.message}`);
-            return [e.migrationId, null];
-        }
+        const migrations = this.migrateToLatest();
+        const mostRecentId = await migrations.reduce((idPromise, migration) => Promise.resolve(idPromise).then(migration), currentId);
+        return [mostRecentId, migrations.length];
     },
 });

package/lib/migrations/runMigrations.js

@@ -32,15 +32,10 @@ export const runMigrations = async ({ migrationRepository, logger = createLogger
         unchainedAPI,
     });
     const [lastMigrationId, operationCount] = await runner.run();
-    if (operationCount !== null) {
-        if (operationCount > 0) {
-            logger.info(`All ${operationCount} migrations completed with most recent id: ${lastMigrationId}`);
-        }
-        else {
-            logger.debug(`No migrations run, already at latest id: ${currentId}`);
-        }
+    if (operationCount > 0) {
+        logger.info(`All ${operationCount} migrations completed with most recent id: ${lastMigrationId}`);
     }
     else {
-        logger.warn(`Some migrations failed, last successful id: ${lastMigrationId}`);
+        logger.debug(`No migrations run, already at latest id: ${currentId}`);
     }
 };

package/lib/setup/setupWorkqueue.js

@@ -12,7 +12,14 @@ export const queueWorkers = [];
 export async function setupWorkqueue({ unchainedAPI, migrationRepository, ...workQueueOptions }) {
     if (workQueueOptions.disableWorker || UNCHAINED_DISABLE_WORKER)
         return;
-    await runMigrations({ migrationRepository, unchainedAPI });
+    try {
+        await runMigrations({ migrationRepository, unchainedAPI });
+    }
+    catch (error) {
+        logger.error('Migration failed; continuing startup', {
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
     (workQueueOptions?.enabledQueueManagers || defaultQueueManagers).forEach((f) => {
         const handler = f.actions(workQueueOptions, unchainedAPI);
         queueWorkers.push(handler);

package/lib/templates/order-parser/getOrderSummaryData.js

@@ -21,7 +21,7 @@ export const getOrderSummaryData = async (order, params, context) => {
     const deliveryProvider = await modules.delivery.findProvider({
         deliveryProviderId: orderDelivery.deliveryProviderId,
     });
-    const deliveryAddress = ch.addressToString(orderDelivery?.context?.deliveryAddress || order.billingAddress);
+    const deliveryAddress = ch.addressToString(orderDelivery?.context?.address || orderDelivery?.context?.deliveryAddress || order.billingAddress);
     const billingAddress = ch.addressToString(order.billingAddress);
     const orderPricing = OrderPricingSheet({
         calculation: order.calculation,

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "@unchainedshop/platform",
   "description": "Complete e-commerce platform bundle for the Unchained Engine",
-  "version": "5.0.0-alpha.5",
+  "version": "5.0.0-alpha.8",
   "main": "lib/platform-index.js",
   "types": "lib/platform-index.d.ts",
   "type": "module",
+  "bin": {
+    "unchained": "./bin/unchained.js"
+  },
   "scripts": {
     "clean": "tsc -b --clean",
     "build": "tsc -b",
@@ -34,18 +37,18 @@
   },
   "homepage": "https://github.com/unchainedshop/unchained#readme",
   "engines": {
-    "node": ">=24.0.0",
+    "node": ">=26.0.0",
     "npm": ">=10.0.0"
   },
   "dependencies": {
-    "@unchainedshop/api": "^5.0.0-alpha.5",
-    "@unchainedshop/core": "^5.0.0-alpha.5",
-    "@unchainedshop/events": "^5.0.0-alpha.5",
-    "@unchainedshop/logger": "^5.0.0-alpha.5",
-    "@unchainedshop/mongodb": "^5.0.0-alpha.5",
-    "@unchainedshop/plugins": "^5.0.0-alpha.5",
-    "@unchainedshop/roles": "^5.0.0-alpha.5",
-    "@unchainedshop/utils": "^5.0.0-alpha.5"
+    "@unchainedshop/api": "^5.0.0-alpha.8",
+    "@unchainedshop/core": "^5.0.0-alpha.8",
+    "@unchainedshop/events": "^5.0.0-alpha.8",
+    "@unchainedshop/logger": "^5.0.0-alpha.8",
+    "@unchainedshop/mongodb": "^5.0.0-alpha.8",
+    "@unchainedshop/plugins": "^5.0.0-alpha.8",
+    "@unchainedshop/roles": "^5.0.0-alpha.8",
+    "@unchainedshop/utils": "^5.0.0-alpha.8"
   },
   "devDependencies": {
     "@types/node": "^26.2.0",