@fragno-dev/cli 0.2.0 → 0.2.3

package/package.json

@@ -1,49 +1,48 @@
 {
   "name": "@fragno-dev/cli",
-  "version": "0.2.0",
+  "version": "0.2.3",
+  "homepage": "https://fragno.dev",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/rejot-dev/fragno.git",
+    "directory": "apps/fragno-cli"
+  },
+  "bin": {
+    "fragno-cli": "./bin/run.js"
+  },
+  "type": "module",
+  "main": "./dist/cli.js",
+  "module": "./dist/cli.js",
+  "types": "./dist/cli.d.ts",
   "exports": {
     ".": {
-      "development": "./src/cli.ts",
       "types": "./dist/cli.d.ts",
       "default": "./dist/cli.js"
     }
   },
-  "type": "module",
-  "bin": {
-    "fragno-cli": "./bin/run.js"
-  },
-  "engines": {
-    "node": ">=22"
+  "dependencies": {
+    "@clack/prompts": "^0.11.0",
+    "c12": "^3.3.3",
+    "gunshi": "^0.26.3",
+    "jsonc-parser": "^3.3.1",
+    "@fragno-dev/core": "0.2.2",
+    "@fragno-dev/db": "0.4.1",
+    "@fragno-dev/node": "0.0.9"
   },
   "devDependencies": {
     "@types/node": "^22.19.7",
-    "@vitest/coverage-istanbul": "^3.2.4",
+    "@vitest/coverage-istanbul": "^4.1.0",
     "@fragno-private/typescript-config": "0.0.1",
     "@fragno-private/vitest-config": "0.0.0"
   },
-  "dependencies": {
-    "@clack/prompts": "^0.11.0",
-    "c12": "^3.3.3",
-    "gunshi": "^0.26.3",
-    "marked": "^15.0.12",
-    "marked-terminal": "^7.3.0",
-    "@fragno-dev/core": "0.2.0",
-    "@fragno-dev/corpus": "0.0.7",
-    "@fragno-dev/db": "0.3.0"
-  },
-  "main": "./dist/cli.js",
-  "module": "./dist/cli.js",
-  "types": "./dist/cli.d.ts",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/rejot-dev/fragno.git",
-    "directory": "apps/fragno-cli"
+  "engines": {
+    "node": ">=22"
   },
-  "homepage": "https://fragno.dev",
-  "license": "MIT",
   "scripts": {
     "build": "tsdown",
     "build:watch": "tsdown --watch",
-    "types:check": "tsc --noEmit"
+    "types:check": "tsc --noEmit",
+    "test": "vitest run"
   }
 }

package/src/cli.ts

@@ -1,14 +1,15 @@
 #!/usr/bin/env node
 
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
 import { cli, define } from "gunshi";
+
 import { generateCommand } from "./commands/db/generate.js";
-import { migrateCommand } from "./commands/db/migrate.js";
 import { infoCommand } from "./commands/db/info.js";
+import { migrateCommand } from "./commands/db/migrate.js";
 import { searchCommand } from "./commands/search.js";
-import { corpusCommand } from "./commands/corpus.js";
-import { readFileSync } from "node:fs";
-import { fileURLToPath } from "node:url";
-import { dirname, join } from "node:path";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const packageJson = JSON.parse(readFileSync(join(__dirname, "../package.json"), "utf-8"));
@@ -43,10 +44,11 @@ export async function run() {
         name: "fragno-cli search",
         version,
       });
