arcway 0.1.0

package/client/ui/tooltip.stories.jsx

@@ -0,0 +1,32 @@
+import React from 'react';
+import { expect, within } from 'storybook/test';
+import { Tooltip, TooltipTrigger, TooltipContent, TooltipProvider } from './tooltip.jsx';
+import { Button } from './button.jsx';
+const meta = {
+  title: 'UI/Tooltip',
+  component: Tooltip,
+  decorators: [
+    (Story) => (
+      <TooltipProvider>
+        <Story />
+      </TooltipProvider>
+    ),
+  ],
+};
+var stdin_default = meta;
+const Default = {
+  render: () => (
+    <Tooltip>
+      <TooltipTrigger asChild>
+        <Button>Hover me</Button>
+      </TooltipTrigger>
+      <TooltipContent>Tooltip text</TooltipContent>
+    </Tooltip>
+  ),
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const trigger = canvas.getByRole('button', { name: 'Hover me' });
+    await expect(trigger).toBeInTheDocument();
+  },
+};
+export { Default, stdin_default as default };

package/client/ui/use-transition.js

@@ -0,0 +1,35 @@
+import { useState, useEffect, useRef, useCallback } from 'react';
+function useTransition(open, duration = 150) {
+  const [mounted, setMounted] = useState(open);
+  const [stage, setStage] = useState(open ? 'idle' : 'exit');
+  const timerRef = useRef(void 0);
+  const rafRef = useRef(void 0);
+  useEffect(() => {
+    if (open) {
+      setMounted(true);
+      setStage('enter');
+      rafRef.current = requestAnimationFrame(() => {
+        rafRef.current = requestAnimationFrame(() => {
+          setStage('idle');
+        });
+      });
+    } else if (mounted) {
+      setStage('exit');
+      clearTimeout(timerRef.current);
+      timerRef.current = setTimeout(() => {
+        setMounted(false);
+      }, duration);
+    }
+    return () => {
+      clearTimeout(timerRef.current);
+      if (rafRef.current) cancelAnimationFrame(rafRef.current);
+    };
+  }, [open]);
+  const onAnimationEnd = useCallback(() => {
+    if (!open) {
+      setMounted(false);
+    }
+  }, [open]);
+  return { mounted, stage, onAnimationEnd };
+}
+export { useTransition };

package/client/ws.js

@@ -0,0 +1,132 @@
+import { io } from 'socket.io-client';
+
+class WsManager {
+  socket = null;
+  socketId = null;
+  subscriptions = new Map();
+  pendingRequests = new Map();
+  messageId = 0;
+  requestTimeout;
+  url;
+  wsPath;
+
+  constructor(options) {
+    this.url = options.url;
+    this.requestTimeout = options.requestTimeout ?? 3e4;
+
+    try {
+      this.wsPath = new URL(this.url).pathname || '/ws';
+    } catch {
+      this.wsPath = '/ws';
+    }
+  }
+
+  isConnected() {
+    return !!this.socket?.connected && this.socketId !== null;
+  }
+
+  connect() {
+    if (this.socket) return;
+
+    try {
+      const parsed = new URL(this.url);
+      this.socket = io(parsed.origin, {
+        path: this.wsPath,
+        transports: ['websocket'],
+        withCredentials: true,
+      });
+    } catch {
+      return;
+    }
+
+    this.socket.on('msg', (data) => {
+      // Handle initial connection handshake
+      if (data.path === this.wsPath && data.data?.socketId) {
+        this.socketId = data.data.socketId;
+        for (const path of this.subscriptions.keys()) {
+          this.socket.emit('msg', { path, method: 'SUBSCRIBE' });
+        }
+        return;
+      }
+
+      // Resolve pending request-response
+      if (data.id) {
+        const pending = this.pendingRequests.get(data.id);
+        if (pending) {
+          clearTimeout(pending.timeout);
+          this.pendingRequests.delete(data.id);
+          pending.resolve(data);
+        }
+      }
+
+      // Notify subscription listeners
+      if (data.path) {
+        const callbacks = this.subscriptions.get(data.path);
+        if (callbacks) {
+          for (const cb of callbacks) cb(data);
+        }
+      }
+    });
+
+    this.socket.on('disconnect', () => {
+      this.socketId = null;
+      for (const [id, pending] of this.pendingRequests) {
+        clearTimeout(pending.timeout);
+        pending.reject(new Error('WebSocket connection closed'));
+        this.pendingRequests.delete(id);
+      }
+    });
+  }
+
+  disconnect() {
+    if (this.socket) {
+      this.socket.disconnect();
+      this.socket = null;
+    }
+    this.socketId = null;
+  }
+
+  subscribe(path, callback) {
+    let callbacks = this.subscriptions.get(path);
+    const isNew = !callbacks;
+
+    if (!callbacks) {
+      callbacks = new Set();
+      this.subscriptions.set(path, callbacks);
+    }
+    callbacks.add(callback);
+
+    if (isNew && this.isConnected()) {
+      this.socket.emit('msg', { path, method: 'SUBSCRIBE' });
+    }
+
+    return () => {
+      callbacks.delete(callback);
+      if (callbacks.size === 0) {
+        this.subscriptions.delete(path);
+        if (this.isConnected()) {
+          this.socket.emit('msg', { path, method: 'UNSUBSCRIBE' });
+        }
+      }
+    };
+  }
+
+  async request(path, method, body) {
+    if (!this.isConnected()) {
+      throw new Error('WebSocket not connected');
+    }
+
+    const id = String(++this.messageId);
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        this.pendingRequests.delete(id);
+        reject(new Error(`WebSocket request timeout: ${method} ${path}`));
+      }, this.requestTimeout);
+
+      this.pendingRequests.set(id, { resolve, reject, timeout });
+      this.socket.emit('msg', { path, method, body, id });
+    });
+  }
+}
+
+export { WsManager };

