@multipliers-dev/renovate-workflow 0.3.0 → 0.3.1

package/README.md

@@ -67,22 +67,19 @@ Success is `queue_empty` or a classification packet. The classifier **never merg
 
 Required for `/renovate-loop --babysit` and the freshness poll CLI. Not required to try the classifier.
 
-Add a git devDependency and script in your consumer `package.json`:
+Add the npm devDependency and script in your consumer `package.json`:
 
 ```json
 {
   "devDependencies": {
-    "renovate-workflow": "github:multipliers-dev/renovate-workflow",
-    "tsx": "^4.23.12"
+    "@multipliers-dev/renovate-workflow": "^0.3.0"
   },
   "scripts": {
-    "renovate:freshness-poll": "tsx node_modules/renovate-workflow/scripts/renovate-freshness-poll.ts"
+    "renovate:freshness-poll": "renovate-workflow freshness-poll"
   }
 }
 ```
 
-The `scripts/` tree in the installable package is a **temporary legacy surface** for git consumers running `tsx` on TypeScript sources. The stable npm API is the compiled `renovate-workflow` CLI (`renovate-workflow freshness-poll`); see [`.cursor/plans/2026-10-07-npm-package-distribution.plan.md`](.cursor/plans/2026-10-07-npm-package-distribution.plan.md).
-
 See [examples/adopt-stub/package.json](examples/adopt-stub/package.json) and [docs/adopt.md](docs/adopt.md).
 
 ---
@@ -117,22 +114,14 @@ Also:
 
 ## Publishing (maintainers)
 
-This repository uses a **two-step release** — version bump in a reviewed PR, then manual publish. Merging to `main` never publishes.
+This repository uses a **two-step release**. **Merging to `main` never publishes.**
 
 | Step | Who | What |
 | --- | --- | --- |
-| **A — Version bump** | Reviewed PR | Bump aligned manifests (`package.json`, `plugin.json`, `.cursor-plugin/plugin.json`). For `0.3.0`, also scope-rename to `@multipliers-dev/renovate-workflow` and remove `private`. |
-| **B — Publish** | Maintainer | Dispatch [`.github/workflows/release.yml`](.github/workflows/release.yml) on `main` with confirmation `publish X.Y.Z`. |
-
-**Before first release:**
-
-1. `version-bump-0.3.0` merged on `main` (scoped name, `0.3.0`, not private).
-2. **npm CLI preflight** — `sh scripts/npm-stage-cli-preflight.sh` (staged publishing requires npm **≥ 11.15.0**; Node version alone does not guarantee `npm stage` exists).
-3. **One-time registry bootstrap** — validate `0.3.0` in the checkout (`npm ci`, `npm test`, `npm run typecheck`, `npm run build`, `npm pack`), then `npm run bootstrap:tarball` to build/preflight a **disposable `0.0.1` tarball** (npm pack in an isolated temp dir — not manual `tar -czf`; canonical checkout stays at `0.3.0`), then `npm stage publish` that tarball. **Do not** stage `0.3.0` and leave it pending. See [docs/versioning.md § Trusted Publishing bootstrap](docs/versioning.md#trusted-publishing-bootstrap).
-4. Configure npm **Trusted Publisher** for workflow `release.yml` (`multipliers-dev/renovate-workflow`). See [docs/versioning.md § npm Trusted Publisher settings](docs/versioning.md#npm-trusted-publisher-settings).
-5. Dispatch **Release** within **48 hours** of creating the Trusted Publisher configuration; after successful OIDC `0.3.0`, reject the pending bootstrap stage with `npm stage reject <stage-id>` (2FA).
+| **A — Version bump** | Reviewed PR | Bump aligned manifests (`package.json`, `plugin.json`, `.cursor-plugin/plugin.json`) to the same `X.Y.Z`. |
+| **B — Publish** | Maintainer | On `main`, manually dispatch [`.github/workflows/release.yml`](.github/workflows/release.yml) with confirmation `publish X.Y.Z`. |
 
-Publishing uses **OIDC** (no `NPM_TOKEN`). Provenance is automatic for public packages from this public repo.
+Publishing uses npm **Trusted Publishing** (GitHub Actions OIDC). **Do not** create or store an `NPM_TOKEN` / `NODE_AUTH_TOKEN` for releases. Provenance is automatic for this public package from this public repo.
 
 The release workflow reads **name and version from the checked-out `package.json` only** (`npm publish --access public` with no CLI coordinate override). It does not bump versions or commit to `main`. npm and plugin always share version *V* at the same commit. Only one release dispatch runs at a time (`concurrency: release`).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@multipliers-dev/renovate-workflow",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -15,20 +15,11 @@
     "renovate-workflow": "./dist/cli.js"
   },
   "engines": {
-    "node": ">=22.22.1"
+    "node": ">=22.23.3"
   },
   "files": [
     "dist",
-    "README.md",
-    "scripts/renovate-freshness-poll.ts",
-    "scripts/lib",
-    "!scripts/**/*.test.ts",
-    "!scripts/fixtures",
-    "!scripts/cli.ts",
-    "!scripts/check-agent-plugins-spec-drift.ts",
-    "!scripts/tsconfig.json",
-    "!scripts/tsconfig.build.json",
-    "!scripts/*.sh"
+    "README.md"
   ],
   "scripts": {
     "dev": "tsx watch src/index.ts",
@@ -51,6 +42,6 @@
     "husky": "^9.1.7",
     "tsx": "^4.23.15",
     "typescript": "^7.0.2",
-    "vitest": "^5.0.3"
+    "vitest": "^5.0.5"
   }
 }

