@pulse-compute/cli 0.0.0 → 1.0.0-beta.2

package/src/internal/command-executor.js

@@ -0,0 +1,143 @@
+'use strict';
+
+const fs = require('node:fs');
+const { PulseProjectError } = require('../project-config.js');
+const {
+  compileNativeProject,
+  buildProject,
+  runProjectTests,
+  inspectProject,
+  doctorProject,
+  startDevServer,
+  initProject,
+  errorSummary
+} = require('../project-execution.js');
+const { normalizeCommandRequest } = require('./command-request.js');
+const { isCommandPlan } = require('./command-plan.js');
+const { resolvedProjectForContext, isProjectContext } = require('./project-context.js');
+
+const EXECUTOR_IDS = Object.freeze(['meta', 'init', 'artifact', 'compile', 'build', 'test', 'inspect', 'doctor', 'dev']);
+
+const defaultOperations = Object.freeze({
+  compileNativeProject,
+  buildProject,
+  runProjectTests,
+  inspectProject,
+  doctorProject,
+  startDevServer,
+  initProject
+});
+
+function selectOperations(overrides) {
+  if (!overrides) return defaultOperations;
+  const selected = {};
+  for (const [name, operation] of Object.entries(defaultOperations)) {
+    selected[name] = typeof overrides[name] === 'function' ? overrides[name] : operation;
+  }
+  return Object.freeze(selected);
+}
+
+function inspectArtifact(file) {
+  if (!fs.existsSync(file)) {
+    throw new PulseProjectError('PULSE_INSPECT_TARGET_MISSING', `Inspect target does not exist: ${file}`, { file });
+  }
+  return Object.freeze({ status: 'ok', file, value: JSON.parse(fs.readFileSync(file, 'utf8')) });
+}
+
+function projectForExecution(plan, projectContext) {
+  if (plan.mode !== 'project') return undefined;
+  if (!isProjectContext(projectContext)) {
+    throw new TypeError(`Pulse ${plan.command} project execution requires the authoritative ProjectContext`);
+  }
+  return resolvedProjectForContext(projectContext);
+}
+
+async function executeDev(project, request, operations, options = {}) {
+  let eventCount = 0;
+  let lastEvent;
+  const onEvent = (event) => {
+    eventCount += 1;
+    lastEvent = event;
+    if (typeof options.onEvent === 'function') options.onEvent(event);
+  };
+  const running = await operations.startDevServer(project, {
+    host: request.host,
+    port: request.port,
+    watch: request.watch,
+    once: request.once,
+    onEvent
+  });
+  const signalSource = options.signalSource || process;
+  const close = () => {
+    if (!running.server.listening) return;
+    running.server.close();
+    if (typeof running.server.closeIdleConnections === 'function') running.server.closeIdleConnections();
+  };
+  signalSource.once('SIGINT', close);
+  signalSource.once('SIGTERM', close);
+  try {
+    await running.closed;
+  } finally {
+    signalSource.removeListener('SIGINT', close);
+    signalSource.removeListener('SIGTERM', close);
+  }
+  return { status: 0, result: { status: 'closed', ready: running.ready, eventCount, lastEvent } };
+}
+
+async function executeCommandPlan(plan, requestValue, options = {}) {
+  if (!isCommandPlan(plan)) throw new TypeError('Command execution requires a command plan');
+  const request = normalizeCommandRequest(requestValue);
+  const operations = selectOperations(options.operations);
+  const cliVersion = String(options.cliVersion || require('../../package.json').version);
+
+  if (request.kind === 'meta' || request.help) {
+    const invocation = request.kind === 'meta' ? request.invocation : 'help';
+    if (invocation === 'help') return { status: 0, help: true };
+    if (invocation === 'version') return { status: 0, version: cliVersion };
+    return { status: 0, completion: request.shell };
+  }
+  if (request.command === 'init') {
+    return { status: 0, result: operations.initProject(plan.target, { name: request.name, force: request.force }) };
+  }
+  if (plan.mode === 'artifact') return { status: 0, result: inspectArtifact(plan.artifact) };
+
+  const project = projectForExecution(plan, options.projectContext);
+  if (request.command === 'compile') {
+    return {
+      status: 0,
+      result: operations.compileNativeProject(project, {
+        clean: request.clean,
+        outDir: request.outDir,
+        experimentalNativeSize: request.experimentalNativeSize
+      })
+    };
+  }
+  if (request.command === 'build') {
+    return {
+      status: 0,
+      result: operations.buildProject(project, {
+        clean: request.clean,
+        outDir: request.outDir,
+        experimentalNativeSize: request.experimentalNativeSize
+      })
+    };
+  }
+  if (request.command === 'test') {
+    const result = await operations.runProjectTests(project, { caseName: request.caseName });
+    return { status: result.status === 'passed' ? 0 : 1, result };
+  }
+  if (request.command === 'inspect') return { status: 0, result: operations.inspectProject(project) };
+  if (request.command === 'doctor') {
+    const result = operations.doctorProject(project, { strict: request.strict });
+    return { status: result.status === 'failed' ? 1 : 0, result };
+  }
+  if (request.command === 'dev') return executeDev(project, request, operations, options);
+  throw new PulseProjectError('PULSE_COMMAND_UNIMPLEMENTED', `Pulse command is not implemented: ${request.command}`, { command: request.command });
+}
+
+module.exports = Object.freeze({
+  EXECUTOR_IDS,
+  executeCommandPlan,
+  inspectArtifact,
+  summarizeExecutionError: errorSummary
+});

