@gershy/lilac 0.0.1

package/cmp/mjs/util/logger.d.ts

@@ -0,0 +1,20 @@
+type LoggerData = null | boolean | number | string | {
+    [limn]: (...args: any) => LoggerData;
+} | LoggerData[] | {
+    [k: string]: LoggerData;
+};
+export default class Logger {
+    static dummy: Logger;
+    private format;
+    private domain;
+    private ctx;
+    private write;
+    private opts;
+    constructor(domain: string, ctx?: Obj<any>, opts?: typeof this.opts, write?: typeof this.write);
+    getDomain(): string;
+    getTraceId(term: string): string;
+    log(data: LoggerData): void;
+    kid(domain: string): Logger;
+    scope<Fn extends (logger: Logger) => any>(domain: string, ctx: Obj<any>, fn: Fn): ReturnType<Fn>;
+}
+export {};

package/cmp/mjs/util/logger.js

@@ -0,0 +1,147 @@
+// TODO: @gershy/logger (or @gershy/watcher?)
+import { getClsName, inCls, isCls } from '@gershy/clearing';
+const scrubbed = (val, opts = {}) => {
+    const { isScrub = (k, _v) => k[0] === '!', doScrub = ((v) => `$scrub(${getClsName(v)})`), seen = new Map() } = opts ?? {};
+    if (val === null)
+        return val;
+    if (isCls(val, Boolean))
+        return val;
+    if (isCls(val, Number))
+        return val;
+    if (isCls(val, String))
+        return val;
+    if (seen.has(val))
+        return seen.get(val) ?? null;
+    if (isCls(val, Array)) {
+        const result = [];
+        seen.set(val, result);
+        for (const item of val)
+            result.push(scrubbed(item, { isScrub, doScrub, seen }));
+        return result;
+    }
+    else if (isCls(val, Object)) {
+        // Consider using hashes to display scrubbed values? (Makes them correlatable!)
+        const result = {};
+        seen.set(val, result);
+        for (const [k, v] of val)
+            result[k] = isScrub(k, v) ? doScrub(v) : scrubbed(v, { isScrub, doScrub, seen });
+        return result;
+    }
+    else if (inCls(val[limn], Function)) {
+        return scrubbed(val[limn](), { isScrub, doScrub, seen });
+    }
+    else {
+        // Consider processing for other types (sets, maps?)
+        return val;
+    }
+};
+export default class Logger {
+    static dummy = {
+        getTraceId() { return ''; },
+        log() { },
+        kid() { return Logger.dummy; },
+        scope(...args) { return args.at(-1)(Logger.dummy); }
+    };
+    format(v /* should not have cycles */, seen = new Map()) {
+        // Formats any value into json (so that it can be logged)
+        if (v == null)
+            return null;
+        if (isCls(v, Boolean))
+            return v;
+        if (isCls(v, Number))
+            return v;
+        if (isCls(v, String))
+            return v.length > this.opts.maxStrLen ? v.slice(0, this.opts.maxStrLen - 1) + '\u2026' : v;
+        if (seen.has(v))
+            return `<cyc> ${getClsName(v)}(...)`;
+        if (inCls(v[limn], Function)) {
+            const formatted = {};
+            seen.set(v, formatted);
+            Object.assign(formatted, this.format(v[limn](), seen));
+            return formatted;
+        }
+        if (isCls(v, Array)) {
+            const arr = [];
+            seen.set(v, arr);
+            for (const vv of v)
+                arr.push(this.format(vv, seen));
+            return arr;
+        }
+        if (isCls(v, Object)) {
+            const obj = {};
+            seen.set(v, obj);
+            for (const k in v)
+                obj[k] = this.format(v[k], seen);
+            return obj;
+        }
+        return `${getClsName(v)}(...)`;
+    }
+    ;
+    domain;
+    ctx;
+    write;
+    opts;
+    constructor(domain, ctx = {}, opts, write) {
+        this.domain = domain;
+        this.ctx = {
+            ...ctx,
+            $: this.domain,
+            [this.domain.split('.').at(-1)]: Math.random().toString(36).slice(2, 12)[padTail](10, '0'),
+        };
+        this.opts = opts ?? { maxStrLen: 250 };
+        // Note this default `this.write` function produces truncated values (sloppy outputting) in the
+        // cli, but works perfectly for lambdas with json-style logging configured!
+        this.write = write ?? ((val) => console.log(val));
+    }
+    getDomain() { return this.domain; }
+    getTraceId(term) {
+        const traceId = this.ctx[term];
+        if (!traceId)
+            throw Error('trace term invalid')[mod]({ term, ctx: this.ctx });
+        return traceId;
+    }
+    log(data) {
+        // Use-cases:
+        // 1. logger.log('a basic string')
+        //    - The logged payload is converted to `{ msg: 'a basic string' }`
+        // 2. logger.log({ msg: 'a basic string' })
+        //    - Logged as-is; equivalent to #1
+        // 3. logger.log({ $$: 'note', msg: 'a basic string' })
+        //    - Same as #1 and #2, but logger domain has "note" appended to it
+        // 4. logger.log({ $$: 'noteOnly' })
+        //    - Logged payload will be `{}`; only info is the tag - useful for infinitesimal moments in
+        //      the flamegraph!
+        // 5. logger.log({ $$: 'context.noteOnly' })
+        //    - Valid way to extend domain with more than 1 component at once!
+        let dmn = null;
+        if (data && isCls(data?.$$, String))
+            ({ $$: dmn, ...data } = data);
+        const domain = dmn ? [this.domain, dmn].join('.') : this.domain;
+        if (!isCls(data, Object))
+            data = { msg: data };
+        this.write({}[merge]({ $: this.ctx })[merge](scrubbed(this.format(data)))[merge]({ $: { $: domain } }));
+    }
+    kid(domain) {
+        const d = [this.domain, domain].filter(Boolean).join('.');
+        const logger = new Logger(d, this.ctx, this.opts, this.write);
+        return logger;
+    }
+    scope(domain, ctx, fn) {
+        const ms = Date.now();
+        const logger = this.kid(domain);
+        logger.log({ $$: 'launch', ...ctx });
+        const accept = val => { logger.log({ $$: 'accept', ms: Date.now() - ms }); return val; };
+        const glitch = err => { logger.log({ $$: err.log?.term ?? 'glitch', ms: Date.now() - ms, err }); throw err; }; // Always throws an error! Note allowing the consumer to override the logged term/domain offers a lot of flexibility!
+        let v;
+        try {
+            v = fn(logger);
+        }
+        catch (err) {
+            glitch(err);
+        }
+        return isCls(v, Promise)
+            ? v.then(accept, glitch)
+            : accept(v);
+    }
+}
+;

