@wpelevator/tug 0.9.0 → 0.11.0

package/dist/cli-prompt.d.ts

@@ -0,0 +1,9 @@
+/** True when both ends are a terminal and the run is not CI, so asking a question can be answered. */
+export declare function canPrompt(env?: NodeJS.ProcessEnv): boolean;
+export type Prompter = (question: string, hidden?: boolean) => Promise<string>;
+/** Ask a line of text on the terminal; with `hidden` the typed characters are not echoed. */
+export declare const ask: Prompter;
+/** A yes/no question; an empty answer takes `fallback`. */
+export declare function confirm(question: string, fallback?: boolean, prompt?: Prompter): Promise<boolean>;
+/** Pick one of `options` by number; an empty answer takes the option at `fallback`. */
+export declare function choose(question: string, options: readonly string[], fallback?: number, prompt?: Prompter): Promise<number>;

package/dist/cli-prompt.js

@@ -0,0 +1,60 @@
+import readline from 'node:readline';
+import { Writable } from 'node:stream';
+/** True when both ends are a terminal and the run is not CI, so asking a question can be answered. */
+export function canPrompt(env = process.env) {
+    return !!process.stdin.isTTY && !!process.stdout.isTTY && !env.CI;
+}
+/** Ask a line of text on the terminal; with `hidden` the typed characters are not echoed. */
+export const ask = async (question, hidden = false) => {
+    const muted = { on: false };
+    const output = new Writable({
+        write(chunk, _encoding, callback) {
+            if (!muted.on)
+                process.stdout.write(chunk);
+            callback();
+        },
+    });
+    const rl = readline.createInterface({ input: process.stdin, output, terminal: true });
+    try {
+        return await new Promise((resolve, reject) => {
+            rl.once('close', () => reject(new Error('input closed before an answer was given')));
+            rl.question(question, (answer) => {
+                if (hidden)
+                    process.stdout.write('\n');
+                resolve(answer);
+            });
+            muted.on = hidden;
+        });
+    }
+    finally {
+        rl.removeAllListeners('close');
+        rl.close();
+    }
+};
+/** A yes/no question; an empty answer takes `fallback`. */
+export async function confirm(question, fallback = true, prompt = ask) {
+    for (;;) {
+        const answer = (await prompt(`${question} ${fallback ? '(Y/n)' : '(y/N)'} `))
+            .trim()
+            .toLowerCase();
+        if (answer === '')
+            return fallback;
+        if (answer === 'y' || answer === 'yes')
+            return true;
+        if (answer === 'n' || answer === 'no')
+            return false;
+    }
+}
+/** Pick one of `options` by number; an empty answer takes the option at `fallback`. */
+export async function choose(question, options, fallback = 0, prompt = ask) {
+    console.error(question);
+    options.forEach((option, index) => console.error(`  ${index + 1}) ${option}`));
+    for (;;) {
+        const answer = (await prompt(`Choose 1-${options.length} (${fallback + 1}): `)).trim();
+        if (answer === '')
+            return fallback;
+        const index = Number(answer) - 1;
+        if (Number.isInteger(index) && index >= 0 && index < options.length)
+            return index;
+    }
+}

package/dist/cli-secrets.d.ts

@@ -0,0 +1,12 @@
+import type { Prompter } from './cli-prompt.ts';
+/** Variable names a Compose file requires, in order of appearance; ones with a default are optional. */
+export declare function requiredVariables(source: string): string[];
+/**
+ * Variables the Compose file references that nothing supplies: not a control secret, the environment
+ * or `.env`. Compose would render them empty, which for a password is never intended.
+ */
+export declare function findMissingSecrets(file: string, secretNames: readonly string[], env?: NodeJS.ProcessEnv): Promise<string[]>;
+/** A URL-safe random secret with 192 bits of entropy. */
+export declare function generateSecret(): string;
+/** Resolve each missing secret interactively; returns the values to store. */
+export declare function promptForSecrets(names: readonly string[], prompt?: Prompter): Promise<Record<string, string>>;

