@bytefaceinc/web-lang 0.1.1

package/lib/cli/commands/compile.js

@@ -0,0 +1,127 @@
+'use strict';
+
+const { performance } = require('perf_hooks');
+const { compileInputSource } = require('../compile-service');
+const { inferDefaultCompileTargets, resolveTargets } = require('../targets');
+const {
+  bold,
+  color,
+  createSpinner,
+  dim,
+  displayPath,
+  formatCompileStatsLine,
+  formatBytes,
+  formatDuration,
+  formatErrorMessage,
+  indentMultiline,
+  padLabel,
+  pluralize,
+  printCommandHeader,
+  printLine,
+  printTargetIssues,
+  sum,
+} = require('../shared');
+
+async function executeCompileCommand({ args }) {
+  const targets = args.length > 0 ? args : inferDefaultCompileTargets(process.cwd());
+
+  if (targets.length === 0) {
+    printCompileHelp();
+    process.exitCode = 1;
+    return;
+  }
+
+  const resolution = resolveTargets(targets, process.cwd());
+
+  printTargetIssues(resolution.errors);
+
+  if (resolution.files.length === 0) {
+    printLine(color('[x] No WEB sources found to compile.', 'red'));
+    process.exitCode = 1;
+    return;
+  }
+
+  const startedAt = performance.now();
+  const results = [];
+  const failures = [];
+
+  printCommandHeader(`Compiling ${pluralize(resolution.files.length, 'WEB source')} from ${displayPath(process.cwd())}`);
+
+  for (let index = 0; index < resolution.files.length; index += 1) {
+    const inputPath = resolution.files[index];
+    const spinner = createSpinner(`[${index + 1}/${resolution.files.length}] Compiling ${displayPath(inputPath)}`);
+
+    spinner.start();
+
+    try {
+      const result = await compileInputSource(inputPath);
+
+      spinner.succeed(
+        `[ok] ${displayPath(result.inputPath)} -> ${displayPath(result.htmlPath)} + ${displayPath(result.cssPath)} (${formatDuration(result.durationMs)})`
+      );
+
+      printLine(dim(`     ${formatCompileStatsLine(result)}`));
+      results.push(result);
+    } catch (error) {
+      spinner.fail(`[x] ${displayPath(inputPath)} failed`);
+      printLine(dim(indentMultiline(formatErrorMessage(error), '     ')));
+      failures.push({
+        inputPath,
+        message: formatErrorMessage(error),
+      });
+    }
+  }
+
+  printCompileSummary(results, failures, performance.now() - startedAt, resolution.errors.length);
+
+  if (failures.length > 0 || resolution.errors.length > 0) {
+    process.exitCode = 1;
+  }
+}
+
+function printCompileSummary(results, failures, durationMs, resolutionErrorCount) {
+  const totalSourceBytes = sum(results, (result) => result.sourceBytes);
+  const totalOutputBytes = sum(results, (result) => result.htmlBytes + result.cssBytes);
+  const totalDomNodes = sum(results, (result) => result.stats.domNodeCount);
+  const totalCssRules = sum(results, (result) => result.stats.cssRuleCount);
+  const totalHeadEntries = sum(results, (result) => result.stats.headEntryCount);
+  const totalScriptBlocks = sum(results, (result) => result.stats.scriptBlockCount);
+
+  printLine('');
+  printLine(bold('Summary'));
+  printLine(`${padLabel('Succeeded')} ${color(String(results.length), 'green')}`);
+  printLine(`${padLabel('Failed')} ${failures.length > 0 ? color(String(failures.length), 'red') : String(failures.length)}`);
+  printLine(`${padLabel('Skipped')} ${resolutionErrorCount > 0 ? color(String(resolutionErrorCount), 'yellow') : String(resolutionErrorCount)}`);
+  printLine(`${padLabel('Source bytes')} ${formatBytes(totalSourceBytes)}`);
+  printLine(`${padLabel('Output bytes')} ${formatBytes(totalOutputBytes)}`);
+  printLine(`${padLabel('DOM nodes')} ${totalDomNodes}`);
+  printLine(`${padLabel('CSS rules')} ${totalCssRules}`);
+  printLine(`${padLabel('Head entries')} ${totalHeadEntries}`);
+  printLine(`${padLabel('Script blocks')} ${totalScriptBlocks}`);
+  printLine(`${padLabel('Duration')} ${formatDuration(durationMs)}`);
+}
+
+function printCompileHelp() {
+  printLine(color(bold('Compile Command'), 'blue'));
+  printLine('Compile one or more `.web` sources into matching HTML and CSS files.');
+  printLine('');
+  printLine(bold('Usage'));
+  printLine('  web <file.web>');
+  printLine('  web <file>');
+  printLine('  web <directory>');
+  printLine('  web <glob>');
+  printLine('  web compile <target...>');
+  printLine('');
+  printLine(bold('Examples'));
+  printLine('  web home.web');
+  printLine('  web home');
+  printLine('  web .');
+  printLine('  web ./code/*');
+  printLine('');
+  printLine('If no argument is provided and `layout.web` exists, the CLI compiles it by default.');
+}
+
+module.exports = {
+  executeCompileCommand,
+  printCompileHelp,
+};

