@heronlabs/terminal-cli 0.0.3 → 1.0.0

package/README.md

@@ -1,5 +1,7 @@
 # 🪶 terminal-cli — Heron CLI (`hcli`)
 
+[![npm version](https://img.shields.io/npm/v/@heronlabs/terminal-cli.svg)](https://www.npmjs.com/package/@heronlabs/terminal-cli)
+[![license](https://img.shields.io/npm/l/@heronlabs/terminal-cli.svg)](./LICENSE)
 [![CI](https://github.com/heronlabs/terminal-cli/actions/workflows/ci-cli.yml/badge.svg)](https://github.com/heronlabs/terminal-cli/actions/workflows/ci-cli.yml)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.8.x-blue.svg)](https://www.typescriptlang.org/)
 [![NestJS](https://img.shields.io/badge/NestJS-11.x-e0234e.svg)](https://nestjs.com/)
@@ -14,6 +16,7 @@ AWS S3, and Luxon. Designed to run as a scheduled cron container on EasyPanel.
 ## Table of Contents
 
 - [Why This Project](#why-this-project)
+- [Install](#install)
 - [Quick Start](#quick-start)
 - [Commands](#commands)
 - [Configuration](#configuration)
@@ -32,6 +35,25 @@ Scheduled, type-safe database backups with a single binary:
 - **Cron-ready containers** — purpose-built Dockerfiles run a backup on start and every 12 hours.
 - **100% tested** — v8 coverage + Stryker mutation testing, both at 100% thresholds.
 
+## Install
+
+`hcli` is a global CLI binary. Install it globally to put `hcli` on your `PATH`:
+
+```bash
+npm i -g @heronlabs/terminal-cli
+# or: pnpm add -g @heronlabs/terminal-cli
+```
+
+Then run any command:
+
+```bash
+hcli version
+hcli psql-backup
+```
+
+You also need the database client tools for the engine you back up: `pg_dump` /
+`psql` for PostgreSQL, `mysqldump` / `mysql` for MySQL.
+
 ## Quick Start
 
 ### Prerequisites
@@ -43,7 +65,7 @@ Scheduled, type-safe database backups with a single binary:
 | `pg_dump` / `psql` | — | PostgreSQL backup/restore |
 | `mysqldump` / `mysql` | — | MySQL backup/restore |
 
-### Installation
+### From source (development)
 
 ```bash
 git clone https://github.com/heronlabs/terminal-cli.git
@@ -104,11 +126,7 @@ All configuration comes from environment variables (see [.env.example](./.env.ex
 
 | Variable | Required | Description |
 |---|---|---|
-| `DB_HOST` | ✅ | Database host |
-| `DB_PORT` | ✅ | Database port |
-| `DB_NAME` | ✅ | Database name |
-| `DB_USER` | ✅ | Database user |
-| `DB_PASSWORD` | ✅ | Database password |
+| `DB_URL` | ✅ | Connection URL (`postgres://`/`mysql://user:pass@host:port/dbname`) or an AWS SSM Parameter Store ARN resolved via [`@heronlabs/env-ssm`](https://www.npmjs.com/package/@heronlabs/env-ssm) |
 | `AWS_S3_BUCKET_NAME` | for S3 | Destination bucket for remote backups |
 | `AWS_REGION` | for S3 | AWS region |
 | `AWS_ACCESS_KEY_ID` | for S3 | AWS credentials (or use an instance role) |

package/bin/src/core/interfaces/backup-service.js

@@ -6,7 +6,7 @@ class BackupService {
     logger;
     s3StorageService;
     async run(local, filename) {
-        const result = this.dump(filename);
+        const result = await this.dump(filename);
         if (!result.ok) {
             this.logger.error(result.error.message);
             return;

package/bin/src/core/interfaces/rollup-service.js

@@ -13,7 +13,7 @@ class RollupService {
                 return;
             }
         }
-        const result = this.restore(filename);
+        const result = await this.restore(filename);
         if (!result.ok) {
             this.logger.error(result.error.message);
             return;

package/bin/src/core/services/mysql-backup-service.js

@@ -20,8 +20,8 @@ let MysqlBackupService = class MysqlBackupService extends backup_service_1.Backu
     logger;
     environmentService;
     s3StorageService;
-    dump(filename) {
-        const { host, port, name, user, password } = this.environmentService.database;
+    async dump(filename) {
+        const { host, port, name, user, password } = await this.environmentService.database();
         const timestamp = luxon_1.DateTime.utc().toFormat("yyyy-MM-dd'T'HH-mm-ss'Z'");
         const backupFileName = filename ?? `${name}-${timestamp}.sql.gz`;
         try {

package/bin/src/core/services/mysql-rollup-service.js

@@ -19,8 +19,8 @@ let MysqlRollupService = class MysqlRollupService extends rollup_service_1.Rollu
     logger;
     environmentService;
     s3StorageService;
-    restore(backupFileName) {
-        const { host, port, name, user, password } = this.environmentService.database;
+    async restore(backupFileName) {
+        const { host, port, name, user, password } = await this.environmentService.database();
         try {
             (0, child_process_1.execSync)('set -o pipefail; gunzip -c "$BACKUP_FILE" | mariadb -u "$DB_USER" -h "$DB_HOST" -P "$DB_PORT" "$DB_NAME"', {
                 env: {

package/bin/src/core/services/psql-backup-service.js

@@ -20,8 +20,8 @@ let PsqlBackupService = class PsqlBackupService extends backup_service_1.BackupS
     logger;
     environmentService;
     s3StorageService;
-    dump(filename) {
-        const { host, port, name, user, password } = this.environmentService.database;
+    async dump(filename) {
+        const { host, port, name, user, password } = await this.environmentService.database();
         const timestamp = luxon_1.DateTime.utc().toFormat("yyyy-MM-dd'T'HH-mm-ss'Z'");
         const backupFileName = filename ?? `${name}-${timestamp}.sql.gz`;
         try {

package/bin/src/core/services/psql-rollup-service.js

@@ -19,8 +19,8 @@ let PsqlRollupService = class PsqlRollupService extends rollup_service_1.RollupS
     logger;
     environmentService;
     s3StorageService;
-    restore(backupFileName) {
-        const { host, port, name, user, password } = this.environmentService.database;
+    async restore(backupFileName) {
+        const { host, port, name, user, password } = await this.environmentService.database();
         try {
             (0, child_process_1.execSync)('set -o pipefail; gunzip -c "$BACKUP_FILE" | psql', {
                 env: {

package/bin/src/infrastructure/environment/environment-module.js

@@ -7,13 +7,14 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.EnvironmentModule = exports.environmentModule = void 0;
+const env_ssm_1 = require("@heronlabs/env-ssm");
 const common_1 = require("@nestjs/common");
 const config_1 = require("@nestjs/config");
 const environment_service_1 = require("./services/environment-service");
 exports.environmentModule = {
     providers: [environment_service_1.EnvironmentService],
     exports: [environment_service_1.EnvironmentService],
-    imports: [config_1.ConfigModule],
+    imports: [config_1.ConfigModule, env_ssm_1.SsmConfigModule],
 };
 let EnvironmentModule = class EnvironmentModule {
 };

package/bin/src/infrastructure/environment/services/environment-service.js

@@ -10,30 +10,47 @@ var __metadata = (this && this.__metadata) || function (k, v) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.EnvironmentService = void 0;
+const env_ssm_1 = require("@heronlabs/env-ssm");
 const common_1 = require("@nestjs/common");
 const config_1 = require("@nestjs/config");
 let EnvironmentService = class EnvironmentService {
     configService;
-    get database() {
-        return {
-            host: this.configService.getOrThrow('DB_HOST'),
-            port: this.configService.getOrThrow('DB_PORT'),
-            name: this.configService.getOrThrow('DB_NAME'),
-            user: this.configService.getOrThrow('DB_USER'),
-            password: this.configService.getOrThrow('DB_PASSWORD'),
+    ssmConfigService;
+    async database() {
+        const databaseUrl = await this.ssmConfigService.getOrThrow('DB_URL');
+        let url;
+        try {
+            url = new URL(databaseUrl);
+        }
+        catch {
+            throw new Error('Invalid DB_URL');
+        }
+        const connection = {
+            host: url.hostname,
+            port: url.port,
+            name: url.pathname.slice(1),
+            user: decodeURIComponent(url.username),
+            password: decodeURIComponent(url.password),
         };
+        const missing = ['host', 'name', 'user'].filter(field => connection[field] === '');
+        if (missing.length > 0) {
+            throw new Error(`Invalid DB_URL: missing ${missing.join(', ')}`);
+        }
+        return connection;
     }
     get storage() {
         return {
             bucketName: this.configService.getOrThrow('AWS_S3_BUCKET_NAME'),
         };
     }
-    constructor(configService) {
+    constructor(configService, ssmConfigService) {
         this.configService = configService;
+        this.ssmConfigService = ssmConfigService;
     }
 };
 exports.EnvironmentService = EnvironmentService;
 exports.EnvironmentService = EnvironmentService = __decorate([
     (0, common_1.Injectable)(),
-    __metadata("design:paramtypes", [config_1.ConfigService])
+    __metadata("design:paramtypes", [config_1.ConfigService,
+        env_ssm_1.SsmConfigService])
 ], EnvironmentService);

package/package.json

@@ -8,6 +8,7 @@
   },
   "dependencies": {
     "@aws-sdk/client-s3": "^3.1045.0",
+    "@heronlabs/env-ssm": "^1.0.0",
     "@nestjs/common": "^11.1.18",
     "@nestjs/config": "^4.0.4",
     "@nestjs/core": "^11.1.18",
@@ -71,6 +72,7 @@
       "@swc/core"
     ],
     "overrides": {
+      "qs@<6.15.2": ">=6.15.2",
       "tmp@<0.2.6": ">=0.2.6"
     }
   },
@@ -92,5 +94,5 @@
     "test:mutation": "stryker run stryker.conf.json",
     "test:unit": "vitest run"
   },
-  "version": "0.0.3"
+  "version": "1.0.0"
 }