@rightkit/git 0.1.0

package/guard-coverage.test.mjs

@@ -0,0 +1,220 @@
+// F5 regression, two properties layered on top of each other:
+//
+// 1. Reachability (original F5): "every generated workflow's first job
+//    carries the private-repo guard" is not the same claim as "no job in a
+//    generated workflow can ever run in a private repo." The QA report
+//    proved the two diverge in publish-package-managers.yml: `winget-token`
+//    had no guard of its own and no `needs`, so it always ran (and always
+//    exited 0) regardless of repository visibility, and `winget` depended
+//    only on that unguarded job.
+//
+// 2. Loudness (the re-validation finding): even once every job is
+//    reachability-guarded, gating the guarded job itself with a job-level
+//    `if: !github.event.repository.private` makes GitHub SKIP that job for
+//    a private repo — the nested "refuse" step inside it is then
+//    unreachable and never runs. A skip is not a failure: the run can read
+//    as "nothing to do" instead of the loud, non-zero failure invariant I1
+//    requires. The fix is a single `private-repo-guard` job with NO
+//    job-level `if` (so it always executes) whose one step's OWN `if`
+//    fires only when private and exits 1 — that fails the job outright.
+//    Every real job `needs` it instead of gating itself.
+//
+// This test renders every lane and walks the job graph, asserting each job
+// is either itself a "self-guard" job (property 2: no job-level `if`, so it
+// unconditionally runs, plus a step whose own `if` matches the positive
+// private check and whose body exits non-zero — i.e. it cannot SUCCEED in a
+// private repo, and does not merely skip) or transitively guarded: it
+// `needs` at least one (transitively) guarded job, and does not override
+// the default `needs`-implies-`success()` gate with `always()` (which would
+// make it run even after a guarded dependency failed/was skipped). This
+// models real GitHub Actions semantics: an `if:` expression that does not
+// itself call success()/always()/cancelled()/failure() is implicitly ANDed
+// with `success()`, so a job whose only dependency failed is skipped too.
+//
+// A job gated the OLD way — job-level `if: !private` — is deliberately NOT
+// recognized as guarded here: that shape is exactly the loudness bug, so a
+// template that regressed to it must fail this test, not pass it.
+//
+// Fails against the pre-fix templates (winget-token: neither guarded nor
+// depending on a guarded job; every guard job-level-`if` gated instead of
+// self-failing) and passes after the fix.
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { renderTemplate } from "./render.mjs";
+import { buildRenderContext, LANE_FILENAMES, KNOWN_LANES } from "./manifest.mjs";
+
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)));
+const templatesDir = path.join(packageRoot, "templates");
+
+const FULL_MANIFEST = {
+  schemaVersion: 1,
+  lanes: [...KNOWN_LANES],
+  matrix: { os: ["ubuntu-latest", "macos-latest", "windows-latest"], node: ["22.13", "24"] },
+  packageManager: "pnpm@11.18.0",
+  publish: {
+    npm: { oidc: true, provenance: true },
+    homebrew: { tap: "acme/homebrew-tap", formulaName: "widgets" },
+    winget: { packageIdentifier: "Acme.Widgets" },
+  },
+  templateVersion: "1.0.0",
+};
+
+const NEGATED_PRIVATE_RE = /!\s*github\.event\.repository\.private/;
+const POSITIVE_PRIVATE_RE = /(?<!!\s*)github\.event\.repository\.private/;
+const ALWAYS_RE = /\balways\(\)/;
+const EXIT_NONZERO_RE = /exit\s+[1-9]/;
+
+/**
+ * Minimal line-based parser for the one shape our templates use: top-level
+ * `jobs:` map, each job a `  name:` header, job-level `if:`/`needs:` at
+ * exactly 4-space indent, steps introduced by `      - ` at 6-space indent
+ * with their own `if:`/`run:` nested under that (see templates/*.yml). Good
+ * enough for our own generated YAML; not a general YAML parser.
+ */
+function parseJobs(content) {
+  const lines = content.split("\n");
+  const jobsIdx = lines.findIndex((l) => /^jobs:\s*$/.test(l));
+  assert.ok(jobsIdx !== -1, "rendered workflow has no top-level jobs: map");
+
+  const jobStarts = [];
+  for (let i = jobsIdx + 1; i < lines.length; i++) {
+    if (/^ {2}\S.*:\s*$/.test(lines[i])) jobStarts.push(i);
+  }
+
+  const jobs = new Map();
+  for (let idx = 0; idx < jobStarts.length; idx++) {
+    const start = jobStarts[idx];
+    const end = idx + 1 < jobStarts.length ? jobStarts[idx + 1] : lines.length;
+    const name = /^ {2}(\S+):/.exec(lines[start])[1];
+    const block = lines.slice(start, end);
+
+    const ifLine = block.find((l) => /^ {4}if: /.test(l));
+    const needsLine = block.find((l) => /^ {4}needs: /.test(l));
+
+    let needs = [];
+    if (needsLine) {
+      const inline = /^ {4}needs:\s*\[(.*)\]\s*$/.exec(needsLine);
+      if (inline) {
+        needs = inline[1].split(",").map((s) => s.trim()).filter(Boolean);
+      } else {
+        const bare = /^ {4}needs:\s*(\S+)\s*$/.exec(needsLine);
+        if (bare) needs = [bare[1]];
+      }
+    }
+
+    // Self-guard detection: a STEP-level `if:` (any indent deeper than the
+    // job-level 4 spaces already captured above as `ifLine`) that positively
+    // references repository.private, with a non-zero `exit` appearing before
+    // the next step starts. Such a job cannot reach "success" in a private
+    // repo regardless of what its job-level `if` says (here, nothing — the
+    // fixed templates give these jobs no job-level `if` at all).
+    let selfGuardStep = false;
+    for (let i = 0; i < block.length; i++) {
+      const isStepIfLine = /^\s+if: /.test(block[i]) && !/^ {4}if: /.test(block[i]);
+      if (isStepIfLine && POSITIVE_PRIVATE_RE.test(block[i])) {
+        const nextStepOffset = block.slice(i + 1).findIndex((l) => /^ {6}- /.test(l));
+        const stepBody = nextStepOffset === -1 ? block.slice(i) : block.slice(i, i + 1 + nextStepOffset);
+        if (EXIT_NONZERO_RE.test(stepBody.join("\n"))) selfGuardStep = true;
+      }
+    }
+
+    jobs.set(name, {
+      ifExpr: ifLine ? ifLine.trim().slice("if: ".length) : null,
+      needs,
+      selfGuardStep,
+    });
+  }
+  return jobs;
+}
+
+/** True if `jobName` can never SUCCEED in a private repo (fails outright or skips). */
+function isGuarded(jobs, jobName, visiting = new Set()) {
+  if (visiting.has(jobName)) return false; // cycle guard, shouldn't happen
+  visiting.add(jobName);
+
+  const job = jobs.get(jobName);
+  assert.ok(job, `needs references unknown job '${jobName}'`);
+
+  // Self-failing job: no job-level `if` gates it away (it always runs), but
+  // one of its own steps refuses (fails) when private. This is the LOUD
+  // shape — the job runs and fails, it is never silently skipped.
+  if (job.selfGuardStep) return true;
+
+  // The OLD shape (job-level `if: !private`) is deliberately NOT treated as
+  // guarded here — gating the whole job away is exactly the "skip instead
+  // of fail" bug this suite now guards against. A template that regresses
+  // to it must fail this assertion, not pass it via this branch.
+  if (job.ifExpr && NEGATED_PRIVATE_RE.test(job.ifExpr) && !job.selfGuardStep) {
+    return false;
+  }
+
+  // A custom `if:` that calls always() bypasses the default needs->success()
+  // gate, so a guarded dependency being skipped would NOT stop this job.
+  if (job.ifExpr && ALWAYS_RE.test(job.ifExpr)) return false;
+
+  // Default GitHub Actions semantics: an `if:` that doesn't call
+  // success()/always()/cancelled()/failure() is implicitly ANDed with
+  // success(), which requires every direct `needs` job to have succeeded.
+  // A failed or skipped dependency fails that check, so this job is
+  // transitively guarded if ANY one of its needs is guarded.
+  return job.needs.some((n) => isGuarded(jobs, n, visiting));
+}
+
+function renderAllLanes() {
+  const context = buildRenderContext(FULL_MANIFEST, "/repos/widgets");
+  const rendered = {};
+  for (const lane of FULL_MANIFEST.lanes) {
+    const templatePath = path.join(templatesDir, LANE_FILENAMES[lane]);
+    const templateText = fs.readFileSync(templatePath, "utf8");
+    rendered[lane] = renderTemplate(templateText, context);
+  }
+  return rendered;
+}
+
+test("F5: every job in every rendered lane is private-guarded or transitively depends on a guarded job", () => {
+  const rendered = renderAllLanes();
+  for (const lane of KNOWN_LANES) {
+    const jobs = parseJobs(rendered[lane]);
+    assert.ok(jobs.size > 0, `lane ${lane} has no jobs`);
+    for (const jobName of jobs.keys()) {
+      assert.ok(
+        isGuarded(jobs, jobName),
+        `lane ${lane} job '${jobName}' is neither private-guarded nor depends (transitively) on a job that is — a private repo could execute it (F5)`,
+      );
+    }
+  }
+});
+
+// F5 loudness proof (the specific gap the re-validation found): a job that
+// is only reachable through a job-level `if: !private` is SKIPPED, not
+// FAILED, for a private repo — GitHub reports skipped jobs as neutral, and
+// a workflow made entirely of skips/successes shows green, not the loud
+// failure invariant I1 demands. This asserts the concrete structural
+// precondition for the loud-failure behavior: the `private-repo-guard` job
+// itself carries NO job-level `if` (so GitHub always schedules and runs it,
+// private or not) and its own step-level `if` positively matches private
+// with a non-zero `exit` — so when private, the job runs and then fails.
+// Fails against the pre-fix shape (guard logic lived inside a job gated by
+// `if: !private`, so the refusing step was itself skipped) and against any
+// regression back to that shape.
+test("F5: private-repo-guard job has no job-level `if` (always runs) and fails outright when private", () => {
+  const rendered = renderAllLanes();
+  for (const lane of KNOWN_LANES) {
+    const jobs = parseJobs(rendered[lane]);
+    const guard = jobs.get("private-repo-guard");
+    assert.ok(guard, `lane ${lane} has no private-repo-guard job`);
+    assert.equal(
+      guard.ifExpr,
+      null,
+      `lane ${lane} private-repo-guard carries a job-level 'if' (${guard.ifExpr}) — that would let it be SKIPPED instead of run-then-failed for a private repo`,
+    );
+    assert.ok(
+      guard.selfGuardStep,
+      `lane ${lane} private-repo-guard has no step that positively checks private and exits non-zero`,
+    );
+  }
+});

