opencode-gitwt 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 voischev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,144 @@
-# Temporary Holding Version
+# opencode-gitwt
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Тонкая обёртка над `git worktree` для OpenCode и CLI. Подход как в `arc-wt`:
+создать отдельный checkout, проверить его, получить путь и продолжить работу
+в текущей сессии. Git остаётся единственным реестром worktree.
+
+Требования: Node.js от 22.14, Git, OpenCode от 1.19.3 до 2.0.
+
+## Подключение
+
+После первого релиза в npm добавьте в `opencode.json`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["opencode-gitwt@0.1.0"]
+}
+```
+
+Для установки из SourceCraft используйте Git-spec вместо имени пакета:
+
+```text
+git+https://git@git.sourcecraft.dev/voischev/opencode-gitwt.git#<commit>
+```
+
+Замените `<commit>` нужным хешем. Сборка и install-скрипты не нужны.
+Для локальной разработки укажите `file://`-путь к `src/index.js`.
+После подключения перезапустите OpenCode.
+
+## Работа агента
+
+- `gitwt_create`: создать новую ветку и worktree, проверить корень, ветку и HEAD,
+  вернуть `worktreePath`.
+- `gitwt_list`: показать реестр Git; `status: true` добавляет live-статус.
+- `gitwt_cd`: найти точную ветку или полный путь, вернуть путь, HEAD и статус.
+- `gitwt_remove`: явно удалить конкретный worktree, убедившись, что он больше
+  не используется.
+
+```json
+{ "branch": "feature/login", "base": "main" }
+```
+
+Агент продолжает ту же сессию. Возвращённый путь нужно использовать в `workdir`
+команд и в путях файловых инструментов. `gitwt_cd` только находит каталог:
+он не меняет cwd процесса или контекст сессии. Завершение ответа, чистый статус
+или merge ветки не являются командой на удаление. При паузе и передаче задачи
+сохраните worktree и передайте его путь, ветку и оставшуюся работу.
+
+## CLI
+
+После публикации: `npm install -g opencode-gitwt`. Из клона: `node bin/git-wt.js`.
+
+```bash
+git-wt add feature/login --base main --json
+git-wt add review-copy --from origin/feature/login --path "/tmp/review copy"
+git-wt list --status --json
+git-wt cd feature/login
+git-wt hooks feature/login
+git-wt remove feature/login
+git-wt config
+```
+
+`add` всегда создаёт новую ветку. Для существующей работы укажите проверенный
+ref или commit в `--from`, а новой копии дайте другое имя. По умолчанию база
+обновляется из remote: `trunk`, затем `main`, затем `master`, затем remote HEAD.
+Fetch повторяется один раз при ошибке. Грязный исходный checkout не мешает
+созданию, его изменения не переносятся. Ошибка создания может оставить копию:
+сначала осмотрите сообщённый путь, не повторяйте создание вслепую.
+
+`--path` — полный путь копии; `--dir` — базовый каталог. Без них используется
+`~/git-wt/<имя-репо>-<id>/<ветка>`. Имена веток сохраняются и проверяются Git.
+`--remote` и `--prefix` переопределяют настройки.
+
+`cd` печатает только каталог. `--json` выдаёт один JSON-объект или массив,
+ошибки идут в stderr с ненулевым exit code. `list --porcelain` также выдаёт
+JSON-массив. Неизвестные ahead/behind отсутствуют в ответе, а не равны нулю.
+
+## Опциональные хуки
+
+Один формат настроек: JSONC. Приоритет: значения по умолчанию →
+`~/.config/opencode/gitwt.jsonc` → `.opencode/gitwt.jsonc` исходного checkout →
+параметры плагина → аргументы операции.
+
+```jsonc
+{
+  "remote": "origin",
+  "base": "auto",
+  "worktreeDir": "~/worktrees",
+  "hooks": {
+    "postCreate": [["npm", "ci"]],
+    "preRemove": [["docker", "compose", "down"]]
+  }
+}
+```
+
+Команда — argv-массив или явная shell-строка (`bash -c` / `cmd /c`).
+В хуках доступны `BRANCH`, `WORKTREE_PATH`, `HEAD`; в postCreate дополнительно
+`SOURCE_PATH`. cwd — целевой worktree. Подготовку окружения, например копирование
+локального `.env`, при необходимости выполняет postCreate.
+
+Снимок обоих хуков сохраняется в служебном каталоге конкретного Git worktree,
+не в рабочих файлах. Текущий конфиг не подменяет preRemove существующей копии.
+`add --no-hooks` явно сохраняет отключённые хуки; ради JSON отключать их не надо.
+Ошибка postCreate возвращается предупреждением при сохранённой копии.
+Ошибка preRemove блокирует удаление даже с `--force`.
+
+`hooks` — read-only диагностика без текста команд. Только `snapshot: "present"`
+и `preRemove: "none"` подтверждают сохранённое отключение. У вручную созданного
+worktree снимка может не быть; это не считается доказательством отключения.
+Повреждённый снимок вызывает ошибку, автоматически не исправляется.
+
+## Удаление
+
+Удаление выполняется сразу и только явно. Основной и текущий worktree защищены;
+удаляйте из другого checkout. Dirty проверяется до и после preRemove.
+`--force` разрешает потерю локальных изменений, но не обходит ошибку хука.
+После удаления используется `git branch -d`: неслитая ветка сохраняется
+с предупреждением. `--keep-branch` оставляет ветку в любом случае.
+
+Терминалы, перенос сессий, lease, отдельная база состояний и очистка по idle
+не используются. Нет автокоммитов, push, reset и фонового удаления.
+
+## Проверка и npm-релиз
+
+```bash
+npm ci --ignore-scripts
+npm run check
+npm test
+node scripts/release.js --check
+```
+
+Тесты используют реальные временные Git-репозитории. При наличии OpenCode
+1.19.3 smoke-тест проверяет регистрацию инструментов в изолированном сервере
+без LLM. Для сквозной Git-установки задайте `GITWT_TEST_PLUGIN_SPEC` равным
+Git-spec и запустите `node --test test/plugin.test.js`.
+
+SourceCraft CI проверяет PR и main. Для публикации добавьте granular npm-токен
+в секрет репозитория `NPM_TOKEN`, влейте PR и отправьте тег версии `v0.1.0`.
+Workflow проверяет тесты, линт, тег/HEAD, историю origin/main и tarball перед
+публикацией. Токен доступен только кубику publish, временный `.npmrc` создаётся
+вне репозитория. npm Trusted Publishing для SourceCraft не поддерживается.
+
+Репозиторий:
+https://sourcecraft.dev/voischev/opencode-gitwt

