Files
opencode-power-pack/bin/opencode-power-pack.mjs
T
Wayner Barrios ab74f6a2ce Add a fail-closed native sandbox runner for portable skill execution
Pin Anthropic's sandbox runtime and translate trusted skill profiles into lightweight, on-demand filesystem, network, credential, and process-tree restrictions. Add readiness diagnostics, secure command and Git workspace discovery, signal-safe cleanup, Linux and macOS integration coverage, packaged-runtime checks, and practical compatibility guidance for Codex, Claude Code, OpenCode, and Pi.
2026-08-16 13:43:54 -05:00

575 lines
19 KiB
JavaScript
Executable File

#!/usr/bin/env node
import { randomUUID } from "node:crypto";
import { realpathSync } from "node:fs";
import {
cp,
lstat,
mkdir,
mkdtemp,
readFile,
readdir,
rename,
rm,
writeFile,
} from "node:fs/promises";
import os from "node:os";
import path from "node:path";
import { fileURLToPath } from "node:url";
import {
loadSandboxContract,
portableSkillPolicy,
resolveSandboxExecutionProfile,
resolveSandboxProfile,
sandboxDoctorReport,
} from "./sandbox/policy.mjs";
import {
probeSandboxRuntime,
runSandboxedCommand,
} from "./sandbox/runtime.mjs";
const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
const USAGE = `OpenCode Power Pack selective skill installer
Usage:
npx @waybarrios/opencode-power-pack list
npx @waybarrios/opencode-power-pack install <skill...> [options]
npx @waybarrios/opencode-power-pack install --profile <name> [options]
npx @waybarrios/opencode-power-pack install --all [options]
npx @waybarrios/opencode-power-pack sandbox doctor [--json]
npx @waybarrios/opencode-power-pack sandbox resolve --skill <name> [--json]
npx @waybarrios/opencode-power-pack sandbox resolve --sandbox-profile <name> [--json]
npx @waybarrios/opencode-power-pack sandbox exec --skill <name> [options] -- <command> [args...]
Options:
--profile <name> Install a curated profile. Repeatable.
--all Install every bundled skill.
--project Install into ./.agents/skills for this repository.
--global Install into ~/.agents/skills. This is the default.
--force Replace an existing skill directory with rollback on failure.
--dry-run Show what would change without writing files.
--sandbox-profile Select an allowed profile escalation for sandbox exec.
--allow-domain Allow one network destination. Repeatable.
--allow-env Expose one existing environment variable. Repeatable.
--confirm-external-side-effects
Confirm a publish profile before sandbox exec.
-h, --help Show this help.
The .agents/skills location is shared by Codex, OpenCode, and Pi.`;
async function pathExists(target) {
try {
await lstat(target);
return true;
} catch (error) {
if (error?.code === "ENOENT") return false;
throw error;
}
}
export async function resolveProjectRoot(start) {
let current = path.resolve(start);
while (true) {
if (await pathExists(path.join(current, ".git"))) return current;
const parent = path.dirname(current);
if (parent === current) {
throw new Error("--project requires running inside a Git repository.");
}
current = parent;
}
}
export async function loadCatalog(packageRoot = PACKAGE_ROOT) {
const source = await readFile(path.join(packageRoot, "skillsets.json"), "utf8");
return JSON.parse(source);
}
export async function discoverSkills(packageRoot = PACKAGE_ROOT) {
const skillsRoot = path.join(packageRoot, "skills");
const entries = await readdir(skillsRoot, { withFileTypes: true });
const skills = [];
for (const entry of entries) {
if (!entry.isDirectory()) continue;
const skillFile = path.join(skillsRoot, entry.name, "SKILL.md");
if (!(await pathExists(skillFile))) continue;
const source = await readFile(skillFile, "utf8");
const description = source
.match(/^---\r?\n([\s\S]*?)\r?\n---/)?.[1]
.split(/\r?\n/)
.find((line) => line.startsWith("description:"))
?.slice("description:".length)
.trim()
.replace(/^(["'])(.*)\1$/, "$2");
skills.push({ name: entry.name, description: description || "" });
}
return skills.sort((left, right) => left.name.localeCompare(right.name));
}
export function resolveSelection({ skillNames = [], profileNames = [], all = false }, catalog, availableNames) {
const available = new Set(availableNames);
const selected = new Set(all ? availableNames : skillNames);
for (const profileName of profileNames) {
const profile = catalog.profiles[profileName];
if (!profile) {
throw new Error(`Unknown profile: ${profileName}`);
}
for (const skillName of profile.skills) selected.add(skillName);
}
if (selected.size === 0) {
throw new Error("Choose at least one skill, profile, or --all.");
}
const pending = [...selected];
while (pending.length > 0) {
const skillName = pending.pop();
if (!available.has(skillName)) {
throw new Error(`Unknown skill: ${skillName}`);
}
for (const dependency of catalog.dependencies[skillName] || []) {
if (!selected.has(dependency)) {
selected.add(dependency);
pending.push(dependency);
}
}
}
return [...selected].sort((left, right) => left.localeCompare(right));
}
async function replaceDirectoryWithRollback(
source,
destination,
force,
packageRoot,
sandboxContract,
) {
const parent = path.dirname(destination);
const name = path.basename(destination);
const lock = `${destination}.opp-lock`;
try {
await mkdir(lock);
} catch (error) {
if (error?.code === "EEXIST") {
throw new Error(
`Another installation is updating ${name}. If no installer is running, remove ${lock}.`,
);
}
throw error;
}
let stagingRoot;
let staged;
let backup;
let operationError;
const warnings = [];
try {
stagingRoot = await mkdtemp(path.join(parent, `.opp-${name}-`));
staged = path.join(stagingRoot, name);
await cp(source, staged, { recursive: true, errorOnExist: true, force: false });
await cp(path.join(packageRoot, "UPSTREAMS.json"), path.join(staged, "UPSTREAMS.json"));
await cp(
path.join(packageRoot, "THIRD_PARTY_NOTICES.md"),
path.join(staged, "THIRD_PARTY_NOTICES.md"),
);
await cp(path.join(packageRoot, "LICENSES"), path.join(staged, "LICENSES"), { recursive: true });
await writeFile(
path.join(staged, "SANDBOX_POLICY.json"),
`${JSON.stringify(portableSkillPolicy(sandboxContract, name), null, 2)}\n`,
"utf8",
);
if (force && await pathExists(destination)) {
backup = path.join(parent, `.opp-backup-${name}-${randomUUID()}`);
await rename(destination, backup);
}
try {
await rename(staged, destination);
} catch (error) {
if (backup && !(await pathExists(destination))) {
try {
await rename(backup, destination);
backup = undefined;
} catch (rollbackError) {
throw new AggregateError(
[error, rollbackError],
[
`Could not promote ${name} or restore its backup at ${backup}.`,
`Promotion failed: ${error.message}`,
`Rollback failed: ${rollbackError.message}`,
].join(" "),
);
}
}
throw error;
}
if (backup) {
try {
await rm(backup, { recursive: true, force: true });
} catch (error) {
warnings.push(`Installed ${name}, but could not remove backup ${backup}: ${error.message}`);
}
}
} catch (error) {
operationError = error;
}
if (stagingRoot) {
try {
await rm(stagingRoot, { recursive: true, force: true });
} catch (error) {
if (operationError) {
operationError = new AggregateError(
[operationError, error],
`Installation and staging cleanup both failed for ${name}.`,
);
} else {
warnings.push(`Installed ${name}, but could not remove staging directory ${stagingRoot}: ${error.message}`);
}
}
}
try {
await rm(lock, { recursive: true, force: true });
} catch (error) {
if (operationError) {
operationError = new AggregateError(
[operationError, error],
`Installation and lock cleanup both failed for ${name}. Lock: ${lock}`,
);
} else {
warnings.push(`Installed ${name}, but could not remove lock ${lock}: ${error.message}`);
}
}
if (operationError) throw operationError;
return warnings;
}
export async function installSkills({
skillNames,
destination,
force = false,
dryRun = false,
packageRoot = PACKAGE_ROOT,
}) {
if (!dryRun) await mkdir(destination, { recursive: true });
const sandboxContract = await loadSandboxContract(packageRoot);
const results = [];
for (const skillName of skillNames) {
const source = path.join(packageRoot, "skills", skillName);
const target = path.join(destination, skillName);
const exists = await pathExists(target);
if (exists && !force) {
results.push({ name: skillName, status: "skipped" });
continue;
}
if (dryRun) {
results.push({ name: skillName, status: exists ? "would-update" : "would-install" });
continue;
}
const warnings = await replaceDirectoryWithRollback(
source,
target,
force,
packageRoot,
sandboxContract,
);
results.push({
name: skillName,
status: exists ? "updated" : "installed",
...(warnings.length > 0 ? { warnings } : {}),
});
}
return results;
}
function parseInstallArgs(args) {
const options = {
skillNames: [],
profileNames: [],
all: false,
force: false,
dryRun: false,
scope: "global",
};
let explicitScope;
for (let index = 0; index < args.length; index += 1) {
const value = args[index];
if (value === "--profile") {
const profileName = args[index + 1];
if (!profileName || profileName.startsWith("-")) {
throw new Error("--profile requires a profile name.");
}
options.profileNames.push(profileName);
index += 1;
} else if (value === "--all") {
options.all = true;
} else if (value === "--force") {
options.force = true;
} else if (value === "--dry-run") {
options.dryRun = true;
} else if (value === "--project" || value === "--global") {
const scope = value.slice(2);
if (explicitScope && explicitScope !== scope) {
throw new Error("Choose only one of --project or --global.");
}
explicitScope = scope;
options.scope = scope;
} else if (value === "--help" || value === "-h") {
options.help = true;
} else if (value.startsWith("-")) {
throw new Error(`Unknown option: ${value}`);
} else {
options.skillNames.push(value);
}
}
return options;
}
function printCatalog(catalog, skills, write) {
write("Profiles:\n");
for (const [name, profile] of Object.entries(catalog.profiles)) {
write(` ${name.padEnd(16)} ${profile.description}\n`);
}
write("\nSkills:\n");
for (const skill of skills) {
write(` ${skill.name.padEnd(42)} ${skill.description}\n`);
}
}
export function parseSandboxArgs(args) {
const [command, ...rest] = args;
if (!command) throw new Error("Choose a sandbox command: doctor, resolve, or exec.");
if (command === "exec") return parseSandboxExecArgs(rest);
if (!["doctor", "resolve"].includes(command)) {
throw new Error(`Unknown sandbox command: ${command}`);
}
const options = { command, json: false };
for (let index = 0; index < rest.length; index += 1) {
const value = rest[index];
if (value === "--json") {
options.json = true;
} else if (value === "--skill" || value === "--sandbox-profile") {
if (command !== "resolve") throw new Error(`${value} is only valid with sandbox resolve.`);
const target = rest[index + 1];
if (!target || target.startsWith("-")) throw new Error(`${value} requires a value.`);
const key = value === "--skill" ? "skillName" : "profileName";
if (options[key]) throw new Error(`${value} may be provided only once.`);
options[key] = target;
index += 1;
} else {
throw new Error(`Unknown sandbox option: ${value}`);
}
}
if (command === "resolve" && !options.skillName && !options.profileName) {
throw new Error("sandbox resolve requires --skill or --sandbox-profile.");
}
if (command === "resolve" && options.skillName && options.profileName) {
throw new Error("Choose exactly one of --skill or --sandbox-profile.");
}
return options;
}
export function parseSandboxExecArgs(args) {
const separator = args.indexOf("--");
if (separator === -1) throw new Error("sandbox exec requires -- before the command.");
const optionArgs = args.slice(0, separator);
const command = args.slice(separator + 1);
if (command.length === 0 || command[0] === "") {
throw new Error("sandbox exec requires a non-empty command after --.");
}
const options = {
command: "exec",
allowedDomains: [],
allowedEnvironment: [],
confirmExternalSideEffects: false,
childCommand: command,
};
for (let index = 0; index < optionArgs.length; index += 1) {
const value = optionArgs[index];
if (["--skill", "--sandbox-profile", "--allow-domain", "--allow-env"].includes(value)) {
const target = optionArgs[index + 1];
if (!target || target.startsWith("-")) throw new Error(`${value} requires a value.`);
if (value === "--skill" || value === "--sandbox-profile") {
const key = value === "--skill" ? "skillName" : "profileName";
if (options[key]) throw new Error(`${value} may be provided only once.`);
options[key] = target;
} else if (value === "--allow-domain") {
options.allowedDomains.push(target);
} else {
options.allowedEnvironment.push(target);
}
index += 1;
} else if (value === "--confirm-external-side-effects") {
if (options.confirmExternalSideEffects) {
throw new Error("--confirm-external-side-effects may be provided only once.");
}
options.confirmExternalSideEffects = true;
} else {
throw new Error(`Unknown sandbox exec option: ${value}`);
}
}
if (!options.skillName) throw new Error("sandbox exec requires --skill.");
return options;
}
function printSandboxResolution(resolution, write) {
if (resolution.skill) write(`Skill: ${resolution.skill}\n`);
write(`Profile: ${resolution.profile.name}\n`);
write(`Description: ${resolution.profile.description}\n`);
write(`Risk level: ${resolution.profile.riskLevel}\n`);
write(`Enforcement: ${resolution.profile.enforcementLevel}\n`);
write("Capabilities:\n");
for (const [name, value] of Object.entries(resolution.profile.capabilities)) {
write(` ${name.padEnd(20)} ${value}\n`);
}
if (resolution.allowedEscalations) {
const names = resolution.allowedEscalations.map((profile) => profile.name);
write(`Allowed escalations: ${names.length > 0 ? names.join(", ") : "none"}\n`);
}
write("Warning: advisory metadata does not isolate commands or tools.\n");
}
function printSandboxDoctor(report, write) {
write(`Sandbox contract: ${report.ok ? "valid" : "invalid"}\n`);
write(`Schema version: ${report.schemaVersion}\n`);
write(`Profiles: ${report.profiles}\n`);
write(`Assigned skills: ${report.assignedSkills}/${report.packagedSkills}\n`);
write(`Enforcement: ${report.enforcementLevel}\n`);
write(`Backend: ${report.backend}\n`);
write(`Runner ready: ${report.runnerReady ? "yes" : "no"}\n`);
write(`Execution level: ${report.executionLevel}\n`);
write(`Strict ready: ${report.strictReady ? "yes" : "no"}\n`);
for (const warning of report.warnings) write(`Warning: ${warning}\n`);
}
export async function runSandboxCommand(args, context) {
const options = parseSandboxArgs(args);
const skills = await discoverSkills(context.packageRoot);
const availableSkillNames = skills.map((skill) => skill.name);
const contract = await loadSandboxContract(context.packageRoot, availableSkillNames);
if (options.command === "exec") {
const profile = resolveSandboxExecutionProfile(contract, options);
return runSandboxedCommand({
profile,
allowedDomains: options.allowedDomains,
allowedEnvironment: options.allowedEnvironment,
confirmExternalSideEffects: options.confirmExternalSideEffects,
command: options.childCommand,
}, context);
}
const result = options.command === "doctor"
? sandboxDoctorReport(
contract,
availableSkillNames,
await probeSandboxRuntime({
cwd: context.cwd,
env: context.env || process.env,
...context.runtimeProbeContext,
}),
)
: resolveSandboxProfile(contract, options);
if (options.json) context.write(`${JSON.stringify(result, null, 2)}\n`);
else if (options.command === "doctor") printSandboxDoctor(result, context.write);
else printSandboxResolution(result, context.write);
return options.command === "doctor" && !result.runnerReady ? 1 : 0;
}
export async function main(args = process.argv.slice(2), context = {}) {
const write = context.write || ((text) => process.stdout.write(text));
const writeError = context.writeError || ((text) => process.stderr.write(text));
const cwd = context.cwd || process.cwd();
const home = context.home || os.homedir();
const packageRoot = context.packageRoot || PACKAGE_ROOT;
const [command = "help", ...rest] = args;
if (command === "help" || command === "--help" || command === "-h") {
write(`${USAGE}\n`);
return 0;
}
if (command === "sandbox") {
return runSandboxCommand(rest, {
...context,
cwd,
home,
packageRoot,
write,
writeError,
});
}
const catalog = await loadCatalog(packageRoot);
const skills = await discoverSkills(packageRoot);
if (command === "list") {
if (rest.length > 0) throw new Error(`Unknown list option: ${rest[0]}`);
printCatalog(catalog, skills, write);
return 0;
}
if (command !== "install") throw new Error(`Unknown command: ${command}`);
const options = parseInstallArgs(rest);
if (options.help) {
write(`${USAGE}\n`);
return 0;
}
const selected = resolveSelection(options, catalog, skills.map((skill) => skill.name));
const destination = options.scope === "project"
? path.join(await resolveProjectRoot(cwd), ".agents", "skills")
: path.join(home, ".agents", "skills");
const results = await installSkills({
skillNames: selected,
destination,
force: options.force,
dryRun: options.dryRun,
packageRoot,
});
write(`${options.dryRun ? "Plan for" : "Selected"} ${results.length} skill(s) in ${destination}\n`);
for (const result of results) {
write(` ${result.status.padEnd(13)} ${result.name}\n`);
for (const warning of result.warnings || []) write(` warning ${warning}\n`);
}
if (!options.dryRun) {
write("Restart your agent if the new skills do not appear automatically.\n");
}
return 0;
}
export function isDirectInvocation(argvEntry, moduleUrl = import.meta.url) {
if (!argvEntry) return false;
try {
return fileURLToPath(moduleUrl) === realpathSync(argvEntry);
} catch {
return false;
}
}
const invokedDirectly = isDirectInvocation(process.argv[1]);
if (invokedDirectly) {
main()
.then((exitCode) => { process.exitCode = exitCode; })
.catch((error) => {
process.stderr.write(`Error: ${error.message}\n`);
process.exitCode = 1;
});
}