ecopages 0.2.0-beta.9 → 0.2.0-rc.1

package/README.md

@@ -6,10 +6,16 @@ It provides scaffolding and development commands to streamline your workflow. It
 
 ## Quick Start
 
-Initialize a new project from the default template:
+Initialize a new project from the interactive template picker:
 
 ```bash
-bunx ecopages init my-app
+bunx ecopages init
+```
+
+For a deterministic invocation, select a template explicitly:
+
+```bash
+bunx ecopages init my-app --template react
 cd my-app
 bun install
 bun dev
@@ -17,31 +23,42 @@ bun dev
 
 ## Commands
 
-| Command                      | Description                                | Equivalent (Bun)                |
-| :--------------------------- | :----------------------------------------- | :------------------------------ |
-| `ecopages init <dir>`        | Scaffolds a new project                    | N/A                             |
-| `ecopages dev [entry]`       | Starts the dev server                      | `bun run [entry] --dev`         |
-| `ecopages dev:watch [entry]` | Dev server + hard restarts on file changes | `bun --watch run [entry] --dev` |
-| `ecopages dev:hot [entry]`   | Dev server + HMR (no hard restarts)        | `bun --hot run [entry] --dev`   |
-| `ecopages build [entry]`     | Creates a production build                 | `bun run [entry] --build`       |
-| `ecopages start [entry]`     | Starts the production server               | `bun run [entry]`               |
-| `ecopages preview [entry]`   | Previews the production build locally      | `bun run [entry] --preview`     |
+| Command               | Description                                         | Equivalent (Bun)                |
+| :-------------------- | :-------------------------------------------------- | :------------------------------ |
+| `ecopages init [dir]` | Scaffolds a new project (interactive without `dir`) | N/A                             |
+| `ecopages dev`        | Starts the dev server                               | `bun run [entry] --dev`         |
+| `ecopages dev:watch`  | Dev server + hard restarts on file changes          | `bun --watch run [entry] --dev` |
+| `ecopages dev:hot`    | Dev server + HMR (no hard restarts)                 | `bun --hot run [entry] --dev`   |
+| `ecopages build`      | Creates a production build                          | `bun run [entry] --build`       |
+| `ecopages start`      | Starts the production server                        | `bun run [entry]`               |
+| `ecopages preview`    | Previews the production build locally               | `bun run [entry] --preview`     |
 
 > [!NOTE]
-> `[entry]` defaults to `app.ts` if not provided.
+> The entry file defaults to `app.ts`. Override it with `--entry-file`.
+
+### Templates
+
+Official templates are versioned with the CLI release. Use `--template <id>` for an official template or `--from <source>` for a community Git template. Community sources support giget provider notation and GitHub, GitLab, Bitbucket, and SourceHut repository URLs.
+
+```bash
+ecopages init my-site --template jsx
+ecopages init my-site --from github:acme/my-template#v1.0.0
+```
+
+The official template IDs are `jsx`, `react`, `lit-jsx`, `radiant`, `blog-jsx`, `blog-react`, `docs-starter`, `react-better-auth`, and `llm-wiki`.
 
 ## Environment & Runtime Options
 
 Server and build commands accept the following options. They automatically map to the equivalent environment variables for the underlying process:
 
-| Option                     | Env Var                 | Description                         |
-| :------------------------- | :---------------------- | :---------------------------------- |
-| `-p, --port <port>`        | `ECOPAGES_PORT`         | Server port (default 3000)          |
-| `-n, --hostname <host>`    | `ECOPAGES_HOSTNAME`     | Server hostname                     |
-| `-b, --base-url <url>`     | `ECOPAGES_BASE_URL`     | Base URL string                     |
-| `-d, --debug`              | `ECOPAGES_LOGGER_DEBUG` | Enables debug-level logging         |
-| `-r, --react-fast-refresh` |                         | Enables React Fast Refresh          |
-| `--runtime <runtime>`      |                         | Force execution via `bun` or `node` |
+| Option                     | Env Var                 | Description                                               |
+| :------------------------- | :---------------------- | :-------------------------------------------------------- |
+| `-p, --port <port>`        | `ECOPAGES_PORT`         | Server port (default 3000)                                |
+| `-n, --hostname <host>`    | `ECOPAGES_HOSTNAME`     | Server hostname                                           |
+| `-b, --base-url <url>`     | `ECOPAGES_BASE_URL`     | Base URL string                                           |
+| `-d, --debug`              | `ECOPAGES_LOGGER_DEBUG` | Enables debug logging and startup phase trace (see below) |
+| `-r, --react-fast-refresh` |                         | Enables React Fast Refresh                                |
+| `--runtime <runtime>`      |                         | Force execution via `bun` or `node`                       |
 
 ### Runtime Detection
 
@@ -63,6 +80,37 @@ ecopages dev --port 8080 --debug
 ecopages dev -r
 ```
 
