@masculinecache/warp-axi 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 masculinecache
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,46 @@
-# Temporary Holding Version
+# @masculinecache/warp-axi
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Agent-ergonomic TOON wrapper for the Cloudflare WARP CLI (`warp-cli`).
+
+## Install
+
+```bash
+npm install -g @masculinecache/warp-axi
+```
+
+## Usage
+
+```bash
+warp-axi status                    # Connection status
+warp-axi status --detail           # Detailed status with account info
+warp-axi connect                   # Connect to WARP
+warp-axi disconnect                # Disconnect from WARP
+warp-axi registration show         # Show registration state
+warp-axi registration new --org X  # Register with organization
+warp-axi tunnel dump               # Split tunnel routes
+warp-axi tunnel stats              # Tunnel statistics
+warp-axi settings                  # Client settings
+warp-axi debug network             # Network diagnostics
+warp-axi vnet list                 # Virtual networks
+warp-axi target list               # Infrastructure targets
+```
+
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | General error |
+| 2 | WARP not installed |
+
+## MDM headless enrollment
+
+```bash
+warp-axi registration new --org <team> --token <service-token>
+```
+
+Service tokens are created in Zero Trust → Settings → Devices → Service Tokens.
+
+## License
+
+MIT

package/dist/bin/warp-axi.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/warp-axi.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+import { run } from "../src/cli.js";
+import { exitCodeForError } from "../src/errors.js";
+const argv = process.argv.slice(2);
+const cwd = process.cwd();
+run(argv, undefined, cwd)
+    .then(({ stdout, exitCode }) => {
+    if (stdout)
+        process.stdout.write(stdout + "\n");
+    process.exitCode = exitCode;
+})
+    .catch((err) => {
+    const message = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`warp-axi: ${message}\n`);
+    process.exitCode = exitCodeForError(err);
+});

package/dist/src/args.d.ts

@@ -0,0 +1,6 @@
+export declare function takeFlag(args: string[], flag: string): string | undefined;
+export declare function takeBoolFlag(args: string[], flag: string): boolean;
+export declare function takeAllFlags(args: string[], flags: string[]): string[];
+export declare function hasFlag(args: string[], flag: string): boolean;
+export declare function getFlag(args: string[], name: string): string | undefined;
+export declare function getPositional(args: string[], startIdx: number): string | undefined;

package/dist/src/args.js

@@ -0,0 +1,56 @@
+export function takeFlag(args, flag) {
+    const eqFlag = `--${flag}=`;
+    const idx = args.findIndex((a) => a === `--${flag}` || a.startsWith(eqFlag));
+    if (idx === -1)
+        return undefined;
+    const arg = args[idx];
+    if (arg.startsWith(eqFlag)) {
+        args.splice(idx, 1);
+        return arg.slice(eqFlag.length);
+    }
+    const value = args[idx + 1];
+    if (value === undefined || value.startsWith("--")) {
+        args.splice(idx, 1);
+        return "";
+    }
+    args.splice(idx, 2);
+    return value;
+}
+export function takeBoolFlag(args, flag) {
+    const idx = args.indexOf(`--${flag}`);
+    if (idx === -1)
+        return false;
+    args.splice(idx, 1);
+    return true;
+}
+export function takeAllFlags(args, flags) {
+    const taken = [];
+    for (const flag of flags) {
+        const idx = args.indexOf(`--${flag}`);
+        if (idx !== -1) {
+            taken.push(flag);
+            args.splice(idx, 1);
+        }
+    }
+    return taken;
+}
+export function hasFlag(args, flag) {
+    return args.includes(`--${flag}`);
+}
+export function getFlag(args, name) {
+    const eqFlag = `--${name}=`;
+    const idx = args.findIndex((a) => a === `--${name}` || a.startsWith(eqFlag));
+    if (idx === -1)
+        return undefined;
+    const arg = args[idx];
+    if (arg.startsWith(eqFlag))
+        return arg.slice(eqFlag.length);
+    return args[idx + 1];
+}
+export function getPositional(args, startIdx) {
+    for (let i = startIdx; i < args.length; i++) {
+        if (!args[i].startsWith("--"))
+            return args[i];
+    }
+    return undefined;
+}

