@pajh/buldng 0.0.2 → 0.0.4

package/package.json

@@ -1,19 +1,23 @@
 {
   "name": "@pajh/buldng",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "type": "module",
-  "main": "dist/init.js",
-  "files": ["dist"],
+  "main": "./src/buldng-lib.js",
+  "files": [
+    "src"
+  ],
   "scripts": {
-    "build": "node build.js"
+    "check": "tsc --noEmit",
+    "build": "npm run check"
   },
   "dependencies": {
-   "esbuild": "^0.28.1",
-   "typescript": "^7.0.2"
+    "esbuild": "^0.28.2"
   },
   "devDependencies": {
-   "stylelint": "^17.14.1",
-   "stylelint-config-standard": "^40.0.0"
-}
-
+    "typescript": "^6.0.3"
+  },
+  "exports": {
+    ".": "./src/buldng-lib.js",
+    "./web": "./src/buldng-web.ts"
+  }
 }

package/src/buldng-dev-errors.js

@@ -0,0 +1,84 @@
+// Development-only error overlay installed by the local preview server.
+// The production build never references this file from its HTML.
+
+window.__buldngErrorOverlay = true;
+
+let shown = false;
+
+window.addEventListener("error", (event) => {
+  showError(event.error ?? event.message, "error");
+});
+
+window.addEventListener("unhandledrejection", (event) => {
+  showError(event.reason, "unhandledrejection");
+});
+
+function showError(reason, type) {
+  if (shown) return;
+  shown = true;
+
+  const message = getMessage(reason);
+  const stack = getStack(reason);
+  const overlay = document.createElement("aside");
+  overlay.id = "buldng-dev-error-overlay";
+  overlay.style.cssText = [
+    "position: fixed",
+    "z-index: 2147483647",
+    "left: 1rem",
+    "right: 1rem",
+    "bottom: 1rem",
+    "max-height: 70vh",
+    "overflow: auto",
+    "padding: 1rem 1.25rem",
+    "border: 2px solid #d33",
+    "border-radius: 8px",
+    "background: #240b0b",
+    "color: #fff",
+    "font: 16px/1.4 monospace",
+    "box-shadow: 0 4px 24px #0008",
+  ].join(";");
+
+  const close = document.createElement("button");
+  close.type = "button";
+  close.textContent = "Close";
+  close.style.cssText = "float:right; padding:.35rem .6rem; cursor:pointer";
+  close.addEventListener("click", () => overlay.remove());
+
+  const title = document.createElement("strong");
+  title.textContent = "BULDR preview: something broke";
+
+  const hint = document.createElement("p");
+  hint.textContent = `(${type}) Check the DevTools console for the full mapped stack.`;
+
+  const text = document.createElement("p");
+  text.textContent = message;
+
+  overlay.append(close, title, hint, text);
+  if (stack) {
+    const details = document.createElement("details");
+    const summary = document.createElement("summary");
+    summary.textContent = "Raw stack";
+    const pre = document.createElement("pre");
+    pre.textContent = stack;
+    pre.style.cssText = "white-space:pre-wrap; overflow-wrap:anywhere";
+    details.append(summary, pre);
+    overlay.appendChild(details);
+  }
+
+  document.body?.appendChild(overlay);
+}
+
+function getMessage(reason) {
+  if (reason instanceof Error && reason.message) return reason.message;
+  if (typeof reason === "string" && reason) return reason;
+  try {
+    const text = JSON.stringify(reason);
+    return text || "Unknown error";
+  } catch {
+    return String(reason) || "Unknown error";
+  }
+}
+
+function getStack(reason) {
+  return reason && typeof reason.stack === "string" ? reason.stack : "";
+}

package/src/buldng-lib.js

