@stacksjs/defaults 0.70.206 → 0.70.208

package/package.json

@@ -2,15 +2,31 @@
   "name": "@stacksjs/defaults",
   "type": "module",
   "sideEffects": false,
-  "version": "0.70.206",
-  "description": "Default Stacks scaffold resources (views, layouts, components, preloader) — shipped so apps consuming the framework from node_modules get the same fallback resources a vendored checkout provides. Source of truth: storage/framework/defaults.",
+  "version": "0.70.208",
+  "description": "The complete managed Stacks application scaffold, including runtime defaults, AI guidance, editor metadata, and npm-backed project support files.",
   "author": "Chris Breuer",
   "license": "MIT",
   "homepage": "https://github.com/stacksjs/stacks/tree/main/storage/framework/defaults",
   "files": [
     "README.md",
+    "TODO.md",
+    "ai",
     "resources",
-    "app"
+    "app",
+    "assets",
+    "docs",
+    "functions",
+    "ide",
+    "lang",
+    "routes",
+    "stores",
+    "styles",
+    "types",
+    "vcs",
+    "views",
+    "bootstrap.ts",
+    "stx-components-plugin.ts",
+    "project"
   ],
   "exports": {
     "./*": "./*",

package/project/bootstrap

@@ -0,0 +1,161 @@
+#!/bin/sh
+set -eu
+
+## To learn more, visit https://stacksjs.com/docs/guide/bootstrap
+## Usage:
+##   ./bootstrap
+##   curl -fsSL https://stacksjs.com/install | sh
+##   curl -fsSL https://stacksjs.com/install | sh -s -- my-project
+
+ASSUME_YES=0
+PROJECT_NAME=""
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    -y|--yes) ASSUME_YES=1 ;;
+    -h|--help)
+      echo "Usage: ./bootstrap [--yes] [project-name]"
+      exit 0
+      ;;
+    -*)
+      echo "Unknown option: $1"
+      exit 1
+      ;;
+    *)
+      if [ -n "$PROJECT_NAME" ]; then
+        echo "Only one project name may be supplied."
+        exit 1
+      fi
+      PROJECT_NAME="$1"
+      ;;
+  esac
+  shift
+done
+
+TEMP_DIR=""
+cleanup() {
+  if [ -n "$TEMP_DIR" ] && [ -d "$TEMP_DIR" ]; then
+    rm -rf "$TEMP_DIR"
+  fi
+}
+trap cleanup EXIT INT TERM
+
+confirm_install() {
+  if [ "$ASSUME_YES" -eq 1 ]; then
+    return 0
+  fi
+
+  if [ ! -r /dev/tty ]; then
+    echo "Pantry is required to provision Bun and the local toolchain."
+    echo "Run again with --yes to approve its installation."
+    return 1
+  fi
+
+  printf "Pantry will install Bun and the local development toolchain. Continue? [Y/n] " > /dev/tty
+  IFS= read -r answer < /dev/tty || answer=""
+  case "$answer" in
+    ""|y|Y|yes|YES|Yes) return 0 ;;
+    *) echo "Installation cancelled."; return 1 ;;
+  esac
+}
+
+# --- Pantry installer (inlined so it works via curl-pipe-bash before clone) ---
+ensure_pantry() {
+  if command -v pantry >/dev/null 2>&1; then
+    return
+  fi
+
+  confirm_install || exit 1
+
+  OS=$(uname -s | tr '[:upper:]' '[:lower:]')
+  ARCH=$(uname -m)
+  case "$ARCH" in
+    x86_64|amd64) ARCH="x64" ;;
+    arm64|aarch64) ARCH="arm64" ;;
+  esac
+
+  INSTALL_DIR="${HOME}/.local/bin"
+  mkdir -p "$INSTALL_DIR"
+
+  ZIP="pantry-${OS}-${ARCH}.zip"
+  URL="https://github.com/home-lang/pantry/releases/latest/download/${ZIP}"
+
+  echo "Downloading Pantry from ${URL}..."
+  TEMP_DIR=$(mktemp -d)
+  curl -fsSL -o "${TEMP_DIR}/${ZIP}" "$URL"
+  unzip -oq "${TEMP_DIR}/${ZIP}" -d "$INSTALL_DIR"
+  chmod +x "${INSTALL_DIR}/pantry"
+  rm -rf "$TEMP_DIR"
+  TEMP_DIR=""
+
+  export PATH="${INSTALL_DIR}:${PATH}"
+  echo "Pantry installed to ${INSTALL_DIR}/pantry"
+}
+
+# --- Main ---
+
+# If we are outside a project, create one from the latest stable release.
+if [ ! -d "storage/framework/core" ]; then
+  if [ -z "$PROJECT_NAME" ]; then
+    PROJECT_NAME="${STACKS_PROJECT:-stacks}"
+
+    if [ -r /dev/tty ]; then
+      printf "Project directory [%s]: " "$PROJECT_NAME" > /dev/tty
+      IFS= read -r requested_name < /dev/tty || requested_name=""
+      if [ -n "$requested_name" ]; then
+        PROJECT_NAME="$requested_name"
+      fi
+    fi
+  fi
+
+  if [ -e "$PROJECT_NAME" ]; then
+    echo "Path '$PROJECT_NAME' already exists. Please use a different name."
+    exit 1
+  fi
+
+  RELEASE_TAG="${STACKS_VERSION:-}"
+  if [ -z "$RELEASE_TAG" ]; then
+    RELEASE_URL=$(curl -fsSL -o /dev/null -w '%{url_effective}' "https://github.com/stacksjs/stacks/releases/latest")
+    RELEASE_TAG=${RELEASE_URL##*/}
+  fi
+
+  case "$RELEASE_TAG" in
+    v*) ;;
+    *) RELEASE_TAG="v${RELEASE_TAG}" ;;
+  esac
+
+  echo "Downloading Stacks ${RELEASE_TAG}..."
+  TEMP_DIR=$(mktemp -d)
+  curl -fsSL -o "${TEMP_DIR}/stacks.zip" "https://github.com/stacksjs/stacks/archive/refs/tags/${RELEASE_TAG}.zip"
+  unzip -q "${TEMP_DIR}/stacks.zip" -d "$TEMP_DIR"
+  ARCHIVE_DIR="${TEMP_DIR}/stacks-${RELEASE_TAG#v}"
+
+  if [ ! -d "$ARCHIVE_DIR" ]; then
+    echo "The Stacks release archive had an unexpected layout."
+    exit 1
+  fi
+
+  mv "$ARCHIVE_DIR" "$PROJECT_NAME"
+  rm -rf "$TEMP_DIR"
+  TEMP_DIR=""
+  cd "$PROJECT_NAME"
+fi
+
+# Detect if we're in a Stacks project
+if [ ! -d "storage/framework/core" ]; then
+  echo "Error: not inside a Stacks project."
+  exit 1
+fi
+
+PROJECT_ROOT=$(pwd)
+
+ensure_pantry
+
+echo "Bootstrapping Stacks project..."
+"${PROJECT_ROOT}/buddy" setup --skip-aws
+
+echo ""
+echo "Project bootstrapped successfully!"
+if [ -n "$PROJECT_NAME" ]; then
+  echo "Run 'cd $PROJECT_NAME && ./buddy dev' to start the dev server."
+fi