package/lib/cli/commands/init.js

@@ -0,0 +1,172 @@
+'use strict';
+
+const { performance } = require('perf_hooks');
+const { compileInputSource } = require('../compile-service');
+const {
+  INIT_AGENT_GUIDE_FILENAME,
+  INIT_DOC_SEQUENCE,
+  INIT_SOURCE_FILENAME,
+  listExistingInitArtifacts,
+  resolveInitProjectArtifacts,
+  writeInitProjectFiles,
+} = require('../init-service');
+const {
+  bold,
+  color,
+  createSpinner,
+  dim,
+  displayPath,
+  formatBytes,
+  formatCompileStatsLine,
+  formatDuration,
+  formatErrorMessage,
+  indentMultiline,
+  padLabel,
+  printCommandHeader,
+  printLine,
+} = require('../shared');
+
+async function executeInitCommand({ args }) {
+  let parsedArgs;
+  let artifacts;
+
+  try {
+    parsedArgs = parseInitArgs(args);
+    artifacts = resolveInitProjectArtifacts(parsedArgs.targetDirectory, process.cwd());
+  } catch (error) {
+    printLine(color(`[x] ${formatErrorMessage(error)}`, 'red'));
+    process.exitCode = 1;
+    return;
+  }
+
+  const startedAt = performance.now();
+
+  printCommandHeader(`Initializing a new WEB project in ${displayPath(artifacts.projectRoot)}`);
+  printLine(dim('This creates a starter `index.web`, a combined `web-lang-agents.md`, and the first compiled HTML/CSS output.'));
+
+  if (!artifacts.projectRootExists) {
+    printLine(dim('The target directory does not exist yet. WEB will create it before writing the starter files.'));
+  }
+
+  printLine('');
+
+  const conflicts = listExistingInitArtifacts(artifacts);
+
+  if (conflicts.length > 0) {
+    printLine(color('[x] Cannot initialize this directory because `web init` would overwrite existing files.', 'red'));
+
+    for (const conflictPath of conflicts) {
+      printLine(dim(`    - ${displayPath(conflictPath)}`));
+    }
+
+    printLine(dim('    Move those files, choose a clean project directory, or remove the old scaffold before running `web init` again.'));
+    process.exitCode = 1;
+    return;
+  }
+
+  const scaffoldSpinner = createSpinner('[1/2] Creating starter project files');
+  scaffoldSpinner.start();
+
+  let scaffoldResult;
+
+  try {
+    scaffoldResult = writeInitProjectFiles(artifacts);
+    scaffoldSpinner.succeed(`[ok] Created ${INIT_SOURCE_FILENAME} + ${INIT_AGENT_GUIDE_FILENAME}`);
+    printLine(dim(`     ${formatBytes(scaffoldResult.sourceBytes + scaffoldResult.agentGuideBytes)} across 2 files | bundled docs: ${INIT_DOC_SEQUENCE.join(', ')}`));
+  } catch (error) {
+    scaffoldSpinner.fail('[x] Project scaffolding failed');
+    printLine(dim(indentMultiline(formatErrorMessage(error), '     ')));
+    process.exitCode = 1;
+    return;
+  }
+
+  const compileSpinner = createSpinner(`[2/2] Compiling ${displayPath(artifacts.sourcePath)}`);
+  compileSpinner.start();
+
+  let compileResult;
+
+  try {
+    compileResult = await compileInputSource(artifacts.sourcePath);
+    compileSpinner.succeed(
+      `[ok] ${displayPath(compileResult.inputPath)} -> ${displayPath(compileResult.htmlPath)} + ${displayPath(compileResult.cssPath)} (${formatDuration(compileResult.durationMs)})`
+    );
+    printLine(dim(`     ${formatCompileStatsLine(compileResult)}`));
+  } catch (error) {
+    compileSpinner.fail(`[x] ${displayPath(artifacts.sourcePath)} failed`);
+    printLine(dim(indentMultiline(formatErrorMessage(error), '     ')));
+    process.exitCode = 1;
+    return;
+  }
+
+  printInitSummary({
+    artifacts,
+    scaffoldResult,
+    compileResult,
+    durationMs: performance.now() - startedAt,
+  });
+}
+
+function printInitHelp() {
+  printLine(color(bold('Init Command'), 'blue'));
+  printLine('Initialize a new WEB project in the current directory or in one target directory with a starter page, compiled output, and a local agent context doc.');
+  printLine('');
+  printLine(bold('Usage'));
+  printLine('  web init');
+  printLine('  web init .');
+  printLine('  web init <directory>');
+  printLine('');
+  printLine(bold('Behavior'));
+  printLine('  Uses the current working directory when no target is provided');
+  printLine('  Accepts one directory target such as `.` or `website`');
+  printLine('  Creates the target directory automatically when it does not exist yet');
+  printLine('  Creates `index.web` with a simple intro banner');
+  printLine('  Creates `web-lang-agents.md` by combining `getting-started.md`, `cli.md`, and `compiler.md`');
+  printLine('  Compiles the starter page into `index.html` and `index.css`');
+  printLine('  Refuses to overwrite existing scaffold files in the target directory');
+  printLine('');
+  printLine(bold('Example'));
+  printLine('  web init .');
+  printLine('  web init website');
+  printLine('');
+  printLine('The generated `web-lang-agents.md` keeps the packaged WEB docs in one file so local agents can load the project context quickly.');
+}
+
+function parseInitArgs(args) {
+  if (args.length === 0) {
+    return {
+      targetDirectory: '.',
+    };
+  }
+
+  if (args.length === 1) {
+    return {
+      targetDirectory: args[0],
+    };
+  }
+
+  throw new Error('The init command accepts at most one directory target. Examples: `web init .` or `web init website`.');
+}
+
+function printInitSummary({ artifacts, scaffoldResult, compileResult, durationMs }) {
+  printLine('');
+  printLine(bold('Summary'));
+  printLine(`${padLabel('Project root')} ${displayPath(artifacts.projectRoot)}`);
+  printLine(`${padLabel('Source')} ${displayPath(artifacts.sourcePath)}`);
+  printLine(`${padLabel('Agent guide')} ${displayPath(artifacts.agentGuidePath)}`);
+  printLine(`${padLabel('HTML')} ${displayPath(compileResult.htmlPath)}`);
+  printLine(`${padLabel('CSS')} ${displayPath(compileResult.cssPath)}`);
+  printLine(`${padLabel('Bundled docs')} ${scaffoldResult.bundledDocs.join(', ')}`);
+  printLine(`${padLabel('Source bytes')} ${formatBytes(scaffoldResult.sourceBytes)}`);
+  printLine(`${padLabel('Guide bytes')} ${formatBytes(scaffoldResult.agentGuideBytes)}`);
+  printLine(`${padLabel('Output bytes')} ${formatBytes(compileResult.htmlBytes + compileResult.cssBytes)}`);
+  printLine(`${padLabel('DOM nodes')} ${compileResult.stats.domNodeCount}`);
+  printLine(`${padLabel('CSS rules')} ${compileResult.stats.cssRuleCount}`);
+  printLine(`${padLabel('Head entries')} ${compileResult.stats.headEntryCount}`);
+  printLine(`${padLabel('Script blocks')} ${compileResult.stats.scriptBlockCount}`);
+  printLine(`${padLabel('Duration')} ${formatDuration(durationMs)}`);
+}
+
+module.exports = {
+  executeInitCommand,
+  printInitHelp,
+};

