statikapi 0.1.0

package/README.md

@@ -0,0 +1,160 @@
+# statikapi — Static API generator (CLI)
+
+Build a folder of JSON endpoints from simple files, then preview them in a lightweight UI.
+
+> Requires **Node 18+**.
+
+## Install
+
+Use without installing (recommended):
+
+```
+npx statikapi --help
+
+Or add to a project
+pnpm add -D statikapi
+# npm i -D statikapi
+# yarn add -D statikapi
+```
+
+## Commands
+
+```
+statikapi <command> [options]
+
+Commands:
+  init        Scaffold a new StatikAPI project
+  build       Build static JSON endpoints
+  dev         Watch & rebuild on changes
+  preview     Serve the built JSON files + UI
+
+Global:
+  -h, --help      Show help
+  -v, --version   Show version
+```
+
+##Quick start
+
+```
+# 1) Create a folder with API sources
+
+mkdir src-api
+echo "export default { hello: 'world' }" > src-api/index.js
+
+# 2) Build
+
+npx statikapi build --pretty
+
+# 3) Preview (opens http://127.0.0.1:8788/_ui)
+
+npx statikapi preview
+```
+
+## Project layout
+
+- src-api/: your source files (default; configurable)
+- api-out/: generated JSON, one folder per route (default)
+
+Examples of file → route mapping:
+
+File Route Output file
+src-api/index.js / api-out/index.json
+src-api/blog/archive.js /blog/archive api-out/blog/archive/index.json
+src-api/users/[id].js /users/:id dynamic (see below)
+src-api/docs/[...slug].js /docs/\*slug catch-all (see below)
+
+## Dynamic routes
+
+For src-api/users/[id].js, export a paths() function that returns the concrete IDs to prebuild:
+
+```
+// src-api/users/[id].js
+export async function paths() {
+return ['1', '2', '3']; // builds /users/1, /users/2, /users/3
+}
+
+export async function data({ params }) {
+return { id: params.id };
+}
+```
+
+Catch-all works similarly:
+
+```
+// src-api/docs/[...slug].js
+export async function paths() {
+return [['a', 'b'], ['guide']]; // → /docs/a/b and /docs/guide
+}
+export async function data({ params }) {
+return { slug: params.slug, path: params.slug.join('/') };
+}
+```
+
+## Producing data
+
+Each module can export either:
+
+- `export async function data(ctx) { ... }` → its return value is serialized, or
+- `export default <value|function>` → if a function, it’s called and awaited.
+
+Returned data must be JSON-serializable (plain objects/arrays, finite numbers, no functions, etc.).
+
+## Config
+
+You can optionally add statikapi.config.js in your project root:
+
+```
+export default {
+srcDir: 'src-api',
+outDir: 'api-out',
+};
+```
+
+You can override via flags: `--srcDir <dir>`, `--outDir <dir>`.
+
+## Flags (per command)
+
+`build`
+
+- `--pretty` (or `--minify=false`) — pretty-print JSON.
+- `--srcDir`, `--outDir` — override config paths.
+
+`dev`
+
+- Rebuilds on changes, updates the preview UI via SSE.
+- `--previewHost`, `--previewPort` — where to notify the preview server.
+- `--srcDir`, `--outDir` — override config paths.
+
+`preview`
+
+- Serves `api-out/` and the UI at `/\_ui`.
+- `--host` (default 127.0.0.1)
+- `--port` (default 8788)
+- `--open` — try to open the browser
+- UI source:
+  - `--uiDir <path>` — serve a built UI from this directory
+  - Otherwise, uses the embedded UI bundled with the CLI
+  - If missing, proxies to a dev UI at `http://127.0.0.1:5173` (override with `--uiDevHost`, `--uiDevPort`)
+
+## Examples
+
+There are two example projects in this repo under `example/`:
+
+```
+# from repo root
+
+pnpm -C example/basic dev
+pnpm -C example/basic preview
+
+pnpm -C example/dynamic dev
+pnpm -C example/dynamic preview
+```
+
+## Troubleshooting
+
+- UI doesn’t load: ensure `preview` is running; if you’re developing the UI separately, start Vite on port 5173 or pass `--uiDir` to serve a built UI.
+- Dynamic routes not emitted: make sure the file exports a valid `paths()` function returning strings (or arrays of strings for catch-all).
+
+License
+
+ISC – see LICENSE

