wendkeep 0.75.2 → 0.76.0

package/packages/vault/src/worktree-metadata.mjs

@@ -0,0 +1,274 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+
+export const WORKTREE_REGISTRY_SCHEMA = 1;
+export const WORKTREE_REGISTRY_REL = 'wendkeep/worktrees-v1.json';
+
+function worktreeError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+function gitOutput(startDir, args, spawn = spawnSync) {
+  const result = spawn('git', args, {
+    cwd: startDir,
+    encoding: 'utf8',
+    windowsHide: true,
+  });
+  if (result.status !== 0) {
+    throw worktreeError(
+      'WENDKEEP_WORKTREE_GIT_FAILED',
+      String(result.stderr || result.error?.message || `git ${args[0]} falhou`).trim(),
+    );
+  }
+  return String(result.stdout || '').trim();
+}
+
+function absoluteGitPath(repoRoot, value) {
+  return resolve(isAbsolute(value) ? value : join(repoRoot, value));
+}
+
+function parseWorktreeList(text) {
+  const records = [];
+  let current = null;
+  for (const line of String(text || '').split(/\r?\n/)) {
+    if (line.startsWith('worktree ')) {
+      current = { path: resolve(line.slice('worktree '.length)) };
+      records.push(current);
+    } else if (current && line.startsWith('HEAD ')) {
+      current.head = line.slice('HEAD '.length);
+    } else if (current && line.startsWith('branch ')) {
+      current.branch = line.slice('branch '.length).replace(/^refs\/heads\//, '');
+    } else if (current && line === 'bare') {
+      current.bare = true;
+    } else if (current && line === 'detached') {
+      current.detached = true;
+    }
+  }
+  return records;
+}
+
+export function discoverWorktreeRepository({ startDir = process.cwd(), spawn = spawnSync } = {}) {
+  const repoRoot = resolve(gitOutput(startDir, ['rev-parse', '--show-toplevel'], spawn));
+  const commonDir = absoluteGitPath(
+    repoRoot,
+    gitOutput(repoRoot, ['rev-parse', '--git-common-dir'], spawn),
+  );
+  const gitDir = absoluteGitPath(
+    repoRoot,
+    gitOutput(repoRoot, ['rev-parse', '--git-dir'], spawn),
+  );
+  const worktrees = parseWorktreeList(gitOutput(repoRoot, ['worktree', 'list', '--porcelain'], spawn));
+  const main = worktrees.find((entry) => !entry.bare) || null;
+  if (!main) {
+    throw worktreeError(
+      'WENDKEEP_WORKTREE_MAIN_UNRESOLVED',
+      'Não foi possível localizar a worktree principal do repositório.',
+    );
+  }
+  return {
+    repoRoot,
+    commonDir,
+    gitDir,
+    mainWorktree: main.path,
+    worktrees,
+  };
+}
+
+function sleep(milliseconds) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, milliseconds);
+}
+
+export function withWorktreeRegistryLock(registryPath, operation, {
+  timeoutMs = 5_000,
+  staleMs = 30_000,
+  now = () => Date.now(),
+} = {}) {
+  const lockPath = `${registryPath}.lock`;
+  const startedAt = now();
+  mkdirSync(dirname(registryPath), { recursive: true });
+  while (true) {
+    try {
+      mkdirSync(lockPath);
+      break;
+    } catch (error) {
+      if (error?.code !== 'EEXIST') throw error;
+      try {
+        if (now() - statSync(lockPath).mtimeMs > staleMs) {
+          rmSync(lockPath, { recursive: true, force: true });
+          continue;
+        }
+      } catch (inspectError) {
+        if (inspectError?.code !== 'ENOENT') throw inspectError;
+        continue;
+      }
+      if (now() - startedAt >= timeoutMs) {
+        throw worktreeError(
+          'WENDKEEP_WORKTREE_REGISTRY_BUSY',
+          `Registry de worktrees ocupado: ${registryPath}`,
+        );
+      }
+      sleep(20);
+    }
+  }
+  try {
+    return operation();
+  } finally {
+    rmSync(lockPath, { recursive: true, force: true });
+  }
+}
+
+function atomicJson(path, value) {
+  mkdirSync(dirname(path), { recursive: true });
+  const content = `${JSON.stringify(value, null, 2)}\n`;
+  if (existsSync(path) && readFileSync(path, 'utf8') === content) return false;
+  const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
+  writeFileSync(temporary, content, { encoding: 'utf8', flag: 'wx' });
+  renameSync(temporary, path);
+  return true;
+}
+
+function validateRegistry(value, path) {
+  if (
+    value?.schemaVersion !== WORKTREE_REGISTRY_SCHEMA
+    || typeof value.repositoryId !== 'string'
+    || !value.repositoryId
+    || typeof value.projectId !== 'string'
+    || !value.projectId
+    || typeof value.vaultPath !== 'string'
+    || !value.vaultPath
+    || !value.entries
+    || typeof value.entries !== 'object'
+    || Array.isArray(value.entries)
+  ) {
+    throw worktreeError(
+      'WENDKEEP_WORKTREE_REGISTRY_INVALID',
+      `Registry de worktrees incompleto em "${path}".`,
+    );
+  }
+  return value;
+}
+
+function parseRegistry(path) {
+  let value;
+  try {
+    value = JSON.parse(readFileSync(path, 'utf8'));
+  } catch (error) {
+    throw worktreeError(
+      'WENDKEEP_WORKTREE_REGISTRY_INVALID',
+      `Registry de worktrees inválido em "${path}": ${error.message}`,
+    );
+  }
+  return validateRegistry(value, path);
+}
+
+export function readWorktreeRegistry(repository) {
+  const path = join(repository.commonDir, ...WORKTREE_REGISTRY_REL.split('/'));
+  return existsSync(path) ? { path, registry: parseRegistry(path) } : { path, registry: null };
+}
+
+export function resolveWorktreeVaultBinding({ startDir = process.cwd(), projectId } = {}) {
+  let repository;
+  try {
+    repository = discoverWorktreeRepository({ startDir });
+  } catch (error) {
+    if (error?.code === 'WENDKEEP_WORKTREE_GIT_FAILED') return null;
+    throw error;
+  }
+  const { path, registry } = readWorktreeRegistry(repository);
+  if (!registry) return null;
+  if (registry.projectId !== projectId) {
+    throw worktreeError(
+      'WENDKEEP_WORKTREE_PROJECT_MISMATCH',
+      `Registry "${path}" pertence ao projeto "${registry.projectId}", não "${projectId}".`,
+    );
+  }
+  return {
+    base: resolve(registry.vaultPath),
+    projectId: registry.projectId,
+    repositoryId: registry.repositoryId,
+    registryPath: path,
+    projectRoot: repository.mainWorktree,
+    repository,
+  };
+}
+
+export function mutateWorktreeRegistry(repository, mutator) {
+  if (!repository?.commonDir || typeof mutator !== 'function') {
+    throw worktreeError('WENDKEEP_WORKTREE_REPOSITORY_INVALID', 'Repositório Git inválido.');
+  }
+  const registryPath = join(repository.commonDir, ...WORKTREE_REGISTRY_REL.split('/'));
+  return withWorktreeRegistryLock(registryPath, () => {
+    if (!existsSync(registryPath)) {
+      throw worktreeError(
+        'WENDKEEP_WORKTREE_REGISTRY_MISSING',
+        `Registry de worktrees ausente em "${registryPath}".`,
+      );
+    }
+    const current = parseRegistry(registryPath);
+    const next = validateRegistry(mutator(structuredClone(current)), registryPath);
+    atomicJson(registryPath, next);
+    return next;
+  });
+}
+
+export function worktreeIdentity(repositoryId, gitDir) {
+  return createHash('sha256')
+    .update(`${repositoryId}\n${resolve(gitDir).replaceAll('\\', '/').toLowerCase()}\n`)
+    .digest('hex');
+}
+
+export function ensureWorktreeMetadata({
+  repository,
+  projectId,
+  vaultPath,
+  worktreesRoot = '.worktrees',
+} = {}) {
+  if (!repository?.commonDir || !repository?.gitDir) {
+    throw worktreeError('WENDKEEP_WORKTREE_REPOSITORY_INVALID', 'Repositório Git inválido.');
+  }
+  const registryPath = join(repository.commonDir, ...WORKTREE_REGISTRY_REL.split('/'));
+  const normalizedVault = resolve(String(vaultPath || ''));
+  const registry = withWorktreeRegistryLock(registryPath, () => {
+    const current = existsSync(registryPath) ? parseRegistry(registryPath) : null;
+    if (current && current.projectId !== projectId) {
+      throw worktreeError(
+        'WENDKEEP_WORKTREE_PROJECT_MISMATCH',
+        `Registry pertence a outro projeto: ${current.projectId}.`,
+      );
+    }
+    if (current && resolve(current.vaultPath) !== normalizedVault) {
+      throw worktreeError(
+        'WENDKEEP_WORKTREE_VAULT_MISMATCH',
+        'Registry aponta para outro Vault canônico.',
+      );
+    }
+    const next = current || {
+      schemaVersion: WORKTREE_REGISTRY_SCHEMA,
+      repositoryId: randomUUID(),
+      projectId,
+      vaultPath: normalizedVault,
+      worktreesRoot,
+      entries: {},
+    };
+    atomicJson(registryPath, next);
+    return next;
+  });
+  return {
+    registryPath,
+    repositoryId: registry.repositoryId,
+    currentWorktreeId: worktreeIdentity(registry.repositoryId, repository.gitDir),
+    registry,
+  };
+}

