@substrate-ai/core 0.19.54

package/dist/adapters/worker-adapter.d.ts

@@ -0,0 +1,188 @@
+/**
+ * WorkerAdapter interface definition
+ *
+ * This is the core pluggable interface that all CLI agent adapters must implement.
+ * Adding a new adapter requires only creating a class that satisfies this interface
+ * — no modifications to the orchestrator core are needed (NFR11, FR14).
+ *
+ * @example
+ * ```typescript
+ * class MyCustomAdapter implements WorkerAdapter {
+ *   readonly id: AgentId = 'my-custom-agent'
+ *   readonly displayName = 'My Custom Agent'
+ *   readonly adapterVersion = '1.0.0'
+ *   // ... implement all 7 methods
+ * }
+ * ```
+ */
+import type { AgentId } from '../types.js';
+import type { SpawnCommand, AdapterOptions, AdapterCapabilities, AdapterHealthResult, TaskResult, TokenEstimate, PlanRequest, PlanParseResult, DiscoveryReport } from './types.js';
+/**
+ * WorkerAdapter — the interface every CLI agent adapter must implement.
+ *
+ * Adapters are responsible for:
+ * 1. Verifying their CLI binary is installed and responsive (healthCheck)
+ * 2. Constructing the spawn command to execute a task (buildCommand)
+ * 3. Constructing the spawn command for plan generation (buildPlanningCommand)
+ * 4. Parsing task result output from the CLI (parseOutput)
+ * 5. Parsing plan result output from the CLI (parsePlanOutput)
+ * 6. Estimating token usage for budget tracking (estimateTokens)
+ * 7. Reporting their capabilities for routing decisions (getCapabilities)
+ */
+export interface WorkerAdapter {
+    /**
+     * Unique identifier for this adapter type.
+     * Used as the Map key in AdapterRegistry.
+     * @example "claude-code"
+     */
+    readonly id: AgentId;
+    /**
+     * Human-readable display name for the adapter.
+     * @example "Claude Code"
+     */
+    readonly displayName: string;
+    /**
+     * Semantic version of this adapter implementation.
+     * @example "1.0.0"
+     */
+    readonly adapterVersion: string;
+    /**
+     * Verify that the underlying CLI binary is installed, accessible, and
+     * able to respond in headless/non-interactive mode.
+     *
+     * This method must NOT throw — failures should be captured in the returned
+     * AdapterHealthResult.
+     *
+     * @returns A promise resolving to health check details
+     *
+     * @example
+     * ```typescript
+     * const result = await adapter.healthCheck()
+     * if (!result.healthy) console.error(result.error)
+     * ```
+     */
+    healthCheck(): Promise<AdapterHealthResult>;
+    /**
+     * Generate the spawn command to execute a coding task.
+     *
+     * The returned SpawnCommand must set `cwd` to options.worktreePath so the
+     * CLI agent operates in the correct git worktree (NFR10).
+     *
+     * @param prompt   Prompt or description of the task to execute
+     * @param options  Per-invocation execution options
+     * @returns SpawnCommand ready to be executed by the orchestrator
+     *
+     * @example
+     * ```typescript
+     * const cmd = adapter.buildCommand('Fix the failing tests', { worktreePath: '/tmp/wt', billingMode: 'api' })
+     * // spawn(cmd.binary, cmd.args, { cwd: cmd.cwd, env: { ...process.env, ...cmd.env } })
+     * ```
+     */
+    buildCommand(prompt: string, options: AdapterOptions): SpawnCommand;
+    /**
+     * Generate the spawn command to invoke the CLI agent for plan generation.
+     *
+     * @param request  Plan request with goal and context
+     * @param options  Per-invocation execution options
+     * @returns SpawnCommand for the planning invocation
+     */
+    buildPlanningCommand(request: PlanRequest, options: AdapterOptions): SpawnCommand;
+    /**
+     * Parse the raw CLI process output into a normalized TaskResult.
+     *
+     * This method must handle all output variations including:
+     * - Valid JSON stdout
+     * - Non-JSON stdout (fallback)
+     * - Non-zero exit codes
+     * - Combined stdout + stderr
+     *
+     * @param stdout    Standard output captured from the CLI process
+     * @param stderr    Standard error captured from the CLI process
+     * @param exitCode  Exit code from the CLI process
+     * @returns Normalized TaskResult
+     */
+    parseOutput(stdout: string, stderr: string, exitCode: number): TaskResult;
+    /**
+     * Parse the raw CLI output from a planning invocation into a PlanParseResult.
+     *
+     * @param stdout    Standard output from the planning invocation
+     * @param stderr    Standard error from the planning invocation
+     * @param exitCode  Exit code from the planning invocation
+     * @returns Parsed plan result
+     */
+    parsePlanOutput(stdout: string, stderr: string, exitCode: number): PlanParseResult;
+    /**
+     * Estimate the token count for a given prompt string.
+     *
+     * Used for pre-execution budget checks. Implementations may use heuristics
+     * (e.g., character count / 3) when exact tokenizers are unavailable.
+     *
+     * @param prompt  The prompt text to estimate
+     * @returns TokenEstimate with input, output, and total projections
+     *
+     * @example
+     * ```typescript
+     * const estimate = adapter.estimateTokens('Fix the failing tests in auth.ts')
+     * if (estimate.total > budgetCap) throw new BudgetExceededError(...)
+     * ```
+     */
+    estimateTokens(prompt: string): TokenEstimate;
+    /**
+     * Return the capabilities of this adapter's underlying CLI agent.
+     *
+     * The returned object is used by the orchestrator for:
+     * - Routing decisions (which adapter handles which task type)
+     * - Plan generation eligibility
+     * - Budget mode selection
+     *
+     * @returns AdapterCapabilities for this agent
+     */
+    getCapabilities(): AdapterCapabilities;
+}
+/**
+ * AdapterRegistry — public interface for the adapter registry.
+ *
+ * Defined here (not in types.ts) to avoid a circular dependency between
+ * types.ts and worker-adapter.ts. AdapterRegistry references WorkerAdapter,
+ * which is defined in this file, so placing it here keeps the dep graph acyclic.
+ *
+ * The concrete implementation (AdapterRegistry class) lives in the monolith
+ * until Epic 41. This interface exposes only the public method surface.
+ *
+ * Usage:
+ * ```typescript
+ * const registry: AdapterRegistry = new ConcreteAdapterRegistry()
+ * const report = await registry.discoverAndRegister()
+ * const claude = registry.get('claude-code')
+ * ```
+ */
+export interface AdapterRegistry {
+    /**
+     * Register an adapter by its id.
+     * Overwrites any existing adapter with the same id.
+     */
+    register(adapter: WorkerAdapter): void;
+    /**
+     * Retrieve a registered adapter by id.
+     * @returns The adapter, or undefined if not registered
+     */
+    get(id: AgentId): WorkerAdapter | undefined;
+    /**
+     * Return all registered adapters as an array.
+     */
+    getAll(): WorkerAdapter[];
+    /**
+     * Return all registered adapters that support plan generation.
+     */
+    getPlanningCapable(): WorkerAdapter[];
+    /**
+     * Instantiate all built-in adapters, run health checks sequentially,
+     * and register those that pass.
+     *
+     * Failed adapters are included in the report but do NOT prevent startup.
+     *
+     * @returns Discovery report with per-adapter results
+     */
+    discoverAndRegister(): Promise<DiscoveryReport>;
+}
+//# sourceMappingURL=worker-adapter.d.ts.map

