types(mcp): type the stdio CLI's option plumbing, fixing three crashes it hid (#9773)

`parseOptions` is now typed from CLI_FLAG_SPEC -- repeatable flags as arrays, boolean flags as
booleans, anything else as `string | boolean` behind an index signature, because the parser
genuinely accepts any `--flag` and a closed record would be a lie. That type flows into every
`options` parameter, every argv parameter becomes `readonly string[]`, and the config parameters
take the contract's LoopoverConfig.

Three defects fell out immediately, each reproduced against main before the fix:

  TypeError: (options[key] ?? []) is not iterable
  repoFullName.includes is not a function
  LoopOver API 404: {"error":"not_found"}

The first is `--issue --issue 5`: a bare repeatable flag is stored as `true` by the no-value
branch, and the accumulator then spread it. Anything not already a list now starts a fresh one --
the only sane reading of a flag that carried no value to keep.

The second is `maintain <sub> --repo` with no value. `true` passed the `!repoFullName` truthiness
guard and then died on a string method, where "Pass --repo owner/repo." was intended.

The third is a bare `--login`, read as the literal string "true", so `decision-pack --login`
requested a contributor NAMED "true" and reported them not found instead of saying the value was
missing. Options are read through optionText() now, which treats a valueless flag as absent -- and
every one of those call sites already had an env or profile fallback for absent.

Also: the contract's LoopoverConfig was missing `session`, `telemetryEnabled`, and profile
`createdAt`, all three read and written by the CLI with nothing checking they existed. The legacy
top-level `session` is still written on the default profile so an older CLI reading the same file
keeps working, which is exactly why it cannot be left undeclared.

277 -> 184 `: any` occurrences in the bin. The remainder is a long tail of callbacks over API
payloads that stay untyped for a structural reason worth its own issue: CLI_RESPONSE_SCHEMAS
covers only the 24 STATIC paths, so all 53 parameterised calls fall through to the untyped
overload. #9773 stays open for that.

Author: JSONbored

packages/loopover-contract/src/api-schemas.ts

@@ -40,13 +40,27 @@ export const PROFILE_NAME_PATTERN = /^[a-z0-9][a-z0-9._-]{0,63}$/;
 
 export type LoopoverConfigProfile = {
   apiUrl?: unknown;
-  session?: { token?: unknown } | null | undefined;
+  /** #9773: stamped by `loopover-mcp login` and preserved across re-logins. It was absent from this type
+   *  while the CLI read and wrote it, so nothing checked the field even existed. */
+  createdAt?: unknown;
+  session?: LoopoverConfigSession | null | undefined;
 };
 
