@wrangled/cli 0.2.0

package/dist/runner/run.js

@@ -0,0 +1,204 @@
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { setTimeout as sleep } from "node:timers/promises";
+import { fileURLToPath } from "node:url";
+import { api, ApiError, apiText, CliError, exitCodes, getSigned, writeCredentials } from "../api.js";
+import { brand, envPrefix } from "../brand.js";
+import { RUN_ROOT_ENV } from "../files.js";
+import { installSkillFolder, unpackSkill } from "../skills.js";
+import { parseClaim } from "./claim.js";
+import { MAX_TURNS } from "./harness.js";
+import { commandHarness, harnesses } from "./harnesses.js";
+import { LogTail, redact, RUN_ERROR_MAX_BYTES, tailBytes } from "./redact.js";
+export const RUNNER_TOKEN_ENV = `${envPrefix}_RUNNER_TOKEN`;
+export const HARNESS_COMMAND_ENV = `${envPrefix}_RUNNER_HARNESS_COMMAND`;
+export const API_URL_ENV = `${envPrefix}_API_URL`;
+/** Set for a harness, so its agent, memory and proposal commands act as the run's skill's agent unless told otherwise. */
+export const AGENT_ENV = `${envPrefix}_AGENT`;
+const HEARTBEAT_MS = 60_000;
+const IDLE_WAIT_MS = 60_000;
+const FINISH_RETRY_WAITS_MS = [2_000, 5_000, 15_000];
+/** What a harness may inherit from the runner's environment. Keys and tokens are never on it. */
+const INHERITED_ENV = ["HOME", "USER", "LOGNAME", "SHELL", "TERM", "LANG", "LC_ALL", "LC_CTYPE", "TMPDIR", "TZ"];
+const stopMessages = {
+    deadline: "The run's deadline passed, so the runner stopped the harness.",
+    cancelled: "The run was cancelled, so the runner stopped the harness.",
+    stopped: "The runner was stopped, so it stopped the harness.",
+};
+/**
+ * The environment a harness starts with, built from nothing: the allowlisted basics, the run's own `wr` first on
+ * PATH, its config folder, the API address, and the run folder, outside which `wr` reads and writes no files.
+ */
+export function harnessEnv(source, run) {
+    const env = {};
+    for (const name of INHERITED_ENV) {
+        const value = source[name];
+        if (value !== undefined)
+            env[name] = value;
+    }
+    env.PATH = [run.binDir, source.PATH || "/usr/bin:/bin"].join(":");
+    env.XDG_CONFIG_HOME = run.configHome;
+    env[API_URL_ENV] = run.apiUrl;
+    env[RUN_ROOT_ENV] = run.dir;
+    env[AGENT_ENV] = "skill";
+    return env;
+}
+/** The worker's prompt, then how a run keeps its log, notes and proposals as its skill's agent. */
+export function runPrompt(prompt) {
+    const cli = brand.slug;
+    return `${prompt}
+
+This is a scheduled run for one ${brand.name} workspace. Run \`${cli} agent start\` first: it opens this run's log and prints its run id and your notes from earlier runs (\`${cli} memory get\` prints them in full). Rewrite a note for the next run with \`${cli} memory set <note> --file <path>\`. Propose a draft ad for a person to approve with \`${cli} proposals create\`, giving the run id. Run \`${cli} agent finish <run-id> --status succeeded|failed --file <report.md>\` last, with a short Markdown report whose first line says what the run did.`;
+}
+const shellQuote = (s) => `'${s.replaceAll("'", `'\\''`)}'`;
+/** A `wr` that runs this very CLI with this very Node. */
+function cliShim() {
+    const main = fileURLToPath(new URL("../main.js", import.meta.url));
+    return `#!/bin/sh\nexec ${shellQuote(process.execPath)} ${shellQuote(main)} "$@"\n`;
+}
+const runnerConnection = (options) => ({
+    apiUrl: options.apiUrl,
+    apiKey: options.token,
+    rejected: `The runner token in ${RUNNER_TOKEN_ENV} was rejected by ${options.apiUrl}.`,
+});
+/** Claims one run, does it in a fresh folder, reports how it ended, and removes the folder. */
+export async function runOnce(options) {
+    const connection = runnerConnection(options);
+    const answer = await apiText(connection, "/api/runner/claim", options.runId === undefined ? {} : { runId: options.runId });
+    if (answer === "")
+        return { kind: "idle" };
+    const claim = parseClaim(JSON.parse(answer));
+    const secrets = [claim.runKey, options.token, ...(claim.billing.kind === "openrouter" ? [claim.billing.key] : [])];
+    const say = (line) => options.say(redact(line, secrets));
+    say(`Claimed run ${claim.runId}: ${claim.skill.name} version ${claim.skill.version} with ${claim.harness}.`);
+    const stop = new AbortController();
+    const stopWith = (reason) => {
+        if (!stop.signal.aborted)
+            stop.abort(reason);
+    };
+    const onStop = () => stopWith("stopped");
+    if (options.signal.aborted)
+        onStop();
+    options.signal.addEventListener("abort", onStop, { once: true });
+    const deadline = Math.min(claim.deadline.getTime(), options.maxSeconds === undefined ? Infinity : Date.now() + options.maxSeconds * 1000);
+    const deadlineTimer = setTimeout(() => stopWith("deadline"), Math.max(0, deadline - Date.now()));
+    const heartbeat = startHeartbeat(connection, claim.runId, () => stopWith("cancelled"), say);
+    const log = new LogTail();
+    let dir;
+    let report;
+    try {
+        dir = await mkdtemp(join(tmpdir(), `${brand.slug}-run-`));
+        const result = await execute(claim, dir, options, stop.signal, (text) => log.append(text));
+        report = finishReport(result, stop.signal.reason);
+    }
+    catch (error) {
+        report = { status: "failed", error: stop.signal.aborted ? stopMessages[stop.signal.reason] : `The runner failed: ${error.message}` };
+    }
+    finally {
+        clearTimeout(deadlineTimer);
+        heartbeat.stop();
+        options.signal.removeEventListener("abort", onStop);
+        if (dir !== undefined)
+            await rm(dir, { recursive: true, force: true }).catch((error) => say(`Could not remove ${dir}: ${error.message}`));
+    }
+    report.logTail = log.report(secrets);
+    if (report.error !== undefined)
+        report.error = tailBytes(redact(report.error, secrets), RUN_ERROR_MAX_BYTES);
+    try {
+        await finish(connection, claim.runId, report, say);
+    }
+    catch (error) {
+        if (error instanceof ApiError && error.status === 409) {
+            say(`Run ${claim.runId} had already ended on the server (${error.message}).`);
+            return { kind: "ran", runId: claim.runId, status: "ended_elsewhere" };
+        }
+        throw error;
+    }
+    say(`Run ${claim.runId} ${report.status}${report.error ? `: ${report.error}` : "."}`);
+    return { kind: "ran", runId: claim.runId, status: report.status };
+}
+/** Finish is idempotent on the server, so a network failure or a server error is worth another try before the run is lost. */
+async function finish(connection, runId, report, say) {
+    for (const wait of [...FINISH_RETRY_WAITS_MS, undefined]) {
+        try {
+            await api(connection, `/api/runner/runs/${runId}/finish`, report);
+            return;
+        }
+        catch (error) {
+            const retryable = error instanceof ApiError ? error.status >= 500 : error instanceof CliError && error.exitCode !== exitCodes.auth;
+            if (!retryable || wait === undefined)
+                throw error;
+            say(`Finishing run ${runId} failed (${error.message}); trying again.`);
+            await sleep(wait);
+        }
+    }
+}
+function finishReport(result, stopped) {
+    const { exitCode, tokens } = result;
+    if (stopped)
+        return { status: "failed", exitCode, tokens, error: stopMessages[stopped] };
+    if (exitCode === 0)
+        return { status: "succeeded", exitCode, tokens };
+    return { status: "failed", exitCode, tokens, error: `The harness exited with code ${exitCode}.` };
+}
+/** Puts the skill, the run key's login and a `wr` in `dir`, then runs the harness there. */
+async function execute(claim, dir, options, signal, log) {
+    const skillsDir = join(dir, claim.harness === "claude" ? ".claude" : ".codex", "skills");
+    await installSkillFolder(skillsDir, claim.skill.name, unpackSkill(claim.skill, await getSigned(claim.skill.url)), []);
+    const configHome = join(dir, ".config");
+    await writeCredentials({ apiKey: claim.runKey, apiUrl: options.apiUrl }, configHome);
+    const binDir = join(dir, ".bin");
+    await mkdir(binDir);
+    await writeFile(join(binDir, brand.slug), cliShim(), { mode: 0o755 });
+    if (signal.aborted)
+        throw new Error("stopped before the harness started");
+    const harness = options.harnessCommand ? commandHarness(options.harnessCommand) : harnesses[claim.harness];
+    return harness({
+        dir,
+        skill: claim.skill.name,
+        prompt: runPrompt(claim.prompt),
+        model: claim.model,
+        billing: claim.billing,
+        aiCapUsd: claim.aiCapUsd,
+        maxTurns: MAX_TURNS,
+        env: harnessEnv(process.env, { dir, binDir, configHome, apiUrl: options.apiUrl }),
+        signal,
+        log,
+    });
+}
+/** Beats now (moving the run to running) and every minute; a cancel, or a server that no longer knows the run, stops it. */
+function startHeartbeat(connection, runId, cancel, say) {
+    const beat = async () => {
+        try {
+            const answer = await api(connection, `/api/runner/runs/${runId}/heartbeat`, {});
+            if (answer.cancel)
+                cancel();
+        }
+        catch (error) {
+            if (error instanceof ApiError && error.status === 404)
+                cancel();
+            else
+                say(`Heartbeat for run ${runId} failed: ${error.message}`);
+        }
+    };
+    void beat();
+    const timer = setInterval(() => void beat(), HEARTBEAT_MS);
+    return { stop: () => clearInterval(timer) };
+}
+/** Does runs one at a time until `signal` aborts: straight on after a run, a minute's wait after finding none. */
+export async function runLoop(options) {
+    while (!options.signal.aborted) {
+        let ran = false;
+        try {
+            ran = (await runOnce(options)).kind === "ran";
+        }
+        catch (error) {
+            if (error instanceof CliError && error.exitCode === exitCodes.auth)
+                throw error;
+            options.say(redact(`error: ${error.message}`, [options.token]));
+        }
+        if (!ran)
+            await sleep(IDLE_WAIT_MS, undefined, { signal: options.signal }).catch(() => undefined);
+    }
+}

