@domesystems/templates 0.2.0 → 0.3.1

package/README.md

@@ -1,59 +1,37 @@
 # Dome Templates CLI
 
-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`.
-
-## Install and run
-
-Use `npx`; Node.js 20 or newer is required.
+Pull immutable Dome template releases, publish public templates from GitHub, and run an existing local directory.
 
 ```bash
-# Download a template into ./ai-agent-for-documentation.
-npx @domesystems/templates init ai-agent-for-documentation
-
-# Download if needed, provision Dome, and run it locally.
-npx @domesystems/templates up ai-agent-for-documentation
+npx @domesystems/templates login --registry https://templates-registry.domesystems.ai --github
+npx @domesystems/templates pull dome-systems/ai-agent-for-documentation --registry https://templates-registry.domesystems.ai --dir ai-agent-for-documentation
+npx @domesystems/templates up --dir ai-agent-for-documentation
 ```
 
-By default, archives come from
-`https://templates.domesystems.ai/templates/downloads/<template>.zip`.
+Every remote command takes either `--server <Dome application URL>` or `--registry <Registry URL>`. `--server` discovers the Registry endpoint through the app server; `--registry` connects directly to an explicitly supplied Registry. Credentials are isolated per selected endpoint.
 
-For local Library development, point the CLI at a local download server:
+Use direct Registry endpoints when the app-server discovery document is unavailable:
 
 ```bash
-DOME_TEMPLATES_BASE_URL=http://localhost:3001/templates/downloads \
-  npx @domesystems/templates init ai-agent-for-documentation
+# Production
+npx @domesystems/templates login --registry https://templates-registry.domesystems.ai
+npx @domesystems/templates pull dome-systems/ai-agent-for-documentation --registry https://templates-registry.domesystems.ai
+
+# Development
+npx @domesystems/templates login --registry https://templates-registry-dev.domesystems.ai
 ```
 
 ## Commands
 
 ```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]
+templates login [--server <URL>|--registry <URL>] [--github]
+templates logout [--server <URL>|--registry <URL>]
+templates doctor <pull|up|publish> [--dir <directory>] [--server <URL>|--registry <URL>] [--json]
+templates pull <scope/package[@version]> [--dir <directory>] [--server <URL>|--registry <URL>]
+templates up [--dir <directory>] [--port <host-port>] [--skip-provision|--provision] [--no-start] [--detach]
+templates publish [--dry-run] [--server <URL>|--registry <URL>]
 ```
 
-| 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.
+`pull` only accepts scoped package names, verifies the Registry SHA-256 before extraction, accepts only the archive's `template/` root, writes `.dome-template-lock.yaml`, and never overwrites a non-empty directory. `up` is local-only and never downloads or updates a release. `publish` reads the scoped name and SemVer version from `template.yaml`, requires a clean Git checkout, and cannot replace a published version.
+
+The CLI holds no authority over package ownership or artifact access. The Registry revalidates every publish and creates short-lived artifact URLs; it does not expose raw S3 keys.

package/package.json

@@ -1,7 +1,11 @@
 {
   "name": "@domesystems/templates",
-  "version": "0.2.0",
-  "description": "Download, initialize, and run Dome governed-agent templates.",
+  "version": "0.3.1",
+  "description": "Pull, publish, and run versioned Dome templates.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dome-systems/templates-cli.git"
+  },
   "type": "module",
   "bin": {
     "dome-templates": "bin/dome-templates.mjs"
@@ -22,7 +26,6 @@
     "test": "node --test"
   },
   "dependencies": {
-    "unzipper": "0.12.3",
     "unzipper": "0.12.3",
     "yaml": "2.9.0"
   }

package/src/cli.mjs

@@ -2,310 +2,52 @@ import fs from "node:fs";
 import path from "node:path";
 import { spawn, spawnSync } from "node:child_process";
 import readline from "node:readline/promises";
-import { readManifest } from "./manifest.mjs";
+import { readManifest, readPublishManifest } from "./manifest.mjs";
 import { imageForRuntime, renderCompose } from "./runtime.mjs";
