fix(plugin-cli): improve profile release setup UX (#3117)

* fix(plugin-cli): clarify profile release setup

* docs: explain plugin profile setup flow

* docs: explain CLI installation

Author: ascorbic

.changeset/plugin-profile-setup-ux.md

@@ -0,0 +1,5 @@
+---
+"@emdash-cms/plugin-cli": patch
+---
+
+Improves package-profile and automated-release setup: missing manifests point to the plugin-directory command, GitHub repository prompts use a detected `origin` remote, setup failures omit stack traces, and a published profile shows both manual and GitHub Actions release commands.

docs/src/content/docs/plugins/creating-plugins/cli.mdx

@@ -9,6 +9,16 @@ import { Steps } from "@astrojs/starlight/components";
 
 The CLI uses an [Atmosphere account](/plugins/creating-plugins/publishing/#your-atmosphere-account) as the publisher identity for package profiles and releases.
 
+## Install the CLI
+
+Plugins created with `pnpm dlx @emdash-cms/plugin-cli init` already include the CLI as a pinned development dependency. Add it to an existing plugin before using the other commands:
+
+```sh
+pnpm add -D @emdash-cms/plugin-cli
+```
+
+The examples use `pnpm exec emdash-plugin` so each command runs the version installed in the plugin. Use `pnpm dlx` for the one-off `init` command, not for repeated build, login, or release commands.
+
 ## Commands
 
 The CLI provides the following commands:
@@ -51,7 +61,7 @@ The following example shows the two scripts most plugins add to `package.json`:
 Create a new plugin with `init`:
 
 ```sh
-npx @emdash-cms/plugin-cli init my-plugin
+pnpm dlx @emdash-cms/plugin-cli init my-plugin
 ```
 
 This scaffolds `emdash-plugin.jsonc`, `src/plugin.ts`, `package.json`, `tsconfig.json`, `vitest.config.ts`, a workerd-backed test, a README, `AGENTS.md`, a local `creating-plugins` skill, and package-manager configuration. `.agents/skills` and `.claude/skills` link to the canonical `skills` directory, and `.claude/CLAUDE.md` links to `AGENTS.md`, so Codex and Claude use the same project guidance. The source starts with one route assigned to a `SandboxedPlugin`-typed constant and exported as default. The test invokes that route through EmDash's production sandbox wrapper and host bridge.
@@ -63,7 +73,7 @@ The CLI detects whether npm, pnpm, Yarn, or Bun launched it and generates matchi
 Non-interactive setup requires explicit ownership metadata. Use the following form in scripts:
 
 ```sh
-npx @emdash-cms/plugin-cli init my-plugin --yes \
+pnpm dlx @emdash-cms/plugin-cli init my-plugin --yes \
   --publisher did:plc:abc123def456 \
   --author-name "Jane Doe" \
   --security-email security@example.com
@@ -150,7 +160,7 @@ The write uses the current record CID as a precondition. If another process chan
 
 `profile setup` prepares the publisher-owned package profile for automated releases. It creates a missing profile from `emdash-plugin.jsonc`, or adds delegated-release settings to an existing valid profile without replacing its package metadata.
 
-Run the interactive setup from the plugin directory:
+Run the interactive setup from the plugin directory. From elsewhere in a monorepo, pass `--dir <plugin-directory>`:
 
 ```sh
 emdash-plugin profile setup
@@ -159,15 +169,15 @@ emdash-plugin profile setup
 | Flag | Default | Description |
 | --- | --- | --- |
 | `--dir <path>` | Current directory | Plugin source directory. |
-| `--repository <url>` | Manifest `repo` | Canonical public GitHub repository URL. Interactive setup asks when neither value is present. |
+| `--repository <url>` | Manifest `repo`, then Git `origin` | Canonical public GitHub repository URL. Interactive setup pre-fills a detected GitHub remote or asks when none is available. |
 | `--confirmation <mode>` | `escalation-only` | Use `escalation-only` for permission increases or `always` for every release. |
 | `--yes`, `-y` | `false` | Accept the default policy without prompting. Required when a non-interactive run would change the profile. |
 
-The command uses the active CLI login to write the profile. It refuses to replace a different signed repository. Run `emdash-plugin switch <did>` when the active account does not match the manifest publisher.
+The command uses the active CLI login to write the profile. It refuses to replace a different signed repository. Run `emdash-plugin switch <did>` when the active account does not match the manifest publisher. After publishing the profile, it shows `emdash-plugin publish` for a manual release and `emdash-plugin release setup` for GitHub Actions.
 
 ## `release setup`
 
-`release setup` runs package-profile setup, then creates one shared `.github/workflows/emdash-release.yml` at the Git repository root. Nested plugin packages reuse the same workflow.
+`release setup` runs package-profile setup from one plugin directory, then creates one shared `.github/workflows/emdash-release.yml` at the Git repository root. Nested plugin packages reuse the same workflow. Run it from a plugin directory or pass `--dir <plugin-directory>`; the repository root does not identify which package profile to prepare.
 
 ```sh
 emdash-plugin release setup

docs/src/content/docs/plugins/creating-plugins/delegated-releases.mdx

@@ -21,7 +21,8 @@ Use [`emdash-plugin publish`](/plugins/creating-plugins/publishing/#publish) for
 Prepare the following before starting:
 
 - A public GitHub repository containing a sandboxed EmDash plugin.
-- A valid [`emdash-plugin.jsonc`](/plugins/creating-plugins/manifest/) with `slug`, `publisher`, `license`, an author, and a security contact. Set `repo` to the canonical GitHub URL, or enter it during interactive setup.
+- `@emdash-cms/plugin-cli` installed as a development dependency. Plugins created with the CLI already include it.
+- A valid [`emdash-plugin.jsonc`](/plugins/creating-plugins/manifest/) with `slug`, `publisher`, `license`, an author, and a security contact. Set `repo` to the canonical GitHub URL, or confirm the detected GitHub remote during interactive setup.
 - A version in `package.json`, or in `emdash-plugin.jsonc` for a registry-only plugin.
 - The Atmosphere account named by `publisher`.
 - A browser that supports passkeys. Release approval requires user verification.
@@ -44,14 +45,16 @@ pnpm exec emdash-plugin validate
 
    The CLI stores this local publishing session outside the project. GitHub Actions never receives it.
 
-2. Prepare the package profile and generate the workflow.
+2. Prepare the package profile and generate the workflow from the plugin directory.
 
    ```sh
    pnpm exec emdash-plugin release setup
    ```
 
    The command reads the package metadata from `emdash-plugin.jsonc`. If the package profile is missing, it offers to create it. If the profile exists without delegated-release settings, it offers to add them while preserving the existing package metadata.
 
+   In a monorepo, run the command inside the plugin package or pass `--dir <plugin-directory>`. If the manifest does not contain `repo`, setup detects the GitHub `origin` remote and pre-fills the repository prompt.
+
    Setup asks when a release needs approval:
 
    - **When plugin permissions increase** is the default. A release waits for approval when its declared access expands relative to the latest release.
@@ -65,7 +68,9 @@ pnpm exec emdash-plugin validate
    pnpm exec emdash-plugin profile setup
    ```
 
-   In a non-interactive terminal, pass `--yes` to accept the default approval policy. Pass `--repository <https-url>` when the manifest does not contain `repo`, and `--confirmation always` to require approval for every release.
+   After publishing the package profile, this command shows the manual and GitHub Actions release commands.
+
+   In a non-interactive terminal, pass `--yes` to accept the default approval policy. Pass `--repository <https-url>` when neither the manifest nor Git remote supplies the repository, and `--confirmation always` to require approval for every release.
 
 3. Review and commit the generated workflow.
 

packages/plugin-cli/README.md

@@ -7,15 +7,23 @@ CLI for authoring, building, and publishing EmDash plugins.
 ## Installation
 
 ```sh
-npx @emdash-cms/plugin-cli init my-plugin
+pnpm dlx @emdash-cms/plugin-cli init my-plugin
 ```
 
 Interactive setup collects the required publisher, author, and security metadata, detects the invoking package manager, and shows a project summary before writing. The scaffold includes a workerd-backed Vitest host, `AGENTS.md`, a canonical `skills/creating-plugins` skill shared through `.agents/skills` and `.claude/skills` symlinks, a Claude instruction link, package scripts for every validation and publishing command, and pnpm build-script policy when pnpm is selected.
 
+The generated plugin includes `@emdash-cms/plugin-cli` as a pinned development dependency. Add it before using the CLI in an existing plugin:
+
+```sh
+pnpm add -D @emdash-cms/plugin-cli
+```
+
+Run project commands with `pnpm exec emdash-plugin`. This uses the version pinned by the plugin instead of downloading a potentially different version for each command.
+
 Non-interactive setup requires explicit ownership metadata:
 
 ```sh
-npx @emdash-cms/plugin-cli init my-plugin --yes \
+pnpm dlx @emdash-cms/plugin-cli init my-plugin --yes \
   --publisher did:plc:abc123def456 \
   --author-name "Jane Doe" \
   --security-email security@example.com
@@ -118,16 +126,16 @@ On first publish, pass `--license` and `--security-email` (or `--security-url`)
 
 See [Automated plugin releases](https://docs.emdashcms.com/plugins/creating-plugins/delegated-releases/) for the complete publisher journey, including release-service authorisation, first-run repository approval, passkeys, and troubleshooting.
 
-Run the setup command from a public GitHub repository containing an EmDash plugin:
+Run the setup command from the plugin directory, not the monorepo root. Pass `--dir <plugin-directory>` when running it from elsewhere:
 
 ```sh
-emdash-plugin login <handle-or-did>
-emdash-plugin release setup
+pnpm exec emdash-plugin login <handle-or-did>
+pnpm exec emdash-plugin release setup
 ```
 
 The command reads the plugin metadata and publisher from `emdash-plugin.jsonc`. If the package profile does not exist, it offers to create it. If the profile predates delegated releases, it offers to add the signed repository and release policy while preserving the existing package metadata. The default policy requires the publisher's [Atmosphere account](https://docs.emdashcms.com/plugins/creating-plugins/publishing/#your-atmosphere-account) to approve releases when plugin permissions increase. Choose the every-release option to require approval each time.
 
-Set `repo` in `emdash-plugin.jsonc`, or enter the canonical GitHub repository URL when prompted. The standalone `emdash-plugin profile setup` command prepares only the package profile.
+Set `repo` in `emdash-plugin.jsonc`, or confirm the canonical GitHub repository URL when prompted. If the manifest omits `repo`, setup detects a GitHub `origin` remote and uses it as the prompt default. The standalone `emdash-plugin profile setup` command prepares only the package profile, then shows the commands for publishing a release manually or configuring GitHub Actions.
 
 Both setup commands accept `--repository <url>`, `--confirmation escalation-only|always`, and `--yes`. `release setup` also accepts `--service-url`, `--action-ref`, `--trigger auto|changesets|tags|manual`, and `--force` for the generated workflow. The default hosted service is `https://releases.emdashcms.com`.
 

packages/plugin-cli/src/build/pipeline.ts

@@ -130,7 +130,7 @@ export async function resolveSources(
 	if (!(await fileExists(manifestPath))) {
 		throw new BuildPipelineError(
 			"MISSING_MANIFEST",
-			`No ${MANIFEST_FILENAME} found in ${resolvedDir}. Scaffold one with: emdash-plugin init`,
+			`No ${MANIFEST_FILENAME} found in ${resolvedDir}. Run this command from a plugin directory, or pass --dir <plugin-directory>.`,
 		);
 	}
 

packages/plugin-cli/src/commands/profile.ts

@@ -8,6 +8,7 @@ import consola from "consola";
 import pc from "picocolors";
 
 import { resolveSources } from "../build/pipeline.js";
+import { probeEnvironment } from "../init/environment.js";
 import { resolveHandleToDid } from "../manifest/publisher.js";
 import { manifestToProfileInput, resolveSections } from "../manifest/translate.js";
 import { resumeSession } from "../oauth.js";
@@ -22,34 +23,78 @@ export interface RunProfileSetupOptions {
 	repository?: string;
 	confirmation?: string;
 	yes?: boolean;
+	nextSteps?: boolean;
 }
 
 function cancelled(value: unknown): asserts value is Exclude<typeof value, symbol> {
 	if (clack.isCancel(value))
 		throw new PackageProfileSetupError("INVALID_INPUT", "Setup cancelled.");
 }
 
-async function repositoryValue(
-	configured: string | undefined,
-	interactive: boolean,
+interface RepositoryPromptOptions {
+	message: string;
+	defaultValue?: string;
+	placeholder: string;
+	validate(value: string | undefined): string | undefined;
+}
+
+export interface ResolveProfileRepositoryOptions {
+	configured: string | undefined;
+	interactive: boolean;
+	pluginDir: string;
+	prompt?: (options: RepositoryPromptOptions) => Promise<unknown>;
+}
+
+export async function resolveProfileRepository(
+	options: ResolveProfileRepositoryOptions,
 ): Promise<string> {
-	if (configured) return configured;
-	if (!interactive) {
+	if (options.configured) return options.configured;
+	const environment = await probeEnvironment(options.pluginDir);
+	const detected = environment.repo
+		? (canonicalGitHubRepository(environment.repo) ?? undefined)
+		: undefined;
+	if (!options.interactive) {
+		if (detected) return detected;
 		throw new PackageProfileSetupError(
 			"INVALID_REPOSITORY",
 			"Add `repo` to emdash-plugin.jsonc or pass --repository with an HTTPS GitHub repository URL.",
 		);
 	}
-	const answer = await clack.text({
-		message: "GitHub repository URL",
-		placeholder: "https://github.com/example/gallery",
+	const prompt = options.prompt ?? ((input) => clack.text(input));
+	const answer = await prompt({
+		message: detected
+			? "GitHub repository URL (press enter to use the detected origin)"
+			: "GitHub repository URL",
+		...(detected === undefined ? {} : { defaultValue: detected }),
+		placeholder: detected ?? "https://github.com/example/gallery",
 		validate: (value) =>
 			canonicalGitHubRepository(value ?? "") ? undefined : "Enter an HTTPS GitHub repository URL.",
 	});
 	cancelled(answer);
 	return String(answer);
 }
 
+export function printProfileSetupResult(
+	result: { status: "created" | "ready" | "updated"; profileUri: string },
+	confirmation: "always" | "escalation-only",
+	showNextSteps: boolean,
+): void {
+	if (result.status === "ready") {
+		consola.success(`Package profile is ready: ${pc.dim(result.profileUri)}`);
+	} else {
+		consola.success(`Published package profile: ${pc.dim(result.profileUri)}`);
+		consola.info(
+			confirmation === "always"
+				? "Your Atmosphere account must approve every release."
+				: "Your Atmosphere account must approve releases when plugin permissions increase.",
+		);
+	}
+	if (!showNextSteps) return;
+	consola.info("Next, publish a release:");
+	consola.info(`  Manually: ${pc.cyan("emdash-plugin publish")}`);
+	consola.info(`  With GitHub Actions: ${pc.cyan("emdash-plugin release setup")}`);
+}
+
 async function confirmationValue(
 	configured: string | undefined,
 	interactive: boolean,
@@ -111,10 +156,11 @@ async function runProfileSetupInternal(options: RunProfileSetupOptions): Promise
 			`The active CLI account does not own ${sources.manifest.slug}. Run \`emdash-plugin switch ${publisherDid}\` first.`,
 		);
 	}
-	const repository = await repositoryValue(
-		options.repository ?? sources.manifest.repo,
+	const repository = await resolveProfileRepository({
+		configured: options.repository ?? sources.manifest.repo,
 		interactive,
-	);
+		pluginDir: sources.pluginDir,
+	});
 	const confirmation = await confirmationValue(options.confirmation, interactive);
 	const loaded = await import("../manifest/load.js").then(({ loadManifest }) =>
 		loadManifest(sources.manifestPath),
@@ -135,7 +181,7 @@ async function runProfileSetupInternal(options: RunProfileSetupOptions): Promise
 	};
 	const proposed = await setupPackageProfile(input);
 	if (proposed.status === "ready") {
-		consola.success(`Package profile is ready: ${pc.dim(proposed.profileUri)}`);
+		printProfileSetupResult(proposed, confirmation, options.nextSteps !== false);
 		return;
 	}
 	if (!interactive && options.yes !== true) {
@@ -159,14 +205,7 @@ async function runProfileSetupInternal(options: RunProfileSetupOptions): Promise
 		}
 	}
 	const result = await setupPackageProfile({ ...input, apply: true });
-	consola.success(
-		`${result.status === "created" ? "Created" : "Updated"} package profile: ${pc.dim(result.profileUri)}`,
-	);
-	consola.info(
-		confirmation === "always"
-			? "Your Atmosphere account must approve every release."
-			: "Your Atmosphere account must approve releases when plugin permissions increase.",
-	);
+	printProfileSetupResult(result, confirmation, options.nextSteps !== false);
 }
 
 export async function runProfileSetup(options: RunProfileSetupOptions): Promise<void> {

packages/plugin-cli/src/release-setup.ts

@@ -11,7 +11,6 @@ import { resolveSources } from "./build/pipeline.js";
 import { runProfileSetup } from "./commands/profile.js";
 import { resolveHandleToDid } from "./manifest/publisher.js";
 import { installedCliVersion } from "./package-version.js";
-import { PackageProfileSetupError } from "./profile/setup.js";
 import { findRepositoryRoot } from "./release-prepare.js";
 
 export const DEFAULT_RELEASE_SERVICE_URL = "https://releases.emdashcms.com";
@@ -623,6 +622,7 @@ export const releaseSetupCommand = defineCommand({
 						repository: args.repository,
 						confirmation: args.confirmation,
 						yes: args.yes,
+						nextSteps: false,
 					}),
 			});
 			for (const warning of result.warnings) consola.warn(warning);
@@ -641,11 +641,8 @@ export const releaseSetupCommand = defineCommand({
 			);
 			consola.info("The first run links this repository workflow in the release dashboard.");
 		} catch (error) {
-			if (error instanceof ReleaseSetupError || error instanceof PackageProfileSetupError) {
-				consola.error(error.message);
-				process.exit(1);
-			}
-			throw error;
+			consola.error(error instanceof Error ? error.message : "Release setup failed.");
+			process.exit(1);
 		}
 	},
 });