package/bin/git-wt.js

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+import { parseArgs } from "node:util";
+import { loadConfig } from "../src/config.js";
+import {
+  createWorktree,
+  inspectHooks,
+  listWorktrees,
+  removeWorktree,
+  repository,
+  resolveWorktree,
+} from "../src/worktree.js";
+
+const machine = process.argv.includes("--json") || process.argv.includes("--porcelain");
+
+async function main() {
+  const {
+    values,
+    positionals: [command, target, ...extra],
+  } = parseArgs({
+    allowPositionals: true,
+    options: {
+      json: { type: "boolean" },
+      porcelain: { type: "boolean" },
+      status: { type: "boolean" },
+      remote: { type: "string" },
+      base: { type: "string" },
+      from: { type: "string" },
+      prefix: { type: "string" },
+      path: { type: "string" },
+      dir: { type: "string" },
+      "no-hooks": { type: "boolean" },
+      force: { type: "boolean" },
+      "keep-branch": { type: "boolean" },
+      help: { type: "boolean", short: "h" },
+    },
+  });
+  if (!command || values.help) {
+    process.stdout.write(
+      "git-wt add <ветка> [--base <remote-ветка> | --from <ref>] [--path <путь> | --dir <каталог>] [--no-hooks] [--json]\ngit-wt list [--status] [--json | --porcelain]\ngit-wt cd <ветка|путь>\ngit-wt hooks <ветка|путь>\ngit-wt remove <ветка|путь> [--force] [--keep-branch]\ngit-wt config\n",
+    );
+    return;
+  }
+  if (extra.length || (!["add", "cd", "remove", "hooks"].includes(command) && target))
+    throw new Error("Лишние позиционные аргументы");
+  if (values["no-hooks"] && command !== "add")
+    throw new Error("--no-hooks допустим только при создании worktree");
+  const cwd = process.cwd();
+  const config = {
+    remote: values.remote,
+    base: values.base,
+    prefix: values.prefix,
+    worktreeDir: values.dir,
+  };
+  let result;
+  switch (command) {
+    case "add":
+      result = await createWorktree(cwd, {
+        branch: target,
+        path: values.path,
+        from: values.from,
+        noHooks: values["no-hooks"],
+        config,
+      });
+      break;
+    case "list":
+      result = await listWorktrees(cwd, { status: values.status });
+      break;
+    case "cd":
+      result = await resolveWorktree(cwd, target);
+      break;
+    case "hooks":
+      result = await inspectHooks(cwd, target);
+      break;
+    case "remove":
+      result = await removeWorktree(cwd, target, {
+        force: values.force,
+        deleteBranch: !values["keep-branch"],
+      });
+      break;
+    case "config":
+      result = await loadConfig((await repository(cwd)).root, config);
+      break;
+    default:
+      throw new Error(`Неизвестная команда: ${command}`);
+  }
+  process.stdout.write(
+    command === "cd" && !machine
+      ? `${result.worktreePath}\n`
+      : `${JSON.stringify(result, null, machine ? 0 : 2)}\n`,
+  );
+}
+
+main().catch((error) => {
+  process.stderr.write(
+    machine
+      ? `${JSON.stringify({ code: error.code ?? "unexpected_error", error: error.message, ...error.details })}\n`
+      : `Ошибка: ${error.message}\n`,
+  );
+  process.exitCode = 1;
+});

