tw-framework 1.0.0

package/dist/adapters/index.ts

@@ -0,0 +1,228 @@
+/**
+ * TW Framework — deployment adapters.
+ *
+ * Each adapter is a set of ready-to-copy files for one deployment target:
+ *   - node:       zero-dependency Node 18+ server for a `tw build` output
+ *   - bun:        full production TWServer on Bun
+ *   - docker:     multi-stage Dockerfiles (full + static runtimes)
+ *   - vercel:     vercel.json build config
+ *   - netlify:    netlify.toml build config
+ *   - cloudflare: wrangler.toml + _headers + _redirects (Pages)
+ *   - aws:       S3 + CloudFront deploy script (static) / container path
+ *   - digitalocean: .do/app.yaml App Platform spec
+ *   - render:    render.yaml blueprint
+ *   - railway:   railway.toml container config
+ *   - fly:       fly.toml machine config
+ *   - github-pages: deploy workflow + .nojekyll
+ *   - firebase:  firebase.json hosting config
+ *   - nginx:     nginx.conf server block (self-hosted static)
+ *   - caddy:     Caddyfile (self-hosted static)
+ *
+ * Apps pull them in with `tw adapter <name>` (apps/cli/tw/commands/adapter.ts).
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export interface AdapterInfo {
+  name: string;
+  description: string;
+  /** Files copied into the app root: { source-in-package, destination } */
+  files: Array<{ from: string; to: string }>;
+  /** Printed after generation. */
+  nextSteps: string[];
+}
+
+// Resolve the adapter files directory. In the monorepo this is
+// packages/adapters/tw/; in the published CLI bundle the files are copied
+// next to dist/tw.mjs under dist/adapters/ and the bundle sets
+// globalThis.__TW_BUNDLE_DIR to dist/.
+function resolvePkgDir(): string {
+  const self = dirname(fileURLToPath(import.meta.url));
+  const bundleDir = (globalThis as any).__TW_BUNDLE_DIR as string | undefined;
+  if (bundleDir) {
+    const fromBundle = join(bundleDir, "adapters");
+    if (existsSync(join(fromBundle, "node", "server.mjs"))) return fromBundle;
+  }
+  if (existsSync(join(self, "node", "server.mjs"))) return self;
+  return self;
+}
+
+const PKG_DIR = resolvePkgDir();
+
+export const ADAPTERS: Record<string, AdapterInfo> = {
+  node: {
+    name: "node",
+    description: "Zero-dependency Node 18+ static server for the .tw/ build output (no .twm APIs)",
+    files: [{ from: "node/server.mjs", to: "server.mjs" }],
+    nextSteps: [
+      "tw build",
+      "node server.mjs          # PORT=8000 HOST=0.0.0.0 by default",
+    ],
+  },
+  bun: {
+    name: "bun",
+    description: "Full production TWServer (pages, .twm APIs, middleware) on Bun",
+    files: [{ from: "bun/server.ts", to: "server.ts" }],
+    nextSteps: [
+      "tw build",
+      "bun server.ts             # PORT=3000 by default",
+    ],
+  },
+  docker: {
+    name: "docker",
+    description: "Multi-stage Docker images: Dockerfile (full server incl. .twm APIs) + Dockerfile.static (tiny Node runtime)",
+    files: [
+      { from: "docker/Dockerfile", to: "Dockerfile" },
+      { from: "docker/Dockerfile.static", to: "Dockerfile.static" },
+      { from: "docker/.dockerignore", to: ".dockerignore" },
+      { from: "docker/docker-compose.yml", to: "docker-compose.yml" },
+      { from: "node/server.mjs", to: "server.mjs" },
+    ],
+    nextSteps: [
+      "docker build -t tw-app .",
+      "docker run -p 8000:8000 tw-app",
+      "# or: docker compose up",
+    ],
+  },
+  vercel: {
+    name: "vercel",
+    description: "Vercel build configuration for the .tw/ output",
+    files: [{ from: "vercel/vercel.json", to: "vercel.json" }],
+    nextSteps: [
+      "npx vercel deploy --prod",
+    ],
+  },
+  netlify: {
+    name: "netlify",
+    description: "Netlify build configuration (static + pre-rendered output)",
+    files: [{ from: "netlify/netlify.toml", to: "netlify.toml" }],
+    nextSteps: [
+      "git push (netlify.toml is picked up on connect)",
+      "# or: npx netlify deploy --prod --dir .tw",
+    ],
+  },
+  cloudflare: {
+    name: "cloudflare",
+    description: "Cloudflare Pages config with asset caching and security headers",
+    files: [
+      { from: "cloudflare/wrangler.toml", to: "wrangler.toml" },
+      { from: "cloudflare/_headers", to: "_headers" },
+      { from: "cloudflare/_redirects", to: "_redirects" },
+    ],
+    nextSteps: [
+      "npx wrangler pages deploy .tw",
+      "# or connect the repo in the Cloudflare dashboard",
+    ],
+  },
+  aws: {
+    name: "aws",
+    description: "AWS deployment: S3 + CloudFront sync script for static output (containers for the full server)",
+    files: [
+      { from: "aws/deploy-s3.sh", to: "deploy-s3.sh" },
+      { from: "aws/README.md", to: "AWS-DEPLOY.md" },
+    ],
+    nextSteps: [
+      "tw build",
+      "BUCKET=<your-bucket> DISTRIBUTION_ID=<id> bash deploy-s3.sh",
+      "# full server (APIs): tw adapter docker + App Runner / ECS",
+    ],
+  },
+  digitalocean: {
+    name: "digitalocean",
+    description: "DigitalOcean App Platform spec (static output; containers for the full server)",
+    files: [{ from: "digitalocean/.do/app.yaml", to: ".do/app.yaml" }],
+    nextSteps: [
+      "doctl apps create --spec .do/app.yaml",
+      "# or: Apps -> Create App from repo in the control panel",
+    ],
+  },
+  render: {
+    name: "render",
+    description: "Render blueprint: static site service (docker service for the full server)",
+    files: [{ from: "render/render.yaml", to: "render.yaml" }],
+    nextSteps: [
+      "Dashboard -> New -> Blueprint -> pick this repo",
+    ],
+  },
+  railway: {
+    name: "railway",
+    description: "Railway container config for the full server (PORT honoured)",
+    files: [{ from: "railway/railway.toml", to: "railway.toml" }],
+    nextSteps: [
+      "tw adapter docker        # railway deploys the Dockerfile",
+      "railway up               # or connect the repo in the dashboard",
+    ],
+  },
+  fly: {
+    name: "fly",
+    description: "Fly.io machine config for the full server (needs the Dockerfile)",
+    files: [{ from: "fly/fly.toml", to: "fly.toml" }],
+    nextSteps: [
+      "tw adapter docker        # fly deploys the container image",
+      "fly launch && fly deploy",
+    ],
+  },
+  "github-pages": {
+    name: "github-pages",
+    description: "GitHub Actions workflow deploying the static build to Pages",
+    files: [
+      { from: "github-pages/.github/workflows/deploy.yml", to: ".github/workflows/deploy.yml" },
+      { from: "github-pages/.nojekyll", to: ".nojekyll" },
+    ],
+    nextSteps: [
+      "git add .github/workflows/deploy.yml .nojekyll && git push",
+      "Settings -> Pages -> Source: GitHub Actions",
+    ],
+  },
+  firebase: {
+    name: "firebase",
+    description: "Firebase Hosting config with clean URLs and immutable asset caching",
+    files: [{ from: "firebase/firebase.json", to: "firebase.json" }],
+    nextSteps: [
+      "tw build && firebase deploy",
+    ],
+  },
+  nginx: {
+    name: "nginx",
+    description: "nginx server block for self-hosting the static build",
+    files: [{ from: "nginx/nginx.conf", to: "nginx.conf" }],
+    nextSteps: [
+      "tw build",
+      "cp nginx.conf /etc/nginx/sites-available/tw-app",
+      "# adjust server_name + root, then enable the site",
+    ],
+  },
+  caddy: {
+    name: "caddy",
+    description: "Caddyfile for self-hosting the static build with automatic HTTPS",
+    files: [{ from: "caddy/Caddyfile", to: "Caddyfile" }],
+    nextSteps: [
+      "tw build",
+      "caddy run    # replace example.com with your domain",
+    ],
+  },
+};
+
+/** Copy an adapter's files into an app directory. Returns the written paths. */
+export function generateAdapter(name: string, appDir: string): string[] {
+  const adapter = ADAPTERS[name];
+  if (!adapter) {
+    throw new Error(`Unknown adapter "${name}". Available: ${Object.keys(ADAPTERS).join(", ")}`);
+  }
+  const written: string[] = [];
+  for (const f of adapter.files) {
+    const src = join(PKG_DIR, f.from);
+    if (!existsSync(src)) throw new Error(`Adapter file missing: ${f.from}`);
+    const dest = join(appDir, f.to);
+    mkdirSync(dirname(dest), { recursive: true });
+    writeFileSync(dest, readFileSync(src));
+    written.push(dest);
+  }
+  return written;
+}
+
+export function listAdapters(): AdapterInfo[] {
+  return Object.values(ADAPTERS);
+}

