Skip to content

Commit 251559b

Browse files
committed
Merge main #1068 for direct-submit delivery
2 parents 17b6db0 + aa00966 commit 251559b

7 files changed

Lines changed: 458 additions & 11 deletions

File tree

‎architecture.md‎

Lines changed: 13 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -3241,8 +3241,10 @@ transactions](#replay-and-effect-transactions).
32413241

32423242
#### Managed checkout reuse
32433243

3244-
An ordinary Repository or Worktree selects a managed checkout under `~/.xmd/repositories`,
3245-
addressed by a digest of its whole identity and described by a closed version 1 sidecar
3244+
An ordinary Repository or Worktree selects a managed checkout under `~/.xmd/repositories`.
3245+
A workspace-marked REPL entry instead selects beneath its existing session workspace,
3246+
as described in [Session workspace placement](#session-workspace-placement). Both use
3247+
the same selector, with slots addressed by a digest of the whole identity and a closed version 1 sidecar
32463248
written by exclusive temporary sibling plus atomic rename only after the checkout is
32473249
complete and verified. The slot is entered under an exclusive non-blocking advisory lock
32483250
held for the whole document execution, so a second process is refused rather than made
@@ -3345,8 +3347,9 @@ worktree. A workflow run has none.
33453347

33463348
#### Managed bytes
33473349

3348-
A managed checkout is a Repository or Worktree an ordinary `xmd run` created under
3349-
the host root `~/.xmd/repositories`, addressed by a digest of its whole identity, described by a
3350+
A managed checkout is a Repository or Worktree created under the host root
3351+
`~/.xmd/repositories`, or under the session workspace for a marked REPL entry,
3352+
addressed by a digest of its whole identity, described by a
33503353
closed version 1 sidecar written beside it, and held for one document execution by an
33513354
exclusive non-blocking advisory lock. It survives every execution: nothing deletes,
33523355
resets, cleans, fetches or repairs one.
@@ -6721,8 +6724,12 @@ Completed entries remain projections. Old bytes are never rewritten, and an
67216724
older reader that rejects unknown members refuses a marked history.
67226725

67236726
The workspace root is passed directly from the entry owner into the CLI-private
6724-
recorder, only for marked entries. The captured project cwd is a separate direct
6725-
input for lazy ambient discovery and ordinary commit identity. Native Git still
6727+
recorder, only for marked entries. Fresh selections in those entries use
6728+
`<workspace>/repositories` as their managed root, including linked Worktrees.
6729+
Unmarked entries keep the configured host root. A nested Dir cannot retarget
6730+
that root. Acknowledged placements retain their recorded paths without moving
6731+
checkouts or validating current HEAD on replay. The captured project cwd is a
6732+
separate direct input for lazy ambient discovery and ordinary commit identity. Native Git still
67266733
requires an operation to name a valid selected checkout; a workspace cwd supplies
67276734
no project fallback. The Sidekick's native provider keeps the captured project
67286735
`agentCwd`, or the caller's explicit dependency, and its existing identity and

‎packages/cli/src/deno-repositories.ts‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,8 @@
88
* operation, but fail to start at all. Only `deno.ts`, `compiled.ts` and the
99
* two REPL hosts beside them import this file, and all of them are Deno.
1010
*
11-
* Managed checkouts live beneath `~/.xmd/repositories` and survive every
11+
* Ordinary managed checkouts live beneath `~/.xmd/repositories`; workspace-marked
12+
* REPL entries use their session workspace. Checkouts survive every
1213
* execution: what is in one is somebody's work, and nothing deletes one. There
1314
* is no environment variable naming a different root, because the only caller
1415
* that needs one is a test, and a test is handed the root directly.
@@ -28,6 +29,7 @@ import { Execution } from "@executablemd/core/api";
2829
import type { Plugin, PluginInstallRequest, PluginInstallation } from "@executablemd/core/api";
2930
import type { Operation } from "effection";
3031
import { cwd } from "@executablemd/runtime";
32+
import { join } from "node:path";
3133
import { gitPlugin } from "@executablemd/git";
3234
import { useRunComposition } from "@executablemd/git/deno";
3335
import { replRepositoryInstallation } from "./repl/repositories/deno/provider.ts";
@@ -135,7 +137,7 @@ export function denoReplEntry(helper: HelperAssembly, root: string): ReplEntryIn
135137
return (owner, placement) =>
136138
replRepositoryInstallation(owner, {
137139
helper: configured,
138-
root,
140+
root: placement?.workspace === undefined ? root : join(placement.workspace, "repositories"),
139141
...placement,
140142
});
141143
}

‎packages/cli/src/documents/sidekick/entries.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -169,6 +169,48 @@ arguments for continuation, or `null` when there is no more. If a later read's
169169
cursor refuses because the answer changed, restart the read without the cursor.
170170
Nothing these reads return authorizes a repository change.
171171

172+
### Acquire a repository for later entries
173+
174+
Read `<Guide.Environment />`, `<REPL.Environment />` and
175+
`<REPL.Syntax names={["Repository", "File"]} />` first. Replace the example
176+
locator and creation base below with the selected repository and resolved commit:
177+
178+
````xmd
179+
<Let as="code" select="code">
180+
```xmd
181+
<Repository name="project" url="/known/repository" base="KNOWN_COMMIT" as="checkout" />
182+
{checkout}
183+
```
184+
</Let>
185+
<REPL.EntryInput>{code}</REPL.EntryInput>
186+
<REPL.Submit />
187+
````
188+
189+
Follow the receipt's read instruction and inspect the actual outcome and checkout
190+
binding. An entry can print a refusal; status alone proves no acquisition.
191+
Derive a relative checkout path from the returned absolute path and the workspace
192+
reported by `<REPL.Environment />`. Replace `RELATIVE_CHECKOUT` below with that
193+
observed address, preserving the rest of this later response:
194+
195+
````xmd
196+
<Let as="code" select="code">
197+
```xmd
198+
<File path="RELATIVE_CHECKOUT/README.md" as="readme" />
199+
{readme}
200+
```
201+
</Let>
202+
<REPL.EntryInput>{code}</REPL.EntryInput>
203+
<REPL.Submit />
204+
````
205+
206+
Read that entry's output. This new read uses the current checkout and needs no
207+
new Repository selection, including after reopening the session. An acknowledged
208+
old read still answers with its historical text. Inspect actual Git origin and
209+
HEAD when revision identity matters: the requested `base` is the creation base,
210+
while a compatible checkout may since have advanced. Fresh same-base acquisition
211+
preserves that current HEAD and local changes. An incompatible repository or
212+
creation base refuses; do not reset work to force reuse.
213+
172214
### Test, fix and reuse a session component
173215

174216
When asked to create and test a component, write its definition and a companion

‎packages/cli/src/documents/sidekick/environment.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,12 @@ answer.
1717
- Write session components under `components/`, copied inputs under `inputs/`,
1818
and generated files at an appropriate workspace-relative path. These files
1919
survive reopening; another session has its own directory.
20+
- On Deno and compiled hosts, a fresh `<Repository>` selection in a submitted
21+
entry places its checkout beneath this workspace's `repositories/`. Worktrees
22+
follow that root. Read the actual returned checkout path and current workspace
23+
before deriving a relative address; do not guess the slot layout. Later entries
24+
can read that relative path without acquiring again, including after reopening.
25+
Existing recorded placements keep their paths. Placement grants no permission.
2026
- Component lookup searches the invocation's configured directories first,
2127
then this session's `components/`, then ordinary registered defaults. Explicit
2228
includes replace the project defaults. Read the selected origin through

0 commit comments

Comments
 (0)