npm - @stacksjs/defaults - Versions diffs - 0.74.31 → 0.74.33 - Mend

@stacksjs/defaults 0.74.31 → 0.74.33

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (22) hide show

package/ai/skills/stacks-analytics/SKILL.md +104 -26
package/ai/skills/stacks-auto-imports/SKILL.md +1 -1
package/ai/skills/stacks-orm/SKILL.md +1 -1
package/ai/skills/stacks-technical-diagrams/SKILL.md +1 -1
package/app/Actions/Auth/CreateReferralCodeAction.ts +13 -0
package/app/Actions/Auth/ReferralSummaryAction.ts +13 -0
package/app/Actions/Auth/RegisterAction.ts +2 -1
package/app/Actions/Dashboard/Content/FileDuplicateAction.ts +25 -0
package/app/Actions/Dashboard/Content/FileRenameAction.ts +25 -0
package/app/Actions/Dashboard/Content/FileVisibilityAction.ts +25 -0
package/app/Actions/Dashboard/Content/file-manager.test.ts +198 -0
package/app/Actions/Dashboard/Content/file-manager.ts +208 -1
package/app/Middleware/Can.ts +3 -1
package/app/Middleware/Permission.ts +3 -1
package/app/Middleware/Role.ts +3 -1
package/app/Models/Referral.ts +16 -0
package/app/Models/ReferralCode.ts +12 -0
package/ide/vscode/package.json +1 -1
package/package.json +2 -2
package/routes/auth.ts +2 -0
package/routes/dashboard-api.ts +3 -0
package/resources/assets/fonts/Monaco.ttf +0 -0

package/ai/skills/stacks-analytics/SKILL.md CHANGED Viewed

@@ -1,6 +1,6 @@
 ---
 name: stacks-analytics
-description: Use when adding analytics to a Stacks application - configuring Fathom or self-hosted analytics, generating tracking scripts, privacy-friendly analytics setup, or the analytics configuration. Covers @stacksjs/analytics and config/analytics.ts.
+description: Use when adding analytics to a Stacks application - configuring Fathom, Plausible, Google Analytics or self-hosted analytics, generating tracking scripts, privacy-friendly analytics setup, or the analytics configuration. Covers @stacksjs/analytics and config/analytics.ts.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob
@@ -8,24 +8,84 @@ allowed-tools: Read Edit Write Bash Grep Glob
 # Stacks Analytics
-Privacy-friendly analytics with Fathom and self-hosted driver support.
+Privacy-friendly analytics with four drivers: Fathom, Plausible, Google Analytics
+and self-hosted.
 ## Key Paths
 - Core package: `storage/framework/core/analytics/src/`
+- Drivers: `storage/framework/core/analytics/src/drivers/`
+- Registry (dispatch on the configured driver): `storage/framework/core/analytics/src/registry.ts`
 - Configuration: `config/analytics.ts`
+## Driver registry
+Read `config/analytics.ts` and render the driver it names. This is the entry
+point; reach for an individual driver only when you need one specific script
+regardless of config.
+```typescript
+import { generateAnalyticsScript, getAnalyticsHead } from '@stacksjs/analytics'
+import { analytics } from '@stacksjs/config'
+// HTML you can drop into a layout <head>
+const script = generateAnalyticsScript(analytics)
+// Or the [tag, attributes] pairs a docs `head` array takes
+const head = getAnalyticsHead(analytics)
+```
+The registry is loud on purpose. A `driver` value with no implementation throws,
+and so does a driver that is selected but missing its config (the message names
+the exact key to set). Only an app with no `driver` at all gets an empty result.
+Nothing injects the script for you - a framework that silently posted pageviews
+to a third party would be the wrong default. Render it yourself in the layout
+that should carry it.
 ## Drivers
-### Fathom Analytics
-Privacy-focused, GDPR-compliant analytics. Requires a Fathom account.
+### Fathom
+Hosted, cookie-free, GDPR-compliant. Requires a Fathom account.
+`scriptUrl` points the tag at your own origin so a content blocker does not drop it.
-### Self-Hosted Analytics
-Generate tracking scripts for self-hosted analytics:
+```typescript
+import { generateFathomScript } from '@stacksjs/analytics'
+generateFathomScript({
+  siteId: 'ABCDEFGH',
+  honorDnt: true,      // -> data-honor-dnt="true"
+  spa: true,           // -> data-spa="auto"
+  scriptUrl: undefined, // defaults to Fathom's CDN
+})
+```
+### Plausible
+Cookie-free, hosted or self-hosted. `hashMode` and `trackLocalhost` pick the
+script variant (`script.hash.js`, `script.local.js`); `scriptUrl` overrides the
+computed URL entirely, which is how you point at a self-hosted install.
 ```typescript
-import { generateSelfHostedScript, getSelfHostedAnalyticsHead, generateInlineScript } from '@stacksjs/analytics'
+import { generatePlausibleScript } from '@stacksjs/analytics'
+generatePlausibleScript({ domain: 'example.com', hashMode: true })
+```
+### Google Analytics
+GA4 via gtag.js. Emits the loader plus the inline `js` / `config` bootstrap;
+`debug: true` sets `debug_mode` so the property shows up in DebugView.
+```typescript
+import { generateGoogleAnalyticsScript } from '@stacksjs/analytics'
+generateGoogleAnalyticsScript({ trackingId: 'G-XXXXXXXXXX', debug: false })
+```
+### Self-Hosted
+A small first-party tracker that POSTs to your own endpoint.
+```typescript
+import { generateSelfHostedScript, getSelfHostedAnalyticsHead } from '@stacksjs/analytics'
-// Generate tracking script tag
 const script = generateSelfHostedScript({
   siteId: 'ABCDEF',
   apiEndpoint: 'https://analytics.myapp.com/api/event',
@@ -34,19 +94,34 @@ const script = generateSelfHostedScript({
   trackOutboundLinks: true       // track external link clicks
 })
-// Generate head configuration for STX
 const headConfig = getSelfHostedAnalyticsHead({
   siteId: 'ABCDEF',
   apiEndpoint: 'https://analytics.myapp.com/api/event'
 })
-// Generate inline script (no external JS file)
-const inline = generateInlineScript(config)
 ```