package/dist/adapters/netlify/netlify.toml

@@ -0,0 +1,23 @@
+# Netlify deployment for TW Framework
+# Generated by `tw adapter netlify`.
+
+[build]
+  command = "tw build"
+  publish = ".tw"
+
+# Hashed assets never change — cache them forever.
+[[headers]]
+  for = "/assets/*"
+  [headers.values]
+    Cache-Control = "public, max-age=31536000, immutable"
+
+[[headers]]
+  for = "/js/*"
+  [headers.values]
+    Cache-Control = "public, max-age=31536000, immutable"
+
+# Permanent redirects — extend as needed.
+# [[redirects]]
+#   from = "/old-path"
+#   to = "/new-path"
+#   status = 301

package/dist/adapters/nginx/nginx.conf

@@ -0,0 +1,43 @@
+# nginx server block for TW Framework
+# Generated by `tw adapter nginx`.
+#
+# Place in /etc/nginx/sites-available/tw-app (symlink into sites-enabled)
+# or include from your main nginx.conf. Adjust server_name and the root
+# path to where the project lives on the server.
+#
+# Static output only (pages + pre-rendered routes). For the full server,
+# run `tw serve` (or the node/bun adapter) behind nginx as a proxy:
+#
+#   location / {
+#     proxy_pass http://127.0.0.1:8000;
+#     proxy_set_header Host $host;
+#     proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+#   }
+
+server {
+    listen 80;
+    server_name example.com;
+
+    # The build output — dot-prefix directories are served fine when
+    # the root points directly at them.
+    root /var/www/tw-app/.tw;
+    index index.html;
+
+    # Hashed assets never change — cache them forever.
+    location /assets/ {
+        add_header Cache-Control "public, max-age=31536000, immutable";
+    }
+
+    location /js/ {
+        add_header Cache-Control "public, max-age=31536000, immutable";
+    }
+
+    # Clean URLs: /about serves about/index.html.
+    location / {
+        try_files $uri $uri/ $uri.html =404;
+    }
+
+    # Never serve server-side sources.
+    location ~ /\. { deny all; }
+    location ~ \.(twm|ts|tsx|env)$ { deny all; }
+}

