Inspect bundle or policy

Instructions

Implementation Reference

• src/tools/authoring/inspect.ts:34-76 (handler)

  Main tool handler: registers the 'rego_inspect' MCP tool, validates the target path, runs 'opa inspect --format=json', parses the JSON output, and returns structured data (manifest, namespaces, annotations, signatures).

  export function registerRegoInspect(server: McpServer, config: Config): void {
    const opa = new OpaCli(config);
  
    server.registerTool(
      'rego_inspect',
      {
        title: 'Inspect bundle or policy',
        description:
          'Inspect an OPA bundle, policy directory, or single Rego file with `opa inspect`. Returns manifest data, namespaces, rule annotations, and (if signed) signature metadata.',
        inputSchema: RegoInspectInput,
      },
      async ({ target }) => {
        return withToolEnvelope<RegoInspectOutput>(config, async () => {
          const validation = validatePaths([target], config, { mustExist: true });
          if (!validation.ok) return validation.error;
          const [resolved] = validation.resolved;
  
          const result = await opa.inspect({ target: resolved! });
  
          const subprocessFailure = mapSubprocessFailure(result, 'opa');
          if (subprocessFailure) return subprocessFailure;
  
          if (result.exitCode !== 0) {
            return err(
              'INVALID_BUNDLE',
              'opa inspect rejected the target — it is not a valid bundle, directory, or Rego file.',
              {
                details: { stderr: result.stderr.trim(), stdout: result.stdout.trim() },
              },
            );
          }
  
          const parsed = tryParseJson<RegoInspectOutput>(result.stdout);
          if (parsed === undefined) {
            return err('UNKNOWN_ERROR', 'opa inspect produced no parseable JSON output.', {
              details: { stdout: result.stdout.trim() },
            });
          }
          return ok<RegoInspectOutput>(parsed);
        });
      },
    );
  }

• src/tools/authoring/inspect.ts:20-25 (schema)

  Zod input schema for RegoInspect: requires a 'target' string (path to bundle, directory, or .rego file).

  const RegoInspectInput = {
    target: z
      .string()
      .min(1)
      .describe('Path to a bundle archive (`*.tar.gz`), directory, or single Rego file.'),
  };

• src/tools/authoring/inspect.ts:27-32 (schema)

  TypeScript interface for the tool output: manifest, namespaces, annotations, and optional signatures.

  export interface RegoInspectOutput {
    manifest?: unknown;
    namespaces?: Record<string, unknown>;
    annotations?: unknown;
    signatures?: unknown;
  }

• src/tools/authoring/index.ts:19-27 (registration)

  Registration entry point: calls registerRegoInspect() as part of authoring tool registration.

  export function registerAuthoringTools(server: McpServer, config: Config): void {
    registerRegoFormat(server, config);
    registerRegoCheck(server, config);
    registerRegoLint(server, config);
    registerRegoParseAst(server, config);
    registerRegoInspect(server, config);
    registerRegoCapabilities(server, config);
    registerRegoDeps(server, config);
  }

• src/lib/opa-cli.ts:236-242 (helper)

  OpaCli.inspect() helper: wraps the 'opa inspect --format=json' subprocess call.

  /**
   * Inspect a bundle, directory, or single Rego file. Returns its
   * packages, namespaces, manifest, and annotations as JSON on stdout.
   */
  async inspect(input: InspectInput): Promise<SpawnResult> {
    return this.run(['inspect', '--format=json', input.target]);
  }