create-sailor 1.4.0 → 1.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-sailor",
-  "version": "1.4.0",
+  "version": "1.4.1",
   "description": "Governed AI-native SaaS scaffolder for Nebutra Sailor. Bootstrap a production-ready Next.js + Hono + Prisma monorepo with multi-tenant foundations, region-aware defaults, and AI integrations.",
   "type": "module",
   "main": "dist/index.js",
@@ -9,6 +9,7 @@
   },
   "files": [
     "dist",
+    "templates",
     "README.md",
     "LICENSE"
   ],

package/templates/deploy/Dockerfile.web

@@ -0,0 +1,57 @@
+FROM node:22-alpine AS base
+
+# Install dependencies only when needed
+FROM base AS deps
+RUN apk add --no-cache libc6-compat
+WORKDIR /app
+
+# Enable corepack for pnpm
+RUN corepack enable pnpm
+
+COPY package.json pnpm-lock.yaml* ./
+COPY turbo.json ./
+COPY patches ./patches
+COPY apps/web/package.json ./apps/web/
+COPY backends/gateway/package.json ./backends/gateway/
+COPY packages/*/package.json ./packages/
+RUN pnpm install --frozen-lockfile
+
+# Rebuild the source code only when needed
+FROM base AS builder
+WORKDIR /app
+RUN corepack enable pnpm
+COPY --from=deps /app/node_modules ./node_modules
+COPY . .
+
+# Pass nextjs env vars for build time if necessary
+ENV NEXT_TELEMETRY_DISABLED 1
+RUN pnpm run build
+
+# Production image, copy all the files and run next
+FROM base AS runner
+WORKDIR /app
+
+ENV NODE_ENV production
+ENV NEXT_TELEMETRY_DISABLED 1
+
+RUN addgroup --system --gid 1001 nodejs
+RUN adduser --system --uid 1001 nextjs
+
+# Set the correct permission for prerender cache
+RUN mkdir .next
+RUN chown nextjs:nodejs .next
+
+# Automatically leverage output traces to reduce image size
+# https://nextjs.org/docs/advanced-features/output-file-tracing
+COPY --from=builder --chown=nextjs:nodejs /app/apps/web/.next/standalone ./
+COPY --from=builder --chown=nextjs:nodejs /app/apps/web/.next/static ./apps/web/.next/static
+COPY --from=builder --chown=nextjs:nodejs /app/apps/web/public ./apps/web/public
+
+USER nextjs
+
+EXPOSE 3000
+
+ENV PORT 3000
+ENV HOSTNAME "0.0.0.0"
+
+CMD ["node", "apps/web/server.js"]

package/templates/deploy/docker-compose.yml

@@ -0,0 +1,40 @@
+version: '3.8'
+
+services:
+  web:
+    build: 
+      context: .
+      dockerfile: Dockerfile.web
+    ports:
+      - "3000:3000"
+    environment:
+      - DATABASE_URL=postgresql://postgres:postgres@db:5432/nebutra
+      - REDIS_URL=redis://redis:6379
+    depends_on:
+      - db
+      - redis
+    restart: always
+
+  db:
+    image: postgres:15-alpine
+    environment:
+      - POSTGRES_USER=postgres
+      - POSTGRES_PASSWORD=postgres
+      - POSTGRES_DB=nebutra
+    ports:
+      - "5432:5432"
+    volumes:
+      - pgdata:/var/lib/postgresql/data
+    restart: always
+
+  redis:
+    image: redis:7-alpine
+    ports:
+      - "6379:6379"
+    volumes:
+      - redisdata:/data
+    restart: always
+
+volumes:
+  pgdata:
+  redisdata:

package/templates/deploy/railway.toml

@@ -0,0 +1,13 @@
+[build]
+builder = "NIXPACKS"
+buildCommand = "pnpm build"
+
+[build.nixpacksPlan.phases.setup]
+nixPkgs = ["...", "pnpm-8_x"]
+
+[deploy]
+startCommand = "pnpm start"
+healthcheckPath = "/api/health"
+healthcheckTimeout = 100
+restartPolicyType = "ON_FAILURE"
+restartPolicyMaxRetries = 5

package/templates/deploy/vercel.json

@@ -0,0 +1,37 @@
+{
+  "version": 2,
+  "buildCommand": "pnpm build",
+  "ignoreCommand": "bash ./scripts/ignore-build-step.sh",
+  "framework": "nextjs",
+  "crons": [
+    {
+      "path": "/api/webhooks/cron/daily",
+      "schedule": "0 0 * * *"
+    }
+  ],
+  "headers": [
+    {
+      "source": "/(.*)",
+      "headers": [
+        {
+          "key": "X-Content-Type-Options",
+          "value": "nosniff"
+        },
+        {
+          "key": "X-Frame-Options",
+          "value": "DENY"
+        },
+        {
+          "key": "X-XSS-Protection",
+          "value": "1; mode=block"
+        }
+      ]
+    }
+  ],
+  "rewrites": [
+    {
+      "source": "/api/auth/:path*",
+      "destination": "/api/auth/:path*"
+    }
+  ]
+}

package/templates/deploy/wrangler.toml

@@ -0,0 +1,8 @@
+name = "nebutra-sailor"
+compatibility_date = "2024-03-20"
+compatibility_flags = ["nodejs_compat"]
+pages_build_output_dir = ".opennext"
+
+[env.production]
+# Add your production variables here
+# DATABASE_URL = "postgress://..."

package/templates/docs/docusaurus/README.md

@@ -0,0 +1,24 @@
+# {PRODUCT_NAME} Docs
+
+Documentation site for {PRODUCT_NAME}, built with [Docusaurus 3](https://docusaurus.io/).
+
+## Develop
+
+```bash
+pnpm install
+pnpm dev          # http://localhost:3001
+```
+
+## Add a page
+
+1. Drop a `.md` or `.mdx` file under `docs/`
+2. Add the path to `sidebars.ts` (or use auto-generated sidebars)
+
+## Deploy
+
+```bash
+pnpm build        # static output -> build/
+pnpm serve        # preview locally
+```
+
+The `build/` directory can be hosted on any static host (Vercel, Cloudflare Pages, S3, GitHub Pages).

package/templates/docs/docusaurus/docs/getting-started/develop.md

@@ -0,0 +1,20 @@
+---
+sidebar_position: 2
+---
+
+# Develop
+
+```bash
+pnpm dev          # http://localhost:3001
+```
+
+The site rebuilds on file change. New pages: drop a `.md` or `.mdx` under `docs/` and add it to `sidebars.ts`.
+
+## Build for production
+
+```bash
+pnpm build
+pnpm serve
+```
+
+The static output is written to `build/` — host it on any CDN.

package/templates/docs/docusaurus/docs/getting-started/install.md

@@ -0,0 +1,11 @@
+---
+sidebar_position: 1
+---
+
+# Install
+
+```bash
+pnpm install
+```
+
+That's it — Docusaurus has no separate setup step.

package/templates/docs/docusaurus/docs/intro.md

@@ -0,0 +1,15 @@
+---
+sidebar_position: 1
+slug: /
+---
+
+# Welcome to {PRODUCT_NAME}
+
+This is the documentation site for **{PRODUCT_NAME}**, scaffolded by [create-sailor](https://github.com/Nebutra/Nebutra-Sailor) with [Docusaurus 3](https://docusaurus.io/).
+
+## What's next
+
+- [Install dependencies](./getting-started/install.md)
+- [Run the dev server](./getting-started/develop.md)
+
+Edit `docs/intro.md` to change this page.

package/templates/docs/docusaurus/docusaurus.config.ts

@@ -0,0 +1,66 @@
+import type * as Preset from "@docusaurus/preset-classic";
+import type { Config } from "@docusaurus/types";
+import { themes as prismThemes } from "prism-react-renderer";
+
+const config: Config = {
+  title: "{PRODUCT_NAME}",
+  tagline: "Documentation for {PRODUCT_NAME}",
+  favicon: "img/favicon.ico",
+
+  url: "https://docs.example.com",
+  baseUrl: "/",
+
+  organizationName: "your-org",
+  projectName: "your-repo",
+
+  onBrokenLinks: "throw",
+  onBrokenMarkdownLinks: "warn",
+
+  i18n: {
+    defaultLocale: "en",
+    locales: ["en"],
+  },
+
+  presets: [
+    [
+      "classic",
+      {
+        docs: {
+          sidebarPath: "./sidebars.ts",
+          editUrl: "https://github.com/your-org/your-repo/tree/main/docs/",
+          routeBasePath: "/",
+        },
+        blog: false,
+        theme: {
+          customCss: "./src/css/custom.css",
+        },
+      } satisfies Preset.Options,
+    ],
+  ],
+
+  themeConfig: {
+    image: "img/social-card.png",
+    navbar: {
+      title: "{PRODUCT_NAME}",
+      logo: { alt: "{PRODUCT_NAME}", src: "img/logo.svg" },
+      items: [
+        { type: "docSidebar", sidebarId: "tutorialSidebar", position: "left", label: "Docs" },
+        {
+          href: "https://github.com/your-org/your-repo",
+          label: "GitHub",
+          position: "right",
+        },
+      ],
+    },
+    footer: {
+      style: "dark",
+      copyright: "Copyright © " + new Date().getFullYear() + " {PRODUCT_NAME}.",
+    },
+    prism: {
+      theme: prismThemes.github,
+      darkTheme: prismThemes.dracula,
+    },
+  } satisfies Preset.ThemeConfig,
+};
+
+export default config;

package/templates/docs/docusaurus/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@nebutra/docs",
+  "private": true,
+  "version": "0.0.1",
+  "scripts": {
+    "dev": "docusaurus start --port 3001",
+    "start": "docusaurus start --port 3001",
+    "build": "docusaurus build",
+    "serve": "docusaurus serve --port 3001",
+    "typecheck": "tsc --noEmit",
+    "clear": "docusaurus clear"
+  },
+  "dependencies": {
+    "@docusaurus/core": "^3.7.0",
+    "@docusaurus/preset-classic": "^3.7.0",
+    "@mdx-js/react": "^3.0.1",
+    "clsx": "^2.1.1",
+    "prism-react-renderer": "^2.4.1",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@docusaurus/module-type-aliases": "^3.7.0",
+    "@docusaurus/tsconfig": "^3.7.0",
+    "@docusaurus/types": "^3.7.0",
+    "typescript": "^5.9.3"
+  },
+  "browserslist": {
+    "production": [
+      ">0.5%",
+      "not dead",
+      "not op_mini all"
+    ],
+    "development": [
+      "last 3 chrome version",
+      "last 3 firefox version",
+      "last 5 safari version"
+    ]
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}

package/templates/docs/docusaurus/sidebars.ts

@@ -0,0 +1,14 @@
+import type { SidebarsConfig } from "@docusaurus/plugin-content-docs";
+
+const sidebars: SidebarsConfig = {
+  tutorialSidebar: [
+    "intro",
+    {
+      type: "category",
+      label: "Getting started",
+      items: ["getting-started/install", "getting-started/develop"],
+    },
+  ],
+};
+
+export default sidebars;

package/templates/docs/docusaurus/src/css/custom.css

@@ -0,0 +1,22 @@
+:root {
+  --ifm-color-primary: #0033fe;
+  --ifm-color-primary-dark: #002de5;
+  --ifm-color-primary-darker: #002bd9;
+  --ifm-color-primary-darkest: #0023b3;
+  --ifm-color-primary-light: #1f4cff;
+  --ifm-color-primary-lighter: #2d57ff;
+  --ifm-color-primary-lightest: #5a78ff;
+  --ifm-code-font-size: 95%;
+  --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.1);
+}
+
+[data-theme="dark"] {
+  --ifm-color-primary: #4d72ff;
+  --ifm-color-primary-dark: #2d57ff;
+  --ifm-color-primary-darker: #1f4cff;
+  --ifm-color-primary-darkest: #0033fe;
+  --ifm-color-primary-light: #6d8aff;
+  --ifm-color-primary-lighter: #7d97ff;
+  --ifm-color-primary-lightest: #adbfff;
+  --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.3);
+}

package/templates/docs/docusaurus/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "extends": "@docusaurus/tsconfig",
+  "compilerOptions": {
+    "baseUrl": "."
+  },
+  "exclude": [".docusaurus", "build"]
+}

package/templates/docs/fumadocs/README.md

@@ -0,0 +1,46 @@
+# {PRODUCT_NAME} Docs
+
+Documentation site for {PRODUCT_NAME}, built with [Fumadocs](https://fumadocs.vercel.app/) + Next.js 16 + Tailwind v4.
+
+## Run locally
+
+```bash
+pnpm --filter @nebutra/docs dev
+```
+
+Opens on http://localhost:3001.
+
+## Edit content
+
+MDX source lives in `content/docs/`. Each file becomes a page under `/docs/<slug>`.
+
+- Add a new page → create `content/docs/my-page.mdx`
+- Control sidebar order → edit `content/docs/meta.json`
+- Use built-in components (`<Cards>`, `<Card>`, `<Tabs>`, `<Tab>`, `<Callout>`, etc.) directly in MDX — they come from `fumadocs-ui/mdx`.
+
+## Customize
+
+- **Branding / colors**: wired to `@nebutra/tokens` via `app/global.css`. Edit tokens centrally, not here.
+- **Sidebar / nav**: `app/docs/layout.tsx` — `DocsLayout` props.
+- **Search**: `app/api/search/route.ts` auto-indexes all MDX via `createFromSource`.
+- **MDX plugins**: `source.config.ts` → `mdxOptions`.
+
+Full Fumadocs reference: https://fumadocs.vercel.app/docs.
+
+## 2026 docs best practices
+
+This template follows Nebutra docs best-practices, encoded as MDX comments inline in each starter page:
+
+- **Home** — hero + 3-6 cards, no marketing fluff
+- **Getting Started** — single goal: 5-minute first example (Install → Initialize → Hello World → Next steps)
+- **Concepts** — explains the "why" / mental model, not steps, not APIs
+- **API Reference** — auto-generated from OpenAPI; every endpoint has method badge + params + schema + multi-language examples
+
+When refreshing the API reference inputs:
+
+```bash
+pnpm --filter @nebutra/gateway generate:spec
+pnpm generate:api-types
+```
+
+Then replace `content/docs/api.mdx` with generated reference content sourced from `backends/gateway/openapi.json`.

package/templates/docs/fumadocs/app/(home)/page.tsx

@@ -0,0 +1,22 @@
+import Link from "next/link";
+
+export const dynamic = "force-static";
+
+export default function HomePage() {
+  return (
+    <main className="flex flex-1 flex-col items-center justify-center gap-6 px-4 py-24 text-center">
+      <h1 className="text-4xl font-bold tracking-tight sm:text-5xl">
+        {"{PRODUCT_NAME}"} Documentation
+      </h1>
+      <p className="max-w-xl text-lg text-fd-muted-foreground">
+        Build AI-native SaaS products faster. Everything you need to ship is documented here.
+      </p>
+      <Link
+        href="/docs"
+        className="rounded-md bg-fd-primary px-6 py-3 font-semibold text-fd-primary-foreground transition-opacity hover:opacity-90"
+      >
+        Read the docs
+      </Link>
+    </main>
+  );
+}

package/templates/docs/fumadocs/app/api/search/route.ts

@@ -0,0 +1,4 @@
+import { createFromSource } from "fumadocs-core/search/server";
+import { source } from "@/lib/source";
+
+export const { GET } = createFromSource(source);

package/templates/docs/fumadocs/app/docs/[[...slug]]/page.tsx

@@ -0,0 +1,39 @@
+import defaultMdxComponents from "fumadocs-ui/mdx";
+import { DocsBody, DocsDescription, DocsPage, DocsTitle } from "fumadocs-ui/page";
+import { notFound } from "next/navigation";
+import { source } from "@/lib/source";
+
+export const dynamic = "force-static";
+
+export default async function Page(props: { params: Promise<{ slug?: string[] }> }) {
+  const params = await props.params;
+  const page = source.getPage(params.slug);
+  if (!page) notFound();
+
+  const MDX = page.data.body;
+
+  return (
+    <DocsPage toc={page.data.toc} full={page.data.full}>
+      <DocsTitle>{page.data.title}</DocsTitle>
+      <DocsDescription>{page.data.description}</DocsDescription>
+      <DocsBody>
+        <MDX components={{ ...defaultMdxComponents }} />
+      </DocsBody>
+    </DocsPage>
+  );
+}
+
+export function generateStaticParams() {
+  return source.generateParams();
+}
+
+export async function generateMetadata(props: { params: Promise<{ slug?: string[] }> }) {
+  const params = await props.params;
+  const page = source.getPage(params.slug);
+  if (!page) notFound();
+
+  return {
+    title: page.data.title,
+    description: page.data.description,
+  };
+}

package/templates/docs/fumadocs/app/docs/layout.tsx

@@ -0,0 +1,11 @@
+import { DocsLayout } from "fumadocs-ui/layouts/docs";
+import type { ReactNode } from "react";
+import { source } from "@/lib/source";
+
+export default function Layout({ children }: { children: ReactNode }) {
+  return (
+    <DocsLayout tree={source.pageTree} nav={{ title: "{PRODUCT_NAME}" }}>
+      {children}
+    </DocsLayout>
+  );
+}

package/templates/docs/fumadocs/app/global.css

@@ -0,0 +1,10 @@
+@import "tailwindcss";
+@import "fumadocs-ui/css/neutral.css";
+@import "fumadocs-ui/css/preset.css";
+
+/* Pull in Nebutra design tokens (brand colors, semantic scales, gradients). */
+@import "@nebutra/tokens/styles.css";
+
+/* Tell Tailwind v4 to scan @nebutra/ui source so its utility classes compile. */
+@source "../node_modules/@nebutra/ui/src/**/*.{ts,tsx}";
+@source "../node_modules/fumadocs-ui/dist/**/*.js";

