Files
reverse-engineering-anything/src/cli/guidanceCommands.ts
T
morluto e44f0077c9 test(cli): derive CLI tool coverage and schema parity from command registry (#11776)
* test(cli): derive CLI tool coverage and schema parity from command registry

* test(cli): check recorded routed operations and host operation bindings
2026-11-16 16:30:36 -05:00

162 lines
5.5 KiB
TypeScript

import { z } from "zod";
import { ArtifactResourceScope } from "../resources/index.js";
import {
readGuidanceSection,
searchGuidance,
} from "../application/GuidanceAccess.js";
import {
readGuidanceSectionInputSchema,
searchGuidanceLimitSchema,
searchGuidanceInputSchema,
} from "../contracts/guidanceContracts.js";
import { CLI_COMMANDS } from "../contracts/cliCommandNames.js";
import { logCliCommand } from "../cliLogging.js";
import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
import type { Logger } from "pino";
import { registerCliCommand } from "./commandRegistry.js";
import type { CliInstance } from "./types.js";
import { cliDecimalField } from "./options.js";
import { ownCliProcessResource } from "./cliResources.js";
/** Guidance descriptors owned by one CLI host. */
export class CliGuidanceResources {
#retained: ArtifactResourceScope | undefined;
resources(): ArtifactResourceScope {
this.#retained ??= new ArtifactResourceScope();
return this.#retained;
}
/** Release this host's descriptors, retaining failed cleanup for retry. */
async close(): Promise<void> {
const resources = this.#retained;
if (resources === undefined) return;
await resources.close();
if (this.#retained === resources) this.#retained = undefined;
}
}
/** Process CLI host used when a caller does not pass its own resources. */
const processGuidanceResources = new CliGuidanceResources();
/** Release CLI-owned guidance descriptors, retaining failed cleanup for retry. */
export const closeCliGuidanceResources = (
resources: CliGuidanceResources = processGuidanceResources,
): Promise<void> => resources.close();
ownCliProcessResource("guidance", () => closeCliGuidanceResources());
/** Register offline search and retrieval for the installed REA guide bundle. */
export const registerGuidanceCommands = (
cli: CliInstance,
logger: Logger,
resources: CliGuidanceResources = processGuidanceResources,
): void => {
registerCliCommand(
cli,
CLI_COMMANDS.guidance,
{
description: "Search or read the installed REA workflow guidance",
args: z.object({}),
options: z
.object({
action: z
.enum(["search", "read"])
.default("search")
.describe("Guidance action to perform: search or read"),
query: searchGuidanceInputSchema.shape.query
.optional()
.describe(
"Required with search; all non-generic query words must match",
),
locator: readGuidanceSectionInputSchema.shape.locator
.optional()
.describe(
"Required with --action read; locator returned by search",
),
// Decimal tokens only: numeric coercion would read "0x2" as 2.
limit: cliDecimalField(searchGuidanceLimitSchema.optional()).describe(
"Maximum search matches; search only, defaults to 8",
),
cursor: searchGuidanceInputSchema.shape.cursor
.optional()
.describe("Continue a search page; search only"),
})
.superRefine((options, context) => {
if (options.action === "search") {
if (options.query === undefined)
context.addIssue({
code: "custom",
path: ["query"],
message: "--query is required with --action search",
});
if (options.locator !== undefined)
context.addIssue({
code: "custom",
path: ["locator"],
message: "--locator can only be used with --action read",
});
} else {
if (options.locator === undefined)
context.addIssue({
code: "custom",
path: ["locator"],
message: "--locator is required with --action read",
});
for (const option of ["query", "limit", "cursor"] as const)
if (options[option] !== undefined)
context.addIssue({
code: "custom",
path: [option],
message: `--${option} can only be used with --action search`,
});
}
}),
run: ({ options }) =>
logCliCommand(logger, CLI_COMMANDS.guidance, async () => {
const result =
options.action === "search"
? await searchGuidance(
{
...(options.query === undefined
? {}
: { query: options.query }),
...(options.limit === undefined
? {}
: { limit: options.limit }),
...(options.cursor === undefined
? {}
: { cursor: options.cursor }),
},
resources.resources(),
)
: await readGuidanceSection(
{
locator: options.locator,
},
resources.resources(),
);
return result.ok ? result.value : projectAnalysisError(result.error);
}),
},
{
operations: [
{
name: "search_guidance",
flags: {
query: "--query",
limit: "--limit",
cursor: "--cursor",
},
},
{
name: "read_guidance_section",
flags: {
locator: "--locator",
},
},
],
},
);
};