package/src/internal/command-plan.d.ts

@@ -0,0 +1,9 @@
+import type { NormalizedCommandRequest, MetaCommandRequest } from './command-request';
+import type { ProjectContext } from './project-context';
+
+export type CommandPlan = Readonly<Record<string, unknown> & { ok: true; command: string }>;
+export declare function createCommandPlan(
+  request: NormalizedCommandRequest | MetaCommandRequest | Readonly<Record<string, unknown>>,
+  options?: Readonly<{ cwd?: string; version?: string; projectContext?: ProjectContext }>
+): CommandPlan;
+export declare function isCommandPlan(value: unknown): value is CommandPlan;

package/src/internal/command-plan.js

@@ -0,0 +1,73 @@
+'use strict';
+
+const path = require('node:path');
+const { PulseProjectError } = require('../project-config.js');
+const { normalizeCommandRequest } = require('./command-request.js');
+const { isProjectContext, projectDocumentForContext } = require('./project-context.js');
+
+const EXPERIMENTAL_NATIVE_SIZE_PLAN = Object.freeze({
+  mode: 'experimental-native-size',
+  experimental: true,
+  goal: 'size',
+  owner: 'native-compiler'
+});
+
+function createCommandPlan(requestValue, options = {}) {
+  const request = normalizeCommandRequest(requestValue);
+  const cwd = path.resolve(options.cwd || process.cwd());
+  const version = String(options.version || require('../../package.json').version);
+
+  if (request.kind === 'meta') {
+    if (request.invocation === 'help') return Object.freeze({ ok: true, command: 'help' });
+    if (request.invocation === 'version') return Object.freeze({ ok: true, command: 'version', version });
+    return Object.freeze({ ok: true, command: 'completion', shell: request.shell, generatedFrom: 'pulse.command-spec' });
+  }
+  if (request.command === 'init') {
+    return Object.freeze({ ok: true, command: 'init', target: path.resolve(cwd, request.target || '.'), backgroundWork: false });
+  }
+
+  if (request.command === 'inspect' && request.artifact) {
+    return Object.freeze({ ok: true, command: 'inspect', mode: 'artifact', artifact: path.resolve(cwd, request.artifact), backgroundWork: false });
+  }
+
+  const projectContext = options.projectContext;
+  if (!isProjectContext(projectContext)) {
+    throw new TypeError(`Pulse ${request.command} planning requires the authoritative ProjectContext`);
+  }
+  const project = projectDocumentForContext(projectContext);
+  if (request.experimentalNativeSize === true && request.command === 'build' && projectContext.target !== 'native') {
+    throw new PulseProjectError(
+      'PULSE_EXPERIMENTAL_NATIVE_SIZE_UNSUPPORTED',
+      'The --experimental-native-size flag is available only for Native compilation.',
+      {
+        target: projectContext.target,
+        required: Object.freeze({ target: 'native' })
+      }
+    );
+  }
+  return Object.freeze({
+    ok: true,
+    command: request.command,
+    mode: 'project',
+    project,
+    provider: request.command === 'compile' ? null : projectContext.provider,
+    configuredProvider: request.command === 'compile' ? projectContext.provider : undefined,
+    buildMode: request.command === 'compile'
+      ? 'portable-native-wasm'
+      : (request.command === 'build'
+          ? ((projectContext.target || project.target || 'native') === 'javascript' ? 'javascript-source-package' : 'native-provider')
+          : undefined),
+    optimization: request.experimentalNativeSize === true ? EXPERIMENTAL_NATIVE_SIZE_PLAN : undefined,
+    backgroundWork: false,
+    foregroundServer: request.command === 'dev'
+  });
+}
+
+function isCommandPlan(value) {
+  return Boolean(value && value.ok === true && typeof value.command === 'string');
+}
+
+module.exports = Object.freeze({
+  createCommandPlan,
+  isCommandPlan
+});

