HTTP API: artifacts

Co zapisuje `majordomus generate`: každý dokument s kódováními, ve kterých je commitován — JSON pro program, YAML vedle něj, Markdown pro čtenáře — každý se svým schématem, zdrojem a hashem, sladěný s pracovním stromem. Deklarací je vlastní manifest generátoru; nic zde neudržuje seznam.

Vykresleno z docs/generated/openapi.json, který spustitelný soubor generuje ze svého registru schopností a CI jej odmítne, je-li zastaralý. Surový dokument je na /openapi.json; běžící server servíruje stejný dokument na vlastní /openapi.json a Swagger UI na /swagger.

artefakty

GET /api/v1/artifacts artifacts.list

Vypsat generované artefakty

Manifest, který `majordomus generate` commituje jako docs/generated/artifacts.json, sesouhlasený s pracovním stromem: každý dokument s kódováními, v nichž je zapsán, a každý soubor s jeho formátem, schématem, zdrojem, velikostí, hashem a tím, zda soubor na disku stále odpovídá. Volitelně zúžený na jeden dokument nebo jedno kódování. Jen čte; `majordomus generate` zapisuje a `majordomus generate --check` je verdikt bajt po bajtu.

query
behaviorally_verified
vyžaduje se měření výkonu
cache procesu (max_entries=8, ttl_seconds=5)
nástroj MCP majordomus_artifacts
Zdroj MCP {"name": "artifacts", "uri": "majordomus://artifacts"}

Parametry dotazu

název	typ	povinné	popis	příklady
dokument	string	ne	Pouze artefakty tohoto dokumentu (`registry`, `cli`, `openapi`, ...).
formát	ArtifactFormat \| null	ne	Pouze artefakty zapsané v tomto kódování.	one-encoding: "yaml"

Vyzkoušejte

Port je ten, který server zalogoval; 8741 je ten, o který žádá jako první. Hodnoty jsou první příklad operace.

curl -s "http://127.0.0.1:8741/api/v1/artifacts?format=yaml"

Testováno v apps/majordomus-cli/tests/http_serve.rs, který přehrává routu s těmito hodnotami proti serveru na skutečném socketu.

Odpovědi

status	tělo	význam
200	ArtifactReport	Výpis generovaných artefaktů: výsledek.
400	ErrorBody	`invalid_input`: Vstup neodpovídá schématu: parametr špatného typu, neznámý parametr nebo hodnota, kterou schopnost odmítne.
404	ErrorBody	`not_found`: Vstup pojmenovává něco, co repozitář nemá.
500	ErrorBody	`internal`: Schopnost selhala z vlastního důvodu; zpráva ho pojmenovává.
výchozí	ErrorBody	Jakékoli jiné selhání, které transport hlásí: 405 `method_not_allowed` pro jinou metodu na této cestě, 400 `invalid_input` pro tělo, které není objektem JSON.

Schémata

Komponenty, které používají jen operace tohoto tagu. Každý řádek je pole daného typu, jeho doc komentář je popis; typ vlastněný jinou stránkou na ni odkazuje.

ArtifactFormat

"json" | "yaml" | "markdown" | "text"

Kódování, v němž je zapsán jeden generovaný artefakt.

jsonDokument JSON: formátovaný, jeden koncový newline, provenance jako členy.
yamlStejný dokument v YAML vrstvy, původ jako komentářový banner.
markdownMarkdown pro čtenáře, původ jako HTML komentář.
textŘádkově orientovaný text, který čte jiný program: povolenky shellového nástroje, provenience jako komentáře #.

Používá artifacts.list ArtifactView DocumentView

ArtifactReport

object

Odpověď artifacts.list.

vlastnost	typ	povinné	popis
manifest	string	ano	Manifest, z něhož se četlo, relativně k repozitáři.
přítomno	boolean	ano	Zda je manifest v tomto repozitáři vůbec commitnutý. Repozitář, který nikdy nespustil `majordomus generate`, nemá žádný generovaný strom, což je fakt o něm a ne selhání tohoto volání: každý seznam níže je pak prázdný a každý součet nulový.
schema	string	ano	Schéma, které manifest nese, prázdné, když není co číst.
dokumenty	pole DocumentView → DocumentView	ano	Dokumenty, v pořadí manifestu.
artefakty	pole ArtifactView → ArtifactView	ano	Soubory v pořadí manifestu po případném filtru.
součty	ArtifactTallies → ArtifactTallies	ano	Počty.
verdikt	ArtifactVerdict → ArtifactVerdict	ano	Kde strom jako celek stojí, rozhodnuto ze všech součtů.
znovu vygenerovat	string	ano	Příkaz, který přepíše každý z nich.
verify	string	ano	Příkaz, který rozhoduje o zastaralosti bajt po bajtu, což je silnější než hash.

