create-fate 0.0.0 → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Nakazawa Tech
+
+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,24 @@
+# create-fate
+
+Create a new fate app:
+
+```sh
+vp create fate my-app
+```
+
+The generated app is installed and the fate client is generated during creation.
+
+Choose between these templates:
+
+- `void`: Void pages router with Drizzle.
+- `drizzle`: tRPC with Drizzle.
+- `http`: Native HTTP with Drizzle.
+- `prisma`: tRPC with Prisma.
+
+For a non-interactive install:
+
+```sh
+vp create fate my-app --template void
+```
+
+The template sources live in `packages/create-fate/templates/fate`.

package/bin/create-fate.mjs

@@ -0,0 +1,412 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath, URL } from 'node:url';
+import { cancel, intro, isCancel, outro, select, text } from '@clack/prompts';
+
+const variants = {
+  drizzle: {
+    description: 'tRPC with Drizzle',
+    label: 'Drizzle',
+    template: 'drizzle',
+  },
+  http: {
+    description: 'Native HTTP with Drizzle',
+    label: 'Native HTTP',
+    template: 'http',
+  },
+  prisma: {
+    description: 'tRPC with Prisma',
+    label: 'Prisma',
+    template: 'prisma',
+  },
+  void: {
+    description: 'Void with void-fate and Drizzle',
+    label: 'Void',
+    template: 'void',
+  },
+};
+
+const fateDependencyNames = ['@nkzw/fate', 'react-fate', 'void-fate'];
+
+const usage = () => {
+  process.stdout.write(`Usage: create-fate [directory] [--template void|drizzle|http|prisma]
+
+Create a new fate app.
+
+Options:
+  --template, -t  Template variant to create
+  --no-setup      Skip dependency installation and fate client generation
+  --help, -h      Show this help message
+`);
+};
+
+const normalizePackageName = (name) =>
+  name
+    .trim()
+    .toLowerCase()
+    .replaceAll(/[^a-z0-9._-]+/g, '-')
+    .replaceAll(/^-+|-+$/g, '') || 'my-app';
+
+const parseArgs = (args) => {
+  let setup = true;
+  let targetDir;
+  let variant;
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === '--help' || arg === '-h') {
+      return { help: true };
+    }
+
+    if (arg === '--no-setup') {
+      setup = false;
+      continue;
+    }
+
+    if (arg === '--template' || arg === '-t' || arg === '--variant') {
+      variant = args[++index];
+      continue;
+    }
+
+    if (arg?.startsWith('--template=')) {
+      variant = arg.slice('--template='.length);
+      continue;
+    }
+
+    if (arg?.startsWith('--variant=')) {
+      variant = arg.slice('--variant='.length);
+      continue;
+    }
+
+    if (!targetDir) {
+      targetDir = arg;
+      continue;
+    }
+
+    throw new Error(`Unexpected argument: ${arg}`);
+  }
+
+  return { setup, targetDir, variant };
+};
+
+const validateTargetDir = (value) => {
+  const targetDir = value?.trim();
+  if (!targetDir) {
+    throw new Error('Target directory is required.');
+  }
+
+  const normalized = path.normalize(targetDir);
+  if (
+    !path.isAbsolute(normalized) &&
+    (normalized === '.' || normalized.startsWith('..') || normalized.includes(`${path.sep}..`))
+  ) {
+    throw new Error('Target directory cannot escape the current directory.');
+  }
+
+  return normalized;
+};
+
+const validateTargetDirInput = (value) => {
+  try {
+    validateTargetDir(value || 'my-app');
+    return;
+  } catch (error) {
+    return error instanceof Error ? error.message : String(error);
+  }
+};
+
+const abortPrompt = () => {
+  cancel('Create fate app cancelled.');
+  process.exit(0);
+};
+
+const promptForTargetDir = async () => {
+  const result = await text({
+    defaultValue: 'my-app',
+    message: 'Project directory',
+    placeholder: 'my-app',
+    validate: validateTargetDirInput,
+  });
+
+  if (isCancel(result)) {
+    abortPrompt();
+  }
+
+  return result;
+};
+
+const promptForVariant = async () => {
+  const result = await select({
+    message: 'Select a fate template',
+    options: Object.entries(variants).map(([value, variant]) => ({
+      hint: variant.description,
+      label: variant.label,
+      value,
+    })),
+  });
+
+  if (isCancel(result)) {
+    abortPrompt();
+  }
+
+  return result;
+};
+
+const getRegistryURL = () => {
+  const registry = process.env.npm_config_registry || 'https://registry.npmjs.org/';
+  return registry.endsWith('/') ? registry : `${registry}/`;
+};
+
+const fetchLatestPackageVersion = async (packageName) => {
+  const response = await globalThis.fetch(
+    new URL(encodeURIComponent(packageName), getRegistryURL()),
+  );
+  if (!response.ok) {
+    throw new Error(`Could not fetch ${packageName} from npm registry.`);
+  }
+
+  const metadata = await response.json();
+  const version = metadata?.['dist-tags']?.latest;
+  if (typeof version !== 'string' || !version) {
+    throw new Error(`Could not resolve latest version for ${packageName}.`);
+  }
+
+  return version;
+};
+
+const collectFateDependencies = (dir, dependencies = new Set()) => {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (entry.name === 'node_modules' || entry.name === '.git') {
+      continue;
+    }
+
+    const entryPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      collectFateDependencies(entryPath, dependencies);
+      continue;
+    }
+
+    if (entry.name !== 'package.json') {
+      continue;
+    }
+
+    const json = JSON.parse(fs.readFileSync(entryPath, 'utf8'));
+    for (const dependencyType of ['dependencies', 'devDependencies', 'peerDependencies']) {
+      const packageDependencies = json[dependencyType];
+      if (!packageDependencies) {
+        continue;
+      }
+
+      for (const dependencyName of fateDependencyNames) {
+        if (packageDependencies[dependencyName]) {
+          dependencies.add(dependencyName);
+        }
+      }
+    }
+  }
+
+  return dependencies;
+};
+
+const resolveFateDependencyVersions = async (rootDir) => {
+  const dependencies = [...collectFateDependencies(rootDir)];
+  return Object.fromEntries(
+    await Promise.all(
+      dependencies.map(async (dependencyName) => [
+        dependencyName,
+        `^${await fetchLatestPackageVersion(dependencyName)}`,
+      ]),
+    ),
+  );
+};
+
+const updatePackageJsonFiles = (rootDir, dir, packageName, fateDependencyVersions) => {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (entry.name === 'node_modules' || entry.name === '.git') {
+      continue;
+    }
+
+    const entryPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      updatePackageJsonFiles(rootDir, entryPath, packageName, fateDependencyVersions);
+      continue;
+    }
+
+    if (entry.name !== 'package.json') {
+      continue;
+    }
+
+    const json = JSON.parse(fs.readFileSync(entryPath, 'utf8'));
+    if (entryPath === path.join(rootDir, 'package.json')) {
+      json.name = packageName;
+    }
+
+    for (const dependencyType of ['dependencies', 'devDependencies', 'peerDependencies']) {
+      const dependencies = json[dependencyType];
+      if (!dependencies) {
+        continue;
+      }
+
+      for (const [dependencyName, version] of Object.entries(fateDependencyVersions)) {
+        if (dependencies[dependencyName]) {
+          dependencies[dependencyName] = version;
+        }
+      }
+    }
+
+    fs.writeFileSync(entryPath, `${JSON.stringify(json, null, 2)}\n`);
+  }
+};
+
+const restoreTemplateFileNames = (dir) => {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const entryPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      restoreTemplateFileNames(entryPath);
+      continue;
+    }
+
+    if (entry.name === '_gitignore') {
+      fs.renameSync(entryPath, path.join(dir, '.gitignore'));
+    }
+  }
+};
+
+const copyExampleEnvFiles = (dir) => {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const entryPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      copyExampleEnvFiles(entryPath);
+      continue;
+    }
+
+    if (!entry.name.endsWith('.env.example')) {
+      continue;
+    }
+
+    const envPath = path.join(dir, entry.name.slice(0, -'.example'.length));
+    if (!fs.existsSync(envPath)) {
+      fs.copyFileSync(entryPath, envPath);
+    }
+  }
+};
+
+const runCommand = (command, args, cwd) => {
+  const result = spawnSync(command, args, {
+    cwd,
+    shell: process.platform === 'win32',
+    stdio: 'inherit',
+  });
+
+  if (result.error) {
+    throw result.error;
+  }
+
+  if (result.status !== 0) {
+    throw new Error(`Command failed: ${[command, ...args].join(' ')}`);
+  }
+};
+
+const setupProject = (targetPath, selectedVariant) => {
+  runCommand('vp', ['install'], targetPath);
+
+  switch (selectedVariant) {
+    case 'prisma':
+      runCommand('vp', ['run', '--filter', '@app/server', 'dev:setup'], targetPath);
+      runCommand('vp', ['run', 'fate:generate'], targetPath);
+      break;
+    case 'void':
+      runCommand('vp', ['run', 'prepare:void'], targetPath);
+      runCommand('vp', ['run', 'fate:generate'], targetPath);
+      break;
+    default:
+      runCommand('vp', ['run', 'fate:generate'], targetPath);
+      break;
+  }
+};
+
+const printReadme = (targetPath) => {
+  const readmePath = path.join(targetPath, 'README.md');
+  if (!fs.existsSync(readmePath)) {
+    return;
+  }
+
+  process.stdout.write(`\nNext steps are in README.md. Follow these instructions:\n\n`);
+  process.stdout.write(fs.readFileSync(readmePath, 'utf8'));
+  process.stdout.write('\n');
+};
+
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+const resolveTemplateRoot = (template) => {
+  const templateRoot = path.resolve(packageRoot, 'templates', 'fate', template);
+  if (!fs.existsSync(templateRoot)) {
+    throw new Error(`Template '${template}' could not be found.`);
+  }
+
+  return templateRoot;
+};
+
+const main = async () => {
+  const options = parseArgs(process.argv.slice(2));
+  if (options.help) {
+    usage();
+    return;
+  }
+
+  const interactive = process.stdin.isTTY && process.stdout.isTTY;
+  if (interactive) {
+    intro('create-fate');
+  }
+
+  const selectedVariant = options.variant ?? (interactive ? await promptForVariant() : 'void');
+  if (!selectedVariant || !variants[selectedVariant]) {
+    throw new Error(
+      `Unknown template '${selectedVariant}'. Expected one of: ${Object.keys(variants).join(', ')}.`,
+    );
+  }
+
+  const targetDir = validateTargetDir(
+    options.targetDir ?? (interactive ? await promptForTargetDir() : 'my-app'),
+  );
+  const targetPath = path.resolve(process.cwd(), targetDir);
+  if (fs.existsSync(targetPath) && fs.readdirSync(targetPath).length > 0) {
+    throw new Error(`Target directory '${targetDir}' is not empty.`);
+  }
+
+  const templateRoot = resolveTemplateRoot(variants[selectedVariant].template);
+  const fateDependencyVersions = await resolveFateDependencyVersions(templateRoot);
+  fs.mkdirSync(targetPath, { recursive: true });
+  fs.cpSync(templateRoot, targetPath, { recursive: true });
+  restoreTemplateFileNames(targetPath);
+  copyExampleEnvFiles(targetPath);
+  updatePackageJsonFiles(
+    targetPath,
+    targetPath,
+    normalizePackageName(path.basename(targetDir)),
+    fateDependencyVersions,
+  );
+
+  if (options.setup) {
+    setupProject(targetPath, selectedVariant);
+  }
+
+  const message = `Created ${variants[selectedVariant].label} fate app in ${targetDir}`;
+  if (interactive) {
+    outro(message);
+  } else {
+    process.stdout.write(`${message}\n`);
+  }
+
+  printReadme(targetPath);
+};
+
+try {
+  await main();
+} catch (error) {
+  process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+  process.exit(1);
+}

