@rivinia/env 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,55 @@
-# 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.1.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` 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.1.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,183 @@
+"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 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`,
+    },
+];
+/**
+ * `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);
+        const configsSnapshot = () => JSON.stringify(project.architect?.build?.configurations ?? null);
+        const configsBefore = configsSnapshot();
+        let created = 0;
+        for (const file of fileDefs(sourceRoot)) {
+            const path = `/${file.name}`;
+            if (tree.exists(path)) {
+                context.logger.info(`[rivinia/env] exists, skipped: ${path}`);
+                continue;
+            }
+            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 (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 });
+}
+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,14 @@
+{
+  "$schema": "http://json-schema.org/schema",
+  "$id": "rivinia-env-ng-add",
+  "title": "Rivinia env ng-add options",
+  "type": "object",
+  "properties": {
+    "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 };