@toolfactory.dev/core 1.0.0-rc

package/out/codegen/render-oauth-http-mcp-server.js

@@ -0,0 +1,220 @@
+import { renderMcpHostSharedSource } from './render-mcp-host-shared.js';
+import { requireBaseUrlEnvArgvCheck } from './mcp-host-product-runtime.js';
+/**
+ * Static OAuth + stateful MCP Streamable HTTP host for generated `cli/oauth-http-mcp-server.ts`.
+ */
+export function renderOAuthHttpMcpServerSource(product = 'api2ai', loggingImport) {
+    const shared = renderMcpHostSharedSource('oauth-http', product);
+    return `#!/usr/bin/env node
+/**
+ * Generated OAuth + stateful MCP Streamable HTTP host (static runtime — no @toolfactory.dev/core).
+ */
+import { randomUUID } from 'node:crypto';
+import * as fs from 'node:fs';
+import * as http from 'node:http';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import * as path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { ListToolsRequestSchema, type ListToolsResult } from '@modelcontextprotocol/sdk/types.js';
+import * as z from 'zod/v4';
+import { loggingAdapter } from '${loggingImport}';
+
+${shared}
+
+type SessionEntry = {
+    transport: StreamableHTTPServerTransport;
+    server: McpServer;
+    session: McpOAuthSession;
+};
+
+const sessionEntries = new Map<string, SessionEntry>();
+const sessionStore = new Map<string, McpOAuthSession>();
+const sessionHeaders = new Map<string, Record<string, string | string[] | undefined>>();
+
+function isInitializeRequestBody(body: unknown): boolean {
+    if (Array.isArray(body)) {
+        return body.some((item) => isInitializeRequestBody(item));
+    }
+    if (!body || typeof body !== 'object') {
+        return false;
+    }
+    const record = body as Record<string, unknown>;
+    return record.jsonrpc === '2.0' && record.method === 'initialize';
+}
+
+function mcpRequiresBearerOnInitialize(generated: GeneratedHostModule): boolean {
+    return generated.requiresAuth && generatedHasProtectedTool(generated);
+}
+
+function readSessionId(req: IncomingMessage): string | undefined {
+    const raw = req.headers['mcp-session-id'];
+    const value = Array.isArray(raw) ? raw[0] : raw;
+    return typeof value === 'string' && value.trim().length > 0 ? value.trim() : undefined;
+}
+
+async function createMcpServerForSession(
+    generated: GeneratedHostModule,
+    httpHostConfig: OAuthHttpHostRuntimeConfig,
+    sessionId: string,
+    headers: Record<string, string | string[] | undefined>
+): Promise<SessionEntry> {
+    const { name, version } = requireMcpServerIdentity(generated);
+    const server = new McpServer({ name, version });
+    const session: McpOAuthSession = {
+        sessionId,
+        createdAt: Date.now()
+    };
+    sessionStore.set(sessionId, session);
+    await registerMcpTools(server, generated, {
+        envDirs: httpHostConfig.envDirs,
+        resolveContext: async () => {
+            const hdr = sessionHeaders.get(sessionId) ?? headers;
+            return await resolveHostContextForOAuthSession(httpHostConfig, generated, hdr, sessionStore, sessionId);
+        }
+    });
+    const transport = new StreamableHTTPServerTransport({
+        sessionIdGenerator: () => sessionId,
+        onsessioninitialized: (sid) => {
+            session.sessionId = sid;
+        }
+    });
+    transport.onclose = () => {
+        sessionEntries.delete(sessionId);
+        sessionStore.delete(sessionId);
+        sessionHeaders.delete(sessionId);
+        // Transport already closed — see public/passthrough HTTP host (avoid server.close loop).
+    };
+    await server.connect(transport);
+    return { transport, server, session };
+}
+
+async function handleOAuthMcpRequest(
+    req: IncomingMessage,
+    res: ServerResponse,
+    generated: GeneratedHostModule,
+    httpHostConfig: OAuthHttpHostRuntimeConfig
+): Promise<void> {
+    const headers = req.headers as Record<string, string | string[] | undefined>;
+    const sessionIdHeader = readSessionId(req);
+    const parsedBody = req.method === 'POST' ? await readMcpHttpJsonBody(req) : undefined;
+
+    if (mcpRequiresBearerOnInitialize(generated)) {
+        const bearer = readBearerFromHeaders(headers);
+        const verified = await verifyCredentialForGate(generated, bearer);
+        if (!verified) {
+            if (!sessionIdHeader && isInitializeRequestBody(parsedBody)) {
+                sendOAuthUnauthorized(res, httpHostConfig);
+                return;
+            }
+            if (sessionIdHeader && !sessionEntries.has(sessionIdHeader)) {
+                sendOAuthUnauthorized(res, httpHostConfig);
+                return;
+            }
+        }
+    }
+
+    let entry: SessionEntry | undefined;
+    if (sessionIdHeader && sessionEntries.has(sessionIdHeader)) {
+        entry = sessionEntries.get(sessionIdHeader);
+    } else if (req.method === 'POST' && isInitializeRequestBody(parsedBody)) {
+        const newSessionId = randomUUID();
+        entry = await createMcpServerForSession(generated, httpHostConfig, newSessionId, headers);
+        sessionEntries.set(newSessionId, entry);
+    } else if (sessionIdHeader) {
+        writeJsonRpcError(res, 404, -32_001, 'Session not found');
+        return;
+    } else if (req.method === 'POST') {
+        writeJsonRpcError(res, 400, -32_000, 'Bad Request: Session ID required');
+        return;
+    } else {
+        writeJsonRpcMethodNotAllowed(res);
+        return;
+    }
+
+    if (!entry) {
+        writeJsonRpcInternalError(res);
+        return;
+    }
+
+    const activeSessionId = entry.session.sessionId;
+    sessionHeaders.set(activeSessionId, headers);
+
+    try {
+        await entry.transport.handleRequest(req, res, parsedBody);
+    } catch (err) {
+        loggingAdapter.error('[mcp] oauth HTTP request failed', {
+            error: err instanceof Error ? err.message : String(err)
+        });
+        if (!res.headersSent) {
+            writeJsonRpcInternalError(res);
+        }
+    }
+}
+
+async function runOAuthHttpMcpStandaloneFromArgv(argv: string[]): Promise<void> {
+    const modulePath = argv[0];
+    if (!modulePath) {
+        throw new Error(
+            'Usage: node oauth-http-mcp-server.js <path-to-*-tools.js> [--base-url-env ENV] --oauth-idp-url URL --port N [--oauth-scope SCOPE] [--host HOST] [--path /mcp]'
+        );
+    }
+    const envDirs = [process.cwd(), path.dirname(path.resolve(modulePath))];
+    loadLocalEnvFiles(envDirs);
+    const imported = await import(pathToFileURL(path.resolve(modulePath)).href);
+    if (!imported || typeof imported !== 'object') {
+        throw new Error(\`Generated module "\${modulePath}" did not export an object.\`);
+    }
+    const generated = readGeneratedModule(imported as Record<string, unknown>);
+    const httpHostConfig = parseOAuthHttpHostArgv(argv.slice(1), envDirs);
+    ${requireBaseUrlEnvArgvCheck(product, 'httpHostConfig.baseUrlEnvKey')}
+    await validateOAuthHttpHostAtStartup(httpHostConfig, generated);
+    const resourceUrl =
+        'http://' + httpHostConfig.listenHost + ':' + httpHostConfig.port + httpHostConfig.mcpPath;
+    loggingAdapter.info('[mcp] oauth HTTP listening', {
+        resourceUrl,
+        authorizationServer: httpHostConfig.oauthIdpUrl,
+        oauthOnInitialize: mcpRequiresBearerOnInitialize(generated)
+            ? 'Bearer required (protected tools — Cursor login when enabling MCP' +
+              (generatedHasPublicTool(generated) ? '; public tools after login' : '') +
+              ')'
+            : 'no Bearer required (only public tools)'
+    });
+
+    const httpServer = http.createServer(async (req, res) => {
+        const url = new URL(req.url ?? '/', 'http://' + (req.headers.host ?? 'localhost'));
+        if (url.pathname === '/.well-known/oauth-protected-resource') {
+            res.writeHead(200, { 'content-type': 'application/json' });
+            res.end(JSON.stringify(oauthResourceMetadataDocument(httpHostConfig)));
+            return;
+        }
+        if (url.pathname === '/oauth/login') {
+            res.writeHead(200, { 'content-type': 'text/html; charset=utf-8' });
+            res.end(
+                '<!doctype html><html><body><h1>MCP OAuth</h1><p>Use Cursor MCP &quot;Needs login&quot; for PKCE OAuth, or open the IDP authorize URL from MCP logs.</p><p>IDP: ' +
+                    httpHostConfig.oauthIdpUrl +
+                    '/authorize</p></body></html>'
+            );
+            return;
+        }
+        if (url.pathname !== httpHostConfig.mcpPath) {
+            res.writeHead(404).end('Not found');
+            return;
+        }
+        if (req.method === 'POST' || req.method === 'GET' || req.method === 'DELETE') {
+            await handleOAuthMcpRequest(req, res, generated, httpHostConfig);
+            return;
+        }
+        res.writeHead(405).end('Method not allowed');
+    });
+
+    await new Promise<void>((resolve, reject) => {
+        httpServer.once('error', reject);
+        httpServer.listen(httpHostConfig.port, httpHostConfig.listenHost, () => resolve());
+    });
+}
+
+await runOAuthHttpMcpStandaloneFromArgv(process.argv.slice(2));
+`;
+}

