Skip to content

Commit 638a92c

Browse files
committed
🌳 Name a Git repository inside a workflow run
The third slice of #293, and the first one a document can reach. `<Repository>` names a locator and gets one primary named-branch checkout; `<Dir>` moves the working directory without creating anything. Both are ordinary registered defaults the workflow host installs for a live or partial execution, so a repository-local component with either name is chosen ahead of them. Creation is one durable Workspace effect. The first live reach admits the locator, resolves the base exactly once, pins the commit and retains the whole checkout — objects, working tree, modes, symbolic links — so the imported bytes, the metadata row, the published Workspace root and the filtered journal result commit together or not at all. Resolution happens once: a remote whose default branch moves afterwards changes nothing, because replay restores the pin rather than asking again. HEAD is never left detached; a base that resolves only to a tag or a bare commit gets a deterministic provider-owned branch, and the record says which. Attachment is ephemeral and happens every time, which is what makes a partial replay safe to continue from. It rebuilds the checkout from the Workspace root the journal selected and proves it is still the one the record names: where it came from, how it names objects, and whether the creation commit is in it. Readable is not identity — a valid clone of an unrelated repository is perfectly readable — and `.git` must be a real directory, because the operating system resolves a working directory before Git is given one. What is deliberately not asked is where HEAD is: #294 moves that transactionally. A refusal the provider recognizes is a failed durable outcome against the unchanged root, reported with a fixed sanitized word. It fails the operation it is part of like any other Effection work; an authored `<PrintErrors>` region is what decides otherwise, for its whole region. Retained state that disagrees with the record is fatal instead, and travels past every printing boundary. Ownership is visible in the modules: `repository.ts` is what a `<Repository>` creates and attaches, `effects.ts` the durable envelope, `refusals.ts` the words a refusal travels in, `identity.ts` holding a retained record to the identity that names it, and `provider.ts` the wiring. `<Worktree>` and the linked-checkout half of the control plane are the slice above this one. Refs #293
1 parent 3afd0a7 commit 638a92c

25 files changed

Lines changed: 4455 additions & 11 deletions

‎packages/workflow/deno.ts‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,5 +38,13 @@ export type { WorkflowLifecycleOptions } from "./src/deno/lifecycle.ts";
3838
export { hashRunId, workflowRunLock, workflowRunPath } from "./src/deno/path.ts";
3939
export { APPLICATION_ID, SCHEMA_VERSION } from "./src/deno/schema.ts";
4040
export { withWorkflowWorkspace } from "./src/deno/workspace/host.ts";
41+
export type { WorkflowWorkspaceOptions } from "./src/deno/workspace/host.ts";
42+
export { WORKSPACE_REPOSITORY } from "./src/deno/composition/provider.ts";
43+
export type {
44+
CompositionObserver,
45+
CompositionProviderOptions,
46+
} from "./src/deno/composition/provider.ts";
47+
export { denoRepositoryHost } from "./src/deno/composition/host.ts";
48+
export type { GitInvocation, GitOutcome, RepositoryHost } from "./src/deno/composition/host.ts";
4149
export { WORKSPACE_FILE } from "./src/deno/workspace/files.ts";
4250
export { WORKSPACE_ROOT } from "./src/deno/workspace/logical-path.ts";

‎packages/workflow/mod.ts‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,34 @@ export { getWorkflowRun, retainedWorkflowInstallation, workflowInstallation } fr
4141
export type { WorkflowRun } from "./src/run.ts";
4242
export { useWorkflowServiceDenial, WorkflowServiceDeniedError } from "./src/service-denial.ts";
4343

