@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.
Files changed (140) hide show
  1. package/README.md +9 -4
  2. package/dist/index.js +1 -1
  3. package/dist/tools/adguardFilters.d.ts.map +1 -1
  4. package/dist/tools/adguardFilters.js +7 -26
  5. package/dist/tools/adguardFilters.js.map +1 -1
  6. package/dist/tools/adguardQueryLog.d.ts.map +1 -1
  7. package/dist/tools/adguardQueryLog.js +8 -26
  8. package/dist/tools/adguardQueryLog.js.map +1 -1
  9. package/dist/tools/adguardStats.d.ts.map +1 -1
  10. package/dist/tools/adguardStats.js +7 -26
  11. package/dist/tools/adguardStats.js.map +1 -1
  12. package/dist/tools/alertList.d.ts +5 -0
  13. package/dist/tools/alertList.d.ts.map +1 -1
  14. package/dist/tools/alertList.js +16 -17
  15. package/dist/tools/alertList.js.map +1 -1
  16. package/dist/tools/aptHistory.d.ts +6 -0
  17. package/dist/tools/aptHistory.d.ts.map +1 -1
  18. package/dist/tools/aptHistory.js +14 -4
  19. package/dist/tools/aptHistory.js.map +1 -1
  20. package/dist/tools/aptUpdate.d.ts.map +1 -1
  21. package/dist/tools/aptUpdate.js +20 -5
  22. package/dist/tools/aptUpdate.js.map +1 -1
  23. package/dist/tools/backupDiff.d.ts.map +1 -1
  24. package/dist/tools/backupDiff.js +2 -1
  25. package/dist/tools/backupDiff.js.map +1 -1
  26. package/dist/tools/backupList.d.ts.map +1 -1
  27. package/dist/tools/backupList.js +7 -4
  28. package/dist/tools/backupList.js.map +1 -1
  29. package/dist/tools/backupRestore.d.ts.map +1 -1
  30. package/dist/tools/backupRestore.js +4 -3
  31. package/dist/tools/backupRestore.js.map +1 -1
  32. package/dist/tools/backupRun.d.ts.map +1 -1
  33. package/dist/tools/backupRun.js +10 -2
  34. package/dist/tools/backupRun.js.map +1 -1
  35. package/dist/tools/backupStatus.d.ts.map +1 -1
  36. package/dist/tools/backupStatus.js +8 -4
  37. package/dist/tools/backupStatus.js.map +1 -1
  38. package/dist/tools/certList.d.ts.map +1 -1
  39. package/dist/tools/certList.js +25 -18
  40. package/dist/tools/certList.js.map +1 -1
  41. package/dist/tools/certRenew.js +2 -2
  42. package/dist/tools/certRenew.js.map +1 -1
  43. package/dist/tools/composeDown.d.ts.map +1 -1
  44. package/dist/tools/composeDown.js +3 -10
  45. package/dist/tools/composeDown.js.map +1 -1
  46. package/dist/tools/composePs.d.ts.map +1 -1
  47. package/dist/tools/composePs.js +2 -2
  48. package/dist/tools/composePs.js.map +1 -1
  49. package/dist/tools/composePull.d.ts.map +1 -1
  50. package/dist/tools/composePull.js +3 -10
  51. package/dist/tools/composePull.js.map +1 -1
  52. package/dist/tools/composeUp.d.ts.map +1 -1
  53. package/dist/tools/composeUp.js +5 -11
  54. package/dist/tools/composeUp.js.map +1 -1
  55. package/dist/tools/containerScan.d.ts.map +1 -1
  56. package/dist/tools/containerScan.js +14 -6
  57. package/dist/tools/containerScan.js.map +1 -1
  58. package/dist/tools/diagnostics.d.ts +5 -0
  59. package/dist/tools/diagnostics.d.ts.map +1 -1
  60. package/dist/tools/diagnostics.js +26 -19
  61. package/dist/tools/diagnostics.js.map +1 -1
  62. package/dist/tools/diskUsage.d.ts.map +1 -1
  63. package/dist/tools/diskUsage.js +4 -3
  64. package/dist/tools/diskUsage.js.map +1 -1
  65. package/dist/tools/grafanaSnapshot.d.ts.map +1 -1
  66. package/dist/tools/grafanaSnapshot.js +11 -34
  67. package/dist/tools/grafanaSnapshot.js.map +1 -1
  68. package/dist/tools/healthCheck.d.ts +8 -0
  69. package/dist/tools/healthCheck.d.ts.map +1 -1
  70. package/dist/tools/healthCheck.js +56 -21
  71. package/dist/tools/healthCheck.js.map +1 -1
  72. package/dist/tools/journalLogs.d.ts.map +1 -1
  73. package/dist/tools/journalLogs.js +1 -0
  74. package/dist/tools/journalLogs.js.map +1 -1
  75. package/dist/tools/logSearch.d.ts.map +1 -1
  76. package/dist/tools/logSearch.js +20 -6
  77. package/dist/tools/logSearch.js.map +1 -1
  78. package/dist/tools/nodeList.d.ts.map +1 -1
  79. package/dist/tools/nodeList.js +22 -11
  80. package/dist/tools/nodeList.js.map +1 -1
  81. package/dist/tools/npmCerts.d.ts.map +1 -1
  82. package/dist/tools/npmCerts.js +6 -38
  83. package/dist/tools/npmCerts.js.map +1 -1
  84. package/dist/tools/npmProxyHosts.d.ts.map +1 -1
  85. package/dist/tools/npmProxyHosts.js +6 -38
  86. package/dist/tools/npmProxyHosts.js.map +1 -1
  87. package/dist/tools/ntfySend.d.ts.map +1 -1
  88. package/dist/tools/ntfySend.js +6 -16
  89. package/dist/tools/ntfySend.js.map +1 -1
  90. package/dist/tools/ntfyTopics.d.ts +4 -0
  91. package/dist/tools/ntfyTopics.d.ts.map +1 -1
  92. package/dist/tools/ntfyTopics.js +26 -17
  93. package/dist/tools/ntfyTopics.js.map +1 -1
  94. package/dist/tools/prometheusQuery.d.ts.map +1 -1
  95. package/dist/tools/prometheusQuery.js +8 -16
  96. package/dist/tools/prometheusQuery.js.map +1 -1
  97. package/dist/tools/serviceLogs.d.ts.map +1 -1
  98. package/dist/tools/serviceLogs.js +5 -1
  99. package/dist/tools/serviceLogs.js.map +1 -1
  100. package/dist/tools/speedtestResults.d.ts.map +1 -1
  101. package/dist/tools/speedtestResults.js +7 -16
  102. package/dist/tools/speedtestResults.js.map +1 -1
  103. package/dist/tools/sshTest.js +4 -4
  104. package/dist/tools/sshTest.js.map +1 -1
  105. package/dist/tools/uptimeKumaStatus.d.ts +4 -0
  106. package/dist/tools/uptimeKumaStatus.d.ts.map +1 -1
  107. package/dist/tools/uptimeKumaStatus.js +30 -16
  108. package/dist/tools/uptimeKumaStatus.js.map +1 -1
  109. package/dist/tools/volumeBackup.d.ts.map +1 -1
  110. package/dist/tools/volumeBackup.js +4 -3
  111. package/dist/tools/volumeBackup.js.map +1 -1
  112. package/dist/utils/compose.d.ts +27 -0
  113. package/dist/utils/compose.d.ts.map +1 -0
  114. package/dist/utils/compose.js +92 -0
  115. package/dist/utils/compose.js.map +1 -0
  116. package/dist/utils/config.d.ts +4 -0
  117. package/dist/utils/config.d.ts.map +1 -0
  118. package/dist/utils/config.js +7 -0
  119. package/dist/utils/config.js.map +1 -0
  120. package/dist/utils/errors.d.ts +2 -2
  121. package/dist/utils/errors.d.ts.map +1 -1
  122. package/dist/utils/errors.js +8 -4
  123. package/dist/utils/errors.js.map +1 -1
  124. package/dist/utils/restic.d.ts +13 -0
  125. package/dist/utils/restic.d.ts.map +1 -0
  126. package/dist/utils/restic.js +21 -0
  127. package/dist/utils/restic.js.map +1 -0
  128. package/dist/utils/service-http.d.ts +82 -0
  129. package/dist/utils/service-http.d.ts.map +1 -0
  130. package/dist/utils/service-http.js +104 -0
  131. package/dist/utils/service-http.js.map +1 -0
  132. package/dist/utils/since-param.d.ts +13 -0
  133. package/dist/utils/since-param.d.ts.map +1 -0
  134. package/dist/utils/since-param.js +21 -0
  135. package/dist/utils/since-param.js.map +1 -0
  136. package/dist/utils/ssh-api.d.ts +54 -3
  137. package/dist/utils/ssh-api.d.ts.map +1 -1
  138. package/dist/utils/ssh-api.js +222 -33
  139. package/dist/utils/ssh-api.js.map +1 -1
  140. 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"}