package/src/internal/command-reporter.d.ts

@@ -0,0 +1,15 @@
+import type { MetaCommandRequest, NormalizedCommandRequest } from './command-request';
+import type { CommandPlan } from './command-plan';
+import type { CommandExecutionResult } from './command-executor';
+
+export interface WritableLike { write(value: string): unknown }
+export interface CommandReporter {
+  reportPlan(request: NormalizedCommandRequest, plan: CommandPlan): void;
+  reportEvent(request: NormalizedCommandRequest, event: Readonly<Record<string, unknown>>): void;
+  reportExecution(request: NormalizedCommandRequest | MetaCommandRequest, plan: CommandPlan, execution: CommandExecutionResult): CommandExecutionResult;
+  reportDiagnostic(summary: Readonly<Record<string, unknown>>, context?: Readonly<{ request?: NormalizedCommandRequest | MetaCommandRequest; argv?: readonly string[]; json?: boolean }>): void;
+}
+
+export declare function createCommandReporter(options?: Readonly<{ stdout?: WritableLike; stderr?: WritableLike; cliVersion?: string; usageText?: string }>): CommandReporter;
+export declare function writeJson(stream: WritableLike, value: unknown): void;
+export declare function writeHumanResult(stream: WritableLike, command: string, result: any): void;

package/src/internal/command-reporter.js

