@guilz-dev/sdlc-gh 0.1.0

package/scripts/lib/stacks.mjs

@@ -0,0 +1,138 @@
+#!/usr/bin/env node
+/**
+ * Read stack catalog from config/stacks.json and infer stack/mode candidates.
+ */
+import { readFileSync, readdirSync, statSync, existsSync } from "node:fs";
+import { join, dirname, basename, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "../..");
+const CATALOG_PATH = join(ROOT, "config/stacks.json");
+export const DEFAULT_EXCLUDED_DIRS = new Set([
+  ".git",
+  "node_modules",
+  "vendor",
+  ".venv",
+  "dist",
+  "build",
+  "coverage",
+  "tmp",
+  "sample",
+]);
+
+let cached;
+
+export function loadStacks() {
+  if (!cached) {
+    cached = JSON.parse(readFileSync(CATALOG_PATH, "utf8"));
+  }
+  return cached.stacks;
+}
+
+export function getStack(id) {
+  const stack = loadStacks().find((s) => s.id === id);
+  if (!stack) {
+    throw new Error(`Unknown stack: ${id}`);
+  }
+  return stack;
+}
+
+export function stackIds() {
+  return loadStacks().map((s) => s.id);
+}
+
+function walk(dir, root, markersByName, nestedMatches) {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (entry.isDirectory()) {
+      if (DEFAULT_EXCLUDED_DIRS.has(entry.name)) continue;
+      walk(join(dir, entry.name), root, markersByName, nestedMatches);
+      continue;
+    }
+
+    const stacks = markersByName.get(entry.name);
+    if (!stacks) continue;
+
+    const fullPath = join(dir, entry.name);
+    const relPath = relative(root, fullPath);
+    if (!relPath || relPath === entry.name) continue;
+
+    for (const stack of stacks) {
+      nestedMatches.push({ stackId: stack.id, path: relPath });
+    }
+  }
+}
+
+export function detectStackCandidates(repoPath) {
+  const repoRoot = resolve(repoPath);
+  const stacks = loadStacks();
+  const rootMatches = [];
+  const nestedMatches = [];
+
+  for (const stack of stacks) {
+    if (existsSync(join(repoRoot, stack.marker))) {
+      rootMatches.push({ stackId: stack.id, path: stack.marker });
+    }
+  }
+
+  if (existsSync(repoRoot) && statSync(repoRoot).isDirectory()) {
+    const markersByName = new Map();
+    for (const stack of stacks) {
+      const key = basename(stack.marker);
+      const values = markersByName.get(key) ?? [];
+      values.push(stack);
+      markersByName.set(key, values);
+    }
+    walk(repoRoot, repoRoot, markersByName, nestedMatches);
+  }
+
+  const rootStackIds = [...new Set(rootMatches.map((m) => m.stackId))];
+  const nestedStackIds = [...new Set(nestedMatches.map((m) => m.stackId))];
+  const suggested =
+    rootStackIds.length === 1
+      ? rootStackIds[0]
+      : rootStackIds.length === 0 && nestedStackIds.length === 1 && nestedStackIds[0] !== "ts"
+        ? nestedStackIds[0]
+        : null;
+
+  return {
+    repoRoot,
+    rootMatches,
+    nestedMatches,
+    suggested,
+    ambiguous:
+      rootStackIds.length > 1 ||
+      nestedStackIds.length > 1 ||
+      (rootStackIds.length === 0 && nestedStackIds.length === 1 && nestedStackIds[0] === "ts"),
+  };
+}
+
+export function inspectRepoMode(repoPath) {
+  const target = resolve(repoPath);
+  if (!existsSync(target)) {
+    return { suggested: "new", reason: "target directory does not exist", ambiguous: false };
+  }
+  if (!statSync(target).isDirectory()) {
+    throw new Error(`Not a directory: ${target}`);
+  }
+
+  const entries = readdirSync(target).filter((entry) => entry !== ".DS_Store");
+  if (entries.length === 0) {
+    return { suggested: "new", reason: "target directory is empty", ambiguous: false };
+  }
+
+  const nonGitEntries = entries.filter((entry) => entry !== ".git");
+  if (nonGitEntries.length === 0) {
+    return { suggested: null, reason: "target contains only .git", ambiguous: true };
+  }
+
+  const rootMarkers = loadStacks().filter((stack) => existsSync(join(target, stack.marker)));
+  if (rootMarkers.length > 0) {
+    return { suggested: "existing", reason: "detected existing stack marker files", ambiguous: false };
+  }
+
+  if (nonGitEntries.every((entry) => /^README(\..+)?$/i.test(entry) || entry === ".gitignore")) {
+    return { suggested: null, reason: "target looks like a seed repository", ambiguous: true };
+  }
+
+  return { suggested: "existing", reason: "target already contains files", ambiguous: false };
+}

