@potentiajs/core 0.1.0-preview.0

package/package.json

@@ -0,0 +1,90 @@
+{
+  "name": "@potentiajs/core",
+  "version": "0.1.0-preview.0",
+  "private": false,
+  "description": "Experimental Bun-first JavaScript framework kernel for contract-driven routing, actions, and form metadata.",
+  "type": "module",
+  "main": "./src/index.js",
+  "module": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "publishConfig": {
+    "access": "public",
+    "tag": "preview"
+  },
+  "bin": {
+    "potentia": "./bin/potentia.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js"
+    },
+    "./file-routing": {
+      "types": "./src/file-routing.d.ts",
+      "import": "./src/file-routing.js"
+    },
+    "./forms": {
+      "types": "./src/forms.d.ts",
+      "import": "./src/forms.js"
+    }
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "examples/file-routing-basic/",
+    "examples/full-flow-basic/",
+    "examples/form-rendering-basic/",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "bun test",
+    "check": "bun test",
+    "pack:dry": "npm pack --dry-run --json",
+    "check:preview": "bun run test && bun run check && npm pack --dry-run --json",
+    "check:release": "bun run check:preview",
+    "check:file-routing": "bun test tests/file-routing-*.test.js",
+    "generate:file-routes": "bun scripts/generate-file-routes.js"
+  },
+  "keywords": [
+    "actions",
+    "bun",
+    "contracts",
+    "effects",
+    "form-projection",
+    "form-state",
+    "forms",
+    "framework",
+    "full-stack",
+    "functional-core",
+    "javascript",
+    "metadata",
+    "plain-javascript",
+    "router",
+    "routing",
+    "runtime-contracts",
+    "server-actions",
+    "server-framework",
+    "sigiljs",
+    "validation",
+    "web-framework"
+  ],
+  "author": "Daniel Weipert",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/antistructured/potentiajs.git"
+  },
+  "bugs": {
+    "url": "https://github.com/antistructured/potentiajs/issues"
+  },
+  "homepage": "https://github.com/antistructured/potentiajs#readme",
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "dependencies": {
+    "@weipertda/sigiljs": "0.18.0"
+  },
+  "devDependencies": {}
+}

package/src/cli.js

