cumstack 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Lavion
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,3 @@
+# cumstack
+
+A lightweight reactive framework with signals, routing, and i18n support. Just a package for modern web applications with server-side rendering and client-side hydration. Made this since why not.

package/cli/build.js

@@ -0,0 +1,19 @@
+/**
+ * cumstack Build Command
+ * builds application for production
+ */
+import { buildApp } from './builder.js';
+
+const appRoot = process.cwd();
+
+export default async function build() {
+  console.log('[cumstack] Building cumstack application for production...\n');
+
+  try {
+    await buildApp(appRoot, false);
+    console.log('[cumstack] Build complete!');
+  } catch (error) {
+    console.error('[cumstack] Build failed:', error.message);
+    throw error;
+  }
+}

package/cli/builder.js

@@ -0,0 +1,172 @@
+#!/usr/bin/env bun
+
+/**
+ * cumstack Build Engine
+ * Core build logic for cumstack applications
+ */
+
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { existsSync } from 'fs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+// Extension resolution hierarchy: jsx > tsx > js > ts
+const EXTENSION_HIERARCHY = ['.jsx', '.tsx', '.js', '.ts'];
+
+/**
+ * Resolve file path with optional extension
+ * Tries exact path first, then extensions in hierarchy order
+ */
+function resolveWithExtension(basePath) {
+  const ext = path.extname(basePath);
+  if (['.js', '.jsx', '.ts', '.tsx'].includes(ext) && existsSync(basePath)) return basePath;
+  if (existsSync(basePath)) return basePath;
+  for (const extension of EXTENSION_HIERARCHY) {
+    const pathWithExt = basePath + extension;
+    if (existsSync(pathWithExt)) return pathWithExt;
+  }
+  return basePath;
+}
+
+export async function buildApp(appRoot, isDev = false, buildTimestamp = Date.now()) {
+  const outDir = isDev ? 'dist/dev' : 'dist/live';
+  console.log(`[cumstack] Building cumstack app for ${isDev ? 'development' : 'production'}...`);
+  console.log(`[cumstack] Output: ${outDir}`);
+  globalThis.__BUILD_TIMESTAMP__ = buildTimestamp;
+  let serverBuild;
+  try {
+    serverBuild = await Bun.build({
+      entrypoints: [path.join(appRoot, 'src/entry.server.jsx')],
+      outdir: path.join(appRoot, outDir, 'server'),
+      target: 'bun',
+      format: 'esm',
+      minify: !isDev,
+      sourcemap: isDev ? 'inline' : 'external',
+      external: ['hono', 'cloudflare:*'],
+      naming: '[dir]/main.server.js',
+      jsx: {
+        runtime: 'automatic',
+        importSource: 'hono/jsx',
+      },
+      // resolve @cumstack imports to framework package
+      plugins: [
+        {
+          name: 'resolve-cumstack',
+          setup(build) {
+            build.onResolve({ filter: /^@cumstack\/app/ }, (args) => {
+              let subpath = args.path.replace('@cumstack/app', '');
+              if (subpath === '/server') subpath = '/app/server/index.js';
+              else if (subpath === '/client') subpath = '/app/client/index.js';
+              else if (subpath === '/client/Twink') subpath = '/app/client/Twink.js';
+              else if (subpath === '/shared/i18n') subpath = '/app/shared/i18n.js';
+              else if (subpath === '/shared/reactivity') subpath = '/app/shared/reactivity.js';
+              else if (subpath === '/shared/router') subpath = '/app/shared/router.js';
+              else if (subpath === '/shared/utils') subpath = '/app/shared/utils.js';
+              else if (subpath === '/shared/language-codes') subpath = '/app/shared/language-codes.js';
+              else if (!subpath.endsWith('.js')) subpath += '.js';
+              return {
+                path: path.join(__dirname, '..', 'src', subpath),
+                external: false,
+              };
+            });
+            // resolve ~ alias to src directory
+            build.onResolve({ filter: /^~\// }, (args) => {
+              const subpath = args.path.replace('~', 'src');
+              const basePath = path.join(appRoot, subpath);
+              const resolvedPath = resolveWithExtension(basePath);
+              return {
+                path: resolvedPath,
+                external: false,
+              };
+            });
+          },
+        },
+      ],
+    });
+  } catch (error) {
+    console.error('[cumstack] Server build threw an exception:');
+    console.error(error);
+    throw new Error(`Server build failed: ${error.message}`);
+  }
+  if (!serverBuild.success) {
+    console.error('[cumstack] Server build failed:');
+    console.error('[cumstack] Build logs count:', serverBuild.logs.length);
+    for (const log of serverBuild.logs) console.error(`  [${log.level}] ${log.message}`);
+    throw new Error('Server build failed');
+  }
+
+  // build client entry
+  const clientBuild = await Bun.build({
+    entrypoints: [path.join(appRoot, 'src/entry.client.jsx')],
+    outdir: path.join(appRoot, outDir, 'client'),
+    target: 'browser',
+    format: 'esm',
+    minify: !isDev,
+    sourcemap: isDev ? 'inline' : 'external',
+    naming: '[dir]/main.client.js',
+    jsx: {
+      runtime: 'automatic',
+      importSource: 'hono/jsx',
+    },
+    // resolve @cumstack imports to framework package
+    plugins: [
+      {
+        name: 'resolve-cumstack',
+        setup(build) {
+          build.onResolve({ filter: /^@cumstack\/app/ }, (args) => {
+            let subpath = args.path.replace('@cumstack/app', '');
+            if (subpath === '/server') subpath = '/app/server/index.js';
+            else if (subpath === '/client') subpath = '/app/client/index.js';
+            else if (subpath === '/shared/i18n') subpath = '/app/shared/i18n.js';
+            else if (subpath === '/shared/reactivity') subpath = '/app/shared/reactivity.js';
+            else if (subpath === '/shared/router') subpath = '/app/shared/router.js';
+            else if (subpath === '/shared/utils') subpath = '/app/shared/utils.js';
+            else if (subpath === '/shared/language-codes') subpath = '/app/shared/language-codes.js';
+            else if (subpath === '/client/Twink') subpath = '/app/client/Twink.js';
+            else if (!subpath.endsWith('.js')) subpath += '.js';
+            return {
+              path: path.join(__dirname, '..', 'src', subpath),
+              external: false,
+            };
+          });
+          // resolve ~ alias to src directory
+          build.onResolve({ filter: /^~\// }, (args) => {
+            const subpath = args.path.replace('~', 'src');
+            const basePath = path.join(appRoot, subpath);
+            const resolvedPath = resolveWithExtension(basePath);
+            return {
+              path: resolvedPath,
+              external: false,
+            };
+          });
+        },
+      },
+    ],
+  });
+
+  if (!clientBuild.success) {
+    console.error('[cumstack] Client build failed:');
+    for (const log of clientBuild.logs) console.error(`  ${log.level}: ${log.message}`);
+    throw new Error('Client build failed');
+  }
+  // process CSS through PostCSS (tailwindcss)
+  try {
+    const postcss = await import('postcss');
+    const tailwindcss = await import('@tailwindcss/postcss');
+    const cssPath = path.join(appRoot, 'src/main.css');
+    const css = await Bun.file(cssPath).text();
+    const result = await postcss.default([tailwindcss.default({ base: appRoot })]).process(css, {
+      from: cssPath,
+      to: path.join(appRoot, outDir, 'client/main.css'),
+      map: isDev ? { inline: true } : false,
+    });
+    await Bun.write(path.join(appRoot, outDir, 'client/main.css'), result.css);
+    console.log('[cumstack] CSS processed with Tailwind');
+  } catch (error) {
+    console.warn('[cumstack] PostCSS processing failed:', error.message);
+    const cssPath = path.join(appRoot, 'src/main.css');
+    await Bun.write(path.join(appRoot, outDir, 'client/main.css'), await Bun.file(cssPath).text());
+  }
+  console.log('[cumstack] Build complete!');
+}

