create-rapidoc 0.0.0-stage → 0.1.2

package/LICENSE.txt

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2022 Mrinmoy Majumdar
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,37 @@
-# Temporary Holding Version
+# create-rapidoc
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Scaffolds a [RapiDoc Portal](https://portal.rapidocui.com): a developer portal built from OpenAPI specs and Markdown guides.
+
+```bash
+npm create rapidoc@latest my-portal
+cd my-portal
+npm install
+npm run dev
+```
+
+Run it in a folder that already has OpenAPI files and the portal uses them: one API reference and navigation tab per spec. Otherwise it adds a sample spec.
+
+Node.js 22.12 or later.
+
+## What it writes
+
+- `rapidoc.config.yaml`: site, theme, header, navigation tabs and APIs
+- `package.json` with `@rapidoc/cli` and `@rapidoc/portal`, and `dev`, `build`, `validate` and `preview` scripts
+- `docs/`: a home page, a getting-started guide and a Markdoc guide
+- `specs/api.yaml` (when the folder has no specs), `.gitignore` and `README.md`
+
+Existing files are kept unless you pass `--force`.
+
+## Options
+
+| Option            | Meaning                                                                           |
+| :---------------- | :-------------------------------------------------------------------------------- |
+| `--title <title>` | Site title, e.g. `"Acme Developer Portal"`                                        |
+| `--force`, `-f`   | Overwrite existing files                                                          |
+| `--yes`, `-y`     | Don't ask; use the defaults (in a terminal it asks for the title and which specs) |
+
+`rapidoc init` in [`@rapidoc/cli`](https://www.npmjs.com/package/@rapidoc/cli) does the same in an existing project.
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "create-rapidoc",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.2",
+  "description": "Interactive scaffolding CLI to create new RapiDoc Developer Portals",
+  "keywords": [
+    "create-rapidoc",
+    "developer-portal",
+    "documentation",
+    "openapi",
+    "rapidoc",
+    "scaffold"
+  ],
+  "homepage": "https://portal.rapidocui.com",
+  "bugs": {
+    "url": "https://github.com/rapi-doc/RapiDoc/issues"
+  },
+  "license": "MIT",
+  "author": "Mrinmoy Majumdar <mrin9@yahoo.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rapi-doc/RapiDoc.git",
+    "directory": "packages/create-rapidoc"
+  },
+  "bin": {
+    "create-rapidoc": "src/index.js"
+  },
+  "files": [
+    "src"
+  ],
+  "type": "module",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./scaffold": "./src/scaffold.js",
+    "./wizard": "./src/wizard.js"
+  },
+  "scripts": {
+    "test": "node --test tests/**/*.test.js"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.8.1",
+    "yaml": "^2.9.1"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  }
+}

