@cardelli/ambit 0.1.1 → 0.1.3

package/esm/deno.d.ts

@@ -0,0 +1,51 @@
+declare namespace _default {
+    let name: string;
+    let version: string;
+    let description: string;
+    let license: string;
+    let exports: {
+        ".": string;
+        "./providers/fly": string;
+        "./providers/tailscale": string;
+        "./schemas/config": string;
+        "./schemas/fly": string;
+        "./schemas/tailscale": string;
+        "./lib/cli": string;
+        "./lib/command": string;
+        "./lib/output": string;
+        "./lib/result": string;
+        "./lib/paths": string;
+        "./src/credentials": string;
+        "./src/discovery": string;
+        "./src/guard": string;
+        "./src/resolve": string;
+    };
+    let tasks: {
+        dev: string;
+        run: string;
+        check: string;
+        test: string;
+        "check-versions": string;
+        build: string;
+    };
+    let imports: {
+        "@/": string;
+        "@cliffy/table": string;
+        "@std/assert": string;
+        "@std/cli": string;
+        "@std/json": string;
+        "@std/path": string;
+        "@std/fs": string;
+        "@std/toml": string;
+        zod: string;
+    };
+    namespace compilerOptions {
+        let strict: boolean;
+        let baseUrl: string;
+        let paths: {
+            "@/*": string[];
+        };
+    }
+}
+export default _default;
+//# sourceMappingURL=deno.d.ts.map

package/esm/deno.d.ts.map

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

package/esm/deno.js

@@ -0,0 +1,49 @@
+export default {
+    "name": "@cardelli/ambit",
+    "version": "0.1.3",
+    "description": "Deploy apps to the cloud that only you and your AI agents can reach",
+    "license": "MIT",
+    "exports": {
+        ".": "./main.ts",
+        "./providers/fly": "./src/providers/fly.ts",
+        "./providers/tailscale": "./src/providers/tailscale.ts",
+        "./schemas/config": "./src/schemas/config.ts",
+        "./schemas/fly": "./src/schemas/fly.ts",
+        "./schemas/tailscale": "./src/schemas/tailscale.ts",
+        "./lib/cli": "./lib/cli.ts",
+        "./lib/command": "./lib/command.ts",
+        "./lib/output": "./lib/output.ts",
+        "./lib/result": "./lib/result.ts",
+        "./lib/paths": "./lib/paths.ts",
+        "./src/credentials": "./src/credentials.ts",
+        "./src/discovery": "./src/discovery.ts",
+        "./src/guard": "./src/guard.ts",
+        "./src/resolve": "./src/resolve.ts"
+    },
+    "tasks": {
+        "dev": "deno run --watch main.ts",
+        "run": "deno run -A main.ts",
+        "check": "deno check main.ts",
+        "test": "deno test -A",
+        "check-versions": "deno run --allow-net --allow-run=git scripts/check-versions.ts",
+        "build": "deno run -A scripts/build_npm.ts"
+    },
+    "imports": {
+        "@/": "./",
+        "@cliffy/table": "jsr:@cliffy/table@^1.0.0",
+        "@std/assert": "jsr:@std/assert@1",
+        "@std/cli": "jsr:@std/cli@^1.0.27",
+        "@std/json": "jsr:@std/json@^1.0.2",
+        "@std/path": "jsr:@std/path@^1.1.4",
+        "@std/fs": "jsr:@std/fs@^1.0.22",
+        "@std/toml": "jsr:@std/toml@^1",
+        "zod": "jsr:@zod/zod@^4.3.6"
+    },
+    "compilerOptions": {
+        "strict": true,
+        "baseUrl": ".",
+        "paths": {
+            "@/*": ["./*"]
+        }
+    }
+};

package/esm/lib/result.d.ts

@@ -0,0 +1,8 @@
+export type Result<T, K extends string = string> = ({
+    ok: true;
+} & T) | {
+    ok: false;
+    kind: K;
+    message: string;
+};
+//# sourceMappingURL=result.d.ts.map

package/esm/lib/result.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"result.d.ts","sourceRoot":"","sources":["../../src/lib/result.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,MAAM,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,GAAG,MAAM,IAC3C,CAAC;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG,CAAC,CAAC,GAClB;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,CAAC,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC"}