package/dist/adapters/worker-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-adapter.d.ts","sourceRoot":"","sources":["../../src/adapters/worker-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAA;AAC1C,OAAO,KAAK,EACV,YAAY,EACZ,cAAc,EACd,mBAAmB,EACnB,mBAAmB,EACnB,UAAU,EACV,aAAa,EACb,WAAW,EACX,eAAe,EACf,eAAe,EAChB,MAAM,YAAY,CAAA;AAEnB;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,aAAa;IAG5B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAA;IAEpB;;;OAGG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAE5B;;;OAGG;IACH,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;IAI/B;;;;;;;;;;;;;;OAcG;IACH,WAAW,IAAI,OAAO,CAAC,mBAAmB,CAAC,CAAA;IAE3C;;;;;;;;;;;;;;;OAeG;IACH,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,YAAY,CAAA;IAEnE;;;;;;OAMG;IACH,oBAAoB,CAAC,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,cAAc,GAAG,YAAY,CAAA;IAEjF;;;;;;;;;;;;;OAaG;IACH,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,UAAU,CAAA;IAEzE;;;;;;;OAOG;IACH,eAAe,CACb,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,GACf,eAAe,CAAA;IAElB;;;;;;;;;;;;;;OAcG;IACH,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,CAAA;IAE7C;;;;;;;;;OASG;IACH,eAAe,IAAI,mBAAmB,CAAA;CACvC;AAMD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,aAAa,GAAG,IAAI,CAAA;IAEtC;;;OAGG;IACH,GAAG,CAAC,EAAE,EAAE,OAAO,GAAG,aAAa,GAAG,SAAS,CAAA;IAE3C;;OAEG;IACH,MAAM,IAAI,aAAa,EAAE,CAAA;IAEzB;;OAEG;IACH,kBAAkB,IAAI,aAAa,EAAE,CAAA;IAErC;;;;;;;OAOG;IACH,mBAAmB,IAAI,OAAO,CAAC,eAAe,CAAC,CAAA;CAChD"}

