@stacksjs/stx 0.2.0 → 0.2.3

package/dist/deploy/config-generators.d.ts

@@ -0,0 +1,75 @@
+import path from 'node:path';
+/**
+ * Generate netlify.toml content from config
+ */
+export declare function generateNetlifyToml(config: NetlifyConfig): string;
+/**
+ * Detect project configuration from filesystem
+ */
+export declare function detectProjectConfig(directory: string): Promise<ProjectConfig>;
+/**
+ * Generate default Netlify config for an stx project
+ */
+export declare function createDefaultNetlifyConfig(projectConfig?: ProjectConfig): NetlifyConfig;
+/**
+ * Write netlify.toml to a directory
+ */
+export declare function writeNetlifyConfig(directory: string, config?: NetlifyConfig): Promise<string>;
+/**
+ * Check if netlify.toml exists
+ */
+export declare function hasNetlifyConfig(directory: string): boolean;
+/**
+ * Read existing netlify.toml (basic parsing)
+ */
+export declare function readNetlifyConfig(directory: string): Promise<string | null>;
+// ============================================================================
+// Types
+// ============================================================================
+export declare interface NetlifyConfig {
+  build: {
+    command: string
+    publish: string
+    functions?: string
+    edge_functions?: string
+    environment?: Record<string, string>
+  }
+  functions?: {
+    directory?: string
+    node_bundler?: 'esbuild' | 'nft'
+    external_node_modules?: string[]
+  }
+  edge_functions?: Array<{
+    function: string
+    path: string
+  }>
+  redirects?: Array<{
+    from: string
+    to: string
+    status?: number
+    force?: boolean
+    conditions?: Record<string, string>
+  }>
+  headers?: Array<{
+    for: string
+    values: Record<string, string>
+  }>
+  plugins?: Array<{
+    package: string
+    inputs?: Record<string, unknown>
+  }>
+  context?: Record<string, {
+    command?: string
+    publish?: string
+    environment?: Record<string, string>
+  }>
+}
+export declare interface ProjectConfig {
+  framework?: 'stx' | 'static' | 'spa'
+  buildCommand?: string
+  outputDir?: string
+  functionsDir?: string
+  edgeFunctionsDir?: string
+  nodeVersion?: string
+  isSPA?: boolean
+}

package/dist/deploy/index.d.ts

@@ -0,0 +1,84 @@
+import { createNetlifyClient, collectDeployFiles, createFileManifest, filterRequiredFiles, formatSize, getTotalSize,  } from './netlify';
+import { detectProjectConfig, createDefaultNetlifyConfig, generateNetlifyToml, writeNetlifyConfig, hasNetlifyConfig,  } from './config-generators';
+export type {
+  NetlifyClient,
+  NetlifySite,
+  NetlifyDeploy,
+  DeployFile,
+} from './netlify';
+export type {
+  NetlifyConfig,
+  ProjectConfig,
+} from './config-generators';
+/**
+ * Deploy to Netlify
+ */
+export declare function deploy(config?: DeployConfig): Promise<DeployResult>;
+/**
+ * Initialize Netlify configuration for a project
+ */
+export declare function initNetlify(config?: InitConfig): Promise<{
+  configPath: string
+  siteId?: string
+}>;
+// ============================================================================
+// Types
+// ============================================================================
+export declare interface DeployConfig {
+  directory?: string
+  siteId?: string
+  token?: string
+  production?: boolean
+  message?: string
+  build?: boolean
+  open?: boolean
+  dryRun?: boolean
+  functions?: string
+  cwd?: string
+  onProgress?: (status: DeployProgress) => void
+}
+export declare interface DeployProgress {
+  stage: 'build' | 'collect' | 'upload' | 'process' | 'done' | 'error'
+  message: string
+  percent?: number
+  details?: unknown
+}
+export declare interface DeployResult {
+  success: boolean
+  url: string
+  siteUrl?: string
+  deployId: string
+  logs: string[]
+  duration: number
+  filesUploaded: number
+  totalSize: number
+}
+export declare interface InitConfig {
+  directory?: string
+  siteId?: string
+  createSite?: boolean
+  siteName?: string
+}
+// ============================================================================
+// Error Handling
+// ============================================================================
+export declare class DeployError extends Error {
+  code: string;
+  constructor(message: string, code: string);
+}
+export {
+  createNetlifyClient,
+  collectDeployFiles,
+  createFileManifest,
+  filterRequiredFiles,
+  formatSize,
+  getTotalSize,
+  calculateSha1,
+} from './netlify';
+export {
+  generateNetlifyToml,
+  detectProjectConfig,
+  createDefaultNetlifyConfig,
+  writeNetlifyConfig,
+  hasNetlifyConfig,
+} from './config-generators';

