Skip to content

Commit ac3746d

Browse files
committed
docs: add JSDoc to all exported functions for docstring coverage
1 parent 920537d commit ac3746d

2 files changed

Lines changed: 29 additions & 0 deletions

File tree

‎bin/lib/deploy.js‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,11 @@ const { runArgv } = require("./runner");
1111

1212
const INSTANCE_NAME_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
1313

14+
/**
15+
* Validate that name is a safe instance/hostname string.
16+
* @param {string} name - Instance name to validate.
17+
* @throws {Error} If name is invalid, non-string, or too long.
18+
*/
1419
function validateInstanceName(name) {
1520
if (!name || typeof name !== "string" || name.length > 253 || !INSTANCE_NAME_RE.test(name)) {
1621
throw new Error(
@@ -32,11 +37,24 @@ function runSsh(host, remoteCmd, opts = {}) {
3237
return runArgv("ssh", args, opts);
3338
}
3439

40+
/**
41+
* Copy a file to a remote host via scp using argv arrays (no shell).
42+
* @param {string} src - Local source path.
43+
* @param {string} destHostPath - Remote destination in host:path format.
44+
* @param {object} [opts] - Options forwarded to runArgv.
45+
*/
3546
function runScp(src, destHostPath, opts = {}) {
3647
const args = ["-q", ...SSH_OPTS, src, destHostPath];
3748
return runArgv("scp", args, opts);
3849
}
3950

51+
/**
52+
* Sync files to a remote host via rsync using argv arrays (no shell).
53+
* @param {string[]} sources - Local paths to sync.
54+
* @param {string} host - Remote hostname (must pass validateInstanceName).
55+
* @param {string} dest - Remote destination directory.
56+
* @param {object} [opts] - Options forwarded to runArgv.
57+
*/
4058
function runRsync(sources, host, dest, opts = {}) {
4159
const args = [
4260
"-az", "--delete",
@@ -50,6 +68,11 @@ function runRsync(sources, host, dest, opts = {}) {
5068
return runArgv("rsync", args, opts);
5169
}
5270

71+
/**
72+
* Wrap a string in POSIX single quotes, escaping embedded quotes.
73+
* @param {string} s - Value to quote.
74+
* @returns {string} Shell-safe single-quoted string.
75+
*/
5376
function shellQuote(s) {
5477
return "'" + s.replace(/'/g, "'\\''") + "'";
5578
}

‎bin/lib/runner.js‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,12 @@ const BLOCKED_ENV_VARS = new Set([
4848
"CURL_CA_BUNDLE", "SSL_CERT_FILE", "NODE_EXTRA_CA_CERTS",
4949
]);
5050

51+
/**
52+
* Validate caller-supplied env vars against a blocklist of dangerous keys.
53+
* Throws if any blocked key is present; returns a shallow copy otherwise.
54+
* @param {object} [callerEnv] - Env overrides from the caller.
55+
* @returns {object} Sanitized env entries safe to merge with process.env.
56+
*/
5157
function sanitizeEnv(callerEnv) {
5258
if (!callerEnv) return {};
5359
const blocked = Object.keys(callerEnv).filter((k) => BLOCKED_ENV_VARS.has(k));

0 commit comments

Comments
 (0)