@shortlink-org/portolan 0.1.0 → 0.2.1

package/README.md

@@ -1,17 +1,44 @@
-# portolan
+<p align="center">
+  <img src="./public/readme-header.webp" alt="A software architecture landscape mapped by Portolan" width="100%" />
+</p>
 
-A browser for a software estate's architecture catalog: systems or bounded
-contexts, components, interfaces, events, flows, stores and ADRs, read out of
-the code and specs that already describe them, and rendered as a navigable
-site. DDD enriches the model when a repository really uses it; it is not a
-prerequisite.
+<h1 align="center">Portolan</h1>
 
-The catalog and site are static end to end and require no backend. Optional
-branch comparison and source previews read immutable files from GitHub or
-GitLab at runtime; local development uses a localhost-only control plane.
+<p align="center"><strong>Your architecture, read from the code.</strong></p>
 
-Live: <https://shortlink-org.github.io/portolan/> (the example estate in
-`examples/`).
+<p align="center">
+  Turn code, contracts, schemas, traces and ADRs into a validated, navigable map of your software estate.
+</p>
+
+<p align="center">
+  <a href="https://shortlink-org.github.io/portolan/landing">View the product tour</a>
+  ·
+  <a href="https://shortlink-org.github.io/portolan/?catalog=example">Explore the example catalog</a>
+</p>
+
+## Make architecture visible — and keep it honest
+
+Architecture documentation loses value when it becomes another system teams
+must remember to maintain. Portolan starts with the evidence your repositories
+already contain and turns it into one coherent, searchable view of the system.
+
+See how bounded contexts, services, APIs, events, data stores, flows and
+decisions fit together. Follow any relationship back to its source. Surface
+missing contracts, ownership conflicts and architectural drift before they
+become production surprises.
+
+- **Understand the whole estate.** Move from the landscape to a single flow,
+  service, schema or decision without losing context.
+- **Trust what you see.** Portolan merges and validates facts from code,
+  specifications and observed traces instead of relying on a second hand-built
+  inventory.
+- **Publish anywhere.** The catalog and site are static end to end, require no
+  hosted backend and fit naturally into pull requests and CI.
+
+DDD enriches the model when a repository uses it; it is never a prerequisite.
+Optional branch comparison and source previews read immutable files from GitHub
+or GitLab at runtime, while local development uses a localhost-only control
+plane.
 
 ## What it does
 
@@ -49,45 +76,6 @@ Facts carry a status: `declared` (a fragment says so), `verified` (a recorded
 trace showed it happening), `unresolved` (nothing in the catalog answers the
 reference).
 
