{"id":51118912,"url":"https://github.com/adr/adr-manager-apps","last_synced_at":"2026-06-25T00:30:31.667Z","repository":{"id":366369527,"uuid":"1256085772","full_name":"adr/adr-manager-apps","owner":"adr","description":"Monorepo for joint major releases of the web-based ADR Manager and its VS Code extension","archived":false,"fork":false,"pushed_at":"2026-06-21T14:50:06.000Z","size":8563,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-21T15:12:55.042Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/adr.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-01T12:56:05.000Z","updated_at":"2026-06-21T14:49:16.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/adr/adr-manager-apps","commit_stats":null,"previous_names":["adr/adr-manager-apps"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/adr/adr-manager-apps","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adr%2Fadr-manager-apps","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adr%2Fadr-manager-apps/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adr%2Fadr-manager-apps/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adr%2Fadr-manager-apps/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/adr","download_url":"https://codeload.github.com/adr/adr-manager-apps/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adr%2Fadr-manager-apps/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34755061,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-24T02:00:07.484Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-25T00:30:31.198Z","updated_at":"2026-06-25T00:30:31.657Z","avatar_url":"https://github.com/adr.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ADR Manager Apps\n\n[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)\n[![Extension · CI](https://github.com/adr/adr-manager-apps/actions/workflows/extension-ci.yml/badge.svg)](https://github.com/adr/adr-manager-apps/actions/workflows/extension-ci.yml)\n[![Web · Tests](https://github.com/adr/adr-manager-apps/actions/workflows/web-tests.yml/badge.svg)](https://github.com/adr/adr-manager-apps/actions/workflows/web-tests.yml)\n[![VS Code Marketplace](https://img.shields.io/visual-studio-marketplace/v/StevenChen.vscode-adr-manager?label=marketplace)](https://marketplace.visualstudio.com/items?itemName=StevenChen.vscode-adr-manager)\n\nADR Manager Apps is the monorepo for the web-based **ADR Manager** and the **ADR Manager VS Code extension**.\nBoth apps help teams create, edit, validate, and manage Architectural Decision Records (ADRs) written in Markdown with the [MADR](https://adr.github.io/madr/) template.\n\n- **Web app**: manage MADRs in GitHub repositories, live at \u003chttps://adr.github.io/adr-manager-apps/\u003e\n- **VS Code extension**: manage MADRs in local workspaces, on the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=StevenChen.vscode-adr-manager)\n\nThe apps share a common core and tooling, and are developed, tested, versioned, and released together from one pnpm workspace.\n\n## Packages\n\n| Package                        | Path                                                   | Description                                                                                                                                           |\n| ------------------------------ | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `adr-manager`                  | [`apps/adr-manager`](apps/adr-manager)                 | Web app (Vue 3, Vite, TypeScript, CodeMirror 6) for managing MADRs in GitHub repositories via GitHub OAuth                                            |\n| `vscode-adr-manager`           | [`apps/vscode-adr-manager`](apps/vscode-adr-manager)   | VS Code extension for managing MADRs in single-root, multi-root, and folder-based workspaces, with commands, context menus, snippets, and diagnostics |\n| `@adr-manager/core`            | [`packages/core`](packages/core)                       | Shared MADR parser (ANTLR4), ADR domain model, and utilities used by both apps                                                                        |\n| `@adr-manager/eslint-config`   | [`packages/eslint-config`](packages/eslint-config)     | Shared ESLint flat configs (`base`, `vue`, `node`)                                                                                                    |\n| `@adr-manager/prettier-config` | [`packages/prettier-config`](packages/prettier-config) | Shared Prettier configuration                                                                                                                         |\n| `@adr-manager/tsconfig`        | [`packages/tsconfig`](packages/tsconfig)               | Shared TypeScript configs (`base`, `vue`, `node`, `commonjs`)                                                                                         |\n\nThe two apps are the deliverables. The `@adr-manager/*` packages are private workspace packages and are not published anywhere.\n\nPackage-specific usage details live in the package docs:\n\n- [Web app README](apps/adr-manager/README.md)\n- [VS Code extension README](apps/vscode-adr-manager/README.md) and [CHANGELOG](apps/vscode-adr-manager/CHANGELOG.md)\n\n## Architecture\n\n- `@adr-manager/core` is consumed directly as TypeScript source (its exports point at `src/index.ts`), so there is no build step and no stale artifacts between the core and the apps.\n- `@adr-manager/eslint-config`, `@adr-manager/prettier-config`, and `@adr-manager/tsconfig` centralize tooling so every package extends the same rules.\n- Shared dependency versions are pinned once in the `catalog:` section of [`pnpm-workspace.yaml`](pnpm-workspace.yaml) and referenced from packages with the `catalog:` protocol.\n- The workspace uses pnpm's `nodeLinker: hoisted` (flat `node_modules`) because the Vue and VS Code packaging toolchains expect flat dependency resolution.\n\n## Prerequisites\n\n- [Node.js](https://nodejs.org/) \u003e= 22.13\n- [pnpm](https://pnpm.io/) 11.5.1, pinned via the `packageManager` field so recent pnpm versions (or `corepack enable`) switch to it automatically\n- [Git](https://git-scm.com/)\n- [Visual Studio Code](https://code.visualstudio.com/) when developing or testing the extension\n\n## Getting started\n\n```bash\ngit clone https://github.com/adr/adr-manager-apps.git\ncd adr-manager-apps\npnpm install\n```\n\nInstalls are hardened in [`pnpm-workspace.yaml`](pnpm-workspace.yaml): newly published dependency versions are delayed for five days, and only reviewed build scripts (`esbuild`, `cypress`, `core-js`) are allowed to run.\nIf pnpm reports blocked dependency build scripts, review and approve them with `pnpm approve-builds`.\n\n## Development\n\nRun both apps at once (Vite dev server plus the extension watchers):\n\n```bash\npnpm dev\n```\n\nOr run them individually as described below.\n\n### Web app\n\n```bash\npnpm dev:web\n```\n\nThe Vite dev server runs at `http://localhost:8000/adr-manager-apps/` (the `/adr-manager-apps/` base path matches the GitHub Pages deployment).\nThe main manager route is `http://localhost:8000/adr-manager-apps/#/manager`.\n\nThe web app connects to GitHub through OAuth and stores the active `authId` and local ADR changes in browser local storage.\nYou need a GitHub account with access to a repository that contains MADRs, normally under `docs/adr`.\n\n### VS Code extension\n\nThere are two ways to run the extension locally:\n\n- **Debug with F5**: open the `apps/vscode-adr-manager` folder in VS Code (the `Run Extension` launch configuration lives in that folder) and press `F5`. This builds the extension and opens an Extension Development Host.\n- **Watch mode**: run `pnpm watch:ext` from the workspace root. This watches the extension host bundle (esbuild), the webview bundles (Vite), and the type checker (tsc) in parallel and writes output to `apps/vscode-adr-manager/dist`.\n\nIn the Extension Development Host, open a folder that contains an ADR directory and run `Open ADR Manager` from the Command Palette.\nThe extension defaults to `docs/decisions` for the ADR directory. Change it with the `adrManager.adrDirectory` setting or the `Change ADR Directory` command.\n\n## Build and package\n\n```bash\npnpm build      # build every package\npnpm build:web  # web app only: vue-tsc type check + Vite build -\u003e apps/adr-manager/dist\npnpm build:ext  # extension only: esbuild (host) + Vite (webviews) -\u003e apps/vscode-adr-manager/dist\n```\n\nPackage the extension as a VSIX file and install it into VS Code:\n\n```bash\npnpm vsix\ncode --install-extension apps/vscode-adr-manager/vscode-adr-manager-\u003cversion\u003e.vsix\n```\n\nReplace `\u003cversion\u003e` with the version from `apps/vscode-adr-manager/package.json`.\n\n## Testing and code quality\n\n| Command                             | What it runs                                                      |\n| ----------------------------------- | ----------------------------------------------------------------- |\n| `pnpm test`                         | All package test suites (Vitest)                                  |\n| `pnpm test:web`                     | Web app unit tests                                                |\n| `pnpm test:ext`                     | Extension tests (`pretest` typechecks, compiles, and lints first) |\n| `pnpm e2e:web`                      | Web app end-to-end tests (Cypress)                                |\n| `pnpm lint`                         | Linting (ESLint) in every package with a `lint` script            |\n| `pnpm typecheck`                    | Type checks in every package with a `typecheck` script            |\n| `pnpm lint:ext`                     | Extension linting (ESLint)                                        |\n| `pnpm format` / `pnpm format:check` | Prettier write / check across the whole repository                |\n\n### End-to-end tests\n\nThe Cypress tests run against mocked GitHub and GitLab provider APIs. They need the web app dev server running, but do not need OAuth tokens, provider credentials, or live repositories:\n\n```bash\npnpm dev:web   # in a separate terminal\npnpm e2e:web\n```\n\n## Releases and CI\n\nReleases are coordinated with [Changesets](https://github.com/changesets/changesets):\n\nFor the GitHub Pages setup checklist and deployment guide, see [GitHub Pages CI/CD Guide](docs/github-pages-ci-cd.md).\n\n1. Add a changeset alongside any change that should be released: `pnpm changeset`.\n2. On every push to `main`, the `Release` workflow opens or updates a **Version Packages (joint release)** PR that applies pending changesets (version bumps and changelogs, via `pnpm version-packages`).\n3. Merging that PR publishes the bumped versions to `main`. Neither package is published to npm. Instead:\n   - the web app deploys to GitHub Pages automatically (`Web · Build \u0026 Publish` pushes `apps/adr-manager/dist` to the `gh-pages` branch), and\n   - the extension is published to the VS Code Marketplace by manually running the `Extension · Publish` workflow (`vsce publish`, requires the `VSCE_PAT` secret).\n\n| Workflow                | Trigger                                                        | What it does                                               |\n| ----------------------- | -------------------------------------------------------------- | ---------------------------------------------------------- |\n| `Repo · Checks`         | Every push, manual                                             | Prettier check, type checks, and linting across the repo   |\n| `Extension · CI`        | Push touching the extension or shared packages, manual         | Compiles, lints, tests, and uploads a VSIX artifact        |\n| `Web · Tests`           | Push touching the web app or shared packages, manual           | Vitest unit tests and Cypress e2e tests (Chrome)           |\n| `Release`               | Push to `main`                                                 | Opens/updates the Changesets \"Version Packages\" PR         |\n| `Web · Build \u0026 Publish` | Push to `main` touching the web app or shared packages, manual | Builds the web app and deploys it to the `gh-pages` branch |\n| `Extension · Publish`   | Manual                                                         | Publishes the extension to the VS Code Marketplace         |\n\n## Repository structure\n\n```text\n.\n|-- .changeset/                  # changesets config and pending release notes\n|-- .github/workflows/           # CI, release, and publish pipelines\n|-- apps/\n|   |-- adr-manager/             # web app (src, tests, cypress)\n|   `-- vscode-adr-manager/      # VS Code extension (src, webviews in web/)\n|-- packages/\n|   |-- core/                    # shared MADR parser and ADR domain model\n|   |-- eslint-config/           # shared ESLint flat configs\n|   |-- prettier-config/         # shared Prettier config\n|   `-- tsconfig/                # shared TypeScript configs\n|-- .nvmrc                       # Node version used by CI (and nvm users)\n|-- package.json                 # root orchestration scripts\n|-- pnpm-workspace.yaml          # workspace layout, dependency catalog, install hardening\n`-- README.md\n```\n\n## Contributing\n\nContributions are welcome.\nBefore opening a pull request:\n\n1. Create an issue or comment on an existing issue when the change affects behavior or public workflows.\n2. Keep changes focused and describe the user-facing effect.\n3. Add or update tests when changing behavior.\n4. Run the relevant checks from the workspace root.\n5. Add a changeset with `pnpm changeset` when the change should be released.\n\nFor a full validation pass, run:\n\n```bash\npnpm build\npnpm test\npnpm typecheck\npnpm lint\npnpm format:check\n```\n\nIf the extension package is affected, also run `pnpm vsix`.\n\n### Reporting issues\n\nOpen a GitHub issue with:\n\n- The package that is affected\n- Your operating system\n- Your Node.js and pnpm versions\n- Steps to reproduce the issue\n- Expected and actual behavior\n- Screenshots or logs when they help explain the problem\n\nDo not include private GitHub tokens, OAuth session values, or repository secrets in issues.\n\n## License\n\nThis project is licensed under the [Apache License 2.0](LICENSE).\n\n## Acknowledgements\n\n- The web-based ADR Manager started as an undergraduate research project at the Institute of Software Engineering of the University of Stuttgart and was submitted to the [ICSE Score Contest 2021](https://conf.researchr.org/home/icse-2021/score-2021).\n- The VS Code extension was created by Steven Chen as part of a Bachelor thesis at the University of Stuttgart.\n- Both apps build on the [MADR](https://adr.github.io/madr/) template from the [adr organization](https://github.com/adr).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadr%2Fadr-manager-apps","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fadr%2Fadr-manager-apps","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadr%2Fadr-manager-apps/lists"}