Skip to content

ARTIFACT_CONTRACT.md

Latest commit

 

History

History
87 lines (56 loc) · 4.58 KB

ARTIFACT_CONTRACT.md

File metadata and controls

87 lines (56 loc) · 4.58 KB

Output Artifact Contract

This document defines the output representation model for jtk and cfl. It establishes the vocabulary and semantics that all commands must follow.

Artifact Types

Two general artifact types apply across all commands:

Type Purpose Default? Flag
agent Action-oriented output for LLM/agent consumption. Contains what's needed to decide the next step. Yes (none - default)
full Inspection-oriented output for human debugging. Richer curated fields beyond agent. No --full

agent (default)

The agent artifact is intentionally curated output containing what you need to decide the next step.

  • Each command defines its agent artifact: which fields are action-relevant
  • Content is transformed for readability (e.g., markdown instead of XHTML)
  • Strips transport metadata (self URLs, _links, _expandable)
  • Strips visual-only fields (avatarUrls)

Examples:

  • jtk issues get → key, summary, status, assignee (enough to triage)
  • cfl page view → id, title, space, ancestors, content as markdown (enough to navigate and act)

full

The full artifact provides richer inspection-oriented output for debugging and deeper understanding.

  • Each command defines additional fields beyond agent (dates, authors, versions, relationships)
  • Still curated by the CLI, not a pass-through of API payloads
  • Content transformation same as agent (readable format)

Examples:

  • jtk issues get --full → agent fields + created, updated, reporter, components, labels
  • cfl page view --full → agent fields + version, created, modified, author

Raw Mode (Command-Specific)

Some commands expose a --raw mode for source-faithful content where transformation would lose fidelity. This is not a general artifact type—it applies only to commands that transform content.

  • Shows original storage format (XHTML, ADF JSON) instead of transformed content
  • Errors on commands where raw has no meaning (e.g., list commands)
  • Mutually exclusive with --full

Example:

  • cfl page view --raw → XHTML storage format instead of markdown

Flag Behavior

(none)       → agent artifact (curated, transformed content)
--full       → full artifact (richer curation, transformed content)
--raw        → raw mode (source-faithful content, command-specific)
--full --raw → error: mutually exclusive

Implementation note: The mutual exclusivity constraint (--full --raw → error) and command-specific --raw validation are forward-looking requirements. They will be enforced as commands are migrated in #199 and #200.

Output Format

JTK and CFL both use text-first output. The -o json resource surface has been removed from both tools (JTK earlier, then CFL via #392); CFL retains -o table and -o plain only. JSON is reserved for control-plane envelopes (cfl set-credential --json, jtk set-credential --json) and round-trip payloads (jtk automation export).

jtk and cfl both use presenter-owned text output for default CLI rendering. cfl's command/output contract is defined in tools/cfl/internal/cmd/OUTPUT_SPEC.md; its presenter-boundary guidance and documented exceptions live in tools/cfl/internal/present/README.md.

Text output modes:

  • Default = focused output for human and agent consumption (defined per-command)
  • Tool-specific detail/inspection flags stay tool-local: jtk uses flags such as --extended, --id, and --fulltext; cfl uses --full plus command-specific flags documented in tools/cfl/internal/cmd/OUTPUT_SPEC.md

Design Principles

  1. Intentional artifacts, not field stripping. Commands project domain objects into purpose-built artifacts. They don't start with everything and strip fields away.

  2. Agent is the default. LLM/agent consumption is the primary use case. Human inspection is opt-in via each tool's additive inspection flag set.

  3. Raw is command-specific. Not every command needs --raw. It's only for commands where content transformation occurs.

  4. Curated, not pass-through. Even --full is curated by the CLI. Raw API payloads are not exposed directly.

History: --compact flag

The global --compact flag was removed after the artifact projection migration. Its behavior (stripping null fields, avatarUrls, self-links, _links, _expandable) is superseded by agent-default semantics — commands now produce intentionally shaped artifacts rather than post-processing raw API payloads.

Note: jtk automation export --compact is unrelated — it controls JSON formatting (minified vs pretty-printed), not metadata stripping.