@stacksjs/buddy 0.70.257 → 0.70.259

package/dist/commands/dns.js

@@ -1,103 +1,3 @@
-import process from "node:process";
-import { log, onUnknownSubcommand } from "@stacksjs/cli";
-import { config } from "@stacksjs/config";
-import { renderDnsConfig, resolveLiveRecords, syncDnsConfig } from "@stacksjs/dns";
-import { ExitCode } from "@stacksjs/types";
-import { loadProjectDnsConfig } from "../config";
-export function dns(buddy) {
-  const descriptions = {
-    dns: "Lists the DNS records for a domain",
-    query: "Host name or IP address to query",
-    type: "Type of the DNS record being queried (A, MX, NS\u2026)",
-    nameserver: "Address of the nameserver to send packets to",
-    class: "Network class of the DNS record being queried (IN, CH, HS)",
-    udp: "Use the DNS protocol over UDP",
-    tcp: "Use the DNS protocol over TCP",
-    tls: "Use the DNS-over-TLS protocol",
-    https: "Use the DNS-over-HTTPS protocol",
-    short: "Short mode: display nothing but the first result",
-    json: "Display the output as JSON",
-    project: "Target a specific project",
-    verbose: "Enable verbose output"
-  };
-  buddy.command("dns [domain]", descriptions.dns).option("-q, --query <query>", descriptions.query).option("-t, --type <type>", descriptions.type, { default: "A" }).option("-n, --nameserver <nameserver>", descriptions.nameserver).option("--class <class>", descriptions.class).option("-U, --udp", descriptions.udp).option("-T, --tcp", descriptions.tcp).option("-S, --tls", descriptions.tls).option("-H, --https", descriptions.https).option("-1, --short", descriptions.short, { default: !1 }).option("-J, --json", descriptions.json, { default: !1 }).option("-p, --project [project]", descriptions.project, { default: !1 }).option("--verbose", descriptions.verbose, { default: !1 }).action(async (domain, options) => {
-    log.debug("Running `buddy dns [domain]` ...", options);
-    const targetDomain = domain || config.app.url;
-    let DnsClient, formatOutput;
-    try {
-      const dnsx = await import("@stacksjs/dnsx");
-      DnsClient = dnsx.DnsClient;
-      formatOutput = dnsx.formatOutput;
-    } catch (err) {
-      log.error("`buddy dns` needs the @stacksjs/dnsx runtime, but only the type declarations are currently published. Install a build with the JS runtime (or wait for the next dnsx release) and re-run.");
-      log.debug(`[dns] import failure: ${err instanceof Error ? err.message : String(err)}`);
-      process.exit(ExitCode.FatalError);
-    }
-    try {
-      const client = new DnsClient({
-        domains: [targetDomain],
-        type: options.type,
-        nameserver: options.nameserver,
-        class: options.class,
-        udp: options.udp,
-        tcp: options.tcp,
-        tls: options.tls,
-        https: options.https,
-        short: options.short,
-        json: options.json,
-        verbose: options.verbose
-      }), startTime = performance.now(), responses = await client.query(), duration = performance.now() - startTime, output = formatOutput(responses, {
-        json: options.json ?? !1,
-        short: options.short ?? !1,
-        showDuration: duration,
-        colors: { enabled: !0 },
-        rawSeconds: !1
-      });
-      console.log(output);
-    } catch (error) {
-      log.error(`DNS query failed: ${error instanceof Error ? error.message : String(error)}`);
-      process.exit(ExitCode.FatalError);
-    }
-    process.exit(ExitCode.Success);
-  });
-  const bareDomain = (input) => (input || config.app.url || "").replace(/^[a-z]+:\/\//i, "").replace(/[/:].*$/, "");
-  buddy.command("dns:pull [domain]", "Print a domain's live DNS records as a config/dns.ts block").option("--verbose", descriptions.verbose, { default: !1 }).action(async (domain, options) => {
-    const target = bareDomain(domain);
-    log.debug(`Running \`buddy dns:pull ${target}\` ...`, options);
-    const records = await resolveLiveRecords(target);
-    if (!records.length) {
-      log.error(`No DNS records resolved for ${target}.`);
-      process.exit(ExitCode.FatalError);
-    }
-    console.log(renderDnsConfig(target, records));
-    process.exit(ExitCode.Success);
-  });
-  buddy.command("dns:diff [domain]", "Show which config/dns.ts records are missing from the live zone").option("--verbose", descriptions.verbose, { default: !1 }).action(async (domain, options) => {
-    const target = bareDomain(domain);
-    log.debug(`Running \`buddy dns:diff ${target}\` ...`, options);
-    const dnsConfig = await loadProjectDnsConfig(config.dns), { plan, provider } = await syncDnsConfig(target, dnsConfig, { dryRun: !0 });
-    for (const item of plan.items) {
-      const detail = item.record.type === "TXT" || item.record.type === "MX" ? ` ${item.record.content}` : ` \u2192 ${item.record.content}`;
-      console.log(`  ${item.action === "create" ? "+ create" : "  keep  "} ${item.record.type.padEnd(5)} ${item.record.name}${detail}`);
-    }
-    console.log(`
-${plan.create.length} to create, ${plan.keep.length} already present (${provider ? `registrar: ${provider}` : "public DNS"})`);
-    process.exit(ExitCode.Success);
-  });
-  buddy.command("dns:sync [domain]", "Additively sync config/dns.ts to the registrar (creates missing records; never deletes or overwrites)").option("--dry-run", "Show the plan without writing any records", { default: !1 }).option("--verbose", descriptions.verbose, { default: !1 }).action(async (domain, options) => {
-    const target = bareDomain(domain);
-    log.debug(`Running \`buddy dns:sync ${target}\` ...`, options);
-    const dnsConfig = await loadProjectDnsConfig(config.dns), result = await syncDnsConfig(target, dnsConfig, { dryRun: options.dryRun });
-    if (!result.provider && !options.dryRun) {
-      log.warn(`No DNS provider credentials found (e.g. PORKBUN_API_KEY / PORKBUN_SECRET_KEY) \u2014 nothing was synced. ${result.plan.create.length} record(s) would be created.`);
-      process.exit(ExitCode.Success);
-    }
-    for (const record of result.plan.create)
-      console.log(`  ${result.applied ? "created" : "would create"} ${record.type.padEnd(5)} ${record.name} \u2192 ${record.content}`);
-    const verb = result.applied ? "created" : "to create", count = result.applied ? result.created : result.plan.create.length;
-    console.log(`
-dns:sync ${target}: ${count} ${verb}, ${result.kept} kept${result.failed ? `, ${result.failed} failed` : ""}${result.provider ? ` (${result.provider})` : ""}`);
-    process.exit(result.failed > 0 ? ExitCode.FatalError : ExitCode.Success);
-  });
-  onUnknownSubcommand(buddy, "dns");
-}
+import process from"node:process";import{log,onUnknownSubcommand}from"@stacksjs/cli";import{config}from"@stacksjs/config";import{renderDnsConfig,resolveLiveRecords,syncDnsConfig}from"@stacksjs/dns";import{ExitCode}from"@stacksjs/types";import{loadProjectDnsConfig}from"../config";export function dns(buddy){const descriptions={dns:"Lists the DNS records for a domain",query:"Host name or IP address to query",type:"Type of the DNS record being queried (A, MX, NS\u2026)",nameserver:"Address of the nameserver to send packets to",class:"Network class of the DNS record being queried (IN, CH, HS)",udp:"Use the DNS protocol over UDP",tcp:"Use the DNS protocol over TCP",tls:"Use the DNS-over-TLS protocol",https:"Use the DNS-over-HTTPS protocol",short:"Short mode: display nothing but the first result",json:"Display the output as JSON",project:"Target a specific project",verbose:"Enable verbose output"};buddy.command("dns [domain]",descriptions.dns).option("-q, --query <query>",descriptions.query).option("-t, --type <type>",descriptions.type,{default:"A"}).option("-n, --nameserver <nameserver>",descriptions.nameserver).option("--class <class>",descriptions.class).option("-U, --udp",descriptions.udp).option("-T, --tcp",descriptions.tcp).option("-S, --tls",descriptions.tls).option("-H, --https",descriptions.https).option("-1, --short",descriptions.short,{default:!1}).option("-J, --json",descriptions.json,{default:!1}).option("-p, --project [project]",descriptions.project,{default:!1}).option("--verbose",descriptions.verbose,{default:!1}).action(async(domain,options)=>{log.debug("Running `buddy dns [domain]` ...",options);const targetDomain=domain||config.app.url;let DnsClient,formatOutput;try{const dnsx=await import("@stacksjs/dnsx");DnsClient=dnsx.DnsClient;formatOutput=dnsx.formatOutput}catch(err){log.error("`buddy dns` needs the @stacksjs/dnsx runtime, but only the type declarations are currently published. Install a build with the JS runtime (or wait for the next dnsx release) and re-run.");log.debug(`[dns] import failure: ${err instanceof Error?err.message:String(err)}`);process.exit(ExitCode.FatalError)}try{const client=new DnsClient({domains:[targetDomain],type:options.type,nameserver:options.nameserver,class:options.class,udp:options.udp,tcp:options.tcp,tls:options.tls,https:options.https,short:options.short,json:options.json,verbose:options.verbose}),startTime=performance.now(),responses=await client.query(),duration=performance.now()-startTime,output=formatOutput(responses,{json:options.json??!1,short:options.short??!1,showDuration:duration,colors:{enabled:!0},rawSeconds:!1});console.log(output)}catch(error){log.error(`DNS query failed: ${error instanceof Error?error.message:String(error)}`);process.exit(ExitCode.FatalError)}process.exit(ExitCode.Success)});const bareDomain=(input)=>(input||config.app.url||"").replace(/^[a-z]+:\/\//i,"").replace(/[/:].*$/,"");buddy.command("dns:pull [domain]","Print a domain's live DNS records as a config/dns.ts block").option("--verbose",descriptions.verbose,{default:!1}).action(async(domain,options)=>{const target=bareDomain(domain);log.debug(`Running \`buddy dns:pull ${target}\` ...`,options);const records=await resolveLiveRecords(target);if(!records.length){log.error(`No DNS records resolved for ${target}.`);process.exit(ExitCode.FatalError)}console.log(renderDnsConfig(target,records));process.exit(ExitCode.Success)});buddy.command("dns:diff [domain]","Show which config/dns.ts records are missing from the live zone").option("--verbose",descriptions.verbose,{default:!1}).action(async(domain,options)=>{const target=bareDomain(domain);log.debug(`Running \`buddy dns:diff ${target}\` ...`,options);const dnsConfig=await loadProjectDnsConfig(config.dns),{plan,provider}=await syncDnsConfig(target,dnsConfig,{dryRun:!0});for(const item of plan.items){const detail=item.record.type==="TXT"||item.record.type==="MX"?` ${item.record.content}`:` \u2192 ${item.record.content}`;console.log(`  ${item.action==="create"?"+ create":"  keep  "} ${item.record.type.padEnd(5)} ${item.record.name}${detail}`)}console.log(`
+${plan.create.length} to create, ${plan.keep.length} already present (${provider?`registrar: ${provider}`:"public DNS"})`);process.exit(ExitCode.Success)});buddy.command("dns:sync [domain]","Additively sync config/dns.ts to the registrar (creates missing records; never deletes or overwrites)").option("--dry-run","Show the plan without writing any records",{default:!1}).option("--verbose",descriptions.verbose,{default:!1}).action(async(domain,options)=>{const target=bareDomain(domain);log.debug(`Running \`buddy dns:sync ${target}\` ...`,options);const dnsConfig=await loadProjectDnsConfig(config.dns),result=await syncDnsConfig(target,dnsConfig,{dryRun:options.dryRun});if(!result.provider&&!options.dryRun){log.warn(`No DNS provider credentials found (e.g. PORKBUN_API_KEY / PORKBUN_SECRET_KEY) \u2014 nothing was synced. ${result.plan.create.length} record(s) would be created.`);process.exit(ExitCode.Success)}for(const record of result.plan.create)console.log(`  ${result.applied?"created":"would create"} ${record.type.padEnd(5)} ${record.name} \u2192 ${record.content}`);const verb=result.applied?"created":"to create",count=result.applied?result.created:result.plan.create.length;console.log(`
+dns:sync ${target}: ${count} ${verb}, ${result.kept} kept${result.failed?`, ${result.failed} failed`:""}${result.provider?` (${result.provider})`:""}`);process.exit(result.failed>0?ExitCode.FatalError:ExitCode.Success)});onUnknownSubcommand(buddy,"dns")}

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

