diff --git a/docs/api/functions/application_SetupPlan.setupPlan.html b/docs/api/functions/application_SetupPlan.setupPlan.html index 7640ea623..74902efb3 100644 --- a/docs/api/functions/application_SetupPlan.setupPlan.html +++ b/docs/api/functions/application_SetupPlan.setupPlan.html @@ -28,7 +28,7 @@
  • providerEnvironment: SetupProviderEnvironment

    • Returns readonly SetupAction[]

    +
  • Defined in src/application/SetupPlan.ts:9
    • diff --git a/docs/api/functions/application_SetupSkill.canonicalSkillNeedsInstall.html b/docs/api/functions/application_SetupSkill.canonicalSkillNeedsInstall.html index 39337a431..9b91663d9 100644 --- a/docs/api/functions/application_SetupSkill.canonicalSkillNeedsInstall.html +++ b/docs/api/functions/application_SetupSkill.canonicalSkillNeedsInstall.html @@ -24,7 +24,7 @@
  • home: string

    • Returns Promise<boolean>

    +
  • Defined in src/application/SetupSkill.ts:34
    • diff --git a/docs/api/functions/application_SetupSkill.installCanonicalSkill.html b/docs/api/functions/application_SetupSkill.installCanonicalSkill.html index 64747cc5b..a8d1fa056 100644 --- a/docs/api/functions/application_SetupSkill.installCanonicalSkill.html +++ b/docs/api/functions/application_SetupSkill.installCanonicalSkill.html @@ -24,7 +24,7 @@
  • home: string

    • Returns Promise<"failed" | "unchanged" | "installed">

    +
  • Defined in src/application/SetupSkill.ts:50
    • diff --git a/docs/product-catalog.json b/docs/product-catalog.json index 4c63d5fd3..165991e84 100644 --- a/docs/product-catalog.json +++ b/docs/product-catalog.json @@ -8,7 +8,7 @@ "client": "2.0.0-beta.4", "core": "2.0.0-beta.4" }, - "skill_version": "20" + "skill_version": "21" }, "tools": { "total": 95, diff --git a/scripts/generate-package-metadata.mjs b/scripts/generate-package-metadata.mjs index e496ffa8c..945d392dd 100644 --- a/scripts/generate-package-metadata.mjs +++ b/scripts/generate-package-metadata.mjs @@ -18,12 +18,12 @@ const lock = JSON.parse( await readFile(join(root, "package-lock.json"), "utf8"), ); const skill = await readFile( - join(root, "skills/rea-analysis/SKILL.md"), + join(root, "skills/reverse-engineer-anything/SKILL.md"), "utf8", ); const skillVersion = /^\s{2}version:\s*"([^"]+)"\s*$/mu.exec(skill)?.[1]; if (skillVersion === undefined) - throw new Error("Missing rea-analysis skill metadata version"); + throw new Error("Missing reverse-engineer-anything skill metadata version"); const versionOf = (name) => { const value = lock.packages?.[`node_modules/${name}`]?.version; if (typeof value !== "string") diff --git a/scripts/generate-skill-metadata.mjs b/scripts/generate-skill-metadata.mjs index 3c683aca6..3d4bc4bbc 100644 --- a/scripts/generate-skill-metadata.mjs +++ b/scripts/generate-skill-metadata.mjs @@ -10,7 +10,7 @@ for (const argument of arguments_) throw new Error(`Unknown skill metadata option: ${argument}`); const root = join(dirname(fileURLToPath(import.meta.url)), ".."); -const path = join(root, "skills/rea-analysis/SKILL.md"); +const path = join(root, "skills/reverse-engineer-anything/SKILL.md"); const current = await readFile(path, "utf8"); const { CATALOG_IDENTITY } = await import( `${pathToFileURL(join(root, "dist/catalogIdentity.js")).href}?${String(Date.now())}` diff --git a/scripts/verify-package.mjs b/scripts/verify-package.mjs index aa2c680c5..3974c7c05 100644 --- a/scripts/verify-package.mjs +++ b/scripts/verify-package.mjs @@ -756,14 +756,18 @@ try { !mcpRegistration.includes("add-mcp npx -y rea-agents@latest mcp --name rea") ) throw new Error("Incur mcp add did not register the latest npx command"); - const skillPath = join(home, ".agents/skills/rea-analysis/SKILL.md"); + const skillPath = join( + home, + ".agents/skills/reverse-engineer-anything/SKILL.md", + ); + const legacySkillPath = join(home, ".agents/skills/rea-analysis/SKILL.md"); const siblingSkillPath = join(home, ".agents/skills/unrelated/SKILL.md"); if (supportedSetupHost) { await mkdir(join(home, ".agents/skills/rea-analysis"), { recursive: true, }); await mkdir(join(home, ".agents/skills/unrelated"), { recursive: true }); - await writeFile(skillPath, "stale managed skill\n"); + await writeFile(legacySkillPath, "stale managed skill\n"); await writeFile(siblingSkillPath, "unrelated skill\n"); } const plannedExecution = await runWithStatus( @@ -776,7 +780,7 @@ try { const plannedClaudeConfig = await readFile(claudeConfig, "utf8"); const plannedCodexConfig = await readFile(codexTarget, "utf8"); const plannedCursorConfig = await readFile(cursorConfig, "utf8"); - const plannedSkill = await readFile(skillPath, "utf8"); + const plannedSkill = await readFile(legacySkillPath, "utf8"); if ( planned.status !== "needs_confirmation" || plannedExecution.status !== 1 || @@ -856,17 +860,18 @@ try { throw new Error("packaged setup did not preserve config symlinks"); const skill = await readFile(skillPath, "utf8"); const canonicalSkill = await readFile( - join(root, "skills/rea-analysis/SKILL.md"), + join(root, "skills/reverse-engineer-anything/SKILL.md"), "utf8", ); if (skill !== canonicalSkill) throw new Error("packaged skill did not match its canonical source"); if ( - (await readFile(`${skillPath}.rea.backup`, "utf8")) !== + (await pathExists(legacySkillPath)) || + (await readFile(`${legacySkillPath}.rea.backup`, "utf8")) !== "stale managed skill\n" || (await readFile(siblingSkillPath, "utf8")) !== "unrelated skill\n" ) - throw new Error("packaged stale-skill upgrade was not isolated"); + throw new Error("packaged skill-name migration was not isolated"); const alignedDoctorExecution = await runWithStatus( cli, ["doctor", "--json"], diff --git a/skills/rea-analysis/SKILL.md b/skills/reverse-engineer-anything/SKILL.md similarity index 99% rename from skills/rea-analysis/SKILL.md rename to skills/reverse-engineer-anything/SKILL.md index b5cdd0257..6eff4e5f3 100644 --- a/skills/rea-analysis/SKILL.md +++ b/skills/reverse-engineer-anything/SKILL.md @@ -1,8 +1,8 @@ --- -name: rea-analysis +name: reverse-engineer-anything description: Reverse engineer native, Electron/JavaScript, and web applications with REA. Connect static artifacts to passive runtime evidence, explain how features work, and build a version tailored to the user's project. metadata: - version: "20" + version: "21" tool_count: 95 catalog_digest: "b3db06bedadc1ad21a6cfe76f58a9c6cebbf9bce4f9663733b6bab07a57203c3" --- @@ -101,9 +101,9 @@ Notes is only a documentation example. Never select an app unless the user names ## Ensure REA is ready -1. Run `npx -y rea-agents doctor`. +1. Run `npx -y rea-agents@latest doctor`. 2. If setup is needed, tell the user REA needs to install its local binary-analysis tools. Do not lead with implementation details or assume the user knows reverse-engineering products. -3. Before installing external software, obtain approval and identify what will be installed. If deeper analysis needs Hopper, describe it as REA's local analysis engine and note that it is a separate Mac app with its own license. Then run `npx -y rea-agents setup --yes`. +3. Before installing external software, obtain approval and identify what will be installed. If deeper analysis needs Hopper, describe it as REA's local analysis engine and note that it is a separate Mac app with its own license. Then run `npx -y rea-agents@latest setup --yes`. 4. If macOS or an installer requests human input, tell the user exactly what needs attention. After they finish, rerun setup and doctor. 5. If setup registers a new MCP server, tell the user to restart their agent to load all REA tools. Direct CLI commands remain available before restart. diff --git a/src/application/SetupPlan.ts b/src/application/SetupPlan.ts index 4396da098..7a16ff908 100644 --- a/src/application/SetupPlan.ts +++ b/src/application/SetupPlan.ts @@ -3,6 +3,7 @@ import type { SetupClient, SetupProviderEnvironment, } from "./Setup.js"; +import { PRODUCT_IDENTITY } from "../identity.js"; /** Build the complete setup mutation plan before approval. */ export const setupPlan = ( @@ -42,8 +43,9 @@ export const setupPlan = ( ? [ { kind: "install_skill" as const, - target: "~/.agents/skills/rea-analysis/SKILL.md", - detail: "Install or update the bundled REA analysis skill.", + target: `~/.agents/skills/${PRODUCT_IDENTITY.skillName}/SKILL.md`, + detail: + "Install or update the bundled REA reverse-engineering skill.", external: false, }, ] diff --git a/src/application/SetupSkill.ts b/src/application/SetupSkill.ts index c8907cd58..78b59ae7b 100644 --- a/src/application/SetupSkill.ts +++ b/src/application/SetupSkill.ts @@ -1,18 +1,26 @@ -import { mkdir, readFile, rm } from "node:fs/promises"; +import { lstat, mkdir, readFile, rm } from "node:fs/promises"; import { dirname, join } from "node:path"; import writeFileAtomic from "write-file-atomic"; import { PRODUCT_IDENTITY } from "../identity.js"; +const skillDestination = (home: string, name: string): string => + join(home, ".agents/skills", name, "SKILL.md"); + +const readOptionalText = async (path: string): Promise => { + try { + return await readFile(path, "utf8"); + } catch (cause: unknown) { + if (cause instanceof Error && "code" in cause && cause.code === "ENOENT") + return undefined; + throw cause; + } +}; + const canonicalSkillFiles = async ( home: string, ): Promise<{ readonly content: string; readonly destination: string }> => ({ - destination: join( - home, - ".agents/skills", - PRODUCT_IDENTITY.skillName, - "SKILL.md", - ), + destination: skillDestination(home, PRODUCT_IDENTITY.skillName), content: await readFile( new URL( `../../skills/${PRODUCT_IDENTITY.skillName}/SKILL.md`, @@ -28,7 +36,11 @@ export const canonicalSkillNeedsInstall = async ( ): Promise => { try { const { content, destination } = await canonicalSkillFiles(home); - return (await readFile(destination, "utf8")) !== content; + if ((await readOptionalText(destination)) !== content) return true; + for (const name of PRODUCT_IDENTITY.legacySkillNames) + if ((await readOptionalText(skillDestination(home, name))) !== undefined) + return true; + return false; } catch { return true; } @@ -38,45 +50,80 @@ export const canonicalSkillNeedsInstall = async ( export const installCanonicalSkill = async ( home: string, ): Promise<"installed" | "unchanged" | "failed"> => { - let destination = join( - home, - ".agents/skills", - PRODUCT_IDENTITY.skillName, - "SKILL.md", - ); + let destination = skillDestination(home, PRODUCT_IDENTITY.skillName); let backup = `${destination}.rea.backup`; let original: string | undefined; + let canonicalChanged = false; + const removedLegacy: Array<{ + readonly content: string; + readonly destination: string; + }> = []; try { const canonical = await canonicalSkillFiles(home); destination = canonical.destination; backup = `${destination}.rea.backup`; const { content } = canonical; - original = await readFile(destination, "utf8").catch(() => undefined); - if (original === content) return "unchanged"; + original = await readOptionalText(destination); + const legacy: Array<{ + readonly content: string; + readonly destination: string; + }> = []; + for (const name of PRODUCT_IDENTITY.legacySkillNames) { + const legacyDestination = skillDestination(home, name); + const legacyContent = await readOptionalText(legacyDestination); + if (legacyContent !== undefined) { + if ((await lstat(dirname(legacyDestination))).isSymbolicLink()) + throw new Error("legacy skill directory is a symbolic link"); + legacy.push({ content: legacyContent, destination: legacyDestination }); + } + } + if (original === content && legacy.length === 0) return "unchanged"; await mkdir(dirname(destination), { recursive: true }); - if (original !== undefined) + if (original !== undefined && original !== content) await writeFileAtomic(backup, original, { encoding: "utf8", mode: 0o600, }); - await writeFileAtomic(destination, content, { - encoding: "utf8", - mode: 0o600, - }); + canonicalChanged = original !== content; + if (canonicalChanged) + await writeFileAtomic(destination, content, { + encoding: "utf8", + mode: 0o600, + }); if ((await readFile(destination, "utf8")) !== content) throw new Error("skill readback mismatch"); + for (const legacySkill of legacy) { + await writeFileAtomic( + `${legacySkill.destination}.rea.backup`, + legacySkill.content, + { encoding: "utf8", mode: 0o600 }, + ); + await rm(legacySkill.destination, { force: true }); + removedLegacy.push(legacySkill); + } return "installed"; } catch { try { - if (original === undefined) await rm(destination, { force: true }); - else + if (canonicalChanged && original === undefined) + await rm(destination, { force: true }); + else if (canonicalChanged && original !== undefined) await writeFileAtomic(destination, original, { encoding: "utf8", mode: 0o600, }); } catch { - // The backup remains beside the skill for explicit operator recovery. + // The canonical backup remains beside the skill for operator recovery. } + for (const legacySkill of removedLegacy) + try { + await mkdir(dirname(legacySkill.destination), { recursive: true }); + await writeFileAtomic(legacySkill.destination, legacySkill.content, { + encoding: "utf8", + mode: 0o600, + }); + } catch { + // The legacy backup remains beside the skill for operator recovery. + } return "failed"; } }; diff --git a/src/application/Uninstall.ts b/src/application/Uninstall.ts index a645cb528..869d2428d 100644 --- a/src/application/Uninstall.ts +++ b/src/application/Uninstall.ts @@ -87,12 +87,7 @@ export const systemUninstallHost = ( ): UninstallHost => ({ clients: () => Promise.resolve(supportedClients(home)), removeClient: (client) => removeClient(client, fileSystem), - removeSkill: () => - removeManagedPath( - join(home, ".agents/skills", PRODUCT_IDENTITY.skillName), - "skill", - fileSystem, - ), + removeSkill: () => removeManagedSkills(home, fileSystem), purgeData: async () => [ await removeManagedPath(join(home, ".rea/cache"), "cache", fileSystem), await removeManagedPath(join(home, ".rea/state"), "state", fileSystem), @@ -262,6 +257,36 @@ const removeManagedPath = async ( } }; +const removeManagedSkills = async ( + home: string, + fileSystem: UninstallFileSystem, +): Promise => { + const results: UninstallItem[] = []; + for (const name of [ + PRODUCT_IDENTITY.skillName, + ...PRODUCT_IDENTITY.legacySkillNames, + ]) + results.push( + await removeManagedPath( + join(home, ".agents/skills", name), + "skill", + fileSystem, + ), + ); + const failed = results.find(({ status }) => status === "failed"); + if (failed !== undefined) return failed; + const retained = results.find(({ status }) => status === "retained"); + if (retained !== undefined) return retained; + const removed = results.filter(({ status }) => status === "removed"); + if (removed.length > 0) + return item( + "skill", + "removed", + removed.map(({ detail }) => detail).join(" "), + ); + return item("skill", "skipped", "No managed REA skill installation exists."); +}; + const item = ( name: string, status: UninstallItem["status"], diff --git a/src/generatedPackageMetadata.ts b/src/generatedPackageMetadata.ts index 370cbf09c..b3e9df193 100644 --- a/src/generatedPackageMetadata.ts +++ b/src/generatedPackageMetadata.ts @@ -5,5 +5,5 @@ export const PACKAGE_METADATA = { serverSdkVersion: "2.0.0-beta.4", clientSdkVersion: "2.0.0-beta.4", coreSdkVersion: "2.0.0-beta.4", - skillVersion: "20", + skillVersion: "21", } as const; diff --git a/src/identity.ts b/src/identity.ts index 64ed07683..7097c2bb3 100644 --- a/src/identity.ts +++ b/src/identity.ts @@ -11,7 +11,8 @@ export const PRODUCT_IDENTITY = { cliBinary: "rea", mcpCommand: `npx -y ${PACKAGE_METADATA.name}@latest mcp`, mcpServerKey: "rea", - skillName: "rea-analysis", + skillName: "reverse-engineer-anything", + legacySkillNames: ["rea-analysis"], skillVersion: PACKAGE_METADATA.skillVersion, configFileName: "rea.json", } as const; diff --git a/tests/setupLifecycle.test.ts b/tests/setupLifecycle.test.ts index fdbff715e..589417fcc 100644 --- a/tests/setupLifecycle.test.ts +++ b/tests/setupLifecycle.test.ts @@ -146,9 +146,14 @@ describe("agent lifecycle", () => { const home = await mkdtemp(join(tmpdir(), "rea-uninstall-")); roots.push(home); const cursor = join(home, ".cursor/mcp.json"); - const skill = join(home, ".agents/skills/rea-analysis/SKILL.md"); + const skill = join( + home, + ".agents/skills/reverse-engineer-anything/SKILL.md", + ); + const legacySkill = join(home, ".agents/skills/rea-analysis/SKILL.md"); await mkdir(dirname(cursor), { recursive: true }); await mkdir(dirname(skill), { recursive: true }); + await mkdir(dirname(legacySkill), { recursive: true }); await writeFile( cursor, JSON.stringify({ @@ -159,6 +164,7 @@ describe("agent lifecycle", () => { }), ); await writeFile(skill, "managed"); + await writeFile(legacySkill, "legacy managed"); await mkdir(join(home, ".rea"), { recursive: true }); await import("node:fs/promises").then(({ symlink }) => symlink(home, join(home, ".rea/cache")), @@ -168,6 +174,8 @@ describe("agent lifecycle", () => { expect(JSON.parse(await readFile(cursor, "utf8"))).toEqual({ mcpServers: { other: { command: "other" } }, }); + await expect(readFile(skill, "utf8")).rejects.toThrow(); + await expect(readFile(legacySkill, "utf8")).rejects.toThrow(); expect(first.items).toContainEqual( expect.objectContaining({ name: "cache", @@ -300,7 +308,7 @@ describe("agent lifecycle", () => { it("reports a managed-path removal failure", async () => { const home = await mkdtemp(join(tmpdir(), "rea-uninstall-remove-")); roots.push(home); - const skillRoot = join(home, ".agents/skills/rea-analysis"); + const skillRoot = join(home, ".agents/skills/reverse-engineer-anything"); await mkdir(skillRoot, { recursive: true }); const result = await runUninstall( false, diff --git a/tests/setupSkill.test.ts b/tests/setupSkill.test.ts index 33f75bd94..ba9f2c4ad 100644 --- a/tests/setupSkill.test.ts +++ b/tests/setupSkill.test.ts @@ -1,4 +1,11 @@ -import { mkdtemp, mkdir, readFile, rm, writeFile } from "node:fs/promises"; +import { + mkdtemp, + mkdir, + readFile, + rm, + symlink, + writeFile, +} from "node:fs/promises"; import { tmpdir } from "node:os"; import { dirname, join } from "node:path"; import { afterEach, describe, expect, it } from "vitest"; @@ -19,7 +26,10 @@ describe("canonical skill transaction", () => { it("backs up and upgrades a stale managed skill without touching siblings", async () => { const home = await mkdtemp(join(tmpdir(), "rea-skill-test-")); roots.push(home); - const destination = join(home, ".agents/skills/rea-analysis/SKILL.md"); + const destination = join( + home, + ".agents/skills/reverse-engineer-anything/SKILL.md", + ); const sibling = join(home, ".agents/skills/unrelated/SKILL.md"); await mkdir(dirname(destination), { recursive: true }); await mkdir(dirname(sibling), { recursive: true }); @@ -31,7 +41,7 @@ describe("canonical skill transaction", () => { expect(await readFile(`${destination}.rea.backup`, "utf8")).toBe( "stale managed skill\n", ); - expect(await readFile(destination, "utf8")).toContain('version: "20"'); + expect(await readFile(destination, "utf8")).toContain('version: "21"'); expect(await readFile(destination, "utf8")).toContain( `tool_count: ${String(TOOL_CONTRACTS.length)}`, ); @@ -39,4 +49,49 @@ describe("canonical skill transaction", () => { expect(await canonicalSkillNeedsInstall(home)).toBe(false); expect(await installCanonicalSkill(home)).toBe("unchanged"); }); + + it("backs up and retires the legacy skill name", async () => { + const home = await mkdtemp(join(tmpdir(), "rea-skill-test-")); + roots.push(home); + const legacy = join(home, ".agents/skills/rea-analysis/SKILL.md"); + const destination = join( + home, + ".agents/skills/reverse-engineer-anything/SKILL.md", + ); + await mkdir(dirname(legacy), { recursive: true }); + await writeFile(legacy, "legacy managed skill\n"); + + expect(await canonicalSkillNeedsInstall(home)).toBe(true); + expect(await installCanonicalSkill(home)).toBe("installed"); + expect(await readFile(destination, "utf8")).toContain( + "name: reverse-engineer-anything", + ); + expect(await readFile(`${legacy}.rea.backup`, "utf8")).toBe( + "legacy managed skill\n", + ); + await expect(readFile(legacy, "utf8")).rejects.toThrow(); + expect(await canonicalSkillNeedsInstall(home)).toBe(false); + }); + + it("does not migrate a legacy skill through a directory symlink", async () => { + const home = await mkdtemp(join(tmpdir(), "rea-skill-test-")); + roots.push(home); + const skillsRoot = join(home, ".agents/skills"); + const external = join(home, "external-skill"); + const legacyRoot = join(skillsRoot, "rea-analysis"); + const legacy = join(legacyRoot, "SKILL.md"); + const destination = join(skillsRoot, "reverse-engineer-anything/SKILL.md"); + await mkdir(skillsRoot, { recursive: true }); + await mkdir(external, { recursive: true }); + await writeFile(join(external, "SKILL.md"), "external skill\n"); + await symlink( + external, + legacyRoot, + process.platform === "win32" ? "junction" : "dir", + ); + + expect(await installCanonicalSkill(home)).toBe("failed"); + expect(await readFile(legacy, "utf8")).toBe("external skill\n"); + await expect(readFile(destination, "utf8")).rejects.toThrow(); + }); });