@clubedge/create-clubedge-app 0.2.0 → 0.3.0

package/dist/steps/install.js

@@ -0,0 +1,19 @@
+import process from "node:process";
+import { commandSucceeds, run } from "../utils/process.js";
+/** The generated workspace relies on pnpm features (workspace:* and pnpm-workspace.yaml). */
+export async function resolvePnpm() {
+    if (await commandSucceeds("pnpm", ["--version"]))
+        return ["pnpm"];
+    if (await commandSucceeds("corepack", ["pnpm", "--version"]))
+        return ["corepack", "pnpm"];
+    return null;
+}
+/** The package manager that launched the CLI, from npm_config_user_agent (e.g. "npm/10.8.2 ..."). */
+export function detectLauncher(userAgent = process.env.npm_config_user_agent) {
+    const name = userAgent?.split("/")[0];
+    return name && ["npm", "pnpm", "yarn", "bun"].includes(name) ? name : null;
+}
+export async function installDependencies(directory, pnpm) {
+    const [command, ...prefix] = pnpm;
+    await run(command, [...prefix, "install"], directory);
+}

package/dist/utils/fs.js

@@ -0,0 +1,97 @@
+import { access, copyFile, mkdir, readdir, rm } from "node:fs/promises";
+import { dirname, join, relative, sep } from "node:path";
+import { runCapture } from "./process.js";
+export async function pathExists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * npm drops `.gitignore` and `.npmrc` from published tarballs, so the bundled template stores
+ * them under these names and the CLI restores them when copying.
+ */
+export const packedFileNames = {
+    ".gitignore": "_gitignore",
+    ".npmrc": "_npmrc",
+};
+export function toPackedPath(path) {
+    return mapBasename(path, (name) => packedFileNames[name]);
+}
+export function fromPackedPath(path) {
+    return mapBasename(path, (name) => Object.entries(packedFileNames).find(([, packed]) => packed === name)?.[0]);
+}
+function mapBasename(path, map) {
+    const parts = path.split("/");
+    const last = parts.pop();
+    return [...parts, map(last) ?? last].join("/");
+}
+/** Never copied from a local template directory that is not a Git work tree. */
+const ignoredDirectories = new Set([
+    ".git",
+    ".next",
+    ".turbo",
+    ".pnpm-store",
+    "node_modules",
+    "coverage",
+    "dist",
+    "playwright-report",
+    "test-results",
+]);
+/** Local environment files hold secrets; only the committed example is part of a template. */
+function isLocalSecret(name) {
+    return /^\.env(\..+)?$/.test(name) && name !== ".env.example";
+}
+/** True for dependencies, build output, and local secrets, which never belong in a template. */
+export function isIgnoredTemplatePath(path) {
+    const parts = path.split("/");
+    return parts.some((part) => ignoredDirectories.has(part)) || isLocalSecret(parts.at(-1));
+}
+/**
+ * Lists template files as forward-slash relative paths. Inside a Git work tree this narrows to
+ * tracked and unignored files. The ignore rules always apply as well, because the directory may
+ * sit inside an unrelated repository (a home directory under version control, for example).
+ */
+export async function listTemplateFiles(root) {
+    let files;
+    try {
+        const output = await runCapture("git", ["-C", root, "ls-files", "-co", "--exclude-standard", "-z"]);
+        files = output.split("\0").filter(Boolean);
+    }
+    catch {
+        files = await walk(root, root);
+    }
+    const kept = await Promise.all(files.map(async (file) => !isIgnoredTemplatePath(file) && (await pathExists(join(root, file))) ? file : null));
+    return kept.filter((file) => file !== null).sort();
+}
+async function walk(root, directory) {
+    const entries = await readdir(directory, { withFileTypes: true });
+    const files = [];
+    for (const entry of entries) {
+        const path = join(directory, entry.name);
+        if (entry.isDirectory()) {
+            if (!ignoredDirectories.has(entry.name))
+                files.push(...(await walk(root, path)));
+        }
+        else if (entry.isFile() && !isLocalSecret(entry.name)) {
+            files.push(relative(root, path).split(sep).join("/"));
+        }
+    }
+    return files;
+}
+export async function copyTemplateFiles(sourceRoot, targetRoot, files) {
+    for (const { from, to } of files) {
+        const target = join(targetRoot, to);
+        await mkdir(dirname(target), { recursive: true });
+        await copyFile(join(sourceRoot, from), target);
+    }
+}
+/** Removes everything inside a directory while keeping the directory itself. */
+export async function emptyDirectory(directory) {
+    for (const entry of await readdir(directory)) {
+        await rm(join(directory, entry), { recursive: true, force: true });
+    }
+}

