feat: add CONTRIBUTING.md and update project documentation

sharjeelyunus · sharjeelyunus · commit c5b9015422e8 · 2026-04-03T01:02:43.000+05:00
- Introduced a new CONTRIBUTING.md file to guide contributors on local development, project layout, and release processes.
- Updated README to reference the new CONTRIBUTING.md for development setup and project structure.
- Modified package.json to include the repository URL and adjusted publish configuration for npm.
- Enhanced release workflow to support trusted publishing with OIDC for npm.
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -19,6 +19,7 @@ jobs:
 
     permissions:
       contents: write
+      id-token: write
 
     steps:
       - name: Checkout repository
@@ -68,6 +69,11 @@ jobs:
           generate_release_notes: true
 
       - name: Publish to GitHub Packages
-        run: npm publish
+        run: npm publish --registry=https://npm.pkg.github.com
         env:
           NODE_AUTH_TOKEN: ${{ secrets.GH_PACKAGES_TOKEN }}
+
+      - name: Publish to npm (trusted publishing / OIDC)
+        run: |
+          npm install -g npm@latest
+          npm publish --registry=https://registry.npmjs.org --provenance
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,77 @@
+# Contributing to Ensemble CLI
+
+This document is for people working on the CLI itself. If you only use `ensemble` in your projects, see the [README](README.md).
+
+## Local development
+
+```bash
+git clone https://github.com/EnsembleUI/ensemble-cli
+cd ensemble-cli
+npm install
+npm run build
+npm link   # optional: use the CLI globally from this checkout
+```
+
+### Scripts
+
+| Command                | Description                   |
+| ---------------------- | ----------------------------- |
+| `npm run dev`          | Run the CLI with `ts-node`    |
+| `npm run build`        | Compile TypeScript to `dist/` |
+| `npm test`             | Run the test suite (Vitest)   |
+| `npm run test:watch`   | Tests in watch mode           |
+| `npm run lint`         | ESLint                        |
+| `npm run format`       | Prettier (write)              |
+| `npm run format:check` | Prettier (check only)         |
+
+## Project layout
+
+```text
+src/
+├── auth/       # Session & token handling
+├── cloud/      # Firestore API client
+├── commands/   # CLI commands
+├── config/     # Global & project config
+├── core/       # Domain logic (app collection, DTOs, diff)
+└── lib/        # Shared utilities
+tests/
+├── auth/       # Auth unit tests (token, session)
+├── cloud/      # Firestore client tests
+├── config/     # Config tests (project, global)
+├── core/       # Core unit tests (appCollector, bundleDiff, buildDocuments)
+└── lib/        # Utility tests (spinner)
+```
+
+## Advanced: Firebase and backend configuration
+
+Normal installs use Ensemble’s cloud endpoints and a Firebase API key that is **injected at build time** (`npm run build` reads `ENSEMBLE_FIREBASE_API_KEY` via `scripts/inject-env.mjs`). You typically set that only when building or testing the CLI from source.
+
+You can override the defaults at **runtime** (forks, custom backends, local integration tests):
+
+| Variable                    | Default                                 | Purpose                                       |
+| --------------------------- | --------------------------------------- | --------------------------------------------- |
+| `ENSEMBLE_FIREBASE_PROJECT` | `ensemble-web-studio`                   | Firestore / Firebase project ID               |
+| `ENSEMBLE_AUTH_BASE_URL`    | `https://studio.ensembleui.com/sign-in` | Browser sign-in page used by `ensemble login` |
+| `ENSEMBLE_FIREBASE_API_KEY` | Injected placeholder in `dist/`         | Firebase Web API key (token refresh, etc.)    |
+
+If the built-in key is missing or wrong, token refresh may fail with a message to set `ENSEMBLE_FIREBASE_API_KEY`.
+
+## Releases
+
+GitHub Actions bumps the version, tags, creates a GitHub Release, and publishes `@ensembleui/cli` to **GitHub Packages** and \*\*npm`.
+
+**npm: trusted publishing (OIDC)** — Pushes to [registry.npmjs.org](https://www.npmjs.com/) use [trusted publishing](https://docs.npmjs.com/trusted-publishers): short-lived tokens via GitHub OIDC, no `NPM_TOKEN` secret. On npm → **Package** → **Settings** → **Trusted publishing**, add **GitHub Actions** with repository `EnsembleUI/ensemble-cli` and workflow filename **`release.yml`** (must match exactly, including `.yml`). `package.json` must keep a correct [`repository`](https://docs.npmjs.com/trusted-publishers) URL for this repo.
+
+**Repository secrets**
+
+| Secret                      | Purpose                                   |
+| --------------------------- | ----------------------------------------- |
+| `GH_PACKAGES_TOKEN`         | Publish to GitHub Packages                |
+| `ENSEMBLE_FIREBASE_API_KEY` | Used at build time when compiling the CLI |
+
+To cut a release: GitHub → **Actions** → **Release (bump version, tag, publish)** → choose `patch`, `minor`, or `major`.
+
+## Security notes (maintainers)
+
+- GitHub tokens used in `.npmrc` for GitHub Packages must not be committed; use least-privilege scopes (`read:packages` for consumers) and rotate if exposed.
+- Shell and subprocess usage in the CLI (`npm view`, `npm install -g`, `open`/`start`/`xdg-open`) should stay **static string literals** so user input cannot be injected into shells.
diff --git a/README.md b/README.md
@@ -4,39 +4,11 @@ CLI for logging in, initializing, and pushing app definitions to the Ensemble cl
 
 ## Installation
 
-### From GitHub Packages (recommended)
-
-#### Option 1: One-shot install script
-
-Run this command once (it will prompt for a GitHub token with `read:packages`):
-
 ```bash
