@govela/create 0.0.0-stage → 0.7.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 abullo
+
+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,18 @@
-# Temporary Holding Version
+# @govela/create
 
-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.
+Creates a Vela application.
+
+```sh
+npm create @govela my-app             # Vite, Vitest with @govela/testing
+npm create @govela my-app -- --ssr    # a Go server renders, Vite builds the client
+npm create @govela my-app -- --app    # a Vela App: routes with Go loaders
+```
+
+The projects are TypeScript (`vela check --types`, typed tests); `--js`
+writes JavaScript. `--module example.com/my-app` sets the Go module path
+of `--ssr` and `--app`. Every project has a component test, ESLint with
+`@govela/eslint-plugin`, `npm run check` (`vela check`), a GitHub Actions
+workflow running the check, the linter, the tests and the build, and an
+`AGENTS.md` pointing to the Vela authoring guide.
+
+License: MIT.

package/bin/create.js

@@ -0,0 +1,146 @@
+#!/usr/bin/env node
+// npm create @govela [directory] -- [--ssr | --app] [--js] [--module path]
+//
+// Creates a Vela application from one of the templates of this package
+// (tasks 066, 088): default (Vite), ssr (a Go server renders, Vite builds
+// the client) or app (a Vela App with routes and Go loaders), in TypeScript
+// or, with --js, JavaScript. A template is templates/<name>/base, the files
+// of both languages, and templates/<name>/ts or /js on top of it.
+import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, statSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const root = dirname(dirname(fileURLToPath(import.meta.url)));
+const manifest = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'));
+
+const usage = `usage: npm create @govela [directory] -- [options]
+
+options:
+  --ssr            server rendering: a Go server renders, Vite builds the client
+  --app            a Vela App: file-based routes with Go loaders
+  --js             JavaScript instead of TypeScript
+  --ts             TypeScript (the default)
+  --module path    the Go module path of --ssr and --app (example.com/<name>)
+  --help           this text
+`;
+
+function fail(message) {
+  process.stderr.write(`create-vela: ${message}\n`);
+  process.exit(1);
+}
+
+export function parseArgs(argv) {
+  const options = { template: 'default', directory: null, module: null, language: 'ts' };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    switch (arg) {
+      case '--ssr':
+      case '--app': {
+        const template = arg.slice(2);
+        if (options.template !== 'default' && options.template !== template) throw new Error('--ssr and --app exclude each other');
+        options.template = template;
+        break;
+      }
+      case '--js':
+      case '--ts':
+        options.language = arg.slice(2);
+        break;
+      case '--module':
+        if (!argv[i + 1]) throw new Error('--module needs a Go module path');
+        options.module = argv[++i];
+        break;
+      case '--help':
+      case '-h':
+        options.help = true;
+        break;
+      default:
+        if (arg.startsWith('-')) throw new Error(`unknown option ${arg}`);
+        if (options.directory) throw new Error(`a second directory ${arg}`);
+        options.directory = arg;
+    }
+  }
+  return options;
+}
+
+// packageName turns a directory name into a valid npm package name.
+function packageName(dir) {
+  const name = basename(dir).toLowerCase().replace(/[^a-z0-9._~-]+/g, '-').replace(/^[._-]+|-+$/g, '');
+  return name || 'vela-app';
+}
+
+// Files that npm would rename or drop when publishing are stored with a
+// leading underscore.
+function outputName(name) {
+  if (name === '_gitignore') return '.gitignore';
+  if (name === '_github') return '.github';
+  return name;
+}
+
+function substitute(text, values) {
+  for (const [key, value] of Object.entries(values)) text = text.split(key).join(value);
+  return text;
+}
+
+function copyTemplate(from, to, values) {
+  mkdirSync(to, { recursive: true });
+  for (const name of readdirSync(from)) {
+    const source = join(from, name);
+    const target = join(to, substitute(outputName(name), values));
+    if (statSync(source).isDirectory()) {
+      copyTemplate(source, target, values);
+      continue;
+    }
+    writeFileSync(target, substitute(readFileSync(source, 'utf8'), values));
+  }
+}
+
+export function create(options) {
+  const directory = resolve(options.directory || 'vela-app');
+  if (existsSync(directory) && readdirSync(directory).length > 0) {
+    throw new Error(`${directory} is not empty`);
+  }
+  const name = packageName(directory);
+  const module = options.module || `example.com/${name}`;
+  if (!/^[A-Za-z0-9._~\/-]+$/.test(module)) throw new Error(`${module} is not a Go module path`);
+  const values = {
+    __NAME__: name,
+    __MODULE__: module,
+    __VERSION__: manifest.version,
+    __APP_VERSION__: manifest.govela.app,
+    __EXT__: options.language,
+  };
+  const template = join(root, 'templates', options.template);
+  copyTemplate(join(template, 'base'), directory, values);
+  copyTemplate(join(template, options.language), directory, values);
+  return { directory, name, template: options.template, language: options.language };
+}
+
+function main() {
+  let options;
+  try {
+    options = parseArgs(process.argv.slice(2));
+  } catch (err) {
+    process.stderr.write(usage);
+    fail(err.message);
+  }
+  if (options.help) {
+    process.stdout.write(usage);
+    return;
+  }
+  let result;
+  try {
+    result = create(options);
+  } catch (err) {
+    fail(err.message);
+  }
+  const dir = relative(process.cwd(), result.directory) || '.';
+  const steps = [`cd ${dir}`, 'npm install'];
+  if (result.template === 'ssr') steps.push('npx vela', 'go mod tidy', 'npm run dev:vela & npm run dev & npm run dev:server');
+  else if (result.template === 'app') steps.push('npx vela-app gen && npx vela', 'go mod tidy', 'npm run dev');
+  else steps.push('npm run dev');
+  const language = result.language === 'ts' ? 'TypeScript' : 'JavaScript';
+  process.stdout.write(`Created ${result.name} (${result.template}, ${language}) in ${result.directory}\n\nNext:\n${steps.map((s) => `  ${s}\n`).join('')}`);
+}
+
+// npm runs the command through a link in node_modules/.bin.
+if (process.argv[1] && realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url))) main();

