create-stitchkit 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,46 @@
+# Changelog
+
+All notable changes to **create-stitchkit** are documented here. The scaffolder
+has its own version and release line; the Stitchkit range tested by its template
+is declared in the template root catalog.
+
+## [Unreleased]
+
+## [0.1.0] — 2026-08-08
+
+### Added
+
+- **Production-shaped official starter.** `bun create stitchkit my-app`
+  generates a Bun workspace with a separate Next.js frontend and Stitchkit API,
+  Prisma/PostgreSQL, shared contracts, typed HTTP and React Query clients,
+  Socket.IO cache updates, OpenAPI, MCP, CLI, a production-shaped reference app and a
+  complete `/ui` component catalogue.
+- **Complete starter SEO surface.** A typed locale-aware page registry now drives
+  unique page metadata, canonical and language alternatives, Open Graph and
+  Twitter cards, sitemap entries and visible catalogue headings.
+- **Direct PM2 entrypoints.** Development and production configs supervise Bun
+  and Next entrypoints without package-script wrappers.
+- **External PostgreSQL boundary.** Generated applications own Prisma schemas
+  and migrations but connect to environment-provided PostgreSQL exclusively
+  through `DATABASE_URL`; they do not package or start a database runtime.
+- **One runnable canonical template.** Starter development now runs directly
+  from `packages/create-stitchkit/template` with Bun/Next HMR; generated
+  consumers exist only as ephemeral release-lane fixtures.
+- **Fleet-shaped workspace layout.** Backend, frontend, config, database and
+  shared code live together under one `packages/*` namespace.
+- **Self-contained consumer gates.** A fresh scaffold generates its Prisma
+  client before typechecking, remains lint-clean after a Next build and excludes
+  runtime test artifacts from the published tarball.
+- **Canonical status palette.** Success and destructive states use the source
+  UI system hues in both themes with accessible foreground contrast.
+- **Compact reference surface.** The starter home now fits one desktop viewport
+  and demonstrates one PostgreSQL-backed repository query, one refresh mutation,
+  cache invalidation and realtime propagation without shipping a demo CRUD domain.
+- **Removable component catalogue.** Every catalogue-only screen and composition
+  lives under the `/ui` route directory, while reusable primitives stay in
+  `components/ui`; its desktop navigation is a compact floating palette.
+- **Generated Next.js declarations stay generated.** `next-env.d.ts` is ignored
+  and `next typegen` runs before standalone TypeScript checks, preventing dev/build churn.
+- **Independent compatibility target.** The committed template catalog and
+  lockfile keep generated projects on the last explicitly validated Stitchkit
+  range until a separate starter release advances it.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Max Listov
+
+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

@@ -0,0 +1,35 @@
+# create-stitchkit
+
+Create the canonical Stitchkit application:
+
+```bash
+bun create stitchkit my-app
+cd my-app
+# Point DATABASE_URL in .env at your PostgreSQL database.
+bun run dev
+```
+
+The generated Bun workspace contains a Next.js frontend, a separate Stitchkit
+API, Prisma/PostgreSQL, typed shared contracts, Socket.IO, MCP, CLI tools and a
+complete production UI system.
+
+It uses one conventional `packages/*` namespace: `backend`, `frontend`,
+`config`, `db` and `shared`. The copied application keeps the neutral
+`stitchkit-starter` identity until its owner explicitly renames it.
+
+Its runnable example is the Stitchkit Starter: one configurable GitHub repository
+is persisted through a server-side PostgreSQL cache, including a Prisma-backed
+visibility enum that flows through the shared schema and typed client. `/en/ui`
+presents every reusable primitive and composition. Every public page ships with
+localized metadata, canonical and language alternatives, sitemap coverage and a
+generated Open Graph card.
+
+The included PM2 configs launch Bun and Next entrypoints directly, so package
+script wrappers do not hide the supervised processes or distort their metrics.
+PostgreSQL is supplied by the application environment through `DATABASE_URL`;
+the generated project does not package or start a database runtime.
+
+The generated workspace uses the Stitchkit range declared once in the template
+catalog and ships with the exact lockfile validated by this package. Framework
+and scaffolder releases are independent: a new Stitchkit version does not move
+the starter until that target is deliberately updated and revalidated.

package/dist/cli.js

