@ziex/cli 0.1.0-dev.865

package/install.cjs

@@ -0,0 +1,218 @@
+// Postinstall script for ziex npm package
+// Resolves the native binary from platform-specific optionalDependencies
+// or falls back to downloading from GitHub releases.
+
+const { existsSync, mkdirSync, copyFileSync, chmodSync, createWriteStream, unlinkSync } = require("fs");
+const { execSync } = require("child_process");
+const path = require("path");
+const https = require("https");
+const { createGunzip } = require("zlib");
+
+const PLATFORM_MAP = {
+  darwin: {
+    arm64: { pkg: "@ziex/cli-darwin-arm64", target: "macos-aarch64" },
+    x64: { pkg: "@ziex/cli-darwin-x64", target: "macos-x64" },
+  },
+  linux: {
+    x64: { pkg: "@ziex/cli-linux-x64", target: "linux-x64" },
+    arm64: { pkg: "@ziex/cli-linux-arm64", target: "linux-aarch64" },
+  },
+  win32: {
+    x64: { pkg: "@ziex/cli-win32-x64", target: "windows-x64" },
+    arm64: { pkg: "@ziex/cli-win32-arm64", target: "windows-aarch64" },
+  },
+};
+
+const GITHUB_REPO = "ziex-dev/ziex";
+
+function getPlatformInfo() {
+  const os = process.platform;
+  const arch = process.arch;
+  const info = PLATFORM_MAP[os]?.[arch];
+  if (!info) {
+    throw new Error(`Unsupported platform: ${os}-${arch}`);
+  }
+  return info;
+}
+
+function getVersion() {
+  const pkg = require("./package.json");
+  return pkg.version;
+}
+
+function getBinaryName(target) {
+  const isWindows = process.platform === "win32";
+  return `zx-${target}${isWindows ? ".exe" : ""}`;
+}
+
+function getOutputPath() {
+  const binDir = path.join(__dirname, "bin");
+  const isWindows = process.platform === "win32";
+  return path.join(binDir, isWindows ? "zx.exe" : "zx");
+}
+
+// Try to resolve binary from optionalDependencies
+function tryResolveFromOptionalDep(pkgName) {
+  try {
+    const pkgPath = require.resolve(`${pkgName}/package.json`);
+    const pkgDir = path.dirname(pkgPath);
+    const pkgJson = require(pkgPath);
+    const binName = pkgJson.bin?.zx || pkgJson.bin?.ziex;
+    if (binName) {
+      const binPath = path.join(pkgDir, binName);
+      if (existsSync(binPath)) {
+        return binPath;
+      }
+    }
+    // Fallback: look for the binary directly
+    const isWindows = process.platform === "win32";
+    const possibleNames = isWindows ? ["zx.exe"] : ["zx"];
+    for (const name of possibleNames) {
+      const candidate = path.join(pkgDir, "bin", name);
+      if (existsSync(candidate)) return candidate;
+    }
+  } catch {
+    // Package not installed
+  }
+  return null;
+}
+
+// Download from GitHub releases
+function downloadFromGitHub(target, version) {
+  return new Promise((resolve, reject) => {
+    const isWindows = process.platform === "win32";
+    const ext = isWindows ? "zip" : "tar.gz";
+    const tag = version.startsWith("0.") ? `zx-v${version}` : `zx-v${version}`;
+    const url = `https://github.com/${GITHUB_REPO}/releases/download/${tag}/zx-${target}.${ext}`;
+    const latestUrl = `https://github.com/${GITHUB_REPO}/releases/latest/download/zx-${target}.${ext}`;
+
+    const binDir = path.join(__dirname, "bin");
+    mkdirSync(binDir, { recursive: true });
+    const archivePath = path.join(binDir, `zx-${target}.${ext}`);
+
+    console.log(`Downloading ziex binary for ${target}...`);
+
+    function download(downloadUrl, isRetry) {
+      const followRedirect = (url) => {
+        const proto = url.startsWith("https") ? https : require("http");
+        proto
+          .get(url, { headers: { "User-Agent": "ziex-npm" } }, (res) => {
+            if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+              followRedirect(res.headers.location);
+              return;
+            }
+            if (res.statusCode !== 200) {
+              if (!isRetry) {
+                // Retry with latest
+                download(latestUrl, true);
+                return;
+              }
+              reject(new Error(`Download failed with status ${res.statusCode}: ${downloadUrl}`));
+              return;
+            }
+
+            const file = createWriteStream(archivePath);
+            res.pipe(file);
+            file.on("finish", () => {
+              file.close(() => resolve(archivePath));
+            });
+          })
+          .on("error", reject);
+      };
+      followRedirect(downloadUrl);
+    }
+
+    download(url, false);
+  });
+}
+
+function extractTarGz(archivePath, targetBinaryName, outputPath) {
+  const binDir = path.dirname(outputPath);
+  // Use tar command (available on macOS and Linux)
+  execSync(`tar -xzf "${archivePath}" -C "${binDir}"`, { stdio: "pipe" });
+  const extractedPath = path.join(binDir, targetBinaryName);
+  if (existsSync(extractedPath)) {
+    copyFileSync(extractedPath, outputPath);
+    unlinkSync(extractedPath);
+  }
+  unlinkSync(archivePath);
+}
+
+function extractZip(archivePath, targetBinaryName, outputPath) {
+  const binDir = path.dirname(outputPath);
+  execSync(`unzip -o "${archivePath}" -d "${binDir}"`, { stdio: "pipe" });
+  const extractedPath = path.join(binDir, targetBinaryName);
+  if (existsSync(extractedPath)) {
+    copyFileSync(extractedPath, outputPath);
+    unlinkSync(extractedPath);
+  }
+  unlinkSync(archivePath);
+}
+
+async function main() {
+  const { pkg: pkgName, target } = getPlatformInfo();
+  const outputPath = getOutputPath();
+  const binDir = path.dirname(outputPath);
+  mkdirSync(binDir, { recursive: true });
+
+  // Step 1: Try to resolve from optional dependency
+  const resolvedPath = tryResolveFromOptionalDep(pkgName);
+  if (resolvedPath) {
+    console.log(`Found ziex binary from ${pkgName}`);
+    copyFileSync(resolvedPath, outputPath);
+    chmodSync(outputPath, 0o755);
+
+    // Create ziex alias (symlink or copy)
+    createAliases(outputPath);
+    return;
+  }
+
+  // Step 2: Download from GitHub releases
+  console.log(`Platform package ${pkgName} not found, downloading from GitHub...`);
+  try {
+    const version = getVersion();
+    const archivePath = await downloadFromGitHub(target, version);
+    const binaryName = getBinaryName(target);
+    const isWindows = process.platform === "win32";
+
+    if (isWindows) {
+      extractZip(archivePath, binaryName, outputPath);
+    } else {
+      extractTarGz(archivePath, binaryName, outputPath);
+    }
+
+    chmodSync(outputPath, 0o755);
+    createAliases(outputPath);
+    console.log("ziex binary installed successfully!");
+  } catch (err) {
+    console.error(`Failed to install ziex binary: ${err.message}`);
+    console.error("You can install it manually from: https://ziex.dev/install");
+    process.exit(1);
+  }
+}
+
+function createAliases(zxPath) {
+  const binDir = path.dirname(zxPath);
+  const isWindows = process.platform === "win32";
+  const ziexPath = path.join(binDir, isWindows ? "ziex.exe" : "ziex");
+
+  // The main binary is `zx`, create `ziex` as a copy/symlink
+  try {
+    if (existsSync(ziexPath) && ziexPath !== zxPath) unlinkSync(ziexPath);
+    if (ziexPath !== zxPath) {
+      try {
+        const fs = require("fs");
+        fs.symlinkSync(path.basename(zxPath), ziexPath);
+      } catch {
+        copyFileSync(zxPath, ziexPath);
+      }
+    }
+  } catch {
+    // Non-critical
+  }
+}
+
+main().catch((err) => {
+  console.error(err.message);
+  process.exit(1);
+});

