statikapi 0.1.0

package/src/commands/preview.js

@@ -0,0 +1,320 @@
+import http from 'node:http';
+import fs from 'node:fs/promises';
+import fss from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { URL, fileURLToPath } from 'node:url';
+import { readFlags } from '../util/readFlags.js';
+import { loadConfig } from '../config/loadConfig.js';
+import { routeToOutPath } from '../build/routeOutPath.js';
+
+export default async function previewCmd(argv) {
+  // Keep old tests green: in non-TTY (node --test), behave like stub and exit.
+  if (!process.stdout.isTTY) {
+    console.log('statikapi preview → previewing built JSON (stub)');
+    return 0;
+  }
+
+  const flags = readFlags(argv || []);
+  const host = String(flags.host ?? '127.0.0.1');
+  const port = Number.isFinite(flags.port) ? Number(flags.port) : 8788;
+  const autoOpen = flags.open === true;
+
+  const { config } = await loadConfig({ flags });
+
+  // --- React UI defaults ---
+  // Prefer --uiDir; else use embedded UI inside this package; else proxy to Vite dev.
+  const here = path.dirname(fileURLToPath(import.meta.url)); // .../packages/cli/src/commands
+  const embeddedUi = path.resolve(here, '../../ui'); // .../packages/cli/ui
+  const uiDir = flags.uiDir ? path.resolve(String(flags.uiDir)) : embeddedUi;
+  const hasUi = uiDir && fss.existsSync(uiDir);
+
+  const uiDevHost = String(flags.uiDevHost ?? '127.0.0.1');
+  const uiDevPort = Number.isFinite(flags.uiDevPort) ? Number(flags.uiDevPort) : 5173;
+
+  const MIME = {
+    '.html': 'text/html; charset=utf-8',
+    '.js': 'application/javascript; charset=utf-8',
+    '.css': 'text/css; charset=utf-8',
+    '.json': 'application/json; charset=utf-8',
+    '.svg': 'image/svg+xml',
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.ico': 'image/x-icon',
+    '.map': 'application/json',
+  };
+
+  const outDir = config.paths.outAbs;
+  const manifestPath = path.join(outDir, '.statikapi', 'manifest.json');
+
+  const send = (res, code, body, headers = {}) => {
+    const h = {
+      'Cache-Control': 'no-store',
+      ...headers,
+    };
+    res.writeHead(code, h);
+    if (body && (typeof body === 'string' || Buffer.isBuffer(body))) res.end(body);
+    else res.end();
+  };
+
+  const notFound = (res, msg = 'Not found') =>
+    send(res, 404, JSON.stringify({ error: msg }) + '\n', {
+      'Content-Type': 'application/json; charset=utf-8',
+    });
+
+  const badReq = (res, msg) =>
+    send(res, 400, JSON.stringify({ error: msg }) + '\n', {
+      'Content-Type': 'application/json; charset=utf-8',
+    });
+
+  const etag = (buf) => `"sha1-${crypto.createHash('sha1').update(buf).digest('hex')}"`;
+
+  async function readManifest() {
+    try {
+      const raw = await fs.readFile(manifestPath);
+      return raw;
+    } catch {
+      return Buffer.from('[]', 'utf8');
+    }
+  }
+
+  // --- SSE: subscribers/broadcast ---
+  const clients = new Set(); // Set<http.ServerResponse>
+  function sseSend(res, data) {
+    // default "message" event with one data line
+    res.write(`data: ${data}\n\n`);
+  }
+  function broadcast(data) {
+    for (const res of clients) {
+      try {
+        sseSend(res, data);
+      } catch {
+        /* ignore */
+      }
+    }
+  }
+
+  // Simple proxy to Vite dev server (only used if no built UI is found)
+  async function proxyUi(req, res, uiPathname) {
+    const httpMod = uiDevHost.startsWith('https')
+      ? await import('node:https')
+      : await import('node:http');
+    const client = uiDevHost.startsWith('https') ? httpMod.default : httpMod.default;
+    const targetPath =
+      uiPathname + (req.url.includes('?') ? req.url.slice(req.url.indexOf('?')) : '');
+    const opts = {
+      hostname: uiDevHost,
+      port: uiDevPort,
+      method: req.method || 'GET',
+      path: targetPath,
+      headers: req.headers,
+    };
+    const p = client.request(opts, (up) => {
+      const headers = { ...up.headers };
+      // Always no-store for UI assets
+      headers['cache-control'] = 'no-store';
+      res.writeHead(up.statusCode || 502, headers);
+      up.pipe(res);
+    });
+    p.on('error', () => {
+      const msg = `StatikAPI UI dev server not found at http://${uiDevHost}:${uiDevPort}. Start it with: pnpm -w --filter packages/ui dev`;
+      res.writeHead(502, {
+        'Content-Type': 'text/plain; charset=utf-8',
+        'Cache-Control': 'no-store',
+      });
+      res.end(msg);
+    });
+    if (req.readable) req.pipe(p);
+    else p.end();
+  }
+
+  async function tryServeFrom(rootDir, reqPath, { spaFallback = null } = {}) {
+    const target = path.normalize(path.join(rootDir, reqPath.replace(/^\/+/, '')));
+    if (!target.startsWith(rootDir)) return null; // path traversal guard
+    try {
+      const st = await fs.stat(target);
+      if (st.isDirectory()) {
+        const idx = path.join(target, 'index.html');
+        const buf = await fs.readFile(idx);
+        return { buf, ctype: MIME['.html'] };
+      }
+      const buf = await fs.readFile(target);
+      const ext = path.extname(target).toLowerCase();
+      return { buf, ctype: MIME[ext] || 'application/octet-stream' };
+    } catch {
+      if (spaFallback) {
+        try {
+          const fallback = path.join(rootDir, spaFallback);
+          const buf = await fs.readFile(fallback);
+          return { buf, ctype: MIME['.html'] };
+        } catch {
+          /* ignore */
+        }
+      }
+      return null;
+    }
+  }
+
+  const server = http.createServer(async (req, res) => {
+    const base = `http://${host}:${port}`;
+    let url;
+    try {
+      url = new URL(req.url || '/', base);
+    } catch {
+      return notFound(res, 'Invalid URL');
+    }
+    const pathname = url.pathname;
+
+    // --- SSE subscription ---
+    if (pathname === '/_ui/events') {
+      res.writeHead(200, {
+        'Content-Type': 'text/event-stream; charset=utf-8',
+        'Cache-Control': 'no-store',
+        Connection: 'keep-alive',
+      });
+      res.write(': connected\n\n'); // comment line
+      clients.add(res);
+
+      // keepalive pings
+      const ping = setInterval(() => {
+        try {
+          res.write(': ping\n\n');
+        } catch {
+          // ignore write errors
+        }
+      }, 30000);
+
+      req.on('close', () => {
+        clearInterval(ping);
+        clients.delete(res);
+      });
+      return;
+    }
+
+    // Internal notify hook (used by dev watcher)
+    if (pathname === '/_ui/changed') {
+      const route = url.searchParams.get('route') || '';
+      broadcast(`changed:${route}`);
+      return send(res, 204, '');
+    }
+
+    // UI root always React: serve built dist if present; otherwise proxy to Vite dev
+    if (pathname === '/_ui' || pathname === '/ui' || pathname === '/ui/') {
+      if (hasUi) {
+        const served = await tryServeFrom(uiDir, 'index.html', { spaFallback: null });
+        if (served) {
+          return send(res, 200, served.buf, {
+            'Content-Type': served.ctype,
+            'Cache-Control': 'no-store',
+          });
+        }
+      }
+      return proxyUi(req, res, '/_ui/');
+    }
+
+    // Helper: manifest passthrough
+    if (pathname === '/_ui/index' || pathname === '/ui/index') {
+      const raw = await readManifest();
+      const tag = etag(raw);
+      if (req.headers['if-none-match'] === tag) {
+        res.writeHead(304, { ETag: tag, 'Cache-Control': 'no-store' });
+        return res.end();
+      }
+      return send(res, 200, raw, {
+        'Content-Type': 'application/json; charset=utf-8',
+        ETag: tag,
+      });
+    }
+
+    // Helper: stream a built JSON by route
+    if (pathname === '/_ui/file' || pathname === '/ui/file') {
+      const route = url.searchParams.get('route');
+      if (!route || !route.startsWith('/')) {
+        return badReq(res, 'query parameter "route" is required and must start with "/"');
+      }
+      const fileAbs = routeToOutPath({ outAbs: outDir, route });
+      if (!fss.existsSync(fileAbs)) return notFound(res, `No file for route: ${route}`);
+      res.writeHead(200, {
+        'Content-Type': 'application/json; charset=utf-8',
+        'X-StatikAPI-Route': route,
+        'X-StatikAPI-File': path.relative(process.cwd(), fileAbs).replaceAll(path.sep, '/'),
+        'Cache-Control': 'no-store',
+      });
+      fss.createReadStream(fileAbs).pipe(res);
+      return;
+    }
+
+    // Serve UI assets: built if present, else proxy to Vite dev
+    if (pathname.startsWith('/_ui') || pathname.startsWith('/ui')) {
+      if (hasUi) {
+        const rel = pathname.replace(/^\/_?ui\/?/, '');
+        const reqPath = rel === '' ? 'index.html' : rel;
+        const served = await tryServeFrom(uiDir, reqPath, { spaFallback: 'index.html' });
+        if (served) {
+          return send(res, 200, served.buf, {
+            'Content-Type': served.ctype,
+            'Cache-Control': 'no-store',
+          });
+        }
+        return notFound(res);
+      }
+      return proxyUi(req, res, pathname);
+    }
+
+    // Static serve from api-out (best-effort)
+    const safe = path.normalize(path.join(outDir, pathname));
+    if (!safe.startsWith(outDir)) return notFound(res);
+    try {
+      const stat = await fs.stat(safe);
+      if (stat.isDirectory()) {
+        const idx = path.join(safe, 'index.json');
+        const s2 = await fs.readFile(idx);
+        return send(res, 200, s2, { 'Content-Type': 'application/json; charset=utf-8' });
+      } else {
+        const buf = await fs.readFile(safe);
+        const ctype = safe.endsWith('.json')
+          ? 'application/json; charset=utf-8'
+          : 'text/plain; charset=utf-8';
+        return send(res, 200, buf, { 'Content-Type': ctype });
+      }
+    } catch {
+      return notFound(res);
+    }
+  });
+
+  await new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(port, host, resolve);
+  });
+
+  const url = `http://${host}:${port}/_ui`;
+  console.log(`statikapi preview → serving ${path.relative(process.cwd(), outDir) || outDir}`);
+  console.log(`open  ${url}`);
+
+  if (autoOpen) {
+    openBrowser(url).catch(() => {});
+  }
+
+  // Graceful shutdown
+  await new Promise((resolve) => {
+    const stop = () => server.close(() => resolve());
+    process.on('SIGINT', stop);
+    process.on('SIGTERM', stop);
+  });
+  return 0;
+}
+
+async function openBrowser(url) {
+  const { exec } = await import('node:child_process');
+  const plat = process.platform;
+  return new Promise((resolve) => {
+    const cmd =
+      plat === 'darwin'
+        ? `open "${url}"`
+        : plat === 'win32'
+          ? `start "" "${url}"`
+          : `xdg-open "${url}"`;
+    exec(cmd, () => resolve());
+  });
+}

