@prisma-next/extension-author-tools 0.8.0

package/README.md

@@ -0,0 +1,33 @@
+# @prisma-next/extension-author-tools
+
+CLI tools that pair with the [`prisma-next-extension-upgrade`](../../../skills/extension-author/prisma-next-extension-upgrade/SKILL.md) agent skill. Today this package ships one tool; future tools for extension authors using the upgrade-skill flow will land here.
+
+The agent-readable upgrade procedure itself (the SKILL.md, the `upgrades/<from>-to-<to>/instructions.md` set, the README) lives at [`skills/extension-author/prisma-next-extension-upgrade/`](../../../skills/extension-author/prisma-next-extension-upgrade/) and is distributed via `npx skills add prisma/prisma-next/skills/extension-author --all`. This package is the npm-published companion that supplies the CI bin the skill drives.
+
+## Installation
+
+```bash
+pnpm add -D @prisma-next/extension-author-tools
+# or:
+npm install --save-dev @prisma-next/extension-author-tools
+```
+
+## Tools
+
+### `prisma-next-check-pins`
+
+CI guard for extension packages. Asserts that every `@prisma-next/*` entry under the package's `peerDependencies` (and, optionally, `dependencies`) is pinned to an exact version, not a range.
+
+This is the invariant the [`prisma-next-extension-upgrade`](../../../skills/extension-author/prisma-next-extension-upgrade/SKILL.md) skill relies on at upgrade time: extension authors pin every `@prisma-next/*` peer to a single exact version per release of their extension, so the skill can mechanically advance both the framework deps and the extension's published version in lockstep.
+
+Run from the extension's repository root:
+
+```bash
+pnpm exec prisma-next-check-pins
+```
+
+Exit code is `0` if every `@prisma-next/*` peerDep is exact, non-zero otherwise. Suitable for use in a GitHub Actions `run:` step, a pre-commit hook, or `package.json` `scripts.lint`.
+
+## Source location
+
+`packages/0-shared/extension-author-tools/`

package/bin/prisma-next-check-pins.mjs

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+// Enforce the exact-pin rule for Prisma Next extensions: every
+// `@prisma-next/*` entry in `dependencies`, `peerDependencies`, and
+// `optionalDependencies` must be a single exact-version string, and
+// every entry must resolve to the same version. Exits 0 on success
+// (no output); on failure, prints one structured line per offending
+// entry and exits non-zero.
+
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { cwd, exit, stderr } from 'node:process';
+
+const DEP_FIELDS = ['dependencies', 'peerDependencies', 'optionalDependencies'];
+const PRISMA_NEXT_SCOPE = '@prisma-next/';
+const EXACT_VERSION_RE = /^\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?$/;
+
+function readPackageJson() {
+  const path = join(cwd(), 'package.json');
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch (err) {
+    stderr.write(`prisma-next-check-pins: cannot read package.json at ${path}: ${err.message}\n`);
+    exit(2);
+  }
+}
+
+function collectEntries(pkg) {
+  const entries = [];
+  for (const field of DEP_FIELDS) {
+    const deps = pkg[field];
+    if (!deps || typeof deps !== 'object') continue;
+    for (const [name, spec] of Object.entries(deps)) {
+      if (!name.startsWith(PRISMA_NEXT_SCOPE)) continue;
+      entries.push({ field, name, spec });
+    }
+  }
+  return entries;
+}
+
+function findViolations(entries) {
+  const violations = [];
+  const exactEntries = [];
+  for (const entry of entries) {
+    if (typeof entry.spec === 'string' && EXACT_VERSION_RE.test(entry.spec)) {
+      exactEntries.push(entry);
+    } else {
+      violations.push({
+        ...entry,
+        rule: 'exact-version',
+        message:
+          'not an exact-version pin (operators, ranges, workspace specifiers, and wildcards are forbidden; expected e.g. "0.7.0")',
+      });
+    }
+  }
+  if (exactEntries.length > 1) {
+    const versions = new Set(exactEntries.map((entry) => entry.spec));
+    if (versions.size > 1) {
+      const observed = Array.from(versions).sort().join(', ');
+      for (const entry of exactEntries) {
+        violations.push({
+          ...entry,
+          rule: 'single-version',
+          message: `all @prisma-next/* entries must share the same exact version (observed: ${observed})`,
+        });
+      }
+    }
+  }
+  return violations;
+}
+
+function main() {
+  const pkg = readPackageJson();
+  const entries = collectEntries(pkg);
+  const violations = findViolations(entries);
+  if (violations.length === 0) {
+    exit(0);
+  }
+  const pkgName = typeof pkg.name === 'string' ? pkg.name : '<unnamed>';
+  stderr.write(`prisma-next-check-pins: ${violations.length} violation(s) in ${pkgName}\n`);
+  for (const v of violations) {
+    stderr.write(`  ${v.field}.${v.name} = ${JSON.stringify(v.spec)} — ${v.message}\n`);
+  }
+  exit(1);
+}
+
+main();

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@prisma-next/extension-author-tools",
+  "version": "0.8.0",
+  "license": "Apache-2.0",
+  "type": "module",
+  "description": "CLI tools that pair with the prisma-next-extension-upgrade agent skill — including `prisma-next-check-pins`, the CI guard that asserts every `@prisma-next/*` peerDep on an extension package is exact-version-pinned. Future tools for extension authors employing the upgrade skill ship from this package.",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "bin": {
+    "prisma-next-check-pins": "./bin/prisma-next-check-pins.mjs"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  },
+  "files": [
+    "README.md",
+    "bin"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/prisma/prisma-next.git",
+    "directory": "packages/0-shared/extension-author-tools"
+  }
+}