@brainervirus/workit-core 0.6.1 → 0.7.0

package/src/core/registration.ts

@@ -0,0 +1,215 @@
+// Registration merge helpers for the OpenCode/Cursor installers (RR-06).
+// Pure functions: accept the existing user config, return the deduplicated
+// config PLUS the explicit list of keys changed. Unrelated user settings are
+// never rewritten — their values round-trip JSON-identical. The install
+// scripts (`packages/workit-core/scripts/install-*-plugin.sh`) import these so
+// there is exactly one source of truth for registration merging.
+import { existsSync } from "node:fs";
+import path from "node:path";
+
+export interface MergeResult<T> {
+  config: T;
+  changed: string[];
+}
+
+const isRecord = (v: unknown): v is Record<string, unknown> =>
+  v !== null && typeof v === "object" && !Array.isArray(v);
+
+/** Exact identity match — `name` or `name@version` — never a substring (D3). */
+const named = (s: string, name: string) => s === name || s.startsWith(`${name}@`);
+
+/**
+ * True when a plugin identity is a current or legacy Workit entry. Matched by
+ * exact identity, never by substring: an unrelated plugin whose id merely
+ * contains "workflow-toolkit" is preserved (D3). Path-style identities are
+ * compared with normalized separators so a Windows file:// pin (backslashes)
+ * still matches the packages/workit-* path checks.
+ */
+export function isWorkitPlugin(value: unknown): boolean {
+  const s = String(value).replaceAll("\\", "/");
+  const url = s.startsWith("file://") || s.startsWith("git+file://");
+  const pkgPath =
+    s.includes("/packages/workit-opencode/") ||
+    s.includes("/packages/workit-cursor/") ||
+    s.includes("/node_modules/@brainervirus/workit-opencode/") ||
+    s.includes("/node_modules/@brainervirus/workit-cursor/");
+  return (
+    named(s, "workflow-toolkit") ||
+    named(s, "workflow-toolkit-opencode") ||
+    named(s, "local/workflow-toolkit") ||
+    named(s, "@brainervirus/workit-opencode") ||
+    named(s, "@brainervirus/workit-cursor") ||
+    (url && pkgPath) ||
+    (s.startsWith("git+file://") && s.includes("workflow-toolkit"))
+  );
+}
+
+/** Deduplicate every legacy/current Workit plugin identity to one dev pin. */
+export function mergeOpenCodePlugins(plugin: unknown, pin: string): MergeResult<unknown[]> {
+  const existing = Array.isArray(plugin) ? plugin : typeof plugin === "string" ? [plugin] : [];
+  const config = [pin, ...existing.filter((p) => !isWorkitPlugin(p))];
+  const changed = JSON.stringify(config) !== JSON.stringify(existing) ? ["plugin"] : [];
+  return { config, changed };
+}
+
+/** Merge an existing OpenCode config with a dev pin; preserve unrelated keys. */
+export function mergeOpenCodeConfig(
+  config: unknown,
+  pin: string,
+): MergeResult<Record<string, unknown>> {
+  const base = isRecord(config) ? { ...config } : {};
+  const changed: string[] = [];
+
+  const plugins = mergeOpenCodePlugins(base.plugin, pin);
+  if (plugins.changed.length > 0) {
+    base.plugin = plugins.config;
+    changed.push("plugin");
+  }
+
+  // Drop share skills.paths — native ~/.config/opencode/skills links avoid
+  // triple-load duplicates. Matched by exact path segment, never substring: an
+  // unrelated dir like `~/projects/my-workflow-toolkit-skills` is preserved (D3).
+  const skills = base.skills;
+  if (isRecord(skills) && Array.isArray(skills.paths)) {
+    const next = skills.paths.filter((p) => {
+      const segment = String(p).split(/[\\/]/);
+      return !segment.some((seg) => named(seg, "workflow-toolkit"));
+    });
+    if (next.length !== skills.paths.length) {
+      base.skills = { ...skills, paths: next };
+      changed.push("skills.paths");
+    }
+  }
+
+  return { config: base, changed };
+}
+
+/** Collapse current + legacy Cursor plugin identities to a single one. */
+export function mergeCursorEnabledPlugins(enabled: unknown): MergeResult<Record<string, boolean>> {
+  const prev = isRecord(enabled) ? { ...(enabled as Record<string, boolean>) } : {};
+  const next: Record<string, boolean> = { ...prev, "workflow-toolkit": true };
+  delete next["local/workflow-toolkit"]; // legacy duplicate identity
+  const changed = JSON.stringify(next) !== JSON.stringify(prev) ? ["enabled_plugins"] : [];
+  return { config: next, changed };
+}
+
+/** Append the plugin dir once, preserving any existing plugin directories. */
+export function mergeCursorPluginDirs(
+  pluginDirs: unknown,
+  pluginDir: string,
+): MergeResult<string[]> {
+  // path.join does not strip a single trailing separator; do it explicitly for
+  // the dedup comparison (guarding the filesystem-root case).
+  const strip = (p: string) => {
+    const j = path.join(p);
+    return path.dirname(j) === j ? j : j.replace(/[\\/]+$/, "");
+  };
+  const normalized = strip(pluginDir);
+  const prev = Array.isArray(pluginDirs) ? pluginDirs.map(String) : [];
+  // Normalize both sides for comparison so a trailing-slash variant of an
+  // existing entry is not appended as a duplicate; existing entries are kept
+  // verbatim.
+  const exists = prev.some((d) => strip(d) === normalized);
+  const next = exists ? prev : [...prev, normalized];
+  const changed = next.length !== prev.length ? ["plugin_dirs"] : [];
+  return { config: next, changed };
+}
+
+/** Merge Cursor settings: one plugin identity, dirs appended, unrelated keys kept. */
+export function mergeCursorSettings(
+  settings: unknown,
+  pluginDir: string,
+): MergeResult<Record<string, unknown>> {
+  const base = isRecord(settings) ? { ...settings } : {};
+  const changed: string[] = [];
+
+  const enabled = mergeCursorEnabledPlugins(base.enabled_plugins);
+  if (enabled.changed.length > 0) {
+    base.enabled_plugins = enabled.config;
+    changed.push("enabled_plugins");
+  }
+
+  const dirs = mergeCursorPluginDirs(base.plugin_dirs, pluginDir);
+  if (dirs.changed.length > 0) {
+    base.plugin_dirs = dirs.config;
+    changed.push("plugin_dirs");
+  }
+
+  return { config: base, changed };
+}
+
+/** Set one portable workit MCP server, dropping the legacy server name. */
+export function mergeCursorMcp(
+  mcp: unknown,
+  serverName: string,
+  server: Record<string, unknown>,
+): MergeResult<Record<string, unknown>> {
+  const base = isRecord(mcp) ? { ...mcp } : {};
+  const servers = isRecord(base.mcpServers)
+    ? { ...(base.mcpServers as Record<string, unknown>) }
+    : {};
+  delete servers["workflow-toolkit"]; // legacy duplicate registration
+  servers[serverName] = server;
+  const changed = JSON.stringify(servers) !== JSON.stringify(base.mcpServers) ? ["mcpServers"] : [];
+  base.mcpServers = servers;
+  return { config: base, changed };
+}
+
+/** Swap the sessionStart hook command, preserving other hooks and fields. */
+export function mergeCursorHooks(
+  hooks: unknown,
+  sessionStartEntry: Record<string, unknown>,
+): MergeResult<Record<string, unknown>> {
+  const base: Record<string, unknown> = isRecord(hooks) ? { ...hooks } : { version: 1 };
+  const hooksMap = isRecord(base.hooks) ? { ...(base.hooks as Record<string, unknown>) } : {};
+  const list = Array.isArray(hooksMap.sessionStart) ? hooksMap.sessionStart : [];
+  const same =
+    list.length === 1 &&
+    isRecord(list[0]) &&
+    JSON.stringify(list[0]) === JSON.stringify(sessionStartEntry);
+  if (same) return { config: base, changed: [] };
+  hooksMap.sessionStart = [sessionStartEntry];
+  base.hooks = hooksMap;
+  return { config: base, changed: ["hooks.sessionStart"] };
+}
+
+/**
+ * Portable Cursor MCP server entry for an installed plugin dir: prefer the
+ * self-contained node dist bundle (PT-10); fall back to the bash shim for a
+ * dist-less dev checkout.
+ */
+export function cursorMcpServerEntry(packageDir: string): {
+  command: string;
+  args: string[];
+} {
+  if (existsSync(path.join(packageDir, "dist", "mcp-server.js"))) {
+    return {
+      command: "node",
+      args: [path.join(packageDir, "dist", "mcp-server.js"), "${workspaceFolder}"],
+    };
+  }
+  return {
+    command: "bash",
+    args: [path.join(packageDir, "mcp", "run-server.sh"), "${workspaceFolder}"],
+  };
+}
+
+/**
+ * Portable Cursor sessionStart hook entry: prefer the self-contained node dist
+ * bundle; fall back to the bash shim for a dist-less dev checkout (AR-06).
+ */
+export function cursorHooksEntry(packageDir: string): {
+  command: string;
+  args: string[];
+} {
+  if (existsSync(path.join(packageDir, "dist", "cursor-session-start.js"))) {
+    return {
+      command: "node",
+      args: [path.join(packageDir, "dist", "cursor-session-start.js")],
+    };
+  }
+  return {
+    command: "bash",
+    args: [path.join(packageDir, "hooks", "session-start")],
+  };
+}

