ecopages 0.3.0 → 0.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +16 -13
  2. package/bin/cli.js +36 -14
  3. package/package.json +3 -3
package/README.md CHANGED
@@ -2,41 +2,44 @@
2
2
 
3
3
  The official CLI for the Ecopages framework.
4
4
 
5
- It provides scaffolding and development commands to streamline your workflow. It runs your app on Bun when you launch it through Bun, on Node otherwise, and applies runtime-specific launch behavior for each engine.
5
+ It provides scaffolding and development commands to streamline your workflow. It runs your app on Node by default and on Bun when you launch it through Bun or pass `--runtime bun`, and applies runtime-specific launch behavior for each engine.
6
6
 
7
7
  ## Quick Start
8
8
 
9
9
  Initialize a new project from the interactive template picker:
10
10
 
11
11
  ```bash
12
- bunx ecopages init
12
+ npx ecopages init
13
+ # or: pnpm dlx ecopages init
13
14
  ```
14
15
 
15
16
  For a deterministic invocation, select a template explicitly:
16
17
 
17
18
  ```bash
18
- bunx ecopages init my-app --template react
19
+ npx ecopages init my-app --template react
19
20
  cd my-app
20
- bun install
21
- bun dev
21
+ pnpm install
22
+ pnpm dev
22
23
  ```
23
24
 
25
+ The commands above run on Node. Bun is optional: launch them through Bun (`bunx ecopages init`, `bun dev`) or pass `--runtime bun` to run the app on Bun.
26
+
24
27
  ## Commands
25
28
 
26
- | Command | Description | Equivalent (Bun) |
29
+ | Command | Description | What it runs |
27
30
  | :-------------------- | :------------------------------------------------------ | :------------------------------------------------------------------- |
28
31
  | `ecopages init [dir]` | Scaffolds a new project (interactive without `dir`) | N/A |
29
- | `ecopages dev` | Starts the dev server (supervises config/.env restarts) | `bun run [entry] --dev` |
30
- | `ecopages dev:watch` | Dev server + hard restarts on file changes | Bun: `bun --watch run [entry] --dev`; Node: `node --watch …` |
31
- | `ecopages build` | Creates a production build | `bun run [entry] --build` |
32
+ | `ecopages dev` | Starts the dev server (supervises config/.env restarts) | `[entry] --dev` through tsx on Node, `bun run [entry] --dev` on Bun |
33
+ | `ecopages dev:watch` | Dev server + hard restarts on file changes | Node: `node --watch …`; Bun: `bun --watch run [entry] --dev` |
34
+ | `ecopages build` | Creates a production build | `[entry] --build` through tsx on Node, `bun run [entry] --build` |
32
35
  | `ecopages start` | Starts the production server from the built output | Runs the emitted server bundle |
33
- | `ecopages preview` | Previews the production build locally | `bun run [entry] --preview` |
36
+ | `ecopages preview` | Previews the production build locally | `[entry] --preview` through tsx on Node, `bun run [entry] --preview` |
34
37
  | `ecopages types` | Writes virtual-module types for `tsc`, then exits | Loads `eco.config.ts` and sets processors up; the entry does not run |
35
38
 
36
39
  > [!NOTE]
37
40
  > The entry file defaults to `app.ts`. Override it with `--entry-file`.
38
41
 
39
- `ecopages start` does not load `eco.config.ts`, so it finds the build output by looking for `.server/manifest.json` one level below the app root (dot-prefixed directories included). It uses the only match, fails with the matches listed when there are several, and fails with "run `ecopages build`" when there is none. Pass `--dist-dir <dir>` to select a directory, which is required for nested (`out/web`) and symlinked outputs and whenever the app builds several outputs, such as `dist-<scope>` per build target.
42
+ `ecopages start` does not load `eco.config.ts`, so it finds the build output by looking for `.server/manifest.json` one level below the app root (dot-prefixed directories included). It uses the only match, fails with the matches listed when there are several, and fails with "run `ecopages build`" when there is none. Only apps that register API or WebSocket handlers build a server bundle. For a static-only app, `start` instead reports that the build has no server bundle when `dist` (or the `--dist-dir` directory) holds built HTML; serve that output with `ecopages preview` or deploy `dist/` to a static host. Pass `--dist-dir <dir>` to select a directory, which is required for nested (`out/web`) and symlinked outputs and whenever the app builds several outputs, such as `dist-<scope>` per build target.
40
43
 