@@ -0,0 +1,465 @@
+// tools/build-lib.js
+import fs from "node:fs";
+import path from "node:path";
+import esbuild from "esbuild";
+
+
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { WorkFile } from "./workfile.js";
+import { getDest, setSource, setDest, assertDestWrite, assertSourceRead, getInputs, looksLikeFilename, looksLikeHTML, 
+  looksLikeCSS, looksLikeJS, ensureLeadingSlash, ensureWorkFile } from "./buldng-validate.js";
+import { file, literal, wrap, append, replace, compile, materialise}
+ from "./buldng-ops.js";
+export { file, literal, wrap, append, replace, compile, materialise } 
+  from "./buldng-ops.js";
+export { assertSourceRead, assertDestWrite, setSource, setDest, looksLikeFilename, 
+         looksLikeHTML, looksLikeCSS, looksLikeJS, ensureWorkFile, ensureLeadingSlash } from "./buldng-validate.js";
+
+export default {
+  setSource,
+  setDest,
+  mkdir,
+  deepCopy,
+  file,
+  literal,
+  wrap,
+  append,
+  replace,
+  materialise,
+  compile,
+  csslink,
+  scriptlink,
+  pageHTML,
+  buldngHTMLWrapper,
+  reg,
+  printHeader,
+  typescriptCheck
+};
+
+const here = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(here, "../package.json"), "utf8"));
+const registry = new Map();
+
+export function reg(key, value) {
+  if (typeof key !== "string") {
+    throw new Error(`reg(): key must be a string`);
+  }
+  
+  const wf = ensureWorkFile(value, "reg");
+  
+  if (registry.has(key)) {
+    console.log(`reg(): overwriting existing key '${key}'`);
+  }
+  
+  registry.set(key, wf);
+  return wf;
+}
+
+function findTSC() {
+    const localTSC = path.resolve("node_modules/.bin/tsc");
+
+    if (fs.existsSync(localTSC)) {
+        return localTSC; // Local compiler — correct
+    }
+
+    try {
+        const globalTSC = execSync("which tsc").toString().trim();
+        return globalTSC; // Global compiler — acceptable
+    } catch {
+        return null; // No compiler found
+    }
+}
+
+export function typescriptCheck() {
+    let hasTS = false;
+    const require = createRequire(import.meta.url);
+
+    try {
+        // Detect ANY installed TypeScript (local or global)
+        require.resolve("typescript");
+
+        hasTS = true;
+    } catch {
+        hasTS = false;
+    }
+
+    if (!hasTS) {
+        console.log("TypeScript not found — skipping TS checks");
+        return;
+    }
+
+    const { execSync } = require("node:child_process");
+    const tscPath = findTSC();
+
+    if (!tscPath) {
+        console.error("TypeScript compiler not found (local or global)");
+        process.exit(1);
+    }
+
+    console.log("Using TypeScript compiler:", tscPath);
+
+
+    try {
+        // npx will run local tsc if present, otherwise global tsc
+        execSync(`${tscPath} --noEmit`, { stdio: "inherit" });
+    } catch (err) {
+        throw new Error("TypeScript check failed");
+    }
+}
+
+
+let headerPrinted = false;
+export function printHeader(importMeta) {
+  if (headerPrinted) return;
+  headerPrinted = true;
+  
+  const version = pkg.version;
+  const timestamp = new Date().toLocaleString("en-IE", { hour12: false });
+  
+  const callerFile = fileURLToPath(importMeta.url);
+  const callerDir = dirname(callerFile);
+  
+  console.log(`*local* buldng build system v${version} — ${timestamp}`);
+  console.log(`${callerDir}/${callerFile.split("/").pop()}`);
+}
+
+export function csslink(input) {
+  const pre  = `<link rel="stylesheet" href="`;
+  const post = `">`;
+  
+  // --------------------------------------------------
+  // Case 1: string
+  // --------------------------------------------------
+  if (typeof input === "string") {
+    if (!input.endsWith(".css")) {
+      throw new Error(`csslink(): expected a .css filename, got '${input}'`);
+    }
+    
+    return new WorkFile(
+      "literal",
+      { value: pre + ensureLeadingSlash(input) + post },
+      [],
+      "csslink"
+    );
+  }
+  
+  // --------------------------------------------------
+  // Case 2: WorkFile
+  // --------------------------------------------------
+  if (input instanceof WorkFile) {
+    return new WorkFile(
+      "wrap",
+      { pre, post },
+      [input],
+      "csslink"
+    );
+  }
+  
+  throw new Error(`csslink(): expected string or WorkFile, got ${typeof input}`);
+}
+
+export function scriptlink(input) {
+  const pre  = `<script type="module" src="/`;
+  const post = `"></script>`;
+  
+  // --------------------------------------------------
+  // Case 1: string
+  // --------------------------------------------------
+  if (typeof input === "string") {
+    if (!input.endsWith(".js")) {
+      throw new Error(`scriptlink(): expected a .js filename, got '${input}'`);
+    }
+    
+    return new WorkFile(
+      "literal",
+      { value: pre + input + post },
+      [],
+      "scriptlink"
+    );
+  }
+  
+  // --------------------------------------------------
+  // Case 2: WorkFile
+  // --------------------------------------------------
+  if (input instanceof WorkFile) {
+    return new WorkFile(
+      "wrap",
+      { pre, post },
+      [input],
+      "scriptlink"
+    );
+  }
+  
+  throw new Error(`scriptlink(): expected string or WorkFile, got ${typeof input}`);
+}
+
+
+// --------------------------------------------------
+// mkdir("puzzle")
+// --------------------------------------------------
+export function mkdir(relDir) {
+  const abs = assertDestWrite(relDir);
+  fs.mkdirSync(abs, { recursive: true });
+}
+
+// --------------------------------------------------
+// deepCopy — raw filesystem path
+// --------------------------------------------------
+export function deepCopy(from, to) {
+  let DEST = getDest();
+  
+  console.log(`deepCopy: ${from} → ${to}`);
+  
+  const absFrom = path.resolve(from);
+  
+  if (to.includes("..")) {
+    throw new Error("SECURITY: Illegal path traversal in deepCopy()");
+  }
+  
+  const absTo = to === "/" ? DEST : path.resolve(DEST, to);
+  
+  if (!absTo.startsWith(DEST)) {
+    throw new Error(`SECURITY: deepCopy target escapes dest:
+      dest: ${DEST}
+      target: ${absTo}`);
+    }
+    
+    if (!fs.existsSync(absFrom)) {
+      throw new Error(`deepCopy: source does not exist: ${absFrom}`);
+    }
+    
+    function copyRecursive(src, dst) {
+      const stat = fs.statSync(src);
+      
+      if (stat.isDirectory()) {
+        fs.mkdirSync(dst, { recursive: true });
+        const entries = fs.readdirSync(src);
+        for (const entry of entries) {
+          copyRecursive(path.join(src, entry), path.join(dst, entry));
+        }
+      } else {
+        fs.mkdirSync(path.dirname(dst), { recursive: true });
+        fs.copyFileSync(src, dst);
+      }
+    }
+    
+    copyRecursive(absFrom, absTo);
+  }
+  
+  export function header() {
+    printHeader(import.meta);
+  }
+  
+  
+  function packageFileAbs(filename) {
+    const __filename = fileURLToPath(import.meta.url);
+    const __dirname = dirname(__filename);
+    return join(__dirname, filename);
+  }
+  
+  // wraps whatever you provide in the overall buldng html wrapper.
+  // also compiles buldng's layout.ts and saves layout.js to the site root.
+  export function buldngHTMLWrapper(source) {
+    const srcWF = ensureWorkFile(source, "source");
+    
+    // 1. Compile buldng's layout.ts (lazy)
+    const layoutTS = new WorkFile("file", { absPath: packageFileAbs("layout.ts") }, []);
+    const layoutJS = compile(layoutTS);
+    
+    // 2. Save compiled layout.js to the site root (this triggers execution)
+    layoutJS.save("layout.js");
+    
+    // 2.5 Save camera.css to the site root (this triggers execution)
+    const buldngCSS = new WorkFile("file", { absPath: packageFileAbs("buldng.css") }, []);
+    buldngCSS.save("buldng.css");
+
+    const devErrors = new WorkFile("file", { absPath: packageFileAbs("buldng-dev-errors.js") }, []);
+    devErrors.save("buldng-dev-errors.js");
+    
+    // 3. Wrap project shell in buldng's wrapper.html
+    const wrapperWF = new WorkFile("file", { absPath: packageFileAbs("wrapper.html") }, []);
+    return replace(wrapperWF, "<!--CAMERA-STYLE-->", srcWF);
+  }
+  
+
+  
+  const _warned = {
+    shell: false,
+    projectCSS: false
+  };
+  
+  export function pageHTML({ app, css = null, js = null, out }) {
+    if (!out || typeof out !== "string") {
+      throw new Error("pageHTML(): 'out' must be a non-empty string");
+    }
+    
+    if (!app) {
+      throw new Error("pageHTML(): 'app' is required and cannot be null");
+    }
+    
+    const appWF = ensureWorkFile(app, "app");
+    
+    // Look up optional registered assets
+    const shellWF = registry.get("shell") ?? null;
+    const projectCSS = registry.get("projectCSS") ?? null;
+    
+    // One-time warnings
+    if (!shellWF && !_warned.shell) {
+      console.warn(
+        "pageHTML(): no 'shell' registered — building raw page HTML.\n" +
+        "To register a shell use: reg('shell', file`layout/shell.html`)"
+      );
+      _warned.shell = true;
+    }
+    
+    if (!projectCSS && !_warned.projectCSS) {
+      console.warn(
+        "pageHTML(): no 'projectCSS' registered — page will not include project CSS.\n" +
+        "To register project CSS use: reg('projectCSS', file`layout/buldng.css`)"
+      );
+      _warned.projectCSS = true;
+    }
+    
+    // --------------------------------------------------
+    // Build HTML WorkFile lazily
+    // --------------------------------------------------
+    
+    let htmlWF;
+    
+    if (shellWF) {
+      htmlWF = replace(shellWF, "<!--APP-->", appWF);
+    } else {
+      htmlWF = appWF;
+    }
+    
+    // Insert JS lazily
+    if (js) {
+      const jsWF = resolveAsset(js, {
+        ext: ".js",
+        tag: "scriptlink",
+        wrap: scriptlink,
+        autoPrefix: "js"
+      });
+      htmlWF = replace(htmlWF, "<!--SCRIPTS-->", jsWF);
+    }
+    
+    // Insert CSS lazily (project first)
+    const cssWFs = [];
+    
+    if (projectCSS) {
+      cssWFs.push(resolveAsset(projectCSS, {
+        ext: ".css",
+        tag: "csslink",
+        wrap: csslink,
+        autoPrefix: "css"
+      }));
+      console.log(`${out}: has projectCSS`);
+    }
+    
+    if (css) {
+      cssWFs.push(resolveAsset(css, {
+        ext: ".css",
+        tag: "csslink",
+        wrap: csslink,
+        autoPrefix: "css"
+      }));
+      console.log(`${out}: has pageCSS`);
+    }
+    
+    if (cssWFs.length === 0) {
+      // No CSS at all → do nothing
+      // (This is allowed)
+    } else if (cssWFs.length === 1) {
+      // One CSS → inject directly
+      htmlWF = replace(htmlWF, "<!--CSS-->", cssWFs[0]);
+    } else {
+      // Two CSS → append them
+      const cssListWF = append(...cssWFs);
+      htmlWF = replace(htmlWF, "<!--CSS-->", cssListWF);
+    }
+    
+    // The ONLY public collapse operator
+    return htmlWF.save(out);
+  }
+  
+  let autoCounter = 1;
+  
+function resolveAsset(input, {
+  ext,        // ".css" or ".js"
+  tag,        // "csslink" or "jslink"
+  wrap,       // csslink() or stylelink()
+  autoPrefix  // "css" or "js"
+}) {
+  if (input == null) return null;
+
+  // Case 1: string
+  if (typeof input === "string") {
+    if (!input.endsWith(ext)) {
+      throw new Error(`pageHTML(${ext}): expected a ${ext} filename, got '${input}'`);
+    }
+    return wrap(input);
+  }
+
+  // Case 2: must be WorkFile
+  if (!(input instanceof WorkFile)) {
+    throw new Error(`pageHTML(${ext}): expected string or WorkFile, got ${typeof input}`);
+  }
+
+  // Case 3: already a link
+  if (input.tag === tag) {
+    return input;
+  }
+
+  // Case 4: literal WorkFile
+  if (input.op === "literal") {
+    const value = input.config.value;
+
+    if (value.endsWith(ext)) {
+      return wrap(input);
+    }
+
+    throw new Error(
+      `pageHTML(${ext}): literal WorkFile does not end in ${ext} → '${value}'`
+    );
+  }
+
+  // Case 5a: materialise WorkFile
+  if (input.op === "materialise") {
+    const target = input.config.target;
+
+    if (!target.endsWith(ext)) {
+      throw new Error(
+        `pageHTML(${ext}): materialise target '${target}' does not end in ${ext}`
+      );
+    }
+
+    return wrap(input);
+  }
+
+  // Case 5b: blob → auto-materialise
+  const autoName = `${autoPrefix}${autoCounter++}${ext}`;
+
+  console.warn(
+    `pageHTML(${ext}): received non-literal WorkFile; auto-materialising as ${autoName}`
+  );
+
+  const mat = materialise(input, autoName);
+  return wrap(mat);
+}
+
+  
+  // --------------------------------------------------
+  // build-inputs.json manifest
+  // --------------------------------------------------
+  process.on("exit", () => {
+    if (process.env.BULDNG_HOT !== "1") return;
+    let DEST = getDest();
+    let INPUTS = getInputs();
+    const manifest = Array.from(INPUTS);
+    const out = path.join(DEST, "build-inputs.json");
+    fs.writeFileSync(out, JSON.stringify(manifest, null, 2));
+  });
+