package/kv.d.ts

@@ -0,0 +1,27 @@
+export interface KVNamespace {
+    get(key: string): Promise<string | null>;
+    put(key: string, value: string, options?: {
+        expiration?: number;
+        expirationTtl?: number;
+    }): Promise<void>;
+    delete(key: string): Promise<void>;
+    list(options?: {
+        prefix?: string;
+    }): Promise<{
+        keys: {
+            name: string;
+        }[];
+    }>;
+}
+/**
+ * In-memory KV namespace. Used as the default shim on platforms that don't
+ * provide a real KV binding (e.g. Vercel). Data lives only for the lifetime
+ * of the isolate instance.
+ */
+export declare function createMemoryKV(): KVNamespace;
+/**
+ * Create a `__zx_kv` import object for use with `run({ kv: ... })`.
+ * Always returns a valid import object. When JSPI is unavailable all KV
+ * operations are stubbed (get → not-found, put/delete → success, list → []).
+ */
+export declare function createKVImports(bindings: Record<string, KVNamespace>, getMemory: () => WebAssembly.Memory): Record<string, unknown>;

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@ziex/cli",
+  "version": "0.1.0-dev.865",
+  "description": "ZX is a framework for building web applications with Zig.",
+  "main": "index.js",
+  "type": "module",
+  "bin": {
+    "ziex": "bin/ziex",
+    "zx": "bin/ziex"
+  },
+  "exports": {
+    ".": "./index.js",
+    "./react": "./react/index.js",
+    "./wasm": "./wasm/index.js",
+    "./wasm/init": "./wasm/init.js",
+    "./cloudflare": "./cloudflare/index.js",
+    "./aws-lambda": "./aws-lambda/index.js",
+    "./vercel": "./vercel/index.js"
+  },
+  "homepage": "https://ziex.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ziex-dev/ziex.git"
+  },
+  "keywords": [
+    "zx",
+    "zig",
+    "web framework",
+    "jsx",
+    "react",
+    "server components",
+    "client components",
+    "server actions",
+    "client actions",
+    "server actions"
+  ],
+  "author": "Nurul Huda (Apon) <me@nurulhudaapon.com>",
+  "license": "MIT",
+  "scripts": {
+    "postinstall": "node install.js"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
+  },
+  "optionalDependencies": {
+    "@ziex/cli-darwin-arm64": "0.1.0-dev.805",
+    "@ziex/cli-darwin-x64": "0.1.0-dev.805",
+    "@ziex/cli-linux-x64": "0.1.0-dev.805",
+    "@ziex/cli-linux-arm64": "0.1.0-dev.805",
+    "@ziex/cli-win32-x64": "0.1.0-dev.805",
+    "@ziex/cli-win32-arm64": "0.1.0-dev.805"
+  },
+  "module": "index.js",
+  "types": "index.d.ts"
+}

