@stacksjs/defaults 0.75.255 → 0.75.257

package/resources/components/Dashboard/Content/PostEditorDialog.stx

@@ -28,7 +28,11 @@ interface PostDraft {
 }
 
 const open = useReactiveProp('open', false)
-const post = useReactiveProp('post', null as PostRecord | null)
+// Named `editing`, not `post`, while still reading the `post` prop.
+// A bare `post` in a `{{ … }}` interpolation is resolved server-side
+// against module and global scope, where it finds the dashboard API
+// client's own `post()` and calls it mid-render (stacksjs/stacks#2944).
+const editing = useReactiveProp('post', null as PostRecord | null)
 const categories = useReactiveProp('categories', [] as OptionRecord[])
 const tags = useReactiveProp('tags', [] as OptionRecord[])
 const authors = useReactiveProp('authors', [] as AuthorRecord[])
@@ -49,7 +53,7 @@ let wasOpen = false
 effect(() => {
   const isOpen = open()
   if (isOpen && !wasOpen) {
-    const record = post()
+    const record = editing()
     title.set(record?.title || '')
     excerpt.set(record?.excerpt || '')
     content.set(record?.content || '')
@@ -93,7 +97,7 @@ function submit(): void {
 
 <Modal
   :isOpen="open()"
-  :title="post() ? 'Edit post' : 'New post'"
+  :title="editing() ? 'Edit post' : 'New post'"
   description="Content, ownership, and taxonomies are persisted together."
   size="xl"
   :closable="!busy()"
@@ -169,7 +173,7 @@ function submit(): void {
     <div class="flex gap-2 justify-end w-full">
       <Button :disabled="busy()" variant="secondary" @click="close">Cancel</Button>
       <Button type="submit" form="post-editor-form" :disabled="!valid()" :loading="busy()">
-        {{ post() ? 'Save changes' : 'Create post' }}
+        {{ editing() ? 'Save changes' : 'Create post' }}
       </Button>
     </div>
   </template>

package/resources/functions/dashboard/data.ts

@@ -17,123 +17,110 @@
  */
 
 import { existsSync } from 'node:fs'
-import { basename, dirname, resolve } from 'node:path'
-
-let projectRootCache: string | null = null
-
-const VENDORED_DEFAULTS_PREFIX = 'storage/framework/defaults/'
-let defaultsRootCache: string | null = null
+import { basename, resolve } from 'node:path'
+import { defaultsPath, projectPath } from '@stacksjs/path'
 
 /**
- * The framework defaults tree: `storage/framework/defaults` in a project that
- * vendors it, `node_modules/@stacksjs/defaults` in one that does not. Counted
- * from this file first, which is inside that tree in both layouts; the project
- * root is the fallback for a copy that was bundled somewhere else.
+ * The project root, and where the defaults tree is, both from
+ * `@stacksjs/path`.
+ *
+ * This file used to hand-roll the walk, explicitly to avoid importing the
+ * path package, which was recorded as having "its own evaluation graph" that
+ * "would slow page renders". Measured rather than inherited: importing
+ * `@stacksjs/path` in this checkout costs 1.5-2.7ms, once per process because
+ * the module cache holds it, not once per render. `preloader.ts` next door
+ * already imports it.
+ *
+ * The walk also had to go, independently of cost. It anchored on a directory
+ * containing `storage/framework/defaults`, which is the one directory
+ * stacksjs/stacks#2941 is removing: in a project resolving its defaults from
+ * `node_modules`, the walk would find no anchor and fall through to
+ * `process.cwd()`, which is right only by luck.
  */
-function defaultsRoot(): string {
-  if (defaultsRootCache) return defaultsRootCache
-  const own = resolve(dirname(new URL(import.meta.url).pathname), '../../..')
-  const candidates = [
-    own,
-    resolve(projectRoot(), 'storage/framework/defaults'),
-    resolve(projectRoot(), 'node_modules/@stacksjs/defaults'),
-  ]
-  defaultsRootCache = candidates.find(candidate => existsSync(resolve(candidate, 'app/Models'))) ?? candidates[1]!
-  return defaultsRootCache
-}
-
 function projectRoot(): string {
-  if (projectRootCache) return projectRootCache
-  // Walk up from this file location to find the project root (the dir
-  // that contains `storage/framework`). This mirrors what
-  // `@stacksjs/path` does, but without pulling in the path package
-  // (which has its own evaluation graph and would slow page renders).
-  let dir = dirname(new URL(import.meta.url).pathname)
-  for (let i = 0; i < 12; i++) {
-    if (existsSync(resolve(dir, 'storage/framework'))) {
-      projectRootCache = dir
-      return dir
-    }
-    const parent = dirname(dir)
-    if (parent === dir) break
-    dir = parent
-  }
-  // Fall back to cwd — STX serves run from the project root.
-  projectRootCache = process.cwd()
-  return projectRootCache
+  return projectPath()
 }
 
 /**
- * Fast-path map of common model names to relative paths. The first existing
- * file wins, and user overrides always take priority over framework defaults.
- * A cached filesystem index below covers newly-added and nested models so
- * this map is an optimization rather than a correctness requirement.
+ * Fast-path map of common model names to the two places they can live:
+ * `[path under the project, path under the defaults tree]`.
+ *
+ * The first existing file wins, and user overrides always take priority over
+ * framework defaults. A cached filesystem index below covers newly-added and
+ * nested models, so this map is an optimization rather than a correctness
+ * requirement.
+ *
+ * The second element is relative to the defaults tree rather than to the
+ * project, because that tree is not always inside the project: it is
+ * `storage/framework/defaults` when the project vendors a current copy and the
+ * installed `@stacksjs/defaults` otherwise (stacksjs/stacks#2941). Fifty-five
+ * rows used to spell `storage/framework/defaults/` out by hand.
  */
-const MODEL_PATHS: Record<string, string[]> = {
+const MODEL_PATHS: Record<string, [string, string]> = {
   // Auth / core
-  User: ['app/Models/User.ts', 'storage/framework/defaults/app/Models/User.ts'],
-  Team: ['app/Models/Team.ts', 'storage/framework/defaults/app/Models/Team.ts'],
-  Subscriber: ['app/Models/Subscriber.ts', 'storage/framework/defaults/app/Models/Subscriber.ts'],
-  SubscriberEmail: ['app/Models/SubscriberEmail.ts', 'storage/framework/defaults/app/Models/SubscriberEmail.ts'],
-  Subscription: ['app/Models/Subscription.ts', 'storage/framework/defaults/app/Models/Subscription.ts'],
+  User: ['app/Models/User.ts', 'app/Models/User.ts'],
+  Team: ['app/Models/Team.ts', 'app/Models/Team.ts'],
+  Subscriber: ['app/Models/Subscriber.ts', 'app/Models/Subscriber.ts'],
+  SubscriberEmail: ['app/Models/SubscriberEmail.ts', 'app/Models/SubscriberEmail.ts'],
+  Subscription: ['app/Models/Subscription.ts', 'app/Models/Subscription.ts'],
 
   // Content
-  Post: ['app/Models/Post.ts', 'storage/framework/defaults/app/Models/Content/Post.ts'],
-  Page: ['app/Models/Page.ts', 'storage/framework/defaults/app/Models/Content/Page.ts'],
-  Author: ['app/Models/Author.ts', 'storage/framework/defaults/app/Models/Content/Author.ts'],
-  Comment: ['app/Models/Comment.ts', 'storage/framework/defaults/app/Models/Comment.ts'],
-  Tag: ['app/Models/Tag.ts', 'storage/framework/defaults/app/Models/Tag.ts'],
-  Category: ['app/Models/Category.ts', 'storage/framework/defaults/app/Models/commerce/Category.ts'],
+  Post: ['app/Models/Post.ts', 'app/Models/Content/Post.ts'],
+  Page: ['app/Models/Page.ts', 'app/Models/Content/Page.ts'],
+  Author: ['app/Models/Author.ts', 'app/Models/Content/Author.ts'],
+  Comment: ['app/Models/Comment.ts', 'app/Models/Comment.ts'],
+  Tag: ['app/Models/Tag.ts', 'app/Models/Tag.ts'],
+  Category: ['app/Models/Category.ts', 'app/Models/commerce/Category.ts'],
 
   // App / operations
-  Activity: ['app/Models/Activity.ts', 'storage/framework/defaults/app/Models/Activity.ts'],
-  Deployment: ['app/Models/Deployment.ts', 'storage/framework/defaults/app/Models/Deployment.ts'],
-  Release: ['app/Models/Release.ts', 'storage/framework/defaults/app/Models/Release.ts'],
-  Notification: ['app/Models/Notification.ts', 'storage/framework/defaults/app/Models/Notification.ts'],
-  Job: ['app/Models/Job.ts', 'storage/framework/defaults/app/Models/Job.ts'],
-  FailedJob: ['app/Models/FailedJob.ts', 'storage/framework/defaults/app/Models/FailedJob.ts'],
-  Log: ['app/Models/Log.ts', 'storage/framework/defaults/app/Models/Log.ts'],
-  Request: ['app/Models/Request.ts', 'storage/framework/defaults/app/Models/Request.ts'],
-  Error: ['app/Models/Error.ts', 'storage/framework/defaults/app/Models/Error.ts'],
-  Websocket: ['app/Models/Websocket.ts', 'storage/framework/defaults/app/Models/realtime/Websocket.ts'],
+  Activity: ['app/Models/Activity.ts', 'app/Models/Activity.ts'],
+  Deployment: ['app/Models/Deployment.ts', 'app/Models/Deployment.ts'],
+  Release: ['app/Models/Release.ts', 'app/Models/Release.ts'],
+  Notification: ['app/Models/Notification.ts', 'app/Models/Notification.ts'],
+  Job: ['app/Models/Job.ts', 'app/Models/Job.ts'],
+  FailedJob: ['app/Models/FailedJob.ts', 'app/Models/FailedJob.ts'],
+  Log: ['app/Models/Log.ts', 'app/Models/Log.ts'],
+  Request: ['app/Models/Request.ts', 'app/Models/Request.ts'],
+  Error: ['app/Models/Error.ts', 'app/Models/Error.ts'],
+  Websocket: ['app/Models/Websocket.ts', 'app/Models/realtime/Websocket.ts'],
 
   // Marketing
-  Campaign: ['app/Models/Campaign.ts', 'storage/framework/defaults/app/Models/Campaign.ts'],
-  EmailList: ['app/Models/EmailList.ts', 'storage/framework/defaults/app/Models/EmailList.ts'],
-  SocialPost: ['app/Models/SocialPost.ts', 'storage/framework/defaults/app/Models/SocialPost.ts'],
+  Campaign: ['app/Models/Campaign.ts', 'app/Models/Campaign.ts'],
+  EmailList: ['app/Models/EmailList.ts', 'app/Models/EmailList.ts'],
+  SocialPost: ['app/Models/SocialPost.ts', 'app/Models/SocialPost.ts'],
 
   // Commerce
-  Order: ['app/Models/Order.ts', 'storage/framework/defaults/app/Models/commerce/Order.ts'],
-  OrderItem: ['app/Models/OrderItem.ts', 'storage/framework/defaults/app/Models/commerce/OrderItem.ts'],
-  Cart: ['app/Models/Cart.ts', 'storage/framework/defaults/app/Models/commerce/Cart.ts'],
-  CartItem: ['app/Models/CartItem.ts', 'storage/framework/defaults/app/Models/commerce/CartItem.ts'],
-  Customer: ['app/Models/Customer.ts', 'storage/framework/defaults/app/Models/commerce/Customer.ts'],
-  Product: ['app/Models/Product.ts', 'storage/framework/defaults/app/Models/commerce/Product.ts'],
-  ProductVariant: ['app/Models/ProductVariant.ts', 'storage/framework/defaults/app/Models/commerce/ProductVariant.ts'],
-  ProductUnit: ['app/Models/ProductUnit.ts', 'storage/framework/defaults/app/Models/commerce/ProductUnit.ts'],
-  Manufacturer: ['app/Models/Manufacturer.ts', 'storage/framework/defaults/app/Models/commerce/Manufacturer.ts'],
-  Coupon: ['app/Models/Coupon.ts', 'storage/framework/defaults/app/Models/commerce/Coupon.ts'],
-  GiftCard: ['app/Models/GiftCard.ts', 'storage/framework/defaults/app/Models/commerce/GiftCard.ts'],
-  LicenseKey: ['app/Models/LicenseKey.ts', 'storage/framework/defaults/app/Models/commerce/LicenseKey.ts'],
-  Review: ['app/Models/Review.ts', 'storage/framework/defaults/app/Models/commerce/Review.ts'],
-  Receipt: ['app/Models/Receipt.ts', 'storage/framework/defaults/app/Models/commerce/Receipt.ts'],
-  PrintDevice: ['app/Models/PrintDevice.ts', 'storage/framework/defaults/app/Models/commerce/PrintDevice.ts'],
-  ShippingMethod: ['app/Models/ShippingMethod.ts', 'storage/framework/defaults/app/Models/commerce/ShippingMethod.ts'],
-  ShippingRate: ['app/Models/ShippingRate.ts', 'storage/framework/defaults/app/Models/commerce/ShippingRate.ts'],
-  ShippingZone: ['app/Models/ShippingZone.ts', 'storage/framework/defaults/app/Models/commerce/ShippingZone.ts'],
-  DeliveryRoute: ['app/Models/DeliveryRoute.ts', 'storage/framework/defaults/app/Models/commerce/DeliveryRoute.ts'],
-  DigitalDelivery: ['app/Models/DigitalDelivery.ts', 'storage/framework/defaults/app/Models/commerce/DigitalDelivery.ts'],
-  Courier: ['app/Models/Courier.ts', 'storage/framework/defaults/app/Models/commerce/Courier.ts'],
-  TaxRate: ['app/Models/TaxRate.ts', 'storage/framework/defaults/app/Models/commerce/TaxRate.ts'],
-  WaitlistProduct: ['app/Models/WaitlistProduct.ts', 'storage/framework/defaults/app/Models/commerce/WaitlistProduct.ts'],
-  WaitlistRestaurant: ['app/Models/WaitlistRestaurant.ts', 'storage/framework/defaults/app/Models/commerce/WaitlistRestaurant.ts'],
-  LoyaltyPoint: ['app/Models/LoyaltyPoint.ts', 'storage/framework/defaults/app/Models/commerce/LoyaltyPoint.ts'],
-  LoyaltyReward: ['app/Models/LoyaltyReward.ts', 'storage/framework/defaults/app/Models/commerce/LoyaltyReward.ts'],
-  Payment: ['app/Models/Payment.ts', 'storage/framework/defaults/app/Models/commerce/Payment.ts'],
-  PaymentMethod: ['app/Models/PaymentMethod.ts', 'storage/framework/defaults/app/Models/PaymentMethod.ts'],
-  PaymentProduct: ['app/Models/PaymentProduct.ts', 'storage/framework/defaults/app/Models/PaymentProduct.ts'],
-  PaymentTransaction: ['app/Models/PaymentTransaction.ts', 'storage/framework/defaults/app/Models/PaymentTransaction.ts'],
-  Transaction: ['app/Models/Transaction.ts', 'storage/framework/defaults/app/Models/commerce/Transaction.ts'],
+  Order: ['app/Models/Order.ts', 'app/Models/commerce/Order.ts'],
+  OrderItem: ['app/Models/OrderItem.ts', 'app/Models/commerce/OrderItem.ts'],
+  Cart: ['app/Models/Cart.ts', 'app/Models/commerce/Cart.ts'],
+  CartItem: ['app/Models/CartItem.ts', 'app/Models/commerce/CartItem.ts'],
+  Customer: ['app/Models/Customer.ts', 'app/Models/commerce/Customer.ts'],
+  Product: ['app/Models/Product.ts', 'app/Models/commerce/Product.ts'],
+  ProductVariant: ['app/Models/ProductVariant.ts', 'app/Models/commerce/ProductVariant.ts'],
+  ProductUnit: ['app/Models/ProductUnit.ts', 'app/Models/commerce/ProductUnit.ts'],
+  Manufacturer: ['app/Models/Manufacturer.ts', 'app/Models/commerce/Manufacturer.ts'],
+  Coupon: ['app/Models/Coupon.ts', 'app/Models/commerce/Coupon.ts'],
+  GiftCard: ['app/Models/GiftCard.ts', 'app/Models/commerce/GiftCard.ts'],
+  LicenseKey: ['app/Models/LicenseKey.ts', 'app/Models/commerce/LicenseKey.ts'],
+  Review: ['app/Models/Review.ts', 'app/Models/commerce/Review.ts'],
+  Receipt: ['app/Models/Receipt.ts', 'app/Models/commerce/Receipt.ts'],
+  PrintDevice: ['app/Models/PrintDevice.ts', 'app/Models/commerce/PrintDevice.ts'],
+  ShippingMethod: ['app/Models/ShippingMethod.ts', 'app/Models/commerce/ShippingMethod.ts'],
+  ShippingRate: ['app/Models/ShippingRate.ts', 'app/Models/commerce/ShippingRate.ts'],
+  ShippingZone: ['app/Models/ShippingZone.ts', 'app/Models/commerce/ShippingZone.ts'],
+  DeliveryRoute: ['app/Models/DeliveryRoute.ts', 'app/Models/commerce/DeliveryRoute.ts'],
+  DigitalDelivery: ['app/Models/DigitalDelivery.ts', 'app/Models/commerce/DigitalDelivery.ts'],
+  Courier: ['app/Models/Courier.ts', 'app/Models/commerce/Courier.ts'],
+  TaxRate: ['app/Models/TaxRate.ts', 'app/Models/commerce/TaxRate.ts'],
+  WaitlistProduct: ['app/Models/WaitlistProduct.ts', 'app/Models/commerce/WaitlistProduct.ts'],
+  WaitlistRestaurant: ['app/Models/WaitlistRestaurant.ts', 'app/Models/commerce/WaitlistRestaurant.ts'],
+  LoyaltyPoint: ['app/Models/LoyaltyPoint.ts', 'app/Models/commerce/LoyaltyPoint.ts'],
+  LoyaltyReward: ['app/Models/LoyaltyReward.ts', 'app/Models/commerce/LoyaltyReward.ts'],
+  Payment: ['app/Models/Payment.ts', 'app/Models/commerce/Payment.ts'],
+  PaymentMethod: ['app/Models/PaymentMethod.ts', 'app/Models/PaymentMethod.ts'],
+  PaymentProduct: ['app/Models/PaymentProduct.ts', 'app/Models/PaymentProduct.ts'],
+  PaymentTransaction: ['app/Models/PaymentTransaction.ts', 'app/Models/PaymentTransaction.ts'],
+  Transaction: ['app/Models/Transaction.ts', 'app/Models/commerce/Transaction.ts'],
 }
 
 const modelCache = new Map<string, any>()
@@ -153,7 +140,7 @@ async function discoverModelPaths(): Promise<Map<string, string[]>> {
     const paths = new Map<string, string[]>()
     const modelRoots = [
       resolve(root, 'app/Models'),
-      resolve(defaultsRoot(), 'app/Models'),
+      defaultsPath('app/Models'),
     ]
 
     for (const modelsRoot of modelRoots) {
@@ -178,11 +165,11 @@ async function discoverModelPaths(): Promise<Map<string, string[]>> {
 }
 
 async function modelCandidatePaths(name: string): Promise<string[]> {
-  const root = projectRoot()
   const discovered = (await discoverModelPaths()).get(name) ?? []
-  const explicit = (MODEL_PATHS[name] ?? []).map(path => path.startsWith(VENDORED_DEFAULTS_PREFIX)
-    ? resolve(defaultsRoot(), path.slice(VENDORED_DEFAULTS_PREFIX.length))
-    : resolve(root, path))
+  const entry = MODEL_PATHS[name]
+  const explicit = entry
+    ? [resolve(projectRoot(), entry[0]), defaultsPath(entry[1])]
+    : []
   return [...new Set([...discovered, ...explicit])]
 }
 

package/resources/functions/dashboard/sidebar.ts

@@ -111,15 +111,41 @@ interface NavItem {
 }
 
 /**
- * Pull the discovered-models manifest `buddy dev:dashboard` writes into the
- * project's runtime state.
- * Returns the default empty payload when the file is absent (fresh project
+ * Where `buddy dev --dashboard` writes the discovered-models manifest, and
+ * where this reads it: under `storage/framework/runtime/`, which `.gitignore`
+ * covers.
+ */
+export const DISCOVERED_MANIFEST_PATH = 'storage/framework/runtime/dashboard/.discovered-models.json'
+
+/**
+ * Where it used to be written, inside the vendored framework tree.
+ *
+ * Read as a fallback rather than dropped, because an app that upgrades does
+ * not get a new manifest until its next `buddy dev --dashboard` - and without
+ * this it would render an empty sidebar until then. New writes only ever go
+ * to the path above.
+ */
+export const LEGACY_DISCOVERED_MANIFEST_PATH = 'storage/framework/defaults/views/dashboard/.discovered-models.json'
+
+/** The first of the two manifest paths that exists, or null when neither does. */
+function discoveredManifestPath(cwd: string): string | null {
+  for (const rel of [DISCOVERED_MANIFEST_PATH, LEGACY_DISCOVERED_MANIFEST_PATH]) {
+    const candidate = resolve(cwd, rel)
+    if (existsSync(candidate))
+      return candidate
+  }
+  return null
+}
+
+/**
+ * Pull the discovered-models manifest written by the dashboard dev server.
+ * Returns the default empty payload when neither path has one (fresh project
  * before the first dashboard run regenerates it).
  */
 export function loadDiscoveredManifest(
-  manifestPath = resolve(process.cwd(), 'storage/framework/runtime/dashboard/discovered-models.json'),
+  manifestPath = discoveredManifestPath(process.cwd()),
 ): DiscoveredManifest {
-  if (!existsSync(manifestPath))
+  if (manifestPath === null || !existsSync(manifestPath))
     return { models: [], sections: defaultToggles(), nav: [] }
 
   try {
@@ -682,10 +708,5 @@ export function buildWebSidebarSections(): WebSidebarSection[] {
         ...(item.roles && item.roles.length > 0 ? { roles: item.roles } : {}),
       })),
     })),
-    {
-      id: 'system',
-      label: '',
-      items: [{ id: 'settings', label: 'Settings', icon: NAV_ICON_CLASSES.settings, iconColor: 'blue', href: '/settings' }],
-    },
   ]
 }

package/resources/plugins/preloader.ts

@@ -171,8 +171,6 @@ if (!isRepl && !isPostinstall) {
 
   if (typeof applyRuntimeDirectoryEnv === 'function')
     applyRuntimeDirectoryEnv()
-  else
-    console.warn('[stacks] installed @stacksjs/path has no applyRuntimeDirectoryEnv; stx and ts-cloud will use their default state directories. Run `buddy upgrade` to refresh the framework packages.')
 
   // An app that does not vendor the framework defaults gets a gitignored
   // `storage/framework/defaults` link to the installed package. A fresh clone
@@ -181,6 +179,8 @@ if (!isRepl && !isPostinstall) {
   // published-version reason as the helper above.
   if (typeof linkPackagedDefaults === 'function')
     linkPackagedDefaults()
+  else
+    console.warn('[stacks] installed @stacksjs/path has no applyRuntimeDirectoryEnv; stx and ts-cloud will use their default state directories. Run `buddy upgrade` to refresh the framework packages.')
 }
 
 // stx template engine plugin
@@ -359,7 +359,7 @@ export async function loadAutoImports() {
   // Priority: user models (app/Models) override framework defaults
   const modelDirs = [
     path.userModelsPath(),
-    path.storagePath('framework/defaults/app/Models'),
+    path.defaultsPath('app/Models'),
   ]
 
   const loadedModels = new Set<string>()
@@ -430,7 +430,7 @@ export async function loadAutoImports() {
   // Priority: user controllers > default controllers
   const controllerDirs = [
     path.userControllersPath(),
-    path.storagePath('framework/defaults/app/Controllers'),
+    path.defaultsPath('app/Controllers'),
   ]
   const loadedControllers = new Set<string>()
 

package/scaffold/README.md

@@ -0,0 +1,36 @@
+# __APP_NAME__
+
+A [Stacks](https://stacksjs.com) application.
+
+## Getting started
+
+```bash
+./buddy dev
+```
+
+`./buddy doctor` checks your setup if anything does not start.
+
+## Everyday commands
+
+| Command | What it does |
+|---|---|
+| `./buddy dev` | Start the development servers |
+| `./buddy migrate` | Apply pending database migrations |
+| `./buddy test` | Run the test suite |
+| `./buddy typecheck` | Type check `app/`, `config/`, `resources/` and `routes/` |
+| `./buddy lint` | Lint, and `./buddy lint:fix` to fix what can be fixed |
+| `./buddy upgrade` | Move to the latest Stacks release |
+| `./buddy list` | Every other command |
+
+## Where things live
+
+- `app/`, `resources/`, `routes/`, `database/`: your application.
+- `config/`: every setting, one typed file per subsystem. System dependencies
+  are declared in `config/deps.ts`, and `deps.yaml` is generated from it.
+- `storage/framework/defaults`: the framework's default models, actions, views
+  and routes. It is a gitignored link to `node_modules/@stacksjs/defaults`, so
+  it upgrades with the `stacks` dependency. Override any default by creating the
+  same path under `app/` or `resources/`, or run `./buddy publish:defaults` to
+  commit a copy of the whole tree instead.
+
+Read more at [stacksjs.com/docs](https://stacksjs.com/docs).

package/scaffold/config/analytics.ts

@@ -0,0 +1,16 @@
+import type { AnalyticsConfig } from '@stacksjs/types'
+
+/**
+ * AnalyticsHQ is Stacks' first-party analytics driver. Paste the site id from
+ * your AnalyticsHQ app to enable it. An empty site id emits no tracking tags.
+ */
+export default {
+  driver: 'analyticshq',
+  environments: ['production', 'staging'],
+
+  drivers: {
+    analyticshq: {
+      siteId: '',
+    },
+  },
+} satisfies AnalyticsConfig

package/scaffold/config/app.ts

@@ -0,0 +1,49 @@
+import type { AppConfig } from '@stacksjs/types'
+import { env } from '@stacksjs/env'
+
+/**
+ * **Application Configuration**
+ *
+ * This configuration defines all of your application options. Because Stacks is fully-typed,
+ * you may hover any of the options below and the definitions will be provided. In case
+ * you have any questions, feel free to reach out via Discord or GitHub Discussions.
+ */
+export default {
+  name: env.APP_NAME ?? '__APP_NAME__',
+  // Shown on the starter page, the coming-soon page, and any page that sets
+  // no description of its own.
+  description: '',
+  env: env.APP_ENV ?? 'local',
+  url: env.APP_URL ?? 'stacks.localhost',
+  redirectUrls: [],
+  debug: env.DEBUG ?? false,
+  key: env.APP_KEY,
+
+  maintenanceMode: env.APP_MAINTENANCE ?? false,
+  comingSoonMode: env.APP_COMING_SOON ?? false,
+  comingSoonSecret: env.APP_COMING_SOON_SECRET ?? '',
+  // docMode: true, // instead of example.com/docs, deploys example.com as main entry point for docs
+  docMode: false,
+
+  timezone: 'America/Los_Angeles',
+  locale: 'en',
+  fallbackLocale: 'en',
+  cipher: 'aes-256-cbc',
+
+  // /sitemap.xml and /robots.txt are generated from resources/views, in dev
+  // and production alike. A page that says `noindex` (a robots meta tag, or
+  // `const noindex = true` in its server script) is left out, as are dynamic
+  // [param] routes, error pages and anything robots.txt disallows. A file you
+  // put in public/ wins over the generated one.
+  seo: {
+    sitemap: {
+      // Concrete URLs for dynamic routes, e.g. '/products/blue-mug'.
+      include: [],
+      exclude: [],
+    },
+    robots: {
+      // Added to the default '/api/'.
+      disallow: [],
+    },
+  },
+} satisfies AppConfig

package/scaffold/config/blog.ts

@@ -0,0 +1,79 @@
+import { env } from '@stacksjs/env'
+
+export interface BlogConfig {
+  subdomain: string
+  title: string
+  description: string
+  postsPerPage: number
+  /**
+   * NOT YET HONOURED by the static blog builder. Nothing reads this: the
+   * generated pages carry no comment section either way. The CMS has
+   * commenting (the `commentable` trait and `comments` in `@stacksjs/cms`),
+   * but the static build does not render it (stacksjs/stacks#365-adjacent;
+   * found auditing config keys nothing reads).
+   */
+  enableComments: boolean
+  /** Honoured: generates `feed.xml` and the RSS link in the layout. */
+  enableRss: boolean
+  /** Honoured: generates `sitemap.xml`. */
+  enableSitemap: boolean
+  /**
+   * NOT YET HONOURED by the static blog builder. Nothing reads this and no
+   * search index is generated.
+   */
+  enableSearch: boolean
+  /** Short title used in the blog layout nav; defaults to `title`. */
+  siteTitle?: string
+  /** Fallback post author when frontmatter has none. */
+  author?: string
+  /** Canonical site origin for feed/sitemap URLs when no request origin exists. */
+  url?: string
+  nav?: { text: string, link: string }[]
+  /** Which modes the blog theme toggle offers. */
+  themes?: ('colored' | 'light' | 'dark')[]
+  defaultTheme?: 'colored' | 'light' | 'dark'
+  /** Raw HTML for the blog footer colophon line. */
+  colophon?: string
+  social: {
+    twitter?: string
+    github?: string
+  }
+  theme: {
+    primaryColor: string
+    logo?: string
+  }
+}
+
+// The site origin feeds and the sitemap are written against. APP_URL is often
+// a bare host, which is not a URL on its own.
+const appUrl = String(env.APP_URL || '').replace(/\/+$/, '')
+const siteUrl = appUrl && !/^https?:\/\//.test(appUrl) ? `https://${appUrl}` : appUrl
+
+const config: BlogConfig = {
+  subdomain: 'blog',
+  title: `${env.APP_NAME || '__APP_NAME__'} Blog`,
+  description: '',
+  postsPerPage: 10,
+  // `enableComments` and `enableSearch` are declared but not yet implemented
+  // by the static blog builder - see the interface above. Left `true` so the
+  // value does not have to change when they are.
+  enableComments: true,
+  enableRss: true,
+  enableSitemap: true,
+  enableSearch: true,
+  author: env.APP_NAME || '__APP_NAME__',
+  ...(siteUrl && { url: siteUrl }),
+  nav: [
+    { text: 'Home', link: '/' },
+    { text: 'Blog', link: '/blog' },
+  ],
+  themes: ['colored', 'light', 'dark'],
+  defaultTheme: 'light',
+  colophon: '<a href="/blog/feed.xml">RSS</a>',
+  social: {},
+  theme: {
+    primaryColor: '#171717',
+  },
+}
+
+export default config

package/scaffold/config/buddy-bot.ts

@@ -0,0 +1,50 @@
+import type { BuddyConfig } from '@buddysh/buddy'
+
+/**
+ * buddy-bot is the one dependency bot a Stacks app runs.
+ *
+ * `.github/workflows/buddy-bot.yml` is what drives it: updates every two
+ * hours, a dashboard issue 15 minutes later, and a daily pass that closes pull
+ * requests whose bump already landed. Nothing else should be opening
+ * dependency pull requests here - two bots proposing the same bump is
+ * stacksjs/stacks#2574, and it costs a full CI matrix per duplicate.
+ */
+export default {
+  repository: {
+    provider: 'github',
+    // In Actions this is already the account or organization the repository
+    // lives under, which is the only place the workflow above runs. Replace the
+    // fallback if you also run buddy-bot locally.
+    owner: process.env.GITHUB_REPOSITORY_OWNER || 'your-github-owner',
+    name: '__APP_SLUG__',
+    // token: process.env.BUDDY_BOT_TOKEN,
+  },
+
+  dashboard: {
+    enabled: true,
+    title: 'Dependency Dashboard',
+  },
+
+  workflows: {
+    enabled: true,
+    outputDir: '.github/workflows',
+    templates: {
+      daily: true,
+      weekly: true,
+      monthly: true,
+    },
+    custom: [],
+  },
+
+  packages: {
+    strategy: 'all',
+    ignore: [
+      // Packages to hold back, e.g. '@types/node'
+    ],
+    ignorePaths: [
+      // Glob patterns to skip, e.g. 'apps/legacy/**'
+    ],
+  },
+
+  verbose: false,
+} satisfies BuddyConfig