From 562f3b20a73d1f91f6487cfed3ef65ff9ef4b5fa Mon Sep 17 00:00:00 2001 From: Andreas Brenner Date: Sun, 14 Jun 2026 21:49:34 +0300 Subject: [PATCH] ANW-28 docs: README and LICENSE for the public mirror Replace the placeholder README with the full public-facing README, and switch licensing to BSD 3-Clause per aav's decision on ANW-28: add a single LICENSE file, drop the dual LICENSE-MIT / LICENSE-APACHE, and update the Cargo.toml license field to match. README/LICENSE content authored by kaa, landed verbatim. Assumed: dropping the old MIT/Apache files and updating Cargo.toml license = BSD-3-Clause is the consistent completion of aav's BSD decision (v0.0.0, nothing released relied on the old grant); flag if the dual license was meant to stay. --- Cargo.toml | 2 +- LICENSE | 28 +++++++ LICENSE-APACHE | 201 ------------------------------------------------- LICENSE-MIT | 21 ------ README.md | 181 +++++++++++++++++++++++++++++++++++++------- 5 files changed, 181 insertions(+), 252 deletions(-) create mode 100644 LICENSE delete mode 100644 LICENSE-APACHE delete mode 100644 LICENSE-MIT diff --git a/Cargo.toml b/Cargo.toml index ed408d5..41e98a5 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -4,7 +4,7 @@ description = "Read-only HTTP daemon over a markdown vault, querying YAML frontm version = "0.0.0" edition = "2024" rust-version = "1.95" -license = "MIT OR Apache-2.0" +license = "BSD-3-Clause" repository = "ssh://gw.aristov.cc/srv/repos/anwesen.git" [[bin]] diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..f5da4c6 --- /dev/null +++ b/LICENSE @@ -0,0 +1,28 @@ +BSD 3-Clause License + +Copyright (c) 2026, Alexey Aristov + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are met: + +1. Redistributions of source code must retain the above copyright notice, this + list of conditions and the following disclaimer. + +2. Redistributions in binary form must reproduce the above copyright notice, + this list of conditions and the following disclaimer in the documentation + and/or other materials provided with the distribution. + +3. Neither the name of the copyright holder nor the names of its + contributors may be used to endorse or promote products derived from + this software without specific prior written permission. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE +DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE +FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR +SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER +CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. diff --git a/LICENSE-APACHE b/LICENSE-APACHE deleted file mode 100644 index 85cc56a..0000000 --- a/LICENSE-APACHE +++ /dev/null @@ -1,201 +0,0 @@ - Apache License - Version 2.0, January 2004 - http://www.apache.org/licenses/ - - TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION - - 1. Definitions. - - "License" shall mean the terms and conditions for use, reproduction, - and distribution as defined by Sections 1 through 9 of this document. - - "Licensor" shall mean the copyright owner or entity authorized by - the copyright owner that is granting the License. - - "Legal Entity" shall mean the union of the acting entity and all - other entities that control, are controlled by, or are under common - control with that entity. For the purposes of this definition, - "control" means (i) the power, direct or indirect, to cause the - direction or management of such entity, whether by contract or - otherwise, or (ii) ownership of fifty percent (50%) or more of the - outstanding shares, or (iii) beneficial ownership of such entity. - - "You" (or "Your") shall mean an individual or Legal Entity - exercising permissions granted by this License. - - "Source" form shall mean the preferred form for making modifications, - including but not limited to software source code, documentation - source, and configuration files. - - "Object" form shall mean any form resulting from mechanical - transformation or translation of a Source form, including but - not limited to compiled object code, generated documentation, - and conversions to other media types. - - "Work" shall mean the work of authorship, whether in Source or - Object form, made available under the License, as indicated by a - copyright notice that is included in or attached to the work - (an example is provided in the Appendix below). - - "Derivative Works" shall mean any work, whether in Source or Object - form, that is based on (or derived from) the Work and for which the - editorial revisions, annotations, elaborations, or other modifications - represent, as a whole, an original work of authorship. For the purposes - of this License, Derivative Works shall not include works that remain - separable from, or merely link (or bind by name) to the interfaces of, - the Work and Derivative Works thereof. - - "Contribution" shall mean any work of authorship, including - the original version of the Work and any modifications or additions - to that Work or Derivative Works thereof, that is intentionally - submitted to Licensor for inclusion in the Work by the copyright owner - or by an individual or Legal Entity authorized to submit on behalf of - the copyright owner. For the purposes of this definition, "submitted" - means any form of electronic, verbal, or written communication sent - to the Licensor or its representatives, including but not limited to - communication on electronic mailing lists, source code control systems, - and issue tracking systems that are managed by, or on behalf of, the - Licensor for the purpose of discussing and improving the Work, but - excluding communication that is conspicuously marked or otherwise - designated in writing by the copyright owner as "Not a Contribution." - - "Contributor" shall mean Licensor and any individual or Legal Entity - on behalf of whom a Contribution has been received by Licensor and - subsequently incorporated within the Work. - - 2. Grant of Copyright License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - copyright license to reproduce, prepare Derivative Works of, - publicly display, publicly perform, sublicense, and distribute the - Work and such Derivative Works in Source or Object form. - - 3. Grant of Patent License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - (except as stated in this section) patent license to make, have made, - use, offer to sell, sell, import, and otherwise transfer the Work, - where such license applies only to those patent claims licensable - by such Contributor that are necessarily infringed by their - Contribution(s) alone or by combination of their Contribution(s) - with the Work to which such Contribution(s) was submitted. If You - institute patent litigation against any entity (including a - cross-claim or counterclaim in a lawsuit) alleging that the Work - or a Contribution incorporated within the Work constitutes direct - or contributory patent infringement, then any patent licenses - granted to You under this License for that Work shall terminate - as of the date such litigation is filed. - - 4. Redistribution. You may reproduce and distribute copies of the - Work or Derivative Works thereof in any medium, with or without - modifications, and in Source or Object form, provided that You - meet the following conditions: - - (a) You must give any other recipients of the Work or - Derivative Works a copy of this License; and - - (b) You must cause any modified files to carry prominent notices - stating that You changed the files; and - - (c) You must retain, in the Source form of any Derivative Works - that You distribute, all copyright, patent, trademark, and - attribution notices from the Source form of the Work, - excluding those notices that do not pertain to any part of - the Derivative Works; and - - (d) If the Work includes a "NOTICE" text file as part of its - distribution, then any Derivative Works that You distribute must - include a readable copy of the attribution notices contained - within such NOTICE file, excluding those notices that do not - pertain to any part of the Derivative Works, in at least one - of the following places: within a NOTICE text file distributed - as part of the Derivative Works; within the Source form or - documentation, if provided along with the Derivative Works; or, - within a display generated by the Derivative Works, if and - wherever such third-party notices normally appear. The contents - of the NOTICE file are for informational purposes only and - do not modify the License. You may add Your own attribution - notices within Derivative Works that You distribute, alongside - or as an addendum to the NOTICE text from the Work, provided - that such additional attribution notices cannot be construed - as modifying the License. - - You may add Your own copyright statement to Your modifications and - may provide additional or different license terms and conditions - for use, reproduction, or distribution of Your modifications, or - for any such Derivative Works as a whole, provided Your use, - reproduction, and distribution of the Work otherwise complies with - the conditions stated in this License. - - 5. Submission of Contributions. Unless You explicitly state otherwise, - any Contribution intentionally submitted for inclusion in the Work - by You to the Licensor shall be under the terms and conditions of - this License, without any additional terms or conditions. - Notwithstanding the above, nothing herein shall supersede or modify - the terms of any separate license agreement you may have executed - with Licensor regarding such Contributions. - - 6. Trademarks. This License does not grant permission to use the trade - names, trademarks, service marks, or product names of the Licensor, - except as required for describing the origin of the Work and - reproducing the content of the NOTICE file. - - 7. Disclaimer of Warranty. Unless required by applicable law or - agreed to in writing, Licensor provides the Work (and each - Contributor provides its Contributions) on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or - implied, including, without limitation, any warranties or conditions - of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A - PARTICULAR PURPOSE. You are solely responsible for determining the - appropriateness of using or redistributing the Work and assume any - risks associated with Your exercise of permissions under this License. - - 8. Limitation of Liability. In no event and under no legal theory, - whether in tort (including negligence), contract, or otherwise, - unless required by applicable law (such as deliberate and grossly - negligent acts) or agreed to in writing, shall any Contributor be - liable to You for damages, including any direct, indirect, special, - incidental, or consequential damages of any character arising as a - result of this License or out of the use or inability to use the - Work (including but not limited to damages for loss of goodwill, - work stoppage, computer failure or malfunction, or any and all - other commercial damages or losses), even if such Contributor - has been advised of the possibility of such damages. - - 9. Accepting Warranty or Support. While redistributing the Work or - Derivative Works thereof, You may accept and charge a fee for, - acceptance of support, warranty, indemnity, or other liability - obligations and/or rights consistent with this License. However, - in accepting such obligations, You may act only on Your own behalf - and on Your sole responsibility, not on behalf of any other - Contributor, and only if You agree to indemnify, defend, and hold - each Contributor harmless for any liability incurred by, or claims - asserted against, such Contributor by reason of your accepting any - such warranty or support. - - END OF TERMS AND CONDITIONS - - APPENDIX: How to apply the Apache License to your work. - - To apply the Apache License to your work, attach the following - boilerplate notice, with the fields enclosed by brackets "[]" - replaced with your own identifying information. (Don't include - the brackets!) The text should be enclosed in the appropriate - comment syntax for the file format. We also recommend that a - file name or class identifier and description of purpose be - included on the same "printed page" as the copyright notice for - easier identification within the archive. - - Copyright 2026 Carvers - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or - implied. See the License for the specific language governing permissions - and limitations under the License. diff --git a/LICENSE-MIT b/LICENSE-MIT deleted file mode 100644 index 5e879d9..0000000 --- a/LICENSE-MIT +++ /dev/null @@ -1,21 +0,0 @@ -MIT License - -Copyright (c) 2026 Carvers - -Permission is hereby granted, free of charge, to any person obtaining a copy -of this software and associated documentation files (the "Software"), to deal -in the Software without restriction, including without limitation the rights -to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -copies of the Software, and to permit persons to whom the Software is -furnished to do so, subject to the following conditions: - -The above copyright notice and this permission notice shall be included in -all copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN -THE SOFTWARE. diff --git a/README.md b/README.md index c9bc464..1599bbb 100644 --- a/README.md +++ b/README.md @@ -1,55 +1,178 @@ # Anwesen -Read-only HTTP daemon over a markdown vault. Walks notes in place, parses -YAML frontmatter, watches the directory for changes, and answers three kinds -of question over JSON: read one note, list a folder, query by frontmatter. +> *Anwesen* (German): the premises, the estate -- and, in Heidegger, a coming-to-presence. A read-only HTTP daemon that brings a markdown vault into presence over the network. -See the User Manual and ADRs in the project's design vault for the contract -and rationale. +Anwesen serves an Obsidian-style markdown vault read-only over HTTP. It walks the notes in place, parses their YAML frontmatter, and lets remote clients query notes by frontmatter fields, read individual notes, and list folders -- with no database, no copy, and no migration of the underlying directory. The same query and merge engine is also available offline as a one-shot CLI. -## Subcommands +## Why + +Obsidian is the odd one out among knowledge stores in not shipping a native HTTP API. Notion, Confluence, Wiki.js, Outline and the rest expose one out of the box; an Obsidian vault is just a directory of markdown files on disk. Anwesen brings that vault up to the same bar without converting it into something else: the files stay exactly where Obsidian wrote them and remain editable in Obsidian with no coordination. Programs that need the vault's contents stop re-implementing "walk the directory, parse the YAML, filter the notes" -- they ask Anwesen. + +## What it does + +``` +Obsidian vault -> Anwesen (walk + frontmatter index) -> HTTP/JSON -> consumers +``` + +Anwesen answers three kinds of question over HTTP: + +- *Give me this one note* -- `GET /notes/` +- *List the contents of this folder* -- `GET /notes//` +- *Find every note whose frontmatter matches these predicates* -- `GET /query?...` + +The frontmatter index is built once at startup and kept current by watching the vault directory. The index lives in memory; a restart rebuilds it, and there is nothing on disk to corrupt or migrate. + +The same query-and-merge engine also runs offline, with no server: `anwesen merge` walks a directory, evaluates a query, and writes the merged markdown to stdout (see [Local generation](#local-generation)). + +## Quick start + +Build (Rust, 2024 edition, stable toolchain): + +``` +cargo build --release +``` + +Run: + +``` +anwesen serve --vault /path/to/vault +``` + +Anwesen binds `127.0.0.1:8080` by default, walks the vault once, then serves the API and watches for changes. Stop it with `SIGINT`/`SIGTERM`; there is nothing on disk to clean up. + +Check a vault before serving it: + +``` +anwesen doctor --vault /path/to/vault +``` + +Build one file out of many notes, without starting the daemon: + +``` +anwesen merge --vault /path/to/vault --query 'tags=adr&__anw-order=title' > ADRs.md +``` + +## CLI ``` anwesen serve --vault [--bind ] [--log-level ] -anwesen doctor --vault [--log-level ] +anwesen doctor --vault +anwesen merge --vault --query anwesen version ``` -Each flag has a matching `ANWESEN_` environment variable; CLI wins -over env. +| Flag | Env var | Default | Meaning | +|---|---|---|---| +| `--vault ` | `ANWESEN_VAULT` | *required* | Path to the vault root. | +| `--bind ` | `ANWESEN_BIND` | `127.0.0.1:8080` | Listen address for `serve`. | +| `--log-level ` | `ANWESEN_LOG_LEVEL` | `info` | `error`, `warn`, `info`, `debug`, or `trace`. | +| `--query ` | -- | *required for `merge`* | A `/query` query string: frontmatter predicates plus `__anw-` controls. | -## Deployment +Every flag has a matching `ANWESEN_` environment variable; CLI flags win over env vars. -A systemd unit and an example reverse-proxy config live in [`deploy/`](deploy/). -Anwesen binds `127.0.0.1` and ships no authentication -- the proxy is the -access boundary. See [`deploy/README.md`](deploy/README.md). +- **`serve`** -- run the daemon: walk the vault, build the index, watch for changes, serve the API. +- **`doctor`** -- walk the vault once and report what would stop clean ingestion: unreadable files, unparseable YAML, path collisions on the HTTP surface, and frontmatter type drift (the same key carrying incompatible types across notes). Read-only; non-zero exit if any issue is found. +- **`merge`** -- one-shot local generation: walk the vault, evaluate `--query`, and write the merged markdown document to stdout. No server, no HTTP. See [Local generation](#local-generation). +- **`version`** -- print version and exit. -## Development +## HTTP API + +All endpoints are `GET` and return JSON unless noted. + +### `GET /notes/` -- read one note + +Returns `{ path, frontmatter, body, last_modified, etag, size }`, where `body` is the markdown with the frontmatter block stripped. + +- `Accept: text/markdown` returns the raw file verbatim, frontmatter intact. +- `If-None-Match: ""` returns `304 Not Modified` when the note is unchanged. ETags are strong -- the BLAKE3 hash of the file's raw bytes -- so they are stable across restarts and unaffected by identical-byte rewrites (format-on-save, sync clients, `git checkout` of the same revision). +- `..` segments in the path are rejected with `400`. + +### `GET /notes//` -- directory listing + +Note the trailing slash; that is how a folder index is distinguished from a note read. Returns the immediate children only (non-recursive), each with name, type (`file`/`dir`), `last_modified`, and size. + +### `GET /query?...` -- frontmatter query + +Returns `{ results, total, truncated }`. Each query-string `key=value` is a predicate on a frontmatter field; different keys combine with AND. ``` -scripts/ci.sh # fmt + clippy + test + hurl contract harness +GET /query?tags=anwesen&kind=adr ``` -### HTTP contract tests +**Field operators** (suffix on the key): -End-to-end HTTP behaviour is verified by [hurl](https://hurl.dev/) per -ADR-008. Install once: +| Suffix | Example | Meaning | +|---|---|---| +| *(none)* | `tags=python` | Exact match on scalars; "contains" if the field is a list. | +| `__in` | `tags__in=python,go` | Any of the listed values matches. | +| `__all` | `tags__all=python,fastapi` | List contains all listed values. | +| `__not` | `status__not=draft` | Negation. | +| `__exists` | `deprecated__exists=false` | Presence / absence of the key. | +| `__regex` | `title__regex=^PDR-\d+` | Regex on a scalar (anchor it for speed). | +| `__prefix` | `path__prefix=Projects` | String prefix. | +| `__gt` `__gte` `__lt` `__lte` | `date__gte=2026-01-01` | Ordered comparison; numbers and ISO dates. | + +ISO-8601 dates and RFC 3339 datetimes are coerced to typed dates at read time, so range operators work on them. Nested keys use dots: `author.name=...`. Unknown operators return `400` rather than being silently ignored. Unanchored substring (`__contains`) is intentionally not provided; use `__regex`. + +**Control parameters** (`__anw-` prefix; configure the query rather than constrain matches): + +| Parameter | Default | Meaning | +|---|---|---| +| `__anw-recursive=` | `true` | Recurse into subdirectories. | +| `__anw-path=` | vault root | Restrict matches to a path prefix. | +| `__anw-limit=` | no limit | Cap the result list; `total` still reports the full match count. | +| `__anw-order=[:asc\|:desc]` | path order | Order fragments (merge mode only). | +| `__anw-kind=` | off | Refuse a mixed merge unless every matched note shares one value for the key (merge mode only). | + +By default `/query` returns metadata only; fetch bodies with `/notes/`. + +#### Markdown-merge mode + +`Accept: text/markdown` on `/query` returns the **bodies** of all matched notes concatenated into one markdown document, each fragment preceded by an HTML-comment source marker and separated by a blank line. This is the single-request path for building one file out of many notes: ``` -# Ubuntu / Debian -curl -sSL -o /tmp/hurl.deb https://github.com/Orange-OpenSource/hurl/releases/download/8.0.0/hurl_8.0.0_amd64.deb -sudo dpkg -i /tmp/hurl.deb + +...body... -# Pinned at hurl 8.0.0. Other recent 8.x releases also work but are not -# what CI runs. + +...body... ``` -Then `scripts/ci.sh` -- or `tests/run-hurl.sh` to run just the contract -suite (it builds the debug binary if missing, boots `anwesen serve` on -`127.0.0.1:18086`, waits for `/health`, runs every `tests/hurl/**/*.hurl`, -and tears the daemon down on exit). Override the port with -`ANWESEN_TEST_PORT=` if 18086 clashes locally. +`__anw-order` sets fragment order; `__anw-kind` guards against merging notes that disagree on a key (returns `400` naming the offenders). Both evaluate over the full match set before `__anw-limit` truncates. + +The same merged document is available offline, without the daemon, via `anwesen merge` (see [Local generation](#local-generation)). + +### `GET /health` -- liveness and index freshness + +Returns vault path, note count, last index/event timestamps, watcher state, an in-flight-rescan flag, and supervisor restart counters. Always returns `200` while the process is up; for a hard liveness signal use TCP connectivity. + +### Status codes + +`200` ok | `304` ETag matched | `400` bad request | `404` not found | `500` internal | `503` index not ready (retry shortly). + +## Local generation + +`anwesen merge` produces the markdown-merge document on the command line, with no server and no HTTP round-trip. It walks the vault, evaluates the query, and writes the merged document to stdout: + +``` +anwesen merge --vault /path/to/vault --query 'tags=adr&__anw-order=title&__anw-kind=kind' +``` + +The `--query` string is the exact `/query` grammar: frontmatter predicates plus the `__anw-` controls, including `__anw-order` for fragment order and `__anw-kind` for the homogeneity guard. The output is byte-identical to the HTTP merge mode for the same vault and query -- both run the same engine. A `__anw-kind` violation exits non-zero and names the offending values on stderr; an empty match set writes nothing and exits `0`. + +This is the materialization path: build a `CLAUDE.md`, a skill bundle, or any single file assembled from many notes, driven from a script or a one-off shell. + +## Design notes + +- **In place, read-only.** Anwesen reads the same directory Obsidian writes to and never writes back. The vault stays editable in Obsidian with no coordination, and there is no write API by design. +- **Frontmatter is the index.** Filtering is server-side and first-class; clients never walk-and-parse. Note *bodies* are served verbatim but not full-text indexed. +- **No authentication.** Anwesen trusts every request it accepts and binds `127.0.0.1` by default. Put a reverse proxy (nginx, caddy, warpgate) in front for TLS and access control. The contract is simple: if you can reach Anwesen, you can read everything it indexes. +- **Standalone.** Anwesen is its own repository with its own release cycle, reusable by any consumer -- not a sub-package of the first thing that used it. + +## Implementation + +Rust (2024 edition) on Tokio: `axum`/`tower` for HTTP, `clap` for the CLI, `tracing` for logs, `serde` (with `serde_yaml` and `serde_json`) for the data model, `notify` for filesystem watching, and BLAKE3 for ETags. The frontmatter index is evaluated in memory; there is no external search engine and no on-disk index. ## License -Dual-licensed under MIT or Apache-2.0 at your option. +BSD 3-Clause. See [LICENSE](LICENSE).