-curl -fsSL https://raw.githubusercontent.com/EnsembleUI/ensemble-cli/main/scripts/install-ensemble-cli.sh | bash
+npm install -g @ensembleui/cli
 ```
 
-#### Option 2: Manual setup
-
-1. **Configure npm to use GitHub Packages for `@ensembleui`:**
-
-   Add this to your `~/.npmrc` (global) or project `.npmrc`:
-
-   ```bash
-   @ensembleui:registry=https://npm.pkg.github.com
-   //npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN
-   ```
-
-   Your GitHub token must have at least the `read:packages` scope. Treat this token as a **secret**:
-   - Do not commit `.npmrc` to source control.
-   - Prefer the minimum required scopes (typically `read:packages`).
-   - Rotate the token promptly if you suspect it has been exposed.
-
-2. **Install the CLI globally:**
-
-   ```bash
-   npm install -g @ensembleui/cli
-   ```
-
-3. **Use the CLI:**
+### Use the CLI
 
 ```bash
 ensemble login
@@ -50,25 +22,6 @@ ensemble add
 ensemble update
 ```
 
-### Development setup
-
-```bash
-npm install
-npm run build
-npm link   # link globally for local development
-```
-
-## Releasing (GitHub Packages)
-
-This repo uses GitHub Actions to:
-
-- bump the version in `package.json`
-- create a git tag (e.g. `v0.1.0`)
-- create a GitHub Release
-- publish `@ensembleui/cli` to GitHub Packages
-
-To release a new version, go to GitHub → Actions → run the workflow **Release (bump version, tag, publish)** and choose `patch`, `minor`, or `major`.
-
 ## Commands
 
 | Command            | Description                                                               |
@@ -201,25 +154,26 @@ Without `-y`, both commands refuse to run when not attached to a TTY and exit wi
 
 > **Tip:** In CI, prefer `ensemble push --dry-run` / `ensemble pull --dry-run` in a validation job, and use `-y` only when you are ready to apply changes.
 
-## Environment Variables
+## Environment variables
+
+For everyday use you do not need to set anything beyond what is described in [CI/CD](#cicd) (`ENSEMBLE_TOKEN` in automation).
+
+**Optional:**
 
 | Variable                          | Purpose                                                                                                      |
 | --------------------------------- | ------------------------------------------------------------------------------------------------------------ |
-| `ENSEMBLE_TOKEN`                  | Token for CI; the CLI uses it instead of global config. Get it with `ensemble token` after `ensemble login`. |
-| `ENSEMBLE_FIREBASE_PROJECT`       | Firestore project (default: `ensemble-web-studio`)                                                           |
-| `ENSEMBLE_AUTH_BASE_URL`          | Auth sign-in URL (default: `https://studio.ensembleui.com/sign-in`)                                          |
-| `ENSEMBLE_FIREBASE_API_KEY`       | Firebase API key used by the CLI (injected at build time; can be overridden for custom environments/tests).  |
-| `ENSEMBLE_VERBOSE` / `VERBOSE`    | When set to a truthy value (`1`, `true`, `yes`, `on`), enables verbose mode for commands that support it.    |
-| `DEBUG`                           | When set to a truthy value (`1`, `true`, `yes`, `on`), enables debug output (same as passing `--debug`).     |
-| `CI` / `ENSEMBLE_NO_UPDATE_CHECK` | When set to a truthy value, disables the automatic version check at startup.                                 |
+| `ENSEMBLE_VERBOSE` / `VERBOSE`    | Truthy values (`1`, `true`, `yes`, `on`) enable verbose mode where supported.                                |
+| `DEBUG`                           | Same idea as global `--debug` (truthy values as above).                                                      |
+| `CI` / `ENSEMBLE_NO_UPDATE_CHECK` | Truthy values disable the startup “new version available” check (useful in CI or when you want a quiet run). |
+
+Firebase project, auth URL, and API key are fixed for the published CLI (the API key is injected when the package is built). You only need to think about those when [developing the CLI](CONTRIBUTING.md#advanced-firebase-and-backend-configuration).
 
 ## Security considerations
 
 - **Secrets and tokens**
   - `ENSEMBLE_TOKEN` (CI token) is a long-lived Firebase refresh token. Store it only in CI secret stores (e.g. GitHub Actions secrets), never in source control or logs.
   - The local auth file at `~/.ensemble/cli-config.json` contains ID tokens and refresh tokens for your user account. Anyone who can read this file can act as you in the CLI.
   - The CLI now writes `~/.ensemble/cli-config.json` with user-only permissions on POSIX systems (`0700` directory, `0600` file), but you should still treat it as sensitive.
-  - GitHub tokens used in `.npmrc` (for GitHub Packages) must not be committed or shared; use least-privilege scopes (`read:packages`) and rotate if exposed.
 - **Auth and authorization model**
   - Authentication is handled via browser sign-in to Ensemble (backed by Firebase). The CLI stores tokens locally and refreshes them via Firebase’s secure token API.
   - Authorization is enforced server-side using Firestore security rules and app-level roles (`write`/`owner`). The CLI passes your Firebase ID token as a Bearer token and does not make its own trust decisions beyond handling HTTP responses.
@@ -230,34 +184,9 @@ Without `-y`, both commands refuse to run when not attached to a TTY and exit wi
   - All shell commands used by the CLI (`npm view`, `npm install -g`, `open`/`start`/`xdg-open`) are static string literals and must remain so to avoid shell injection.
   - Firestore/network debug hooks intentionally avoid logging Authorization headers or raw tokens; custom debug handlers must preserve this invariant.
 
-## Project Structure
-
-```text
-src/
-├── auth/       # Session & token handling
-├── cloud/      # Firestore API client
-├── commands/   # CLI commands
-├── config/     # Global & project config
-├── core/       # Domain logic (app collection, DTOs, diff)
-└── lib/        # Shared utilities
-tests/
-├── auth/       # Auth unit tests (token, session)
-├── cloud/      # Firestore client tests
-├── config/     # Config tests (project, global)
-├── core/       # Core unit tests (appCollector, bundleDiff, buildDocuments)
-└── lib/        # Utility tests (spinner)
-```
-
-## Development
+## Contributing
 
-```bash
-npm run dev        # Run with ts-node
-npm run build      # Compile TypeScript
-npm run test       # Run tests
-npm run test:watch # Run tests in watch mode
-npm run lint       # ESLint
-npm run format     # Prettier
-```
+See [CONTRIBUTING.md](CONTRIBUTING.md) for local development, tests, project layout, and the release workflow.
 
 ## License
 
diff --git a/package.json b/package.json
@@ -23,10 +23,15 @@
     "cli"
   ],
   "files": [
-    "dist"
+    "dist",
+    "README.md"
   ],
   "publishConfig": {
-    "registry": "https://npm.pkg.github.com"
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/EnsembleUI/ensemble-cli.git"
   },
   "license": "MIT",
   "type": "commonjs",
