feat(create)!: switch manifest-entry syntax from @org/name to @org:name

fengmk2 · fengmk2 · commit c441ba69f9f9 · 2026-04-25T11:08:08.000+08:00
BREAKING (unpublished feature): the manifest-entry selector uses `:` instead of `/`. `vp create @your-org:web` now picks the `web` entry from `@your-org/create`'s `createConfig.templates` manifest. The old `@your-org/web` form is no longer a manifest lookup — it reverts to the pre-feature `expandCreateShorthand` path that turns it into `@your-org/create-web`, exactly as it worked before this feature. Rationale (cpojer + fengmk2, PR #1398 review): the `/` form collides with real npm packages. If `@your-org/web` exists on npm as a genuine package, `vp create @your-org/web` would silently prefer the manifest entry over the real package — confusing, and fragile. The `:` separator mirrors the existing `vite:monorepo` / `vite:library` builtin-template syntax, which users already read as "namespace:entry". It also keeps manifest entries lexically distinct from any real npm package path. Miss behavior: `vp create @org:foo` where `foo` isn't in the manifest (or the manifest is absent) is a HARD ERROR listing the available entries. No silent fall-through — the `:` form is an explicit manifest lookup, and the fallback shorthand is reserved for the `/` form. Updated: `parseOrgScopedSpec` parses only `@scope` and `@scope:name` (returns `null` for `@scope/anything`), `resolveOrgManifestForCreate` errors on direct-selection miss, CLI help text, RFC command matrix + examples + error-handling table + compatibility section, docs guide + config page, snap-test fixture commands (`create-org-bundled`, `create-org-monorepo-direct-in-monorepo`), `--no-interactive` hint line, and unit tests for `parseOrgScopedSpec` (new test pinning the null return for the `/` form).
diff --git a/docs/config/create.md b/docs/config/create.md
@@ -16,7 +16,7 @@ export default defineConfig({
 });
 ```
 
-Any value accepted by `vp create` as a first argument works here — `@your-org` for an org picker, `@your-org/web` for a direct manifest entry, `vite:application` for a built-in, etc.
+Any value accepted by `vp create` as a first argument works here — `@your-org` for an org picker, `@your-org:web` for a direct manifest entry, `vite:application` for a built-in, etc.
 
 ## Precedence
 
diff --git a/docs/guide/create.md b/docs/guide/create.md
@@ -98,7 +98,7 @@ An organization can publish a curated set of templates under a single npm scope
 vp create @your-org
 
 # Run a specific manifest entry directly
-vp create @your-org/web
+vp create @your-org:web
 
 # Set the org as the default for a repo (see create.defaultTemplate config)
 vp create
@@ -171,7 +171,7 @@ Each entry supports:
 
 | Field         | Required | Notes                                                                                                                                                                                                                                        |
 | ------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `name`        | yes      | Kebab-case identifier. Used by `vp create @org/<name>` for direct selection. Must be unique within the array.                                                                                                                                |
+| `name`        | yes      | Kebab-case identifier. Used by `vp create @org:<name>` for direct selection. Must be unique within the array.                                                                                                                                |
 | `description` | yes      | One-line description shown in the picker.                                                                                                                                                                                                    |
 | `template`    | yes      | An npm specifier (`@org/template-foo`, optionally `@version`), a GitHub URL (`github:user/repo`), a `vite:*` builtin, a local workspace package name, or a relative path (`./templates/foo`) that resolves against the `@org/create` root. |
 | `keywords`    | no       | Filter terms for picker search.                                                                                                                                                                                                              |
@@ -215,7 +215,7 @@ Available templates in @your-org/create:
 
 Examples:
   # Scaffold a specific template from the org
-  vp create @your-org/web --no-interactive
+  vp create @your-org:web --no-interactive
 
   # Or use a Vite+ built-in template
   vp create vite:application --no-interactive
diff --git a/packages/cli/snap-tests/create-org-bundled/snap.txt b/packages/cli/snap-tests/create-org-bundled/snap.txt
@@ -1,4 +1,4 @@
-> node $SNAP_CASES_DIR/.shared/mock-npm-registry.mjs -- vp create @your-org/demo --no-interactive --directory my-demo-app # bundled template: extract tarball, copy subdir
+> node $SNAP_CASES_DIR/.shared/mock-npm-registry.mjs -- vp create @your-org:demo --no-interactive --directory my-demo-app # bundled template: extract tarball, copy subdir
 
 selected 'demo' from @your-org/create
 ◇ Scaffolded my-demo-app
diff --git a/packages/cli/snap-tests/create-org-bundled/steps.json b/packages/cli/snap-tests/create-org-bundled/steps.json
@@ -1,6 +1,6 @@
 {
   "commands": [
-    "node $SNAP_CASES_DIR/.shared/mock-npm-registry.mjs -- vp create @your-org/demo --no-interactive --directory my-demo-app # bundled template: extract tarball, copy subdir",
+    "node $SNAP_CASES_DIR/.shared/mock-npm-registry.mjs -- vp create @your-org:demo --no-interactive --directory my-demo-app # bundled template: extract tarball, copy subdir",
     "cat my-demo-app/package.json # verify package.json name was rewritten",
     "cat my-demo-app/src/index.ts # verify bundled source copied",
     "ls my-demo-app/README.md # verify README copied"
diff --git a/packages/cli/snap-tests/create-org-config-default/snap.txt b/packages/cli/snap-tests/create-org-config-default/snap.txt
@@ -9,7 +9,7 @@ Available templates in @your-org/create:
 
 Examples:
   # Scaffold a specific template from the org
-  vp create @your-org/web --no-interactive
+  vp create @your-org:web --no-interactive
 
   # Or use a Vite+ built-in template
   vp create vite:application --no-interactive
diff --git a/packages/cli/snap-tests/create-org-monorepo-direct-in-monorepo/snap.txt b/packages/cli/snap-tests/create-org-monorepo-direct-in-monorepo/snap.txt
@@ -1,4 +1,4 @@
-[1]> node $SNAP_CASES_DIR/.shared/mock-npm-registry.mjs -- vp create @your-org/monorepo --no-interactive # direct-selecting a monorepo entry inside a monorepo -> refuse
+[1]> node $SNAP_CASES_DIR/.shared/mock-npm-registry.mjs -- vp create @your-org:monorepo --no-interactive # direct-selecting a monorepo entry inside a monorepo -> refuse
 
 You are already in a monorepo workspace.
 Use a different template or run this command outside the monorepo
diff --git a/packages/cli/snap-tests/create-org-monorepo-direct-in-monorepo/steps.json b/packages/cli/snap-tests/create-org-monorepo-direct-in-monorepo/steps.json
@@ -1,5 +1,5 @@
 {
   "commands": [
-    "node $SNAP_CASES_DIR/.shared/mock-npm-registry.mjs -- vp create @your-org/monorepo --no-interactive # direct-selecting a monorepo entry inside a monorepo -> refuse"
+    "node $SNAP_CASES_DIR/.shared/mock-npm-registry.mjs -- vp create @your-org:monorepo --no-interactive # direct-selecting a monorepo entry inside a monorepo -> refuse"
   ]
 }
diff --git a/packages/cli/snap-tests/create-org-monorepo-filter/snap.txt b/packages/cli/snap-tests/create-org-monorepo-filter/snap.txt
@@ -12,7 +12,7 @@ Available templates in @your-org/create:
 
 Examples:
   # Scaffold a specific template from the org
-  vp create @your-org/web --no-interactive
+  vp create @your-org:web --no-interactive
 
   # Or use a Vite+ built-in template
   vp create vite:application --no-interactive
diff --git a/packages/cli/snap-tests/create-org-no-interactive-error/snap.txt b/packages/cli/snap-tests/create-org-no-interactive-error/snap.txt
@@ -10,7 +10,7 @@ Available templates in @your-org/create:
 
 Examples:
   # Scaffold a specific template from the org
-  vp create @your-org/web --no-interactive
+  vp create @your-org:web --no-interactive
 
   # Or use a Vite+ built-in template
   vp create vite:application --no-interactive
diff --git a/packages/cli/src/create/__tests__/org-manifest.spec.ts b/packages/cli/src/create/__tests__/org-manifest.spec.ts
@@ -24,16 +24,22 @@ describe('parseOrgScopedSpec', () => {
     expect(parseOrgScopedSpec('@your-org@latest')).toEqual({ scope: '@your-org' });
   });
 
-  it('parses @scope/name', () => {
-    expect(parseOrgScopedSpec('@your-org/web')).toEqual({ scope: '@your-org', name: 'web' });
+  it('parses @scope:name', () => {
+    expect(parseOrgScopedSpec('@your-org:web')).toEqual({ scope: '@your-org', name: 'web' });
   });
 
-  it('parses @scope/name@version', () => {
-    expect(parseOrgScopedSpec('@your-org/web@1.2.3')).toEqual({ scope: '@your-org', name: 'web' });
+  it('parses @scope:name@version', () => {
+    expect(parseOrgScopedSpec('@your-org:web@1.2.3')).toEqual({ scope: '@your-org', name: 'web' });
   });
 
-  it('treats a trailing slash as scope-only', () => {
-    expect(parseOrgScopedSpec('@your-org/')).toEqual({ scope: '@your-org' });
+  it('treats @scope: (empty name) as scope-only', () => {
+    expect(parseOrgScopedSpec('@your-org:')).toEqual({ scope: '@your-org' });
+  });
+
+  it('returns null for the @scope/name slash form (reserved for existing shorthand)', () => {
+    expect(parseOrgScopedSpec('@your-org/web')).toBeNull();
+    expect(parseOrgScopedSpec('@your-org/create-web')).toBeNull();
+    expect(parseOrgScopedSpec('@your-org/')).toBeNull();
   });
 });
 
diff --git a/packages/cli/src/create/bin.ts b/packages/cli/src/create/bin.ts
@@ -82,7 +82,7 @@ const helpMessage = renderCliDoc({
             '  create-nuxt, github:user/repo, https://github.com/user/template-repo, etc.',
             '- Local: @company/generator-*, ./tools/create-ui-component',
             `- Org scope: ${accent('@your-org')} → picker from ${accent('@your-org/create')}'s ${accent('createConfig.templates')} manifest`,
