@bytefaceinc/web-lang 0.1.1

package/lib/cli/init-service.js

@@ -0,0 +1,204 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { resolveCompileOutputPaths } = require('../../compiler.js');
+
+const INIT_SOURCE_FILENAME = 'index.web';
+const INIT_AGENT_GUIDE_FILENAME = 'web-lang-agents.md';
+const INIT_DOC_SEQUENCE = [
+  'getting-started.md',
+  'cli.md',
+  'compiler.md',
+];
+const BUNDLED_DOCS_DIRECTORY = path.join(__dirname, '..', '..', 'docs');
+
+function resolveInitProjectArtifacts(targetDirectory, workingDirectory) {
+  const projectRoot = resolveInitProjectRoot(targetDirectory, workingDirectory);
+  const sourcePath = path.join(projectRoot, INIT_SOURCE_FILENAME);
+  const agentGuidePath = path.join(projectRoot, INIT_AGENT_GUIDE_FILENAME);
+  const compileOutputs = resolveCompileOutputPaths(sourcePath);
+
+  return {
+    projectRoot,
+    projectRootExists: fs.existsSync(projectRoot),
+    sourcePath,
+    agentGuidePath,
+    htmlPath: compileOutputs.htmlPath,
+    cssPath: compileOutputs.cssPath,
+  };
+}
+
+function resolveInitProjectRoot(targetDirectory, workingDirectory) {
+  const baseDirectory = path.resolve(workingDirectory || process.cwd());
+  const requestedTarget = targetDirectory && targetDirectory !== '' ? targetDirectory : '.';
+  const projectRoot = path.resolve(baseDirectory, requestedTarget);
+
+  if (fs.existsSync(projectRoot) && !fs.statSync(projectRoot).isDirectory()) {
+    throw new Error(`The init target "${targetDirectory}" resolves to a file. Point \`web init\` at a directory path instead.`);
+  }
+
+  return projectRoot;
+}
+
+function listExistingInitArtifacts(artifacts) {
+  return [
+    artifacts.sourcePath,
+    artifacts.agentGuidePath,
+    artifacts.htmlPath,
+    artifacts.cssPath,
+  ].filter((artifactPath) => fs.existsSync(artifactPath));
+}
+
+function writeInitProjectFiles(artifacts) {
+  const sourceContent = createStarterIndexSource();
+  const agentGuideContent = buildAgentsContextDocument();
+
+  fs.mkdirSync(artifacts.projectRoot, { recursive: true });
+  fs.writeFileSync(artifacts.sourcePath, sourceContent, 'utf8');
+  fs.writeFileSync(artifacts.agentGuidePath, agentGuideContent, 'utf8');
+
+  return {
+    sourceContent,
+    agentGuideContent,
+    sourceBytes: Buffer.byteLength(sourceContent),
+    agentGuideBytes: Buffer.byteLength(agentGuideContent),
+    bundledDocs: [...INIT_DOC_SEQUENCE],
+  };
+}
+
+function createStarterIndexSource() {
+  return [
+    'define {',
+    '  @pageBackground = "linear-gradient(180deg, #050816 0%, #0f172a 100%)";',
+    '  @panelSurface = "rgba(15, 23, 42, 0.78)";',
+    '  @panelBorder = "1px solid rgba(148, 163, 184, 0.24)";',
+    '  @textStrong = "#f8fafc";',
+    '  @textMuted = "#cbd5e1";',
+    '  @accent = "#c084fc";',
+    '  @shadow = "0 32px 80px rgba(2, 6, 23, 0.42)";',
+    '',
+    '  Main pageMain;',
+    '  Section introBanner;',
+    '  Span introEyebrow;',
+    '  Heading1 introTitle;',
+    '  Paragraph introCopy;',
+    '}',
+    '',
+    '::head {',
+    '  meta {',
+    '    name = "description";',
+    '    content = "A starter WEB project scaffolded with web init."; ',
+    '  }',
+    '',
+    '  meta {',
+    '    name = "theme-color";',
+    '    content = "#050816";',
+    '  }',
+    '}',
+    '',
+    '* {',
+    '  boxSizing = "border-box";',
+    '}',
+    '',
+    'html {',
+    '  background = @pageBackground;',
+    '  color = @textStrong;',
+    '  fontFamily = "-apple-system, BlinkMacSystemFont, Segoe UI, Inter, Roboto, Helvetica Neue, Arial, sans-serif";',
+    '  lineHeight = 1.5;',
+    '}',
+    '',
+    'pageMain {',
+    '  minHeight = "100vh";',
+    '  display = "grid";',
+    '  placeItems = "center";',
+    '  padding = "2rem";',
+    '',
+    '  introBanner {',
+    '    width = "min(100%, 720px)";',
+    '    padding = "3rem";',
+    '    background = @panelSurface;',
+    '    border = @panelBorder;',
+    '    borderRadius = "18px";',
+    '    boxShadow = @shadow;',
+    '    display = "grid";',
+    '    gap = "1rem";',
+    '    backdropFilter = "blur(16px)";',
+    '',
+    '    introEyebrow {',
+    '      textContent = "WELCOME TO WEB";',
+    '      display = "inline-flex";',
+    '      width = "fit-content";',
+    '      padding = "0.45rem 0.75rem";',
+    '      border = @panelBorder;',
+    '      borderRadius = "999px";',
+    '      background = "rgba(192, 132, 252, 0.12)";',
+    '      color = @accent;',
+    '      fontSize = "0.78rem";',
+    '      fontWeight = 700;',
+    '      letterSpacing = "0.08em";',
+    '      textTransform = "uppercase";',
+    '    }',
+    '',
+    '    introTitle {',
+    '      textContent = "Start building with one .web file."; ',
+    '      margin = "0";',
+    '      fontSize = "clamp(2.75rem, 8vw, 4.5rem)";',
+    '      lineHeight = 1.04;',
+    '      letterSpacing = "-0.04em";',
+    '    }',
+    '',
+    '    introCopy {',
+    '      textContent = "Compile to standard HTML and CSS, keep web-lang-agents.md nearby for local agent context, and expand this starter into your first WEB page."; ',
+    '      margin = "0";',
+    '      maxWidth = "58ch";',
+    '      color = @textMuted;',
+    '      fontSize = "1.05rem";',
+    '      lineHeight = 1.65;',
+    '    }',
+    '  }',
+    '}',
+  ].join('\n');
+}
+
+function buildAgentsContextDocument() {
+  const docSections = INIT_DOC_SEQUENCE.map((fileName) => {
+    const content = readBundledDoc(fileName).trim();
+    return `<!-- Source: docs/${fileName} -->\n\n${content}`;
+  });
+
+  return [
+    '# WEB Lang Agent Context',
+    '',
+    'Generated by `web init` so local agents have the current packaged WEB getting-started guide, CLI guide, and compiler reference in one local document.',
+    '',
+    'Bundled in this order: `getting-started.md`, `cli.md`, `compiler.md`.',
+    '',
+    '---',
+    '',
+    docSections.join('\n\n---\n\n'),
+    '',
+  ].join('\n');
+}
+
+function readBundledDoc(fileName) {
+  const docPath = path.join(BUNDLED_DOCS_DIRECTORY, fileName);
+
+  try {
+    return fs.readFileSync(docPath, 'utf8');
+  } catch (error) {
+    throw new Error(`The init command could not read the bundled doc "${fileName}" from ${docPath}.`);
+  }
+}
+
+module.exports = {
+  INIT_AGENT_GUIDE_FILENAME,
+  INIT_DOC_SEQUENCE,
+  INIT_SOURCE_FILENAME,
+  buildAgentsContextDocument,
+  createStarterIndexSource,
+  listExistingInitArtifacts,
+  resolveInitProjectArtifacts,
+  resolveInitProjectRoot,
+  writeInitProjectFiles,
+};

