@rocket/js 0.1.0 → 0.1.1

package/src/cli/RocketInit.js

@@ -1,10 +1,24 @@
 /* eslint-disable no-console */
-import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 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 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';
+const SITE_STATUS_PAGE_PATH = 'docs/pages/site-status.rocket.js';
 const ROCKET_AGENT_SKILL_PATH = '.agents/skills/rocket/SKILL.md';
+const EXISTING_ROCKET_PAGE_NOISE_THRESHOLD = 3;
+const STARTER_PAGE_FILES = [
+  SHARED_DATA_PATH,
+  INDEX_PAGE_PATH,
+  DOCS_PAGE_PATH,
+  JAVASCRIPT_DEMO_PAGE_PATH,
+  REQUEST_DEMO_PAGE_PATH,
+  SITE_STATUS_PAGE_PATH,
+];
 
 const rocketConfigSource = `/** @type {import('@rocket/js/types.js').RocketConfig} */
 export default {
@@ -12,6 +26,86 @@ export default {
 };
 `;
 
+const sharedDataSource = `import { resolve } from '@rocket/js/resolve.js';
+
+export const headerData = {
+  logo: [
+    resolve('@rocket/js/docs/assets/rocket-logo-light.svg', import.meta),
+    resolve('@rocket/js/docs/assets/rocket-text-no-logo.svg', import.meta),
+  ],
+  homeLink: '/',
+  navLinks: [
+    { text: 'Docs', href: '/docs' },
+    { text: 'Demos', href: '/javascript-demo' },
+  ],
+  socials: [],
+};
+
+/** @type {import('@rocket/js/types.js').FooterSection[]} */
+export const footerData = [];
+
+export const heroData = {
+  headerData,
+  footerData,
+  heroMainData: {
+    logoNoText: resolve('@rocket/js/docs/assets/rocket-logo-light.svg', import.meta),
+    eyebrow: 'ROCKET STARTER',
+    title: 'Rocket Site',
+    body: 'A static documentation site built with Rocket Pages and Atlas layouts.',
+    documentationLink: '/docs',
+    documentationText: 'Read the docs',
+    setupLink: '/javascript-demo',
+    setupText: 'View demos',
+    installLabel: 'Build',
+    installCommand: 'npm run build',
+  },
+  whyRocketData: [
+    {
+      icon: 'file-earmark-text',
+      title: 'Plain Pages',
+      description: 'Author durable content in Markdown and keep routes explicit.',
+    },
+    {
+      icon: 'play-btn',
+      title: 'Live Demos',
+      description: 'Use JavaScript Demos for browser examples with standalone URLs.',
+    },
+    {
+      icon: 'arrow-left-right',
+      title: 'Request Demos',
+      description: 'Show concrete same-site responses without leaving the docs.',
+    },
+  ],
+  quickStartData: {
+    title: 'Quick start',
+    subtitle: 'From this project:',
+    command: ['npm start', 'npm run build'],
+    description: 'Edit docs/pages, then run the build before publishing.',
+  },
+  workflowData: {
+    title: 'Starter workflow',
+    steps: [
+      {
+        icon: 'pencil-square',
+        title: 'Edit Pages',
+        description: 'Update the Markdown and JavaScript Pages under docs/pages.',
+      },
+      {
+        icon: 'terminal',
+        title: 'Build',
+        description: 'Run npm run build and fix any errors before publishing.',
+      },
+    ],
+  },
+};
+
+export const docData = {
+  headerData,
+  footerData,
+  navigationIconServerBudget: 35,
+};
+`;
+
 const indexPageSource = `\`\`\`js server
 export const config = {
   path: '/',
@@ -19,23 +113,165 @@ export const config = {
     title: 'Rocket Site',
     description: 'Documentation built with Rocket.',
   },
+  menu: {
+    iconName: 'house',
+    order: 0,
+  },
 };
 
-export { layout } from '@rocket/js/layout.js';
+import { atlasHeroLayout, atlasHeroComponents } from '@rocket/js/layouts/atlasHero.js';
+import { heroData } from './sharedData.js';
+
+export const components = atlasHeroComponents;
+export const layout = pageData => atlasHeroLayout(pageData, heroData);
 \`\`\`
 
 # Rocket Site
 
-This Page is rendered by Rocket.
+This starter is rendered with Rocket's Atlas hero layout.
 
 ## Next steps
 
 - Edit this Page in \`docs/pages/index.rocket.md\`.
-- Add general documentation Pages under \`docs/pages\`.
-- Add component reference Pages next to the components they document.
+- Edit the shared Atlas data in \`docs/pages/sharedData.js\`.
+- Add general documentation Pages under \`docs/pages\` with the Atlas docs layout.
+- Add component reference Pages next to the components they document under \`src\`.
 - Run \`npm run build\` to verify the site.
 `;
 