package/dist/deploy/netlify.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Create a Netlify API client
+ */
+export declare function createNetlifyClient(config: NetlifyClientConfig): NetlifyClient;
+/**
+ * Calculate SHA1 hash of file content
+ */
+export declare function calculateSha1(content: ArrayBuffer | Uint8Array): Promise<string>;
+/**
+ * Collect files from a directory for deployment
+ */
+export declare function collectDeployFiles(directory: string, options?: { ignore?: string[] }): Promise<DeployFile[]>;
+/**
+ * Create file manifest (path -> sha1 hash mapping)
+ */
+export declare function createFileManifest(files: DeployFile[]): Record<string, string>;
+/**
+ * Filter files that need uploading (not already on Netlify)
+ */
+export declare function filterRequiredFiles(files: DeployFile[], required: string[]): DeployFile[];
+/**
+ * Format file size for display
+ */
+export declare function formatSize(bytes: number): string;
+/**
+ * Get total size of files
+ */
+export declare function getTotalSize(files: DeployFile[]): number;
+// ============================================================================
+// Types
+// ============================================================================
+export declare interface NetlifySite {
+  id: string
+  name: string
+  url: string
+  ssl_url: string
+  admin_url: string
+  created_at: string
+  updated_at: string
+  custom_domain?: string
+  default_domain: string
+  deploy_url: string
+  published_deploy?: NetlifyDeploy
+}
+export declare interface NetlifyDeploy {
+  id: string
+  site_id: string
+  state: 'new' | 'pending_review' | 'uploading' | 'uploaded' | 'preparing' | 'prepared' | 'processing' | 'ready' | 'error' | 'retrying'
+  name: string
+  url: string
+  ssl_url: string
+  admin_url: string
+  deploy_url: string
+  deploy_ssl_url: string
+  created_at: string
+  updated_at: string
+  published_at?: string
+  title?: string
+  context: string
+  branch?: string
+  commit_ref?: string
+  commit_url?: string
+  review_url?: string
+  error_message?: string
+  required: string[]
+  required_functions?: string[]
+}
+export declare interface CreateDeployOptions {
+  title?: string
+  branch?: string
+  draft?: boolean
+  files: Record<string, string>
+  functions?: Record<string, string>
+  async?: boolean
+}
+export declare interface DeployFile {
+  path: string
+  content: ArrayBuffer | Uint8Array
+  sha1: string
+}
+export declare interface NetlifyClientConfig {
+  token: string
+  baseUrl?: string
+}
+export declare interface NetlifyError extends Error {
+  status: number
+  code?: string
+  details?: unknown
+}
+// ============================================================================
+// Netlify Client
+// ============================================================================
+export declare interface NetlifyClient {
+  getSite(siteId: string): Promise<NetlifySite>
+  listSites(): Promise<NetlifySite[]>
+  createSite(name?: string): Promise<NetlifySite>
+  createDeploy(siteId: string, options: CreateDeployOptions): Promise<NetlifyDeploy>
+  uploadFile(deployId: string, path: string, content: ArrayBuffer | Uint8Array): Promise<void>
+  uploadFiles(deployId: string, files: DeployFile[]): Promise<void>
+  getDeploy(deployId: string): Promise<NetlifyDeploy>
+  waitForDeploy(deployId: string, options?: WaitOptions): Promise<NetlifyDeploy>
+  lockDeploy(deployId: string): Promise<NetlifyDeploy>
+  unlockDeploy(deployId: string): Promise<NetlifyDeploy>
+}
+export declare interface WaitOptions {
+  timeout?: number
+  pollInterval?: number
+  onProgress?: (deploy: NetlifyDeploy) => void
+}

