@pajh/buldng 0.0.1 → 0.0.2

package/dist/buldng-lib.js

@@ -1,209 +1,68 @@
 // 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
-// --------------------------------------------------
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { readFileSync } from "node:fs";
 
-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 { WorkFile } from "./workfile.js";
+import { getDest, assertDestWrite, assertSourceRead, getInputs } from "./buldng-validate.js";
+export { assertSourceRead, assertDestWrite, setSource, setDest } from "./buldng-validate.js";
 
-function validateRoots() {
-  if (!SRC || !DEST) return;
+const here = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(here, "../package.json"), "utf8"));
 
-  // 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}`);
-  }
-}
+let headerPrinted = false;
+export function printHeader(importMeta) {
+  if (headerPrinted) return;
+  headerPrinted = true;
 
-// --------------------------------------------------
-// PATH SAFETY HELPERS
-// --------------------------------------------------
+  const version = pkg.version;
+  const timestamp = new Date().toLocaleString("en-IE", { hour12: false });
 
-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;
-}
+  const callerFile = fileURLToPath(importMeta.url);
+  const callerDir = dirname(callerFile);
 
-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);
-  }
-
-  // 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;
-  }
-}
-
-// --------------------------------------------------
-// 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")
-    );
-  }
-
-  return new File(result.outputFiles[0].text);
+  console.log(`Xx buldng build system v${version} — ${timestamp}`);
+  console.log(`${callerDir}/${callerFile.split("/").pop()}`);
 }
 
 // --------------------------------------------------
 // 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}`);
   }
 
-  // Ensure source exists
   if (!fs.existsSync(absFrom)) {
     throw new Error(`deepCopy: source does not exist: ${absFrom}`);
   }
 
-  // Recursively copy
   function copyRecursive(src, dst) {
     const stat = fs.statSync(src);
 
@@ -211,12 +70,9 @@ export function deepCopy(from, to) {
       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);
+        copyRecursive(path.join(src, entry), path.join(dst, entry));
       }
     } else {
-      // File
       fs.mkdirSync(path.dirname(dst), { recursive: true });
       fs.copyFileSync(src, dst);
     }
@@ -225,36 +81,113 @@ export function deepCopy(from, to) {
   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");
+  }
+
+  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 }, []);
+}
+
 // --------------------------------------------------
-// rm_dest("dir") — remove a file or directory inside DEST
+// ensureWorkFile(x)
 // --------------------------------------------------
+function ensureWorkFile(x, fieldName = "value") {
+  if (x instanceof WorkFile) return x;
 
-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()");
+  if (typeof x === "string") {
+    return literal(x);
   }
 
-  const abs = path.resolve(DEST, relPath);
+  throw new Error(`${fieldName} must be WorkFile or string`);
+}
 
-  if (!abs.startsWith(DEST)) {
-    throw new Error(`SECURITY: rmDest target escapes dest:
-      dest: ${DEST}
-      target: ${abs}`);
+// --------------------------------------------------
+// csslink(filename)
+// --------------------------------------------------
+export function csslink(filename) {
+  return new WorkFile(
+    "literal",
+    { value: `<link rel="stylesheet" href="/${filename}">` },
+    []
+  );
+}
+
+// --------------------------------------------------
+// scriptlink(filename)
+// --------------------------------------------------
+export function scriptlink(filename) {
+  return new WorkFile(
+    "literal",
+    { value: `<script type="module" src="/${filename}"></script>` },
+    []
+  );
+}
+
+// --------------------------------------------------
+// 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 (children.length < 2) {
+    throw new Error("append(): requires at least 2 items");
   }
 
-  if (!fs.existsSync(abs)) {
-    console.log(`rmDest: nothing to remove: ${abs}`);
-    return;
+  return new WorkFile("append", {}, children);
+}
+
+// --------------------------------------------------
+// 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 (tagWF.op === "literal" && tagWF.config.value.trim() === "") {
+    throw new Error(`replace(): tag cannot be blank`);
   }
 
-  fs.rmSync(abs, { recursive: true, force: true });
-  console.log(`rmDest: removed ${abs}`);
+  return new WorkFile("replace", {}, [srcWF, tagWF, repWF]);
 }
 
