@bytefaceinc/web-lang 0.1.1

package/lib/cli/commands/watch.js

@@ -0,0 +1,458 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { compileInputSource } = require('../compile-service');
+const { DEFAULT_SCREENSHOT_FORMAT, DEFAULT_VIEWPORT_HEIGHT, DEFAULT_VIEWPORT_WIDTH, renderScreenshotArtifact } = require('../screenshot-service');
+const { getWatchRuntimeSettings } = require('../watch-settings');
+const { resolveTargets } = require('../targets');
+const { SCREENSHOT_DIRECTORY_NAME } = require('../screenshot-artifacts');
+const {
+  bold,
+  color,
+  createSpinner,
+  dim,
+  displayPath,
+  formatBytes,
+  formatCompileStatsLine,
+  formatDuration,
+  formatErrorMessage,
+  formatLongDuration,
+  formatLocalTimestamp,
+  indentMultiline,
+  padLabel,
+  printCommandHeader,
+  printLine,
+  printTargetIssues,
+} = require('../shared');
+
+const WATCH_SCREENSHOT_FLAGS = new Set(['-s', '-screenshot', '--screenshot']);
+
+async function executeWatchCommand({ args }) {
+  let parsedArgs;
+
+  try {
+    parsedArgs = parseWatchArgs(args);
+  } catch (error) {
+    printLine(color(`[x] ${formatErrorMessage(error)}`, 'red'));
+    process.exitCode = 1;
+    return;
+  }
+
+  const resolution = resolveTargets([parsedArgs.target], process.cwd());
+
+  printTargetIssues(resolution.errors);
+
+  if (resolution.files.length === 0) {
+    printLine(color('[x] No WEB source found to watch.', 'red'));
+    process.exitCode = 1;
+    return;
+  }
+
+  if (resolution.files.length !== 1) {
+    printLine(color(`[x] The watch command expects exactly one WEB source, but "${parsedArgs.target}" resolved to ${resolution.files.length}.`, 'red'));
+    printLine(dim('    Use a single file path or bare file name when starting a watch session.'));
+    process.exitCode = 1;
+    return;
+  }
+
+  const session = new WatchSession({
+    inputPath: resolution.files[0],
+    screenshotEnabled: parsedArgs.screenshotEnabled,
+    workingDirectory: process.cwd(),
+    settings: getWatchRuntimeSettings(),
+  });
+
+  await session.start();
+}
+
+function printWatchHelp() {
+  printLine(color(bold('Watch Command'), 'blue'));
+  printLine('Watch one `.web` source, recompile it when the file changes, and optionally capture periodic screenshots.');
+  printLine('');
+  printLine(bold('Usage'));
+  printLine('  web watch <file.web> [-screenshot|-s]');
+  printLine('  web watch <file> [-screenshot|-s]');
+  printLine('');
+  printLine(bold('Examples'));
+  printLine('  web watch home.web');
+  printLine('  web watch home');
+  printLine('  web watch home.web -s');
+  printLine('  web watch home.web -screenshot');
+  printLine('');
+  printLine('Defaults');
+  printLine('  Recompile on source changes');
+  printLine('  Idle shutdown: after 1 hour with no recent source activity');
+  printLine('  Screenshot cadence with `-s`: initial baseline capture, then every 5 minutes');
+  printLine(`  Screenshot directory: ./${SCREENSHOT_DIRECTORY_NAME}`);
+  printLine('');
+  printLine('The watch session prints a verbose exit summary when it stops due to inactivity.');
+}
+
+function parseWatchArgs(args) {
+  if (args.length === 0) {
+    throw new Error('The watch command expects one WEB source. Example: web watch home.web -s');
+  }
+
+  const targets = [];
+  let screenshotEnabled = false;
+
+  for (const token of args) {
+    if (WATCH_SCREENSHOT_FLAGS.has(token)) {
+      screenshotEnabled = true;
+      continue;
+    }
+
+    if (token.startsWith('-')) {
+      throw new Error(`Unknown watch option "${token}". Supported flags are -screenshot and -s.`);
+    }
+
+    targets.push(token);
+  }
+
+  if (targets.length === 0) {
+    throw new Error('The watch command expects one WEB source. Example: web watch home.web -s');
+  }
+
+  if (targets.length > 1) {
+    throw new Error('The watch command currently supports watching exactly one WEB source at a time.');
+  }
+
+  return {
+    target: targets[0],
+    screenshotEnabled,
+  };
+}
+
+class WatchSession {
+  constructor(options) {
+    this.inputPath = path.resolve(options.inputPath);
+    this.workingDirectory = path.resolve(options.workingDirectory || process.cwd());
+    this.screenshotEnabled = Boolean(options.screenshotEnabled);
+    this.settings = options.settings;
+
+    this.lastActivityAt = Date.now();
+    this.startedAt = Date.now();
+    this.lastSuccessfulCompile = null;
+    this.lastFailedCompile = null;
+    this.lastScreenshotAt = null;
+    this.buildCount = 0;
+    this.failedBuildCount = 0;
+    this.screenshotCount = 0;
+    this.pendingBuildReason = null;
+    this.pendingPeriodicScreenshot = false;
+    this.needsInitialScreenshot = this.screenshotEnabled;
+    this.isCompiling = false;
+    this.isCapturingScreenshot = false;
+    this.isShuttingDown = false;
+    this.lastKnownFingerprint = readFileFingerprint(this.inputPath);
+    this.debounceTimer = null;
+    this.idleTimer = null;
+    this.screenshotTimer = null;
+    this.stopReason = null;
+    this.watchHandler = null;
+  }
+
+  async start() {
+    return new Promise((resolve) => {
+      this.resolveStop = resolve;
+
+      printCommandHeader(`Watching ${displayPath(this.inputPath)} for changes from ${displayPath(this.workingDirectory)}`);
+      printLine(dim('Outputs will update next to the source file.'));
+      printLine(dim(`Idle timeout is ${formatLongDuration(this.settings.idleTimeoutMs)} without recent source activity.`));
+
+      if (this.screenshotEnabled) {
+        printLine(dim(`Screenshots are enabled: one baseline capture, then every ${formatLongDuration(this.settings.screenshotIntervalMs)} into ${SCREENSHOT_DIRECTORY_NAME}.`));
+      } else {
+        printLine(dim('Screenshots are disabled for this watch session. Use `-s` or `-screenshot` to turn them on.'));
+      }
+
+      printLine('');
+
+      this.startWatchingSourceFile();
+      this.resetIdleTimer();
+
+      if (this.screenshotEnabled) {
+        this.startScreenshotTimer();
+      }
+
+      void this.runBuild('initial compile');
+    });
+  }
+
+  startWatchingSourceFile() {
+    this.watchHandler = (currentStats, previousStats) => {
+      const nextFingerprint = normalizeStatsFingerprint(currentStats);
+
+      if (!didFileFingerprintChange(this.lastKnownFingerprint, nextFingerprint)) {
+        return;
+      }
+
+      this.lastKnownFingerprint = nextFingerprint;
+      this.noteSourceActivity('source change detected');
+      this.scheduleBuild('source change detected');
+    };
+
+    fs.watchFile(this.inputPath, { interval: this.settings.pollIntervalMs }, this.watchHandler);
+  }
+
+  startScreenshotTimer() {
+    this.screenshotTimer = setInterval(() => {
+      this.pendingPeriodicScreenshot = true;
+      void this.flushPendingWork();
+    }, this.settings.screenshotIntervalMs);
+  }
+
+  noteSourceActivity(reason) {
+    this.lastActivityAt = Date.now();
+    this.resetIdleTimer();
+    printLine(dim(`[watch] ${reason} at ${formatLocalTimestamp(this.lastActivityAt)}.`));
+  }
+
+  resetIdleTimer() {
+    if (this.idleTimer) {
+      clearTimeout(this.idleTimer);
+    }
+
+    this.idleTimer = setTimeout(() => {
+      void this.stopDueToInactivity();
+    }, this.settings.idleTimeoutMs);
+  }
+
+  scheduleBuild(reason) {
+    this.pendingBuildReason = reason;
+
+    if (this.debounceTimer) {
+      clearTimeout(this.debounceTimer);
+    }
+
+    this.debounceTimer = setTimeout(() => {
+      this.debounceTimer = null;
+      void this.flushPendingWork();
+    }, this.settings.debounceMs);
+  }
+
+  async flushPendingWork() {
+    if (this.isShuttingDown) {
+      return;
+    }
+
+    if (this.isCompiling || this.isCapturingScreenshot) {
+      return;
+    }
+
+    if (this.pendingBuildReason) {
+      const buildReason = this.pendingBuildReason;
+      this.pendingBuildReason = null;
+      await this.runBuild(buildReason);
+      return;
+    }
+
+    if (this.pendingPeriodicScreenshot) {
+      this.pendingPeriodicScreenshot = false;
+      await this.capturePeriodicScreenshot();
+    }
+  }
+
+  async runBuild(reason) {
+    if (this.isShuttingDown) {
+      return;
+    }
+
+    this.isCompiling = true;
+    const spinner = createSpinner(`[watch] Compiling ${displayPath(this.inputPath)} (${reason})`);
+    spinner.start();
+
+    try {
+      const compileResult = await compileInputSource(this.inputPath);
+      this.buildCount += 1;
+      this.lastSuccessfulCompile = {
+        at: Date.now(),
+        result: compileResult,
+      };
+
+      spinner.succeed(
+        `[ok] ${displayPath(compileResult.inputPath)} -> ${displayPath(compileResult.htmlPath)} + ${displayPath(compileResult.cssPath)} (${formatDuration(compileResult.durationMs)})`
+      );
+      printLine(dim(`     ${formatCompileStatsLine(compileResult)}`));
+
+      if (this.screenshotEnabled && this.needsInitialScreenshot) {
+        this.needsInitialScreenshot = false;
+        await this.captureScreenshot('Initial screenshot');
+      }
+    } catch (error) {
+      this.failedBuildCount += 1;
+      this.lastFailedCompile = {
+        at: Date.now(),
+        message: formatErrorMessage(error),
+      };
+
+      spinner.fail(`[x] ${displayPath(this.inputPath)} failed`);
+      printLine(dim(indentMultiline(formatErrorMessage(error), '     ')));
+    } finally {
+      this.isCompiling = false;
+    }
+
+    await this.flushPendingWork();
+  }
+
+  async capturePeriodicScreenshot() {
+    if (this.isShuttingDown || !this.screenshotEnabled) {
+      return;
+    }
+
+    if (!this.lastSuccessfulCompile) {
+      printLine(color('[!] Skipping scheduled screenshot because no successful compile is available yet.', 'yellow'));
+      return;
+    }
+
+    await this.captureScreenshot('Scheduled screenshot');
+    await this.flushPendingWork();
+  }
+
+  async captureScreenshot(label) {
+    if (!this.lastSuccessfulCompile || this.isShuttingDown) {
+      return;
+    }
+
+    this.isCapturingScreenshot = true;
+    const spinner = createSpinner(`[watch] ${label} for ${displayPath(this.inputPath)}`);
+    spinner.start();
+
+    try {
+      const screenshotResult = await renderScreenshotArtifact({
+        inputPath: this.inputPath,
+        htmlPath: this.lastSuccessfulCompile.result.htmlPath,
+        workingDirectory: this.workingDirectory,
+        format: DEFAULT_SCREENSHOT_FORMAT,
+        viewportWidth: DEFAULT_VIEWPORT_WIDTH,
+        viewportHeight: DEFAULT_VIEWPORT_HEIGHT,
+        fullPage: true,
+      });
+
+      this.screenshotCount += 1;
+      this.lastScreenshotAt = Date.now();
+
+      spinner.succeed(`[ok] ${displayPath(screenshotResult.outputPath)} (${formatDuration(screenshotResult.durationMs)})`);
+      printLine(dim(`     ${screenshotResult.format.toUpperCase()} | full page ${screenshotResult.pageWidth} x ${screenshotResult.pageHeight} | @ 1x | ${formatBytes(screenshotResult.imageBytes)} out`));
+    } catch (error) {
+      spinner.fail('[x] Watch screenshot failed');
+      printLine(dim(indentMultiline(formatErrorMessage(error), '     ')));
+    } finally {
+      this.isCapturingScreenshot = false;
+    }
+  }
+
+  async stopDueToInactivity() {
+    if (this.isShuttingDown) {
+      return;
+    }
+
+    this.isShuttingDown = true;
+    this.stopReason = 'Stopping the watch process due to no recent source activity.';
+
+    this.cleanup();
+    this.printExitSummary();
+
+    if (this.resolveStop) {
+      this.resolveStop();
+    }
+
+    process.exitCode = this.failedBuildCount > 0 && this.buildCount === 0 ? 1 : 0;
+  }
+
+  cleanup() {
+    if (this.debounceTimer) {
+      clearTimeout(this.debounceTimer);
+      this.debounceTimer = null;
+    }
+
+    if (this.idleTimer) {
+      clearTimeout(this.idleTimer);
+      this.idleTimer = null;
+    }
+
+    if (this.screenshotTimer) {
+      clearInterval(this.screenshotTimer);
+      this.screenshotTimer = null;
+    }
+
+    if (this.watchHandler) {
+      fs.unwatchFile(this.inputPath, this.watchHandler);
+      this.watchHandler = null;
+    }
+  }
+
+  printExitSummary() {
+    printLine('');
+    printLine(color(bold('Watch Session Ended'), 'yellow'));
+    printLine(this.stopReason);
+    printLine(`No source file changes were detected for ${formatLongDuration(this.settings.idleTimeoutMs)} while watching ${displayPath(this.inputPath)}.`);
+    printLine(`Last observed source activity: ${formatLocalTimestamp(this.lastActivityAt)}.`);
+
+    if (this.lastSuccessfulCompile) {
+      printLine(`Last successful compile: ${formatLocalTimestamp(this.lastSuccessfulCompile.at)}.`);
+    } else {
+      printLine('Last successful compile: none during this watch session.');
+    }
+
+    if (this.lastFailedCompile) {
+      printLine(`Last failed compile: ${formatLocalTimestamp(this.lastFailedCompile.at)}.`);
+      printLine(dim(indentMultiline(this.lastFailedCompile.message, '    ')));
+    }
+
+    if (this.screenshotEnabled) {
+      printLine(`Screenshots captured: ${this.screenshotCount}.`);
+
+      if (this.lastScreenshotAt) {
+        printLine(`Last screenshot: ${formatLocalTimestamp(this.lastScreenshotAt)}.`);
+      } else {
+        printLine('Last screenshot: none captured during this watch session.');
+      }
+    }
+
+    printLine(`${padLabel('Successful builds')} ${this.buildCount}`);
+    printLine(`${padLabel('Failed builds')} ${this.failedBuildCount}`);
+    printLine(`${padLabel('Elapsed')} ${formatLongDuration(Date.now() - this.startedAt)}`);
+    printLine('Run the watch command again when you are ready to continue watching for updates.');
+  }
+}
+
+function readFileFingerprint(filePath) {
+  try {
+    return normalizeStatsFingerprint(fs.statSync(filePath));
+  } catch (error) {
+    return {
+      exists: false,
+      mtimeMs: 0,
+      size: 0,
+    };
+  }
+}
+
+function normalizeStatsFingerprint(stats) {
+  if (!stats || typeof stats.mtimeMs !== 'number') {
+    return {
+      exists: false,
+      mtimeMs: 0,
+      size: 0,
+    };
+  }
+
+  return {
+    exists: true,
+    mtimeMs: Number(stats.mtimeMs) || 0,
+    size: Number(stats.size) || 0,
+  };
+}
+
+function didFileFingerprintChange(previousFingerprint, nextFingerprint) {
+  return previousFingerprint.exists !== nextFingerprint.exists
+    || previousFingerprint.mtimeMs !== nextFingerprint.mtimeMs
+    || previousFingerprint.size !== nextFingerprint.size;
+}
+
+module.exports = {
+  executeWatchCommand,
+  printWatchHelp,
+};

