@aicoffe/ai-native-sdlc-mcp 0.1.0

package/dist/workflow/ids.d.ts

@@ -0,0 +1,27 @@
+export declare const SLUG_MAX_LENGTH = 64;
+/**
+ * Lowercase, NFKD-fold, keep only [a-z0-9-], collapse consecutive hyphens,
+ * trim hyphens, cap at 64 chars. Returns '' when nothing survives (e.g.
+ * CJK-only titles) — callers apply the 'wf-NNN' fallback via generateIds.
+ */
+export declare function slugify(title: string): string;
+/** UTC date as YYYYMMDD. */
+export declare function dateCompact(now: Date): string;
+/** UTC date as YYYY-MM-DD. */
+export declare function dateIso(now: Date): string;
+export interface WorkflowIds {
+    workflow_id: string;
+    intent_id: string;
+    slug: string;
+}
+/**
+ * Generate ids for a new workflow. `dailyCount` is the 1-based per-day counter
+ * (persisted in the store index by the caller). The same counter feeds the
+ * 'wf-NNN' slug fallback for titles with no ASCII content.
+ */
+export declare function generateIds(title: string, now: Date, dailyCount: number): WorkflowIds;
+/**
+ * Next per-day counter given all known workflow ids: max existing NNN for the
+ * day (zero-padded 3 digits), +1; starts at 1.
+ */
+export declare function nextDailyCount(existingWorkflowIds: string[], compactDate: string): number;

package/dist/workflow/ids.js

@@ -0,0 +1,63 @@
+// mcp-server/src/workflow/ids.ts
+// Workflow/intent id generation and slug helpers.
+//
+// All dates are UTC (toISOString). The daily counter is injected by the caller
+// (derived from the persisted store index) so this module stays pure.
+export const SLUG_MAX_LENGTH = 64;
+/**
+ * Lowercase, NFKD-fold, keep only [a-z0-9-], collapse consecutive hyphens,
+ * trim hyphens, cap at 64 chars. Returns '' when nothing survives (e.g.
+ * CJK-only titles) — callers apply the 'wf-NNN' fallback via generateIds.
+ */
+export function slugify(title) {
+    const folded = title
+        .normalize('NFKD')
+        .toLowerCase()
+        .replace(/\s+/g, '-') // whitespace becomes a hyphen separator
+        .replace(/[^a-z0-9-]/g, '') // strip everything else (incl. combining marks)
+        .replace(/-{2,}/g, '-') // collapse consecutive hyphens
+        .replace(/^-+|-+$/g, ''); // trim leading/trailing hyphens
+    return folded
+        .slice(0, SLUG_MAX_LENGTH)
+        .replace(/-+$/g, ''); // re-trim after the cap may cut mid-hyphen
+}
+/** UTC date as YYYYMMDD. */
+export function dateCompact(now) {
+    return now.toISOString().slice(0, 10).replace(/-/g, '');
+}
+/** UTC date as YYYY-MM-DD. */
+export function dateIso(now) {
+    return now.toISOString().slice(0, 10);
+}
+function pad3(n) {
+    return String(n).padStart(3, '0');
+}
+/**
+ * Generate ids for a new workflow. `dailyCount` is the 1-based per-day counter
+ * (persisted in the store index by the caller). The same counter feeds the
+ * 'wf-NNN' slug fallback for titles with no ASCII content.
+ */
+export function generateIds(title, now, dailyCount) {
+    const compact = dateCompact(now);
+    const workflow_id = `WF-${compact}-${pad3(dailyCount)}`;
+    const intent_id = `INTENT-${compact}-${pad3(dailyCount)}`;
+    const slug = slugify(title) || `wf-${pad3(dailyCount)}`;
+    return { workflow_id, intent_id, slug };
+}
+/**
+ * Next per-day counter given all known workflow ids: max existing NNN for the
+ * day (zero-padded 3 digits), +1; starts at 1.
+ */
+export function nextDailyCount(existingWorkflowIds, compactDate) {
+    const prefix = `WF-${compactDate}-`;
+    let max = 0;
+    for (const id of existingWorkflowIds) {
+        if (!id.startsWith(prefix))
+            continue;
+        const tail = id.slice(prefix.length);
+        if (!/^\d{3}$/.test(tail))
+            continue;
+        max = Math.max(max, Number.parseInt(tail, 10));
+    }
+    return max + 1;
+}