package/out/codegen/render-stdio-mcp-server.d.ts

@@ -0,0 +1,5 @@
+import { type McpHostProduct } from './mcp-host-product-runtime.js';
+/**
+ * Static MCP stdio host for generated `cli/stdio-mcp-server.ts`.
+ */
+export declare function renderStdioMcpServerSource(product: McpHostProduct | undefined, loggingImport: string): string;

package/out/codegen/render-stdio-mcp-server.js

@@ -0,0 +1,58 @@
+import { renderMcpHostSharedSource } from './render-mcp-host-shared.js';
+import { requireBaseUrlEnvArgvCheck } from './mcp-host-product-runtime.js';
+/**
+ * Static MCP stdio host for generated `cli/stdio-mcp-server.ts`.
+ */
+export function renderStdioMcpServerSource(product = 'api2ai', loggingImport) {
+    const shared = renderMcpHostSharedSource('stdio', product);
+    return `#!/usr/bin/env node
+/**
+ * Generated MCP stdio host (static runtime — no @toolfactory.dev/core).
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { ListToolsRequestSchema, type ListToolsResult } from '@modelcontextprotocol/sdk/types.js';
+import * as z from 'zod/v4';
+import { loggingAdapter } from '${loggingImport}';
+
+${shared}
+
+async function runStdioMcpServer(
+    generated: ReturnType<typeof readGeneratedModule>,
+    hostConfig: HostRuntimeConfig
+): Promise<void> {
+    const { name, version } = requireMcpServerIdentity(generated);
+    const server = new McpServer({ name, version });
+    await registerMcpTools(server, generated, {
+        envDirs: hostConfig.envDirs,
+        resolveContext: () => resolveHostContextForCall(hostConfig, generated)
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+
+async function runStdioMcpStandaloneFromArgv(argv: string[]): Promise<void> {
+    const modulePath = argv[0];
+    if (!modulePath) {
+        throw new Error('Usage: node stdio-mcp-server.js <path-to-*-tools.js> [host options...]');
+    }
+    const envDirs = [process.cwd(), path.dirname(path.resolve(modulePath))];
+    loadLocalEnvFiles(envDirs);
+    const imported = await import(pathToFileURL(path.resolve(modulePath)).href);
+    if (!imported || typeof imported !== 'object') {
+        throw new Error(\`Generated module "\${modulePath}" did not export an object.\`);
+    }
+    const generated = readGeneratedModule(imported as Record<string, unknown>);
+    const hostConfig = parseHostArgv(argv.slice(1), envDirs);
+    ${requireBaseUrlEnvArgvCheck(product, 'hostConfig.baseUrlEnvKey')}
+    validateHostAtStartup(hostConfig, generated);
+    loggingAdapter.info('[mcp] host context refreshed each tool call');
+    await runStdioMcpServer(generated, hostConfig);
+}
+
+await runStdioMcpStandaloneFromArgv(process.argv.slice(2));
+`;
+}

