@cardelli/ambit 0.1.5 → 0.2.1

package/esm/cli/commands/deploy/modes.js

@@ -0,0 +1,152 @@
+// =============================================================================
+// Deploy Modes — Image, Config, and Template Resolution
+// =============================================================================
+import * as dntShim from "../../../_dnt.shims.js";
+import { join } from "../../../deps/jsr.io/@std/path/1.1.4/mod.js";
+import { fileExists } from "../../../lib/cli.js";
+import { scanFlyToml } from "../../../util/guard.js";
+import { fetchTemplate, parseTemplateRef } from "../../../util/template.js";
+// =============================================================================
+// Image Mode
+// =============================================================================
+/**
+ * Generate a minimal fly.toml with http_service config for auto start/stop.
+ * Written to a temp directory and cleaned up after deploy.
+ */
+const generateServiceToml = (port) => `[http_service]\n` +
+    `  internal_port = ${port}\n` +
+    `  auto_stop_machines = "stop"\n` +
+    `  auto_start_machines = true\n` +
+    `  min_machines_running = 0\n`;
+/**
+ * Parse --main-port value. Returns the port number, or null if "none".
+ * Dies on invalid input.
+ */
+const parseMainPort = (raw, out) => {
+    if (raw === "none")
+        return null;
+    const port = Number(raw);
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+        out.die(`Invalid --main-port: "${raw}". Use a Port Number (1-65535) or "none".`);
+        return "error";
+    }
+    return port;
+};
+/** Resolve deploy config for image mode (--image). */
+export const resolveImageMode = (image, mainPortRaw, out) => {
+    const mainPort = parseMainPort(mainPortRaw, out);
+    if (mainPort === "error")
+        return null;
+    const preflight = {
+        scanned: false,
+        warnings: [],
+    };
+    if (mainPort !== null) {
+        const tempDir = dntShim.Deno.makeTempDirSync();
+        const configPath = join(tempDir, "fly.toml");
+        dntShim.Deno.writeTextFileSync(configPath, generateServiceToml(mainPort));
+        out.ok(`HTTP Service on Port ${mainPort} (auto start/stop)`);
+        return { image, configPath, preflight, tempDir };
+    }
+    out.info("Image Mode — No Service Config");
+    return { image, preflight };
+};
+// =============================================================================
+// Config Mode
+// =============================================================================
+/** Resolve deploy config for config mode (default — uses fly.toml). */
+export const resolveConfigMode = async (explicitConfig, out) => {
+    let configPath = explicitConfig;
+    if (!configPath && (await fileExists("./fly.toml"))) {
+        configPath = "./fly.toml";
+    }
+    if (!configPath) {
+        out.info("No fly.toml Found — Deploying Without Config Scan");
+        return { preflight: { scanned: false, warnings: [] } };
+    }
+    if (!(await fileExists(configPath))) {
+        out.die(`Config File Not Found: ${configPath}`);
+        return null;
+    }
+    const tomlContent = await dntShim.Deno.readTextFile(configPath);
+    const scan = scanFlyToml(tomlContent);
+    if (scan.errors.length > 0) {
+        for (const err of scan.errors) {
+            out.err(err);
+        }
+        out.die("Pre-flight Check Failed. Fix fly.toml Before Deploying.");
+        return null;
+    }
+    for (const warn of scan.warnings) {
+        out.warn(warn);
+    }
+    out.ok(`Scanned ${configPath}`);
+    return {
+        configPath,
+        preflight: { scanned: scan.scanned, warnings: scan.warnings },
+    };
+};
+// =============================================================================
+// Template Mode
+// =============================================================================
+/** Resolve deploy config for template mode (--template). */
+export const resolveTemplateMode = async (templateRaw, out) => {
+    const ref = parseTemplateRef(templateRaw);
+    if (!ref) {
+        out.die(`Invalid Template Reference: "${templateRaw}". ` +
+            `Format: owner/repo[/path][@ref]`);
+        return null;
+    }
+    const label = (ref.path === "."
+        ? `${ref.owner}/${ref.repo}`
+        : `${ref.owner}/${ref.repo}/${ref.path}`) +
+        (ref.ref ? `@${ref.ref}` : "");
+    out.info(`Template: ${label}`);
+    const fetchSpinner = out.spinner("Fetching Template from GitHub");
+    const result = await fetchTemplate(ref);
+    if (!result.ok) {
+        fetchSpinner.fail("Template Fetch Failed");
+        out.die(result.error);
+        return null;
+    }
+    const { tempDir, templateDir } = result.value;
+    fetchSpinner.success("Template Fetched");
+    const configPath = join(templateDir, "fly.toml");
+    let tomlContent;
+    try {
+        tomlContent = await dntShim.Deno.readTextFile(configPath);
+    }
+    catch {
+        try {
+            dntShim.Deno.removeSync(tempDir, { recursive: true });
+        }
+        catch {
+            /* ignore */
+        }
+        out.die(`Template '${ref.path === "." ? ref.repo : ref.path}' Has No fly.toml`);
+        return null;
+    }
+    const scan = scanFlyToml(tomlContent);
+    if (scan.errors.length > 0) {
+        try {
+            dntShim.Deno.removeSync(tempDir, { recursive: true });
+        }
+        catch {
+            /* ignore */
+        }
+        for (const err of scan.errors) {
+            out.err(err);
+        }
+        out.die("Pre-flight Check Failed for Template fly.toml");
+        return null;
+    }
+    for (const warn of scan.warnings) {
+        out.warn(warn);
+    }
+    out.ok(`Scanned ${ref.path === "." ? "" : ref.path + "/"}fly.toml`);
+    return {
+        configPath,
+        preflight: { scanned: scan.scanned, warnings: scan.warnings },
+        tempDir,
+    };
+};

