@guiho/runx 0.4.1 → 0.5.2

package/library/cli.js

@@ -4,6 +4,7 @@
 import { Type } from '@sinclair/typebox';
 import { Value } from '@sinclair/typebox/value';
 import { defineCommand, renderUsage, runCommand as runCittyCommand } from 'citty';
+import { agentMaintenanceWorkerCwd, runAgentMaintenanceWorker, spawnAgentMaintenanceWorker } from './agent-maintenance.js';
 import { applyAgentInstructions, installAgentSkill, listAgentPrompts, listAgentSkills, removeAgentInstructions, showAgentInstructions, showAgentPrompt, showAgentSkill, uninstallAgentSkill, updateAgentInstructions, updateAgentSkill, } from './agents.js';
 import { RunXError } from './errors.js';
 import { runCommand } from './executor.js';
@@ -12,11 +13,11 @@ import { initializeRunXManifest } from './init.js';
 import { readManifest, resolveCommand } from './manifest.js';
 import { resolvePath } from './path-utils.js';
 import { renderDescription, renderExecutionPlan, renderJson, renderList } from './render.js';
-import { fetchReleaseCatalog, resolveUpgradePlatform } from './release-catalog.js';
+import { fetchReleaseCatalog, paginateReleaseCatalog, resolveUpgradePlatform } from './release-catalog.js';
 import { checkForLatestVersion, uninstallSelf, upgradeSelf } from './self-management.js';
 import { readCachedUpdateNotice, runUpdateWorker, spawnUpdateWorker } from './update-cache.js';
 import { renderReleaseCatalog, renderUpgradeEvent, renderUpgradeHeading, renderUpgradePlan, renderUpgradeResult } from './upgrade-reporting.js';