package/src/index.js

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+
+import path from "node:path";
+import fs from "node:fs";
+import pkg from "../package.json" with { type: "json" };
+import { findOpenApiSpecs, scaffoldProject } from "./scaffold.js";
+import { askInitQuestions } from "./wizard.js";
+
+const args = process.argv.slice(2);
+
+function printHelp() {
+  console.log(`
+create-rapidoc - Scaffold a modern RapiDoc Developer Portal
+
+Usage:
+  npm create rapidoc@latest [directory] [options]
+  npx create-rapidoc [directory] [options]
+
+Options:
+  --title <title>    Human-readable site title (e.g. "Acme Developer Portal")
+  --force, -f        Overwrite existing files in target directory
+  --yes, -y          Don't ask: use the defaults (in a terminal it asks for the title and which specs)
+  --help, -h         Show this help message
+  --version, -v      Show version information
+
+Examples:
+  npm create rapidoc@latest my-portal
+  npx create-rapidoc ./company-docs --title "Stripe Alternative Docs"
+`);
+}
+
+if (args.includes("--help") || args.includes("-h")) {
+  printHelp();
+  process.exit(0);
+}
+
+if (args.includes("--version") || args.includes("-v")) {
+  console.log(pkg.version);
+  process.exit(0);
+}
+
+let targetDir = args.find((a) => !a.startsWith("-")) || "my-developer-portal";
+const titleIdx = args.indexOf("--title");
+const customTitle = titleIdx !== -1 && args[titleIdx + 1] ? args[titleIdx + 1] : undefined;
+const force = args.includes("--force") || args.includes("-f");
+const yes = args.includes("--yes") || args.includes("-y");
+const foundSpecs = fs.existsSync(targetDir) ? findOpenApiSpecs(targetDir) : [];
+
+// In a terminal, the same questions as `rapidoc init` (installing is left to the next steps).
+let answers = { title: customTitle };
+if (!yes && process.stdin.isTTY && process.stdout.isTTY && !process.env.CI) {
+  const clack = await import("@clack/prompts");
+  const answer = (prompt) => async (options) => {
+    const value = await prompt(options);
+    if (clack.isCancel(value)) {
+      clack.cancel("Cancelled.");
+      process.exit(130);
+    }
+    return value;
+  };
+  clack.intro("Create a RapiDoc developer portal");
+  answers = await askInitQuestions({
+    ask: {
+      text: answer(clack.text),
+      multiselect: answer(clack.multiselect),
+      confirm: answer(clack.confirm),
+    },
+    targetDir,
+    foundSpecs,
+    known: { title: customTitle },
+    askInstall: false,
+  });
+}
+
+console.log(`\n🚀 Scaffolding new RapiDoc Developer Portal into: ${targetDir}`);
+
+try {
+  const result = await scaffoldProject(targetDir, {
+    title: answers.title || undefined,
+    overwrite: force,
+    specs: answers.specs ?? foundSpecs,
+  });
+
+  console.log(`\n✨ Successfully created ${result.projectName}!`);
+  console.log(`   • Site Title:   ${result.siteTitle}`);
+  console.log(`   • Location:     ${result.targetDir}`);
+  console.log(`   • Files:        ${result.filesCreated.length} starter files generated`);
+
+  console.log(`\nNext steps:`);
+  console.log(`   1. cd ${path.relative(process.cwd(), result.targetDir) || "."}`);
+  console.log(`   2. npm install`);
+  console.log(`   3. npm run dev\n`);
+} catch (err) {
+  console.error(`\n❌ Failed to scaffold portal: ${err.message}\n`);
+  process.exit(1);
+}

package/src/scaffold.js

