@domesystems/templates 0.1.0 → 0.2.0

package/README.md

@@ -1,168 +1,59 @@
-# Dome templates
+# Dome Templates CLI
 
-Reusable, importable governed-agent templates. Each template combines an HCL
-configuration bundle for Dome with an optional companion application.
+Download, configure, and run governed-agent templates from the Dome Template
+Library. The package contains no template source: each template is fetched as a
+versioned ZIP archive from the Library when you run `init` or `up`.
 
-## Use the template CLI
+## Install and run
 
-The public package is also an executable. It copies the template, creates a
-local `.env` from `.env.example`, and generates the Compose file from the
-runtime declaration in `template.yaml` — individual templates do not need a
-Dockerfile or a committed Compose file.
+Use `npx`; Node.js 20 or newer is required.
 
 ```bash
-# Create a working copy in ./ai-agent-for-documentation.
+# Download a template into ./ai-agent-for-documentation.
 npx @domesystems/templates init ai-agent-for-documentation
 
-# Initialize when needed, provision Dome, then start the selected runtime.
+# Download if needed, provision Dome, and run it locally.
 npx @domesystems/templates up ai-agent-for-documentation
 ```
 
-`up` runs `dome import dome.tf`, then `docker compose` with a generated,
-Git-ignored `.dome-compose.yaml`. Use `--no-start` to provision without
-starting a container, `--skip-provision` to start an already-provisioned
-template, `--detach` for a background container, and `--dir <directory>` to
-choose a local destination.
+By default, archives come from
+`https://templates.domesystems.ai/templates/downloads/<template>.zip`.
 
-Runtime selection is explicit rather than guessed:
-
-```yaml
-app:
-  runtime:
-    pattern: chat         # chat or run
-    language: python      # python or typescript
-    image_tag: "0.1.0"    # optional; defaults to latest
-```
-
-The CLI maps `language` and `pattern` to a shared, published runtime image.
-For an unusual runtime, set `app.runtime.image` to a complete image reference
-(including its tag) to override that mapping.
-Add a template directory to the package's `files` list when publishing a new
-template so the CLI can discover it.
-
-## Use a template
+For local Library development, point the CLI at a local download server:
 
 ```bash
-git clone https://github.com/dome-systems/templates.git
-cd templates/<template>
-
-brew install dome-systems/tap/dome
-dome auth login
-dome sandbox provision
-
-# Preview resources, variables, and required permissions. Changes nothing.
-dome import dome.tf --plan-only
-
-# Apply after reviewing the preview. Dome prompts for required variables.
-dome import dome.tf
+DOME_TEMPLATES_BASE_URL=http://localhost:3001/templates/downloads \
+  npx @domesystems/templates init ai-agent-for-documentation
 ```
 
-Imports run as asynchronous jobs in Dome. Existing resources are converged by
-name, missing resources are created, and any destructive replacement is
-refused. Secrets are input variables: they are never committed to a template
-or returned in an export.
-
-Every built companion app needs the one-time agent token created by the import:
-
-```bash
-dome import outputs <job-id>
-cp .env.example .env
-docker compose up
-```
-
-Tool and model credentials remain in Dome; the app only holds its agent token.
-
-### Runtime image
-
-Templates do not build a runtime themselves. In development, clone the sibling
-`dome-systems/template-runtime` repository and build the archetype image before
-starting a template:
-
-```bash
-cd template-runtime
-docker build -f Dockerfile.chat -t ghcr.io/dome-systems/runtime-py-chat:dev .
-docker build -f Dockerfile.run -t ghcr.io/dome-systems/runtime-py-run:dev .
-```
-
-TypeScript equivalents are available as `ghcr.io/dome-systems/runtime-ts-chat`
-and `ghcr.io/dome-systems/runtime-ts-run`; substitute either image in a template's Compose file
-when using the Node runtime.
-
-The CLI-generated Compose configuration uses the appropriate image and mounts
-only the template's local `app/` configuration. Release templates should set a
-versioned `app.runtime.image_tag` rather than relying on `latest`.
+## Commands
 