package/package.json

@@ -1,6 +1,26 @@
 {
   "name": "@govela/create",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.7.0",
+  "description": "Creates a Vela application: npm create @govela. Manifest generated by the compiler repository; do not edit.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/elauven/vela.git",
+    "directory": "packages/create"
+  },
+  "type": "module",
+  "bin": {
+    "create-govela": "bin/create.js"
+  },
+  "files": [
+    "bin",
+    "templates",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": "^20.19.0 || >=22.12.0"
+  },
+  "govela": {
+    "app": "0.3.0"
+  }
+}

package/templates/app/base/AGENTS.md

@@ -0,0 +1,44 @@
+# Agent instructions
+
+This is a Vela App: file-based routes in `src/routes`, rendered on the
+server by Go and hydrated in the browser. Before you create or edit a
+`.vela` component, read the Vela authoring guide of the compiler version
+this project uses:
+
+https://github.com/elauven/vela/blob/v__VERSION__/AGENTS.md
+
+and, for routes, loaders and actions:
+
+https://github.com/elauven/vela/blob/v__VERSION__/docs/APP.md
+
+When a compiler diagnostic disagrees with an example, trust the diagnostic.
+
+## This project
+
+- `src/routes/**/Page.vela` are pages, `Layout.vela` wraps them. The Go
+  loaders in `server/routes` (the same tree) return each component's
+  `data` prop; `npx vela-app scaffold` adds the missing ones.
+- `src/_app`, `internal/appgen` and `out/` are generated; never edit them.
+- A component at any depth reads the route, the form and the data of the
+  page with `getPage()` from `#app/page.js` (call it in the script; keep it
+  as `$state.deep(getPage())` to follow navigation) instead of passing
+  `route` and `data` down as props.
+- Permission checks go in `guard.go` (`func Guard(ctx, r) error`, `npx
+  vela-app scaffold -guard /route`), never in a layout loader: a guard runs
+  before every loader and action below its directory. Read the user from
+  an `app.Local` set by middleware.
+- Code that runs during the first render is translated to Go: keep it free
+  of browser APIs. Treat every `VELA-SSR-*` diagnostic as an error to fix.
+- Tests are `*.test.__EXT__` files next to the components, run by Vitest with
+  `@govela/testing` (`render`, `fireEvent`).
+
+## Before handing off
+
+```sh
+npm run check   # vela-app gen and vela check --ssr (and --types)
+npm run lint    # eslint: the code of the components and modules
+npm test        # vitest run
+npm run build   # vela-app build: the server and the client into build/
+```
+
+All of them must pass.