package/package.json

@@ -1,7 +1,30 @@
 {
   "name": "create-fate",
-  "version": "0.0.0",
-  "description": "",
+  "version": "1.0.0",
+  "description": "Create a new fate app.",
+  "homepage": "https://github.com/nkzw-tech/fate",
+  "license": "MIT",
+  "author": {
+    "name": "Christoph Nakazawa",
+    "email": "christoph.pojer@gmail.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nkzw-tech/fate",
+    "directory": "packages/create-fate"
+  },
+  "bin": {
+    "create-fate": "./bin/create-fate.mjs"
+  },
+  "files": [
+    "bin",
+    "templates"
+  ],
   "type": "module",
-  "main": "index.js"
+  "dependencies": {
+    "@clack/prompts": "^1.4.0"
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  }
 }

package/templates/fate/README.md

@@ -0,0 +1,8 @@
+# fate Templates
+
+This directory is the canonical source for fate project scaffolds.
+
+- `void/` contains the Void pages router + Drizzle template.
+- `drizzle/` contains the tRPC + Drizzle template.
+- `http/` contains the native HTTP + Drizzle template.
+- `prisma/` contains the tRPC + Prisma template.

package/templates/fate/drizzle/.github/workflows/push.yml

@@ -0,0 +1,27 @@
+name: test
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [24]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: voidzero-dev/setup-vp@v1
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: true
+          run-install: true
+      - run: |
+          vp run dev:setup
+          vp run test:all
+          vp run build

