npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@ogarciarevett/jev-sdk

v0.2.0

Published

Typed Jev decision support for repository agents: judgments, option scoring, finding routing, decision logs, an MCP server, and a stop hook.

Readme

jev-sdk

Typed decision support with secrets masked before sending.

License: Apache-2.0 TypeScript CI

Works with Node.js · Bun · MCP


Ask Jev, the TypeSafe decision service, typed questions about a piece of state and get one verdict per question. The SDK masks secrets before anything leaves the machine, applies a bar per question by its stakes, retries rate limits, and reports how far ahead the winning answer was. It ships a library, command-line tools, an MCP server, and a stop hook.

A verdict is evidence for an operator or an agent. It never authorizes an edit, a deployment, a financial action, or a skipped review.

flowchart LR
    state["State + question pack"] --> mask["Mask secrets<br/>on this machine"]
    mask --> jev["Jev<br/>TypeSafe service"]
    jev --> bar{"Clears the bar<br/>for its stakes?"}
    bar -->|yes| verdict["Verdict<br/>yes / no, choice, score"]
    bar -->|no, or any failure| undecided["undecided + reason<br/>stop or ask a person"]

Quick path

  1. Install: npm i @ogarciarevett/jev-sdk
  2. Put TYPESAFE_API_KEY in the process environment (see The API key).
  3. Copy a question pack into your repository and ask:
mkdir -p questions
cp node_modules/@ogarciarevett/jev-sdk/questions/agent-operations.json questions/
printf '%s\n' '{"change":"rename a test helper","files":["test/helper.ts"]}' \
  | npx --no-install jev-judge --state - --questions questions/agent-operations.json

It prints one JSON object with a verdict per question id. Treat undecided as "stop or ask a person", never as yes.

Install

| Package manager | Command | | --- | --- | | npm | npm i @ogarciarevett/jev-sdk | | pnpm | pnpm add @ogarciarevett/jev-sdk | | Bun | bun add @ogarciarevett/jev-sdk |

Every release goes out under one dist-tag. A pre-release never moves latest.

| Dist-tag | Versions | Install | | --- | --- | --- | | latest | X.Y.Z | npm i @ogarciarevett/jev-sdk | | rc | X.Y.Z-rc.N | npm i @ogarciarevett/jev-sdk@rc | | beta | X.Y.Z-beta.N | npm i @ogarciarevett/jev-sdk@beta | | alpha | X.Y.Z-alpha.N | npm i @ogarciarevett/jev-sdk@alpha |

Pin an exact version (@ogarciarevett/[email protected]) when you want the same bytes on every install. Each npm release carries a provenance attestation that links it to the GitHub workflow run that built it.

