@junheep/gwt 0.1.0 → 0.2.0

package/README.md

@@ -33,6 +33,38 @@ 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.
 
+## Coding agents
+
+Coding agents do not know about `gwt` and reach for `git worktree add`, which
+skips the copied files, assigned ports, and setup hooks. Install a skill that
+tells them otherwise:
+
+```sh
+gwt skill install claude
+gwt skill install codex
+```
+
+The installer shows the target path and asks for confirmation before writing.
+Both agents read the same `SKILL.md` format and differ only in location, so
+the installed skill is identical:
+
+| Agent  | Default                        | With `--project`             |
+| ------ | ------------------------------ | ---------------------------- |
+| Claude | `~/.claude/skills/gwt/SKILL.md` | `.claude/skills/gwt/SKILL.md` |
+| Codex  | `~/.agents/skills/gwt/SKILL.md` | `.agents/skills/gwt/SKILL.md` |
+
+`--project` writes into the primary worktree so the skill can be committed for
+the team.
+
+The skill covers what `gwt --help` does not: that gwt is preferred over native
+`git worktree`, that project hooks need `gwt trust`, that a failed setup is
+retried rather than recreated, that ports come from `gwt info`, and that
+removal is destructive. It points at `gwt <command> --help` for command
+details instead of repeating them, so it does not go stale as gwt changes.
+Reinstall after upgrading to pick up a revised skill; an unchanged file is
+reported as already installed, and a modified one is replaced only after
+confirmation.
+
 ## Configuration
 
 Create user configuration for the current repository:
@@ -141,7 +173,8 @@ pnpm install --frozen-lockfile
 
 Hook paths in user config are resolved relative to the directory containing
 `config.json`; hook paths in `.gwt.json` are resolved relative to the target
-worktree. Both run with the target worktree as their working directory.
+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
@@ -166,6 +199,7 @@ gwt trust [--revoke]
 gwt config create [--project]
 gwt config show
 gwt shell install zsh [--dry-run] [--yes]
+gwt skill install <claude|codex> [--project] [--dry-run] [--yes]
 ```
 
 Run `gwt --help` for the command overview, or `gwt <command> --help` for
@@ -184,6 +218,8 @@ arrow keys, `j`/`k`, or Ctrl-n/Ctrl-p to move; press 1–9 to select a numbered
 row immediately; or press `/` to filter by branch, ID, or path. Enter switches
 to the selected worktree. Escape leaves filter mode or cancels the picker.
 
-`gwt remove` refuses dirty worktrees. It removes the branch only when
-`git branch -d` considers the deletion safe. `--discard --yes` explicitly
-allows dirty worktree removal and forced branch deletion.
+`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
+whether to force-delete the branch; non-interactive use keeps it and prints a
+command for deleting it later. `--discard --yes` explicitly allows dirty
+worktree removal and forced branch deletion.

package/bin/gwt.mjs

@@ -23,12 +23,13 @@ import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path"
 import { emitKeypressEvents } from "node:readline"
 import { createInterface } from "node:readline/promises"
 
-const VERSION = "0.1.0"
 const PROJECT_CONFIG_FILE = ".gwt.json"
 const PORT_MIN = 20_000
 const PORT_MAX = 39_999
 const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/
 const DEFAULT_CONFIG = { worktreeDirectory: ".worktrees", copyFiles: [], ports: [] }
+const SKILL_DIRECTORIES = { claude: ".claude", codex: ".agents" }
+const SKILL_USAGE = `Usage: gwt skill install <${Object.keys(SKILL_DIRECTORIES).join("|")}> [--project] [--dry-run] [--yes]`
 
 class CliError extends Error {}
 
@@ -496,14 +497,14 @@ function runHook(name, repository, configDocument, worktree, metadata) {
     GWT_BRANCH: context.branch,
     ...Object.fromEntries(Object.entries(context.ports).map(([key, value]) => [key, String(value)])),
   }
+  console.log(`Running ${name}...`)
   const result = run(hook.path, [], {
     cwd: context.path,
     env,
     input: `${JSON.stringify(context)}\n`,
     allowFailure: true,
+    stdio: ["pipe", "inherit", "inherit"],
   })
-  if (result.stdout) process.stdout.write(result.stdout)
-  if (result.stderr) process.stderr.write(result.stderr)
   if (result.status !== 0) throw new CliError(`${name} failed with status ${result.status}`)
 }
 
@@ -817,18 +818,46 @@ function worktreeRows(repository) {
   return rows
 }
 