package/react/dom.d.ts

@@ -0,0 +1,21 @@
+import type { ComponentMetadata } from "./types";
+export type PreparedComponent = {
+    domNode: HTMLElement;
+    props: Record<string, any> & {
+        dangerouslySetInnerHTML?: {
+            __html: string;
+        };
+    };
+    Component: (props: any) => React.ReactElement;
+};
+export declare function prepareComponent(component: ComponentMetadata): Promise<PreparedComponent>;
+export declare function filterComponents(components: ComponentMetadata[]): ComponentMetadata[];
+export type DiscoveredComponent = {
+    id: string;
+    name: string;
+    props: Record<string, any>;
+    container: HTMLElement;
+};
+export declare function discoverComponents(): DiscoveredComponent[];
+export type ComponentRegistry = Record<string, () => Promise<(props: any) => React.ReactElement>>;
+export declare function hydrateAll(registry: ComponentRegistry, render: (container: HTMLElement, Component: (props: any) => React.ReactElement, props: Record<string, any>) => void): Promise<void>;

package/react/index.d.ts

@@ -0,0 +1,2 @@
+export { prepareComponent, filterComponents, discoverComponents, hydrateAll, type PreparedComponent, type DiscoveredComponent, type ComponentRegistry, } from "./dom";
+export type { ComponentMetadata } from "./types";