package/lib/cli/commands/screenshot.js

@@ -0,0 +1,257 @@
+'use strict';
+
+const path = require('path');
+const { performance } = require('perf_hooks');
+const { compileInputSource } = require('../compile-service');
+const {
+  DEFAULT_DEVICE_SCALE_FACTOR,
+  DEFAULT_SCREENSHOT_FORMAT,
+  DEFAULT_VIEWPORT_HEIGHT,
+  DEFAULT_VIEWPORT_WIDTH,
+  renderScreenshotArtifact,
+} = require('../screenshot-service');
+const { SCREENSHOT_DIRECTORY_NAME } = require('../screenshot-artifacts');
+const { resolveTargets } = require('../targets');
+const {
+  bold,
+  color,
+  createSpinner,
+  dim,
+  displayPath,
+  formatBytes,
+  formatCompileStatsLine,
+  formatDuration,
+  formatErrorMessage,
+  indentMultiline,
+  padLabel,
+  printCommandHeader,
+  printLine,
+  printTargetIssues,
+} = require('../shared');
+
+const SCREENSHOT_FORMAT_FLAGS = new Map([
+  ['--jpg', 'jpg'],
+  ['--jpeg', 'jpg'],
+  ['--png', 'png'],
+]);
+
+async function executeScreenshotCommand({ args }) {
+  let screenshotArgs;
+
+  try {
+    screenshotArgs = parseScreenshotArgs(args);
+  } catch (error) {
+    printLine(color(`[x] ${formatErrorMessage(error)}`, 'red'));
+    process.exitCode = 1;
+    return;
+  }
+
+  const resolution = resolveTargets([screenshotArgs.target], process.cwd());
+
+  printTargetIssues(resolution.errors);
+
+  if (resolution.files.length === 0) {
+    printLine(color('[x] No WEB source found to render.', 'red'));
+    process.exitCode = 1;
+    return;
+  }
+
+  if (resolution.files.length !== 1) {
+    printLine(color(`[x] The screenshot command expects exactly one WEB source, but "${screenshotArgs.target}" resolved to ${resolution.files.length}.`, 'red'));
+    printLine(dim('    Use a single file path, a bare file name, or a target that resolves to one `.web` source.'));
+    process.exitCode = 1;
+    return;
+  }
+
+  const inputPath = resolution.files[0];
+  const startedAt = performance.now();
+
+  printCommandHeader(`Capturing a rendered screenshot for ${displayPath(inputPath)} from ${displayPath(process.cwd())}`);
+  printLine(dim(`Images will be written to ${displayPath(path.join(process.cwd(), SCREENSHOT_DIRECTORY_NAME))}`));
+  printLine('');
+
+  const compileSpinner = createSpinner(`[1/2] Compiling ${displayPath(inputPath)}`);
+  compileSpinner.start();
+
+  let compileResult;
+
+  try {
+    compileResult = await compileInputSource(inputPath);
+
+    compileSpinner.succeed(
+      `[ok] ${displayPath(compileResult.inputPath)} -> ${displayPath(compileResult.htmlPath)} + ${displayPath(compileResult.cssPath)} (${formatDuration(compileResult.durationMs)})`
+    );
+
+    printLine(dim(`     ${formatCompileStatsLine(compileResult)}`));
+  } catch (error) {
+    compileSpinner.fail(`[x] ${displayPath(inputPath)} failed`);
+    printLine(dim(indentMultiline(formatErrorMessage(error), '     ')));
+    process.exitCode = 1;
+    return;
+  }
+
+  const renderSpinner = createSpinner('[2/2] Rendering screenshot artifact');
+  renderSpinner.start();
+
+  let screenshotResult;
+
+  try {
+    screenshotResult = await renderScreenshotArtifact({
+      inputPath,
+      htmlPath: compileResult.htmlPath,
+      workingDirectory: process.cwd(),
+      format: screenshotArgs.format,
+      viewportWidth: screenshotArgs.viewportWidth,
+      viewportHeight: screenshotArgs.viewportHeight,
+      deviceScaleFactor: screenshotArgs.deviceScaleFactor,
+      fullPage: screenshotArgs.fullPage,
+    });
+
+    renderSpinner.succeed(
+      `[ok] ${displayPath(screenshotResult.outputPath)} (${formatDuration(screenshotResult.durationMs)})`
+    );
+
+    printLine(dim(`     ${formatScreenshotStatsLine(screenshotResult)}`));
+  } catch (error) {
+    renderSpinner.fail('[x] Screenshot render failed');
+    printLine(dim(indentMultiline(formatErrorMessage(error), '     ')));
+    process.exitCode = 1;
+    return;
+  }
+
+  printScreenshotSummary(compileResult, screenshotResult, performance.now() - startedAt);
+}
+
+function printScreenshotHelp() {
+  printLine(color(bold('Screenshot Command'), 'blue'));
+  printLine('Compile one `.web` source and render a JPG or PNG screenshot of the compiled page.');
+  printLine('');
+  printLine(bold('Usage'));
+  printLine('  web screenshot <file.web> [--jpg|--png] [width height [deviceScaleFactor]]');
+  printLine('');
+  printLine(bold('Examples'));
+  printLine('  web screenshot home.web');
+  printLine('  web screenshot home');
+  printLine('  web screenshot home.web --jpg 1080 1080 2');
+  printLine('  web screenshot home.web --png 1440 900');
+  printLine('  web watch home.web -s');
+  printLine('');
+  printLine('Defaults');
+  printLine('  Format: jpg');
+  printLine('  Width: 1600');
+  printLine('  Full-page mode: on when no width and height are provided');
+  printLine('  Device scale factor: 1');
+  printLine(`  Screenshot directory: ./${SCREENSHOT_DIRECTORY_NAME}`);
+  printLine('');
+  printLine('If width and height are provided, the command captures the current viewport instead of forcing a full-page image.');
+  printLine(`The CLI creates ./${SCREENSHOT_DIRECTORY_NAME} in the current working directory automatically when needed.`);
+}
+
+function parseScreenshotArgs(args) {
+  if (args.length === 0) {
+    throw new Error('The screenshot command expects a WEB source. Example: web screenshot home.web --jpg 1080 1080 2');
+  }
+
+  const [target, ...rest] = args;
+  const numericArgs = [];
+  let format = DEFAULT_SCREENSHOT_FORMAT;
+
+  for (const token of rest) {
+    if (SCREENSHOT_FORMAT_FLAGS.has(token)) {
+      format = SCREENSHOT_FORMAT_FLAGS.get(token);
+      continue;
+    }
+
+    if (token.startsWith('-')) {
+      throw new Error(`Unknown screenshot option "${token}". Supported flags are --jpg, --jpeg, and --png.`);
+    }
+
+    numericArgs.push(token);
+  }
+
+  if (numericArgs.length !== 0 && numericArgs.length !== 2 && numericArgs.length !== 3) {
+    throw new Error('Screenshot size expects `width height [deviceScaleFactor]`. Example: web screenshot home.web --jpg 1080 1080 2');
+  }
+
+  if (numericArgs.length === 0) {
+    return {
+      target,
+      format,
+      viewportWidth: DEFAULT_VIEWPORT_WIDTH,
+      viewportHeight: DEFAULT_VIEWPORT_HEIGHT,
+      deviceScaleFactor: DEFAULT_DEVICE_SCALE_FACTOR,
+      fullPage: true,
+    };
+  }
+
+  return {
+    target,
+    format,
+    viewportWidth: parsePositiveInteger(numericArgs[0], 'width'),
+    viewportHeight: parsePositiveInteger(numericArgs[1], 'height'),
+    deviceScaleFactor: numericArgs[2] ? parsePositiveNumber(numericArgs[2], 'deviceScaleFactor') : DEFAULT_DEVICE_SCALE_FACTOR,
+    fullPage: false,
+  };
+}
+
+function parsePositiveInteger(rawValue, label) {
+  if (!/^\d+$/.test(rawValue)) {
+    throw new Error(`The screenshot ${label} must be a positive whole number. Received "${rawValue}".`);
+  }
+
+  const value = Number(rawValue);
+
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new Error(`The screenshot ${label} must be greater than zero. Received "${rawValue}".`);
+  }
+
+  return value;
+}
+
+function parsePositiveNumber(rawValue, label) {
+  if (!/^\d+(\.\d+)?$/.test(rawValue)) {
+    throw new Error(`The screenshot ${label} must be a positive number. Received "${rawValue}".`);
+  }
+
+  const value = Number(rawValue);
+
+  if (!Number.isFinite(value) || value <= 0) {
+    throw new Error(`The screenshot ${label} must be greater than zero. Received "${rawValue}".`);
+  }
+
+  return value;
+}
+
+function formatScreenshotStatsLine(result) {
+  const modeLabel = result.fullPage
+    ? `full page ${result.pageWidth} x ${result.pageHeight}`
+    : `viewport ${result.viewportWidth} x ${result.viewportHeight}`;
+
+  return `${result.format.toUpperCase()} | ${modeLabel} | @ ${result.deviceScaleFactor}x | ${formatBytes(result.imageBytes)} out`;
+}
+
+function printScreenshotSummary(compileResult, screenshotResult, durationMs) {
+  printLine('');
+  printLine(bold('Summary'));
+  printLine(`${padLabel('Source')} ${displayPath(compileResult.inputPath)}`);
+  printLine(`${padLabel('HTML')} ${displayPath(compileResult.htmlPath)}`);
+  printLine(`${padLabel('CSS')} ${displayPath(compileResult.cssPath)}`);
+  printLine(`${padLabel('Image')} ${displayPath(screenshotResult.outputPath)}`);
+  printLine(`${padLabel('Format')} ${screenshotResult.format.toUpperCase()}`);
+  printLine(`${padLabel('Mode')} ${screenshotResult.fullPage ? 'full page' : 'viewport'}`);
+  printLine(`${padLabel('Viewport')} ${screenshotResult.viewportWidth} x ${screenshotResult.viewportHeight} @ ${screenshotResult.deviceScaleFactor}x`);
+  printLine(`${padLabel('Page size')} ${screenshotResult.pageWidth} x ${screenshotResult.pageHeight}`);
+  printLine(`${padLabel('Image bytes')} ${formatBytes(screenshotResult.imageBytes)}`);
+  printLine(`${padLabel('Source bytes')} ${formatBytes(compileResult.sourceBytes)}`);
+  printLine(`${padLabel('Output bytes')} ${formatBytes(compileResult.htmlBytes + compileResult.cssBytes)}`);
+  printLine(`${padLabel('DOM nodes')} ${compileResult.stats.domNodeCount}`);
+  printLine(`${padLabel('CSS rules')} ${compileResult.stats.cssRuleCount}`);
+  printLine(`${padLabel('Head entries')} ${compileResult.stats.headEntryCount}`);
+  printLine(`${padLabel('Script blocks')} ${compileResult.stats.scriptBlockCount}`);
+  printLine(`${padLabel('Duration')} ${formatDuration(durationMs)}`);
+}
+
+module.exports = {
+  executeScreenshotCommand,
+  printScreenshotHelp,
+};