@stacksjs/config 0.70.88 → 0.70.91

package/dist/features.js

@@ -0,0 +1,53 @@
+import { config } from "./config";
+const FEATURE_NAMES = [
+  "auth",
+  "marketing",
+  "cms",
+  "commerce",
+  "dashboard",
+  "monitoring",
+  "realtime",
+  "queue"
+], FEATURE_DEFAULTS = {
+  dashboard: !0
+}, overrides = new Map;
+function configFor(name) {
+  const raw = config[name];
+  return raw && typeof raw === "object" ? raw : void 0;
+}
+export function feature(name) {
+  if (overrides.has(name))
+    return overrides.get(name);
+  const cfg = configFor(name);
+  if (cfg) {
+    const enabledField = cfg.enabled;
+    if (enabledField === !1)
+      return !1;
+    if (Array.isArray(cfg.env) && cfg.env.length > 0) {
+      const currentEnv = (config.app?.env ?? "").toString();
+      if (!cfg.env.includes(currentEnv))
+        return !1;
+    }
+    if (enabledField !== void 0)
+      return !!enabledField;
+    return !0;
+  }
+  return FEATURE_DEFAULTS[name] ?? !1;
+}
+export function enableFeature(name) {
+  overrides.set(name, !0);
+}
+export function disableFeature(name) {
+  overrides.set(name, !1);
+}
+export function resetFeature(name) {
+  overrides.delete(name);
+}
+export function listFeatures() {
+  const out = {};
+  for (const name of FEATURE_NAMES)
+    out[name] = feature(name);
+  for (const name of overrides.keys())
+    out[name] = feature(name);
+  return out;
+}

package/dist/helpers.d.ts

@@ -0,0 +1,45 @@
+import { config } from '.';
+import type { AppConfig, CacheConfig, CdnConfig, ChatConfig, CliConfig, DatabaseConfig, DependenciesConfig, DnsConfig, EmailConfig, Events, FilesystemsConfig, FeatureFlagsConfig, GitConfig, HashingConfig, LibraryConfig, Model, NotificationConfig, PaymentConfig, QueueConfig, SearchEngineConfig, SecurityConfig, ServicesConfig, StacksConfig, StorageConfig, UiConfig } from '@stacksjs/types';
+export declare function localUrl(options?: {
+  domain?: string
+  type?: LocalUrlType
+  network?: boolean
+  localhost?: boolean
+  https?: boolean
+}): Promise<string>;
+export declare function defineStacksConfig(config: StacksConfig): StacksConfig;
+export declare function defineApp(config: AppConfig): AppConfig;
+export declare function defineCache(config: CacheConfig): CacheConfig;
+export declare function defineCdn(config: CdnConfig): CdnConfig;
+export declare function defineChat(config: ChatConfig): ChatConfig;
+export declare function defineCli(config: CliConfig): CliConfig;
+export declare function defineDatabase(config: DatabaseConfig): DatabaseConfig;
+export declare function defineDependencies(config: DependenciesConfig): DependenciesConfig;
+export declare function defineDns(config: DnsConfig): DnsConfig;
+export declare function defineEmailConfig(config: EmailConfig): EmailConfig;
+export declare function defineEmail(config: EmailConfig): EmailConfig;
+export declare function defineGit(config: GitConfig): GitConfig;
+export declare function defineHashing(config: HashingConfig): HashingConfig;
+export declare function defineLibrary(config: LibraryConfig): LibraryConfig;
+export declare function defineNotification(config: NotificationConfig): NotificationConfig;
+export declare function definePayment(config: PaymentConfig): PaymentConfig;
+export declare function defineQueue(config: QueueConfig): QueueConfig;
+export declare function defineSearchEngine(config: SearchEngineConfig): SearchEngineConfig;
+export declare function defineSecurity(config: SecurityConfig): SecurityConfig;
+export declare function defineServices(config: ServicesConfig): ServicesConfig;
+export declare function defineSms(config: any): any;
+export declare function defineStorage(config: StorageConfig): StorageConfig;
+export declare function defineFilesystems(config: FilesystemsConfig): FilesystemsConfig;
+export declare function defineFeatureFlags(config: FeatureFlagsConfig): FeatureFlagsConfig;
+export declare function defineUi(config: UiConfig): UiConfig;
+export declare function defineModel(config: Model): Model;
+export declare function defineEvents(config: Events): Events;
+export type LocalUrlType = | 'frontend'
+  | 'backend'
+  | 'api'
+  | 'admin'
+  | 'library'
+  | 'email'
+  | 'docs'
+  | 'inspect'
+  | 'desktop';

