@devcxl/opencode-cabbage 0.3.1 → 1.0.0

package/dist/kernel/caller.d.ts

@@ -0,0 +1,48 @@
+/**
+ * 工具调用者校验原语（spec §2.2）。
+ *
+ * 判定：`ctx.agent` 为 agent 名；session 无 parentID（经 session client 检查）→ primary；
+ * 子会话按 agent 名映射角色，未知 agent 保守视为 reviewer（最低权限）。
+ */
+export type CallerRole = "primary" | "developer" | "architect" | "reviewer" | "goal-verify";
+/** 5 个生命周期工具（spec §2.2 / PRD R4） */
+export declare const LIFECYCLE_TOOLS: readonly ["setup_control", "flow_control", "task_control", "tdd_checkpoint", "release_control"];
+/**
+ * 解析工具（+op）允许的角色集。op 级覆盖优先；未知工具保守返回空集（fail-closed）。
+ */
+export declare function rolesForTool(tool: string, op?: string): CallerRole[];
+/** requireCaller 拒绝时的错误码 */
+export declare const CALLER_NOT_AUTHORIZED = "CALLER_NOT_AUTHORIZED";
+/** 工具 execute 上下文的最小可见面（ToolContext 的子集） */
+export interface CallerContext {
+    agent: string;
+    sessionID: string;
+}
+/** session client 的最小可见面（goalClient 的子集） */
+export interface CallerSessionClient {
+    session: {
+        get(input: {
+            sessionID: string;
+        }): Promise<{
+            data?: {
+                parentID?: string | null;
+            };
+        }>;
+    };
+}
+/**
+ * 解析调用者角色：无 parentID（session 查询成功且 data 存在）→ primary；
+ * 查询失败/无 data → 保守视为 reviewer（最低权限，fail-closed）；
+ * 子会话按 agent 名映射；未知 agent → reviewer。
+ */
+export declare function resolveCaller(ctx: CallerContext, client: CallerSessionClient): Promise<CallerRole>;
+/**
+ * 调用者门禁原语：角色在 allowedRoles 内返回 null（通过），
+ * 否则返回含 CALLER_NOT_AUTHORIZED 码的错误消息（调用方组装 `{ code, message }` 响应）。
+ */
+export declare function requireCaller(ctx: CallerContext, allowedRoles: CallerRole[], op: string, client: CallerSessionClient): Promise<string | null>;
+/**
+ * 工具级 caller 门禁：按工具（+op）矩阵解析允许角色后校验。
+ * 供各生命周期工具 execute 内调用（spec §2.2 第一道门；config 层为第二道门）。
+ */
+export declare function requireToolCaller(ctx: CallerContext, tool: string, op: string | undefined, client: CallerSessionClient): Promise<string | null>;

package/dist/kernel/caller.js

