2cde2a9032
Conflict resolution notes: - package.json/run-gates: both sides' new doc-sync gates kept (master's scoped-events/readme gates + this branch's website-api/website-yaml); js-yaml devDeps deduped (master added them independently). - pnpm-workspace/knip: website AND python/sdk-runtime entries kept. - doc-typecheck/verify-type-equiv: master's condensed headers kept, website glob retained in both scan scopes. - vendor/cordis/src/fiber.ts: master's lifecycle-hardening code taken; this branch's richer FiberState JSDoc reapplied on top. vendor/README.md logs both local modifications (hardening = 6, JSDoc enrichment = 7). - pnpm-lock: regenerated from master's side (pnpm install). Post-merge sync the gates forced (the system working as designed): - verify-website-yaml caught 4 stale plugin names from master's package reorg (dsh-stdio-agent -> dsh-stdio-demo, dsh-acp-agent -> dsh-acp-demo); 8 references fixed across guide/ and develop/. - gen-website-api picked up master's 6 new services automatically (ctx.approval/permission/sandbox/sessionQuery/skills/tasks -> 6 new pages + sidebar); api/index.md hub updated to list them. - AGENTS.md budget ceiling 1370 -> 1400: the website rows (layout line + two command lines) and master's own growth collided with the old ceiling; all three website rows are load-bearing (new top-level dir, new CI command).
119 lines
4.8 KiB
Markdown
119 lines
4.8 KiB
Markdown
<!-- Generated by scripts/gen-website-api.ts — do not edit by hand. Run `pnpm run gen-website-api` to regenerate. -->
|
|
|
|
# ctx.fs
|
|
|
|
`FileSystem` (abstract seam) — provided by `@deepseek-ai/dsh-fs`.
|
|
|
|
Abstract filesystem provider. Targets must preserve identity across aliases; reads expose regular UTF-8 text or typed errors, listings are stable and content-free, and mutations are atomic. Optional guards add stale protection without changing the unguarded provider contract.
|
|
|
|
[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/fs/fs/src/index.ts#L78)
|
|
|
|
### ctx.fs.resolve(path, opts?)
|
|
|
|
```ts website-api
|
|
abstract resolve(path: string, opts?: { cwd?: string }): Promise<FsTarget>
|
|
```
|
|
|
|
Resolve a model/plugin-supplied path into a stable FsTarget. May perform I/O (a remote/sandboxed backend may need a round-trip to map a path to a stable identity), hence async even though the local backend only normalizes + realpaths.
|
|
|
|
- `path` — the path to resolve; relative paths resolve against `opts.cwd`.
|
|
- `opts` — `cwd` overrides the backend's default base for relative paths.
|
|
|
|
**Returns** the stable target; the same file yields the same `targetKey`.
|
|
|
|
[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/fs/fs/src/index.ts#L92)
|
|
|
|
### ctx.fs.stat(target, signal?)
|
|
|
|
```ts website-api
|
|
abstract stat(target: FsTarget, signal?: AbortSignal): Promise<FsInfo | undefined>
|
|
```
|
|
|
|
Return target metadata, or `undefined` when the target does not exist.
|
|
|
|
- `target` — the resolved target to stat.
|
|
- `signal` — aborts the metadata round-trip.
|
|
|
|
**Returns** metadata only, never content; undefined for an absent target.
|
|
|
|
[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/fs/fs/src/index.ts#L100)
|
|
|
|
### ctx.fs.readText(target, signal?)
|
|
|
|
```ts website-api
|
|
abstract readText(target: FsTarget, signal?: AbortSignal): Promise<string>
|
|
```
|
|
|
|
Read the whole regular text file as a single decoded string.
|
|
|
|
- `target` — the resolved target to read.
|
|
- `signal` — aborts the read.
|
|
|
|
**Returns** the full decoded UTF-8 content.
|
|
|
|
[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/fs/fs/src/index.ts#L108)
|
|
|
|
### ctx.fs.streamText(target, signal?)
|
|
|
|
```ts website-api
|
|
abstract streamText(target: FsTarget, signal?: AbortSignal): Promise<AsyncIterable<string>>
|
|
```
|
|
|
|
Stream the whole regular text file as decoded text chunks (same text semantics as readText, for large files). The backend owns cross-chunk UTF-8 decoding and binary rejection so the policy layer never touches raw bytes.
|
|
|
|
- `target` — the resolved target to read.
|
|
- `signal` — aborts the stream, including between chunks.
|
|
|
|
**Returns** the chunk iterable, decoded and validated like `readText`.
|
|
|
|
[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/fs/fs/src/index.ts#L119)
|
|
|
|
### ctx.fs.listDir(target, signal?)
|
|
|
|
```ts website-api
|
|
abstract listDir(target: FsTarget, signal?: AbortSignal): Promise<FsDirEntry[]>
|
|
```
|
|
|
|
List direct children of a directory in stable name order. Returns resolved child targets plus cheap metadata only; never reads file contents.
|
|
|
|
- `target` — the resolved directory target.
|
|
- `signal` — aborts the listing.
|
|
|
|
**Returns** one entry per direct child, in stable name order.
|
|
|
|
[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/fs/fs/src/index.ts#L128)
|
|
|
|
### ctx.fs.writeText(target, content, expected?, signal?)
|
|
|
|
```ts website-api
|
|
abstract writeText(target: FsTarget, content: string, expected?: FsWriteIntent, signal?: AbortSignal): Promise<FsWriteOutcome>
|
|
```
|
|
|
|
Atomically create or replace UTF-8 text. `expected` guards intent and staleness; omission allows unconditional overwrite.
|
|
|
|
- `target` — the resolved target to write.
|
|
- `content` — the full new file content.
|
|
- `expected` — the write intent guarding the write; omit for unconditional.
|
|
- `signal` — aborts before the atomic rename takes effect.
|
|
|
|
**Returns** the outcome, including the version the write produced.
|
|
|
|
[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/fs/fs/src/index.ts#L139)
|
|
|
|
### ctx.fs.editText(target, edit, expected?, signal?)
|
|
|
|
```ts website-api
|
|
abstract editText(target: FsTarget, edit: FsEditRequest, expected?: { version: FsVersion }, signal?: AbortSignal): Promise<FsEditOutcome>
|
|
```
|
|
|
|
Atomically edit literal text. When supplied, the version guard is checked before matching so stale content reports `FS_STALE_VERSION`; omission edits the current content without a freshness precondition.
|
|
|
|
- `target` — the resolved target to edit.
|
|
- `edit` — the literal search/replace request.
|
|
- `expected` — the version guard; omit for an unconditional edit.
|
|
- `signal` — aborts before the atomic rename takes effect.
|
|
|
|
**Returns** the outcome, including the version the edit produced.
|
|
|
|
[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/fs/fs/src/index.ts#L151)
|