@ismaelsoilet/synapsejs 1.1.0

package/src/runtime/uploads.ts

@@ -0,0 +1,192 @@
+/**
+ * SynapseJS - Uploads
+ *
+ * The RPC endpoint speaks JSON on purpose — that is what closes CSRF by
+ * construction — so files need their own door. This one requires a session,
+ * refuses a name that tries to escape the upload directory, and stops reading the
+ * moment the body passes the limit instead of buffering it first.
+ *
+ * The endpoint stores bytes and returns a relative path; what those bytes mean is
+ * the slice's business, decided by its own contract.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { Err, Ok, type Result } from '../core/machine-types';
+import type { SessionContext } from '../core/session-context';
+
+export const DEFAULT_MAX_UPLOAD_BYTES = 5 * 1024 * 1024;
+
+/** No separators, no `..`, no leading dash or dot, and a sane length. */
+const NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,119}$/;
+
+export type UploadErrorCode = 'INVALID_NAME' | 'UNAUTHORIZED' | 'TOO_LARGE' | 'EMPTY_BODY' | 'WRITE_FAILED';
+
+export function maxUploadBytes(raw: string | undefined = process.env.SYNAPSE_MAX_UPLOAD_BYTES): number {
+  const parsed = Number(raw);
+
+  return Number.isFinite(parsed) && parsed > 0 ? Math.floor(parsed) : DEFAULT_MAX_UPLOAD_BYTES;
+}
+
+/**
+ * Accepts a plain file name or refuses it — it never silently rewrites one, so a
+ * caller sending `../../etc/passwd` gets an error instead of a surprise file.
+ */
+export function safeUploadName(raw: string | null): Result<string, 'INVALID_NAME'> {
+  if (!raw) {
+    return Err('INVALID_NAME');
+  }
+
+  const trimmed = raw.trim();
+
+  if (path.basename(trimmed) !== trimmed || !NAME_PATTERN.test(trimmed)) {
+    return Err('INVALID_NAME');
+  }
+
+  return Ok(trimmed);
+}
+
+export interface UploadOutcome {
+  status: number;
+  body: Record<string, unknown>;
+}
+
+/** Reads at most `maxBytes`, cancelling the stream instead of buffering a bomb. */
+export async function readBodyWithinLimit(
+  body: ReadableStream<Uint8Array> | null,
+  maxBytes: number
+): Promise<Result<Uint8Array, 'TOO_LARGE'>> {
+  if (!body) {
+    return Ok(new Uint8Array());
+  }
+
+  const reader = body.getReader();
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+
+  for (;;) {
+    const { done, value } = await reader.read();
+
+    if (done) {
+      break;
+    }
+
+    if (!value) {
+      continue;
+    }
+
+    total += value.byteLength;
+
+    if (total > maxBytes) {
+      await reader.cancel();
+      return Err('TOO_LARGE');
+    }
+
+    chunks.push(value);
+  }
+
+  const merged = new Uint8Array(total);
+  let offset = 0;
+
+  for (const chunk of chunks) {
+    merged.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+
+  return Ok(merged);
+}
+
+export async function saveUpload(
+  request: Request,
+  options: { baseDir: string; domain: string; session: SessionContext; maxBytes?: number }
+): Promise<UploadOutcome> {
+  if (!options.session.isAuthenticated) {
+    return { status: 401, body: { ok: false, error: 'UNAUTHORIZED' } };
+  }
+
+  const maxBytes = options.maxBytes ?? maxUploadBytes();
+
+  const declared = Number(request.headers.get('content-length') ?? '');
+  if (Number.isFinite(declared) && declared > maxBytes) {
+    return { status: 413, body: { ok: false, error: 'TOO_LARGE', maxBytes } };
+  }
+
+  const contentType = request.headers.get('content-type') || '';
+  let fileBytes: Uint8Array;
+  let targetFileName: string;
+
+  if (contentType.includes('multipart/form-data')) {
+    let formData: FormData;
+    try {
+      formData = await request.formData();
+    } catch {
+      return { status: 400, body: { ok: false, error: 'INVALID_MULTIPART_BODY' } };
+    }
+    const file = formData.get('file');
+    if (!file || typeof file === 'string') {
+      return {
+        status: 422,
+        body: { ok: false, error: 'NO_FILE_IN_FORM_DATA', hint: 'envie o arquivo no campo "file"' }
+      };
+    }
+    const uploadedFile = file as File;
+    if (uploadedFile.size > maxBytes) {
+      return { status: 413, body: { ok: false, error: 'TOO_LARGE', maxBytes } };
+    }
+    if (uploadedFile.size === 0) {
+      return { status: 422, body: { ok: false, error: 'EMPTY_BODY' } };
+    }
+
+    const rawName = uploadedFile.name || new URL(request.url).searchParams.get('name');
+    const name = safeUploadName(rawName);
+    if (!name.ok) {
+      return {
+        status: 400,
+        body: { ok: false, error: 'INVALID_NAME', hint: 'nome do arquivo inválido' }
+      };
+    }
+    targetFileName = name.value;
+    fileBytes = new Uint8Array(await uploadedFile.arrayBuffer());
+  } else {
+    const name = safeUploadName(new URL(request.url).searchParams.get('name'));
+
+    if (!name.ok) {
+      return {
+        status: 400,
+        body: { ok: false, error: 'INVALID_NAME', hint: 'passe ?name=arquivo.pdf, sem diretórios e sem ".."' }
+      };
+    }
+
+    const body = await readBodyWithinLimit(request.body, maxBytes);
+    if (!body.ok) {
+      return { status: 413, body: { ok: false, error: 'TOO_LARGE', maxBytes } };
+    }
+
+    if (body.value.byteLength === 0) {
+      return { status: 422, body: { ok: false, error: 'EMPTY_BODY' } };
+    }
+
+    targetFileName = name.value;
+    fileBytes = body.value;
+  }
+
+  const directory = path.join(options.baseDir, '.synapse', 'uploads', options.domain);
+  const fileName = `${crypto.randomUUID().slice(0, 8)}-${targetFileName}`;
+  const target = path.join(directory, fileName);
+
+  try {
+    fs.mkdirSync(directory, { recursive: true });
+    fs.writeFileSync(target, fileBytes);
+  } catch (err) {
+    return { status: 500, body: { ok: false, error: 'WRITE_FAILED', message: (err as Error).message } };
+  }
+
+  return {
+    status: 200,
+    body: {
+      ok: true,
+      path: path.relative(options.baseDir, target).split(path.sep).join('/'),
+      bytes: fileBytes.byteLength
+    }
+  };
+}

package/templates/starter/.dockerignore

@@ -0,0 +1,7 @@
+node_modules
+.git
+.synapse/dist
+.synapse/oracles
+.synapse/synapse.sqlite*
+.synapse/queue.sqlite*
+*.log

package/templates/starter/Dockerfile

@@ -0,0 +1,40 @@
+# ==============================================================================
+# SynapseJS Production Dockerfile (Starter Template)
+# Ultra-lightweight (~90MB), non-root execution, native health check
+# ==============================================================================
+
+FROM oven/bun:alpine AS builder
+WORKDIR /app
+
+# Install dependencies with lockfile caching
+COPY package.json bun.lock* ./
+RUN bun install --frozen-lockfile
+
+# Copy application source code
+COPY . .
+
+# Pre-build client bundles and standalone distribution
+RUN bun run build:standalone
+
+# ==============================================================================
+# Production Runner Stage
+# ==============================================================================
+FROM oven/bun:alpine AS runner
+WORKDIR /app
+
+ENV NODE_ENV=production \
+    PORT=3000 \
+    SYNAPSE_LOG=json
+
+# Copy standalone distribution and production dependencies from builder
+COPY --from=builder /app/.synapse/standalone ./
+COPY --from=builder /app/node_modules ./node_modules
+
+USER bun
+
+EXPOSE 3000
+
+HEALTHCHECK --interval=30s --timeout=5s --start-period=5s --retries=3 \
+  CMD bun -e "fetch('http://localhost:' + (process.env.PORT || 3000) + '/_synapse/api/health').then(r => process.exit(r.ok ? 0 : 1)).catch(() => process.exit(1))"
+
+CMD ["bun", "run", "server.ts"]

package/templates/starter/README.md

@@ -0,0 +1,40 @@
+# SynapseJS Starter App ⚡
+
+Aplicação construída com **SynapseJS** — framework fullstack para Bun onde uma feature inteira
+(contrato, DDL, server action, UI e oráculo) vive num único arquivo `*.slice.tsx`.
+
+Requisito: **Bun >= 1.2**.
+
+## Comandos rápidos
+
+```bash
+# 1. Iniciar servidor com SSR e auto-migração
+bun run dev
+
+# 2. Criar uma nova fatia vertical com 1 comando
+bun run new-slice <domain> <name>
+# Exemplo: bun run new-slice users register-user
+
+# 3. Rodar os oráculos da fatia
+bun run test
+
+# 4. Checar tipos
+bun run check
+
+# 5. Iniciar servidor MCP local (JSON-RPC sobre stdio)
+bun run mcp
+
+# 6. Particionar as fatias em shared/server/client e rodar os dois gates
+bun run split
+```
+
+## RBAC no browser
+
+As Server Actions recebem `SessionContext`. Para exercitar uma action protegida a partir da UI,
+defina os cookies que o shell SSR repassa como headers:
+
+```js
+document.cookie = 'synapse_token=demo; synapse_roles=support';
+```
+
+Sem credencial a action responde `Err('UNAUTHORIZED')` — o RBAC é aplicado de verdade, não decorativo.

package/templates/starter/gitignore

@@ -0,0 +1,6 @@
+node_modules/
+.synapse/
+.codebase/
+dist/
+*.log
+.DS_Store

package/templates/starter/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "starter-app",
+  "version": "0.1.0",
+  "type": "module",
+  "engines": {
+    "bun": ">=1.2.0"
+  },
+  "scripts": {
+    "dev": "synapse dev",
+    "check": "synapse check",
+    "migrate": "synapse migrate",
+    "mcp": "synapse mcp",
+    "skeleton": "synapse skeleton",
+    "test": "synapse test",
+    "new-slice": "synapse new-slice",
+    "split": "synapse split",
+    "build": "synapse build",
+    "build:standalone": "synapse build --standalone",
+    "start": "synapse start"
+  },
+  "dependencies": {
+    "@ismaelsoilet/synapsejs": "^1.1.0",
+    "@sinclair/typebox": "^0.34.40",
+    "fast-check": "^3.23.2",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.4.2",
+    "@types/react": "^19.0.10",
+    "@types/react-dom": "^19.0.4",
+    "typescript": "^5.8.2"
+  }
+}