package/lib/cli/compile-service.js

@@ -0,0 +1,19 @@
+'use strict';
+
+const path = require('path');
+const { resolveCompileOutputPaths } = require('../../compiler.js');
+const { compileFileInWorker } = require('./compiler-runner');
+
+async function compileInputSource(inputPath, options = {}) {
+  const outputPaths = resolveCompileOutputPaths(inputPath, options);
+
+  return compileFileInWorker(inputPath, {
+    htmlPath: outputPaths.htmlPath,
+    cssPath: outputPaths.cssPath,
+    stylesheetHref: path.basename(outputPaths.cssPath),
+  });
+}
+
+module.exports = {
+  compileInputSource,
+};

package/lib/cli/compile-worker.js

@@ -0,0 +1,32 @@
+'use strict';
+
+const { performance } = require('perf_hooks');
+const { parentPort, workerData } = require('worker_threads');
+const { compileFile } = require('../../compiler.js');
+
+const startedAt = performance.now();
+
+try {
+  const result = compileFile(workerData.inputPath, workerData.options);
+
+  parentPort.postMessage({
+    ok: true,
+    result: {
+      inputPath: result.inputPath,
+      htmlPath: result.htmlPath,
+      cssPath: result.cssPath,
+      sourceBytes: result.sourceBytes,
+      htmlBytes: result.htmlBytes,
+      cssBytes: result.cssBytes,
+      stats: result.stats,
+      durationMs: performance.now() - startedAt,
+    },
+  });
+} catch (error) {
+  parentPort.postMessage({
+    ok: false,
+    error: {
+      message: error instanceof Error ? error.message : String(error),
+    },
+  });
+}

