@plurnk/plurnk-aliases 0.1.0

package/README.md

@@ -0,0 +1,50 @@
+# @plurnk/plurnk-aliases
+
+Zero-dependency parser for the plurnk model-alias cascade. Vendor-agnostic, MIT.
+
+Resolves `PLURNK_MODEL_<alias>=<provider>/<model>` env vars (plus per-alias
+`PLURNK_BASEURL_<alias>` endpoint overrides) into structured `ProviderAlias`
+records. Extracted from `@plurnk/plurnk-providers` so a **thin client** can
+resolve aliases from its own always-fresh env — and send the daemon a resolved
+`{ provider, model, baseUrl? }` — without pulling the provider-instantiation or
+tokenizer machinery. `@plurnk/plurnk-providers` depends on this and re-exports
+the same surface, so it stays the single source of truth.
+
+## Install
+
+```
+npm install @plurnk/plurnk-aliases
+```
+
+Node ≥26, ESM.
+
+## API
+
+```ts
+import { parseAliasesFromEnv, resolveActiveAlias, type ProviderAlias } from "@plurnk/plurnk-aliases";
+
+parseAliasesFromEnv(env = process.env): ProviderAlias[]   // every declared alias
+resolveActiveAlias(env = process.env): ProviderAlias | null // the PLURNK_MODEL-selected one, or null
+```
+
+```ts
+interface ProviderAlias {
+    readonly alias: string;     // lowercase, .env key suffix downcased
+    readonly provider: string;  // "openai", "openrouter", "ollama", …
+    readonly model: string;     // provider-native id; may contain "/"
+    readonly baseUrl?: string;  // PLURNK_BASEURL_<alias> override, when set
+}
+```
+
+To resolve a named alias (e.g. from `loop.run({ alias })`), parse and find:
+
+```ts
+const alias = parseAliasesFromEnv().find((a) => a.alias === name.toLowerCase());
+```
+
+## Contract
+
+The provider segment is the **first** `/`-delimited field; the model id is the
+remainder (it may itself contain `/`). Aliases are case-folded. Fail-hard on a
+case-folding collision (two keys → one alias) and on a `PLURNK_BASEURL_*`
+override with no matching alias (a typo, never a silent no-op). See `SPEC.md`.

package/SPEC.md

@@ -0,0 +1,47 @@
+# @plurnk/plurnk-aliases — contract
+
+The canonical parser for the plurnk model-alias cascade. Zero runtime
+dependencies. `@plurnk/plurnk-providers` depends on this package and re-exports
+its surface unchanged; thin clients depend on it directly to resolve aliases
+without the provider/tokenizer machinery.
+
+## The cascade
+
+- **`PLURNK_MODEL_<alias>=<provider>/<model>`** declares an alias. The provider
+  segment is the **first** `/`-delimited field; the model id is everything after
+  that first `/` (it MAY contain further `/`, e.g. `openrouter/anthropic/claude-…`).
+- **`PLURNK_MODEL=<alias>`** selects the active alias at boot.
+- **`PLURNK_BASEURL_<alias>`** attaches a per-alias endpoint override — the one
+  thing a per-provider base-URL var can't express (two aliases on the same
+  provider name pointing at different self-hosted boxes).
+
+Alias keys are **case-folded** (the suffix after `PLURNK_MODEL_` / `PLURNK_BASEURL_`
+is downcased), so `PLURNK_MODEL_opus` and `PLURNK_MODEL_OPUS` name the same alias.
+
+## `ProviderAlias`
+
+```ts
+interface ProviderAlias {
+    readonly alias: string;
+    readonly provider: string;
+    readonly model: string;
+    readonly baseUrl?: string;  // present only when PLURNK_BASEURL_<alias> is set
+}
+```
+
+## Functions
+
+- **`parseAliasesFromEnv(env = process.env): ProviderAlias[]`** — every declared
+  alias. Skips entries with an empty value or no `/` in the value.
+- **`resolveActiveAlias(env = process.env): ProviderAlias | null`** — the alias
+  named by `PLURNK_MODEL` (case-insensitive), or `null` when `PLURNK_MODEL` is
+  unset or names no declared alias.
+
+## Fail-hard rules
+
+- **Case-folding collision** — two `PLURNK_MODEL_*` keys that downcase to the
+  same alias throw (`Duplicate provider alias "<alias>"`). No silent pick.
+- **Dangling override** — a `PLURNK_BASEURL_*` whose alias has no matching
+  `PLURNK_MODEL_*` throws (a typo, not a silent no-op).
+
+Both are contract violations surfaced loudly, never recovered.

package/dist/aliases.d.ts

@@ -0,0 +1,4 @@
+import type { ProviderAlias } from "./types.ts";
+export declare const parseAliasesFromEnv: (env?: NodeJS.ProcessEnv) => ProviderAlias[];
+export declare const resolveActiveAlias: (env?: NodeJS.ProcessEnv) => ProviderAlias | null;
+//# sourceMappingURL=aliases.d.ts.map

package/dist/aliases.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aliases.d.ts","sourceRoot":"","sources":["../src/aliases.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAkBhD,eAAO,MAAM,mBAAmB,GAAI,MAAK,MAAM,CAAC,UAAwB,KAAG,aAAa,EAuBvF,CAAC;AAEF,eAAO,MAAM,kBAAkB,GAAI,MAAK,MAAM,CAAC,UAAwB,KAAG,aAAa,GAAG,IAKzF,CAAC"}

package/dist/aliases.js

