feat(dsh-sdk): create <source> — add external plugin as native PM dependency + cordis mount

dsh-sdk create <source> adds a github (github:owner/repo#ref) or npm (pkg@version)
plugin as a package-manager-native dependency, then mounts the resolved dependency
in cordis.yml through ProjectEditSession. Adds PackageManager.add(spec) and
ProjectEditSession.addExternalPlugin(id, packageName). No giget/pacote. Per-file
100% coverage on the new/changed files.

packages/sdk/scripts/README.md

@@ -8,6 +8,7 @@ The `dsh-sdk` launcher owns SDK project startup and configuration.
 | `dsh-sdk dev [target] [-- args…]` | Register TypeScript and local-workspace source resolution, then use the start path |
 | `dsh-sdk build [args…]` | Invoke the project's installed tsdown with the project arguments |
 | `dsh-sdk config` | Open one interactive edit session, review accumulated changes, commit once, and install once when NPM dependencies changed |
+| `dsh-sdk create <source>` | Add an external Cordis plugin from a native package-manager source (`pkg@version` or `github:owner/repo#ref`): confirm, `<pm> add <source>`, then mount the resolved dependency in `cordis.yml`. No giget/pacote; the package manager resolves and pins the source (github deps build via their own `prepare` under the manager's policy) |
 
 `ProjectBuild(tsdownConfig)` and `PluginBuild(tsdownConfig)` are exported only from `@deepseek-ai/dsh-scripts/dev/tsdown-config`. Development and production read the same `cordis.yml`.
 

packages/sdk/scripts/src/args.ts

@@ -8,12 +8,13 @@ import { parseArgs as parseNodeArgs } from 'node:util'
 import { Command } from 'commander'
 
 /** Commands implemented by the dsh-sdk launcher. */
-type DshSdkCommand = 'start' | 'dev' | 'build' | 'config'
+type DshSdkCommand = 'start' | 'dev' | 'build' | 'config' | 'create'
 
 /** Parsed dsh-sdk invocation. */
 export interface DshSdkArgs {
   command?: DshSdkCommand
   target?: string
+  source?: string
   forwarded: readonly string[]
   help: boolean
 }
@@ -60,6 +61,9 @@ export function parseDshSdkArgs(argv: readonly string[]): DshSdkArgs {
   program.command('config').helpOption(false).action(() => {
     parsed = { command: 'config', forwarded: [], help: false }
   })
+  program.command('create <source>').helpOption(false).action((source: string) => {
+    parsed = { command: 'create', source, forwarded: [], help: false }
+  })
   program.parse([...launcherArgv], { from: 'user' })
   /* v8 ignore next -- every registered Commander action above assigns parsed or Commander throws */
   if (!parsed) throw new Error('dsh-sdk command did not resolve')

packages/sdk/scripts/src/command.ts

@@ -7,6 +7,7 @@
 import { parseDshSdkArgs } from './args.ts'
 import { runProjectBuild } from './build.ts'
 import { runConfigCommand, type ConfigCommandContext } from './config.ts'
+import { runCreatePluginCommand } from './create-plugin.ts'
 import { runSDK } from './runtime.ts'
 import { DSH_SDK_TEMPLATES } from './templates/dsh-sdk-templates.ts'
 
@@ -19,6 +20,7 @@ export interface DshSdkCommandContext extends ConfigCommandContext {
   run?: typeof runSDK
   build?: typeof runProjectBuild
   config?: typeof runConfigCommand
+  createPlugin?: typeof runCreatePluginCommand
 }
 
 /** Run one parsed dsh-sdk command and return its process exit code. */
@@ -40,6 +42,7 @@ export async function runDshSdkCommand(
     const run = context.run ?? runSDK
     const build = context.build ?? runProjectBuild
     const config = context.config ?? runConfigCommand
+    const createPlugin = context.createPlugin ?? runCreatePluginCommand
     switch (args.command) {
       case 'start': await run(args.target, { cwd: context.cwd, argv: args.forwarded }); break
       case 'dev': await run(args.target, { cwd: context.cwd, dev: true, argv: args.forwarded }); break
@@ -49,6 +52,8 @@ export async function runDshSdkCommand(
         if (result.installError) return 1
         break
       }
+      /* v8 ignore next -- Commander requires <source>, so create never dispatches without it */
+      case 'create': await createPlugin(args.source ?? '', context); break
     }
     return 0
   } catch (error) {

packages/sdk/scripts/src/create-plugin.ts

@@ -0,0 +1,91 @@
+/**
+ * dsh-sdk create command: add an external Cordis plugin (github or npm) as a
+ * native package-manager dependency and mount it in cordis.yml.
+ *
+ * @module @deepseek-ai/dsh-scripts/create-plugin
+ */
+
+import { readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import {
+  ClackPromptPort,
+  ConfirmQuestion,
+  SdkProject,
+  createBuiltinRegistry,
+  requireAnswer,
+  type PackageManager,
+  type ProjectCommitResult,
+  type PromptPort,
+} from '@deepseek-ai/dsh-helper'
+
+/** Process and interaction slice required by dsh-sdk create. */
+export interface CreatePluginContext {
+  cwd: string
+  stdin: NodeJS.ReadStream
+  stdout: NodeJS.WriteStream
+  port?: PromptPort
+  add?: (manager: PackageManager, spec: string, cwd: string) => Promise<void>
+}
+
+/** Result of a create run; `undefined` when the confirmation was declined. */
+export type CreatePluginResult = ProjectCommitResult<SdkProject> | undefined
+
+/** Derive a stable cordis entry id from a package name's last path segment. */
+function pluginId(packageName: string): string {
+  const base = packageName.startsWith('@') ? packageName.slice(packageName.indexOf('/') + 1) : packageName
+  const id = base.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '')
+  /* v8 ignore next -- a valid npm package name always yields a non-empty id */
+  if (!id) throw new Error(`cannot derive a plugin id from package name: ${packageName}`)
+  return id
+}
+
+/** Read the direct dependency names declared in a project's package.json. */
+async function dependencyNames(cwd: string): Promise<Set<string>> {
+  const manifest = JSON.parse(await readFile(join(cwd, 'package.json'), 'utf8')) as {
+    dependencies?: Record<string, unknown>
+  }
+  /* v8 ignore next -- generated projects always declare a dependencies map */
+  return new Set(Object.keys(manifest.dependencies ?? {}))
+}
+
+/**
+ * Add one external plugin dependency to the current project and mount it.
+ * @param source - a package-manager-native source (`pkg@version` or `github:owner/repo#ref`).
+ * @param context - process, interaction, and dependency-add boundaries.
+ * @returns the commit result, or `undefined` when the confirmation was declined.
+ */
+export async function runCreatePluginCommand(
+  source: string,
+  context: CreatePluginContext,
+): Promise<CreatePluginResult> {
+  const spec = source.trim()
+  if (!spec) throw new Error('dsh-sdk create requires a plugin source (pkg@version or github:owner/repo#ref)')
+  if (!context.port && (!context.stdin.isTTY || !context.stdout.isTTY)) {
+    throw new Error('dsh-sdk create requires an interactive TTY')
+  }
+  const project = await SdkProject.open(context.cwd)
+  /* v8 ignore next -- production TTY wiring is exercised by the built-bin smoke */
+  const port = context.port ?? new ClackPromptPort(context.stdin, context.stdout)
+  const confirmed = requireAnswer(await new ConfirmQuestion({
+    id: 'create.confirm',
+    message: `Add plugin '${spec}' as a dependency and mount it in cordis.yml?`,
+    initialValue: true,
+  }).resolve(port))
+  if (!confirmed) return undefined
+
+  const before = await dependencyNames(context.cwd)
+  /* v8 ignore next -- production package-manager wiring is exercised by the built-bin smoke */
+  const add = context.add ?? ((manager, source, cwd) => manager.add(source, cwd))
+  await add(project.profile.packageManager, spec, context.cwd)
+  const after = await dependencyNames(context.cwd)
+  const added = [...after].filter(name => !before.has(name))
+  if (added.length === 0) throw new Error(`dsh-sdk create: '${spec}' added no new dependency`)
+
+  const reopened = await SdkProject.open(context.cwd)
+  const registry = createBuiltinRegistry(reopened.profile)
+  const edit = reopened.edit(registry)
+  for (const packageName of added) edit.addExternalPlugin(pluginId(packageName), packageName)
+  const commit = await edit.commit()
+  context.stdout.write(`Mounted ${added.join(', ')} in cordis.yml.\n`)
+  return commit
+}

packages/sdk/scripts/tests/scripts.spec.ts

@@ -31,6 +31,7 @@ import { PluginBuild, ProjectBuild, runProjectBuild } from '../src/build.ts'
 import { runDshSdkCommand, type DshSdkCommandContext } from '../src/command.ts'
 import { runConfigCommand } from '../src/config.ts'
 import { ConfigWorkflow, type ConfigPlan } from '../src/config/config-workflow.ts'
+import { runCreatePluginCommand } from '../src/create-plugin.ts'
 import { initialize, resolve as resolveLocalPlugin } from '../src/local-plugin-loader-hooks.ts'
 
 const temporary: string[] = []
@@ -559,3 +560,62 @@ describe('ConfigWorkflow', () => {
     expect(output.read()).toContain('Disable feature: ask-user')
   })
 })
+
+describe('dsh-sdk create', () => {
+  const writeDependency = (name: string) => async (_m: unknown, spec: string, cwd: string): Promise<void> => {
+    const path = join(cwd, 'package.json')
+    const manifest = JSON.parse(await readFile(path, 'utf8')) as { dependencies?: Record<string, string> }
+    manifest.dependencies = { ...manifest.dependencies, [name]: spec }
+    await writeFile(path, JSON.stringify(manifest, null, 2))
+  }
+
+  it('adds a dependency and mounts it after confirmation', async () => {
+    const project = await committedProject()
+    const context = { ...commandContext(project.root), port: new QueuePort([true]), add: writeDependency('my-ext-plugin') }
+    const result = await runCreatePluginCommand('github:o/r#sha', context)
+    expect(result?.project.cordis.entry('my-ext-plugin')?.name).toBe('my-ext-plugin')
+    expect(context.readStdout()).toContain('Mounted my-ext-plugin')
+  })
+
+  it('derives the cordis id from a scoped package name', async () => {
+    const project = await committedProject()
+    const context = { ...commandContext(project.root), port: new QueuePort([true]), add: writeDependency('@acme/cool-plugin') }
+    const result = await runCreatePluginCommand('@acme/cool-plugin@1.0.0', context)
+    expect(result?.project.cordis.entry('cool-plugin')?.name).toBe('@acme/cool-plugin')
+  })
+
+  it('returns undefined and adds nothing when declined', async () => {
+    const project = await committedProject()
+    let added = false
+    const context = {
+      ...commandContext(project.root),
+      port: new QueuePort([false]),
+      add: async () => { added = true },
+    }
+    await expect(runCreatePluginCommand('pkg@1.0.0', context)).resolves.toBeUndefined()
+    expect(added).toBe(false)
+  })
+
+  it('rejects an empty source, a non-TTY session, and a no-op add', async () => {
+    const project = await committedProject()
+    await expect(runCreatePluginCommand('   ', { ...commandContext(project.root), port: new QueuePort([]) }))
+      .rejects.toThrow('requires a plugin source')
+    const noTty = commandContext(project.root)
+    noTty.stdin.isTTY = false
+    noTty.stdout.isTTY = false
+    await expect(runCreatePluginCommand('pkg@1.0.0', noTty)).rejects.toThrow('interactive TTY')
+    const noOutTty = commandContext(project.root)
+    noOutTty.stdout.isTTY = false
+    await expect(runCreatePluginCommand('pkg@1.0.0', noOutTty)).rejects.toThrow('interactive TTY')
+    await expect(runCreatePluginCommand('pkg@1.0.0', {
+      ...commandContext(project.root), port: new QueuePort([true]), add: async () => {},
+    })).rejects.toThrow('added no new dependency')
+  })
+
+  it('dispatches create through the launcher', async () => {
+    const project = await committedProject()
+    const context = commandContext(project.root)
+    context.createPlugin = async () => undefined
+    await expect(runDshSdkCommand(['create', 'pkg@1.0.0'], context)).resolves.toBe(0)
+  })
+})