package/react/index.js

@@ -0,0 +1,144 @@
+var __defProp = Object.defineProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: (newValue) => all[name] = () => newValue
+    });
+};
+
+// src/react/dom.ts
+function findCommentMarker(id) {
+  const startPrefix = `$${id} `;
+  const endMarker = `/$${id}`;
+  const walker = document.createTreeWalker(document.body, NodeFilter.SHOW_COMMENT, null);
+  let startComment = null;
+  let endComment = null;
+  let name = "";
+  let props = {};
+  let node;
+  while (node = walker.nextNode()) {
+    const text = node.textContent?.trim() || "";
+    if (text.startsWith(startPrefix)) {
+      startComment = node;
+      const content = text.slice(startPrefix.length);
+      const jsonStart = content.indexOf("{");
+      if (jsonStart !== -1) {
+        name = content.slice(0, jsonStart).trim();
+        const jsonStr = content.slice(jsonStart);
+        try {
+          props = JSON.parse(jsonStr);
+        } catch {}
+      } else {
+        name = content.trim();
+      }
+    }
+    if (text === endMarker) {
+      endComment = node;
+      break;
+    }
+  }
+  if (startComment && endComment) {
+    return { startComment, endComment, name, props };
+  }
+  return null;
+}
+function createContainerBetweenMarkers(startComment, endComment) {
+  const container = document.createElement("div");
+  container.style.display = "contents";
+  let current = startComment.nextSibling;
+  while (current && current !== endComment) {
+    const next = current.nextSibling;
+    container.appendChild(current);
+    current = next;
+  }
+  endComment.parentNode?.insertBefore(container, endComment);
+  return container;
+}
+async function prepareComponent(component) {
+  const marker = findCommentMarker(component.id);
+  if (!marker) {
+    throw new Error(`Comment marker for ${component.id} not found`, { cause: component });
+  }
+  const props = marker.props;
+  const domNode = createContainerBetweenMarkers(marker.startComment, marker.endComment);
+  const Component = await component.import();
+  return { domNode, props, Component };
+}
+function filterComponents(components) {
+  const currentPath = window.location.pathname;
+  return components.filter((component) => component.route === currentPath || !component.route);
+}
+function discoverComponents() {
+  const components = [];
+  const walker = document.createTreeWalker(document.body, NodeFilter.SHOW_COMMENT, null);
+  const markers = [];
+  let node;
+  while (node = walker.nextNode()) {
+    const text = node.textContent?.trim() || "";
+    if (text.startsWith("$") && !text.startsWith("/$")) {
+      const spaceIdx = text.indexOf(" ");
+      if (spaceIdx !== -1) {
+        const id = text.slice(1, spaceIdx);
+        const content = text.slice(spaceIdx + 1);
+        if (content.startsWith("[")) {
+          continue;
+        }
+        const jsonStart = content.indexOf("{");
+        let name = "";
+        let props = {};
+        if (jsonStart !== -1) {
+          name = content.slice(0, jsonStart).trim();
+          try {
+            props = JSON.parse(content.slice(jsonStart));
+          } catch {}
+        } else {
+          name = content.trim();
+        }
+        markers.push({ id, name, props, startComment: node, endComment: null });
+      }
+    } else if (text.startsWith("/$")) {
+      const id = text.slice(2);
+      const marker = markers.find((m) => m.id === id && !m.endComment);
+      if (marker) {
+        marker.endComment = node;
+      }
+    }
+  }
+  for (const marker of markers) {
+    if (!marker.endComment)
+      continue;
+    const container = createContainerBetweenMarkers(marker.startComment, marker.endComment);
+    components.push({
+      id: marker.id,
+      name: marker.name,
+      props: marker.props,
+      container
+    });
+  }
+  return components;
+}
+async function hydrateAll(registry, render) {
+  const components = discoverComponents();
+  await Promise.all(components.map(async ({ name, props, container }) => {
+    const importer = registry[name];
+    if (!importer) {
+      console.warn(`Component "${name}" not found in registry`);
+      return;
+    }
+    try {
+      const Component = await importer();
+      render(container, Component, props);
+    } catch (error) {
+      console.error(`Failed to hydrate "${name}":`, error);
+    }
+  }));
+}
+export {
+  prepareComponent,
+  hydrateAll,
+  filterComponents,
+  discoverComponents
+};