package/cli/create.js

@@ -0,0 +1,36 @@
+#!/usr/bin/env bun
+
+/**
+ * cumstack Create Command
+ * Creates a new cumstack project from template
+ */
+
+import { existsSync } from 'fs';
+import { mkdir, cp } from 'fs/promises';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+export default async function create() {
+  const projectName = process.argv[3];
+  if (!projectName) {
+    console.error('Error: Please provide a project name');
+    console.log('Usage: cum create <project-name>');
+    process.exit(1);
+  }
+  const targetDir = path.resolve(projectName);
+  if (existsSync(targetDir)) {
+    console.error(`Error: Directory "${projectName}" already exists`);
+    process.exit(1);
+  }
+  console.log(`Creating new cumstack project: ${projectName}`);
+  await mkdir(targetDir, { recursive: true });
+  const templateDir = path.join(__dirname, '../templates/monorepo');
+  await cp(templateDir, targetDir, { recursive: true });
+  console.log(`Project created successfully!`);
+  console.log(`\nNext steps:`);
+  console.log(`  cd ${projectName}`);
+  console.log(`  bun install`);
+  console.log(`  bun run dev`);
+}

package/cli/dev.js

@@ -0,0 +1,109 @@
+/**
+ * cumstack Dev Command
+ * Starts development environment with build, wrangler, and HMR
+ */
+
+import { spawn } from 'child_process';
+import { watch } from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { WebSocketServer } from 'ws';
+import { buildApp } from './builder.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const appRoot = process.cwd();
+const HMR_PORT = 8790;
+const DEBOUNCE_MS = 100;
+
+export default async function dev() {
+  console.log('[cumstack] Starting cumstack development environment');
+  console.log(`[cumstack] App root: ${appRoot}`);
+  console.log('[cumstack] Building application...');
+  await runBuild();
+  // start HMR WebSocket server
+  const wss = new WebSocketServer({ port: HMR_PORT });
+  const clients = new Set();
+  wss.on('connection', (ws) => {
+    clients.add(ws);
+    console.log('[cumstack] HMR Client connected');
+    ws.on('close', () => {
+      clients.delete(ws);
+      console.log('[cumstack] HMR Client disconnected');
+    });
+  });
+  console.log(`[cumstack] HMR WebSocket server running on port ${HMR_PORT}`);
+  // start file watcher
+  let rebuildTimeout;
+  let isRebuilding = false;
+  const triggerRebuild = async (filePath) => {
+    if (rebuildTimeout) clearTimeout(rebuildTimeout);
+    rebuildTimeout = setTimeout(async () => {
+      if (isRebuilding) return;
+      isRebuilding = true;
+      const relativePath = path.relative(appRoot, filePath);
+      console.log(`[cumstack] HMR File changed: ${relativePath}`);
+      console.log('[cumstack] Rebuilding...');
+      try {
+        await runBuild();
+        const ext = path.extname(relativePath);
+        let updateType = 'js-update';
+        if (ext === '.css') {
+          updateType = 'css-update';
+          console.log('[cumstack] Build successful, hot swapping styles...');
+        } else if (['.js', '.jsx'].includes(ext) && relativePath.includes('/client/')) {
+          updateType = 'js-update';
+          console.log('[cumstack] Build successful, hot swapping modules...');
+        } else {
+          updateType = 'server-update';
+          console.log('[cumstack] Build successful, patching DOM...');
+        }
+        clients.forEach((client) => {
+          if (client.readyState === 1) {
+            client.send(
+              JSON.stringify({
+                type: updateType,
+                path: relativePath,
+                timestamp: Date.now(),
+              })
+            );
+          }
+        });
+      } catch (error) {
+        console.error('[cumstack] Build failed:', error.message);
+      } finally {
+        isRebuilding = false;
+      }
+    }, DEBOUNCE_MS);
+  };
+  const srcDir = path.join(appRoot, 'src');
+  watch(srcDir, { recursive: true }, (eventType, filename) => {
+    if (!filename) return;
+    const ext = path.extname(filename);
+    if (['.js', '.jsx', '.ts', '.tsx', '.css', '.json'].includes(ext)) triggerRebuild(path.join(srcDir, filename));
+  });
+  console.log(`[cumstack] HMR Watching ${path.relative(appRoot, srcDir)}/`);
+  console.log('[cumstack] Starting Wrangler dev server...');
+  const wrangler = spawn('wrangler', ['dev', '--env', 'dev'], {
+    cwd: appRoot,
+    stdio: 'inherit',
+    shell: true,
+  });
+  // handle exit
+  wrangler.on('exit', (code) => {
+    console.log('[cumstack] Shutting down cumstack dev server...');
+    wss.close();
+    process.exit(code);
+  });
+  // cleanup
+  process.on('SIGINT', () => {
+    console.log('[cumstack] Shutting down cumstack dev server...');
+    wrangler.kill();
+    wss.close();
+    process.exit(0);
+  });
+}
+// run build process
+async function runBuild() {
+  const timestamp = Date.now();
+  await buildApp(appRoot, true, timestamp);
+}