package/lib/cli/screenshot-artifacts.js

@@ -0,0 +1,81 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const SCREENSHOT_DIRECTORY_NAME = 'web-lang-screenshots';
+
+function resolveScreenshotArtifactPaths(inputPath, format, workingDirectory = process.cwd(), capturedAt = new Date()) {
+  const resolvedInputPath = path.resolve(inputPath);
+  const resolvedWorkingDirectory = path.resolve(workingDirectory);
+  const screenshotsRoot = path.join(resolvedWorkingDirectory, SCREENSHOT_DIRECTORY_NAME);
+  const relativeInputDirectory = path.relative(resolvedWorkingDirectory, path.dirname(resolvedInputPath));
+  const outputDirectory = isPathInsideWorkingDirectory(relativeInputDirectory)
+    ? path.join(screenshotsRoot, relativeInputDirectory)
+    : screenshotsRoot;
+  const fileBaseName = path.basename(resolvedInputPath, path.extname(resolvedInputPath));
+  const timestampLabel = formatScreenshotTimestamp(capturedAt);
+
+  return {
+    screenshotsRoot,
+    outputDirectory,
+    timestampLabel,
+    outputPath: resolveUniqueTimestampedScreenshotPath(outputDirectory, fileBaseName, timestampLabel, format),
+  };
+}
+
+function ensureScreenshotOutputDirectory(directoryPath) {
+  fs.mkdirSync(directoryPath, { recursive: true });
+}
+
+function isPathInsideWorkingDirectory(relativePath) {
+  if (!relativePath || relativePath === '.') {
+    return false;
+  }
+
+  if (path.isAbsolute(relativePath)) {
+    return false;
+  }
+
+  return !relativePath.startsWith('..');
+}
+
+function resolveUniqueTimestampedScreenshotPath(outputDirectory, fileBaseName, timestampLabel, format) {
+  const baseFileName = `${fileBaseName}-${timestampLabel}`;
+  let suffix = 0;
+
+  while (true) {
+    const candidateName = suffix === 0
+      ? `${baseFileName}.${format}`
+      : `${baseFileName}-${String(suffix + 1).padStart(2, '0')}.${format}`;
+    const candidatePath = path.join(outputDirectory, candidateName);
+
+    if (!fs.existsSync(candidatePath)) {
+      return candidatePath;
+    }
+
+    suffix += 1;
+  }
+}
+
+function formatScreenshotTimestamp(value) {
+  const date = value instanceof Date ? value : new Date(value);
+
+  return [
+    date.getFullYear(),
+    String(date.getMonth() + 1).padStart(2, '0'),
+    String(date.getDate()).padStart(2, '0'),
+  ].join('-') + '_' + [
+    String(date.getHours()).padStart(2, '0'),
+    String(date.getMinutes()).padStart(2, '0'),
+    String(date.getSeconds()).padStart(2, '0'),
+    String(date.getMilliseconds()).padStart(3, '0'),
+  ].join('-');
+}
+
+module.exports = {
+  SCREENSHOT_DIRECTORY_NAME,
+  ensureScreenshotOutputDirectory,
+  formatScreenshotTimestamp,
+  resolveScreenshotArtifactPaths,
+};

