@stacksjs/defaults 0.75.254 → 0.75.256

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 {

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

package/scaffold/config/cloud.ts

@@ -0,0 +1,103 @@
+import type { CloudConfig } from '@stacksjs/types'
+import type { CloudConfig as TsCloudConfig } from '@stacksjs/ts-cloud'
+import { env } from '@stacksjs/env'
+
+const APP_SLUG = '__APP_SLUG__'
+const APP_DOMAIN = env.APP_DOMAIN || undefined
+
+/**
+ * Safe application cloud defaults.
+ *
+ * Set APP_DOMAIN and provider credentials before the first deploy. Use
+ * `cloud.attachTo` only when this app is intentionally joining a server owned
+ * by another ts-cloud project.
+ */
+export const tsCloud: TsCloudConfig = {
+  project: {
+    name: APP_SLUG,
+    slug: APP_SLUG,
+    region: 'us-east-1',
+  },
+
+  stateDir: 'storage/cloud',
+
+  // Deploy to Hetzner Cloud, or set `provider: 'ssh'` to deploy to a Linux box
+  // you already own over SSH (a Raspberry Pi, a NUC, an old laptop):
+  //
+  //   cloud: { provider: 'ssh' },
+  //   ssh: { profile: 'raspberry-pi', hosts: [{ host: 'pi-stacks.local', user: 'pi' }] },
+  //
+  // See `buddy server:flash`, `server:first-boot`, `server:doctor` and
+  // `server:setup` for getting a fresh board to that point.
+  cloud: {
+    provider: 'hetzner',
+  },
+
+  mode: 'server',
+
+  environments: {
+    production: {
+      type: 'production',
+      deployBranch: 'main',
+      region: 'us-east-1',
+      variables: {
+        APP_ENV: 'production',
+        NODE_ENV: 'production',
+        LOG_LEVEL: 'info',
+      },
+    },
+  },
+
+  infrastructure: {
+    compute: {
+      instances: 1,
+      size: 'small',
+      disk: {
+        size: 20,
+        type: 'ssd',
+        encrypted: true,
+      },
+      webServer: 'rpx',
+      proxy: {
+        engine: 'rpx',
+        onDemandTls: true,
+      },
+    },
+  },
+
+  sites: {
+    main: {
+      root: '.',
+      path: '/',
+      domain: APP_DOMAIN,
+      start: 'bun node_modules/@stacksjs/buddy/dist/serve-entry.js',
+      port: 3000,
+      preStart: [
+        'bun install --frozen-lockfile',
+        'bun node_modules/@stacksjs/buddy/dist/cli.js migrate',
+      ],
+      env: {
+        APP_ENV: 'production',
+        NODE_ENV: 'production',
+        PORT_API: '3008',
+        API_URL: 'http://127.0.0.1:3008',
+      },
+    },
+
+    api: {
+      root: '.',
+      start: 'bun node_modules/@stacksjs/actions/dist/serve/api.js',
+      port: 3008,
+      preStart: ['bun install --frozen-lockfile'],
+      env: {
+        HOST: '127.0.0.1',
+        APP_ENV: 'production',
+        NODE_ENV: 'production',
+      },
+    },
+  },
+}
+
+const config: CloudConfig = {}
+
+export default config

package/scaffold/config/dns.ts

@@ -0,0 +1,16 @@
+import type { DnsConfig } from '@stacksjs/types'
+
+/**
+ * Additional DNS records owned by this application.
+ *
+ * Server records are derived from config/cloud.ts during deployment. Add
+ * provider and zone details there before asking Buddy to reconcile DNS.
+ */
+export default {
+  a: [],
+  aaaa: [],
+  cname: [],
+  mx: [],
+  txt: [],
+  nameservers: [],
+} satisfies DnsConfig

package/scaffold/config/docs.ts

@@ -0,0 +1,57 @@
+import type { BunPressOptions } from '@stacksjs/bunpress'
+import { env } from '@stacksjs/env'
+
+/**
+ * **Documentation Configuration**
+ *
+ * Your app's documentation site, built with BunPress from `docs/`. There is no
+ * `docs/` until you create one: add `docs/index.md` and `buddy dev` serves it
+ * at /docs, and `buddy deploy` builds it.
+ */
+
+// 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: BunPressOptions = {
+  verbose: false,
+  docsDir: './docs',
+  outDir: './dist/docs',
+
+  nav: [],
+
+  markdown: {
+    title: `${env.APP_NAME || '__APP_NAME__'} Documentation`,
+    meta: {
+      description: '',
+      author: env.APP_NAME || '__APP_NAME__',
+    },
+    syntaxHighlightTheme: 'github-dark',
+    toc: {
+      enabled: true,
+      minDepth: 2,
+      maxDepth: 3,
+    },
+    sidebar: {
+      '/': [
+        {
+          text: 'Getting Started',
+          items: [
+            { text: 'Introduction', link: '/' },
+          ],
+        },
+      ],
+    },
+  },
+
+  sitemap: {
+    enabled: Boolean(siteUrl),
+    baseUrl: siteUrl ? `${siteUrl}/docs` : '',
+  },
+
+  robots: {
+    enabled: true,
+  },
+}
+
+export default config

package/scaffold/config/email.ts