package/cli/index.js

@@ -0,0 +1,65 @@
+#!/usr/bin/env bun
+
+/**
+ * cumstack CLI
+ * command-line interface for cumstack framework
+ */
+
+const commands = {
+  dev: './dev.js',
+  build: './build.js',
+  create: './create.js',
+};
+
+const colors = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  cyan: '\x1b[36m',
+  green: '\x1b[32m',
+  red: '\x1b[31m',
+  yellow: '\x1b[33m',
+  magenta: '\x1b[35m',
+};
+
+function frameHeader(text) {
+  const lines = text.split('\n').map((line) => line.trim());
+  const maxLength = Math.max(...lines.map((l) => l.length));
+  const top = '╔' + '═'.repeat(maxLength + 2) + '╗';
+  const bottom = '╚' + '═'.repeat(maxLength + 2) + '╝';
+  const framedLines = lines.map((line) => `╟ ${line.padEnd(maxLength, ' ')} ╢`);
+  return [top, ...framedLines, bottom].join('\n');
+}
+
+// usage/help text
+function printUsage(error) {
+  const header = frameHeader('cumstack Framework CLI');
+  console.log(error ? `${colors.red}${header}${colors.reset}` : `${colors.cyan}${header}${colors.reset}`);
+  console.log(`${colors.yellow}Usage:${colors.reset}
+  cum <command> [options]
+
+  ${colors.cyan}Commands:${colors.reset}
+  ${colors.green}  dev${colors.reset}     → Start development server with HMR
+  ${colors.green}  build${colors.reset}   → Build for production
+  ${colors.green}  create${colors.reset}  → Create a new cumstack project
+
+  ${colors.cyan}Examples:${colors.reset}
+  ${colors.green}  cum dev
+  ${colors.green}  cum build
+  ${colors.green}  cum create my-app
+  `);
+
+  process.exit(error ? 1 : 0);
+}
+
+const command = process.argv[2];
+if (!command) printUsage();
+if (!commands[command]) printUsage(`Unknown command "${command}"`);
+try {
+  const commandModule = await import(commands[command]);
+  if (typeof commandModule.default !== 'function') throw new Error(`Command module "${command}" does not export a default function`);
+  await commandModule.default();
+} catch (err) {
+  console.error(`${colors.red}\nFailed to execute "${command}": ${err.message}${colors.reset}`);
+  if (err.stack) console.error(`${colors.red}${err.stack}${colors.reset}`);
+  process.exit(1);
+}