package/src/config/defaults.js

@@ -0,0 +1,4 @@
+export const DEFAULT_CONFIG = {
+  srcDir: 'src-api',
+  outDir: 'api-out',
+};

package/src/config/loadConfig.js

@@ -0,0 +1,46 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { DEFAULT_CONFIG } from './defaults.js';
+import { validateAndNormalize, ConfigError } from './validate.js';
+
+export async function loadConfig({ cwd = process.cwd(), flags = {} } = {}) {
+  const file = path.join(cwd, 'statikapi.config.js');
+  let fromFile = false;
+  let fileCfg = {};
+
+  try {
+    await fs.access(file);
+    fromFile = true;
+    const mod = await import(pathToFileURL(file).href);
+    fileCfg = (mod?.default ?? mod?.config ?? mod) || {};
+    if (typeof fileCfg !== 'object' || fileCfg == null || Array.isArray(fileCfg)) {
+      throw new ConfigError('Config file must export an object (default or named "config")');
+    }
+  } catch (err) {
+    if (err?.code !== 'ENOENT') {
+      const e = err instanceof Error ? err : new Error(String(err));
+      e.message = `Failed to load "statikapi.config.js": ${e.message}`;
+      throw e;
+    }
+    // no config file → fine
+  }
+
+  // Merge: defaults <- file <- flags
+  const merged = {
+    ...DEFAULT_CONFIG,
+    ...fileCfg,
+    ...pickFlags(flags),
+  };
+
+  // Validate & expand absolute paths
+  const finalCfg = validateAndNormalize(merged, { cwd });
+  return { config: finalCfg, source: { fromFile, filePath: file } };
+}
+
+function pickFlags(flags) {
+  const o = {};
+  if (flags.srcDir != null) o.srcDir = String(flags.srcDir);
+  if (flags.outDir != null) o.outDir = String(flags.outDir);
+  return o;
+}

