@heychunky/core 0.1.0

package/dist/secrets/store.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Where secrets come from.
+ *
+ * The Core never knows which store it has. A machine identity on an operator's
+ * laptop, one in a deployed worker — same interface, and no service client is
+ * aware of the difference.
+ *
+ * A store owns its own reference format: `infisicalStore` speaks
+ * `infisical://project/environment/folder/KEY` and both recognises and parses
+ * it itself. Nothing here interprets a reference, which is what lets a second
+ * store exist without teaching this module its scheme — and what keeps
+ * `postgres://user:pw@host/db` a literal rather than a reference that happens
+ * to have a scheme.
+ */
+export interface SecretStore {
+    /** Whether this store recognises `ref` as one of its references. */
+    owns(ref: string): boolean;
+    /** Resolve one reference to its value. Throws if it does not exist. */
+    get(ref: string): Promise<string>;
+    /**
+     * Every key directly under a reference naming a container rather than a
+     * value — for Infisical, a folder. Nothing recurses: a sync pushes one
+     * app's environment, and a nested folder is a different app's.
+     */
+    list(prefix: string): Promise<Record<string, string>>;
+    /**
+     * Write one value, creating whatever has to exist to hold it.
+     *
+     * Writing is idempotent because a caller cannot usefully know whether a
+     * reference is already there — checking first and then writing is two
+     * requests and a race, and the answer is the same either way.
+     */
+    set(ref: string, value: string): Promise<void>;
+}
+/** A store backed by a plain map. For tests, and for values already in hand. */
+export declare function memoryStore(values: Record<string, string>): SecretStore;
+/**
+ * Resolve a map of env var → reference-or-literal into env var → value.
+ *
+ * Literals pass through untouched, because a refs file legitimately mixes
+ * them: `RESEND_FROM` is not a secret, `RESEND_KEY` is. The store decides
+ * which is which.
+ *
+ * **An empty value is an error, not an empty string.** A key that exists but
+ * holds nothing resolves to `""` and the process starts with a broken
+ * credential, failing later and far from the cause. Failing here puts the
+ * error where it belongs.
+ */
+export declare function resolveEnv(refs: Record<string, string>, store: SecretStore): Promise<Record<string, string>>;
+//# sourceMappingURL=store.d.ts.map

package/dist/secrets/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/secrets/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,MAAM,WAAW,WAAW;IAC1B,oEAAoE;IACpE,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAC3B,uEAAuE;IACvE,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAClC;;;;OAIG;IACH,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACtD;;;;;;OAMG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAChD;AAED,gFAAgF;AAChF,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,WAAW,CAuBvE;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,UAAU,CAC9B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC5B,KAAK,EAAE,WAAW,GACjB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAiBjC"}

package/dist/secrets/store.js

@@ -0,0 +1,71 @@
+/**
+ * Where secrets come from.
+ *
+ * The Core never knows which store it has. A machine identity on an operator's
+ * laptop, one in a deployed worker — same interface, and no service client is
+ * aware of the difference.
+ *
+ * A store owns its own reference format: `infisicalStore` speaks
+ * `infisical://project/environment/folder/KEY` and both recognises and parses
+ * it itself. Nothing here interprets a reference, which is what lets a second
+ * store exist without teaching this module its scheme — and what keeps
+ * `postgres://user:pw@host/db` a literal rather than a reference that happens
+ * to have a scheme.
+ */
+/** A store backed by a plain map. For tests, and for values already in hand. */
+export function memoryStore(values) {
+    return {
+        owns(ref) {
+            return Object.hasOwn(values, ref);
+        },
+        async get(ref) {
+            const v = values[ref];
+            if (v === undefined)
+                throw new Error(`No value for reference: ${ref}`);
+            return v;
+        },
+        async list(prefix) {
+            const out = {};
+            for (const [ref, value] of Object.entries(values)) {
+                if (!ref.startsWith(prefix))
+                    continue;
+                const key = ref.slice(prefix.length);
+                if (key && !key.includes("/"))
+                    out[key] = value;
+            }
+            return out;
+        },
+        async set(ref, value) {
+            values[ref] = value;
+        },
+    };
+}
+/**
+ * Resolve a map of env var → reference-or-literal into env var → value.
+ *
+ * Literals pass through untouched, because a refs file legitimately mixes
+ * them: `RESEND_FROM` is not a secret, `RESEND_KEY` is. The store decides
+ * which is which.
+ *
+ * **An empty value is an error, not an empty string.** A key that exists but
+ * holds nothing resolves to `""` and the process starts with a broken
+ * credential, failing later and far from the cause. Failing here puts the
+ * error where it belongs.
+ */
+export async function resolveEnv(refs, store) {
+    const out = {};
+    for (const [key, value] of Object.entries(refs)) {
+        if (!store.owns(value)) {
+            out[key] = value;
+            continue;
+        }
+        const resolved = await store.get(value);
+        if (resolved === "") {
+            throw new Error(`${key} resolved to an empty value from ${value} — the reference exists ` +
+                `but holds nothing. Remove it until the key has a value.`);
+        }
+        out[key] = resolved;
+    }
+    return out;
+}
+//# sourceMappingURL=store.js.map

