@wpelevator/tug 0.5.0 → 0.6.0

package/dist/cli-config.js

@@ -1,36 +1,286 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import yaml from 'js-yaml';
+/** Defaults for options of commands that work on the project (top level of the config file). */
+export const COMMAND_SETTINGS = {
+    file: { type: 'path', flag: '--file', commands: ['deploy'] },
+    buildLocal: { type: 'boolean', flag: '--build-local', commands: ['deploy'] },
+    wait: { type: 'boolean', flag: '--no-wait', commands: ['deploy', 'rollback'] },
+};
+/** Per-node connection data (`nodes.<name>`); `nodeDefaults` takes the subset that is not node-specific. */
+export const NODE_SETTINGS = {
+    ssh: { type: 'string', flag: '<ssh-target>', commands: ['node-install'] },
+    address: { type: 'string', flag: '--address', commands: ['node-install', 'node-register'] },
+    publicAddress: {
+        type: 'string',
+        flag: '--public-address',
+        commands: ['node-install', 'node-register'],
+    },
+    label: {
+        type: 'list',
+        flag: '--label',
+        commands: ['node-install', 'node-register', 'node-enroll'],
+    },
+    mesh: { type: 'boolean', flag: '--mesh', commands: ['node-install', 'node-enroll'] },
+    wgPort: { type: 'port', flag: '--wg-port', commands: ['node-install'] },
+    installDocker: {
+        type: 'boolean',
+        flag: '--install-docker',
+        commands: ['node-install', 'node-enroll'],
+    },
+    image: { type: 'string', flag: '--image', commands: ['node-install', 'node-enroll'] },
+    agentControlUrl: {
+        type: 'string',
+        flag: '--agent-control-url',
+        commands: ['node-install', 'node-enroll'],
+    },
+    httpOnlyDev: {
+        type: 'boolean',
+        flag: '--http-only-dev',
+        commands: ['node-install', 'node-enroll'],
+    },
+    ca: { type: 'path', flag: '--ca', commands: ['node-enroll'] },
+};
+const NODE_SPECIFIC_KEYS = ['ssh', 'address', 'publicAddress'];
+const SETTINGS = { ...COMMAND_SETTINGS, ...NODE_SETTINGS };
+/** Default file names, in lookup order; more than one present is an error. */
+export const CONFIG_NAMES = ['tug.yml', 'tug.yaml', 'tug.json', '.tug.json'];
+/** `tug.yml` becomes `tug.local.yml`, `.tug.json` becomes `.tug.local.json`. */
+export function localConfigPath(file) {
+    const { dir, name, ext } = path.parse(file);
+    return path.join(dir, `${name}.local${ext}`);
+}
 /** Resolve adapter settings once; domain operations receive these explicit values. */
 export async function resolveCliConfig(options, env, cwd, creating = false) {
     for (const key of ['config', 'controlUrl', 'project'])
         if (options[key] !== undefined && (!options[key].trim() || /[\r\n\0]/.test(options[key])))
             throw new Error(`--${key.replace(/[A-Z]/g, (c) => '-' + c.toLowerCase())} must be a nonempty single-line value`);
-    const file = path.resolve(cwd, options.config || env.TUG_CONFIG || '.tug.json');
-    let config = {};
-    try {
-        const input = JSON.parse(await fs.readFile(file, 'utf8'));
-        if (!input || typeof input !== 'object' || Array.isArray(input))
-            throw new Error('expected a JSON object');
-        for (const key of ['controlUrl', 'operatorToken', 'project']) {
-            const value = input[key];
-            if (value !== undefined && (typeof value !== 'string' || !value.trim()))
-                throw new Error(`${key} must be a nonempty string`);
-        }
-        config = input;
-    }
-    catch (error) {
-        const missing = error.code === 'ENOENT';
-        if (!missing || (!creating && Boolean(options.config || env.TUG_CONFIG)))
-            throw new Error(`Cannot read config ${file}: ${error.message}`, { cause: error });
-    }
+    const selected = options.config || env.TUG_CONFIG;
+    const file = selected ? path.resolve(cwd, selected) : await discoverConfigFile(cwd);
+    const localFile = localConfigPath(file);
+    const base = await readConfigFile(file, false);
+    if (!base && !creating && selected)
+        throw new Error(`Cannot read config ${file}: ENOENT: no such file`);
+    const overlay = await readConfigFile(localFile, true);
+    const config = mergeConfigs(base ?? emptyConfig(), overlay ?? emptyConfig());
     const controlUrl = options.controlUrl || env.TUG_CONTROL_URL || config.controlUrl || 'http://localhost:8080';
     return {
         file,
+        fileExists: Boolean(base),
+        localFile,
         controlUrl: normalizeControlUrl(controlUrl),
-        operatorToken: env.TUG_TOKEN || config.operatorToken,
+        token: env.TUG_TOKEN || config.token,
         project: options.project || env.TUG_PROJECT || config.project || 'site',
+        commandDefaults: config.commandDefaults,
+        nodeDefaults: config.nodeDefaults,
+        nodes: config.nodes,
     };
 }