package/project/buddy

@@ -0,0 +1,175 @@
+#!/bin/sh
+set -e
+
+ROOT_DIR=$(CDPATH= cd -- "$(dirname "$0")" && pwd)
+PANTRY_LOCAL_BIN="${ROOT_DIR}/pantry/.bin"
+PANTRY_DIR="${ROOT_DIR}/pantry"
+USER_LOCAL_BIN="${HOME}/.local/bin"
+PANTRY_INSTALLER="${ROOT_DIR}/storage/framework/scripts/pantry-install"
+PANTRY_SETUP_DONE="${PANTRY_DIR}/.postsetup-done"
+PANTRY_BOOTSTRAP_TIMEOUT_SECONDS="${PANTRY_BOOTSTRAP_TIMEOUT_SECONDS:-600}"
+PANTRY_DEPENDENCIES_TIMEOUT_SECONDS="${PANTRY_DEPENDENCIES_TIMEOUT_SECONDS:-1200}"
+
+# Resolve which CLI entrypoint to invoke. Resolution order matches the
+# action-runner fallback chain in `@stacksjs/actions`:
+#
+#   1. `storage/framework/core/buddy/src/cli.ts`  — userland override (legacy
+#      "framework lives in the project" layout). Kept FIRST so projects that
+#      have published buddy via `buddy publish:core buddy` still win.
+#   2. `node_modules/@stacksjs/buddy/src/cli.ts`  — installed package, TS source
+#      (workspace symlink or a real npm install with `src/` shipped).
+#   3. `node_modules/@stacksjs/buddy/dist/cli.js` — published JS-only build.
+#
+# If none of these are present the script bails with a clear message instead
+# of `bun` exploding on a missing file.
+resolve_buddy_entry() {
+  for candidate in \
+    "${ROOT_DIR}/storage/framework/core/buddy/src/cli.ts" \
+    "${ROOT_DIR}/node_modules/@stacksjs/buddy/src/cli.ts" \
+    "${ROOT_DIR}/node_modules/@stacksjs/buddy/dist/cli.js" \
+  ; do
+    if [ -f "${candidate}" ]; then
+      echo "${candidate}"
+      return 0
+    fi
+  done
+  return 1
+}
+
+if ! BUDDY_ENTRY=$(resolve_buddy_entry); then
+  echo "buddy: could not locate CLI entrypoint." >&2
+  echo "  Tried: storage/framework/core/buddy/src/cli.ts, node_modules/@stacksjs/buddy/{src/cli.ts,dist/cli.js}." >&2
+  echo "  Run \`bun install\` or \`buddy publish:core buddy\` to make the CLI available." >&2
+  exit 1
+fi
+
+run_with_timeout() {
+  timeout_seconds="$1"
+  shift
+  timeout_flag="${TMPDIR:-/tmp}/buddy-timeout-$$"
+  rm -f "${timeout_flag}"
+
+  "$@" &
+  cmd_pid=$!
+
+  (
+    sleep "${timeout_seconds}"
+
+    if kill -0 "${cmd_pid}" 2>/dev/null; then
+      echo "Command timed out after ${timeout_seconds}s: $*" >&2
+      : > "${timeout_flag}"
+      kill "${cmd_pid}" 2>/dev/null || true
+      sleep 2
+      kill -9 "${cmd_pid}" 2>/dev/null || true
+    fi
+  ) &
+  watchdog_pid=$!
+
+  wait "${cmd_pid}"
+  status=$?
+
+  kill "${watchdog_pid}" 2>/dev/null || true
+  wait "${watchdog_pid}" 2>/dev/null || true
+
+  if [ -f "${timeout_flag}" ]; then
+    rm -f "${timeout_flag}"
+    return 124
+  fi
+
+  rm -f "${timeout_flag}"
+  return "${status}"
+}
+
+is_usable_bun() {
+  [ -x "$1" ] && sh -c '"$1" --version >/dev/null 2>&1' sh "$1" 2>/dev/null
+}
+
+# Run buddy with the correct PATH and NODE_PATH for pantry resolution.
+run_buddy() {
+  BUN_CMD="$1"
+  shift
+
+  # When the framework SOURCE is vendored here (storage/framework/core) AND the
+  # installed @stacksjs/* packages actually ship src (a workspace/source-linked
+  # checkout), resolve them from src via the `development` export condition so the
+  # monorepo runs build-free (a fresh checkout has no dist yet).
+  #
+  # Guard on a representative package having src: an app that vendors the core but
+  # installs the PUBLISHED (dist-only) packages has no src, so the `development`
+  # condition would resolve to ./src/* files that were never shipped (`error:
+  # preload not found "@stacksjs/env/plugin.js"`, then Cannot-find-module for
+  # every other import). In that case omit the flag and let bun/import/default
+  # resolve the dist.
+  CONDITIONS=""
+  if [ -d "${ROOT_DIR}/storage/framework/core" ] && [ -f "${ROOT_DIR}/node_modules/@stacksjs/env/src/index.ts" ]; then
+    CONDITIONS="--conditions development"
+  fi
+
+  # Only prepend the pantry dir to NODE_PATH when the setup completed: for a
+  # node_modules app there is no ./pantry, and pointing NODE_PATH at a missing
+  # (or half-installed, after a failed bootstrap) dir makes bun miss
+  # node_modules (e.g. `Cannot find module '@stacksjs/env'` from a preload).
+  if [ -f "${PANTRY_SETUP_DONE}" ]; then
+    exec env PATH="${PANTRY_LOCAL_BIN}:${USER_LOCAL_BIN}:${PATH}" NODE_PATH="${PANTRY_DIR}:${NODE_PATH:-}" "${BUN_CMD}" ${CONDITIONS} "${BUDDY_ENTRY}" "$@"
+  fi
+  exec env PATH="${PANTRY_LOCAL_BIN}:${USER_LOCAL_BIN}:${PATH}" "${BUN_CMD}" ${CONDITIONS} "${BUDDY_ENTRY}" "$@"
+}
+
+# Fast path: if pantry is already set up, run immediately. We deliberately
+# DO NOT run `pantry install` here — re-installing on every invocation
+# burned ~1s of `buddy --help` startup time (and made shell completion
+# unusable). Once the pantry directory exists and a bun is on PATH, we
+# trust that state until the user explicitly runs `bun install` or
+# `buddy install`. To force a refresh, set STACKS_FORCE_PANTRY=1.
+if is_usable_bun "${PANTRY_LOCAL_BIN}/bun" && [ "${STACKS_FORCE_PANTRY:-}" != "1" ]; then
+  run_buddy "${PANTRY_LOCAL_BIN}/bun" "$@"
+fi
+
+if [ -d "${PANTRY_DIR}" ] && command -v bun >/dev/null 2>&1 && [ "${STACKS_FORCE_PANTRY:-}" != "1" ]; then
+  run_buddy "$(command -v bun)" "$@"
+fi
+
+# node_modules layout (framework from npm, not vendored): there is no per-project
+# pantry to bootstrap and none is needed to run the CLI — if a bun runtime is on
+# PATH and the pantry installer is absent, just use it.
+if command -v bun >/dev/null 2>&1 && [ "${STACKS_FORCE_PANTRY:-}" != "1" ] && [ ! -x "${PANTRY_INSTALLER}" ]; then
+  run_buddy "$(command -v bun)" "$@"
+fi
+
+# Pantry not set up (or an earlier bootstrap died halfway) - bootstrap it.
+# Every step is failure-tolerant on purpose: a pantry download/install hiccup
+# (a registry outage, or an unpublished release winning the race against CI)
+# must not abort this script under `set -e` before the bun fallbacks below
+# run. With a bun on PATH and node_modules present, the CLI runs identically
+# without pantry.
+pantry_bootstrap_failed=0
+if ! command -v pantry >/dev/null 2>&1; then
+  if [ -x "${PANTRY_INSTALLER}" ]; then
+    run_with_timeout "${PANTRY_BOOTSTRAP_TIMEOUT_SECONDS}" "${PANTRY_INSTALLER}" || pantry_bootstrap_failed=1
+    export PATH="${USER_LOCAL_BIN}:${PATH}"
+  else
+    echo "Pantry installer not found at ${PANTRY_INSTALLER}" >&2
+    pantry_bootstrap_failed=1
+  fi
+fi
+
+if command -v pantry >/dev/null 2>&1; then
+  run_with_timeout "${PANTRY_DEPENDENCIES_TIMEOUT_SECONDS}" pantry install || pantry_bootstrap_failed=1
+else
+  pantry_bootstrap_failed=1
+fi
+
+# After install, try again
+if is_usable_bun "${PANTRY_LOCAL_BIN}/bun"; then
+  run_buddy "${PANTRY_LOCAL_BIN}/bun" "$@"
+fi
+
+if command -v bun >/dev/null 2>&1; then
+  if [ "${pantry_bootstrap_failed}" = "1" ]; then
+    echo "buddy: pantry bootstrap incomplete; falling back to the bun on PATH." >&2
+  fi
+  run_buddy "$(command -v bun)" "$@"
+fi
+
+echo "Pantry did not provide a local bun runtime." >&2
+exit 1

