@saws/cli 2.0.0-beta.2 → 2.0.0-beta.21

package/dist/commands/host/index.js

@@ -1,10 +1,32 @@
 import { Command } from "commander";
 import { configureHostCommand } from "./command.js";
+import { createHostCommand } from "./create.js";
+import { importHostKeyCommand } from "./import-key.js";
 export const createCommand = () => new Command("host")
     .description("configure deployment hosts")
+    .addCommand(new Command("create")
+    .description("create a global deployment host")
+    .argument("<name>", "global host name")
+    .requiredOption("--address <address>", "host name or IP address")
+    .requiredOption("--user <deployment-user>", "persistent deployment account")
+    .option("--ssh-port <port>", "SSH port")
+    .option("--platform <platform>", 'Docker platform such as "linux/amd64"')
+    .option("--exposure <mode>", 'network exposure policy: "tunnel" or "public"')
+    .option("--allowed-tcp-port <port...>", "public TCP ports allowed by the host firewall")
+    .action(createHostCommand))
+    .addCommand(new Command("key")
+    .description("manage global host deployment keys")
+    .addCommand(new Command("import")
+    .description("import an existing private key into encrypted global storage")
+    .argument("<name>", "global host name")
+    .requiredOption("--file <path>", "path to an SSH private key")
+    .option("--force", "replace an existing deployment key")
+    .action(importHostKeyCommand)))
     .addCommand(new Command("configure")
-    .description("install Docker and apply the configured security policy")
+    .description("bootstrap a deployment user and apply host security policy")
     .argument("[name]", "host name; optional when exactly one host exists")
-    .option("--config <string>", "path to service definition")
-    .option("--dry-run", "print the remote configuration command")
+    .requiredOption("--user <bootstrap-user>", "existing SSH account used for initial configuration")
+    .option("--config <path>", "path to saws.ts")
+    .option("--global", "configure a host from the global host registry")
+    .option("--dry-run", "describe configuration without making changes")
     .action(configureHostCommand));

package/dist/commands/init/command.d.ts

@@ -1,7 +1 @@
-export interface InitCommandOptions {
-    rootDir?: string;
-    config?: string;
-    dryRun?: boolean;
-}
-export declare function initCommand(serviceName: string, path: string | undefined, options: InitCommandOptions): Promise<void>;
-//# sourceMappingURL=command.d.ts.map
+export declare const initCommand: (serviceName?: string, configPath?: string) => Promise<void>;

package/dist/commands/init/command.js

@@ -1,15 +1,24 @@
-import { findServiceDefinition, getSawsConfig, InitContext, } from "@saws/core";
-export async function initCommand(serviceName, path, options) {
-    const rootDir = options.rootDir ?? process.cwd();
-    const rootService = await getSawsConfig(options.config ?? path);
-    const service = findServiceDefinition(rootService, serviceName);
-    await service.init(new InitContext({
-        stage: "local",
-        rootDir,
-        dryRun: options.dryRun ?? false,
-        env: process.env,
-        logSink: ({ stream, chunk }) => {
-            (stream === "stderr" ? process.stderr : process.stdout).write(chunk);
-        },
-    }));
-}
+import path from "node:path";
+import fs from "node:fs/promises";
+import { findServiceDefinition, getSawsConfig } from "@saws/core";
+import { installDependencies } from "@saws/core/utils/dependency-management";
+import { createFileIfNotExists } from "@saws/core/utils/create-file-if-not-exists";
+import { sawsTsTemplate } from "./templates/saws-ts.template.js";
+import { tsconfigJsonTemplate } from "./templates/tsconfig-json.template.js";
+import { gitignoreTemplate } from "./templates/gitignore.template.js";
+export const initCommand = async (serviceName, configPath) => {
+    if (serviceName != null) {
+        const serviceDefinition = await getSawsConfig(configPath);
+        await findServiceDefinition(serviceDefinition, serviceName).init();
+        return;
+    }
+    const name = path.parse(path.resolve(".")).name;
+    // not used for now
+    await installDependencies([]);
+    await installDependencies(["@saws/core", "typescript", "@tsconfig/node26"], {
+        development: true,
+    });
+    await fs.writeFile("./tsconfig.json", tsconfigJsonTemplate(), {});
+    await createFileIfNotExists("./saws.ts", sawsTsTemplate({ name }));
+    await createFileIfNotExists("./.gitignore", gitignoreTemplate());
+};