@@ -1,135 +1,13 @@
-import { assertFrameworkRepo } from "./framework-repo";
-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 stablePath(value) {
-  if (typeof value !== "string" || !value.includes(root))
-    return value;
-  return value.replaceAll(root, "<project root>");
-}
-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(stablePath(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(`
+import{assertFrameworkRepo}from"./framework-repo";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 stablePath(value){if(typeof value!=="string"||!value.includes(root))return value;return value.replaceAll(root,"<project root>")}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(stablePath(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(`
+`).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() {
-  assertFrameworkRepo(root, "docs:buddy");
-  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");
-    const current = readFileSync(outputPath, "utf8");
-    if (current !== expected) {
-      const currentLines = current.split(`
-`), expectedLines = expected.split(`
-`), differences = [];
-      for (let i = 0;i < Math.max(currentLines.length, expectedLines.length) && differences.length < 6; i++)
-        if (currentLines[i] !== expectedLines[i])
-          differences.push(`  line ${i + 1}:
-    committed: ${JSON.stringify(currentLines[i] ?? "<end of file>")}
-    generated: ${JSON.stringify(expectedLines[i] ?? "<end of file>")}`);
-      throw Error(`Buddy command reference is stale; run bun run docs:buddy
+`}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(){assertFrameworkRepo(root,"docs:buddy");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");const current=readFileSync(outputPath,"utf8");if(current!==expected){const currentLines=current.split(`
+`),expectedLines=expected.split(`
+`),differences=[];for(let i=0;i<Math.max(currentLines.length,expectedLines.length)&&differences.length<6;i++)if(currentLines[i]!==expectedLines[i])differences.push(`  line ${i+1}:
+    committed: ${JSON.stringify(currentLines[i]??"<end of file>")}
+    generated: ${JSON.stringify(expectedLines[i]??"<end of file>")}`);throw Error(`Buddy command reference is stale; run bun run docs:buddy
 ${differences.join(`
-`)}`);
-    }
-    console.log("Buddy command reference matches the runtime registry");
-  }
-}
-if (import.meta.main)
-  await run();
+`)}`)}console.log("Buddy command reference matches the runtime registry")}}if(import.meta.main)await run();

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

@@ -1,38 +1 @@
-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");
-  });
-});
+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/framework-repo.js

@@ -1,14 +1 @@
-import { existsSync } from "node:fs";
-import { isAbsolute, relative, resolve } from "node:path";
-export function isInsideRoot(root, cwd) {
-  const rel = relative(resolve(root), resolve(cwd));
-  return rel === "" || !rel.startsWith("..") && !isAbsolute(rel);
-}
-export function looksLikeFrameworkRepo(root) {
-  return existsSync(resolve(root, "storage/framework/core/buddy"));
-}
-export function assertFrameworkRepo(root, command, cwd = process.cwd()) {
-  if (looksLikeFrameworkRepo(root) && isInsideRoot(root, cwd))
-    return;
-  throw Error(`${command} operates on the Stacks framework repository and would write to ${root}, which is not where you are (${cwd}). Run it from a framework checkout; an application has no generated framework artifacts to check.`);
-}
+import{existsSync}from"node:fs";import{isAbsolute,relative,resolve}from"node:path";export function isInsideRoot(root,cwd){const rel=relative(resolve(root),resolve(cwd));return rel===""||!rel.startsWith("..")&&!isAbsolute(rel)}export function looksLikeFrameworkRepo(root){return existsSync(resolve(root,"storage/framework/core/buddy"))}export function assertFrameworkRepo(root,command,cwd=process.cwd()){if(looksLikeFrameworkRepo(root)&&isInsideRoot(root,cwd))return;throw Error(`${command} operates on the Stacks framework repository and would write to ${root}, which is not where you are (${cwd}). Run it from a framework checkout; an application has no generated framework artifacts to check.`)}

package/dist/commands/docs/framework-repo.test.js

@@ -1,68 +1 @@
-import { describe, expect, it } from "bun:test";
-import { mkdirSync, mkdtempSync, rmSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join, resolve } from "node:path";
-import { assertFrameworkRepo, isInsideRoot, looksLikeFrameworkRepo } from "./framework-repo";
-describe("isInsideRoot", () => {
-  it("accepts the root itself and anything under it", () => {
-    expect(isInsideRoot("/a/b", "/a/b")).toBe(!0);
-    expect(isInsideRoot("/a/b", "/a/b/c/d")).toBe(!0);
-  });
-  it("rejects a sibling and a parent", () => {
-    expect(isInsideRoot("/a/b", "/a/c")).toBe(!1);
-    expect(isInsideRoot("/a/b", "/a")).toBe(!1);
-  });
-  it("rejects another project entirely", () => {
-    expect(isInsideRoot("/Users/x/Code/stacks", "/Users/x/Code/Apps/reviewos.org")).toBe(!1);
-  });
-});
-describe("looksLikeFrameworkRepo", () => {
-  it("recognises a tree carrying the framework core", () => {
-    const dir = mkdtempSync(join(tmpdir(), "stacks-fw-"));
-    try {
-      mkdirSync(resolve(dir, "storage/framework/core/buddy"), { recursive: !0 });
-      expect(looksLikeFrameworkRepo(dir)).toBe(!0);
-    } finally {
-      rmSync(dir, { recursive: !0, force: !0 });
-    }
-  });
-  it("does not mistake an ordinary application for it", () => {
-    const dir = mkdtempSync(join(tmpdir(), "stacks-app-"));
-    try {
-      mkdirSync(resolve(dir, "app"), { recursive: !0 });
-      expect(looksLikeFrameworkRepo(dir)).toBe(!1);
-    } finally {
-      rmSync(dir, { recursive: !0, force: !0 });
-    }
-  });
-});
-describe("assertFrameworkRepo", () => {
-  it("passes inside the framework repo", () => {
-    const dir = mkdtempSync(join(tmpdir(), "stacks-fw-"));
-    try {
-      mkdirSync(resolve(dir, "storage/framework/core/buddy"), { recursive: !0 });
-      expect(() => assertFrameworkRepo(dir, "docs:artifacts", dir)).not.toThrow();
-    } finally {
-      rmSync(dir, { recursive: !0, force: !0 });
-    }
-  });
-  it("refuses when run from somewhere else, and says where it would have written", () => {
-    const framework = mkdtempSync(join(tmpdir(), "stacks-fw-")), app = mkdtempSync(join(tmpdir(), "stacks-app-"));
-    try {
-      mkdirSync(resolve(framework, "storage/framework/core/buddy"), { recursive: !0 });
-      expect(() => assertFrameworkRepo(framework, "docs:artifacts", app)).toThrow(/docs:artifacts/);
-      expect(() => assertFrameworkRepo(framework, "docs:artifacts", app)).toThrow(new RegExp(framework));
-    } finally {
-      rmSync(framework, { recursive: !0, force: !0 });
-      rmSync(app, { recursive: !0, force: !0 });
-    }
-  });
-  it("refuses when the root is not a framework tree at all", () => {
-    const dir = mkdtempSync(join(tmpdir(), "stacks-app-"));
-    try {
-      expect(() => assertFrameworkRepo(dir, "docs:links", dir)).toThrow();
-    } finally {
-      rmSync(dir, { recursive: !0, force: !0 });
-    }
-  });
-});
+import{describe,expect,it}from"bun:test";import{mkdirSync,mkdtempSync,rmSync}from"node:fs";import{tmpdir}from"node:os";import{join,resolve}from"node:path";import{assertFrameworkRepo,isInsideRoot,looksLikeFrameworkRepo}from"./framework-repo";describe("isInsideRoot",()=>{it("accepts the root itself and anything under it",()=>{expect(isInsideRoot("/a/b","/a/b")).toBe(!0);expect(isInsideRoot("/a/b","/a/b/c/d")).toBe(!0)});it("rejects a sibling and a parent",()=>{expect(isInsideRoot("/a/b","/a/c")).toBe(!1);expect(isInsideRoot("/a/b","/a")).toBe(!1)});it("rejects another project entirely",()=>{expect(isInsideRoot("/Users/x/Code/stacks","/Users/x/Code/Apps/reviewos.org")).toBe(!1)})});describe("looksLikeFrameworkRepo",()=>{it("recognises a tree carrying the framework core",()=>{const dir=mkdtempSync(join(tmpdir(),"stacks-fw-"));try{mkdirSync(resolve(dir,"storage/framework/core/buddy"),{recursive:!0});expect(looksLikeFrameworkRepo(dir)).toBe(!0)}finally{rmSync(dir,{recursive:!0,force:!0})}});it("does not mistake an ordinary application for it",()=>{const dir=mkdtempSync(join(tmpdir(),"stacks-app-"));try{mkdirSync(resolve(dir,"app"),{recursive:!0});expect(looksLikeFrameworkRepo(dir)).toBe(!1)}finally{rmSync(dir,{recursive:!0,force:!0})}})});describe("assertFrameworkRepo",()=>{it("passes inside the framework repo",()=>{const dir=mkdtempSync(join(tmpdir(),"stacks-fw-"));try{mkdirSync(resolve(dir,"storage/framework/core/buddy"),{recursive:!0});expect(()=>assertFrameworkRepo(dir,"docs:artifacts",dir)).not.toThrow()}finally{rmSync(dir,{recursive:!0,force:!0})}});it("refuses when run from somewhere else, and says where it would have written",()=>{const framework=mkdtempSync(join(tmpdir(),"stacks-fw-")),app=mkdtempSync(join(tmpdir(),"stacks-app-"));try{mkdirSync(resolve(framework,"storage/framework/core/buddy"),{recursive:!0});expect(()=>assertFrameworkRepo(framework,"docs:artifacts",app)).toThrow(/docs:artifacts/);expect(()=>assertFrameworkRepo(framework,"docs:artifacts",app)).toThrow(new RegExp(framework))}finally{rmSync(framework,{recursive:!0,force:!0});rmSync(app,{recursive:!0,force:!0})}});it("refuses when the root is not a framework tree at all",()=>{const dir=mkdtempSync(join(tmpdir(),"stacks-app-"));try{expect(()=>assertFrameworkRepo(dir,"docs:links",dir)).toThrow()}finally{rmSync(dir,{recursive:!0,force:!0})}})});

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

@@ -1,71 +1,4 @@
-import { readFileSync, writeFileSync } from "node:fs";
-import { resolve } from "node:path";
-import { assertFrameworkRepo } from "./framework-repo";
-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(`
+import{readFileSync,writeFileSync}from"node:fs";import{resolve}from"node:path";import{assertFrameworkRepo}from"./framework-repo";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() {
-  assertFrameworkRepo(root, "docs:artifacts");
-  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();
+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(){assertFrameworkRepo(root,"docs:artifacts");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.js

@@ -1,19 +1 @@
-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");
-  });
-});
+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.js

