@cardelli/ambit 0.1.5 → 0.2.0

package/esm/cli/commands/create/index.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.d.ts.map

package/esm/cli/commands/create/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/create/index.ts"],"names":[],"mappings":""}

package/esm/cli/commands/create/index.js

@@ -0,0 +1,292 @@
+// =============================================================================
+// Create Command - Create Tailscale Subnet Router on Fly.io Custom Network
+// =============================================================================
+import { parseArgs } from "../../../deps/jsr.io/@std/cli/1.0.28/mod.js";
+import { bold, readSecret } from "../../../lib/cli.js";
+import { checkArgs } from "../../../lib/args.js";
+import { createOutput } from "../../../lib/output.js";
+import { runMachine } from "../../../lib/machine.js";
+import { registerCommand } from "../../mod.js";
+import { getRouterTag } from "../../../util/naming.js";
+import { isPublicTld } from "../../../util/guard.js";
+import { createFlyProvider, } from "../../../providers/fly.js";
+import { createTailscaleProvider, } from "../../../providers/tailscale.js";
+import { getCredentialStore } from "../../../util/credentials.js";
+import { FLY_PRIVATE_SUBNET, SOCKS_PROXY_PORT, TAILSCALE_API_KEY_PREFIX, } from "../../../util/constants.js";
+import { resolveOrg } from "../../../util/resolve.js";
+import { isAutoApproverConfigured, isTagOwnerConfigured } from "../../../util/tailscale-local.js";
+import { createTransition, hydrateCreate, reportSkipped, } from "./machine.js";
+// =============================================================================
+// Stage 1: Fly.io Configuration
+// =============================================================================
+const stageFlyConfig = async (out, opts) => {
+    out.header("Step 1: Fly.io Configuration").blank();
+    const fly = createFlyProvider();
+    await fly.auth.ensureInstalled();
+    const email = await fly.auth.login({ interactive: !opts.json });
+    out.ok(`Authenticated as ${email}`);
+    const org = await resolveOrg(fly, opts, out);
+    const region = opts.region || "iad";
+    out.ok(`Using Region: ${region}`);
+    out.blank();
+    return { fly, org, region };
+};
+// =============================================================================
+// Stage 2: Tailscale Configuration
+// =============================================================================
+const stageTailscaleConfig = async (out, opts) => {
+    out.header("Step 2: Tailscale Configuration").blank();
+    const credentials = getCredentialStore();
+    let apiKey = opts.apiKey || (await credentials.getTailscaleApiKey());
+    if (!apiKey) {
+        if (opts.json) {
+            return out.die("--api-key Is Required in JSON Mode");
+        }
+        out.dim("Ambit Needs an API Access Token (Not an Auth Key) to Manage Your Tailnet.")
+            .dim("Create One at: https://login.tailscale.com/admin/settings/keys")
+            .blank();
+        apiKey = await readSecret("API access token (tskey-api-...): ");
+        if (!apiKey) {
+            return out.die("Tailscale API Access Token Required");
+        }
+    }
+    if (!apiKey.startsWith(TAILSCALE_API_KEY_PREFIX)) {
+        return out.die("Invalid Token Format. Expected 'tskey-api-...' (API Access Token, Not Auth Key)");
+    }
+    const tailscale = createTailscaleProvider(apiKey);
+    const validateSpinner = out.spinner("Validating API Access Token");
+    const isValid = await tailscale.auth.validateKey();
+    if (!isValid) {
+        validateSpinner.fail("Invalid API Access Token");
+        return out.die("Failed to Validate Tailscale API Access Token");
+    }
+    validateSpinner.success("API Access Token Validated");
+    await credentials.setTailscaleApiKey(apiKey);
+    const tagOwnerSpinner = out.spinner(`Checking tagOwners for ${opts.tag}`);
+    const policy = await tailscale.acl.getPolicy();
+    const hasTagOwner = isTagOwnerConfigured(policy, opts.tag);
+    if (!hasTagOwner) {
+        tagOwnerSpinner.fail(`Tag ${opts.tag} Not Configured in tagOwners`);
+        out.blank()
+            .text(`  The Tag ${opts.tag} Does Not Exist in Your Tailscale ACL tagOwners.`)
+            .text("  Tailscale Will Reject Auth Keys for Undefined Tags.")
+            .blank()
+            .text("  Add This Tag in Your Tailscale ACL Settings:")
+            .dim("  https://login.tailscale.com/admin/acls/visual/tags")
+            .blank()
+            .dim(`    "tagOwners": { "${opts.tag}": ["autogroup:admin"] }`)
+            .blank();
+        return out.die(`Add ${opts.tag} to tagOwners Before Creating Router`);
+    }
+    tagOwnerSpinner.success(`Tag ${opts.tag} Configured in tagOwners`);
+    if (opts.json) {
+        const approverSpinner = out.spinner(`Checking autoApprovers for ${opts.tag}`);
+        const hasApprover = isAutoApproverConfigured(policy, opts.tag);
+        if (!hasApprover) {
+            approverSpinner.fail(`autoApprovers Not Configured for ${opts.tag}`);
+            out.blank()
+                .text("  JSON mode skips interactive route approval.")
+                .text(`  Configure autoApprovers for ${opts.tag} so routes are approved on deploy.`)
+                .blank()
+                .dim("  Add to your ACL at: https://login.tailscale.com/admin/acls/file")
+                .blank()
+                .dim(`    "autoApprovers": { "routes": { "${FLY_PRIVATE_SUBNET}": ["${opts.tag}"] } }`)
+                .blank();
+            return out.die(`Configure autoApprovers for ${opts.tag} Before Using --json`);
+        }
+        approverSpinner.success(`autoApprovers Configured for ${opts.tag}`);
+    }
+    out.blank();
+    return tailscale;
+};
+// =============================================================================
+// Stage 3: Deploy Subnet Router
+// =============================================================================
+const stageDeploy = async (out, fly, tailscale, opts) => {
+    out.header("Step 3: Deploy Subnet Router").blank();
+    const ctx = {
+        fly,
+        tailscale,
+        out,
+        ...opts,
+        appName: "",
+        routerId: "",
+    };
+    const phase = await hydrateCreate(ctx);
+    if (phase === "complete") {
+        out.ok(`Network "${opts.network}" Already Fully Created`);
+        out.done({
+            network: opts.network,
+            router: {
+                appName: ctx.appName,
+                tailscaleIp: ctx.device?.addresses[0] ?? null,
+            },
+            subnet: ctx.subnet ?? null,
+            tag: opts.tag,
+        });
+        out.print();
+        return;
+    }
+    reportSkipped(out, phase);
+    const machine = {
+        terminal: "complete",
+        transition: createTransition,
+    };
+    const result = await runMachine(machine, phase, ctx);
+    if (!result.ok)
+        return out.die(result.error);
+    stageSummary(out, fly, tailscale, ctx, opts);
+};
+// =============================================================================
+// Stage 4: Summary
+// =============================================================================
+const stageSummary = async (out, fly, tailscale, ctx, opts) => {
+    const policy = await tailscale.acl.getPolicy();
+    const hasAutoApprover = isAutoApproverConfigured(policy, opts.tag);
+    out.done({
+        network: opts.network,
+        router: {
+            appName: ctx.appName,
+            tailscaleIp: ctx.device?.addresses[0] ?? null,
+        },
+        subnet: ctx.subnet ?? null,
+        tag: opts.tag,
+    });
+    out.blank()
+        .header("=".repeat(50))
+        .header("  Router Created!")
+        .header("=".repeat(50))
+        .blank()
+        .text(`Any Flycast App on the "${opts.network}" Network Is Reachable as:`)
+        .text(`  <app-name>.${opts.network}`)
+        .blank();
+    if (ctx.subnet) {
+        const machines = await fly.machines.list(ctx.appName);
+        const routerMachine = machines.find((m) => m.private_ip);
+        if (routerMachine?.private_ip) {
+            out.text("SOCKS5 Proxy Available at:")
+                .text(`  socks5://[${routerMachine.private_ip}]:${SOCKS_PROXY_PORT}`)
+                .dim("Containers on This Network Can Use It to Reach Your Tailnet.")
+                .blank();
+        }
+    }
+    out.dim("Deploy an App to This Network:")
+        .dim(`  ambit deploy my-app --network ${opts.network}`)
+        .blank()
+        .dim("Invite People to Your Tailnet:")
+        .dim("  https://login.tailscale.com/admin/users")
+        .dim("Control Their Access:")
+        .dim("  https://login.tailscale.com/admin/acls/visual/general-access-rules")
+        .blank();
+    if (ctx.subnet && !hasAutoApprover) {
+        out.header("Recommended: Configure autoApprovers")
+            .blank()
+            .dim("  Add to Your Tailnet Policy File at:")
+            .dim("  https://login.tailscale.com/admin/acls/file")
+            .blank()
+            .text(`  "autoApprovers": { "routes": { "${ctx.subnet}": ["${opts.tag}"] } }`)
+            .blank()
+            .dim("  Routes Were Approved via API for This Session.")
+            .dim("  autoApprovers Will Auto-Approve on Future Restarts.")
+            .blank();
+    }
+    if (ctx.subnet) {
+        out.header("Recommended ACL Rules:")
+            .blank()
+            .dim("  To Restrict Access, Add ACL Rules to Your Policy File:")
+            .dim("  https://login.tailscale.com/admin/acls/file")
+            .blank()
+            .dim(`    {"action": "accept", "src": ["group:YOUR_GROUP"], "dst": ["${opts.tag}:53"]}`)
+            .dim(`    {"action": "accept", "src": ["group:YOUR_GROUP"], "dst": ["${ctx.subnet}:*"]}`)
+            .blank();
+    }
+    if (!opts.shouldApprove) {
+        out.dim("Route Approval Was Skipped. To Complete Setup:")
+            .dim(`  ambit doctor --network ${opts.network}`)
+            .blank();
+    }
+    out.print();
+};
+// =============================================================================
+// Create Command
+// =============================================================================
+const create = async (argv) => {
+    const opts = {
+        string: ["org", "region", "api-key", "tag"],
+        boolean: ["help", "yes", "json", "no-auto-approve"],
+        alias: { y: "yes" },
+    };
+    const args = parseArgs(argv, opts);
+    checkArgs(args, opts, "ambit create");
+    if (args.help) {
+        console.log(`
+${bold("ambit create")} - Create Tailscale Subnet Router
+
+${bold("USAGE")}
+  ambit create <network> [options]
+
+${bold("OPTIONS")}
+  --org <org>         Fly.io organization slug
+  --region <region>   Fly.io region (default: iad)
+  --api-key <key>     Tailscale API access token (tskey-api-...)
+  --tag <tag>         Tailscale ACL tag for the router (default: tag:ambit-<network>)
+  --no-auto-approve        Skip waiting for router and approving routes
+  -y, --yes           Skip confirmation prompts
+  --json              Output as JSON (implies --no-auto-approve)
+
+${bold("DESCRIPTION")}
+  Deploys a Tailscale subnet router onto a Fly.io custom private network.
+  The network name becomes a TLD on your tailnet:
+
+    my-app.${args._[0] || "<network>"} resolves to my-app.flycast
+
+${bold("EXAMPLES")}
+  ambit create browsers
+  ambit create browsers --org my-org --region sea
+`);
+        return;
+    }
+    const out = createOutput(args.json);
+    const networkArg = args._[0];
+    if (!networkArg || typeof networkArg !== "string") {
+        return out.die("Network Name Required. Usage: ambit create <network>");
+    }
+    const network = networkArg;
+    if (isPublicTld(network)) {
+        return out.die(`"${network}" Is a Public TLD and Cannot Be Used as a Network Name`);
+    }
+    const tag = args.tag || getRouterTag(network);
+    const shouldApprove = !(args["no-auto-approve"] || args.json);
+    out.blank()
+        .header("=".repeat(50))
+        .header(`  ambit Create: ${network}`)
+        .header("=".repeat(50))
+        .blank();
+    const { fly, org, region } = await stageFlyConfig(out, {
+        json: args.json,
+        org: args.org,
+        region: args.region,
+    });
+    const tailscale = await stageTailscaleConfig(out, {
+        json: args.json,
+        apiKey: args["api-key"],
+        tag,
+        network,
+    });
+    await stageDeploy(out, fly, tailscale, {
+        network,
+        org,
+        region,
+        tag,
+        shouldApprove,
+    });
+};
+// =============================================================================
+// Register Command
+// =============================================================================
+registerCommand({
+    name: "create",
+    description: "Create a Tailscale subnet router on a Fly.io custom network",
+    usage: "ambit create <network> [--org <org>] [--region <region>]",
+    run: create,
+});