+### Debug logging and startup trace
+
+Set these in `.env` or on the command line when diagnosing slow dev startup or first page load.
+
+| Env var                       | CLI                    | What you get                                                                                   |
+| :---------------------------- | :--------------------- | :--------------------------------------------------------------------------------------------- |
+| `ECOPAGES_LOGGER_DEBUG=true`  | `ecopages dev --debug` | Verbose `[@ecopages/core]` logs across the stack, plus **startup phase trace** lines on stderr |
+| `ECOPAGES_STARTUP_TRACE=true` | —                      | **Only** the phase trace (no extra debug noise). Useful when measuring first-open latency      |
+
+Trace lines are prefixed with `[ecopages:startup-trace]` and look like:
+
+```text
+[ecopages:startup-trace] phase=config-ready wallMs=1271
+[ecopages:startup-trace] phase=setupAppRuntimePlugins durationMs=714 wallMs=1999
+[ecopages:startup-trace] phase=route-registry durationMs=1 wallMs=2000
+[ecopages:startup-trace] phase=server-listen durationMs=45 wallMs=2046
+[ecopages:startup-trace] phase=dev-client-transform durationMs=42 wallMs=2100
+[ecopages:startup-trace] phase=first-request-ssr durationMs=5296 wallMs=12495
+[ecopages:startup-trace] summary path=/docs/getting-started/introduction bundleCount=13 clientBundleBytes=858396 wallMs=12496
+```
+
+Phases: config ready → runtime plugins → route registry → server listening → first request SSR (with per-module `dev-client-transform` on demand for `/assets/__eco_dev__/` modules). The summary includes bundle count and total client JS bytes for that first request.
+
+```bash
+# Focused perf trace only
+ECOPAGES_STARTUP_TRACE=true pnpm dev
+
+# Full debug + trace
+ecopages dev --debug
+```
+
 ## Ecosystem & Plugins
 
 Ecopages relies on a modular architecture. Core logic and framework integrations are published as `@ecopages/*` packages on [npm](https://www.npmjs.com/org/ecopages).

package/bin/brand.js

@@ -0,0 +1,42 @@
+import { styleText } from 'node:util';
+
+/**
+ * Terminal mark rasterized from `assets/brand/logo-on-light.svg`.
+ * @remarks Half-blocks keep rows flush; a thin stroke leaves the spiral's inner gaps open.
+ */
+const BRAND_MARK_LINES = [
+	'                ▄▄▄▄',
+	'        ▄▄▄▄█▀▀▀▀▄█',
+	'    ▄▄▀▀▀        ██',
+	' ▄█▀      ▄▄▄▄   █',
+	'▄█       █▀  ██  █',
+	'█▄  ▀█▄ ██  ▄█  ██',
+	' █▄   ▀▀██▀▀▀   █',
+	'  ▀▀█▄  ▀█    ▄█▀',
+	'  ▄█▀     ▀▀▀▀▀',
+	' █▀',
+	'▀',
+];
+
+export function formatBrandBanner(version, stream = process.stdout) {
+	const markWidth = Math.max(...BRAND_MARK_LINES.map((line) => [...line].length));
+	const versionLabel = stream.hasColors?.() ? styleText('dim', version) : version;
+	const labels = ['ecopages', versionLabel];
+	const labelStart = Math.max(0, Math.floor((BRAND_MARK_LINES.length - labels.length) / 2));
+
+	return BRAND_MARK_LINES.map((line, index) => {
+		const padded = `${line}${' '.repeat(markWidth - [...line].length)}`;
+		const label = labels[index - labelStart];
+		return label === undefined ? padded : `${padded}  ${label}`;
+	}).join('\n');
+}
+
+export function withBrandBanner(version, text) {
+	if (!process.stdout.isTTY) return text;
+	return `${formatBrandBanner(version)}\n\n${text}`;
+}
+
+export function printBrandBanner(version) {
+	if (!process.stderr.isTTY) return;
+	process.stderr.write(`${formatBrandBanner(version, process.stderr)}\n\n`);
+}