package/templates/docs/fumadocs/app/layout.tsx

@@ -0,0 +1,18 @@
+import { RootProvider } from "fumadocs-ui/provider";
+import type { ReactNode } from "react";
+import "./global.css";
+
+export const metadata = {
+  title: "{PRODUCT_NAME} Docs",
+  description: "Documentation for {PRODUCT_NAME}",
+};
+
+export default function RootLayout({ children }: { children: ReactNode }) {
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <body className="flex min-h-screen flex-col">
+        <RootProvider>{children}</RootProvider>
+      </body>
+    </html>
+  );
+}

package/templates/docs/fumadocs/content/docs/api.mdx

@@ -0,0 +1,31 @@
+---
+title: API Reference
+description: Complete API documentation
+---
+
+{/* 2026 BEST PRACTICE: API Reference should be auto-generated from OpenAPI spec */}
+{/* 2026 BEST PRACTICE: Every endpoint needs: Method badge, params table, response schema, multi-language examples */}
+{/* TODO: Export backends/gateway/openapi.json and replace this starter page with generated reference content. */}
+
+# API Reference
+
+API documentation is easiest to maintain when it is generated from your OpenAPI spec.
+
+To refresh the source spec and the shared TypeScript types in `apps/web`:
+
+```bash
+pnpm --filter @nebutra/gateway generate:spec
+pnpm generate:api-types
+```
+
+## Endpoints
+
+### GET /hello
+
+Returns a hello message.
+
+**Response**:
+
+```json
+{ "message": "Hello, world!" }
+```