package/dist/adapters/node/server.mjs

@@ -0,0 +1,214 @@
+#!/usr/bin/env node
+/**
+ * TW Framework — Node deployment adapter (zero dependencies).
+ *
+ * Serves a `tw build` output directory (default: .tw/) with plain Node 18+:
+ *   - clean URLs ( /about -> about.html or about/index.html )
+ *   - ETag / 304 responses, Cache-Control for hashed assets
+ *   - gzip for compressible responses (zlib)
+ *   - Range requests (single range) for media files
+ *   - SPA fallback ( index.html ) for unknown routes
+ *   - security: server-only files (.twm/.ts/.env, dotfiles) are NEVER served,
+ *     path traversal is blocked, X-Content-Type-Options: nosniff always set
+ *
+ * Usage:  node server.mjs           (from the app root, after `tw build`)
+ * Env:    PORT (default 8000)  HOST (default 0.0.0.0)  TW_ROOT (default .tw)
+ */
+
+import { createServer } from "node:http";
+import { createGzip } from "node:zlib";
+import { createHash } from "node:crypto";
+import { createReadStream, existsSync, statSync, readFileSync } from "node:fs";
+import { join, normalize, extname, resolve, sep } from "node:path";
+
+const ROOT = resolve(process.env.TW_ROOT ?? ".tw");
+const PORT = Number(process.env.PORT ?? 8000);
+const HOST = process.env.HOST ?? "0.0.0.0";
+
+if (!existsSync(ROOT)) {
+  console.error(`Build output not found: ${ROOT}`);
+  console.error("Run `tw build` first (or set TW_ROOT).");
+  process.exit(1);
+}
+
+const MIME = {
+  ".html": "text/html; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".js": "text/javascript; charset=utf-8",
+  ".mjs": "text/javascript; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".svg": "image/svg+xml",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".webp": "image/webp",
+  ".avif": "image/avif",
+  ".ico": "image/x-icon",
+  ".txt": "text/plain; charset=utf-8",
+  ".xml": "application/xml",
+  ".pdf": "application/pdf",
+  ".woff": "font/woff",
+  ".woff2": "font/woff2",
+  ".ttf": "font/ttf",
+  ".mp4": "video/mp4",
+  ".webm": "video/webm",
+  ".wasm": "application/wasm",
+};
+
+const COMPRESSIBLE = new Set([".html", ".css", ".js", ".mjs", ".json", ".svg", ".txt", ".xml"]);
+const SECURITY_HEADERS = {
+  "x-content-type-options": "nosniff",
+  "referrer-policy": "strict-origin-when-cross-origin",
+};
+
+/** Never serve server-only files or dotfiles (mirrors TW StaticHandler). */
+function isForbidden(pathname) {
+  const segments = pathname.split("/").filter(Boolean);
+  const last = segments[segments.length - 1] ?? "";
+  if (/\.(twm|ts|tsx|mts|cts)$/i.test(last) || /^\.env/i.test(last)) return true;
+  return segments.some((s) => s.startsWith(".") && s !== ".");
+}
+
+/** Resolve a pathname inside ROOT, blocking traversal. Returns null if unsafe. */
+function safeResolve(pathname) {
+  const target = normalize(join(ROOT, pathname));
+  if (target !== ROOT && !target.startsWith(ROOT + sep)) return null;
+  return target;
+}
+
+/** Clean-URL resolution: exact file -> +.html -> dir/index.html. */
+function resolveFile(pathname) {
+  const candidates = [];
+  const base = safeResolve(pathname);
+  if (base === null) return null;
+  if (pathname === "/" || pathname === "") {
+    candidates.push(join(ROOT, "index.html"));
+  } else {
+    candidates.push(base);
+    if (!extname(base)) {
+      candidates.push(base + ".html");
+      candidates.push(join(base, "index.html"));
+    }
+  }
+  for (const c of candidates) {
+    if (existsSync(c) && statSync(c).isFile()) return c;
+  }
+  return null;
+}
+
+function etagFor(stat) {
+  const h = createHash("sha1").update(`${stat.size}:${stat.mtimeMs}`).digest("hex").slice(0, 16);
+  return `"${h}"`;
+}
+
+const server = createServer((req, res) => {
+  let pathname;
+  try {
+    pathname = decodeURIComponent(new URL(req.url ?? "/", "http://local").pathname);
+  } catch {
+    res.writeHead(400, { "content-type": "text/plain" });
+    return res.end("Bad Request");
+  }
+  // Collapse duplicate slashes (`//x` must match `/x`).
+  pathname = pathname.replace(/\/{2,}/g, "/");
+
+  if (req.method !== "GET" && req.method !== "HEAD") {
+    res.writeHead(405, { allow: "GET, HEAD", ...SECURITY_HEADERS });
+    return res.end("Method Not Allowed");
+  }
+
+  if (isForbidden(pathname)) {
+    res.writeHead(404, { "content-type": "text/plain", ...SECURITY_HEADERS });
+    return res.end("Not Found");
+  }
+
+  const file = resolveFile(pathname);
+  const finalPath = file ?? ((existsSync(join(ROOT, "index.html")) && pathname !== "/") ? join(ROOT, "index.html") : null);
+  if (!finalPath) {
+    // Custom 404 page if the build produced one.
+    const notFound = join(ROOT, "404.html");
+    if (existsSync(notFound)) {
+      res.writeHead(404, { "content-type": "text/html; charset=utf-8", ...SECURITY_HEADERS });
+      if (req.method === "HEAD") return res.end();
+      return createReadStream(notFound).pipe(res);
+    }
+    res.writeHead(404, { "content-type": "text/plain", ...SECURITY_HEADERS });
+    return res.end("Not Found");
+  }
+
+  const stat = statSync(finalPath);
+  const ext = extname(finalPath).toLowerCase();
+  const type = MIME[ext] ?? "application/octet-stream";
+  const etag = etagFor(stat);
+  const headers = { ...SECURITY_HEADERS, "content-type": type, etag };
+
+  // Hashed assets get long caching (assets/<name>.<hash>.<ext>).
+  if (/\/assets\/[^/]+\.[0-9a-f]{8,}\.(css|js)$/i.test(finalPath)) {
+    headers["cache-control"] = "public, max-age=31536000, immutable";
+  } else {
+    headers["cache-control"] = "no-cache";
+  }
+
+  // Conditional request
+  if (req.headers["if-none-match"] === etag) {
+    res.writeHead(304, { etag, ...SECURITY_HEADERS });
+    return res.end();
+  }
+
+  // Range request (single range only)
+  const range = req.headers.range;
+  if (range && /^bytes=\d*-\d*$/.test(range)) {
+    const [startStr, endStr] = range.slice(6).split("-");
+    const start = startStr === "" ? 0 : Number(startStr);
+    const end = endStr === "" ? stat.size - 1 : Math.min(Number(endStr), stat.size - 1);
+    if (start <= end && start < stat.size) {
+      res.writeHead(206, {
+        ...headers,
+        "content-range": `bytes ${start}-${end}/${stat.size}`,
+        "content-length": String(end - start + 1),
+        "accept-ranges": "bytes",
+      });
+      if (req.method === "HEAD") return res.end();
+      return createReadStream(finalPath, { start, end }).pipe(res);
+    }
+    res.writeHead(416, { "content-range": `bytes */${stat.size}` });
+    return res.end();
+  }
+
+  headers["accept-ranges"] = "bytes";
+  headers["content-length"] = String(stat.size);
+
+  // gzip when the client accepts it and the type is compressible.
+  const acceptEncoding = String(req.headers["accept-encoding"] ?? "");
+  const wantsGzip = COMPRESSIBLE.has(ext) && stat.size > 1024 && acceptEncoding.includes("gzip");
+  if (wantsGzip) {
+    delete headers["content-length"];
+    headers["content-encoding"] = "gzip";
+    headers["vary"] = "Accept-Encoding";
+    res.writeHead(200, headers);
+    if (req.method === "HEAD") return res.end();
+    return createReadStream(finalPath).pipe(createGzip()).pipe(res);
+  }
+
+  res.writeHead(200, headers);
+  if (req.method === "HEAD") return res.end();
+  createReadStream(finalPath).pipe(res);
+});
+
+server.listen(PORT, HOST, () => {
+  console.log(`  TW Node adapter — serving ${ROOT}`);
+  console.log(`  http://${HOST}:${PORT}\n`);
+});
+
+// Drain connections on SIGTERM/SIGINT (docker stop, k8s, Ctrl+C)
+const shutdown = (signal) => {
+  console.log(`  [TW] ${signal} received — shutting down gracefully...`);
+  server.close(() => process.exit(0));
+  setTimeout(() => process.exit(0), 5000).unref();
+};
+process.on("SIGTERM", () => shutdown("SIGTERM"));
+process.on("SIGINT", () => shutdown("SIGINT"));
+process.on("unhandledRejection", (reason) => {
+  console.warn("[TW] Unhandled promise rejection:", reason?.message ?? reason);
+});

