@rightkit/git 0.2.26 → 0.2.28

package/README.md

@@ -1,43 +1,59 @@
 # @rightkit/git
 
-Public-repo-only GitHub Actions workflow templates for the Right/Orthic product suite. One CLI, `right-git`, that renders and installs CI lanes into a repository — and refuses to touch a private one.
+Public-repository-only GitHub Actions workflow layer for Right Suite products. The CLI `right-git` renders and installs CI lanes into `.github/workflows/` from a `.rightgit.json` manifest.
 
-## Why public-only
+| Item | Value |
+|---|---|
+| Where it runs | Build and release tooling (repository CI setup) |
+| Rust pair | None |
+| Version | see INDEX.md |
+| License | MIT OR Apache-2.0 |
 
-GitHub Actions minutes are free and unlimited on public repos, and billed on private ones. `@rightkit/git` enforces that boundary in code, not by convention:
+## Commands
 
-1. **Install-time refusal** — `right-git install`/`sync` resolves repo visibility and refuses any private or internal repo, with no override flag. Visibility fails closed: an unconfirmed repo is treated as not-public.
-2. **Run-time guard** — every rendered workflow carries an unconditional `private-repo-guard` job that fails loudly (`exit 1`) if the repo is ever flipped private after install; every other job depends on it.
-3. **Drift audit** — `right-git drift --all` re-checks visibility across managed repos.
+- `right-git install <repo> --lanes ci,...` writes `.rightgit.json` and renders workflows.
+- `right-git sync` re-renders installed workflows from the manifest.
+- `right-git drift --all` checks installed workflows against templates and re-checks visibility.
+- `right-git adopt` imports existing workflows into the template library.
+- `right-git uninstall` removes every managed file.
 
-## What it does
+`install` and `sync` refuse private, internal and unconfirmed-visibility repositories. There is no override flag.
 
-- **`right-git install|sync`** — render CI lanes (ci, qualification, package-smoke, release-candidate, publish-npm, publish-package-managers) from a `.rightgit.json` manifest into `.github/workflows/`.
-- **`right-git drift`** — detect divergence between installed workflows and templates, and orphaned managed workflows.
-- **`right-git adopt`** — import existing workflows into the template library.
-- **`right-git uninstall`** — remove every managed file, leaving zero behind.
+## Optional QA evidence upload (rust-hybrid)
 
-Workflows are thin callers over the repo's own scripts, so a private repo running the same gates locally executes identical checks.
+Set `qaEvidencePath` in `.rightgit.json` to upload the gate's QA output as a workflow artifact. The path is relative to `$RUNNER_TEMP`; the rendered step uses `${{ runner.temp }}/<path>`. Absolute paths and expression syntax are rejected.
 
-Sync records exact prior bytes, refuses unmanaged same-name workflows, & preflights every target before any write. Qualification preserves schema logs with a unique required artifact.
+```json
+{
+  "profile": "rust-hybrid",
+  "gate": { "path": "scripts/gate.sh" },
+  "qaEvidencePath": "pulse-hub-qa",
+  "qaEvidenceRetentionDays": 14
+}
+```
 
-## Credential posture (read before enabling package-manager publishing)
+- The step runs after the gate with `if: always()` and `if-no-files-found: ignore`.
+- Artifact name: `qa-evidence-${{ matrix.os || runner.os }}-${{ github.run_attempt }}`.
+- `qaEvidenceRetentionDays` is an integer from 1 to 90 and defaults to 7. It requires `qaEvidencePath`.
+- Omit the key and the rendered `ci.yml` is unchanged.
 
-- **Signing credentials stay environment-scoped.** Opt-in Windows candidates use GitHub OIDC with Azure Artifact Signing. Opt-in macOS candidates use a temporary runner keychain plus Apple API-key notarization. Signing jobs run only for `v*` tag refs; manual dispatch produces unsigned candidates only. npm publishing uses short-lived OIDC.
-- **Exception, disclosed:** the optional, opt-in `publish-package-managers` lane *does* require two owner-provisioned, long-lived tokens in GitHub Actions `secrets.*` (`HOMEBREW_TAP_TOKEN`, `WINGET_CREATE_GITHUB_TOKEN`) to open tap/manifest PRs. These are real bearer tokens, public-repo-scoped by the visibility gate but not zero-exposure. The "no signing credential in CI" invariant is specifically about code-signing material; it does not mean "no credential of any kind."
+## Entry points
 