package/esm/lib/result.js

@@ -0,0 +1 @@
+export {};

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

@@ -7,7 +7,7 @@ import { createOutput } from "../../../lib/output.js";
 import { registerCommand } from "../mod.js";
 import { extractSubnet, getRouterTag } from "../../schemas/config.js";
 import { isPublicTld } from "../../guard.js";
-import { createFlyProvider, FlyDeployError, getRouterAppName } from "../../providers/fly.js";
+import { createFlyProvider, FlyDeployError, getRouterAppName, } from "../../providers/fly.js";
 import { createTailscaleProvider, enableAcceptRoutes, isAcceptRoutesEnabled, isTailscaleInstalled, waitForDevice, } from "../../providers/tailscale.js";
 import { getCredentialStore } from "../../credentials.js";
 import { resolveOrg } from "../../resolve.js";
@@ -50,10 +50,11 @@ ${bold("EXAMPLES")}
         return;
     }
     const out = createOutput(args.json);
-    const network = args._[0];
-    if (!network) {
+    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`);
     }

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

@@ -3,6 +3,7 @@
 // =============================================================================
 import * as dntShim from "../../../_dnt.shims.js";
 import { parseArgs } from "../../../deps/jsr.io/@std/cli/1.0.27/mod.js";
+import { join } from "../../../deps/jsr.io/@std/path/1.1.4/mod.js";
 import { bold, confirm, fileExists } from "../../../lib/cli.js";
 import { createOutput } from "../../../lib/output.js";
 import { registerCommand } from "../mod.js";
@@ -10,14 +11,161 @@ import { createFlyProvider, FlyDeployError } from "../../providers/fly.js";
 import { findRouterApp } from "../../discovery.js";
 import { resolveOrg } from "../../resolve.js";
 import { assertNotRouter, auditDeploy, scanFlyToml } from "../../guard.js";
+import { fetchTemplate, parseTemplateRef } from "../../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). */
+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). */
+const resolveConfigMode = async (explicitConfig, out) => {
+    // Determine config path: explicit --config, or auto-detect ./fly.toml
+    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;
+    }
+    // Pre-flight scan
+    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). */
+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.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.message);
+        return null;
+    }
+    fetchSpinner.success("Template Fetched");
+    // Find and scan the template's fly.toml
+    const configPath = join(result.templateDir, "fly.toml");
+    let tomlContent;
+    try {
+        tomlContent = await dntShim.Deno.readTextFile(configPath);
+    }
+    catch {
+        try {
+            dntShim.Deno.removeSync(result.tempDir, { recursive: true });
+        }
+        catch { /* ignore */ }
+        out.die(`Template '${ref.path}' Has No fly.toml`);
+        return null;
+    }
+    const scan = scanFlyToml(tomlContent);
+    if (scan.errors.length > 0) {
+        try {
+            dntShim.Deno.removeSync(result.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}/fly.toml`);
+    return {
+        configPath,
+        preflight: { scanned: scan.scanned, warnings: scan.warnings },
+        tempDir: result.tempDir,
+    };
+};
 // =============================================================================
 // Deploy Command
 // =============================================================================
 const deploy = async (argv) => {
     const args = parseArgs(argv, {
-        string: ["network", "org", "region", "image", "config"],
+        string: [
+            "network",
+            "org",
+            "region",
+            "image",
+            "config",
+            "main-port",
+            "template",
+        ],
         boolean: ["help", "yes", "json"],
         alias: { y: "yes" },
+        default: { "main-port": "80" },
     });
     if (args.help) {
         console.log(`
@@ -28,20 +176,37 @@ ${bold("USAGE")}
 
 ${bold("MODES")}
   Config mode (default):
-    ambit deploy <app> --network <name>                 Uses ./fly.toml
-    ambit deploy <app> --network <name> --config path   Explicit fly.toml
+    ambit deploy <app> --network <name>                    Uses ./fly.toml
+    ambit deploy <app> --network <name> --config path      Explicit fly.toml
 
   Image mode:
-    ambit deploy <app> --network <name> --image <img>   Docker image, no toml
+    ambit deploy <app> --network <name> --image <img>      Docker image, no toml
+
+  Template mode:
+    ambit deploy <app> --network <name> --template <ref>   GitHub template
 
 ${bold("OPTIONS")}
-  --network <name>   Custom 6PN network to target (required)
-  --org <org>        Fly.io organization slug
-  --region <region>  Primary deployment region
-  --image <img>      Docker image (mutually exclusive with --config)
-  --config <path>    fly.toml path (mutually exclusive with --image)
-  -y, --yes          Skip confirmation prompts
-  --json             Output as JSON
+  --network <name>       Custom 6PN network to target (required)
+  --org <org>            Fly.io organization slug
+  --region <region>      Primary deployment region
+  -y, --yes              Skip confirmation prompts
+  --json                 Output as JSON
+
+${bold("CONFIG MODE")} (default)
+  --config <path>        Explicit fly.toml path (auto-detects ./fly.toml if omitted)
+
+${bold("IMAGE MODE")}
+  --image <img>          Docker image to deploy (no fly.toml needed)
+  --main-port <port>     Internal port for HTTP service (default: 80, "none" to skip)
+
+${bold("TEMPLATE MODE")}
+  --template <ref>       GitHub template as owner/repo/path[@ref]
+
+  Reference format:
+    owner/repo/path           Fetch from the default branch
+    owner/repo/path@tag       Fetch a tagged release
+    owner/repo/path@branch    Fetch a specific branch
+    owner/repo/path@commit    Fetch a specific commit
 
 ${bold("SAFETY")}
   Always deploys with --no-public-ips and --flycast.
@@ -52,6 +217,8 @@ ${bold("EXAMPLES")}
   ambit deploy my-app --network browsers
   ambit deploy my-app --network browsers --image registry/img:latest
   ambit deploy my-app --network browsers --config ./fly.toml --region sea
+  ambit deploy my-browser --network lab --template ToxicPine/ambit-templates/cdp
+  ambit deploy my-browser --network lab --template ToxicPine/ambit-templates/cdp@v1.0
 `);
         return;
     }
@@ -59,10 +226,11 @@ ${bold("EXAMPLES")}
     // ==========================================================================
     // Phase 0: Parse & Validate
     // ==========================================================================
-    const app = args._[0];
-    if (!app) {
+    const appArg = args._[0];
+    if (!appArg || typeof appArg !== "string") {
         return out.die("App Name Required. Usage: ambit deploy <app> --network <name>");
     }
+    const app = appArg;
     if (!args.network) {
         return out.die("--network Is Required");
     }
@@ -70,10 +238,11 @@ ${bold("EXAMPLES")}
         assertNotRouter(app);
     }
     catch (e) {
-        return out.die(e.message);
+        return out.die(e instanceof Error ? e.message : String(e));
     }
-    if (args.image && args.config) {
-        return out.die("--image and --config Are Mutually Exclusive");
+    const modeFlags = [args.image, args.config, args.template].filter(Boolean);
+    if (modeFlags.length > 1) {
+        return out.die("--image, --config, and --template Are Mutually Exclusive");
     }
     const network = args.network;
     out.blank()
@@ -128,44 +297,21 @@ ${bold("EXAMPLES")}
     }
     out.blank();
     // ==========================================================================
-    // Phase 4: Pre-flight TOML Scan
+    // Phase 4: Resolve Deploy Mode
     // ==========================================================================
     out.header("Step 4: Pre-flight Check").blank();
-    let preflight = { scanned: false, warnings: [] };
-    // Determine config path for config mode (not image mode)
-    let configPath = args.config;
-    if (!args.image) {
-        if (!configPath) {
-            // Auto-detect ./fly.toml
-            if (await fileExists("./fly.toml")) {
-                configPath = "./fly.toml";
-            }
-        }
-        if (configPath) {
-            if (!(await fileExists(configPath))) {
-                return out.die(`Config File Not Found: ${configPath}`);
-            }
-            const tomlContent = await dntShim.Deno.readTextFile(configPath);
-            const scan = scanFlyToml(tomlContent);
-            preflight = { scanned: scan.scanned, warnings: scan.warnings };
-            if (scan.errors.length > 0) {
-                for (const err of scan.errors) {
-                    out.err(err);
-                }
-                return out.die("Pre-flight Check Failed. Fix fly.toml Before Deploying.");
-            }
-            for (const warn of scan.warnings) {
-                out.warn(warn);
-            }
-            out.ok(`Scanned ${configPath}`);
-        }
-        else {
-            out.info("No fly.toml Found — Deploying Without Config Scan");
-        }
+    let deployConfig;
+    if (args.template) {
+        deployConfig = await resolveTemplateMode(args.template, out);
+    }
+    else if (args.image) {
+        deployConfig = resolveImageMode(args.image, String(args["main-port"]), out);
     }
     else {
-        out.info("Image Mode — Skipping TOML Scan");
+        deployConfig = await resolveConfigMode(args.config, out);
     }
+    if (!deployConfig)
+        return; // mode resolver already called out.die()
     out.blank();
     // ==========================================================================
     // Phase 5: Deploy with Enforced Flags
@@ -174,8 +320,8 @@ ${bold("EXAMPLES")}
     out.dim("Deploying with --no-public-ips --flycast ...");
     try {
         await fly.deploySafe(app, {
-            image: args.image,
-            config: configPath,
+            image: deployConfig.image,
+            config: deployConfig.configPath,
             region: args.region,
         });
     }
@@ -186,6 +332,14 @@ ${bold("EXAMPLES")}
         }
         throw e;
     }