package/scripts/lib/agent-plugins-spec.ts

@@ -1,150 +0,0 @@
-export const AGENT_PLUGINS_SCHEMA_BASE = "https://agent-plugins.org/schemas";
-export const PUBLISHED_SPEC_MD_URL = "https://agent-plugins.org/specification.md";
-
-const DECLARED_SCHEMA_PATTERN =
-  /^https:\/\/agent-plugins\.org\/schemas\/(\d+\.\d+\.\d+)\/plugin\.schema\.json$/;
-
-const PUBLISHED_SPEC_VERSION_PATTERN = /^\*\*Spec Version:\s*(\d+\.\d+\.\d+)\s*\*\*$/m;
-const PUBLISHED_STATUS_PATTERN = /^\*\*Status:\s*Published\s*\*\*$/m;
-
-export type SpecVersionRelationship = "behind" | "current" | "ahead";
-
-export type SpecRelationshipEvaluation = {
-  declaredVersion: string;
-  latestPublishedVersion: string;
-  relationship: SpecVersionRelationship;
-  driftDetected: boolean;
-};
-
-export type PublishedSignalConfirmation = {
-  markdownVersion: string;
-  schemaVersion: string;
-  schemaHttpStatus: number;
-};
-
-export function buildPublishedSchemaUrl(version: string): string {
-  return `${AGENT_PLUGINS_SCHEMA_BASE}/${version}/plugin.schema.json`;
-}
-
-export function parseAgentPluginsSchemaUrl(schemaUrl: string): string {
-  const match = DECLARED_SCHEMA_PATTERN.exec(schemaUrl);
-  if (!match) {
-    throw new Error(
-      `malformed Agent Plugins schema URL: expected https://agent-plugins.org/schemas/X.Y.Z/plugin.schema.json`,
-    );
-  }
-  return match[1]!;
-}
-
-export function parseDeclaredSpecVersion($schema: string): string {
-  try {
-    return parseAgentPluginsSchemaUrl($schema);
-  } catch {
-    throw new Error(
-      `malformed $schema URL: expected https://agent-plugins.org/schemas/X.Y.Z/plugin.schema.json`,
-    );
-  }
-}
-
-export function parsePublishedSchemaDocumentVersion(schemaDocument: string): string {
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(schemaDocument) as unknown;
-  } catch {
-    throw new Error("published schema document is not valid JSON");
-  }
-
-  if (typeof parsed !== "object" || parsed === null || !("$id" in parsed)) {
-    throw new Error("published schema document is missing $id");
-  }
-
-  const schemaId = (parsed as { $id: unknown }).$id;
-  if (typeof schemaId !== "string") {
-    throw new Error("published schema document has invalid $id");
-  }
-
-  return parseAgentPluginsSchemaUrl(schemaId);
-}
-
-export function parsePublishedSpecVersion(specMarkdown: string): string {
-  if (!PUBLISHED_STATUS_PATTERN.test(specMarkdown)) {
-    throw new Error("upstream specification.md is missing Status: Published");
-  }
-
-  const versionMatch = PUBLISHED_SPEC_VERSION_PATTERN.exec(specMarkdown);
-  if (!versionMatch) {
-    throw new Error("upstream specification.md is missing Spec Version");
-  }
-
-  return versionMatch[1]!;
-}
-
-export function compareSemver(a: string, b: string): -1 | 0 | 1 {
-  const aParts = a.split(".").map((part) => Number(part));
-  const bParts = b.split(".").map((part) => Number(part));
-
-  if (aParts.length !== 3 || bParts.length !== 3) {
-    throw new Error(`invalid semver: ${a} or ${b}`);
-  }
-
-  for (let index = 0; index < 3; index += 1) {
-    const aPart = aParts[index]!;
-    const bPart = bParts[index]!;
-
-    if (!Number.isInteger(aPart) || !Number.isInteger(bPart)) {
-      throw new Error(`invalid semver: ${a} or ${b}`);
-    }
-
-    if (aPart < bPart) {
-      return -1;
-    }
-    if (aPart > bPart) {
-      return 1;
-    }
-  }
-
-  return 0;
-}
-
-export function confirmPublishedUpstreamVersion(
-  signals: PublishedSignalConfirmation,
-): string {
-  const { markdownVersion, schemaVersion, schemaHttpStatus } = signals;
-
-  if (schemaHttpStatus !== 200) {
-    throw new Error(
-      `published schema URL returned HTTP ${schemaHttpStatus} for version ${schemaVersion}`,
-    );
-  }
-
-  if (markdownVersion !== schemaVersion) {
-    throw new Error(
-      `published signal mismatch: specification.md reports ${markdownVersion} but published schema document $id reports ${schemaVersion}`,
-    );
-  }
-
-  return markdownVersion;
-}
-
-export function evaluateSpecRelationship(options: {
-  declared: string;
-  published: string;
-}): SpecRelationshipEvaluation {
-  const comparison = compareSemver(options.declared, options.published);
-
-  let relationship: SpecVersionRelationship;
-  if (comparison < 0) {
-    relationship = "behind";
-  } else if (comparison > 0) {
-    relationship = "ahead";
-  } else {
-    relationship = "current";
-  }
-
-  return {
-    declaredVersion: options.declared,
-    latestPublishedVersion: options.published,
-    relationship,
-    driftDetected: relationship === "behind",
-  };
-}

