hagiscript-sdk 0.2.9-dev.1780142424.1.dedbfb7

package/dist/src/runtime/node-release.js

@@ -0,0 +1,149 @@
+import { mapNodePlatform } from "./node-platform.js";
+export const DEFAULT_NODE_MAJOR = 22;
+export const OFFICIAL_NODE_DIST_BASE_URL = "https://nodejs.org/dist";
+export class NodeVersionSelectorError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "NodeVersionSelectorError";
+    }
+}
+export class NodeRuntimeSourcePolicyError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "NodeRuntimeSourcePolicyError";
+    }
+}
+export function normalizeVersionSelector(selector) {
+    const trimmed = selector?.trim();
+    return trimmed && trimmed.length > 0
+        ? trimmed.toLowerCase()
+        : String(DEFAULT_NODE_MAJOR);
+}
+export function validateVersionSelector(selector) {
+    const normalized = normalizeVersionSelector(selector);
+    if (["lts", "latest", "current"].includes(normalized)) {
+        return;
+    }
+    if (/^v?\d+(?:\.\d+\.\d+)?$/.test(normalized)) {
+        return;
+    }
+    throw new NodeVersionSelectorError(`Invalid Node.js version selector: ${selector ?? ""}. Use lts, latest, current, 22, 22.11.0, or v22.11.0.`);
+}
+export async function fetchNodeReleaseMetadata(fetchImpl = fetch, baseUrl = OFFICIAL_NODE_DIST_BASE_URL) {
+    assertOfficialNodeDistBaseUrl(baseUrl);
+    const response = await fetchImpl(`${baseUrl}/index.json`, {
+        headers: { accept: "application/json" }
+    });
+    if (!response.ok) {
+        throw new Error(`Failed to fetch Node.js release metadata: HTTP ${response.status}`);
+    }
+    const data = (await response.json());
+    if (!Array.isArray(data)) {
+        throw new Error("Node.js release metadata response was not an array.");
+    }
+    return data.map(parseReleaseMetadata);
+}
+export function resolveNodeRelease(releases, selector, platform) {
+    validateVersionSelector(selector);
+    const normalized = normalizeVersionSelector(selector);
+    const sorted = [...releases].sort(compareReleaseDescending);
+    const selected = selectRelease(sorted, normalized, platform);
+    if (!selected) {
+        throw new NodeVersionSelectorError(`No Node.js release matched version selector: ${selector ?? DEFAULT_NODE_MAJOR}`);
+    }
+    return selected;
+}
+export function selectNodeArchive(releases, selector, platform = mapNodePlatform(), baseUrl = OFFICIAL_NODE_DIST_BASE_URL) {
+    assertOfficialNodeDistBaseUrl(baseUrl);
+    const release = resolveNodeRelease(releases, selector, platform);
+    if (!release.files.includes(platform.releaseFileKey)) {
+        throw new Error(`Node.js ${release.version} does not publish an archive for ${platform.nodeFileKey}.`);
+    }
+    const fileName = `node-${release.version}-${platform.nodeFileKey}.${platform.archiveExtension}`;
+    const url = `${baseUrl}/${release.version}/${fileName}`;
+    assertOfficialNodeArchiveUrl(url, baseUrl);
+    return {
+        release,
+        version: release.version,
+        platform,
+        fileName,
+        url
+    };
+}
+export function assertOfficialNodeDistBaseUrl(baseUrl) {
+    let parsed;
+    try {
+        parsed = new URL(baseUrl);
+    }
+    catch {
+        throw new NodeRuntimeSourcePolicyError(`Node.js runtime source is not a valid URL: ${baseUrl}`);
+    }
+    if (parsed.protocol !== "https:" || parsed.hostname !== "nodejs.org") {
+        throw new NodeRuntimeSourcePolicyError(`Node.js runtime source is not governed by the official distribution host: ${baseUrl}`);
+    }
+}
+function assertOfficialNodeArchiveUrl(url, baseUrl) {
+    assertOfficialNodeDistBaseUrl(baseUrl);
+    const parsedUrl = new URL(url);
+    const parsedBaseUrl = new URL(baseUrl);
+    if (parsedUrl.protocol !== "https:" ||
+        parsedUrl.hostname !== parsedBaseUrl.hostname ||
+        !parsedUrl.pathname.startsWith("/dist/v")) {
+        throw new NodeRuntimeSourcePolicyError(`Node.js archive URL violates source policy: ${url}`);
+    }
+}
+function parseReleaseMetadata(value) {
+    if (typeof value !== "object" || value === null) {
+        throw new Error("Node.js release metadata item was not an object.");
+    }
+    const record = value;
+    if (typeof record.version !== "string" || !Array.isArray(record.files)) {
+        throw new Error("Node.js release metadata item is missing version or files.");
+    }
+    return {
+        version: record.version,
+        lts: typeof record.lts === "string" || typeof record.lts === "boolean"
+            ? record.lts
+            : undefined,
+        files: record.files.filter((file) => typeof file === "string"),
+        npm: typeof record.npm === "string" ? record.npm : undefined
+    };
+}
+function selectRelease(releases, selector, platform) {
+    const candidates = platform
+        ? releases.filter((release) => release.files.includes(platform.releaseFileKey))
+        : releases;
+    if (selector === "lts") {
+        return candidates.find((release) => Boolean(release.lts));
+    }
+    if (selector === "latest" || selector === "current") {
+        return candidates[0];
+    }
+    if (/^v?\d+$/.test(selector)) {
+        const major = Number(selector.replace(/^v/, ""));
+        return candidates.find((release) => getMajorVersion(release.version) === major);
+    }
+    const exact = selector.startsWith("v") ? selector : `v${selector}`;
+    return candidates.find((release) => release.version === exact);
+}
+function compareReleaseDescending(left, right) {
+    const leftParts = parseVersionParts(left.version);
+    const rightParts = parseVersionParts(right.version);
+    for (let index = 0; index < 3; index += 1) {
+        if (leftParts[index] !== rightParts[index]) {
+            return rightParts[index] - leftParts[index];
+        }
+    }
+    return 0;
+}
+function getMajorVersion(version) {
+    return parseVersionParts(version)[0];
+}
+function parseVersionParts(version) {
+    const match = /^v?(\d+)\.(\d+)\.(\d+)$/.exec(version);
+    if (!match) {
+        return [0, 0, 0];
+    }
+    return [Number(match[1]), Number(match[2]), Number(match[3])];
+}
+//# sourceMappingURL=node-release.js.map

