Generated from modules.json by crystal run spec/support/generate.cr; edit that file, not this one.

Fossil

Reading and writing Fossil, through operations named for what they do.

• src/ocx/fossil.cr: Reach Fossil only through operations named for what they do, on a Place: where fossil acts, on the host or in a sandbox, its transport private and its one start of the fossil program; read a setting.
• src/ocx/fossil/said.cr: Read the forum posts and ticket changes that may hold an OCX message, each with its thread or ticket, its text and its receipt (the user, whether it has an address, its number), in the order received; the check-ins among the artifacts listed, with their branches and receipts; artifacts' receipts; and what a user may do, as Fossil grants it, inherited capabilities included.
• src/ocx/fossil/repository.cr: Ask Fossil what a repository holds besides its artifacts: a user's password, the default user, its login group, the checkout a directory is in, the remote, the names it resolves, a checkout's changes, its public URL, and its hooks.
• src/ocx/fossil/tickets.cr: Read and write tickets' changes in Fossil: a ticket's newest change, the tickets and threads a prefix of a hash names, and a comment appended as a user.
• src/ocx/fossil/forum.cr: Read and write forum posts in Fossil: a post a prefix of its hash names, read from its artifact, and a reply or a thread's first post composed as Fossil's forum artifact and put in through a checkout, an empty one of a repository named outright.
• src/ocx/fossil/wiki.cr: Read and write wiki pages in Fossil: the names of the pages with a prefix, every version of a page with its text as its artifact holds it and the user and receipt it came by, and a new page written as a given user, as create reads a pattern and import copies the patterns.
• src/ocx/fossil/checkins.cr: Read and write check-ins and their tags in Fossil: when the newest was made, who checked one in, a tag on one with the user Fossil received it from, and a tag added.
• src/ocx/fossil/sync.cr: Clone, open, close and push with Fossil, a repository opened empty for what Fossil does only in a checkout, saying why a push did not reach its remote; import git's fast-export, export a repository to git and read where its export stands.
• src/ocx/fossil/direct.cr: Read a repository's database directly in Crystal, query-only, waiting on Fossil's lock as Fossil does, the second implementation of Fossil's reads; and find the checkout a directory is in by its checkout file, from there up. Seed a new git export's state, so its first export keeps an imported upstream's commits.
• src/ocx/hook.cr: Log each after-receive hook run as one JSON line, after bringing the repository's git export up to date when a check-in arrived and, given a node user, being that node of protocol v1 over the artifacts listed, each run to start handed to a watcher of its own through the release root's link; act at once on what a tool wrote on the repository itself, and check every run when the node starts; say how it is installed for a release root, read where it stands on a repository and read back its last run.

Protocol

Protocol v1 and the tools: what OCX writes in Fossil and reads back, and how each tool is defined, reached and answered.

