mizcausevic-dev/agent-card-fleet-summary

Purpose and principal workflow: This Node.js library and CLI analyze a fleet of A2A AgentCard JSON documents, count autonomy and memory categories, and report governance findings. The main workflow starts when a command-line user runs agent-card-fleet-summary with a cards directory; the CLI reads the cards, invokes the analyzer, formats a report, and writes it to stdout or a file. The package also exposes the analyzer and formatters to library consumers.

Components

CLI and file workflow

• CLI runner — src/cli.ts: Parses options, reads *.json AgentCards from a directory, calls the summarizer and formatter, and writes output; optionally exits with failure when high-severity findings exist.

Analysis and output

• Fleet analyzer — src/summarize.ts: Builds per-agent rows and fleet counts, evaluates the documented governance rules, and returns a report with ok false when any finding is high severity.

• Report formatters — src/format.ts: Renders a report as Markdown or a concise summary; the CLI also supports JSON serialization directly.

• Library entry point — src/index.ts: Exports the summarizer, formatters, and public types for package consumers.

Domain contract

• AgentCard and report types — src/types.ts: Defines the AgentCard subset analyzed by the library, finding codes and severities, summary rows, and the fleet report shape.

External actors

• Command-line user — path: null. Supplies the cards directory and optional formatting, timestamp, output, and failure-threshold options.

• Library consumer — path: null. May provide AgentCard objects to the exported summarizer and use the exported formatters.

Relationships

• Command-line user -> CLI runner: invokes the installed command with a cards directory and options; documented usage and argument handling establish this entry point.

• CLI runner -> Fleet analyzer: calls summarize(cards, args.now) after loading the input files.

• Fleet analyzer -> AgentCard and report types: consumes AgentCard-shaped inputs and returns a FleetReport containing rows, counts, findings, and status.

• CLI runner -> Report formatters: calls a formatter for Markdown or summary output; for JSON, serializes the report directly.

• Report formatters -> AgentCard and report types: reads the report structure and finding severities to render output.

• CLI runner -> Command-line user: writes the report to stdout unless an output file was specified; returns documented status codes, including failure for high findings when requested.

• CLI runner -> Output file: writes formatted report text when --out is supplied; the file is a runtime destination, not a repository component.

• Library consumer -> Library entry point: imports the package’s public exports.

• Library entry point -> Fleet analyzer: re-exports summarize for library use.

• Library entry point -> Report formatters: re-exports toMarkdown and toSummary.

• Library entry point -> AgentCard and report types: re-exports the public types.

Coverage limits: The sampled source establishes the CLI, analysis rules, report formatting, and public exports. No persistent state, network calls, or external provider integrations are shown; the analyzer operates on the supplied in-memory cards.