package/cmp/mjs/util/normalize.d.ts

@@ -0,0 +1,2 @@
+declare const normalize: (val: any, seen?: Set<any>) => any;
+export default normalize;

package/cmp/mjs/util/normalize.js

@@ -0,0 +1,23 @@
+import { isCls, getClsName } from '@gershy/clearing';
+const normalize = (val, seen = new Set()) => {
+    // Derives a json-stringifiable value from *any* value
+    // E.g. to hash *anything*: hash(JSON.stringify(normalized(anything)));
+    // Handles terminations
+    if (isCls(val, String))
+        return val;
+    if (isCls(val, Number))
+        return val;
+    if (val === null)
+        return null;
+    if (val === undefined)
+        return null;
+    if (seen.has(val))
+        return '<<!circ!>>';
+    seen.add(val);
+    if (isCls(val, Array))
+        return val[map](v => normalize(v, seen));
+    if (isCls(val, Object))
+        return normalize(Object.entries(val).sort((e0, e1) => e0[0] < e1[0] ? -1 : 1), seen);
+    return normalize({ $form: getClsName(val), ...val }, seen);
+};
+export default normalize;

package/cmp/mjs/util/procTerraform.d.ts

@@ -0,0 +1,8 @@
+import { rootFact } from '@gershy/disk';
+import { ProcOpts } from '@gershy/util-nodejs-proc';
+type Fact = typeof rootFact;
+declare const _default: (fact: Fact, cmd: string, opts?: ProcOpts) => Promise<{
+    logDb: import("@gershy/disk").Fact;
+    output: string;
+}>;
+export default _default;

package/cmp/mjs/util/procTerraform.js