package/package.json

@@ -0,0 +1,134 @@
+{
+  "name": "arcway",
+  "version": "0.1.0",
+  "description": "A convention-based framework for building modular monoliths with strict domain boundaries.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./server/index.js",
+  "files": [
+    "server/",
+    "client/",
+    "LICENSE",
+    "README.md"
+  ],
+  "bin": {
+    "arcway": "./server/bin/solo.js"
+  },
+  "imports": {
+    "#server/*": "./server/*",
+    "#client/*": "./client/*"
+  },
+  "exports": {
+    ".": "./server/index.js",
+    "./internals": "./server/internals.js",
+    "./lib/vault": "./server/lib/vault/index.js",
+    "./lib/client": "./client/index.js",
+    "./ui": "./client/ui/index.js",
+    "./middlewares": "./server/middlewares/index.js",
+    "./ui/theme.css": "./client/ui/theme.css",
+    "./ui/style-mira.css": "./client/ui/style-mira.css"
+  },
+  "scripts": {
+    "test": "vitest run --project=unit",
+    "test:storybook": "TMPDIR=~/tmp PLAYWRIGHT_BROWSERS_PATH=~/.cache/playwright vitest run --project=storybook",
+    "test:all": "TMPDIR=~/tmp PLAYWRIGHT_BROWSERS_PATH=~/.cache/playwright vitest run",
+    "format": "prettier --write 'server/**/*.js' 'client/**/*.js' 'tests/**/*.js'",
+    "format:check": "prettier --check 'server/**/*.js' 'client/**/*.js' 'tests/**/*.js'",
+    "lint": "eslint server/ client/ tests/",
+    "lint:fix": "eslint server/ client/ tests/ --fix",
+    "storybook": "storybook dev -p 6006",
+    "build-storybook": "storybook build"
+  },
+  "dependencies": {
+    "@aws-sdk/client-s3": "^3.987.0",
+    "@babel/core": "^7.29.0",
+    "@base-ui/react": "^1.2.0",
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "@tailwindcss/postcss": "^4.1.18",
+    "arktype": "^2.1.29",
+    "bcryptjs": "^3.0.3",
+    "better-sqlite3": "^12.6.2",
+    "cache-manager": "^7.2.8",
+    "chokidar": "^5.0.0",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "cmdk": "^1.1.1",
+    "commander": "^14.0.3",
+    "cookie": "^1.1.1",
+    "cron-parser": "^5.5.0",
+    "dataloader": "^2.2.3",
+    "dotenv": "^17.2.4",
+    "embla-carousel-react": "^8.6.0",
+    "esbuild": "^0.27.3",
+    "glob": "^11.0.0",
+    "graphql": "^16.12.0",
+    "graphql-ws": "^6.0.7",
+    "graphql-yoga": "^5.18.0",
+    "imapflow": "^1.2.9",
+    "input-otp": "^1.4.2",
+    "ioredis": "^5.9.2",
+    "ioredis-mock": "^8.13.1",
+    "iron-session": "^8.0.4",
+    "jose": "^6.1.3",
+    "knex": "^3.1.0",
+    "lucide-react": "^0.564.0",
+    "mailparser": "^3.9.3",
+    "nanoid": "^5.1.6",
+    "nodemailer": "^8.0.1",
+    "p-limit": "^7.3.0",
+    "pg": "^8.13.0",
+    "pino": "^10.3.1",
+    "pino-pretty": "^13.1.3",
+    "postcss": "^8.5.6",
+    "radix-ui": "^1.4.3",
+    "rate-limiter-flexible": "^9.1.1",
+    "react-day-picker": "^9.13.2",
+    "react-refresh": "^0.18.0",
+    "react-resizable-panels": "^4.6.4",
+    "recharts": "^3.7.0",
+    "socket.io": "^4.8.3",
+    "socket.io-client": "^4.8.3",
+    "sonner": "^2.0.7",
+    "swr": "^2.3.3",
+    "tailwind-merge": "^3.4.1",
+    "tailwindcss": "^4.1.18",
+    "tailwindcss-animate": "^1.0.7",
+    "vaul": "^1.1.2",
+    "ws": "^8.19.0",
+    "zod": "^3.24.0"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "react-dom": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@chromatic-com/storybook": "^5.0.1",
+    "@storybook/addon-a11y": "^10.2.8",
+    "@storybook/addon-docs": "^10.2.8",
+    "@storybook/addon-onboarding": "^10.2.8",
+    "@storybook/addon-vitest": "^10.2.8",
+    "@storybook/react-vite": "^10.2.8",
+    "@tailwindcss/vite": "^4.1.18",
+    "@testing-library/react": "^16.3.2",
+    "@vitest/browser-playwright": "4.0.18",
+    "@vitest/coverage-v8": "^4.0.18",
+    "eslint": "^9.39.2",
+    "eslint-plugin-storybook": "^10.2.8",
+    "happy-dom": "^20.6.1",
+    "jsdom": "^28.0.0",
+    "playwright": "^1.58.2",
+    "prettier": "^3.8.1",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "storybook": "^10.2.8",
+    "vitest": "^4.0.18"
+  }
+}

