feat(worktree): enhance worktree management with new functions and improved path resolution

- Introduced functions for resolving worktree instance roles and reading worktree registries.
- Added utilities for finding worktree roots and validating worktree CLI scripts.
- Updated promotion functions to utilize new worktree management capabilities, improving overall workflow and error handling.
- Refactored existing code to streamline worktree path resolution and enhance maintainability.

Author: J-Giggles

apps/server/src/local/promotionApply.ts

@@ -21,11 +21,6 @@ import {
 } from "./promotionStatus.ts";
 import { writeRelaunchQuiesce } from "./relaunchQuiesce.ts";
 import { writePromotionPreSnapshot } from "./promotionSnapshot.ts";
-import {
-  resolveWorktreeInstanceRole,
-  type WorktreeRegistry,
-  tryResolveWorktreeRecordFromEnv,
-} from "../../../../scripts/worktree-instance.ts";
 
 export type LocalDesktopPromotionApplyResult =
   | {
@@ -62,6 +57,124 @@ const CONVEX_PROMOTION_PUSH_RELATIVE_PATH = NodePath.join(
   "scripts",
   "convex-promotion-push.mjs",
 );
+const WORKTREE_CLI_RELATIVE_PATH = NodePath.join("scripts", "worktree-cli.ts");
+const WORKTREE_DEV_INSTANCE_PREFIX = "t3code-local-worktree-";
+const WORKTREE_REGISTRY_RELATIVE_PATH = NodePath.join(
+  ".local",
+  "share",
+  "t3code-local",
+  "worktrees.json",
+);
+
+type WorktreeInstanceRole = "main" | "staging";
+
+interface WorktreeInstanceRecord {
+  readonly slug: string;
+  readonly role?: WorktreeInstanceRole;
+}
+
+export interface WorktreeRegistry {
+  readonly instances: readonly WorktreeInstanceRecord[];
+}
+
+function resolveWorktreeInstanceRole(record: WorktreeInstanceRecord): WorktreeInstanceRole {
+  const role = record.role ?? "staging";
+  if (role === "main" || role === "staging") {
+    return role;
+  }
+  throw new Error(`Invalid worktree role "${record.role}".`);
+}
+
+function findWorktreeRecord(
+  slug: string,
+  registry: WorktreeRegistry,
+): WorktreeInstanceRecord | undefined {
+  return registry.instances.find((record) => record.slug === slug);
+}
+
+function tryResolveWorktreeRecordFromEnv(
+  env: NodeJS.ProcessEnv,
+  registry: WorktreeRegistry,
+): WorktreeInstanceRecord | undefined {
+  const slugFromEnv = env.T3CODE_WORKTREE_SLUG?.trim();
+  if (slugFromEnv) {
+    return findWorktreeRecord(slugFromEnv, registry);
+  }
+
+  const devInstance = env.T3CODE_DEV_INSTANCE?.trim();
+  if (!devInstance?.startsWith(WORKTREE_DEV_INSTANCE_PREFIX)) {
+    return undefined;
+  }
+
+  return findWorktreeRecord(devInstance.slice(WORKTREE_DEV_INSTANCE_PREFIX.length), registry);
+}
+
+function readWorktreeRegistry(homeDirectory = NodeOS.homedir()): WorktreeRegistry {
+  const registryPath = NodePath.join(homeDirectory, WORKTREE_REGISTRY_RELATIVE_PATH);
+  try {
+    const parsed = JSON.parse(NodeFS.readFileSync(registryPath, "utf8")) as {
+      readonly instances?: unknown;
+    };
+    if (!Array.isArray(parsed.instances)) {
+      return { instances: [] };
+    }
+    return {
+      instances: parsed.instances.flatMap((entry) => {
+        if (!entry || typeof entry !== "object") {
+          return [];
+        }
+        const record = entry as Partial<WorktreeInstanceRecord>;
+        if (typeof record.slug !== "string") {
+          return [];
+        }
+        if (record.role !== undefined && record.role !== "main" && record.role !== "staging") {
+          return [];
+        }
+        return [record as WorktreeInstanceRecord];
+      }),
+    };
+  } catch {
+    return { instances: [] };
+  }
+}
+
+function candidateSiblingStagingWorktreePath(worktreePath: string | undefined): string | undefined {
+  const trimmed = worktreePath?.trim();
+  if (!trimmed) {
+    return undefined;
+  }
+  return NodePath.join(NodePath.dirname(NodePath.resolve(trimmed)), "t3code-staging");
+}
+
+function findNearestWorktreeRoot(startPath: string): string | undefined {
+  let current = NodePath.resolve(startPath);
+  while (true) {
+    if (NodeFS.existsSync(NodePath.join(current, WORKTREE_CLI_RELATIVE_PATH))) {
+      return current;
+    }
+    const parent = NodePath.dirname(current);
+    if (parent === current) {
+      return undefined;
+    }
+    current = parent;
+  }
+}
+
+function hasWorktreeCli(stagingWorktreePath: string): boolean {
+  return NodeFS.existsSync(resolveWorktreeCliScriptPath(stagingWorktreePath));
+}
+
+export function resolveWorktreeCliScriptPath(stagingWorktreePath: string): string {
+  return NodePath.join(stagingWorktreePath, WORKTREE_CLI_RELATIVE_PATH);
+}
+
+function requireWorktreeCliScriptPath(stagingWorktreePath: string): string {
+  const scriptPath = resolveWorktreeCliScriptPath(stagingWorktreePath);
+  if (!NodeFS.existsSync(scriptPath)) {
+    throw new Error(`Missing worktree launcher script: ${scriptPath}`);
+  }
+  return scriptPath;
+}
 
 /**
  * Default promotion pushes schema/functions in place; only full DB copy needs a backend restart.
@@ -928,21 +1041,39 @@ export type MainPromotionRelaunchTarget =
       readonly stagingWorktreePath: string;
     };
 
-function resolveDefaultStagingWorktreePath(): string {
-  return NodePath.resolve(NodePath.dirname(fileURLToPath(import.meta.url)), "../../../..");
+export function resolveDefaultStagingWorktreePath(env: NodeJS.ProcessEnv = process.env): string {
+  const moduleWorktreeRoot = findNearestWorktreeRoot(
+    NodePath.dirname(fileURLToPath(import.meta.url)),
+  );
+  const cwdWorktreeRoot = findNearestWorktreeRoot(process.cwd());
+  const candidates = [
+    candidateSiblingStagingWorktreePath(env.T3CODE_APP_ROOT),
+    candidateSiblingStagingWorktreePath(env.T3CODE_LOCAL_MAIN_WORKTREE),
+    candidateSiblingStagingWorktreePath(cwdWorktreeRoot),
+    candidateSiblingStagingWorktreePath(moduleWorktreeRoot),
+    NodePath.resolve(NodePath.dirname(fileURLToPath(import.meta.url)), "../../../.."),
+  ].filter((value): value is string => Boolean(value));
+
+  for (const candidate of candidates) {
+    if (hasWorktreeCli(candidate)) {
+      return candidate;
+    }
+  }
+
+  return candidates[0] ?? NodePath.resolve(process.cwd(), "../t3code-staging");
 }
 
 export function resolveMainPromotionRelaunchTarget(
   env: NodeJS.ProcessEnv = process.env,
-  registry?: WorktreeRegistry,
+  registry: WorktreeRegistry = readWorktreeRegistry(),
 ): MainPromotionRelaunchTarget {
   const record = tryResolveWorktreeRecordFromEnv(env, registry);
   if (record && resolveWorktreeInstanceRole(record) === "main") {
     return {
       kind: "worktree",
       slug: record.slug,
       stagingWorktreePath:
-        env.T3CODE_LOCAL_STAGING_WORKTREE?.trim() || resolveDefaultStagingWorktreePath(),
+        env.T3CODE_LOCAL_STAGING_WORKTREE?.trim() || resolveDefaultStagingWorktreePath(env),
     };
   }
 
@@ -957,7 +1088,7 @@ export function spawnDetachedWorktreeLauncher(
     return;
   }
 
-  const worktreeCli = NodePath.join(input.stagingWorktreePath, "scripts/worktree-cli.ts");
+  const worktreeCli = requireWorktreeCliScriptPath(input.stagingWorktreePath);
   const child = NodeChildProcess.spawn(process.execPath, [worktreeCli, "start", input.slug], {
     cwd: input.stagingWorktreePath,
     detached: true,

apps/server/src/local/promotionPreflight.test.ts

@@ -0,0 +1,14 @@
+import * as NodePath from "node:path";
+import { describe, expect, it } from "vitest";
+
+import { resolvePromotionPreflightCheckScriptPath } from "./promotionPreflight.ts";
+
+describe("promotionPreflight script paths", () => {
+  it("resolves the UI/model check script from the staging worktree", () => {
+    const stagingWorktree = "/worktrees/t3code-staging";
+
+    expect(resolvePromotionPreflightCheckScriptPath(stagingWorktree)).toBe(
+      NodePath.join(stagingWorktree, "scripts", "local-promotion-preflight-check.ts"),
+    );
+  });
+});

apps/server/src/local/promotionPreflight.ts

@@ -23,20 +23,19 @@ import {
   writeWorktreeAgentAutomation,
   writeWorktreeDesktopSettings,
 } from "../../../../scripts/worktree-instance.ts";
-import { autoCommitStagingChangesForPromotion } from "./promotionApply.ts";
+import {
+  autoCommitStagingChangesForPromotion,
+  resolveWorktreeCliScriptPath,
+} from "./promotionApply.ts";
 import { readLocalWorktreePathsFromEnv } from "./promotionStatus.ts";
 
 const TEST_SLUG = "test";
 const TOKEN_TTL_MS = 30 * 60 * 1_000;
 const PREFLIGHT_STATUS_FILENAME = "promotion-preflight-status.json";
 const PREFLIGHT_TOKEN_FILENAME = "promotion-preflight-passed.json";
-const WORKTREE_CLI_SCRIPT = NodePath.resolve(
-  NodePath.dirname(new URL(import.meta.url).pathname),
-  "../../../../scripts/worktree-cli.ts",
-);
-const PREFLIGHT_CHECK_SCRIPT = NodePath.resolve(
-  NodePath.dirname(new URL(import.meta.url).pathname),
-  "../../../../scripts/local-promotion-preflight-check.ts",
+const PREFLIGHT_CHECK_RELATIVE_PATH = NodePath.join(
+  "scripts",
+  "local-promotion-preflight-check.ts",
 );
 
 type PromotionPreflightToken = {
@@ -395,13 +394,28 @@ function runConvexValidation(input: {
   });
 }
 
+export function resolvePromotionPreflightCheckScriptPath(stagingWorktreePath: string): string {
+  return NodePath.join(stagingWorktreePath, PREFLIGHT_CHECK_RELATIVE_PATH);
+}
+
+function requireScriptPath(path: string, label: string): string {
+  if (!NodeFS.existsSync(path)) {
+    throw new Error(`Missing ${label}: ${path}`);
+  }
+  return path;
+}
+
 function startTestStack(input: {
   readonly stagingWorktreePath: string;
   readonly urls: ReturnType<typeof resolveWorktreeInstanceUrls>;
 }): void {
   writeWorktreeDesktopSettings(input.urls.t3Home, input.urls.tailscaleServePath);
   writeWorktreeAgentAutomation(input.urls.t3Home, input.urls.cdpPort);
-  runScript(process.execPath, [WORKTREE_CLI_SCRIPT, "start", TEST_SLUG, "--wait"], {
+  const worktreeCliScript = requireScriptPath(
+    resolveWorktreeCliScriptPath(input.stagingWorktreePath),
+    "worktree launcher script",
+  );
+  runScript(process.execPath, [worktreeCliScript, "start", TEST_SLUG, "--wait"], {
     cwd: input.stagingWorktreePath,
     env: {
       ...process.env,
@@ -414,15 +428,17 @@ function startTestStack(input: {
 }
 
 function runUiAndModelChecks(input: {
+  readonly stagingWorktreePath: string;
   readonly testWorktreePath: string;
   readonly urls: ReturnType<typeof resolveWorktreeInstanceUrls>;
 }): string {
-  if (!NodeFS.existsSync(PREFLIGHT_CHECK_SCRIPT)) {
-    throw new Error(`Missing preflight UI/model check script: ${PREFLIGHT_CHECK_SCRIPT}`);
-  }
+  const preflightCheckScript = requireScriptPath(
+    resolvePromotionPreflightCheckScriptPath(input.stagingWorktreePath),
+    "preflight UI/model check script",
+  );
 
-  const stdout = runScript(process.execPath, [PREFLIGHT_CHECK_SCRIPT], {
-    cwd: NodePath.resolve(NodePath.dirname(new URL(import.meta.url).pathname), "../../../../"),
+  const stdout = runScript(process.execPath, [preflightCheckScript], {
+    cwd: input.stagingWorktreePath,
     env: {
       ...process.env,
       T3CODE_PREFLIGHT_VITE_URL: `http://127.0.0.1:${input.urls.webPort}`,
@@ -567,6 +583,7 @@ async function runPreflight(
     startStep("verify-desktop-and-vite", "Checking projects and messages on Vite and Desktop.");
     startStep("send-real-model-check", "Sending Hi through the real configured provider.");
     const modelCheckThreadId = runUiAndModelChecks({
+      stagingWorktreePath: paths.localStagingWorktreePath,
       testWorktreePath: prepared.testWorktreePath,
       urls,
     });