The same versions are mirrored to GitHub Packages (https://npm.pkg.github.com), which needs a token with read:packages even for public packages; npm is the simpler source.

Runtimes

| Runtime | Support | | --- | --- | | Node.js | ^22.18.0 \|\| >=24.2.0, the first releases with import.meta.main, which every command uses. | | Bun | Imports work as they do in Node. bunx --no-install jev-judge runs the commands with Node, as their #!/usr/bin/env node line asks; bunx --bun runs them with Bun. |

The package is ES modules only and ships TypeScript declarations.

The API key

Set TYPESAFE_API_KEY in the process environment, from your CI secret store or a keychain wrapper that exports it for one invocation. Never put it in a file in the repository, in package.json, or in a command argument.

Jev reads the key from the environment only. It does not load .env files, and neither does Node unless asked with --env-file. Bun does load .env files on its own, so under Bun either keep the key out of them or run with --no-env-file.

Without the key every verdict is undecided with the reason typesafe_api_key_missing; nothing is sent.

Verdicts

Each question id in the result maps to a verdict:

| Field | Meaning | | --- | --- | | verdict | yes or no for a noul question, the chosen option for a choice, the level for a score, box for a box, or undecided. | | value, valueKind | The probability (noul) or confidence (choice, score, box) behind the answer. | | box | Only for a box question: the top, bottom, left and right edges as fractions of the image. | | threshold | The bar the answer had to clear: an explicit override if the call set one, else the question's stakes (passive 0.6, design 0.75, critical 0.9), else 0.8. | | margin | How far the leading answer is ahead of the next one. | | leaning | The answer the service gave, even when it did not clear the bar. | | reason | Only on undecided: why. |

undecided means Jev could not decide above the bar. It is never permission to proceed. Its reasons:

| Reason | What happened | | --- | --- | | typesafe_api_key_missing | No key in the environment; nothing was sent. | | request_timeout, network_error | The service did not answer in time, or could not be reached. | | http_client_error, http_server_error, rate_limited | The service refused the request, failed, or was still rate-limiting after retries. | | response_schema_mismatch, answer_missing, answer_type_mismatch | The answer did not have the expected shape. | | below_threshold | The service answered, but not confidently enough for this question's bar. |

The judging commands exit 0 for any verdict, undecided included, and 2 for a usage error. Two commands differ:

  • jev-stop-hook follows the Claude Code Stop hook contract: exit 0 lets the assistant stop (on no, undecided, or any failure), and exit 2 blocks the stop on yes, with the reason on stderr.
  • jev-smoke exits 2 when TYPESAFE_API_KEY is missing, instead of reporting a latency it never measured.

Commands

| Command | Role | | --- | --- | | jev-judge | Judge typed questions about state. | | jev-score-options | Compare options across weighted dimensions. | | jev-finding | Route a review finding against committed code and a base ref. | | jev-outcome, jev-report | Record and summarize how decisions turned out. | | jev-capabilities | Select capabilities from your skills and extras. | | jev-mcp-server | Serve the jev_judge tool over MCP stdio. | | jev-stop-hook | Optional Claude Code Stop hook: blocks a stop while Jev judges the assistant can still make progress alone; no or undecided lets it stop. | | jev-smoke | Optional live latency and availability probe; needs the key. |

Every command except jev-mcp-server, jev-stop-hook, and jev-smoke prints its flags with --help. The package registers no hooks or MCP servers on its own; wire up the ones you want.

Run the commands from your repository's working directory. jev-judge reads questions/agent-operations.json there unless --questions <path> says otherwise; jev-finding reads questions/agent-operations.json and questions/plan-decisions.json unless --questions-directory <path> says otherwise. Nothing is read from the package implicitly.

With --log, decisions are appended to .local/jev-decisions/ under the working directory (--directory <path> overrides it). The log holds masked content, but it is still yours: keep .local/ in your .gitignore.

Library

Import by subpath:

import { judge, jevDependenciesFrom } from "@ogarciarevett/jev-sdk/judge";

const result = await judge(
  {
    state: { change: "rename a test helper", files: ["test/helper.ts"] },
    questions: {
      needs_owner: { type: "noul", stakes: "design", instructions: "Does the owner have to act?" },
    },
  },
  jevDependenciesFrom(process.env),
);
console.log(result.verdicts.needs_owner?.verdict);

| Subpath | Contents | | --- | --- | | @ogarciarevett/jev-sdk, /judge | judge, jevDependenciesFrom, thresholds, and the request and verdict types. | | /mask | maskJevText, maskJevState, maskJevQuestions: the masking applied before every request. | | /score-options, /finding, /capabilities | The logic behind jev-score-options, jev-finding, and jev-capabilities. | | /decision-log | Reading and writing the decision log. | | /jev-judge, /jev-finding, and the other command names | Each command's module, importable without running it. | | /questions/*, /skills/jev/* | The question pack templates and the agent skill, as files. |

Images and Box (experimental)

TypeSafe's image models are opt-in and "dreamer-ready": fine for prototypes, not yet for production, and the format can change. Pass PNG or JPEG bytes in images, keyed by a reference string, and write that reference where the image belongs (state, instructions or criteria). The SDK sends the TypeSafe-Danger-Zone-Images: true header for you. A box question returns where something is; it needs Jev 1.14.

import { readFileSync } from "node:fs";
import { JEV_BOX_MODEL, judge, jevDependenciesFrom } from "@ogarciarevett/jev-sdk/judge";

const photo = "6e1d0b7c-kitchen"; // a reference that cannot occur in your text by accident
const result = await judge(
  {
    state: { photo },
    questions: {
      mug_visible: { type: "noul", instructions: "Is there a coffee mug in `photo`?" },
      mug: { type: "box", instructions: "the coffee mug in `photo`" },
    },
    images: { [photo]: readFileSync("kitchen.jpg") },
    model: JEV_BOX_MODEL,
    timeoutMs: 30_000,
  },
  jevDependenciesFrom(process.env),
);
console.log(result.verdicts.mug?.box); // { top, bottom, left, right } as fractions

A box answer is always a box, even when the target is absent, so pair it with a noul as above. Image bytes are not text, so they are sent as they are; everything else is still masked, and the decision log never holds the bytes. The service rejects an image with a side under 280 or over 1568 pixels; such a call ends undecided with http_client_error. longContext: true sends TypeSafe-Danger-Zone-Long-Context: true and raises the state budget to 786,000 characters. Docs: https://docs.typesafe.ai/images

Question packs and the agent skill

The packs in questions/ are templates: copy them into your repository and adapt the questions to your vocabulary. A pack is { "questions": { "<id>": { "type", "stakes", "instructions", "criteria" } } }; types are noul, choice, and score.

skills/jev/ is a portable agent skill with references on the protocol, question packs, anti-patterns, and a worked example. Copy it if your agent runtime uses skills.

Migrating from a source checkout

If your repository carries a copy of Jev's sources, install the package, replace relative imports with the subpaths above and direct bun <path>/jev-*.ts calls with the jev-* commands, keep your question packs in your own questions/ directory, and delete the copy once your tests pass.

Develop

bun install
bun test
bunx tsc --noEmit
bun run build

bun test includes a smoke test that builds and packs the package, installs it into a temporary consumer, and imports, type-checks, and runs it with plain node. It needs node and npm on PATH and is skipped without them, unless JEV_REQUIRE_NODE_SMOKE=1 (set in CI) turns the skip into a failure.

Releases are cut from GitHub Releases; see RELEASING.md.

License

Apache-2.0