@guiho/runx 0.2.7 → 0.4.1

package/library/agents.js

@@ -1,51 +1,153 @@
-import { mkdir, readFile, writeFile } from 'node:fs/promises';
-import { homedir } from 'node:os';
-import { dirname, join } from 'node:path';
+/**
+ * @copyright Copyright © 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ */
 import { RunXError } from './errors.js';
-const managedStart = '<!-- BEGIN RUNX AGENT INSTRUCTIONS -->';
-const managedEnd = '<!-- END RUNX AGENT INSTRUCTIONS -->';
-export const installAgentSkill = async (scope, tool, cwd) => {
-    const root = scope === 'global' ? homedir() : cwd;
+import { homeDirectory, joinPath, resolvePath } from './path-utils.js';
+import { ensureDirectory, pathExists, readTextIfExists, removePath, writeTextFile } from './storage.js';
+export { applyAgentInstructions, installAgentSkill, listAgentPrompts, listAgentSkills, removeAgentInstructions, showAgentInstructions, showAgentPrompt, showAgentSkill, uninstallAgentSkill, updateAgentInstructions, updateAgentSkill, };
+const skillId = 'guiho-s-runx';
+const promptId = 'guiho-i-runx';
+const managedStart = '<!-- BEGIN RUNX — DO NOT EDIT THIS SECTION -->';
+const managedEnd = '<!-- END RUNX -->';
+async function installAgentSkill(scope, cwd) {
+    return writeSkillTargets(scope, cwd);
+}
+async function updateAgentSkill(scope, cwd) {
+    return writeSkillTargets(scope, cwd);
+}
+async function uninstallAgentSkill(scope, cwd) {
+    const targets = skillDirectories(scope, cwd);
+    for (const target of targets)
+        await removePath(target);
+    return targets;
+}
+function listAgentSkills(filter) {
+    const skills = [{ id: skillId, description: 'Inspect, validate, describe, and safely execute RunX command catalogs.' }];
+    const keyword = filter?.trim().toLowerCase();
+    return keyword ? skills.filter((skill) => `${skill.id} ${skill.description}`.toLowerCase().includes(keyword)) : skills;
+}
+async function showAgentSkill(id) {
+    if (id !== skillId)
+        throw new RunXError(`Unknown RunX skill: ${id}`, 2);
+    return {
+        id,
+        path: `skills/${skillId}/SKILL.md`,
+        description: listAgentSkills()[0].description,
+        metadata: { version: '0.1.0', package: '@guiho/runx' },
+    };
+}
+async function applyAgentInstructions(cwd) {
+    return reconcileInstructions(cwd, 'apply');
+}
+async function updateAgentInstructions(cwd) {
+    return reconcileInstructions(cwd, 'update');
+}
+async function removeAgentInstructions(cwd) {
+    const changed = [];
+    for (const path of await instructionTargets(cwd)) {
+        const existing = await readTextIfExists(path);
+        if (existing === null)
+            continue;
+        const next = removeManagedBlock(existing);
+        if (next !== existing) {
+            await writeTextFile(path, next);
+            changed.push(path);
+        }
+    }
+    return changed;
+}
+async function showAgentInstructions() {
+    return instructionBlock();
+}
+function listAgentPrompts(namesOnly = false) {
+    return namesOnly
+        ? [promptId]
+        : [{ id: promptId, description: 'Guide an agent through safe RunX catalog inspection and execution.' }];
+}
+async function showAgentPrompt(id) {
+    if (id !== promptId)
+        throw new RunXError(`Unknown RunX prompt: ${id}`, 2);
+    return readBundledPrompt();
+}
+async function writeSkillTargets(scope, cwd) {
     const skill = await readBundledSkill();
-    const targets = tool === 'all' ? ['agents', 'claude'] : [tool];
     const installed = [];
-    for (const target of targets) {
-        const directory = target === 'agents'
-            ? join(root, '.agents', 'skills', 'guiho-s-runx')
-            : join(root, '.claude', 'skills', 'guiho-s-runx');
-        const path = join(directory, 'SKILL.md');
-        await mkdir(directory, { recursive: true });
-        await writeFile(path, skill, 'utf8');
+    for (const directory of skillDirectories(scope, cwd)) {
+        const path = joinPath(directory, 'SKILL.md');
+        await ensureDirectory(directory);
+        await writeTextFile(path, skill);
         installed.push(path);
     }
     return installed;
-};
-export const installAgentInstructions = async (cwd) => {
-    const path = join(cwd, 'AGENTS.md');
-    let existing = '';
-    try {
-        existing = await readFile(path, 'utf8');
-    }
-    catch (error) {
-        if (!(error instanceof Error && 'code' in error && error.code === 'ENOENT'))
-            throw error;
+}
+function skillDirectories(scope, cwd) {
+    const root = scope === 'global' ? homeDirectory() : resolvePath(cwd);
+    return [
+        joinPath(root, '.agents', 'skills', skillId),
+        joinPath(root, '.claude', 'skills', skillId),
+    ];
+}
+async function instructionTargets(cwd) {
+    const root = resolvePath(cwd);
+    const agents = joinPath(root, 'AGENTS.md');
+    const claude = joinPath(root, 'CLAUDE.md');
+    const agentsExists = await pathExists(agents);
+    const claudeExists = await pathExists(claude);
+    if (agentsExists && claudeExists)
+        return [agents, claude];
+    if (claudeExists)
+        return [claude];
+    return [agents];
+}
+async function reconcileInstructions(cwd, _action) {
+    const changed = [];
+    for (const path of await instructionTargets(cwd)) {
+        const existing = await readTextIfExists(path) ?? '';
+        const next = replaceManagedBlock(existing, instructionBlock());
+        if (next !== existing) {
+            await writeTextFile(path, next);
+            changed.push(path);
+        }
     }
-    const section = `${managedStart}\n## RunX Command Catalog\n\nUse the bundled \`guiho-s-runx\` skill whenever working with \`runx.yaml\` manifests. Inspect with \`runx check --format json\` and \`runx list --format json\` before selecting a command. Use a UID for automation and require explicit developer approval before \`--yes\` on confirmation-gated commands.\n${managedEnd}`;
-    const pattern = new RegExp(`${escapeRegExp(managedStart)}[\\s\\S]*?${escapeRegExp(managedEnd)}`, 'g');
-    const next = pattern.test(existing) ? existing.replace(pattern, section) : `${existing.trimEnd()}${existing.trim() ? '\n\n' : ''}${section}\n`;
-    await mkdir(dirname(path), { recursive: true });
-    await writeFile(path, next, 'utf8');
-    return path;
-};
-const readBundledSkill = async () => {
+    return changed;
+}
+function instructionBlock() {
+    return `${managedStart}
+## RunX Command Catalog
+
+Load the \`guiho-s-runx\` skill before working with \`runx.yaml\`. Inspect with
+\`runx check --format json\` and \`runx list --format json\`, select stable UIDs,
+use \`runx run <uid> --dry-run\` before unfamiliar work, and add \`--yes\` only
+after explicit approval for a confirmation-gated command.
+${managedEnd}
+`;
+}
+function replaceManagedBlock(existing, block) {
+    const pattern = new RegExp(`${escapeRegExp(managedStart)}[\\s\\S]*?${escapeRegExp(managedEnd)}\\s*`, 'g');
+    const stripped = existing.replace(pattern, '').trimEnd();
+    return `${stripped}${stripped ? '\n\n' : ''}${block}`;
+}
+function removeManagedBlock(existing) {
+    const pattern = new RegExp(`\\s*${escapeRegExp(managedStart)}[\\s\\S]*?${escapeRegExp(managedEnd)}\\s*`, 'g');
+    const next = existing.replace(pattern, '\n').trimEnd();
+    return next ? `${next}\n` : '';
+}
+async function readBundledSkill() {
     if (globalThis.__RUNX_EMBEDDED_RESOURCES__?.skill)
         return globalThis.__RUNX_EMBEDDED_RESOURCES__.skill;
     const path = new URL('../skills/guiho-s-runx/SKILL.md', import.meta.url);
-    try {
-        return await Bun.file(path).text();
-    }
-    catch {
-        throw new RunXError('Bundled guiho-s-runx skill is unavailable. Reinstall RunX from an official release.');
-    }
-};
-const escapeRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    if (!(await Bun.file(path).exists()))
+        throw new RunXError('Bundled guiho-s-runx skill is unavailable.', 5);
+    return Bun.file(path).text();
+}
+async function readBundledPrompt() {
+    if (globalThis.__RUNX_EMBEDDED_RESOURCES__?.prompt)
+        return globalThis.__RUNX_EMBEDDED_RESOURCES__.prompt;
+    const path = new URL('../prompts/guiho-i-runx.md', import.meta.url);
+    if (!(await Bun.file(path).exists()))
+        throw new RunXError('Bundled guiho-i-runx prompt is unavailable.', 5);
+    return Bun.file(path).text();
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/library/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../source/cli.ts"],"names":[],"mappings":"AAAA;;GAEG;AAaH,OAAO,KAAK,EAAkB,UAAU,EAAkB,MAAM,OAAO,CAAA;AAGvE,OAAO,EACL,MAAM,EACN,uBAAuB,EACvB,WAAW,GACZ,CAAA;AA8PD,QAAA,MAAiB,WAAW,iBAAwB,CAAA;AAEpD,iBAAe,MAAM,CAAC,OAAO,GAAE,MAAM,EAA0B,GAAG,OAAO,CAAC,IAAI,CAAC,CAY9E;AAED,iBAAe,uBAAuB,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAiBxE"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../source/cli.ts"],"names":[],"mappings":"AAAA;;GAEG;AA8BH,OAAO,KAAK,EAAkB,UAAU,EAAkB,MAAM,OAAO,CAAA;AAIvE,OAAO,EACL,MAAM,EACN,uBAAuB,EACvB,WAAW,GACZ,CAAA;AAsPD,QAAA,MAAiB,WAAW,iBAAwB,CAAA;AAEpD,iBAAe,MAAM,CAAC,OAAO,GAAE,MAAM,EAA0B,GAAG,OAAO,CAAC,IAAI,CAAC,CAuB9E;AAED,iBAAe,uBAAuB,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAexE"}