-Manifest input is treated as untrusted: every field flowing into rendered YAML is charset-allowlisted, so a manifest cannot inject `${{ secrets.* }}` or shell/expression syntax.
+No importable API. The package has no `main` and no `exports` map. The supported surface is the `right-git` bin.
 
-## Install
+## Peer dependencies
 
-```sh
-npm install -g @rightkit/git   # or: npx @rightkit/git --help
-```
+None. No runtime dependencies (Node builtins only).
 
-Node builtins only; no runtime dependencies.
+## Example
 
-## Profiles
+```sh
+pnpm add -D @rightkit/git
+pnpm exec right-git install . --lanes ci
+pnpm exec right-git drift --all
+```
 
-`profile` defaults to `node`. `rust-hybrid` requires `ci`, accepts optional `release-candidate`, installs pinned Node plus Rust, then runs product-owned package scripts. `rustCache.workspaces` declares every independent Cargo workspace whose `target` directory participates in dependency caching. Rust-hybrid workflows also enable source-aware sccache compilation caching, reuse one stable cache namespace across CI & candidate jobs, & keep workspace-crate artifacts out of rust-cache to prevent stale exact hits. Candidate configuration is `{ buildScript, checkScript, artifactRoot, os, targets?, signWindows?, signMacos?, releaseChain? }`. Legacy `os` remains supported & derives one target per runner; explicit `targets` is `{ os, platform, architecture }[]`, independent of main CI matrix. Each target maps to native runner, Rust target triple, exact unsigned artifact, & platform signing matrix. Supported platform values are `windows`, `macos`, `linux`; architectures are `x86_64`, `arm64`. RightGit always uploads an unsigned handoff. `signWindows: true` adds Azure OIDC signing. `signMacos: true` adds Developer ID signing plus notarization from protected environment secrets.
+## Known issues
 
-`releaseChain` lets RightGit own full protected DAG while product scripts own artifact semantics: `{ windowsFinalizeScript, macosFinalizeScript?, installedQualificationScript, publishScript, qualificationRunnerVariable, publishSecrets? }`. Generated ordering is unsigned candidate → platform signing/finalization → installed qualification → publication. It deliberately rejects more than one Windows target or more than one macOS target because its installed-qualification/publish handoff has one canonical signed artifact per platform. Every protected job is tag-gated, publication needs successful installed qualification plus macOS finalization when enabled, & only publish job receives declared publication secrets plus `contents: write`.
+- The optional `publish-package-managers` lane needs two long-lived tokens in GitHub Actions secrets. Their names and scope are in the package templates, and they are not zero-exposure. Read `docs/rules/github-access.md` in the workspace before enabling it.
+- Manifest fields are charset-checked before they reach workflow YAML.

package/manifest.mjs

@@ -59,9 +59,17 @@ const TOP_LEVEL_KEYS = new Set([
   "profile",
   "gate",
   "rustCache",
+  "qaEvidencePath",
+  "qaEvidenceRetentionDays",
   "candidate",
   "ownership",
 ]);
+// Optional QA evidence upload (rust-hybrid ci only). qaEvidencePath is a safe
+// relative path under $RUNNER_TEMP; it renders as `${{ runner.temp }}/<path>`.
+const QA_EVIDENCE_DEFAULT_RETENTION_DAYS = 7;
+const QA_EVIDENCE_MAX_RETENTION_DAYS = 90;
+// Pinned to the same upload-artifact release the rust-hybrid release-candidate template uses.
+const UPLOAD_ARTIFACT_PIN = "actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4";
 const GATE_PATH_RE = /^(?!.*\.\.)(?!.*\s)[A-Za-z0-9][A-Za-z0-9._/-]*$/;
 const RUST_WORKSPACE_PATH_RE = /^(?:\.|(?!.*\.\.)(?!.*\s)[A-Za-z0-9][A-Za-z0-9._/-]*)$/;
 const PACKAGE_SCRIPT_RE = /^[A-Za-z0-9][A-Za-z0-9:_-]*$/;
