@agou/dsh-worktrees 0.0.0-stage → 1.0.0

package/index.js

@@ -0,0 +1,215 @@
+import path from 'node:path';
+import Schema from '@deepseek-ai/schemastery';
+import { z } from 'zod';
+import { createInitialState, validateState } from './lib/manager.js';
+import { WorktreeHost } from './host.js';
+import { registerTransport } from './transport.js';
+
+export const name = 'worktrees';
+export const inject = ['storageDomain', 'workspaceRegistry', 'sessionController', 'agents', 'workingDirectory', 'connection', 'settings', 'systemPrompt', 'tools'];
+export const Config = Schema.object({
+  directory: Schema.string().description('Absolute directory for newly created managed worktrees.').volatile(),
+  maxRetained: Schema.number().min(1).max(Number.MAX_SAFE_INTEGER).step(1).default(15).description('Eligible worktrees retained after protected checkouts are excluded.').volatile(),
+});
+
+const stateSchema = z.unknown().transform((value, context) => {
+  try { return validateState(value); }
+  catch (error) {
+    context.addIssue({ code: 'custom', message: error instanceof Error ? error.message : String(error) });
+    return z.NEVER;
+  }
+});
+const domainSpec = {
+  name: 'dsh_worktrees',
+  version: 1,
+  tables: {},
+  global: { schema: stateSchema, initial: createInitialState() },
+};
+
+// Strict tool schemas may require unused optional fields to be present.
+const optionalText = maximum => z.preprocess(value => value === '' ? undefined : value, z.string().min(1).max(maximum).optional());
+const optionalRetention = z.preprocess(value => value === 0 ? undefined : value, z.number().int().min(1).max(Number.MAX_SAFE_INTEGER).optional());
+const optionalRevision = z.preprocess(value => value === -1 ? undefined : value, z.number().int().nonnegative().optional());
+
+export function registerInfoTool(ctx, host) {
+  const input = z.object({
+    action: z.enum(['status', 'list', 'branches']),
+    workspace_id: optionalText(256),
+    offset: z.number().int().nonnegative().default(0),
+    limit: z.number().int().min(1).max(50).default(20),
+  }).strict();
+  ctx.tools.register({
+    name: 'worktree_info',
+    description: 'Inspect the current session worktree, list managed worktrees, or list a workspace’s existing Git branches. Reads only; does not create, checkout, restore, delete, or change settings. Lists are paginated with offset and limit.',
+    parameters: {
+      type: 'object',
+      properties: {
+        action: { type: 'string', enum: ['status', 'list', 'branches'] },
+        workspace_id: { type: 'string', description: 'Registered workspace id. Omit or use an empty string for the current session workspace.' },
+        offset: { type: 'integer', minimum: 0, default: 0 },
+        limit: { type: 'integer', minimum: 1, maximum: 50, default: 20 },
+      },
+      required: ['action'],
+      additionalProperties: false,
+    },
+    output: {
+      schema: { type: 'object', properties: { text: { type: 'string' } }, required: ['text'], additionalProperties: false },
+      render: (_args, value) => [{ type: 'text', text: value.text }],
+    },
+    async execute(args, exec) {
+      const request = input.parse(args);
+      if (!exec.agent) throw new Error('A session is required to inspect its worktree.');
+      const workspace = request.workspace_id ? host.workspace(request.workspace_id) : host.workspaceFor(exec.agent.session);
+      if (request.action === 'branches') {
+        if (!workspace) return { text: 'This session has no registered workspace or managed worktree.' };
+        const info = await host.manager.inspectWorkspace(workspace, exec.signal);
+        return { text: JSON.stringify({ workspaceId: workspace.workspaceId, currentBranch: info.currentBranch, head: info.head, defaultBase: info.defaultBase, branches: info.branches.slice(request.offset, request.offset + request.limit), total: info.branches.length }) };
+      }
+      const state = host.manager.list();
+      const binding = state.bindings[exec.agent.id];
+      const rows = request.action === 'status'
+        ? (binding?.worktreeId ? [state.worktrees[binding.worktreeId]] : [])
+        : Object.values(state.worktrees).filter(record => record.workspaceId === workspace?.workspaceId);
+      return { text: JSON.stringify({ workspaceId: workspace?.workspaceId ?? null, binding: binding ?? null, records: rows.slice(request.offset, request.offset + request.limit).map(({ token: _token, ...record }) => record), total: rows.length, config: host.configuration(), revision: host.descriptor().revision }) };
+    },
+  });
+}
+
+export function registerManagementTool(ctx, host) {
+  const input = z.object({
+    action: z.enum(['prepare', 'checkout', 'restore', 'remove', 'configure']),
+    session_id: optionalText(256),
+    workspace_id: optionalText(256),
+    worktree_id: optionalText(256),
+    mode: z.enum(['local', 'new']).optional(),
+    branch: optionalText(4096),
+    directory: optionalText(32767),
+    max_retained: optionalRetention,
+    expected_revision: optionalRevision,
+  }).strict();
+  ctx.tools.register({
+    name: 'worktree_manage',
+    description: 'Request a managed worktree operation. prepare selects Local or a detached worktree for a blank session before its first message; it does not send a message. checkout immediately changes the source workspace branch. restore recovers a saved snapshot; remove snapshots first and archives linked chats. configure changes the new-worktree directory or soft retention count. Each mutation uses the Host’s normal approval flow; this tool cannot approve its own request.',
+    parameters: {
+      type: 'object',
+      properties: {
+        action: { type: 'string', enum: ['prepare', 'checkout', 'restore', 'remove', 'configure'] },
+        session_id: { type: 'string', description: 'Session for prepare. Omit or use an empty string for the calling session; new selection requires a blank session.' },
+        workspace_id: { type: 'string', description: 'Registered source workspace for checkout. Omit or use an empty string for the calling session workspace.' },
+        worktree_id: { type: 'string', description: 'Managed id from worktree_info, required for restore/remove. Use an empty string for other actions.' },
+        mode: { type: 'string', enum: ['local', 'new'], description: 'Required for prepare; ignored for other actions.' },
+        branch: { type: 'string', description: 'Existing local branch for checkout, or base ref for prepare(new). Omit or use an empty string when unused.' },
+        directory: { type: 'string', description: 'Absolute Host path for future worktrees, for configure. Omit or use an empty string to keep the current directory.' },
+        max_retained: { type: 'integer', minimum: 0, description: 'Soft eligible-worktree retention target, for configure. Omit or use 0 to keep the current target.' },
+        expected_revision: { type: 'integer', minimum: -1, description: 'Settings revision from worktree_info. Omit or use -1 for the current revision; 0 is a valid explicit revision.' },
+      },
+      required: ['action'],
+      additionalProperties: false,
+    },
+    output: {
+      schema: { type: 'object', properties: { text: { type: 'string' } }, required: ['text'], additionalProperties: false },
+      render: (_args, value) => [{ type: 'text', text: value.text }],
+    },
+    async execute(args, exec) {
+      const request = input.parse(args);
+      if (!exec.agent) throw new Error('A calling session is required for a worktree operation.');
+      let result;
+      switch (request.action) {
+        case 'prepare': {
+          if (!request.mode) throw new Error('prepare requires mode.');
+          const caller = { id: `tool:${exec.callId}`, signal: exec.signal };
+          const operation = { sessionId: request.session_id ?? exec.agent.id, operationId: exec.callId, choice: { mode: request.mode, ...(request.branch ? { baseRef: request.branch } : {}) } };
+          try { result = await host.prepare(operation, caller, exec.signal); }
+          finally { await host.settle(operation, caller); }
+          break;
+        }
+        case 'checkout': {
+          if (!request.branch) throw new Error('checkout requires branch.');
+          const workspace = request.workspace_id ? host.workspace(request.workspace_id) : host.workspaceFor(exec.agent.session);
+          if (!workspace) throw new Error('This session has no registered workspace.');
+          const value = await host.manager.checkout(workspace, request.branch, exec.signal);
+          result = { workspaceId: value.workspaceId, currentBranch: value.currentBranch, head: value.head };
+          break;
+        }
+        case 'restore':
+        case 'remove':
+          if (!request.worktree_id) throw new Error(`${request.action} requires worktree_id.`);
+          result = await host[request.action](request.worktree_id, exec.signal);
+          break;
+        case 'configure':
+          result = await host.configure({
+            ...(request.directory ? { directory: request.directory } : {}),
+            ...(request.max_retained !== undefined ? { maxRetained: request.max_retained } : {}),
+            expectedRevision: request.expected_revision ?? host.descriptor().revision,
+          });
+          break;
+        default: throw new Error('Unknown worktree action.');
+      }
+      return { text: JSON.stringify(result) };
+    },
+  });
+  ctx.on('tools/pre-execute', async (exec, next) => {
+    const decision = await next();
+    if (exec.name !== 'worktree_manage' || decision.kind !== 'allow') return decision;
+    const action = input.parse(exec.arguments).action;
+    return {
+      kind: 'ask',
+      reason: `Allow managed worktree operation: ${action}`,
+      displayReason: { en: `Allow managed worktree operation: ${action}`, zh: `允许执行工作树操作：${action}` },
+    };
+  });
+}
+
+export function registerHostEvents(ctx, host) {
+  ctx.on('session/event', (session, event) => {
+    host.observe(session, event);
+    if (event.type === 'turn/end') host.requestCleanup();
+    if (event.type === 'working-directory/change') host.requestDiscovery(true);
+  });
+  ctx.on('domain/changed', change => {
+    if (change.domain !== 'workspace') return;
+    host.requestCleanup();
+    host.requestDiscovery(true);
+  });
+  ctx.on('agent/created', async ({ agent, signal }) => {
+    host.reconciled.delete(agent.id);
+    await host.inherit(agent, signal);
+    await host.reconcile(agent.session);
+  });
+  ctx.on('session/disposed', session => {
+    host.reconciled.delete(session.id);
+    host.accepting.delete(session.id);
+  });
+  // This guard runs before native ensure() can recover a missing cwd to its original workspace.
+  ctx.on('system-prompt/assemble', async (_assembly, context, next) => {
+    if (context.agent) await host.assertAvailable(context.agent, context.signal);
+    return next();
+  }, { prepend: true });
+  ctx.on('agent/pre-step', async ({ agent, signal }, next) => {
+    await host.assertAvailable(agent, signal);
+    return next();
+  });
+}
+
+export async function apply(ctx, config) {
+  if (!path.isAbsolute(config.directory.get())) throw new Error('dsh-worktrees: directory must be an absolute path.');
+  const domain = await ctx.storageDomain.open(domainSpec);
+  const host = new WorktreeHost(ctx, config, { get: () => domain.global.get(), set: value => domain.global.set(value) });
+  ctx.effect(() => async () => {
+    await host.dispose();
+    await domain.close();
+  });
+  ctx.effect(() => ctx.settings.configure({ auto: false }, ctx.fiber));
+  registerTransport(ctx, host);
+  registerHostEvents(ctx, host);
+  ctx.systemPrompt.context({
+    name: 'worktrees:current',
+    order: ctx.systemPrompt.getContextOrder('WORKING_DIRECTORY') + 1,
+    interpolate: false,
+    required: true,
+    text: context => host.context(context.agent),
+  });
+  registerInfoTool(ctx, host);
+  registerManagementTool(ctx, host);
+  await host.start();
+}

