@rocket/js 0.1.1 → 0.2.0

package/src/SocialPreviewPlayground.js

@@ -3,6 +3,7 @@ import {
   DEFAULT_SOCIAL_PREVIEW_IMAGE_WIDTH,
   defaultSocialPreviewTemplate,
 } from './defaultSocialPreviewTemplate.js';
+import { debounce } from './debounce.js';
 
 const DEFAULT_TITLE = 'Runtime Guide';
 const DEFAULT_DESCRIPTION = 'Learn how Acme UI components load, render, and ship with Rocket.';
@@ -81,22 +82,23 @@ export class SocialPreviewPlayground extends HTMLElement {
     this.templateFrame = null;
     /** @type {HTMLAnchorElement | null} */
     this.pngLink = null;
+    // Typing reloads the preview iframe and rewrites history, so batch keystrokes.
+    this.schedulePreviewUpdate = debounce(() => this.updatePreviewResources(), 150);
   }
 
   connectedCallback() {
-    if (this.shadowRoot) {
-      return;
+    if (!this.shadowRoot) {
+      this.config = this.readConfig();
+      this.state = this.initialState(this.config);
+      this.attachShadow({ mode: 'open' });
+      this.render();
+      this.connectControls();
+      this.updatePreviewResources();
     }
-    this.config = this.readConfig();
-    this.state = this.initialState(this.config);
-    const shadowRoot = this.attachShadow({ mode: 'open' });
-    this.render();
-    this.connectControls();
-    this.updatePreviewResources();
     this.resizePreviewFrame();
-    const frame = shadowRoot.querySelector('[data-social-preview-frame-shell]');
+    const frame = this.shadowRoot?.querySelector('[data-social-preview-frame-shell]');
     if (frame && 'ResizeObserver' in window) {
-      this.resizeObserver = new ResizeObserver(() => this.resizePreviewFrame());
+      this.resizeObserver ??= new ResizeObserver(() => this.resizePreviewFrame());
       this.resizeObserver.observe(frame);
     }
   }
@@ -160,8 +162,8 @@ export class SocialPreviewPlayground extends HTMLElement {
     const page = config.pages.find(candidate => candidate.path === config.selectedPath);
     return {
       selectedPath: page?.path ?? config.selectedPath,
-      title: config.defaultTitle || page?.title || DEFAULT_TITLE,
-      description: config.defaultDescription || page?.description || DEFAULT_DESCRIPTION,
+      title: page?.title || config.defaultTitle,
+      description: page?.description || config.defaultDescription,
     };
   }
 
@@ -423,11 +425,11 @@ export class SocialPreviewPlayground extends HTMLElement {
     });
     titleInput?.addEventListener('input', () => {
       this.state.title = titleInput.value;
-      this.updatePreviewResources();
+      this.schedulePreviewUpdate();
     });
     descriptionInput?.addEventListener('input', () => {
       this.state.description = descriptionInput.value;
-      this.updatePreviewResources();
+      this.schedulePreviewUpdate();
     });
     shadowRoot
       .querySelector('button[data-social-preview-previous-page]')
@@ -506,7 +508,11 @@ export class SocialPreviewPlayground extends HTMLElement {
       return;
     }
     if (this.config.templateUrl) {
-      this.templateFrame.src = this.socialPreviewResourcePath(this.config.templateUrl);
+      const templateSrc = this.socialPreviewResourcePath(this.config.templateUrl);
+      // assigning an unchanged src still reloads the iframe, so compare first
+      if (this.templateFrame.getAttribute('src') !== templateSrc) {
+        this.templateFrame.src = templateSrc;
+      }
     } else {
       this.templateFrame.srcdoc = this.previewHtml();
     }