package/dist/src/runtime/node-release.js.map

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

package/dist/src/runtime/node-verify.d.ts

@@ -0,0 +1,30 @@
+export interface RuntimeExecutablePaths {
+    nodePath: string;
+    npmPath: string;
+}
+export interface RuntimeCommandInvocation {
+    command: string;
+    args: string[];
+    launchOptions: {
+        shell?: boolean;
+    };
+}
+export interface NodeRuntimeVerificationResult {
+    valid: boolean;
+    targetDirectory: string;
+    nodeVersion?: string;
+    npmVersion?: string;
+    nodePath?: string;
+    npmPath?: string;
+    failureReason?: string;
+}
+export interface VerifyNodeRuntimeOptions {
+    platform?: NodeJS.Platform;
+    timeoutMs?: number;
+    runCommand?: (command: string, args: string[], timeoutMs: number, launchOptions?: {
+        shell?: boolean;
+    }) => Promise<string>;
+}
+export declare function verifyNodeRuntime(targetDirectory: string, options?: VerifyNodeRuntimeOptions): Promise<NodeRuntimeVerificationResult>;
+export declare function buildRuntimeNpmInvocation(paths: RuntimeExecutablePaths, args: string[], platform?: NodeJS.Platform): RuntimeCommandInvocation;
+export declare function getRuntimeExecutablePaths(targetDirectory: string, platform?: NodeJS.Platform): RuntimeExecutablePaths;