package/src/config/validate.js

@@ -0,0 +1,39 @@
+import path from 'node:path';
+
+export class ConfigError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'ConfigError';
+  }
+}
+
+export function validateAndNormalize(userCfg, { cwd = process.cwd() } = {}) {
+  const cfg = { ...userCfg };
+
+  for (const key of ['srcDir', 'outDir']) {
+    if (typeof cfg[key] !== 'string' || !cfg[key].trim()) {
+      throw new ConfigError(`"${key}" must be a non-empty string`);
+    }
+    if (path.isAbsolute(cfg[key])) {
+      throw new ConfigError(`"${key}" must be a relative path. Got absolute: ${cfg[key]}`);
+    }
+    // normalize separators & remove ./ and a/../b
+    const normalized = path.posix.normalize(cfg[key].replaceAll(path.sep, '/'));
+    if (normalized.startsWith('..')) {
+      throw new ConfigError(`"${key}" cannot traverse outside the project: ${normalized}`);
+    }
+    cfg[key] = normalized;
+  }
+
+  if (cfg.srcDir === cfg.outDir) {
+    throw new ConfigError(`"srcDir" and "outDir" must differ (both "${cfg.srcDir}")`);
+  }
+
+  return {
+    ...cfg,
+    paths: {
+      srcAbs: path.join(cwd, cfg.srcDir),
+      outAbs: path.join(cwd, cfg.outDir),
+    },
+  };
+}