package/lib/git.js

@@ -0,0 +1,186 @@
+import { spawn } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import * as fs from 'node:fs/promises';
+import path from 'node:path';
+
+const MAX_OUTPUT = 64 * 1024 * 1024;
+const TIMEOUT = 60_000;
+
+export class WorktreeError extends Error {
+  constructor(code, message, cause) {
+    super(message, cause === undefined ? undefined : { cause });
+    this.name = 'WorktreeError';
+    this.code = code;
+  }
+}
+
+export function fail(code, message) {
+  throw new WorktreeError(code, message);
+}
+
+export function samePath(left, right) {
+  const normalize = value => process.platform === 'win32' ? path.resolve(value).toLowerCase() : path.resolve(value);
+  return normalize(left) === normalize(right);
+}
+
+export function inside(parent, child) {
+  const relative = path.relative(parent, child);
+  return relative === '' || (!path.isAbsolute(relative) && relative !== '..' && !relative.startsWith(`..${path.sep}`));
+}
+
+export async function exists(target) {
+  try {
+    return await fs.lstat(target);
+  } catch (error) {
+    if (error.code === 'ENOENT') return undefined;
+    throw error;
+  }
+}
+
+export async function canonical(target) {
+  if (typeof target !== 'string' || !path.isAbsolute(target) || target.includes('\0')) {
+    fail('INVALID_PATH', 'The directory must be an absolute filesystem path.');
+  }
+  return fs.realpath(target);
+}
+
+export function gitEnvironment(overrides = {}) {
+  const environment = Object.fromEntries(Object.entries(process.env).filter(([key]) => !/^GIT_/i.test(key)));
+  return {
+    ...environment,
+    GIT_TERMINAL_PROMPT: '0',
+    GIT_NO_LAZY_FETCH: '1',
+    GIT_NO_REPLACE_OBJECTS: '1',
+    GIT_LFS_SKIP_SMUDGE: '1',
+    ...overrides,
+  };
+}
+
+/** Every Git argument is literal. Repository selectors and injected Git configuration are discarded. */
+export async function git(cwd, args, options = {}) {
+  const { signal, allowed = [0], input, env, maxOutput = MAX_OUTPUT, timeout = TIMEOUT } = options;
+  signal?.throwIfAborted();
+  return new Promise((resolve, reject) => {
+    let failure;
+    let stdoutSize = 0;
+    let stderrSize = 0;
+    const stdout = [];
+    const stderr = [];
+    const child = spawn('git', [
+      '-c', 'core.hooksPath=/dev/null',
+      '-c', 'core.fsmonitor=false',
+      '-c', 'core.untrackedCache=false',
+      '-c', 'submodule.recurse=false',
+      '-c', 'gc.auto=0',
+      '-c', 'maintenance.auto=false',
+      ...args,
+    ], {
+      cwd,
+      env: gitEnvironment(env),
+      shell: false,
+      windowsHide: true,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    const stop = error => {
+      failure ??= error;
+      child.kill();
+    };
+    const abort = () => stop(signal.reason ?? new WorktreeError('ABORTED', 'The Git operation was cancelled.'));
+    const timer = setTimeout(() => stop(new WorktreeError('GIT_TIMEOUT', `Git ${args[0]} exceeded ${timeout} ms.`)), timeout);
+    timer.unref();
+    signal?.addEventListener('abort', abort, { once: true });
+    if (signal?.aborted) abort();
+    child.on('error', error => { failure ??= error; });
+    child.stdout.on('data', data => {
+      stdoutSize += data.length;
+      if (stdoutSize > maxOutput) stop(new WorktreeError('OUTPUT_LIMIT', 'Git output exceeded the safe capture limit.'));
+      else stdout.push(data);
+    });
+    child.stderr.on('data', data => {
+      stderrSize += data.length;
+      if (stderrSize > maxOutput) stop(new WorktreeError('OUTPUT_LIMIT', 'Git error output exceeded the safe capture limit.'));
+      else stderr.push(data);
+    });
+    child.stdin.on('error', error => {
+      if (error.code !== 'EPIPE' && error.code !== 'ERR_STREAM_DESTROYED') stop(error);
+    });
+    child.on('close', code => {
+      clearTimeout(timer);
+      signal?.removeEventListener('abort', abort);
+      const output = Buffer.concat(stdout);
+      if (failure) return reject(failure);
+      if (!allowed.includes(code)) {
+        return reject(new WorktreeError('GIT_FAILED', `Git ${args[0]} failed (${code}): ${Buffer.concat(stderr).toString('utf8').trim().slice(0, 4096)}`));
+      }
+      resolve({ stdout: output.toString('utf8'), bytes: output, code });
+    });
+    child.stdin.end(input);
+  });
+}
+
+export async function filterOverrides(cwd, signal) {
+  const configured = await git(cwd, ['config', '--null', '--name-only', '--get-regexp', '^filter\\.'], { signal, allowed: [0, 1] });
+  const drivers = new Set();
+  for (const key of configured.stdout.split('\0')) {
+    const separator = key.lastIndexOf('.');
+    if (separator > 7 && ['clean', 'smudge', 'process', 'required'].includes(key.slice(separator + 1))) drivers.add(key.slice(7, separator));
+  }
+  return [...drivers].flatMap(driver => ['clean', 'smudge', 'process', 'required'].flatMap(attribute => [
+    '-c', `filter.${driver}.${attribute}=${attribute === 'required' ? 'false' : ''}`,
+  ]));
+}
+
+export async function repository(directory, signal) {
+  const real = await canonical(directory);
+  const root = (await git(real, ['rev-parse', '--show-toplevel'], { signal })).stdout.replace(/\r?\n$/, '');
+  const common = (await git(real, ['rev-parse', '--path-format=absolute', '--git-common-dir'], { signal })).stdout.replace(/\r?\n$/, '');
+  return { root: await canonical(root), commonDir: await canonical(common) };
+}
+
+export async function commitAt(cwd, ref, signal, optional = false) {
+  const result = await git(cwd, ['rev-parse', '--verify', '--end-of-options', `${ref}^{commit}`], { signal, allowed: optional ? [0, 128] : [0] });
+  if (result.code !== 0) return null;
+  const value = result.stdout.trim();
+  if (!/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(value)) fail('INVALID_OBJECT', 'Git returned an invalid commit identity.');
+  return value;
+}
+
+/** Parse Git's NUL-delimited protocol, rejecting filenames that cannot round-trip safely. */
+export function nulRecords(buffer) {
+  const decoder = new TextDecoder('utf-8', { fatal: true });
+  return decoder.decode(buffer).split('\0').filter(Boolean);
+}
+
+export function treeEntries(buffer) {
+  return nulRecords(buffer).map(line => {
+    const match = /^(\d{6}) (blob|tree|commit) ([a-f0-9]{40}|[a-f0-9]{64})\t([\s\S]+)$/.exec(line);
+    if (!match) fail('INVALID_TREE', 'Git returned an invalid tree entry.');
+    return { mode: match[1], type: match[2], oid: match[3], name: match[4] };
+  });
+}
+
+export function safeChild(root, name) {
+  const parts = typeof name === 'string' ? name.split('/') : [];
+  const unsafeWindows = process.platform === 'win32' && parts.some(part => /[:<>"|?*\u0000-\u001f]/.test(part) || /[. ]$/.test(part) || /^(?:con(?:in\$|out\$)?|prn|aux|nul|com[1-9\u00b9\u00b2\u00b3]|lpt[1-9\u00b9\u00b2\u00b3])(?:\.|$)/i.test(part));
+  if (!name || name.includes('\\') || unsafeWindows || parts.some(part => !part || part === '.' || part === '..' || part.toLowerCase() === '.git')) {
+    fail('UNSAFE_TREE', `The Git tree contains an unsafe path: ${JSON.stringify(name)}.`);
+  }
+  const target = path.resolve(root, ...name.split('/'));
+  if (!inside(root, target) || samePath(root, target)) fail('UNSAFE_TREE', 'The Git tree escapes the checkout directory.');
+  return target;
+}
+
+export function digest(bytes) {
+  return createHash('sha256').update(bytes).digest('hex');
+}
+
+export async function bounded(promise, signal) {
+  signal?.throwIfAborted();
+  if (!signal) return promise;
+  return new Promise((resolve, reject) => {
+    const abort = () => reject(signal.reason ?? new WorktreeError('ABORTED', 'The operation was cancelled.'));
+    signal.addEventListener('abort', abort, { once: true });
+    Promise.resolve(promise).then(resolve, reject).finally(() => signal.removeEventListener('abort', abort));
+    if (signal.aborted) abort();
+  });
+}