@masculinecache/wrangler-axi 0.1.0

package/dist/src/toon.d.ts

@@ -0,0 +1,30 @@
+import { encode } from "@toon-format/toon";
+export { encode };
+export interface FieldDef {
+    render: (item: any) => any;
+    as?: string;
+}
+/** Schema maps an output key to a renderer. Item is passed as `any`. */
+export interface Schema {
+    [outputKey: string]: FieldDef;
+}
+/** Simple field extracted directly from the item, optionally renamed. */
+export declare function field(key: string, as?: string): FieldDef;
+/** Nested field: item[key][subkey]. */
+export declare function pluck(key: string, subkey: string, as?: string): FieldDef;
+/** Join an array field into a comma-separated string (or empty string). */
+export declare function joinArray(key: string, subkey: string, as?: string, empty?: string): FieldDef;
+/** ISO timestamp formatted as relative human time. */
+export declare function relativeTime(key: string, as?: string): FieldDef;
+export declare function boolYesNo(key: string, as?: string): FieldDef;
+export declare function mapEnum(key: string, map: Record<string, string>, fallback?: string, as?: string): FieldDef;
+export declare function lower(key: string, as?: string): FieldDef;
+export declare function checksSummary(key: string, as?: string): FieldDef;
+export declare function custom(fn: (item: any) => any, as?: string): FieldDef;
+/** Map an item through a schema into a plain object of outputKey -> rendered value. */
+export declare function extract(item: any, schema: Schema): Record<string, unknown>;
+export declare function renderList(label: string, items: unknown[], schema: Schema): string;
+export declare function renderDetail(label: string, item: unknown, schema: Schema): string;
+export declare function renderHelp(lines: string[]): string;
+export declare function renderError(message: string, code: string, suggestions?: string[]): string;
+export declare function renderOutput(blocks: Array<string | undefined>): string;

package/dist/src/toon.js

@@ -0,0 +1,159 @@
+import { encode } from "@toon-format/toon";
+export { encode };
+function formatRelativeTime(iso) {
+    if (!iso) {
+        return "unknown";
+    }
+    const then = new Date(iso).getTime();
+    if (Number.isNaN(then)) {
+        return "unknown";
+    }
+    const diffSec = Math.floor((Date.now() - then) / 1000);
+    if (diffSec < 60) {
+        return "just now";
+    }
+    const min = Math.floor(diffSec / 60);
+    if (min < 60) {
+        return `${min}m ago`;
+    }
+    const hour = Math.floor(min / 60);
+    if (hour < 24) {
+        return `${hour}h ago`;
+    }
+    const day = Math.floor(hour / 24);
+    if (day < 30) {
+        return `${day}d ago`;
+    }
+    const month = Math.floor(day / 30);
+    if (month < 12) {
+        return `${month}mo ago`;
+    }
+    return `${Math.floor(month / 12)}y ago`;
+}
+function rec(item) {
+    return (item ?? {});
+}
+/** Simple field extracted directly from the item, optionally renamed. */
+export function field(key, as) {
+    return {
+        render: (item) => rec(item)[key] ?? null,
+        ...(as ? { as } : {}),
+    };
+}
+/** Nested field: item[key][subkey]. */
+export function pluck(key, subkey, as) {
+    return {
+        render: (item) => {
+            const val = rec(item)[key];
+            if (val && typeof val === "object") {
+                return rec(val)[subkey] ?? null;
+            }
+            return null;
+        },
+        ...(as ? { as } : {}),
+    };
+}
+/** Join an array field into a comma-separated string (or empty string). */
+export function joinArray(key, subkey, as, empty = "none") {
+    return {
+        render: (item) => {
+            const val = rec(item)[key];
+            if (!Array.isArray(val) || val.length === 0) {
+                return empty;
+            }
+            return val
+                .map((x) => (typeof x === "string" ? x : rec(x)[subkey]))
+                .filter(Boolean)
+                .join(",");
+        },
+        ...(as ? { as } : {}),
+    };
+}
+/** ISO timestamp formatted as relative human time. */
+export function relativeTime(key, as) {
+    return {
+        render: (item) => {
+            const iso = rec(item)[key];
+            return typeof iso === "string" ? formatRelativeTime(iso) : "unknown";
+        },
+        ...(as ? { as } : {}),
+    };
+}
+export function boolYesNo(key, as) {
+    return {
+        render: (item) => (rec(item)[key] ? "yes" : "no"),
+        ...(as ? { as } : {}),
+    };
+}
+export function mapEnum(key, map, fallback, as) {
+    return {
+        render: (item) => {
+            const val = rec(item)[key];
+            const str = val == null ? undefined : String(val);
+            if (str !== undefined && Object.prototype.hasOwnProperty.call(map, str)) {
+                return map[str];
+            }
+            return fallback ?? str ?? "none";
+        },
+        ...(as ? { as } : {}),
+    };
+}
+export function lower(key, as) {
+    return {
+        render: (item) => {
+            const v = rec(item)[key];
+            return typeof v === "string" ? v.toLowerCase() : v ?? null;
+        },
+        ...(as ? { as } : {}),
+    };
+}
+export function checksSummary(key, as) {
+    return {
+        render: (item) => {
+            const checks = rec(item)[key];
+            if (!Array.isArray(checks)) {
+                return "none";
+            }
+            const passed = checks.filter((c) => rec(c).conclusion === "SUCCESS" ||
+                rec(c).conclusion === "NEUTRAL").length;
+            return `${passed}/${checks.length} pass`;
+        },
+        ...(as ? { as } : {}),
+    };
+}
+export function custom(fn, as) {
+    return {
+        render: fn,
+        ...(as ? { as } : {}),
+    };
+}
+/** Map an item through a schema into a plain object of outputKey -> rendered value. */
+export function extract(item, schema) {
+    const out = {};
+    for (const [label, def] of Object.entries(schema)) {
+        out[label] = def.render(item);
+    }
+    return out;
+}
+export function renderList(label, items, schema) {
+    return encode({ [label]: items.map((i) => extract(i, schema)) });
+}
+export function renderDetail(label, item, schema) {
+    return encode({ [label]: extract(item, schema) });
+}
+export function renderHelp(lines) {
+    if (lines.length === 0) {
+        return "";
+    }
+    return `help[${lines.length}]:\n${lines.map((l) => `  ${l}`).join("\n")}`;
+}
+export function renderError(message, code, suggestions = []) {
+    const err = encode({ error: message, code });
+    if (suggestions.length > 0) {
+        return `${err}\n${renderHelp(suggestions)}`;
+    }
+    return err;
+}
+export function renderOutput(blocks) {
+    return blocks.filter(Boolean).join("\n");
+}

