feat(sdk): headless PromptPort + create/config headless plan

Add HeadlessPromptPort (fail-loud non-interactive PromptPort), thread
prefilled feature values through FeatureConfigurator, and let CreateWizard
and ConfigWorkflow accept a headless feature plan that skips the interactive
tree/suggests prompts. Per-file 100% coverage on all changed files.

packages/sdk/create-sdk/src/create-wizard.ts

@@ -48,6 +48,7 @@ export class CreateWizard {
   private readonly versionProbe: PackageManagerVersionProbe
   private readonly userAgent: string
   private readonly linkWorkspaceRoot: string | undefined
+  private readonly featurePlan: readonly FeatureSelection[] | undefined
 
   /** Bind parsed args and infrastructure to one wizard run. */
   constructor(options: {
@@ -57,6 +58,7 @@ export class CreateWizard {
     releaseVersion: string
     versionProbe?: PackageManagerVersionProbe
     userAgent?: string
+    features?: readonly FeatureSelection[]
   }) {
     this.args = options.args
     this.port = options.port
@@ -68,6 +70,7 @@ export class CreateWizard {
     this.linkWorkspaceRoot = options.args.linkWorkspace
       ? fileURLToPath(new URL('../../../../', import.meta.url))
       : undefined
+    this.featurePlan = options.features
   }
 
   /** Collect all answers before constructing any project files. */
@@ -129,39 +132,43 @@ export class CreateWizard {
     const configurable = registry.all().filter(feature => feature.id === 'bash'
       || feature.id === 'persistence'
       || (!feature.required && feature.isApplicable(profile)))
-    const selected = [...requireAnswer(await this.port.nestedMultiselect({
-      message: 'Select features',
-      options: configurable.map((feature) => {
-        const nested = feature.mode !== 'single'
-        const defaults = new Set(feature.defaultOptions(profile))
-        return {
-          value: feature.id,
-          label: feature.summary,
-          required: feature.required,
-          default: feature.required || feature.id === 'hmr' || feature.id === 'fs' || feature.id === 'todo'
-            || feature.id === 'skill',
-          ...nested ? {
-            choiceMode: feature.mode === 'multiple' ? 'multiple' as const : 'exclusive' as const,
-            choices: feature.options.map(option => ({
-              value: option.id,
-              label: option.label,
-              default: defaults.has(option.id),
-            })),
-          } : {},
+    const selected = this.featurePlan
+      ? this.featurePlan.map(feature => ({ value: feature.id, choices: feature.options }))
+      : [...requireAnswer(await this.port.nestedMultiselect({
+        message: 'Select features',
+        options: configurable.map((feature) => {
+          const nested = feature.mode !== 'single'
+          const defaults = new Set(feature.defaultOptions(profile))
+          return {
+            value: feature.id,
+            label: feature.summary,
+            required: feature.required,
+            default: feature.required || feature.id === 'hmr' || feature.id === 'fs' || feature.id === 'todo'
+              || feature.id === 'skill',
+            ...nested ? {
+              choiceMode: feature.mode === 'multiple' ? 'multiple' as const : 'exclusive' as const,
+              choices: feature.options.map(option => ({
+                value: option.id,
+                label: option.label,
+                default: defaults.has(option.id),
+              })),
+            } : {},
+          }
+        }),
+      }))]
+    if (!this.featurePlan) {
+      for (const { value: id } of [...selected]) {
+        const feature = registry.get(id)
+        for (const suggestedId of feature.suggests) {
+          if (selected.some(item => item.value === suggestedId)) continue
+          const suggested = registry.get(suggestedId)
+          const add = requireAnswer(await new ConfirmQuestion({
+            id: `${feature.id}.${suggested.id}`,
+            message: `Add the recommended ${suggested.summary.toLowerCase()} for ${feature.summary.toLowerCase()}?`,
+            initialValue: true,
+          }).resolve(this.port))
+          if (add) selected.push({ value: suggested.id, choices: suggested.defaultOptions(profile) })
         }
-      }),
-    }))]
-    for (const { value: id } of [...selected]) {
-      const feature = registry.get(id)
-      for (const suggestedId of feature.suggests) {
-        if (selected.some(item => item.value === suggestedId)) continue
-        const suggested = registry.get(suggestedId)
-        const add = requireAnswer(await new ConfirmQuestion({
-          id: `${feature.id}.${suggested.id}`,
-          message: `Add the recommended ${suggested.summary.toLowerCase()} for ${feature.summary.toLowerCase()}?`,
-          initialValue: true,
-        }).resolve(this.port))
-        if (add) selected.push({ value: suggested.id, choices: suggested.defaultOptions(profile) })
       }
     }
     const fixed = new Set(selections.map(selection => selection.id))
@@ -174,12 +181,16 @@ export class CreateWizard {
     for (const choice of selected) {
       choices.set(choice.value, choice.choices.length > 0 ? choice.choices : undefined)
     }
+    const plannedById = new Map((this.featurePlan ?? []).map(feature => [feature.id, feature]))
     for (const [id, options] of choices) {
+      const planned = plannedById.get(id)
       selections.push(await configurator.configure(
         registry.get(id),
         profile,
         undefined,
         options,
+        planned?.secrets ?? {},
+        planned?.values ?? {},
       ))
     }
     return selections

packages/sdk/create-sdk/tests/create.spec.ts

@@ -5,9 +5,11 @@ import { PassThrough, Writable } from 'node:stream'
 import { fileURLToPath } from 'node:url'
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import {
+  HeadlessPromptPort,
   LocalPluginBlueprint,
   featureId,
   NpmPackageManager,
+  type FeatureSelection,
   type NestedMultiSelectValue,
   type PromptPort,
 } from '@deepseek-ai/dsh-helper'
@@ -233,6 +235,54 @@ describe('CreateWizard and scaffolder', () => {
     expect(resolved.request.features.find(item => item.id === 'hmr')).toMatchObject({ options: ['default'] })
   })
 
+  it('runs headlessly from a feature plan without reaching the terminal', async () => {
+    const cwd = await mkdtemp(join(tmpdir(), 'create-headless-'))
+    temporary.push(cwd)
+    const features: FeatureSelection[] = [
+      { id: featureId('persistence'), options: ['sqlite'], values: { region: 'us' } },
+      { id: featureId('web'), options: ['exa'], secrets: { apiKey: 'exa-key' } },
+    ]
+    const resolved = await new CreateWizard({
+      args: parseCreateArgs([
+        'my-agent', '--description=demo', '--provider=deepseek', '--api-key=deepseek-key',
+        '--model=deepseek-v4-flash', '--interface=stdio', '--pm=npm', '--no-install',
+      ]),
+      port: new HeadlessPromptPort(),
+      cwd,
+      releaseVersion: '0.0.1',
+      versionProbe: async () => '10.0.0',
+      features,
+    }).run()
+    expect(resolved.install).toBe(false)
+    expect(resolved.request.localPlugins).toEqual([])
+    expect(resolved.request.features.find(item => item.id === 'web')).toMatchObject({
+      options: ['exa'], secrets: { apiKey: 'exa-key' },
+    })
+    expect(resolved.request.features.find(item => item.id === 'persistence')).toMatchObject({ options: ['sqlite'] })
+    expect(resolved.request.features.find(item => item.id === 'provider')).toMatchObject({
+      secrets: { apiKey: 'deepseek-key' },
+    })
+  })
+
+  it('rejects a non-string feature value in a headless plan', async () => {
+    const cwd = await mkdtemp(join(tmpdir(), 'create-headless-bad-'))
+    temporary.push(cwd)
+    const features = [
+      { id: featureId('persistence'), options: ['sqlite'], values: { bad: 1 } },
+    ] as unknown as FeatureSelection[]
+    await expect(new CreateWizard({
+      args: parseCreateArgs([
+        'my-agent', '--description=demo', '--provider=deepseek', '--api-key=k',
+        '--model=m', '--interface=stdio', '--pm=npm', '--no-install',
+      ]),
+      port: new HeadlessPromptPort(),
+      cwd,
+      releaseVersion: '0.0.1',
+      versionProbe: async () => '10.0.0',
+      features,
+    }).run()).rejects.toThrow('must be a string')
+  })
+
   it('writes the project once and refuses every existing target', async () => {
     const root = await mkdtemp(join(tmpdir(), 'create-scaffold-'))
     temporary.push(root)