@prisma-next/cli 0.8.0-dev.4 → 0.8.0-dev.5

package/src/commands/init/agent-skill-install.ts

@@ -1,44 +1,109 @@
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
+import { version as cliVersion } from '../../../package.json' with { type: 'json' };
 import type { PackageManager } from './detect-package-manager';
 import { errorInitSkillInstallFailed } from './errors';
 
 const exec = promisify(execFile);
 
 /**
- * The npm package the agent-skill install dispatches to. Version-locked
- * to Prisma Next via the consumer project's `package.json`; the install
- * subprocess picks up whatever version is resolvable at install time.
+ * Default base for the GitHub-URL form `<owner>/<repo>` consumed by
+ * upstream `skills add`. Each `SkillSource` joins this base with its
+ * own subpath (and optional `#ref` for version-pinned clusters).
+ */
+export const DEFAULT_AGENT_SKILL_BASE = 'prisma/prisma-next';
+
+/**
+ * One discovery scope inside the Prisma Next monorepo. The CLI emits
+ * one `skills add <base>/<subpath>[#ref] --all` invocation per source
+ * during `init`.
+ *
+ * `ref` semantics:
+ * - `cli`: pin to the CLI's own package version (lockstep with the
+ *   skills' SPI). Used for the version-locked usage cluster — the
+ *   skills under `skills/<X>/SKILL.md`, which describe the public
+ *   package API and are pinned to the version of `@prisma-next/*`
+ *   currently installed in the consumer's project.
+ * - `null`: no ref. The cluster is "always-latest" — the cumulative
+ *   instruction set is the source of truth, and the latest revision
+ *   on `main` includes bug fixes for every prior transition. Used
+ *   for the upgrade and extension-author clusters.
+ */
+export interface SkillSource {
+  readonly subpath: string;
+  readonly ref: 'cli' | null;
+  readonly description: string;
+}
+
+export const DEFAULT_AGENT_SKILL_SOURCES: readonly SkillSource[] = [
+  {
+    subpath: 'skills',
+    ref: 'cli',
+    description: 'usage skills (version-locked to installed Prisma Next)',
+  },
+  {
+    subpath: 'skills/upgrade',
+    ref: null,
+    description: 'upgrade skill (always tracks `main`)',
+  },
+  {
+    subpath: 'skills/extension-author',
+    ref: null,
+    description: 'extension-author skill (always tracks `main`)',
+  },
+];
+
+/**
+ * Test-only escape hatch for pinning the install base to a local
+ * checkout. Production runs leave this unset, so installs always use
+ * `DEFAULT_AGENT_SKILL_BASE`.
  *
- * The skill is **always** installed at the project level — never the
- * user level — precisely so the skill version tracks the project's
- * Prisma Next version. A user-level (global) install of an
- * agent-skills CLI package would have to pick a single version for
- * every project on the host, which breaks the version-locking invariant
- * the rest of the framework relies on (skills, CLI, runtime, and
- * extension packs all ship at the same version per release).
+ * When set to an absolute filesystem path (typical for tests), the
+ * `#ref` fragment is dropped — local-path mode in upstream's CLI does
+ * not accept refs, and the local clone has whatever content the test
+ * checked into it anyway. When set to anything else (e.g. a fork name
+ * `myuser/prisma-next`), the ref policy is preserved.
+ */
+function resolveAgentSkillBase(): string {
+  const override = process.env['PRISMA_NEXT_SKILLS_BASE']?.trim();
+  return override && override.length > 0 ? override : DEFAULT_AGENT_SKILL_BASE;
+}
+
+function isLocalPath(base: string): boolean {
+  return base.startsWith('/') || /^[a-zA-Z]:[\\/]/.test(base);
+}
+
+/**
+ * Build the `<base>/<subpath>[#ref]` URL the `skills` CLI will
+ * resolve. Exported for unit tests so the per-source format can be
+ * asserted without going through the full install loop.
  */
