@iyulab/canopy-page 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -7,6 +7,16 @@ Notable changes to canopy-page. The format follows
 The `settings.json` contract is what consuming projects plan their upgrades around, so changes
 to it — its fields, its validation, and what the checks reject — are what this file is about.
 
+## [0.10.0] — 2026-08-11
+
+### Added
+
+- **New `watch` command.** `canopy-page watch [site-dir] [-o out] [--port n]` builds once, then
+  rebuilds on every source change and serves the result on `http://localhost:<port>/` (default
+  `8080`, refused if already taken rather than silently moved). A failed rebuild is reported on
+  the console and leaves the last successful build being served — the process itself never exits
+  on a broken save.
+
 ## [0.9.0] — 2026-08-11
 
 ### Added

package/README.md

@@ -60,6 +60,7 @@ Node 22 or newer.
 npx canopy-page init docs/site     # write a settings file (and a home page, if needed)
 npx canopy-page check docs/site    # report anything broken, without building
 npx canopy-page build docs/site -o dist/help
+npx canopy-page watch docs/site       # rebuild on change, serve it locally
 ```
 
 `init` never replaces a settings file that is already there, and writes no page into a folder
@@ -75,6 +76,7 @@ fail. Both leave with a non-zero exit code when they do, which is all a pipeline
 | `canopy-page init [site-dir]` | Write a settings file naming the site after its folder |
 | `canopy-page check [site-dir]` | Check settings and references; build nothing |
 | `canopy-page build [site-dir] [-o out]` | Check, then publish to `out` (default `./site`) |
+| `canopy-page watch [site-dir] [-o out] [--port n]` | Build, then rebuild on change and serve it locally (default port `8080`) |
 
 `[site-dir]` is the folder holding `settings.json`, and defaults to the current one.
 

package/dist/cli-args.d.ts

@@ -12,6 +12,12 @@ export type ParsedArgs = {
     command: "build";
     dir: string;
     out: string;
+} | {
+    ok: true;
+    command: "watch";
+    dir: string;
+    out: string;
+    port: number;
 } | {
     ok: true;
     command: "check" | "init";

package/dist/cli-args.js

@@ -12,16 +12,19 @@ export const USAGE = [
     "  init  [site-dir]           Start a site: write a settings file",
     "  check [site-dir]           Check the site without publishing it",
     "  build [site-dir]           Check the site, then publish it",
+    "  watch [site-dir]           Build, then rebuild on change and serve it",
     "",
     "  [site-dir]                 Folder holding settings.json (defaults to .)",
-    "  -o, --out <dir>            Where build writes the site (defaults to ./site)",
+    "  -o, --out <dir>            Where build/watch writes the site (defaults to ./site)",
+    "  --port <n>                 Port watch serves on (defaults to 8080)",
 ].join("\n");
 const OUT_FLAGS = new Set(["-o", "--out"]);
+const PORT_FLAGS = new Set(["--port"]);
 export function parseArgs(argv) {
     const [command, ...rest] = argv;
     if (command === undefined)
         return { ok: false, error: USAGE };
-    if (command === "build" || command === "check" || command === "init") {
+    if (command === "build" || command === "check" || command === "init" || command === "watch") {
         return parseCommand(command, rest);
     }
     if (command.startsWith("-")) {
@@ -31,18 +34,30 @@ export function parseArgs(argv) {
     }
     return { ok: false, error: `${USAGE}\n\nUnknown command "${command}".` };
 }
+function parsePort(value, flag) {
+    if (value === undefined || value.startsWith("-")) {
+        return { ok: false, error: `${flag} needs a port number.` };
+    }
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed < 1 || parsed > 65535) {
+        return { ok: false, error: `${flag} needs a port number between 1 and 65535, got "${value}".` };
+    }
+    return parsed;
+}
 function parseCommand(command, argv) {
     const positional = [];
     let out;
+    let port;
     for (let i = 0; i < argv.length; i += 1) {
         const arg = argv[i];
         if (OUT_FLAGS.has(arg)) {
-            if (command !== "build") {
-                // Only build writes a site, so an output directory elsewhere is not a
-                // harmless extra: whoever passed it expects a site to appear somewhere.
+            if (command !== "build" && command !== "watch") {
+                // Only build and watch write a site, so an output directory elsewhere
+                // is not a harmless extra: whoever passed it expects a site to appear
+                // somewhere.
                 return {
                     ok: false,
-                    error: `${arg} is for build, which writes a site; ${command} does not.`,
+                    error: `${arg} is for build/watch, which write a site; ${command} does not.`,
                 };
             }
             const value = argv[i + 1];
@@ -53,6 +68,20 @@ function parseCommand(command, argv) {
             i += 1;
             continue;
         }
+        if (PORT_FLAGS.has(arg)) {
+            if (command !== "watch") {
+                return {
+                    ok: false,
+                    error: `${arg} is for watch, which serves the site; ${command} does not.`,
+                };
+            }
+            const parsed = parsePort(argv[i + 1], arg);
+            if (typeof parsed !== "number")
+                return parsed;
+            port = parsed;
+            i += 1;
+            continue;
+        }
         if (arg.startsWith("-")) {
             return { ok: false, error: `${USAGE}\n\nUnknown option "${arg}".` };
         }
@@ -66,5 +95,7 @@ function parseCommand(command, argv) {
     const dir = positional[0] ?? ".";
     if (command === "build")
         return { ok: true, command, dir, out: out ?? "site" };
+    if (command === "watch")
+        return { ok: true, command, dir, out: out ?? "site", port: port ?? 8080 };
     return { ok: true, command, dir };
 }

package/dist/cli.js

@@ -4,6 +4,7 @@ import { checkSite } from "./check.js";
 import { initSite, InitError } from "./init.js";
 import { parseArgs } from "./cli-args.js";
 import { SiteError } from "./site.js";
+import { WatchError, watchSite } from "./watch.js";
 async function main() {
     const args = parseArgs(process.argv.slice(2));
     if (!args.ok) {
@@ -19,6 +20,32 @@ async function main() {
         console.log("canopy-page: run `canopy-page build` to publish it");
         return;
     }
+    if (args.command === "watch") {
+        const handle = await watchSite({ dir: args.dir, out: args.out, port: args.port });
+        if (handle === undefined) {
+            // The initial build already printed why — buildSite/reportFindings own
+            // that message, watch has nothing to add.
+            process.exitCode = 1;
+            return;
+        }
+        let closing = false;
+        const shutdown = () => {
+            if (closing)
+                return;
+            closing = true;
+            void handle
+                .close()
+                .then(() => process.exit(0))
+                .catch((error) => {
+                const message = error instanceof Error ? error.message : String(error);
+                console.error(`canopy-page: error while shutting down — ${message}`);
+                process.exit(1);
+            });
+        };
+        process.on("SIGINT", shutdown);
+        process.on("SIGTERM", shutdown);
+        return;
+    }
     process.exitCode =
         args.command === "build"
             ? await buildSite({ dir: args.dir, out: args.out })
@@ -27,7 +54,7 @@ async function main() {
 main().catch((error) => {
     // A site error is about the site, not about canopy-page: the message is the
     // whole of what a reader needs, and a stack trace on top of it only buries it.
-    if (error instanceof SiteError || error instanceof InitError) {
+    if (error instanceof SiteError || error instanceof InitError || error instanceof WatchError) {
         console.error(`error: ${error.message}`);
     }
     else

package/dist/watch.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Something about running `watch` itself, as opposed to `check.ts`'s findings
+ * (about the site) or `InitError` (about `init`) — a port already in use is
+ * the case this exists for. The message is the whole of what a reader needs,
+ * same reasoning as `SiteError` in `site.ts`.
+ */
+export declare class WatchError extends Error {
+}
+/** A running preview server, and how to stop it. */
+export interface StaticServer {
+    /** The port actually bound — the same value passed in, unless it was 0. */
+    readonly port: number;
+    close(): Promise<void>;
+}
+/** Serve the files in `root` over HTTP on `port` (0 for an OS-assigned port). */
+export declare function serveStatic(root: string, port: number): Promise<StaticServer>;
+/** What a watch run needs to know. */
+export interface WatchOptions {
+    /** Directory holding the settings file. */
+    dir: string;
+    /** Directory to write the site into, and to serve. */
+    out: string;
+    /** Port to serve on. */
+    port: number;
+    /** Called after every rebuild attempt (not the initial build) with its exit code. */
+    onRebuild?: (code: number) => void;
+}
+/** A running watch session, and how to stop it. */
+export interface WatchHandle {
+    /** The port actually bound. */
+    readonly port: number;
+    close(): Promise<void>;
+}
+/**
+ * Build once, then rebuild on every source change and serve the result.
+ *
+ * The server binds before the first build runs: a port already in use is an
+ * environment problem that has nothing to do with the site, and failing on
+ * it immediately — via `WatchError`, which propagates uncaught to `cli.ts` —
+ * costs nothing. Binding after a multi-second build would waste that build
+ * on a run that was always going to fail.
+ *
+ * A failed *rebuild* (as opposed to this first build) is reported and
+ * nothing else: `buildSite`'s existing contract (an error means nothing is
+ * written) means the previous, working output just keeps being served. The
+ * process only ever stops on the initial build failing — there is nothing to
+ * serve yet, so the server is closed again — or on the caller closing it.
+ *
+ * `buildSite` is not guaranteed to only resolve with an exit code: a
+ * malformed `settings.json` (edited mid-session) or a transient fs error
+ * (e.g. a lock held by an editor's save, more likely here since the watcher
+ * below has no `awaitWriteFinish`) surfaces as a thrown `SiteError` instead.
+ * Both the initial build and every rebuild treat a throw exactly like a
+ * nonzero exit code — the alternative, letting a rebuild's rejection go
+ * uncaught, would take down the whole watch process over one bad save.
+ */
+export declare function watchSite(options: WatchOptions): Promise<WatchHandle | undefined>;

package/dist/watch.js

@@ -0,0 +1,294 @@
+import { readFile, stat } from "node:fs/promises";
+import http from "node:http";
+import { basename, extname, resolve, sep } from "node:path";
+import { watch as watchFiles } from "chokidar";
+import { buildSite } from "./build.js";
+/**
+ * Serving a build's output locally during authoring.
+ *
+ * This is a preview server for one author on one machine, not a production
+ * origin: no range requests, no caching headers, no compression. The only
+ * thing it has to get right is not serving a path outside the directory it
+ * was told to serve.
+ */
+const MIME_TYPES = {
+    ".html": "text/html; charset=utf-8",
+    ".css": "text/css; charset=utf-8",
+    ".js": "text/javascript; charset=utf-8",
+    ".json": "application/json; charset=utf-8",
+    ".svg": "image/svg+xml",
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+    ".ico": "image/x-icon",
+    ".txt": "text/plain; charset=utf-8",
+    ".xml": "application/xml; charset=utf-8",
+    ".woff": "font/woff",
+    ".woff2": "font/woff2",
+};
+function contentType(filePath) {
+    return MIME_TYPES[extname(filePath).toLowerCase()] ?? "application/octet-stream";
+}
+/**
+ * Check if a resolved file path contains any dot-prefixed segments (hidden files
+ * or directories). A request for `/.git/config` has `basename(...) === "config"`,
+ * which doesn't start with `.`, but the path contains the hidden segment `.git`.
+ * We reject any such path to avoid serving hidden version control, metadata, or
+ * temporary files that happen to exist under the served root.
+ */
+function hasHiddenSegment(root, filePath) {
+    const relative = filePath.slice(root.length);
+    const segments = relative.split(sep).filter((s) => s.length > 0);
+    return segments.some((s) => s.startsWith("."));
+}
+/**
+ * Something about running `watch` itself, as opposed to `check.ts`'s findings
+ * (about the site) or `InitError` (about `init`) — a port already in use is
+ * the case this exists for. The message is the whole of what a reader needs,
+ * same reasoning as `SiteError` in `site.ts`.
+ */
+export class WatchError extends Error {
+}
+/**
+ * Resolve a request URL to a path inside `root`, refusing anything that
+ * would land outside it.
+ *
+ * A percent-encoded "..%2F" is exactly as much a traversal attempt as a
+ * literal one, so decoding happens before the containment check runs — a
+ * check against the raw string would let the encoded form through.
+ *
+ * Malformed percent-encoding (e.g. %zz, lone %) throws URIError in
+ * decodeURIComponent — catching it here prevents an unhandled rejection
+ * that would hang the connection.
+ */
+function resolveRequestPath(root, url) {
+    let decoded;
+    try {
+        decoded = decodeURIComponent(url.split("?")[0] ?? "/");
+    }
+    catch {
+        // Malformed percent-encoding results in 404
+        return undefined;
+    }
+    const target = resolve(root, decoded.replace(/^\/+/, ""));
+    const rootWithSep = root.endsWith(sep) ? root : root + sep;
+    if (target !== root && !target.startsWith(rootWithSep))
+        return undefined;
+    return target;
+}
+/** Resolve a request URL to the file that answers it, following one directory→index.html hop. */
+async function resolveFile(root, url, triedIndex = false) {
+    const target = resolveRequestPath(root, url);
+    if (target === undefined)
+        return undefined;
+    try {
+        const stats = await stat(target);
+        if (stats.isDirectory()) {
+            if (triedIndex)
+                return undefined;
+            return resolveFile(root, `${url.replace(/\/?$/, "/")}index.html`, true);
+        }
+        return target;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Serve the files in `root` over HTTP on `port` (0 for an OS-assigned port). */
+export function serveStatic(root, port) {
+    const absoluteRoot = resolve(root);
+    // Path segments this server never has a reason to answer for — the same
+    // reasoning `isSkippedDir` in vault.ts applies to what a build publishes.
+    const server = http.createServer((req, res) => {
+        void (async () => {
+            const file = await resolveFile(absoluteRoot, req.url ?? "/");
+            if (file === undefined || hasHiddenSegment(absoluteRoot, file)) {
+                res.writeHead(404, { "content-type": "text/plain; charset=utf-8" });
+                res.end("Not Found");
+                return;
+            }
+            try {
+                const body = await readFile(file);
+                res.writeHead(200, { "content-type": contentType(file) });
+                res.end(body);
+            }
+            catch {
+                res.writeHead(404, { "content-type": "text/plain; charset=utf-8" });
+                res.end("Not Found");
+            }
+        })();
+    });
+    return new Promise((resolvePromise, reject) => {
+        server.once("error", (error) => {
+            reject(error.code === "EADDRINUSE"
+                ? new WatchError(`Port ${port} is already in use — pick another with --port.`)
+                : error);
+        });
+        server.listen(port, () => {
+            const address = server.address();
+            const actualPort = typeof address === "object" && address !== null ? address.port : port;
+            resolvePromise({
+                port: actualPort,
+                close: () => new Promise((res, rej) => {
+                    server.close((err) => (err ? rej(err) : res()));
+                }),
+            });
+        });
+    });
+}
+const DEBOUNCE_MS = 300;
+/** `Error#message` if it's one, else a `String()` fallback for whatever else a rejection carries. */
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * Build once, then rebuild on every source change and serve the result.
+ *
+ * The server binds before the first build runs: a port already in use is an
+ * environment problem that has nothing to do with the site, and failing on
+ * it immediately — via `WatchError`, which propagates uncaught to `cli.ts` —
+ * costs nothing. Binding after a multi-second build would waste that build
+ * on a run that was always going to fail.
+ *
+ * A failed *rebuild* (as opposed to this first build) is reported and
+ * nothing else: `buildSite`'s existing contract (an error means nothing is
+ * written) means the previous, working output just keeps being served. The
+ * process only ever stops on the initial build failing — there is nothing to
+ * serve yet, so the server is closed again — or on the caller closing it.
+ *
+ * `buildSite` is not guaranteed to only resolve with an exit code: a
+ * malformed `settings.json` (edited mid-session) or a transient fs error
+ * (e.g. a lock held by an editor's save, more likely here since the watcher
+ * below has no `awaitWriteFinish`) surfaces as a thrown `SiteError` instead.
+ * Both the initial build and every rebuild treat a throw exactly like a
+ * nonzero exit code — the alternative, letting a rebuild's rejection go
+ * uncaught, would take down the whole watch process over one bad save.
+ */
+export async function watchSite(options) {
+    const { dir, out, port, onRebuild } = options;
+    const server = await serveStatic(out, port);
+    let initialCode;
+    try {
+        initialCode = await buildSite({ dir, out });
+    }
+    catch (error) {
+        console.error(`canopy-page: build failed — ${errorMessage(error)}`);
+        await server.close();
+        return undefined;
+    }
+    if (initialCode !== 0) {
+        await server.close();
+        return undefined;
+    }
+    const absoluteDir = resolve(dir);
+    const resolvedOut = resolve(out);
+    const outWithSep = resolvedOut.endsWith(sep) ? resolvedOut : resolvedOut + sep;
+    let rebuildTimer;
+    let rebuilding = false;
+    let rebuildQueued = false;
+    // Tracks the rebuild currently running (if any) so close() can drain it
+    // instead of resolving while it's still writing to `out` in the
+    // background — see close() below.
+    let currentRebuild;
+    function runRebuild() {
+        if (rebuilding) {
+            rebuildQueued = true;
+            return;
+        }
+        rebuilding = true;
+        currentRebuild = buildSite({ dir, out })
+            .then((code) => {
+            console.log(code === 0
+                ? "canopy-page: rebuilt"
+                : "canopy-page: rebuild failed — serving the last successful build");
+            onRebuild?.(code);
+        }, (error) => {
+            // Same outcome as a nonzero exit code — the last successful build
+            // keeps being served — reported distinctly since it's a different
+            // failure shape. onRebuild still fires so a caller waiting on it
+            // (a test, or a future CLI status line) doesn't hang forever.
+            console.error(`canopy-page: rebuild failed — serving the last successful build (${errorMessage(error)})`);
+            onRebuild?.(1);
+        })
+            .finally(() => {
+            rebuilding = false;
+            currentRebuild = undefined;
+            if (rebuildQueued) {
+                rebuildQueued = false;
+                runRebuild();
+            }
+        });
+    }
+    function scheduleRebuild() {
+        if (rebuildTimer !== undefined)
+            clearTimeout(rebuildTimer);
+        rebuildTimer = setTimeout(runRebuild, DEBOUNCE_MS);
+    }
+    // Ignoring is structural only — dot-directories, node_modules, and the
+    // resolved output directory itself (unignored, a build watching its own
+    // output would rebuild forever). Content-level exclusions (settings.exclude)
+    // are deliberately not repeated here: vault.ts already restates canopy's
+    // exclusion rules once as a tracked debt, and a watch trigger that fires on
+    // an excluded file costs one redundant rebuild, not a wrong answer.
+    const watcher = watchFiles(absoluteDir, {
+        ignoreInitial: true,
+        ignored: (watchedPath) => {
+            const resolved = resolve(watchedPath);
+            if (resolved === absoluteDir)
+                return false;
+            if (resolved === resolvedOut || resolved.startsWith(outWithSep))
+                return true;
+            const name = basename(resolved);
+            return name === "node_modules" || name.startsWith(".");
+        },
+    });
+    // chokidar.watch() returns before its initial directory scan finishes
+    // arming the underlying OS watches — a file saved in that window can go
+    // unnoticed. Waiting for "ready" here means the promise this function
+    // returns is only kept once a change is guaranteed to be caught, which is
+    // what lets a caller (a test, or a human saving a file right after start)
+    // trust that watch mode is actually watching.
+    await new Promise((res) => watcher.once("ready", res));
+    watcher.on("all", scheduleRebuild);
+    // chokidar emits "error" for real, plausible triggers — a watched folder
+    // renamed or deleted mid-session, EPERM on Windows, ENOSPC from an inotify
+    // watch limit on Linux, EACCES on an unreadable subdirectory. An
+    // EventEmitter's "error" event with no listener throws uncaught, which
+    // would take down the whole watch process — exactly what this file's other
+    // error handling (buildSite failures never killing the process) exists to
+    // avoid. Reporting and continuing is the same "keep running" contract.
+    watcher.on("error", (error) => {
+        console.error(`canopy-page: watch error — ${errorMessage(error)}`);
+    });
+    console.log(`canopy-page: watching ${dir}, serving http://localhost:${server.port}/`);
+    return {
+        port: server.port,
+        close: async () => {
+            if (rebuildTimer !== undefined)
+                clearTimeout(rebuildTimer);
+            // A rebuild queued behind one already in flight (see runRebuild) hasn't
+            // started yet — cancelling it here means close() doesn't leave a fresh,
+            // unsignaled canopy build spawning after it returns, same as clearing
+            // rebuildTimer above does for one that was merely scheduled.
+            rebuildQueued = false;
+            // Closing the watcher first means no further change can schedule a new
+            // rebuild while we drain below — only what's already running is left
+            // to wait out, since rebuildQueued was just cleared above.
+            await watcher.close();
+            // A rebuild already in flight keeps writing to `out` and calling
+            // onRebuild after this close() would otherwise have returned, which
+            // breaks the "everything this started has stopped" contract close()
+            // is supposed to have. The loop (rather than a single await) guards
+            // against runRebuild reassigning currentRebuild synchronously from
+            // inside the previous one's `finally` — which can no longer chain into
+            // an actual rebuild now that rebuildQueued is cleared, but leaves the
+            // loop here as the correct shape regardless.
+            while (currentRebuild !== undefined) {
+                await currentRebuild;
+            }
+            await server.close();
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iyulab/canopy-page",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Authoring pipeline for documentation sites: one settings file, integrity checks, and a build.",
   "type": "module",
   "license": "MIT",
@@ -53,6 +53,7 @@
     "vitest": "^4.1.9"
   },
   "dependencies": {
-    "@iyulab/canopy": "^0.10.0"
+    "@iyulab/canopy": "^0.10.0",
+    "chokidar": "^5.0.0"
   }
 }