package/dist/dev-server/crosswind.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Lazily load the Crosswind module
+ * Returns null if Crosswind is not installed
+ */
+export declare function loadCrosswind(): Promise<CrosswindModule | null>;
+/**
+ * Reset the Crosswind module cache (useful for testing)
+ */
+export declare function resetCrosswindCache(): void;
+/**
+ * Load crosswind config from the working directory
+ */
+export declare function loadCrosswindConfig(cwd: string): Promise<CrosswindConfig | null>;
+/**
+ * Build Crosswind CSS using the build() API
+ * This scans content files and generates CSS for all used classes
+ */
+export declare function buildCrosswindCSS(cwd: string): Promise<string>;
+/**
+ * Rebuild Crosswind CSS (called on file changes)
+ */
+export declare function rebuildCrosswindCSS(cwd: string): Promise<void>;
+/**
+ * Get the cached CSS (for serving)
+ */
+export declare function getCachedCSS(): string;
+/**
+ * Extract all CSS class names from HTML content
+ */
+export declare function extractClassNames(htmlContent: string): Set<string>;
+/**
+ * Extract utility classes from HTML content and generate CSS using Crosswind
+ */
+export declare function generateCrosswindCSS(htmlContent: string): Promise<string>;
+/**
+ * Inject generated CSS into HTML content
+ * Tries to inject before </head>, falls back to <body> or prepends
+ */
+export declare function injectCrosswindCSS(htmlContent: string): Promise<string>;
+// Type for Crosswind module
+declare interface CrosswindModule {
+  CSSGenerator: new (config: CrosswindConfig) => CSSGenerator
+  config: CrosswindConfig
+  build?: (config: CrosswindConfig) => Promise<CrosswindBuildResult>
+  defaultConfig?: CrosswindConfig
+}
+declare interface CrosswindConfig {
+  content?: string[]
+  output?: string
+  preflight?: boolean
+  minify?: boolean
+  preflights?: unknown[]
+  safelist?: string[]
+}

package/dist/dev-server/index.d.ts

@@ -0,0 +1,7 @@
+export * from './terminal-colors';
+export * from './crosswind';
+export * from './theme-selector';
+export * from './port-utils';
+export * from './native-window';
+export * from './keyboard-shortcuts';
+export * from './types';

package/dist/dev-server/keyboard-shortcuts.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Print keyboard shortcuts help
+ */
+export declare function printShortcutsHelp(): void;
+/**
+ * Print server status with URL
+ */
+export declare function printServerStatus(serverUrl: string): void;
+/**
+ * Open URL in the default browser
+ */
+export declare function openInBrowser(url: string): void;
+/**
+ * Setup keyboard shortcuts for the server
+ * Enables raw mode for handling single keystrokes
+ *
+ * @param serverUrl - The URL of the dev server
+ * @param stopServer - Function to call when stopping the server
+ * @param customHandlers - Optional custom command handlers
+ */
+export declare function setupKeyboardShortcuts(serverUrl: string, stopServer: () => void, customHandlers?: KeyboardCommandHandlers): void;
+/**
+ * Cleanup keyboard shortcuts (restore terminal state)
+ */
+export declare function cleanupKeyboardShortcuts(): void;
+/**
+ * Keyboard shortcut command handlers
+ */
+export declare interface KeyboardCommandHandlers {
+  onOpen?: () => void
+  onClear?: () => void
+  onQuit?: () => void
+  onHelp?: () => void
+}

package/dist/dev-server/native-window.d.ts

@@ -0,0 +1,40 @@
+import type { SidebarConfig } from '@stacksjs/desktop';
+/**
+ * Open a native window for development
+ * Uses the desktop package to create a webview window
+ *
+ * @param port - The port the dev server is running on
+ * @param config - Optional configuration overrides
+ * @returns true if window opened successfully, false otherwise
+ */
+export declare function openNativeWindow(port: number, config?: NativeWindowConfig): Promise<boolean>;
+/**
+ * Check if native window support is available
+ * Returns true if the desktop package can be used
+ */
+export declare function isNativeWindowSupported(): Promise<boolean>;
+/**
+ * Extract sidebar configuration from template content
+ * Looks for:
+ * 1. <Sidebar variant="tahoe"> component with props
+ * 2. @nativeSidebar directive
+ * 3. <script native-sidebar> (deprecated)
+ */
+export declare function extractSidebarConfig(templateContent: string): SidebarConfig | undefined;
+/**
+ * Default configuration for the native window
+ */
+export declare const DEFAULT_NATIVE_WINDOW_CONFIG: Required<Omit<NativeWindowConfig, 'sidebarConfig'>> & { sidebarConfig?: SidebarConfig };
+/**
+ * Configuration for the native development window
+ */
+export declare interface NativeWindowConfig {
+  title?: string
+  width?: number
+  height?: number
+  darkMode?: boolean
+  hotReload?: boolean
+  nativeSidebar?: boolean
+  sidebarWidth?: number
+  sidebarConfig?: SidebarConfig
+}