package/dist/skill-zip.js

@@ -0,0 +1,189 @@
+// The server and the CLI each keep an identical copy of this file (src/lib/skills/skill-zip.ts and cli/src/skill-zip.ts);
+// src/lib/cli-consistency.test.ts fails when they differ.
+import { Inflate, zipSync } from "fflate";
+export const SKILL_NAME_PATTERN = /^[a-z0-9][a-z0-9-]{0,63}$/;
+/**
+ * A published skill's zip, before and after inflating. The zip cap stays under the hosting platform's 4.5 MB request
+ * limit. `files` counts files only; `entries` also counts the folder records `zip -r` writes.
+ */
+export const SKILL_LIMITS = { zipBytes: 4 * 1024 * 1024, files: 200, entries: 1000, unpackedBytes: 20 * 1024 * 1024 };
+export const SKILL_MD = "SKILL.md";
+export class SkillZipError extends Error {
+}
+const refuse = (reason) => {
+    throw new SkillZipError(`refused: ${reason}`);
+};
+const megabytes = (bytes) => `${Math.round((bytes / (1024 * 1024)) * 10) / 10} MB`;
+export function refuseOversizedZip(bytes) {
+    if (bytes > SKILL_LIMITS.zipBytes)
+        refuse(`zip is ${megabytes(bytes)}, the limit is ${megabytes(SKILL_LIMITS.zipBytes)}`);
+}
+export function refuseTooManyFiles(files) {
+    if (files > SKILL_LIMITS.files)
+        refuse(`zip holds ${files} files, the limit is ${SKILL_LIMITS.files}`);
+}
+export function refuseOversizedFiles(bytes) {
+    if (bytes > SKILL_LIMITS.unpackedBytes)
+        refuse(`files unpack to ${megabytes(bytes)}, the limit is ${megabytes(SKILL_LIMITS.unpackedBytes)}`);
+}
+/** Why a file name inside a skill cannot be written safely, or null when it can. Names are relative to the skill folder. */
+export function unsafeFileName(name) {
+    if (name.includes("\\"))
+        return `backslash in ${name}`;
+    if (name.startsWith("/") || /^[A-Za-z]:/.test(name))
+        return `absolute path ${name}`;
+    if (name.includes("\0"))
+        return `NUL in ${JSON.stringify(name)}`;
+    const segments = name.split("/");
+    if (segments.includes(".."))
+        return `.. in ${name}`;
+    if (segments.some((s) => s === "" || s === "."))
+        return `empty or . segment in ${name}`;
+    return null;
+}
+/** Zips the files; each name is a `/`-separated path inside the skill folder. */
+export function zipSkillFiles(files) {
+    const unix = (mode) => ({ os: 3, attrs: ((0o100000 | mode) << 16) >>> 0 });
+    return zipSync(Object.fromEntries(files.map((f) => [f.name, [f.data, unix(f.executable ? 0o755 : 0o644)]])), { level: 9 });
+}
+/** Reads and checks a skill's zip without trusting any size or name it declares. Throws SkillZipError naming the problem. */
+export function readSkillZip(zip, skillName) {
+    refuseOversizedZip(zip.byteLength);
+    const files = unpack(zip);
+    const skillMd = files.find((f) => f.name === SKILL_MD) ?? refuse(`no ${SKILL_MD} at the top of the skill folder`);
+    const front = frontMatter(new TextDecoder().decode(skillMd.data));
+    const name = front.get("name") || refuse(`${SKILL_MD} has no name in its front matter`);
+    if (name !== skillName)
+        refuse(`${SKILL_MD} name '${name}' does not match skill '${skillName}'`);
+    const description = front.get("description") || refuse(`${SKILL_MD} has no description in its front matter`);
+    return { title: front.get("title") || name, description, files };
+}
+const EOCD = 0x06054b50;
+const CENTRAL = 0x02014b50;
+const LOCAL = 0x04034b50;
+const SYMLINK = 0o120000;
+const FILE_TYPE = 0o170000;
+const INFLATE_STEP = 4096;
+function unpack(zip) {
+    const view = new DataView(zip.buffer, zip.byteOffset, zip.byteLength);
+    const u16 = (at) => (at + 2 <= zip.byteLength ? view.getUint16(at, true) : refuse("zip is cut short"));
+    const u32 = (at) => (at + 4 <= zip.byteLength ? view.getUint32(at, true) : refuse("zip is cut short"));
+    let end = -1;
+    for (let at = zip.byteLength - 22; at >= Math.max(0, zip.byteLength - 22 - 0xffff); at--) {
+        if (view.getUint32(at, true) === EOCD) {
+            end = at;
+            break;
+        }
+    }
+    if (end === -1)
+        refuse("not a zip file");
+    const count = u16(end + 10);
+    let at = u32(end + 16);
+    if (count === 0xffff || at === 0xffffffff)
+        refuse("zip64 archives are not supported");
+    if (count > SKILL_LIMITS.entries)
+        refuse(`zip holds ${count} entries, the limit is ${SKILL_LIMITS.entries}`);
+    const entries = [];
+    for (let i = 0; i < count; i++) {
+        if (u32(at) !== CENTRAL)
+            refuse("zip's file list is damaged");
+        const flags = u16(at + 8);
+        const nameLength = u16(at + 28);
+        const name = new TextDecoder().decode(zip.subarray(at + 46, at + 46 + nameLength));
+        const mode = u32(at + 38) >>> 16;
+        const entry = { name, method: u16(at + 10), compressed: u32(at + 20), size: u32(at + 24), local: u32(at + 42), executable: (mode & 0o111) !== 0 };
+        at += 46 + nameLength + u16(at + 30) + u16(at + 32);
+        const unsafe = unsafeFileName(name.endsWith("/") ? name.slice(0, -1) : name);
+        if (unsafe)
+            refuse(unsafe);
+        if ((mode & FILE_TYPE) === SYMLINK)
+            refuse(`symlink at ${name}`);
+        if (flags & 1)
+            refuse(`${name} is encrypted`);
+        if (name.endsWith("/"))
+            continue;
+        if (entries.some((e) => e.name === name))
+            refuse(`${name} appears twice`);
+        if (entry.method !== 0 && entry.method !== 8)
+            refuse(`${name} uses an unsupported compression method`);
+        entries.push(entry);
+    }
+    refuseTooManyFiles(entries.length);
+    refuseOversizedFiles(entries.reduce((sum, e) => sum + e.size, 0));
+    let unpacked = 0;
+    return entries.map((entry) => {
+        if (u32(entry.local) !== LOCAL)
+            refuse(`zip entry ${entry.name} is damaged`);
+        const start = entry.local + 30 + u16(entry.local + 26) + u16(entry.local + 28);
+        if (start + entry.compressed > zip.byteLength)
+            refuse("zip is cut short");
+        const raw = zip.subarray(start, start + entry.compressed);
+        // A zip can declare small sizes and still inflate to gigabytes, so the inflated bytes are counted as they arrive.
+        const chunks = [];
+        let size = 0;
+        const take = (chunk) => {
+            size += chunk.byteLength;
+            unpacked += chunk.byteLength;
+            if (size > entry.size)
+                refuse(`${entry.name} unpacks to more than the zip says`);
+            if (unpacked > SKILL_LIMITS.unpackedBytes)
+                refuse(`files unpack to more than ${megabytes(SKILL_LIMITS.unpackedBytes)}`);
+            chunks.push(chunk);
+        };
+        if (entry.method === 0)
+            take(raw);
+        else {
+            const inflate = new Inflate((chunk) => take(chunk));
+            try {
+                let offset = 0;
+                do {
+                    inflate.push(raw.subarray(offset, offset + INFLATE_STEP), offset + INFLATE_STEP >= raw.byteLength);
+                    offset += INFLATE_STEP;
+                } while (offset < raw.byteLength);
+            }
+            catch (error) {
+                if (error instanceof SkillZipError)
+                    throw error;
+                refuse(`${entry.name} is damaged`);
+            }
+        }
+        if (size !== entry.size)
+            refuse(`${entry.name} unpacks to a different size than the zip says`);
+        const data = new Uint8Array(size);
+        let offset = 0;
+        for (const chunk of chunks) {
+            data.set(chunk, offset);
+            offset += chunk.byteLength;
+        }
+        return { name: entry.name, data, executable: entry.executable };
+    });
+}
+/** The `key: value` lines between the opening `---` fences. Quoted values lose their quotes; `>` and `|` blocks are joined. */
+function frontMatter(text) {
+    const lines = text.replace(/^/, "").split(/\r?\n/);
+    const values = new Map();
+    if (lines[0]?.trim() !== "---")
+        return values;
+    const close = lines.findIndex((line, i) => i > 0 && line.trim() === "---");
+    if (close === -1)
+        refuse(`${SKILL_MD} front matter has no closing ---`);
+    for (let i = 1; i < close; i++) {
+        const match = /^([A-Za-z_][\w-]*):\s*(.*)$/.exec(lines[i]);
+        if (!match)
+            continue;
+        const key = match[1];
+        let value = match[2].trim();
+        if (/^[>|][-+]?$/.test(value)) {
+            const block = [];
+            while (i + 1 < close && /^(\s+\S|\s*$)/.test(lines[i + 1]))
+                block.push(lines[++i].trim());
+            value = block.join(value.startsWith(">") ? " " : "\n").trim();
+        }
+        else if (/^"(.*)"$/.test(value))
+            value = value.slice(1, -1).replace(/\\"/g, '"').replace(/\\\\/g, "\\");
+        else if (/^'(.*)'$/.test(value))
+            value = value.slice(1, -1).replace(/''/g, "'");
+        values.set(key, value);
+    }
+    return values;
+}

package/dist/skills.js

@@ -0,0 +1,131 @@
+import { createHash, randomBytes } from "node:crypto";
+import { lstat, mkdir, readdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { CliError, exitCodes, readCredentials, resolveApiUrl, UnreadableCredentialsError } from "./api.js";
+import { envPrefix } from "./brand.js";
+import { firstSymlink, inRunFolder } from "./files.js";
+import { readSkillZip, refuseOversizedFiles, refuseOversizedZip, refuseTooManyFiles, SKILL_NAME_PATTERN, SkillZipError, zipSkillFiles, } from "./skill-zip.js";
+export const OPERATOR_TOKEN_ENV = `${envPrefix}_OPERATOR_TOKEN`;
+// Env files hold secrets, and a published skill reaches every workspace.
+const skipped = (entry) => [".git", "node_modules", ".DS_Store", ".env", ".envrc"].includes(entry) || entry.startsWith(".env.");
+/** Operator commands (the skill library, promoting and dropping a worker's candidate) take the operator token, never the workspace API key. */
+export async function operatorConnection(apiUrlFlag) {
+    const token = process.env[OPERATOR_TOKEN_ENV];
+    if (!token)
+        throw new CliError(`Set ${OPERATOR_TOKEN_ENV} to the server's OPERATOR_TOKEN for operator commands.`, exitCodes.auth);
+    const stored = await readCredentials().catch((error) => {
+        if (error instanceof UnreadableCredentialsError)
+            return null;
+        throw error;
+    });
+    const apiUrl = resolveApiUrl(apiUrlFlag, stored);
+    return { apiUrl, apiKey: token, rejected: `The operator token in ${OPERATOR_TOKEN_ENV} was rejected by ${apiUrl}.` };
+}
+/** `my-skill` or `my-skill@3`; a null version means the latest published one. */
+export function parseSkillRef(ref) {
+    const match = /^([^@]+)(?:@([1-9]\d{0,8}))?$/.exec(ref);
+    if (!match || !SKILL_NAME_PATTERN.test(match[1])) {
+        throw new CliError(`'${ref}' is not a skill: use <name> or <name>@<version>, where the name is lowercase letters, digits and dashes.`, exitCodes.usage);
+    }
+    return { name: match[1], version: match[2] === undefined ? null : Number(match[2]) };
+}
+/**
+ * Every file under `dir`, refusing symlinks and skipping .git, node_modules, .DS_Store and env files (.env, .env.*,
+ * .envrc). The file count and sizes are checked before any file is read.
+ */
+export async function readSkillFolder(dir) {
+    const found = [];
+    let bytes = 0;
+    await inRunFolder(dir);
+    async function walk(relative) {
+        const entries = (await readdir(join(dir, ...relative))).filter((e) => !skipped(e)).sort();
+        for (const entry of entries) {
+            const name = [...relative, entry].join("/");
+            const path = join(dir, ...relative, entry);
+            const info = await lstat(path);
+            if (info.isSymbolicLink())
+                throw new CliError(`refused: symlink at ${name}`, exitCodes.error);
+            if (info.isDirectory())
+                await walk([...relative, entry]);
+            else if (info.isFile()) {
+                found.push({ name, path, executable: (info.mode & 0o111) !== 0 });
+                bytes += info.size;
+                checked(() => {
+                    refuseTooManyFiles(found.length);
+                    refuseOversizedFiles(bytes);
+                });
+            }
+            else
+                throw new CliError(`refused: ${name} is not a regular file`, exitCodes.error);
+        }
+    }
+    await walk([]);
+    return Promise.all(found.map(async (f) => ({ name: f.name, data: await readFile(f.path), executable: f.executable })));
+}
+/** Zips the files and checks them the way the server will, so a refusal comes before anything is sent. */
+export function packSkill(name, files) {
+    return checked(() => {
+        const zip = zipSkillFiles(files);
+        refuseOversizedZip(zip.byteLength);
+        readSkillZip(zip, name);
+        return zip;
+    });
+}
+/** The files of a downloaded version, once its bytes match the SHA-256 the server recorded at publish. */
+export function unpackSkill(download, zip) {
+    if (createHash("sha256").update(zip).digest("hex") !== download.sha256) {
+        throw new CliError(`The download of ${download.name} version ${download.version} does not match its recorded sha256. Nothing was installed.`, exitCodes.error);
+    }
+    return checked(() => readSkillZip(zip, download.name).files);
+}
+function checked(run) {
+    try {
+        return run();
+    }
+    catch (error) {
+        if (error instanceof SkillZipError)
+            throw new CliError(error.message, exitCodes.error);
+        throw error;
+    }
+}
+/**
+ * Makes <skillsDir>/<name> hold exactly `files`: they are written to a sibling folder first, which then takes the old
+ * folder's place, so no file from an earlier version survives. Refuses to follow a symlink at any of `above` or the
+ * skill's own folder.
+ */
+export async function installSkillFolder(skillsDir, name, files, above) {
+    const target = await inRunFolder(join(skillsDir, name));
+    const linked = await firstSymlink([...above, target]);
+    if (linked)
+        throw new CliError(`Refusing to write through the symlink at ${linked}. Remove it and try again.`, exitCodes.error);
+    const suffix = randomBytes(6).toString("hex");
+    const staged = join(skillsDir, `.${name}.${suffix}.new`);
+    const old = join(skillsDir, `.${name}.${suffix}.old`);
+    await mkdir(staged, { recursive: true });
+    try {
+        for (const file of files) {
+            const path = join(staged, ...file.name.split("/"));
+            await mkdir(dirname(path), { recursive: true });
+            await writeFile(path, file.data, { flag: "wx", mode: file.executable ? 0o755 : 0o644 });
+        }
+        const replacing = await rename(target, old).then(() => true, (error) => {
+            if (error.code === "ENOENT")
+                return false;
+            throw error;
+        });
+        try {
+            await rename(staged, target);
+        }
+        catch (error) {
+            if (replacing)
+                await rename(old, target);
+            throw error;
+        }
+        if (replacing)
+            await rm(old, { recursive: true, force: true });
+    }
+    finally {
+        await rm(staged, { recursive: true, force: true });
+    }
+    return target;
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@wrangled/cli",
+  "version": "0.2.0",
+  "description": "Command-line access to your marketing data warehouse, for people and coding agents",
+  "type": "module",
+  "bin": {
+    "wr": "dist/main.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bdavis905/wrangled.git",
+    "directory": "cli"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsc -p ."
+  },
+  "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.3.288",
+    "fflate": "^0.8.3"
+  },
+  "devDependencies": {
+    "@types/node": "^24",
+    "typescript": "^6.0.3"
+  }
+}