package/bin/statikapi.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { run } from '../src/index.js';
+
+// pass argv explicitly
+const code = await run(process.argv.slice(2));
+
+// let stdout/stderr flush; still returns non-zero on failure
+process.exitCode = Number.isInteger(code) ? code : 0;

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "statikapi",
+  "version": "0.1.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/zonayedpca/statikapi",
+    "directory": "packages/cli"
+  },
+  "bugs": { "url": "https://github.com/zonayedpca/statikapi/issues" },
+  "homepage": "https://github.com/zonayedpca/statikapi#readme",
+  "type": "module",
+  "bin": { "statikapi": "bin/statikapi.js" },
+  "files": ["bin", "dist", "ui", "src", "README.md", "LICENSE"],
+  "exports": { ".": { "import": "./src/index.js" } },
+  "engines": { "node": ">=18" },
+  "license": "MIT",
+  "keywords": ["static", "json", "api", "cli", "ssg"],
+  "publishConfig": { "access": "public", "provenance": true },
+  "dependencies": {
+    "chokidar": "^3.6.0"
+  },
+  "scripts": {
+    "build": "node ./scripts/build.js || true",
+    "sync-ui": "rm -rf ui && mkdir -p ui && cp -R ../ui/dist/* ui/",
+    "prepack": "pnpm -w --filter @statikapi/ui build && pnpm run sync-ui"
+  }
+}

package/src/build/routeOutPath.js

@@ -0,0 +1,8 @@
+import path from 'node:path';
+
+/** Map a route to an output JSON file (index.json style). Static routes only. */
+export function routeToOutPath({ outAbs, route }) {
+  // '/' -> index.json, '/users' -> users/index.json, '/blog/archive' -> blog/archive/index.json
+  const rel = route === '/' ? 'index.json' : route.slice(1) + '/index.json';
+  return path.join(outAbs, rel);
+}

package/src/commands/build.js