package/templates/app/base/README.md

@@ -0,0 +1,19 @@
+# __NAME__
+
+A [Vela App](https://github.com/elauven/vela/blob/main/docs/VELA_APP.md):
+routes in `src/routes`, Go loaders in `server/routes`, the server in
+`cmd/server`.
+
+```sh
+npm install
+npx vela-app gen && npx vela   # once, so that go mod tidy sees the generated packages
+go mod tidy
+npm run dev                    # http://127.0.0.1:8080
+```
+
+```sh
+npm test         # component tests
+npm run check    # compiler and server-rendering diagnostics
+npm run lint     # eslint
+npm run build    # build/: the server binary and the client
+```

package/templates/app/base/_github/workflows/ci.yml

@@ -0,0 +1,23 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-go@v6
+        with:
+          go-version-file: go.mod
+      - uses: actions/setup-node@v5
+        with:
+          node-version: '24'
+          cache: npm
+      - run: npm ci
+      - run: npm run check
+      - run: npm run lint
+      - run: npm test
+      - run: npm run build

package/templates/app/base/_gitignore

@@ -0,0 +1,7 @@
+# Generated by vela-app gen, vela, vite build and vela-app build.
+/src/_app/
+/internal/appgen/
+/out/
+/dist/
+/build/
+/node_modules/

package/templates/app/base/cmd/server/main.go

@@ -0,0 +1,53 @@
+package main
+
+import (
+	"flag"
+	"fmt"
+	"log"
+	"net"
+	"net/http"
+	"os"
+	"path/filepath"
+
+	"__MODULE__/internal/appgen"
+	"github.com/elauven/vela/app"
+	"github.com/elauven/vela/ssr_runtime/vite"
+)
+
+func main() {
+	addr := flag.String("addr", "127.0.0.1:8080", "listen address")
+	dev := flag.String("dev", "", "URL of the Vite dev server; serve dist/ when empty")
+	dist := flag.String("dist", "dist", `directory of vite build; "none" serves pages without client`)
+	flag.Parse()
+
+	mux := http.NewServeMux()
+	var assets *vite.Assets
+	switch {
+	case *dev != "":
+		assets = vite.Dev(*dev)
+	case *dist != "none":
+		var err error
+		if assets, err = vite.Load(filepath.Join(*dist, ".vite", "manifest.json"), "/"); err != nil {
+			log.Fatal(err)
+		}
+		mux.Handle("/assets/", http.FileServer(http.Dir(*dist)))
+	}
+	handler, err := app.New(app.Config{
+		Routes:   appgen.Routes(),
+		Assets:   assets,
+		Manifest: filepath.Join("out", "client", "vela.manifest.json"),
+		Head:     app.Head{Title: "__NAME__"},
+		Dev:      *dev != "",
+	})
+	if err != nil {
+		log.Fatal(err)
+	}
+	mux.Handle("/", handler)
+
+	listener, err := net.Listen("tcp", *addr)
+	if err != nil {
+		log.Fatal(err)
+	}
+	fmt.Fprintf(os.Stdout, "http://%s\n", listener.Addr())
+	log.Fatal(http.Serve(listener, mux))
+}

package/templates/app/base/go.mod

@@ -0,0 +1,8 @@
+module __MODULE__
+
+go 1.25
+
+require (
+	github.com/elauven/vela/app v__APP_VERSION__
+	github.com/elauven/vela/ssr_runtime v__VERSION__
+)

package/templates/app/base/server/routes/load.go

@@ -0,0 +1,30 @@
+// Package routes holds the loaders of src/routes: the function of a
+// component returns its data prop.
+package routes
+
+import (
+	"context"
+
+	"github.com/elauven/vela/app"
+)
+
+// Site is the data of Layout.
+type Site struct {
+	Site string `json:"site"`
+}
+
+// Greeting is the data of Page.
+type Greeting struct {
+	Greeting string `json:"greeting"`
+}
+
+// Layout loads the data of every page.
+func Layout(ctx context.Context, r *app.Request) (Site, error) {
+	return Site{Site: "__NAME__"}, nil
+}
+
+// Page loads the data of /.
+func Page(ctx context.Context, r *app.Request) (Greeting, error) {
+	r.Head().Title = "Home"
+	return Greeting{Greeting: "Hello from Go"}, nil
+}

package/templates/app/base/vela.config.json

@@ -0,0 +1,6 @@
+{
+  "project": "src",
+  "out": "out",
+  "ssr": true,
+  "ssrModule": "__MODULE__/out/server"
+}

package/templates/app/base/vite.config.js

@@ -0,0 +1,11 @@
+import vela from '@govela/unplugin/vite';
+
+export default {
+  plugins: [vela()],
+  server: { origin: 'http://localhost:5173' },
+  build: { manifest: true, rollupOptions: { input: 'src/_app/client.js' } },
+  test: {
+    environment: 'happy-dom',
+    setupFiles: ['./vitest.setup.__EXT__'],
+  },
+};

package/templates/app/base/vitest.setup.__EXT__

@@ -0,0 +1,5 @@
+import { afterEach } from 'vitest';
+import { cleanup } from '@govela/testing';
+
+// Every test starts with an empty document.
+afterEach(cleanup);

package/templates/app/js/eslint.config.js

@@ -0,0 +1,12 @@
+import { defineConfig } from 'eslint/config';
+import js from '@eslint/js';
+import globals from 'globals';
+import vela from '@govela/eslint-plugin';
+
+export default defineConfig(
+  { ignores: ['dist/', 'out/', 'build/', 'src/_app/'] },
+  js.configs.recommended,
+  vela.configs.recommended,
+  { files: ['src/**/*.js', '**/*.vela/*.js'], languageOptions: { globals: globals.browser } },
+  { files: ['*.config.js'], languageOptions: { globals: globals.node } },
+);

package/templates/app/js/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "__NAME__",
+  "private": true,
+  "type": "module",
+  "imports": {
+    "#app/*": "./src/_app/*"
+  },
+  "scripts": {
+    "gen": "vela-app gen",
+    "dev": "vela-app dev",
+    "check": "vela-app gen && vela check --project src --ssr",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "build": "vela-app build"
+  },
+  "dependencies": {
+    "@govela/app": "__APP_VERSION__",
+    "@govela/runtime": "__VERSION__"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@govela/compiler": "__VERSION__",
+    "@govela/eslint-plugin": "__VERSION__",
+    "@govela/testing": "__VERSION__",
+    "@govela/unplugin": "__VERSION__",
+    "eslint": "^10.14.0",
+    "globals": "^17.0.0",
+    "happy-dom": "^21.0.4",
+    "vite": "^8.3.5",
+    "vitest": "^5.1.0"
+  }
+}