package/dist/commands/init/index.d.ts

@@ -1,3 +1,2 @@
 import { Command } from "commander";
 export declare const createCommand: () => Command;
-//# sourceMappingURL=index.d.ts.map

package/dist/commands/init/index.js

@@ -1,10 +1,6 @@
 import { Command } from "commander";
 import { initCommand } from "./command.js";
 export const createCommand = () => new Command("init")
-    .description("bootstrap one configured service and its dependencies")
-    .argument("<service>", "name of the service to initialize")
+    .argument("[service]", "name of the service to initialize")
     .argument("[config]", "path to service definition")
-    .option("--root-dir <string>", "project root used for generated files")
-    .option("--config <string>", "path to service definition")
-    .option("--dry-run", "allow service initializers to preview their changes")
     .action(initCommand);

package/dist/commands/init/templates/gitignore.template.d.ts

@@ -0,0 +1 @@
+export declare const gitignoreTemplate: () => string;

package/dist/commands/init/templates/gitignore.template.js

@@ -0,0 +1,4 @@
+export const gitignoreTemplate = () => `node_modules
+.saws/saws-*-local-output.json
+.saws/.secrets
+.DS_Store`;

package/dist/commands/init/templates/saws-ts.template.d.ts

@@ -0,0 +1,3 @@
+export declare const sawsTsTemplate: ({ name }: {
+    name: string;
+}) => string;

package/dist/commands/init/templates/saws-ts.template.js

@@ -0,0 +1,7 @@
+export const sawsTsTemplate = ({ name }) => `import { ServiceDefinition } from "@saws/core";
+
+export default new ServiceDefinition({
+  name: "${name}",
+  dependencies: [],
+});
+`;

package/dist/commands/init/templates/tsconfig-json.template.d.ts

@@ -0,0 +1 @@
+export declare const tsconfigJsonTemplate: () => string;

package/dist/commands/init/templates/tsconfig-json.template.js

@@ -0,0 +1,4 @@
+export const tsconfigJsonTemplate = () => /* json */ `{
+  "extends": "@tsconfig/node26/tsconfig.json",
+  "files": []
+}`;

package/dist/commands/logs/command.d.ts

@@ -0,0 +1,5 @@
+export interface LogsCommandOptions {
+    config?: string;
+    stage: string;
+}
+export declare const logsCommand: (serviceName: string | undefined, options: LogsCommandOptions) => Promise<void>;

package/dist/commands/logs/command.js

@@ -0,0 +1,19 @@
+import { findServiceDefinition, getSawsConfig } from "@saws/core";
+export const logsCommand = async (serviceName, options) => {
+    const { config, stage } = options;
+    if (stage == null || stage.length === 0) {
+        throw new Error("logs requires --stage <string>");
+    }
+    if (stage === "local")
+        return;
+    process.env.STAGE = stage;
+    const serviceDefinition = await getSawsConfig(config);
+    if (serviceName != null) {
+        await findServiceDefinition(serviceDefinition, serviceName).logs(stage);
+        return;
+    }
+    await Promise.all(collectServices(serviceDefinition).map((service) => service.logs(stage)));
+};
+function collectServices(root) {
+    return [...new Set(root.getAllDependencies())];
+}

package/dist/commands/logs/index.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare const createCommand: () => Command;

package/dist/commands/logs/index.js

@@ -0,0 +1,7 @@
+import { Command } from "commander";
+import { logsCommand } from "./command.js";
+export const createCommand = () => new Command("logs")
+    .option("--stage <string>", "stage to tail logs from")
+    .option("--config <path>", "path to service definition")
+    .argument("[service]", "name of the service to tail logs from")
+    .action(logsCommand);

package/dist/commands/secrets/command.d.ts

@@ -1,8 +1,8 @@
 export interface SecretsCommandOptions {
+    config?: string;
     stage?: string;
+    global?: boolean;
     set?: string;
     get?: boolean;
-    rootDir?: string;
 }
 export declare function secretsCommand(name: string, options: SecretsCommandOptions): Promise<void>;
-//# sourceMappingURL=command.d.ts.map