package/dist/adapters/worker-adapter.js

@@ -0,0 +1,19 @@
+/**
+ * WorkerAdapter interface definition
+ *
+ * This is the core pluggable interface that all CLI agent adapters must implement.
+ * Adding a new adapter requires only creating a class that satisfies this interface
+ * — no modifications to the orchestrator core are needed (NFR11, FR14).
+ *
+ * @example
+ * ```typescript
+ * class MyCustomAdapter implements WorkerAdapter {
+ *   readonly id: AgentId = 'my-custom-agent'
+ *   readonly displayName = 'My Custom Agent'
+ *   readonly adapterVersion = '1.0.0'
+ *   // ... implement all 7 methods
+ * }
+ * ```
+ */
+export {};
+//# sourceMappingURL=worker-adapter.js.map

package/dist/adapters/worker-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-adapter.js","sourceRoot":"","sources":["../../src/adapters/worker-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG"}

package/dist/budget/budget-tracker.d.ts

@@ -0,0 +1,22 @@
+/**
+ * BudgetTracker — interface and stub for tracking token/cost budgets.
+ * Migrated to @substrate-ai/core (Story 41-7)
+ */
+import type { IBaseService } from '../types.js';
+import type { TypedEventBus, CoreEvents } from '../events/index.js';
+import type { ILogger } from '../dispatch/types.js';
+export interface BudgetTracker extends IBaseService {
+}
+export declare class BudgetTrackerImpl implements BudgetTracker {
+    private readonly _eventBus;
+    private readonly _logger;
+    constructor(eventBus: TypedEventBus<CoreEvents>, logger?: ILogger);
+    initialize(): Promise<void>;
+    shutdown(): Promise<void>;
+}
+export interface BudgetTrackerOptions {
+    eventBus: TypedEventBus<CoreEvents>;
+    logger?: ILogger;
+}
+export declare function createBudgetTracker(options: BudgetTrackerOptions): BudgetTracker;
+//# sourceMappingURL=budget-tracker.d.ts.map

package/dist/budget/budget-tracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"budget-tracker.d.ts","sourceRoot":"","sources":["../../src/budget/budget-tracker.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAC/C,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA;AACnE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAA;AAMnD,MAAM,WAAW,aAAc,SAAQ,YAAY;CAElD;AAMD,qBAAa,iBAAkB,YAAW,aAAa;IACrD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA2B;IACrD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAErB,QAAQ,EAAE,aAAa,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC,EAAE,OAAO;IAK3D,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAsB3B,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAGhC;AAMD,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,aAAa,CAAC,UAAU,CAAC,CAAA;IACnC,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB;AAED,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,oBAAoB,GAAG,aAAa,CAEhF"}

package/dist/budget/budget-tracker.js