@@ -75,8 +83,11 @@ const NATIVE_RUNNER_TARGETS = new Map([
   ["macos-15-intel", ["macos", "x86_64"]],
 ]);
 
+// Hosted `macos-*` runners plus the self-hosted Xcode runner labels (`xcode-27`).
+const MACOS_RUNNER_RE = /^(macos|xcode)-/i;
+
 function inferredTarget(os) {
-  const platform = /^windows-/i.test(os) ? "windows" : /^macos-/i.test(os) ? "macos" : "linux";
+  const platform = /^windows-/i.test(os) ? "windows" : MACOS_RUNNER_RE.test(os) ? "macos" : "linux";
   return { os, platform, architecture: platform === "macos" ? "arm64" : "x86_64" };
 }
 
@@ -160,6 +171,21 @@ export function validateManifest(manifest) {
     errors.push("gate is only valid for profile 'rust-hybrid'");
   }
 
+  if (manifest.qaEvidencePath !== undefined) {
+    if (profile !== "rust-hybrid") {
+      errors.push("qaEvidencePath is only valid for profile 'rust-hybrid'");
+    } else if (typeof manifest.qaEvidencePath !== "string" || !GATE_PATH_RE.test(manifest.qaEvidencePath)) {
+      errors.push("qaEvidencePath must be a safe relative path under $RUNNER_TEMP (no '..', whitespace, leading '/', or expression syntax)");
+    }
+  }
+  if (manifest.qaEvidenceRetentionDays !== undefined) {
+    if (manifest.qaEvidencePath === undefined) {
+      errors.push("qaEvidenceRetentionDays requires qaEvidencePath");
+    } else if (!Number.isInteger(manifest.qaEvidenceRetentionDays) || manifest.qaEvidenceRetentionDays < 1 || manifest.qaEvidenceRetentionDays > QA_EVIDENCE_MAX_RETENTION_DAYS) {
+      errors.push(`qaEvidenceRetentionDays must be an integer from 1 to ${QA_EVIDENCE_MAX_RETENTION_DAYS}`);
+    }
+  }
+
   const rustCache = manifest.rustCache;
   if (rustCache !== undefined) {
     if (profile !== "rust-hybrid") {
@@ -230,7 +256,7 @@ export function validateManifest(manifest) {
             if (nativeTarget && (target.platform !== nativeTarget[0] || target.architecture !== nativeTarget[1])) {
               errors.push(`candidate.targets[] must declare ${target.os} as ${nativeTarget[0]}/${nativeTarget[1]}`);
             }
-            if ((target.platform === "windows" && !/^windows-/i.test(target.os)) || (target.platform === "macos" && !/^macos-/i.test(target.os))) {
+            if ((target.platform === "windows" && !/^windows-/i.test(target.os)) || (target.platform === "macos" && !MACOS_RUNNER_RE.test(target.os))) {
               errors.push("candidate.targets[].os must match its Windows or macOS platform");
             }
             const targetKey = `${target.os}|${target.platform}|${target.architecture}`;
@@ -1004,6 +1030,27 @@ export function ownershipStep(manifest, lane = "ci") {
   return `\n      - name: RightKit ownership (protected registry roots)\n        shell: bash\n        run: test "$(git rev-parse HEAD)" = "${sourceRevision}" && ${command}`;
 }
 
+/**
+ * Optional QA evidence upload, rendered after the rust-hybrid gate step.
+ * Returns "" when qaEvidencePath is unset, so the rendered workflow stays
+ * byte-identical to a manifest without the key.
+ */
+export function qaEvidenceStep(manifest) {
+  if (manifest.qaEvidencePath === undefined) return "";
+  const retentionDays = manifest.qaEvidenceRetentionDays ?? QA_EVIDENCE_DEFAULT_RETENTION_DAYS;
+  return [
+    "      - name: Upload QA evidence",
+    "        if: always()",
+    `        uses: ${UPLOAD_ARTIFACT_PIN}`,
+    "        with:",
+    "          name: qa-evidence-${{ matrix.os || runner.os }}-${{ github.run_attempt }}",
+    `          path: \${{ runner.temp }}/${manifest.qaEvidencePath}`,
+    `          retention-days: ${retentionDays}`,
+    "          if-no-files-found: ignore",
+    "",
+  ].join("\n");
+}
+
 export function buildRenderContext(manifest, repoPath, lane = "ci") {
   const pm = parsePackageManager(manifest.packageManager);
   const projectName = deriveProjectName(repoPath);
@@ -1031,6 +1078,7 @@ export function buildRenderContext(manifest, repoPath, lane = "ci") {
     MACOS_SIGNING_JOB: macosSigningJob(manifest, pm, artifactPrefix),
     RELEASE_CHAIN_JOBS: releaseChainJobs(manifest, pm, artifactPrefix),
     OWNERSHIP_STEP: ownershipStep(manifest, lane),
+    QA_EVIDENCE_STEP: qaEvidenceStep(manifest),
   };
 
   // Every key below is populated ONLY when its source manifest section is

package/manifest.schema.json

@@ -116,6 +116,18 @@
       "type": "object", "required": ["path"], "additionalProperties": false,
       "properties": { "path": { "type": "string", "pattern": "^(?!.*\\.\\.)(?!.*\\s)[A-Za-z0-9][A-Za-z0-9._/-]*$" } }
     },
+    "qaEvidencePath": {
+      "type": "string",
+      "description": "rust-hybrid only. Safe relative path under $RUNNER_TEMP where the gate writes QA evidence; rendered as ${{ runner.temp }}/<path> and uploaded with if: always().",
+      "pattern": "^(?!.*\\.\\.)(?!.*\\s)[A-Za-z0-9][A-Za-z0-9._/-]*$"
+    },
+    "qaEvidenceRetentionDays": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 90,
+      "default": 7,
+      "description": "rust-hybrid only, requires qaEvidencePath. Artifact retention in days."
+    },
     "candidate": {
       "type": "object",
       "required": ["buildScript", "checkScript", "admissionScript", "stageSummaryScript", "artifactRoot", "os"],

package/manifest.test.mjs

@@ -207,6 +207,9 @@ test("candidate targets permit native multi-architecture matrices independent of
   assert.equal(validateManifest({ ...multiArchitecture, candidate: { ...multiArchitecture.candidate, targets: [{ os: "windows-2025", platform: "windows", architecture: "riscv64" }] } }).valid, false);
   assert.equal(validateManifest({ ...multiArchitecture, candidate: { ...multiArchitecture.candidate, targets: [{ os: "windows-11-arm", platform: "windows", architecture: "x86_64" }] } }).valid, false);
   assert.equal(validateManifest({ ...multiArchitecture, candidate: { ...multiArchitecture.candidate, targets: [{ os: "ubuntu-24.04", platform: "windows", architecture: "x86_64" }] } }).valid, false);
+  const xcodeRunner = { ...multiArchitecture, candidate: { ...multiArchitecture.candidate, os: ["xcode-27"], targets: [{ os: "xcode-27", platform: "macos", architecture: "arm64" }], signWindows: false } };
+  assert.equal(validateManifest(xcodeRunner).valid, true, JSON.stringify(validateManifest(xcodeRunner).errors));
+  assert.equal(validateManifest({ ...multiArchitecture, candidate: { ...multiArchitecture.candidate, os: ["ubuntu-24.04"], targets: [{ os: "ubuntu-24.04", platform: "macos", architecture: "arm64" }] } }).valid, false);
   assert.equal(validateManifest({ ...multiArchitecture, candidate: { ...multiArchitecture.candidate, targets: [{ os: "${{ secrets.X }}", platform: "windows", architecture: "x86_64" }] } }).valid, false);
   assert.equal(validateManifest({ ...multiArchitecture, candidate: { ...multiArchitecture.candidate, releaseChain: { windowsFinalizeScript: "release:finalize:win", macosFinalizeScript: "release:finalize:mac", installedQualificationScript: "release:qualify", publishScript: "release:publish", qualificationRunnerVariable: "QUALIFICATION_RUNNER_LABEL" } } }).valid, false);
 });
@@ -389,3 +392,17 @@ test("F15 non-regression: realistic homebrew/winget/matrix values still validate
   });
   assert.equal(result.valid, true, JSON.stringify(result.errors));
 });
