@stacksjs/buddy 0.70.88 → 0.70.90

package/dist/commands/config-migrate.d.ts

@@ -0,0 +1,26 @@
+import type { CLI } from '@stacksjs/types';
+/*.ts` files.
+ * Honors `--dry-run` (prints diffs without writing) and `--only=<id>`
+ * (restrict to a single codemod).
+ */
+export declare function runConfigMigrations(opts: {
+  dryRun?: boolean
+  only?: string
+}): Promise<{ changed: string[], skipped: string[] }>;
+export declare function configMigrate(buddy: CLI): void;
+/**
+ * A single config codemod — describes a search-and-replace operation
+ * against a user config file under `~/config/<file>.ts`. Each codemod
+ * is targeted at one specific Stacks-version transition (e.g. "0.65 →
+ * 0.66 renamed `cache.driver` to `cache.default`"). The replacement is
+ * a string transform — we deliberately avoid AST manipulation here
+ * because the input is user TS, comments matter, and we'd rather
+ * produce a textual diff than gamble on `ts-morph` reformatting code.
+ */
+export declare interface ConfigCodemod {
+  id: string
+  description: string
+  files: string[]
+  shouldApply(content: string): boolean
+  apply(content: string): string
+}

package/dist/commands/config-migrate.js

@@ -0,0 +1,94 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import process from "node:process";
+import { italic, log } from "@stacksjs/cli";
+import { projectPath } from "@stacksjs/path";
+const CODEMODS = [
+  {
+    id: "0.65-cache-driver-rename",
+    description: "Rename `cache.driver` to `cache.default` (introduced in 0.65).",
+    files: ["cache.ts"],
+    shouldApply: (c) => /\bdriver\s*:/.test(c) && !c.includes("default:"),
+    apply: (c) => c.replace(/(\bcache\b[\s\S]*?)\bdriver(\s*:)/m, "$1default$2")
+  },
+  {
+    id: "0.68-search-engine-name",
+    description: "Rename `searchEngine.driver` to `searchEngine.default` (matches other configs).",
+    files: ["search-engine.ts"],
+    shouldApply: (c) => /\bdriver\s*:/.test(c),
+    apply: (c) => c.replace(/\bdriver(\s*:)/g, "default$1")
+  },
+  {
+    id: "0.70-ports-string-to-number",
+    description: 'Convert string port values like `"3000"` to numbers (TypeScript types now require number).',
+    files: ["ports.ts"],
+    shouldApply: (c) => /:\s*['"]\d+['"]/.test(c),
+    apply: (c) => c.replace(/:\s*['"](\d+)['"]/g, ": $1")
+  }
+];
+export async function runConfigMigrations(opts) {
+  const changed = [], skipped = [], codemods = opts.only ? CODEMODS.filter((m) => m.id === opts.only) : CODEMODS;
+  if (codemods.length === 0) {
+    log.warn(`No matching codemods. Available: ${CODEMODS.map((m) => m.id).join(", ")}`);
+    return { changed, skipped };
+  }
+  for (const cm of codemods) {
+    log.info(`Codemod ${italic(cm.id)} \u2014 ${cm.description}`);
+    for (const rel of cm.files) {
+      const full = projectPath(`config/${rel}`);
+      if (!existsSync(full)) {
+        skipped.push(`${full} (missing)`);
+        continue;
+      }
+      const before = readFileSync(full, "utf-8");
+      if (!cm.shouldApply(before)) {
+        skipped.push(`${full} (no changes)`);
+        continue;
+      }
+      const after = cm.apply(before);
+      if (after === before) {
+        skipped.push(`${full} (no changes)`);
+        continue;
+      }
+      if (opts.dryRun) {
+        log.info(`[dry-run] would update ${full}`);
+        printDiff(before, after);
+      } else {
+        writeFileSync(full, after);
+        log.success(`updated ${full}`);
+      }
+      changed.push(full);
+    }
+  }
+  return { changed, skipped };
+}
+function printDiff(before, after) {
+  const beforeLines = before.split(`
+`), afterLines = after.split(`
+`), max = Math.max(beforeLines.length, afterLines.length);
+  for (let i = 0;i < max; i++) {
+    const b = beforeLines[i], a = afterLines[i];
+    if (b === a)
+      continue;
+    if (b !== void 0)
+      process.stdout.write(`  - ${b}
+`);
+    if (a !== void 0)
+      process.stdout.write(`  + ${a}
+`);
+  }
+  process.stdout.write(`
+`);
+}
+export function configMigrate(buddy) {
+  buddy.command("config:migrate", "Apply config-shape codemods for the latest Stacks version").option("--dry-run", "Preview changes without writing", { default: !1 }).option("--only [id]", "Run a single codemod by id", { default: "" }).action(async (options) => {
+    log.info("Running `buddy config:migrate` ...");
+    const { changed, skipped } = await runConfigMigrations({
+      dryRun: Boolean(options.dryRun),
+      only: options.only?.length ? options.only : void 0
+    });
+    log.info(`Changed: ${changed.length}, Skipped: ${skipped.length}`);
+    if (skipped.length > 0)
+      for (const s of skipped)
+        log.debug(`  skipped: ${s}`);
+  });
+}

package/dist/commands/configure.d.ts

@@ -0,0 +1,2 @@
+import type { CLI } from '@stacksjs/types';
+export declare function configure(buddy: CLI): void;

package/dist/commands/configure.js

@@ -0,0 +1,48 @@
+import process from "node:process";
+import { log, onUnknownSubcommand, outro, runCommand } from "@stacksjs/cli";
+import { path as p } from "@stacksjs/path";
+import { ExitCode } from "@stacksjs/types";
+export function configure(buddy) {
+  const descriptions = {
+    configure: "Configure options",
+    aws: "Configure the AWS connection",
+    project: "Target a specific project",
+    profile: "The AWS profile to use",
+    verbose: "Enable verbose output"
+  };
+  buddy.command("configure", descriptions.configure).option("--aws", descriptions.aws, { default: !1 }).option("-p, --project [project]", descriptions.project, { default: !1 }).option("--verbose", descriptions.verbose, { default: !1 }).action(async (options) => {
+    log.debug("Running `buddy configure` ...", options);
+    if (options?.aws) {
+      await configureAws(options);
+      process.exit(ExitCode.Success);
+    }
+    log.info("Not implemented yet. Please use the --aws flag to configure AWS.");
+    process.exit(ExitCode.Success);
+  });
+  buddy.command("configure:aws", descriptions.aws).option("-p, --project [project]", descriptions.project, { default: !1 }).option("--profile", descriptions.profile, {
+    default: process.env.AWS_PROFILE
+  }).option("--verbose", descriptions.verbose, { default: !1 }).option("--access-key-id", "The AWS access key").option("--secret-access-key", "The AWS secret access key").option("--region", "The AWS region").option("--output", "The AWS output format").option("--quiet", "Suppress output").action(async (options) => {
+    log.debug("Running `buddy configure:aws` ...", options);
+    await configureAws(options);
+    process.exit(ExitCode.Success);
+  });
+  onUnknownSubcommand(buddy, "configure");
+}
+async function configureAws(options) {
+  const startTime = performance.now(), awsAccessKeyId = options?.accessKeyId ?? process.env.AWS_ACCESS_KEY_ID, awsSecretAccessKey = options?.secretAccessKey ?? process.env.AWS_SECRET_ACCESS_KEY, defaultRegion = "us-east-1", defaultOutputFormat = options?.output ?? "json", profile = process.env.AWS_PROFILE ?? options?.profile, command = profile ? `aws configure --profile ${profile}` : "aws configure", input = `${awsAccessKeyId}
+${awsSecretAccessKey}
+${defaultRegion}
+${defaultOutputFormat}
+`, result = await runCommand(command, {
+    cwd: p.projectPath(),
+    stdin: "pipe",
+    input
+  });
+  if (result.isErr) {
+    await outro("While running the cloud command, there was an issue", { startTime, useSeconds: !0 }, result.error);
+    process.exit(ExitCode.FatalError);
+  }
+  if (options?.quiet)
+    return;
+  await outro("Exited", { startTime, useSeconds: !0 });
+}

package/dist/commands/create.d.ts

@@ -0,0 +1,2 @@
+import type { CLI } from '@stacksjs/types';
+export declare function create(buddy: CLI): void;

package/dist/commands/create.js

@@ -0,0 +1,141 @@
+import { chmodSync } from "node:fs";
+import process from "node:process";
+import { runAction } from "@stacksjs/actions";
+import { bold, cyan, dim, intro, log, onUnknownSubcommand, runCommand } from "@stacksjs/cli";
+import { Action } from "@stacksjs/enums";
+import { resolve } from "@stacksjs/path";
+import { isFolder } from "@stacksjs/storage";
+import { ExitCode } from "@stacksjs/types";
+import { useOnline } from "@stacksjs/utils";
+import { uninstallAllFeatures } from "./features";
+import { ensurePantryDependencies, ensurePantryInstalled } from "./setup";
+export function create(buddy) {
+  const descriptions = {
+    name: "The name of the project",
+    command: "Create a new Stacks project",
+    ui: "Are you building a UI?",
+    components: "Are you building UI components?",
+    webComponents: "Automagically built optimized custom elements/web components?",
+    vue: "Automagically built a Vue component library?",
+    views: "How about views?",
+    functions: "Are you developing functions/composables?",
+    api: "Are you building an API?",
+    database: "Do you need a database?",
+    notifications: "Do you need notifications? e.g. email, SMS, push or chat notifications",
+    cache: "Do you need caching?",
+    email: "Do you need email?",
+    project: "Target a specific project",
+    minimal: "Skip optional feature bundles (cms, commerce, dashboard, marketing, monitoring, realtime, queue) \u2014 bare-bones API/SPA starter that can re-add them later via `./buddy <feature>:install`.",
+    verbose: "Enable verbose output"
+  };
+  buddy.command("new [name]", descriptions.command).alias("create [name]").option("-n, --name [name]", descriptions.name, { default: !1 }).option("-u, --ui", descriptions.ui, { default: !0 }).option("-c, --components", descriptions.components, { default: !0 }).option("-w, --web-components", descriptions.webComponents, { default: !0 }).option("-v, --vue", descriptions.vue, { default: !0 }).option("-p, --views", descriptions.views, { default: !0 }).option("-f, --functions", descriptions.functions, { default: !0 }).option("-a, --api", descriptions.api, { default: !0 }).option("-d, --database", descriptions.database, { default: !0 }).option("-ca, --cache", descriptions.cache, { default: !1 }).option("-e, --email", descriptions.email, { default: !1 }).option("-p, --project [project]", descriptions.project, { default: !1 }).option("-m, --minimal", descriptions.minimal, { default: !1 }).option("--verbose", descriptions.verbose, { default: !1 }).action(async (name, options) => {
+    log.debug("Running `buddy new <name>` ...", options);
+    const startTime = await intro("buddy new");
+    name = name ?? options.name;
+    const path = resolve(process.cwd(), name);
+    isFolderCheck(path);
+    onlineCheck();
+    const result = await download(name, path, options);
+    if (result.isErr) {
+      log.error(result.error);
+      process.exit(ExitCode.FatalError);
+    }
+    await ensureEnv(path, options);
+    ensureExecutableScripts(path);
+    await install(path, options);
+    if (options.minimal)
+      await stripFeatures(path);
+    if (startTime) {
+      const time = performance.now() - startTime;
+      log.success(dim(`[${time.toFixed(2)}ms] Completed`));
+    }
+    log.info(bold("Welcome to the Stacks Framework! \u269B\uFE0F"));
+    log.info("To learn more, visit https://stacksjs.com");
+    process.exit(ExitCode.Success);
+  });
+  onUnknownSubcommand(buddy, "new");
+}
+function isFolderCheck(path) {
+  if (isFolder(path)) {
+    log.error(`Path ${path} already exists`);
+    process.exit(ExitCode.FatalError);
+  }
+}
+function onlineCheck() {
+  if (!useOnline()) {
+    log.info("It appears you are disconnected from the internet.");
+    log.info("The Stacks setup requires a brief internet connection for setup.");
+    log.info("For instance, it installs your dependencies from.");
+    process.exit(ExitCode.FatalError);
+  }
+}
+async function download(name, path, _options) {
+  log.info("Setting up your stack.");
+  try {
+    const { downloadTemplate } = await import("@stacksjs/gitit");
+    await downloadTemplate("stacks", { dir: name });
+    log.success(`Successfully scaffolded your project at ${cyan(path)}`);
+    return { isErr: !1 };
+  } catch (error) {
+    return { isErr: !0, error: error instanceof Error ? error.message : String(error) };
+  }
+}
+function ensureExecutableScripts(path) {
+  for (const script of ["buddy", "bootstrap"])
+    try {
+      chmodSync(resolve(path, script), 493);
+    } catch {}
+}
+async function ensureEnv(path, _options) {
+  log.info("Ensuring your environment is ready...");
+  await ensurePantryInstalled();
+  await ensurePantryDependencies(path);
+  log.success("Environment is ready");
+}
+async function install(path, options) {
+  log.info("Installing & setting up Stacks");
+  log.info("Running bun install...");
+  let result = await runCommand("bun install", { ...options, cwd: path });
+  if (result?.isErr) {
+    log.error(result.error);
+    process.exit(ExitCode.FatalError);
+  }
+  log.info("Copying .env.example \u2192 .env");
+  result = await runCommand("cp .env.example .env", { ...options, cwd: path });
+  if (result?.isErr) {
+    log.error(result.error);
+    process.exit(ExitCode.FatalError);
+  }
+  log.info("Removing template-encrypted env files...");
+  const { rm } = await import("node:fs/promises");
+  for (const stale of [".env.development", ".env.staging", ".env.production", ".env.keys"])
+    await rm(`${path}/${stale}`, { force: !0 });
+  log.info("Generating application key...");
+  const keyResult = await runAction(Action.KeyGenerate, { ...options, cwd: path });
+  if (keyResult.isErr) {
+    log.error(keyResult.error);
+    process.exit(ExitCode.FatalError);
+  }
+  log.info("Initializing git repository...");
+  result = await runCommand("git init", { ...options, cwd: path });
+  if (result.isErr) {
+    log.error(result.error);
+    process.exit(ExitCode.FatalError);
+  }
+  log.success("Installed & set-up \uD83D\uDE80");
+}
+async function stripFeatures(path) {
+  log.info("Stripping optional feature bundles (--minimal)...");
+  const results = await uninstallAllFeatures({ root: path });
+  let strippedAny = !1;
+  for (const { feature, configOutcome, filesRemoved } of results)
+    if (configOutcome === "flipped" || filesRemoved.length > 0) {
+      strippedAny = !0;
+      const fileSummary = filesRemoved.length > 0 ? ` (${filesRemoved.length} path${filesRemoved.length === 1 ? "" : "s"})` : "";
+      log.info(`  - ${feature}${fileSummary}`);
+    }
+  if (!strippedAny)
+    log.info("  \u2192 no feature scaffolding present; nothing to strip.");
+  else
+    log.success("Minimal skeleton ready \u2014 run `./buddy <feature>:install` to add features back.");
+}

package/dist/commands/deploy.d.ts

@@ -0,0 +1,107 @@
+import type { CLI } from '@stacksjs/types';
+/**
+ * Resolve (and decrypt) the deploy-target's environment file into a flat
+ * key/value map, so its values can be shipped to the server as each site's
+ * systemd `.env` content.
+ *
+ * ts-cloud's `buildSiteDeployScript` treats `site.env` as the COMPLETE
+ * content of the deployed `.env` — it doesn't read or merge in anything
+ * from the packaged release tarball (ts-cloud is a generic deploy tool; it
+ * has no idea `.env.production`/dotenvx encryption exist, that's entirely a
+ * Stacks convention). Left unaddressed, every Hetzner site deploys with
+ * ONLY whatever's in that site's own `env` override (often nothing at all)
+ * — confirmed against a real deploy (stacksjs/status#1 Phase 9): the `main`
+ * site (no `env` override) came up logging "loaded 0 variables from .env",
+ * and `api` (which only declares `{ HOST, APP_ENV }` to force the loopback
+ * bind) came up with just those 2 keys and none of its real production
+ * config, failing config validation on the still-`encrypted:...` APP_ENV
+ * ciphertext it never had a chance to decrypt (no DOTENV_PRIVATE_KEY_* in
+ * that 2-key set).
+ *
+ * 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.
+ */
+export declare function resolveDeployEnvValues(environment: 'production' | 'staging' | 'development'): 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
+ * declares its own `port` (the generated systemd unit already sets
+ * `Environment=PORT=${site.port}` — see buildSiteDeployScript in ts-cloud —
+ * so a leftover PORT in the shipped `.env` would otherwise silently win
+ * over it once the app's own dotenv loading applies file values on top of
+ * the process env).
+ */
+export declare function mergeSiteDeployEnv(sites: Record<string, any>, resolvedDeployEnv: Record<string, string>): Record<string, any>;
+/**
+ * Make the site model environment-aware. For a non-production environment that
+ * declares a `domainPrefix` (staging → `staging`, development → `dev`), every
+ * site's public domain becomes `<prefix>.<domain>`, and URL values that point at
+ * those hosts (APP_URL, OAuth redirect URLs, redirect targets, …) are rewritten
+ * to match — so one config drives prod + staging + dev from their own branches
+ * without duplicating site blocks. Only `//<host>` URL occurrences are rewritten;
+ * bare `user@host` (e.g. mail identities) is left alone. Production is untouched.
+ */
+export declare function applyEnvironmentToSites(sites: Record<string, any>, environment: string, config: any): Record<string, any>;
+/**
+ * Loopback-bound server-app sites (e.g. the `api` site: env.HOST=127.0.0.1,
+ * reached only through `buddy serve`'s same-origin /api proxy on :3000 —
+ * stacksjs/stacks#1950) must NOT have their port opened to the internet.
+ * ts-cloud's Hetzner provisioning opens EVERY numeric `site.port` to
+ * 0.0.0.0/0 + ::/0 (collectUpstreamPorts → buildHetznerFirewallRules), which
+ * would leave only the process bind between the public internet and the full
+ * bun-router API. Hand the provision step a copy of the config with those
+ * ports stripped — the unmodified config still drives deployAllComputeSites,
+ * so the systemd unit (ExecStart, Environment=PORT) is unaffected.
+ *
+ * Domain-less sites only: a loopback site WITH a domain feeds the rpx
+ * gateway's route table (which proxies to 127.0.0.1:port on-box), so its
+ * port declaration is left alone.
+ */
+export declare function scrubLoopbackSitePortsForFirewall(tsCloudConfig: any): any;
+/**
+ * Everything is MERGE-based so a shared mail server keeps every other tenant's
+ * domains, keys, users, and forward rules untouched. Best-effort — a hiccup is
+ * logged, never fails the release. Returns what the DNS step needs (mail host +
+ * DKIM public key), or null when there is nothing to reconcile / it failed.
+ */
+export declare function provisionMailTenant(ip: string, logger: typeof log): Promise<MailTenantResult | null>;
+/**
+ * Publish the mail DNS for a hosted domain via Porkbun (idempotent delete+create
+ * per record): MX → the mail host, SPF authorizing the box IP, the domain's DKIM
+ * public key at `mail._domainkey`, and a DMARC policy. Best-effort — logged, not
+ * thrown. No-op without Porkbun credentials (the records are printed to add by
+ * hand). MX targets the tenant's own `mail.<domain>` when that name already
+ * resolves to the box (own-brand mail host; requires the mail cert to cover it
+ * as a SAN), and falls back to the shared mail host (`mail.stacksjs.com`)
+ * otherwise, where no per-domain mail A record or extra TLS SAN is needed.
+ */
+export declare function reconcileMailDns(res: MailTenantResult, ip: string, logger: typeof log): Promise<void>;
+export declare function deploy(buddy: CLI): void;
+/**
+ * Use console.log for clean output without timestamps
+ * @defaultValue
+ * ```ts
+ * {
+ *   info: (...args: any[]) => unknown,
+ *   success: (...args: any[]) => unknown,
+ *   warn: (...args: any[]) => unknown,
+ *   error: (...args: any[]) => unknown,
+ *   debug: (...args: any[]) => void
+ * }
+ * ```
+ */
+declare const log: {
+  info: (...args: any[]) => unknown;
+  success: (...args: any[]) => unknown;
+  warn: (...args: any[]) => unknown;
+  error: (...args: any[]) => unknown;
+  debug: (...args: any[]) => void
+};
+/** What a mail-tenant reconcile resolved + provisioned, for the DNS step. */
+export declare interface MailTenantResult {
+  domain: string
+  mailHost: string
+  dkimPubB64?: string
+  created: Array<{ address: string, password: string }>
+}