@pajh/buldng 0.0.3 → 0.0.5

package/package.json

@@ -1,19 +1,28 @@
 {
   "name": "@pajh/buldng",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "type": "module",
-  "main": "dist/buldng-lib.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",
+    "./error": "./src/layout-err.ts",
+    "./MIME.json": "./src/MIME.json"
+  },
+  "bin": {
+    "buldng-serve": "./src/serve.js"
+  }
 }

package/src/MIME.json

@@ -0,0 +1,11 @@
+{
+  ".html": "text/html",
+  ".css": "text/css",
+  ".js": "application/javascript",
+  ".json": "application/json",
+  ".svg": "image/svg+xml",
+  ".png": "image/png",
+  ".woff2": "font/woff2",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg"
+}

package/src/buldng-async.js

@@ -0,0 +1,20 @@
+// Experimental async building functions
+
+export function task(fn) {
+    return new Promise((resolve, reject) => {
+      try {
+        fn();
+        resolve();
+      } catch (err) {
+        reject(err);
+      }
+    });
+  }
+
+ export function parallel(...jobs) {
+    return Promise.all(jobs);
+  }
+
+ export function finalise(fn) {
+    return fn();
+  }

package/src/buldng-files.js

@@ -0,0 +1,58 @@
+// buldng-files.js
+// file handling functions for buldng
+import { getDest, setSource, setDest, assertDestWrite, assertSourceRead, getInputs, looksLikeFilename, looksLikeHTML,
+         looksLikeCSS, looksLikeJS } from "./buldng-validate.js";
+import fs from "node:fs";
+import path from "node:path";
+
+// --------------------------------------------------
+// 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);
+  }

package/src/buldng-html.js

@@ -0,0 +1,262 @@
+// buldng-html.js — HTML assembly subsystem
+
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { readFileSync } from "node:fs";
+import { WorkFile } from "./workfile.js";
+import {
+  ensureWorkFile,
+  ensureLeadingSlash
+} from "./buldng-validate.js";
+import {
+  replace,
+  append,
+  materialise,
+  compile
+} from "./buldng-ops.js";
+
+// --------------------------------------------------
+// Registry for shell + projectCSS
+// --------------------------------------------------
+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 makeLinkOp({ name, ext, pre, post }) {
+  return function linkOp(input) {
+
+    // Case 1: string
+    if (typeof input === "string") {
+      if (!input.endsWith(ext)) {
+        throw new Error(`${name}(): expected a ${ext} filename or WorkFile`);
+      }
+
+      const fixed = ensureLeadingSlash(input);
+
+      return new WorkFile(
+        "literal",
+        { value: pre + fixed + post },
+        [],
+        name
+      );
+    }
+
+    // Case 2: WorkFile
+    if (input instanceof WorkFile) {
+      return new WorkFile(
+        "wrap",
+        { pre, post },
+        [input],
+        name
+      );
+    }
+
+    throw new Error(`${name}(): expected a ${ext} filename or WorkFile`);
+  };
+}
+
+export const csslink = makeLinkOp({
+  name: "csslink",
+  ext: ".css",
+  pre: `<link rel="stylesheet" href="`,
+  post: `">`
+});
+
+export const scriptlink = makeLinkOp({
+  name: "scriptlink",
+  ext: ".js",
+  pre: `<script type="module" src="`,
+  post: `"></script>`
+});
+
+// --------------------------------------------------
+// Helper: absolute path to package files
+// --------------------------------------------------
+function packageFileAbs(filename) {
+  const __filename = fileURLToPath(import.meta.url);
+  const __dirname = dirname(__filename);
+  return join(__dirname, filename);
+}
+
+// --------------------------------------------------
+// buldngHTMLWrapper()
+// --------------------------------------------------
+export function buldngHTMLWrapper(source) {
+  const srcWF = ensureWorkFile(source, "source");
+
+  // Compile buldng's layout.ts (lazy)
+  const layoutTS = new WorkFile("file", { absPath: packageFileAbs("layout.ts") }, []);
+  const layoutJS = compile(layoutTS);
+
+  // Save compiled layout.js to site root
+  layoutJS.save("layout.js");
+
+  // Save buldng.css to site root
+  const buldngCSS = new WorkFile("file", { absPath: packageFileAbs("buldng.css") }, []);
+  buldngCSS.save("buldng.css");
+
+  // Wrap project shell in wrapper.html
+  const wrapperWF = new WorkFile("file", { absPath: packageFileAbs("wrapper.html") }, []);
+  return replace(wrapperWF, "<!--CAMERA-STYLE-->", srcWF);
+}
+
+// --------------------------------------------------
+// pageHTML()
+// --------------------------------------------------
+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");
+
+  const shellWF = registry.get("shell") ?? null;
+  const projectCSS = registry.get("projectCSS") ?? null;
+
+  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/buldr.css`)"
+    );
+    _warned.projectCSS = true;
+  }
+
+  let htmlWF = shellWF
+    ? replace(shellWF, "<!--APP-->", appWF)
+    : appWF;
+
+  // Insert JS
+  if (js) {
+    const jsWF = resolveAsset(js, {
+      ext: ".js",
+      tag: "scriptlink",
+      wrap: scriptlink,
+      autoPrefix: "js"
+    });
+    htmlWF = replace(htmlWF, "<!--SCRIPTS-->", jsWF);
+  }
+
+  // Insert CSS (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 === 1) {
+    htmlWF = replace(htmlWF, "<!--CSS-->", cssWFs[0]);
+  } else if (cssWFs.length > 1) {
+    const cssListWF = append(...cssWFs);
+    htmlWF = replace(htmlWF, "<!--CSS-->", cssListWF);
+  }
+
+  return htmlWF.save(out);
+}
+
+// --------------------------------------------------
+// resolveAsset()
+// --------------------------------------------------
+let autoCounter = 1;
+
+function resolveAsset(input, {
+  ext,
+  tag,
+  wrap,
+  autoPrefix
+}) {
+  if (input == null) return null;
+
+  if (typeof input === "string") {
+    if (!input.endsWith(ext)) {
+      throw new Error(`pageHTML(${ext}): expected a ${ext} filename, got '${input}'`);
+    }
+    return wrap(input);
+  }
+
+  if (!(input instanceof WorkFile)) {
+    throw new Error(`pageHTML(${ext}): expected string or WorkFile, got ${typeof input}`);
+  }
+
+  if (input.tag === tag) {
+    return input;
+  }
+
+  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}'`
+    );
+  }
+
+  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);
+  }
+
+  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);
+}

package/src/buldng-lib.js

@@ -0,0 +1,90 @@
+// buldng-lib.js — the main buldng build library
+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";
+import { task, parallel, finalise } from "./buldng-async.js";
+import { typescriptCheck } from "./buldng-typescript.js";
+import { mkdir, deepCopy } from "./buldng-files.js";
+import {
+  reg,
+  csslink,
+  scriptlink,
+  pageHTML,
+  buldngHTMLWrapper
+} from "./buldng-html.js";
+
+export default {
+  setSource,
+  setDest,
+  mkdir,
+  deepCopy,
+  task,
+  parallel,
+  finalise,
+  file,
+  literal,
+  wrap,
+  append,
+  replace,
+  compile,
+  materialise,
+  task,
+  parallel,
+  finalise,
+  csslink,
+  scriptlink,
+  pageHTML,
+  buldngHTMLWrapper,
+  reg,
+  printHeader,
+  typescriptCheck
+};
+
+const here = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(here, "../package.json"), "utf8"));
+
+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 header() {
+  printHeader(import.meta);
+}
+
+// --------------------------------------------------
+// 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));
+});