@stacksjs/buddy 0.70.162 → 0.70.164

package/README.md

@@ -344,7 +344,7 @@ For help, discussion about best practices, or any other conversation that would
 
 For casual chit-chat with others using this package:
 
-[Join the Stacks Discord Server](https://discord.gg/stacksjs)
+[Join the Stacks Discord Server](https://stacksjs.com/discord)
 
 ## Postcardware
 

package/dist/cli.js

@@ -38,6 +38,7 @@ async function main() {
     await applyBuddyConfig(buddy);
   } catch {}
   if (needsFullSetup) {
+    p.ensureRuntimeDirectories();
     const { loadCommands, getCommandsToLoad, markLoaded } = await import("./lazy-commands.js"), { setup } = await import("./commands/setup.js");
     setup(buddy);
     markLoaded(buddy, "setup");

package/dist/commands/ai-context.d.ts

@@ -0,0 +1,13 @@
+import type { CLI, CliOptions } from '@stacksjs/types';
+export declare function generateAiContextOutput(options?: AiContextCommandOptions, projectRoot?: string): AiContextCommandResult;
+export declare function aiContext(buddy: CLI): void;
+export declare interface AiContextCommandOptions extends CliOptions {
+  json?: boolean
+  output?: string
+  maxChars?: string | number
+  model?: string
+}
+export declare interface AiContextCommandResult {
+  output: string
+  outputPath: string | null
+}

package/dist/commands/ai-context.js

@@ -0,0 +1,29 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import process from "node:process";
+import { buildProjectContext } from "@stacksjs/ai";
+import { onUnknownSubcommand } from "@stacksjs/cli";
+export function generateAiContextOutput(options = {}, projectRoot = process.cwd()) {
+  const maxChars = options.maxChars === void 0 ? void 0 : Number(options.maxChars), result = buildProjectContext(projectRoot, { maxChars, model: options.model }), output = options.json ? `${JSON.stringify(result, null, 2)}
+` : `${result.text}
+
+Context metrics:
+${JSON.stringify(result.metrics, null, 2)}
+`;
+  if (!options.output)
+    return { output, outputPath: null };
+  const outputPath = resolve(projectRoot, String(options.output));
+  mkdirSync(dirname(outputPath), { recursive: !0 });
+  writeFileSync(outputPath, output);
+  return { output, outputPath };
+}
+export function aiContext(buddy) {
+  buddy.command("ai:context", "Generate compact deterministic project context for coding models").option("-J, --json", "Emit the versioned machine-readable context contract", { default: !1 }).option("-o, --output [path]", "Write output to a file instead of stdout").option("--max-chars [characters]", "Maximum characters in the prompt context payload", { default: 4000 }).option("--model [model]", "Model family used for the heuristic token estimate", { default: "gpt-4o" }).example("buddy ai:context").example("buddy ai:context --json").example("buddy ai:context --json --output storage/framework/runtime/ai-context.json").action((options) => {
+    const generated = generateAiContextOutput(options);
+    if (generated.outputPath)
+      console.log(`Wrote AI project context to ${generated.outputPath}`);
+    else
+      process.stdout.write(generated.output);
+  });
+  onUnknownSubcommand(buddy, "ai:context");
+}

package/dist/commands/create.js

@@ -38,8 +38,8 @@ export function create(buddy) {
       log.error(result.error);
       process.exit(ExitCode.FatalError);
     }
-    await ensureEnv(path, options);
     ensureExecutableScripts(path);
+    await ensureEnv(path, options);
     await install(path, options);
     if (options.minimal)
       await stripFeatures(path);

package/dist/commands/deploy.d.ts

@@ -18,11 +18,21 @@ import type { CLI } from '@stacksjs/types';
  * ciphertext it never had a chance to decrypt (no DOTENV_PRIVATE_KEY_* in
  * that 2-key set).
  *
+ * Keys namespaced to another tenant on this box (`cloud.tenants` in
+ * `config/cloud.ts`) are dropped here, before anything is shipped. Those
+ * projects deploy from their own repositories with their own env files and
+ * never need the owner's copy — and because ts-cloud treats `site.env` as the
+ * complete `.env`, leaving them in writes one tenant's secrets into an
+ * unrelated site's `.env` on disk.
+ *
  * Returns `{}` (not an error) when the file doesn't exist or fails to
  * parse — an app with no `.env.production` yet shouldn't block deploying
  * with whatever `site.env` overrides it does have.
+ *
+ * @param environment - Which `.env.<environment>` to read.
+ * @param tsCloudConfig - The deploy target's ts-cloud config, read for `project.slug`.
  */
-export declare function resolveDeployEnvValues(environment: 'production' | 'staging' | 'development'): Promise<Record<string, string>>;
+export declare function resolveDeployEnvValues(environment: 'production' | 'staging' | 'development', tsCloudConfig?: { project?: { slug?: string } }): Promise<Record<string, string>>;
 /**
  * Merge the deploy-target's resolved env values underneath each site's own
  * explicit `env` overrides, stripping a general `PORT` when the site

package/dist/commands/deploy.js

@@ -1,6 +1,6 @@
 import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { join, relative } from "node:path";
 import process from "node:process";
 import { runAction } from "@stacksjs/actions";
 import { italic, onUnknownSubcommand, outro, prompts, runCommand } from "@stacksjs/cli";
@@ -395,7 +395,7 @@ async function pollUntil(opts) {
   let lastHeartbeat = 0;
   for (;; )
     try {
-      opts.check();
+      await opts.check();
       return;
     } catch {
       const elapsedSecs = Math.floor((Date.now() - started) / 1000);
@@ -408,33 +408,18 @@ async function pollUntil(opts) {
       await new Promise((r) => setTimeout(r, opts.intervalMs ?? 5000));
     }
 }
-async function waitForRemoteReady(ip, verbose) {
-  const { execSync } = await import("node:child_process"), sshArgs = [
-    "-o",
-    "StrictHostKeyChecking=no",
-    "-o",
-    "UserKnownHostsFile=/dev/null",
-    "-o",
-    "BatchMode=yes",
-    "-o",
-    "ConnectTimeout=10",
-    `root@${ip}`
-  ], run = (remote) => execSync(`ssh ${sshArgs.map((a) => `'${a}'`).join(" ")} '${remote.replace(/'/g, "'\\''")}'`, {
-    encoding: "utf8",
-    stdio: ["ignore", "pipe", verbose ? "inherit" : "pipe"]
-  }), sshWaitSecs = readWaitSecs("TS_CLOUD_SSH_WAIT_SECS", 480);
+async function waitForRemoteReady(ip) {
+  const { sshExecOrThrow } = await import("@stacksjs/ts-cloud"), run = (remote) => sshExecOrThrow(ip, remote, { user: "root", connectTimeoutSec: 10 }), sshWaitSecs = readWaitSecs("TS_CLOUD_SSH_WAIT_SECS", 480);
   await pollUntil({
     label: "Waiting for SSH to come up",
     timeoutSecs: sshWaitSecs,
-    check: () => {
-      run("true");
-    },
+    check: () => run("true"),
     timeoutMessage: (elapsed) => `SSH did not become reachable on ${ip} within ${fmtDuration(sshWaitSecs)} (waited ${elapsed}s). ` + "The box may still be booting \u2014 raise TS_CLOUD_SSH_WAIT_SECS and retry."
   });
   log.success("SSH is up");
   log.info("Waiting for cloud-init (installing bun + caddy)...");
   try {
-    run("cloud-init status --wait || true");
+    await run("cloud-init status --wait || true");
   } catch (err) {
     log.debug("cloud-init status --wait returned non-zero (continuing):", err);
   }
@@ -442,14 +427,20 @@ async function waitForRemoteReady(ip, verbose) {
   await pollUntil({
     label: "Waiting for the bun runtime",
     timeoutSecs: bootWaitSecs,
-    check: () => {
-      run("test -x /usr/local/bin/bun");
-    },
+    check: () => run("test -x /usr/local/bin/bun"),
     timeoutMessage: (elapsed) => `bun runtime did not appear at /usr/local/bin/bun within ${fmtDuration(bootWaitSecs)} (waited ${elapsed}s). ` + "cloud-init may have failed \u2014 SSH in and check /var/log/cloud-init-output.log; " + "raise TS_CLOUD_BOOT_WAIT_SECS for slow regions."
   });
   log.success("Server is ready (bun installed)");
 }
-export async function resolveDeployEnvValues(environment) {
+async function resolveDeclaredTenants() {
+  try {
+    const { config } = await import("@stacksjs/config"), tenants = config.cloud?.tenants;
+    return Array.isArray(tenants) ? tenants.filter((slug) => typeof slug === "string") : [];
+  } catch {
+    return [];
+  }
+}
+export async function resolveDeployEnvValues(environment, tsCloudConfig) {
   const fileName = environment === "production" ? ".env.production" : environment === "staging" ? ".env.staging" : existsSync(p.projectPath(".env.development")) ? ".env.development" : ".env", filePath = p.projectPath(fileName);
   if (!existsSync(filePath))
     return {};
@@ -465,7 +456,13 @@ export async function resolveDeployEnvValues(environment) {
         continue;
       values[key] = String(value);
     }
-    return values;
+    const { foreignTenantKeys, partitionTenantEnv } = await import("@stacksjs/env"), partition = partitionTenantEnv(values, {
+      self: tsCloudConfig?.project?.slug,
+      tenants: await resolveDeclaredTenants()
+    });
+    for (const { tenant, keys } of foreignTenantKeys(partition))
+      log.warn(`[deploy] Skipping ${keys.length} '${tenant}' key(s) in ${fileName} \u2014 they belong to that tenant's own ` + `repository, and shipping them writes its secrets into this project's site .env files. Remove them with: buddy env:check --file ${fileName}. Keys: ${keys.join(", ")}`);
+    return partition.own;
   } catch (error) {
     log.debug(`[deploy] Failed to resolve ${fileName} for site env merging:`, error);
     return {};
@@ -716,7 +713,7 @@ async function runHetznerDeploy(args) {
     log.error("Provisioned server has no public IP \u2014 cannot deploy over SSH.");
     process.exit(ExitCode.FatalError);
   }
-  await waitForRemoteReady(ip, verbose);
+  await waitForRemoteReady(ip);
   const { execSync } = await import("node:child_process"), { tmpdir } = await import("node:os"), sites = applyEnvironmentToSites(tsCloudConfig.sites || {}, environment, tsCloudConfig), slug = tsCloudConfig.project?.slug || "app";
   let sha;
   try {
@@ -732,7 +729,11 @@ async function runHetznerDeploy(args) {
     ".cache",
     "bin",
     "dist",
+    relative(p.projectPath(), p.stxPath()).replace(/\/$/, ""),
     ".stx",
+    relative(p.projectPath(), p.cloudStatePath()).replace(/\/$/, ""),
+    ".ts-cloud",
+    relative(p.projectPath(), p.frameworkRuntimePath()).replace(/\/$/, ""),
     "tmp",
     "temp",
     ".DS_Store",
@@ -771,7 +772,7 @@ async function runHetznerDeploy(args) {
   }
   if (docker)
     await buildContainerImageWithPantry({ slug, sites, verbose });
-  const resolvedDeployEnv = await resolveDeployEnvValues(environment), sitesWithResolvedEnv = mergeSiteDeployEnv(sites, resolvedDeployEnv);
+  const resolvedDeployEnv = await resolveDeployEnvValues(environment, tsCloudConfig), sitesWithResolvedEnv = mergeSiteDeployEnv(sites, resolvedDeployEnv);
   for (const [envKey, envValue] of Object.entries(resolvedDeployEnv))
     if (process.env[envKey] === void 0)
       process.env[envKey] = envValue;

package/dist/commands/dev.js

@@ -4,10 +4,10 @@ import readline from "node:readline";
 import process from "node:process";
 import { bold, cyan, dim, green, intro, log, onUnknownSubcommand, outro, prompts, runCommand, yellow } from "@stacksjs/cli";
 import { homedir } from "node:os";
-import { dirname, join } from "node:path";
+import { dirname, join, relative } from "node:path";
 import { fileURLToPath } from "node:url";
 import { Action } from "@stacksjs/enums";
-import { libsPath, projectPath } from "@stacksjs/path";
+import { libsPath, projectPath, stxPath } from "@stacksjs/path";
 import { ExitCode } from "@stacksjs/types";
 import { version } from "../../package.json";
 const DEV_BOOT_STARTING_LINE_COUNT = 3;
@@ -215,17 +215,32 @@ export function dev(buddy) {
   onUnknownSubcommand(buddy, "dev");
 }
 export async function startDevelopmentServer(_options, _startTime) {
-  const options = _options, startedAt = _startTime, appUrl = process.env.APP_URL ?? "stacks.localhost", nativeMode = options.native === !0, proxyManagedExternally = process.env.STACKS_PROXY_MANAGED === "1", frontendPort = Number(process.env.PORT) || 3000, apiPort = Number(process.env.PORT_API) || 3008, docsPort = Number(process.env.PORT_DOCS) || 3006, dashboardPort = Number(process.env.PORT_ADMIN) || 3002, includeDashboard = process.env.STACKS_DEV_DASHBOARD === "1", domain = resolvePrettyDevDomain(appUrl, nativeMode), appLooksCustom = domain !== null, localhostOnly = process.env.STACKS_DEV_LOCALHOST === "1", prettyUrlsRequested = appLooksCustom && !localhostOnly, systemAuthorized = !prettyUrlsRequested || proxyManagedExternally ? !0 : await canStartPrettyDevProxy(), usePrettyUrls = shouldUsePrettyDevUrls({
+  const options = _options, startedAt = _startTime, appUrl = process.env.APP_URL ?? "stacks.localhost", nativeMode = options.native === !0, proxyManagedExternally = process.env.STACKS_PROXY_MANAGED === "1", preferredFrontendPort = Number(process.env.PORT) || 3000, preferredApiPort = Number(process.env.PORT_API) || 3008, preferredDocsPort = Number(process.env.PORT_DOCS) || 3006, preferredDashboardPort = Number(process.env.PORT_ADMIN) || 3002;
+  if (process.env.STACKS_DEV_NO_KILL !== "1")
+    await cleanupStaleDevProcesses([
+      preferredFrontendPort,
+      preferredApiPort,
+      preferredDocsPort,
+      preferredDashboardPort
+    ]);
+  const portShifts = [], claimPort = async (label, preferred) => {
+    if (proxyManagedExternally)
+      return preferred;
+    const port = await findAvailablePort(preferred);
+    if (port !== preferred)
+      portShifts.push(`${label} :${preferred} \u2192 :${port}`);
+    return port;
+  }, frontendPort = await claimPort("Frontend", preferredFrontendPort), apiPort = await claimPort("API", preferredApiPort), docsPort = await claimPort("Docs", preferredDocsPort), dashboardPort = await claimPort("Dashboard", preferredDashboardPort);
+  process.env.PORT = String(frontendPort);
+  process.env.PORT_API = String(apiPort);
+  process.env.PORT_DOCS = String(docsPort);
+  process.env.PORT_ADMIN = String(dashboardPort);
+  const includeDashboard = process.env.STACKS_DEV_DASHBOARD === "1", domain = resolvePrettyDevDomain(appUrl, nativeMode), appLooksCustom = domain !== null, localhostOnly = process.env.STACKS_DEV_LOCALHOST === "1", prettyUrlsRequested = appLooksCustom && !localhostOnly, systemAuthorized = !prettyUrlsRequested || proxyManagedExternally ? !0 : await canStartPrettyDevProxy(), usePrettyUrls = shouldUsePrettyDevUrls({
     domain,
     localhostOnly,
     proxyManagedExternally,
     systemAuthorized
-  }), prettySetupRequired = prettyUrlsRequested && !usePrettyUrls, hasCustomDomain = usePrettyUrls && !proxyManagedExternally, displayedDomain = usePrettyUrls ? domain : null, dashboardDomain = displayedDomain ? `dashboard.${displayedDomain}` : null, frontendUrl = displayedDomain ? `https://${displayedDomain}` : `http://localhost:${frontendPort}`, apiUrl = displayedDomain ? `https://${displayedDomain}/api` : `http://localhost:${apiPort}`, docsUrl = displayedDomain ? `https://${displayedDomain}/docs` : `http://localhost:${docsPort}`, dashboardUrl = dashboardDomain ? `https://${dashboardDomain}` : `http://localhost:${dashboardPort}`, managedPorts = [
-    frontendPort,
-    apiPort,
-    docsPort,
-    ...includeDashboard ? [dashboardPort] : []
-  ];
+  }), prettySetupRequired = prettyUrlsRequested && !usePrettyUrls, hasCustomDomain = usePrettyUrls && !proxyManagedExternally, displayedDomain = usePrettyUrls ? domain : null, dashboardDomain = displayedDomain ? `dashboard.${displayedDomain}` : null, frontendUrl = displayedDomain ? `https://${displayedDomain}` : `http://localhost:${frontendPort}`, apiUrl = displayedDomain ? `https://${displayedDomain}/api` : `http://localhost:${apiPort}`, docsUrl = displayedDomain ? `https://${displayedDomain}/docs` : `http://localhost:${docsPort}`, dashboardUrl = dashboardDomain ? `https://${dashboardDomain}` : `http://localhost:${dashboardPort}`;
   process.env.STACKS_PROXY_MANAGED = "1";
   process.env.STACKS_DEV_QUIET = "1";
   console.log();
@@ -234,10 +249,12 @@ export async function startDevelopmentServer(_options, _startTime) {
     console.log(`  ${dim("    ")}${dim("Run `./buddy setup:ssl` once, then restart `./buddy dev`.")}`);
     console.log();
   }
+  if (portShifts.length > 0) {
+    console.log(`  ${yellow("\u26A0")}  ${yellow("Ports in use by another process")} ${dim(`- ${portShifts.join(", ")}`)}`);
+    console.log();
+  }
   console.log(`  ${bold(cyan("stacks"))} ${dim(`v${version}`)}  ${dim("starting\u2026")}`);
   console.log();
-  if (process.env.STACKS_DEV_NO_KILL !== "1")
-    await cleanupStaleDevProcesses(managedPorts);
   const rpxTlsPreflight = hasCustomDomain && domain ? prepareRpxTlsForDev({ domain, includeDashboard, options }) : Promise.resolve();
   if (localhostOnly && domain && !proxyManagedExternally)
     removeStalePublicDomainOverrides(domain, includeDashboard, options.verbose ?? !1).catch(() => {});
@@ -432,16 +449,16 @@ function printDevReadyBanner(input) {
   console.log();
 }
 function printDevEngineNotes() {
-  const routesFile = join(projectPath(), ".stx/routes.ts"), crosswindConfig = join(projectPath(), "config/crosswind.ts");
+  const routesFile = stxPath("routes.ts"), routesLabel = relative(projectPath(), routesFile), crosswindConfig = join(projectPath(), "config/crosswind.ts");
   if (existsSync(crosswindConfig) || existsSync(join(projectPath(), "crosswind.config.ts")))
     console.log(`  ${green("[Crosswind]")} ${dim("CSS engine loaded")}`);
   if (existsSync(routesFile))
     try {
       const routeCount = (readFileSync(routesFile, "utf8").match(/pattern:/g) ?? []).length;
       if (routeCount > 0)
-        console.log(`  ${green("[stx]")} ${dim(`Generated ${routeCount} routes \u2192 .stx/routes.ts`)}`);
+        console.log(`  ${green("[stx]")} ${dim(`Generated ${routeCount} routes \u2192 ${routesLabel}`)}`);
     } catch {
-      console.log(`  ${green("[stx]")} ${dim("Routes manifest \u2192 .stx/routes.ts")}`);
+      console.log(`  ${green("[stx]")} ${dim(`Routes manifest \u2192 ${routesLabel}`)}`);
     }
 }
 async function launchNativeAppWindow(url, options) {
@@ -617,6 +634,19 @@ async function probeDevServerHttp(port) {
       return !0;
   return !1;
 }
+async function findAvailablePort(preferred, attempts = 20) {
+  for (let port = preferred;port < preferred + attempts; port++) {
+    let server;
+    try {
+      server = Bun.serve({ port, hostname: "0.0.0.0", reusePort: !1, fetch: () => new Response });
+    } catch {
+      continue;
+    }
+    server.stop(!0);
+    return port;
+  }
+  return preferred;
+}
 async function waitForPort(port, timeoutMs) {
   const deadline = Date.now() + timeoutMs;
   while (Date.now() < deadline) {

package/dist/commands/docs/buddy-commands.d.ts

@@ -0,0 +1,8 @@
+import type { BuddyCommandInventoryEntry } from '../list';
+export declare function renderBuddyCommandReference(inventory: BuddyInventory): string;
+export declare function loadBuddyInventory(): BuddyInventory;
+export declare function run(): Promise<void>;
+declare interface BuddyInventory {
+  commands: BuddyCommandInventoryEntry[]
+  total: number
+}

package/dist/commands/docs/buddy-commands.js

@@ -0,0 +1,116 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+const root = resolve(import.meta.dir, "../../../../../../.."), outputPath = resolve(root, "docs/guide/buddy/commands.md"), cliPath = resolve(root, "storage/framework/core/buddy/src/cli.ts");
+function markdown(value) {
+  return String(value).replaceAll("\\", "\\\\").replaceAll("|", "\\|").replaceAll(`
+`, "<br>");
+}
+function code(value) {
+  return `\`${String(value).replaceAll("`", "\\`")}\``;
+}
+function optionFlags(option) {
+  return option.flags.map((flag) => code(`${flag.length === 1 ? "-" : "--"}${flag}`)).join(", ");
+}
+function optionKind(option) {
+  return [
+    option.boolean ? "boolean" : "value",
+    option.required ? "required" : "optional",
+    ...option.negated ? ["negated"] : []
+  ].join(", ");
+}
+function argumentSyntax(argument) {
+  const value = `${argument.name}${argument.variadic ? "..." : ""}`;
+  return code(argument.required ? `<${value}>` : `[${value}]`);
+}
+function commandSection(command) {
+  const lines = [
+    `### ${code(command.name)}`,
+    "",
+    command.description || "No description provided.",
+    "",
+    `- Usage: ${code(command.usage)}`,
+    `- Namespace: ${command.namespace ? code(command.namespace) : "none"}`,
+    `- Aliases: ${command.aliases.length ? command.aliases.map(code).join(", ") : "none"}`,
+    `- Arguments: ${command.arguments.length ? command.arguments.map(argumentSyntax).join(", ") : "none"}`
+  ];
+  if (command.options.length)
+    lines.push("", "| Option | Description | Contract | Default |", "| --- | --- | --- | --- |", ...command.options.map((option) => `| ${optionFlags(option)} | ${markdown(option.description || "\u2014")} | ${optionKind(option)} | ${option.default === void 0 ? "\u2014" : code(JSON.stringify(option.default))} |`));
+  if (command.examples.length)
+    lines.push("", "Examples:", "", "```bash", ...command.examples, "```");
+  return lines.join(`
+`);
+}
+export function renderBuddyCommandReference(inventory) {
+  const commands = [...inventory.commands].sort((a, b) => a.name.localeCompare(b.name));
+  if (inventory.total !== commands.length)
+    throw Error(`Buddy inventory total ${inventory.total} does not match ${commands.length} commands`);
+  if (new Set(commands.map((command) => command.name)).size !== commands.length)
+    throw Error("Buddy inventory contains duplicate canonical command names");
+  const groups = new Map;
+  for (const command of commands) {
+    const group = command.namespace || (command.name.includes(":") ? command.name.split(":")[0] : "general"), entries = groups.get(group) || [];
+    entries.push(command);
+    groups.set(group, entries);
+  }
+  const groupSummary = [...groups.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([group, entries]) => `| ${code(group)} | ${entries.length} |`);
+  return `${[
+    "---",
+    "title: Buddy Command Reference",
+    "description: Generated reference for every Buddy command, argument, option, alias, default, and example.",
+    "---",
+    "<!-- Generated by storage/framework/core/buddy/src/commands/docs/buddy-commands.ts. Do not edit by hand. -->",
+    "",
+    "# Buddy Command Reference",
+    "",
+    `This reference is generated from Buddy's runtime command registry and currently contains **${commands.length} commands**. Run \`bun run docs:buddy\` after changing the registry; CI rejects stale output.`,
+    "",
+    "## Command groups",
+    "",
+    "| Group | Commands |",
+    "| --- | ---: |",
+    ...groupSummary,
+    "",
+    "## Commands",
+    "",
+    ...commands.flatMap((command) => [commandSection(command), ""])
+  ].join(`
+`).split(`
+`).map((line) => line.trimEnd()).join(`
+`).trimEnd()}
+`;
+}
+export function loadBuddyInventory() {
+  const result = Bun.spawnSync([process.execPath, cliPath, "list", "--json"], {
+    cwd: root,
+    env: { ...process.env, NO_COLOR: "1" },
+    stdout: "pipe",
+    stderr: "pipe"
+  });
+  if (result.exitCode !== 0)
+    throw Error(`Buddy command inventory failed (${result.exitCode}): ${result.stderr.toString().trim()}`);
+  const inventory = JSON.parse(result.stdout.toString());
+  if (!Array.isArray(inventory.commands) || !Number.isInteger(inventory.total))
+    throw Error("Buddy command inventory returned an invalid payload");
+  return inventory;
+}
+export async function run() {
+  const mode = process.argv.includes("--write") ? "write" : process.argv.includes("--check") ? "check" : null;
+  if (!mode) {
+    console.error("usage: bun storage/framework/core/buddy/src/commands/docs/buddy-commands.ts --write | --check");
+    process.exit(2);
+  }
+  const expected = renderBuddyCommandReference(loadBuddyInventory());
+  if (mode === "write") {
+    mkdirSync(dirname(outputPath), { recursive: !0 });
+    writeFileSync(outputPath, expected);
+    console.log(`Wrote ${outputPath}`);
+  } else {
+    if (!existsSync(outputPath))
+      throw Error("Buddy command reference is missing; run bun run docs:buddy");
+    if (readFileSync(outputPath, "utf8") !== expected)
+      throw Error("Buddy command reference is stale; run bun run docs:buddy");
+    console.log("Buddy command reference matches the runtime registry");
+  }
+}
+if (import.meta.main)
+  await run();

package/dist/commands/docs/buddy-commands.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/commands/docs/buddy-commands.test.js

@@ -0,0 +1,38 @@
+import { describe, expect, it } from "bun:test";
+import { renderBuddyCommandReference } from "./buddy-commands";
+const command = {
+  name: "deploy",
+  description: "Deploy the application",
+  aliases: ["ship"],
+  usage: "$ buddy deploy [environment]",
+  arguments: [{ name: "environment", required: !1, variadic: !1 }],
+  options: [{
+    name: "region",
+    flags: ["r", "region"],
+    description: "Cloud region",
+    required: !0,
+    boolean: !1,
+    negated: !1,
+    default: "us-east-1"
+  }],
+  examples: ["buddy deploy production"]
+};
+describe("Buddy command reference", () => {
+  it("renders every command contract field", () => {
+    const result = renderBuddyCommandReference({ commands: [command], total: 1 });
+    expect(result).toContain("**1 commands**");
+    expect(result).toContain("### `deploy`");
+    expect(result).toContain("Aliases: `ship`");
+    expect(result).toContain("Arguments: `[environment]`");
+    expect(result).toContain('| `-r`, `--region` | Cloud region | value, required | `"us-east-1"` |');
+    expect(result).toContain("buddy deploy production");
+  });
+  it("sorts commands and rejects incomplete inventories", () => {
+    const about = { ...command, name: "about" }, result = renderBuddyCommandReference({ commands: [command, about], total: 2 });
+    expect(result.indexOf("### `about`")).toBeLessThan(result.indexOf("### `deploy`"));
+    expect(() => renderBuddyCommandReference({ commands: [command], total: 2 })).toThrow("does not match");
+  });
+  it("rejects duplicate canonical names", () => {
+    expect(() => renderBuddyCommandReference({ commands: [command, command], total: 2 })).toThrow("duplicate");
+  });
+});

package/dist/commands/docs/generated-artifacts.d.ts

@@ -0,0 +1,3 @@
+import { type OpenApiDocument } from '../../../../api/src/generate-types';
+export declare function validateOpenApi(document: OpenApiDocument): string[];
+export declare function run(): Promise<void>;

package/dist/commands/docs/generated-artifacts.js

@@ -0,0 +1,69 @@
+import { readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { generateOpenApi } from "../../../../api/src/generate-openapi";
+import { renderOpenApiTypes } from "../../../../api/src/generate-types";
+const root = resolve(import.meta.dir, "../../../../../../.."), openApiPath = resolve(root, "storage/framework/api/openapi.json"), apiTypesPath = resolve(root, "storage/framework/api/api-types.ts");
+export function validateOpenApi(document) {
+  const errors = [], paths = Object.entries(document.paths || {});
+  if (paths.length < 10)
+    errors.push("OpenAPI document has fewer than 10 registered paths");
+  const operationIds = new Set;
+  for (const [route, item] of paths)
+    for (const [method, operation] of Object.entries(item)) {
+      if (!operation.operationId)
+        errors.push(`${method.toUpperCase()} ${route}: operationId is missing`);
+      else if (operationIds.has(operation.operationId))
+        errors.push(`${method.toUpperCase()} ${route}: duplicate operationId ${operation.operationId}`);
+      else
+        operationIds.add(operation.operationId);
+      for (const parameter of operation.parameters || [])
+        if (parameter.in === "path" && !parameter.required)
+          errors.push(`${method.toUpperCase()} ${route}: path parameter ${parameter.name} must be required`);
+    }
+  return errors;
+}
+async function expectedArtifacts() {
+  const document = await generateOpenApi({ write: !1 }), errors = validateOpenApi(document);
+  if (errors.length)
+    throw Error(errors.join(`
+`));
+  return {
+    openApi: JSON.stringify(document, null, 2),
+    apiTypes: renderOpenApiTypes(document)
+  };
+}
+async function write() {
+  const expected = await expectedArtifacts();
+  writeFileSync(openApiPath, expected.openApi);
+  writeFileSync(apiTypesPath, expected.apiTypes);
+  console.log("Generated OpenAPI and API type artifacts");
+}
+async function check() {
+  const expected = await expectedArtifacts(), errors = [];
+  if (readFileSync(openApiPath, "utf8") !== expected.openApi)
+    errors.push("storage/framework/api/openapi.json is stale");
+  if (readFileSync(apiTypesPath, "utf8") !== expected.apiTypes)
+    errors.push("storage/framework/api/api-types.ts is stale");
+  if (errors.length)
+    throw Error(`${errors.join(`
+`)}
+Run bun run docs:artifacts and review the generated diff.`);
+  console.log(`Generated API artifacts are current (${Object.keys(JSON.parse(expected.openApi).paths).length} paths)`);
+}
+export async function run() {
+  try {
+    if (process.argv.includes("--write"))
+      await write();
+    else if (process.argv.includes("--check"))
+      await check();
+    else {
+      console.error("usage: bun storage/framework/core/buddy/src/commands/docs/generated-artifacts.ts --write | --check");
+      process.exit(2);
+    }
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  }
+}
+if (import.meta.main)
+  await run();

package/dist/commands/docs/generated-artifacts.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/commands/docs/generated-artifacts.test.js

@@ -0,0 +1,19 @@
+import { describe, expect, it } from "bun:test";
+import { validateOpenApi } from "./generated-artifacts";
+describe("generated API artifact validation", () => {
+  it("rejects empty, duplicate, and optional path evidence", () => {
+    expect(validateOpenApi({ paths: {} })).toContain("OpenAPI document has fewer than 10 registered paths");
+    const paths = {};
+    for (let index = 0;index < 10; index++)
+      paths[`/items/${index}/{id}`] = {
+        get: {
+          operationId: index < 2 ? "duplicate" : `get_${index}`,
+          parameters: [{ name: "id", in: "path", required: index !== 2, schema: { type: "string" } }],
+          responses: {}
+        }
+      };
+    const errors = validateOpenApi({ paths });
+    expect(errors).toContain("GET /items/1/{id}: duplicate operationId duplicate");
+    expect(errors).toContain("GET /items/2/{id}: path parameter id must be required");
+  });
+});

package/dist/commands/docs/links.d.ts

@@ -0,0 +1,18 @@
+/** True for links this checker deliberately does not resolve on disk. */
+export declare function isSkippableLink(target: string): boolean;
+/** Extract inline-link targets with 1-based line numbers, skipping code. */
+export declare function extractLinks(content: string): Array<{ target: string, line: number }>;
+/**
+ * On-disk paths a link could legitimately resolve to. Absolute (`/x`) links are
+ * rooted at `docsRoot`; relative links at the file's directory. Extensionless
+ * links also try `.md` and `index.md` (VitePress clean URLs), and `.html` links
+ * try their `.md` source.
+ */
+export declare function resolveCandidates(target: string, fileDir: string, docsRoot: string): string[];
+export declare function checkDocsLinks(docsRoot?: unknown): BrokenDocLink[];
+export declare function run(): Promise<void>;
+export declare interface BrokenDocLink {
+  file: string
+  line: number
+  target: string
+}