package/lib/cli/compiler-runner.js

@@ -0,0 +1,37 @@
+'use strict';
+
+const path = require('path');
+const { Worker } = require('worker_threads');
+
+const COMPILE_WORKER_PATH = path.join(__dirname, 'compile-worker.js');
+
+function compileFileInWorker(inputPath, options) {
+  return new Promise((resolve, reject) => {
+    const worker = new Worker(COMPILE_WORKER_PATH, {
+      workerData: {
+        inputPath,
+        options,
+      },
+    });
+
+    worker.once('message', (message) => {
+      if (message.ok) {
+        resolve(message.result);
+        return;
+      }
+
+      reject(new Error(message.error.message));
+    });
+
+    worker.once('error', reject);
+    worker.once('exit', (code) => {
+      if (code !== 0) {
+        reject(new Error(`Compiler worker exited with code ${code}`));
+      }
+    });
+  });
+}
+
+module.exports = {
+  compileFileInWorker,
+};

package/lib/cli/index.js

@@ -0,0 +1,154 @@
+'use strict';
+
+const { executeInitCommand, printInitHelp } = require('./commands/init');
+const { executeCompileCommand, printCompileHelp } = require('./commands/compile');
+const { executeScreenshotCommand, printScreenshotHelp } = require('./commands/screenshot');
+const { executeWatchCommand, printWatchHelp } = require('./commands/watch');
+const { bold, color, printLine, readPackageVersion } = require('./shared');
+
+async function main(rawArgs = process.argv.slice(2)) {
+  const invocation = parseInvocation(rawArgs);
+
+  if (invocation.kind === 'version') {
+    printLine(readPackageVersion());
+    return;
+  }
+
+  if (invocation.kind === 'help') {
+    printHelp(invocation.topic);
+    return;
+  }
+
+  if (invocation.command === 'init') {
+    await executeInitCommand({ args: invocation.args });
+    return;
+  }
+
+  if (invocation.command === 'watch') {
+    await executeWatchCommand({ args: invocation.args });
+    return;
+  }
+
+  if (invocation.command === 'screenshot') {
+    await executeScreenshotCommand({ args: invocation.args });
+    return;
+  }
+
+  await executeCompileCommand({ args: invocation.args });
+}
+
+function parseInvocation(args) {
+  if (args.length === 0) {
+    return {
+      kind: 'command',
+      command: 'compile',
+      args: [],
+    };
+  }
+
+  const [first, ...rest] = args;
+
+  if (first === '--version' || first === '-v') {
+    return {
+      kind: 'version',
+    };
+  }
+
+  if (first === '--help' || first === '-h') {
+    return {
+      kind: 'help',
+      topic: null,
+    };
+  }
+
+  if (first === 'help') {
+    return {
+      kind: 'help',
+      topic: rest[0] || null,
+    };
+  }
+
+  if (first === 'compile' || first === 'init' || first === 'screenshot' || first === 'watch') {
+    const topic = rest.includes('--help') || rest.includes('-h') ? first : null;
+
+    if (topic) {
+      return {
+        kind: 'help',
+        topic,
+      };
+    }
+
+    return {
+      kind: 'command',
+      command: first,
+      args: rest,
+    };
+  }
+
+  if (args.includes('--help') || args.includes('-h')) {
+    return {
+      kind: 'help',
+      topic: 'compile',
+    };
+  }
+
+  return {
+    kind: 'command',
+    command: 'compile',
+    args,
+  };
+}
+
+function printHelp(topic) {
+  switch (topic) {
+    case 'compile':
+      printCompileHelp();
+      return;
+    case 'init':
+      printInitHelp();
+      return;
+    case 'screenshot':
+      printScreenshotHelp();
+      return;
+    case 'watch':
+      printWatchHelp();
+      return;
+    default:
+      printGeneralHelp();
+      return;
+  }
+}
+
+function printGeneralHelp() {
+  printLine(color(bold('WEB CLI'), 'blue'));
+  printLine('Initialize WEB projects, compile `.web` power docs, render screenshots, or keep a watch session running for live rebuilds.');
+  printLine('');
+  printLine(bold('Usage'));
+  printLine('  web init [directory]');
+  printLine('  web <file.web>');
+  printLine('  web <file>');
+  printLine('  web <directory>');
+  printLine('  web <glob>');
+  printLine('  web compile <target...>');
+  printLine('  web screenshot <file.web> [--jpg|--png] [width height [deviceScaleFactor]]');
+  printLine('  web watch <file.web> [-screenshot|-s]');
+  printLine('');
+  printLine(bold('Examples'));
+  printLine('  web init');
+  printLine('  web init .');
+  printLine('  web init website');
+  printLine('  web home.web');
+  printLine('  web home');
+  printLine('  web .');
+  printLine('  web ./code/*');
+  printLine('  web screenshot home.web');
+  printLine('  web screenshot home.web --jpg 1080 1080 2');
+  printLine('  web watch home.web');
+  printLine('  web watch home.web -s');
+  printLine('');
+  printLine('If no argument is provided and `layout.web` exists, the CLI compiles it by default.');
+}
+
+module.exports = {
+  main,
+};