@mesh-tech/mesh-cli 0.20.2 → 0.20.3

package/dist/src/commands/site.d.ts

@@ -1,3 +1,2 @@
 import { Command } from "commander";
 export declare function registerSiteCommands(program: Command): void;
-//# sourceMappingURL=site.d.ts.map

package/dist/src/commands/site.js

@@ -1,21 +1,3 @@
-/**
- * `mesh site` — publish a built directory as an OAuth-protected static site.
- *
- *   mesh site publish <name> <dir>   walk, hash, upload what's missing, commit
- *   mesh site versions <name>        what has been published, newest first
- *   mesh site rollback <name> <ver>  flip the pointer back
- *
- * Content-addressed and incremental, which is not an optimisation here so much
- * as the thing that makes it usable: Enlight's build is 138 MB across 138 files,
- * and 106 MB of that is six Dynamsoft installers that never change. They upload
- * on the first publish and never again.
- *
- * Three stateless calls against the agent-api, so a run that dies partway
- * through leaves nothing to clean up and a re-run resumes by re-asking what is
- * missing.
- *
- * Design: `docs/superpowers/specs/2026-08-07-studio-static-sites-design.md`.
- */
 import { createHash } from "node:crypto";
 import { createReadStream } from "node:fs";
 import { readdir, readFile, stat } from "node:fs/promises";
@@ -23,27 +5,8 @@ import { join, relative, resolve, sep } from "node:path";
 import { logError, logInfo, logSuccess, logWarn } from "../utils/log.js";
 import { agentApiFetch, agentApiSend, describeHttpError, describeNetworkError, resolveTarget, } from "./agent-api-client.js";
 const DEFAULT_AUTH_CONTEXT = "mesh.dev";
-/** How many blob uploads run at once. Bounded because the API buffers each blob
- *  to verify its hash, and the largest real file in this corpus is 43 MB. */
 const UPLOAD_CONCURRENCY = 4;
-/** Names never worth publishing, skipped rather than uploaded and served. */
 const SKIP_ENTRIES = new Set([".DS_Store", "Thumbs.db", ".git"]);
