@pajh/buldng 0.0.1 → 0.0.3

package/dist/buldng-lib.js

@@ -1,261 +1,408 @@
 // tools/build-lib.js
-
 import fs from "node:fs";
 import path from "node:path";
 import esbuild from "esbuild";
 
-// --------------------------------------------------
-// GLOBAL SOURCE & DEST ROOTS
-// --------------------------------------------------
-
-let SRC = null;
-let DEST = null;
-
-// --------------------------------------------------
-// SETTERS WITH SAFETY CHECKS
-// --------------------------------------------------
-
-export function setSource(dir) {
-  const abs = path.resolve(dir);
-  SRC = abs;
-  validateRoots();
-}
-
-export function setDest(dir) {
-  const abs = path.resolve(dir);
-  DEST = abs;
-  validateRoots();
-}
 
-const INPUTS = new Set();
-
-function trackInput(absPath) {
-  if (!SRC || !DEST) return;
-  if (absPath.startsWith(SRC) && !absPath.startsWith(DEST)) {
-    INPUTS.add(absPath);
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { readFileSync } from "node:fs";
+
+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
+};
+
+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`);
   }
-}
-
-function validateRoots() {
-  if (!SRC || !DEST) return;
-
-  // src cannot be inside dest, dest cannot be inside src
-  if (SRC.startsWith(DEST) || DEST.startsWith(SRC)) {
-    throw new Error(`SECURITY: src and dest cannot be nested:
-      src:  ${SRC}
-      dest: ${DEST}`);
+  
+  const wf = ensureWorkFile(value, "reg");
+  
+  if (registry.has(key)) {
+    console.log(`reg(): overwriting existing key '${key}'`);
   }
+  
+  registry.set(key, wf);
+  return wf;
 }
 
-// --------------------------------------------------
-// PATH SAFETY HELPERS
-// --------------------------------------------------
-
-function assertSourceRead(relPath) {
-  if (!SRC) throw new Error("SECURITY: Source root not set");
-  if (relPath.includes("..")) throw new Error("SECURITY: Illegal path traversal in read()");
-  const abs = path.resolve(SRC, relPath);
-  if (!abs.startsWith(SRC)) throw new Error("SECURITY: Read outside src/");
-  trackInput(abs);   // ← NEW
-  return abs;
+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()}`);
 }
 
-function assertDestWrite(relPath) {
-  if (!DEST) throw new Error("SECURITY: Dest root not set");
-  if (relPath.includes("..")) throw new Error("SECURITY: Illegal path traversal in save()");
-  const abs = path.resolve(DEST, relPath);
-  if (!abs.startsWith(DEST)) throw new Error("SECURITY: Write outside dest/");
-  return abs;
-}
-
-// --------------------------------------------------
-// File object — fluent API
-// --------------------------------------------------
-
-class File {
-  constructor(content) {
-    this.content = content;
-  }
-
-  // Fluent append: read another file from src and append its contents
-  append(relPath) {
-    const abs = assertSourceRead(relPath);
-    const extra = fs.readFileSync(abs, "utf8");
-    return new File(this.content + "\n" + extra);
+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"
+    );
   }
-
-  // Save relative to dest
-  save(relTarget) {
-    const out = assertDestWrite(relTarget);
-    fs.mkdirSync(path.dirname(out), { recursive: true });
-    fs.writeFileSync(out, this.content, "utf8");
-    console.log(`Saved: ${out}`);
-    return out;
+  
+  // --------------------------------------------------
+  // 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}`);
 }
 
