@nmakarov/cli-toolkit 0.18.0 → 0.23.0

package/scripts/ssm/ssm-admin.js

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+/**
+ * Local admin CLI for SSM Parameter Store (uses your workstation AWS credentials / profile).
+ *
+ * Prerequisites: IAM permission for ssm:Get*, ssm:PutParameter, ssm:DeleteParameter on your parameters
+ * (and kms:Decrypt/Encrypt if you use SecureString).
+ *
+ * Run from this package root (`subprojects/cli-toolkit`):
+ *
+ *   npx tsx scripts/ssm/ssm-admin.js list --prefix /mlsfarm/tf3/
+ *   npm run ssm:list -- --prefix /mlsfarm/tf3/
+ *
+ * Or from a project that depends on `@nmakarov/cli-toolkit` (after a release that ships `scripts/ssm/`):
+ *
+ *   npx tsx node_modules/@nmakarov/cli-toolkit/scripts/ssm/ssm-admin.js list --prefix /mlsfarm/tf3/
+ *
+ * Optional: AWS_REGION, AWS_PROFILE (standard SDK env).
+ */
+
+import {
+    SSMClient,
+    GetParametersByPathCommand,
+    GetParameterCommand,
+    PutParameterCommand,
+    DeleteParameterCommand,
+} from "@aws-sdk/client-ssm";
+import { parseCli, getRegion } from "./parse-cli.js";
+
+function usage() {
+    console.error(`Usage:
+  npx tsx scripts/ssm/ssm-admin.js list   --prefix /path/ [--recursive false]
+  npx tsx scripts/ssm/ssm-admin.js get    --name /path/KEY
+  npx tsx scripts/ssm/ssm-admin.js put    --name /path/KEY --value "..." [--type String|SecureString] [--overwrite]
+  npx tsx scripts/ssm/ssm-admin.js delete --name /path/KEY`);
+}
+
+function ensureLeadingSlash(path) {
+    const p = path.trim();
+    if (!p.startsWith("/")) return `/${p}`;
+    return p;
+}
+
+async function main() {
+    const { _, flags } = parseCli(process.argv.slice(2));
+    const cmd = (_[0] || "").toLowerCase();
+    if (!cmd || cmd === "help" || cmd === "-h" || cmd === "--help") {
+        usage();
+        process.exit(cmd ? 0 : 1);
+    }
+
+    const region = typeof flags.region === "string" ? flags.region : getRegion();
+    const client = new SSMClient({ region });
+
+    if (cmd === "list") {
+        const prefix = ensureLeadingSlash(String(flags.prefix || "/mlsfarm/tf3/"));
+        const recursive = flags.recursive === false || flags.recursive === "false" ? false : true;
+        let next;
+        const rows = [];
+        do {
+            const out = await client.send(
+                new GetParametersByPathCommand({
+                    Path: prefix,
+                    Recursive: recursive,
+                    WithDecryption: true,
+                    NextToken: next,
+                })
+            );
+            for (const p of out.Parameters || []) {
+                rows.push({ name: p.Name, type: p.Type, version: p.Version });
+            }
+            next = out.NextToken;
+        } while (next);
+
+        if (rows.length === 0) {
+            console.log(`(no parameters under ${prefix})`);
+            return;
+        }
+        const w = Math.max(...rows.map((r) => (r.name || "").length), 4);
+        console.log(`${"NAME".padEnd(w)}  TYPE            VER`);
+        for (const r of rows) {
+            console.log(`${(r.name || "").padEnd(w)}  ${(r.type || "").padEnd(14)} ${r.version ?? ""}`);
+        }
+        return;
+    }
+
+    if (cmd === "get") {
+        const name = flags.name;
+        if (typeof name !== "string" || !name.trim()) {
+            console.error("get: --name is required");
+            usage();
+            process.exit(1);
+        }
+        const out = await client.send(
+            new GetParameterCommand({ Name: ensureLeadingSlash(name), WithDecryption: true })
+        );
+        const p = out.Parameter;
+        if (!p?.Name) {
+            console.error("Parameter not found");
+            process.exit(1);
+        }
+        console.log(`Name:  ${p.Name}`);
+        console.log(`Type:  ${p.Type}`);
+        console.log(`Value: ${p.Value ?? ""}`);
+        return;
+    }
+
+    if (cmd === "put") {
+        const name = flags.name;
+        const value = flags.value;
+        if (typeof name !== "string" || !name.trim()) {
+            console.error("put: --name is required");
+            process.exit(1);
+        }
+        if (typeof value !== "string") {
+            console.error("put: --value is required (string)");
+            process.exit(1);
+        }
+        const type = flags.type === "SecureString" ? "SecureString" : "String";
+        const overwrite = flags.overwrite === true || flags.overwrite === "true";
+        const ver = await client.send(
+            new PutParameterCommand({
+                Name: ensureLeadingSlash(name),
+                Value: value,
+                Type: type,
+                Overwrite: overwrite,
+            })
+        );
+        console.log(`OK Version ${ver.Version}`);
+        return;
+    }
+
+    if (cmd === "delete") {
+        const name = flags.name;
+        if (typeof name !== "string" || !name.trim()) {
+            console.error("delete: --name is required");
+            process.exit(1);
+        }
+        await client.send(new DeleteParameterCommand({ Name: ensureLeadingSlash(name) }));
+        console.log("OK deleted");
+        return;
+    }
+
+    console.error(`Unknown command: ${cmd}`);
+    usage();
+    process.exit(1);
+}
+
+main().catch((e) => {
+    console.error(e instanceof Error ? e.message : e);
+    process.exit(1);
+});