+function displayWidth(value) {
+  let width = 0
+  for (const character of value.normalize("NFC")) {
+    const codePoint = character.codePointAt(0)
+    if (/\p{Mark}/u.test(character) || codePoint === 0x200d) continue
+    const fullWidth = codePoint >= 0x1100 && (
+      codePoint <= 0x115f
+      || codePoint === 0x2329
+      || codePoint === 0x232a
+      || (codePoint >= 0x2e80 && codePoint <= 0xa4cf && codePoint !== 0x303f)
+      || (codePoint >= 0xac00 && codePoint <= 0xd7a3)
+      || (codePoint >= 0xf900 && codePoint <= 0xfaff)
+      || (codePoint >= 0xfe10 && codePoint <= 0xfe19)
+      || (codePoint >= 0xfe30 && codePoint <= 0xfe6f)
+      || (codePoint >= 0xff00 && codePoint <= 0xff60)
+      || (codePoint >= 0xffe0 && codePoint <= 0xffe6)
+      || (codePoint >= 0x1f300 && codePoint <= 0x1faff)
+      || (codePoint >= 0x20000 && codePoint <= 0x3fffd)
+    )
+    width += fullWidth ? 2 : 1
+  }
+  return width
+}
+
+function padDisplay(value, width) {
+  return `${value}${" ".repeat(Math.max(0, width - displayWidth(value)))}`
+}
+
 function commandList(args) {
   if (args.length > 0) throw new CliError("Usage: gwt list")
   const repository = discoverRepository()
   const rows = worktreeRows(repository)
   const widths = {
-    id: Math.max(2, ...rows.map((row) => row.id.length)),
-    branch: Math.max(6, ...rows.map((row) => row.branch.length)),
-    setup: Math.max(5, ...rows.map((row) => row.setup.length)),
+    id: Math.max(2, ...rows.map((row) => displayWidth(row.id))),
+    branch: Math.max(6, ...rows.map((row) => displayWidth(row.branch))),
+    setup: Math.max(5, ...rows.map((row) => displayWidth(row.setup))),
   }
-  console.log(`  ${"ID".padEnd(widths.id)}  ${"BRANCH".padEnd(widths.branch)}  ${"SETUP".padEnd(widths.setup)}  PATH`)
+  console.log(`  ${padDisplay("ID", widths.id)}  ${padDisplay("BRANCH", widths.branch)}  ${padDisplay("SETUP", widths.setup)}  PATH`)
   for (const row of rows) {
-    console.log(`${row.current ? "*" : " "} ${row.id.padEnd(widths.id)}  ${row.branch.padEnd(widths.branch)}  ${row.setup.padEnd(widths.setup)}  ${row.path}`)
+    console.log(`${row.current ? "*" : " "} ${padDisplay(row.id, widths.id)}  ${padDisplay(row.branch, widths.branch)}  ${padDisplay(row.setup, widths.setup)}  ${row.path}`)
   }
 }
 
@@ -890,6 +919,7 @@ async function commandRemove(args) {
   const removeArgs = ["worktree", "remove"]
   if (options.discard) removeArgs.push("--force")
   removeArgs.push(targetPath)
+  console.log(`Removing worktree ${metadata?.id ?? targetPath}...`)
   git(removeArgs, repository.primaryPath)
   if (metadata?.metadataPath && existsSync(metadata.metadataPath)) unlinkSync(metadata.metadataPath)
 
@@ -897,7 +927,20 @@ async function commandRemove(args) {
   if (worktree.branch && !options["keep-branch"]) {
     const deleteArgs = ["branch", options.discard ? "-D" : "-d", "--", worktree.branch]
     const result = git(deleteArgs, repository.primaryPath, { allowFailure: true })
-    branchMessage = result.status === 0 ? `Deleted branch: ${worktree.branch}` : `Kept branch: ${worktree.branch}`
+    if (result.status === 0) {
+      branchMessage = `Deleted branch: ${worktree.branch}`
+    } else if (!options.discard) {
+      console.log(`Branch '${worktree.branch}' could not be deleted safely.`)
+      const forceDelete = await ask("Force-delete the branch? [y/N] ")
+      if (forceDelete) {
+        git(["branch", "-D", "--", worktree.branch], repository.primaryPath)
+        branchMessage = `Deleted branch: ${worktree.branch}`
+      } else {
+        branchMessage = `Kept branch: ${worktree.branch}\nDelete later: git branch -D -- ${worktree.branch}`
+      }
+    } else {
+      branchMessage = `Kept branch: ${worktree.branch}`
+    }
   } else if (worktree.branch) branchMessage = `Kept branch: ${worktree.branch}`
 
   console.log(`Removed worktree: ${metadata?.id ?? targetPath}`)
@@ -1034,6 +1077,7 @@ if command -v gwt >/dev/null 2>&1; then
       'trust:Approve project hooks'
       'config:Manage user and project configuration'
       'shell:Install shell integration'
+      'skill:Install the gwt skill for coding agents'
     )
 
     if (( CURRENT == 2 )); then
@@ -1091,6 +1135,15 @@ if command -v gwt >/dev/null 2>&1; then
           '--yes[skip installation confirmation]' \
           '(-h --help)'{-h,--help}'[show help]'
         ;;
+      skill)
+        _arguments \
+          '2:action:(install)' \
+          '3:agent:(claude codex)' \
+          '--project[install into the repository instead of the home directory]' \
+          '--dry-run[show the change without writing]' \
+          '--yes[skip installation confirmation]' \
+          '(-h --help)'{-h,--help}'[show help]'
+        ;;
     esac
   }
 