package/dist/dev-server/port-utils.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Check if a port is available by attempting to bind to it
+ * Checks both IPv4 and IPv6
+ */
+export declare function isPortAvailable(port: number): Promise<boolean>;
+/**
+ * Find an available port starting from the given port
+ * @param startPort - The port to start searching from
+ * @param maxAttempts - Maximum number of ports to try (default: 20)
+ * @throws Error if no available port is found within maxAttempts
+ */
+export declare function findAvailablePort(startPort: number, maxAttempts?: any): Promise<number>;
+/**
+ * Find an available port within a specific range
+ */
+export declare function findAvailablePortInRange(range: PortRange): Promise<number>;
+/**
+ * Default port for the dev server
+ */
+export declare const DEFAULT_PORT: 3000;
+/**
+ * Port range configuration
+ */
+export declare interface PortRange {
+  start: number
+  end: number
+}

package/dist/dev-server/terminal-colors.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Colorize a string with the specified color
+ */
+export declare function colorize(text: string, color: ColorName): string;
+/**
+ * Create a success message (green)
+ */
+export declare function success(text: string): string;
+/**
+ * Create a warning message (yellow)
+ */
+export declare function warning(text: string): string;
+/**
+ * Create an error message (red)
+ */
+export declare function error(text: string): string;
+/**
+ * Create an info message (cyan)
+ */
+export declare function info(text: string): string;
+/**
+ * Create a dim/muted message (gray)
+ */
+export declare function dim(text: string): string;
+/**
+ * ANSI color codes for terminal output
+ * Provides consistent coloring for CLI messages
+ */
+export declare const colors: {
+  // Reset
+  reset: '\x1B[0m';
+  // Text styles
+  bright: '\x1B[1m';
+  dim: '\x1B[2m';
+  underscore: '\x1B[4m';
+  blink: '\x1B[5m';
+  reverse: '\x1B[7m';
+  hidden: '\x1B[8m';
+  // Foreground colors
+  black: '\x1B[30m';
+  red: '\x1B[31m';
+  green: '\x1B[32m';
+  yellow: '\x1B[33m';
+  blue: '\x1B[34m';
+  magenta: '\x1B[35m';
+  cyan: '\x1B[36m';
+  white: '\x1B[37m';
+  gray: '\x1B[90m';
+  // Background colors
+  bgBlack: '\x1B[40m';
+  bgRed: '\x1B[41m';
+  bgGreen: '\x1B[42m';
+  bgYellow: '\x1B[43m';
+  bgBlue: '\x1B[44m';
+  bgMagenta: '\x1B[45m';
+  bgCyan: '\x1B[46m';
+  bgWhite: '\x1B[47m';
+  bgGray: '\x1B[100m'
+};
+export type ColorName = keyof typeof colors

package/dist/dev-server/theme-selector.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Theme Selector Module
+ * Provides UI components for syntax highlighting theme selection
+ */
+/**
+ * Generate theme selector CSS styles
+ * Used in markdown preview pages for syntax highlighting theme selection
+ */
+export declare function getThemeSelectorStyles(): string;
+/**
+ * Generate theme selector HTML with dropdown
+ * @param themeOptions - HTML string of option elements
+ */
+export declare function getThemeSelectorHtml(themeOptions: string): string;
+/**
+ * Generate theme change JavaScript
+ * Handles toggling dark mode based on theme selection
+ */
+export declare function getThemeSelectorScript(): string;
+/**
+ * Generate frontmatter display HTML
+ * @param data - Frontmatter key-value pairs
+ */
+export declare function getFrontmatterHtml(data: Record<string, unknown>): string;
+/**
+ * Check if a theme name indicates a dark theme
+ */
+export declare function isDarkTheme(themeName: string): boolean;
+/**
+ * List of dark theme keywords for theme detection
+ */
+export declare const DARK_THEME_KEYWORDS: readonly ['dark', 'night', 'monokai', 'dracula', 'nord', 'material', 'ayu', 'one-dark', 'tokyo', 'gruvbox', 'solarized-dark'];

package/dist/dev-server/types.d.ts