package/esm/cli/commands/create/machine.d.ts

@@ -0,0 +1,33 @@
+import { type Output } from "../../../lib/output.js";
+import { Result } from "../../../lib/result.js";
+import { type FlyProvider } from "../../../providers/fly.js";
+import type { TailscaleProvider } from "../../../providers/tailscale.js";
+import type { TailscaleDevice } from "../../../schemas/tailscale.js";
+export type CreatePhase = "create_app" | "deploy_router" | "await_device" | "approve_routes" | "configure_dns" | "accept_routes" | "complete";
+export type CreateResult = {
+    network: string;
+    router: {
+        appName: string;
+        tailscaleIp: string | null;
+    };
+    subnet: string | null;
+    tag: string;
+};
+export interface CreateCtx {
+    fly: FlyProvider;
+    tailscale: TailscaleProvider;
+    out: Output<CreateResult>;
+    network: string;
+    org: string;
+    region: string;
+    tag: string;
+    shouldApprove: boolean;
+    appName: string;
+    routerId: string;
+    device?: TailscaleDevice;
+    subnet?: string;
+}
+export declare const reportSkipped: (out: Output<CreateResult>, startPhase: CreatePhase) => void;
+export declare const hydrateCreate: (ctx: CreateCtx) => Promise<CreatePhase>;
+export declare const createTransition: (phase: CreatePhase, ctx: CreateCtx) => Promise<Result<CreatePhase>>;
+//# sourceMappingURL=machine.d.ts.map