-## SelfHostedConfig Interface
+## Driver config interfaces
 ```typescript
+interface FathomConfig {
+  siteId: string                  // Fathom site ID
+  scriptUrl?: string              // serve the script first-party
+  honorDnt?: boolean              // respect Do Not Track
+  spa?: boolean                   // re-record pageviews on client routing
+}
+interface PlausibleConfig {
+  domain: string                  // the site's domain
+  scriptUrl?: string              // self-hosted Plausible or a proxy
+  trackLocalhost?: boolean        // keep localhost pageviews
+  hashMode?: boolean              // count hash routes
+}
+interface GoogleAnalyticsConfig {
+  trackingId: string              // GA4 measurement ID
+  debug?: boolean                 // debug_mode -> DebugView
+}
 interface SelfHostedConfig {
   siteId: string                  // unique site identifier
   apiEndpoint: string             // analytics API URL
@@ -60,18 +135,22 @@ interface SelfHostedConfig {
 ```typescript
 {
-  driver: 'fathom',              // 'fathom' | 'google-analytics'
+  driver: 'fathom',              // 'fathom' | 'plausible' | 'google-analytics' | 'self-hosted'
   drivers: {
-    googleAnalytics: {
-      trackingId: ''              // GA tracking ID
-    },
-    fathom: {
-      siteId: ''                  // Fathom site ID
-    }
+    googleAnalytics: { trackingId: '' },
+    fathom: { siteId: '' },
+    plausible: { domain: '' },
+    selfHosted: { siteId: '', apiEndpoint: '' },
   }
 }
 ```
+## First-party pageview capture
+Separate from the drivers, and no script at all: `capturePageviews: true` has the
+stx servers record page GETs into `analytics_events`, which is what feeds the
+native `/analytics/pages`, `/referrers` and `/devices` dashboards.
 ## Dashboard Integration
 Analytics dashboard at `/dashboard/analytics` displays:
@@ -81,11 +160,10 @@ Analytics dashboard at `/dashboard/analytics` displays:
 - Engagement metrics
 ## Gotchas
-- Default driver is `fathom` — privacy-focused by default
-- Self-hosted analytics require your own analytics endpoint
+- Selecting a driver does not inject anything - call `generateAnalyticsScript()` in your layout
+- A misconfigured driver throws rather than emitting nothing; the message names the config key
 - `honorDnt: true` respects browser Do Not Track settings
-- `escapeAttr()` is used internally to prevent XSS in generated scripts
-- Google Analytics tracking ID goes in config, not env (unless you override)
-- Analytics scripts are generated server-side and injected into page head
-- Fathom is a paid service — self-hosted is free but requires infrastructure
+- Attribute values are escaped, and inline script values are JS-escaped, to prevent XSS
+- Fathom is a paid service - self-hosted is free but requires infrastructure
 - `trackOutboundLinks` adds click handlers to external `<a>` tags
+- `capturePageviews` is server-side and independent of `driver`

package/ai/skills/stacks-auto-imports/SKILL.md CHANGED Viewed

@@ -66,7 +66,7 @@ globalThis.toggleDark = toggleDark
 - **Custom Functions**: From `resources/functions/` (counter, dark mode, GPX, geo utilities)
 ### Server Auto-Imports (100+)
-- **All ORM Models**: User, Post, Author, Product, Order, Payment, Customer, etc. (98 models)
+- **All ORM Models**: User, Post, Author, Product, Order, Payment, Customer, etc. (100 models)
 - **Request Models**: UserRequest, PostRequest, OrderRequest, etc.
 - **Actions**: Action types and helpers
 - **Schema**: validation schema builder

package/ai/skills/stacks-orm/SKILL.md CHANGED Viewed

@@ -11,7 +11,7 @@ allowed-tools: Read Edit Write Bash Grep Glob
 ## Key Paths
 - Core ORM package: `storage/framework/core/orm/src/`
 - ORM implementation: `storage/framework/orm/`
-- Model definitions: `storage/framework/defaults/app/Models/` (98 models)
+- Model definitions: `storage/framework/defaults/app/Models/` (100 models)
 - Application models: `app/Models/`
 - Default model templates: `storage/framework/defaults/app/Models/`
 - ORM type globals: `storage/framework/types/orm-globals.d.ts`

package/ai/skills/stacks-technical-diagrams/SKILL.md CHANGED Viewed

@@ -30,7 +30,7 @@ Run `bun --config=storage/framework/defaults/ai/skills/stacks-technical-diagrams
 1. Inspect the implementation before drawing. Treat `app/` as overrides and `storage/framework/defaults/app/` as fallbacks. Follow registrations in `app/Routes.ts`, route files, actions, jobs, listeners, middleware, models, config, resources, and framework entry points that matter to the requested view.
 2. Read the relevant Stacks domain skill before mapping an unfamiliar subsystem. Common companions include `stacks-router`, `stacks-actions`, `stacks-models`, `stacks-database`, `stacks-jobs`, `stacks-events`, `stacks-realtime`, and `stacks-cloud`.
 3. Draw one question per diagram. For a runtime overview, prefer browser or client -> stx/router -> action or service -> model/query -> database, then add only the external systems and trust boundaries needed for that story.