@@ -0,0 +1,92 @@
+import type { SyntaxHighlightTheme, StxOptions } from '../types';
+/**
+ * Get MIME type for a file extension
+ */
+export declare function getMimeType(ext: string): string;
+/**
+ * MIME type mapping
+ */
+export declare const MIME_TYPES: {
+  '.html': 'text/html';
+  '.css': 'text/css';
+  '.js': 'application/javascript';
+  '.mjs': 'application/javascript';
+  '.json': 'application/json';
+  '.png': 'image/png';
+  '.jpg': 'image/jpeg';
+  '.jpeg': 'image/jpeg';
+  '.gif': 'image/gif';
+  '.svg': 'image/svg+xml';
+  '.ico': 'image/x-icon';
+  '.webp': 'image/webp';
+  '.woff': 'font/woff';
+  '.woff2': 'font/woff2';
+  '.ttf': 'font/ttf';
+  '.eot': 'application/vnd.ms-fontobject';
+  '.otf': 'font/otf';
+  '.mp4': 'video/mp4';
+  '.webm': 'video/webm';
+  '.mp3': 'audio/mpeg';
+  '.wav': 'audio/wav';
+  '.pdf': 'application/pdf';
+  '.zip': 'application/zip';
+  '.xml': 'application/xml';
+  '.txt': 'text/plain';
+  '.md': 'text/markdown';
+  '.stx': 'text/html'
+};
+/**
+ * Default dev server options
+ */
+export declare const DEFAULT_DEV_OPTIONS: Required<Omit<DevServerOptions, 'stxOptions' | 'markdown'>>;
+/**
+ * Markdown rendering options
+ */
+export declare interface MarkdownOptions {
+  syntaxHighlighting?: {
+    /** Enable server-side syntax highlighting */
+    serverSide?: boolean
+    /** Enable syntax highlighting (default: true) */
+    enabled?: boolean
+    /** Default theme for code blocks */
+    defaultTheme?: SyntaxHighlightTheme
+    /** Highlight code blocks with unknown languages */
+    highlightUnknownLanguages?: boolean
+    /** Additional themes to make available */
+    additionalThemes?: SyntaxHighlightTheme[]
+  }
+}
+/**
+ * Dev server configuration options
+ */
+export declare interface DevServerOptions {
+  port?: number
+  watch?: boolean
+  native?: boolean
+  stxOptions?: StxOptions
+  markdown?: MarkdownOptions
+  cache?: boolean
+  hotReload?: boolean
+  hmrPort?: number
+}
+/**
+ * Server instance returned by serve functions
+ */
+export declare interface ServerInstance {
+  stop: () => void
+  url: string
+  port: number
+  hmrPort?: number
+}
+/**
+ * File watcher event types
+ */
+export type WatchEventType = 'change' | 'rename' | 'delete' | 'add'
+/**
+ * File watcher callback
+ */
+export type WatchCallback = (eventType: WatchEventType, filename: string) => void
+/**
+ * Route handler function
+ */
+export type RouteHandler = (request: Request) => Promise<Response> | Response

package/dist/dev-server.d.ts

@@ -1,8 +1,27 @@
+import {  } from './dev-server/index';
+import {  } from './hot-reload';
+import {  } from './route-middleware';
 import type { SyntaxHighlightTheme } from './types';
 // Build and serve a specific stx file
 export declare function serveStxFile(filePath: string, options?: DevServerOptions): Promise<boolean>;
 // Build and serve multiple files (stx and Markdown)
 export declare function serveMultipleStxFiles(filePaths: string[], options?: DevServerOptions): Promise<boolean>;
+/**
+ * Serve a full STX application with file-based routing
+ *
+ * Directory structure:
+ *   pages/
+ *     index.stx       → /
+ *     about.stx       → /about
+ *     chat/
+ *       index.stx     → /chat
+ *       [id].stx      → /chat/:id (dynamic route)
+ *   components/       → Shared components
+ *   public/           → Static assets
+ */
+export declare function serveApp(appDir?: string, options?: DevServerOptions): Promise<boolean>;
+// NOTE: Crosswind CSS, theme selector, port utils, and native window functions
+// have been extracted to dev-server/ modules for better organization
 // Define types for dev server options
 export declare interface DevServerOptions {
   port?: number
@@ -19,4 +38,6 @@ export declare interface DevServerOptions {
     }
   }
   cache?: boolean
+  hotReload?: boolean
+  hmrPort?: number
 }