ecopages 0.2.0-rc.0 → 0.2.0-rc.10

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,18 +23,29 @@ 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 (supervises config/.env restarts) | `bun run [entry] --dev`                                      |
+| `ecopages dev:watch`  | Dev server + hard restarts on file changes              | Bun: `bun --watch run [entry] --dev`; Node: `node --watch …` |
+| `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
 
@@ -63,6 +80,8 @@ ecopages dev --port 8080 --debug
 ecopages dev -r
 ```
 
+During `ecopages dev`, adding, changing, or removing `eco.config.ts` (or `--config`) and supported project `.env` files restarts the dev server automatically. The CLI supervises that restart and reloads dotenv files. When the preferred port is busy, development startup uses the same fallback flow as preview: TTY sessions show a Clack confirmation, while non-interactive sessions scan automatically only when the port was not pinned with `--port` or `ECOPAGES_PORT`.
+
 ### Debug logging and startup trace
 
 Set these in `.env` or on the command line when diagnosing slow dev startup or first page load.

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`);
+}

package/bin/cli.js

@@ -1,12 +1,15 @@
 #!/usr/bin/env node
 
-import { downloadTemplate } from 'giget';
-import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { spawn } from 'node:child_process';
-import { join } from 'node:path';
 import { parseArgs } from 'node:util';
 import { Logger } from '@ecopages/logger';
 import { createLaunchPlan } from './launch-plan.js';
+import {
+	ECOPAGES_DEV_RESTART_EXIT_CODE,
+	ECOPAGES_DEV_RESTART_REASON_ENV,
+} from '@ecopages/core/dev/development-restart';
+import { withBrandBanner } from './brand.js';
 
 const logger = new Logger('[ecopages:cli]', { debug: process.env.ECOPAGES_LOGGER_DEBUG === 'true' });
 
@@ -40,18 +43,9 @@ const sharedServerOptionDefinitions = {
 		type: 'string',
 		short: 'e',
 	},
-	help: {
-		type: 'boolean',
-		short: 'h',
-	},
-};
-
-const initOptionDefinitions = {
-	template: {
-		type: 'string',
-	},
-	repo: {
+	config: {
 		type: 'string',
+		short: 'c',
 	},
 	help: {
 		type: 'boolean',
@@ -61,12 +55,10 @@ const initOptionDefinitions = {
 
 function getMainHelpText() {
 	return [
-		`ecopages ${pkg.version}`,
-		'',
 		'Usage: ecopages <command> [options]',
 		'',
 		'Commands:',
-		'  init <dir>              Initialize a new project from a template',
+		'  init [dir]              Initialize a new project from a template',
 		'  dev                     Start the development server',
 		'  dev:watch               Start the development server with watch mode',
 		'  dev:hot                 Start the development server with hot reload',
@@ -76,6 +68,7 @@ function getMainHelpText() {
 		'',
 		'Global options:',
 		'  -e, --entry-file <file> Entry file (default: app.ts)',
+		'  -c, --config <file>     Ecopages config file (default: eco.config.ts)',
 		'  -h, --help              Show help',
 		'  --version               Show version',
 	].join('\n');
@@ -95,6 +88,7 @@ function getServerCommandHelpText(commandName, description) {
 		'  -r, --react-fast-refresh                Enable React Fast Refresh for Bun HMR',
 		'      --runtime <runtime>                 Force bun or node',
 		'  -e, --entry-file <file>                 Entry file (default: app.ts)',
+		'  -c, --config <file>                     Ecopages config file (default: eco.config.ts)',
 		'  -h, --help                              Show help',
 	].join('\n');
 }
@@ -113,19 +107,7 @@ function getBuildCommandHelpText() {
 		'  -r, --react-fast-refresh                Enable React Fast Refresh for Bun HMR',
 		'      --runtime <runtime>                 Force bun or node',
 		'  -e, --entry-file <file>                 Entry file (default: app.ts)',
-		'  -h, --help                              Show help',
-	].join('\n');
-}
-
-function getInitCommandHelpText() {
-	return [
-		'Usage: ecopages init <dir> [options]',
-		'',
-		'Initialize a new project from a template.',
-		'',
-		'Options:',
-		'      --template <template>               Template name from ecopages/examples/',
-		'      --repo <repo>                       GitHub repo in user/repo form',
+		'  -c, --config <file>                     Ecopages config file (default: eco.config.ts)',
 		'  -h, --help                              Show help',
 	].join('\n');
 }
@@ -164,30 +146,12 @@ function parseServerCommandArgs(rawArgs, commandName, description, mode = 'serve
 			debug: values.debug,
 			reactFastRefresh: values['react-fast-refresh'],
 			runtime: values.runtime,
+			configFile: values.config,
 		},
 	};
 }
 
-function parseInitCommandArgs(rawArgs) {
-	const { values, positionals } = parseCommandArguments(rawArgs, initOptionDefinitions);
-
-	if (values.help) {
-		console.log(getInitCommandHelpText());
-		return { help: true };
-	}
-
-	if (positionals.length !== 1) {
-		throw new Error('The `init` command requires exactly one target directory argument.');
-	}
-
-	return {
-		dir: positionals[0],
-		template: values.template ?? 'starter-jsx',
-		repo: values.repo ?? 'ecopages/ecopages',
-	};
-}
-
-function runLaunchPlan(launchPlan) {
+function runLaunchPlan(launchPlan, options = {}) {
 	if (Object.keys(launchPlan.envOverrides).length > 0) {
 		logger.debug(`Environment overrides: ${JSON.stringify(launchPlan.envOverrides)}`);
 	}
@@ -215,6 +179,11 @@ function runLaunchPlan(launchPlan) {
 	});
 
 	child.on('exit', (code) => {
+		if (options.superviseDevRestarts && code === ECOPAGES_DEV_RESTART_EXIT_CODE) {
+			options.onDevRestart?.();
+			return;
+		}
+
 		process.exit(code || 0);
 	});
 }
@@ -227,61 +196,38 @@ function runLaunchPlan(launchPlan) {
  * @param {string} entryFile - Entry file to run
  */
 async function runEntryCommand(args, options = {}, entryFile = 'app.ts', launchMode = 'start') {
-	let launchPlan;
 	const requiresBuiltBundle = launchMode === 'start';
+	const superviseDevRestarts = launchMode === 'dev';
 
 	if (!requiresBuiltBundle && !existsSync(entryFile)) {
 		logger.error(`Error: Entry file "${entryFile}" not found in the current directory.`);
 		process.exit(1);
 	}
 
-	try {
-		launchPlan = await createLaunchPlan(args, options, entryFile, launchMode);
-	} catch (error) {
-		const message = error instanceof Error ? error.message : String(error);
-		logger.error(message);
-		process.exit(1);
-	}
-
-	runLaunchPlan(launchPlan);
-}
-
-async function runInitCommand(rawArgs) {
-	const parsed = parseInitCommandArgs(rawArgs);
-
-	if (parsed.help) {
-		return;
-	}
-
-	const { dir, template, repo } = parsed;
-
-	if (existsSync(dir)) {
-		logger.error(`Target directory already exists: ${dir}`);
-		process.exit(1);
-	}
+	const launchChild = async (restartReason) => {
+		let launchPlan;
+		try {
+			launchPlan = await createLaunchPlan(args, options, entryFile, launchMode);
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			logger.error(message);
+			process.exit(1);
+		}
 
-	logger.info(`Creating target directory '${dir}'...`);
+		if (restartReason) {
+			launchPlan.env[ECOPAGES_DEV_RESTART_REASON_ENV] = restartReason;
+			launchPlan.envOverrides[ECOPAGES_DEV_RESTART_REASON_ENV] = restartReason;
+		}
 
-	try {
-		await downloadTemplate(`github:${repo}/examples/${template}`, {
-			dir,
-			force: true,
+		runLaunchPlan(launchPlan, {
+			superviseDevRestarts,
+			onDevRestart: () => {
+				void launchChild('configuration or environment change');
+			},
 		});
+	};
 
-		const pkgPath = join(dir, 'package.json');
-		if (existsSync(pkgPath)) {
-			const projectPkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
-			projectPkg.name = dir;
-			writeFileSync(pkgPath, JSON.stringify(projectPkg, null, 2) + '\n');
-			logger.info(`Renamed project to '${dir}'`);
-		}
-
-		logger.info('Project initialized! Run `bun install && bun dev` to start.');
-	} catch (error) {
-		const message = error instanceof Error ? error.message : String(error);
-		logger.error(`Failed to fetch template: ${message}`);
-		process.exit(1);
-	}
+	await launchChild();
 }
 
 async function runServerCommand(rawArgs, definition) {
@@ -303,7 +249,7 @@ export async function runCli(rawArgs = process.argv.slice(2)) {
 	const [commandName, ...commandArgs] = rawArgs;
 
 	if (!commandName || commandName === '--help' || commandName === '-h') {
-		console.log(getMainHelpText());
+		console.log(withBrandBanner(pkg.version, getMainHelpText()));
 		return;
 	}
 
@@ -314,9 +260,11 @@ export async function runCli(rawArgs = process.argv.slice(2)) {
 
 	try {
 		switch (commandName) {
-			case 'init':
-				await runInitCommand(commandArgs);
+			case 'init': {
+				const { runInitCommand } = await import('./init.js');
+				await runInitCommand(commandArgs, logger);
 				return;
+			}
 			case 'dev':
 				await runServerCommand(commandArgs, {
 					name: 'dev',

package/bin/git-template-source-providers.js

@@ -0,0 +1,56 @@
+import { repositoryName, withSubpath } from './git-template-source-shared.js';
+
+export function normalizeGithubParts(parts, source) {
+	if (parts.length < 2) {
+		return null;
+	}
+
+	const [owner, repositoryPart, marker, ref, ...subpath] = parts;
+	const repository = `${owner}/${repositoryName(repositoryPart)}`;
+	if (marker === 'tree' || marker === 'blob') {
+		if (!ref) throw new Error(`Template URL '${source}' is missing a Git ref.`);
+		return `github:${withSubpath(repository, subpath)}#${ref}`;
+	}
+	return `github:${repository}`;
+}
+
+export function normalizeGitlabParts(parts) {
+	const markerIndex = parts.indexOf('-');
+	const treeIndex = parts.findIndex((part) => part === 'tree' || part === 'blob');
+	if (markerIndex > 0 && treeIndex > markerIndex && parts[treeIndex + 1]) {
+		const repository = parts.slice(0, markerIndex).map(repositoryName).join('/');
+		const ref = parts[treeIndex + 1];
+		const subpath = parts.slice(treeIndex + 2);
+		return `gitlab:${withSubpath(repository, subpath)}#${ref}`;
+	}
+	if (parts.length >= 2) return `gitlab:${parts.join('/')}`;
+	return null;
+}
+
+export function normalizeBitbucketParts(parts) {
+	if (parts.length < 2) {
+		return null;
+	}
+
+	const [workspace, repositoryPart, marker, ref, ...subpath] = parts;
+	const repository = `${workspace}/${repositoryName(repositoryPart)}`;
+	if (marker === 'src' && ref) {
+		return `bitbucket:${withSubpath(repository, subpath)}#${ref}`;
+	}
+	return `bitbucket:${repository}`;
+}
+
+export function normalizeSourcehutParts(parts) {
+	if (parts.length < 2) {
+		return null;
+	}
+
+	const treeIndex = parts.findIndex((part) => part === 'tree' || part === 'blob');
+	if (treeIndex > 1 && parts[treeIndex + 1]) {
+		const repository = parts.slice(0, treeIndex).map(repositoryName).join('/');
+		const ref = parts[treeIndex + 1];
+		const subpath = parts.slice(treeIndex + 2);
+		return `sourcehut:${withSubpath(repository, subpath)}#${ref}`;
+	}
+	return `sourcehut:${parts.join('/')}`;
+}