-### Projects without DDD
-
-`extract-project` is the neutral baseline. It reads repository metadata and
-deployment/build manifests without executing project code, creates a `system`,
-`product`, `team` or `namespace` containing a component, and records its role
-(`application`, `worker`, `job`, `cli`, `library`, and so on) and technologies.
-It also lists the commands the runner files declare - make targets, npm
-scripts, just recipes, Taskfile and poe/pdm tasks, Maven and Gradle goals,
-cargo aliases and xtask subcommands - which `extract-commands` does on its
-own for a service a domain extractor describes.
-Contract, messaging and data extractors then add OpenAPI, AsyncAPI, GraphQL,
-proto, SQL, Redis, River, Watermill and outbound HTTP/SOAP facts to that same
-component.
-For Go services, the HTTP client extractor also joins common router
-registrations to handlers, interface calls, string-keyed factory branches and
-concrete providers. Constructor maps, fixed factories, capability assertions,
-composite/direct field assignment and setter injection are followed when the
-source proves one concrete target. The resulting flow starts at the inbound
-endpoint and fans out by the provider choices proved by source; when a
-provider's transport lives in another module, the flow stops at that
-implementation and says that the outbound transport could not be resolved.
-Endpoints without provider selection are composed too, including handlers
-passed through closures and local variables. Swagger `@Router` evidence can
-root a handler factory behind a custom registry, while calls reached from a
-`main → Run` assembly path become startup flows. These generated transport and
-async flows carry their trigger kind and static-confidence level; `AddFunc`,
-`AfterFunc`, and `Schedule` registrations become scheduled roots. A transport
-fragment with no proven root is marked `unproven` instead of looking like a
-complete scenario.
-
-The older JSON keys `contexts` and `services` remain the wire format, so old
-catalogs need no migration (portolan.0004). Optional `kind` fields say when those nodes should
-be read as a neutral group and component. When `kind` is absent, the historical
-`bounded-context` and `service` meanings apply.
-
-The setup wizard always offers the neutral extractor. A language-specific DDD
-extractor is selected only when its expected model structure is present; a
-`go.mod` or a directory merely named `internal/domain` is not sufficient.
-
 ## What the site shows
 
 - **Entity pages** — context, service, aggregate (entities, value objects,
@@ -160,9 +148,19 @@ npx portolan generate
 npx portolan dev
 ```
 
-`init` writes a minimal `portolan.json`, adds `.portolan/` to `.gitignore`,
-and, when the repository has a `package.json`, adds these scripts without
-replacing scripts that are already there:
+`init` looks at the repository the way the site's Settings page does when a
+project is added: it finds the directories that hold a build file, the domain
+layouts, API specifications, schemas, migrations, ADRs and glossaries it can
+read, and proposes a `portolan.json` with an extractor for each. In a terminal
+it asks which directories are projects, what to read in each, and whether to
+run `portolan generate` straight away; every question has the detected answer
+as its default. With `--yes`, or without a terminal, it takes those defaults
+and asks nothing. A plugin whose toolchain is not on `PATH` is pointed out
+before anything is written.
+
+`init` never overwrites an existing `portolan.json`. It adds `.portolan/` to
+`.gitignore` and, when the repository has a `package.json`, adds these scripts
+without replacing scripts that are already there:
 
 ```json
 {
@@ -181,89 +179,30 @@ deployable static site.
 
 | command | purpose |
 | --- | --- |
-| `portolan init` | create the first manifest without overwriting an existing one |
+| `portolan init` | inspect the repository and write the first manifest; `--yes` takes every detected default |
 | `portolan dev` | run the local site and setup UI |
 | `portolan generate` | update fragments, documentation, and exports |
 | `portolan check` | fail when committed generated files are stale, without writing them |
 | `portolan build` | build the static site into `dist/` |
 | `portolan diff BASE` | describe the architecture change from a branch, tag, or commit |
-| `portolan doctor` | show which optional plugin toolchains are available |
-
-Node.js 24 is required. A process extractor also needs the toolchain of the
-language it reads: Go for the Go extractors, Python 3 for Python, Java 21 for
-Java, and Cargo for Rust. `portolan doctor` reports the local set. The Docker
-image contains all of them.
-
-### Check pull requests with GitHub Actions
-
-Generated files are checked rather than silently rewritten in CI:
-
-```yaml
-name: Architecture
-on: [pull_request]
-
-permissions:
-  contents: read
-
-jobs:
-  check:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v7
-        with:
-          fetch-depth: 0
-      - uses: shortlink-org/portolan@0.1.0
-        with:
-          command: check
-          version: 0.1.0
-```
+| `portolan doctor` | show which toolchains the manifest's plugins need and which are on `PATH` |
 
-Full history is required because fragments are stamped with the last commit
-that changed their input. A shallow clone would make that stamp unreliable.
-
-### Publish the site to GitHub Pages
-
-```yaml
-name: Architecture site
-on:
-  push:
-    branches: [main]
-  workflow_dispatch:
-
-permissions:
-  contents: read
-  pages: write
-  id-token: write
-
-jobs:
-  build:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v7
-      - uses: shortlink-org/portolan@0.1.0
-        with:
-          command: build
-          version: 0.1.0
-          output: dist
-          base: /${{ github.event.repository.name }}/
-      - uses: actions/configure-pages@v6
-      - uses: actions/upload-pages-artifact@v5
-        with:
-          path: dist
-
-  deploy:
-    needs: build
-    runs-on: ubuntu-latest
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
-    steps:
-      - id: deployment
-        uses: actions/deploy-pages@v5
-```
+Node.js 24 is required, and for a repository the built-in extractors can
+read on their own it is the only requirement: every Go plugin runs as one
+wasm module over the workspace (`adr/0006`), the fetchers run inside the
+host (`adr/0008`), and the package ships no Go at all. A Go, TypeScript,
+OpenAPI, proto, SQL or GraphQL tree is read, and another repository or a
+schema registry is vendored, with Node and git alone. An extractor that runs
+in its own runtime still needs it: Python 3 for Django and Celery, Java 21
+for Java, Cargo for Rust. `portolan doctor` reports what the manifest asks
+for against what is on `PATH`. The Docker image contains all of them.
+
+### Add delivery automation
 
-The action deliberately separates building from deployment, so the Pages
-permissions are held only by the deploy job.
+While `portolan dev` is running, open **Settings → Delivery presets**. Portolan
+detects GitHub or GitLab from the repository's `origin`, previews the exact CI
+changes, and installs architecture checks and static catalog publishing in one
+step. Existing unmanaged workflow files are never overwritten.
 
 ### Run without installing Node or language toolchains
 
@@ -276,7 +215,7 @@ docker run --rm \
   -e HOME=/tmp \
   -v "$PWD:/workspace" \
   -w /workspace \
-  ghcr.io/shortlink-org/portolan:0.1.0 generate
+  ghcr.io/shortlink-org/portolan:0.2.0 generate
 ```
 
 Use immutable versions in CI. `latest` is intended for trying the CLI, not for
@@ -310,78 +249,3 @@ Generated output is committed, so a change to it shows up in a diff. CI builds
 the site (`npm run build`); the `--check` variants and the test suites are run
 locally before a change lands, since they need the Go, Java, Rust and Python
 toolchains the plugins are written in.
-
-### Release Portolan
-
-Give the repository an `NPM_TOKEN` Actions secret that can publish the
-`@shortlink-org/portolan` package. Push a tag matching the version in
-`package.json`, for example `0.1.0`. The release workflow verifies the package,
-publishes it to npm with provenance, builds multi-platform container images at
-`ghcr.io/shortlink-org/portolan`, attests the image, and creates or updates the
-GitHub release notes. The tag itself is also the immutable version of the
-composite action used by consumer repositories.
-
-### In a pull request
-
-`gen:check` says the documentation follows from the catalog; it does not say
-what the change does. `.github/workflows/architecture-diff.yml` puts that on
-the pull request itself, without ever failing it:
-
-- one sticky comment with the events, endpoints, transitions and owners that
-  are not what they were, breaking first, ending in a link into the published
-  site's Changes page for the same pair of branches;
-- the same list as SARIF in the checks tab, breaking as errors, each result
-  anchored at the fragment that declares the id, so code scanning shows it;
-- the report again in the job summary, for whoever reads the run.
-
-The comment is `scripts/forge-comment.mjs` over the markdown `npm run diff`
-writes. It finds its own earlier comment by a marker and updates it in place.
-`GITHUB_TOKEN` with `pull-requests: write` is enough on GitHub; a pull request
-from a fork has a read-only token, and the step says so and stays green.
-
-The Changes page itself compares the built catalog with any branch or tag the
-forge lists, so the link in the comment works for a release just as well.
-
-On GitLab the job token cannot write notes, so the job wants a project access
-token with the `api` scope and the Reporter role as `PORTOLAN_TOKEN`:
-
-```yaml
-architecture-diff:
-  image: node:24
-  rules: [{ if: $CI_PIPELINE_SOURCE == "merge_request_event" }]
-  script:
-    - git fetch origin "$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
-    - npm ci
-    - node scripts/diff.mjs "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME" --site "$CI_PAGES_URL" --head "$CI_COMMIT_REF_NAME" --output .portolan/diff.md
-    - node scripts/forge-comment.mjs .portolan/diff.md
-```
-
-### In a release
-
-`.github/workflows/release-notes.yml` runs the same diff when a `v*` tag is
-pushed, against the tag before it, and `scripts/forge-release.mjs` writes it
-into the release as one section between two markers: the rest of the notes,
-hand-written or generated by the forge, stays as it was, and a rerun replaces
-the section rather than repeating it. A tag with no release yet gets one,
-named after the tag. The first tag of a repository has nothing to compare
-against, and the job says so and stops. The same job on GitLab:
-
-```yaml
-architecture-release:
-  image: node:24
-  rules: [{ if: $CI_COMMIT_TAG }]
-  script:
-    - git fetch --tags origin
-    - npm ci
-    - previous=$(git describe --tags --abbrev=0 "$CI_COMMIT_TAG^")
-    - node scripts/diff.mjs "$previous" --site "$CI_PAGES_URL" --head "$CI_COMMIT_TAG" --output .portolan/release.md
-    - node scripts/forge-release.mjs .portolan/release.md
-```
-
-Three build-time variables shape the chat:
-
-| variable | effect |
-|---|---|
-| `VITE_CHAT=off` | no chat at all: no button, no settings section, and its chunk is not built |
-| `VITE_CHAT_PROXY_URL` | the worker that answers with a key of its own (see `proxy/README.md`); unset, the chat waits for the reader's own model |
-| (a switch in Settings) | the reader turns the chat on or off in their browser; on by default when a proxy answers |

package/cli/init.mjs

@@ -0,0 +1,285 @@
+// `portolan init`: look at the repository, propose a manifest, write it.
+//
+// Detection is the same code the site's Settings page uses to add a project
+// (scripts/local-api.mjs), so the CLI and the UI agree on what a repository
+// contains. The prompts are the only thing this file adds; with `--yes`, or
+// without a terminal, every question takes its default.
+
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, posix, resolve } from "node:path";
+
+import * as p from "@clack/prompts";
+
+import { INSTALL_ROOT, builtinDefinition } from "../scripts/builtin-plugins.mjs";
+import { discoverProject, manifestWithProject, planProject, writeManifest } from "../scripts/local-api.mjs";
+
+const TOOLCHAINS = { go: "Go", cargo: "Cargo", java: "Java", python3: "Python 3" };
+const VERSION_FLAGS = { go: ["version"], cargo: ["--version"], java: ["-version"], python3: ["--version"] };
+
+export const SCRIPTS = {
+  "architecture": "portolan dev",
+  "architecture:gen": "portolan generate",
+  "architecture:check": "portolan check",
+  "architecture:build": "portolan build",
+};
+
+export class InitError extends Error {}
+
+/**
+ * Create portolan.json for `workspace`.
+ *
+ * `ask` answers the questions init has; `defaultAnswers` takes every default
+ * and `promptAnswers` asks a terminal. Returns what was done so the caller can
+ * continue with `portolan generate` when the user asked for it.
+ */
+export async function init(workspace, { version, ask = defaultAnswers, log = console.log } = {}) {
+  const manifestPath = resolve(workspace, "portolan.json");
+  if (existsSync(manifestPath)) throw new InitError("portolan.json already exists; init did not change it");
+
+  const projectPackage = readJson(resolve(workspace, "package.json"));
+  const repository = slug(String(projectPackage?.name ?? "").replace(/^@[^/]+\//, "")) || slug(basename(workspace)) || "project";
+
+  const scan = ask.scan?.() ?? null;
+  const discovery = discoverProject(workspace, ".");
+  scan?.done(discovery.filesScanned, discovery.truncated);
+
+  const roots = await ask.roots(rootChoices(discovery.components));
+  const single = roots.length === 1 && roots[0] === ".";
+
+  const projects = [];
+  const usedIds = new Set();
+  for (const root of roots) {
+    const found = root === "." ? discovery : discoverProject(workspace, root);
+    const id = single ? repository : uniqueId(root, usedIds);
+    const defaults = { id, name: titleOf(id), group: single ? id : repository, component: id };
+    const identity = single && found.detections.length ? await ask.identity(defaults) : defaults;
+    usedIds.add(identity.id);
+
+    const plugins = found.detections.length
+      ? await ask.plugins(root, found.detections.map((detection) => ({ ...detection, requirement: toolchainFor(detection.plugin) })))
+      : [];
+    projects.push({ root, ...identity, plugins });
+  }
+
+  const missing = missingToolchains(projects.flatMap((project) => project.plugins));
+  for (const [label, plugins] of missing) ask.warn(`${plugins.join(", ")} need${plugins.length === 1 ? "s" : ""} ${label}, which is not on PATH; portolan doctor lists the toolchains`);
+
+  const title = single ? projects[0].name : titleOf(repository);
+  const manifest = buildManifest(workspace, projects, { version, title });
+
+  const rows = projects.map((project) => [project.id, project.root, project.plugins.length ? project.plugins.join(", ") : "project (nothing detected)"]);
+  const widths = [0, 1].map((column) => Math.max(...rows.map((row) => row[column].length)));
+  const summary = rows.map((row) => `${row[0].padEnd(widths[0])}  ${row[1].padEnd(widths[1])}  ${row[2]}`);
+  if (!(await ask.write(summary))) throw new InitError("cancelled; nothing was written");
+  writeManifest(manifestPath, manifest);
+  log("created portolan.json");
+
+  const scripts = projectPackage ? await ask.scripts(Object.keys(SCRIPTS).filter((name) => !(name in (projectPackage.scripts ?? {})))) : false;
+  if (scripts) {
+    const merged = { ...(projectPackage.scripts ?? {}) };
+    for (const [name, command] of Object.entries(SCRIPTS)) if (!(name in merged)) merged[name] = command;
+    writeFileSync(resolve(workspace, "package.json"), `${JSON.stringify({ ...projectPackage, scripts: merged }, null, 2)}\n`);
+    log("added architecture scripts to package.json");
+  }
+
+  const ignorePath = resolve(workspace, ".gitignore");
+  const ignore = existsSync(ignorePath) ? readFileSync(ignorePath, "utf8") : "";
+  if (!ignore.split(/\r?\n/).includes(".portolan/")) {
+    writeFileSync(ignorePath, `${ignore}${ignore && !ignore.endsWith("\n") ? "\n" : ""}\n# Portolan local build state\n.portolan/\n`);
+  }
+
+  const generate = await ask.generate();
+  ask.finish(generate);
+  return { manifest, projects, generate };
+}
+
+/** Every question answered with its default: the `--yes` and CI path. */
+export const defaultAnswers = {
+  roots: (choices) => choices.filter((choice) => choice.selected).map((choice) => choice.path),
+  identity: (defaults) => defaults,
+  plugins: (root, detections) => detections.filter((detection) => detection.selected && detection.confidence === "high").map((detection) => detection.plugin),
+  warn: (message) => console.warn(`portolan: ${message}`),
+  write: () => true,
+  scripts: (names) => names.length > 0,
+  generate: () => false,
+  finish: (generate) => { if (!generate) console.log("next: portolan generate && portolan dev"); },
+};
+
+/** The same questions, asked in a terminal with @clack/prompts. */
+export function promptAnswers(version) {
+  p.intro(`portolan ${version}`);
+  let spinner;
+  return {
+    scan() {
+      spinner = p.spinner();
+      spinner.start("Scanning the repository");
+      return {
+        done(files, truncated) {
+          spinner.stop(`Scanned ${files} files${truncated ? " (stopped early; a large repository)" : ""}`);
+        },
+      };
+    },
+    async roots(choices) {
+      if (choices.length <= 1) return defaultAnswers.roots(choices);
+      return answer(await p.multiselect({
+        message: "Which directories are projects?",
+        options: choices.map((choice) => ({ value: choice.path, label: choice.path, hint: [choice.name, choice.technologies.join(", ")].filter(Boolean).join(" · ") })),
+        initialValues: defaultAnswers.roots(choices),
+        required: true,
+      }));
+    },
+    async identity(defaults) {
+      const id = answer(await p.text({
+        message: "Project id",
+        initialValue: defaults.id,
+        validate: (value) => (slug(value) ? undefined : "Use letters, digits and dashes."),
+      }));
+      const clean = slug(id);
+      return clean === defaults.id ? defaults : { ...defaults, id: clean, name: titleOf(clean), group: clean, component: clean };
+    },
+    async plugins(root, detections) {
+      const chosen = answer(await p.multiselect({
+        message: root === "." ? "What should Portolan read?" : `What should Portolan read in ${root}?`,
+        options: detections.map((detection) => ({
+          value: detection.plugin,
+          label: detection.plugin,
+          hint: [detection.evidence, detection.requirement?.missing ? `needs ${detection.requirement.label}, not on PATH` : ""].filter(Boolean).join(" · "),
+        })),
+        initialValues: defaultAnswers.plugins(root, detections),
+        required: true,
+      }));
+      return chosen;
+    },
+    warn: (message) => p.log.warn(message),
+    async write(summary) {
+      p.note(summary.join("\n"), "portolan.json");
+      return answer(await p.confirm({ message: "Write portolan.json?", initialValue: true }));
+    },
+    async scripts(names) {
+      if (!names.length) return false;
+      return answer(await p.confirm({ message: `Add ${names.join(", ")} to package.json scripts?`, initialValue: true }));
+    },
+    async generate() {
+      return answer(await p.confirm({ message: "Run portolan generate now?", initialValue: true }));
+    },
+    finish(generate) {
+      p.outro(generate ? "Generating; then: portolan dev" : "Next: portolan generate && portolan dev");
+    },
+  };
+}
+
+export function isInteractive(env = process.env) {
+  return Boolean(process.stdin.isTTY && process.stdout.isTTY) && !env.CI;
+}
+
+export function commandWorks(command, args) {
+  const result = spawnSync(command, args, { stdio: "ignore" });
+  return !result.error && result.status === 0;
+}
+
+function answer(value) {
+  if (p.isCancel(value)) {
+    p.cancel("init cancelled; nothing was written");
+    process.exit(0);
+  }
+  return value;
+}
+
+/**
+ * Directories that could be projects, with the default choice made: the
+ * repository root when it has a build file of its own, otherwise every nested
+ * directory that has one.
+ */
+function rootChoices(components) {
+  const rootHasMarkers = components.some((candidate) => candidate.path === ".");
+  const nested = components.filter((candidate) => candidate.path !== ".");
+  const choices = [
+    { path: ".", name: "repository root", markers: [], technologies: [], ...components.find((candidate) => candidate.path === ".") },
+    ...nested,
+  ];
+  return choices.map((choice) => ({ ...choice, selected: choice.path === "." ? rootHasMarkers || nested.length === 0 : !rootHasMarkers }));
+}
+
+function buildManifest(workspace, projects, { version, title }) {
+  let manifest = {
+    $schema: `https://raw.githubusercontent.com/shortlink-org/portolan/${version}/schema/portolan.schema.json`,
+    sources: [],
+    projects: [],
+    extract: [],
+  };
+  for (const project of projects) {
+    if (project.plugins.length) {
+      const plan = planProject(workspace, manifest, {
+        root: project.root,
+        id: project.id,
+        name: project.name,
+        group: project.group,
+        component: project.component,
+        plugins: project.plugins,
+      });
+      manifest = manifestWithProject(manifest, plan);
+      continue;
+    }
+    // Nothing to read yet; the project extractor still gives the site one node.
+    const out = posix.join(project.root, "portolan");
+    manifest.projects.push({ id: project.id, name: project.name, root: project.root, group: project.group, component: project.component });
+    manifest.sources.push(`${out}/*.json`);
+    manifest.extract.push({
+      plugin: "project",
+      in: project.root,
+      out,
+      options: { group: project.group, groupName: titleOf(project.group), component: project.component, componentName: project.name, out: "project.json" },
+    });
+  }
+  manifest.sources = [...new Set(manifest.sources)];
+  manifest.generate = [
+    { plugin: "markdown", out: "docs", options: { title } },
+    { plugin: "mermaid", out: "exports/mermaid", options: { title: `${title} flows` } },
+  ];
+  return manifest;
+}
+
+const toolchainChecks = new Map();
+
+export function toolchainFor(plugin, declared = null) {
+  const command = declared?.process?.command ?? builtinDefinition(plugin)?.process?.command;
+  const label = TOOLCHAINS[command];
+  if (!label) return null;
+  if (!toolchainChecks.has(command)) {
+    // The Rust extractor ships as a binary in the Docker image, and
+    // run-builtin uses it before it would ever ask for Cargo; doctor and init
+    // agree, or the image would report a toolchain it does not need.
+    const prebuilt = command === "cargo" && !declared && existsSync(resolve(INSTALL_ROOT, "plugins/extract-rust/target/release/portolan-extract-rust"));
+    toolchainChecks.set(command, prebuilt || commandWorks(command, VERSION_FLAGS[command]));
+  }
+  return { command, label, missing: !toolchainChecks.get(command) };
+}
+
+function missingToolchains(plugins) {
+  const missing = new Map();
+  for (const plugin of new Set(plugins)) {
+    const need = toolchainFor(plugin);
+    if (!need?.missing) continue;
+    missing.set(need.label, [...(missing.get(need.label) ?? []), plugin]);
+  }
+  return missing;
+}
+
+function uniqueId(root, used) {
+  const short = slug(posix.basename(root));
+  if (short && !used.has(short)) return short;
+  return slug(root) || `project-${used.size + 1}`;
+}
+
+function readJson(path) {
+  try { return JSON.parse(readFileSync(path, "utf8")); } catch { return null; }
+}
+
+export function slug(value) {
+  return String(value).toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+}
+
+export function titleOf(value) {
+  return value.split("-").filter(Boolean).map((part) => part[0].toUpperCase() + part.slice(1)).join(" ");
+}