package/dist/src/util.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Validate that every flag present in args is known. Positive short flags like
+ * `-J` are checked too. Unknown flags throw VALIDATION_ERROR listing the valid
+ * flags so the agent self-corrects in one turn.
+ */
+export declare function validateFlags(args: string[], valid: string[], commandName: string): void;
+/** True if args requests help explicitly (contains --help/-h). Empty args run with defaults. */
+export declare function wantsHelp(args: string[]): boolean;

package/dist/src/util.js

@@ -0,0 +1,26 @@
+import { AxiError } from "./errors.js";
+import { getAllFlags } from "./args.js";
+/** Global flags that are always allowed on any command. */
+const ALWAYS_ALLOWED = ["--help", "-h", "--account"];
+/**
+ * Validate that every flag present in args is known. Positive short flags like
+ * `-J` are checked too. Unknown flags throw VALIDATION_ERROR listing the valid
+ * flags so the agent self-corrects in one turn.
+ */
+export function validateFlags(args, valid, commandName) {
+    const allowed = [...new Set([...ALWAYS_ALLOWED, ...valid])];
+    const present = getAllFlags(args);
+    const unknown = present.filter((f) => !allowed.includes(f));
+    if (unknown.length > 0) {
+        throw new AxiError(`Unknown flag(s): ${unknown.join(", ")} for ${commandName}`, "VALIDATION_ERROR", [
+            `Valid flags for ${commandName}: ${allowed
+                .filter((f) => f !== "--help" && f !== "-h")
+                .join(", ")}`,
+            "Run `wrangler-axi --help` or add --help for usage",
+        ]);
+    }
+}
+/** True if args requests help explicitly (contains --help/-h). Empty args run with defaults. */
+export function wantsHelp(args) {
+    return args.includes("--help") || args.includes("-h");
+}

package/dist/src/version.d.ts

@@ -0,0 +1 @@
+export declare const VERSION: string;

package/dist/src/version.js