package/package.json

@@ -1,6 +1,55 @@
 {
   "name": "opencode-gitwt",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Git worktree для OpenCode: создать, проверить, вернуть путь и явно удалить",
+  "type": "module",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./server": "./src/index.js"
+  },
+  "bin": {
+    "git-wt": "./bin/git-wt.js"
+  },
+  "files": [
+    "src",
+    "bin",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22.14.0",
+    "opencode": ">=1.19.3 <2"
+  },
+  "scripts": {
+    "check": "biome check .",
+    "test": "node --test",
+    "release": "node scripts/release.js"
+  },
+  "dependencies": {
+    "jsonc-parser": "3.3.1",
+    "zod": "4.1.8"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.6.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://git@git.sourcecraft.dev/voischev/opencode-gitwt.git"
+  },
+  "homepage": "https://sourcecraft.dev/voischev/opencode-gitwt",
+  "bugs": {
+    "url": "https://sourcecraft.dev/voischev/opencode-gitwt/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "git",
+    "worktree"
+  ],
+  "license": "MIT"
+}

package/src/config.js

@@ -0,0 +1,69 @@
+import { readFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { parse } from "jsonc-parser";
+import { z } from "zod";
+import { GitwtError } from "./process.js";
+
+const command = z.union([z.string().min(1), z.tuple([z.string().min(1)]).rest(z.string())]);
+export const hooksSchema = z
+  .object({
+    postCreate: z.array(command).default([]),
+    preRemove: z.array(command).default([]),
+  })
+  .strict();
+const schema = z
+  .object({
+    remote: z
+      .string()
+      .regex(/^[a-zA-Z0-9_][a-zA-Z0-9._-]*$/)
+      .default("origin"),
+    base: z.string().min(1).default("auto"),
+    prefix: z.string().default(""),
+    worktreeDir: z.string().min(1).optional(),
+    hooks: hooksSchema.default({ postCreate: [], preRemove: [] }),
+  })
+  .strict();
+
+export function expandPath(value, home = os.homedir(), base = process.cwd()) {
+  if (value === "~") return home;
+  return path.resolve(
+    value.startsWith("~/") ? home : base,
+    value.startsWith("~/") ? value.slice(2) : value,
+  );
+}
+
+async function readConfig(file) {
+  try {
+    const errors = [];
+    const value = parse(await readFile(file, "utf8"), errors, { allowTrailingComma: true });
+    if (errors.length || !value || typeof value !== "object" || Array.isArray(value)) {
+      throw new Error("Ожидается объект JSONC");
+    }
+    return value;
+  } catch (error) {
+    if (error.code === "ENOENT") return {};
+    throw new GitwtError("invalid_config", `Не удалось прочитать ${file}: ${error.message}`);
+  }
+}
+
+export async function loadConfig(root, overrides = {}, home = os.homedir()) {
+  const config = { hooks: {} };
+  for (const value of [
+    await readConfig(path.join(home, ".config/opencode/gitwt.jsonc")),
+    await readConfig(path.join(root, ".opencode/gitwt.jsonc")),
+    Object.fromEntries(Object.entries(overrides).filter(([, value]) => value !== undefined)),
+  ]) {
+    const checked = schema.partial().safeParse(value);
+    if (!checked.success)
+      throw new GitwtError(
+        "invalid_config",
+        `Некорректные настройки: ${checked.error.issues.map((issue) => issue.path.join(".") || "неизвестное поле").join(", ")}`,
+      );
+    const hooks = { ...config.hooks, ...value.hooks };
+    Object.assign(config, value, { hooks });
+  }
+  const resolved = schema.parse(config);
+  if (resolved.worktreeDir) resolved.worktreeDir = expandPath(resolved.worktreeDir, home, root);
+  return resolved;
+}

package/src/environment.js

@@ -0,0 +1,12 @@
+import { run } from "./process.js";
+
+export async function runHooks(commands, cwd, env, signal) {
+  for (const command of commands) {
+    const argv = Array.isArray(command)
+      ? command
+      : process.platform === "win32"
+        ? [process.env.ComSpec ?? "cmd.exe", "/d", "/s", "/c", command]
+        : ["bash", "-c", command];
+    await run(argv[0], argv.slice(1), { cwd, env, signal });
+  }
+}

package/src/index.js

@@ -0,0 +1,66 @@
+import { z } from "zod";
+import { createWorktree, listWorktrees, removeWorktree, resolveWorktree } from "./worktree.js";
+
+export async function GitwtPlugin({ directory }, config = {}) {
+  return {
+    tool: {
+      gitwt_create: {
+        description:
+          "Создать и проверить новый worktree. Продолжайте текущую сессию, используя возвращённый worktreePath в командах и файловых операциях. Сохраняйте worktree при паузе и передаче задачи.",
+        args: {
+          branch: z.string().describe("Имя новой ветки"),
+          base: z.string().optional().describe("Базовая remote-ветка"),
+          from: z
+            .string()
+            .optional()
+            .describe("Явная локальная ссылка или проверенный commit вместо remote-базы"),
+          path: z.string().optional().describe("Полный путь нового worktree"),
+          noHooks: z.boolean().optional().describe("Явно отключить хуки для создаваемого worktree"),
+        },
+        execute: async (args, ctx) =>
+          JSON.stringify(
+            await createWorktree(ctx.directory ?? directory, {
+              ...args,
+              signal: ctx.abort,
+              config: { ...config, base: args.base ?? config.base },
+            }),
+          ),
+      },
+      gitwt_list: {
+        description:
+          "Показать worktree из реестра Git. status добавляет dirty и доступные ahead/behind; отсутствие этих полей означает неизвестное состояние.",
+        args: { status: z.boolean().optional() },
+        execute: async (args, ctx) =>
+          JSON.stringify(await listWorktrees(ctx.directory ?? directory, args)),
+      },
+      gitwt_cd: {
+        description:
+          "Найти worktree по точной ветке или полному пути и вернуть его путь, HEAD и статус. Каталог текущей сессии не меняется: используйте worktreePath явно.",
+        args: { target: z.string() },
+        execute: async ({ target }, ctx) =>
+          JSON.stringify(
+            await resolveWorktree(ctx.directory ?? directory, target, { status: true }),
+          ),
+      },
+      gitwt_remove: {
+        description:
+          "Только по явной просьбе удалить указанный worktree, убедившись, что он больше не используется. force разрешает потерю изменений, но не обходит ошибку preRemove. Без автокоммитов и отложенной очистки.",
+        args: {
+          target: z.string(),
+          force: z.boolean().optional(),
+          keepBranch: z.boolean().optional(),
+        },
+        execute: async ({ target, force, keepBranch }, ctx) =>
+          JSON.stringify(
+            await removeWorktree(ctx.directory ?? directory, target, {
+              force,
+              deleteBranch: !keepBranch,
+              signal: ctx.abort,
+            }),
+          ),
+      },
+    },
+  };
+}
+
+export default { id: "opencode-gitwt", server: GitwtPlugin };

package/src/process.js

@@ -0,0 +1,41 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const execute = promisify(execFile);
+
+export class GitwtError extends Error {
+  constructor(code, message, details = {}) {
+    super(message);
+    this.name = "GitwtError";
+    this.code = code;
+    this.details = details;
+  }
+}
+
+export async function run(command, args = [], options = {}) {
+  try {
+    const result = await execute(command, args, {
+      cwd: options.cwd,
+      env: options.env ? { ...process.env, ...options.env } : process.env,
+      signal: options.signal,
+      timeout: options.timeout ?? 120_000,
+      maxBuffer: 16 * 1024 * 1024,
+      encoding: "utf8",
+      windowsHide: true,
+    });
+    return { ...result, code: 0 };
+  } catch (error) {
+    if (options.allowFailure && typeof error.code === "number") {
+      return { stdout: error.stdout ?? "", stderr: error.stderr ?? "", code: error.code };
+    }
+    throw new GitwtError(
+      "command_failed",
+      `Команда ${command} завершилась с ошибкой: ${error.stderr?.trim() || error.message}`,
+      { command, exitCode: error.code },
+    );
+  }
+}
+
+export function git(args, cwd, options = {}) {
+  return run("git", args, { ...options, cwd });
+}

package/src/worktree.js

@@ -0,0 +1,287 @@
+import { createHash } from "node:crypto";
+import { lstat, mkdir, readFile, realpath, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { expandPath, hooksSchema, loadConfig } from "./config.js";
+import { runHooks } from "./environment.js";
+import { GitwtError, git } from "./process.js";
+
+export async function repository(cwd) {
+  const root = await git(["rev-parse", "--show-toplevel"], cwd);
+  const common = await git(["rev-parse", "--path-format=absolute", "--git-common-dir"], cwd);
+  return {
+    root: await realpath(root.stdout.trim()),
+    commonDir: await realpath(common.stdout.trim()),
+  };
+}
+
+export function parseWorktrees(text) {
+  return text
+    .split("\0\0")
+    .filter(Boolean)
+    .map((block) => {
+      const item = {};
+      for (const field of block.split("\0").filter(Boolean)) {
+        const space = field.indexOf(" ");
+        const key = space < 0 ? field : field.slice(0, space);
+        const value = space < 0 ? true : field.slice(space + 1);
+        if (key === "worktree") item.worktreePath = value;
+        if (key === "HEAD") item.head = value;
+        if (key === "branch") item.branch = value.replace(/^refs\/heads\//, "");
+        if (["detached", "locked", "prunable", "bare"].includes(key)) item[key] = value;
+      }
+      return item;
+    });
+}
+
+export async function listWorktrees(cwd, { status = false } = {}) {
+  const repo = await repository(cwd);
+  const items = parseWorktrees(
+    (await git(["worktree", "list", "--porcelain", "-z"], repo.root)).stdout,
+  );
+  for (const item of items) {
+    item.current = item.worktreePath === repo.root;
+    if (!status || "prunable" in item || item.bare) continue;
+    item.dirty = Boolean((await git(["status", "--porcelain", "-z"], item.worktreePath)).stdout);
+    const upstream = await git(
+      ["rev-list", "--left-right", "--count", "HEAD...@{upstream}"],
+      item.worktreePath,
+      { allowFailure: true },
+    );
+    if (upstream.code === 0)
+      [item.ahead, item.behind] = upstream.stdout.trim().split(/\s+/).map(Number);
+  }
+  return items;
+}
+
+export async function resolveWorktree(cwd, target, options) {
+  if (typeof target !== "string" || !target)
+    throw new GitwtError("invalid_target", "Укажите ветку или полный путь worktree");
+  const expanded = expandPath(target, os.homedir(), cwd);
+  const fullPath = await realpath(expanded).catch((error) => {
+    if (error.code !== "ENOENT") throw error;
+    return expanded;
+  });
+  const matches = (await listWorktrees(cwd, options)).filter(
+    (item) => item.branch === target || item.worktreePath === fullPath,
+  );
+  if (matches.length !== 1)
+    throw new GitwtError("worktree_missing", `Worktree не найден или имя неоднозначно: ${target}`);
+  if ("prunable" in matches[0])
+    throw new GitwtError(
+      "worktree_missing",
+      `Каталог worktree недоступен: ${matches[0].worktreePath}`,
+    );
+  await realpath(matches[0].worktreePath);
+  return matches[0];
+}
+
+async function validBranch(branch, cwd) {
+  if (typeof branch !== "string" || !branch || branch.startsWith("-"))
+    throw new GitwtError("invalid_name", "Укажите корректное имя ветки");
+  if (
+    (await git(["check-ref-format", `refs/heads/${branch}`], cwd, { allowFailure: true })).code !==
+    0
+  ) {
+    throw new GitwtError("invalid_name", `Недопустимое имя ветки: ${branch}`);
+  }
+}
+
+async function retryGit(args, cwd, signal) {
+  let result;
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    result = await git(args, cwd, { allowFailure: true, signal });
+    if (result.code === 0) return result;
+    signal?.throwIfAborted();
+  }
+  throw new GitwtError(
+    "fetch_failed",
+    `Git ${args[0]} завершился с ошибкой после двух попыток: ${result.stderr.trim()}`,
+  );
+}
+
+async function baseReference(cwd, config, { from, signal }) {
+  if (from) {
+    if (from.startsWith("-")) throw new GitwtError("invalid_base", "Недопустимая стартовая ссылка");
+    return (
+      await git(["rev-parse", "--verify", `${from}^{commit}`], cwd, { signal })
+    ).stdout.trim();
+  }
+  let base = config.base;
+  if (base === "auto") {
+    const refs = await retryGit(
+      ["ls-remote", "--heads", config.remote, "trunk", "main", "master"],
+      cwd,
+      signal,
+    );
+    base = ["trunk", "main", "master"].find((name) =>
+      refs.stdout.split("\n").some((line) => line.endsWith(`refs/heads/${name}`)),
+    );
+    if (!base) {
+      const head = await retryGit(["ls-remote", "--symref", config.remote, "HEAD"], cwd, signal);
+      base = head.stdout.match(/^ref: refs\/heads\/(.+)\tHEAD$/m)?.[1];
+    }
+  }
+  if (!base)
+    throw new GitwtError("base_missing", "Не удалось определить базовую ветку; укажите --base");
+  await validBranch(base, cwd);
+  const ref = `refs/remotes/${config.remote}/${base}`;
+  await retryGit(["fetch", "--no-tags", config.remote, `${base}:${ref}`], cwd, signal);
+  return (await git(["rev-parse", "--verify", `${ref}^{commit}`], cwd)).stdout.trim();
+}
+
+async function hookFile(cwd) {
+  return (
+    await git(
+      ["rev-parse", "--path-format=absolute", "--git-path", "opencode-gitwt-hooks.json"],
+      cwd,
+    )
+  ).stdout.trim();
+}
+
+async function readHooks(cwd) {
+  try {
+    return hooksSchema.parse(JSON.parse(await readFile(await hookFile(cwd), "utf8")));
+  } catch (error) {
+    if (error.code === "ENOENT") return null;
+    throw new GitwtError("invalid_hooks", `Не удалось прочитать снимок хуков: ${error.message}`);
+  }
+}
+
+export async function inspectHooks(cwd, target) {
+  const item = await resolveWorktree(cwd, target);
+  const hooks = await readHooks(item.worktreePath);
+  return {
+    worktreePath: item.worktreePath,
+    snapshot: hooks ? "present" : "absent",
+    postCreate: hooks ? (hooks.postCreate.length ? "configured" : "none") : "unknown",
+    preRemove: hooks ? (hooks.preRemove.length ? "configured" : "none") : "unknown",
+  };
+}
+
+export async function createWorktree(cwd, options = {}) {
+  const repo = await repository(cwd);
+  const home = options.home ?? os.homedir();
+  const config = await loadConfig(repo.root, options.config, home);
+  const branch = `${config.prefix}${options.branch ?? ""}`;
+  await validBranch(options.branch, repo.root);
+  await validBranch(branch, repo.root);
+  if (
+    (
+      await git(["show-ref", "--verify", "--quiet", `refs/heads/${branch}`], repo.root, {
+        allowFailure: true,
+      })
+    ).code === 0
+  ) {
+    throw new GitwtError(
+      "branch_exists",
+      `Ветка ${branch} уже существует; создайте новую от нужной базы`,
+    );
+  }
+  const primary = (await listWorktrees(repo.root))[0].worktreePath;
+  const id = createHash("sha256").update(repo.commonDir).digest("hex").slice(0, 8);
+  const target = options.path
+    ? expandPath(options.path, home, repo.root)
+    : path.join(
+        config.worktreeDir ?? path.join(home, "git-wt"),
+        `${path.basename(primary)}-${id}`,
+        branch,
+      );
+  const existing = await lstat(target).catch((error) => {
+    if (error.code !== "ENOENT") throw error;
+  });
+  if (existing || (await listWorktrees(repo.root)).some((item) => item.worktreePath === target)) {
+    throw new GitwtError("worktree_exists", `Путь уже занят: ${target}`);
+  }
+  const head = await baseReference(repo.root, config, options);
+  await mkdir(path.dirname(target), { recursive: true });
+  const worktreePath = path.join(await realpath(path.dirname(target)), path.basename(target));
+  const hooks = options.noHooks ? { postCreate: [], preRemove: [] } : config.hooks;
+  try {
+    await git(
+      ["worktree", "add", "--no-track", "-b", branch, "--", worktreePath, head],
+      repo.root,
+      { signal: options.signal },
+    );
+    const actualRoot = (await git(["rev-parse", "--show-toplevel"], worktreePath)).stdout.trim();
+    const actualBranch = (await git(["branch", "--show-current"], worktreePath)).stdout.trim();
+    const actualHead = (await git(["rev-parse", "HEAD"], worktreePath)).stdout.trim();
+    const actual = await resolveWorktree(repo.root, worktreePath);
+    if (
+      (await realpath(actualRoot)) !== worktreePath ||
+      actualBranch !== branch ||
+      actualHead !== head ||
+      actual.branch !== branch ||
+      actual.head !== head
+    ) {
+      throw new GitwtError("verification_failed", "Проверка корня, ветки или HEAD не прошла");
+    }
+    await writeFile(await hookFile(worktreePath), `${JSON.stringify(hooks)}\n`, {
+      flag: "wx",
+      mode: 0o600,
+    });
+  } catch (error) {
+    throw new GitwtError(
+      "worktree_create_failed",
+      `Создание ${worktreePath} завершилось ошибкой; проверьте этот путь перед повтором: ${error.message}`,
+      { worktreePath },
+    );
+  }
+  const warnings = [];
+  try {
+    await runHooks(
+      hooks.postCreate,
+      worktreePath,
+      { BRANCH: branch, WORKTREE_PATH: worktreePath, HEAD: head, SOURCE_PATH: repo.root },
+      options.signal,
+    );
+  } catch (error) {
+    warnings.push(`Worktree создан, но postCreate завершился с ошибкой: ${error.message}`);
+  }
+  return { branch, worktreePath, head, warnings };
+}
+
+export async function removeWorktree(cwd, target, options = {}) {
+  const repo = await repository(cwd);
+  const items = await listWorktrees(repo.root);
+  const item = await resolveWorktree(repo.root, target);
+  if (item.worktreePath === items[0].worktreePath || item.current) {
+    throw new GitwtError(
+      "protected_worktree",
+      "Нельзя удалить основной или текущий worktree; запустите удаление из другого worktree",
+    );
+  }
+  const assertClean = async () => {
+    if (!options.force && (await git(["status", "--porcelain", "-z"], item.worktreePath)).stdout) {
+      throw new GitwtError(
+        "worktree_dirty",
+        "Worktree содержит изменения; явный --force удалит их",
+      );
+    }
+  };
+  const hooks = await readHooks(item.worktreePath);
+  await assertClean();
+  await runHooks(
+    hooks?.preRemove ?? [],
+    item.worktreePath,
+    { BRANCH: item.branch ?? "", WORKTREE_PATH: item.worktreePath, HEAD: item.head },
+    options.signal,
+  );
+  await assertClean();
+  await git(
+    ["worktree", "remove", ...(options.force ? ["--force"] : []), "--", item.worktreePath],
+    repo.root,
+    { signal: options.signal },
+  );
+  const warnings = [];
+  let branchDeleted = false;
+  if (item.branch && options.deleteBranch !== false) {
+    const result = await git(["branch", "-d", "--", item.branch], repo.root, {
+      allowFailure: true,
+    });
+    branchDeleted = result.code === 0;
+    if (!branchDeleted)
+      warnings.push(`Worktree удалён, ветка ${item.branch} сохранена: ${result.stderr.trim()}`);
+  }
+  return { worktreePath: item.worktreePath, branch: item.branch, branchDeleted, warnings };
+}