package/server/bin/cli.js

@@ -0,0 +1,42 @@
+import { Command } from 'commander';
+import { createRequire } from 'node:module';
+import registerDev from './commands/dev.js';
+import registerStart from './commands/start.js';
+import registerMcp from './commands/mcp.js';
+import registerBuild from './commands/build.js';
+import registerSeed from './commands/seed.js';
+import registerDocs from './commands/docs.js';
+import registerTest from './commands/test.js';
+import registerLint from './commands/lint.js';
+import registerGraphQLSchema from './commands/graphql-schema.js';
+import registerSchema from './commands/schema.js';
+import registerMigrate from './commands/migrate.js';
+
+function getPackageVersion() {
+  try {
+    const require2 = createRequire(import.meta.url);
+    const pkg = require2('../../package.json');
+    return pkg.version ?? '0.0.0';
+  } catch {
+    return '0.0.0';
+  }
+}
+
+function createProgram() {
+  const program = new Command();
+  program.name('arcway').description('Arcway framework CLI').version(getPackageVersion());
+  registerDev(program);
+  registerMcp(program);
+  registerStart(program);
+  registerBuild(program);
+  registerSeed(program);
+  registerDocs(program);
+  registerTest(program);
+  registerLint(program);
+  registerGraphQLSchema(program);
+  registerSchema(program);
+  registerMigrate(program);
+  return program;
+}
+
+export { createProgram };

package/server/bin/commands/build.js

@@ -0,0 +1,23 @@
+import { build } from '#server/build.js';
+
+async function runBuild() {
+  const rootDir = process.cwd();
+  try {
+    console.log('Building pages for production...');
+    const result = await build({ rootDir });
+    if (result.pages) {
+      console.log('Pages build complete.');
+    } else {
+      console.log('No pages to build.');
+    }
+  } catch (err) {
+    console.error('Build failed:', err instanceof Error ? err.message : err);
+    process.exit(1);
+  }
+}
+
+function register(program) {
+  program.command('build').description('Build pages for production').action(runBuild);
+}
+
+export default register;

package/server/bin/commands/dev.js