-## Runtime contract
-
-Every built companion app follows the same small operational contract:
-
-| Surface | Guarantee |
-|---|---|
-| `.env.example` | The complete committed list of values a local operator may need. It contains names and setup guidance, never real values. |
-| `docker-compose.yml` | Starts the app on port `3000`, loads `.env`, mounts `app/` read-only, and declares the health check. |
-| `GET /health` | Liveness only: returns `200 {"status":"ok"}` without calling Dome or an upstream system. Offline mode is valid. `/healthz` is an equivalent compatibility alias. |
-| `GET /readyz` | Readiness of the initialized runtime API. Returns `200`; its `mode` is `live` or `offline`. |
-| Docker `HEALTHCHECK` | Probes `/health`; inherited by every shared runtime image and repeated in Compose for a visible local contract. |
-
-The Library renders each template's committed `.env.example` verbatim, so setup
-requirements have one source of truth. Add a new variable there when the
-companion app needs it; use `app.options.env` in `template.yaml` as well when
-that value is interpolated into an agent prompt, starter, or help text.
-
-## Archetype containers
-
-The separate `dome-systems/template-runtime` repository builds one image per app
-shape. They contain no template-specific code — a template mounts an
-`app/agent.yaml` giving its **prompt**, its **skills** and its **invoker**, which
-is the shape the Dome agent runtime will take, so swapping a container for the
-real runner is a config move rather than a rewrite.
-
-Four UIs cover all 249 templates. A report is a run whose output is a table; an approval
-console is a queue with two extra buttons.
-
-| Archetype | Covers | Shapes | State |
-|---|---|---|---|
-| `ghcr.io/dome-systems/runtime-py-chat` | 66 | interactive-assistant | Built |
-| `ghcr.io/dome-systems/runtime-py-run` | 120 | scheduled-job, report-dashboard | Built |
-| `dome/template-queue` | 48 | triage-queue, approval-console | Not built |
-| `dome/template-console` | 15 | external-service, developer-harness | Not built |
-
-The governance drawer is shared chrome across all four, not a per-archetype feature.
-
-Tools go through the Gateway over MCP; models go through the Broker's
-Anthropic-compatible ingress. Both authenticate with the same agent token, which is why
-the container holds one secret and no provider key. Without `DOME_TOKEN` it starts in
-offline mode: the chrome works and the allow-list is still enforced, but tools and model
-are simulated.
-
-## What is source and what is generated
-
-`dome.tf` is the configuration source of truth for Dome resources. It is a
-portable HCL bundle that `dome import` can inspect, preview, and apply.
-`template.yaml` is catalog metadata and the source of truth for choosing the
-shared local runtime; `rules/*.cedar` and `app/instructions.md` are
-human-authored source.
-
-## Relationship to the Template Library
-
-This repository is the Library's only template-content source. A merge to `main`
-dispatches its commit SHA to `dome-systems/web-library`; that repository checks out
-and builds the exact revision, then opens or updates one source-refresh PR. The
-Library does not copy or edit template content, and a refresh PR must be merged
-before the new source can be published.
-
-The dispatch uses the `LIBRARY_SOURCE_SYNC_TOKEN` repository secret. It needs a
-fine-grained token that may dispatch workflows in `dome-systems/web-library`.
-
-## Validation
-
-Run the metadata and source-reference checks locally:
-
-```bash
-npm install
-npm run validate
-terraform fmt -check -recursive
+```text
+npx @domesystems/templates init <template> [--dir <directory>] [--force]
+npx @domesystems/templates up <template> [--dir <directory>] [--port <host-port>] [--skip-provision] [--provision] [--no-start] [--detach] [--verbose] [--force]
 ```
 
-CI runs the same checks. A plan-only import against a designated Dome sandbox can
-be added when CI has an appropriate non-production workspace and credentials.
+| Command | Option | What it does |
+|---|---|---|
+| `init` | `--dir <directory>` | Downloads into this directory. Defaults to `./<template>`. |
+| `init` | `--force` | Allows a non-empty destination; downloaded source files can replace existing files. |
+| `up` | `--dir <directory>` | Uses this existing template directory, or downloads it when it does not exist. |
+| `up` | `--port <host-port>` | Publishes the runtime at `http://localhost:<host-port>`; default `3000`. |
+| `up` | `--skip-provision` | Does not run `dome import`. |
+| `up` | `--provision` | Re-imports Dome resources even when local credentials already exist. |
+| `up` | `--no-start` | Does not start Docker after setup. |
+| `up` | `--detach` | Starts Docker Compose in the background. |
+| `up` | `--verbose` | Shows generated Compose details and the full Dome import response. |
+| `up` | `--force` | Allows a non-empty destination only when `up` needs to download it. |
+
+`up` reuses a configured `.env` by default, so routine restarts do not import
+resources again. Use `--provision` after changing the template’s Dome
+resources. Status markers are colored in compatible terminals; set `NO_COLOR=1`
+to turn colors off.
+
+## Security and source
+
+The CLI accepts only archives whose contents live below the requested template
+directory. It rejects traversal paths, unsupported archive entries, oversized
+downloads, and archives without `template.yaml` before copying files into your
+project. The Template Library controls the ZIP contents and current revision.

