@rivinia/env 0.3.0 → 0.3.1

package/README.md

@@ -3,50 +3,49 @@
 [![npm version](https://img.shields.io/npm/v/@rivinia/env.svg)](https://www.npmjs.com/package/@rivinia/env)
 [![license](https://img.shields.io/npm/l/@rivinia/env.svg)](https://www.npmjs.com/package/@rivinia/env)
 
-Typed application environments for Angular: dev/staging/prod file layout, a
-`BaseEnvironment` contract, and an `ng-add` schematic that scaffolds the
-files and wires the build configurations. Zero runtime code — environments are
-build-time constants; this package ships types plus setup tooling only.
+`@rivinia/env` provides the `BaseEnvironment` TypeScript contract and an
+Angular CLI `ng add` schematic. It does not read environment values at
+runtime: Angular's build file replacements select a statically imported
+environment file.
 
-- Version: **0.3.0**
-- Requires: nothing at runtime (types only). Schematic runs under Angular CLI 22+.
+- Prepared patch: **0.3.1** (latest published: **0.3.0**)
+- No runtime providers or services; the package supplies a type and CLI tooling.
+- The generated model imports `BaseEnvironment` from this package.
 
-## Install
+## Install and scaffold
+
+From an Angular CLI workspace:
 
 ```bash
 npm install @rivinia/env
-ng add @rivinia/env   # multi-select: dev / stage / prod
+ng add @rivinia/env
 ```
 
-Interactive runs ask which environments to scaffold (checkbox, all checked by
-default); non-interactive runs take all. From flags, comma-separate (short
-aliases work: `dev`, `prod`, `stag`):
+The schematic prompts for environments when interactive; the default and
+non-interactive selection is all three (`dev`, `stage`, `prod`). Select only
+what you need with a comma-separated option:
 
 ```bash
 ng add @rivinia/env --environments stage,prod
 ```
 
-Only the selection is scaffolded and wired (model + base file always — the
-base is the replacement source). Each wired configuration gets its output
-directory (`builds/dev`, `builds/stag`, `builds/prod`) unless it already
-defines one, and `/builds` is appended to `.gitignore` once. Re-runs never
-overwrite files or duplicate configuration.
+Accepted names are `dev`, `stage` (or `stag`), and `prod`. `--project <name>`
+selects a project in a multi-project workspace; otherwise it uses
+`defaultProject` from `angular.json`, falling back to the first project.
+The schematic uses that project's `sourceRoot` (or `<root>/src`, then `src`).
 
-`ng add` creates (never overwrites) `src/environments/`:
+The model and development base file are always scaffolded. The selected
+environment files are created only if they do not already exist:
 
+```text
+src/environments/
+  environment.model.ts   # AppEnvironment extends BaseEnvironment
+  environment.ts         # development defaults; not replaced by the CLI
+  environment.staging.ts # only when stage is selected
+  environment.prod.ts    # only when prod is selected
 ```
-environment.model.ts   # AppEnvironment extends BaseEnvironment — extend it
-environment.ts         # dev defaults (used as-is by `dev`)
-environment.staging.ts # stage values (production: true)
-environment.prod.ts    # prod values
-```
-
-and wires `angular.json`: `production` gains its replacement if missing, and a
-`staging` configuration (copied from `production`) is created if absent.
-`development` intentionally gets no replacement (CLI standard). The app version
-is snapshotted from your `package.json` into each file (`0.0.0` fallback).
 
-## Usage pattern (app-owned)
+The generated contract and values have this shape:
 
 ```ts
 // environment.model.ts
@@ -55,14 +54,77 @@ import type { BaseEnvironment } from '@rivinia/env';
 export interface AppEnvironment extends BaseEnvironment {
   readonly apiUrl: string;
 }
+```
+
+```ts
+// environment.ts (generated development defaults)
+import type { AppEnvironment } from './environment.model';
+
+export const environment: AppEnvironment = {
+  production: false,
+  version: '1.2.3',
+  apiUrl: 'http://localhost:3000/api',
+};
+```
+
+Staging and production files have the same fields, with `production: true`;
+their generated API URLs are `https://staging.example.com/api` and
+`https://api.example.com/api`. Replace these example URLs and any other
+generated values with the app's real configuration.
+
+The schematic adds a file replacement to an existing `production`
+configuration when `prod` is selected. When `stage` is selected, it creates a
+`staging` configuration if needed (copying `production` settings except its
+`fileReplacements` and `outputPath`) and adds the staging replacement.
+`development` intentionally uses `environment.ts` directly. The schematic
+does not create a missing `production` or `development` configuration.
+
+For selected configurations that exist, it sets `outputPath` to
+`builds/dev`, `builds/stag`, or `builds/prod` only if no output path is
+already configured. If that adds an output path and a root `.gitignore`
+exists, `/builds` is appended once. Existing output paths and files are never
+overwritten; repeated runs do not duplicate replacements.
+
+The version in generated files is copied from the workspace-root
+`package.json` when each file is first created (`0.0.0` if unavailable).
+Since the schematic never overwrites existing files, update `version` in
+those environment files manually when releasing a new app version; rerunning
+`ng add` will not refresh it.
 
-// anywhere:
+## Use the selected environment
+
+Always import the base path from the app, not a stage/prod-specific file:
+
+```ts
+// src/app/trip.service.ts
+import { Injectable } from '@angular/core';
 import { environment } from '../environments/environment';
-fetch(`${environment.apiUrl}/trips`);
-console.log(environment.version); // e.g. footer, about page, cache keys
+
+@Injectable({ providedIn: 'root' })
+export class TripService {
+  readonly apiUrl = environment.apiUrl;
+}
 ```
 
-Re-run the schematic (or edit by hand) when the app version changes.
+The Angular CLI replaces `environment.ts` for the selected build
+configuration. For example:
+
+```bash
+ng build --configuration development
+ng build --configuration staging
+ng build --configuration production
+```
+
+The generated files are compile-time configuration, not secrets: values
+included in a browser build are visible to its users. `BaseEnvironment`
+requires only readonly `production: boolean` and `version: string`; extend
+AppEnvironment with the fields your app needs.
+
+## Public API
+
+| Export            | Kind | Purpose                                                                |
+| ----------------- | ---- | ---------------------------------------------------------------------- |
+| `BaseEnvironment` | type | Required `production` and `version` fields for app environment models. |
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rivinia/env",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Typed application environments for Angular (dev/staging/prod) with an ng-add schematic.",
   "keywords": [
     "angular",