package/dist/helpers.js

@@ -0,0 +1,153 @@
+import { config } from ".";
+export async function localUrl(options = {}) {
+  const domain = options.domain ?? config.app.url ?? "stacks", type = options.type ?? "frontend", localhost = options.localhost ?? !1, https = options.https, network = options.network;
+  let url = domain.replace(/\.[^.]+$/, ".localhost");
+  async function tunnel(port) {
+    const { createLocalTunnel } = await import("@stacksjs/tunnel");
+    return createLocalTunnel(port);
+  }
+  switch (type) {
+    case "frontend":
+      if (network)
+        return await tunnel(config.ports?.frontend || 3000);
+      if (localhost)
+        return `http://localhost:${config.ports?.frontend}`;
+      break;
+    case "backend":
+      if (network)
+        return await tunnel(config.ports?.backend || 3001);
+      if (localhost)
+        return `http://localhost:${config.ports?.backend}`;
+      url = `api.${url}`;
+      break;
+    case "admin":
+      if (network)
+        return await tunnel(config.ports?.admin || 3002);
+      if (localhost)
+        return `http://localhost:${config.ports?.admin}`;
+      url = `admin.${url}`;
+      break;
+    case "library":
+      if (network)
+        return await tunnel(config.ports?.library || 3003);
+      if (localhost)
+        return `http://localhost:${config.ports?.library}`;
+      url = `libs.${url}`;
+      break;
+    case "email":
+      if (network)
+        return await tunnel(config.ports?.email || 3005);
+      if (localhost)
+        return `http://localhost:${config.ports?.email}`;
+      url = `email.${url}`;
+      break;
+    case "desktop":
+      if (network)
+        return await tunnel(config.ports?.desktop || 3004);
+      if (localhost)
+        return `http://localhost:${config.ports?.desktop}`;
+      url = `desktop.${url}`;
+      break;
+    case "docs":
+      if (network)
+        return await tunnel(config.ports?.docs || 3006);
+      if (localhost)
+        return `http://localhost:${config.ports?.docs}`;
+      url = `docs.${url}`;
+      break;
+    case "inspect":
+      if (network)
+        return await tunnel(config.ports?.inspect || 3007);
+      if (localhost)
+        return `http://localhost:${config.ports?.inspect}`;
+      url = `inspect.${url}`;
+      break;
+    default:
+      if (localhost)
+        return `http://localhost:${config.ports?.frontend}`;
+  }
+  if (https)
+    return `https://${url}`;
+  return `http://${url}`;
+}
+export function defineStacksConfig(config) {
+  return config;
+}
+export function defineApp(config) {
+  return config;
+}
+export function defineCache(config) {
+  return config;
+}
+export function defineCdn(config) {
+  return config;
+}
+export function defineChat(config) {
+  return config;
+}
+export function defineCli(config) {
+  return config;
+}
+export function defineDatabase(config) {
+  return config;
+}
+export function defineDependencies(config) {
+  return config;
+}
+export function defineDns(config) {
+  return config;
+}
+export function defineEmailConfig(config) {
+  return config;
+}
+export function defineEmail(config) {
+  return config;
+}
+export function defineGit(config) {
+  return config;
+}
+export function defineHashing(config) {
+  return config;
+}
+export function defineLibrary(config) {
+  return config;
+}
+export function defineNotification(config) {
+  return config;
+}
+export function definePayment(config) {
+  return config;
+}
+export function defineQueue(config) {
+  return config;
+}
+export function defineSearchEngine(config) {
+  return config;
+}
+export function defineSecurity(config) {
+  return config;
+}
+export function defineServices(config) {
+  return config;
+}
+export function defineSms(config) {
+  return config;
+}
+export function defineStorage(config) {
+  return config;
+}
+export function defineFilesystems(config) {
+  return config;
+}
+export function defineFeatureFlags(config) {
+  return config;
+}
+export function defineUi(config) {
+  return config;
+}
+export function defineModel(config) {
+  return config;
+}
+export function defineEvents(config) {
+  return config;
+}

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+// IMPORTANT: do NOT re-add `export * as config from './config'` here.
+// That line creates a module-namespace object named `config` whose
+// properties are non-configurable per the ESM spec (namespaces are sealed).
+// Because `export *` is also exporting the real `config` proxy from
+// `./config`, the namespace object would shadow the proxy under the
+// `config` name — and consumers that did `import { config }` would get
+// the sealed namespace, not the live proxy. The visible symptom: every
+// `config.X` read returns whatever value the proxy's get trap produced
+// the *first* time (typically defaults), and later mutations from
+// `overridesReady` are silently ignored.
+export * from './config';
+export { FRAMEWORK_DEFAULTS } from './defaults';
+export { validateConfig, reportConfigIssues, type ConfigValidationIssue } from './validators';
+export { feature, enableFeature, disableFeature, resetFeature, listFeatures } from './features';