package/scripts/lib/telemetry-artifact.mjs

@@ -0,0 +1,253 @@
+/**
+ * Canonical telemetry artifact shape for inner-loop workflows.
+ * See docs/telemetry-schema.md and docs/telemetry-artifacts.md.
+ */
+
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { execSync } from "node:child_process";
+import { extractClosingIssueNumbers } from "./ccsd-contract.mjs";
+import { aggregateDiffStats, parseLabelInput, resolveAutonomyLevel } from "./diff-size.mjs";
+
+export const TELEMETRY_SCHEMA_VERSION = "1";
+export const ARTIFACT_DIR = "telemetry-artifacts";
+
+/** Required payload fields per docs/telemetry-schema.md */
+export const TELEMETRY_REQUIRED_FIELDS = [
+  "task_id",
+  "pr_number",
+  "repo",
+  "agent_type",
+  "execution_mode",
+  "model",
+  "task_class",
+  "autonomy_level",
+  "tool_calls",
+  "retry_count",
+  "wall_failure_type",
+  "cost",
+  "elapsed_time",
+  "changed_files",
+  "diff_loc",
+  "final_outcome",
+  "review_outcome",
+];
+
+/** Fields commonly unavailable until Langfuse / agent runtime wiring exists */
+export const TELEMETRY_BEST_EFFORT_FIELDS = [
+  "agent_type",
+  "execution_mode",
+  "model",
+  "tool_calls",
+  "cost",
+  "elapsed_time",
+  "review_outcome",
+];
+
+const WALL_FAILURE_PATTERNS = [
+  [/diff[- ]?size/i, "diff-size"],
+  [/issue[- ]?spec/i, "lint"],
+  [/zizmor|codeql|security/i, "security"],
+  [/safe[- ]?output/i, "safe-output"],
+  [/product-ci/i, "test"],
+  [/type(check)?/i, "type"],
+  [/lint/i, "lint"],
+  [/test/i, "test"],
+];
+
+const PLACEHOLDER_DEFAULTS = {
+  agent_type: "n/a",
+  execution_mode: "ci",
+  model: "n/a",
+  task_class: "unknown",
+  autonomy_level: "L1",
+  tool_calls: -1,
+  retry_count: 0,
+  wall_failure_type: "",
+  cost: -1,
+  elapsed_time: -1,
+  changed_files: 0,
+  diff_loc: 0,
+  final_outcome: "in_progress",
+  review_outcome: "pending",
+};
+
+/**
+ * @param {string} input
+ * @returns {string}
+ */
+export function resolveTaskClass(labels) {
+  const taskLabel = labels.find((l) => l.startsWith("task:"));
+  return taskLabel ? taskLabel.replace(/^task:/, "") : PLACEHOLDER_DEFAULTS.task_class;
+}
+
+/**
+ * @param {string} input
+ * @returns {number}
+ */
+export function resolveRetryCount(labels) {
+  const retryLabel = labels.find((l) => l.startsWith("retry:"));
+  if (!retryLabel) return 0;
+  const count = parseInt(retryLabel.split(":")[1], 10);
+  return Number.isFinite(count) ? count : 0;
+}
+
+/**
+ * @param {string | number | undefined | null} prBody
+ * @param {number} prNumber
+ * @returns {string}
+ */
+export function resolveTaskId(prBody, prNumber) {
+  const linked = extractClosingIssueNumbers(String(prBody || ""));
+  if (linked.length === 1) return String(linked[0]);
+  if (linked.length > 1) return String(linked[0]);
+  if (prNumber) return `pr-${prNumber}`;
+  return "unknown";
+}
+
+/**
+ * Map failed CI job / check names to telemetry wall_failure_type.
+ * @param {string} name
+ * @returns {string}
+ */
+export function mapNameToWallFailureType(name) {
+  const text = String(name || "");
+  if (!text) return "";
+  for (const [pattern, wallType] of WALL_FAILURE_PATTERNS) {
+    if (pattern.test(text)) return wallType;
+  }
+  return "";
+}
+
+/**
+ * @param {Record<string, { result?: string }>} jobResults
+ * @returns {string}
+ */
+export function wallFailureTypeFromJobResults(jobResults = {}) {
+  const failed = Object.entries(jobResults)
+    .filter(([, job]) => job?.result === "failure")
+    .map(([name]) => name);
+
+  for (const name of failed) {
+    const mapped = mapNameToWallFailureType(name);
+    if (mapped) return mapped;
+  }
+  return failed.length ? mapNameToWallFailureType(failed[0]) || "test" : "";
+}
+
+/**
+ * @param {Record<string, unknown>} overrides
+ * @returns {{ payload: Record<string, unknown>, placeholders: string[] }}
+ */
+export function buildTelemetryPayload(overrides = {}) {
+  const labels = parseLabelInput(overrides.labels ?? overrides.PR_LABELS ?? "");
+  const prNumber = Number(overrides.pr_number ?? overrides.PR_NUMBER ?? 0) || 0;
+  const prBody = overrides.pr_body ?? overrides.PR_BODY ?? "";
+
+  const payload = {
+    task_id: resolveTaskId(prBody, prNumber),
+    pr_number: prNumber,
+    repo: String(overrides.repo ?? overrides.GITHUB_REPOSITORY ?? "unknown/unknown"),
+    agent_type: String(overrides.agent_type ?? PLACEHOLDER_DEFAULTS.agent_type),
+    execution_mode: String(overrides.execution_mode ?? PLACEHOLDER_DEFAULTS.execution_mode),
+    model: String(overrides.model ?? PLACEHOLDER_DEFAULTS.model),
+    task_class: String(overrides.task_class ?? resolveTaskClass(labels)),
+    autonomy_level: String(
+      overrides.autonomy_level ?? resolveAutonomyLevel(labels) ?? PLACEHOLDER_DEFAULTS.autonomy_level,
+    ),
+    tool_calls: Number(overrides.tool_calls ?? PLACEHOLDER_DEFAULTS.tool_calls),
+    retry_count: Number(
+      overrides.retry_count ?? resolveRetryCount(labels) ?? PLACEHOLDER_DEFAULTS.retry_count,
+    ),
+    wall_failure_type: String(
+      overrides.wall_failure_type ?? overrides.WALL_FAILURE_TYPE ?? PLACEHOLDER_DEFAULTS.wall_failure_type,
+    ),
+    cost: Number(overrides.cost ?? PLACEHOLDER_DEFAULTS.cost),
+    elapsed_time: Number(overrides.elapsed_time ?? PLACEHOLDER_DEFAULTS.elapsed_time),
+    changed_files: Number(overrides.changed_files ?? PLACEHOLDER_DEFAULTS.changed_files),
+    diff_loc: Number(overrides.diff_loc ?? PLACEHOLDER_DEFAULTS.diff_loc),
+    final_outcome: String(overrides.final_outcome ?? PLACEHOLDER_DEFAULTS.final_outcome),
+    review_outcome: String(overrides.review_outcome ?? PLACEHOLDER_DEFAULTS.review_outcome),
+  };
+
+  const placeholders = TELEMETRY_BEST_EFFORT_FIELDS.filter((field) => {
+    if (overrides[field] !== undefined && overrides[field] !== null) return false;
+    const upper = field.toUpperCase();
+    if (overrides[upper] !== undefined && overrides[upper] !== null) return false;
+    return true;
+  });
+
+  return { payload, placeholders };
+}
+
+/**
+ * @param {Record<string, unknown>} options
+ * @returns {Record<string, unknown>}
+ */
+export function buildTelemetryArtifact(options = {}) {
+  const { payload, placeholders } = buildTelemetryPayload(options);
+  return {
+    schema_version: TELEMETRY_SCHEMA_VERSION,
+    emitted_at: new Date().toISOString(),
+    source: String(options.source ?? options.TELEMETRY_SOURCE ?? "unknown"),
+    workflow: options.workflow ?? options.GITHUB_WORKFLOW ?? null,
+    workflow_run_id: Number(options.workflow_run_id ?? options.GITHUB_RUN_ID ?? 0) || null,
+    run_attempt: Number(options.run_attempt ?? options.GITHUB_RUN_ATTEMPT ?? 1) || 1,
+    event_name: options.event_name ?? options.GITHUB_EVENT_NAME ?? null,
+    placeholders,
+    payload,
+  };
+}
+
+/**
+ * @param {{ source: string, prNumber?: number, workflowRunId?: number | string }} params
+ * @returns {string}
+ */
+export function artifactFilename({ source, prNumber = 0, workflowRunId = 0 }) {
+  const safeSource = String(source).replace(/[^a-z0-9-]+/gi, "-");
+  const prPart = prNumber ? `pr${prNumber}` : "no-pr";
+  return `${safeSource}-${prPart}-run${workflowRunId}.json`;
+}
+
+/**
+ * @param {Record<string, unknown>} artifact
+ * @param {{ outDir?: string, filename?: string }} [opts]
+ * @returns {string} absolute path written
+ */
+export function writeTelemetryArtifact(artifact, opts = {}) {
+  const outDir = opts.outDir ?? ARTIFACT_DIR;
+  mkdirSync(outDir, { recursive: true });
+  const filename =
+    opts.filename ??
+    artifactFilename({
+      source: artifact.source,
+      prNumber: artifact.payload?.pr_number,
+      workflowRunId: artifact.workflow_run_id,
+    });
+  const path = join(outDir, filename);
+  writeFileSync(path, `${JSON.stringify(artifact, null, 2)}\n`, "utf8");
+  return path;
+}
+
+/**
+ * @param {string} baseRef e.g. origin/main
+ * @returns {{ changed_files: number, diff_loc: number }}
+ */
+export function diffStatsFromGit(baseRef = "origin/main") {
+  const range = `${baseRef}...HEAD`;
+  try {
+    const numstat = execSync(`git diff --numstat ${range}`, { encoding: "utf8" });
+    const stats = aggregateDiffStats(numstat);
+    return { changed_files: stats.files, diff_loc: stats.loc };
+  } catch {
+    return { changed_files: 0, diff_loc: 0 };
+  }
+}
+
+/**
+ * @param {Record<string, unknown>} payload
+ * @returns {string[]}
+ */
+export function missingRequiredFields(payload) {
+  return TELEMETRY_REQUIRED_FIELDS.filter((key) => payload[key] === undefined || payload[key] === null);
+}