@@ -0,0 +1,23 @@
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+const here = dirname(fileURLToPath(import.meta.url));
+function readPackageVersion() {
+    const candidates = [
+        join(here, "..", "package.json"),
+        join(here, "..", "..", "package.json"),
+    ];
+    for (const path of candidates) {
+        try {
+            const pkg = JSON.parse(readFileSync(path, "utf8"));
+            if (pkg.version) {
+                return pkg.version;
+            }
+        }
+        catch {
+            // try next candidate
+        }
+    }
+    throw new Error("Could not resolve package version for wrangler-axi");
+}
+export const VERSION = readPackageVersion();

package/dist/src/wrangler.d.ts

@@ -0,0 +1,64 @@
+/** Result of a single wrangler invocation. */
+export interface WranglerResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}
+/** Options for a bounded `wrangler tail` session. */
+export interface TailRunOptions {
+    /** Full wrangler args (the command itself is `tail --format json ...`). */
+    args: string[];
+    /** Stop after this many log lines (0 = unbounded; a timeout is then required). */
+    maxEntries: number;
+    /** Stop the stream after this many milliseconds (0 = no timeout). */
+    timeoutMs: number;
+}
+/** Result of a bounded tail session. Entries are raw JSON lines from stdout. */
+export interface TailResult {
+    entries: string[];
+    stderr: string;
+    stoppedBy: "limit" | "timeout" | "exit";
+    exitCode: number;
+}
+/**
+ * A wrangler runner. Production uses the real CLI via execFile/spawn; tests
+ * inject a fake runner so no live API/shell calls happen.
+ */
+export interface WranglerRunner {
+    run(args: string[], options?: {
+        input?: string;
+    }): Promise<WranglerResult>;
+    /**
+     * Stream `wrangler tail` output with a bound (line and/or time). Optional so
+     * minimal fake runners only need `run`; the tail command fails loudly (not
+     * silently degrading) if a runner does not implement it.
+     */
+    tail?(opts: TailRunOptions): Promise<TailResult>;
+}
+/**
+ * Execute a command against wrangler, mapping failures into structured
+ * AxiErrors (validated, then translated). Wranger writes human output to
+ * stdout; on non-zero exit the stderr is translated to a structured error.
+ */
+export declare function callWrangler(runner: WranglerRunner, args: string[], options?: {
+    input?: string;
+}): Promise<{
+    stdout: string;
+    exitCode: number;
+}>;
+/**
+ * Execute a command against wrangler without treating a non-zero exit as a
+ * failure — used where wrangler emits usable stdout yet still exits non-zero
+ * (e.g. `whoami --json` returns exit 1 with `{"loggedIn":false}` when logged
+ * out). The caller is responsible for interpreting the result.
+ */
+export declare function callWranglerLenient(runner: WranglerRunner, args: string[], options?: {
+    input?: string;
+}): Promise<{
+    stdout: string;
+    exitCode: number;
+}>;
+/** Parse a wrangler JSON output string, failing with a structured error. */
+export declare function parseJson<T>(stdout: string, what: string): T;
+/** Default production runner — always talks to the real wrangler. */
+export declare const realRunner: WranglerRunner;

package/dist/src/wrangler.js