@@ -1100,6 +1153,92 @@ if command -v gwt >/dev/null 2>&1; then
 fi`
 }
 
+function agentSkill() {
+  return `---
+name: gwt
+description: Use gwt to create, list, switch, and remove Git worktrees. Use whenever a task needs an isolated worktree, or in place of running 'git worktree' directly.
+---
+
+gwt wraps native Git worktrees and prepares each one with the project's local
+files, assigned ports, and setup hooks.
+
+## Prefer gwt over 'git worktree'
+
+Create worktrees with \`gwt new\`, not \`git worktree add\`. A worktree added with
+plain Git skips the configured file copies, port assignment, and postCreate
+hook, and records no gwt metadata, so \`gwt list\` and \`gwt remove\` cannot manage
+it. Adopt an existing one with \`gwt setup <path>\`.
+
+## Read the help instead of guessing flags
+
+\`gwt --help\` lists the commands, \`gwt <command> --help\` documents arguments,
+options, and behavior, and nested commands such as \`gwt config create --help\`
+have their own help. This skill does not repeat command signatures so that they
+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.
+- 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.
+- \`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
+  explicit target when running non-interactively.
+
+## Removal is destructive
+
+\`gwt remove\` deletes the worktree and, by default, its branch. Confirm with the
+user before running it, and never pass \`--discard --yes\` on your own: together
+they discard uncommitted changes and force-delete an unmerged branch.
+`
+}
+
+function skillPath(agent, project) {
+  const base = project ? discoverRepository().primaryPath : homedir()
+  return join(base, SKILL_DIRECTORIES[agent], "skills", "gwt", "SKILL.md")
+}
+
+async function installSkill(agent, args) {
+  const { options, positionals } = parseOptions(args, {
+    "--project": "boolean",
+    "--dry-run": "boolean",
+    "--yes": "boolean",
+  })
+  if (positionals.length > 0) throw new CliError(SKILL_USAGE)
+
+  const path = skillPath(agent, options.project)
+  const contents = agentSkill()
+  const existing = existsSync(path) ? readFileSync(path, "utf8") : null
+  if (existing === contents) {
+    console.log(`Skill is already installed in ${path}`)
+    return
+  }
+
+  const verb = existing === null ? "Create" : "Replace"
+  console.log(`${verb} ${path}`)
+  if (options["dry-run"]) {
+    console.log(`\n${contents}`)
+    return
+  }
+  if (!options.yes && !(await ask(`${verb}? [y/N] `))) throw new CliError("Skill installation cancelled")
+
+  mkdirSync(dirname(path), { recursive: true })
+  writeFileSync(path, contents)
+  console.log(`Installed skill in ${path}`)
+}
+
+async function commandSkill(args) {
+  if (args[0] === "install" && Object.hasOwn(SKILL_DIRECTORIES, args[1])) {
+    return installSkill(args[1], args.slice(2))
+  }
+  throw new CliError(SKILL_USAGE)
+}
+
 function zshConfigPath() {
   return join(process.env.ZDOTDIR ? resolve(process.env.ZDOTDIR) : homedir(), ".zshrc")
 }
@@ -1169,10 +1308,15 @@ function commandComplete(args) {
   throw new CliError("Invalid completion request")
 }
 
