@guiho/runx 0.2.7 → 0.4.0

package/library/release-catalog.js

@@ -0,0 +1,124 @@
+/**
+ * @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 { compare, parse, valid } from 'semver';
+import { RunXError } from './errors.js';
+export { assetCandidates, fetchReleaseCatalog, findCompatibleAsset, normalizeReleaseVersion, resolveUpgradePlatform, };
+const githubReleaseSchema = Type.Object({
+    tag_name: Type.String(),
+    draft: Type.Optional(Type.Boolean()),
+    prerelease: Type.Optional(Type.Boolean()),
+    published_at: Type.Optional(Type.Union([Type.String(), Type.Null()])),
+    created_at: Type.Optional(Type.Union([Type.String(), Type.Null()])),
+    assets: Type.Array(Type.Object({
+        name: Type.String(),
+        browser_download_url: Type.String(),
+    }, { additionalProperties: true })),
+}, { additionalProperties: true });
+const githubReleasesSchema = Type.Array(githubReleaseSchema);
+const repositoryApi = 'https://api.github.com/repos/CGuiho/runx/releases';
+const fetchReleaseCatalog = async (options) => {
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const releases = [];
+    let page = 1;
+    let next = true;
+    while (next) {
+        const response = await fetchImpl(`${repositoryApi}?per_page=100&page=${page}`, {
+            headers: { accept: 'application/vnd.github+json' },
+        });
+        if (!response.ok)
+            throw new RunXError(`Could not retrieve RunX releases page ${page}: HTTP ${response.status}`, 4);
+        const payload = await response.json();
+        let pageReleases;
+        try {
+            pageReleases = Value.Decode(githubReleasesSchema, payload);
+        }
+        catch {
+            throw new RunXError(`Could not retrieve RunX releases page ${page}: malformed release`, 4);
+        }
+        releases.push(...pageReleases.filter((release) => !release.draft));
+        next = hasNextPage(response.headers.get('link'));
+        page += 1;
+    }
+    const normalized = releases.map((release) => normalizeRelease(release, options));
+    normalized.sort(compareCatalogEntries);
+    const latestStableVersion = normalized.find((entry) => valid(entry.version) && !entry.prerelease)?.version ?? null;
+    for (const entry of normalized)
+        entry.latestStable = entry.version === latestStableVersion;
+    return {
+        schemaVersion: 1,
+        command: 'runx upgrade list',
+        currentVersion: options.currentVersion,
+        latestStableVersion,
+        releases: normalized,
+    };
+};
+const normalizeRelease = (release, platform) => {
+    const version = normalizeReleaseVersion(release.tag_name);
+    const parsed = parse(version);
+    const prerelease = parsed ? parsed.prerelease.length > 0 : Boolean(release.prerelease);
+    return {
+        tag: release.tag_name,
+        version,
+        channel: releaseChannel(version, prerelease),
+        prerelease,
+        publishedAt: release.published_at ?? release.created_at ?? null,
+        current: version === platform.currentVersion,
+        latestStable: false,
+        compatibleAsset: findCompatibleAsset(release, platform),
+    };
+};
+const findCompatibleAsset = (release, platform) => {
+    for (const candidate of assetCandidates(platform)) {
+        const asset = release.assets.find((item) => item.name === candidate);
+        if (asset)
+            return { name: asset.name, url: asset.browser_download_url };
+    }
+    return null;
+};
+const assetCandidates = ({ os, arch, variant }) => {
+    const suffix = os === 'windows' ? '.exe' : '';
+    if (arch === 'arm64')
+        return [`runx-${os}-arm64${suffix}`];
+    const prefix = `runx-${os}-x64`;
+    const names = {
+        baseline: [`${prefix}-baseline${suffix}`, `${prefix}${suffix}`, `${prefix}-modern${suffix}`],
+        default: [`${prefix}${suffix}`, `${prefix}-baseline${suffix}`, `${prefix}-modern${suffix}`],
+        modern: [`${prefix}-modern${suffix}`, `${prefix}${suffix}`, `${prefix}-baseline${suffix}`],
+    };
+    return names[variant];
+};
+const resolveUpgradePlatform = (platform = process.platform, architecture = process.arch) => {
+    const os = platform === 'win32' ? 'windows' : platform === 'darwin' ? 'darwin' : platform === 'linux' ? 'linux' : null;
+    const arch = architecture === 'x64' ? 'x64' : architecture === 'arm64' ? 'arm64' : null;
+    if (!os)
+        throw new RunXError(`Self-upgrade is not supported on ${platform}.`);
+    if (!arch)
+        throw new RunXError(`Self-upgrade is not supported on architecture ${architecture}.`);
+    return { os, arch, variant: 'baseline' };
+};
+const normalizeReleaseVersion = (tag) => tag.replace(/^@guiho\/runx@/, '').replace(/^v/, '');
+const releaseChannel = (version, prerelease) => {
+    const parsed = parse(version);
+    if (!parsed)
+        return 'other';
+    if (!prerelease)
+        return 'stable';
+    const identifier = parsed.prerelease[0];
+    return typeof identifier === 'string' ? identifier : 'prerelease';
+};
+const compareCatalogEntries = (left, right) => {
+    const leftValid = valid(left.version);
+    const rightValid = valid(right.version);
+    if (leftValid && rightValid)
+        return compare(rightValid, leftValid);
+    if (leftValid)
+        return -1;
+    if (rightValid)
+        return 1;
+    return timestamp(right.publishedAt) - timestamp(left.publishedAt);
+};
+const timestamp = (value) => value ? Date.parse(value) || 0 : 0;
+const hasNextPage = (link) => Boolean(link?.split(',').some((part) => /rel="next"/.test(part)));

package/library/self-management.d.ts

@@ -1,11 +1,31 @@
-import type { RunXUpgradeResult, UpdateResult } from './types.js';
-export { checkForLatestVersion, listAvailableVersions, uninstallSelf, upgradeSelf, };
+/**
+ * @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';
+import type { UpdateResult } from './types.js';
+export { checkForLatestVersion, listAvailableVersions, uninstallSelf, upgradeSelf, validateNativeBinary };
+export type UpgradeFileOperations = {
+    rename: (from: string, to: string) => Promise<void>;
+    remove: (path: string) => Promise<void>;
+    makeExecutable: (path: string) => Promise<void>;
+};
+export type UpgradeSelfOptions = {
+    dryRun: boolean;
+    currentVersion?: string;
+    requestedVersion?: string;
+    arch?: UpgradePlan['arch'];
+    variant?: import('./upgrade-types.js').UpgradeVariant;
+    onPlan?: (plan: UpgradePlan) => void;
+    onEvent?: (event: UpgradeEvent) => void;
+    fileOperations?: UpgradeFileOperations;
+};
 declare const checkForLatestVersion: () => Promise<UpdateResult>;
-declare const listAvailableVersions: () => Promise<string[]>;
-declare const upgradeSelf: (dryRun: boolean) => Promise<RunXUpgradeResult>;
+declare const listAvailableVersions: () => Promise<ReleaseCatalog>;
+declare const upgradeSelf: (input: boolean | UpgradeSelfOptions) => Promise<UpgradeEnvelope>;
 declare const uninstallSelf: (dryRun: boolean) => Promise<{
     executablePath: string;
     scheduled: boolean;
     dryRun: boolean;
 }>;
+declare const validateNativeBinary: (bytes: Uint8Array, os: UpgradePlan['os']) => void;
 //# sourceMappingURL=self-management.d.ts.map

package/library/self-management.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"self-management.d.ts","sourceRoot":"","sources":["../source/self-management.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAEjE,OAAO,EACL,qBAAqB,EACrB,qBAAqB,EACrB,aAAa,EACb,WAAW,GACZ,CAAA;AAMD,QAAA,MAAM,qBAAqB,QAAa,OAAO,CAAC,YAAY,CAY3D,CAAA;AAED,QAAA,MAAM,qBAAqB,QAAa,OAAO,CAAC,MAAM,EAAE,CAKvD,CAAA;AAED,QAAA,MAAM,WAAW,WAAkB,OAAO,KAAG,OAAO,CAAC,iBAAiB,CAmBrE,CAAA;AAED,QAAA,MAAM,aAAa,WAAkB,OAAO,KAAG,OAAO,CAAC;IAAE,cAAc,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,OAAO,CAAA;CAAE,CAWrH,CAAA"}
+{"version":3,"file":"self-management.d.ts","sourceRoot":"","sources":["../source/self-management.ts"],"names":[],"mappings":"AAAA;;GAEG;AAUH,OAAO,KAAK,EAAE,cAAc,EAA6C,eAAe,EAAkC,YAAY,EAAgB,WAAW,EAAiB,MAAM,oBAAoB,CAAA;AAC5M,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAE9C,OAAO,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,aAAa,EAAE,WAAW,EAAE,oBAAoB,EAAE,CAAA;AAEzG,MAAM,MAAM,qBAAqB,GAAG;IAClC,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACnD,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACvC,cAAc,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CAChD,CAAA;AAED,MAAM,MAAM,kBAAkB,GAAG;IAC/B,MAAM,EAAE,OAAO,CAAA;IACf,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,IAAI,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;IAC1B,OAAO,CAAC,EAAE,OAAO,oBAAoB,EAAE,cAAc,CAAA;IACrD,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,IAAI,CAAA;IACpC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAAA;IACvC,cAAc,CAAC,EAAE,qBAAqB,CAAA;CACvC,CAAA;AAuCD,QAAA,MAAM,qBAAqB,QAAa,OAAO,CAAC,YAAY,CAS3D,CAAA;AAED,QAAA,MAAM,qBAAqB,QAAa,OAAO,CAAC,cAAc,CAG7D,CAAA;AAED,QAAA,MAAM,WAAW,UAAiB,OAAO,GAAG,kBAAkB,KAAG,OAAO,CAAC,eAAe,CA4IvF,CAAA;AAED,QAAA,MAAM,aAAa,WAAkB,OAAO,KAAG,OAAO,CAAC;IAAE,cAAc,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,OAAO,CAAA;CAAE,CAWrH,CAAA;AAkFD,QAAA,MAAM,oBAAoB,UAAW,UAAU,MAAM,WAAW,CAAC,IAAI,CAAC,KAAG,IAOxE,CAAA"}

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());
+}