@@ -0,0 +1,407 @@
+import { readFile } from 'node:fs/promises';
+
+import { generateFileRoutes } from './file-routing.js';
+import { generateFileRouteSource } from './dev/file-routing/writer.js';
+
+export const USAGE = 'Usage: potentia routes <generate|check> [--root <dir>] [--out <file>] [--package <specifier>] [--cwd <dir>] [--json]';
+
+const DEFAULT_OPTIONS = {
+  root: 'routes',
+  out: '.potentia/routes.generated.js',
+  packageName: '@potentiajs/core',
+  cwd: null,
+  json: false
+};
+
+const FLAG_MAP = new Map([
+  ['--root', 'root'],
+  ['--out', 'out'],
+  ['--package', 'packageName'],
+  ['--cwd', 'cwd']
+]);
+
+export function parseArgs(args = []) {
+  if (!Array.isArray(args)) {
+    return usageError('arguments must be an array', { json: false, command: null });
+  }
+
+  const json = args.includes('--json');
+  const [namespace, command, ...rest] = args;
+  const resolvedCommand = namespace === 'routes' && ['generate', 'check'].includes(command) ? `routes ${command}` : null;
+
+  if (namespace !== 'routes' || !['generate', 'check'].includes(command)) {
+    return usageError('Expected `potentia routes <generate|check>`', { json, command: resolvedCommand });
+  }
+
+  const options = { ...DEFAULT_OPTIONS, json };
+
+  for (let index = 0; index < rest.length; index += 1) {
+    const arg = rest[index];
+
+    if (arg === '--json') {
+      options.json = true;
+      continue;
+    }
+
+    const optionName = FLAG_MAP.get(arg);
+
+    if (!optionName) {
+      return usageError(arg?.startsWith('--') ? `unknown option: ${arg}` : `unexpected argument: ${arg}`, {
+        json,
+        command: resolvedCommand
+      });
+    }
+
+    const value = rest[index + 1];
+    if (!value || value.startsWith('--')) {
+      return usageError(`${arg} requires a value`, { json, command: resolvedCommand });
+    }
+
+    options[optionName] = value;
+    index += 1;
+  }
+
+  return {
+    ok: true,
+    command: resolvedCommand,
+    options: {
+      root: options.root,
+      out: options.out,
+      packageName: options.packageName,
+      cwd: options.cwd,
+      json: options.json
+    }
+  };
+}
+
+export async function main(args = [], io = {}) {
+  const stdout = io.stdout || process.stdout;
+  const stderr = io.stderr || process.stderr;
+  const baseCwd = io.cwd || process.cwd();
+  const parsed = parseArgs(args);
+
+  if (!parsed.ok) {
+    if (parsed.json) {
+      writeJson(stdout, createInvalidUsageEnvelope(parsed.command));
+      return 2;
+    }
+    writeLine(stderr, USAGE);
+    writeLine(stderr, `Usage error: ${parsed.error}`);
+    return 2;
+  }
+
+  const cwd = parsed.options.cwd || baseCwd;
+
+  try {
+    if (parsed.command === 'routes check') {
+      return await runCheck(parsed.options, cwd, { stdout, stderr });
+    }
+
+    return await runGenerate(parsed.options, cwd, { stdout, stderr });
+  } catch (error) {
+    if (parsed.options.json) {
+      writeJson(stdout, createJsonEnvelope({
+        ok: false,
+        command: parsed.command,
+        status: 'failed',
+        root: parsed.options.root,
+        output: parsed.options.out,
+        packageName: parsed.options.packageName,
+        routes: 0,
+        scopes: 0,
+        diagnostics: [{
+          code: 'POTENTIA_FILE_ROUTE_UNEXPECTED',
+          message: safeErrorMessage(error)
+        }]
+      }));
+      return 1;
+    }
+    writeLine(stderr, 'File route generation failed:');
+    writeLine(stderr, `- POTENTIA_FILE_ROUTE_UNEXPECTED ${safeErrorMessage(error)}`);
+    return 1;
+  }
+}
+
+export async function checkFileRoutes(options = {}) {
+  const expected = generateFileRouteSource({
+    rootDir: options.rootDir,
+    outputFile: options.outputFile,
+    packageName: options.packageName,
+    cwd: options.cwd
+  });
+
+  if (!expected.ok) {
+    return {
+      ...expected,
+      ok: false,
+      status: 'failed'
+    };
+  }
+
+  let currentSource;
+  try {
+    currentSource = await readFile(expected.outputFile, 'utf8');
+  } catch (error) {
+    if (isMissingFileError(error)) {
+      return {
+        ok: false,
+        status: 'missing',
+        rootDir: expected.rootDir,
+        outputFile: expected.outputFile,
+        written: false,
+        routes: expected.routes,
+        scopes: expected.scopes,
+        diagnostics: [],
+        errors: []
+      };
+    }
+    return {
+      ok: false,
+      status: 'failed',
+      rootDir: expected.rootDir,
+      outputFile: expected.outputFile,
+      written: false,
+      routes: expected.routes,
+      scopes: expected.scopes,
+      diagnostics: [{
+        code: 'POTENTIA_FILE_ROUTE_READ_FAILED',
+        message: 'Failed to read generated route module',
+        outputFile: expected.outputFile,
+        cause: error instanceof Error ? error.message : String(error)
+      }],
+      errors: [{
+        code: 'POTENTIA_FILE_ROUTE_READ_FAILED',
+        message: 'Failed to read generated route module',
+        outputFile: expected.outputFile,
+        cause: error instanceof Error ? error.message : String(error)
+      }]
+    };
+  }
+
+  const current = normalizeNewlines(currentSource);
+  const generated = normalizeNewlines(expected.source);
+  const currentStatus = current === generated ? 'current' : 'stale';
+
+  return {
+    ok: currentStatus === 'current',
+    status: currentStatus,
+    rootDir: expected.rootDir,
+    outputFile: expected.outputFile,
+    written: false,
+    routes: expected.routes,
+    scopes: expected.scopes,
+    diagnostics: [],
+    errors: []
+  };
+}
+
+export function formatDiagnostic(diagnostic = {}) {
+  const code = diagnostic.code || 'POTENTIA_FILE_ROUTE_FAILED';
+  const location = diagnostic.filePath || diagnostic.relativePath || diagnostic.routePath || diagnostic.rootDir || diagnostic.outputFile || '';
+  const message = diagnostic.message || 'File route generation failed';
+  return location ? `- ${code} ${location} ${message}` : `- ${code} ${message}`;
+}
+
+export function createJsonEnvelope({
+  ok,
+  command,
+  status,
+  root,
+  output,
+  packageName,
+  routes,
+  scopes,
+  diagnostics,
+  hint
+}) {
+  const envelope = {
+    ok: Boolean(ok),
+    command,
+    status,
+    root,
+    output,
+    package: packageName,
+    routes: Number.isFinite(routes) ? routes : 0,
+    scopes: Number.isFinite(scopes) ? scopes : 0,
+    diagnostics: toJsonDiagnostics(diagnostics)
+  };
+
+  if (hint) {
+    envelope.hint = hint;
+  }
+
+  return envelope;
+}
+
+export function toJsonDiagnostics(diagnostics = []) {
+  return diagnostics.map((diagnostic = {}) => {
+    const jsonDiagnostic = {
+      code: diagnostic.code || 'POTENTIA_CLI_ERROR',
+      message: diagnostic.message || 'Unknown diagnostic'
+    };
+    const path = diagnostic.path || diagnostic.filePath || diagnostic.relativePath || diagnostic.routePath || diagnostic.rootDir || diagnostic.outputFile;
+    if (path && !isAbsolutePath(path)) {
+      jsonDiagnostic.path = path;
+    }
+    return jsonDiagnostic;
+  });
+}
+
+async function runGenerate(options, cwd, io) {
+  const result = await generateFileRoutes({
+    rootDir: options.root,
+    outputFile: options.out,
+    packageName: options.packageName,
+    cwd
+  });
+
+  if (!result.ok) {
+    if (options.json) {
+      writeJson(io.stdout, createJsonEnvelope({
+        ok: false,
+        command: 'routes generate',
+        status: 'failed',
+        root: options.root,
+        output: options.out,
+        packageName: options.packageName,
+        routes: result.routes,
+        scopes: result.scopes,
+        diagnostics: result.errors?.length ? result.errors : result.diagnostics
+      }));
+      return 1;
+    }
+    writeDiagnostics(io.stderr, result);
+    return 1;
+  }
+
+  if (options.json) {
+    writeJson(io.stdout, createJsonEnvelope({
+      ok: true,
+      command: 'routes generate',
+      status: 'generated',
+      root: options.root,
+      output: options.out,
+      packageName: options.packageName,
+      routes: result.routes,
+      scopes: result.scopes,
+      diagnostics: result.diagnostics
+    }));
+    return 0;
+  }
+
+  writeLine(io.stdout, 'Generated file routes:');
+  writeLine(io.stdout, `- root: ${options.root}`);
+  writeLine(io.stdout, `- output: ${options.out}`);
+  writeLine(io.stdout, `- routes: ${result.routes}`);
+  writeLine(io.stdout, `- scopes: ${result.scopes}`);
+  return 0;
+}
+
+async function runCheck(options, cwd, io) {
+  const result = await checkFileRoutes({
+    rootDir: options.root,
+    outputFile: options.out,
+    packageName: options.packageName,
+    cwd
+  });
+
+  if (options.json) {
+    const status = result.status || (result.ok ? 'current' : 'failed');
+    writeJson(io.stdout, createJsonEnvelope({
+      ok: status === 'current',
+      command: 'routes check',
+      status,
+      root: options.root,
+      output: options.out,
+      packageName: options.packageName,
+      routes: result.routes,
+      scopes: result.scopes,
+      diagnostics: result.errors?.length ? result.errors : result.diagnostics,
+      hint: ['missing', 'stale'].includes(status) ? 'Run potentia routes generate' : undefined
+    }));
+    return status === 'current' ? 0 : 1;
+  }
+
+  if (result.status === 'current') {
+    writeLine(io.stdout, 'File routes are current:');
+    writeLine(io.stdout, `- root: ${options.root}`);
+    writeLine(io.stdout, `- output: ${options.out}`);
+    writeLine(io.stdout, `- routes: ${result.routes}`);
+    writeLine(io.stdout, `- scopes: ${result.scopes}`);
+    return 0;
+  }
+
+  if (result.status === 'missing') {
+    writeLine(io.stderr, 'File routes are not generated:');
+    writeLine(io.stderr, `- output: ${options.out}`);
+    writeLine(io.stderr, '- run: potentia routes generate');
+    return 1;
+  }
+
+  if (result.status === 'stale') {
+    writeLine(io.stderr, 'File routes are stale:');
+    writeLine(io.stderr, `- output: ${options.out}`);
+    writeLine(io.stderr, '- run: potentia routes generate');
+    return 1;
+  }
+
+  writeDiagnostics(io.stderr, result);
+  return 1;
+}
+
+function writeDiagnostics(stderr, result) {
+  writeLine(stderr, 'File route generation failed:');
+  const diagnostics = result.errors?.length ? result.errors : result.diagnostics || [];
+  for (const diagnostic of diagnostics) {
+    writeLine(stderr, formatDiagnostic(diagnostic));
+  }
+  if (diagnostics.length === 0) {
+    writeLine(stderr, '- POTENTIA_FILE_ROUTE_FAILED File route generation failed');
+  }
+}
+
+function usageError(error, options = {}) {
+  return {
+    ok: false,
+    error,
+    usage: USAGE,
+    json: Boolean(options.json),
+    command: options.command ?? null
+  };
+}
+
+function createInvalidUsageEnvelope(command) {
+  return {
+    ok: false,
+    command,
+    status: 'invalid-usage',
+    diagnostics: [{
+      code: 'POTENTIA_CLI_INVALID_USAGE',
+      message: USAGE
+    }]
+  };
+}
+
+function writeJson(stream, value) {
+  writeLine(stream, JSON.stringify(value));
+}
+
+function writeLine(stream, line) {
+  stream.write(`${line}\n`);
+}
+
+function safeErrorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function isMissingFileError(error) {
+  return error?.code === 'ENOENT';
+}
+
+function normalizeNewlines(value) {
+  return String(value).replace(/\r\n/g, '\n');
+}
+
+function isAbsolutePath(value) {
+  return String(value).startsWith('/') || /^[A-Za-z]:[\\/]/.test(String(value));
+}