• src/ocx/git.cr: Reach git through the operations OCX uses: the refs a fetch is offered and the pack it is answered with, on the host; and an upstream's bare clone, its default branch and its branches' fast-export with marks, in a sandbox; starting git in one private place with PATH alone in its environment.
• src/ocx/git_export.cr: Serve a repository's git export read-only over git's smart HTTP, from where fossil git export recorded it, refusing pushes, viewers who may not read code and requests too large.
• src/ocx/refusal.cr: Name what a caller can cause, one exception every tool answers as a refusal: input not understood, or not allowed or possible now.
• src/ocx/elements.cr: Define OCX's typed elements: a branch's JSON, derived shape, walk and reading from text, all from its type; every input's dry_run; and the leaves with rules of their own.
• src/ocx/log.cr: Perform every operation of a run through one log, the one place the dry-run flag is honored: a check is performed in a dry run too, a change only for real; each operation typed, so the log is derived from what ran.
• src/ocx/text.cr: Write any element as text, the CLI's layout and MCP's text, from its type alone.
• src/ocx/cli.cr: Read a command line by the shape of a tool's input and print the answer as text or JSON, with the CLI's own flags.
• src/ocx/command.cr: Define a tool once, generically: the context it receives, its one method with the log, and its answer, each shape derived from its type.
• src/ocx/commands.cr: Find every tool by walking Command's subclasses, and run one on its input as named text or JSON.
• src/ocx/entry.cr: Choose the entry point by the program's name, or MCP for ocx2 --mcp, and resolve the caller once.
• src/ocx/mcp.cr: Offer every tool over JSON-RPC: tools/list as the list tool's answer, tools/call into the tool's typed input; served by ocx2 --mcp too; the edge where JSON is read.
• src/ocx/commands/audit.cr: Record a verdict on a check-in as an audited tag by the caller, never its author, from a clone and pushed or on the served repository, and read it back as the served repository holds it.
• src/ocx/messages.cr: Read and write protocol v1's OCX messages: find the one an artifact's text holds, its fences paired as CommonMark pairs them; read it into the struct of its kind; write a message, or an object's members, as a fenced block.
• src/ocx/messages/run.cr: Hold a run's layers as protocol v1, sections 5 to 8, defines them: its workspace steps, its sandbox with every field required, its limits and its process; and check what a run's own text decides, refusing with the note its ended carries.
• src/ocx/steps.cr: Fill a run's $$name$$ values, and check its workspace steps against the table of step kinds when it arrives, before any step: what each needs before it, the values it sets, and where its paths may lie; and that its sandbox paths keep apart from the node's own files.
• src/ocx/node/view.cr: Hold what a node sees of the server on one round: its host's directories, the values it sets before a run's first step, its own files, the runs it was sent and the users of nodes, as the situation each run's decision reads.
• src/ocx/decisions.cr: Decide what a node does next about one run, from what it knows and with no Fossil in it: wait, refuse with a note, answer it stopped or lost, start it, end its program for a stop, or nothing; protocol v1's rules as one function its failure cases test.
• src/ocx/server.cr: Say what the server says, as a node reaches it: who sent an artifact, what a user may do there, and the server's order; the URL a run's clone is made from, and a run user's password; and what a report needs to count once written. On the server's repository, from its own receipts, setting a fresh password on a run's user; on a clone, from the server's receipt tool over HTTPS, signed in as the node user through Fossil's login page, with passwords from the node's file, readable by its owner alone, and each report pushed and checked on the server.
• src/ocx/node.cr: Be a node of protocol v1, on the server's repository or a clone of it: each time the hook runs, or a node on a clone pulls, decide each run for the node among the artifacts that arrived, or named by a stop that arrived, from the repository and who the server says sent each, in the server's order; write the answers it can, refused, stopped and lost, as the node user, under a lock so that no run is answered twice; ask a running program's watcher to end it for a stop; name the runs to start; and give each running session what it subscribes to among the artifacts that arrived, a line of JSON in its inbox. A run is in its care while its watcher holds the run's lock.
• src/ocx/care.cr: Keep the node's care of its runs as locks in its directory: the one a round or a watcher holds while it decides and writes, each run's, held by its watcher and naming the watcher and the program it launched, and each run user's; ask a watcher to end its program for a stop, and end what a watcher that has gone left of one.
• src/ocx/served.cr: Find on the served repository what a caller gives a tool: a thread or ticket, a post replied to, a run by a prefix of its hash with the node it names, and where the hook stands, with the node it names.
• src/ocx/writes.cr: Write for a tool's caller: where it writes, a comment appended to a ticket, in the caller's clone and pushed or on the served repository, and this host's node acting at once on what a tool wrote on the repository itself, which starts no hook, a failure of it naming what was written.
• src/ocx/commands/post.cr: Write a plain post as the caller from a clone's checkout: a reply in the thread of the post replied to, put in the clone and pushed, or a change to a ticket; refusing text that holds an OCX message.
• src/ocx/commands/receipt.cr: Say of each artifact who the served repository received it from, that user's capabilities there, the receipt's number and the artifact's row number, or that it has not received it; or a user's capabilities. Never an address, nor anything of an artifact its caller may not read: protocol v1's receipt tool, which nodes and readers on clones ask.
• src/ocx/commands/node.cr: Be a node of protocol v1 on a host other than the server's, such as a build host: on its clone, sign in to the server as the node user, pull, and act on the runs among what the pull brought, as the server's node acts on what its hook is given, or with check on every run for the node, handing each run to start to a watcher that reaches the server as the node does.

Workspace

Where a run's program works, and how it is confined: its workspace, sandbox, inbox and watcher.

