livery.workshop._fragment_engine¶
livery.workshop._fragment_engine ¶
Compose, render and deliver the files the extensions keep current.
Every piece of content an extension delivers into a workspace is a
livery.workshop._fragment_engine.Fragment: an owner, a name, a
target path and the template its content renders from. plan turns the
listed extensions' fragments into one
livery.workshop._fragment_engine.Output per file, and apply
writes them and records what it wrote; drift compares them with the
committed files instead.
How the fragments of one target combine depends on the target's type:
- a TOML file joins its fragments' tables in extension order;
- an ignore or attribute file joins their lines, each line once, and puts the repository's regions after every extension's lines;
- a JSON file merges their objects key by key;
- any other file has one owner.
The fragments apply in the order the caller gives: for a sync, the base
first, then the extensions in composition order, each after the ones it
requires, and the repository's own fragments last. An extension that
takes over or removes a fragment that applies before its own declares
it, with a reason, through replaces or deletes; a second owner of a
one-owner file without that declaration refuses, and so does a
declaration naming a fragment no listed extension ships.
A target is a path at the root, or package/<path> for that path in
every package whose extensions include the owner.
The receipts in .workshop-rendered, at the root and in each package,
record the digest of each file as the engine last wrote it, its
regions left out, so an edit inside a region does not count as an
edit of the file. A file
whose fragments are gone is removed only while it still has those
bytes; a file edited since is kept and named as the repository's own,
and so is an edited file the engine would otherwise rewrite. Regions,
the repository's own lines between marker comments, are read from the
committed file and written back in place on every render.
Classes:
| Name | Description |
|---|---|
Fragment |
One piece of content an extension delivers. |
Output |
One file as the engine renders it. |
Functions:
| Name | Description |
|---|---|
composition |
How the fragments of target combine, by the file's type. |
plan |
Every file the listed fragments render, composed and with its regions kept. |
read_rendered |
The receipts in directory, name to digest; empty without any. |
receipts_from |
The receipts text spells, name to digest; empty for anything else. |
receipt_of |
The receipt path earns as it stands, its regions left out; None if absent. |
merge_receipts |
Two sides' receipts merged key by key, over the base they share. |
write_rendered |
Write the receipts, or remove the file when there are none. |
write_root_file |
Write one file at the root as |
apply |
Write outputs, withdraw what is gone, and say what changed. |
local_receipts |
What the engine linked or copied for this checkout alone, path to receipt. |
apply_untracked |
Write the local outputs git does not track, and nothing else. |
tracked_local |
The local outputs among outputs that git tracks, in path order. |
drift |
One line per file whose committed bytes are not what it renders. |
Attributes:
| Name | Type | Description |
|---|---|---|
PACKAGE_PREFIX |
The target prefix that names a path inside each package of the owner. |
|
RENDERED_MANIFEST |
The receipt file, name to digest, at the root and in each package. |
|
Composition |
How the fragments of one target combine. |
|
LOCAL_RECEIPT |
The checkout's own receipts: what the engine linked or copied for it alone. |
PACKAGE_PREFIX
module-attribute
¶
The target prefix that names a path inside each package of the owner.
RENDERED_MANIFEST
module-attribute
¶
The receipt file, name to digest, at the root and in each package.
Composition
module-attribute
¶
Composition = Literal['tables', 'lines', 'json', 'whole']
How the fragments of one target combine.
LOCAL_RECEIPT
module-attribute
¶
The checkout's own receipts: what the engine linked or copied for it alone.
Written by every delivery, empty when there is nothing of its own, so its presence says the checkout's own files were delivered at all; a checkout without it never had them, which the per-command repair reads (livery.workshop._reconcile.current).
Fragment
dataclass
¶
Fragment(owner: str, name: str, target: str, content: str = '', source: Path | None = None, dynamic: Callable[[Mapping[str, Any]], str] | None = None, replaces: str = '', deletes: str = '', reason: str = '', contributes: bool = False)
One piece of content an extension delivers.
Exactly one of content, source and dynamic carries the
template, except on a fragment that only deletes.
Attributes:
| Name | Type | Description |
|---|---|---|
owner |
str
|
The extension that ships it, by its listed name. |
name |
str
|
The fragment's name, unique within its owner. |
target |
str
|
The path it renders into, relative to the root, or
|
content |
str
|
The template source as a string. |
source |
Path | None
|
A file in the extension's wheel holding the template. |
dynamic |
Callable[[Mapping[str, Any]], str] | None
|
A function of the render data returning the template source, for content no static template can express. |
replaces |
str
|
|
deletes |
str
|
|
reason |
str
|
Why the replacement or deletion is wanted; required with either. |
contributes |
bool
|
Whether the fragment is data for its target's one template rather than text: its rendered content is a JSON object, merged by key with every other contribution to the target, and the template reads the result. |
Methods:
| Name | Description |
|---|---|
template |
The template source this fragment renders from. |
Output
dataclass
¶
Output(path: str, body: bytes, owners: tuple[str, ...], link: Path | None = None, local: bool = False)
One file as the engine renders it.
Attributes:
| Name | Type | Description |
|---|---|---|
path |
str
|
The file, relative to the workspace root, with |
body |
bytes
|
The bytes the file should hold. |
owners |
tuple[str, ...]
|
The fragments it was composed from, as |
link |
Path | None
|
The shipped file or directory the output links to instead of holding bytes; None for a written file. |
local |
bool
|
Whether the output belongs to this checkout alone and is never committed: a link into an installed wheel, a copy the agent reads. Its receipt is the checkout's own. |
composition ¶
composition(target: str) -> Composition
How the fragments of target combine, by the file's type.
Source code in packages/workshop/src/livery/workshop/_fragment_engine.py
plan ¶
plan(root: Path, fragments: Sequence[Fragment], order: Sequence[str], data: Mapping[str, Any], *, packages: Mapping[str, Sequence[str]] | None = None, package_data: Mapping[str, Mapping[str, Any]] | None = None) -> tuple[Output, ...]
Every file the listed fragments render, composed and with its regions kept.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
root
|
Path
|
The workspace root, where the committed files are read for their regions. |
required |
fragments
|
Sequence[Fragment]
|
What the listed extensions ship. |
required |
order
|
Sequence[str]
|
The owners in the order they apply, the base first and the repository last. |
required |
data
|
Mapping[str, Any]
|
The render data every template sees. A package target
also sees |
required |
packages
|
Mapping[str, Sequence[str]] | None
|
Each package's path, relative to the root, to the extensions it lists. |
None
|
package_data
|
Mapping[str, Mapping[str, Any]] | None
|
Render data for one package's files, by its path: what differs per package, such as its name and its release baseline. |
None
|
Returns:
| Type | Description |
|---|---|
tuple[Output, ...]
|
One output per file, sorted by path. |
Raises:
| Type | Description |
|---|---|
Failed
|
for a second owner of a one-owner file, a |
Source code in packages/workshop/src/livery/workshop/_fragment_engine.py
read_rendered ¶
The receipts in directory, name to digest; empty without any.
Source code in packages/workshop/src/livery/workshop/_fragment_engine.py
receipts_from ¶
The receipts text spells, name to digest; empty for anything else.
Source code in packages/workshop/src/livery/workshop/_fragment_engine.py
receipt_of ¶
The receipt path earns as it stands, its regions left out; None if absent.
merge_receipts ¶
merge_receipts(base: Mapping[str, str], ours: Mapping[str, str], theirs: Mapping[str, str], *, beside: Path) -> dict[str, str]
Two sides' receipts merged key by key, over the base they share.
A receipt one side changed takes that side's digest, a removal included, and one both changed alike takes it too. One both changed differently takes the digest of its file as the merge left it in beside, the directory the receipts describe, and goes when the file did: a digest that does not match its file reads as the repository's edit, and the next render would keep that file instead of rewriting it.
Source code in packages/workshop/src/livery/workshop/_fragment_engine.py
write_rendered ¶
Write the receipts, or remove the file when there are none.
Source code in packages/workshop/src/livery/workshop/_fragment_engine.py
write_root_file ¶
Write one file at the root as apply writes it, and its receipt; the lines.
output is a file a commit holds, at the root, never in a package.
Every other file and receipt stays as it is: unlike apply, this
withdraws nothing, so it writes one file while the rest of the
delivery waits. A file edited here is kept and named, as apply
keeps it.
Source code in packages/workshop/src/livery/workshop/_fragment_engine.py
apply ¶
Write outputs, withdraw what is gone, and say what changed.
A file is written when it is missing, and rewritten when its bytes are still what the engine last wrote. A file edited since is kept and named, and so is a file the engine has no receipt for whose bytes differ. A receipted file no output renders any more is removed when unedited and kept and named otherwise; either way its receipt goes, so a kept file is the repository's from then on.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
root
|
Path
|
The workspace root. |
required |
outputs
|
Sequence[Output]
|
What |
required |
packages
|
Sequence[str]
|
The package paths whose receipts the engine keeps, relative to the root. |
()
|
Returns:
| Type | Description |
|---|---|
list[str]
|
One line per file written, removed or kept, in path order. |
Source code in packages/workshop/src/livery/workshop/_fragment_engine.py
local_receipts ¶
What the engine linked or copied for this checkout alone, path to receipt.
apply_untracked ¶
Write the local outputs git does not track, and nothing else.
The write fm sync --locked makes: a checkout's own files (the
agent's fragments, skills and settings) are made current, and no
file a commit holds is written, removed or receipted. A local
output git tracks is left as it is; the drift check names it.
Source code in packages/workshop/src/livery/workshop/_fragment_engine.py
tracked_local ¶
The local outputs among outputs that git tracks, in path order.
A local output is the checkout's own, written for it alone and
ignored through its directory's managed .gitignore; a tracked one
was committed before that, and stays tracked whatever the ignore
file says. Empty when git cannot answer.
Source code in packages/workshop/src/livery/workshop/_fragment_engine.py
drift ¶
One line per file whose committed bytes are not what it renders.
A receipted file no output renders any more is drift too while it is unedited, since the next apply removes it; an edited one is the repository's and says nothing.