Skip to content

examples.md

Latest commit

 

History

History
195 lines (131 loc) · 9.41 KB

examples.md

File metadata and controls

195 lines (131 loc) · 9.41 KB
Raw

Examples

A curated, browsable library of idiomatic Univeros patterns: short, runnable snippets covering common scenarios ("how do you do X here?"). Reach for it instead of grepping source. Every example is linked to a real test, so an example that drifts from working code fails CI.

Composer: univeros/examples Namespace: Altair\Examples

Introduction

The MCP server and framework manifests answer "what exists" in the project: every binding, every route, every spec. They do not answer "what is the idiomatic way to do this here." When an agent (or a human) needs to wire two packages together (say, an HTTP endpoint that dispatches a queue job after successful persistence) there is no canonical reference. The agent reads source, infers conventions, and risks producing non-idiomatic code.

The examples library closes that loop. Each example is a short Markdown file with YAML frontmatter declaring its scenario, the packages it touches, and a path to a real test. The test runs the snippet end-to-end as part of composer test, so if the example drifts from working code the failure is loud and immediate.

This package ships three layers:

  • Library: Altair\Examples\Library\*. The pure logic: parse, query, build the index. Filesystem-rooted, no I/O hidden behind layers.
  • CLI: bin/altair examples:list, :show, :search, :index, :test. The human-facing surface.
  • MCP: framework__list_examples, framework__read_example, framework__search_examples. The agent-facing surface.

The library content itself ships in the Bootstrap starter at .altair/examples/ so composer create-project univeros/univeros myapp already gives you a usable catalogue.

Installation

Standalone:

composer require --dev univeros/examples

You will usually want this as a dev dependency; it is an authoring + introspection surface, not a runtime concern. If you install the full framework (composer require univeros/framework) it is already bundled.

It depends on symfony/yaml (frontmatter parsing) plus univeros/cli, univeros/configuration, univeros/container, and univeros/mcp.

Quick start

In a fresh composer create-project univeros/univeros myapp checkout the catalogue is already populated under .altair/examples/. Inspect it:

vendor/bin/altair examples:list
# ID                                       PACKAGES                  TITLE
# ---------------------------------------- ------------------------- ----------------------------------------
# http/basic-endpoint                      http                      The smallest spec-driven HTTP endpoint
# ...

Pick one and render it:

vendor/bin/altair examples:show http/basic-endpoint

Free-text search:

vendor/bin/altair examples:search "transactional write"

Regenerate the deterministic index after authoring new examples:

vendor/bin/altair examples:index

Re-run every example's linked test (CI gate against drift):

vendor/bin/altair examples:test

Concepts

An example is a Markdown file with a YAML frontmatter block:

---
title: Endpoint that dispatches a job after successful persistence
scenario: Run an async side effect after a domain operation succeeds.
packages: [http, persistence, messaging]
since: 2.0.0
tested_by: tests/Examples/HttpDispatchJobTest.php
---

# Endpoint that dispatches a job after successful persistence

(prose + code blocks)
Field Required Meaning
title yes One-line headline shown in examples:list and the MCP list_examples response.
scenario yes One-sentence "what problem does this solve" hook.
packages yes List of univeros/* package names the example exercises (used for --package filter).
since yes Framework version that introduced the example (semver-ish).
tested_by yes Path (relative to project root) to a real PHPUnit test that runs the snippet.

The identifier of an example is its path relative to .altair/examples/ with the .md extension stripped: http/basic-endpoint, persistence/crud-repository, etc. That is the stable key the CLI, MCP tools, and the index all key on.

The index at .altair/examples/index.json is a deterministic JSON projection of every example's frontmatter. It is regenerated by bin/altair examples:index and exists so agents can browse the catalogue without parsing every file. The --check flag turns it into a CI drift gate.

Usage

Listing the catalogue

vendor/bin/altair examples:list
vendor/bin/altair examples:list --package=http
vendor/bin/altair examples:list --format=json

Reading a single example

vendor/bin/altair examples:show http/basic-endpoint
vendor/bin/altair examples:show http/basic-endpoint --format=json

--format=json returns the frontmatter as a flat object plus a body field with the Markdown, the same shape the MCP read_example tool returns.

Searching

examples:search does a case-insensitive substring match across each example's id, title, scenario, and body:

vendor/bin/altair examples:search "outbox"
vendor/bin/altair examples:search "jwt" --format=json

There is no fancier ranking; the catalogue is small enough that a flat substring match is honest.

Regenerating the index

vendor/bin/altair examples:index           # write .altair/examples/index.json
vendor/bin/altair examples:index --check   # drift gate (exit 1 if the file is stale)

The index is byte-stable for the same input; wire --check into CI so an example added without examples:index failing the build is caught at PR time.

Running every example's linked test

vendor/bin/altair examples:test
vendor/bin/altair examples:test --skip-missing  # ignore examples whose tested_by file doesn't exist yet

This shells out to vendor/bin/phpunit with each tested_by path. Use it in your CI alongside the normal test run; it surfaces "example references a test that's been deleted" in seconds.

Configuration

Container wiring lives in Altair\Examples\Configuration\ExamplesConfiguration. Bind it once at boot:

(new \Altair\Examples\Configuration\ExamplesConfiguration())->apply($container);
Env var Default Meaning
ALTAIR_EXAMPLES_DIR .altair Base directory (relative to project root).
ALTAIR_EXAMPLES_LIBRARY_DIR examples Library subdirectory inside the base directory.
ALTAIR_EXAMPLES_INDEX_FILE index.json Index filename inside the library directory.

The Configuration binds ExampleRepositoryInterface, IndexBuilder, ExampleParser, and ExamplesSettings, all shared. CLI commands and MCP tools are autowired through the Container.

MCP tools

Tool Description Inputs
framework__list_examples All examples, optionally filtered by package. package?: string
framework__read_example Frontmatter + Markdown body of one example by id. id: string
framework__search_examples Free-text substring search across id, title, scenario, body. query: string

Each tool returns deterministic JSON. The agent never has to parse Markdown: read_example returns the body as a string field; list and search return frontmatter only (no body, to keep payloads small).

Testing

The package's own tests live under tests/Examples/: ExampleParserTest, ExampleRepositoryTest, IndexBuilderTest, CliCommandsTest, ExamplesConfigurationTest, McpToolsTest. Each tests one concern; together they exercise the full library end-to-end.

For your own example authoring, the test that proves an example honest is the tested_by file. Treat it as the truth source: if you change an example's code, run the linked test first; the example is just documentation around it.

Authoring discipline

A new example PR must:

  • Include the YAML frontmatter (the parser rejects malformed inputs and CI fails)
  • Provide a tests/Examples/<Name>Test.php that runs the snippet
  • Be under 80 lines of code (forced concision; longer = it is a feature, not an example)
  • Use only univeros/* packages and standard PSR contracts; no third-party deps that are not already framework deps
  • Be added to the index by running bin/altair examples:index before commit

Related packages

  • univeros/mcp: exposes the three tool surfaces to MCP-capable agents
  • univeros/cli: the attribute-driven CLI substrate the commands ride on
  • univeros/bootstrap: ships the .altair/examples/ content in the starter
  • univeros/scaffold: agents that read an example pattern then scaffold the matching spec close the agent's loop