@rivinia/env 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,69 @@
-# Temporary Holding Version
+# @rivinia/env
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![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.
+
+- Version: **0.2.0**
+- Requires: nothing at runtime (types only). Schematic runs under Angular CLI 22+.
+
+## Install
+
+```bash
+npm install @rivinia/env
+ng add @rivinia/env   # multi-select: development / staging / production
+```
+
+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 staging,production
+```
+
+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
+```
+
+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)
+
+```ts
+// environment.model.ts
+import type { BaseEnvironment } from '@rivinia/env';
+
+export interface AppEnvironment extends BaseEnvironment {
+  readonly apiUrl: string;
+}
+
+// anywhere:
+import { environment } from '../environments/environment';
+fetch(`${environment.apiUrl}/trips`);
+console.log(environment.version); // e.g. footer, about page, cache keys
+```
+
+Re-run the schematic (or edit by hand) when the app version changes.
+
+## License
+
+MIT.

package/package.json

@@ -1,6 +1,29 @@
 {
   "name": "@rivinia/env",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "Typed application environments for Angular (dev/staging/prod) with an ng-add schematic.",
+  "keywords": [
+    "angular",
+    "environment",
+    "configuration",
+    "typescript"
+  ],
+  "license": "MIT",
+  "sideEffects": false,
+  "schematics": "./schematics/collection.json",
+  "module": "fesm2022/rivinia-env.mjs",
+  "typings": "types/rivinia-env.d.ts",
+  "exports": {
+    "./package.json": {
+      "default": "./package.json"
+    },
+    ".": {
+      "types": "./types/rivinia-env.d.ts",
+      "default": "./fesm2022/rivinia-env.mjs"
+    }
+  },
+  "type": "module",
+  "dependencies": {
+    "tslib": "^2.3.0"
+  }
 }

package/schematics/collection.json

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

package/schematics/ng-add/index.cjs