package/dist/src/cli.d.ts

@@ -0,0 +1,22 @@
+import { WarpRunner, callWarp, callWarpLenient } from "./warp.js";
+import { AxiError, exitCodeForError } from "./errors.js";
+export interface CommandContext {
+    runner: WarpRunner;
+    cwd?: string;
+}
+export interface CommandArea {
+    name: string;
+    aliases?: string[];
+    description: string;
+    help: string[];
+    run(ctx: CommandContext, args: string[]): Promise<{
+        stdout: string;
+        exitCode: number;
+    }>;
+}
+declare const areas: CommandArea[];
+export declare function run(argv: string[], runner?: WarpRunner, cwd?: string): Promise<{
+    stdout: string;
+    exitCode: number;
+}>;
+export { areas, AxiError, exitCodeForError, callWarp, callWarpLenient };

package/dist/src/cli.js

@@ -0,0 +1,68 @@
+import { realRunner, callWarp, callWarpLenient } from "./warp.js";
+import { AxiError, exitCodeForError } from "./errors.js";
+import { wantsHelp } from "./util.js";
+import { readPackageVersion } from "./version.js";
+import { statusArea } from "./commands/status.js";
+import { registrationArea } from "./commands/registration.js";
+import { connectArea, disconnectArea } from "./commands/connect.js";
+import { tunnelArea } from "./commands/tunnel.js";
+import { settingsArea } from "./commands/settings.js";
+import { debugArea } from "./commands/debug.js";
+import { vnetArea } from "./commands/vnet.js";
+import { targetArea } from "./commands/target.js";
+const areas = [
+    statusArea,
+    registrationArea,
+    connectArea,
+    disconnectArea,
+    tunnelArea,
+    settingsArea,
+    debugArea,
+    vnetArea,
+    targetArea,
+];
+function resolveArea(name) {
+    return areas.find((a) => a.name === name || (a.aliases && a.aliases.includes(name)));
+}
+function renderTopLevelHelp() {
+    const lines = [
+        `bin: warp-axi`,
+        `description: Agent-ergonomic wrapper for Cloudflare WARP CLI (warp-cli)`,
+        ``,
+    ];
+    areas.forEach((a, i) => {
+        lines.push(`help[${i}]:`);
+        lines.push(`  ${a.name.padEnd(14)}${a.description}`);
+    });
+    lines.push(``, `help[${areas.length}]:`, `  --help          Show this help`, `  --version       Show version`);
+    return lines.join("\n");
+}
+export async function run(argv, runner, cwd) {
+    const ctx = { runner: runner ?? realRunner(), cwd };
+    if (argv.length === 0) {
+        return { stdout: renderTopLevelHelp(), exitCode: 0 };
+    }
+    if (argv.length === 1 && wantsHelp(argv)) {
+        return { stdout: renderTopLevelHelp(), exitCode: 0 };
+    }
+    const [first, ...rest] = argv;
+    if (first === "--version" || first === "-V") {
+        const version = await readPackageVersion();
+        return { stdout: version, exitCode: 0 };
+    }
+    const area = resolveArea(first);
+    if (!area) {
+        return {
+            stdout: `warp-axi: unknown command '${first}'. Run 'warp-axi --help' for available commands.`,
+            exitCode: 1,
+        };
+    }
+    if (rest.length > 0 && wantsHelp(rest)) {
+        return {
+            stdout: [`bin: warp-axi ${area.name}`, `description: ${area.description}`, ``, ...area.help].join("\n"),
+            exitCode: 0,
+        };
+    }
+    return area.run(ctx, rest);
+}
+export { areas, AxiError, exitCodeForError, callWarp, callWarpLenient };

