@mesh-tech/mesh-cli 0.20.2 → 0.20.3

package/dist/src/docs/registry-docs.js

@@ -1,38 +1,17 @@
-/**
- * The docs-as-registry-artifact client.
- *
- * The release job publishes the built portal as `@mesh-tech/docs` in the
- * fixed lockstep group, so the docs version IS the @mesh-tech/* baseline
- * version it describes. The audience is exactly "people who can install the
- * packages": the CodeArtifact registry is Zitadel-role-gated (see
- * `mesh registry login`), so no public hosting is required for the docs to
- * reach precisely the authorized set.
- *
- * This module reads the user's existing `~/.npmrc` CodeArtifact token (the
- * one `mesh registry login` writes), lists published docs versions, and
- * fetches + caches a version's tarball. It never talks to AWS directly.
- */
 import { execFileSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import path from "node:path";
 import { homeNpmrcPath, parseNpmrcRegistryAuth } from "../utils/auth-preflight.js";
 export const DOCS_PACKAGE = "@mesh-tech/docs";
-/** The CodeArtifact token + endpoint from `mesh registry login`'s ~/.npmrc line. */
 export function readDocsRegistryAuth(npmrcPath = homeNpmrcPath()) {
     if (!existsSync(npmrcPath))
         return null;
     return parseNpmrcRegistryAuth(readFileSync(npmrcPath, "utf-8"));
 }
-/** The packument URL for a package (`@scope/name` → `@scope%2fname` path encoding). */
 function packumentUrl(endpoint, pkg) {
     return `${endpoint.replace(/\/+$/, "")}/${pkg.replace(/\//g, "%2f")}`;
 }
-/**
- * An authenticated registry request. `accept` defaults to JSON for packument
- * reads; a tarball download must ask for the octet stream instead — the
- * registry answers 406 to a JSON accept on a `.tgz` URL.
- */
 async function registryFetch(auth, url, fetchImpl, accept = "application/json") {
     return fetchImpl(url, {
         headers: {
@@ -41,7 +20,6 @@ async function registryFetch(auth, url, fetchImpl, accept = "application/json")
         },
     });
 }
-/** x.y.z numeric compare (release versions carry no prerelease suffixes). */
 export function compareVersions(a, b) {
     const parse = (v) => {
         const parts = v.split(".").map((n) => Number.parseInt(n, 10) || 0);
@@ -57,11 +35,6 @@ export function compareVersions(a, b) {
     }
     return 0;
 }
-/**
- * Every published docs version, oldest → newest, plus the registry's
- * `latest` dist-tag. Throws with the login remediation when the registry
- * rejects the token — an expired token is the common case (12h TTL).
- */
 export async function listDocsVersions(auth, fetchImpl = fetch) {
     const response = await registryFetch(auth, packumentUrl(auth.endpoint, DOCS_PACKAGE), fetchImpl).catch((error) => {
         throw new Error(`could not reach the package registry: ${error instanceof Error ? error.message : String(error)}`);
@@ -79,7 +52,6 @@ export async function listDocsVersions(auth, fetchImpl = fetch) {
     const versions = Object.keys(packument.versions ?? {}).sort(compareVersions);
     return { versions, latest: packument["dist-tags"]?.latest };
 }
-/** Where fetched docs versions live: `~/.cache/mesh/docs/<version>/`. */
 export function docsCacheRoot() {
     const base = process.env.XDG_CACHE_HOME ?? path.join(homeDir(), ".cache");
     return path.join(base, "mesh", "docs");
@@ -87,12 +59,6 @@ export function docsCacheRoot() {
 function homeDir() {
     return process.env.HOME ?? tmpdir();
 }
-/**
- * Fetch and extract a docs version into the cache; returns the directory
- * containing the site's `dist/`. Cache hit = the directory already has a
- * `dist/index.html`. Partial downloads extract to a temp sibling and rename,
- * so an interrupted fetch never leaves a half-written "good" cache entry.
- */
 export async function fetchDocsArtifact(auth, version, cacheRoot = docsCacheRoot(), fetchImpl = fetch) {
     const targetDir = path.join(cacheRoot, version);
     if (existsSync(path.join(targetDir, "dist", "index.html")))
@@ -106,10 +72,6 @@ export async function fetchDocsArtifact(auth, version, cacheRoot = docsCacheRoot
     if (!tarball) {
         throw new Error(`${DOCS_PACKAGE}@${version} is not in the registry. Run \`mesh docs list\` to see published versions.`);
     }
-    // Only ever send the registry credential to the registry's own origin: the
-    // tarball URL comes out of a response BODY, and a bearer token must not
-    // follow it to an arbitrary host. Real CodeArtifact tarball URLs are
-    // same-origin; anything else is a malformed (or hostile) packument.
     if (new URL(tarball).origin !== new URL(auth.endpoint).origin) {
         throw new Error(`${DOCS_PACKAGE}@${version} points its tarball at ${new URL(tarball).origin}, not the registry (${new URL(auth.endpoint).origin}) — refusing to send the registry token off-origin`);
     }
@@ -124,7 +86,6 @@ export async function fetchDocsArtifact(auth, version, cacheRoot = docsCacheRoot
     rmSync(staging, { recursive: true, force: true });
     mkdirSync(staging, { recursive: true });
     try {
-        // npm tarballs wrap everything in `package/` — strip one component.
         execFileSync("tar", ["-xzf", tgzPath, "-C", staging, "--strip-components", "1"], {
             stdio: ["pipe", "pipe", "pipe"],
         });
@@ -140,4 +101,3 @@ export async function fetchDocsArtifact(auth, version, cacheRoot = docsCacheRoot
     renameSync(staging, targetDir);
     return targetDir;
 }
-//# sourceMappingURL=registry-docs.js.map

package/dist/src/docs/schema.d.ts

@@ -1,34 +1,5 @@
-/**
- * The `docs.json` contract — the one file that turns a directory into portal
- * content, and the reserved-name list that keeps internal material
- * unpublishable even inside an opted-in directory.
- *
- * The reserved list is the safety property of the whole design: it is frozen,
- * deliberately coarse, and matched case-insensitively against every path
- * segment at any depth. Publishing internal material takes TWO mistakes —
- * adding a `docs.json` to a directory that holds it AND moving the material
- * out of a reserved directory. Keep the list coarse; when a document should be
- * public, move the document to a publishable directory rather than narrowing
- * the list.
- */
 import { z } from "zod";
-/**
- * Directory/file names that never publish, at any depth beneath a doc root.
- * Matched case-insensitively against each individual path segment.
- *
- * Evidence-derived from the repo's own `docs/` tree (plans/, superpowers/,
- * incidents/, handoffs/, HRAN/, reviews/, runbooks/, proposals/, designs/,
- * templates/ hold the internal corpus) plus the tooling directories that must
- * never leak (node_modules, __tests__, .claude, .pi) and the generic internal
- * markers (archive, internal, drafts).
- */
 export declare const RESERVED_SEGMENTS: readonly string[];
-/**
- * A doc root's declaration. Everything else about the site is derived from the
- * tree, never declared — this schema is deliberately tiny, and STRICT: an
- * unknown key is a typo the author meant something by, so it fails validation
- * rather than being silently ignored.
- */
 export declare const docsJsonSchema: z.ZodObject<{
     title: z.ZodString;
     order: z.ZodDefault<z.ZodNumber>;
@@ -36,13 +7,6 @@ export declare const docsJsonSchema: z.ZodObject<{
     include: z.ZodDefault<z.ZodArray<z.ZodString>>;
 }, z.core.$strict>;
 export type DocsJson = z.infer<typeof docsJsonSchema>;
-/** True when one path segment is a reserved name (case-insensitive). */
 export declare function isReservedSegment(segment: string): boolean;
-/**
- * True when ANY segment of a repo-relative path is reserved. This is the
- * fail-closed check the CI gate runs over every assembled output path.
- */
 export declare function hasReservedSegment(relPath: string): boolean;
-/** Lower-kebab-case form of a title or filename stem, for routes. */
 export declare function slugify(value: string): string;
-//# sourceMappingURL=schema.d.ts.map

package/dist/src/docs/schema.js

@@ -1,27 +1,4 @@
-/**
- * The `docs.json` contract — the one file that turns a directory into portal
- * content, and the reserved-name list that keeps internal material
- * unpublishable even inside an opted-in directory.
- *
- * The reserved list is the safety property of the whole design: it is frozen,
- * deliberately coarse, and matched case-insensitively against every path
- * segment at any depth. Publishing internal material takes TWO mistakes —
- * adding a `docs.json` to a directory that holds it AND moving the material
- * out of a reserved directory. Keep the list coarse; when a document should be
- * public, move the document to a publishable directory rather than narrowing
- * the list.
- */
 import { z } from "zod";
-/**
- * Directory/file names that never publish, at any depth beneath a doc root.
- * Matched case-insensitively against each individual path segment.
- *
- * Evidence-derived from the repo's own `docs/` tree (plans/, superpowers/,
- * incidents/, handoffs/, HRAN/, reviews/, runbooks/, proposals/, designs/,
- * templates/ hold the internal corpus) plus the tooling directories that must
- * never leak (node_modules, __tests__, .claude, .pi) and the generic internal
- * markers (archive, internal, drafts).
- */
 export const RESERVED_SEGMENTS = [
     "plans",
     "designs",
@@ -41,56 +18,27 @@ export const RESERVED_SEGMENTS = [
     ".claude",
     ".pi",
 ];
-/**
- * A doc root's declaration. Everything else about the site is derived from the
- * tree, never declared — this schema is deliberately tiny, and STRICT: an
- * unknown key is a typo the author meant something by, so it fails validation
- * rather than being silently ignored.
- */
 export const docsJsonSchema = z
     .object({
-    /** Section label in the nav, e.g. "Building apps". */
     title: z.string().min(1),
-    /**
-     * Section position in the nav. Ties break alphabetically by title, so two
-     * sections can never fight over a slot nondeterministically.
-     */
     order: z.number().int().default(50),
-    /**
-     * Route prefix for the section. Defaults to the slugified title. The
-     * empty string is legal and means "this section lives at the site root" —
-     * exactly one root should do that (the front door, `docs/portal`).
-     */
     slug: z
         .string()
         .regex(/^$|^[a-z0-9]+(?:-[a-z0-9]+)*$/, 'slug must be lower-kebab-case or ""')
         .optional(),
-    /**
-     * Escape hatch: explicit repo-relative paths to publish that live outside
-     * any natural doc root (a package README, a repo-root policy file). Expected
-     * to hold a handful of entries across the whole repo — adding one is a
-     * deliberate, reviewable act. Paths under a reserved segment are refused.
-     */
     include: z.array(z.string().min(1)).default([]),
 })
     .strict();
-/** True when one path segment is a reserved name (case-insensitive). */
 export function isReservedSegment(segment) {
     const lowered = segment.toLowerCase();
     return RESERVED_SEGMENTS.some((reserved) => reserved === lowered);
 }
-/**
- * True when ANY segment of a repo-relative path is reserved. This is the
- * fail-closed check the CI gate runs over every assembled output path.
- */
 export function hasReservedSegment(relPath) {
     return relPath.split("/").some(isReservedSegment);
 }
-/** Lower-kebab-case form of a title or filename stem, for routes. */
 export function slugify(value) {
     return (value
         .toLowerCase()
         .replace(/[^a-z0-9]+/g, "-")
         .replace(/^-+|-+$/g, "") || "index");
 }
-//# sourceMappingURL=schema.js.map

package/dist/src/docs/serve.d.ts

@@ -1,27 +1,9 @@
-/**
- * Serve a BUILT docs site (the Zudoku `dist/`) over loopback HTTP.
- *
- * This is deliberately not the deleted portal-serve.ts: that one served a
- * bespoke renderer's output with a custom search-index API. This one serves
- * a prerendered static tree and nothing else — try the exact path, then
- * `<path>.html` (Zudoku's prerendered routes), then `<path>/index.html`,
- * then the SPA fallback. No search endpoint: Pagefind runs client-side
- * against the shipped index files.
- */
 export interface DocsServer {
     url: string;
     port: number;
     close: () => Promise<void>;
 }
-/**
- * Start the server. `port: 0` picks a free one (what tests use).
- *
- * Path safety: the URL path is normalized and rejected outright if it escapes
- * the root — this serves a local preview to the machine's own user, but a
- * `..` escape is a hole with no excuse to exist.
- */
 export declare function serveDocsSite(args: {
     root: string;
     port: number;
 }): Promise<DocsServer>;
-//# sourceMappingURL=serve.d.ts.map

package/dist/src/docs/serve.js

@@ -1,13 +1,3 @@
-/**
- * Serve a BUILT docs site (the Zudoku `dist/`) over loopback HTTP.
- *
- * This is deliberately not the deleted portal-serve.ts: that one served a
- * bespoke renderer's output with a custom search-index API. This one serves
- * a prerendered static tree and nothing else — try the exact path, then
- * `<path>.html` (Zudoku's prerendered routes), then `<path>/index.html`,
- * then the SPA fallback. No search endpoint: Pagefind runs client-side
- * against the shipped index files.
- */
 import { createServer } from "node:http";
 import { readFile } from "node:fs/promises";
 import { extname, join, normalize, sep } from "node:path";
@@ -30,20 +20,8 @@ const CONTENT_TYPES = {
     ".md": "text/markdown; charset=utf-8",
     ".webmanifest": "application/manifest+json",
 };
-/**
- * Start the server. `port: 0` picks a free one (what tests use).
- *
- * Path safety: the URL path is normalized and rejected outright if it escapes
- * the root — this serves a local preview to the machine's own user, but a
- * `..` escape is a hole with no excuse to exist.
- */
 export async function serveDocsSite(args) {
     const root = normalize(args.root);
-    // Containment, not prefix-match: the prefix test alone admits SIBLINGS
-    // whose names extend the root's basename (`<parent>/dist-secret/x` starts
-    // with `<parent>/dist`). The vector that reaches it is an encoded slash —
-    // WHATWG URL parsing strips dot-segments, then decodeURIComponent turns
-    // `..%2f` back into `../`. (Review on #3612.)
     const rootPrefix = root.endsWith(sep) ? root : root + sep;
     const server = createServer((req, res) => {
         void (async () => {
@@ -59,25 +37,20 @@ export async function serveDocsSite(args) {
                 `${pathname.replace(/\/$/, "")}/index.html`,
             ];
             if (pathname !== "/")
-                candidates.push("/index.html"); // SPA fallback
+                candidates.push("/index.html");
             for (const candidate of candidates) {
                 const filePath = normalize(join(root, candidate));
-                // `continue`, not `break`: one malformed candidate must not change
-                // the response for the rest (the SPA fallback lives inside the root).
                 if (filePath !== root && !filePath.startsWith(rootPrefix))
-                    continue; // outside the root — never serve
+                    continue;
                 try {
                     const body = await readFile(filePath);
                     const type = CONTENT_TYPES[extname(filePath)] ?? "application/octet-stream";
-                    // Prerendered HTML can be stale the moment a newer build exists;
-                    // hashed assets are immutable.
                     const cache = candidate.includes("/assets/") ? "public, max-age=31536000, immutable" : "no-cache";
                     res.writeHead(200, { "content-type": type, "cache-control": cache });
                     res.end(body);
                     return;
                 }
                 catch {
-                    // try the next candidate
                 }
             }
             res.writeHead(404, { "content-type": "text/plain" }).end("not found");
@@ -99,4 +72,3 @@ export async function serveDocsSite(args) {
         }),
     };
 }
-//# sourceMappingURL=serve.js.map

package/dist/src/docs/start.d.ts

@@ -1,50 +1,13 @@
-/**
- * `mesh docs start` / `mesh docs list` / `mesh docs stop` — the docs as a
- * local, role-gated server (MESH-1803 follow-up).
- *
- * Two content modes, chosen automatically:
- *
- *   - **Repo mode** — inside a checkout that has doc roots (mesh-platform):
- *     assemble the working tree, build, and serve the static output. This is
- *     the contributor path; the docs are exactly what is on disk.
- *   - **Registry mode** — anywhere else (a tenant repo, a global install):
- *     fetch the published `@mesh-tech/docs` artifact — versioned with the
- *     @mesh-tech/* baseline — from the role-gated registry and serve it.
- *     `-v <version>` pins; default is the registry's `latest` dist-tag.
- *
- * Two run modes: by default the server runs DETACHED in a tmux session with
- * the constant name `mesh-docs` — the handle that keeps a backgrounded server
- * from getting lost — and the command prints the URL once it answers.
- * `--foreground` (or a non-TTY, i.e. an agent/CI) serves in the foreground.
- * `--dev` (repo mode) runs the Zudoku dev server and is foreground-only: it
- * is an authoring tool — you are supposed to watch it.
- *
- * The registry mode is the distribution point: the people who can read the
- * docs are exactly the people who can install the packages, and no public
- * hosting is required.
- */
-/** The one tmux session name — the constant handle for the detached server. */
 export declare const DOCS_TMUX_SESSION = "mesh-docs";
-/** `mesh docs list` — published docs versions, newest first. */
 export declare function runDocsList(): Promise<void>;
-/** The install command to show when tmux is missing, per platform. */
 export declare function tmuxInstallHint(platform?: string): string;
-/** True when tmux is runnable. */
 export declare function tmuxAvailable(): boolean;
-/** The detached/foreground decision, as one pure predicate. */
 export declare function shouldDetach(args: {
     foreground: boolean;
     dev: boolean;
     isTTY: boolean;
 }): boolean;
-/** True when the detached session currently exists. */
 export declare function docsSessionExists(): boolean;
-/**
- * The argv the tmux session runs: a hidden foreground serve of the prepared
- * directory. Source checkouts re-enter through `pnpm exec mesh` at the repo
- * root (the shim-free canonical form); a published install re-enters through
- * the `mesh` bin on PATH.
- */
 export declare function tmuxServeArgs(args: {
     mode: "source" | "dist";
     repoRoot: string;
@@ -54,7 +17,6 @@ export declare function tmuxServeArgs(args: {
     command: string[];
     cwd: string;
 };
-/** (Re)start the detached docs session and wait for it to answer. */
 export declare function startDetached(args: {
     mode: "source" | "dist";
     repoRoot: string;
@@ -62,14 +24,11 @@ export declare function startDetached(args: {
     port: number;
     label: string;
 }): Promise<void>;
-/** `mesh docs stop` — kill the detached session if it exists. */
 export declare function runDocsStop(): void;
-/** The hidden `mesh docs serve-static` the tmux session re-enters through. */
 export declare function runDocsServeStatic(args: {
     root: string;
     port: string;
 }): Promise<void>;
-/** `mesh docs start` — serve the docs locally, detached by default. */
 export declare function runDocsStart(args: {
     repoRoot: string;
     version?: string | undefined;
@@ -77,4 +36,3 @@ export declare function runDocsStart(args: {
     dev: boolean;
     foreground: boolean;
 }): Promise<void>;
-//# sourceMappingURL=start.d.ts.map

package/dist/src/docs/start.js

@@ -1,28 +1,3 @@
-/**
- * `mesh docs start` / `mesh docs list` / `mesh docs stop` — the docs as a
- * local, role-gated server (MESH-1803 follow-up).
- *
- * Two content modes, chosen automatically:
- *
- *   - **Repo mode** — inside a checkout that has doc roots (mesh-platform):
- *     assemble the working tree, build, and serve the static output. This is
- *     the contributor path; the docs are exactly what is on disk.
- *   - **Registry mode** — anywhere else (a tenant repo, a global install):
- *     fetch the published `@mesh-tech/docs` artifact — versioned with the
- *     @mesh-tech/* baseline — from the role-gated registry and serve it.
- *     `-v <version>` pins; default is the registry's `latest` dist-tag.
- *
- * Two run modes: by default the server runs DETACHED in a tmux session with
- * the constant name `mesh-docs` — the handle that keeps a backgrounded server
- * from getting lost — and the command prints the URL once it answers.
- * `--foreground` (or a non-TTY, i.e. an agent/CI) serves in the foreground.
- * `--dev` (repo mode) runs the Zudoku dev server and is foreground-only: it
- * is an authoring tool — you are supposed to watch it.
- *
- * The registry mode is the distribution point: the people who can read the
- * docs are exactly the people who can install the packages, and no public
- * hosting is required.
- */
 import { execFileSync } from "node:child_process";
 import { appendFileSync, existsSync, writeFileSync } from "node:fs";
 import path from "node:path";
@@ -32,7 +7,6 @@ import { discoverDocRoots } from "./discover.js";
 import { runAssemble, reportAssembly, DOCS_APP_DIR } from "./portal.js";
 import { serveDocsSite } from "./serve.js";
 import { DOCS_PACKAGE, fetchDocsArtifact, listDocsVersions, readDocsRegistryAuth, } from "./registry-docs.js";
-/** The one tmux session name — the constant handle for the detached server. */
 export const DOCS_TMUX_SESSION = "mesh-docs";
 function registryAuthOrThrow() {
     const auth = readDocsRegistryAuth();
@@ -42,7 +16,6 @@ function registryAuthOrThrow() {
     }
     return auth;
 }
-/** `mesh docs list` — published docs versions, newest first. */
 export async function runDocsList() {
     const auth = registryAuthOrThrow();
     const { versions, latest } = await listDocsVersions(auth);
@@ -56,10 +29,6 @@ export async function runDocsList() {
         process.stdout.write(`  ${version}${marker}\n`);
     }
 }
-// ---------------------------------------------------------------------------
-// Detached (tmux) machinery
-// ---------------------------------------------------------------------------
-/** The install command to show when tmux is missing, per platform. */
 export function tmuxInstallHint(platform = process.platform) {
     if (platform === "darwin")
         return "brew install tmux";
@@ -67,7 +36,6 @@ export function tmuxInstallHint(platform = process.platform) {
         return "sudo apt-get install tmux   # or your distro's package manager";
     return "install tmux via your package manager";
 }
-/** True when tmux is runnable. */
 export function tmuxAvailable() {
     try {
         execFileSync("tmux", ["-V"], { stdio: ["pipe", "pipe", "pipe"] });
@@ -77,11 +45,9 @@ export function tmuxAvailable() {
         return false;
     }
 }
-/** The detached/foreground decision, as one pure predicate. */
 export function shouldDetach(args) {
     return !args.foreground && !args.dev && args.isTTY;
 }
-/** True when the detached session currently exists. */
 export function docsSessionExists() {
     try {
         execFileSync("tmux", ["has-session", "-t", DOCS_TMUX_SESSION], { stdio: ["pipe", "pipe", "pipe"] });
@@ -91,12 +57,6 @@ export function docsSessionExists() {
         return false;
     }
 }
-/**
- * The argv the tmux session runs: a hidden foreground serve of the prepared
- * directory. Source checkouts re-enter through `pnpm exec mesh` at the repo
- * root (the shim-free canonical form); a published install re-enters through
- * the `mesh` bin on PATH.
- */
 export function tmuxServeArgs(args) {
     const serveArgs = ["docs", "serve-static", "--root", args.serveRoot, "--port", String(args.port)];
     if (args.mode === "dist") {
@@ -104,34 +64,22 @@ export function tmuxServeArgs(args) {
     }
     return { command: ["pnpm", "exec", "mesh", ...serveArgs], cwd: args.repoRoot };
 }
-/** (Re)start the detached docs session and wait for it to answer. */
 export async function startDetached(args) {
     if (!tmuxAvailable()) {
         throw new Error(`tmux is not installed — the detached docs server runs in a tmux session named "${DOCS_TMUX_SESSION}".\n` +
             `Install it with: ${tmuxInstallHint()}\n` +
             `Or run in the foreground instead: mesh docs start --foreground`);
     }
-    // Restart semantics: the session name is the constant handle, so a second
-    // `docs start` replaces the first rather than orphaning it. Say so when it
-    // happens — a developer serving `-v 1.11.3` who starts the working tree
-    // should not lose the first server silently.
     if (docsSessionExists()) {
         logInfo(`Replacing the docs server already running in tmux session "${DOCS_TMUX_SESSION}".`);
         try {
             execFileSync("tmux", ["kill-session", "-t", DOCS_TMUX_SESSION], { stdio: ["pipe", "pipe", "pipe"] });
         }
         catch {
-            // raced with its own shutdown — harmless
         }
     }
     const { command, cwd } = tmuxServeArgs(args);
-    // Pass the argv ARRAY: tmux execs a multi-argument command directly, with no
-    // shell. A single joined string would go through `sh -c`, and a `$()` or
-    // backtick in a path (which mesh-ops worktree names can legitimately carry)
-    // would be evaluated. Verified empirically on tmux 3.6a.
     execFileSync("tmux", ["new-session", "-d", "-s", DOCS_TMUX_SESSION, "-c", cwd, "--", ...command], { stdio: ["pipe", "pipe", "pipe"] });
-    // Wait for the server to answer before printing the URL — "one click" only
-    // works if the link is live when it appears.
     const deadline = Date.now() + 60_000;
     const url = `http://127.0.0.1:${args.port}`;
     let lastError = "";
@@ -154,13 +102,11 @@ export async function startDetached(args) {
 }
 function printReady(url, label) {
     logSuccess(`Mesh docs (${label}) are live:`);
-    // Bare on its own line — one click from any terminal.
     process.stdout.write(`\n  ${url}\n\n`);
     logInfo(`Running detached in the tmux session "${DOCS_TMUX_SESSION}".`);
     logInfo(`  attach: tmux attach -t ${DOCS_TMUX_SESSION}`);
     logInfo(`  stop:   mesh docs stop`);
 }
-/** `mesh docs stop` — kill the detached session if it exists. */
 export function runDocsStop() {
     try {
         execFileSync("tmux", ["kill-session", "-t", DOCS_TMUX_SESSION], { stdio: ["pipe", "pipe", "pipe"] });
@@ -170,7 +116,6 @@ export function runDocsStop() {
         logInfo(`No docs server is running (no tmux session named "${DOCS_TMUX_SESSION}").`);
     }
 }
-/** The hidden `mesh docs serve-static` the tmux session re-enters through. */
 export async function runDocsServeStatic(args) {
     const requestedPort = Number.parseInt(args.port, 10);
     if (!Number.isInteger(requestedPort) || requestedPort < 0 || requestedPort > 65535) {
@@ -188,26 +133,17 @@ export async function runDocsServeStatic(args) {
         process.once("SIGTERM", stop);
     });
 }
-// ---------------------------------------------------------------------------
-// mesh docs start
-// ---------------------------------------------------------------------------
-/** `mesh docs start` — serve the docs locally, detached by default. */
 export async function runDocsStart(args) {
     const requestedPort = Number.parseInt(args.port, 10);
     if (!Number.isInteger(requestedPort) || requestedPort < 0 || requestedPort > 65535) {
         throw new Error(`Invalid --port: ${args.port}`);
     }
-    // Compute the run mode BEFORE any prepare work (assemble+build is the
-    // expensive part; refuse bad combinations up front).
     const detached = shouldDetach({
         foreground: args.foreground,
         dev: args.dev,
         isTTY: process.stdout.isTTY === true,
     });
     if (detached && requestedPort === 0) {
-        // A detached server that picks its own port cannot report the choice back:
-        // the parent would poll 127.0.0.1:0 for a minute and "fail" while a
-        // perfectly good server runs on a port nobody knows.
         throw new Error("--port 0 (pick a free port) needs a foreground server, because the detached session " +
             "cannot report the port it chose back to this process. Use `mesh docs start --foreground --port 0`, " +
             "or pass an explicit port to run detached.");
@@ -238,9 +174,6 @@ export async function runDocsStart(args) {
         }
         const appDir = path.join(args.repoRoot, DOCS_APP_DIR);
         if (args.dev) {
-            // HMR mode for docs authoring: assemble, then hand the tree to the
-            // Zudoku dev server. Foreground-only by design — an authoring tool is
-            // watched, not detached.
             const result = runAssemble({
                 repoRoot: args.repoRoot,
                 outDir: path.join(appDir, "content"),
@@ -260,8 +193,6 @@ export async function runDocsStart(args) {
             });
             return;
         }
-        // Detached mode keeps the waiting display to two lines; the build's noise
-        // lands in a log file instead of the terminal.
         const buildLog = path.join(args.repoRoot, DOCS_APP_DIR, "build.log");
         logInfo(`Preparing the docs from this checkout (assemble + build — log: ${path.relative(args.repoRoot, buildLog)})…`);
         const result = runAssemble({
@@ -310,4 +241,3 @@ export async function runDocsStart(args) {
         process.once("SIGTERM", stop);
     });
 }
-//# sourceMappingURL=start.js.map

package/dist/src/eval/agent-eval.d.mts

@@ -1,14 +1,2 @@
 #!/usr/bin/env npx tsx
-/**
- * Agent eval runner — sends prompts to a mesh.ai.Agent API and captures
- * structured traces of tool calls, results, errors, and artifacts.
- *
- * Usage:
- *   npx tsx agent-eval.mts --prompt "Build a contract onboarding workflow..."
- *   npx tsx agent-eval.mts --prompt-file prompts/contract-onboarding.md
- *   npx tsx agent-eval.mts --prompt "..." --api http://localhost:8787 --conversation conv-123
- *
- * Output: JSON trace to stdout (pipe to jq or a file), human summary to stderr.
- */
 export {};
-//# sourceMappingURL=agent-eval.d.mts.map