package/src/help.js

@@ -0,0 +1,21 @@
+export const HELP = `statikapi — Static API generator
+
+Usage:
+  statikapi <command> [options]
+
+Commands:
+  init        Scaffold a new StatikAPI project
+  build       Build static JSON endpoints
+  dev         Start dev mode (watch & rebuild)
+  preview     Serve the built JSON files
+
+Global options:
+  -h, --help      Show help
+  -v, --version   Show version
+
+Examples:
+  statikapi init
+  statikapi build
+  statikapi dev
+  statikapi preview
+`;

package/src/index.js

@@ -0,0 +1,38 @@
+import { createRequire } from 'node:module';
+import { HELP } from './help.js';
+import initCmd from './commands/init.js';
+import buildCmd from './commands/build.js';
+import devCmd from './commands/dev.js';
+import previewCmd from './commands/preview.js';
+
+const require = createRequire(import.meta.url);
+const { version } = require('../package.json');
+
+export async function run(argv = process.argv.slice(2)) {
+  const [cmd, ...rest] = argv;
+
+  if (!cmd || cmd === '-h' || cmd === '--help') {
+    console.log(HELP);
+    return 0;
+  }
+
+  if (cmd === '-v' || cmd === '--version') {
+    console.log(`statikapi v${version}`);
+    return 0;
+  }
+
+  switch (cmd) {
+    case 'init':
+      return await initCmd(rest);
+    case 'build':
+      return await buildCmd(rest);
+    case 'dev':
+      return await devCmd(rest);
+    case 'preview':
+      return await previewCmd(rest);
+    default:
+      console.error(`Unknown command: ${cmd}\n`);
+      console.log(HELP);
+      return 1;
+  }
+}

package/src/loader/errors.js

@@ -0,0 +1,15 @@
+export class LoaderError extends Error {
+  constructor(file, message) {
+    super(`[module:${file}] ${message}`);
+    this.name = 'LoaderError';
+    this.file = file;
+  }
+}
+
+export class SerializationError extends Error {
+  constructor(message, atPath) {
+    super(`${message}${atPath ? ` at ${atPath}` : ''}`);
+    this.name = 'SerializationError';
+    this.atPath = atPath || '$';
+  }
+}

package/src/loader/loadModuleValue.js