package/out/codegen/write-demos-test-support.d.ts

@@ -0,0 +1,2 @@
+/** Remove legacy `test/generated/*` helpers; compile check uses `npm run build:generated`. */
+export declare function writeGeneratedDemosTestSupport(projectRoot: string): void;

package/out/codegen/write-demos-test-support.js

@@ -0,0 +1,28 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { PROJECT_GENERATE_CONFIG } from '../scripts/write-generated-scripts.js';
+const REMOVED_FILES = [
+    'generated-module.ts',
+    'mcp-stdio-smoke.ts',
+    'mcp-http-smoke.ts',
+    'env-helpers.ts',
+    'compile-generated-fixture.ts',
+    'index.ts'
+];
+/** Remove legacy `test/generated/*` helpers; compile check uses `npm run build:generated`. */
+export function writeGeneratedDemosTestSupport(projectRoot) {
+    const configPath = path.join(projectRoot, PROJECT_GENERATE_CONFIG);
+    if (!fs.existsSync(configPath)) {
+        return;
+    }
+    const outDir = path.join(projectRoot, 'test', 'generated');
+    for (const fileName of REMOVED_FILES) {
+        const stalePath = path.join(outDir, fileName);
+        if (fs.existsSync(stalePath)) {
+            fs.unlinkSync(stalePath);
+        }
+    }
+    if (fs.existsSync(outDir) && fs.readdirSync(outDir).length === 0) {
+        fs.rmdirSync(outDir);
+    }
+}