-            `- Org entry: ${accent('@your-org/web')} → manifest entry "web" (falls back to ${accent('@your-org/create-web')})`,
+            `- Org entry: ${accent('@your-org:web')} → manifest entry "web" from ${accent('@your-org/create')}`,
             `When omitted, uses \`create.defaultTemplate\` from vite.config.ts if set.`,
           ],
         },
@@ -147,7 +147,7 @@ const helpMessage = renderCliDoc({
         '',
         `  ${muted('# Pick from an org that publishes @scope/create with createConfig.templates')}`,
         `  ${accent('vp create @your-org')} ${muted('# interactive picker')}`,
-        `  ${accent('vp create @your-org/web')} ${muted('# direct selection')}`,
+        `  ${accent('vp create @your-org:web')} ${muted('# direct manifest-entry selection')}`,
       ],
     },
   ],
diff --git a/packages/cli/src/create/org-manifest.ts b/packages/cli/src/create/org-manifest.ts
@@ -27,24 +27,35 @@ export interface OrgManifest {
 }
 
 /**
- * Parse the leading `@scope[/name]` segment of a template specifier, ignoring
- * any trailing `@version` suffix on the name.
+ * Parse the org picker specifier: `@scope` (scope only → picker) or
+ * `@scope:name` (direct manifest-entry selection). Colon mirrors the
+ * existing `vite:monorepo` / `vite:library` builtin-template syntax and
+ * keeps manifest entries syntactically distinct from real
+ * `@scope/package-name` npm specifiers.
  *
- * Returns `null` if the input does not look like an org-scoped reference.
+ * Returns `null` for anything else — including the plain `@scope/name`
+ * form, which routes to the existing `@scope/create-name` shorthand as
+ * it did before the org-manifest feature.
  */
 export function parseOrgScopedSpec(spec: string): { scope: string; name?: string } | null {
   if (!spec.startsWith('@')) {
     return null;
   }
-  const slashIndex = spec.indexOf('/');
-  if (slashIndex === -1) {
-    // `@scope` or `@scope@version`
+  // Reject `@scope/anything` — let that form fall through to the
+  // pre-feature shorthand path in `expandCreateShorthand`.
+  if (spec.includes('/')) {
+    return null;
+  }
+  const colonIndex = spec.indexOf(':');
+  if (colonIndex === -1) {
+    // `@scope` or `@scope@version` → scope-only picker.
     const atIndex = spec.indexOf('@', 1);
     const scope = atIndex === -1 ? spec : spec.slice(0, atIndex);
     return { scope };
   }
-  const scope = spec.slice(0, slashIndex);
-  const rest = spec.slice(slashIndex + 1);
+  const scope = spec.slice(0, colonIndex);
+  const rest = spec.slice(colonIndex + 1);
+  // `@scope:name@version` — strip the optional version suffix.
   const atIndex = rest.indexOf('@');
   const name = atIndex === -1 ? rest : rest.slice(0, atIndex);
   if (!name) {
diff --git a/packages/cli/src/create/org-resolve.ts b/packages/cli/src/create/org-resolve.ts
@@ -61,7 +61,7 @@ function printNonInteractiveTable(
   if (firstVisible) {
     body.push(
       '  # Scaffold a specific template from the org',
-      `  vp create ${orgSpec.scope}/${firstVisible.name} --no-interactive`,
+      `  vp create ${orgSpec.scope}:${firstVisible.name} --no-interactive`,
       '',
     );
   }
@@ -131,15 +131,19 @@ export async function resolveOrgManifestForCreate(args: {
   }
 
   if (!manifest) {
+    if (orgSpec.name !== undefined) {
+      // `@org:name` is an explicit manifest lookup; no manifest → hard error.
+      prompts.log.error(
+        `No \`createConfig.templates\` manifest in ${orgSpec.scope}/create — \`@org:name\` requires one.`,
+      );
+      process.exit(1);
+    }
     // Scope-only input (`vp create @org`) strongly implies the user
     // expected the picker. Be explicit about why it didn't engage, so a
     // later `ERR_NO_BIN` from the package manager doesn't look mysterious.
-    // Per-entry `vp create @org/name` stays silent since it's ambiguous.
-    if (orgSpec.name === undefined) {
-      prompts.log.info(
-        `No \`createConfig.templates\` manifest in ${orgSpec.scope}/create — running it as a normal package.`,
-      );
-    }
+    prompts.log.info(
+      `No \`createConfig.templates\` manifest in ${orgSpec.scope}/create — running it as a normal package.`,
+    );
     return { kind: 'passthrough' };
   }
 
@@ -168,8 +172,15 @@ export async function resolveOrgManifestForCreate(args: {
 
   const entry = manifest.templates.find((candidate) => candidate.name === orgSpec.name);
   if (!entry) {
-    // Fall through to the existing `@scope/create-name` shorthand in discovery.ts.
-    return { kind: 'passthrough' };
+    // `@scope:name` is an explicit manifest lookup — no ambiguous fall-through.
+    const available = manifest.templates
+      .filter((t) => !(t.monorepo && args.isMonorepo))
+      .map((t) => t.name)
+      .join(', ');
+    prompts.log.error(
+      `No template named "${orgSpec.name}" in ${manifest.packageName}. Available: ${available || '(none applicable in this context)'}.`,
+    );
+    process.exit(1);
   }
   rejectMonorepoEntryInsideMonorepo(entry, args.isMonorepo);
   return resolveEntry(manifest, entry);
diff --git a/rfcs/create-org-default-templates.md b/rfcs/create-org-default-templates.md

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-> node $SNAP_CASES_DIR/.shared/mock-npm-registry.mjs -- vp create @your-org/demo --no-interactive --directory my-demo-app # bundled template: extract tarball, copy subdir`
	`1`	`+> node $SNAP_CASES_DIR/.shared/mock-npm-registry.mjs -- vp create @your-org:demo --no-interactive --directory my-demo-app # bundled template: extract tarball, copy subdir`
`2`	`2`
`3`	`3`	`selected 'demo' from @your-org/create`
`4`	`4`	`◇ Scaffolded my-demo-app`
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"commands": [`
`3`		`- "node $SNAP_CASES_DIR/.shared/mock-npm-registry.mjs -- vp create @your-org/demo --no-interactive --directory my-demo-app # bundled template: extract tarball, copy subdir",`
	`3`	`+ "node $SNAP_CASES_DIR/.shared/mock-npm-registry.mjs -- vp create @your-org:demo --no-interactive --directory my-demo-app # bundled template: extract tarball, copy subdir",`
`4`	`4`	`"cat my-demo-app/package.json # verify package.json name was rewritten",`
`5`	`5`	`"cat my-demo-app/src/index.ts # verify bundled source copied",`
`6`	`6`	`"ls my-demo-app/README.md # verify README copied"`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-[1]> node $SNAP_CASES_DIR/.shared/mock-npm-registry.mjs -- vp create @your-org/monorepo --no-interactive # direct-selecting a monorepo entry inside a monorepo -> refuse`
	`1`	`+[1]> node $SNAP_CASES_DIR/.shared/mock-npm-registry.mjs -- vp create @your-org:monorepo --no-interactive # direct-selecting a monorepo entry inside a monorepo -> refuse`
`2`	`2`
`3`	`3`	`You are already in a monorepo workspace.`
`4`	`4`	`Use a different template or run this command outside the monorepo`
Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,5 @@`
`1`	`1`	`{`
`2`	`2`	`"commands": [`
`3`		`- "node $SNAP_CASES_DIR/.shared/mock-npm-registry.mjs -- vp create @your-org/monorepo --no-interactive # direct-selecting a monorepo entry inside a monorepo -> refuse"`
	`3`	`+ "node $SNAP_CASES_DIR/.shared/mock-npm-registry.mjs -- vp create @your-org:monorepo --no-interactive # direct-selecting a monorepo entry inside a monorepo -> refuse"`
`4`	`4`	`]`
`5`	`5`	`}`