package/dist/adapters/railway/railway.toml

@@ -0,0 +1,18 @@
+# Railway deployment for TW Framework
+# Generated by `tw adapter railway`.
+#
+# Railway runs the full server in a container and injects PORT —
+# the TW production server honours it automatically.
+#
+# 1. Run `tw adapter docker` first — this config uses the Dockerfile.
+# 2. In Railway: New Project → Deploy from GitHub repo → done.
+
+[build]
+  builder = "DOCKERFILE"
+  dockerfilePath = "Dockerfile"
+
+[deploy]
+  startCommand = "tw serve"
+  healthcheckPath = "/"
+  restartPolicyType = "ON_FAILURE"
+  restartPolicyMaxRetries = 10

package/dist/adapters/render/render.yaml

@@ -0,0 +1,27 @@
+# Render blueprint for TW Framework
+# Generated by `tw adapter render`.
+#
+# Create a new app in the Render dashboard from "Blueprint" and point it at
+# this repository — the file below defines the service.
+
+services:
+  # Static output: pages + pre-rendered routes
+  - type: web
+    name: tw-app
+    runtime: static
+    buildCommand: npm install && npx tw build
+    staticPublishPath: .tw
+    headers:
+      - path: /assets/*
+        name: Cache-Control
+        value: public, max-age=31536000, immutable
+      - path: /js/*
+        name: Cache-Control
+        value: public, max-age=31536000, immutable
+
+  # Full server (.twm APIs + middleware) — uncomment and run
+  # `tw adapter docker` to generate the Dockerfile first:
+  # - type: web
+  #   name: tw-app-full
+  #   runtime: docker
+  #   dockerCommand: tw serve

package/dist/adapters/vercel/vercel.json

@@ -0,0 +1,6 @@
+{
+  "buildCommand": "bunx tw build",
+  "outputDirectory": ".tw",
+  "installCommand": "bun install",
+  "cleanUrls": true
+}