diff --git a/src/commands/update.ts b/src/commands/update.ts
@@ -7,17 +7,20 @@ export async function updateCommand(): Promise<void> {
   return new Promise((resolve) => {
     // IMPORTANT: This command string must remain a static literal and MUST NOT
     // interpolate user-controlled input to avoid shell injection risks.
-    const child = exec('npm install -g @ensembleui/cli', (error) => {
-      if (error) {
-        ui.error('Failed to update @ensembleui/cli automatically.');
-        ui.note('Please run the following command manually:');
-        // eslint-disable-next-line no-console
-        console.log('  npm install -g @ensembleui/cli');
-      } else {
-        ui.success('Successfully updated @ensembleui/cli to the latest version.');
+    const child = exec(
+      'npm install -g @ensembleui/cli --registry=https://registry.npmjs.org',
+      (error) => {
+        if (error) {
+          ui.error('Failed to update @ensembleui/cli automatically.');
+          ui.note('Please run the following command manually:');
+          // eslint-disable-next-line no-console
+          console.log('  npm install -g @ensembleui/cli --registry=https://registry.npmjs.org');
+        } else {
+          ui.success('Successfully updated @ensembleui/cli to the latest version.');
+        }
+        resolve();
       }
-      resolve();
-    });
+    );
 
     if (child.stdout) {
       child.stdout.pipe(process.stdout);
diff --git a/src/index.ts b/src/index.ts
@@ -225,7 +225,7 @@ function checkForUpdates(): void {
   // IMPORTANT: This command string must remain a static literal and MUST NOT
   // interpolate user-controlled input to avoid shell injection risks.
   exec(
-    'npm view @ensembleui/cli version --registry=https://npm.pkg.github.com',
+    'npm view @ensembleui/cli version --registry=https://registry.npmjs.org',
     (error, stdout) => {
       if (error) {
         return;