package/esm/cli/commands/create/machine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"machine.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/create/machine.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,KAAK,MAAM,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAQhD,OAAO,EAEL,KAAK,WAAW,EACjB,MAAM,2BAA2B,CAAC;AASnC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AACzE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAOrE,MAAM,MAAM,WAAW,GACnB,YAAY,GACZ,eAAe,GACf,cAAc,GACd,gBAAgB,GAChB,eAAe,GACf,eAAe,GACf,UAAU,CAAC;AAMf,MAAM,MAAM,YAAY,GAAG;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;IACxD,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,GAAG,EAAE,MAAM,CAAC;CACb,CAAC;AAEF,MAAM,WAAW,SAAS;IACxB,GAAG,EAAE,WAAW,CAAC;IACjB,SAAS,EAAE,iBAAiB,CAAC;IAC7B,GAAG,EAAE,MAAM,CAAC,YAAY,CAAC,CAAC;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,aAAa,EAAE,OAAO,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,eAAe,CAAC;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAeD,eAAO,MAAM,aAAa,GACxB,KAAK,MAAM,CAAC,YAAY,CAAC,EACzB,YAAY,WAAW,SAMxB,CAAC;AAMF,eAAO,MAAM,aAAa,GACxB,KAAK,SAAS,KACb,OAAO,CAAC,WAAW,CA4BrB,CAAC;AAMF,eAAO,MAAM,gBAAgB,GAC3B,OAAO,WAAW,EAClB,KAAK,SAAS,KACb,OAAO,CAAC,MAAM,CAAC,WAAW,CAAC,CA8G7B,CAAC"}

