feat(lastcode): add Codex thread tools

apps/server/src/bin.ts

@@ -17,6 +17,7 @@ import { runServerCommand, serveCommand, startCommand } from "./cli/server.ts";
 import { serviceCommand } from "./cli/service.ts";
 import { servicePreflightCommand } from "./cli/servicePreflight.ts";
 import { triageCommand } from "./cli/triage.ts";
+import { threadCommand } from "./cli/thread.ts";
 
 const CliRuntimeLayer = Layer.mergeAll(NodeServices.layer, NetService.layer);
 
@@ -57,6 +58,7 @@ export const makeCli = ({ cloudEnabled = hasCloudPublicConfig } = {}) =>
       serviceCommand,
       servicePreflightCommand,
       triageCommand,
+      threadCommand,
       cloudEnabled ? connectCommand : connectUnavailableCommand,
     ]),
   );

apps/server/src/cli/config.test.ts

@@ -17,8 +17,8 @@ import {
 } from "@t3tools/contracts";
 import * as NetService from "@t3tools/shared/Net";
 import * as NodeServices from "@effect/platform-node/NodeServices";
-import { deriveServerPaths } from "../config.ts";
-import { resolveServerConfig } from "./config.ts";
+import { DEFAULT_PORT, deriveServerPaths } from "../config.ts";
+import { resolveServerConfig, resolveThreadInspectionConfig } from "./config.ts";
 
 const deriveExplicitServerPaths = (baseDir: string, devUrl: URL | undefined) =>
   deriveServerPaths(baseDir, devUrl, { baseDirIsExplicit: true });
@@ -79,7 +79,7 @@ it.layer(NodeServices.layer)("cli config resolution", (it) => {
           host: Option.none(),
           baseDir: Option.none(),
           cwd: Option.none(),
-          devUrl: Option.none(),
+          devUrl: Option.some(new URL("http://127.0.0.1:5173")),
           noBrowser: Option.none(),
           bootstrapFd: Option.none(),
           autoBootstrapProjectFromCwd: Option.none(),
@@ -619,4 +619,108 @@ it.layer(NodeServices.layer)("cli config resolution", (it) => {
       });
     }),
   );