@@ -0,0 +1,26 @@
+import proc from '@gershy/util-nodejs-proc';
+export default (fact, cmd, opts) => {
+    const numTailingTfLogLines = 20;
+    const writeLog = async (result) => {
+        const [yr, mo, dy, hr, mn, sc, ms] = new Date().toISOString().match(/([0-9]{4})[-]([0-9]{2})[-]([0-9]{2})[T]([0-9]{2})[:]([0-9]{2})[:]([0-9]{2})[.]([0-9]+)[Z]/).slice(1);
+        const term = `${cmd.split(' ')[1]}-${yr}${mo}${dy}-${hr}${mn}${sc}`;
+        const logDb = fact.kid(['.terraform.log', `${term}.txt`]);
+        await logDb.setData(result);
+        return logDb;
+    };
+    return proc(cmd, {
+        timeoutMs: 0,
+        ...opts,
+        cwd: fact,
+        env: { TF_DATA_DIR: '' }
+    }).then(async (result) => {
+        const logDb = await writeLog(result.output);
+        return { logDb, output: result.output.split('\n').slice(-numTailingTfLogLines).join('\n') };
+    }, async (err) => {
+        const logDb = await writeLog(err.output ?? err[limn]());
+        throw Error(`terraform failed (${err.message})`)[mod]({
+            logDb,
+            ...(err.output ? { output: err.output.split('\n').slice(-numTailingTfLogLines).join('\n') } : { cause: err })
+        });
+    });
+};

package/cmp/mjs/util/slashEscape.d.ts

@@ -0,0 +1,2 @@
+declare const _default: (str: string, escapeChars: string) => string;
+export default _default;

package/cmp/mjs/util/slashEscape.js

@@ -0,0 +1,8 @@
+export default (str, escapeChars) => {
+    if (!escapeChars[has]('\\'))
+        escapeChars += '\\';
+    // The regex to construct must have "\" and "]" escaped:
+    const escChars = escapeChars.replace(/([\\\]])/g, '\\$1');
+    const reg = new RegExp(`([${escChars}])`, 'g');
+    return str.replace(reg, '\\$1');
+};

package/cmp/mjs/util/snakeCase.d.ts

@@ -0,0 +1,2 @@
+declare const _default: (val: string) => Lowercase<string>;
+export default _default;

package/cmp/mjs/util/snakeCase.js

@@ -0,0 +1 @@
+export default (val) => val.replace(/([A-Z])/g, '_$1')[lower]();

package/cmp/mjs/util/terraform.d.ts

@@ -0,0 +1,2 @@
+export declare const embed: (v: string) => string;
+export declare const json: (v: Json) => string;

package/cmp/mjs/util/terraform.js

@@ -0,0 +1,6 @@
+export const embed = (v) => '${' + v + '}';
+export const json = (v) => [
+    '| <<EOF',
+    JSON.stringify(v, null, 2)[indent](2),
+    'EOF'
+].join('\n');

package/cmp/mjs/util/tryWithHealing.d.ts

@@ -0,0 +1,7 @@
+export type TryWithHealingArgs<T> = {
+    fn: () => Promise<T>;
+    canHeal: (err: any) => boolean;
+    heal: () => Promise<any>;
+};
+declare const _default: <T>(args: TryWithHealingArgs<T>) => Promise<T>;
+export default _default;

package/cmp/mjs/util/tryWithHealing.js

@@ -0,0 +1,9 @@
+export default async (args) => {
+    const { fn, heal, canHeal } = args;
+    return fn().catch(async (err) => {
+        if (!canHeal(err))
+            throw err;
+        await heal();
+        return fn();
+    });
+};

package/cmp/sideEffects.d.ts

@@ -0,0 +1,2 @@
+declare global {}
+export {};