package/dist/src/commands/connect.d.ts

@@ -0,0 +1,3 @@
+import { type CommandArea } from "../cli.js";
+export declare const connectArea: CommandArea;
+export declare const disconnectArea: CommandArea;

package/dist/src/commands/connect.js

@@ -0,0 +1,50 @@
+import { callWarp } from "../warp.js";
+import { takeBoolFlag } from "../args.js";
+import { wantsHelp, validateFlags } from "../util.js";
+import { renderDetail, renderHelp, field, custom } from "../toon.js";
+const CONN_SCHEMA = {
+    status: field("status"),
+    protocol: field("protocol"),
+    clientIp: custom((item) => {
+        const ip = item.warp_enabled ?? item.client_ip;
+        return ip ? String(ip) : undefined;
+    }),
+    serverIp: custom((item) => {
+        const ip = item.server_ip ?? item.endpoint;
+        return ip ? String(ip) : undefined;
+    }),
+};
+export const connectArea = {
+    name: "connect",
+    description: "Connect to WARP",
+    help: [
+        "usage: warp-axi connect [--json]",
+        "",
+        "Establish a WARP connection.",
+    ],
+    async run(ctx, args) {
+        if (wantsHelp(args))
+            return { stdout: renderHelp(this.help), exitCode: 0 };
+        const useJson = takeBoolFlag(args, "--json");
+        validateFlags(args, ["--json"], "connect");
+        await callWarp(ctx.runner, ["connect"]);
+        return { stdout: renderDetail("connect", { status: "connecting" }, CONN_SCHEMA), exitCode: 0 };
+    },
+};
+export const disconnectArea = {
+    name: "disconnect",
+    description: "Disconnect from WARP",
+    help: [
+        "usage: warp-axi disconnect [--json]",
+        "",
+        "Disconnect the WARP connection.",
+    ],
+    async run(ctx, args) {
+        if (wantsHelp(args))
+            return { stdout: renderHelp(this.help), exitCode: 0 };
+        const useJson = takeBoolFlag(args, "--json");
+        validateFlags(args, ["--json"], "disconnect");
+        await callWarp(ctx.runner, ["disconnect"]);
+        return { stdout: renderDetail("disconnect", { status: "disconnected" }, CONN_SCHEMA), exitCode: 0 };
+    },
+};

package/dist/src/commands/debug.d.ts

@@ -0,0 +1,2 @@
+import { CommandArea } from "../cli.js";
+export declare const debugArea: CommandArea;

package/dist/src/commands/debug.js

