@topogram/cli 0.3.63 → 0.3.64

package/src/github-client.js

@@ -0,0 +1,520 @@
+// @ts-check
+
+import childProcess from "node:child_process";
+
+const DEFAULT_GITHUB_API_BASE_URL = "https://api.github.com";
+const GITHUB_REST_SCRIPT = `
+const request = JSON.parse(process.argv[1]);
+const base = String(request.baseUrl || "https://api.github.com").replace(/\\/+$/, "") + "/";
+const path = String(request.path || "").replace(/^\\/+/, "");
+const url = new URL(path, base);
+for (const [key, value] of Object.entries(request.query || {})) {
+  if (value === null || value === undefined || value === "") continue;
+  url.searchParams.set(key, String(value));
+}
+function canAttachToken(urlValue) {
+  const hostname = new URL(urlValue).hostname.toLowerCase();
+  return hostname === "api.github.com" || hostname.endsWith(".github.com");
+}
+const headers = {
+  accept: "application/vnd.github+json",
+  "user-agent": "topogram-cli",
+  "x-github-api-version": "2022-11-28"
+};
+if (request.token && canAttachToken(url)) {
+  headers.authorization = "Bearer " + request.token;
+}
+if (process.env.TOPOGRAM_GITHUB_API_FIXTURE_ROOT) {
+  const fs = await import("node:fs");
+  const pathModule = await import("node:path");
+  const segments = path.split("/").filter(Boolean);
+  if (segments.some((segment) => segment === ".." || segment.includes("\\\\") || segment.includes("\\0"))) {
+    process.stderr.write("Unsafe GitHub API fixture path.");
+    process.exit(1);
+  }
+  if (process.env.TOPOGRAM_GITHUB_API_FIXTURE_LOG) {
+    fs.appendFileSync(process.env.TOPOGRAM_GITHUB_API_FIXTURE_LOG, JSON.stringify({
+      path,
+      search: url.search,
+      tokenPresent: Boolean(request.token),
+      tokenWouldAttach: Boolean(request.token && canAttachToken(url))
+    }) + "\\n", "utf8");
+  }
+  const fixturePath = pathModule.join(process.env.TOPOGRAM_GITHUB_API_FIXTURE_ROOT, ...segments) + ".json";
+  if (!fs.existsSync(fixturePath)) {
+    process.stderr.write(JSON.stringify({
+      status: 404,
+      statusText: "Not Found",
+      body: JSON.stringify({ message: "Fixture Not Found", path }),
+      url: url.toString()
+    }));
+    process.exit(2);
+  }
+  process.stdout.write(JSON.stringify({
+    status: 200,
+    body: fs.readFileSync(fixturePath, "utf8"),
+    url: url.toString()
+  }));
+  process.exit(0);
+}
+try {
+  const response = await fetch(url, { headers });
+  const text = await response.text();
+  if (!response.ok) {
+    process.stderr.write(JSON.stringify({
+      status: response.status,
+      statusText: response.statusText,
+      body: text,
+      url: url.toString()
+    }));
+    process.exit(2);
+  }
+  process.stdout.write(JSON.stringify({
+    status: response.status,
+    body: text,
+    url: url.toString()
+  }));
+} catch (error) {
+  process.stderr.write(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+}
+`;
+
+/**
+ * @typedef {Object} GitHubCliStatus
+ * @property {boolean} checked
+ * @property {boolean} available
+ * @property {boolean} authenticated
+ * @property {string|null} reason
+ */
+
+/**
+ * @typedef {Object} GitHubRun
+ * @property {number|string|undefined} [databaseId]
+ * @property {string|undefined} [workflowName]
+ * @property {string|undefined} [status]
+ * @property {string|undefined} [conclusion]
+ * @property {string|undefined} [headSha]
+ * @property {string|undefined} [url]
+ */
+
+/**
+ * @typedef {Object} GitHubJob
+ * @property {number|string|undefined} [databaseId]
+ * @property {string|undefined} [name]
+ * @property {string|undefined} [status]
+ * @property {string|undefined} [conclusion]
+ * @property {string|undefined} [url]
+ */
+
+export class GitHubClientError extends Error {
+  /**
+   * @param {string} message
+   * @param {{ status?: number|null, statusText?: string|null, body?: string|null, url?: string|null, command?: string|null }} [details]
+   */
+  constructor(message, details = {}) {
+    super(message);
+    this.name = "GitHubClientError";
+    this.status = details.status ?? null;
+    this.statusText = details.statusText ?? null;
+    this.body = details.body ?? null;
+    this.url = details.url ?? null;
+    this.command = details.command ?? null;
+  }
+}
+
+/**
+ * @returns {string|null}
+ */
+export function githubTokenFromEnv() {
+  return process.env.GITHUB_TOKEN || process.env.GH_TOKEN || null;
+}
+
+/**
+ * @returns {string}
+ */
+export function githubApiBaseUrl() {
+  return process.env.TOPOGRAM_GITHUB_API_BASE_URL || DEFAULT_GITHUB_API_BASE_URL;
+}
+
+/**
+ * @returns {boolean}
+ */
+function shouldUseRestApi() {
+  return Boolean(githubTokenFromEnv());
+}
+
+/**
+ * @param {string} path
+ * @param {{ query?: Record<string, string|number|boolean|null|undefined> }} [options]
+ * @returns {any}
+ */
+function githubRequestJson(path, options = {}) {
+  const result = childProcess.spawnSync(process.execPath, [
+    "--input-type=module",
+    "-e",
+    GITHUB_REST_SCRIPT,
+    JSON.stringify({
+      baseUrl: githubApiBaseUrl(),
+      path,
+      query: options.query || {},
+      token: githubTokenFromEnv() || ""
+    })
+  ], {
+    encoding: "utf8",
+    env: {
+      ...process.env,
+      PATH: process.env.PATH || ""
+    }
+  });
+  if (result.status !== 0) {
+    const error = parseRestError(result);
+    throw new GitHubClientError(formatRestErrorMessage(error), error);
+  }
+  /** @type {any} */
+  let payload = {};
+  try {
+    payload = JSON.parse(String(result.stdout || "{}"));
+  } catch (error) {
+    throw new GitHubClientError(`GitHub REST response was not valid JSON: ${messageFromError(error)}`);
+  }
+  const body = typeof payload.body === "string" ? payload.body : "";
+  try {
+    return body ? JSON.parse(body) : null;
+  } catch (error) {
+    throw new GitHubClientError(`GitHub REST body was not valid JSON: ${messageFromError(error)}`, {
+      body,
+      url: typeof payload.url === "string" ? payload.url : null
+    });
+  }
+}
+
+/**
+ * @param {ReturnType<typeof childProcess.spawnSync>} result
+ * @returns {{ status: number|null, statusText: string|null, body: string|null, url: string|null }}
+ */
+function parseRestError(result) {
+  if (result.status === 2) {
+    try {
+      const payload = JSON.parse(String(result.stderr || "{}"));
+      return {
+        status: Number.isFinite(payload.status) ? payload.status : null,
+        statusText: typeof payload.statusText === "string" ? payload.statusText : null,
+        body: typeof payload.body === "string" ? payload.body : null,
+        url: typeof payload.url === "string" ? payload.url : null
+      };
+    } catch {
+      // Fall through to the generic shape below.
+    }
+  }
+  return {
+    status: null,
+    statusText: null,
+    body: [result.error?.message, result.stderr, result.stdout].filter(Boolean).join("\n").trim() || null,
+    url: null
+  };
+}
+
+/**
+ * @param {{ status: number|null, statusText: string|null, body: string|null, url: string|null }} error
+ * @returns {string}
+ */
+function formatRestErrorMessage(error) {
+  const status = error.status ? `${error.status}${error.statusText ? ` ${error.statusText}` : ""}` : "failed";
+  const body = String(error.body || "").trim();
+  return [`GitHub REST request ${status}.`, body.slice(0, 800)].filter(Boolean).join("\n");
+}
+
+/**
+ * @param {unknown} error
+ * @returns {string}
+ */
+function messageFromError(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/**
+ * @param {string} source
+ * @returns {{ owner: string, repo: string, filePath: string, ref: string|null }}
+ */
+export function parseGithubCatalogSource(source) {
+  const spec = source.slice("github:".length);
+  const [pathPart, ref] = spec.split("?ref=");
+  const segments = pathPart.split("/").filter(Boolean);
+  if (segments.length < 3) {
+    throw new Error(`Invalid GitHub catalog source '${source}'. Expected github:owner/repo/path/to/catalog.json.`);
+  }
+  const [owner, repo, ...fileSegments] = segments;
+  return {
+    owner,
+    repo,
+    filePath: fileSegments.join("/"),
+    ref: ref || null
+  };
+}
+
+/**
+ * @param {string} source
+ * @returns {string}
+ */
+export function readGithubCatalogSourceText(source) {
+  const parsed = parseGithubCatalogSource(source);
+  if (shouldUseRestApi()) {
+    try {
+      const payload = githubRequestJson(`repos/${parsed.owner}/${parsed.repo}/contents/${parsed.filePath}`, {
+        query: parsed.ref ? { ref: parsed.ref } : {}
+      });
+      const content = typeof payload?.content === "string" ? payload.content : "";
+      return Buffer.from(content.replace(/\s+/g, ""), "base64").toString("utf8");
+    } catch (error) {
+      throw new Error(formatGithubCatalogError(source, error, "rest"));
+    }
+  }
+  const result = runGh(githubCatalogGhArgs(parsed));
+  if (result.status !== 0) {
+    throw new Error(formatGithubCatalogError(source, result, "gh"));
+  }
+  return Buffer.from(String(result.stdout || "").replace(/\s+/g, ""), "base64").toString("utf8");
+}
+
+/**
+ * @param {{ owner: string, repo: string, filePath: string, ref: string|null }} parsed
+ * @returns {string[]}
+ */
+function githubCatalogGhArgs(parsed) {
+  const args = ["api", `repos/${parsed.owner}/${parsed.repo}/contents/${parsed.filePath}`, "--jq", ".content"];
+  if (parsed.ref) {
+    args.splice(2, 0, "-f", `ref=${parsed.ref}`);
+  }
+  return args;
+}
+
+/**
+ * @param {string} source
+ * @param {unknown} error
+ * @param {"rest"|"gh"} mode
+ * @returns {string}
+ */
+function formatGithubCatalogError(source, error, mode) {
+  const output = githubErrorOutput(error);
+  const normalized = output.toLowerCase();
+  const commandError = error && typeof error === "object" && "error" in error
+    ? /** @type {{ error?: { code?: string } }} */ (error)
+    : null;
+  if (mode === "gh" && commandError?.error?.code === "ENOENT") {
+    return [
+      `GitHub CLI (gh) is required to read catalog '${source}' without GITHUB_TOKEN or GH_TOKEN.`,
+      "Install gh, set GITHUB_TOKEN or GH_TOKEN, or set TOPOGRAM_CATALOG_SOURCE to a local topograms.catalog.json file."
+    ].join("\n");
+  }
+  if (/\b(401|403)\b/.test(normalized) || normalized.includes("authentication") || normalized.includes("not logged in") || normalized.includes("forbidden")) {
+    return [
+      `Authentication is required to read private catalog '${source}'.`,
+      "Set GITHUB_TOKEN or GH_TOKEN with repository read access, or run gh auth login as a local fallback.",
+      output
+    ].filter(Boolean).join("\n");
+  }
+  if (/\b404\b/.test(normalized) || normalized.includes("not found")) {
+    return [
+      `Catalog source '${source}' was not found, or the current token does not have repository access.`,
+      "Check the github:owner/repo/path source and grant repository read access to the token or GitHub Actions workflow.",
+      output
+    ].filter(Boolean).join("\n");
+  }
+  return [
+    `Failed to read catalog '${source}' with ${mode === "rest" ? "GitHub REST API" : "gh api"}.`,
+    "Set GITHUB_TOKEN or GH_TOKEN, or run gh auth login as a local fallback.",
+    output || "unknown error"
+  ].join("\n");
+}
+
+/**
+ * @param {unknown} error
+ * @returns {string}
+ */
+function githubErrorOutput(error) {
+  if (error instanceof GitHubClientError) {
+    return [error.message, error.body].filter(Boolean).join("\n").trim();
+  }
+  if (error && typeof error === "object" && ("stdout" in error || "stderr" in error || "error" in error)) {
+    const result = /** @type {{ stdout?: string, stderr?: string, error?: Error }} */ (error);
+    return [result.error?.message, result.stderr, result.stdout].filter(Boolean).join("\n").trim();
+  }
+  return messageFromError(error);
+}
+
+/**
+ * @param {{ repoSlug: string, branch?: string, workflowName: string, cwd?: string|null }} input
+ * @returns {GitHubRun|null}
+ */
+export function latestWorkflowRun(input) {
+  if (shouldUseRestApi()) {
+    const payload = githubRequestJson(`repos/${input.repoSlug}/actions/runs`, {
+      query: {
+        branch: input.branch || "main",
+        per_page: 50
+      }
+    });
+    const runs = /** @type {any[]} */ (Array.isArray(payload?.workflow_runs) ? payload.workflow_runs : []);
+    const run = runs.find((candidate) => workflowRunName(candidate) === input.workflowName) || null;
+    return run ? normalizeWorkflowRun(run, input.workflowName) : null;
+  }
+  const result = runGh([
+    "run",
+    "list",
+    "--repo",
+    input.repoSlug,
+    "--branch",
+    input.branch || "main",
+    "--workflow",
+    input.workflowName,
+    "--limit",
+    "1",
+    "--json",
+    "databaseId,workflowName,status,conclusion,headSha,url"
+  ], input.cwd || undefined);
+  if (result.status !== 0) {
+    throw new GitHubClientError("GitHub CLI workflow run lookup failed.", {
+      body: githubErrorOutput(result),
+      command: "gh run list"
+    });
+  }
+  /** @type {any[]} */
+  let runs = [];
+  try {
+    runs = JSON.parse(String(result.stdout || "[]"));
+  } catch (error) {
+    throw new GitHubClientError(`GitHub CLI workflow run output was not valid JSON: ${messageFromError(error)}`, {
+      body: String(result.stdout || "")
+    });
+  }
+  return Array.isArray(runs) && runs.length > 0 ? normalizeWorkflowRun(runs[0], input.workflowName) : null;
+}
+
+/**
+ * @param {any} run
+ * @returns {string|null}
+ */
+function workflowRunName(run) {
+  return typeof run?.workflowName === "string"
+    ? run.workflowName
+    : typeof run?.name === "string"
+      ? run.name
+      : null;
+}
+
+/**
+ * @param {any} run
+ * @param {string} fallbackWorkflowName
+ * @returns {GitHubRun}
+ */
+function normalizeWorkflowRun(run, fallbackWorkflowName) {
+  return {
+    databaseId: run.databaseId ?? run.id,
+    workflowName: run.workflowName || run.name || fallbackWorkflowName,
+    status: run.status,
+    conclusion: run.conclusion,
+    headSha: run.headSha || run.head_sha,
+    url: run.html_url || run.url
+  };
+}
+
+/**
+ * @param {{ repoSlug: string, runId: number|string, cwd?: string|null }} input
+ * @returns {GitHubJob[]}
+ */
+export function workflowRunJobs(input) {
+  if (shouldUseRestApi()) {
+    const payload = githubRequestJson(`repos/${input.repoSlug}/actions/runs/${input.runId}/jobs`, {
+      query: { per_page: 100 }
+    });
+    const jobs = /** @type {any[]} */ (Array.isArray(payload?.jobs) ? payload.jobs : []);
+    return jobs.map(normalizeWorkflowJob);
+  }
+  const result = runGh([
+    "run",
+    "view",
+    String(input.runId),
+    "--repo",
+    input.repoSlug,
+    "--json",
+    "jobs"
+  ], input.cwd || undefined);
+  if (result.status !== 0) {
+    throw new GitHubClientError("GitHub CLI workflow job lookup failed.", {
+      body: githubErrorOutput(result),
+      command: "gh run view"
+    });
+  }
+  /** @type {any} */
+  let payload = {};
+  try {
+    payload = JSON.parse(String(result.stdout || "{}"));
+  } catch (error) {
+    throw new GitHubClientError(`GitHub CLI workflow job output was not valid JSON: ${messageFromError(error)}`, {
+      body: String(result.stdout || "")
+    });
+  }
+  const jobs = Array.isArray(payload.jobs) ? payload.jobs : [];
+  return jobs.map(normalizeWorkflowJob);
+}
+
+/**
+ * @param {any} job
+ * @returns {GitHubJob}
+ */
+function normalizeWorkflowJob(job) {
+  return {
+    databaseId: job.databaseId ?? job.id,
+    name: job.name,
+    status: job.status,
+    conclusion: job.conclusion,
+    url: job.html_url || job.url
+  };
+}
+
+/**
+ * @param {string[]} args
+ * @param {string} [cwd]
+ * @returns {ReturnType<typeof childProcess.spawnSync>}
+ */
+function runGh(args, cwd = process.cwd()) {
+  return childProcess.spawnSync("gh", args, {
+    cwd,
+    encoding: "utf8",
+    env: {
+      ...process.env,
+      GH_TOKEN: process.env.GH_TOKEN || process.env.GITHUB_TOKEN || "",
+      PATH: process.env.PATH || ""
+    }
+  });
+}
+
+/**
+ * @param {{ checkGh?: boolean }} [options]
+ * @returns {{ githubTokenEnv: boolean, ghTokenEnv: boolean, ghCli: GitHubCliStatus }}
+ */
+export function githubAuthStatus(options = {}) {
+  /** @type {GitHubCliStatus} */
+  const ghCli = {
+    checked: Boolean(options.checkGh),
+    available: false,
+    authenticated: false,
+    reason: null
+  };
+  if (options.checkGh) {
+    const result = runGh(["auth", "token"]);
+    ghCli.available = result.error?.code !== "ENOENT";
+    ghCli.authenticated = result.status === 0 && Boolean(String(result.stdout || "").trim());
+    if (!ghCli.available) {
+      ghCli.reason = "GitHub CLI (gh) is not installed or not on PATH.";
+    } else if (!ghCli.authenticated) {
+      ghCli.reason = (result.stderr || result.stdout || result.error?.message || "gh auth token failed.").trim();
+    }
+  }
+  return {
+    githubTokenEnv: Boolean(process.env.GITHUB_TOKEN),
+    ghTokenEnv: Boolean(process.env.GH_TOKEN),
+    ghCli
+  };
+}

package/src/import/core/shared.js

@@ -1,6 +1,26 @@
 import fs from "node:fs";
 import path from "node:path";
 
+import { relativeTo } from "../../path-helpers.js";
+import {
+  canonicalCandidateTerm,
+  ensureTrailingNewline,
+  idHintify,
+  pluralizeCandidateTerm,
+  slugify,
+  titleCase
+} from "../../text-helpers.js";
+
+export {
+  canonicalCandidateTerm,
+  ensureTrailingNewline,
+  idHintify,
+  pluralizeCandidateTerm,
+  relativeTo,
+  slugify,
+  titleCase
+};
+
 export const DEFAULT_IGNORED_DIRS = new Set([
   ".git",
   ".next",
@@ -13,64 +33,6 @@ export const DEFAULT_IGNORED_DIRS = new Set([
   "tmp"
 ]);
 
-export function ensureTrailingNewline(value) {
-  return value.endsWith("\n") ? value : `${value}\n`;
-}
-
-export function slugify(value) {
-  return String(value || "")
-    .trim()
-    .toLowerCase()
-    .replace(/[^a-z0-9]+/g, "-")
-    .replace(/^-+|-+$/g, "") || "untitled";
-}
-
-export function idHintify(value) {
-  return String(value || "")
-    .trim()
-    .toLowerCase()
-    .replace(/[^a-z0-9]+/g, "_")
-    .replace(/^_+|_+$/g, "") || "untitled";
-}
-
-export function canonicalCandidateTerm(value) {
-  const normalized = slugify(value);
-  if (normalized.endsWith("ies")) {
-    return `${normalized.slice(0, -3)}y`;
-  }
-  if (normalized === "status" || normalized === "stats") {
-    return normalized;
-  }
-  if (normalized.endsWith("s") && !normalized.endsWith("ss") && !normalized.endsWith("us") && !normalized.endsWith("is")) {
-    return normalized.slice(0, -1);
-  }
-  return normalized;
-}
-
-export function pluralizeCandidateTerm(value) {
-  const normalized = String(value || "");
-  if (!normalized) return "items";
-  const parts = normalized.split("_");
-  const last = parts.pop() || "item";
-  let plural = last;
-  if (last.endsWith("y") && !/[aeiou]y$/.test(last)) {
-    plural = `${last.slice(0, -1)}ies`;
-  } else if (/(s|x|z|ch|sh)$/.test(last)) {
-    plural = `${last}es`;
-  } else {
-    plural = `${last}s`;
-  }
-  return [...parts, plural].join("_");
-}
-
-export function titleCase(value) {
-  return String(value || "")
-    .split(/[_\-\s]+/)
-    .filter(Boolean)
-    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
-    .join(" ");
-}
-
 export function readTextIfExists(filePath) {
   return fs.existsSync(filePath) ? fs.readFileSync(filePath, "utf8") : null;
 }
@@ -107,10 +69,6 @@ export function listFilesRecursive(rootDir, predicate = () => true, options = {}
   return files.sort();
 }
 
-export function relativeTo(base, filePath) {
-  return path.relative(base, filePath).replaceAll(path.sep, "/");
-}
-
 export function importSearchRoots(paths) {
   return [...new Set([paths.workspaceRoot, paths.topogramRoot].filter(Boolean))];
 }

package/src/import/extractors/api/flutter-dio.js

@@ -3,6 +3,7 @@ import {
   dedupeCandidateRecords,
   findImportFiles,
   makeCandidateRecord,
+  pluralizeCandidateTerm,
   relativeTo,
   titleCase
 } from "../../core/shared.js";
@@ -11,16 +12,11 @@ function featureStemFromPath(filePath) {
   return canonicalCandidateTerm(filePath.match(/\/features\/([^/]+)\//)?.[1] || "item");
 }
 
-function pluralizeStem(stem) {
-  if (stem.endsWith("s")) return stem;
-  return `${stem}s`;
-}
-
 function capabilityIdFor(featureStem, methodName, httpMethod) {
   const stem = canonicalCandidateTerm(featureStem);
   const normalizedMethod = String(methodName || "").toLowerCase();
   if (httpMethod === "GET") {
-    return `cap_list_${pluralizeStem(stem)}`;
+    return `cap_list_${pluralizeCandidateTerm(stem)}`;
   }
   if (httpMethod === "POST") {
     return `cap_create_${stem}`;
@@ -59,12 +55,12 @@ function parseDatasourceFile(text, provenance, filePath, apiConfigPaths) {
     const httpMethod = dioCall[1].toUpperCase();
     const callArgs = dioCall[2];
     const apiRef = callArgs.match(/ApiConfig\.([A-Za-z_][A-Za-z0-9_]*)/);
-    const basePath = apiConfigPaths.get(apiRef?.[1] || "") || `/${pluralizeStem(featureStem)}`;
+    const basePath = apiConfigPaths.get(apiRef?.[1] || "") || `/${pluralizeCandidateTerm(featureStem)}`;
     const dynamicPath = callArgs.match(/"\$\{ApiConfig\.[A-Za-z_][A-Za-z0-9_]*\}\/\$\{[^}]+\}"/);
     const path = dynamicPath ? `${basePath}/{id}` : basePath;
     const queryParams = [...body.matchAll(/'([^']+)'\s*:\s*[^,}]+/g)]
       .map((entry) => ({ name: entry[1], required: false, type: null }));
-    const outputFields = /^GET$/.test(httpMethod) ? [pluralizeStem(featureStem)] : [];
+    const outputFields = /^GET$/.test(httpMethod) ? [pluralizeCandidateTerm(featureStem)] : [];
     const inputFields = [...new Set([...callArgs.matchAll(/data:\s*([A-Za-z_][A-Za-z0-9_]*)/g)].map((entry) => entry[1]))];
     capabilities.push(makeCandidateRecord({
       kind: "capability",

package/src/import/extractors/api/react-native-repository.js

@@ -3,15 +3,11 @@ import {
   dedupeCandidateRecords,
   findImportFiles,
   makeCandidateRecord,
+  pluralizeCandidateTerm,
   relativeTo,
   titleCase
 } from "../../core/shared.js";
 
-function pluralizeStem(stem) {
-  if (stem.endsWith("s")) return stem;
-  return `${stem}s`;
-}
-
 function stemFromRepoPath(filePath) {
   return canonicalCandidateTerm(filePath.match(/\/src\/([^/]+)\//)?.[1] || "item");
 }
@@ -22,7 +18,7 @@ function capabilityIdFor(stem, methodName, httpMethod) {
     return `cap_get_${stem}`;
   }
   if (httpMethod === "GET") {
-    return `cap_list_${pluralizeStem(stem)}`;
+    return `cap_list_${pluralizeCandidateTerm(stem)}`;
   }
   if (httpMethod === "POST") {
     return `cap_create_${stem}`;
@@ -39,7 +35,7 @@ function capabilityIdFor(stem, methodName, httpMethod) {
 function parseRepositoryFile(text, provenance, filePath) {
   const stem = stemFromRepoPath(filePath);
   const baseUrlMatch = String(text || "").match(/baseUrl\s*=\s*["'`]([^"'`]+)["'`]/);
-  const basePath = baseUrlMatch?.[1] || `/${pluralizeStem(stem)}`;
+  const basePath = baseUrlMatch?.[1] || `/${pluralizeCandidateTerm(stem)}`;
   const capabilities = [];
   const methods = [...String(text || "").matchAll(/public\s+async\s+([A-Za-z_][A-Za-z0-9_]*)\(([\s\S]*?)\)\s*(?::\s*[\s\S]*?)?\s*\{/g)];
   for (let index = 0; index < methods.length; index += 1) {
@@ -59,7 +55,7 @@ function parseRepositoryFile(text, provenance, filePath) {
       ...[...String(body || "").matchAll(/payload\.([A-Za-z_][A-Za-z0-9_]*)/g)].map((entry) => entry[1])
     ])].filter((field) => field !== "id");
     const outputFields = httpMethod === "GET"
-      ? (/count/.test(body) ? [pluralizeStem(stem), "count"] : (/map\(/.test(body) ? [pluralizeStem(stem)] : ["id", "title", "body"]))
+      ? (/count/.test(body) ? [pluralizeCandidateTerm(stem), "count"] : (/map\(/.test(body) ? [pluralizeCandidateTerm(stem)] : ["id", "title", "body"]))
       : [];
     capabilities.push(makeCandidateRecord({
       kind: "capability",