@@ -0,0 +1,39 @@
+/**
+ * BudgetTracker — interface and stub for tracking token/cost budgets.
+ * Migrated to @substrate-ai/core (Story 41-7)
+ */
+// ---------------------------------------------------------------------------
+// BudgetTrackerImpl (stub)
+// ---------------------------------------------------------------------------
+export class BudgetTrackerImpl {
+    _eventBus;
+    _logger;
+    constructor(eventBus, logger) {
+        this._eventBus = eventBus;
+        this._logger = logger ?? console;
+    }
+    async initialize() {
+        this._logger.info('BudgetTracker.initialize() — stub');
+        // Subscribe to budget events
+        this._eventBus.on('budget:warning', ({ taskId, currentSpend, limit }) => {
+            this._logger.warn({ taskId, currentSpend, limit }, 'budget:warning');
+        });
+        this._eventBus.on('budget:exceeded', ({ taskId, spend, limit }) => {
+            this._logger.error({ taskId, spend, limit }, 'budget:exceeded');
+        });
+        // Subscribe to task events for cost tracking
+        this._eventBus.on('task:complete', ({ taskId, result }) => {
+            this._logger.debug({ taskId, costUsd: result.costUsd }, 'task:complete — accumulate cost');
+        });
+        this._eventBus.on('task:progress', ({ taskId, tokensUsed }) => {
+            this._logger.debug({ taskId, tokensUsed }, 'task:progress — update token usage');
+        });
+    }
+    async shutdown() {
+        this._logger.info('BudgetTracker.shutdown() — stub');
+    }
+}
+export function createBudgetTracker(options) {
+    return new BudgetTrackerImpl(options.eventBus, options.logger);
+}
+//# sourceMappingURL=budget-tracker.js.map

package/dist/budget/budget-tracker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"budget-tracker.js","sourceRoot":"","sources":["../../src/budget/budget-tracker.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAcH,8EAA8E;AAC9E,2BAA2B;AAC3B,8EAA8E;AAE9E,MAAM,OAAO,iBAAiB;IACX,SAAS,CAA2B;IACpC,OAAO,CAAS;IAEjC,YAAY,QAAmC,EAAE,MAAgB;QAC/D,IAAI,CAAC,SAAS,GAAG,QAAQ,CAAA;QACzB,IAAI,CAAC,OAAO,GAAG,MAAM,IAAI,OAAO,CAAA;IAClC,CAAC;IAED,KAAK,CAAC,UAAU;QACd,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,mCAAmC,CAAC,CAAA;QAEtD,6BAA6B;QAC7B,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,gBAAgB,EAAE,CAAC,EAAE,MAAM,EAAE,YAAY,EAAE,KAAK,EAAE,EAAE,EAAE;YACtE,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,YAAY,EAAE,KAAK,EAAE,EAAE,gBAAgB,CAAC,CAAA;QACtE,CAAC,CAAC,CAAA;QAEF,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,iBAAiB,EAAE,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,EAAE;YAChE,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,iBAAiB,CAAC,CAAA;QACjE,CAAC,CAAC,CAAA;QAEF,6CAA6C;QAC7C,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,eAAe,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE;YACxD,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,EAAE,iCAAiC,CAAC,CAAA;QAC5F,CAAC,CAAC,CAAA;QAEF,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,eAAe,EAAE,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,EAAE,EAAE;YAC5D,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,EAAE,oCAAoC,CAAC,CAAA;QAClF,CAAC,CAAC,CAAA;IACJ,CAAC;IAED,KAAK,CAAC,QAAQ;QACZ,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,iCAAiC,CAAC,CAAA;IACtD,CAAC;CACF;AAWD,MAAM,UAAU,mBAAmB,CAAC,OAA6B;IAC/D,OAAO,IAAI,iBAAiB,CAAC,OAAO,CAAC,QAAQ,EAAE,OAAO,CAAC,MAAM,CAAC,CAAA;AAChE,CAAC"}

package/dist/budget/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Budget module barrel export — @substrate-ai/core (Story 41-7)
+ */
+export type { BudgetTracker, BudgetTrackerOptions } from './budget-tracker.js';
+export { BudgetTrackerImpl, createBudgetTracker } from './budget-tracker.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/budget/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/budget/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,YAAY,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAA;AAC9E,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA"}

package/dist/budget/index.js

@@ -0,0 +1,5 @@
+/**
+ * Budget module barrel export — @substrate-ai/core (Story 41-7)
+ */
+export { BudgetTrackerImpl, createBudgetTracker } from './budget-tracker.js';
+//# sourceMappingURL=index.js.map

package/dist/budget/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/budget/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA"}

package/dist/config/config-migrator.d.ts

