mirror of
https://github.com/waybarrios/opencode-power-pack.git
synced 2026-11-18 18:03:43 +00:00
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.
575 lines
19 KiB
JavaScript
Executable File
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;
|
|
});
|
|
}
|