package/esm/cli/commands/destroy/app.d.ts

@@ -0,0 +1,2 @@
+export declare const destroyApp: (argv: string[]) => Promise<void>;
+//# sourceMappingURL=app.d.ts.map

package/esm/cli/commands/destroy/app.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/destroy/app.ts"],"names":[],"mappings":"AAiLA,eAAO,MAAM,UAAU,GAAU,MAAM,MAAM,EAAE,KAAG,OAAO,CAAC,IAAI,CAoF7D,CAAC"}

package/esm/cli/commands/destroy/app.js

@@ -0,0 +1,173 @@
+// =============================================================================
+// Destroy App — Destroy a Workload App on a Network
+// =============================================================================
+import { parseArgs } from "../../../deps/jsr.io/@std/cli/1.0.28/mod.js";
+import { bold, confirm } from "../../../lib/cli.js";
+import { checkArgs } from "../../../lib/args.js";
+import { createOutput } from "../../../lib/output.js";
+import { Result } from "../../../lib/result.js";
+import { runMachine } from "../../../lib/machine.js";
+import { findWorkloadApp } from "../../../util/discovery.js";
+import { assertNotRouter } from "../../../util/guard.js";
+import { initSession } from "../../../util/session.js";
+// =============================================================================
+// Hydration
+// =============================================================================
+const hydrateDestroyApp = async (ctx) => {
+    const workloadApp = await findWorkloadApp(ctx.fly, ctx.org, ctx.app, ctx.network);
+    if (!workloadApp) {
+        const anyApp = await findWorkloadApp(ctx.fly, ctx.org, ctx.app);
+        if (anyApp) {
+            ctx.out.die(`App '${ctx.app}' Exists on Network '${anyApp.network}', Not '${ctx.network}'`);
+        }
+        return "complete";
+    }
+    ctx.flyAppName = workloadApp.appName;
+    return "confirm";
+};
+// =============================================================================
+// Transitions
+// =============================================================================
+const destroyAppTransition = async (phase, ctx) => {
+    switch (phase) {
+        case "confirm": {
+            ctx.out.blank()
+                .header("Ambit Destroy App")
+                .blank()
+                .text(`  App:      ${ctx.flyAppName}`)
+                .text(`  Network:  ${ctx.network}`)
+                .blank();
+            if (!ctx.yes && !ctx.json) {
+                const confirmed = await confirm(`Destroy App '${ctx.app}' on Network '${ctx.network}'?`);
+                if (!confirmed) {
+                    ctx.out.text("Cancelled.");
+                    return Result.err("Cancelled");
+                }
+                ctx.out.blank();
+            }
+            return Result.ok("delete_app");
+        }
+        case "delete_app": {
+            if (ctx.flyAppName) {
+                await ctx.out.spin("Deleting App", () => ctx.fly.apps.delete(ctx.flyAppName));
+                ctx.out.ok("Fly App Destroyed");
+            }
+            else {
+                ctx.out.skip("Fly App Already Destroyed");
+            }
+            return Result.ok("complete");
+        }
+        default:
+            return Result.err(`Unknown Phase: ${phase}`);
+    }
+};
+// =============================================================================
+// Stage 1: Destroy
+// =============================================================================
+const stageDestroy = async (out, fly, opts) => {
+    const ctx = { fly, out, ...opts };
+    const phase = await hydrateDestroyApp(ctx);
+    if (phase === "complete" && !ctx.flyAppName) {
+        out.ok(`App '${opts.app}' on Network '${opts.network}' Already Destroyed`);
+        out.print();
+        return;
+    }
+    const machine = {
+        terminal: "complete",
+        transition: destroyAppTransition,
+    };
+    const result = await runMachine(machine, phase, ctx);
+    if (!result.ok) {
+        if (result.error === "Cancelled")
+            return;
+        return out.die(result.error);
+    }
+    stageSummary(out, ctx);
+};
+// =============================================================================
+// Stage 3: Summary
+// =============================================================================
+const stageSummary = (out, ctx) => {
+    out.done({
+        destroyed: true,
+        appName: ctx.flyAppName ?? ctx.app,
+        network: ctx.network,
+    });
+    out.ok("App Destroyed");
+    out.blank();
+    out.print();
+};
+// =============================================================================
+// Destroy App Command
+// =============================================================================
+export const destroyApp = async (argv) => {
+    const opts = {
+        string: ["network", "org"],
+        boolean: ["help", "yes", "json"],
+        alias: { y: "yes" },
+    };
+    const args = parseArgs(argv, opts);
+    checkArgs(args, opts, "ambit destroy app");
+    if (args.help) {
+        console.log(`
+${bold("ambit destroy app")} - Destroy a Workload App
+
+${bold("USAGE")}
+  ambit destroy app <app>.<network> [--org <org>] [--yes] [--json]
+  ambit destroy app <app> --network <name> [--org <org>] [--yes] [--json]
+
+${bold("OPTIONS")}
+  --network <name>   Target network (if not using dot syntax)
+  --org <org>        Fly.io organization slug
+  -y, --yes          Skip confirmation prompts
+  --json             Output as JSON
+
+${bold("EXAMPLES")}
+  ambit destroy app my-app.browsers
+  ambit destroy app my-app --network browsers --yes
+`);
+        return;
+    }
+    const out = createOutput(args.json);
+    const appArg = args._[0];
+    if (!appArg || typeof appArg !== "string") {
+        return out.die("Missing App Name. Usage: ambit destroy app <app>.<network>");
+    }
+    let app;
+    let network;
+    if (appArg.includes(".")) {
+        const parts = appArg.split(".");
+        if (parts.length !== 2 || !parts[0] || !parts[1]) {
+            return out.die(`'${appArg}' Should Have Exactly One Dot, Like my-app.my-network`);
+        }
+        if (args.network) {
+            return out.die(`Network Is Already Part of the Name ('${appArg}'), --network Is Not Needed`);
+        }
+        app = parts[0];
+        network = parts[1];
+    }
+    else {
+        app = appArg;
+        if (!args.network) {
+            return out.die(`Missing Network. Use: ambit destroy app ${app}.<network>`);
+        }
+        network = args.network;
+    }
+    try {
+        assertNotRouter(app);
+    }
+    catch (e) {
+        return out.die(e instanceof Error ? e.message : String(e));
+    }
+    const { fly, org } = await initSession(out, {
+        json: args.json,
+        org: args.org,
+    });
+    await stageDestroy(out, fly, {
+        app,
+        network,
+        org,
+        yes: args.yes,
+        json: args.json,
+    });
+};

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

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

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

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

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