-// --------------------------------------------------
-// read("file") → File
-// --------------------------------------------------
-
-export function read(relPath) {
-  const abs = assertSourceRead(relPath);
-  const content = fs.readFileSync(abs, "utf8");
-  return new File(content);
-}
-
-// --------------------------------------------------
-// append(["a.css","b.css"]) → File
-// --------------------------------------------------
-
-export function append(relPaths) {
-  const parts = relPaths.map(p => {
-    const abs = assertSourceRead(p);
-    return fs.readFileSync(abs, "utf8");
-  });
-  return new File(parts.join("\n"));
-}
-
-// --------------------------------------------------
-// stitch({ shell, app, css, js }) → File
-// --------------------------------------------------
-
-export function stitch({ shell, app, css = [], js = [] }) {
-  const shellAbs = assertSourceRead(shell);
-  const appAbs = assertSourceRead(app);
-
-  let html = fs.readFileSync(shellAbs, "utf8");
-  const appHtml = fs.readFileSync(appAbs, "utf8");
-
-  html = html.replace("<!--APP-->", appHtml);
-
-  const cssLinks = css
-    .map(c => `<link rel="stylesheet" href="/${c}">`)
-    .join("\n");
-  html = html.replace("<!--CSS-->", cssLinks);
-
-  const jsScripts = js
-    .map(j => `<script type="module" src="/${j}"></script>`)
-    .join("\n");
-  html = html.replace("<!--SCRIPTS-->", jsScripts);
-
-  return new File(html);
-}
-
-// --------------------------------------------------
-// compile("pages/puzzle.ts") → File
-// --------------------------------------------------
-
-export function compile(relTsPath) {
-  const abs = assertSourceRead(relTsPath);
-
-  const result = esbuild.buildSync({
-    entryPoints: [abs],
-    bundle: true,
-    minify: true,
-    sourcemap: true,
-    format: "esm",
-    target: "esnext",
-    write: false
-  });
-
-  if (result.errors.length > 0) {
-    throw new Error(
-      "Build failed:\n" +
-      result.errors.map(e => e.text).join("\n")
+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"
     );
   }
-
-  return new File(result.outputFiles[0].text);
+  
+  // --------------------------------------------------
+  // 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) {
-  if (!DEST) throw new Error("SECURITY: Dest root not set");
+  let DEST = getDest();
+  
   console.log(`deepCopy: ${from} → ${to}`);
-  // from is raw filesystem path, resolve it normally
+  
   const absFrom = path.resolve(from);
-
-  // to is relative to DEST
+  
   if (to.includes("..")) {
     throw new Error("SECURITY: Illegal path traversal in deepCopy()");
   }
-
+  
   const absTo = to === "/" ? DEST : path.resolve(DEST, to);
-
-  // Ensure target is inside DEST
+  
   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);
   }
-
-  // Ensure source exists
-  if (!fs.existsSync(absFrom)) {
-    throw new Error(`deepCopy: source does not exist: ${absFrom}`);
+  
+  export function header() {
+    printHeader(import.meta);
   }
-
-  // Recursively copy
-  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) {
-        const srcEntry = path.join(src, entry);
-        const dstEntry = path.join(dst, entry);
-        copyRecursive(srcEntry, dstEntry);
-      }
+  
+  
+  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");
+    
+    // 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 {
-      // File
-      fs.mkdirSync(path.dirname(dst), { recursive: true });
-      fs.copyFileSync(src, dst);
+      // 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);
   }
 
-  copyRecursive(absFrom, absTo);
-}
-
-// --------------------------------------------------
-// rm_dest("dir") — remove a file or directory inside DEST
-// --------------------------------------------------
+  // Case 2: must be WorkFile
+  if (!(input instanceof WorkFile)) {
+    throw new Error(`pageHTML(${ext}): expected string or WorkFile, got ${typeof input}`);
+  }
 
-export function rmDest(relPath) {
-  if (!DEST) throw new Error("SECURITY: Dest root not set");
-  if (relPath.includes("..")) {
-    throw new Error("SECURITY: Illegal path traversal in rmDest()");
+  // Case 3: already a link
+  if (input.tag === tag) {
+    return input;
   }
 
-  const abs = path.resolve(DEST, relPath);
+  // Case 4: literal WorkFile
+  if (input.op === "literal") {
+    const value = input.config.value;
 
-  if (!abs.startsWith(DEST)) {
-    throw new Error(`SECURITY: rmDest target escapes dest:
-      dest: ${DEST}
-      target: ${abs}`);
+    if (value.endsWith(ext)) {
+      return wrap(input);
+    }
+
+    throw new Error(
+      `pageHTML(${ext}): literal WorkFile does not end in ${ext} → '${value}'`
+    );
   }
 
-  if (!fs.existsSync(abs)) {
-    console.log(`rmDest: nothing to remove: ${abs}`);
-    return;
+  // 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);
   }
 
-  fs.rmSync(abs, { recursive: true, force: true });
-  console.log(`rmDest: removed ${abs}`);
-}
+  // Case 5b: blob → auto-materialise
+  const autoName = `${autoPrefix}${autoCounter++}${ext}`;
 
+  console.warn(
+    `pageHTML(${ext}): received non-literal WorkFile; auto-materialising as ${autoName}`
+  );
 
-process.on("exit", () => {
-  if (!DEST) return;
-  const manifest = Array.from(INPUTS);
-  const out = path.join(DEST, "build-inputs.json");
-  fs.writeFileSync(out, JSON.stringify(manifest, null, 2));
-});
+  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));
+  });
+