package/dist/index.js

@@ -0,0 +1,4 @@
+export * from "./config";
+export { FRAMEWORK_DEFAULTS } from "./defaults";
+export { validateConfig, reportConfigIssues } from "./validators";
+export { feature, enableFeature, disableFeature, resetFeature, listFeatures } from "./features";

package/dist/overrides.d.ts

@@ -0,0 +1,4 @@
+import type { StacksConfig } from '@stacksjs/types';
+export declare const overrides: StacksConfig;
+export declare const overridesReady: Promise<StacksConfig>;
+export default overrides;

package/dist/overrides.js

@@ -0,0 +1,111 @@
+import { validateConfig } from "./validators";
+const skipConfigLoading = process.env.SKIP_CONFIG_LOADING === "true", skipConfigValidation = process.env.SKIP_CONFIG_VALIDATION === "true", OVERRIDES_KEY = Symbol.for("@stacksjs/config:overrides"), READY_KEY = Symbol.for("@stacksjs/config:overridesReady");
+function defaultsForOverrides() {
+  return {
+    ai: {},
+    analytics: {},
+    app: { name: process.env.APP_NAME || "Stacks", env: process.env.APP_ENV || "production" },
+    auth: {},
+    cache: {},
+    cli: {},
+    cloud: {},
+    cms: {},
+    commerce: {},
+    dashboard: {},
+    database: {},
+    dns: {},
+    realtime: {},
+    email: {},
+    errors: {},
+    featureFlags: {},
+    git: {},
+    hashing: {},
+    library: {},
+    logging: {},
+    marketing: {},
+    monitoring: {},
+    notification: {},
+    queue: {},
+    payment: {},
+    ports: {},
+    saas: {},
+    searchEngine: {},
+    security: {},
+    services: {},
+    filesystems: {},
+    team: {},
+    ui: {}
+  };
+}
+const globalScope = globalThis, sharedOverrides = globalScope[OVERRIDES_KEY];
+export const overrides = sharedOverrides ?? (() => {
+  const created = defaultsForOverrides();
+  globalScope[OVERRIDES_KEY] = created;
+  return created;
+})();
+const userConfigs = [
+  ["ai", "~/config/ai"],
+  ["analytics", "~/config/analytics"],
+  ["app", "~/config/app"],
+  ["auth", "~/config/auth"],
+  ["cache", "~/config/cache"],
+  ["cli", "~/config/cli"],
+  ["cloud", "~/config/cloud"],
+  ["cms", "~/config/cms"],
+  ["commerce", "~/config/commerce"],
+  ["dashboard", "~/config/dashboard"],
+  ["database", "~/config/database"],
+  ["dns", "~/config/dns"],
+  ["email", "~/config/email"],
+  ["errors", "~/config/errors"],
+  ["featureFlags", "~/config/feature-flags"],
+  ["git", "~/config/git"],
+  ["hashing", "~/config/hashing"],
+  ["library", "~/config/library"],
+  ["logging", "~/config/logging"],
+  ["marketing", "~/config/marketing"],
+  ["monitoring", "~/config/monitoring"],
+  ["notification", "~/config/notification"],
+  ["payment", "~/config/payment"],
+  ["ports", "~/config/ports"],
+  ["queue", "~/config/queue"],
+  ["realtime", "~/config/realtime"],
+  ["saas", "~/config/saas"],
+  ["searchEngine", "~/config/search-engine"],
+  ["security", "~/config/security"],
+  ["services", "~/config/services"],
+  ["filesystems", "~/config/filesystems"],
+  ["team", "~/config/team"],
+  ["ui", "~/config/ui"]
+], sharedReady = globalScope[READY_KEY];
+export const overridesReady = sharedReady ?? (() => {
+  const promise = skipConfigLoading ? Promise.resolve(overrides) : Promise.all(userConfigs.map(async ([key, modulePath]) => {
+    try {
+      const mod = await import(modulePath);
+      if (mod?.default !== void 0)
+        overrides[key] = mod.default;
+    } catch (err) {
+      const code = err?.code, msg = err?.message ?? String(err);
+      if (!(code === "ERR_MODULE_NOT_FOUND" || code === "MODULE_NOT_FOUND" || /Cannot find module/i.test(msg)))
+        console.warn(`[config] Failed to load ${String(key)} config from ${modulePath}: ${msg}`);
+    }
+  })).then(() => {
+    if (!skipConfigValidation) {
+      const issues = validateConfig(overrides);
+      if (issues.length > 0) {
+        console.error("[config] Configuration issues detected:");
+        for (const issue of issues)
+          console.error(`  \u2022 ${issue.path}: ${issue.message}`);
+        const summary = issues.map((i) => `  \u2022 ${i.path}: ${i.message}`).join(`
+`);
+        throw Error(`[config] ${issues.length} configuration issue(s) detected at boot:
+${summary}
+Set SKIP_CONFIG_VALIDATION=true to bypass (e.g. when running migrations against partial config).`);
+      }
+    }
+    return overrides;
+  });
+  globalScope[READY_KEY] = promise;
+  return promise;
+})();
+export default overrides;

