@stacksjs/buddy 0.70.162 → 0.70.164

package/dist/commands/publish.js

@@ -14,9 +14,12 @@ export function publish(buddy) {
     middleware: "Publish a default middleware from storage/framework/defaults/app/Middleware/ to app/Middleware/",
     action: "Publish a default action from storage/framework/defaults/app/Actions/ to app/Actions/",
     core: "Publish a framework package source from node_modules/@stacksjs/<pkg>/ into storage/framework/core/<pkg>/ for editing",
+    unpublishCore: "Drop a vendored storage/framework/core/<pkg>/ and go back to the installed @stacksjs/<pkg>",
+    all: "Unvendor the whole framework: remove storage/framework/core and resolve every @stacksjs package from the `stacks` dependency in package.json",
     name: "The name of the resource to publish (e.g. Cart, User)",
     pkg: "The name of the framework package (e.g. router, orm, faker \u2014 without @stacksjs/ prefix)",
     force: "Overwrite an existing userland file",
+    forceUnpublish: "Delete the vendored source even when it has uncommitted changes",
     verbose: "Enable verbose output"
   };
   buddy.command("publish:model <name>", descriptions.model).option("--force", descriptions.force, { default: !1 }).option("--verbose", descriptions.verbose, { default: !1 }).action(async (name, options) => {
@@ -58,6 +61,17 @@ export function publish(buddy) {
   buddy.command("publish:core <pkg>", descriptions.core).option("--force", descriptions.force, { default: !1 }).option("--verbose", descriptions.verbose, { default: !1 }).action(async (pkg, options) => {
     await publishCorePackage(pkg, !!options.force);
   });
+  buddy.command("unpublish:core [pkg]", descriptions.unpublishCore).option("--all", descriptions.all, { default: !1 }).option("--force", descriptions.forceUnpublish, { default: !1 }).option("--verbose", descriptions.verbose, { default: !1 }).action(async (pkg, options) => {
+    if (options.all) {
+      await unvendorFramework(!!options.force);
+      return;
+    }
+    if (!pkg) {
+      log.error("Usage: buddy unpublish:core <pkg>   (or --all to move the whole framework to node_modules)");
+      process.exit(ExitCode.FatalError);
+    }
+    await unpublishCorePackage(pkg, !!options.force);
+  });
   buddy.command("publish [resource] [name]", descriptions.command).option("--force", descriptions.force, { default: !1 }).option("--verbose", descriptions.verbose, { default: !1 }).action(async (resource, name, options) => {
     if (!resource || !name) {
       log.error("Usage: buddy publish:<resource> <Name>  (e.g. buddy publish:model Cart)");
@@ -170,3 +184,138 @@ async function publishResource(ctx) {
   await fs.promises.copyFile(sourcePath, targetPath);
   log.success(`Published ${kind} ${italic(name)} \u2192 ${italic(targetPath.replace(`${process.cwd()}/`, ""))}`);
 }
+async function unpublishCorePackage(pkg, force) {
+  const shortName = normalizeCoreName(pkg), targetDir = path.frameworkPath(`core/${shortName}`), rel = (p) => p.replace(`${process.cwd()}/`, "");
+  if (!existsSync(targetDir)) {
+    log.info(`Not vendored: ${italic(rel(targetDir))} \u2014 nothing to do.`);
+    return;
+  }
+  const installed = resolve(process.cwd(), "node_modules", "@stacksjs", shortName);
+  if (!existsSync(installed) && !force) {
+    log.error(`@stacksjs/${shortName} is not installed, so removing the vendored copy would leave nothing to resolve.`);
+    log.info(`Run \`bun add @stacksjs/${shortName}\` first, or pass --force to remove it anyway.`);
+    process.exit(ExitCode.FatalError);
+  }
+  await assertNoUncommittedChanges(targetDir, force);
+  await fs.promises.rm(targetDir, { recursive: !0, force: !0 });
+  log.success(`Unpublished ${italic(rel(targetDir))} \u2014 @stacksjs/${shortName} now resolves from node_modules.`);
+}
+async function unvendorFramework(force) {
+  const coreDir = path.frameworkPath("core"), rel = (p) => p.replace(`${process.cwd()}/`, "");
+  if (!existsSync(coreDir)) {
+    log.info("No storage/framework/core in this project \u2014 already on the installed packages.");
+    return;
+  }
+  const corePkgPath = resolve(coreDir, "package.json");
+  if (!existsSync(corePkgPath)) {
+    log.error(`${rel(coreDir)} has no package.json, so its version cannot be determined.`);
+    log.info("Unvendor the packages individually with `buddy unpublish:core <pkg>` instead.");
+    process.exit(ExitCode.FatalError);
+  }
+  const corePkg = JSON.parse(await fs.promises.readFile(corePkgPath, "utf-8")), version = corePkg.version;
+  if (!version) {
+    log.error(`${rel(corePkgPath)} has no version field.`);
+    process.exit(ExitCode.FatalError);
+  }
+  await assertNoUncommittedChanges(coreDir, force);
+  const rootPkgPath = resolve(process.cwd(), "package.json"), rootPkgRaw = await fs.promises.readFile(rootPkgPath, "utf-8"), rootPkg = JSON.parse(rootPkgRaw), depName = corePkg.name ?? "stacks", range = `^${version}`, provided = new Set([depName, ...Object.keys(corePkg.dependencies ?? {}).filter((name) => name.startsWith("@stacksjs/"))]);
+  for (const entry of await readdir(coreDir, { withFileTypes: !0 }))
+    if (entry.isDirectory())
+      provided.add(`@stacksjs/${entry.name}`);
+  let repointed = 0;
+  const repointWorkspaceRanges = (pkg) => {
+    let touched = !1;
+    for (const field of ["dependencies", "devDependencies", "peerDependencies"]) {
+      const deps = pkg[field];
+      if (!deps)
+        continue;
+      for (const [name, spec] of Object.entries(deps)) {
+        if (!spec.startsWith("workspace:") || !provided.has(name))
+          continue;
+        deps[name] = range;
+        touched = !0;
+        repointed++;
+      }
+    }
+    return touched;
+  };
+  repointWorkspaceRanges(rootPkg);
+  if (!rootPkg.dependencies?.[depName] && !rootPkg.devDependencies?.[depName])
+    rootPkg.dependencies = { ...rootPkg.dependencies, [depName]: range };
+  if (Array.isArray(rootPkg.workspaces)) {
+    rootPkg.workspaces = rootPkg.workspaces.filter((glob) => !isCoreWorkspaceGlob(glob));
+    if (rootPkg.workspaces.length === 0)
+      delete rootPkg.workspaces;
+  }
+  await fs.promises.writeFile(rootPkgPath, `${JSON.stringify(rootPkg, null, 2)}
+`);
+  for (const glob of rootPkg.workspaces ?? [])
+    for (const memberPkgPath of globSync(`${glob.replace(/\/$/, "")}/package.json`, { cwd: process.cwd(), absolute: !0 })) {
+      const raw = await fs.promises.readFile(memberPkgPath, "utf-8"), memberPkg = JSON.parse(raw);
+      if (repointWorkspaceRanges(memberPkg))
+        await fs.promises.writeFile(memberPkgPath, `${JSON.stringify(memberPkg, null, 2)}
+`);
+    }
+  const bunfigPath = resolve(process.cwd(), "bunfig.toml");
+  let rewrittenPreloads = 0;
+  if (existsSync(bunfigPath)) {
+    const bunfig = await fs.promises.readFile(bunfigPath, "utf-8"), next = bunfig.replace(/(["'])\.?\/?storage\/framework\/core\/([\w-]+)\/([^"']+?)\.ts\1/g, (_match, quote, pkgName, subpath) => {
+      rewrittenPreloads++;
+      return `${quote}@stacksjs/${pkgName}/${subpath}.js${quote}`;
+    });
+    if (next !== bunfig)
+      await fs.promises.writeFile(bunfigPath, next);
+  }
+  await fs.promises.rm(coreDir, { recursive: !0, force: !0 });
+  log.success(`Removed ${italic(rel(coreDir))}`);
+  log.info(`package.json now depends on ${depName}@${range}`);
+  if (repointed > 0)
+    log.info(`Repointed ${repointed} workspace: range${repointed === 1 ? "" : "s"} to ${range}`);
+  if (rewrittenPreloads > 0)
+    log.info(`Rewrote ${rewrittenPreloads} bunfig.toml preload path${rewrittenPreloads === 1 ? "" : "s"} to package specifiers`);
+  log.info("Installing the published packages...");
+  if (await Bun.spawn(["bun", "install"], { cwd: process.cwd(), stdout: "inherit", stderr: "inherit" }).exited !== 0) {
+    log.error("`bun install` failed. package.json and bunfig.toml were updated; re-run the install once the failure is resolved.");
+    process.exit(ExitCode.FatalError);
+  }
+  log.success("This project now runs on the published Stacks packages.");
+  log.info("Vendor an individual package again any time with `buddy publish:core <pkg>`.");
+}
+function normalizeCoreName(pkg) {
+  const shortName = pkg.replace(/^@stacksjs\//, "").replace(/^core\//, "");
+  if (!shortName || shortName.includes("/") || shortName.includes("..")) {
+    process.stderr.write(`Invalid package name: ${pkg}
+`);
+    process.stderr.write("  Use a short name like `router` or the fully qualified `@stacksjs/router`.\n");
+    process.exit(ExitCode.FatalError);
+  }
+  return shortName;
+}
+function isCoreWorkspaceGlob(glob) {
+  const normalized = glob.replace(/^\.\//, "").replace(/\/$/, "");
+  return normalized === "storage/framework/core" || normalized.startsWith("storage/framework/core/");
+}
+async function assertNoUncommittedChanges(dir, force) {
+  if (force)
+    return;
+  try {
+    const proc = Bun.spawn(["git", "status", "--porcelain", "--", dir], {
+      cwd: process.cwd(),
+      stdout: "pipe",
+      stderr: "ignore"
+    }), output = await new Response(proc.stdout).text();
+    if (await proc.exited !== 0)
+      return;
+    const changed = output.split(`
+`).filter(Boolean);
+    if (changed.length === 0)
+      return;
+    log.error(`${changed.length} uncommitted change${changed.length === 1 ? "" : "s"} under ${italic(dir.replace(`${process.cwd()}/`, ""))}:`);
+    for (const line of changed.slice(0, 10))
+      log.info(`  ${line}`);
+    if (changed.length > 10)
+      log.info(`  ... and ${changed.length - 10} more`);
+    log.info("Commit or stash them first, or pass --force to delete them anyway.");
+    process.exit(ExitCode.FatalError);
+  } catch {}
+}

package/dist/commands/run-tool.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Invoke a migrated tooling module's `run()` with a synthetic argv so its
+ * existing `process.argv` flag parsing (`--check` / `--write` / `--revision` …)
+ * sees the flags the buddy command wants, then restore the real argv. Buddy runs
+ * one command per process and the action is terminal, so this swap is safe.
+ */
+export declare function runTool(run: () => void | Promise<void>, ...flags: string[]): Promise<void>;

package/dist/commands/run-tool.js

@@ -0,0 +1,9 @@
+export async function runTool(run, ...flags) {
+  const saved = process.argv;
+  process.argv = [saved[0] ?? "bun", saved[1] ?? "buddy", ...flags];
+  try {
+    await run();
+  } finally {
+    process.argv = saved;
+  }
+}

package/dist/commands/seed.js

@@ -7,49 +7,24 @@ export function seed(buddy) {
     project: "Target a specific project",
     verbose: "Enable verbose output"
   };
-  buddy.command("seed", descriptions.seed).alias("db:seed").option("-p, --project [project]", descriptions.project, { default: !1 }).option("-c, --class [class]", "Run a specific seeder class from database/seeders/", { default: "" }).option("--allow-protected", "Seed auth/oauth models even on a non-fresh DB (will invalidate live tokens)", { default: !1 }).option("--fresh", "Truncate tables before seeding", { default: !1 }).option("--verbose", descriptions.verbose, { default: !1 }).action(async (options) => {
+  buddy.command("seed", descriptions.seed).alias("db:seed").option("-p, --project [project]", descriptions.project, { default: !1 }).option("--only [models]", "Comma-separated list of models to seed", { default: "" }).option("--except [models]", "Comma-separated list of models to skip", { default: "" }).option("--include-defaults", "Also seed the framework's built-in models", { default: !1 }).option("--allow-protected", "Seed auth/oauth models even on a non-fresh DB (will invalidate live tokens)", { default: !1 }).option("--fresh", "Truncate tables before seeding", { default: !1 }).option("--verbose", descriptions.verbose, { default: !1 }).action(async (options) => {
     log.debug("Running `buddy seed` ...", options);
-    const perf = await intro("buddy seed");
-    if (options.class) {
-      const { injectGlobalAutoImports } = await import("@stacksjs/server");
-      await injectGlobalAutoImports();
-      const { runClassSeeders } = await import("@stacksjs/database"), result = await runClassSeeders({ class: options.class });
-      await outro(`Class seeders: ran=${result.ran.length}, skipped=${result.skipped.length}`, { startTime: perf, useSeconds: !0 });
-      process.exit(result.ran.length > 0 ? ExitCode.Success : ExitCode.FatalError);
-    }
-    const { injectGlobalAutoImports } = await import("@stacksjs/server");
+    const perf = await intro("buddy seed"), { injectGlobalAutoImports } = await import("@stacksjs/server");
     await injectGlobalAutoImports();
-    const { runClassSeeders, listSeedableModels } = await import("@stacksjs/database"), { path } = await import("@stacksjs/path"), { fs } = await import("@stacksjs/storage"), seedableModels = await listSeedableModels(), seedersDir = path.projectPath("database/seeders"), existingSeederFiles = fs.existsSync(seedersDir) ? new Set(fs.readdirSync(seedersDir).filter((f) => f.endsWith(".ts"))) : new Set, unmigratedModels = seedableModels.filter((m) => !existingSeederFiles.has(`${m.name}Seeder.ts`));
-    if (unmigratedModels.length > 0)
-      log.warn(`[seed] ${unmigratedModels.length} model(s) declare the deprecated \`useSeeder\` trait but have no class seeder file: ${unmigratedModels.map((m) => m.name).join(", ")}. ` + "The auto-walker has been removed (stacksjs/stacks#1919) \u2014 these models will NOT seed. " + "Run `./buddy seed:scaffold` to codemod a class seeder per model and strip the trait (stacksjs/stacks#1929), then re-run `./buddy seed`.");
-    const classResult = await runClassSeeders(), APP_ENV = process.env.APP_ENV || "local", ran = classResult.ran.length;
-    await outro(`Seeded your ${APP_ENV} database. Class seeders: ran=${ran}, skipped=${classResult.skipped.length}.`, { startTime: perf, useSeconds: !0 });
-    process.exit(ExitCode.Success);
-  });
-  buddy.command("seed:scaffold", "Generate class seeders for every model with a useSeeder trait (codemod for stacksjs/stacks#1919)").option("--force", "Overwrite existing seeder files", { default: !1 }).option("--dry-run", "Print what would be generated without writing files", { default: !1 }).action(async (options) => {
-    const perf = await intro("buddy seed:scaffold");
-    try {
-      const { scaffoldClassSeedersFromModels } = await import("@stacksjs/database"), result = await scaffoldClassSeedersFromModels({
-        force: options.force,
-        dryRun: options.dryRun
-      }), generated = result.generated.length, alreadyThere = result.skipped.filter((s) => s.reason === "already-exists").length, stripped = result.strippedTrait.length, errors = result.errors.length;
-      for (const g of result.generated)
-        console.log(`  + ${g.model} \u2192 ${g.file}`);
-      for (const s of result.skipped.filter((s) => s.reason === "already-exists"))
-        console.log(`  \xB7 ${s.model}: seeder exists (pass --force to overwrite)`);
-      for (const t of result.strippedTrait)
-        console.log(`  - ${t.model}: removed useSeeder trait from model`);
-      for (const t of result.traitStripSkipped)
-        log.warn(`  ! ${t.model}: useSeeder value couldn't be auto-removed \u2014 strip it manually (${t.file})`);
-      for (const e of result.errors)
-        log.warn(`  ! ${e.model}: ${e.error}`);
-      const verb = options.dryRun ? "would generate" : "generated", strippedVerb = options.dryRun ? "would strip" : "stripped";
-      await outro(`Seeder scaffold: ${verb} ${generated}, skipped ${alreadyThere} existing, ${strippedVerb} ${stripped} trait(s), ${errors} error(s).`, { startTime: perf, useSeconds: !0 });
-      process.exit(errors > 0 && generated === 0 ? ExitCode.FatalError : ExitCode.Success);
-    } catch (err) {
-      await outro("seed:scaffold failed", { startTime: perf, useSeconds: !0 }, err);
-      process.exit(ExitCode.FatalError);
+    const { seed: seedDatabase } = await import("@stacksjs/database"), list = (value) => value ? value.split(",").map((entry) => entry.trim()).filter(Boolean) : void 0, summary = await seedDatabase({
+      verbose: options.verbose,
+      fresh: options.fresh,
+      only: list(options.only),
+      except: list(options.except),
+      includeDefaults: options.includeDefaults,
+      allowProtected: options.allowProtected
+    }), APP_ENV = process.env.APP_ENV || "local";
+    if (summary.total === 0) {
+      await outro("No models declare a `useSeeder` trait \u2014 nothing to seed.", { startTime: perf, useSeconds: !0 });
+      process.exit(ExitCode.Success);
     }
+    await outro(`Seeded your ${APP_ENV} database. ${summary.successful}/${summary.total} model(s) seeded${summary.failed > 0 ? `, ${summary.failed} failed` : ""}.`, { startTime: perf, useSeconds: !0 });
+    process.exit(summary.failed > 0 ? ExitCode.FatalError : ExitCode.Success);
   });
   buddy.command("seed:roles", "Seed default RBAC role packs (admin, dev, client)").alias("roles:seed").action(async () => {
     const perf = await intro("buddy seed:roles");

package/dist/commands/serve.d.ts

@@ -1,11 +1,24 @@
 import type { CLI } from '@stacksjs/types';
 /**
- * Resolve the project's includes directory using Stacks conventions. Modern
- * Stacks apps keep reusable `.stx` fragments in `resources/components` and
- * commonly point `config/stx.ts#partialsDir` there; older apps may still use
- * one of the dedicated partials directories below.
+ * Resolve the project's includes directory.
+ *
+ * A configured `config/stx.ts#partialsDir` wins outright. The convention list
+ * below is only a fallback for apps that never set one, and it cannot stand in
+ * for the config: the candidates are probed for existence in order, so an app
+ * that keeps its includes in `resources/components` but also has an unrelated
+ * `resources/partials` directory silently resolved to the wrong one and every
+ * `@include` failed with ENOENT at runtime.
+ *
+ * The configured value is relative to the stx root (`resources`), matching how
+ * stx itself reads it, but an app-root-relative path is accepted too so either
+ * spelling resolves.
+ */
+export declare function resolveUserPartialsPath(cwd?: unknown, configuredDir?: string): string | undefined;
+/**
+ * Read `partialsDir` off the app's stx config. Failure is non-fatal: without
+ * it {@link resolveUserPartialsPath} falls back to the conventions.
  */
-export declare function resolveUserPartialsPath(cwd?: unknown): string | undefined;
+export declare function loadStxPartialsDir(cwd?: unknown): Promise<string | undefined>;
 /**` requests (and any non-GET/HEAD verb) are
  * reverse-proxied to the API process — mirroring the dev views server — so
  * scaffolded `fetch('/api/...')` calls behave identically in production

package/dist/commands/serve.js

@@ -30,7 +30,15 @@ function parseCookies(req) {
   }
   return out;
 }
-export function resolveUserPartialsPath(cwd = process.cwd()) {
+export function resolveUserPartialsPath(cwd = process.cwd(), configuredDir) {
+  if (configuredDir) {
+    const configured = [
+      join(cwd, "resources", configuredDir),
+      join(cwd, configuredDir)
+    ].find((candidate) => existsSync(candidate));
+    if (configured)
+      return configured;
+  }
   const relative = [
     "resources/partials",
     "resources/views/partials",
@@ -39,6 +47,17 @@ export function resolveUserPartialsPath(cwd = process.cwd()) {
   ].find((candidate) => existsSync(join(cwd, candidate)));
   return relative ? join(cwd, relative) : void 0;
 }
+export async function loadStxPartialsDir(cwd = process.cwd()) {
+  const configPath = join(cwd, "config/stx.ts");
+  if (!existsSync(configPath))
+    return;
+  try {
+    const dir = (await import(configPath)).default?.partialsDir;
+    return typeof dir === "string" && dir.length > 0 ? dir : void 0;
+  } catch {
+    return;
+  }
+}
 export function serve(buddy) {
   buddy.command("serve", "Start the production HTTP server (STX views + /api proxy + coming-soon/maintenance gate)").option("-p, --port <port>", "Port to listen on (defaults to PORT env or 3000)").option("--verbose", "Enable verbose output", { default: !1 }).action(async (options) => {
     if (options?.port)
@@ -62,7 +81,7 @@ export function serve(buddy) {
       } catch {}
     if (!stxServe)
       ({ serve: stxServe } = await import("bun-plugin-stx/serve"));
-    const stxModule = await resolveVendoredStxModule(), { site: siteConfig, i18n: i18nConfig } = await loadStxSiteConfig(), userViewsPath = "resources/views", defaultsResources = resolveDefaultsResources(), defaultViewsPath = join(defaultsResources, "views"), userLayoutsPath = existsSync("resources/views/layouts") ? "resources/views/layouts" : "resources/layouts", userPartialsPath = resolveUserPartialsPath(), apiBase = process.env.API_URL || `http://127.0.0.1:${Number(process.env.PORT_API) || config.ports?.api || 3008}`;
+    const stxModule = await resolveVendoredStxModule(), { site: siteConfig, i18n: i18nConfig } = await loadStxSiteConfig(), userViewsPath = "resources/views", defaultsResources = resolveDefaultsResources(), defaultViewsPath = join(defaultsResources, "views"), userLayoutsPath = existsSync("resources/views/layouts") ? "resources/views/layouts" : "resources/layouts", userPartialsPath = resolveUserPartialsPath(process.cwd(), await loadStxPartialsDir()), apiBase = process.env.API_URL || `http://127.0.0.1:${Number(process.env.PORT_API) || config.ports?.api || 3008}`;
     log.info(`Starting production server on port ${port}...`);
     await stxServe({
       patterns: [userViewsPath, defaultViewsPath],

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

@@ -0,0 +1,39 @@
+export declare function isAiProvider(value: string): value is AiProvider;
+/**
+ * Sets a project up for one AI coding agent. Idempotent: re-running it after a
+ * framework upgrade refreshes what it owns and leaves everything else alone.
+ */
+export declare function setupAiProvider(provider: AiProvider, options?: SetupAiOptions): SetupAiResult;
+/**
+ * Renders the result of a setup run.
+ */
+export declare function reportAiSetup(provider: AiProviderDefinition, result: SetupAiResult): void;
+/*.mdc`, Copilot reads `.github/copilot-instructions.md`,
+ * and Gemini CLI reads `GEMINI.md`.
+ */
+export declare const AI_PROVIDERS: readonly AiProviderDefinition[];
+export declare interface AiProviderDefinition {
+  id: AiProvider
+  label: string
+  reads: string[]
+}
+export declare interface SetupAiOptions {
+  copy?: boolean
+  force?: boolean
+}
+export declare interface SetupAiResult {
+  created: string[]
+  skipped: string[]
+}
+/**
+ * `buddy setup:ai` - wires a project up for an AI coding agent.
+ *
+ * The framework keeps its agent material in `storage/framework/defaults/ai`.
+ * Nothing there is read at runtime; this command materializes it into whatever
+ * files and directories the chosen agent actually looks for.
+ *
+ * Only `AGENTS.md` is committed - it is shared guidance every agent reads, and
+ * it belongs in review. The generated per-agent directories are gitignored,
+ * because which agent a developer uses is a personal choice.
+ */
+export type AiProvider = 'claude' | 'codex' | 'cursor' | 'copilot' | 'gemini';

package/dist/commands/setup-ai.js

@@ -0,0 +1,121 @@
+import { cpSync, existsSync, lstatSync, mkdirSync, readdirSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import process from "node:process";
+import { dim, green, log, yellow } from "@stacksjs/cli";
+import { frameworkPath, join, projectPath, relative } from "@stacksjs/path";
+import { listSkills, resolveSkillPath } from "@stacksjs/skills";
+export const AI_PROVIDERS = [
+  { id: "claude", label: "Claude Code", reads: ["AGENTS.md", "CLAUDE.md", ".claude/skills", ".claude/launch.json"] },
+  { id: "codex", label: "OpenAI Codex CLI", reads: ["AGENTS.md"] },
+  { id: "cursor", label: "Cursor", reads: ["AGENTS.md", ".cursor/rules"] },
+  { id: "copilot", label: "GitHub Copilot", reads: ["AGENTS.md", ".github/copilot-instructions.md"] },
+  { id: "gemini", label: "Gemini CLI", reads: ["AGENTS.md", "GEMINI.md"] }
+];
+export function isAiProvider(value) {
+  return AI_PROVIDERS.some((provider) => provider.id === value);
+}
+function materialize(target, path, options) {
+  const existing = lstatSync(path, { throwIfNoEntry: !1 });
+  if (existing) {
+    if (!existing.isSymbolicLink() && !options.force)
+      return !1;
+    rmSync(path, { recursive: !0, force: !0 });
+  }
+  mkdirSync(join(path, ".."), { recursive: !0 });
+  if (options.copy)
+    cpSync(target, path, { recursive: !0 });
+  else
+    symlinkSync(relative(join(path, ".."), target), path, process.platform === "win32" ? "junction" : "dir");
+  return !0;
+}
+function materializeFile(source, path, options) {
+  if (existsSync(path) && !options.force)
+    return !1;
+  mkdirSync(join(path, ".."), { recursive: !0 });
+  cpSync(source, path, { recursive: !0, force: !0 });
+  return !0;
+}
+function installSkills(destination, options) {
+  const names = listSkills();
+  let installed = 0, skipped = 0;
+  mkdirSync(destination, { recursive: !0 });
+  for (const entry of readdirSync(destination)) {
+    const path = join(destination, entry);
+    if (lstatSync(path, { throwIfNoEntry: !1 })?.isSymbolicLink() && !existsSync(path))
+      rmSync(path, { force: !0 });
+  }
+  for (const name of names) {
+    const source = resolveSkillPath(name);
+    if (!source)
+      continue;
+    if (materialize(source, join(destination, name), options))
+      installed++;
+    else
+      skipped++;
+  }
+  return { installed, skipped };
+}
+export function setupAiProvider(provider, options = {}) {
+  const created = [], skipped = [], defaults = frameworkPath("defaults/ai"), rel = (path) => relative(projectPath(), path), record = (path, didCreate) => {
+    (didCreate ? created : skipped).push(rel(path));
+  }, agents = projectPath("AGENTS.md");
+  record(agents, materializeFile(join(defaults, "AGENTS.md"), agents, { ...options, force: !1 }));
+  switch (provider) {
+    case "claude": {
+      const claudeMd = projectPath("CLAUDE.md");
+      record(claudeMd, materialize(agents, claudeMd, { ...options, copy: !1 }));
+      const launch = projectPath(".claude/launch.json");
+      record(launch, materializeFile(join(defaults, "claude/launch.json"), launch, options));
+      const skillsDir = projectPath(".claude/skills"), { installed, skipped: untouched } = installSkills(skillsDir, options);
+      if (installed > 0)
+        created.push(`${rel(skillsDir)} (${installed} skills)`);
+      if (untouched > 0)
+        skipped.push(`${rel(skillsDir)} (${untouched} skills)`);
+      break;
+    }
+    case "codex":
+      break;
+    case "cursor": {
+      const rules = projectPath(".cursor/rules");
+      record(rules, materialize(frameworkPath("defaults/ide/cursor/rules"), rules, options));
+      break;
+    }
+    case "copilot": {
+      const instructions = projectPath(".github/copilot-instructions.md");
+      if (existsSync(instructions) && !options.force)
+        skipped.push(rel(instructions));
+      else {
+        mkdirSync(projectPath(".github"), { recursive: !0 });
+        writeFileSync(instructions, pointerFile("AGENTS.md"), "utf8");
+        created.push(rel(instructions));
+      }
+      break;
+    }
+    case "gemini": {
+      const geminiMd = projectPath("GEMINI.md");
+      record(geminiMd, materialize(agents, geminiMd, { ...options, copy: !1 }));
+      break;
+    }
+  }
+  return { created, skipped };
+}
+function pointerFile(target) {
+  return [
+    "# Project instructions",
+    "",
+    `This project keeps its agent guidance in [\`${target}\`](../${target}), so every`,
+    "agent works from the same rules. Read that file.",
+    "",
+    "Regenerate this pointer with `buddy setup:ai copilot --force`.",
+    ""
+  ].join(`
+`);
+}
+export function reportAiSetup(provider, result) {
+  for (const path of result.created)
+    log.info(`  ${green("+")} ${path}`);
+  for (const path of result.skipped)
+    log.info(`  ${yellow("\xB7")} ${path} ${dim("(already present, left alone)")}`);
+  if (result.created.length === 0)
+    log.info(dim("  Nothing to do - re-run with --force to overwrite."));
+  log.success(`${provider.label} is set up. It reads: ${provider.reads.join(", ")}`);
+}

package/dist/commands/setup.js

@@ -21,6 +21,9 @@ export function setup(buddy) {
   const descriptions = {
     setup: "This command ensures your project is setup correctly",
     ssl: "Setup SSL certificates and hosts file for HTTPS development",
+    ai: "Set the project up for an AI coding agent (Claude Code, Codex, Cursor, Copilot, Gemini)",
+    copy: "Copy the agent files instead of symlinking them, so they can be edited per project",
+    force: "Overwrite files that already exist",
     ohMyZsh: "Enable Oh My Zsh",
     aws: "Ensures AWS is connected to the project",
     project: "Target a specific project",
@@ -49,6 +52,25 @@ export function setup(buddy) {
       log.info("You may need to manually trust certificates or update hosts file");
     }
   });
+  buddy.command("setup:ai [provider]", descriptions.ai).alias("ai:setup").option("--copy", descriptions.copy, { default: !1 }).option("--force", descriptions.force, { default: !1 }).option("--verbose", descriptions.verbose, { default: !1 }).action(async (provider, options) => {
+    log.debug("Running `buddy setup:ai` ...", options);
+    const { AI_PROVIDERS, isAiProvider, reportAiSetup, setupAiProvider } = await import("./setup-ai");
+    let id = provider;
+    if (!id) {
+      const { select } = await import("@stacksjs/cli");
+      id = await select({
+        message: "Which AI coding agent do you use?",
+        choices: AI_PROVIDERS.map((entry) => ({ value: entry.id, label: entry.label })),
+        initial: 0
+      });
+    }
+    if (!id || !isAiProvider(id)) {
+      log.error(`Unknown AI provider: ${id}. Expected one of: ${AI_PROVIDERS.map((entry) => entry.id).join(", ")}`);
+      process.exit(ExitCode.InvalidArgument);
+    }
+    const definition = AI_PROVIDERS.find((entry) => entry.id === id);
+    reportAiSetup(definition, setupAiProvider(id, { copy: options.copy, force: options.force }));
+  });
   buddy.command("setup:oh-my-zsh", descriptions.ohMyZsh).alias("upgrade:oh-my-zsh").option("--verbose", descriptions.verbose, { default: !1 }).action(async (_options) => {
     log.debug("Running `buddy setup:oh-my-zsh` ...", _options);
     const result = await runAction(Action.UpgradeShell);

package/dist/lazy-commands.js

@@ -1,6 +1,7 @@
 const commandRegistry = {
   about: { path: "./commands/about.js", exportName: "about" },
   add: { path: "./commands/add.js", exportName: "add" },
+  "ai:context": { path: "./commands/ai-context.js", exportName: "aiContext" },
   auth: { path: "./commands/auth.js", exportName: "auth" },
   build: { path: "./commands/build.js", exportName: "build" },
   cd: { path: "./commands/cd.js", exportName: "cd" },
@@ -99,6 +100,10 @@ const commandRegistry = {
   serve: { path: "./commands/serve.js", exportName: "serve" },
   "serve:api": { path: "./commands/serve.js", exportName: "serveApi" },
   setup: { path: "./commands/setup.js", exportName: "setup" },
+  "setup:ai": { path: "./commands/setup.js", exportName: "setup" },
+  "setup:ssl": { path: "./commands/setup.js", exportName: "setup" },
+  "setup:oh-my-zsh": { path: "./commands/setup.js", exportName: "setup" },
+  "ai:setup": { path: "./commands/setup.js", exportName: "setup" },
   share: { path: "./commands/share.js", exportName: "share" },
   stack: { path: "./commands/stacks.js", exportName: "stacks" },
   sms: { path: "./commands/sms.js", exportName: "sms" },
@@ -108,7 +113,29 @@ const commandRegistry = {
   types: { path: "./commands/types.js", exportName: "types" },
   undeploy: { path: "./commands/cloud.js", exportName: "cloud" },
   upgrade: { path: "./commands/upgrade.js", exportName: "upgrade" },
-  version: { path: "./commands/version.js", exportName: "version" }
+  version: { path: "./commands/version.js", exportName: "version" },
+  "protocol:conformance": { path: "./commands/protocol.js", exportName: "protocol" },
+  "protocol:sync": { path: "./commands/protocol.js", exportName: "protocol" },
+  "protocol:check": { path: "./commands/protocol.js", exportName: "protocol" },
+  "protocol:manifest": { path: "./commands/protocol.js", exportName: "protocol" },
+  "protocol:manifest:check": { path: "./commands/protocol.js", exportName: "protocol" },
+  "protocol:release": { path: "./commands/protocol.js", exportName: "protocol" },
+  "protocol:release:check": { path: "./commands/protocol.js", exportName: "protocol" },
+  "protocol:drivers": { path: "./commands/protocol.js", exportName: "protocol" },
+  "protocol:drivers:check": { path: "./commands/protocol.js", exportName: "protocol" },
+  "protocol:drivers:test": { path: "./commands/protocol.js", exportName: "protocol" },
+  "protocol:desktop": { path: "./commands/protocol.js", exportName: "protocol" },
+  "protocol:desktop:check": { path: "./commands/protocol.js", exportName: "protocol" },
+  "protocol:pantry": { path: "./commands/protocol.js", exportName: "protocol" },
+  "protocol:pantry:check": { path: "./commands/protocol.js", exportName: "protocol" },
+  "protocol:craft": { path: "./commands/protocol.js", exportName: "protocol" },
+  "protocol:craft:check": { path: "./commands/protocol.js", exportName: "protocol" },
+  "docs:buddy": { path: "./commands/docs.js", exportName: "docs" },
+  "docs:buddy:check": { path: "./commands/docs.js", exportName: "docs" },
+  "docs:artifacts": { path: "./commands/docs.js", exportName: "docs" },
+  "docs:artifacts:check": { path: "./commands/docs.js", exportName: "docs" },
+  "docs:links": { path: "./commands/docs.js", exportName: "docs" },
+  "docs:links:check": { path: "./commands/docs.js", exportName: "docs" }
 }, commandGroups = {
   minimal: ["version", "help"],
   development: ["dev", "build", "test", "lint"],

package/dist/project-setup.js

@@ -12,6 +12,7 @@ const APP_KEY_OPTIONAL_COMMANDS = [
   "clean",
   "fresh",
   "about",
+  "ai:context",
   "doctor",
   "list",
   "setup",