@mulmoclaude/common 0.1.0

package/README.md

@@ -0,0 +1,33 @@
+# @mulmoclaude/common
+
+General-purpose, **dependency-free** runtime type guards shared across the
+MulmoClaude host (`server/`, `src/`), the chat bridges (`@mulmobridge/*`), and
+the plugins.
+
+This is a **leaf package** — it imports nothing, so any tier can depend on it
+without creating an uphill edge (see the dependency-direction rule in the repo
+`CLAUDE.md`).
+
+## Why it exists
+
+`server/utils/types.ts` and `src/utils/types.ts` were byte-for-byte duplicates
+kept in sync by hand, and the `isObj` guard alone had been re-typed in 18 files
+across the bridges and relay. These guards are the definition of "general and
+duplicated," so they live here once.
+
+## Contents
+
+| Guard | Narrows to | Notes |
+|---|---|---|
+| `isRecord(v)` | `Record<string, unknown>` | plain object; **arrays excluded** |
+| `isObj(v)` | `object` | any non-null object; **arrays allowed** |
+| `isNonEmptyString(v)` | `string` | non-empty **after trimming** |
+| `isStringRecord(v)` | `Record<string, string>` | every value is a string |
+| `isStringArray(v)` | `string[]` | every element is a string |
+| `isUnknownArray(v)` | `unknown[]` | prefer over bare `Array.isArray` (which narrows to `any[]`) |
+| `isErrorWithCode(v)` | `{ code: string; message?: string }` | Node.js fs-style errors |
+| `hasStringProp(v, k)` | `Record<k, string>` | key present with a string value |
+| `hasNumberProp(v, k)` | `Record<k, number>` | key present with a number value |
+
+`isRecord` vs `isObj`: use `isRecord` whenever you go on to index string keys —
+`isObj` lets arrays through, which is rarely what you want for a JSON payload.

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+/** Narrow `unknown` to a plain object (not null, not array). */
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+/** Narrow `unknown` to any object (not null, arrays allowed).
+ *  Use `isRecord` when you need to access string keys. */
+export declare function isObj(value: unknown): value is object;
+/** Non-empty string after trimming whitespace. */
+export declare function isNonEmptyString(value: unknown): value is string;
+/** Record whose values are all strings. */
+export declare function isStringRecord(value: unknown): value is Record<string, string>;
+/** String array (every element is a string). */
+export declare function isStringArray(value: unknown): value is string[];
+/** An array of unknowns. Prefer this over a bare `Array.isArray` in typed code:
+ *  `Array.isArray(x: unknown)` narrows to `any[]`, silently reintroducing
+ *  `any`, whereas this keeps the element type `unknown`. */
+export declare function isUnknownArray(value: unknown): value is unknown[];
+/** Error-like object with a `code` property (e.g. Node.js fs errors). */
+export declare function isErrorWithCode(value: unknown): value is {
+    code: string;
+    message?: string;
+};
+/** Check that a record has a specific key with a string value. */
+export declare function hasStringProp<K extends string>(value: unknown, key: K): value is Record<K, string> & Record<string, unknown>;
+/** Check that a record has a specific key with a number value. */
+export declare function hasNumberProp<K extends string>(value: unknown, key: K): value is Record<K, number> & Record<string, unknown>;

package/dist/index.js

@@ -0,0 +1,48 @@
+// General-purpose runtime type guards, shared across the MulmoClaude host,
+// bridges, and plugins. This is a leaf package — pure and dependency-free — so
+// any tier can import it without creating an uphill edge.
+//
+// These originated as `server/utils/types.ts` (#504), which centralised 40+
+// hand-written inline `typeof x === "object"` checks. They are promoted here so
+// the same guards stop being re-hand-written in every bridge and plugin too.
+/** Narrow `unknown` to a plain object (not null, not array). */
+export function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Narrow `unknown` to any object (not null, arrays allowed).
+ *  Use `isRecord` when you need to access string keys. */
+export function isObj(value) {
+    return typeof value === "object" && value !== null;
+}
+/** Non-empty string after trimming whitespace. */
+export function isNonEmptyString(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+/** Record whose values are all strings. */
+export function isStringRecord(value) {
+    if (!isRecord(value))
+        return false;
+    return Object.values(value).every((val) => typeof val === "string");
+}
+/** String array (every element is a string). */
+export function isStringArray(value) {
+    return Array.isArray(value) && value.every((val) => typeof val === "string");
+}
+/** An array of unknowns. Prefer this over a bare `Array.isArray` in typed code:
+ *  `Array.isArray(x: unknown)` narrows to `any[]`, silently reintroducing
+ *  `any`, whereas this keeps the element type `unknown`. */
+export function isUnknownArray(value) {
+    return Array.isArray(value);
+}
+/** Error-like object with a `code` property (e.g. Node.js fs errors). */
+export function isErrorWithCode(value) {
+    return isRecord(value) && typeof value.code === "string";
+}
+/** Check that a record has a specific key with a string value. */
+export function hasStringProp(value, key) {
+    return isRecord(value) && typeof value[key] === "string";
+}
+/** Check that a record has a specific key with a number value. */
+export function hasNumberProp(value, key) {
+    return isRecord(value) && typeof value[key] === "number";
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@mulmoclaude/common",
+  "version": "0.1.0",
+  "description": "General-purpose pure utilities (type guards, etc.) shared across the MulmoClaude host, bridges, and plugins",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepack": "yarn build",
+    "typecheck": "tsc --noEmit",
+    "test": "tsx --test test/test_*.ts",
+    "lint": "eslint src test"
+  },
+  "license": "MIT",
+  "author": "Receptron Team",
+  "devDependencies": {
+    "typescript": "^6.0.3"
+  }
+}