@apexkit/cli 1.0.3 → 1.0.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apexkit/cli",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "The official CLI and developer sync engine for ApexKit",
   "type": "module",
   "main": "./src/index.js",

package/src/index.js

@@ -138,10 +138,163 @@ const TRIGGER_DEFINITIONS = [
   { id: "after_ai_run", name: "after_ai_run", desc: "Runs after AI Prompt execution." },
   { id: "on_vectorization_start", name: "on_vectorization_start", desc: "Fires when revectorization job begins." },
   { id: "cron", name: "cron (Scheduled Job)", desc: "Executed periodically according to Cron expression settings." },
-  { id: "graphql", name: "graphql (Custom Resolver)", desc: "Dynamic Query/Mutation field resolver for GraphQL schema." }
+  { id: "graphql", name: "graphql (Custom Resolver)", desc: "Dynamic Query/Mutation field resolver for GraphQL schema." },
+  { id: "before_realtime_connection_established", name: "before_realtime_connection_established", desc: "Runs before an incoming SSE or WebSocket connection is accepted. Can block connections." },
+  { id: "before_realtime_data_pushed", name: "before_realtime_data_pushed", desc: "Intercepts and mutates real-time event payloads right before sending to a client." },
+  { id: "after_realtime_connection_desconnected", name: "after_realtime_connection_desconnected", desc: "Runs after an SSE or WebSocket client disconnects or connection is dropped." },
 ];
 