package/bin/git-template-source-shared.js

@@ -0,0 +1,7 @@
+export function repositoryName(value) {
+	return value.replace(/\.git$/u, '');
+}
+
+export function withSubpath(repository, subpath) {
+	return subpath.length > 0 ? `${repository}/${subpath.join('/')}` : repository;
+}

package/bin/git-template-source.js

@@ -0,0 +1,62 @@
+import {
+	normalizeBitbucketParts,
+	normalizeGithubParts,
+	normalizeGitlabParts,
+	normalizeSourcehutParts,
+} from './git-template-source-providers.js';
+
+const GIT_PROVIDER_PREFIX = /^(github|gitlab|bitbucket|sourcehut):/u;
+
+const HOST_PROVIDER = {
+	'github.com': 'github',
+	'gitlab.com': 'gitlab',
+	'bitbucket.org': 'bitbucket',
+	'git.sr.ht': 'sourcehut',
+};
+
+const PROVIDER_NORMALIZERS = {
+	github: normalizeGithubParts,
+	gitlab: normalizeGitlabParts,
+	bitbucket: normalizeBitbucketParts,
+	sourcehut: normalizeSourcehutParts,
+};
+
+function normalizeProviderUrl(hostProvider, parts, source) {
+	const normalize = PROVIDER_NORMALIZERS[hostProvider];
+	const normalized = normalize?.(parts, source);
+	if (normalized) {
+		return normalized;
+	}
+
+	throw new Error(`Unsupported template URL '${source}'. Include a repository and optional Git ref.`);
+}
+
+/**
+ * Normalizes a Git provider URL or giget source into a giget template source.
+ */
+export function normalizeGitSource(source) {
+	if (GIT_PROVIDER_PREFIX.test(source)) {
+		return source;
+	}
+
+	let url;
+	try {
+		url = new URL(source);
+	} catch {
+		throw new Error(`Unsupported template source '${source}'. Use a Git provider URL or giget source.`);
+	}
+
+	const hostProvider = HOST_PROVIDER[url.hostname];
+	if (!hostProvider) {
+		throw new Error(
+			`Unsupported template host '${url.hostname}'. Supported hosts are GitHub, GitLab, Bitbucket, and SourceHut.`,
+		);
+	}
+
+	const parts = url.pathname
+		.replace(/^\/+|\/+$/gu, '')
+		.split('/')
+		.filter(Boolean);
+
+	return normalizeProviderUrl(hostProvider, parts, source);
+}