@@ -0,0 +1,57 @@
+import path from 'node:path';
+import { startServer } from './start.js';
+import { startWatcher } from '#server/watcher.js';
+
+async function runDev() {
+  const rootDir = process.cwd();
+  let app = await startServer('development');
+  let restarting = false;
+
+  const stopWatcher = startWatcher({
+    rootDir,
+    onChange: async (filePath) => {
+      if (restarting) return;
+      const relative = path.relative(rootDir, filePath).replace(/\\/g, '/');
+      if (relative.startsWith('api/')) return;
+      restarting = true;
+      app.logger.info(`File changed: ${relative}, restarting...`);
+      try {
+        await app.shutdown();
+      } catch {
+        // Shutdown errors during restart are non-fatal
+      }
+      try {
+        app = await startServer('development');
+      } catch (err) {
+        app.logger.error('Restart failed', { error: String(err) });
+        app.logger.info('Watching for changes to retry...');
+      }
+      restarting = false;
+    },
+  });
+
+  // Override the shutdown handlers to also stop the watcher
+  process.removeAllListeners('SIGINT');
+  process.removeAllListeners('SIGTERM');
+
+  let shuttingDown = false;
+  const shutdown = async () => {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    stopWatcher();
+    await app.shutdown();
+    process.exit(0);
+  };
+
+  process.on('SIGINT', shutdown);
+  process.on('SIGTERM', shutdown);
+}
+
+function register(program) {
+  program
+    .command('dev')
+    .description('Start development server with file watching and auto-restart')
+    .action(runDev);
+}
+
+export default register;

package/server/bin/commands/docs.js

@@ -0,0 +1,30 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { discoverRoutes } from '#server/router/routes.js';
+import { generateOpenAPISpec } from '#server/docs/openapi.js';
+async function runDocs(outFile) {
+  const rootDir = process.cwd();
+  try {
+    console.log('Discovering routes...');
+    const routes = await discoverRoutes(path.join(rootDir, 'api'));
+    console.log(`Found ${routes.length} route(s)`);
+    const spec = generateOpenAPISpec(routes, {
+      title: 'Arcway API',
+      version: '1.0.0',
+    });
+    const json = JSON.stringify(spec, null, 2);
+    await fs.writeFile(outFile, json, 'utf-8');
+    console.log(`OpenAPI spec written to ${outFile}`);
+  } catch (err) {
+    console.error('Docs generation failed:', err instanceof Error ? err.message : err);
+    process.exit(1);
+  }
+}
+function register(program) {
+  program
+    .command('docs')
+    .description('Generate OpenAPI specification from discovered routes')
+    .argument('[outFile]', 'output file path', 'openapi.json')
+    .action(runDocs);
+}
+export default register;

package/server/bin/commands/graphql-schema.js

@@ -0,0 +1,32 @@
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { discoverGraphQL } from '#server/graphql/discovery.js';
+import { mergeGraphQLSchemas } from '#server/graphql/merge.js';
+async function runGraphQLSchema(outFile) {
+  const rootDir = process.cwd();
+  try {
+    console.log('Discovering GraphQL modules...');
+    const graphqlEntries = await discoverGraphQL(rootDir);
+    if (graphqlEntries.length === 0) {
+      console.log('No GraphQL modules found in graphql/ directory.');
+      return;
+    }
+    const mergedSDL = mergeGraphQLSchemas(graphqlEntries);
+    const outputPath = path.resolve(rootDir, outFile);
+    await fs.mkdir(path.dirname(outputPath), { recursive: true });
+    await fs.writeFile(outputPath, mergedSDL, 'utf-8');
+    console.log(`
+GraphQL schema written to ${path.relative(rootDir, outputPath)}`);
+  } catch (err) {
+    console.error('GraphQL schema export failed:', err instanceof Error ? err.message : err);
+    process.exit(1);
+  }
+}
+function register(program) {
+  program
+    .command('graphql:schema')
+    .description('Export merged GraphQL SDL schema')
+    .argument('[outFile]', 'output file path', 'schema.graphql')
+    .action(runGraphQLSchema);
+}
+export default register;

package/server/bin/commands/lint.js

@@ -0,0 +1,35 @@
+import { checkServerClientBoundaries } from '#server/lint/boundaries.js';
+async function runLint() {
+  const rootDir = process.cwd();
+  let hasViolations = false;
+  try {
+    console.log('Checking server/client boundaries...');
+    const scResult = await checkServerClientBoundaries(rootDir);
+    console.log(`  Files scanned: ${scResult.filesScanned}`);
+    if (scResult.violations.length === 0) {
+      console.log('  No server/client boundary violations found.');
+    } else {
+      hasViolations = true;
+      console.log(`
+  ${scResult.violations.length} server/client boundary violation(s) found:
+`);
+      for (const v of scResult.violations) {
+        console.log(`    ${v.file}:${v.line}`);
+        console.log(`      ${v.message}`);
+        console.log(`      Import: ${v.importPath}`);
+        console.log('');
+      }
+    }
+    if (hasViolations) {
+      process.exit(1);
+    }
+    console.log('\nAll boundary checks passed.');
+  } catch (err) {
+    console.error('Lint failed:', err instanceof Error ? err.message : err);
+    process.exit(1);
+  }
+}
+function register(program) {
+  program.command('lint').description('Check server/client boundary violations').action(runLint);
+}
+export default register;

