@a2a-wrapper/core 1.2.0

package/README.md

@@ -0,0 +1,186 @@
+# @a2a-wrapper/core
+
+Shared infrastructure core for [A2A protocol](https://github.com/google/A2A) wrapper projects. Provides logging, configuration loading, event publishing, agent card building, server bootstrapping, session management, and CLI scaffolding — so each wrapper only needs to implement its backend-specific executor.
+
+## Installation
+
+```bash
+npm install @a2a-wrapper/core
+```
+
+Peer dependencies (your wrapper project must install these):
+
+```bash
+npm install @a2a-js/sdk express uuid
+```
+
+## Quick Start
+
+A minimal wrapper project using `createCli`:
+
+```typescript
+import {
+  createCli,
+  type BaseAgentConfig,
+  type A2AExecutor,
+} from "@a2a-wrapper/core";
+
+// 1. Define your backend-specific config
+interface MyBackendConfig {
+  apiUrl: string;
+}
+type MyConfig = BaseAgentConfig<MyBackendConfig>;
+
+// 2. Implement the executor interface
+class MyExecutor implements A2AExecutor {
+  constructor(private config: Required<MyConfig>) {}
+  async initialize() { /* connect to backend */ }
+  async shutdown() { /* cleanup */ }
+  async execute(context: any, event: any) { /* handle A2A tasks */ }
+}
+
+// 3. Wire it up with createCli
+createCli<MyConfig>({
+  packageName: "my-a2a-wrapper",
+  version: "1.0.0",
+  defaults: { /* full default config */ } as Required<MyConfig>,
+  usage: "Usage: my-a2a-wrapper [options]",
+  executorFactory: (config) => new MyExecutor(config),
+  parseBackendArgs: (values) => ({
+    backend: { apiUrl: values["api-url"] as string },
+  }),
+  loadEnvOverrides: () => ({
+    backend: { apiUrl: process.env.MY_API_URL },
+  }),
+  extraArgDefs: {
+    "api-url": { type: "string" },
+  },
+});
+```
+
+Run it:
+
+```bash
+node dist/cli.js --port 3000 --log-level debug --api-url http://localhost:8080
+```
+
+## API Reference
+
+All public symbols are exported from the package root (`@a2a-wrapper/core`). Imports from internal module paths are not supported.
+
+### Utils
+
+| Export | Description |
+|---|---|
+| `createLogger(rootName)` | Factory that returns a new `Logger` instance with the given root name. |
+| `Logger` | Structured logger with `debug`, `info`, `warn`, `error` methods and `child(name)` for hierarchical naming. |
+| `LogLevel` | Enum — `DEBUG`, `INFO`, `WARN`, `ERROR`. |
+| `createDeferred<T>()` | Returns a `Deferred<T>` with externally-resolvable `promise`, `resolve`, and `reject`. |
+| `sleep(ms)` | Returns a Promise that resolves after `ms` milliseconds. |
+| `deepMerge(target, source)` | Recursively merges objects. Arrays are replaced, inputs are not mutated. |
+| `substituteEnvTokens(args)` | Replaces `$VAR_NAME` tokens in string arrays with matching env var values. |
+
+### Config
+
+| Export | Description |
+|---|---|
+| `BaseAgentConfig<TBackend>` | Generic config interface — includes `agentCard`, `server`, `session`, `logging`, `timeouts`, and `backend: TBackend`. |
+| `AgentCardConfig` | Agent card fields (name, description, skills, capabilities). |
+| `ServerConfig` | Server fields (port, hostname, advertiseHost, advertiseProtocol). |
+| `SessionConfig` | Session fields (reuseByContext, ttlMs, cleanupIntervalMs). |
+| `BaseFeatureFlags` | Shared feature flags (`streamArtifactChunks`). |
+| `TimeoutConfig` | Timeout settings. |
+| `LoggingConfig` | Logging settings (level). |
+| `BaseMcpServerConfig` | Common MCP server config pattern. |
+| `SkillConfig` | Skill definition (id, name, description, tags, examples). |
+| `loadConfigFile<T>(filePath)` | Reads and parses a JSON config file. Throws descriptive errors on failure. |
+| `resolveConfig<T>(defaults, configFilePath?, envOverrides?, cliOverrides?)` | Merges config layers: defaults ← file ← env ← CLI. |
+
+### Events
+
+| Export | Description |
+|---|---|
+| `publishStatus(bus, taskId, contextId, state, messageText?, final?)` | Publishes a `TaskStatusUpdateEvent`. |
+| `publishFinalArtifact(bus, taskId, contextId, text)` | Publishes a complete artifact (`lastChunk: true`). |
+| `publishStreamingChunk(bus, taskId, contextId, artifactId, chunkText)` | Publishes an appending artifact chunk. |
+| `publishLastChunkMarker(bus, taskId, contextId, artifactId, fullText)` | Publishes the final streaming chunk. |
+| `publishTraceArtifact(bus, taskId, contextId, traceKey, data)` | Publishes a structured `DataPart` trace artifact. |
+| `publishThoughtArtifact(bus, taskId, contextId, traceKey, text)` | Publishes a `TextPart` trace artifact. |
+
+### Server
+
+| Export | Description |
+|---|---|
+| `buildAgentCard(config)` | Constructs an A2A `AgentCard` from `AgentCardConfig` + `ServerConfig`. |
+| `createA2AServer<T>(config, executorFactory, options?)` | Creates an Express app with standard A2A routes and starts listening. Returns a `ServerHandle`. |
+| `ServerOptions` | Options for protocol version, custom route hooks. |
+| `ServerHandle` | Returned by `createA2AServer` — contains `app`, `server`, `executor`, `shutdown()`. |
+
+### Session
+
+| Export | Description |
+|---|---|
+| `BaseSessionManager<TSession>` | Abstract class managing contextId → session mapping with TTL cleanup and task tracking. Subclass and implement `getOrCreate(contextId)`. |
+| `SessionEntry<TSession>` | Interface for session entries with `session` and `lastUsed` fields. |
+
+### Executor
+
+| Export | Description |
+|---|---|
+| `A2AExecutor` | Interface contract for backend executors — `initialize()`, `shutdown()`, `execute()`, and optional `cancelTask()`, `getContextContent()`, `buildContext()`. |
+
+### CLI
+
+| Export | Description |
+|---|---|
+| `createCli<T>(options)` | Main entry point for wrapper CLIs. Handles arg parsing, config resolution, server creation, and graceful shutdown. |
+| `CliOptions<T>` | Configuration for `createCli` — package name, version, defaults, usage, executor factory, arg definitions. |
+| `parseCommonArgs<T>(argv, extraArgDefs?)` | Parses common CLI flags (`--port`, `--hostname`, `--log-level`, etc.) into typed config overrides. |
+| `CommonArgsResult<T>` | Result of `parseCommonArgs` — config path and partial overrides. |
+
+### A2A SDK Re-exports
+
+| Export | Source |
+|---|---|
+| `AgentCard` | `@a2a-js/sdk` |
+| `TaskState`, `TaskStatusUpdateEvent`, `TaskArtifactUpdateEvent` | `@a2a-js/sdk` |
+| `ExecutionEventBus`, `RequestContext` | `@a2a-js/sdk/server` |
+
+These re-exports isolate wrapper projects from direct SDK imports, so a major SDK upgrade only requires changes in `@a2a-wrapper/core`.
+
+## Contributing
+
+### Prerequisites
+
+- Node.js ≥ 18
+- npm
+
+### Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Run tests
+npm test
+
+# Type-check without emitting
+npm run typecheck
+
+# Clean build output
+npm run clean
+```
+
+### Code Standards
+
+- TypeScript with `strict: true`
+- JSDoc on every exported symbol
+- Property-based tests (fast-check) alongside unit tests (vitest)
+- Follow [Keep a Changelog](https://keepachangelog.com/) for CHANGELOG.md
+
+## License
+
+MIT

package/dist/cli/scaffold.d.ts

@@ -0,0 +1,237 @@
+/**
+ * CLI Scaffold
+ *
+ * Provides a reusable, generic CLI entry-point factory for A2A wrapper
+ * projects. Each wrapper calls {@link createCli} once with its package
+ * metadata, default configuration, backend-specific argument parser, and
+ * executor factory. The scaffold handles everything else: common flag
+ * parsing, layered config resolution, log-level setup, server creation,
+ * and graceful shutdown on SIGINT / SIGTERM.
+ *
+ * This module is intentionally backend-agnostic. Wrapper-specific flags
+ * (e.g. `--cli-url`, `--opencode-url`) are injected via
+ * {@link CliOptions.extraArgDefs} and parsed by the wrapper's
+ * {@link CliOptions.parseBackendArgs} callback.
+ *
+ * The exported {@link parseCommonArgs} helper is also available for unit
+ * and property-based testing of the common flag parsing logic without
+ * triggering the full main-loop side effects.
+ *
+ * @module cli/scaffold
+ */
+import type { BaseAgentConfig } from "../config/types.js";
+import type { ServerOptions, A2AExecutor } from "../server/factory.js";
+/**
+ * Configuration object accepted by {@link createCli}.
+ *
+ * Each wrapper project constructs a `CliOptions` value that wires together
+ * its package metadata, default configuration, backend-specific argument
+ * parsing, environment variable loading, and executor factory. The CLI
+ * scaffold uses these to implement the full main-loop without any
+ * backend-specific knowledge.
+ *
+ * @typeParam T - The full configuration type for the wrapper project.
+ *   Must extend {@link BaseAgentConfig} so that the shared config sections
+ *   (agentCard, server, session, logging, etc.) are guaranteed to exist.
+ *
+ * @example
+ * ```typescript
+ * import { createCli, type CliOptions } from "@a2a-wrapper/core";
+ * import type { AgentConfig } from "./config/types.js";
+ *
+ * const options: CliOptions<AgentConfig> = {
+ *   packageName: "a2a-copilot",
+ *   version: "1.0.0",
+ *   defaults: DEFAULTS,
+ *   usage: "Usage: a2a-copilot [options]\n...",
+ *   parseBackendArgs: (values) => ({ ... }),
+ *   loadEnvOverrides: () => ({ ... }),
+ *   executorFactory: (config) => new CopilotExecutor(config),
+ * };
+ *
+ * createCli(options);
+ * ```
+ */
+export interface CliOptions<T extends BaseAgentConfig<unknown>> {
+    /**
+     * Package name used in `--help` output and log messages.
+     *
+     * @example "a2a-copilot"
+     */
+    packageName: string;
+    /**
+     * Package version printed by `--version`.
+     *
+     * @example "1.2.3"
+     */
+    version: string;
+    /**
+     * Complete default configuration object with every field populated.
+     *
+     * This serves as the base layer in the config merge pipeline
+     * (defaults ← file ← env ← CLI).
+     */
+    defaults: Required<T>;
+    /**
+     * Usage text printed when `--help` is passed.
+     *
+     * Should include all common and wrapper-specific flags with descriptions
+     * and examples.
+     */
+    usage: string;
+    /**
+     * Parse wrapper-specific CLI arguments into config overrides.
+     *
+     * Called after common flags (`--port`, `--hostname`, etc.) have been
+     * extracted. The `values` parameter contains the raw parsed values from
+     * `node:util/parseArgs`, including both common and extra arg definitions.
+     * The callback should return a partial config containing only the
+     * backend-specific fields derived from wrapper-specific flags.
+     *
+     * @param values - Raw parsed argument values from `parseArgs`.
+     * @returns Partial configuration with backend-specific overrides.
+     */
+    parseBackendArgs: (values: Record<string, unknown>) => Partial<T>;
+    /**
+     * Load wrapper-specific environment variable overrides.
+     *
+     * Called during config resolution to inject environment-based overrides
+     * into the merge pipeline (layer 2: env overrides).
+     *
+     * @returns Partial configuration with environment-derived overrides.
+     */
+    loadEnvOverrides: () => Partial<T>;
+    /**
+     * Factory function that creates the backend-specific executor.
+     *
+     * Called with the fully resolved configuration after all merge layers
+     * have been applied. The returned executor is passed to
+     * {@link createA2AServer} for initialization and request handling.
+     *
+     * @param config - The fully resolved configuration.
+     * @returns A new {@link A2AExecutor} instance.
+     */
+    executorFactory: (config: Required<T>) => A2AExecutor;
+    /**
+     * Optional server customization options.
+     *
+     * Passed through to {@link createA2AServer} for protocol version
+     * overrides and custom route registration hooks.
+     */
+    serverOptions?: ServerOptions;
+    /**
+     * Additional `parseArgs` option definitions for wrapper-specific flags.
+     *
+     * These are merged with the common flag definitions before calling
+     * `node:util/parseArgs`. Keys are flag names (without `--` prefix),
+     * values specify the type and optional short alias.
+     *
+     * @example
+     * ```typescript
+     * extraArgDefs: {
+     *   "cli-url":   { type: "string" },
+     *   "model":     { type: "string", short: "m" },
+     *   "workspace": { type: "string", short: "w" },
+     * }
+     * ```
+     */
+    extraArgDefs?: Record<string, {
+        type: "string" | "boolean";
+        short?: string;
+    }>;
+}
+/**
+ * Result of parsing common CLI flags via {@link parseCommonArgs}.
+ *
+ * Contains the config file path (if specified) and a partial config object
+ * with overrides derived from the common flags. This type is intentionally
+ * generic so that the partial config can be merged with wrapper-specific
+ * overrides before being passed to {@link resolveConfig}.
+ *
+ * @typeParam T - The full configuration type (extends {@link BaseAgentConfig}).
+ */
+export interface CommonArgsResult<T extends BaseAgentConfig<unknown>> {
+    /** Path to the JSON config file, if `--agent-json` or `--config` was provided. */
+    configPath?: string;
+    /** Partial config overrides derived from common CLI flags. */
+    overrides: Partial<T>;
+}
+/**
+ * Extract common CLI overrides from raw parsed argument values.
+ *
+ * This pure function maps the shared CLI flags (`--port`, `--hostname`,
+ * `--advertise-host`, `--agent-name`, `--agent-description`,
+ * `--stream-artifacts` / `--no-stream-artifacts`, `--log-level`) into a
+ * partial {@link BaseAgentConfig} structure suitable for merging into the
+ * config resolution pipeline.
+ *
+ * Exported separately from {@link createCli} so that property-based tests
+ * can validate flag-to-config mapping without triggering the full
+ * main-loop side effects (server creation, signal handlers, etc.).
+ *
+ * @typeParam T - The full configuration type (extends {@link BaseAgentConfig}).
+ *
+ * @param values - Raw parsed argument values from `node:util/parseArgs`.
+ *   Expected to contain string/boolean entries keyed by flag name (without
+ *   the `--` prefix).
+ * @returns A {@link CommonArgsResult} with the config file path and
+ *   partial config overrides.
+ *
+ * @example
+ * ```typescript
+ * import { parseCommonArgs } from "@a2a-wrapper/core";
+ *
+ * const result = parseCommonArgs({ port: "3001", "agent-name": "Test" });
+ * // result.overrides.server?.port === 3001
+ * // result.overrides.agentCard?.name === "Test"
+ * ```
+ */
+export declare function parseCommonArgs<T extends BaseAgentConfig<unknown>>(values: Record<string, unknown>): CommonArgsResult<T>;
+/**
+ * Create and run the CLI entry point for an A2A wrapper project.
+ *
+ * Implements the standard main-loop pattern shared by all wrappers:
+ *
+ * 1. **Parse arguments** — merges common flag definitions with any
+ *    wrapper-specific {@link CliOptions.extraArgDefs}, then calls
+ *    `node:util/parseArgs`. Handles `--help` (print usage, exit 0) and
+ *    `--version` (print version, exit 0) immediately.
+ * 2. **Resolve configuration** — calls {@link parseCommonArgs} for shared
+ *    flags, {@link CliOptions.parseBackendArgs} for wrapper-specific flags,
+ *    and {@link CliOptions.loadEnvOverrides} for environment variables.
+ *    Merges all layers via {@link resolveConfig}: defaults ← file ← env ← CLI.
+ * 3. **Set log level** — parses the resolved `logging.level` string and
+ *    applies it to the root logger.
+ * 4. **Create server** — calls {@link createA2AServer} with the resolved
+ *    config, executor factory, and optional server options.
+ * 5. **Register signal handlers** — installs SIGINT and SIGTERM handlers
+ *    that call `handle.shutdown()` and exit cleanly.
+ * 6. **Fatal error handling** — wraps the entire main-loop in a catch
+ *    that logs the error with stack trace and exits with code 1.
+ *
+ * @typeParam T - The full configuration type for the wrapper project.
+ *   Must extend {@link BaseAgentConfig} so that the shared config sections
+ *   are guaranteed to exist.
+ *
+ * @param options - CLI configuration specifying package metadata, defaults,
+ *   argument parsers, and the executor factory.
+ *
+ * @example
+ * ```typescript
+ * import { createCli } from "@a2a-wrapper/core";
+ * import { DEFAULTS } from "./config/defaults.js";
+ * import { CopilotExecutor } from "./copilot/executor.js";
+ *
+ * createCli({
+ *   packageName: "a2a-copilot",
+ *   version: "1.0.0",
+ *   defaults: DEFAULTS,
+ *   usage: "Usage: a2a-copilot [options]\n...",
+ *   parseBackendArgs: (values) => { ... },
+ *   loadEnvOverrides: () => { ... },
+ *   executorFactory: (config) => new CopilotExecutor(config),
+ * });
+ * ```
+ */
+export declare function createCli<T extends BaseAgentConfig<unknown>>(options: CliOptions<T>): void;
+//# sourceMappingURL=scaffold.d.ts.map

package/dist/cli/scaffold.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scaffold.d.ts","sourceRoot":"","sources":["../../src/cli/scaffold.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAKH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAG1D,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AA6BvE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,WAAW,UAAU,CAAC,CAAC,SAAS,eAAe,CAAC,OAAO,CAAC;IAC5D;;;;OAIG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;;;OAIG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;;;;OAKG;IACH,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC;IAEtB;;;;;OAKG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;;;;;;;;;;OAWG;IACH,gBAAgB,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;IAElE;;;;;;;OAOG;IACH,gBAAgB,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,CAAC;IAEnC;;;;;;;;;OASG;IACH,eAAe,EAAE,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC,KAAK,WAAW,CAAC;IAEtD;;;;;OAKG;IACH,aAAa,CAAC,EAAE,aAAa,CAAC;IAE9B;;;;;;;;;;;;;;;OAeG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,QAAQ,GAAG,SAAS,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC/E;AAID;;;;;;;;;GASG;AACH,MAAM,WAAW,gBAAgB,CAAC,CAAC,SAAS,eAAe,CAAC,OAAO,CAAC;IAClE,kFAAkF;IAClF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8DAA8D;IAC9D,SAAS,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;CACvB;AAID;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,eAAe,CAAC,OAAO,CAAC,EAChE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,gBAAgB,CAAC,CAAC,CAAC,CAiDrB;AAID;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,eAAe,CAAC,OAAO,CAAC,EAC1D,OAAO,EAAE,UAAU,CAAC,CAAC,CAAC,GACrB,IAAI,CAuGN"}

package/dist/cli/scaffold.js

@@ -0,0 +1,241 @@
+/**
+ * CLI Scaffold
+ *
+ * Provides a reusable, generic CLI entry-point factory for A2A wrapper
+ * projects. Each wrapper calls {@link createCli} once with its package
+ * metadata, default configuration, backend-specific argument parser, and
+ * executor factory. The scaffold handles everything else: common flag
+ * parsing, layered config resolution, log-level setup, server creation,
+ * and graceful shutdown on SIGINT / SIGTERM.
+ *
+ * This module is intentionally backend-agnostic. Wrapper-specific flags
+ * (e.g. `--cli-url`, `--opencode-url`) are injected via
+ * {@link CliOptions.extraArgDefs} and parsed by the wrapper's
+ * {@link CliOptions.parseBackendArgs} callback.
+ *
+ * The exported {@link parseCommonArgs} helper is also available for unit
+ * and property-based testing of the common flag parsing logic without
+ * triggering the full main-loop side effects.
+ *
+ * @module cli/scaffold
+ */
+import { parseArgs } from "node:util";
+import { resolveConfig } from "../config/loader.js";
+import { createLogger, Logger } from "../utils/logger.js";
+import { createA2AServer } from "../server/factory.js";
+// ─── Common Arg Definitions ────────────────────────────────────────────────
+/**
+ * `parseArgs` option definitions for the flags shared across all wrappers.
+ *
+ * These are merged with any wrapper-specific {@link CliOptions.extraArgDefs}
+ * before calling `node:util/parseArgs`.
+ *
+ * @internal
+ */
+const COMMON_ARG_DEFS = {
+    "agent-json": { type: "string" },
+    config: { type: "string", short: "c" },
+    port: { type: "string", short: "p" },
+    hostname: { type: "string" },
+    "advertise-host": { type: "string" },
+    "agent-name": { type: "string" },
+    "agent-description": { type: "string" },
+    "stream-artifacts": { type: "boolean" },
+    "no-stream-artifacts": { type: "boolean" },
+    "log-level": { type: "string" },
+    help: { type: "boolean", short: "h" },
+    version: { type: "boolean", short: "v" },
+};
+// ─── parseCommonArgs ───────────────────────────────────────────────────────
+/**
+ * Extract common CLI overrides from raw parsed argument values.
+ *
+ * This pure function maps the shared CLI flags (`--port`, `--hostname`,
+ * `--advertise-host`, `--agent-name`, `--agent-description`,
+ * `--stream-artifacts` / `--no-stream-artifacts`, `--log-level`) into a
+ * partial {@link BaseAgentConfig} structure suitable for merging into the
+ * config resolution pipeline.
+ *
+ * Exported separately from {@link createCli} so that property-based tests
+ * can validate flag-to-config mapping without triggering the full
+ * main-loop side effects (server creation, signal handlers, etc.).
+ *
+ * @typeParam T - The full configuration type (extends {@link BaseAgentConfig}).
+ *
+ * @param values - Raw parsed argument values from `node:util/parseArgs`.
+ *   Expected to contain string/boolean entries keyed by flag name (without
+ *   the `--` prefix).
+ * @returns A {@link CommonArgsResult} with the config file path and
+ *   partial config overrides.
+ *
+ * @example
+ * ```typescript
+ * import { parseCommonArgs } from "@a2a-wrapper/core";
+ *
+ * const result = parseCommonArgs({ port: "3001", "agent-name": "Test" });
+ * // result.overrides.server?.port === 3001
+ * // result.overrides.agentCard?.name === "Test"
+ * ```
+ */
+export function parseCommonArgs(values) {
+    const overrides = {};
+    // Config file path (--agent-json or --config)
+    const configPath = (values["agent-json"] ?? values["config"]);
+    // Server overrides
+    const port = values["port"];
+    const hostname = values["hostname"];
+    const advertiseHost = values["advertise-host"];
+    if (port !== undefined || hostname !== undefined || advertiseHost !== undefined) {
+        const server = {};
+        if (port !== undefined)
+            server.port = parseInt(port, 10);
+        if (hostname !== undefined)
+            server.hostname = hostname;
+        if (advertiseHost !== undefined)
+            server.advertiseHost = advertiseHost;
+        overrides.server = server;
+    }
+    // Agent card overrides
+    const agentName = values["agent-name"];
+    const agentDescription = values["agent-description"];
+    if (agentName !== undefined || agentDescription !== undefined) {
+        const agentCard = {};
+        if (agentName !== undefined)
+            agentCard.name = agentName;
+        if (agentDescription !== undefined)
+            agentCard.description = agentDescription;
+        overrides.agentCard = agentCard;
+    }
+    // Feature flag overrides
+    const streamArtifacts = values["stream-artifacts"];
+    const noStreamArtifacts = values["no-stream-artifacts"];
+    const features = {};
+    if (streamArtifacts === true)
+        features.streamArtifactChunks = true;
+    if (noStreamArtifacts === true)
+        features.streamArtifactChunks = false;
+    if (Object.keys(features).length > 0) {
+        overrides.features = features;
+    }
+    // Logging overrides
+    const logLevel = values["log-level"];
+    if (logLevel !== undefined) {
+        overrides.logging = { level: logLevel };
+    }
+    return { configPath, overrides: overrides };
+}
+// ─── createCli ─────────────────────────────────────────────────────────────
+/**
+ * Create and run the CLI entry point for an A2A wrapper project.
+ *
+ * Implements the standard main-loop pattern shared by all wrappers:
+ *
+ * 1. **Parse arguments** — merges common flag definitions with any
+ *    wrapper-specific {@link CliOptions.extraArgDefs}, then calls
+ *    `node:util/parseArgs`. Handles `--help` (print usage, exit 0) and
+ *    `--version` (print version, exit 0) immediately.
+ * 2. **Resolve configuration** — calls {@link parseCommonArgs} for shared
+ *    flags, {@link CliOptions.parseBackendArgs} for wrapper-specific flags,
+ *    and {@link CliOptions.loadEnvOverrides} for environment variables.
+ *    Merges all layers via {@link resolveConfig}: defaults ← file ← env ← CLI.
+ * 3. **Set log level** — parses the resolved `logging.level` string and
+ *    applies it to the root logger.
+ * 4. **Create server** — calls {@link createA2AServer} with the resolved
+ *    config, executor factory, and optional server options.
+ * 5. **Register signal handlers** — installs SIGINT and SIGTERM handlers
+ *    that call `handle.shutdown()` and exit cleanly.
+ * 6. **Fatal error handling** — wraps the entire main-loop in a catch
+ *    that logs the error with stack trace and exits with code 1.
+ *
+ * @typeParam T - The full configuration type for the wrapper project.
+ *   Must extend {@link BaseAgentConfig} so that the shared config sections
+ *   are guaranteed to exist.
+ *
+ * @param options - CLI configuration specifying package metadata, defaults,
+ *   argument parsers, and the executor factory.
+ *
+ * @example
+ * ```typescript
+ * import { createCli } from "@a2a-wrapper/core";
+ * import { DEFAULTS } from "./config/defaults.js";
+ * import { CopilotExecutor } from "./copilot/executor.js";
+ *
+ * createCli({
+ *   packageName: "a2a-copilot",
+ *   version: "1.0.0",
+ *   defaults: DEFAULTS,
+ *   usage: "Usage: a2a-copilot [options]\n...",
+ *   parseBackendArgs: (values) => { ... },
+ *   loadEnvOverrides: () => { ... },
+ *   executorFactory: (config) => new CopilotExecutor(config),
+ * });
+ * ```
+ */
+export function createCli(options) {
+    const { packageName, version, defaults, usage, parseBackendArgs, loadEnvOverrides, executorFactory, serverOptions, extraArgDefs, } = options;
+    const logger = createLogger(packageName);
+    const log = logger.child("cli");
+    // ── Async main loop ───────────────────────────────────────────────────
+    async function main() {
+        // 1. Parse CLI arguments
+        const allArgDefs = { ...COMMON_ARG_DEFS, ...extraArgDefs };
+        const { values } = parseArgs({
+            options: allArgDefs,
+            strict: false,
+        });
+        // Handle --help
+        if (values.help) {
+            console.log(usage);
+            process.exit(0);
+        }
+        // Handle --version
+        if (values.version) {
+            console.log(version);
+            process.exit(0);
+        }
+        // 2. Build config overrides from common + backend args
+        const commonResult = parseCommonArgs(values);
+        const backendOverrides = parseBackendArgs(values);
+        // Merge common overrides with backend overrides for the CLI layer
+        const cliOverrides = {
+            ...commonResult.overrides,
+            ...backendOverrides,
+        };
+        // Load environment variable overrides
+        const envOverrides = loadEnvOverrides();
+        // 3. Resolve config: defaults ← file ← env ← CLI
+        const config = resolveConfig(defaults, commonResult.configPath, envOverrides, cliOverrides);
+        // 4. Set log level
+        const levelStr = config.logging?.level ?? "info";
+        logger.setLevel(Logger.parseLevel(levelStr));
+        if (!commonResult.configPath) {
+            log.info("No --agent-json provided — running with built-in defaults. " +
+                "Pass --agent-json <path> to load a custom agent.");
+        }
+        log.info(`Starting ${packageName}`, {
+            config: commonResult.configPath ?? "(built-in defaults)",
+            agent: config.agentCard?.name,
+            port: config.server?.port,
+        });
+        // 5. Create and start the A2A server
+        const handle = await createA2AServer(config, executorFactory, serverOptions);
+        // 6. Register graceful shutdown handlers
+        const shutdown = async (signal) => {
+            log.info(`${signal} received, shutting down...`);
+            await handle.shutdown();
+            process.exit(0);
+        };
+        process.on("SIGINT", () => shutdown("SIGINT"));
+        process.on("SIGTERM", () => shutdown("SIGTERM"));
+    }
+    // Fatal error handler — log with stack trace and exit 1
+    main().catch((err) => {
+        const error = err instanceof Error ? err : new Error(String(err));
+        log.error("Fatal error", {
+            error: error.message,
+            stack: error.stack,
+        });
+        process.exit(1);
+    });
+}
+//# sourceMappingURL=scaffold.js.map

package/dist/cli/scaffold.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scaffold.js","sourceRoot":"","sources":["../../src/cli/scaffold.ts"],"names":[],"mappings":"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"}