@bytefaceinc/web-lang 0.1.1

package/docs/cli.md

@@ -0,0 +1,657 @@
+# WEB CLI
+
+The WEB CLI has four jobs:
+
+- initialize a new WEB project in the current directory or one target directory
+- compile `.web` source files into matching HTML and CSS files
+- render a compiled `.web` page to a screenshot image
+- watch one `.web` source and rebuild it automatically on change
+
+The command is exposed as:
+
+```bash
+web
+```
+
+This package exposes the CLI binary from `bin/web.js`.
+
+## Quick Start
+
+Initialize a starter project in a clean directory:
+
+```bash
+web init
+```
+
+Initialize the current directory explicitly:
+
+```bash
+web init .
+```
+
+Initialize a new `website` folder and create it if it does not exist yet:
+
+```bash
+web init website
+```
+
+Compile a single file:
+
+```bash
+web home.web
+```
+
+Compile the same file without writing the extension:
+
+```bash
+web home
+```
+
+Compile every `.web` file in the current directory:
+
+```bash
+web .
+```
+
+Compile matching files from another directory:
+
+```bash
+web ./code/*
+```
+
+Render a screenshot using the default full-page mode:
+
+```bash
+web screenshot home.web
+```
+
+Render a JPG at a specific viewport size and device scale factor:
+
+```bash
+web screenshot home.web --jpg 1080 1080 2
+```
+
+Watch a file and recompile it automatically:
+
+```bash
+web watch home.web
+```
+
+Watch a file and capture a baseline screenshot plus timed snapshots every 5 minutes:
+
+```bash
+web watch home.web -s
+```
+
+If no argument is provided and `layout.web` exists in the current working directory, the CLI compiles `layout.web` automatically.
+
+When `web init` runs, the CLI also creates `web-lang-agents.md` in the chosen project root by combining `getting-started.md`, `cli.md`, and `compiler.md` in that order. The goal is to give local agents one up-to-date context document to load quickly.
+
+## Installation and Invocation
+
+From this repo, the command is registered in `package.json` as:
+
+```json
+{
+  "bin": {
+    "web": "./bin/web.js"
+  }
+}
+```
+
+Common ways to run it during development:
+
+```bash
+node bin/web.js init
+```
+
+```bash
+node bin/web.js init website
+```
+
+```bash
+npm link
+web init
+```
+
+```bash
+npm link
+web init website
+```
+
+```bash
+node bin/web.js home.web
+```
+
+```bash
+npm link
+web home.web
+```
+
+```bash
+npm link
+web screenshot home.web
+```
+
+```bash
+npm link
+web watch home.web -s
+```
+
+## Commands
+
+### 1. Init
+
+The init command scaffolds a starter WEB project in the current working directory or in one target directory, generates a local agent context document, and compiles the starter page immediately.
+
+Basic form:
+
+```bash
+web init
+```
+
+```bash
+web init .
+```
+
+```bash
+web init website
+```
+
+Behavior:
+
+- Uses the current working directory when you omit the target.
+- Accepts one directory target such as `.` or `website`.
+- Creates the target directory automatically when it does not exist yet.
+- Creates `index.web` with a simple intro banner.
+- Creates `web-lang-agents.md` by combining `getting-started.md`, `cli.md`, and `compiler.md` from the packaged docs.
+- Compiles the starter page into `index.html` and `index.css`.
+- Refuses to overwrite existing `index.web`, `index.html`, `index.css`, or `web-lang-agents.md` files in the target directory.
+
+Example:
+
+```bash
+web init .
+```
+
+```bash
+web init website
+```
+
+Notes:
+
+- Run `web init` against a clean target directory.
+- The generated `web-lang-agents.md` is meant for local agent context, not browser output.
+- After `web init`, you can keep working in `index.web` or replace it with your own page structure.
+- If the target directory already exists, WEB scaffolds inside it instead of creating a nested project name automatically.
+
+### 2. Compile
+
+These forms all route through the compile command even when you do not write `compile` explicitly.
+
+The following are equivalent:
+
+```bash
+web home.web
+```
+
+```bash
+web compile home.web
+```
+
+### 3. Screenshot
+
+The screenshot command compiles one `.web` source, writes the matching HTML and CSS outputs, then opens the compiled HTML in a headless browser and captures an image.
+
+Basic form:
+
+```bash
+web screenshot home.web
+```
+
+Explicit JPG viewport capture:
+
+```bash
+web screenshot home.web --jpg 1080 1080 2
+```
+
+Syntax:
+
+```bash
+web screenshot <source> [--jpg|--png] [width height [deviceScaleFactor]]
+```
+
+Behavior:
+
+- Accepts one resolved `.web` source at a time.
+- Uses the same file and bare-name resolution rules as the compile command.
+- Writes `home.html` and `home.css` next to the source file.
+- Writes the screenshot image into `./web-lang-screenshots` rooted at the current working directory.
+- Creates `./web-lang-screenshots` automatically when it does not exist yet.
+- Appends a human-readable local timestamp to each screenshot filename.
+- Uses `jpg` by default.
+- If no width and height are provided, the command uses a `1600px` wide viewport, keeps the default device scale factor of `1`, and captures the full page.
+- If width and height are provided, the command captures the current viewport instead of forcing `fullPage`.
+
+Examples:
+
+```bash
+web screenshot home
+```
+
+```bash
+web screenshot home.web --png 1440 900
+```
+
+```bash
+web screenshot home.web --jpg 1080 1080 2
+```
+
+Notes:
+
+- The first numeric argument is the viewport width.
+- The second numeric argument is the viewport height.
+- The optional third numeric argument is the browser `deviceScaleFactor`.
+- A higher `deviceScaleFactor` produces a sharper image with more output pixels.
+
+### 4. Watch
+
+The watch command watches one resolved `.web` source, recompiles it when the source changes, and stays alive until the session is idle long enough to shut itself down.
+
+Basic form:
+
+```bash
+web watch home.web
+```
+
+Watch with timed screenshots:
+
+```bash
+web watch home.web -s
+```
+
+Syntax:
+
+```bash
+web watch <source> [-screenshot|-s]
+```
+
+Behavior:
+
+- Accepts exactly one resolved `.web` source.
+- Uses the same file and bare-name resolution rules as the compile command.
+- Performs an initial compile when the watch session starts.
+- Recompiles the source whenever the watched file changes.
+- Stops automatically after 1 hour with no recent source activity.
+- Prints a verbose exit summary explaining why the watch session ended.
+- With `-s` or `-screenshot`, captures one baseline screenshot after the first successful compile and then keeps capturing snapshots every 5 minutes.
+- Uses the same `./web-lang-screenshots` workspace and timestamped filename pattern as `web screenshot`.
+
+Examples:
+
+```bash
+web watch home
+```
+
+```bash
+web watch home.web
+```
+
+```bash
+web watch home.web -s
+```
+
+```bash
+web watch home.web -screenshot
+```
+
+Notes:
+
+- Watch mode currently supports one source file at a time.
+- Periodic screenshots do not reset the idle timer.
+- If the source file keeps changing, the watch session stays alive and keeps rebuilding.
+
+## Compile Target Forms
+
+### 1. Compile one explicit file
+
+```bash
+web landing.web
+```
+
+Behavior:
+
+- Resolves the path relative to the current working directory.
+- Accepts only files ending in `.web`.
+- Writes outputs next to the source file.
+
+Example result:
+
+- `landing.web` -> `landing.html`
+- `landing.web` -> `landing.css`
+
+### 2. Compile one file by bare name
+
+```bash
+web landing
+```
+
+Behavior:
+
+- If `landing.web` exists in the current working directory, it is used.
+- This convenience only applies when the target has no extension.
+- If the file does not exist, the CLI reports a target issue.
+
+### 3. Compile a directory
+
+```bash
+web .
+```
+
+Behavior:
+
+- Compiles direct `.web` files in that directory.
+- Does not recurse into nested folders.
+- Ignores non-`.web` files.
+
+Example:
+
+```text
+project/
+  home.web
+  about.web
+  notes.txt
+  code/
+    contact.web
+```
+
+`web .` compiles:
+
+- `home.web`
+- `about.web`
+
+It does not compile:
+
+- `notes.txt`
+- `code/contact.web`
+
+### 4. Compile a glob
+
+```bash
+web ./code/*
+```
+
+Behavior:
+
+- Supports `*`, `?`, and character ranges like `[ab]`.
+- Matches are resolved relative to the current working directory.
+- Matching directories are expanded into direct `.web` files inside them.
+- Matching files are compiled only if they end in `.web`.
+
+Notes:
+
+- In shells like `zsh`, the shell may expand the glob before the CLI receives it. That still works.
+- If the shell does not expand the glob, the CLI expands it itself.
+
+## Output Rules
+
+The compile command writes outputs next to each source file using the same base name.
+
+Examples:
+
+- `home.web` -> `home.html` and `home.css`
+- `pages/about.web` -> `pages/about.html` and `pages/about.css`
+- `src/marketing/hero.web` -> `src/marketing/hero.html` and `src/marketing/hero.css`
+
+The generated HTML links to the matching CSS filename for that source file.
+
+The screenshot command writes image artifacts into a dedicated screenshot workspace rooted at the current working directory.
+
+Examples:
+
+- `home.web` -> `web-lang-screenshots/home-YYYY-MM-DD_HH-mm-ss-SSS.jpg`
+- `home.web` with `--png` -> `web-lang-screenshots/home-YYYY-MM-DD_HH-mm-ss-SSS.png`
+- `pages/about.web` -> `web-lang-screenshots/pages/about-YYYY-MM-DD_HH-mm-ss-SSS.jpg`
+
+The command still writes `home.html` and `home.css` first, because the screenshot is taken from the compiled page.
+
+When the source file lives inside the current working directory, the CLI preserves its relative folder structure inside `web-lang-screenshots` to avoid filename collisions.
+If two captures happen with the same timestamp label, the CLI adds a numeric suffix instead of overwriting the earlier image.
+
+The watch command uses the same screenshot workspace and filename pattern when `-s` or `-screenshot` is enabled.
+
+## User Experience
+
+### Header
+
+At startup, the CLI prints a header with:
+
+- the CLI name
+- the current version
+- the number of WEB sources being compiled
+- the current working directory
+
+### Progress display
+
+For each compile step, the CLI shows progress like:
+
+```text
+[1/3] Compiling home.web
+```
+
+When stdout is attached to a TTY, this line is animated with a spinner while compilation is running.
+
+When stdout is not a TTY, the CLI prints static progress lines instead of animation. This makes logs and CI output cleaner.
+
+### Per-step success line
+
+On success, the compile flow prints:
+
+- input file
+- output HTML path
+- output CSS path
+- compile duration
+
+It also prints per-file stats:
+
+- DOM node count
+- CSS rule count
+- head entry count
+- script block count
+- source size
+- total output size
+
+The screenshot flow adds a second render step and prints:
+
+- screenshot image path
+- render duration
+- format
+- viewport or full-page mode
+- device scale factor
+- image size in bytes
+
+The watch flow prints:
+
+- an initial watch header describing the watched file, idle timeout, and screenshot mode
+- a compile step each time the watched file changes
+- a screenshot step when the baseline capture or periodic snapshots run
+- a verbose exit block when the session stops because there was no recent source activity
+
+### Summary block
+
+After the compile command finishes, the CLI prints totals for:
+
+- succeeded files
+- failed files
+- skipped targets
+- total source bytes
+- total output bytes
+- total DOM nodes
+- total CSS rules
+- total head entries
+- total script blocks
+- total duration
+
+After the screenshot command finishes, the CLI prints a focused summary for the single capture:
+
+- source path
+- generated HTML path
+- generated CSS path
+- image path
+- image format
+- capture mode
+- viewport size and device scale factor
+- measured page size
+- image bytes
+- compile stats
+- total duration
+
+After the watch command finishes because of inactivity, the CLI prints:
+
+- the shutdown reason
+- the watched source
+- the idle threshold that was reached
+- the last observed source activity time
+- the last successful compile time
+- the last failed compile details, when present
+- the number of successful builds
+- the number of failed builds
+- the number of screenshots captured, when screenshot mode was enabled
+- the total elapsed watch-session time
+
+## Help and Version
+
+Show usage help:
+
+```bash
+web --help
+```
+
+or
+
+```bash
+web -h
+```
+
+Show the CLI version:
+
+```bash
+web --version
+```
+
+or
+
+```bash
+web -v
+```
+
+Show command-specific help:
+
+```bash
+web init --help
+```
+
+```bash
+web screenshot --help
+```
+
+```bash
+web compile --help
+```
+
+```bash
+web watch --help
+```
+
+## Exit Behavior
+
+The CLI exits with code `0` when all requested targets resolve cleanly and all compiles succeed.
+
+The CLI exits with code `1` when:
+
+- no input targets are available
+- init arguments are invalid
+- an init target resolves to a file instead of a directory
+- init would overwrite existing scaffold files
+- one or more targets cannot be resolved
+- one or more compiles fail
+- screenshot arguments are invalid
+- screenshot rendering fails
+- watch arguments are invalid
+- an unexpected runtime error occurs
+
+The watch command exits with code `0` when it stops normally due to inactivity after at least one successful build.
+
+The watch command exits with code `1` when it never produces a successful build before the session ends.
+
+## Target Resolution Details
+
+Targets are collected, normalized, and deduplicated before compilation.
+
+This means:
+
+- passing the same file more than once still compiles it once
+- files from multiple targets are merged into one compile set
+- final compile order is sorted by path
+
+For `web screenshot`, the resolved target set must contain exactly one `.web` source. If a glob or directory resolves to more than one file, the CLI stops and explains the mismatch instead of guessing.
+
+For `web watch`, the resolved target set must also contain exactly one `.web` source.
+
+Example:
+
+```bash
+web home.web . ./pages/*
+```
+
+If `home.web` is also included by `.` or `./pages/*`, it will still only compile once.
+
+## Error Reporting
+
+The CLI distinguishes between two kinds of problems:
+
+### Target issues
+
+These happen before compilation starts.
+
+Examples:
+
+- a path does not exist
+- a glob matches no `.web` files
+- a directory contains no `.web` files
+
+These are reported under a `Target issues` section and count toward `Skipped` in the summary.
+
+### Compile failures
+
+These happen after a `.web` file is selected for compilation.
+
+Examples:
+
+- syntax errors
+- semantic errors from the compiler
+- unexpected worker failures
+
+These are reported per file and count toward `Failed` in the summary.
+
+## Relationship to `node compiler.js`
+
+The CLI and the legacy script mode are intentionally different:
+
+- `node compiler.js` reads `layout.web` and writes `index.html` plus `styles.css`
+- `web home.web` reads `home.web` and writes `home.html` plus `home.css`
+
+Use the CLI when you want arbitrary `.web` filenames or multi-file compilation.
+
+## Current Limitations
+
+The current CLI behavior is intentionally simple:
+
+- `web init` accepts at most one directory target
+- directory compilation is not recursive
+- there are no custom output directory flags yet
+- watch mode supports one `.web` source at a time
+- watch screenshots always use the default screenshot render settings
+- there are no quiet or JSON output modes yet
+
+If those features are added later, this document should be updated alongside `bin/web.js`.