@@ -0,0 +1,83 @@
+import { callWarpLenient } from "../warp.js";
+import { hasFlag } from "../args.js";
+import { renderDetail, renderError, renderOutput, field } from "../toon.js";
+const debugSubcommands = ["network", "posture", "connectivity-check"];
+const networkSchema = {
+    status: field("status"),
+    local_ip: field("local_ip"),
+    gateway_ip: field("gateway_ip"),
+    dns_server: field("dns_server"),
+    interface: field("interface"),
+};
+const postureSchema = {
+    status: field("status"),
+    compliance_state: field("compliance_state"),
+    serial_number: field("serial_number"),
+    device_id: field("device_id"),
+};
+const connectivitySchema = {
+    result: field("result"),
+    summary: field("summary"),
+};
+const fallbackSchema = {
+    status: field("status"),
+};
+function renderDebugHelp() {
+    return [
+        "usage: warp-axi debug <subcommand> [flags]",
+        "",
+        "Subcommands:",
+        "  network              Network debug info",
+        "  posture              Device posture state",
+        "  connectivity-check   Test connectivity to Cloudflare",
+        "",
+        "Flags:",
+        "  --json               Raw JSON output",
+        "  --help               Show this help",
+    ];
+}
+export const debugArea = {
+    name: "debug",
+    description: "Network, posture, and connectivity diagnostics",
+    help: renderDebugHelp(),
+    async run(ctx, args) {
+        if (args.length === 0) {
+            return { stdout: renderDebugHelp().join("\n"), exitCode: 0 };
+        }
+        const [sub, ...rest] = args;
+        if (!debugSubcommands.includes(sub)) {
+            return {
+                stdout: renderError(`unknown debug subcommand '${sub}'`, "VALIDATION_ERROR", [
+                    `Available: ${debugSubcommands.join(", ")}`,
+                ]),
+                exitCode: 1,
+            };
+        }
+        const useJson = hasFlag(rest, "--json");
+        const warpArgs = ["debug", sub];
+        if (useJson)
+            warpArgs.push("--json");
+        try {
+            const result = await callWarpLenient(ctx.runner, warpArgs);
+            if (useJson) {
+                return { stdout: result.stdout.trim(), exitCode: 0 };
+            }
+            let schema = fallbackSchema;
+            if (sub === "network")
+                schema = networkSchema;
+            else if (sub === "posture")
+                schema = postureSchema;
+            else if (sub === "connectivity-check")
+                schema = connectivitySchema;
+            const label = `debug-${sub}`;
+            return {
+                stdout: renderOutput([renderDetail(label, { status: result.stdout.trim() }, schema)]),
+                exitCode: 0,
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return { stdout: renderError(message, "UNKNOWN"), exitCode: 1 };
+        }
+    },
+};

package/dist/src/commands/registration.d.ts

@@ -0,0 +1,2 @@
+import { type CommandArea } from "../cli.js";
+export declare const registrationArea: CommandArea;

package/dist/src/commands/registration.js

@@ -0,0 +1,111 @@
+import { callWarp, callWarpLenient } from "../warp.js";
+import { takeFlag, takeBoolFlag } from "../args.js";
+import { wantsHelp, validateFlags } from "../util.js";
+import { renderDetail, renderHelp, renderError } from "../toon.js";
+import { field, custom } from "../toon.js";
+const REG_SCHEMA = {
+    organization: custom((item) => {
+        const org = item.organization;
+        return org ? String(org) : "(none)";
+    }),
+    enrollmentType: field("type"),
+    deviceUid: field("uid"),
+    accountId: field("account_id"),
+    enabled: field("enabled"),
+};
+function parseRegJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return { raw: text.trim() };
+    }
+}
+export const registrationArea = {
+    name: "registration",
+    aliases: ["reg"],
+    description: "Show, create, or delete WARP Zero Trust registration",
+    help: [
+        "Usage: warp-axi registration <subcommand> [options]",
+        "",
+        "Subcommands:",
+        "  show        Show current registration details",
+        "  new         Register with a Zero Trust organization",
+        "  delete      Delete current registration",
+        "",
+        "new flags:",
+        "  --org <name>     Organization name (required)",
+        "  --token <token>  MDM service token for headless enrollment",
+        "  --json           Use structured output",
+    ],
+    async run(ctx, args) {
+        if (wantsHelp(args))
+            return { stdout: renderHelp(this.help), exitCode: 0 };
+        const sub = args.shift();
+        switch (sub) {
+            case "show":
+                return regShow(ctx, args);
+            case "new":
+                return regNew(ctx, args);
+            case "delete":
+                return regDelete(ctx, args);
+            default:
+                return { stdout: renderHelp(this.help), exitCode: 0 };
+        }
+    },
+};
+async function regShow(ctx, args) {
+    const useJson = takeBoolFlag(args, "--json");
+    validateFlags(args, ["--json"], "registration show");
+    const warpArgs = ["registration", "show"];
+    if (useJson)
+        warpArgs.push("--json");
+    const result = await callWarpLenient(ctx.runner, warpArgs);
+    if (result.exitCode !== 0 && !result.stdout) {
+        return {
+            stdout: renderDetail("registration", { status: "not registered" }, REG_SCHEMA),
+            exitCode: 0,
+        };
+    }
+    const parsed = useJson ? parseRegJson(result.stdout) : parseRegText(result.stdout);
+    return { stdout: renderDetail("registration", parsed, REG_SCHEMA), exitCode: 0 };
+}
+async function regNew(ctx, args) {
+    const org = takeFlag(args, "org");
+    const token = takeFlag(args, "token");
+    const useJson = takeBoolFlag(args, "--json");
+    validateFlags(args, ["--org", "--token", "--json"], "registration new");
+    if (!org) {
+        return {
+            stdout: renderError("--org is required", "VALIDATION_ERROR", [
+                "Usage: warp-axi registration new --org <name>",
+                "Optionally add --token <mdm-token> for headless enrollment",
+            ]),
+            exitCode: 1,
+        };
+    }
+    const warpArgs = ["registration", "new", "--organization", org];
+    if (token) {
+        warpArgs.push("--service-token", token);
+    }
+    const result = await callWarp(ctx.runner, warpArgs);
+    return { stdout: renderDetail("registration", { status: "registered", organization: org }, REG_SCHEMA), exitCode: 0 };
+}
+async function regDelete(ctx, args) {
+    const useJson = takeBoolFlag(args, "--json");
+    validateFlags(args, ["--json"], "registration delete");
+    const warpArgs = ["registration", "delete"];
+    await callWarp(ctx.runner, warpArgs);
+    return { stdout: renderDetail("registration", { status: "deleted" }, REG_SCHEMA), exitCode: 0 };
+}
+function parseRegText(text) {
+    const result = {};
+    for (const line of text.split("\n")) {
+        const m = line.match(/^\s*(.+?):\s+(.+)$/);
+        if (m) {
+            const key = m[1].trim().toLowerCase().replace(/\s+/g, "_");
+            result[key] = m[2].trim();
+        }
+    }
+    return result;
+}

