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