@@ -0,0 +1,63 @@
+// =============================================================================
+// Destroy Command - Destroy Networks or Apps
+// =============================================================================
+import * as dntShim from "../../../_dnt.shims.js";
+import { parseArgs } from "../../../deps/jsr.io/@std/cli/1.0.28/mod.js";
+import { bold } from "../../../lib/cli.js";
+import { registerCommand } from "../../mod.js";
+import { destroyNetwork } from "./network.js";
+import { destroyApp } from "./app.js";
+// =============================================================================
+// Top-Level Help
+// =============================================================================
+const showDestroyHelp = () => {
+    console.log(`
+${bold("ambit destroy")} - Destroy Networks or Apps
+
+${bold("USAGE")}
+  ambit destroy network <name> [options]
+  ambit destroy app <app>.<network> [options]
+
+${bold("SUBCOMMANDS")}
+  network    Tear down a router, clean up DNS and tailnet device
+  app        Destroy a workload app on a network
+
+${bold("OPTIONS")}
+  --help     Show help for a subcommand
+
+${bold("EXAMPLES")}
+  ambit destroy network browsers
+  ambit destroy app my-app.browsers
+  ambit destroy app my-app --network browsers
+
+Run 'ambit destroy network --help' or 'ambit destroy app --help' for details.
+`);
+};
+// =============================================================================
+// Dispatcher
+// =============================================================================
+const destroy = async (argv) => {
+    const subcommand = typeof argv[0] === "string" ? argv[0] : undefined;
+    if (subcommand === "network") {
+        return destroyNetwork(argv.slice(1));
+    }
+    if (subcommand === "app") {
+        return destroyApp(argv.slice(1));
+    }
+    const args = parseArgs(argv, { boolean: ["help"] });
+    if (args.help) {
+        showDestroyHelp();
+        return;
+    }
+    showDestroyHelp();
+    dntShim.Deno.exit(1);
+};
+// =============================================================================
+// Register Command
+// =============================================================================
+registerCommand({
+    name: "destroy",
+    description: "Destroy a network (router) or a workload app",
+    usage: "ambit destroy network|app <name> [options]",
+    run: destroy,
+});

