@pajh/buldng 0.0.2 → 0.0.3

package/dist/buldng-lib.js

@@ -3,32 +3,146 @@ 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 { WorkFile } from "./workfile.js";
-import { getDest, assertDestWrite, assertSourceRead, getInputs } from "./buldng-validate.js";
-export { assertSourceRead, assertDestWrite, setSource, setDest } from "./buldng-validate.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`);
+  }
+  
+  const wf = ensureWorkFile(value, "reg");
+  
+  if (registry.has(key)) {
+    console.log(`reg(): overwriting existing key '${key}'`);
+  }
+  
+  registry.set(key, wf);
+  return wf;
+}
 
 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(`Xx buldng build system v${version} — ${timestamp}`);
+  
+  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")
 // --------------------------------------------------
@@ -42,153 +156,253 @@ export function mkdir(relDir) {
 // --------------------------------------------------
 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);
   }
-
-  if (!fs.existsSync(absFrom)) {
-    throw new Error(`deepCopy: source does not exist: ${absFrom}`);
+  
+  export function header() {
+    printHeader(import.meta);
   }
-
-  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));
-      }
+  
+  
+  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 {
-      fs.mkdirSync(path.dirname(dst), { recursive: true });
-      fs.copyFileSync(src, dst);
+      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);
   }
-
-  copyRecursive(absFrom, absTo);
-}
-
-export function header() {
-  printHeader(import.meta);
-}
-
-// --------------------------------------------------
-// file`path.ext` — tagged template literal
-// --------------------------------------------------
-export function file(strings, ...values) {
-  if (values.length > 0) {
-    throw new Error("file`` does not support interpolation");
+  
+  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);
   }
 
-  const relPath = strings.join("");
-  const absPath = assertSourceRead(relPath);
-
-  return new WorkFile("file", { relPath, absPath }, []);
-}
-
-// --------------------------------------------------
-// literal(text)
-// --------------------------------------------------
-export function literal(value) {
-  return new WorkFile("literal", { value }, []);
-}
-
-// --------------------------------------------------
-// ensureWorkFile(x)
-// --------------------------------------------------
-function ensureWorkFile(x, fieldName = "value") {
-  if (x instanceof WorkFile) return x;
-
-  if (typeof x === "string") {
-    return literal(x);
+  // Case 2: must be WorkFile
+  if (!(input instanceof WorkFile)) {
+    throw new Error(`pageHTML(${ext}): expected string or WorkFile, got ${typeof input}`);
   }
 
-  throw new Error(`${fieldName} must be WorkFile or string`);
-}
-
-// --------------------------------------------------
-// csslink(filename)
-// --------------------------------------------------
-export function csslink(filename) {
-  return new WorkFile(
-    "literal",
-    { value: `<link rel="stylesheet" href="/${filename}">` },
-    []
-  );
-}
+  // Case 3: already a link
+  if (input.tag === tag) {
+    return input;
+  }
 
-// --------------------------------------------------
-// scriptlink(filename)
-// --------------------------------------------------
-export function scriptlink(filename) {
-  return new WorkFile(
-    "literal",
-    { value: `<script type="module" src="/${filename}"></script>` },
-    []
-  );
-}
+  // Case 4: literal WorkFile
+  if (input.op === "literal") {
+    const value = input.config.value;
 
-// --------------------------------------------------
-// append(...items)
-// --------------------------------------------------
-export function append(...items) {
-  const children = items.map(item => {
-    if (item instanceof WorkFile) return item;
-    if (typeof item === "string") return literal(item);
-    throw new Error("append(): each item must be WorkFile or string");
-  });
+    if (value.endsWith(ext)) {
+      return wrap(input);
+    }
 
-  if (children.length < 2) {
-    throw new Error("append(): requires at least 2 items");
+    throw new Error(
+      `pageHTML(${ext}): literal WorkFile does not end in ${ext} → '${value}'`
+    );
   }
 
-  return new WorkFile("append", {}, children);
-}
+  // Case 5a: materialise WorkFile
+  if (input.op === "materialise") {
+    const target = input.config.target;
 
-// --------------------------------------------------
-// replace(source, tag, replacement)
-// --------------------------------------------------
-export function replace(source, tag, replacement) {
-  const srcWF = ensureWorkFile(source, "source");
-  const tagWF = ensureWorkFile(tag, "tag");
-  const repWF = ensureWorkFile(replacement, "replacement");
+    if (!target.endsWith(ext)) {
+      throw new Error(
+        `pageHTML(${ext}): materialise target '${target}' does not end in ${ext}`
+      );
+    }
 
-  if (tagWF.op === "literal" && tagWF.config.value.trim() === "") {
-    throw new Error(`replace(): tag cannot be blank`);
+    return wrap(input);
   }
 
-  return new WorkFile("replace", {}, [srcWF, tagWF, repWF]);
-}
+  // Case 5b: blob → auto-materialise
+  const autoName = `${autoPrefix}${autoCounter++}${ext}`;
 
-// --------------------------------------------------
-// compile(source)
-// --------------------------------------------------
-export function compile(source, flags = {}) {
-  const srcWF = ensureWorkFile(source, "source");
-  return new WorkFile("compile", { flags }, [srcWF]);
+  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));
-});
+  
+  // --------------------------------------------------
+  // 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));
+  });
+