-export { runCli, runCliWithErrorHandling, runxCommand, };
+export { renderStartupBanner, runCli, runCliWithErrorHandling, runxCommand, };
 class CliHandled extends Error {
 }
 class CliUsageError extends Error {
@@ -31,6 +32,14 @@ const formatSchema = Type.Union([Type.Literal('text'), Type.Literal('json')]);
 const archSchema = Type.Union([Type.Literal('x64'), Type.Literal('arm64')]);
 const variantSchema = Type.Union([Type.Literal('baseline'), Type.Literal('default'), Type.Literal('modern')]);
 const positiveIntegerSchema = Type.Integer({ minimum: 1 });
+const platformLabels = {
+    darwin: 'macOS',
+    linux: 'Linux',
+    win32: 'Windows',
+};
+function renderStartupBanner(platform = process.platform, version = readVersion()) {
+    return `Hello ${platformLabels[platform] ?? platform} - runx v${version}\n`;
+}
 const helpArgs = {
     help: { type: 'boolean', alias: 'h', description: 'Show command help.' },
     'help-tree': { type: 'boolean', description: 'Show this command hierarchy.' },
@@ -135,7 +144,7 @@ function createCommandTree() {
     const upgradeList = leaf('runx upgrade list', 'List RunX releases newest first.', {
         page: { type: 'string', valueHint: 'positive-integer', description: 'Select result page.' },
         'per-page': { type: 'string', valueHint: 'positive-integer', description: 'Select page size.' },
-        'pre-releases': { type: 'boolean', description: 'Include prerelease versions.' },
+        'pre-releases': { type: 'boolean', description: 'Accepted explicitly; prereleases are always included.' },
         arch: { type: 'string', valueHint: 'x64|arm64', description: 'Select target architecture.' },
         variant: { type: 'string', valueHint: 'baseline|default|modern', description: 'Select x64 variant.' },
         format: catalogArgs.format,
@@ -145,7 +154,11 @@ function createCommandTree() {
         args: { ...upgradeArgs, ...helpArgs },
         subCommands: { check: upgradeCheck, list: upgradeList },
         setup: helpSetup(state),
-        run: async () => runUpgrade(options(state.args), state.args),
+        run: async () => {
+            if (state.command === upgradeCheck || state.command === upgradeList)
+                return;
+            await runUpgrade(options(state.args), state.args);
+        },
     });
     state.commands.set('upgrade', upgrade);
     const uninstall = leaf('runx uninstall', 'Uninstall the native RunX executable.', {
@@ -169,7 +182,7 @@ function createCommandTree() {
         },
         run: ({ args }) => {
             if (args._.length === 0)
-                write(`Hello Windows - runx v${readVersion()}\n`);
+                write(renderStartupBanner());
         },
     });
     state.commands.set('', root);
@@ -229,6 +242,11 @@ async function runCli(rawArgs = process.argv.slice(2)) {
         await runUpdateWorker();
         return;
     }
+    const maintenanceWorkerCwd = agentMaintenanceWorkerCwd(rawArgs);
+    if (maintenanceWorkerCwd !== null) {
+        await runAgentMaintenanceWorker(maintenanceWorkerCwd);
+        return;
+    }
     const { command, state } = createCommandTree();
     const cleanOutput = rawArgs.some((arg) => ['-h', '--help', '-v', '--version', '--help-tree', '--help-docs'].includes(arg) || arg.startsWith('--help-tree-depth'));
     if (!cleanOutput) {
@@ -253,6 +271,14 @@ async function runCli(rawArgs = process.argv.slice(2)) {
             throw new CliUsageError(error.message, await renderUsage(state.command));
         throw error;
     }
+    finally {
+        if (shouldScheduleAgentMaintenance(rawArgs)) {
+            spawnAgentMaintenanceWorker(resolvePath(state.args.cwd ?? process.cwd()));
+        }
+    }
+}
+function shouldScheduleAgentMaintenance(rawArgs) {
+    return !['agent', 'uninstall'].includes(rawArgs[0] ?? '');
 }
 async function runCliWithErrorHandling(rawArgs) {
     try {
@@ -335,11 +361,10 @@ async function runUpgradeList(args) {
     const requestedArch = args.arch ? decode(archSchema, args.arch, '--arch') : process.arch;
     const platform = resolveUpgradePlatform(process.platform, requestedArch);
     const variant = decode(variantSchema, args.variant ?? 'baseline', '--variant');
-    const page = positiveInteger(args.page ?? '1', '--page');
-    const perPage = positiveInteger(args.perPage ?? '20', '--per-page');
+    const page = args.page ? positiveInteger(args.page, '--page') : undefined;
+    const perPage = args.perPage ? positiveInteger(args.perPage, '--per-page') : undefined;
     const catalog = await fetchReleaseCatalog({ ...platform, variant, currentVersion: readVersion() });
-    const filtered = args.preReleases ? catalog.releases : catalog.releases.filter((release) => !release.prerelease);
-    const paged = { ...catalog, releases: filtered.slice((page - 1) * perPage, page * perPage) };
+    const paged = paginateReleaseCatalog(catalog, page, perPage);
     write(options(args).format === 'json' ? renderJson(paged) : renderReleaseCatalog(paged));
 }
 async function runUpgrade(optionsValue, args) {

package/library/recovery.js

@@ -15,7 +15,7 @@ const createRecoveryInstructions = (targetVersion, os, targetSource = 'resolved'
     return {
         targetVersion,
         targetSource,
-        installCommand: `curl -fsSL ${installerBaseUrl}/install.sh | sh -s -- --version '${escapeShell(targetVersion)}'`,
+        installCommand: `curl -fsSL ${installerBaseUrl}/install.sh | bash -s -- --version '${escapeShell(targetVersion)}'`,
         stopProcessCommand: 'pkill -x runx',
     };
 };

package/library/release-catalog.d.ts

@@ -2,7 +2,7 @@
  * @copyright Copyright © 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
  */
 import type { ReleaseAsset, ReleaseCatalog, UpgradeArch, UpgradeOs, UpgradeVariant } from './upgrade-types.js';
-export { assetCandidates, fetchReleaseCatalog, findCompatibleAsset, normalizeReleaseVersion, resolveUpgradePlatform, };
+export { assetCandidates, fetchReleaseCatalog, findCompatibleAsset, normalizeReleaseVersion, paginateReleaseCatalog, resolveUpgradePlatform, };
 declare const githubReleaseSchema: import("@sinclair/typebox").TObject<{
     tag_name: import("@sinclair/typebox").TString;
     draft: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
@@ -29,4 +29,5 @@ declare const findCompatibleAsset: (release: GitHubRelease, platform: ReleasePla
 declare const assetCandidates: ({ os, arch, variant }: ReleasePlatform) => string[];
 declare const resolveUpgradePlatform: (platform?: NodeJS.Platform, architecture?: NodeJS.Architecture) => ReleasePlatform;
 declare const normalizeReleaseVersion: (tag: string) => string;
+declare const paginateReleaseCatalog: (catalog: ReleaseCatalog, page?: number, perPage?: number) => ReleaseCatalog;
 //# sourceMappingURL=release-catalog.d.ts.map

package/library/release-catalog.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"release-catalog.d.ts","sourceRoot":"","sources":["../source/release-catalog.ts"],"names":[],"mappings":"AAAA;;GAEG;AAMH,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAuB,WAAW,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AAEnI,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,mBAAmB,EACnB,uBAAuB,EACvB,sBAAsB,GACvB,CAAA;AAED,QAAA,MAAM,mBAAmB;;;;;;;;;;EAUS,CAAA;AAIlC,MAAM,MAAM,aAAa,GAAG,OAAO,mBAAmB,EAAE,MAAM,CAAC,OAAO,mBAAmB,CAAC,CAAA;AAE1F,MAAM,MAAM,eAAe,GAAG;IAC5B,EAAE,EAAE,SAAS,CAAA;IACb,IAAI,EAAE,WAAW,CAAA;IACjB,OAAO,EAAE,cAAc,CAAA;CACxB,CAAA;AAED,KAAK,mBAAmB,GAAG,eAAe,GAAG;IAC3C,cAAc,EAAE,MAAM,CAAA;IACtB,SAAS,CAAC,EAAE,OAAO,KAAK,CAAA;CACzB,CAAA;AAID,QAAA,MAAM,mBAAmB,YAAmB,mBAAmB,KAAG,OAAO,CAAC,cAAc,CAoCvF,CAAA;AAkBD,QAAA,MAAM,mBAAmB,YAAa,aAAa,YAAY,eAAe,KAAG,YAAY,GAAG,IAM/F,CAAA;AAED,QAAA,MAAM,eAAe,0BAA2B,eAAe,KAAG,MAAM,EAUvE,CAAA;AAED,QAAA,MAAM,sBAAsB,sEAA+D,eAM1F,CAAA;AAED,QAAA,MAAM,uBAAuB,QAAS,MAAM,KAAG,MAA6D,CAAA"}
+{"version":3,"file":"release-catalog.d.ts","sourceRoot":"","sources":["../source/release-catalog.ts"],"names":[],"mappings":"AAAA;;GAEG;AAMH,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAuB,WAAW,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AAEnI,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,mBAAmB,EACnB,uBAAuB,EACvB,sBAAsB,EACtB,sBAAsB,GACvB,CAAA;AAED,QAAA,MAAM,mBAAmB;;;;;;;;;;EAUS,CAAA;AAIlC,MAAM,MAAM,aAAa,GAAG,OAAO,mBAAmB,EAAE,MAAM,CAAC,OAAO,mBAAmB,CAAC,CAAA;AAE1F,MAAM,MAAM,eAAe,GAAG;IAC5B,EAAE,EAAE,SAAS,CAAA;IACb,IAAI,EAAE,WAAW,CAAA;IACjB,OAAO,EAAE,cAAc,CAAA;CACxB,CAAA;AAED,KAAK,mBAAmB,GAAG,eAAe,GAAG;IAC3C,cAAc,EAAE,MAAM,CAAA;IACtB,SAAS,CAAC,EAAE,OAAO,KAAK,CAAA;CACzB,CAAA;AAID,QAAA,MAAM,mBAAmB,YAAmB,mBAAmB,KAAG,OAAO,CAAC,cAAc,CAoCvF,CAAA;AAkBD,QAAA,MAAM,mBAAmB,YAAa,aAAa,YAAY,eAAe,KAAG,YAAY,GAAG,IAM/F,CAAA;AAED,QAAA,MAAM,eAAe,0BAA2B,eAAe,KAAG,MAAM,EAUvE,CAAA;AAED,QAAA,MAAM,sBAAsB,sEAA+D,eAM1F,CAAA;AAED,QAAA,MAAM,uBAAuB,QAAS,MAAM,KAAG,MAA6D,CAAA;AAE5G,QAAA,MAAM,sBAAsB,YAAa,cAAc,SAAS,MAAM,YAAY,MAAM,KAAG,cAM1F,CAAA"}

package/library/release-catalog.js

@@ -5,7 +5,7 @@ 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, };
+export { assetCandidates, fetchReleaseCatalog, findCompatibleAsset, normalizeReleaseVersion, paginateReleaseCatalog, resolveUpgradePlatform, };
 const githubReleaseSchema = Type.Object({
     tag_name: Type.String(),
     draft: Type.Optional(Type.Boolean()),
@@ -100,6 +100,14 @@ const resolveUpgradePlatform = (platform = process.platform, architecture = proc
     return { os, arch, variant: 'baseline' };
 };
 const normalizeReleaseVersion = (tag) => tag.replace(/^@guiho\/runx@/, '').replace(/^v/, '');
+const paginateReleaseCatalog = (catalog, page, perPage) => {
+    if (page === undefined && perPage === undefined)
+        return catalog;
+    const selectedPage = page ?? 1;
+    const selectedPageSize = perPage ?? 20;
+    const start = (selectedPage - 1) * selectedPageSize;
+    return { ...catalog, releases: catalog.releases.slice(start, start + selectedPageSize) };
+};
 const releaseChannel = (version, prerelease) => {
     const parsed = parse(version);
     if (!parsed)

package/library/storage.d.ts

@@ -1,7 +1,7 @@
 /**
  * @copyright Copyright © 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
  */
-export { copyTextFile, ensureDirectory, globalRunXDirectory, movePath, pathExists, readTextIfExists, removePath, writeTextFile, };
+export { copyTextFile, ensureDirectory, globalRunXDirectory, movePath, pathExists, readTextIfExists, removePath, writeTextFile, writeTextFileAtomic, };
 declare function globalRunXDirectory(): string;
 declare function pathExists(path: string): Promise<boolean>;
 declare function ensureDirectory(path: string): Promise<void>;
@@ -9,5 +9,6 @@ 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 writeTextFileAtomic(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

@@ -1 +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"}
+{"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,EACb,mBAAmB,GACpB,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,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAU7E;AAED,iBAAe,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEzE"}

package/library/storage.js

@@ -3,7 +3,7 @@
  */
 import { $ } from 'bun';
 import { directoryName, homeDirectory, joinPath } from './path-utils.js';
-export { copyTextFile, ensureDirectory, globalRunXDirectory, movePath, pathExists, readTextIfExists, removePath, writeTextFile, };
+export { copyTextFile, ensureDirectory, globalRunXDirectory, movePath, pathExists, readTextIfExists, removePath, writeTextFile, writeTextFileAtomic, };
 function globalRunXDirectory() {
     return joinPath(homeDirectory(), '.guiho', 'runx');
 }
@@ -33,6 +33,18 @@ async function writeTextFile(path, value) {
     await ensureDirectory(directoryName(path));
     await Bun.write(path, value);
 }
+async function writeTextFileAtomic(path, value) {
+    await ensureDirectory(directoryName(path));
+    const temporary = `${path}.${process.pid}.${crypto.randomUUID()}.tmp`;
+    try {
+        await Bun.write(temporary, value);
+        await movePath(temporary, path);
+    }
+    catch (error) {
+        await removePath(temporary);
+        throw error;
+    }
+}
 async function copyTextFile(source, target) {
     await writeTextFile(target, await Bun.file(source).text());
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@guiho/runx",
   "description": "A language-agnostic, documented command catalog and local CLI executor.",
-  "version": "0.4.1",
+  "version": "0.5.2",
   "type": "module",
   "main": "./library/guiho-runx.js",
   "types": "./library/guiho-runx.d.ts",

package/skills/guiho-s-runx/SKILL.md

@@ -76,3 +76,14 @@ runx upgrade --dry-run
 
 Use `--help`, `--help-tree`, or `--help-docs` at any command scope for the
 current executable contract.
+
+## Automatic Agent Maintenance
+
+Ordinary RunX commands schedule a silent, non-blocking worker that keeps the
+bundled skill current in both global agent-tool directories and reconciles one
+compact managed block in the nearest `AGENTS.md`. A current installation is not
+rewritten. Automatic failures never fail or pollute the foreground command.
+
+Explicit `runx agent ...` commands remain the manual repair and local-scope
+interface. Explicit agent-resource removal and `runx uninstall` do not schedule
+automatic reinstallation.

package/skills/guiho-s-runx/guiho-s-runx.xdocs.md

@@ -1,6 +1,6 @@
 ---
 subject: guiho-s-runx
-description: Agent workflow for safe RunX catalog execution and verified native upgrade/list/recovery operations.
+description: Agent workflow for safe RunX catalog work, automatic resource maintenance, and verified native upgrade/list/recovery operations.
 parent: runx-skills
 children: []
 files:
@@ -17,6 +17,7 @@ keywords:
   - dry run
   - runx upgrade
   - recovery install
+  - automatic maintenance
 flags: []
 status: stable
 ---
@@ -24,3 +25,5 @@ status: stable
 The skill makes manifest inspection, UID selection, dry runs, and explicit
 confirmation the default agent workflow for RunX commands and teaches agents
 how to interpret transactional native upgrades and their recovery contract.
+Ordinary RunX invocations also reconcile the current global skill and nearest
+managed project instruction block through a silent detached worker.