package/bin/dome-templates.mjs

@@ -2,4 +2,4 @@
 
 import { main } from "../src/cli.mjs";
 
-main(process.argv.slice(2));
+await main(process.argv.slice(2));

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@domesystems/templates",
-  "version": "0.1.0",
-  "description": "Initialize and run Dome governed-agent templates.",
+  "version": "0.2.0",
+  "description": "Download, initialize, and run Dome governed-agent templates.",
   "type": "module",
   "bin": {
     "dome-templates": "bin/dome-templates.mjs"
@@ -9,9 +9,7 @@
   "files": [
     "bin",
     "src",
-    "ai-agent-for-documentation",
-    "ai-agent-for-notion",
-    "ai-agent-for-release-notes"
+    "README.md"
   ],
   "engines": {
     "node": ">=20"
@@ -24,6 +22,8 @@
     "test": "node --test"
   },
   "dependencies": {
+    "unzipper": "0.12.3",
+    "unzipper": "0.12.3",
     "yaml": "2.9.0"
   }
 }

package/src/cli.mjs

@@ -1,15 +1,29 @@
 import fs from "node:fs";
 import path from "node:path";
-import { fileURLToPath } from "node:url";
-import { spawnSync } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
+import readline from "node:readline/promises";
 import { readManifest } from "./manifest.mjs";
 import { imageForRuntime, renderCompose } from "./runtime.mjs";
-import { copyTemplate, initializeEnvironment } from "./template-files.mjs";
+import { downloadTemplate, initializeEnvironment } from "./template-files.mjs";
 