44+
export { RepositoryComposition } from "./src/composition/api.ts";
45+
export type { RepositoryCompositionApi } from "./src/composition/api.ts";
46+
export { currentRepository, RepositoryContext } from "./src/composition/context.ts";
47+
export type { RepositoryContextApi } from "./src/composition/context.ts";
48+
export {
49+
RepositoryCompositionError,
50+
RepositoryCompositionProtocolError,
51+
RepositoryCompositionProviderError,
52+
RepositoryStaleStateError,
53+
WorktreeCompositionError,
54+
} from "./src/composition/errors.ts";
55+
export type { RepositoryFailureReason, WorktreeFailureReason } from "./src/composition/errors.ts";
56+
export {
57+
parseRepositoryRecord,
58+
parseWorktreeRecord,
59+
repositoryRecordJson,
60+
sameRepositoryRecord,
61+
sameWorktreeRecord,
62+
worktreeRecordJson,
63+
} from "./src/composition/records.ts";
64+
export type {
65+
RepositoryCreationRequest,
66+
RepositoryRecord,
67+
WorktreeCreationRequest,
68+
WorktreeRecord,
69+
} from "./src/composition/records.ts";
70+
export { useCompositionComponents } from "./src/composition/installation.ts";
71+
4472
export { WorkspaceCoordination, WorkspaceCoordinationProviderError } from "./src/workspace/api.ts";
4573
export type { WorkspaceCoordinationApi } from "./src/workspace/api.ts";
4674
export { createDurableWorkspaceOperation } from "./src/workspace/effect.ts";
Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
/**
2+
* The provider-neutral Repository/Worktree composition Api.
3+
*
4+
* Repository components ask this Api for work; the installed
5+
* provider decides how to do it. This package names no subprocess, no host
6+
* filesystem and no runtime: a workflow host with the authority to touch a Git
7+
* checkout — the Deno host, for now — installs a concrete provider inside its
8+
* `withWorkflowWorkspace()` attachment.
9+
*
10+
* Each component performs two steps against it, and the split is what makes
11+
* replay work. **Creation** is the durable half: it clones, resolves, pins and
12+
* retains, and a completed one restores from the journal without contacting
13+
* anything. **Attachment** is the ephemeral half: it runs every time, live or
14+
* replayed, and its job is to rebuild the live facade and check that the
15+
* retained state the journal selected is still the state that is there. Partial
16+
* replay therefore reattaches without recreating, and a retained checkout that
17+
* has gone missing is discovered where it can still stop the run.
18+
*
19+
* The default handler throws. There is no in-memory fallback: a Repository that
20+
* "starts" without a provider would retain nothing while claiming it had.
21+
*/
22+
23+
import { type Api, createApi } from "@effectionx/context-api";
24+
import type { Operation } from "effection";
25+
import { RepositoryCompositionProviderError } from "./errors.ts";
26+
import type { RepositoryCreationRequest, RepositoryRecord } from "./records.ts";
27+
28+
export interface RepositoryCompositionApi {
29+
/**
30+
* Create or restore the named Repository's creation identity.
31+
*
32+
* One durable effect. A live first reach authorizes the locator, resolves the
33+
* base once, pins the commit and retains the checkout; a replayed one returns
34+
* what was retained without reaching a remote.
35+
*/
36+
createRepository(request: RepositoryCreationRequest): Operation<RepositoryRecord>;
37+
38+
/**
39+
* Rebuild the live facade for a Repository whose creation identity is settled,
40+
* and verify that the Workspace still holds the state that identity names.
41+
*
42+
* Ephemeral: it appends nothing and is performed on every execution.
43+
*/
44+
attachRepository(record: RepositoryRecord): Operation<void>;
45+
}
46+
47+
export const RepositoryComposition: Api<RepositoryCompositionApi> =
48+
createApi<RepositoryCompositionApi>("executablemd.workflow.composition.repository", {
49+
// deno-lint-ignore require-yield
50+
*createRepository(_request: RepositoryCreationRequest): Operation<RepositoryRecord> {
51+
throw new RepositoryCompositionProviderError("<Repository>");
52+
},
53+
// deno-lint-ignore require-yield
54+
*attachRepository(_record: RepositoryRecord): Operation<void> {
55+
throw new RepositoryCompositionProviderError("<Repository>");
56+
},
57+
});
Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
/**
2+
* `<Dir path="..">` — lexical working directory
3+
* (specs/workflow-workspace-spec.md §6.3).
4+
*
5+
* One meaning and one effect on the world: the content expands with `path` as
6+
* the contextual working directory, and the enclosing one is restored when the
7+
* invocation ends — on success, failure and cancellation alike, because the
8+
* installation lives on the invocation's own scope.
9+
*
10+
* It creates nothing and retains nothing. A `<Dir>` inside a `<Repository>`
11+
* leaves that Repository contextual, which is what lets the self-closing
12+
* Worktree spelling work: the path is bound by `as`, `<Dir>` moves the working
13+
* directory to it, and the Repository a later Git component would act on is
14+
* still the enclosing one.
15+
*
16+
* Self-closing `<Dir />` is invalid. A working directory installed for no
17+
* content is a directory nothing runs in, and silently rendering nothing would
18+
* hide a document that meant to write children. Being invalid, it fails the
19+
* operation it is part of; an authored `<PrintErrors>` region may recover from
20+
* that explicitly, and nothing here decides it on an author's behalf.
21+
*/
22+
23+
import { API, cwd } from "@executablemd/runtime";
24+
import { content, hasContent } from "@executablemd/core";
25+
import type { Operation } from "effection";
26+
import type { Json } from "@executablemd/durable-streams";
27+
28+
export const props = {
29+
type: "object",
30+
properties: {
31+
path: { type: "string", minLength: 1 },
32+
},
33+
required: ["path"],
34+
additionalProperties: false,
35+
};
36+
37+
export class DirInvocationError extends Error {
38+
override name = "DirInvocationError";
39+
}
40+
41+
export default function* Dir(props: Record<string, Json>): Operation<string> {
42+
const path = props.path;
43+
if (typeof path !== "string" || path === "") {
44+
throw new DirInvocationError("<Dir> needs a non-empty path.");
45+
}
46+
47+
if (!(yield* hasContent())) {
48+
throw new DirInvocationError(
49+
`<Dir path=${JSON.stringify(path)} /> is invalid: Dir installs a working directory for ` +
50+
`its content, and a self-closing invocation has none. Write it as <Dir path=` +
51+
`${JSON.stringify(path)}>…</Dir>.`,
52+
);
53+
}
54+
55+
// A bound Workspace path is absolute and is used as written; anything else is
56+
// read the way every other authored path is read — against the directory the
57+
// document is already working in. `<Dir path="nested">` inside a Repository
58+
// therefore means that Repository's `nested`, and a `<Dir>` that meant the
59+
// Workspace root would be the surprising one.
60+
const enclosing = yield* cwd();
61+
const target = path.startsWith("/")
62+
? path
63+
: `${enclosing.endsWith("/") ? enclosing.slice(0, -1) : enclosing}/${path}`;
64+
65+
yield* API.Env.around(
66+
{
67+
// deno-lint-ignore require-yield
68+
*cwd(): Operation<string> {
69+
return target;
70+
},
71+
},
72+
{ at: "min" },
73+
);
74+
return yield* content();
75+
}
Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
/**
2+
* `<Repository>` — name a Git repository inside the run's Workspace
3+
* (specs/workflow-workspace-spec.md §6.1).
4+
*
5+
* Two forms, one meaning. Lexical
6+
* `<Repository name=".." url={..}>…</Repository>` creates or restores the named
7+
* checkout, then expands its content with that Repository installed as the
8+
* contextual one and its checkout as the contextual working directory. Both are
9+
* restored when the invocation ends, on success, failure and cancellation
10+
* alike, because they live on the invocation's own scope.
11+
*
12+
* Self-closing `<Repository name=".." url={..} />` creates or restores the same
13+
* checkout, renders nothing, and returns the stable Workspace-relative checkout
14+
* path. Nothing here reaches into how `as` works: the engine's ordinary capture
15+
* binds the returned string, which is what keeps `as` one rule rather than a
16+
* Repository-shaped exception to one.
17+
*
18+
* ## Who decides what a failure means
19+
*
20+
* This component describes what went wrong; it does not decide what the
21+
* document does about it. A refusal it recognizes — a locator it will not use,
22+
* a base that names no commit, a name already this run's for another url —
23+
* arrives as a fixed `RepositoryCompositionError` and then fails the operation
24+
* it is part of, like any other Effection work. An authored `<PrintErrors>`
25+
* region is what says otherwise, and it says so for everything inside it rather
26+
* than for this component alone.
27+
*
28+
* Declaring `printErrors` here would have made that decision for every author,
29+
* for every failure this invocation owns: invalid props, a provider that is not
30+
* installed, a protocol answer that will not parse. None of those is a refusal
31+
* a document asked for, and continuing past one would run later siblings as
32+
* though a checkout existed.
33+
*
34+
* Two things are unaffected, in opposite directions. A stale-state failure is a
35+
* durability failure and travels past every printing boundary, authored or not.
36+
* A failure of the content a caller projected is the caller's, decided by the
37+
* region that text is written in.
38+
*/
39+
40+
import { API } from "@executablemd/runtime";
41+
import { content, hasContent } from "@executablemd/core";
42+
import type { Operation } from "effection";
43+
import type { Json } from "@executablemd/durable-streams";
44+
import { RepositoryComposition } from "../api.ts";
45+
import { RepositoryContext } from "../context.ts";
46+
import { RepositoryCompositionError } from "../errors.ts";
47+
import type { RepositoryCreationRequest } from "../records.ts";
48+
49+
export const props = {
50+
type: "object",
51+
properties: {
52+
name: { type: "string", minLength: 1 },
53+
url: { type: "string", minLength: 1 },
54+
base: { type: "string", minLength: 1 },
55+
},
56+
required: ["name", "url"],
57+
additionalProperties: false,
58+
};
59+
60+
function required(props: Record<string, Json>, prop: string): string {
61+
const value = props[prop];
62+
if (typeof value !== "string" || value === "") {
63+
throw new RepositoryCompositionError(
64+
typeof props.name === "string" ? props.name : "",
65+
"invalid-locator",
66+
`<Repository> needs a non-empty ${prop}.`,
67+
);
68+
}
69+
return value;
70+
}
71+
72+
function optional(props: Record<string, Json>, prop: string): string | undefined {
73+
const value = props[prop];
74+
return typeof value === "string" && value !== "" ? value : undefined;
75+
}
76+
77+
export function parseRepositoryProps(props: Record<string, Json>): RepositoryCreationRequest {
78+
return {
79+
name: required(props, "name"),
80+
locator: required(props, "url"),
81+
base: optional(props, "base"),
82+
};
83+
}
84+
85+
export default function* Repository(props: Record<string, Json>): Operation<string> {
86+
const record = yield* RepositoryComposition.operations.createRepository(
87+
parseRepositoryProps(props),
88+
);
89+
yield* RepositoryComposition.operations.attachRepository(record);
90+
91+
if (!(yield* hasContent())) {
92+
return record.checkoutPath;
93+
}
94+
95+
yield* RepositoryContext.around({ current: () => record }, { at: "min" });
96+
yield* API.Env.around(
97+
{
98+
// deno-lint-ignore require-yield
99+
*cwd(): Operation<string> {
100+
return record.checkoutPath;
101+
},
102+
},
103+
{ at: "min" },
104+
);
105+
return yield* content();
106+
}
Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
/**
2+
* The contextual Repository a lexical `<Repository>` installs for its content.
3+
*
4+
* A stable, namespaced contextual value holding a parsed record and no
5+
* authority. `<Worktree>` reads it to learn which Repository it belongs to; the
6+
* provider decides separately whether anything may be done to that Repository,
7+
* so a replaced context can misname a Repository but cannot grant access to
8+
* one.
9+
*
10+
* Installed with `{ at: "min" }` wherever it is installed, so the nearest
11+
* enclosing Repository answers and the outer one is restored when that scope
12+
* ends. Nesting one Repository inside another therefore means what it reads as.
13+
*/
14+
15+
import { type Api, createApi } from "@effectionx/context-api";
16+
import type { Operation } from "effection";
17+
import type { RepositoryRecord } from "./records.ts";
18+
19+
export interface RepositoryContextApi {
20+
readonly current: RepositoryRecord | undefined;
21+
}
22+
23+
export const RepositoryContext: Api<RepositoryContextApi> = createApi<RepositoryContextApi>(
24+
"executablemd.workflow.composition.context",
25+
{ current: undefined },
26+
);
27+
28+
/** The currently enclosing Repository, or `undefined` when there is none. */
29+
export function currentRepository(): Operation<RepositoryRecord | undefined> {
30+
return RepositoryContext.operations.current;
31+
}
Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
/**
2+
* Registers the composition components as ordinary defaults.
3+
*
4+
* Repository and Dir are ordinary registered defaults — not
5+
* reserved and not structural — so a repository-local component may shadow
6+
* one for its own scope, and the workflow host installs them only for a live
7+
* or partial attachment. A completed root replay does not attach any
8+
* provider, so a document that already ran through completion does not
9+
* re-register them either.
10+
*/
11+
12+
import type { Operation } from "effection";
13+
import { registerComponents } from "@executablemd/core";
14+
import Repository, { props as repositoryProps } from "./components/Repository.ts";
15+
import Dir, { props as dirProps } from "./components/Dir.ts";
16+
17+
const ORIGIN = "@executablemd/workflow/composition";
18+
19+
export function useCompositionComponents(): Operation<void> {
20+
return registerComponents([
21+
{
22+
name: "Repository",
23+
origin: ORIGIN,
24+
props: repositoryProps,
25+
fn: Repository,
26+
},
27+
{
28+
name: "Dir",
29+
origin: ORIGIN,
30+
props: dirProps,
31+
fn: Dir,
32+
},
33+
]);
34+
}

0 commit comments

Comments
 (0)