package/install.mjs

@@ -0,0 +1,72 @@
+// First-time setup: write `.rightgit.json` into a target repo and render its
+// workflows (DESIGN.md §4). Refuses private/internal/unknown repos (I1) and
+// refuses to clobber an already-installed repo — that's what `sync` is for.
+//
+// Matrix/packageManager/templateVersion defaults are the exact example
+// values DESIGN.md §4 documents for `.rightgit.json`, not invented policy.
+
+import fs from "node:fs";
+import path from "node:path";
+import { assertPublic } from "./policy/visibility-gate.mjs";
+import { MANIFEST_FILENAME, validateManifest } from "./manifest.mjs";
+import { syncCommand } from "./sync.mjs";
+
+export const DEFAULT_MATRIX = { os: ["ubuntu-latest", "macos-latest", "windows-latest"], node: ["22.13", "24"] };
+export const DEFAULT_PACKAGE_MANAGER = "pnpm@11.18.0";
+export const DEFAULT_TEMPLATE_VERSION = "1.0.0";
+
+/**
+ * opts: { lanes: string[], matrix?, packageManager?, templateVersion?,
+ *         provenance?: boolean, homebrewTap?, homebrewFormula?, wingetId? }
+ * Never throws. Returns a typed result: { ok, stage, errors, manifestPath?, plan? }
+ */
+export async function installCommand(repoPath, opts = {}, deps = {}) {
+  const visibility = await assertPublic(repoPath, deps);
+  if (!visibility.allowed) {
+    return { ok: false, stage: "visibility", errors: [visibility.reason] };
+  }
+
+  const manifestPath = path.join(repoPath, MANIFEST_FILENAME);
+  if (fs.existsSync(manifestPath)) {
+    return { ok: false, stage: "exists", errors: [`${manifestPath} already exists; use 'right-git sync' to update an installed repo`] };
+  }
+
+  const lanes = opts.lanes;
+  if (!Array.isArray(lanes) || lanes.length === 0) {
+    return { ok: false, stage: "lanes", errors: ["--lanes is required, e.g. --lanes ci,qualification,package-smoke"] };
+  }
+
+  const manifest = {
+    schemaVersion: 1,
+    lanes,
+    matrix: opts.matrix || DEFAULT_MATRIX,
+    packageManager: opts.packageManager || DEFAULT_PACKAGE_MANAGER,
+    templateVersion: opts.templateVersion || DEFAULT_TEMPLATE_VERSION,
+  };
+
+  if (lanes.includes("publish-npm")) {
+    manifest.publish = { ...manifest.publish, npm: { oidc: true, provenance: opts.provenance !== false } };
+  }
+  if (lanes.includes("publish-package-managers")) {
+    if (!opts.homebrewTap || !opts.homebrewFormula || !opts.wingetId) {
+      return {
+        ok: false,
+        stage: "publish-package-managers-config",
+        errors: ["lane 'publish-package-managers' requires --homebrew-tap, --homebrew-formula, and --winget-id"],
+      };
+    }
+    manifest.publish = {
+      ...manifest.publish,
+      homebrew: { tap: opts.homebrewTap, formulaName: opts.homebrewFormula },
+      winget: { packageIdentifier: opts.wingetId },
+    };
+  }
+
+  const { valid, errors } = validateManifest(manifest);
+  if (!valid) return { ok: false, stage: "manifest-invalid", errors };
+
+  fs.writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+
+  const plan = await syncCommand(repoPath, { dryRun: false, deps });
+  return { ok: plan.ok, stage: "synced", errors: plan.errors || [], manifestPath, plan };
+}

