@nmakarov/cli-toolkit 0.27.0 → 0.32.0

package/dist/index.js

@@ -542,7 +542,7 @@ async function showScreen(config2) {
     onRender,
     parentData = {}
   } = config2;
-  return new Promise((resolve2) => {
+  return new Promise((resolve3) => {
     let instance2;
     const keyBindings = [];
     const actions = {};
@@ -717,7 +717,7 @@ async function showScreen(config2) {
     };
     const cleanup = (result) => {
       if (instance2) instance2.unmount();
-      setTimeout(() => resolve2(result), 50);
+      setTimeout(() => resolve3(result), 50);
     };
     instance2 = render(h3(Screen));
   });
@@ -1692,7 +1692,8 @@ var Params = class _Params {
   /**
    * Resolved early in constructor so cleanup does not read params lazily.
    * One of: false (off) | "end" (print at exit) | "top" (print after init,
-   * via context.showUsedParamsIfNeeded()).
+   * via context.showUsedParamsIfNeeded()) | "stop" (print after init, then
+   * exit the process — also via context.showUsedParamsIfNeeded()).
    */
   _showUsedParamsMode = false;
   /** Guard so the dump prints at most once (top OR end, never both). */
@@ -1716,8 +1717,9 @@ var Params = class _Params {
    *   (absent) / --no-showUsedParams / =false   -> false  (off)
    *   --showUsedParams / =true                   -> "end"  (print at exit)
    *   --showUsedParams=top                       -> "top"  (print after init)
-   * Read raw (uncoerced) from args so the string "top" isn't forced to a
-   * boolean, then track it under the "script" module for the dump itself.
+   *   --showUsedParams=stop                      -> "stop" (print after init, then exit)
+   * Read raw (uncoerced) from args so the string "top"/"stop" isn't forced to
+   * a boolean, then track it under the "script" module for the dump itself.
    */
   _resolveShowUsedParams() {
     const raw = this.args.get("showUsedParams");
@@ -1727,6 +1729,8 @@ var Params = class _Params {
       mode = false;
     } else if (typeof raw === "string" && raw.trim().toLowerCase() === "top") {
       mode = "top";
+    } else if (typeof raw === "string" && raw.trim().toLowerCase() === "stop") {
+      mode = "stop";
     } else {
       const s = typeof raw === "string" ? raw.trim().toLowerCase() : raw;
       const falsey = s === false || s === "false" || s === "0" || s === "no" || s === "off";
@@ -1740,7 +1744,7 @@ var Params = class _Params {
   getShowUsedParams() {
     return this._showUsedParamsMode !== false;
   }
-  /** Resolved mode: false | "end" | "top". */
+  /** Resolved mode: false | "end" | "top" | "stop". */
   getShowUsedParamsMode() {
     return this._showUsedParamsMode;
   }
@@ -2434,8 +2438,8 @@ var FileDatabase = class _FileDatabase {
       const items = await fs3.promises.readdir(destPath);
       const versions = items.filter((item) => {
         const itemPath = path3.join(destPath, item);
-        const stat = fs3.statSync(itemPath);
-        return stat.isDirectory() && isTimestampFolder(item);
+        const stat2 = fs3.statSync(itemPath);
+        return stat2.isDirectory() && isTimestampFolder(item);
       });
       return versions.sort();
     } catch (error) {
@@ -2500,8 +2504,8 @@ var FileDatabase = class _FileDatabase {
     }
     const versionFolders = items.filter((item) => {
       const itemPath = path3.join(tablePath, item);
-      const stat = fs3.statSync(itemPath);
-      return stat.isDirectory() && isTimestampFolder(item);
+      const stat2 = fs3.statSync(itemPath);
+      return stat2.isDirectory() && isTimestampFolder(item);
     });
     if (versionFolders.length > 0) {
       const latestVersion = versionFolders.sort().pop();
@@ -3786,6 +3790,7 @@ var S3 = class _S3 {
         secretAccessKey: config2.secretAccessKey
       };
     }
+    process.env.AWS_SDK_JS_NODE_VERSION_SUPPORT_WARNING_DISABLED ??= "true";
     this.client = new S3Client(clientConfig);
   }
   // ── info ────────────────────────────────────────────────────────────────
@@ -3967,6 +3972,204 @@ var S3 = class _S3 {
   }
 };
 
+// src/aws/index.js
+import {
+  STSClient,
+  GetCallerIdentityCommand
+} from "@aws-sdk/client-sts";
+import {
+  EC2Client,
+  DescribeRegionsCommand,
+  DescribeAvailabilityZonesCommand,
+  DescribeVpcsCommand,
+  DescribeSubnetsCommand,
+  DescribeSecurityGroupsCommand,
+  DescribeKeyPairsCommand,
+  DescribeImagesCommand
+} from "@aws-sdk/client-ec2";
+import {
+  Route53Client,
+  ListHostedZonesCommand
+} from "@aws-sdk/client-route-53";
+var DEFAULT_REGION = "us-east-1";
+var CANONICAL_OWNER_ID = "099720109477";
+var DEFAULT_UBUNTU_PATTERN = "ubuntu/images/hvm-ssd-gp3/ubuntu-noble-24.04-amd64-server-*";
+function nameTag(tags) {
+  const t = (tags ?? []).find((x) => x.Key === "Name");
+  return t?.Value ?? null;
+}
+var Aws = class _Aws {
+  /**
+   * Resolve credentials/region from params and return an Aws instance.
+   * Does not call AWS until you invoke a method (clients are lazy).
+   */
+  static async init(context, options = {}) {
+    const getOpt = async (k) => {
+      try {
+        const v = await context?.params?.get?.(k, "string");
+        return v != null && String(v).trim() !== "" ? v : void 0;
+      } catch {
+        return void 0;
+      }
+    };
+    const config2 = {
+      region: options.region ?? await getOpt("awsRegion") ?? DEFAULT_REGION,
+      accessKeyId: options.accessKeyId ?? await getOpt("awsAccessKeyId"),
+      secretAccessKey: options.secretAccessKey ?? await getOpt("awsSecretAccessKey"),
+      sessionToken: options.sessionToken ?? await getOpt("awsSessionToken")
+    };
+    const aws = new _Aws(context, config2);
+    context?.logger?.debug?.(
+      `[aws] region=${config2.region} credentials=${config2.accessKeyId ? "explicit" : "default-chain"}`
+    );
+    return aws;
+  }
+  constructor(context, config2) {
+    this.logger = context?.logger ?? console;
+    this.region = config2.region || DEFAULT_REGION;
+    this._credentials = config2.accessKeyId && config2.secretAccessKey ? {
+      accessKeyId: config2.accessKeyId,
+      secretAccessKey: config2.secretAccessKey,
+      ...config2.sessionToken ? { sessionToken: config2.sessionToken } : {}
+    } : void 0;
+    process.env.AWS_SDK_JS_NODE_VERSION_SUPPORT_WARNING_DISABLED ??= "true";
+    this._clients = {};
+  }
+  // ── clients (lazy, optionally region-scoped) ──────────────────────────────
+  _clientConfig(region) {
+    const cfg = { region: region || this.region };
+    if (this._credentials) cfg.credentials = this._credentials;
+    return cfg;
+  }
+  _sts() {
+    return this._clients.sts ??= new STSClient(this._clientConfig());
+  }
+  _ec2(region) {
+    const key = `ec2:${region || this.region}`;
+    return this._clients[key] ??= new EC2Client(this._clientConfig(region));
+  }
+  _route53() {
+    return this._clients.route53 ??= new Route53Client(this._clientConfig());
+  }
+  getRegion() {
+    return this.region;
+  }
+  // ── identity ──────────────────────────────────────────────────────────────
+  /** { account, arn, userId } — confirm which account/identity the keys belong to. */
+  async whoAmI() {
+    const out = await this._sts().send(new GetCallerIdentityCommand({}));
+    return { account: out.Account, arn: out.Arn, userId: out.UserId };
+  }
+  // ── regions / AZs ──────────────────────────────────────────────────────────
+  /** Enabled region names, sorted. */
+  async listRegions({ allRegions = false } = {}) {
+    const out = await this._ec2().send(new DescribeRegionsCommand({ AllRegions: allRegions }));
+    return (out.Regions ?? []).map((r) => r.RegionName).sort();
+  }
+  /** Availability zone names for a region (defaults to the instance region). */
+  async listAvailabilityZones(region) {
+    const out = await this._ec2(region).send(new DescribeAvailabilityZonesCommand({}));
+    return (out.AvailabilityZones ?? []).filter((z) => z.State === "available").map((z) => z.ZoneName).sort();
+  }
+  // ── VPC / subnets / SGs / key pairs ────────────────────────────────────────
+  /** [{ id, cidr, isDefault, name }] in a region. */
+  async listVpcs(region) {
+    const out = await this._ec2(region).send(new DescribeVpcsCommand({}));
+    return (out.Vpcs ?? []).map((v) => ({
+      id: v.VpcId,
+      cidr: v.CidrBlock,
+      isDefault: !!v.IsDefault,
+      name: nameTag(v.Tags)
+    }));
+  }
+  /** [{ id, vpcId, az, cidr, public, name }]; pass vpcId to scope. */
+  async listSubnets({ vpcId, region } = {}) {
+    const Filters = vpcId ? [{ Name: "vpc-id", Values: [vpcId] }] : void 0;
+    const out = await this._ec2(region).send(new DescribeSubnetsCommand({ Filters }));
+    return (out.Subnets ?? []).map((s) => ({
+      id: s.SubnetId,
+      vpcId: s.VpcId,
+      az: s.AvailabilityZone,
+      cidr: s.CidrBlock,
+      public: !!s.MapPublicIpOnLaunch,
+      name: nameTag(s.Tags)
+    }));
+  }
+  /** [{ id, name, vpcId, description }]; pass vpcId to scope. */
+  async listSecurityGroups({ vpcId, region } = {}) {
+    const Filters = vpcId ? [{ Name: "vpc-id", Values: [vpcId] }] : void 0;
+    const out = await this._ec2(region).send(new DescribeSecurityGroupsCommand({ Filters }));
+    return (out.SecurityGroups ?? []).map((g) => ({
+      id: g.GroupId,
+      name: g.GroupName,
+      vpcId: g.VpcId,
+      description: g.Description
+    }));
+  }
+  /** [{ name, fingerprint }] EC2 key pairs in a region. */
+  async listKeyPairs(region) {
+    const out = await this._ec2(region).send(new DescribeKeyPairsCommand({}));
+    return (out.KeyPairs ?? []).map((k) => ({ name: k.KeyName, fingerprint: k.KeyFingerprint }));
+  }
+  // ── Route53 ────────────────────────────────────────────────────────────────
+  /** [{ id, name, private, recordCount }] — id is the bare zone id (no /hostedzone/). */
+  async listHostedZones() {
+    const zones = [];
+    let marker;
+    do {
+      const out = await this._route53().send(new ListHostedZonesCommand({ Marker: marker }));
+      for (const z of out.HostedZones ?? []) {
+        zones.push({
+          id: (z.Id ?? "").replace("/hostedzone/", ""),
+          name: (z.Name ?? "").replace(/\.$/, ""),
+          // strip trailing dot
+          private: !!z.Config?.PrivateZone,
+          recordCount: z.ResourceRecordSetCount
+        });
+      }
+      marker = out.IsTruncated ? out.NextMarker : void 0;
+    } while (marker);
+    return zones;
+  }
+  /**
+   * Best hosted zone for a domain: exact match, else the longest zone name that
+   * is a suffix of the domain (so "api.foo.com" matches the "foo.com" zone).
+   * Returns the zone object or null.
+   */
+  async findHostedZoneForDomain(domain) {
+    const target = String(domain ?? "").replace(/\.$/, "").toLowerCase();
+    if (!target) return null;
+    const zones = await this.listHostedZones();
+    const exact = zones.find((z) => z.name.toLowerCase() === target);
+    if (exact) return exact;
+    return zones.filter((z) => target.endsWith(`.${z.name.toLowerCase()}`)).sort((a, b) => b.name.length - a.name.length)[0] ?? null;
+  }
+  // ── AMI lookup ──────────────────────────────────────────────────────────────
+  /**
+   * Latest Ubuntu AMI matching a name pattern in a region.
+   * Returns { id, name, creationDate, architecture } or null.
+   */
+  async findLatestUbuntuAmi({ region, pattern = DEFAULT_UBUNTU_PATTERN, architecture = "x86_64" } = {}) {
+    const out = await this._ec2(region).send(new DescribeImagesCommand({
+      Owners: [CANONICAL_OWNER_ID],
+      Filters: [
+        { Name: "name", Values: [pattern] },
+        { Name: "virtualization-type", Values: ["hvm"] },
+        { Name: "state", Values: ["available"] },
+        ...architecture ? [{ Name: "architecture", Values: [architecture] }] : []
+      ]
+    }));
+    const newest = (out.Images ?? []).sort((a, b) => String(b.CreationDate).localeCompare(String(a.CreationDate)))[0];
+    if (!newest) return null;
+    return {
+      id: newest.ImageId,
+      name: newest.Name,
+      creationDate: newest.CreationDate,
+      architecture: newest.Architecture
+    };
+  }
+};
+
 // src/logger/index.js
 import chalk from "chalk";
 import util from "util";
@@ -4317,9 +4520,18 @@ function setup(opts = {}) {
     // the used-params list now (after the script has initialized all its
     // own components), instead of at exit. No-op for the default mode,
     // which prints at exit via the cleanup registered by Params.
+    //
+    // --showUsedParams=stop behaves like "top" but then exits immediately —
+    // a quick "show me the figured params and quit" that skips the flow's
+    // actual work. Like --stopAfter=init, this is a hard exit(0) (registered
+    // cleanups are skipped); call it once components/params are resolved.
     showUsedParamsIfNeeded: () => {
-      if (params.getShowUsedParamsMode?.() === "top") {
-        params.printUsedParams(logger);
+      const mode = params.getShowUsedParamsMode?.();
+      if (mode !== "top" && mode !== "stop") return;
+      params.printUsedParams(logger);
+      if (mode === "stop") {
+        logger.debug?.("[showUsedParams=stop] params printed \u2014 exiting");
+        process.exit(0);
       }
     }
   };
@@ -4330,12 +4542,1061 @@ function setupContext(opts = {}) {
   return setup(opts);
 }
 
+// src/deploy/service.js
+function deriveRepoDirName(repoUrl) {
+  const tail = String(repoUrl ?? "").split("/").pop() ?? "repo";
+  return tail.replace(/\.git$/, "") || "repo";
+}
+function defineService(service) {
+  if (!service?.name) throw new Error("service manifest needs a `name`");
+  if (!service.appsRoot) throw new Error(`service "${service.name}" needs an appsRoot`);
+  if (!service.repoUrl) throw new Error(`service "${service.name}" needs a repoUrl`);
+  if (!service.pm2?.script) throw new Error(`service "${service.name}" needs pm2.script`);
+  const pm2 = {
+    appName: service.name,
+    args: "",
+    ...service.pm2
+  };
+  const nginx = service.nginx ? { siteName: service.name, ...service.nginx } : null;
+  return {
+    repoDirName: deriveRepoDirName(service.repoUrl),
+    repoSubdir: "",
+    keepReleases: 3,
+    testCommand: null,
+    envScrubPatterns: [],
+    legacyRepoEnv: null,
+    buildInfoPath: "build-info.json",
+    deployKey: null,
+    requireEnv: false,
+    ...service,
+    pm2,
+    nginx
+  };
+}
+
+// src/deploy/paths.js
+import { join as join2 } from "path";
+function servicePaths(service) {
+  const root = service.appsRoot;
+  const repoDirName = service.repoDirName ?? "repo";
+  const repoSubdir = service.repoSubdir ?? "";
+  const repo = join2(root, repoDirName);
+  const repoRun = repoSubdir ? join2(repo, repoSubdir) : repo;
+  return {
+    root,
+    repo,
+    repoRun,
+    repoEnv: join2(repoRun, ".env"),
+    releases: join2(root, "releases"),
+    shared: join2(root, "shared"),
+    logs: join2(root, "logs"),
+    current: join2(root, "current"),
+    sharedEnv: join2(root, "shared", ".env"),
+    ecosystem: join2(root, "shared", "ecosystem.config.cjs"),
+    deployLog: join2(root, "logs", "deploy.log"),
+    lockHashFile: join2(root, "shared", ".package-lock.sha256")
+  };
+}
+function releaseStamp(date = /* @__PURE__ */ new Date()) {
+  return date.toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+function releaseDir(releasesRoot, stamp) {
+  return join2(releasesRoot, stamp);
+}
+
+// src/deploy/run.js
+import { spawn } from "child_process";
+function npmEnv(baseEnv = process.env) {
+  const env = { ...baseEnv };
+  delete env.NODE_ENV;
+  return env;
+}
+function npmInstallEnv(baseEnv = process.env) {
+  return {
+    ...npmEnv(baseEnv),
+    NPM_CONFIG_PRODUCTION: "false",
+    npm_config_production: "false"
+  };
+}
+function run(cmd, args, options = {}) {
+  const { cwd, env, logger } = options;
+  return new Promise((resolve3, reject) => {
+    logger?.info?.(`$ ${cmd} ${args.join(" ")}${cwd ? `  (cwd=${cwd})` : ""}`);
+    const child = spawn(cmd, args, {
+      cwd,
+      env: env ?? process.env,
+      stdio: "inherit"
+    });
+    child.on("error", reject);
+    child.on("close", (code) => {
+      if (code === 0) resolve3();
+      else reject(new Error(`${cmd} exited with code ${code}`));
+    });
+  });
+}
+function runShell(command, options = {}) {
+  return run("bash", ["-lc", command], options);
+}
+
+// src/deploy/log.js
+import { appendFile, mkdir } from "fs/promises";
+async function appendDeployLog(deployLogPath, message) {
+  await mkdir(deployLogPath.replace(/\/[^/]+$/, ""), { recursive: true });
+  const line = `[${(/* @__PURE__ */ new Date()).toISOString()}] ${message}
+`;
+  await appendFile(deployLogPath, line);
+}
+
+// src/deploy/git.js
+import { access } from "fs/promises";
+async function pathExists(path5) {
+  try {
+    await access(path5);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function cloneRepo(service, options = {}) {
+  const { dryRun = false, logger = console } = options;
+  const paths = servicePaths(service);
+  if (await pathExists(paths.repo)) {
+    throw new Error(`Repo already exists at ${paths.repo} \u2014 use git pull instead`);
+  }
+  if (dryRun) {
+    logger.info(`[dryRun] would git clone ${service.repoUrl} ${paths.repo}`);
+    return;
+  }
+  await run("git", ["clone", service.repoUrl, paths.repo], { logger });
+  logger.info(`cloned ${service.repoUrl} \u2192 ${paths.repo}`);
+}
+async function pullRepo(service, options = {}) {
+  const { dryRun = false, logger = console } = options;
+  const paths = servicePaths(service);
+  if (!await pathExists(paths.repo)) {
+    throw new Error(`Repo missing at ${paths.repo} \u2014 run provision first`);
+  }
+  if (dryRun) {
+    logger.info(`[dryRun] would git -C ${paths.repo} pull --ff-only`);
+    return;
+  }
+  await run("git", ["-C", paths.repo, "pull", "--ff-only"], { logger });
+  logger.info(`pulled ${paths.repo}`);
+}
+
+// src/deploy/release.js
+import { cp, mkdir as mkdir2, readlink, readdir, stat } from "fs/promises";
+import { join as join3, dirname as pathDirname, sep } from "path";
+var SKIP_TOP = /* @__PURE__ */ new Set(["node_modules", ".git"]);
+function shouldCopyEntry(srcPath) {
+  const parts = srcPath.split(sep);
+  if (parts.some((p) => p === "node_modules" || p === ".git")) return false;
+  const top = parts.at(-1);
+  if (parts.length === 1 && SKIP_TOP.has(top)) return false;
+  return true;
+}
+async function createRelease(service, options = {}) {
+  const { stamp = releaseStamp(), dryRun = false, logger = console } = options;
+  const paths = servicePaths(service);
+  const dest = releaseDir(paths.releases, stamp);
+  if (dryRun) {
+    logger.info(`[dryRun] would copy ${paths.repoRun} \u2192 ${dest}`);
+    return { stamp, path: dest };
+  }
+  await mkdir2(paths.releases, { recursive: true });
+  await cp(paths.repoRun, dest, {
+    recursive: true,
+    filter: (src) => shouldCopyEntry(src)
+  });
+  logger.info(`release ${stamp} created at ${dest}`);
+  return { stamp, path: dest };
+}
+async function readCurrentRelease(paths) {
+  try {
+    const target = await readlink(paths.current);
+    return target.startsWith("/") ? target : join3(pathDirname(paths.current), target);
+  } catch {
+    return null;
+  }
+}
+async function listReleases(paths) {
+  let names;
+  try {
+    names = await readdir(paths.releases);
+  } catch {
+    return [];
+  }
+  const entries = [];
+  for (const name of names) {
+    const full = releaseDir(paths.releases, name);
+    const s = await stat(full);
+    if (s.isDirectory()) entries.push({ name, path: full, mtime: s.mtime });
+  }
+  entries.sort((a, b) => b.name.localeCompare(a.name));
+  return entries;
+}
+
+// src/deploy/activate.js
+import { symlink, unlink } from "fs/promises";
+import { join as join4 } from "path";
+async function activateRelease(releasePath, paths, options = {}) {
+  const { dryRun = false, logger = console } = options;
+  if (dryRun) {
+    logger.info(`[dryRun] would activate ${releasePath} \u2192 ${paths.current}`);
+    return;
+  }
+  try {
+    await unlink(paths.current);
+  } catch {
+  }
+  await symlink(releasePath, paths.current);
+  const envLink = join4(releasePath, ".env");
+  try {
+    await unlink(envLink);
+  } catch {
+  }
+  await symlink(paths.sharedEnv, envLink);
+  logger.info(`active release: ${releasePath}`);
+}
+
+// src/deploy/deps.js
+import { createHash } from "crypto";
+import { access as access2, cp as cp2, mkdir as mkdir3, readFile, rm, writeFile } from "fs/promises";
+import { join as join5 } from "path";
+async function pathExists2(path5) {
+  try {
+    await access2(path5);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function lockfileHash(releasePath) {
+  const lockPath = join5(releasePath, "package-lock.json");
+  try {
+    const buf = await readFile(lockPath);
+    return createHash("sha256").update(buf).digest("hex");
+  } catch {
+    return null;
+  }
+}
+async function readHashFile(path5) {
+  try {
+    return (await readFile(path5, "utf8")).trim();
+  } catch {
+    return null;
+  }
+}
+async function npmInstall(releasePath, hasLock, logger) {
+  await rm(join5(releasePath, "node_modules"), { recursive: true, force: true });
+  const cmd = hasLock ? ["ci", "--include=dev"] : ["install", "--include=dev", "--no-audit", "--no-fund"];
+  logger.info(`running npm ${cmd.join(" ")} in ${releasePath}`);
+  await run("npm", cmd, { cwd: releasePath, logger, env: npmInstallEnv() });
+}
+async function installDeps(service, releasePath, paths, options = {}) {
+  const { dryRun = false, logger = console } = options;
+  if (dryRun) {
+    logger.info(`[dryRun] would install deps in ${releasePath}`);
+    return { hash: null, copied: false };
+  }
+  const hash = await lockfileHash(releasePath);
+  const hasLock = hash !== null;
+  const hashMarker = join5(releasePath, ".deploy-package-lock.sha256");
+  const currentPath = await readCurrentRelease(paths);
+  let copied = false;
+  if (hasLock && currentPath && await pathExists2(join5(currentPath, "node_modules"))) {
+    const currentHash = await readHashFile(join5(currentPath, ".deploy-package-lock.sha256"));
+    if (currentHash === hash) {
+      logger.info("lockfile unchanged \u2014 copying node_modules from current release");
+      await cp2(join5(currentPath, "node_modules"), join5(releasePath, "node_modules"), {
+        recursive: true,
+        force: true
+      });
+      copied = true;
+    }
+  }
+  if (!copied) {
+    await npmInstall(releasePath, hasLock, logger);
+  }
+  if (hasLock) {
+    await writeFile(hashMarker, `${hash}
+`, "utf8");
+    await mkdir3(paths.shared, { recursive: true });
+    await writeFile(paths.lockHashFile, `${hash}
+`, "utf8");
+  }
+  return { hash, copied };
+}
+
+// src/deploy/test.js
+import { symlink as symlink2, unlink as unlink2 } from "fs/promises";
+import { join as join6 } from "path";
+async function runReleaseTests(service, releasePath, paths, options = {}) {
+  const { dryRun = false, logger = console } = options;
+  if (!service.testCommand) {
+    logger.info("no testCommand configured \u2014 skipping tests");
+    return;
+  }
+  if (dryRun) {
+    logger.info(`[dryRun] would run "${service.testCommand}" in ${releasePath}`);
+    return;
+  }
+  const envLink = join6(releasePath, ".env");
+  try {
+    await unlink2(envLink);
+  } catch {
+  }
+  await symlink2(paths.sharedEnv, envLink);
+  logger.info(`running "${service.testCommand}" in ${releasePath}`);
+  await runShell(service.testCommand, { cwd: releasePath, logger, env: npmInstallEnv() });
+}
+
+// src/deploy/prune.js
+import { rm as rm2, readlink as readlink2 } from "fs/promises";
+async function pruneReleases(service, paths, options = {}) {
+  const { dryRun = false, logger = console } = options;
+  const keep = service.keepReleases ?? 3;
+  const releases = await listReleases(paths);
+  let activeName = null;
+  try {
+    const target = await readlink2(paths.current);
+    activeName = target.split("/").pop();
+  } catch {
+  }
+  const keepSet = /* @__PURE__ */ new Set();
+  for (const rel of releases) {
+    if (keepSet.size < keep) keepSet.add(rel.name);
+  }
+  if (activeName) keepSet.add(activeName);
+  const toRemove = releases.filter((rel) => !keepSet.has(rel.name));
+  for (const rel of toRemove) {
+    if (dryRun) {
+      logger.info(`[dryRun] would rm -rf ${rel.path}`);
+    } else {
+      await rm2(rel.path, { recursive: true, force: true });
+      logger.info(`pruned ${rel.path}`);
+    }
+  }
+  return { removed: toRemove.map((r) => r.name) };
+}
+
+// src/deploy/pm2.js
+async function reloadPm2(paths, options = {}) {
+  const { dryRun = false, logger = console } = options;
+  if (dryRun) {
+    logger.info(`[dryRun] would pm2 startOrReload ${paths.ecosystem} --update-env`);
+    return;
+  }
+  await runShell(`pm2 startOrReload "${paths.ecosystem}" --update-env`, { logger });
+  logger.info("pm2 reloaded");
+}
+
+// src/deploy/nginx.js
+import { writeFile as writeFile2 } from "fs/promises";
+import { tmpdir } from "os";
+import { join as join7 } from "path";
+async function hasTlsCert(certPath) {
+  try {
+    await runShell(`sudo test -f '${certPath}'`, {});
+    return true;
+  } catch {
+    return false;
+  }
+}
+function proxyBlock(port) {
+  return `  location / {
+    proxy_pass http://127.0.0.1:${port};
+    proxy_http_version 1.1;
+    proxy_set_header Host $host;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto $scheme;
+    proxy_read_timeout 120s;
+  }`;
+}
+function buildNginxConfig(service) {
+  const { nginx, pm2 } = service;
+  const certDir = `/etc/letsencrypt/live/${nginx.fqdn}`;
+  return `# ${nginx.siteName} \u2014 managed by cli-toolkit deploy (proxy mode)
+# ${nginx.fqdn} \u2192 127.0.0.1:${pm2.port}
+
+server {
+  listen 80;
+  listen [::]:80;
+  server_name ${nginx.fqdn};
+  location / { return 301 https://$host$request_uri; }
+}
+
+server {
+  listen 443 ssl;
+  listen [::]:443 ssl;
+  server_name ${nginx.fqdn};
+
+  ssl_certificate ${certDir}/fullchain.pem;
+  ssl_certificate_key ${certDir}/privkey.pem;
+  include /etc/letsencrypt/options-ssl-nginx.conf;
+  ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;
+
+  client_max_body_size 25m;
+
+${proxyBlock(pm2.port)}
+}
+`;
+}
+function buildNginxConfigHttpOnly(service) {
+  const { nginx, pm2 } = service;
+  return `# ${nginx.siteName} \u2014 managed by cli-toolkit deploy (HTTP proxy, no TLS cert yet)
+
+server {
+  listen 80;
+  listen [::]:80;
+  server_name ${nginx.fqdn};
+
+  client_max_body_size 25m;
+
+${proxyBlock(pm2.port)}
+}
+`;
+}
+async function enableNginxUpstream(service, options = {}) {
+  const { dryRun = false, logger = console } = options;
+  const { nginx } = service;
+  if (!nginx) {
+    logger.info("no nginx config on service \u2014 skipping nginx step");
+    return { skipped: true };
+  }
+  const siteAvailable = `/etc/nginx/sites-available/${nginx.siteName}`;
+  const siteEnabled = `/etc/nginx/sites-enabled/${nginx.siteName}`;
+  const cert = `/etc/letsencrypt/live/${nginx.fqdn}/fullchain.pem`;
+  if (dryRun) {
+    logger.info(`[dryRun] would write ${siteAvailable} (proxy \u2192 127.0.0.1:${service.pm2.port}) and reload nginx`);
+    return { hasCert: null };
+  }
+  const hasCert = await hasTlsCert(cert);
+  const config2 = hasCert ? buildNginxConfig(service) : buildNginxConfigHttpOnly(service);
+  const tmp = join7(tmpdir(), `${service.name}-nginx.conf`);
+  await writeFile2(tmp, config2);
+  await runShell(
+    `sudo cp '${tmp}' '${siteAvailable}' && sudo ln -sf '${siteAvailable}' '${siteEnabled}' && sudo nginx -t && sudo systemctl reload nginx`,
+    { logger }
+  );
+  logger.info(`nginx upstream enabled for ${nginx.fqdn} \u2192 127.0.0.1:${service.pm2.port} (tls=${hasCert})`);
+  return { hasCert };
+}
+
+// src/deploy/sync-env.js
+import { access as access3, mkdir as mkdir4, readFile as readFile2, writeFile as writeFile3 } from "fs/promises";
+function scrubEnvContent(content, patterns = []) {
+  const regexes = patterns.map((p) => p instanceof RegExp ? p : new RegExp(p));
+  if (regexes.length === 0) return content;
+  return content.split("\n").filter((line) => !regexes.some((re) => re.test(line.trim()))).join("\n");
+}
+async function pathExists3(path5) {
+  try {
+    await access3(path5);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function syncEnv(service, options = {}) {
+  const { dryRun = false, logger = console } = options;
+  const paths = servicePaths(service);
+  const patterns = service.envScrubPatterns ?? [];
+  if (dryRun) {
+    logger.info(`[dryRun] would sync ${paths.repoEnv} \u2192 ${paths.sharedEnv}`);
+    return { source: paths.repoEnv, dest: paths.sharedEnv };
+  }
+  let source = paths.repoEnv;
+  if (!await pathExists3(source) && service.legacyRepoEnv && await pathExists3(service.legacyRepoEnv)) {
+    logger.info(`using legacy env: ${service.legacyRepoEnv}`);
+    source = service.legacyRepoEnv;
+  }
+  await mkdir4(paths.shared, { recursive: true });
+  if (!await pathExists3(source)) {
+    if (service.requireEnv) {
+      throw new Error(
+        `No .env found at ${paths.repoEnv}` + (service.legacyRepoEnv ? ` or ${service.legacyRepoEnv}` : "") + " \u2014 place .env on the host or run the remote deploy from a laptop with a local .env (auto-scp)"
+      );
+    }
+    if (!await pathExists3(paths.sharedEnv)) {
+      await writeFile3(paths.sharedEnv, "", { mode: 384 });
+    }
+    logger.warn(`no .env found (source ${source}) \u2014 using empty ${paths.sharedEnv}`);
+    return { source: null, dest: paths.sharedEnv };
+  }
+  const raw = await readFile2(source, "utf8");
+  await writeFile3(paths.sharedEnv, scrubEnvContent(raw, patterns), { mode: 384 });
+  logger.info(`synced ${source} \u2192 ${paths.sharedEnv}`);
+  return { source, dest: paths.sharedEnv };
+}
+
+// src/deploy/build-info.js
+import { readFile as readFile3, writeFile as writeFile4, mkdir as mkdir5 } from "fs/promises";
+import { join as join8, dirname as dirname2 } from "path";
+import { execFile } from "child_process";
+import { promisify } from "util";
+var execFileAsync = promisify(execFile);
+function bumpPatchVersion(version) {
+  const parts = String(version).trim().split(".");
+  const major = Number.parseInt(parts[0], 10) || 0;
+  const minor = Number.parseInt(parts[1], 10) || 0;
+  const patch = Number.parseInt(parts[2], 10) || 0;
+  return `${major}.${minor}.${patch + 1}`;
+}
+async function readJson(path5) {
+  try {
+    return JSON.parse(await readFile3(path5, "utf8"));
+  } catch {
+    return null;
+  }
+}
+async function gitShortCommit(repoPath) {
+  try {
+    const { stdout } = await execFileAsync("git", ["-C", repoPath, "rev-parse", "--short", "HEAD"], {
+      encoding: "utf8"
+    });
+    return stdout.trim() || null;
+  } catch {
+    return null;
+  }
+}
+async function resolveNextVersion(service, paths, pkgPath) {
+  const pkg = await readJson(pkgPath) ?? {};
+  const baseVersion = pkg.version || "0.1.0";
+  const currentPath = await readCurrentRelease(paths);
+  if (currentPath) {
+    const active = await readJson(join8(currentPath, service.buildInfoPath));
+    if (active?.version) return bumpPatchVersion(active.version);
+  }
+  return baseVersion;
+}
+async function readReleaseBuildInfo(service, releasePath) {
+  return readJson(join8(releasePath, service.buildInfoPath));
+}
+async function writeReleaseBuildInfo(service, releasePath, { stamp, dryRun = false, logger = console }) {
+  const paths = servicePaths(service);
+  const pkgPath = join8(paths.repoRun, "package.json");
+  const version = await resolveNextVersion(service, paths, pkgPath);
+  const gitCommit = await gitShortCommit(paths.repo);
+  const buildInfo = {
+    version,
+    release: stamp,
+    deployedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    gitCommit,
+    service: service.name
+  };
+  const dest = join8(releasePath, service.buildInfoPath);
+  if (dryRun) {
+    logger.info(`[dryRun] would write ${dest} (${JSON.stringify(buildInfo)})`);
+    return buildInfo;
+  }
+  await mkdir5(dirname2(dest), { recursive: true });
+  await writeFile4(dest, `${JSON.stringify(buildInfo, null, 2)}
+`, { mode: 420 });
+  const gitSuffix = gitCommit ? ` git=${gitCommit}` : "";
+  logger.info(`build info: v${version} release=${stamp}${gitSuffix}`);
+  return buildInfo;
+}
+
+// src/deploy/init-structure.js
+import { access as access4, appendFile as appendFile2, mkdir as mkdir6, writeFile as writeFile5 } from "fs/promises";
+import { dirname as dirname3, join as join9 } from "path";
+async function pathExists4(path5) {
+  try {
+    await access4(path5);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function requireDeployRoot(parentDir, serviceRoot) {
+  if (await pathExists4(parentDir)) return;
+  throw new Error(
+    `Cannot create ${serviceRoot}: parent directory ${parentDir} does not exist.
+This is meant to run on the target host (where ${parentDir} exists). For a local dry run use --appsRoot=/tmp/<service>.`
+  );
+}
+function buildEcosystemConfig(service, paths) {
+  const { pm2 } = service;
+  const outLog = join9(paths.logs, `${pm2.appName}.out.log`);
+  const errLog = join9(paths.logs, `${pm2.appName}.err.log`);
+  return `/**
+ * pm2 ecosystem for ${service.name} \u2014 seeded by cli-toolkit deploy (init).
+ *
+ * cwd points at the \`current\` symlink (created on first deploy).
+ * Tweak \`args\` here, then: pm2 reload ${paths.ecosystem} --update-env
+ */
+module.exports = {
+    apps: [
+        {
+            name: "${pm2.appName}",
+            script: "${pm2.script}",
+            cwd: "${paths.current}",
+            args: "${pm2.args}",
+            instances: 1,
+            exec_mode: "fork",
+            autorestart: true,
+            min_uptime: "10s",
+            max_restarts: 10,
+            restart_delay: 2000,
+            max_memory_restart: "1500M",
+            out_file: "${outLog}",
+            error_file: "${errLog}",
+            merge_logs: true,
+            time: true,
+            env: {
+                NODE_ENV: "production",
+            },
+        },
+    ],
+};
+`;
+}
+async function initServiceStructure(service, options = {}) {
+  const { dryRun = false, logger = console } = options;
+  const paths = servicePaths(service);
+  const dirs = [paths.releases, paths.shared, paths.logs];
+  const created = [];
+  const skipped = [];
+  if (!dryRun) {
+    await requireDeployRoot(dirname3(paths.root), paths.root);
+  }
+  for (const dir of dirs) {
+    if (await pathExists4(dir)) {
+      skipped.push(dir);
+      continue;
+    }
+    if (!dryRun) await mkdir6(dir, { recursive: true });
+    created.push(dir);
+  }
+  let ecosystemCreated = false;
+  if (await pathExists4(paths.ecosystem)) {
+    skipped.push(paths.ecosystem);
+  } else {
+    if (!dryRun) {
+      await writeFile5(paths.ecosystem, buildEcosystemConfig(service, paths), { mode: 420 });
+    }
+    ecosystemCreated = true;
+    created.push(paths.ecosystem);
+  }
+  const line = `[${(/* @__PURE__ */ new Date()).toISOString()}] init-structure service=${service.name} dryRun=${dryRun} created=${created.length} skipped=${skipped.length}
+`;
+  if (!dryRun) {
+    await mkdir6(paths.logs, { recursive: true });
+    await appendFile2(paths.deployLog, line);
+  }
+  logger.info(`service=${service.name} appsRoot=${paths.root}`);
+  logger.info(`created: ${created.length ? created.join(", ") : "(none)"}`);
+  logger.info(`already present: ${skipped.length ? skipped.join(", ") : "(none)"}`);
+  if (ecosystemCreated) logger.info(`seeded ${paths.ecosystem}`);
+  return { paths, created, skipped, ecosystemCreated };
+}
+
+// src/deploy/bootstrap-host.js
+import { execSync as execSync2 } from "child_process";
+import { access as access5, chmod, copyFile, mkdir as mkdir7, readFile as readFile4, writeFile as writeFile6 } from "fs/promises";
+import { homedir } from "os";
+import { basename as basename2, join as join10 } from "path";
+async function pathExists5(path5) {
+  try {
+    await access5(path5);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function expandHome(path5) {
+  return path5.startsWith("~/") ? join10(homedir(), path5.slice(2)) : path5;
+}
+async function ensurePm2Startup(options = {}) {
+  const { user = "ubuntu", dryRun = false, logger = console } = options;
+  if (dryRun) {
+    logger.info("[dryRun] would configure pm2 startup systemd");
+    return;
+  }
+  try {
+    execSync2("pm2 ping", { stdio: "ignore" });
+  } catch {
+  }
+  try {
+    const out = execSync2(`pm2 startup systemd -u ${user} --hp /home/${user}`, { encoding: "utf8" });
+    const sudoLine = out.split("\n").find((l) => l.trim().startsWith("sudo"));
+    if (sudoLine) {
+      execSync2(sudoLine.trim(), { stdio: "inherit" });
+      logger.info("pm2 startup systemd configured");
+    }
+  } catch (err) {
+    logger.warn(`pm2 startup skipped or already configured: ${err.message}`);
+  }
+}
+async function installDeployKey(deployKeyPath, options = {}) {
+  const { dryRun = false, logger = console } = options;
+  const keyPath = expandHome(deployKeyPath);
+  if (!await pathExists5(keyPath)) {
+    logger.warn(`deploy key not found at ${keyPath} \u2014 skipping git ssh setup`);
+    return;
+  }
+  const keyBase = basename2(keyPath);
+  const sshDir = join10(homedir(), ".ssh");
+  const destKey = join10(sshDir, keyBase);
+  const configPath = join10(sshDir, "config");
+  const block = `
+Host github.com
+  HostName github.com
+  User git
+  IdentityFile ${destKey}
+  IdentitiesOnly yes
+`;
+  if (dryRun) {
+    logger.info(`[dryRun] would install deploy key ${keyPath} \u2192 ${destKey}`);
+    return;
+  }
+  await mkdir7(sshDir, { recursive: true, mode: 448 });
+  await copyFile(keyPath, destKey);
+  await chmod(destKey, 384);
+  let config2 = "";
+  if (await pathExists5(configPath)) config2 = await readFile4(configPath, "utf8");
+  if (!config2.includes("Host github.com")) {
+    await writeFile6(configPath, `${config2.trimEnd()}
+${block}
+`, { mode: 384 });
+    logger.info("updated ~/.ssh/config for github.com");
+  }
+  logger.info(`deploy key installed at ${destKey}`);
+}
+async function installLogrotate(service, options = {}) {
+  const { dryRun = false, logger = console } = options;
+  const conf = `/etc/logrotate.d/${service.name}`;
+  const body = `${service.appsRoot}/logs/*.log {
+  daily
+  rotate 14
+  compress
+  delaycompress
+  missingok
+  notifempty
+  copytruncate
+}
+`;
+  if (dryRun) {
+    logger.info(`[dryRun] would write ${conf}`);
+    return;
+  }
+  const tmp = join10("/tmp", `${service.name}-logrotate.conf`);
+  await writeFile6(tmp, body);
+  await runShell(`sudo cp '${tmp}' '${conf}'`, { logger });
+  logger.info(`logrotate config written: ${conf}`);
+}
+async function bootstrapHost(service, options = {}) {
+  const { deployKey = service.deployKey, user = "ubuntu", dryRun = false, logger = console } = options;
+  await ensurePm2Startup({ user, dryRun, logger });
+  if (deployKey) await installDeployKey(deployKey, { dryRun, logger });
+  await installLogrotate(service, { dryRun, logger });
+  logger.info("bootstrap-host complete");
+}
+
+// src/deploy/deploy-service.js
+async function deployService(service, options = {}) {
+  const {
+    dryRun = false,
+    skipPull = false,
+    skipTests = false,
+    skipNginx = false,
+    logger = console
+  } = options;
+  const paths = servicePaths(service);
+  await initServiceStructure(service, { dryRun, logger });
+  if (!skipPull) await pullRepo(service, { dryRun, logger });
+  await syncEnv(service, { dryRun, logger });
+  const { stamp, path: releasePath } = await createRelease(service, { dryRun, logger });
+  await writeReleaseBuildInfo(service, releasePath, { stamp, dryRun, logger });
+  await installDeps(service, releasePath, paths, { dryRun, logger });
+  if (!skipTests) await runReleaseTests(service, releasePath, paths, { dryRun, logger });
+  await activateRelease(releasePath, paths, { dryRun, logger });
+  await pruneReleases(service, paths, { dryRun, logger });
+  await reloadPm2(paths, { dryRun, logger });
+  if (!skipNginx) await enableNginxUpstream(service, { dryRun, logger });
+  const summary = `deploy complete stamp=${stamp} dryRun=${dryRun}`;
+  logger.info(summary);
+  if (!dryRun) await appendDeployLog(paths.deployLog, summary);
+  return { stamp, releasePath };
+}
+
+// src/deploy/provision-service.js
+import { access as access6 } from "fs/promises";
+async function pathExists6(path5) {
+  try {
+    await access6(path5);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function provisionService(service, options = {}) {
+  const {
+    dryRun = false,
+    deploy = true,
+    skipBootstrap = true,
+    deployKey,
+    logger = console
+  } = options;
+  if (!skipBootstrap) {
+    await bootstrapHost(service, { deployKey, dryRun, logger });
+  }
+  await initServiceStructure(service, { dryRun, logger });
+  const paths = servicePaths(service);
+  if (await pathExists6(paths.repo)) {
+    logger.info(`repo exists at ${paths.repo} \u2014 pulling`);
+    await pullRepo(service, { dryRun, logger });
+  } else {
+    await cloneRepo(service, { dryRun, logger });
+  }
+  await syncEnv(service, { dryRun, logger });
+  if (deploy) {
+    await deployService(service, { dryRun, logger, skipPull: true });
+  } else {
+    logger.info("provision complete (deploy skipped)");
+  }
+}
+
+// src/deploy/rollback-service.js
+import { readlink as readlink3 } from "fs/promises";
+async function rollbackService(service, options = {}) {
+  const { release: targetName, dryRun = false, logger = console } = options;
+  const paths = servicePaths(service);
+  const releases = await listReleases(paths);
+  if (releases.length === 0) throw new Error("No releases to roll back to");
+  let activeName = null;
+  try {
+    const target = await readlink3(paths.current);
+    activeName = target.split("/").pop();
+  } catch {
+    throw new Error("No active release (current symlink missing)");
+  }
+  let rollbackTarget;
+  if (targetName) {
+    rollbackTarget = releases.find((r) => r.name === targetName);
+    if (!rollbackTarget) throw new Error(`Release not found: ${targetName}`);
+  } else {
+    rollbackTarget = releases.find((r) => r.name !== activeName);
+    if (!rollbackTarget) throw new Error("No previous release to roll back to");
+  }
+  if (rollbackTarget.name === activeName) throw new Error(`Already on release ${activeName}`);
+  logger.info(`rollback ${activeName} \u2192 ${rollbackTarget.name}`);
+  const buildInfo = await readReleaseBuildInfo(service, rollbackTarget.path);
+  if (buildInfo?.version) {
+    logger.info(`rollback target: v${buildInfo.version} release=${buildInfo.release ?? rollbackTarget.name}`);
+  }
+  await activateRelease(rollbackTarget.path, paths, { dryRun, logger });
+  await reloadPm2(paths, { dryRun, logger });
+  const summary = `rollback ${activeName} \u2192 ${rollbackTarget.name} dryRun=${dryRun}`;
+  if (!dryRun) await appendDeployLog(paths.deployLog, summary);
+  return { from: activeName, to: rollbackTarget.name, path: rollbackTarget.path };
+}
+
+// src/deploy/ssh-remote.js
+import { access as access7, readFile as readFile5, writeFile as writeFile7 } from "fs/promises";
+import { homedir as homedir2, tmpdir as tmpdir2 } from "os";
+import { basename as basename3, dirname as dirname4, join as join11 } from "path";
+import { spawn as spawn2 } from "child_process";
+var REMOTE_CLI_REL = "node_modules/@nmakarov/cli-toolkit/scripts/deploy/cli.js";
+async function pathExists7(path5) {
+  try {
+    await access7(path5);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function expandHome2(path5) {
+  return path5.startsWith("~/") ? join11(homedir2(), path5.slice(2)) : path5;
+}
+function resolveLocalEnvPath(envFile) {
+  if (envFile) {
+    const expanded = expandHome2(envFile);
+    return expanded.startsWith("/") ? expanded : join11(process.cwd(), expanded);
+  }
+  return join11(process.cwd(), ".env");
+}
+function parseGitHost(repoUrl) {
+  const u = String(repoUrl ?? "");
+  let m = u.match(/^[^@]+@([^:]+):/);
+  if (m) return m[1];
+  m = u.match(/^ssh:\/\/[^@]+@([^/:]+)/);
+  if (m) return m[1];
+  return null;
+}
+function shellQuote(value) {
+  return `'${String(value).replace(/'/g, `'\\''`)}'`;
+}
+function sshRun(host, remoteCommand, options = {}) {
+  const { logger } = options;
+  return new Promise((resolve3, reject) => {
+    logger?.info?.(`ssh ${host} ${remoteCommand.slice(0, 120)}${remoteCommand.length > 120 ? "\u2026" : ""}`);
+    const child = spawn2("ssh", [host, remoteCommand], { stdio: "inherit" });
+    child.on("error", reject);
+    child.on("close", (code) => code === 0 ? resolve3() : reject(new Error(`ssh ${host} exited with code ${code}`)));
+  });
+}
+function scp(localPath, remoteSpec) {
+  return new Promise((resolve3, reject) => {
+    const child = spawn2("scp", [localPath, remoteSpec], { stdio: "inherit" });
+    child.on("error", reject);
+    child.on("close", (code) => code === 0 ? resolve3() : reject(new Error(`scp exited with code ${code}`)));
+  });
+}
+async function ensureDeployKeyOnRemote(host, deployKeyPath, options = {}) {
+  const { logger = console } = options;
+  if (!deployKeyPath) return false;
+  const localPath = expandHome2(deployKeyPath);
+  if (!await pathExists7(localPath)) return false;
+  const keyBase = basename3(localPath);
+  logger.info(`copying deploy key ${localPath} \u2192 ${host}:~/.ssh/${keyBase}`);
+  await sshRun(host, "mkdir -p ~/.ssh && chmod 700 ~/.ssh", { logger });
+  await scp(localPath, `${host}:.ssh/${keyBase}`, { logger });
+  await sshRun(host, `chmod 600 ~/.ssh/${keyBase}`, { logger });
+  return true;
+}
+async function prepareGitHost(host, options = {}) {
+  const { logger = console, gitHost, keyBasename } = options;
+  if (!gitHost) return;
+  const configBlock = keyBasename ? `if ! grep -q 'Host ${gitHost}' ~/.ssh/config 2>/dev/null; then
+  printf '%s\\n' '' 'Host ${gitHost}' '  HostName ${gitHost}' '  User git' '  IdentityFile ~/.ssh/${keyBasename}' '  IdentitiesOnly yes' >> ~/.ssh/config
+  chmod 600 ~/.ssh/config
+  echo "configured ~/.ssh/config for ${gitHost}"
+fi` : `:`;
+  const script = `
+set -euo pipefail
+mkdir -p ~/.ssh
+chmod 700 ~/.ssh
+if ! grep -q '^${gitHost}' ~/.ssh/known_hosts 2>/dev/null; then
+  ssh-keyscan -t ed25519,rsa ${gitHost} >> ~/.ssh/known_hosts 2>/dev/null
+  echo "added ${gitHost} to known_hosts"
+fi
+${configBlock}
+`.trim();
+  await sshRun(host, script, { logger });
+}
+async function ensureRepoDependencies(host, service, options = {}) {
+  const { logger = console } = options;
+  const paths = servicePaths(service);
+  const run2 = shellQuote(paths.repoRun);
+  await sshRun(
+    host,
+    `cd ${run2} && if [ ! -d node_modules/@nmakarov/cli-toolkit ] || [ package-lock.json -nt node_modules/.package-lock.json ]; then npm ci; fi`,
+    { logger }
+  );
+}
+async function ensureEnvOnRemote(host, service, options = {}) {
+  const { logger = console, envFile } = options;
+  const paths = servicePaths(service);
+  const localPath = resolveLocalEnvPath(envFile);
+  if (!await pathExists7(localPath)) return false;
+  logger.info(`copying .env ${localPath} \u2192 ${host}:${paths.repoEnv}`);
+  await sshRun(host, `mkdir -p ${shellQuote(dirname4(paths.repoEnv))}`, { logger });
+  const scrubbed = scrubEnvContent(await readFile5(localPath, "utf8"), service.envScrubPatterns ?? []);
+  const tmp = join11(tmpdir2(), `deploy-env-${Date.now()}`);
+  await writeFile7(tmp, scrubbed, { mode: 384 });
+  await scp(tmp, `${host}:${paths.repoEnv}`, { logger });
+  await sshRun(host, `chmod 600 ${shellQuote(paths.repoEnv)}`, { logger });
+  return true;
+}
+async function ensureRemoteRepo(host, service, options = {}) {
+  const { logger = console, deployKey = service.deployKey, envFile } = options;
+  const paths = servicePaths(service);
+  const repo = shellQuote(paths.repo);
+  const repoUrl = shellQuote(service.repoUrl);
+  const root = shellQuote(paths.root);
+  const localKeyBase = deployKey ? basename3(expandHome2(deployKey)) : null;
+  await ensureDeployKeyOnRemote(host, deployKey, { logger });
+  await prepareGitHost(host, { logger, gitHost: parseGitHost(service.repoUrl), keyBasename: localKeyBase });
+  await sshRun(
+    host,
+    `mkdir -p ${root} && if [ -d ${repo}/.git ]; then git -C ${repo} pull --ff-only; else git clone ${repoUrl} ${repo}; fi`,
+    { logger }
+  );
+  await ensureRepoDependencies(host, service, { logger });
+  await ensureEnvOnRemote(host, service, { logger, envFile });
+}
+async function runRemoteCli(host, service, command, args = [], options = {}) {
+  const { logger = console, manifests, skipPull = false, deployKey = service.deployKey, envFile } = options;
+  const paths = servicePaths(service);
+  const run2 = shellQuote(paths.repoRun);
+  const cli = shellQuote(REMOTE_CLI_REL);
+  if (!skipPull) {
+    await ensureRemoteRepo(host, service, { logger, deployKey, envFile });
+  } else {
+    await ensureRepoDependencies(host, service, { logger });
+    await ensureEnvOnRemote(host, service, { logger, envFile });
+  }
+  const passthrough = [
+    `--service=${service.name}`,
+    ...manifests ? [`--manifests=${manifests}`] : [],
+    ...args
+  ].map(shellQuote).join(" ");
+  await sshRun(host, `cd ${run2} && node ${cli} ${shellQuote(command)} ${passthrough}`.trim(), { logger });
+}
+async function runRemoteStatus(host, service, options = {}) {
+  const { logger = console } = options;
+  const paths = servicePaths(service);
+  const port = service.pm2.port;
+  const app = service.pm2.appName;
+  const script = `
+echo "=== apps root ==="
+ls -la ${shellQuote(paths.root)} 2>/dev/null || echo "(missing)"
+echo ""
+echo "=== current ==="
+readlink ${shellQuote(paths.current)} 2>/dev/null || echo "(not set)"
+echo ""
+echo "=== releases ==="
+ls -1 ${shellQuote(paths.releases)} 2>/dev/null || echo "(none)"
+echo ""
+echo "=== pm2 ==="
+pm2 describe ${app} 2>/dev/null | head -20 || pm2 status ${app} 2>/dev/null || echo "(not running)"
+${port ? `echo ""
+echo "=== app health (localhost) ==="
+curl -sf http://127.0.0.1:${port}/healthz 2>/dev/null || echo "(no /healthz on :${port})"` : ""}
+`.trim();
+  await sshRun(host, script, { logger });
+}
+
+// src/deploy/manifests.js
+import { isAbsolute as isAbsolute2, resolve as resolve2 } from "path";
+import { pathToFileURL } from "url";
+async function loadServices({ manifests = "deploy/services.js", cwd = process.cwd() } = {}) {
+  const abs = isAbsolute2(manifests) ? manifests : resolve2(cwd, manifests);
+  let mod;
+  try {
+    mod = await import(pathToFileURL(abs).href);
+  } catch (err) {
+    throw new Error(`Could not load deploy manifests from ${abs}: ${err.message}`);
+  }
+  const raw = mod.services ?? mod.default;
+  if (!raw) {
+    throw new Error(`Manifests module ${abs} must export \`services\` (or default): a map or array of service manifests`);
+  }
+  const list = Array.isArray(raw) ? raw : Object.values(raw);
+  const out = {};
+  for (const entry of list) {
+    const svc = defineService(entry);
+    out[svc.name] = svc;
+  }
+  return out;
+}
+function resolveServiceFrom(serviceMap, name, { appsRoot } = {}) {
+  const svc = serviceMap[name];
+  if (!svc) {
+    throw new Error(`Unknown service "${name}". Known: ${Object.keys(serviceMap).join(", ") || "(none)"}`);
+  }
+  return appsRoot ? { ...svc, appsRoot } : svc;
+}
+
 // src/tasks/index.js
 import os3 from "os";
 
 // src/utils/core-utils.js
 function sleepMs(ms) {
-  return new Promise((resolve2) => setTimeout(resolve2, ms));
+  return new Promise((resolve3) => setTimeout(resolve3, ms));
 }
 function toJsonColumn(value) {
   if (value === void 0 || value === null) return null;
@@ -4443,7 +5704,7 @@ function defineTasksTable(t, db, tableNameForIndex) {
   t.timestamp("past_due").defaultTo(null);
   t.text("name").notNullable();
   t.text("opid");
-  t.json("params");
+  t.jsonb("params");
   t.text("service_group");
   t.integer("instance_number");
   t.text("service_name");
@@ -4452,7 +5713,7 @@ function defineTasksTable(t, db, tableNameForIndex) {
   t.timestamp("status_changed_at").defaultTo(null);
   t.text("progress");
   t.boolean("success");
-  t.json("results");
+  t.jsonb("results");
   t.index(["service_group", "status", "priority", "created_at"], `${tableNameForIndex}_claim_idx`);
   t.index(["service_group", "name"], `${tableNameForIndex}_group_name_idx`);
 }
@@ -4467,11 +5728,29 @@ function taskHistoryInsertFromQueueRow(row, overrides) {
 async function ensureTaskTables(context, options = {}) {
   const queueName = options.queueName ?? "tasks";
   const recreate = options.recreate ?? false;
+  const dryRun = options.dryRun ?? false;
   const db = getDb(context);
+  const log = context.logger ?? console;
   const { tasksTable, historyTable, registryTable } = queueToTableNames(queueName);
   const needsTasks = recreate ? true : !await db.tableExists(tasksTable);
   const needsHistory = recreate ? true : !await db.tableExists(historyTable);
   const needsRegistry = recreate ? true : !await db.tableExists(registryTable);
+  if (dryRun) {
+    const plan = [];
+    if (recreate) {
+      plan.push(`DROP TABLE IF EXISTS ${historyTable}, ${tasksTable}, ${registryTable}`);
+    }
+    if (needsTasks) plan.push(`CREATE TABLE ${tasksTable} (tasks queue)`);
+    if (needsHistory) plan.push(`CREATE TABLE ${historyTable} (history mirror)`);
+    if (needsRegistry) plan.push(`CREATE TABLE ${registryTable} (services registry)`);
+    if (plan.length === 0) {
+      log.info?.(`[tasks-schema] dryRun \u2014 queue "${queueName}" already up to date; no DDL`);
+    } else {
+      log.info?.(`[tasks-schema] dryRun \u2014 would run ${plan.length} statement(s) for queue "${queueName}":`);
+      for (const s of plan) log.info?.(`  - ${s}`);
+    }
+    return;
+  }
   if (recreate) {
     await db.schema.dropTableIfExists(historyTable);
     await db.schema.dropTableIfExists(tasksTable);
@@ -5376,10 +6655,10 @@ var TaskSampleProcess = class extends AbstractTask {
 };
 
 // src/tasks/coreTasks/TaskShellCommand.js
-import { spawn } from "child_process";
+import { spawn as spawn3 } from "child_process";
 function runShellCommand(command, cwd) {
-  return new Promise((resolve2, reject) => {
-    const child = spawn(command, {
+  return new Promise((resolve3, reject) => {
+    const child = spawn3(command, {
       shell: true,
       cwd: cwd || process.cwd(),
       stdio: ["ignore", "pipe", "pipe"]
@@ -5396,7 +6675,7 @@ function runShellCommand(command, cwd) {
       reject(error);
     });
     child.on("close", (exitCode, signal) => {
-      resolve2({
+      resolve3({
         exitCode,
         output: output.trim(),
         stderr: stderr.trim(),
@@ -5868,7 +7147,7 @@ function mergeAllowedTasksWithServiceTasks(names) {
 }
 
 // src/tasks/taskScriptRunner.js
-import { spawn as spawn2 } from "child_process";
+import { spawn as spawn4 } from "child_process";
 var MAX_PROGRESS_TEXT_LEN = 4e3;
 function toCliArgs(args = []) {
   return args.filter((a) => typeof a === "string" && a.length > 0);
@@ -5914,8 +7193,7 @@ function forwardChildLogToParent(context, prefix, message) {
 }
 function buildNodeArgs(scriptPath, cliArgs) {
   const inheritedExecArgs = Array.isArray(process.execArgv) ? [...process.execArgv] : [];
-  const hasTsRuntimeInParent = inheritedExecArgs.some((arg) => /tsx|ts-node/i.test(arg));
-  return hasTsRuntimeInParent ? [...inheritedExecArgs, scriptPath, ...cliArgs] : ["--import", "tsx", scriptPath, ...cliArgs];
+  return [...inheritedExecArgs, scriptPath, ...cliArgs];
 }
 function resolveTasksTableName(context) {
   return context.tasksQueueName || context.params?.get?.("table") || "tasks";
@@ -5947,7 +7225,7 @@ function createSerializedQueue() {
 async function runNodeTaskScript(context, options) {
   const cliArgs = toCliArgs(["--route=ipc", "--mode=json", ...options.args || []]);
   const nodeArgs = buildNodeArgs(options.scriptPath, cliArgs);
-  const child = spawn2(process.execPath, nodeArgs, {
+  const child = spawn4(process.execPath, nodeArgs, {
     cwd: options.cwd || process.cwd(),
     stdio: ["ignore", "pipe", "pipe", "ipc"],
     env: {
@@ -6034,13 +7312,13 @@ async function runNodeTaskScript(context, options) {
     }
     forwardChildLogToParent(context, prefix, message);
   });
-  return await new Promise((resolve2, reject) => {
+  return await new Promise((resolve3, reject) => {
     child.on("error", (error) => reject(error));
     child.on("close", (exitCode, signal) => {
       void (async () => {
         await flushTaskIpcLogs(context);
         await progressQueue.drain();
-        resolve2({
+        resolve3({
           exitCode,
           signal,
           stdout: state.stdout.trim(),
@@ -6155,9 +7433,8 @@ async function executeClaimedTask(context, tasksTable, historyTable, row, regist
     const dbName = String(context?.params?.get?.("dbName") || "local");
     const tableName = String(context?.params?.get?.("table") || "tasks");
     const fallbackRecoverCommand = [
-      "npx",
-      "tsx",
-      "examples/tasks/recover-task.ts",
+      "node",
+      "examples/tasks/recover-task.js",
       `--dbName='${dbName.replace(/'/g, `'\\''`)}'`,
       `--table='${tableName.replace(/'/g, `'\\''`)}'`,
       `--id='${String(row.id).replace(/'/g, `'\\''`)}'`
@@ -6223,6 +7500,8 @@ async function claimNextRunnableTask(context, tasksTable, serviceGroup, registry
   const db = getDb3(context);
   let query = db(tasksTable).where({ status: "idle" }).where(function() {
     this.whereNull("service_group").orWhere({ service_group: serviceGroup });
+  }).where(function() {
+    this.whereNull("next_run_at").orWhere("next_run_at", "<=", db.fn.now());
   }).orderByRaw("CASE WHEN past_due IS NULL THEN 1 ELSE 0 END ASC").orderBy([{ column: "priority", order: "asc" }]).orderByRaw("CASE WHEN completed_at IS NULL THEN 0 ELSE 1 END ASC").orderBy([{ column: "completed_at", order: "asc" }, { column: "created_at", order: "asc" }]).limit(scanLimit);
   if (taskNames && taskNames.length > 0) {
     query = query.whereIn("name", taskNames);
@@ -6605,6 +7884,7 @@ var TasksManager = class _TasksManager {
 export {
   AbstractTask,
   Args,
+  Aws,
   Box4 as Box,
   Db,
   Divider,
@@ -6618,6 +7898,7 @@ export {
   MultiColumnListComponent,
   MultiColumnListWithPreviewComponent,
   Params,
+  REMOTE_CLI_REL,
   React2 as React,
   S3,
   SERVICE_TASK_NAMES,
@@ -6638,51 +7919,94 @@ export {
   TasksRegistry,
   Text5 as Text,
   TextBlock,
+  activateRelease,
+  appendDeployLog,
   appendTaskIpcLog,
+  bootstrapHost,
   buildBreadcrumb,
   buildDetailBreadcrumb,
   buildFooter,
+  bumpPatchVersion,
+  cloneRepo,
   convertPattern,
+  createRelease,
   defaultFileSynopsisFunction,
   defaultTasksRegistry,
   defaultVersionSynopsisFunction,
+  defineService,
+  deployService,
+  deriveRepoDirName,
+  enableNginxUpstream,
   enqueueStopTask,
   enqueueTask,
+  ensureDeployKeyOnRemote,
+  ensureEnvOnRemote,
+  ensureRemoteRepo,
+  ensureRepoDependencies,
   ensureTaskTables,
   flushTaskIpcLogs,
   getArgsInstance,
   createElement2 as h,
+  initServiceStructure,
+  installDeps,
   ipcFileLogsTableNameForSourceResource,
   joiEdateType,
   joiStringArrayType,
   listServicesRegistry as listAliveRunnerHeartbeats,
+  listReleases,
   listServicesRegistry,
   listSources,
   listTables,
   load,
+  loadServices,
   matchesParsedPattern,
   memo,
   mergeAllowedTasksWithServiceTasks,
   nextTimeMatch,
   normalizeAllowedTasks,
+  npmEnv,
+  npmInstallEnv,
   organizeFooterMessages,
+  parseGitHost,
+  prepareGitHost,
+  provisionService,
+  pruneReleases,
+  pullRepo,
   queueToTableNames,
+  readCurrentRelease,
+  readReleaseBuildInfo,
   readTaskIpcLogsSnapshot,
   registerInServicesRegistry,
   registerInServicesRegistry as registerRunnerHeartbeat,
+  releaseDir,
+  releaseStamp,
+  reloadPm2,
   resolveAsterisks,
   resolveIpcFileLogsDir,
+  resolveNextVersion,
   resolveRanges,
+  resolveServiceFrom,
   resolveSteps,
+  rollbackService,
+  run,
   runNodeTaskScript,
+  runReleaseTests,
+  runRemoteCli,
+  runRemoteStatus,
+  runShell,
   runTasksLoop,
+  scrubEnvContent,
+  servicePaths,
   setupContext,
+  shellQuote,
   showListScreen,
   showMenuScreen,
   showMultiColumnListScreen,
   showMultiColumnListWithPreviewScreen,
   showScreen,
   showWordGridScreen,
+  sshRun,
+  syncEnv,
   taskHistoryInsertFromQueueRow,
   timeMatcher,
   touchServicesRegistry as touchRunnerHeartbeat,
@@ -6698,6 +8022,7 @@ export {
   useMemo,
   useRef2 as useRef,
   useState3 as useState,
-  waitForTaskResult
+  waitForTaskResult,
+  writeReleaseBuildInfo
 };
 //# sourceMappingURL=index.js.map