-    } else if (args[0] === "corpus") {
-      // Run corpus command directly
-      await cli(args.slice(1), corpusCommand, {
-        name: "fragno-cli corpus",
+    } else if (args[0] === "serve") {
+      // Run serve command directly
+      const { serveCommand } = await import("./commands/serve.js");
+      await cli(args.slice(1), serveCommand, {
+        name: "fragno-cli serve",
         version,
       });
     } else if (args[0] === "db") {
@@ -102,14 +104,14 @@ export async function run() {
       console.log("  fragno-cli <COMMAND>");
       console.log("");
       console.log("COMMANDS:");
+      console.log("  serve                 Start a local HTTP server to serve fragments");
       console.log("  db                    Database management commands");
       console.log("  search                Search the Fragno documentation");
-      console.log("  corpus                View code examples and documentation for Fragno");
       console.log("");
       console.log("For more info, run any command with the `--help` flag:");
+      console.log("  fragno-cli serve --help");
       console.log("  fragno-cli db --help");
       console.log("  fragno-cli search --help");
-      console.log("  fragno-cli corpus --help");
       console.log("");
       console.log("OPTIONS:");
       console.log("  -h, --help             Display this help message");
@@ -133,4 +135,4 @@ if (import.meta.main) {
   await run();
 }
 
-export { generateCommand, migrateCommand, infoCommand, searchCommand, corpusCommand };
+export { generateCommand, migrateCommand, infoCommand, searchCommand };

package/src/commands/db/generate.ts

@@ -1,7 +1,9 @@
 import { writeFile, mkdir } from "node:fs/promises";
 import { resolve, dirname } from "node:path";
-import { define } from "gunshi";
+
 import { generateSchemaArtifacts } from "@fragno-dev/db/generation-engine";
+import { define } from "gunshi";
+
 import { importFragmentFiles } from "../../utils/find-fragno-databases";
 
 // Define the db generate command with type safety

package/src/commands/db/info.ts

@@ -1,5 +1,7 @@
 import { resolve } from "node:path";
+
 import { define } from "gunshi";
+
 import { importFragmentFiles } from "../../utils/find-fragno-databases";
 
 export const infoCommand = define({

package/src/commands/db/migrate.ts

@@ -1,7 +1,9 @@
 import { resolve } from "node:path";
+
+import { executeMigrations, type ExecuteMigrationResult } from "@fragno-dev/db/generation-engine";
 import { define } from "gunshi";
+
 import { importFragmentFiles } from "../../utils/find-fragno-databases";
-import { executeMigrations, type ExecuteMigrationResult } from "@fragno-dev/db/generation-engine";
 
 export const migrateCommand = define({
   name: "migrate",

package/src/commands/search.ts

@@ -1,4 +1,5 @@
 import { define } from "gunshi";
+
 import {
   mergeResultsByUrl,
   formatAsMarkdown,

package/src/commands/serve.ts

@@ -0,0 +1,151 @@
+import { createServer, type Server } from "node:http";
+import { resolve, relative } from "node:path";
+
+import { define } from "gunshi";
+
+import type { FragnoInstantiatedFragment } from "@fragno-dev/core";
+import { toNodeHandler } from "@fragno-dev/node";
+
+import { findFragnoFragments } from "../utils/find-fragno-databases";
+import { loadConfig } from "../utils/load-config";
+
+export const serveCommand = define({
+  name: "serve",
+  description: "Start a local HTTP server to serve one or more Fragno fragments",
+  args: {
+    port: {
+      type: "number",
+      short: "p",
+      description: "Port to listen on",
+      default: 8080,
+    },
+    host: {
+      type: "string",
+      short: "H",
+      description: "Host to bind to",
+      default: "localhost",
+    },
+  },
+  run: async (ctx) => {
+    const targets = ctx.positionals;
+    const port = ctx.values.port ?? 8080;
+    const host = ctx.values.host ?? "localhost";
+    const cwd = process.cwd();
+
+    if (targets.length === 0) {
+      throw new Error(
+        "No fragment files specified.\n\n" +
+          "Usage: fragno-cli serve <fragment-file> [fragment-file...]\n\n" +
+          "Example: fragno-cli serve ./src/my-fragment.ts",
+      );
+    }
+
+    const targetPaths = targets.map((target) => resolve(cwd, target));
+
+    // Import all fragment files and find instantiated fragments
+    const allFragments: FragnoInstantiatedFragment<
+      [],
+      unknown,
+      Record<string, unknown>,
+      Record<string, unknown>,
+      Record<string, unknown>,
+      unknown,
+      Record<string, unknown>
+    >[] = [];
+
+    for (const targetPath of targetPaths) {
+      const relativePath = relative(cwd, targetPath);
+      const config = await loadConfig(targetPath);
+      const fragments = findFragnoFragments(config);
+
+      if (fragments.length === 0) {
+        console.warn(
+          `Warning: No instantiated fragments found in ${relativePath}.\n` +
+            `Make sure you export an instantiated fragment (e.g., the return value of createMyFragment()).\n`,
+        );
+        continue;
+      }
+
+      allFragments.push(...fragments);
+      console.log(
+        `  Found ${fragments.length} fragment(s) in ${relativePath}: ${fragments.map((f) => f.name).join(", ")}`,
+      );
+    }
+
+    if (allFragments.length === 0) {
+      throw new Error(
+        "No instantiated fragments found in any of the specified files.\n" +
+          "Make sure your files export instantiated fragments.",
+      );
+    }
+
+    // Build handlers mapped by mountRoute
+    const handlers = allFragments.map((fragment) => ({
+      mountRoute: fragment.mountRoute,
+      handler: toNodeHandler(fragment.handler.bind(fragment)),
+      fragment,
+    }));
+
+    const server = createServer((req, res) => {
+      const url = req.url ?? "";
+
+      for (const { mountRoute, handler } of handlers) {
+        if (url.startsWith(mountRoute)) {
+          return handler(req, res);
+        }
+      }
+
+      res.statusCode = 404;
+      res.setHeader("Content-Type", "application/json");
+      res.end(
+        JSON.stringify({
+          error: "Not Found",
+          availableRoutes: handlers.map((h) => h.mountRoute),
+        }),
+      );
+    });
+
+    server.listen(port, host, () => {
+      const hostStr = addressToString(server);
+      console.log(`\nFragno server is running on: ${hostStr}\n`);
+
+      for (const { fragment } of handlers) {
+        console.log(`Fragment: ${fragment.name}`);
+        console.log(`  Mount: ${hostStr}${fragment.mountRoute}`);
+
+        const routes = fragment.routes as unknown as { method: string; path: string }[];
+        if (routes.length > 0) {
+          console.log("  Routes:");
+          for (const route of routes) {
+            console.log(`    ${route.method} ${fragment.mountRoute}${route.path}`);
+          }
+        }
+
+        console.log("");
+      }
+    });
+  },
+});
+
+function addressToString(server: Server, protocol: "http" | "https" = "http"): string {
+  const addr = server.address();
+  if (!addr) {
+    throw new Error("Address invalid");
+  }
+
+  if (typeof addr === "string") {
+    return addr;
+  }
+
+  let host = addr.address;
+
+  if (host === "::" || host === "0.0.0.0") {
+    host = "localhost";
+  }
+
+  if (addr.family === "IPv6" && host !== "localhost") {
+    host = `[${host}]`;
+  }
+
+  return `${protocol}://${host}:${addr.port}`;
+}

package/src/utils/find-fragno-databases.ts

@@ -1,13 +1,16 @@
-import { isFragnoDatabase, type DatabaseAdapter, FragnoDatabase } from "@fragno-dev/db";
+import { relative } from "node:path";
+
+import { instantiatedFragmentFakeSymbol } from "@fragno-dev/core/internal/symbols";
 import {
   fragnoDatabaseAdapterNameFakeSymbol,
   fragnoDatabaseAdapterVersionFakeSymbol,
 } from "@fragno-dev/db/adapters";
 import type { AnySchema } from "@fragno-dev/db/schema";
-import { instantiatedFragmentFakeSymbol } from "@fragno-dev/core/internal/symbols";
+
 import { type FragnoInstantiatedFragment } from "@fragno-dev/core";
+import { isFragnoDatabase, type DatabaseAdapter, FragnoDatabase } from "@fragno-dev/db";
+
 import { loadConfig } from "./load-config";
-import { relative } from "node:path";
 
 export async function importFragmentFile(path: string): Promise<Record<string, unknown>> {
   // Enable dry run mode for database schema extraction
@@ -149,6 +152,39 @@ function isNewFragnoInstantiatedFragment(
   );
 }
 
+/**
+ * Finds all instantiated Fragno fragments in a module's exports.
+ */
+export function findFragnoFragments(
+  targetModule: Record<string, unknown>,
+): FragnoInstantiatedFragment<
+  [],
+  unknown,
+  Record<string, unknown>,
+  Record<string, unknown>,
+  Record<string, unknown>,
+  unknown,
+  Record<string, unknown>
+>[] {
+  const fragments: FragnoInstantiatedFragment<
+    [],
+    unknown,
+    Record<string, unknown>,
+    Record<string, unknown>,
+    Record<string, unknown>,
+    unknown,
+    Record<string, unknown>
+  >[] = [];
+
+  for (const [_key, value] of Object.entries(targetModule)) {
+    if (isNewFragnoInstantiatedFragment(value)) {
+      fragments.push(value);
+    }
+  }
+
+  return fragments;
+}
+
 /**
  * Finds all FragnoDatabase instances in a module, including those embedded
  * in instantiated fragments.
@@ -168,13 +204,15 @@ export function findFragnoDatabases(
       const options = internal.options as Record<string, unknown>;
 
       // Check if this is a database fragment by looking for implicit database dependencies
-      if (!deps["db"] || !deps["schema"]) {
+      if (!deps["schema"]) {
         continue;
       }
 
       const schema = deps["schema"] as AnySchema;
-      const namespace = deps["namespace"] as string;
-      const databaseAdapter = options["databaseAdapter"] as DatabaseAdapter | undefined;
+      const namespace = deps["namespace"] as string | null;
+      const databaseAdapter =
+        (deps["databaseAdapter"] as DatabaseAdapter | undefined) ??
+        (options["databaseAdapter"] as DatabaseAdapter | undefined);
 
       if (!databaseAdapter) {
         console.warn(

package/src/utils/load-config.test.ts

@@ -1,18 +1,26 @@
 import { describe, it, expect } from "vitest";
-import { stripJsonComments, convertTsconfigPathsToJitiAlias } from "./load-config";
+
 import { resolve } from "node:path";
 
+import { stripJsonComments, convertTsconfigPathsToJitiAlias } from "./load-config";
+
 describe("stripJsonComments", () => {
   it("should strip single-line comments", () => {
     const input = `{
   // This is a comment
   "key": "value"
 }`;
-    const expected = `{
-  
-  "key": "value"
+    const result = stripJsonComments(input);
+    expect(() => JSON.parse(result)).not.toThrow();
+    expect(JSON.parse(result)).toEqual({ key: "value" });
+  });
+
+  it("does not strip double slashes in strings", () => {
+    const input = `{
+  "key": "https://example.com/foo",
+  "another": "value"
 }`;
-    expect(stripJsonComments(input)).toBe(expected);
+    expect(stripJsonComments(input)).toBe(input);
   });
 
   it("should strip multiple single-line comments", () => {
@@ -22,13 +30,21 @@ describe("stripJsonComments", () => {
   // Second comment
   "key2": "value2"
 }`;
-    const expected = `{
-  
-  "key1": "value1", 
-  
-  "key2": "value2"
-}`;
-    expect(stripJsonComments(input)).toBe(expected);
+    const result = stripJsonComments(input);
+    expect(() => JSON.parse(result)).not.toThrow();
+    expect(JSON.parse(result)).toEqual({ key1: "value1", key2: "value2" });
+  });
+
+  it("does not strip multi line comments chars in strings", () => {
+    const input = `{
+      "compilerOptions": {
+        "paths": {
+          "~/*": ["./src/*"]
+        }
+      },
+      "include": ["**/*.ts", "**/*.tsx"],
+    }`;
+    expect(stripJsonComments(input)).toBe(input);
   });
 
   it("should strip multi-line comments", () => {
@@ -37,11 +53,9 @@ describe("stripJsonComments", () => {
      multi-line comment */
   "key": "value"
 }`;
-    const expected = `{
-  
-  "key": "value"
-}`;
-    expect(stripJsonComments(input)).toBe(expected);
+    const result = stripJsonComments(input);
+    expect(() => JSON.parse(result)).not.toThrow();
+    expect(JSON.parse(result)).toEqual({ key: "value" });
   });
 
   it("should strip multiple multi-line comments", () => {
@@ -52,13 +66,9 @@ describe("stripJsonComments", () => {
      spanning lines */
   "key2": "value2"
 }`;
-    const expected = `{
-  
-  "key1": "value1",
-  
-  "key2": "value2"
-}`;
-    expect(stripJsonComments(input)).toBe(expected);
+    const result = stripJsonComments(input);
+    expect(() => JSON.parse(result)).not.toThrow();
+    expect(JSON.parse(result)).toEqual({ key1: "value1", key2: "value2" });
   });
 
   it("should strip both single-line and multi-line comments", () => {
@@ -69,13 +79,9 @@ describe("stripJsonComments", () => {
      comment */
   "key2": "value2" // Another single line
 }`;
-    const expected = `{
-  
-  "key1": "value1",
-  
-  "key2": "value2" 
-}`;
-    expect(stripJsonComments(input)).toBe(expected);
+    const result = stripJsonComments(input);
+    expect(() => JSON.parse(result)).not.toThrow();
+    expect(JSON.parse(result)).toEqual({ key1: "value1", key2: "value2" });
   });
 
   it("should handle strings with comment-like content", () => {
@@ -83,12 +89,12 @@ describe("stripJsonComments", () => {
   "url": "https://example.com",
   "comment": "This // is not a comment"
 }`;
-    // Note: This is a known limitation - the simple regex approach
-    // will strip what looks like comments even inside strings
-    // For tsconfig.json files this is typically fine since URLs/strings
-    // with comment syntax are rare
     const result = stripJsonComments(input);
-    expect(result).toContain('"url": "https:');
+    expect(() => JSON.parse(result)).not.toThrow();
+    expect(JSON.parse(result)).toEqual({
+      url: "https://example.com",
+      comment: "This // is not a comment",
+    });
   });
 
   it("should handle empty input", () => {

package/src/utils/load-config.ts

@@ -1,7 +1,9 @@
-import { loadConfig as c12LoadConfig } from "c12";
+import { constants } from "node:fs";
 import { readFile, access } from "node:fs/promises";
 import { dirname, resolve, join } from "node:path";
-import { constants } from "node:fs";
+
+import { loadConfig as c12LoadConfig } from "c12";
+import { stripComments } from "jsonc-parser";
 
 /**
  * Checks if a file exists using async API.
@@ -37,13 +39,7 @@ async function findTsconfig(startPath: string): Promise<string | null> {
  * Strips comments from JSONC (JSON with Comments) content.
  */
 export function stripJsonComments(jsonc: string): string {
-  // Remove single-line comments (// ...)
-  let result = jsonc.replace(/\/\/[^\n]*/g, "");
-
-  // Remove multi-line comments (/* ... */)
-  result = result.replace(/\/\*[\s\S]*?\*\//g, "");
-
-  return result;
+  return stripComments(jsonc);
 }
 
 /**

package/tsconfig.json

@@ -1,5 +1,5 @@
 {
-  "extends": "@fragno-private/typescript-config/tsconfig.base.json",
+  "extends": "@fragno-private/typescript-config/tsconfig.node.json",
   "compilerOptions": {
     "outDir": "./dist",
     "rootDir": ".",

package/vitest.config.ts

@@ -1,4 +1,5 @@
 import { defineConfig, mergeConfig } from "vitest/config";
+
 import { baseConfig } from "@fragno-private/vitest-config";
 
 export default defineConfig(