@@ -0,0 +1,67 @@
+// The plurnk model-alias cascade — pure env parsing, zero runtime deps.
+//
+// PLURNK_MODEL_<alias>=<provider>/<model> declares an alias; PLURNK_MODEL=<alias>
+// selects the active one at boot. The provider segment is the first "/"-delimited
+// field; the model id is the remainder (it may itself contain "/"). Aliases are
+// case-folded (the .env key suffix downcased). PLURNK_BASEURL_<alias> attaches a
+// per-alias endpoint override — the one thing a per-provider base-URL var can't
+// express (two aliases on the same provider name pointing at different boxes).
+//
+// Extracted from @plurnk/plurnk-providers so a thin consumer can resolve aliases
+// from its own (always-fresh) env without pulling the provider/tokenizer machinery.
+// PLURNK_BASEURL_<alias>: per-alias endpoint override, case-folded on the alias
+// to match PLURNK_MODEL_<alias>. Lets two aliases on the same provider name target
+// different self-hosted boxes (openai/ollama), the one thing a per-name base-URL
+// var can't express.
+const parseBaseUrls = (env) => {
+    const out = new Map();
+    for (const [key, value] of Object.entries(env)) {
+        if (value === undefined || value.length === 0)
+            continue;
+        if (!key.startsWith("PLURNK_BASEURL_"))
+            continue;
+        const aliasRaw = key.slice("PLURNK_BASEURL_".length);
+        if (aliasRaw.length === 0)
+            continue;
+        out.set(aliasRaw.toLowerCase(), value);
+    }
+    return out;
+};
+export const parseAliasesFromEnv = (env = process.env) => {
+    const out = [];
+    const seen = new Set();
+    const baseUrls = parseBaseUrls(env);
+    for (const [key, value] of Object.entries(env)) {
+        if (value === undefined || value.length === 0)
+            continue;
+        if (!key.startsWith("PLURNK_MODEL_"))
+            continue;
+        const aliasRaw = key.slice("PLURNK_MODEL_".length);
+        if (aliasRaw.length === 0)
+            continue;
+        const slash = value.indexOf("/");
+        if (slash <= 0)
+            continue;
+        const alias = aliasRaw.toLowerCase();
+        // Aliases are case-folded, so PLURNK_MODEL_opus and PLURNK_MODEL_OPUS
+        // collide. Surface the ambiguity rather than silently picking one.
+        if (seen.has(alias))
+            throw new Error(`Duplicate provider alias "${alias}": multiple PLURNK_MODEL_* keys case-fold to the same alias. Rename one.`);
+        seen.add(alias);
+        const baseUrl = baseUrls.get(alias);
+        out.push({ alias, provider: value.slice(0, slash), model: value.slice(slash + 1), ...(baseUrl !== undefined ? { baseUrl } : {}) });
+    }
+    // A base-URL override with no matching alias is a typo, not a silent no-op.
+    const unmatched = [...baseUrls.keys()].filter((a) => !seen.has(a));
+    if (unmatched.length > 0)
+        throw new Error(`PLURNK_BASEURL_* override(s) with no matching PLURNK_MODEL_* alias: ${unmatched.join(", ")}. Declare the alias or remove the override.`);
+    return out;
+};
+export const resolveActiveAlias = (env = process.env) => {
+    const selected = env.PLURNK_MODEL;
+    if (selected === undefined || selected.length === 0)
+        return null;
+    const aliases = parseAliasesFromEnv(env);
+    return aliases.find((a) => a.alias === selected.toLowerCase()) ?? null;
+};
+//# sourceMappingURL=aliases.js.map

package/dist/aliases.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"aliases.js","sourceRoot":"","sources":["../src/aliases.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export type { ProviderAlias } from "./types.ts";
+export { parseAliasesFromEnv, resolveActiveAlias } from "./aliases.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export { parseAliasesFromEnv, resolveActiveAlias } from "./aliases.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,7 @@
+export interface ProviderAlias {
+    readonly alias: string;
+    readonly provider: string;
+    readonly model: string;
+    readonly baseUrl?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,aAAa;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC7B"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,52 @@
+{
+    "name": "@plurnk/plurnk-aliases",
+    "version": "0.1.0",
+    "description": "Zero-dependency parser for the plurnk model-alias cascade (PLURNK_MODEL_<alias>=<provider>/<model>, PLURNK_BASEURL_<alias>). Shared by @plurnk/plurnk-providers and thin plurnk clients that resolve aliases without pulling the provider/tokenizer machinery.",
+    "keywords": [
+        "plurnk",
+        "alias",
+        "provider",
+        "env"
+    ],
+    "homepage": "https://github.com/plurnk/plurnk-aliases#readme",
+    "bugs": {
+        "url": "https://github.com/plurnk/plurnk-aliases/issues"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/plurnk/plurnk-aliases.git"
+    },
+    "engines": {
+        "node": ">=26"
+    },
+    "license": "MIT",
+    "author": "@wikitopian",
+    "type": "module",
+    "publishConfig": {
+        "access": "public"
+    },
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "default": "./dist/index.js"
+        },
+        "./package.json": "./package.json"
+    },
+    "files": [
+        "dist/**/*",
+        "README.md",
+        "SPEC.md"
+    ],
+    "scripts": {
+        "test:lint": "tsc --noEmit",
+        "test:unit": "node --test src/**/*.test.ts",
+        "test": "npm run test:lint && npm run test:unit",
+        "build:dist": "tsc -p tsconfig.build.json",
+        "build": "npm run build:dist",
+        "prepare": "npm run build"
+    },
+    "devDependencies": {
+        "@types/node": "^26.0.0",
+        "typescript": "^6.0.3"
+    }
+}