mirrors/pikasTech-unidesk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

gh board-row mutations

Browse Source
This commit is contained in:
Codex
2026-05-21 09:49:34 +00:00
parent 5ec68f0671
commit 6e79a34373
3 changed files with 920 additions and 94 deletions
Download Patch File Download Diff File Expand all files Collapse all files
scripts/src/gh.ts
+724 -54
View File
@@ -21,6 +21,8 @@ const ISSUE_LIST_JSON_FIELDS = ["number", "title", "state", "url", "updatedAt",
const PR_JSON_FIELDS = ["body", "title", "state", "number", "url", "author", "head", "base", "draft", "createdAt", "updatedAt"] as const;
const ISSUE_LIST_STATES = ["open", "closed", "all"] as const;
const BODY_UPDATE_MODES = ["replace", "append"] as const;
const BOARD_MUTATION_SECTIONS = ["open", "closed"] as const;
const BOARD_GITHUB_STATUSES = ["OPEN", "CLOSED"] as const;
const MIN_SAFE_BODY_SCAN_CHARS = MIN_SAFE_ISSUE_BODY_CHARS;
const ISSUE_SCAN_MAX_FINDINGS = 60;
const ISSUE_BODY_PROFILES = {
@@ -44,6 +46,8 @@ type IssueListJsonField = typeof ISSUE_LIST_JSON_FIELDS[number];
type PrJsonField = typeof PR_JSON_FIELDS[number];
type IssueListState = typeof ISSUE_LIST_STATES[number];
type BodyUpdateMode = typeof BODY_UPDATE_MODES[number];
type BoardMutationSection = typeof BOARD_MUTATION_SECTIONS[number];
type BoardGithubStatus = typeof BOARD_GITHUB_STATUSES[number];
type IssueBodyProfileName = keyof typeof ISSUE_BODY_PROFILES;
type IssueBodyProfileOption = "auto" | IssueBodyProfileName;
type EscapeFindingClassification = "suspected-pollution" | "explanatory-mention" | "risk";
@@ -52,7 +56,7 @@ type EscapeBodyKind = "issue-body" | "comment-body";
type CleanupSuggestionAction = "rewrite-issue-body-with-body-file" | "review-comment-manually" | "review-body-length" | "no-cleanup-needed";
type BoardSectionKind = "open" | "closed";
type BoardRequiredColumn = typeof BOARD_AUDIT_REQUIRED_COLUMNS[number];
type BoardColumnKind = BoardRequiredColumn | "focus";
type BoardColumnKind = BoardRequiredColumn | "focus" | "githubStatus";
type BoardRowField = typeof BOARD_ROW_FIELDS[number];
type GitHubDegradedReason =
@@ -244,6 +248,12 @@ interface BoardRowUpdatePlanResult {
newBody: string;
}
interface BoardRowMutationPlanResult {
ok: true;
plan: Record<string, unknown>;
newBody: string;
}
interface GitHubCommandResult {
ok: boolean;
repo: string;
@@ -290,6 +300,10 @@ interface GitHubOptions {
bodyProfile: IssueBodyProfileOption;
boardRowField?: BoardRowField;
boardRowValue?: string;
boardRowFile?: string;
boardSection?: BoardMutationSection;
boardMoveTo?: BoardMutationSection;
boardGithubStatus?: BoardGithubStatus;
}
interface IssueProfileValidationContext {
@@ -515,6 +529,18 @@ function parseIssueBodyProfile(args: string[]): IssueBodyProfileOption {
throw new Error(`unsupported --body-profile ${raw}; supported profiles: auto, code-queue-board, commander-brief`);
}
function parseBoardMutationSection(args: string[], name: "--section" | "--to"): BoardMutationSection | undefined {
const raw = optionValue(args, name);
if (raw === undefined) return undefined;
return validateEnumValue(name, raw, BOARD_MUTATION_SECTIONS);
}
function parseBoardGithubStatus(args: string[]): BoardGithubStatus | undefined {
const raw = optionValue(args, "--status");
if (raw === undefined) return undefined;
return validateEnumValue("--status", raw, BOARD_GITHUB_STATUSES);
}
function parseBoardRowField(args: string[]): BoardRowField | undefined {
const raw = optionValue(args, "--field");
if (raw === undefined) return undefined;
@@ -522,7 +548,7 @@ function parseBoardRowField(args: string[]): BoardRowField | undefined {
}
function validateKnownOptions(args: string[]): void {
const valueOptions = new Set(["--repo", "--limit", "--board-issue", "--known-meta-issue", "--ignore-issue", "--title", "--body-file", "--body", "--base", "--head", "--json", "--state", "--mode", "--expect-updated-at", "--expect-body-sha", "--body-profile", "--label", "--field", "--value"]);
const valueOptions = new Set(["--repo", "--limit", "--board-issue", "--known-meta-issue", "--ignore-issue", "--title", "--body-file", "--body", "--base", "--head", "--json", "--state", "--mode", "--expect-updated-at", "--expect-body-sha", "--body-profile", "--label", "--field", "--value", "--section", "--to", "--status", "--row-file"]);
const flagOptions = new Set(["--dry-run", "--draft", "--notify-claudeqq-brief-diff", "--allow-short-body"]);
for (let index = 0; index < args.length; index += 1) {
const arg = args[index];
@@ -566,6 +592,10 @@ function parseOptions(args: string[]): GitHubOptions {
bodyProfile: parseIssueBodyProfile(args),
boardRowField: parseBoardRowField(args),
boardRowValue: optionValue(args, "--value"),
boardRowFile: optionValue(args, "--row-file"),
boardSection: parseBoardMutationSection(args, "--section"),
boardMoveTo: parseBoardMutationSection(args, "--to"),
boardGithubStatus: parseBoardGithubStatus(args),
};
}
@@ -1279,6 +1309,7 @@ function boardHeaderColumnKind(header: string): BoardColumnKind | null {
if (["branch", "分支", "目标分支", "工作分支"].includes(normalized)) return "branch";
if (["acceptance", "验收", "验收状态", "验收结果", "验收标准"].includes(normalized)) return "acceptance";
if (["relatedtask", "task", "codequeue", "codequeuetask", "相关任务", "任务", "codequeue任务", "cq任务", "相关codequeue任务", "相关codequeuetask"].includes(normalized)) return "relatedTask";
if (["githubstatus", "githubstate", "github状态", "githubissue状态", "issuestate", "issue状态", "issuegithub状态", "开闭状态", "openclosed", "openclosed状态"].includes(normalized)) return "githubStatus";
if (["focus", "currentfocus", "关注点", "当前关注点", "当前focus"].includes(normalized)) return "focus";
if (["progress", "进度", "状态", "当前进度"].includes(normalized)) return "progress";
return null;
@@ -1390,6 +1421,33 @@ function primaryBoardIssueNumberFromIssueCell(issueCell: string | undefined): nu
return null;
}
function boardRowFromCells(section: BoardTableSection, raw: string, cells: string[], lineNumber: number): BoardTableRow {
const columnMap = boardRequiredColumnIndexMap(section.headers);
const issueColumnIndex = boardIssueColumnIndex(section.headers);
const issueCell = issueColumnIndex === null ? undefined : cells[issueColumnIndex];
const primaryIssueNumber = issueColumnIndex === null ? null : primaryBoardIssueNumberFromIssueCell(issueCell);
const issueNumbers = issueColumnIndex === null
? extractIssueNumbers(raw)
: (primaryIssueNumber === null ? extractIssueNumbers(issueCell ?? "") : [primaryIssueNumber]);
const columns: Partial<Record<BoardRequiredColumn, string>> = {};
for (const column of BOARD_AUDIT_REQUIRED_COLUMNS) {
const cellIndex = columnMap.get(column);
if (cellIndex !== undefined) columns[column] = cells[cellIndex] ?? "";
}
return {
section: section.kind,
lineNumber,
raw,
cells,
issueNumbers,
issueNumber: issueNumbers[0] ?? null,
title: issueColumnIndex === null
? (cells.find((cell) => extractIssueNumbers(cell).length > 0) ?? cells[0] ?? null)
: (issueCell ?? cells[0] ?? null),
columns,
};
}
function normalizedBoardCellPlaceholder(value: string): { spaced: string; compact: string } {
const spaced = stripMarkdownInline(value).toLowerCase().replace(/\s+/g, " ").trim();
return { spaced, compact: spaced.replace(/\s+/g, "") };
@@ -1447,37 +1505,19 @@ function parseBoardTables(body: string): { sections: BoardTableSection[]; warnin
const separator = lines[index + 1];
if (separator === undefined || !separator.trim().startsWith("|") || !isMarkdownTableSeparator(separator)) continue;
const headers = markdownCells(lines[index]);
const columnMap = boardRequiredColumnIndexMap(headers);
const issueColumnIndex = boardIssueColumnIndex(headers);
const rows: BoardTableRow[] = [];
let rowIndex = index + 2;
while (rowIndex < lines.length && lines[rowIndex].trim().startsWith("|")) {
if (!isMarkdownTableSeparator(lines[rowIndex])) {
const cells = markdownCells(lines[rowIndex]);
const issueCell = issueColumnIndex === null ? undefined : cells[issueColumnIndex];
const primaryIssueNumber = issueColumnIndex === null ? null : primaryBoardIssueNumberFromIssueCell(issueCell);
const issueNumbers = issueColumnIndex === null
? extractIssueNumbers(lines[rowIndex])
: (primaryIssueNumber === null ? extractIssueNumbers(issueCell ?? "") : [primaryIssueNumber]);
const columns: Partial<Record<BoardRequiredColumn, string>> = {};
for (const column of BOARD_AUDIT_REQUIRED_COLUMNS) {
const cellIndex = columnMap.get(column);
if (cellIndex !== undefined) columns[column] = cells[cellIndex] ?? "";
}
const row: BoardTableRow = {
section: currentKind,
lineNumber: rowIndex + 1,
raw: lines[rowIndex],
const row = boardRowFromCells(
{ kind: currentKind, heading: currentHeading, headingLine: currentHeadingLine, headerLine: index + 1, headers, rows: [] },
lines[rowIndex],
cells,
issueNumbers,
issueNumber: issueNumbers[0] ?? null,
title: issueColumnIndex === null
? (cells.find((cell) => extractIssueNumbers(cell).length > 0) ?? cells[0] ?? null)
: (issueCell ?? cells[0] ?? null),
columns,
};
rowIndex + 1,
);
rows.push(row);
if (issueNumbers.length === 0) {
if (row.issueNumbers.length === 0) {
warnings.push({
issueNumber: null,
section: currentKind,
@@ -1487,19 +1527,19 @@ function parseBoardTables(body: string): { sections: BoardTableSection[]; warnin
rowPreview: preview(row.raw),
});
}
if (issueNumbers.length > 1) {
if (row.issueNumbers.length > 1) {
warnings.push({
issueNumber: row.issueNumber,
section: currentKind,
lineNumber: row.lineNumber,
kind: "multiple-issue-references",
message: issueColumnIndex === null
message: boardIssueColumnIndex(headers) === null
? "Board table row contains multiple issue references; audit uses the first number as the row key."
: "Board table row contains multiple issue references in the Issue column; audit uses the first number as the row key.",
rowPreview: preview(row.raw),
});
}
const missingColumns = BOARD_AUDIT_REQUIRED_COLUMNS.filter((column) => !cellHasMeaningfulValue(columns[column], column));
const missingColumns = BOARD_AUDIT_REQUIRED_COLUMNS.filter((column) => !cellHasMeaningfulValue(row.columns[column], column));
if (missingColumns.length > 0) {
warnings.push({
issueNumber: row.issueNumber,
@@ -1508,7 +1548,7 @@ function parseBoardTables(body: string): { sections: BoardTableSection[]; warnin
kind: "missing-required-columns",
message: "Board table row is missing branch, acceptance, related task, or progress information.",
missingColumns,
columns,
columns: row.columns,
rowPreview: preview(row.raw),
});
}
@@ -1577,6 +1617,35 @@ function boardRowsForState(sections: BoardTableSection[], state: IssueListState)
.flatMap((section) => section.rows.map((row) => ({ section, row })));
}
function boardDuplicateRows(
sections: BoardTableSection[],
issueNumber: number,
): Array<{ section: BoardTableSection; row: BoardTableRow }> {
return boardRowsForState(sections, "all").filter(({ row }) => row.issueNumber === issueNumber);
}
function targetBoardSection(
repo: string,
sections: BoardTableSection[],
kind: BoardMutationSection,
commandName: string,
): { ok: true; section: BoardTableSection } | GitHubCommandFailure {
const matches = sections.filter((section) => section.kind === kind);
if (matches.length === 0) {
return validationError(commandName, repo, `board ${kind.toUpperCase()} table was not found`, {
section: kind,
availableSections: sections.map((section) => ({ kind: section.kind, heading: section.heading, headerLine: section.headerLine })),
}) as GitHubCommandFailure;
}
if (matches.length > 1) {
return validationError(commandName, repo, `board ${kind.toUpperCase()} table is ambiguous`, {
section: kind,
matches: matches.map((section) => ({ heading: section.heading, headingLine: section.headingLine, headerLine: section.headerLine })),
}) as GitHubCommandFailure;
}
return { ok: true, section: matches[0] };
}
function findBoardRow(
repo: string,
sections: BoardTableSection[],
@@ -1620,6 +1689,25 @@ function renderMarkdownTableRow(cells: string[]): string {
return `| ${cells.map(escapeMarkdownTableCell).join(" | ")} |`;
}
function validateMarkdownTableRowLine(line: string): string | null {
if (!line.trim().startsWith("|") || !line.trim().endsWith("|")) return "row-file must contain a Markdown table row starting and ending with |";
if (isMarkdownTableSeparator(line)) return "row-file must contain a data row, not a Markdown table separator";
return null;
}
function readBoardRowFile(path: string | undefined, command: string): { path: string; raw: string; cells: string[] } {
if (path === undefined) throw new Error(`${command} requires --row-file <markdown-row-file>`);
if (!existsSync(path)) throw new Error(`row file not found: ${path}`);
const normalized = normalizeNewlines(readFileSync(path, "utf8")).trim();
if (normalized.length === 0) throw new Error("row-file must contain exactly one non-empty Markdown table row");
const lines = normalized.split("\n");
if (lines.length !== 1) throw new Error("row-file must contain exactly one Markdown table row");
const line = lines[0];
const lineError = validateMarkdownTableRowLine(line);
if (lineError !== null) throw new Error(lineError);
return { path, raw: line, cells: markdownCells(line) };
}
function replaceBoardBodyLine(body: string, lineNumber: number, newLine: string): string {
const normalized = normalizeNewlines(body);
const lines = normalized.split("\n");
@@ -1628,6 +1716,27 @@ function replaceBoardBodyLine(body: string, lineNumber: number, newLine: string)
return lines.join("\n");
}
function removeBoardBodyLine(body: string, lineNumber: number): string {
const normalized = normalizeNewlines(body);
const lines = normalized.split("\n");
if (lineNumber <= 0 || lineNumber > lines.length) throw new Error(`line ${lineNumber} is outside the board body`);
lines.splice(lineNumber - 1, 1);
return lines.join("\n");
}
function insertBoardBodyLineAfter(body: string, lineNumber: number, newLine: string): string {
const normalized = normalizeNewlines(body);
const lines = normalized.split("\n");
if (lineNumber < 0 || lineNumber > lines.length) throw new Error(`insert line ${lineNumber} is outside the board body`);
lines.splice(lineNumber, 0, newLine);
return lines.join("\n");
}
function boardSectionInsertAfterLine(section: BoardTableSection): number {
if (section.rows.length === 0) return section.headerLine + 1;
return section.rows[section.rows.length - 1].lineNumber;
}
function boardBodySafetyIssue(repo: string, boardIssueNumber: number, body: string, options: GitHubOptions): GitHubCommandResult | null {
const guardOptions: GitHubOptions = { ...options, bodyProfile: boardIssueNumber === CODE_QUEUE_BOARD_TARGET_ISSUE ? "code-queue-board" : options.bodyProfile };
return validateIssueBodyGuard(repo, boardIssueNumber, body, guardOptions);
@@ -1723,6 +1832,512 @@ function boardRowUpdatePlan(
};
}
function expectedBoardGithubStatus(section: BoardMutationSection): BoardGithubStatus {
return section === "open" ? "OPEN" : "CLOSED";
}
function normalizeBoardGithubStatusCell(value: string | undefined): BoardGithubStatus | null {
const normalized = stripMarkdownInline(value ?? "").toUpperCase().replace(/\s+/g, "");
if (normalized === "OPEN") return "OPEN";
if (normalized === "CLOSED") return "CLOSED";
return null;
}
function boardHeaderShape(headers: string[]): string[] {
return headers.map((header) => normalizeBoardHeader(header));
}
function sameBoardHeaderShape(a: string[], b: string[]): boolean {
const left = boardHeaderShape(a);
const right = boardHeaderShape(b);
return left.length === right.length && left.every((value, index) => value === right[index]);
}
function boardRowDuplicateFailure(
repo: string,
commandName: string,
sections: BoardTableSection[],
issueNumber: number,
): GitHubCommandFailure | null {
const duplicates = boardDuplicateRows(sections, issueNumber);
if (duplicates.length === 0) return null;
return validationError(commandName, repo, `board row for issue #${issueNumber} already exists; refusing duplicate row`, {
issueNumber,
matches: duplicates.map(({ section, row }) => ({ section: section.kind, lineNumber: row.lineNumber, rowPreview: preview(row.raw) })),
}) as GitHubCommandFailure;
}
function boardStatusOptionFailure(
repo: string,
commandName: string,
targetSection: BoardMutationSection,
status: BoardGithubStatus | undefined,
): GitHubCommandFailure | null {
if (status === undefined) return null;
const expected = expectedBoardGithubStatus(targetSection);
if (status === expected) return null;
return validationError(commandName, repo, `--status ${status} conflicts with --to ${targetSection}; expected ${expected}`, {
targetSection,
status,
expectedStatus: expected,
}) as GitHubCommandFailure;
}
function boardRowStatusConsistency(
repo: string,
commandName: string,
section: BoardTableSection,
row: BoardTableRow,
role: "source" | "target",
): { ok: true; githubStatusColumnIndex: number; actualStatus: BoardGithubStatus | null; expectedStatus: BoardGithubStatus } | GitHubCommandFailure {
const columnMap = boardColumnIndexMap(section.headers);
const githubStatusColumnIndex = columnMap.get("githubStatus");
if (githubStatusColumnIndex === undefined) {
return validationError(commandName, repo, `${role} board table does not contain a GitHub 状态 column`, {
section: section.kind,
headers: section.headers,
lineNumber: row.lineNumber,
rowPreview: preview(row.raw),
}) as GitHubCommandFailure;
}
const expectedStatus = expectedBoardGithubStatus(section.kind);
const actualStatus = normalizeBoardGithubStatusCell(row.cells[githubStatusColumnIndex]);
if (actualStatus !== expectedStatus) {
return validationError(commandName, repo, `${role} row GitHub 状态 ${actualStatus ?? "missing"} conflicts with ${section.kind.toUpperCase()} section; expected ${expectedStatus}`, {
section: section.kind,
lineNumber: row.lineNumber,
rowPreview: preview(row.raw),
actualStatus,
expectedStatus,
githubStatusColumnIndex,
headers: section.headers,
}) as GitHubCommandFailure;
}
return { ok: true, githubStatusColumnIndex, actualStatus, expectedStatus };
}
function boardRowAddPlan(
repo: string,
boardIssue: GitHubIssue,
issueNumber: number,
sectionKind: BoardMutationSection,
rowFile: { path: string; raw: string; cells: string[] },
parsed: { sections: BoardTableSection[]; warnings: BoardRowValidationWarning[] },
): BoardRowMutationPlanResult | GitHubCommandFailure {
const commandName = "issue board-row add";
const duplicate = boardRowDuplicateFailure(repo, commandName, parsed.sections, issueNumber);
if (duplicate !== null) return duplicate;
const targetLookup = targetBoardSection(repo, parsed.sections, sectionKind, commandName);
if (targetLookup.ok === false) return targetLookup;
const target = targetLookup.section;
const issueColumnIndex = boardIssueColumnIndex(target.headers);
if (issueColumnIndex === null) {
return validationError(commandName, repo, "board table does not contain an Issue column required for row-file validation", {
boardIssue: boardIssue.number,
section: sectionKind,
headers: target.headers,
}) as GitHubCommandFailure;
}
const columnMap = boardColumnIndexMap(target.headers);
const githubStatusColumnIndex = columnMap.get("githubStatus");
if (githubStatusColumnIndex === undefined) {
return validationError(commandName, repo, "board table does not contain a GitHub 状态 column required for add section validation", {
boardIssue: boardIssue.number,
section: sectionKind,
headers: target.headers,
}) as GitHubCommandFailure;
}
if (rowFile.cells.length !== target.headers.length) {
return validationError(commandName, repo, "row-file column count does not match the target board table header", {
boardIssue: boardIssue.number,
section: sectionKind,
expectedColumns: target.headers.length,
actualColumns: rowFile.cells.length,
headers: target.headers,
rowFile: rowFile.path,
rowPreview: preview(rowFile.raw),
}) as GitHubCommandFailure;
}
const row = boardRowFromCells(target, rowFile.raw, rowFile.cells, 0);
if (row.issueNumber !== issueNumber) {
return validationError(commandName, repo, "row-file Issue column does not match the requested issue number", {
issueNumber,
issueColumnIndex,
issueCell: rowFile.cells[issueColumnIndex] ?? "",
detectedIssueNumber: row.issueNumber,
rowPreview: preview(rowFile.raw),
}) as GitHubCommandFailure;
}
const expectedStatus = expectedBoardGithubStatus(sectionKind);
const actualStatus = normalizeBoardGithubStatusCell(rowFile.cells[githubStatusColumnIndex]);
if (actualStatus !== expectedStatus) {
return validationError(commandName, repo, "row-file GitHub 状态 column does not match the target section", {
issueNumber,
section: sectionKind,
expectedStatus,
actualStatus,
statusColumnIndex: githubStatusColumnIndex,
statusCell: rowFile.cells[githubStatusColumnIndex] ?? "",
rowPreview: preview(rowFile.raw),
}) as GitHubCommandFailure;
}
const oldBody = boardIssue.body ?? "";
const insertAfterLine = boardSectionInsertAfterLine(target);
let newBody: string;
try {
newBody = insertBoardBodyLineAfter(oldBody, insertAfterLine, rowFile.raw);
} catch (error) {
return validationError(commandName, repo, error instanceof Error ? error.message : String(error), {
issueNumber,
section: sectionKind,
insertAfterLine,
}) as GitHubCommandFailure;
}
return {
ok: true,
newBody,
plan: {
repo,
boardIssue: boardIssue.number,
issueNumber,
action: "add",
section: sectionKind,
insertAfterLine,
rowFile: rowFile.path,
newRow: rowFile.raw,
newCells: rowFile.cells,
row: {
old: null,
new: boardRowSummary(target, { ...row, lineNumber: insertAfterLine + 1 }),
},
linePlan: {
action: "insert",
section: sectionKind,
insertAfterLine,
newLineNumber: insertAfterLine + 1,
},
sectionPlan: {
kind: sectionKind,
heading: target.heading,
headerLine: target.headerLine,
rowCount: target.rows.length,
},
validation: {
issueColumnIndex,
githubStatusColumnIndex,
expectedStatus,
actualStatus,
columnCount: rowFile.cells.length,
},
body: {
oldBodyChars: oldBody.length,
oldBodySha: bodySha(oldBody),
newBodyChars: newBody.length,
newBodySha: bodySha(newBody),
changed: oldBody !== newBody,
},
tableParser: {
reused: "parseBoardTables",
rowValidationWarnings: parsed.warnings.length,
},
request: {
method: "PATCH",
path: `/repos/{owner}/{repo}/issues/${boardIssue.number}`,
body: { bodyChars: newBody.length },
},
},
};
}
function moveBoardBodyRow(body: string, sourceLineNumber: number, insertAfterLine: number, newLine: string): string {
const normalized = normalizeNewlines(body);
const lines = normalized.split("\n");
if (sourceLineNumber <= 0 || sourceLineNumber > lines.length) throw new Error(`line ${sourceLineNumber} is outside the board body`);
if (insertAfterLine < 0 || insertAfterLine > lines.length) throw new Error(`insert line ${insertAfterLine} is outside the board body`);
lines.splice(sourceLineNumber - 1, 1);
const adjustedInsertAfterLine = sourceLineNumber <= insertAfterLine ? insertAfterLine - 1 : insertAfterLine;
lines.splice(adjustedInsertAfterLine, 0, newLine);
return lines.join("\n");
}
function boardRowMovePlan(
repo: string,
boardIssue: GitHubIssue,
issueNumber: number,
targetKind: BoardMutationSection,
status: BoardGithubStatus | undefined,
parsed: { sections: BoardTableSection[]; warnings: BoardRowValidationWarning[] },
): BoardRowMutationPlanResult | GitHubCommandFailure {
const commandName = "issue board-row move";
const statusFailure = boardStatusOptionFailure(repo, commandName, targetKind, status);
if (statusFailure !== null) return statusFailure;
const found = findBoardRow(repo, parsed.sections, issueNumber);
if (found.ok === false) return { ...found, command: commandName, repo } as GitHubCommandFailure;
const sourceConsistency = boardRowStatusConsistency(repo, commandName, found.section, found.row, "source");
if (sourceConsistency.ok === false) return sourceConsistency;
const targetLookup = targetBoardSection(repo, parsed.sections, targetKind, commandName);
if (targetLookup.ok === false) return targetLookup;
const target = targetLookup.section;
const { section: source, row } = found;
if (!sameBoardHeaderShape(source.headers, target.headers)) {
return validationError(commandName, repo, "source and target board tables have different headers; refusing to move a raw row across mismatched columns", {
issueNumber,
source: { section: source.kind, headers: source.headers, headerLine: source.headerLine },
target: { section: target.kind, headers: target.headers, headerLine: target.headerLine },
}) as GitHubCommandFailure;
}
if (row.cells.length !== target.headers.length) {
return validationError(commandName, repo, "source row column count does not match the target board table header", {
issueNumber,
source: { section: source.kind, lineNumber: row.lineNumber, rowPreview: preview(row.raw), cells: row.cells.length },
target: { section: target.kind, headers: target.headers, columns: target.headers.length },
}) as GitHubCommandFailure;
}
const columnMap = boardColumnIndexMap(target.headers);
const githubStatusColumnIndex = columnMap.get("githubStatus");
if (githubStatusColumnIndex === undefined) {
return validationError(commandName, repo, "target board table does not contain a GitHub 状态 column required for section migration", {
issueNumber,
targetSection: targetKind,
headers: target.headers,
}) as GitHubCommandFailure;
}
const oldCells = row.cells.slice();
const newCells = oldCells.slice();
const expectedStatus = expectedBoardGithubStatus(targetKind);
if (githubStatusColumnIndex !== undefined) newCells[githubStatusColumnIndex] = status ?? expectedStatus;
const newRow = renderMarkdownTableRow(newCells);
const oldBody = boardIssue.body ?? "";
const insertAfterLine = boardSectionInsertAfterLine(target);
let newBody: string;
try {
newBody = source.kind === target.kind
? replaceBoardBodyLine(oldBody, row.lineNumber, newRow)
: moveBoardBodyRow(oldBody, row.lineNumber, insertAfterLine, newRow);
} catch (error) {
return validationError(commandName, repo, error instanceof Error ? error.message : String(error), {
issueNumber,
sourceLineNumber: row.lineNumber,
insertAfterLine,
}) as GitHubCommandFailure;
}
return {
ok: true,
newBody,
plan: {
repo,
boardIssue: boardIssue.number,
issueNumber,
action: source.kind === target.kind ? "move-within-section" : "move",
from: source.kind,
to: target.kind,
sourceLineNumber: row.lineNumber,
insertAfterLine,
oldRow: row.raw,
newRow,
oldCells,
newCells,
row: {
old: boardRowSummary(source, row),
new: boardRowSummary(target, { ...row, section: target.kind, raw: newRow, cells: newCells, lineNumber: source.kind === target.kind ? row.lineNumber : insertAfterLine + 1 }),
},
linePlan: {
action: source.kind === target.kind ? "replace" : "move",
sourceLineNumber: row.lineNumber,
insertAfterLine,
newLineNumber: source.kind === target.kind ? row.lineNumber : insertAfterLine + 1,
},
sectionPlan: {
from: source.kind,
to: target.kind,
sourceHeading: source.heading,
targetHeading: target.heading,
},
status: {
requested: status ?? null,
targetDefault: expectedStatus,
githubStatusColumnIndex: githubStatusColumnIndex ?? null,
old: oldCells[githubStatusColumnIndex] ?? "",
new: newCells[githubStatusColumnIndex] ?? "",
},
body: {
oldBodyChars: oldBody.length,
oldBodySha: bodySha(oldBody),
newBodyChars: newBody.length,
newBodySha: bodySha(newBody),
changed: oldBody !== newBody,
},
tableParser: {
reused: "parseBoardTables",
rowValidationWarnings: parsed.warnings.length,
},
request: {
method: "PATCH",
path: `/repos/{owner}/{repo}/issues/${boardIssue.number}`,
body: { bodyChars: newBody.length },
},
},
};
}
function boardRowDeletePlan(
repo: string,
boardIssue: GitHubIssue,
issueNumber: number,
parsed: { sections: BoardTableSection[]; warnings: BoardRowValidationWarning[] },
): BoardRowMutationPlanResult | GitHubCommandFailure {
const commandName = "issue board-row delete";
const found = findBoardRow(repo, parsed.sections, issueNumber);
if (found.ok === false) return { ...found, command: commandName, repo } as GitHubCommandFailure;
const { section, row } = found;
const sourceConsistency = boardRowStatusConsistency(repo, commandName, section, row, "source");
if (sourceConsistency.ok === false) return sourceConsistency;
const oldBody = boardIssue.body ?? "";
let newBody: string;
try {
newBody = removeBoardBodyLine(oldBody, row.lineNumber);
} catch (error) {
return validationError(commandName, repo, error instanceof Error ? error.message : String(error), {
issueNumber,
lineNumber: row.lineNumber,
}) as GitHubCommandFailure;
}
return {
ok: true,
newBody,
plan: {
repo,
boardIssue: boardIssue.number,
issueNumber,
action: "delete",
section: section.kind,
lineNumber: row.lineNumber,
oldRow: row.raw,
oldCells: row.cells,
row: {
old: boardRowSummary(section, row),
new: null,
},
linePlan: {
action: "remove",
section: section.kind,
lineNumber: row.lineNumber,
},
sectionPlan: {
kind: section.kind,
heading: section.heading,
headerLine: section.headerLine,
rowCount: section.rows.length,
},
body: {
oldBodyChars: oldBody.length,
oldBodySha: bodySha(oldBody),
newBodyChars: newBody.length,
newBodySha: bodySha(newBody),
changed: oldBody !== newBody,
},
tableParser: {
reused: "parseBoardTables",
rowValidationWarnings: parsed.warnings.length,
},
request: {
method: "PATCH",
path: `/repos/{owner}/{repo}/issues/${boardIssue.number}`,
body: { bodyChars: newBody.length },
},
},
};
}
async function issueBoardRowMutation(
repo: string,
token: string,
issueNumber: number,
options: GitHubOptions,
commandName: "issue board-row add" | "issue board-row move" | "issue board-row delete",
mutationKey: "add" | "move" | "delete",
buildPlan: (boardIssue: GitHubIssue, parsed: { sections: BoardTableSection[]; warnings: BoardRowValidationWarning[] }) => BoardRowMutationPlanResult | GitHubCommandFailure,
): Promise<GitHubCommandResult> {
const concurrencyOptionError = assertConcurrencyOptions(options, commandName);
if (concurrencyOptionError !== null) return { ...concurrencyOptionError, command: commandName, repo };
const boardIssue = await getIssue(token, repo, options.boardIssue);
if (isGitHubError(boardIssue)) return commandError(commandName, repo, boardIssue, { boardIssue: options.boardIssue, issueNumber });
const parsed = parseBoardTables(boardIssue.body ?? "");
const planned = buildPlan(boardIssue, parsed);
if (planned.ok === false) return planned;
const guardError = boardBodySafetyIssue(repo, options.boardIssue, planned.newBody, options);
const guard = boardBodyGuardSummary(options.boardIssue, planned.newBody, options);
const hasConcurrencyGuard = options.expectBodySha !== undefined || options.expectUpdatedAt !== undefined;
const effectiveDryRun = options.dryRun || !hasConcurrencyGuard;
const base = {
ok: true,
command: commandName,
repo,
boardIssue: {
number: boardIssue.number,
title: boardIssue.title,
state: boardIssue.state,
url: boardIssue.html_url,
bodyChars: (boardIssue.body ?? "").length,
bodySha: bodySha(boardIssue.body ?? ""),
updatedAt: boardIssue.updated_at ?? null,
},
issueNumber,
dryRun: effectiveDryRun,
planned: true,
[mutationKey]: planned.plan,
guard,
bodyOnlySafety: {
oldBody: {
fetched: true,
bodyChars: (boardIssue.body ?? "").length,
bodySha: bodySha(boardIssue.body ?? ""),
updatedAt: boardIssue.updated_at ?? null,
},
newBody: {
bodyChars: planned.newBody.length,
bodySha: bodySha(planned.newBody),
...bodySafetySignals(planned.newBody),
},
},
concurrency: {
expectUpdatedAt: options.expectUpdatedAt ?? null,
expectBodySha: options.expectBodySha ?? null,
note: `non-dry-run board-row ${mutationKey} requires --expect-body-sha or --expect-updated-at and checks the current board issue before PATCH`,
},
};
if (guardError !== null) return { ...guardError, command: commandName, [mutationKey]: planned.plan, guard };
if (effectiveDryRun) {
return {
...base,
dryRun: true,
wouldPatch: { issueNumber: options.boardIssue, bodySha: bodySha(planned.newBody), bodyChars: planned.newBody.length },
note: !hasConcurrencyGuard
? "Default dry-run because no concurrency expectation was supplied; no GitHub issue body was modified."
: "Dry-run only; no GitHub issue body was modified.",
};
}
const concurrencyError = validateIssueConcurrency(repo, options.boardIssue, boardIssue, options);
if (concurrencyError !== null) return { ...base, ...concurrencyError, command: commandName };
const { owner, name } = repoParts(repo);
const issue = await githubRequest<GitHubIssue>(token, "PATCH", `/repos/${owner}/${name}/issues/${options.boardIssue}`, { body: planned.newBody });
if (isGitHubError(issue)) return commandError(commandName, repo, issue, { issueNumber, [mutationKey]: planned.plan });
return {
...base,
dryRun: false,
planned: false,
issue: issueSummary(issue),
concurrency: {
checked: true,
oldIssueUpdatedAt: boardIssue.updated_at ?? null,
oldBodySha: bodySha(boardIssue.body ?? ""),
expectUpdatedAt: options.expectUpdatedAt ?? null,
expectBodySha: options.expectBodySha ?? null,
},
rest: true,
};
}
async function issueBoardRowList(repo: string, token: string, options: GitHubOptions): Promise<GitHubCommandResult> {
const commandName = "issue board-row list";
const boardIssue = await getIssue(token, repo, options.boardIssue);
@@ -1795,7 +2410,7 @@ async function issueBoardRowUpdate(repo: string, token: string, issueNumber: num
shellPollution: { suspected: true, evidence: valuePollutionEvidence },
});
}
const concurrencyOptionError = assertConcurrencyOptions(options);
const concurrencyOptionError = assertConcurrencyOptions(options, commandName);
if (concurrencyOptionError !== null) return { ...concurrencyOptionError, command: commandName, repo };
const boardIssue = await getIssue(token, repo, options.boardIssue);
@@ -1855,7 +2470,7 @@ async function issueBoardRowUpdate(repo: string, token: string, issueNumber: num
};
}
const concurrencyError = validateIssueConcurrency(repo, options.boardIssue, boardIssue, options);
if (concurrencyError !== null) return { ...base, ...concurrencyError };
if (concurrencyError !== null) return { ...base, ...concurrencyError, command: commandName };
const { owner, name } = repoParts(repo);
const issue = await githubRequest<GitHubIssue>(token, "PATCH", `/repos/${owner}/${name}/issues/${options.boardIssue}`, { body: planned.newBody });
if (isGitHubError(issue)) return commandError(commandName, repo, issue, { issueNumber, update: planned.plan });
@@ -1875,6 +2490,56 @@ async function issueBoardRowUpdate(repo: string, token: string, issueNumber: num
};
}
async function issueBoardRowAdd(repo: string, token: string, issueNumber: number, options: GitHubOptions): Promise<GitHubCommandResult> {
const commandName = "issue board-row add";
if (options.boardSection === undefined) return validationError(commandName, repo, "issue board-row add requires --section open|closed", { issueNumber, supportedSections: BOARD_MUTATION_SECTIONS.slice() });
let rowFile: { path: string; raw: string; cells: string[] };
try {
rowFile = readBoardRowFile(options.boardRowFile, commandName);
} catch (error) {
return validationError(commandName, repo, error instanceof Error ? error.message : String(error), {
issueNumber,
rowFile: options.boardRowFile ?? null,
});
}
return issueBoardRowMutation(
repo,
token,
issueNumber,
options,
commandName,
"add",
(boardIssue, parsed) => boardRowAddPlan(repo, boardIssue, issueNumber, options.boardSection as BoardMutationSection, rowFile, parsed),
);
}
async function issueBoardRowMove(repo: string, token: string, issueNumber: number, options: GitHubOptions): Promise<GitHubCommandResult> {
const commandName = "issue board-row move";
if (options.boardMoveTo === undefined) return validationError(commandName, repo, "issue board-row move requires --to open|closed", { issueNumber, supportedTargets: BOARD_MUTATION_SECTIONS.slice() });
return issueBoardRowMutation(
repo,
token,
issueNumber,
options,
commandName,
"move",
(boardIssue, parsed) => boardRowMovePlan(repo, boardIssue, issueNumber, options.boardMoveTo as BoardMutationSection, options.boardGithubStatus, parsed),
);
}
async function issueBoardRowDelete(repo: string, token: string, issueNumber: number, options: GitHubOptions): Promise<GitHubCommandResult> {
const commandName = "issue board-row delete";
return issueBoardRowMutation(
repo,
token,
issueNumber,
options,
commandName,
"delete",
(boardIssue, parsed) => boardRowDeletePlan(repo, boardIssue, issueNumber, parsed),
);
}
function ignoredIssueList(issues: BoardIssueEntry[], ignoreMap: Map<number, "known-meta" | "ignored">): BoardIgnoredIssue[] {
return sortedIssueEntries(issues.filter((issue) => ignoreMap.has(issue.number))).map((issue) => ({
number: issue.number,
@@ -2038,13 +2703,13 @@ function issueEditGuardSummary(issueNumber: number, body: string, options: GitHu
};
}
function assertConcurrencyOptions(options: GitHubOptions): GitHubCommandResult | null {
function assertConcurrencyOptions(options: GitHubOptions, commandName: string): GitHubCommandResult | null {
if (options.expectBodySha === undefined) return null;
try {
normalizeExpectedSha(options.expectBodySha);
return null;
} catch (error) {
return validationError("issue edit", options.repo, error instanceof Error ? error.message : String(error), {
return validationError(commandName, options.repo, error instanceof Error ? error.message : String(error), {
expectBodySha: options.expectBodySha,
});
}
@@ -2702,7 +3367,7 @@ async function issueEdit(repo: string, token: string, issueNumber: number, optio
const bodyGuard = validateIssueBodyGuard(repo, issueNumber, body, options);
if (bodyGuard !== null) return bodyGuard;
}
const concurrencyOptionError = assertConcurrencyOptions(options);
const concurrencyOptionError = assertConcurrencyOptions(options, commandName);
if (concurrencyOptionError !== null) return concurrencyOptionError;
let oldIssue: GitHubIssue | null = null;
let briefDiff: CommanderBriefDiff | null = null;
@@ -3398,7 +4063,9 @@ export function ghHelp(): unknown {
"bun scripts/cli.ts gh issue board-row list [--repo owner/name] --board-issue 20 [--state open|closed|all] [--dry-run]",
"bun scripts/cli.ts gh issue board-row get <issueNumber> [--repo owner/name] --board-issue 20",
"bun scripts/cli.ts gh issue board-row update <issueNumber> [--repo owner/name] --board-issue 20 --field progress|status|validation|branch|tasks|focus --value <text> [--dry-run] [--expect-updated-at ts|--expect-body-sha sha256]",
"bun scripts/cli.ts gh issue board-row move|delete <issueNumber> [unsupported in first phase]",
"bun scripts/cli.ts gh issue board-row add <issueNumber> [--repo owner/name] --board-issue 20 --section open|closed --row-file <markdown-row-file> [--dry-run] [--expect-body-sha sha256]",
"bun scripts/cli.ts gh issue board-row move <issueNumber> [--repo owner/name] --board-issue 20 --to open|closed [--status OPEN|CLOSED] [--dry-run] [--expect-body-sha sha256]",
"bun scripts/cli.ts gh issue board-row delete <issueNumber> [--repo owner/name] --board-issue 20 [--dry-run] [--expect-body-sha sha256]",
"bun scripts/cli.ts gh pr list [--repo owner/name] [--limit N] [--json number,title,state,url,updatedAt,createdAt,author,head,base,draft]",
"bun scripts/cli.ts gh pr read <number> [--repo owner/name] [--json body,title,state,head,base,draft]",
"bun scripts/cli.ts gh pr view <number> [--repo owner/name] [compatibility alias for pr read]",
@@ -3427,7 +4094,7 @@ export function ghHelp(): unknown {
"issue scan-escape classifies literal \\n findings as suspected-pollution, explanatory-mention, or risk, and emits cleanupSuggestions with body/comment ids plus diff-like previews. cleanup-plan is an alias that remains dry-run/read-only.",
"issue board-audit is read-only and defaults to repo pikasTech/unidesk plus board issue #20. It compares GitHub open/closed issue lists with the board OPEN/CLOSED tables and reports missingOpenIssues, closedInOpenRows, missingClosedRows, rowValidationWarnings, ignoredIssues, and recommendedActions. When an Issue column exists, row.issueNumber is taken from that column; #20 and #24 are known meta issues by default.",
"issue board-row list/get reuse the board-audit table parser and are read-only. board-row update changes one table cell by issue number, returns old/new row, body SHA, body guard and request plan, and defaults to dry-run unless --expect-updated-at or --expect-body-sha is supplied for the guarded PATCH. Field aliases map status and validation to the 验收状态 column, tasks to 相关 Code Queue 任务, and focus to 当前关注点.",
"issue board-row move/delete are structured unsupported in this phase; open/closed relocation and row removal need explicit table placement and duplicate-row semantics before they write.",
"issue board-row add/move/delete are row-scoped #20 table mutations. add validates a one-line --row-file against the target table column count, Issue column, and GitHub 状态 column; move refuses duplicate/ambiguous rows and can update GitHub 状态 via --status; delete removes only the matched row. All three default to dry-run and require --expect-body-sha or --expect-updated-at before PATCH. add/move/delete return old/new row, body SHA, and line/section plan details for the parsed table mutation.",
"issue edit 24 --notify-claudeqq-brief-diff remains the legacy #24 notification helper: it reads the old issue body, PATCHes the new body, and sends only newly added '## 更新 ... 北京时间' sections to ClaudeQQ; ClaudeQQ failure does not roll back GitHub.",
"Commander brief ClaudeQQ defaults to private target 645275593 through backend-core /api/microservices/claudeqq/proxy; UNIDESK_COMMANDER_BRIEF_CLAUDEQQ_* env vars can override target, base URL, timeout, and enabled state.",
"comment delete is supported because GitHub supports deleting issue comments; issue/pr hard delete is unsupported and close is the lifecycle alternative.",
@@ -3468,9 +4135,9 @@ export async function runGhCommand(args: string[]): Promise<GitHubCommandResult
const command = [top, sub].filter((value): value is string => value !== undefined).join(" ") || "gh";
return validationError(command, options.repo, "--mode is only supported by gh issue update/edit and gh pr update");
}
if ((options.allowShortBody || options.expectUpdatedAt !== undefined || options.expectBodySha !== undefined || optionWasProvided(args, "--body-profile")) && !(top === "issue" && (sub === "edit" || sub === "update" || sub === "board-row" && third === "update"))) {
if ((options.allowShortBody || options.expectUpdatedAt !== undefined || options.expectBodySha !== undefined || optionWasProvided(args, "--body-profile")) && !(top === "issue" && (sub === "edit" || sub === "update" || sub === "board-row" && ["update", "add", "move", "delete"].includes(third ?? "")))) {
const command = [top, sub].filter((value): value is string => value !== undefined).join(" ") || "gh";
return validationError(command, options.repo, "--allow-short-body, --expect-updated-at, --expect-body-sha, and --body-profile are only supported by gh issue update/edit and gh issue board-row update");
return validationError(command, options.repo, "--allow-short-body, --expect-updated-at, --expect-body-sha, and --body-profile are only supported by gh issue update/edit and gh issue board-row update/add/move/delete");
}
if ((optionWasProvided(args, "--board-issue") || optionWasProvided(args, "--known-meta-issue") || optionWasProvided(args, "--ignore-issue")) && !(top === "issue" && (sub === "board-audit" || sub === "board-row"))) {
const command = [top, sub].filter((value): value is string => value !== undefined).join(" ") || "gh";
@@ -3484,6 +4151,18 @@ export async function runGhCommand(args: string[]): Promise<GitHubCommandResult
const command = [top, sub, third].filter((value): value is string => value !== undefined).join(" ") || "gh";
return validationError(command, options.repo, "--field and --value are only supported by gh issue board-row update");
}
if (optionWasProvided(args, "--row-file") && !(top === "issue" && sub === "board-row" && third === "add")) {
const command = [top, sub, third].filter((value): value is string => value !== undefined).join(" ") || "gh";
return validationError(command, options.repo, "--row-file is only supported by gh issue board-row add");
}
if (optionWasProvided(args, "--section") && !(top === "issue" && sub === "board-row" && third === "add")) {
const command = [top, sub, third].filter((value): value is string => value !== undefined).join(" ") || "gh";
return validationError(command, options.repo, "--section is only supported by gh issue board-row add");
}
if ((optionWasProvided(args, "--to") || optionWasProvided(args, "--status")) && !(top === "issue" && sub === "board-row" && third === "move")) {
const command = [top, sub, third].filter((value): value is string => value !== undefined).join(" ") || "gh";
return validationError(command, options.repo, "--to and --status are only supported by gh issue board-row move");
}
if (optionWasProvided(args, "--label") && !(top === "issue" && sub === "create")) {
const command = [top, sub].filter((value): value is string => value !== undefined).join(" ") || "gh";
return validationError(command, options.repo, "--label is only supported by gh issue create");
@@ -3527,20 +4206,8 @@ export async function runGhCommand(args: string[]): Promise<GitHubCommandResult
if (sub === "board-row") {
const action = third;
const commandName = `issue board-row ${action ?? ""}`.trim();
if (action === "move") {
return unsupportedCommand(commandName, options.repo, "board-row move is deferred in the first phase; open/closed row relocation needs explicit destination-section insertion rules, duplicate-row handling, and audit-safe closed/open semantics before it can write.", {
boardIssue: options.boardIssue,
boundary: "row list/get/update are supported; move between OPEN/CLOSED tables remains unsupported and performs no write",
});
}
if (action === "delete") {
return unsupportedCommand(commandName, options.repo, "board-row delete is deferred in the first phase; row removal needs an explicit archival/delete policy and duplicate-row guard before it can write.", {
boardIssue: options.boardIssue,
boundary: "row list/get/update are supported; delete remains unsupported and performs no write",
});
}
if (action !== "list" && action !== "get" && action !== "update") {
return unsupportedCommand(commandName, options.repo, "board-row supported commands are list, get, update, and structured unsupported move/delete.");
if (action !== "list" && action !== "get" && action !== "update" && action !== "add" && action !== "move" && action !== "delete") {
return unsupportedCommand(commandName, options.repo, "board-row supported commands are list, get, update, add, move, and delete.");
}
const { token, probe } = resolveToken(true);
const missing = authRequired(options.repo, commandName, probe);
@@ -3549,7 +4216,10 @@ export async function runGhCommand(args: string[]): Promise<GitHubCommandResult
const issueNumber = parseNumberForCommand(options.repo, args[3], commandName);
if (typeof issueNumber !== "number") return issueNumber;
if (action === "get") return issueBoardRowGet(options.repo, token, issueNumber, options);
return issueBoardRowUpdate(options.repo, token, issueNumber, options);
if (action === "update") return issueBoardRowUpdate(options.repo, token, issueNumber, options);
if (action === "add") return issueBoardRowAdd(options.repo, token, issueNumber, options);
if (action === "move") return issueBoardRowMove(options.repo, token, issueNumber, options);
return issueBoardRowDelete(options.repo, token, issueNumber, options);
}
if (options.dryRun) {
if (sub === "create") return issueCreate(options.repo, "", options);