vagejs 0.3.1 → 0.3.2

package/README.md

@@ -29,10 +29,10 @@ Requires **Node.js 22.12 or newer**.
 npm create vagejs@latest my-site
 cd my-site
 npm install
-npm run dev
+npm start
 ```
 
-Open the URL it prints. Edit `src/pages/index.md` and the browser reloads.
+`npm start` opens the site in your browser. Edit `src/pages/index.md` and the page reloads. (`npm run dev` does the same without opening a browser, and prints the address.)
 
 ## Using vagejs
 
@@ -103,7 +103,8 @@ export default layout;
 
 | Command | What it does |
 | --- | --- |
-| `npm run dev` | Dev server with live reload |
+| `npm start` | Dev server with live reload, opened in your browser |
+| `npm run dev` | The same, without opening a browser; prints the address (and a direct `[::1]` or `127.0.0.1` address to use if the browser shows HTTP 431) |
 | `npm run check` | Links, SEO, structured data and basic accessibility; writes nothing |
 | `npm run build` | Static site in `dist/`, plus `robots.txt`, `sitemap.xml`, `llms.txt` |
 | `npm run audit` | Page-weight budgets and automated accessibility (`-- --lighthouse` adds Lighthouse) |

package/dist/cli/index.js

@@ -9,6 +9,7 @@ import { VageError } from "../core/errors.js";
 import { assertBranchName, assertCloudflareProject, assertVageSpec, assertWorkerName } from "../core/validate.js";
 import { startDevServer } from "../dev/server.js";
 import { startPreviewServer } from "../dev/preview.js";
+import { directUrl, printUrls } from "../dev/listen.js";
 import { createInterface } from "node:readline/promises";
 import { createProject } from "./create.js";
 import { frameworkInfo } from "./info.js";
@@ -30,10 +31,14 @@ cli
     .option("--root <dir>", "Project root", { default: "." })
     .option("--port <port>", "Port (fails if taken; default picks a free port from 5173)")
     .option("--host [host]", "Expose on the network")
+    .option("--open", "Open the site in your browser (at the direct address, so localhost cookies can't cause HTTP 431)")
     .action((opts) => run(opts, async () => {
     const server = await startDevServer(opts.root, { port: parsePort(opts.port), host: opts.host });
-    console.log(`vagejs dev server running at ${server.resolvedUrls?.local[0]}`);
-    server.resolvedUrls?.network.forEach((url) => console.log(`  network: ${url}`));
+    const direct = directUrl(server.httpServer?.address());
+    printUrls("vagejs dev server", server.resolvedUrls?.local[0], direct, server.resolvedUrls?.network);
+    const target = direct ?? server.resolvedUrls?.local[0] ?? server.resolvedUrls?.network[0];
+    if (opts.open && target)
+        openBrowser(target);
 }));
 cli
     .command("build", "Build the static site into dist/")
@@ -128,10 +133,14 @@ cli
     .option("--root <dir>", "Project root", { default: "." })
     .option("--port <port>", "Port (fails if taken; default picks a free port from 4173)")
     .option("--host [host]", "Expose on the network")
+    .option("--open", "Open the site in your browser")
     .action((opts) => run(opts, async () => {
     const server = await startPreviewServer(opts.root, { port: parsePort(opts.port), host: opts.host });
-    console.log(`vagejs preview running at ${server.resolvedUrls?.local[0]}`);
-    server.resolvedUrls?.network.forEach((url) => console.log(`  network: ${url}`));
+    const direct = directUrl(server.httpServer?.address());
+    printUrls("vagejs preview", server.resolvedUrls?.local[0], direct, server.resolvedUrls?.network);
+    const target = direct ?? server.resolvedUrls?.local[0] ?? server.resolvedUrls?.network[0];
+    if (opts.open && target)
+        openBrowser(target);
 }));
 cli
     .command("info", "Describe commands, config and frontmatter (use --json for agents)")
@@ -493,7 +502,16 @@ try {
     }
 }
 catch (err) {
-    fail(err, Boolean(cli.options.json));
+    fail(usageError(err), Boolean(cli.options.json));
+}
+/** Mistakes in the command line itself (unknown option, extra value) get a clear message, not a stack trace. */
+function usageError(err) {
+    if (err?.name !== "CACError")
+        return err;
+    const name = cli.matchedCommand?.name;
+    const help = name ? `vage ${name} --help` : "vage --help";
+    const lists = /^Unused args/.test(err.message) ? ' Options that take a list want one comma-separated value, e.g. --urls "/a/,/b/".' : "";
+    return new VageError(`${err.message}.${lists} See "${help}".`);
 }
 async function run(opts, fn) {
     try {

package/dist/dev/listen.d.ts

@@ -1,6 +1,17 @@
+import type { AddressInfo } from "node:net";
 export interface ServeOptions {
     port?: number;
     host?: string | boolean;
 }
 /** Runs a Vite listen() call and turns a port conflict into an actionable message. */
 export declare function listenOrExplain<T>(listen: () => Promise<T>, port: number | undefined): Promise<T>;
+/**
+ * The address the server is really listening on, when it's a loopback address, e.g.
+ * http://[::1]:5173/ or http://127.0.0.1:5173/. Browsers keep cookies per host name, so
+ * this address doesn't carry the cookies other projects left on "localhost" (the usual
+ * cause of HTTP 431). A server on every interface (--host) is reached at 127.0.0.1;
+ * a specific network address has no direct loopback address.
+ */
+export declare function directUrl(address: AddressInfo | string | null | undefined): string | undefined;
+/** Prints where the server runs: the localhost URL, the direct address, and network URLs. */
+export declare function printUrls(label: string, local: string | undefined, direct: string | undefined, network?: string[]): void;

package/dist/dev/listen.js

@@ -11,3 +11,29 @@ export async function listenOrExplain(listen, port) {
         throw err;
     }
 }
+/**
+ * The address the server is really listening on, when it's a loopback address, e.g.
+ * http://[::1]:5173/ or http://127.0.0.1:5173/. Browsers keep cookies per host name, so
+ * this address doesn't carry the cookies other projects left on "localhost" (the usual
+ * cause of HTTP 431). A server on every interface (--host) is reached at 127.0.0.1;
+ * a specific network address has no direct loopback address.
+ */
+export function directUrl(address) {
+    if (!address || typeof address === "string")
+        return undefined;
+    if (address.address === "::1")
+        return `http://[::1]:${address.port}/`;
+    if (address.address === "0.0.0.0" || address.address === "::")
+        return `http://127.0.0.1:${address.port}/`;
+    if (address.address.startsWith("127."))
+        return `http://${address.address}:${address.port}/`;
+    return undefined;
+}
+/** Prints where the server runs: the localhost URL, the direct address, and network URLs. */
+export function printUrls(label, local, direct, network = []) {
+    console.log(`${label} running at ${local ?? direct ?? network[0]}`);
+    if (direct && direct !== local)
+        console.log(`  same server: ${direct} (use this if the browser shows HTTP 431)`);
+    for (const url of network)
+        console.log(`  network: ${url}`);
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "vagejs",
-  "version": "0.3.1",
-  "description": "AI-native, static-first web framework: Markdown sites with built-in SEO, llms.txt, audits, security and safe deploys.",
+  "version": "0.3.2",
+  "description": "A free static site generator for AI website development: Markdown pages with built-in SEO, llms.txt, checks, spam protection and safe deploys.",
   "keywords": [
     "static-site-generator",
     "ssg",
@@ -9,9 +9,9 @@
     "seo",
     "llms-txt",
     "ai-agents",
-    "vite",
-    "cli",
-    "web-framework"
+    "agents-md",
+    "claude-code",
+    "cli"
   ],
   "homepage": "https://vagejs.com",
   "author": "vagejs.com",

package/templates/starter/AGENTS.md

@@ -6,7 +6,8 @@ This website uses **vagejs** (pre-release). Only the features listed here exist
 
 | Command           | What it does                                              |
 | ----------------- | --------------------------------------------------------- |
-| `npm run dev`     | Dev server with live reload. Prints the local URL.        |
+| `npm run dev`     | Dev server with live reload. Prints the local URL and the same server's direct address (e.g. `http://[::1]:5173/`): if a browser shows HTTP 431 on localhost (too many cookies from other projects), use the direct address. Use this one yourself; it doesn't open a browser. |
+| `npm start`       | For people: the dev server, opened in the default browser at the direct address. |
 | `npm run build`   | Static build into `dist/`. Exits non-zero on any error.   |
 | `npm run check`   | SEO, link, structured-data and basic a11y checks. Writes nothing. Exit 1 on errors (`--strict`: also on warnings). |
 | `npm run audit`   | Builds, then checks page-weight budgets and runs axe accessibility rules. `--lighthouse` adds a local Lighthouse run (install `lighthouse`; needs Chrome). `--url <https://...>` audits a deployed page via PageSpeed Insights (+ CrUX field data with `CRUX_API_KEY`). |

package/templates/starter/package.json

@@ -4,6 +4,7 @@
   "private": true,
   "type": "module",
   "scripts": {
+    "start": "vage dev --open",
     "dev": "vage dev",
     "build": "vage build",
     "check": "vage check",
@@ -11,6 +12,6 @@
     "preview": "vage preview"
   },
   "devDependencies": {
-    "vagejs": "^0.3.1"
+    "vagejs": "^0.3.2"
   }
 }