@substrate-ai/core 0.19.54

package/dist/types.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Core types for Substrate
+ * Shared type definitions used across all modules
+ */
+/** Unique identifier for a task in the DAG */
+export type TaskId = string;
+/** Unique identifier for a worker/agent instance */
+export type WorkerId = string;
+/** Unique identifier for a registered agent type */
+export type AgentId = string;
+/** Status of an individual task */
+export type TaskStatus = 'pending' | 'ready' | 'queued' | 'running' | 'completed' | 'failed' | 'cancelled' | 'blocked';
+/** Status of an orchestration session */
+export type SessionStatus = 'initializing' | 'running' | 'paused' | 'completed' | 'failed' | 'cancelled';
+/** Billing mode for a worker/agent */
+export type BillingMode = 'subscription' | 'api' | 'free';
+/** Severity level for errors and log messages */
+export type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+/** Task priority level */
+export type TaskPriority = 'low' | 'normal' | 'high' | 'critical';
+/** Agent capability descriptor */
+export interface AgentCapability {
+    name: string;
+    version: string;
+    supportedTaskTypes: string[];
+    billingMode: BillingMode;
+    maxConcurrency: number;
+}
+/** Task graph node definition */
+export interface TaskNode {
+    id: TaskId;
+    title: string;
+    description: string;
+    agentId?: AgentId;
+    status: TaskStatus;
+    priority: TaskPriority;
+    dependencies: TaskId[];
+    metadata: Record<string, unknown>;
+    createdAt: Date;
+    startedAt?: Date;
+    completedAt?: Date;
+}
+/** Session configuration */
+export interface SessionConfig {
+    id: string;
+    name: string;
+    projectRoot: string;
+    taskGraphPath: string;
+    maxConcurrency: number;
+    budgetCap?: number;
+    billingMode: BillingMode;
+}
+/** Cost tracking record */
+export interface CostRecord {
+    taskId: TaskId;
+    agentId: AgentId;
+    sessionId: string;
+    tokens: number;
+    estimatedCost: number;
+    billingMode: BillingMode;
+    timestamp: Date;
+}
+/**
+ * Lifecycle interface for all orchestrator services/modules in @substrate-ai/core.
+ * Mirrors BaseService from src/core/di.ts but lives in core to avoid monolith imports.
+ * Every module that participates in graceful startup/shutdown must implement this.
+ */
+export interface IBaseService {
+    /**
+     * Initialize the service — set up connections, subscribe to events, etc.
+     * Called after all services are constructed but before the orchestrator is ready.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Tear down the service gracefully.
+     * Called during orchestrator shutdown in reverse dependency order.
+     */
+    shutdown(): Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,8CAA8C;AAC9C,MAAM,MAAM,MAAM,GAAG,MAAM,CAAA;AAE3B,oDAAoD;AACpD,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAA;AAE7B,oDAAoD;AACpD,MAAM,MAAM,OAAO,GAAG,MAAM,CAAA;AAE5B,mCAAmC;AACnC,MAAM,MAAM,UAAU,GAClB,SAAS,GACT,OAAO,GACP,QAAQ,GACR,SAAS,GACT,WAAW,GACX,QAAQ,GACR,WAAW,GACX,SAAS,CAAA;AAEb,yCAAyC;AACzC,MAAM,MAAM,aAAa,GACrB,cAAc,GACd,SAAS,GACT,QAAQ,GACR,WAAW,GACX,QAAQ,GACR,WAAW,CAAA;AAEf,sCAAsC;AACtC,MAAM,MAAM,WAAW,GAAG,cAAc,GAAG,KAAK,GAAG,MAAM,CAAA;AAEzD,iDAAiD;AACjD,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,CAAA;AAE9E,0BAA0B;AAC1B,MAAM,MAAM,YAAY,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,UAAU,CAAA;AAEjE,kCAAkC;AAClC,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;IACf,kBAAkB,EAAE,MAAM,EAAE,CAAA;IAC5B,WAAW,EAAE,WAAW,CAAA;IACxB,cAAc,EAAE,MAAM,CAAA;CACvB;AAED,iCAAiC;AACjC,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,EAAE,MAAM,CAAA;IACnB,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,MAAM,EAAE,UAAU,CAAA;IAClB,QAAQ,EAAE,YAAY,CAAA;IACtB,YAAY,EAAE,MAAM,EAAE,CAAA;IACtB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACjC,SAAS,EAAE,IAAI,CAAA;IACf,SAAS,CAAC,EAAE,IAAI,CAAA;IAChB,WAAW,CAAC,EAAE,IAAI,CAAA;CACnB;AAED,4BAA4B;AAC5B,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,aAAa,EAAE,MAAM,CAAA;IACrB,cAAc,EAAE,MAAM,CAAA;IACtB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,WAAW,EAAE,WAAW,CAAA;CACzB;AAED,2BAA2B;AAC3B,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,OAAO,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;IACjB,MAAM,EAAE,MAAM,CAAA;IACd,aAAa,EAAE,MAAM,CAAA;IACrB,WAAW,EAAE,WAAW,CAAA;IACxB,SAAS,EAAE,IAAI,CAAA;CAChB;AAMD;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IAE3B;;;OAGG;IACH,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CAC1B"}

package/dist/types.js

@@ -0,0 +1,6 @@
+/**
+ * Core types for Substrate
+ * Shared type definitions used across all modules
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

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

package/dist/version-manager/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @substrate-ai/core version-manager barrel export.
+ * Re-exports all version management types and implementations.
+ */
+export type { VersionManager, VersionCheckResult, UpgradePreview } from './version-manager.js';
+export { VersionManagerImpl, createVersionManager } from './version-manager-impl.js';
+export type { VersionManagerDeps } from './version-manager-impl.js';
+export { UpdateChecker, UpdateCheckError } from './update-checker.js';
+export { VersionCache } from './version-cache.js';
+export type { VersionCacheEntry } from './version-cache.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/version-manager/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/version-manager/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,YAAY,EAAE,cAAc,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAC9F,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAA;AACpF,YAAY,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAA;AACnE,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAA;AACrE,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AACjD,YAAY,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAA"}

package/dist/version-manager/index.js

@@ -0,0 +1,8 @@
+/**
+ * @substrate-ai/core version-manager barrel export.
+ * Re-exports all version management types and implementations.
+ */
+export { VersionManagerImpl, createVersionManager } from './version-manager-impl.js';
+export { UpdateChecker, UpdateCheckError } from './update-checker.js';
+export { VersionCache } from './version-cache.js';
+//# sourceMappingURL=index.js.map

package/dist/version-manager/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/version-manager/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAA;AAEpF,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAA;AACrE,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA"}

package/dist/version-manager/update-checker.d.ts

@@ -0,0 +1,44 @@
+/**
+ * UpdateChecker — queries the npm registry for the latest package version.
+ *
+ * Uses Node.js built-in `https` module (no extra HTTP dependency).
+ * Uses `semver` for major-version comparison (AC7, AC8).
+ */
+/**
+ * Thrown when an update check fails due to network error, timeout, or bad response.
+ */
+export declare class UpdateCheckError extends Error {
+    readonly name = "UpdateCheckError";
+    constructor(message: string);
+}
+/**
+ * Queries the npm registry to determine the latest published version of a package.
+ */
+export declare class UpdateChecker {
+    private readonly timeoutMs;
+    constructor(timeoutMs?: number);
+    /**
+     * Fetch the latest published version of a package from the npm registry.
+     *
+     * @param packageName - npm package name (e.g. 'substrate')
+     * @returns The latest version string (semver)
+     * @throws {UpdateCheckError} on timeout, network error, non-200 HTTP status, or parse failure
+     */
+    fetchLatestVersion(packageName: string): Promise<string>;
+    /**
+     * Determine whether upgrading from currentVersion to latestVersion is a breaking (major) change.
+     *
+     * @param currentVersion - The currently installed version (semver string)
+     * @param latestVersion - The available latest version (semver string)
+     * @returns true if the major version increases; false if either version is invalid
+     */
+    isBreaking(currentVersion: string, latestVersion: string): boolean;
+    /**
+     * Return a changelog URL for the given version.
+     *
+     * @param latestVersion - The version to link to
+     * @returns A URL string pointing to the GitHub release page
+     */
+    getChangelog(latestVersion: string): string;
+}
+//# sourceMappingURL=update-checker.d.ts.map

package/dist/version-manager/update-checker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-checker.d.ts","sourceRoot":"","sources":["../../src/version-manager/update-checker.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAUH;;GAEG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,SAAkB,IAAI,sBAAqB;gBAE/B,OAAO,EAAE,MAAM;CAK5B;AAMD;;GAEG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAQ;gBAEtB,SAAS,SAAO;IAI5B;;;;;;OAMG;IACH,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAqGxD;;;;;;OAMG;IACH,UAAU,CAAC,cAAc,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO;IAWlE;;;;;OAKG;IACH,YAAY,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM;CAG5C"}

package/dist/version-manager/update-checker.js

@@ -0,0 +1,171 @@
+/**
+ * UpdateChecker — queries the npm registry for the latest package version.
+ *
+ * Uses Node.js built-in `https` module (no extra HTTP dependency).
+ * Uses `semver` for major-version comparison (AC7, AC8).
+ */
+import https from 'node:https';
+import * as semver from 'semver';
+// ---------------------------------------------------------------------------
+// Error class
+// ---------------------------------------------------------------------------
+/**
+ * Thrown when an update check fails due to network error, timeout, or bad response.
+ */
+export class UpdateCheckError extends Error {
+    name = 'UpdateCheckError';
+    constructor(message) {
+        super(message);
+        // Restore prototype chain
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+// ---------------------------------------------------------------------------
+// UpdateChecker class
+// ---------------------------------------------------------------------------
+/**
+ * Queries the npm registry to determine the latest published version of a package.
+ */
+export class UpdateChecker {
+    timeoutMs;
+    constructor(timeoutMs = 5000) {
+        this.timeoutMs = timeoutMs;
+    }
+    /**
+     * Fetch the latest published version of a package from the npm registry.
+     *
+     * @param packageName - npm package name (e.g. 'substrate')
+     * @returns The latest version string (semver)
+     * @throws {UpdateCheckError} on timeout, network error, non-200 HTTP status, or parse failure
+     */
+    fetchLatestVersion(packageName) {
+        return new Promise((resolve, reject) => {
+            const url = `https://registry.npmjs.org/${packageName}/latest`;
+            let settled = false;
+            const safeReject = (err) => {
+                if (!settled) {
+                    settled = true;
+                    clearTimeout(timer);
+                    reject(err);
+                }
+            };
+            const safeResolve = (value) => {
+                if (!settled) {
+                    settled = true;
+                    clearTimeout(timer);
+                    resolve(value);
+                }
+            };
+            // Use setTimeout + req.destroy() to implement the timeout, since the
+            // https.get legacy callback API does not accept an AbortSignal directly.
+            // eslint-disable-next-line prefer-const
+            let req;
+            const timer = setTimeout(() => {
+                req.destroy();
+                safeReject(new UpdateCheckError(`Update check timed out after ${this.timeoutMs}ms`));
+            }, this.timeoutMs);
+            const followRedirect = (location, hopsLeft) => {
+                const redirectReq = https.get(location, (redirectRes) => {
+                    // Handle up to 2 redirect hops
+                    if (redirectRes.statusCode !== undefined &&
+                        redirectRes.statusCode >= 300 &&
+                        redirectRes.statusCode < 400 &&
+                        redirectRes.headers.location &&
+                        hopsLeft > 0) {
+                        redirectRes.resume();
+                        followRedirect(redirectRes.headers.location, hopsLeft - 1);
+                        return;
+                    }
+                    if (redirectRes.statusCode !== 200) {
+                        redirectRes.resume();
+                        safeReject(new UpdateCheckError(`npm registry returned HTTP ${String(redirectRes.statusCode)} for ${packageName}`));
+                        return;
+                    }
+                    collectBody(redirectRes, safeResolve, safeReject);
+                });
+                redirectReq.on('error', (err) => {
+                    safeReject(new UpdateCheckError(`Update check network error: ${err.message}`));
+                });
+                // Apply the same timeout to redirect requests
+                redirectReq.setTimeout(this.timeoutMs, () => {
+                    redirectReq.destroy();
+                    safeReject(new UpdateCheckError(`Update check timed out after ${this.timeoutMs}ms`));
+                });
+            };
+            req = https.get(url, (res) => {
+                // Handle redirects
+                if (res.statusCode !== undefined &&
+                    res.statusCode >= 300 &&
+                    res.statusCode < 400 &&
+                    res.headers.location) {
+                    res.resume();
+                    // Follow up to 2 redirect hops
+                    followRedirect(res.headers.location, 1);
+                    return;
+                }
+                if (res.statusCode !== 200) {
+                    res.resume();
+                    safeReject(new UpdateCheckError(`npm registry returned HTTP ${String(res.statusCode)} for ${packageName}`));
+                    return;
+                }
+                collectBody(res, safeResolve, safeReject);
+            });
+            req.on('error', (err) => {
+                // When req.destroy() is called on timeout, this fires with the destroy error.
+                // safeReject handles the settled check to avoid double-rejection.
+                safeReject(new UpdateCheckError(`Update check network error: ${err.message}`));
+            });
+        });
+    }
+    /**
+     * Determine whether upgrading from currentVersion to latestVersion is a breaking (major) change.
+     *
+     * @param currentVersion - The currently installed version (semver string)
+     * @param latestVersion - The available latest version (semver string)
+     * @returns true if the major version increases; false if either version is invalid
+     */
+    isBreaking(currentVersion, latestVersion) {
+        if (!semver.valid(currentVersion) || !semver.valid(latestVersion)) {
+            return false;
+        }
+        const currentMajor = semver.major(currentVersion);
+        const latestMajor = semver.major(latestVersion);
+        return latestMajor > currentMajor;
+    }
+    /**
+     * Return a changelog URL for the given version.
+     *
+     * @param latestVersion - The version to link to
+     * @returns A URL string pointing to the GitHub release page
+     */
+    getChangelog(latestVersion) {
+        return `See https://github.com/johnplanow/substrate/releases/tag/v${latestVersion}`;
+    }
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function collectBody(res, resolve, reject) {
+    const chunks = [];
+    res.on('data', (chunk) => {
+        chunks.push(chunk);
+    });
+    res.on('end', () => {
+        try {
+            const body = Buffer.concat(chunks).toString('utf-8');
+            const data = JSON.parse(body);
+            if (typeof data.version !== 'string' || data.version.length === 0) {
+                reject(new UpdateCheckError('npm registry response missing version field'));
+                return;
+            }
+            resolve(data.version);
+        }
+        catch {
+            reject(new UpdateCheckError('Failed to parse npm registry response'));
+        }
+    });
+    res.on('error', (err) => {
+        reject(new UpdateCheckError(`Response stream error: ${err.message}`));
+    });
+}
+//# sourceMappingURL=update-checker.js.map

package/dist/version-manager/update-checker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-checker.js","sourceRoot":"","sources":["../../src/version-manager/update-checker.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,MAAM,YAAY,CAAA;AAE9B,OAAO,KAAK,MAAM,MAAM,QAAQ,CAAA;AAEhC,8EAA8E;AAC9E,cAAc;AACd,8EAA8E;AAE9E;;GAEG;AACH,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IACvB,IAAI,GAAG,kBAAkB,CAAA;IAE3C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,0BAA0B;QAC1B,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAA;IACnD,CAAC;CACF;AAED,8EAA8E;AAC9E,sBAAsB;AACtB,8EAA8E;AAE9E;;GAEG;AACH,MAAM,OAAO,aAAa;IACP,SAAS,CAAQ;IAElC,YAAY,SAAS,GAAG,IAAI;QAC1B,IAAI,CAAC,SAAS,GAAG,SAAS,CAAA;IAC5B,CAAC;IAED;;;;;;OAMG;IACH,kBAAkB,CAAC,WAAmB;QACpC,OAAO,IAAI,OAAO,CAAS,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YAC7C,MAAM,GAAG,GAAG,8BAA8B,WAAW,SAAS,CAAA;YAC9D,IAAI,OAAO,GAAG,KAAK,CAAA;YAEnB,MAAM,UAAU,GAAG,CAAC,GAAqB,EAAQ,EAAE;gBACjD,IAAI,CAAC,OAAO,EAAE,CAAC;oBACb,OAAO,GAAG,IAAI,CAAA;oBACd,YAAY,CAAC,KAAK,CAAC,CAAA;oBACnB,MAAM,CAAC,GAAG,CAAC,CAAA;gBACb,CAAC;YACH,CAAC,CAAA;YAED,MAAM,WAAW,GAAG,CAAC,KAAa,EAAQ,EAAE;gBAC1C,IAAI,CAAC,OAAO,EAAE,CAAC;oBACb,OAAO,GAAG,IAAI,CAAA;oBACd,YAAY,CAAC,KAAK,CAAC,CAAA;oBACnB,OAAO,CAAC,KAAK,CAAC,CAAA;gBAChB,CAAC;YACH,CAAC,CAAA;YAED,qEAAqE;YACrE,yEAAyE;YACzE,wCAAwC;YACxC,IAAI,GAAiC,CAAA;YACrC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;gBAC5B,GAAG,CAAC,OAAO,EAAE,CAAA;gBACb,UAAU,CAAC,IAAI,gBAAgB,CAAC,gCAAgC,IAAI,CAAC,SAAS,IAAI,CAAC,CAAC,CAAA;YACtF,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,CAAA;YAElB,MAAM,cAAc,GAAG,CAAC,QAAgB,EAAE,QAAgB,EAAQ,EAAE;gBAClE,MAAM,WAAW,GAAG,KAAK,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC,WAAW,EAAE,EAAE;oBACtD,+BAA+B;oBAC/B,IACE,WAAW,CAAC,UAAU,KAAK,SAAS;wBACpC,WAAW,CAAC,UAAU,IAAI,GAAG;wBAC7B,WAAW,CAAC,UAAU,GAAG,GAAG;wBAC5B,WAAW,CAAC,OAAO,CAAC,QAAQ;wBAC5B,QAAQ,GAAG,CAAC,EACZ,CAAC;wBACD,WAAW,CAAC,MAAM,EAAE,CAAA;wBACpB,cAAc,CAAC,WAAW,CAAC,OAAO,CAAC,QAAQ,EAAE,QAAQ,GAAG,CAAC,CAAC,CAAA;wBAC1D,OAAM;oBACR,CAAC;oBAED,IAAI,WAAW,CAAC,UAAU,KAAK,GAAG,EAAE,CAAC;wBACnC,WAAW,CAAC,MAAM,EAAE,CAAA;wBACpB,UAAU,CACR,IAAI,gBAAgB,CAClB,8BAA8B,MAAM,CAAC,WAAW,CAAC,UAAU,CAAC,QAAQ,WAAW,EAAE,CAClF,CACF,CAAA;wBACD,OAAM;oBACR,CAAC;oBACD,WAAW,CAAC,WAAW,EAAE,WAAW,EAAE,UAAU,CAAC,CAAA;gBACnD,CAAC,CAAC,CAAA;gBACF,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,EAAE;oBAC9B,UAAU,CAAC,IAAI,gBAAgB,CAAC,+BAA+B,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC,CAAA;gBAChF,CAAC,CAAC,CAAA;gBACF,8CAA8C;gBAC9C,WAAW,CAAC,UAAU,CAAC,IAAI,CAAC,SAAS,EAAE,GAAG,EAAE;oBAC1C,WAAW,CAAC,OAAO,EAAE,CAAA;oBACrB,UAAU,CAAC,IAAI,gBAAgB,CAAC,gCAAgC,IAAI,CAAC,SAAS,IAAI,CAAC,CAAC,CAAA;gBACtF,CAAC,CAAC,CAAA;YACJ,CAAC,CAAA;YAED,GAAG,GAAG,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,EAAE,EAAE;gBAC3B,mBAAmB;gBACnB,IACE,GAAG,CAAC,UAAU,KAAK,SAAS;oBAC5B,GAAG,CAAC,UAAU,IAAI,GAAG;oBACrB,GAAG,CAAC,UAAU,GAAG,GAAG;oBACpB,GAAG,CAAC,OAAO,CAAC,QAAQ,EACpB,CAAC;oBACD,GAAG,CAAC,MAAM,EAAE,CAAA;oBACZ,+BAA+B;oBAC/B,cAAc,CAAC,GAAG,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAA;oBACvC,OAAM;gBACR,CAAC;gBAED,IAAI,GAAG,CAAC,UAAU,KAAK,GAAG,EAAE,CAAC;oBAC3B,GAAG,CAAC,MAAM,EAAE,CAAA;oBACZ,UAAU,CACR,IAAI,gBAAgB,CAClB,8BAA8B,MAAM,CAAC,GAAG,CAAC,UAAU,CAAC,QAAQ,WAAW,EAAE,CAC1E,CACF,CAAA;oBACD,OAAM;gBACR,CAAC;gBAED,WAAW,CAAC,GAAG,EAAE,WAAW,EAAE,UAAU,CAAC,CAAA;YAC3C,CAAC,CAAC,CAAA;YAEF,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,EAAE;gBACtB,8EAA8E;gBAC9E,kEAAkE;gBAClE,UAAU,CAAC,IAAI,gBAAgB,CAAC,+BAA+B,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC,CAAA;YAChF,CAAC,CAAC,CAAA;QACJ,CAAC,CAAC,CAAA;IACJ,CAAC;IAED;;;;;;OAMG;IACH,UAAU,CAAC,cAAsB,EAAE,aAAqB;QACtD,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,cAAc,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,aAAa,CAAC,EAAE,CAAC;YAClE,OAAO,KAAK,CAAA;QACd,CAAC;QAED,MAAM,YAAY,GAAG,MAAM,CAAC,KAAK,CAAC,cAAc,CAAC,CAAA;QACjD,MAAM,WAAW,GAAG,MAAM,CAAC,KAAK,CAAC,aAAa,CAAC,CAAA;QAE/C,OAAO,WAAW,GAAG,YAAY,CAAA;IACnC,CAAC;IAED;;;;;OAKG;IACH,YAAY,CAAC,aAAqB;QAChC,OAAO,6DAA6D,aAAa,EAAE,CAAA;IACrF,CAAC;CACF;AAED,8EAA8E;AAC9E,UAAU;AACV,8EAA8E;AAE9E,SAAS,WAAW,CAClB,GAAoB,EACpB,OAAgC,EAChC,MAA0C;IAE1C,MAAM,MAAM,GAAa,EAAE,CAAA;IAE3B,GAAG,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAa,EAAE,EAAE;QAC/B,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;IACpB,CAAC,CAAC,CAAA;IAEF,GAAG,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE;QACjB,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAA;YACpD,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAyB,CAAA;YACrD,IAAI,OAAO,IAAI,CAAC,OAAO,KAAK,QAAQ,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBAClE,MAAM,CAAC,IAAI,gBAAgB,CAAC,6CAA6C,CAAC,CAAC,CAAA;gBAC3E,OAAM;YACR,CAAC;YACD,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;QACvB,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,CAAC,IAAI,gBAAgB,CAAC,uCAAuC,CAAC,CAAC,CAAA;QACvE,CAAC;IACH,CAAC,CAAC,CAAA;IAEF,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,GAAU,EAAE,EAAE;QAC7B,MAAM,CAAC,IAAI,gBAAgB,CAAC,0BAA0B,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC,CAAA;IACvE,CAAC,CAAC,CAAA;AACJ,CAAC"}

package/dist/version-manager/version-cache.d.ts

@@ -0,0 +1,42 @@
+/**
+ * VersionCache — reads and writes the update-check result cache file.
+ *
+ * Cache is stored at ~/.substrate/update-cache.json (global, across all projects).
+ * TTL defaults to 24 hours. (AC4)
+ */
+/**
+ * Serialized cache entry stored in update-cache.json.
+ */
+export interface VersionCacheEntry {
+    /** ISO 8601 timestamp of the last successful check */
+    lastChecked: string;
+    /** Latest version returned by the npm registry */
+    latestVersion: string;
+    /** The installed version at the time of the check */
+    currentVersion: string;
+}
+/**
+ * Manages reading and writing the version check result cache.
+ *
+ * Write errors are silently swallowed so that a read-only home directory
+ * never breaks CLI execution.
+ */
+export declare class VersionCache {
+    private readonly cachePath;
+    private readonly ttlMs;
+    constructor(cachePath?: string, ttlMs?: number);
+    /**
+     * Read the cache file. Returns null if the file is missing, unreadable, or expired.
+     */
+    read(): VersionCacheEntry | null;
+    /**
+     * Write a cache entry to disk. Creates the parent directory if needed.
+     * Silently swallows any write errors.
+     */
+    write(entry: VersionCacheEntry): void;
+    /**
+     * Check whether a cache entry has expired according to the configured TTL.
+     */
+    isExpired(entry: VersionCacheEntry): boolean;
+}
+//# sourceMappingURL=version-cache.d.ts.map

package/dist/version-manager/version-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version-cache.d.ts","sourceRoot":"","sources":["../../src/version-manager/version-cache.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAWH;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,sDAAsD;IACtD,WAAW,EAAE,MAAM,CAAA;IACnB,kDAAkD;IAClD,aAAa,EAAE,MAAM,CAAA;IACrB,qDAAqD;IACrD,cAAc,EAAE,MAAM,CAAA;CACvB;AAMD;;;;;GAKG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAQ;IAClC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAQ;gBAG5B,SAAS,GAAE,MAAmE,EAC9E,KAAK,GAAE,MAA4B;IAMrC;;OAEG;IACH,IAAI,IAAI,iBAAiB,GAAG,IAAI;IAuBhC;;;OAGG;IACH,KAAK,CAAC,KAAK,EAAE,iBAAiB,GAAG,IAAI;IASrC;;OAEG;IACH,SAAS,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO;CAI7C"}

package/dist/version-manager/version-cache.js

@@ -0,0 +1,69 @@
+/**
+ * VersionCache — reads and writes the update-check result cache file.
+ *
+ * Cache is stored at ~/.substrate/update-cache.json (global, across all projects).
+ * TTL defaults to 24 hours. (AC4)
+ */
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import os from 'node:os';
+import path from 'node:path';
+// ---------------------------------------------------------------------------
+// VersionCache class
+// ---------------------------------------------------------------------------
+/**
+ * Manages reading and writing the version check result cache.
+ *
+ * Write errors are silently swallowed so that a read-only home directory
+ * never breaks CLI execution.
+ */
+export class VersionCache {
+    cachePath;
+    ttlMs;
+    constructor(cachePath = path.join(os.homedir(), '.substrate', 'update-cache.json'), ttlMs = 24 * 60 * 60 * 1000) {
+        this.cachePath = cachePath;
+        this.ttlMs = ttlMs;
+    }
+    /**
+     * Read the cache file. Returns null if the file is missing, unreadable, or expired.
+     */
+    read() {
+        try {
+            const raw = readFileSync(this.cachePath, 'utf-8');
+            const entry = JSON.parse(raw);
+            if (typeof entry.lastChecked !== 'string' ||
+                typeof entry.latestVersion !== 'string' ||
+                typeof entry.currentVersion !== 'string') {
+                return null;
+            }
+            if (this.isExpired(entry)) {
+                return null;
+            }
+            return entry;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Write a cache entry to disk. Creates the parent directory if needed.
+     * Silently swallows any write errors.
+     */
+    write(entry) {
+        try {
+            mkdirSync(dirname(this.cachePath), { recursive: true });
+            writeFileSync(this.cachePath, JSON.stringify(entry, null, 2), 'utf-8');
+        }
+        catch {
+            // Silently swallow write errors — a missing cache is handled gracefully
+        }
+    }
+    /**
+     * Check whether a cache entry has expired according to the configured TTL.
+     */
+    isExpired(entry) {
+        const age = Date.now() - new Date(entry.lastChecked).getTime();
+        return age > this.ttlMs;
+    }
+}
+//# sourceMappingURL=version-cache.js.map

package/dist/version-manager/version-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version-cache.js","sourceRoot":"","sources":["../../src/version-manager/version-cache.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,SAAS,CAAA;AAChE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AACnC,OAAO,EAAE,MAAM,SAAS,CAAA;AACxB,OAAO,IAAI,MAAM,WAAW,CAAA;AAkB5B,8EAA8E;AAC9E,qBAAqB;AACrB,8EAA8E;AAE9E;;;;;GAKG;AACH,MAAM,OAAO,YAAY;IACN,SAAS,CAAQ;IACjB,KAAK,CAAQ;IAE9B,YACE,YAAoB,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,YAAY,EAAE,mBAAmB,CAAC,EAC9E,QAAgB,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI;QAEnC,IAAI,CAAC,SAAS,GAAG,SAAS,CAAA;QAC1B,IAAI,CAAC,KAAK,GAAG,KAAK,CAAA;IACpB,CAAC;IAED;;OAEG;IACH,IAAI;QACF,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,YAAY,CAAC,IAAI,CAAC,SAAS,EAAE,OAAO,CAAC,CAAA;YACjD,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAsB,CAAA;YAElD,IACE,OAAO,KAAK,CAAC,WAAW,KAAK,QAAQ;gBACrC,OAAO,KAAK,CAAC,aAAa,KAAK,QAAQ;gBACvC,OAAO,KAAK,CAAC,cAAc,KAAK,QAAQ,EACxC,CAAC;gBACD,OAAO,IAAI,CAAA;YACb,CAAC;YAED,IAAI,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC;gBAC1B,OAAO,IAAI,CAAA;YACb,CAAC;YAED,OAAO,KAAK,CAAA;QACd,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,IAAI,CAAA;QACb,CAAC;IACH,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,KAAwB;QAC5B,IAAI,CAAC;YACH,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;YACvD,aAAa,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,OAAO,CAAC,CAAA;QACxE,CAAC;QAAC,MAAM,CAAC;YACP,wEAAwE;QAC1E,CAAC;IACH,CAAC;IAED;;OAEG;IACH,SAAS,CAAC,KAAwB;QAChC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,OAAO,EAAE,CAAA;QAC9D,OAAO,GAAG,GAAG,IAAI,CAAC,KAAK,CAAA;IACzB,CAAC;CACF"}

package/dist/version-manager/version-manager-impl.d.ts

@@ -0,0 +1,81 @@
+/**
+ * VersionManagerImpl — concrete implementation of the VersionManager interface.
+ *
+ * Handles update checks with caching, upgrade previews, and config migration delegation.
+ * (AC6, FR62, FR64)
+ */
+import type { VersionManager, VersionCheckResult, UpgradePreview } from './version-manager.js';
+import { UpdateChecker } from './update-checker.js';
+import { VersionCache } from './version-cache.js';
+import type { MigrationResult } from '../config/index.js';
+export interface VersionManagerDeps {
+    cache?: VersionCache;
+    updateChecker?: UpdateChecker;
+    /**
+     * Whether the update_check config setting is enabled.
+     * Pass `false` when `global.update_check` is explicitly set to `false` in config.
+     * Defaults to `true` (checks enabled).
+     */
+    updateCheckEnabled?: boolean;
+}
+/**
+ * Concrete implementation of VersionManager.
+ *
+ * @param deps - Optional overrides for cache and updateChecker (for testing)
+ */
+export declare class VersionManagerImpl implements VersionManager {
+    private readonly cache;
+    private readonly updateChecker;
+    private readonly updateCheckEnabled;
+    constructor(deps?: VersionManagerDeps);
+    /**
+     * Read the current package version from the bundled package.json.
+     * Tries multiple relative paths because the bundler may place this chunk
+     * at different depths (e.g. dist/version-manager-impl-xxx.js vs
+     * src/modules/version-manager/version-manager-impl.ts).
+     * Falls back to '0.0.0' if the file is unreadable.
+     */
+    getCurrentVersion(): string;
+    /**
+     * Check whether a newer version is available on npm.
+     *
+     * Respects:
+     * 1. update_check config setting (AC5)
+     * 2. SUBSTRATE_NO_UPDATE_CHECK env var
+     * 3. Cache TTL (24h by default), unless forceRefresh is true
+     *
+     * Returns updateAvailable: false without a network call when checks are disabled
+     * or the cache is fresh (and forceRefresh is not set).
+     *
+     * @param forceRefresh - When true, skips the cache and always makes a fresh network request.
+     */
+    checkForUpdates(forceRefresh?: boolean): Promise<VersionCheckResult>;
+    /**
+     * Return an upgrade preview for the given target version.
+     */
+    getUpgradePreview(targetVersion: string): UpgradePreview;
+    /**
+     * Migrate the project configuration from one format version to another.
+     * Delegates to the shared defaultConfigMigrator singleton.
+     * Loads the actual config from the project config file so migration functions receive real data.
+     */
+    migrateConfiguration(fromVersion: string, toVersion: string): MigrationResult;
+    /**
+     * Migrate a task graph file from one format version to another.
+     * Delegates to the shared defaultConfigMigrator singleton.
+     */
+    migrateTaskGraphFormat(fromVersion: string, toVersion: string, filePath: string): MigrationResult;
+    /**
+     * Check whether the given config format version is supported by this toolkit.
+     */
+    isConfigCompatible(configVersion: string): boolean;
+    /**
+     * Check whether the given task graph format version is supported by this toolkit.
+     */
+    isTaskGraphCompatible(graphVersion: string): boolean;
+}
+/**
+ * Create a new VersionManager instance with optional dependency overrides.
+ */
+export declare function createVersionManager(deps?: VersionManagerDeps): VersionManager;
+//# sourceMappingURL=version-manager-impl.d.ts.map

package/dist/version-manager/version-manager-impl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version-manager-impl.d.ts","sourceRoot":"","sources":["../../src/version-manager/version-manager-impl.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAOH,OAAO,KAAK,EAAE,cAAc,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAC9F,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AACjD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAA;AAWzD,MAAM,WAAW,kBAAkB;IACjC,KAAK,CAAC,EAAE,YAAY,CAAA;IACpB,aAAa,CAAC,EAAE,aAAa,CAAA;IAC7B;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAA;CAC7B;AAMD;;;;GAIG;AACH,qBAAa,kBAAmB,YAAW,cAAc;IACvD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAc;IACpC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAe;IAC7C,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAS;gBAEhC,IAAI,GAAE,kBAAuB;IAMzC;;;;;;OAMG;IACH,iBAAiB,IAAI,MAAM;IA0B3B;;;;;;;;;;;;OAYG;IACG,eAAe,CAAC,YAAY,UAAQ,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAwExE;;OAEG;IACH,iBAAiB,CAAC,aAAa,EAAE,MAAM,GAAG,cAAc;IAkBxD;;;;OAIG;IACH,oBAAoB,CAAC,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,eAAe;IAsB7E;;;OAGG;IACH,sBAAsB,CAAC,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,eAAe;IAKjG;;OAEG;IACH,kBAAkB,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO;IAIlD;;OAEG;IACH,qBAAqB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO;CAGrD;AAMD;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,GAAE,kBAAuB,GAAG,cAAc,CAElF"}