@@ -515,11 +521,11 @@ export class SocialPreviewPlayground extends HTMLElement {
       this.pngLink.download = this.selectedPage()?.downloadFilename ?? 'social-preview.png';
     }
     if (this.config.syncHistory && this.config.workflowUrl) {
-      window.history.replaceState(
-        null,
-        '',
-        this.socialPreviewResourcePath(this.config.workflowUrl),
-      );
+      const workflowPath = this.socialPreviewResourcePath(this.config.workflowUrl);
+      const currentPath = `${window.location.pathname}${window.location.search}`;
+      if (workflowPath !== currentPath) {
+        window.history.replaceState(null, '', workflowPath);
+      }
     }
   }
 

package/src/asyncMessage.js

@@ -3,6 +3,11 @@
 
 /**
  * Turns a MessagePort into an AsyncPort, which can wait for responses.
+ *
+ * Do not use sendAndWait from inside module customization hooks: the main
+ * thread may be blocked in Atomics.wait (e.g. during a nested
+ * module.register() call) and unable to reply, which deadlocks the hook.
+ *
  * @param {MessagePort} port
  * @returns {AsyncPort}
  */
@@ -13,9 +18,10 @@ export function makeAsyncPort(port) {
     p._wait.resolve(message);
     p._wait = Promise.withResolvers();
   });
-  p.sendAndWait = async message => {
+  p.sendAndWait = message => {
+    const wait = p._wait;
     p.postMessage(message);
-    return p._wait;
+    return wait.promise;
   };
   return p;
 }

package/src/cli/RocketBuild.js

@@ -6,8 +6,10 @@ import { build } from 'vite';
 import path from 'node:path';
 import { PageRuntime } from '../page-runtime.js';
 import { createIconAssetStore, rocketIconRuntimeOutputs } from '../icons.js';