@@ -0,0 +1,88 @@
+/**
+ * 工具调用者校验原语（spec §2.2）。
+ *
+ * 判定：`ctx.agent` 为 agent 名；session 无 parentID（经 session client 检查）→ primary；
+ * 子会话按 agent 名映射角色，未知 agent 保守视为 reviewer（最低权限）。
+ */
+/** 5 个生命周期工具（spec §2.2 / PRD R4） */
+export const LIFECYCLE_TOOLS = [
+    "setup_control",
+    "flow_control",
+    "task_control",
+    "tdd_checkpoint",
+    "release_control",
+];
+/** 工具默认允许角色矩阵：primary 全量；developer 仅 tdd_checkpoint；其余角色默认无工具 */
+const TOOL_ROLES = {
+    setup_control: ["primary"],
+    flow_control: ["primary"],
+    task_control: ["primary"],
+    tdd_checkpoint: ["primary", "developer"],
+    release_control: ["primary"],
+};
+/** op 级覆盖（最后匹配优先）：architect 仅 flow_control.status 只读；goal-verify 仅 complete-flow；tdd_checkpoint.not-applicable 仅 primary（spec §2.3 纯文档豁免） */
+const OP_ROLES = {
+    flow_control: {
+        "complete-flow": ["goal-verify"],
+        status: ["primary", "architect"],
+    },
+    tdd_checkpoint: {
+        "not-applicable": ["primary"],
+    },
+};
+/**
+ * 解析工具（+op）允许的角色集。op 级覆盖优先；未知工具保守返回空集（fail-closed）。
+ */
+export function rolesForTool(tool, op) {
+    if (op && OP_ROLES[tool]?.[op])
+        return OP_ROLES[tool][op];
+    return TOOL_ROLES[tool] ?? [];
+}
+/** requireCaller 拒绝时的错误码 */
+export const CALLER_NOT_AUTHORIZED = "CALLER_NOT_AUTHORIZED";
+const ROLE_BY_AGENT = {
+    "dev-lifecycle": "primary",
+    developer: "developer",
+    architect: "architect",
+    reviewer: "reviewer",
+    "goal-verify": "goal-verify",
+};
+/**
+ * 解析调用者角色：无 parentID（session 查询成功且 data 存在）→ primary；
+ * 查询失败/无 data → 保守视为 reviewer（最低权限，fail-closed）；
+ * 子会话按 agent 名映射；未知 agent → reviewer。
+ */
+export async function resolveCaller(ctx, client) {
+    let session;
+    try {
+        session = await client.session.get({ sessionID: ctx.sessionID });
+    }
+    catch {
+        return "reviewer";
+    }
+    if (!session?.data)
+        return "reviewer";
+    if (session.data.parentID)
+        return ROLE_BY_AGENT[ctx.agent] ?? "reviewer";
+    return "primary";
+}
+/**
+ * 调用者门禁原语：角色在 allowedRoles 内返回 null（通过），
+ * 否则返回含 CALLER_NOT_AUTHORIZED 码的错误消息（调用方组装 `{ code, message }` 响应）。
+ */
+export async function requireCaller(ctx, allowedRoles, op, client) {
+    const role = await resolveCaller(ctx, client);
+    if (allowedRoles.includes(role))
+        return null;
+    return `${CALLER_NOT_AUTHORIZED}: caller "${ctx.agent}" resolved as "${role}" is not allowed to call "${op}" (allowed: ${allowedRoles.join(", ")})`;
+}
+/**
+ * 工具级 caller 门禁：按工具（+op）矩阵解析允许角色后校验。
+ * 供各生命周期工具 execute 内调用（spec §2.2 第一道门；config 层为第二道门）。
+ */
+export async function requireToolCaller(ctx, tool, op, client) {
+    const allowed = rolesForTool(tool, op);
+    const label = op ? `${tool}:{op:"${op}"}` : tool;
+    return requireCaller(ctx, allowed, label, client);
+}
+//# sourceMappingURL=caller.js.map

package/dist/kernel/caller.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"caller.js","sourceRoot":"","sources":["../../src/kernel/caller.ts"],"names":[],"mappings":"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"}

package/dist/kernel/context.d.ts

@@ -0,0 +1,27 @@
+/** 注入块内的防重复 marker（message transform 据此跳过已注入的会话） */
+export declare const CONTEXT_MARKER = "cabbage-project-context";
+/** CONTEXT.md 全文注入的行数上限，超长截断并提示 */
+export declare const MAX_CONTEXT_LINES = 200;
+export interface ContextDigest {
+    /** 根 CONTEXT.md 的绝对路径 */
+    path: string;
+    /** 文件 mtime（毫秒），用于缓存刷新判定 */
+    mtimeMs: number;
+    /** sha256(内容) 前 16 位十六进制 */
+    digest: string;
+    /** 从 CONTEXT.md 提取的 ## 标题列表 */
+    terms: string[];
+}
+export interface ContextBlock extends ContextDigest {
+    /** 可直接注入到 prompt 的块文本 */
+    block: string;
+}
+export declare function resetContextCache(): void;
+/**
+ * 发现并摘要项目根 CONTEXT.md。
+ * - 缺失 → 返回 null（不报错）
+ * - mtime 变化才重读，否则命中缓存
+ */
+export declare function getContextBlock(projectDir: string): Promise<ContextBlock | null>;
+/** 取注入块文本；无块时返回空串（调用方无需判空） */
+export declare function formatContextBlock(block: ContextBlock | null): string;

package/dist/kernel/context.js