package/react/types.d.ts

@@ -0,0 +1,190 @@
+/**
+ * Metadata for a client-side component used within a ZX file.
+ *
+ * This type represents the metadata for components that are marked with the `@rendering` attribute
+ * in ZX files. When a component is declared with `@rendering={.react}` or `@rendering={.client}` in a
+ * `.zx` file, the ZX transpiler generates a `ComponentMetadata` entry that is included in the
+ * generated `components` array.
+ *
+ * @example
+ * ```tsx
+ * // In a ZX file (page.zx):
+ * <CounterComponent @rendering={.react} max_count={10} />
+ *
+ * // Generated components array (components.ts):
+ * export const components: ComponentMetadata[] = [
+ *   {
+ *     name: "CounterComponent",
+ *     path: "./components/CounterComponent.tsx",
+ *     id: "zx-dcde04c415da9d1b15ca2690d8b497ae",
+ *     type: "react",
+ *     import: () => import('./components/CounterComponent.tsx')
+ *   }
+ * ];
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Using ComponentMetadata with prepareComponent:
+ * import { prepareComponent, type ComponentMetadata } from "ziex";
+ *
+ * for (const component of components) {
+ *   const { domNode, props, Component } = await prepareComponent(component);
+ *   // Render component to DOM node
+ * }
+ * ```
+ */
+export type ComponentMetadata = {
+    /**
+     * The name of the component as declared in the ZX file.
+     *
+     * This is the tag name used in JSX syntax within `.zx` files. It corresponds to the component
+     * identifier used in the component declaration (e.g., `<CounterComponent />`).
+     *
+     * @example
+     * ```tsx
+     * // In ZX file:
+     * <CounterComponent @rendering={.react} />
+     *
+     * // name will be: "CounterComponent"
+     * ```
+     */
+    name: string;
+    /**
+     * The file path to the component module.
+     *
+     * This is the relative or absolute path to the component file that will be dynamically imported
+     * at runtime. For CSR components, this typically points to a `.tsx` or `.jsx` file. For Client
+     * components, this points to a Zig component file.
+     *
+     * The path is determined from the `@jsImport` directive in the ZX file, or defaults to
+     * `./{componentName}.tsx` if not explicitly specified.
+     *
+     * @example
+     * ```tsx
+     * // In ZX file:
+     * const CounterComponent = @jsImport("components/Counter.tsx");
+     * <CounterComponent @rendering={.react} />
+     *
+     * // path will be: "components/Counter.tsx"
+     * ```
+     *
+     * @example
+     * ```tsx
+     * // Without explicit @jsImport:
+     * <MyComponent @rendering={.react} />
+     *
+     * // path will default to: "./MyComponent.tsx"
+     * ```
+     */
+    path: string;
+    /**
+     * The route of of the component in which page the component was used,
+     * null in case the component was used in other non-page/layout context.
+     * ```
+     */
+    route: string | null;
+    /**
+     * A unique identifier for the component's hydration boundary.
+     *
+     * This ID is generated by hashing the component's path and name using MD5, then formatting it
+     * as a hex string with the "zx-" prefix and a counter suffix. The ID is used to locate the
+     * component's comment markers in the DOM during client-side hydration.
+     *
+     * The ID format is: `zx-{32 hex characters}-{counter}` (e.g., `zx-dcde04c415da9d1b15ca2690d8b497ae-0`)
+     *
+     * The ZX runtime renders components with comment markers in the format:
+     * `<!--$id name props-->...<!--/$id-->`
+     *
+     * @example
+     * ```tsx
+     * // Component metadata:
+     * {
+     *   name: "CounterComponent",
+     *   path: "./components/Counter.tsx",
+     *   id: "zx-dcde04c415da9d1b15ca2690d8b497ae-0"
+     * }
+     *
+     * // Generated HTML with comment markers:
+     * <!--$zx-dcde04c415da9d1b15ca2690d8b497ae-0 CounterComponent {"max_count":10}-->
+     * <button>0</button>
+     * <!--/$zx-dcde04c415da9d1b15ca2690d8b497ae-0-->
+     * ```
+     */
+    id: string;
+    /**
+     * The rendering type of the component, determining how it will be rendered on the client.
+     *
+     * - **"react"** (Client Side React): The component is a React component that will be rendered
+     *   using React's client-side rendering. The component file should export a default React
+     *   component function. This is the most common type for interactive UI components.
+     *
+     * - **"client"** (Client Side Zig): The component is a Zig component that will be compiled to
+     *   WebAssembly and rendered on the client side. This allows you to use Zig's performance
+     *   and type safety for client-side components.
+     *
+     * The type is determined by the `@rendering` attribute value in the ZX file (`.react` or `.client`).
+     *
+     * @example
+     * ```tsx
+     * // CSR component (React):
+     * <CounterComponent @rendering={.react} max_count={10} />
+     * // type: "react"
+     *
+     * // Component file (CounterComponent.tsx):
+     * export default function CounterComponent({ max_count }: { max_count: number }) {
+     *   return <div>Count: {max_count}</div>;
+     * }
+     * ```
+     *
+     * @example
+     * ```tsx
+     * // Client component (Zig/WASM):
+     * <CounterComponent @rendering={.client} />
+     * // type: "client"
+     *
+     * // Component file (CounterComponent.zig):
+     * pub fn CounterComponent(allocator: zx.Allocator) zx.Component {
+     *   return (<div @allocator={allocator}>Counter</div>);
+     * }
+     * ```
+     */
+    type: "react" | "client";
+    /**
+     * A lazy-loading function that dynamically imports the component module.
+     *
+     * This function returns a Promise that resolves to the component function. It enables
+     * code-splitting and lazy loading of components, improving initial page load performance
+     * by only loading components when they are needed.
+     *
+     * For CSR components, the imported module should export a default React component.
+     * For Client components, the import mechanism depends on the WASM module structure.
+     *
+     * The function is called during client-side hydration to load and render the component
+     * into its corresponding DOM container element.
+     *
+     * @returns A Promise that resolves to a component function that accepts props and returns a React element.
+     *
+     * @example
+     * ```tsx
+     * // Component metadata:
+     * {
+     *   import: () => import('./components/CounterComponent.tsx')
+     * }
+     *
+     * // Usage:
+     * const Component = await component.import();
+     * // Component is now the default export from CounterComponent.tsx
+     * ```
+     *
+     * @example
+     * ```tsx
+     * // With prepareComponent helper:
+     * import { prepareComponent } from "ziex";
+     *
+     * const { Component, props, domNode } = await prepareComponent(component);
+     * // Component is loaded and ready to render with props
+     * ```
+     */
+    import: () => Promise<(props: any) => React.ReactElement>;
+};