@loopover/miner 0.1.0

package/lib/self-review-context.js

@@ -0,0 +1,339 @@
+import { buildCollisionReport, MAX_FOCUS_MANIFEST_BYTES, parseFocusManifestContent } from "@loopover/engine";
+
+// Real SelfReviewContext fetcher (#5145, Wave 3.5). Builds the context object the miner's self-review pass
+// (packages/gittensory-engine/src/miner/self-review-adapter.ts) needs, at the SAME fidelity the live gate's
+// own DB-backed construction produces (src/db/repositories.ts's toRepositoryRecord/toIssueRecord/
+// toPullRequestRecord) -- just built fresh from live GitHub data instead of a DB round-trip, since the miner
+// has no database. Two of SelfReviewContext's eight fields are DELIBERATELY left undefined, not stubbed:
+//
+//   - `bounties`: bounty data is not GitHub-native in this codebase -- it comes from an external "Gitt"
+//     system that PUSHES data into the live gate's own internal ingest route (src/api/routes.ts). There is
+//     no public endpoint the miner could legitimately pull from instead.
+//   - `issueQuality`: built by buildIssueQualityReport, which lives only in root src/signals/engine.ts and
+//     has never been extracted into @loopover/engine (the same "not yet extracted" situation
+//     src/signals/slop.ts documented before #5133 extracted slop scoring specifically).
+//
+// Both are already optional on SelfReviewContext, and buildPredictedGateVerdict already degrades gracefully
+// without them -- omitting them here is the same tradeoff the live gate itself makes for a repo it hasn't
+// computed bounty/quality data for yet, not a corner cut specific to the miner.
+
+const GITHUB_API_VERSION = "2022-11-28";
+const DEFAULT_API_BASE_URL = "https://api.github.com";
+const DEFAULT_RAW_CONTENT_BASE_URL = "https://raw.githubusercontent.com";
+const DEFAULT_GITTENSOR_API_BASE = "https://api.gittensor.io";
+const DEFAULT_PER_PAGE = 100;
+const DEFAULT_MAX_PAGES = 10;
+
+// Mirrors src/signals/focus-manifest-loader.ts's MANIFEST_FILE_CANDIDATES exactly -- first candidate that
+// resolves wins, same as the live gate's own lookup order.
+const MANIFEST_FILE_CANDIDATES = [".gittensory.yml", ".github/gittensory.yml", ".gittensory.json", ".github/gittensory.json"];
+
+function parseRepoFullName(repoFullName) {
+  if (typeof repoFullName !== "string") return null;
+  const [owner, repo, extra] = repoFullName.split("/");
+  if (!owner || !repo || extra !== undefined) return null;
+  return { owner, repo };
+}
+
+function githubHeaders(githubToken) {
+  const headers = {
+    accept: "application/vnd.github+json",
+    "user-agent": "loopover-miner",
+    "x-github-api-version": GITHUB_API_VERSION,
+  };
+  const token = typeof githubToken === "string" ? githubToken.trim() : "";
+  if (token) headers.authorization = `Bearer ${token}`;
+  return headers;
+}
+
+function normalizeOptions(options = {}) {
+  return {
+    githubToken: options.githubToken ?? process.env.GITHUB_TOKEN ?? "",
+    apiBaseUrl: typeof options.apiBaseUrl === "string" && options.apiBaseUrl.trim() ? options.apiBaseUrl.trim() : DEFAULT_API_BASE_URL,
+    rawContentBaseUrl:
+      typeof options.rawContentBaseUrl === "string" && options.rawContentBaseUrl.trim() ? options.rawContentBaseUrl.trim() : DEFAULT_RAW_CONTENT_BASE_URL,
+    gittensorApiBase:
+      typeof options.gittensorApiBase === "string" && options.gittensorApiBase.trim() ? options.gittensorApiBase.trim() : DEFAULT_GITTENSOR_API_BASE,
+    fetchImpl: options.fetchImpl ?? fetch,
+    perPage: Number.isInteger(options.perPage) && options.perPage > 0 ? options.perPage : DEFAULT_PER_PAGE,
+    maxPages: Number.isInteger(options.maxPages) && options.maxPages > 0 ? options.maxPages : DEFAULT_MAX_PAGES,
+    contributorLogin: typeof options.contributorLogin === "string" ? options.contributorLogin.trim() : "",
+    linkedIssues: Array.isArray(options.linkedIssues) ? options.linkedIssues.filter((n) => Number.isInteger(n)) : [],
+  };
+}
+
+async function githubGetJson(url, resolved) {
+  const response = await resolved.fetchImpl(url, { method: "GET", headers: githubHeaders(resolved.githubToken) });
+  const payload = await response.json().catch(() => null);
+  return { response, payload };
+}
+
+async function fetchPaginated(pathWithQuery, resolved) {
+  const results = [];
+  for (let page = 1; page <= resolved.maxPages; page += 1) {
+    const separator = pathWithQuery.includes("?") ? "&" : "?";
+    const url = `${resolved.apiBaseUrl}${pathWithQuery}${separator}per_page=${resolved.perPage}&page=${page}`;
+    const { response, payload } = await githubGetJson(url, resolved);
+    if (!response.ok || !Array.isArray(payload)) break;
+    results.push(...payload);
+    if (payload.length < resolved.perPage) break;
+  }
+  return results;
+}
+
+// Mirrors src/db/repositories.ts's toRepositoryRecord + upsertRepositoryFromGitHub's field mapping. The
+// miner has no App installation/DB, so installationId/isInstalled/isRegistered/registryConfig are honest
+// "unregistered" defaults, not values pulled from GitHub -- GitHub's own repo payload carries none of them.
+async function fetchRepositoryRecord(target, resolved) {
+  const url = `${resolved.apiBaseUrl}/repos/${encodeURIComponent(target.owner)}/${encodeURIComponent(target.repo)}`;
+  const { response, payload } = await githubGetJson(url, resolved);
+  if (!response.ok || !payload || typeof payload !== "object") return null;
+  return {
+    fullName: `${target.owner}/${target.repo}`,
+    owner: payload.owner?.login ?? target.owner,
+    name: payload.name ?? target.repo,
+    installationId: undefined,
+    isInstalled: false,
+    isRegistered: false,
+    isPrivate: payload.private ?? false,
+    htmlUrl: payload.html_url ?? null,
+    defaultBranch: payload.default_branch ?? null,
+    registryConfig: null,
+  };
+}
+
+// Mirrors src/db/repositories.ts's extractLinkedPrNumbers exactly.
+const LINKED_PR_PATTERN = /\b(?:PR|pull request)\s+#(\d+)\b/gi;
+function extractLinkedPrNumbers(body) {
+  const numbers = [];
+  for (const match of body.matchAll(LINKED_PR_PATTERN)) {
+    const number = Number(match[1]);
+    if (Number.isInteger(number) && number > 0) numbers.push(number);
+  }
+  return numbers;
+}
+
+// Mirrors src/db/repositories.ts's extractLinkedIssueNumbers: GitHub's own closing-keyword vocabulary, only
+// counting a fully-qualified owner/repo#N reference when it targets the SAME repo being fetched.
+const LINKED_ISSUE_PATTERN = /\b(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?)\s+(?:([\w.-]+\/[\w.-]+)#|#)(\d+)\b/gi;
+function extractLinkedIssueNumbers(body, repoFullName) {
+  // Strip backtick code spans first so a closing-keyword pattern quoted as example code doesn't count.
+  const withoutCodeSpans = body.replace(/`[^`]*`/g, "");
+  const numbers = [];
+  const normalizedRepo = repoFullName.toLowerCase();
+  for (const match of withoutCodeSpans.matchAll(LINKED_ISSUE_PATTERN)) {
+    const qualifiedRepo = match[1];
+    if (qualifiedRepo !== undefined && qualifiedRepo.toLowerCase() !== normalizedRepo) continue;
+    const number = Number(match[2]);
+    if (Number.isInteger(number) && number > 0) numbers.push(number);
+  }
+  return numbers;
+}
+
+function labelNames(labels) {
+  if (!Array.isArray(labels)) return [];
+  return labels.flatMap((label) => (label && typeof label === "object" && typeof label.name === "string" ? [label.name] : []));
+}
+
+// Mirrors src/db/repositories.ts's toIssueRecord, populated straight from the live payload (createdAt/
+// updatedAt/closedAt come from the DB-row read path there only as a caching artifact, not a semantic
+// transform -- the live REST fields are the real source).
+function toIssueRecord(repoFullName, issue) {
+  const body = issue.body ?? "";
+  return {
+    repoFullName,
+    number: issue.number,
+    title: issue.title,
+    state: issue.state,
+    authorLogin: issue.user?.login ?? null,
+    authorAssociation: issue.author_association ?? null,
+    htmlUrl: issue.html_url ?? null,
+    body,
+    createdAt: issue.created_at ?? null,
+    updatedAt: issue.updated_at ?? null,
+    closedAt: issue.closed_at ?? null,
+    labels: labelNames(issue.labels),
+    linkedPrs: extractLinkedPrNumbers(body),
+  };
+}
+
+async function fetchOpenIssueRecords(target, resolved) {
+  const payloads = await fetchPaginated(
+    `/repos/${encodeURIComponent(target.owner)}/${encodeURIComponent(target.repo)}/issues?state=open&sort=created&direction=asc`,
+    resolved,
+  );
+  // GitHub's Issues endpoint also returns pull requests -- filter them out, same as the live gate's own fetch.
+  return payloads.filter((issue) => issue && typeof issue === "object" && !issue.pull_request).map((issue) => toIssueRecord(`${target.owner}/${target.repo}`, issue));
+}
+
+function mergeableBooleanState(mergeable) {
+  if (mergeable === true) return "clean";
+  if (mergeable === false) return "dirty";
+  return null;
+}
+
+// Mirrors src/db/repositories.ts's toPullRequestRecord. Only the fields SelfReviewContext/buildCollisionReport
+// actually consume are populated with real precision; merge/RC3 gate-plumbing fields the live gate's fuller
+// PullRequestRecord carries (mergeAttemptCount, approvedHeadSha, ...) don't exist on the engine package's
+// leaner mirror type and aren't meaningful for a miner attempt anyway.
+function toPullRequestRecord(repoFullName, pr) {
+  const body = pr.body ?? "";
+  return {
+    repoFullName,
+    number: pr.number,
+    title: pr.title,
+    state: pr.state,
+    authorLogin: pr.user?.login ?? null,
+    authorAssociation: pr.author_association ?? null,
+    headSha: pr.head?.sha ?? null,
+    headRef: pr.head?.ref ?? null,
+    baseRef: pr.base?.ref ?? null,
+    htmlUrl: pr.html_url ?? null,
+    mergedAt: pr.merged_at ?? null,
+    isDraft: pr.draft ?? null,
+    mergeableState: pr.mergeable_state ?? mergeableBooleanState(pr.mergeable),
+    reviewDecision: null,
+    body,
+    createdAt: pr.created_at ?? null,
+    updatedAt: pr.updated_at ?? null,
+    closedAt: pr.closed_at ?? null,
+    labels: labelNames(pr.labels),
+    linkedIssues: extractLinkedIssueNumbers(body, repoFullName),
+  };
+}
+
+async function fetchOpenPullRequestRecords(target, resolved) {
+  const payloads = await fetchPaginated(
+    `/repos/${encodeURIComponent(target.owner)}/${encodeURIComponent(target.repo)}/pulls?state=open&sort=created&direction=asc`,
+    resolved,
+  );
+  return payloads.map((pr) => toPullRequestRecord(`${target.owner}/${target.repo}`, pr));
+}
+
+// Mirrors src/signals/focus-manifest-loader.ts's raw-content lookup order and bounded body read:
+// first candidate path that resolves wins, but hostile manifests never exceed the parser byte cap in memory.
+async function readBoundedManifestResponseText(response) {
+  const contentLength = response.headers?.get?.("content-length") ?? null;
+  if (contentLength !== null) {
+    const parsedLength = Number.parseInt(contentLength, 10);
+    if (Number.isFinite(parsedLength) && parsedLength > MAX_FOCUS_MANIFEST_BYTES) return null;
+  }
+  if (!response.body?.getReader) {
+    const text = await response.text();
+    if (typeof text !== "string") return null;
+    return new TextEncoder().encode(text).byteLength > MAX_FOCUS_MANIFEST_BYTES ? null : text;
+  }
+
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  let totalBytes = 0;
+  let text = "";
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      totalBytes += value.byteLength;
+      if (totalBytes > MAX_FOCUS_MANIFEST_BYTES) {
+        await reader.cancel();
+        return null;
+      }
+      text += decoder.decode(value, { stream: true });
+    }
+    text += decoder.decode();
+    return text;
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+async function fetchManifestContent(target, resolved) {
+  for (const path of MANIFEST_FILE_CANDIDATES) {
+    const url = `${resolved.rawContentBaseUrl}/${encodeURIComponent(target.owner)}/${encodeURIComponent(target.repo)}/HEAD/${path}`;
+    try {
+      const response = await resolved.fetchImpl(url, { method: "GET", headers: { accept: "application/json", "user-agent": "loopover-miner" } });
+      if (response.ok) {
+        const text = await readBoundedManifestResponseText(response);
+        if (typeof text === "string") return text;
+      }
+    } catch {
+      // Try the next candidate path.
+    }
+  }
+  return null;
+}
+
+// Mirrors src/gittensor/api.ts's fetchGittensorContributorSnapshot/fetchOfficialGittensorMiner: a public,
+// unauthenticated GET against the Gittensor API (not GitHub) -- confirmed only when a real entry with a
+// matching GitHub login is found; any transport/parse failure fails closed to "not confirmed", never throws.
+async function fetchConfirmedContributor(login, resolved) {
+  if (!login) return false;
+  try {
+    const response = await resolved.fetchImpl(`${resolved.gittensorApiBase}/miners`, { method: "GET", headers: { accept: "application/json" } });
+    if (!response.ok) return false;
+    const payload = await response.json().catch(() => null);
+    if (!Array.isArray(payload)) return false;
+    const normalizedLogin = login.toLowerCase();
+    return payload.some((miner) => typeof miner?.githubUsername === "string" && miner.githubUsername.toLowerCase() === normalizedLogin);
+  } catch {
+    return false;
+  }
+}
+
+// Per self-review-adapter.ts's own doc comment: the caller computes inDuplicateCluster "the same way the
+// live gate's collision report would" -- adapted from src/signals/engine.ts's real
+// isPullRequestInDuplicateCluster (root src/, not extracted to the engine package), which requires >= 2
+// PULL REQUEST items in a high-risk cluster, not just any high-risk cluster containing the target. That
+// threshold matters: buildCollisionReport's own pairwise "shared linked issue" rule already marks an
+// issue+its-one-legitimately-closing-PR pair as a HIGH-risk cluster (confirmed empirically) -- without the
+// >= 2 threshold, inDuplicateCluster would fire on the completely normal case of "one PR already closes
+// this issue," not genuine overlapping/duplicate work. Checks the target ISSUE's presence instead of a
+// not-yet-existing PR number, since the miner's own submission doesn't exist as a real PullRequestRecord yet.
+function computeInDuplicateCluster(repoFullName, issues, pullRequests, targetIssueNumbers) {
+  if (targetIssueNumbers.length === 0) return false;
+  const report = buildCollisionReport(repoFullName, issues, pullRequests);
+  return report.clusters.some(
+    (cluster) =>
+      cluster.risk === "high" &&
+      cluster.items.filter((item) => item.type === "pull_request").length >= 2 &&
+      cluster.items.some((item) => item.type === "issue" && targetIssueNumbers.includes(item.number)),
+  );
+}
+
+/**
+ * Build a real SelfReviewContext from live GitHub data, at the same fidelity the live gate's own DB-backed
+ * construction produces. See this file's header for the two fields (bounties, issueQuality) deliberately
+ * left undefined and why.
+ *
+ * @param {string} repoFullName
+ * @param {{
+ *   githubToken?: string, contributorLogin?: string, linkedIssues?: number[],
+ *   apiBaseUrl?: string, rawContentBaseUrl?: string, gittensorApiBase?: string,
+ *   fetchImpl?: typeof fetch, perPage?: number, maxPages?: number,
+ * }} [options]
+ * @returns {Promise<import("./self-review-context.js").SelfReviewContextResult>}
+ */
+export async function fetchSelfReviewContext(repoFullName, options = {}) {
+  const target = parseRepoFullName(repoFullName);
+  if (!target) throw new Error("invalid_repo_full_name");
+  const resolved = normalizeOptions(options);
+
+  const [repo, issues, pullRequests, manifestContent, confirmedContributor] = await Promise.all([
+    fetchRepositoryRecord(target, resolved),
+    fetchOpenIssueRecords(target, resolved),
+    fetchOpenPullRequestRecords(target, resolved),
+    fetchManifestContent(target, resolved),
+    fetchConfirmedContributor(resolved.contributorLogin, resolved),
+  ]);
+
+  const manifest = parseFocusManifestContent(manifestContent, "repo_file");
+  const inDuplicateCluster = computeInDuplicateCluster(`${target.owner}/${target.repo}`, issues, pullRequests, resolved.linkedIssues);
+
+  return {
+    manifest,
+    repo,
+    issues,
+    pullRequests,
+    confirmedContributor,
+    inDuplicateCluster,
+  };
+}

package/lib/slop-assessment.d.ts

@@ -0,0 +1,3 @@
+import type { SlopAssessment, SlopAssessmentInput } from "@loopover/engine";
+
+export function runSlopAssessment(input: SlopAssessmentInput): SlopAssessment;

package/lib/slop-assessment.js

@@ -0,0 +1,20 @@
+import { buildSlopAssessment } from "@loopover/engine";
+
+// Production runSlopAssessment binding (#5133, Wave 3.5 follow-up to #2334). `attempt-runner.js`'s
+// `deps.runSlopAssessment` (via #2333's iterate-loop -> self-review-adapter's `SelfReviewAdapterDeps`) had
+// no production implementation anywhere in this package -- only the test double in
+// `test/unit/miner-attempt-runner.test.ts` existed. `packages/gittensory-engine/src/miner/self-review-adapter.ts`'s
+// own header comment already anticipated this exact binding: `SelfReviewSlopInput`/`SelfReviewSlopAssessment`
+// are a deliberate, hand-kept STRUCTURAL MIRROR of `buildSlopAssessment`'s own `SlopAssessmentInput`/
+// `SlopAssessment` (down to reusing the SAME canonical `AdvisoryFinding` type for `findings`), specifically so
+// a real binding could be a direct pass-through with no mapping logic once the deterministic scorer itself
+// became portable -- which #5133 did (`src/signals/slop.ts`'s PR-side scorer is now extracted to
+// `packages/gittensory-engine/src/signals/slop.ts`, byte-parity-verified against the live gate's own copy).
+
+/**
+ * @param {import("@loopover/engine").SlopAssessmentInput} input
+ * @returns {import("@loopover/engine").SlopAssessment}
+ */
+export function runSlopAssessment(input) {
+  return buildSlopAssessment(input);
+}

package/lib/stack-detection.d.ts

@@ -0,0 +1,41 @@
+/** Stack auto-detection (#4785). `detectRepoStack` inspects an already-cloned repo's manifest / lockfile / config
+ * files and returns a structured stack description, or an explicit fail-closed result when the stack can't be
+ * confidently identified (no guessing). */
+
+/** Which manifest (and lockfile, when present) drove the detection. */
+export type StackEvidence = {
+  manifest: string;
+  lockfile: string | null;
+};
+
+/** A confidently-detected stack. Command fields are `null` when the command can't be inferred without guessing. */
+export type DetectedRepoStack = {
+  detected: true;
+  language: string;
+  packageManager: string | null;
+  buildCommand: string | null;
+  testCommand: string | null;
+  lintCommand: string | null;
+  formatCommand: string | null;
+  evidence: StackEvidence;
+};
+
+/** A repo whose stack could not be confidently identified. */
+export type UndetectedRepoStack = {
+  detected: false;
+  reason: string;
+};
+
+export type RepoStackResult = DetectedRepoStack | UndetectedRepoStack;
+
+export type DetectRepoStackOptions = {
+  existsSync?: (path: string) => boolean;
+  readFileSync?: (path: string, encoding: "utf8") => string;
+};
+
+/** Manifests, in the precedence order detection tries them (first match wins). */
+export const RECOGNIZED_MANIFESTS: readonly string[];
+
+export function detectRepoStack(repoPath: string, options?: DetectRepoStackOptions): RepoStackResult;
+
+export function renderStackSummary(stack: RepoStackResult): string;

package/lib/stack-detection.js

@@ -0,0 +1,248 @@
+/** Stack auto-detection (#4785): inspect an already-cloned target repo's manifest / lockfile / config files and
+ * infer a structured description of its stack — language, package manager, and the build / test / lint / format
+ * commands — before any code-generation step runs. Like `miner-goal-spec.js` this reads the ALREADY-CLONED repo on
+ * disk (attempt-worktree.js's prepareAttemptWorktree runs first), so the injected `existsSync` / `readFileSync`
+ * always receive the FULL joined path, mirroring node:fs. It is pure and NEVER throws: an unreadable/unparseable
+ * file degrades to "no evidence" rather than crashing, and — per the acceptance criteria — a repo whose stack
+ * can't be confidently identified returns an explicit `{ detected: false, reason }` instead of guessing. */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+/** Manifests, in the precedence order detection tries them; the first matching primary manifest wins. A caller with
+ * a known polyglot repo can inspect `evidence.manifest` to see which one was chosen. */
+export const RECOGNIZED_MANIFESTS = Object.freeze([
+  "package.json",
+  "pyproject.toml",
+  "setup.py",
+  "setup.cfg",
+  "requirements.txt",
+  "Pipfile",
+  "Cargo.toml",
+  "go.mod",
+  "pom.xml",
+  "build.gradle",
+  "build.gradle.kts",
+]);
+
+const NO_MANIFEST_REASON =
+  "No recognized dependency manifest (package.json, pyproject.toml, Cargo.toml, go.mod, pom.xml, or build.gradle) was found at the repository root.";
+
+const NODE_PACKAGE_MANAGERS = Object.freeze(["npm", "yarn", "pnpm", "bun"]);
+const NODE_LOCKFILES = Object.freeze([
+  ["pnpm-lock.yaml", "pnpm"],
+  ["yarn.lock", "yarn"],
+  ["bun.lockb", "bun"],
+  ["package-lock.json", "npm"],
+]);
+
+/** Build a never-throwing accessor over the cloned repo. `exists` and `read` both swallow fs errors so the detector
+ * treats an EACCES/ENOENT/binary file as simply "absent" instead of crashing the attempt. */
+function makeAccess(repoPath, options) {
+  const existsImpl = options.existsSync ?? existsSync;
+  const readImpl = options.readFileSync ?? readFileSync;
+  const exists = (relativePath) => {
+    try {
+      return existsImpl(join(repoPath, relativePath)) === true;
+    } catch {
+      return false;
+    }
+  };
+  const read = (relativePath) => {
+    try {
+      if (!exists(relativePath)) return null;
+      const content = readImpl(join(repoPath, relativePath), "utf8");
+      return typeof content === "string" ? content : null;
+    } catch {
+      return null;
+    }
+  };
+  return { exists, read };
+}
+
+function parseJson(text) {
+  if (typeof text !== "string") return null;
+  try {
+    const parsed = JSON.parse(text);
+    return parsed && typeof parsed === "object" ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Pick a package.json script by exact name first, then by pattern, considering only string-valued scripts. */
+function pickScript(scripts, exactName, pattern) {
+  const names = Object.keys(scripts).filter((name) => typeof scripts[name] === "string");
+  if (names.includes(exactName)) return exactName;
+  return names.find((name) => pattern.test(name)) ?? null;
+}
+
+function nodeLockfile(exists) {
+  const match = NODE_LOCKFILES.find(([file]) => exists(file));
+  return match ? match[0] : null;
+}
+
+function nodePackageManager(pkg, lockfile) {
+  const corepack =
+    typeof pkg?.packageManager === "string" ? pkg.packageManager.split("@")[0].trim().toLowerCase() : "";
+  if (NODE_PACKAGE_MANAGERS.includes(corepack)) return corepack;
+  const byLock = NODE_LOCKFILES.find(([file]) => file === lockfile);
+  // A package.json with no lockfile is still a Node project; npm is its default runner (a default, not a guess).
+  return byLock ? byLock[1] : "npm";
+}
+
+function hasTypescriptDependency(pkg) {
+  const deps = { ...(pkg?.dependencies ?? {}), ...(pkg?.devDependencies ?? {}) };
+  return typeof deps.typescript === "string";
+}
+
+function detectNode({ exists, read }) {
+  if (!exists("package.json")) return null;
+  const pkg = parseJson(read("package.json"));
+  const scripts =
+    pkg && typeof pkg.scripts === "object" && pkg.scripts && !Array.isArray(pkg.scripts) ? pkg.scripts : {};
+  const language = exists("tsconfig.json") || hasTypescriptDependency(pkg) ? "typescript" : "javascript";
+  const lockfile = nodeLockfile(exists);
+  const packageManager = nodePackageManager(pkg, lockfile);
+
+  const buildName = pickScript(scripts, "build", /^(build|compile|bundle)(:|$)/i);
+  const testName = pickScript(scripts, "test", /(^|:)test(:|$)/i);
+  const lintName = pickScript(scripts, "lint", /(^|:)lint(:|$)/i);
+  const formatName = pickScript(scripts, "format", /(^|:)(format|fmt)(:|$)/i);
+
+  return {
+    language,
+    packageManager,
+    buildCommand: buildName ? `${packageManager} run ${buildName}` : null,
+    // `<pm> test` is the built-in test lifecycle across npm/yarn/pnpm/bun; a non-"test" script uses `run`.
+    testCommand: testName ? (testName === "test" ? `${packageManager} test` : `${packageManager} run ${testName}`) : null,
+    lintCommand: lintName ? `${packageManager} run ${lintName}` : null,
+    formatCommand: formatName ? `${packageManager} run ${formatName}` : null,
+    evidence: { manifest: "package.json", lockfile },
+  };
+}
+
+function detectPython({ exists, read }) {
+  const manifest = ["pyproject.toml", "setup.py", "setup.cfg", "requirements.txt", "Pipfile"].find(exists);
+  if (manifest === undefined) return null;
+  const pyproject = read("pyproject.toml") ?? "";
+
+  let packageManager;
+  let lockfile = null;
+  if (exists("poetry.lock") || /\[tool\.poetry\]/.test(pyproject)) {
+    packageManager = "poetry";
+    lockfile = exists("poetry.lock") ? "poetry.lock" : null;
+  } else if (exists("uv.lock")) {
+    packageManager = "uv";
+    lockfile = "uv.lock";
+  } else if (exists("Pipfile") || exists("Pipfile.lock")) {
+    packageManager = "pipenv";
+    lockfile = exists("Pipfile.lock") ? "Pipfile.lock" : null;
+  } else {
+    packageManager = "pip";
+  }
+
+  // Commands are inferred only from real config so an undeclared tool is never guessed (acceptance: fail safe).
+  const hasRuff = exists("ruff.toml") || exists(".ruff.toml") || /\[tool\.ruff\]/.test(pyproject);
+  const hasPytest = exists("pytest.ini") || exists("tox.ini") || /\[tool\.pytest\b/.test(pyproject);
+
+  return {
+    language: "python",
+    packageManager,
+    buildCommand: /\[build-system\]/.test(pyproject) ? (packageManager === "poetry" ? "poetry build" : "python -m build") : null,
+    testCommand: hasPytest ? "pytest" : null,
+    lintCommand: hasRuff ? "ruff check ." : null,
+    formatCommand: hasRuff ? "ruff format ." : null,
+    evidence: { manifest, lockfile },
+  };
+}
+
+function detectRust({ exists }) {
+  if (!exists("Cargo.toml")) return null;
+  return {
+    language: "rust",
+    packageManager: "cargo",
+    buildCommand: "cargo build",
+    testCommand: "cargo test",
+    lintCommand: "cargo clippy",
+    formatCommand: "cargo fmt",
+    evidence: { manifest: "Cargo.toml", lockfile: exists("Cargo.lock") ? "Cargo.lock" : null },
+  };
+}
+
+function detectGo({ exists }) {
+  if (!exists("go.mod")) return null;
+  const hasGolangci = exists(".golangci.yml") || exists(".golangci.yaml") || exists(".golangci.toml");
+  return {
+    language: "go",
+    packageManager: "go",
+    buildCommand: "go build ./...",
+    testCommand: "go test ./...",
+    lintCommand: hasGolangci ? "golangci-lint run" : "go vet ./...",
+    formatCommand: "gofmt -l .",
+    evidence: { manifest: "go.mod", lockfile: exists("go.sum") ? "go.sum" : null },
+  };
+}
+
+function detectMaven({ exists }) {
+  if (!exists("pom.xml")) return null;
+  return {
+    language: "java",
+    packageManager: "maven",
+    buildCommand: "mvn -B package",
+    testCommand: "mvn -B test",
+    lintCommand: null,
+    formatCommand: null,
+    evidence: { manifest: "pom.xml", lockfile: null },
+  };
+}
+
+function detectGradle({ exists }) {
+  const manifest = exists("build.gradle") ? "build.gradle" : exists("build.gradle.kts") ? "build.gradle.kts" : null;
+  if (manifest === null) return null;
+  const runner = exists("gradlew") ? "./gradlew" : "gradle";
+  return {
+    language: "java",
+    packageManager: "gradle",
+    buildCommand: `${runner} build`,
+    testCommand: `${runner} test`,
+    lintCommand: null,
+    formatCommand: null,
+    evidence: { manifest, lockfile: null },
+  };
+}
+
+const DETECTORS = Object.freeze([detectNode, detectPython, detectRust, detectGo, detectMaven, detectGradle]);
+
+/**
+ * Detect the stack of an already-cloned repository at `repoPath`. Returns `{ detected: true, ... }` with the
+ * language, package manager, and any confidently-inferred commands, or `{ detected: false, reason }` when no
+ * recognized manifest is present. Never throws.
+ */
+export function detectRepoStack(repoPath, options = {}) {
+  if (typeof repoPath !== "string" || !repoPath.trim()) {
+    return { detected: false, reason: "A repository path is required to detect the stack." };
+  }
+  const access = makeAccess(repoPath, options);
+  for (const detector of DETECTORS) {
+    const detected = detector(access);
+    if (detected !== null) {
+      return { detected: true, ...detected };
+    }
+  }
+  return { detected: false, reason: NO_MANIFEST_REASON };
+}
+
+/** One-line human summary of a detection result, suitable for a coding-agent prompt or an operator log. */
+export function renderStackSummary(stack) {
+  if (!stack || stack.detected !== true) {
+    return `stack not detected: ${stack?.reason ?? "unknown reason"}`;
+  }
+  const commands = [
+    stack.buildCommand ? `build=\`${stack.buildCommand}\`` : null,
+    stack.testCommand ? `test=\`${stack.testCommand}\`` : null,
+    stack.lintCommand ? `lint=\`${stack.lintCommand}\`` : null,
+    stack.formatCommand ? `format=\`${stack.formatCommand}\`` : null,
+  ].filter((entry) => entry !== null);
+  const suffix = commands.length > 0 ? ` (${commands.join(", ")})` : " (no validation commands detected)";
+  return `${stack.language} via ${stack.packageManager ?? "unknown"}${suffix}`;
+}