+// --------------------------------------------------
+// compile(source)
+// --------------------------------------------------
+export function compile(source, flags = {}) {
+  const srcWF = ensureWorkFile(source, "source");
+  return new WorkFile("compile", { flags }, [srcWF]);
+}
 
+// --------------------------------------------------
+// build-inputs.json manifest
+// --------------------------------------------------
 process.on("exit", () => {
-  if (!DEST) return;
+  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));

package/dist/buldng-validate.js

@@ -0,0 +1,102 @@
+import fs from "node:fs";
+import path from "node:path";
+
+// --------------------------------------------------
+// GLOBAL SOURCE & DEST ROOTS
+// --------------------------------------------------
+
+let SRC = null;
+let DEST = null;
+
+// --------------------------------------------------
+// SETTERS WITH SAFETY CHECKS
+// --------------------------------------------------
+
+export function setSource(dir) {
+  const abs = path.resolve(dir);
+  const sentinel = path.join(abs, "BULDNG_SRC");
+  if (!fs.existsSync(sentinel)) {
+    throw new Error(`SECURITY: Source directory "${abs}" does not contain BLDNG_SRC sentinel`);
+  }
+  SRC = abs;
+  validateRoots();
+}
+
+export function setDest(dir) {
+  const abs = path.resolve(dir);
+
+  if (fs.existsSync(abs)) {
+    const sentinel = path.join(abs, "BULDNG_SRC");
+    if (fs.existsSync(sentinel)) {
+      throw new Error(`SECURITY: Dest directory "${abs}" contains BLDNG_SRC sentinel`);
+    }
+
+    const entries = fs.readdirSync(abs, { withFileTypes: true });
+    for (const entry of entries) {
+      fs.rmSync(path.join(abs, entry.name), { recursive: true, force: true });
+    }
+  } else {
+    fs.mkdirSync(abs, { recursive: true });
+  }
+
+  DEST = abs;
+  validateRoots();
+}
+
+export function getDest() {
+  if (!DEST) throw new Error("SECURITY: Dest root not set");
+  return DEST;
+}
+
+// --------------------------------------------------
+// PATH SAFETY HELPERS
+// --------------------------------------------------
+
+export 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);
+  return abs;
+}
+
+export 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;
+}
+
+function validateRoots() {
+  if (!SRC || !DEST) return;
+
+  const srcReal = fs.realpathSync(SRC);
+  const destReal = fs.realpathSync(DEST);
+
+  if (srcReal === destReal) {
+    throw new Error(`SECURITY: src and dest resolve to the same directory:
+      src:  ${SRC}
+      dest: ${DEST}`);
+  }
+
+  if (srcReal.startsWith(destReal) || destReal.startsWith(srcReal)) {
+    throw new Error(`SECURITY: src and dest cannot be nested:
+      src:  ${SRC}
+      dest: ${DEST}`);
+  }
+}
+
+const INPUTS = new Set();
+
+export function getInputs() {
+  return INPUTS;
+}
+
+export function trackInput(absPath) {
+  if (!SRC || !DEST) return;
+  if (absPath.startsWith(SRC) && !absPath.startsWith(DEST)) {
+    INPUTS.add(absPath);
+  }
+}

package/dist/init.js

@@ -0,0 +1,2 @@
+export * from "./buldng-lib.js";
+

package/dist/workfile.js