@@ -0,0 +1,60 @@
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { LoaderError } from './errors.js';
+import { assertSerializable } from './serializeGuard.js';
+
+/**
+ * Load a module file (ESM or CJS), resolve its value:
+ *  - if it exports `async function data()`, call it (no args) and await.
+ *  - else if default export is a function, call and await.
+ *  - else if default export is a value, use it.
+ * Then verify JSON-serializability.
+ */
+export async function loadModuleValue(fileAbs, args = {}) {
+  const fresh = args?.__fresh === true; // dev watcher sets this
+
+  const fileInfo = short(fileAbs);
+  let mod;
+  try {
+    const u = new URL(pathToFileURL(fileAbs).href);
+    if (fresh) u.search = `v=${Date.now()}-${Math.random()}`;
+    mod = await import(u.href);
+  } catch (e) {
+    throw new LoaderError(fileInfo, `Failed to import: ${e.message}`);
+  }
+
+  let producer = null;
+  if (typeof mod?.data === 'function') producer = mod.data;
+  else if (typeof mod?.default === 'function') producer = mod.default;
+
+  let value;
+  try {
+    if (producer) value = await producer(args);
+    else if ('default' in (mod || {})) value = mod.default;
+    else
+      throw new LoaderError(
+        fileInfo,
+        `No export found. Use 'export async function data()' or 'export default <value|function>'.`
+      );
+  } catch (e) {
+    if (e instanceof LoaderError) throw e;
+    throw new LoaderError(fileInfo, `Error executing module: ${e.message}`);
+  }
+
+  try {
+    assertSerializable(value, '$');
+  } catch (e) {
+    throw new LoaderError(fileInfo, `Not JSON-serializable: ${e.message}`);
+  }
+
+  return value;
+}
+
+function short(p) {
+  // Show path relative to repo root for nicer messages
+  try {
+    return path.relative(process.cwd(), p) || p;
+  } catch {
+    return p;
+  }
+}

package/src/loader/loadPaths.js

@@ -0,0 +1,102 @@
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { LoaderError } from './errors.js';
+
+export async function loadPaths(fileAbs, { route, type, segments }, { fresh = false } = {}) {
+  const fileInfo = short(fileAbs);
+  let mod;
+  try {
+    const u = new URL(pathToFileURL(fileAbs).href);
+    if (fresh) u.search = `v=${Date.now()}-${Math.random()}`;
+    mod = await import(u.href);
+  } catch (e) {
+    throw new LoaderError(fileInfo, `Failed to import for paths(): ${e.message}`);
+  }
+  if (typeof mod?.paths !== 'function') return null;
+
+  let res;
+  try {
+    res = await mod.paths();
+  } catch (e) {
+    throw new LoaderError(fileInfo, `paths() threw: ${e.message}`);
+  }
+  if (!Array.isArray(res)) {
+    throw new LoaderError(fileInfo, `paths() must return an array`);
+  }
+
+  if (type === 'dynamic') {
+    // /users/:id → string[]
+    for (const v of res) {
+      if (typeof v !== 'string')
+        throw new LoaderError(fileInfo, `paths() for ${route} must be string[]`);
+      if (!v)
+        throw new LoaderError(
+          fileInfo,
+          `paths() entry for :${paramName(segments)} cannot be empty`
+        );
+      if (v.includes('/'))
+        throw new LoaderError(
+          fileInfo,
+          `paths() entry for :${paramName(segments)} must not contain '/'`
+        );
+    }
+    return res.map((v) => [v]); // normalize to array-of-segments
+  }
+
+  if (type === 'catchall') {
+    // /docs/*slug → (string | string[])[]
+    const out = [];
+    for (const v of res) {
+      if (typeof v === 'string') {
+        if (!v)
+          throw new LoaderError(
+            fileInfo,
+            `paths() entry for *${paramName(segments)} must be non-empty`
+          );
+        out.push([v]);
+      } else if (Array.isArray(v)) {
+        if (v.length === 0) {
+          throw new LoaderError(
+            fileInfo,
+            `paths() entry for *${paramName(segments)} must be non-empty`
+          );
+        }
+        for (const s of v) {
+          if (typeof s !== 'string' || !s) {
+            throw new LoaderError(
+              fileInfo,
+              `paths() entry for *${paramName(segments)} must contain non-empty strings`
+            );
+          }
+          if (s.includes('/')) {
+            throw new LoaderError(
+              fileInfo,
+              `paths() entry segment for *${paramName(segments)} must not contain '/'`
+            );
+          }
+        }
+        out.push(v);
+      } else {
+        throw new LoaderError(fileInfo, `paths() for ${route} must be (string | string[])[]`);
+      }
+    }
+    return out;
+  }
+
+  // static shouldn't have paths()
+  return null;
+}
+
+function paramName(segTokens) {
+  // segTokens like ['users', ':id'] or ['docs','*slug']
+  const tok = segTokens.find((t) => t.startsWith(':') || t.startsWith('*'));
+  return tok ? tok.slice(1) : 'param';
+}
+
+function short(p) {
+  try {
+    return path.relative(process.cwd(), p) || p;
+  } catch {
+    return p;
+  }
+}