package/scripts/lib/bootstrap-tarball.ts

@@ -1,230 +0,0 @@
-import { execSync } from "node:child_process";
-import {
-  copyFileSync,
-  cpSync,
-  existsSync,
-  mkdirSync,
-  mkdtempSync,
-  readFileSync,
-  rmSync,
-  writeFileSync,
-} from "node:fs";
-import { tmpdir } from "node:os";
-import { basename, dirname, join, resolve } from "node:path";
-
-export const BOOTSTRAP_VERSION = "0.0.1";
-
-const FORBIDDEN_ENTRY_PATTERNS: Array<{ label: string; test: (entry: string) => boolean }> = [
-  {
-    label: "directory entry package/ (trailing slash)",
-    test: (entry) => entry === "package/" || entry === "package",
-  },
-  {
-    label: "AppleDouble (._*)",
-    test: (entry) => /(^|\/)\._[^/]+/.test(entry),
-  },
-  {
-    label: ".git",
-    test: (entry) => entry.includes(".git"),
-  },
-  {
-    label: "test files",
-    test: (entry) => entry.endsWith(".test.ts") || entry.endsWith(".test.js"),
-  },
-  {
-    label: "fixtures",
-    test: (entry) => entry.includes("/fixtures/"),
-  },
-  {
-    label: "credentials",
-    test: (entry) =>
-      /(^|\/)\.env($|\.)/.test(entry) ||
-      entry.includes("credentials.json") ||
-      entry.includes("id_rsa"),
-  },
-];
-
-export function listTarballEntries(tarballPath: string): string[] {
-  const listing = execSync(`tar -tzf "${tarballPath}"`, { encoding: "utf8" });
-  return listing
-    .trim()
-    .split("\n")
-    .filter(Boolean);
-}
-
-export function readPackedManifest(tarballPath: string): { name: string; version: string } {
-  const raw = execSync(`tar -xOf "${tarballPath}" package/package.json`, { encoding: "utf8" });
-  return JSON.parse(raw) as { name: string; version: string };
-}
-
-export function parsePackTarballName(packOutput: string): string {
-  const tarballName = packOutput
-    .split(/\r?\n/)
-    .map((line) => line.trim())
-    .filter((line) => line.endsWith(".tgz"))
-    .at(-1);
-  if (!tarballName) {
-    throw new Error(`npm pack did not report a .tgz filename:\n${packOutput}`);
-  }
-  return tarballName;
-}
-
-export function assertBootstrapTarballEntries(entries: string[]): void {
-  const violations: string[] = [];
-
-  for (const entry of entries) {
-    for (const pattern of FORBIDDEN_ENTRY_PATTERNS) {
-      if (pattern.test(entry)) {
-        violations.push(`${entry} (${pattern.label})`);
-        break;
-      }
-    }
-  }
-
-  if (violations.length > 0) {
-    throw new Error(
-      `bootstrap tarball failed preflight:\n${violations.map((v) => `  - ${v}`).join("\n")}`
-    );
-  }
-
-  const normalized = entries.map((entry) => entry.replace(/^package\//, ""));
-  if (!normalized.some((entry) => entry.startsWith("dist/"))) {
-    throw new Error("bootstrap tarball missing dist/ publish surface");
-  }
-  if (!normalized.includes("package.json")) {
-    throw new Error("bootstrap tarball missing package/package.json");
-  }
-  if (!normalized.includes("README.md")) {
-    throw new Error("bootstrap tarball missing package/README.md");
-  }
-}
-
-export type BootstrapTarballResult = {
-  tarballPath: string;
-  entries: string[];
-  manifest: { name: string; version: string };
-};
-
-/** Lifecycle hooks that reference dev-only paths excluded from the packed `files` list. */
-const ISOLATED_PACK_SCRIPT_KEYS = ["prepare", "prepack"] as const;
-
-function stripIsolatedPackLifecycleScripts(packageDir: string): void {
-  const packageJsonPath = join(packageDir, "package.json");
-  const manifest = JSON.parse(readFileSync(packageJsonPath, "utf8")) as {
-    scripts?: Record<string, string>;
-  };
-  if (!manifest.scripts) {
-    return;
-  }
-  for (const key of ISOLATED_PACK_SCRIPT_KEYS) {
-    delete manifest.scripts[key];
-  }
-  writeFileSync(packageJsonPath, `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
-}
-
-function packDirectoryToDestination(packageDir: string, packDestination: string): string {
-  mkdirSync(packDestination, { recursive: true });
-  const packOutput = execSync(
-    `npm pack --ignore-scripts --loglevel error --pack-destination "${packDestination}"`,
-    {
-      cwd: packageDir,
-      encoding: "utf8",
-      stdio: ["ignore", "pipe", "pipe"],
-    }
-  );
-  const packedName = parsePackTarballName(packOutput);
-  return join(packDestination, packedName);
-}
-
-/**
- * Build a disposable bootstrap tarball from an already-validated `npm pack` artifact.
- *
- * Uses `npm pack --ignore-scripts` in an isolated temp directory so the tarball
- * matches libnpmpack layout (file entries only under package/..., no bare package/
- * directory entry). Manual `tar -czf` is rejected by the npm registry (E415 invalid
- * path: package/) because BSD tar emits a trailing-slash directory entry.
- */
-export function createBootstrapTarballFromValidatedPack(
-  validatedTarballPath: string,
-  options: { outputDir?: string; keepWorkdirs?: boolean } = {}
-): BootstrapTarballResult {
-  const absoluteValidated = resolve(validatedTarballPath);
-  if (!existsSync(absoluteValidated)) {
-    throw new Error(`validated pack tarball not found: ${absoluteValidated}`);
-  }
-
-  const workRoot = mkdtempSync(join(tmpdir(), "renovate-workflow-bootstrap-work-"));
-  const extractDir = join(workRoot, "extract");
-  const isolatedPackageDir = join(workRoot, "isolated-package");
-  // Default: durable artifact dir outside workRoot so the returned .tgz survives work cleanup.
-  const artifactDir = options.outputDir
-    ? resolve(options.outputDir)
-    : mkdtempSync(join(tmpdir(), "renovate-workflow-bootstrap-artifact-"));
-
-  try {
-    mkdirSync(extractDir, { recursive: true });
-    cpSync(absoluteValidated, join(workRoot, "validated.tgz"));
-    execSync(`tar -xzf "${join(workRoot, "validated.tgz")}" -C "${extractDir}"`, {
-      stdio: "pipe",
-    });
-
-    const extractedPackageDir = join(extractDir, "package");
-    if (!existsSync(join(extractedPackageDir, "package.json"))) {
-      throw new Error("validated pack tarball missing package/package.json");
-    }
-
-    cpSync(extractedPackageDir, isolatedPackageDir, { recursive: true });
-    execSync(`npm pkg set version=${BOOTSTRAP_VERSION}`, {
-      cwd: isolatedPackageDir,
-      stdio: "pipe",
-    });
-    // Packed artifact omits scripts/*.sh; npm pack may still run `prepare` unless removed.
-    stripIsolatedPackLifecycleScripts(isolatedPackageDir);
-
-    const packDir = join(workRoot, "packed");
-    const packedPath = packDirectoryToDestination(isolatedPackageDir, packDir);
-    const packedName = basename(packedPath);
-    const finalPath = join(artifactDir, packedName);
-
-    copyFileSync(packedPath, finalPath);
-
-    const entries = listTarballEntries(finalPath);
-    assertBootstrapTarballEntries(entries);
-    const manifest = readPackedManifest(finalPath);
-
-    if (manifest.version !== BOOTSTRAP_VERSION) {
-      throw new Error(
-        `bootstrap tarball version must be ${BOOTSTRAP_VERSION}, got ${manifest.version}`
-      );
-    }
-
-    return { tarballPath: finalPath, entries, manifest };
-  } finally {
-    if (!options.keepWorkdirs) {
-      rmSync(workRoot, { recursive: true, force: true });
-    }
-  }
-}
-
-export function packValidatedReleaseArtifact(repoRoot: string): string {
-  const packDir = mkdtempSync(join(tmpdir(), "renovate-workflow-validated-pack-"));
-  return packDirectoryToDestination(repoRoot, packDir);
-}
-
-export function removePackedArtifactTree(tarballPath: string): void {
-  rmSync(dirname(tarballPath), { recursive: true, force: true });
-}
-
-/** Remove the temp directory that owns a default-path bootstrap tarball. */
-export function removeBootstrapArtifactTree(tarballPath: string): void {
-  rmSync(dirname(tarballPath), { recursive: true, force: true });
-}
-
-export function assertCheckoutVersion(repoRoot: string, expectedVersion: string): void {
-  const manifest = JSON.parse(
-    readFileSync(join(repoRoot, "package.json"), "utf8")
-  ) as { version: string };
-  if (manifest.version !== expectedVersion) {
-    throw new Error(`Expected package version ${expectedVersion}, got ${manifest.version}`);
-  }
-}

package/scripts/lib/derive-stop-causes.ts

@@ -1,121 +0,0 @@
-/**
- * Single derivation table for classifier emission and guardrails evaluation.
- * Keys must match the reference table in the renovate investigation lane plan.
- */
-
-export const TRIGGER_WATCH_KEYS = [
-  "implementation_changes_required",
-  "lockfile_threshold_exceeded",
-  "ci_failure_unexplained",
-  "runtime_behavior_affected",
-] as const;
-
-export type TriggerWatchKey = (typeof TRIGGER_WATCH_KEYS)[number];
-
-export const KNOWN_STOP_CAUSES = [
-  "decision_human_required",
-  "stop_flag_expected_human_required",
-  "triggered_implementation_changes_required",
-  "triggered_lockfile_threshold_exceeded",
-  "triggered_ci_failure_unexplained",
-  "triggered_runtime_behavior_affected",
-  "triggered_runtime_behavior_affected_sole",
-  "triggered_human_required_unmapped",
-  "decision_defer",
-] as const;
-
-export type StopCauseKey = (typeof KNOWN_STOP_CAUSES)[number];
-
-const KNOWN_STOP_CAUSE_SET = new Set<string>(KNOWN_STOP_CAUSES);
-const TRIGGER_WATCH_KEY_SET = new Set<string>(TRIGGER_WATCH_KEYS);
-
-export type DeriveStopCausesInput = {
-  stop?: boolean;
-  classification?: {
-    decision?: string;
-  };
-  triggered_human_required?: string[];
-  stop_causes?: string[];
-};
-
-export function isKnownStopCause(value: string): value is StopCauseKey {
-  return KNOWN_STOP_CAUSE_SET.has(value);
-}
-
-function deriveTriggerStopCauses(triggered: string[]): StopCauseKey[] {
-  const causes: StopCauseKey[] = [];
-
-  if (triggered.some((key) => !TRIGGER_WATCH_KEY_SET.has(key))) {
-    causes.push("triggered_human_required_unmapped");
-  }
-
-  if (triggered.includes("implementation_changes_required")) {
-    causes.push("triggered_implementation_changes_required");
-  }
-
-  if (triggered.includes("lockfile_threshold_exceeded")) {
-    causes.push("triggered_lockfile_threshold_exceeded");
-  }
-
-  if (triggered.includes("ci_failure_unexplained")) {
-    causes.push("triggered_ci_failure_unexplained");
-  }
-
-  if (triggered.includes("runtime_behavior_affected")) {
-    if (triggered.length === 1) {
-      causes.push("triggered_runtime_behavior_affected_sole");
-    } else {
-      causes.push("triggered_runtime_behavior_affected");
-    }
-  }
-
-  return causes;
-}
-
-export function deriveStopCauses(packet: DeriveStopCausesInput): StopCauseKey[] {
-  const causes: StopCauseKey[] = [];
-  const decision = packet.classification?.decision;
-  const triggered = packet.triggered_human_required ?? [];
-
-  if (decision === "defer") {
-    causes.push("decision_defer");
-  }
-
-  if (decision === "human_required") {
-    causes.push("decision_human_required");
-  }
-
-  if (packet.stop === true && decision === "human_required") {
-    causes.push("stop_flag_expected_human_required");
-  }
-
-  causes.push(...deriveTriggerStopCauses(triggered));
-
-  return causes;
-}
-
-export function stopCausesMatchDerivation(packet: DeriveStopCausesInput): boolean {
-  const expectedCauses = deriveStopCauses(packet);
-  const packetCauses = packet.stop_causes ?? [];
-
-  if (packetCauses.length !== expectedCauses.length) {
-    return false;
-  }
-
-  const sortedPacketCauses = [...packetCauses].sort();
-  const sortedExpectedCauses = [...expectedCauses].sort();
-
-  return sortedPacketCauses.every((cause, index) => cause === sortedExpectedCauses[index]);
-}
-
-export function validateStopCausesDerivation(packet: DeriveStopCausesInput): string | null {
-  if (packet.stop !== true) {
-    return null;
-  }
-
-  if (!stopCausesMatchDerivation(packet)) {
-    return "packet stop_causes do not match deriveStopCauses derivation";
-  }
-
-  return null;
-}