package/templates/fate/drizzle/.oxfmtrc.jsonc

@@ -0,0 +1,23 @@
+{
+  "$schema": "./node_modules/oxfmt/configuration_schema.json",
+  "singleQuote": true,
+  "experimentalSortImports": {
+    "newlinesBetween": false,
+  },
+  "experimentalSortPackageJson": {
+    "sortScripts": true,
+  },
+  "experimentalTailwindcss": {
+    "stylesheet": "client/src/App.css",
+  },
+  "ignorePatterns": [
+    "client/dist/",
+    "client/index.html",
+    "client/src/fate.ts",
+    "client/src/translations/",
+    "coverage/",
+    "dist/",
+    "pnpm-lock.yaml",
+    "server/dist",
+  ],
+}

package/templates/fate/drizzle/.vite-hooks/pre-commit

@@ -0,0 +1 @@
+vp staged

package/templates/fate/drizzle/.vscode/extensions.json

@@ -0,0 +1,12 @@
+{
+  "recommendations": [
+    "dbaeumer.vscode-eslint",
+    "oxc.oxc-vscode",
+    "styled-components.vscode-styled-components",
+    "sysoev.vscode-open-in-github",
+    "tailwindcss.intellisense",
+    "TypeScriptTeam.native-preview",
+    "usernamehw.errorlens",
+    "wix.vscode-import-cost"
+  ]
+}