@@ -0,0 +1,162 @@
+// --------------------------------------------------
+// WorkFile — immutable, lazy, tree-structured build node
+// --------------------------------------------------
+
+import fs from "node:fs";
+import path from "node:path";
+import esbuild from "esbuild";
+import { assertDestWrite } from "./buldng-lib.js";
+
+export class WorkFile {
+  constructor(op, config = {}, children = []) {
+    this.op = op;               // "file", "literal", "append", "replace", "compile"
+    this.config = Object.freeze(config);
+    this.children = Object.freeze(children);
+
+    Object.freeze(this);        // full immutability
+  }
+
+  // --------------------------------------------------
+  // execute(): recursively produce output string
+  // --------------------------------------------------
+  execute() {
+    switch (this.op) {
+
+      // ----------------------------------------------
+      // FILE — lazy read from disk
+      // ----------------------------------------------
+      case "file": {
+        const abs = this.config.absPath;
+        return fs.readFileSync(abs, "utf8");
+      }
+
+      // ----------------------------------------------
+      // LITERAL — inline text
+      // ----------------------------------------------
+      case "literal": {
+        return this.config.value;
+      }
+
+      // ----------------------------------------------
+      // APPEND — concat children in order
+      // ----------------------------------------------
+      case "append": {
+        let out = "";
+
+        for (const child of this.children) {
+          const chunk = child.execute();
+
+          if (out.length > 0 &&
+              !out.endsWith("\n") &&
+              !chunk.startsWith("\n")) {
+            out += "\n";
+          }
+
+          out += chunk;
+        }
+
+        return out;
+      }
+
+      // ----------------------------------------------
+      // REPLACE — replace tag with replacement
+      // ----------------------------------------------
+      case "replace": {
+        if (this.children.length !== 3) {
+          throw new Error(`replace(): expected 3 children, got ${this.children.length}`);
+        }
+
+        const [srcWF, tagWF, repWF] = this.children;
+
+        const src = srcWF.execute();
+        const tag = tagWF.execute();
+        const rep = repWF.execute();
+
+        if (!src.includes(tag)) {
+          throw new Error(`replace(): tag "${tag}" not found in source`);
+        }
+
+        return src.replace(tag, rep);
+      }
+
+      // ----------------------------------------------
+      // COMPILE — esbuild wrapper
+      // ----------------------------------------------
+      case "compile": {
+        if (this.children.length !== 1) {
+          throw new Error(`compile(): expected 1 child, got ${this.children.length}`);
+        }
+
+        const child = this.children[0];
+
+        // If child is a file WorkFile, use its absolute path directly
+        if (child.op === "file" && child.config.absPath) {
+          const entry = child.config.absPath;
+
+          const result = esbuild.buildSync({
+            entryPoints: [entry],
+            bundle: true,
+            minify: true,
+            sourcemap: true,
+            format: "esm",
+            target: "esnext",
+            write: false
+          });
+
+          if (result.errors?.length) {
+            throw new Error("Build failed:\n" + result.errors.map(e => e.text).join("\n"));
+          }
+
+          return result.outputFiles[0].text;
+        }
+
+        // Otherwise compile from stdin
+        const srcText = child.execute();
+
+        const result = esbuild.buildSync({
+          stdin: {
+            contents: srcText,
+            resolveDir: process.cwd(),
+            sourcefile: "input.ts"
+          },
+          bundle: true,
+          minify: true,
+          sourcemap: true,
+          format: "esm",
+          target: "esnext",
+          write: false
+        });
+
+        if (result.errors?.length) {
+          throw new Error("Build failed:\n" + result.errors.map(e => e.text).join("\n"));
+        }
+
+        return result.outputFiles[0].text;
+      }
+
+      // ----------------------------------------------
+      // Unknown op
+      // ----------------------------------------------
+      default:
+        throw new Error(`WorkFile.execute(): unknown op "${this.op}"`);
+    }
+  }
+
+  // --------------------------------------------------
+  // save(): write output to disk
+  // --------------------------------------------------
+  save(target) {
+    if (!target) {
+      throw new Error("WorkFile.save(): target filename required");
+    }
+
+    const abs = assertDestWrite(target);
+    const out = this.execute();
+
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    fs.writeFileSync(abs, out, "utf8");
+
+    console.log(`Saved: ${abs}`);
+    return abs;
+  }
+}

package/package.json

@@ -1,10 +1,19 @@
 {
   "name": "@pajh/buldng",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "type": "module",
-  "main": "dist/buldng-lib.js",
+  "main": "dist/init.js",
   "files": ["dist"],
   "scripts": {
-    "build": "cp src/buldng-lib.js dist/buldng-lib.js"
-  }
+    "build": "node build.js"
+  },
+  "dependencies": {
+   "esbuild": "^0.28.1",
+   "typescript": "^7.0.2"
+  },
+  "devDependencies": {
+   "stylelint": "^17.14.1",
+   "stylelint-config-standard": "^40.0.0"
+}
+
 }