@@ -0,0 +1,133 @@
+'use strict';
+
+const { renderCompletion } = require('../completion.js');
+const { normalizeCommandRequest } = require('./command-request.js');
+
+function writeJson(stream, value) {
+  stream.write(`${JSON.stringify(value, null, 2)}\n`);
+}
+
+function writeHumanResult(stream, command, result) {
+  if (command === 'init') {
+    stream.write(`Initialized Pulse project at ${result.root}\n`);
+    for (const file of result.files) stream.write(`  ${file}\n`);
+    if (result.nextSteps) {
+      stream.write('Next steps:\n');
+      for (const step of result.nextSteps) stream.write(`  ${step}\n`);
+    }
+    return;
+  }
+  if (command === 'build') {
+    stream.write(`Built ${result.project.entryFile} for ${result.provider}\n`);
+    stream.write(`  ${result.files.manifest}\n`);
+    stream.write(`  ${result.files.handler}\n`);
+    if (result.files.nativeWasm) stream.write(`  ${result.files.nativeWasm}\n`);
+    if (result.files.providerWasm) stream.write(`  ${result.files.providerWasm}\n`);
+    if (result.manifest && result.manifest.providerTarget && result.manifest.providerTarget.optimization && result.manifest.providerTarget.optimization.experimental) {
+      stream.write('  experimental optimization: native-size (compiler-owned profile)\n');
+    }
+    return;
+  }
+  if (command === 'compile') {
+    stream.write(`Compiled ${result.project.entryFile} to provider-neutral Pulse Wasm\n`);
+    stream.write(`  ${result.files.nativeWasm}\n`);
+    stream.write(`  ${result.files.manifest}\n`);
+    if (result.native && result.native.optimization && result.native.optimization.experimental) {
+      stream.write('  experimental optimization: native-size (compiler-owned profile)\n');
+    }
+    return;
+  }
+  if (command === 'test') {
+    for (const entry of result.cases || []) stream.write(`${entry.status === 'passed' ? 'ok' : 'not ok'} - ${entry.name}\n`);
+    stream.write(`${result.summary.passed}/${result.summary.total} Pulse project tests passed\n`);
+    return;
+  }
+  if (command === 'inspect') {
+    stream.write(`${result.project.entryFile}\n`);
+    stream.write(`  workspace: ${result.project.workspace ? result.project.workspace.root : result.project.root}\n`);
+    if (result.project.selectedProfile) stream.write(`  profile: ${result.project.selectedProfile.name} (${result.project.selectedProfile.source})\n`);
+    stream.write(`  target: ${result.project.target || 'native'}\n`);
+    stream.write(`  provider: ${result.project.provider}\n`);
+    stream.write(`  capabilities: ${(result.compiler.capabilities || []).join(', ') || 'none'}\n`);
+    stream.write(`  effects: ${result.compiler.effectCount}\n`);
+    stream.write(`  continuations: ${result.compiler.continuationCount}\n`);
+    return;
+  }
+  if (command === 'doctor') {
+    for (const check of result.checks) stream.write(`${check.status.padEnd(7)} ${check.id}: ${check.message}\n`);
+    for (const entry of result.checks.filter((check) => check.status !== 'passed' && check.remediation)) {
+      for (const step of entry.remediation) stream.write(`  help: ${step}\n`);
+    }
+    stream.write(`doctor: ${result.status}\n`);
+  }
+}
+
+function createCommandReporter(options = {}) {
+  const stdout = options.stdout || process.stdout;
+  const stderr = options.stderr || process.stderr;
+  const cliVersion = String(options.cliVersion || require('../../package.json').version);
+  const usageText = String(options.usageText || '');
+
+  function reportPlan(requestValue, plan) {
+    const request = normalizeCommandRequest(requestValue);
+    if (request.kind !== 'command') return;
+    if (request.json) writeJson(stdout, { status: 'ok', version: cliVersion, plan });
+    else stdout.write(`${plan.command}: ${plan.mode || 'ready'}\n`);
+  }
+
+  function reportEvent(requestValue, event) {
+    const request = normalizeCommandRequest(requestValue);
+    if (request.kind !== 'command') return;
+    if (request.json) stdout.write(`${JSON.stringify(event)}\n`);
+    else if (event.event === 'ready') stdout.write(`pulse dev: ${event.url}\n`);
+    else if (event.event === 'reloaded') stdout.write(`reloaded ${event.entry}\n`);
+    else if (event.event === 'compile-error') stderr.write(`compile error: ${event.error.message}\n`);
+    else if (event.event === 'request-error') stderr.write(`request error: ${event.error.message}\n`);
+  }
+
+  function reportExecution(requestValue, plan, execution) {
+    const request = normalizeCommandRequest(requestValue);
+    if (request.kind === 'meta' || request.help) {
+      const invocation = request.kind === 'meta' ? request.invocation : 'help';
+      if (invocation === 'help') stdout.write(usageText);
+      else if (invocation === 'version') stdout.write(`${execution.version}\n`);
+      else {
+        const completion = renderCompletion(request.shell);
+        stdout.write(completion);
+        return { ...execution, bytes: Buffer.byteLength(completion) };
+      }
+      return execution;
+    }
+    if (plan.mode === 'artifact') {
+      if (request.json) writeJson(stdout, execution.result);
+      else stdout.write(`${execution.result.file}: ok\n`);
+      return execution;
+    }
+    if (request.command === 'dev') return execution;
+    if (request.json) writeJson(stdout, execution.result);
+    else writeHumanResult(stdout, request.command, execution.result);
+    return execution;
+  }
+
+  function reportDiagnostic(summary, context = {}) {
+    const request = context.request;
+    const wantsJson = Boolean(context.json)
+      || Boolean(request && request.kind === 'command' && request.json)
+      || Array.from(context.argv || []).includes('--json');
+    if (wantsJson) {
+      writeJson(stderr, { status: 'error', version: cliVersion, error: summary });
+      return;
+    }
+    stderr.write(`pulse: ${summary.code ? `${summary.code}: ` : ''}${summary.message}\n`);
+    for (const step of summary.remediation || []) stderr.write(`  help: ${step}\n`);
+    if (summary.docs) stderr.write(`  docs: ${summary.docs}\n`);
+  }
+
+  return Object.freeze({ reportPlan, reportEvent, reportExecution, reportDiagnostic });
+}
+
+module.exports = Object.freeze({
+  createCommandReporter,
+  writeJson,
+  writeHumanResult
+});