package/project/storage/framework/tsconfig.app.json

@@ -0,0 +1,50 @@
+{
+  // Framework-provided defaults for YOUR application code: `app/`, `config/`,
+  // `resources/` and `routes/`. The project's root `tsconfig.json` extends this
+  // file, so everything set here applies unless the root overrides it.
+  //
+  // Framework internals are checked separately, by `tsconfig.framework.json`.
+  "extends": "./tsconfig.base.json",
+  "compilerOptions": {
+    // App code runs on both the server and in the browser (stx templates,
+    // stores, composables), so DOM types sit on top of the base `esnext` lib.
+    "lib": ["esnext", "dom"],
+    "rootDir": "../..",
+    // Kept inside the framework's own cache rather than `node_modules/.cache`,
+    // so the incremental build survives a `bun install` and never lands in a
+    // hoisted or symlinked `node_modules` shared with another project.
+    "tsBuildInfoFile": "./.cache/typescript/app.tsbuildinfo",
+    "paths": {
+      "@stacksjs/actions/*": ["./core/actions/src/*"],
+      "@stacksjs/*": ["./core/*/src"],
+      "stacks/*": ["./core/*/src"],
+      "buddy": ["./core/buddy/src/index.ts"],
+      "buddy/*": ["./core/buddy/src/*"],
+      "Actions/*": ["../../app/Actions/*"],
+      "Commands/*": ["../../app/Commands/*"],
+      "Jobs/*": ["../../app/Jobs/*"],
+      "Middleware/*": ["../../app/Middleware/*"],
+      "Models/*": ["../../app/Models/*"],
+      "Notifications/*": ["../../app/Notifications/*"],
+      "~/*": ["../../*"],
+      "@/*": ["../../resources/*"]
+    }
+  },
+  // Only the four directories you author, plus the generated framework
+  // declarations (auto-imports, ORM globals, model attributes) they rely on.
+  // Keeping this list tight is the single biggest lever on check time.
+  "include": [
+    "./types/**/*.d.ts",
+    "../../app/**/*.ts",
+    "../../config/**/*.ts",
+    "../../resources/**/*.ts",
+    "../../routes/**/*.ts"
+  ],
+  "exclude": [
+    "../../cloud/**",
+    "../../dist/**",
+    "../../node_modules/**",
+    "../../pantry/**",
+    "../../resources/assets/**"
+  ]
+}

