@ismaelsoilet/synapsejs 1.1.0

package/src/client/hooks.ts

@@ -0,0 +1,152 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import type { Result } from '../core/machine-types';
+
+export interface UseSubscriptionOptions {
+  enabled?: boolean;
+  onOpen?: () => void;
+  onError?: (error: Event) => void;
+}
+
+export interface UseSubscriptionResult {
+  isConnected: boolean;
+  error: Error | null;
+}
+
+/**
+ * Hook for subscribing to Server-Sent Events (SSE) from client UI.
+ * Handles automatic subscription, message parsing, and teardown on unmount.
+ */
+export function useSubscription<T = unknown>(
+  topic: string,
+  onMessage: (data: T) => void,
+  options: UseSubscriptionOptions = {}
+): UseSubscriptionResult {
+  const { enabled = true, onOpen, onError } = options;
+  const [isConnected, setIsConnected] = useState<boolean>(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const onMessageRef = useRef(onMessage);
+  onMessageRef.current = onMessage;
+  const onOpenRef = useRef(onOpen);
+  onOpenRef.current = onOpen;
+  const onErrorRef = useRef(onError);
+  onErrorRef.current = onError;
+
+  useEffect(() => {
+    if (
+      !enabled ||
+      typeof window === 'undefined' ||
+      !(window as unknown as { EventSource?: typeof EventSource }).EventSource
+    ) {
+      return;
+    }
+
+    const sseUrl = `/_synapse/sse/${encodeURIComponent(topic)}`;
+    const eventSource = new EventSource(sseUrl);
+
+    eventSource.onopen = () => {
+      setIsConnected(true);
+      setError(null);
+      onOpenRef.current?.();
+    };
+
+    eventSource.onmessage = (e) => {
+      try {
+        const parsed = JSON.parse(e.data) as T;
+        onMessageRef.current(parsed);
+      } catch (err) {
+        console.error(`[useSubscription] Falha ao parsear evento SSE do tópico "${topic}":`, err);
+      }
+    };
+
+    eventSource.onerror = (e) => {
+      setIsConnected(false);
+      const err = new Error(`Conexão SSE perdida para o tópico "${topic}"`);
+      setError(err);
+      onErrorRef.current?.(e);
+    };
+
+    return () => {
+      eventSource.close();
+      setIsConnected(false);
+    };
+  }, [topic, enabled]);
+
+  return { isConnected, error };
+}
+
+export interface UseActionResult<TPayload, TData, TError> {
+  execute: (payload: TPayload) => Promise<Result<TData, TError>>;
+  isSubmitting: boolean;
+  isLoading: boolean;
+  data: TData | null;
+  error: TError | null;
+  isSuccess: boolean;
+  isError: boolean;
+  reset: () => void;
+}
+
+/**
+ * Hook for executing server actions from client UI with reactive state management.
+ */
+export function useAction<TPayload = unknown, TData = unknown, TError = string>(
+  actionFn?: (payload: TPayload) => Promise<Result<TData, TError>>
+): UseActionResult<TPayload, TData, TError> {
+  const [isSubmitting, setIsSubmitting] = useState<boolean>(false);
+  const [data, setData] = useState<TData | null>(null);
+  const [error, setError] = useState<TError | null>(null);
+  const [isSuccess, setIsSuccess] = useState<boolean>(false);
+
+  const reset = useCallback(() => {
+    setIsSubmitting(false);
+    setData(null);
+    setError(null);
+    setIsSuccess(false);
+  }, []);
+
+  const execute = useCallback(
+    async (payload: TPayload): Promise<Result<TData, TError>> => {
+      if (!actionFn) {
+        const errVal = 'NO_ACTION_FUNCTION' as unknown as TError;
+        setError(errVal);
+        return { ok: false, error: errVal };
+      }
+
+      setIsSubmitting(true);
+      setError(null);
+      setIsSuccess(false);
+
+      try {
+        const result = await actionFn(payload);
+        if (result.ok) {
+          setData(result.value);
+          setIsSuccess(true);
+          setError(null);
+        } else {
+          setError(result.error);
+          setIsSuccess(false);
+        }
+        return result;
+      } catch (err: unknown) {
+        const failure = (err instanceof Error ? err.message : String(err)) as unknown as TError;
+        setError(failure);
+        setIsSuccess(false);
+        return { ok: false, error: failure };
+      } finally {
+        setIsSubmitting(false);
+      }
+    },
+    [actionFn]
+  );
+
+  return {
+    execute,
+    isSubmitting,
+    isLoading: isSubmitting,
+    data,
+    error,
+    isSuccess,
+    isError: error !== null,
+    reset
+  };
+}

package/src/client/i18n.ts

@@ -0,0 +1,40 @@
+/**
+ * SynapseJS - Isomorphic i18n Translation Primitive
+ *
+ * Lightweight, zero-dependency translation helper for client and server components.
+ * Guarantees zero server-leakage when used in client artifacts.
+ */
+
+export type TranslationDictionary = Record<string, Record<string, string>>;
+export type TranslateFn = (key: string, params?: Record<string, string | number>) => string;
+
+/**
+ * Creates an isomorphic translation function for a given dictionary and locale.
+ * Supports interpolation with `{param}` placeholders and graceful fallback.
+ *
+ * @example
+ * const t = createTranslator({
+ *   'en': { 'welcome': 'Hello, {name}!' },
+ *   'pt-BR': { 'welcome': 'Olá, {name}!' }
+ * }, 'pt-BR');
+ *
+ * t('welcome', { name: 'Maria' }) // 'Olá, Maria!'
+ */
+export function createTranslator(
+  dictionary: TranslationDictionary,
+  currentLocale: string,
+  fallbackLocale = 'pt-BR'
+): TranslateFn {
+  const dict = dictionary[currentLocale] ?? dictionary[fallbackLocale] ?? {};
+  const fallbackDict = dictionary[fallbackLocale] ?? {};
+
+  return (key: string, params?: Record<string, string | number>): string => {
+    let template = dict[key] ?? fallbackDict[key] ?? key;
+    if (params) {
+      for (const [paramKey, paramValue] of Object.entries(params)) {
+        template = template.replaceAll(`{${paramKey}}`, String(paramValue));
+      }
+    }
+    return template;
+  };
+}

package/src/client.ts

@@ -0,0 +1,66 @@
+/**
+ * SynapseJS - Client Entry (browser)
+ *
+ * What a slice's UI is allowed to import. The package root is the server surface:
+ * it reaches SQLite, PostgreSQL and `process.env`, so a browser bundle that pulls it
+ * in cannot even be built. This entry exposes exactly the values that are valid in
+ * a browser — the RPC transport and the session cookie — and nothing else.
+ *
+ * The splitter's leak gate enforces this: a value imported from the bare package
+ * inside a client artifact fails the build and says so.
+ */
+
+// Declarative UI Components
+export {
+  Badge,
+  type BadgeProps,
+  Button,
+  type ButtonProps,
+  Card,
+  type CardProps,
+  type Column,
+  DataForm,
+  type DataFormProps,
+  DataTable,
+  type DataTableProps,
+  expandNestedObject,
+  type FormField,
+  getNestedProperty,
+  Pagination,
+  type PaginationProps,
+  setNestedProperty
+} from './client/components';
+// Context & SSR data isolation
+export {
+  type SynapseContextValue,
+  SynapseProvider,
+  type SynapseProviderProps,
+  useLoaderData,
+  useSession,
+  useSynapseContext
+} from './client/context';
+// Reactive Action & Realtime Subscription Hooks
+export {
+  type UseActionResult,
+  type UseSubscriptionOptions,
+  type UseSubscriptionResult,
+  useAction,
+  useSubscription
+} from './client/hooks';
+export {
+  createTranslator,
+  type TranslateFn,
+  type TranslationDictionary
+} from './client/i18n';
+export type { Result } from './core/machine-types';
+export { type RpcTransportError, rpcCall, rpcTransportFailure } from './core/rpc-client';
+export type { SessionContext } from './core/session-context';
+export {
+  clearSession,
+  currentRoles,
+  DEFAULT_SESSION_MAX_AGE_SECONDS,
+  ROLES_COOKIE,
+  SESSION_COOKIE,
+  sessionCookie,
+  storeSession
+} from './core/session-cookie';

package/src/compiler/agent-diagnostic-json.ts

@@ -0,0 +1,113 @@
+/**
+ * SynapseJS - Agent Diagnostic JSON Engine
+ *
+ * Machine-only compiler diagnostic interceptor.
+ * Replaces human-targeted ANSI text output with structured JSON coordinates:
+ * { status, errorCount, issues: [{ file, line, column, errorCode, message }] }
+ * Enables closed-loop deterministic auto-correction by AI agents.
+ */
+
+import * as path from 'path';
+import * as ts from 'typescript';
+
+export interface DiagnosticIssue {
+  file: string;
+  line: number;
+  column: number;
+  errorCode: number;
+  message: string;
+}
+
+export interface DiagnosticReport {
+  status: 'PASS' | 'FAIL';
+  errorCount: number;
+  timestamp: string;
+  durationMs: number;
+  issues: DiagnosticIssue[];
+  code?: string;
+  message?: string;
+}
+
+export function runMachineVerifications(projectRoot: string, targetFile?: string): DiagnosticReport {
+  const startTime = Date.now();
+  const tsConfigPath = path.join(projectRoot, 'tsconfig.json');
+  const configFile = ts.readConfigFile(tsConfigPath, ts.sys.readFile);
+  const parsed = ts.parseJsonConfigFileContent(configFile.config, ts.sys, projectRoot);
+
+  const fileNames = targetFile
+    ? parsed.fileNames.filter((f) => f.endsWith(targetFile) || f.includes(targetFile))
+    : parsed.fileNames;
+
+  // Nothing matched is not a pass: no file was verified.
+  if (fileNames.length === 0) {
+    return {
+      status: 'FAIL',
+      errorCount: 1,
+      timestamp: new Date().toISOString(),
+      durationMs: Date.now() - startTime,
+      issues: [],
+      code: targetFile ? 'TARGET_FILE_NOT_FOUND' : 'NO_FILES_MATCHED',
+      message: targetFile
+        ? `Nenhum arquivo do projeto corresponde a '${targetFile}'.`
+        : `O tsconfig em '${tsConfigPath}' não inclui nenhum arquivo — nada foi verificado.`
+    };
+  }
+
+  const program = ts.createProgram(fileNames, parsed.options);
+  const diagnostics = ts.getPreEmitDiagnostics(program);
+
+  const durationMs = Date.now() - startTime;
+
+  if (diagnostics.length === 0) {
+    return {
+      status: 'PASS',
+      errorCount: 0,
+      timestamp: new Date().toISOString(),
+      durationMs,
+      issues: []
+    };
+  }
+
+  const structuredErrors: DiagnosticIssue[] = diagnostics.map((d) => {
+    let file = 'unknown';
+    let line = 0;
+    let column = 0;
+
+    if (d.file && d.start !== undefined) {
+      const position = d.file.getLineAndCharacterOfPosition(d.start);
+      file = path.relative(projectRoot, d.file.fileName);
+      line = position.line + 1;
+      column = position.character + 1;
+    }
+
+    return {
+      file,
+      line,
+      column,
+      errorCode: d.code,
+      message: ts.flattenDiagnosticMessageText(d.messageText, '\n')
+    };
+  });
+
+  return {
+    status: 'FAIL',
+    errorCount: structuredErrors.length,
+    timestamp: new Date().toISOString(),
+    durationMs,
+    issues: structuredErrors
+  };
+}
+
+if (import.meta.main) {
+  const target = process.argv[2];
+  const report = runMachineVerifications(process.cwd(), target);
+
+  // Write pure, unadulterated JSON to stdout for agent consumption
+  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+
+  if (report.status === 'FAIL') {
+    process.exit(1);
+  } else {
+    process.exit(0);
+  }
+}

package/src/compiler/ast-daemon-compressor.ts

@@ -0,0 +1,190 @@
+/**
+ * SynapseJS - Native AST Daemon & Codebase Compressor
+ *
+ * Extracts exact structural topology and signatures from slices and core modules.
+ * Suppresses implementation bodies to produce a compressed skeleton map (.codebase/repo-map.d.ts)
+ * that fits well within a 3,000-token budget for LLM context injection.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as ts from 'typescript';
+import { generateDatabaseSchemaCatalog } from './db-schema-generator';
+
+/**
+ * Resolves the runtime contract behind a TypeBox schema declaration.
+ *
+ * TypeBox carries the inferred shape on the `static` phantom property, which is
+ * exactly what `Static<typeof Schema>` exposes — the contract the agent needs.
+ */
+function describeSchemaType(checker: ts.TypeChecker, name: ts.Node): string {
+  const type = checker.getTypeAtLocation(name);
+  const staticProperty = type.getProperty('static');
+
+  if (staticProperty) {
+    const staticType = checker.getTypeOfSymbolAtLocation(staticProperty, name);
+    const printable = checker.typeToString(staticType, name, ts.TypeFormatFlags.NoTruncation);
+    return printable.length > 400 ? checker.typeToString(staticType, name) : printable;
+  }
+
+  return checker.typeToString(type, name);
+}
+
+interface SliceMetadata {
+  slicePath: string;
+  exportedTypes: string[];
+  exportedFunctions: string[];
+  hasUI: boolean;
+  hasPBT: boolean;
+}
+
+function isTestFile(fileName: string): boolean {
+  return /\.(test|spec)\.[cm]?tsx?$/.test(fileName);
+}
+
+export function compressRepositoryAST(
+  baseDir: string,
+  outputFile: string,
+  graphFile?: string
+): {
+  manifestTokensEstimate: number;
+  totalModules: number;
+  totalSlices: number;
+} {
+  const tsConfigPath = path.join(baseDir, 'tsconfig.json');
+  const configFile = ts.readConfigFile(tsConfigPath, ts.sys.readFile);
+  const parsed = ts.parseJsonConfigFileContent(configFile.config, ts.sys, baseDir);
+
+  // Every file the project compiles is mapped, not only `slices/` and `core/`:
+  // the tooling must also work on a conventional app that adopts it.
+  const sourceFiles = parsed.fileNames.filter((f) => !f.endsWith('.d.ts') && !isTestFile(f));
+
+  const program = ts.createProgram(sourceFiles, parsed.options);
+  const typeChecker = program.getTypeChecker();
+
+  let manifest = `// [SYNAPSE-JS AUTO-GENERATED SKELETON MAP]\n`;
+  manifest += `// STRICT CONTRACTS, ALGEBRAIC TYPES AND FUNCTION SIGNATURES ONLY.\n`;
+  manifest += `// Regenerate with 'synapse skeleton' — output is deterministic and committed.\n`;
+  manifest += `// NOT COMPILABLE: this is a signature digest for LLM context, not a .d.ts module.\n`;
+  manifest += `// It carries no imports and names repeat across modules by design.\n\n`;
+
+  const architectureGraph: SliceMetadata[] = [];
+
+  for (const src of program.getSourceFiles()) {
+    if (src.isDeclarationFile || !sourceFiles.includes(src.fileName)) {
+      continue;
+    }
+
+    const relPath = path.relative(baseDir, src.fileName);
+    manifest += `// ============================================================================\n`;
+    manifest += `// MODULE: ${relPath}\n`;
+    manifest += `// ============================================================================\n`;
+
+    const sliceMeta: SliceMetadata = {
+      slicePath: relPath,
+      exportedTypes: [],
+      exportedFunctions: [],
+      hasUI: false,
+      hasPBT: false
+    };
+
+    ts.forEachChild(src, (node) => {
+      const modifiers = ts.canHaveModifiers(node) ? ts.getModifiers(node) : undefined;
+      const isExported = modifiers?.some((m: ts.Modifier) => m.kind === ts.SyntaxKind.ExportKeyword);
+
+      // 1. Exported Type Aliases & Interfaces (e.g. TypeBox static types, Result types)
+      if (isExported && (ts.isTypeAliasDeclaration(node) || ts.isInterfaceDeclaration(node))) {
+        manifest += `${node.getText(src)}\n\n`;
+        sliceMeta.exportedTypes.push(node.name.text);
+      }
+
+      // 2. Exported Schemas & constants, resolved to their real inferred types
+      if (isExported && ts.isVariableStatement(node)) {
+        for (const decl of node.declarationList.declarations) {
+          const varName = decl.name.getText(src);
+          if (varName.endsWith('Schema')) {
+            manifest += `export declare const ${varName}: ${describeSchemaType(typeChecker, decl.name)};\n`;
+            sliceMeta.exportedTypes.push(varName);
+          }
+          if (varName === 'sliceTests') {
+            sliceMeta.hasPBT = true;
+          }
+        }
+      }
+
+      // 3. Exported Functions (Skeletonized: signature only, body stripped)
+      if (isExported && ts.isFunctionDeclaration(node) && node.name) {
+        const fnName = node.name.text;
+        const params = node.parameters
+          .map((p) => {
+            const pName = p.name.getText(src);
+            const pType = p.type ? p.type.getText(src) : 'unknown';
+            return `${pName}: ${pType}`;
+          })
+          .join(', ');
+
+        let retType = 'void';
+        if (node.type) {
+          retType = node.type.getText(src);
+        } else {
+          const signature = typeChecker.getSignatureFromDeclaration(node);
+          if (signature) {
+            retType = typeChecker.typeToString(typeChecker.getReturnTypeOfSignature(signature));
+          }
+        }
+
+        manifest += `export declare function ${fnName}(${params}): ${retType};\n`;
+        sliceMeta.exportedFunctions.push(fnName);
+
+        if (fnName.endsWith('Trigger') || fnName.endsWith('View') || fnName.endsWith('Component')) {
+          sliceMeta.hasUI = true;
+        }
+      }
+    });
+
+    manifest += `\n`;
+    architectureGraph.push(sliceMeta);
+  }
+
+  // Ensure output directory exists
+  const outDir = path.dirname(outputFile);
+  if (!fs.existsSync(outDir)) {
+    fs.mkdirSync(outDir, { recursive: true });
+  }
+
+  fs.writeFileSync(outputFile, manifest, 'utf-8');
+
+  // Also generate the database schema catalog if outputting into .codebase
+  try {
+    const dbSchemaPath = path.join(outDir, 'db-schema.d.ts');
+    generateDatabaseSchemaCatalog(baseDir, dbSchemaPath);
+  } catch {
+    // Non-fatal if project has no slices yet
+  }
+
+  if (graphFile) {
+    fs.writeFileSync(graphFile, JSON.stringify(architectureGraph, null, 2), 'utf-8');
+  }
+
+  // Heuristic token estimation: ~4 chars per token
+  const tokenEstimate = Math.round(manifest.length / 4);
+
+  return {
+    manifestTokensEstimate: tokenEstimate,
+    totalModules: architectureGraph.length,
+    totalSlices: architectureGraph.filter((entry) => entry.slicePath.endsWith('.slice.tsx')).length
+  };
+}
+
+if (import.meta.main) {
+  const root = process.cwd();
+  const repoMapPath = path.join(root, '.codebase/repo-map.d.ts');
+  const graphPath = path.join(root, '.codebase/architecture-graph.json');
+
+  console.log('⚡ [AST Daemon] Extraindo esqueleto e comprimindo repositório...');
+  const stats = compressRepositoryAST(root, repoMapPath, graphPath);
+  console.log(`✅ [AST Daemon PASS] Manifesto gerado com sucesso!`);
+  console.log(`   - Arquivo: .codebase/repo-map.d.ts`);
+  console.log(`   - Fatias e módulos processados: ${stats.totalSlices}`);
+  console.log(`   - Estimativa de tokens: ~${stats.manifestTokensEstimate} tokens (limite: 3.000 tokens)`);
+}