@@ -0,0 +1,562 @@
+import fs from "node:fs";
+import path from "node:path";
+import pkg from "../package.json" with { type: "json" };
+
+/**
+ * Range for the @rapidoc packages a new project depends on. They release with create-rapidoc as one
+ * fixed group (.changeset/config.json), so its own version is theirs too.
+ */
+const RAPIDOC_PACKAGES_RANGE = `^${pkg.version}`;
+
+/**
+ * Starter template contents for scaffolding a new RapiDoc Developer Portal.
+ */
+
+const STARTER_SPEC = `openapi: 3.1.0
+info:
+  title: Core Services API
+  version: 1.0.0
+  description: High-performance microservices and developer APIs.
+servers:
+  - url: https://api.example.com/v1
+    description: Production Server
+  - url: https://sandbox.example.com/v1
+    description: Sandbox Environment
+paths:
+  /health:
+    get:
+      summary: Service Health Check
+      description: Returns the operational status and uptime of the system.
+      operationId: getHealth
+      tags:
+        - System
+      responses:
+        '200':
+          description: Service operational
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  status:
+                    type: string
+                    example: healthy
+                  timestamp:
+                    type: string
+                    format: date-time
+
+  /items:
+    get:
+      summary: List items
+      description: Retrieve a paginated collection of catalog items.
+      operationId: listItems
+      tags:
+        - Items
+      responses:
+        '200':
+          description: List of items
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/Item'
+    post:
+      summary: Create item
+      description: Creates a new catalog item.
+      operationId: createItem
+      tags:
+        - Items
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateItemRequest'
+      responses:
+        '201':
+          description: Item created successfully
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Item'
+
+components:
+  schemas:
+    Item:
+      type: object
+      required:
+        - id
+        - name
+      properties:
+        id:
+          type: string
+          example: item_123
+        name:
+          type: string
+          example: Standard Widget
+        status:
+          type: string
+          enum: [active, archived]
+          example: active
+
+    CreateItemRequest:
+      type: object
+      required:
+        - name
+      properties:
+        name:
+          type: string
+          example: Premium Widget
+`;
+
+const STARTER_GETTING_STARTED = `---
+title: Getting Started
+description: Quickstart guide to integrating with the Core Developer Platform.
+---
+
+# Getting Started
+
+Welcome to the Developer Portal. This guide walks you through authenticating with our services and making your very first API request.
+
+## Prerequisites
+
+Before making requests, ensure you have:
+1. Created an account on the Developer Dashboard.
+2. Generated a secure API token with read/write access.
+
+## Base URLs
+
+| Environment | Base URL |
+| :--- | :--- |
+| **Production** | \`https://api.example.com/v1\` |
+| **Sandbox** | \`https://sandbox.example.com/v1\` |
+
+## First Request
+
+Send an authenticated \`GET\` request to the health check endpoint:
+
+\`\`\`bash
+curl -X GET "https://sandbox.example.com/v1/health" \\
+  -H "Authorization: Bearer YOUR_API_TOKEN"
+\`\`\`
+
+You will receive a \`200 OK\` response:
+
+\`\`\`json
+{
+  "status": "healthy",
+  "timestamp": "2026-10-18T12:00:00Z"
+}
+\`\`\`
+
+## Next Steps
+
+Explore the interactive API console or review our [Architecture Overview](/docs/guides/overview).
+`;
+
+const STARTER_OVERVIEW = (withStarterSpec) => `---
+title: Architecture Overview
+description: Learn how microservices, caching, and rate limiting work across the platform.
+---
+
+# Architecture Overview
+
+Our platform is engineered for high throughput, predictable latencies, and distributed fault tolerance.
+
+{% callout type="info" title="Zero Downtime Deployments" %}
+All endpoints operate across multiple geographically distributed availability zones.
+{% /callout %}
+
+## Implementation Steps
+
+{% steps %}
+{% step title="Generate Credentials" %}
+Obtain your API Key from the portal settings and configure it in your environment variables.
+{% /step %}
+
+{% step title="Configure Webhooks" %}
+Register a secure HTTPS callback URL to receive real-time event notifications.
+{% /step %}
+
+{% step title="Test Endpoints in Sandbox" %}
+Validate schema payloads against the sandbox environment before going live.
+{% /step %}
+{% /steps %}
+${
+  withStarterSpec
+    ? `
+## Try It
+
+Any operation from your specs can be embedded live in a guide (\`spec\` is the API's \`id\` in \`rapidoc.config.yaml\`):
+
+{% api-operation spec="core" path="/items" method="get" /%}
+`
+    : ""
+}
+## Code Examples
+
+{% tabs %}
+{% tab name="JavaScript" %}
+\`\`\`javascript
+const res = await fetch('https://api.example.com/v1/items', {
+  headers: { Authorization: 'Bearer YOUR_TOKEN' }
+});
+const items = await res.json();
+\`\`\`
+{% /tab %}
+
+{% tab name="Python" %}
+\`\`\`python
+import requests
+
+res = requests.get('https://api.example.com/v1/items', headers={
+    'Authorization': 'Bearer YOUR_TOKEN'
+})
+items = res.json()
+\`\`\`
+{% /tab %}
+
+{% tab name="cURL" %}
+\`\`\`bash
+curl -H "Authorization: Bearer YOUR_TOKEN" https://api.example.com/v1/items
+\`\`\`
+{% /tab %}
+{% /tabs %}
+`;
+
+const STARTER_HOME = (title, apiId) => `---
+title: "${title}"
+description: Guides and interactive API reference.
+template: splash
+hero:
+  # layout: stacked  # split (default): text left, image right; stacked: centred, image below
+  tagline: Everything you need to integrate with our APIs, from your first request to production.
+  actions:
+    - text: Get started
+      link: /docs/getting-started/
+      icon: right-arrow
+    - text: API reference
+      link: /apis/${apiId}
+      variant: minimal
+---
+
+{% card-grid %}
+{% card title="Getting Started" icon="rocket" href="/docs/getting-started/" %}
+Authenticate and make your first request.
+{% /card %}
+{% card title="Architecture Overview" icon="book-open" href="/docs/guides/overview/" %}
+How the platform handles caching, rate limits and failover.
+{% /card %}
+{% /card-grid %}
+`;
+
+const STARTER_CONFIG = (
+  title,
+  apis,
+) => `# yaml-language-server: $schema=./node_modules/@rapidoc/portal/schema.json
+site:
+  title: "${title}"
+  description: "Official developer portal and interactive API reference."
+  # url: "https://developers.example.com"   # canonical links and sitemap; a path (https://example.com/developers) is where the portal is served
+  # image: "/social-card.png"               # preview image for shared links (needs url)
+  banner:
+    message: "🎉 Welcome to our brand new developer portal!"
+    href: "/docs/getting-started"
+
+theme:
+  primary: "#f59e0b"
+  mode: auto
+  # css: "./styles/portal.css"   # your stylesheet, loaded after the portal's own
+
+# Tags added to every page, e.g. analytics:
+# head:
+#   - script: { src: "https://plausible.io/js/script.js", defer: true, data-domain: "example.com" }
+
+# Row 1 of the header: links and menus right of the search
+header:
+  links:
+    - label: "Solutions"
+      items:
+        - label: "Getting Started"
+          icon: "rocket"
+          description: "Quickstart guide and developer tutorials"
+          href: "/docs/getting-started"
+        - label: "${apis[0].label}"
+          icon: "lightning"
+          description: "Interactive OpenAPI documentation"
+          href: "/apis/${apis[0].id}"
+    - label: "Get started"
+      href: "/docs/getting-started"
+      style: primary
+
+# Row 2 of the header: one tab per entry; a documentation tab has its own sidebar
+navigation:
+  - label: "Documentation"
+    icon: "book"
+    items:
+      - label: "Guides"
+        items:
+          - getting-started
+          - guides/overview
+${apis.map((api) => `  - label: "${api.label}"\n    icon: "code"\n    api: ${api.id}\n`).join("")}  - label: "API Catalog"
+    icon: "squares-four"
+    catalog: true
+
+apis:
+${apis.map((api) => `  - id: ${api.id}\n    spec: "${api.spec}"\n`).join("")}# Several versions of one API: \`versions\` instead of \`spec\`. The first is the default, at /apis/<id>;
+# the others are at /apis/<id>/<version>, with a version picker on the reference page.
+#   versions:
+#     - "./specs/api-v2.yaml"
+#     - "./specs/api-v1.yaml"
+
+# Arazzo workflow files: drawn by {% workflow file="<id>" /%} in docs pages and exported as MCP
+# tools. A source description named like an API id resolves against that API's spec.
+# workflows:
+#   - file: "./workflows/checkout.arazzo.yaml"
+
+rapidoc:
+  render-style: "focused"
+  schema-style: "tree"
+
+# Each docs page is also published as Markdown, with /llms.txt for AI tools and "Copy page" buttons.
+# llms: false   # turns that off
+
+# Optional: sign-in through your OpenID Connect provider and access rules, enforced by
+# \`rapidoc serve\` (npm install @rapidoc/server). Secrets are environment variables of the server:
+# RAPIDOC_SESSION_SECRET and RAPIDOC_AUTH_CLIENT_SECRET.
+# auth:
+#   issuer: "https://your-tenant.okta.com/oauth2/default"
+#   clientId: "portal-web"
+#   tryIt: true   # Try in the API reference sends the signed-in reader's access token
+# access:
+#   default: public
+#   rules:
+#     - path: /docs/internal/**
+#       allow: signed-in
+`;
+
+const STARTER_PACKAGE_JSON = (projectName) =>
+  JSON.stringify(
+    {
+      name: projectName,
+      version: "0.1.0",
+      private: true,
+      type: "module",
+      scripts: {
+        dev: "rapidoc dev",
+        build: "rapidoc build",
+        validate: "rapidoc validate",
+        preview: "npx serve dist",
+      },
+      // The CLI loads the portal engine for dev/build; listing it here also makes the config's
+      // $schema path (node_modules/@rapidoc/portal/schema.json) resolve.
+      devDependencies: {
+        "@rapidoc/cli": RAPIDOC_PACKAGES_RANGE,
+        "@rapidoc/portal": RAPIDOC_PACKAGES_RANGE,
+      },
+    },
+    null,
+    2,
+  );
+
+const STARTER_GITIGNORE = `node_modules/
+dist/
+.rapidoc-temp/
+.DS_Store
+`;
+
+const STARTER_README = (title) => `# ${title}
+
+Welcome to your developer portal, powered by **[@rapidoc/portal](https://rapidocui.com)**.
+
+## Quick Start
+
+\`\`\`bash
+# 1. Install dependencies
+npm install
+
+# 2. Live preview with hot reload
+npm run dev
+
+# 3. Build the static portal (SSG) into dist/, then preview it
+npm run build
+npm run preview
+\`\`\`
+
+Run \`npm run validate\` (for example in CI) to check every spec in \`apis:\` against the OpenAPI schema. It also warns about operations without an \`operationId\`, whose links change when their summary is edited.
+
+## Project Structure
+
+\`\`\`text
+├── docs/                 # Documentation pages (.md, .markdoc, .mdx); docs/index.* is the home page
+├── specs/                # OpenAPI specifications (.yaml, .json)
+├── public/               # Static files (logo, favicon, images), served from /
+├── rapidoc.config.yaml   # Portal header, navigation tabs, theme and APIs
+├── package.json
+└── README.md
+\`\`\`
+`;
+
+const SPEC_EXTENSIONS = new Set([".yaml", ".yml", ".json"]);
+const SKIPPED_DIRS = new Set(["node_modules", "dist", "build", "coverage", ".rapidoc-temp"]);
+
+/**
+ * Finds OpenAPI / Swagger documents in a folder (and up to `maxDepth` levels below it), so a portal can be
+ * scaffolded around specs that already exist. A file counts when an `openapi:` or `swagger:` key appears
+ * in its first few kilobytes. Hidden folders and build output are skipped.
+ *
+ * @param {string} dir - Folder to search
+ * @param {object} [options] - { maxDepth = 3 }
+ * @returns {Array<string>} Spec paths relative to `dir`, with forward slashes, sorted
+ */
+export function findOpenApiSpecs(dir, { maxDepth = 3 } = {}) {
+  const root = path.resolve(dir);
+  const found = [];
+  const walk = (current, depth) => {
+    let entries;
+    try {
+      entries = fs.readdirSync(current, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (entry.name.startsWith(".")) continue;
+      const fullPath = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        if (depth < maxDepth && !SKIPPED_DIRS.has(entry.name)) walk(fullPath, depth + 1);
+      } else if (
+        SPEC_EXTENSIONS.has(path.extname(entry.name).toLowerCase()) &&
+        isOpenApiDocument(fullPath)
+      ) {
+        found.push(path.relative(root, fullPath).split(path.sep).join("/"));
+      }
+    }
+  };
+  walk(root, 0);
+  return found.sort();
+}
+
+function isOpenApiDocument(filePath) {
+  const fd = fs.openSync(filePath, "r");
+  try {
+    const buffer = Buffer.alloc(4096);
+    const bytesRead = fs.readSync(fd, buffer, 0, buffer.length, 0);
+    return /^\s*["']?(openapi|swagger)["']?\s*:/m.test(buffer.toString("utf8", 0, bytesRead));
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+// A valid npm package name from a folder name: lowercase, URL-safe, not starting with . or _
+// ("RapiDocPortal" -> "rapidocportal", "My Portal" -> "my-portal").
+function toPackageName(name) {
+  const cleaned = name
+    .toLowerCase()
+    .replace(/[^a-z0-9._~-]+/g, "-")
+    .replace(/^[._-]+|-+$/g, "")
+    .slice(0, 214);
+  return cleaned || "my-dev-portal";
+}
+
+// API ids and tab labels from spec file names: "specs/orders-api.yaml" -> { id: 'orders-api', label: 'Orders API' }
+function apisFromSpecs(specs) {
+  const used = new Set();
+  return specs.map((spec) => {
+    const base =
+      path
+        .basename(spec, path.extname(spec))
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-|-$/g, "") || "api";
+    let id = base;
+    for (let n = 2; used.has(id); n += 1) id = `${base}-${n}`;
+    used.add(id);
+    const label = base
+      .replace(/-/g, " ")
+      .replace(/\b\w/g, (c) => c.toUpperCase())
+      .replace(/\bApi\b/g, "API");
+    return { id, label, spec: `./${spec}` };
+  });
+}
+
+/** The site title a folder gets when none is given: `acme-docs` → "Acme Docs". */
+export function defaultSiteTitle(targetDir, name) {
+  const folderName = name || path.basename(path.resolve(targetDir)) || "my-dev-portal";
+  return folderName.replace(/[-_]/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+}
+
+/**
+ * What scaffoldProject would write, without writing anything: { projectName, siteTitle, apis, files },
+ * where files are { path, content }. `init` uses it to list the files --force would overwrite.
+ */
+export function planScaffold(targetDir, options = {}) {
+  const resolvedDir = path.resolve(targetDir);
+  const folderName = options.name || path.basename(resolvedDir) || "my-dev-portal";
+  const projectName = toPackageName(folderName);
+  const siteTitle = options.title || defaultSiteTitle(resolvedDir, options.name);
+  const withStarterSpec = !options.specs?.length;
+  const apis = withStarterSpec
+    ? [{ id: "core", label: "Core API", spec: "./specs/api.yaml" }]
+    : apisFromSpecs(options.specs);
+
+  const docsDir = path.join(resolvedDir, "docs");
+  const guidesDir = path.join(docsDir, "guides");
+  const specsDir = path.join(resolvedDir, "specs");
+
+  const files = [
+    {
+      path: path.join(resolvedDir, "rapidoc.config.yaml"),
+      content: STARTER_CONFIG(siteTitle, apis),
+    },
+    { path: path.join(resolvedDir, "package.json"), content: STARTER_PACKAGE_JSON(projectName) },
+    { path: path.join(resolvedDir, ".gitignore"), content: STARTER_GITIGNORE },
+    { path: path.join(resolvedDir, "README.md"), content: STARTER_README(siteTitle) },
+    ...(withStarterSpec ? [{ path: path.join(specsDir, "api.yaml"), content: STARTER_SPEC }] : []),
+    { path: path.join(docsDir, "index.markdoc"), content: STARTER_HOME(siteTitle, apis[0].id) },
+    { path: path.join(docsDir, "getting-started.md"), content: STARTER_GETTING_STARTED },
+    { path: path.join(guidesDir, "overview.markdoc"), content: STARTER_OVERVIEW(withStarterSpec) },
+  ];
+  return { targetDir: resolvedDir, projectName, siteTitle, apis, files };
+}
+
+/**
+ * Scaffolds a new RapiDoc Developer Portal into target directory. Existing files are left alone unless
+ * `overwrite` is set (they are listed in `filesSkipped`), so it can also add a portal to an existing repo.
+ *
+ * @param {string} targetDir - Destination directory path
+ * @param {object} [options] - { name, title, overwrite, specs }. `specs` lists OpenAPI files (relative to
+ *   targetDir) to use instead of the starter spec; see findOpenApiSpecs.
+ * @returns {{ targetDir: string, projectName: string, siteTitle: string, apis: Array<object>,
+ *   filesCreated: Array<string>, filesSkipped: Array<string> }}
+ */
+export function scaffoldProject(targetDir, options = {}) {
+  const {
+    targetDir: resolvedDir,
+    projectName,
+    siteTitle,
+    apis,
+    files,
+  } = planScaffold(targetDir, options);
+  for (const file of files) fs.mkdirSync(path.dirname(file.path), { recursive: true });
+
+  const filesCreated = [];
+  const filesSkipped = [];
+  for (const file of files) {
+    if (!fs.existsSync(file.path) || options.overwrite) {
+      fs.writeFileSync(file.path, file.content, "utf8");
+      filesCreated.push(file.path);
+    } else {
+      filesSkipped.push(file.path);
+    }
+  }
+
+  return {
+    targetDir: resolvedDir,
+    projectName,
+    siteTitle,
+    apis,
+    filesCreated,
+    filesSkipped,
+  };
+}

package/src/wizard.js

@@ -0,0 +1,44 @@
+import { defaultSiteTitle } from "./scaffold.js";
+
+/**
+ * The questions `rapidoc init` and `npm create rapidoc` ask in a terminal, for whatever the command line
+ * didn't already say. Each one is also an option (--title, --spec / --starter-spec, --install /
+ * --no-install), so a run can be repeated without questions.
+ *
+ * @param {object} args
+ * @param {{ text: Function, multiselect: Function, confirm: Function }} args.ask - prompt functions
+ *   (@clack/prompts' signatures): the CLI passes its lib/prompt.js, create-rapidoc its own.
+ * @param {string} args.targetDir - The portal folder.
+ * @param {string[]} args.foundSpecs - OpenAPI files found there (findOpenApiSpecs), relative to it.
+ * @param {{ title?: string, specs?: string[], install?: boolean }} args.known - Answers the command line
+ *   already gave; `undefined` means ask. `specs: []` means the starter spec.
+ * @param {boolean} [args.askInstall=true] - Whether to ask about `npm install` (not when the folder
+ *   already has a package.json, which the scaffold leaves alone).
+ * @returns {Promise<{ title?: string, specs?: string[], install?: boolean }>}
+ */
+export async function askInitQuestions({ ask, targetDir, foundSpecs, known, askInstall = true }) {
+  const answers = { ...known };
+  if (answers.title === undefined) {
+    const fallback = defaultSiteTitle(targetDir);
+    answers.title = await ask.text({
+      message: "Site title",
+      placeholder: fallback,
+      defaultValue: fallback,
+    });
+  }
+  if (answers.specs === undefined && foundSpecs.length) {
+    answers.specs = await ask.multiselect({
+      message: `OpenAPI files to include (${foundSpecs.length} found; none selected = a starter spec)`,
+      options: foundSpecs.map((spec) => ({ value: spec, label: spec })),
+      initialValues: foundSpecs,
+      required: false,
+    });
+  }
+  if (askInstall && answers.install === undefined) {
+    answers.install = await ask.confirm({
+      message: "Install the dependencies with npm now?",
+      initialValue: true,
+    });
+  }
+  return answers;
+}