@feng0531/dsh-vcs 0.5.1 → 0.7.0

package/README.md

@@ -1,8 +1,8 @@
 # DSH VCS
 
-在 DeepSeek Harness（DSH）Web 中查看 Git / SVN 文件变更和提交历史的**只读插件**。
+在 DeepSeek Harness（DSH）Web 中查看 Git / SVN 文件变更和提交历史，**默认只读预览**。
 
-你可以查看差异、浏览历史、追溯文件，但不能通过本插件修改文件、暂存、提交、拉取或推送。
+你可以查看差异、浏览历史、追溯文件。0.6.0 起新增一个明确的写操作例外：预览并确认后切换已有本地 Git 分支，会改变 HEAD、暂存区和工作文件；不提供正文编辑、暂存、提交、拉取或推送。源码能力说明不代表目标版本已通过正式发布门禁，请核对对应发布渠道。
 
 - npm 包：`@feng0531/dsh-vcs`
 - [下载正式版本](https://github.com/f-e-n-g-0531/dsh-vcs/releases/latest) · [查看更新](https://github.com/f-e-n-g-0531/dsh-vcs/blob/main/CHANGELOG.md)
@@ -17,9 +17,10 @@
 | 浏览 Git 历史 | 搜索提交说明、作者、路径与提交时间范围（since/until，含边界，按 committer date）；查看本地分支、提交图、提交详情与目录 |
 | 比较历史版本 | 比较提交与选定父提交，或选择两个本地提交进行 A/B 比较 |
 | 追溯代码来源 | 文件历史、唯一来源重命名追踪（含改名同时修改）、Blame（逐行查看最后修改者和提交） |
-| 搜索与定位 | 搜索固定提交中的内容，点击结果定位命中行，返回保留结果 |
+| 搜索与定位 | 在固定提交中分页搜索内容，点击结果定位命中行；高级、基础与分段阅读支持目标行，返回保留结果与阅读设置 |
 | 查看其他内容 | 支持部分静态图片比较；较大历史 UTF-8 文件可分段阅读 |
 | 浏览 SVN 历史 | 明确同意连接后，查看 HTTPS 仓库日志、修订差异和文件历史 |
+| 切换本地 Git 分支（0.6.0 起） | 独立入口预览当前／目标分支与提交，明确确认后执行；不是历史引用导航 |
 
 提供中英文界面。编辑器加载失败时会显示基础文本比较；它不是完整的 Monaco 替代品。
 
@@ -74,6 +75,14 @@ VCS 顶部“更新插件”提供更新检查、宿主插件管理器与最新
 
 新增文件可能使用空白左侧。冲突文件只供查看，不提供三方合并或冲突解决。
 
+### 确认式本地 Git 分支切换（0.6.0 候选）
+
+历史页的分支下拉只改变阅读起点，**不会切换工作区**。实际切换使用独立的“切换本地分支”入口：先读取已有本地分支，选择目标并预览当前／目标完整引用及提交，再明确确认。预览约 60 秒失效，确认仅能使用一次；取消预览不执行切换，切换过程中不能重复提交。
+
+仅支持已有的本地 `refs/heads` 分支和干净、普通的 Git 工作副本。已暂存、未暂存、未跟踪以及**被忽略的文件**都会阻止操作；不会自动保存、stash、强制覆盖、创建分支或连接远端。配置了过滤器或命令 hooks、存在 Git attributes、稀疏／部分克隆、assume-unchanged／skip-worktree、符号链接／子模块、未完成的合并／变基等操作或锁时也会保守拒绝。Git 元数据或工作路径硬链接（含本地克隆共享的对象文件）、元数据符号链接／alternates、linked worktree、分离／符号链接的 Git 元数据目录、`core.worktree`、detached／未创建首个提交的 HEAD，以及与目标分支同名的 tag 均不支持；目标被其他 worktree 占用时不绕过 Git 的拒绝。
+
+确认前重新检查仓库和分支状态，但不保证与其他 Git 工具之间的原子隔离。写入已开始后取消、超时或失败可能表示**结果未知**，不能当作已回滚；先手动刷新并核对当前分支、暂存区和工作文件，不要盲目重试。成功后界面重新发现并刷新仓库。
+
 ### SVN 历史需要单独同意
 
 本地 SVN 变更比较不连接服务器。打开远程历史前，需要审阅服务器与路径范围并勾选同意；授权约 5 分钟后过期，须重新手动同意。
@@ -82,9 +91,10 @@ VCS 顶部“更新插件”提供更新检查、宿主插件管理器与最新
 
 ## 目前的限制
 
-- **不是完整的 Fork 客户端**：没有仓库写操作，历史图和列表都有容量限制；分支导航使用本地分支、标签及本地缓存的远程跟踪引用，不连接远端、不 fetch。
+- **不是完整的 Fork 客户端**：除上述确认式已有本地 Git 分支切换外，仓库浏览保持只读；不提供 stage、commit、stash、force、fetch 或 push。历史图和列表都有容量限制；历史分支导航可使用本地分支、标签及本地缓存的远程跟踪引用，不连接远端。
 - 普通文本比较每侧最多 **2MiB**。Git提交／A-B／工作区三个模式比较超限时可手动加载完整文本（UTF-8／GBK／带BOM的UTF-16），每侧最多 **8MiB、10万行**，单行最多65536字符；计算超时会明确提示结果不完整。工作区读取期间发生变化会拒绝结果，但不是系统级原子快照；SVN大文件仍不支持。
-- 历史 UTF-8 正文分段最多 **16MiB**；分段阅读不是完整 Diff。正文按固定对象缓存，最多 32MiB／8 项／60 秒，缓存命中仍重新验证请求授权。历史目录按需分页，每页最多 100 项，单目录仍有 10 万项和 16MiB 命令输出上限。
+- 内容搜索每页最多100条匹配，扫描最多64个文件／16MiB正文，匹配列表最多1MiB；固定提交树上限10万项／16MiB。超过16MiB的文件跳过并提示结果不完整，二进制排除；无匹配的扫描页仍可能有下一页。长命中行仅显示开头片段，打开文件可继续阅读。
+- 历史 UTF-8 正文分段最多 **16MiB**，每片64KiB；按全局行号定位，行片段有明确提示；基础单版本阅读每窗口最多500行。分段阅读不是完整 Diff。正文按固定对象缓存，最多 32MiB／8 项／60 秒，缓存命中仍重新验证请求授权。历史目录按需分页，每页最多 100 项，单目录仍有 10 万项和 16MiB 命令输出上限。
 - 重命名追溯仅沿第一父链，至少50%相似且确认唯一删除源／新增目标；合并、复制、歧义或累计32次确认后停止。
 - 子模块变更只显示 Index 记录的提交指针与本地检出状态（已检出／未初始化／目录缺失／不可读）；不进入子模块、不读取其 HEAD，也不更新或同步。
 - 树浏览和来源行预览可手动查看该历史路径的文件历史，并可选跟随重命名；路径必须存在于所选提交，跟随规则与路径历史一致（第一父链、≥50%相似、唯一确认、32次上限）。

package/branch-switch-host.mjs

@@ -0,0 +1,35 @@
+// Server-owned, single-use confirmation and cooperative repository exclusion.
+import {randomBytes} from 'node:crypto';
+import path from 'node:path';
+const access=new Map();
+const error=(code,message)=>Object.assign(new Error(message),{code});
+const keyOf=root=>{const key=path.resolve(root);return process.platform==='win32'?key.toLowerCase():key;};
+export function acquireRepositoryAccess(root,write=false){
+ const key=keyOf(root),state=access.get(key)||{readers:0,writer:false};
+ if(state.writer||(write&&state.readers))throw error('vcs/busy','This repository has an active operation. Wait for it to finish and prepare again.');
+ if(write)state.writer=true;else state.readers++;access.set(key,state);let released=false;
+ return()=>{if(released)return;released=true;if(write)state.writer=false;else state.readers--;if(!state.writer&&!state.readers)access.delete(key);};
+}
+export function createBranchSwitchCoordinator({api,now=Date.now,ttlMs=60000,maxTokens=32}){
+ const tokens=new Map();
+ const purge=()=>{for(const [token,row]of tokens)if(row.expiresAt<=now())tokens.delete(token);};
+ return {
+  invalidate(entry){for(const [token,row]of tokens)if(row.entry===entry)tokens.delete(token);},
+  clear(){tokens.clear();},
+  async prepare(address,{entry,repository,cwd,signal,assertAuthorized}){
+   const snapshot=await api.prepareLocalBranchSwitch({...repository},{branch:address.branch,signal});await assertAuthorized();signal?.throwIfAborted();purge();
+   while(tokens.size>=maxTokens)tokens.delete(tokens.keys().next().value);
+   const token=randomBytes(32).toString('hex'),expiresAt=now()+ttlMs;
+   tokens.set(token,{snapshot,expiresAt,entry,repository,cwd,sessionId:address.sessionId,repositoryId:address.repositoryId});
+   return {token,expiresAt,current:snapshot.current,target:snapshot.target};
+  },
+  async confirm(address,{entry,repository,cwd,signal,assertAuthorized}){
+   purge();const row=tokens.get(address.token);tokens.delete(address.token);
+   if(!row||row.entry!==entry||row.repository!==repository||row.cwd!==cwd||row.sessionId!==address.sessionId||row.repositoryId!==address.repositoryId)throw error('vcs/branch-confirmation-invalid','Confirmation is expired, used, or belongs to a different Session/repository. Prepare again.');
+   const release=acquireRepositoryAccess(repository.root,true);let started=false;
+   try{await assertAuthorized();signal?.throwIfAborted();const result=await api.switchLocalBranch({...repository},{snapshot:row.snapshot,signal,assertAuthorized,onStart(){started=true;}});await assertAuthorized();signal?.throwIfAborted();return result;}
+   catch(failure){if(started)throw error('vcs/branch-outcome-unknown','Branch switching started but its final result could not be confirmed. Refresh the repository and inspect the current branch before preparing another switch.');throw failure;}
+   finally{release();}
+  },
+ };
+}

package/branch-switch.mjs

@@ -0,0 +1,193 @@
+import * as fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import {createHash} from 'node:crypto';
+import {git} from './local-command.mjs';
+import {currentOperationBudget} from './src/operation-budget.mjs';
+import {isObjectId} from './git-history.mjs';
+
+const MAX_BYTES = 2 * 1024 * 1024;
+const MAX_BRANCHES = 1000;
+const LF = String.fromCharCode(10), NUL = String.fromCharCode(0);
+const fail = (kind,message) => Object.assign(new Error(message),{code:'vcs/branch-'+kind});
+const check = signal => {signal?.throwIfAborted();currentOperationBudget()?.throwIfExpired();};
+const digest = value => createHash('sha256').update(value).digest('hex');
+const branchName = value => {
+  if (typeof value !== 'string' || !value || value.length > 1024 || value.startsWith('-') || value.startsWith('refs/') || [...value].some(char => char.charCodeAt(0) <= 32 || char.charCodeAt(0) === 127)) throw fail('unsupported','Select an existing local branch name.');
+  return value;
+};
+
+// Private, empty hooks/attributes locations are command-scoped, never repository config writes.
+async function safeContext(repo,signal,work) {
+  check(signal);
+  if (!repo || repo.type !== 'git' || typeof repo.root !== 'string') throw fail('unsupported','Branch switching supports local Git working copies only.');
+  const root = await fs.realpath(repo.root);
+  if (root !== path.resolve(repo.root)) throw fail('changed','Repository canonical root changed; rediscover repositories.');
+  const metadata = path.join(root,'.git');
+  const metadataStat = await fs.lstat(metadata);
+  if (!metadataStat.isDirectory() || metadataStat.isSymbolicLink() || await fs.realpath(metadata) !== metadata) throw fail('unsupported','Linked, separate or symlinked Git directories are not supported.');
+  const metadataIdentity = await checkedMetadata(metadata,signal);
+  const temporary = await fs.mkdtemp(path.join(os.tmpdir(),'dsh-vcs-switch-'));
+  try {
+    const hooks = path.join(temporary,'hooks'),attributes = path.join(temporary,'attributes');
+    await fs.mkdir(hooks);await fs.writeFile(attributes,'');
+    const run = (args,max = MAX_BYTES) => {check(signal);return git(root,['-c','core.hooksPath='+hooks,'-c','core.attributesFile='+attributes,'-c','submodule.recurse=false','-c','core.ignoreStat=false','-c','core.untrackedCache=false','-c','core.protectNTFS=true','-c','core.protectHFS=true','-c','hook.post-checkout.enabled=false','-c','hook.reference-transaction.enabled=false',...args],max,{signal});};
+    const top = (await run(['rev-parse','--show-toplevel'])).toString('utf8').trim();
+    if (await fs.realpath(top) !== root || (await run(['rev-parse','--is-bare-repository'])).toString('utf8').trim() !== 'false') throw fail('unsupported','A canonical non-bare working copy is required.');
+    return await work({root,run,metadataIdentity});
+  } finally {await fs.rm(temporary,{recursive:true,force:true,maxRetries:5});}
+}
+
+// Metadata may redirect Git writes even when the .git root itself is canonical.
+async function checkedMetadata(directory,signal) {
+  const rows = [];let count = 0;
+  const visit = async (target,recursive) => {
+    check(signal);if (++count > 20000) throw fail('unsupported','Git metadata exceeds the safe inspection limit.');
+    let stat;try {stat = await fs.lstat(target,{bigint:true});} catch (error) {if (error.code === 'ENOENT') return;throw error;}
+    if (stat.isSymbolicLink() || (stat.isFile() && stat.nlink > 1n) || await fs.realpath(target) !== target || (!stat.isDirectory() && !stat.isFile())) throw fail('unsupported','Redirected Git metadata is not supported.');
+    rows.push([path.relative(directory,target),String(stat.dev),String(stat.ino)]);
+    if (recursive && stat.isDirectory()) {for (const entry of (await fs.readdir(target)).sort()) await visit(path.join(target,entry),true);}
+  };
+  await visit(directory,false);
+  for (const file of ['HEAD','index','config','config.worktree','packed-refs','shallow']) await visit(path.join(directory,file),false);
+  for (const name of ['objects','refs','logs','info']) await visit(path.join(directory,name),true);
+  for (const file of ['objects/info/alternates','objects/info/http-alternates']) {
+    try {await fs.lstat(path.join(directory,file));} catch (error) {if (error.code === 'ENOENT') continue;throw error;}
+    throw fail('unsupported','Alternate object databases are not supported.');
+  }
+  return digest(JSON.stringify(rows));
+}
+
+function decode(buffer) {
+  try {return new TextDecoder('utf-8',{fatal:true}).decode(buffer);}
+  catch {throw fail('unsupported','Branch metadata must be valid UTF-8.');}
+}
+async function currentBranch(run) {
+  let ref;
+  try {ref = decode(await run(['symbolic-ref','--quiet','HEAD'])).trim();}
+  catch (error) {if (error.code !== 'VCS_COMMAND') throw error;throw fail('unsupported','Detached or unborn HEAD cannot switch branches here.');}
+  if (!ref.startsWith('refs/heads/')) throw fail('unsupported','HEAD must identify an existing local branch.');
+  let commit;
+  try {commit = decode(await run(['rev-parse','--verify',ref+'^{commit}'])).trim();}
+  catch (error) {if (error.code !== 'VCS_COMMAND') throw error;throw fail('unsupported','Unborn HEAD cannot switch branches here.');}
+  if (!isObjectId(commit)) throw fail('unsupported','Invalid current branch commit.');
+  return {ref,name:ref.slice(11),commit};
+}
+async function branches(run) {
+  const output = decode(await run(['for-each-ref','--sort=refname','--count='+String(MAX_BRANCHES+1),'--format=%(refname)%00%(objectname)%00%(objecttype)','refs/heads/']));
+  const lines = output ? output.trimEnd().split(LF) : [];
+  if (lines.length > MAX_BRANCHES) throw fail('unsupported','Local branch count exceeds 1000.');
+  return lines.map(line => {
+    const [ref,commit,type,...extra] = line.split(NUL);
+    if (extra.length || !ref?.startsWith('refs/heads/') || !isObjectId(commit) || type !== 'commit') throw fail('unsupported','Invalid local branch metadata.');
+    return {ref,name:ref.slice(11),commit};
+  });
+}
+async function configSnapshot(run) {
+  const raw = decode(await run(['config','--null','--list']));
+  const config = [];
+  for (const record of raw.split(NUL).filter(Boolean)) {
+    const cut = record.indexOf(LF),key = (cut < 0 ? record : record.slice(0,cut)).toLowerCase(),value = cut < 0 ? '' : record.slice(cut+1);
+    if (['hook.post-checkout.enabled','hook.reference-transaction.enabled'].includes(key) && value === 'false') continue;
+    if (key === 'core.worktree') throw fail('unsupported','Separate Git working directories are not supported.');
+    if (key.startsWith('filter.') || key.startsWith('hook.')) throw fail('unsupported','Configured Git filters or command hooks are not supported for safe switching.');
+    if ((['core.sparsecheckout','core.sparsecheckoutcone','index.sparse'].includes(key) && !['false','no','0'].includes(value.toLowerCase())) || key === 'extensions.partialclone' || /^remote[.].*[.]promisor$/.test(key)) throw fail('unsupported','Sparse or partial working copies are not supported for safe switching.');
+    if (!['core.hookspath','core.attributesfile','core.fsmonitor','submodule.recurse'].includes(key)) config.push(record);
+  }
+  return digest(config.join(NUL));
+}
+async function absentGitState(root,run) {
+  const locations = decode(await run(['rev-parse','--git-dir','--git-common-dir'])).trim().split(LF);
+  if (locations.length !== 2) throw fail('unsupported','Invalid Git metadata directory.');
+  const directories = [...new Set(await Promise.all(locations.map(value => fs.realpath(path.resolve(root,value)))))];
+  if (directories.some(directory => directory !== path.join(root,'.git'))) throw fail('unsupported','External Git metadata is not supported.');
+  for (const directory of directories) for (const name of ['MERGE_HEAD','CHERRY_PICK_HEAD','REVERT_HEAD','REBASE_HEAD','BISECT_LOG','rebase-merge','rebase-apply','sequencer','index.lock','HEAD.lock','info/sparse-checkout','info/attributes']) {
+    try {await fs.lstat(path.join(directory,name));}
+    catch (error) {if (error.code === 'ENOENT') continue;throw error;}
+    throw fail('unsupported','Repository operation, sparse state, attributes or lock is present: '+name);
+  }
+}
+async function safeTree(run,commit) {
+  const raw = decode(await run(['ls-tree','-r','-z','--full-tree',commit]));
+  if (raw && !raw.endsWith(NUL)) throw fail('unsupported','Truncated tree metadata.');
+  const paths = [];
+  for (const row of raw.split(NUL).filter(Boolean)) {
+    const tab = row.indexOf(String.fromCharCode(9)),header = row.slice(0,tab),file = row.slice(tab+1);
+    if (tab < 0 || !file || !/^(100644|100755) blob [a-f0-9]{40,64}$/.test(header)) throw fail('unsupported','Symlinks, submodules or unsupported tree entries prevent safe switching.');
+    paths.push(file);
+    if (file.split('/').some(part => part.toLowerCase() === '.gitattributes')) throw fail('unsupported','Git attributes are not supported for safe switching.');
+  }
+  return {hash:digest(raw),paths};
+}
+async function checkWorkingPaths(root,paths) {
+  const checked = new Set();
+  for (const file of paths) {
+    if (!file || path.isAbsolute(file) || (process.platform === 'win32' && (file.includes(':') || file.includes(String.fromCharCode(92)))) || file.split('/').some(part => !part || part === '.' || part === '..' || part.toLowerCase() === '.git')) throw fail('unsupported','Invalid tracked path.');
+    let component = root;
+    for (const part of file.split('/')) {
+      component = path.join(component,part);
+      if (checked.has(component)) continue;
+      checked.add(component);
+      try {const stat=await fs.lstat(component,{bigint:true});if (stat.isSymbolicLink() || (stat.isFile() && stat.nlink > 1n)) throw fail('unsupported','Working tree symlinks or hardlinks prevent safe switching.');}
+      catch (error) {if (error.code !== 'ENOENT') throw error;}
+    }
+  }
+}
+async function snapshotFor({root,run,metadataIdentity},name,signal) {
+  branchName(name);
+  try {await run(['check-ref-format','--branch',name]);}
+  catch (error) {if (error.code !== 'VCS_COMMAND') throw error;throw fail('unsupported','Invalid local branch name.');}
+  const config = await configSnapshot(run);
+  await absentGitState(root,run);
+  const current = await currentBranch(run);
+  const target = (await branches(run)).find(item => item.name === name);
+  if (!target) throw fail('changed','The selected local branch no longer exists.');
+  try {await run(['show-ref','--verify','--quiet','refs/tags/'+name]);throw fail('unsupported','A tag shares the selected branch name; ambiguous selections are not supported.');}
+  catch (error) {if (!(error.code === 'VCS_COMMAND' && error.exitCode === 1)) throw error;}
+  if (target.ref === current.ref) throw fail('unsupported','The selected branch is already checked out.');
+  const trees = [await safeTree(run,current.commit),await safeTree(run,target.commit)];
+  const staged = decode(await run(['ls-files','--stage','-z']));
+  for (const row of staged.split(NUL).filter(Boolean)) if (!/^[0-9]{6} [a-f0-9]{40,64} 0	/.test(row)) throw fail('dirty','Unmerged Index entries prevent switching.');
+  await checkWorkingPaths(root,trees.flatMap(tree => tree.paths));
+  const flags = decode(await run(['ls-files','-v','-z']));
+  if (flags.split(NUL).filter(Boolean).some(row => !row.startsWith('H '))) throw fail('unsupported','Assume-unchanged, skip-worktree or special Index flags prevent switching.');
+  // Filters have already been excluded before status can inspect working content.
+  const status = await run(['status','--porcelain=v1','-z','--untracked-files=all','--ignored=matching','--ignore-submodules=none']);
+  if (status.length) throw fail('dirty','Working copy must be clean, including staged, untracked and ignored files.');
+  const afterCurrent = await currentBranch(run);
+  const afterTarget = decode(await run(['rev-parse','--verify',target.ref+'^{commit}'])).trim();
+  if (JSON.stringify(current) !== JSON.stringify(afterCurrent) || target.commit !== afterTarget) throw fail('changed','Branch references changed during preview validation.');
+  check(signal);
+  const metadata = await fs.lstat(path.join(root,'.git'),{bigint:true});
+  const repositoryIdentity = [metadata.dev,metadata.ino,metadata.birthtimeNs].map(String);
+  const fingerprint = digest(JSON.stringify({current,target,config,trees,staged,flags,repositoryIdentity,metadataIdentity}));
+  return {root,current,target,fingerprint};
+}
+
+export async function listLocalBranches(repo,{signal} = {}) {
+  return safeContext(repo,signal,async({run}) => ({current:await currentBranch(run),branches:await branches(run)}));
+}
+export async function prepareLocalBranchSwitch(repo,{branch,signal} = {}) {
+  return safeContext(repo,signal,context => snapshotFor(context,branch,signal));
+}
+export async function switchLocalBranch(repo,{snapshot,signal,assertAuthorized,onStart} = {}) {
+  let started = false;
+  try {
+    if (!snapshot || snapshot.root !== repo?.root || typeof snapshot.fingerprint !== 'string' || typeof assertAuthorized !== 'function' || typeof onStart !== 'function') throw fail('changed','A current server-issued branch preview is required.');
+    return await safeContext(repo,signal,async context => {
+      const fresh = await snapshotFor(context,snapshot.target?.name,signal);
+      if (JSON.stringify(fresh) !== JSON.stringify(snapshot)) throw fail('changed','Branch selection or repository state changed; prepare again.');
+      // External Git commands do not share the Host lock. No cross-process atomicity is claimed.
+      await assertAuthorized();check(signal);
+      started = true;onStart();
+      await context.run(['switch','--no-guess','--no-overwrite-ignore','--no-recurse-submodules','--',fresh.target.name]);
+      check(signal);await assertAuthorized();check(signal);
+      const current = await currentBranch(context.run);
+      if (current.ref !== fresh.target.ref || current.commit !== fresh.target.commit) throw fail('changed','Branch changed while switching.');
+      return {current};
+    });
+  } catch (error) {
+    if (!started) throw error;
+    throw Object.assign(fail('outcome-unknown','Branch switch may have changed the working copy. Refresh repository state before any further action.'),{outcomeUnknown:true,cause:error});
+  }
+}