+const docsPageSource = `\`\`\`js server
+export const config = {
+  path: '/docs',
+  metadata: {
+    title: 'Docs',
+    description: 'A first Atlas docs Page generated by rocket init.',
+  },
+  menu: {
+    iconName: 'book',
+    order: 10,
+  },
+};
+
+import { atlasDocLayout, atlasDocComponents } from '@rocket/js/layouts/atlasDoc.js';
+import { docData } from './sharedData.js';
+
+export const components = atlasDocComponents;
+export const layout = pageData => atlasDocLayout(pageData, docData);
+\`\`\`
+
+# Docs
+
+This Page uses Rocket's package-provided Atlas docs layout.
+
+## Authoring Pages
+
+Every Page owns its URL with \`config.path\`. General documentation Pages belong under
+\`docs/pages\`, and component reference Pages can live next to the source files they document.
+
+## Navigation Icons
+
+Atlas docs navigation reads \`menu.iconName\` from Page config. Use Bootstrap Icon names for Pages
+that appear in the left navigation.
+`;
+
+const javascriptDemoPageSource = `\`\`\`js server
+export const config = {
+  path: '/javascript-demo',
+  metadata: {
+    title: 'JavaScript Demo',
+    description: 'A starter JavaScript Demo with a generated Standalone Demo URL.',
+  },
+  menu: {
+    iconName: 'window',
+    order: 20,
+  },
+};
+
+import { atlasDocLayout, atlasDocComponents } from '@rocket/js/layouts/atlasDoc.js';
+import { docData } from './sharedData.js';
+
+export const components = atlasDocComponents;
+export const layout = pageData => atlasDocLayout(pageData, docData);
+\`\`\`
+
+# JavaScript Demo
+
+Use a \`js demo\` block for browser-rendered examples. Rocket also generates a Standalone Demo URL
+at \`/javascript-demo/_demo/starterButton/\`.
+
+\`\`\`js demo label="docs/pages/javascript-demo.rocket.md"
+import { html } from 'lit';
+
+export const starterButton = () => html\`<button type="button">Rocket demo</button>\`;
+\`\`\`
+`;
+
+const requestDemoPageSource = `\`\`\`js server
+export const config = {
+  path: '/request-demo',
+  metadata: {
+    title: 'Request Demo',
+    description: 'A starter Request Demo pointed at a concrete static JSON Page.',
+  },
+  menu: {
+    iconName: 'arrow-left-right',
+    order: 30,
+  },
+};
+
+import { atlasDocLayout, atlasDocComponents } from '@rocket/js/layouts/atlasDoc.js';
+import { docData } from './sharedData.js';
+
+export const components = atlasDocComponents;
+export const layout = pageData => atlasDocLayout(pageData, docData);
+\`\`\`
+
+# Request Demo
+
+Use a Request Demo when readers need to inspect a same-site \`GET\` response. Static Request Demo
+examples should point at concrete paths and avoid query-dependent output.
+
+\`\`\`js request-demo url="/api/site-status.json" label="docs/pages/site-status.rocket.js" height=220
+export const config = {
+  path: '/api/site-status.json',
+  metadata: { title: 'Site Status' },
+  menu: false,
+};
+
+export default function siteStatusPage() {
+  return {
+    status: 'ready',
+    generatedBy: 'Rocket',
+    pages: ['/docs', '/javascript-demo', '/request-demo'],
+  };
+}
+\`\`\`
+`;
+
+const siteStatusPageSource = `export const config = {
+  path: '/api/site-status.json',
+  metadata: { title: 'Site Status' },
+  menu: false,
+};
+
+export default function siteStatusPage() {
+  return {
+    status: 'ready',
+    generatedBy: 'Rocket',
+    pages: ['/docs', '/javascript-demo', '/request-demo'],
+  };
+}
+`;
+
+const STARTER_PAGE_SOURCES = new Map([
+  [SHARED_DATA_PATH, sharedDataSource],
+  [INDEX_PAGE_PATH, indexPageSource],
+  [DOCS_PAGE_PATH, docsPageSource],
+  [JAVASCRIPT_DEMO_PAGE_PATH, javascriptDemoPageSource],
+  [REQUEST_DEMO_PAGE_PATH, requestDemoPageSource],
+  [SITE_STATUS_PAGE_PATH, siteStatusPageSource],
+]);
+
 const rocketAgentSkillSource = `---
 name: rocket
 description: Use when editing Rocket Pages, config, layouts, component reference Pages, or build behavior in this project.
@@ -43,18 +279,21 @@ description: Use when editing Rocket Pages, config, layouts, component reference
 
 # Rocket
 
-Use this skill when working on this project's Rocket site.
-
 ## Rules
 
-- Read \`rocket-config.js\` before changing Pages.
-- Rocket discovers Pages from \`includeGlobs\`.
-- Every Page owns its public URL through \`config.path\`.
-- Put general documentation Pages under \`docs/pages\`.
-- Put component reference Pages next to the component they document.
-- Prefer Markdown Pages for durable content.
-- Use JavaScript Pages only for request-time or programmatic rendering.
-- Keep Rocket changes buildable with \`npm run build\`.
+- Read \`rocket-config.js\` first; Page discovery follows \`includeGlobs\`.
+- Every Page owns its URL through \`config.path\`; put general docs in \`docs/pages\` and component docs next to the component.
+- Prefer Markdown for durable content; use JavaScript Pages for request-time or programmatic output.
+- Prefer interactive examples for component and behavior docs; use \`js demo\` when readers benefit from trying the UI.
+- Prefer Atlas docs layouts: \`atlasDocLayout\` for docs, \`atlasHeroLayout\` for a standalone docs home, with matching \`components\` exports.
+- 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.
+- 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/\`.
+- Keep \`npm run build\` passing; record Rocket package issues separately from local workarounds.
 `;
 
 export class RocketInit {
@@ -64,7 +303,7 @@ export class RocketInit {
   async setupCommand(program) {
     program
       .command('init')
-      .description('create a minimal Rocket project shape')
+      .description('create a Rocket docs starter')
       .action(() => {
         const result = this.init();
         reportInitResult(result);
@@ -89,8 +328,15 @@ export class RocketInit {
       writeJsonFile('package.json', packageJsonUpdate.packageJson);
     }
 
+    const shouldCreateStarterPages =
+      existingRocketPageFileCount(process.cwd()) < EXISTING_ROCKET_PAGE_NOISE_THRESHOLD;
+
     writeFileIfMissing(ROCKET_CONFIG_PATH, rocketConfigSource, result);
-    writeFileIfMissing(INDEX_PAGE_PATH, indexPageSource, result);
+    if (shouldCreateStarterPages) {
+      for (const filePath of STARTER_PAGE_FILES) {
+        writeFileIfMissing(filePath, STARTER_PAGE_SOURCES.get(filePath) || '', result);
+      }
+    }
     writeFileIfMissing(ROCKET_AGENT_SKILL_PATH, rocketAgentSkillSource, result);
 
     return result;
@@ -204,7 +450,7 @@ function addRocketScript(scripts, { genericName, fallbackName, command, updated,
     updated.push(`scripts.${genericName}`);
     return;
   }
-  if (scripts[genericName] === command) {
+  if (scriptRunsRocketCommand(scripts[genericName], genericName)) {
     skipped.push(`scripts.${genericName}`);
     return;
   }
@@ -237,8 +483,8 @@ function rocketNextSteps(packageJson) {
     return ['npx rocket start', 'npx rocket build'];
   }
   return [
-    npmScriptCommand(packageJson.scripts, 'start', 'rocket:start', 'rocket start'),
-    npmScriptCommand(packageJson.scripts, 'build', 'rocket:build', 'rocket build'),
+    npmScriptCommand(packageJson.scripts, 'start', 'rocket:start'),
+    npmScriptCommand(packageJson.scripts, 'build', 'rocket:build'),
   ];
 }
 
@@ -246,18 +492,85 @@ function rocketNextSteps(packageJson) {
  * @param {Record<string, any>} scripts
  * @param {string} genericName
  * @param {string} fallbackName
- * @param {string} command
  */
-function npmScriptCommand(scripts, genericName, fallbackName, command) {
-  if (scripts[genericName] === command) {
+function npmScriptCommand(scripts, genericName, fallbackName) {
+  if (scriptRunsRocketCommand(scripts[genericName], genericName)) {
     return genericName === 'start' ? 'npm start' : `npm run ${genericName}`;
   }
-  if (scripts[fallbackName] === command) {
+  if (scriptRunsRocketCommand(scripts[fallbackName], genericName)) {
     return `npm run ${fallbackName}`;
   }
   return `npx rocket ${genericName}`;
 }
 
+/**
+ * @param {unknown} script
+ * @param {string} commandName
+ * @returns {boolean}
+ */
+function scriptRunsRocketCommand(script, commandName) {
+  if (typeof script !== 'string') {
+    return false;
+  }
+  const shellBoundary = '[\\s"\\\'`;&|()]';
+  return new RegExp(
+    `(^|${shellBoundary})(?:npx\\s+)?rocket\\s+${commandName}(?=$|${shellBoundary})`,
+  ).test(script);
+}
+
+/**
+ * @param {string} directory
+ * @returns {number}
+ */
+function existingRocketPageFileCount(directory) {
+  if (!existsSync(directory)) {
+    return 0;
+  }
+  return countRocketPageFiles(directory, { count: 0 });
+}
+
+/**
+ * @param {string} directory
+ * @param {{ count: number }} state
+ * @returns {number}
+ */
+function countRocketPageFiles(directory, state) {
+  if (state.count >= EXISTING_ROCKET_PAGE_NOISE_THRESHOLD) {
+    return state.count;
+  }
+  for (const entry of readdirSync(directory, { withFileTypes: true })) {
+    if (shouldIgnoreRocketPageScanEntry(entry.name)) {
+      continue;
+    }
+    const entryPath = path.join(directory, entry.name);
+    if (entry.isDirectory()) {
+      countRocketPageFiles(entryPath, state);
+    } else if (isRocketPageFile(entry.name)) {
+      state.count += 1;
+    }
+    if (state.count >= EXISTING_ROCKET_PAGE_NOISE_THRESHOLD) {
+      return state.count;
+    }
+  }
+  return state.count;
+}
+
+/**
+ * @param {string} name
+ * @returns {boolean}
+ */
+function shouldIgnoreRocketPageScanEntry(name) {
+  return ['.git', '.netlify', 'coverage', 'dist', 'node_modules', 'temp'].includes(name);
+}
+
+/**
+ * @param {string} fileName
+ * @returns {boolean}
+ */
+function isRocketPageFile(fileName) {
+  return fileName.endsWith('.rocket.md') || fileName.endsWith('.rocket.js');
+}
+
 /**
  * @param {string} filePath
  * @param {string} contents

package/src/cli/RocketStart.js

@@ -5,6 +5,9 @@ import { debounce } from '../debounce.js';
 import path from 'path';
 
 export class RocketStart {
+  /** @type {RocketStartOptions} */
+  startOptions = {};
+
   /**
    * @param {import('commander').Command} program
    * @param {import('./RocketCli.js').RocketCli} cli
@@ -12,17 +15,29 @@ export class RocketStart {
   async setupCommand(program, cli) {
     this.cli = cli;
 
-    program.command('start').action(async () => {
-      await cli.getConfig();
-      await this.start();
-    });
+    program
+      .command('start')
+      .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')
+      .action(async options => {
+        const startOptions = normalizeStartOptions(options);
+        await cli.getConfig();
+        await this.start(startOptions);
+      });
   }
 
-  spawnServer() {
+  /**
+   * @param {RocketStartOptions} [options]
+   */
+  spawnServer(options = {}) {
     process.stdin.setRawMode?.(true);
     return spawn(
       'node',
-      [path.join(import.meta.dirname, '../main.js'), this.cli?.configFilePath || ''],
+      startServerArgs({
+        configFilePath: this.cli?.configFilePath,
+        options,
+      }),
       {
         stdio: 'inherit',
         cwd: process.cwd(),
@@ -32,36 +47,42 @@ export class RocketStart {
 
   restartServer() {
     this.server?.kill();
-    this.server = this.spawnServer();
+    this.server = this.spawnServer(this.startOptions);
     console.clear();
     console.log('Restarting rocket server...');
   }
 
-  async start() {
-    this.server = this.spawnServer();
+  /**
+   * @param {RocketStartOptions} [options]
+   */
+  async start(options = {}) {
+    this.startOptions = options;
+    this.server = this.spawnServer(options);
 
-    // watch config
-    watch(
-      path.join(process.cwd(), this.cli?.configFilePath || 'rocket-config.js'),
-      debounce(async (_, filename) => {
-        if (!filename) {
-          return;
-        }
-        this.restartServer();
-      }, 100),
-    );
+    if (options.watch !== false) {
+      // watch config
+      watch(
+        path.join(process.cwd(), this.cli?.configFilePath || 'rocket-config.js'),
+        debounce(async (_, filename) => {
+          if (!filename) {
+            return;
+          }
+          this.restartServer();
+        }, 100),
+      );
 
-    // watch src
-    watch(
-      import.meta.dirname,
-      { recursive: true },
-      debounce(async (_, filename) => {
-        if (!filename) {
-          return;
-        }
-        this.restartServer();
-      }, 100),
-    );
+      // watch src
+      watch(
+        import.meta.dirname,
+        { recursive: true },
+        debounce(async (_, filename) => {
+          if (!filename) {
+            return;
+          }
+          this.restartServer();
+        }, 100),
+      );
+    }
 
     process.stdin.on('data', data => {
       const char = data.toString();
@@ -77,3 +98,48 @@ export class RocketStart {
     console.log('Restart the server with Ctrl+R');
   }
 }
+
+/**
+ * @typedef {{ port?: number; open?: boolean; watch?: boolean }} RocketStartOptions
+ */
+
+/**
+ * @param {{ port?: string; open?: boolean; watch?: boolean }} options
+ * @returns {RocketStartOptions}
+ */
+export function normalizeStartOptions(options) {
+  return {
+    ...(options.port !== undefined ? { port: parsePortOption(options.port) } : {}),
+    ...(options.open !== undefined ? { open: options.open } : {}),
+    ...(options.watch !== undefined ? { watch: options.watch } : {}),
+  };
+}
+
+/**
+ * @param {{ configFilePath?: string; options?: RocketStartOptions }} input
+ */
+export function startServerArgs({ configFilePath, options = {} }) {
+  return [
+    path.join(import.meta.dirname, '../main.js'),
+    configFilePath || '',
+    JSON.stringify(options),
+  ];
+}
+
+/**
+ * @param {string} value
+ */
+function parsePortOption(value) {
+  if (!/^\d+$/.test(value)) {
+    throw new Error(
+      `Invalid --port ${JSON.stringify(value)}. Expected an integer from 1 to 65535.`,
+    );
+  }
+  const port = Number(value);
+  if (port < 1 || port > 65535) {
+    throw new Error(
+      `Invalid --port ${JSON.stringify(value)}. Expected an integer from 1 to 65535.`,
+    );
+  }
+  return port;
+}

package/src/components.js

@@ -1,6 +1,25 @@
 import { resolve } from '@rocket/js/resolve.js';
 import { createComponentHydration } from './component-hydration.js';
 
+/** @type {import('@rocket/js/types.js').Components} */
+export const rocketDemoComponents = {
+  'rocket-code-block': {
+    file: './RocketCodeBlock.js',
+    className: 'RocketCodeBlock',
+    loading: 'hydrate:onVisible',
+  },
+  'rocket-js-demo': {
+    file: './RocketJsDemo.js',
+    className: 'RocketJsDemo',
+    loading: 'client',
+  },
+  'rocket-request-demo': {
+    file: './RocketRequestDemo.js',
+    className: 'RocketRequestDemo',
+    loading: 'client',
+  },
+};
+
 /**
  * @param {import('@rocket/js/types.js').Components} components
  */

package/src/icons.js

@@ -46,6 +46,21 @@ export function iconsFromPath(files) {
   };
 }
 
+export const rocketBootstrapIconLibraries = {
+  bootstrap: iconsFromPackage('bootstrap-icons', 'icons/*.svg'),
+};
+
+export const rocketDefaultBootstrapIconLibrary = 'bootstrap';
+
+/**
+ * @param {{ addIconLibraries: (iconLibraries: import('@rocket/js/types.js').IconLibrariesConfig, options?: { defaultIconLibrary?: string }) => void }} pageData
+ */
+export function addBootstrapIconLibrary(pageData) {
+  pageData.addIconLibraries(rocketBootstrapIconLibraries, {
+    defaultIconLibrary: rocketDefaultBootstrapIconLibrary,
+  });
+}
+
 export class IconAssetStore {
   constructor() {
     /** @type {Map<string, { url: string; svg: string; library: string; name: string }>} */

package/src/layouts/atlas/atlasDocLayout.js

@@ -5,6 +5,7 @@ import { resolve } from '../../resolve.js';
 import { webAwesomeComponents } from '@rocket/js/components/web-awesome.js';
 import { addBootstrapIconLibrary } from '../layout.js';
 import { pageNavigationLinks } from '../../menus/pageNavigation.js';
+import { rocketDemoComponents } from '../../components.js';
 
 export const DEFAULT_ATLAS_DOC_NAVIGATION_ICON_SERVER_BUDGET = 35;
 
@@ -35,21 +36,7 @@ export const atlasDocComponents = {
     className: 'RocketSocialLink',
     loading: 'server',
   },
-  'rocket-code-block': {
-    file: './RocketCodeBlock.js',
-    className: 'RocketCodeBlock',
-    loading: 'hydrate:onVisible',
-  },
-  'rocket-js-demo': {
-    file: './RocketJsDemo.js',
-    className: 'RocketJsDemo',
-    loading: 'client',
-  },
-  'rocket-request-demo': {
-    file: './RocketRequestDemo.js',
-    className: 'RocketRequestDemo',
-    loading: 'client',
-  },
+  ...rocketDemoComponents,
   ...webAwesomeComponents,
 };