-// --- 4. ACCURATE WORKSPACE TYPES & CONFIG GENERATOR ---
+// --- 4. AUTOMATED REMOTE TYPE RESOLUTION & SCANNER ---
+function scanWorkspaceForRemoteUrls() {
+  const urls = new Set();
+  const dirs = ["./webhooks", "./modules", "./templates"];
+  const urlRegex =
+    /(?:import|export)\s+(?:[\s\S]*?from\s+)?["'](https?:\/\/[^"']+)["']|import\s*\(\s*["'](https?:\/\/[^"']+)["']\s*\)|@jsxImportSource\s+(https?:\/\/[^\s*]+)/g;
+
+  dirs.forEach((dir) => {
+    if (!fs.existsSync(dir)) return;
+    const files = fs.readdirSync(dir, { recursive: true });
+    files.forEach((file) => {
+      const fullPath = path.join(dir, file);
+      if (fs.statSync(fullPath).isFile()) {
+        const ext = path.extname(fullPath);
+        if ([".js", ".ts", ".jsx", ".tsx", ".html"].includes(ext)) {
+          try {
+            const content = fs.readFileSync(fullPath, "utf-8");
+            let match;
+            while ((match = urlRegex.exec(content)) !== null) {
+              const url = match[1] || match[2] || match[3];
+              if (url) urls.add(url.trim());
+            }
+          } catch (e) {}
+        }
+      }
+    });
+  });
+
+  return Array.from(urls);
+}
+
+async function resolveRemoteTypeUrl(importUrl) {
+  try {
+    const res = await fetch(importUrl, {
+      method: "GET",
+      headers: { "User-Agent": "ApexKit-CLI/1.0" },
+      redirect: "follow",
+    });
+
+    const dtsHeader = res.headers.get("x-typescript-types");
+    if (dtsHeader) {
+      return dtsHeader.startsWith("http") ? dtsHeader : new URL(dtsHeader, importUrl).href;
+    }
+
+    if (importUrl.endsWith(".d.ts")) {
+      return importUrl;
+    }
+
+    if (importUrl.includes("esm.sh")) {
+      const dtsParamUrl = importUrl.includes("?") ? `${importUrl}&dts` : `${importUrl}?dts`;
+      const paramRes = await fetch(dtsParamUrl, { method: "HEAD", redirect: "follow" });
+      const paramHeader = paramRes.headers.get("x-typescript-types");
+      if (paramHeader) {
+        return paramHeader.startsWith("http") ? paramHeader : new URL(paramHeader, importUrl).href;
+      }
+    }
+  } catch (e) {}
+  return null;
+}
+
+/**
+ * Recursively fetches a .d.ts file and all relative imports/exports inside it
+ */
+async function downloadDtsTree(currentDtsUrl, baseDir, relativeSubpath = "index.d.ts", visited = new Set()) {
+  if (visited.has(currentDtsUrl)) return;
+  visited.add(currentDtsUrl);
+
+  const localFilePath = path.join(baseDir, relativeSubpath);
+  fs.mkdirSync(path.dirname(localFilePath), { recursive: true });
+
+  try {
+    const res = await fetch(currentDtsUrl, {
+      headers: { "User-Agent": "ApexKit-CLI/1.0" },
+      redirect: "follow",
+    });
+    if (!res.ok) return;
+
+    let content = await res.text();
+
+    // Regex to locate relative imports or exports like:
+    // import { Hono } from './hono.d.ts';
+    // export * from './types.d.ts';
+    const relImportRegex = /(?:import|export)\s+[\s\S]*?from\s+["'](\.[^"']+)["']/g;
+    const relMatches = [];
+    let match;
+    while ((match = relImportRegex.exec(content)) !== null) {
+      relMatches.push(match[1]);
+    }
+
+    // Write file locally
+    fs.writeFileSync(localFilePath, content);
+
+    // Recursively pull all dependencies relative to current URL
+    for (const relPath of relMatches) {
+      // Normalize extension: ensure it resolves to .d.ts on the CDN
+      let targetRel = relPath;
+      if (!targetRel.endsWith(".d.ts") && !targetRel.endsWith(".ts")) {
+        targetRel = `${targetRel}.d.ts`;
+      }
+
+      const nextUrl = new URL(targetRel, currentDtsUrl).href;
+      const nextLocalSubpath = path.normalize(
+        path.join(path.dirname(relativeSubpath), targetRel.replace(/^\.\//, ""))
+      );
+
+      await downloadDtsTree(nextUrl, baseDir, nextLocalSubpath, visited);
+    }
+  } catch (err) {
+    console.warn(`  ⚠️ Failed to recursively pull: ${currentDtsUrl} -> ${err.message}`);
+  }
+}
+
+async function pullRemoteModuleTypes(urls) {
+  const typesDir = path.join(".apexkit", "types");
+  fs.mkdirSync(typesDir, { recursive: true });
+
+  const resolvedPaths = {};
+
+  for (const rawUrl of urls) {
+    try {
+      // Use directory container for each package to support relative child imports cleanly
+      const urlFolder = rawUrl.replace(/[^a-zA-Z0-9_.-]/g, "_");
+      const packageDir = path.join(typesDir, urlFolder);
+      const rootDtsFile = path.join(packageDir, "index.d.ts");
+
+      if (fs.existsSync(rootDtsFile) && fs.statSync(rootDtsFile).size > 0) {
+        resolvedPaths[rawUrl] = `./${rootDtsFile.replace(/\\/g, "/")}`;
+        continue;
+      }
+
+      console.log(`  🌐 [Types]: Resolving remote type tree for ${rawUrl}...`);
+      const dtsUrl = await resolveRemoteTypeUrl(rawUrl);
+
+      if (dtsUrl) {
+        fs.mkdirSync(packageDir, { recursive: true });
+        await downloadDtsTree(dtsUrl, packageDir, "index.d.ts");
+
+        if (fs.existsSync(rootDtsFile)) {
+          resolvedPaths[rawUrl] = `./${rootDtsFile.replace(/\\/g, "/")}`;
+          console.log(`  📦 [Types]: Successfully cached dependency tree in ${packageDir}`);
+        }
+      }
+    } catch (err) {
+      console.warn(`  ⚠️ Could not pull remote types for ${rawUrl}: ${err.message}`);
+    }
+  }
+
+  return resolvedPaths;
+}
+
+// --- 5. ACCURATE WORKSPACE TYPES & CONFIG GENERATOR ---
 async function generateWorkspaceFiles() {
   console.log("  ⏳ Fetching collection schemas from DB...");
   let collectionsData = [];
@@ -332,6 +485,13 @@ export interface FileMetadata {
   visibility?: ScriptVisibility;
 }
 
+export type ApexKitDb = typeof $db;
+export type ApexKitHttp = typeof $http;
+export type ApexKitFiles = typeof $files;
+export type ApexKitFs = typeof $fs;
+export type ApexKitCache = typeof $cache;
+export type ApexKitEnv = typeof $env;
+
 export interface AuthContext {
   id: number | string;
   email: string;
@@ -369,6 +529,19 @@ export interface VoidHookEvent {
 }
 
 declare global {
+  namespace JSX {
+    interface Element extends Promise<string>, String {
+      [key: string]: any;
+      toString(): string;
+    }
+    interface IntrinsicElements {
+      [elemName: string]: any;
+    }
+    interface ElementChildrenAttribute {
+      children: {};
+    }
+  }
+
   const __fileMetadata__: FileMetadata;
 
   /** ApexKit Database Client */
@@ -597,50 +770,122 @@ declare global {
     init?: { method?: string; headers?: any; body?: any; redirect?: "follow" | "manual" | "error" }
   ): Promise<Response>;
 }
+
+// --- RUNTIME MODULE DEFINITIONS ---
+declare module "react/jsx-runtime" {
+  export const jsx: any;
+  export const jsxs: any;
+  export const Fragment: any;
+}
+
+declare module "react/jsx-dev-runtime" {
+  export const jsxDEV: any;
+  export const Fragment: any;
+}
+
+declare module "hono/jsx/jsx-runtime" {
+  export const jsx: any;
+  export const jsxs: any;
+  export const Fragment: any;
+}
+
+declare module "hono/jsx" {
+  export const jsx: any;
+  export const jsxs: any;
+  export const Fragment: any;
+  export type FC<T = any> = (props: T) => any;
+}
+
+// --- HONO CONTEXT OVERLOADS ---
+declare module "hono" {
+  interface Context {
+    html(html: string | Promise<string> | JSX.Element | any, status?: any, headers?: any): Response | Promise<Response>;
+  }
+}
+
+// --- REMOTE URL MODULE DECLARATIONS & FALLBACKS ---
+declare module "https://*" {
+  const content: any;
+  export default content;
+  export * from "https://*";
+}
+
+declare module "http://*" {
+  const content: any;
+  export default content;
+  export * from "http://*";
+}
+
 export {};
 `;
   fs.writeFileSync("apexkit.d.ts", types.trim());
-  console.log("  📄 Generated apexkit.d.ts with Accurate Scaled & Relational Typings");
+  console.log("  📄 Generated apexkit.d.ts with Accurate Scaled Typings & Universal JSX");
+
+  // Dynamically scan all files and auto-pull remote module types
+  const remoteUrls = scanWorkspaceForRemoteUrls();
+  const resolvedRemoteTypes = await pullRemoteModuleTypes(remoteUrls);
+
+  const dynamicPaths = {
+    "@/custom/*": ["./modules/custom/*"],
+    "@/esm/*": ["./modules/esm/*"],
+  };
+
+  // Map each pulled remote URL to its local cached definition
+  for (const [remoteUrl, localPath] of Object.entries(resolvedRemoteTypes)) {
+    dynamicPaths[remoteUrl] = [localPath];
+    dynamicPaths[`${remoteUrl}/*`] = [`${localPath}/*`];
+  }
 
   const jsconfig = {
     compilerOptions: {
       target: "ES2022",
       module: "ESNext",
       ignoreDeprecations: "6.0",
-      moduleResolution: "node",
+      moduleResolution: "bundler",
+      allowImportingTsExtensions: true,
+      jsx: "preserve",
       baseUrl: ".",
-      paths: {
-        "@/custom/*": ["./modules/custom/*"],
-        "@/esm/*": ["./modules/esm/*"],
-      },
+      paths: dynamicPaths,
       allowJs: true,
       checkJs: true,
     },
-    include: ["**/*.js", "**/*.ts", "**/*.html", "apexkit.d.ts"],
+    include: [
+      "**/*.js",
+      "**/*.ts",
+      "**/*.jsx",
+      "**/*.tsx",
+      "**/*.html",
+      "apexkit.d.ts",
+      ".apexkit/types/**/*.d.ts",
+    ],
   };
   fs.writeFileSync("jsconfig.json", JSON.stringify(jsconfig, null, 2));
-  console.log("  📄 Generated jsconfig.json for module resolution");
+  console.log("  📄 Generated jsconfig.json with Auto-Mapped Remote Types & JSX Support");
 }
 
 // --- 5. INITIAL CODE GENERATOR ---
 function getBoilerplateCode(fileType, cleanName, ext, triggerType, targetCollection) {
+  const metadataPath =
+    fileType === "template"
+      ? "./templates/"
+      : fileType.includes("module")
+      ? "./modules/custom/"
+      : "./webhooks/";
+
+  const typeImportPath = metadataPath.includes("modules/") ? "../../apexkit" : "../apexkit";
+
   const metadata = {
     name: cleanName,
     extension: ext,
     target_collection: targetCollection,
     type: fileType,
-    path:
-      fileType === "template"
-        ? "./templates/"
-        : fileType.includes("module")
-        ? "./modules/custom/"
-        : "./webhooks/",
+    path: metadataPath,
     trigger_type: triggerType,
     active: true,
     visibility: "private",
   };
 
-  const header = `/** @type {import("../apexkit").FileMetadata} */\nexport const __fileMetadata__ = ${JSON.stringify(
+  const header = `/** @type {import("${typeImportPath}").FileMetadata} */\nexport const __fileMetadata__ = ${JSON.stringify(
     metadata,
     null,
     2
@@ -666,10 +911,11 @@ export function ${cleanName.replace(/-/g, "_")}(data = {}) {
 __fileMetadata__ = ${JSON.stringify(metadata, null, 2)}
 -->
 <script server>
-/// <reference path="../apexkit.d.ts" />
+/** @type {import("../apexkit").ApexKitDb} */
+const db = $db;
 
 export default async function (context) {
-  const posts = await $db.records.list(\`${targetCollection || "posts"}\`, { limit: 10 }).catch(() => ({ items: [] }));
+  const posts = await db.records.list(\`${targetCollection || "posts"}\`, { limit: 10 }).catch(() => ({ items: [] }));
   return {
     title: \`${cleanName.replace(/-/g, " ").toUpperCase()}\`,
     items: posts.items
@@ -756,6 +1002,62 @@ export default async function (event) {
     data
   });
 }
+`;
+
+    case "before_realtime_connection_established":
+      return `${header}/**
+ * Hook: before_realtime_connection_established
+ * Intercepts incoming Realtime connections before upgrading/accepting.
+ *
+ * @param {{ trigger: string, data: { ip: string, protocol: 'sse' | 'websocket', headers: Record<string, string> }, auth: import("${typeImportPath}").AuthContext | null }} event
+ */
+export default async function (event) {
+  const { ip, protocol, headers } = event.data;
+
+  // Example: Block suspicious user-agents or IPs (throwing an error drops the connection)
+  // if (headers["user-agent"]?.includes("BadBot")) {
+  //   throw new Error("Connection denied");
+  // }
+
+  return true;
+}
+`;
+
+    case "before_realtime_data_pushed":
+      return `${header}/**
+ * Hook: before_realtime_data_pushed
+ * Intercepts event data just before broadcasting to the connected client.
+ *
+ * @param {{ trigger: string, data: any, auth: import("${typeImportPath}").AuthContext | null }} event
+ * @returns {Promise<any>} Return modified payload, or throw an error to send an empty object {}
+ */
+export default async function (event) {
+  const eventPayload = event.data;
+
+  // Example: Redact sensitive information before the client receives it
+  // (NOTE: $realtime.send is blocked inside this hook to avoid infinite loops)
+  // if (eventPayload.data && eventPayload.data.internal_secret) {
+  //   delete eventPayload.data.internal_secret;
+  // }
+
+  return eventPayload;
+}
+`;
+
+    case "after_realtime_connection_desconnected":
+      return `${header}/**
+ * Hook: after_realtime_connection_desconnected
+ * Fires asynchronously when a client stream/socket disconnects or drops.
+ *
+ * @param {{ trigger: string, data: { ip: string, protocol: 'sse' | 'websocket', headers: Record<string, string> }, auth: import("${typeImportPath}").AuthContext | null }} event
+ */
+export default async function (event) {
+  const { ip, protocol } = event.data;
+
+  console.log(\`Client disconnected (\${protocol}) from \${ip}\`);
+
+  return true;
+}
 `;
 
     default:
@@ -802,10 +1104,12 @@ async function runInitFile() {
   }
 
   const cleanName = rawName.replace(/[^a-zA-Z0-9_-]/g, "");
-  const ext =
+  const allowedScriptExts = ["js", "ts", "jsx", "tsx"];
+  const rawExt =
     fileType === "template"
       ? "html"
-      : ((await rl.question("Extension (js/ts) [js]: ")).trim() || "js");
+      : ((await rl.question("Extension (js/ts/jsx/tsx) [js]: ")).trim().toLowerCase() || "js");
+  const ext = fileType === "template" ? "html" : (allowedScriptExts.includes(rawExt) ? rawExt : "js");
 
   let triggerType = "manual";
   let targetCollection = null;
@@ -816,7 +1120,7 @@ async function runInitFile() {
       console.log(`  ${String(i + 1).padStart(2, " ")}) ${t.name}`);
     });
 
-    const trigChoice = parseInt((await rl.question("\nChoice (1-42) [1]: ")).trim() || "1", 10);
+    const trigChoice = parseInt((await rl.question("\nChoice (1-45) [1]: ")).trim() || "1", 10);
     const selectedTrig = TRIGGER_DEFINITIONS[trigChoice - 1] || TRIGGER_DEFINITIONS[0];
     triggerType = selectedTrig.id;
 
@@ -918,11 +1222,16 @@ async function runPull() {
       const payload = await scriptRes.json();
       const scripts = Array.isArray(payload) ? payload : payload.local || [];
 
+      const allowedScriptExts = ["js", "ts", "jsx", "tsx"];
+
       scripts.forEach((script) => {
+        const remoteExt = script.metadata?.extension?.toLowerCase();
+        const extension = allowedScriptExts.includes(remoteExt) ? remoteExt : "js";
+
         const meta = {
           id: script.id,
           name: script.name,
-          extension: "js",
+          extension: extension,
           target_collection: script.target_collection || null,
           type: script.metadata?.type || "webhook",
           path: script.metadata?.path || "./webhooks/",
@@ -934,7 +1243,9 @@ async function runPull() {
         const targetDir = meta.path.replace(/^\.\//, "");
         fs.mkdirSync(targetDir, { recursive: true });
 
-        const formattedContent = `/** @type {import("../apexkit").FileMetadata} */\nexport const __fileMetadata__ = ${JSON.stringify(
+        const typeImportPath = meta.path.includes("modules/") ? "../../apexkit" : "../apexkit";
+
+        const formattedContent = `/** @type {import("${typeImportPath}").FileMetadata} */\nexport const __fileMetadata__ = ${JSON.stringify(
           meta,
           null,
           2
@@ -996,9 +1307,11 @@ async function runPull() {
     console.warn(`  ⚠️ AI Actions pull warning: ${e.message}`);
   }
 
+  // Ensure .apexkit/types is ready and regenerate workspace definitions + remote types
+  fs.mkdirSync(path.join(".apexkit", "types"), { recursive: true });
   await generateWorkspaceFiles();
 
-  console.log(`\n✨ Pull complete! Hydrated ${pulledCount} items to local workspace.`);
+  console.log(`\n✨ Pull complete! Hydrated ${pulledCount} items and resolved remote types.`);
   process.exit(0);
 }
 
@@ -1039,7 +1352,7 @@ function inferFileMetadata(filePath, content) {
     return content;
   }
 
-  // 3. Scripts / Webhooks / Modules -> JS Export metadata
+  // 3. Scripts / Webhooks / Modules -> JS/TS/JSX/TSX Export metadata
   let deducedType = "webhook";
   let deducedPath = "./webhooks/";
   let deducedTrigger = "manual";
@@ -1052,7 +1365,7 @@ function inferFileMetadata(filePath, content) {
     deducedPath = "./modules/esm/";
   }
 
-  const jsMetaRe = /(?:export\s+const\s+__fileMetadata__\s*=\s*)(\{[\s\S]*?\});?/;
+  const jsMetaRe = /(?:\/\*\*[\s\S]*?\*\/\s*)?export\s+const\s+__fileMetadata__\s*=\s*(\{[\s\S]*?\});?/;
   const match = content.match(jsMetaRe);
 
   let metaObj = {};
@@ -1062,9 +1375,14 @@ function inferFileMetadata(filePath, content) {
     } catch (e) {}
   }
 
+  // Prioritize real file extension if js|ts|jsx|tsx, otherwise force to js
+  const allowedScriptExts = ["js", "ts", "jsx", "tsx"];
+  const fileExt = ext.toLowerCase();
+  const prioritizedExt = allowedScriptExts.includes(fileExt) ? fileExt : "js";
+
   const finalMeta = {
     name: metaObj.name || baseName,
-    extension: metaObj.extension || ext || "js",
+    extension: prioritizedExt,
     target_collection: metaObj.target_collection || null,
     type: metaObj.type || deducedType,
     path: metaObj.path || deducedPath,
@@ -1073,12 +1391,20 @@ function inferFileMetadata(filePath, content) {
     visibility: metaObj.visibility || "private",
   };
 
+  const typeImportPath = finalMeta.path.includes("modules/") ? "../../apexkit" : "../apexkit";
+  const formattedMetadata = `/** @type {import("${typeImportPath}").FileMetadata} */\nexport const __fileMetadata__ = ${JSON.stringify(
+    finalMeta,
+    null,
+    2
+  )};`;
+
   if (!match) {
-    return `/** @type {import("../apexkit").FileMetadata} */\nexport const __fileMetadata__ = ${JSON.stringify(
-      finalMeta,
-      null,
-      2
-    )};\n\n${content}`;
+    return `${formattedMetadata}\n\n${content}`;
+  }
+
+  // If metadata extension differed or needs updating, replace with prioritized definition
+  if (metaObj.extension !== prioritizedExt || content.includes('import("../apexkit")') && typeImportPath.includes("../..")) {
+    return content.replace(jsMetaRe, formattedMetadata);
   }
 
   return content;
@@ -1393,6 +1719,8 @@ function startWatcher() {
         if (
           filename.endsWith(".js") ||
           filename.endsWith(".ts") ||
+          filename.endsWith(".jsx") ||
+          filename.endsWith(".tsx") ||
           filename.endsWith(".html") ||
           filename.endsWith(".json")
         ) {