package/out/codegen/zod-codegen.d.ts

@@ -0,0 +1,9 @@
+export type JsonSchemaDict = Record<string, unknown>;
+/** Emits Zod v4 expression source (uses identifier `z` in scope). */
+export declare function emitZodExpression(schema: JsonSchemaDict): string;
+/** Append `(example: …)` to a description when JSON Schema carries example(s) and text does not already. */
+export declare function mergeJsonSchemaExampleIntoDescription(description: string | undefined, schema: JsonSchemaDict): string | undefined;
+/** Shared helpers referenced by per-tool Zod schemas in generated modules. */
+export declare function emitGeneratedZodPreamble(): string;
+export declare function emitInputZodByToolExport(schemasByTool: Record<string, JsonSchemaDict>): string;
+export declare function buildInputZodBlock(schemasByTool: Record<string, JsonSchemaDict>): string;

package/out/codegen/zod-codegen.js

@@ -0,0 +1,149 @@
+/** Emits Zod v4 expression source (uses identifier `z` in scope). */
+export function emitZodExpression(schema) {
+    if (schema === null || typeof schema !== 'object' || Array.isArray(schema)) {
+        return 'z.unknown()';
+    }
+    if (Array.isArray(schema.anyOf)) {
+        return emitUnion(schema.anyOf);
+    }
+    if (Array.isArray(schema.oneOf)) {
+        return emitUnion(schema.oneOf);
+    }
+    if (schema.type === 'object' &&
+        schema.properties !== undefined &&
+        typeof schema.properties === 'object' &&
+        !Array.isArray(schema.properties)) {
+        const props = schema.properties;
+        const required = new Set(Array.isArray(schema.required)
+            ? schema.required.filter((x) => typeof x === 'string')
+            : []);
+        const entries = Object.entries(props).map(([key, propSchema]) => {
+            let inner = emitZodExpression(propSchema);
+            if (!required.has(key)) {
+                inner = `${inner}.optional()`;
+            }
+            return `${JSON.stringify(key)}: ${inner}`;
+        });
+        let obj = `z.object({ ${entries.join(', ')} })`;
+        if (schema.additionalProperties === false) {
+            obj += '.strict()';
+        }
+        return withDescribe(obj, schema);
+    }
+    if (schema.type === 'array') {
+        const items = emitZodExpression((schema.items ?? {}));
+        return withDescribe(`z.union([z.array(${items}), z.string()])`, schema);
+    }
+    if (schema.type === 'string') {
+        if (Array.isArray(schema.enum) && schema.enum.length >= 1 && schema.enum.every((e) => typeof e === 'string')) {
+            return withDescribe(emitStringPicklist(schema.enum), schema);
+        }
+        return withDescribe('z.string()', schema);
+    }
+    if (schema.type === 'number' || schema.type === 'integer') {
+        return emitLlmTolerantNumber(schema, schema.type === 'integer');
+    }
+    if (schema.type === 'boolean') {
+        return withDescribe('z.union([z.boolean(), z.literal("true"), z.literal("false")])', schema);
+    }
+    if (schema.type === 'object' && schema.additionalProperties === true) {
+        return withDescribe('z.record(z.string(), z.union([z.string(), z.number(), z.boolean()]))', schema);
+    }
+    if (schema.type === 'object' &&
+        typeof schema.additionalProperties === 'object' &&
+        schema.additionalProperties !== null &&
+        !Array.isArray(schema.additionalProperties)) {
+        const valueType = emitZodExpression(schema.additionalProperties);
+        return withDescribe(`z.record(z.string(), ${valueType})`, schema);
+    }
+    return 'z.unknown()';
+}
+function formatExampleForDescription(value) {
+    if (typeof value === 'string') {
+        return value;
+    }
+    if (typeof value === 'number' || typeof value === 'boolean') {
+        return String(value);
+    }
+    return JSON.stringify(value);
+}
+function firstJsonSchemaExampleValue(schema) {
+    if (Array.isArray(schema.examples) && schema.examples.length > 0) {
+        return schema.examples[0];
+    }
+    if (schema.example !== undefined) {
+        return schema.example;
+    }
+    return undefined;
+}
+/** Append `(example: …)` to a description when JSON Schema carries example(s) and text does not already. */
+export function mergeJsonSchemaExampleIntoDescription(description, schema) {
+    const trimmed = description?.trim() ?? '';
+    if (trimmed.includes('(example:')) {
+        return trimmed.length > 0 ? trimmed : undefined;
+    }
+    const exampleValue = firstJsonSchemaExampleValue(schema);
+    if (exampleValue === undefined) {
+        return trimmed.length > 0 ? trimmed : undefined;
+    }
+    const suffix = `(example: ${formatExampleForDescription(exampleValue)})`;
+    return trimmed.length > 0 ? `${trimmed} ${suffix}` : suffix;
+}
+function withDescribe(expr, schema) {
+    const desc = mergeJsonSchemaExampleIntoDescription(typeof schema.description === 'string' ? schema.description : undefined, schema);
+    if (desc && desc.length > 0) {
+        return `${expr}.describe(${JSON.stringify(desc)})`;
+    }
+    return expr;
+}
+function emitUnion(parts) {
+    const emitted = parts.map((p) => emitZodExpression(p));
+    if (emitted.length === 0) {
+        return 'z.never()';
+    }
+    if (emitted.length === 1) {
+        return emitted[0];
+    }
+    return `z.union([${emitted.join(', ')}])`;
+}
+function emitStringPicklist(strings) {
+    if (strings.length === 0) {
+        return 'z.never()';
+    }
+    if (strings.length === 1) {
+        return `z.literal(${JSON.stringify(strings[0])})`;
+    }
+    return `z.union([${strings.map((v) => `z.literal(${JSON.stringify(v)})`).join(', ')}])`;
+}
+/** MCP tool args: models often pass OpenAPI numbers/booleans as JSON strings. */
+function emitLlmTolerantNumber(schema, integer) {
+    if (Array.isArray(schema.enum) && schema.enum.length >= 1 && schema.enum.every(isFiniteNumber)) {
+        const literals = schema.enum.flatMap((v) => [
+            `z.literal(${v})`,
+            `z.literal(${JSON.stringify(String(v))})`
+        ]);
+        if (literals.length === 1) {
+            return withDescribe(literals[0], schema);
+        }
+        return withDescribe(`z.union([${literals.join(', ')}])`, schema);
+    }
+    const numberBranch = integer ? 'z.number().int()' : 'z.number()';
+    return withDescribe(`z.union([${numberBranch}, z.string()])`, schema);
+}
+function isFiniteNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value);
+}
+/** Shared helpers referenced by per-tool Zod schemas in generated modules. */
+export function emitGeneratedZodPreamble() {
+    return `import * as z from 'zod/v4';
+`;
+}
+export function emitInputZodByToolExport(schemasByTool) {
+    const entries = Object.entries(schemasByTool).map(([toolName, schema]) => {
+        return `    ${JSON.stringify(toolName)}: ${emitZodExpression(schema)}`;
+    });
+    return `export const inputZodByTool = {\n${entries.join(',\n')}\n};`;
+}
+export function buildInputZodBlock(schemasByTool) {
+    return `${emitInputZodByToolExport(schemasByTool)}\n`;
+}