package/license

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 Gershom Maes
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@gershy/lilac",
+  "version": "0.0.1",
+  "description": "Luscious infrastructure Living as Code - an opinionated approach to IAC",
+  "keywords": [
+    "lilac",
+    "luscious",
+    "iac",
+    "infrastructure"
+  ],
+  "author": "Gershom Maes",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gershy/lilac.git"
+  },
+  "bugs": {
+    "url": "https://github.com/gershy/lilac/issues"
+  },
+  "homepage": "https://github.com/gershy/lilac#readme",
+  "license": "ISC",
+  "peerDependencies": {
+    "@gershy/clearing": "^0.0.24"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.1",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
+  },
+  "type": "module",
+  "files": [
+    "cmp"
+  ],
+  "sideEffects": false,
+  "types": "./cmp/mjs/main.d.ts",
+  "exports": {
+    ".": {
+      "import": "./cmp/mjs/main.js",
+      "require": "./cmp/cjs/main.js"
+    }
+  },
+  "scripts": {
+    "test": "npm run ts.check && npx tsx ./src/main.test.ts",
+    "ts.check": "npx tsc --noEmit",
+    "build.cjs": "tsc -p build/tsconfig.cjs.json",
+    "build.mjs": "tsc -p build/tsconfig.mjs.json",
+    "build": "node ./build/act.js removeCmp && npm run build.cjs && npm run build.mjs && node ./build/act.js finalizeExportVariants",
+    "git.pub": "npm run test && git add --all && git commit -m \"automated\" && git push",
+    "npm.login": "npm login",
+    "npm.pub": "npm run test && npm run build && npm publish --access public"
+  },
+  "dependencies": {
+    "@gershy/disk": "^0.0.8",
+    "@gershy/util-nodejs-proc": "^0.0.1"
+  }
+}

package/readme.md

@@ -0,0 +1,39 @@
+# Lilac
+
+Lilac is "Luscious Infrastructure Living As Code". It's an opinionated take on typical infrastructure-as-code.
+
+Understanding Lilac involves multiple concepts:
+1. Flowers (logical services)
+    - Petals (individually provisioned infrastructure/microservices)
+    - Stems (iac providers, e.g. terraform)
+2. Pollen (inter-flower interfacing)
+3. Seeds (registry of all available Flowers)
+
+## 1. Flowers
+
+Flowers are logical infrastructural service. Some examples of Flowers are:
+1. An api gateway
+2. A compute cluster
+3. A lambda function
+4. A document-style database
+5. A relational-style database
+5. A blob storage database
+6. A queue
+
+The purpose of an infrastructural service is to provide some sort of systems behaviour. In implementing systems, we often have to think about additional, non-behavioural systems concerns - for example, access controls. A Lilac Resource represents only the distilled systems behaviour - when working with Lilac Resources, non-behavioural concerns are abstracted away.
+
+## 2. Lilac Comms (TODO: Rename "comms" -> "bees" / "pollinators" / "pollen"?)
+
+A Lilac Comm represents a dependency between some Lilac Resources. For example, a lambda function may query/insert documents into a document database. A Comm could be used to represent the lambda function's link to the document database.
+
+## 3. IAC Entities
+
+Lilac provides an opinion on how to represent systems, but it is unopinionated about how that representation is consumed and physically provisioned in the world. In provisioning a Lilac setup, the setup as a whole is converted into a number of IAC Entities - these IAC Entities are aware of a particular provisioning strategy, e.g. aws cloudformation or terraform. A set of IAC Entities is essentially the output of a Lilac setup; they allow a Lilac representation to become a real, functioning system.
+
+## 4. Lilac Registry
+
+The Lilac Registry exhaustively represents the set of Lilac Resource types available. For example, a particular systems primitive (e.g. Temporal) may not have a corresponding Lilac Resource. In such a case, if Temporal is desired, a new Lilac Resource would have to be written for it, and added to the Registry. The Registry also enables development-time testing - a fully mocked Registry can be substituted to the Lilac setup, and the result will be a true-to-production test environment (e.g. local testing).
+
+## 5. The Patio
+
+IAC deploys always involve the creation of infrastructure-describing code, which is abstracted away by Lilac and treated as ephemeral. But sometimes, deploys also involve the creation of files which are expected to be checked into version control. The "patio" is a file pointer that ought to be provided by the consumer, and points to some arbitrary directory in their control, which is checked into version control. Lilac will populate this directory, and pull from it appropriately (in order to reproduce deploys where ephemeral code is generated, and version-controlled code is still version-controlled). Note a good example of a version-controlled IAC file is terraform's .terraform.lock.hcl file!