Skip to content

docs/features/app-wizard.md lists non-existent templates node-server and static, which fail validation in POST /api/scaffold #6033

Description

@atomantic

Problem

In docs/features/app-wizard.md:34, step 2 of "Mode 2: Create New App" instructs users:

2. **Template**: Select template (vite+express, node-server, static)

However, server/lib/validation.js:1100-1107 strictly restricts scaffoldSchema.template to SCAFFOLD_TEMPLATES:

export const SCAFFOLD_TEMPLATES = [
  'portos-stack',
  'vite-express',
  'vite-react',
  'express-api',
  'ios-native',
  'xcode-multiplatform'
];

And server/routes/scaffold.js:94-154 (GET /api/scaffold/templates) registers only these 6 templates.
Neither node-server nor static exists. Submitting either template value to POST /api/scaffold is rejected by Zod with a 400 VALIDATION_ERROR.

Furthermore, the API table in docs/features/app-wizard.md:55-62 omits the directory browser endpoint GET /api/scaffold/directories and helper route POST /api/scaffold/templates/create.

Trigger

A user or developer following docs/features/app-wizard.md attempts to invoke POST /api/scaffold with { "template": "node-server", ... } or { "template": "static", ... }.

Impact

The scaffolding request fails immediately with HTTP 400 (Invalid enum value). Meanwhile, actual supported scaffolding templates (portos-stack, vite-react, ios-native, xcode-multiplatform) are not discoverable from the feature guide.

Fix

  1. Update docs/features/app-wizard.md line 34 to list the real templates: portos-stack, vite-express, vite-react, express-api, ios-native, xcode-multiplatform.
  2. Add GET /api/scaffold/directories and POST /api/scaffold/templates/create to the API table in docs/features/app-wizard.md.
  3. Verify test coverage in server/routes/scaffold.test.js or server/lib/validation.test.js.

Alternative rejected: Adding node-server and static to SCAFFOLD_TEMPLATES — rejected because express-api and vite-react supersede them, and PortOS does not maintain standalone static/node-server scaffolding scripts.

Acceptance Criteria

  • docs/features/app-wizard.md lists the 6 actual templates from SCAFFOLD_TEMPLATES.
  • docs/features/app-wizard.md documents GET /api/scaffold/directories.
  • Existing scaffolding tests pass (npm test -- server/routes/scaffold.test.js).

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationeffort:lowEffort: lowmodel:lightModel size: lightplanTracked by /do:replanplanner:gemini-3-7-flashPlan authored by the gemini-3-7-flash model

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions