modelalive 0.5.0

package/README.md

@@ -0,0 +1,38 @@
+# modelalive (JavaScript)
+
+TypeScript/JavaScript SDK for [Model Alive](https://github.com/Ahaozandaburada/modelalive).
+
+## Install
+
+```bash
+npm install modelalive
+```
+
+Build from source (monorepo):
+
+```bash
+npm install
+npm run build
+```
+
+## Usage
+
+```typescript
+import { alive, check, ensure, resolve } from "modelalive";
+
+// Non-throwing check
+const result = alive("claude-sonnet-4-20250514");
+console.log(result.status);       // "retired"
+console.log(result.replacement); // "claude-sonnet-4-6"
+
+// Pre-flight before API call
+const safe = ensure("claude-sonnet-4-20250514"); // "claude-sonnet-4-6"
+
+// Full replacement chain
+resolve("gemini-2.0-flash"); // "gemini-3.5-flash"
+
+// Strict mode (throws on unknown)
+check("unknown-model", { strictUnknown: true });
+```
+
+Registry is bundled at build time from `registry/models.json`.

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+import type { AliveResult } from "./types.js";
+export declare function alive(model: string, today?: Date): AliveResult;
+export declare function check(model: string, opts?: {
+    strictUnknown?: boolean;
+    today?: Date;
+}): AliveResult;
+export declare function resolve(model: string, today?: Date): string;
+export declare function ensure(model: string, opts?: {
+    strictUnknown?: boolean;
+    today?: Date;
+}): string;
+export * from "./types.js";

package/dist/index.js

@@ -0,0 +1,95 @@
+import { daysUntil, effectiveStatus, loadRegistry, resolveAlias, } from "./registry.js";
+import { ModelRetiredError, ModelUnknownError } from "./types.js";
+export function alive(model, today = new Date()) {
+    const registry = loadRegistry();
+    const queried = model.trim();
+    const [canonical, aliased] = resolveAlias(queried, registry);
+    const entry = registry.models[canonical];
+    if (!entry) {
+        return {
+            model: canonical,
+            queried_model: queried,
+            canonical_model: canonical,
+            aliased,
+            alive: true,
+            status: "unknown",
+            confidence: "unknown",
+            message: "Model not in registry — assumed alive.",
+            registry_version: registry.version,
+        };
+    }
+    const status = effectiveStatus(entry, today);
+    const sourceKey = entry.source ?? "";
+    const sourceMeta = registry.sources[sourceKey];
+    const daysLeft = daysUntil(entry.retired_at, today);
+    const base = {
+        model: canonical,
+        queried_model: queried,
+        canonical_model: canonical,
+        aliased,
+        provider: entry.provider,
+        deprecated_at: entry.deprecated_at,
+        retired_at: entry.retired_at,
+        replacement: entry.replacement ?? null,
+        breaking_changes: entry.breaking_changes ?? [],
+        migrate_url: entry.migrate_url,
+        days_until_retirement: daysLeft,
+        registry_version: registry.version,
+        source_url: sourceMeta?.url,
+        source_checked_at: sourceMeta?.checked_at,
+        confidence: entry.source ? "verified" : "unknown",
+        alive: status !== "retired",
+        status: status,
+    };
+    if (status === "retired") {
+        const repl = entry.replacement ? ` Use '${entry.replacement}' instead.` : "";
+        base.message = `Model '${canonical}' was retired.${repl}`;
+        base.alive = false;
+    }
+    else if (status === "deprecated") {
+        base.message = `Model '${canonical}' is deprecated.`;
+        base.alive = true;
+    }
+    return base;
+}
+export function check(model, opts = {}) {
+    const result = alive(model, opts.today);
+    if (opts.strictUnknown && result.status === "unknown") {
+        throw new ModelUnknownError(result);
+    }
+    if (result.status === "retired") {
+        throw new ModelRetiredError(result);
+    }
+    return result;
+}
+export function resolve(model, today = new Date()) {
+    let current = model.trim();
+    const visited = new Set();
+    for (let i = 0; i < 12; i++) {
+        if (visited.has(current))
+            break;
+        visited.add(current);
+        const result = alive(current, today);
+        if (result.status === "active" || result.status === "unknown") {
+            return result.canonical_model ?? current;
+        }
+        if (!result.replacement)
+            return result.canonical_model ?? current;
+        const repl = alive(result.replacement, today);
+        if (repl.status === "active")
+            return result.replacement;
+        current = result.replacement;
+    }
+    return current;
+}
+export function ensure(model, opts = {}) {
+    const result = alive(model, opts.today);
+    if (opts.strictUnknown && result.status === "unknown") {
+        throw new ModelUnknownError(result);
+    }
+    if (result.status === "retired" && !result.replacement) {
+        throw new ModelRetiredError(result);
+    }
+    return resolve(model, opts.today);
+}
+export * from "./types.js";

package/dist/registry.d.ts

@@ -0,0 +1,6 @@
+import type { Registry, RegistryModel } from "./types.js";
+export declare function loadRegistry(): Registry;
+export declare function parseDate(value?: string): Date | null;
+export declare function effectiveStatus(entry: RegistryModel, today?: Date): string;
+export declare function resolveAlias(model: string, registry?: Registry): [string, boolean];
+export declare function daysUntil(retiredAt: string | undefined, today?: Date): number | null;

package/dist/registry.js

@@ -0,0 +1,46 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+let _registry = null;
+export function loadRegistry() {
+    if (_registry)
+        return _registry;
+    const path = join(__dirname, "..", "registry.json");
+    _registry = JSON.parse(readFileSync(path, "utf-8"));
+    return _registry;
+}
+export function parseDate(value) {
+    if (!value)
+        return null;
+    return new Date(`${value}T00:00:00Z`);
+}
+export function effectiveStatus(entry, today = new Date()) {
+    const retired = parseDate(entry.retired_at);
+    if (retired && retired <= today)
+        return "retired";
+    if (entry.status === "legacy")
+        return "deprecated";
+    return entry.status;
+}
+export function resolveAlias(model, registry = loadRegistry()) {
+    let current = model;
+    const chain = [model];
+    for (let i = 0; i < 8; i++) {
+        const next = registry.aliases[current];
+        if (!next)
+            return [current, chain.length > 1];
+        if (chain.includes(next))
+            break;
+        chain.push(next);
+        current = next;
+    }
+    return [current, chain.length > 1];
+}
+export function daysUntil(retiredAt, today = new Date()) {
+    const target = parseDate(retiredAt);
+    if (!target)
+        return null;
+    const ms = target.getTime() - today.getTime();
+    return Math.floor(ms / (1000 * 60 * 60 * 24));
+}

package/dist/smoke.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/smoke.test.js

@@ -0,0 +1,7 @@
+import assert from "node:assert/strict";
+import { alive, ensure, resolve } from "./index.js";
+assert.equal(alive("claude-sonnet-4-20250514").status, "retired");
+assert.equal(resolve("claude-sonnet-4-20250514"), "claude-sonnet-4-6");
+assert.equal(ensure("claude-sonnet-4-20250514"), "claude-sonnet-4-6");
+assert.equal(alive("claude-sonnet-4-6").status, "active");
+console.log("modelalive js: ok");

package/dist/types.d.ts

@@ -0,0 +1,48 @@
+export interface AliveResult {
+    model: string;
+    alive: boolean;
+    status: "active" | "deprecated" | "retired" | "unknown";
+    queried_model?: string;
+    canonical_model?: string;
+    aliased?: boolean;
+    provider?: string;
+    deprecated_at?: string;
+    retired_at?: string;
+    replacement?: string | null;
+    breaking_changes?: string[];
+    migrate_url?: string;
+    days_until_retirement?: number | null;
+    message?: string;
+    registry_version?: string;
+    source_url?: string;
+    source_checked_at?: string;
+    confidence?: string;
+}
+export interface Registry {
+    version: string;
+    schema_version: number;
+    sources: Record<string, {
+        url: string;
+        checked_at: string;
+    }>;
+    aliases: Record<string, string>;
+    models: Record<string, RegistryModel>;
+}
+export interface RegistryModel {
+    provider: string;
+    status: string;
+    deprecated_at?: string;
+    retired_at?: string;
+    replacement?: string | null;
+    breaking_changes?: string[];
+    migrate_url?: string;
+    source?: string;
+}
+export declare class ModelRetiredError extends Error {
+    readonly result: AliveResult;
+    constructor(result: AliveResult);
+}
+export declare class ModelUnknownError extends Error {
+    readonly result: AliveResult;
+    constructor(result: AliveResult);
+}

package/dist/types.js

@@ -0,0 +1,16 @@
+export class ModelRetiredError extends Error {
+    result;
+    constructor(result) {
+        super(result.message ?? `Model ${result.model} is retired`);
+        this.result = result;
+        this.name = "ModelRetiredError";
+    }
+}
+export class ModelUnknownError extends Error {
+    result;
+    constructor(result) {
+        super(result.message ?? `Model ${result.model} is unknown`);
+        this.result = result;
+        this.name = "ModelUnknownError";
+    }
+}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "modelalive",
+  "version": "0.5.0",
+  "description": "Pre-flight check: is this LLM model ID still alive?",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": ["dist", "registry.json"],
+  "scripts": {
+    "build": "tsc && cp ../registry/models.json registry.json",
+    "prebuild": "cp ../registry/models.json registry.json",
+    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js 2>/dev/null || npm run build && node --test dist/test/*.js"
+  },
+  "keywords": ["llm", "anthropic", "openai", "gemini", "deprecation", "model-id"],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Ahaozandaburada/modelalive.git",
+    "directory": "js"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.0"
+  }
+}