+export type LoopoverConfigSession = { token?: unknown; createdAt?: unknown; login?: unknown };
+
 export type LoopoverConfig = {
   activeProfile?: unknown;
   profiles?: Record<string, LoopoverConfigProfile | undefined>;
   apiUrl?: unknown;
+  /**
+   * #9773: the pre-profile session and the telemetry opt-in, both still read and written by the CLI.
+   *
+   * `session` is the LEGACY single-session shape from before profiles existed -- `loopover-mcp login` on
+   * the default profile still writes it so an older CLI reading the same file keeps working, which is
+   * exactly why it cannot be dropped from the type.
+   */
+  session?: LoopoverConfigSession | null | undefined;
+  telemetryEnabled?: unknown;
 };
 
 /**

packages/loopover-contract/src/cli-config.ts

@@ -43,6 +43,52 @@ export function cliApiPaths(binSource: string): string[] {
   return [...paths].sort();
 }
 
+/**
+ * Every PARAMETERISED `/v1/...` path the CLI calls, normalised to the document's own `{param}` form (#9773).
+ *
+ * `cliApiPaths` above deliberately rejects anything containing a `$`, so until now the 53 template call
+ * sites -- every per-contributor and per-repo endpoint -- fell through to the untyped overload. That, not
+ * an oversight in the call sites, is why the stdio bin still reads those payloads as `any`.
+ *
+ * Each `${...}` becomes `{}` first (its own contents can be an arbitrary expression, including nested
+ * braces and a `?:` with slashes in both arms), then the segments are re-keyed positionally against the
+ * document's parameter names, so the emitted key is exactly the string `openapi.json` uses.
+ */
+export function cliParameterisedApiPaths(binSource: string, document: OpenApiDocument): string[] {
+  const documented = Object.keys(document.paths).filter((path) => path.includes("{"));
+  const shapes = new Map<string, string>();
+  for (const documentPath of documented) shapes.set(documentPath.replace(/\{[^}]+\}/g, "{}"), documentPath);
+
+  const found = new Set<string>();
+  for (const match of binSource.matchAll(/api(?:Get|Post|Delete|Fetch)\(\s*`(\/v1\/[^`]*)`/g)) {
+    const raw = match[1]!;
+    if (!raw.includes("${")) continue;
+    // Collapse each interpolation, honouring nested braces, then drop any trailing query the template adds.
+    let collapsed = "";
+    for (let index = 0; index < raw.length; index += 1) {
+      if (raw[index] === "$" && raw[index + 1] === "{") {
+        let depth = 1;
+        index += 2;
+        while (index < raw.length && depth > 0) {
+          if (raw[index] === "{") depth += 1;
+          else if (raw[index] === "}") depth -= 1;
+          index += 1;
+        }
+        index -= 1;
+        collapsed += "{}";
+      } else {
+        collapsed += raw[index];
+      }
+    }
+    const withoutQuery = collapsed.split("?")[0]!.replace(/\/+$/, "");
+    // A template whose interpolation spans a slash (a conditional query suffix, say) cannot be a path
+    // shape; it simply will not match a documented one, and is left unvalidated exactly as before.
+    const documentPath = shapes.get(withoutQuery);
+    if (documentPath) found.add(documentPath);
+  }
+  return [...found].sort();
+}
+
 type SchemaBlock = { name: string; source: string; exported: boolean };
 
 /** Every top-level `const XSchema = ...` in the source, in declaration order, with its full body. */
@@ -108,8 +154,10 @@ import { z } from "zod";
 `;
 
 export function renderApiSchemas(sourceText: string, documentText: string, binSource: string): string {
-  const byPath = responseSchemaByPath(JSON.parse(documentText) as OpenApiDocument, cliApiPaths(binSource));
-  const blocks = closure(parseSchemaBlocks(sourceText), [...new Set(byPath.values())]);
+  const document = JSON.parse(documentText) as OpenApiDocument;
+  const byPath = responseSchemaByPath(document, cliApiPaths(binSource));
+  const byPattern = responseSchemaByPath(document, cliParameterisedApiPaths(binSource, document));
+  const blocks = closure(parseSchemaBlocks(sourceText), [...new Set([...byPath.values(), ...byPattern.values()])]);
   const body = blocks
     .map((block) =>
       block.source
@@ -122,7 +170,11 @@ export function renderApiSchemas(sourceText: string, documentText: string, binSo
     .sort(([left], [right]) => left.localeCompare(right))
     .map(([path, schema]) => `  "${path}": ${schema},`)
     .join("\n");
-  return `${HEADER}${body.trimEnd()}\n\n${TABLE_HEADER}${table}\n} as const;\n\n${TABLE_TYPES}`;
+  const patternTable = [...byPattern.entries()]
+    .sort(([left], [right]) => left.localeCompare(right))
+    .map(([path, schema]) => `  "${path}": ${schema},`)
+    .join("\n");
+  return `${HEADER}${body.trimEnd()}\n\n${TABLE_HEADER}${table}\n} as const;\n\n${PATTERN_TABLE_HEADER}${patternTable}\n} as const;\n\n${TABLE_TYPES}`;
 }
 
 const TABLE_HEADER = `/**
@@ -135,11 +187,46 @@ const TABLE_HEADER = `/**
 export const CLI_RESPONSE_SCHEMAS = {
 `;
 
+const PATTERN_TABLE_HEADER = `/**
+ * The same, for the PARAMETERISED paths (#9773) -- keyed by the document's own \`{param}\` template.
+ *
+ * Separate from the table above because these cannot be looked up by an exact string: the CLI builds them
+ * with interpolation, so the match happens at the type level (see MatchApiPath) rather than by key.
+ */
+export const CLI_PARAMETERISED_RESPONSE_SCHEMAS = {
+`;
+
 const TABLE_TYPES = `/** A path the client validates. */
 export type ValidatedApiPath = keyof typeof CLI_RESPONSE_SCHEMAS;
 
 /** The parsed response type for a validated path -- what the CLI call sites get instead of \`any\`. */
 export type ApiResponse<Path extends ValidatedApiPath> = z.infer<(typeof CLI_RESPONSE_SCHEMAS)[Path]>;
+
+/** A parameterised path pattern the client validates. */
+export type ParameterisedApiPath = keyof typeof CLI_PARAMETERISED_RESPONSE_SCHEMAS;
+
+/**
+ * A pattern with every \`{param}\` widened to \`\${string}\`, so a concrete path can be matched against it.
+ *
+ * Recursive because a pattern can carry several parameters
+ * (\`/v1/contributors/{login}/repos/{owner}/{repo}/decision\`).
+ */
+export type TemplatedApiPath<Pattern extends string> = Pattern extends \`\${infer Head}{\${string}}\${infer Tail}\`
+  ? \`\${Head}\${string}\${TemplatedApiPath<Tail>}\`
+  : Pattern;
+
+/**
+ * The pattern a CONCRETE path matches, or \`never\` when it matches none.
+ *
+ * This is what lets the CLI keep writing its natural interpolated template and still get the exact response
+ * type: the mapped type distributes over every known pattern and keeps only the arms the string satisfies.
+ */
+export type MatchApiPath<Path extends string> = {
+  [Pattern in ParameterisedApiPath]: Path extends TemplatedApiPath<Pattern> ? Pattern : never;
+}[ParameterisedApiPath];
+
+/** The parsed response for a concrete parameterised path. */
+export type ParameterisedApiResponse<Path extends string> = z.infer<(typeof CLI_PARAMETERISED_RESPONSE_SCHEMAS)[MatchApiPath<Path>]>;
 `;
 
 export function generate(deps: { readFile?: (path: string) => string } = {}): string {

packages/loopover-mcp/bin/loopover-mcp.ts

@@ -133,3 +133,27 @@ describe("loopover-mcp CLI — boolean `--flag=value` parsing (#8689)", () => {
     expect(out).toContain("[mcp_servers.loopover]");
   });
 });
+
+// #9773: three crashes the `: any` on the option plumbing was hiding. Each is a real invocation a user can
+// type; each threw or lied before this. Typing parseOptions from CLI_FLAG_SPEC is what surfaced all three.
+describe("a flag given with no value (#9773)", () => {
+  it("does not let a bare repeatable flag poison the next one", async () => {
+    // `--issue --issue 5` stored `true` for the first, then spread it: "true is not iterable".
+    const out = await withEnv(AUTHED, () =>
+      captureStdout(() => mod.runCli(["preflight", "--login", "acme", "--repo", "acme/widgets", "--title", "t", "--body", "b", "--issue", "--issue", "5", "--json"])),
+    );
+    expect(out.length).toBeGreaterThan(0);
+  });
+
+  it("reports the usage error for `maintain --repo` instead of throwing a TypeError", async () => {
+    // Was: "repoFullName.includes is not a function" -- a bare flag parses to `true`, which passed the
+    // truthiness guard and then died on a string method.
+    await expect(withEnv(AUTHED, () => captureStdout(() => mod.runCli(["maintain", "list", "--repo"])))).rejects.toThrow("Pass --repo owner/repo.");
+  });
+
+  it("treats a bare --login as absent rather than as a contributor NAMED \"true\"", async () => {
+    // Was: `/v1/contributors/true/decision-pack` -- a real request for a real-looking login, answered with
+    // "not found", when the user had simply forgotten the value.
+    await expect(withEnv({ ...AUTHED, LOOPOVER_LOGIN: undefined, GITHUB_LOGIN: undefined }, () => captureStdout(() => mod.runCli(["decision-pack", "--login"])))).rejects.toThrow(/--login/);
+  });
+});

scripts/gen-contract-api-schemas.ts

@@ -90,11 +90,10 @@ describe("bin loopover_get_contributor_profile stdio tool (in-process, #7760)",
       expect(captured.url).toContain("/v1/contributors/octocat/profile");
       expect(captured.method).toBe("GET");
       expect(result.isError).toBeFalsy();
-      // structuredContent is the raw API payload; the summary line is the remote tool's fixed sentence.
-      expect(result.structuredContent).toMatchObject({ login: "octocat" });
+      // structuredContent is the raw API payload; the summary line is the tool's own fixed sentence.
+      expect(result.structuredContent).toMatchObject({ login: "octocat", source: "github_cache" });
       const text = JSON.stringify(result);
       expect(text).toContain("LoopOver contributor profile for octocat.");
-      expect(text).toContain("3 registered repos; 12 merged PRs; strongest in review-tooling.");
     } finally {
       await client.close().catch(() => undefined);
     }
@@ -117,19 +116,20 @@ describe("bin loopover_get_contributor_profile stdio tool (in-process, #7760)",
 });
 
 describe("bin contributor-profile CLI (in-process, #7760)", () => {
-  it.each(MODULES)("shares getContributorProfile with the stdio tool: prints the header + API summary — %s", async (specifier) => {
+  it.each(MODULES)("shares getContributorProfile with the stdio tool: prints the header — %s", async (specifier) => {
     capturedRequests.length = 0;
     const mod = loaded.get(specifier)!;
     const out = await captureStdout(() => mod.contributorProfileCli({ login: "octocat" }));
     expect(capturedRequests.at(-1)!.url).toBe("/v1/contributors/octocat/profile");
+    // #9773: the "API summary" line this used to assert came from a `summary` field the endpoint has never
+    // returned -- invented by the fixture, read by the CLI, asserted here. The header is what really prints.
     expect(out).toMatch(/LoopOver contributor profile for octocat\./);
-    expect(out).toContain("3 registered repos; 12 merged PRs; strongest in review-tooling.");
   });
 
   it.each(MODULES)("--json re-serializes the same payload the shared call returned — %s", async (specifier) => {
     const mod = loaded.get(specifier)!;
     const out = await captureStdout(() => mod.contributorProfileCli({ login: "octocat", json: true }));
-    const payload = JSON.parse(out) as { login: string; summary: string };
-    expect(payload).toMatchObject({ login: "octocat", summary: "3 registered repos; 12 merged PRs; strongest in review-tooling." });
+    const payload = JSON.parse(out) as { login: string; source: string };
+    expect(payload).toMatchObject({ login: "octocat", source: "github_cache" });
   });
 });

test/unit/mcp-cli-bool-flag-parsing.test.ts

@@ -25,12 +25,12 @@ describe("loopover-mcp CLI — contributor-profile (#6737)", () => {
 
     const plain = await runAsync(["contributor-profile", "--login", "octocat"], e);
     expect(plain).toMatch(/LoopOver contributor profile for octocat\./);
-    expect(plain).toMatch(/3 registered repos; 12 merged PRs; strongest in review-tooling\./);
     expect(requests.at(-1)).toBe("/v1/contributors/octocat/profile");
 
-    const json = JSON.parse(await runAsync(["contributor-profile", "--login", "octocat", "--json"], e)) as { login: string; summary: string };
-    // Parity: the --json surface re-serializes the same payload the plain summary was built from.
-    expect(json).toMatchObject({ login: "octocat", summary: "3 registered repos; 12 merged PRs; strongest in review-tooling." });
+    const json = JSON.parse(await runAsync(["contributor-profile", "--login", "octocat", "--json"], e)) as { login: string; source: string };
+    // Parity: the --json surface re-serializes the payload verbatim. Asserted on fields the endpoint really
+    // returns -- the previous assertion named a `summary` that only ever existed in the fixture (#9773).
+    expect(json).toMatchObject({ login: "octocat", source: "github_cache" });
   });
 
   it("resolves the login from LOOPOVER_LOGIN when --login is omitted, and url-encodes it", async () => {

test/unit/mcp-cli-contributor-profile-inprocess.test.ts

@@ -387,7 +387,11 @@ export async function startFixtureServer(
         JSON.stringify({
           login: decodeURIComponent(contributorProfileMatch[1]!),
           generatedAt: "2026-05-30T00:00:00.000Z",
-          summary: "3 registered repos; 12 merged PRs; strongest in review-tooling.",
+          // #9773: a `summary` used to be here. The real endpoint has never returned one -- neither
+          // ContributorProfile shape carries the field, and the string existed nowhere but this fixture --
+          // so it was an invented field the CLI then read and the test then asserted on. All three agreed
+          // with each other and none agreed with the server.
+          source: "github_cache",
         }),
       );
       return;