package/server/bin/commands/mcp.js

@@ -0,0 +1,26 @@
+import { makeConfig } from '#server/config/loader.js';
+import { loadEnvFiles } from '#server/env.js';
+async function runMcp() {
+  const rootDir = process.cwd();
+  loadEnvFiles(rootDir, 'development');
+  try {
+    const config = await makeConfig(rootDir);
+    if (config.mcp?.enabled === false) {
+      process.stderr.write('MCP is disabled in arcway.config.js (mcp.enabled = false)\n');
+      process.exit(1);
+    }
+    const { startMcpServer } = await import('../../mcp/server.js');
+    await startMcpServer(rootDir);
+  } catch (err) {
+    process.stderr.write(`MCP server failed: ${err instanceof Error ? err.message : err}
+`);
+    process.exit(1);
+  }
+}
+function register(program) {
+  program
+    .command('mcp')
+    .description('Start MCP (Model Context Protocol) debug server over stdio for AI coding agents')
+    .action(runMcp);
+}
+export default register;

package/server/bin/commands/migrate.js

@@ -0,0 +1,82 @@
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { makeConfig } from '#server/config/loader.js';
+import { loadEnvFiles } from '#server/env.js';
+import { createDB } from '#server/db/index.js';
+async function runMigrateMake(name) {
+  const rootDir = process.cwd();
+  try {
+    const migrationsDir = path.resolve(rootDir, 'migrations');
+    await fs.mkdir(migrationsDir, { recursive: true });
+    const now = new Date();
+    const timestamp = [
+      now.getFullYear(),
+      String(now.getMonth() + 1).padStart(2, '0'),
+      String(now.getDate()).padStart(2, '0'),
+      String(now.getHours()).padStart(2, '0'),
+      String(now.getMinutes()).padStart(2, '0'),
+    ].join('');
+    const fileName = `${timestamp}-${name}.js`;
+    const filePath = path.join(migrationsDir, fileName);
+    const template = `export async function up(knex) {
+  // TODO: implement migration
+}
+
+export async function down(knex) {
+  // TODO: implement rollback
+}
+`;
+    await fs.writeFile(filePath, template, 'utf-8');
+    console.log(`Created migration: ${path.relative(rootDir, filePath)}`);
+  } catch (err) {
+    console.error('Failed to create migration:', err instanceof Error ? err.message : err);
+    process.exit(1);
+  }
+}
+async function runMigrateRun() {
+  const rootDir = process.cwd();
+  const mode = process.env.NODE_ENV === 'production' ? 'production' : 'development';
+  loadEnvFiles(rootDir, mode);
+  try {
+    const config = await makeConfig(rootDir);
+    const db = await createDB(config.database);
+    await db.runMigrations();
+    await db.destroy();
+  } catch (err) {
+    console.error('Migration failed:', err instanceof Error ? err.message : err);
+    process.exit(1);
+  }
+}
+async function runMigrateRollback() {
+  const rootDir = process.cwd();
+  const mode = process.env.NODE_ENV === 'production' ? 'production' : 'development';
+  loadEnvFiles(rootDir, mode);
+  try {
+    const config = await makeConfig(rootDir);
+    const db = await createDB(config.database);
+    const { batch, log } = await db.runRollback();
+    if (log.length > 0) {
+      console.log(`Rolled back batch ${batch}: ${log.join(', ')}`);
+    } else {
+      console.log('Nothing to rollback.');
+    }
+    await db.destroy();
+  } catch (err) {
+    console.error('Rollback failed:', err instanceof Error ? err.message : err);
+    process.exit(1);
+  }
+}
+function register(program) {
+  const migrate = program.command('migrate').description('Database migration commands');
+  migrate
+    .command('make')
+    .description('Create a new migration file')
+    .argument('<name>', 'migration name (e.g. create_users)')
+    .action(runMigrateMake);
+  migrate.command('run').description('Run pending migrations').action(runMigrateRun);
+  migrate
+    .command('rollback')
+    .description('Rollback the last batch of migrations')
+    .action(runMigrateRollback);
+}
+export default register;