@@ -1,85 +1,2 @@
-import { assertFrameworkRepo } from "./framework-repo";
-import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
-import { dirname, join, relative, resolve } from "node:path";
-const root = resolve(import.meta.dir, "../../../../../../.."), docsDir = resolve(root, "docs"), INLINE_LINK = /\[[^\]]*\]\(([^)]+)\)/g;
-export function isSkippableLink(target) {
-  return target === "" || target.startsWith("#") || /^[a-z][\w+.-]*:/i.test(target) || target.startsWith("//") || target.startsWith("{{") || target.includes("<");
-}
-export function extractLinks(content) {
-  const out = [], lines = content.replace(/<!--[\s\S]*?-->/g, (match) => match.replace(/[^\n]/g, " ")).split(`
-`);
-  let inFence = !1;
-  for (let index = 0;index < lines.length; index++) {
-    const raw = lines[index];
-    if (/^\s*(```|~~~)/.test(raw)) {
-      inFence = !inFence;
-      continue;
-    }
-    if (inFence)
-      continue;
-    const line = raw.replace(/`[^`]*`/g, "");
-    for (const match of line.matchAll(INLINE_LINK)) {
-      let target = match[1].trim();
-      const space = target.search(/\s/);
-      if (space !== -1)
-        target = target.slice(0, space);
-      out.push({ target, line: index + 1 });
-    }
-  }
-  return out;
-}
-export function resolveCandidates(target, fileDir, docsRoot) {
-  const clean = target.split("#")[0].split("?")[0];
-  if (!clean)
-    return [];
-  const base = clean.startsWith("/") ? join(docsRoot, clean.slice(1)) : resolve(fileDir, clean), candidates = [base];
-  if (!/\.\w+$/.test(clean))
-    candidates.push(`${base}.md`, join(base, "index.md"));
-  else if (clean.endsWith(".html"))
-    candidates.push(base.replace(/\.html$/, ".md"), join(base.replace(/\.html$/, ""), "index.md"));
-  return candidates;
-}
-function walkMarkdown(dir) {
-  const files = [];
-  for (const entry of readdirSync(dir, { withFileTypes: !0 })) {
-    const full = join(dir, entry.name);
-    if (entry.isDirectory()) {
-      if (entry.name === "node_modules" || entry.name.startsWith("."))
-        continue;
-      files.push(...walkMarkdown(full));
-    } else if (entry.name.endsWith(".md"))
-      files.push(full);
-  }
-  return files;
-}
-export function checkDocsLinks(docsRoot = docsDir) {
-  const broken = [];
-  for (const file of walkMarkdown(docsRoot)) {
-    const content = readFileSync(file, "utf8");
-    for (const { target, line } of extractLinks(content)) {
-      if (isSkippableLink(target))
-        continue;
-      const candidates = resolveCandidates(target, dirname(file), docsRoot);
-      if (candidates.length === 0)
-        continue;
-      if (!candidates.some((candidate) => existsSync(candidate) && statSync(candidate).isFile()))
-        broken.push({ file: relative(docsRoot, file), line, target });
-    }
-  }
-  return broken;
-}
-export async function run() {
-  assertFrameworkRepo(root, "docs:links");
-  const broken = checkDocsLinks();
-  if (broken.length === 0)
-    console.log("\u2713 All internal documentation links resolve.");
-  else {
-    console.error(`\u2717 ${broken.length} broken internal documentation link(s):`);
-    for (const link of broken)
-      console.error(`  ${link.file}:${link.line} -> ${link.target}`);
-    if (process.argv.includes("--check"))
-      process.exit(1);
-  }
-}
-if (import.meta.main)
-  await run();
+import{assertFrameworkRepo}from"./framework-repo";import{existsSync,readdirSync,readFileSync,statSync}from"node:fs";import{dirname,join,relative,resolve}from"node:path";const root=resolve(import.meta.dir,"../../../../../../.."),docsDir=resolve(root,"docs"),INLINE_LINK=/\[[^\]]*\]\(([^)]+)\)/g;export function isSkippableLink(target){return target===""||target.startsWith("#")||/^[a-z][\w+.-]*:/i.test(target)||target.startsWith("//")||target.startsWith("{{")||target.includes("<")}export function extractLinks(content){const out=[],lines=content.replace(/<!--[\s\S]*?-->/g,(match)=>match.replace(/[^\n]/g," ")).split(`
+`);let inFence=!1;for(let index=0;index<lines.length;index++){const raw=lines[index];if(/^\s*(```|~~~)/.test(raw)){inFence=!inFence;continue}if(inFence)continue;const line=raw.replace(/`[^`]*`/g,"");for(const match of line.matchAll(INLINE_LINK)){let target=match[1].trim();const space=target.search(/\s/);if(space!==-1)target=target.slice(0,space);out.push({target,line:index+1})}}return out}export function resolveCandidates(target,fileDir,docsRoot){const clean=target.split("#")[0].split("?")[0];if(!clean)return[];const base=clean.startsWith("/")?join(docsRoot,clean.slice(1)):resolve(fileDir,clean),candidates=[base];if(!/\.\w+$/.test(clean))candidates.push(`${base}.md`,join(base,"index.md"));else if(clean.endsWith(".html"))candidates.push(base.replace(/\.html$/,".md"),join(base.replace(/\.html$/,""),"index.md"));return candidates}function walkMarkdown(dir){const files=[];for(const entry of readdirSync(dir,{withFileTypes:!0})){const full=join(dir,entry.name);if(entry.isDirectory()){if(entry.name==="node_modules"||entry.name.startsWith("."))continue;files.push(...walkMarkdown(full))}else if(entry.name.endsWith(".md"))files.push(full)}return files}export function checkDocsLinks(docsRoot=docsDir){const broken=[];for(const file of walkMarkdown(docsRoot)){const content=readFileSync(file,"utf8");for(const{target,line}of extractLinks(content)){if(isSkippableLink(target))continue;const candidates=resolveCandidates(target,dirname(file),docsRoot);if(candidates.length===0)continue;if(!candidates.some((candidate)=>existsSync(candidate)&&statSync(candidate).isFile()))broken.push({file:relative(docsRoot,file),line,target})}}return broken}export async function run(){assertFrameworkRepo(root,"docs:links");const broken=checkDocsLinks();if(broken.length===0)console.log("\u2713 All internal documentation links resolve.");else{console.error(`\u2717 ${broken.length} broken internal documentation link(s):`);for(const link of broken)console.error(`  ${link.file}:${link.line} -> ${link.target}`);if(process.argv.includes("--check"))process.exit(1)}}if(import.meta.main)await run();