package/templates/starter/src/slices/welcome/hello-world.slice.tsx

@@ -0,0 +1,172 @@
+import type React from 'react';
+import { useState } from 'react';
+import {
+  type DatabaseClient,
+  Err,
+  fc,
+  MockDatabaseClient,
+  Ok,
+  type Result,
+  type SessionContext,
+  type Static,
+  Type,
+  Value
+} from 'synapsejs';
+
+// ============================================================================
+// 1. CONTRATO DE ENTRADA JIT (TypeBox)
+// ============================================================================
+export const HelloWorldInputSchema = Type.Object({
+  name: Type.String({ minLength: 2, maxLength: 50 }),
+  message: Type.Optional(Type.String({ maxLength: 200 }))
+});
+export type HelloWorldInput = Static<typeof HelloWorldInputSchema>;
+
+// DDL DECLARATIVO DA FATIA (Auto-migrado via AST pelo Synapse)
+export const sliceSchema = `
+  CREATE TABLE IF NOT EXISTS greetings (
+    id TEXT PRIMARY KEY,
+    name TEXT NOT NULL,
+    message TEXT,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+  );
+`;
+
+// ============================================================================
+// 2. MODELAGEM ESTRITA DE DOMÍNIO (Result<T, E>)
+// ============================================================================
+export type HelloWorldOutput = Result<
+  { greetingId: string; greeting: string; createdAt: string },
+  'INVALID_SCHEMA' | 'NO_DATABASE' | 'PERSISTENCE_FAILED'
+>;
+
+// ============================================================================
+// 3. EXECUÇÃO DE SERVIDOR PURA (SERVER ACTION)
+// ============================================================================
+export async function helloWorldAction(
+  payload: unknown,
+  db?: DatabaseClient,
+  _session?: SessionContext
+): Promise<HelloWorldOutput> {
+  if (!db) {
+    return Err('NO_DATABASE');
+  }
+
+  if (!Value.Check(HelloWorldInputSchema, payload)) {
+    return Err('INVALID_SCHEMA');
+  }
+  const input = payload as HelloWorldInput;
+  const greetingId = crypto.randomUUID();
+  const greeting = `Olá, ${input.name}! Bem-vindo ao SynapseJS.`;
+
+  await db.query(`INSERT INTO greetings (id, name, message) VALUES ($1, $2, $3)`, [
+    greetingId,
+    input.name,
+    input.message || 'Boas-vindas'
+  ]);
+
+  return Ok({
+    greetingId,
+    greeting,
+    createdAt: new Date().toISOString()
+  });
+}
+
+// ============================================================================
+// 4. COMPONENTE UI REACT
+// ============================================================================
+export interface HelloWorldViewProps {
+  defaultName?: string;
+  onSubmitAction?: (payload: unknown) => Promise<HelloWorldOutput>;
+}
+
+export function HelloWorldView({ defaultName = 'Desenvolvedor', onSubmitAction }: HelloWorldViewProps) {
+  const [feedback, setFeedback] = useState<string | null>(null);
+
+  const handleSubmit = async (e: React.FormEvent<HTMLFormElement>) => {
+    e.preventDefault();
+    if (!onSubmitAction) return;
+
+    const form = e.currentTarget;
+    const formData = new FormData(form);
+    const payload = {
+      name: formData.get('name') as string,
+      message: (formData.get('message') as string) || undefined
+    };
+
+    const res = await onSubmitAction(payload);
+    if (res.ok) {
+      setFeedback(res.value.greeting);
+    } else {
+      setFeedback(`Erro: ${res.error}`);
+    }
+  };
+
+  return (
+    <div className="max-w-md mx-auto p-6 bg-slate-900 border border-slate-800 rounded-xl text-slate-100">
+      <h2 className="text-xl font-bold mb-4 text-cyan-400">⚡ SynapseJS Starter Slice</h2>
+      <form onSubmit={handleSubmit} className="space-y-4">
+        <div>
+          <label htmlFor="hello-name" className="block text-xs font-mono text-slate-400 mb-1">
+            Seu Nome:
+          </label>
+          <input
+            id="hello-name"
+            name="name"
+            defaultValue={defaultName}
+            required
+            className="w-full px-3 py-2 bg-slate-800 border border-slate-700 rounded text-sm text-white"
+          />
+        </div>
+        <div>
+          <label htmlFor="hello-message" className="block text-xs font-mono text-slate-400 mb-1">
+            Mensagem (Opcional):
+          </label>
+          <input
+            id="hello-message"
+            name="message"
+            placeholder="Primeira fatia no SynapseJS..."
+            className="w-full px-3 py-2 bg-slate-800 border border-slate-700 rounded text-sm text-white"
+          />
+        </div>
+        <button
+          type="submit"
+          className="w-full py-2 bg-cyan-600 hover:bg-cyan-500 rounded text-white font-medium text-sm transition-colors"
+        >
+          Executar Ação RPC
+        </button>
+      </form>
+      {feedback && <div className="mt-4 p-3 bg-slate-800 rounded text-xs font-mono text-cyan-300">{feedback}</div>}
+    </div>
+  );
+}
+
+// ============================================================================
+// 5. ORÁCULO DE AUTO-VERIFICAÇÃO PBT (Property-Based Testing)
+// ============================================================================
+export const sliceTests = {
+  description: 'Verificação PBT de invariantes para hello-world',
+  cases: [
+    {
+      name: 'nome válido produz saudação que o contém',
+      run: async () => {
+        fc.assert(
+          fc.asyncProperty(fc.string({ minLength: 2, maxLength: 50 }), async (validName) => {
+            const result = await helloWorldAction({ name: validName }, new MockDatabaseClient());
+            return result.ok === true && result.value.greeting.includes(validName);
+          })
+        );
+      }
+    },
+    {
+      name: 'sem conexão de banco retorna NO_DATABASE',
+      run: async () => {
+        const result = await helloWorldAction({ name: 'Ismael' });
+
+        if (result.ok || result.error !== 'NO_DATABASE') {
+          throw new Error(`Invariante violada: esperava NO_DATABASE, obteve ${JSON.stringify(result)}`);
+        }
+      }
+    }
+  ]
+};

package/templates/starter/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "forceConsistentCasingInFileNames": true,
+    "types": ["bun"],
+    "paths": {
+      "synapsejs": ["./node_modules/@ismaelsoilet/synapsejs"],
+      "synapsejs/*": ["./node_modules/@ismaelsoilet/synapsejs/*"]
+    }
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", ".codebase", ".synapse"]
+}