package/templates/docs/fumadocs/content/docs/concepts.mdx

@@ -0,0 +1,19 @@
+---
+title: Concepts
+description: Core mental models and design decisions
+---
+
+{/* 2026 BEST PRACTICE: Concepts explains the "why" and mental model */}
+{/* 2026 BEST PRACTICE: Don't explain steps — that's Guides. Don't list APIs — that's API Reference */}
+
+# Concepts
+
+Understand the core models and design decisions.
+
+## Workspaces
+
+A workspace is...
+
+## Authentication
+
+...

package/templates/docs/fumadocs/content/docs/getting-started.mdx

@@ -0,0 +1,56 @@
+---
+title: Getting Started
+description: Run your first example in 5 minutes
+---
+
+{/* 2026 BEST PRACTICE: Getting Started's ONLY goal is 5-minute first example */}
+{/* 2026 BEST PRACTICE: No architecture explanation here — that belongs in Concepts */}
+{/* 2026 BEST PRACTICE: Structure: Install → Initialize → Hello World → Next steps */}
+
+# Getting Started
+
+## Install
+
+```bash
+npm install @your-product/sdk
+```
+
+## Initialize
+
+```ts title="src/index.ts"
+import { YourProduct } from '@your-product/sdk';
+
+const client = new YourProduct({
+  apiKey: process.env.YOUR_API_KEY,
+});
+```
+
+## Hello World
+
+<Tabs items={['TypeScript', 'Python', 'cURL']}>
+<Tab value="TypeScript">
+```ts
+const result = await client.hello();
+console.log(result);
+```
+</Tab>
+<Tab value="Python">
+```python
+result = client.hello()
+print(result)
+```
+</Tab>
+<Tab value="cURL">
+```bash
+curl https://api.your-product.com/hello \
+  -H "Authorization: Bearer $YOUR_API_KEY"
+```
+</Tab>
+</Tabs>
+
+## Next steps
+
+<Cards>
+  <Card title="Concepts" href="/docs/concepts" />
+  <Card title="API Reference" href="/docs/api" />
+</Cards>