package/src/internal/command-request.d.ts

@@ -0,0 +1,35 @@
+export type PulseCliCommand = 'init' | 'doctor' | 'inspect' | 'test' | 'dev' | 'compile' | 'build';
+
+export interface CommonNormalizedRequest {
+  readonly kind: 'command';
+  readonly command: PulseCliCommand;
+  readonly json: boolean;
+  readonly dryRun: boolean;
+  readonly help?: boolean;
+}
+
+export type MetaCommandRequest =
+  | Readonly<{ kind: 'meta'; invocation: 'help' }>
+  | Readonly<{ kind: 'meta'; invocation: 'version' }>
+  | Readonly<{ kind: 'meta'; invocation: 'completion'; shell: 'bash' | 'zsh' | 'fish' }>;
+
+export type NormalizedCommandRequest = Readonly<CommonNormalizedRequest & {
+  readonly directory?: string;
+  readonly profile?: string;
+  readonly target?: string;
+  readonly name?: string;
+  readonly force?: boolean;
+  readonly strict?: boolean;
+  readonly artifact?: string;
+  readonly caseName?: string;
+  readonly host?: string;
+  readonly port?: number;
+  readonly watch?: boolean;
+  readonly once?: boolean;
+  readonly outDir?: string;
+  readonly clean?: boolean;
+  readonly experimentalNativeSize?: boolean;
+}>;
+
+export declare function parseCommandRequest(argv: readonly string[]): NormalizedCommandRequest | MetaCommandRequest;
+export declare function normalizeCommandRequest(value: readonly string[] | Readonly<Record<string, unknown>>): NormalizedCommandRequest | MetaCommandRequest;

package/src/internal/command-request.js