package/scripts/lib/template-root.mjs

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** @param {string} dir */
+export function isTemplateRoot(dir) {
+  return (
+    existsSync(join(dir, "scripts/bootstrap-harness.sh")) &&
+    existsSync(join(dir, "config/stacks.json")) &&
+    existsSync(join(dir, "scripts/setup-wizard.mjs"))
+  );
+}
+
+/**
+ * Resolve the harness template root (source of bootstrap assets).
+ * @param {{ fromModule?: string }} [options]
+ */
+export function resolveTemplateRoot(options = {}) {
+  const envRoot = process.env.SDLCGH_TEMPLATE_ROOT?.trim();
+  if (envRoot) {
+    if (!isTemplateRoot(envRoot)) {
+      throw new Error(`SDLCGH_TEMPLATE_ROOT is not a valid harness template: ${envRoot}`);
+    }
+    return envRoot;
+  }
+
+  if (options.fromModule) {
+    const fromLib = join(dirname(fileURLToPath(options.fromModule)), "../..");
+    if (isTemplateRoot(fromLib)) return fromLib;
+  }
+
+  const fromCwd = process.cwd();
+  if (isTemplateRoot(fromCwd)) return fromCwd;
+
+  throw new Error(
+    "Unable to locate harness template root. Run from the sdlc-gh package, set SDLCGH_TEMPLATE_ROOT, or use `npx @guilz-dev/sdlc-gh init`.",
+  );
+}