package/dist/src/runtime/node-verify.js

@@ -0,0 +1,102 @@
+import { access } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { constants } from "node:fs";
+import { CommandExecutionError, getCommandLaunchOptions, runCommand as defaultRunCommand } from "./command-launch.js";
+export async function verifyNodeRuntime(targetDirectory, options = {}) {
+    const timeoutMs = options.timeoutMs ?? 15_000;
+    const runCommand = options.runCommand ?? runVersionCommand;
+    const paths = getRuntimeExecutablePaths(targetDirectory, options.platform);
+    const npmInvocation = buildRuntimeNpmInvocation(paths, ["--version"], options.platform);
+    try {
+        await access(paths.nodePath, constants.X_OK);
+        await access(resolveNpmValidationTargetPath(paths, options.platform), constants.X_OK);
+        const nodeLaunchOptions = getCommandLaunchOptions(paths.nodePath, {
+            platform: options.platform
+        });
+        const [nodeVersion, npmVersion] = await Promise.all([
+            runCommand(paths.nodePath, ["--version"], timeoutMs, {
+                ...nodeLaunchOptions
+            }),
+            runCommand(npmInvocation.command, npmInvocation.args, timeoutMs, npmInvocation.launchOptions)
+        ]);
+        return {
+            valid: true,
+            targetDirectory,
+            nodeVersion: nodeVersion.trim(),
+            npmVersion: npmVersion.trim(),
+            nodePath: paths.nodePath,
+            npmPath: paths.npmPath
+        };
+    }
+    catch (error) {
+        return {
+            valid: false,
+            targetDirectory,
+            nodePath: paths.nodePath,
+            npmPath: paths.npmPath,
+            failureReason: error instanceof Error ? error.message : String(error)
+        };
+    }
+}
+export function buildRuntimeNpmInvocation(paths, args, platform = process.platform) {
+    const nodeLaunchOptions = getCommandLaunchOptions(paths.nodePath, { platform });
+    if (platform === "win32" && !nodeLaunchOptions.shell) {
+        return {
+            command: paths.nodePath,
+            args: [resolveBundledWindowsNpmCliPath(paths), ...args],
+            launchOptions: {}
+        };
+    }
+    return {
+        command: paths.npmPath,
+        args,
+        launchOptions: getCommandLaunchOptions(paths.npmPath, { platform })
+    };
+}
+export function getRuntimeExecutablePaths(targetDirectory, platform = process.platform) {
+    if (platform === "win32") {
+        return {
+            nodePath: join(targetDirectory, "node.exe"),
+            npmPath: join(targetDirectory, "npm.cmd")
+        };
+    }
+    return {
+        nodePath: join(targetDirectory, "bin", "node"),
+        npmPath: join(targetDirectory, "bin", "npm")
+    };
+}
+async function runVersionCommand(command, args, timeoutMs, launchOptions = {}) {
+    try {
+        const { stdout } = await defaultRunCommand(command, args, {
+            timeoutMs,
+            env: prependExecutableDirectoryToPath(command),
+            shell: launchOptions.shell,
+            maxBuffer: 1024 * 1024
+        });
+        return stdout;
+    }
+    catch (error) {
+        const stderr = error instanceof CommandExecutionError ? error.context.stderr.trim() : "";
+        throw new Error(stderr.length > 0
+            ? stderr
+            : `Command failed: ${command} ${args.join(" ")}`);
+    }
+}
+function resolveNpmValidationTargetPath(paths, platform = process.platform) {
+    return platform === "win32"
+        ? resolveBundledWindowsNpmCliPath(paths)
+        : paths.npmPath;
+}
+function resolveBundledWindowsNpmCliPath(paths) {
+    return join(dirname(paths.nodePath), "node_modules", "npm", "bin", "npm-cli.js");
+}
+function prependExecutableDirectoryToPath(command, baseEnv = process.env) {
+    const executableDirectory = dirname(command);
+    const pathKey = process.platform === "win32" ? "Path" : "PATH";
+    const existingPath = process.platform === "win32" ? (baseEnv.Path ?? baseEnv.PATH ?? "") : (baseEnv.PATH ?? "");
+    return {
+        ...baseEnv,
+        [pathKey]: [executableDirectory, existingPath].filter(Boolean).join(process.platform === "win32" ? ";" : ":")
+    };
+}
+//# sourceMappingURL=node-verify.js.map

