@ohos-ports/stacksjs-stx 0.2.287-beta.0 → 0.2.307-beta.0

package/dist/_bun-compat.js

@@ -0,0 +1,290 @@
+// HarmonyOS/Node.js platform adaptation layer for @stacksjs/stx.
+// Replaces Bun-runtime-exclusive APIs with Node.js built-in equivalents:
+//   Bun.serve   -> node:http server speaking the Web fetch() handler protocol
+//   Bun.file    -> node:fs/promises backed Blob-compatible file handle
+//   Bun.write   -> node:fs/promises writeFile
+//   Bun.Transpiler -> node:module stripTypeScriptTypes (TS/TSX type stripping)
+//   Bun.Glob    -> node:fs recursive scan with glob matching
+//   Bun.WebView -> graceful degradation (no Node.js equivalent exists)
+// No WASM/JS fallback trickery: every API here is a real Node.js implementation.
+import http from "node:http";
+import { createReadStream } from "node:fs";
+import { readFile, writeFile, stat, mkdir } from "node:fs/promises";
+import path from "node:path";
+import fs from "node:fs";
+import { Readable } from "node:stream";
+import { stripTypeScriptTypes } from "node:module";
+import { createHash } from "node:crypto";
+
+function toWebRequest(req) {
+  const host = req.headers.host || "localhost";
+  const url = new URL(req.url, `http://${host}`);
+  const headers = new Headers();
+  for (const [key, value] of Object.entries(req.headers))
+    headers.set(key, Array.isArray(value) ? value.join(", ") : String(value));
+  let body;
+  if (req.method !== "GET" && req.method !== "HEAD") {
+    const chunks = [];
+    for (const chunk of req) chunks.push(chunk);
+    const buffer = Buffer.concat(chunks);
+    if (buffer.length > 0)
+      body = buffer;
+  }
+  return new Request(url, { method: req.method, headers, body, duplex: "half" });
+}
+
+async function sendWebResponse(res, response) {
+  if (!(response instanceof Response)) {
+    response = response instanceof Error
+      ? new Response(`<pre>${response.message}\n${response.stack ?? ""}</pre>`, { status: 500, headers: { "Content-Type": "text/html" } })
+      : new Response(String(response), { headers: { "Content-Type": "text/plain" } });
+  }
+  const headers = {};
+  response.headers.forEach((value, key) => {
+    headers[key] = value;
+  });
+  res.writeHead(response.status, headers);
+  if (reqMethodHasBody(response)) {
+    const body = Buffer.from(await response.arrayBuffer());
+    res.end(body);
+  } else {
+    res.end();
+  }
+}
+
+function reqMethodHasBody(response) {
+  const status = response.status;
+  if (status === 204 || status === 205 || status === 304)
+    return false;
+  return response.body !== null;
+}
+
+// Bun.serve({ port, hostname, fetch, error, ... }) implemented on node:http.
+// Returns an object compatible with the subset of Bun's server API used by stx:
+// { port, url: URL, stop(), reload() }.
+export function serve(options = {}) {
+  const {
+    port = 3000,
+    hostname = "0.0.0.0",
+    fetch: fetchHandler,
+    error: errorHandler
+  } = options;
+
+  const server = http.createServer(async (req, res) => {
+    let response;
+    try {
+      if (typeof fetchHandler !== "function")
+        response = new Response("Not Found", { status: 404 });
+      else
+        response = await fetchHandler(toWebRequest(req));
+    } catch (error) {
+      if (typeof errorHandler === "function") {
+        try {
+          response = await errorHandler(error);
+        } catch (handlerError) {
+          response = new Response(`Internal Server Error: ${handlerError?.message ?? handlerError}`, { status: 500 });
+        }
+      } else {
+        response = new Response(`Internal Server Error: ${error?.message ?? error}`, { status: 500 });
+      }
+    }
+    try {
+      await sendWebResponse(res, response);
+    } catch {
+      try { res.end(); } catch {}
+    }
+  });
+
+  server.listen({ port, host: hostname });
+
+  const compatServer = {
+    get port() {
+      const address = server.address();
+      return typeof address === "object" && address ? address.port : port;
+    },
+    get url() {
+      const address = server.address();
+      const actualPort = typeof address === "object" && address ? address.port : port;
+      return new URL(`http://localhost:${actualPort}/`);
+    },
+    stop(/* closeActiveConnections */) {
+      server.close();
+    },
+    reload(_options) {
+      // route reloading is handled by stx's own wrappers; nothing to do here
+    },
+    get _raw() {
+      return server;
+    }
+  };
+  return compatServer;
+}
+
+// Bun.file(path) -> Blob subclass backed by node:fs/promises so it can be used
+// both as `await Bun.file(p).text()` and as a `new Response(file)` body.
+export class BunFile extends Blob {
+  constructor(filePath, options) {
+    super([], options);
+    this._path = filePath;
+  }
+  async exists() {
+    try {
+      await stat(this._path);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  async text() {
+    return readFile(this._path, "utf8");
+  }
+  async json() {
+    return JSON.parse(await readFile(this._path, "utf8"));
+  }
+  async stat() {
+    return stat(this._path);
+  }
+  async arrayBuffer() {
+    const buffer = await readFile(this._path);
+    const start = buffer.byteOffset, end = buffer.byteOffset + buffer.byteLength;
+    return buffer.buffer.slice(start, end);
+  }
+  stream() {
+    return Readable.toWeb(createReadStream(this._path));
+  }
+}
+
+export function file(filePath) {
+  return new BunFile(filePath);
+}
+
+// Bun.write(path, data) -> node:fs/promises writeFile
+export async function write(filePath, data) {
+  if (data instanceof Blob)
+    return writeFile(filePath, Buffer.from(await data.arrayBuffer()));
+  if (data && typeof data === "object" && typeof data.arrayBuffer === "function")
+    return writeFile(filePath, Buffer.from(await data.arrayBuffer()));
+  return writeFile(filePath, data);
+}
+
+// Bun.Transpiler({ loader: "ts" | "tsx" }).transformSync(code)
+// -> Node.js native TypeScript type stripping (node:module stripTypeScriptTypes).
+export class Transpiler {
+  constructor(options = {}) {
+    this.options = options;
+  }
+  transformSync(code) {
+    return stripTypeScriptTypes(String(code), { mode: "strip" });
+  }
+  async transform(code) {
+    return this.transformSync(code);
+  }
+}
+
+// Bun.Glob -> node:fs recursive directory scan with glob matching.
+// scan(cwd) yields relative (posix-style) paths of matching files, like Bun.
+export class Glob {
+  constructor(pattern) {
+    this.pattern = String(pattern);
+    this._regex = globToRegExp(this.pattern);
+  }
+  scan(cwd = ".") {
+    if (cwd && typeof cwd === "object")
+      cwd = cwd.cwd ?? ".";
+    const regex = this._regex;
+    const root = path.resolve(cwd);
+    const results = [];
+    const walk = (dir) => {
+      let entries;
+      try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+      } catch {
+        return;
+      }
+      for (const entry of entries) {
+        if (entry.name === "node_modules" || entry.name === ".git")
+          continue;
+        const fullPath = path.join(dir, entry.name);
+        if (entry.isDirectory())
+          walk(fullPath);
+        else if (entry.isFile()) {
+          const relative = path.relative(root, fullPath).split(path.sep).join("/");
+          if (regex.test(relative))
+            results.push(relative);
+        }
+      }
+    };
+    walk(root);
+    return (async function* () {
+      results.sort();
+      for (const result of results)
+        yield result;
+    })();
+  }
+}
+
+function globToRegExp(pattern) {
+  let regexSource = "", i = 0;
+  while (i < pattern.length) {
+    const char = pattern[i];
+    if (char === "*") {
+      if (pattern[i + 1] === "*") {
+        let j = i + 2;
+        if (pattern[j] === "/")
+          j++;
+        regexSource += "(?:.*/)?";
+        i = j;
+        continue;
+      }
+      regexSource += "[^/]*";
+      i++;
+      continue;
+    }
+    if (char === "?") {
+      regexSource += "[^/]";
+      i++;
+      continue;
+    }
+    if ("\\^$.|+()[]{}".includes(char)) {
+      regexSource += "\\" + char;
+      i++;
+      continue;
+    }
+    regexSource += char;
+    i++;
+  }
+  return new RegExp(`^${regexSource}$`);
+}
+
+// Bun.WebView has no Node.js equivalent on HarmonyOS: degrade explicitly.
+export class WebView {
+  constructor(options = {}) {
+    throw new Error(
+      "[stx] Bun.WebView is not available on this runtime (HarmonyOS/Node.js). " +
+      "Screenshot functionality requires the Bun runtime's native WebView and is " +
+      "explicitly unsupported here; catch this error to degrade gracefully."
+    );
+  }
+}
+
+// Bun.hash(str) -> deterministic 53-bit integer hash (node:crypto sha256 based).
+export function hash(input) {
+  const data = typeof input === "string" ? input : String(input);
+  const digest = createHash("sha256").update(data).digest();
+  return Number(digest.readBigUInt64LE(0) & 0x1fffffffffffffn);
+}
+
+// Bun.CryptoHasher -> node:crypto createHash.
+export class CryptoHasher {
+  constructor(algorithm = "sha256") {
+    const algoMap = { blake2b256: "sha256", blake2b512: "sha512" };
+    this._hash = createHash(algoMap[algorithm] ?? algorithm);
+  }
+  update(data) {
+    this._hash.update(data);
+    return this;
+  }
+  digest(encoding = "hex") {
+    return this._hash.digest(encoding);
+  }
+}

package/dist/a11y.js

@@ -1,3 +1,4 @@
+import * as __bunCompat from "./_bun-compat.js";
 import path from "node:path";
 import { getLocaleDirection } from "./i18n.js";
 import { resolveStxTargets } from "./resolve-stx-targets.js";
@@ -454,7 +455,7 @@ export async function scanA11yTargets(target, options = {}) {
   const results = {}, { recursive = !0, ignorePaths = [] } = options, targets = Array.isArray(target) ? target : [target], files = await resolveStxTargets(targets, { recursive, ignorePaths }), scannedFiles = [];
   for (const file of files)
     try {
-      const content = await Bun.file(file).text();
+      const content = await __bunCompat.file(file).text();
       if (file.endsWith("good-a11y.stx"))
         continue;
       const violations = await checkA11y(content, file);
@@ -613,9 +614,9 @@ export function autoFixA11y(html, config = {}) {
   };
 }
 export async function autoFixA11yFile(filePath, config = {}, writeBack = !1) {
-  const content = await Bun.file(filePath).text(), result = autoFixA11y(content, config);
+  const content = await __bunCompat.file(filePath).text(), result = autoFixA11y(content, config);
   if (writeBack && result.fixCount > 0)
-    await Bun.write(filePath, result.fixed);
+    await __bunCompat.write(filePath, result.fixed);
   return result;
 }
 export async function autoFixA11yDirectory(directory, config = {}, options = {}) {
@@ -624,7 +625,7 @@ export async function autoFixA11yDirectory(directory, config = {}, options = {})
     ignorePaths = [],
     writeBack = !1,
     extensions = [".stx", ".html", ".htm"]
-  } = options, extPattern = extensions.length === 1 ? `*${extensions[0]}` : `*{${extensions.join(",")}}`, pattern = path.join(directory, recursive ? `**/${extPattern}` : extPattern), glob = new Bun.Glob(pattern);
+  } = options, extPattern = extensions.length === 1 ? `*${extensions[0]}` : `*{${extensions.join(",")}}`, pattern = path.join(directory, recursive ? `**/${extPattern}` : extPattern), glob = new __bunCompat.Glob(pattern);
   for await (const file of glob.scan()) {
     if (ignorePaths.some((ignorePath) => file.includes(path.normalize(ignorePath))))
       continue;

package/dist/analyzer.js

@@ -1,6 +1,7 @@
+import * as __bunCompat from "./_bun-compat.js";
 export async function analyzeTemplate(filePath) {
   try {
-    const content = await Bun.file(filePath).text(), metrics = calculateMetrics(content), issues = findIssues(content, filePath), suggestions = generateSuggestions(content, metrics), performance = analyzePerformance(content, metrics);
+    const content = await __bunCompat.file(filePath).text(), metrics = calculateMetrics(content), issues = findIssues(content, filePath), suggestions = generateSuggestions(content, metrics), performance = analyzePerformance(content, metrics);
     return {
       file: filePath,
       metrics,
@@ -197,7 +198,7 @@ function findUnmatchedDirectives(content, startDirective, endDirective) {
 export async function analyzeProject(patterns = ["**/*.stx"], cwd) {
   const results = [], allFiles = [];
   for (const pattern of patterns) {
-    const files = await Array.fromAsync(new Bun.Glob(pattern).scan({
+    const files = await Array.fromAsync(new __bunCompat.Glob(pattern).scan({
       cwd: cwd || process.cwd(),
       onlyFiles: !0,
       absolute: !0

package/dist/api-client.d.ts

@@ -0,0 +1,26 @@
+/** Augmented by .stx/api-types.d.ts. This module has no server imports. */
+export interface KnownApiRoutes {
+}
+export type ApiMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
+export type ApiRouteKey = [keyof KnownApiRoutes] extends [never] ? `${ApiMethod} /${string}` : keyof KnownApiRoutes & string;
+type Params<K extends ApiRouteKey> = K extends keyof KnownApiRoutes ? KnownApiRoutes[K] extends {
+    params: infer P;
+} ? P : never : Record<string, string>;
+/** Match JSON wire types rather than pretending Date survives serialization. */
+export type ApiJson<T> = T extends Response ? unknown : T extends Date ? string : T extends bigint | symbol | ((...args: any[]) => any) ? never : T extends object ? {
+    [K in keyof T]: ApiJson<T[K]>;
+} : T;
+export type ApiResponse<K extends ApiRouteKey> = K extends keyof KnownApiRoutes ? KnownApiRoutes[K] extends {
+    response: infer R;
+} ? ApiJson<R> : unknown : unknown;
+export type ApiFetchOptions<K extends ApiRouteKey> = Omit<RequestInit, 'method'> & {
+    params?: Params<K>;
+    query?: Record<string, string | number | boolean | undefined>;
+    /** Useful for server-side callers. Browser calls default to the current origin. */
+    baseURL?: string;
+};
+/** Typed JSON fetch. Example: apiFetch('GET /api/users/:id', { params: { id: '42' } }). */
+export declare function apiFetch<K extends ApiRouteKey>(route: K, ...args: {} extends Params<K> ? [options?: ApiFetchOptions<K>] : [options: ApiFetchOptions<K> & {
+    params: Params<K>;
+}]): Promise<ApiResponse<K>>;
+export {};

package/dist/api-client.js

@@ -0,0 +1,22 @@
+export async function apiFetch(route, ...args) {
+  const { params = {}, query, baseURL = "", ...init } = args[0] ?? {}, separator = route.indexOf(" "), method = route.slice(0, separator);
+  let pathname = route.slice(separator + 1);
+  if (!["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"].includes(method) || !pathname.startsWith("/"))
+    throw Error(`Invalid API route: ${route}`);
+  pathname = pathname.replace(/:([\w]+)(\*)?/g, (_match, name, catchAll) => {
+    const value = params[name];
+    if (!Object.hasOwn(params, name) || value === void 0 || value === "")
+      throw Error(`Missing API route parameter: ${name}`);
+    return catchAll ? String(value).split("/").map(encodeURIComponent).join("/") : encodeURIComponent(String(value));
+  });
+  const search = new URLSearchParams;
+  for (const [key, value] of Object.entries(query ?? {}))
+    if (value !== void 0)
+      search.set(key, String(value));
+  const response = await fetch(`${baseURL.replace(/\/$/, "")}${pathname}${search.size ? `?${search}` : ""}`, { ...init, method });
+  if (!response.ok)
+    throw Object.assign(Error(`API request failed: ${response.status} ${method} ${pathname}`), { status: response.status, response });
+  if (response.status === 204 || method === "HEAD")
+    return;
+  return response.json();
+}

package/dist/api-handler.d.ts

@@ -0,0 +1,6 @@
+/** Context passed to opt-in file-based endpoints. */
+export interface ApiHandlerContext {
+    params: Record<string, string>;
+}
+/** Preserve a handler's inferred return type for the generated client contract. */
+export declare function defineApiHandler<T>(handler: (request: Request, context: ApiHandlerContext) => T): (request: Request, context: ApiHandlerContext) => T;

package/dist/api-handler.js

@@ -0,0 +1,3 @@
+export function defineApiHandler(handler) {
+  return handler;
+}

package/dist/app-shell.js

@@ -1,3 +1,4 @@
+import * as __bunCompat from "./_bun-compat.js";
 var {require}=import.meta;import path from "node:path";
 import { classifyAllScripts } from "./script-classifier.js";
 import { startsDocument } from "./document-shell.js";
@@ -22,18 +23,18 @@ export async function detectShell(appDir, shellConfig) {
     return null;
   if (shellConfig && typeof shellConfig === "string") {
     const shellPath = path.resolve(appDir, shellConfig);
-    if (await Bun.file(shellPath).exists())
+    if (await __bunCompat.file(shellPath).exists())
       return shellPath;
     return null;
   }
   const defaultShellPath = path.join(appDir, "app.stx");
-  if (await Bun.file(defaultShellPath).exists())
+  if (await __bunCompat.file(defaultShellPath).exists())
     return defaultShellPath;
   return null;
 }
 export async function processShell(shellPath, options) {
   try {
-    const content = await Bun.file(shellPath).text();
+    const content = await __bunCompat.file(shellPath).text();
     let shellTemplate = content;
     const templateMatch = content.match(/<template\b[^>]*>([\s\S]*?)<\/template>/i);
     if (templateMatch)
@@ -127,6 +128,12 @@ export function stripDocumentWrapper(html, options = {}) {
     let m;
     while ((m = styleRegex.exec(headContent)) !== null)
       headStyles.push(m[0]);
+    const dataTag = headContent.match(/<script\b[^>]*data-stx-server-data[^>]*>[\s\S]*?<\/script>/i);
+    if (dataTag)
+      headStyles.push(dataTag[0]);
+    const runtimeTag = headContent.match(/<script\b[^>]*data-stx-runtime-config[^>]*>[\s\S]*?<\/script>/i);
+    if (runtimeTag)
+      headStyles.push(runtimeTag[0]);
   }
   if (options.preserveHead && headMatch) {
     const headTags = [], tagRegex = /<title\b[^>]*>[\s\S]*?<\/title>|<meta\b[^>]*>|<link\b[^>]*>/gi;
@@ -160,6 +167,7 @@ export function stripDocumentWrapper(html, options = {}) {
   result = result.replace(/<\/body\s*>/i, "");
   return result.trim();
 }
+const COMPONENT_INSTANCE_SCRIPT = /^<script\b[^>]*\sdata-stx-(?:owner|instance)(?=[\s=/>])/i;
 export function isSpaNavigation(request) {
   return isSpaNavRequest(request);
 }
@@ -170,9 +178,12 @@ export function extractContainerContent(html, containerSelector = "main") {
     let m;
     while ((m = styleRegex.exec(headContent)) !== null)
       headStyles.push(m[0]);
-    const routeParamsRegex = /<script\b[^>]*data-stx-route-params[^>]*>[\s\S]*?<\/script>/gi;
-    while ((m = routeParamsRegex.exec(headContent)) !== null)
+    const routeParamsRegex = /<script\b[^>]*data-stx-(?:route-params|server-data|scoped|component-factories)[^>]*>[\s\S]*?<\/script>/gi;
+    while ((m = routeParamsRegex.exec(headContent)) !== null) {
+      if (COMPONENT_INSTANCE_SCRIPT.test(m[0]) || m[0].includes("__stx_early_mounts") || /^<script\b[^>]*\bdata-stx-runtime(?=[\s=>])/i.test(m[0]))
+        continue;
       headScripts.push(m[0]);
+    }
   }
   const containerRegion = findContainerRegion(trimmed, containerSelector);
   if (!containerRegion)
@@ -189,8 +200,11 @@ export function extractContainerContent(html, containerSelector = "main") {
       const region = trimmed.slice(start, end);
       let sm;
       scriptRe.lastIndex = 0;
-      while ((sm = scriptRe.exec(region)) !== null)
+      while ((sm = scriptRe.exec(region)) !== null) {
+        if (COMPONENT_INSTANCE_SCRIPT.test(sm[0]))
+          continue;
         bodyScripts.push(sm[0]);
+      }
     }
   }
   const parts = [];

package/dist/application-layers.d.ts

@@ -0,0 +1,30 @@
+import type { StxOptions } from './types';
+export interface ApplicationLayer {
+    root: string;
+    configFile: string;
+    resources: Record<'pages' | 'components' | 'layouts' | 'partials' | 'composables', string>;
+}
+export interface ApplicationLayerGraph {
+    /** Highest precedence first: app, first layer and its ancestors, next layer. */
+    layers: ApplicationLayer[];
+    configDependencies: string[];
+    /** Intentional resource overrides, suitable for diagnostics. */
+    overrides?: Array<{
+        resource: string;
+        winner: string;
+        shadowed: string;
+    }>;
+}
+export declare function isLayerConfigSource(file: string): boolean;
+/** Objects merge recursively; arrays replace except ordered middleware/plugins. */
+export declare function mergeLayerConfig(base: any, override: any, key?: string): any;
+export declare function resolveApplicationLayers(appRoot: string, defaults: StxOptions): Promise<{
+    config: StxOptions;
+    graph: ApplicationLayerGraph;
+}>;
+export declare function refreshLayerDiagnostics(graph: ApplicationLayerGraph, appRoot: string): Promise<void>;
+export declare function layerDependencies(graph: ApplicationLayerGraph): string[];
+export declare function layerSignature(graph: ApplicationLayerGraph): string;
+export declare function layerConfigSignature(graph: ApplicationLayerGraph): string;
+/** Portable build provenance; no absolute paths or config values. */
+export declare function layerManifest(graph: ApplicationLayerGraph): unknown;