-import { downloadTemplate, initializeEnvironment } from "./template-files.mjs";
-
-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>] [--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) {
-  throw new Error(`${message}\n\n${usage()}`);
-}
-
-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, 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.");
-      index += 1;
-    } else {
-      fail(`Unknown option: ${argument}`);
-    }
-  }
-  if (!["init", "up"].includes(command)) fail(`Unknown command: ${command}`);
-  if (!slug) fail("A template slug is required.");
-  return { command, slug, options };
-}
-
-function validateTemplateSlug(slug) {
-  if (slug.includes("/") || slug.includes("\\") || slug === "." || slug === "..") {
-    fail(`Invalid template slug: ${slug}`);
-  }
-}
-
-function targetDirectory(slug, directory) {
-  return path.resolve(process.cwd(), directory ?? slug);
-}
-
-function isEmpty(directory) {
-  return !fs.existsSync(directory) || fs.readdirSync(directory).length === 0;
-}
-
-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.`);
-  }
-  output(status("info", `Downloading ${slug}…`));
-  const archiveURL = await downloadTemplate(slug, target, {
-    baseURL: process.env.DOME_TEMPLATES_BASE_URL,
-    fetchImplementation,
-  });
-  const environmentCreated = initializeEnvironment(target);
-  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;
-}
-
-async function resolveUpDirectory(slug, options, output, fetchImplementation) {
-  const target = targetDirectory(slug, options.directory);
-  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) {
-  const result = spawnSync(command, args, { cwd, stdio: "inherit" });
-  if (result.error) throw new Error(`Could not run ${command}: ${result.error.message}`);
-  if (result.status !== 0) throw new Error(`${command} ${args.join(" ")} exited with status ${result.status}.`);
-}
-
-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) {
-      output(usage());
-      return;
-    }
-    const { command, slug, options } = parsed;
-    if (command === "init") {
-      await init(slug, options, output, fetchImplementation);
-      return;
-    }
-
-    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, options.port));
-    if (options.verbose) {
-      output(status("info", `Generated ${path.basename(composePath)} with ${imageForRuntime(manifest.app.runtime)} for http://localhost:${options.port}.`));
-    }
-
-    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);
-    }
-    if (!options.provision || !options.start) {
-      output("Skipped requested steps. Re-run without --skip-provision or --no-start when ready.");
-    }
-  } catch (caught) {
-    error(`Error: ${caught.message}`);
-    process.exitCode = 1;
-  }
-}
+import { extractRelease, initializeEnvironment } from "./template-files.mjs";
+import { createArchive, publishSource } from "./publish-files.mjs";
+import { DEFAULT_SERVER, deleteProfile, directRegistry, discover, login, normalizeServer, readProfile, registryRequest } from "./registry.mjs";
+
+function ansi(code, value, options) { return options.color && process.stdout.isTTY ? `\u001B[${code}m${value}\u001B[0m` : value; }
+function line(kind, value, options) { const styles = { info: ["•", "36"], success: ["✓", "32"], warning: ["!", "33"], error: ["✗", "31"] }; const [mark, code] = styles[kind]; return `${ansi(code, mark, options)} ${value}`; }
+function usage() { return "Usage:\n  templates login [--server <Dome application URL>|--registry <Registry URL>] [--github]\n  templates logout [--server <Dome application URL>|--registry <Registry URL>]\n  templates doctor <pull|up|publish> [package] [--dir <directory>] [--server <URL>|--registry <URL>] [--json]\n  templates pull <scope/package[@version]> [--dir <directory>] [--server <URL>|--registry <URL>]\n  templates up [--dir <directory>] [--port <host-port>] [--skip-provision|--provision] [--no-start] [--detach] [--verbose]\n  templates publish [--dry-run] [--server <Dome application URL>|--registry <Registry URL>]\n"; }
+function parse(argv) {
+  if (!argv.length || argv.includes("--help") || argv.includes("-h")) return { help: true };
+  const [command, ...rest] = argv;
+  const options = { server: undefined, directory: undefined, port: 3000, dryRun: false, json: false, github: false, provision: true, forceProvision: false, start: true, detach: false, verbose: false, color: !process.env.NO_COLOR };
+  const values = [];
+  for (let i = 0; i < rest.length; i += 1) {
+    const arg = rest[i];
+    if (arg === "--server" || arg === "--registry" || arg === "--dir" || arg === "--port" || arg === "--color") { const value = rest[++i]; if (!value) throw new Error(`${arg} requires a value.`); if (arg === "--server") options.server = normalizeServer(value); else if (arg === "--registry") options.registry = normalizeServer(value); else if (arg === "--dir") options.directory = value; else if (arg === "--color") { if (!["auto", "always", "never"].includes(value)) throw new Error("--color must be auto, always, or never."); options.color = value === "always" || (value === "auto" && !process.env.NO_COLOR); } else { options.port = Number(value); if (!Number.isInteger(options.port) || options.port < 1 || options.port > 65535) throw new Error("--port requires an integer from 1 to 65535."); } }
+    else if (arg === "--github") options.github = true; else if (arg === "--dry-run") options.dryRun = true; else if (arg === "--json") options.json = true; else if (arg === "--skip-provision") options.provision = false; else if (arg === "--provision") options.forceProvision = true; else if (arg === "--no-start") options.start = false; else if (arg === "--detach") options.detach = true; else if (arg === "--verbose") options.verbose = true; else if (arg.startsWith("-")) throw new Error(`Unknown option: ${arg}`); else values.push(arg);
+  }
+  if (options.server && options.registry) throw new Error("Use either --server or --registry, not both.");
+  if (!["login", "logout", "doctor", "pull", "up", "publish"].includes(command)) throw new Error(`Unknown command: ${command}`);
+  return { command, values, options };
+}
+function remoteTarget(options) { return options.registry ? directRegistry(options.registry) : options.server ?? DEFAULT_SERVER; }
+function packageReference(value) { const match = /^([a-z0-9][a-z0-9-]*\/[a-z0-9][a-z0-9-]*)(?:@(.+))?$/.exec(value ?? ""); if (!match) throw new Error("Template package must be fully qualified as scope/package or scope/package@version."); return { name: match[1], version: match[2] }; }
+function destination(name, directory) { return path.resolve(process.cwd(), directory ?? name.split("/")[1]); }
+function empty(dir) { return !fs.existsSync(dir) || fs.readdirSync(dir).length === 0; }
+async function pull(name, options, output, fetchImplementation) {
+  const ref = packageReference(name); const target = destination(ref.name, options.directory); if (!empty(target)) throw new Error(`${target} already exists and is not empty. Choose an empty --dir.`);
+  output(line("info", `Fetching ${ref.name}@${ref.version ?? "latest"}`, options));
+  const [scope, slug] = ref.name.split("/"); const remote = remoteTarget(options); const { body: release } = await registryRequest(remote, `/v1/packages/${scope}/${slug}${ref.version ? `/${encodeURIComponent(ref.version)}` : ""}`, { fetchImplementation });
+  if (!release.name || !release.version || !release.sha256 || !release.source) throw new Error("Registry returned incomplete release metadata.");
+  const { body: download } = await registryRequest(remote, `/v1/packages/${scope}/${slug}/${encodeURIComponent(release.version)}/download-url`, { method: "POST", fetchImplementation });
+  const response = await fetchImplementation(download.url, { headers: { accept: "application/zip" } }); if (!response.ok) throw new Error(`Could not download ${ref.name}: ${response.status} ${response.statusText}.`);
+  fs.mkdirSync(target, { recursive: true }); await extractRelease(Buffer.from(await response.arrayBuffer()), target, release); const created = initializeEnvironment(target);
+  output(line("success", `Pulled ${release.name}@${release.version}`, options)); output(`  Saved to ${target}`); if (created) output(line("success", "Created .env from .env.example", options));
+}
+function run(command, args, cwd) { const result = spawnSync(command, args, { cwd, stdio: "inherit" }); if (result.error || result.status !== 0) throw new Error(`${command} ${args.join(" ")} failed.`); }
+function configured(target) { const env = path.join(target, ".env"); return fs.existsSync(env) && ["DOME_TOKEN", "DOME_GATEWAY_URL"].every((key) => new RegExp(`^${key}=(?!\\s*$|undefined|\"\")`, "m").test(fs.readFileSync(env, "utf8"))); }
+async function up(options, output) { const target = path.resolve(process.cwd(), options.directory ?? "."); const manifest = readManifest(target); output(line("info", `Checking ${target}`, options)); fs.writeFileSync(path.join(target, ".dome-compose.yaml"), renderCompose(manifest.app.runtime, options.port)); if (options.provision && (!configured(target) || options.forceProvision)) { output(line("info", "Setting up Dome resources", options)); run("dome", ["import", "dome.tf"], target); } if (options.start) { output(line("info", `Starting app at http://localhost:${options.port}`, options)); run("docker", ["compose", "-f", ".dome-compose.yaml", "up", ...(options.detach ? ["--detach"] : [])], target); } }
+async function publish(options, output, fetchImplementation) { const target = path.resolve(process.cwd(), options.directory ?? "."); const manifest = readPublishManifest(target); const source = publishSource(target); const name = manifest.metadata.name; const [scope, slug] = name.split("/"); const archive = options.dryRun ? null : createArchive(source); output(line("info", `Checking ${name}@${manifest.metadata.version}`, options)); const payload = { name, version: manifest.metadata.version, title: manifest.metadata.title, summary: manifest.metadata.summary ?? "", sha256: archive?.sha256, size_bytes: archive?.buffer.length, source: { repository: manifest.metadata.source.repository, path: manifest.metadata.source.path, commit: source.commit, remote: source.remote, files: source.files } };
+  const { target: registry, body: attempt } = await registryRequest(remoteTarget(options), "/v1/publish-attempts", { method: "POST", body: { ...payload, dry_run: options.dryRun }, authenticated: true, fetchImplementation });
+  if (options.dryRun) { output(line("success", `Publish plan is valid for ${name}@${manifest.metadata.version}`, options)); return; }
+  try { output(line("info", "Uploading release artifact", options)); const upload = await fetchImplementation(attempt.upload_url, { method: "PUT", headers: { "content-type": "application/zip" }, body: archive.buffer }); if (!upload.ok) throw new Error(`Artifact upload failed: ${upload.status} ${upload.statusText}.`); const { body: published } = await registryRequest(registry, `/v1/publish-attempts/${encodeURIComponent(attempt.id)}/complete`, { method: "POST", body: { sha256: archive.sha256, size_bytes: archive.buffer.length }, authenticated: true, fetchImplementation }); output(line("success", `Published ${published.name ?? name}@${published.version ?? manifest.metadata.version}`, options)); if (published.url) output(`  ${published.url}`); } finally { archive.cleanup(); }
+}
+async function doctor(subject, options, output, fetchImplementation) { const checks = []; const add = (name, passed, remediation) => checks.push({ name, passed, remediation }); try { if (subject === "pull") { const remote = remoteTarget(options); if (typeof remote === "string") await discover(remote, fetchImplementation); add("Registry reachability", true); } else if (subject === "up") { const target = path.resolve(process.cwd(), options.directory ?? "."); readManifest(target); add("template.yaml", true); add("Docker Compose", spawnSync("docker", ["compose", "version"], { stdio: "ignore" }).status === 0, "Install Docker Desktop or Docker Engine with the Compose plugin."); add("Dome CLI", spawnSync("dome", ["--version"], { stdio: "ignore" }).status === 0, "Install the Dome CLI."); } else if (subject === "publish") { readPublishManifest(path.resolve(process.cwd(), options.directory ?? ".")); publishSource(path.resolve(process.cwd(), options.directory ?? ".")); const profile = readProfile(remoteTarget(options).server ?? remoteTarget(options)); const location = options.registry ? `--registry ${options.registry}` : `--server ${options.server ?? DEFAULT_SERVER}`; add("Registry sign-in", Boolean(profile?.token), `Run npx @domesystems/templates login ${location}`); } else throw new Error("doctor expects pull, up, or publish."); } catch (error) { add("Preflight", false, error.message); }
+  if (options.json) output(JSON.stringify({ server: options.registry ?? options.server ?? DEFAULT_SERVER, checks })); else checks.forEach((check) => output(line(check.passed ? "success" : "error", check.passed ? check.name : `${check.name}: ${check.remediation}`, options))); if (checks.some((check) => !check.passed)) throw new Error(`Cannot continue until ${subject} checks pass.`);
+}
+export async function main(argv, { output = console.log, error = console.error, fetchImplementation = globalThis.fetch, sleep } = {}) { try { const parsed = parse(argv); if (parsed.help) return output(usage()); const { command, values, options } = parsed; const remote = remoteTarget(options); if (options.json) options.color = false; if (command === "login") { const destination = options.registry ?? options.server ?? DEFAULT_SERVER; output(line("info", `Opening sign-in for ${destination}`, options)); const session = await login(remote, { github: options.github, fetchImplementation, sleep, onStart: (started) => output(`Open ${started.verification_uri} and enter ${started.user_code ?? "the displayed code"}.`) }); output(line("success", `Signed in as ${session.session.email}`, options)); return; } if (command === "logout") { const server = remote.server ?? remote; const profile = readProfile(server); if (profile?.token) await registryRequest(remote, "/v1/auth/logout", { method: "POST", authenticated: true, fetchImplementation }); deleteProfile(server); output(line("success", `Signed out of ${server}`, options)); return; } if (command === "pull") return pull(values[0], options, output, fetchImplementation); if (command === "up") return up(options, output); if (command === "publish") return publish(options, output, fetchImplementation); return doctor(values[0], options, output, fetchImplementation); } catch (caught) { error(line("error", caught.message, { color: false })); process.exitCode = 1; } }

