Skip to content

Nara v3.2.0 — Composable & Evolvable Open Code

Latest
Latest

Choose a tag to compare

View all tags
@MasRama MasRama released this 06 Sep 16:32
· 27 commits to main since this release
v3.2.0
2a3a9f9

Nara v3.2.0 — Composable & Evolvable Open Code

Nara v3.1 taught the CLI to describe architecture and how it changes. v3.2 makes that architecture something you can ship, adopt, and keep: official capabilities install as explicit source, adapt through ordinary typed code, and evolve without orphaning your customizations.

Composable Open Code

A Feature Assembly separates three things starter kits usually blur together:

Feature-owned source
+
application-owned bindings
+
explicit application activation

Installing a Feature copies its implementation into your source tree, writes application-owned bindings beside it, and activates them with explicit composition calls in your canonical roots. Every file is visible and verified by the architecture engine before anything is applied — installation is transactional and fails closed.

Official Features do not need zero application-level changes. They need zero hidden application-level changes.

Bindings remain ordinary Hono / Vue Router TypeScript. No runtime registry, no DI container, no hidden plugin system.

Evolvable Open Code

Installed source stays evolvable through a three-way reconciliation:

BASE + LOCAL + INCOMING

BASE is the exact official source recorded at install time, LOCAL is your possibly customized copy, and INCOMING is the current official source. Upstream-only updates merge in, local-only code is preserved, and conflicts are reported as a stable path list — never as conflict markers, never partially applied.

Open code without orphaning.

Feature-owned source can evolve while application-owned bindings and local policy remain untouched. Conflicts and architecture regressions fail closed.

Typed Host Requirements

Users is the substantial proof. It needs account identity without depending on any particular identity implementation:

Users
→ typed host requirements

application binding
→ Auth or another compatible provider

Users declares its host surface as plain TypeScript; the application binding satisfies it with the reference Auth capability or any compatible provider the application owns. Users no longer hard-depends on the Auth implementation. No service locator, no runtime dependency injection.

Explicit prerequisites

Official Features may declare distribution-only prerequisites through:

.nara/requirements.json
  • Provider requirements are explicit and validated against the application's actual source
  • npm requirements are validated against actual imports
  • package.json composition is transactional
  • The lockfile remains untouched
  • Nara does not run npm install
  • Provider Features are never auto-installed

Requirements metadata is distribution help, not architecture truth — the engine derives facts from src/, never from the manifest.

Architecture intelligence

Supporting improvements since v3.1, in service of the composed application:

  • Architecture Context Packs — bounded reading order before editing
  • Application integration provenance — which bindings mount which routes, from which boundary symbols
  • Public API consumer evidence — who consumes exact public and browser-safe symbols
  • Boundary export provenance — statically provable framework composition
  • Architecture-aware diff / affected reasoning between refs
  • guard — fail CI only on newly introduced diagnostics

Official Features

Current catalog:

health
audit
users

Users is the first substantial assembly — full server routes, browser pages, migrations, and typed host bindings — and requires a compatible provider for its bundled application binding. Auth remains a reference implementation in the Nara repository and is not an official installable Feature.

Verification

The canonical release gate for v3.2.0 proves version coherence; production build, startup, and serving; HTTP stack compatibility; actual npm tarball contents; clean project generation; Health assembly and lineage; official Feature installation; Users substantial composition; package prerequisite composition; migration compatibility; substrate integrity; architecture validation; and customized binding preservation through evolve.

Links

Assets 2
Loading