fix(cli): harden setup and destructive workflows

This commit is contained in:
N0zoM1z0
2026-07-14 20:32:18 +00:00
parent bf9619267b
commit c240ae19c6
13 changed files with 351 additions and 53 deletions
+8 -14
View File
@@ -6,21 +6,15 @@ import { relative, resolve } from "node:path";
const root = resolve(import.meta.dirname, "..");
// Collect all TS, MJS, and Python source files, excluding generated and third-party dirs.
const sourceFiles = [
...globSync("src/**/*.ts", {
// Native globSync is available throughout the Node versions in package.engines.
// Its exclusion option is `exclude`; `ignore` and `nodir` belong to npm glob.
const sourceFiles = globSync(
["src/**/*.ts", "tests/**/*.ts", "scripts/**/*.mjs", "bridge/**/*.py"],
{
cwd: root,
nodir: true,
ignore: ["dist/**", "node_modules/**"],
}),
...globSync("tests/**/*.ts", {
cwd: root,
nodir: true,
ignore: ["node_modules/**"],
}),
...globSync("scripts/**/*.mjs", { cwd: root, nodir: true }),
...globSync("bridge/**/*.py", { cwd: root, nodir: true }),
];
exclude: (path) => path.split(/[\\/]/u).includes("node_modules"),
},
);
const patterns = [
{ regex: /TODO(?::\s*(.*))?$/gm, label: "TODO" },
+21 -8
View File
@@ -25,7 +25,10 @@ import { installMacHopper } from "./MacHopper.js";
import { configureDetectedClients } from "./SetupClients.js";
import { supportedClients, type SetupClient } from "./SupportedClients.js";
export type { SetupClient } from "./SupportedClients.js";
import { installCanonicalSkill } from "./SetupSkill.js";
import {
canonicalSkillInstallationNeeded,
installCanonicalSkill,
} from "./SetupSkill.js";
import { setupPlan } from "./SetupPlan.js";
import {
setupInstallFailure,
@@ -69,6 +72,7 @@ export interface SetupHost {
hopperPath: string | undefined,
command: readonly string[],
): Promise<ClientConfigurationResult>;
skillInstallationNeeded(): Promise<boolean>;
installSkill(): Promise<"installed" | "unchanged" | "failed">;
doctor(): Promise<Awaited<ReturnType<typeof runDoctor>>>;
}
@@ -140,7 +144,13 @@ export const runSetup = async (
);
const installHopper = hopperPath === undefined || linuxHopperRepairNeeded;
const detectedClients = await host.detectedClients();
plannedActions = setupPlan(host.platform, installHopper, detectedClients);
const installSkill = await host.skillInstallationNeeded();
plannedActions = setupPlan(
host.platform,
installHopper,
detectedClients,
installSkill,
);
let approved = options.approved;
let interactiveApproval = false;
if (!approved && confirm !== undefined && !options.structured) {
@@ -182,12 +192,14 @@ export const runSetup = async (
appliedActions,
});
if (clientFailure !== undefined) return fail(clientFailure);
const skill = await host.installSkill();
if (skill === "failed")
return fail(
"REA analysis skill could not be installed or verified. Check permissions for `~/.agents/skills`, then rerun setup.",
);
if (skill === "installed") appliedActions.push("installed_skill");
if (installSkill) {
const skill = await host.installSkill();
if (skill === "failed")
return fail(
"REA analysis skill could not be installed or verified. Check permissions for `~/.agents/skills`, then rerun setup.",
);
if (skill === "installed") appliedActions.push("installed_skill");
}
const doctor = await host.doctor();
const remediation = finalSetupRemediation(
host.platform,
@@ -261,6 +273,7 @@ const systemSetupHost = (): SetupHost => {
: client.format === "toml"
? configureTomlClient(client, hopperPath, command)
: configureJsonClient(client, hopperPath, command),
skillInstallationNeeded: () => canonicalSkillInstallationNeeded(homedir()),
installSkill: () => installCanonicalSkill(homedir()),
doctor: () => runDoctor(undefined, doctorHost),
};
+6 -4
View File
@@ -14,7 +14,7 @@ const failedConfigurationMessage = (
return "Agent configuration could not be verified after writing. Repair the configuration file or restore its `.rea.backup`, then rerun setup.";
};
/** Configure each detected agent, stopping after the first failed transaction. */
/** Configure every detected agent and report all failed transaction classes. */
export const configureDetectedClients = async (options: {
readonly host: SetupHost;
readonly detectedClients: readonly SetupClient[];
@@ -23,6 +23,7 @@ export const configureDetectedClients = async (options: {
readonly clients: Record<string, ClientConfigurationResult>;
readonly appliedActions: string[];
}): Promise<string | undefined> => {
const failures = new Set<"backup" | "write" | "readback">();
for (const client of options.detectedClients) {
const result = await options.host.configureClient(
client,
@@ -30,10 +31,11 @@ export const configureDetectedClients = async (options: {
options.command,
);
options.clients[client.name] = result;
if (result.status === "failed")
return failedConfigurationMessage(result.reason);
if (result.status === "failed") failures.add(result.reason);
if (result.status === "configured")
options.appliedActions.push(`configured_${client.name}`);
}
return undefined;
return failures.size === 0
? undefined
: [...failures].map(failedConfigurationMessage).join(" ");
};
+11 -6
View File
@@ -5,6 +5,7 @@ export const setupPlan = (
platform: NodeJS.Platform,
installHopper: boolean,
clients: readonly SetupClient[],
installSkill: boolean,
): readonly SetupAction[] => [
...(installHopper
? [
@@ -32,10 +33,14 @@ export const setupPlan = (
external: false,
}),
),
{
kind: "install_skill",
target: "~/.agents/skills/rea-analysis/SKILL.md",
detail: "Install or update the bundled REA analysis skill.",
external: false,
},
...(installSkill
? [
{
kind: "install_skill" as const,
target: "~/.agents/skills/rea-analysis/SKILL.md",
detail: "Install or update the bundled REA analysis skill.",
external: false,
},
]
: []),
];
+30 -13
View File
@@ -4,26 +4,43 @@ import writeFileAtomic from "write-file-atomic";
import { PRODUCT_IDENTITY } from "../identity.js";
const canonicalSkillDestination = (home: string): string =>
join(home, ".agents/skills", PRODUCT_IDENTITY.skillName, "SKILL.md");
const readCanonicalSkill = (): Promise<string> =>
readFile(
new URL(
`../../skills/${PRODUCT_IDENTITY.skillName}/SKILL.md`,
import.meta.url,
),
"utf8",
);
/** Determine whether setup would need to install or update the canonical skill. */
export const canonicalSkillInstallationNeeded = async (
home: string,
): Promise<boolean> => {
try {
const [canonical, installed] = await Promise.all([
readCanonicalSkill(),
readFile(canonicalSkillDestination(home), "utf8").catch(() => undefined),
]);
return installed !== canonical;
} catch {
// Disclose the action when setup cannot prove the installed copy is aligned.
return true;
}
};
/** Transactionally install or upgrade the versioned canonical REA skill. */
export const installCanonicalSkill = async (
home: string,
): Promise<"installed" | "unchanged" | "failed"> => {
const destination = join(
home,
".agents/skills",
PRODUCT_IDENTITY.skillName,
"SKILL.md",
);
const destination = canonicalSkillDestination(home);
const backup = `${destination}.rea.backup`;
let original: string | undefined;
try {
const content = await readFile(
new URL(
`../../skills/${PRODUCT_IDENTITY.skillName}/SKILL.md`,
import.meta.url,
),
"utf8",
);
const content = await readCanonicalSkill();
original = await readFile(destination, "utf8").catch(() => undefined);
if (original === content) return "unchanged";
await mkdir(dirname(destination), { recursive: true });
+2
View File
@@ -194,6 +194,8 @@ const runCommand = (
): Promise<boolean> =>
new Promise((resolveResult) => {
const child = spawn(command, [...arguments_], {
// Reserve parent stdout for Incur's structured result. Array positions
// are child fds 0/1/2, so npm stdout and stderr both reach parent stderr.
stdio:
output === "human" ? "inherit" : ["inherit", process.stderr, "inherit"],
});
+3 -1
View File
@@ -160,7 +160,9 @@ const registerSetupCommands = (
installHopper: z
.boolean()
.default(false)
.describe("Also approve Hopper installation with --yes"),
.describe(
"Approve Hopper installation when missing or repair is needed (requires --yes)",
),
}),
alias: { yes: "y", installHopper: "install-hopper" },
run: ({ options, formatExplicit }) =>
+40 -2
View File
@@ -1,4 +1,5 @@
import { Cli, z } from "incur";
import { createInterface } from "node:readline/promises";
import { loadConfiguredPermissionAuthority } from "./application/PermissionConfiguration.js";
import {
@@ -49,9 +50,13 @@ export const registerPolicyCommands = (
network: z.enum(["none", "loopback", "external"]).default("none"),
mount: z.boolean().default(false),
write: z.boolean().default(false),
yes: z
.boolean()
.default(false)
.describe("Confirm a destructive policy revocation without prompting"),
}),
alias: { environmentNames: "environment-names" },
run: ({ args, options }) =>
alias: { environmentNames: "environment-names", yes: "y" },
run: ({ args, options, formatExplicit }) =>
logCliCommand(logger, "policy", async () => {
const config = parseConfig(process.env);
if (!config.ok) return failure(config.error);
@@ -76,6 +81,22 @@ export const registerPolicyCommands = (
permissionProjectStore === undefined
)
return { error: "Project policy is not configured" };
if (!options.yes) {
if (formatExplicit || process.stdin.isTTY !== true)
return {
error: "ConfirmationRequired",
message: "Policy grant revocation requires confirmation",
grant_id: args.value,
remediation:
"Verify the grant ID, then rerun the same command with --yes.",
};
if (!(await confirmRevocation(args.value)))
return {
error: "Cancelled",
message: "Policy grant revocation was cancelled",
grant_id: args.value,
};
}
const revoked = await revokeProjectPermissionGrant(
permissionProjectStore,
permissionProjectRoot,
@@ -100,6 +121,23 @@ export const registerPolicyCommands = (
});
};
const confirmRevocation = async (grantId: string): Promise<boolean> => {
const prompt = createInterface({
input: process.stdin,
output: process.stdout,
});
try {
const answer = (
await prompt.question(`Revoke policy grant "${grantId}"? [y/N] `)
)
.trim()
.toLowerCase();
return answer === "y" || answer === "yes";
} finally {
prompt.close();
}
};
const explain = async (
config: AppConfig,
capability: PermissionCapability,
+1 -3
View File
@@ -187,9 +187,7 @@ const linuxDemoLaunch = (
};
const usesLinuxDemo = (options: HopperApplicationLauncherOptions): boolean =>
process.platform === "linux" &&
basename(options.launcherPath) === "Hopper" &&
options.demoHelperPath !== undefined;
process.platform === "linux" && options.demoHelperPath !== undefined;
const spawnLauncher = async (
command: string,
+57
View File
@@ -0,0 +1,57 @@
import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { afterEach, describe, expect, it } from "vitest";
import { HopperApplicationLauncher } from "../src/hopper/BridgeLauncher.js";
const directories: string[] = [];
afterEach(async () => {
await Promise.all(
directories
.splice(0)
.map((path) => rm(path, { recursive: true, force: true })),
);
});
describe("Hopper application launcher", () => {
it.skipIf(process.platform !== "linux")(
"uses the Linux demo helper for a non-canonical launcher path",
async () => {
const directory = await mkdtemp(join(tmpdir(), "rea-launcher-test-"));
directories.push(directory);
const helper = join(directory, "demo-helper.py");
await writeFile(helper, "import sys\nsys.exit(0)\n");
const launcher = new HopperApplicationLauncher({
launcherPath: "/usr/bin/true",
targetPath: "/tmp/fixture",
targetKind: "executable",
loaderArgs: [],
bridgeScriptPath: "/tmp/hopper_bridge.py",
demoHelperPath: helper,
});
const launched = await launcher.launch({
directory,
socketPath: join(directory, "bridge.sock"),
token: "token",
runId: "run-wrapper",
});
expect(launched.ok).toBe(true);
if (!launched.ok) return;
expect(launched.value.process.spawnfile).toBe("/usr/bin/python3");
expect(launched.value.process.spawnargs).toContain(helper);
expect(launched.value.shutdownByCleanup).toBe(true);
expect(await readFile(join(directory, "bootstrap.py"), "utf8")).toContain(
"REA_OWNS_PROCESS_LIFETIME = True",
);
if (launched.value.process.exitCode === null)
await new Promise<void>((resolve) => {
launched.value.process.once("exit", () => resolve());
});
},
);
});
+95
View File
@@ -0,0 +1,95 @@
import { execFile } from "node:child_process";
import { mkdtemp, rm } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { promisify } from "node:util";
import { afterEach, describe, expect, it } from "vitest";
import {
readProjectPermissionStore,
writeProjectPermissionStore,
} from "../src/application/ProjectPermissionStore.js";
const execFileAsync = promisify(execFile);
const CLI_INTEGRATION_TIMEOUT_MS = 60_000;
const roots: string[] = [];
afterEach(async () => {
await Promise.all(
roots.splice(0).map((root) => rm(root, { recursive: true, force: true })),
);
});
describe("policy CLI revocation", () => {
it(
"requires confirmation in structured mode and accepts explicit approval",
async () => {
const project = await mkdtemp(join(tmpdir(), "rea-policy-cli-"));
roots.push(project);
const store = join(project, ".rea", "permissions.json");
const grant = {
grant_id: "project:evidence-read",
capability: "evidence_read" as const,
roots: [project],
executables: [],
environment_names: [],
network: "none" as const,
mount: false,
lifetime: "project" as const,
operation_identity: null,
expires_at: null,
};
expect(
(await writeProjectPermissionStore(store, project, [grant])).ok,
).toBe(true);
const environment = {
...process.env,
REA_PERMISSION_PROJECT_ROOT: project,
REA_PERMISSION_PROJECT_STORE: store,
};
const unapproved = await execFileAsync(
process.execPath,
["scripts/rea.mjs", "--json", "policy", "revoke", grant.grant_id],
{ cwd: process.cwd(), env: environment },
).catch((cause: unknown) => cause);
expect(unapproved).toMatchObject({ code: 1, stderr: "" });
expect(
JSON.parse((unapproved as { readonly stdout: string }).stdout),
).toEqual({
error: "ConfirmationRequired",
message: "Policy grant revocation requires confirmation",
grant_id: grant.grant_id,
remediation:
"Verify the grant ID, then rerun the same command with --yes.",
});
expect(await readProjectPermissionStore(store, project)).toMatchObject({
ok: true,
value: { grants: [grant] },
});
const approved = await execFileAsync(
process.execPath,
[
"scripts/rea.mjs",
"--json",
"policy",
"revoke",
grant.grant_id,
"--yes",
],
{ cwd: process.cwd(), env: environment },
);
expect(JSON.parse(approved.stdout)).toEqual({
revoked: grant.grant_id,
reload: "Send SIGHUP to the REA MCP process",
});
expect(await readProjectPermissionStore(store, project)).toMatchObject({
ok: true,
value: { grants: [] },
});
},
CLI_INTEGRATION_TIMEOUT_MS,
);
});
+64 -2
View File
@@ -19,9 +19,11 @@ class FakeSetupHost implements SetupHost {
hopper: string | undefined;
hopperInstallSucceeds = true;
skill: "installed" | "unchanged" | "failed" = "installed";
skillNeedsInstallation = true;
clients: readonly SetupClient[] = [];
clientResults = new Map<string, ClientConfigurationResult>();
hopperInstalls = 0;
skillInstallations = 0;
configurations = 0;
doctorHealthy: boolean | undefined;
linuxDemoRuntimeMissing = false;
@@ -62,8 +64,12 @@ class FakeSetupHost implements SetupHost {
this.clientResults.get(client.name) ?? { status: "configured" },
);
};
installSkill = (): Promise<"installed" | "unchanged" | "failed"> =>
Promise.resolve(this.skill);
skillInstallationNeeded = (): Promise<boolean> =>
Promise.resolve(this.skillNeedsInstallation);
installSkill = (): Promise<"installed" | "unchanged" | "failed"> => {
this.skillInstallations += 1;
return Promise.resolve(this.skill);
};
doctor = (): Promise<{
healthy: boolean;
hopperPath?: string;
@@ -126,6 +132,21 @@ describe("setup workflow", () => {
);
});
it("omits an aligned skill from the plan and does not reinstall it", async () => {
const host = new FakeSetupHost();
host.hopper = "/Applications/Hopper";
host.skillNeedsInstallation = false;
const result = await runSetup(options(true), host);
expect(result.status).toBe("ready");
expect(result.plannedActions.map(({ kind }) => kind)).not.toContain(
"install_skill",
);
expect(result.appliedActions).toEqual([]);
expect(host.skillInstallations).toBe(0);
});
it("reports ready after an accepted Linux plan installs healthy Hopper", async () => {
const host = new FakeSetupHost("linux");
host.distribution = {
@@ -218,6 +239,19 @@ describe("setup workflow", () => {
expect(host.hopperInstalls).toBe(0);
});
it("treats --install-hopper as approval, not a healthy reinstall request", async () => {
const host = new FakeSetupHost();
host.hopper = "/Applications/Hopper";
const result = await runSetup(options(true, true), host);
expect(result.status).toBe("ready");
expect(result.plannedActions.map(({ kind }) => kind)).not.toContain(
"install_hopper",
);
expect(host.hopperInstalls).toBe(0);
});
it("installs missing Linux demo dependencies for existing Hopper", async () => {
const host = new FakeSetupHost("linux");
host.distribution = {
@@ -297,6 +331,34 @@ describe("setup workflow", () => {
expect(result.remediation).not.toContain("internal_client_key");
});
it("records later client outcomes after an earlier configuration fails", async () => {
const host = new FakeSetupHost();
host.hopper = "/Applications/Hopper";
host.clients = [
{ name: "before", configPath: "/before.json" },
{ name: "broken", configPath: "/broken.json" },
{ name: "after", configPath: "/after.json" },
];
host.clientResults.set("broken", { status: "failed", reason: "write" });
const result = await runSetup(options(true), host);
expect(result.status).toBe("needs_human");
expect(host.configurations).toBe(3);
expect(result.clients).toEqual({
before: { status: "configured" },
broken: { status: "failed", reason: "write" },
after: { status: "configured" },
});
expect(result.appliedActions).toEqual([
"configured_before",
"configured_after",
]);
expect(result.remediation).toBe(
"Agent configuration could not be updated. Check file permissions, then rerun setup.",
);
});
it("explains skill installation recovery", async () => {
const host = new FakeSetupHost();
host.hopper = "/Applications/Hopper";
+13
View File
@@ -3,6 +3,7 @@ import { tmpdir } from "node:os";
import { dirname, join } from "node:path";
import { afterEach, describe, expect, it } from "vitest";
import { installCanonicalSkill } from "../src/application/Setup.js";
import { canonicalSkillInstallationNeeded } from "../src/application/SetupSkill.js";
import { TOOL_CONTRACTS } from "../src/contracts/toolContracts.js";
const roots: string[] = [];
@@ -32,6 +33,18 @@ describe("canonical skill transaction", () => {
`tool_count: ${String(TOOL_CONTRACTS.length)}`,
);
expect(await readFile(sibling, "utf8")).toBe("unrelated skill\n");
expect(await canonicalSkillInstallationNeeded(home)).toBe(false);
expect(await installCanonicalSkill(home)).toBe("unchanged");
});
it("reports a missing or stale canonical skill as needing installation", async () => {
const home = await mkdtemp(join(tmpdir(), "rea-skill-plan-test-"));
roots.push(home);
const destination = join(home, ".agents/skills/rea-analysis/SKILL.md");
expect(await canonicalSkillInstallationNeeded(home)).toBe(true);
await mkdir(dirname(destination), { recursive: true });
await writeFile(destination, "stale managed skill\n");
expect(await canonicalSkillInstallationNeeded(home)).toBe(true);
});
});