@guiho/runx 0.2.6 → 0.4.0

package/library/self-management.js

@@ -1,55 +1,213 @@
-import { Buffer } from 'node:buffer';
-import { chmod, rename, rm } from 'node:fs/promises';
-import { basename } from 'node:path';
+/**
+ * @copyright Copyright © 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ */
+import { $ } from 'bun';
+import { compare, gt, valid } from 'semver';
 import { RunXError } from './errors.js';
+import { applyAgentInstructions, updateAgentSkill } from './agents.js';
 import { readVersion } from './help.js';
-export { checkForLatestVersion, listAvailableVersions, uninstallSelf, upgradeSelf, };
-const repositoryApi = 'https://api.github.com/repos/CGuiho/runx/releases';
-const checkForLatestVersion = async () => {
-    const currentVersion = readVersion();
-    try {
-        const response = await fetch(`${repositoryApi}/latest`, { headers: { accept: 'application/vnd.github+json' } });
-        if (!response.ok)
-            return { currentVersion, latestVersion: currentVersion, updateAvailable: false };
-        const release = await response.json();
-        const latestVersion = release.tag_name.replace(/^@guiho\/runx@/, '').replace(/^v/, '');
-        const asset = findAsset(release);
-        return { currentVersion, latestVersion, updateAvailable: compareVersions(latestVersion, currentVersion) > 0, url: asset?.browser_download_url };
-    }
-    catch {
-        return { currentVersion, latestVersion: currentVersion, updateAvailable: false };
+import { baseName } from './path-utils.js';
+import { fetchReleaseCatalog, resolveUpgradePlatform } from './release-catalog.js';
+import { createRecoveryInstructions } from './recovery.js';
+export { checkForLatestVersion, listAvailableVersions, uninstallSelf, upgradeSelf, validateNativeBinary };
+class UpgradeOperationError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'UpgradeOperationError';
+        this.code = code;
     }
+}
+const defaultFileOperations = {
+    rename: async (from, to) => {
+        if (process.platform === 'win32') {
+            const child = Bun.spawn(['cmd.exe', '/d', '/s', '/c', 'move', '/y', from, to], { stdout: 'pipe', stderr: 'pipe' });
+            const [code, error] = await Promise.all([child.exited, new Response(child.stderr).text()]);
+            if (code !== 0)
+                throw new Error(error.trim() || `Could not move ${from} to ${to}.`);
+            return;
+        }
+        await $ `mv ${from} ${to}`.quiet();
+    },
+    remove: async (path) => {
+        if (process.platform === 'win32') {
+            const child = Bun.spawn(['cmd.exe', '/d', '/s', '/c', 'del', '/f', '/q', path], { stdout: 'ignore', stderr: 'pipe' });
+            const [code, error] = await Promise.all([child.exited, new Response(child.stderr).text()]);
+            if (code !== 0 && await Bun.file(path).exists())
+                throw new Error(error.trim() || `Could not remove ${path}.`);
+            return;
+        }
+        await $ `rm -f ${path}`.quiet();
+    },
+    makeExecutable: async (path) => {
+        if (process.platform === 'win32')
+            return;
+        await $ `chmod 755 ${path}`.quiet();
+    },
+};
+const checkForLatestVersion = async () => {
+    const catalog = await listAvailableVersions();
+    const latest = catalog.releases.find((release) => release.latestStable);
+    return {
+        currentVersion: catalog.currentVersion,
+        latestVersion: catalog.latestStableVersion ?? catalog.currentVersion,
+        updateAvailable: Boolean(latest && valid(latest.version) && valid(catalog.currentVersion) && gt(latest.version, catalog.currentVersion)),
+        url: latest?.compatibleAsset?.url,
+    };
 };
 const listAvailableVersions = async () => {
-    const response = await fetch(`${repositoryApi}?per_page=20`, { headers: { accept: 'application/vnd.github+json' } });
-    if (!response.ok)
-        throw new RunXError(`Could not retrieve RunX releases: HTTP ${response.status}`);
-    const releases = await response.json();
-    return releases.map((release) => release.tag_name.replace(/^@guiho\/runx@/, '').replace(/^v/, ''));
+    const platform = resolveUpgradePlatform();
+    return fetchReleaseCatalog({ ...platform, currentVersion: readVersion() });
 };
