@ gitkraken/ 共享工具
端口接口、共享类型和用于 core-tools 单相机 域包( 如 @gitkraken/compose-tools)依赖于这个软件包;消费者用自己的git和AI供应商来实施其端口.
港口
GitPort
Raw git 命令执行 。 启动非零退出密码.
interface GitPort {
exec(args: string[], options?: GitExecOptions): Promise<string>;
}
interface GitExecOptions {
env?: Record<string, string>;
stdin?: string;
signal?: AbortSignal;
}
所有更高层次的git操作(diffing, content building, ref management, rebase coordersion等)都是域包中的功能,用于编译调用 exec()消费者从未在这一界面上执行更高层次的操作——见 ComposeGitPort 内 @gitkraken/compose-tools 用于该域特有的可选更高层次操作表面.
signal 从每个接受一个域的工作流程中转发 AbortSignal适配器应该将它连接到其 git-进程执行中,所以取消会终止进程.
AiModelPort
无国籍文本生成 。 呼叫者通过每个呼叫的全部消息历史——会话线程是呼叫者的责任,而不是模型的责任.
interface AiModelPort {
generate(params: AiGenerateParams): Promise<AiGenerateResult>;
}
interface AiGenerateParams {
system?: string;
messages: AiMessage[];
maxTokens?: number;
temperature?: number;
signal?: AbortSignal;
}
interface AiGenerateResult {
text: string;
usage?: AiTokenUsage;
}
signal 从每个AI工作流程中转发。 适配器应该把它接入 LLM 请求中 取消飞行中通话.
StoragePort
Async key/value store for a library's own state, 已被主机范围化 . 无TTL; get 返回时 null 对于一个缺失的密钥. createMemoryStorage() 是不可延长的 Map- 支持实施测试.
interface StoragePort {
get(key: string): Promise<string | null>;
set(key: string, value: string): Promise<void>;
delete(key: string): Promise<void>;
}
TelemetryPort
火灾和遗忘的遥测水槽;执行不得抛出. noopTelemetry 是主机注入一无所有时的默认值。 呼叫者通过可以持有 URL 或错误文本的属性 redactUrlCredentials。 。 。 .
interface TelemetryPort {
event(name: string, attributes?: TelemetryAttributes): void;
exception(error: unknown, attributes?: TelemetryAttributes): void;
}
FileSystemPort
文件系统访问超过绝对的,主机提供的路径. 缺席是 null· ; remove 缺少并丢入非空目录时为无操作, 除非 recursive 设置; mode 是非 POSIX 主机忽略的 POSIX 权限 .
interface FileSystemPort {
readFile(path: string): Promise<string | null>;
writeFile(path: string, content: string, options?: { mode?: number }): Promise<void>;
remove(path: string, options?: { recursive?: boolean }): Promise<void>;
readDir(path: string): Promise<string[] | null>;
}
实施港口
消费者将自己的git和AI供应商包装成适配器. 适配器可以分层遥测,缓存,错误处理,取消,优先排队,或者其他任何行为——都不可见于域包.
示例 GitPort 适配器
import type { GitPort } from '@gitkraken/shared-tools';
const git: GitPort = {
exec: async (args, options) => {
const result = await myGitProvider.run(args, {
cwd: '/path/to/repo',
env: options?.env,
stdin: options?.stdin,
signal: options?.signal,
});
return result.stdout;
},
};
示例 AiModelPort 适配器
import type { AiModelPort } from '@gitkraken/shared-tools';
const ai: AiModelPort = {
generate: async (params) => {
const response = await myAiProvider.chat(params.messages, {
system: params.system,
maxTokens: params.maxTokens,
temperature: params.temperature,
signal: params.signal,
});
return {
text: response.text,
usage: { inputTokens: response.inputTokens, outputTokens: response.outputTokens },
};
},
};
撤消列表
域包使用这些原始来记录一次操作的每次git突变,并随后回放倒数. 机器是共享的,因为它的外形是通俗的——任何能移动回放或改变活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活化活.
capturePreOperationState(git, options?)
抓取工作流程触摸到任何东西之前的操作前状态 :
- 目前HEAD SHA和分支名称.
- 当前工作目录的解密藏出( 通过
git stash create当工作日是脏的时侯, 没有 添加到隐藏列表中 .
撤消使用此快照恢复头部和工作目录 。 抓取帮助器在建立存储器时注意不突变真实的git索引——它使用临时索引通过 GIT_INDEX_FILE 所以消费者的状态 从来没有被扰动.
UndoStore
阅读和写作 UndoManifest 对象输入 repo 对象数据库 refs/undo/<id>。特性在分支操作中幸存,在撤销运行时自动被去除。 提供 save(manifest), (中文(简体) ), load(id), (中文(简体) ), list(), (中文(简体) ), delete(id)。 。 。 .
generateUndoId()
显示一个稳定的UUID,用于新的取消列表 .
undoOperation(input) 财务报告和审定财务报表 validateUndo(input)
核心撤消执行和干运行验证符 。 域包(像作曲)用自己的输入类型来包装这些- undoCompose 以编剧工具代表 undoOperation 翻译后.
出口
数值 :
createMemoryStoragenoopTelemetryredactUrlCredentialscapturePreOperationStategenerateUndoIdUndoStoreundoOperationvalidateUndo
类型 :
GitPort, (中文(简体) ),GitExecOptionsAiModelPort, (中文(简体) ),AiGenerateParams, (中文(简体) ),AiGenerateResult, (中文(简体) ),AiMessage, (中文(简体) ),AiTokenUsageStoragePort, (中文(简体) ),TelemetryPort, (中文(简体) ),TelemetryAttributes, (中文(简体) ),FileSystemPortAiCreditUsage, (中文(简体) ),GetAiCreditUsagePreOperationState, (中文(简体) ),UndoManifest, (中文(简体) ),UndoIdRefKind, (中文(简体) ),RefIdentity, (中文(简体) ),RefSnapshot, (中文(简体) ),RefMovementUndoBlocker, (中文(简体) ),UndoWarning, (中文(简体) ),UndoValidationUndoInput, (中文(简体) ),UndoForceOptions, (中文(简体) ),UndoResult, (中文(简体) ),ValidateUndoInput
也导出 : refKindToFullRefname(kind, name) 用于解析标记为全名的身份.
运行时环境
这个软件包使用节点.js内置(node:crypto, (中文(简体) ), node:fs, (中文(简体) ), node:os, (中文(简体) ), node:path在倒置机械。 在任何环境中,只输入类型都是安全的;运行时间使用 UndoStore, (中文(简体) ), capturePreOperationState, (中文(简体) ), generateUndoId, (中文(简体) ), undoOperation, (中文(简体) ), validateUndo 需要节点运行时间.
捐款
此套件遵循了 monrepo 的标准工具 – 见 root 捐款额。本地命令:
pnpm --filter @gitkraken/shared-tools build
pnpm --filter @gitkraken/shared-tools typecheck
pnpm --filter @gitkraken/shared-tools test
修改端口的设计限制
港口是故意最小和稳定的。 添加方法到 GitPort 或者说 AiModelPort 这对于每一个消费者来说都是一个突破性的变化——每一个执行都必须更新。 在提出新方法之前:
- 确认操作不能表示为基于
exec()或者说generate()。 。 。 . - 确认操作需要多个域包(不仅仅是一个).
- 确认任何消费者都无法合理地在适配器中以不同方式实施该软件.
当堆叠的变更需要合同在使用该合同的包件之前到位时,新港口可能先于消费者落地.
在实践中,新的方法应该是罕见的。 默认的答案是“这是否应该进入港口?” 没有 ——将其放入一个域包中作为调用功能 exec() 编号 : generate() 内部或特定域的端口界面(参见 ComposeGitPort 以作曲工具.