Skip to content

Commit 0b48453

Browse files
committed
Import approved host assets through Sidekick
1 parent aa00966 commit 0b48453

15 files changed

Lines changed: 1118 additions & 13 deletions

File tree

‎architecture.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6695,6 +6695,43 @@ no project fallback. The Sidekick's native provider keeps the captured project
66956695
`agentCwd`, or the caller's explicit dependency, and its existing identity and
66966696
configuration.
66976697

6698+
### Approved host asset import
6699+
6700+
The captured CLI-private `<REPL.ImportAsset source="/known/mock ü.html"
6701+
destination="inputs/mock ü.html" />` control imports one non-repository regular
6702+
file into the existing session workspace. The root passes that directory directly;
6703+
response cwd and props cannot retarget it. Missing workspace or importer refuses.
6704+
The native adapter checks effective read/write restrictions before metadata I/O,
6705+
after approval and before publication. Ordinary Files and repository acquisition
6706+
keep their existing owners.
6707+
6708+
Preparation resolves metadata and retains one exact source/destination pair.
6709+
Core elicitation presents that pair and the workspace-relative result with exact
6710+
Import/Decline choices and no initial answer. Only validated Import permits content
6711+
access or destination data effects. Closing remains unanswered; Stop withdraws
6712+
and joins this response's question without answering an entry's independent one.
6713+
6714+
The adapter copies bytes into a private temporary directory beneath the final
6715+
parent, then publishes the complete payload with a no-replace hard link. The link
6716+
names the staged copy, never the external source. Existing files, directories,
6717+
dangling links and late collisions survive. Relative containment and observed
6718+
parent links use the existing stable-host-namespace guarantee. A collision requires
6719+
another explicit destination and fresh approval.
6720+
6721+
Cleanup is armed before acquisition. Each non-abortable native mutation retains
6722+
its completion and joins it before staging removal. Success follows complete
6723+
publication and successful cleanup. Cancellation during issued publication can
6724+
leave complete bytes, and cleanup preserves them. Cleanup failure or uncertain
6725+
publication stops the exchange; neither becomes ordinary refused-control feedback.
6726+
6727+
The existing control intent retains both operands before work. Only a joined
6728+
ordinary Result receives an outcome; only success designates the relative path.
6729+
An append failure supplies no success. Unfinished imports remain unknown: passive
6730+
cold inspection reads no source, restarts no question and copies nothing. Later
6731+
ordinary entries read the workspace copy, independently of the external source.
6732+
There is no crash reconciliation, automatic retry, adoption or atomic host-file
6733+
and journal transaction.
6734+
66986735
### Response-owned component testing
66996736

67006737
`repl/sidekick/testing.ts` executes REPL.Test documents in fresh children of the