-4. Write output to the user's requested path. When no path is given, use `docs/diagrams/<descriptive-name>.html` and keep the source JSON beside it.
+4. Write output to the user's requested path. When no path is given, use `docs/public/diagrams/<descriptive-name>/index.html` and keep the source JSON beside it. That path matters: BunPress only renders `docs/**/*.md` and copies `docs/public/**`, so a diagram written anywhere else under `docs/` never reaches the built site. The directory-plus-`index.html` shape is what the deployed docs host serves at the clean URL `/docs/diagrams/<descriptive-name>` - a bare `<name>.html` is redirected to an extensionless path that does not exist. Link to it from a docs page as `/diagrams/<descriptive-name>` (BunPress adds the `/docs` base).
 If Bun cannot run, fall back to architecture mode: copy `assets/template.html`, hand-place SVG using the design system below, and run the self-review checklist before delivering.

package/app/Actions/Auth/CreateReferralCodeAction.ts ADDED Viewed

@@ -0,0 +1,13 @@
+import { Action } from '@stacksjs/actions'
+import { createReferralCode } from '@stacksjs/auth'
+import { response } from '@stacksjs/router'
+export default new Action({
+  name: 'CreateReferralCodeAction',
+  method: 'POST',
+  async handle(request: RequestInstance) {
+    const user = await request.user()
+    if (!user?.id) return response.error('Unauthenticated', 401)
+    return response.json({ code: await createReferralCode(Number(user.id)) })
+  },
+})

package/app/Actions/Auth/ReferralSummaryAction.ts ADDED Viewed

@@ -0,0 +1,13 @@
+import { Action } from '@stacksjs/actions'
+import { referralSummary } from '@stacksjs/auth'
+import { response } from '@stacksjs/router'
+export default new Action({
+  name: 'ReferralSummaryAction',
+  method: 'GET',
+  async handle(request: RequestInstance) {
+    const user = await request.user()
+    if (!user?.id) return response.error('Unauthenticated', 401)
+    return response.json(await referralSummary(Number(user.id)))
+  },
+})

package/app/Actions/Auth/RegisterAction.ts CHANGED Viewed

