Open History to see the last commit
1import * as NodeUtil from "node:util";
2
3import * as HostProcess from "@t3tools/shared/HostProcess";
4import * as Console from "effect/Console";
5import * as Effect from "effect/Effect";
6import * as FileSystem from "effect/FileSystem";
7import * as Layer from "effect/Layer";
8import * as Path from "effect/Path";
9import { Command, Flag, GlobalFlag, Prompt } from "effect/cli";
10import { FetchHttpClient } from "effect/http";
11
12import packageJson from "../../package.json" with { type: "json" };
13import * as BootService from "../cloud/bootService.ts";
14import * as ServiceProtection from "../cloud/serviceProtection.ts";
15import { compareExactServiceVersions, SERVICE_ENV_FILE } from "../cloud/serviceProtocol.ts";
16import * as ServerConfig from "../config.ts";
17import * as ProcessRunner from "../processRunner.ts";
18import { projectLocationFlags, resolveCliAuthConfig } from "./config.ts";
19import { resolveEntryPath } from "./invocation.ts";
20
21export const layer = (config: ServerConfig.ServerConfig["Service"]) =>
22 BootService.layer({
23 baseDir: config.baseDir,
24 logsDir: config.logsDir,
25 cliVersion: packageJson.version,
26 }).pipe(Layer.provide(ProcessRunner.layer), Layer.provide(FetchHttpClient.layer));
27
28export type ServiceReconcileResult =
29 | {
30 readonly changed: false;
31 readonly status: BootService.BootServiceStatus;
32 }
33 | {
34 readonly changed: true;
35 readonly previouslyInstalled: boolean;
36 readonly plan: BootService.BootServicePlan;
37 };
38
39const SERVICE_ENV_KEY = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/u;
40
41/**
42 * Sets or removes (`undefined`) entries in `service.env` text and keeps every
43 * other line, including comments, as the user wrote it.
44 */
45export const upsertServiceEnv = (
46 contents: string,
47 entries: Readonly<Record<string, string | undefined>>,
48): string => {
49 const written = new Set<string>();
50 const lines = contents.split("\n").flatMap((line) => {
51 const key = SERVICE_ENV_KEY.exec(line)?.[1];
52 if (key === undefined || !Object.hasOwn(entries, key)) return [line];
53 const value = entries[key];
54 if (value === undefined || written.has(key)) return [];
55 written.add(key);
56 return [`${key}=${value}`];
57 });
58 while (lines.at(-1) === "") lines.pop();
59 for (const [key, value] of Object.entries(entries)) {
60 if (value !== undefined && !written.has(key)) lines.push(`${key}=${value}`);
61 }
62 return lines.length === 0 ? "" : `${lines.join("\n")}\n`;
63};
64
65/** `service.env` under `baseDir`, parsed as the service launcher parses it. */
66export const readServiceEnv = Effect.fn("cli.service.read_env")(function* (baseDir: string) {
67 const fs = yield* FileSystem.FileSystem;
68 const path = (yield* Path.Path).join(baseDir, SERVICE_ENV_FILE);
69 const contents = (yield* fs.exists(path)) ? yield* fs.readFileString(path) : "";
70 const entries = Object.entries(NodeUtil.parseEnv(contents)).flatMap(([key, value]) =>
71 value === undefined ? [] : [[key, value] as const],
72 );
73 return { path, contents, entries: Object.fromEntries(entries) };
74});
75
76export const writeServiceEnv = Effect.fn("cli.service.write_env")(function* (
77 baseDir: string,
78 entries: Readonly<Record<string, string | undefined>>,
79) {
80 const fs = yield* FileSystem.FileSystem;
81 const current = yield* readServiceEnv(baseDir);
82 const next = upsertServiceEnv(current.contents, entries);
83 if (next === current.contents) return;
84 yield* fs.makeDirectory(baseDir, { recursive: true });
85 yield* fs.writeFileString(current.path, next);
86});
87
88export const reconcileService = Effect.fn("cli.service.reconcile")(function* (options?: {
89 readonly allowDowngrade?: boolean;
90 readonly start?: boolean;
91}) {
92 const { baseDir } = yield* ServerConfig.ServerConfig;
93 const service = yield* BootService.BootService;
94 const status = yield* service.status;
95 // Before the downgrade check, which reads this home's state, not the service's.
96 if (status.otherBaseDir !== undefined) {
97 return yield* new BootService.BootServiceOtherBaseDirError({
98 installedBaseDir: status.otherBaseDir,
99 baseDir,
100 });
101 }
102 if (status.installed && status.current) {
103 return { changed: false, status } satisfies ServiceReconcileResult;
104 }
105 if (status.supported && !status.installed) {
106 // A new service listens on this machine only, until `t3 up` opens the local network.
107 const { entries } = yield* readServiceEnv(baseDir);
108 if (entries.T3CODE_LAN === undefined && entries.T3CODE_HOST === undefined) {
109 yield* writeServiceEnv(baseDir, { T3CODE_LAN: "false" });
110 }
111 }
112 if (
113 status.installedVersion !== undefined &&
114 options?.allowDowngrade !== true &&
115 compareExactServiceVersions(packageJson.version, status.installedVersion) < 0
116 ) {
117 return yield* new BootService.BootServiceDowngradeRefusedError({
118 installedVersion: status.installedVersion,
119 targetVersion: packageJson.version,
120 });
121 }
122 const plan = yield* service.install(options);
123 return {
124 changed: true,
125 previouslyInstalled: status.installed,
126 plan,
127 } satisfies ServiceReconcileResult;
128});
129
130export function formatServiceChange(
131 result: Extract<ServiceReconcileResult, { readonly changed: true }>,
132): string {
133 if (result.plan.handedOff === true) {
134 return `Service update to t3@${packageJson.version} queued. This session will disconnect.\nLog: ${result.plan.logPath}`;
135 }
136 return `Service ${result.previouslyInstalled ? "updated" : "installed"} · t3@${packageJson.version}\nLog: ${result.plan.logPath}`;
137}
138
139function formatProtection(
140 protection: ServiceProtection.ServiceProtectionState | undefined,
141): ReadonlyArray<string> {
142 if (protection === undefined) return [];
143 return [
144 protection.unprotected === undefined
145 ? ` Memory protection: on${protection.setByProtect ? " (t3 service protect)" : ""}`
146 : ` Memory protection: off, ${protection.unprotected} grants none. Run \`t3 service protect\`.`,
147 ...(protection.oomScoreAdj === undefined ? [] : [` OOM score: ${protection.oomScoreAdj}`]),
148 ];
149}
150
151function formatServiceStatus(
152 status: BootService.BootServiceStatus,
153 cliVersion: string,
154 protection?: ServiceProtection.ServiceProtectionState,
155): string {
156 if (!status.supported) {
157 return "T3 Code service\n Status: unavailable on this machine\n Supported on: Linux with systemd, macOS with launchd, Windows with Task Scheduler";
158 }
159 if (!status.installed) {
160 return "T3 Code service\n Status: not installed\n Next: Run `t3 service install`.";
161 }
162 if (status.otherBaseDir !== undefined) {
163 return [
164 "T3 Code service",
165 " Status: installed for another T3 home",
166 ` Base dir: ${status.otherBaseDir}`,
167 ` Next: Pass \`${BootService.formatBootServiceBaseDirOption(status.otherBaseDir)}\` to manage it.`,
168 ].join("\n");
169 }
170 const installedVersion = status.installedVersion ?? cliVersion;
171 const problems = (status.problems ?? []).map(
172 (problem) => ` [${problem}] ${BootService.formatBootServiceProblem(problem)}`,
173 );
174 if (
175 !status.current &&
176 status.installedVersion !== undefined &&
177 compareExactServiceVersions(status.installedVersion, cliVersion) > 0
178 ) {
179 return [
180 "T3 Code service",
181 ` Status: installed · t3@${installedVersion} (newer than this t3@${cliVersion} CLI)`,
182 ` Unit: ${status.unitPath}`,
183 ` Logs: ${status.logPath}`,
184 ...formatProtection(protection),
185 ...problems,
186 ` Next: Run \`t3 update ${installedVersion}\` to match it, or pass \`--allow-downgrade\` to \`t3 service install\` explicitly.`,
187 ].join("\n");
188 }
189 return [
190 "T3 Code service",
191 ` Status: ${status.current ? `installed · t3@${installedVersion}` : "needs an update or repair"}`,
192 ` Unit: ${status.unitPath}`,
193 ` Logs: ${status.logPath}`,
194 ...formatProtection(protection),
195 ...problems,
196 ...(status.current ? [] : [" Next: Run `t3 service install` to repair it."]),
197 ].join("\n");
198}
199
200const runServiceCommand = Effect.fn("cli.service.run")(function* <A, E, R>(
201 flags: { readonly baseDir: Parameters<typeof resolveCliAuthConfig>[0]["baseDir"] },
202 run: Effect.Effect<A, E, R>,
203) {
204 const logLevel = yield* GlobalFlag.LogLevel;
205 const config = yield* resolveCliAuthConfig(flags, logLevel);
206 return yield* run.pipe(Effect.provide(Layer.merge(layer(config), ServerConfig.layer(config))));
207});
208
209const serviceReconcileFlags = {
210 ...projectLocationFlags,
211 allowDowngrade: Flag.Boolean("allow-downgrade").pipe(
212 Flag.withDescription("Allow replacing a newer installed service with this older CLI version."),
213 Flag.withDefault(false),
214 ),
215};
216
217const serviceInstallCommand = Command.make("install", serviceReconcileFlags).pipe(
218 Command.withDescription(
219 "Install T3 Code as a background service for this user. `t3 up` also chooses how your other devices reach it.",
220 ),
221 Command.withHandler((flags) =>
222 runServiceCommand(
223 flags,
224 Effect.gen(function* () {
225 const result = yield* reconcileService({ allowDowngrade: flags.allowDowngrade });
226 if (!result.changed) {
227 yield* Console.log(
228 `T3 Code service is already installed with t3@${packageJson.version} (${yield* resolveEntryPath}).`,
229 );
230 return;
231 }
232 yield* Console.log(formatServiceChange(result));
233 if (!result.previouslyInstalled) {
234 yield* Console.log("Run `t3 up` to choose how your other devices reach it.");
235 }
236 }),
237 ),
238 ),
239);
240
241const serviceUpdateCommand = Command.make("update", serviceReconcileFlags).pipe(
242 Command.withDescription("Deprecated. Run `t3 update` to move to a newer release."),
243 Command.unlisted,
244 Command.withHandler((flags) =>
245 runServiceCommand(
246 flags,
247 Effect.gen(function* () {
248 yield* Console.log(
249 "`t3 service update` is deprecated: run `t3 update` to move to a newer release, or `t3 service install` to repair the service. Repairing now.",
250 );
251 const result = yield* reconcileService({ allowDowngrade: flags.allowDowngrade });
252 if (!result.changed) {
253 yield* Console.log(
254 `T3 Code service is already using t3@${packageJson.version} (${yield* resolveEntryPath}).`,
255 );
256 return;
257 }
258 yield* Console.log(formatServiceChange(result));
259 }),
260 ),
261 ),
262);
263
264const serviceRestartCommand = Command.make("restart", projectLocationFlags).pipe(
265 Command.withDescription(
266 "Restart the background service. Picks up a version installed by `t3 update` that was not restarted at the time.",
267 ),
268 Command.withHandler((flags) =>
269 runServiceCommand(
270 flags,
271 Effect.gen(function* () {
272 const service = yield* BootService.BootService;
273 const status = yield* service.status;
274 const outcome = yield* service.restart;
275 const onVersion =
276 status.installedVersion === undefined ? "" : ` on t3@${status.installedVersion}`;
277 yield* Console.log(
278 outcome === "restarted"
279 ? `Restarted the T3 Code service${onVersion}.`
280 : outcome === "queued"
281 ? `Queued a restart of the T3 Code service${onVersion}. This session runs inside the service and disconnects when it goes down.\nLogs: ${status.logPath}`
282 : status.otherBaseDir !== undefined
283 ? `The T3 Code service serves ${status.otherBaseDir}, so it was not restarted. Pass \`${BootService.formatBootServiceBaseDirOption(status.otherBaseDir)}\` to restart it.`
284 : "T3 Code service is not installed.",
285 );
286 }),
287 ),
288 ),
289);
290
291const serviceUninstallCommand = Command.make("uninstall", projectLocationFlags).pipe(
292 Command.withDescription("Stop and remove the T3 Code background service."),
293 Command.withHandler((flags) =>
294 runServiceCommand(
295 flags,
296 Effect.gen(function* () {
297 const service = yield* BootService.BootService;
298 const path = yield* Path.Path;
299 const { baseDir } = yield* ServerConfig.ServerConfig;
300 // An unreadable unit stays removable; only a unit known to serve another home is kept.
301 const installedBaseDir = yield* service.status.pipe(
302 Effect.map((status) => status.installedBaseDir),
303 Effect.orElseSucceed(() => undefined),
304 );
305 if (
306 installedBaseDir !== undefined &&
307 path.resolve(installedBaseDir) !== path.resolve(baseDir)
308 ) {
309 yield* Console.log(
310 `The T3 Code service serves ${installedBaseDir}, so it was not removed. Pass \`${BootService.formatBootServiceBaseDirOption(installedBaseDir)}\` to remove it.`,
311 );
312 return;
313 }
314 const removed = yield* service.uninstall;
315 yield* Console.log(
316 removed ? "Removed the T3 Code service." : "T3 Code service is not installed.",
317 );
318 }),
319 ),
320 ),
321);
322
323const serviceStatusCommand = Command.make("status", projectLocationFlags).pipe(
324 Command.withDescription("Show whether the T3 Code background service is installed."),
325 Command.withHandler((flags) =>
326 runServiceCommand(
327 flags,
328 Effect.gen(function* () {
329 const service = yield* BootService.BootService;
330 const path = yield* Path.Path;
331 const status = yield* service.status;
332 const protection =
333 status.installed && (yield* HostProcess.Platform) === "linux"
334 ? yield* ServiceProtection.readProtection(path.dirname(status.unitPath)).pipe(
335 Effect.provide(ProcessRunner.layer),
336 )
337 : undefined;
338 yield* Console.log(formatServiceStatus(status, packageJson.version, protection));
339 }),
340 ),
341 ),
342);
343
344const formatDropIns = (dropIns: ReadonlyArray<ServiceProtection.DropIn>) =>
345 dropIns.map(
346 ({ path, contents }) => ` ${path}: ${contents.trimEnd().split("\n").slice(1).join(" ")}`,
347 );
348
349const confirm = (yes: boolean, message: string) =>
350 yes ? Effect.succeed(true) : Prompt.run(Prompt.Confirm({ message, initial: false }));
351
352const serviceProtectCommand = Command.make("protect", {
353 ...projectLocationFlags,
354 undo: Flag.Boolean("undo").pipe(
355 Flag.withDescription("Remove the protection this command set up."),
356 Flag.withDefault(false),
357 ),
358 yes: Flag.Boolean("yes").pipe(
359 Flag.withDescription("Answer yes to every question, including SSH and Tailscale."),
360 Flag.withDefault(false),
361 ),
362}).pipe(
363 Command.withDescription(
364 "Protect the T3 Code server from agents under memory pressure (Linux with systemd). Asks for sudo.",
365 ),
366 Command.withHandler((flags) =>
367 Effect.gen(function* () {
368 const unsupported = "Service protection needs Linux with systemd.";
369 if ((yield* HostProcess.Platform) !== "linux") return yield* Console.log(unsupported);
370 // Before resolving config, which creates T3 directories that root would then own.
371 if ((yield* HostProcess.UserId) === 0) {
372 return yield* Console.log(
373 "Run `t3 service protect` as the user that runs T3 Code, without sudo. It asks for sudo when it needs root.",
374 );
375 }
376 return yield* runServiceCommand(
377 flags,
378 Effect.gen(function* () {
379 const uid = yield* HostProcess.UserId;
380 const remote = yield* ServiceProtection.detectRemoteAccessUnits;
381 const { unitPath } = yield* (yield* BootService.BootService).status;
382 if (uid === undefined || remote === undefined || unitPath === "") {
383 return yield* Console.log(unsupported);
384 }
385 const userUnitDir = (yield* Path.Path).dirname(unitPath);
386
387 if (flags.undo) {
388 const installed = yield* ServiceProtection.installedProtection(
389 ServiceProtection.protectionPlan({
390 uid,
391 userUnitDir,
392 remoteAccessUnits: ServiceProtection.REMOTE_ACCESS_UNITS,
393 }),
394 );
395 if (installed === undefined) {
396 return yield* Console.log("T3 Code service protection is not set up.");
397 }
398 yield* Console.log(
399 [
400 "Removes:",
401 ...[...installed.system, ...installed.user, installed.managerDefaults].map(
402 ({ path, shared }) =>
403 ` ${path}${shared === true ? " (kept while another user is protected)" : ""}`,
404 ),
405 ].join("\n"),
406 );
407 if (!(yield* confirm(flags.yes, "Remove T3 Code service protection?"))) return;
408 yield* ServiceProtection.removeProtection(installed);
409 return yield* Console.log(
410 "Removed T3 Code service protection. The server's OOM score returns to normal after `t3 service restart`.",
411 );
412 }
413
414 yield* Console.log(
415 [
416 "Keeps T3 Code running when agents fill this machine's memory:",
417 " - reserves memory for the T3 Code server, so the kernel takes memory from agents first",
418 " - makes the out-of-memory killer pick agents before the server",
419 "It adds systemd drop-in files and changes nothing else. Undo with `t3 service protect --undo`.",
420 ].join("\n"),
421 );
422 const names = remote.map((unit) => unit.replace(/\.service$/, "")).join(" and ");
423 const protectRemote =
424 remote.length > 0 &&
425 (yield* confirm(
426 flags.yes,
427 `Also protect ${names} so you can still reach this machine under memory pressure?`,
428 ));
429 const plan = ServiceProtection.protectionPlan({
430 uid,
431 userUnitDir,
432 remoteAccessUnits: protectRemote ? remote : [],
433 });
434 yield* Console.log(
435 [
436 "Drop-ins it writes, as root through sudo:",
437 ...formatDropIns(plan.system),
438 "As you:",
439 ...formatDropIns([plan.managerDefaults, ...plan.user]),
440 ].join("\n"),
441 );
442 if (!(yield* confirm(flags.yes, "Apply these settings?"))) return;
443 yield* ServiceProtection.applyProtection(plan);
444 yield* Console.log(
445 "Protected T3 Code. Memory protection applies now; the server takes its OOM score after `t3 service restart`. Undo with `t3 service protect --undo`.",
446 );
447 }).pipe(Effect.provide(ProcessRunner.layer)),
448 );
449 }),
450 ),
451);
452
453export const serviceCommand = Command.make("service").pipe(
454 Command.withDescription("Manage the T3 Code background service."),
455 Command.withSubcommands([
456 serviceInstallCommand,
457 serviceRestartCommand,
458 serviceUninstallCommand,
459 serviceStatusCommand,
460 serviceProtectCommand,
461 serviceUpdateCommand,
462 ]),
463);