package/dist/src/runtime/node-verify.js.map

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

package/dist/src/runtime/npm-global.d.ts

@@ -0,0 +1,28 @@
+export interface NpmCommandResult {
+    command: string;
+    args: string[];
+    stdout: string;
+    stderr: string;
+}
+export interface NpmCommandFailureContext extends NpmCommandResult {
+    exitCode?: string | number | null;
+}
+export declare class NpmCommandError extends Error {
+    readonly context: NpmCommandFailureContext;
+    constructor(message: string, context: NpmCommandFailureContext);
+}
+export interface NpmGlobalCommandOptions {
+    timeoutMs?: number;
+    env?: NodeJS.ProcessEnv;
+    platform?: NodeJS.Platform;
+    nodePath?: string;
+    registryMirror?: string;
+    prefix?: string;
+    runCommand?: (command: string, args: string[], timeoutMs: number, launchOptions?: {
+        shell?: boolean;
+    }) => Promise<NpmCommandResult>;
+}
+export declare function listGlobalPackages(npmPath: string, options?: NpmGlobalCommandOptions): Promise<NpmCommandResult>;
+export declare function installGlobalPackage(npmPath: string, selector: string, options?: NpmGlobalCommandOptions): Promise<NpmCommandResult>;
+export declare function buildListGlobalPackagesArgs(options?: NpmGlobalCommandOptions): string[];
+export declare function buildInstallGlobalPackageArgs(selector: string, options?: NpmGlobalCommandOptions): string[];

package/dist/src/runtime/npm-global.js

@@ -0,0 +1,77 @@
+import { CommandExecutionError, getCommandLaunchOptions, runCommand as defaultRunCommand } from "./command-launch.js";
+import { buildRuntimeNpmInvocation, } from "./node-verify.js";
+export class NpmCommandError extends Error {
+    context;
+    constructor(message, context) {
+        super(message);
+        this.name = "NpmCommandError";
+        this.context = context;
+    }
+}
+export async function listGlobalPackages(npmPath, options = {}) {
+    return runNpmCommand(npmPath, buildListGlobalPackagesArgs(options), options);
+}
+export async function installGlobalPackage(npmPath, selector, options = {}) {
+    return runNpmCommand(npmPath, buildInstallGlobalPackageArgs(selector, options), options);
+}
+export function buildListGlobalPackagesArgs(options = {}) {
+    return appendGlobalNpmOptions(["list", "-g", "--depth=0", "--json"], options);
+}
+export function buildInstallGlobalPackageArgs(selector, options = {}) {
+    return appendGlobalNpmOptions(["install", "-g", selector], options);
+}
+function appendGlobalNpmOptions(args, options) {
+    const nextArgs = options.registryMirror
+        ? [...args, "--registry", options.registryMirror]
+        : [...args];
+    return options.prefix ? [...nextArgs, "--prefix", options.prefix] : nextArgs;
+}
+async function runNpmCommand(npmPath, args, options) {
+    const timeoutMs = options.timeoutMs ?? 120_000;
+    const invocation = buildNpmCommandInvocation(npmPath, args, options);
+    const runner = options.runCommand
+        ? options.runCommand
+        : (command, commandArgs, commandTimeoutMs, launchOptions) => execNpmCommand(command, commandArgs, commandTimeoutMs, options.env, launchOptions);
+    return runner(invocation.command, invocation.args, timeoutMs, invocation.launchOptions);
+}
+function buildNpmCommandInvocation(npmPath, args, options) {
+    const platform = options.platform ?? process.platform;
+    if (platform === "win32" && options.nodePath) {
+        return buildRuntimeNpmInvocation({
+            nodePath: options.nodePath,
+            npmPath,
+        }, args, platform);
+    }
+    return {
+        command: npmPath,
+        args,
+        launchOptions: getCommandLaunchOptions(npmPath, { platform })
+    };
+}
+async function execNpmCommand(command, args, timeoutMs, env, launchOptions = {}) {
+    try {
+        const { stdout, stderr } = await defaultRunCommand(command, args, {
+            timeoutMs,
+            env,
+            shell: launchOptions.shell,
+            maxBuffer: 10 * 1024 * 1024
+        });
+        return {
+            command,
+            args,
+            stdout,
+            stderr
+        };
+    }
+    catch (error) {
+        const context = error instanceof CommandExecutionError ? error.context : undefined;
+        throw new NpmCommandError(`npm command failed: ${command} ${args.join(" ")}`, {
+            command,
+            args,
+            stdout: context?.stdout ?? "",
+            stderr: context?.stderr ?? "",
+            exitCode: context?.exitCode
+        });
+    }
+}
+//# sourceMappingURL=npm-global.js.map