@@ -30,7 +30,8 @@ export default new Action({
     const password = request.get('password')
     const name = request.get('name')
-    const result = await register({ email, password, name })
+    const referralCode = request.get('referralCode')
+    const result = await register({ email, password, name, referralCode: typeof referralCode === 'string' ? referralCode : undefined })
     if (result) {
       const user = await Auth.getUserFromToken(result.token)

package/app/Actions/Dashboard/Content/FileDuplicateAction.ts ADDED Viewed

@@ -0,0 +1,25 @@
+import type { RequestInstance } from '@stacksjs/types'
+import { Action } from '@stacksjs/actions'
+import { response } from '@stacksjs/router'
+import { DashboardFileError, duplicateDashboardFile } from './file-manager'
+export default new Action({
+  name: 'FileDuplicateAction',
+  description: 'Copies a file or directory beside the original on a configured storage disk.',
+  method: 'POST',
+  async handle(request: RequestInstance) {
+    try {
+      const duplicated = await duplicateDashboardFile({
+        disk: String(request.get('disk', 'public')),
+        path: request.get('path'),
+        name: request.get('name'),
+      })
+      return response.json(duplicated)
+    }
+    catch (error) {
+      if (error instanceof DashboardFileError)
+        return response.json({ message: error.message, fields: error.fields }, error.status)
+      throw error
+    }
+  },
+})

package/app/Actions/Dashboard/Content/FileRenameAction.ts ADDED Viewed

@@ -0,0 +1,25 @@
+import type { RequestInstance } from '@stacksjs/types'
+import { Action } from '@stacksjs/actions'
+import { response } from '@stacksjs/router'
+import { DashboardFileError, renameDashboardFile } from './file-manager'
+export default new Action({
+  name: 'FileRenameAction',
+  description: 'Renames a file or directory in place on a configured storage disk.',
+  method: 'PATCH',
+  async handle(request: RequestInstance) {
+    try {
+      const renamed = await renameDashboardFile({
+        disk: String(request.get('disk', 'public')),
+        path: request.get('path'),
+        name: request.get('name'),
+      })
+      return response.json(renamed)
+    }
+    catch (error) {
+      if (error instanceof DashboardFileError)
+        return response.json({ message: error.message, fields: error.fields }, error.status)
+      throw error
+    }
+  },
+})

package/app/Actions/Dashboard/Content/FileVisibilityAction.ts ADDED Viewed

@@ -0,0 +1,25 @@
+import type { RequestInstance } from '@stacksjs/types'
+import { Action } from '@stacksjs/actions'
+import { response } from '@stacksjs/router'
+import { DashboardFileError, setDashboardFileVisibility } from './file-manager'
+export default new Action({
+  name: 'FileVisibilityAction',
+  description: 'Sets a file or directory public or private on a configured storage disk.',
+  method: 'PUT',
+  async handle(request: RequestInstance) {
+    try {
+      const updated = await setDashboardFileVisibility({
+        disk: String(request.get('disk', 'public')),
+        path: request.get('path'),
+        visibility: request.get('visibility'),
+      })
+      return response.json(updated)
+    }
+    catch (error) {
+      if (error instanceof DashboardFileError)
+        return response.json({ message: error.message, fields: error.fields }, error.status)
+      throw error
+    }
+  },
+})

package/app/Actions/Dashboard/Content/file-manager.test.ts CHANGED Viewed

@@ -6,10 +6,13 @@ import { StorageManager } from '@stacksjs/storage'
 import {
   createDashboardDirectory,
   deleteDashboardFile,
+  duplicateDashboardFile,
   getDashboardFileSnapshot,
   normalizeDashboardFileName,
   normalizeDashboardFileLimit,
   normalizeDashboardFilePath,
+  renameDashboardFile,
+  setDashboardFileVisibility,
   uploadDashboardFiles,
 } from './file-manager'
@@ -163,3 +166,198 @@ describe('dashboard file manager', () => {
     expect(() => normalizeDashboardFileName('nested/name')).toThrow('separators')
   })
 })
+describe('renameDashboardFile', () => {
+  test('renames a file and leaves nothing behind under the old name', async () => {
+    const disk = manager.disk('public')
+    await disk.write('documents/readme.txt', 'hello')
+    const result = await renameDashboardFile({ path: 'documents/readme.txt', name: 'guide.txt' }, manager)
+    expect(result).toEqual({ from: 'documents/readme.txt', to: 'documents/guide.txt', type: 'file', moved: 1 })
+    expect(await disk.fileExists('documents/guide.txt')).toBe(true)
+    expect(await disk.fileExists('documents/readme.txt')).toBe(false)
+    expect(await disk.readToString('documents/guide.txt')).toBe('hello')
+  })
+  test('renames at the top level, where there is no parent to keep', async () => {
+    const disk = manager.disk('public')
+    await disk.write('notes.txt', 'top level')
+    expect(await renameDashboardFile({ path: 'notes.txt', name: 'todo.txt' }, manager))
+      .toEqual({ from: 'notes.txt', to: 'todo.txt', type: 'file', moved: 1 })
+    expect(await disk.readToString('todo.txt')).toBe('top level')
+  })
+  /**
+   * The parent is kept deliberately. Renaming is changing the last segment;
+   * moving something elsewhere is a different gesture and would want its own
+   * endpoint, so a name is a name and never a path.
+   */
+  test('refuses a name that is really a path', async () => {
+    await manager.disk('public').write('a/b.txt', 'x')
+    await expect(renameDashboardFile({ path: 'a/b.txt', name: '../escaped.txt' }, manager))
+      .rejects.toMatchObject({ status: 422 })
+    await expect(renameDashboardFile({ path: 'a/b.txt', name: 'nested/deep.txt' }, manager))
+      .rejects.toMatchObject({ status: 422 })
+  })
+  test('renames a directory by moving what is inside it, at any depth', async () => {
+    const disk = manager.disk('public')
+    await disk.write('images/logo.png', 'a')
+    await disk.write('images/icons/favicon.png', 'b')
+    const result = await renameDashboardFile({ path: 'images', name: 'media' }, manager)
+    expect(result).toEqual({ from: 'images', to: 'media', type: 'directory', moved: 2 })
+    expect(await disk.readToString('media/logo.png')).toBe('a')
+    expect(await disk.readToString('media/icons/favicon.png')).toBe('b')
+    expect(await disk.fileExists('images/logo.png')).toBe(false)
+    expect(await disk.directoryExists('images')).toBe(false)
+  })
+  test('refuses to overwrite an existing name', async () => {
+    const disk = manager.disk('public')
+    await disk.write('documents/readme.txt', 'keep me')
+    await disk.write('documents/guide.txt', 'me too')
+    await expect(renameDashboardFile({ path: 'documents/readme.txt', name: 'guide.txt' }, manager))
+      .rejects.toMatchObject({ status: 409 })
+    // Neither side moved: a refused rename is not a partial one.
+    expect(await disk.readToString('documents/readme.txt')).toBe('keep me')
+    expect(await disk.readToString('documents/guide.txt')).toBe('me too')
+  })
+  test('says so rather than silently doing nothing when the name is unchanged', async () => {
+    await manager.disk('public').write('a.txt', 'x')
+    await expect(renameDashboardFile({ path: 'a.txt', name: 'a.txt' }, manager))
+      .rejects.toMatchObject({ status: 422 })
+  })
+  test('is a 404 when the item does not exist', async () => {
+    await expect(renameDashboardFile({ path: 'nope.txt', name: 'yes.txt' }, manager))
+      .rejects.toMatchObject({ status: 404 })
+  })
+})
+describe('setDashboardFileVisibility', () => {
+  test('flips a single file and reads back as the adapter sees it', async () => {
+    const disk = manager.disk('public')
+    await disk.write('documents/readme.txt', 'hello')
+    expect(await setDashboardFileVisibility({ path: 'documents/readme.txt', visibility: 'private' }, manager))
+      .toEqual({ path: 'documents/readme.txt', visibility: 'private', type: 'file', changed: 1 })
+    expect(await disk.visibility('documents/readme.txt')).toBe('private')
+    await setDashboardFileVisibility({ path: 'documents/readme.txt', visibility: 'public' }, manager)
+    expect(await disk.visibility('documents/readme.txt')).toBe('public')
+  })
+  /**
+   * A folder is applied file by file, not to the folder. Object storage has no
+   * directories to carry an ACL, and on a local disk a directory's mode gates
+   * listing rather than reading - the files are what gate access on both.
+   */
+  test('applies to every file beneath a folder, at any depth', async () => {
+    const disk = manager.disk('public')
+    await disk.write('images/logo.png', 'a')
+    await disk.write('images/icons/favicon.png', 'b')
+    expect(await setDashboardFileVisibility({ path: 'images', visibility: 'private' }, manager))
+      .toEqual({ path: 'images', visibility: 'private', type: 'directory', changed: 2 })
+    expect(await disk.visibility('images/logo.png')).toBe('private')
+    expect(await disk.visibility('images/icons/favicon.png')).toBe('private')
+  })
+  test('leaves files outside the folder alone', async () => {
+    const disk = manager.disk('public')
+    await disk.write('images/logo.png', 'a')
+    await disk.write('documents/readme.txt', 'b')
+    await setDashboardFileVisibility({ path: 'images', visibility: 'private' }, manager)
+    expect(await disk.visibility('documents/readme.txt')).toBe('public')
+  })
+  test('rejects anything that is not public or private', async () => {
+    await manager.disk('public').write('a.txt', 'x')
+    for (const visibility of ['world-readable', '', 'PUBLIC', true, undefined]) {
+      await expect(setDashboardFileVisibility({ path: 'a.txt', visibility }, manager))
+        .rejects.toMatchObject({ status: 422 })
+    }
+  })
+  test('is a 404 when the item does not exist', async () => {
+    await expect(setDashboardFileVisibility({ path: 'nope.txt', visibility: 'private' }, manager))
+      .rejects.toMatchObject({ status: 404 })
+  })
+})
+describe('duplicateDashboardFile', () => {
+  test('names the copy before the extension, not after it', async () => {
+    const disk = manager.disk('public')
+    await disk.write('documents/readme.txt', 'hello')
+    const result = await duplicateDashboardFile({ path: 'documents/readme.txt' }, manager)
+    // `readme.txt copy` is a file whose type the OS, the browser and this
+    // dashboard's own type grouping would all read as unknown.
+    expect(result).toEqual({ from: 'documents/readme.txt', to: 'documents/readme copy.txt', type: 'file', copied: 1 })
+    expect(await disk.readToString('documents/readme copy.txt')).toBe('hello')
+    expect(await disk.readToString('documents/readme.txt')).toBe('hello')
+  })
+  test('counts up rather than colliding when a copy already exists', async () => {
+    const disk = manager.disk('public')
+    await disk.write('a.txt', 'x')
+    expect((await duplicateDashboardFile({ path: 'a.txt' }, manager)).to).toBe('a copy.txt')
+    expect((await duplicateDashboardFile({ path: 'a.txt' }, manager)).to).toBe('a copy 2.txt')
+    expect((await duplicateDashboardFile({ path: 'a.txt' }, manager)).to).toBe('a copy 3.txt')
+  })
+  test('takes an explicit name when given one', async () => {
+    await manager.disk('public').write('a.txt', 'x')
+    expect((await duplicateDashboardFile({ path: 'a.txt', name: 'b.txt' }, manager)).to).toBe('b.txt')
+    await expect(duplicateDashboardFile({ path: 'a.txt', name: 'b.txt' }, manager))
+      .rejects.toMatchObject({ status: 409 })
+    await expect(duplicateDashboardFile({ path: 'a.txt', name: '../escaped.txt' }, manager))
+      .rejects.toMatchObject({ status: 422 })
+  })
+  test('copies a folder and everything under it, leaving the original whole', async () => {
+    const disk = manager.disk('public')
+    await disk.write('images/logo.png', 'a')
+    await disk.write('images/icons/favicon.png', 'b')
+    const result = await duplicateDashboardFile({ path: 'images' }, manager)
+    expect(result).toEqual({ from: 'images', to: 'images copy', type: 'directory', copied: 2 })
+    expect(await disk.readToString('images copy/logo.png')).toBe('a')
+    expect(await disk.readToString('images copy/icons/favicon.png')).toBe('b')
+    expect(await disk.readToString('images/logo.png')).toBe('a')
+  })
+  /**
+   * The copy lands beside the original under the same parent, so a deep listing
+   * taken while copying could see the files it is itself creating. Paths are
+   * collected first; this is what says so.
+   */
+  test('does not copy the copy it is making', async () => {
+    const disk = manager.disk('public')
+    await disk.write('media/one.txt', '1')
+    await disk.write('media/two.txt', '2')
+    expect((await duplicateDashboardFile({ path: 'media' }, manager)).copied).toBe(2)
+    expect(await disk.fileExists('media copy/media copy/one.txt')).toBe(false)
+  })
+  test('is a 404 when the item does not exist', async () => {
+    await expect(duplicateDashboardFile({ path: 'nope.txt' }, manager))
+      .rejects.toMatchObject({ status: 404 })
+  })
+})

package/app/Actions/Dashboard/Content/file-manager.ts CHANGED Viewed

@@ -1,7 +1,7 @@
 import type { ResponseStatus } from '@stacksjs/bun-router'
 import { statfs } from 'node:fs/promises'
 import { posix } from 'node:path'
-import type { StorageAdapter, StorageManager, UploadedFileLike } from '@stacksjs/storage'
+import type { StorageAdapter, StorageManager, UploadedFileLike, Visibility } from '@stacksjs/storage'
 import { Storage } from '@stacksjs/storage'
 const DEFAULT_DISK = 'public'
@@ -443,6 +443,213 @@ export async function deleteDashboardFile(
   throw new DashboardFileError(`Storage item "${path}" was not found.`, 404)
 }
+/**
+ * Rename a file or a folder in place.
+ *
+ * The parent stays put and only the last segment changes, which is what a
+ * rename in a file manager means - moving something elsewhere is a different
+ * gesture and would want a different endpoint.
+ *
+ * A directory is renamed by moving what is inside it rather than by moving the
+ * directory. On a local disk `moveFile` is `fs.rename` and would happily move a
+ * whole tree, but object storage has no directories at all: a folder there is a
+ * shared key prefix, and renaming it means rewriting the key of every object
+ * under it. Doing it the same way on both is the only version that is not
+ * quietly wrong on one of them.
+ *
+ * See stacksjs/stacks#245.
+ */
+export async function renameDashboardFile(
+  input: { disk?: string, path: unknown, name: unknown },
+  manager: Manager = Storage,
+): Promise<{ from: string, to: string, type: 'file' | 'directory', moved: number }> {
+  const selected = resolveDisk(manager, input.disk)
+  const from = normalizeDashboardFilePath(input.path)
+  const name = normalizeDashboardFileName(input.name)
+  const separator = from.lastIndexOf('/')
+  const parent = separator === -1 ? '' : from.slice(0, separator)
+  const to = [parent, name].filter(Boolean).join('/')
+  if (to === from)
+    throw new DashboardFileError('The new name matches the current one.', 422, { name: 'Choose a different name.' })
+  if (await selected.adapter.fileExists(to) || await selected.adapter.directoryExists(to))
+    throw new DashboardFileError(`An item named "${name}" already exists.`, 409, { name: 'Choose a different name.' })
+  if (await selected.adapter.fileExists(from)) {
+    await selected.adapter.moveFile(from, to)
+    return { from, to, type: 'file', moved: 1 }
+  }
+  if (!(await selected.adapter.directoryExists(from)))
+    throw new DashboardFileError(`Storage item "${from}" was not found.`, 404)
+  // Collected before anything moves. Mutating a tree while iterating it is how
+  // a rename half-completes and leaves files under both names.
+  const files: string[] = []
+  for await (const entry of selected.adapter.list(from, { deep: true })) {
+    const path = normalizeListedPath(String(entry.path))
+    if (entry.type === 'file' && path)
+      files.push(path)
+  }
+  for (const file of files) {
+    // `list` may answer absolute-from-root or relative-to-`from` paths
+    // depending on the adapter; both end with the part that has to be kept.
+    const relative = file.startsWith(`${from}/`) ? file.slice(from.length + 1) : file
+    await selected.adapter.moveFile(file.startsWith(`${from}/`) ? file : `${from}/${relative}`, `${to}/${relative}`)
+  }
+  // An empty source is what is left, and it should not be: a rename leaves one
+  // item, not two. Directories are implicit on object storage, so this is a
+  // no-op there rather than a failure.
+  await selected.adapter.deleteDirectory(from)
+  return { from, to, type: 'directory', moved: files.length }
+}
+/**
+ * Make a file, or everything in a folder, public or private.
+ *
+ * A folder is applied file by file rather than to the folder itself, for the
+ * same reason a rename is: object storage has no directories, only a shared key
+ * prefix, and an ACL belongs to an object. `directoryExists` there is a
+ * prefix-has-objects check with nothing at that key, so asking to change the
+ * "directory" would address something that does not exist.
+ *
+ * It is also the right answer on a local disk, where a mode on a directory
+ * controls listing and traversal but not whether a file inside it can be read.
+ * The files are what gate access on both, so the files are what this sets.
+ *
+ * See stacksjs/stacks#245.
+ */
+export async function setDashboardFileVisibility(
+  input: { disk?: string, path: unknown, visibility: unknown },
+  manager: Manager = Storage,
+): Promise<{ path: string, visibility: Visibility, type: 'file' | 'directory', changed: number }> {
+  const selected = resolveDisk(manager, input.disk)
+  const path = normalizeDashboardFilePath(input.path)
+  if (input.visibility !== 'public' && input.visibility !== 'private') {
+    throw new DashboardFileError('Visibility must be "public" or "private".', 422, {
+      visibility: 'Choose either public or private.',
+    })
+  }
+  const visibility = input.visibility as Visibility
+  if (await selected.adapter.fileExists(path)) {
+    await selected.adapter.changeVisibility(path, visibility)
+    return { path, visibility, type: 'file', changed: 1 }
+  }
+  if (!(await selected.adapter.directoryExists(path)))
+    throw new DashboardFileError(`Storage item "${path}" was not found.`, 404)
+  let changed = 0
+  for await (const entry of selected.adapter.list(path, { deep: true })) {
+    if (entry.type !== 'file')
+      continue
+    const listed = normalizeListedPath(String(entry.path))
+    if (!listed)
+      continue
+    await selected.adapter.changeVisibility(listed.startsWith(`${path}/`) ? listed : `${path}/${listed}`, visibility)
+    changed++
+  }
+  return { path, visibility, type: 'directory', changed }
+}
+/**
+ * The name a duplicate gets when the caller does not choose one.
+ *
+ * `readme.txt` becomes `readme copy.txt`, then `readme copy 2.txt` - the
+ * suffix goes before the extension, because `readme.txt copy` is a file whose
+ * type the operating system, the browser and this dashboard's own type
+ * grouping all read as unknown.
+ *
+ * A directory has no extension to preserve, and `posix.extname` returns `''`
+ * for one, so the same code handles both.
+ */
+async function availableCopyName(path: string, exists: (candidate: string) => Promise<boolean>): Promise<string> {
+  const base = posix.basename(path)
+  const extension = posix.extname(base)
+  const stem = extension ? base.slice(0, -extension.length) : base
+  const parent = path.slice(0, Math.max(0, path.length - base.length - 1))
+  for (let attempt = 1; attempt <= 100; attempt++) {
+    const suffix = attempt === 1 ? 'copy' : `copy ${attempt}`
+    const candidate = `${stem} ${suffix}${extension}`
+    const full = [parent, candidate].filter(Boolean).join('/')
+    if (!(await exists(full)))
+      return candidate
+  }
+  throw new DashboardFileError('Too many copies of this item already exist.', 409, {
+    name: 'Rename some copies, or choose a name.',
+  })
+}
+/**
+ * Copy a file, or a folder and everything in it, beside the original.
+ *
+ * Deep-walks a directory for the same reason rename and visibility do: object
+ * storage has no folder to copy, only a shared key prefix, so duplicating one
+ * means copying every object beneath it.
+ *
+ * The name is optional. A file manager's "Duplicate" is a single gesture that
+ * has to produce something, so an omitted name becomes `<name> copy`, then
+ * `<name> copy 2` - checked for availability rather than assumed, since the
+ * first copy is usually not the only one.
+ *
+ * See stacksjs/stacks#245.
+ */
+export async function duplicateDashboardFile(
+  input: { disk?: string, path: unknown, name?: unknown },
+  manager: Manager = Storage,
+): Promise<{ from: string, to: string, type: 'file' | 'directory', copied: number }> {
+  const selected = resolveDisk(manager, input.disk)
+  const from = normalizeDashboardFilePath(input.path)
+  const taken = async (candidate: string): Promise<boolean> =>
+    await selected.adapter.fileExists(candidate) || await selected.adapter.directoryExists(candidate)
+  const name = input.name === undefined || input.name === null || input.name === ''
+    ? await availableCopyName(from, taken)
+    : normalizeDashboardFileName(input.name)
+  const separator = from.lastIndexOf('/')
+  const parent = separator === -1 ? '' : from.slice(0, separator)
+  const to = [parent, name].filter(Boolean).join('/')
+  if (to === from)
+    throw new DashboardFileError('A copy needs a different name.', 422, { name: 'Choose a different name.' })
+  if (await taken(to))
+    throw new DashboardFileError(`An item named "${name}" already exists.`, 409, { name: 'Choose a different name.' })
+  if (await selected.adapter.fileExists(from)) {
+    await selected.adapter.copyFile(from, to)
+    return { from, to, type: 'file', copied: 1 }
+  }
+  if (!(await selected.adapter.directoryExists(from)))
+    throw new DashboardFileError(`Storage item "${from}" was not found.`, 404)
+  // Collected before anything is written, so a copy cannot pick up the files
+  // it is itself creating - `to` sits beside `from` under the same parent, and
+  // a deep listing that ran while copying could see them.
+  const files: string[] = []
+  for await (const entry of selected.adapter.list(from, { deep: true })) {
+    const listed = normalizeListedPath(String(entry.path))
+    if (entry.type === 'file' && listed)
+      files.push(listed.startsWith(`${from}/`) ? listed : `${from}/${listed}`)
+  }
+  for (const file of files)
+    await selected.adapter.copyFile(file, `${to}/${file.slice(from.length + 1)}`)
+  return { from, to, type: 'directory', copied: files.length }
+}
 export async function uploadDashboardFiles(
   input: { disk?: string, path?: string, files: UploadedFileLike[] },
   manager: Manager = Storage,

package/app/Middleware/Can.ts CHANGED Viewed

@@ -3,6 +3,8 @@ import { authenticatedUser } from '@stacksjs/auth/middleware'
 import { HttpError } from '@stacksjs/error-handling'
 import { Middleware, resolveRouteModel, setRouteModelFallback } from '@stacksjs/router'
+let ormModule: typeof import('@stacksjs/orm') | undefined
 /**
  * Convention binding: parameter `site` resolves through the `Site` model
  * (stacksjs/stacks#2231).
@@ -24,7 +26,7 @@ setRouteModelFallback(async (value, { param }) => {
   // touched: lowercasing the rest would turn `blogPost` into `Blogpost`.
   const modelName = param.charAt(0).toUpperCase() + param.slice(1)
-  const orm = await import('@stacksjs/orm') as Record<string, any>
+  const orm = (ormModule ??= await import('@stacksjs/orm')) as Record<string, any>
   const model = orm[modelName]
   // No model of that name — decline, so the raw string passes through exactly

package/app/Middleware/Permission.ts CHANGED Viewed

@@ -2,6 +2,8 @@ import { authenticatedUser } from '@stacksjs/auth/middleware'
 import { HttpError } from '@stacksjs/error-handling'
 import { Middleware } from '@stacksjs/router'
+let rbacModule: typeof import('@stacksjs/auth/rbac') | undefined
 /**
  * Permission Middleware
  *
@@ -32,7 +34,7 @@ export default new Middleware({
       throw new HttpError(401, 'Unauthenticated.')
     }
-    const { hasAnyPermission } = await import('@stacksjs/auth/rbac')
+    const { hasAnyPermission } = rbacModule ??= await import('@stacksjs/auth/rbac')
     const hasRequired = await hasAnyPermission(user, requiredPermissions)

package/app/Middleware/Role.ts CHANGED Viewed

@@ -2,6 +2,8 @@ import { authenticatedUser } from '@stacksjs/auth/middleware'
 import { HttpError } from '@stacksjs/error-handling'
 import { Middleware } from '@stacksjs/router'
+let rbacModule: typeof import('@stacksjs/auth/rbac') | undefined
 /**
  * Role Middleware
  *
@@ -32,7 +34,7 @@ export default new Middleware({
     }
     // Dynamically import to avoid circular dependency
-    const { hasAnyRole } = await import('@stacksjs/auth/rbac')
+    const { hasAnyRole } = rbacModule ??= await import('@stacksjs/auth/rbac')
     const hasRequired = await hasAnyRole(user, requiredRoles)

package/app/Models/Referral.ts ADDED Viewed

@@ -0,0 +1,16 @@
+import { defineModel } from '@stacksjs/orm'
+import { schema } from '@stacksjs/validation'
+export default defineModel({
+  name: 'Referral',
+  table: 'referrals',
+  traits: { useTimestamps: true },
+  indexes: [{ name: 'referrals_referrer_status', columns: ['referrer_id', 'status'] }],
+  attributes: {
+    referrerId: { required: true, validation: { rule: schema.number().integer().min(1) } },
+    referredUserId: { required: true, unique: true, validation: { rule: schema.number().integer().min(1) } },
+    code: { required: true, validation: { rule: schema.string().max(24) } },
+    status: { required: true, default: 'registered', validation: { rule: schema.enum(['registered', 'qualified']) } },
+    qualifiedAt: { nullable: true, validation: { rule: schema.date() } },
+  },
+} as const)

package/app/Models/ReferralCode.ts ADDED Viewed

@@ -0,0 +1,12 @@
+import { defineModel } from '@stacksjs/orm'
+import { schema } from '@stacksjs/validation'
+export default defineModel({
+  name: 'ReferralCode',
+  table: 'referral_codes',
+  traits: { useTimestamps: true },
+  attributes: {
+    userId: { required: true, unique: true, validation: { rule: schema.number().integer().min(1) } },
+    code: { required: true, unique: true, validation: { rule: schema.string().max(24) } },
+  },
+} as const)

package/ide/vscode/package.json CHANGED Viewed

@@ -2,7 +2,7 @@
   "publisher": "Stacks",
   "name": "vscode-stacks",
   "displayName": "Stacks",
-  "version": "0.74.31",
+  "version": "0.74.33",
   "description": "A modern Stacks development environment.",
   "license": "MIT",
   "funding": "https://github.com/sponsors/chrisbbreuer",

package/package.json CHANGED Viewed

@@ -2,7 +2,7 @@
   "name": "@stacksjs/defaults",
   "type": "module",
   "sideEffects": false,
-  "version": "0.74.31",
+  "version": "0.74.33",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/stacksjs/stacks.git",
@@ -55,7 +55,7 @@
   "dependencies": {
     "@iconify-json/f7": "^1.2.2",
     "@iconify-json/hugeicons": "^1.2.27",
-    "@stacksjs/mobile": "^0.74.31",
+    "@stacksjs/mobile": "^0.74.33",
     "@stacksjs/sanitizer": "^0.2.113",
     "ts-qr-codes": "^0.1.8"
   }

package/routes/auth.ts CHANGED Viewed

@@ -74,6 +74,8 @@ route.group({ prefix: '/auth' }, () => {
 })
 route.group({ middleware: 'auth' }, () => {
+  route.get('/referrals', 'Actions/Auth/ReferralSummaryAction').rateLimit(60, 'minute')
+  route.post('/referrals/code', 'Actions/Auth/CreateReferralCodeAction').rateLimit(10, 'minute')
   route.get('/me', 'Actions/Auth/AuthUserAction')
   route.post('/logout', 'Actions/Auth/LogoutAction')
   // Sign out everywhere: revoke every access/refresh token AND destroy

package/routes/dashboard-api.ts CHANGED Viewed

@@ -245,6 +245,9 @@ route.group({ prefix: '/api/dashboard', apiResponse: true }, () => {
   guard(route.get('/files', 'Actions/Dashboard/Content/FileIndexAction'))
   guard(route.post('/files/directories', 'Actions/Dashboard/Content/FileDirectoryStoreAction'))
   guard(route.post('/files/uploads', 'Actions/Dashboard/Content/FileUploadAction'))
+  guard(route.patch('/files', 'Actions/Dashboard/Content/FileRenameAction'))
+  guard(route.put('/files/visibility', 'Actions/Dashboard/Content/FileVisibilityAction'))
+  guard(route.post('/files/duplicates', 'Actions/Dashboard/Content/FileDuplicateAction'))
   guard(route.delete('/files', 'Actions/Dashboard/Content/FileDestroyAction'))
   guard(route.get('/ci/status', 'Actions/Dashboard/Ci/StatusAction'))

package/resources/assets/fonts/Monaco.ttf DELETED Viewed

Binary file