@@ -0,0 +1,73 @@
+import { createHash } from "node:crypto";
+import { readFile, stat } from "node:fs/promises";
+import path from "node:path";
+/** 注入块内的防重复 marker（message transform 据此跳过已注入的会话） */
+export const CONTEXT_MARKER = "cabbage-project-context";
+/** CONTEXT.md 全文注入的行数上限，超长截断并提示 */
+export const MAX_CONTEXT_LINES = 200;
+let _cache = null;
+export function resetContextCache() {
+    _cache = null;
+}
+/**
+ * 发现并摘要项目根 CONTEXT.md。
+ * - 缺失 → 返回 null（不报错）
+ * - mtime 变化才重读，否则命中缓存
+ */
+export async function getContextBlock(projectDir) {
+    const filePath = path.join(projectDir, "CONTEXT.md");
+    let stats;
+    try {
+        stats = await stat(filePath);
+    }
+    catch {
+        _cache = null;
+        return null;
+    }
+    if (_cache?.projectDir === projectDir && _cache.mtimeMs === stats.mtimeMs) {
+        return buildContextBlock(projectDir, filePath, stats.mtimeMs, _cache.content);
+    }
+    const content = await readFile(filePath, "utf8");
+    _cache = { projectDir, mtimeMs: stats.mtimeMs, content };
+    return buildContextBlock(projectDir, filePath, stats.mtimeMs, content);
+}
+/** 取注入块文本；无块时返回空串（调用方无需判空） */
+export function formatContextBlock(block) {
+    return block?.block ?? "";
+}
+function buildContextBlock(projectDir, filePath, mtimeMs, content) {
+    const digest = createHash("sha256").update(content).digest("hex").slice(0, 16);
+    const terms = extractTerms(content);
+    return {
+        path: filePath,
+        mtimeMs,
+        digest,
+        terms,
+        block: renderBlock(projectDir, filePath, mtimeMs, digest, terms, content),
+    };
+}
+function extractTerms(content) {
+    const terms = [];
+    for (const line of content.split("\n")) {
+        const match = /^##\s+(.+)$/.exec(line);
+        if (match)
+            terms.push(match[1].trim());
+    }
+    return terms;
+}
+function renderBlock(projectDir, filePath, mtimeMs, digest, terms, content) {
+    const lines = content.split("\n");
+    const truncated = lines.length > MAX_CONTEXT_LINES;
+    const body = truncated ? lines.slice(0, MAX_CONTEXT_LINES).join("\n") : content;
+    const header = [
+        "## Project Context (auto-injected)",
+        `<!-- ${CONTEXT_MARKER} -->`,
+        `来源: ${path.relative(projectDir, filePath)} · mtime: ${new Date(mtimeMs).toISOString()} · digest: ${digest}`,
+        terms.length > 0 ? `主题: ${terms.join(", ")}` : "",
+    ].filter(Boolean).join("\n");
+    const truncationNote = truncated
+        ? `\n\n> ⚠️ CONTEXT.md 超过 ${MAX_CONTEXT_LINES} 行，已截断。请直接读取完整文件。`
+        : "";
+    return `${header}\n\n${body}${truncationNote}`;
+}
+//# sourceMappingURL=context.js.map

package/dist/kernel/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/kernel/context.ts"],"names":[],"mappings":"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"}

package/dist/kernel/flow.d.ts