package/esm/cli/commands/create/machine.js

@@ -0,0 +1,162 @@
+// =============================================================================
+// Create — Phases, Context, Hydration, Transitions
+// =============================================================================
+import { randomId } from "../../../lib/cli.js";
+import { Result } from "../../../lib/result.js";
+import { extractSubnet } from "../../../util/fly-transforms.js";
+import { ROUTER_DOCKER_DIR, SECRET_NETWORK_NAME, SECRET_ROUTER_ID, SECRET_TAILSCALE_AUTHKEY, } from "../../../util/constants.js";
+import { FlyDeployError, } from "../../../providers/fly.js";
+import { getRouterAppName } from "../../../util/naming.js";
+import { enableAcceptRoutes, isAcceptRoutesEnabled, isAutoApproverConfigured, isTailscaleInstalled, waitForDevice, } from "../../../util/tailscale-local.js";
+import { findRouterApp, getRouterMachineInfo } from "../../../util/discovery.js";
+// =============================================================================
+// Phase Labels
+// =============================================================================
+const CREATE_PHASES = [
+    { phase: "create_app", label: "Fly App Created" },
+    { phase: "deploy_router", label: "Router Deployed" },
+    { phase: "await_device", label: "Router in Tailnet" },
+    { phase: "approve_routes", label: "Routes Approved" },
+    { phase: "configure_dns", label: "Split DNS Configured" },
+    { phase: "accept_routes", label: "Accept Routes Enabled" },
+];
+export const reportSkipped = (out, startPhase) => {
+    for (const { phase, label } of CREATE_PHASES) {
+        if (phase === startPhase)
+            break;
+        out.skip(label);
+    }
+};
+// =============================================================================
+// Hydration — determine starting phase from infrastructure state
+// =============================================================================
+export const hydrateCreate = async (ctx) => {
+    const router = await findRouterApp(ctx.fly, ctx.org, ctx.network);
+    if (!router)
+        return "create_app";
+    ctx.appName = router.appName;
+    ctx.routerId = router.routerId;
+    const machine = await getRouterMachineInfo(ctx.fly, router.appName);
+    if (!machine || machine.state !== "started")
+        return "deploy_router";
+    ctx.subnet = machine.subnet;
+    if (!ctx.shouldApprove)
+        return "complete";
+    const device = await ctx.tailscale.devices.getByHostname(router.appName);
+    if (!device)
+        return "await_device";
+    ctx.device = device;
+    const routes = await ctx.tailscale.routes.get(device.id);
+    if (!routes || routes.unapproved.length > 0)
+        return "approve_routes";
+    const dns = await ctx.tailscale.dns.getSplit();
+    if (!dns[ctx.network]?.length)
+        return "configure_dns";
+    if (!(await isAcceptRoutesEnabled()))
+        return "accept_routes";
+    return "complete";
+};
+// =============================================================================
+// Transitions
+// =============================================================================
+export const createTransition = async (phase, ctx) => {
+    switch (phase) {
+        case "create_app": {
+            const suffix = randomId(8);
+            ctx.appName = getRouterAppName(ctx.network, suffix);
+            ctx.routerId = suffix;
+            await ctx.out.spin("Creating App", () => ctx.fly.apps.create(ctx.appName, ctx.org, { network: ctx.network }));
+            ctx.out.ok(`Created App: ${ctx.appName}`);
+            return Result.ok("deploy_router");
+        }
+        case "deploy_router": {
+            const authKey = await ctx.tailscale.auth.createKey({
+                reusable: false,
+                ephemeral: false,
+                preauthorized: true,
+                tags: [ctx.tag],
+            });
+            ctx.out.ok("Auth Key Created");
+            await ctx.out.spin("Setting Secrets", () => ctx.fly.secrets.set(ctx.appName, {
+                [SECRET_TAILSCALE_AUTHKEY]: authKey,
+                [SECRET_NETWORK_NAME]: ctx.network,
+                [SECRET_ROUTER_ID]: ctx.routerId,
+            }, { stage: true }));
+            const dockerDir = ROUTER_DOCKER_DIR;
+            try {
+                await ctx.fly.deploy.router(ctx.appName, dockerDir, {
+                    region: ctx.region,
+                });
+            }
+            catch (e) {
+                if (e instanceof FlyDeployError) {
+                    ctx.out.dim(`  ${e.detail}`);
+                    return Result.err(e.message);
+                }
+                throw e;
+            }
+            ctx.out.ok("Router Deployed");
+            const machines = await ctx.fly.machines.list(ctx.appName);
+            const m = machines.find((m) => m.private_ip);
+            if (m?.private_ip)
+                ctx.subnet = extractSubnet(m.private_ip);
+            if (!ctx.shouldApprove)
+                return Result.ok("complete");
+            return Result.ok("await_device");
+        }
+        case "await_device": {
+            ctx.device = await waitForDevice(ctx.tailscale, ctx.appName, 180000);
+            ctx.out.ok(`Router Joined Tailnet: ${ctx.device.addresses[0]}`);
+            if (!ctx.subnet) {
+                const machines = await ctx.fly.machines.list(ctx.appName);
+                const m = machines.find((m) => m.private_ip);
+                if (m?.private_ip)
+                    ctx.subnet = extractSubnet(m.private_ip);
+            }
+            return Result.ok("approve_routes");
+        }
+        case "approve_routes": {
+            if (!ctx.device || !ctx.subnet) {
+                return Result.err("Missing Device or Subnet");
+            }
+            const policy = await ctx.tailscale.acl.getPolicy();
+            const hasAutoApprover = isAutoApproverConfigured(policy, ctx.tag);
+            if (hasAutoApprover) {
+                ctx.out.ok("Routes Auto-Approved via ACL Policy");
+            }
+            else {
+                await ctx.tailscale.routes.approve(ctx.device.id, [ctx.subnet]);
+                ctx.out.ok("Subnet Routes Approved");
+            }
+            return Result.ok("configure_dns");
+        }
+        case "configure_dns": {
+            if (!ctx.device)
+                return Result.err("Missing Device");
+            await ctx.tailscale.dns.setSplit(ctx.network, [ctx.device.addresses[0]]);
+            ctx.out.ok(`Split DNS Configured: *.${ctx.network}`);
+            return Result.ok("accept_routes");
+        }
+        case "accept_routes": {
+            if (await isTailscaleInstalled()) {
+                if (await isAcceptRoutesEnabled()) {
+                    ctx.out.ok("Accept Routes Already Enabled");
+                }
+                else if (await enableAcceptRoutes()) {
+                    ctx.out.ok("Accept Routes Enabled");
+                }
+                else {
+                    ctx.out.warn("Could Not Enable Accept Routes");
+                    ctx.out.dim("  Run: sudo tailscale set --accept-routes");
+                }
+            }
+            else {
+                ctx.out.warn("Tailscale CLI Not Found");
+                ctx.out.dim("  Ensure Accept-Routes is Enabled on This Device");
+            }
+            return Result.ok("complete");
+        }
+        default:
+            return Result.err(`Unknown Phase: ${phase}`);
+    }
+};

package/esm/cli/commands/deploy/index.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.d.ts.map

package/esm/cli/commands/deploy/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/deploy/index.ts"],"names":[],"mappings":""}