41
44
  ### Templates
42
45
 
@@ -97,7 +100,7 @@ ecopages dev --port 8080 --debug
97
100
 
98
101
  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. If the restarted dev server exits with an error, for example because of an invalid config, `ecopages dev` logs the exit code and waits for the next change in the project or a linked workspace package, then starts again. 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`.
99
102
 
100
- `SIGTERM` and `SIGINT` sent to `ecopages` are forwarded to the server it started, and `ecopages` exits once that server has.
103
+ `SIGTERM` and `SIGINT` sent to `ecopages` are forwarded to the server it started, and `ecopages` exits once that server has. `ecopages` exits with the server's exit code, or with 128 plus the signal number when a signal ended the server, for example 137 when the build is killed (SIGKILL).
101
104
 
102
105
  ### Debug logging and startup trace
103
106
 
@@ -139,8 +142,8 @@ Ecopages relies on a modular architecture. Core logic and framework integrations
139
142
  | Package | Description |
140
143
  | :---------------------------- | :------------------------------------------- |
141
144
  | `@ecopages/browser-router` | Client-side navigation & view transitions. |
142
- | `@ecopages/codemod` | AST migrations for codebase upgrades. |
143
145
  | `@ecopages/core` | The foundational SSG engine. |
146
+ | `@ecopages/dev-toolbar` | Development-only browser toolbar. |
144
147
  | `@ecopages/ecopages-jsx` | Ecopages-owned JSX routes and hydration. |
145
148
  | `@ecopages/file-system` | Runtime-agnostic file system utilities. |
146
149
  | `@ecopages/image-processor` | Asset pipeline for responsive images. |
package/bin/cli.js CHANGED
@@ -2,6 +2,7 @@
2
2
 
3
3
  import { existsSync, readFileSync } from 'node:fs';
4
4
  import { spawn } from 'node:child_process';
5
+ import os from 'node:os';
5
6
  import path from 'node:path';
6
7
  import { fileURLToPath } from 'node:url';
7
8
  import { parseArgs } from 'node:util';
@@ -75,20 +76,26 @@ function getMainHelpText() {
75
76
  ].join('\n');
76
77
  }
77
78
 
78
- function getServerCommandHelpText(commandName, description, extraOptionLines = []) {
79
+ const SHARED_SERVER_OPTION_HELP = {
80
+ port: ' -p, --port <port> Override ECOPAGES_PORT',
81
+ hostname: ' -n, --hostname <hostname> Override ECOPAGES_HOSTNAME',
82
+ 'base-url': ' -b, --base-url <baseUrl> Override ECOPAGES_BASE_URL',
83
+ debug: ' -d, --debug Enable debug logging',
84
+ runtime: ' --runtime <runtime> Force bun or node',
85
+ 'entry-file': ' -e, --entry-file <file> Entry file (default: app.ts)',
86
+ config: ' -c, --config <file> Ecopages config file (default: eco.config.ts)',
87
+ };
88
+
89
+ function getServerCommandHelpText(commandName, description, extraOptionLines = [], ignoredOptions = []) {
79
90
  return [
80
91
  `Usage: ecopages ${commandName} [options]`,
81
92
  '',
82
93
  description,
83
94
  '',
84
95
  'Options:',
85
- ' -p, --port <port> Override ECOPAGES_PORT',
86
- ' -n, --hostname <hostname> Override ECOPAGES_HOSTNAME',
87
- ' -b, --base-url <baseUrl> Override ECOPAGES_BASE_URL',
88
- ' -d, --debug Enable debug logging',
89
- ' --runtime <runtime> Force bun or node',
90
- ' -e, --entry-file <file> Entry file (default: app.ts)',
91
- ' -c, --config <file> Ecopages config file (default: eco.config.ts)',
96
+ ...Object.entries(SHARED_SERVER_OPTION_HELP)
97
+ .filter(([option]) => !ignoredOptions.includes(option))
98
+ .map(([, line]) => line),
92
99
  ...extraOptionLines,
93
100
  ' -h, --help Show help',
94
101
  ].join('\n');
@@ -115,10 +122,12 @@ function parseServerCommandArgs(rawArgs, definition) {
115
122
 
116
123
  if (values.help) {
117
124
  console.log(
118
- getServerCommandHelpText(commandName, definition.description, [
119
- ...Object.values(valueOptions),
120
- ...(definition.optionHelpLines ?? []),
121
- ]),
125
+ getServerCommandHelpText(
126
+ commandName,
127
+ definition.description,
128
+ [...Object.values(valueOptions), ...(definition.optionHelpLines ?? [])],
129
+ definition.ignoredOptions,
130
+ ),
122
131
  );
123
132
  return { help: true };
124
133
  }
@@ -155,6 +164,18 @@ function parseServerCommandArgs(rawArgs, definition) {
155
164
  */
156
165
  const FORWARDED_SIGNALS = ['SIGTERM', 'SIGINT'];
157
166
 
167
+ /**
168
+ * Exit code for a child that a signal terminated.
169
+ *
170
+ * @remarks
171
+ * Node reports such a child with a null exit code, which `process.exit(code || 0)` turned into success, so a
172
+ * build killed by the OOM killer (SIGKILL) looked like it had passed. Shells report the same case as 128 plus
173
+ * the signal number, and so does this.
174
+ */
175
+ function getSignalExitCode(signal) {
176
+ return 128 + (os.constants.signals[signal] ?? 0);
177
+ }
178
+
158
179
  function runLaunchPlan(launchPlan, options = {}) {
159
180
  if (Object.keys(launchPlan.envOverrides).length > 0) {
160
181
  logger.debug(`Environment overrides: ${JSON.stringify(launchPlan.envOverrides)}`);
@@ -189,7 +210,7 @@ function runLaunchPlan(launchPlan, options = {}) {
189
210
  process.exit(1);
190
211
  });
191
212
 
192
- child.on('exit', (code) => {
213
+ child.on('exit', (code, signal) => {
193
214
  for (const signal of FORWARDED_SIGNALS) {
194
215
  process.off(signal, forwardSignal);
195
216
  }
@@ -205,7 +226,7 @@ function runLaunchPlan(launchPlan, options = {}) {
205
226
  return;
206
227
  }
207
228
 
208
- process.exit(code || 0);
229
+ process.exit(signal ? getSignalExitCode(signal) : code || 0);
209
230
  });
210
231
  }
211
232
 
@@ -366,6 +387,7 @@ const SERVER_COMMANDS = {
366
387
  'Load eco.config.ts so processors write the types for virtual modules such as ecopages:images, then exit. The app entry does not run. Run it before tsc.',
367
388
  entryArgs: [],
368
389
  resolveEntry: () => fileURLToPath(import.meta.resolve('@ecopages/core/config/write-types')),
390
+ ignoredOptions: ['port', 'hostname', 'base-url', 'entry-file'],
369
391
  optionOverrides: { nodeEnv: 'production' },
370
392
  },
371
393
  preview: {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "ecopages",
3
- "version": "0.3.0",
3
+ "version": "0.3.1",
4
4
  "description": "CLI utilities for Ecopages",
5
5
  "type": "module",
6
6
  "engines": {
@@ -36,8 +36,8 @@
36
36
  },
37
37
  "dependencies": {
38
38
  "@clack/prompts": "^1.7.0",
39
- "@ecopages/core": "0.3.0",
40
- "@ecopages/file-system": "0.3.0",
39
+ "@ecopages/core": "0.3.1",
40
+ "@ecopages/file-system": "0.3.1",
41
41
  "@ecopages/logger": "^0.2.3",
42
42
  "giget": "^2.0.0",
43
43
  "tsx": "^4.22.3"