• src/ocx/workspaces.cr: Lay out a run's workspace under the agents root, by its user, project and run, and give its clone a fresh random password and the public URL it is made from, checked, with the user and password in it.
• src/ocx/sandbox.cr: Name bubblewrap, the one program that confines a process, and start a sandbox or a run's process with the one call that starts either; say how a process ended, by its status or the signal that ended it, and keep the end of what it printed.
• src/ocx/tasks.cr: Hold OCX's own jobs in a sandbox, such as an import's git and fossil, as data: a task's sandbox and limits written as a run's layers, its workspace the directory it works in, run through the same plan and the one start as a run's process.
• src/ocx/session.cr: Make a run's inbox, a named pipe in the node's directory held open for reading and writing, as large as Linux lets it be, and inherited by no program; put a line in one whole or not at all, never waiting; and start a detached process, such as a watcher, in a session of its own: the one place one is started.
• src/ocx/commands/create.cr: Write a run as the caller on the served repository: the first post of a new thread, a reply to a post, or a change to a ticket, its fields from a pattern's JSON block, the version of its wiki page an admin or setup wrote, and those given over them, checked as a node checks it; this host's node acting on it at once when the run names it.
• src/ocx/commands/run.cr: Start a manual run by hand: find it by a prefix of its hash, refuse it unless it is manual, decide it as this host's node would, started by a person, saying why the node leaves it waiting, and have the node act on it, handing it to a watcher, which writes its started and ended.
• src/ocx/commands/stop.cr: Write a stop for a run as the caller on the served repository, where the run is: a reply to its post, or a change to its ticket; this host's node acting on it at once when the run names it.
• src/ocx/launch.cr: Perform a run's or a task's layers as tables: each workspace step's act, each sandbox field as bubblewrap's arguments in the protocol's order, each limit as what enforces it, the program found on the right PATH, a plan run to its end, and the kept logs as a post.
• src/ocx/watcher.cr: Watch one run of protocol v1 as a process of its own, holding the run's lock and its user's: decide it again under the node's lock, perform its workspace steps, write started with the values it used, run its process as its sandbox and limits layers give it, its run and a session's deliveries on its standard input, or for a session whose deliveries each start a process, one process for its run and one for each delivery in turn, keep the ends of its STDERR and STDOUT in the workspace and post them, write ended (exited, limit, or stopped on TERM), and hand on the next run of the same user; and hand each run to start to such a watcher.
• src/ocx/relay.cr: Relay a session's deliveries from its inbox to its program's standard input, in order, holding up to a bound of what the program has not taken, past which it reads the inbox no more, so the hook, which never waits on a session, gives it nothing more.

Console

The console, served by Fossil as a CGI program.

• src/ocx/markdown.cr: Write any element as Markdown, the web page's layout, from its type alone: sections for its branches, tables for its schemas, a line for each operation, letting a page draw an item of a list itself.
• src/ocx/commands/echo.cr: Answer with exactly the arguments read and who gave them, so every way in can be shown to deliver the same input.
• src/ocx/commands/list.cr: List every tool with the derived shape of its input, what runs when no tool is named and what MCP lists; help adds each output's shape, the context's and the answer's, and where releases live.
• src/ocx/commands/status.cr: Show who is calling and from where: the context as resolved, the release, what the root serves and offers, where its hook stands on the served repository and what its node offers; find the release's source at its own check-in.
• src/ocx/cgi.cr: Answer Fossil's CGI requests as Markdown in the skin: the list with each tool as a card, or a tool's answer with a button back to the list and its own card, or JSON.
• src/ocx/page.cr: Lay out the web page around the Markdown walk: a style block taking its colours from the skin, the strip of the context's facts, and each tool as a card with a link to where it is defined, the capabilities it needs marked for the viewer, what it would do now, and its form unless a POST of it would be refused.
• src/ocx/commands/hook.cr: Install or remove the after-receive hook on the served repository, as the release root's link to the served release, leaving other hooks alone, and read back where it stands.
• src/ocx/commands/export.cr: Bring the served repository's git export up to date from the command line on its host or the web page, a failed export refused with what Fossil said, and say where the export stands; a dry run lists what awaits.
• src/ocx/commands/import.cr: Make a new served repository of a git repository beside the served one: its branches cloned, exported and imported in a sandbox, its git export seeded with the upstream's own commits, placed, given the hook as the served one has it, and joined to the served one's login group, so its admin signs in to it as to the served one; leaving nothing when it fails.

Release

Building, staging, accepting and rolling back releases.

• src/ocx/worktree.cr: Start the tree's own programs, crystal and shards, the one place they are started, to gate and build a release.
• src/ocx/releases.cr: Keep the release root: stage a release as next, accept it into the root, install it the first time, and roll back.
• src/ocx/staging.cr: Stage a committed checkout's built programs as a release named for its check-in, smoked before it is offered.
• src/ocx/commands/release.cr: Offer staging, accepting and rolling back a release as commands.

Git

Git clients reading a Fossil export.

• src/ocx/mirror.cr: Keep a repository's git export current: run fossil git export into the export its setting names, one run at a time, a run asked for meanwhile making it export again, keep the last run in the export's .git, and read where the export stands as fossil git status says.