package/templates/app/js/src/routes/Layout.vela

@@ -0,0 +1,24 @@
+<script>
+  export let data = null;
+  export let route = null;
+</script>
+
+<template>
+  <div class="site">
+    <nav>
+      <a href="/" class:active={route.path === '/'}>{data.site}</a>
+    </nav>
+    <main><slot /></main>
+  </div>
+</template>
+
+<style>
+  .site {
+    font-family: system-ui, sans-serif;
+    max-width: 40rem;
+    margin: 2rem auto;
+  }
+  .active {
+    font-weight: bold;
+  }
+</style>

package/templates/app/js/src/routes/Page.test.js

@@ -0,0 +1,13 @@
+import { expect, test } from 'vitest';
+import { fireEvent, render } from '@govela/testing';
+import Page from './Page.vela';
+
+test('greets and counts clicks', async () => {
+  const { container } = render(Page, { props: { data: { greeting: 'Hello' } } });
+  expect(container.querySelector('h1').textContent).toBe('Hello');
+
+  const button = container.querySelector('button');
+  await fireEvent.click(button);
+
+  expect(button.textContent).toBe('Clicked 1 times');
+});

package/templates/app/js/src/routes/Page.vela

@@ -0,0 +1,10 @@
+<script>
+  export let data = null;
+
+  let count = $state(0);
+</script>
+
+<template>
+  <h1>{data.greeting}</h1>
+  <button @click={() => count++}>Clicked {count} times</button>
+</template>