package/project/storage/framework/tsconfig.base.json

@@ -0,0 +1,58 @@
+{
+  // The single source of truth for TypeScript defaults across a Stacks project.
+  //
+  // Nothing extends this file by accident: editors only auto-discover
+  // `tsconfig.json`, so this base is loaded exclusively through `extends`. It
+  // deliberately carries compiler options ONLY - `include`, `exclude` and
+  // `paths` are per-project concerns and live in the configs that extend it
+  // (`tsconfig.app.json`, `tsconfig.framework.json`, `core/tsconfig.json`).
+  //
+  // Every option below is written out explicitly rather than inherited, so the
+  // full default set is readable in one place and a project can override any
+  // single line without having to rediscover what the rest of them were.
+  //
+  // Type checking runs on TypeScript 7 (`tsc`, the native Go compiler). Options
+  // dropped in 7.0 - `baseUrl`, `importsNotUsedAsValues`, `preserveValueImports`,
+  // `suppressImplicitAnyIndexErrors`, `out`, `charset` - are intentionally absent.
+  // Path mappings resolve relative to the config file that declares them, which
+  // is why no `baseUrl` is needed.
+  "compilerOptions": {
+    /* Language and environment */
+    "target": "esnext",
+    "lib": ["esnext"],
+    "jsx": "preserve",
+
+    /* Modules */
+    "module": "esnext",
+    "moduleDetection": "force",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "allowImportingTsExtensions": true,
+    // Only Bun's ambient types are loaded automatically. Anything else has to
+    // be imported explicitly, which keeps tsgo from scanning every @types
+    // package it can reach.
+    "types": ["bun"],
+
+    /* Interop */
+    "allowSyntheticDefaultImports": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "isolatedModules": true,
+
+    /* Type checking */
+    "strict": true,
+    "strictNullChecks": true,
+    "noUncheckedIndexedAccess": true,
+    "noUncheckedSideEffectImports": true,
+    // Left off because pickier already reports unused locals, and it can
+    // auto-fix them. Two tools flagging the same thing is just noise.
+    "noUnusedLocals": false,
+
+    /* Emit - Bun does the bundling, tsc only ever type checks */
+    "noEmit": true,
+
+    /* Performance */
+    "incremental": true,
+    "skipLibCheck": true
+  }
+}