package/dist/cli-secrets.js

@@ -0,0 +1,71 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { ask } from "./cli-prompt.js";
+/** `$$` is an escaped dollar; `${NAME}` is required only when it has no `:-`, `-`, `:+`, `+`, `:?` or `?` modifier. */
+const REFERENCE = /\$\$|\$\{([A-Za-z_][A-Za-z0-9_]*)\}|\$([A-Za-z_][A-Za-z0-9_]*)/g;
+/** Variable names a Compose file requires, in order of appearance; ones with a default are optional. */
+export function requiredVariables(source) {
+    const names = new Set();
+    for (const line of source.split('\n')) {
+        if (/^\s*#/.test(line))
+            continue;
+        for (const match of line.matchAll(REFERENCE)) {
+            const name = match[1] ?? match[2];
+            if (name)
+                names.add(name);
+        }
+    }
+    return [...names];
+}
+/** Variables Compose reads from the `.env` file next to the Compose file. */
+async function dotEnvNames(dir) {
+    try {
+        const text = await fs.readFile(path.join(dir, '.env'), 'utf8');
+        return new Set(text
+            .split('\n')
+            .map((line) => /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/.exec(line)?.[1])
+            .filter((name) => !!name));
+    }
+    catch {
+        return new Set();
+    }
+}
+/**
+ * Variables the Compose file references that nothing supplies: not a control secret, the environment
+ * or `.env`. Compose would render them empty, which for a password is never intended.
+ */
+export async function findMissingSecrets(file, secretNames, env = process.env) {
+    const known = new Set(secretNames);
+    const dotEnv = await dotEnvNames(path.dirname(file));
+    // An unreadable file is reported by `docker compose config` with its own message.
+    const source = await fs.readFile(file, 'utf8').catch(() => '');
+    return requiredVariables(source).filter((name) => !known.has(name) && env[name] === undefined && !dotEnv.has(name));
+}
+/** A URL-safe random secret with 192 bits of entropy. */
+export function generateSecret() {
+    return crypto.randomBytes(24).toString('base64url');
+}
+/** Resolve each missing secret interactively; returns the values to store. */
+export async function promptForSecrets(names, prompt = ask) {
+    const values = {};
+    for (const name of names) {
+        for (;;) {
+            const choice = (await prompt(`${name} is missing. [g]enerate a strong password or [e]nter a value? (g) `))
+                .trim()
+                .toLowerCase();
+            if (choice === '' || choice === 'g') {
+                values[name] = generateSecret();
+                break;
+            }
+            if (choice === 'e') {
+                const value = await prompt(`${name}: `, true);
+                if (value) {
+                    values[name] = value;
+                    break;
+                }
+            }
+        }
+    }
+    return values;
+}

package/dist/cli-status.d.ts

@@ -0,0 +1,40 @@
+/** The control status endpoint returns database rows and a JSON-encoded node report. */
+export interface StatusResponse {
+    projects: {
+        id: string;
+        current_deployment_id: string | null;
+    }[];
+    deployments: {
+        id: string;
+        version: string;
+        state: string;
+        error_message: string | null;
+    }[];
+    nodes: {
+        id: string;
+        name: string;
+        status: string;
+        last_seen_at: string | null;
+    }[];
+    statuses: {
+        project_id: string;
+        node_id: string;
+        node: string | null;
+        health: string;
+        observed_version: string | null;
+        status_json: string;
+    }[];
+}
+/** Render observations without treating a stale node's last report as current health. */
+export declare function formatStatus(status: StatusResponse): string;
+export interface NodeListing {
+    name: string;
+    status: string;
+    address: string | null;
+    ingress: number | boolean;
+    labels: string[];
+    last_seen_at: string | null;
+    disabled_at?: string | null;
+}
+/** A table of the registered nodes: state, inter-node address, ingress role, labels and last contact. */
+export declare function formatNodes(nodes: NodeListing[]): string;

package/dist/cli-status.js

@@ -0,0 +1,91 @@
+/** Render observations without treating a stale node's last report as current health. */
+export function formatStatus(status) {
+    const lines = [];
+    const nodes = new Map(status.nodes.map((node) => [node.id, node]));
+    for (const project of [...status.projects].sort((a, b) => a.id.localeCompare(b.id))) {
+        const deployment = status.deployments.find((item) => item.id === project.current_deployment_id);
+        lines.push(`Project ${project.id}`);
+        if (deployment) {
+            lines.push(`  Deployment: ${deployment.version} (${deployment.state})`);
+            if (deployment.error_message)
+                lines.push(`  Error: ${deployment.error_message}`);
+        }
+        else {
+            lines.push(project.current_deployment_id
+                ? '  Deployment: current deployment not in recent results'
+                : '  Deployment: none');
+        }
+        const reports = status.statuses
+            .filter((item) => item.project_id === project.id)
+            .sort((a, b) => (a.node || a.node_id).localeCompare(b.node || b.node_id));
+        if (!reports.length)
+            lines.push('  No node reports');
+        for (const report of reports) {
+            const node = nodes.get(report.node_id);
+            lines.push(`  Node ${report.node || report.node_id}: ${node?.status || 'unknown'}; last reported ${report.health}${report.observed_version ? ` (${report.observed_version})` : ''}`);
+            try {
+                const detail = JSON.parse(report.status_json);
+                if (detail &&
+                    typeof detail === 'object' &&
+                    'error' in detail &&
+                    typeof detail.error === 'string' &&
+                    detail.error)
+                    lines.push(`    Error: ${detail.error}`);
+                if (detail &&
+                    typeof detail === 'object' &&
+                    'serviceStates' in detail &&
+                    detail.serviceStates &&
+                    typeof detail.serviceStates === 'object') {
+                    lines.push(...serviceStateLines(detail.serviceStates));
+                }
+            }
+            catch {
+                lines.push('    Report details unavailable');
+            }
+        }
+    }
+    if (!status.projects.length)
+        lines.push('No projects');
+    lines.push('', 'Nodes');
+    if (!status.nodes.length)
+        lines.push('  No nodes');
+    for (const node of [...status.nodes].sort((a, b) => a.name.localeCompare(b.name)))
+        lines.push(`  ${node.name}: ${node.status}; last seen ${node.last_seen_at || 'never'}`);
+    return lines.join('\n');
+}
+/** A table of the registered nodes: state, inter-node address, ingress role, labels and last contact. */
+export function formatNodes(nodes) {
+    if (!nodes.length)
+        return 'No nodes';
+    const rows = [
+        ['NODE', 'STATUS', 'ADDRESS', 'INGRESS', 'LABELS', 'LAST SEEN'],
+        ...[...nodes]
+            .sort((a, b) => a.name.localeCompare(b.name))
+            .map((node) => [
+            node.name,
+            node.disabled_at ? 'disabled' : node.status,
+            node.address || '-',
+            node.ingress ? 'yes' : 'no',
+            node.labels.join(',') || '-',
+            node.last_seen_at || 'never',
+        ]),
+    ];
+    const widths = rows[0].map((_, column) => Math.max(...rows.map((row) => row[column].length)));
+    return rows
+        .map((row) => row
+        .map((cell, column) => cell.padEnd(widths[column]))
+        .join('  ')
+        .trimEnd())
+        .join('\n');
+}
+function serviceStateLines(serviceStates) {
+    return Object.entries(serviceStates)
+        .sort(([a], [b]) => a.localeCompare(b))
+        .flatMap(([name, state]) => {
+        const item = (state && typeof state === 'object' ? state : {});
+        if (typeof item.rolloutState !== 'string')
+            return [];
+        const error = typeof item.rolloutError === 'string' && item.rolloutError ? ` — ${item.rolloutError}` : '';
+        return [`    ${name}: ${item.rolloutState}${error}`];
+    });
+}