@hawkeyexl/manni 0.0.0-bootstrap.0 → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 manni contributors
+
+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.

package/README.md

@@ -0,0 +1,178 @@
+# manni
+
+One command line for documentation that is meant to be checked. `manni meta`
+validates the **presence and format** of document metadata against **JSON
+Schema**, built for CI. It was published as `docmeta` up to 4.13.1; see
+[Coming from docmeta](#coming-from-docmeta).
+
+[![npm](https://img.shields.io/npm/v/@hawkeyexl/manni?color=cb3837&logo=npm&logoColor=white)](https://www.npmjs.com/package/@hawkeyexl/manni)
+[![CI](https://github.com/hawkeyexl/manni/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/hawkeyexl/manni/actions/workflows/ci.yml)
+[![node](https://img.shields.io/node/v/@hawkeyexl/manni?color=5fa04e&logo=node.js&logoColor=white)](https://nodejs.org)
+[![license](https://img.shields.io/npm/l/@hawkeyexl/manni?color=blue)](LICENSE)
+
+`manni meta` checks the metadata in your documents (Markdown frontmatter and more)
+against one or more JSON Schemas. It verifies that required fields are present
+and correctly formatted: a `type`, an ISO 8601 `timestamp`, a URI `resource`. It
+does not judge prose quality. It ships with 23 [built-in
+schemas](https://hawkeyexl.github.io/manni/meta/reference/built-in-schemas/). They
+cover content vocabularies such as the [Open Knowledge Format
+(OKF)](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md),
+[Diátaxis](https://diataxis.fr/), [The Good Docs
+Project](https://www.thegooddocsproject.dev/template), and the [Seven-Action
+model](https://passo.uno/seven-action-model/). They also cover the front matter
+contracts of site generators such as
+[Docusaurus](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-docs#markdown-front-matter)
+3.10, Hugo, Jekyll, and MkDocs Material. Run `manni meta schemas` for the full
+list. It follows [clig.dev](https://clig.dev) conventions and returns a nonzero
+exit code (plus optional GitHub annotations) when validation fails.
+
+It can also **fill in** the metadata that is missing, so adopting a standard on an existing docset is not a data-entry project.
+
+## Install
+
+```bash
+npm install -g @hawkeyexl/manni
+# or run it without installing:
+npx @hawkeyexl/manni meta validate "**/*.md"
+```
+
+Requires Node.js 24 or later.
+
+## Coming from docmeta?
+
+The metadata tool used to be the whole package. Three things changed:
+
+- **The command.** `docmeta validate …` is now `manni meta validate …`. The
+  package still installs a `docmeta` bin that runs the same program, so
+  existing scripts keep working while you move them.
+- **The config file.** `manni.config.yaml`, shared by every tool in the
+  family, with the metadata tool's keys under `meta:`. A `docmeta.config.yaml`
+  is still read, with a warning.
+- **The GitHub Action.** `uses: hawkeyexl/manni@v0`, same inputs.
+
+Everything else is the same: the exit codes, the output formats, the built-in
+schemas and their published URLs (the old `…/docmeta/schemas/` URLs stay
+served and resolve offline), and the programmatic API.
+
+## Quick start
+
+Point `manni meta validate` at a file, a directory (walked recursively), or a glob. With no `--schema`, it validates against the default set: the built-in OKF schema plus `passo-uno:seven-action:1.0`, which constrains an optional `action` field and requires nothing on its own.
+
+```bash
+manni meta validate docs/intro.md
+```
+
+```text
+✗ docs/intro.md
+    (root)      must have required property 'type'   (line 1)  [google:okf:0.1]
+    /timestamp  must match format "date-time"        (line 9)  [google:okf:0.1]
+
+1 file checked, 0 passed, 1 failed, 0 errors
+```
+
+A clean run exits `0`; validation failures exit `1`; operational errors (no input, unknown schema, parse error) exit `2`.
+
+## Run it in CI
+
+On GitHub Actions, use the packaged action. It sets up Node, pins the CLI, and
+defaults to inline PR annotations:
+
+```yaml
+- uses: actions/checkout@v4
+- uses: hawkeyexl/manni@v0
+  with:
+    paths: "docs/**/*.md"
+```
+
+Every input is in the [Action
+reference](https://hawkeyexl.github.io/manni/meta/reference/action/). Other
+platforms run the CLI directly. The [CI
+recipes](https://hawkeyexl.github.io/manni/meta/ci/recipes/) cover GitLab CI,
+Jenkins, and the rest.
+
+To catch problems before they reach CI, manni meta publishes a
+[pre-commit](https://pre-commit.com/) hook. The whole configuration is three
+lines, and the file-matching pattern is derived from the extensions manni meta
+actually reads rather than hand-written:
+
+```yaml
+repos:
+  - repo: https://github.com/hawkeyexl/manni
+    rev: v0.1.0
+    hooks:
+      - id: manni-meta
+```
+
+## Fill in what's missing
+
+`manni meta fill` infers the metadata properties your schema asks for but a page
+does not carry, and writes back the values it is confident about. It is the
+fast way to clear the backlog on a repo that has never enforced metadata.
+
+```bash
+manni meta fill docs/ --dry-run     # preview; writes nothing
+manni meta fill docs/               # apply
+```
+
+```text
+✓ docs/intro.md
+    /description  A tour of the CLI and its four commands.  0.91
+    below 0.7: /resource 0.38
+
+anthropic/claude-sonnet-4-5 · Threshold 0.7 · 1 file · 1 field written · 1 skipped
+```
+
+Confidence is the last gate, not the only one. A proposal must first satisfy the
+target property's own subschema. It must name a property your schema declares,
+and it must leave the document still valid after the merge. Only then does
+`--confidence` (default `0.7`) apply. Values below it are skipped and reported
+by name. They are never written with a caveat, and the score itself never
+reaches your document.
+
+`fill` writes in place by default, so run it on a clean tree and review the
+diff.
+
+It picks an LLM provider by detecting one. The order is `ANTHROPIC_API_KEY`,
+then `OPENAI_API_KEY`, then a signed-in `claude` CLI, then a local model that
+needs no credentials at all. That means it works with whatever you have, and it
+reports which provider it used. Pass `--provider` to pin one. That is worth
+doing in CI. Left to detect, a runner that loses its key falls back to the local
+model, and downloads it rather than failing the build.
+
+Pass `--local` when the document must not leave the machine. It runs inference
+on-device and **refuses every hosted provider**, a signed-in `claude` CLI
+included. That CLI runs locally, but its inference does not. See the [`fill`
+reference](https://hawkeyexl.github.io/manni/meta/reference/cli/#meta-fill) for every
+flag and for what the local fallback costs.
+
+## Supported formats
+
+Markdown, MDX, AsciiDoc, reStructuredText, XML (including DITA topics and maps),
+and HTML. Run `manni meta schemas` to list the built-in schemas, every supported
+format, and which formats `fill` can write back to.
+
+`fill` writes to all of them. It splices the exact character range of the value
+rather than re-serializing the document. Comments, entity spellings, attribute
+order, indentation, and a DOCTYPE all survive untouched.
+
+## Documentation
+
+Full guides, recipes, and reference live on the documentation site:
+
+**https://hawkeyexl.github.io/manni/meta/**
+
+| Track | What it covers |
+|-------|----------------|
+| [Get started](https://hawkeyexl.github.io/manni/meta/get-started/) | Install and run your first validation. |
+| [Set up validation](https://hawkeyexl.github.io/manni/meta/set-up/) | Stand up validation for a repo: `manni.config.yaml`, per-folder schema overrides. |
+| [Run it in CI](https://hawkeyexl.github.io/manni/meta/ci/) | GitHub Actions and other CI recipes, exit codes, and PR annotations. |
+| [Define & evolve schemas](https://hawkeyexl.github.io/manni/schemas/) | Author a schema, wire up resolution, and version it without breaking the build. |
+| [Reference](https://hawkeyexl.github.io/manni/meta/reference/cli/) | Every CLI flag, Action input, config key, the schema-resolution precedence chain, and output formats. |
+
+## Contributing
+
+Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for dev setup, the test loop, and how to add support for a new input format.
+
+## License
+
+[MIT](LICENSE)