diff --git a/.cursor/rules/web-artifact-no-degrade.mdc b/.cursor/rules/web-artifact-no-degrade.mdc new file mode 100644 index 0000000..c3ee54c --- /dev/null +++ b/.cursor/rules/web-artifact-no-degrade.mdc @@ -0,0 +1,26 @@ +--- +description: Marqdo Web Artifact — no degradation; Document/Endpoint/Resource only +globs: ext/web/**,ext/net/**,ext/data/**,ext/security/**,examples/**/*,tests/ext/web*,doc/design/ext-web*,doc/adr/0007* +alwaysApply: true +--- + +# Web Artifact — 不允许降级 + +Canonical: `doc/adr/0007-web-document-endpoint.md` · `doc/design/ext-web-artifact.md` · `doc/next/007.md` (superseded). + +## Hard bans + +1. **Do not** restore or reintroduce author-facing `compose_main` / `compose_intro` / `compose_*` fragmented table DSLs, god `# page` mutation piles, or `app.configure(...)` junk-drawer APIs. +2. **Do not** use `json.set` / `json.append` bag glue for pages, routes, or middleware. Tables = data. View schema is only `|type|slot|value|attrs|style|` (ZH aliases allowed). +3. **Do not** call `ensure_plugin` or `host_*` from author programs or from `ext/**` (plugin load is facade/capability only). +4. **Do not** register implicit user routes. Declared routes come from Artifact metadata or `web.route`. System routes (`/_part`, `/_form`, …) must appear in `web.inspect`. +5. **Do not** invent DSL, nested frontmatter under `##`, or new table dialects when the design is silent — **stop and ask**. +6. **Do not** mix EN/ZH API names in one `.mq.md`. +7. **Do not** silently delete capabilities. Removals require design text + tests updated in the same change. +8. **Do not** put DB/auth/cache/storage/websocket author APIs back into `ext/web/web.mq.md` — they live in `ext/data`, `ext/security`, `ext/net`. + +## Required direction + +- Document (`type: web` / `类型: 网页`), Endpoint (`type: endpoint` / `类型: 端点`), Resource modules. +- Facade only: `web.page` · `web.route` · `web.serve` · `web.render` · `web.inspect` (ZH mirrors). +- Code is documentation: the `.mq.md` is the page/API docs and the implementation. diff --git a/.cursor/skills/marqdo-dev/SKILL.md b/.cursor/skills/marqdo-dev/SKILL.md index 28ac1a0..2453e10 100644 --- a/.cursor/skills/marqdo-dev/SKILL.md +++ b/.cursor/skills/marqdo-dev/SKILL.md @@ -92,7 +92,7 @@ Better still — call a named helper: 7. **Do not use `##` inside `# main` for document sectioning** — those become nested functions. Use paragraphs / `---` breaks instead. 8. **Index:** prefer `[键](集合)` / `` [`名`](集合) `` over footnote `` m[^k] ``. -Browser client programs: prefer `import browser:lib/browser.mq.md` (no native plugin). Server sites: `ext/web` + GFM page/style tables. +Browser client programs: prefer `import browser:lib/browser.mq.md` (no native plugin). Server sites: Artifact Metadata (`type: web|endpoint`) + `ext/web` facade + `ext/data` / `ext/security` / `ext/net` — see [ext-web-artifact.md](../../doc/design/ext-web-artifact.md). **Never** restore `compose_*` / `app.configure`. ## Developing libraries (`lib/*`, `ext/*`) @@ -121,7 +121,9 @@ Canonical thin-template + waves: [lib-code-as-docs.md](../../doc/design/lib-code | Need | Place | |------|--------| | Browser effect maps (WASM client) | `lib/browser.mq.md` | -| Site HTML / HTTP / DB | `ext/web` classes + compose from tables | +| Site HTML / HTTP | `ext/web` Document/Endpoint + View tables | +| DB / cache / storage | `ext/data` | +| Auth / OIDC / RBAC | `ext/security` | | List/map primitives | `lib/table.mq.md` | | Parse JSON text | `lib/json.mq.md` only | diff --git a/.cursor/skills/marqdo/SKILL.md b/.cursor/skills/marqdo/SKILL.md index 2d1558e..0cdf965 100644 --- a/.cursor/skills/marqdo/SKILL.md +++ b/.cursor/skills/marqdo/SKILL.md @@ -224,44 +224,53 @@ APIs: `# agent` / `# 智能体` → `## run` / `## route` / `## step` / `## plan Examples: [agent-pong](../../examples/agent-pong/) · [agent-okf-flywheel](../../examples/agent-okf-flywheel/). Harness: `scripts/agent-harness.sh`. Design: [ext-agent.md](../../doc/design/ext-agent.md) · Wave B: [agent-framework-2026-09.md](../../doc/research/agent-framework-2026-09.md) · v2: [doc/next/003.md](../../doc/next/003.md) · P4: [doc/next/004.md](../../doc/next/004.md). Dev LLM: copy [.env.example](../../.env.example) → `.env` (gitignored). -## Official extension: `ext/web` (dynamic sites) +## Official extension: `ext/web` (Document / Endpoint / Resource) -Install: `marqdo ext add web` (ZH id: `网页`). Build native plugin first: `cargo build --release -p marqdo_plugin_web`. +Install: `marqdo ext add web` (ZH id: `网页`). Build native plugin: `scripts/build-web-plugin.sh` / `marqdo ext add web`. -Import **one language file** — never mix EN/ZH API names in the same `.mq.md`: +**Constitution (ADR 0007 — do not degrade):** -- EN: `import web:ext/web/web.mq.md` +1. **Document / Endpoint / Resource** — `.mq.md` with `type: web|endpoint` (ZH `类型: 网页|端点`) is the site surface; not a Flask-style class pile. +2. **Code is documentation** — the file is docs + route + handler. +3. **Table = data** — View schema only `|type|slot|value|attrs|style|`. No `compose_*` dialects, no `json.set` glue. +4. **Facade only** — `web.page` · `web.route` · `web.serve` · `web.render` · `web.inspect`. DB → `ext/data`; auth → `ext/security`; ws/http → `ext/net`. +5. **No author `ensure_plugin` / `host_*`**; import web = capability (plugin auto-load). +6. **Declared vs system routes**; `web.inspect` lists both. No silent user routes. + +Import **one language** per file: + +- EN: `import web:ext/web/web.mq.md` (+ `import data:ext/data/db.mq.md` as needed) - ZH: `导入 网页:ext/web/网页.mq.md` -**Hard rules (web):** +```markdown +--- +type: web +route: / +title: Hello +import web:ext/web/web.mq.md +--- -- Authors use **GFM tables + `#` classes** — no `json.parse` / `json.set` glue, no hand-built part JSON. -- Table cells stay **literal strings**; path text like `` `posts`.`title` `` is resolved by web classes. -- **Quote path/MIME cells** that contain `/` (T5 cell expressions treat bare `/` as division): `"/static/logo.svg"`, `"image/png"`. -- **`ext/**` never calls `host_*`** — hot path is native `plugins/web` ABI (default **Go `libweb`**, build via `scripts/build-web-plugin.sh`). -- HTTPS: terminate at reverse proxy; set `cookie_secure=True` on auth (no in-process TLS). +# Hello -**Typical layout:** - -```text -index.mq.md # entry + home page table + listen -pages/ # sub-pages -components/ # reusable |属性|值|样式| tables -styles/ # CSS modules -public/ # static + favicon.ico|png|svg -db/ # schema + open/init -data/ # sqlite runtime (gitignore) +Executable document as a page. ``` -**Core objects (EN / ZH):** `# page`/`页面`, `# style`/`样式`, `# db`/`数据库`, `# form`/`表单`, `# app`/`应用`, `# auth`/`鉴权`, `# cache`/`缓存`, `# storage`/`存储`. +```markdown +--- +type: endpoint +method: POST +path: /api/ping +response: json +--- -**Typical flow:** `db.init` → `page.compose_*` → `app` + `static` / `listen`. Client: `marqdo wasm build -o static` + `web.client_embed source="/static/client.mq.md"` — **no author JS**; bridge may implement rich host effects ([browser-wasm-e.md](../../doc/roadmap/browser-wasm-e.md) · [browser-app](../../examples/browser-app/)). +*{"ok": true}* +``` -**Shipped surface (W0–W7 + P3 + W8 + route D mount):** middleware + JSON API (`app.configure`); transactions, pagination, FTS search (`db.migrate`, `db.fts`, `db.search`); security (argon2, CSRF, SQLite sessions, login rate limit); SEO / RSS / Markdown (`page.meta`, `route_rss`, `lib/net.markdown_parse`); upload / download / gallery; sitemap / robots / error pages / redirects; RBAC (`app.gate`, user `role`); audit timestamps + FK in `db.init`; ETag on downloads; **W8** site icons (`app.icons` → `/favicon.ico`), head resource tables (`page.head`), image assembly (`make_images` / `page.images`); **表驱动引言** `page.compose_intro` / `页面.引言装配`(属性/值/样式表 → `.main-intro`,避免手写 HTML 字符串);**D** `client_embed` auto-mount + DOM effect helpers (`text_patch` / `dom_patch`). +Site entry may `# main` → `web.serve root="."`. Client WASM: `ext/web/client.mq.md` / `lib/browser` — no author JS. -Design: [ext-web.md](../../doc/design/ext-web.md) · assets: [web-assets-and-images.md](../../doc/design/web-assets-and-images.md) · capability matrix: [web-net-capabilities.md](../../doc/design/web-net-capabilities.md) · example: [examples/marqdo-blog/](../../examples/marqdo-blog/) · client: [examples/web-client-site/](../../examples/web-client-site/). +Design: [ext-web-artifact.md](../../doc/design/ext-web-artifact.md) · ADR [0007](../../doc/adr/0007-web-document-endpoint.md) · rule: `.cursor/rules/web-artifact-no-degrade.mdc` · example: [examples/marqdo-blog/](../../examples/marqdo-blog/). -Web patterns: [examples.md](examples.md) §13 · API index: [reference.md](reference.md). +Web patterns: [examples.md](examples.md) · API index: [reference.md](reference.md). ## Official extension: `ext/quantum` (circuits + Q7/Q8) diff --git a/CHANGELOG.md b/CHANGELOG.md index 7085587..5ef8157 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,10 +3,18 @@ ## Unreleased ### Added +- **Web Artifact 模型(ADR 0007)**:`type: web|endpoint`(ZH `类型: 网页|端点`);核心 `src/artifact/`;`sys.artifact_kind`;无 `# main` 时 Result 摘要。 +- **`ext/web` facade**:`page` · `route` · `serve` · `render` · `inspect` · `use`;子模块 page/route/dom/client/component。 +- **`ext/data` · `ext/security` · `ext/net`**:从 monolithic web 拆出 Resource。 +- **统一 View** `|type|slot|value|attrs|style|` + ABI `web_render_nodes` / `web_serve_root` / `web_inspect` / `web_app_use`。 +- **规则**:`.cursor/rules/web-artifact-no-degrade.mdc`;设计 `doc/design/ext-web-artifact.md`。 ### Fixed ### Changed +- **破坏性**:删除作者面 `compose_*` / `app.configure` / 作者 `ensure_plugin`。旧 web gold 标 `#[ignore]`;新金样 `web-artifact-*`。 +- **核心表面 Δ**:**无增删**(复用 Metadata `type`)。 +- 修订 `ext-web.md` C1;`doc/next/007.md` superseded。 ## v1.1.1 — 2026-09-24 diff --git a/doc/adr/0007-web-document-endpoint.md b/doc/adr/0007-web-document-endpoint.md new file mode 100644 index 0000000..478cdd8 --- /dev/null +++ b/doc/adr/0007-web-document-endpoint.md @@ -0,0 +1,54 @@ +# ADR 0007:Web Document / Endpoint / Resource(破坏性 · 代码即文档) + +| | | +|---|---| +| Status | **Accepted** | +| Date | 2026-09-28 | +| Related | [ext-web-artifact.md](../design/ext-web-artifact.md) · [ext-web.md](../design/ext-web.md) · [binding.md](../design/binding.md) · ADR [0006](0006-artifact-metadata-binding.md) · [layers.md](../design/layers.md) · [doc/next/007.md](../next/007.md) | + +## Context + +- [`ext/web/web.mq.md`](../../ext/web/web.mq.md) 已膨胀为小型 Web Framework(Page God Object、`configure` 垃圾抽屉、碎片 Table DSL、隐式路由),与 Marqdo「代码即文档」冲突。 +- [doc/next/007.md](../next/007.md) 提出 Document / Endpoint / Resource 三原语与拆分 `ext/web` · `ext/net` · `ext/data` · `ext/security`。 +- 现行 [ext-web.md](../design/ext-web.md) **C1** 禁止为 web 改核心;Document/Endpoint 装载识别需要 Language/Runtime 参与(复用 Artifact Metadata `type`,**不**新增 CORE_CONSTRUCTS 标记)。 +- Binding(ADR 0006)已提供文件级 Metadata;`type: prompt` 先例在扩展侧消费 metadata。 + +## Decision + +1. **采纳** Document / Endpoint / Resource 为 Web 模型一等公民;正式规范见 [ext-web-artifact.md](../design/ext-web-artifact.md)。 +2. **修订 ext-web C1**:允许核心在装载期识别 `type: web|endpoint`(及中文 `类型: 网页|端点`)并暴露 artifact 分类;**装配 / HTTP / DB 语义仍在 ext + plugin**。单元格求值、import 句法、CORE_CONSTRUCTS 计数不变。 +3. **文件级 Artifact only**:不在 `##` 函数体嵌套 `---` frontmatter(与 Binding Phase 1 / 解析器一致)。 +4. **破坏性重写作者面**:删除 `compose_*` 碎片 DSL、god `# page` 变异堆、`app.configure` 多参数抽屉、作者 `ensure_plugin`;examples 与 `tests/ext/web*` 同步重写。 +5. **目录定稿**(007 §三十五 + §四十): + - `ext/web/` — page · route · component · dom · client · facade + - `ext/net/` — http · websocket · url + - `ext/data/` — db · cache · storage + - `ext/security/` — auth · oidc · rbac +6. **统一 View 表**:`| type | slot | value | attrs | style |`;Table = Data,禁止每函数私有方言。 +7. **declared vs system routes**:用户 route 须声明;`/_part` · `/_form` 等为 system,经 `web.inspect` 可见。 +8. **import = capability**:`import web:…` 由 facade 自动加载 native plugin;作者程序不写 `ensure_plugin` / `host_*`。 +9. **Metadata v1 锁定(原 007 未决项)**: + - 发现:`web.serve root=` 扫描 `root/**/*.mq.md`,仅注册 `type`/`类型` ∈ {web,网页,endpoint,端点} 的文件;无 type 的库文件忽略。 + - Data:仅 flat 键 `data_source` · `data_order` · `data_where`(text;where 为 `col=val` 逗号分隔)。嵌套 YAML `data:` 推迟。 + - Result:`{ok: bool, value: any, error: text|None}`。 + - Realtime 模块名:`ext/net/websocket.mq.md`(ZH:`实时.mq.md`)。 + - ZH metadata:`类型`←type,`路由`←route,`方法`←method,`路径`←path,`请求`←request,`响应`←response,`鉴权`←auth,`数据源`←data_source,`排序`←data_order,`条件`←data_where。 + +## Consequences + +### Positive + +- `.mq.md` 同时是文档、路由、实现与鉴权声明。 +- 与 LLM/Agent Artifact Metadata 统一心智。 +- 职责边界清晰,可独立演化 data/security/net。 + +### Negative / Risks + +- 破坏性:全部现有 web 作者程序与 smokes 必须改写。 +- Endpoint 热路径仍经 plugin → `CallLibPath` / 文件装载回调;须保持 ABI 稳定演进。 +- flat data 键表达力弱于嵌套 YAML;后续另 ADR。 + +### Neutral + +- 不新增 Markdown 核心标记;`${…}` 仍仅 Metadata。 +- Go `plugins/web` 可分波删除死 compose ABI;作者面先断。 diff --git a/doc/design/ext-web-artifact.md b/doc/design/ext-web-artifact.md new file mode 100644 index 0000000..565a666 --- /dev/null +++ b/doc/design/ext-web-artifact.md @@ -0,0 +1,195 @@ +# 官方扩展:Web Artifact(Document / Endpoint / Resource) + +| | | +|---|---| +| 状态 | **Accepted · 破坏性(取代 page/app God Object 作者面)** | +| 日期 | 2026-09-28 | +| ADR | [0007-web-document-endpoint.md](../adr/0007-web-document-endpoint.md) | +| 讨论稿 | [doc/next/007.md](../next/007.md)(superseded) | +| 安装 | `marqdo ext add web`(`web` / `网页`) | +| 相关 | [binding.md](binding.md) · [ext-web.md](ext-web.md) · [stdlib-i18n.md](stdlib-i18n.md) · [layers.md](layers.md) | + +--- + +## 0. 一句话 + +> **Document describes the page. Table describes the data. Endpoint describes the interaction. Metadata describes the runtime. Marqdo executes all of them.** + +--- + +## 1. 三原语 + +| Artifact | Metadata `type` / `类型` | 含义 | +|----------|--------------------------|------| +| **Document** | `web` / `网页` | Markdown 正文 + View → HTML;`route`/`路由` 注册 declared HTTP | +| **Endpoint** | `endpoint` / `端点` | 可执行正文为 handler;`path`+`method` 注册 API | +| **Resource** | (绑定/导入) | `ext/data` · `ext/security` · 未来 LLM 等,经 metadata / import 声明 | + +核心装载识别 `type`/`类型`(见 `src/artifact/`);渲染与 listen 在 `ext/web` + `plugins/web`。 + +--- + +## 2. 目录 + +```text +ext/web/ + web.mq.md · 网页.mq.md # facade: page route serve render inspect + page.mq.md · route.mq.md · component.mq.md · dom.mq.md · client.mq.md +ext/net/ http.mq.md · websocket.mq.md · url.mq.md +ext/data/ db.mq.md · cache.mq.md · storage.mq.md +ext/security/ auth.mq.md · oidc.mq.md · rbac.mq.md +``` + +作者入口通常: + +```text +site/ + index.mq.md # type: web · route: / · 或 # main → web.serve + pages/*.mq.md # type: web + api/*.mq.md # type: endpoint + data/ # sqlite runtime (gitignore) +``` + +--- + +## 3. Document(`type: web`) + +```markdown +--- +type: web +title: Marqdo Blog +route: / +method: GET +data_source: posts +data_order: -created_at +import web:ext/web/web.mq.md +import data:ext/data/db.mq.md +--- + +# Marqdo + +Welcome to the executable web. +``` + +| 键 (EN) | 键 (ZH) | 说明 | +|---------|---------|------| +| `type` | `类型` | `web` / `网页` | +| `route` | `路由` | 路径,可含 `{param}` | +| `method` | `方法` | 默认 `GET` | +| `title` | `标题` | 文档标题 / `
一个用 Marqdo 的 web 扩展库(ext/web)写成的博客系统。
它演示了:GFM 表格装配导航与侧栏、SQLite 驱动的主体绑定、动态路由 /post/{slug}、标签归档、以及受 session 保护的后台 CRUD。
"** -**about = > about.组件装配 组件=`首页`** -**about = > about.样式 样式=`首页CSS`** - -**post = > 网页.页面 标题="文章"** -**post = > post.组件装配 组件=`首页`** -**post = > post.主体装配 主体=`详情绑定`** -**post = > post.查询条件 条件=`文章条件`** -**post = > post.详情 详情=True** -**post = > post.样式 样式=`首页CSS`** - -**tags = > 网页.页面 标题="标签归档" 引言="点击标签查看该主题下的文章。
"** -**tags = > tags.组件装配 组件=`首页`** -**tags = > tags.主体装配 主体=`标签列表`** -**tags = > tags.链接前缀 前缀="/tag/"** -**tags = > tags.样式 样式=`首页CSS`** - -**tagged = > 网页.页面 标题="标签"** -**tagged = > tagged.组件装配 组件=`首页`** -**tagged = > tagged.主体装配 主体=`列表`** -**tagged = > tagged.查询条件 条件=`标签条件`** -**tagged = > tagged.排序 排序="-created_at"** -**tagged = > tagged.样式 样式=`首页CSS`** - -**app = > 网页.应用 页面=page 数据库=store 后台=True 主机="127.0.0.1" 端口=18085** -**app = > app.路由 路径="/about" 页面=about** -**app = > app.路由 路径="/post/{slug}" 页面=post** -**app = > app.路由 路径="/tags" 页面=tags** -**app = > app.路由 路径="/tag/{slug}" 页面=tagged** -**app = > app.静态 目录="public" 挂载="/static"** -**app = > app.图标 表=`站点图标`** -**app = > app.路由实时 路径="/live" 回显=True** -**app = > app.鉴权 用户表=`管理员` 会话时长=3600** -> `app`.监听 \ No newline at end of file +```text +marqdo run examples/marqdo-blog/serve.mq.md +``` diff --git a/examples/marqdo-blog/pages/about.mq.md b/examples/marqdo-blog/pages/about.mq.md new file mode 100644 index 0000000..fd50dd6 --- /dev/null +++ b/examples/marqdo-blog/pages/about.mq.md @@ -0,0 +1,10 @@ +--- +类型: 网页 +路由: /about +方法: GET +标题: 关于 +--- + +# 关于 Marqdo + +Marqdo 是可执行文档语言:文档即程序,程序即知识。 diff --git a/examples/marqdo-blog/serve.mq.md b/examples/marqdo-blog/serve.mq.md new file mode 100644 index 0000000..bebeaa3 --- /dev/null +++ b/examples/marqdo-blog/serve.mq.md @@ -0,0 +1,9 @@ +--- +title: marqdo-blog serve +description: Scan Artifact .mq.md under this directory and listen (ADR 0007). +导入 网页:ext/web/网页.mq.md +--- + +# main + +> 网页.服务 根="." 主机="127.0.0.1" 端口=18081 diff --git a/examples/web-client-site/README.md b/examples/web-client-site/README.md index ff825f3..32322f8 100644 --- a/examples/web-client-site/README.md +++ b/examples/web-client-site/README.md @@ -1,20 +1,14 @@ -# web-client-site(路线 D) +# examples/web-client-site -服务端 `ext/web` + 浏览器 WASM 会话;**作者零业务 JS**。 +SSR **Document Artifact** + `web.client_embed` auto-mount(零作者 JS)。ADR 0007。 ```bash -# 仓库根 -cargo build -p marqdo --release -cargo build --release -p marqdo_plugin_web -./target/release/marqdo ext add web - -# 构建 WASM + bridge 到本示例 static/ -./target/release/marqdo wasm build -o examples/web-client-site/static -# 保留 client.mq.md(wasm build 只写入 wasm/bridge) - -cd examples/web-client-site -marqdo run index.mq.md -# 打开 http://127.0.0.1:18090/ +bash scripts/build-web-plugin.sh +export MARQDO_EXT=$PWD/ext # 若本机 ~/.marqdo/ext 未同步 +marqdo wasm build -o examples/web-client-site/static +cargo run -- run examples/web-client-site/serve.mq.md ``` -`index.mq.md` 用 `web.client_embed source="/static/client.mq.md"` 注入自启脚本;交互在 `static/client.mq.md`。 +- `index.mq.md` — `type: web` 文档页 +- `serve.mq.md` — `web.serve` + `static_dir` +- `static/client.mq.md` — `lib/browser` wire(不变) diff --git a/examples/web-client-site/index.mq.md b/examples/web-client-site/index.mq.md index 36a3d8d..342d69d 100644 --- a/examples/web-client-site/index.mq.md +++ b/examples/web-client-site/index.mq.md @@ -1,19 +1,14 @@ --- -title: web-client-site -description: SSR shell + client_embed auto-mount; author zero JS (route D) +type: web +title: Marqdo client site +route: / +method: GET +description: SSR Document + client_embed auto-mount; author zero JS (ADR 0007). import web:ext/web/web.mq.md --- -# main +# Marqdo client site -Server page with a counter UI. Client logic lives in `static/client.mq.md` -(loaded by official bridge via `client_embed`). +SSR shell with WASM session. Client logic lives in `static/client.mq.md`. -**`embed` = > web.client_embed bridge="/static/marqdo-bridge.js" wasm="/static/marqdo_wasm.wasm" source="/static/client.mq.md" boot=True** - -**`intro` = "SSR + WASM session. No author JS.
booting…" + embed** - -**page = > web.page title="Marqdo client site" intro=intro** -**app = > web.app page=page host="127.0.0.1" port=18090** -**app = > app.static dir="static" mount="/static"** -> `app`.listen +To serve with static assets, run `serve.mq.md` in this directory. diff --git a/examples/web-client-site/serve.mq.md b/examples/web-client-site/serve.mq.md new file mode 100644 index 0000000..8d1d933 --- /dev/null +++ b/examples/web-client-site/serve.mq.md @@ -0,0 +1,10 @@ +--- +title: web-client-site serve +import web:ext/web/web.mq.md +--- + +# main + +**`embed` = > web.client_embed source="/static/client.mq.md"** +> print text=embed-ready +> web.serve root="." host="127.0.0.1" port=18090 static_dir="static" diff --git a/ext/data/cache.mq.md b/ext/data/cache.mq.md new file mode 100644 index 0000000..13bca6a --- /dev/null +++ b/ext/data/cache.mq.md @@ -0,0 +1,60 @@ +--- +title: ext/data/cache +description: Cache Resource (ADR 0007). +import plugin:lib/plugin.mq.md +import sys:lib/sys.mq.md +import table:lib/table.mq.md +--- + +## _load + +**p = > plugin.native_path name="web"** +1. `p` + > plugin.load path=`p` +2. * + > print text=ext/data: native web plugin not found + > sys.exit code=1 +**** + +# cache + + `url`="memory:" + +Key–value cache. Use `memory:` for in-process (tests / single process) or `redis://host:6379/0` for Redis. + +> _load +*> web_cache_new url=`url`* + +## get + + `key` + +**url = [url](self)** +*> web_cache_get url=`url` key=`key`* + +## set + + `key` + + `value` + + `ttl`=None + +Optional `ttl` is seconds until expiry. + +**url = [url](self)** +*> web_cache_set url=`url` key=`key` value=`value` ttl=`ttl`* + +## del + + `key` + +**url = [url](self)** +*> web_cache_del url=`url` key=`key`* + +## exists + + `key` + +**url = [url](self)** +*> web_cache_exists url=`url` key=`key`* + +## ttl + + `key` + +**url = [url](self)** +*> web_cache_ttl url=`url` key=`key`* + diff --git a/ext/data/db.mq.md b/ext/data/db.mq.md new file mode 100644 index 0000000..f56ee01 --- /dev/null +++ b/ext/data/db.mq.md @@ -0,0 +1,238 @@ +--- +title: ext/data/db +description: Database Resource — CRUD, txn, migrate, FTS (ADR 0007). +import plugin:lib/plugin.mq.md +import sys:lib/sys.mq.md +import table:lib/table.mq.md +--- + +## _load + +**p = > plugin.native_path name="web"** +1. `p` + > plugin.load path=`p` +2. * + > print text=ext/data: native web plugin not found + > sys.exit code=1 +**** + +# db + + `url`="sqlite:site.db" + +Open a database handle. URL schemes: `sqlite:path` (default), `postgres://…` / `postgresql://…` (same CRUD methods). + +> _load +*> web_db_new url=`url`* + +## init + + `name` + + `fields` + +Create a table from a schema table. Optional columns: `唯一`/`unique`, `索引`/`index` (creates UNIQUE / INDEX), `外键`/`fk`/`references` (e.g. `posts.id` or `posts(id)`). Columns named `created_at` / `updated_at` are filled automatically on insert/update when present. + +**url = [url](self)** +*> web_db_init url=`url` name=`name` fields=`fields`* + +## insert + + `table` + + `rows` + + `txn`=None + +**url = [url](self)** +*> web_db_insert url=`url` table=`table` rows=`rows` txn=`txn`* + +## select + + `table` + + `where`=None + + `limit`=200 + + `order`=None + + `txn`=None + +Simple filters: one-row map of column→value (AND `=`), or rows `|字段|操作|值|` (`=` `!=` `>` `>=` `<` `<=` `like` `in` `between` `is null`; add `|或|` = `是` to join a row with `OR`). `order` is a column name with optional `-` prefix for descending (`"created_at"`, `"-created_at"`), comma-separated for multiple keys. Pass `txn` to read inside an open transaction. For pages (with a total), use `paginate`. + +**url = [url](self)** +**r = > web_db_select url=`url` table=`table` where=`where` limit=`limit` order=`order` offset=None txn=`txn`** +*[rows](r)* + +## paginate + + `table` + + `where`=None + + `limit`=200 + + `order`=None + + `跳过`=0 + + `txn`=None + +Like `select` but returns `{ rows, total }` — the total counts rows matching `where` regardless of `limit`/`跳过`, so you can render `上一页 / 下一页`. Set `跳过` to the number of rows to skip (e.g. page 2 with 10 per page ⇒ `跳过`=10). + +**url = [url](self)** +*> web_db_select url=`url` table=`table` where=`where` limit=`limit` order=`order` offset=`跳过` txn=`txn`* + +## get + + `table` + + `id` + + `txn`=None + +**url = [url](self)** +*> web_db_get url=`url` table=`table` id=`id` txn=`txn`* + +## update + + `table` + + `id` + + `row` + + `txn`=None + +**url = [url](self)** +*> web_db_update url=`url` table=`table` id=`id` row=`row` txn=`txn`* + +## delete + + `table` + + `id` + + `txn`=None + +**url = [url](self)** +*> web_db_delete url=`url` table=`table` id=`id` txn=`txn`* + +## exec + + `sql` + + `args`=None + + `txn`=None + +**url = [url](self)** +*> web_db_exec url=`url` sql=`sql` args=`args` txn=`txn`* + +## query + + `sql` + + `args`=None + + `txn`=None + +Run bare SQL and return the result set — count / join / group / subqueries. Returns `{ rows, count }`. + +**url = [url](self)** +*> web_db_query url=`url` sql=`sql` args=`args` txn=`txn`* + +## count + + `table` + + `where`=None + + `txn`=None + +Count rows matching a `where` filter (same syntax as `select`). Returns a number. + +**url = [url](self)** +**r = > web_db_count url=`url` table=`table` where=`where` txn=`txn`** +*[count](r)* + +## migrate + + `steps` + +Apply versioned SQL migrations. `steps` is a `|version|sql|` / `|版本|SQL|` table. Applied versions are recorded in `_marqdo_migrations`. Re-running is a no-op for already-applied versions. SQLite only. + +**url = [url](self)** +*> web_db_migrate url=`url` steps=`steps`* + +## fts + + `table` + + `columns` + + `name`=None + +Create an FTS5 index on `table` for the listed content columns (CSV string or list). Default FTS name is `{table}_fts`. Keeps the index in sync via triggers. Requires integer `id` PK. SQLite only. + +**url = [url](self)** +*> web_db_fts_create url=`url` table=`table` columns=`columns` name=`name`* + +## search + + `table` + + `q` + + `limit`=20 + + `name`=None + +Full-text search (`MATCH`) against the FTS5 index from `fts`. Returns `{ rows, count }` with a `rank` column (bm25). SQLite only. + +**url = [url](self)** +*> web_db_search url=`url` table=`table` q=`q` limit=`limit` name=`name`* + +## 事务 + +Begin a transaction: borrows the pooled connection exclusively and returns a +`txn` handle. Write inside it, then `提交` (commit) or `回滚` (roll back). +Every statement runs on the same connection, so a batch is atomic. + +**url = [url](self)** +*> web_db_begin url=`url`* + +# txn + + `txn` + + `url` + +A transaction handle from `db.事务`. All CRUD here runs on the transaction's +connection; finish with `提交` or `回滚`. + +*self* + +## insert + + `table` + + `rows` + +**url = [url](self)** +**txn = [txn](self)** +*> web_db_insert url=`url` table=`table` rows=`rows` txn=`txn`* + +## select + + `table` + + `where`=None + + `limit`=200 + + `order`=None + +Same filters as `db.select`; runs inside the transaction. + +**url = [url](self)** +**txn = [txn](self)** +**r = > web_db_select url=`url` table=`table` where=`where` limit=`limit` order=`order` offset=None txn=`txn`** +*[rows](r)* + +## get + + `table` + + `id` + +**url = [url](self)** +**txn = [txn](self)** +*> web_db_get url=`url` table=`table` id=`id` txn=`txn`* + +## update + + `table` + + `id` + + `row` + +**url = [url](self)** +**txn = [txn](self)** +*> web_db_update url=`url` table=`table` id=`id` row=`row` txn=`txn`* + +## delete + + `table` + + `id` + +**url = [url](self)** +**txn = [txn](self)** +*> web_db_delete url=`url` table=`table` id=`id` txn=`txn`* + +## exec + + `sql` + + `args`=None + +**url = [url](self)** +**txn = [txn](self)** +*> web_db_exec url=`url` sql=`sql` args=`args` txn=`txn`* + +## 提交 + +Commit the transaction and return its connection to the pool. + +**txn = [txn](self)** +*> web_db_commit txn=`txn`* + +## 回滚 + +Roll the transaction back (undo every write) and return its connection. + +**txn = [txn](self)** +*> web_db_rollback txn=`txn`* + diff --git a/ext/data/form.mq.md b/ext/data/form.mq.md new file mode 100644 index 0000000..7b49724 --- /dev/null +++ b/ext/data/form.mq.md @@ -0,0 +1,67 @@ +--- +title: ext/data/form +description: Form Resource — fields, validate, submit (ADR 0007). +import plugin:lib/plugin.mq.md +import sys:lib/sys.mq.md +import table:lib/table.mq.md +--- + +## _load + +**p = > plugin.native_path name="web"** +1. `p` + > plugin.load path=`p` +2. * + > print text=ext/data: native web plugin not found + > sys.exit code=1 +**** + +# form + + `table`=None + + `action`=insert + + `id`=None + +Field table + rules table; submit writes through `# db`. + +> _load +*> web_form_new table=`table` action=`action` id=`id`* + +## fields + + `fields` + +*> web_form_fields form=`self` fields=`fields`* + +## rules + + `rules` + +*> web_form_rules form=`self` rules=`rules`* + +## labels + + `submit`="Submit" + + `cancel`="cancel" + + `cancel_href`="" + +Localized submit / cancel copy for rendered forms. + +*> web_form_labels form=`self` submit=`submit` cancel=`cancel` cancel_href=`cancel_href`* + +## validate + + `rules`=None + + `data` + +*> web_form_validate form=`self` rules=`rules` data=`data`* + +## render + + `id`=form + + `data`=None + + `errors`=None + +*> web_form_render form=`self` id=`id` data=`data` errors=`errors`* + +## submit + + `data` + + `db` + +**url = [url](db)** +*> web_form_submit form=`self` data=`data` url=`url`* + diff --git a/ext/data/storage.mq.md b/ext/data/storage.mq.md new file mode 100644 index 0000000..02b9619 --- /dev/null +++ b/ext/data/storage.mq.md @@ -0,0 +1,86 @@ +--- +title: ext/data/storage +description: Object storage Resource (ADR 0007). +import plugin:lib/plugin.mq.md +import sys:lib/sys.mq.md +import table:lib/table.mq.md +--- + +## _load + +**p = > plugin.native_path name="web"** +1. `p` + > plugin.load path=`p` +2. * + > print text=ext/data: native web plugin not found + > sys.exit code=1 +**** + +# storage + + `url`="file:data/blobs" + +Object storage. `file:dir` stores blobs on disk (offline / gold). `s3://bucket?endpoint=http://127.0.0.1:9000&access_key=…&secret_key=…` talks to MinIO / S3. + +> _load +*> web_storage_new url=`url`* + +## put + + `key` + + `body`=None + + `path`=None + + `content_type`="application/octet-stream" + +Provide either `body` (text) or `path` (local file to upload). + +**url = [url](self)** +*> web_storage_put url=`url` key=`key` body=`body` path=`path` content_type=`content_type`* + +## get + + `key` + +**url = [url](self)** +*> web_storage_get url=`url` key=`key`* + +## delete + + `key` + +**url = [url](self)** +*> web_storage_delete url=`url` key=`key`* + +## list + + `prefix`="" + +**url = [url](self)** +*> web_storage_list url=`url` prefix=`prefix`* + +# media + + `storage`=None + +Offline helpers for upload validation and saving into `# storage` (also used by HTTP `app.upload`). + +> _load +*> web_media_new storage=`storage`* + +## validate + + `filename` + + `content_type`="application/octet-stream" + + `size` + + `max_bytes`=5242880 + + `types`=None + +*> web_upload_validate filename=`filename` content_type=`content_type` size=`size` max_bytes=`max_bytes` types=`types`* + +## save + + `path` + + `key`=None + + `content_type`="application/octet-stream" + + `prefix`=uploads/ + + `storage`=None + +**st = storage** +1. `st` == None + **st = [storage](self)** +2. * + +*> web_upload_save storage=`st` path=`path` key=`key` content_type=`content_type` prefix=`prefix`* + diff --git a/ext/net/http.mq.md b/ext/net/http.mq.md new file mode 100644 index 0000000..68052f2 --- /dev/null +++ b/ext/net/http.mq.md @@ -0,0 +1,31 @@ +--- +title: ext/net/http +description: HTTP primitives surface for Web Runtime (ADR 0007). Prefer Document/Endpoint Artifacts over raw calls. +import plugin:lib/plugin.mq.md +import sys:lib/sys.mq.md +--- + +## _load + +**p = > plugin.native_path name="web"** +1. `p` + > plugin.load path=`p` +2. * + > print text=ext/net: native web plugin not found + > sys.exit code=1 +**** + +## result + + `ok` + + `value`=None + + `error`=None + +Unified Result map `{ok, value, error}`. + +`out` = + +| ok | value | error | +|----|-------|-------| +| `ok` | `value` | `error` | + +*out* diff --git a/ext/net/url.mq.md b/ext/net/url.mq.md new file mode 100644 index 0000000..221b8a8 --- /dev/null +++ b/ext/net/url.mq.md @@ -0,0 +1,9 @@ +--- +title: ext/net/url +description: URL helpers (stdlib host wrappers). ADR 0007. +--- + +## encode + + `text` + +*> host_url_encode text=`text`* diff --git a/ext/net/websocket.mq.md b/ext/net/websocket.mq.md new file mode 100644 index 0000000..4558fa1 --- /dev/null +++ b/ext/net/websocket.mq.md @@ -0,0 +1,41 @@ +--- +title: ext/net/websocket +description: WebSocket client Resource (ADR 0007). +import plugin:lib/plugin.mq.md +import sys:lib/sys.mq.md +import table:lib/table.mq.md +--- + +## _load + +**p = > plugin.native_path name="web"** +1. `p` + > plugin.load path=`p` +2. * + > print text=ext/net: native web plugin not found + > sys.exit code=1 +**** + +# ws + + `timeout_sec`=30 + +WebSocket client helper. + +> _load +`out` = + +| timeout_sec | _type | +|-------------|-------| +| `timeout_sec` | ws | + +*out* + +## connect + + `url` + + `message`="" + + `headers`=None + +Single request–response: connect to `url`, send `message`, collect up to 256 server text replies (each up to 1 MiB), close. Transport errors and timeouts return `{ok:false, error}` instead of looking like an empty successful reply. + +**timeout = [timeout_sec](self)** +*> web_ws_connect url=`url` message=`message` headers=`headers` timeout_sec=`timeout`* diff --git a/ext/security/auth.mq.md b/ext/security/auth.mq.md new file mode 100644 index 0000000..7f2c14f --- /dev/null +++ b/ext/security/auth.mq.md @@ -0,0 +1,58 @@ +--- +title: ext/security/auth +description: Auth Resource (ADR 0007). +import plugin:lib/plugin.mq.md +import sys:lib/sys.mq.md +import table:lib/table.mq.md +--- + +## _load + +**p = > plugin.native_path name="web"** +1. `p` + > plugin.load path=`p` +2. * + > print text=ext/security: native web plugin not found + > sys.exit code=1 +**** + +# auth + + `users` + + `session_ttl`=3600 + +Session/auth helper. Constructs a config object; `login` validates against the users table. To gate `/admin` on this app, use `app.auth users=…` instead. + +> _load +*> web_auth_new users=`users` session_ttl=`session_ttl`* + +## login + + `username` + + `password` + +Validate credentials against the users table and create a session. Returns `{ok, session_id, username, role}`. + +**users = [users](self)** +**ttl = [session_ttl](self)** +*> web_auth_login username=`username` password=`password` users=`users` session_ttl=`ttl`* + +## check + + `session_id` + +Returns `{ok, username, role}` when the session is valid. + +*> web_auth_check session_id=`session_id`* + +## logout + + `session_id` + +Destroy the session. + +*> web_auth_logout session_id=`session_id`* + +## hash_password + + `password` + +Hash a plaintext password for storage in admin user tables (argon2id). Store the returned `hash` in the `password` column; login verifies automatically. + +*> web_password_hash password=`password`* + diff --git a/ext/security/oidc.mq.md b/ext/security/oidc.mq.md new file mode 100644 index 0000000..3b037e9 --- /dev/null +++ b/ext/security/oidc.mq.md @@ -0,0 +1,31 @@ +--- +title: ext/security/oidc +description: OIDC attach helper for app handles (ADR 0007). Prefer declared auth metadata on Endpoints. +import plugin:lib/plugin.mq.md +import sys:lib/sys.mq.md +--- + +## _load + +**p = > plugin.native_path name="web"** +1. `p` + > plugin.load path=`p` +2. * + > print text=ext/security: native web plugin not found + > sys.exit code=1 +**** + +## attach + + `app` + + `issuer`=None + + `client_id` + + `client_secret` + + `redirect_uri` + + `scopes`="openid profile email" + + `callback_path`=None + + `authorize_url`=None + + `token_url`=None + + `userinfo_url`=None + +> _load +*> web_app_oidc app=`app` issuer=`issuer` client_id=`client_id` client_secret=`client_secret` redirect_uri=`redirect_uri` scopes=`scopes` callback_path=`callback_path` authorize_url=`authorize_url` token_url=`token_url` userinfo_url=`userinfo_url`* diff --git a/ext/security/rbac.mq.md b/ext/security/rbac.mq.md new file mode 100644 index 0000000..6cfe05f --- /dev/null +++ b/ext/security/rbac.mq.md @@ -0,0 +1,61 @@ +--- +title: ext/security/rbac +description: RBAC Resource (ADR 0007). +import plugin:lib/plugin.mq.md +import sys:lib/sys.mq.md +import table:lib/table.mq.md +--- + +## _load + +**p = > plugin.native_path name="web"** +1. `p` + > plugin.load path=`p` +2. * + > print text=ext/security: native web plugin not found + > sys.exit code=1 +**** + +# rbac + +Offline helpers for role ⊥ permission. Prefer `app.enable_rbac` + gates for HTTP; use these for scripts/tests. + +## can + + `permissions` + + `needed` + +Return `{ok, allowed}` — whether held permission CSV includes any of `needed` (CSV). Held `*` allows all. + +> _load +*> web_rbac_can permissions=`permissions` needed=`needed`* + +## assign_role + + `url` + + `username` + + `role` + +Bind `username` (in `web_users`) to role name. + +> _load +*> web_rbac_assign_role url=`url` username=`username` role=`role`* + +## create_role + + `url` + + `name` + +Create a non-system role; returns `{ok, id, name}`. + +> _load +*> web_rbac_create_role url=`url` name=`name`* + +## set_role_permissions + + `url` + + `role` + + `permissions` + + `grantable`="" + +Replace permissions on a non-system role (CSV). `grantable` restricts grants (anti-escalation); empty = full catalog. + +> _load +*> web_rbac_set_role_permissions url=`url` role=`role` permissions=`permissions` grantable=`grantable`* + diff --git a/ext/web/README.md b/ext/web/README.md index 9289588..0b264b4 100644 --- a/ext/web/README.md +++ b/ext/web/README.md @@ -1,31 +1,20 @@ -# ext/web +# ext/web — Document / Endpoint / Resource -Official dynamic website extension: **GFM tables + class methods**. -Design: [`doc/design/ext-web.md`](../../doc/design/ext-web.md). +Official dynamic site extension (**ADR 0007**). Design: [`doc/design/ext-web-artifact.md`](../../doc/design/ext-web-artifact.md). -| Surface | Import | Classes | -|---------|--------|---------| -| English | `> ext/web/web.mq.md` | `page` · `db` · `app` · `form` · `style` | -| Chinese | `> ext/web/网页.mq.md` | `页面` · `数据库` · `应用` · `表单` · `样式` | - -```bash -cargo build -p marqdo_plugin_web -# optional install into ~/.marqdo/ext -marqdo ext add web -``` - -Canonical sample (design §4): [`examples/web-site/`](../../examples/web-site/). - -```bash -cargo run -- run examples/web-site/index.mq.md -# http://127.0.0.1:18081/ -# /_form/article · /admin · /admin/articles/new -``` - -Offline smokes: `tests/ext/web-smoke.mq.md`, `web-form-smoke.mq.md`, `web-admin-smoke.mq.md`. - -| Feature | Notes | +| Surface | Import | |---------|--------| -| Form §5.5 | field/rules tables · `validate` · `submit` · `mount_form` → `GET\|POST /_form/{id}` | -| Admin CRUD | `admin=True` · schema → same form path · new/edit/delete under `/admin/{table}` | -| Route | `` `app`.route path=/about page=`about` `` → `GET /about` | \ No newline at end of file +| English | `import web:ext/web/web.mq.md` | +| Chinese | `导入 网页:ext/web/网页.mq.md` | + +**Facade:** `page` · `route` · `serve` · `render` · `inspect` · `use` + +**Related modules:** `ext/data` (db/cache/storage) · `ext/security` (auth/oidc/rbac) · `ext/net` (http/websocket/url) + +```bash +bash scripts/build-web-plugin.sh +marqdo ext add web # optional install +marqdo run examples/marqdo-blog/serve.mq.md +``` + +Hard rules: no author `ensure_plugin` / `compose_*` / `configure` junk drawer; View schema `|type|slot|value|attrs|style|` only; declared vs system routes via `inspect`. diff --git a/ext/web/_capability.mq.md b/ext/web/_capability.mq.md new file mode 100644 index 0000000..31ccb88 --- /dev/null +++ b/ext/web/_capability.mq.md @@ -0,0 +1,18 @@ +--- +title: ext/web/_capability +description: Internal — load native web plugin once. Authors must not call this; import web = capability (ADR 0007). +import plugin:lib/plugin.mq.md +import sys:lib/sys.mq.md +--- + +## load + +Load ABI v2 `web` plugin if present. Fail loud when missing. + +**p = > plugin.native_path name="web"** +1. `p` + > plugin.load path=`p` +2. * + > print text=ext/web: native web plugin not found (build plugins/web or marqdo ext add web) + > sys.exit code=1 +**** diff --git a/ext/web/client.mq.md b/ext/web/client.mq.md new file mode 100644 index 0000000..6b84380 --- /dev/null +++ b/ext/web/client.mq.md @@ -0,0 +1,50 @@ +--- +title: ext/web/client +description: Browser Runtime helpers (WASM bridge). Prefer lib/browser for effect tables (ADR 0007). +import cap:ext/web/_capability.mq.md +import table:lib/table.mq.md +--- + +## embed + + `bridge`="/static/marqdo-bridge.js" + + `wasm`="/static/marqdo_wasm.wasm" + + `source`="" + + `boot`=True + +HTML snippet that loads the official browser Marqdo bridge (route C/D). With `boot` and non-empty `source`, auto-mounts. No author JS. + +> cap.load +1. `boot` + 1. `source` != "" + *""* + 2. * + *""* +2. * + *""* + +## text_patch + + `sel` + + `text` + +`set_text` effects map. Prefer `lib/browser` in client `.mq.md`. + +**`m` = > table.put in=None at=sel value=text** +*> table.put in=None at="set_text" value=m* + +## dom_patch + + `sel` + + `html`="" + + `attrs`=None + + `remove`=False + +**`spec` = > table.put in=None at="html" value=html** +1. `attrs` + **`spec` = > table.put in=`spec` at="attrs" value=attrs** +2. * + **_ = 1** +1. `remove` + **`spec` = > table.put in=`spec` at="remove" value=True** +2. * + **_ = 1** +**`m` = > table.put in=None at=sel value=spec** +*> table.put in=None at="dom" value=m* diff --git a/ext/web/component.mq.md b/ext/web/component.mq.md new file mode 100644 index 0000000..f3bd393 --- /dev/null +++ b/ext/web/component.mq.md @@ -0,0 +1,20 @@ +--- +title: ext/web/component +description: Reusable Document fragments as View node tables (ADR 0007). +import table:lib/table.mq.md +--- + +## nodes + + `table` + +Identity helper — a component is a View table `|type|slot|value|attrs|style|`. + +*table* + +## merge + + `a` + + `b` + +Concatenate two View node lists (list-of-maps or column tables). Prefer authoring one table. + +*> table.concat a=`a` b=`b`* diff --git a/ext/web/dom.mq.md b/ext/web/dom.mq.md new file mode 100644 index 0000000..1d5b76a --- /dev/null +++ b/ext/web/dom.mq.md @@ -0,0 +1,38 @@ +--- +title: ext/web/dom +description: DOM Artifact — Markdown/body to structure; raw HTML is escape hatch only (ADR 0007). +import cap:ext/web/_capability.mq.md +import table:lib/table.mq.md +--- + +## from_markdown + + `text` + +Turn Markdown text into a simple DOM map `{kind:"markdown", text}` for `page.render` / `web.render`. + +> cap.load +**`out` = > table.put in=None at="kind" value="markdown"** +*> table.put in=`out` at="text" value=text* + +## raw + + `html` + +Escape hatch — wrap a raw HTML string. Prefer Markdown / View nodes. + +> cap.load +**`out` = > table.put in=None at="kind" value="raw"** +*> table.put in=`out` at="html" value=html* + +## render + + `dom` + +Render a DOM Artifact (markdown or raw) to HTML via native plugin. + +> cap.load +**kind = [kind](dom)** +1. `kind` == "raw" + **html = [html](dom)** + *html* +2. * + **text = [text](dom)** + *> web_dom_markdown text=`text`* diff --git a/ext/web/page.mq.md b/ext/web/page.mq.md new file mode 100644 index 0000000..4f65fca --- /dev/null +++ b/ext/web/page.mq.md @@ -0,0 +1,54 @@ +--- +title: ext/web/page +description: Document → View. Sole compose path is render(nodes=) with unified View schema (ADR 0007). +import cap:ext/web/_capability.mq.md +import table:lib/table.mq.md +--- + +# page + + `title`="" + + `route`="/" + + `method`="GET" + + `body`="" + + `nodes`=None + + `data_source`="" + + `data_order`="" + + `data_where`="" + +Web Document handle. Prefer constructing from Artifact Metadata via `web.page` facade. +View tables use only `|type|slot|value|attrs|style|` (ZH `|类型|槽|值|属性|样式|`). + +> cap.load +`out` = + +| _type | title | route | method | body | nodes | data_source | data_order | data_where | +|-------|-------|-------|--------|------|-------|-------------|------------|------------| +| page | `title` | `route` | `method` | `body` | `nodes` | `data_source` | `data_order` | `data_where` | + +*out* + +## render + + `nodes`=None + + `db`=None + +Render Document to HTML. `nodes` is the unified View table; when omitted, uses `self.nodes` or Markdown `body`. + +> cap.load +**n = nodes** +1. `n` == None + **n = [nodes](self)** +2. * + **_ = 1** +1. `n` + *> web_render_nodes page=`self` nodes=`n` db=`db`* +2. * + **body = [body](self)** + *> web_render_document page=`self` body=`body` db=`db`* + +## css + + `css` + +Escape hatch — append raw CSS (not a second primary language). + +> cap.load +*> web_page_css page=`self` css=`css`* diff --git a/ext/web/route.mq.md b/ext/web/route.mq.md new file mode 100644 index 0000000..1b4885d --- /dev/null +++ b/ext/web/route.mq.md @@ -0,0 +1,60 @@ +--- +title: ext/web/route +description: Declared Endpoint / Document route registration (ADR 0007). +import cap:ext/web/_capability.mq.md +import table:lib/table.mq.md +--- + +# route + + `app` + + `path` + + `method`="GET" + + `page`=None + + `fn`="" + + `request`="json" + + `response`="json" + + `auth`="" + +Declared route handle. Prefer `web.route` / Artifact `type: endpoint` discovery via `web.serve`. + +> cap.load +`out` = + +| _type | app | path | method | page | fn | request | response | auth | +|-------|-----|------|--------|------|----|---------|----------|------| +| route | `app` | `path` | `method` | `page` | `fn` | `request` | `response` | `auth` | + +*out* + +## use + + `middleware` + +Attach middleware table to this route (`|header|value|` or named capability rows). + +> cap.load +*> web_route_use route=`self` middleware=`middleware`* + +## register + + `app`=None + +Register this declared route on an app handle. + +> cap.load +**a = app** +1. `a` == None + **a = [app](self)** +2. * + **_ = 1** +**page = [page](self)** +**fn = [fn](self)** +1. `page` + **path = [path](self)** + *> web_app_route app=`a` path=`path` page=`page`* +2. `fn` + **path = [path](self)** + **method = [method](self)** + **request = [request](self)** + **response = [response](self)** + *> web_app_invoke app=`a` path=`path` method=`method` fn=`fn` body=`request` return=`response`* +3. * + *> table.put in=None at="ok" value=False* diff --git a/ext/web/web.mq.md b/ext/web/web.mq.md index 8da3213..c6c334e 100644 --- a/ext/web/web.mq.md +++ b/ext/web/web.mq.md @@ -1,74 +1,93 @@ --- title: ext/web/web -description: Official web site classes (English). Tables + methods; no bag glue. -import plugin:lib/plugin.mq.md -import sys:lib/sys.mq.md +description: >- + Web Artifact facade (ADR 0007) — page · route · serve · render · inspect · use. + Document/Endpoint first-class. No compose_* / configure / author ensure_plugin. +import cap:ext/web/_capability.mq.md +import page_mod:ext/web/page.mq.md +import route_mod:ext/web/route.mq.md +import dom_mod:ext/web/dom.mq.md +import client_mod:ext/web/client.mq.md import table:lib/table.mq.md --- -## ensure_plugin +Importing this module is the web **capability** (native plugin loads on first facade call). -Load the ABI v2 `web` plugin once. +## page + + `title`="" + + `route`="/" + + `method`="GET" + + `body`="" + + `nodes`=None + + `data_source`="" + + `data_order`="" + + `data_where`="" -**p = > plugin.native_path name="web"** -1. `p` - > plugin.load path=`p` -2. * - > print text=ext/web: native web plugin not found (build marqdo_plugin_web or marqdo ext add web) - > sys.exit code=1 -**** +Construct a Document handle. Prefer `type: web` Artifact files discovered by `serve`. -## make_style - + `name`="" - + `table` - + `strict`=False +*> page_mod.page title=`title` route=`route` method=`method` body=`body` nodes=`nodes` data_source=`data_source` data_order=`data_order` data_where=`data_where`* -Assemble a GFM style table into a CSS string. Two shapes are accepted: -`|选择器|属性|值|` rule rows (arbitrary selectors; rows sharing a selector are -merged, and a leading `|媒体|` column groups rows into `@media` blocks), or -`|属性|值|` property rows wrapped as `.name { … }`. Selectors starting with -`@keyframes name` emit keyframe blocks (`属性` = stop `from`/`to`/`N%`, -`值` = `prop: val` or use `@keyframes name from` + normal 属性/值). Quote CSS -values that contain `/` (e.g. `"16/9"`, `"1 / 5"`); bare `1 / 5` is integer -division and becomes a numeric cell — default mode warns, `strict=True` errors. -For complex themes prefer `page.css` (raw string, no table eval) or an external -`static/*.css` via `page.head`. Styles stay as data tables, `make_style` turns -them into CSS — 样式即数据、装配即函数. +## route + + `app` + + `path` + + `method`="GET" + + `page`=None + + `fn`="" + + `request`="json" + + `response`="json" + + `auth`="" -> ensure_plugin -*> web_style name=`name` table=`table` strict=`strict`* +Register a declared Document page or Endpoint (`fn` = `lib.member`). -## make_intro - + `table` +**r = > route_mod.route app=`app` path=`path` method=`method` page=`page` fn=`fn` request=`request` response=`response` auth=`auth`** +*> `r`.register app=`app`* -Assemble an intro bind table (`|属性|值|样式|` / `|front|back|style|`) into an -HTML fragment for `.main-intro`. Same slot vocabulary as `compose_intro` -(`kicker`/`title`/`lede`/`claim`/`step`, plus ZH aliases). The `样式` column is -treated as a class name only here — prefer `page.compose_intro` when styles -should resolve from `shell.*` tables into `styles_css`. +## render + + `doc`=None + + `nodes`=None + + `body`="" + + `title`="" + + `db`=None -> ensure_plugin -*> web_intro table=`table`* +Render a Document or View nodes to HTML (offline / preview). -## make_images - + `table` +> cap.load +1. `doc` + *> `doc`.render nodes=`nodes` db=`db`* +2. `nodes` + *> web_render_nodes page=`doc` nodes=`nodes` db=`db` title=`title`* +3. * + *> web_render_document page=`doc` body=`body` db=`db` title=`title`* -Assemble a GFM image table into an HTML fragment (`div.mq-images` of -`