package/dist/commands/secrets/command.js

@@ -1,16 +1,38 @@
-import { SecretsManager } from "@saws/secrets";
+import { getSawsConfigModule, SecretsManager } from "@saws/core";
 export async function secretsCommand(name, options) {
-    const manager = new SecretsManager({
-        stage: options.stage ?? "local",
-        rootDir: options.rootDir ?? process.cwd(),
-    });
+    const value = options.set;
+    if (options.get && value != null) {
+        throw new Error("secrets accepts only one of --get or --set <value>");
+    }
+    if (!options.get && value == null) {
+        throw new Error("secrets requires either --get or --set <value>");
+    }
+    if (!options.global) {
+        process.env.STAGE = options.stage ?? "local";
+    }
+    const config = await getSawsConfigModule(options.config);
+    const manager = Object.values(config).find((candidate) => candidate instanceof SecretsManager) ?? config.secrets;
+    if (!isSecretsManagerLike(manager)) {
+        throw new Error('saws.ts must export a SecretsManager instance named "secrets"');
+    }
+    const secrets = options.global ? manager.global : manager;
     if (options.get) {
-        console.log(await manager.get(name));
+        console.log(await secrets.get(name));
         return;
     }
-    if (options.set == null) {
-        throw new Error("secrets requires either --get or --set <value>");
+    if (value == null) {
+        throw new Error("secrets requires --set <value>");
     }
-    await manager.set(name, options.set);
+    await secrets.set(name, value);
     console.log("Set secret");
 }
+function isSecretsManagerLike(value) {
+    if (value == null || typeof value !== "object")
+        return false;
+    const candidate = value;
+    return (typeof candidate.get === "function" &&
+        typeof candidate.set === "function" &&
+        candidate.global != null &&
+        typeof candidate.global.get === "function" &&
+        typeof candidate.global.set === "function");
+}

package/dist/commands/secrets/index.d.ts

@@ -1,3 +1,2 @@
 import { Command } from "commander";
 export declare const createCommand: () => Command;
-//# sourceMappingURL=index.d.ts.map

package/dist/commands/secrets/index.js

@@ -1,9 +1,11 @@
 import { Command } from "commander";
 import { secretsCommand } from "./command.js";
 export const createCommand = () => new Command("secrets")
-    .argument("<string>", "secret name")
-    .option("--stage <string>", "stage", "local")
-    .option("--set <string>", "set secret value")
-    .option("--get", "get secret value")
-    .option("--root-dir <string>", "project root used for local secrets")
+    .description("get or set encrypted project secrets")
+    .argument("<name>", "secret name")
+    .option("--stage <string>", "stage for a stage-scoped secret", "local")
+    .option("--global", "use the global secret scope")
+    .option("--set <string>", "set the secret value")
+    .option("--get", "get the secret value")
+    .option("--config <string>", "path to service definition")
     .action(secretsCommand);

package/dist/hosts.d.ts

@@ -1,4 +1,2 @@
-import { Host } from "@saws/host";
-import type { ServiceDefinition } from "@saws/core";
+import { Host, type ServiceDefinition } from "@saws/core";
 export declare function findConfiguredHosts(root: ServiceDefinition): Host[];
-//# sourceMappingURL=hosts.d.ts.map

package/dist/hosts.js

@@ -1,16 +1,17 @@
-import { Host } from "@saws/host";
+import { Host } from "@saws/core";
 export function findConfiguredHosts(root) {
     const hosts = new Set();
-    const visited = new Set();
-    const visit = (service) => {
-        if (visited.has(service))
+    const visited = new WeakSet();
+    const visit = (value) => {
+        if (value == null || typeof value !== "object" || visited.has(value))
             return;
-        visited.add(service);
-        const host = service.docker?.host;
-        if (host instanceof Host)
-            hosts.add(host);
-        for (const dependency of service.dependencies)
-            visit(dependency);
+        visited.add(value);
+        if (value instanceof Host) {
+            hosts.add(value);
+            return;
+        }
+        for (const child of Object.values(value))
+            visit(child);
     };
     visit(root);
     return [...hosts];

package/docs/global-hosts-and-applications.md

@@ -0,0 +1,307 @@
+# Global hosts and packaged applications
+
+This guide covers the complete remote-deployment workflow:
+
+1. Save a machine as a reusable global host.
+2. Bootstrap that machine for SAWS deployments.
+3. Reference the host from an application input file.
+4. Install and deploy a packaged application.
+
+## Prerequisites
+
+You need the SAWS CLI, a Debian or Ubuntu server, and an existing SSH account that can run commands
+as `root` or with interactive `sudo`.
+
+```sh
+npm install --save-dev @saws/cli
+```
+
+By default, global hosts and installed applications live under `~/.saws`. Set `SAWS_HOME` before
+running any host or application command if that state should live elsewhere:
+
+```sh
+export SAWS_HOME=/srv/saws-state
+```
+
+Use the same `SAWS_HOME` for every command that should share hosts, keys, applications, and local
+deployment state.
+
+> `saws host configure` applies an opinionated security baseline. It installs and enables Docker,
+> fail2ban, UFW, and unattended upgrades; resets the UFW rules; installs Docker firewall rules;
+> configures a deployment account; and disables SSH password authentication after verifying key
+> access. Use a new server when possible and run the command with `--dry-run` first.
+
+## 1. Create a global host
+
+A global host is a named machine profile that can be reused by any project or packaged application.
+Create a public host with:
+
+```sh
+npx saws host create edge \
+  --address 203.0.113.10 \
+  --user saws \
+  --platform linux/amd64 \
+  --exposure public
+```
+
+The important values are:
+
+- `edge`: the name passed to `getGlobalHost("edge")` later.
+- `--address`: a DNS name or IP address reachable over SSH.
+- `--user`: the persistent, unprivileged account SAWS will create and use for deployments. This is
+  not necessarily the account that already exists on the server.
+- `--platform`: the Docker target platform. It is optional, but useful when the development machine
+  and server use different CPU architectures. Examples include `linux/amd64` and `linux/arm64`.
+- `--exposure`: `public` or `tunnel`. Public hosts allow selected inbound application ports;
+  tunnel hosts allow none.
+
+A public host allows TCP ports 80 and 443 by default. Specify the complete public-port set when an
+application needs different ports:
+
+```sh
+npx saws host create observability \
+  --address metrics.example.com \
+  --user saws \
+  --exposure public \
+  --allowed-tcp-port 8080 4317 4318
+```
+
+When `--allowed-tcp-port` is supplied, it replaces the default list; include 80 and 443 explicitly
+if the machine also needs them. The SSH port is allowed separately. To use a nonstandard SSH port,
+add `--ssh-port 2222`.
+
+For a private machine reached only through an SSH or network tunnel:
+
+```sh
+npx saws host create internal \
+  --address 10.0.0.20 \
+  --user saws \
+  --exposure tunnel
+```
+
+Do not supply public ports for a tunnel host.
+
+### Where the profile is stored
+
+The profile is plain JSON at:
+
+```text
+~/.saws/hosts/<name>/host.json
+```
+
+It contains the address, users, ports, exposure policy, and platform, but no private key. If you edit
+the profile directly, rerun the configure step so the host firewall and readiness record match it.
+Creating a host whose name already exists fails instead of overwriting the profile.
+
+## 2. Configure the machine
+
+Preview the bootstrap operation first:
+
+```sh
+npx saws host configure edge --global --user ubuntu --dry-run
+```
+
+Then apply it:
+
+```sh
+npx saws host configure edge --global --user ubuntu
+```
+
+Here, `ubuntu` is an existing bootstrap account with root or sudo access. It is used only to prepare
+the server. Subsequent deployments connect as the persistent deployment user (`saws` in this
+example) configured by the earlier host-creation command.
+
+SAWS generates an Ed25519 deployment key when the global host does not have one, encrypts the
+private key in the global secret store, installs the public key for the deployment account, and only
+then disables password-based SSH access.
+
+To use an existing unencrypted, non-passphrase-protected private key, import it before configuring
+the machine:
+
+```sh
+npx saws host key import edge --file ~/.ssh/edge_deploy
+npx saws host configure edge --global --user ubuntu
+```
+
+The source file is not modified. Import refuses to replace an existing key unless `--force` is
+passed.
+
+Global host keys are encrypted beneath `~/.saws/secrets`. The encryption passcode and generated
+public-key metadata are stored in `~/.saws/.env`, with file permissions restricted to the current
+user. Back up both locations securely. Losing the passcode makes the encrypted deployment key
+unusable.
+
+## 3. Install an application instance
+
+Install the package and give this local instance a name:
+
+```sh
+npx saws app install @saws/reverse-proxy-application --name edge-proxy
+```
+
+The package argument accepts an npm version or tag. Pin a version for the initial installation if
+needed:
+
+```sh
+npx saws app install @saws/reverse-proxy-application@2.0.0-beta.17 --name edge-proxy
+```
+
+SAWS refuses to install over an existing application name. It creates this local application
+directory:
+
+```text
+~/.saws/apps/edge-proxy/
+├── config.ts
+├── package.json
+├── package-lock.json
+├── saws.ts
+└── node_modules/
+```
+
+This directory also becomes the home for that instance's secrets, outputs, and other local SAWS
+state. The install command does not deploy anything.
+
+List installed application instances, package versions, and configuration state at any time:
+
+```sh
+npx saws app list
+```
+
+## 4. Configure the generated file
+
+A packaged application exports the shape of the input it expects. Consult that package's README for
+its application-specific fields. Applications that deploy to a remote machine accept or derive a
+`Host`; reference the global profile with `getGlobalHost`.
+
+Open the generated configuration in your editor:
+
+```sh
+${EDITOR:-vi} "${SAWS_HOME:-$HOME/.saws}/apps/edge-proxy/config.ts"
+```
+
+The generated file derives its type from the installed application's `create` factory. TypeScript
+therefore reports missing or incompatible fields. For example, `config.ts` can route public
+hostnames to ports on the target machine:
+
+```ts
+import { getGlobalHost } from "@saws/core";
+import type { ReverseProxyApplicationConfig } from "@saws/reverse-proxy-application";
+
+export default {
+  host: getGlobalHost("edge"),
+  acmeEmail: "ops@example.com",
+  routes: [
+    { hostname: "api.example.com", port: 3000 },
+    { hostname: "app.example.com", port: 8080, healthUri: "/health" },
+  ],
+} satisfies ReverseProxyApplicationConfig;
+```
+
+For applications with secrets, export a `SecretsManager` named `secrets` and pass lazy references
+instead of secret values:
+
+```ts
+import { getGlobalHost, SecretsManager } from "@saws/core";
+import type { OpenDesignApplicationConfig } from "@saws/open-design-application";
+
+export const secrets = new SecretsManager();
+
+export default {
+  host: getGlobalHost("edge"),
+  registry: "registry.example.com/saws",
+  setupPassword: secrets.reference("open-design-application-password"),
+} satisfies OpenDesignApplicationConfig;
+```
+
+`secrets.reference(...)` is stage-scoped: production and staging can use different values without
+changing the configuration file. Use `secrets.global.reference(...)` only for a value intentionally
+shared across stages.
+
+### Update an installed application
+
+Update an instance when the version on its npm release channel is newer than its installed semantic
+version:
+
+```sh
+npx saws app update edge-proxy
+```
+
+Update never overwrites `config.ts`. Stable applications follow npm's `latest` dist-tag, while
+applications already on a beta version follow the `beta` dist-tag. If the instance was installed by
+an older SAWS CLI, its first update renames `input.ts` to `config.ts` without changing the contents.
+If both files exist, update stops and asks you to resolve the ambiguity.
+
+### Set application secrets
+
+Run secret commands from the installed application directory so a default `SecretsManager` resolves
+the correct storage location:
+
+```sh
+cd "${SAWS_HOME:-$HOME/.saws}/apps/edge-proxy"
+npx --package @saws/cli saws secrets example-secret \
+  --stage production \
+  --set 'replace-with-the-secret-value'
+```
+
+Avoid placing real secret values in shell history when that matters for your environment. The
+encrypted stage file is stored under the installed application's `.saws/secrets` directory.
+
+## 5. Deploy the application
+
+Deploy a named instance to any non-`local` stage:
+
+```sh
+npx saws app deploy edge-proxy --stage production
+```
+
+The deployment command:
+
+1. Loads `~/.saws/apps/edge-proxy/saws.ts`.
+2. Resolves the generated configuration and application factory.
+3. Resolves stage-scoped environment and secrets.
+4. Connects to the global host with its deployment key.
+5. Verifies that the host still matches the configured security policy.
+6. Deploys application dependencies in order and starts or replaces changed containers.
+
+By default, stages isolate generated names, Docker networks, persistent volumes, runtime files,
+secrets, and outputs. Deploying `staging` and `production` therefore creates separate application
+resources even when they use the same host. Explicitly overridden volume names can opt out of that
+isolation.
+
+For a public application, confirm before deployment that:
+
+- DNS records point to the host.
+- Every published TCP port is in the global host's `allowedTcpPorts`.
+- Cloud-provider or upstream-network firewalls allow the same ports.
+- Any required registry credentials and application secrets exist for the target stage.
+- Services addressed by a reverse proxy are reachable from the proxy container.
+
+## Operations and troubleshooting
+
+To run standard SAWS commands against an installed application, change into its directory:
+
+```sh
+cd "${SAWS_HOME:-$HOME/.saws}/apps/edge-proxy"
+npx --package @saws/cli saws logs --stage production
+npx --package @saws/cli saws logs reverse-proxy --stage production
+```
+
+Common failures:
+
+- **Host is not configured or has drifted:** rerun the global `host configure` command with the host
+  name and bootstrap user. This reapplies the declared firewall and security policy.
+- **SSH fails after configuration:** verify that the global key store and `~/.saws/.env` came from
+  the same SAWS home and that the configured address and SSH port are correct.
+- **A published service is unreachable:** Docker port publishing and the host allowlist are separate.
+  The service must publish the port, and the host profile must allow it.
+- **An HTTPS certificate is not issued:** verify public DNS and inbound ports 80 and 443. A hostname
+  route in the reverse-proxy application requests and renews its certificate automatically.
+- **A remote Dockerfile application asks for a registry:** remote hosts cannot use an image that was
+  built only on the development machine. Configure the application's `registry` and any required
+  registry authentication, or supply a prebuilt image.
+- **A secret cannot be decrypted:** use the same `SAWS_HOME` and `SAWS_SECRETS_PASSCODE` that created
+  the encrypted file.
+
+Treat `~/.saws` (or the configured `SAWS_HOME`) as operational state. Back it up securely, especially
+the global `.env`, encrypted secret stores, application input files, and any output needed by your
+deployment workflow. Remote Docker volumes must be backed up separately on the target machines.

package/package.json

@@ -1,34 +1,27 @@
 {
   "name": "@saws/cli",
-  "version": "2.0.0-beta.2",
-  "description": "Command-line interface for SAWS",
+  "version": "2.0.0-beta.21",
+  "description": "",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/shichongrui/saws.git",
-    "directory": "packages/cli"
+    "url": "git+https://github.com/shichongrui/saws.git"
   },
-  "type": "module",
   "bin": {
-    "saws": "dist/bin/saws.js"
+    "saws": "./dist/bin/saws.js"
   },
   "files": [
-    "dist"
+    "./dist",
+    "./docs"
   ],
-  "scripts": {
-    "prebuild": "node -e \"fs.rmSync('dist', { recursive: true, force: true })\"",
-    "build": "tsc -p tsconfig.json",
-    "postbuild": "chmod +x dist/bin/saws.js",
-    "test": "npm run build && node --test dist/commands/**/*.test.js",
-    "typecheck": "tsc -p tsconfig.json --noEmit"
-  },
+  "type": "module",
   "dependencies": {
-    "@saws/core": "2.0.0-beta.2",
-    "@saws/host": "2.0.0-beta.2",
-    "@saws/secrets": "2.0.0-beta.2",
-    "commander": "^14.0.3"
+    "@saws/core": "2.0.0-beta.21",
+    "commander": "^15.0.0",
+    "find-package-json": "^1.2.0",
+    "semver": "^7.8.5"
   },
   "devDependencies": {
-    "@types/node": "^20.11.19",
-    "typescript": "^5.3.3"
+    "@types/find-package-json": "^1.2.7",
+    "@types/semver": "^7.8.0"
   }
 }

package/dist/bin/saws.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"saws.d.ts","sourceRoot":"","sources":["../../src/bin/saws.ts"],"names":[],"mappings":""}