@@ -0,0 +1,191 @@
+import { readFlags } from '../util/readFlags.js'; // from Task 3
+import { loadConfig } from '../config/loadConfig.js'; // from Task 3
+import { ConfigError } from '../config/validate.js'; // from Task 3
+import { mapRoutes } from '../router/mapRoutes.js'; // from Task 4
+import { loadModuleValue } from '../loader/loadModuleValue.js'; // from Task 5
+import { loadPaths } from '../loader/loadPaths.js';
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import crypto from 'node:crypto';
+
+import { emptyDir, writeFileEnsured } from '../util/fsx.js';
+import { routeToOutPath } from '../build/routeOutPath.js';
+import { formatBytes } from '../util/bytes.js';
+
+function toConcrete(routePattern, segTokens, segs) {
+  // segTokens: ['users', ':id'] or ['docs','*slug']
+  // segs: ['1'] or ['a','b']
+  let idx = 0;
+  const parts = routePattern.split('/').map((p) => {
+    if (p.startsWith(':')) return segs[idx++] ?? '';
+    if (p.startsWith('*')) return segs.slice(idx).join('/');
+    return p;
+  });
+  const concrete = parts.join('/').replace(/\/+/g, '/');
+  return concrete;
+}
+
+function toParams(segTokens, concreteRoute) {
+  const concreteSegs = concreteRoute.split('/').filter(Boolean);
+  const params = {};
+
+  for (let i = 0; i < segTokens.length; i++) {
+    const tok = segTokens[i];
+    if (tok.startsWith(':')) {
+      params[tok.slice(1)] = concreteSegs[i] ?? '';
+    } else if (tok.startsWith('*')) {
+      params[tok.slice(1)] = concreteSegs.slice(i);
+      break;
+    }
+  }
+  return params;
+}
+
+export default async function buildCmd(argv) {
+  const t0 = Date.now();
+  try {
+    const flags = readFlags(argv);
+    const { config } = await loadConfig({ flags });
+
+    const pretty = flags.pretty === true || flags.minify === false;
+    const space = pretty ? 2 : 0;
+
+    // keep legacy-friendly stub line so the old test passes
+    console.log('statikapi build → building JSON endpoints (MVP)');
+
+    // discover routes
+    const routes = await mapRoutes({ srcAbs: config.paths.srcAbs });
+
+    // MVP: only handle static routes (dynamic/catch-all in next task)
+    const staticRoutes = routes.filter((r) => r.type === 'static');
+    const dynRoutes = routes.filter((r) => r.type === 'dynamic');
+    const catRoutes = routes.filter((r) => r.type === 'catchall');
+
+    // prepare outDir (clean, then write)
+    await emptyDir(config.paths.outAbs);
+
+    let fileCount = 0;
+    let byteCount = 0;
+    let skippedDynamic = 0;
+    const manifest = []; // array of unified entries
+
+    const digest = (s) => crypto.createHash('sha1').update(s).digest('hex');
+    const relSrc = (abs) => {
+      try {
+        return path.relative(process.cwd(), abs) || abs;
+      } catch {
+        return abs;
+      }
+    };
+
+    const relOut = (abs) => {
+      try {
+        return path.relative(process.cwd(), abs).replaceAll(path.sep, '/') || abs;
+      } catch {
+        return abs;
+      }
+    };
+
+    async function pushManifest({ route, srcFile, outFile, json }) {
+      const st = await fs.stat(outFile).catch(() => null);
+      const entry = {
+        // stable field order
+        route,
+        outFile: relOut(outFile),
+        srcFile: relSrc(srcFile),
+        // backward-compat (old tests read filePath → output path)
+        filePath: relOut(outFile),
+        bytes: Buffer.byteLength(json),
+        mtime: st ? st.mtimeMs : Date.now(),
+        hash: digest(json),
+        revalidate: null,
+      };
+      manifest.push(entry);
+    }
+
+    for (const r of staticRoutes) {
+      const val = await loadModuleValue(r.file);
+      const json = JSON.stringify(val, null, space) + (pretty ? '\n' : '');
+      const outFile = routeToOutPath({ outAbs: config.paths.outAbs, route: r.route });
+      await writeFileEnsured(outFile, json);
+      fileCount++;
+      byteCount += Buffer.byteLength(json);
+
+      await pushManifest({ route: r.route, srcFile: r.file, outFile, json });
+    }
+
+    // helper: materialize a concrete route from tokens + param segments
+    async function emitConcreteRoute(r, segs) {
+      const concreteRoute = toConcrete(r.route, r.segments, segs);
+      const params = toParams(r.segments, concreteRoute);
+      const val = await loadModuleValue(r.file, { params });
+      const json = JSON.stringify(val, null, space) + (pretty ? '\n' : '');
+      const outFile = routeToOutPath({ outAbs: config.paths.outAbs, route: concreteRoute });
+      await writeFileEnsured(outFile, json);
+      fileCount++;
+      byteCount += Buffer.byteLength(json);
+
+      await pushManifest({ route: concreteRoute, srcFile: r.file, outFile, json });
+    }
+
+    // dynamic: expect [['val'], ...] from loadPaths()
+    for (const r of dynRoutes) {
+      const list = await loadPaths(r.file, r);
+      if (!list) {
+        skippedDynamic++;
+        continue;
+      }
+      const seen = new Set();
+      for (const segs of list) {
+        const concrete = toConcrete(r.route, r.segments, segs);
+        if (seen.has(concrete)) continue;
+        seen.add(concrete);
+        await emitConcreteRoute(r, segs);
+      }
+    }
+
+    // catch-all: expect [['a','b'], ['guide'], ...]
+    for (const r of catRoutes) {
+      const list = await loadPaths(r.file, r);
+      if (!list) {
+        skippedDynamic++;
+        continue;
+      }
+      const seen = new Set();
+      for (const segs of list) {
+        const concrete = toConcrete(r.route, r.segments, segs);
+        if (seen.has(concrete)) continue;
+        seen.add(concrete);
+        await emitConcreteRoute(r, segs);
+      }
+    }
+
+    // Write manifest once (sorted for determinism)
+    const manifestPath = path.join(config.paths.outAbs, '.statikapi', 'manifest.json');
+    const sorted = manifest.sort((a, b) => a.route.localeCompare(b.route));
+    const manifestJson = JSON.stringify(sorted, null, pretty ? 2 : 0) + (pretty ? '\n' : '');
+    await writeFileEnsured(manifestPath, manifestJson);
+    byteCount += Buffer.byteLength(manifestJson);
+    fileCount++;
+
+    const elapsed = Date.now() - t0;
+
+    const extra = skippedDynamic ? `, skipped ${skippedDynamic} dynamic route(s)` : '';
+    console.log(
+      `[statikapi] wrote ${fileCount} file(s), ${formatBytes(byteCount)} in ${elapsed} ms${extra}`
+    );
+    return 0;
+  } catch (err) {
+    if (err instanceof ConfigError) {
+      console.error(`[statikapi] Config error: ${err.message}`);
+      return 1;
+    }
+    // LoaderError already includes file path; show as-is
+    if (err && err.name === 'LoaderError') {
+      console.error(`[statikapi] ${err.message}`);
+      return 1;
+    }
+    console.error('[statikapi] Build failed:', err?.stack || err?.message || err);
+    return 1;
+  }
+}