package/manifest.mjs

@@ -0,0 +1,278 @@
+// Loader and hand-rolled validator for the per-repo `.rightgit.json` manifest.
+// Mirrors the shape documented in manifest.schema.json. No ajv dependency —
+// validation is plain JS so the package stays dependency-free (node builtins only).
+
+import fs from "node:fs";
+import path from "node:path";
+
+export const MANIFEST_FILENAME = ".rightgit.json";
+
+export const KNOWN_LANES = Object.freeze([
+  "ci",
+  "qualification",
+  "package-smoke",
+  "release-candidate",
+  "publish-npm",
+  "publish-package-managers",
+]);
+
+// Rendered filename for each lane, installed under <repo>/.github/workflows/.
+export const LANE_FILENAMES = Object.freeze({
+  ci: "ci.yml",
+  qualification: "qualification.yml",
+  "package-smoke": "package-smoke.yml",
+  "release-candidate": "release-candidate.yml",
+  "publish-npm": "publish-npm.yml",
+  "publish-package-managers": "publish-package-managers.yml",
+});
+
+const PACKAGE_MANAGER_RE = /^(pnpm|npm|yarn)@\d+\.\d+\.\d+$/;
+const TEMPLATE_VERSION_RE = /^\d+\.\d+\.\d+$/;
+
+// F15 fix: every one of these fields is manifest (attacker-controlled)
+// input that flows verbatim into a rendered workflow file via render.mjs's
+// literal `${TOKEN}` substitution — render.mjs does no escaping, by design
+// (it is a byte-deterministic template engine, not a YAML/expression-aware
+// one). The re-validation proved a hostile `publish.homebrew.formulaName`
+// containing GitHub Actions expression syntax (`${{ secrets.APPLE_... }}`)
+// survived unmodified into rendered YAML, which GitHub Actions would then
+// evaluate as a real expression — a workflow-expression injection, not just
+// a cosmetic issue. The fix is at the INPUT boundary, not the render step:
+// every manifest field that reaches a template must match a strict
+// allowlist charset that cannot express `${{ }}`, backticks, `$()`,
+// newlines, or any other shell/YAML/expression metacharacter — validated
+// once here, so render.mjs can stay a dumb, deterministic string replacer.
+const SAFE_MATRIX_VALUE_RE = /^[A-Za-z0-9][A-Za-z0-9._/*-]*$/;
+const GITHUB_OWNER_RE = /^[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})$/;
+const GITHUB_REPO_RE = /^[A-Za-z0-9](?:[A-Za-z0-9._-]{0,99})$/;
+const HOMEBREW_FORMULA_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9+_.-]*$/;
+const WINGET_PACKAGE_IDENTIFIER_RE = /^[A-Za-z0-9][A-Za-z0-9-]*(?:\.[A-Za-z0-9][A-Za-z0-9-]*)+$/;
+
+const TOP_LEVEL_KEYS = new Set([
+  "schemaVersion",
+  "lanes",
+  "matrix",
+  "packageManager",
+  "publish",
+  "templateVersion",
+]);
+
+/**
+ * Validate a parsed manifest object against the right-git manifest contract.
+ * Never throws. Returns { valid, errors }.
+ */
+export function validateManifest(manifest) {
+  const errors = [];
+
+  if (manifest === null || typeof manifest !== "object" || Array.isArray(manifest)) {
+    return { valid: false, errors: ["manifest must be a JSON object"] };
+  }
+
+  for (const key of Object.keys(manifest)) {
+    if (!TOP_LEVEL_KEYS.has(key)) errors.push(`unknown top-level field: ${key}`);
+  }
+
+  if (manifest.schemaVersion !== 1) {
+    errors.push("schemaVersion must be exactly 1");
+  }
+
+  let lanes = [];
+  if (!Array.isArray(manifest.lanes) || manifest.lanes.length === 0) {
+    errors.push("lanes must be a non-empty array");
+  } else {
+    lanes = manifest.lanes;
+    const seen = new Set();
+    for (const lane of lanes) {
+      if (typeof lane !== "string" || !KNOWN_LANES.includes(lane)) {
+        errors.push(`unknown lane: ${JSON.stringify(lane)}`);
+      } else if (seen.has(lane)) {
+        errors.push(`duplicate lane: ${lane}`);
+      } else {
+        seen.add(lane);
+      }
+    }
+  }
+
+  if (manifest.matrix === null || typeof manifest.matrix !== "object" || Array.isArray(manifest.matrix)) {
+    errors.push("matrix must be an object with os and node arrays");
+  } else {
+    for (const field of ["os", "node"]) {
+      const value = manifest.matrix[field];
+      if (!Array.isArray(value) || value.length === 0 || !value.every((v) => typeof v === "string" && SAFE_MATRIX_VALUE_RE.test(v))) {
+        errors.push(
+          `matrix.${field} must be a non-empty array of safe runner/version labels (letters, digits, '.', '_', '-', '/', '*' only — no expression or shell syntax)`,
+        );
+      }
+    }
+    for (const key of Object.keys(manifest.matrix)) {
+      if (key !== "os" && key !== "node") errors.push(`unknown matrix field: ${key}`);
+    }
+  }
+
+  if (typeof manifest.packageManager !== "string" || !PACKAGE_MANAGER_RE.test(manifest.packageManager)) {
+    errors.push("packageManager must match '<pnpm|npm|yarn>@X.Y.Z'");
+  }
+
+  if (typeof manifest.templateVersion !== "string" || !TEMPLATE_VERSION_RE.test(manifest.templateVersion)) {
+    errors.push("templateVersion must be a semver string 'X.Y.Z'");
+  }
+
+  const publish = manifest.publish;
+  if (publish !== undefined) {
+    if (publish === null || typeof publish !== "object" || Array.isArray(publish)) {
+      errors.push("publish must be an object");
+    } else {
+      for (const key of Object.keys(publish)) {
+        if (!["npm", "homebrew", "winget"].includes(key)) errors.push(`unknown publish field: ${key}`);
+      }
+      if (publish.npm !== undefined) {
+        const npm = publish.npm;
+        if (npm === null || typeof npm !== "object") {
+          errors.push("publish.npm must be an object");
+        } else {
+          if (npm.oidc !== true) errors.push("publish.npm.oidc must be true (I2: OIDC is the only publish credential)");
+          if (typeof npm.provenance !== "boolean") errors.push("publish.npm.provenance must be a boolean");
+        }
+      }
+      if (publish.homebrew !== undefined) {
+        const hb = publish.homebrew;
+        if (hb === null || typeof hb !== "object") {
+          errors.push("publish.homebrew must be an object");
+        } else {
+          const tapMatch = typeof hb.tap === "string" ? /^([^/]+)\/([^/]+)$/.exec(hb.tap) : null;
+          if (!tapMatch || !GITHUB_OWNER_RE.test(tapMatch[1]) || !GITHUB_REPO_RE.test(tapMatch[2])) {
+            errors.push(
+              "publish.homebrew.tap must be 'owner/repo' using GitHub-safe characters only (letters, digits, '-', '_', '.' — no expression or shell syntax)",
+            );
+          }
+          if (typeof hb.formulaName !== "string" || !HOMEBREW_FORMULA_NAME_RE.test(hb.formulaName)) {
+            errors.push(
+              "publish.homebrew.formulaName must be a Homebrew-safe identifier (letters, digits, '+', '_', '.', '-' only — no expression or shell syntax)",
+            );
+          }
+        }
+      }
+      if (publish.winget !== undefined) {
+        const wg = publish.winget;
+        if (wg === null || typeof wg !== "object" || typeof wg.packageIdentifier !== "string" || !WINGET_PACKAGE_IDENTIFIER_RE.test(wg.packageIdentifier)) {
+          errors.push(
+            "publish.winget.packageIdentifier must be a dotted WinGet-safe identifier, e.g. 'Publisher.Package' (letters, digits, '-', '.' only — no expression or shell syntax)",
+          );
+        }
+      }
+    }
+  }
+
+  if (lanes.includes("publish-npm")) {
+    if (!publish || !publish.npm) {
+      errors.push("lane 'publish-npm' requires publish.npm { oidc: true, provenance }");
+    }
+  }
+
+  if (lanes.includes("publish-package-managers")) {
+    if (!publish || !publish.homebrew) {
+      errors.push("lane 'publish-package-managers' requires publish.homebrew { tap, formulaName }");
+    }
+    if (!publish || !publish.winget) {
+      errors.push("lane 'publish-package-managers' requires publish.winget { packageIdentifier }");
+    }
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Read and validate `<repoPath>/.rightgit.json`.
+ * Never throws — returns a typed result: { ok, manifest, errors, path }.
+ */
+export function loadManifest(repoPath) {
+  const manifestPath = path.join(repoPath, MANIFEST_FILENAME);
+  let raw;
+  try {
+    raw = fs.readFileSync(manifestPath, "utf8");
+  } catch (error) {
+    return { ok: false, manifest: null, errors: [`cannot read ${manifestPath}: ${error.message}`], path: manifestPath };
+  }
+
+  let manifest;
+  try {
+    manifest = JSON.parse(raw);
+  } catch (error) {
+    return { ok: false, manifest: null, errors: [`invalid JSON in ${manifestPath}: ${error.message}`], path: manifestPath };
+  }
+
+  const { valid, errors } = validateManifest(manifest);
+  if (!valid) {
+    return { ok: false, manifest, errors, path: manifestPath };
+  }
+  return { ok: true, manifest, errors: [], path: manifestPath };
+}
+
+function parsePackageManager(spec) {
+  const match = /^(pnpm|npm|yarn)@(\d+\.\d+\.\d+)$/.exec(spec);
+  if (!match) throw new Error(`invalid packageManager spec: ${spec}`);
+  const [, name, version] = match;
+  const installCommand = {
+    pnpm: "pnpm install --frozen-lockfile",
+    npm: "npm ci",
+    yarn: "yarn install --frozen-lockfile",
+  }[name];
+  const runPrefix = { pnpm: "pnpm run", npm: "npm run", yarn: "yarn run" }[name];
+  return { name, version, installCommand, runPrefix };
+}
+
+function yamlFlowStringList(values) {
+  return `[${values.map((v) => JSON.stringify(String(v))).join(", ")}]`;
+}
+
+/**
+ * Derive one project name from the target repo's package.json, falling back
+ * to the repo directory's basename. Never throws.
+ */
+export function deriveProjectName(repoPath) {
+  try {
+    const pkgRaw = fs.readFileSync(path.join(repoPath, "package.json"), "utf8");
+    const pkg = JSON.parse(pkgRaw);
+    if (typeof pkg.name === "string" && pkg.name.length > 0) {
+      return pkg.name.replace(/^@[^/]+\//, "");
+    }
+  } catch {
+    // fall through to directory name
+  }
+  return path.basename(path.resolve(repoPath));
+}
+
+/**
+ * Build the flat placeholder -> value map used by render.mjs, from a
+ * validated manifest plus the target repo's derived project name.
+ */
+export function buildRenderContext(manifest, repoPath) {
+  const pm = parsePackageManager(manifest.packageManager);
+  const projectName = deriveProjectName(repoPath);
+  const artifactPrefix = projectName.toLowerCase().replace(/[^a-z0-9-]+/g, "-");
+
+  const context = {
+    OS_MATRIX: yamlFlowStringList(manifest.matrix.os),
+    NODE_MATRIX: yamlFlowStringList(manifest.matrix.node),
+    NODE_PUBLISH_VERSION: JSON.stringify(String(manifest.matrix.node[0])),
+    PM_NAME: pm.name,
+    PM_CACHE: pm.name,
+    INSTALL_COMMAND: pm.installCommand,
+    PM_RUN: pm.runPrefix,
+    ARTIFACT_PREFIX: artifactPrefix,
+    TEMPLATE_VERSION: manifest.templateVersion,
+  };
+
+  if (manifest.publish?.npm) {
+    context.NPM_PROVENANCE_FLAG = manifest.publish.npm.provenance ? " --provenance" : "";
+  }
+  if (manifest.publish?.homebrew) {
+    context.HOMEBREW_TAP = manifest.publish.homebrew.tap;
+    context.HOMEBREW_FORMULA_NAME = manifest.publish.homebrew.formulaName;
+  }
+  if (manifest.publish?.winget) {
+    context.WINGET_PACKAGE_IDENTIFIER = manifest.publish.winget.packageIdentifier;
+  }
+
+  return context;
+}

package/manifest.schema.json

@@ -0,0 +1,85 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://rightkit.dev/schemas/rightgit-manifest-v1.json",
+  "title": "right-git per-repo manifest (.rightgit.json)",
+  "description": "Declares which right-git lanes a public repo installs and how templates should be parameterized. Hand-validated by manifest.mjs — this file documents the contract, it is not fed to a JSON Schema validator at runtime.",
+  "type": "object",
+  "required": ["schemaVersion", "lanes", "matrix", "packageManager", "templateVersion"],
+  "additionalProperties": false,
+  "properties": {
+    "schemaVersion": {
+      "const": 1
+    },
+    "lanes": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "enum": [
+          "ci",
+          "qualification",
+          "package-smoke",
+          "release-candidate",
+          "publish-npm",
+          "publish-package-managers"
+        ]
+      }
+    },
+    "matrix": {
+      "type": "object",
+      "required": ["os", "node"],
+      "additionalProperties": false,
+      "properties": {
+        "os": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "node": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string", "minLength": 1 }
+        }
+      }
+    },
+    "packageManager": {
+      "type": "string",
+      "pattern": "^(pnpm|npm|yarn)@\\d+\\.\\d+\\.\\d+$"
+    },
+    "publish": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "npm": {
+          "type": "object",
+          "required": ["oidc", "provenance"],
+          "additionalProperties": false,
+          "properties": {
+            "oidc": { "type": "boolean", "const": true },
+            "provenance": { "type": "boolean" }
+          }
+        },
+        "homebrew": {
+          "type": "object",
+          "required": ["tap", "formulaName"],
+          "additionalProperties": false,
+          "properties": {
+            "tap": { "type": "string", "pattern": "^[^/]+/[^/]+$" },
+            "formulaName": { "type": "string", "minLength": 1 }
+          }
+        },
+        "winget": {
+          "type": "object",
+          "required": ["packageIdentifier"],
+          "additionalProperties": false,
+          "properties": {
+            "packageIdentifier": { "type": "string", "minLength": 1 }
+          }
+        }
+      }
+    },
+    "templateVersion": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$"
+    }
+  }
+}