package/src/manifest.mjs

@@ -20,3 +20,36 @@ export function readManifest(templateDirectory) {
   }
   return manifest;
 }
+
+const PACKAGE_NAME = /^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?\/[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$/;
+const VERSION = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+
+export function readPublishManifest(templateDirectory) {
+  const manifest = readManifest(templateDirectory);
+  if (manifest.apiVersion !== "templates.domesystems.ai/v1" || manifest.kind !== "Template") {
+    throw new Error("template.yaml must declare apiVersion templates.domesystems.ai/v1 and kind Template.");
+  }
+  const metadata = manifest.metadata ?? {};
+  if (!PACKAGE_NAME.test(metadata.name ?? "")) {
+    throw new Error("template.yaml metadata.name must be a lowercase scoped name such as im2nguyen/tinyfish.");
+  }
+  if (!VERSION.test(metadata.version ?? "")) {
+    throw new Error("template.yaml metadata.version must be a valid SemVer version.");
+  }
+  if (typeof metadata.title !== "string" || !metadata.title.trim()) {
+    throw new Error("template.yaml metadata.title is required to publish a template.");
+  }
+  const source = metadata.source;
+  if (!source || typeof source.repository !== "string" || typeof source.path !== "string" || !source.path.trim()) {
+    throw new Error("template.yaml metadata.source.repository and metadata.source.path are required to publish a template.");
+  }
+  let repository;
+  try { repository = new URL(source.repository); } catch { throw new Error("metadata.source.repository must be a GitHub HTTPS URL."); }
+  if (repository.protocol !== "https:" || repository.hostname !== "github.com" || !/^\/[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+\/?$/.test(repository.pathname)) {
+    throw new Error("metadata.source.repository must be a public https://github.com/<owner>/<repository> URL.");
+  }
+  if (source.path.split(/[\\/]+/).some((part) => !part || part === "." || part === "..")) {
+    throw new Error("metadata.source.path must be a relative repository path without traversal.");
+  }
+  return manifest;
+}

package/src/publish-files.mjs

@@ -0,0 +1,68 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+
+const EXCLUDED = new Set([".git", ".env", ".terraform", "node_modules", ".dome-compose.yaml", "docker-compose.yml"]);
+const MAX_BYTES = 100 * 1024 * 1024;
+
+function walk(root, relative = "") {
+  const directory = path.join(root, relative);
+  return fs.readdirSync(directory, { withFileTypes: true }).flatMap((entry) => {
+    if (EXCLUDED.has(entry.name)) return [];
+    const next = path.posix.join(relative, entry.name);
+    if (entry.isDirectory()) return walk(root, next);
+    if (!entry.isFile() || entry.isSymbolicLink()) throw new Error(`Cannot publish unsupported source entry: ${next}`);
+    return [next];
+  });
+}
+
+export function git(command, args, cwd) {
+  const result = spawnSync(command, args, { cwd, encoding: "utf8" });
+  if (result.error || result.status !== 0) {
+    const reason = result.error?.message ?? result.stderr.trim() ?? "command failed";
+    throw new Error(`Git is required to publish this template (${reason}).`);
+  }
+  return result.stdout.trim();
+}
+
+export function publishSource(directory) {
+  const root = path.resolve(directory);
+  const commit = git("git", ["rev-parse", "HEAD"], root);
+  if (git("git", ["status", "--porcelain", "--", "."], root)) throw new Error("The template directory has uncommitted changes. Commit or stash them before publishing.");
+  const remote = git("git", ["config", "--get", "remote.origin.url"], root).replace(/\.git$/, "");
+  const files = walk(root).sort();
+  let size = 0;
+  const entries = files.map((file) => {
+    const contents = fs.readFileSync(path.join(root, file));
+    size += contents.length;
+    if (size > MAX_BYTES) throw new Error("Template source exceeds the 100 MiB publishing limit.");
+    return { path: file, sha256: crypto.createHash("sha256").update(contents).digest("hex"), size: contents.length };
+  });
+  return { root, commit, remote, files: entries, size };
+}
+
+export function createArchive(source) {
+  const staging = fs.mkdtempSync(path.join(os.tmpdir(), "dome-template-publish-"));
+  const archive = path.join(staging, "release.zip");
+  const contents = path.join(staging, "template");
+  try {
+    fs.mkdirSync(contents);
+    for (const entry of source.files) {
+      const destination = path.join(contents, entry.path);
+      fs.mkdirSync(path.dirname(destination), { recursive: true });
+      fs.copyFileSync(path.join(source.root, entry.path), destination);
+    }
+    const result = spawnSync("zip", ["-q", "-r", archive, "template"], { cwd: staging, encoding: "utf8" });
+    if (result.error || result.status !== 0) {
+      const reason = result.error?.message ?? result.stderr.trim() ?? "zip failed";
+      throw new Error(`Could not package template release (${reason}).`);
+    }
+    const buffer = fs.readFileSync(archive);
+    return { buffer, sha256: crypto.createHash("sha256").update(buffer).digest("hex"), cleanup: () => fs.rmSync(staging, { recursive: true, force: true }) };
+  } catch (error) {
+    fs.rmSync(staging, { recursive: true, force: true });
+    throw error;
+  }
+}

package/src/registry.mjs

@@ -0,0 +1,109 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+export const DEFAULT_SERVER = "https://app.domesystems.ai";
+
+function profileKey(server) {
+  return crypto.createHash("sha256").update(new URL(server).origin).digest("hex").slice(0, 24);
+}
+
+function credentialPath(server) {
+  const root = process.env.DOME_TEMPLATES_CONFIG_HOME
+    ?? path.join(process.env.XDG_CONFIG_HOME ?? path.join(os.homedir(), ".config"), "dome", "templates");
+  return path.join(root, `${profileKey(server)}.json`);
+}
+
+export function normalizeServer(server = DEFAULT_SERVER) {
+  const url = new URL(server);
+  if (url.protocol !== "https:" && url.hostname !== "localhost" && url.hostname !== "127.0.0.1") {
+    throw new Error("--server must use HTTPS (or localhost for development).");
+  }
+  url.pathname = "/";
+  url.search = "";
+  url.hash = "";
+  return url.toString().replace(/\/$/, "");
+}
+
+export function directRegistry(server) {
+  const registry = normalizeServer(server);
+  return { server: registry, registry };
+}
+
+export function readProfile(server) {
+  try {
+    const profile = JSON.parse(fs.readFileSync(credentialPath(server), "utf8"));
+    return profile.server === normalizeServer(server) ? profile : null;
+  } catch { return null; }
+}
+
+export function writeProfile(server, profile) {
+  const file = credentialPath(server);
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  fs.writeFileSync(file, `${JSON.stringify({ ...profile, server: normalizeServer(server) }, null, 2)}\n`, { mode: 0o600 });
+}
+
+export function deleteProfile(server) {
+  fs.rmSync(credentialPath(server), { force: true });
+}
+
+async function responseJSON(response, action) {
+  const type = response.headers?.get?.("content-type") ?? "";
+  const body = type.includes("json") ? await response.json().catch(() => null) : null;
+  if (!response.ok) throw new Error(body?.message ?? `${action} failed: ${response.status} ${response.statusText}.`);
+  return body ?? {};
+}
+
+export async function discover(server, fetchImplementation = globalThis.fetch) {
+  const selected = normalizeServer(server);
+  const response = await fetchImplementation(`${selected}/.well-known/dome-template-registry`, { headers: { accept: "application/json" } });
+  const document = await responseJSON(response, "Registry discovery");
+  if (typeof document.registry !== "string") throw new Error("The selected Dome server did not return a Registry endpoint.");
+  const endpoint = new URL(document.registry);
+  if (endpoint.protocol !== "https:" && endpoint.hostname !== "localhost" && endpoint.hostname !== "127.0.0.1") throw new Error("The selected Dome server returned an unsafe Registry endpoint.");
+  return { server: selected, registry: endpoint.toString().replace(/\/$/, "") };
+}
+
+async function targetFor(server, fetchImplementation) {
+  return typeof server === "string" ? discover(server, fetchImplementation) : server;
+}
+
+export async function registryRequest(server, pathname, { method = "GET", body, authenticated = false, fetchImplementation = globalThis.fetch } = {}) {
+  const target = await targetFor(server, fetchImplementation);
+  const headers = { accept: "application/json" };
+  if (body !== undefined) headers["content-type"] = "application/json";
+  if (authenticated) {
+    const profile = readProfile(target.server);
+    if (!profile?.token) throw new Error(`Sign in to ${target.server} first: npx @domesystems/templates login --server ${target.server}`);
+    headers.authorization = `Bearer ${profile.token}`;
+  }
+  const response = await fetchImplementation(`${target.registry}${pathname}`, {
+    method, headers, body: body === undefined ? undefined : JSON.stringify(body),
+  });
+  return { target, body: await responseJSON(response, "Registry request") };
+}
+
+export async function login(server, { github = false, fetchImplementation = globalThis.fetch, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)), onStart } = {}) {
+  const target = await targetFor(server, fetchImplementation);
+  const response = await fetchImplementation(`${target.registry}/v1/auth/device/start`, {
+    method: "POST", headers: { accept: "application/json", "content-type": "application/json" }, body: JSON.stringify({ github }),
+  });
+  const started = await responseJSON(response, "Starting sign-in");
+  if (!started.device_code || !started.verification_uri) throw new Error("Registry sign-in returned an incomplete device authorization.");
+  onStart?.(started);
+  const deadline = Date.now() + Math.min(Number(started.expires_in ?? 900), 900) * 1000;
+  const interval = Math.max(Number(started.interval ?? 3), 2) * 1000;
+  while (Date.now() < deadline) {
+    await sleep(interval);
+    const complete = await fetchImplementation(`${target.registry}/v1/auth/device/complete`, {
+      method: "POST", headers: { accept: "application/json", "content-type": "application/json" }, body: JSON.stringify({ device_code: started.device_code }),
+    });
+    if (complete.status === 202 || complete.status === 428) continue;
+    const session = await responseJSON(complete, "Completing sign-in");
+    if (!session.token || !session.email) throw new Error("Registry sign-in completed without a token or email.");
+    writeProfile(target.server, { token: session.token, email: session.email, github: session.github ?? null, publisherScope: session.publisher_scope ?? null });
+    return { target, started, session };
+  }
+  throw new Error("Sign-in expired before it was completed. Run login again.");
+}