package/src/commands/dev.js

@@ -0,0 +1,249 @@
+import chokidar from 'chokidar';
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import crypto from 'node:crypto';
+import { readFlags } from '../util/readFlags.js';
+import { loadConfig } from '../config/loadConfig.js';
+import { mapRoutes, fileToRoute } from '../router/mapRoutes.js';
+import { routeToOutPath } from '../build/routeOutPath.js';
+import { writeFileEnsured } from '../util/fsx.js';
+import { loadModuleValue } from '../loader/loadModuleValue.js';
+import { loadPaths } from '../loader/loadPaths.js';
+
+function clearScreen() {
+  process.stdout.write('\x1Bc'); // ANSI "clear screen"
+}
+
+function toConcrete(routePattern, segTokens, segs) {
+  let idx = 0;
+  const parts = routePattern.split('/').map((p) => {
+    if (p.startsWith(':')) return segs[idx++] ?? '';
+    if (p.startsWith('*')) return segs.slice(idx).join('/');
+    return p;
+  });
+  return parts.join('/').replace(/\/+/g, '/');
+}
+
+function toParams(segTokens, concreteRoute) {
+  const concreteSegs = concreteRoute.split('/').filter(Boolean);
+  const params = {};
+  for (let i = 0; i < segTokens.length; i++) {
+    const tok = segTokens[i];
+    if (tok.startsWith(':')) params[tok.slice(1)] = concreteSegs[i] ?? '';
+    else if (tok.startsWith('*')) {
+      params[tok.slice(1)] = concreteSegs.slice(i);
+      break;
+    }
+  }
+  return params;
+}
+
+export default async function devCmd(argv) {
+  // In non-TTY (like node --test), behave like the old stub so tests don't hang.
+  if (!process.stdout.isTTY) {
+    console.log('statikapi dev → starting dev server (stub)');
+    return 0;
+  }
+
+  const flags = readFlags(argv);
+  const { config } = await loadConfig({ flags });
+
+  // Where to notify preview
+  const previewHost = String(flags.previewHost ?? '127.0.0.1');
+  const previewPort = Number.isFinite(flags.previewPort) ? Number(flags.previewPort) : 8788;
+  const notifyOrigin = `http://${previewHost}:${previewPort}`;
+
+  async function notifyChanged(route) {
+    try {
+      // Node 18+ has global fetch
+      const u = `${notifyOrigin}/_ui/changed?route=${encodeURIComponent(route)}`;
+      await fetch(u, { method: 'POST' }).catch(() => {});
+    } catch {
+      // Ignore if preview isn't running
+    }
+  }
+
+  // Cache of outputs per source file (for deletions on subsequent rebuilds)
+  const lastEmitted = new Map(); // fileAbs -> Set<concreteRoute>
+
+  // Manifest state
+  const manifestByRoute = new Map(); // route -> entry
+  const digest = (s) => crypto.createHash('sha1').update(s).digest('hex');
+  const relSrc = (abs) => {
+    try {
+      return path.relative(process.cwd(), abs) || abs;
+    } catch {
+      return abs;
+    }
+  };
+  const relOut = (abs) => {
+    try {
+      return path.relative(process.cwd(), abs).replaceAll(path.sep, '/') || abs;
+    } catch {
+      return abs;
+    }
+  };
+  async function writeManifest() {
+    const list = Array.from(manifestByRoute.values()).sort((a, b) =>
+      a.route.localeCompare(b.route)
+    );
+    const json = JSON.stringify(list, null, 2) + '\n';
+    await writeFileEnsured(path.join(config.paths.outAbs, '.statikapi', 'manifest.json'), json);
+  }
+  async function upsertManifest({ route, srcFile, outFile, json }) {
+    const st = await fs.stat(outFile).catch(() => null);
+
+    const entry = {
+      route,
+      outFile: relOut(outFile),
+      srcFile: relSrc(srcFile),
+      filePath: relOut(outFile), // backward-compat alias
+      bytes: Buffer.byteLength(json),
+      mtime: st ? st.mtimeMs : Date.now(),
+      hash: digest(json),
+      revalidate: null,
+    };
+    manifestByRoute.set(route, entry);
+  }
+  function deleteFromManifest(route) {
+    manifestByRoute.delete(route);
+  }
+
+  async function emitStatic(r, { fresh = false } = {}) {
+    const val = await loadModuleValue(r.file, { __fresh: fresh });
+    const json = JSON.stringify(val, null, 2) + '\n';
+    const outFile = routeToOutPath({ outAbs: config.paths.outAbs, route: r.route });
+    await writeFileEnsured(outFile, json);
+    lastEmitted.set(r.file, new Set([r.route]));
+    await upsertManifest({ route: r.route, srcFile: r.file, outFile, json });
+    // notify UI
+    await notifyChanged(r.route);
+    return 1;
+  }
+
+  async function emitDynamic(r, { fresh = false } = {}) {
+    const list = await loadPaths(r.file, r, { fresh });
+    if (!list) {
+      lastEmitted.set(r.file, new Set());
+      return { written: 0, skipped: 1 };
+    }
+    const seen = new Set();
+    const emittedRoutes = new Set();
+    let written = 0;
+    for (const segs of list) {
+      const concrete = toConcrete(r.route, r.segments, segs);
+      if (seen.has(concrete)) continue;
+      seen.add(concrete);
+      const params = toParams(r.segments, concrete);
+      const val = await loadModuleValue(r.file, { params, __fresh: fresh });
+      const json = JSON.stringify(val, null, 2) + '\n';
+      const outFile = routeToOutPath({ outAbs: config.paths.outAbs, route: concrete });
+      await writeFileEnsured(outFile, json);
+      emittedRoutes.add(concrete);
+      await upsertManifest({ route: concrete, srcFile: r.file, outFile, json });
+      written++;
+    }
+    // Delete stale outputs from this file (not present anymore)
+    const prev = lastEmitted.get(r.file) || new Set();
+    for (const oldRoute of prev) {
+      if (!emittedRoutes.has(oldRoute)) {
+        const p = routeToOutPath({ outAbs: config.paths.outAbs, route: oldRoute });
+        try {
+          await fs.rm(p, { force: true });
+        } catch {
+          // ignore
+        }
+        deleteFromManifest(oldRoute);
+        await notifyChanged(oldRoute);
+      }
+    }
+    lastEmitted.set(r.file, emittedRoutes);
+
+    // notify UI for all emitted routes
+    for (const route of emittedRoutes) {
+      await notifyChanged(route);
+    }
+
+    return { written, skipped: 0 };
+  }
+
+  function shouldHandle(fileAbs) {
+    const rel = path.posix.normalize(
+      fileAbs.replaceAll(path.sep, '/').slice(config.paths.srcAbs.length + 1)
+    );
+    if (!rel) return false;
+    if (rel.startsWith('_')) return false;
+    const ext = path.extname(rel);
+    return ext === '.js' || ext === '.mjs' || ext === '.cjs';
+  }
+
+  async function buildOne(fileAbs, kind) {
+    if (!shouldHandle(fileAbs)) return;
+    const info = fileToRoute({ srcAbs: config.paths.srcAbs, fileAbs });
+    clearScreen();
+    console.log(`statikapi dev → ${kind}: ${path.relative(process.cwd(), fileAbs)}`);
+
+    if (!info) {
+      // File is ignored or no longer maps; delete prior outputs if any
+      const prev = lastEmitted.get(fileAbs);
+      if (prev) {
+        for (const route of prev) {
+          const p = routeToOutPath({ outAbs: config.paths.outAbs, route });
+          try {
+            await fs.rm(p, { force: true });
+          } catch {
+            // ignore
+          }
+          deleteFromManifest(route);
+          await notifyChanged(route);
+        }
+        lastEmitted.delete(fileAbs);
+      }
+      console.log(`[statikapi] (ignored or unmapped)`);
+      await writeManifest();
+      return;
+    }
+
+    const r = { file: fileAbs, route: info.route, type: info.type, segments: info.normSegments };
+    try {
+      if (r.type === 'static') {
+        const files = await emitStatic(r, { fresh: true });
+        console.log(`[statikapi] wrote ${files} file(s) for ${r.route}`);
+      } else {
+        const { written, skipped } = await emitDynamic(r, { fresh: true });
+        const extra = skipped ? `, skipped ${skipped}` : '';
+        console.log(`[statikapi] wrote ${written} file(s) for ${r.route}${extra}`);
+      }
+      await writeManifest();
+    } catch (err) {
+      console.error(`[statikapi] ${err?.message || err}`);
+    }
+  }
+
+  // Initial full build
+  clearScreen();
+  console.log('statikapi dev → initial build…');
+  const routes = await mapRoutes({ srcAbs: config.paths.srcAbs });
+  for (const r of routes) {
+    if (r.type === 'static') await emitStatic(r);
+    else await emitDynamic(r);
+  }
+  await writeManifest();
+  console.log(`[statikapi] ready. Watching ${path.relative(process.cwd(), config.paths.srcAbs)}/`);
+
+  const watcher = chokidar.watch(config.paths.srcAbs, {
+    ignoreInitial: true,
+    ignored: (p) => path.basename(p).startsWith('_'),
+  });
+  watcher.on('add', (p) => buildOne(p, 'add'));
+  watcher.on('change', (p) => buildOne(p, 'change'));
+  watcher.on('unlink', (p) => buildOne(p, 'unlink'));
+
+  // Keep process alive until SIGINT
+  await new Promise((resolve) => {
+    const stop = () => watcher.close().then(resolve).catch(resolve);
+    process.on('SIGINT', stop);
+    process.on('SIGTERM', stop);
+  });
+  return 0;
+}

package/src/commands/init.js

@@ -0,0 +1,10 @@
+export default async function initCmd() {
+  console.log('statikapi init → use `npx create-statikapi <name>` to scaffold a new project.');
+}
+
+// after publishing, replace the above with the below:
+// export default async function initCmd(argv) {
+//   // Delegate to create-statikapi programmatically
+//   const { main } = await import('create-statikapi/src/index.js');
+//   return (await main(argv), 0);
+// }