package/dist/secrets/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../../src/secrets/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAuBH,gFAAgF;AAChF,MAAM,UAAU,WAAW,CAAC,MAA8B;IACxD,OAAO;QACL,IAAI,CAAC,GAAW;YACd,OAAO,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QACpC,CAAC;QACD,KAAK,CAAC,GAAG,CAAC,GAAW;YACnB,MAAM,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;YACtB,IAAI,CAAC,KAAK,SAAS;gBAAE,MAAM,IAAI,KAAK,CAAC,2BAA2B,GAAG,EAAE,CAAC,CAAC;YACvE,OAAO,CAAC,CAAC;QACX,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,MAAc;YACvB,MAAM,GAAG,GAA2B,EAAE,CAAC;YACvC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;gBAClD,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC;oBAAE,SAAS;gBACtC,MAAM,GAAG,GAAG,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;gBACrC,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC;oBAAE,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;YAClD,CAAC;YACD,OAAO,GAAG,CAAC;QACb,CAAC;QACD,KAAK,CAAC,GAAG,CAAC,GAAW,EAAE,KAAa;YAClC,MAAM,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;QACtB,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,IAA4B,EAC5B,KAAkB;IAElB,MAAM,GAAG,GAA2B,EAAE,CAAC;IACvC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QAChD,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;YACvB,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;YACjB,SAAS;QACX,CAAC;QACD,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACxC,IAAI,QAAQ,KAAK,EAAE,EAAE,CAAC;YACpB,MAAM,IAAI,KAAK,CACb,GAAG,GAAG,oCAAoC,KAAK,0BAA0B;gBACvE,yDAAyD,CAC5D,CAAC;QACJ,CAAC;QACD,GAAG,CAAC,GAAG,CAAC,GAAG,QAAQ,CAAC;IACtB,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/services/types.d.ts

@@ -0,0 +1,39 @@
+/**
+ * What every service client reports about itself.
+ *
+ * Isomorphic — an app may want a health line as much as an operator does.
+ */
+/** One line a person can read: counts, identity, quota. */
+export interface ServiceStatus {
+    service: string;
+    ok: boolean;
+    detail: string;
+    error?: string;
+}
+/**
+ * What a key enables, and how much of that was actually established.
+ *
+ *  - `scopes`       the provider declared the key's rights
+ *  - `identity`     it named the key, and said nothing about rights
+ *  - `reachability` it authenticated. Nothing else was learnt
+ *
+ * The tier is the honest part: rendering the third like the first implies an
+ * assurance nobody obtained.
+ */
+export type AccessEvidence = "scopes" | "identity" | "reachability";
+export interface ServiceAccess {
+    service: string;
+    ok: boolean;
+    evidence: AccessEvidence;
+    scopes?: string[];
+    /** What the key lets the factory do, in operator terms. */
+    can: string[];
+    /** Powers worth seeing, and every place we could not tell. */
+    notes: string[];
+    error?: string;
+}
+/** Run a probe and turn a throw into a readable failure. */
+export declare function probe(service: string, fn: () => Promise<string>): Promise<ServiceStatus>;
+/** Same, for access reports. */
+export declare function probeAccess(service: string, fn: () => Promise<Omit<ServiceAccess, "service" | "ok">>): Promise<ServiceAccess>;
+//# sourceMappingURL=types.d.ts.map

package/dist/services/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/services/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,2DAA2D;AAC3D,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,UAAU,GAAG,cAAc,CAAC;AAEpE,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,EAAE,EAAE,OAAO,CAAC;IACZ,QAAQ,EAAE,cAAc,CAAC;IACzB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,2DAA2D;IAC3D,GAAG,EAAE,MAAM,EAAE,CAAC;IACd,8DAA8D;IAC9D,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,4DAA4D;AAC5D,wBAAsB,KAAK,CACzB,OAAO,EAAE,MAAM,EACf,EAAE,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,GACxB,OAAO,CAAC,aAAa,CAAC,CAOxB;AAED,gCAAgC;AAChC,wBAAsB,WAAW,CAC/B,OAAO,EAAE,MAAM,EACf,EAAE,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,aAAa,EAAE,SAAS,GAAG,IAAI,CAAC,CAAC,GACvD,OAAO,CAAC,aAAa,CAAC,CASxB"}

package/dist/services/types.js

@@ -0,0 +1,28 @@
+/**
+ * What every service client reports about itself.
+ *
+ * Isomorphic — an app may want a health line as much as an operator does.
+ */
+/** Run a probe and turn a throw into a readable failure. */
+export async function probe(service, fn) {
+    try {
+        return { service, ok: true, detail: await fn() };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { service, ok: false, detail: "unreachable", error: message.slice(0, 200) };
+    }
+}
+/** Same, for access reports. */
+export async function probeAccess(service, fn) {
+    try {
+        return { service, ok: true, ...(await fn()) };
+    }
+    catch (err) {
+        return {
+            service, ok: false, evidence: "reachability", can: [], notes: [],
+            error: err instanceof Error ? err.message.slice(0, 200) : String(err),
+        };
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/services/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/services/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAkCH,4DAA4D;AAC5D,MAAM,CAAC,KAAK,UAAU,KAAK,CACzB,OAAe,EACf,EAAyB;IAEzB,IAAI,CAAC;QACH,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;IACnD,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACjE,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC;IACrF,CAAC;AACH,CAAC;AAED,gCAAgC;AAChC,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,OAAe,EACf,EAAwD;IAExD,IAAI,CAAC;QACH,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,EAAE,CAAC,EAAE,CAAC;IAChD,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO;YACL,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAE,GAAG,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE;YAChE,KAAK,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;SACtE,CAAC;IACJ,CAAC;AACH,CAAC"}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@heychunky/core",
+  "version": "0.1.0",
+  "description": "The engine the Chunky CLI, worker and apps run on.",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./admin": {
+      "types": "./dist/admin/index.d.ts",
+      "default": "./dist/admin/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "test": "node --test 'test/**/*.test.ts'",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "devDependencies": {
+    "@types/node": "^24",
+    "typescript": "^5"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/heychunkydev/heychunky-core.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}