package/dist/src/runtime/npm-global.js.map

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

package/dist/src/runtime/npm-sync.d.ts

@@ -0,0 +1,164 @@
+import { NpmCommandError, type NpmCommandFailureContext, type NpmGlobalCommandOptions } from "./npm-global.js";
+import { verifyNodeRuntime } from "./node-verify.js";
+import { type CustomAgentCliToolInput, type ToolSyncGroupId, type ToolSyncRequirement } from "./tool-sync-catalog.js";
+export interface NpmSyncManifestEntry {
+    version: string;
+    target?: string;
+    toolId?: string;
+    toolDisplayName?: string;
+    toolGroup?: ToolSyncGroupId;
+    toolRequirement?: ToolSyncRequirement;
+}
+export interface NpmSyncManifest {
+    packages: Record<string, NpmSyncManifestEntry>;
+    syncMode: "packages" | "tools";
+    registryMirror?: string;
+}
+export interface NpmSyncToolManifestSelection {
+    optionalAgentCliSyncEnabled?: boolean;
+    selectedOptionalAgentCliIds?: string[];
+    customAgentClis?: CustomAgentCliToolInput[];
+}
+export interface NpmSyncToolManifest {
+    tools: NpmSyncToolManifestSelection;
+    registryMirror?: string;
+}
+export type InstalledGlobalPackages = Record<string, string>;
+export type NpmSyncActionKind = "noop" | "install" | "upgrade" | "downgrade" | "sync";
+export interface NpmSyncPlannedAction {
+    packageName: string;
+    requiredRange: string;
+    targetSelector: string;
+    selectedInstallSelector: string;
+    installedVersion?: string;
+    action: NpmSyncActionKind;
+    toolId?: string;
+    toolDisplayName?: string;
+    toolGroup?: ToolSyncGroupId;
+    toolRequirement?: ToolSyncRequirement;
+}
+export interface NpmSyncActionResult extends NpmSyncPlannedAction {
+    changed: boolean;
+    command?: string;
+    args?: string[];
+    stdout?: string;
+    stderr?: string;
+    fallback?: NpmSyncFallbackEvent;
+}
+export interface NpmSyncRuntimeMetadata {
+    targetDirectory: string;
+    nodePath: string;
+    npmPath: string;
+    nodeVersion: string;
+    npmVersion: string;
+}
+export type NpmSyncFallbackPolicy = "auto" | "mirror-only";
+export type NpmSyncCommandKind = "inventory" | "install";
+export interface NpmSyncFallbackEvent {
+    commandKind: NpmSyncCommandKind;
+    packageName?: string;
+    mirrorRegistry: string;
+    fallbackRegistry: string;
+    retrySucceeded: boolean;
+}
+export interface NpmSyncSummary {
+    runtime: NpmSyncRuntimeMetadata;
+    manifestPath: string;
+    packageCount: number;
+    syncMode: NpmSyncManifest["syncMode"];
+    registryMirror?: string;
+    fallbackPolicy: NpmSyncFallbackPolicy;
+    fallbackUsed: boolean;
+    fallbackEvents: NpmSyncFallbackEvent[];
+    noopCount: number;
+    changedCount: number;
+    actions: NpmSyncActionResult[];
+}
+export interface NpmSyncOptions {
+    runtimePath: string;
+    manifestPath?: string;
+    runtimeManifestPath?: string;
+    registryMirror?: string;
+    fallbackPolicy?: NpmSyncFallbackPolicy;
+    force?: boolean;
+    npmOptions?: NpmGlobalCommandOptions;
+    verifyRuntime?: typeof verifyNodeRuntime;
+    onLog?: (event: NpmSyncLogEvent) => void;
+}
+export interface NpmSyncPlanOptions {
+    force?: boolean;
+}
+export type NpmSyncLogEvent = {
+    type: "manifest-loaded";
+    manifestPath: string;
+    packageCount: number;
+    syncMode: NpmSyncManifest["syncMode"];
+    registryMirror?: string;
+} | {
+    type: "fallback-policy";
+    fallbackPolicy: NpmSyncFallbackPolicy;
+    registryMirror: string;
+    fallbackRegistry?: string;
+} | {
+    type: "fallback-used";
+    fallback: NpmSyncFallbackEvent;
+} | {
+    type: "mirror-only";
+    registryMirror: string;
+} | {
+    type: "runtime-valid";
+    runtime: NpmSyncRuntimeMetadata;
+} | {
+    type: "inventory";
+    packages: InstalledGlobalPackages;
+} | {
+    type: "planned-action";
+    action: NpmSyncPlannedAction;
+} | {
+    type: "skip";
+    action: NpmSyncPlannedAction;
+} | {
+    type: "install-start";
+    action: NpmSyncPlannedAction;
+} | {
+    type: "install-complete";
+    action: NpmSyncActionResult;
+} | {
+    type: "summary";
+    summary: NpmSyncSummary;
+};
+export declare class NpmSyncError extends Error {
+    constructor(message: string);
+}
+export declare class NpmManifestValidationError extends NpmSyncError {
+    readonly errors: string[];
+    constructor(errors: string[]);
+}
+export declare class NpmSyncCommandError extends NpmSyncError {
+    readonly packageName?: string;
+    readonly fallbackPolicy: NpmSyncFallbackPolicy;
+    readonly registryMirror?: string;
+    readonly fallbackRegistry?: string;
+    readonly fallbackAttempted: boolean;
+    readonly command: string;
+    readonly args: string[];
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly mirrorContext?: NpmCommandFailureContext;
+    readonly officialContext?: NpmCommandFailureContext;
+    constructor(message: string, error: NpmCommandError, options?: {
+        packageName?: string;
+        fallbackPolicy?: NpmSyncFallbackPolicy;
+        registryMirror?: string;
+        fallbackRegistry?: string;
+        mirrorError?: NpmCommandError;
+        officialError?: NpmCommandError;
+    });
+}
+export declare function loadNpmSyncManifest(manifestPath: string): Promise<NpmSyncManifest>;
+export declare function loadNpmSyncManifestFromRuntimeManifest(manifestPath?: string): Promise<NpmSyncManifest>;
+export declare function validateNpmSyncManifest(value: unknown): NpmSyncManifest;
+export declare function validateRegistryMirror(value: unknown, path?: string): string | undefined;
+export declare function normalizeGlobalInventory(stdout: string): InstalledGlobalPackages;
+export declare function createNpmSyncPlan(manifest: NpmSyncManifest, installed: InstalledGlobalPackages, options?: NpmSyncPlanOptions): NpmSyncPlannedAction[];
+export declare function syncNpmGlobals(options: NpmSyncOptions): Promise<NpmSyncSummary>;