@@ -0,0 +1,262 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ngAdd = ngAdd;
+const schematics_1 = require("@angular-devkit/schematics");
+const MODEL_FILE = `import type { BaseEnvironment } from '@rivinia/env';
+
+/**
+ * Application environment contract. Extend with your own fields
+ * (apiUrl, keys, feature flags, …) — nothing else in the app should
+ * import environment values except through this type.
+ */
+export interface AppEnvironment extends BaseEnvironment {
+  /** Base URL for API calls (per-environment value below). */
+  readonly apiUrl: string;
+}
+`;
+const ALL_ENVIRONMENTS = ['development', 'staging', 'production'];
+/** Short aliases users actually type (`prod`, `dev`, `stag`). */
+const ENVIRONMENT_ALIASES = {
+    dev: 'development',
+    prod: 'production',
+    stag: 'staging',
+    stage: 'staging',
+};
+/** Output directory short names: builds/dev, builds/prod, builds/stag. */
+const OUTPUT_DIR = {
+    development: 'builds/dev',
+    staging: 'builds/stag',
+    production: 'builds/prod',
+};
+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('staging')) {
+        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('production')) {
+        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.
+ *
+ * - 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).
+ * - App version is snapshotted from the app's `package.json` (`0.0.0` fallback).
+ */
+function ngAdd(options) {
+    return (tree, context) => {
+        const workspace = readWorkspace(tree, context, options.project);
+        if (!workspace)
+            return tree;
+        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 development (dev), staging (stag), production (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, selected)) {
+            const path = `/${file.name}`;
+            if (tree.exists(path)) {
+                context.logger.info(`[rivinia/env] exists, skipped: ${path}`);
+                continue;
+            }
+            tree.create(path, file.content(version));
+            created++;
+        }
+        if (selected.includes('production')) {
+            ensureReplacement(tree, angular, name, 'production', {
+                replace: `${sourceRoot}/environments/environment.ts`,
+                with: `${sourceRoot}/environments/environment.prod.ts`,
+            });
+        }
+        if (selected.includes('staging')) {
+            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');
+        }
+        context.logger.info(`[rivinia/env] ${created} file(s) created, configurations wired for '${name}'.`);
+        return tree;
+    };
+}
+function readWorkspace(tree, context, requested) {
+    let angular;
+    try {
+        const raw = tree.read('/angular.json')?.toString('utf-8');
+        if (!raw)
+            throw new schematics_1.SchematicsException('angular.json not found.');
+        angular = JSON.parse(raw);
+    }
+    catch (error) {
+        context.logger.warn(`[rivinia/env] cannot read angular.json (${error instanceof Error ? error.message : error}) — skipping.`);
+        return null;
+    }
+    const names = Object.keys(angular.projects ?? {});
+    if (names.length === 0) {
+        context.logger.warn('[rivinia/env] no projects in angular.json — skipping.');
+        return null;
+    }
+    // NOTE: the schema default for `project` is "" (engine-filled), so only a
+    // non-empty value counts as an explicit request. (`??` alone would honor "".)
+    const name = requested && requested.length > 0
+        ? requested
+        : angular.defaultProject && typeof angular.defaultProject === 'string'
+            ? angular.defaultProject
+            : names[0];
+    const project = angular.projects?.[name];
+    if (!project) {
+        context.logger.warn(`[rivinia/env] project '${name}' not found — skipping.`);
+        return null;
+    }
+    return { name, project, angular };
+}
+function readAppVersion(tree) {
+    try {
+        const raw = tree.read('/package.json')?.toString('utf-8');
+        if (!raw)
+            return '0.0.0';
+        const parsed = JSON.parse(raw);
+        return typeof parsed.version === 'string' && parsed.version.length > 0
+            ? parsed.version
+            : '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+}
+function getConfigurations(angular, name) {
+    const project = angular.projects?.[name];
+    if (!project)
+        throw new schematics_1.SchematicsException(`[rivinia/env] project '${name}' not found.`);
+    project.architect ??= {};
+    project.architect.build ??= {};
+    const build = project.architect.build;
+    build.configurations ??= {};
+    return build.configurations;
+}
+function ensureReplacement(tree, angular, name, configuration, entry) {
+    if (!tree.exists('/angular.json'))
+        return;
+    const configurations = getConfigurations(angular, name);
+    const target = configurations[configuration];
+    if (!target)
+        return; // never create production/development for the user
+    const list = target['fileReplacements'];
+    if (!Array.isArray(list)) {
+        target['fileReplacements'] = [{ ...entry }];
+        return;
+    }
+    const exists = list.some((item) => typeof item === 'object' &&
+        item !== null &&
+        item['replace'] === entry.replace &&
+        item['with'] === entry.with);
+    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 target = configurations[env];
+        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;
+    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', {
+        replace: `${sourceRoot}/environments/environment.ts`,
+        with: `${sourceRoot}/environments/environment.staging.ts`,
+    });
+}

package/schematics/ng-add/schema.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "http://json-schema.org/schema",
+  "$id": "rivinia-env-ng-add",
+  "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 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"] },
+      "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" }
+        ]
+      }
+    },
+    "project": {
+      "type": "string",
+      "description": "Angular CLI project name — only for multi-app workspaces. Defaults to the workspace default project.",
+      "default": ""
+    }
+  },
+  "required": []
+}

package/types/rivinia-env.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Minimal contract every Rivinia-style environment file satisfies.
+ * Applications extend it with their own fields (apiUrl, keys, …) — the
+ * library never dictates field names beyond these two.
+ */
+interface BaseEnvironment {
+  /** `true` for production-like builds (staging included). */
+  readonly production: boolean;
+  /**
+   * Application version, snapshotted from the app's `package.json` when the
+   * files are scaffolded. Re-run the schematic or edit by hand on release.
+   */
+  readonly version: string;
+}
+export type { BaseEnvironment };