@@ -0,0 +1,166 @@
+export type CmdResult = {
+    stdout: string;
+    stderr: string;
+};
+export type CmdFn = (args: string) => Promise<CmdResult>;
+export declare function setFlowGhExecutor(fn: CmdFn | null): void;
+export declare function setFlowGitExecutor(fn: CmdFn | null): void;
+export declare function flowGh(args: string): Promise<CmdResult>;
+export declare function flowGit(args: string): Promise<CmdResult>;
+export type FlowStage = "requirements" | "design" | "tasks" | "code" | "review";
+export declare const FLOW_STAGES: FlowStage[];
+/** 高风险 Flow 标签：design 与 tasks 之间需用户确认（PRD R11） */
+export declare const RISK_LABEL = "cabbage:risk:high";
+/** 新建 Flow Record 的 body：目标/验收/阶段 checklist（spec §2.3 create-flow） */
+export declare function buildFlowBody(slug: string): string;
+/** 从 body checklist 提取已完成阶段（按流程顺序） */
+export declare function getCompletedStages(body: string): FlowStage[];
+/** 把 stage 的 checkbox 标记为完成；已标记或缺失时幂等返回原 body */
+export declare function markStageComplete(body: string, stage: FlowStage): string;
+/** 从 issue labels 提取当前阶段（阶段序号最大的 cabbage:stage:* 标签） */
+export declare function getCurrentStage(labels: string[]): FlowStage | null;
+export type StageGateResult = {
+    ok: true;
+} | {
+    ok: false;
+    code: string;
+    message: string;
+};
+export type StageOp = "stage-start" | "stage-complete";
+/**
+ * 前置门禁判定：
+ * - stage-start X：前驱阶段须已 completed（requirements 无前置）
+ * - stage-complete X：X 未完成时前驱须已 completed；requirements 完成需 user_confirmed 一次
+ * - stage-start tasks：高风险 Flow（cabbage:risk:high）需 user_confirmed 确认
+ * - 已完成阶段重复 start/complete → 幂等通过
+ */
+export declare function checkStageGate(op: StageOp, stage: FlowStage, completed: FlowStage[], highRisk: boolean, userConfirmed: boolean): StageGateResult;
+export interface FlowRecordSummary {
+    number: number;
+    title: string;
+    state: string;
+    labels: string[];
+}
+export interface SubtaskSummary {
+    number: number;
+    title: string;
+    state: string;
+}
+export interface CheckSummary {
+    name: string;
+    state: string;
+}
+export interface RelatedPrSummary {
+    number: number;
+    title: string;
+    state: string;
+    headRefName: string;
+    checks: CheckSummary[];
+}
+export interface FlowStatusReport {
+    flow: FlowRecordSummary;
+    stages: {
+        completed: FlowStage[];
+        current: FlowStage | null;
+    };
+    subtasks: SubtaskSummary[];
+    pullRequests: RelatedPrSummary[];
+}
+export type FlowStatusResult = {
+    ok: true;
+    status: FlowStatusReport;
+} | {
+    ok: false;
+    code: "NOT_FOUND" | "GITHUB_ERROR";
+    message: string;
+};
+/** 关联 PR：PR body 引用了 Flow 或任一子任务 Issue 号（保留 PR 原始字段） */
+export declare function filterRelatedPrs<T extends {
+    number: number;
+    body?: string;
+}>(prs: T[], parentIssueNumber: number, subtaskNumbers: number[]): T[];
+/** 把 statusCheckRollup 精简为 {name, state} 列表（name 兼容 .name/.context） */
+export declare function summarizeChecks(rollup: Array<{
+    name?: string;
+    context?: string;
+    state: string;
+}>): CheckSummary[];
+/** 读 Flow Record + 子任务 + 关联 PR checks 汇总（spec §2.3 status） */
+export declare function readFlowStatus(parentIssueNumber: number): Promise<FlowStatusResult>;
+export type PlanningResult = {
+    ok: true;
+    worktreePath: string;
+    branch: string;
+    prNumber?: number;
+    reused?: boolean;
+} | {
+    ok: false;
+    code: string;
+    message: string;
+};
+/** 创建 planning worktree `.worktree/planning-<slug>`（architect 在此写文档） */
+export declare function planningStart(projectDir: string, parentIssueNumber: number): Promise<PlanningResult>;
+/** 对 planning worktree 的变更创建 Planning PR（Planning Baseline） */
+export declare function planningPr(projectDir: string, parentIssueNumber: number): Promise<PlanningResult>;
+export interface CreateFlowInput {
+    projectDir: string;
+    title: string;
+    sessionID: string;
+    /** 提供时对已有 Issue 建立 Flow 绑定（不新建）——legacy 检测 + 双 session 检查 */
+    parentIssueNumber?: number;
+}
+export type CreateFlowResult = {
+    ok: true;
+    ref: {
+        parentIssueNumber: number;
+        slug: string;
+    };
+} | {
+    ok: false;
+    code: string;
+    message: string;
+};
+/**
+ * create-flow：
+ * - 新建模式：validateTitle → Profile 门禁 → Draft Parent Issue（body 含目标/验收/阶段 checklist）→ bindSession
+ * - 绑定模式（提供 parentIssueNumber）：legacy 检测（§11.2）→ bindSession 双 session 检查（§10.3）
+ */
+export declare function createFlow(input: CreateFlowInput): Promise<CreateFlowResult>;
+export type FlowLifecycleResult = {
+    ok: true;
+    parentIssueNumber: number;
+} | {
+    ok: false;
+    code: string;
+    message: string;
+};
+/** complete-flow（仅 goal-verify 调用，goal 已验证）：关闭 Parent Issue + 标记 completed */
+export declare function completeFlow(projectDir: string, parentIssueNumber: number): Promise<FlowLifecycleResult>;
+/** cancel-flow：受控取消（user_confirmed）→ 关闭 Issue + 标记 cancelled */
+export declare function cancelFlow(projectDir: string, parentIssueNumber: number, userConfirmed: boolean): Promise<FlowLifecycleResult>;
+export type TakeoverFlowResult = {
+    ok: true;
+    parentIssueNumber: number;
+    oldSessionID: string | null;
+} | {
+    ok: false;
+    code: string;
+    message: string;
+};
+/** takeover：双 session 接管（user_confirmed）→ 旧 session 置 paused + 新 session 绑定（§10.3） */
+export declare function takeoverFlow(projectDir: string, parentIssueNumber: number, newSessionID: string, userConfirmed: boolean): Promise<TakeoverFlowResult>;
+export type ApplyStageResult = {
+    ok: true;
+    stage: FlowStage;
+    completedStages: FlowStage[];
+    highRisk: boolean;
+} | {
+    ok: false;
+    code: string;
+    message: string;
+};
+/**
+ * stage-start / stage-complete：
+ * 门禁（checkStageGate）→ stage-complete 更新 body checklist（乐观锁）→ setStageLabel。
+ */
+export declare function applyStageOp(projectDir: string, parentIssueNumber: number, op: StageOp, stage: FlowStage, userConfirmed: boolean): Promise<ApplyStageResult>;