@signal24/dk-server-foundation 26.213.615

package/src/cli/dksf-dev.ts

@@ -0,0 +1,363 @@
+#!/usr/bin/env node
+
+import { ChildProcess, spawn, spawnSync } from 'child_process';
+import { existsSync, readFileSync, writeFileSync, unlinkSync, rmSync } from 'fs';
+import { createHash } from 'crypto';
+import { tmpdir } from 'os';
+import { join, dirname } from 'path';
+import { setTimeout as sleep } from 'timers/promises';
+
+process.env.APP_ENV = process.env.APP_ENV || 'development';
+
+function findProjectRoot(): string {
+    let dir = process.cwd();
+    while (true) {
+        if (existsSync(join(dir, 'package.json'))) return dir;
+        const parent = dirname(dir);
+        if (parent === dir) {
+            console.error('Could not find package.json in any parent directory');
+            process.exit(1);
+        }
+        dir = parent;
+    }
+}
+
+const projectDir = findProjectRoot();
+const tscPath = require.resolve('typescript/bin/tsc');
+
+// --- Dev state coordination ---
+
+const projectHash = createHash('md5').update(projectDir).digest('hex').substring(0, 12);
+const devLockFile = join(tmpdir(), `dksf-dev-${projectHash}.lock`);
+const devStateFile = join(tmpdir(), `dksf-dev-${projectHash}.json`);
+
+interface DevState {
+    ready: boolean;
+    pids: number[];
+}
+
+function isPidAlive(pid: number): boolean {
+    try {
+        process.kill(pid, 0);
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+function readDevState(): DevState | null {
+    try {
+        return JSON.parse(readFileSync(devStateFile, 'utf-8'));
+    } catch {
+        return null;
+    }
+}
+
+function writeDevState(state: DevState): void {
+    writeFileSync(devStateFile, JSON.stringify(state));
+}
+
+function registerDevPid(): void {
+    const state = readDevState() ?? { ready: true, pids: [] };
+    state.pids = state.pids.filter(isPidAlive);
+    if (!state.pids.includes(process.pid)) state.pids.push(process.pid);
+    writeDevState(state);
+}
+
+function unregisterDevPid(): void {
+    const state = readDevState();
+    if (!state) return;
+    state.pids = state.pids.filter(p => p !== process.pid && isPidAlive(p));
+    if (state.pids.length === 0) {
+        try {
+            unlinkSync(devStateFile);
+        } catch {
+            // ignore
+        }
+    } else {
+        writeDevState(state);
+    }
+}
+
+function isDevRunning(): boolean {
+    const state = readDevState();
+    return !!state?.ready && state.pids.some(isPidAlive);
+}
+
+function tryAcquireBuildLock(retries = 5): boolean {
+    if (retries <= 0) return false;
+    try {
+        writeFileSync(devLockFile, String(process.pid), { flag: 'wx' });
+        return true;
+    } catch (err: unknown) {
+        if ((err as NodeJS.ErrnoException).code !== 'EEXIST') throw err;
+        try {
+            const pid = parseInt(readFileSync(devLockFile, 'utf-8'));
+            if (!isPidAlive(pid)) {
+                unlinkSync(devLockFile);
+                return tryAcquireBuildLock(retries - 1);
+            }
+        } catch {
+            return tryAcquireBuildLock(retries - 1);
+        }
+        return false;
+    }
+}
+
+function releaseBuildLock(): void {
+    try {
+        unlinkSync(devLockFile);
+    } catch {
+        // ignore
+    }
+}
+
+// --- Core operations ---
+
+function clean(): void {
+    rmSync(join(projectDir, 'dist'), { recursive: true, force: true });
+}
+
+function tsc(tsconfig: string): void {
+    const result = spawnSync(process.execPath, [tscPath, '-p', tsconfig], {
+        stdio: 'inherit',
+        cwd: projectDir
+    });
+    if (result.status !== 0) process.exit(result.status ?? 1);
+}
+
+function startTscWatchWithReadySignal(): { child: ChildProcess; ready: Promise<void> } {
+    const child = spawn(process.execPath, [tscPath, '-w', '--preserveWatchOutput', '-p', 'tsconfig.json'], {
+        stdio: ['inherit', 'pipe', 'inherit'],
+        cwd: projectDir
+    });
+
+    const ready = new Promise<void>((resolve, reject) => {
+        let resolved = false;
+        child.stdout!.on('data', (data: Buffer) => {
+            process.stdout.write(data);
+            if (!resolved && data.toString().includes('Watching for file changes')) {
+                resolved = true;
+                resolve();
+            }
+        });
+        child.on('close', code => {
+            if (!resolved) reject(new Error(`tsc exited with code ${code}`));
+        });
+    });
+
+    return { child, ready };
+}
+
+async function performLockedWatchBuild(): Promise<ChildProcess> {
+    console.log('Starting dev build...');
+    clean();
+    const { child, ready } = startTscWatchWithReadySignal();
+    await ready;
+    console.log('Dev build ready.');
+    writeDevState({ ready: true, pids: [] });
+    releaseBuildLock();
+    return child;
+}
+
+// Returns tsc watch child process if this process is the builder, null otherwise
+async function ensureDevBuild(): Promise<ChildProcess | null> {
+    if (isDevRunning()) {
+        console.log('Using existing dev build from another process.');
+        return null;
+    }
+
+    if (tryAcquireBuildLock()) {
+        return performLockedWatchBuild();
+    }
+
+    // Wait for another builder to finish
+    console.log('Waiting for another dksf-dev process to finish building...');
+    while (true) {
+        await sleep(200);
+        if (readDevState()?.ready) {
+            console.log('Build ready.');
+            return null;
+        }
+        try {
+            const pid = parseInt(readFileSync(devLockFile, 'utf-8'));
+            if (!isPidAlive(pid)) {
+                if (tryAcquireBuildLock()) {
+                    return performLockedWatchBuild();
+                }
+            }
+        } catch {
+            if (readDevState()?.ready) return null;
+            if (tryAcquireBuildLock()) {
+                return performLockedWatchBuild();
+            }
+        }
+    }
+}
+
+// --- Subcommands ---
+
+function cmdClean(): void {
+    clean();
+}
+
+function cmdBuild(args: string[]): void {
+    const watch = args.includes('--watch');
+    console.log('Building...');
+    clean();
+    if (watch) {
+        const child = spawn(process.execPath, [tscPath, '-w', '--preserveWatchOutput', '-p', 'tsconfig.json'], {
+            stdio: 'inherit',
+            cwd: projectDir
+        });
+        process.on('SIGINT', () => {});
+        process.on('SIGTERM', () => child.kill('SIGTERM'));
+        child.on('close', code => process.exit(code ?? 0));
+    } else {
+        tsc('tsconfig.json');
+        console.log('Build complete.');
+    }
+}
+
+async function cmdRun(args: string[]): Promise<void> {
+    const ddIdx = args.indexOf('--');
+    const ownArgs = ddIdx >= 0 ? args.slice(0, ddIdx) : args;
+    const childArgs = ddIdx >= 0 ? args.slice(ddIdx + 1) : ['server:start'];
+
+    const debug = ownArgs.includes('--debug');
+    const script = ownArgs.find(a => !a.startsWith('-')) ?? '.';
+
+    const tscChild = await ensureDevBuild();
+    registerDevPid();
+    process.on('exit', unregisterDevPid);
+
+    const nodeArgs = ['--enable-source-maps', '--watch', '--watch-preserve-output'];
+
+    const port = process.env.PORT;
+    const inspectFlag = debug ? '--inspect-brk' : '--inspect';
+    nodeArgs.push(port ? `${inspectFlag}=${parseInt(port) + 1000}` : inspectFlag);
+
+    nodeArgs.push(script, ...childArgs);
+
+    const child = spawn(process.execPath, nodeArgs, {
+        stdio: 'inherit',
+        cwd: projectDir
+    });
+    process.on('SIGINT', () => {});
+    process.on('SIGTERM', () => {
+        child.kill('SIGTERM');
+        tscChild?.kill('SIGTERM');
+    });
+    child.on('close', code => {
+        tscChild?.kill();
+        process.exit(code ?? 0);
+    });
+}
+
+function cmdMigrate(args: string[]): void {
+    const debug = args.includes('--debug');
+
+    if (!isDevRunning()) {
+        console.log('Building...');
+        clean();
+        tsc('tsconfig.json');
+        console.log('Build complete.');
+    } else {
+        console.log('Using existing dev build from another process.');
+    }
+
+    const inspectFlag = debug ? '--inspect-brk=9226' : '--inspect=9226';
+    const child = spawn(process.execPath, ['--enable-source-maps', inspectFlag, '.', 'migration:run'], {
+        stdio: 'inherit',
+        cwd: projectDir
+    });
+    child.on('close', code => process.exit(code ?? 0));
+}
+
+function cmdRepl(args: string[]): void {
+    const debug = args.includes('--debug');
+
+    if (!isDevRunning()) {
+        console.log('Building...');
+        clean();
+        tsc('tsconfig.json');
+        console.log('Build complete.');
+    } else {
+        console.log('Using existing dev build from another process.');
+    }
+
+    const inspectFlag = debug ? '--inspect-brk=9227' : '--inspect=9227';
+    const child = spawn(process.execPath, ['--enable-source-maps', inspectFlag, '.', 'repl'], {
+        stdio: 'inherit',
+        cwd: projectDir
+    });
+    child.on('close', code => process.exit(code ?? 0));
+}
+
+function cmdTest(args: string[]): void {
+    const debug = args.includes('--debug');
+    const testArgs = args.filter(a => a !== '--debug');
+
+    console.log('Building...');
+    clean();
+    tsc('tsconfig.test.json');
+    console.log('Build complete.');
+
+    const inspectFlag = debug ? '--inspect-brk=9268' : '--inspect=9268';
+    const child = spawn(process.execPath, [inspectFlag, join(__dirname, 'dksf-test.js'), ...testArgs], {
+        stdio: 'inherit',
+        cwd: projectDir
+    });
+    child.on('close', code => process.exit(code ?? 0));
+}
+
+// --- Entry ---
+
+async function main(): Promise<void> {
+    const [cmd, ...args] = process.argv.slice(2);
+
+    switch (cmd) {
+        case 'clean':
+            cmdClean();
+            return;
+        case 'build':
+            cmdBuild(args);
+            return;
+        case 'run':
+            await cmdRun(args);
+            return;
+        case 'migrate':
+            cmdMigrate(args);
+            return;
+        case 'repl':
+            cmdRepl(args);
+            return;
+        case 'test':
+            cmdTest(args);
+            return;
+        default:
+            console.error(`Usage: dksf-dev <command> [options]
+
+Commands:
+  clean                        Remove the dist/ directory
+  build [--watch]              Clean and build (--watch for watch mode)
+  run [--debug] [script] [--]  Clean, build, and start with node --watch
+  migrate [--debug]            Clean, build (if needed), and run migrations
+  repl [--debug]               Clean, build (if needed), and start a REPL
+  test [--debug] [args...]     Clean, build tests, and run dksf-test
+
+Run options:
+  --debug      Use --inspect-brk instead of --inspect
+  <script>     Entrypoint to run (default: ".", uses package.json "main")
+  -- <args>    Arguments passed to the child process (default: server:start)
+
+Environment:
+  PORT         When set, inspect port is PORT+1000 (default: 9229)`);
+            process.exit(1);
+    }
+}
+
+main().catch(err => {
+    console.error(err);
+    process.exit(1);
+});

package/src/cli/dksf-gen-proto.ts

@@ -0,0 +1,176 @@
+#!/usr/bin/env node
+
+import { execSync } from 'child_process';
+import { existsSync, mkdirSync, readdirSync, statSync } from 'fs';
+import { basename, dirname, join, resolve } from 'path';
+
+const args = process.argv.slice(2);
+
+function printUsage() {
+    console.log(`
+Usage: dksf-gen-proto <proto-file-or-dir> <output-dir> [options]
+
+Generates TypeScript types from Protocol Buffer definitions using ts-proto.
+
+Arguments:
+  <proto-file-or-dir>  Path to a .proto file or directory containing .proto files
+  <output-dir>         Directory where generated files will be written
+
+Options:
+  --only-types         Only generate type definitions (no encode/decode)
+  --use-date           Use Date for google.protobuf.Timestamp (default: string)
+  --use-map-type       Use ES6 Map for proto maps (default: plain object)
+
+  -h, --help           Show this help message
+
+Examples:
+  dksf-gen-proto ./proto/service.proto ./src/generated
+  dksf-gen-proto ./proto ./src/generated/proto
+  dksf-gen-proto ./resources/proto/my-service.proto ./src/types --with-encode
+`);
+}
+
+if (args.includes('-h') || args.includes('--help') || args.length < 2) {
+    printUsage();
+    process.exit(args.length < 2 ? 1 : 0);
+}
+
+const inputPath = resolve(args[0]);
+const outputDir = resolve(args[1]);
+
+// Parse options
+const onlyTypes = args.includes('--only-types');
+const useDate = args.includes('--use-date');
+const useMapType = args.includes('--use-map-type');
+
+// Validate input path exists
+if (!existsSync(inputPath)) {
+    console.error(`Error: Input path does not exist: ${inputPath}`);
+    process.exit(1);
+}
+
+// Collect proto files
+const protoFiles: string[] = [];
+let protoDir: string;
+const stat = statSync(inputPath);
+
+if (stat.isFile()) {
+    if (!inputPath.endsWith('.proto')) {
+        console.error(`Error: Input file must be a .proto file: ${inputPath}`);
+        process.exit(1);
+    }
+    protoFiles.push(inputPath);
+    protoDir = dirname(inputPath);
+} else if (stat.isDirectory()) {
+    const files = readdirSync(inputPath);
+    for (const file of files) {
+        if (file.endsWith('.proto')) {
+            protoFiles.push(join(inputPath, file));
+        }
+    }
+    if (protoFiles.length === 0) {
+        console.log('No .proto files found in directory, nothing to generate.');
+        process.exit(0);
+    }
+    protoDir = inputPath;
+} else {
+    console.error(`Error: Input path is neither a file nor directory: ${inputPath}`);
+    process.exit(1);
+}
+
+// Create output directory if it doesn't exist
+if (!existsSync(outputDir)) {
+    mkdirSync(outputDir, { recursive: true });
+}
+
+// Find ts-proto plugin
+function findTsProtoPlugin(): string {
+    // Use require.resolve to find ts-proto, which works with workspaces and hoisting
+    try {
+        const tsProtoPath = require.resolve('ts-proto/package.json');
+        const tsProtoDir = dirname(tsProtoPath);
+        const pluginPath = join(tsProtoDir, 'protoc-gen-ts_proto');
+        if (existsSync(pluginPath)) {
+            return pluginPath;
+        }
+    } catch {
+        // Fall through to error
+    }
+
+    console.error(`Error: ts-proto not found. Install it with:
+  npm install --save-dev ts-proto
+  # or
+  yarn add -D ts-proto`);
+    process.exit(1);
+}
+
+const tsProtoPlugin = findTsProtoPlugin();
+
+// Build ts-proto options
+const tsProtoOpts: string[] = [];
+
+if (onlyTypes) {
+    tsProtoOpts.push('onlyTypes=true');
+}
+
+// Use string for timestamps by default (cleaner for JSON APIs)
+if (!useDate) {
+    tsProtoOpts.push('useDate=false');
+}
+
+// Use plain objects for maps by default
+if (!useMapType) {
+    tsProtoOpts.push('useMapType=false');
+}
+
+// Additional sensible defaults
+tsProtoOpts.push('esModuleInterop=true');
+tsProtoOpts.push('outputServices=false');
+
+const tsProtoOptString = tsProtoOpts.join(',');
+
+console.log(`Generating TypeScript types from ${protoFiles.length} proto file(s)...`);
+
+// Build protoc command
+const protocArgs = [
+    `--plugin=protoc-gen-ts_proto="${tsProtoPlugin}"`,
+    `--ts_proto_out="${outputDir}"`,
+    `--ts_proto_opt=${tsProtoOptString}`,
+    `-I"${protoDir}"`,
+    ...protoFiles.map(f => `"${f}"`)
+];
+
+const protocCmd = `npx protoc ${protocArgs.join(' ')}`;
+
+try {
+    execSync(protocCmd, {
+        stdio: 'inherit',
+        cwd: process.cwd()
+    });
+} catch {
+    console.error('Error running protoc with ts-proto');
+    process.exit(1);
+}
+
+// Get the base name for the output message
+const baseName = stat.isFile() ? basename(inputPath, '.proto') : 'proto';
+
+console.log(`
+TypeScript types generated successfully!
+
+Output directory: ${outputDir}
+
+Usage with SrpcServer:
+  import { ClientMessage, ServerMessage } from '${outputDir.replace(process.cwd(), '.')}/${baseName}';
+
+  const server = new SrpcServer<SrpcMeta, ClientMessage, ServerMessage>({
+      // ...
+  });
+
+Usage with SrpcClient:
+  import { ClientMessage, ServerMessage } from '${outputDir.replace(process.cwd(), '.')}/${baseName}';
+
+  const client = new SrpcClient<ClientMessage, ServerMessage>(
+      // ...
+  );
+`);

package/src/cli/dksf-install.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+
+import { execSync } from 'child_process';
+
+const packageDir = __dirname.substring(0, __dirname.lastIndexOf('dist') - 1);
+const baseDir = packageDir.endsWith('node_modules/@signal24/dk-server-foundation') ? packageDir.substring(0, packageDir.length - 43) : packageDir;
+
+execSync('npx deepkit-type-install', { cwd: baseDir });
+execSync('npx patch-package --patch-dir ./node_modules/@signal24/dk-server-foundation/patches', { cwd: baseDir });
+
+process.exit(0);

package/src/cli/dksf-test.ts

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+
+/* eslint-disable @typescript-eslint/no-require-imports */
+
+import { spawn } from 'child_process';
+import { readdirSync } from 'fs';
+import { join, resolve } from 'path';
+
+process.env.TZ = 'UTC';
+process.env.APP_ENV = 'test';
+
+const distDir = resolve('dist');
+
+async function main() {
+    // Run global setup if available
+    let teardown: (() => Promise<void>) | undefined;
+    try {
+        const globalSetup = require(join(distDir, 'tests', 'shared', 'globalSetup'));
+        if (globalSetup.setup) {
+            await globalSetup.setup();
+        }
+        if (globalSetup.teardown) {
+            teardown = globalSetup.teardown;
+        }
+    } catch {
+        // No global setup found, continue
+    }
+
+    // Parse arguments
+    const args = process.argv.slice(2);
+    const nodeArgs: string[] = [];
+    const fileArgs: string[] = [];
+
+    for (const arg of args) {
+        if (arg.startsWith('-')) {
+            nodeArgs.push(arg);
+        } else {
+            fileArgs.push(arg);
+        }
+    }
+
+    // Collect test files
+    let testFiles: string[];
+    if (fileArgs.length > 0) {
+        // Map source paths to dist paths
+        testFiles = fileArgs.map(f => {
+            if (f.startsWith('dist/')) return f;
+            return f.replace(/^tests\//, 'dist/tests/').replace(/\.ts$/, '.js');
+        });
+    } else {
+        // Find all spec files in dist/tests
+        testFiles = [];
+        const findSpecFiles = (dir: string) => {
+            const entries = readdirSync(dir, { withFileTypes: true });
+            for (const entry of entries) {
+                const fullPath = join(dir, entry.name);
+                if (entry.isDirectory()) {
+                    findSpecFiles(fullPath);
+                } else if (entry.name.endsWith('.spec.js')) {
+                    testFiles.push(fullPath);
+                }
+            }
+        };
+        findSpecFiles(join(distDir, 'tests'));
+    }
+
+    // Run node --test
+    // Note: --test-timeout applies to describe() suites on Node 24+, so this must be high
+    // enough to cover DB setup in before() hooks under concurrent execution.
+    // Individual tests can override with { timeout } per-test if needed.
+    const child = spawn(
+        process.execPath,
+        ['--enable-source-maps', '--test', '--test-force-exit', '--test-timeout=180000', ...nodeArgs, ...testFiles],
+        {
+            stdio: 'inherit',
+            env: { ...process.env, TZ: 'UTC' }
+        }
+    );
+
+    const exitCode = await new Promise<number | null>(resolve => {
+        child.on('close', resolve);
+    });
+
+    // Run teardown
+    if (teardown) {
+        await teardown();
+    }
+
+    process.exit(exitCode ?? 1);
+}
+
+main().catch(err => {
+    console.error('Test runner error:', err);
+    process.exit(1);
+});