package/src/template-files.mjs

@@ -1,7 +1,9 @@
+import crypto from "node:crypto";
 import fs from "node:fs";
-import path from "node:path";
 import os from "node:os";
+import path from "node:path";
 import unzipper from "unzipper";
+import { stringify } from "yaml";
 
 const excludedNames = new Set([".env", ".git", ".terraform", "node_modules", "docker-compose.yml", ".dome-compose.yaml"]);
 const maximumArchiveBytes = 50 * 1024 * 1024;
@@ -9,21 +11,16 @@ 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;
+  const clean = normalized.replace(/\/+$/, "");
+  if (!clean || normalized.startsWith("/") || normalized.includes("\0") || clean.split("/").some((part) => part === "." || part === "..")) throw new Error(`Template archive contains an unsafe path: ${relative}`);
+  return clean;
 }
 
-function relativeArchivePath(entryPath, slug) {
+function relativeArchivePath(entryPath) {
   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;
+  if (normalized === "template") return undefined;
+  if (!normalized.startsWith("template/")) throw new Error("Template archive must contain one fixed template/ root.");
+  return normalized.slice("template/".length);
 }
 
 export function copyTemplate(source, destination) {
@@ -32,11 +29,8 @@ export function copyTemplate(source, destination) {
     if (excludedNames.has(entry.name)) continue;
     const from = path.join(source, entry.name);
     const to = path.join(destination, entry.name);
-    if (entry.isDirectory()) {
-      copyTemplate(from, to);
-    } else if (entry.isFile()) {
-      fs.copyFileSync(from, to);
-    }
+    if (entry.isDirectory()) copyTemplate(from, to);
+    else if (entry.isFile()) fs.copyFileSync(from, to);
   }
 }
 
@@ -50,51 +44,34 @@ 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.`);
+export function writeLock(destination, release) {
+  fs.writeFileSync(path.join(destination, ".dome-template-lock.yaml"), stringify({
+    apiVersion: "templates.domesystems.ai/v1", package: release.name, version: release.version, sha256: release.sha256,
+    source: { repository: release.source.repository, commit: release.source.commit, path: release.source.path },
+  }));
+}
 
+export async function extractRelease(archive, destination, release) {
+  if (!Buffer.isBuffer(archive) || archive.length === 0 || archive.length > maximumArchiveBytes) throw new Error(`Template artifact must be between 1 byte and ${maximumArchiveBytes / 1024 / 1024} MiB.`);
+  if (crypto.createHash("sha256").update(archive).digest("hex") !== release.sha256) throw new Error(`Template artifact integrity check failed for ${release.name}@${release.version}.`);
   let directory;
-  try {
-    directory = await unzipper.Open.buffer(archive);
-  } catch {
-    throw new Error(`Downloaded ${slug} is not a valid ZIP archive.`);
-  }
-
+  try { directory = await unzipper.Open.buffer(archive); } catch { throw new Error(`Release artifact for ${release.name} 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);
+  const entries = directory.files.map((entry) => ({ entry, relative: relativeArchivePath(entry.path) })).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.`);
-    }
+    if (entry.type === "File" && (extractedBytes += entry.uncompressedSize) > 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);
+    const source = path.join(staging, "template");
     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.`);
+      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(`Release artifact for ${release.name} does not contain template.yaml.`);
     copyTemplate(source, destination);
-  } finally {
-    fs.rmSync(staging, { recursive: true, force: true });
-  }
-  return archiveURL.toString();
+    writeLock(destination, release);
+  } finally { fs.rmSync(staging, { recursive: true, force: true }); }
 }