+
+test("qaEvidencePath and qaEvidenceRetentionDays are optional, rust-hybrid only, and charset-checked", () => {
+  const valid = { ...VALID_MINIMAL, profile: "rust-hybrid", gate: { path: "scripts/gate.sh" } };
+  assert.equal(validateManifest({ ...valid, qaEvidencePath: "pulse-hub-qa" }).valid, true);
+  assert.equal(validateManifest({ ...valid, qaEvidencePath: "pulse-hub-qa", qaEvidenceRetentionDays: 30 }).valid, true);
+  for (const qaEvidencePath of ["/abs", "../up", "pulse hub", "${{ runner.temp }}/x", "a;b", "", null]) {
+    assert.equal(validateManifest({ ...valid, qaEvidencePath }).valid, false, String(qaEvidencePath));
+  }
+  for (const qaEvidenceRetentionDays of [0, 91, 1.5, "7"]) {
+    assert.equal(validateManifest({ ...valid, qaEvidencePath: "pulse-hub-qa", qaEvidenceRetentionDays }).valid, false, String(qaEvidenceRetentionDays));
+  }
+  assert.equal(validateManifest({ ...valid, qaEvidenceRetentionDays: 7 }).valid, false, "retention requires a path");
+  assert.equal(validateManifest({ ...VALID_MINIMAL, qaEvidencePath: "pulse-hub-qa" }).valid, false, "node profile rejects qaEvidencePath");
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rightkit/git",
-  "version": "0.2.26",
+  "version": "0.2.28",
   "description": "Public-repo-only GitHub Actions workflow layer: templates, visibility gate, sync/drift/adopt/uninstall for right-git.",
   "license": "MIT OR Apache-2.0",
   "type": "module",

package/render.test.mjs

@@ -829,3 +829,24 @@ test("ci.yml ownership check cannot be removed by deleting optional repo metadat
   const without = renderTemplate(template, buildRenderContext(structuredClone(FULL_MANIFEST), "/repos/widgets"));
   assert.match(without, /RightKit ownership \(protected registry roots\)/);
 });
+
+test("rust-hybrid ci uploads QA evidence after the gate only when qaEvidencePath is set", () => {
+  const base = { ...FULL_MANIFEST, lanes: ["ci"], profile: "rust-hybrid", gate: { path: "scripts/gate.sh" }, templateVersion: "1.1.0" };
+  const template = fs.readFileSync(path.join(templatesDir, "profiles/rust-hybrid/ci.yml"), "utf8");
+
+  const unset = renderTemplate(template, buildRenderContext(structuredClone(base), "/repos/widgets"));
+  assert.doesNotMatch(unset, /upload-artifact|QA evidence|runner\.temp/);
+  assert.match(unset, /CARGO_PROFILE_TEST_DEBUG: "0"\n$/);
+
+  const set = renderTemplate(template, buildRenderContext({ ...structuredClone(base), qaEvidencePath: "pulse-hub-qa" }, "/repos/widgets"));
+  assert.ok(set.indexOf("bash ./scripts/gate.sh") < set.indexOf("- name: Upload QA evidence"), "upload must follow the gate step");
+  assert.match(
+    set,
+    /      - name: Upload QA evidence\n        if: always\(\)\n        uses: actions\/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4\n        with:\n          name: qa-evidence-\$\{\{ matrix\.os \|\| runner\.os \}\}-\$\{\{ github\.run_attempt \}\}\n          path: \$\{\{ runner\.temp \}\}\/pulse-hub-qa\n          retention-days: 7\n          if-no-files-found: ignore\n$/,
+  );
+  // The upload step is the only difference between the two renders.
+  assert.equal(set.replace(/      - name: Upload QA evidence[\s\S]*$/, ""), unset);
+
+  const custom = renderTemplate(template, buildRenderContext({ ...structuredClone(base), qaEvidencePath: "pulse-hub-qa", qaEvidenceRetentionDays: 30 }, "/repos/widgets"));
+  assert.match(custom, /retention-days: 30\n/);
+});

package/rightkit-ownership.json

@@ -0,0 +1,15 @@
+{
+  "package": "@rightkit/git",
+  "capabilities": [
+    {
+      "capability": "github-workflows",
+      "summary": "Public-repo-only GitHub Actions workflow layer: templates, visibility gate, sync/drift/adopt/uninstall for right-git.; declaration-only detection (no precise implementation fingerprint)",
+      "fingerprints": [],
+      "detection": "declaration-only",
+      "policyNotes": [
+        "Package contract retained; dependency declarations do not verify integration.",
+        "No precise implementation fingerprint; declaration-only inventory, never enforced ownership or verified integration."
+      ]
+    }
+  ]
+}

package/templates/profiles/rust-hybrid/ci.yml

@@ -93,3 +93,4 @@ ${RUST_CACHE_WORKSPACES}
           CARGO_INCREMENTAL: "0"
           CARGO_PROFILE_DEV_DEBUG: "0"
           CARGO_PROFILE_TEST_DEBUG: "0"
+${QA_EVIDENCE_STEP}

package/templates/publish-npm.yml

@@ -43,10 +43,30 @@ ${PACKAGE_MANAGER_SETUP}
 ${OWNERSHIP_STEP}
       - run: node scripts/release/build-candidate.mjs --version "${{ github.event.release.tag_name }}" --platform current --out "release/candidates/publish"
       - run: node scripts/release/check-release.mjs release/candidates/publish
+      # check-release must supply publication-evidence.json with artifactSha256.
+      # Capture gated bytes before publication; never hash the source path during readback.
       - id: tarball
         shell: bash
         run: |
-          TARBALL="release/candidates/publish/$(node -e 'const c=require("./release/candidates/publish/compatibility.json");process.stdout.write(c.packageName.replace(/^@/, "").replace("/", "-")+"-"+c.version+".tgz")')"
-          test -f "$TARBALL"
-          echo "path=$TARBALL" >> "$GITHUB_OUTPUT"
+          node --input-type=module <<'NODE'
+          import fs from 'node:fs';
+          import { prepareNpmPublication } from '@rightkit/release/publication-gate.mjs';
+          const root = 'release/candidates/publish';
+          const c = JSON.parse(fs.readFileSync(`${root}/compatibility.json`));
+          const tarball = `${root}/${c.packageName.replace(/^@/, '').replace('/', '-')}-${c.version}.tgz`;
+          const proof = prepareNpmPublication({ name: c.packageName, version: c.version, tarball, evidencePath: `${root}/publication-evidence.json` });
+          // Only safe single-line metadata may enter GitHub outputs.
+          for (const value of [tarball, proof.name, proof.version]) if (/[\r\n]/.test(value)) throw new Error('unsafe npm publication identity');
+          fs.appendFileSync(process.env.GITHUB_OUTPUT, `path=${tarball}\nname=${proof.name}\nversion=${proof.version}\nsha1=${proof.sha1}\n`);
+          NODE
       - run: npm publish "${{ steps.tarball.outputs.path }}"${NPM_PROVENANCE_FLAG} --access public
+      - name: Require registry byte equality
+        env:
+          NPM_PUBLICATION_NAME: ${{ steps.tarball.outputs.name }}
+          NPM_PUBLICATION_VERSION: ${{ steps.tarball.outputs.version }}
+          NPM_PUBLICATION_SHA1: ${{ steps.tarball.outputs.sha1 }}
+        run: |
+          node --input-type=module <<'NODE'
+          import { verifyNpmRegistryBytes } from '@rightkit/release/publication-gate.mjs';
+          verifyNpmRegistryBytes({ name: process.env.NPM_PUBLICATION_NAME, version: process.env.NPM_PUBLICATION_VERSION, sha1: process.env.NPM_PUBLICATION_SHA1 });
+          NODE