From 6338fa10e948d9f62f8eea84c793a0c4255e8d66 Mon Sep 17 00:00:00 2001 From: Marqdo Agent Date: Sat, 21 Nov 2026 10:18:59 +0800 Subject: [PATCH] feat(fs): add append, read_at and recursive walk --- crates/cli/tests/stdlib_product.rs | 7 +- crates/marqdo-host/src/fs.rs | 170 +++++++++++++++++++ crates/marqdo-host/src/host.rs | 117 +++++++++++++ crates/marqdo-host/tests/resource_streams.rs | 51 ++++++ docs/STATUS.md | 7 +- docs/adr/0045-fs-append-read-at-walk.md | 46 +++++ docs/architecture/CURRENT.md | 7 +- docs/architecture/README.md | 1 + docs/evidence/2026-11-21-fs-extended.md | 39 +++++ spec/evaluation.md | 7 + stdlib/fs/file.mq.md | 27 +++ stdlib/stdlib.json | 2 +- stdlib/tests/fs.mq.md | 8 +- 13 files changed, 479 insertions(+), 10 deletions(-) create mode 100644 docs/adr/0045-fs-append-read-at-walk.md create mode 100644 docs/evidence/2026-11-21-fs-extended.md diff --git a/crates/cli/tests/stdlib_product.rs b/crates/cli/tests/stdlib_product.rs index 2129364..3572696 100644 --- a/crates/cli/tests/stdlib_product.rs +++ b/crates/cli/tests/stdlib_product.rs @@ -202,8 +202,11 @@ fn fs_test_exercises_the_file_operation_surface() { assert_eq!(items[7]["value"], true); assert_eq!(items[8]["value"], true); assert_eq!(items[9]["value"], "你好\n"); - assert_eq!(items[10]["value"], true); - assert_eq!(items[11]["value"], true); + assert_eq!(items[10]["decimal"], "7"); + assert_eq!(items[11]["value"], "你好\n世界\n"); + assert_eq!(items[12]["items"][0]["value"], "fs-b.txt"); + assert_eq!(items[13]["value"], true); + assert_eq!(items[14]["value"], true); assert!( !stdlib_dir().join("tests/out").exists(), "the fs test did not remove its directory" diff --git a/crates/marqdo-host/src/fs.rs b/crates/marqdo-host/src/fs.rs index 9703e16..d788c8d 100644 --- a/crates/marqdo-host/src/fs.rs +++ b/crates/marqdo-host/src/fs.rs @@ -4,6 +4,7 @@ //! symlink escapes outside the project root are rejected before the capability //! check, and the capability check happens before any I/O. +use std::io::{Read, Seek, SeekFrom, Write}; use std::path::{Component, Path, PathBuf}; use marqdo_span::Span; @@ -321,6 +322,131 @@ impl ProjectFs { } Ok(fs_ok(Value::None)) } + "append" => { + if args.len() != 2 { + return Err(fs_arity(operation, 2, args.len(), span)); + } + let (absolute, relative) = self.resolve(&args[0], span)?; + self.ensure_parent_inside(&absolute, &relative, span)?; + let bytes = args[1].as_bytes(); + if bytes.len() > MAX_READ_BYTES as usize { + return Err(RuntimeError::new( + ErrorCategory::ResourceExhausted, + span, + format!( + "append to `{relative}` exceeds the {} byte limit", + MAX_READ_BYTES + ), + )); + } + let mut file = std::fs::OpenOptions::new() + .append(true) + .create(true) + .open(&absolute) + .map_err(|error| { + RuntimeError::new( + ErrorCategory::HostError, + span, + format!("cannot append to `{relative}`: {error}"), + ) + })?; + file.write_all(bytes).map_err(|error| { + RuntimeError::new( + ErrorCategory::HostError, + span, + format!("cannot append to `{relative}`: {error}"), + ) + })?; + Ok(fs_ok(Value::int(bytes.len() as i64))) + } + "read_at" => { + if args.len() != 3 { + return Err(fs_arity(operation, 3, args.len(), span)); + } + let (absolute, relative) = self.resolve(&args[0], span)?; + let offset = parse_offset(&args[1], span)?; + let length = parse_offset(&args[2], span)?; + if length > MAX_READ_BYTES { + return Err(RuntimeError::new( + ErrorCategory::ResourceExhausted, + span, + format!("read_at length exceeds the {} byte limit", MAX_READ_BYTES), + )); + } + let mut file = std::fs::File::open(&absolute).map_err(|error| { + RuntimeError::new( + ErrorCategory::HostError, + span, + format!("cannot read `{relative}`: {error}"), + ) + })?; + file.seek(SeekFrom::Start(offset)).map_err(|error| { + RuntimeError::new( + ErrorCategory::HostError, + span, + format!("cannot seek `{relative}`: {error}"), + ) + })?; + let mut buffer = Vec::new(); + file.take(length) + .read_to_end(&mut buffer) + .map_err(|error| { + RuntimeError::new( + ErrorCategory::HostError, + span, + format!("cannot read `{relative}`: {error}"), + ) + })?; + let text = String::from_utf8(buffer).map_err(|_| { + RuntimeError::new( + ErrorCategory::Type, + span, + format!("`{relative}` slice is not valid UTF-8"), + ) + })?; + Ok(fs_ok(Value::text(text))) + } + "walk" => { + let (absolute, relative) = self.resolve(one_arg(operation, args, span)?, span)?; + if !absolute.exists() { + return Ok(fs_error( + "fs.not_found", + &format!("`{relative}` does not exist"), + )); + } + let absolute = self.ensure_inside(&absolute, &relative, span)?; + let metadata = std::fs::metadata(&absolute).map_err(|error| { + RuntimeError::new( + ErrorCategory::HostError, + span, + format!("cannot stat `{relative}`: {error}"), + ) + })?; + if !metadata.is_dir() { + return Ok(fs_error( + "fs.not_directory", + &format!("`{relative}` is not a directory"), + )); + } + let mut entries = Vec::new(); + walk_directory(&absolute, "", &mut entries, 0).map_err(|error| { + RuntimeError::new( + ErrorCategory::HostError, + span, + format!("cannot walk `{relative}`: {error}"), + ) + })?; + if entries.len() > 4096 { + return Err(RuntimeError::new( + ErrorCategory::ResourceExhausted, + span, + "walk exceeds the 4096 entry limit", + )); + } + Ok(fs_ok(Value::List( + entries.into_iter().map(Value::text).collect(), + ))) + } "rename" => { if args.len() != 2 { return Err(fs_arity(operation, 2, args.len(), span)); @@ -461,6 +587,50 @@ impl ProjectFs { } } +fn parse_offset(raw: &str, span: Option) -> Result { + raw.parse::().map_err(|_| { + RuntimeError::new( + ErrorCategory::Type, + span, + format!("`{raw}` is not a non-negative integer offset"), + ) + }) +} + +fn walk_directory( + dir: &Path, + prefix: &str, + out: &mut Vec, + depth: usize, +) -> std::io::Result<()> { + if depth > 64 { + return Err(std::io::Error::new( + std::io::ErrorKind::InvalidInput, + "directory depth exceeds 64", + )); + } + let mut entries = std::fs::read_dir(dir)?.collect::, _>>()?; + entries.sort_by_key(|entry| entry.file_name()); + for entry in entries { + let file_type = entry.file_type()?; + if file_type.is_symlink() { + continue; + } + let name = entry.file_name().to_string_lossy().to_string(); + let relative = if prefix.is_empty() { + name.clone() + } else { + format!("{prefix}/{name}") + }; + if file_type.is_dir() { + walk_directory(&entry.path(), &relative, out, depth + 1)?; + } else { + out.push(relative); + } + } + Ok(()) +} + fn invalid_path(span: Option, message: impl Into) -> RuntimeError { RuntimeError::new(ErrorCategory::PermissionDenied, span, message) } diff --git a/crates/marqdo-host/src/host.rs b/crates/marqdo-host/src/host.rs index 30ca530..1a67a6b 100644 --- a/crates/marqdo-host/src/host.rs +++ b/crates/marqdo-host/src/host.rs @@ -879,6 +879,123 @@ impl Host for StdHost { format!("unsupported resource operation `{operation}`"), )); }; + if name == "read_at" { + if args.len() != 3 { + return Err(RuntimeError::new( + ErrorCategory::Arity, + ctx.span, + format!( + "resource operation `fs.read_at` expects 3 arguments, got {}", + args.len() + ), + )); + } + let path_type = args[0].type_name(); + let Value::Text(path) = args[0].clone() else { + return Err(RuntimeError::type_error( + ctx.span, + format!("fs.read_at path must be Text, got {path_type}"), + )); + }; + let offset = match &args[1] { + Value::Int(value) => value.to_string(), + other => { + return Err(RuntimeError::type_error( + ctx.span, + format!("fs.read_at offset must be Int, got {}", other.type_name()), + )) + } + }; + let length = match &args[2] { + Value::Int(value) => value.to_string(), + other => { + return Err(RuntimeError::type_error( + ctx.span, + format!("fs.read_at length must be Int, got {}", other.type_name()), + )) + } + }; + self.capabilities.check_read(&path, ctx.span)?; + let result = self + .fs + .request("read_at", &[path, offset, length], ctx.span)?; + self.record_semantic( + "resource.request", + None, + Some(&ctx.module_id), + ctx.span, + Some("op=fs.read_at"), + ); + self.record_resource_effect("resource.request", ctx, started, "fs.read_at"); + return Ok(result); + } + if name == "append" { + if args.len() != 2 { + return Err(RuntimeError::new( + ErrorCategory::Arity, + ctx.span, + format!( + "resource operation `fs.append` expects 2 arguments, got {}", + args.len() + ), + )); + } + let path_type = args[0].type_name(); + let Value::Text(path) = args[0].clone() else { + return Err(RuntimeError::type_error( + ctx.span, + format!("fs.append path must be Text, got {path_type}"), + )); + }; + let text_type = args[1].type_name(); + let Value::Text(text) = args[1].clone() else { + return Err(RuntimeError::type_error( + ctx.span, + format!("fs.append text must be Text, got {text_type}"), + )); + }; + self.capabilities.check_write(&path, ctx.span)?; + let result = self.fs.request("append", &[path, text], ctx.span)?; + self.record_semantic( + "resource.request", + None, + Some(&ctx.module_id), + ctx.span, + Some("op=fs.append"), + ); + self.record_resource_effect("resource.request", ctx, started, "fs.append"); + return Ok(result); + } + if name == "walk" { + if args.len() != 1 { + return Err(RuntimeError::new( + ErrorCategory::Arity, + ctx.span, + format!( + "resource operation `fs.walk` expects 1 argument, got {}", + args.len() + ), + )); + } + let path_type = args[0].type_name(); + let Value::Text(path) = args[0].clone() else { + return Err(RuntimeError::type_error( + ctx.span, + format!("fs.walk path must be Text, got {path_type}"), + )); + }; + self.capabilities.check_read(&path, ctx.span)?; + let result = self.fs.request("walk", &[path], ctx.span)?; + self.record_semantic( + "resource.request", + None, + Some(&ctx.module_id), + ctx.span, + Some("op=fs.walk"), + ); + self.record_resource_effect("resource.request", ctx, started, "fs.walk"); + return Ok(result); + } let expected = match name { "exists" | "metadata" | "list" | "mkdir" | "remove" => 1, "rename" => 2, diff --git a/crates/marqdo-host/tests/resource_streams.rs b/crates/marqdo-host/tests/resource_streams.rs index 3778034..40ee508 100644 --- a/crates/marqdo-host/tests/resource_streams.rs +++ b/crates/marqdo-host/tests/resource_streams.rs @@ -744,3 +744,54 @@ fn process_run_requires_an_exact_program_grant() { .unwrap_err(); assert_eq!(missing.category, ErrorCategory::PermissionDenied); } + +#[test] +fn fs_append_read_at_and_walk_are_bounded() { + let dir = tempfile::tempdir().unwrap(); + let capabilities = Capabilities::project() + .allow_read("out") + .allow_read("out/**") + .allow_write("out") + .allow_write("out/**"); + let mut host = StdHost::new(SandboxMode::Project, capabilities, dir.path()); + let ctx = context(); + host.resource_request("fs.mkdir", vec![Value::text("out")], &ctx) + .unwrap(); + let appended = host + .resource_request( + "fs.append", + vec![Value::text("out/data.txt"), Value::text("hello")], + &ctx, + ) + .unwrap(); + assert_eq!(field(&appended, "value"), &Value::int(5)); + host.resource_request( + "fs.append", + vec![Value::text("out/data.txt"), Value::text(" world")], + &ctx, + ) + .unwrap(); + let slice = host + .resource_request( + "fs.read_at", + vec![Value::text("out/data.txt"), Value::int(6), Value::int(5)], + &ctx, + ) + .unwrap(); + assert_eq!(field(&slice, "value"), &Value::text("world")); + let walked = host + .resource_request("fs.walk", vec![Value::text("out")], &ctx) + .unwrap(); + assert_eq!( + field(&walked, "value"), + &Value::List(vec![Value::text("data.txt")]) + ); + let error = host + .resource_request( + "fs.read_at", + vec![Value::text("out/data.txt"), Value::int(-1), Value::int(1)], + &ctx, + ) + .unwrap_err(); + assert_eq!(error.category, ErrorCategory::Type); +} diff --git a/docs/STATUS.md b/docs/STATUS.md index 0ca5802..e237c5f 100644 --- a/docs/STATUS.md +++ b/docs/STATUS.md @@ -58,7 +58,7 @@ byte-identical). cargo fmt --all -- --check PASS cargo clippy --workspace --all-targets -- -D warnings PASS cargo test --workspace --locked PASS - 478 passed, 0 failed, 2 ignored; includes 7/7 Linux security tests + 479 passed, 0 failed, 2 ignored; includes 7/7 Linux security tests ``` The documentation and test migration is local work; re-run this block after it @@ -200,13 +200,14 @@ This is still a **local VM lane**, not a self-hosted GitHub Actions security URL `Value::Table`; inputs are never mutated; GFM AST laziness and physical T0 storage are unchanged. `std:fs/file` provides bounded `读文本`/`写文本`/`复制文件` over the existing `resource.*` ABI plus `存在`/`元数据`/`列出目录`/`创建目录`/ - `删除`/`重命名` over `resource.request` (ADR-0041); `data/json`/`data/csv` + `删除`/`重命名`/`追加文本`/`读取片段`/`遍历` over `resource.request` + (ADR-0041/0045); `data/json`/`data/csv` provide recursive JSON and quoted single-row CSV product parsers; `path` and a `regex` subset are pure `.mq.md`; `datetime` is pure UTC ISO-8601 and `clock.现在` reads `clock.now` in project mode (ADR-0042); `env.读取` reads only exact `--allow-env NAME` grants in project mode (ADR-0043); `process.运行` runs an exact `--allow-process PROGRAM` grant with 5 s timeout and 1 MiB caps - (ADR-0044, not an OS sandbox). Append/seek/watch, recursive walk, streaming + (ADR-0044, not an OS sandbox). File watch, binary offset reads, streaming JSON/CSV, a JSON depth bound, regex groups/alternation, secure random and compression remain open. - Bundled standard library (CM-A10, ADR-0028): `stdlib/` ships diff --git a/docs/adr/0045-fs-append-read-at-walk.md b/docs/adr/0045-fs-append-read-at-walk.md new file mode 100644 index 0000000..4791298 --- /dev/null +++ b/docs/adr/0045-fs-append-read-at-walk.md @@ -0,0 +1,46 @@ +# ADR-0045: `fs.append`, `fs.read_at` and `fs.walk` + +Status: **Accepted** +Date: 2026-11-21 +Relates to: ADR-0041 +Specs: `spec/evaluation.md` +Evidence: `docs/evidence/2026-11-21-fs-extended.md` + +## Context + +ADR-0041 added metadata/directory operations, but file content still required +a whole-file `resource.open` read and a whole-buffer write. That leaves append, +offset reads and recursive directory discovery unavailable to `.mq.md` without +adding Rust algorithms to the standard library. + +## Decision + +Extend the existing `fs.*` group of `resource.request`: + +```text +resource.request("fs.append", [path, text]) -> {ok:true, value:count} +resource.request("fs.read_at", [path, offset, len])-> {ok:true, value:Text} +resource.request("fs.walk", [dir]) -> {ok:true, value:List} +``` + +* `fs.append` writes UTF-8 text to the end of a project file, creating it when + missing. It requires `fs_write`, is bounded by the existing 8 MiB file limit, + and never bypasses the path policy. +* `fs.read_at` reads at most `len` bytes from `offset` and returns Text. Both + values are non-negative integers; `len` is capped at 8 MiB. Invalid UTF-8 is + a fatal type error, not silent loss. +* `fs.walk` recursively lists regular files under a directory, relative to the + project root. It requires `fs_read`, skips symlinks, has a depth limit of 64 + and a 4096-entry limit. The list is sorted by name at each level. +* All three are project-mode only, use the same path/grant checks as the other + `fs.*` operations, and record one `resource.request` effect event. +* No new builtin or host trait method is added; the operation strings extend + the existing ABI. + +## Consequences + +* `std:fs/file` exposes `追加文本`, `读取片段` and `遍历` in `.mq.md`. +* Binary offset reads, append handles and filesystem watch remain open; a + watch API needs a separate event model and ADR. +* The operations allocate at most the existing 8 MiB read limit; `walk` is + metadata-only and returns names, not contents. diff --git a/docs/architecture/CURRENT.md b/docs/architecture/CURRENT.md index 3995e95..2cb2a27 100644 --- a/docs/architecture/CURRENT.md +++ b/docs/architecture/CURRENT.md @@ -90,7 +90,7 @@ review RFC, not a new crate per provider. | stdio stderr | `resource.open("stdio","stderr",["write"])`; separate from stdout and CLI diagnostics | implemented | `resource_streams`, `stdlib_product` | | project file read | `resource.open("file", path, ["read"])`; path/grant checked; bounded | implemented, project mode | `resource_streams`, `stdlib_product` | | project file write | `resource.open("file", path, ["write"])`; buffers until `close`, never flush-on-drop | implemented, project mode | `resource_streams`, `stdlib_product` | -| `std:fs/file` | `fs.读文本`, `fs.写文本`, `fs.复制文件` over `resource.open/read/write/close` and `Memory`; bounded at 8 MiB | implemented (read/write/copy) | `stdlib_product` | +| `std:fs/file` | `读文本/写文本/复制文件/存在/元数据/列出目录/创建目录/删除/重命名/追加文本/读取片段/遍历` over `resource.*`; bounded at 8 MiB | implemented; no watch/binary offset read | `stdlib_product` | | `resource.request` | `resource.request("fs.exists|metadata|list|mkdir|remove|rename", paths)`; project mode, grant-checked, recoverable fs Result | implemented `fs.*`; no seek/append/watch | `resource_streams`, `stdlib_product` | | `std:data/json` | `json.解析(文本)` -> Result with nested Value; `json.格式化(值)` -> Text | implemented (recursive, recoverable errors) | `stdlib_product` | | `std:data/csv` | `csv.解析行(文本)` -> Result with List; `csv.格式化行(列表)` -> Text | implemented (single row, quoted) | `stdlib_product` | @@ -125,8 +125,8 @@ that a phase is complete. |---|---|---| | P0 | Stdlib release is a bundle in this repo; extraction is deferred (ADR-0039) | accepted, keep in repo | | P0 | Documentation drift between `STATUS.md`, the architecture index and the evidence | being fixed by this migration and the docs gate | -| P1 | `std:fs/file` read/write/copy and `resource.request` fs metadata/directory operations are implemented; append/seek/watch/recursive walk remain open | open | -| P1 | No file append/seek/watch/recursive directory walk | open; future Resource Operation extension | +| P1 | `std:fs/file` read/write/copy, metadata/directory, append/read_at/walk are implemented; watch and binary offset reads remain open | open | +| P1 | No file watch or binary `read_at` | open; future Resource Operation extension | | P1 | JSON/CSV product parsers are implemented; no streaming/multi-line CSV or depth-bounded JSON walker | open | | P1 | CLI split into `commands/{sandbox,run,check,inspect,init,package,tool}.rs`; host split into `host/{resource_ops,providers,effects,dispatch}.rs` plus `process.rs`; `commands.rs` keeps shared project/runtime helpers and `host.rs` keeps the `Host` trait methods and capability checks | split; shared helpers and trait methods remain by design | | P2 | HTTP parsing is Unicode-codepoint oriented; a general byte body is not the only path | open; convert before a general network release | @@ -165,5 +165,6 @@ that a phase is complete. - [ADR-0042: `clock.now` resource operation](../adr/0042-clock-resource-operation.md) — accepted project-mode Unix-millis clock. - [ADR-0043: `env.get` resource operation](../adr/0043-env-resource-operation.md) — accepted exact-name environment grants. - [ADR-0044: `process.run` resource operation](../adr/0044-process-resource-operation.md) — accepted exact-path process grant; not a sandbox. +- [ADR-0045: fs append/read_at/walk](../adr/0045-fs-append-read-at-walk.md) — accepted bounded content and directory walk. - [Compute-machine RFC-0001](../MARQDO_COMPUTE_MACHINE_RFC_0001.md) and [core/stdlib RFC-0002](../MARQDO_COMPUTE_CORE_STDLIB_MIGRATION_RFC_0002.md) — design input. - [Architecture audit and refactor RFC](Marqdo_CLI_Latest_Architecture_Audit_and_Refactor_RFC.md) — review input for this migration. diff --git a/docs/architecture/README.md b/docs/architecture/README.md index 0981bdb..358ab35 100644 --- a/docs/architecture/README.md +++ b/docs/architecture/README.md @@ -49,6 +49,7 @@ The implemented first slices of these RFCs are recorded in `CURRENT.md` and | `clock.now` resource operation | [0042](../adr/0042-clock-resource-operation.md) | Accepted (project mode, Unix millis) | | `env.get` resource operation | [0043](../adr/0043-env-resource-operation.md) | Accepted (exact-name project grant) | | `process.run` resource operation | [0044](../adr/0044-process-resource-operation.md) | Accepted (exact program grant, project only, not a sandbox) | +| `fs.append`/`fs.read_at`/`fs.walk` | [0045](../adr/0045-fs-append-read-at-walk.md) | Accepted (bounded content, directory walk) | | Table physical storage (T1/T2/T3), strict stdin/stderr/file/network resources | — | **Not decided**; do not implement by implication | ## Evidence and status diff --git a/docs/evidence/2026-11-21-fs-extended.md b/docs/evidence/2026-11-21-fs-extended.md new file mode 100644 index 0000000..170ff79 --- /dev/null +++ b/docs/evidence/2026-11-21-fs-extended.md @@ -0,0 +1,39 @@ +# Evidence: `fs.append`, `fs.read_at` and `fs.walk` + +Date: 2026-11-21 (Asia/Shanghai) +Source baseline: `7859c26213bda30b34a5379a4ab1f75430967494` +Repository: `marqdo-cli` +Decision record: [ADR-0045](../adr/0045-fs-append-read-at-walk.md) + +## Implemented + +`resource.request` now supports: + +- `fs.append(path, text)` -> `{ok:true, value:count}`; creates the file, + requires `fs_write`, 8 MiB cap. +- `fs.read_at(path, offset, length)` -> `{ok:true, value:Text}`; non-negative + integers, 8 MiB cap, invalid UTF-8 is fatal. +- `fs.walk(dir)` -> `{ok:true, value:List}`; recursive regular files, + skips symlinks, depth 64, 4096-entry cap. + +`std:fs/file` exposes `追加文本`, `读取片段`, `遍历`. + +## Tests + +`stdlib/tests/fs.mq.md` appends, reads a slice and walks the output directory; +`crates/marqdo-host/tests/resource_streams.rs` pins host behavior and the +negative-offset type error. + +```text +cargo fmt --all -- --check PASS +cargo clippy --workspace --all-targets -- -D warnings PASS +cargo test --workspace 479 passed, 0 failed, 2 ignored +cargo test -p marqdo-host --test resource_streams 24 passed +cargo test -p marqdo-cli --test stdlib_product 14 passed +python3 tools/pack-stdlib.py PASS +``` + +## Not covered + +No file watch, no binary offset read into `Memory`, no seek/resume handle, no +write-at-offset, no recursive delete and no symlink traversal. diff --git a/spec/evaluation.md b/spec/evaluation.md index 6b7fe1e..90636ae 100644 --- a/spec/evaluation.md +++ b/spec/evaluation.md @@ -205,6 +205,9 @@ resource.request("fs.list", [path]) -> {ok:true, value:List} resource.request("fs.mkdir", [path]) -> {ok:true, value:None} resource.request("fs.remove", [path]) -> {ok:true, value:None} resource.request("fs.rename", [from, to]) -> {ok:true, value:None} +resource.request("fs.append", [path, text]) -> {ok:true, value:count} +resource.request("fs.read_at", [path, offset, len]) -> {ok:true, value:Text} +resource.request("fs.walk", [dir]) -> {ok:true, value:List} resource.request("clock.now", []) -> {ok:true, value:UnixMillis} resource.request("env.get", [name]) -> {ok:true, value:Text} resource.request("process.run", [program, args])-> {ok:true, value:{status, stdout, stderr}} @@ -224,6 +227,10 @@ resource.request("process.run", [program, args])-> {ok:true, value:{status, stdo (`remove` on a non-empty directory). Unknown operations, traversal, capability denial and I/O failures stay fatal. * `remove` never recurses; `rename` never overwrites; `mkdir` is single-level. +* `append` writes UTF-8 text to the end of a file (creating it) and returns the + written count; `read_at` returns at most `len` bytes from `offset` as Text; + `walk` recursively lists regular files under a directory, skipping symlinks, + with depth 64 / 4096-entry limits (ADR-0045). * The operation never moves file bytes. Content still uses `resource.open/read/write/close`. * `clock.now` takes no arguments and returns UTC Unix milliseconds. It is diff --git a/stdlib/fs/file.mq.md b/stdlib/fs/file.mq.md index 1a68d34..134a7b3 100644 --- a/stdlib/fs/file.mq.md +++ b/stdlib/fs/file.mq.md @@ -177,3 +177,30 @@ import: 目标已存在时返回 `fs.exists`,不覆盖。 *resource.request("fs.rename", [源, 目标])* + +## 追加文本 + +`(路径, 文本)` + +把文本追加到项目文件;文件不存在时创建。仍受 8 MiB 单次读取上限和 +`fs_write` 授权约束。 + +*resource.request("fs.append", [路径, 文本])* + +## 读取片段 + +`(路径, 偏移, 长度)` + +从偏移处读取最多 `长度` 字节,按 UTF-8 解码后返回文本。偏移/长度必须 +是非负整数,长度上限 8 MiB。 + +*resource.request("fs.read_at", [路径, 偏移, 长度])* + +## 遍历 + +`(路径)` + +递归列出目录下的普通文件,返回相对项目根的路径列表。跳过符号链接, +深度上限 64,条目上限 4096。 + +*resource.request("fs.walk", [路径])* diff --git a/stdlib/stdlib.json b/stdlib/stdlib.json index f35d663..a3b71c8 100644 --- a/stdlib/stdlib.json +++ b/stdlib/stdlib.json @@ -1,5 +1,5 @@ { "name": "marqdo-stdlib", "version": "0.1.0", - "digest": "sha256:c7208520e3eef1fdc98327055092f9d52081851f652dd970d4f602e30e58e75f" + "digest": "sha256:6974496a9826f977189804bae0959e494bfc7443543ed4afffcea1ac390b0ce9" } diff --git a/stdlib/tests/fs.mq.md b/stdlib/tests/fs.mq.md index 54157f6..0873de2 100644 --- a/stdlib/tests/fs.mq.md +++ b/stdlib/tests/fs.mq.md @@ -23,8 +23,14 @@ import: **读取 = fs.读文本("out/fs-b.txt")** +**追加 = fs.追加文本("out/fs-b.txt", "世界\n")** + +**片段 = fs.读取片段("out/fs-b.txt", 0, 100)** + +**遍历 = fs.遍历("out")** + **删除 = fs.删除("out/fs-b.txt")** **删除目录 = fs.删除("out")** -*[创建.ok, 写入.value.count, 存在.value, 元数据.value.kind, 元数据.value.size, 列表.value, 是文件.value, 是目录.value, 重命名.ok, 读取.value, 删除.ok, 删除目录.ok]* +*[创建.ok, 写入.value.count, 存在.value, 元数据.value.kind, 元数据.value.size, 列表.value, 是文件.value, 是目录.value, 重命名.ok, 读取.value, 追加.value, 片段.value, 遍历.value, 删除.ok, 删除目录.ok]*