@@ -0,0 +1,175 @@
+import { spawn } from "node:child_process";
+import { createInterface } from "node:readline";
+import { AxiError } from "./errors.js";
+import { mapWranglerError } from "./errors.js";
+import { wranglerNotInstalledError } from "./errors.js";
+/** Cap on captured stdout, mirroring execFile's maxBuffer contract. */
+const MAX_OUTPUT = 64 * 1024 * 1024;
+/**
+ * Run the real `wrangler` binary with the given args, capturing stdout/stderr.
+ * Uses spawn (not execFile) because stdin input must be written explicitly:
+ * async `execFile` silently ignores an `input` option and hangs the child.
+ * Throws a NO_SUCH_FILE error if wrangler isn't on PATH.
+ */
+async function runWrangler(args, options) {
+    return new Promise((resolve, reject) => {
+        let child;
+        try {
+            child = spawn("wrangler", args, { windowsHide: true });
+        }
+        catch (err) {
+            reject(err);
+            return;
+        }
+        let stdout = "";
+        let stderr = "";
+        let settled = false;
+        let overflow = false;
+        const finish = (exitCode) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            resolve({ stdout, stderr, exitCode });
+        };
+        child.on("error", (err) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            const e = err;
+            if (e.code === "ENOENT") {
+                reject(wranglerNotInstalledError());
+            }
+            else {
+                reject(err);
+            }
+        });
+        child.on("close", (code) => finish(overflow ? 1 : (code ?? 0)));
+        child.stdout?.on("data", (chunk) => {
+            stdout += String(chunk);
+            if (!overflow && stdout.length > MAX_OUTPUT) {
+                overflow = true;
+                stderr += "wrangler-axi: output exceeded 64 MiB and was truncated";
+                child.kill("SIGKILL");
+            }
+        });
+        child.stderr?.on("data", (chunk) => {
+            stderr += String(chunk);
+        });
+        // EPIPE is expected when wrangler exits before draining stdin (e.g. an
+        // auth error on `secret put`); the exit code already carries the failure.
+        child.stdin?.on("error", () => { });
+        if (options?.input !== undefined) {
+            child.stdin?.end(options.input);
+        }
+        else {
+            child.stdin?.end();
+        }
+    });
+}
+/**
+ * Execute a command against wrangler, mapping failures into structured
+ * AxiErrors (validated, then translated). Wranger writes human output to
+ * stdout; on non-zero exit the stderr is translated to a structured error.
+ */
+export async function callWrangler(runner, args, options) {
+    const result = await runner.run(args, options);
+    if (result.exitCode !== 0) {
+        throw mapWranglerError(result.stderr || result.stdout, result.exitCode);
+    }
+    return { stdout: result.stdout, exitCode: result.exitCode };
+}
+/**
+ * Execute a command against wrangler without treating a non-zero exit as a
+ * failure — used where wrangler emits usable stdout yet still exits non-zero
+ * (e.g. `whoami --json` returns exit 1 with `{"loggedIn":false}` when logged
+ * out). The caller is responsible for interpreting the result.
+ */
+export async function callWranglerLenient(runner, args, options) {
+    const result = await runner.run(args, options);
+    return { stdout: result.stdout, exitCode: result.exitCode };
+}
+/** Parse a wrangler JSON output string, failing with a structured error. */
+export function parseJson(stdout, what) {
+    try {
+        return JSON.parse(stdout);
+    }
+    catch {
+        throw new AxiError(`Could not parse ${what} from wrangler output`, "UNKNOWN", ["Run with --json to get machine-readable output"]);
+    }
+}
+/**
+ * Stream `wrangler tail --format json` and stop at the configured bound (max
+ * lines or timeout), then SIGTERM the child so the session ends like Ctrl+C.
+ * On entry, resolves with the captured raw lines and why the stream stopped.
+ */
+async function runTail(opts) {
+    return new Promise((resolve, reject) => {
+        let child;
+        try {
+            child = spawn("wrangler", opts.args, { windowsHide: true });
+        }
+        catch (err) {
+            reject(err);
+            return;
+        }
+        const entries = [];
+        let stderrBuf = "";
+        let settled = false;
+        let timer;
+        const finish = (stoppedBy, exitCode = 0) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            if (timer !== undefined) {
+                clearTimeout(timer);
+            }
+            if (!child.killed) {
+                try {
+                    child.kill("SIGTERM");
+                }
+                catch {
+                    // already gone
+                }
+            }
+            resolve({ entries, stderr: stderrBuf, stoppedBy, exitCode });
+        };
+        if (opts.timeoutMs > 0) {
+            timer = setTimeout(() => finish("timeout"), opts.timeoutMs);
+        }
+        child.on("error", (err) => {
+            const e = err;
+            if (e.code === "ENOENT") {
+                settled = true;
+                reject(wranglerNotInstalledError());
+            }
+            else {
+                settled = true;
+                reject(err);
+            }
+        });
+        child.on("close", (code) => {
+            finish("exit", code ?? 0);
+        });
+        child.stderr?.on("data", (chunk) => {
+            stderrBuf += String(chunk);
+        });
+        if (child.stdout) {
+            const rl = createInterface({ input: child.stdout });
+            rl.on("line", (line) => {
+                const trimmed = line.replace(/\s+$/, "");
+                if (!trimmed) {
+                    return;
+                }
+                entries.push(trimmed);
+                if (opts.maxEntries > 0 && entries.length >= opts.maxEntries) {
+                    finish("limit");
+                }
+            });
+        }
+    });
+}
+/** Default production runner — always talks to the real wrangler. */
+export const realRunner = { run: runWrangler, tail: runTail };

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@masculinecache/wrangler-axi",
+  "version": "0.1.0",
+  "description": "Agent-ergonomic TOON wrapper around Cloudflare Wrangler 4.x",
+  "type": "module",
+  "bin": {
+    "wrangler-axi": "dist/bin/wrangler-axi.js"
+  },
+  "files": [
+    "dist",
+    "!dist/test",
+    "skills/wrangler-axi",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "dev": "tsx bin/wrangler-axi.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/masculinecache/wrangler-axi.git"
+  },
+  "homepage": "https://github.com/masculinecache/wrangler-axi#readme",
+  "bugs": {
+    "url": "https://github.com/masculinecache/wrangler-axi/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@toon-format/toon": "^2.1.0",
+    "axi-sdk-js": "^0.1.10"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  }
+}

