@stacksjs/buddy 0.70.163 → 0.70.164

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

@@ -100,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" },
@@ -109,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/package.json

@@ -2,7 +2,7 @@
   "name": "@stacksjs/buddy",
   "type": "module",
   "sideEffects": false,
-  "version": "0.70.163",
+  "version": "0.70.164",
   "description": "Meet Buddy. The Stacks runtime.",
   "author": "Chris Breuer",
   "contributors": [
@@ -91,52 +91,53 @@
     "prepublishOnly": "bun run build"
   },
   "dependencies": {
-    "@stacksjs/actions": "^0.70.163",
-    "@stacksjs/ai": "^0.70.163",
-    "@stacksjs/alias": "^0.70.163",
-    "@stacksjs/arrays": "^0.70.163",
-    "@stacksjs/auth": "^0.70.163",
-    "@stacksjs/build": "^0.70.163",
-    "@stacksjs/cache": "^0.70.163",
-    "@stacksjs/cli": "^0.70.163",
+    "@stacksjs/actions": "^0.70.164",
+    "@stacksjs/ai": "^0.70.164",
+    "@stacksjs/alias": "^0.70.164",
+    "@stacksjs/arrays": "^0.70.164",
+    "@stacksjs/auth": "^0.70.164",
+    "@stacksjs/build": "^0.70.164",
+    "@stacksjs/cache": "^0.70.164",
+    "@stacksjs/cli": "^0.70.164",
     "@stacksjs/clapp": "^0.2.12",
-    "@stacksjs/cloud": "^0.70.163",
-    "@stacksjs/collections": "^0.70.163",
-    "@stacksjs/config": "^0.70.163",
-    "@stacksjs/database": "^0.70.163",
-    "@stacksjs/desktop": "^0.70.163",
-    "@stacksjs/dns": "^0.70.163",
-    "@stacksjs/email": "^0.70.163",
-    "@stacksjs/enums": "^0.70.163",
-    "@stacksjs/error-handling": "^0.70.163",
-    "@stacksjs/events": "^0.70.163",
-    "@stacksjs/git": "^0.70.163",
+    "@stacksjs/cloud": "^0.70.164",
+    "@stacksjs/collections": "^0.70.164",
+    "@stacksjs/config": "^0.70.164",
+    "@stacksjs/database": "^0.70.164",
+    "@stacksjs/desktop": "^0.70.164",
+    "@stacksjs/dns": "^0.70.164",
+    "@stacksjs/email": "^0.70.164",
+    "@stacksjs/enums": "^0.70.164",
+    "@stacksjs/error-handling": "^0.70.164",
+    "@stacksjs/events": "^0.70.164",
+    "@stacksjs/git": "^0.70.164",
     "@stacksjs/gitit": "^0.2.5",
-    "@stacksjs/health": "^0.70.163",
+    "@stacksjs/health": "^0.70.164",
     "@stacksjs/dnsx": "^0.2.3",
     "@stacksjs/httx": "^0.1.10",
-    "@stacksjs/lint": "^0.70.163",
-    "@stacksjs/logging": "^0.70.163",
-    "@stacksjs/notifications": "^0.70.163",
-    "@stacksjs/objects": "^0.70.163",
-    "@stacksjs/orm": "^0.70.163",
-    "@stacksjs/path": "^0.70.163",
-    "@stacksjs/payments": "^0.70.163",
-    "@stacksjs/realtime": "^0.70.163",
-    "@stacksjs/router": "^0.70.163",
+    "@stacksjs/lint": "^0.70.164",
+    "@stacksjs/logging": "^0.70.164",
+    "@stacksjs/notifications": "^0.70.164",
+    "@stacksjs/objects": "^0.70.164",
+    "@stacksjs/orm": "^0.70.164",
+    "@stacksjs/path": "^0.70.164",
+    "@stacksjs/skills": "^0.70.164",
+    "@stacksjs/payments": "^0.70.164",
+    "@stacksjs/realtime": "^0.70.164",
+    "@stacksjs/router": "^0.70.164",
     "@stacksjs/rpx": "^0.11.31",
-    "@stacksjs/search-engine": "^0.70.163",
-    "@stacksjs/security": "^0.70.163",
-    "@stacksjs/server": "^0.70.163",
-    "@stacksjs/storage": "^0.70.163",
-    "@stacksjs/strings": "^0.70.163",
-    "@stacksjs/testing": "^0.70.163",
-    "@stacksjs/tunnel": "^0.70.163",
-    "@stacksjs/types": "^0.70.163",
-    "@stacksjs/ui": "^0.70.163",
-    "@stacksjs/utils": "^0.70.163",
-    "@stacksjs/validation": "^0.70.163",
-    "@stacksjs/ts-cloud": "^0.7.56"
+    "@stacksjs/search-engine": "^0.70.164",
+    "@stacksjs/security": "^0.70.164",
+    "@stacksjs/server": "^0.70.164",
+    "@stacksjs/storage": "^0.70.164",
+    "@stacksjs/strings": "^0.70.164",
+    "@stacksjs/testing": "^0.70.164",
+    "@stacksjs/tunnel": "^0.70.164",
+    "@stacksjs/types": "^0.70.164",
+    "@stacksjs/ui": "^0.70.164",
+    "@stacksjs/utils": "^0.70.164",
+    "@stacksjs/validation": "^0.70.164",
+    "@stacksjs/ts-cloud": "^0.7.60"
   },
   "devDependencies": {
     "better-dx": "^0.2.17"