package/index.js

@@ -0,0 +1,22 @@
+/* cumstack Framework main entry point */
+
+// client exports
+export { cowgirl, CowgirlCreampie, configureHydration } from './src/app/client/index.js';
+export { Twink } from './src/app/client/Twink.js';
+
+// server exports
+export { foxgirl, FoxgirlCreampie, Router, Route, Head, Title, Meta, TwinkTag, Script, h, renderToString } from './src/app/server/index.js';
+
+// shared exports
+export {
+  registerTranslations,
+  t,
+  setLanguage,
+  getLanguage,
+  getTranslations,
+  localizeRoute,
+  extractLanguageFromRoute,
+  detectBrowserLanguage,
+} from './src/app/shared/i18n.js';
+
+export { createMoan, onClimax, knotMemo, loadShot, batch, untrack, useLocation } from './src/app/shared/reactivity.js';

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "cumstack",
+  "version": "1.0.0",
+  "description": "A lightweight reactive framework with signals, routing, and i18n",
+  "type": "module",
+  "main": "index.js",
+  "bin": {
+    "cum": "./cli/index.js"
+  },
+  "scripts": {
+    "fmt": "prettier --write ."
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/iLavion/cumstack.git"
+  },
+  "bugs": {
+    "url": "https://github.com/iLavion/cumstack/issues"
+  },
+  "homepage": "https://github.com/iLavion/cumstack#readme",
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "index.js",
+    "src/",
+    "cli/",
+    "templates/"
+  ],
+  "dependencies": {
+    "@tailwindcss/postcss": "^4.1.18",
+    "postcss": "^8.5.6",
+    "ws": "^8.18.3"
+  },
+  "exports": {
+    ".": "./index.js",
+    "./app/client": "./src/app/client/index.js",
+    "./app/server": "./src/app/server/index.js",
+    "./app/shared/i18n": "./src/app/shared/i18n.js",
+    "./app/shared/reactivity": "./src/app/shared/reactivity.js",
+    "./app/shared/router": "./src/app/shared/router.js",
+    "./app/shared/utils": "./src/app/shared/utils.js",
+    "./app/shared/language-codes": "./src/app/shared/language-codes.js",
+    "./client/Twink": "./src/app/client/Twink.js",
+    "./client/components": "./src/app/client/components.js",
+    "./client/hmr": "./src/app/client/hmr.js",
+    "./server/components": "./src/app/server/components.js",
+    "./server/jsx": "./src/app/server/jsx.js",
+    "./server/hono-utils": "./src/app/server/hono-utils.js",
+    "./cli": "./cli/index.js"
+  },
+  "keywords": [
+    "framework",
+    "reactivity",
+    "signals",
+    "router",
+    "i18n"
+  ],
+  "author": {
+    "name": "Lavion <lavion@invalsia.com>",
+    "url": "https://github.com/iLavion"
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "prettier": "^3.7.4"
+  }
+}