package/dist/src/commands/settings.d.ts

@@ -0,0 +1,2 @@
+import { type CommandArea } from "../cli.js";
+export declare const settingsArea: CommandArea;

package/dist/src/commands/settings.js

@@ -0,0 +1,65 @@
+import { callWarpLenient } from "../warp.js";
+import { takeBoolFlag } from "../args.js";
+import { wantsHelp, validateFlags } from "../util.js";
+import { renderDetail, renderHelp, field, custom } from "../toon.js";
+const SETTINGS_SCHEMA = {
+    mode: field("mode"),
+    excludeRoutes: custom((item) => {
+        const exclude = item.exclude_routes ?? item.exclude;
+        if (Array.isArray(exclude))
+            return exclude.join(", ");
+        return exclude ? String(exclude) : undefined;
+    }),
+    includeRoutes: custom((item) => {
+        const include = item.include_routes ?? item.include;
+        if (Array.isArray(include))
+            return include.join(", ");
+        return include ? String(include) : undefined;
+    }),
+    dns: field("dns"),
+    proxy: field("proxy"),
+};
+function parseSettingsJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return parseSettingsText(text);
+    }
+}
+function parseSettingsText(text) {
+    const result = {};
+    for (const line of text.split("\n")) {
+        const m = line.match(/^\s*(.+?):\s+(.+)$/);
+        if (m) {
+            const key = m[1].trim().toLowerCase().replace(/\s+/g, "_");
+            result[key] = m[2].trim();
+        }
+    }
+    return result;
+}
+export const settingsArea = {
+    name: "settings",
+    aliases: ["config"],
+    description: "Show WARP client settings and configuration",
+    help: [
+        "usage: warp-axi settings [--json]",
+        "",
+        "Show current WARP client settings.",
+        "",
+        "Flags:",
+        "  --json    Use warp-cli --json for structured output",
+    ],
+    async run(ctx, args) {
+        if (wantsHelp(args))
+            return { stdout: renderHelp(this.help), exitCode: 0 };
+        const useJson = takeBoolFlag(args, "--json");
+        validateFlags(args, ["--json"], "settings");
+        const warpArgs = ["settings"];
+        if (useJson)
+            warpArgs.push("--json");
+        const result = await callWarpLenient(ctx.runner, warpArgs);
+        const parsed = useJson ? parseSettingsJson(result.stdout) : parseSettingsText(result.stdout);
+        return { stdout: renderDetail("settings", parsed, SETTINGS_SCHEMA), exitCode: 0 };
+    },
+};