@@ -0,0 +1,230 @@
+#!/usr/bin/env bun
+// @bun
+
+// src/cli.ts
+import { basename as basename2, resolve as resolve2 } from "path";
+var {spawn } = globalThis.Bun;
+
+// src/options.ts
+var HELP = `Create a production-shaped Stitchkit application.
+
+Usage:
+  bun create stitchkit <directory> [--no-install]
+
+Options:
+  --no-install  Generate files without installing dependencies
+  --help        Show this help
+`;
+function helpText() {
+  return HELP;
+}
+function parseOptions(args) {
+  if (args.includes("--help") || args.includes("-h"))
+    return "help";
+  const unknown = args.filter((arg) => arg.startsWith("-") && arg !== "--no-install");
+  if (unknown.length > 0) {
+    throw new Error(`Unknown option: ${unknown[0]}`);
+  }
+  const positionals = args.filter((arg) => !arg.startsWith("-"));
+  if (positionals.length !== 1) {
+    throw new Error("Exactly one destination directory is required");
+  }
+  const destination = positionals[0];
+  if (destination === undefined)
+    throw new Error("Destination directory is required");
+  return {
+    destination,
+    install: !args.includes("--no-install")
+  };
+}
+
+// src/scaffold.ts
+import { lstat, mkdir, readdir, readFile, rm, writeFile } from "fs/promises";
+import { homedir } from "os";
+import { basename, dirname, join, parse, relative, resolve, sep } from "path";
+var TEXT_EXTENSIONS = new Set([
+  ".cjs",
+  ".css",
+  ".example",
+  ".html",
+  ".js",
+  ".json",
+  ".lock",
+  ".md",
+  ".mjs",
+  ".prisma",
+  ".sql",
+  ".ts",
+  ".tsx",
+  ".txt",
+  ".yaml",
+  ".yml"
+]);
+var TEMPLATE_RENAMES = new Map([
+  ["_env", ".env"],
+  ["_env.example", ".env.example"],
+  ["_gitignore", ".gitignore"]
+]);
+var IGNORED_DIRECTORIES = new Set([
+  ".next",
+  "coverage",
+  "dist",
+  "node_modules",
+  "playwright-report",
+  "test-results"
+]);
+function isTemplateSourcePathIncluded(sourcePath) {
+  const normalized = sourcePath.replaceAll("\\", "/").replace(/^\.\//, "");
+  if (!normalized)
+    return true;
+  const segments = normalized.split("/");
+  if (segments.some((segment) => IGNORED_DIRECTORIES.has(segment)))
+    return false;
+  if (normalized === "packages/db/src/generated" || normalized.startsWith("packages/db/src/generated/"))
+    return false;
+  const name = basename(normalized);
+  return name !== ".env" && name !== "next-env.d.ts" && !name.endsWith(".log") && !name.endsWith(".tsbuildinfo");
+}
+function shouldIncludeTemplatePath(templateDirectory, sourcePath) {
+  return isTemplateSourcePathIncluded(relative(templateDirectory, sourcePath));
+}
+function portablePath(path) {
+  return path.split(sep).join("/");
+}
+function isUnsafeDestination(destination) {
+  const root = parse(destination).root;
+  const home = resolve(homedir());
+  return destination === root || destination === home;
+}
+async function assertDestinationAvailable(destination) {
+  if (isUnsafeDestination(destination)) {
+    throw new Error("Refusing to scaffold into a filesystem root or home directory");
+  }
+  try {
+    const info = await lstat(destination);
+    if (info.isSymbolicLink()) {
+      throw new Error(`Destination cannot be a symbolic link: ${destination}`);
+    }
+    if (!info.isDirectory()) {
+      throw new Error(`Destination exists and is not a directory: ${destination}`);
+    }
+    const entries = await readdir(destination);
+    if (entries.length > 0) {
+      throw new Error(`Destination is not empty: ${destination}`);
+    }
+    return true;
+  } catch (error) {
+    if (error instanceof Error && "code" in error && error.code === "ENOENT")
+      return false;
+    throw error;
+  }
+}
+async function collectMaterialisedFiles(templateDirectory, directory, files) {
+  const entries = await readdir(directory, { withFileTypes: true });
+  entries.sort((left, right) => left.name.localeCompare(right.name));
+  for (const entry of entries) {
+    const sourcePath = join(directory, entry.name);
+    if (!shouldIncludeTemplatePath(templateDirectory, sourcePath))
+      continue;
+    if (entry.isDirectory()) {
+      await collectMaterialisedFiles(templateDirectory, sourcePath, files);
+      continue;
+    }
+    if (!entry.isFile()) {
+      throw new Error(`Template entries must be files or directories: ${sourcePath}`);
+    }
+    const targetName = TEMPLATE_RENAMES.get(entry.name);
+    const sourceRelativePath = relative(templateDirectory, sourcePath);
+    const outputRelativePath = targetName ? join(dirname(sourceRelativePath), targetName) : sourceRelativePath;
+    const extension = targetName?.includes(".") ? targetName.slice(targetName.indexOf(".")) : "";
+    const fileExtension = extension || sourcePath.slice(sourcePath.lastIndexOf("."));
+    const content = TEXT_EXTENSIONS.has(fileExtension) || targetName ? await readFile(sourcePath, "utf8") : await readFile(sourcePath);
+    files.push({
+      sourcePath: portablePath(sourceRelativePath),
+      outputPath: portablePath(outputRelativePath),
+      content
+    });
+  }
+}
+async function materialiseTemplateFiles(templateDirectory) {
+  const files = [];
+  await collectMaterialisedFiles(templateDirectory, templateDirectory, files);
+  return files;
+}
+async function writeMaterialisedFiles(destination, files) {
+  for (const file of files) {
+    const targetPath = join(destination, file.outputPath);
+    await mkdir(dirname(targetPath), { recursive: true });
+    await writeFile(targetPath, file.content);
+  }
+}
+async function scaffoldProject(templateDirectory, destination) {
+  const resolvedDestination = resolve(destination);
+  const destinationExisted = await assertDestinationAvailable(resolvedDestination);
+  await mkdir(resolvedDestination, { recursive: true });
+  try {
+    await writeMaterialisedFiles(resolvedDestination, await materialiseTemplateFiles(templateDirectory));
+  } catch (error) {
+    if (!destinationExisted) {
+      await rm(resolvedDestination, { recursive: true, force: true });
+    } else {
+      const entries = await readdir(resolvedDestination);
+      await Promise.all(entries.map((entry) => rm(join(resolvedDestination, entry), { recursive: true, force: true })));
+    }
+    throw error;
+  }
+}
+
+// src/cli.ts
+async function run(args) {
+  try {
+    const options = parseOptions(args);
+    if (options === "help") {
+      process.stdout.write(helpText());
+      return 0;
+    }
+    const destination = resolve2(options.destination);
+    const templateDirectory = resolve2(import.meta.dir, "../template");
+    await scaffoldProject(templateDirectory, destination);
+    if (options.install) {
+      const install = spawn(["bun", "install"], {
+        cwd: destination,
+        stdin: "inherit",
+        stdout: "inherit",
+        stderr: "inherit"
+      });
+      const exitCode = await install.exited;
+      if (exitCode !== 0)
+        throw new Error(`bun install failed with exit code ${exitCode}`);
+    }
+    process.stdout.write(`
+Created Stitchkit Starter in ${basename2(destination)}
+
+`);
+    process.stdout.write(`  cd ${options.destination}
+`);
+    process.stdout.write(`  bun run dev
+
+`);
+    process.stdout.write(`Web: http://localhost:3210
+`);
+    process.stdout.write(`API: http://localhost:3211
+`);
+    process.stdout.write(`MCP: http://localhost:3211/mcp
+`);
+    process.stdout.write(`OpenAPI: http://localhost:3211/openapi.json
+`);
+    return 0;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`create-stitchkit: ${message}
+`);
+    return 1;
+  }
+}
+if (import.meta.main) {
+  process.exitCode = await run(Bun.argv.slice(2));
+}
+export {
+  run
+};

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "create-stitchkit",
+  "version": "0.1.0",
+  "description": "Create a production-shaped Stitchkit application",
+  "license": "MIT",
+  "author": "Max Listov <maxlistov@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/max-listov/stitchkit.git",
+    "directory": "packages/create-stitchkit"
+  },
+  "type": "module",
+  "bin": {
+    "create-stitchkit": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "template/**/*",
+    "!template/**/.env",
+    "!template/**/node_modules/**",
+    "!template/**/.next/**",
+    "!template/**/dist/**",
+    "!template/**/playwright-report/**",
+    "!template/**/test-results/**",
+    "!template/**/next-env.d.ts",
+    "!template/**/src/generated/**",
+    "!template/**/*.log",
+    "!template/**/*.tsbuildinfo",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "check": "bun x tsc --noEmit",
+    "test": "bun test tests",
+    "build": "rm -rf dist && bun build src/cli.ts --outdir dist --target bun --packages external && chmod +x dist/cli.js",
+    "prepublishOnly": "bun run check && bun run test && bun run build"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.14",
+    "typescript": "^7.0.2"
+  },
+  "engines": {
+    "bun": ">=1.2.0"
+  },
+  "packageManager": "bun@1.3.14"
+}