-/**
- * HTTP failures in site language.
- *
- * The shared `describeHttpError` is written for conversations, and two of its
- * branches actively mislead here:
- *
- *  - It folds **403 into 401** and advises `mesh login`. For a publish that is
- *    the wrong instruction and the wrong diagnosis — the caller IS authenticated
- *    and simply lacks the grant, so logging in again changes nothing and hides
- *    the one fact that would fix it.
- *  - Its **404** says "conversation/artifact not found … run `mesh conversations
- *    list`", which sends someone debugging a rollback to an unrelated command.
- *
- * Everything else defers to the shared renderer, so there is still one place
- * that handles 503s, redirects and the generic shape.
- */
 async function describeSiteHttpError(res, target, site) {
     if (res.status === 403) {
         return (`not allowed to publish "${site}" — you are authenticated but lack the grant. ` +
@@ -54,7 +17,6 @@ async function describeSiteHttpError(res, target, site) {
     }
     return describeHttpError(res, target, { id: site });
 }
-/** SHA-256 of a file, streamed so a 43 MB installer never lands in memory whole. */
 async function hashFile(absolute) {
     const h = createHash("sha256");
     await new Promise((res, rej) => {
@@ -65,7 +27,6 @@ async function hashFile(absolute) {
     });
     return h.digest("hex");
 }
-/** Walk a directory into manifest entries, hashing as it goes. */
 async function walk(root) {
     const out = [];
     async function visit(dir) {
@@ -73,9 +34,6 @@ async function walk(root) {
             if (SKIP_ENTRIES.has(entry.name))
                 continue;
             const absolute = join(dir, entry.name);
-            // Symlinks are NOT followed. A build directory that links outside itself
-            // would otherwise publish whatever it points at, and a link cycle would
-            // hang the walk — neither is a thing a built site legitimately needs.
             if (entry.isSymbolicLink()) {
                 logWarn(`skipping symlink ${relative(root, absolute)}`);
                 continue;
@@ -88,8 +46,6 @@ async function walk(root) {
                 continue;
             const info = await stat(absolute);
             out.push({
-                // Manifest paths are always forward-slashed, whatever the host OS uses,
-                // so a site published from Windows resolves identically to one from a Mac.
                 path: relative(root, absolute).split(sep).join("/"),
                 absolute,
                 hash: await hashFile(absolute),
@@ -109,7 +65,6 @@ function human(bytes) {
         return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
     return `${(bytes / 1024 / 1024 / 1024).toFixed(2)} GB`;
 }
-/** Run `worker` over `items`, at most `limit` at a time. */
 async function pooled(items, limit, worker) {
     let next = 0;
     const runners = Array.from({ length: Math.min(limit, items.length) }, async () => {
@@ -135,12 +90,8 @@ async function publish(name, dir, opts, target) {
     const total = files.reduce((n, f) => n + f.size, 0);
     logInfo(`${files.length} files, ${human(total)}`);
     if (!files.some((f) => f.path === "index.html")) {
-        // A warning, not an error — a site of pure assets is legitimate. But an SPA
-        // without index.html serves nothing at its root and the fallback has no
-        // target, which is much cheaper to hear now than to diagnose in a browser.
         logWarn("no index.html at the root — deep links and the site root will 404");
     }
-    // ── ① what is missing ────────────────────────────────────────────────────
     const unique = [...new Set(files.map((f) => f.hash))];
     const checkRes = await agentApiSend(target, `/v1/sites/${encodeURIComponent(name)}/blobs/check`, {
         method: "POST",
@@ -151,13 +102,11 @@ async function publish(name, dir, opts, target) {
     const { missing } = (await checkRes.json());
     const missingSet = new Set(missing);
     const toUpload = files.filter((f) => missingSet.has(f.hash));
-    // Deduplicated by hash: a build with the same bytes at two paths uploads once.
     const seen = new Set();
     const uploads = toUpload.filter((f) => (seen.has(f.hash) ? false : (seen.add(f.hash), true)));
     const uploadBytes = uploads.reduce((n, f) => n + f.size, 0);
     const reused = files.length - uploads.length;
     logInfo(`${uploads.length} to upload (${human(uploadBytes)}); ${reused} already present (${human(total - uploadBytes)})`);
-    // ── ② upload them ────────────────────────────────────────────────────────
     let done = 0;
     await pooled(uploads, UPLOAD_CONCURRENCY, async (file) => {
         const body = await readFile(file.absolute);
@@ -169,7 +118,6 @@ async function publish(name, dir, opts, target) {
         done += 1;
         logInfo(`  [${done}/${uploads.length}] ${file.path} (${human(file.size)})`);
     });
-    // ── ③ commit ─────────────────────────────────────────────────────────────
     const fileMap = Object.fromEntries(files.map((f) => [f.path, f.hash]));
     const commitRes = await agentApiSend(target, `/v1/sites/${encodeURIComponent(name)}/versions`, {
         method: "POST",
@@ -177,9 +125,6 @@ async function publish(name, dir, opts, target) {
     });
     if (!commitRes.ok) {
         if (commitRes.status === 409) {
-            // The server holds the truth about what is actually stored, so report its
-            // list rather than re-deriving one — a mismatch here means the upload and
-            // the commit disagree, and the server's view is the one that matters.
             const body = (await commitRes.json().catch(() => ({})));
             throw new Error(`commit rejected: ${body.missing?.length ?? "some"} blobs are missing server-side. ` +
                 `Re-run to upload them.`);
@@ -221,7 +166,6 @@ async function rollback(name, version, target) {
         throw new Error(await describeSiteHttpError(res, target, name));
     logSuccess(`${name} now serves ${version}`);
 }
-/** Shared target resolution + error reporting for every subcommand. */
 async function run(opts, body) {
     let target;
     try {
@@ -257,10 +201,6 @@ export function registerSiteCommands(program) {
         .description("Publish a built directory as a new version\n\n" +
         "Uploads only files the server does not already hold, so a rebuild moves\n" +
         "only what changed.")
-        // NOT `--version`: commander registers `-V, --version` on the root program,
-        // and it wins. `mesh site publish x ./dist --version abc` printed the CLI's
-        // own version and exited 0 without publishing anything — a silent no-op that
-        // looks like success, which is the worst shape a CI flag can have.
         .option("--version-id <id>", "Version id (default: a UTC timestamp; CI usually passes a git sha)")
         .option("--no-activate", "Publish without pointing the site at it")).action(async (name, dir, opts) => {
         await run(opts, (target) => publish(name, dir, { version: opts.versionId, activate: opts.activate }, target));
@@ -274,4 +214,3 @@ export function registerSiteCommands(program) {
         await run(opts, (target) => rollback(name, version, target));
     });
 }
-//# sourceMappingURL=site.js.map

package/dist/src/commands/skills.d.ts

@@ -1,74 +1,13 @@
-/**
- * mesh skills sync — agent-skill distribution (design §7.2, AC D1/D2).
- *
- * Three layers, one command:
- *
- *   1. BASE skills (how to drive the CLI — the CLI's own skills/) are
- *      installed into the repo's `.claude/skills/mesh-<name>/SKILL.md`.
- *      CLI-managed: files carry a managed marker and are only overwritten
- *      when they carry it (hand-edited copies are left alone with a warning).
- *
- *   2. PLATFORM skills — the build-an-app recipes that ship inside the
- *      `@mesh-tech/*` packages the repo already depends on
- *      (`node_modules/@mesh-tech/<pkg>/skills/<domain>/`). These are FETCHED
- *      from the installed package rather than vendored into the CLI, so the
- *      recipe stays owned by the platform package it documents and moves with
- *      it. `@mesh-tech/app-kit#apps` — the scaffold → wire → run → debug
- *      recipe — is the one every app repo needs.
- *      Requires `pnpm install` to have run; before that the layer is a no-op
- *      with a note.
- *
- *   3. INTENT discovery for those same package skills, for agents that read
- *      the catalog rather than `.claude/skills/`: the hook mechanism
- *      vendored into the CLI (deterministic, offline — no interactive
- *      installer):
- *        - .intent/hooks/intent-claude-gate.mjs (SessionStart catalog +
- *          edit gate; invokes the REPO-PINNED `pnpm exec intent`)
- *        - `@tanstack/intent` in the repo's devDependencies — the fence tells
- *          agents to run `pnpm exec intent list`, so the binary has to be
- *          pinned in the repo it runs in, tenant app repos included
- *        - .claude/settings.json SessionStart hook (JSON-merged, idempotent)
- *        - AGENTS.md fence (<!-- intent-skills:start/end -->) for
- *          non-Claude agents
- *
- * `mesh skills sync --check` is the CI/doctor form: exits 1 listing what is
- * missing or stale, changes nothing. `mesh create-app` runs a best-effort
- * sync after scaffolding so a fresh Claude session in a fresh repo sees every
- * skill layer with zero manual setup (D1).
- */
 import { Command } from "commander";
-/**
- * The `@tanstack/intent` range pinned into a target repo, and the single
- * source for every place that range appears: the standalone apps-repo
- * template renders from it, and `test/skills-sync.test.ts` holds it equal to
- * the CLI's own devDependency, so the binary agents invoke matches the
- * catalog format the vendored gate hook expects.
- */
 export declare const INTENT_RANGE = "^0.3.6";
-/** The repo root skills sync targets: the enclosing git root, else cwd. */
 export declare function resolveTargetRoot(startDir?: string): string;
-/**
- * Platform skills reachable from the target repo: every
- * `node_modules/@mesh-tech/<pkg>/skills/<domain>/SKILL.md`. Installed under
- * `mesh-<pkg>-<domain>` so a package's `core` skill can never collide with the
- * CLI's own `mesh-core`. One entry per `<pkg>/<domain>` — the same package
- * linked from several workspace packages is still one skill.
- */
 export declare function listPackageSkills(root: string): Array<{
     name: string;
     dir: string;
     source: string;
 }>;
-/**
- * Seed the app's OWN skill — the stub a developer grows into the guidance only
- * their app can carry. Written once and never touched again: it carries no
- * managed marker, so `sync` leaves it alone forever.
- * Returns the repo-relative path when it wrote one, else null.
- */
 export declare function seedAppSkill(root: string, appName: string, appRelPath: string): string | null;
-/** Run a sync (or check). Returns true when everything is in place. */
 export declare function syncSkills(root: string, opts?: {
     check?: boolean;
 }): boolean;
 export declare function registerSkillsCommands(program: Command): void;
-//# sourceMappingURL=skills.d.ts.map

package/dist/src/commands/skills.js

@@ -1,41 +1,3 @@
-/**
- * mesh skills sync — agent-skill distribution (design §7.2, AC D1/D2).
- *
- * Three layers, one command:
- *
- *   1. BASE skills (how to drive the CLI — the CLI's own skills/) are
- *      installed into the repo's `.claude/skills/mesh-<name>/SKILL.md`.
- *      CLI-managed: files carry a managed marker and are only overwritten
- *      when they carry it (hand-edited copies are left alone with a warning).
- *
- *   2. PLATFORM skills — the build-an-app recipes that ship inside the
- *      `@mesh-tech/*` packages the repo already depends on
- *      (`node_modules/@mesh-tech/<pkg>/skills/<domain>/`). These are FETCHED
- *      from the installed package rather than vendored into the CLI, so the
- *      recipe stays owned by the platform package it documents and moves with
- *      it. `@mesh-tech/app-kit#apps` — the scaffold → wire → run → debug
- *      recipe — is the one every app repo needs.
- *      Requires `pnpm install` to have run; before that the layer is a no-op
- *      with a note.
- *
- *   3. INTENT discovery for those same package skills, for agents that read
- *      the catalog rather than `.claude/skills/`: the hook mechanism
- *      vendored into the CLI (deterministic, offline — no interactive
- *      installer):
- *        - .intent/hooks/intent-claude-gate.mjs (SessionStart catalog +
- *          edit gate; invokes the REPO-PINNED `pnpm exec intent`)
- *        - `@tanstack/intent` in the repo's devDependencies — the fence tells
- *          agents to run `pnpm exec intent list`, so the binary has to be
- *          pinned in the repo it runs in, tenant app repos included
- *        - .claude/settings.json SessionStart hook (JSON-merged, idempotent)
- *        - AGENTS.md fence (<!-- intent-skills:start/end -->) for
- *          non-Claude agents
- *
- * `mesh skills sync --check` is the CI/doctor form: exits 1 listing what is
- * missing or stale, changes nothing. `mesh create-app` runs a best-effort
- * sync after scaffolding so a fresh Claude session in a fresh repo sees every
- * skill layer with zero manual setup (D1).
- */
 import * as fs from "fs";
 import * as path from "path";
 import { execFileSync } from "child_process";
@@ -45,15 +7,7 @@ import { findPackageRoot } from "./local/stack.js";
 const MANAGED_MARKER = "<!-- managed-by: mesh skills sync — edits are overwritten; copy content elsewhere to customize -->";
 const FENCE_START = "<!-- intent-skills:start -->";
 const HOOK_RELATIVE = path.join(".intent", "hooks", "intent-claude-gate.mjs");
-/**
- * The `@tanstack/intent` range pinned into a target repo, and the single
- * source for every place that range appears: the standalone apps-repo
- * template renders from it, and `test/skills-sync.test.ts` holds it equal to
- * the CLI's own devDependency, so the binary agents invoke matches the
- * catalog format the vendored gate hook expects.
- */
 export const INTENT_RANGE = "^0.3.6";
-/** The repo root skills sync targets: the enclosing git root, else cwd. */
 export function resolveTargetRoot(startDir = process.cwd()) {
     try {
         return execFileSync("git", ["rev-parse", "--show-toplevel"], {
@@ -69,7 +23,6 @@ export function resolveTargetRoot(startDir = process.cwd()) {
 function cliAsset(...segments) {
     return path.join(findPackageRoot(), ...segments);
 }
-/** Base skills shipped in the CLI package (skills/<name>/SKILL.md). */
 function listBaseSkills() {
     const dir = cliAsset("skills");
     if (!fs.existsSync(dir))
@@ -79,7 +32,6 @@ function listBaseSkills() {
         .filter((entry) => entry.isDirectory() && fs.existsSync(path.join(dir, entry.name, "SKILL.md")))
         .map((entry) => ({ name: entry.name, source: path.join(dir, entry.name, "SKILL.md") }));
 }
-/** Managed content = source SKILL.md with the marker after its frontmatter. */
 function renderManagedSkill(source) {
     const raw = fs.readFileSync(source, "utf-8");
     const frontmatter = raw.match(/^(---\n[\s\S]*?\n---\n)/)?.[1];
@@ -87,14 +39,7 @@ function renderManagedSkill(source) {
         return `${MANAGED_MARKER}\n\n${raw}`;
     return `${frontmatter}\n${MANAGED_MARKER}\n${raw.slice(frontmatter.length)}`;
 }
-/** The CLI's own skills are layer 1; fetching them again as a package skill would double-install them. */
 const BASE_SKILL_PACKAGE = "mesh-cli";
-/**
- * Every `node_modules/@mesh-tech` directory in the repo. In a pnpm workspace a
- * dependency is linked into the node_modules of the package that DECLARES it,
- * so `@mesh-tech/app-kit` — declared by `apps/<name>/` — is not under the repo
- * root's node_modules at all.
- */
 function meshTechScopeDirs(root, maxDepth = 6) {
     const scopes = [];
     const walk = (dir, depth) => {
@@ -111,8 +56,6 @@ function meshTechScopeDirs(root, maxDepth = 6) {
             if (!entry.isDirectory())
                 continue;
             if (entry.name === "node_modules") {
-                // Don't descend: the scope dir here already links everything this level
-                // can see, and `.pnpm/` would yield the same content many times over.
                 const scope = path.join(dir, entry.name, "@mesh-tech");
                 if (fs.existsSync(scope))
                     scopes.push(scope);
@@ -126,13 +69,6 @@ function meshTechScopeDirs(root, maxDepth = 6) {
     walk(root, 0);
     return scopes;
 }
-/**
- * Platform skills reachable from the target repo: every
- * `node_modules/@mesh-tech/<pkg>/skills/<domain>/SKILL.md`. Installed under
- * `mesh-<pkg>-<domain>` so a package's `core` skill can never collide with the
- * CLI's own `mesh-core`. One entry per `<pkg>/<domain>` — the same package
- * linked from several workspace packages is still one skill.
- */
 export function listPackageSkills(root) {
     const byName = new Map();
     for (const scopeDir of meshTechScopeDirs(root)) {
@@ -156,7 +92,6 @@ export function listPackageSkills(root) {
     }
     return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
 }
-/** Copy a skill's supporting files (references/, examples/, …) alongside SKILL.md. */
 function copySkillExtras(sourceDir, targetDir) {
     for (const entry of fs.readdirSync(sourceDir, { withFileTypes: true })) {
         if (entry.name === "SKILL.md")
@@ -164,12 +99,6 @@ function copySkillExtras(sourceDir, targetDir) {
         fs.cpSync(path.join(sourceDir, entry.name), path.join(targetDir, entry.name), { recursive: true });
     }
 }
-/**
- * Seed the app's OWN skill — the stub a developer grows into the guidance only
- * their app can carry. Written once and never touched again: it carries no
- * managed marker, so `sync` leaves it alone forever.
- * Returns the repo-relative path when it wrote one, else null.
- */
 export function seedAppSkill(root, appName, appRelPath) {
     const target = path.join(root, ".claude", "skills", appName, "SKILL.md");
     if (fs.existsSync(target))
@@ -182,7 +111,6 @@ export function seedAppSkill(root, appName, appRelPath) {
 }
 function planSync(root) {
     const items = [];
-    // 1. Base skills → .claude/skills/mesh-<name>/SKILL.md
     for (const skill of listBaseSkills()) {
         const target = path.join(root, ".claude", "skills", `mesh-${skill.name}`, "SKILL.md");
         const desired = renderManagedSkill(skill.source);
@@ -210,7 +138,6 @@ function planSync(root) {
             }
         }
     }
-    // 2. Platform skills fetched from installed @mesh-tech/* packages
     const packageSkills = listPackageSkills(root);
     for (const skill of packageSkills) {
         const targetDir = path.join(root, ".claude", "skills", skill.name);
@@ -251,7 +178,6 @@ function planSync(root) {
     if (packageSkills.length === 0 && meshTechScopeDirs(root).length === 0) {
         logInfo("No @mesh-tech packages installed yet — run `pnpm install`, then `mesh skills sync` again for the platform skills.");
     }
-    // 3. Intent gate hook (CLI-managed generated file — kept current)
     const hookSource = cliAsset("assets", "intent", "intent-claude-gate.mjs");
     const hookTarget = path.join(root, HOOK_RELATIVE);
     const hookDesired = fs.readFileSync(hookSource, "utf-8");
@@ -266,8 +192,6 @@ function planSync(root) {
                 fs.writeFileSync(hookTarget, hookDesired, { mode: 0o755 });
             },
         });
-    // 4. `@tanstack/intent` devDependency — the fence tells agents to run
-    //    `pnpm exec intent`, which only resolves when the repo pins it.
     const rootPkgPath = path.join(root, "package.json");
     if (fs.existsSync(rootPkgPath)) {
         let rootPkg = null;
@@ -287,9 +211,6 @@ function planSync(root) {
         else {
             items.push({
                 label,
-                // Writing the dependency does not install it. Bare `mesh skills sync`
-                // in an already-installed repo leaves `pnpm exec intent` unresolvable
-                // until the next install, so say so rather than reporting success.
                 remediation: "Added @tanstack/intent — run `pnpm install` so `pnpm exec intent` resolves.",
                 state: "write",
                 apply: () => {
@@ -301,7 +222,6 @@ function planSync(root) {
             });
         }
     }
-    // 5. .claude/settings.json SessionStart hook (JSON merge, idempotent)
     const settingsPath = path.join(root, ".claude", "settings.json");
     let settings = {};
     try {
@@ -336,7 +256,6 @@ function planSync(root) {
                 fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 1) + "\n");
             },
         });
-    // 6. AGENTS.md fence (non-Claude agents discover Intent skills too)
     const agentsPath = path.join(root, "AGENTS.md");
     const fence = fs.readFileSync(cliAsset("assets", "intent", "agents-fence.md"), "utf-8");
     const agentsCurrent = fs.existsSync(agentsPath) ? fs.readFileSync(agentsPath, "utf-8") : null;
@@ -352,7 +271,6 @@ function planSync(root) {
         });
     return items;
 }
-/** Run a sync (or check). Returns true when everything is in place. */
 export function syncSkills(root, opts = {}) {
     const items = planSync(root);
     let dirty = false;
@@ -396,4 +314,3 @@ export function registerSkillsCommands(program) {
         }
     });
 }
-//# sourceMappingURL=skills.js.map

package/dist/src/commands/stack.d.ts

@@ -1,17 +1,2 @@
-/**
- * mesh stack — Manage personal Pulumi stacks.
- *
- * mesh stack init             Create a personal dev stack (dev-{github-user})
- * mesh stack init --from uat  Base on a different stack
- *
- * Creates Pulumi.<stack>.yaml with:
- *   - mesh:deploy: false (skip K8s deployments — dev-only stack)
- *   - mesh:deployerRole copied from the base stack
- *   - aws:region copied from the base stack
- */
 import { Command } from "commander";
-/**
- * Find Pulumi.<stack>.yaml files in the app root.
- */
 export declare function registerStackCommand(program: Command): void;
-//# sourceMappingURL=stack.d.ts.map