Používá artifacts.list

ArtifactState

"current" | "stale" | "missing" | "present"

Jak stojí jeden generovaný soubor vůči stromu, v němž je commitnut.

currentSoubor tam je a jeho bajty mají hash, který zaznamenal manifest.
staleSoubor tam je a jeho bajty se liší: byl upraven, nebo generátor postoupil dál.
missingManifest ho jmenuje a strom ho nemá.
presentSoubor tam je a manifest pro něj nezaznamenává žádný hash: vlastní kódování manifestu, které se samo hashovat nemůže. generate --check je porovnává.

Používá ArtifactView

ArtifactTallies

object

Kolik z každého, aby volající nepotřeboval vlastní aritmetiku.

vlastnost	typ	povinné	popis
dokumenty	integer (uint)	ano	Dokumenty v manifestu.
artefakty	integer (uint)	ano	Soubory v manifestu, po případném filtru.
aktuální	integer (uint)	ano	Hashe, které se shodují.
zastaralé	integer (uint)	ano	Hashe, které nejsou.
chybí	integer (uint)	ano	Soubory, které manifest jmenuje a strom je nemá.
přítomno	integer (uint)	ano	Soubory, k nimž manifest nezaznamenává žádný hash.

Používá ArtifactReport

ArtifactVerdict

"current" | "unverified" | "stale" | "missing" | "not_generated"

Kde generovaný strom stojí jako celek: jediný verdikt, který vykresluje každý povrch, rozhodnutý zde, aby o něm žádná stránka nerozhodovala znovu z podmnožiny součtů.

use majordomus_cli::capability::builtin::artifacts::ArtifactVerdict;
let v: ArtifactVerdict = serde_json::from_str("\"unverified\"").unwrap();
assert_eq!(v, ArtifactVerdict::Unverified);
assert!(ArtifactVerdict::Current < ArtifactVerdict::Unverified);

currentKaždý soubor tam je a hashuje se na to, co zaznamenal manifest.
unverifiedKaždý soubor je tam, žádný není zastaralý a některé nenesou zaznamenaný hash: jejich bajty se zde neporovnávaly, takže strom není znám jako aktuální. Rozhoduje o nich majordomus generate --check.
staleSoubor se liší od toho, co zaznamenal manifest.
missingSoubor, který manifest jmenuje, ve stromu není.
not_generatedŽádný manifest není commitnut: repozitář nikdy nespustil majordomus generate.

Používá ArtifactReport

ArtifactView

object

Jeden generovaný soubor, jak ho deklaruje manifest a jak ho má strom.

vlastnost	typ	povinné	popis
path	string	ano	Cesta relativní k repozitáři.
dokument	string	ano	Dokument, který promítá.
formát	ArtifactFormat → ArtifactFormat	ano	Kódování.
schema	string \| null	ne	Schéma JSON, které jeho obsah splňuje, pokud nějaké deklaruje.
zdroj	string	ano	Jeden řádek: z čeho bylo odvozeno.
bajty	integer \| null	ne	Velikost, kterou manifest zaznamenal.
sha256	string \| null	ne	Hash, který manifest zaznamenal.
state	ArtifactState → ArtifactState	ano	Kde soubor proti tomu stojí.

Používá ArtifactReport

DocumentView

object

Jeden dokument a kódování, v nichž je commitnut.

vlastnost	typ	povinné	popis
id	string	ano	Id dokumentu, sdílené každým jeho kódováním.
schema	string \| null	ne	Id schématu, které nesou jeho strukturovaná kódování.
zdroj	string	ano	Jeden řádek: z čeho bylo odvozeno.
formáty	pole ArtifactFormat → ArtifactFormat	ano	Kódování, v pořadí manifestu.

Používá ArtifactReport