package/template/README.md

@@ -0,0 +1,69 @@
+# Stitchkit Starter
+
+Production-shaped application generated by `create-stitchkit`.
+
+## Start
+
+Point `DATABASE_URL` in `.env` at an existing PostgreSQL database, then run:
+
+```bash
+bun run dev
+```
+
+The command validates the environment, generates the Prisma client, applies the
+checked-in migrations and launches:
+
+- Web: <http://localhost:3210>
+- UI catalogue: <http://localhost:3210/en/ui>
+- API: <http://localhost:3211>
+- OpenAPI: <http://localhost:3211/openapi.json>
+- MCP: <http://localhost:3211/mcp>
+
+The home page is a compact Stitchkit Starter reference surface. One configured
+GitHub repository exercises the PostgreSQL cache → contract → typed client →
+mutation invalidation → realtime path without adding a demo product domain.
+Configure it with `GITHUB_REPOSITORY`; `GITHUB_TOKEN` is optional.
+Repository visibility demonstrates the canonical Prisma enum → shared Zod schema
+→ HTTP/UI path without duplicating its allowed values.
+
+The `/en/ui` catalogue is isolated under
+`packages/frontend/src/app/[locale]/ui` and can be removed as one directory;
+reusable primitives remain in `components/ui`. It renders the complete
+foundation, overlay, data, motion, theme and composition system with generic
+fixtures. The root theme uses
+`@wrksz/themes/next` with hybrid cookie/localStorage persistence: the server can
+read the selected theme, while browser tabs remain synchronized. Client code
+imports typed hooks from `@wrksz/themes/client/*`; global theme ownership stays
+in the server layout. Interactive changes use a presentation-only runner around
+the native View Transition API. Its default is a 250 ms crossfade; the theme
+catalogue demonstrates configurable crossfade/radial effects and speeds.
+Unsupported browsers and users requesting reduced motion switch immediately.
+
+## Gates
+
+```bash
+bun run check
+bun run test
+bun run build
+```
+
+## Production
+
+Provide a production `.env`, then:
+
+```bash
+bun run db:deploy
+bun run build
+bun run pm2:prod
+```
+
+The Next.js frontend and Stitchkit API are separate processes and can also be
+deployed independently.
+
+PostgreSQL is external infrastructure in development and production. The
+application owns its schema and migrations; the environment owns the database
+process and supplies its connection through `DATABASE_URL`.
+
+`bun run dev` and `bun run pm2:dev` use the same direct PM2 development path.
+Rename the neutral `stitchkit-starter` package and process names when adopting
+the template for a product.