@@ -0,0 +1,58 @@
+/**
+ * ConfigMigrator — registry and executor of config format migrations (FR63).
+ *
+ * Migrations are keyed as "N->M" strings (e.g. "1->2") and are applied
+ * sequentially when migrating across multiple versions.
+ */
+export interface MigrationResult {
+    success: boolean;
+    fromVersion: string;
+    toVersion: string;
+    migratedKeys: string[];
+    manualStepsRequired: string[];
+    backupPath: string | null;
+}
+/**
+ * ConfigMigrator manages a registry of migration functions and applies them
+ * sequentially to upgrade config documents from one format version to another.
+ */
+export declare class ConfigMigrator {
+    private readonly migrations;
+    /**
+     * Register a migration function for the given version key.
+     *
+     * @param key - Migration key in format "N->M" (e.g. "1->2")
+     * @param fn - Migration function that receives the raw config and returns the migrated config
+     */
+    register(key: string, fn: (config: unknown) => unknown): void;
+    /**
+     * Check whether a sequential migration path exists from fromVersion to toVersion.
+     *
+     * @param fromVersion - Starting version string
+     * @param toVersion - Target version string
+     * @returns true if every step in the path is registered
+     */
+    canMigrate(fromVersion: string, toVersion: string): boolean;
+    /**
+     * Apply sequential migrations from fromVersion to toVersion.
+     *
+     * If fromVersion === toVersion, returns a no-op success result.
+     * If any intermediate migration is missing, returns success:false.
+     *
+     * When filePath is provided and migration is needed, a backup is written to
+     * `${filePath}.bak.v${fromVersion}` before any transformations are applied.
+     *
+     * @param config - Raw config object to migrate
+     * @param fromVersion - Starting format version string
+     * @param toVersion - Target format version string
+     * @param filePath - Optional path to the source config file for backup creation
+     * @returns Object containing the (possibly migrated) config and a MigrationResult
+     */
+    migrate(config: unknown, fromVersion: string, toVersion: string, filePath?: string): {
+        config: unknown;
+        result: MigrationResult;
+    };
+}
+/** Singleton instance for use throughout the toolkit */
+export declare const defaultConfigMigrator: ConfigMigrator;
+//# sourceMappingURL=config-migrator.d.ts.map

package/dist/config/config-migrator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-migrator.d.ts","sourceRoot":"","sources":["../../src/config/config-migrator.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,OAAO,CAAA;IAChB,WAAW,EAAE,MAAM,CAAA;IACnB,SAAS,EAAE,MAAM,CAAA;IACjB,YAAY,EAAE,MAAM,EAAE,CAAA;IACtB,mBAAmB,EAAE,MAAM,EAAE,CAAA;IAC7B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;CAC1B;AAED;;;GAGG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAuD;IAElF;;;;;OAKG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,OAAO,GAAG,IAAI;IAI7D;;;;;;OAMG;IACH,UAAU,CAAC,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO;IAgB3D;;;;;;;;;;;;;;OAcG;IACH,OAAO,CACL,MAAM,EAAE,OAAO,EACf,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,EACjB,QAAQ,CAAC,EAAE,MAAM,GAChB;QAAE,MAAM,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,eAAe,CAAA;KAAE;CA2GhD;AAED,wDAAwD;AACxD,eAAO,MAAM,qBAAqB,gBAAuB,CAAA"}

package/dist/config/config-migrator.js