@@ -0,0 +1,154 @@
+'use strict';
+
+const { PulseProjectError } = require('../project-config.js');
+const { COMPLETION_SHELLS } = require('../completion.js');
+const {
+  COMMANDS,
+  COMMAND_SPECS,
+  optionForToken,
+  optionAllowed,
+  publicOptionsForCommand
+} = require('../command-spec.js');
+
+function deepFreeze(value) {
+  if (!value || typeof value !== 'object' || Object.isFrozen(value)) return value;
+  for (const child of Object.values(value)) deepFreeze(child);
+  return Object.freeze(value);
+}
+
+function metaRequest(invocation, detail = {}) {
+  return deepFreeze({ kind: 'meta', invocation, ...detail });
+}
+
+function baseCommandRequest(command) {
+  const request = { kind: 'command', command, json: false, dryRun: false };
+  if (command === 'compile' || command === 'build') request.clean = true;
+  return request;
+}
+
+function allowedRequestKeys(command) {
+  const keys = new Set(['command', 'json', 'dryRun', 'help']);
+  for (const option of publicOptionsForCommand(command)) keys.add(option.key);
+  for (const positional of COMMAND_SPECS[command].positionals) keys.add(positional.key);
+  return keys;
+}
+
+function finishCommandRequest(request) {
+  const allowed = allowedRequestKeys(request.command);
+  for (const key of Object.keys(request)) {
+    if (key === 'kind') continue;
+    if (!allowed.has(key)) throw new Error(`CLI request normalization leaked unsupported field ${request.command}.${key}`);
+  }
+  return deepFreeze(request);
+}
+
+function parseCommandRequest(argv) {
+  const input = Array.from(argv || []);
+  if (input.length === 0 || ['help', '--help', '-h'].includes(input[0])) return metaRequest('help');
+  if (['--version', '-v', 'version'].includes(input[0])) return metaRequest('version');
+  if (String(input[0]).toLowerCase() === 'completion') {
+    input.shift();
+    const shell = input.shift();
+    if (!shell || input.length > 0 || !COMPLETION_SHELLS.includes(String(shell).toLowerCase())) {
+      throw new PulseProjectError('PULSE_ARGUMENT_UNEXPECTED', 'Usage: pulse completion <bash|zsh|fish>.', { shell, allowed: COMPLETION_SHELLS });
+    }
+    return metaRequest('completion', { shell: String(shell).toLowerCase() });
+  }
+
+  const command = String(input.shift()).toLowerCase();
+  if (!COMMANDS.includes(command)) {
+    throw new PulseProjectError('PULSE_COMMAND_UNKNOWN', `Unknown pulse command "${command}".`, { command, allowed: COMMANDS });
+  }
+
+  const request = baseCommandRequest(command);
+  for (let index = 0; index < input.length; index += 1) {
+    const token = input[index];
+    const next = () => {
+      const value = input[++index];
+      if (value === undefined) throw new PulseProjectError('PULSE_ARGUMENT_MISSING', `Missing value after ${token}.`, { token });
+      return value;
+    };
+
+    if (token === '--provider' || String(token).startsWith('--provider=')) {
+      throw new PulseProjectError(
+        'PULSE_PROVIDER_FLAG_REMOVED',
+        'The public --provider override was removed. Configure the deployment provider in .pulse/config.ts; pulse compile is always provider-neutral and pulse build realizes the configured provider.',
+        { token, command, replacement: command === 'compile' ? 'pulse compile' : 'active profile in .pulse/config.ts' }
+      );
+    }
+    if (token === '--source-only') {
+      throw new PulseProjectError(
+        'PULSE_SOURCE_ONLY_REMOVED',
+        'The --source-only build mode was removed. Native builds always emit generated source and provider Wasm together.',
+        { token, command, replacement: 'pulse build' }
+      );
+    }
+
+    const match = optionForToken(token);
+    if (match) {
+      const { option, flag } = match;
+      if (!optionAllowed(option, command)) {
+        throw new PulseProjectError('PULSE_ARGUMENT_UNEXPECTED', `Unexpected pulse ${command} argument: ${token}`, { token, command });
+      }
+      let value;
+      if (option.kind === 'boolean') value = true;
+      else if (option.kind === 'boolean-value') value = flag.value;
+      else {
+        const raw = token === flag.name ? next() : token.slice(flag.name.length + 1);
+        if (raw === '') throw new PulseProjectError('PULSE_ARGUMENT_MISSING', `Missing value after ${flag.name}.`, { token: flag.name });
+        value = option.parse === 'number' ? Number(raw) : raw;
+      }
+      request[option.key] = value;
+      continue;
+    }
+
+    if (!token.startsWith('-')) {
+      if (command === 'init' && !request.target) {
+        request.target = token;
+        continue;
+      }
+      if (command !== 'init' && !request.directory) {
+        request.directory = token;
+        continue;
+      }
+    }
+    throw new PulseProjectError('PULSE_ARGUMENT_UNEXPECTED', `Unexpected pulse ${command} argument: ${token}`, { token, command });
+  }
+
+  return finishCommandRequest(request);
+}
+
+function isCommandRequest(value) {
+  return Boolean(value && value.kind === 'command' && COMMANDS.includes(value.command));
+}
+
+function isMetaRequest(value) {
+  return Boolean(value && value.kind === 'meta' && ['help', 'version', 'completion'].includes(value.invocation));
+}
+
+function normalizeCommandRequest(value) {
+  if (Array.isArray(value)) return parseCommandRequest(value);
+  if (isCommandRequest(value) || isMetaRequest(value)) return value;
+  if (!value || typeof value !== 'object') throw new TypeError('CLI command request must be argv or a parsed request object');
+
+  if (value.help && !value.command) return metaRequest('help');
+  if (value.version && !value.command) return metaRequest('version');
+  if (value.completion && !value.command) return metaRequest('completion', { shell: String(value.completion).toLowerCase() });
+  if (!COMMANDS.includes(value.command)) {
+    throw new PulseProjectError('PULSE_COMMAND_UNKNOWN', `Unknown pulse command "${value.command}".`, { command: value.command, allowed: COMMANDS });
+  }
+
+  const request = baseCommandRequest(value.command);
+  for (const key of allowedRequestKeys(value.command)) {
+    if (key === 'command') continue;
+    if (Object.prototype.hasOwnProperty.call(value, key) && value[key] !== undefined) request[key] = value[key];
+  }
+  return finishCommandRequest(request);
+}
+
+module.exports = deepFreeze({
+  parseCommandRequest,
+  normalizeCommandRequest,
+  isCommandRequest,
+  isMetaRequest
+});