+/** `nodeDefaults` under the node's own keys; a list in the node replaces the default list. */
+export function nodeSettings(config, name) {
+    return { ...config.nodeDefaults, ...(name ? config.nodes[name] : undefined) };
+}
+/**
+ * Use config values as defaults for the options of a command: a key applies to a command that lists it
+ * and has an option of that name, and never over a value given on the command line.
+ */
+export function applyConfigDefaults(command, values, settings) {
+    const attributes = new Set(command.options.map((option) => option.attributeName()));
+    for (const [key, value] of Object.entries(settings)) {
+        if (SETTINGS[key]?.commands.includes(command.name()) &&
+            attributes.has(key) &&
+            command.getOptionValueSource(key) !== 'cli')
+            values[key] = value;
+    }
+}
+function emptyConfig() {
+    return { commandDefaults: {}, nodeDefaults: {}, nodes: {} };
+}
+async function discoverConfigFile(cwd) {
+    const found = [];
+    for (const name of CONFIG_NAMES) {
+        try {
+            await fs.stat(path.join(cwd, name));
+            found.push(name);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+    }
+    if (found.length > 1)
+        throw new Error(`Found more than one config file (${found.join(', ')}) in ${cwd}; keep one or select it with --config`);
+    return path.join(cwd, found[0] ?? CONFIG_NAMES[0]);
+}
+function parseText(file, content) {
+    return path.extname(file) === '.json' ? JSON.parse(content) : yaml.load(content);
+}
+async function readConfigFile(file, overlay) {
+    let content;
+    try {
+        content = await fs.readFile(file, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw new Error(`Cannot read config ${file}: ${error.message}`, { cause: error });
+    }
+    try {
+        return parseConfig(parseText(file, content) ?? {}, path.dirname(file), overlay ? undefined : localConfigPath(file));
+    }
+    catch (error) {
+        throw new Error(`Cannot read config ${file}: ${error.message}`, { cause: error });
+    }
+}
+const isObject = (value) => Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+function text(value, where) {
+    if (typeof value !== 'string' || !value.trim() || /[\r\n\0]/.test(value))
+        throw new Error(`${where} must be a nonempty single-line string`);
+    return value;
+}
+/** Same rule as --name, so a name from the file is as safe as one typed. */
+function nodeName(name) {
+    if (!/^[a-zA-Z0-9][a-zA-Z0-9_.-]*$/.test(name))
+        throw new Error(`nodes.${name} must be a node name of letters, numbers, dots, underscores or hyphens`);
+    return name;
+}
+function settingValue(setting, value, where, dir) {
+    switch (setting.type) {
+        case 'string':
+            return text(value, where);
+        case 'path':
+            return path.resolve(dir, text(value, where));
+        case 'boolean':
+            if (typeof value !== 'boolean')
+                throw new Error(`${where} must be true or false`);
+            return value;
+        case 'port':
+            return String(integerOption(String(value), where, 1, 65535));
+        case 'list':
+            return (Array.isArray(value) ? value : [value]).map((item, index) => text(item, Array.isArray(value) ? `${where}[${index}]` : where));
+    }
+}
+function parseSettings(input, table, where, dir) {
+    if (!isObject(input))
+        throw new Error(`${where} must be a mapping`);
+    const settings = {};
+    for (const [key, value] of Object.entries(input)) {
+        if (!table[key])
+            throw new Error(`${where}.${key} is not a known setting (known: ${Object.keys(table).join(', ')})`);
+        settings[key] = settingValue(table[key], value, `${where}.${key}`, dir);
+    }
+    return settings;
+}
+/** `overlay` names the overlay to suggest for a tracked file; undefined means this file is the overlay and may hold a token. */
+function parseConfig(input, dir, overlay) {
+    if (!isObject(input))
+        throw new Error('expected a mapping of settings');
+    const config = emptyConfig();
+    const nodeDefaultsTable = Object.fromEntries(Object.entries(NODE_SETTINGS).filter(([key]) => !NODE_SPECIFIC_KEYS.includes(key)));
+    for (const [key, value] of Object.entries(input)) {
+        if (key === 'controlUrl' || key === 'project')
+            config[key] = text(value, key);
+        else if (key === 'token') {
+            if (overlay)
+                throw new Error(`token must not be set in a tracked file; put it in ${overlay} or TUG_TOKEN`);
+            config.token = text(value, key);
+        }
+        else if (COMMAND_SETTINGS[key])
+            config.commandDefaults[key] = settingValue(COMMAND_SETTINGS[key], value, key, dir);
+        else if (key === 'nodeDefaults')
+            config.nodeDefaults = parseSettings(value, nodeDefaultsTable, key, dir);
+        else if (key === 'nodes') {
+            if (!isObject(value))
+                throw new Error('nodes must be a mapping of node names');
+            for (const [name, node] of Object.entries(value))
+                config.nodes[nodeName(name)] = parseSettings(node ?? {}, NODE_SETTINGS, `nodes.${name}`, dir);
+        }
+        else {
+            const known = [
+                'controlUrl',
+                'project',
+                ...(overlay ? [] : ['token']),
+                ...Object.keys(COMMAND_SETTINGS),
+                'nodeDefaults',
+                'nodes',
+            ];
+            throw new Error(`${key} is not a known setting (known: ${known.join(', ')})`);
+        }
+    }
+    return config;
+}
+/** The overlay wins key by key, including inside `nodeDefaults` and each node. */
+function mergeConfigs(base, overlay) {
+    const nodes = {};
+    for (const name of new Set([...Object.keys(base.nodes), ...Object.keys(overlay.nodes)]))
+        nodes[name] = { ...base.nodes[name], ...overlay.nodes[name] };
+    return {
+        controlUrl: overlay.controlUrl ?? base.controlUrl,
+        project: overlay.project ?? base.project,
+        token: overlay.token ?? base.token,
+        commandDefaults: { ...base.commandDefaults, ...overlay.commandDefaults },
+        nodeDefaults: { ...base.nodeDefaults, ...overlay.nodeDefaults },
+        nodes,
+    };
+}
+function serialize(file, data, notice) {
+    if (path.extname(file) === '.json')
+        return `${JSON.stringify(data, null, 2)}\n`;
+    return `${notice ? `# ${notice}\n` : ''}${yaml.dump(data)}`;
+}
+/**
+ * `tug init`: create the tracked file when it is missing and always store the token in the untracked
+ * overlay, git-ignoring it. An existing tracked file is never rewritten, so its comments survive;
+ * connection flags passed to `init` are saved to the overlay instead.
+ */
+export async function writeInitConfig(config, token, explicit) {
+    const written = [];
+    if (!config.fileExists) {
+        await fs.mkdir(path.dirname(config.file), { recursive: true });
+        await fs.writeFile(config.file, serialize(config.file, { controlUrl: config.controlUrl, project: config.project }, `Safe to commit: keep the API token out of this file (use TUG_TOKEN or ${path.basename(config.localFile)}).`));
+        written.push(config.file);
+    }
+    let local = {};
+    try {
+        const existing = parseText(config.localFile, await fs.readFile(config.localFile, 'utf8'));
+        if (isObject(existing))
+            local = existing;
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    local.token = token;
+    if (config.fileExists) {
+        if (explicit.controlUrl)
+            local.controlUrl = config.controlUrl;
+        if (explicit.project)
+            local.project = config.project;
+    }
+    await fs.writeFile(config.localFile, serialize(config.localFile, local), { mode: 0o600 });
+    await fs.chmod(config.localFile, 0o600);
+    written.push(config.localFile);
+    await gitIgnore(config.localFile);
+    return written;
+}
+/** Add `file` to the .gitignore next to it when it sits in a git work tree and is not ignored yet. */
+async function gitIgnore(file) {
+    const cwd = path.dirname(file);
+    const ignored = spawnSync('git', ['check-ignore', '-q', '--', file], { cwd });
+    if (ignored.status !== 1)
+        return; // 0: already ignored; anything else: not a git checkout
+    const ignoreFile = path.join(cwd, '.gitignore');
+    let current = '';
+    try {
+        current = await fs.readFile(ignoreFile, 'utf8');
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    await fs.writeFile(ignoreFile, `${current}${current && !current.endsWith('\n') ? '\n' : ''}${path.basename(file)}\n`);
+}
 export function normalizeControlUrl(value) {
     if (!value.trim() || /[\r\n\0]/.test(value))
         throw new Error('control URL must be a nonempty single-line URL');

package/dist/cli-live-transport.d.ts

@@ -1,3 +1,3 @@
 import type { CliLiveTransport } from './cli-live.ts';
 /** Credentials travel only in the upgrade header, never a URL or frame. */
-export declare function createCliLiveTransport(controlUrl: string, operatorToken?: string): CliLiveTransport;
+export declare function createCliLiveTransport(controlUrl: string, token?: string): CliLiveTransport;

package/dist/cli-live-transport.js

@@ -3,7 +3,7 @@ import { CliLiveError } from "./cli-live.js";
 import { LIVE_MAX_FRAME_BYTES as MAX_FRAME, LIVE_MAX_BUFFERED_BYTES as MAX_BUFFERED, LIVE_START_TIMEOUT_MS, } from "./protocol.js";
 const MAX_EVENTS = 1024;
 /** Credentials travel only in the upgrade header, never a URL or frame. */
-export function createCliLiveTransport(controlUrl, operatorToken) {
+export function createCliLiveTransport(controlUrl, token) {
     const url = new URL(controlUrl);
     if (url.protocol !== 'http:' && url.protocol !== 'https:')
         throw new CliLiveError('live control URL must use http or https');
@@ -19,7 +19,7 @@ export function createCliLiveTransport(controlUrl, operatorToken) {
                     return;
                 }
                 const socket = new WebSocket(url, {
-                    headers: operatorToken ? { Authorization: `Bearer ${operatorToken}` } : {},
+                    headers: token ? { Authorization: `Bearer ${token}` } : {},
                     maxPayload: MAX_FRAME,
                     handshakeTimeout: LIVE_START_TIMEOUT_MS,
                     perMessageDeflate: false,

package/dist/cli-live.d.ts

@@ -8,6 +8,8 @@ export interface LiveInput {
     node?: string;
     command?: string[];
     interactive?: boolean;
+    /** `tug run`: a one-off container instead of the running one. */
+    oneOff?: boolean;
     tty?: boolean;
     tail?: string | number;
 }

package/dist/cli-live.js

@@ -31,6 +31,7 @@ export function parseLiveRequest(operation, input) {
         command,
         interactive: input.interactive ?? false,
         tty: input.tty ?? false,
+        ...(input.oneOff ? { oneOff: true } : {}),
     };
 }
 export class CliLiveError extends Error {