package/templates/app/ts/eslint.config.js

@@ -0,0 +1,14 @@
+import { defineConfig } from 'eslint/config';
+import js from '@eslint/js';
+import globals from 'globals';
+import tseslint from 'typescript-eslint';
+import vela from '@govela/eslint-plugin';
+
+export default defineConfig(
+  { ignores: ['dist/', 'out/', 'build/', 'src/_app/'] },
+  js.configs.recommended,
+  tseslint.configs.recommended,
+  vela.configs.recommended,
+  { files: ['src/**/*.ts', '**/*.vela/*.ts'], languageOptions: { globals: globals.browser } },
+  { files: ['*.config.js'], languageOptions: { globals: globals.node } },
+);

package/templates/app/ts/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "__NAME__",
+  "private": true,
+  "type": "module",
+  "imports": {
+    "#app/*": "./src/_app/*"
+  },
+  "scripts": {
+    "gen": "vela-app gen",
+    "dev": "vela-app dev",
+    "check": "vela-app gen && vela check --project src --types --ssr",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "build": "vela-app build"
+  },
+  "dependencies": {
+    "@govela/app": "__APP_VERSION__",
+    "@govela/runtime": "__VERSION__"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@govela/compiler": "__VERSION__",
+    "@govela/eslint-plugin": "__VERSION__",
+    "@govela/testing": "__VERSION__",
+    "@govela/unplugin": "__VERSION__",
+    "eslint": "^10.14.0",
+    "globals": "^17.0.0",
+    "happy-dom": "^21.0.4",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.72.1",
+    "vite": "^8.3.5",
+    "vitest": "^5.1.0"
+  }
+}

package/templates/app/ts/src/routes/Layout.vela

@@ -0,0 +1,26 @@
+<script lang="ts">
+  import type { LayoutProps } from './$types';
+
+  export let data: LayoutProps['data'];
+  export let route: LayoutProps['route'];
+</script>
+
+<template>
+  <div class="site">
+    <nav>
+      <a href="/" class:active={route.path === '/'}>{data.site}</a>
+    </nav>
+    <main><slot /></main>
+  </div>
+</template>
+
+<style>
+  .site {
+    font-family: system-ui, sans-serif;
+    max-width: 40rem;
+    margin: 2rem auto;
+  }
+  .active {
+    font-weight: bold;
+  }
+</style>

package/templates/app/ts/src/routes/Page.test.ts

@@ -0,0 +1,13 @@
+import { expect, test } from 'vitest';
+import { fireEvent, render } from '@govela/testing';
+import Page from './Page.vela';
+
+test('greets and counts clicks', async () => {
+  const { container } = render(Page, { props: { data: { greeting: 'Hello' } } });
+  expect(container.querySelector('h1')!.textContent).toBe('Hello');
+
+  const button = container.querySelector('button')!;
+  await fireEvent.click(button);
+
+  expect(button.textContent).toBe('Clicked 1 times');
+});

package/templates/app/ts/src/routes/Page.vela

@@ -0,0 +1,12 @@
+<script lang="ts">
+  import type { PageProps } from './$types';
+
+  export let data: PageProps['data'];
+
+  let count = $state(0);
+</script>
+
+<template>
+  <h1>{data.greeting}</h1>
+  <button @click={() => count++}>Clicked {count} times</button>
+</template>

package/templates/app/ts/tsconfig.json

@@ -0,0 +1,4 @@
+{
+  "extends": "./src/_app/tsconfig.json",
+  "include": ["src"]
+}

package/templates/app/ts/vela.app.json

@@ -0,0 +1 @@
+{ "typescript": true }