@junheep/gwt 0.2.2 → 0.4.0

package/README.md

@@ -29,9 +29,10 @@ gwt shell install zsh
 ```
 
 The installer shows the line it will add to `~/.zshrc` and asks for
-confirmation. The integration also provides Zsh completion for commands,
-options, worktrees, and Git refs. It only changes directories; it does not load
-environment variables or run project hooks.
+confirmation. The integration also provides Zsh completion and automatically
+loads assigned ports and configured environment variables when Zsh enters a
+managed worktree. Previous values are restored when Zsh leaves it. Normal
+environment synchronization produces no output.
 
 ## Coding agents
 
@@ -82,7 +83,6 @@ Repositories without a remote use their canonical path.
 {
   "projects": {
     "github.com/owner/repository": {
-      "worktreeDirectory": ".worktrees",
       "copyFiles": [
         "apps/server/.env",
         "apps/web/.env"
@@ -91,6 +91,9 @@ Repositories without a remote use their canonical path.
         "WEB_PORT",
         "SERVER_PORT"
       ],
+      "env": {
+        "NEXT_PUBLIC_API_ENDPOINT": "http://127.0.0.1:${SERVER_PORT}"
+      },
       "postCreate": "hooks/worktree-setup",
       "preRemove": "hooks/worktree-cleanup"
     }
@@ -114,7 +117,6 @@ The project file contains the configuration fields directly:
 ```json
 {
   "base": "origin/main",
-  "worktreeDirectory": ".worktrees",
   "copyFiles": [
     "apps/server/.env",
     "apps/web/.env"
@@ -123,6 +125,9 @@ The project file contains the configuration fields directly:
     "WEB_PORT",
     "SERVER_PORT"
   ],
+  "env": {
+    "NEXT_PUBLIC_API_ENDPOINT": "http://127.0.0.1:${SERVER_PORT}"
+  },
   "postCreate": "./scripts/worktree-setup",
   "preRemove": "./scripts/worktree-cleanup"
 }
@@ -133,21 +138,38 @@ The two files are not merged. Run `gwt config show` to see whether user and
 repository configuration is available, the location of each existing config
 file, the active source, and its resolved value.
 
-All fields are optional. Without either config, worktrees are created beneath
-`.worktrees`, use the primary worktree's current commit as their base, and run
-no setup actions.
+All fields are optional. Without either config, worktrees are created outside
+the repository beneath `~/.gwt/worktrees`. Set `GWT_HOME` to an absolute path
+to use a different gwt home directory. A repository normally uses a directory
+named after it. If another repository already uses that name, gwt adds a short
+hash derived from the canonical path. Worktrees use the primary worktree's
+current commit as their base and run no setup actions.
 
 - `base`: Git revision used when `--base` is omitted.
-- `worktreeDirectory`: Repository-relative directory for managed worktrees.
+- `worktreeDirectory`: Optional repository-relative directory for managed
+  worktrees. Setting it opts out of the external default.
 - `copyFiles`: Ignored local files copied from the primary worktree without
   overwriting an existing destination.
 - `ports`: Environment variable names assigned stable ports in the range
   20000–39999.
+- `env`: Environment variables loaded alongside assigned ports. Values are
+  literal strings with optional `${PORT_NAME}` references to names declared in
+  `ports`. Shell expressions and references to arbitrary process variables are
+  not evaluated.
 - `postCreate`: Executable run after files and ports are prepared.
 - `preRemove`: Executable run before removal.
 
-The worktree directory is added to `.git/info/exclude`; tracked project files
-are not modified.
+An explicitly configured repository-relative worktree directory is added to
+`.git/info/exclude`; tracked project files are not modified.
+
+For example, an existing configuration can retain the previous in-repository
+layout explicitly:
+
+```json
+{
+  "worktreeDirectory": ".worktrees"
+}
+```
 
 ## Hooks
 
@@ -159,6 +181,7 @@ GWT_PATH
 GWT_PRIMARY_PATH
 GWT_BRANCH
 <each name declared in ports>