package/src/app/client/Twink.js

@@ -0,0 +1,57 @@
+/**
+ * link component - client side
+ */
+
+import { getLanguage } from '../shared/i18n.js';
+
+/**
+ * check if currently in a language-prefixed route
+ * @returns {boolean} True if in a language-prefixed route
+ */
+function isInLanguageRoute() {
+  if (typeof window === 'undefined') return false;
+  return window.location.pathname.match(/^\/[a-z]{2}(?:\/|$)/);
+}
+
+/**
+ * smart link component with automatic language prefix handling
+ * @param {Object} props - Twink properties
+ * @param {string} props.href - Twink URL
+ * @param {string|boolean} [props.locale] - Language code or false to disable prefix
+ * @param {string} [props.prefetch] - Prefetch mode ('hover' or 'visible')
+ * @param {string} [props.access] - Access level for link
+ * @param {boolean} [props.external] - Force external link behavior
+ * @param {*} props.children - Twink content
+ * @returns {Object} Virtual DOM element
+ */
+export function Twink(props) {
+  const { href, locale, prefetch, access, external, children, ...rest } = props;
+  const currentLanguage = getLanguage();
+  const isExternal = external || href.startsWith('http') || href.startsWith('//');
+
+  // check if we're currently in a language-prefixed route
+  // this will be evaluated at render time, so it will update on navigation
+  const inLanguageRoute = isInLanguageRoute();
+
+  // apply locale to internal links only if we're in a language route or locale is explicitly set
+  let finalHref = href;
+  if (!isExternal && (locale || (locale !== false && inLanguageRoute))) {
+    const targetLocale = locale || currentLanguage;
+    if (!href.startsWith(`/${targetLocale}`)) finalHref = `/${targetLocale}${href === '/' ? '' : href}`;
+  }
+
+  const linkProps = {
+    ...rest,
+    href: finalHref,
+    'data-spa-link': !isExternal,
+    ...(prefetch && { 'data-prefetch': prefetch }),
+    ...(access && { 'data-link-access': access }),
+    ...(isExternal && { target: '_blank', rel: 'noopener noreferrer' }),
+  };
+
+  return {
+    type: 'a',
+    props: linkProps,
+    children: Array.isArray(children) ? children : [children],
+  };
+}

package/src/app/client/components.js

@@ -0,0 +1,28 @@
+/**
+ * cumstack Client Components
+ * utilities for component hydration
+ */
+
+/**
+ * initialize all cumstack components on the page
+ * override this in your app to add custom component initialization
+ * @returns {void}
+ */
+export function initComponents() {
+  document.querySelectorAll('button[onclick*="setCount"]').forEach((button) => {
+    let count = 0;
+    const match = button.textContent.match(/Clicks: (\d+)/);
+    if (match) count = parseInt(match[1]);
+    button.removeAttribute('onclick');
+    button.addEventListener('click', () => {
+      count++;
+      button.textContent = `Clicks: ${count}`;
+    });
+  });
+}
+
+// auto-initialize components on DOMContentLoaded
+if (typeof document !== 'undefined') {
+  if (document.readyState === 'loading') document.addEventListener('DOMContentLoaded', initComponents);
+  else initComponents();
+}