+
+  it.effect("pins every derived path to the explicitly active dev state", () =>
+    Effect.gen(function* () {
+      const { join } = yield* Path.Path;
+      const fs = yield* FileSystem.FileSystem;
+      const baseDir = yield* fs.makeTempDirectoryScoped({ prefix: "thread-active-home-" });
+      const stateDir = join(baseDir, "dev");
+      const inheritedDevUrl = new URL("http://127.0.0.1:5173");
+      const resolved = yield* resolveServerConfig(
+        {
+          mode: Option.none(),
+          port: Option.some(3773),
+          host: Option.none(),
+          baseDir: Option.some(baseDir),
+          cwd: Option.none(),
+          devUrl: Option.some(inheritedDevUrl),
+          noBrowser: Option.none(),
+          bootstrapFd: Option.none(),
+          autoBootstrapProjectFromCwd: Option.none(),
+          logWebSocketEvents: Option.none(),
+          tailscaleServeEnabled: Option.none(),
+          tailscaleServePort: Option.none(),
+        },
+        Option.none(),
+        { activeStateDir: Option.some(stateDir) },
+      ).pipe(
+        Effect.provide(
+          Layer.mergeAll(
+            ConfigProvider.layer(ConfigProvider.fromEnv({ env: {} })),
+            NetService.layer,
+          ),
+        ),
+      );
+      assert.equal(resolved.baseDir, baseDir);
+      assert.equal(resolved.stateDir, stateDir);
+      assert.equal(resolved.devUrl, inheritedDevUrl);
+      assert.equal(resolved.dbPath, join(stateDir, "state.sqlite"));
+      assert.equal(resolved.environmentIdPath, join(stateDir, "environment-id"));
+      assert.equal(resolved.serverRuntimeStatePath, join(stateDir, "server-runtime.json"));
+      assert.equal(resolved.secretsDir, join(stateDir, "secrets"));
+
+      const userdataStateDir = join(baseDir, "userdata");
+      const userdata = yield* resolveServerConfig(
+        {
+          mode: Option.none(),
+          port: Option.some(3773),
+          host: Option.none(),
+          baseDir: Option.some(baseDir),
+          cwd: Option.none(),
+          devUrl: Option.some(new URL("http://127.0.0.1:5173")),
+          noBrowser: Option.none(),
+          bootstrapFd: Option.none(),
+          autoBootstrapProjectFromCwd: Option.none(),
+          logWebSocketEvents: Option.none(),
+          tailscaleServeEnabled: Option.none(),
+          tailscaleServePort: Option.none(),
+        },
+        Option.none(),
+        { activeStateDir: Option.some(userdataStateDir) },
+      ).pipe(
+        Effect.provide(
+          Layer.mergeAll(
+            ConfigProvider.layer(ConfigProvider.fromEnv({ env: {} })),
+            NetService.layer,
+          ),
+        ),
+      );
+      assert.equal(userdata.stateDir, userdataStateDir);
+      assert.equal(userdata.devUrl?.href, "http://127.0.0.1:5173/");
+    }).pipe(Effect.scoped),
+  );
+
+  it.effect("derives thread inspection config without probing ports or provisioning paths", () =>
+    Effect.gen(function* () {
+      const fs = yield* FileSystem.FileSystem;
+      const { join } = yield* Path.Path;
+      const root = yield* fs.makeTempDirectoryScoped({ prefix: "thread-config-read-only-" });
+      const baseDir = join(root, "missing-home");
+      let portProbeCount = 0;
+      const netLayer = Layer.succeed(NetService.NetService, {
+        canListenOnHost: () => Effect.die("unexpected port probe"),
+        isPortAvailableOnLoopback: () => Effect.die("unexpected port probe"),
+        hasListenerOnHost: () => Effect.die("unexpected port probe"),
+        reserveLoopbackPort: () => Effect.die("unexpected port probe"),
+        findAvailablePort: () => {
+          portProbeCount += 1;
+          return Effect.die("unexpected port probe");
+        },
+      });
+      const resolved = yield* resolveThreadInspectionConfig(
+        { baseDir: Option.some(baseDir) },
+        Option.none(),
+      ).pipe(
+        Effect.provide(
+          Layer.mergeAll(ConfigProvider.layer(ConfigProvider.fromEnv({ env: {} })), netLayer),
+        ),
+      );
+
+      assert.equal(resolved.port, DEFAULT_PORT);
+      assert.equal(resolved.baseDir, baseDir);
+      assert.equal(portProbeCount, 0);
+      assert.isFalse(yield* fs.exists(baseDir));
+    }).pipe(Effect.scoped),
+  );
 });

apps/server/src/cli/config.ts

@@ -17,6 +17,11 @@ import { readBootstrapEnvelope } from "../bootstrap.ts";
 import * as ServerConfig from "../config.ts";
 import { expandHomePath, resolveBaseDir } from "../os-jank.ts";
 