package/dist/workflow/mutex.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Keyed promise-queue mutex. The mutating workflow tools serialize on a
+ * single REPO-LEVEL key ('$repo'), NOT per-workflow keys: action handlers
+ * operate on the ONE shared git working tree, so concurrent workflows would
+ * otherwise race each other (e.g. workflow B's branch checkout switching
+ * branches under workflow A's in-flight commit). The implementation stays
+ * generic per-key; only the keys used by callers changed.
+ */
+export declare class KeyedMutex {
+    private readonly tails;
+    run<T>(key: string, fn: () => Promise<T>): Promise<T>;
+}

package/dist/workflow/mutex.js

@@ -0,0 +1,24 @@
+// mcp-server/src/workflow/mutex.ts
+/**
+ * Keyed promise-queue mutex. The mutating workflow tools serialize on a
+ * single REPO-LEVEL key ('$repo'), NOT per-workflow keys: action handlers
+ * operate on the ONE shared git working tree, so concurrent workflows would
+ * otherwise race each other (e.g. workflow B's branch checkout switching
+ * branches under workflow A's in-flight commit). The implementation stays
+ * generic per-key; only the keys used by callers changed.
+ */
+export class KeyedMutex {
+    tails = new Map();
+    async run(key, fn) {
+        const prev = this.tails.get(key) ?? Promise.resolve();
+        const next = prev.then(fn, fn);
+        const tail = next.then(() => undefined, () => undefined);
+        this.tails.set(key, tail);
+        void tail.then(() => {
+            if (this.tails.get(key) === tail) {
+                this.tails.delete(key);
+            }
+        });
+        return next;
+    }
+}

package/dist/workflow/paths.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Defense-in-depth containment for store/event paths built from a workflow_id:
+ * resolve under baseDir and assert the result stays there. Traversal ids
+ * (e.g. "../../etc/x") are rejected before any filesystem touch.
+ */
+export declare function resolveUnderBase(baseDir: string, relPath: string): string;

package/dist/workflow/paths.js

@@ -0,0 +1,15 @@
+// mcp-server/src/workflow/paths.ts
+import path from 'node:path';
+/**
+ * Defense-in-depth containment for store/event paths built from a workflow_id:
+ * resolve under baseDir and assert the result stays there. Traversal ids
+ * (e.g. "../../etc/x") are rejected before any filesystem touch.
+ */
+export function resolveUnderBase(baseDir, relPath) {
+    const base = path.resolve(baseDir);
+    const resolved = path.resolve(base, relPath);
+    if (resolved !== base && !resolved.startsWith(base + path.sep)) {
+        throw new Error(`workflow_id escapes store directory: ${relPath}`);
+    }
+    return resolved;
+}

package/dist/workflow/retry.d.ts

@@ -0,0 +1,14 @@
+export type SleepFn = (ms: number) => Promise<void>;
+export declare const defaultSleep: SleepFn;
+export declare function isRetryable(error: Error): boolean;
+/**
+ * Runs a task with up to `maxRetries` attempts (default 3), exponential
+ * backoff Math.pow(2, i) * 1000 ms between attempts, retrying only when
+ * isRetryable(error) is true. Non-retryable errors and the final attempt's
+ * error propagate to the caller.
+ */
+export declare class RetryableAction {
+    private readonly sleep;
+    constructor(sleep?: SleepFn);
+    execute<T>(task: () => Promise<T>, maxRetries?: number): Promise<T>;
+}

package/dist/workflow/retry.js

@@ -0,0 +1,52 @@
+// mcp-server/src/workflow/retry.ts
+import { GhUnavailableError } from './handlers/gh.js';
+export const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+export function isRetryable(error) {
+    if (error instanceof GhUnavailableError)
+        return false;
+    const message = error.message;
+    if (message.includes('ETIMEDOUT'))
+        return true;
+    if (message.includes('ECONNREFUSED'))
+        return true;
+    if (message.includes('rate limit'))
+        return true;
+    if (message.includes('not found'))
+        return false;
+    if (message.includes('permission denied'))
+        return false;
+    if (message.includes('ENOENT'))
+        return false;
+    return false;
+}
+/**
+ * Runs a task with up to `maxRetries` attempts (default 3), exponential
+ * backoff Math.pow(2, i) * 1000 ms between attempts, retrying only when
+ * isRetryable(error) is true. Non-retryable errors and the final attempt's
+ * error propagate to the caller.
+ */
+export class RetryableAction {
+    sleep;
+    constructor(sleep = defaultSleep) {
+        this.sleep = sleep;
+    }
+    async execute(task, maxRetries = 3) {
+        let lastError;
+        for (let i = 0; i < maxRetries; i++) {
+            try {
+                return await task();
+            }
+            catch (error) {
+                lastError = error;
+                if (!isRetryable(asError(error)) || i === maxRetries - 1) {
+                    throw error;
+                }
+                await this.sleep(Math.pow(2, i) * 1000);
+            }
+        }
+        throw lastError;
+    }
+}
+function asError(error) {
+    return error instanceof Error ? error : new Error(String(error));
+}

package/dist/workflow/state-machine.d.ts

@@ -0,0 +1,46 @@
+import type { Stage, WorkflowDefinition, WorkflowState } from './types.js';
+import { WorkflowEventBus } from './event-bus.js';
+import type { WorkflowStore } from './store.js';
+import type { ActionHandler } from './handlers/index.js';
+import { type SleepFn } from './retry.js';
+export interface StateMachineOptions {
+    sleep?: SleepFn;
+    maxRetries?: number;
+}
+export declare class WorkflowStateMachine {
+    private readonly definition;
+    private readonly stateStore;
+    private readonly eventBus;
+    private readonly handlers;
+    private readonly retry;
+    private readonly maxRetries;
+    private readonly offs;
+    constructor(definition: WorkflowDefinition, stateStore: WorkflowStore, eventBus: WorkflowEventBus, actionHandlers: Record<string, ActionHandler>, options?: StateMachineOptions);
+    /** Detaches the machine from the bus (tests rebuild machines on one bus). */
+    dispose(): void;
+    private handleStageCompleted;
+    private handleGateDecision;
+    private handleActionCompleted;
+    private handleActionFailed;
+    private transition;
+    private executeAction;
+    private failedEvent;
+    /** Pure payload builder for llm stages; no side effects, no events. */
+    triggerLLMStage(stage: Stage, state: WorkflowState): Record<string, unknown>;
+    /** Pure payload builder for gates; no side effects, no events. */
+    presentGate(stage: Stage, state: WorkflowState): Record<string, unknown>;
+    /** Doc §6 view consumed by buildToolResponse: llm_generate / gate_wait / processing. */
+    getCurrentStageView(state: WorkflowState): Record<string, unknown>;
+    /**
+     * D10: walk the definition backwards from the current gate to the nearest
+     * preceding llm_generation stage; prefer its RECORDED outputs from the
+     * stage.completed event, fall back to rendered stage.outputs templates.
+     */
+    collectArtifacts(state: WorkflowState): string[];
+    getStage(stageId: string): Stage;
+    renderPath(template: string, state: WorkflowState): string;
+    renderPrompt(template: string | undefined, state: WorkflowState): string;
+    private requireWorkflow;
+    private requireCurrentStage;
+    recoverWorkflows(): Promise<void>;
+}

package/dist/workflow/state-machine.js

@@ -0,0 +1,313 @@
+import { isRetryable, RetryableAction } from './retry.js';
+import { renderStrict, renderTemplate } from './template.js';
+import { validateContextVars } from './handlers/contain.js';
+export class WorkflowStateMachine {
+    definition;
+    stateStore;
+    eventBus;
+    handlers;
+    retry;
+    maxRetries;
+    offs = [];
+    constructor(definition, stateStore, eventBus, actionHandlers, options = {}) {
+        this.definition = definition;
+        this.stateStore = stateStore;
+        this.eventBus = eventBus;
+        this.handlers = actionHandlers;
+        this.retry = new RetryableAction(options.sleep);
+        this.maxRetries = options.maxRetries ?? 3;
+        this.offs.push(this.eventBus.on('stage.completed', (event) => this.handleStageCompleted(event)), this.eventBus.on('gate.decision', (event) => this.handleGateDecision(event)), this.eventBus.on('action.completed', (event) => this.handleActionCompleted(event)), this.eventBus.on('action.failed', (event) => this.handleActionFailed(event)));
+    }
+    /** Detaches the machine from the bus (tests rebuild machines on one bus). */
+    dispose() {
+        for (const off of this.offs)
+            off();
+        this.offs.length = 0;
+    }
+    // ========== 事件处理器 ==========
+    async handleStageCompleted(event) {
+        const state = await this.requireWorkflow(event.workflow_id);
+        this.requireCurrentStage(state, event.stage_id);
+        const currentStage = this.getStage(state.current_stage);
+        if (currentStage.type !== 'llm_generation') {
+            throw new Error(`Stage ${currentStage.id} is not llm_generation`);
+        }
+        state.stages[currentStage.id] = {
+            status: 'completed',
+            output: event.output,
+            completed_at: event.timestamp,
+        };
+        await this.transition(state, currentStage.next);
+    }
+    async handleGateDecision(event) {
+        const state = await this.requireWorkflow(event.workflow_id);
+        this.requireCurrentStage(state, event.stage_id);
+        const currentStage = this.getStage(state.current_stage);
+        if (currentStage.type !== 'gate') {
+            throw new Error(`Stage ${currentStage.id} is not a gate`);
+        }
+        if (!(currentStage.decisions ?? []).includes(event.decision)) {
+            throw new Error(`Decision ${event.decision} is not allowed at gate ${currentStage.id}`);
+        }
+        if (event.decision === 'approved') {
+            state.stages[currentStage.id] = {
+                status: 'approved',
+                approved_by: event.approved_by,
+                approved_at: event.timestamp,
+            };
+            await this.transition(state, currentStage.next);
+        }
+        else if (event.decision === 'rejected') {
+            state.stages[currentStage.id] = {
+                status: 'rejected',
+                rejected_by: event.approved_by,
+                rejected_at: event.timestamp,
+                reason: event.changes,
+            };
+            await this.transition(state, currentStage.on_reject || currentStage.id);
+        }
+        else {
+            state.stages[currentStage.id] = {
+                status: 'pending',
+                modified_at: event.timestamp,
+                changes: event.changes,
+            };
+            await this.transition(state, currentStage.id);
+        }
+    }
+    async handleActionCompleted(event) {
+        const state = await this.requireWorkflow(event.workflow_id);
+        this.requireCurrentStage(state, event.stage_id);
+        const currentStage = this.getStage(state.current_stage);
+        if (currentStage.type !== 'action') {
+            throw new Error(`Stage ${currentStage.id} is not an action`);
+        }
+        state.stages[currentStage.id] = {
+            status: 'completed',
+            result: event.result,
+            completed_at: event.timestamp,
+        };
+        if (event.result.context_updates) {
+            state.context = { ...state.context, ...event.result.context_updates };
+        }
+        await this.transition(state, currentStage.next);
+    }
+    async handleActionFailed(event) {
+        const state = await this.requireWorkflow(event.workflow_id);
+        this.requireCurrentStage(state, event.stage_id);
+        const currentStage = this.getStage(state.current_stage);
+        state.stages[event.stage_id] = {
+            status: 'failed',
+            error: event.error,
+            retryable: event.retryable,
+            failed_at: event.timestamp,
+        };
+        if (event.retryable) {
+            // Stays 'running' on the current action stage; startup recovery re-drives it.
+            state.status = 'running';
+            await this.stateStore.save(state);
+            return;
+        }
+        const targetStageId = currentStage.on_error || 'blocked';
+        if (targetStageId === state.current_stage) {
+            // Already ON the on_error stage and its own handler failed non-retryably:
+            // block and stop — never re-transition (no infinite loop).
+            state.status = 'blocked';
+            await this.stateStore.save(state);
+            return;
+        }
+        await this.transition(state, targetStageId);
+    }
+    // ========== 核心流转逻辑 ==========
+    async transition(state, nextStageId) {
+        const nextStage = this.getStage(nextStageId);
+        // D2 terminal self-loop guard: 'completed'/'blocked' are self-looping action
+        // stages; transitioning onto ourselves must not re-execute the handler.
+        if (nextStageId === state.current_stage && nextStage.type === 'action') {
+            state.status = nextStageId === 'completed' ? 'completed' : 'blocked';
+            state.last_active = new Date().toISOString();
+            await this.stateStore.save(state);
+            return;
+        }
+        state.current_stage = nextStageId;
+        state.last_active = new Date().toISOString();
+        switch (nextStage.type) {
+            case 'llm_generation':
+                state.status = 'running';
+                await this.stateStore.save(state);
+                break;
+            case 'gate':
+                state.status = 'waiting_for_user';
+                await this.stateStore.save(state);
+                break;
+            case 'action':
+                // 状态先落盘：save BEFORE executing the side effect.
+                state.status = 'running';
+                await this.stateStore.save(state);
+                await this.executeAction(nextStage, state);
+                break;
+        }
+    }
+    // ========== Action 执行 ==========
+    async executeAction(stage, state) {
+        const handler = this.handlers[stage.handler];
+        if (!handler) {
+            await this.eventBus.emitWorkflowEvent(this.failedEvent(state.workflow_id, stage.id, `Unknown action handler: ${stage.handler}`, false));
+            return;
+        }
+        try {
+            const result = await this.retry.execute(() => handler(stage.handler_params ?? {}, state), this.maxRetries);
+            await this.eventBus.emitWorkflowEvent({
+                type: 'action.completed',
+                workflow_id: state.workflow_id,
+                stage_id: stage.id,
+                result,
+                timestamp: new Date().toISOString(),
+            });
+        }
+        catch (error) {
+            const err = error instanceof Error ? error : new Error(String(error));
+            await this.eventBus.emitWorkflowEvent(this.failedEvent(state.workflow_id, stage.id, err.message, isRetryable(err)));
+        }
+    }
+    failedEvent(workflowId, stageId, error, retryable) {
+        return {
+            type: 'action.failed',
+            workflow_id: workflowId,
+            stage_id: stageId,
+            error,
+            retryable,
+            timestamp: new Date().toISOString(),
+        };
+    }
+    // ========== 阶段视图（供 Tool 层消费） ==========
+    /** Pure payload builder for llm stages; no side effects, no events. */
+    triggerLLMStage(stage, state) {
+        return {
+            action: 'llm_generate',
+            stage_id: stage.id,
+            skill: stage.skill,
+            prompt: this.renderPrompt(stage.prompt_template, state),
+            inputs: (stage.inputs ?? []).map((p) => this.renderPath(p, state)),
+            outputs: (stage.outputs ?? []).map((p) => this.renderPath(p, state)),
+        };
+    }
+    /** Pure payload builder for gates; no side effects, no events. */
+    presentGate(stage, state) {
+        return {
+            action: 'gate_wait',
+            stage_id: stage.id,
+            checklist: stage.checklist ?? [],
+            prompt: this.renderPrompt(stage.gate_prompt, state),
+            decisions: stage.decisions ?? [],
+            artifacts: this.collectArtifacts(state),
+        };
+    }
+    /** Doc §6 view consumed by buildToolResponse: llm_generate / gate_wait / processing. */
+    getCurrentStageView(state) {
+        const stage = this.getStage(state.current_stage);
+        if (stage.type === 'llm_generation') {
+            return {
+                action: 'llm_generate',
+                workflow_id: state.workflow_id,
+                current_stage: stage.id,
+                skill: stage.skill,
+                prompt: this.renderPrompt(stage.prompt_template, state),
+                inputs: (stage.inputs ?? []).map((p) => this.renderPath(p, state)),
+                outputs: (stage.outputs ?? []).map((p) => this.renderPath(p, state)),
+            };
+        }
+        if (stage.type === 'gate') {
+            const view = this.presentGate(stage, state);
+            return {
+                action: 'gate_wait',
+                workflow_id: state.workflow_id,
+                current_stage: stage.id,
+                checklist: view.checklist,
+                prompt: view.prompt,
+                decisions: view.decisions,
+            };
+        }
+        return { action: 'processing', workflow_id: state.workflow_id, current_stage: stage.id };
+    }
+    /**
+     * D10: walk the definition backwards from the current gate to the nearest
+     * preceding llm_generation stage; prefer its RECORDED outputs from the
+     * stage.completed event, fall back to rendered stage.outputs templates.
+     */
+    collectArtifacts(state) {
+        const idx = this.definition.stages.findIndex((s) => s.id === state.current_stage);
+        for (let i = idx - 1; i >= 0; i--) {
+            const stage = this.definition.stages[i];
+            if (stage.type !== 'llm_generation')
+                continue;
+            const recorded = state.stages[stage.id]?.output;
+            if (recorded && recorded.length > 0) {
+                return [...recorded];
+            }
+            return (stage.outputs ?? []).map((p) => this.renderPath(p, state));
+        }
+        return [];
+    }
+    // ========== 辅助方法 ==========
+    getStage(stageId) {
+        const stage = this.definition.stages.find((s) => s.id === stageId);
+        if (!stage)
+            throw new Error(`Unknown stage: ${stageId}`);
+        return stage;
+    }
+    renderPath(template, state) {
+        return renderStrict(template, state.context);
+    }
+    renderPrompt(template, state) {
+        if (!template)
+            return '';
+        return renderTemplate(template, state.context);
+    }
+    async requireWorkflow(workflowId) {
+        const state = await this.stateStore.load(workflowId);
+        if (!state) {
+            throw new Error(`Unknown workflow: ${workflowId}`);
+        }
+        return state;
+    }
+    requireCurrentStage(state, eventStageId) {
+        if (eventStageId !== state.current_stage) {
+            throw new Error(`Event stage_id ${eventStageId} does not match current stage ${state.current_stage} ` +
+                `(workflow ${state.workflow_id})`);
+        }
+    }
+    // ========== 启动恢复 (M6) ==========
+    async recoverWorkflows() {
+        const states = await this.stateStore.listAll();
+        for (const state of states) {
+            if (state.status !== 'running')
+                continue;
+            const stage = this.definition.stages.find((s) => s.id === state.current_stage);
+            if (!stage || stage.type !== 'action')
+                continue;
+            if (state.stages[stage.id]?.completed_at)
+                continue;
+            try {
+                // On-disk state is untrusted (cloned repos): validate context-derived
+                // path vars before letting any handler touch the filesystem.
+                validateContextVars(state.context);
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                console.error(JSON.stringify({
+                    type: 'workflow.blocked',
+                    workflow_id: state.workflow_id,
+                    stage: state.current_stage,
+                    reason: 'invalid context',
+                    error: message,
+                }));
+                state.status = 'blocked';
+                await this.stateStore.save(state);
+                continue;
+            }
+            // Idempotent handlers make a single re-execution safe.
+            await this.executeAction(stage, state);
+        }
+    }
+}

package/dist/workflow/store.d.ts

@@ -0,0 +1,30 @@
+import type { WorkflowState } from './types.js';
+export interface WorkflowSummary {
+    workflow_id: string;
+    title: string;
+    current_stage: string;
+    status: string;
+    last_active: string;
+}
+export declare function summarize(state: WorkflowState): WorkflowSummary;
+/**
+ * File-backed state store under {repoRoot}/.workflow:
+ *   workflows/{id}.json — one file per workflow state
+ *   index.json          — array of workflow summaries
+ * All file writes go through tmp+rename so readers never observe partial files.
+ */
+export declare class WorkflowStore {
+    private readonly root;
+    private readonly workflowsDir;
+    private readonly indexPath;
+    constructor(repoRoot: string);
+    private statePath;
+    save(state: WorkflowState): Promise<void>;
+    /** Missing workflow → null; callers turn that into an "Unknown workflow" error.
+     *  Containment is checked OUTSIDE the try so traversal ids throw, not return null. */
+    load(id: string): Promise<WorkflowState | null>;
+    listAll(): Promise<WorkflowState[]>;
+    /** Active = neither completed nor blocked. Derived from state files so the list self-heals. */
+    getActiveSummaries(): Promise<WorkflowSummary[]>;
+    updateIndex(state: WorkflowState): Promise<void>;
+}