package/bin/init.js

@@ -0,0 +1,392 @@
+import { downloadTemplate } from 'giget';
+import * as prompts from '@clack/prompts';
+import { existsSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { spawn } from 'node:child_process';
+import { basename, join } from 'node:path';
+import { parseArgs } from 'node:util';
+import { printBrandBanner, withBrandBanner } from './brand.js';
+import { normalizeGitSource } from './git-template-source.js';
+
+const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf-8'));
+const templateManifest = JSON.parse(readFileSync(new URL('../templates.json', import.meta.url), 'utf-8'));
+const officialTemplates = [...templateManifest.templates].sort((left, right) => left.order - right.order);
+const defaultOfficialTemplate = officialTemplates.find((template) => template.default) ?? officialTemplates[0];
+
+const initOptionDefinitions = {
+	template: {
+		type: 'string',
+	},
+	repo: {
+		type: 'string',
+	},
+	from: {
+		type: 'string',
+	},
+	interactive: {
+		type: 'boolean',
+	},
+	'no-interactive': {
+		type: 'boolean',
+	},
+	install: {
+		type: 'boolean',
+	},
+	'no-install': {
+		type: 'boolean',
+	},
+	start: {
+		type: 'boolean',
+	},
+	'no-start': {
+		type: 'boolean',
+	},
+	help: {
+		type: 'boolean',
+		short: 'h',
+	},
+};
+
+function getInitCommandHelpText() {
+	return [
+		'Usage: ecopages init [dir] [options]',
+		'',
+		'Initialize a new project from a template.',
+		'',
+		'With no directory in a TTY, starts the interactive project creator.',
+		'',
+		'Options:',
+		'      --template <id>                     Official template ID',
+		'      --from <source>                     Community Git template source',
+		'      --interactive                       Force interactive mode',
+		'      --no-interactive                    Disable interactive mode',
+		'      --install                           Install dependencies',
+		'      --no-install                        Skip dependency installation',
+		'      --start                             Install and start the dev server',
+		'      --no-start                          Do not start the dev server',
+		'  -h, --help                              Show help',
+	].join('\n');
+}
+
+function parseExclusiveBoolean(enable, disable, enableFlag, disableFlag) {
+	if (enable && disable) {
+		throw new Error(`The \`${enableFlag}\` and \`${disableFlag}\` options cannot be used together.`);
+	}
+	if (enable) return true;
+	if (disable) return false;
+	return undefined;
+}
+
+function parseInitCommandArgs(rawArgs) {
+	const { values, positionals } = parseArgs({
+		args: rawArgs,
+		options: initOptionDefinitions,
+		allowPositionals: true,
+		strict: true,
+	});
+
+	if (values.help) {
+		console.log(withBrandBanner(pkg.version, getInitCommandHelpText()));
+		return { help: true };
+	}
+
+	if (positionals.length > 1) {
+		throw new Error('The `init` command accepts at most one target directory argument.');
+	}
+
+	if (values.template && values.from) {
+		throw new Error('The `--template` and `--from` options cannot be used together.');
+	}
+
+	if (values.repo) {
+		throw new Error('The `--repo` option was removed. Use `--from <source>` instead.');
+	}
+
+	const interactive = parseExclusiveBoolean(
+		values.interactive,
+		values['no-interactive'],
+		'--interactive',
+		'--no-interactive',
+	);
+	const install = parseExclusiveBoolean(values.install, values['no-install'], '--install', '--no-install');
+	const start = parseExclusiveBoolean(values.start, values['no-start'], '--start', '--no-start');
+
+	if (start && install === false) {
+		throw new Error('The `--start` option requires dependency installation.');
+	}
+
+	const dir = positionals[0];
+	const useInteractive = interactive ?? (!dir && Boolean(process.stdin.isTTY));
+
+	if (!dir && !useInteractive) {
+		throw new Error(
+			'A target directory is required outside a TTY. Run `ecopages init --interactive` to use prompts.',
+		);
+	}
+
+	return {
+		dir,
+		template: values.template,
+		from: values.from,
+		interactive: useInteractive,
+		install,
+		start,
+	};
+}
+
+function findOfficialTemplate(templateId) {
+	const template = officialTemplates.find((candidate) => candidate.id === templateId);
+	if (!template) {
+		const available = officialTemplates.map((candidate) => candidate.id).join(', ');
+		throw new Error(`Unknown official template '${templateId}'. Available templates: ${available}`);
+	}
+
+	return template;
+}
+
+function detectPackageManager() {
+	const userAgent = process.env.npm_config_user_agent || '';
+	if (userAgent.startsWith('bun/')) return 'bun';
+	if (userAgent.startsWith('pnpm/')) return 'pnpm';
+	return 'npm';
+}
+
+function getTemplateSource(templateId, source) {
+	if (source) return normalizeGitSource(source);
+	const officialTemplate = findOfficialTemplate(templateId);
+	return `github:ecopages/ecopages/templates/${officialTemplate.source}#v${pkg.version}`;
+}
+
+function runChildCommand(command, args, cwd) {
+	return new Promise((resolve, reject) => {
+		const child = spawn(command, args, { cwd, stdio: 'inherit' });
+		child.on('error', reject);
+		child.on('exit', (code, signal) => {
+			if (signal) {
+				reject(new Error(`${command} was terminated by ${signal}.`));
+				return;
+			}
+
+			if (code !== 0) {
+				reject(new Error(`${command} exited with code ${code ?? 1}.`));
+				return;
+			}
+
+			resolve();
+		});
+	});
+}
+
+function rewriteWorkspaceDependencies(projectPkg) {
+	for (const blockName of ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies']) {
+		const block = projectPkg[blockName];
+		if (!block || typeof block !== 'object') continue;
+		for (const [name, version] of Object.entries(block)) {
+			if (version === 'workspace:*') block[name] = pkg.version;
+		}
+	}
+}
+
+function updateProjectManifest(targetDir, packageDirectory, isOfficial) {
+	const packagePath = join(targetDir, packageDirectory, 'package.json');
+	if (!existsSync(packagePath)) {
+		throw new Error(`Template package directory '${packageDirectory}' does not contain a package.json.`);
+	}
+
+	const projectPkg = JSON.parse(readFileSync(packagePath, 'utf-8'));
+	projectPkg.name = basename(targetDir);
+	if (isOfficial) rewriteWorkspaceDependencies(projectPkg);
+
+	if (isOfficial) {
+		for (const blockName of ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies']) {
+			const block = projectPkg[blockName];
+			if (!block || typeof block !== 'object') continue;
+			if (
+				Object.values(block).some((version) => typeof version === 'string' && version.startsWith('workspace:'))
+			) {
+				throw new Error(`Template package still contains workspace dependencies in ${packagePath}.`);
+			}
+		}
+	}
+
+	writeFileSync(packagePath, `${JSON.stringify(projectPkg, null, 2)}\n`);
+	return packagePath;
+}
+
+function isCancelled(value) {
+	if (prompts.isCancel(value)) {
+		prompts.cancel('Project creation cancelled.');
+		return true;
+	}
+	return false;
+}
+
+async function promptProjectDirectory() {
+	const answer = await prompts.text({
+		message: 'Project directory:',
+		placeholder: 'my-app',
+		validate: (value) => (value.trim().length === 0 ? 'Enter a project directory.' : undefined),
+	});
+	if (isCancelled(answer)) return null;
+	return answer.trim();
+}
+
+async function promptTemplateSelection() {
+	const answer = await prompts.select({
+		message: 'Select a template:',
+		options: [
+			...officialTemplates.map((template) => ({
+				label: template.displayName,
+				value: template.id,
+				hint: template.description,
+			})),
+			{
+				label: 'Community template',
+				value: '__community__',
+				hint: 'Use a Git repository or provider source.',
+			},
+		],
+	});
+	if (isCancelled(answer)) return null;
+	return answer;
+}
+
+async function promptCommunityTemplateSource() {
+	const sourceAnswer = await prompts.text({
+		message: 'Template source:',
+		placeholder: 'github:owner/repository#v1.0.0',
+		validate: (value) => (value.trim().length === 0 ? 'Enter a Git template source.' : undefined),
+	});
+	if (isCancelled(sourceAnswer)) return null;
+	return sourceAnswer.trim();
+}
+
+async function resolveInteractiveTemplateChoice(templateId, source) {
+	if (templateId || source) {
+		return { templateId, source };
+	}
+
+	const answer = await promptTemplateSelection();
+	if (answer === null) {
+		return null;
+	}
+	if (answer === '__community__') {
+		const communitySource = await promptCommunityTemplateSource();
+		if (communitySource === null) {
+			return null;
+		}
+		return { templateId, source: communitySource };
+	}
+	return { templateId: answer, source };
+}
+
+async function promptInstallChoice(packageManager, parsed) {
+	if (parsed.start) {
+		return true;
+	}
+	if (parsed.install !== undefined) {
+		return parsed.install;
+	}
+	if (!parsed.interactive) {
+		return undefined;
+	}
+
+	const answer = await prompts.confirm({
+		message: `Install dependencies with ${packageManager}?`,
+		initialValue: true,
+	});
+	if (isCancelled(answer)) return null;
+	return answer;
+}
+
+async function promptStartChoice(parsed, install) {
+	if (parsed.start !== undefined) {
+		return parsed.start;
+	}
+	if (!parsed.interactive || !install) {
+		return undefined;
+	}
+
+	const answer = await prompts.confirm({ message: 'Start the development server now?', initialValue: false });
+	if (isCancelled(answer)) return null;
+	return answer;
+}
+
+async function collectInitAnswers(parsed) {
+	const packageManager = detectPackageManager();
+	let dir = parsed.dir;
+	let templateId = parsed.template;
+	let source = parsed.from;
+
+	if (parsed.interactive && !dir) {
+		const promptedDir = await promptProjectDirectory();
+		if (promptedDir === null) return null;
+		dir = promptedDir;
+	}
+
+	if (parsed.interactive) {
+		const templateChoice = await resolveInteractiveTemplateChoice(templateId, source);
+		if (templateChoice === null) return null;
+		templateId = templateChoice.templateId;
+		source = templateChoice.source;
+	}
+
+	if (!templateId && !source) templateId = defaultOfficialTemplate.id;
+	if (parsed.interactive) {
+		prompts.log.step(`Resolved template source: ${getTemplateSource(templateId, source)}`);
+	}
+
+	const installAnswer = await promptInstallChoice(packageManager, parsed);
+	if (installAnswer === null) return null;
+	const install = installAnswer ?? false;
+
+	const startAnswer = await promptStartChoice(parsed, install);
+	if (startAnswer === null) return null;
+	const start = startAnswer ?? false;
+
+	return { dir, templateId, source, packageManager, install, start };
+}
+
+export async function runInitCommand(rawArgs, logger) {
+	const parsed = parseInitCommandArgs(rawArgs);
+	if (parsed.help) return;
+
+	printBrandBanner(pkg.version);
+	const answers = await collectInitAnswers(parsed);
+	if (!answers) return;
+
+	const { dir, templateId, source, packageManager, install, start } = answers;
+	if (existsSync(dir)) throw new Error(`Target directory already exists: ${dir}`);
+
+	const officialTemplate = source ? null : findOfficialTemplate(templateId);
+	const templateSource = getTemplateSource(templateId, source);
+	const packageDirectory = officialTemplate?.packageDirectory ?? '.';
+	let targetCreated = false;
+
+	try {
+		if (!parsed.interactive) prompts.log.step(`Resolved template source: ${templateSource}`);
+		prompts.log.step(`Downloading ${officialTemplate?.displayName ?? 'community template'}...`);
+		targetCreated = true;
+		await downloadTemplate(templateSource, { dir, force: true });
+		prompts.log.step('Preparing project manifest...');
+		updateProjectManifest(dir, packageDirectory, Boolean(officialTemplate));
+		prompts.log.step(`Project created in ${dir}.`);
+
+		const packageCwd = join(dir, packageDirectory);
+		if (install) {
+			prompts.log.step(`Installing dependencies with ${packageManager}...`);
+			await runChildCommand(packageManager, ['install'], packageCwd);
+		}
+		if (start) {
+			prompts.log.step('Starting the development server...');
+			await runChildCommand(packageManager, ['run', 'dev'], packageCwd);
+		}
+
+		const relativeCwd = packageDirectory === '.' ? dir : join(dir, packageDirectory);
+		logger.info(
+			`Project initialized. Run 'cd "${relativeCwd}" && ${packageManager} install && ${packageManager} run dev'.`,
+		);
+	} catch (error) {
+		if (targetCreated) rmSync(dir, { recursive: true, force: true });
+		throw error;
+	}
+}

package/bin/launch-plan.js

@@ -2,6 +2,12 @@ import { existsSync, readFileSync } from 'node:fs';
 import path from 'node:path';
 import { parseEnv } from 'node:util';
 import { SERVER_BUNDLE_DIR, SERVER_BUNDLE_FILENAME } from '@ecopages/core/utils/resolve-entry-file';
+import {
+	resolveEcoConfigPath,
+	resolveEmittedEcoConfigPath,
+	assertProductionConfigIdentity,
+} from '@ecopages/core/config';
+import { ECOPAGES_ENTRY_WATCH_ENV, getDevEnvFileNames } from '@ecopages/core/dev/development-restart';
 
 const SERVER_BUNDLE_MANIFEST_FILENAME = 'manifest.json';
 
@@ -9,13 +15,7 @@ const nodeRequirePreload = import.meta.resolve('./node-require-preload.js');
 const tsxLoader = import.meta.resolve('tsx/esm');
 
 function getEnvFilePaths(nodeEnv) {
-	const envFiles = ['.env', '.env.local'];
-
-	if (nodeEnv) {
-		envFiles.push(`.env.${nodeEnv}`, `.env.${nodeEnv}.local`);
-	}
-
-	return envFiles.filter((envFile) => existsSync(envFile));
+	return getDevEnvFileNames(nodeEnv).filter((envFile) => existsSync(envFile));
 }
 
 export function buildEnvOverrides(options) {
@@ -26,9 +26,26 @@ export function buildEnvOverrides(options) {
 	if (options.debug) env.ECOPAGES_LOGGER_DEBUG = 'true';
 	if (options.nodeEnv) env.NODE_ENV = options.nodeEnv;
 	if (options.entryFile) env.ECOPAGES_ENTRY_FILE = options.entryFile;
+	if (options.configFile) {
+		env.ECOPAGES_CONFIG_FILE = path.isAbsolute(options.configFile)
+			? options.configFile
+			: path.resolve(process.cwd(), options.configFile);
+	}
+	if (options.watch) {
+		env[ECOPAGES_ENTRY_WATCH_ENV] = '1';
+	}
 	return env;
 }
 
+export function resolveEcoConfigFilePath(options = {}, cwd = process.cwd(), resolverOptions = {}) {
+	return resolveEcoConfigPath({
+		configFile: options.configFile,
+		cwd,
+		required: false,
+		preferEmitted: resolverOptions.preferEmitted,
+	});
+}
+
 export function buildLaunchEnv(options) {
 	const envOverrides = buildEnvOverrides(options);
 	const envFileValues = getEnvFilePaths(options.nodeEnv).reduce((env, envFile) => {
@@ -59,7 +76,7 @@ export function detectRuntime(options = {}) {
 	return 'node';
 }
 
-export function buildBunArgs(args, options, entryFile, hasConfig) {
+export function buildBunArgs(args, options, entryFile, configFilePath) {
 	const bunArgs = [];
 
 	if (options.watch) bunArgs.push('--watch');
@@ -67,8 +84,8 @@ export function buildBunArgs(args, options, entryFile, hasConfig) {
 
 	bunArgs.push('run');
 
-	if (hasConfig) {
-		bunArgs.push('--preload', `./eco.config.${'ts'}`);
+	if (configFilePath) {
+		bunArgs.push('--preload', configFilePath);
 	}
 
 	bunArgs.push(entryFile, ...args);
@@ -157,6 +174,10 @@ export function createLaunchPlan(args, options, entryFile, launchMode) {
 	const { envOverrides, env } = buildLaunchEnv(resolvedOptions);
 	const runtime = detectRuntime(resolvedOptions);
 	const resolvedLaunchMode = inferLaunchMode(args, launchMode);
+	const isExplicitConfig = Boolean(resolvedOptions.configFile || process.env.ECOPAGES_CONFIG_FILE);
+	const resolvedConfigFile = resolveEcoConfigFilePath(resolvedOptions, process.cwd(), {
+		preferEmitted: usesProductionBundle(resolvedLaunchMode) && !isExplicitConfig,
+	});
 
 	const distServerApp = resolveProductionServerEntry(process.cwd());
 	const shouldUseBundle = usesProductionBundle(resolvedLaunchMode);
@@ -167,6 +188,12 @@ export function createLaunchPlan(args, options, entryFile, launchMode) {
 	}
 
 	if (useBundle) {
+		assertProductionConfigIdentity(process.cwd(), resolvedConfigFile, { isExplicitOverride: isExplicitConfig });
+		const runtimeConfigFile = resolveEmittedEcoConfigPath(process.cwd()) ?? resolvedConfigFile;
+		if (runtimeConfigFile) {
+			envOverrides.ECOPAGES_CONFIG_FILE = runtimeConfigFile;
+			env.ECOPAGES_CONFIG_FILE = runtimeConfigFile;
+		}
 		if (runtime === 'node') {
 			return {
 				runtime,
@@ -187,10 +214,16 @@ export function createLaunchPlan(args, options, entryFile, launchMode) {
 	}
 
 	if (runtime === 'node') {
+		const commandArgs = ['--import', nodeRequirePreload, '--import', tsxLoader];
+		if (resolvedOptions.watch) {
+			commandArgs.push('--watch');
+		}
+		commandArgs.push(resolvedEntryFile, ...args);
+
 		return {
 			runtime,
 			command: process.execPath,
-			commandArgs: ['--import', nodeRequirePreload, '--import', tsxLoader, resolvedEntryFile, ...args],
+			commandArgs,
 			envOverrides,
 			env,
 		};
@@ -199,7 +232,7 @@ export function createLaunchPlan(args, options, entryFile, launchMode) {
 	return {
 		runtime,
 		command: 'bun',
-		commandArgs: buildBunArgs(args, resolvedOptions, resolvedEntryFile, existsSync('eco.config.ts')),
+		commandArgs: buildBunArgs(args, resolvedOptions, resolvedEntryFile, resolvedConfigFile),
 		envOverrides,
 		env,
 	};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ecopages",
-  "version": "0.2.0-rc.0",
+  "version": "0.2.0-rc.10",
   "description": "CLI utilities for Ecopages",
   "type": "module",
   "engines": {
@@ -28,11 +28,15 @@
     "lit",
     "mdx"
   ],
+  "publishConfig": {
+    "access": "public"
+  },
   "bin": {
     "ecopages": "bin/cli.js"
   },
   "dependencies": {
-    "@ecopages/core": "0.2.0-rc.0",
+    "@clack/prompts": "^1.7.0",
+    "@ecopages/core": "0.2.0-rc.10",
     "@ecopages/logger": "^0.2.3",
     "giget": "^2.0.0",
     "tsx": "^4.22.3"
@@ -41,4 +45,4 @@
     "bun-types": "*",
     "typescript": "^5"
   }
-}
+}

package/templates.json

@@ -0,0 +1,95 @@
+{
+	"templates": [
+		{
+			"id": "jsx",
+			"displayName": "JSX",
+			"description": "A minimal Ecopages JSX application.",
+			"category": "integration",
+			"order": 10,
+			"default": true,
+			"source": "jsx",
+			"packageDirectory": ".",
+			"integrations": ["ecopages-jsx", "mdx"]
+		},
+		{
+			"id": "react",
+			"displayName": "React",
+			"description": "A minimal Ecopages React application.",
+			"category": "integration",
+			"order": 20,
+			"source": "react",
+			"packageDirectory": ".",
+			"integrations": ["react"]
+		},
+		{
+			"id": "lit-jsx",
+			"displayName": "Lit JSX",
+			"description": "A KitaJS and Lit Ecopages application.",
+			"category": "integration",
+			"order": 30,
+			"source": "lit-jsx",
+			"packageDirectory": ".",
+			"integrations": ["kitajs", "lit"]
+		},
+		{
+			"id": "radiant",
+			"displayName": "Radiant UI",
+			"description": "An Ecopages JSX application built with Radiant UI components.",
+			"category": "integration",
+			"order": 35,
+			"source": "radiant",
+			"packageDirectory": ".",
+			"integrations": ["ecopages-jsx", "radiant-ui"]
+		},
+		{
+			"id": "blog-jsx",
+			"displayName": "Blog JSX",
+			"description": "A content-driven blog rendered with Ecopages JSX.",
+			"category": "application",
+			"order": 40,
+			"source": "blog-jsx",
+			"packageDirectory": ".",
+			"integrations": ["ecopages-jsx", "mdx"]
+		},
+		{
+			"id": "blog-react",
+			"displayName": "Blog React",
+			"description": "A content-driven blog rendered with React.",
+			"category": "application",
+			"order": 50,
+			"source": "blog-react",
+			"packageDirectory": ".",
+			"integrations": ["react", "mdx"]
+		},
+		{
+			"id": "docs-starter",
+			"displayName": "Docs Starter",
+			"description": "A documentation site powered by the content processor.",
+			"category": "application",
+			"order": 60,
+			"source": "docs-starter",
+			"packageDirectory": ".",
+			"integrations": ["ecopages-jsx", "mdx"]
+		},
+		{
+			"id": "react-better-auth",
+			"displayName": "React Better Auth",
+			"description": "A React application with Better Auth and Drizzle.",
+			"category": "application",
+			"order": 70,
+			"source": "react-better-auth",
+			"packageDirectory": ".",
+			"integrations": ["react"]
+		},
+		{
+			"id": "llm-wiki",
+			"displayName": "LLM Wiki",
+			"description": "A persistent, LLM-maintained knowledge base and site.",
+			"category": "application",
+			"order": 80,
+			"source": "llm-wiki",
+			"packageDirectory": "app",
+			"integrations": ["ecopages-jsx", "mdx"]
+		}
+	]
+}