@rivinia/env 0.2.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.2.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: development / staging / production
+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 staging,production
+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         # development defaults (used as-is by `development`)
-environment.staging.ts # staging values (production: true)
-environment.prod.ts    # production 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.2.0",
+  "version": "0.3.1",
   "description": "Typed application environments for Angular (dev/staging/prod) with an ng-add schematic.",
   "keywords": [
     "angular",

package/schematics/collection.json

@@ -2,7 +2,7 @@
   "$schema": "../../../node_modules/@angular-devkit/schematics/collection-schema.json",
   "schematics": {
     "ng-add": {
-      "description": "Scaffold typed environment files and wire dev/staging/production configurations.",
+      "description": "Scaffold typed environment files and wire dev/stage/prod configurations.",
       "factory": "./ng-add/index.cjs#ngAdd",
       "schema": "./ng-add/schema.json"
     }

package/schematics/ng-add/index.cjs

@@ -14,19 +14,25 @@ export interface AppEnvironment extends BaseEnvironment {
   readonly apiUrl: string;
 }
 `;
-const ALL_ENVIRONMENTS = ['development', 'staging', 'production'];
+const ALL_ENVIRONMENTS = ['dev', 'stage', 'prod'];
 /** Short aliases users actually type (`prod`, `dev`, `stag`). */
 const ENVIRONMENT_ALIASES = {
-    dev: 'development',
-    prod: 'production',
-    stag: 'staging',
-    stage: 'staging',
+    dev: 'dev',
+    prod: 'prod',
+    stag: 'stage',
+    stage: 'stage',
 };
 /** Output directory short names: builds/dev, builds/prod, builds/stag. */
 const OUTPUT_DIR = {
-    development: 'builds/dev',
-    staging: 'builds/stag',
-    production: 'builds/prod',
+    dev: 'builds/dev',
+    stage: 'builds/stag',
+    prod: 'builds/prod',
+};
+/** Maps an environment name to its Angular CLI configuration name. */
+const CONFIG_NAME = {
+    dev: 'development',
+    stage: 'staging',
+    prod: 'production',
 };
 const fileDefs = (sourceRoot, selected) => {
     const files = [
@@ -44,7 +50,7 @@ const fileDefs = (sourceRoot, selected) => {
                 `};\n`,
         },
     ];
-    if (selected.includes('staging')) {
+    if (selected.includes('stage')) {
         files.push({
             name: `${sourceRoot}/environments/environment.staging.ts`,
             content: (version) => `import type { AppEnvironment } from './environment.model';\n\n` +
@@ -56,7 +62,7 @@ const fileDefs = (sourceRoot, selected) => {
                 `};\n`,
         });
     }
-    if (selected.includes('production')) {
+    if (selected.includes('prod')) {
         files.push({
             name: `${sourceRoot}/environments/environment.prod.ts`,
             content: (version) => `import type { AppEnvironment } from './environment.model';\n\n` +
@@ -105,11 +111,9 @@ function ngAdd(options) {
         const unknown = [...new Set(cleaned)].filter((e) => !ALL_ENVIRONMENTS.includes(e));
         if (unknown.length > 0) {
             throw new schematics_1.SchematicsException(`[rivinia/env] unknown environment(s): ${unknown.join(', ')}. ` +
-                `Choose from development (dev), staging (stag), production (prod).`);
+                `Choose from dev, stage (stag), prod.`);
         }
-        const selected = cleaned.length > 0
-            ? [...new Set(cleaned)]
-            : [...ALL_ENVIRONMENTS];
+        const selected = cleaned.length > 0 ? [...new Set(cleaned)] : [...ALL_ENVIRONMENTS];
         const configsSnapshot = () => JSON.stringify(project.architect?.build?.configurations ?? null);
         const configsBefore = configsSnapshot();
         let created = 0;
@@ -122,13 +126,13 @@ function ngAdd(options) {
             tree.create(path, file.content(version));
             created++;
         }
-        if (selected.includes('production')) {
+        if (selected.includes('prod')) {
             ensureReplacement(tree, angular, name, 'production', {
                 replace: `${sourceRoot}/environments/environment.ts`,
                 with: `${sourceRoot}/environments/environment.prod.ts`,
             });
         }
-        if (selected.includes('staging')) {
+        if (selected.includes('stage')) {
             ensureStaging(tree, angular, name, sourceRoot, context);
         }
         ensureOutputPaths(tree, angular, name, selected, context);
@@ -224,7 +228,8 @@ function ensureOutputPaths(tree, angular, name, selected, context) {
     const configurations = getConfigurations(angular, name);
     let touched = false;
     for (const env of selected) {
-        const target = configurations[env];
+        const configName = CONFIG_NAME[env];
+        const target = configurations[configName];
         if (!target || 'outputPath' in target)
             continue;
         target['outputPath'] = OUTPUT_DIR[env];

package/schematics/ng-add/schema.json

@@ -6,23 +6,35 @@
   "properties": {
     "environments": {
       "type": ["array", "string"],
-      "description": "Which environments to scaffold and wire: array, or comma-separated string on the CLI (--environments staging,production). Model + base file always. Omit for all three.",
-      "default": ["development", "staging", "production"],
-      "items": { "type": "string", "enum": ["development", "staging", "production", "dev", "prod", "stag", "stage"] },
+      "description": "Which environments to scaffold and wire: array, or comma-separated string on the CLI (--environments stage,prod). Model + base file always. Omit for all three.",
+      "default": ["dev", "stage", "prod"],
+      "items": {
+        "type": "string",
+        "enum": ["dev", "stage", "prod", "stag"]
+      },
       "x-prompt": {
         "message": "Which environments should ng-add scaffold and wire?",
         "type": "list",
         "multiselect": true,
         "items": [
-          { "value": "development", "label": "development — base file, no replacement" },
-          { "value": "staging", "label": "staging — staging file + configuration" },
-          { "value": "production", "label": "production — prod file + replacement" }
+          {
+            "value": "dev",
+            "label": "dev \u2014 base file, no replacement"
+          },
+          {
+            "value": "stage",
+            "label": "stage \u2014 staging file + configuration"
+          },
+          {
+            "value": "prod",
+            "label": "prod \u2014 prod file + replacement"
+          }
         ]
       }
     },
     "project": {
       "type": "string",
-      "description": "Angular CLI project name — only for multi-app workspaces. Defaults to the workspace default project.",
+      "description": "Angular CLI project name \u2014 only for multi-app workspaces. Defaults to the workspace default project.",
       "default": ""
     }
   },