@@ -1,15 +1,67 @@
1
1
  export declare function assertCommandSafe(command: string): void;
2
- interface NodeConfig {
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
- export declare function execSSH(command: string, node?: string): Promise<string>;
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":"AAqBA,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAKvD;AAKD,UAAU,UAAU;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CACjB;AA+BD,wBAAgB,aAAa,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,UAAU,CASvD;AAED,wBAAgB,SAAS,IAAI;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,EAAE,CAY5D;AAED,wBAAsB,OAAO,CAC3B,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,MAAM,GACZ,OAAO,CAAC,MAAM,CAAC,CAgFjB;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"}
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"}
@@ -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 EXEC_TIMEOUT_MS = 30_000;
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 getNodesRegistry() {
31
- const raw = process.env.HOMELAB_NODES;
32
- if (!raw)
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
- try {
35
- const parsed = JSON.parse(raw);
36
- const registry = {};
37
- for (const [name, cfg] of Object.entries(parsed)) {
38
- const c = cfg;
39
- registry[name] = {
40
- host: c.host || "",
41
- username: c.user || c.username || "pi",
42
- keyPath: c.keyPath || "",
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
- return {};
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
- if (registry[node])
56
- return registry[node];
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(", ") || "(none -- set HOMELAB_NODES)"}`);
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 Object.entries(registry)) {
142
+ for (const [name, cfg] of registry) {
68
143
  nodes.push({ name, host: cfg.host });
69
144
  }
70
145
  return nodes;
71
146
  }
72
- export async function execSSH(command, node) {
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 (process.env.HOMELAB_DRY_RUN && process.env.HOMELAB_DRY_RUN !== "false") {
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
- let stdout = "";
82
- let stderr = "";
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(EXEC_TIMEOUT_MS));
88
- }, EXEC_TIMEOUT_MS);
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 (code !== 0 && code !== null) {
104
- reject(new CommandFailedError(command, code, stderr));
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 += data.toString();
300
+ stdout.push(data);
112
301
  })
113
302
  .stderr.on("data", (data) => {
114
- stderr += data.toString();
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: keyPath ? readFileSync(keyPath) : undefined,
329
+ privateKey,
141
330
  agent: process.env.SSH_AUTH_SOCK,
142
331
  readyTimeout: CONNECT_TIMEOUT_MS,
143
332
  });