@rivinia/env 0.3.0 → 0.3.2

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+.
+- Package version: **0.3.2**
+- 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,85 @@ import type { BaseEnvironment } from '@rivinia/env';
 export interface AppEnvironment extends BaseEnvironment {
   readonly apiUrl: string;
 }
+```
 
-// anywhere:
+```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 creates the short `dev`, `stag`, and `prod` build configurations
+for the selected environments, copying settings from the corresponding
+`development`, `staging`, or `production` configuration when one exists.
+Otherwise, it creates the short configuration with the required environment
+replacement when needed (`dev` uses the base file directly). It also wires
+existing legacy keys when present: `development`
+uses `environment.ts`, `staging` replaces it with
+`environment.staging.ts`, and `production` replaces it with
+`environment.prod.ts`. The short names are the recommended CLI commands; the
+legacy names remain available for existing scripts.
+
+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.
+
+## 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 { Service } from '@angular/core';
 import { environment } from '../environments/environment';
-fetch(`${environment.apiUrl}/trips`);
-console.log(environment.version); // e.g. footer, about page, cache keys
+
+@Service()
+export class TripService {
+  readonly apiUrl = environment.apiUrl;
+}
 ```
 
-Re-run the schematic (or edit by hand) when the app version changes.
+After `ng add @rivinia/env`, build with the short configuration names:
+
+```bash
+ng build --configuration dev
+ng build --configuration stag
+ng build --configuration prod
+```
+
+These are actual keys in `angular.json`, not Angular CLI aliases. If you
+maintain custom configurations, inspect the selected project's
+`architect.build.configurations` and ensure each key has the intended
+`fileReplacements`; `ng build --configuration` uses the key exactly as written.
+
+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.2",
   "description": "Typed application environments for Angular (dev/staging/prod) with an ng-add schematic.",
   "keywords": [
     "angular",

package/schematics/ng-add/index.cjs

@@ -28,8 +28,14 @@ const OUTPUT_DIR = {
     stage: 'builds/stag',
     prod: 'builds/prod',
 };
-/** Maps an environment name to its Angular CLI configuration name. */
+/** Public short configuration names used by `ng build --configuration`. */
 const CONFIG_NAME = {
+    dev: 'dev',
+    stage: 'stag',
+    prod: 'prod',
+};
+/** Existing long configuration names remain wired for compatibility. */
+const LEGACY_CONFIG_NAME = {
     dev: 'development',
     stage: 'staging',
     prod: 'production',
@@ -38,11 +44,11 @@ const fileDefs = (sourceRoot, selected) => {
     const files = [
         { name: `${sourceRoot}/environments/environment.model.ts`, content: () => MODEL_FILE },
         // The base file is always scaffolded: it is the `replace` source for
-        // prod/staging swaps (and what `development` uses directly).
+        // prod/stag swaps (and what dev uses directly).
         {
             name: `${sourceRoot}/environments/environment.ts`,
             content: (version) => `import type { AppEnvironment } from './environment.model';\n\n` +
-                `/** Development defaults. Used as-is by the \`development\` configuration. */\n` +
+                `/** Development defaults. Used as-is by the \`dev\` configuration. */\n` +
                 `export const environment: AppEnvironment = {\n` +
                 `  production: false,\n` +
                 `  version: '${version}',\n` +
@@ -54,7 +60,7 @@ const fileDefs = (sourceRoot, selected) => {
         files.push({
             name: `${sourceRoot}/environments/environment.staging.ts`,
             content: (version) => `import type { AppEnvironment } from './environment.model';\n\n` +
-                `/** Staging mirrors production. Wired via the \`staging\` configuration. */\n` +
+                `/** Staging mirrors production. Wired via the \`stag\` configuration. */\n` +
                 `export const environment: AppEnvironment = {\n` +
                 `  production: true,\n` +
                 `  version: '${version}',\n` +
@@ -77,14 +83,15 @@ const fileDefs = (sourceRoot, selected) => {
 };
 /**
  * `ng add @rivinia/env` — scaffolds typed environment files and wires
- * development/staging/production configurations with file replacements.
+ * dev/stag/prod configurations with file replacements.
  *
  * - Never overwrites existing files (each file skipped individually).
  * - Never removes user configuration: only ADDS missing fileReplacements
- *   (matched by replace+with pair) and creates a `staging` configuration
- *   (copied from `production` when present) if absent.
- * - `development` intentionally gets no replacement (CLI standard: it uses
- *   `environment.ts` directly).
+ *   (one per source file) and creates short configurations from their legacy
+ *   equivalents when absent.
+ * - `dev` intentionally gets no replacement (it uses `environment.ts`).
+ *   Existing `development`, `staging`, and `production` configurations remain
+ *   wired for compatibility.
  * - App version is snapshotted from the app's `package.json` (`0.0.0` fallback).
  */
 function ngAdd(options) {
@@ -127,14 +134,20 @@ function ngAdd(options) {
             created++;
         }
         if (selected.includes('prod')) {
-            ensureReplacement(tree, angular, name, 'production', {
+            ensureNamedConfig(tree, angular, name, 'prod', ['production'], context);
+            const replacement = {
                 replace: `${sourceRoot}/environments/environment.ts`,
                 with: `${sourceRoot}/environments/environment.prod.ts`,
-            });
+            };
+            ensureReplacement(tree, angular, name, 'prod', replacement);
+            ensureReplacement(tree, angular, name, 'production', replacement);
         }
         if (selected.includes('stage')) {
             ensureStaging(tree, angular, name, sourceRoot, context);
         }
+        if (selected.includes('dev')) {
+            ensureNamedConfig(tree, angular, name, 'dev', ['development'], context);
+        }
         ensureOutputPaths(tree, angular, name, selected, context);
         if (created > 0 || configsSnapshot() !== configsBefore) {
             tree.overwrite('/angular.json', JSON.stringify(angular, null, 2) + '\n');
@@ -204,18 +217,25 @@ function ensureReplacement(tree, angular, name, configuration, entry) {
     const configurations = getConfigurations(angular, name);
     const target = configurations[configuration];
     if (!target)
-        return; // never create production/development for the user
+        return;
     const list = target['fileReplacements'];
     if (!Array.isArray(list)) {
         target['fileReplacements'] = [{ ...entry }];
         return;
     }
-    const exists = list.some((item) => typeof item === 'object' &&
+    const matches = list
+        .map((item, index) => ({ item, index }))
+        .filter(({ item }) => typeof item === 'object' &&
         item !== null &&
-        item['replace'] === entry.replace &&
-        item['with'] === entry.with);
-    if (!exists)
+        item['replace'] === entry.replace);
+    if (matches.length === 0) {
         list.push({ ...entry });
+        return;
+    }
+    const firstIndex = matches[0].index;
+    list[firstIndex] = { ...entry };
+    for (const { index } of matches.slice(1).reverse())
+        list.splice(index, 1);
 }
 /**
  * Points each selected configuration at its build directory
@@ -228,12 +248,13 @@ function ensureOutputPaths(tree, angular, name, selected, context) {
     const configurations = getConfigurations(angular, name);
     let touched = false;
     for (const env of selected) {
-        const configName = CONFIG_NAME[env];
-        const target = configurations[configName];
-        if (!target || 'outputPath' in target)
-            continue;
-        target['outputPath'] = OUTPUT_DIR[env];
-        touched = true;
+        for (const configName of [CONFIG_NAME[env], LEGACY_CONFIG_NAME[env]]) {
+            const target = configurations[configName];
+            if (!target || 'outputPath' in target)
+                continue;
+            target['outputPath'] = OUTPUT_DIR[env];
+            touched = true;
+        }
     }
     if (touched)
         ensureGitignore(tree, context);
@@ -251,17 +272,28 @@ function ensureGitignore(tree, context) {
 function ensureStaging(tree, angular, name, sourceRoot, context) {
     if (!tree.exists('/angular.json'))
         return;
-    const configurations = getConfigurations(angular, name);
-    if (!configurations['staging']) {
-        const production = configurations['production'];
-        const copy = production && typeof production === 'object' ? { ...production } : {};
-        delete copy['fileReplacements'];
-        delete copy['outputPath'];
-        configurations['staging'] = copy;
-        context.logger.info('[rivinia/env] created `staging` configuration.');
-    }
-    ensureReplacement(tree, angular, name, 'staging', {
+    ensureNamedConfig(tree, angular, name, 'stag', ['staging', 'production'], context);
+    ensureNamedConfig(tree, angular, name, 'staging', ['stag', 'production'], context);
+    const replacement = {
         replace: `${sourceRoot}/environments/environment.ts`,
         with: `${sourceRoot}/environments/environment.staging.ts`,
-    });
+    };
+    ensureReplacement(tree, angular, name, 'stag', replacement);
+    ensureReplacement(tree, angular, name, 'staging', replacement);
+}
+function ensureNamedConfig(tree, angular, name, configuration, fallbacks, context) {
+    if (!tree.exists('/angular.json'))
+        return;
+    const configurations = getConfigurations(angular, name);
+    if (configurations[configuration])
+        return;
+    const source = fallbacks
+        .map((fallback) => configurations[fallback])
+        .find((candidate) => candidate && typeof candidate === 'object');
+    const copy = source
+        ? JSON.parse(JSON.stringify(source))
+        : {};
+    delete copy['outputPath'];
+    configurations[configuration] = copy;
+    context.logger.info(`[rivinia/env] created \`${configuration}\` configuration.`);
 }