Skip to content

Commit 3998020

Browse files
hyperpolymathclaude
hyperpolymath
and
claude
committed
chore: prepare A2ML/K9 tooling for Pandoc, VS Code, and crates.io submission
- Add homepage and readme fields to a2ml-lsp Cargo.toml - Fix k9-lsp edition 2024->2021, add homepage, add text-editors category - Create PANDOC-SUBMISSION.md for both A2ML and K9 pandoc tooling - Create VS Code marketplace README.md for both extensions Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent 84ad26d commit 3998020

6 files changed

Lines changed: 185 additions & 2 deletions

File tree

‎a2ml/editors/vscode/README.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# A2ML for Visual Studio Code
2+
3+
Syntax highlighting for [A2ML](https://github.com/hyperpolymath/standards/tree/main/a2ml) (Attested Markup Language) — a structured document format for AI agent manifests and project metadata.
4+
5+
## Features
6+
7+
- Syntax highlighting for `.a2ml` files
8+
- Directive recognition (`@abstract`, `@opaque`, `@fig`, `@ref`, `@include`, etc.)
9+
- Section header highlighting (`[metadata]`, `[dependencies]`, etc.)
10+
- Inline formatting (bold, italic, links, code spans)
11+
- Fenced code block support with language annotations
12+
- SPDX license header recognition
13+
14+
## File Associations
15+
16+
| Extension | Language |
17+
|-----------|----------|
18+
| `.a2ml` | A2ML |
19+
20+
## LSP Support
21+
22+
For diagnostics, completions, and hover documentation, install the
23+
[A2ML LSP server](https://github.com/hyperpolymath/standards/tree/main/a2ml/lsp)
24+
and configure the `a2ml.server.path` setting.
25+
26+
## Related
27+
28+
- [A2ML Specification](https://github.com/hyperpolymath/standards/tree/main/a2ml/SPEC-v1.0.adoc)
29+
- [Pandoc Reader/Writer](https://github.com/hyperpolymath/standards/tree/main/a2ml/pandoc)
30+
31+
## License
32+
33+
PMPL-1.0-or-later (Palimpsest License)

‎a2ml/lsp/Cargo.toml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,8 @@ authors = ["Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>"]
1111
license = "PMPL-1.0-or-later"
1212
description = "Language Server Protocol implementation for A2ML"
1313
repository = "https://github.com/hyperpolymath/standards"
14+
homepage = "https://github.com/hyperpolymath/standards/tree/main/a2ml/lsp"
15+
readme = "README.adoc"
1416
keywords = ["a2ml", "lsp", "language-server"]
1517
categories = ["development-tools", "text-editors"]
1618

‎a2ml/pandoc/PANDOC-SUBMISSION.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
# A2ML Pandoc Reader, Writer, and Filter
2+
3+
## Summary
4+
5+
Custom Pandoc reader, writer, and Lua filter for A2ML (Attested Markup Language) — a structured document format for AI agent manifests and project metadata.
6+
7+
A2ML provides a typed, formally verified surface syntax with directives (`@abstract`, `@opaque`, `@fig`, `@ref`, etc.), sections, key-value metadata, and cross-references. This tooling brings full Pandoc ecosystem support: convert A2ML to HTML, PDF, DOCX, Markdown, EPUB, and dozens more formats.
8+
9+
## Components
10+
11+
- **a2ml.lua** — Combined Pandoc custom reader (360 lines). Parses A2ML surface syntax into the Pandoc AST preserving headings, directives, code blocks, inline formatting, and cross-references.
12+
- **a2ml-reader.lua** — Standalone reader variant (189 lines) for simpler use cases.
13+
- **a2ml-writer.lua** — Custom Pandoc writer (153 lines). Converts any Pandoc AST to valid A2ML output, enabling round-trip conversion and cross-format workflows.
14+
- **a2ml-filter.lua** — Post-processing Lua filter with six passes: cross-reference resolution, `@include` directive expansion, TOC generation, diagram rendering (Mermaid/Graphviz), SPDX validation, and git metadata enrichment.
15+
- **a2ml.html** — HTML5 Pandoc template with directive-specific styling (colour-coded borders for `@abstract`, `@opaque`, `@fig`, `@note`, `@warning`), responsive layout, print-friendly output, and syntax highlighting.
16+
17+
## Usage
18+
19+
```sh
20+
# A2ML to HTML (full pipeline)
21+
pandoc -f a2ml.lua input.a2ml \
22+
--lua-filter=a2ml-filter.lua \
23+
--template=a2ml.html \
24+
-o output.html
25+
26+
# A2ML to PDF
27+
pandoc -f a2ml.lua input.a2ml -o output.pdf
28+
29+
# Markdown to A2ML
30+
pandoc input.md -t a2ml-writer.lua -o output.a2ml
31+
```
32+
33+
## Requirements
34+
35+
- Pandoc 3.0+ with Lua support
36+
37+
## Spec
38+
39+
- A2ML v1.0.0: <https://github.com/hyperpolymath/standards/tree/main/a2ml>
40+
- Media type: `application/vnd.a2ml` (IANA registration pending)
41+
42+
## Related
43+
44+
- [pandoc/lua-filters](https://github.com/pandoc/lua-filters) — Community Lua filters repository
45+
- [A2ML LSP server](../lsp/) — Language Server Protocol implementation
46+
- [VS Code extension](../editors/vscode/) — Syntax highlighting for VS Code
47+
- [A2ML specification](../SPEC-v1.0.adoc) — Full language specification
48+
49+
## License
50+
51+
PMPL-1.0-or-later (Palimpsest License)
52+
53+
## Author
54+
55+
Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>

‎k9-svc/editors/vscode/README.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# K9-SVC for Visual Studio Code
2+
3+
Syntax highlighting for [K9](https://github.com/hyperpolymath/standards/tree/main/k9-svc) (Self-Validating Components) — a security-tiered service configuration language built on Nickel.
4+
5+
## Features
6+
7+
- Syntax highlighting for `.k9` and `.k9.ncl` files
8+
- Trust level keyword recognition (Kennel, Yard, Hunt)
9+
- Pedigree field highlighting (`name`, `version`, `description`, `trust_level`)
10+
- Nickel contract annotation colouring (`| Type`)
11+
- Recipe block identification
12+
- SPDX license header recognition
13+
- K9 magic number (`K9!`) detection
14+
15+
## File Associations
16+
17+
| Extension | Language |
18+
|------------|----------|
19+
| `.k9` | K9 |
20+
| `.k9.ncl` | K9 |
21+
22+
## LSP Support
23+
24+
For diagnostics, completions, and hover documentation, install the
25+
[K9 LSP server](https://github.com/hyperpolymath/standards/tree/main/k9-svc/lsp)
26+
and configure the `k9.lsp.path` setting.
27+
28+
## Related
29+
30+
- [K9 Specification](https://github.com/hyperpolymath/standards/tree/main/k9-svc/SPEC.adoc)
31+
- [Pandoc Reader/Writer](https://github.com/hyperpolymath/standards/tree/main/k9-svc/pandoc)
32+
- [Pedigree Contract](https://github.com/hyperpolymath/standards/tree/main/k9-svc/pedigree.ncl)
33+
34+
## License
35+
36+
PMPL-1.0-or-later (Palimpsest License)

‎k9-svc/lsp/Cargo.toml‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,14 +8,15 @@
88
[package]
99
name = "k9-lsp"
1010
version = "0.1.0"
11-
edition = "2024"
11+
edition = "2021"
1212
authors = ["Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>"]
1313
license = "PMPL-1.0-or-later"
1414
description = "Language Server Protocol server for K9 Self-Validating Components"
1515
repository = "https://github.com/hyperpolymath/standards"
16+
homepage = "https://github.com/hyperpolymath/standards/tree/main/k9-svc/lsp"
1617
readme = "README.adoc"
1718
keywords = ["k9", "lsp", "nickel", "svc", "language-server"]
18-
categories = ["development-tools"]
19+
categories = ["development-tools", "text-editors"]
1920

2021
[dependencies]
2122
tower-lsp = "0.20"

‎k9-svc/pandoc/PANDOC-SUBMISSION.md‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
# K9 Pandoc Reader, Writer, and Filter
2+
3+
## Summary
4+
5+
Custom Pandoc reader, writer, and Lua filter for K9 Self-Validating Components — a security-tiered service configuration format built on Nickel, with three trust levels (Kennel, Yard, Hunt) and structured pedigree metadata.
6+
7+
K9 files come in two syntaxes: YAML (`.k9`) for Kennel-level configs and Nickel (`.k9.ncl`) for Yard/Hunt-level components with contracts, recipes, and cryptographic signing. This tooling enables converting K9 documents to HTML, PDF, DOCX, Markdown, and all other Pandoc-supported formats.
8+
9+
## Components
10+
11+
- **k9.lua** — Comprehensive Pandoc custom reader (597 lines). Auto-detects YAML vs Nickel syntax, extracts pedigree metadata, identifies security trust level, and parses records, contracts, recipes, and bindings into the Pandoc AST.
12+
- **k9-reader.lua** — Lightweight reader variant (92 lines) for quick extraction.
13+
- **k9-writer.lua** — Custom Pandoc writer (230 lines). Converts any Pandoc AST to valid K9 Nickel output with pedigree blocks, security settings, recipe definitions, and proper multiline string syntax (`m%"..."%`).
14+
- **k9-filter.lua** — Post-processing Lua filter with four passes: security badge colouring (green/amber/red for trust levels), contract annotation highlighting, recipe command validation (80+ known tools), and pedigree completeness checking.
15+
- **k9.html** — HTML5 Pandoc template with security-level-adaptive header bar, pedigree summary card, contract styling, recipe blocks with labels, copy-to-clipboard on code blocks, and responsive/print-friendly layout.
16+
17+
## Usage
18+
19+
```sh
20+
# K9 Nickel to HTML (full pipeline)
21+
pandoc -f k9.lua input.k9.ncl \
22+
--lua-filter=k9-filter.lua \
23+
--template=k9.html \
24+
-o output.html
25+
26+
# K9 YAML to PDF
27+
pandoc -f k9.lua config.k9 -o output.pdf
28+
29+
# Round-trip: K9 to AST to K9
30+
pandoc -f k9.lua input.k9.ncl -t k9-writer.lua -o roundtrip.k9.ncl
31+
```
32+
33+
## Requirements
34+
35+
- Pandoc 3.0+ with Lua support
36+
37+
## Spec
38+
39+
- K9 SVC specification: <https://github.com/hyperpolymath/standards/tree/main/k9-svc>
40+
- Media type: `application/vnd.k9+nickel` (IANA registration pending)
41+
42+
## Related
43+
44+
- [pandoc/lua-filters](https://github.com/pandoc/lua-filters) — Community Lua filters repository
45+
- [K9 LSP server](../lsp/) — Language Server Protocol implementation
46+
- [VS Code extension](../editors/vscode/) — Syntax highlighting for VS Code
47+
- [K9 specification](../SPEC.adoc) — Full K9 SVC specification
48+
- [Pedigree contract](../pedigree.ncl) — Nickel contract defining component structure
49+
50+
## License
51+
52+
PMPL-1.0-or-later (Palimpsest License)
53+
54+
## Author
55+
56+
Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>

0 commit comments

Comments
 (0)