@@ -0,0 +1,27 @@
+import type { EmailConfig } from '@stacksjs/types'
+import { env } from '@stacksjs/env'
+
+export default {
+  from: {
+    name: env.MAIL_FROM_NAME || '__APP_NAME__',
+    address: env.MAIL_FROM_ADDRESS || 'hello@example.com',
+  },
+
+  domain: env.MAIL_DOMAIN || env.APP_DOMAIN || 'example.com',
+  mailboxes: [],
+  forwards: {},
+  url: env.APP_URL || '__APP_SLUG__.localhost',
+  charset: 'UTF-8',
+
+  server: {
+    // Explicit opt-in: a generated application must never reconcile the
+    // framework repository's shared mail server or mailboxes.
+    enabled: false,
+    scan: true,
+    subdomain: 'mail',
+    // Gmail Postmaster Tools shows how Gmail receives your mail. Add your
+    // domain at https://postmaster.google.com, paste the TXT value it shows,
+    // and every deploy keeps it published.
+    // postmaster: { google: 'google-site-verification=...' },
+  },
+} satisfies EmailConfig

package/scaffold/config/library.ts

@@ -0,0 +1,64 @@
+import type { LibraryConfig } from '@stacksjs/types'
+
+/**
+ * **Library Configuration**
+ *
+ * This configuration defines all of your library 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: '__APP_SLUG__',
+  // The npm scope your packages publish under, e.g. 'your-org'. Set it before
+  // `buddy libs:publish`; the @ prefix is added automatically.
+  owner: null,
+  // `owner/name` on GitHub; fills in each package's repository, homepage and bugs links.
+  repository: '',
+  license: 'MIT',
+  author: '',
+  contributors: [],
+  defaultLanguage: 'en',
+  releaseable: true,
+
+  /**
+   * One `resources/` tree, any number of npm packages.
+   *
+   * Each entry claims a slice of `resources/functions` or `resources/components`
+   * by glob and becomes its own package: its own name, manifest, dist and
+   * version. Slices may overlap, so a component can ship in a bundle package
+   * and in a focused one. `buddy libs` prints what each package resolved to,
+   * `buddy build:libs` builds them all, `buddy libs:publish` publishes them.
+   */
+  packages: [
+    {
+      name: '__APP_SLUG__-fx',
+      kind: 'functions',
+      description: 'Your function library description.',
+      keywords: ['functions', 'composables', 'library', 'typescript', 'javascript'],
+      include: ['*.ts'],
+      // These composables call stx's ambient globals (`state`, `useDark`),
+      // which no module exports. Saying so here is what lets them ship: the
+      // build otherwise refuses them, because a consumer importing the
+      // published package would hit `ReferenceError: state is not defined`.
+      runtime: 'stx',
+    },
+
+    {
+      name: '__APP_SLUG__-components',
+      kind: 'components',
+      description: 'Your STX component library, as tree-shakeable modules.',
+      keywords: ['components', 'custom-elements', 'stx', 'library', 'typescript'],
+      prefix: '__APP_TAG_PREFIX__',
+      include: ['*.stx'],
+    },
+
+    {
+      name: '__APP_SLUG__-elements',
+      kind: 'web-components',
+      description: 'Your framework agnostic web component library description.',
+      keywords: ['custom-elements', 'web-components', 'library', 'framework-agnostic', 'typescript', 'javascript'],
+      prefix: '__APP_TAG_PREFIX__',
+      include: ['*.stx'],
+    },
+  ],
+} satisfies LibraryConfig

package/scaffold/config/lint.ts

@@ -0,0 +1,42 @@
+import type { LintConfig } from '@stacksjs/types'
+
+/**
+ * Lint configuration.
+ *
+ * Code style lives in `config/code-style.ts` (pickier's own options). This file
+ * holds the checks Stacks runs on top of it - today, the stx conformance
+ * checks behind `buddy lint --stx`.
+ *
+ * The baselines are a ratchet. A number is a DEBT, not a target: going above
+ * one fails, and dropping below one is reported too, so a cleared violation has
+ * to be recorded rather than quietly banked. Every non-zero entry names what
+ * clears it.
+ */
+const config: LintConfig = {
+  stx: {
+    baselines: {
+      'comment-landmine': 0,
+      'dist-component-error': 0,
+      'dist-layout-published': 0,
+      'dist-path-leak': 0,
+      'script-tag-balance': 0,
+      'strict-lint': 0,
+      'unmanaged-timer': 0,
+      'style-block': 0,
+      'dom-guard': 0,
+      'inline-style-attr': 0,
+      'plain-internal-anchor': 0,
+
+      // config/ui.ts sets neither `strict` nor `pagesDir`. Pinning pagesDir
+      // changes how stx resolves topology, so it wants its own dev+build pass
+      // rather than being swept in with a lint change.
+      'stx-config-keys': 2,
+
+      // resources/emails/order-confirmation.stx is a whole email document, so
+      // it owns its DOCTYPE.
+      'doctype-no-nolayout': 1,
+    },
+  },
+}
+
+export default config

package/scaffold/config/mobile.ts

@@ -0,0 +1,27 @@
+import type { MobileConfig } from '@stacksjs/types'
+import { env } from '@stacksjs/env'
+
+export default {
+  ios: {
+    appName: env.APP_NAME ?? '__APP_NAME__',
+    // A placeholder the App Store rejects on purpose: replace it with your own
+    // reverse-DNS id before the first build you mean to ship.
+    bundleId: '__APP_BUNDLE_ID__',
+    version: '1.0.0',
+    buildNumber: '1',
+    deploymentTarget: '16.0',
+    url: env.APP_URL,
+    darkMode: true,
+    backgroundColor: '#0a0a0a',
+    orientations: ['portrait'],
+    capabilities: {
+      haptics: true,
+      share: true,
+      secureStorage: true,
+      clipboard: true,
+      localDatabase: true,
+      screenCapture: true,
+      pdfViewer: true,
+    },
+  },
+} satisfies MobileConfig

package/scaffold/config/team.ts

@@ -0,0 +1,6 @@
+import type { Team } from '@stacksjs/types'
+
+export default {
+  name: '__APP_NAME__',
+  members: {},
+} satisfies Team