package/out/scripts/generated-scripts-banner.d.ts

@@ -0,0 +1,2 @@
+/** Prepended to every file under consumer `scripts/generated/`. */
+export declare const GENERATED_SCRIPTS_BANNER = "// @generated from @toolfactory.dev/core \u2014 do not edit; regenerated when running project generate.\n\n";

package/out/scripts/generated-scripts-banner.js

@@ -0,0 +1,2 @@
+/** Prepended to every file under consumer `scripts/generated/`. */
+export const GENERATED_SCRIPTS_BANNER = '// @generated from @toolfactory.dev/core — do not edit; regenerated when running project generate.\n\n';

package/out/scripts/render-kill-listeners-on-port.mjs.d.ts

@@ -0,0 +1 @@
+export declare function renderKillListenersOnPortMjsSource(): string;

package/out/scripts/render-kill-listeners-on-port.mjs.js

@@ -0,0 +1,81 @@
+import { GENERATED_SCRIPTS_BANNER } from './generated-scripts-banner.js';
+export function renderKillListenersOnPortMjsSource() {
+    return `${GENERATED_SCRIPTS_BANNER}/**
+ * Kill only TCP listeners on a port (not clients connected to that port).
+ */
+import { execSync } from 'node:child_process';
+
+/**
+ * @param {number} port
+ * @returns {string[]}
+ */
+function listListenerPids(port) {
+    try {
+        const raw = execSync(\`lsof -nP -iTCP:\${port} -sTCP:LISTEN -t\`, { encoding: 'utf8' }).trim();
+        if (!raw) {
+            return [];
+        }
+        return raw.split('\\n').filter(Boolean);
+    } catch (err) {
+        const status = err && typeof err === 'object' && 'status' in err ? err.status : undefined;
+        if (status === 1) {
+            return [];
+        }
+        throw err;
+    }
+}
+
+/**
+ * @param {string} pid
+ * @returns {string}
+ */
+function processCommand(pid) {
+    try {
+        return execSync(\`ps -p \${pid} -o comm=\`, { encoding: 'utf8' }).trim();
+    } catch {
+        return '';
+    }
+}
+
+function isNodeListener(pid) {
+    const comm = processCommand(pid).toLowerCase();
+    return comm === 'node' || comm.endsWith('/node');
+}
+
+/**
+ * @param {number} port
+ * @param {{ logPrefix?: string, nodeOnly?: boolean }} [options]
+ * @returns {{ killed: string[], skipped: string[] }}
+ */
+export function killListenersOnPort(port, options = {}) {
+    const logPrefix = options.logPrefix ?? 'kill';
+    const nodeOnly = options.nodeOnly !== false;
+    const pids = listListenerPids(port);
+    if (pids.length === 0) {
+        console.log(\`[\${logPrefix}] port \${port}: nothing listening\`);
+        return { killed: [], skipped: [] };
+    }
+
+    const killed = [];
+    const skipped = [];
+    for (const pid of pids) {
+        if (nodeOnly && !isNodeListener(pid)) {
+            const comm = processCommand(pid) || 'unknown';
+            skipped.push(pid);
+            console.warn(\`[\${logPrefix}] port \${port}: skip pid \${pid} (\${comm}) — not a node listener\`);
+            continue;
+        }
+        execSync(\`kill \${pid}\`);
+        killed.push(pid);
+    }
+
+    if (killed.length > 0) {
+        console.log(\`[\${logPrefix}] port \${port}: stopped \${killed.join(', ')}\`);
+    }
+    if (killed.length === 0 && skipped.length > 0) {
+        console.log(\`[\${logPrefix}] port \${port}: no node listener stopped\`);
+    }
+    return { killed, skipped };
+}
+`;
+}