‎packages/cli/src/bun-repl.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
import { useNodeReplAssetImport } from "./node-repl-asset-import.ts";
12
/**
23
* The REPL's host on Bun.
34
*
@@ -19,6 +20,7 @@ import { XMD_VERSION } from "./cli.ts";
1920
import { useBunReplTerminal } from "./bun-repl-terminal.ts";
2021

2122
export function* useBunRepl(): Operation<void> {
23+
yield* useNodeReplAssetImport();
2224
yield* installReplHost({
2325
dataRoot: () => platformDataRoot(process.platform, homedir(), process.env, sep),
2426
// What this process is, stated here because this is where it is known.

‎packages/cli/src/compiled-repl.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
import { useNodeReplAssetImport } from "./node-repl-asset-import.ts";
12
/**
23
* The REPL's host inside the compiled binary.
34
*
@@ -19,6 +20,7 @@ import { XMD_VERSION } from "./cli.ts";
1920
import { useCompiledReplTerminal } from "./compiled-repl-terminal.ts";
2021

2122
export function* useCompiledRepl(): Operation<void> {
23+
yield* useNodeReplAssetImport();
2224
yield* installReplHost({
2325
dataRoot: () => platformDataRoot(process.platform, homedir(), process.env, sep),
2426
// What this process is, stated here because this is where it is known.

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
import { useNodeReplAssetImport } from "./node-repl-asset-import.ts";
12
/**
23
* The REPL's host on Deno.
34
*
@@ -19,6 +20,7 @@ import { XMD_VERSION } from "./cli.ts";
1920
import { useDenoReplTerminal } from "./deno-repl-terminal.ts";
2021

2122
export function* useDenoRepl(): Operation<void> {
23+
yield* useNodeReplAssetImport();
2224
yield* installReplHost({
2325
dataRoot: () => platformDataRoot(process.platform, homedir(), process.env, sep),
2426
// What this process is, stated here because this is where it is known.

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

Lines changed: 24 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,17 @@ answer.
2323
before deriving a relative address; do not guess the slot layout. Later entries
2424
can read that relative path without acquiring again, including after reopening.
2525
Existing recorded placements keep their paths. Placement grants no permission.
26+
- Import a non-repository asset directly in your response with
27+
`<REPL.ImportAsset source="/known/external/mock ü.html" destination="inputs/mock ü.html" />`.
28+
Propose `inputs/<original filename>`, preserving spaces and Unicode. The
29+
question shows the exact resolved source, destination and relative result.
30+
Only Import permits copying; Decline or Stop copies nothing while approval
31+
waits. A supplied path alone is not approval. Use the returned relative path
32+
for later ordinary reads, including after reopening.
33+
- An occupied file, directory or symlink refuses import. Choose another explicit
34+
destination and request fresh approval. An unfinished import has an unknown
35+
outcome; inspect the saved evidence and destination before another request.
36+
Repository files follow repository acquisition.
2637
- Component lookup searches the invocation's configured directories first,
2738
then this session's `components/`, then ordinary registered defaults. Explicit
2839
includes replace the project defaults. Read the selected origin through
@@ -55,8 +66,9 @@ answer.
5566
- An entry's subprocesses are its own: they are started under the entry's
5667
permissions, captured and recorded, and released with it. They are not a shell
5768
you hold open across entries.
58-
- You have no native shell, file-editing or MCP tools. File and command work
59-
belongs in an ordinary entry, under that entry's permissions.
69+
- You have no native shell, file-editing or MCP tools. Ordinary File and command work
70+
belongs in an entry, under that entry's permissions. Use the direct import
71+
control for non-repository host assets.
6072
- Workspace policy and language rules are different things. The language says
6173
what you may write; the workspace says what this execution may reach. A
6274
construct can be perfectly valid and still be refused here.
@@ -72,15 +84,18 @@ answer.
7284
The host returns the facts it knows — and its explicit unknowns — as feedback,
7385
then asks for your next response.
7486

75-
For an explicitly known project at `/known/project`, this **entry** copies one
76-
input into the session workspace. Replace that example path with the actual
77-
known project path before submission:
87+
For a known non-repository asset, write this in your **response**:
7888

7989
```xmd
80-
<Dir path="/known/project">
81-
<File path="request.md" as="request" />
82-
</Dir>
83-
<File path="inputs/request.md">{request}</File>
90+
<REPL.ImportAsset source="/known/external/mock ü.html" destination="inputs/mock ü.html" />
91+
```
92+
93+
The person sees the exact source and destination before any file content is
94+
read. After Import succeeds, feedback gives `inputs/mock ü.html`. A later
95+
**entry** reads that copy, including after reopening:
96+
97+
```xmd
98+
<File path="inputs/mock ü.html" />
8499
```
85100

86101
## Common mistake
Lines changed: 235 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,235 @@
1+
import { copyFile, link, mkdir, mkdtemp, realpath } from "node:fs/promises";
2+
import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
3+
import { lstat, rm, stat } from "@effectionx/fs";
4+
import { elicit, isJsonObject } from "@executablemd/core";
5+
import { cwd } from "@executablemd/runtime";
6+
import { Permissions } from "@executablemd/runtime/api";
7+
import { ensure, Err, Ok, scoped, until } from "effection";
8+
import type { Operation, Result } from "effection";
9+
import { ReplHost } from "./repl/host.ts";
10+
import type { AssetImportRequest } from "./repl/host.ts";
11+
12+
const nativeOperations = {
13+
copyFile,
14+
link,
15+
mkdir: (path: string, options: { recursive: true }) => mkdir(path, options),
16+
mkdtemp: (path: string) => mkdtemp(path),
17+
realpath: (path: string) => realpath(path),
18+
};
19+
20+
export function* useNodeReplAssetImport(native = nativeOperations): Operation<void> {
21+
yield* ReplHost.around(
22+
{
23+
importAsset: ([request]) => importAsset(request, native),
24+
},
25+
{ at: "min" },
26+
);
27+
}
28+
29+
function joined<T>(start: () => Promise<T>, adopt: (value: T) => void = () => {}): Operation<T> {
30+
return scoped(function* () {
31+
let pending: Promise<T> | undefined;
32+
yield* ensure(function* () {
33+
if (pending !== undefined) {
34+
yield* until(
35+
pending.then(
36+
() => undefined,
37+
() => undefined,
38+
),
39+
);
40+
}
41+
});
42+
pending = start().then((value) => {
43+
adopt(value);
44+
return value;
45+
});
46+
return yield* until(pending);
47+
});
48+
}
49+
50+
function* allowed(): Operation<void> {
51+
if (
52+
!(yield* Permissions.operations.files("read")) ||
53+
!(yield* Permissions.operations.files("write"))
54+
) {
55+
throw new ImportRefusal("Asset import requires effective file read and write permission.");
56+
}
57+
}
58+
59+
function inside(root: string, path: string): boolean {
60+
const suffix = relative(root, path);
61+
return (
62+
suffix === "" || (!isAbsolute(suffix) && suffix !== ".." && !suffix.startsWith(`..${sep}`))
63+
);
64+
}
65+
66+
function code(error: unknown, name: string): boolean {
67+
return error instanceof Error && "code" in error && error.code === name;
68+
}
69+
70+
function* vacant(path: string): Operation<void> {
71+
try {
72+
yield* lstat(path);
73+
} catch (error) {
74+
if (code(error, "ENOENT")) {
75+
return;
76+
}
77+
throw error;
78+
}
79+
throw new ImportRefusal(
80+
"The import destination is occupied. Choose another explicit destination and obtain new approval.",
81+
);
82+
}
83+
84+
function* destinationPath(
85+
root: string,
86+
destination: string,
87+
native: typeof nativeOperations,
88+
): Operation<string> {
89+
if (destination.length === 0 || isAbsolute(destination)) {
90+
throw new ImportRefusal("Choose a nonempty workspace-relative import destination.");
91+
}
92+
const target = resolve(root, destination);
93+
if (target === root || !inside(root, target)) {
94+
throw new ImportRefusal("Choose an import destination inside the session workspace.");
95+
}
96+
let parent = dirname(target);
97+
while (true) {
98+
try {
99+
const actual = yield* joined(() => native.realpath(parent));
100+
if (!inside(root, actual)) {
101+
throw new ImportRefusal(
102+
"The import destination parent leaves the session workspace. Choose another destination.",
103+
);
104+
}
105+
break;
106+
} catch (error) {
107+
if (!code(error, "ENOENT")) {
108+
throw error;
109+
}
110+
const next = dirname(parent);
111+
if (next === parent) {
112+
throw error;
113+
}
114+
parent = next;
115+
}
116+
}
117+
yield* vacant(target);
118+
return target;
119+
}
120+
121+
function importAsset(
122+
request: AssetImportRequest,
123+
native: typeof nativeOperations,
124+
): Operation<Result<string>> {
125+
const { workspace, source: offeredSource, destination } = request;
126+
return scoped(function* () {
127+
let source: string;
128+
let root: string;
129+
let target: string;
130+
try {
131+
if (
132+
typeof offeredSource !== "string" ||
133+
offeredSource.length === 0 ||
134+
typeof destination !== "string" ||
135+
typeof workspace !== "string" ||
136+
workspace.length === 0
137+
) {
138+
throw new ImportRefusal(
139+
"Import requires a source, a destination and this session's workspace.",
140+
);
141+
}
142+
yield* allowed();
143+
const current = yield* cwd();
144+
source = yield* joined(() => native.realpath(resolve(current, offeredSource)));
145+
if (!(yield* stat(source)).isFile()) {
146+
throw new ImportRefusal("Choose a regular source file to import.");
147+
}
148+
root = yield* joined(() => native.realpath(workspace));
149+
target = yield* destinationPath(root, destination, native);
150+
} catch (error) {
151+
return refused(error);
152+
}
153+
const answer = yield* elicit({
154+
schema: {
155+
type: "object",
156+
properties: {
157+
decision: { type: "string", title: "Import this file?", enum: ["Import", "Decline"] },
158+
},
159+
required: ["decision"],
160+
additionalProperties: false,
161+
},
162+
message: `Source: ${source}\nDestination: ${target}\nWorkspace path after import: ${destination}\nImport copies this file into your session workspace.`,
163+
});
164+
if (!isJsonObject(answer) || answer.decision !== "Import") {
165+
return Err(new Error("Asset import declined. No file was copied."));
166+
}
167+
let temporary: string | undefined;
168+
yield* ensure(function* () {
169+
if (temporary !== undefined) {
170+
yield* rm(temporary, { recursive: true, force: true });
171+
}
172+
});
173+
try {
174+
yield* allowed();
175+
if (!(yield* stat(source)).isFile()) {
176+
throw new ImportRefusal(
177+
"The approved source is no longer a regular file. Request a new import.",
178+
);
179+
}
180+
target = yield* destinationPath(root, destination, native);
181+
yield* joined(() => native.mkdir(dirname(target), { recursive: true }));
182+
yield* joined(
183+
() => native.mkdtemp(join(dirname(target), ".xmd-import-")),
184+
(path) => {
185+
temporary = path;
186+
},
187+
);
188+
if (temporary === undefined) {
189+
throw new Error("Asset import staging was not acquired.");
190+
}
191+
const payload = join(temporary, "payload");
192+
yield* joined(() => native.copyFile(source, payload));
193+
yield* allowed();
194+
try {
195+
yield* joined(() => native.link(payload, target));
196+
} catch (error) {
197+
if (code(error, "EEXIST")) {
198+
return Err(
199+
new Error(
200+
"The import destination became occupied. Choose another explicit destination and obtain new approval.",
201+
),
202+
);
203+
}
204+
throw new PublicationError(error);
205+
}
206+
} catch (error) {
207+
if (error instanceof PublicationError) {
208+
throw error;
209+
}
210+
return refused(error);
211+
}
212+
return Ok(destination);
213+
});
214+
}
215+
216+
class PublicationError extends Error {
217+
constructor(cause: unknown) {
218+
super(
219+
"Asset import publication could not be established. Inspect the destination before requesting another import.",
220+
{ cause },
221+
);
222+
}
223+
}
224+
225+
class ImportRefusal extends Error {}
226+
227+
function refused(error: unknown): Result<never> {
228+
if (
229+
error instanceof ImportRefusal ||
230+
(error instanceof Error && "code" in error && typeof error.code === "string")
231+
) {
232+
return Err(error);
233+
}
234+
throw error;
235+
}

‎packages/cli/src/node-repl.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
import { useNodeReplAssetImport } from "./node-repl-asset-import.ts";
12
/**
23
* The REPL's host on Node.
34
*
@@ -19,6 +20,7 @@ import { XMD_VERSION } from "./cli.ts";
1920
import { useNodeReplTerminal } from "./node-repl-terminal.ts";
2021

2122
export function* useNodeRepl(): Operation<void> {
23+
yield* useNodeReplAssetImport();
2224
yield* installReplHost({
2325
dataRoot: () => platformDataRoot(process.platform, homedir(), process.env, sep),
2426
// What this process is, stated here because this is where it is known.

0 commit comments

Comments
 (0)