peter/devclaw-gitea
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: make workflow states dynamic with XState-style statechart config (#147) (#160)

Browse Source 
## Summary

Introduces a configurable workflow state machine that replaces all hardcoded
state labels. The default workflow matches current behavior exactly, ensuring
backward compatibility.

## Architecture

### lib/workflow.ts — Core workflow engine

XState-style statechart configuration:

```typescript
type StateConfig = {
  type: 'queue' | 'active' | 'hold' | 'terminal';
  role?: 'dev' | 'qa';
  label: string;
  color: string;
  priority?: number;
  on?: Record<string, TransitionTarget>;
};
```

All behavior is derived from the config:
- Queue states: `type: 'queue'`, grouped by role, ordered by priority
- Active states: `type: 'active'` — worker occupied
- Transitions: defined with optional actions (gitPull, detectPr, closeIssue, reopenIssue)
- Labels and colors: derived from state.label and state.color

### Derivation functions

- `getStateLabels()` — all labels for issue tracker sync
- `getLabelColors()` — label → color mapping
- `getQueueLabels(role)` — queue labels for a role, ordered by priority
- `getActiveLabel(role)` — the active/in-progress label for a role
- `getRevertLabel(role)` — queue label to revert to on failure
- `detectRoleFromLabel()` — detect role from a queue label
- `getCompletionRule(role, result)` — derive transition rule from config

## Files Changed

- **lib/workflow.ts** — NEW: workflow engine and default config
- **lib/providers/provider.ts** — deprecate STATE_LABELS, LABEL_COLORS; derive from workflow
- **lib/providers/github.ts** — use workflow config for label operations
- **lib/providers/gitlab.ts** — use workflow config for label operations
- **lib/services/pipeline.ts** — use getCompletionRule() from workflow
- **lib/services/tick.ts** — use workflow for queue/active labels
- **lib/services/health.ts** — use workflow for active/revert labels
- **lib/tools/work-start.ts** — use workflow for target label

## Backward Compatibility

- DEFAULT_WORKFLOW matches current hardcoded behavior exactly
- Deprecated exports kept for any external consumers
- No breaking changes to tool interfaces or project state

## Future Work

- Load per-project workflow overrides from projects.json
- User-facing config in projects/workflow.json
- Tool schema generation from workflow states
This commit is contained in:
Lauren ten Hoor
2026-02-13 18:50:09 +08:00
committed by GitHub
parent 24235cdbf7
commit dfeadf742a
8 changed files with 617 additions and 109 deletions
Download Patch File Download Diff File Expand all files Collapse all files

33
lib/providers/github.ts
View File

@@ -5,10 +5,15 @@ import {
type IssueProvider,
type Issue,
type StateLabel,
STATE_LABELS,
LABEL_COLORS,
type IssueComment,
} from "./provider.js";
import { runCommand } from "../run-command.js";
import {
DEFAULT_WORKFLOW,
getStateLabels,
getLabelColors,
type WorkflowConfig,
} from "../workflow.js";
type GhIssue = {
number: number;
@@ -28,7 +33,12 @@ function toIssue(gh: GhIssue): Issue {
export class GitHubProvider implements IssueProvider {
private repoPath: string;
constructor(opts: { repoPath: string }) { this.repoPath = opts.repoPath; }
private workflow: WorkflowConfig;
constructor(opts: { repoPath: string; workflow?: WorkflowConfig }) {
this.repoPath = opts.repoPath;
this.workflow = opts.workflow ?? DEFAULT_WORKFLOW;
}
private async gh(args: string[]): Promise<string> {
const result = await runCommand(["gh", ...args], { timeoutMs: 30_000, cwd: this.repoPath });
@@ -41,7 +51,11 @@ export class GitHubProvider implements IssueProvider {
}
async ensureAllStateLabels(): Promise<void> {
for (const label of STATE_LABELS) await this.ensureLabel(label, LABEL_COLORS[label]);
const labels = getStateLabels(this.workflow);
const colors = getLabelColors(this.workflow);
for (const label of labels) {
await this.ensureLabel(label, colors[label]);
}
}
async createIssue(title: string, description: string, label: StateLabel, assignees?: string[]): Promise<Issue> {
@@ -65,7 +79,7 @@ export class GitHubProvider implements IssueProvider {
return toIssue(JSON.parse(raw) as GhIssue);
}
async listComments(issueId: number): Promise<import("./provider.js").IssueComment[]> {
async listComments(issueId: number): Promise<IssueComment[]> {
try {
const raw = await this.gh(["api", `repos/:owner/:repo/issues/${issueId}/comments`, "--jq", ".[] | {author: .user.login, body: .body, created_at: .created_at}"]);
if (!raw) return [];
@@ -75,9 +89,10 @@ export class GitHubProvider implements IssueProvider {
async transitionLabel(issueId: number, from: StateLabel, to: StateLabel): Promise<void> {
const issue = await this.getIssue(issueId);
const stateLabels = issue.labels.filter((l) => STATE_LABELS.includes(l as StateLabel));
const stateLabels = getStateLabels(this.workflow);
const currentStateLabels = issue.labels.filter((l) => stateLabels.includes(l));
const args = ["issue", "edit", String(issueId)];
for (const l of stateLabels) args.push("--remove-label", l);
for (const l of currentStateLabels) args.push("--remove-label", l);
args.push("--add-label", to);
await this.gh(args);
}
@@ -86,8 +101,10 @@ export class GitHubProvider implements IssueProvider {
async reopenIssue(issueId: number): Promise<void> { await this.gh(["issue", "reopen", String(issueId)]); }
hasStateLabel(issue: Issue, expected: StateLabel): boolean { return issue.labels.includes(expected); }
getCurrentStateLabel(issue: Issue): StateLabel | null {
return STATE_LABELS.find((l) => issue.labels.includes(l)) ?? null;
const stateLabels = getStateLabels(this.workflow);
return stateLabels.find((l) => issue.labels.includes(l)) ?? null;
}
async hasMergedMR(issueId: number): Promise<boolean> {

33
lib/providers/gitlab.ts
View File

@@ -5,14 +5,24 @@ import {
type IssueProvider,
type Issue,
type StateLabel,
STATE_LABELS,
LABEL_COLORS,
type IssueComment,
} from "./provider.js";
import { runCommand } from "../run-command.js";
import {
DEFAULT_WORKFLOW,
getStateLabels,
getLabelColors,
type WorkflowConfig,
} from "../workflow.js";
export class GitLabProvider implements IssueProvider {
private repoPath: string;
constructor(opts: { repoPath: string }) { this.repoPath = opts.repoPath; }
private workflow: WorkflowConfig;
constructor(opts: { repoPath: string; workflow?: WorkflowConfig }) {
this.repoPath = opts.repoPath;
this.workflow = opts.workflow ?? DEFAULT_WORKFLOW;
}
private async glab(args: string[]): Promise<string> {
const result = await runCommand(["glab", ...args], { timeoutMs: 30_000, cwd: this.repoPath });
@@ -25,7 +35,11 @@ export class GitLabProvider implements IssueProvider {
}
async ensureAllStateLabels(): Promise<void> {
for (const label of STATE_LABELS) await this.ensureLabel(label, LABEL_COLORS[label]);
const labels = getStateLabels(this.workflow);
const colors = getLabelColors(this.workflow);
for (const label of labels) {
await this.ensureLabel(label, colors[label]);
}
}
async createIssue(title: string, description: string, label: StateLabel, assignees?: string[]): Promise<Issue> {
@@ -52,7 +66,7 @@ export class GitLabProvider implements IssueProvider {
return JSON.parse(raw) as Issue;
}
async listComments(issueId: number): Promise<import("./provider.js").IssueComment[]> {
async listComments(issueId: number): Promise<IssueComment[]> {
try {
const raw = await this.glab(["api", `projects/:id/issues/${issueId}/notes`, "--paginate"]);
const notes = JSON.parse(raw) as Array<{ author: { username: string }; body: string; created_at: string; system: boolean }>;
@@ -69,9 +83,10 @@ export class GitLabProvider implements IssueProvider {
async transitionLabel(issueId: number, from: StateLabel, to: StateLabel): Promise<void> {
const issue = await this.getIssue(issueId);
const stateLabels = issue.labels.filter((l) => STATE_LABELS.includes(l as StateLabel));
const stateLabels = getStateLabels(this.workflow);
const currentStateLabels = issue.labels.filter((l) => stateLabels.includes(l));
const args = ["issue", "update", String(issueId)];
for (const l of stateLabels) args.push("--unlabel", l);
for (const l of currentStateLabels) args.push("--unlabel", l);
args.push("--label", to);
await this.glab(args);
}
@@ -80,8 +95,10 @@ export class GitLabProvider implements IssueProvider {
async reopenIssue(issueId: number): Promise<void> { await this.glab(["issue", "reopen", String(issueId)]); }
hasStateLabel(issue: Issue, expected: StateLabel): boolean { return issue.labels.includes(expected); }
getCurrentStateLabel(issue: Issue): StateLabel | null {
return STATE_LABELS.find((l) => issue.labels.includes(l)) ?? null;
const stateLabels = getStateLabels(this.workflow);
return stateLabels.find((l) => issue.labels.includes(l)) ?? null;
}
async hasMergedMR(issueId: number): Promise<boolean> {

39
lib/providers/provider.ts
View File

@@ -2,18 +2,37 @@
* IssueProvider — Abstract interface for issue tracker operations.
*
* Implementations: GitHub (gh CLI), GitLab (glab CLI).
*
* Note: STATE_LABELS and LABEL_COLORS are kept for backward compatibility
* but new code should use the workflow config via lib/workflow.ts.
*/
import { DEFAULT_WORKFLOW, getStateLabels, getLabelColors } from "../workflow.js";
export const STATE_LABELS = [
"Planning", "To Do", "Doing", "To Test", "Testing", "Done", "To Improve", "Refining",
] as const;
// ---------------------------------------------------------------------------
// State labels — derived from default workflow for backward compatibility
// ---------------------------------------------------------------------------
export type StateLabel = (typeof STATE_LABELS)[number];
/**
* @deprecated Use workflow.getStateLabels() instead.
* Kept for backward compatibility with existing code.
*/
export const STATE_LABELS = getStateLabels(DEFAULT_WORKFLOW) as readonly string[];
export const LABEL_COLORS: Record<StateLabel, string> = {
Planning: "#95a5a6", "To Do": "#428bca", Doing: "#f0ad4e", "To Test": "#5bc0de",
Testing: "#9b59b6", Done: "#5cb85c", "To Improve": "#d9534f", Refining: "#f39c12",
};
/**
* StateLabel type — union of all valid state labels.
* This remains a string type for flexibility with custom workflows.
*/
export type StateLabel = string;
/**
* @deprecated Use workflow.getLabelColors() instead.
* Kept for backward compatibility with existing code.
*/
export const LABEL_COLORS: Record<string, string> = getLabelColors(DEFAULT_WORKFLOW);
// ---------------------------------------------------------------------------
// Issue types
// ---------------------------------------------------------------------------
export type Issue = {
iid: number;
@@ -30,6 +49,10 @@ export type IssueComment = {
created_at: string;
};
// ---------------------------------------------------------------------------
// Provider interface
// ---------------------------------------------------------------------------
export interface IssueProvider {
ensureLabel(name: string, color: string): Promise<void>;
ensureAllStateLabels(): Promise<void>;