-const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const supportsColor = process.stdout.isTTY && !process.env.NO_COLOR;
+
+function color(code, text) {
+  return supportsColor ? `\u001B[${code}m${text}\u001B[0m` : text;
+}
+
+function status(kind, message) {
+  const styles = {
+    info: ["●", "36"],
+    success: ["✓", "32"],
+    warning: ["→", "33"],
+  };
+  const [marker, code] = styles[kind];
+  return `${color(code, marker)} ${message}`;
+}
 
 function usage() {
-  return `Usage:\n  npx @domesystems/templates init <template> [--dir <directory>] [--force]\n  npx @domesystems/templates up <template> [--dir <directory>] [--skip-provision] [--no-start] [--detach] [--force]\n\nCommands:\n  init  Copy a template locally and create .env from .env.example.\n  up    Initialize (when needed), generate Compose from template.yaml, provision Dome, and start it.\n\nThe generated .dome-compose.yaml is ignored by Git. Runtime images are selected\nfrom app.runtime.language and app.runtime.pattern in template.yaml.\n`;
+  return `Usage:\n  npx @domesystems/templates init <template> [--dir <directory>] [--force]\n  npx @domesystems/templates up <template> [--dir <directory>] [--port <host-port>] [--skip-provision] [--provision] [--no-start] [--detach] [--verbose] [--force]\n\nCommands:\n  init  Download a template locally and create .env from .env.example.\n  up    Download when needed, generate Compose from template.yaml, provision Dome, and start it.\n\nTemplates are downloaded from templates.domesystems.ai by default. A configured\nlocal .env skips provisioning automatically. Use --provision to re-sync\nexisting resources. Use --port to choose the local host port (default: 3000).\nThe generated .dome-compose.yaml is ignored by Git. Use --verbose to show the\nfull Dome import response for troubleshooting.\n`;
 }
 
 function fail(message) {
@@ -19,13 +33,21 @@ function fail(message) {
 function parseArguments(argv) {
   if (argv.length === 0 || argv.includes("--help") || argv.includes("-h")) return { help: true };
   const [command, slug, ...rest] = argv;
-  const options = { force: false, provision: true, start: true, detach: false, directory: undefined };
+  const options = { force: false, provision: true, forceProvision: false, start: true, detach: false, verbose: false, directory: undefined, port: 3000 };
   for (let index = 0; index < rest.length; index += 1) {
     const argument = rest[index];
     if (argument === "--force") options.force = true;
     else if (argument === "--skip-provision") options.provision = false;
+    else if (argument === "--provision") options.forceProvision = true;
     else if (argument === "--no-start") options.start = false;
     else if (argument === "--detach") options.detach = true;
+    else if (argument === "--verbose") options.verbose = true;
+    else if (argument === "--port") {
+      const port = Number(rest[index + 1]);
+      if (!Number.isInteger(port) || port < 1 || port > 65535) fail("--port requires an integer from 1 to 65535.");
+      options.port = port;
+      index += 1;
+    }
     else if (argument === "--dir") {
       options.directory = rest[index + 1];
       if (!options.directory) fail("--dir requires a directory.");
@@ -39,15 +61,10 @@ function parseArguments(argv) {
   return { command, slug, options };
 }
 
-function templateSource(slug) {
+function validateTemplateSlug(slug) {
   if (slug.includes("/") || slug.includes("\\") || slug === "." || slug === "..") {
     fail(`Invalid template slug: ${slug}`);
   }
-  const source = path.join(packageRoot, slug);
-  if (!fs.statSync(path.join(source, "template.yaml"), { throwIfNoEntry: false })?.isFile()) {
-    fail(`Unknown template: ${slug}`);
-  }
-  return source;
 }
 
 function targetDirectory(slug, directory) {
@@ -58,23 +75,39 @@ function isEmpty(directory) {
   return !fs.existsSync(directory) || fs.readdirSync(directory).length === 0;
 }
 
-function init(slug, options, output) {
-  const source = templateSource(slug);
+async function init(slug, options, output, fetchImplementation) {
+  validateTemplateSlug(slug);
   const target = targetDirectory(slug, options.directory);
   if (!isEmpty(target) && !options.force) {
     throw new Error(`${target} already exists and is not empty. Choose --dir or pass --force.`);
   }
-  copyTemplate(source, target);
+  output(status("info", `Downloading ${slug}…`));
+  const archiveURL = await downloadTemplate(slug, target, {
+    baseURL: process.env.DOME_TEMPLATES_BASE_URL,
+    fetchImplementation,
+  });
   const environmentCreated = initializeEnvironment(target);
-  output(`Initialized ${slug} in ${target}.`);
-  if (environmentCreated) output("Created .env from .env.example. Add the required values before a live run.");
+  output(status("success", `Downloaded ${slug} from ${archiveURL}.`));
+  if (environmentCreated) {
+    output("Created .env from .env.example.");
+    output("When you run `up`, Dome will prompt for import credentials; they are never written to .env.");
+    output("After import, `up` writes DOME_TOKEN and DOME_GATEWAY_URL into .env. Add any other template-specific runtime values before starting.");
+  }
   return target;
 }
 
-function resolveUpDirectory(slug, options, output) {
+async function resolveUpDirectory(slug, options, output, fetchImplementation) {
   const target = targetDirectory(slug, options.directory);
-  if (fs.statSync(path.join(target, "template.yaml"), { throwIfNoEntry: false })?.isFile()) return target;
-  return init(slug, options, output);
+  if (fs.statSync(path.join(target, "template.yaml"), { throwIfNoEntry: false })?.isFile()) {
+    const environmentCreated = initializeEnvironment(target);
+    if (environmentCreated) {
+      output("Created .env from .env.example.");
+      output("When you run `up`, Dome will prompt for import credentials; they are never written to .env.");
+      output("After import, `up` writes DOME_TOKEN and DOME_GATEWAY_URL into .env. Add any other template-specific runtime values before starting.");
+    }
+    return target;
+  }
+  return init(slug, options, output, fetchImplementation);
 }
 
 function run(command, args, cwd) {
@@ -83,7 +116,150 @@ function run(command, args, cwd) {
   if (result.status !== 0) throw new Error(`${command} ${args.join(" ")} exited with status ${result.status}.`);
 }
 
-export function main(argv, { output = console.log, error = console.error } = {}) {
+function parseFinalJSON(output, command) {
+  const starts = [...output.matchAll(/(?:^|\n)\{/g)].map((match) => match.index + (match[0][0] === "\n" ? 1 : 0));
+  for (const start of starts.reverse()) {
+    try {
+      return JSON.parse(output.slice(start));
+    } catch {
+      // The CLI may have printed an interactive prompt before its final JSON result.
+    }
+  }
+  throw new Error(`${command} completed without a readable JSON result.`);
+}
+
+function runJSON(command, args, cwd, { displayOutput = true } = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, { cwd, stdio: ["inherit", "pipe", "inherit"] });
+    let output = "";
+    let displayed = 0;
+    child.stdout.on("data", (chunk) => {
+      const text = chunk.toString();
+      output += text;
+      if (displayOutput === true) {
+        process.stdout.write(text);
+        displayed = output.length;
+      } else if (displayOutput === "before-final-json") {
+        const match = /(?:^|\n)\{/.exec(output);
+        if (match) {
+          const jsonStart = match.index + (match[0][0] === "\n" ? 1 : 0);
+          if (jsonStart > displayed) process.stdout.write(output.slice(displayed, jsonStart));
+          displayed = jsonStart;
+        } else {
+          process.stdout.write(text);
+          displayed = output.length;
+        }
+      }
+    });
+    child.on("error", (error) => reject(new Error(`Could not run ${command}: ${error.message}`)));
+    child.on("close", (status) => {
+      if (status !== 0) {
+        reject(new Error(`${command} ${args.join(" ")} exited with status ${status}.`));
+        return;
+      }
+      try {
+        resolve(parseFinalJSON(output, command));
+      } catch (error) {
+        reject(error);
+      }
+    });
+  });
+}
+
+function importSummary(response) {
+  const results = response.data?.job?.results ?? [];
+  const counts = new Map();
+  for (const result of results) counts.set(result.action, (counts.get(result.action) ?? 0) + 1);
+  if (counts.size === 0) return "Dome import completed.";
+  const descriptions = [...counts].map(([action, count]) => `${count} ${action}${count === 1 ? "" : "s"}`);
+  return `Dome import complete: ${descriptions.join(", ")}.`;
+}
+
+function replaceEnvironmentValue(source, name, value) {
+  const expression = new RegExp(`^${name}=.*$`, "m");
+  if (!expression.test(source)) throw new Error(`The runtime .env is missing ${name}.`);
+  return source.replace(expression, `${name}=${JSON.stringify(value)}`);
+}
+
+function undefinedEnvironmentValues(source) {
+  return source
+    .split(/\r?\n/)
+    .map((line) => line.match(/^([A-Za-z_][A-Za-z0-9_]*)=(?:\s*|""|''|undefined)$/)?.[1])
+    .filter(Boolean);
+}
+
+function runtimeEnvironmentIsConfigured(target) {
+  const environmentPath = path.join(target, ".env");
+  if (!fs.statSync(environmentPath, { throwIfNoEntry: false })?.isFile()) return false;
+  const environment = fs.readFileSync(environmentPath, "utf8");
+  const missing = new Set(undefinedEnvironmentValues(environment));
+  return ["DOME_TOKEN", "DOME_GATEWAY_URL"].every(
+    (name) => new RegExp(`^${name}=`, "m").test(environment) && !missing.has(name),
+  );
+}
+
+async function fillRuntimeEnvironment(target, output) {
+  const environmentPath = path.join(target, ".env");
+  let environment = fs.readFileSync(environmentPath, "utf8");
+  const missing = undefinedEnvironmentValues(environment);
+  if (missing.length === 0) return;
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    throw new Error(`Missing runtime .env values: ${missing.join(", ")}. Set them before starting Docker.`);
+  }
+
+  output(`Complete ${environmentPath} before starting the app.`);
+  const terminal = readline.createInterface({ input: process.stdin, output: process.stdout, terminal: true });
+  const write = terminal._writeToOutput.bind(terminal);
+  terminal._writeToOutput = (text) => {
+    if (text === "\n" || text === "\r\n") write(text);
+  };
+  try {
+    for (const name of missing) {
+      const value = (await terminal.question(`Enter ${name}: `)).trim();
+      if (!value) throw new Error(`${name} is required to start the app.`);
+      environment = replaceEnvironmentValue(environment, name, value);
+    }
+  } finally {
+    terminal.close();
+  }
+  fs.writeFileSync(environmentPath, environment);
+  output(`Saved runtime values to ${environmentPath}.`);
+}
+
+function gatewayURL(response) {
+  return response.data?.gateway?.endpoints?.gatewayUrl ?? response.data?.gateway?.endpoints?.gateway_url;
+}
+
+async function writeRuntimeEnvironment(target, manifest, importResponse, output) {
+  const jobID = importResponse.data?.job?.id;
+  if (!jobID) throw new Error("Dome import succeeded but did not return an import job ID.");
+
+  const gatewayName = manifest.catalog?.gateway?.name;
+  if (!gatewayName) throw new Error("template.yaml must declare catalog.gateway.name to configure the runtime.");
+
+  const environmentPath = path.join(target, ".env");
+  let environment = fs.readFileSync(environmentPath, "utf8");
+  // Validate the local contract before consuming a one-time secret.
+  for (const name of ["DOME_TOKEN", "DOME_GATEWAY_URL"]) {
+    if (!new RegExp(`^${name}=.*$`, "m").test(environment)) throw new Error(`The runtime .env is missing ${name}.`);
+  }
+
+  const gateway = await runJSON("dome", ["gateways", "get", gatewayName, "--format", "json"], target, { displayOutput: false });
+  const url = gatewayURL(gateway);
+  if (!url) throw new Error(`Gateway ${gatewayName} has no runtime endpoint.`);
+
+  const revealed = await runJSON("dome", ["import", "outputs", jobID, "--format", "json"], target, { displayOutput: false });
+  const outputs = revealed.data?.outputs ?? {};
+  const tokens = Object.entries(outputs).filter(([name, value]) => name.endsWith("_token") && value);
+  if (tokens.length !== 1) throw new Error("The import must produce exactly one *_token output to configure DOME_TOKEN.");
+
+  environment = replaceEnvironmentValue(environment, "DOME_TOKEN", tokens[0][1]);
+  environment = replaceEnvironmentValue(environment, "DOME_GATEWAY_URL", url);
+  fs.writeFileSync(environmentPath, environment);
+  output(`Configured ${environmentPath} with the one-time agent token and Gateway URL.`);
+}
+
+export async function main(argv, { output = console.log, error = console.error, fetchImplementation = globalThis.fetch } = {}) {
   try {
     const parsed = parseArguments(argv);
     if (parsed.help) {
@@ -92,18 +268,35 @@ export function main(argv, { output = console.log, error = console.error } = {})
     }
     const { command, slug, options } = parsed;
     if (command === "init") {
-      init(slug, options, output);
+      await init(slug, options, output, fetchImplementation);
       return;
     }
 
-    const target = resolveUpDirectory(slug, options, output);
+    const target = await resolveUpDirectory(slug, options, output, fetchImplementation);
     const manifest = readManifest(target);
     const composePath = path.join(target, ".dome-compose.yaml");
-    fs.writeFileSync(composePath, renderCompose(manifest.app.runtime));
-    output(`Generated ${path.basename(composePath)} using ${imageForRuntime(manifest.app.runtime)}.`);
+    fs.writeFileSync(composePath, renderCompose(manifest.app.runtime, options.port));
+    if (options.verbose) {
+      output(status("info", `Generated ${path.basename(composePath)} with ${imageForRuntime(manifest.app.runtime)} for http://localhost:${options.port}.`));
+    }
 
-    if (options.provision) run("dome", ["import", "dome.tf"], target);
+    const alreadyProvisioned = runtimeEnvironmentIsConfigured(target);
+    if (options.provision && alreadyProvisioned && !options.forceProvision) {
+      const nextStep = options.start
+        ? "Dome is already set up — starting the app. To update Dome resources later, use --provision."
+        : "Dome is already set up. To update Dome resources later, use --provision.";
+      output(status("success", nextStep));
+    } else if (options.provision) {
+      output(status("info", "Setting up Dome resources…"));
+      const imported = await runJSON("dome", ["import", "dome.tf", "--format", "json"], target, {
+        displayOutput: options.verbose ? true : "before-final-json",
+      });
+      if (!options.verbose) output(status("success", importSummary(imported)));
+      await writeRuntimeEnvironment(target, manifest, imported, output);
+    }
     if (options.start) {
+      await fillRuntimeEnvironment(target, output);
+      output(status("info", `Starting app at http://localhost:${options.port}…`));
       const args = ["compose", "-f", ".dome-compose.yaml", "up"];
       if (options.detach) args.push("--detach");
       run("docker", args, target);

package/src/runtime.mjs

@@ -16,7 +16,7 @@ export function imageForRuntime(runtime) {
   return `${image}:${runtime.image_tag ?? "latest"}`;
 }
 
-export function renderCompose(runtime) {
+export function renderCompose(runtime, hostPort = 3000) {
   const image = imageForRuntime(runtime);
-  return `# Generated by @domesystems/templates. Do not edit; update template.yaml instead.\nservices:\n  app:\n    image: ${image}\n    env_file: .env\n    volumes:\n      - ./app:/config:ro\n    ports:\n      - \"3000:3000\"\n    healthcheck:\n      test: [\"CMD\", \"python\", \"-c\", \"import urllib.request; urllib.request.urlopen('http://127.0.0.1:3000/health', timeout=2)\"]\n      interval: 30s\n      timeout: 3s\n      start_period: 10s\n      retries: 3\n`;
+  return `# Generated by @domesystems/templates. Do not edit; update template.yaml instead.\nservices:\n  app:\n    image: ${image}\n    env_file: .env\n    volumes:\n      - ./app:/config:ro\n    ports:\n      - \"${hostPort}:3000\"\n    healthcheck:\n      test: [\"CMD\", \"python\", \"-c\", \"import urllib.request; urllib.request.urlopen('http://127.0.0.1:3000/health', timeout=2)\"]\n      interval: 30s\n      timeout: 3s\n      start_period: 10s\n      retries: 3\n`;
 }

package/src/template-files.mjs

@@ -1,7 +1,30 @@
 import fs from "node:fs";
 import path from "node:path";
+import os from "node:os";
+import unzipper from "unzipper";
 
 const excludedNames = new Set([".env", ".git", ".terraform", "node_modules", "docker-compose.yml", ".dome-compose.yaml"]);
+const maximumArchiveBytes = 50 * 1024 * 1024;
+const maximumExtractedBytes = 100 * 1024 * 1024;
+
+function archivePath(relative) {
+  const normalized = relative.replaceAll("\\", "/");
+  const withoutTrailingSlash = normalized.replace(/\/+$/, "");
+  if (!withoutTrailingSlash || normalized.startsWith("/") || normalized.includes("\0") || withoutTrailingSlash.split("/").some((part) => part === "." || part === "..")) {
+    throw new Error(`Template archive contains an unsafe path: ${relative}`);
+  }
+  return withoutTrailingSlash;
+}
+
+function relativeArchivePath(entryPath, slug) {
+  const normalized = archivePath(entryPath);
+  if (normalized === slug) return undefined;
+  const prefix = `${slug}/`;
+  if (!normalized.startsWith(prefix)) throw new Error(`Template archive must contain files under ${prefix}`);
+  const relative = normalized.slice(prefix.length);
+  if (!relative) throw new Error("Template archive contains an invalid empty path.");
+  return relative;
+}
 
 export function copyTemplate(source, destination) {
   fs.mkdirSync(destination, { recursive: true });
@@ -26,3 +49,52 @@ export function initializeEnvironment(templateDirectory) {
   }
   return false;
 }
+
+export async function downloadTemplate(slug, destination, { baseURL, fetchImplementation = globalThis.fetch } = {}) {
+  const archiveURL = new URL(`${slug}.zip`, `${(baseURL ?? "https://templates.domesystems.ai/templates/downloads").replace(/\/$/, "")}/`);
+  const response = await fetchImplementation(archiveURL, { headers: { accept: "application/zip" } });
+  if (!response.ok) throw new Error(`Could not download ${slug}: ${response.status} ${response.statusText}.`);
+
+  const archive = Buffer.from(await response.arrayBuffer());
+  if (archive.length === 0 || archive.length > maximumArchiveBytes) throw new Error(`Template archive must be between 1 byte and ${maximumArchiveBytes / 1024 / 1024} MiB.`);
+
+  let directory;
+  try {
+    directory = await unzipper.Open.buffer(archive);
+  } catch {
+    throw new Error(`Downloaded ${slug} is not a valid ZIP archive.`);
+  }
+
+  let extractedBytes = 0;
+  const entries = directory.files
+    .map((entry) => ({ entry, relative: relativeArchivePath(entry.path, slug) }))
+    .filter(({ relative }) => relative !== undefined);
+  for (const { entry, relative } of entries) {
+    if (entry.type !== "File" && entry.type !== "Directory") throw new Error(`Template archive contains an unsupported entry: ${relative}`);
+    if (entry.type === "File") {
+      extractedBytes += entry.uncompressedSize;
+      if (extractedBytes > maximumExtractedBytes) throw new Error(`Template archive expands beyond ${maximumExtractedBytes / 1024 / 1024} MiB.`);
+    }
+  }
+
+  const staging = fs.mkdtempSync(path.join(os.tmpdir(), "dome-template-"));
+  try {
+    const source = path.join(staging, slug);
+    for (const { entry, relative } of entries) {
+      const target = path.join(source, relative);
+      if (entry.type === "Directory") {
+        fs.mkdirSync(target, { recursive: true });
+      } else {
+        fs.mkdirSync(path.dirname(target), { recursive: true });
+        fs.writeFileSync(target, await entry.buffer());
+      }
+    }
+    if (!fs.statSync(path.join(source, "template.yaml"), { throwIfNoEntry: false })?.isFile()) {
+      throw new Error(`Downloaded ${slug} does not contain template.yaml.`);
+    }
+    copyTemplate(source, destination);
+  } finally {
+    fs.rmSync(staging, { recursive: true, force: true });
+  }
+  return archiveURL.toString();
+}