package/dist/validators.d.ts

@@ -0,0 +1,19 @@
+import type { StacksConfig } from '@stacksjs/types';
+/**
+ * Validate a config snapshot. Returns the list of issues — caller decides
+ * whether to throw, log, or just print a summary. Returns an empty array
+ * when everything checks out.
+ */
+export declare function validateConfig(config: Partial<StacksConfig>): ConfigValidationIssue[];
+/**
+ * Convenience: validate and pretty-print to stderr. Returns true when
+ * the config is clean. Used by the boot path so users see issues
+ * immediately on startup rather than digging into a stack trace later.
+ */
+export declare function reportConfigIssues(config: Partial<StacksConfig>): boolean;
+export declare interface ConfigValidationIssue {
+  path: string
+  message: string
+}
+// eslint-disable-next-line pickier/no-unused-vars
+declare type Check = (value: unknown, path: string) => ConfigValidationIssue[];

package/dist/validators.js

@@ -0,0 +1,119 @@
+function isPlainObject(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function checkInteger(min, max) {
+  return (value, path) => {
+    if (value == null)
+      return [];
+    let num = null;
+    if (typeof value === "number" && Number.isInteger(value))
+      num = value;
+    else if (typeof value === "string" && /^-?\d+$/.test(value))
+      num = Number.parseInt(value, 10);
+    if (num === null)
+      return [{ path, message: `expected integer, got ${typeof value} (${JSON.stringify(value)})` }];
+    if (num < min || num > max)
+      return [{ path, message: `expected integer in [${min}, ${max}], got ${num}` }];
+    return [];
+  };
+}
+function checkOneOf(values) {
+  return (value, path) => {
+    if (value == null)
+      return [];
+    if (typeof value !== "string" || !values.includes(value))
+      return [{ path, message: `expected one of [${values.join(", ")}], got ${JSON.stringify(value)}` }];
+    return [];
+  };
+}
+function checkString() {
+  return (value, path) => {
+    if (value == null)
+      return [];
+    return typeof value === "string" ? [] : [{ path, message: `expected string, got ${typeof value}` }];
+  };
+}
+function checkBoolean() {
+  return (value, path) => {
+    if (value == null)
+      return [];
+    return typeof value === "boolean" ? [] : [{ path, message: `expected boolean, got ${typeof value}` }];
+  };
+}
+const PORT_CHECK = checkInteger(1, 65535), SCHEMA = {
+  app: {
+    rules: {
+      name: checkString(),
+      env: checkOneOf(["local", "development", "staging", "production", "test"]),
+      debug: checkBoolean(),
+      url: checkString()
+    }
+  },
+  ports: {
+    rules: {
+      frontend: PORT_CHECK,
+      api: PORT_CHECK,
+      admin: PORT_CHECK,
+      docs: PORT_CHECK,
+      systemTray: PORT_CHECK,
+      desktop: PORT_CHECK
+    }
+  },
+  database: {
+    rules: {
+      default: checkOneOf(["sqlite", "mysql", "singlestore", "postgres", "dynamodb"])
+    }
+  },
+  cache: {
+    rules: {
+      driver: checkOneOf(["memory", "redis", "singlestore"])
+    }
+  },
+  featureFlags: {
+    rules: {
+      default: checkOneOf(["memory", "database"]),
+      missing: checkOneOf(["false", "throw"])
+    }
+  },
+  queue: {
+    rules: {
+      default: checkOneOf(["sync", "database", "redis"])
+    }
+  },
+  logging: {
+    rules: {
+      level: checkOneOf(["trace", "debug", "info", "warn", "error", "fatal"])
+    }
+  },
+  email: {
+    rules: {
+      default: checkOneOf(["ses", "sendgrid", "mailgun", "mailtrap", "smtp", "log", "capture"])
+    }
+  }
+};
+export function validateConfig(config) {
+  const issues = [];
+  for (const [section, schema] of Object.entries(SCHEMA)) {
+    const sectionValue = config[section];
+    if (sectionValue == null)
+      continue;
+    if (!isPlainObject(sectionValue)) {
+      issues.push({ path: section, message: `expected object, got ${typeof sectionValue}` });
+      continue;
+    }
+    for (const [field, check] of Object.entries(schema.rules)) {
+      const v = sectionValue[field];
+      issues.push(...check(v, `${section}.${field}`));
+    }
+  }
+  return issues;
+}
+export function reportConfigIssues(config) {
+  const issues = validateConfig(config);
+  if (issues.length === 0)
+    return !0;
+  console.warn("[config] Configuration issues detected:");
+  for (const issue of issues)
+    console.warn(`  \u2022 ${issue.path}: ${issue.message}`);
+  return !1;
+}

package/package.json

@@ -2,7 +2,7 @@
   "name": "@stacksjs/config",
   "type": "module",
   "sideEffects": false,
-  "version": "0.70.88",
+  "version": "0.70.91",
   "description": "The Stacks config helper methods.",
   "author": "Chris Breuer",
   "contributors": [
@@ -53,9 +53,9 @@
     "ts-pantry": "^0.10.11"
   },
   "devDependencies": {
-    "@stacksjs/alias": "0.70.88",
+    "@stacksjs/alias": "0.70.91",
     "better-dx": "^0.2.16",
-    "@stacksjs/types": "0.70.88",
+    "@stacksjs/types": "0.70.91",
     "bunfig": "^0.15.11"
   }
 }