package/dist/src/commands/status.d.ts

@@ -0,0 +1,2 @@
+import { type CommandArea } from "../cli.js";
+export declare const statusArea: CommandArea;

package/dist/src/commands/status.js

@@ -0,0 +1,89 @@
+import { callWarpLenient } from "../warp.js";
+import { takeBoolFlag } from "../args.js";
+import { wantsHelp, validateFlags } from "../util.js";
+import { renderDetail, renderHelp, field, custom } from "../toon.js";
+const STATUS_SCHEMA = {
+    status: field("status"),
+    registration: custom((item) => {
+        const raw = item.registration;
+        return raw ? "registered" : "unregistered";
+    }),
+    accountId: field("account_id"),
+};
+const STATUS_DETAIL_SCHEMA = {
+    status: field("status"),
+    organization: custom((item) => {
+        const raw = item.registration;
+        if (!raw)
+            return "unregistered";
+        return raw.organization ? String(raw.organization) : "registered";
+    }),
+    accountId: field("account_id"),
+    enrollmentType: custom((item) => {
+        const raw = item.registration;
+        if (!raw)
+            return undefined;
+        return raw.type ? String(raw.type) : undefined;
+    }),
+    deviceUid: custom((item) => {
+        const raw = item.registration;
+        if (!raw)
+            return undefined;
+        return raw.uid ? String(raw.uid) : undefined;
+    }),
+    protocol: field("protocol"),
+    vnet: field("vnet"),
+};
+function parseStatusJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return { status: text.trim() };
+    }
+}
+function parseStatusText(text) {
+    const result = {};
+    for (const line of text.split("\n")) {
+        const m = line.match(/^\s*(.+?):\s+(.+)$/);
+        if (m) {
+            const key = m[1].trim().toLowerCase().replace(/\s+/g, "_");
+            result[key] = m[2].trim();
+        }
+    }
+    if (!result.status) {
+        result.status = text.includes("Connected") ? "Connected" : text.includes("Disconnected") ? "Disconnected" : "Unknown";
+    }
+    return result;
+}
+export const statusArea = {
+    name: "status",
+    aliases: ["info"],
+    description: "Show WARP connection status and registration info",
+    help: [
+        "usage: warp-axi status [--json] [--detail]",
+        "",
+        "Show current WARP connection status.",
+        "",
+        "Flags:",
+        "  --json    Use warp-cli --json for structured output",
+        "  --detail  Show full registration details (org, device UID, protocol)",
+    ],
+    async run(ctx, args) {
+        if (wantsHelp(args))
+            return { stdout: renderHelp(this.help), exitCode: 0 };
+        const useJson = takeBoolFlag(args, "--json");
+        const detail = takeBoolFlag(args, "--detail");
+        validateFlags(args, ["--json", "--detail"], "status");
+        const warpArgs = ["status"];
+        if (useJson)
+            warpArgs.push("--json");
+        const result = await callWarpLenient(ctx.runner, warpArgs);
+        const parsed = useJson
+            ? parseStatusJson(result.stdout)
+            : parseStatusText(result.stdout);
+        const schema = detail ? STATUS_DETAIL_SCHEMA : STATUS_SCHEMA;
+        const output = renderDetail("status", parsed, schema);
+        return { stdout: output, exitCode: 0 };
+    },
+};

package/dist/src/commands/target.d.ts

@@ -0,0 +1,2 @@
+import { CommandArea } from "../cli.js";
+export declare const targetArea: CommandArea;