package/dist/utils/names.js

@@ -0,0 +1,14 @@
+import { basename } from "node:path";
+export function packageNameFromDirectory(directory) {
+    return (basename(directory)
+        .toLowerCase()
+        .replace(/[^a-z0-9._-]+/g, "-")
+        .replace(/^[._-]+|[._-]+$/g, "") || "my-app");
+}
+export function displayNameFromPackageName(packageName) {
+    return packageName
+        .split(/[-._]+/)
+        .filter(Boolean)
+        .map((part) => part[0].toUpperCase() + part.slice(1))
+        .join(" ");
+}

package/dist/utils/process.js

@@ -0,0 +1,49 @@
+import { spawn } from "node:child_process";
+import process from "node:process";
+// Package manager shims on Windows are .cmd files, which need a shell to start.
+const useShell = process.platform === "win32";
+/** Runs a command with inherited output. Rejects on a non-zero exit. */
+export async function run(command, args, cwd) {
+    await new Promise((resolve, reject) => {
+        const child = spawn(command, args, { cwd, stdio: "inherit", shell: useShell });
+        child.once("error", reject);
+        child.once("exit", (code, signal) => {
+            if (code === 0)
+                resolve();
+            else
+                reject(new Error(`${command} exited with ${signal ? `signal ${signal}` : `code ${code}`}.`));
+        });
+    });
+}
+/** Runs a command and returns trimmed stdout. Rejects with stderr on a non-zero exit. */
+export async function runCapture(command, args, cwd) {
+    return await new Promise((resolve, reject) => {
+        const child = spawn(command, args, {
+            cwd,
+            shell: useShell,
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        let stdout = "";
+        let stderr = "";
+        child.stdout.on("data", (chunk) => (stdout += chunk.toString()));
+        child.stderr.on("data", (chunk) => (stderr += chunk.toString()));
+        child.once("error", reject);
+        child.once("exit", (code, signal) => {
+            if (code === 0) {
+                resolve(stdout.trim());
+                return;
+            }
+            const reason = signal ? `signal ${signal}` : `code ${code}`;
+            reject(new Error(`${command} exited with ${reason}${stderr.trim() ? `: ${stderr.trim()}` : "."}`));
+        });
+    });
+}
+export async function commandSucceeds(command, args) {
+    try {
+        await runCapture(command, args);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@clubedge/create-clubedge-app",
-  "version": "0.2.0",
-  "description": "Create a Next.js application from the Clubedge Starter reference implementation.",
+  "version": "0.3.0",
+  "description": "Create an application from the Clubedge Starter reference implementation.",
   "type": "module",
   "packageManager": "pnpm@10.9.0",
   "bin": {
@@ -9,6 +9,9 @@
   },
   "files": [
     "bin/",
+    "dist/",
+    "template/",
+    "template.lock.json",
     "README.md",
     "CHANGELOG.md",
     "LICENSE",
@@ -17,6 +20,11 @@
   "engines": {
     "node": ">=22.12.0"
   },
+  "clubedge": {
+    "starterRepository": "Clubedge/clubedge-starter",
+    "starterRef": "v0.3.0",
+    "starterCommit": "60f1691920c91a5cf83e480a3ce98c3ddefdef55"
+  },
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -34,12 +42,20 @@
     "scaffolding"
   ],
   "scripts": {
-    "start": "node ./bin/create.mjs",
-    "check": "node --check ./bin/create.mjs",
-    "test": "node --test"
+    "build": "tsc -p tsconfig.build.json",
+    "check": "tsc --noEmit",
+    "test": "vitest run",
+    "bundle-template": "node scripts/bundle-template.mjs",
+    "start": "pnpm build && node ./bin/create.mjs",
+    "prepack": "pnpm build"
   },
   "dependencies": {
     "@clack/prompts": "^1.8.1",
     "giget": "^2.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.5",
+    "typescript": "^5.9.3",
+    "vitest": "^5.0.3"
   }
 }

package/template/.dockerignore

@@ -0,0 +1,8 @@
+node_modules
+.pnpm-store
+.turbo
+.next
+.git
+.env*
+coverage
+playwright-report

package/template/.env.example

@@ -0,0 +1,25 @@
+NODE_ENV=development
+NEXT_PUBLIC_APP_URL=http://localhost:3000
+
+# Supabase PostgreSQL: use the transaction pooler with prepare disabled (configured in src/db).
+DATABASE_URL=postgresql://postgres.[project-ref]:[password]@aws-0-[region].pooler.supabase.com:6543/postgres
+
+# Supabase Auth (publishable key only; never put a service role key in the browser)
+NEXT_PUBLIC_SUPABASE_URL=
+NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=
+
+# Optional cache and rate limits (Redis protocol; rediss:// enables TLS)
+# Upstash example: rediss://default:YOUR_PASSWORD@your-database.upstash.io:6379
+REDIS_URL=
+
+# Storage adapter: s3 (works with AWS S3 and Cloudflare R2) or supabase
+STORAGE_PROVIDER=s3
+STORAGE_BUCKET=
+STORAGE_REGION=auto
+STORAGE_ENDPOINT=
+STORAGE_ACCESS_KEY_ID=
+STORAGE_SECRET_ACCESS_KEY=
+STORAGE_PUBLIC_URL=
+
+# Supabase Storage adapter
+SUPABASE_STORAGE_BUCKET=

package/template/.gitattributes

@@ -0,0 +1,6 @@
+# Keep LF endings on every platform so Prettier and shell scripts behave the same everywhere.
+* text=auto eol=lf
+*.ico binary
+*.png binary
+*.jpg binary
+*.webp binary

package/template/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,35 @@
+name: Bug report
+description: Report a reproducible problem in Clubedge Starter.
+title: "[Bug]: "
+labels: [bug]
+body:
+  - type: markdown
+    attributes:
+      value: Before submitting, search existing issues and remove secrets or personal data from logs.
+  - type: textarea
+    id: description
+    attributes:
+      label: What happened?
+      description: Describe the behavior and what you expected instead.
+    validations:
+      required: true
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Steps to reproduce
+      placeholder: Include the smallest set of steps that shows the problem.
+    validations:
+      required: true
+  - type: input
+    id: versions
+    attributes:
+      label: Environment
+      description: Include OS, Node.js, and pnpm versions.
+      placeholder: Windows 11, Node 22.12, pnpm 10.9.0
+    validations:
+      required: true
+  - type: textarea
+    id: logs
+    attributes:
+      label: Logs or screenshots
+      description: Redact tokens, passwords, URLs with credentials, and other private data.

package/template/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Setup and troubleshooting
+    url: https://github.com/Clubedge/clubedge-starter/blob/main/SETUP.md
+    about: Check the setup guide before opening an issue.
+  - name: Report a security vulnerability privately
+    url: https://github.com/Clubedge/clubedge-starter/security/advisories/new
+    about: Do not post vulnerability details in a public issue.

package/template/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,24 @@
+name: Feature request
+description: Suggest an improvement or capability.
+title: "[Feature]: "
+labels: [enhancement]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: What problem should this solve?
+      description: Describe the use case and who benefits.
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+      description: Describe the change you have in mind. Alternatives are welcome.
+    validations:
+      required: true
+  - type: textarea
+    id: details
+    attributes:
+      label: Additional context
+      description: Include links, examples, or constraints that would help evaluate the request.

package/template/.github/pull_request_template.md

@@ -0,0 +1,20 @@
+## Summary
+
+<!-- What changed and why? Link related issues with "Closes #123" when applicable. -->
+
+## Changes
+
+<!-- List the meaningful changes. -->
+
+## Verification
+
+- [ ] `pnpm lint`
+- [ ] `pnpm typecheck`
+- [ ] `pnpm test`
+- [ ] `pnpm format:check`
+- [ ] `pnpm build`
+- [ ] `pnpm test:e2e` (when browser behavior changed)
+
+## Notes for reviewers
+
+<!-- Include screenshots, migration details, environment changes, or known limitations. -->

package/template/.github/workflows/ci.yml

@@ -0,0 +1,49 @@
+name: CI
+on:
+  pull_request:
+  push:
+    branches: [main]
+  workflow_dispatch:
+permissions:
+  contents: read
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    env:
+      DATABASE_URL: postgresql://postgres:postgres@127.0.0.1:5432/postgres
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm format:check
+      - run: pnpm lint
+      - run: pnpm typecheck
+      - run: pnpm test
+      - run: pnpm exec playwright install --with-deps chromium
+      - run: pnpm test:e2e
+      - run: pnpm build
+      - run: pnpm audit --audit-level high
+
+  docker:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Build the production image
+        run: docker build --tag clubedge-starter:ci .
+      - name: Start the image and check health
+        run: |
+          set -euo pipefail
+          docker run --detach --name app --publish 3000:3000             --env DATABASE_URL=postgresql://postgres:postgres@127.0.0.1:5432/postgres             clubedge-starter:ci
+          trap 'docker logs app; docker rm --force app' EXIT
+          for attempt in $(seq 1 30); do
+            if curl --fail --silent http://127.0.0.1:3000/api/health; then
+              exit 0
+            fi
+            sleep 2
+          done
+          echo "The container did not become healthy."
+          exit 1

package/template/.prettierignore

@@ -0,0 +1 @@
+pnpm-lock.yaml

package/template/.prettierrc.json

@@ -0,0 +1 @@
+{ "semi": true, "singleQuote": false, "trailingComma": "all", "printWidth": 100 }

package/template/AGENTS.md

@@ -0,0 +1,31 @@
+# Agent guide
+
+## Architecture rules
+
+- `packages/{core,auth,cache,db,storage}` are framework-agnostic. Never import `next`, `react`, `server-only`, `@tanstack/*`, or app code (`@/…`) there. Accept configuration, clients, and cookies as function arguments.
+- `packages/core` depends on no other workspace package.
+- `apps/web/src/server/` is the composition root: the only place that reads environment variables, bridges Next.js cookies to `CookieStore`, and picks providers. Routes, server actions, and components import from `@/server/*`, never from `@supabase/*`, `@aws-sdk/*`, `redis`, or `postgres`.
+- Expected failures (bad credentials, invalid codes) are returned as `Result` values from `@clubedge/core`; exceptions are for unexpected errors.
+- Project identity (name, description, links) lives in `apps/web/src/config/site.json`; `create-clubedge-app` rewrites that file, so do not hard-code the project name elsewhere.
+- `pnpm lint` enforces these boundaries. Run `pnpm lint`, `pnpm typecheck`, and `pnpm test` before finishing a change.
+
+<!-- BEGIN:nextjs-agent-rules -->
+
+## This is NOT the Next.js you know
+
+This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` (resolved from this file's directory; in monorepos the `next` package may not be visible from the repo root) before writing any code. Heed deprecation notices.
+
+This block is written and re-added by `next dev` — verify at `node_modules/next/dist/server/lib/generate-agent-files.js`. Removing it from a diff only re-creates the uncommitted change; committing it with your work keeps the tree clean.
+
+<!-- END:nextjs-agent-rules -->
+
+<!-- BEGIN:turborepo-agent-rules -->
+
+# This is NOT the Turborepo you know
+
+Turborepo configuration, task behavior, and CLI commands can vary between installed versions and may differ from your training data. Resolve the `turbo` package from this file's directory or relevant workspace; in monorepos, it may not be visible from the repository root. For example, run `node -p "require.resolve('turbo/package.json')"` from a workspace that depends on `turbo`.
+
+Read `docs/README.md` inside that installed package first, then read the relevant pages from its `docs/` directory before changing Turborepo configuration or commands. Heed deprecation notices. These bundled docs match the installed package version and are available without network access.
+
+This block is written and re-added by `turbo` before repository-scoped commands when an AI agent is detected. In the Turborepo source repository, its template is defined in `crates/turborepo-cli/src/cli/agent_guidance.rs`. Removing the managed block while updates are enabled means a later qualifying invocation will add it again. Set `"agentGuidance": false` in the root `turbo.json` or `turbo.jsonc` to opt out; this does not remove an existing block. Keep the block committed with your work to avoid an uncommitted change on the next agent invocation.
+<!-- END:turborepo-agent-rules -->

package/template/CODE_OF_CONDUCT.md

@@ -0,0 +1,22 @@
+# Code of Conduct
+
+## Our commitment
+
+We are committed to making participation in Clubedge Starter welcoming and respectful for everyone, regardless of experience, identity, background, or point of view.
+
+## Expected behavior
+
+- Be considerate, respectful, and constructive.
+- Critique ideas and code without personal attacks.
+- Accept feedback and focus on what is best for the project and its users.
+- Respect privacy. Do not publish private information or credentials.
+
+## Unacceptable behavior
+
+Harassment, discrimination, intimidation, personal attacks, unwanted sexual attention, doxxing, and other conduct that would reasonably make someone feel unsafe are not acceptable in project spaces.
+
+## Enforcement
+
+Project maintainers may edit or remove contributions and may restrict participation when behavior violates this code. Report conduct concerns privately to the repository owner through [their GitHub profile](https://github.com/Clubedge). Reports will be handled as confidentially as practical.
+
+This code applies in repository discussions, issues, pull requests, and other spaces when someone is representing this project.

package/template/CONTRIBUTING.md

@@ -0,0 +1,53 @@
+# Contributing
+
+Thanks for helping improve Clubedge Starter. Contributions of code, documentation, bug reports, and focused feature proposals are welcome.
+
+## Before you start
+
+- Check existing issues and pull requests for related work.
+- For a large or user-visible change, open an issue first so we can agree on the scope.
+- For security concerns, follow [SECURITY.md](SECURITY.md) instead of opening a public issue.
+- Keep pull requests focused. Explain the problem, the change, and any setup or migration impact.
+
+## Development setup
+
+Follow [SETUP.md](SETUP.md) to install dependencies and configure local services. Most changes can be checked with:
+
+```sh
+pnpm lint
+pnpm typecheck
+pnpm test
+pnpm format:check
+pnpm build
+```
+
+Run `pnpm test:e2e` for changes that affect browser behavior. It requires a locally installed Playwright browser. CI runs the full configured verification workflow for pull requests.
+
+## Contribution workflow
+
+1. Fork the repository and create a focused branch from `main`.
+2. Make the change and add or update coverage and documentation where appropriate.
+3. Run the checks relevant to the change and review `git diff` for secrets or generated output.
+4. Open a pull request against `main`, describe the user impact, and link the related issue when there is one.
+5. Respond to review feedback; maintainers will use the pull request checks and discussion to decide when the change is ready to merge.
+
+## Project conventions
+
+- Keep application code in `apps/web`, reusable shadcn/ui code in `packages/ui`, and framework-agnostic infrastructure in `packages/{core,auth,db,storage,cache}`.
+- Reach providers through `apps/web/src/server` rather than scattering provider SDK calls through routes and components. `pnpm lint` enforces these boundaries.
+- Keep server secrets out of client code and out of committed files. Update `.env.example` when adding configuration, using placeholders only.
+- For database changes, update the Drizzle schema and generate, review, and commit the migration. Do not maintain a second migration history for the same application tables.
+- For shared UI changes, preserve compatibility between both `components.json` files and use the established package exports.
+- Update docs when commands, configuration, or behavior change.
+- `clubedge.template.json` tells `create-clubedge-app` how to scaffold this repository. Keep it in step when moving the app, the site config, the environment example, or the Docker image name; `pnpm test` checks it.
+- Follow the existing formatting and TypeScript conventions. Prefer a small dependency footprint and explain new runtime dependencies in the pull request.
+
+## Pull request checklist
+
+- [ ] The change addresses an issue or clearly explains its motivation.
+- [ ] Documentation and `.env.example` are updated when needed.
+- [ ] Database migrations are included and reviewed when schema changes.
+- [ ] Relevant lint, typecheck, unit, formatting, and build checks pass locally.
+- [ ] No credentials, generated build output, or unrelated changes are included.
+
+By submitting a contribution for inclusion, you agree that it will be distributed under the repository's [Apache License, Version 2.0](LICENSE), consistent with section 5 of that license. No separate contributor license agreement is currently required.

package/template/Dockerfile

@@ -0,0 +1,32 @@
+FROM node:22-alpine AS base
+RUN corepack enable
+WORKDIR /app
+
+# Reduce the workspace to the web app and the packages it depends on, split into manifests
+# (for a cacheable install layer) and full sources. New packages are picked up automatically.
+FROM base AS pruner
+COPY . .
+RUN pnpm dlx turbo@^2.5.0 prune @clubedge/web --docker
+
+FROM base AS deps
+COPY --from=pruner /app/out/json/ .
+RUN pnpm install --frozen-lockfile
+
+FROM base AS builder
+ENV NEXT_TELEMETRY_DISABLED=1
+COPY --from=deps /app/ .
+COPY --from=pruner /app/out/full/ .
+COPY tsconfig.base.json ./
+RUN pnpm build
+
+FROM node:22-alpine AS runner
+ENV NODE_ENV=production NEXT_TELEMETRY_DISABLED=1 HOSTNAME=0.0.0.0 PORT=3000
+WORKDIR /app
+RUN addgroup --system --gid 1001 nodejs && adduser --system --uid 1001 nextjs
+COPY --from=builder --chown=nextjs:nodejs /app/apps/web/.next/standalone ./
+COPY --from=builder --chown=nextjs:nodejs /app/apps/web/public ./apps/web/public
+COPY --from=builder --chown=nextjs:nodejs /app/apps/web/.next/static ./apps/web/.next/static
+WORKDIR /app/apps/web
+USER nextjs
+EXPOSE 3000
+CMD ["node", "server.js"]