package/scripts/ssm/ssm-pull.js

@@ -0,0 +1,147 @@
+#!/usr/bin/env node
+/**
+ * Pull all SSM parameters under a path (recursive) for use on servers or locally.
+ * Uses default credential chain (on EC2: instance profile; e.g. mlsfarm tf3 `04.4.ssm_iam.tf`).
+ *
+ * Output modes:
+ *   print   — table to stdout (default)
+ *   dotenv  — KEY=value lines (dotenv-friendly; optional --file)
+ *   shell   — export KEY='...' lines for: eval "$(npx tsx ... --output shell)"
+ *
+ * Env key = last path segment of the parameter name (e.g. /mlsfarm/tf3/DATABASE_URL → DATABASE_URL).
+ *
+ * From package root:
+ *
+ *   npx tsx scripts/ssm/ssm-pull.js --path /mlsfarm/tf3/
+ *   npm run ssm:pull -- --path /mlsfarm/tf3/ --output dotenv --file .env.from-ssm
+ *   eval "$(npx tsx scripts/ssm/ssm-pull.js --path /mlsfarm/tf3/ --output shell)"
+ */
+
+import { SSMClient, GetParametersByPathCommand } from "@aws-sdk/client-ssm";
+import { writeFileSync } from "fs";
+import { parseCli, getRegion } from "./parse-cli.js";
+
+function ensureLeadingSlash(path) {
+    const p = path.trim();
+    if (!p.startsWith("/")) return `/${p}`;
+    return p.endsWith("/") ? p : `${p}/`;
+}
+
+function leafKey(paramName) {
+    const trimmed = paramName.replace(/^\/+|\/+$/g, "");
+    const parts = trimmed.split("/");
+    const leaf = parts[parts.length - 1] || trimmed;
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(leaf)) {
+        return leaf.replace(/[^A-Za-z0-9_]+/g, "_").replace(/^(\d)/, "_$1");
+    }
+    return leaf;
+}
+
+function escapeDotenvValue(value) {
+    if (/[\s#'"]/u.test(value) || value.includes("\n")) {
+        const escaped = value.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n");
+        return `"${escaped}"`;
+    }
+    return value;
+}
+
+function escapeShellSingleQuoted(value) {
+    return `'${value.replace(/'/g, `'\"'\"'`)}'`;
+}
+
+async function fetchAll(client, path) {
+    const outList = [];
+    let next;
+    do {
+        const out = await client.send(
+            new GetParametersByPathCommand({
+                Path: path,
+                Recursive: true,
+                WithDecryption: true,
+                NextToken: next,
+            })
+        );
+        for (const p of out.Parameters || []) {
+            if (p.Name && p.Value !== undefined) {
+                outList.push({ name: p.Name, value: p.Value, type: p.Type });
+            }
+        }
+        next = out.NextToken;
+    } while (next);
+    outList.sort((a, b) => a.name.localeCompare(b.name));
+    return outList;
+}
+
+async function main() {
+    const { flags } = parseCli(process.argv.slice(2));
+    const pathRaw = flags.path;
+    if (typeof pathRaw !== "string" || !pathRaw.trim()) {
+        console.error("Required: --path /your/prefix/");
+        process.exit(1);
+    }
+    const path = ensureLeadingSlash(pathRaw);
+    const output = String(flags.output || "print").toLowerCase();
+    const file = typeof flags.file === "string" ? flags.file : undefined;
+
+    const region = typeof flags.region === "string" ? flags.region : getRegion();
+    const client = new SSMClient({ region });
+
+    const params = await fetchAll(client, path);
+    if (params.length === 0) {
+        const msg = `(no parameters under ${path})`;
+        if (file) writeFileSync(file, "", "utf8");
+        else console.log(msg);
+        return;
+    }
+
+    if (output === "print") {
+        const lines = [
+            `region=${region} path=${path} count=${params.length}`,
+            "",
+            ...params.map((p) => {
+                const k = leafKey(p.name);
+                const preview =
+                    p.value.length > 120 ? `${p.value.slice(0, 117)}...` : p.value;
+                return `${p.name}  [${k}]  (${p.type})  ${preview}`;
+            }),
+        ];
+        const text = lines.join("\n");
+        if (file) writeFileSync(file, text + "\n", "utf8");
+        else console.log(text);
+        return;
+    }
+
+    if (output === "dotenv") {
+        const body = params
+            .map((p) => {
+                const k = leafKey(p.name);
+                return `${k}=${escapeDotenvValue(p.value)}`;
+            })
+            .join("\n");
+        const text = `${body}\n`;
+        if (file) writeFileSync(file, text, "utf8");
+        else process.stdout.write(text);
+        return;
+    }
+
+    if (output === "shell") {
+        const body = params
+            .map((p) => {
+                const k = leafKey(p.name);
+                return `export ${k}=${escapeShellSingleQuoted(p.value)}`;
+            })
+            .join("\n");
+        const text = `${body}\n`;
+        if (file) writeFileSync(file, text, "utf8");
+        else process.stdout.write(text);
+        return;
+    }
+
+    console.error(`Unknown --output ${output}. Use: print | dotenv | shell`);
+    process.exit(1);
+}
+
+main().catch((e) => {
+    console.error(e instanceof Error ? e.message : e);
+    process.exit(1);
+});