package/out/scripts/render-load-env-local.mjs.d.ts

@@ -0,0 +1 @@
+export declare function renderLoadEnvLocalMjsSource(): string;

package/out/scripts/render-load-env-local.mjs.js

@@ -0,0 +1,67 @@
+import { GENERATED_SCRIPTS_BANNER } from './generated-scripts-banner.js';
+export function renderLoadEnvLocalMjsSource() {
+    return `${GENERATED_SCRIPTS_BANNER}/**
+ * Load \`.env\` then \`.env.local\` into process.env.
+ * Does not override keys already set in the shell; \`.env.local\` overrides \`.env\`.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const defaultRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+
+function stripOptionalQuotes(value) {
+    if (value.length < 2) {
+        return value;
+    }
+    const first = value[0];
+    const last = value[value.length - 1];
+    if ((first === '"' && last === '"') || (first === "'" && last === "'")) {
+        return value.slice(1, -1);
+    }
+    return value;
+}
+
+function parseEnvLine(line) {
+    const trimmed = line.trim();
+    if (trimmed.length === 0 || trimmed.startsWith('#')) {
+        return undefined;
+    }
+    const assignment = trimmed.startsWith('export ') ? trimmed.slice('export '.length).trim() : trimmed;
+    const separator = assignment.indexOf('=');
+    if (separator <= 0) {
+        return undefined;
+    }
+    const key = assignment.slice(0, separator).trim();
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) {
+        return undefined;
+    }
+    return [key, stripOptionalQuotes(assignment.slice(separator + 1).trim())];
+}
+
+function loadEnvFile(filePath, options) {
+    const overrideExisting = options?.overrideExisting === true;
+    if (!existsSync(filePath)) {
+        return false;
+    }
+    const content = readFileSync(filePath, 'utf-8');
+    for (const line of content.split(/\\r?\\n/u)) {
+        const parsed = parseEnvLine(line);
+        if (!parsed) {
+            continue;
+        }
+        const [key, value] = parsed;
+        if (overrideExisting || process.env[key] === undefined) {
+            process.env[key] = value;
+        }
+    }
+    return true;
+}
+
+/** @param {string} [root] defaults to project root (parent of scripts/) */
+export function loadProjectEnvLocal(root = defaultRoot) {
+    loadEnvFile(path.join(root, '.env'));
+    loadEnvFile(path.join(root, '.env.local'), { overrideExisting: true });
+}
+`;
+}

package/out/scripts/render-require-env.mjs.d.ts

@@ -0,0 +1 @@
+export declare function renderRequireEnvMjsSource(): string;