package/skills/wrangler-axi/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: wrangler-axi
+description: Run Cloudflare Wrangler operations through the wrangler-axi TOON wrapper when you need worker deploys, secrets, KV/D1/R2, Pages, or account identity. Use whenever the task touches wrangler, workers, Cloudflare secrets, KV namespaces, D1 databases, R2 buckets, or Pages projects.
+---
+
+# wrangler-axi
+
+Agent-ergonomic TOON wrapper around Cloudflare Wrangler 4.x. Outputs compact TOON on stdout (no JSON parsing needed), with definitive empty states, aggregate counts, and structured errors with actionable suggestions.
+
+## Invocation
+
+If the `wrangler-axi` binary is on PATH, run it directly:
+
+```sh
+wrangler-axi <area> <sub> [args]
+```
+
+Otherwise invoke without a global install:
+
+```sh
+npx -y wrangler-axi <area> <sub> [args]
+```
+
+Run with no args for the home view; run `wrangler-axi --help` for the full area list.
+
+## Global flags
+
+- `--help` / `-h` — show help (always allowed on every command)
+- `--version` / `-v` — print version
+- `--account <id|name>` — select the Cloudflare account
+
+Every list supports `--fields <a,b,c>` and `--limit <n>`.
+
+## Commands
+
+```sh
+npx -y wrangler-axi whoami                                         # identity / auth state
+npx -y wrangler-axi secrets list [--name <worker>]                 # worker secrets
+npx -y wrangler-axi secrets put <key> --name <worker>              # value from stdin
+npx -y wrangler-axi secrets delete <key> --name <worker>
+
+npx -y wrangler-axi kv namespace list
+npx -y wrangler-axi kv key list --namespace-id <id> [--prefix <p>]
+npx -y wrangler-axi kv key get <key> --namespace-id <id> [--text]
+npx -y wrangler-axi kv key put <key> <value> --namespace-id <id>
+
+npx -y wrangler-axi d1 databases list
+npx -y wrangler-axi d1 query <db> --command "SELECT 1" [--remote]
+
+npx -y wrangler-axi r2 bucket list
+npx -y wrangler-axi r2 bucket info <name>
+
+npx -y wrangler-axi pages project list
+npx -y wrangler-axi pages deployment list --project-name <name>
+
+npx -y wrangler-axi workers deploy [path] [--name <worker>]
+npx -y wrangler-axi workers versions list [--name <worker>]
+npx -y wrangler-axi workers deployments list [--name <worker>]
+npx -y wrangler-axi workers tail [worker] [--max-entries <n>] [--timeout <sec>] [--search <text>] [--status error]
+```
+
+## Exit codes
+
+- `0` success (including no-ops / empty results)
+- `1` runtime error (not authenticated, not found)
+- `2` usage error (unknown flag, missing required flag)
+
+Errors go to stdout in TOON with a suggestion; unknown flags fail loudly and list the valid flags so you can
+self-correct in one step. `--help` is always allowed. No command prompts interactively.
+
+## Installation
+
+```sh
+npm install -g @masculinecache/wrangler-axi
+```
+
+Requires Node.js >= 20 and `wrangler` on PATH (`npm install -g wrangler`).
+
+## Integrations
+
+This skill is one of two complementary install paths (see the README). A session hook for Claude Code / Codex /
+OpenCode injects live account state at session start instead. Install whichever fits; you only need one.