-const upgradeSelf = async (dryRun) => {
-    const executablePath = requireNativeExecutable();
-    const update = await checkForLatestVersion();
-    const upToDate = !update.updateAvailable && update.latestVersion === update.currentVersion && Boolean(update.url);
-    if (!update.updateAvailable || !update.url)
-        return { ...update, executablePath, scheduled: false, upToDate };
-    if (dryRun)
-        return { ...update, executablePath, scheduled: false, upToDate: false };
-    const response = await fetch(update.url);
-    if (!response.ok)
-        throw new RunXError(`Could not download RunX update: HTTP ${response.status}`);
-    const temporaryPath = `${executablePath}.new`;
-    await Bun.write(temporaryPath, await response.arrayBuffer());
-    if (process.platform !== 'win32') {
-        await chmod(temporaryPath, 0o755);
-        await rename(temporaryPath, executablePath);
-        return { ...update, executablePath, scheduled: false, upToDate: false };
+const upgradeSelf = async (input) => {
+    const options = typeof input === 'boolean' ? { dryRun: input } : input;
+    const fileOperations = options.fileOperations ?? defaultFileOperations;
+    const currentVersion = options.currentVersion ?? readVersion();
+    const detectedPlatform = resolveUpgradePlatform(process.platform, options.arch ?? process.arch);
+    const platform = { ...detectedPlatform, variant: options.variant ?? detectedPlatform.variant };
+    const executablePath = resolveSelfExecutable();
+    const events = [];
+    let phase = 'plan';
+    let plan = null;
+    let recovery = createRecoveryInstructions(currentVersion, platform.os, 'fallback-current');
+    let temporaryPath = null;
+    let replacement = null;
+    let mutationCode = null;
+    const emit = (eventPhase, status, message) => {
+        phase = eventPhase;
+        const event = { sequence: events.length + 1, phase: eventPhase, status, ...(message ? { message } : {}) };
+        events.push(event);
+        options.onEvent?.(event);
+    };
+    emit('plan', 'started');
+    try {
+        let catalog;
+        try {
+            catalog = await fetchReleaseCatalog({ ...platform, currentVersion });
+        }
+        catch (error) {
+            throw new UpgradeOperationError(classifyPlanError(error), errorMessage(error));
+        }
+        const requestedVersion = options.requestedVersion?.replace(/^@guiho\/runx@/, '').replace(/^v/, '');
+        const stableTarget = requestedVersion
+            ? catalog.releases.find((release) => release.version === requestedVersion)
+            : catalog.releases.find((release) => release.latestStable);
+        if (!stableTarget || !catalog.latestStableVersion)
+            throw new UpgradeOperationError('release_lookup_failed', 'No stable RunX release is available for upgrade.');
+        const target = preventDowngrade(currentVersion, stableTarget, catalog.releases);
+        const targetIsCurrent = target.version === currentVersion;
+        recovery = createRecoveryInstructions(target.version, platform.os, 'resolved');
+        if (!targetIsCurrent && !target.compatibleAsset) {
+            throw new UpgradeOperationError('no_compatible_asset', `RunX ${target.version} has no compatible ${platform.os} ${platform.arch} asset.`);
+        }
+        plan = {
+            currentVersion,
+            targetVersion: target.version,
+            os: platform.os,
+            arch: platform.arch,
+            assetName: target.compatibleAsset?.name ?? '',
+            assetUrl: target.compatibleAsset?.url ?? '',
+            executablePath,
+        };
+        emit('plan', 'succeeded');
+        options.onPlan?.(plan);
+        if (baseName(executablePath).toLowerCase().startsWith('bun')) {
+            throw new UpgradeOperationError('verification_failed', 'Self-management requires a native RunX executable installed from a GitHub release.');
+        }
+        if (targetIsCurrent) {
+            emitSkippedMutation(events, options.onEvent);
+            return envelope('up-to-date', plan, events, { installedVersion: currentVersion, cleanupDeferred: false }, recovery);
+        }
+        if (options.dryRun) {
+            emitSkippedMutation(events, options.onEvent);
+            return envelope('dry-run', plan, events, null, recovery);
+        }
+        emit('download', 'started');
+        const response = await fetch(plan.assetUrl);
+        if (!response.ok)
+            throw new UpgradeOperationError('download_failed', `Could not download RunX ${plan.targetVersion}: HTTP ${response.status}`);
+        const bytes = new Uint8Array(await response.arrayBuffer());
+        if (bytes.length === 0)
+            throw new UpgradeOperationError('download_invalid', 'Downloaded RunX executable is empty.');
+        emit('download', 'succeeded');
+        emit('validate', 'started');
+        try {
+            validateNativeBinary(bytes, platform.os);
+            temporaryPath = `${executablePath}.new-${process.pid}-${crypto.randomUUID()}`;
+            await Bun.write(temporaryPath, bytes);
+            if (platform.os !== 'windows')
+                await fileOperations.makeExecutable(temporaryPath);
+        }
+        catch (error) {
+            throw asOperationError('download_invalid', error);
+        }
+        emit('validate', 'succeeded');
+        emit('replace', 'started');
+        replacement = { backupPath: `${executablePath}.old-${process.pid}-${crypto.randomUUID()}`, originalMoved: false };
+        mutationCode = 'backup_failed';
+        try {
+            await fileOperations.rename(executablePath, replacement.backupPath);
+            replacement.originalMoved = true;
+            mutationCode = 'replace_failed';
+            await fileOperations.rename(temporaryPath, executablePath);
+            temporaryPath = null;
+        }
+        catch (error) {
+            throw asOperationError(mutationCode, error);
+        }
+        emit('replace', 'succeeded');
+        emit('verify', 'started');
+        try {
+            await verifyExecutableVersion(executablePath, plan.targetVersion);
+        }
+        catch (error) {
+            throw asOperationError('verification_failed', error);
+        }
+        emit('verify', 'succeeded');
+        emit('cache', 'started');
+        if (Bun.env.NODE_ENV === 'test') {
+            emit('cache', 'skipped', 'Agent reconciliation is isolated during tests.');
+        }
+        else {
+            await updateAgentSkill('global', process.cwd());
+            await applyAgentInstructions(process.cwd());
+            emit('cache', 'succeeded', 'Agent skill and project instructions reconciled.');
+        }
+        emit('cleanup', 'started');
+        const cleanupDeferred = await cleanupBackup(replacement.backupPath, platform.os, fileOperations);
+        emit('cleanup', cleanupDeferred ? 'skipped' : 'succeeded', cleanupDeferred ? 'Old executable deletion was deferred; replacement already succeeded.' : undefined);
+        return envelope('upgraded', plan, events, { installedVersion: plan.targetVersion, cleanupDeferred }, recovery);
+    }
+    catch (error) {
+        const primary = asOperationError(classifyFailure(phase, mutationCode), error);
+        if (!events.some((event) => event.phase === phase && event.status === 'failed'))
+            emit(phase, 'failed', primary.message);
+        if (temporaryPath)
+            await fileOperations.remove(temporaryPath).catch(() => undefined);
+        if (replacement?.originalMoved) {
+            try {
+                await rollbackReplacement(replacement.backupPath, executablePath, fileOperations);
+                return envelope('rolled-back', plan, events, { installedVersion: currentVersion, cleanupDeferred: false }, recovery, {
+                    code: primary.code,
+                    phase,
+                    message: primary.message,
+                });
+            }
+            catch (rollbackError) {
+                return envelope('failed', plan, events, null, recovery, {
+                    code: 'rollback_failed',
+                    phase,
+                    message: `${primary.message}. Automatic rollback failed: ${errorMessage(rollbackError)}. Canonical path: ${executablePath}. Backup path: ${replacement.backupPath}.`,
+                });
+            }
+        }
+        return envelope('failed', plan, events, null, recovery, { code: primary.code, phase, message: primary.message });
     }
-    await replaceWindowsExecutable(temporaryPath, executablePath, update.latestVersion);
-    return { ...update, executablePath, scheduled: false, upToDate: false };
 };
 const uninstallSelf = async (dryRun) => {
-    const executablePath = requireNativeExecutable();
+    const executablePath = resolveSelfExecutable();
+    if (baseName(executablePath).toLowerCase().startsWith('bun'))
+        throw new RunXError('Self-management requires a native RunX executable installed from a GitHub release.');
     if (dryRun)
         return { executablePath, scheduled: false, dryRun: true };
     if (process.platform === 'win32') {
@@ -57,84 +215,106 @@ const uninstallSelf = async (dryRun) => {
         Bun.spawn(['cmd.exe', '/d', '/s', '/c', command], { detached: true, stdout: 'ignore', stderr: 'ignore', stdin: 'ignore' });
         return { executablePath, scheduled: true, dryRun: false };
     }
-    await rm(executablePath);
+    await defaultFileOperations.remove(executablePath);
     return { executablePath, scheduled: false, dryRun: false };
 };
-const findAsset = (release) => release.assets.find((asset) => asset.name === assetName());
-const assetName = () => `runx-${process.platform === 'win32' ? 'windows' : process.platform === 'darwin' ? 'darwin' : 'linux'}-${process.arch}${process.platform === 'win32' ? '.exe' : ''}`;
-const requireNativeExecutable = () => {
-    const executablePath = process.env['RUNX_SELF_PATH'] ?? process.execPath;
-    if (basename(executablePath).toLowerCase().startsWith('bun'))
-        throw new RunXError('Self-management requires a native RunX executable installed from a GitHub release.');
-    return executablePath;
+const envelope = (outcome, plan, events, result, recovery, error = null) => ({ schemaVersion: 1, command: 'runx upgrade', outcome, plan, events, result, recovery, error });
+const preventDowngrade = (currentVersion, stableTarget, releases) => {
+    if (!valid(currentVersion) || !valid(stableTarget.version) || compare(currentVersion, stableTarget.version) < 0)
+        return stableTarget;
+    return releases.find((release) => release.version === currentVersion) ?? {
+        tag: currentVersion,
+        version: currentVersion,
+        channel: valid(currentVersion)?.includes('-') ? 'prerelease' : 'stable',
+        prerelease: Boolean(valid(currentVersion)?.includes('-')),
+        publishedAt: null,
+        current: true,
+        latestStable: false,
+        compatibleAsset: null,
+    };
 };
-const replaceWindowsExecutable = async (temporaryPath, executablePath, expectedVersion) => {
-    const backupPath = `${executablePath}.old`;
-    let originalMoved = false;
-    try {
-        await rm(backupPath, { force: true });
-        await rename(executablePath, backupPath);
-        originalMoved = true;
-        await rename(temporaryPath, executablePath);
-        await verifyExecutableVersion(executablePath, expectedVersion);
-        await cleanupWindowsBackup(backupPath);
-    }
-    catch (error) {
-        const replacementFailure = errorMessage(error);
-        await rm(temporaryPath, { force: true }).catch(() => undefined);
-        if (!originalMoved) {
-            throw new RunXError(`Could not replace the Windows RunX executable at ${executablePath}: ${replacementFailure}`);
-        }
-        try {
-            await rm(executablePath, { force: true });
-            await rename(backupPath, executablePath);
-        }
-        catch (rollbackError) {
-            throw new RunXError(`Windows RunX upgrade failed at ${executablePath}: ${replacementFailure}. Automatic rollback also failed: ${errorMessage(rollbackError)}`);
-        }
-        throw new RunXError(`Windows RunX upgrade failed; the previous executable was restored at ${executablePath}: ${replacementFailure}`);
+const emitSkippedMutation = (events, onEvent) => {
+    for (const phase of ['download', 'validate', 'replace', 'verify', 'cache', 'cleanup']) {
+        const event = { sequence: events.length + 1, phase, status: 'skipped' };
+        events.push(event);
+        onEvent?.(event);
     }
 };
+const rollbackReplacement = async (backupPath, executablePath, operations) => {
+    await operations.remove(executablePath);
+    await operations.rename(backupPath, executablePath);
+};
 const verifyExecutableVersion = async (executablePath, expectedVersion) => {
     const verification = Bun.spawn([executablePath, '--version'], { stdin: 'ignore', stdout: 'pipe', stderr: 'pipe' });
+    let timeout;
+    const exited = Promise.race([
+        verification.exited,
+        new Promise((_, reject) => {
+            timeout = setTimeout(() => {
+                verification.kill();
+                reject(new Error('replacement version check timed out after 10 seconds'));
+            }, 10_000);
+        }),
+    ]);
     const [stdout, stderr, exitCode] = await Promise.all([
         new Response(verification.stdout).text(),
         new Response(verification.stderr).text(),
-        verification.exited,
-    ]);
+        exited,
+    ]).finally(() => {
+        if (timeout !== undefined)
+            clearTimeout(timeout);
+    });
     const actualVersion = stdout.trim();
     if (exitCode !== 0)
         throw new Error(`replacement exited with code ${exitCode}${stderr.trim() ? `: ${stderr.trim()}` : ''}`);
     if (actualVersion !== expectedVersion)
         throw new Error(`replacement reported version ${actualVersion || '<empty>'}; expected ${expectedVersion}`);
 };
-const cleanupWindowsBackup = async (backupPath) => {
+const cleanupBackup = async (backupPath, os, operations) => {
     try {
-        await rm(backupPath, { force: true });
+        await operations.remove(backupPath);
+        return false;
+    }
+    catch {
+        if (os !== 'windows')
+            throw new UpgradeOperationError('replace_failed', `Could not delete old RunX executable: ${backupPath}`);
+        scheduleWindowsBackupCleanup(backupPath);
+        return true;
     }
-    catch { }
-    scheduleWindowsBackupCleanup(backupPath);
 };
 const scheduleWindowsBackupCleanup = (backupPath) => {
     const command = 'for ($attempt = 0; $attempt -lt 300; $attempt += 1) { if (-not (Test-Path -LiteralPath $env:RUNX_BACKUP_PATH)) { exit 0 }; try { Remove-Item -LiteralPath $env:RUNX_BACKUP_PATH -Force -ErrorAction Stop; exit 0 } catch { Start-Sleep -Milliseconds 100 } }; exit 1';
-    const encodedCommand = Buffer.from(command, 'utf16le').toString('base64');
-    Bun.spawn(['cmd.exe', '/d', '/s', '/c', `powershell.exe -NoLogo -NoProfile -NonInteractive -WindowStyle Hidden -EncodedCommand ${encodedCommand}`], {
+    Bun.spawn(['powershell.exe', '-NoLogo', '-NoProfile', '-NonInteractive', '-WindowStyle', 'Hidden', '-Command', command], {
         detached: true,
         env: { ...process.env, RUNX_BACKUP_PATH: backupPath },
-        stdout: 'ignore',
-        stderr: 'ignore',
-        stdin: 'ignore',
-    });
+        stdout: 'ignore', stderr: 'ignore', stdin: 'ignore',
+    }).unref();
 };
-const errorMessage = (error) => error instanceof Error ? error.message : String(error);
-const compareVersions = (left, right) => {
-    const parse = (value) => value.split(/[.+-]/).map((part) => Number.parseInt(part, 10) || 0);
-    const a = parse(left);
-    const b = parse(right);
-    for (let index = 0; index < Math.max(a.length, b.length); index += 1) {
-        const difference = (a[index] ?? 0) - (b[index] ?? 0);
-        if (difference !== 0)
-            return difference;
-    }
-    return 0;
+const validateNativeBinary = (bytes, os) => {
+    const native = os === 'windows'
+        ? bytes[0] === 0x4d && bytes[1] === 0x5a
+        : os === 'linux'
+            ? bytes[0] === 0x7f && bytes[1] === 0x45 && bytes[2] === 0x4c && bytes[3] === 0x46
+            : isMachO(bytes);
+    if (!native)
+        throw new RunXError(`Downloaded file is not a native ${os} executable.`);
 };
+const isMachO = (bytes) => {
+    const magic = Array.from(bytes.slice(0, 4)).map((value) => value.toString(16).padStart(2, '0')).join('');
+    return ['feedface', 'feedfacf', 'cefaedfe', 'cffaedfe', 'cafebabe', 'bebafeca'].includes(magic);
+};
+const classifyPlanError = (error) => /malformed/.test(errorMessage(error)) ? 'release_payload_invalid' : 'release_lookup_failed';
+const classifyFailure = (phase, mutationCode) => {
+    if (phase === 'download')
+        return 'download_failed';
+    if (phase === 'validate')
+        return 'download_invalid';
+    if (phase === 'replace')
+        return mutationCode ?? 'replace_failed';
+    if (phase === 'verify')
+        return 'verification_failed';
+    return 'release_lookup_failed';
+};
+const asOperationError = (code, error) => error instanceof UpgradeOperationError ? error : new UpgradeOperationError(code, errorMessage(error));
+const resolveSelfExecutable = () => process.env['RUNX_SELF_PATH'] ?? process.execPath;
+const errorMessage = (error) => error instanceof Error ? error.message : String(error);

package/library/storage.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @copyright Copyright © 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ */
+export { copyTextFile, ensureDirectory, globalRunXDirectory, movePath, pathExists, readTextIfExists, removePath, writeTextFile, };
+declare function globalRunXDirectory(): string;
+declare function pathExists(path: string): Promise<boolean>;
+declare function ensureDirectory(path: string): Promise<void>;
+declare function removePath(path: string): Promise<void>;
+declare function movePath(from: string, to: string): Promise<void>;
+declare function readTextIfExists(path: string): Promise<string | null>;
+declare function writeTextFile(path: string, value: string): Promise<void>;
+declare function copyTextFile(source: string, target: string): Promise<void>;
+//# sourceMappingURL=storage.d.ts.map

package/library/storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../source/storage.ts"],"names":[],"mappings":"AAAA;;GAEG;AAKH,OAAO,EACL,YAAY,EACZ,eAAe,EACf,mBAAmB,EACnB,QAAQ,EACR,UAAU,EACV,gBAAgB,EAChB,UAAU,EACV,aAAa,GACd,CAAA;AAED,iBAAS,mBAAmB,IAAI,MAAM,CAErC;AAED,iBAAe,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAExD;AAED,iBAAe,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE1D;AAED,iBAAe,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAErD;AAED,iBAAe,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAQ/D;AAED,iBAAe,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAEpE;AAED,iBAAe,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAGvE;AAED,iBAAe,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEzE"}

package/library/storage.js

@@ -0,0 +1,38 @@
+/**
+ * @copyright Copyright © 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ */
+import { $ } from 'bun';
+import { directoryName, homeDirectory, joinPath } from './path-utils.js';
+export { copyTextFile, ensureDirectory, globalRunXDirectory, movePath, pathExists, readTextIfExists, removePath, writeTextFile, };
+function globalRunXDirectory() {
+    return joinPath(homeDirectory(), '.guiho', 'runx');
+}
+async function pathExists(path) {
+    return Bun.file(path).exists();
+}
+async function ensureDirectory(path) {
+    await $ `mkdir -p ${path}`.quiet();
+}
+async function removePath(path) {
+    await $ `rm -rf ${path}`.quiet();
+}
+async function movePath(from, to) {
+    if (process.platform === 'win32') {
+        const child = Bun.spawn(['cmd.exe', '/d', '/s', '/c', 'move', '/y', from, to], { stdout: 'ignore', stderr: 'pipe' });
+        const [code, error] = await Promise.all([child.exited, new Response(child.stderr).text()]);
+        if (code !== 0)
+            throw new Error(error.trim() || `Could not move ${from} to ${to}.`);
+        return;
+    }
+    await $ `mv ${from} ${to}`.quiet();
+}
+async function readTextIfExists(path) {
+    return await pathExists(path) ? Bun.file(path).text() : null;
+}
+async function writeTextFile(path, value) {
+    await ensureDirectory(directoryName(path));
+    await Bun.write(path, value);
+}
+async function copyTextFile(source, target) {
+    await writeTextFile(target, await Bun.file(source).text());
+}

package/library/types.d.ts

@@ -1,31 +1,26 @@
-import type { Static } from '@sinclair/typebox';
-import type { CommandSchema, ManifestSchema } from './manifest.js';
-export type RunXManifest = Static<typeof ManifestSchema>;
-export type RunXCommand = Static<typeof CommandSchema>;
-export type ResolvedCommand = RunXCommand & {
+/**
+ * @copyright Copyright © 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ */
+import type { RunXCommand, RunXManifest } from './configuration.js';
+export type { AgentScope, CliOptions, OutputFormat, ResolvedCommand, RunXCommand, RunXManifest, UpdateResult, };
+type ResolvedCommand = RunXCommand & {
     index: number;
     selector: string;
     manifestPath: string;
     cwd: string;
 };
-export type OutputFormat = 'text' | 'json';
-export type CliOptions = {
+type OutputFormat = 'text' | 'json';
+type CliOptions = {
     cwd: string;
-    file?: string;
+    config?: string;
     format: OutputFormat;
     verbose: boolean;
 };
-export type AgentTool = 'agents' | 'claude' | 'all';
-export type AgentScope = 'local' | 'global';
-export type UpdateResult = {
+type AgentScope = 'local' | 'global';
+type UpdateResult = {
     currentVersion: string;
     latestVersion: string;
     updateAvailable: boolean;
     url?: string;
 };
-export type RunXUpgradeResult = UpdateResult & {
-    executablePath: string;
-    scheduled: boolean;
-    upToDate: boolean;
-};
 //# sourceMappingURL=types.d.ts.map

package/library/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../source/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAA;AAC/C,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA;AAElE,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,OAAO,cAAc,CAAC,CAAA;AACxD,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,OAAO,aAAa,CAAC,CAAA;AAEtD,MAAM,MAAM,eAAe,GAAG,WAAW,GAAG;IAC1C,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,MAAM,CAAA;IAChB,YAAY,EAAE,MAAM,CAAA;IACpB,GAAG,EAAE,MAAM,CAAA;CACZ,CAAA;AAED,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,MAAM,CAAA;AAE1C,MAAM,MAAM,UAAU,GAAG;IACvB,GAAG,EAAE,MAAM,CAAA;IACX,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,YAAY,CAAA;IACpB,OAAO,EAAE,OAAO,CAAA;CACjB,CAAA;AAED,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,KAAK,CAAA;AAEnD,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,QAAQ,CAAA;AAE3C,MAAM,MAAM,YAAY,GAAG;IACzB,cAAc,EAAE,MAAM,CAAA;IACtB,aAAa,EAAE,MAAM,CAAA;IACrB,eAAe,EAAE,OAAO,CAAA;IACxB,GAAG,CAAC,EAAE,MAAM,CAAA;CACb,CAAA;AAED,MAAM,MAAM,iBAAiB,GAAG,YAAY,GAAG;IAC7C,cAAc,EAAE,MAAM,CAAA;IACtB,SAAS,EAAE,OAAO,CAAA;IAClB,QAAQ,EAAE,OAAO,CAAA;CAClB,CAAA"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../source/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAEnE,YAAY,EACV,UAAU,EACV,UAAU,EACV,YAAY,EACZ,eAAe,EACf,WAAW,EACX,YAAY,EACZ,YAAY,GACb,CAAA;AAED,KAAK,eAAe,GAAG,WAAW,GAAG;IACnC,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,MAAM,CAAA;IAChB,YAAY,EAAE,MAAM,CAAA;IACpB,GAAG,EAAE,MAAM,CAAA;CACZ,CAAA;AAED,KAAK,YAAY,GAAG,MAAM,GAAG,MAAM,CAAA;AAEnC,KAAK,UAAU,GAAG;IAChB,GAAG,EAAE,MAAM,CAAA;IACX,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,YAAY,CAAA;IACpB,OAAO,EAAE,OAAO,CAAA;CACjB,CAAA;AAED,KAAK,UAAU,GAAG,OAAO,GAAG,QAAQ,CAAA;AAEpC,KAAK,YAAY,GAAG;IAClB,cAAc,EAAE,MAAM,CAAA;IACtB,aAAa,EAAE,MAAM,CAAA;IACrB,eAAe,EAAE,OAAO,CAAA;IACxB,GAAG,CAAC,EAAE,MAAM,CAAA;CACb,CAAA"}

package/library/types.js

@@ -0,0 +1,3 @@
+/**
+ * @copyright Copyright © 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ */

package/library/update-cache.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @copyright Copyright © 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ */
+import type { Static } from '@sinclair/typebox';
+export { cacheSchema, readCachedUpdateNotice, runUpdateWorker, spawnUpdateWorker, updateCachePath, };
+export type { UpdateCache, };
+declare const cacheSchema: import("@sinclair/typebox").TObject<{
+    newVersionAvailable: import("@sinclair/typebox").TBoolean;
+    latestVersion: import("@sinclair/typebox").TString;
+    upgradeCommand: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    lastCheck: import("@sinclair/typebox").TString;
+}>;
+type UpdateCache = Static<typeof cacheSchema>;
+declare function updateCachePath(): string;
+declare function readCachedUpdateNotice(verbose?: boolean): Promise<string | null>;
+declare function spawnUpdateWorker(): void;
+declare function runUpdateWorker(options?: {
+    fetchImpl?: typeof fetch;
+    now?: () => Date;
+}): Promise<UpdateCache>;
+//# sourceMappingURL=update-cache.d.ts.map

package/library/update-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-cache.d.ts","sourceRoot":"","sources":["../source/update-cache.ts"],"names":[],"mappings":"AAAA;;GAEG;AAUH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAA;AAE/C,OAAO,EACL,WAAW,EACX,sBAAsB,EACtB,eAAe,EACf,iBAAiB,EACjB,eAAe,GAChB,CAAA;AACD,YAAY,EACV,WAAW,GACZ,CAAA;AAED,QAAA,MAAM,WAAW;;;;;EAKkB,CAAA;AAEnC,KAAK,WAAW,GAAG,MAAM,CAAC,OAAO,WAAW,CAAC,CAAA;AAE7C,iBAAS,eAAe,IAAI,MAAM,CAEjC;AAED,iBAAe,sBAAsB,CAAC,OAAO,UAAQ,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAY7E;AAED,iBAAS,iBAAiB,IAAI,IAAI,CAYjC;AAED,iBAAe,eAAe,CAAC,OAAO,GAAE;IAAE,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,IAAI,CAAA;CAAO,GAAG,OAAO,CAAC,WAAW,CAAC,CAiBjH"}

package/library/update-cache.js

@@ -0,0 +1,68 @@
+/**
+ * @copyright Copyright © 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ */
+import { Type } from '@sinclair/typebox';
+import { Value } from '@sinclair/typebox/value';
+import { gt, valid } from 'semver';
+import { readVersion } from './help.js';
+import { fetchReleaseCatalog, resolveUpgradePlatform } from './release-catalog.js';
+import { globalRunXDirectory, movePath, readTextIfExists, writeTextFile } from './storage.js';
+import { joinPath } from './path-utils.js';
+export { cacheSchema, readCachedUpdateNotice, runUpdateWorker, spawnUpdateWorker, updateCachePath, };
+const cacheSchema = Type.Object({
+    newVersionAvailable: Type.Boolean(),
+    latestVersion: Type.String(),
+    upgradeCommand: Type.Optional(Type.String()),
+    lastCheck: Type.String(),
+}, { additionalProperties: false });
+function updateCachePath() {
+    return joinPath(globalRunXDirectory(), 'cache.json');
+}
+async function readCachedUpdateNotice(verbose = false) {
+    const raw = await readTextIfExists(updateCachePath());
+    if (raw === null)
+        return null;
+    try {
+        const cache = Value.Decode(cacheSchema, JSON.parse(raw));
+        return cache.newVersionAvailable
+            ? 'New version available. Run this command to upgrade: runx upgrade'
+            : null;
+    }
+    catch (error) {
+        if (verbose)
+            process.stderr.write(`warning: ignored invalid RunX update cache: ${error instanceof Error ? error.message : String(error)}\n`);
+        return null;
+    }
+}
+function spawnUpdateWorker() {
+    if (Bun.env.RUNX_DISABLE_UPDATE_WORKER === '1')
+        return;
+    const command = process.execPath.toLowerCase().includes('bun')
+        ? [process.execPath, Bun.main, '--check-updates-worker']
+        : [process.execPath, '--check-updates-worker'];
+    Bun.spawn(command, {
+        detached: true,
+        stdout: 'ignore',
+        stderr: 'ignore',
+        stdin: 'ignore',
+        env: process.env,
+    }).unref();
+}
+async function runUpdateWorker(options = {}) {
+    const currentVersion = readVersion();
+    const platform = resolveUpgradePlatform();
+    const catalog = await fetchReleaseCatalog({ ...platform, currentVersion, fetchImpl: options.fetchImpl });
+    const latestVersion = catalog.latestStableVersion ?? currentVersion;
+    const newVersionAvailable = Boolean(valid(currentVersion) && valid(latestVersion) && gt(latestVersion, currentVersion));
+    const cache = {
+        newVersionAvailable,
+        latestVersion,
+        ...(newVersionAvailable ? { upgradeCommand: 'runx upgrade' } : {}),
+        lastCheck: (options.now?.() ?? new Date()).toISOString(),
+    };
+    const path = updateCachePath();
+    const temporary = `${path}.${process.pid}.${crypto.randomUUID()}.tmp`;
+    await writeTextFile(temporary, `${JSON.stringify(cache, null, 2)}\n`);
+    await movePath(temporary, path);
+    return cache;
+}

package/library/upgrade-reporting.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @copyright Copyright © 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ */
+import type { ReleaseCatalog, UpgradeEnvelope, UpgradeEvent, UpgradePlan } from './upgrade-types.js';
+export { renderReleaseCatalog, renderUpgradeEvent, renderUpgradeHeading, renderUpgradePlan, renderUpgradeResult, };
+declare const renderUpgradeHeading: () => string;
+declare const renderUpgradePlan: (plan: UpgradePlan) => string;
+declare const renderUpgradeEvent: (event: UpgradeEvent) => string;
+declare const renderUpgradeResult: (result: UpgradeEnvelope) => string;
+declare const renderReleaseCatalog: (catalog: ReleaseCatalog) => string;
+//# sourceMappingURL=upgrade-reporting.d.ts.map