@@ -0,0 +1,158 @@
+/**
+ * ConfigMigrator — registry and executor of config format migrations (FR63).
+ *
+ * Migrations are keyed as "N->M" strings (e.g. "1->2") and are applied
+ * sequentially when migrating across multiple versions.
+ */
+import { writeFileSync, readFileSync } from 'fs';
+/**
+ * ConfigMigrator manages a registry of migration functions and applies them
+ * sequentially to upgrade config documents from one format version to another.
+ */
+export class ConfigMigrator {
+    migrations = new Map();
+    /**
+     * Register a migration function for the given version key.
+     *
+     * @param key - Migration key in format "N->M" (e.g. "1->2")
+     * @param fn - Migration function that receives the raw config and returns the migrated config
+     */
+    register(key, fn) {
+        this.migrations.set(key, fn);
+    }
+    /**
+     * Check whether a sequential migration path exists from fromVersion to toVersion.
+     *
+     * @param fromVersion - Starting version string
+     * @param toVersion - Target version string
+     * @returns true if every step in the path is registered
+     */
+    canMigrate(fromVersion, toVersion) {
+        if (fromVersion === toVersion)
+            return true;
+        const from = parseInt(fromVersion, 10);
+        const to = parseInt(toVersion, 10);
+        if (isNaN(from) || isNaN(to) || from >= to)
+            return false;
+        for (let v = from; v < to; v++) {
+            const key = `${String(v)}->${String(v + 1)}`;
+            if (!this.migrations.has(key))
+                return false;
+        }
+        return true;
+    }
+    /**
+     * Apply sequential migrations from fromVersion to toVersion.
+     *
+     * If fromVersion === toVersion, returns a no-op success result.
+     * If any intermediate migration is missing, returns success:false.
+     *
+     * When filePath is provided and migration is needed, a backup is written to
+     * `${filePath}.bak.v${fromVersion}` before any transformations are applied.
+     *
+     * @param config - Raw config object to migrate
+     * @param fromVersion - Starting format version string
+     * @param toVersion - Target format version string
+     * @param filePath - Optional path to the source config file for backup creation
+     * @returns Object containing the (possibly migrated) config and a MigrationResult
+     */
+    migrate(config, fromVersion, toVersion, filePath) {
+        // No-op: same version
+        if (fromVersion === toVersion) {
+            return {
+                config,
+                result: {
+                    success: true,
+                    fromVersion,
+                    toVersion,
+                    migratedKeys: [],
+                    manualStepsRequired: [],
+                    backupPath: null,
+                },
+            };
+        }
+        const from = parseInt(fromVersion, 10);
+        const to = parseInt(toVersion, 10);
+        if (isNaN(from) || isNaN(to) || from >= to) {
+            return {
+                config,
+                result: {
+                    success: false,
+                    fromVersion,
+                    toVersion,
+                    migratedKeys: [],
+                    manualStepsRequired: [
+                        `Cannot migrate from version "${fromVersion}" to "${toVersion}": invalid version range.`,
+                    ],
+                    backupPath: null,
+                },
+            };
+        }
+        // Check all steps exist first
+        for (let v = from; v < to; v++) {
+            const key = `${String(v)}->${String(v + 1)}`;
+            if (!this.migrations.has(key)) {
+                return {
+                    config,
+                    result: {
+                        success: false,
+                        fromVersion,
+                        toVersion,
+                        migratedKeys: [],
+                        manualStepsRequired: [
+                            `Missing migration step: "${key}". ` +
+                                `Cannot automatically migrate from version "${fromVersion}" to "${toVersion}". ` +
+                                `Please upgrade the toolkit: npm install -g substrate@latest`,
+                        ],
+                        backupPath: null,
+                    },
+                };
+            }
+        }
+        // Write backup file before applying any migrations (AC4)
+        let backupPath = null;
+        if (filePath !== undefined) {
+            backupPath = `${filePath}.bak.v${fromVersion}`;
+            const originalContent = readFileSync(filePath, 'utf-8');
+            writeFileSync(backupPath, originalContent, 'utf-8');
+        }
+        // Apply migrations sequentially
+        let current = config;
+        const migratedKeys = [];
+        for (let v = from; v < to; v++) {
+            const key = `${String(v)}->${String(v + 1)}`;
+            const fn = this.migrations.get(key);
+            const before = JSON.stringify(current);
+            current = fn(current);
+            const after = JSON.stringify(current);
+            // Detect changed keys by comparing against previous-step output (not original config)
+            if (current !== null &&
+                typeof current === 'object' &&
+                !Array.isArray(current)) {
+                const beforeObj = JSON.parse(before);
+                const afterObj = JSON.parse(after);
+                for (const k of Object.keys(afterObj)) {
+                    if (JSON.stringify(afterObj[k]) !== JSON.stringify(beforeObj[k])) {
+                        if (!migratedKeys.includes(k)) {
+                            migratedKeys.push(k);
+                        }
+                    }
+                }
+            }
+        }
+        return {
+            config: current,
+            result: {
+                success: true,
+                fromVersion,
+                toVersion,
+                migratedKeys,
+                manualStepsRequired: [],
+                backupPath,
+            },
+        };
+    }
+}
+/** Singleton instance for use throughout the toolkit */
+export const defaultConfigMigrator = new ConfigMigrator();
+//# sourceMappingURL=config-migrator.js.map

package/dist/config/config-migrator.js.map

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

