@rivinia/env 0.1.0 → 0.3.0

package/README.md

@@ -8,23 +8,37 @@ Typed application environments for Angular: dev/staging/prod file layout, a
 files and wires the build configurations. Zero runtime code — environments are
 build-time constants; this package ships types plus setup tooling only.
 
-- Version: **0.1.0**
+- Version: **0.3.0**
 - Requires: nothing at runtime (types only). Schematic runs under Angular CLI 22+.
 
 ## Install
 
 ```bash
 npm install @rivinia/env
-ng add @rivinia/env
+ng add @rivinia/env   # multi-select: dev / stage / prod
 ```
 
+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`):
+
+```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.
+
 `ng add` creates (never overwrites) `src/environments/`:
 
 ```
 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
+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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rivinia/env",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "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,38 +14,67 @@ export interface AppEnvironment extends BaseEnvironment {
   readonly apiUrl: string;
 }
 `;
-const fileDefs = (sourceRoot) => [
-    { name: `${sourceRoot}/environments/environment.model.ts`, content: () => MODEL_FILE },
-    {
-        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` +
-            `export const environment: AppEnvironment = {\n` +
-            `  production: false,\n` +
-            `  version: '${version}',\n` +
-            `  apiUrl: 'http://localhost:3000/api',\n` +
-            `};\n`,
-    },
-    {
-        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` +
-            `export const environment: AppEnvironment = {\n` +
-            `  production: true,\n` +
-            `  version: '${version}',\n` +
-            `  apiUrl: 'https://staging.example.com/api',\n` +
-            `};\n`,
-    },
-    {
-        name: `${sourceRoot}/environments/environment.prod.ts`,
-        content: (version) => `import type { AppEnvironment } from './environment.model';\n\n` +
-            `export const environment: AppEnvironment = {\n` +
-            `  production: true,\n` +
-            `  version: '${version}',\n` +
-            `  apiUrl: 'https://api.example.com/api',\n` +
-            `};\n`,
-    },
-];
+const ALL_ENVIRONMENTS = ['dev', 'stage', 'prod'];
+/** Short aliases users actually type (`prod`, `dev`, `stag`). */
+const ENVIRONMENT_ALIASES = {
+    dev: 'dev',
+    prod: 'prod',
+    stag: 'stage',
+    stage: 'stage',
+};
+/** Output directory short names: builds/dev, builds/prod, builds/stag. */
+const OUTPUT_DIR = {
+    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 = [
+        { 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).
+        {
+            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` +
+                `export const environment: AppEnvironment = {\n` +
+                `  production: false,\n` +
+                `  version: '${version}',\n` +
+                `  apiUrl: 'http://localhost:3000/api',\n` +
+                `};\n`,
+        },
+    ];
+    if (selected.includes('stage')) {
+        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` +
+                `export const environment: AppEnvironment = {\n` +
+                `  production: true,\n` +
+                `  version: '${version}',\n` +
+                `  apiUrl: 'https://staging.example.com/api',\n` +
+                `};\n`,
+        });
+    }
+    if (selected.includes('prod')) {
+        files.push({
+            name: `${sourceRoot}/environments/environment.prod.ts`,
+            content: (version) => `import type { AppEnvironment } from './environment.model';\n\n` +
+                `export const environment: AppEnvironment = {\n` +
+                `  production: true,\n` +
+                `  version: '${version}',\n` +
+                `  apiUrl: 'https://api.example.com/api',\n` +
+                `};\n`,
+        });
+    }
+    return files;
+};
 /**
  * `ng add @rivinia/env` — scaffolds typed environment files and wires
  * development/staging/production configurations with file replacements.
@@ -66,10 +95,29 @@ function ngAdd(options) {
         const { name, project, angular } = workspace;
         const sourceRoot = project.sourceRoot ?? (project.root ? `${project.root}/src` : 'src');
         const version = readAppVersion(tree);
+        // Empty selection (or engine default) means everything — same as --defaults.
+        // Accepts arrays (prompt/programmatic) and comma strings (CLI flags), with
+        // short aliases (dev/prod/stag/stage) normalized before validation.
+        const rawSelected = options.environments;
+        const asArray = Array.isArray(rawSelected)
+            ? [...rawSelected]
+            : typeof rawSelected === 'string'
+                ? rawSelected.split(',')
+                : [];
+        const cleaned = asArray
+            .map((e) => e.trim().toLowerCase())
+            .filter((e) => e.length > 0)
+            .map((e) => ENVIRONMENT_ALIASES[e] ?? e);
+        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 dev, stage (stag), prod.`);
+        }
+        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;
-        for (const file of fileDefs(sourceRoot)) {
+        for (const file of fileDefs(sourceRoot, selected)) {
             const path = `/${file.name}`;
             if (tree.exists(path)) {
                 context.logger.info(`[rivinia/env] exists, skipped: ${path}`);
@@ -78,11 +126,16 @@ function ngAdd(options) {
             tree.create(path, file.content(version));
             created++;
         }
-        ensureReplacement(tree, angular, name, 'production', {
-            replace: `${sourceRoot}/environments/environment.ts`,
-            with: `${sourceRoot}/environments/environment.prod.ts`,
-        });
-        ensureStaging(tree, angular, name, sourceRoot, context);
+        if (selected.includes('prod')) {
+            ensureReplacement(tree, angular, name, 'production', {
+                replace: `${sourceRoot}/environments/environment.ts`,
+                with: `${sourceRoot}/environments/environment.prod.ts`,
+            });
+        }
+        if (selected.includes('stage')) {
+            ensureStaging(tree, angular, name, sourceRoot, context);
+        }
+        ensureOutputPaths(tree, angular, name, selected, context);
         if (created > 0 || configsSnapshot() !== configsBefore) {
             tree.overwrite('/angular.json', JSON.stringify(angular, null, 2) + '\n');
         }
@@ -164,6 +217,37 @@ function ensureReplacement(tree, angular, name, configuration, entry) {
     if (!exists)
         list.push({ ...entry });
 }
+/**
+ * Points each selected configuration at its build directory
+ * (builds/dev, builds/stag, builds/prod) — but only when the app has not
+ * customized `outputPath` already. Never overwrites user output locations.
+ */
+function ensureOutputPaths(tree, angular, name, selected, context) {
+    if (!tree.exists('/angular.json'))
+        return;
+    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;
+    }
+    if (touched)
+        ensureGitignore(tree, context);
+}
+/** Appends `/builds` to the app .gitignore once (build outputs don't commit). */
+function ensureGitignore(tree, context) {
+    if (!tree.exists('/.gitignore'))
+        return;
+    const content = tree.read('/.gitignore')?.toString('utf-8') ?? '';
+    if (/(^|\n)\/*builds\/?(\n|$)/.test(content))
+        return;
+    tree.overwrite('/.gitignore', content.replace(/\s*$/, '\n') + '/builds\n');
+    context.logger.info('[rivinia/env] added /builds to .gitignore.');
+}
 function ensureStaging(tree, angular, name, sourceRoot, context) {
     if (!tree.exists('/angular.json'))
         return;

package/schematics/ng-add/schema.json

@@ -4,9 +4,37 @@
   "title": "Rivinia env ng-add options",
   "type": "object",
   "properties": {
+    "environments": {
+      "type": ["array", "string"],
+      "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": "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": ""
     }
   },