+<each name declared in env>
 ```
 
 Example `postCreate` hook:
@@ -176,9 +199,10 @@ Hook paths in user config are resolved relative to the directory containing
 worktree. Both run with the target worktree as their working directory, and
 their standard output and errors are streamed directly to the terminal.
 
-Hooks in user config are trusted because the user added them directly. Hooks
-from a committed `.gwt.json` require explicit trust because they execute
-repository code:
+User configuration is trusted because the user added it directly. Ports and
+environment variables from a committed `.gwt.json` require explicit trust
+because they automatically change the shell; repository hooks require the same
+approval because they execute code:
 
 ```sh
 gwt trust
@@ -192,8 +216,8 @@ Approval is invalidated when `.gwt.json` or either hook changes.
 gwt new [branch] [--base <ref>] [--no-hooks]
 gwt setup [id|branch|path] [--no-hooks]
 gwt list
-gwt switch [id|branch|path]
-gwt info [id|branch|path]
+gwt switch [primary|id|branch|path]
+gwt info [primary|id|branch|path]
 gwt remove [id|branch|path] [--keep-branch|--discard] [--yes] [--no-hooks]
 gwt trust [--revoke]
 gwt config create [--project]
@@ -216,7 +240,9 @@ Setup failures retain the worktree and record the failure. Retry with
 Run `gwt switch` without a target to open the interactive picker. Use the
 arrow keys, `j`/`k`, or Ctrl-n/Ctrl-p to move; press `/` to filter by branch,
 ID, or path. Enter switches to the selected worktree. Escape leaves filter
-mode or cancels the picker.
+mode or cancels the picker. `primary` is a reserved ID for the repository's
+primary worktree, so `gwt switch primary` returns to it from any linked
+worktree.
 
 `gwt remove` refuses dirty worktrees and first tries to delete the branch with
 `git branch -d`. If Git rejects safe deletion, an interactive terminal asks

package/bin/gwt.mjs

@@ -19,7 +19,7 @@ import {
 } from "node:fs"
 import { createServer } from "node:net"
 import { homedir } from "node:os"
-import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path"
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path"
 import { emitKeypressEvents } from "node:readline"
 import { createInterface } from "node:readline/promises"
 
@@ -28,7 +28,8 @@ const PORT_MIN = 20_000
 const PORT_MAX = 39_999
 const PICKER_ESCAPE_CODE_TIMEOUT_MS = 50
 const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/
-const DEFAULT_CONFIG = { worktreeDirectory: ".worktrees", copyFiles: [], ports: [] }
+const SHELL_ENV_STATE = "GWT_SHELL_ENV_STATE"
+const DEFAULT_CONFIG = { copyFiles: [], ports: [], env: {} }
 const SKILL_DIRECTORIES = { claude: ".claude", codex: ".agents" }
 const SKILL_USAGE = `Usage: gwt skill install <${Object.keys(SKILL_DIRECTORIES).join("|")}> [--project] [--dry-run] [--yes]`
 
