@kontextmind/kxm 0.6.0

package/plugins/kxm/src/external-effects.ts

@@ -0,0 +1,299 @@
+/**
+ * KXM External Side-Effect Idempotency (Slice C)
+ * Ensures deterministic branching, preflight CAS checks, and immutable receipts for external mutations.
+ */
+
+import { DatabaseSync } from "node:sqlite";
+import { createHash } from "node:crypto";
+import { mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+
+export const EXTERNAL_EFFECT_SCHEMA = "kxm.external-effect-receipt.v1" as const;
+
+export type ExternalActionKind =
+  | "git-branch"
+  | "git-commit"
+  | "git-push"
+  | "pr-create"
+  | "tracker-issue"
+  | "webhook";
+
+export type ExternalEffectStatus = "in-flight" | "committed" | "failed" | "aborted";
+
+export interface ExternalEffectReceipt {
+  schema: typeof EXTERNAL_EFFECT_SCHEMA;
+  effectKey: string;
+  runId: string;
+  stepId: string;
+  attemptId: string;
+  actionKind: ExternalActionKind;
+  targetRef: string;
+  status: ExternalEffectStatus;
+  payloadHash: string;
+  receiptPayload: Record<string, unknown>;
+  executedAt: string;
+  completedAt?: string | undefined;
+}
+
+export interface RunBranchOptions {
+  description?: string | undefined;
+  workflowId?: string | undefined;
+  issueKey?: string | undefined;
+  format?: "prefix-run" | "run-suffix" | undefined;
+}
+
+export function slugifyBranchPart(text: string, maxLength: number = 40): string {
+  const cleaned = text
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  if (cleaned.length <= maxLength) return cleaned;
+  return cleaned.slice(0, maxLength).replace(/-+$/, "");
+}
+
+export function deterministicRunBranch(
+  runId: string,
+  descriptionOrOptions?: string | RunBranchOptions,
+): string {
+  const cleanId = runId.replace(/^run_/, "");
+  if (!descriptionOrOptions) {
+    return `kxm/run-${cleanId}`;
+  }
+
+  const options: RunBranchOptions =
+    typeof descriptionOrOptions === "string"
+      ? { description: descriptionOrOptions }
+      : descriptionOrOptions;
+
+  const parts: string[] = [];
+  if (options.workflowId) {
+    const wf = slugifyBranchPart(options.workflowId, 25);
+    if (wf) parts.push(wf);
+  }
+  if (options.issueKey) {
+    const issue = slugifyBranchPart(options.issueKey, 20);
+    if (issue && !parts.some((p) => p.includes(issue))) parts.push(issue);
+  }
+  if (options.description) {
+    const desc = slugifyBranchPart(options.description, 35);
+    if (desc && !parts.some((p) => p.includes(desc))) parts.push(desc);
+  }
+
+  const slug = parts.join("-").slice(0, 50).replace(/-+$/, "");
+  if (!slug) {
+    return `kxm/run-${cleanId}`;
+  }
+
+  if (options.format === "prefix-run") {
+    return `kxm/${slug}-run-${cleanId}`;
+  }
+  return `kxm/run-${cleanId}-${slug}`;
+}
+
+export function computeEffectKey(
+  runId: string,
+  stepId: string,
+  actionKind: ExternalActionKind,
+  targetRef: string,
+): string {
+  const raw = `${runId}:${stepId}:${actionKind}:${targetRef}`;
+  return `eff_${createHash("sha256").update(raw).digest("hex").slice(0, 16)}`;
+}
+
+export class ExternalEffectsLedger {
+  private db: DatabaseSync;
+
+  constructor(dbPath: string = ":memory:") {
+    if (dbPath !== ":memory:") {
+      mkdirSync(dirname(dbPath), { recursive: true });
+    }
+    this.db = new DatabaseSync(dbPath);
+    this.initSchema();
+  }
+
+  private initSchema(): void {
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS external_effects (
+        effect_key TEXT PRIMARY KEY,
+        run_id TEXT NOT NULL,
+        step_id TEXT NOT NULL,
+        attempt_id TEXT NOT NULL,
+        action_kind TEXT NOT NULL,
+        target_ref TEXT NOT NULL,
+        status TEXT NOT NULL,
+        payload_hash TEXT NOT NULL,
+        receipt_payload TEXT NOT NULL,
+        executed_at TEXT NOT NULL,
+        completed_at TEXT
+      );
+      CREATE INDEX IF NOT EXISTS idx_ext_effects_run ON external_effects(run_id);
+    `);
+  }
+
+  /**
+   * Preflight Check-And-Set (CAS):
+   * Guarantees that an external mutation is only initiated if not already committed or currently in-flight.
+   */
+  claimEffect(input: {
+    runId: string;
+    stepId: string;
+    attemptId: string;
+    actionKind: ExternalActionKind;
+    targetRef: string;
+    payload?: Record<string, unknown> | undefined;
+    timeoutMs?: number | undefined;
+  }): { ok: true; effectKey: string } | { ok: false; error: string; existing?: ExternalEffectReceipt } {
+    const effectKey = computeEffectKey(input.runId, input.stepId, input.actionKind, input.targetRef);
+    const now = new Date().toISOString();
+    const payloadStr = JSON.stringify(input.payload ?? {});
+    const payloadHash = createHash("sha256").update(payloadStr).digest("hex");
+
+    const existing = this.getReceipt(effectKey);
+    if (existing) {
+      if (existing.status === "committed") {
+        return {
+          ok: false,
+          error: `effect_already_committed: ${input.actionKind} on ${input.targetRef} was already committed`,
+          existing,
+        };
+      }
+      if (existing.status === "in-flight") {
+        const timeout = input.timeoutMs ?? 60000;
+        const elapsed = Date.now() - Date.parse(existing.executedAt);
+        if (elapsed < timeout) {
+          return {
+            ok: false,
+            error: `effect_in_flight: ${input.actionKind} on ${input.targetRef} is currently executing`,
+            existing,
+          };
+        }
+        // If timed out, allow reclaim by updating status
+      }
+    }
+
+    const stmt = this.db.prepare(`
+      INSERT INTO external_effects (
+        effect_key, run_id, step_id, attempt_id, action_kind, target_ref,
+        status, payload_hash, receipt_payload, executed_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(effect_key) DO UPDATE SET
+        attempt_id = excluded.attempt_id,
+        status = 'in-flight',
+        executed_at = excluded.executed_at,
+        payload_hash = excluded.payload_hash,
+        receipt_payload = excluded.receipt_payload
+    `);
+
+    stmt.run(
+      effectKey,
+      input.runId,
+      input.stepId,
+      input.attemptId,
+      input.actionKind,
+      input.targetRef,
+      "in-flight",
+      payloadHash,
+      payloadStr,
+      now,
+    );
+
+    return { ok: true, effectKey };
+  }
+
+  commitEffect(
+    effectKey: string,
+    receiptPayload: Record<string, unknown>,
+  ): void {
+    const now = new Date().toISOString();
+    const stmt = this.db.prepare(`
+      UPDATE external_effects
+      SET status = 'committed', receipt_payload = ?, completed_at = ?
+      WHERE effect_key = ?
+    `);
+    stmt.run(JSON.stringify(receiptPayload), now, effectKey);
+  }
+
+  abortEffect(effectKey: string, reason: string): void {
+    const now = new Date().toISOString();
+    const stmt = this.db.prepare(`
+      UPDATE external_effects
+      SET status = 'aborted', receipt_payload = ?, completed_at = ?
+      WHERE effect_key = ?
+    `);
+    stmt.run(JSON.stringify({ error: reason }), now, effectKey);
+  }
+
+  getReceipt(effectKey: string): ExternalEffectReceipt | undefined {
+    const stmt = this.db.prepare(`
+      SELECT * FROM external_effects WHERE effect_key = ?
+    `);
+    const row = stmt.get(effectKey) as {
+      effect_key: string;
+      run_id: string;
+      step_id: string;
+      attempt_id: string;
+      action_kind: ExternalActionKind;
+      target_ref: string;
+      status: ExternalEffectStatus;
+      payload_hash: string;
+      receipt_payload: string;
+      executed_at: string;
+      completed_at: string | null;
+    } | undefined;
+
+    if (!row) return undefined;
+
+    return {
+      schema: EXTERNAL_EFFECT_SCHEMA,
+      effectKey: row.effect_key,
+      runId: row.run_id,
+      stepId: row.step_id,
+      attemptId: row.attempt_id,
+      actionKind: row.action_kind,
+      targetRef: row.target_ref,
+      status: row.status,
+      payloadHash: row.payload_hash,
+      receiptPayload: JSON.parse(row.receipt_payload) as Record<string, unknown>,
+      executedAt: row.executed_at,
+      completedAt: row.completed_at ?? undefined,
+    };
+  }
+
+  listRunEffects(runId: string): ExternalEffectReceipt[] {
+    const stmt = this.db.prepare(`
+      SELECT * FROM external_effects WHERE run_id = ? ORDER BY executed_at ASC
+    `);
+    const rows = stmt.all(runId) as Array<{
+      effect_key: string;
+      run_id: string;
+      step_id: string;
+      attempt_id: string;
+      action_kind: ExternalActionKind;
+      target_ref: string;
+      status: ExternalEffectStatus;
+      payload_hash: string;
+      receipt_payload: string;
+      executed_at: string;
+      completed_at: string | null;
+    }>;
+
+    return rows.map((row) => ({
+      schema: EXTERNAL_EFFECT_SCHEMA,
+      effectKey: row.effect_key,
+      runId: row.run_id,
+      stepId: row.step_id,
+      attemptId: row.attempt_id,
+      actionKind: row.action_kind,
+      targetRef: row.target_ref,
+      status: row.status,
+      payloadHash: row.payload_hash,
+      receiptPayload: JSON.parse(row.receipt_payload) as Record<string, unknown>,
+      executedAt: row.executed_at,
+      completedAt: row.completed_at ?? undefined,
+    }));
+  }
+
+  close(): void {
+    this.db.close();
+  }
+}

package/plugins/kxm/src/github-watch.ts

@@ -0,0 +1,255 @@
+import { createHmac, randomUUID } from "node:crypto";
+import { redactSecrets } from "./redact.ts";
+import type { WorkflowEvidenceInput } from "./workflow.ts";
+
+export type WatchStatus = "passed" | "failed" | "warning";
+
+export interface GithubCheckRun {
+  name: string;
+  status: string;
+  conclusion?: string | null;
+  html_url?: string;
+  completed_at?: string | null;
+}
+
+export interface GithubWatchInput {
+  serverUrl: string;
+  definitionId: string;
+  signalSecret: string;
+  runId: string;
+  stageId: string;
+  signalKey: string;
+  repo: string;
+  pr: number;
+  required?: string[];
+  timeoutMs: number;
+  intervalMs: number;
+  token?: string;
+  deliveryId?: string;
+  dryRun?: boolean;
+  now?: () => number;
+  sleep?: (ms: number) => Promise<void>;
+  fetchImpl?: typeof fetch;
+}
+
+export interface GithubWatchResult {
+  exitCode: number;
+  posted: boolean;
+  duplicate?: boolean;
+  status?: WatchStatus;
+  summary: string;
+  evidence: WorkflowEvidenceInput;
+  deliveryId?: string;
+  skipped?: boolean;
+}
+
+async function fetchWithTimeout(fetchImpl: typeof fetch, input: string, init: RequestInit, timeoutMs: number): Promise<Response> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), Math.max(1, timeoutMs));
+  try {
+    return await fetchImpl(input, { ...init, signal: controller.signal });
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function requiredToken(token: string | undefined): string | undefined {
+  const value = token?.trim();
+  return value || undefined;
+}
+
+const FAILED_CONCLUSIONS = new Set([
+  "failure",
+  "cancelled",
+  "timed_out",
+  "action_required",
+  "stale",
+  "startup_failure",
+]);
+const SUCCESS_CONCLUSIONS = new Set(["success"]);
+const CHECK_RUNS_PER_PAGE = 100;
+const MAX_CHECK_RUN_PAGES = 100;
+
+export function mapCheckConclusion(
+  runs: GithubCheckRun[],
+  required: string[] = [],
+): { status: WatchStatus | "pending"; evidence: WorkflowEvidenceInput } {
+  const names = required.length > 0 ? required : [...new Set(runs.map((run) => run.name))];
+  const interesting = names.map((name) => runs.find((run) => run.name === name));
+  const evidence = Object.fromEntries(interesting.slice(0, 32).map((run, index) => {
+    const name = names[index] ?? "unknown";
+    const conclusion = run?.conclusion ?? run?.status ?? "missing";
+    const url = run?.html_url ? ` url:${run.html_url}` : "";
+    const completed = run?.completed_at ? ` at:${run.completed_at}` : "";
+    return [`github.check:${name}`, redactSecrets(`conclusion:${conclusion}${url}${completed}`).slice(0, 500)];
+  }));
+  if (names.length === 0 || interesting.some((run) => !run || run.status !== "completed")) {
+    return { status: "pending", evidence };
+  }
+  if (interesting.some((run) => FAILED_CONCLUSIONS.has(run?.conclusion ?? ""))) {
+    return { status: "failed", evidence };
+  }
+  if (interesting.every((run) => SUCCESS_CONCLUSIONS.has(run?.conclusion ?? ""))) {
+    return { status: "passed", evidence };
+  }
+  return { status: "pending", evidence };
+}
+
+export async function postWorkflowSignal(input: {
+  serverUrl: string;
+  definitionId: string;
+  signalSecret: string;
+  runId: string;
+  signalKey: string;
+  status: WatchStatus;
+  summary: string;
+  evidence: WorkflowEvidenceInput;
+  deliveryId: string;
+  timeoutMs?: number;
+  fetchImpl?: typeof fetch;
+}): Promise<{ httpStatus: number; duplicate: boolean }> {
+  const body = JSON.stringify({ status: input.status, summary: input.summary, evidence: input.evidence });
+  const signature = `sha256=${createHmac("sha256", input.signalSecret).update(body).digest("hex")}`;
+  const endpoint = [
+    input.serverUrl.replace(/\/$/, ""),
+    "v1/webhooks",
+    encodeURIComponent(input.definitionId),
+    "runs",
+    encodeURIComponent(input.runId),
+    "signals",
+    encodeURIComponent(input.signalKey),
+  ].join("/");
+  const response = await fetchWithTimeout(input.fetchImpl ?? fetch, endpoint, {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      "x-hub-signature-256": signature,
+      "x-kxm-delivery-id": input.deliveryId,
+    },
+    body,
+  }, input.timeoutMs ?? 15_000);
+  const text = await response.text();
+  let duplicate = false;
+  try {
+    const parsed = JSON.parse(text) as { duplicate?: boolean };
+    duplicate = parsed.duplicate === true;
+  } catch {
+    // Non-JSON responses are treated as adapter failures below.
+  }
+  if (!response.ok && response.status !== 200) {
+    throw new Error(`signal_http_${response.status}`);
+  }
+  return { httpStatus: response.status, duplicate };
+}
+
+export async function watchGithubChecks(input: GithubWatchInput): Promise<GithubWatchResult> {
+  const token = requiredToken(input.token);
+  if (!token) {
+    return { exitCode: 1, posted: false, skipped: true, summary: "github_auth_unavailable", evidence: {} };
+  }
+  const fetchImpl = input.fetchImpl ?? fetch;
+  const now = input.now ?? Date.now;
+  const sleep = input.sleep ?? ((ms: number) => new Promise((resolve) => setTimeout(resolve, ms)));
+  const deadline = now() + input.timeoutMs;
+  const headers = {
+    authorization: `Bearer ${token}`,
+    accept: "application/vnd.github+json",
+    "user-agent": "kxm-github-watch",
+  };
+  const contextEvidence: WorkflowEvidenceInput = {
+    "workflow.run": input.runId,
+    "workflow.stage": input.stageId,
+    "workflow.signal": input.signalKey,
+  };
+  const explicitDeliveryId = input.deliveryId?.trim();
+  const deliveryGeneration = randomUUID();
+  let deliveryId = explicitDeliveryId || `github-watch:${deliveryGeneration}:pr-${input.pr}`;
+  const deliver = async (
+    status: WatchStatus,
+    summary: string,
+    evidence: WorkflowEvidenceInput,
+  ): Promise<GithubWatchResult> => {
+    const boundedEvidence = Object.fromEntries(Object.entries({ ...contextEvidence, ...evidence }).slice(0, 64));
+    if (input.dryRun) return { exitCode: status === "failed" && summary === "github_watch_timeout" ? 4 : 0, posted: false, status, summary, evidence: boundedEvidence, deliveryId };
+    for (let attempt = 1; attempt <= 3; attempt += 1) {
+      try {
+        const posted = await postWorkflowSignal({ serverUrl: input.serverUrl, definitionId: input.definitionId, signalSecret: input.signalSecret, runId: input.runId, signalKey: input.signalKey, status, summary, evidence: boundedEvidence, deliveryId, timeoutMs: Math.min(15_000, Math.max(1_000, input.intervalMs)), fetchImpl });
+        return { exitCode: status === "failed" && summary === "github_watch_timeout" ? 4 : 0, posted: true, duplicate: posted.duplicate, status, summary, evidence: boundedEvidence, deliveryId };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : "signal_failed";
+        if (/signal_http_(404|409)\b/.test(message)) return { exitCode: 1, posted: false, summary: "workflow_not_waiting", evidence: boundedEvidence, deliveryId };
+        const transient = /signal_http_(429|5\d\d)\b/.test(message) || message === "signal_failed" || /abort|timeout|fetch/i.test(message);
+        if (!transient || attempt === 3) return { exitCode: 1, posted: false, summary: "signal_failed", evidence: boundedEvidence, deliveryId };
+        await sleep(Math.min(250 * (2 ** (attempt - 1)), 1_000));
+      }
+    }
+    return { exitCode: 1, posted: false, summary: "signal_failed", evidence: boundedEvidence, deliveryId };
+  };
+  const githubGet = async (url: string): Promise<Response | undefined> => {
+    for (let attempt = 1; attempt <= 3; attempt += 1) {
+      const remaining = deadline - now();
+      if (remaining <= 0) return undefined;
+      try {
+        const response = await fetchWithTimeout(fetchImpl, url, { headers }, Math.min(15_000, remaining));
+        if (response.status !== 429 && response.status < 500) return response;
+        if (attempt === 3) return response;
+      } catch {
+        if (attempt === 3 || now() >= deadline) return undefined;
+      }
+      await sleep(Math.min(250 * (2 ** (attempt - 1)), Math.max(1, deadline - now())));
+    }
+    return undefined;
+  };
+  const prResponse = await githubGet(`https://api.github.com/repos/${input.repo}/pulls/${input.pr}`);
+  if (!prResponse) return deliver("failed", "github_watch_timeout", {});
+  if (!prResponse.ok) {
+    return { exitCode: 1, posted: false, summary: "github_pr_unavailable", evidence: { "github.http": String(prResponse.status) } };
+  }
+  const pull = await prResponse.json() as { head?: { sha?: string } };
+  const headSha = pull.head?.sha;
+  if (!headSha) {
+    return { exitCode: 1, posted: false, summary: "github_head_unavailable", evidence: {} };
+  }
+  if (!explicitDeliveryId) deliveryId = `github-watch:${deliveryGeneration}:${headSha.slice(0, 40)}`;
+  let lastEvidence: WorkflowEvidenceInput = {};
+  while (now() <= deadline) {
+    const checkRuns: GithubCheckRun[] = [];
+    for (let page = 1; page <= MAX_CHECK_RUN_PAGES; page += 1) {
+      const checksUrl = new URL(`https://api.github.com/repos/${input.repo}/commits/${headSha}/check-runs`);
+      checksUrl.searchParams.set("per_page", String(CHECK_RUNS_PER_PAGE));
+      checksUrl.searchParams.set("page", String(page));
+      const checksResponse = await githubGet(checksUrl.toString());
+      if (!checksResponse) return deliver("failed", "github_watch_timeout", lastEvidence);
+      if (!checksResponse.ok) {
+        return { exitCode: 1, posted: false, summary: "github_checks_unavailable", evidence: { "github.http": String(checksResponse.status) } };
+      }
+      const payload = await checksResponse.json() as { total_count?: number; check_runs?: GithubCheckRun[] };
+      const pageRuns = Array.isArray(payload.check_runs) ? payload.check_runs : [];
+      checkRuns.push(...pageRuns);
+      const totalCount = Number.isInteger(payload.total_count) && payload.total_count! >= 0
+        ? payload.total_count!
+        : undefined;
+      const complete = totalCount === undefined
+        ? pageRuns.length < CHECK_RUNS_PER_PAGE
+        : checkRuns.length >= totalCount;
+      if (complete) break;
+      if (pageRuns.length === 0 || page === MAX_CHECK_RUN_PAGES) {
+        return {
+          exitCode: 1,
+          posted: false,
+          summary: "github_checks_unavailable",
+          evidence: { "github.pagination": pageRuns.length === 0 ? "incomplete" : "limit_exceeded" },
+        };
+      }
+    }
+    const mapped = mapCheckConclusion(checkRuns, input.required ?? []);
+    lastEvidence = mapped.evidence;
+    if (mapped.status !== "pending") {
+      const summary = mapped.status === "passed" ? "required GitHub checks passed" : "required GitHub checks failed";
+      return deliver(mapped.status, summary, mapped.evidence);
+    }
+    if (now() + input.intervalMs > deadline) break;
+    await sleep(input.intervalMs);
+  }
+  return deliver("failed", "github_watch_timeout", lastEvidence);
+}