@zintrust/core 0.4.24 → 0.4.27

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zintrust/core",
-  "version": "0.4.24",
+  "version": "0.4.27",
   "description": "Production-grade TypeScript backend framework for JavaScript",
   "homepage": "https://zintrust.com",
   "repository": {
@@ -50,7 +50,7 @@
   },
   "dependencies": {
     "@cloudflare/containers": "^0.1.1",
-    "@zintrust/workers": "^0.4.0",
+    "@zintrust/workers": "^0.4.25",
     "bcryptjs": "^3.0.3",
     "bullmq": "^5.71.0",
     "chalk": "^5.6.2",

package/src/boot/bootstrap.js

@@ -10,6 +10,7 @@ import { Env } from '../config/env.js';
 import { Logger } from '../config/logger.js';
 import { ErrorFactory } from '../exceptions/ZintrustError.js';
 import { ProjectRuntime } from '../runtime/ProjectRuntime.js';
+import { WorkerProjectAutoImports } from '../runtime/WorkerProjectAutoImports.js';
 import { loadWorkersModule } from '../runtime/WorkersModule.js';
 let appInstance;
 let serverInstance;
@@ -165,6 +166,10 @@ async function useWorkerStarter() {
     // Initialize worker management system
     let workerInit = null;
     try {
+        const projectWorkerEntrypoint = await WorkerProjectAutoImports.tryImportProjectWorkerEntrypoint();
+        if (!projectWorkerEntrypoint.ok && projectWorkerEntrypoint.reason === 'import-failed') {
+            Logger.warn(`Project worker entrypoint import failed: ${projectWorkerEntrypoint.errorMessage ?? 'Unknown error'}`);
+        }
         const workers = await loadWorkersModule();
         if (workers?.WorkerInit !== undefined) {
             workerInit = workers.WorkerInit;

package/src/cli/commands/InitContainerCommand.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"InitContainerCommand.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/InitContainerCommand.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,KAAK,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAyKlE,eAAO,MAAM,oBAAoB;cACrB,YAAY;EAkBtB,CAAC"}
+{"version":3,"file":"InitContainerCommand.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/InitContainerCommand.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,KAAK,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAqSlE,eAAO,MAAM,oBAAoB;cACrB,YAAY;EAqBtB,CAAC"}

package/src/cli/commands/InitContainerCommand.js

@@ -7,12 +7,13 @@ const DOCKER_COMPOSE_WORKERS_TEMPLATE = `name: zintrust-workers
 
 services:
   # Workers/Jobs API Service (Port 7772)
-  # Exposes the Workers API to create/manage jobs
+  # Exposes the Workers API to create/manage jobs using the project worker overlay image.
   workers-api:
-    image: \${WORKERS_IMAGE:-zintrust/zintrust-workers:latest}
+    image: \${WORKERS_IMAGE:-zintrust-workers-local:latest}
     build:
       context: .
-      dockerfile: Dockerfile
+      dockerfile: Dockerfile.workers
+      target: runtime
     command: ["node", "--experimental-specifier-resolution=node", "dist/src/boot/bootstrap.js"]
     environment:
       # Runtime
@@ -26,7 +27,6 @@ services:
       - APP_KEY=\${APP_KEY}
       - ENCRYPTION_CIPHER=\${ENCRYPTION_CIPHER:-aes-256-cbc}
       - LOG_LEVEL=\${LOG_LEVEL:-info}
-      - ZINTRUST_PROJECT_ROOT=/app/dist
 
       # Workers & Queue
       - WORKER_ENABLED=\${WORKER_ENABLED:-false}
@@ -96,23 +96,148 @@ services:
     ports:
       - '7772:7772'
 
+  # Dedicated background worker runner.
+  # Uses the same project overlay image but boots the worker target.
+  worker-runner:
+    image: \${WORKERS_RUNNER_IMAGE:-zintrust-workers-local:latest}
+    build:
+      context: .
+      dockerfile: Dockerfile.workers
+      target: worker
+    environment:
+      # Runtime
+      - NODE_ENV=\${NODE_ENV:-development}
+      - HOST=0.0.0.0
+
+      # Application
+      - APP_NAME=\${APP_NAME:-ZinTrust}
+      - APP_KEY=\${APP_KEY}
+      - ENCRYPTION_CIPHER=\${ENCRYPTION_CIPHER:-aes-256-cbc}
+      - LOG_LEVEL=\${LOG_LEVEL:-info}
+
+      # Workers & Queue
+      - DOCKER_WORKER=true
+      - WORKER_ENABLED=\${WORKER_ENABLED:-true}
+      - WORKER_AUTO_START=\${WORKER_AUTO_START:-true}
+      - QUEUE_ENABLED=true
+      - QUEUE_MONITOR_ENABLED=\${QUEUE_MONITOR_ENABLED:-false}
+      - QUEUE_MONITOR_MIDDLEWARE=\${QUEUE_MONITOR_MIDDLEWARE:-}
+      - WORKER_PERSISTENCE_DRIVER=\${WORKER_PERSISTENCE_DRIVER:-redis}
+      - WORKER_PERSISTENCE_DB_CONNECTION=\${WORKER_PERSISTENCE_DB_CONNECTION:-mysql}
+      - WORKER_PERSISTENCE_REDIS_KEY_PREFIX=\${WORKER_PERSISTENCE_REDIS_KEY_PREFIX}
+      - QUEUE_DRIVER=\${QUEUE_DRIVER:-redis}
+      - QUEUE_CONNECTION=\${QUEUE_CONNECTION:-redis}
+      - CACHE_DRIVER=\${CACHE_DRIVER:-redis}
+
+      # Redis
+      - REDIS_HOST=\${DOCKER_REDIS_HOST:-host.docker.internal}
+      - REDIS_PORT=\${REDIS_PORT:-6379}
+      - REDIS_PASSWORD=\${REDIS_PASSWORD}
+      - REDIS_QUEUE_DB=\${REDIS_QUEUE_DB:-1}
+
+      # Database
+      - DB_CONNECTION=\${DB_CONNECTION:-postgres}
+      - DB_HOST=\${DOCKER_DB_HOST:-host.docker.internal}
+      - DB_PORT=\${DB_PORT:-3306}
+      - DB_DATABASE=\${DB_DATABASE:-zintrust}
+      - DB_USERNAME=\${DB_USERNAME:-zintrust}
+      - DB_PASSWORD=\${DB_PASSWORD:-}
+
+      # SMTP Mail
+      - MAIL_DRIVER=\${MAIL_DRIVER:-smtp}
+      - MAIL_CONNECTION=\${MAIL_CONNECTION:-smtp}
+      - MAIL_HOST=\${MAIL_HOST}
+      - MAIL_PORT=\${MAIL_PORT:-587}
+      - MAIL_SECURE=\${MAIL_SECURE:-false}
+      - MAIL_USERNAME=\${MAIL_USERNAME}
+      - MAIL_PASSWORD=\${MAIL_PASSWORD}
+      - MAIL_FROM_ADDRESS=\${MAIL_FROM_ADDRESS}
+      - MAIL_FROM_NAME=\${MAIL_FROM_NAME:-ZinTrust}
+
+      # PostgreSQL
+      - DB_PORT_POSTGRESQL=\${DB_PORT_POSTGRESQL:-5432}
+      - DB_DATABASE_POSTGRESQL=\${DB_DATABASE_POSTGRESQL:-zintrust}
+      - DB_USERNAME_POSTGRESQL=\${DB_USERNAME_POSTGRESQL:-zintrust}
+      - DB_PASSWORD_POSTGRESQL=\${DB_PASSWORD_POSTGRESQL:-}
+
+      # MySQL
+      - DB_PORT_MYSQL=\${DB_PORT_MYSQL:-3306}
+      - DB_DATABASE_MYSQL=\${DB_DATABASE_MYSQL:-zintrust}
+      - DB_USERNAME_MYSQL=\${DB_USERNAME_MYSQL:-zintrust}
+      - DB_PASSWORD_MYSQL=\${DB_PASSWORD_MYSQL:-}
+
+      # Cloudflare D1
+      - D1_DATABASE_ID=\${D1_DATABASE_ID}
+      - D1_ACCOUNT_ID=\${D1_ACCOUNT_ID}
+      - D1_API_TOKEN=\${D1_API_TOKEN}
+      - D1_REMOTE_URL=\${D1_REMOTE_URL}
+      - D1_REMOTE_KEY_ID=\${D1_REMOTE_KEY_ID}
+      - D1_REMOTE_SECRET=\${D1_REMOTE_SECRET}
+
+      # Cloudflare KV
+      - KV_NAMESPACE_ID=\${KV_NAMESPACE_ID}
+      - KV_ACCOUNT_ID=\${KV_ACCOUNT_ID}
+      - KV_API_TOKEN=\${KV_API_TOKEN}
+      - KV_REMOTE_URL=\${KV_REMOTE_URL}
+      - KV_REMOTE_KEY_ID=\${KV_REMOTE_KEY_ID}
+      - KV_REMOTE_SECRET=\${KV_REMOTE_SECRET}
+
 `;
-const DOCKERFILE_TEMPLATE = String.raw `FROM zintrust/zintrust:latest AS runtime
+const DOCKERFILE_TEMPLATE = String.raw `# Multi-stage worker overlay image.
+#
+# This compiles the local ZinTrust app first, then copies only the compiled worker-related
+# artifacts onto the published zintrust/zintrust runtime image.
+
+FROM node:20-alpine AS project-build
+
+WORKDIR /project
+
+ENV NPM_CONFIG_CACHE=/root/.npm
+ENV NPM_CONFIG_PREFER_OFFLINE=true
+
+RUN apk upgrade --no-cache \
+  && apk add --no-cache g++ git make python3
+
+COPY package.json package-lock.json ./
+
+RUN --mount=type=cache,target=/root/.npm,id=zintrust-worker-overlay-npm-cache,sharing=locked \
+  npm config set fetch-retries 5 \
+    && npm config set fetch-retry-mintimeout 20000 \
+    && npm config set fetch-retry-maxtimeout 120000 \
+    && npm ci
+
+COPY . .
+
+# Fresh projects always ship npm run build; do not depend on framework-internal build variants.
+RUN --mount=type=cache,target=/root/.npm,id=zintrust-worker-overlay-npm-cache,sharing=locked npm run build
+
+FROM project-build AS worker-overlay
+
+RUN set -eu; \
+  overlay_root=/overlay; \
+  mkdir -p "$overlay_root/dist"; \
+  if [ -d /project/dist/app ]; then cp -R /project/dist/app "$overlay_root/dist/app"; fi; \
+  mkdir -p "$overlay_root/dist/src"; \
+  if [ -f /project/dist/src/zintrust.workers.js ]; then cp /project/dist/src/zintrust.workers.js "$overlay_root/dist/src/zintrust.workers.js"; fi; \
+  if [ -f /project/dist/src/zintrust.workers.js.map ]; then cp /project/dist/src/zintrust.workers.js.map "$overlay_root/dist/src/zintrust.workers.js.map"; fi
+
+FROM zintrust/zintrust:latest AS runtime
 
 WORKDIR /app
 
-ENV NODE_ENV=production
-ENV PORT=7772
-ENV HOST=0.0.0.0
+COPY --from=worker-overlay --chown=nodejs:nodejs /overlay/dist/ /app/dist/
 
-USER nodejs
+FROM runtime AS worker
 
-HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
-  CMD node -e "require('node:http').get('http://localhost:7772/health', (r) => {if (r.statusCode !== 200) throw new Error(r.statusCode)})"
+ENV DOCKER_WORKER=true
+ENV WORKER_ENABLED=true
+ENV WORKER_AUTO_START=true
+ENV QUEUE_ENABLED=true
+ENV PORT=0
 
-EXPOSE 7772
+HEALTHCHECK NONE
 
-CMD ["node", "dist/src/boot/bootstrap.js"]
+CMD ["node", "dist/bin/zin.js", "worker:start-all"]
 `;
 const backupSuffix = () => new Date().toISOString().replaceAll(/[:.]/g, '-');
 const backupFileIfExists = (filePath) => {
@@ -138,19 +263,18 @@ async function writeDockerComposeFile(cwd) {
     }
 }
 async function writeDockerfile(cwd) {
-    const dockerfilePath = join(cwd, 'Dockerfile');
+    const dockerfilePath = join(cwd, 'Dockerfile.workers');
     let shouldWrite = true;
     if (existsSync(dockerfilePath)) {
-        // Only ask if it's different or just generic confirm? Let's just ask.
-        shouldWrite = await PromptHelper.confirm('Dockerfile already exists. Overwrite with standard worker configuration?', false);
+        shouldWrite = await PromptHelper.confirm('Dockerfile.workers already exists. Overwrite with the ZinTrust worker overlay image?', false);
     }
     if (shouldWrite) {
         backupFileIfExists(dockerfilePath);
         writeFileSync(dockerfilePath, DOCKERFILE_TEMPLATE);
-        Logger.info('✅ Created Dockerfile');
+        Logger.info('✅ Created Dockerfile.workers');
     }
     else {
-        Logger.info('Skipped Dockerfile');
+        Logger.info('Skipped Dockerfile.workers');
     }
 }
 export const InitContainerCommand = Object.freeze({
@@ -165,7 +289,8 @@ export const InitContainerCommand = Object.freeze({
                 await writeDockerComposeFile(cwd);
                 await writeDockerfile(cwd);
                 Logger.info('✅ Container worker scaffolding complete.');
-                Logger.info('Run with: docker-compose -f docker-compose.workers.yml up');
+                Logger.info('Run with: docker compose -f docker-compose.workers.yml up');
+                Logger.info('Build worker runner with: docker build -f Dockerfile.workers --target worker .');
                 await Promise.resolve();
             },
         });

package/src/cli/commands/MigrateWorkerCommand.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"MigrateWorkerCommand.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/MigrateWorkerCommand.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAkB,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAiNrE,eAAO,MAAM,oBAAoB;cACrB,YAAY;EAUtB,CAAC"}
+{"version":3,"file":"MigrateWorkerCommand.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/MigrateWorkerCommand.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAkB,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAuNrE,eAAO,MAAM,oBAAoB;cACrB,YAAY;EAUtB,CAAC"}

package/src/cli/commands/MigrateWorkerCommand.js

@@ -15,7 +15,12 @@ const isBuiltInDriver = (driver) => driver === 'sqlite' ||
     driver === 'sqlserver' ||
     driver === 'd1' ||
     driver === 'd1-remote';
-const getWorkerPersistenceConnectionName = () => {
+const getWorkerPersistenceConnectionName = (optionValue) => {
+    if (typeof optionValue === 'string') {
+        const trimmed = optionValue.trim();
+        if (trimmed.length > 0)
+            return trimmed;
+    }
     if (typeof process === 'undefined')
         return 'default';
     const raw = process.env?.['WORKER_PERSISTENCE_DB_CONNECTION'];
@@ -31,6 +36,7 @@ const addOptions = (command) => {
         .option('--step <number>', 'Number of batches to rollback (use with --rollback)', '1')
         .option('--force', 'Skip production confirmation (allow unsafe operations in production)')
         .option('--all', 'Run migrations for all configured database connections')
+        .option('--connection <name>', 'Use a specific database connection for worker migrations')
         .option('--no-interactive', 'Disable interactive prompts (useful for CI/CD)');
 };
 const getInteractive = (options) => options['interactive'] !== false;
@@ -137,7 +143,7 @@ const executeMigrateWorker = async (options, cmd) => {
         }
     }
     else {
-        const selected = getWorkerPersistenceConnectionName();
+        const selected = getWorkerPersistenceConnectionName(options['connection']);
         const hasSelected = selected.length > 0;
         const connections = databaseConfig.connections;
         const configured = hasSelected ? connections[selected] : undefined;

package/src/cli/commands/WorkerCommands.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"WorkerCommands.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/WorkerCommands.ts"],"names":[],"mappings":"AACA;;;GAGG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAgiBrD;;GAEG;AACH,eAAO,MAAM,cAAc;mCApYS,YAAY;qCA4CV,YAAY;oCAiDb,YAAY;uCAkFT,YAAY;mCA0FhB,YAAY;sCAgCT,YAAY;sCAgCZ,YAAY;CAmElD,CAAC"}
+{"version":3,"file":"WorkerCommands.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/WorkerCommands.ts"],"names":[],"mappings":"AACA;;;GAGG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AA0lBrD;;GAEG;AACH,eAAO,MAAM,cAAc;mCAtaS,YAAY;qCA4CV,YAAY;oCAiDb,YAAY;uCAqHT,YAAY;mCAyFhB,YAAY;sCAgCT,YAAY;sCAgCZ,YAAY;CAmElD,CAAC"}

package/src/cli/commands/WorkerCommands.js

@@ -7,14 +7,26 @@ import { ErrorFactory } from '../../exceptions/ZintrustError.js';
 import { BaseCommand } from '../BaseCommand.js';
 import { Env } from '../../config/env.js';
 import { Logger } from '../../config/logger.js';
+import { WorkerProjectAutoImports } from '../../runtime/WorkerProjectAutoImports.js';
 import { loadWorkersModule as loadWorkersRuntimeModule } from '../../runtime/WorkersModule.js';
 // Lazy initialization to prevent temporal dead zone issues
 let WorkerFactory;
 let WorkerRegistry;
 let HealthMonitor;
 let ResourceMonitor;
+let workerProjectEntrypointAttempted = false;
+const ensureProjectWorkerEntrypointLoaded = async () => {
+    if (workerProjectEntrypointAttempted)
+        return;
+    workerProjectEntrypointAttempted = true;
+    const result = await WorkerProjectAutoImports.tryImportProjectWorkerEntrypoint();
+    if (!result.ok && result.reason === 'import-failed') {
+        Logger.warn(`Project worker entrypoint import failed: ${result.errorMessage ?? 'Unknown error'}`);
+    }
+};
 const loadWorkersModule = async () => {
     try {
+        await ensureProjectWorkerEntrypointLoaded();
         return (await loadWorkersRuntimeModule());
     }
     catch (error) {
@@ -232,6 +244,32 @@ const isRegisteredWorkerRunning = async (workerLike) => {
     const isPaused = typeof pausedFn === 'function' ? pausedFn() : false;
     return isRunning && !isPaused;
 };
+const resolveAutoStartWorkerNames = async (factory, workersModule) => {
+    const persistedRecords = await factory.listPersistedRecords();
+    const fileRecords = typeof factory.listFileBackedRecords === 'function'
+        ? await factory.listFileBackedRecords()
+        : [];
+    if (typeof workersModule.selectAutoStartNames === 'function') {
+        return workersModule.selectAutoStartNames(persistedRecords, fileRecords, Logger.warn);
+    }
+    const persistedNames = persistedRecords
+        .filter((record) => record.activeStatus !== false && record.autoStart === true)
+        .map((record) => record.name);
+    if (persistedNames.length > 0) {
+        return { names: persistedNames, source: 'persisted' };
+    }
+    const seen = new Set();
+    const fileNames = [];
+    for (const record of fileRecords) {
+        if (record.activeStatus === false || record.autoStart !== true)
+            continue;
+        if (seen.has(record.name))
+            continue;
+        seen.add(record.name);
+        fileNames.push(record.name);
+    }
+    return { names: fileNames, source: fileNames.length > 0 ? 'file' : 'none' };
+};
 /**
  * Worker Start All Command
  */
@@ -244,17 +282,19 @@ const createWorkerStartAllCommand = () => {
                 return;
             }
             const factory = await getWorkerFactory();
-            const records = await factory.listPersistedRecords();
-            const autoStartRecords = records.filter((record) => record.activeStatus !== false && record.autoStart === true);
-            const workers = autoStartRecords.map((record) => record.name);
+            const workersModule = await loadWorkersModule();
+            const { names: workers, source } = await resolveAutoStartWorkerNames(factory, workersModule);
             if (workers.length === 0) {
-                Logger.info('No auto-start eligible persisted workers found.');
+                Logger.info('No auto-start eligible persisted or file-backed workers found.');
                 return;
             }
-            const discoveredWorkers = await pollForPersistedWorkers(factory);
-            const eligibleWorkers = workers.filter((name) => discoveredWorkers.includes(name));
+            let eligibleWorkers = workers;
+            if (source === 'persisted') {
+                const discoveredWorkers = await pollForPersistedWorkers(factory);
+                eligibleWorkers = workers.filter((name) => discoveredWorkers.includes(name));
+            }
             if (eligibleWorkers.length === 0) {
-                Logger.info('No auto-start eligible workers are currently persisted.');
+                Logger.info('No auto-start eligible workers are currently available.');
                 return;
             }
             const results = await Promise.all(eligibleWorkers.map(async (name) => {

package/src/index.js

@@ -1,11 +1,11 @@
 /**
- * @zintrust/core v0.4.24
+ * @zintrust/core v0.4.27
  *
  * ZinTrust Framework - Production-Grade TypeScript Backend
  * Built for performance, type safety, and exceptional developer experience
  *
  * Build Information:
- *   Built: 2026-03-27T14:32:35.640Z
+ *   Built: 2026-03-28T14:15:33.465Z
  *   Node: >=20.0.0
  *   License: MIT
  *
@@ -21,7 +21,7 @@
  * Available at runtime for debugging and health checks
  */
 export const ZINTRUST_VERSION = '0.1.41';
-export const ZINTRUST_BUILD_DATE = '2026-03-27T14:32:35.607Z'; // Replaced during build
+export const ZINTRUST_BUILD_DATE = '2026-03-28T14:15:33.427Z'; // Replaced during build
 export { Application } from './boot/Application.js';
 export { AwsSigV4 } from './common/index.js';
 export { SignedRequest } from './security/SignedRequest.js';

package/src/runtime/WorkerProjectAutoImports.d.ts

@@ -0,0 +1,14 @@
+type ImportResult = {
+    ok: true;
+    loadedPath: string;
+} | {
+    ok: false;
+    loadedPath?: string;
+    reason: 'not-found' | 'import-failed';
+    errorMessage?: string;
+};
+export declare const WorkerProjectAutoImports: Readonly<{
+    tryImportProjectWorkerEntrypoint(): Promise<ImportResult>;
+}>;
+export {};
+//# sourceMappingURL=WorkerProjectAutoImports.d.ts.map

package/src/runtime/WorkerProjectAutoImports.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WorkerProjectAutoImports.d.ts","sourceRoot":"","sources":["../../../src/runtime/WorkerProjectAutoImports.ts"],"names":[],"mappings":"AAKA,KAAK,YAAY,GACb;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GAChC;IACE,EAAE,EAAE,KAAK,CAAC;IACV,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,WAAW,GAAG,eAAe,CAAC;IACtC,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC;AA6BN,eAAO,MAAM,wBAAwB;wCACO,OAAO,CAAC,YAAY,CAAC;EA0C/D,CAAC"}

package/src/runtime/WorkerProjectAutoImports.js

@@ -0,0 +1,63 @@
+import { Logger } from '../config/logger.js';
+import { existsSync } from '../node-singletons/fs.js';
+import * as path from '../node-singletons/path.js';
+import { pathToFileURL } from '../node-singletons/url.js';
+const resolveProjectRoot = () => {
+    const projectRoot = String(process.env['ZINTRUST_PROJECT_ROOT'] ?? '').trim();
+    return projectRoot.length > 0 ? projectRoot : process.cwd();
+};
+const getCandidates = (projectRoot) => {
+    return [
+        path.join(projectRoot, 'src', 'zintrust.workers.ts'),
+        path.join(projectRoot, 'dist', 'src', 'zintrust.workers.js'),
+        path.join(projectRoot, 'src', 'zintrust.workers.js'),
+    ];
+};
+const invokeWorkerEntrypoint = async (mod) => {
+    let registerWorkers = null;
+    if (typeof mod['registerWorkers'] === 'function') {
+        registerWorkers = mod['registerWorkers'];
+    }
+    else if (typeof mod['default'] === 'function') {
+        registerWorkers = mod['default'];
+    }
+    if (registerWorkers !== null) {
+        await registerWorkers();
+    }
+};
+export const WorkerProjectAutoImports = Object.freeze({
+    async tryImportProjectWorkerEntrypoint() {
+        const candidates = getCandidates(resolveProjectRoot()).filter((candidate) => existsSync(candidate));
+        if (candidates.length === 0) {
+            return { ok: false, reason: 'not-found' };
+        }
+        let firstFailure = null;
+        for (const candidate of candidates) {
+            try {
+                // eslint-disable-next-line no-await-in-loop
+                const mod = (await import(pathToFileURL(candidate).href));
+                // eslint-disable-next-line no-await-in-loop
+                await invokeWorkerEntrypoint(mod);
+                return { ok: true, loadedPath: candidate };
+            }
+            catch (error) {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                Logger.debug('[workers] Project worker entrypoint import failed', {
+                    candidate,
+                    errorMessage,
+                });
+                firstFailure ??= {
+                    ok: false,
+                    loadedPath: candidate,
+                    reason: 'import-failed',
+                    errorMessage,
+                };
+            }
+        }
+        return (firstFailure ?? {
+            ok: false,
+            reason: 'import-failed',
+            errorMessage: 'All worker entrypoint candidates failed',
+        });
+    },
+});

package/src/templates/project/basic/app/Workers/ExampleWorker.ts.tpl

@@ -0,0 +1,17 @@
+import { Logger } from '@zintrust/core';
+
+export const workerDefinition = Object.freeze({
+  name: 'example-worker',
+  queueName: 'example-worker',
+  version: '1.0.0',
+  autoStart: false,
+  activeStatus: true,
+  concurrency: 1,
+  processorSpec: 'app/Workers/ExampleWorker.ts',
+});
+
+export async function ZinTrustProcessor(payload: unknown): Promise<void> {
+  Logger.info('Example worker processed job', { payload });
+}
+
+export default ZinTrustProcessor;

package/src/templates/project/basic/package.json.tpl

@@ -12,6 +12,7 @@
   },
   "dependencies": {
     "@zintrust/core": "^{{coreVersion}}",
+    "@zintrust/d1-migrator": "^0.4.6",
     "@zintrust/governance": "^0.1.25"
   },
   "devDependencies": {

package/src/templates/project/basic/src/zintrust.workers.ts.tpl

@@ -0,0 +1,11 @@
+/**
+ * Optional ZinTrust worker bootstrap.
+ *
+ * Docker worker containers and worker CLI commands auto-load this file when it exists.
+ * For simple code-first workers that export `workerDefinition`, you usually do not need to
+ * update this file after scaffolding. Keep it for advanced pre-registration or grouped imports.
+ */
+
+import '@app/Workers/ExampleWorker';
+
+export const __zintrustGeneratedWorkerStub = 'zintrust.workers.ts';