package/template/_env

@@ -0,0 +1,11 @@
+NODE_ENV=development
+DATABASE_URL=postgresql://USER:PASSWORD@127.0.0.1:5432/stitchkit_starter
+API_PORT=3211
+WEB_PORT=3210
+NEXT_PUBLIC_API_URL=http://127.0.0.1:3211
+INTERNAL_API_URL=http://127.0.0.1:3211
+NEXT_PUBLIC_WEB_URL=http://127.0.0.1:3210
+LOG_FORMAT=pretty
+GITHUB_REPOSITORY=max-listov/stitchkit
+GITHUB_CACHE_TTL_SECONDS=900
+# GITHUB_TOKEN=github_pat_...

package/template/_env.example

@@ -0,0 +1,12 @@
+NODE_ENV=development
+DATABASE_URL=postgresql://USER:PASSWORD@127.0.0.1:5432/stitchkit_starter
+API_PORT=3211
+WEB_PORT=3210
+NEXT_PUBLIC_API_URL=http://127.0.0.1:3211
+INTERNAL_API_URL=http://127.0.0.1:3211
+NEXT_PUBLIC_WEB_URL=http://127.0.0.1:3210
+LOG_FORMAT=pretty
+GITHUB_REPOSITORY=max-listov/stitchkit
+GITHUB_CACHE_TTL_SECONDS=900
+# Optional. Authenticated conditional requests have a higher GitHub rate limit.
+# GITHUB_TOKEN=github_pat_...

package/template/_gitignore

@@ -0,0 +1,10 @@
+node_modules/
+dist/
+.next/
+next-env.d.ts
+.env
+coverage/
+*.log
+packages/db/src/generated/
+playwright-report/
+test-results/

package/template/biome.json

@@ -0,0 +1,43 @@
+{
+  "$schema": "https://biomejs.dev/schemas/2.5.7/schema.json",
+  "files": {
+    "includes": [
+      "**",
+      "!!**/src/generated",
+      "!!**/.next",
+      "!!**/dist",
+      "!!playwright-report",
+      "!!test-results",
+      "!!packages/frontend/next-env.d.ts",
+      "!!packages/frontend/public"
+    ]
+  },
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space",
+    "indentWidth": 2,
+    "lineWidth": 96
+  },
+  "javascript": {
+    "formatter": {
+      "quoteStyle": "single",
+      "jsxQuoteStyle": "single",
+      "trailingCommas": "all",
+      "semicolons": "always"
+    }
+  },
+  "css": {
+    "parser": {
+      "tailwindDirectives": true
+    }
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "preset": "recommended",
+      "suspicious": {
+        "noExplicitAny": "error"
+      }
+    }
+  }
+}