package/src/doctor.mjs

@@ -2,6 +2,7 @@
 // harness integrity check (hooks/harness-doctor.mjs). Exits 1 on any error.
 import { resolve } from 'node:path';
 import { checkHarness, checkVaultLinks, checkSessionActivity, checkStackedFrontmatter, renderStackedFrontmatterLines, checkUnpricedModels, renderUnpricedModelLines, checkStaleDerivedSections, renderStaleDerivedSectionLines, checkSessionObservability, renderSessionObservabilityLines } from '../hooks/harness-doctor.mjs';
+import { diagnoseManagedWorktrees } from './worktree.mjs';
 import { runVaultHealth } from '../hooks/vault-health.mjs';
 import { checkSyncDefs } from './sync-defs.mjs';
 import { resolveProjectVault } from './project-vault.mjs';
@@ -133,6 +134,12 @@ export function runDoctor(argv) {
   for (const item of repairable) process.stdout.write(`  → ${item}\n`);
   for (const w of warnings) process.stdout.write(`  ! ${w}\n`);
 
+  const worktrees = diagnoseManagedWorktrees({ startDir: projectRoot });
+  process.stdout.write(`\n[worktrees] ${worktrees.initialized ? `${worktrees.issues.length} problema(s)` : 'não inicializado'}\n`);
+  for (const issue of worktrees.issues) {
+    process.stdout.write(`  → ${issue.slug}: ${issue.errorCode} — ${issue.repair}\n`);
+  }
+
   // 3. Link/graph health — órfãos que o grafo do Obsidian mostraria, com o comando de reparo.
   const links = checkVaultLinks(vaultBase);
   const graphLabel = links.graphColors === true ? 'com cores' : links.graphColors === false ? 'sem cores' : 'sem graph.json';
@@ -181,6 +188,7 @@ export function runDoctor(argv) {
     || attention.length
     || repairable.length
     || warnings.length
+    || worktrees.issues.length
     || links.derivedOrphans
     || links.artifactOrphans
     || links.graphColors === false

package/src/init.mjs

@@ -13,6 +13,7 @@ import {
   CHANGE_NUDGE_HOOKS,
   CHANGE_GATE_HOOKS,
   hookCommand,
+  hookCommandWorkingTree,
   hookCommandLocal,
   hookCommandLocalLegacy,
   codexHookSpecs,
@@ -39,6 +40,7 @@ import { seedDotcontext, globalHasDotcontext, resolveDotcontextSkipMcp, renderSe
 import { adoptSpecsState, ensureSpecsReadme, SPECS_STATE_FILE } from '../hooks/spec-core.mjs';
 import { bindProjectVault, readProjectBinding } from './project-vault.mjs';
 import { seedMemoryV2 } from './memory.mjs';
+import { installVscodeWorktreeTasks } from './worktree.mjs';
 import {
   DEFAULT_OPERATING_PROFILE,
   normalizeOperatingProfile,
@@ -66,6 +68,7 @@ function parseArgs(argv) {
     else if (a === '--force') args.force = true;
     else if (a === '--no-companions') args.noCompanions = true;
     else if (a === '--no-colors') args.noColors = true;
+    else if (a === '--vscode-worktree-tasks') args.vscodeWorktreeTasks = true;
     else if (a === '--dotcontext-mcp') args.dotcontextMcp = argv[++i];
     else if (a.startsWith('--dotcontext-mcp=')) args.dotcontextMcp = a.slice(17);
     else if (a === '--dotcontext-hooks') args.dotcontextHooks = argv[++i];
@@ -109,7 +112,19 @@ function backup(path) {
 
 // Comando preferido para um hook: node-direto quando o projeto tem o pacote local (alta
 // frequência sem cold-start de npx — ver R3 do design 0.31.0); senão o npx portátil.
+export function isWendkeepSelfCheckout(projectPath) {
+  try {
+    if (!projectPath || !existsSync(join(projectPath, 'bin', 'wendkeep.mjs'))) return false;
+    const pkg = JSON.parse(readFileSync(join(projectPath, 'package.json'), 'utf8'));
+    const bin = typeof pkg.bin === 'string' ? pkg.bin : pkg.bin?.wendkeep;
+    return pkg.name === 'wendkeep' && String(bin || '').replace(/\\/g, '/') === 'bin/wendkeep.mjs';
+  } catch {
+    return false;
+  }
+}
+
 export function hookCommandFor(name, projectPath) {
+  if (isWendkeepSelfCheckout(projectPath)) return hookCommandWorkingTree(name);
   try {
     if (projectPath && existsSync(join(projectPath, 'node_modules', 'wendkeep', 'hooks', `${name}.mjs`))) {
       return hookCommandLocal(name);
@@ -142,13 +157,22 @@ export function mergeSettings(existing, { vaultPath, withMcp, force, companions
     ...CHANGE_GATE_HOOKS,
     ...companionHookSpecs(companions, { dotcontextHookLevel }),
   ].sort((a, b) => (a.order ?? 0) - (b.order ?? 0));
+  const selfCheckout = isWendkeepSelfCheckout(projectPath);
   for (const h of allSpecs) {
+    const useWorkingTree = !h.command && selfCheckout;
     const useLocal = !h.command && h.preferLocal && localHookAvailable(h.name, projectPath);
-    const command = h.command ?? (useLocal ? 'node' : hookCommand(h.name));
-    const args = useLocal ? [localHookArg(h.name)] : undefined;
+    const command = h.command ?? (useWorkingTree
+      ? hookCommandWorkingTree(h.name)
+      : (useLocal ? 'node' : hookCommand(h.name)));
+    const args = !useWorkingTree && useLocal ? [localHookArg(h.name)] : undefined;
     // Dual-recognition: um hook nomeado é reconhecido tanto na forma npx quanto na node-direta,
     // para que trocar a forma preferida (ou re-initar noutra máquina) nunca duplique o grupo.
-    const candidates = h.command ? [h.command] : [hookCommand(h.name), hookCommandLocal(h.name), hookCommandLocalLegacy(h.name)];
+    const candidates = h.command ? [h.command] : [
+      hookCommand(h.name),
+      hookCommandWorkingTree(h.name),
+      hookCommandLocal(h.name),
+      hookCommandLocalLegacy(h.name),
+    ];
     const ownsHook = (x) => candidates.includes(x.command)
       || (x.command === 'node' && Array.isArray(x.args) && x.args[0] === localHookArg(h.name));
     const groups = Array.isArray(s.hooks[h.event]) ? [...s.hooks[h.event]] : [];
@@ -159,7 +183,8 @@ export function mergeSettings(existing, { vaultPath, withMcp, force, companions
       // entry's fields in place — without disturbing any sibling hooks the user grouped with it.
       const hk = owning.hooks.find(ownsHook);
       const brokenRelative = hk?.command === hookCommandLocalLegacy(h.name);
-      if (force || brokenRelative) {
+      const wrongRuntime = !h.command && hk?.command !== command;
+      if (force || brokenRelative || wrongRuntime) {
         hk.command = command;
         if (args) hk.args = args;
         else delete hk.args;
@@ -208,14 +233,19 @@ export function mergeSettings(existing, { vaultPath, withMcp, force, companions
 // it does handle is the legacy `timeout` key, which Codex silently ignores in favour of a
 // 600s default; rewriting it to `timeoutSec` invalidates the stored trusted_hash and costs
 // the user one "Hooks need review" prompt. That is the point.
-export function mergeCodexHooks(existing, { force = false } = {}) {
+export function mergeCodexHooks(existing, { force = false, projectPath = '' } = {}) {
   const file = existing && typeof existing === 'object' ? { ...existing } : {};
   file.hooks = { ...(file.hooks || {}) };
   const specs = codexHookSpecs([...SESSION_HOOKS, ...CHANGE_NUDGE_HOOKS, ...CHANGE_GATE_HOOKS])
     .sort((a, b) => (a.order ?? 0) - (b.order ?? 0));
+  const selfCheckout = isWendkeepSelfCheckout(projectPath);
   for (const h of specs) {
-    const entry = codexHookEntry(h);
-    const owns = (x) => x.command === entry.command;
+    const entry = {
+      ...codexHookEntry(h),
+      ...(selfCheckout ? { command: hookCommandWorkingTree(h.name) } : {}),
+    };
+    const candidates = new Set([hookCommand(h.name), hookCommandWorkingTree(h.name)]);
+    const owns = (x) => candidates.has(x.command);
     const groups = Array.isArray(file.hooks[h.event]) ? [...file.hooks[h.event]] : [];
     const owning = groups.find((g) => (g.hooks || []).some(owns));
     if (owning) {
@@ -224,7 +254,8 @@ export function mergeCodexHooks(existing, { force = false } = {}) {
       // `timeout` is the pre-0.46 key: Codex never read it. Migrate it even without --force,
       // otherwise the hook keeps running at the 600s default forever.
       const legacyTimeout = 'timeout' in hk;
-      if (force || legacyTimeout) {
+      const wrongRuntime = hk.command !== entry.command;
+      if (force || legacyTimeout || wrongRuntime) {
         if (legacyTimeout) {
           if (hk.timeoutSec === undefined) hk.timeoutSec = hk.timeout;
           delete hk.timeout;
@@ -233,6 +264,7 @@ export function mergeCodexHooks(existing, { force = false } = {}) {
           hk.timeoutSec = entry.timeoutSec;
           if (entry.statusMessage) hk.statusMessage = entry.statusMessage;
         }
+        if (wrongRuntime) hk.command = entry.command;
       }
       if (force && matcher) owning.matcher = matcher;
       if (force && !matcher) delete owning.matcher;
@@ -450,6 +482,10 @@ export async function runInit(argv) {
     ?? (existingBinding ? undefined : DEFAULT_OPERATING_PROFILE);
   const configPatch = profile === undefined ? {} : setOperatingProfile({}, profile);
   bindProjectVault({ projectRoot: projectPath, vaultPath, configPatch });
+  if (args.vscodeWorktreeTasks) {
+    const tasks = installVscodeWorktreeTasks({ projectRoot: projectPath });
+    log(`VS Code worktree tasks: ${tasks.state} (${tasks.path})`);
+  }
 
   // Companion plugins/MCP selection. --no-companions wins; --companions <csv> is
   // explicit; an interactive TTY gets a multi-choice prompt (context-mode pre-checked);
@@ -593,12 +629,12 @@ export async function runInit(argv) {
   const codexPath = join(projectPath, '.codex', 'hooks.json');
   const codexRead = readJsonSafe(codexPath);
   if (!codexRead.ok) {
-    writeJson(`${codexPath}.new`, mergeCodexHooks(null, { force: true }));
+    writeJson(`${codexPath}.new`, mergeCodexHooks(null, { force: true, projectPath }));
     log(M.codexBadJson(codexPath));
   } else {
     const hadFile = codexRead.data !== null;
     if (hadFile) backup(codexPath);
-    writeJson(codexPath, mergeCodexHooks(codexRead.data, { force: args.force }));
+    writeJson(codexPath, mergeCodexHooks(codexRead.data, { force: args.force, projectPath }));
     log(M.codexHooks(hadFile ? M.merged : M.created, hadFile ? M.bakSaved : ''));
   }
   log(M.codexTrust);

package/src/sync.mjs

@@ -26,7 +26,10 @@ export async function runSync(argv) {
   const profileRaw = opt(argv, '--profile');
   const profileArgs = hasProfile ? ['--profile', profileRaw] : [];
   const projectPath = resolve(projectRaw && !projectRaw.startsWith('--') ? projectRaw : process.cwd());
-  const passthrough = argv.filter((a) => a === '--yes' || a === '-y' || a === '--force');
+  const passthrough = argv.filter((a) => a === '--yes'
+    || a === '-y'
+    || a === '--force'
+    || a === '--vscode-worktree-tasks');
 
   // 1. init — idempotente: refaz a fiação sem sobrescrever o que já está configurado.
   step(1, 'init');

package/src/taxonomy.mjs

@@ -11,6 +11,7 @@ import {
   codexHookEntry,
   codexHookSpecs,
   hookCommand,
+  hookCommandWorkingTree,
   hookCommandLocal,
   hookCommandLocalLegacy,
 } from '../packages/integrations/src/host-hooks.mjs';
@@ -24,6 +25,7 @@ export {
   codexHookEntry,
   codexHookSpecs,
   hookCommand,
+  hookCommandWorkingTree,
   hookCommandLocal,
   hookCommandLocalLegacy,
   mcpServerEntry,