- CHANGELOG.md:v2.8.0 条目(中英双语); - README.md:版本行 2.7.1→2.8.0 + 愿景第 6 条(知识可证明); - doc/releases/v2.8.0.md:双语发版说明(亮点/用法/已知限制); - skills/marqdo-dev/index.mq.md:新增 prove 任务(路径/目录模式/ require_lean/json;参数用 + 行声明升参,check 与 narrative-ratio 通过); - 设计文档 §12.5 标记已合入;发版链接统一指向 doc/releases/v2.8.0.md。
372 lines
17 KiB
Markdown
Executable File
372 lines
17 KiB
Markdown
Executable File
---
|
|
markup: occlusion
|
|
title: Engineering boundaries for executable handbooks
|
|
import:
|
|
plugin: lib/plugin.mq.md
|
|
sys: lib/sys.mq.md
|
|
paths: lib/path.mq.md
|
|
table: lib/table.mq.md
|
|
result: lib/result.mq.md
|
|
---
|
|
|
|
This extension supplies the small OS and service boundaries used by executable
|
|
engineering handbooks. File reads/writes, JSON/TOML, data decisions, retries and
|
|
release ordering remain Marqdo code. The native plugin provides bounded argv
|
|
process execution, private authenticated GitHub HTTPS, ZIP inspection and R2
|
|
Signature V4 uploads. No Python interpreter or generated shell program is used.
|
|
|
|
Read the task contract before calling it. Process children and native plugins
|
|
have the calling OS user's authority; a plugin grant is broader than a native
|
|
filesystem grant. The root parameter selects a working/artifact directory, not
|
|
an OS sandbox. Never treat reading this file as authorization to push refs,
|
|
change a release, upload assets or run arbitrary commands.
|
|
|
|
Build this repository's marqdo_plugin_engineering crate before first use; the
|
|
development handbook's prepare_engineering task performs that bootstrap through
|
|
marqdo call. MARQDO_ENGINEERING_PLUGIN may select a locally built library. Installed
|
|
packs use the same plugin resolver as other official extensions. This boundary
|
|
is native-only; browser WASM cannot start processes or load this library.
|
|
|
|
The public operation definitions and private request helper below share one
|
|
implementation. For the complete release workflow, read
|
|
[the executable release handbook](../../skills/marqdo-release/index.mq.md).
|
|
Normal filesystem work uses [the native file tools](../../skills/marqdo-dev/files.mq.md);
|
|
this extension is not an alternate file-write API.
|
|
|
|
## _load
|
|
|
|
| 返回 | 类型 | 说明 |
|
|
|---|---|---|
|
|
| result | any | Load the installed or locally built engineering plugin |
|
|
|
|
Resolve the library through the existing extension resolver so an installed
|
|
pack and a development build share the same public calls. A missing library
|
|
produces the normal plugin diagnostic; build or install it rather than hiding
|
|
the failure behind a fixed success result. Repeated loads use the host loader's
|
|
existing ownership rules. This private boundary requires plugin effects and
|
|
never guesses a Python replacement or invents an external interpreter.
|
|
|
|
We **path = [Resolve the engineering native library](plugin.native_path(name="engineering"))**.
|
|
After locating it we return *[Load the bounded engineering operations](plugin.load(path=`path`))*.
|
|
|
|
## request
|
|
|
|
| 参数 | 类型 | 默认 | 说明 |
|
|
|---|---|---|---|
|
|
| operation | text | required | command, git_inspect, github, archive, analyze, gzip_text or r2_put |
|
|
| payload | map | required | Operation-specific ordinary data; never credential values |
|
|
| root | text | "." | Existing working/artifact root for this operation |
|
|
|
|
| 返回 | 类型 | 说明 |
|
|
|---|---|---|
|
|
| result | map | Result.ok/value/error from the selected boundary |
|
|
|
|
Use `operation`, `payload` and `root`="." only at a documented native boundary.
|
|
Inputs travel as structured plugin values, not strings containing a generated
|
|
program. Failed process setup, HTTP, archive validation or signing remains a
|
|
failed Result. A successful command request still requires checking value.code
|
|
and value.timed_out. No private credential becomes a tool argument or result;
|
|
authentication is resolved inside the plugin from existing stores.
|
|
|
|
We **loaded = [Load this package's native boundary](_load())** and
|
|
**base = [Read the granted runtime working root](sys.cwd())** and **resolved_root = root**.
|
|
1. not [The requested root is already absolute](paths.is_absolute(path=`root`))
|
|
We **resolved_root = base + "/" + root** so process and native filesystem locations agree.
|
|
|
|
`request_data` =
|
|
|
|
| operation | payload | root |
|
|
|---|---|---|
|
|
| `operation` | `payload` | `resolved_root` |
|
|
|
|
Return *[Perform the explicit native boundary operation](engineering_request(request=`request_data`))*.
|
|
|
|
## run
|
|
|
|
| 参数 | 类型 | 默认 | 说明 |
|
|
|---|---|---|---|
|
|
| argv | list | required | Executable followed by individual text arguments |
|
|
| cwd | text | "." | Existing directory inside root |
|
|
| timeout_ms | number | 120000 | Positive limit through 3600000 milliseconds |
|
|
| max_output | number | 262144 | Per-stream capture limit through 16777216 bytes |
|
|
| stdin | any | None | Optional text sent to child stdin, then closed |
|
|
| env | any | None | Optional child-only text environment values |
|
|
| root | text | "." | Root used to resolve cwd and local Git identity |
|
|
|
|
| 返回 | 类型 | 说明 |
|
|
|---|---|---|
|
|
| result | map | Result containing code/stdout/stderr/timed_out/truncated |
|
|
|
|
Use `argv`, `cwd`=".", `timeout_ms`=120000, `max_output`=262144, `stdin`=None,
|
|
`env`=None and `root`="." to invoke an existing OS tool. Arguments are passed
|
|
individually even when they contain quotes, spaces or shell metacharacters.
|
|
Inline shell programs, forced Git updates and hook bypass are rejected; a
|
|
checked-in packaging script remains a normal explicit external-tool invocation.
|
|
|
|
The return distinguishes transport completion from child success. Inspect code
|
|
and timed_out before consuming stdout. Output is drained concurrently and kept
|
|
within the requested cap so noisy children cannot deadlock their own pipes.
|
|
On Unix, timeout kills the child process group; Windows attempts taskkill's tree
|
|
termination. Output retained by surviving descendants cannot cause unbounded
|
|
waiting. A process environment is child-local and does not mutate the parent.
|
|
|
|
`payload` =
|
|
|
|
| argv | cwd | timeout_ms | max_output | stdin | env |
|
|
|---|---|---|---|---|---|
|
|
| `argv` | `cwd` | `timeout_ms` | `max_output` | `stdin` | `env` |
|
|
|
|
Return *[Execute the explicit argument vector with bounded capture](request(operation="command", payload=`payload`, root=`root`))*.
|
|
|
|
## github
|
|
|
|
| 参数 | 类型 | 默认 | 说明 |
|
|
|---|---|---|---|
|
|
| path | text | required | API path under /repos/cflmy/marqdo/ |
|
|
| method | text | "GET" | GET, PATCH or POST; mutations need the user's task instruction |
|
|
| data | any | None | JSON body; no authentication data |
|
|
| missing | bool | False | Treat GET 404 as a successful None |
|
|
| root | text | "." | Checkout used by credential helpers |
|
|
|
|
| 返回 | 类型 | 说明 |
|
|
|---|---|---|
|
|
| result | map | Result containing service JSON, None or a redacted transport error |
|
|
|
|
Use `path`, `method`="GET", `data`=None, `missing`=False and `root`=".".
|
|
The plugin resolves GH_TOKEN/GITHUB_TOKEN, Git's configured credential helper or
|
|
the checkout owner's existing gh store privately. It tries the configured
|
|
GitHub proxy before direct HTTPS. An uncertain POST is not replayed; a caller
|
|
must observe whether publication occurred before deciding to retry a mutation.
|
|
|
|
Only this repository's API paths are accepted. HTTP errors report their status
|
|
without reflecting credentials, signed URLs or arbitrary response bodies.
|
|
Missing evidence stays missing; a network failure is not a synthetic empty
|
|
release. Test endpoint overrides are explicit environment configuration and
|
|
belong only in isolated fixture runs.
|
|
|
|
`payload` =
|
|
|
|
| path | method | data | missing |
|
|
|---|---|---|---|
|
|
| `path` | `method` | `data` | `missing` |
|
|
|
|
Return *[Request private-authenticated repository service JSON](request(operation="github", payload=`payload`, root=`root`))*.
|
|
|
|
## inspect_zip
|
|
|
|
| 参数 | 类型 | 默认 | 说明 |
|
|
|---|---|---|---|
|
|
| path | text | required | Existing ZIP or VSIX inside root |
|
|
| root | text | "." | Artifact root; symlink escapes are refused |
|
|
|
|
| 返回 | 类型 | 说明 |
|
|
|---|---|---|
|
|
| result | map | Result with entries and selected UTF-8 package metadata |
|
|
|
|
Use `path` and `root`="." to inspect a binary format without extraction.
|
|
The plugin caps entry count and total expanded size, rejects escaping paths and
|
|
symlinks, and reads every entry to validate its content/CRC. It retains only
|
|
bounded VERSION, Cargo and VSIX metadata text for Marqdo's role-specific checks.
|
|
Hashing the archive itself remains lib/fs.file_hash, not an alternate Python IO
|
|
path. ZIP metadata cannot prove plugin ABI compatibility or execute a program.
|
|
|
|
We **payload = [Name the one archive path field](table.put(in=None, at="path", value=`path`))**.
|
|
|
|
Return *[Inspect the archive format without writing extracted files](request(operation="archive", payload=`payload`, root=`root`))*.
|
|
|
|
## put_file
|
|
|
|
| 参数 | 类型 | 默认 | 说明 |
|
|
|---|---|---|---|
|
|
| path | text | required | Verified upload file inside root |
|
|
| key | text | required | Explicit R2 key such as vX.Y.Z/filename.zip |
|
|
| sha256 | text | required | Previously verified SHA256; changed bytes are rejected |
|
|
| root | text | "." | Root containing the local upload file |
|
|
|
|
| 返回 | 类型 | 说明 |
|
|
|---|---|---|
|
|
| result | map | Result with written key, SHA256 and byte count |
|
|
|
|
Use `path`, `key`, `sha256` and `root`="." for an authorized publication.
|
|
The plugin transfers this bounded file across the authenticated service boundary
|
|
and rechecks its digest before signing; Marqdo decides which files and keys are
|
|
required. Credentials stay in existing R2 environment settings or ~/.marqdo/r2.env.
|
|
A configured credential home can select the maintainer's store when running under
|
|
another OS identity. Key material is never a parameter, result or command argument.
|
|
|
|
This is an external write. Successful PUT is evidence for that key only; public
|
|
CDN parity is checked separately. The release handbook uploads every pack before
|
|
writing VERSION pointers and never sweeps unrelated files from dist. A timeout
|
|
remains uncertain publication, so inspect the public object before retrying.
|
|
|
|
`payload` =
|
|
|
|
| path | key | sha256 |
|
|
|---|---|---|
|
|
| `path` | `key` | `sha256` |
|
|
|
|
Return *[Upload exactly the verified artifact with private R2 signing](request(operation="r2_put", payload=`payload`, root=`root`))*.
|
|
|
|
## put_text
|
|
|
|
| 参数 | 类型 | 默认 | 说明 |
|
|
|---|---|---|---|
|
|
| key | text | required | Explicit VERSION key selected by the release workflow |
|
|
| text | text | required | Small UTF-8 pointer body with its intended trailing newline |
|
|
| root | text | "." | Checkout used to locate existing credential stores |
|
|
|
|
| 返回 | 类型 | 说明 |
|
|
|---|---|---|
|
|
| result | map | Result with written key, SHA256 and byte count |
|
|
|
|
Use `key`, `text` and `root`="." only after all required publication bytes are
|
|
verified. This operation signs a small UTF-8 service body; it does not write a
|
|
local file or infer which version should become latest. The calling Marqdo
|
|
workflow owns that decision and its ordering. Keys remain explicit so a replay
|
|
cannot silently publish a different version from environment state.
|
|
As with put_file, service completion does not substitute for reading the public
|
|
pointer and checking the associated download hashes.
|
|
|
|
`payload` =
|
|
|
|
| key | text |
|
|
|---|---|
|
|
| `key` | `text` |
|
|
|
|
Return *[Write the explicitly selected publication pointer](request(operation="r2_put", payload=`payload`, root=`root`))*.
|
|
## analyze
|
|
|
|
| 参数 | 类型 | 默认 | 说明 |
|
|
|---|---|---|---|
|
|
| source | text | required | Exact source text already read through lib/fs |
|
|
| include_body | bool | False | Include compiler AST debug evidence for migration review |
|
|
|
|
| 返回 | 类型 | 说明 |
|
|
|---|---|---|
|
|
| result | map | Result with compiler functions, contracts, diagnostics and narrative ratios |
|
|
|
|
Use `source` and `include_body`=False to inspect an authored document
|
|
without executing it. File access belongs to the caller's native filesystem
|
|
step; this operation receives text and uses the actual Marqdo parser and checker.
|
|
It does not invent a regular-expression grammar, load imports, run main, open
|
|
network resources or infer permission from prose. Full dependency checks still
|
|
use marqdo check on the real file.
|
|
|
|
The returned parameter names, defaults, heading spans and contracts support
|
|
editing without guessing the syntax. Narrative ratios come from the same
|
|
implementation used by the repository gate. AST debug evidence is optional
|
|
because it is large and intended for mechanical migration comparisons, while
|
|
the normal result remains a compact source description.
|
|
|
|
`payload` =
|
|
|
|
| source | include_body |
|
|
|---|---|
|
|
| `source` | `include_body` |
|
|
|
|
Return *[Inspect this text with the real compiler](request(operation="analyze", payload=`payload`))*.
|
|
|
|
|
|
## gzip_text
|
|
|
|
| 参数 | 类型 | 默认 | 说明 |
|
|
|---|---|---|---|
|
|
| data | map | required | Portable bytes returned by net.get(response="bytes") |
|
|
| max_bytes | number | 16777216 | Positive expanded UTF-8 limit, at most 64 MiB |
|
|
|
|
| 返回 | 类型 | 说明 |
|
|
|---|---|---|
|
|
| result | map | Result containing decoded UTF-8 text or bounded format failure |
|
|
|
|
Use `data` and `max_bytes`=16777216 at a compressed data boundary.
|
|
Native net.get owns the network read and returns portable bytes; this operation
|
|
only interprets their gzip format. It accepts concatenated gzip members, validates
|
|
their checksums, caps compressed input and expanded output, and rejects non-UTF-8
|
|
text. No temporary file, shell pipeline or Python process is involved.
|
|
|
|
This is useful for a published apt Packages.gz index. A successful HTTP response
|
|
alone cannot establish its package version; decode and inspect its real stanzas.
|
|
Malformed data or an expansion beyond the cap remains an error. Binary payloads
|
|
are outside this text contract. Calling requires plugin, while the caller's
|
|
earlier download independently requires network.read.
|
|
|
|
`payload` =
|
|
|
|
| data | max_bytes |
|
|
|---|---|
|
|
| `data` | `max_bytes` |
|
|
|
|
Return *[Decode the bounded compressed text format](request(operation="gzip_text", payload=`payload`))*.
|
|
|
|
|
|
## check_exit
|
|
|
|
| 参数 | 类型 | 默认 | 说明 |
|
|
|---|---|---|---|
|
|
| outcome | map | required | Actual Result returned by engineering.run or its command boundary |
|
|
|
|
| 返回 | 类型 | 说明 |
|
|
|---|---|---|
|
|
| result | map | Observed process Result; failure retains its complete bounded execution evidence |
|
|
|
|
Use `outcome` from an actual process call. Starting a process successfully is
|
|
different from that process succeeding: command transport can return ok=true
|
|
with a nonzero child code. This pure adapter requires code zero and no timeout.
|
|
It never starts or retries a process, changes a command or discards failed output.
|
|
|
|
A setup/transport failure is retained unchanged. A nonzero exit or timeout becomes
|
|
a failed Result with the original execution record in value, including stdout,
|
|
stderr and truncation flags. This makes --require-ok useful for a complete
|
|
callable workflow without treating CLI transport success as a passed build.
|
|
Bounded output can be truncated even when the command succeeds; inspect that
|
|
flag before describing it as a full log.
|
|
|
|
This function only classifies supplied observations. It cannot prove that an
|
|
arbitrary caller-provided map came from a real command. Development tasks call
|
|
run and then this adapter in the same source flow, retaining their actual argv
|
|
and result. Release ordering and retry policy remain the caller's responsibility.
|
|
|
|
1. not access(`outcome`, "ok")
|
|
Return *outcome* with its original native setup failure.
|
|
We **execution = [Read the actual bounded process observation](access(outcome, "value"))**.
|
|
1. access(`execution`, "code") != 0 or access(`execution`, "timed_out")
|
|
We **failed = [Distinguish child failure from successful transport](result.error(code="engineering.process_failed", message="nonzero exit or timeout; inspect the actual execution in value", operation="check_exit"))**.
|
|
Return *[Keep all observed process evidence on failure](table.put(in=`failed`, at="value", value=`execution`))*.
|
|
Return *outcome* after the observed child exits successfully.
|
|
|
|
|
|
## checked
|
|
|
|
| 参数 | 类型 | 默认 | 说明 |
|
|
|---|---|---|---|
|
|
| argv | list | required | Existing executable and individual text arguments |
|
|
| cwd | text | "." | Existing working directory within root |
|
|
| timeout_ms | number | 120000 | Positive child duration limit up to one hour |
|
|
| max_output | number | 262144 | Bounded bytes retained per stdout/stderr stream |
|
|
| stdin | any | None | Optional text sent to child standard input |
|
|
| env | any | None | Optional child-only text environment record |
|
|
| root | text | "." | Working root matching the intended checkout |
|
|
|
|
| 返回 | 类型 | 说明 |
|
|
|---|---|---|
|
|
| result | map | Result requiring a zero child exit; actual execution evidence is retained |
|
|
|
|
Use `argv`, `cwd`=".", `timeout_ms`=120000, `max_output`=262144,
|
|
`stdin`=None, `env`=None and `root`="." to execute one existing tool and require
|
|
its success in the same callable workflow. It composes run and check_exit rather
|
|
than regenerating process management, credential handling or a shell program.
|
|
The parameter vector, directory and resource limits keep their existing meaning.
|
|
|
|
A setup failure, nonzero exit or timeout returns ok=false. Its actual stdout,
|
|
stderr and truncation state remain available for diagnosis. A successful result
|
|
means the observed child exited successfully; interpreting its business output
|
|
still belongs to the caller. Use --require-ok when this single call controls a
|
|
dependent external automation. No retry or publication is implied.
|
|
|
|
This operation requires plugin. Its child retains normal OS authority, and the
|
|
native boundary keeps its existing argv guards and private credential rules.
|
|
For example, a unit-test task can pass cargo, test, --lib and --offline as four
|
|
separate text elements without needing a new generated command script.
|
|
|
|
After the bounded execution we return *[Require the actual child outcome and preserve all evidence](check_exit(outcome=run(argv=`argv`, cwd=`cwd`, timeout_ms=`timeout_ms`, max_output=`max_output`, stdin=`stdin`, env=`env`, root=`root`)))*.
|