-import { paginatedArchivePaths } from '../page-pagination.js';
-import { createStaticPageModuleLoader } from '../static-page-module-loader.js';
+import { hasPagePagination, paginatedArchivePaths } from '../page-pagination.js';
+import { hasPageFeed, pageFeedPath } from '../feeds.js';
+import { hasStaticParams, staticParamsPagePaths } from '../static-params.js';
+import { createPageModuleLoader } from '../page-module-loader.js';
 import { writeSiteDiscoverabilityOutputs } from '../siteDiscoverability.js';
 import { normalizeDocumentPath, standaloneDemoPaths } from '../standalone-demo-url.js';
 import {
@@ -46,6 +48,7 @@ export class RocketBuild {
 
     program
       .command('build')
+      .description('build the static site into the output directory')
       .option('-o, --output-dir <path>', 'Path where to output built files')
       .action(async ({ outputDir }) => {
         if (outputDir) {
@@ -96,6 +99,8 @@ export class RocketBuild {
       emitRedirectFallbacks: !this.cli.config.adapter,
     });
     const outDir = this.outputDir ? path.resolve(this.outputDir) : path.resolve('dist');
+    // Vite's emptyOutDir force-clears any outDir, so containment must hold on every path.
+    assertOutputDirInsideProject(outDir);
     assertPublicAssetsOutputDir({ projectRoot: process.cwd(), outDir });
 
     try {
@@ -217,7 +222,7 @@ export function splitPages(pages) {
 export async function renderStaticPages({
   pages,
   staticPages,
-  pageModuleLoader = createStaticPageModuleLoader(),
+  pageModuleLoader = createPageModuleLoader(),
   origin = 'http://localhost',
   urlLifecycle,
   siteHeadMetadata,
@@ -232,6 +237,8 @@ export async function renderStaticPages({
   assertStaticJavaScriptPagesHaveConcretePaths(staticPages);
   assertNoStandaloneDemoPathCollisions(pages, staticPages);
   assertNoPaginatedArchivePathCollisions(pages, staticPages);
+  assertPageFeedsAreBuildable({ pages, staticPages, siteOrigin });
+  assertNoStaticParamsPathCollisions(pages, staticPages);
   validateUrlLifecycleGeneratedOutputCollisions({
     redirects: urlLifecycle?.redirects,
     pages,
@@ -265,6 +272,13 @@ export async function renderStaticPages({
   });
   for (const [pagePath, page] of staticPages) {
     try {
+      if (hasStaticParams(page)) {
+        for (const paramPath of staticParamsPagePaths({ pages, page, pagePath })) {
+          const paramResponse = await pageRuntime.render(new Request(new URL(paramPath, origin)));
+          await writeStaticResponse(paramPath, paramResponse);
+        }
+        continue;
+      }
       const response = await pageRuntime.render(new Request(new URL(pagePath, origin)));
       await writeStaticResponse(pagePath, response);
       for (const archivePath of paginatedArchivePaths({ pages, page, pagePath })) {
@@ -275,6 +289,11 @@ export async function renderStaticPages({
         const demoResponse = await pageRuntime.render(new Request(new URL(demoPath, origin)));
         await writeStandaloneDemoResponse(demoPath, page, demoResponse);
       }
+      if (hasPageFeed(page)) {
+        const feedPath = pageFeedPath(pagePath);
+        const feedResponse = await pageRuntime.render(new Request(new URL(feedPath, origin)));
+        await writeStaticResponse(feedPath, feedResponse);
+      }
     } catch (error) {
       throw new Error(`Failed to render page: ${pagePath}. ${errorMessage(error)}`, {
         cause: error,
@@ -293,18 +312,55 @@ export async function renderStaticPages({
  */
 function assertStaticJavaScriptPagesHaveConcretePaths(staticPages) {
   for (const [pagePath, page] of staticPages) {
-    if (!page.file.endsWith('.js') || !hasPathParameter(pagePath)) {
+    if (!page.file.endsWith('.js') || !hasPathParameter(pagePath) || hasStaticParams(page)) {
       continue;
     }
     throw new Error(
       `Static JavaScript Page ${pagePath} (${page.file}) cannot be rendered as one static ` +
-        `output document because its path is parameterized. Parameterized JavaScript Pages need ` +
-        `request-time rendering until Rocket has an API for enumerating static params. Use ` +
-        `render: 'server' for this Page today.`,
+        `output document because its path is parameterized. Export static params to enumerate ` +
+        `its output documents, or use render: 'server' for request-time rendering.`,
     );
   }
 }
 
+/**
+ * @param {import('@rocket/js/types.js').PageRegistry} pages
+ * @param {import('@rocket/js/types.js').PageRegistry} staticPages
+ */
+function assertNoStaticParamsPathCollisions(pages, staticPages) {
+  const configuredPages = configuredPageOutputPaths(pages);
+  const staticParamsPages = new Map();
+  for (const [pagePath, page] of staticPages) {
+    if (!hasStaticParams(page)) {
+      continue;
+    }
+    if (hasPagePagination(page)) {
+      throw new Error(
+        `Static JavaScript Page ${pagePath} (${page.file}) cannot combine static params with ` +
+          `pagination. Paginate a concrete archive Page instead.`,
+      );
+    }
+    for (const paramPath of staticParamsPagePaths({ pages, page, pagePath })) {
+      const outputPath = normalizeDocumentPath(paramPath);
+      const collision = configuredPages.get(outputPath);
+      if (collision) {
+        throw new Error(
+          `Static params output path ${paramPath} for page ${page.file} collides with ` +
+            `configured Page ${collision.page.file} at ${collision.path}`,
+        );
+      }
+      const paramCollision = staticParamsPages.get(outputPath);
+      if (paramCollision) {
+        throw new Error(
+          `Static params output path ${paramPath} for page ${page.file} collides with ` +
+            `static params output path ${paramCollision.path} for page ${paramCollision.page.file}`,
+        );
+      }
+      staticParamsPages.set(outputPath, { path: paramPath, page });
+    }
+  }
+}
+
 /**
  * @param {string} pagePath
  */
@@ -312,6 +368,40 @@ function hasPathParameter(pagePath) {
   return /(^|\/):[^/]+/.test(pagePath);
 }
 
+/**
+ * @param {{
+ *   pages: import('@rocket/js/types.js').PageRegistry;
+ *   staticPages: import('@rocket/js/types.js').PageRegistry;
+ *   siteOrigin?: string;
+ * }} options
+ */
+function assertPageFeedsAreBuildable({ pages, staticPages, siteOrigin }) {
+  for (const [pagePath, page] of staticPages) {
+    if (!hasPageFeed(page)) {
+      continue;
+    }
+    if (hasPathParameter(pagePath)) {
+      throw new Error(
+        `Page Feed for ${page.file} cannot use the parameterized path ${pagePath}. ` +
+          `Page Feeds need a concrete owning Page path.`,
+      );
+    }
+    if (typeof siteOrigin !== 'string' || siteOrigin.trim() === '') {
+      throw new Error(
+        `Page Feed ${pageFeedPath(pagePath)} for ${page.file} requires a Site Origin for ` +
+          `absolute feed URLs. Add siteOrigin: 'https://example.com' to rocket-config.js.`,
+      );
+    }
+    const collision = pages.get(pageFeedPath(pagePath));
+    if (collision) {
+      throw new Error(
+        `Page Feed ${pageFeedPath(pagePath)} for ${page.file} collides with configured ` +
+          `Page ${collision.file}`,
+      );
+    }
+  }
+}
+
 /**
  * @param {import('@rocket/js/types.js').PageRegistry} pages
  * @param {import('@rocket/js/types.js').PageRegistry} staticPages
@@ -429,23 +519,30 @@ function writeIconAssetOutputs(iconAssetStore) {
 /**
  * @param {string} outDir
  */
-function clearExistingOutputDir(outDir) {
-  if (!existsSync(outDir)) {
-    return;
-  }
+function assertOutputDirInsideProject(outDir) {
   const projectRoot = path.resolve(process.cwd());
   const relativeOutDir = path.relative(projectRoot, outDir);
   if (
     relativeOutDir === '' ||
-    relativeOutDir.startsWith(`..${path.sep}`) ||
     relativeOutDir === '..' ||
+    relativeOutDir.startsWith(`..${path.sep}`) ||
     path.isAbsolute(relativeOutDir)
   ) {
     throw new Error(
       `Invalid build output directory ${outDir}. ` +
-        `Rocket can only clear an existing output directory inside the project root.`,
+        `Rocket only writes build output inside the project root.`,
     );
   }
+}
+
+/**
+ * @param {string} outDir
+ */
+function clearExistingOutputDir(outDir) {
+  if (!existsSync(outDir)) {
+    return;
+  }
+  assertOutputDirInsideProject(outDir);
   rmSync(outDir, { recursive: true });
 }
 

package/src/cli/RocketCli.js

@@ -1,9 +1,14 @@
+import { readFileSync } from 'node:fs';
 import { Command } from 'commander';
 import { readConfig } from '../config.js';
 import { RocketBuild } from './RocketBuild.js';
 import { RocketInit } from './RocketInit.js';
 import { RocketStart } from './RocketStart.js';
 
+const packageJson = JSON.parse(
+  readFileSync(new URL('../../package.json', import.meta.url), 'utf8'),
+);
+
 export class RocketCli {
   /** @type {string[]} */
   argv;
@@ -21,7 +26,12 @@ export class RocketCli {
     this.argv = argv;
 
     this.program = new Command();
-    this.program.allowUnknownOption(true).option('-c, --config-file <path>', 'path to config file');
+    this.program
+      .name('rocket')
+      .description('HTML-first static-site metaframework for content sites and Web Component docs')
+      .version(packageJson.version)
+      .allowUnknownOption(true)
+      .option('-c, --config-file <path>', 'path to config file');
     this.program.parseOptions(this.argv);
 
     this.program.allowUnknownOption(false);

package/src/cli/RocketInit.js

@@ -5,6 +5,7 @@ import path from 'node:path';
 const ROCKET_CONFIG_PATH = 'rocket-config.js';
 const INDEX_PAGE_PATH = 'docs/pages/index.rocket.md';
 const SHARED_DATA_PATH = 'docs/pages/sharedData.js';
+const THEME_CSS_PATH = 'public/rocket-theme.css';
 const DOCS_PAGE_PATH = 'docs/pages/docs.rocket.md';
 const JAVASCRIPT_DEMO_PAGE_PATH = 'docs/pages/javascript-demo.rocket.md';
 const REQUEST_DEMO_PAGE_PATH = 'docs/pages/request-demo.rocket.md';
@@ -13,6 +14,7 @@ const ROCKET_AGENT_SKILL_PATH = '.agents/skills/rocket/SKILL.md';
 const EXISTING_ROCKET_PAGE_NOISE_THRESHOLD = 3;
 const STARTER_PAGE_FILES = [
   SHARED_DATA_PATH,
+  THEME_CSS_PATH,
   INDEX_PAGE_PATH,
   DOCS_PAGE_PATH,
   JAVASCRIPT_DEMO_PAGE_PATH,
@@ -28,6 +30,8 @@ export default {
 
 const sharedDataSource = `import { resolve } from '@rocket/js/resolve.js';
 
+const themeStylesheets = ['/rocket-theme.css'];
+
 export const headerData = {
   logo: [
     resolve('@rocket/js/docs/assets/rocket-logo-light.svg', import.meta),
@@ -47,6 +51,7 @@ export const footerData = [];
 export const heroData = {
   headerData,
   footerData,
+  stylesheets: themeStylesheets,
   heroMainData: {
     logoNoText: resolve('@rocket/js/docs/assets/rocket-logo-light.svg', import.meta),
     eyebrow: 'ROCKET STARTER',
@@ -102,10 +107,29 @@ export const heroData = {
 export const docData = {
   headerData,
   footerData,
+  stylesheets: themeStylesheets,
   navigationIconServerBudget: 35,
 };
 `;
 
+const themeCssSource = `:root {
+  --rocket-theme-primary: #e10d14;
+  --rocket-theme-primary-dark: #b90f12;
+  --rocket-theme-link: #0366d6;
+}
+
+.atlas-page,
+.atlas-header,
+.atlas-navigation,
+.atlas-toc,
+.home-main,
+rocket-header {
+  --primary-color: var(--rocket-theme-primary);
+  --primary-color-dark: var(--rocket-theme-primary-dark);
+  --link-color: var(--rocket-theme-link);
+}
+`;
+
 const indexPageSource = `\`\`\`js server
 export const config = {
   path: '/',
@@ -265,6 +289,7 @@ export default function siteStatusPage() {
 
 const STARTER_PAGE_SOURCES = new Map([
   [SHARED_DATA_PATH, sharedDataSource],
+  [THEME_CSS_PATH, themeCssSource],
   [INDEX_PAGE_PATH, indexPageSource],
   [DOCS_PAGE_PATH, docsPageSource],
   [JAVASCRIPT_DEMO_PAGE_PATH, javascriptDemoPageSource],
@@ -289,10 +314,15 @@ description: Use when editing Rocket Pages, config, layouts, component reference
 - Markdown using Rocket custom elements needs a \`components\` export; use Atlas component maps or \`rocketDemoComponents\`.
 - Add \`menu.iconName\` to Atlas docs navigation Pages so the left navigation has icons.
 - Direct layout re-exports are supported when no local wrapper function is needed.
+- For Atlas theming, use shared layout data with \`stylesheets\` and centralized CSS variables instead of per-Page style injection.
+- To add a general Page, create \`docs/pages/name.rocket.md\`, set \`config.path\`, \`metadata\`, \`menu.iconName\`, and use the shared docs layout.
 - Custom layouts rendering \`rocket-icon\` need \`addBootstrapIconLibrary(pageData)\` before \`document()\`.
 - Static JavaScript Pages render once per concrete path; query/header/cookie/live-data output needs \`render: 'server'\`.
 - Static Request Demos should target concrete non-query URLs.
 - After adding a \`js demo\`, verify the parent Page and Standalone Demo URL \`/page/_demo/demoName/\`.
+- If \`rocket init\` fails because package.json has \`"type": "commonjs"\`, change it to \`"type": "module"\` or rerun \`npx rocket init --yes\`.
+- If dev server watchers fail with \`EMFILE\`, run \`npm start -- --no-watch --no-open\` and use \`Ctrl+R\` for manual restarts.
+- When smoke-testing Pages with curl, send \`Accept: text/html\`: \`curl -H 'Accept: text/html' http://localhost:8888/path\`.
 - Keep \`npm run build\` passing; record Rocket package issues separately from local workarounds.
 `;
 
@@ -304,17 +334,19 @@ export class RocketInit {
     program
       .command('init')
       .description('create a Rocket docs starter')
-      .action(() => {
-        const result = this.init();
+      .option('-y, --yes', 'update an explicit CommonJS package.json type to module')
+      .action(options => {
+        const result = this.init({ yes: options.yes });
         reportInitResult(result);
       });
   }
 
   /**
+   * @param {RocketInitOptions} [options]
    * @returns {RocketInitResult}
    */
-  init() {
-    const packageJsonUpdate = preparePackageJsonUpdate('package.json');
+  init(options = {}) {
+    const packageJsonUpdate = preparePackageJsonUpdate('package.json', options);
     /** @type {RocketInitResult} */
     const result = {
       created: [],
@@ -343,6 +375,12 @@ export class RocketInit {
   }
 }
 
+/**
+ * @typedef {{
+ *   yes?: boolean;
+ * }} RocketInitOptions
+ */
+
 /**
  * @typedef {{
  *   created: string[];
@@ -359,6 +397,7 @@ export class RocketInit {
 
 /**
  * @param {string} filePath
+ * @param {RocketInitOptions} options
  * @returns {{
  *   changed: boolean;
  *   packageJson: Record<string, any>;
@@ -367,7 +406,7 @@ export class RocketInit {
  *   nextSteps: string[];
  * } | undefined}
  */
-function preparePackageJsonUpdate(filePath) {
+function preparePackageJsonUpdate(filePath, options) {
   if (!existsSync(filePath)) {
     return undefined;
   }
@@ -379,19 +418,19 @@ function preparePackageJsonUpdate(filePath) {
   if (!isPlainRecord(packageJson)) {
     throw new Error('package.json must contain a JSON object');
   }
-  if (packageJson.type === 'commonjs') {
-    throw new Error(
-      `Rocket init expects an ESM project. Found package.json type "commonjs". ` +
-        `Change package.json to "type": "module" before running rocket init.`,
-    );
-  }
 
   /** @type {string[]} */
   const updated = [];
   /** @type {string[]} */
   const skipped = [];
 
-  if (!hasOwn(packageJson, 'type')) {
+  if (packageJson.type === 'commonjs') {
+    if (!options.yes) {
+      throw commonJsProjectError();
+    }
+    packageJson.type = 'module';
+    updated.push('type');
+  } else if (!hasOwn(packageJson, 'type')) {
     packageJson.type = 'module';
     updated.push('type');
   } else if (packageJson.type === 'module') {
@@ -434,6 +473,19 @@ function preparePackageJsonUpdate(filePath) {
   };
 }
 
+function commonJsProjectError() {
+  return new Error(
+    `Rocket init expects an ESM project. Found package.json type "commonjs".\n\n` +
+      `Update package.json before running rocket init:\n` +
+      `-  "type": "commonjs",\n` +
+      `+  "type": "module",\n\n` +
+      `Then rerun:\n` +
+      `  npx rocket init\n\n` +
+      `Or let Rocket apply that package.json change:\n` +
+      `  npx rocket init --yes`,
+  );
+}
+
 /**
  * @param {Record<string, any>} scripts
  * @param {{

package/src/cli/RocketStart.js

@@ -8,6 +8,9 @@ export class RocketStart {
   /** @type {RocketStartOptions} */
   startOptions = {};
 
+  /** @type {import('child_process').ChildProcess | undefined} */
+  server = undefined;
+
   /**
    * @param {import('commander').Command} program
    * @param {import('./RocketCli.js').RocketCli} cli
@@ -17,6 +20,7 @@ export class RocketStart {
 
     program
       .command('start')
+      .description('start the development server')
       .option('-p, --port <port>', 'port for the development server')
       .option('--no-open', 'do not open the browser')
       .option('--no-watch', 'disable automatic file watching and reloads')
@@ -32,7 +36,7 @@ export class RocketStart {
    */
   spawnServer(options = {}) {
     process.stdin.setRawMode?.(true);
-    return spawn(
+    const server = spawn(
       'node',
       startServerArgs({
         configFilePath: this.cli?.configFilePath,
@@ -43,13 +47,47 @@ export class RocketStart {
         cwd: process.cwd(),
       },
     );
+    server.on('exit', (code, signal) => {
+      // ignore exits of already-replaced servers during a restart
+      if (this.server !== server) {
+        return;
+      }
+      this.server = undefined;
+      if (this.startOptions.watch !== false) {
+        console.log(
+          `Rocket dev server stopped (${signal ?? `code ${code}`}). ` +
+            'Waiting for changes - press Ctrl+R to restart or Ctrl+C to quit.',
+        );
+      } else {
+        this.shutdown(typeof code === 'number' ? code : 1);
+      }
+    });
+    return server;
   }
 
   restartServer() {
-    this.server?.kill();
-    this.server = this.spawnServer(this.startOptions);
+    const oldServer = this.server;
+    this.server = undefined;
     console.clear();
     console.log('Restarting rocket server...');
+    if (oldServer && oldServer.exitCode === null && oldServer.signalCode === null) {
+      // wait for the old process to release its port before respawning
+      oldServer.once('exit', () => {
+        this.server = this.spawnServer(this.startOptions);
+      });
+      oldServer.kill();
+    } else {
+      this.server = this.spawnServer(this.startOptions);
+    }
+  }
+
+  /**
+   * @param {number} code
+   */
+  shutdown(code) {
+    process.stdin.setRawMode?.(false);
+    this.server?.kill();
+    process.exit(code);
   }
 
   /**
@@ -71,25 +109,31 @@ export class RocketStart {
         }, 100),
       );
 
-      // watch src
-      watch(
-        import.meta.dirname,
-        { recursive: true },
-        debounce(async (_, filename) => {
-          if (!filename) {
-            return;
-          }
-          this.restartServer();
-        }, 100),
-      );
+      // watch the framework source when running from a Rocket checkout
+      const frameworkSrcDir = path.join(import.meta.dirname, '..');
+      if (!frameworkSrcDir.includes('node_modules') && frameworkSrcDir.startsWith(process.cwd())) {
+        watch(
+          frameworkSrcDir,
+          { recursive: true },
+          debounce(async (_, filename) => {
+            if (!filename) {
+              return;
+            }
+            this.restartServer();
+          }, 100),
+        );
+      }
+    }
+
+    for (const signal of ['SIGINT', 'SIGTERM']) {
+      process.on(signal, () => this.shutdown(0));
     }
 
     process.stdin.on('data', data => {
       const char = data.toString();
       if (char === '\u0003' || char === '\u0004') {
         // Ctrl+C or Ctrl+D
-        this.server?.kill();
-        process.exit(0);
+        this.shutdown(0);
       } else if (char === '\u0012') {
         // Ctrl+R
         this.restartServer();

package/src/cli/cli.js

@@ -1,7 +1,16 @@
 #!/usr/bin/env node
+/* eslint-disable no-console */
 
 import { RocketCli } from './RocketCli.js';
 
 const cli = new RocketCli();
 
-await cli.start();
+try {
+  await cli.start();
+} catch (error) {
+  console.error(error instanceof Error ? error.message : error);
+  if (process.env.ROCKET_DEBUG) {
+    console.error(error);
+  }
+  process.exit(1);
+}