packages/plugin-cli/tests/cli-errors.test.ts

@@ -0,0 +1,37 @@
+import { execFile } from "node:child_process";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { expect, it } from "vitest";
+
+const CLI = fileURLToPath(new URL("../dist/index.mjs", import.meta.url));
+
+function runCli(args: string[], cwd: string) {
+	return new Promise<{ code: number | string | undefined; output: string }>((resolve) => {
+		execFile(
+			process.execPath,
+			[CLI, ...args],
+			{ cwd, env: { ...process.env, NO_COLOR: "1" } },
+			(error, stdout, stderr) => {
+				resolve({ code: error?.code, output: `${stdout}${stderr}` });
+			},
+		);
+	});
+}
+
+it("reports a missing plugin directory without a stack trace", async () => {
+	const dir = await mkdtemp(join(tmpdir(), "emdash-release-setup-root-"));
+	try {
+		const result = await runCli(["release", "setup", "--yes"], dir);
+
+		expect(result.code).toBe(1);
+		expect(result.output).toContain("Run this command from a plugin directory");
+		expect(result.output).toContain("--dir <plugin-directory>");
+		expect(result.output).not.toContain("BuildPipelineError");
+		expect(result.output).not.toMatch(/\n\s+at /);
+	} finally {
+		await rm(dir, { recursive: true, force: true });
+	}
+});