@tmhs/homelab-mcp 0.15.3 → 0.16.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +9 -4
- package/dist/index.js +1 -1
- package/dist/tools/adguardFilters.d.ts.map +1 -1
- package/dist/tools/adguardFilters.js +7 -26
- package/dist/tools/adguardFilters.js.map +1 -1
- package/dist/tools/adguardQueryLog.d.ts.map +1 -1
- package/dist/tools/adguardQueryLog.js +8 -26
- package/dist/tools/adguardQueryLog.js.map +1 -1
- package/dist/tools/adguardStats.d.ts.map +1 -1
- package/dist/tools/adguardStats.js +7 -26
- package/dist/tools/adguardStats.js.map +1 -1
- package/dist/tools/alertList.d.ts +5 -0
- package/dist/tools/alertList.d.ts.map +1 -1
- package/dist/tools/alertList.js +16 -17
- package/dist/tools/alertList.js.map +1 -1
- package/dist/tools/aptHistory.d.ts +6 -0
- package/dist/tools/aptHistory.d.ts.map +1 -1
- package/dist/tools/aptHistory.js +14 -4
- package/dist/tools/aptHistory.js.map +1 -1
- package/dist/tools/aptUpdate.d.ts.map +1 -1
- package/dist/tools/aptUpdate.js +20 -5
- package/dist/tools/aptUpdate.js.map +1 -1
- package/dist/tools/backupDiff.d.ts.map +1 -1
- package/dist/tools/backupDiff.js +2 -1
- package/dist/tools/backupDiff.js.map +1 -1
- package/dist/tools/backupList.d.ts.map +1 -1
- package/dist/tools/backupList.js +7 -4
- package/dist/tools/backupList.js.map +1 -1
- package/dist/tools/backupRestore.d.ts.map +1 -1
- package/dist/tools/backupRestore.js +4 -3
- package/dist/tools/backupRestore.js.map +1 -1
- package/dist/tools/backupRun.d.ts.map +1 -1
- package/dist/tools/backupRun.js +10 -2
- package/dist/tools/backupRun.js.map +1 -1
- package/dist/tools/backupStatus.d.ts.map +1 -1
- package/dist/tools/backupStatus.js +8 -4
- package/dist/tools/backupStatus.js.map +1 -1
- package/dist/tools/certList.d.ts.map +1 -1
- package/dist/tools/certList.js +25 -18
- package/dist/tools/certList.js.map +1 -1
- package/dist/tools/certRenew.js +2 -2
- package/dist/tools/certRenew.js.map +1 -1
- package/dist/tools/composeDown.d.ts.map +1 -1
- package/dist/tools/composeDown.js +3 -10
- package/dist/tools/composeDown.js.map +1 -1
- package/dist/tools/composePs.d.ts.map +1 -1
- package/dist/tools/composePs.js +2 -2
- package/dist/tools/composePs.js.map +1 -1
- package/dist/tools/composePull.d.ts.map +1 -1
- package/dist/tools/composePull.js +3 -10
- package/dist/tools/composePull.js.map +1 -1
- package/dist/tools/composeUp.d.ts.map +1 -1
- package/dist/tools/composeUp.js +5 -11
- package/dist/tools/composeUp.js.map +1 -1
- package/dist/tools/containerScan.d.ts.map +1 -1
- package/dist/tools/containerScan.js +14 -6
- package/dist/tools/containerScan.js.map +1 -1
- package/dist/tools/diagnostics.d.ts +5 -0
- package/dist/tools/diagnostics.d.ts.map +1 -1
- package/dist/tools/diagnostics.js +26 -19
- package/dist/tools/diagnostics.js.map +1 -1
- package/dist/tools/diskUsage.d.ts.map +1 -1
- package/dist/tools/diskUsage.js +4 -3
- package/dist/tools/diskUsage.js.map +1 -1
- package/dist/tools/grafanaSnapshot.d.ts.map +1 -1
- package/dist/tools/grafanaSnapshot.js +11 -34
- package/dist/tools/grafanaSnapshot.js.map +1 -1
- package/dist/tools/healthCheck.d.ts +8 -0
- package/dist/tools/healthCheck.d.ts.map +1 -1
- package/dist/tools/healthCheck.js +56 -21
- package/dist/tools/healthCheck.js.map +1 -1
- package/dist/tools/journalLogs.d.ts.map +1 -1
- package/dist/tools/journalLogs.js +1 -0
- package/dist/tools/journalLogs.js.map +1 -1
- package/dist/tools/logSearch.d.ts.map +1 -1
- package/dist/tools/logSearch.js +20 -6
- package/dist/tools/logSearch.js.map +1 -1
- package/dist/tools/nodeList.d.ts.map +1 -1
- package/dist/tools/nodeList.js +22 -11
- package/dist/tools/nodeList.js.map +1 -1
- package/dist/tools/npmCerts.d.ts.map +1 -1
- package/dist/tools/npmCerts.js +6 -38
- package/dist/tools/npmCerts.js.map +1 -1
- package/dist/tools/npmProxyHosts.d.ts.map +1 -1
- package/dist/tools/npmProxyHosts.js +6 -38
- package/dist/tools/npmProxyHosts.js.map +1 -1
- package/dist/tools/ntfySend.d.ts.map +1 -1
- package/dist/tools/ntfySend.js +6 -16
- package/dist/tools/ntfySend.js.map +1 -1
- package/dist/tools/ntfyTopics.d.ts +4 -0
- package/dist/tools/ntfyTopics.d.ts.map +1 -1
- package/dist/tools/ntfyTopics.js +26 -17
- package/dist/tools/ntfyTopics.js.map +1 -1
- package/dist/tools/prometheusQuery.d.ts.map +1 -1
- package/dist/tools/prometheusQuery.js +8 -16
- package/dist/tools/prometheusQuery.js.map +1 -1
- package/dist/tools/serviceLogs.d.ts.map +1 -1
- package/dist/tools/serviceLogs.js +5 -1
- package/dist/tools/serviceLogs.js.map +1 -1
- package/dist/tools/speedtestResults.d.ts.map +1 -1
- package/dist/tools/speedtestResults.js +7 -16
- package/dist/tools/speedtestResults.js.map +1 -1
- package/dist/tools/sshTest.js +4 -4
- package/dist/tools/sshTest.js.map +1 -1
- package/dist/tools/uptimeKumaStatus.d.ts +4 -0
- package/dist/tools/uptimeKumaStatus.d.ts.map +1 -1
- package/dist/tools/uptimeKumaStatus.js +30 -16
- package/dist/tools/uptimeKumaStatus.js.map +1 -1
- package/dist/tools/volumeBackup.d.ts.map +1 -1
- package/dist/tools/volumeBackup.js +4 -3
- package/dist/tools/volumeBackup.js.map +1 -1
- package/dist/utils/compose.d.ts +27 -0
- package/dist/utils/compose.d.ts.map +1 -0
- package/dist/utils/compose.js +92 -0
- package/dist/utils/compose.js.map +1 -0
- package/dist/utils/config.d.ts +4 -0
- package/dist/utils/config.d.ts.map +1 -0
- package/dist/utils/config.js +7 -0
- package/dist/utils/config.js.map +1 -0
- package/dist/utils/errors.d.ts +2 -2
- package/dist/utils/errors.d.ts.map +1 -1
- package/dist/utils/errors.js +8 -4
- package/dist/utils/errors.js.map +1 -1
- package/dist/utils/restic.d.ts +13 -0
- package/dist/utils/restic.d.ts.map +1 -0
- package/dist/utils/restic.js +21 -0
- package/dist/utils/restic.js.map +1 -0
- package/dist/utils/service-http.d.ts +82 -0
- package/dist/utils/service-http.d.ts.map +1 -0
- package/dist/utils/service-http.js +104 -0
- package/dist/utils/service-http.js.map +1 -0
- package/dist/utils/since-param.d.ts +13 -0
- package/dist/utils/since-param.d.ts.map +1 -0
- package/dist/utils/since-param.js +21 -0
- package/dist/utils/since-param.js.map +1 -0
- package/dist/utils/ssh-api.d.ts +54 -3
- package/dist/utils/ssh-api.d.ts.map +1 -1
- package/dist/utils/ssh-api.js +222 -33
- package/dist/utils/ssh-api.js.map +1 -1
- package/package.json +1 -1
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
export interface ServiceDef {
|
|
2
|
+
/** Human-readable service name used in messages. */
|
|
3
|
+
name: string;
|
|
4
|
+
/** Env var that overrides the port. */
|
|
5
|
+
portEnv: string;
|
|
6
|
+
defaultPort: number;
|
|
7
|
+
/** Appended to HTTP-error (curl exit 22) messages, e.g. which credentials to check. */
|
|
8
|
+
authHint?: string;
|
|
9
|
+
}
|
|
10
|
+
export declare const SERVICES: {
|
|
11
|
+
adguard: {
|
|
12
|
+
name: string;
|
|
13
|
+
portEnv: string;
|
|
14
|
+
defaultPort: number;
|
|
15
|
+
authHint: string;
|
|
16
|
+
};
|
|
17
|
+
grafana: {
|
|
18
|
+
name: string;
|
|
19
|
+
portEnv: string;
|
|
20
|
+
defaultPort: number;
|
|
21
|
+
authHint: string;
|
|
22
|
+
};
|
|
23
|
+
npm: {
|
|
24
|
+
name: string;
|
|
25
|
+
portEnv: string;
|
|
26
|
+
defaultPort: number;
|
|
27
|
+
authHint: string;
|
|
28
|
+
};
|
|
29
|
+
prometheus: {
|
|
30
|
+
name: string;
|
|
31
|
+
portEnv: string;
|
|
32
|
+
defaultPort: number;
|
|
33
|
+
};
|
|
34
|
+
alertmanager: {
|
|
35
|
+
name: string;
|
|
36
|
+
portEnv: string;
|
|
37
|
+
defaultPort: number;
|
|
38
|
+
};
|
|
39
|
+
uptimeKuma: {
|
|
40
|
+
name: string;
|
|
41
|
+
portEnv: string;
|
|
42
|
+
defaultPort: number;
|
|
43
|
+
};
|
|
44
|
+
speedtest: {
|
|
45
|
+
name: string;
|
|
46
|
+
portEnv: string;
|
|
47
|
+
defaultPort: number;
|
|
48
|
+
};
|
|
49
|
+
ntfy: {
|
|
50
|
+
name: string;
|
|
51
|
+
portEnv: string;
|
|
52
|
+
defaultPort: number;
|
|
53
|
+
};
|
|
54
|
+
};
|
|
55
|
+
/** Read a HOMELAB_* setting for a node, falling back to `fallback`. */
|
|
56
|
+
export declare function setting(node: string | undefined, key: string, fallback: string): string;
|
|
57
|
+
export declare function setting(node: string | undefined, key: string): string | undefined;
|
|
58
|
+
/** Resolve and validate a service port (env override, per-node overridable). */
|
|
59
|
+
export declare function servicePort(service: ServiceDef, node?: string): number;
|
|
60
|
+
/** Basic-auth flag for AdGuard Home. */
|
|
61
|
+
export declare function adguardAuth(node?: string): string;
|
|
62
|
+
/** Bearer token (preferred) or basic-auth flag for Grafana. */
|
|
63
|
+
export declare function grafanaAuth(node?: string): string;
|
|
64
|
+
/** Log in to Nginx Proxy Manager and return an API token. */
|
|
65
|
+
export declare function getNpmToken(port: number, node?: string): Promise<string>;
|
|
66
|
+
export interface CurlErrorOptions {
|
|
67
|
+
/** Replaces the default HTTP-error (exit 22) message. */
|
|
68
|
+
httpError?: string;
|
|
69
|
+
}
|
|
70
|
+
/**
|
|
71
|
+
* Map curl failures to actionable messages: exit 7 (cannot connect),
|
|
72
|
+
* 22 (HTTP error), 28 (timeout), and unparseable JSON responses. Anything
|
|
73
|
+
* else goes through errorResponse unchanged.
|
|
74
|
+
*/
|
|
75
|
+
export declare function curlErrorResponse(error: unknown, service: ServiceDef, port: number, options?: CurlErrorOptions): {
|
|
76
|
+
content: {
|
|
77
|
+
type: "text";
|
|
78
|
+
text: string;
|
|
79
|
+
}[];
|
|
80
|
+
isError: true;
|
|
81
|
+
};
|
|
82
|
+
//# sourceMappingURL=service-http.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"service-http.d.ts","sourceRoot":"","sources":["../../src/utils/service-http.ts"],"names":[],"mappings":"AAQA,MAAM,WAAW,UAAU;IACzB,oDAAoD;IACpD,IAAI,EAAE,MAAM,CAAC;IACb,uCAAuC;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,uFAAuF;IACvF,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,eAAO,MAAM,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4BiB,CAAC;AAEvC,uEAAuE;AACvE,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC;AACzF,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;AAKnF,gFAAgF;AAChF,wBAAgB,WAAW,CAAC,OAAO,EAAE,UAAU,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAQtE;AAED,wCAAwC;AACxC,wBAAgB,WAAW,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAIjD;AAED,+DAA+D;AAC/D,wBAAgB,WAAW,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAWjD;AAED,6DAA6D;AAC7D,wBAAsB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAW9E;AAED,MAAM,WAAW,gBAAgB;IAC/B,yDAAyD;IACzD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,UAAU,EACnB,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,gBAAqB;;;;;;EAmC/B"}
|
|
@@ -0,0 +1,104 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Shared helpers for tools that call a service's HTTP API with curl on the
|
|
3
|
+
* node: port and credential lookup (per-node overridable via HOMELAB_NODES
|
|
4
|
+
* env), Nginx Proxy Manager login, and curl exit-code mapping.
|
|
5
|
+
*/
|
|
6
|
+
import { execSSH, errorResponse, nodeSetting } from "./ssh-api.js";
|
|
7
|
+
import { CommandFailedError } from "./errors.js";
|
|
8
|
+
export const SERVICES = {
|
|
9
|
+
adguard: {
|
|
10
|
+
name: "AdGuard Home",
|
|
11
|
+
portEnv: "HOMELAB_ADGUARD_PORT",
|
|
12
|
+
defaultPort: 3000,
|
|
13
|
+
authHint: "Check authentication -- set HOMELAB_ADGUARD_USER and HOMELAB_ADGUARD_PASSWORD. Also check the port: " +
|
|
14
|
+
"AdGuard Home and Grafana both default to 3000, so if Grafana uses it, " +
|
|
15
|
+
"set HOMELAB_ADGUARD_PORT to the AdGuard web UI port.",
|
|
16
|
+
},
|
|
17
|
+
grafana: {
|
|
18
|
+
name: "Grafana",
|
|
19
|
+
portEnv: "HOMELAB_GRAFANA_PORT",
|
|
20
|
+
defaultPort: 3000,
|
|
21
|
+
authHint: "Check authentication -- set HOMELAB_GRAFANA_TOKEN (API key) or HOMELAB_GRAFANA_USER/HOMELAB_GRAFANA_PASSWORD.",
|
|
22
|
+
},
|
|
23
|
+
npm: {
|
|
24
|
+
name: "Nginx Proxy Manager",
|
|
25
|
+
portEnv: "HOMELAB_NPM_PORT",
|
|
26
|
+
defaultPort: 81,
|
|
27
|
+
authHint: "Check authentication -- set HOMELAB_NPM_EMAIL and HOMELAB_NPM_PASSWORD.",
|
|
28
|
+
},
|
|
29
|
+
prometheus: { name: "Prometheus", portEnv: "HOMELAB_PROMETHEUS_PORT", defaultPort: 9090 },
|
|
30
|
+
alertmanager: { name: "Alertmanager", portEnv: "HOMELAB_ALERTMANAGER_PORT", defaultPort: 9093 },
|
|
31
|
+
uptimeKuma: { name: "Uptime Kuma", portEnv: "HOMELAB_UPTIME_KUMA_PORT", defaultPort: 3001 },
|
|
32
|
+
speedtest: { name: "Speedtest Tracker", portEnv: "HOMELAB_SPEEDTEST_PORT", defaultPort: 8765 },
|
|
33
|
+
ntfy: { name: "Ntfy", portEnv: "HOMELAB_NTFY_PORT", defaultPort: 8080 },
|
|
34
|
+
};
|
|
35
|
+
export function setting(node, key, fallback) {
|
|
36
|
+
return nodeSetting(node, key) ?? fallback;
|
|
37
|
+
}
|
|
38
|
+
/** Resolve and validate a service port (env override, per-node overridable). */
|
|
39
|
+
export function servicePort(service, node) {
|
|
40
|
+
const raw = nodeSetting(node, service.portEnv);
|
|
41
|
+
if (raw === undefined)
|
|
42
|
+
return service.defaultPort;
|
|
43
|
+
const port = Number(raw);
|
|
44
|
+
if (!Number.isInteger(port) || port < 1 || port > 65535) {
|
|
45
|
+
throw new Error(`${service.portEnv} must be a port number between 1 and 65535 (got "${raw}").`);
|
|
46
|
+
}
|
|
47
|
+
return port;
|
|
48
|
+
}
|
|
49
|
+
/** Basic-auth flag for AdGuard Home. */
|
|
50
|
+
export function adguardAuth(node) {
|
|
51
|
+
const user = setting(node, "HOMELAB_ADGUARD_USER", "admin");
|
|
52
|
+
const password = setting(node, "HOMELAB_ADGUARD_PASSWORD", "admin");
|
|
53
|
+
return `-u '${user}:${password}'`;
|
|
54
|
+
}
|
|
55
|
+
/** Bearer token (preferred) or basic-auth flag for Grafana. */
|
|
56
|
+
export function grafanaAuth(node) {
|
|
57
|
+
const token = setting(node, "HOMELAB_GRAFANA_TOKEN");
|
|
58
|
+
if (token) {
|
|
59
|
+
return `-H 'Authorization: Bearer ${token}'`;
|
|
60
|
+
}
|
|
61
|
+
const user = setting(node, "HOMELAB_GRAFANA_USER", "admin");
|
|
62
|
+
const password = setting(node, "HOMELAB_GRAFANA_PASSWORD");
|
|
63
|
+
if (password) {
|
|
64
|
+
return `-u '${user}:${password}'`;
|
|
65
|
+
}
|
|
66
|
+
return `-u 'admin:admin'`;
|
|
67
|
+
}
|
|
68
|
+
/** Log in to Nginx Proxy Manager and return an API token. */
|
|
69
|
+
export async function getNpmToken(port, node) {
|
|
70
|
+
const email = setting(node, "HOMELAB_NPM_EMAIL", "admin@example.com");
|
|
71
|
+
const password = setting(node, "HOMELAB_NPM_PASSWORD", "changeme");
|
|
72
|
+
const payload = JSON.stringify({ identity: email, secret: password });
|
|
73
|
+
const output = await execSSH(`curl -sf -X POST -H 'Content-Type: application/json' ` +
|
|
74
|
+
`-d '${payload}' 'http://localhost:${port}/api/tokens'`, node);
|
|
75
|
+
const parsed = JSON.parse(output);
|
|
76
|
+
return parsed.token;
|
|
77
|
+
}
|
|
78
|
+
/**
|
|
79
|
+
* Map curl failures to actionable messages: exit 7 (cannot connect),
|
|
80
|
+
* 22 (HTTP error), 28 (timeout), and unparseable JSON responses. Anything
|
|
81
|
+
* else goes through errorResponse unchanged.
|
|
82
|
+
*/
|
|
83
|
+
export function curlErrorResponse(error, service, port, options = {}) {
|
|
84
|
+
if (error instanceof CommandFailedError) {
|
|
85
|
+
if (error.exitCode === 7) {
|
|
86
|
+
return errorResponse(new Error(`Could not connect to ${service.name} on port ${port}. Is it running? ` +
|
|
87
|
+
`Set ${service.portEnv} if using a non-default port.`));
|
|
88
|
+
}
|
|
89
|
+
if (error.exitCode === 22) {
|
|
90
|
+
return errorResponse(new Error(options.httpError ??
|
|
91
|
+
`${service.name} on port ${port} returned an HTTP error.` +
|
|
92
|
+
(service.authHint ? ` ${service.authHint}` : "")));
|
|
93
|
+
}
|
|
94
|
+
if (error.exitCode === 28) {
|
|
95
|
+
return errorResponse(new Error(`${service.name} on port ${port} did not respond in time.`));
|
|
96
|
+
}
|
|
97
|
+
}
|
|
98
|
+
if (error instanceof SyntaxError) {
|
|
99
|
+
return errorResponse(new Error(`Unexpected (non-JSON) response from ${service.name} on port ${port}.` +
|
|
100
|
+
(service.authHint ? ` ${service.authHint}` : "")));
|
|
101
|
+
}
|
|
102
|
+
return errorResponse(error);
|
|
103
|
+
}
|
|
104
|
+
//# sourceMappingURL=service-http.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"service-http.js","sourceRoot":"","sources":["../../src/utils/service-http.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
import { z } from "zod";
|
|
2
|
+
/**
|
|
3
|
+
* Relative durations (30s, 10m, 2h, 7d) or an ISO 8601 date/time
|
|
4
|
+
* (2024-05-01, 2024-05-01T12:00, 2024-05-01T12:00:00Z).
|
|
5
|
+
*/
|
|
6
|
+
export declare const SINCE_RE: RegExp;
|
|
7
|
+
export declare function sinceSchema(description: string): z.ZodString;
|
|
8
|
+
/**
|
|
9
|
+
* Convert to a value `docker logs --since` accepts. Docker parses Go
|
|
10
|
+
* durations, which have no day unit, so "7d" becomes "168h".
|
|
11
|
+
*/
|
|
12
|
+
export declare function toDockerSince(since: string): string;
|
|
13
|
+
//# sourceMappingURL=since-param.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"since-param.d.ts","sourceRoot":"","sources":["../../src/utils/since-param.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;GAGG;AACH,eAAO,MAAM,QAAQ,QAC+D,CAAC;AAErF,wBAAgB,WAAW,CAAC,WAAW,EAAE,MAAM,eAK9C;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAGnD"}
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
import { z } from "zod";
|
|
2
|
+
/**
|
|
3
|
+
* Relative durations (30s, 10m, 2h, 7d) or an ISO 8601 date/time
|
|
4
|
+
* (2024-05-01, 2024-05-01T12:00, 2024-05-01T12:00:00Z).
|
|
5
|
+
*/
|
|
6
|
+
export const SINCE_RE = /^(\d{1,6}[smhd]|\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}(:\d{2})?(Z|[+-]\d{2}:?\d{2})?)?)$/;
|
|
7
|
+
export function sinceSchema(description) {
|
|
8
|
+
return z
|
|
9
|
+
.string()
|
|
10
|
+
.regex(SINCE_RE, "Use a duration like 30m, 2h, 7d or an ISO date like 2024-05-01T12:00:00Z")
|
|
11
|
+
.describe(description);
|
|
12
|
+
}
|
|
13
|
+
/**
|
|
14
|
+
* Convert to a value `docker logs --since` accepts. Docker parses Go
|
|
15
|
+
* durations, which have no day unit, so "7d" becomes "168h".
|
|
16
|
+
*/
|
|
17
|
+
export function toDockerSince(since) {
|
|
18
|
+
const days = /^(\d+)d$/.exec(since);
|
|
19
|
+
return days ? `${Number(days[1]) * 24}h` : since;
|
|
20
|
+
}
|
|
21
|
+
//# sourceMappingURL=since-param.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"since-param.js","sourceRoot":"","sources":["../../src/utils/since-param.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;GAGG;AACH,MAAM,CAAC,MAAM,QAAQ,GACnB,kFAAkF,CAAC;AAErF,MAAM,UAAU,WAAW,CAAC,WAAmB;IAC7C,OAAO,CAAC;SACL,MAAM,EAAE;SACR,KAAK,CAAC,QAAQ,EAAE,0EAA0E,CAAC;SAC3F,QAAQ,CAAC,WAAW,CAAC,CAAC;AAC3B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,KAAa;IACzC,MAAM,IAAI,GAAG,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACpC,OAAO,IAAI,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC;AACnD,CAAC"}
|
package/dist/utils/ssh-api.d.ts
CHANGED
|
@@ -1,15 +1,67 @@
|
|
|
1
1
|
export declare function assertCommandSafe(command: string): void;
|
|
2
|
-
|
|
2
|
+
/** Timeout budgets for tools that run long remote operations. */
|
|
3
|
+
export declare const TIMEOUTS: {
|
|
4
|
+
/** apt upgrade, compose pull, image scans, volume backups. */
|
|
5
|
+
readonly long: number;
|
|
6
|
+
/** restic backup/restore runs. */
|
|
7
|
+
readonly backup: number;
|
|
8
|
+
/** compose up/down, apt update, cert renewal, disk walks, log searches. */
|
|
9
|
+
readonly medium: number;
|
|
10
|
+
};
|
|
11
|
+
export interface ExecOptions {
|
|
12
|
+
/** Overall timeout (connect + command) in milliseconds. */
|
|
13
|
+
timeoutMs?: number;
|
|
14
|
+
}
|
|
15
|
+
/**
|
|
16
|
+
* Default exec timeout. HOMELAB_SSH_TIMEOUT_MS overrides the 30s default for
|
|
17
|
+
* tools that do not set their own budget.
|
|
18
|
+
*/
|
|
19
|
+
export declare function defaultExecTimeoutMs(): number;
|
|
20
|
+
export interface NodeConfig {
|
|
3
21
|
host: string;
|
|
4
22
|
username: string;
|
|
5
23
|
keyPath: string;
|
|
24
|
+
/** Per-node overrides for HOMELAB_* settings (compose dir, backup repo, ports, ...). */
|
|
25
|
+
env: Record<string, string>;
|
|
6
26
|
}
|
|
27
|
+
/**
|
|
28
|
+
* Resolve a HOMELAB_* setting for a node: the node's `env` override from
|
|
29
|
+
* HOMELAB_NODES first, then the process environment.
|
|
30
|
+
*/
|
|
31
|
+
export declare function nodeSetting(node: string | undefined, key: string): string | undefined;
|
|
7
32
|
export declare function getNodeConfig(node?: string): NodeConfig;
|
|
8
33
|
export declare function listNodes(): {
|
|
9
34
|
name: string;
|
|
10
35
|
host: string;
|
|
11
36
|
}[];
|
|
12
|
-
|
|
37
|
+
/**
|
|
38
|
+
* Expand a leading "~" to the user's home directory. MCP clients and CI
|
|
39
|
+
* runners pass env values literally (no shell), so "~/.ssh/id_ed25519"
|
|
40
|
+
* would otherwise be treated as a relative path.
|
|
41
|
+
*/
|
|
42
|
+
export declare function expandHome(p: string): string;
|
|
43
|
+
/** Read the private key, mapping file errors to a clear SSHAuthError. */
|
|
44
|
+
export declare function loadPrivateKey(keyPath: string): Buffer | undefined;
|
|
45
|
+
/** HOMELAB_DRY_RUN is enabled by "true", "1", "yes" or "on" (case-insensitive). */
|
|
46
|
+
export declare function isDryRun(): boolean;
|
|
47
|
+
/** Max bytes of stdout/stderr kept per command (HOMELAB_MAX_OUTPUT_BYTES, default 1 MiB). */
|
|
48
|
+
export declare function maxOutputBytes(): number;
|
|
49
|
+
/**
|
|
50
|
+
* Collects raw output chunks and keeps only the last `maxBytes` bytes.
|
|
51
|
+
* Decoding happens once at the end so multibyte UTF-8 characters split
|
|
52
|
+
* across chunks are not corrupted.
|
|
53
|
+
*/
|
|
54
|
+
export declare class TailBuffer {
|
|
55
|
+
private readonly maxBytes;
|
|
56
|
+
private chunks;
|
|
57
|
+
private size;
|
|
58
|
+
private total;
|
|
59
|
+
constructor(maxBytes: number);
|
|
60
|
+
push(chunk: Buffer): void;
|
|
61
|
+
get truncated(): boolean;
|
|
62
|
+
toString(): string;
|
|
63
|
+
}
|
|
64
|
+
export declare function execSSH(command: string, node?: string, options?: ExecOptions): Promise<string>;
|
|
13
65
|
export declare function checkSSHAvailable(): Promise<void>;
|
|
14
66
|
export declare function errorResponse(error: unknown): {
|
|
15
67
|
content: {
|
|
@@ -18,5 +70,4 @@ export declare function errorResponse(error: unknown): {
|
|
|
18
70
|
}[];
|
|
19
71
|
isError: true;
|
|
20
72
|
};
|
|
21
|
-
export {};
|
|
22
73
|
//# sourceMappingURL=ssh-api.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"ssh-api.d.ts","sourceRoot":"","sources":["../../src/utils/ssh-api.ts"],"names":[],"mappings":"
|
|
1
|
+
{"version":3,"file":"ssh-api.d.ts","sourceRoot":"","sources":["../../src/utils/ssh-api.ts"],"names":[],"mappings":"AAuBA,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAKvD;AAKD,iEAAiE;AACjE,eAAO,MAAM,QAAQ;IACnB,8DAA8D;;IAE9D,kCAAkC;;IAElC,2EAA2E;;CAEnE,CAAC;AAEX,MAAM,WAAW,WAAW;IAC1B,2DAA2D;IAC3D,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,CAK7C;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,wFAAwF;IACxF,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC7B;AAmCD;;;GAGG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAKrF;AA4CD,wBAAgB,aAAa,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,UAAU,CAavD;AAED,wBAAgB,SAAS,IAAI;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,EAAE,CAY5D;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAM5C;AAED,yEAAyE;AACzE,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAYlE;AAED,mFAAmF;AACnF,wBAAgB,QAAQ,IAAI,OAAO,CAGlC;AAID,6FAA6F;AAC7F,wBAAgB,cAAc,IAAI,MAAM,CAGvC;AAED;;;;GAIG;AACH,qBAAa,UAAU;IAKT,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAJrC,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,IAAI,CAAK;IACjB,OAAO,CAAC,KAAK,CAAK;gBAEW,QAAQ,EAAE,MAAM;IAE7C,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAiBzB,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED,QAAQ,IAAI,MAAM;CAWnB;AAED,wBAAsB,OAAO,CAC3B,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,MAAM,EACb,OAAO,GAAE,WAAgB,GACxB,OAAO,CAAC,MAAM,CAAC,CAiHjB;AAED,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC,CAMvD;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG;IAC7C,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC1C,OAAO,EAAE,IAAI,CAAC;CACf,CA4BA"}
|
package/dist/utils/ssh-api.js
CHANGED
|
@@ -1,4 +1,6 @@
|
|
|
1
1
|
import { readFileSync } from "node:fs";
|
|
2
|
+
import { homedir } from "node:os";
|
|
3
|
+
import { join } from "node:path";
|
|
2
4
|
import { Client } from "ssh2";
|
|
3
5
|
import { SSHError, SSHConnectionError, SSHAuthError, SSHTimeoutError, CommandFailedError, UnsafeCommandError, } from "./errors.js";
|
|
4
6
|
const DANGEROUS_PATTERNS = [
|
|
@@ -19,44 +21,117 @@ export function assertCommandSafe(command) {
|
|
|
19
21
|
}
|
|
20
22
|
}
|
|
21
23
|
const CONNECT_TIMEOUT_MS = 10_000;
|
|
22
|
-
const
|
|
24
|
+
const DEFAULT_EXEC_TIMEOUT_MS = 30_000;
|
|
25
|
+
/** Timeout budgets for tools that run long remote operations. */
|
|
26
|
+
export const TIMEOUTS = {
|
|
27
|
+
/** apt upgrade, compose pull, image scans, volume backups. */
|
|
28
|
+
long: 30 * 60_000,
|
|
29
|
+
/** restic backup/restore runs. */
|
|
30
|
+
backup: 60 * 60_000,
|
|
31
|
+
/** compose up/down, apt update, cert renewal, disk walks, log searches. */
|
|
32
|
+
medium: 5 * 60_000,
|
|
33
|
+
};
|
|
34
|
+
/**
|
|
35
|
+
* Default exec timeout. HOMELAB_SSH_TIMEOUT_MS overrides the 30s default for
|
|
36
|
+
* tools that do not set their own budget.
|
|
37
|
+
*/
|
|
38
|
+
export function defaultExecTimeoutMs() {
|
|
39
|
+
const raw = process.env.HOMELAB_SSH_TIMEOUT_MS;
|
|
40
|
+
if (!raw)
|
|
41
|
+
return DEFAULT_EXEC_TIMEOUT_MS;
|
|
42
|
+
const n = Number(raw);
|
|
43
|
+
return Number.isFinite(n) && n > 0 ? n : DEFAULT_EXEC_TIMEOUT_MS;
|
|
44
|
+
}
|
|
23
45
|
function getDefaultConfig() {
|
|
24
46
|
return {
|
|
25
47
|
host: process.env.HOMELAB_PI_HOST || "raspberrypi.local",
|
|
26
48
|
username: process.env.HOMELAB_PI_USER || "pi",
|
|
27
49
|
keyPath: process.env.HOMELAB_PI_KEY_PATH || "",
|
|
50
|
+
env: {},
|
|
28
51
|
};
|
|
29
52
|
}
|
|
30
|
-
function
|
|
31
|
-
|
|
32
|
-
|
|
53
|
+
function optionalString(value) {
|
|
54
|
+
return typeof value === "string" ? value : "";
|
|
55
|
+
}
|
|
56
|
+
const SETTING_KEY_RE = /^HOMELAB_[A-Z0-9_]+$/;
|
|
57
|
+
function parseNodeEnv(name, value) {
|
|
58
|
+
if (value === undefined)
|
|
33
59
|
return {};
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
};
|
|
60
|
+
if (typeof value !== "object" || value === null || Array.isArray(value)) {
|
|
61
|
+
throw new SSHError(`HOMELAB_NODES entry "${name}": "env" must be an object of HOMELAB_* settings.`);
|
|
62
|
+
}
|
|
63
|
+
const env = {};
|
|
64
|
+
for (const [key, v] of Object.entries(value)) {
|
|
65
|
+
if (!SETTING_KEY_RE.test(key)) {
|
|
66
|
+
throw new SSHError(`HOMELAB_NODES entry "${name}": env key "${key}" must look like HOMELAB_*.`);
|
|
67
|
+
}
|
|
68
|
+
if (typeof v !== "string" && typeof v !== "number") {
|
|
69
|
+
throw new SSHError(`HOMELAB_NODES entry "${name}": env value for ${key} must be a string or number.`);
|
|
44
70
|
}
|
|
71
|
+
env[key] = String(v);
|
|
72
|
+
}
|
|
73
|
+
return env;
|
|
74
|
+
}
|
|
75
|
+
/**
|
|
76
|
+
* Resolve a HOMELAB_* setting for a node: the node's `env` override from
|
|
77
|
+
* HOMELAB_NODES first, then the process environment.
|
|
78
|
+
*/
|
|
79
|
+
export function nodeSetting(node, key) {
|
|
80
|
+
const override = getNodeConfig(node).env[key];
|
|
81
|
+
if (override !== undefined && override !== "")
|
|
82
|
+
return override;
|
|
83
|
+
const value = process.env[key];
|
|
84
|
+
return value === undefined || value === "" ? undefined : value;
|
|
85
|
+
}
|
|
86
|
+
/**
|
|
87
|
+
* Parse HOMELAB_NODES. Invalid JSON or entries without a host raise an
|
|
88
|
+
* SSHError naming the problem instead of silently dropping every node.
|
|
89
|
+
*/
|
|
90
|
+
function getNodesRegistry() {
|
|
91
|
+
const registry = new Map();
|
|
92
|
+
const raw = process.env.HOMELAB_NODES;
|
|
93
|
+
if (!raw || !raw.trim())
|
|
45
94
|
return registry;
|
|
95
|
+
let parsed;
|
|
96
|
+
try {
|
|
97
|
+
parsed = JSON.parse(raw);
|
|
46
98
|
}
|
|
47
|
-
catch {
|
|
48
|
-
|
|
99
|
+
catch (err) {
|
|
100
|
+
const reason = err instanceof Error ? err.message : String(err);
|
|
101
|
+
throw new SSHError(`HOMELAB_NODES is not valid JSON (${reason}).`);
|
|
102
|
+
}
|
|
103
|
+
if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
|
|
104
|
+
throw new SSHError('HOMELAB_NODES must be a JSON object mapping node names to {"host", "user", "keyPath", "env"}.');
|
|
49
105
|
}
|
|
106
|
+
for (const [name, cfg] of Object.entries(parsed)) {
|
|
107
|
+
if (typeof cfg !== "object" || cfg === null || Array.isArray(cfg)) {
|
|
108
|
+
throw new SSHError(`HOMELAB_NODES entry "${name}" must be an object.`);
|
|
109
|
+
}
|
|
110
|
+
const c = cfg;
|
|
111
|
+
const host = optionalString(c.host).trim();
|
|
112
|
+
if (!host) {
|
|
113
|
+
throw new SSHError(`HOMELAB_NODES entry "${name}" is missing "host".`);
|
|
114
|
+
}
|
|
115
|
+
registry.set(name, {
|
|
116
|
+
host,
|
|
117
|
+
username: optionalString(c.user) || optionalString(c.username) || "pi",
|
|
118
|
+
keyPath: optionalString(c.keyPath),
|
|
119
|
+
env: parseNodeEnv(name, c.env),
|
|
120
|
+
});
|
|
121
|
+
}
|
|
122
|
+
return registry;
|
|
50
123
|
}
|
|
51
124
|
export function getNodeConfig(node) {
|
|
52
125
|
if (!node)
|
|
53
126
|
return getDefaultConfig();
|
|
54
127
|
const registry = getNodesRegistry();
|
|
55
|
-
|
|
56
|
-
|
|
128
|
+
const cfg = registry.get(node);
|
|
129
|
+
if (cfg)
|
|
130
|
+
return cfg;
|
|
57
131
|
if (node === "default")
|
|
58
132
|
return getDefaultConfig();
|
|
59
|
-
throw new SSHError(`Unknown node "${node}". Available nodes: ${listNodes().map((n) => n.name).join(", ")
|
|
133
|
+
throw new SSHError(`Unknown node "${node}". Available nodes: ${listNodes().map((n) => n.name).join(", ")}. ` +
|
|
134
|
+
"Add nodes via HOMELAB_NODES.");
|
|
60
135
|
}
|
|
61
136
|
export function listNodes() {
|
|
62
137
|
const defaultCfg = getDefaultConfig();
|
|
@@ -64,28 +139,135 @@ export function listNodes() {
|
|
|
64
139
|
{ name: "default", host: defaultCfg.host },
|
|
65
140
|
];
|
|
66
141
|
const registry = getNodesRegistry();
|
|
67
|
-
for (const [name, cfg] of
|
|
142
|
+
for (const [name, cfg] of registry) {
|
|
68
143
|
nodes.push({ name, host: cfg.host });
|
|
69
144
|
}
|
|
70
145
|
return nodes;
|
|
71
146
|
}
|
|
72
|
-
|
|
147
|
+
/**
|
|
148
|
+
* Expand a leading "~" to the user's home directory. MCP clients and CI
|
|
149
|
+
* runners pass env values literally (no shell), so "~/.ssh/id_ed25519"
|
|
150
|
+
* would otherwise be treated as a relative path.
|
|
151
|
+
*/
|
|
152
|
+
export function expandHome(p) {
|
|
153
|
+
if (p === "~")
|
|
154
|
+
return homedir();
|
|
155
|
+
if (p.startsWith("~/") || p.startsWith("~\\")) {
|
|
156
|
+
return join(homedir(), p.slice(2));
|
|
157
|
+
}
|
|
158
|
+
return p;
|
|
159
|
+
}
|
|
160
|
+
/** Read the private key, mapping file errors to a clear SSHAuthError. */
|
|
161
|
+
export function loadPrivateKey(keyPath) {
|
|
162
|
+
if (!keyPath)
|
|
163
|
+
return undefined;
|
|
164
|
+
const resolved = expandHome(keyPath);
|
|
165
|
+
try {
|
|
166
|
+
return readFileSync(resolved);
|
|
167
|
+
}
|
|
168
|
+
catch (err) {
|
|
169
|
+
const reason = err instanceof Error ? err.message : String(err);
|
|
170
|
+
throw new SSHAuthError(`Cannot read SSH private key at "${resolved}" (${reason}). ` +
|
|
171
|
+
"Check HOMELAB_PI_KEY_PATH (or keyPath in HOMELAB_NODES).");
|
|
172
|
+
}
|
|
173
|
+
}
|
|
174
|
+
/** HOMELAB_DRY_RUN is enabled by "true", "1", "yes" or "on" (case-insensitive). */
|
|
175
|
+
export function isDryRun() {
|
|
176
|
+
const raw = (process.env.HOMELAB_DRY_RUN ?? "").trim().toLowerCase();
|
|
177
|
+
return raw === "true" || raw === "1" || raw === "yes" || raw === "on";
|
|
178
|
+
}
|
|
179
|
+
const DEFAULT_MAX_OUTPUT_BYTES = 1024 * 1024;
|
|
180
|
+
/** Max bytes of stdout/stderr kept per command (HOMELAB_MAX_OUTPUT_BYTES, default 1 MiB). */
|
|
181
|
+
export function maxOutputBytes() {
|
|
182
|
+
const n = Number(process.env.HOMELAB_MAX_OUTPUT_BYTES);
|
|
183
|
+
return Number.isFinite(n) && n > 0 ? n : DEFAULT_MAX_OUTPUT_BYTES;
|
|
184
|
+
}
|
|
185
|
+
/**
|
|
186
|
+
* Collects raw output chunks and keeps only the last `maxBytes` bytes.
|
|
187
|
+
* Decoding happens once at the end so multibyte UTF-8 characters split
|
|
188
|
+
* across chunks are not corrupted.
|
|
189
|
+
*/
|
|
190
|
+
export class TailBuffer {
|
|
191
|
+
maxBytes;
|
|
192
|
+
chunks = [];
|
|
193
|
+
size = 0;
|
|
194
|
+
total = 0;
|
|
195
|
+
constructor(maxBytes) {
|
|
196
|
+
this.maxBytes = maxBytes;
|
|
197
|
+
}
|
|
198
|
+
push(chunk) {
|
|
199
|
+
this.chunks.push(chunk);
|
|
200
|
+
this.size += chunk.length;
|
|
201
|
+
this.total += chunk.length;
|
|
202
|
+
while (this.size > this.maxBytes && this.chunks.length > 0) {
|
|
203
|
+
const excess = this.size - this.maxBytes;
|
|
204
|
+
const first = this.chunks[0];
|
|
205
|
+
if (first.length <= excess) {
|
|
206
|
+
this.chunks.shift();
|
|
207
|
+
this.size -= first.length;
|
|
208
|
+
}
|
|
209
|
+
else {
|
|
210
|
+
this.chunks[0] = first.subarray(excess);
|
|
211
|
+
this.size -= excess;
|
|
212
|
+
}
|
|
213
|
+
}
|
|
214
|
+
}
|
|
215
|
+
get truncated() {
|
|
216
|
+
return this.total > this.size;
|
|
217
|
+
}
|
|
218
|
+
toString() {
|
|
219
|
+
let buf = Buffer.concat(this.chunks);
|
|
220
|
+
if (this.truncated) {
|
|
221
|
+
// Skip UTF-8 continuation bytes left over from the cut.
|
|
222
|
+
let start = 0;
|
|
223
|
+
while (start < buf.length && start < 4 && (buf[start] & 0xc0) === 0x80)
|
|
224
|
+
start++;
|
|
225
|
+
buf = buf.subarray(start);
|
|
226
|
+
return `[output truncated: showing last ${buf.length} of ${this.total} bytes]\n` + buf.toString("utf8");
|
|
227
|
+
}
|
|
228
|
+
return buf.toString("utf8");
|
|
229
|
+
}
|
|
230
|
+
}
|
|
231
|
+
export async function execSSH(command, node, options = {}) {
|
|
232
|
+
const timeoutMs = options.timeoutMs ?? defaultExecTimeoutMs();
|
|
73
233
|
assertCommandSafe(command);
|
|
74
|
-
if (
|
|
234
|
+
if (isDryRun()) {
|
|
75
235
|
const cfg = getNodeConfig(node);
|
|
76
236
|
return `[dry-run] would execute on ${cfg.host}: ${command}`;
|
|
77
237
|
}
|
|
78
238
|
const { host, username, keyPath } = getNodeConfig(node);
|
|
239
|
+
// Read the key before arming the timer so a bad path fails fast and
|
|
240
|
+
// does not leave a pending timeout behind.
|
|
241
|
+
const privateKey = loadPrivateKey(keyPath);
|
|
79
242
|
return new Promise((resolve, reject) => {
|
|
80
243
|
const conn = new Client();
|
|
81
|
-
|
|
82
|
-
|
|
244
|
+
const maxBytes = maxOutputBytes();
|
|
245
|
+
const stdout = new TailBuffer(maxBytes);
|
|
246
|
+
const stderr = new TailBuffer(maxBytes);
|
|
83
247
|
let timedOut = false;
|
|
248
|
+
let started = false;
|
|
249
|
+
let activeStream = null;
|
|
84
250
|
const timer = setTimeout(() => {
|
|
85
251
|
timedOut = true;
|
|
252
|
+
if (activeStream) {
|
|
253
|
+
// Best effort: ask the remote side to terminate the command before
|
|
254
|
+
// dropping the connection. Not every SSH server honors signals.
|
|
255
|
+
try {
|
|
256
|
+
activeStream.signal?.("TERM");
|
|
257
|
+
}
|
|
258
|
+
catch {
|
|
259
|
+
// ignore
|
|
260
|
+
}
|
|
261
|
+
try {
|
|
262
|
+
activeStream.close?.();
|
|
263
|
+
}
|
|
264
|
+
catch {
|
|
265
|
+
// ignore
|
|
266
|
+
}
|
|
267
|
+
}
|
|
86
268
|
conn.end();
|
|
87
|
-
reject(new SSHTimeoutError(
|
|
88
|
-
},
|
|
269
|
+
reject(new SSHTimeoutError(timeoutMs, started));
|
|
270
|
+
}, timeoutMs);
|
|
89
271
|
conn
|
|
90
272
|
.on("ready", () => {
|
|
91
273
|
conn.exec(command, (err, stream) => {
|
|
@@ -94,24 +276,31 @@ export async function execSSH(command, node) {
|
|
|
94
276
|
conn.end();
|
|
95
277
|
return reject(new SSHError(err.message, command));
|
|
96
278
|
}
|
|
279
|
+
started = true;
|
|
280
|
+
activeStream = stream;
|
|
97
281
|
stream
|
|
98
|
-
.on("close", (code) => {
|
|
282
|
+
.on("close", (code, signal) => {
|
|
99
283
|
clearTimeout(timer);
|
|
100
284
|
conn.end();
|
|
101
285
|
if (timedOut)
|
|
102
286
|
return;
|
|
103
|
-
if (
|
|
104
|
-
|
|
287
|
+
if (signal) {
|
|
288
|
+
// Killed by a signal (for example the OOM killer): partial
|
|
289
|
+
// output must not be reported as success.
|
|
290
|
+
reject(new CommandFailedError(command, -1, `${stderr.toString().trim()}\nRemote command terminated by signal ${signal}`.trim()));
|
|
291
|
+
}
|
|
292
|
+
else if (code !== 0 && code !== null && code !== undefined) {
|
|
293
|
+
reject(new CommandFailedError(command, code, stderr.toString()));
|
|
105
294
|
}
|
|
106
295
|
else {
|
|
107
|
-
resolve(stdout.trim());
|
|
296
|
+
resolve(stdout.toString().trim());
|
|
108
297
|
}
|
|
109
298
|
})
|
|
110
299
|
.on("data", (data) => {
|
|
111
|
-
stdout
|
|
300
|
+
stdout.push(data);
|
|
112
301
|
})
|
|
113
302
|
.stderr.on("data", (data) => {
|
|
114
|
-
stderr
|
|
303
|
+
stderr.push(data);
|
|
115
304
|
});
|
|
116
305
|
});
|
|
117
306
|
})
|
|
@@ -137,7 +326,7 @@ export async function execSSH(command, node) {
|
|
|
137
326
|
host,
|
|
138
327
|
port: 22,
|
|
139
328
|
username,
|
|
140
|
-
privateKey
|
|
329
|
+
privateKey,
|
|
141
330
|
agent: process.env.SSH_AUTH_SOCK,
|
|
142
331
|
readyTimeout: CONNECT_TIMEOUT_MS,
|
|
143
332
|
});
|