+    finally {
+        if (deployConfig.tempDir) {
+            try {
+                dntShim.Deno.removeSync(deployConfig.tempDir, { recursive: true });
+            }
+            catch { /* ignore */ }
+        }
+    }
     out.ok("Deploy Succeeded");
     out.blank();
     // ==========================================================================
@@ -211,33 +365,23 @@ ${bold("EXAMPLES")}
     // Phase 7: Result
     // ==========================================================================
     const hasIssues = audit.public_ips_released > 0 || audit.warnings.length > 0;
+    const result = {
+        app,
+        network,
+        created,
+        audit: {
+            public_ips_released: audit.public_ips_released,
+            certs_removed: audit.certs_removed,
+            flycast_allocations: audit.flycast_allocations,
+            warnings: audit.warnings,
+        },
+        preflight: deployConfig.preflight,
+    };
     if (hasIssues) {
-        out.fail("Deploy Completed with Issues", {
-            app,
-            network,
-            created,
-            audit: {
-                public_ips_released: audit.public_ips_released,
-                certs_removed: audit.certs_removed,
-                flycast_allocations: audit.flycast_allocations,
-                warnings: audit.warnings,
-            },
-            preflight,
-        });
+        out.fail("Deploy Completed with Issues", result);
     }
     else {
-        out.done({
-            app,
-            network,
-            created,
-            audit: {
-                public_ips_released: audit.public_ips_released,
-                certs_removed: audit.certs_removed,
-                flycast_allocations: audit.flycast_allocations,
-                warnings: audit.warnings,
-            },
-            preflight,
-        });
+        out.done(result);
     }
     out.blank()
         .header("=".repeat(50))