package/src/core/repo-context.ts

@@ -0,0 +1,447 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import path from "node:path";
+import { vcsConfig, mergedPrStyle } from "./vcs-config";
+
+// Ports of scripts/_shared/common.sh + the four maintained context generators
+// (pr-ready-context.sh, changelog-context.sh, docs-refresh-context.sh,
+// release-notes-context.sh). Each generator returns the same stdout text shape
+// the shell produced (## sections parsed by parse-sections.ts).
+
+export type ContextResult = { stdout: string; stderr: string; exitCode: number; cwd: string };
+
+const runGit = (
+  cwd: string,
+  args: string[],
+): { stdout: string; stderr: string; exitCode: number } => {
+  const result = spawnSync("git", args, { cwd, encoding: "utf8" });
+  return {
+    stdout: (result.stdout ?? "").trimEnd(),
+    stderr: (result.stderr ?? "").trimEnd(),
+    exitCode: result.status ?? 1,
+  };
+};
+
+/** repo_root: git rev-parse --show-toplevel || pwd */
+export const repoRoot = (cwd: string): string => {
+  const r = runGit(cwd, ["rev-parse", "--show-toplevel"]);
+  return r.exitCode === 0 && r.stdout ? r.stdout : cwd;
+};
+
+/** current_branch: git rev-parse --abbrev-ref HEAD || unknown */
+export const currentBranch = (cwd: string): string => {
+  const r = runGit(cwd, ["rev-parse", "--abbrev-ref", "HEAD"]);
+  return r.exitCode === 0 && r.stdout ? r.stdout : "unknown";
+};
+
+/** default_base: first of origin/main main origin/master master origin/develop develop, else HEAD~1 */
+export const defaultBase = (cwd: string): string => {
+  for (const ref of [
+    "origin/main",
+    "main",
+    "origin/master",
+    "master",
+    "origin/develop",
+    "develop",
+  ]) {
+    if (runGit(cwd, ["rev-parse", "--verify", ref]).exitCode === 0) return ref;
+  }
+  return "HEAD~1";
+};
+
+export const rangeArgOrDefault = (arg: string | undefined, cwd: string): string =>
+  arg ? arg : `${defaultBase(cwd)}...HEAD`;
+
+export const isProtectedBranch = (branch: string): boolean =>
+  ["main", "master", "develop", "prod", "production"].includes(branch);
+
+export const isPrBranch = (branch: string): boolean =>
+  branch.startsWith("feature/") || branch.startsWith("bugfix/");
+
+export type PrBranchContext = {
+  baseRef: string;
+  mergeBase: string;
+  range: string;
+  diffRange: string;
+};
+
+/** resolve_pr_branch_context: derive the branch-exclusive range from VCS config. */
+export function resolvePrBranchContext(
+  cwd: string,
+): { ok: true; value: PrBranchContext } | { ok: false; error: string } {
+  const branch = currentBranch(cwd);
+  if (isProtectedBranch(branch)) {
+    return {
+      ok: false,
+      error: `cannot build PR context on protected branch ${branch} — PRs are for feature/* or bugfix/* only`,
+    };
+  }
+  if (!isPrBranch(branch)) {
+    if (branch === "unknown") {
+      return {
+        ok: false,
+        error: `not in a git repository at ${repoRoot(cwd)} — open the target repository as the OpenCode session directory`,
+      };
+    }
+    return {
+      ok: false,
+      error: `branch ${branch} is not feature/* or bugfix/* — checkout a feature branch or pass an explicit git range`,
+    };
+  }
+
+  const resolved = vcsConfig("resolve", cwd);
+  if (resolved.ok === false) {
+    return { ok: false, error: String(resolved.error) };
+  }
+  const base = String(resolved.defaultTargetBranch ?? "");
+  if (!base || runGit(cwd, ["check-ref-format", "--branch", base]).exitCode !== 0) {
+    return { ok: false, error: `invalid configured PR target branch ${base}` };
+  }
+
+  for (const ref of [`origin/${base}`, base]) {
+    if (runGit(cwd, ["rev-parse", "--verify", ref]).exitCode !== 0) continue;
+    const mb = runGit(cwd, ["merge-base", ref, "HEAD"]);
+    if (mb.exitCode !== 0 || !mb.stdout) continue;
+    return {
+      ok: true,
+      value: {
+        baseRef: ref,
+        mergeBase: mb.stdout,
+        range: `${ref}..HEAD`,
+        diffRange: `${mb.stdout}..HEAD`,
+      },
+    };
+  }
+  return {
+    ok: false,
+    error: `configured PR target branch ${base} not found — fetch/checkout it or pass an explicit git range`,
+  };
+}
+
+export function resolvePrRange(cwd: string): string | null {
+  const ctx = resolvePrBranchContext(cwd);
+  return ctx.ok ? ctx.value.range : null;
+}
+
+export const prRangeArgOrDefault = (arg: string | undefined, cwd: string): string | null =>
+  arg ? arg : resolvePrRange(cwd);
+
+export const printSection = (title: string): string => `\n## ${title}\n\n`;
+
+// macOS/Windows filesystems are case-insensitive: existsSync() would match a
+// differently-cased candidate, so the returned template_path must be the
+// ACTUAL on-disk name. Probe each candidate directory case-insensitively and
+// report the real entry — identical to the case-sensitive Linux probe, which
+// only ever sees the exact on-disk name.
+const probeCaseInsensitive = (dir: string, wanted: string): string | null => {
+  try {
+    for (const entry of readdirSync(dir)) {
+      if (entry.toLowerCase() === wanted.toLowerCase()) return entry;
+    }
+  } catch {
+    /* missing dir */
+  }
+  return null;
+};
+
+export const findPrTemplate = (cwd: string): string | null => {
+  for (const rel of [
+    ".gitlab/merge_request_templates/Default.md",
+    ".gitlab/merge_request_templates/default.md",
+    ".gitlab/merge_request_templates/merge_request_template.md",
+    ".github/PULL_REQUEST_TEMPLATE.md",
+    ".github/pull_request_template.md",
+    ".github/PULL_REQUEST_TEMPLATE/pull_request_template.md",
+    "docs/PULL_REQUEST_TEMPLATE.md",
+    "PULL_REQUEST_TEMPLATE.md",
+  ]) {
+    const parts = rel.split("/");
+    const base = parts[parts.length - 1];
+    const dir = parts.length > 1 ? path.join(cwd, ...parts.slice(0, -1)) : cwd;
+    const actual = probeCaseInsensitive(dir, base);
+    if (actual) return [...parts.slice(0, -1), actual].join("/");
+  }
+  return null;
+};
+
+export const fallbackPrTemplate = (): string => `## Summary
+-
+
+## Validation
+- [ ] Not run`;
+
+/** commit_log_for_range: git log --oneline --decorate --no-merges, falls back to -10. */
+export const commitLogForRange = (cwd: string, range: string): string => {
+  const r = runGit(cwd, ["log", "--oneline", "--decorate", "--no-merges", range, "--"]);
+  if (r.exitCode === 0) return r.stdout;
+  return runGit(cwd, ["log", "--oneline", "--decorate", "-10", "--"]).stdout;
+};
+
+export const changedFilesForRange = (cwd: string, range: string): string => {
+  const r = runGit(cwd, ["diff", "--name-only", range, "--"]);
+  if (r.exitCode === 0) return r.stdout;
+  return runGit(cwd, ["diff", "--name-only", "--"]).stdout;
+};
+
+export const diffStatForRange = (cwd: string, range: string): string => {
+  const r = runGit(cwd, ["diff", "--stat", range, "--"]);
+  if (r.exitCode === 0) return r.stdout;
+  return runGit(cwd, ["diff", "--stat", "--"]).stdout;
+};
+
+const packageScripts = (cwd: string, keys: string[]): string[] => {
+  const pkgPath = path.join(cwd, "package.json");
+  if (!existsSync(pkgPath)) return [];
+  try {
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf8")) as { scripts?: Record<string, string> };
+    return keys
+      .filter((k) => pkg.scripts && typeof pkg.scripts[k] === "string")
+      .map((k) => `${k}: ${pkg.scripts?.[k]}`);
+  } catch {
+    return [];
+  }
+};
+
+/** find . -maxdepth 3 -name README.md -o -name *.md with excludes, sorted, first 200. */
+export const documentationFiles = (cwd: string): string[] => {
+  const excluded = new Set([".git", "node_modules", "target", "dist"]);
+  const matches: string[] = [];
+  const walk = (dir: string, depth: number) => {
+    if (depth > 3) return;
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        if (excluded.has(entry.name)) continue;
+        walk(path.join(dir, entry.name), depth + 1);
+      } else if (entry.isFile() && (entry.name === "README.md" || entry.name.endsWith(".md"))) {
+        // Shell parity: the script printed "./path" with forward slashes even
+        // on win32, where path.relative would otherwise emit backslashes.
+        matches.push("./" + path.relative(cwd, path.join(dir, entry.name)).replaceAll("\\", "/"));
+      }
+    }
+  };
+  walk(cwd, 1);
+  return matches.sort().slice(0, 200);
+};
+
+const readTrimmed = (file: string, maxLines: number): string => {
+  if (!existsSync(file)) return "";
+  const lines = readFileSync(file, "utf8").split("\n");
+  return lines.slice(0, maxLines).join("\n");
+};
+
+/** Port of pr-ready-context.sh — PR-ready repository context. */
+export function prReadyContext(root: string, range?: string): ContextResult {
+  const cwd = path.resolve(repoRoot(root));
+  let stdout = "";
+  const autoRange = range === undefined;
+
+  let ctx: { ok: true; value: PrBranchContext } | { ok: false; error: string } | null = null;
+  if (autoRange) {
+    ctx = resolvePrBranchContext(cwd);
+    if (!ctx.ok) return { stdout: "", stderr: `ERROR: ${ctx.error}\n`, exitCode: 1, cwd };
+    range = ctx.value.range;
+  }
+
+  stdout += printSection("Repository");
+  stdout += `root: ${cwd}\n`;
+  stdout += `branch: ${currentBranch(cwd)}\n`;
+  stdout += `range: ${range}\n`;
+  if (autoRange && ctx?.ok) {
+    stdout += `base_ref: ${ctx.value.baseRef}\n`;
+    stdout += `merge_base: ${ctx.value.mergeBase}\n`;
+    stdout += `diff_range: ${ctx.value.diffRange}\n`;
+    stdout += "range_mode: branch-exclusive\n";
+    if (process.env.PR_SYNC_NOTES) stdout += `git_sync: ${process.env.PR_SYNC_NOTES}\n`;
+  }
+  const diffRange = autoRange && ctx?.ok ? ctx.value.diffRange : (range ?? "");
+
+  stdout += printSection("Working Tree");
+  const status = runGit(cwd, ["status", "--short"]);
+  stdout += status.stdout + (status.stderr ? `\n${status.stderr}` : "");
+  stdout += "\n";
+
+  stdout += printSection("Commits");
+  stdout += commitLogForRange(cwd, range ?? "");
+  stdout += "\n";
+
+  stdout += printSection("Diff Stat");
+  stdout += diffStatForRange(cwd, diffRange);
+  stdout += "\n";
+
+  stdout += printSection("Changed Files");
+  stdout += changedFilesForRange(cwd, diffRange);
+  stdout += "\n";
+
+  stdout += printSection("PR Template");
+  const template = findPrTemplate(cwd);
+  if (template) {
+    stdout += `template_path: ${template}\n\n`;
+    stdout += readTrimmed(path.join(cwd, template), 220);
+  } else {
+    stdout += "template_path: none\n\n";
+    stdout += fallbackPrTemplate();
+  }
+  stdout += "\n";
+
+  stdout += printSection("Recent Validation Signals");
+  if (existsSync(path.join(cwd, "package.json"))) {
+    stdout += "package.json detected. Common scripts:\n";
+    const found = packageScripts(cwd, ["lint", "format:check", "test", "build"]);
+    if (found.length) stdout += found.join("\n") + "\n";
+  }
+  if (
+    existsSync(path.join(cwd, "Cargo.toml")) ||
+    existsSync(path.join(cwd, "src-tauri/Cargo.toml"))
+  ) {
+    stdout += "Rust project detected.\n";
+  }
+
+  stdout += printSection("VCS Config");
+  const vc = vcsConfig("resolve", cwd);
+  if (vc.ok) {
+    stdout += `workspace: ${String(vc.workspace_name ?? "none")}\n`;
+    stdout += `provider: ${String(vc.provider ?? "gitlab")}\n`;
+  } else {
+    // RL-01: never report silent defaults for malformed vcs.json — surface the
+    // exact-path diagnostic instead.
+    stdout += `vcs: unreadable (malformed) — ${String(vc.error ?? "cannot read vcs.json")}\n`;
+  }
+  // B4: the shell printed only workspace:/provider: (the summary dump was
+  // discarded). Keep that concise shape — no raw summary JSON in the context.
+  if (!vcsConfig("summary", cwd).ok) {
+    stdout += "vcs: not configured — run /wk-init action vcs_scaffold\n";
+  }
+
+  stdout += printSection("Merged PR Style");
+  const style = mergedPrStyle(6, cwd);
+  stdout += JSON.stringify(style, null, 2) + "\n";
+
+  return { stdout, stderr: "", exitCode: 0, cwd };
+}
+
+const CHANGELOG_RULES = `- Use an [Unreleased] section.
+- Use Added, Changed, Deprecated, Removed, Fixed, Security.
+- Entries should be human-readable and user-facing.
+- Do not use raw commit messages as changelog bullets.
+- MERGE into existing ### Category under [Unreleased] — never append a second ### Added / ### Fixed block.
+- Apply with the native workflow_changelog_apply tool only (not hand-edits under Unreleased).
+- If Unreleased already has duplicate category headings, normalize_only first.`;
+
+/** Port of changelog-context.sh — changelog update context. */
+export function changelogContext(root: string, range?: string): ContextResult {
+  const cwd = path.resolve(repoRoot(root));
+  const resolvedRange = rangeArgOrDefault(range, cwd);
+  let stdout = "";
+
+  stdout += printSection("Repository");
+  stdout += `root: ${cwd}\n`;
+  stdout += `branch: ${currentBranch(cwd)}\n`;
+  stdout += `range: ${resolvedRange}\n`;
+
+  stdout += printSection("Keep a Changelog Rules");
+  stdout += CHANGELOG_RULES + "\n";
+
+  stdout += printSection("Existing CHANGELOG.md");
+  const changelogPath = path.join(cwd, "CHANGELOG.md");
+  if (existsSync(changelogPath)) {
+    stdout += readTrimmed(changelogPath, 260) + "\n";
+  } else {
+    stdout += "CHANGELOG.md not found.\n";
+  }
+
+  stdout += printSection("Commits");
+  stdout += commitLogForRange(cwd, resolvedRange) + "\n";
+
+  stdout += printSection("Diff Stat");
+  stdout += diffStatForRange(cwd, resolvedRange) + "\n";
+
+  stdout += printSection("Changed Files");
+  stdout += changedFilesForRange(cwd, resolvedRange) + "\n";
+
+  return { stdout, stderr: "", exitCode: 0, cwd };
+}
+
+/** Port of docs-refresh-context.sh — documentation refresh context. */
+export function docsRefreshContext(root: string, range?: string): ContextResult {
+  const cwd = path.resolve(repoRoot(root));
+  const resolvedRange = rangeArgOrDefault(range, cwd);
+  let stdout = "";
+
+  stdout += printSection("Repository");
+  stdout += `root: ${cwd}\n`;
+  stdout += `branch: ${currentBranch(cwd)}\n`;
+  stdout += `range: ${resolvedRange}\n`;
+
+  stdout += printSection("Changed Files");
+  stdout += changedFilesForRange(cwd, resolvedRange) + "\n";
+
+  stdout += printSection("Documentation Files");
+  stdout += documentationFiles(cwd).join("\n") + "\n";
+
+  stdout += printSection("README Preview");
+  const readme = path.join(cwd, "README.md");
+  if (existsSync(readme)) {
+    stdout += readTrimmed(readme, 220) + "\n";
+  } else {
+    stdout += "README.md not found.\n";
+  }
+
+  stdout += printSection("Package Scripts");
+  const pkgPath = path.join(cwd, "package.json");
+  if (existsSync(pkgPath)) {
+    try {
+      const pkg = JSON.parse(readFileSync(pkgPath, "utf8")) as Record<string, unknown>;
+      stdout +=
+        JSON.stringify({ name: pkg.name, version: pkg.version, scripts: pkg.scripts }, null, 2) +
+        "\n";
+    } catch {
+      /* unreadable package.json */
+    }
+  } else {
+    stdout += "package.json not found.\n";
+  }
+
+  return { stdout, stderr: "", exitCode: 0, cwd };
+}
+
+/** Port of release-notes-context.sh — tags + commits + files for a range. */
+export function releaseNotesContext(root: string, rangeOrTag: string): ContextResult {
+  const cwd = path.resolve(repoRoot(root));
+  if (!rangeOrTag) {
+    return { stdout: "", stderr: "ERROR: release tag or range required\n", exitCode: 1, cwd };
+  }
+  const resolvedRange = rangeArgOrDefault(rangeOrTag, cwd);
+  let stdout = "";
+
+  stdout += printSection("Repository");
+  stdout += `root: ${cwd}\n`;
+  stdout += `branch: ${currentBranch(cwd)}\n`;
+  stdout += `requested: ${rangeOrTag}\n`;
+  stdout += `range: ${resolvedRange}\n`;
+
+  stdout += printSection("Tags");
+  const tags = runGit(cwd, ["tag", "--sort=-creatordate"]);
+  if (tags.exitCode === 0) stdout += tags.stdout.split("\n").slice(0, 20).join("\n") + "\n";
+
+  stdout += printSection("Commits");
+  stdout += commitLogForRange(cwd, resolvedRange) + "\n";
+
+  stdout += printSection("Diff Stat");
+  stdout += diffStatForRange(cwd, resolvedRange) + "\n";
+
+  stdout += printSection("Changed Files");
+  stdout += changedFilesForRange(cwd, resolvedRange) + "\n";
+
+  stdout += printSection("Existing Release Files");
+  for (const rel of ["CHANGELOG.md", "RELEASE_NOTES.md", ".github/releases.md"]) {
+    if (existsSync(path.join(cwd, rel))) stdout += rel + "\n";
+  }
+
+  return { stdout, stderr: "", exitCode: 0, cwd };
+}

package/src/core/repo-tools.ts

@@ -0,0 +1,23 @@
+import { fail, ok, run } from "../core";
+
+export type RunResult = ReturnType<typeof run>;
+
+export type RepoRuntime = {
+  git(root: string, args: string[]): RunResult;
+  verifyProject(root: string, dryRun: boolean): RunResult;
+  prContext(root: string, range: string | undefined): RunResult;
+  changelogContext(root: string, range: string | undefined): RunResult;
+  docsContext(root: string, range: string | undefined): RunResult;
+  releaseContext(root: string, range: string): RunResult;
+  prCreate(root: string, env: Record<string, string>): RunResult;
+  initApply(root: string, action: string, env: Record<string, string>): RunResult;
+  initStatus(root: string): RunResult;
+  toolkitStatus(root: string): RunResult | Promise<RunResult>;
+};
+
+export const normalizeLegacyResult = (value: Record<string, unknown>) => {
+  if (value.error) return fail(String(value.error));
+  if (value.ok === false) return fail("legacy operation reported failure");
+  const { ok: _legacyOk, ...data } = value;
+  return ok(data);
+};