package/lib/cli/screenshot-service.js

@@ -0,0 +1,153 @@
+'use strict';
+
+const fs = require('fs');
+const { performance } = require('perf_hooks');
+const { pathToFileURL } = require('url');
+const {
+  ensureScreenshotOutputDirectory,
+  resolveScreenshotArtifactPaths,
+} = require('./screenshot-artifacts');
+
+const DEFAULT_SCREENSHOT_FORMAT = 'jpg';
+const DEFAULT_VIEWPORT_WIDTH = 1600;
+const DEFAULT_VIEWPORT_HEIGHT = 900;
+const DEFAULT_DEVICE_SCALE_FACTOR = 1;
+const SCREENSHOT_LOAD_TIMEOUT_MS = 15000;
+const JPEG_QUALITY = 90;
+
+async function renderScreenshotArtifact(options) {
+  const artifacts = resolveScreenshotArtifactPaths(
+    options.inputPath,
+    options.format || DEFAULT_SCREENSHOT_FORMAT,
+    options.workingDirectory || process.cwd(),
+    options.capturedAt
+  );
+
+  ensureScreenshotOutputDirectory(artifacts.outputDirectory);
+
+  const screenshotResult = await captureScreenshot({
+    htmlPath: options.htmlPath,
+    outputPath: artifacts.outputPath,
+    format: options.format || DEFAULT_SCREENSHOT_FORMAT,
+    viewportWidth: options.viewportWidth || DEFAULT_VIEWPORT_WIDTH,
+    viewportHeight: options.viewportHeight || DEFAULT_VIEWPORT_HEIGHT,
+    deviceScaleFactor: options.deviceScaleFactor || DEFAULT_DEVICE_SCALE_FACTOR,
+    fullPage: options.fullPage !== false,
+  });
+
+  return {
+    ...artifacts,
+    ...screenshotResult,
+  };
+}
+
+async function captureScreenshot(options) {
+  const puppeteer = loadPuppeteer();
+  const startedAt = performance.now();
+  let browser = null;
+
+  try {
+    browser = await puppeteer.launch({
+      headless: true,
+    });
+
+    const page = await browser.newPage();
+
+    await page.setViewport({
+      width: options.viewportWidth,
+      height: options.viewportHeight,
+      deviceScaleFactor: options.deviceScaleFactor,
+    });
+
+    await page.emulateMediaType('screen');
+    await page.goto(pathToFileURL(options.htmlPath).href, {
+      waitUntil: 'load',
+      timeout: SCREENSHOT_LOAD_TIMEOUT_MS,
+    });
+    await waitForPageToSettle(page);
+
+    const pageMetrics = await page.evaluate(() => {
+      const doc = document.documentElement;
+      const body = document.body || doc;
+
+      return {
+        pageWidth: Math.max(doc.scrollWidth, body.scrollWidth, doc.clientWidth, window.innerWidth),
+        pageHeight: Math.max(doc.scrollHeight, body.scrollHeight, doc.clientHeight, window.innerHeight),
+      };
+    });
+
+    const screenshotOptions = {
+      path: options.outputPath,
+      type: options.format === 'png' ? 'png' : 'jpeg',
+      fullPage: options.fullPage,
+    };
+
+    if (screenshotOptions.type === 'jpeg') {
+      screenshotOptions.quality = JPEG_QUALITY;
+    }
+
+    await page.screenshot(screenshotOptions);
+    const imageBytes = fs.statSync(options.outputPath).size;
+
+    return {
+      outputPath: options.outputPath,
+      format: options.format,
+      fullPage: options.fullPage,
+      viewportWidth: options.viewportWidth,
+      viewportHeight: options.viewportHeight,
+      deviceScaleFactor: options.deviceScaleFactor,
+      pageWidth: pageMetrics.pageWidth,
+      pageHeight: pageMetrics.pageHeight,
+      imageBytes,
+      durationMs: performance.now() - startedAt,
+    };
+  } finally {
+    if (browser) {
+      await browser.close();
+    }
+  }
+}
+
+function loadPuppeteer() {
+  try {
+    return require('puppeteer');
+  } catch (error) {
+    if (error && error.code === 'MODULE_NOT_FOUND') {
+      throw new Error('The screenshot command requires the `puppeteer` dependency. Run `npm install` in the `web-lang` package before using `web screenshot` or `web watch -s`.');
+    }
+
+    throw error;
+  }
+}
+
+async function waitForPageToSettle(page) {
+  if (typeof page.waitForNetworkIdle === 'function') {
+    try {
+      await page.waitForNetworkIdle({
+        idleTime: 250,
+        timeout: 1500,
+      });
+    } catch (error) {
+      // Some pages may keep network activity alive; continue with the last rendered state.
+    }
+  }
+
+  await page.evaluate(() => {
+    const afterFonts = document.fonts && document.fonts.ready
+      ? document.fonts.ready.catch(() => undefined)
+      : Promise.resolve();
+
+    return afterFonts.then(() => new Promise((resolve) => {
+      requestAnimationFrame(() => requestAnimationFrame(resolve));
+    }));
+  });
+}
+
+module.exports = {
+  DEFAULT_DEVICE_SCALE_FACTOR,
+  DEFAULT_SCREENSHOT_FORMAT,
+  DEFAULT_VIEWPORT_HEIGHT,
+  DEFAULT_VIEWPORT_WIDTH,
+  captureScreenshot,
+  renderScreenshotArtifact,
+};