@@ -127,7 +128,7 @@ function validateRelativePath(value, field) {
 
 function validateConfig(parsed, label) {
   if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new CliError(`${label} must contain an object`)
-  const allowed = new Set(["base", "worktreeDirectory", "copyFiles", "ports", "postCreate", "preRemove"])
+  const allowed = new Set(["base", "worktreeDirectory", "copyFiles", "ports", "env", "postCreate", "preRemove"])
   for (const key of Object.keys(parsed)) {
     if (!allowed.has(key)) throw new CliError(`${label} contains an unknown field: ${key}`)
   }
@@ -136,9 +137,12 @@ function validateConfig(parsed, label) {
     throw new CliError("base must be a non-empty string")
   }
 
-  const worktreeDirectory = validateRelativePath(parsed.worktreeDirectory ?? ".worktrees", "worktreeDirectory")
-  if (worktreeDirectory.split(/[\\/]+/).some((part) => !/^[A-Za-z0-9._-]+$/.test(part))) {
-    throw new CliError("worktreeDirectory can only contain letters, digits, '.', '_', '-', and path separators")
+  let worktreeDirectory
+  if (parsed.worktreeDirectory !== undefined) {
+    worktreeDirectory = validateRelativePath(parsed.worktreeDirectory, "worktreeDirectory")
+    if (worktreeDirectory.split(/[\\/]+/).some((part) => !/^[A-Za-z0-9._-]+$/.test(part))) {
+      throw new CliError("worktreeDirectory can only contain letters, digits, '.', '_', '-', and path separators")
+    }
   }
   if (!Array.isArray(parsed.copyFiles ?? [])) throw new CliError("copyFiles must be an array")
   const copyFiles = (parsed.copyFiles ?? []).map((path, index) => validateRelativePath(path, `copyFiles[${index}]`))
@@ -147,27 +151,105 @@ function validateConfig(parsed, label) {
   if (!Array.isArray(parsed.ports ?? [])) throw new CliError("ports must be an array")
   const ports = (parsed.ports ?? []).map((name, index) => {
     if (typeof name !== "string" || !ENV_NAME.test(name)) throw new CliError(`ports[${index}] is not a valid environment variable name`)
+    if (name.startsWith("GWT_")) throw new CliError(`ports[${index}] cannot use the reserved GWT_ prefix`)
     return name
   })
   if (new Set(ports).size !== ports.length) throw new CliError("ports cannot contain duplicates")
   if (ports.length > 100) throw new CliError("ports cannot contain more than 100 entries")
 
+  if (!parsed.env || typeof parsed.env !== "object" || Array.isArray(parsed.env)) {
+    if (parsed.env !== undefined) throw new CliError("env must be an object")
+  }
+  const envEntries = Object.entries(parsed.env ?? {})
+  if (envEntries.length > 100) throw new CliError("env cannot contain more than 100 entries")
+  const env = Object.fromEntries(envEntries.map(([name, value]) => {
+    if (!ENV_NAME.test(name)) throw new CliError(`env.${name} is not a valid environment variable name`)
+    if (name.startsWith("GWT_")) throw new CliError(`env.${name} cannot use the reserved GWT_ prefix`)
+    if (ports.includes(name)) throw new CliError(`env.${name} conflicts with a configured port`)
+    if (typeof value !== "string") throw new CliError(`env.${name} must be a string`)
+
+    const remainder = value.replace(/\$\{([^}]*)\}/g, (_, reference) => {
+      if (!ENV_NAME.test(reference) || !ports.includes(reference)) {
+        throw new CliError(`env.${name} references unknown port ${reference || "(empty)"}`)
+      }
+      return ""
+    })
+    if (remainder.includes("${")) throw new CliError(`env.${name} contains an invalid port reference`)
+    return [name, value]
+  }))
+
   for (const hook of ["postCreate", "preRemove"]) {
     if (parsed[hook] !== undefined) validateRelativePath(parsed[hook], hook)
   }
 
-  return {
+  const config = {
     ...parsed,
-    worktreeDirectory,
     copyFiles,
     ports,
+    env,
   }
+  if (worktreeDirectory !== undefined) config.worktreeDirectory = worktreeDirectory
+  return config
+}
+
+function resolveConfiguredEnv(config, ports) {
+  return Object.fromEntries(Object.entries(config.env).map(([name, template]) => [
+    name,
+    template.replace(/\$\{([^}]*)\}/g, (_, reference) => {
+      if (!Object.hasOwn(ports, reference)) {
+        throw new CliError(`Cannot resolve env.${name}: this worktree has no assigned ${reference}`)
+      }
+      return String(ports[reference])
+    }),
+  ]))
 }
 
 function configHome() {
   return process.env.XDG_CONFIG_HOME || join(homedir(), ".config")
 }
 
+function gwtHome() {
+  const path = process.env.GWT_HOME || join(homedir(), ".gwt")
+  if (!isAbsolute(path)) throw new CliError("GWT_HOME must be an absolute path")
+  return path
+}
+
+function repositoryUsesDirectory(repository, directory) {
+  const resolvedDirectory = pathExists(directory) ? canonical(directory) : resolve(directory)
+  return repository.worktrees.some((worktree) => {
+    if (!pathExists(worktree.path)) return false
+    const worktreePath = canonical(worktree.path)
+    return worktreePath !== repository.primaryPath && dirname(worktreePath) === resolvedDirectory
+  })
+}
+
+function directoryIsEmpty(path) {
+  try {
+    return statSync(path).isDirectory() && readdirSync(path).length === 0
+  } catch {
+    return false
+  }
+}
+
+function defaultWorktreeDirectory(repository) {
+  const root = join(gwtHome(), "worktrees")
+  const name = basename(repository.primaryPath)
+  const namedDirectory = join(root, name)
+  const digest = createHash("sha256").update(repository.primaryPath).digest("hex").slice(0, 8)
+  const disambiguatedDirectory = join(root, `${name}-${digest}`)
+
+  if (repositoryUsesDirectory(repository, disambiguatedDirectory)) return disambiguatedDirectory
+  if (repositoryUsesDirectory(repository, namedDirectory)) return namedDirectory
+  if (!pathExists(namedDirectory) || directoryIsEmpty(namedDirectory)) return namedDirectory
+  return disambiguatedDirectory
+}
+
+function resolveWorktreeDirectory(repository, config) {
+  return config.worktreeDirectory
+    ? resolve(repository.primaryPath, config.worktreeDirectory)
+    : defaultWorktreeDirectory(repository)
+}
+
 function userConfigPath() {
   return join(configHome(), "gwt", "config.json")
 }
@@ -311,6 +393,8 @@ function resolveWorktree(repository, selector, options = {}) {
     return current
   }
 
+  if (selector === "primary") return repository.primary
+
   const metadata = loadMetadata(repository)
   const idMatch = metadata.find((item) => item.id === selector)
   if (idMatch) {
@@ -330,9 +414,10 @@ function resolveWorktree(repository, selector, options = {}) {
 }
 
 function generateId(repository, config) {
+  const directory = resolveWorktreeDirectory(repository, config)
   for (let attempt = 0; attempt < 100; attempt += 1) {
     const id = randomBytes(4).toString("hex")
-    const target = join(repository.primaryPath, config.worktreeDirectory, id)
+    const target = join(directory, id)
     if (!existsSync(metadataPath(repository, id)) && !pathExists(target)) return id
   }
   throw new CliError("Could not generate a unique worktree ID")
@@ -398,7 +483,7 @@ function hookPaths(configDocument, worktreePath) {
 
 function trustFingerprint(repository, configDocument, worktreePath) {
   const hooks = hookPaths(configDocument, worktreePath)
-  if (hooks.length === 0) return null
+  if (hooks.length === 0 && configDocument.value.ports.length === 0 && Object.keys(configDocument.value.env).length === 0) return null
   const hash = createHash("sha256")
   hash.update(repository.primaryPath)
   hash.update("\0")
@@ -468,20 +553,24 @@ async function ensureTrusted(repository, configDocument, worktreePath) {
   if (!fingerprint || isTrusted(repository, fingerprint)) return
 
   const hooks = hookPaths(configDocument, worktreePath)
-  console.error("This repository wants to run:")
+  console.error("This repository wants to configure your development environment:")
   for (const hook of hooks) console.error(`  ${hook.name}: ${hook.configuredPath}`)
+  for (const name of configDocument.value.ports) console.error(`  port: ${name}`)
+  for (const name of Object.keys(configDocument.value.env)) console.error(`  env: ${name}`)
   const allowed = await ask("Allow and remember? [y/N] ")
-  if (!allowed) throw new CliError("Project hooks are not trusted. Run 'gwt trust' to approve them")
+  if (!allowed) throw new CliError("Project configuration is not trusted. Run 'gwt trust' to approve it")
   saveTrust(repository, fingerprint)
 }
 
-function hookContext(repository, worktree, metadata) {
+function hookContext(repository, config, worktree, metadata) {
+  const ports = metadata?.ports ?? {}
   return {
     id: metadata?.id ?? "",
     path: canonical(worktree.path),
     primaryPath: repository.primaryPath,
     branch: worktree.branch ?? "",
-    ports: metadata?.ports ?? {},
+    ports,
+    environment: resolveConfiguredEnv(config, ports),
   }
 }
 
@@ -489,7 +578,7 @@ function runHook(name, repository, configDocument, worktree, metadata) {
   const configuredPath = configDocument.value[name]
   if (!configuredPath) return
   const hook = hookPaths(configDocument, canonical(worktree.path)).find((item) => item.name === name)
-  const context = hookContext(repository, worktree, metadata)
+  const context = hookContext(repository, configDocument.value, worktree, metadata)
   const env = {
     ...process.env,
     GWT_ID: context.id,
@@ -497,6 +586,7 @@ function runHook(name, repository, configDocument, worktree, metadata) {
     GWT_PRIMARY_PATH: context.primaryPath,
     GWT_BRANCH: context.branch,
     ...Object.fromEntries(Object.entries(context.ports).map(([key, value]) => [key, String(value)])),
+    ...context.environment,
   }
   console.log(`Running ${name}...`)
   const result = run(hook.path, [], {
@@ -632,24 +722,27 @@ async function commandNew(args) {
   const base = requestedBase
     ? gitOutput(["rev-parse", "--verify", `${requestedBase}^{commit}`], repository.primaryPath)
     : gitOutput(["rev-parse", "HEAD"], repository.primaryPath)
-  const target = join(repository.primaryPath, configDocument.value.worktreeDirectory, id)
-  ensureLocalExclude(repository, configDocument.value.worktreeDirectory)
+  const target = join(resolveWorktreeDirectory(repository, configDocument.value), id)
+  if (configDocument.value.worktreeDirectory) {
+    ensureLocalExclude(repository, configDocument.value.worktreeDirectory)
+  }
 
   git(["worktree", "add", "-b", branch, target, base], repository.primaryPath, { stdio: "inherit" })
+  const targetPath = canonical(target)
   const refreshed = discoverRepository(repository.primaryPath)
-  const worktree = refreshed.worktrees.find((item) => resolve(item.path) === resolve(target))
+  const worktree = refreshed.worktrees.find((item) => resolve(item.path) === targetPath)
 
   try {
     const metadata = await setupWorktree(refreshed, configDocument, worktree, {
       id,
       noHooks: options["no-hooks"],
     })
-    console.log(`Worktree ${metadata.id} is ready at ${target}`)
+    console.log(`Worktree ${metadata.id} is ready at ${targetPath}`)
     console.log(`Branch: ${branch}`)
     for (const [name, port] of Object.entries(metadata.ports)) console.log(`${name}: ${port}`)
-    writeCdDirective(target)
+    writeCdDirective(targetPath)
   } catch (error) {
-    console.error(`Setup failed; worktree retained at ${target}`)
+    console.error(`Setup failed; worktree retained at ${targetPath}`)
     console.error(`Retry: gwt setup ${id}`)
     console.error(`Remove: gwt remove ${id}`)
     throw error
@@ -806,7 +899,7 @@ async function chooseWorktree(repository) {
 }
 
 async function commandSwitch(args) {
-  if (args.length > 1) throw new CliError("Usage: gwt switch [id|branch|path]")
+  if (args.length > 1) throw new CliError("Usage: gwt switch [primary|id|branch|path]")
   const repository = discoverRepository()
   const worktree = args[0] ? resolveWorktree(repository, args[0]) : await chooseWorktree(repository)
   writeCdDirective(canonical(worktree.path))
@@ -911,7 +1004,7 @@ function commandList(args) {
 }
 
 function commandInfo(args) {
-  if (args.length > 1) throw new CliError("Usage: gwt info [id|branch|path]")
+  if (args.length > 1) throw new CliError("Usage: gwt info [primary|id|branch|path]")
   const repository = discoverRepository()
   const worktree = resolveWorktree(repository, args[0])
   const metadata = metadataForWorktree(repository, worktree)
@@ -1010,21 +1103,21 @@ function commandTrust(args) {
   const configDocument = loadConfig(repository)
   if (!configDocument.requiresTrust) {
     console.log(configDocument.source === "user"
-      ? "User config hooks are trusted automatically"
+      ? "User configuration is trusted automatically"
       : "This repository has no project config to approve")
     return
   }
   const fingerprint = trustFingerprint(repository, configDocument, canonical(current.path))
   if (!fingerprint) {
-    console.log("This repository has no project hooks to approve")
+    console.log("This repository has no project configuration that requires approval")
     return
   }
   saveTrust(repository, fingerprint)
-  console.log(`Trusted project hooks for ${repository.primaryPath}`)
+  console.log(`Trusted project configuration for ${repository.primaryPath}`)
 }
 
 function configScaffold() {
-  return { worktreeDirectory: ".worktrees", copyFiles: [], ports: [] }
+  return { copyFiles: [], ports: [], env: {} }
 }
 
 function commandConfigCreate(args) {
@@ -1079,6 +1172,7 @@ function commandConfigShow(args) {
   console.log(`Repository config: ${repositoryConfigured ? "configured" : "not created"}`)
   if (repositoryConfigured) console.log(`  File: ${projectPath}`)
   console.log(`Active config: ${activeLabel}`)
+  console.log(`Worktree directory: ${resolveWorktreeDirectory(repository, active.value)}`)
   console.log(JSON.stringify(active.value, null, 2))
 }
 
@@ -1088,6 +1182,94 @@ function commandConfig(args) {
   throw new CliError("Usage: gwt config <create [--project]|show>")
 }
 
+function configuredShellEnvironment() {
+  const insideRepository = git(["rev-parse", "--is-inside-work-tree"], process.cwd(), { allowFailure: true })
+  if (insideRepository.status !== 0) return {}
+
+  const repository = discoverRepository()
+  const worktree = currentWorktree(repository)
+  if (!worktree || resolve(worktree.path) === resolve(repository.primaryPath)) return {}
+
+  const metadata = metadataForWorktree(repository, worktree)
+  if (!metadata) return {}
+
+  const configDocument = loadConfig(repository)
+  if (configDocument.requiresTrust) {
+    const fingerprint = trustFingerprint(repository, configDocument, canonical(worktree.path))
+    if (!isTrusted(repository, fingerprint)) return {}
+  }
+
+  const ports = Object.fromEntries(configDocument.value.ports.map((name) => {
+    if (!Object.hasOwn(metadata.ports ?? {}, name)) {
+      throw new CliError(`This worktree has no assigned ${name}; recreate it after changing ports`)
+    }
+    return [name, String(metadata.ports[name])]
+  }))
+  return { ...ports, ...resolveConfiguredEnv(configDocument.value, metadata.ports ?? {}) }
+}
+
+function readShellEnvironmentState() {
+  const encoded = process.env[SHELL_ENV_STATE]
+  if (!encoded) return { originals: {} }
+
+  try {
+    const parsed = JSON.parse(Buffer.from(encoded, "base64url").toString("utf8"))
+    if (!parsed || typeof parsed.originals !== "object" || Array.isArray(parsed.originals)) throw new Error()
+    const originals = Object.fromEntries(Object.entries(parsed.originals).map(([name, original]) => {
+      if (!ENV_NAME.test(name) || name.startsWith("GWT_")) throw new Error()
+      if (!original || typeof original !== "object" || typeof original.present !== "boolean") throw new Error()
+      if (original.present && typeof original.value !== "string") throw new Error()
+      return [name, original.present ? { present: true, value: original.value } : { present: false }]
+    }))
+    return { originals }
+  } catch {
+    return { originals: {} }
+  }
+}
+
+function quoteZsh(value) {
+  return `'${String(value).replaceAll("'", `'\\''`)}'`
+}
+
+function shellEnvironmentCommands(environment) {
+  const previous = readShellEnvironmentState()
+  const names = new Set([...Object.keys(previous.originals), ...Object.keys(environment)])
+  const originals = {}
+  const commands = []
+
+  for (const name of names) {
+    const original = previous.originals[name] ?? (Object.hasOwn(process.env, name)
+      ? { present: true, value: process.env[name] }
+      : { present: false })
+
+    if (Object.hasOwn(environment, name)) {
+      originals[name] = original
+      commands.push(`export ${name}=${quoteZsh(environment[name])}`)
+    } else if (original.present) {
+      commands.push(`export ${name}=${quoteZsh(original.value)}`)
+    } else {
+      commands.push(`unset ${name}`)
+    }
+  }
+
+  if (Object.keys(originals).length === 0) {
+    commands.push(`unset ${SHELL_ENV_STATE}`)
+  } else {
+    const state = Buffer.from(JSON.stringify({ originals })).toString("base64url")
+    commands.push(`export ${SHELL_ENV_STATE}=${quoteZsh(state)}`)
+  }
+  return commands.join("\n")
+}
+
+function commandShellEnvironment(args) {
+  if (args.length !== 1 || args[0] !== "zsh") throw new CliError("Invalid shell environment request")
+  let environment = {}
+  try {
+    environment = configuredShellEnvironment()
+  } catch {}
+  console.log(shellEnvironmentCommands(environment))
+}
+
 function zshIntegration() {
   return `# gwt shell integration for zsh
 if command -v gwt >/dev/null 2>&1; then
@@ -1099,9 +1281,18 @@ if command -v gwt >/dev/null 2>&1; then
       builtin cd -- "$(<"$cd_file")" || exit_code=$?
     fi
     rm -f -- "$cd_file"
+    if [[ $exit_code -eq 0 ]]; then
+      _gwt_sync_env
+    fi
     return $exit_code
   }
 
+  _gwt_sync_env() {
+    local commands
+    commands="$(command gwt __shell_env zsh 2>/dev/null)" || return 0
+    [[ -n "$commands" ]] && eval "$commands"
+  }
+
   _gwt_worktrees() {
     local -a targets
     targets=("\${(@f)$(command gwt __complete worktrees 2>/dev/null)}")
@@ -1199,6 +1390,12 @@ if command -v gwt >/dev/null 2>&1; then
   if (( $+functions[compdef] )); then
     compdef _gwt gwt
   fi
+
+  typeset -ga chpwd_functions
+  if (( ! \${chpwd_functions[(I)_gwt_sync_env]} )); then
+    chpwd_functions+=(_gwt_sync_env)
+  fi
+  _gwt_sync_env
 fi`
 }
 
@@ -1227,13 +1424,16 @@ stay accurate across versions.
 
 ## What the help does not make obvious
 
-- Hooks declared by a committed \`.gwt.json\` do not run until the repository is
-  approved with \`gwt trust\`. Approval is invalidated whenever the config or a
-  hook changes, so a repository that worked before can start asking again.
+- Ports, environment variables, and hooks declared by a committed \`.gwt.json\`
+  are not applied until the repository is approved with \`gwt trust\`. Approval
+  is invalidated whenever the config or a hook changes, so a repository that
+  worked before can start asking again.
 - A failed setup keeps the worktree and records the failure. Retry it with
   \`gwt setup <id>\` rather than removing and recreating the worktree.
-- Ports are assigned per worktree. Read them from \`gwt info\` instead of assuming
-  a project default; two worktrees of the same project never share a port.
+- Ports are assigned per worktree. With shell integration installed, assigned
+  ports and configured environment variables load automatically. Read ports
+  from \`gwt info\` instead of assuming a project default; two worktrees of the
+  same project never share a port.
 - \`gwt switch\` changes the shell's directory only when the shell integration is
   installed. Otherwise it just prints the path.
 - \`gwt switch\` with no target opens an interactive picker, so always pass an
@@ -1332,13 +1532,14 @@ function commandComplete(args) {
 
   if (args[0] === "worktrees") {
     const repository = discoverRepository()
-    const values = []
+    const values = ["primary"]
     for (const worktree of repository.worktrees) {
+      if (resolve(worktree.path) === resolve(repository.primaryPath)) continue
       const metadata = metadataForWorktree(repository, worktree)
-      if (metadata?.id) values.push(metadata.id)
-      if (worktree.branch) values.push(worktree.branch)
+      const selector = worktree.branch ?? metadata?.id
+      if (selector) values.push(selector)
     }
-    console.log([...new Set(values)].join("\n"))
+    console.log(values.join("\n"))
     return
   }
 
@@ -1377,7 +1578,7 @@ Commands:
   switch    Switch the current shell to a worktree
   info      Show worktree details and assigned ports
   remove    Safely remove a worktree and optionally its branch
-  trust     Approve or revoke repository project hooks
+  trust     Approve or revoke repository project configuration
   config    Create or inspect configuration
   shell     Install shell integration
   skill     Install the gwt skill for coding agents
@@ -1411,10 +1612,13 @@ Options:
 
 Behavior:
   The worktree receives an immutable 8-character ID. gwt creates it below the
-  configured worktreeDirectory, copies configured local files, assigns stable
+  resolved worktree directory, copies configured local files, assigns stable
   ports, and runs postCreate. A setup failure keeps the worktree so setup can
   be retried. With shell integration installed, the current shell moves into
-  the new worktree after setup succeeds.
+  the new worktree after setup succeeds. Without worktreeDirectory, the default
+  is $GWT_HOME/worktrees or ~/.gwt/worktrees when GWT_HOME is not set. A short
+  repository hash is added to the directory name only when needed to avoid a
+  name collision.
 
 Examples:
   gwt new feature/auth
@@ -1457,36 +1661,40 @@ Example:
     switch: `Switch the current shell to another worktree.
 
 Usage:
-  gwt switch [id|branch|path]
+  gwt switch [primary|id|branch|path]
 
 Arguments:
-  id|branch|path  Worktree to switch to. Opens the picker when omitted.
+  selector        Worktree to switch to. Opens the picker when omitted.
 
 Options:
   -h, --help      Show help for this command.
 
 Behavior:
-  The picker supports arrow keys, j/k, Ctrl-n/Ctrl-p, and '/' filtering. Shell
-  integration must be installed for gwt to change the parent shell's directory;
-  otherwise the selected path is only printed.
+  'primary' is the reserved ID for the primary worktree. Other worktrees can be
+  selected by ID, exact branch name, or path. The picker supports arrow keys,
+  j/k, Ctrl-n/Ctrl-p, and '/' filtering. Shell integration must be installed for
+  gwt to change the parent shell's directory; otherwise the path is only printed.
 
 Examples:
   gwt switch
+  gwt switch primary
   gwt switch feature/auth
   gwt switch a1b2c3d4`,
     info: `Show a worktree's identity, Git state, setup status, and assigned ports.
 
 Usage:
-  gwt info [id|branch|path]
+  gwt info [primary|id|branch|path]
 
 Arguments:
-  id|branch|path  Worktree to inspect. Defaults to the current worktree.
+  selector        'primary', an ID, an exact branch name, or a path. Defaults
+                  to the current worktree.
 
 Options:
   -h, --help      Show help for this command.
 
 Examples:
   gwt info
+  gwt info primary
   gwt info feature/auth`,
     remove: `Safely remove a linked worktree and, by default, its branch.
 
@@ -1515,7 +1723,7 @@ Examples:
   gwt remove
   gwt remove feature/auth --keep-branch
   gwt remove a1b2c3d4 --discard --yes`,
-    trust: `Approve or revoke hooks declared by the repository's .gwt.json.
+    trust: `Approve or revoke active configuration declared by the repository's .gwt.json.
 
 Usage:
   gwt trust [--revoke]
@@ -1524,9 +1732,10 @@ Options:
   --revoke        Remove the stored approval for this repository.
   -h, --help      Show help for this command.
 
-Approval is tied to the configuration and hook contents, so changing either
-requires approval again. Hooks declared in user configuration are trusted
-automatically.
+Approval is required before repository-defined ports or environment variables
+are applied, or repository hooks run. It is tied to the configuration and hook
+contents, so changing either requires approval again. User configuration is
+trusted automatically.
 
 Examples:
   gwt trust
@@ -1579,8 +1788,8 @@ Options:
   -h, --help      Show help for this command.
 
 The output distinguishes a missing user config file from an existing file that
-does not configure the current project. Repository configuration takes
-precedence over user configuration.
+does not configure the current project. It also shows the resolved worktree
+directory. Repository configuration takes precedence over user configuration.
 
 Example:
   gwt config show`,
@@ -1593,7 +1802,8 @@ Options:
   -h, --help      Show help for this command.
 
 The integration lets gwt change the current shell's directory after new,
-switch, and removal of the current worktree. It also installs completion.
+switch, and removal of the current worktree. It also loads the worktree's
+assigned ports and configured environment, and installs completion.
 
 Example:
   gwt shell install zsh`,
@@ -1608,7 +1818,9 @@ Options:
   -h, --help      Show help for this command.
 
 The command adds one initialization line to ~/.zshrc, or to $ZDOTDIR/.zshrc
-when ZDOTDIR is set. Restart Zsh or source the file after installation.
+when ZDOTDIR is set. Restart Zsh or source the file after installation. The
+integration updates the environment when Zsh starts or changes directory and
+restores previous values after leaving a managed worktree.
 
 Examples:
   gwt shell install zsh
@@ -1685,6 +1897,7 @@ async function main() {
   if (command === "shell") return commandShell(args)
   if (command === "skill") return commandSkill(args)
   if (command === "__complete") return commandComplete(args)
+  if (command === "__shell_env") return commandShellEnvironment(args)
   throw new CliError(`Unknown command: ${command}`)
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@junheep/gwt",
-  "version": "0.2.2",
+  "version": "0.4.0",
   "description": "Lightweight native Git worktree workflows",
   "license": "MIT",
   "author": "Junhee Park",