@nmakarov/cli-toolkit 0.29.0 → 0.33.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nmakarov/cli-toolkit",
-  "version": "0.29.0",
+  "version": "0.33.0",
   "description": "A comprehensive toolkit for building CLI applications",
   "type": "module",
   "main": "./dist/index.js",
@@ -58,6 +58,14 @@
       "import": "./dist/s3.js",
       "require": "./dist/s3.cjs"
     },
+    "./aws": {
+      "import": "./dist/aws.js",
+      "require": "./dist/aws.cjs"
+    },
+    "./deploy": {
+      "import": "./dist/deploy.js",
+      "require": "./dist/deploy.cjs"
+    },
     "./tasks": {
       "import": "./dist/tasks.js",
       "require": "./dist/tasks.cjs"
@@ -68,7 +76,9 @@
     }
   },
   "bin": {
-    "cli-runner": "./dist/cli-runner.js"
+    "cli-runner": "./dist/cli-runner.js",
+    "cli-deploy": "./scripts/deploy/cli.js",
+    "cli-aws-discover": "./scripts/aws/discover.js"
   },
   "scripts": {
     "ssm:list": "node scripts/ssm/ssm-admin.js list",
@@ -146,6 +156,8 @@
   "files": [
     "dist/",
     "scripts/ssm/",
+    "scripts/deploy/",
+    "scripts/aws/",
     "README.md",
     "LICENSE"
   ],
@@ -159,8 +171,11 @@
     "vitest": "^4.0.3"
   },
   "dependencies": {
+    "@aws-sdk/client-ec2": "^3.1075.0",
+    "@aws-sdk/client-route-53": "^3.1075.0",
     "@aws-sdk/client-s3": "^3.750.0",
     "@aws-sdk/client-ssm": "^3.750.0",
+    "@aws-sdk/client-sts": "^3.1075.0",
     "axios": "^1.6.0",
     "chalk": "^4.1.2",
     "dotenv": "^17.2.3",

package/scripts/aws/discover.js

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+/**
+ * cli-aws-discover — read-only peek at the AWS account behind your credentials.
+ *
+ * Once @nmakarov/cli-toolkit is installed, run it without copying anything:
+ *
+ *   npx cli-aws-discover
+ *   npx cli-aws-discover --awsRegion=ca-central-1
+ *
+ * Credentials/region resolve from AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY /
+ * AWS_REGION (env or .env), an AWS_PROFILE, or an instance role. If none are
+ * found — or AWS rejects them — it prints exactly how to get a key, no stack trace.
+ *
+ * Handy for finding the Route53 zone id / VPC / AMI you need for terraform.tfvars.
+ */
+
+import { init } from "../../dist/init.js";
+import { Aws } from "../../dist/aws.js";
+
+const flow = async (context) => {
+    const { logger } = context;
+    logger.info("cli-aws-discover — read-only peek at your AWS account");
+
+    const aws = await Aws.init(context);
+
+    const cred = await aws.checkCredentials();
+    if (!cred.ok) {
+        logger.error(Aws.credentialsHelp(aws.getRegion()));
+        process.exitCode = 1;
+        return;
+    }
+    logger.info(`credentials: ${cred.source}`);
+
+    try {
+        const me = await aws.whoAmI();
+        logger.info(`account  ${me.account}   region ${aws.getRegion()}`);
+        logger.info(`identity ${me.arn}`);
+
+        const zones = await aws.listHostedZones();
+        logger.info(`\nRoute53 hosted zones (${zones.length}):`);
+        for (const z of zones) logger.info(`  ${z.name.padEnd(30)} ${z.id}${z.private ? " [private]" : ""}`);
+
+        const vpcs = await aws.listVpcs();
+        logger.info(`\nVPCs (${vpcs.length}):`);
+        for (const v of vpcs) logger.info(`  ${v.id}  ${v.cidr}${v.isDefault ? "  default" : ""}  ${v.name ?? ""}`);
+
+        const ami = await aws.findLatestUbuntuAmi();
+        logger.info(`\nLatest Ubuntu AMI: ${ami ? `${ami.id}  ${ami.name}` : "(none)"}`);
+    } catch (err) {
+        if (Aws.isAuthError(err)) {
+            logger.error(`AWS rejected the credentials it found (${err.name}).\n`);
+            logger.error(Aws.credentialsHelp(aws.getRegion()));
+            process.exitCode = 1;
+            return;
+        }
+        throw err;
+    }
+};
+
+init(flow);

package/scripts/deploy/cli.js

@@ -0,0 +1,181 @@
+#!/usr/bin/env node
+/**
+ * cli-deploy — manifest-driven release deploys to EC2 (local or over SSH).
+ *
+ * Projects describe each app in a manifests module (default ./deploy/services.js)
+ * that exports `services` (a map/array of service manifests). Then:
+ *
+ *   # from your laptop, over SSH (uses ~/.ssh/config Host alias):
+ *   cli-deploy setup    --service=web --host=web-prod
+ *   cli-deploy deploy   --service=web --host=web-prod
+ *   cli-deploy rollback --service=web --host=web-prod
+ *   cli-deploy status   --service=web --host=web-prod
+ *
+ *   # directly on the host (no --host):
+ *   cli-deploy deploy   --service=web
+ *
+ * Commands: setup | bootstrap | init | provision | deploy | rollback | status
+ *
+ * Common flags (cli-toolkit params; CLI/env/.env):
+ *   --service     (required) service name from the manifests module
+ *   --manifests   path to manifests module (default deploy/services.js)
+ *   --host        ssh Host alias → run remotely (omit to run locally)
+ *   --appsRoot    override the manifest appsRoot (handy for /tmp dry runs)
+ *   --dryRun --skipPull --skipTests --skipNginx
+ *   --withBootstrap --noDeploy        (provision)
+ *   --release=<stamp>                  (rollback to a specific release)
+ *   --deployKey=~/.ssh/key             (git deploy key, ssh repos)
+ *   --envFile=path/to/.env             (laptop .env to scp; default ./.env)
+ */
+
+import { init } from "../../dist/init.js";
+import {
+    loadServices,
+    resolveServiceFrom,
+    bootstrapHost,
+    initServiceStructure,
+    provisionService,
+    deployService,
+    rollbackService,
+    ensureRemoteRepo,
+    runRemoteCli,
+    runRemoteStatus,
+    servicePaths,
+    listReleases,
+    readCurrentRelease,
+} from "../../dist/deploy.js";
+
+const COMMANDS = ["setup", "bootstrap", "init", "provision", "deploy", "rollback", "status"];
+
+function remotePassthrough(flags) {
+    const out = [];
+    const bools = ["dryRun", "skipPull", "skipTests", "skipNginx", "noDeploy", "withBootstrap"];
+    for (const k of bools) if (flags[k]) out.push(`--${k}`);
+    if (flags.release) out.push(`--release=${flags.release}`);
+    if (flags.deployKey) out.push(`--deployKey=${flags.deployKey}`);
+    return out;
+}
+
+async function localStatus(service, logger) {
+    const paths = servicePaths(service);
+    const current = await readCurrentRelease(paths);
+    const releases = await listReleases(paths);
+    logger.info(`service   ${service.name}`);
+    logger.info(`appsRoot  ${paths.root}`);
+    logger.info(`current   ${current ?? "(not set)"}`);
+    logger.info(`releases  ${releases.length ? releases.map((r) => r.name).join(", ") : "(none)"}`);
+}
+
+const flow = async (context) => {
+    const { logger, params } = context;
+    const command = (context.args.getCommands?.() ?? [])[0];
+    const serviceName = params.get("service", "string optional");
+    const host = params.get("host", "string optional");
+    const manifests = params.get("manifests", "string default deploy/services.js");
+
+    const flags = params.getAll({
+        dryRun: "boolean default false",
+        skipPull: "boolean default false",
+        skipTests: "boolean default false",
+        skipNginx: "boolean default false",
+        withBootstrap: "boolean default false",
+        noDeploy: "boolean default false",
+        appsRoot: "string optional",
+        release: "string optional",
+        deployKey: "string optional",
+        envFile: "string optional",
+    });
+
+    if (!command || !serviceName || !COMMANDS.includes(command)) {
+        logger.error("Usage: cli-deploy <command> --service=<name> [--host=<ssh>] [flags]");
+        logger.error(`Commands: ${COMMANDS.join(", ")}`);
+        logger.error("Example: cli-deploy deploy --service=web --host=web-prod");
+        process.exitCode = 2;
+        return;
+    }
+
+    let serviceMap;
+    try {
+        serviceMap = await loadServices({ manifests });
+    } catch (err) {
+        logger.error(err.message);
+        process.exitCode = 2;
+        return;
+    }
+
+    let service;
+    try {
+        service = resolveServiceFrom(serviceMap, serviceName, { appsRoot: flags.appsRoot });
+    } catch (err) {
+        logger.error(err.message);
+        process.exitCode = 2;
+        return;
+    }
+    if (flags.deployKey) service = { ...service, deployKey: flags.deployKey };
+
+    // ── Remote: orchestrate over SSH, re-invoking this CLI on the host ──────────
+    if (host) {
+        const extra = remotePassthrough(flags);
+        const opts = { logger, manifests, deployKey: service.deployKey, envFile: flags.envFile };
+        logger.info(`remote ${command} service=${service.name} host=${host}`);
+
+        switch (command) {
+            case "setup":
+                await ensureRemoteRepo(host, service, opts);
+                await runRemoteCli(host, service, "bootstrap", extra, { ...opts, skipPull: true });
+                await runRemoteCli(host, service, "init", extra, { ...opts, skipPull: true });
+                await runRemoteCli(host, service, "provision", extra, { ...opts, skipPull: true });
+                break;
+            case "status":
+                await runRemoteStatus(host, service, { logger });
+                break;
+            default:
+                await runRemoteCli(host, service, command, extra, opts);
+        }
+        return;
+    }
+
+    // ── Local: run the step(s) on this machine (the host, or a dry run) ─────────
+    logger.info(`local ${command} service=${service.name}`);
+    switch (command) {
+        case "bootstrap":
+            await bootstrapHost(service, { deployKey: service.deployKey, dryRun: flags.dryRun, logger });
+            break;
+        case "init":
+            await initServiceStructure(service, { dryRun: flags.dryRun, logger });
+            break;
+        case "provision":
+            await provisionService(service, {
+                dryRun: flags.dryRun,
+                deploy: !flags.noDeploy,
+                skipBootstrap: !flags.withBootstrap,
+                deployKey: flags.withBootstrap ? service.deployKey : undefined,
+                logger,
+            });
+            break;
+        case "deploy":
+            await deployService(service, {
+                dryRun: flags.dryRun,
+                skipPull: flags.skipPull,
+                skipTests: flags.skipTests,
+                skipNginx: flags.skipNginx,
+                logger,
+            });
+            break;
+        case "rollback":
+            await rollbackService(service, { release: flags.release, dryRun: flags.dryRun, logger });
+            break;
+        case "setup":
+            await bootstrapHost(service, { deployKey: service.deployKey, dryRun: flags.dryRun, logger });
+            await initServiceStructure(service, { dryRun: flags.dryRun, logger });
+            await provisionService(service, { dryRun: flags.dryRun, deploy: !flags.noDeploy, skipBootstrap: true, logger });
+            break;
+        case "status":
+            await localStatus(service, logger);
+            break;
+        default:
+            break;
+    }
+};
+
+init(flow);