Skip to main content

ADR-0027: Workspace method install and member enumeration

  • Status: Proposed
  • Date: 2026-07-25
  • Deciders: Michel Gillet

Context​

ADR-0024 defines method asset resolution and allows a superbuild workspace W to hold the union of write-contract versions under $W/.tools_local/esys/a2c/<ver>/. ADR-0025 (amended by ADR-0026) defines how a2c discovers W.

What ADR-0024 does not specify is how a2c learns the set of member product repos R in W, or how it installs method assets for those versions. Options that couple a2c to Google repo XML, esysrepo internals, or a blind filesystem walk of every .git would either miss layouts or invent monorepo assumptions.

LibESys esysrepo (the CLI) already understands both esysrepo-native and Google repo workspaces. A2C users who only use Google repo may not have esysrepo on PATH.

Decision​

1. Separation of concerns​

ToolResponsibility
esysrepo / repoEnumerate member project paths in workspace W
a2cRead each member’s write contract (adoption.yaml); install method assets for the needed version(s) under .tools_local/esys/a2c/<ver>/

a2c does not parse .repo/manifest.xml or esysrepo private stores as the primary path. It consumes a normalized project list from an external CLI.

2. Member enumeration order​

When a2c needs the member list for W:

  1. If esysrepo is available on PATH, invoke it (subcommand/flags as documented by esysrepo) and request machine-readable output (JSON preferred).
  2. Else if repo (Google) is available on PATH, invoke it and normalize its listing into the same shape.
  3. Else fail with a clear message to install esysrepo or repo.

Do not run esysrepo and repo in parallel as competing sources. Prefer esysrepo; use Google repo only when esysrepo is missing.

A full-tree “find every .git and sniff for A2C” walk is not the primary algorithm. An optional, clearly gated fallback may be added later only if both CLIs are absent — and must not be the documented default.

3. Normalized project list (contract)​

Whatever the backend CLI returns, a2c normalizes to a logical document like:

{
  "schema_version": 1,
  "workspace_root": ".",
  "source": "esysrepo",
  "projects": [
    { "path": "src/foo", "name": "foo" },
    { "path": "src/bar", "name": "bar" }
  ]
}
  • workspace_root may be . or absolute; a2c resolves against discovered W (ADR-0025).
  • path is relative to W or absolute under W.
  • name is optional.
  • source is esysrepo or repo (which backend produced the list).

Exact esysrepo flag names are an implementation detail; this ADR binds the normalized shape and precedence, not a frozen argv string.

4. Collecting write-contract versions​

For workspace-scoped install:

  1. Discover W (ADR-0025).
  2. Obtain the project list (§2–§3).
  3. For each projects[].path, treat it as a candidate product root R.
  4. If {tool_state_root}/adoption.yaml exists (dual-read per ADR-0024), record tool_version (normalize; strip leading v for directory names as elsewhere).
  5. Skip paths with no adoption record (not A2C-governed, or not yet adopted).
  6. The install set is the union of those versions.

Single-repo install (no --workspace): use only the current R’s write contract (or an explicit --version).

5. Install commands (product shape)​

a2c exposes install entry points consistent with existing a2c method path:

  • a2c method install — install method assets for the current repo’s write contract into $W/.tools_local/esys/a2c/V/ when W is known, else $R/.tools_local/esys/a2c/V/.
  • a2c method install --workspace — enumerate members (§2), union versions (§4), install each missing V once under $W/.tools_local/esys/a2c/V/.

Optional flags (names may vary): --version, --dry-run, --json.

6. Fetching assets for version V​

How bytes arrive under .tools_local/esys/a2c/V/ is an implementation choice documented with the command (e.g. git checkout of a2c-workflow at tag vV, PyPI/Conan package, or copy from a developer method root). Requirements:

  • Installed tree must satisfy “looks like A2C method assets” (same recognition used by method resolution in ADR-0024).
  • Never install into $W/tools/ai-rules/ (superbuild-workflow territory).
  • Never treat $W/tools/ai-rules/ as the A2C method root.

7. Relationship to ADR-0024 / ADR-0025​

  • ADR-0024 remains the write-contract and resolution ADR.
  • ADR-0025 remains workspace discovery.
  • This ADR owns member enumeration backends and method install UX.

Consequences​

Positive​

  • One adapter covers esysrepo-native and Google repo workspaces when esysrepo is present; pure repo users still work via fallback.
  • a2c stays decoupled from manifest/XML evolution.
  • Union install matches ADR-0024’s shared .tools_local model without attaching member repos to one superbuild in git.

Negative​

  • Requires esysrepo (preferred) or Google repo on PATH for --workspace.
  • Normalized JSON schema must stay in sync with esysrepo CLI output (version the schema; amend this ADR if the contract changes).
  • Fetch mechanism for method packages may need a follow-up ADR if packaging strategy hardens (PyPI vs git tag vs Conan).

Non-goals​

  • Implementing the esysrepo JSON command itself (owned by esysrepo).
  • Replacing superbuild-workflow at $W/tools/ai-rules/.
  • Auto-adopting A2C into every manifest project.

References​

  • ADR-0024 — write contract, method resolution, .tools_local install prefix
  • ADR-0025 — discovering W
  • ADR-0026 — user-global esysrepo config exclusion
  • ADR-0021 — Amends vs Supersede

Amends​

  • (none)

Amended by​

  • (none)

Supersedes​

  • (none)

Superseded by​

  • (none)