package/src/dev/file-routing/diagnostics.js

@@ -0,0 +1,24 @@
+import { FILE_ROUTE_DIAGNOSTIC_CODES } from './path-mapping.js';
+
+export function routeCollisionDiagnostics(routes) {
+  const byPath = new Map();
+
+  for (const route of routes) {
+    const existing = byPath.get(route.routePath) || [];
+    existing.push(route);
+    byPath.set(route.routePath, existing);
+  }
+
+  const collisions = [];
+  for (const [routePath, entries] of byPath.entries()) {
+    if (entries.length < 2) continue;
+    collisions.push({
+      code: FILE_ROUTE_DIAGNOSTIC_CODES.COLLISION,
+      message: 'Multiple route files map to the same route path',
+      routePath: routePath,
+      files: entries.map((entry) => entry.filePath).sort()
+    });
+  }
+
+  return collisions.sort((a, b) => a.routePath.localeCompare(b.routePath));
+}

package/src/dev/file-routing/generator.js

@@ -0,0 +1,126 @@
+import path from 'node:path';
+
+import { normalizePath } from './path-mapping.js';
+
+export function generateRouteModule(scanResult, options = {}) {
+  const outputPath = normalizePath(options.outputPath || '.potentia/routes.generated.js');
+  const errors = Array.isArray(scanResult?.errors) ? scanResult.errors : [];
+
+  if (!scanResult || scanResult.ok === false || errors.length > 0) {
+    return {
+      ok: false,
+      source: '',
+      outputPath: outputPath,
+      imports: [],
+      errors: errors.length > 0 ? errors : [{ code: 'POTENTIA_FILE_ROUTE_INVALID_SCAN', message: 'Scan result is invalid' }]
+    };
+  }
+
+  const imports = buildImports(scanResult, outputPath);
+  const source = renderModule(scanResult, imports, options.packageName || '@potentiajs/core');
+
+  return {
+    ok: true,
+    source: source,
+    outputPath: outputPath,
+    imports: imports,
+    errors: []
+  };
+}
+
+function buildImports(scanResult, outputPath) {
+  const imports = [];
+  const outputDir = normalizePath(path.posix.dirname(outputPath));
+
+  scanResult.routes.forEach((route, index) => {
+    imports.push({
+      kind: 'route',
+      importName: `route${index}`,
+      importPath: relativeImport(outputDir, route.filePath),
+      filePath: route.filePath,
+      routePath: route.routePath,
+      segments: route.segments
+    });
+  });
+
+  scanResult.scopes.forEach((scope, index) => {
+    imports.push({
+      kind: 'scope',
+      importName: `scope${index}`,
+      importPath: relativeImport(outputDir, scope.filePath),
+      filePath: scope.filePath,
+      routePath: scope.routePath,
+      segments: scope.segments
+    });
+  });
+
+  return imports;
+}
+
+function renderModule(scanResult, imports, packageName) {
+  const routeImports = imports.filter((entry) => entry.kind === 'route');
+  const scopeImports = imports.filter((entry) => entry.kind === 'scope');
+  const lines = [
+    '// Generated by PotentiaJS. Do not edit by hand.',
+    `import { createRoutes, mount } from '${packageName}';`,
+    ''
+  ];
+
+  for (const entry of imports) {
+    lines.push(`import ${entry.importName} from '${entry.importPath}';`);
+  }
+
+  lines.push('', 'export default createRoutes({', '  routes: [');
+
+  const routeEntries = routeImports.map((entry) => ({
+    ...scanResult.routes.find((route) => route.filePath === entry.filePath),
+    importName: entry.importName
+  }));
+  const scopeEntries = scopeImports.map((entry) => ({
+    ...scanResult.scopes.find((scope) => scope.filePath === entry.filePath),
+    importName: entry.importName
+  }));
+  const grouped = routeEntries.filter((route) => shouldGroup(route, routeEntries, scopeEntries));
+  const direct = routeEntries.filter((route) => !grouped.includes(route));
+
+  for (const route of direct) {
+    lines.push(`    ${route.importName},`);
+  }
+
+  const groupNames = Array.from(new Set(grouped.map((route) => route.segments[0]))).sort();
+  for (const groupName of groupNames) {
+    const routes = grouped.filter((route) => route.segments[0] === groupName);
+    const scope = scopeEntries.find((entry) => entry.segments[0] === groupName && entry.segments.length === 1);
+    const prefix = `/${groupName}`;
+    lines.push('    mount(createRoutes({');
+    lines.push(`      prefix: '${prefix}',`);
+    if (scope) {
+      lines.push(`      hooks: ${scope.importName}.hooks,`);
+      lines.push(`      contracts: ${scope.importName}.contracts,`);
+      lines.push(`      meta: ${scope.importName}.meta,`);
+    }
+    lines.push('      routes: [');
+    for (const route of routes) {
+      lines.push(`        ${route.importName},`);
+    }
+    lines.push('      ]');
+    lines.push('    })),');
+  }
+
+  lines.push('  ]', '});', '');
+  return lines.join('\n');
+}
+
+function shouldGroup(route, allRoutes, scopes) {
+  if (route.segments.length < 2 && route.routePath !== `/${route.segments[0]}`) return false;
+  const first = route.segments[0];
+  if (!first) return false;
+  if (scopes.some((scope) => scope.segments[0] === first && scope.segments.length === 1)) return true;
+  return allRoutes.filter((candidate) => candidate.segments[0] === first).length > 1;
+}
+
+function relativeImport(fromDir, filePath) {
+  const relative = path.posix.relative(fromDir, normalizePath(filePath));
+  const normalized = relative.startsWith('.') ? relative : `./${relative}`;
+  return normalized.replaceAll('\\\\', '/');
+}

package/src/dev/file-routing/index.js

@@ -0,0 +1,5 @@
+export { routeCollisionDiagnostics } from './diagnostics.js';
+export { generateRouteModule } from './generator.js';
+export { FILE_ROUTE_DIAGNOSTIC_CODES, mapRouteFile, normalizePath } from './path-mapping.js';
+export { scanRouteTree } from './scanner.js';
+export { generateFileRoutes } from './writer.js';