package/lib/cli/shared.js

@@ -0,0 +1,261 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const PACKAGE_JSON_PATH = path.join(__dirname, '..', '..', 'package.json');
+const SPINNER_FRAMES = ['-', '\\', '|', '/'];
+const ANSI = {
+  reset: '\u001b[0m',
+  bold: '\u001b[1m',
+  dim: '\u001b[2m',
+  red: '\u001b[31m',
+  green: '\u001b[32m',
+  yellow: '\u001b[33m',
+  blue: '\u001b[34m',
+  cyan: '\u001b[36m',
+  gray: '\u001b[90m',
+};
+
+function readPackageVersion() {
+  try {
+    const packageJson = JSON.parse(fs.readFileSync(PACKAGE_JSON_PATH, 'utf8'));
+    return packageJson.version || '0.1.0';
+  } catch (error) {
+    return '0.1.0';
+  }
+}
+
+function displayPath(targetPath) {
+  const relativePath = path.relative(process.cwd(), targetPath);
+
+  if (!relativePath || relativePath === '') {
+    return '.';
+  }
+
+  if (!relativePath.startsWith('..')) {
+    return relativePath;
+  }
+
+  return targetPath;
+}
+
+function formatBytes(byteCount) {
+  if (byteCount < 1024) {
+    return `${byteCount} B`;
+  }
+
+  if (byteCount < 1024 * 1024) {
+    return `${(byteCount / 1024).toFixed(1)} KB`;
+  }
+
+  return `${(byteCount / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+function formatDuration(durationMs) {
+  if (durationMs < 1000) {
+    return `${Math.max(1, Math.round(durationMs))} ms`;
+  }
+
+  return `${(durationMs / 1000).toFixed(2)} s`;
+}
+
+function formatLongDuration(durationMs) {
+  const totalSeconds = Math.max(0, Math.round(durationMs / 1000));
+  const hours = Math.floor(totalSeconds / 3600);
+  const minutes = Math.floor((totalSeconds % 3600) / 60);
+  const seconds = totalSeconds % 60;
+  const parts = [];
+
+  if (hours > 0) {
+    parts.push(`${hours}h`);
+  }
+
+  if (hours > 0 || minutes > 0) {
+    parts.push(`${minutes}m`);
+  }
+
+  parts.push(`${seconds}s`);
+
+  return parts.join(' ');
+}
+
+function formatLocalTimestamp(value) {
+  const date = value instanceof Date ? value : new Date(value);
+
+  return [
+    date.getFullYear(),
+    String(date.getMonth() + 1).padStart(2, '0'),
+    String(date.getDate()).padStart(2, '0'),
+  ].join('-') + ' ' + [
+    String(date.getHours()).padStart(2, '0'),
+    String(date.getMinutes()).padStart(2, '0'),
+    String(date.getSeconds()).padStart(2, '0'),
+  ].join(':');
+}
+
+function formatErrorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function indentMultiline(text, prefix) {
+  return String(text)
+    .split('\n')
+    .map((line) => `${prefix}${line}`)
+    .join('\n');
+}
+
+function createSpinner(label) {
+  const interactive = process.stdout.isTTY;
+  let frameIndex = 0;
+  let intervalId = null;
+
+  return {
+    start() {
+      if (!interactive) {
+        printLine(dim(label));
+        return;
+      }
+
+      renderFrame();
+      intervalId = setInterval(() => {
+        frameIndex = (frameIndex + 1) % SPINNER_FRAMES.length;
+        renderFrame();
+      }, 80);
+    },
+    succeed(message) {
+      stop();
+
+      if (interactive) {
+        clearCurrentLine();
+      }
+
+      printLine(color(message, 'green'));
+    },
+    fail(message) {
+      stop();
+
+      if (interactive) {
+        clearCurrentLine();
+      }
+
+      printLine(color(message, 'red'));
+    },
+  };
+
+  function stop() {
+    if (intervalId !== null) {
+      clearInterval(intervalId);
+      intervalId = null;
+    }
+  }
+
+  function renderFrame() {
+    process.stdout.write(`\r${color(SPINNER_FRAMES[frameIndex], 'cyan')} ${label}`);
+  }
+}
+
+function clearCurrentLine() {
+  process.stdout.write('\r');
+  process.stdout.write('\u001b[2K');
+}
+
+function printCommandHeader(subtitle) {
+  const version = readPackageVersion();
+  printLine(color(`${bold('WEB CLI')} ${dim(`v${version}`)}`, 'blue'));
+  printLine(dim(subtitle));
+  printLine('');
+}
+
+function printTargetIssues(errors) {
+  if (errors.length === 0) {
+    return;
+  }
+
+  printLine(color(bold('Target issues'), 'yellow'));
+
+  for (const error of errors) {
+    printLine(color(`[!] ${error}`, 'yellow'));
+  }
+
+  printLine('');
+}
+
+function formatCompileStatsLine(result) {
+  return `${result.stats.domNodeCount} DOM nodes | ${result.stats.cssRuleCount} CSS rules | ${result.stats.headEntryCount} head entries | ${result.stats.scriptBlockCount} script blocks | ${formatBytes(result.sourceBytes)} in | ${formatBytes(result.htmlBytes + result.cssBytes)} out`;
+}
+
+function printUnexpectedCliError(error) {
+  const message = formatErrorMessage(error);
+  const [firstLine, ...rest] = message.split('\n');
+
+  printLine(color(`[x] ${firstLine}`, 'red'));
+
+  if (rest.length > 0) {
+    printLine(dim(indentMultiline(rest.join('\n'), '    ')));
+  }
+}
+
+function pluralize(count, noun) {
+  return `${count} ${noun}${count === 1 ? '' : 's'}`;
+}
+
+function padLabel(label) {
+  return `${label}:`.padEnd(17, ' ');
+}
+
+function sum(values, iteratee) {
+  return values.reduce((total, value) => total + iteratee(value), 0);
+}
+
+function printLine(value) {
+  process.stdout.write(`${value}\n`);
+}
+
+function bold(value) {
+  return color(value, 'bold');
+}
+
+function dim(value) {
+  return color(value, 'dim');
+}
+
+function color(value, ...styles) {
+  if (!supportsColor()) {
+    return String(value);
+  }
+
+  const prefix = styles.map((style) => ANSI[style] || '').join('');
+  return `${prefix}${value}${ANSI.reset}`;
+}
+
+function supportsColor() {
+  if (process.env.FORCE_COLOR === '0' || process.env.NO_COLOR === '1') {
+    return false;
+  }
+
+  return process.stdout.isTTY;
+}
+
+module.exports = {
+  bold,
+  color,
+  createSpinner,
+  dim,
+  displayPath,
+  formatBytes,
+  formatCompileStatsLine,
+  formatDuration,
+  formatErrorMessage,
+  formatLocalTimestamp,
+  formatLongDuration,
+  indentMultiline,
+  padLabel,
+  pluralize,
+  printCommandHeader,
+  printLine,
+  printTargetIssues,
+  printUnexpectedCliError,
+  readPackageVersion,
+  sum,
+};