nene2-js

TypeScript ecosystem for NENE2: OpenAPI-aligned types, HTTP client helpers, and Problem Details utilities for apps that consume NENE2 JSON APIs.

Documentation: https://hideyukimori.github.io/nene2-js/ (English, 日本語, Français, 中文, Português, Deutsch)

This repository is not a Node.js port of the PHP framework. The PHP runtime stays in NENE2. MCP stdio servers in PHP live in nene-mcp.

What this repo is for

• Typed fetch wrappers and shared client boundaries derived from NENE2 OpenAPI
• RFC 9457 Problem Details parsing and validation-error helpers for TypeScript consumers
• Optional codegen scripts and published npm packages (@hideyukimori/nene2-client, scoped subpackages later)
• Documentation and tooling that follow the same Issue-driven workflow as NENE2

What this repo is not for

• Replacing NENE2 PHP HTTP runtime, routing, middleware, or DI
• Duplicating nene-mcp (stdio MCP server in PHP)
• React/Vite starter UI (that remains in NENE2 frontend/ unless explicitly extracted later)
• Direct database access from AI tools or SDK code
• Application-specific business logic (belongs in consumer projects and NENE2-FT style trials)

See docs/scope.md for the full in-scope / out-of-scope matrix.

Install (npm)

npm install @hideyukimori/[email protected]

Requires Node 22+ (native fetch) or a browser with fetch. TypeScript consumers get .d.ts from the package.

Monorepo / contributors: clone this repo and use npm run check (builds dist/ and runs pack smoke).

Local layout (sibling of NENE2)

../docker/
├── NENE2/          # PHP framework (contract source: docs/openapi/openapi.yaml)
├── nene2-js/       # this repository
├── nene-mcp/       # PHP MCP stdio library (separate concern)
└── NENE2-FT/       # field-trial reference apps

Clone next to your existing NENE2 checkout:

cd /path/to/parent-of-NENE2
git clone [email protected]:hideyukiMORI/nene2-js.git
cd nene2-js
npm install
npm run check

OpenAPI types: npm run codegen (see Phase 3).

Point local development at a running NENE2 API when needed:

cp .env.example .env
# NENE2_JS_API_BASE_URL=http://localhost:8080

Usage (typed client)

import { createNene2Client, Nene2ClientError } from '@hideyukimori/nene2-client';

const client = createNene2Client({
  baseUrl: 'http://localhost:8080',
  // apiKey: process.env.NENE2_MACHINE_API_KEY,
  // bearer: process.env.NENE2_BEARER_TOKEN,
});

const { health, ping } = await client.smoke();
const root = await client.frameworkSmoke();
const notes = await client.listNotes({ limit: 20 });

// Load balancers may return 503 with status "degraded" — opt in:
const degraded = await client.health({ allowDegraded: true });

try {
  await client.getNote(1);
} catch (err) {
  if (err instanceof Nene2ClientError && err.problem) {
    console.error(err.problem.title, err.problem.detail);
  }
}

Works in Node 22+ and browsers that provide fetch.

Verify the API before live smoke

Port 8080 is not always NENE2. Confirm the canonical health shape:

curl -sS http://localhost:8080/health | jq .
# expect: { "status": "ok", "service": "NENE2" }

Or in TypeScript: await client.health({ strictService: true }) rejects wrong service values.

If you see a different JSON wrapper, point NENE2_JS_API_BASE_URL at a running NENE2 PHP instance (sibling ../NENE2).

Multi-backend live smoke (same client, OpenAPI contract — see ADR 0003):

export NENE2_JS_API_BASE_URL=http://localhost:18080     # NENE2 evac (see ft-evac-ports.md)
export NENE2_JS_PYTHON_BASE_URL=http://localhost:18000  # optional: nene2-python
# export NENE2_JS_NODE_BASE_URL=http://localhost:13000  # optional: nene2-node

npm run verify:backends   # curl /health, /examples/ping, /examples/notes
npm test -- tests/client/live-smoke-matrix.test.ts

Unset URLs are skipped; CI runs fixture tests only. Field-trial friction: ADR 0004.

Documentation site (local)

npm install
npm run docs:dev    # http://localhost:5175
npm run docs:build  # static output → .vitepress/dist

Published on push to main via .github/workflows/docs.yml.

Contributing

Work is GitHub Issue driven. Read docs/CONTRIBUTING.md and docs/workflow.md before opening a PR.

AI agents: start at AGENTS.md.

Consumer DX evidence: field trials (FT30–529 marathon; see methodology, friction registry). Local app sandbox: sibling ../nene2-js-FT/. Quick start: howto/consume-client.md.

Release: docs/development/publish.md · Phase history: docs/phase-2.md.

Related projects

| Project | Role | | ----------------------------------------------------------------------- | -------------------------------------------------------- | | NENE2 | PHP API framework, OpenAPI contract, MCP catalog in-repo | | nene2-node | Node.js framework port (@hideyukimori/nene2-framework) | | nene-mcp | Standalone PHP stdio MCP server | | hideyukimori/nene2 | Composer package for PHP consumers |

License

MIT — see LICENSE.