package/templates/fate/drizzle/.vscode/settings.json

@@ -0,0 +1,25 @@
+{
+  "editor.formatOnSave": true,
+  "files.insertFinalNewline": true,
+  "files.trimFinalNewlines": true,
+  "editor.codeActionsOnSave": {
+    "source.fixAll.eslint": "explicit"
+  },
+  "[javascript]": {
+    "editor.defaultFormatter": "oxc.oxc-vscode"
+  },
+  "[typescriptreact]": {
+    "editor.defaultFormatter": "oxc.oxc-vscode"
+  },
+  "[typescript]": {
+    "editor.defaultFormatter": "oxc.oxc-vscode"
+  },
+  "[json]": {
+    "editor.defaultFormatter": "oxc.oxc-vscode"
+  },
+  "typescript.preferences.importModuleSpecifierEnding": "js",
+  "typescript.reportStyleChecksAsWarnings": false,
+  "typescript.updateImportsOnFileMove.enabled": "always",
+  "typescript.preferences.autoImportFileExcludePatterns": ["**/node_modules/vitest"],
+  "typescript.experimental.useTsgo": true
+}

package/templates/fate/drizzle/AGENTS.md

@@ -0,0 +1,55 @@
+# Using _fate_ for React applications
+
+This guidance is for agents working in projects bootstrapped from the fate template. It focuses on the client-side patterns for fate's view composition and action execution.
+
+## Core Workflow
+
+- **Define views with explicit selections:** Define reusable view objects with `view<T>()({...})`, compose them via spreads, and resolve them with `useView`.
+- **Resolve data via references:** Avoid passing raw fetched objects; instead pass `ViewRef`s to downstream components to keep selections scoped and cache-aware. Then call `const result = useView(viewDefinition, ref)` to read only the selected fields while subscribing to cache updates. Name the prop after the result data, and rename it using destructuring in the function arguments: `const PostComponent = ({ post: postRef }: { post: ViewRef<'Post'>}) => { const post = useView(PostView, postRef); ... }`.
+- **Request data at screen roots:** Use `useRequest` to compose all views required for a route or screen into a single typed request; wrap roots in `Suspense` and an error boundary since requests may suspend or throw.
+- **Compose reusable views:** Extract nested selections into their own views (e.g., `UserView`) and compose them inside parent views (`author: UserView`) to avoid duplication and overfetching. This keeps selections DRY and ensures view updates propagate consistently when the cache changes.
+
+## Actions & Mutations
+
+- **Prefer `fate.actions` with `useActionState`:** Trigger mutations through React Actions to integrate with Suspense/`useTransition`, receiving `[result, action, isPending]`. Call actions via the relevant data inputs, for example `action({input: { id: post.id }})`.
+- **Optimistic updates by default:** Pass `optimistic` payloads to immediately update the normalized cache; only views selecting the changed fields re-render and failures roll back automatically. Optimistic payloads should match the expected server data changes of the associated object.
+- **Select extra fields when side effects matter:** When a mutation affects related entities (e.g., comment count on a post), pass a `view` to the action to fetch the needed fields in the same round-trip and keep the cache coherent for all dependent views.
+- **Imperative escape hatch:** Use `fate.mutations` when you must fire mutations outside React components or without waiting on prior actions; handle loading/error states yourself.
+- **Handle deletions and resets explicitly:** Use the `delete: true` flag to evict records from the cache, and send the `'reset'` token to clear stale action errors without re-running the mutation.
+- **Error handling model:** Treat expected errors (e.g., 404) at the call site via the action result; unexpected errors bubble to the nearest React error boundary.
+
+## Common Pitfalls
+
+- **Use ViewRefs:** Pass references instead of raw data. Keep components focused on views and `ViewRef`s to let fate manage data masking and updates.
+- **Co-locate data needs:** Keep view definitions near their components and compose them upward to the request root for predictable fetching.
+- **Use Suspense:** Wrap pages in `Suspense`/`ErrorBoundary` instead of ad-hoc loading/error flags; fate aligns with Async React by design.
+- **Do not duplicate types:** Keep generated tRPC types and views imported from the server package. Avoid redefining entity shapes on the client. This ensures view selections stay type-safe end-to-end.
+- **`useRequest` only at the root:** When adding routes or layouts, create a dedicated `useRequest` call per screen root that pulls together all child views; do not scatter `useRequest` across leaf components unless it's necessary to issue requests due to user input.
+- **React Actions:** Prefer React Action-friendly UI primitives (buttons/forms that accept an `action` prop). If unavailable, wrap action calls with `startTransition` in `onClick` handlers.
+- **Generated Client** The fate client is generated via `pnpm fate:generate`. It should not be manually edited. Instead make the proper schema changes on the server and run `pnpm fate:generate`.
+- **Library Versions:** This repository uses the most recent releases of React, fate, Vite, tRPC, and more. You might not know about the new releases yet, please don't get confused. The versions you see are real, and there are no feature or version mismatches. You can search the internet for more information about them.
+
+Full documentation can be found on the filesystem at `./client/node_modules/react-fate/README.md` or online at [fate.technology](https://fate.technology/).
+
+## Review Checklist for Agents
+
+- [ ] Every component that reads server data does so through `useView` and receives a `ViewRef` prop.
+- [ ] Root components gather data with a single `useRequest` call.
+- [ ] Mutations are wired through `useActionState` with optimistic updates and necessary `view` selections; imperative `fate.mutations` are justified when used.
+- [ ] Shared selections live in reusable views using regular JavaScript object spreads rather than duplicated field lists.
+
+<!--VITE PLUS START-->
+
+# Using Vite+, the Unified Toolchain for the Web
+
+This project is using Vite+, a unified toolchain built on top of Vite, Rolldown, Vitest, tsdown, Oxlint, Oxfmt, and Vite Task. Vite+ wraps runtime management, package management, and frontend tooling in a single global CLI called `vp`. Vite+ is distinct from Vite, and it invokes Vite through `vp dev` and `vp build`. Run `vp help` to print a list of commands and `vp <command> --help` for information about a specific command.
+
+Docs are local at `node_modules/vite-plus/docs` or online at https://viteplus.dev/guide/.
+
+## Review Checklist
+
+- [ ] Run `vp install` after pulling remote changes and before getting started.
+- [ ] Run `vp check` and `vp test` to format, lint, type check and test changes.
+- [ ] Check if there are `vite.config.ts` tasks or `package.json` scripts necessary for validation, run via `vp run <script>`.
+
+<!--VITE PLUS END-->