gitnexus 1.6.9 → 1.6.10-aptos.0

package/dist/core/move/install.js

@@ -0,0 +1,391 @@
+import { createHash } from 'node:crypto';
+import { execFile } from 'node:child_process';
+import { constants as fsConstants } from 'node:fs';
+import { access, chmod, copyFile, lstat, mkdir, mkdtemp, open, readFile, readdir, rename, rm, writeFile, } from 'node:fs/promises';
+import { get as httpsGet } from 'node:https';
+import os from 'node:os';
+import path from 'node:path';
+import { promisify } from 'node:util';
+import { downloadToFile, MAX_ARCHIVE_BYTES, sha256File, verifyArchiveChecksum, } from './artifact-download.js';
+import { acquireInstallLock, moveFlowInstallLockWaitMs } from './install-lock.js';
+import { isCompatibleMoveFlowVersion, MOVE_FLOW_RELEASE } from './release.js';
+const DEFAULT_HTTP_TIMEOUT_MS = 30_000;
+const MAX_CHECKSUM_BYTES = 1024 * 1024;
+const MAX_BINARY_BYTES = 128 * 1024 * 1024;
+const MAX_METADATA_BYTES = 64 * 1024;
+const execFileAsync = promisify(execFile);
+const parsePositiveInteger = (value, fallback) => {
+    const parsed = Number(value);
+    return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : fallback;
+};
+const validateReleaseCoordinates = (version, repository, tag) => {
+    if (!/^\d+\.\d+\.\d+$/.test(version)) {
+        throw new Error(`invalid move-flow version '${version}'; expected X.Y.Z`);
+    }
+    if (!isCompatibleMoveFlowVersion(version)) {
+        throw new Error(`unsupported move-flow major version '${version}'`);
+    }
+    if (!/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repository)) {
+        throw new Error(`invalid move-flow repository '${repository}'; expected owner/name`);
+    }
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(tag)) {
+        throw new Error(`invalid move-flow release tag '${tag}'`);
+    }
+};
+const platformKey = (platform = process.platform, arch = process.arch) => {
+    if (platform === 'linux' && arch === 'x64')
+        return 'linux-x64';
+    if (platform === 'linux' && arch === 'arm64')
+        return 'linux-arm64';
+    if (platform === 'darwin' && arch === 'arm64')
+        return 'darwin-arm64';
+    if (platform === 'darwin' && arch === 'x64')
+        return 'darwin-x64';
+    if (platform === 'win32' && arch === 'x64')
+        return 'win32-x64';
+    return null;
+};
+const execFileOutput = (file, args, options) => execFileAsync(file, args, {
+    timeout: options.timeout,
+    env: options.env,
+    encoding: options.encoding ?? 'utf8',
+}).then(({ stdout }) => String(stdout));
+let detectedLinuxCompatibility;
+const detectLinuxCompatibility = async () => {
+    if (process.arch === 'x64') {
+        try {
+            const cpuinfo = await readFile('/proc/cpuinfo', 'utf8');
+            if (!/(^|\s)avx2(\s|$)/m.test(cpuinfo))
+                return true;
+        }
+        catch {
+            return true;
+        }
+    }
+    try {
+        const output = await execFileOutput('ldd', ['--version'], { timeout: 3_000 });
+        const match = /(\d+)\.(\d+)/.exec(output.split('\n')[0] ?? '');
+        if (!match)
+            return true;
+        const major = Number(match[1]);
+        const minor = Number(match[2]);
+        return major < 2 || (major === 2 && minor < 34);
+    }
+    catch {
+        return true;
+    }
+};
+const linuxNeedsCompatBuild = (env) => {
+    if (process.platform !== 'linux')
+        return Promise.resolve(false);
+    if (env.GITNEXUS_MOVE_FLOW_COMPAT === '1')
+        return Promise.resolve(true);
+    detectedLinuxCompatibility ??= detectLinuxCompatibility();
+    return detectedLinuxCompatibility;
+};
+const releaseTargetForPlatform = async (key, env) => {
+    switch (key) {
+        case 'darwin-arm64':
+            return 'aarch64-apple-darwin';
+        case 'darwin-x64':
+            return 'x86_64-apple-darwin';
+        case 'linux-arm64':
+            return `aarch64-unknown-linux-gnu${(await linuxNeedsCompatBuild(env)) ? '-compat' : ''}`;
+        case 'linux-x64':
+            return `x86_64-unknown-linux-gnu${(await linuxNeedsCompatBuild(env)) ? '-compat' : ''}`;
+        case 'win32-x64':
+            return 'x86_64-pc-windows-msvc';
+        default:
+            return null;
+    }
+};
+export async function getMoveFlowInstallConfig(env = process.env) {
+    const key = platformKey();
+    if (!key)
+        return null;
+    const version = env.GITNEXUS_MOVE_FLOW_VERSION?.trim() || MOVE_FLOW_RELEASE.version;
+    const repository = env.GITNEXUS_MOVE_FLOW_REPO?.trim() || MOVE_FLOW_RELEASE.repository;
+    const tag = env.GITNEXUS_MOVE_FLOW_TAG?.trim() || `${MOVE_FLOW_RELEASE.tagPrefix}${version}`;
+    validateReleaseCoordinates(version, repository, tag);
+    const releaseTarget = await releaseTargetForPlatform(key, env);
+    if (!releaseTarget)
+        return null;
+    const assetName = `${tag}-${releaseTarget}.zip`;
+    if (path.basename(assetName) !== assetName)
+        throw new Error('invalid move-flow asset name');
+    const identity = createHash('sha256')
+        .update(`${repository}\0${tag}\0${assetName}`)
+        .digest('hex')
+        .slice(0, 12);
+    const cacheRoot = env.GITNEXUS_MOVE_FLOW_DIR?.trim()
+        ? path.resolve(env.GITNEXUS_MOVE_FLOW_DIR)
+        : path.join(env.GITNEXUS_HOME?.trim() || path.join(os.homedir(), '.gitnexus'), 'tools', 'move-flow');
+    const installDir = path.join(cacheRoot, version, `${key}-${identity}`);
+    const binaryName = process.platform === 'win32' ? 'move-flow.exe' : 'move-flow';
+    return {
+        version,
+        repository,
+        tag,
+        releaseTarget,
+        assetName,
+        releaseBase: `https://github.com/${repository}/releases/download/${tag}`,
+        binaryName,
+        installDir,
+        binaryPath: path.join(installDir, binaryName),
+        metadataPath: path.join(installDir, 'release.json'),
+        lockPath: `${installDir}.install.lock`,
+        httpTimeoutMs: parsePositiveInteger(env.GITNEXUS_MOVE_FLOW_HTTP_TIMEOUT_MS, DEFAULT_HTTP_TIMEOUT_MS),
+    };
+}
+/** Resolve the configured release without downloading or starting move-flow. */
+export async function getMoveFlowReleaseSelection(env = process.env) {
+    const config = await getMoveFlowInstallConfig(env);
+    return config
+        ? {
+            version: config.version,
+            repository: config.repository,
+            tag: config.tag,
+            assetName: config.assetName,
+        }
+        : undefined;
+}
+export const powershellExpandArchiveInvocation = (archive, destination) => {
+    const archiveEnv = 'GITNEXUS_MOVE_FLOW_ARCHIVE_PATH';
+    const destinationEnv = 'GITNEXUS_MOVE_FLOW_DESTINATION_PATH';
+    return {
+        args: [
+            '-NoProfile',
+            '-NonInteractive',
+            '-Command',
+            `Expand-Archive -LiteralPath $env:${archiveEnv} -DestinationPath $env:${destinationEnv} -Force`,
+        ],
+        env: {
+            ...process.env,
+            [archiveEnv]: archive,
+            [destinationEnv]: destination,
+        },
+    };
+};
+export const reportedMoveFlowVersion = (output) => /(?:^|\s)v?(\d+\.\d+\.\d+)(?:\s|$)/.exec(output)?.[1] ?? null;
+const exactVersionMatches = async (binaryPath, version) => {
+    try {
+        const output = await execFileOutput(binaryPath, ['--version'], { timeout: 5_000 });
+        return reportedMoveFlowVersion(output) === version;
+    }
+    catch {
+        return false;
+    }
+};
+const expectedMetadata = (config) => ({
+    version: config.version,
+    repository: config.repository,
+    tag: config.tag,
+    assetName: config.assetName,
+});
+const verifiedBinary = (config, metadata) => ({
+    binaryPath: config.binaryPath,
+    version: metadata.version,
+    fingerprint: createHash('sha256')
+        .update(`${metadata.repository}\0${metadata.tag}\0${metadata.assetName}\0${metadata.binarySha256}`)
+        .digest('hex'),
+});
+const validCachedInstall = async (config) => {
+    let metadataHandle;
+    try {
+        // Single open, then every check reads through the handle, so the type/size
+        // gates and the JSON read cannot race a concurrent swap of the file
+        // (CodeQL js/file-system-race). O_NOFOLLOW makes the kernel reject a
+        // symlinked final component atomically on POSIX; Windows has no such flag
+        // (0 fallback) — there the fstat isFile() gate plus the downstream
+        // metadata/binary-hash validation carry the (home-dir, local-writer)
+        // threat model.
+        metadataHandle = await open(config.metadataPath, fsConstants.O_RDONLY | (fsConstants.O_NOFOLLOW ?? 0));
+        const metadataStat = await metadataHandle.stat();
+        if (!metadataStat.isFile() ||
+            metadataStat.size <= 0 ||
+            metadataStat.size > MAX_METADATA_BYTES) {
+            return null;
+        }
+        const metadata = JSON.parse(await metadataHandle.readFile({ encoding: 'utf8' }));
+        const expected = expectedMetadata(config);
+        const binaryStat = await lstat(config.binaryPath);
+        if (!binaryStat.isFile() || binaryStat.size <= 0 || binaryStat.size > MAX_BINARY_BYTES) {
+            return null;
+        }
+        await access(config.binaryPath, process.platform === 'win32' ? fsConstants.F_OK : fsConstants.X_OK);
+        if (metadata.schemaVersion !== 1 ||
+            metadata.version !== expected.version ||
+            metadata.repository !== expected.repository ||
+            metadata.tag !== expected.tag ||
+            metadata.assetName !== expected.assetName ||
+            metadata.binarySha256 !== (await sha256File(config.binaryPath))) {
+            return null;
+        }
+        if (!(await exactVersionMatches(config.binaryPath, config.version))) {
+            return null;
+        }
+        return verifiedBinary(config, metadata);
+    }
+    catch {
+        return null;
+    }
+    finally {
+        await metadataHandle?.close().catch(() => { });
+    }
+};
+export async function findCachedMoveFlowBinary(env = process.env) {
+    try {
+        const config = await getMoveFlowInstallConfig(env);
+        if (!config)
+            return null;
+        return validCachedInstall(config);
+    }
+    catch {
+        return null;
+    }
+}
+const extractZip = async (archive, destination) => {
+    await mkdir(destination, { recursive: true });
+    try {
+        if (process.platform === 'win32') {
+            const shell = process.env.ComSpec ? 'powershell.exe' : 'powershell';
+            const invocation = powershellExpandArchiveInvocation(archive, destination);
+            await execFileOutput(shell, invocation.args, { timeout: 30_000, env: invocation.env });
+            return;
+        }
+        await execFileOutput('unzip', ['-q', archive, '-d', destination], { timeout: 30_000 });
+    }
+    catch (error) {
+        throw new Error(`could not extract ${path.basename(archive)} (${error instanceof Error ? error.message : String(error)}). ` +
+            'Install unzip, or set MOVE_FLOW to an existing move-flow binary.');
+    }
+};
+const findExtractedBinary = async (root, binaryName) => {
+    const stack = [root];
+    const names = new Set([binaryName, 'move-flow']);
+    const candidates = [];
+    while (stack.length > 0) {
+        const current = stack.pop();
+        if (!current)
+            break;
+        const entries = await readdir(current, { withFileTypes: true });
+        for (const entry of entries) {
+            const full = path.join(current, entry.name);
+            if (entry.isDirectory())
+                stack.push(full);
+            else if (entry.isFile() && names.has(entry.name))
+                candidates.push(full);
+        }
+    }
+    if (candidates.length !== 1)
+        return null;
+    const candidate = candidates[0];
+    const binaryStat = await lstat(candidate);
+    return binaryStat.isFile() && binaryStat.size > 0 && binaryStat.size <= MAX_BINARY_BYTES
+        ? candidate
+        : null;
+};
+export async function installMoveFlow(env = process.env) {
+    // GITNEXUS_SKIP_OPTIONAL_GRAMMARS is the umbrella opt-out for all optional
+    // binary downloads (honored by the retired postinstall probe too).
+    for (const flag of ['GITNEXUS_SKIP_MOVE_FLOW', 'GITNEXUS_SKIP_OPTIONAL_GRAMMARS']) {
+        if (env[flag] === '1') {
+            return { status: 'skipped', message: `installation disabled by ${flag}=1` };
+        }
+    }
+    let config;
+    try {
+        config = await getMoveFlowInstallConfig(env);
+    }
+    catch (error) {
+        return {
+            status: 'failed',
+            message: error instanceof Error ? error.message : String(error),
+        };
+    }
+    if (!config) {
+        return {
+            status: 'unsupported',
+            message: `unsupported platform ${process.platform}-${process.arch}; set MOVE_FLOW to provide a binary`,
+        };
+    }
+    const cached = await validCachedInstall(config);
+    if (cached) {
+        return { status: 'available', binary: cached };
+    }
+    let releaseLock;
+    let tempDir;
+    let stagedDir;
+    try {
+        releaseLock = await acquireInstallLock(config.lockPath, {
+            waitTimeoutMs: moveFlowInstallLockWaitMs(config.httpTimeoutMs),
+        });
+        const published = await validCachedInstall(config);
+        if (published) {
+            return { status: 'available', binary: published };
+        }
+        tempDir = await mkdtemp(path.join(os.tmpdir(), 'move-flow-'));
+        const archivePath = path.join(tempDir, config.assetName);
+        const sumsPath = path.join(tempDir, 'SHA256SUMS');
+        const extractDir = path.join(tempDir, 'extract');
+        await downloadToFile(`${config.releaseBase}/SHA256SUMS`, sumsPath, config.httpTimeoutMs, httpsGet, MAX_CHECKSUM_BYTES);
+        await downloadToFile(`${config.releaseBase}/${config.assetName}`, archivePath, config.httpTimeoutMs, httpsGet, MAX_ARCHIVE_BYTES);
+        const verification = await verifyArchiveChecksum(await readFile(sumsPath, 'utf8'), config.assetName, archivePath);
+        if (verification.status === 'missing') {
+            return {
+                status: 'failed',
+                message: `SHA256SUMS does not list ${config.assetName}; refusing to install`,
+            };
+        }
+        if (verification.status === 'mismatch') {
+            return {
+                status: 'failed',
+                message: `checksum mismatch for ${config.assetName}; refusing to install`,
+            };
+        }
+        await extractZip(archivePath, extractDir);
+        const extracted = await findExtractedBinary(extractDir, config.binaryName);
+        if (!extracted) {
+            return {
+                status: 'failed',
+                message: `${config.assetName} did not contain ${config.binaryName}; refusing to install`,
+            };
+        }
+        await mkdir(path.dirname(config.installDir), { recursive: true });
+        stagedDir = await mkdtemp(`${config.installDir}.partial-`);
+        const stagedBinary = path.join(stagedDir, config.binaryName);
+        await copyFile(extracted, stagedBinary);
+        if (process.platform !== 'win32')
+            await chmod(stagedBinary, 0o755);
+        if (!(await exactVersionMatches(stagedBinary, config.version))) {
+            return {
+                status: 'failed',
+                message: `installed binary did not report exact version ${config.version}; refusing to keep it`,
+            };
+        }
+        const metadata = {
+            schemaVersion: 1,
+            ...expectedMetadata(config),
+            archiveSha256: verification.actual,
+            binarySha256: await sha256File(stagedBinary),
+        };
+        await writeFile(path.join(stagedDir, 'release.json'), JSON.stringify(metadata, null, 2));
+        await rm(config.installDir, { recursive: true, force: true });
+        await rename(stagedDir, config.installDir);
+        stagedDir = undefined;
+        return { status: 'installed', binary: verifiedBinary(config, metadata) };
+    }
+    catch (error) {
+        return {
+            status: 'failed',
+            message: `installation failed: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    finally {
+        await Promise.allSettled([
+            tempDir && rm(tempDir, { recursive: true, force: true }),
+            stagedDir && rm(stagedDir, { recursive: true, force: true }),
+            releaseLock?.(),
+        ]);
+    }
+}

package/dist/core/move/mcp-client.d.ts

@@ -0,0 +1,115 @@
+/**
+ * MoveFlowClient implementation that spawns `move-flow mcp` and communicates
+ * via MCP JSON-RPC over stdio (newline-delimited JSON).
+ *
+ * The move-flow binary (Rust/rmcp) is expected at `process.env.MOVE_FLOW`
+ * or on $PATH as `move-flow`.
+ */
+import type { MoveFactsMap, CallGraphMap } from './compiler-facts.js';
+/**
+ * A move-flow tool call that failed in user space: the package could not be
+ * built (an `isError: true` tool result whose content text carries the
+ * diagnostic, e.g. "failed to build package `<path>`: <reason>") or the request
+ * parameters were rejected (JSON-RPC -32602 invalid_params). Distinguishes
+ * caller/input errors from transport and server faults so callers can render
+ * them as user-actionable.
+ */
+export declare class MoveFlowToolCallError extends Error {
+    /** JSON-RPC error code when the failure surfaced as a protocol error. */
+    readonly code?: number;
+    constructor(message: string, opts?: {
+        code?: number;
+    });
+}
+/**
+ * The move-flow surface GitNexus consumes. Defined here (not in the ingest
+ * phase) so the client owns its own contract and the ingest phase depends on
+ * the client, never the reverse.
+ */
+export interface MoveFlowClient {
+    /** Full-fidelity per-module facts (move_package_query query:"facts"). */
+    facts(packagePath: string): Promise<MoveFactsMap>;
+    /** Function-level call graph (caller qualified name → callee qualified names). */
+    callGraph(packagePath: string): Promise<CallGraphMap>;
+    /**
+     * Build status probe (move_package_status): does the package compile, and
+     * what did the compiler say. Older move-flow builds do not expose the tool -
+     * gate calls solely on `capabilities().hasStatusTool` (like `facts` on
+     * `hasFactsQuery`).
+     */
+    packageStatus(packagePath: string): Promise<MovePackageStatus>;
+    /** Capability probe (cached): which queries this move-flow build supports. */
+    capabilities(): Promise<MoveFlowCapabilities>;
+    shutdown(): Promise<void>;
+}
+/**
+ * Result of `move_package_status`: whether the package builds, plus the raw
+ * text move-flow returned ("no errors or warnings" on success, the compiler
+ * diagnostics on failure).
+ */
+export interface MovePackageStatus {
+    ok: boolean;
+    diagnostics: string;
+}
+/** What a given move-flow build can answer. */
+export interface MoveFlowCapabilities {
+    /** `facts` query available (rich, compiler-sourced per-module facts). */
+    hasFactsQuery: boolean;
+    /** `move_package_status` tool available (build status + diagnostics). */
+    hasStatusTool: boolean;
+}
+/** Minimal shape of an entry in an MCP `tools/list` response. */
+export interface MoveFlowToolInfo {
+    name: string;
+    inputSchema?: unknown;
+}
+/**
+ * Derive move-flow capabilities from a `tools/list` response.
+ *
+ * `facts` is a *query type* on `move_package_query` (a `const` in the tool's
+ * `inputSchema` QueryType enum), not a standalone tool — so we detect it by
+ * inspecting the schema. A hypothetical future standalone `move_package_facts`
+ * tool is also honoured for forward-compatibility.
+ *
+ * Accepts either bare tool-name strings or `{ name, inputSchema }` entries.
+ */
+export declare function detectMoveFlowCapabilities(tools: ReadonlyArray<string | MoveFlowToolInfo>): MoveFlowCapabilities;
+export declare class MoveFlowMcpClient implements MoveFlowClient {
+    private proc;
+    private requestId;
+    private pending;
+    private initialized;
+    private initPromise;
+    private capsPromise;
+    private binaryPath;
+    private stderrLines;
+    private static readonly MAX_STDERR;
+    private stderrContext;
+    constructor(binaryPath?: string);
+    private failProcess;
+    private ensureStarted;
+    private _start;
+    private send;
+    private request;
+    private callTool;
+    callGraph(packagePath: string): Promise<CallGraphMap>;
+    facts(packagePath: string): Promise<MoveFactsMap>;
+    packageStatus(packagePath: string): Promise<MovePackageStatus>;
+    /** Raw JSON-RPC request (non-`tools/call`), e.g. `tools/list`. */
+    private rpcRequest;
+    capabilities(): Promise<MoveFlowCapabilities>;
+    shutdown(): Promise<void>;
+}
+export interface ResolvedMoveFlowClient {
+    client: MoveFlowMcpClient;
+    version: string;
+}
+/** Construct a client for a binary that was already verified by the installer. */
+export declare const createMoveFlowClient: (binaryPath: string) => MoveFlowMcpClient;
+/**
+ * Probe and resolve a move-flow candidate exactly once, returning null when
+ * the binary is missing or reports an incompatible major version. When
+ * `binaryPath` is provided only that path is probed; otherwise resolution is
+ * `$MOVE_FLOW` (explicit override), then `move-flow` on `$PATH`.
+ */
+export declare function tryResolveMoveFlowClient(binaryPath?: string): ResolvedMoveFlowClient | null;