-export const AGENT_SKILL_PACKAGE = '@prisma-next/skills';
+export function formatSkillSourceUrl(source: SkillSource): string {
+  const base = resolveAgentSkillBase();
+  const url = `${base}/${source.subpath}`;
+  if (source.ref === null) return url;
+  if (isLocalPath(base)) return url;
+  if (source.ref === 'cli') return `${url}#v${cliVersion}`;
+  return url;
+}
 
 /**
- * The skill-install command, formatted for the project's detected
- * package manager. `npx`/`pnpm dlx`/`bunx` are interchangeable to the
- * user; we pick the variant that matches the rest of the install step
- * so a single project consistently uses one runner.
+ * The skill-install command for one source, formatted for the
+ * project's detected package manager. `npx`/`pnpm dlx`/`bunx` are
+ * interchangeable to the user; we pick the variant that matches the
+ * rest of the install step so a single project consistently uses one
+ * runner.
  *
  * `--all` auto-selects every skill in the cluster and every detected
  * agent runtime, skipping the multi-select prompts the `skills` CLI
  * shows by default. A non-interactive scaffold step cannot present
- * prompts, and the cluster is designed to be installed as a unit (the
- * router skill routes between the workflow-scoped siblings). Users who
- * want a narrower install run `npx skills add @prisma-next/skills`
- * themselves after `init` with the flags they want.
+ * prompts.
  *
  * Exported for unit tests so the per-PM dispatch can be asserted
  * without a live subprocess.
  */