@@ -255,6 +399,6 @@ ${bold("EXAMPLES")}
 registerCommand({
     name: "deploy",
     description: "Deploy an app safely on a custom private network",
-    usage: "ambit deploy <app> --network <name> [--image <img>] [--org <org>] [--region <region>]",
+    usage: "ambit deploy <app> --network <name> [--image <img>] [--template <ref>] [--org <org>] [--region <region>]",
     run: deploy,
 });

package/esm/src/cli/commands/status.js

@@ -78,9 +78,7 @@ const showNetworkStatus = async (fly, tailscale, args) => {
         .text(`  Region:        ${machine?.region ?? "unknown"}`)
         .text(`  Machine State: ${machine?.state ?? "unknown"}`)
         .text(`  Private IP:    ${machine?.privateIp ?? "unknown"}`)
-        .text(`  SOCKS Proxy:   ${machine?.privateIp
-        ? `socks5://[${machine.privateIp}]:1080`
-        : "unknown"}`);
+        .text(`  SOCKS Proxy:   ${machine?.privateIp ? `socks5://[${machine.privateIp}]:1080` : "unknown"}`);
     if (machine?.subnet) {
         out.text(`  Subnet:        ${machine.subnet}`);
     }

package/esm/src/cli/mod.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../../../src/src/cli/mod.ts"],"names":[],"mappings":"AAaA,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACxC;AAQD,eAAO,MAAM,eAAe,GAAI,SAAS,OAAO,KAAG,IAElD,CAAC;AAEF,eAAO,MAAM,UAAU,GAAI,MAAM,MAAM,KAAG,OAAO,GAAG,SAEnD,CAAC;AAEF,eAAO,MAAM,cAAc,QAAO,OAAO,EAExC,CAAC;AAQF,eAAO,MAAM,QAAQ,QAAO,IA4B3B,CAAC;AAEF,eAAO,MAAM,WAAW,QAAO,IAE9B,CAAC;AAMF,eAAO,MAAM,MAAM,GAAU,MAAM,MAAM,EAAE,KAAG,OAAO,CAAC,IAAI,CAuCzD,CAAC"}
+{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../../../src/src/cli/mod.ts"],"names":[],"mappings":"AAcA,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACxC;AAQD,eAAO,MAAM,eAAe,GAAI,SAAS,OAAO,KAAG,IAElD,CAAC;AAEF,eAAO,MAAM,UAAU,GAAI,MAAM,MAAM,KAAG,OAAO,GAAG,SAEnD,CAAC;AAEF,eAAO,MAAM,cAAc,QAAO,OAAO,EAExC,CAAC;AAQF,eAAO,MAAM,QAAQ,QAAO,IA4B3B,CAAC;AAEF,eAAO,MAAM,WAAW,QAAO,IAE9B,CAAC;AAMF,eAAO,MAAM,MAAM,GAAU,MAAM,MAAM,EAAE,KAAG,OAAO,CAAC,IAAI,CAuCzD,CAAC"}

package/esm/src/cli/mod.js

@@ -4,6 +4,7 @@
 import * as dntShim from "../../_dnt.shims.js";
 import { parseArgs } from "../../deps/jsr.io/@std/cli/1.0.27/mod.js";
 import { bold, dim } from "../../lib/cli.js";
+import denoConfig from "../../deno.js";
 // =============================================================================
 // Commands Registry
 // =============================================================================
@@ -20,7 +21,7 @@ export const getAllCommands = () => {
 // =============================================================================
 // Help Text
 // =============================================================================
-const VERSION = "0.3.0";
+const VERSION = denoConfig.version;
 export const showHelp = () => {
     console.log(`
 ${bold("ambit")} - Tailscale Subnet Router for Fly.io Custom Networks
@@ -65,7 +66,7 @@ export const runCli = async (argv) => {
         showVersion();
         return;
     }
-    const commandName = args._[0];
+    const commandName = typeof args._[0] === "string" ? args._[0] : undefined;
     if (!commandName || args.help) {
         if (commandName) {
             const command = getCommand(commandName);

package/esm/src/schemas/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../src/src/schemas/config.ts"],"names":[],"mappings":"AAOA,OAAO,yBAAyB,CAAC;AAKjC,eAAO,MAAM,YAAY,GAAI,SAAS,MAAM,KAAG,MACvB,CAAC;AAEzB,eAAO,MAAM,aAAa,GAAI,WAAW,MAAM,KAAG,MAKjD,CAAC;AAMF,eAAO,MAAM,YAAY,QAAO,MAG/B,CAAC"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../src/src/schemas/config.ts"],"names":[],"mappings":"AAOA,OAAO,yBAAyB,CAAC;AAKjC,eAAO,MAAM,YAAY,GAAI,SAAS,MAAM,KAAG,MAAgC,CAAC;AAEhF,eAAO,MAAM,aAAa,GAAI,WAAW,MAAM,KAAG,MAKjD,CAAC;AAMF,eAAO,MAAM,YAAY,QAAO,MAG/B,CAAC"}

package/esm/src/template.d.ts

@@ -0,0 +1,38 @@
+import type { Result } from "../lib/result.js";
+/** Kinds of errors that can occur when fetching a template from GitHub. */
+export type TemplateErrorKind = "NotFound" | "RateLimited" | "HttpError" | "ExtractionFailed" | "PathNotFound" | "PathNotDirectory" | "EmptyArchive" | "NetworkError";
+/** Parsed GitHub template reference. */
+export interface TemplateRef {
+    owner: string;
+    repo: string;
+    path: string;
+    ref: string | undefined;
+}
+/** Result of fetching a template from GitHub. */
+export type TemplateFetchResult = Result<{
+    tempDir: string;
+    templateDir: string;
+}, TemplateErrorKind>;
+/**
+ * Parse a template reference string into its components.
+ * Returns null if the format is invalid.
+ *
+ * Format: owner/repo/path[@ref]
+ *
+ * The first two segments are always owner/repo. Everything after the second
+ * slash up to an optional @ref is the path within the repository. This is
+ * unambiguous because GitHub owner and repo names cannot contain slashes.
+ */
+export declare const parseTemplateRef: (raw: string) => TemplateRef | null;
+/**
+ * Download a template from GitHub and extract the target subdirectory
+ * to a temp directory.
+ *
+ * On success, returns the temp dir (for cleanup) and the path to the
+ * extracted template directory. The caller is responsible for removing
+ * tempDir when done.
+ *
+ * On failure, cleans up the temp dir and returns a typed error.
+ */
+export declare const fetchTemplate: (ref: TemplateRef) => Promise<TemplateFetchResult>;
+//# sourceMappingURL=template.d.ts.map

package/esm/src/template.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"template.d.ts","sourceRoot":"","sources":["../../src/src/template.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAM/C,2EAA2E;AAC3E,MAAM,MAAM,iBAAiB,GACzB,UAAU,GACV,aAAa,GACb,WAAW,GACX,kBAAkB,GAClB,cAAc,GACd,kBAAkB,GAClB,cAAc,GACd,cAAc,CAAC;AAMnB,wCAAwC;AACxC,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;CACzB;AAED,iDAAiD;AACjD,MAAM,MAAM,mBAAmB,GAAG,MAAM,CACtC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,EACxC,iBAAiB,CAClB,CAAC;AA4BF;;;;;;;;;GASG;AACH,eAAO,MAAM,gBAAgB,GAAI,KAAK,MAAM,KAAG,WAAW,GAAG,IAyB5D,CAAC;AAMF;;;;;;;;;GASG;AACH,eAAO,MAAM,aAAa,GACxB,KAAK,WAAW,KACf,OAAO,CAAC,mBAAmB,CAsH7B,CAAC"}

package/esm/src/template.js

@@ -0,0 +1,159 @@
+// =============================================================================
+// Template - Fetch Deploy Templates from GitHub Repositories
+// =============================================================================
+//
+// Downloads a subdirectory from a GitHub repository for use as a deploy
+// template. Templates are expected to contain at least a fly.toml and
+// typically a Dockerfile.
+//
+// Reference format: owner/repo/path[@ref]
+//
+//   ToxicPine/ambit-templates/cdp          → default branch
+//   ToxicPine/ambit-templates/cdp@v1.0     → tagged release
+//   ToxicPine/ambit-templates/cdp@main     → explicit branch
+//
+// =============================================================================
+import * as dntShim from "../_dnt.shims.js";
+import { join } from "../deps/jsr.io/@std/path/1.1.4/mod.js";
+import { runCommand } from "../lib/command.js";
+// =============================================================================
+// Internal Helpers
+// =============================================================================
+/** Shorthand for returning a typed fetch error. */
+const fail = (kind, message) => ({
+    ok: false,
+    kind,
+    message,
+});
+/** Format a template reference for display. */
+const formatRef = (ref) => `${ref.owner}/${ref.repo}/${ref.path}` + (ref.ref ? `@${ref.ref}` : "");
+/** Format owner/repo with optional ref for display. */
+const formatRepo = (ref) => `${ref.owner}/${ref.repo}` + (ref.ref ? `@${ref.ref}` : "");
+// =============================================================================
+// Parse Template Reference
+// =============================================================================
+/**
+ * Parse a template reference string into its components.
+ * Returns null if the format is invalid.
+ *
+ * Format: owner/repo/path[@ref]
+ *
+ * The first two segments are always owner/repo. Everything after the second
+ * slash up to an optional @ref is the path within the repository. This is
+ * unambiguous because GitHub owner and repo names cannot contain slashes.
+ */
+export const parseTemplateRef = (raw) => {
+    // Split off @ref suffix
+    const atIndex = raw.lastIndexOf("@");
+    let body;
+    let ref;
+    if (atIndex > 0) {
+        body = raw.slice(0, atIndex);
+        ref = raw.slice(atIndex + 1);
+        if (!ref)
+            return null;
+    }
+    else {
+        body = raw;
+    }
+    // Need at least owner/repo/path
+    const parts = body.split("/");
+    if (parts.length < 3)
+        return null;
+    const owner = parts[0];
+    const repo = parts[1];
+    const path = parts.slice(2).join("/");
+    if (!owner || !repo || !path)
+        return null;
+    return { owner, repo, path, ref };
+};
+// =============================================================================
+// Fetch Template
+// =============================================================================
+/**
+ * Download a template from GitHub and extract the target subdirectory
+ * to a temp directory.
+ *
+ * On success, returns the temp dir (for cleanup) and the path to the
+ * extracted template directory. The caller is responsible for removing
+ * tempDir when done.
+ *
+ * On failure, cleans up the temp dir and returns a typed error.
+ */
+export const fetchTemplate = async (ref) => {
+    const tempDir = dntShim.Deno.makeTempDirSync({ prefix: "ambit-template-" });
+    const cleanup = () => {
+        try {
+            dntShim.Deno.removeSync(tempDir, { recursive: true });
+        }
+        catch { /* ignore */ }
+    };
+    const cleanFail = (kind, message) => {
+        cleanup();
+        return fail(kind, message);
+    };
+    try {
+        const url = ref.ref
+            ? `https://api.github.com/repos/${ref.owner}/${ref.repo}/tarball/${ref.ref}`
+            : `https://api.github.com/repos/${ref.owner}/${ref.repo}/tarball`;
+        const response = await fetch(url, {
+            headers: {
+                Accept: "application/vnd.github+json",
+                "User-Agent": "ambit-cli",
+            },
+        });
+        if (!response.ok) {
+            const repo = formatRepo(ref);
+            if (response.status === 404) {
+                return cleanFail("NotFound", `Template Repository Not Found: ${repo}. ` +
+                    "Check that the repository exists and is public.");
+            }
+            if (response.status === 403) {
+                return cleanFail("RateLimited", "GitHub API Rate Limit Exceeded. Try again later.");
+            }
+            return cleanFail("HttpError", `GitHub API Returned HTTP ${response.status} for ${repo}`);
+        }
+        // Write tarball to disk
+        const tarballPath = join(tempDir, "template.tar.gz");
+        const tarball = new Uint8Array(await response.arrayBuffer());
+        dntShim.Deno.writeFileSync(tarballPath, tarball);
+        // Extract
+        const extractDir = join(tempDir, "extract");
+        dntShim.Deno.mkdirSync(extractDir);
+        const extractResult = await runCommand([
+            "tar",
+            "xzf",
+            tarballPath,
+            "-C",
+            extractDir,
+        ]);
+        if (!extractResult.success) {
+            return cleanFail("ExtractionFailed", "Failed to Extract Template Archive");
+        }
+        // GitHub tarballs have a single top-level dir (owner-repo-commitish/)
+        const entries = [...dntShim.Deno.readDirSync(extractDir)];
+        const topLevel = entries.find((e) => e.isDirectory);
+        if (!topLevel) {
+            return cleanFail("EmptyArchive", "Template Archive Has No Top-Level Directory");
+        }
+        // Locate the template subdirectory
+        const templateDir = join(extractDir, topLevel.name, ref.path);
+        try {
+            const stat = dntShim.Deno.statSync(templateDir);
+            if (!stat.isDirectory) {
+                return cleanFail("PathNotDirectory", `Template Path '${ref.path}' Is Not a Directory in ${formatRepo(ref)}`);
+            }
+        }
+        catch {
+            return cleanFail("PathNotFound", `Template Path '${ref.path}' Not Found in ${formatRepo(ref)}`);
+        }
+        return { ok: true, tempDir, templateDir };
+    }
+    catch (e) {
+        if (e instanceof TypeError) {
+            return cleanFail("NetworkError", "Network Error: Could Not Reach GitHub");
+        }
+        cleanup();
+        throw e;
+    }
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@cardelli/ambit",
-  "version": "0.1.1",
-  "description": "Tailscale subnet router manager for Fly.io custom networks",
+  "version": "0.1.3",
+  "description": "Deploy apps to the cloud that only you and your AI agents can reach",
   "license": "MIT",
   "module": "./esm/src/providers/fly.js",
   "exports": {