package/src/internal/node-http.js

@@ -0,0 +1,54 @@
+'use strict';
+
+function normalizeHeaders(headers) {
+  if (!headers) return [];
+  if (Array.isArray(headers)) return headers.map((pair) => [String(pair[0]), String(pair[1])]);
+  if (typeof headers[Symbol.iterator] === 'function') {
+    return Array.from(headers, ([name, value]) => [String(name), String(value)]);
+  }
+  return Object.entries(headers).map(([name, value]) => [String(name), String(value)]);
+}
+
+function groupHeaders(headers) {
+  const order = [];
+  const groups = new Map();
+  for (const [name, value] of normalizeHeaders(headers)) {
+    const display = String(name);
+    const lower = display.toLowerCase();
+    if (!groups.has(lower)) {
+      groups.set(lower, { name: display, values: [] });
+      order.push(lower);
+    }
+    groups.get(lower).values.push(String(value));
+  }
+  return order.map((key) => groups.get(key));
+}
+
+function writeNodeHttpResponse(response, hostResult) {
+  const result = hostResult || { status: 500, kind: 'empty', headers: [] };
+  response.statusCode = result.status || 500;
+  for (const group of groupHeaders(result.headers || [])) {
+    response.setHeader(group.name, group.values.length === 1 ? group.values[0] : group.values.slice());
+  }
+  if (result.kind === 'stream' && result.bodyStream) {
+    if (typeof result.bodyStream.pipe === 'function') {
+      result.bodyStream.pipe(response);
+      return result;
+    }
+    if (Array.isArray(result.bodyStream.chunks)) {
+      for (const chunk of result.bodyStream.chunks) {
+        response.write(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk)));
+      }
+      response.end();
+      return result;
+    }
+    if (typeof result.bodyStream === 'string' || Buffer.isBuffer(result.bodyStream)) {
+      response.end(result.bodyStream);
+      return result;
+    }
+  }
+  response.end(result.body === undefined || result.body === null ? '' : String(result.body));
+  return result;
+}
+
+module.exports = Object.freeze({ groupHeaders, writeNodeHttpResponse });