-export function formatSkillInstallCommand(pm: PackageManager): string {
-  const args = ['skills', 'add', AGENT_SKILL_PACKAGE, '--all'];
+export function formatSkillInstallCommand(pm: PackageManager, source: SkillSource): string {
+  const args = ['skills', 'add', formatSkillSourceUrl(source), '--all'];
   switch (pm) {
     case 'pnpm':
       return `pnpm dlx ${args.join(' ')}`;
@@ -69,31 +134,37 @@ function commandToExec(command: string): {
 }
 
 /**
- * Runs the project-level skill install. Returns `{ ok: true, command }`
- * on success; throws a structured `errorInitSkillInstallFailed` on
- * failure. The throw is intentionally fatal — project-level skill
- * install is unconditional (modulo `--no-skill`) and the user opted
- * into Prisma Next by running `init`. A silent skip would defeat the
- * onboarding-to-zero contract.
+ * Runs the project-level skill install for every source in
+ * `DEFAULT_AGENT_SKILL_SOURCES`, in order. Returns
+ * `{ ok: true, commands }` on success; throws a structured
+ * `errorInitSkillInstallFailed` on the first failure (subsequent
+ * sources are not attempted — the user opted into Prisma Next by
+ * running `init` and a partial install would leave the project in an
+ * ambiguous state). The throw is intentionally fatal — project-level
+ * skill install is unconditional (modulo `--no-skill`).
  */
 export async function runProjectLevelSkillInstall(ctx: {
   readonly baseDir: string;
   readonly pm: PackageManager;
   readonly filesWritten: readonly string[];
-}): Promise<{ readonly ok: true; readonly command: string }> {
-  const command = formatSkillInstallCommand(ctx.pm);
-  const { file, args } = commandToExec(command);
-  try {
-    await exec(file, args, { cwd: ctx.baseDir });
-    return { ok: true, command };
-  } catch (err) {
-    throw errorInitSkillInstallFailed({
-      skillInstallCommand: command,
-      filesWritten: ctx.filesWritten,
-      cause:
-        redactSecrets(readChildStderr(err)) || (err instanceof Error ? err.message : String(err)),
-    });
+}): Promise<{ readonly ok: true; readonly commands: readonly string[] }> {
+  const commands: string[] = [];
+  for (const source of DEFAULT_AGENT_SKILL_SOURCES) {
+    const command = formatSkillInstallCommand(ctx.pm, source);
+    const { file, args } = commandToExec(command);
+    try {
+      await exec(file, args, { cwd: ctx.baseDir });
+      commands.push(command);
+    } catch (err) {
+      throw errorInitSkillInstallFailed({
+        skillInstallCommand: command,
+        filesWritten: ctx.filesWritten,
+        cause:
+          redactSecrets(readChildStderr(err)) || (err instanceof Error ? err.message : String(err)),
+      });
+    }
   }
+  return { ok: true, commands };
 }
 
 function readChildStderr(err: unknown): string {
@@ -125,6 +196,6 @@ export function redactSecrets(stderr: string): string {
 /**
  * Hand-rolled skill stub path that init must not leave behind. Removed
  * on every init run so a project's `.agents/skills/prisma-next/` does
- * not shadow the published `@prisma-next/skills` package.
+ * not shadow the installed Prisma Next skill cluster.
  */
 export const LEGACY_SKILL_FILE = '.agents/skills/prisma-next/SKILL.md';

package/src/commands/init/errors.ts

@@ -239,7 +239,7 @@ export function errorInitEmitFailed(options: {
 
 /**
  * The project-level agent-skill install (`npx skills add
- * @prisma-next/skills`) failed after a successful dependency
+ * prisma/prisma-next#v<version>`) failed after a successful dependency
  * install + emit. The project's scaffold remains on disk; the user
  * can either fix the underlying issue (network, registry, PATH) and
  * run the install command manually, or re-run `init --no-skill` to
@@ -253,7 +253,7 @@ export function errorInitSkillInstallFailed(options: {
   readonly filesWritten: readonly string[];
   readonly cause: string;
 }): CliStructuredError {
-  return new CliStructuredError('5013', 'Failed to install @prisma-next/skills', {
+  return new CliStructuredError('5013', 'Failed to install Prisma Next skills', {
     domain: 'CLI',
     why: `\`${options.skillInstallCommand}\` exited with an error: ${options.cause}`,
     fix:

package/src/commands/init/exit-codes.ts

@@ -62,8 +62,8 @@ export const INIT_EXIT_INSTALL_FAILED = 4;
 export const INIT_EXIT_EMIT_FAILED = 5;
 
 /**
- * The project-level `@prisma-next/skills` install (`npx skills add
- * @prisma-next/skills`) failed after a successful dependency
+ * The project-level Prisma Next skills install (`npx skills add
+ * prisma/prisma-next#v<version>`) failed after a successful dependency
  * install + emit. The scaffolded project files remain on disk; the
  * user can fix the underlying issue (network, registry reachability,
  * `npx skills` not on PATH) and run the install manually, or re-run

package/src/commands/init/index.ts

@@ -89,7 +89,7 @@ export function createInitCommand(): Command {
     .option('--no-install', 'Skip dependency installation and contract emission')
     .option(
       '--no-skill',
-      'Skip the @prisma-next/skills install (air-gapped CI, restricted registries, etc.)',
+      'Skip Prisma Next skills install (air-gapped CI, restricted registries, etc.)',
     )
     .action(async (options: InitCommandOptions) => {
       const { runInit } = await import('./init');

package/src/commands/init/init.ts

@@ -8,6 +8,7 @@ import { formatErrorJson, formatErrorOutput } from '../../utils/formatters/error
 import type { GlobalFlags } from '../../utils/global-flags';
 import { TerminalUI } from '../../utils/terminal-ui';
 import {
+  DEFAULT_AGENT_SKILL_SOURCES,
   formatSkillInstallCommand,
   LEGACY_SKILL_FILE,
   runProjectLevelSkillInstall,
@@ -182,7 +183,7 @@ export async function runInit(
   // and missing-on-disk-at-write-time is tolerated.
   const filesToDelete: string[] = inputs.reinit ? [...findStaleArtefacts(baseDir, schemaDir)] : [];
 
-  // `init` delegates the skill to `npx skills add @prisma-next/skills`,
+  // `init` delegates the skill to `npx skills add prisma/prisma-next#v<version>`,
   // so a hand-rolled `.agents/skills/prisma-next/SKILL.md` in the project
   // would shadow the published package. Queue it for deletion on every
   // run (not gated on `--reinit`).
@@ -449,26 +450,31 @@ export async function runInit(
   // potentially fails. We skip the install when the user passed
   // `--no-install` for the same reason — no `node_modules` means the
   // workspace isn't ready to consume the skill yet anyway.
-  const manualProjectSkillCommand = formatSkillInstallCommand(install.effectivePm);
+  const manualProjectSkillCommands = DEFAULT_AGENT_SKILL_SOURCES.map((source) =>
+    formatSkillInstallCommand(install.effectivePm, source),
+  );
+  const manualProjectSkillSummary = manualProjectSkillCommands.map((c) => `\`${c}\``).join(' && ');
   let skillRegistered = false;
   if (!inputs.installProjectSkill) {
     warnings.push(
-      `Skipped @prisma-next/skills install (--no-skill). To install later, run \`${manualProjectSkillCommand}\` in this project.`,
+      `Skipped Prisma Next agent-skill install (--no-skill). To install the skills later, run: ${manualProjectSkillSummary}`,
     );
   } else if (install.skipped) {
     warnings.push(
-      `Skipped @prisma-next/skills install because --no-install was passed. Once you run install manually, register the skill with \`${manualProjectSkillCommand}\`.`,
+      `Skipped Prisma Next agent-skill install because --no-install was passed. After you run install manually, install the skills with: ${manualProjectSkillSummary}`,
     );
   } else {
     const spinner = ui.spinner();
-    spinner.start('Registering @prisma-next/skills with the agent runtime...');
+    spinner.start('Registering Prisma Next skills with the agent runtime...');
     try {
       const project = await runProjectLevelSkillInstall({
         baseDir,
         pm: install.effectivePm,
         filesWritten,
       });
-      spinner.stop(`Registered @prisma-next/skills (project level) — ran \`${project.command}\``);
+      spinner.stop(
+        `Registered Prisma Next skills (project level) — ran ${project.commands.map((c) => `\`${c}\``).join(', ')}`,
+      );
       skillRegistered = true;
     } catch (error) {
       spinner.stop('Agent-skill install failed');

package/src/commands/init/inputs.ts

@@ -69,7 +69,7 @@ export interface ResolvedInitInputs {
    */
   readonly removePreviousFacade: string | null;
   /**
-   * Whether to run `npx skills add @prisma-next/skills` at the
+   * Whether to run `npx skills add prisma/prisma-next#v<version>` at the
    * project level after install + emit. True by default; `--no-skill`
    * sets it to `false`. The skill is always project-level (never
    * user-level / global) so its version stays locked to the project's

package/src/commands/init/output.ts

@@ -121,7 +121,7 @@ export function buildNextSteps(options: {
   readonly emitCommand: string;
   readonly schemaPath: string;
   /**
-   * Whether the project-level `@prisma-next/skills` install actually ran
+   * Whether the project-level Prisma Next skills install actually ran
    * and succeeded during this `init`. When false (the user passed
    * `--no-skill` or `--no-install`, so the install was skipped), the
    * "registered with your agent runtime" step is omitted — the skip is
@@ -145,7 +145,7 @@ export function buildNextSteps(options: {
   push('Open prisma-next.md for a quick reference on how to write your first typed query.');
   if (options.skillRegistered) {
     push(
-      '@prisma-next/skills is registered with your agent runtime — open the project in your IDE and ask the agent to add a model, run a query, or plan a migration.',
+      'Prisma Next skills are registered with your agent runtime — open the project in your IDE and ask the agent to add a model, run a query, or plan a migration.',
     );
   }
   return steps;