+function version() {
+  const path = join(import.meta.dirname, "..", "package.json")
+  return JSON.parse(readFileSync(path, "utf8")).version
+}
+
 function help(command, subcommand) {
   const topic = [command, subcommand].filter(Boolean).join(" ")
   const texts = {
-    "": `gwt ${VERSION} - lightweight native Git worktree workflows
+    "": `gwt ${version()} - lightweight native Git worktree workflows
 
 Usage:
   gwt <command> [options]
@@ -1187,6 +1331,7 @@ Commands:
   trust     Approve or revoke repository project hooks
   config    Create or inspect configuration
   shell     Install shell integration
+  skill     Install the gwt skill for coding agents
 
 Options:
   -h, --help      Show help.
@@ -1198,6 +1343,7 @@ Examples:
   gwt remove
   gwt config create
   gwt shell install zsh
+  gwt skill install claude
 
 Run 'gwt <command> --help' for command behavior and more examples.`,
     new: `Create a worktree, prepare its development environment, and switch to it.
@@ -1311,9 +1457,10 @@ Options:
 
 Behavior:
   Without --discard, dirty worktrees are rejected and branches are deleted only
-  when 'git branch -d' considers deletion safe. The primary worktree cannot be
-  removed. Removing the current worktree returns an integrated shell to the
-  primary worktree.
+  when 'git branch -d' considers deletion safe. If safe deletion fails, an
+  interactive terminal asks whether to force-delete the branch; non-interactive
+  use keeps it. The primary worktree cannot be removed. Removing the current
+  worktree returns an integrated shell to the primary worktree.
 
 Examples:
   gwt remove
@@ -1417,6 +1564,50 @@ when ZDOTDIR is set. Restart Zsh or source the file after installation.
 Examples:
   gwt shell install zsh
   gwt shell install zsh --dry-run`,
+    skill: `Install the gwt skill so coding agents use gwt correctly.
+
+Usage:
+  gwt skill install <claude|codex> [--project] [--dry-run] [--yes]
+
+Options:
+  -h, --help      Show help for this command.
+
+The skill teaches an agent to prefer gwt over native 'git worktree', to read
+'gwt <command> --help' for command details, and to treat removal as
+destructive. It does not duplicate command signatures, so it stays accurate
+as gwt changes.
+
+Examples:
+  gwt skill install claude
+  gwt skill install codex`,
+    "skill install": `Install the gwt skill for a coding agent.
+
+Usage:
+  gwt skill install <claude|codex> [--project] [--dry-run] [--yes]
+
+Arguments:
+  claude          Install for Claude Code, under .claude/skills.
+  codex           Install for Codex, under .agents/skills.
+
+Options:
+  --project       Write the skill inside the primary worktree, so it can be
+                  committed for the team, instead of the home directory.
+  --dry-run       Print the target path and the skill without writing it.
+  --yes           Install without asking for confirmation.
+  -h, --help      Show help for this command.
+
+Both agents read the same SKILL.md format and only differ in location, so the
+installed skill is identical. Install it once per agent.
+
+Reinstall after upgrading gwt to pick up a revised skill. The command reports
+an unchanged file as already installed and asks before replacing a modified
+one.
+
+Examples:
+  gwt skill install claude
+  gwt skill install codex
+  gwt skill install codex --project
+  gwt skill install claude --dry-run`,
   }
 
   if (!Object.hasOwn(texts, topic)) throw new CliError(`Unknown help topic: ${topic}`)
@@ -1427,9 +1618,9 @@ async function main() {
   const [command, ...args] = process.argv.slice(2)
   if (!command || command === "--help" || command === "-h") return help()
   if (command === "help") return help(args[0], args[1])
-  if (command === "--version" || command === "-V") return console.log(VERSION)
+  if (command === "--version" || command === "-V") return console.log(version())
   if (args.includes("--help") || args.includes("-h")) {
-    const subcommand = ["config", "shell"].includes(command)
+    const subcommand = ["config", "shell", "skill"].includes(command)
       ? args.find((argument) => !argument.startsWith("-"))
       : undefined
     return help(command, subcommand)
@@ -1443,6 +1634,7 @@ async function main() {
   if (command === "trust") return commandTrust(args)
   if (command === "config") return commandConfig(args)
   if (command === "shell") return commandShell(args)
+  if (command === "skill") return commandSkill(args)
   if (command === "__complete") return commandComplete(args)
   throw new CliError(`Unknown command: ${command}`)
 }

package/package.json

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