@guilz-dev/sdlc-gh 0.1.0

package/scripts/lib/l1-readiness.mjs

@@ -0,0 +1,258 @@
+import { spawnSync, execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { localChecks, result, resolveStackId } from "./doctor-local.mjs";
+import { detectRepoProfile } from "./setup-wizard.mjs";
+
+function resolveRepoRoot() {
+  try {
+    return execFileSync("git", ["rev-parse", "--show-toplevel"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+  } catch {
+    return process.cwd();
+  }
+}
+
+function ghJson(args, cwd) {
+  const out = spawnSync("gh", args, {
+    cwd,
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  if (out.status !== 0) {
+    throw new Error(out.stderr.trim() || "gh command failed");
+  }
+  return JSON.parse(out.stdout);
+}
+
+function ghReady() {
+  if (spawnSync("gh", ["--version"], { stdio: "ignore" }).status !== 0) {
+    return { ok: false, reason: "gh is not installed" };
+  }
+  if (spawnSync("gh", ["auth", "status"], { stdio: "ignore" }).status !== 0) {
+    return { ok: false, reason: "gh is not authenticated" };
+  }
+  return { ok: true, reason: "" };
+}
+
+function resolveGithubRepo(repoRoot, explicit) {
+  if (explicit) return explicit;
+  return ghJson(["repo", "view", "--json", "nameWithOwner"], repoRoot).nameWithOwner;
+}
+
+function checkLocalL1Assets(repoRoot) {
+  const entries = [];
+  const requiredFiles = [
+    ".github/ISSUE_TEMPLATE/task.yml",
+    ".github/agents/triager.agent.md",
+    ".github/agents/implementer.agent.md",
+    ".github/workflows/copilot-setup-steps.yml",
+    ".github/workflows/harness-ci.yml",
+  ];
+  for (const file of requiredFiles) {
+    if (existsSync(join(repoRoot, file))) {
+      entries.push(result("PASS", file, "exists"));
+    } else {
+      entries.push(result("FAIL", file, "missing", "Run bootstrap/setup wizard and commit harness assets."));
+    }
+  }
+  return entries;
+}
+
+function checkGithubState(repoRoot, githubRepo, stackId) {
+  const entries = [];
+
+  if (!stackId) {
+    entries.push(
+      result(
+        "SKIP",
+        "L1 required checks",
+        "stack could not be resolved",
+        "Ensure exactly one product-ci-*.yml workflow exists or run setup-wizard.",
+      ),
+    );
+    return entries;
+  }
+
+  let labels = [];
+  try {
+    labels = ghJson(["api", `repos/${githubRepo}/labels?per_page=100`], repoRoot);
+  } catch (error) {
+    entries.push(result("SKIP", "GitHub labels", error.message, "Run `./scripts/setup-github.sh` to sync labels."));
+  }
+  if (labels.length > 0) {
+    const requiredLabels = ["task:docs", "task:test-fix", "autonomy:L1"];
+    const remote = new Set(labels.map((l) => l.name));
+    const missing = requiredLabels.filter((name) => !remote.has(name));
+    if (missing.length === 0) {
+      entries.push(result("PASS", "L1 labels", requiredLabels.join(", ")));
+    } else {
+      entries.push(result("FAIL", "L1 labels", `missing: ${missing.join(", ")}`, "Run `./scripts/setup-github.sh`."));
+    }
+  }
+
+  try {
+    const rulesets = ghJson(["api", `repos/${githubRepo}/rulesets`], repoRoot);
+    const main = rulesets.find((r) => r.name === "main-protection");
+    if (!main) {
+      entries.push(result("FAIL", "main-protection ruleset", "missing", "Run `./scripts/setup-github.sh`."));
+    } else {
+      entries.push(result("PASS", "main-protection ruleset", "exists"));
+      const details = ghJson(["api", `repos/${githubRepo}/rulesets/${main.id}`], repoRoot);
+      const statusRule = (details.rules ?? []).find((rule) => rule.type === "required_status_checks");
+      const contexts = new Set((statusRule?.parameters?.required_status_checks ?? []).map((c) => c.context));
+      const expected = ["harness-static", "diff-size", "issue-spec-check", `product-ci-${stackId}`];
+      const missing = expected.filter((name) => !contexts.has(name));
+      if (missing.length === 0) {
+        entries.push(result("PASS", "L1 required checks", expected.join(", ")));
+      } else {
+        entries.push(
+          result(
+            "FAIL",
+            "L1 required checks",
+            `missing: ${missing.join(", ")}`,
+            "Update rulesets via `./scripts/setup-github.sh`.",
+          ),
+        );
+      }
+    }
+  } catch (error) {
+    entries.push(result("SKIP", "GitHub rulesets", error.message, "Check repository Rulesets in GitHub settings."));
+  }
+
+  try {
+    const runs = ghJson(
+      ["api", `repos/${githubRepo}/actions/workflows/copilot-setup-steps.yml/runs?per_page=5`],
+      repoRoot,
+    );
+    const latest = runs.workflow_runs?.[0];
+    if (!latest) {
+      entries.push(
+        result(
+          "WARN",
+          "Copilot setup workflow",
+          "no runs found",
+          "Run Actions > Copilot setup > workflow_dispatch once.",
+        ),
+      );
+    } else if (latest.status === "in_progress" || latest.status === "queued" || latest.conclusion == null) {
+      entries.push(
+        result(
+          "WARN",
+          "Copilot setup workflow",
+          `latest run ${latest.id} is ${latest.status ?? "in progress"}`,
+          "Wait for the Copilot setup workflow to finish, then re-run this check.",
+        ),
+      );
+    } else if (latest.conclusion === "success") {
+      entries.push(result("PASS", "Copilot setup workflow", `latest run ${latest.id} is success`));
+    } else {
+      entries.push(
+        result(
+          "FAIL",
+          "Copilot setup workflow",
+          `latest run ${latest.id} conclusion=${latest.conclusion}`,
+          "Re-run the Copilot setup workflow and fix failures.",
+        ),
+      );
+    }
+  } catch (error) {
+    entries.push(
+      result(
+        "SKIP",
+        "Copilot setup workflow",
+        error.message,
+        "Verify workflow file exists and you have Actions read permission.",
+      ),
+    );
+  }
+
+  return entries;
+}
+
+export function formatReadinessSummary(report) {
+  const lines = [
+    "## L1 readiness",
+    "",
+    `- Profile: **${report.profile}**`,
+    `- Stack: **${report.stackId || "(unresolved)"}**`,
+    `- Result: **${report.hasFail ? "FAIL" : report.hasSkip && report.strict ? "SKIP (strict)" : "PASS"}**`,
+    "",
+    "| Status | Check | Detail |",
+    "| --- | --- | --- |",
+  ];
+  for (const entry of report.entries) {
+    lines.push(`| ${entry.status} | ${entry.label} | ${entry.detail.replace(/\|/g, "\\|")} |`);
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+/**
+ * @param {{ githubRepo?: string, template?: boolean, strict?: boolean, json?: boolean, summary?: boolean, repoRoot?: string }} args
+ */
+export function runReadinessCheck(args) {
+  const repoRoot = args.repoRoot || resolveRepoRoot();
+  const profile = detectRepoProfile(repoRoot, { template: args.template });
+  const template = profile.template || args.template;
+  const local = localChecks(repoRoot, { templateMode: template });
+  const stackId = local.stackId || resolveStackId(repoRoot);
+
+  const entries = [];
+  entries.push(result("PASS", "Repository", repoRoot));
+  entries.push(result("PASS", "Profile", template ? "template" : "product"));
+  entries.push(
+    stackId
+      ? result("PASS", "Stack", stackId)
+      : result("FAIL", "Stack", "could not resolve stack id", "Run setup-wizard or ensure one product-ci-*.yml exists."),
+  );
+
+  entries.push(
+    ...local.entries.map((entry) => ({
+      ...entry,
+      label: `doctor:${entry.label}`,
+    })),
+  );
+  entries.push(...checkLocalL1Assets(repoRoot));
+
+  const gh = ghReady();
+  if (!gh.ok) {
+    entries.push(result("SKIP", "GitHub CLI/Auth", gh.reason, "Install/authenticate `gh` to verify remote readiness."));
+  } else {
+    try {
+      const githubRepo = resolveGithubRepo(repoRoot, args.githubRepo ?? "");
+      entries.push(result("PASS", "GitHub repository", githubRepo));
+      entries.push(...checkGithubState(repoRoot, githubRepo, stackId));
+    } catch (error) {
+      entries.push(
+        result("SKIP", "GitHub repository", error.message, "Run from a cloned GitHub repo or pass --github-repo."),
+      );
+    }
+  }
+
+  entries.push(
+    result(
+      "MANUAL",
+      "Copilot coding agent entitlement",
+      "cannot be verified from repository configuration alone",
+      "Ensure your org/repo has GitHub Copilot coding agent enabled.",
+    ),
+  );
+
+  const hasFail = entries.some((entry) => entry.status === "FAIL");
+  const hasSkip = entries.some((entry) => entry.status === "SKIP");
+  const hasWarn = entries.some((entry) => entry.status === "WARN");
+
+  return {
+    repoRoot,
+    profile: template ? "template" : "product",
+    stackId,
+    strict: Boolean(args.strict),
+    hasFail,
+    hasSkip,
+    hasWarn,
+    entries,
+    exitCode: hasFail || (args.strict && hasSkip) ? 1 : 0,
+  };
+}

package/scripts/lib/merge-harness-package.mjs

@@ -0,0 +1,36 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+
+/**
+ * Merge harness npm scripts into an existing package.json without overwriting
+ * application metadata or dependencies.
+ *
+ * @param {string} templatePath harness template package.json
+ * @param {string} targetPath product repository package.json
+ * @returns {{ action: "created" | "merged", scriptCount: number }}
+ */
+export function mergeHarnessPackageJson(templatePath, targetPath) {
+  const template = JSON.parse(readFileSync(templatePath, "utf8"));
+  const harnessScripts = template.scripts ?? {};
+
+  if (!existsSync(targetPath)) {
+    const created = {
+      private: true,
+      type: "module",
+      description: "Harness tooling scripts (Node.js required for local checks only)",
+      scripts: harnessScripts,
+    };
+    writeFileSync(targetPath, `${JSON.stringify(created, null, 2)}\n`, "utf8");
+    return { action: "created", scriptCount: Object.keys(harnessScripts).length };
+  }
+
+  const existing = JSON.parse(readFileSync(targetPath, "utf8"));
+  const merged = {
+    ...existing,
+    scripts: {
+      ...(existing.scripts ?? {}),
+      ...harnessScripts,
+    },
+  };
+  writeFileSync(targetPath, `${JSON.stringify(merged, null, 2)}\n`, "utf8");
+  return { action: "merged", scriptCount: Object.keys(harnessScripts).length };
+}

package/scripts/lib/npm-package.mjs

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+import { loadStacks } from "./stacks.mjs";
+
+/** Canonical npm `files` list — keep in sync with package.json */
+export const NPM_PACKAGE_FILES = [
+  "AGENTS.md",
+  "config",
+  "docs",
+  "evals",
+  "infra",
+  "prompts",
+  "scripts",
+  ".github",
+  "sample/go",
+  "sample/python",
+  "sample/ruby",
+  "sample/php/composer.json",
+  "sample/php/composer.lock",
+  "sample/php/phpunit.xml",
+  "sample/php/src",
+  "sample/php/tests",
+  "sample/ts/biome.json",
+  "sample/ts/package.json",
+  "sample/ts/package-lock.json",
+  "sample/ts/tsconfig.json",
+  "sample/ts/src",
+  "sample/ts/tests",
+];
+
+const SAMPLE_SKIP_DIRS = new Set([
+  "node_modules",
+  "vendor",
+  ".bundle",
+  "__pycache__",
+  ".pytest_cache",
+  ".vite",
+  ".phpunit.result.cache",
+]);
+
+/** @param {string} relPath repo-relative posix path */
+export function isPathCoveredByNpmFiles(relPath, files = NPM_PACKAGE_FILES) {
+  const normalized = relPath.replace(/\\/g, "/");
+  for (const entry of files) {
+    const pattern = entry.replace(/\\/g, "/");
+    if (normalized === pattern) return true;
+    if (normalized.startsWith(`${pattern}/`)) return true;
+  }
+  return false;
+}
+
+/** @param {string} root repository root */
+function walkSampleFiles(root, sampleRelDir, out) {
+  const abs = join(root, sampleRelDir);
+  if (!existsSync(abs)) return;
+
+  const visit = (dir) => {
+    for (const name of readdirSync(dir)) {
+      if (SAMPLE_SKIP_DIRS.has(name)) continue;
+      const absPath = join(dir, name);
+      const relPath = relative(root, absPath).replace(/\\/g, "/");
+      if (statSync(absPath).isDirectory()) {
+        visit(absPath);
+      } else {
+        out.push(relPath);
+      }
+    }
+  };
+  visit(abs);
+}
+
+/**
+ * @param {string} root repository root
+ * @returns {{ missingOnDisk: string[], notPacked: string[] }}
+ */
+export function validateNpmSampleCoverage(root) {
+  const missingOnDisk = [];
+  for (const entry of NPM_PACKAGE_FILES) {
+    if (!existsSync(join(root, entry))) {
+      missingOnDisk.push(entry);
+    }
+  }
+
+  const sampleFiles = [];
+  for (const stack of loadStacks()) {
+    walkSampleFiles(root, `sample/${stack.sampleDir}`, sampleFiles);
+  }
+
+  const notPacked = sampleFiles.filter((relPath) => !isPathCoveredByNpmFiles(relPath));
+  return { missingOnDisk, notPacked };
+}
+
+/** @param {string} root repository root */
+export function validatePackageJsonFiles(root) {
+  const pkgPath = join(root, "package.json");
+  if (!existsSync(pkgPath)) {
+    return { ok: false, reason: "package.json not found" };
+  }
+
+  const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+  const actual = [...(pkg.files ?? [])].sort();
+  const expected = [...NPM_PACKAGE_FILES].sort();
+  if (JSON.stringify(actual) !== JSON.stringify(expected)) {
+    return {
+      ok: false,
+      reason: "package.json files is out of sync with scripts/lib/npm-package.mjs (NPM_PACKAGE_FILES)",
+    };
+  }
+  return { ok: true, reason: "" };
+}
+
+/** @param {string} stackId */
+export function postInstallHint(stackId) {
+  switch (stackId) {
+    case "ts":
+      return "Run `npm install` in the repository root before opening a PR.";
+    case "python":
+      return "Run `pip install -r requirements-dev.txt` (or your preferred venv workflow) before opening a PR.";
+    case "go":
+      return "Run `go test ./...` once to fetch modules before opening a PR.";
+    case "ruby":
+      return "Run `bundle install` before opening a PR.";
+    case "php":
+      return "Run `composer install` before opening a PR.";
+    default:
+      return "Install stack dependencies before opening a PR.";
+  }
+}

package/scripts/lib/setup-wizard.mjs

@@ -0,0 +1,224 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { spawnSync } from "node:child_process";
+import { detectStackCandidates, getStack, stackIds } from "./stacks.mjs";
+
+export const CODEOWNERS_PLACEHOLDER = "@your-org/harness-engineers";
+
+/** @param {string} owner */
+export function isValidCodeownersOwner(owner) {
+  const trimmed = owner.trim();
+  if (/^@[^/\s]+\/[^/\s]+$/.test(trimmed)) return true;
+  if (/^@[\w.-]+$/.test(trimmed)) return true;
+  return false;
+}
+
+/** @param {string} repoRoot */
+export function detectHarnessPresent(repoRoot) {
+  return (
+    existsSync(join(repoRoot, ".github/workflows/harness-ci.yml")) &&
+    existsSync(join(repoRoot, "scripts/doctor.mjs"))
+  );
+}
+
+/** @param {string} repoRoot */
+export function countProductCiWorkflows(repoRoot) {
+  const workflowsDir = join(repoRoot, ".github/workflows");
+  if (!existsSync(workflowsDir)) return 0;
+  return readdirSync(workflowsDir).filter((name) => /^product-ci-.*\.yml$/.test(name)).length;
+}
+
+/**
+ * @param {string} repoRoot
+ * @param {{ template?: boolean }} [options]
+ */
+export function detectRepoProfile(repoRoot, options = {}) {
+  const harnessPresent = detectHarnessPresent(repoRoot);
+  const productCiCount = countProductCiWorkflows(repoRoot);
+  const hasSampleStacks = existsSync(join(repoRoot, "sample/ts"));
+  const template =
+    options.template === true ||
+    (harnessPresent && productCiCount > 1 && hasSampleStacks);
+
+  let kind = "unknown";
+  if (!harnessPresent) kind = "needs-bootstrap";
+  else if (template) kind = "template";
+  else kind = "product";
+
+  return { kind, harnessPresent, productCiCount, hasSampleStacks, template };
+}
+
+/** @param {string} repoRoot */
+export function readHarnessStack(repoRoot) {
+  const stackFile = join(repoRoot, ".harness-stack");
+  if (!existsSync(stackFile)) return "";
+  return readFileSync(stackFile, "utf8").trim();
+}
+
+/** @param {string} repoRoot @param {string} stackId */
+export function writeHarnessStack(repoRoot, stackId) {
+  getStack(stackId);
+  writeFileSync(join(repoRoot, ".harness-stack"), `${stackId}\n`, "utf8");
+}
+
+/** @param {string} repoRoot */
+export function codeownersHasPlaceholder(repoRoot) {
+  const codeownersFile = join(repoRoot, ".github/CODEOWNERS");
+  if (!existsSync(codeownersFile)) return false;
+  return readFileSync(codeownersFile, "utf8").includes(CODEOWNERS_PLACEHOLDER);
+}
+
+/** @param {string} repoRoot @param {string} owner */
+export function applyCodeownersOwner(repoRoot, owner) {
+  if (!isValidCodeownersOwner(owner)) {
+    throw new Error(`Invalid CODEOWNERS owner: ${owner}`);
+  }
+  const codeownersFile = join(repoRoot, ".github/CODEOWNERS");
+  if (!existsSync(codeownersFile)) {
+    throw new Error(`Missing ${codeownersFile}`);
+  }
+  const current = readFileSync(codeownersFile, "utf8");
+  writeFileSync(codeownersFile, current.replaceAll(CODEOWNERS_PLACEHOLDER, owner.trim()), "utf8");
+}
+
+/** @param {string} repoRoot */
+export function suggestStack(repoRoot) {
+  const detected = detectStackCandidates(repoRoot);
+  if (detected.suggested) return detected.suggested;
+  if (detectRepoProfile(repoRoot).template) return "ts";
+  return "";
+}
+
+/** @param {string} repoRoot */
+export function resolveGithubRepo(repoRoot) {
+  const result = spawnSync("gh", ["repo", "view", "--json", "nameWithOwner"], {
+    cwd: repoRoot,
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  if (result.status !== 0) return "";
+  try {
+    return JSON.parse(result.stdout).nameWithOwner ?? "";
+  } catch {
+    return "";
+  }
+}
+
+/** @param {{ repoRoot: string, stackId: string, owner: string, githubRepo: string, template: boolean, withEvalRuleset: boolean, yes: boolean, skipGithub: boolean, dryRun: boolean, writeHarnessStack?: boolean, patchCodeowners?: boolean }} options */
+export function buildWizardPlan(options) {
+  const {
+    repoRoot,
+    stackId,
+    owner,
+    githubRepo,
+    template,
+    withEvalRuleset,
+    skipGithub,
+    dryRun,
+    writeHarnessStack: shouldWriteStack = true,
+    patchCodeowners = true,
+  } = options;
+
+  const steps = [];
+  if (shouldWriteStack) {
+    steps.push({ id: "harness-stack", action: "write", detail: `.harness-stack -> ${stackId}` });
+  }
+  if (patchCodeowners) {
+    steps.push({
+      id: "codeowners",
+      action: "patch",
+      detail: `replace ${CODEOWNERS_PLACEHOLDER} -> ${owner}`,
+    });
+  } else if (template) {
+    steps.push({
+      id: "codeowners",
+      action: "skip",
+      detail: `keep template placeholder (${CODEOWNERS_PLACEHOLDER})`,
+    });
+  } else if (owner && owner !== "(unchanged)") {
+    steps.push({
+      id: "codeowners",
+      action: "skip",
+      detail: "CODEOWNERS placeholder already replaced; no change",
+    });
+  }
+  if (!skipGithub) {
+    steps.push({
+      id: "setup-github",
+      action: "run",
+      detail: `sync labels + main-protection${withEvalRuleset ? " + eval ruleset" : ""} for ${githubRepo || "(auto)"}`,
+    });
+  }
+  steps.push({
+    id: "doctor",
+    action: "run",
+    detail: `doctor --strict${template ? " --template" : ""}${dryRun ? " (skipped in dry-run)" : ""}`,
+  });
+  return { repoRoot, stackId, owner, githubRepo, template, withEvalRuleset, skipGithub, dryRun, steps };
+}
+
+/** @param {string} repoRoot */
+export function ghReady(repoRoot) {
+  const version = spawnSync("gh", ["--version"], { stdio: "ignore" });
+  if (version.status !== 0) return { ok: false, reason: "gh is not installed" };
+  const auth = spawnSync("gh", ["auth", "status"], { stdio: "ignore" });
+  if (auth.status !== 0) return { ok: false, reason: "gh is not authenticated" };
+  return { ok: true, reason: "" };
+}
+
+/** @param {string} repoRoot @param {string[]} args */
+function runScript(repoRoot, scriptName, args) {
+  const scriptPath = join(repoRoot, "scripts", scriptName);
+  return spawnSync(scriptPath, args, {
+    cwd: repoRoot,
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+    shell: false,
+  });
+}
+
+/** @param {{ repoRoot: string, stackId: string, mode: string, owner: string, yes: boolean, templateRoot?: string }} options */
+export function runBootstrap(options) {
+  const { repoRoot, stackId, mode, owner, yes, templateRoot } = options;
+  const root = templateRoot || repoRoot;
+  const scriptPath = join(root, "scripts/bootstrap-harness.sh");
+  const args = [
+    "--repo",
+    repoRoot,
+    "--stack",
+    stackId,
+    "--mode",
+    mode,
+    "--codeowners-team",
+    owner,
+  ];
+  if (yes) args.push("--yes");
+  return spawnSync("bash", [scriptPath, ...args], {
+    cwd: root,
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+}
+
+/** @param {{ repoRoot: string, githubRepo: string, withEvalRuleset: boolean, yes: boolean, dryRun: boolean }} options */
+export function runSetupGithub(options) {
+  const { repoRoot, githubRepo, withEvalRuleset, yes, dryRun } = options;
+  const args = [];
+  if (githubRepo) args.push("--github-repo", githubRepo);
+  if (withEvalRuleset) args.push("--with-eval-ruleset");
+  if (yes) args.push("--yes");
+  if (dryRun) args.push("--dry-run");
+  return runScript(repoRoot, "setup-github.mjs", args);
+}
+
+/** @param {{ repoRoot: string, template: boolean, strict: boolean }} options */
+export function runDoctor(options) {
+  const { repoRoot, template, strict } = options;
+  const args = [];
+  if (strict) args.push("--strict");
+  if (template) args.push("--template");
+  return runScript(repoRoot, "doctor.mjs", args);
+}
+
+export { stackIds, detectStackCandidates, getStack };