package/dist/config/config-system-impl.d.ts

@@ -0,0 +1,63 @@
+/**
+ * ConfigSystem implementation — loads configuration in hierarchy order and
+ * exposes get/set/getMasked operations.
+ *
+ * Hierarchy (lowest → highest priority):
+ *   built-in defaults
+ *     → global user config  (~/.substrate/config.yaml)
+ *     → project config      (./.substrate/config.yaml)
+ *     → environment vars    (ADT_* prefixed)
+ *     → CLI flag overrides  (passed via ConfigSystemOptions.cliOverrides)
+ *
+ * No imports from src/ (monolith) — zero monolith dependencies.
+ */
+import { type SubstrateConfig, type ConfigSystem, type ConfigSystemOptions } from './types.js';
+type DeepPartial<T> = {
+    [K in keyof T]?: T[K] extends object ? DeepPartial<T[K]> : T[K];
+};
+export declare function deepMerge<T extends Record<string, unknown>>(base: T, override: DeepPartial<T>): T;
+/**
+ * Get a value from a nested object using dot-notation key.
+ */
+export declare function getByPath(obj: unknown, path: string): unknown;
+/**
+ * Return a deep clone of `obj` with `path` set to `value`.
+ * Creates intermediate objects as needed.
+ */
+export declare function setByPath(obj: Record<string, unknown>, path: string, value: unknown): Record<string, unknown>;
+/**
+ * Check whether a config format version is compatible with this toolkit.
+ *
+ * @param version - Version string to check
+ * @returns true if the version is in SUPPORTED_CONFIG_FORMAT_VERSIONS
+ */
+export declare function getVersionCompatibility(version: string): boolean;
+export declare class ConfigSystemImpl implements ConfigSystem {
+    private _config;
+    private readonly _projectConfigDir;
+    private readonly _globalConfigDir;
+    private readonly _cliOverrides;
+    private readonly _logger;
+    constructor(options?: ConfigSystemOptions);
+    get isLoaded(): boolean;
+    load(): Promise<void>;
+    getConfig(): SubstrateConfig;
+    get(key: string): unknown;
+    set(key: string, value: unknown): Promise<void>;
+    getMasked(): SubstrateConfig;
+    getConfigFormatVersion(): string;
+    isCompatible(version: string): boolean;
+    private _fileExists;
+    private _loadYamlFile;
+}
+/**
+ * Create a new ConfigSystem instance.
+ *
+ * @example
+ * const config = createConfigSystem()
+ * await config.load()
+ * const cfg = config.getConfig()
+ */
+export declare function createConfigSystem(options?: ConfigSystemOptions): ConfigSystem;
+export {};
+//# sourceMappingURL=config-system-impl.d.ts.map

package/dist/config/config-system-impl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-system-impl.d.ts","sourceRoot":"","sources":["../../src/config/config-system-impl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAQH,OAAO,EAKL,KAAK,eAAe,EAEpB,KAAK,YAAY,EACjB,KAAK,mBAAmB,EACzB,MAAM,YAAY,CAAA;AA2CnB,KAAK,WAAW,CAAC,CAAC,IAAI;KACnB,CAAC,IAAI,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,MAAM,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;CAChE,CAAA;AAED,wBAAgB,SAAS,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACzD,IAAI,EAAE,CAAC,EACP,QAAQ,EAAE,WAAW,CAAC,CAAC,CAAC,GACvB,CAAC,CAqBH;AA6DD;;GAEG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAQ7D;AAED;;;GAGG;AACH,wBAAgB,SAAS,CACvB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,OAAO,GACb,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAmBzB;AAMD;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAEhE;AAMD,qBAAa,gBAAiB,YAAW,YAAY;IACnD,OAAO,CAAC,OAAO,CAA+B;IAC9C,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAQ;IAC1C,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAQ;IACzC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAwB;IACtD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAErB,OAAO,GAAE,mBAAwB;IAW7C,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAEK,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IA2D3B,SAAS,IAAI,eAAe;IAU5B,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAKnB,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAwDrD,SAAS,IAAI,eAAe;IAK5B,sBAAsB,IAAI,MAAM;IAIhC,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;YAQxB,WAAW;YASX,aAAa;CA4D5B;AAMD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,GAAE,mBAAwB,GAAG,YAAY,CAElF"}