package/routes/core.ts

@@ -0,0 +1,78 @@
+import process from 'node:process'
+import { route } from '@stacksjs/router'
+
+/**
+ * Framework routes shared by every Stacks app.
+ *
+ * User routes load first — defining the same path in `routes/web.ts` or
+ * `routes/api.ts` overrides these defaults.
+ */
+route.get('/locale/{locale}', 'Actions/Locale/SetLocaleAction')
+
+// robots.txt — block crawler indexing on non-production envs so staging /
+// preview deploys don't end up in search results (stacksjs/stacks#1077).
+// APP_ENV wins over NODE_ENV because Stacks apps key everything off APP_ENV.
+// Define a `/robots.txt` route in your own routes to override.
+route.get('/robots.txt', () => {
+  const env = (process.env.APP_ENV ?? process.env.NODE_ENV ?? '').toLowerCase()
+  const body = env === 'production'
+    ? 'User-agent: *\nAllow: /\n'
+    : 'User-agent: *\nDisallow: /\n'
+  return new Response(body, {
+    headers: { 'Content-Type': 'text/plain; charset=utf-8' },
+  })
+}).skipCsrf()
+
+// Mailable preview routes (stacksjs/stacks#1900 A3) — dev-only HTML
+// pages that render every Mailable in `app/Mail/` with sample props
+// from `resources/emails/_previews/<slug>.ts`. Production deployments
+// short-circuit to 404 so even an accidental route registration in
+// prod can't leak the preview surface.
+function isProduction(): boolean {
+  const env = (process.env.APP_ENV ?? process.env.NODE_ENV ?? '').toLowerCase()
+  return env === 'production'
+}
+
+function notFound(): Response {
+  return new Response('Not Found', { status: 404 })
+}
+
+route.get('/_stacks/mail/preview', async () => {
+  if (isProduction()) return notFound()
+  const { discoverMailables, renderIndexHtml } = await import('@stacksjs/email')
+  return new Response(renderIndexHtml(discoverMailables()), {
+    headers: { 'Content-Type': 'text/html; charset=utf-8' },
+  })
+}).skipCsrf()
+
+route.get('/_stacks/mail/preview/{name}', async (req: any) => {
+  if (isProduction()) return notFound()
+  const { discoverMailables, renderMailablePreview, renderPreviewHtml } = await import('@stacksjs/email')
+  const slug = String(req?.params?.name ?? '')
+  const mailable = discoverMailables().find(m => m.slug === slug)
+  if (!mailable) return notFound()
+  const preview = await renderMailablePreview(mailable)
+  const url = new URL(req.url)
+  const view = url.searchParams.get('view')
+  const variant: 'desktop' | 'mobile' | 'text'
+    = view === 'mobile' ? 'mobile' : view === 'text' ? 'text' : 'desktop'
+  return new Response(renderPreviewHtml(mailable, preview, variant), {
+    headers: { 'Content-Type': 'text/html; charset=utf-8' },
+  })
+}).skipCsrf()
+
+// Raw rendered body for the preview-page iframe — same handler shape
+// but skips the surrounding UI chrome so the iframe renders only the
+// email body itself. Returning text/html lets the browser style it
+// natively without our outer stylesheet leaking in.
+route.get('/_stacks/mail/preview/{name}/raw', async (req: any) => {
+  if (isProduction()) return notFound()
+  const { discoverMailables, renderMailablePreview } = await import('@stacksjs/email')
+  const slug = String(req?.params?.name ?? '')
+  const mailable = discoverMailables().find(m => m.slug === slug)
+  if (!mailable) return notFound()
+  const preview = await renderMailablePreview(mailable)
+  return new Response(preview.html || '<!DOCTYPE html><html><body><p style="font-family:sans-serif;color:#6b7280;padding:40px;text-align:center">No HTML body — try the Text tab.</p></body></html>', {
+    headers: { 'Content-Type': 'text/html; charset=utf-8' },
+  })
+}).skipCsrf()