package/esm/cli/commands/destroy/network.d.ts

@@ -0,0 +1,2 @@
+export declare const destroyNetwork: (argv: string[]) => Promise<void>;
+//# sourceMappingURL=network.d.ts.map

package/esm/cli/commands/destroy/network.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"network.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/destroy/network.ts"],"names":[],"mappings":"AAwQA,eAAO,MAAM,cAAc,GAAU,MAAM,MAAM,EAAE,KAAG,OAAO,CAAC,IAAI,CAkDjE,CAAC"}

package/esm/cli/commands/destroy/network.js

@@ -0,0 +1,210 @@
+// =============================================================================
+// Destroy Network — Tear Down Router and Clean Up Tailnet
+// =============================================================================
+import { parseArgs } from "../../../deps/jsr.io/@std/cli/1.0.28/mod.js";
+import { bold, confirm } from "../../../lib/cli.js";
+import { checkArgs } from "../../../lib/args.js";
+import { createOutput } from "../../../lib/output.js";
+import { Result } from "../../../lib/result.js";
+import { runMachine } from "../../../lib/machine.js";
+import { findRouterApp, listWorkloadAppsOnNetwork, } from "../../../util/discovery.js";
+import { initSession } from "../../../util/session.js";
+// =============================================================================
+// Phase Labels
+// =============================================================================
+const DESTROY_NETWORK_PHASES = [
+    { phase: "confirm", label: "Confirmed" },
+    { phase: "clear_dns", label: "Split DNS Cleared" },
+    { phase: "remove_device", label: "Tailscale Device Removed" },
+    { phase: "delete_app", label: "Fly App Destroyed" },
+];
+const reportSkipped = (out, startPhase) => {
+    for (const { phase, label } of DESTROY_NETWORK_PHASES) {
+        if (phase === startPhase)
+            break;
+        out.skip(label);
+    }
+};
+// =============================================================================
+// Hydration
+// =============================================================================
+const hydrateDestroyNetwork = async (ctx) => {
+    const router = await findRouterApp(ctx.fly, ctx.org, ctx.network);
+    const dns = await ctx.tailscale.dns.getSplit();
+    const hasDns = (dns[ctx.network]?.length ?? 0) > 0;
+    if (router) {
+        ctx.appName = router.appName;
+        const device = await ctx.tailscale.devices.getByHostname(router.appName);
+        if (device) {
+            ctx.device = device;
+            ctx.tag = device.tags?.[0] ?? undefined;
+        }
+    }
+    if (!router && !ctx.device && !hasDns)
+        return "complete";
+    if (!hasDns && !ctx.device && router)
+        return "delete_app";
+    if (!hasDns && ctx.device)
+        return "remove_device";
+    if (!hasDns)
+        return router ? "delete_app" : "complete";
+    return "confirm";
+};
+// =============================================================================
+// Transitions
+// =============================================================================
+const destroyNetworkTransition = async (phase, ctx) => {
+    switch (phase) {
+        case "confirm": {
+            const workloads = await listWorkloadAppsOnNetwork(ctx.fly, ctx.org, ctx.network);
+            ctx.out.blank()
+                .header("Ambit Destroy Network")
+                .blank()
+                .text(`  Network:    ${ctx.network}`)
+                .text(`  Router App: ${ctx.appName ?? "unknown"}`)
+                .text(`  Tag:        ${ctx.tag ?? "unknown"}`)
+                .blank();
+            if (workloads.length > 0) {
+                ctx.out.warn(`${workloads.length} Workload App(s) Still on Network '${ctx.network}':`);
+                for (const wa of workloads) {
+                    ctx.out.text(`  - ${wa.appName}`);
+                }
+                ctx.out.blank();
+                ctx.out.dim("These Apps Will Lose Connectivity when the Router Is Destroyed.");
+                ctx.out.dim(`Consider Destroying Them First with: ambit destroy app <name>.${ctx.network}`);
+                ctx.out.blank();
+            }
+            if (!ctx.yes && !ctx.json) {
+                const confirmed = await confirm("Destroy This Router?");
+                if (!confirmed) {
+                    ctx.out.text("Cancelled.");
+                    return Result.err("Cancelled");
+                }
+                ctx.out.blank();
+            }
+            return Result.ok("clear_dns");
+        }
+        case "clear_dns": {
+            await ctx.tailscale.dns.clearSplit(ctx.network);
+            ctx.out.ok("Split DNS Cleared");
+            return Result.ok("remove_device");
+        }
+        case "remove_device": {
+            if (ctx.device) {
+                await ctx.tailscale.devices.delete(ctx.device.id);
+                ctx.out.ok("Tailscale Device Removed");
+            }
+            else {
+                ctx.out.skip("Tailscale Device Already Removed");
+            }
+            return Result.ok("delete_app");
+        }
+        case "delete_app": {
+            if (ctx.appName) {
+                await ctx.out.spin("Deleting App", () => ctx.fly.apps.delete(ctx.appName));
+                ctx.out.ok("Fly App Destroyed");
+            }
+            else {
+                ctx.out.skip("Fly App Already Destroyed");
+            }
+            return Result.ok("complete");
+        }
+        default:
+            return Result.err(`Unknown Phase: ${phase}`);
+    }
+};
+// =============================================================================
+// Stage 1: Destroy
+// =============================================================================
+const stageDestroy = async (out, fly, tailscale, opts) => {
+    const ctx = { fly, tailscale, out, ...opts };
+    const phase = await hydrateDestroyNetwork(ctx);
+    if (phase === "complete") {
+        out.ok(`Network "${opts.network}" Already Destroyed`);
+        out.print();
+        return;
+    }
+    reportSkipped(out, phase);
+    const machine = {
+        terminal: "complete",
+        transition: destroyNetworkTransition,
+    };
+    const result = await runMachine(machine, phase, ctx);
+    if (!result.ok) {
+        if (result.error === "Cancelled")
+            return;
+        return out.die(result.error);
+    }
+    stageSummary(out, ctx);
+};
+// =============================================================================
+// Stage 3: Summary
+// =============================================================================
+const stageSummary = (out, ctx) => {
+    out.done({
+        destroyed: true,
+        appName: ctx.appName ?? "",
+        workloadAppsWarned: 0,
+    });
+    out.ok("Router Destroyed");
+    if (ctx.tag) {
+        out.blank()
+            .dim("If You Added ACL Policy Entries for This Router, Remember to Remove:")
+            .dim(`  tagOwners:     ${ctx.tag}`)
+            .dim(`  autoApprovers: routes for ${ctx.tag}`)
+            .dim(`  acls:          rules referencing ${ctx.tag}`)
+            .blank();
+    }
+    else {
+        out.blank()
+            .dim("If You Added ACL Policy Entries for This Router, Remember to Remove")
+            .dim("the Associated Tag from tagOwners, autoApprovers, and acls.")
+            .blank();
+    }
+    out.print();
+};
+// =============================================================================
+// Destroy Network Command
+// =============================================================================
+export const destroyNetwork = async (argv) => {
+    const opts = {
+        string: ["network", "org"],
+        boolean: ["help", "yes", "json"],
+        alias: { y: "yes" },
+    };
+    const args = parseArgs(argv, opts);
+    checkArgs(args, opts, "ambit destroy network");
+    if (args.help) {
+        console.log(`
+${bold("ambit destroy network")} - Tear Down Router
+
+${bold("USAGE")}
+  ambit destroy network <name> [--org <org>] [--yes] [--json]
+
+${bold("OPTIONS")}
+  --org <org>        Fly.io organization slug
+  -y, --yes          Skip confirmation prompts
+  --json             Output as JSON
+
+${bold("EXAMPLES")}
+  ambit destroy network browsers
+  ambit destroy network browsers --org my-org --yes
+`);
+        return;
+    }
+    const out = createOutput(args.json);
+    const network = (typeof args._[0] === "string" ? args._[0] : undefined) || args.network;
+    if (!network) {
+        return out.die("Network Name Required. Usage: ambit destroy network <name>");
+    }
+    const { fly, tailscale, org } = await initSession(out, {
+        json: args.json,
+        org: args.org,
+    });
+    await stageDestroy(out, fly, tailscale, {
+        network,
+        org,
+        yes: args.yes,
+        json: args.json,
+    });
+};

package/esm/cli/commands/doctor.d.ts.map

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