+export class CliLocationError extends Schema.TaggedErrorClass<CliLocationError>()(
+  "CliLocationError",
+  { message: Schema.String },
+) {}
+
 export const modeFlag = Flag.choice("mode", ServerConfig.RuntimeMode.literals).pipe(
   Flag.withDescription("Runtime mode. `desktop` keeps loopback defaults unless overridden."),
   Flag.optional,
@@ -159,6 +164,7 @@ export interface CliServerFlags {
 export interface CliAuthLocationFlags {
   readonly baseDir: Option.Option<string>;
   readonly devUrl?: Option.Option<URL>;
+  readonly stateDir?: Option.Option<string>;
 }
 
 export const sharedServerLocationFlags = {
@@ -213,6 +219,9 @@ export const resolveServerConfig = (
   options?: {
     readonly startupPresentation?: ServerConfig.StartupPresentation;
     readonly forceAutoBootstrapProjectFromCwd?: boolean;
+    readonly activeStateDir?: Option.Option<string>;
+    readonly provisionPaths?: boolean;
+    readonly discoverPort?: boolean;
   },
 ) =>
   Effect.gen(function* () {
@@ -259,7 +268,7 @@ export const resolveServerConfig = (
       {
         onSome: (value) => Effect.succeed(value),
         onNone: () => {
-          if (mode === "desktop") {
+          if (mode === "desktop" || options?.discoverPort === false) {
             return Effect.succeed(ServerConfig.DEFAULT_PORT);
           }
           return findAvailablePort(ServerConfig.DEFAULT_PORT);
@@ -281,16 +290,38 @@ export const resolveServerConfig = (
     );
     const rawCwd = Option.getOrElse(normalizedFlags.cwd, () => process.cwd());
     const cwd = path.resolve(yield* expandHomePath(rawCwd.trim()));
-    yield* fs.makeDirectory(cwd, { recursive: true });
-    const derivedPaths = yield* ServerConfig.deriveServerPaths(baseDir, devUrl, {
-      baseDirIsExplicit: Option.isSome(explicitBaseDir),
+    const provisionPaths = options?.provisionPaths ?? true;
+    if (provisionPaths) yield* fs.makeDirectory(cwd, { recursive: true });
+    const requestedStateDir = yield* Option.match(options?.activeStateDir ?? Option.none(), {
+      onNone: () => Effect.void,
+      onSome: (value) => Effect.map(expandHomePath(value.trim()), path.resolve),
     });
-    yield* ServerConfig.ensureServerDirectories(derivedPaths);
+    const userdataStateDir = path.join(baseDir, "userdata");
+    const devStateDir = path.join(baseDir, "dev");
+    if (
+      requestedStateDir !== undefined &&
+      requestedStateDir !== userdataStateDir &&
+      requestedStateDir !== devStateDir
+    ) {
+      return yield* new CliLocationError({
+        message: "--state-dir must select the userdata or dev directory within --base-dir.",
+      });
+    }
+    const derivedPaths = yield* ServerConfig.deriveServerPaths(
+      baseDir,
+      requestedStateDir === userdataStateDir
+        ? undefined
+        : requestedStateDir === devStateDir
+          ? (devUrl ?? new URL("http://127.0.0.1"))
+          : devUrl,
+      { baseDirIsExplicit: requestedStateDir === undefined && Option.isSome(explicitBaseDir) },
+    );
+    if (provisionPaths) yield* ServerConfig.ensureServerDirectories(derivedPaths);
     const persistedObservabilitySettings = yield* loadPersistedObservabilitySettings(
       derivedPaths.settingsPath,
     );
     const serverTracePath = env.traceFile ?? derivedPaths.serverTracePath;
-    yield* fs.makeDirectory(path.dirname(serverTracePath), { recursive: true });
+    if (provisionPaths) yield* fs.makeDirectory(path.dirname(serverTracePath), { recursive: true });
     const startupPresentation = options?.startupPresentation ?? "browser";
     const isHeadlessStartup = startupPresentation === "headless";
     const noBrowser = Option.getOrElse(
@@ -391,27 +422,38 @@ export const resolveServerConfig = (
     return config;
   });
 
+const cliAuthServerFlags = (flags: CliAuthLocationFlags): CliServerFlags => ({
+  mode: Option.none(),
+  port: Option.none(),
+  host: Option.none(),
+  baseDir: flags.baseDir,
+  cwd: Option.none(),
+  devUrl: flags.devUrl ?? Option.none(),
+  noBrowser: Option.none(),
+  bootstrapFd: Option.none(),
+  autoBootstrapProjectFromCwd: Option.none(),
+  logWebSocketEvents: Option.none(),
+  tailscaleServeEnabled: Option.none(),
+  tailscaleServePort: Option.none(),
+});
+
 export const resolveCliAuthConfig = (
   flags: CliAuthLocationFlags,
   cliLogLevel: Option.Option<LogLevel.LogLevel>,
 ) =>
-  resolveServerConfig(
-    {
-      mode: Option.none(),
-      port: Option.none(),
-      host: Option.none(),
-      baseDir: flags.baseDir,
-      cwd: Option.none(),
-      devUrl: flags.devUrl ?? Option.none(),
-      noBrowser: Option.none(),
-      bootstrapFd: Option.none(),
-      autoBootstrapProjectFromCwd: Option.none(),
-      logWebSocketEvents: Option.none(),
-      tailscaleServeEnabled: Option.none(),
-      tailscaleServePort: Option.none(),
-    },
-    cliLogLevel,
-  );
+  resolveServerConfig(cliAuthServerFlags(flags), cliLogLevel, {
+    activeStateDir: flags.stateDir ?? Option.none(),
+  });
+
+export const resolveThreadInspectionConfig = (
+  flags: CliAuthLocationFlags,
+  cliLogLevel: Option.Option<LogLevel.LogLevel>,
+) =>
+  resolveServerConfig(cliAuthServerFlags(flags), cliLogLevel, {
+    activeStateDir: flags.stateDir ?? Option.none(),
+    provisionPaths: false,
+    discoverPort: false,
+  });
 
 const DurationShorthandPattern = /^(?<value>\d+)(?<unit>ms|s|m|h|d|w)$/i;