package/scripts/merge-harness-package.mjs

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import { resolve } from "node:path";
+import { mergeHarnessPackageJson } from "./lib/merge-harness-package.mjs";
+
+const [templatePathArg, targetPathArg] = process.argv.slice(2);
+if (!templatePathArg || !targetPathArg || process.argv.includes("--help") || process.argv.includes("-h")) {
+  console.log(`Usage: merge-harness-package.mjs <template-package.json> <target-package.json>`);
+  process.exit(templatePathArg && !targetPathArg ? 1 : 0);
+}
+
+const templatePath = resolve(templatePathArg);
+const targetPath = resolve(targetPathArg);
+const result = mergeHarnessPackageJson(templatePath, targetPath);
+console.log(`${result.action} ${targetPath} (${result.scriptCount} harness scripts)`);

package/scripts/route-harness-review.mjs

@@ -0,0 +1,168 @@
+#!/usr/bin/env node
+/**
+ * Route nightly harness review summary into GitHub issues (#4).
+ */
+import { execSync } from "node:child_process";
+import { appendFileSync, existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import {
+  applyRoutingPlanDryRun,
+  bodyHasRoutingMarker,
+  buildRoutingPlan,
+} from "./lib/harness-review-routing.mjs";
+import { REVIEW_OUT_DIR } from "./lib/harness-review.mjs";
+
+function ghJson(cmd) {
+  const out = execSync(cmd, {
+    encoding: "utf8",
+    env: process.env,
+    stdio: ["pipe", "pipe", "pipe"],
+  });
+  return JSON.parse(out);
+}
+
+function parseRepo(repo) {
+  const [owner, name] = String(repo).split("/");
+  if (!owner || !name) throw new Error(`Invalid GITHUB_REPOSITORY: ${repo}`);
+  return { owner, name };
+}
+
+function ghApi(method, path, payload = null) {
+  if (payload) {
+    const file = join(tmpdir(), `gh-api-${Date.now()}.json`);
+    writeFileSync(file, JSON.stringify(payload));
+    try {
+      const verb = method === "GET" ? "" : `-X ${method} `;
+      return ghJson(`gh api ${verb}${path} --input ${file}`);
+    } finally {
+      unlinkSync(file);
+    }
+  }
+  return ghJson(`gh api ${path}`);
+}
+
+function listOpenRoutedIssues(owner, name) {
+  const issues = ghApi("GET", `repos/${owner}/${name}/issues?state=open&per_page=100`);
+  return (Array.isArray(issues) ? issues : []).filter((issue) =>
+    String(issue.body || "").includes("harness-routing-key:"),
+  );
+}
+
+function createIssue(owner, name, action) {
+  return ghApi("POST", `repos/${owner}/${name}/issues`, {
+    title: action.title,
+    body: action.body,
+    labels: action.labels ?? [],
+  });
+}
+
+function updateIssue(owner, name, issueNumber, action) {
+  return ghApi("PATCH", `repos/${owner}/${name}/issues/${issueNumber}`, {
+    title: action.title,
+    body: action.body,
+  });
+}
+
+function main() {
+  const repo = process.env.GITHUB_REPOSITORY;
+  if (!repo) {
+    console.error("::error::GITHUB_REPOSITORY is required");
+    process.exit(1);
+  }
+
+  const dryRun = process.env.HARNESS_ROUTING_DRY_RUN === "1";
+  if (!dryRun && !process.env.GH_TOKEN && !process.env.GITHUB_TOKEN) {
+    console.error("::error::GH_TOKEN or GITHUB_TOKEN is required");
+    process.exit(1);
+  }
+
+  const reviewDir = process.env.HARNESS_REVIEW_OUT_DIR || REVIEW_OUT_DIR;
+  const summaryPath =
+    process.env.HARNESS_REVIEW_SUMMARY_PATH || join(reviewDir, "harness-review-summary.json");
+  if (!existsSync(summaryPath)) {
+    console.error(`::error::Missing summary: ${summaryPath}`);
+    process.exit(1);
+  }
+
+  const summary = JSON.parse(readFileSync(summaryPath, "utf8"));
+  const plan = buildRoutingPlan(summary);
+  const { owner, name } = parseRepo(repo);
+
+  mkdirSync(reviewDir, { recursive: true });
+  const planPath = join(reviewDir, "harness-review-routing-plan.json");
+  writeFileSync(planPath, `${JSON.stringify(plan, null, 2)}\n`, "utf8");
+  console.log(`Wrote ${planPath}`);
+
+  if (!(plan.actions ?? []).length) {
+    console.log("No routing actions (thresholds not met)");
+    console.log(`::notice::routing_actions=0`);
+    return;
+  }
+
+  if (dryRun) {
+    const preview = applyRoutingPlanDryRun(plan, { existingIssues: [] });
+    const previewPath = join(reviewDir, "harness-review-routing-preview.json");
+    writeFileSync(previewPath, `${JSON.stringify(preview, null, 2)}\n`, "utf8");
+    console.log(`Dry run: ${plan.actions.length} action(s) — see ${previewPath}`);
+    console.log(`::notice::routing_actions=${plan.actions.length} dry_run=true`);
+    return;
+  }
+
+  let existingIssues;
+  try {
+    existingIssues = listOpenRoutedIssues(owner, name);
+  } catch (error) {
+    console.error(`::error::Failed to list routed issues: ${error.message}`);
+    process.exit(1);
+  }
+  const results = [];
+
+  for (const action of plan.actions) {
+    const match = existingIssues.find((issue) =>
+      bodyHasRoutingMarker(issue.body, action.dedupe_key),
+    );
+    if (match) {
+      const updated = updateIssue(owner, name, match.number, action);
+      results.push({
+        dedupe_key: action.dedupe_key,
+        operation: "update_issue",
+        issue_number: updated.number,
+        url: updated.html_url,
+      });
+      console.log(`Updated issue #${updated.number} (${action.kind})`);
+    } else {
+      const created = createIssue(owner, name, action);
+      results.push({
+        dedupe_key: action.dedupe_key,
+        operation: "create_issue",
+        issue_number: created.number,
+        url: created.html_url,
+      });
+      console.log(`Created issue #${created.number} (${action.kind})`);
+    }
+  }
+
+  const resultsPath = join(reviewDir, "harness-review-routing-results.json");
+  writeFileSync(
+    resultsPath,
+    `${JSON.stringify({ generated_at: new Date().toISOString(), results }, null, 2)}\n`,
+    "utf8",
+  );
+  console.log(`Wrote ${resultsPath}`);
+  console.log(`::notice::routing_actions=${results.length}`);
+
+  const stepSummaryPath = process.env.GITHUB_STEP_SUMMARY;
+  if (stepSummaryPath && results.length) {
+    const lines = ["", "## Issue routing", ""];
+    for (const result of results) {
+      lines.push(`- ${result.operation}: [#${result.issue_number}](${result.url})`);
+    }
+    appendFileSync(stepSummaryPath, `${lines.join("\n")}\n`, "utf8");
+  }
+}
+
+const isMain =
+  process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isMain) main();