heroku-dash 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ryan McGeary
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,230 @@
+# heroku-dash
+
+A keyboard-driven Heroku dashboard in your terminal, inspired by **gh-dash**.
+
+Run **`heroku dash`** inside a Git repository to open its Heroku pipeline. Browse teams, pipelines, and apps; inspect resources and settings; scale dynos; and manage config without leaving your terminal.
+
+## Installation
+
+Requires a current [Heroku CLI](https://devcenter.heroku.com/articles/heroku-cli), Node.js 22+, and an interactive terminal. The minimum terminal size is 80 × 24; 120 × 36 or larger is recommended.
+
+For the dashboard's icons, select a **[Nerd Font](https://www.nerdfonts.com/)** in your terminal settings. A **Nerd Font Mono** variant, such as **JetBrainsMono Nerd Font Mono** or **FiraCode Nerd Font Mono**, keeps icons aligned to the terminal grid. Missing or boxed icons usually mean the terminal is using an unpatched font.
+
+```sh
+heroku plugins:install heroku-dash
+heroku dash
+```
+
+The plugin is installed from [npm](https://www.npmjs.com/package/heroku-dash) directly through the Heroku CLI.
+
+Authentication uses your existing Heroku CLI login, including `HEROKU_API_KEY` when set. Run `heroku login` first if needed.
+
+Try the offline demo without making any Heroku requests:
+
+```sh
+heroku dash --demo
+```
+
+Update installed Heroku plugins:
+
+```sh
+heroku plugins:update
+```
+
+Uninstall this plugin:
+
+```sh
+heroku plugins:uninstall heroku-dash
+```
+
+## Usage
+
+```sh
+heroku dash                            # Detect the current repository's pipeline
+heroku dash --pipeline my-pipeline     # Pipeline name or ID
+heroku dash --app my-app               # App name or ID
+heroku dash --remote staging           # App attached to a specific Git remote
+heroku dash --team my-team             # Start in a team
+heroku dash --read-only                # Disable all remote changes
+heroku dash --refresh 60               # Refresh the current app every minute
+heroku dash --refresh 0                # Manual refresh only
+```
+
+`--app`, `--pipeline`, `--remote`, and `--team` are mutually exclusive. The default refresh interval is 30 seconds; nonzero intervals must be at least 10 seconds.
+
+### Repository detection
+
+1. Explicit flags take precedence.
+2. Detect Heroku HTTPS/SSH Git remotes, including named staging/production remotes and `heroku-accounts` SSH aliases. Look up each app's pipeline coupling.
+3. If the remotes resolve to one pipeline, open its **pipeline overview**, rather than choosing a deployment implicitly.
+4. Otherwise, match a pipeline to the **Git repository root directory name**, including when invoked from a subdirectory.
+5. A single remote app without a pipeline opens directly. If no match exists, start in the workspace browser.
+
+When remotes span multiple pipelines, the browser asks you to choose one. Use `--remote` to disambiguate. Duplicate pipeline names can be selected by ID with `--pipeline`.
+
+### Workspace
+
+The left sidebar browses teams, pipelines, or apps. Choosing a team scopes its pipelines and apps; **All teams / personal** clears the scope. Pipelines list apps ordered by stage. Open an app to see its seven views, with a selectable resource list above a scrollable details pane.
+
+The heading shows the resource hierarchy: **team › pipeline › app**, including when you open an app or pipeline directly. Personal resources use **Personal**, and apps without a pipeline use **No pipeline**. Opening a resource resolves its parents without changing the sidebar's team filter.
+
+Nerd Font icons identify teams, pipelines, apps, process types, databases, and the app views. **Green** indicates healthy/successful states, **amber** indicates pending states or maintenance, **red** indicates failures, and **gray** indicates inactive or unknown states. Config rows use a lock for masked values and an amber eye for revealed values. Status text remains visible alongside icons and colors.
+
+Pipeline stages are color-coded: **blue** development, **purple** review, **amber** staging, and **green** production. The active view and focused pane use Heroku purple. On narrower terminals, inactive tabs show their number and icon; the active tab keeps its name.
+
+While data is loading, an OpenCode-inspired purple scanner (`■` / `⬝`) sweeps back and forth in the status bar, with a fading trail and a brief pause at each turn. It updates every 40 ms alongside the operation in progress. It covers pipeline/app loads, config vars, workspace refreshes, and confirmed changes, and stops when the work finishes.
+
+| View | What you can do |
+| --- | --- |
+| **1 Overview** | Inspect app identity, team, region, stack, URLs, formation, and latest release |
+| **2 Resources** | Inspect process commands, desired quantity, dyno size, individual dyno states and ages; scale quantity and size |
+| **3 Add-ons** | Inspect services, plans, provisioning state, billing app, and local/shared attachments |
+| **4 Config** | View config keys; reveal or copy a selected value; create, replace, or delete variables |
+| **5 Settings** | Inspect domains, ACM state, buildpacks, region, stack, and space; toggle maintenance mode |
+| **6 Releases** | Inspect the latest 20 releases, including status, author, description, and timestamp |
+| **7 Metrics** | View current dyno health, desired/running counts by process, crashed/starting counts, dyno ages, and recent deployment outcomes |
+
+### Keyboard shortcuts
+
+| Key | Action |
+| --- | --- |
+| `t` / `p` / `a` | Browse teams / pipelines / apps |
+| `j` / `k`, `↑` / `↓` | Move selection, or scroll the focused details pane |
+| `Enter` | Open the selected item |
+| `Tab` / `Shift-Tab` | Focus the next / previous pane |
+| `/` | Filter sidebar names; submit an empty filter to clear |
+| `Esc` | Return to pipeline / workspace, clear a sidebar filter, or cancel a prompt |
+| `1`–`7` | Select an app view |
+| `h` / `l`, `[` / `]`, `←` / `→` | Previous / next app view |
+| `R` | Refresh the current app, pipeline, or workspace catalog |
+| `Ctrl-L` | Redraw the terminal |
+| `o` | Open the corresponding Heroku web dashboard page |
+| `?` | Show keyboard help |
+| `q` / `Ctrl-C` | Quit (`q` closes help; `Ctrl-C` also exits from input prompts) |
+
+App actions:
+
+| Key | View | Action |
+| --- | --- | --- |
+| `s` | Resources | Scale the selected process row (server icon, `[s] scale`); enter quantity and dyno size |
+| `v` | Config | Reveal / hide the selected value |
+| `y` | Config | Copy the selected variable's full value to the clipboard, even when masked |
+| `e` | Config | Replace the selected variable's value |
+| `n` | Config | Create a variable (or explicitly replace an existing key) |
+| `d` | Config | Delete the selected variable |
+| `m` | Settings | Toggle maintenance mode |
+
+In prompts, `Enter` continues, `Esc` cancels, and `Ctrl-U` clears the input. Config-value input is masked. Editing replaces the complete value and currently supports single-line input; existing multiline values can be inspected but should be edited through the standard CLI or web dashboard.
+
+## Remote changes and config values
+
+Every write displays the target app and proposed change, then requires typing the **exact app name**. Scaling can change billing and restart dynos. Config changes create a release and restart the app. Maintenance mode affects request serving.
+
+`--read-only` blocks all non-GET requests at the plugin's API boundary, in addition to disabling mutation prompts. The offline demo also runs read-only.
+
+Config values are fetched only when opening Config. Press `v` to reveal or hide the selected variable independently of the others. Moving between rows keeps revealed values visible, so you can inspect several at once. Switching views/apps or manually refreshing hides them all again. The plugin keeps fetched values in memory for the selected app and does not write config values to disk. Automatic refresh updates operational app data; use `R` to refresh config values.
+
+Press **`y`** to copy the selected variable's value without revealing it. Revealed values appear in **cyan** in the Details pane; **click the highlighted value** to copy it. Clicking any wrapped or multiline portion copies the complete value. Empty values show a clickable `(empty value)` placeholder. Copying preserves whitespace, Unicode, and multiline content, and works in `--read-only` mode. The status bar confirms the variable name without displaying its value.
+
+Clipboard access uses the system clipboard on the machine running `dash` (macOS, Windows, or a Linux desktop). On Wayland, install `wl-clipboard`; X11 uses `xsel`, with a bundled fallback. A desktop clipboard must be accessible to the terminal; headless/SSH sessions without one show a copy error instead.
+
+## Metrics and current scope
+
+The Metrics view uses real snapshots from the public Heroku Platform API. It counts `up` and `idle` formation dynos as healthy, excludes one-off processes from desired-formation health, and shows recent release outcomes. Dyno age is time since creation, not a historical uptime guarantee. During deploys, overlapping dynos can exceed the desired count.
+
+**CPU, memory, throughput, and request-latency time series are not available through the public Platform API used here.** Press `o` in Metrics to open Heroku's metrics dashboard.
+
+Add-on provisioning/plan changes, pipeline promotions, log streaming, domain/buildpack edits, and historical monitoring are outside this initial version. Settings other than maintenance mode are displayed read-only. Individual section failures are shown without preventing other sections from loading.
+
+## Development and verification
+
+Plain JavaScript ESM, an oclif/Heroku command, and Blessed terminal widgets. No application compilation step is required; `npm run build` generates the oclif command manifest.
+
+### Local development
+
+From a checkout of this repository:
+
+```sh
+npm ci
+npm run build
+heroku plugins:link .
+heroku dash --demo
+```
+
+To switch from a development link to the npm release:
+
+```sh
+heroku plugins:unlink heroku-dash
+heroku plugins:install heroku-dash
+```
+
+### Checks
+
+```sh
+npm run check             # Lint, automated tests, command manifest
+npm pack --dry-run        # Inspect the publishable package
+```
+
+Tests use mocked transports and in-memory terminal streams. They cover repository resolution, pagination, partial API failures, read-only guards, confirmation validation, all three mutation paths, config masking, keyboard navigation, stale-response handling, and terminal cleanup.
+
+### Publishing to npm
+
+Run these commands from the repository root with Node.js 22+:
+
+```sh
+npm ci
+npm publish --dry-run       # Run checks and inspect the package without uploading
+npm login                  # Sign in to the npm account publishing the package
+npm publish
+```
+
+`npm publish` runs lint and tests through `prepublishOnly`, then generates the command manifest through `prepack`. The package includes the runtime source, `oclif.manifest.json`, README, and MIT license. Development dependencies are needed to publish, but aren't required when installing the published plugin. Package access is explicitly public.
+
+The initial release is **`heroku-dash@0.1.0`**. For subsequent releases, increment the version before publishing, for example:
+
+```sh
+npm version patch --no-git-tag-version
+```
+
+This updates `package.json` and `package-lock.json`; npm does not allow publishing the same package version twice.
+
+### Explicit read-only integration checks
+
+These are opt-in and use the current Heroku CLI account:
+
+```sh
+npm run test:live -- ~/work/hermod ~/work/heimdall
+```
+
+The live-check transport **rejects every method except GET**. It verifies repository-to-pipeline resolution and renders all seven app views, printing counts rather than config values. It reads every app in the detected pipelines.
+
+After linking the plugin, macOS/Linux users with Python 3 can exercise the actual CLI in a pseudo-terminal:
+
+```sh
+python3 scripts/terminal-check.py
+python3 scripts/terminal-check.py --repo ~/work/hermod
+python3 scripts/terminal-check.py --repo ~/work/heimdall
+```
+
+Without `--repo`, this uses the offline demo. Live terminal checks always pass `--read-only --refresh 0`; mutation behavior is tested only with mocked APIs.
+
+### Layout
+
+```text
+src/commands/dash.js   Command flags, authentication, startup
+src/project.js         Git context and pipeline resolution
+src/hierarchy.js       Team and pipeline parents for resource breadcrumbs
+src/api.js             Platform API reads, pagination, guarded writes
+src/ui/dashboard.js    Terminal navigation, prompts, refresh, lifecycle
+src/ui/views.js        View models, config masking, operational metrics
+src/ui/details.js      Highlighted values and scroll-aware click targets
+src/ui/theme.js        Nerd Font icons, semantic colors, styled labels
+src/ui/text.js         Terminal-safe text sanitization
+src/demo.js            Offline demo data
+test/                  API, project, view, and keyboard integration tests
+scripts/               Explicit GET-only live and pseudo-terminal checks
+```
+
+## License
+
+MIT

package/oclif.manifest.json

@@ -0,0 +1,105 @@
+{
+  "commands": {
+    "dash": {
+      "aliases": [],
+      "args": {},
+      "description": "navigate Heroku teams, pipelines, and apps in a rich terminal dashboard",
+      "examples": [
+        "<%= config.bin %> dash",
+        "<%= config.bin %> dash --pipeline my-pipeline",
+        "<%= config.bin %> dash --app my-app --read-only",
+        "<%= config.bin %> dash --remote staging"
+      ],
+      "flags": {
+        "app": {
+          "char": "a",
+          "description": "App name or ID",
+          "exclusive": [
+            "pipeline",
+            "remote",
+            "team"
+          ],
+          "name": "app",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "pipeline": {
+          "char": "p",
+          "description": "Pipeline name or ID",
+          "exclusive": [
+            "app",
+            "remote",
+            "team"
+          ],
+          "name": "pipeline",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "remote": {
+          "char": "r",
+          "description": "Heroku Git remote to use",
+          "exclusive": [
+            "app",
+            "pipeline",
+            "team"
+          ],
+          "name": "remote",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "team": {
+          "char": "t",
+          "description": "Start in a team (name or ID)",
+          "exclusive": [
+            "app",
+            "pipeline",
+            "remote"
+          ],
+          "name": "team",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "read-only": {
+          "description": "Disable all remote changes",
+          "name": "read-only",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "refresh": {
+          "description": "Refresh current app every N seconds (0 disables)",
+          "name": "refresh",
+          "default": 30,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "demo": {
+          "description": "Explore an offline demo; no Heroku requests",
+          "name": "demo",
+          "allowNo": false,
+          "type": "boolean"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "dash",
+      "pluginAlias": "heroku-dash",
+      "pluginName": "heroku-dash",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "promptFlagActive": false,
+      "isESM": true,
+      "relativePath": [
+        "src",
+        "commands",
+        "dash.js"
+      ]
+    }
+  },
+  "version": "0.1.0"
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "heroku-dash",
+  "version": "0.1.0",
+  "description": "A keyboard-driven terminal dashboard for Heroku",
+  "author": "Ryan McGeary <ryan@mcgeary.org>",
+  "homepage": "https://github.com/rmm5t/heroku-dash",
+  "bugs": {"url": "https://github.com/rmm5t/heroku-dash/issues"},
+  "repository": {"type": "git", "url": "git+https://github.com/rmm5t/heroku-dash.git"},
+  "license": "MIT",
+  "type": "module",
+  "engines": {"node": ">=22"},
+  "files": ["src", "oclif.manifest.json", "README.md", "LICENSE"],
+  "keywords": ["heroku", "heroku-cli-plugin", "oclif", "tui", "dashboard"],
+  "oclif": {"bin": "heroku", "commands": "./src/commands"},
+  "publishConfig": {"access": "public"},
+  "scripts": {
+    "build": "oclif manifest",
+    "lint": "eslint src test scripts",
+    "test": "node --test",
+    "check": "npm run lint && npm test && npm run build",
+    "test:live": "node scripts/live-check.js",
+    "prepack": "npm run build",
+    "prepublishOnly": "npm run lint && npm test"
+  },
+  "dependencies": {
+    "@heroku-cli/command": "^13.2.2",
+    "@oclif/core": "^4.13.2",
+    "blessed": "^0.1.81",
+    "clipboardy": "^5.3.2"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.2",
+    "eslint": "^9.39.2",
+    "globals": "^16.5.0",
+    "oclif": "^4.23.29"
+  }
+}

package/src/api.js

@@ -0,0 +1,128 @@
+const V3 = 'application/vnd.heroku+json; version=3'
+const encode = encodeURIComponent
+
+export function statusCode(error) {
+  return error.statusCode ?? error.status ?? error.response?.statusCode ?? error.http?.statusCode ?? error.http?.http?.statusCode
+}
+
+export function errorMessage(error) {
+  const status = statusCode(error)
+  if (status === 401) return 'Heroku authentication expired. Run heroku login and reopen dash.'
+  if (status === 403) return 'Your Heroku account does not have permission to view or change this resource.'
+  if (status === 429) return 'Heroku API rate limit reached. Wait before refreshing.'
+  return error.body?.message ?? error.message ?? String(error)
+}
+
+export class HerokuAPI {
+  constructor(client, {readOnly = false} = {}) {
+    this.client = client
+    this.readOnly = readOnly
+  }
+
+  async request(path, options = {}) {
+    const method = options.method ?? 'GET'
+    if (this.readOnly && method !== 'GET') throw new Error('Read-only mode: remote changes are disabled.')
+    return this.client.request(path, {retryAuth: false, ...options, method, headers: {Accept: V3, ...options.headers}})
+  }
+
+  async get(path, options) {
+    return (await this.request(path, options)).body
+  }
+
+  async list(path, options = {}) {
+    const items = []
+    let range = options.headers?.Range
+    const seen = new Set()
+    do {
+      const response = await this.request(path, {...options, headers: {...options.headers, ...(range ? {Range: range} : {})}})
+      if (!Array.isArray(response.body)) throw new Error(`Unexpected list response from ${path}`)
+      items.push(...response.body)
+      range = response.headers?.['next-range'] ?? response.headers?.['Next-Range']
+      if (range && seen.has(range)) throw new Error(`Repeated pagination range from ${path}`)
+      if (range) seen.add(range)
+    } while (range)
+    return items
+  }
+
+  async catalog() {
+    const results = await Promise.allSettled([this.list('/teams'), this.list('/pipelines'), this.list('/apps')])
+    const catalog = {warnings: []}
+    for (const [i, key] of ['teams', 'pipelines', 'apps'].entries()) {
+      const result = results[i]
+      if (result.status === 'fulfilled') catalog[key] = result.value.sort((a, b) => a.name.localeCompare(b.name))
+      else {
+        catalog[key] = []
+        catalog.warnings.push(`${key}: ${errorMessage(result.reason)}`)
+      }
+    }
+    if (results.every(r => r.status === 'rejected')) throw results[2].reason
+    return catalog
+  }
+
+  async coupling(app) {
+    try {
+      return await this.get(`/apps/${encode(app)}/pipeline-couplings`)
+    } catch (error) {
+      if (statusCode(error) === 404) return null
+      throw error
+    }
+  }
+
+  async pipelineApps(pipeline) {
+    const couplings = await this.list(`/pipelines/${encode(pipeline)}/pipeline-couplings`)
+    return Promise.all(couplings.map(async coupling => ({
+      ...await this.get(`/apps/${encode(coupling.app.id)}`),
+      stage: coupling.stage,
+    })))
+  }
+
+  async appData(app) {
+    const base = `/apps/${encode(app)}`
+    const sections = {
+      app: () => this.get(base),
+      coupling: () => this.coupling(app),
+      formation: () => this.list(`${base}/formation`),
+      dynos: () => this.list(`${base}/dynos`),
+      addons: () => this.list(`${base}/addons`),
+      attachments: () => this.list(`${base}/addon-attachments`),
+      domains: () => this.list(`${base}/domains`),
+      buildpacks: () => this.list(`${base}/buildpack-installations`),
+      // Only the latest page: release histories can be enormous.
+      releases: () => this.get(`${base}/releases`, {headers: {Range: 'version ..; order=desc,max=20;'}}),
+    }
+    const data = {errors: {}, fetchedAt: new Date().toISOString()}
+    await Promise.all(Object.entries(sections).map(async ([key, load]) => {
+      try { data[key] = await load() }
+      catch (error) { data.errors[key] = errorMessage(error); data[key] = ['app', 'coupling'].includes(key) ? null : [] }
+    }))
+    if (!data.app) throw new Error(data.errors.app)
+    return data
+  }
+
+  config(app) { return this.get(`/apps/${encode(app)}/config-vars`) }
+
+  async scale(app, type, quantity, size, confirmation) {
+    this.confirm(app, confirmation)
+    if (!Number.isSafeInteger(quantity) || quantity < 0) throw new Error('Dyno quantity must be a non-negative integer.')
+    if (!size?.trim()) throw new Error('Enter a dyno size, such as Standard-1X.')
+    return this.get(`/apps/${encode(app)}/formation/${encode(type)}`, {method: 'PATCH', body: {quantity, size: size.trim()}})
+  }
+
+  async setConfig(app, key, value, confirmation) {
+    this.confirm(app, confirmation)
+    if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(key)) throw new Error('Config keys must start with a letter or underscore and contain only letters, digits, and underscores.')
+    if (value !== null && typeof value !== 'string') throw new Error('Config values must be strings.')
+    return this.get(`/apps/${encode(app)}/config-vars`, {method: 'PATCH', body: {[key]: value}})
+  }
+
+  async maintenance(app, enabled, confirmation) {
+    this.confirm(app, confirmation)
+    if (typeof enabled !== 'boolean') throw new Error('Maintenance mode must be a boolean.')
+    return this.get(`/apps/${encode(app)}`, {method: 'PATCH', body: {maintenance: enabled}})
+  }
+
+  confirm(app, confirmation) {
+    if (this.readOnly) throw new Error('Read-only mode: remote changes are disabled.')
+    if (!app || confirmation !== app) throw new Error('Type the exact app name to confirm this change.')
+  }
+}

package/src/commands/dash.js

@@ -0,0 +1,47 @@
+import {Command} from '@heroku-cli/command'
+import {Flags} from '@oclif/core'
+import {HerokuAPI} from '../api.js'
+import {inspectProject, resolveContext} from '../project.js'
+
+export default class Dash extends Command {
+  static promptFlagActive = false
+  static baseFlags = Command.baseFlagsWithoutPrompt()
+  static description = 'navigate Heroku teams, pipelines, and apps in a rich terminal dashboard'
+  static examples = [
+    '<%= config.bin %> dash',
+    '<%= config.bin %> dash --pipeline my-pipeline',
+    '<%= config.bin %> dash --app my-app --read-only',
+    '<%= config.bin %> dash --remote staging',
+  ]
+  static flags = {
+    app: Flags.string({char: 'a', description: 'App name or ID', exclusive: ['pipeline', 'remote', 'team']}),
+    pipeline: Flags.string({char: 'p', description: 'Pipeline name or ID', exclusive: ['app', 'remote', 'team']}),
+    remote: Flags.string({char: 'r', description: 'Heroku Git remote to use', exclusive: ['app', 'pipeline', 'team']}),
+    team: Flags.string({char: 't', description: 'Start in a team (name or ID)', exclusive: ['app', 'pipeline', 'remote']}),
+    'read-only': Flags.boolean({description: 'Disable all remote changes', default: false}),
+    refresh: Flags.integer({description: 'Refresh current app every N seconds (0 disables)', default: 30, min: 0}),
+    demo: Flags.boolean({description: 'Explore an offline demo; no Heroku requests', default: false}),
+  }
+
+  async run() {
+    const {flags} = await this.parse(Dash)
+    if (!process.stdin.isTTY || !process.stdout.isTTY) this.error('heroku dash needs an interactive terminal (TTY). Run it directly in your terminal.')
+    if (flags.refresh !== 0 && flags.refresh < 10) this.error('--refresh must be 0 or at least 10 seconds.')
+    const {runDashboard} = await import('../ui/dashboard.js')
+    if (flags.demo) {
+      const {createDemo} = await import('../demo.js')
+      return runDashboard({...createDemo(), refresh: flags.refresh, demo: true})
+    }
+    if (!await this.heroku.getAuth()) this.error('Log in with heroku login before opening dash.')
+    // Interactive reauthentication must not take over the full-screen terminal.
+    this.heroku.twoFactorPrompt = async () => { throw new Error('This resource requires additional authentication. Authorize it with the Heroku CLI, then reopen dash.') }
+    const api = new HerokuAPI(this.heroku, {readOnly: flags['read-only']})
+    const [catalog, project] = await Promise.all([api.catalog(), inspectProject()])
+    const context = await resolveContext(api, catalog, flags, project)
+    if (flags.team) {
+      context.team = catalog.teams.find(t => t.id === flags.team || t.name === flags.team)
+      if (!context.team) this.error(`Team not found: ${flags.team}`)
+    }
+    await runDashboard({api, catalog, context, refresh: flags.refresh})
+  }
+}

package/src/demo.js

@@ -0,0 +1,31 @@
+import {HerokuAPI} from './api.js'
+
+export function createDemo() {
+  const now = Date.now()
+  const ago = seconds => new Date(now - seconds * 1000).toISOString()
+  const team = {id: 'team-demo', name: 'acme'}
+  const pipeline = {id: 'pipeline-demo', name: 'constellation', owner: {id: team.id, type: 'team'}}
+  const apps = ['staging', 'production'].map(stage => ({
+    id: `app-${stage}`, name: `constellation-${stage}`, stage, team,
+    region: {name: 'us'}, stack: {name: 'heroku-24'}, build_stack: {name: 'heroku-24'},
+    web_url: `https://constellation-${stage}.herokuapp.com`, maintenance: false, acm: true,
+    created_at: ago(86400 * 90), updated_at: ago(3600),
+  }))
+  const data = app => ({app, coupling: {pipeline: {id: pipeline.id, name: pipeline.name}}, errors: {}, fetchedAt: new Date().toISOString(),
+    formation: [{type: 'web', quantity: 2, size: 'Standard-1X', command: 'npm start'}, {type: 'worker', quantity: 1, size: 'Standard-2X', command: 'node worker.js'}],
+    dynos: ['web.1', 'web.2', 'worker.1'].map(name => ({name, type: name.split('.')[0], state: 'up', size: name.startsWith('web') ? 'Standard-1X' : 'Standard-2X', created_at: ago(4700), command: 'node server.js', release: {version: 42}})),
+    addons: [{id: 'postgres', name: 'postgresql-orbit-12345', plan: {name: 'heroku-postgresql:essential-0'}, addon_service: {name: 'heroku-postgresql'}, state: 'provisioned', app, config_vars: ['DATABASE_URL']}],
+    attachments: [{name: 'DATABASE', addon: {id: 'postgres'}}],
+    domains: [{hostname: `${app.name}.herokuapp.com`, kind: 'heroku', status: 'succeeded'}],
+    buildpacks: [{ordinal: 1, buildpack: {name: 'heroku/nodejs', url: 'heroku/nodejs'}}],
+    releases: [42, 41, 40].map((version, i) => ({version, status: 'succeeded', description: i ? 'Update config vars' : 'Deploy a1b2c3d', created_at: ago(4700 + i * 86400), user: {email: 'developer@example.com'}})),
+  })
+  // Use the real API's read-only guards even in the offline demo.
+  const api = new HerokuAPI({request() { throw new Error('Demo is offline.') }}, {readOnly: true})
+  const catalog = {teams: [team], pipelines: [pipeline], apps, warnings: []}
+  api.catalog = async () => structuredClone(catalog)
+  api.pipelineApps = async () => structuredClone(apps)
+  api.appData = async id => data(apps.find(a => a.id === id || a.name === id))
+  api.config = async () => ({NODE_ENV: 'production', EXAMPLE_SECRET: 'demo-only-value', WEB_CONCURRENCY: '2'})
+  return {api, catalog, context: {pipeline, reason: 'Offline demo'}}
+}

package/src/hierarchy.js

@@ -0,0 +1,27 @@
+import {errorMessage} from './api.js'
+
+// Resource ownership is independent of the sidebar's team filter. Couplings
+// often contain only a pipeline ID/name, so enrich them from the catalog first.
+export async function resolveHierarchy(api, catalog, {app = null, pipeline = null}) {
+  const known = pipeline && catalog.pipelines.find(item => item.id === pipeline.id)
+  const result = {
+    pipeline: pipeline ? {...known, ...pipeline} : null,
+    team: {name: 'Personal'},
+    errors: {},
+  }
+  try {
+    if (result.pipeline && !app?.team && !Object.hasOwn(result.pipeline, 'owner')) {
+      result.pipeline = await api.get(`/pipelines/${encodeURIComponent(result.pipeline.id)}`)
+    }
+    const owner = result.pipeline?.owner
+    const team = app?.team ?? (owner?.type === 'team' ? {id: owner.id, name: owner.name} : null)
+    if (team) {
+      const cached = catalog.teams.find(item => item.id === team.id || (team.name && item.name === team.name))
+      result.team = team.name ? team : cached ?? await api.get(`/teams/${encodeURIComponent(team.id)}`)
+    }
+  } catch (error) {
+    result.team = {name: 'Team unavailable'}
+    result.errors.hierarchy = errorMessage(error)
+  }
+  return result
+}