Skip to content

Commit fef5de8

Browse files
authored
✨ Add the ordinary run's repository provider (#643) (#695)
* ✨ Add the ordinary run's repository provider (#643) The seam exists; this is the second implementation of it. A provider that works against the caller's own filesystem rather than a retained workflow run: no WorkflowRun, no Workspace, no journal, nothing to replay. What makes a checkout this execution's is an advisory lock, and what makes it the same checkout tomorrow is the sidecar beside it. It discovers the repository the execution was started inside — canonical common directory as identity, canonical checkout root as the selection, so starting in a linked worktree names the same repository as starting in the primary checkout while Git operations still act on the worktree. It places managed Repositories and Worktrees under `~/.xmd/repositories` at a digest of their whole identity, describes each with a closed version 1 sidecar written by exclusive temporary sibling plus atomic rename only after the checkout is complete, and holds each slot for one document execution with a kernel-released non-blocking advisory lock — so a second process is refused immediately rather than made to wait, and a crash releases the slot without cleanup. Nothing deletes, resets, cleans, fetches or repairs a managed checkout: what is in one is somebody's work. Local Git performs the same authored transitions the workflow performers do, directly against the authenticated checkout, under the same fixed configuration that disables hooks, signing, file-system monitors and repository-supplied helper programs. A commit records the invoking user's own effective Git identity, captured from the trusted host before the document expands; a host that can name no identity refuses `<Git.Commit>` and names the commands that fix it rather than writing the workflow identity into somebody's repository, and every other component stays usable. Push keeps the observe/adopt/fast-forward/refuse rules and stores one private evidence entry per verified publication in the provider instance's own closure. `<PullRequest>` requires the exact matching entry that instance holds: a Push for another checkout, repository, origin, destination, branch or commit is irrelevant, a later Push of the same destination supersedes the earlier entry, and missing or conflicting evidence is a local refusal before a credential is opened. Nothing crosses executions. No entrypoint installs any of this yet — the suites install it themselves through the trusted test installer, and `architecture.md` gains the terminology these structures need but no status row, because nothing on main can reach them. The certified tier suite is split by capability rather than carried whole: ambient and local Git, managed checkouts, live remotes. Every describe block is intact, all 51 cases are preserved, and shared fixtures moved to tests/support/run-composition-tier.ts. * 🔒️ Select a checkout only under the whole repository identity (#643) `selectCheckout()` admitted a registered checkout as a candidate when its identity's `locatorFingerprint` equalled the authenticated contextual one. A fingerprint names where a repository came from, not which repository it is: two `<Repository>` elements naming one url under two names are two repositories, with separate slots, separate advisory leases and separate Push evidence, and every other member of their identities is equal. So a `<Dir>` into the second one, written where the first is the Repository in scope, passed selection authentication against the first and then acted in a checkout the first never selected. Under that path `<Git.Switch>` moved the second repository's branch, and `<Git.Push>` reached its origin and recorded publication evidence for it. The candidate now has to equal the contextual identity under `sameRepositoryIdentity`, so every member of `REPOSITORY_IDENTITY_MEMBERS` participates and the comparison stays in one place rather than becoming a second partial one. Nothing legitimate narrows: every checkout of a repository already carries that repository's identity, and a Worktree registers under its owner's, so longest-containing-checkout selection among a repository's own checkouts is unchanged. The regression asks for the refusal at the three surfaces that reach different things — a local mutation, a publication and a Git host — and observes the second repository's branch, head, index, working tree and remote refs rather than inferring them. It counts the authentication sessions the host opened and the credentials the Git host was asked for, so "nothing was reached" is measured. Two controls keep it from passing vacuously: the same document shape reaching every one of those boundaries when the identity does match, with the session counter non-empty there under the same fixtures, and a Worktree of the Repository in scope still operating when entered by its returned path. * 🐛 Stop the ordinary-run tier depending on the host's Git identity (#643) Two CI-only failures, both in this tier's own tests. `refsOf` used `toSorted()`. The Node shards run `tsc --project tsconfig.node.json`, which targets ES2022, so the call does not exist there — TS2550, before a single test runs, on all five shards. Reverted to `sort()`, which is what the neighbouring helpers in this tier already do: the array being sorted is the one `map` just made, so there is nothing of anyone else's to mutate. Eleven cases then failed on `UnresolvedGitIdentityError` — ORC3, ORC4, ORC5, four in ORC14, three in ORC15 and one in ORC17. They reach `<Git.Commit>` without saying who the commit is by, so the provider fell through to its production default and read the *host's* Git configuration. That passes on a machine with `user.name` set and fails on every CI runner, which is to say the suite was asserting something about who ran it rather than about the document. `runOrdinaryDocument` now installs a fixed identity, spread first so a case that supplies its own reader still wins — which is how the ORC13 cases that are *about* identity resolution keep working, including the one that proves `<Git.Commit>` refuses when the host can say nothing. Verified by reproducing the runner rather than trusting the reading: with `user.useConfigOnly` set and no configuration file, `git var GIT_AUTHOR_IDENT` fails exactly as it does in CI, and the four suites went from 6 failed (11 steps) to 17 passed (60 steps). They also still pass with an identity present, so neither direction is assumed. --------- Co-authored-by: Taras Mankovski <[email protected]>
1 parent 1721c06 commit fef5de8

19 files changed

Lines changed: 5462 additions & 5 deletions

‎architecture.md‎

Lines changed: 8 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,10 @@ Existing documents and code get aligned to this section retroactively.
3434
| definition base | the Git revision supplied to choose a workflow definition's pinned commit |
3535
| Repository base | the optional Git revision from which one named Repository initializes its primary checkout |
3636
| Repository selection | plain structural composition data naming the repository one component invocation acts on: an opaque provider-minted selection identifier, the display name, the credential-free repository identity, and the selected checkout path. It carries no credential, provider handle, lock, database, run ID or authority — the installed provider authenticates every selection against private state before it touches Git or a service, so a copied, replaced or rebuilt one can misname a target and be refused but can never reach one |
37+
| ambient Repository | the repository an ordinary document execution was started inside, discovered once before root expansion from the invocation's starting directory. Its identity is the canonical common Git directory and its selected checkout is the canonical checkout root, so starting in a linked worktree names the same repository as starting in the primary checkout while Git operations still act on the worktree. A workflow run has none |
38+
| managed checkout | a Repository or Worktree an ordinary document execution created under the host root `~/.xmd/repositories`, addressed by a digest of its whole identity, described by a closed version 1 sidecar written beside it, and held for one document execution by an exclusive non-blocking advisory lock. It survives every execution: nothing deletes, resets, cleans, fetches or repairs one |
39+
| ordinary Git identity | the invoking user's effective Git author and committer name and email, captured once from the trusted host's own environment and configuration before a document expands and kept in the provider's closure. It is used for an ordinary `<Git.Commit>` and nothing else, because that commit lands in the caller's own checkout; a workflow run keeps its one fixed identity, whose whole purpose is that retained Git state does not depend on whose machine made it. It is not a prop, a Context value, a component result or a middleware answer, and nothing else about the environment is borrowed with it — hooks, file-system monitors, signing programs and repository-supplied credential helpers stay disabled by the same fixed command-line configuration. A host where Git can name no identity refuses `<Git.Commit>` with an actionable sentence rather than substituting the workflow one; every other component is unaffected |
40+
| ordinary invocation identity | a fresh opaque random value an ordinary document execution's repository provider mints for itself and keeps in its own closure. It is not a prop, a Context value, a component result, a middleware answer, a lifecycle ID or a retained record, and it is neither addressable nor reusable; live Issue and pull-request idempotency and reconciliation keys are derived from it together with the engine's own expansion identity |
3741
| pinned commit | the commit obtained by resolving a base once; it remains the workflow run's starting repository state even as the run creates descendant commits |
3842
| document target | an addressable static heading in a root document's own Markdown flow, named by the canonical path of heading labels that reaches it; selecting one executes the preamble, each ancestor's own content, and that heading's complete subtree |
3943
| Prompt | a person's original request, in ordinary natural language. `xmd plan` takes exactly one |
@@ -2384,9 +2388,10 @@ A Repository selection is composition data and is therefore replaceable: a
23842388
document may bind one, render one, hand one to a child, and construct one that
23852389
looks exactly like it. Nothing a repository provider does is authorized by the
23862390
value it was handed. What stays provider-owned, in the provider's own closure,
2387-
is everything a selection is *not*: the canonical Git identity each selection
2388-
resolves to, the retained rows behind it, and the credentials and locators used
2389-
to reach a service. A selection that the provider did not mint, or one whose
2391+
is everything a selection is *not*: the advisory locks on managed checkouts,
2392+
the canonical Git identity each selection resolves to, an ordinary run's live
2393+
Push evidence, its invocation identity, and every reconciliation key derived
2394+
from them. A selection that the provider did not mint, or one whose
23902395
name, checkout path or identity was edited after it did, is refused before Git
23912396
or a service is touched.
23922397

‎packages/workflow/deno.ts‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -141,3 +141,14 @@ export type {
141141
SuspensionControllerOptions,
142142
SuspensionNotice,
143143
} from "./src/deno/suspension.ts";
144+
/**
145+
* The ordinary run's repository provider.
146+
*
147+
* The installer alone, and the options a trusted entrypoint supplies to it.
148+
* What the provider holds — the leases, the credential assembly, the selection
149+
* registry, the live Push evidence and the metadata writer — stays inside it:
150+
* a package that could reach one of those could authorize a publication this
151+
* execution never made.
152+
*/
153+
export { useRunComposition } from "./src/deno/run-composition/provider.ts";
154+
export type { RunCompositionOptions } from "./src/deno/run-composition/provider.ts";
Lines changed: 168 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,168 @@
1+
/**
2+
* The repository the person running the document is standing in.
3+
*
4+
* A workflow document names every repository it touches, because a workflow is
5+
* a program that runs somewhere else. An ordinary `xmd run` is a command
6+
* somebody typed in a checkout, so the checkout is the obvious subject — and
7+
* making it the default is what lets a document say
8+
*
9+
* ```md
10+
* <Worktree name="issue-643" branch="issue-643">…</Worktree>
11+
* ```
12+
*
13+
* and mean the repository the command was run in.
14+
*
15+
* ## Two identities, and they are not the same
16+
*
17+
* The **common Git directory** identifies the repository; the **checkout root**
18+
* identifies which of its checkouts this invocation is in. They differ exactly
19+
* when the caller is standing in a linked worktree — where `.git` is a file
20+
* naming the primary repository's administration — and keeping them apart is
21+
* what makes starting XMD in a worktree produce the same Repository identity as
22+
* starting it in the primary checkout, while Git operations still act on the
23+
* worktree the command was actually run in.
24+
*
25+
* ## Discovery is not an operation the document asked for
26+
*
27+
* It happens once, before root expansion, from the invocation's starting
28+
* directory. Being outside a repository is not a startup failure: a document
29+
* that never asks for a Repository-dependent operation runs exactly as it would
30+
* anywhere else, and only an element that needs one refuses.
31+
*
32+
* The `origin` is read the same way, and its absence is likewise not a failure.
33+
* A repository with no origin is a perfectly good Repository for a Worktree, a
34+
* Switch, an Add and a Commit; it is only Push and PullRequest that need a
35+
* destination, and each of those checks for one before it opens a credential.
36+
*/
37+
38+
import { realpath } from "node:fs/promises";
39+
import { basename } from "node:path";
40+
import { until, type Operation } from "effection";
41+
import type { GitObjectFormat } from "../../composition/records.ts";
42+
import { admitLocator, locatorFingerprint } from "../composition/locator.ts";
43+
import { currentBranch, readObjectFormat, resolveCommit } from "../composition/git.ts";
44+
import type { GitSession } from "../composition/git.ts";
45+
46+
/** What one Git checkout on this host turned out to be. */
47+
export interface AmbientRepository {
48+
/** The display name a document sees: the checkout directory's own name. */
49+
readonly name: string;
50+
/** The canonical root of the checkout the invocation started in. */
51+
readonly checkoutRoot: string;
52+
/** The canonical common Git directory, which identifies the repository. */
53+
readonly commonDirectory: string;
54+
readonly objectFormat: GitObjectFormat;
55+
/** The commit HEAD named when this invocation started. */
56+
readonly head: string;
57+
/** The locally recorded, admitted `origin`, or `undefined` when there is none. */
58+
readonly origin: string | undefined;
59+
readonly originFingerprint: string | undefined;
60+
/**
61+
* The branch a `<PullRequest>` defaults its base to.
62+
*
63+
* `refs/remotes/origin/HEAD` when the checkout records one, and the branch
64+
* this invocation started on otherwise. Nothing is asked of a remote for it:
65+
* a default branch this run had to fetch would make an ordinary document
66+
* reach the network before it did anything.
67+
*/
68+
readonly defaultBranch: string;
69+
}
70+
71+
/**
72+
* The canonical directory this path resolves to, or `undefined`.
73+
*
74+
* Canonicalization matters more than usual here. `/var` on macOS is
75+
* `/private/var`, and Git writes the resolved path into a linked worktree's
76+
* administration — so a comparison against an unresolved path would report a
77+
* worktree as belonging to no repository.
78+
*/
79+
function* canonical(path: string): Operation<string | undefined> {
80+
try {
81+
return yield* until(realpath(path));
82+
} catch {
83+
return undefined;
84+
}
85+
}
86+
87+
/**
88+
* Discover the ambient repository from this directory, or answer `undefined`.
89+
*
90+
* Every step is a local Git question. Nothing here contacts a remote, opens a
91+
* credential or writes anything.
92+
*/
93+
export function* discoverAmbientRepository(
94+
git: GitSession,
95+
from: string,
96+
): Operation<AmbientRepository | undefined> {
97+
const reportedRoot = yield* git.read(["rev-parse", "--show-toplevel"], from);
98+
if (reportedRoot === undefined) {
99+
return undefined;
100+
}
101+
const checkoutRoot = yield* canonical(reportedRoot);
102+
if (checkoutRoot === undefined) {
103+
return undefined;
104+
}
105+
106+
const reportedCommon = yield* git.read(["rev-parse", "--git-common-dir"], checkoutRoot);
107+
if (reportedCommon === undefined) {
108+
return undefined;
109+
}
110+
// Without `--path-format=absolute`, which not every supported Git has: a
111+
// linked worktree already answers absolutely, and a primary checkout answers
112+
// `.git` relative to itself.
113+
const commonDirectory = yield* canonical(
114+
reportedCommon.startsWith("/") ? reportedCommon : `${checkoutRoot}/${reportedCommon}`,
115+
);
116+
if (commonDirectory === undefined) {
117+
return undefined;
118+
}
119+
120+
const objectFormat = yield* readObjectFormat(git, checkoutRoot);
121+
const head = yield* resolveCommit(git, checkoutRoot, "HEAD");
122+
if (objectFormat === undefined || head === undefined) {
123+
// A directory Git recognizes but cannot say the shape of is not a
124+
// repository this provider will act on. Refusing here is the same answer as
125+
// being outside one, and for the same reason: nothing has been read that
126+
// could name a checkout.
127+
return undefined;
128+
}
129+
130+
const branch = yield* currentBranch(git, checkoutRoot);
131+
const recorded = yield* git.read(["config", "--get", "remote.origin.url"], checkoutRoot);
132+
// Admitted on the way in, not on the way out: what is not a locator this
133+
// provider would hand to Git is a repository with no usable origin, which is
134+
// a state Push and PullRequest already know how to refuse.
135+
const origin = recorded === undefined ? undefined : admitLocator(recorded);
136+
137+
const recordedDefault = yield* git.read(
138+
["symbolic-ref", "--quiet", "--short", "refs/remotes/origin/HEAD"],
139+
checkoutRoot,
140+
);
141+
const defaultBranch = defaultFrom(recordedDefault, branch);
142+
143+
return Object.freeze({
144+
name: basename(checkoutRoot),
145+
checkoutRoot,
146+
commonDirectory,
147+
objectFormat,
148+
head,
149+
origin,
150+
originFingerprint: origin === undefined ? undefined : locatorFingerprint(origin),
151+
defaultBranch,
152+
});
153+
}
154+
155+
/**
156+
* The default branch, from what the checkout records.
157+
*
158+
* `refs/remotes/origin/HEAD` reads as `origin/main`, and what a base names is
159+
* `main`. A detached HEAD with no recorded remote default leaves nothing to
160+
* name, and the empty string is what a `<PullRequest>` then has to be given a
161+
* `base` for.
162+
*/
163+
function defaultFrom(recorded: string | undefined, branch: string | undefined): string {
164+
if (recorded !== undefined && recorded.startsWith("origin/")) {
165+
return recorded.slice("origin/".length);
166+
}
167+
return recorded ?? branch ?? "";
168+
}

0 commit comments

Comments
 (0)