somnus-metadata 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (61) hide show
  1. somnus_metadata-0.1.0/MANIFEST.in +19 -0
  2. somnus_metadata-0.1.0/PKG-INFO +82 -0
  3. somnus_metadata-0.1.0/README.md +70 -0
  4. somnus_metadata-0.1.0/pyproject.toml +39 -0
  5. somnus_metadata-0.1.0/setup.cfg +4 -0
  6. somnus_metadata-0.1.0/src/somnus/__init__.py +9 -0
  7. somnus_metadata-0.1.0/src/somnus/__main__.py +8 -0
  8. somnus_metadata-0.1.0/src/somnus/carriers/__init__.py +167 -0
  9. somnus_metadata-0.1.0/src/somnus/carriers/blockcomment.py +105 -0
  10. somnus_metadata-0.1.0/src/somnus/carriers/linecomment.py +109 -0
  11. somnus_metadata-0.1.0/src/somnus/carriers/markdown.py +106 -0
  12. somnus_metadata-0.1.0/src/somnus/carriers/sidecar.py +73 -0
  13. somnus_metadata-0.1.0/src/somnus/cli.py +169 -0
  14. somnus_metadata-0.1.0/src/somnus/commands/__init__.py +1 -0
  15. somnus_metadata-0.1.0/src/somnus/commands/_common.py +300 -0
  16. somnus_metadata-0.1.0/src/somnus/commands/brief.py +50 -0
  17. somnus_metadata-0.1.0/src/somnus/commands/bump.py +23 -0
  18. somnus_metadata-0.1.0/src/somnus/commands/check.py +48 -0
  19. somnus_metadata-0.1.0/src/somnus/commands/edit.py +18 -0
  20. somnus_metadata-0.1.0/src/somnus/commands/fork.py +89 -0
  21. somnus_metadata-0.1.0/src/somnus/commands/index.py +22 -0
  22. somnus_metadata-0.1.0/src/somnus/commands/init.py +41 -0
  23. somnus_metadata-0.1.0/src/somnus/commands/ls.py +20 -0
  24. somnus_metadata-0.1.0/src/somnus/commands/mcp.py +12 -0
  25. somnus_metadata-0.1.0/src/somnus/commands/migrate.py +406 -0
  26. somnus_metadata-0.1.0/src/somnus/commands/new.py +44 -0
  27. somnus_metadata-0.1.0/src/somnus/commands/query.py +28 -0
  28. somnus_metadata-0.1.0/src/somnus/commands/regions.py +57 -0
  29. somnus_metadata-0.1.0/src/somnus/commands/schema.py +85 -0
  30. somnus_metadata-0.1.0/src/somnus/commands/set_fields.py +52 -0
  31. somnus_metadata-0.1.0/src/somnus/commands/stale.py +67 -0
  32. somnus_metadata-0.1.0/src/somnus/commands/stamp.py +56 -0
  33. somnus_metadata-0.1.0/src/somnus/commands/status.py +36 -0
  34. somnus_metadata-0.1.0/src/somnus/config.py +176 -0
  35. somnus_metadata-0.1.0/src/somnus/db/__init__.py +5 -0
  36. somnus_metadata-0.1.0/src/somnus/db/schema.sql +175 -0
  37. somnus_metadata-0.1.0/src/somnus/db/store.py +682 -0
  38. somnus_metadata-0.1.0/src/somnus/document.py +334 -0
  39. somnus_metadata-0.1.0/src/somnus/ids.py +130 -0
  40. somnus_metadata-0.1.0/src/somnus/infer.py +145 -0
  41. somnus_metadata-0.1.0/src/somnus/mcp.py +304 -0
  42. somnus_metadata-0.1.0/src/somnus/model/__init__.py +1 -0
  43. somnus_metadata-0.1.0/src/somnus/model/jsonschema_export.py +122 -0
  44. somnus_metadata-0.1.0/src/somnus/model/lifecycle.py +114 -0
  45. somnus_metadata-0.1.0/src/somnus/model/schema.py +601 -0
  46. somnus_metadata-0.1.0/src/somnus/model/validate.py +844 -0
  47. somnus_metadata-0.1.0/src/somnus/model/vocab.py +75 -0
  48. somnus_metadata-0.1.0/src/somnus/output.py +92 -0
  49. somnus_metadata-0.1.0/src/somnus/regions.py +210 -0
  50. somnus_metadata-0.1.0/src/somnus/tui/__init__.py +1 -0
  51. somnus_metadata-0.1.0/src/somnus/tui/app.py +411 -0
  52. somnus_metadata-0.1.0/src/somnus/tui/form.py +162 -0
  53. somnus_metadata-0.1.0/src/somnus/tui/term.py +297 -0
  54. somnus_metadata-0.1.0/src/somnus/tui/widgets.py +350 -0
  55. somnus_metadata-0.1.0/src/somnus/yamlsub.py +759 -0
  56. somnus_metadata-0.1.0/src/somnus_metadata.egg-info/PKG-INFO +82 -0
  57. somnus_metadata-0.1.0/src/somnus_metadata.egg-info/SOURCES.txt +59 -0
  58. somnus_metadata-0.1.0/src/somnus_metadata.egg-info/dependency_links.txt +1 -0
  59. somnus_metadata-0.1.0/src/somnus_metadata.egg-info/entry_points.txt +2 -0
  60. somnus_metadata-0.1.0/src/somnus_metadata.egg-info/requires.txt +3 -0
  61. somnus_metadata-0.1.0/src/somnus_metadata.egg-info/top_level.txt +1 -0
@@ -0,0 +1,19 @@
1
+ # Publish the toolkit, not the operator workspace or private research.
2
+ include pyproject.toml README.md
3
+ recursive-include src/somnus *.py *.sql
4
+ prune tests
5
+ prune archive
6
+ prune archives
7
+ prune docs
8
+ prune droid-wiki
9
+ prune runbooks
10
+ prune .codex
11
+ prune .claude
12
+ prune .factory
13
+ prune .github
14
+ prune .somnus-debug
15
+ prune .python_doctor
16
+ prune .python_doctor-src
17
+ exclude AGENTS*.md CONTEXT.md PLAN.md DECISIONS.md SPEC.md CONTRIBUTING.md
18
+ exclude last-session.txt workflows.md raw-tree.md production_doctor.log
19
+ global-exclude __pycache__ *.py[cod] .coverage .env .env.*
@@ -0,0 +1,82 @@
1
+ Metadata-Version: 2.4
2
+ Name: somnus-metadata
3
+ Version: 0.1.0
4
+ Summary: Universal semantic metadata standard and engineering toolkit
5
+ Project-URL: Repository, https://github.com/calisweetleaf/somnus-metadata
6
+ Project-URL: Issues, https://github.com/calisweetleaf/somnus-metadata/issues
7
+ Keywords: metadata,markdown,cli,mcp,sqlite
8
+ Requires-Python: >=3.11
9
+ Description-Content-Type: text/markdown
10
+ Provides-Extra: dev
11
+ Requires-Dist: mypy>=1.9; extra == "dev"
12
+
13
+ # somnus-metadata
14
+
15
+ The Somnus metadata standard (core `somnus://metadata/core/2.0.0`) and its stdlib-only toolkit.
16
+
17
+ Every managed file carries exactly one `somnus:` header. Markdown files use frontmatter or a hidden
18
+ comment envelope. Code and config files use a comment envelope. All other files use a
19
+ `<file>.somnus.yaml` sidecar. A global SQLite registry (`~/.somnus/somnus.db`) indexes identity,
20
+ revisions, relations, claims, and conflicts. It contains no JSON.
21
+
22
+ - Normative specification: [SPEC.md](SPEC.md)
23
+ - Ratified decisions: [DECISIONS.md](DECISIONS.md)
24
+ - Historical material (not normative): [archive/](archive/README.md)
25
+
26
+ ## Install
27
+
28
+ Requires Python 3.11+ and has no third-party dependencies.
29
+
30
+ ```sh
31
+ uv tool install somnus-metadata
32
+ somnus --version
33
+ ```
34
+
35
+ Alternatively, use `pipx install somnus-metadata`. For a Python virtual
36
+ environment, use `python -m pip install somnus-metadata`.
37
+
38
+ The distribution is **somnus-metadata**; the command and Python import remain
39
+ **somnus**. Do not install the unrelated PyPI distribution named `somnus` into
40
+ this same environment: it owns the same command/import names.
41
+
42
+ For development from a source checkout, use `uv tool install --editable .`.
43
+ The installed tool works outside this repository; register the project roots you
44
+ want to manage with `somnus init --root /path/to/project`.
45
+
46
+ Package release 0.1.0 implements metadata core 2.0.0. These are separate versions.
47
+ The CLI, terminal UI and stdio MCP adapter share one backend. A distributable
48
+ coding-agent plugin is not included in this release.
49
+
50
+ ## Quick start
51
+
52
+ ```
53
+ somnus init --root . # create ~/.somnus, config.toml, registry; register this root
54
+ somnus new specification "My Spec" # scaffold a conformant Markdown artifact
55
+ somnus check my-spec.md --level semantic
56
+ somnus stamp notes.py # dry-run diff; add --write to apply
57
+ somnus index # reconcile roots into the registry
58
+ somnus ls
59
+ somnus q --conflicts
60
+ somnus set my-spec.md "classification.tags=memory, design" # header edit, new revision
61
+ somnus edit # terminal UI
62
+ ```
63
+
64
+ `somnus brief` prints an agent cheat sheet suitable for pasting into a repository's `AGENTS.md`.
65
+
66
+ ## MCP server
67
+
68
+ `somnus mcp` serves non-interactive commands (excluding `edit` and `mcp` itself)
69
+ as Model Context Protocol tools over stdio.
70
+ Each tool returns the command's text output. Register it with any MCP client by command:
71
+
72
+ ```
73
+ somnus mcp # optional: somnus --actor NAME mcp
74
+ ```
75
+
76
+ Exit codes: `0` ok, `1` validation errors, refusals, or conflicts, `2` usage or I/O errors.
77
+
78
+ ## Tests
79
+
80
+ ```
81
+ PYTHONPATH=src python -m unittest discover -s tests
82
+ ```
@@ -0,0 +1,70 @@
1
+ # somnus-metadata
2
+
3
+ The Somnus metadata standard (core `somnus://metadata/core/2.0.0`) and its stdlib-only toolkit.
4
+
5
+ Every managed file carries exactly one `somnus:` header. Markdown files use frontmatter or a hidden
6
+ comment envelope. Code and config files use a comment envelope. All other files use a
7
+ `<file>.somnus.yaml` sidecar. A global SQLite registry (`~/.somnus/somnus.db`) indexes identity,
8
+ revisions, relations, claims, and conflicts. It contains no JSON.
9
+
10
+ - Normative specification: [SPEC.md](SPEC.md)
11
+ - Ratified decisions: [DECISIONS.md](DECISIONS.md)
12
+ - Historical material (not normative): [archive/](archive/README.md)
13
+
14
+ ## Install
15
+
16
+ Requires Python 3.11+ and has no third-party dependencies.
17
+
18
+ ```sh
19
+ uv tool install somnus-metadata
20
+ somnus --version
21
+ ```
22
+
23
+ Alternatively, use `pipx install somnus-metadata`. For a Python virtual
24
+ environment, use `python -m pip install somnus-metadata`.
25
+
26
+ The distribution is **somnus-metadata**; the command and Python import remain
27
+ **somnus**. Do not install the unrelated PyPI distribution named `somnus` into
28
+ this same environment: it owns the same command/import names.
29
+
30
+ For development from a source checkout, use `uv tool install --editable .`.
31
+ The installed tool works outside this repository; register the project roots you
32
+ want to manage with `somnus init --root /path/to/project`.
33
+
34
+ Package release 0.1.0 implements metadata core 2.0.0. These are separate versions.
35
+ The CLI, terminal UI and stdio MCP adapter share one backend. A distributable
36
+ coding-agent plugin is not included in this release.
37
+
38
+ ## Quick start
39
+
40
+ ```
41
+ somnus init --root . # create ~/.somnus, config.toml, registry; register this root
42
+ somnus new specification "My Spec" # scaffold a conformant Markdown artifact
43
+ somnus check my-spec.md --level semantic
44
+ somnus stamp notes.py # dry-run diff; add --write to apply
45
+ somnus index # reconcile roots into the registry
46
+ somnus ls
47
+ somnus q --conflicts
48
+ somnus set my-spec.md "classification.tags=memory, design" # header edit, new revision
49
+ somnus edit # terminal UI
50
+ ```
51
+
52
+ `somnus brief` prints an agent cheat sheet suitable for pasting into a repository's `AGENTS.md`.
53
+
54
+ ## MCP server
55
+
56
+ `somnus mcp` serves non-interactive commands (excluding `edit` and `mcp` itself)
57
+ as Model Context Protocol tools over stdio.
58
+ Each tool returns the command's text output. Register it with any MCP client by command:
59
+
60
+ ```
61
+ somnus mcp # optional: somnus --actor NAME mcp
62
+ ```
63
+
64
+ Exit codes: `0` ok, `1` validation errors, refusals, or conflicts, `2` usage or I/O errors.
65
+
66
+ ## Tests
67
+
68
+ ```
69
+ PYTHONPATH=src python -m unittest discover -s tests
70
+ ```
@@ -0,0 +1,39 @@
1
+ [build-system]
2
+ requires = ["setuptools>=68.0.0"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "somnus-metadata"
7
+ version = "0.1.0"
8
+ description = "Universal semantic metadata standard and engineering toolkit"
9
+ readme = "README.md"
10
+ requires-python = ">=3.11"
11
+ dependencies = []
12
+
13
+ keywords = ["metadata", "markdown", "cli", "mcp", "sqlite"]
14
+
15
+ [project.urls]
16
+ Repository = "https://github.com/calisweetleaf/somnus-metadata"
17
+ Issues = "https://github.com/calisweetleaf/somnus-metadata/issues"
18
+
19
+ [project.scripts]
20
+ somnus = "somnus.cli:main"
21
+
22
+ [project.optional-dependencies]
23
+ dev = ["mypy>=1.9"]
24
+
25
+ [tool.mypy]
26
+ python_version = "3.11"
27
+ mypy_path = "src"
28
+ files = ["src/somnus"]
29
+ check_untyped_defs = true
30
+ no_implicit_optional = true
31
+ warn_redundant_casts = true
32
+ warn_unused_ignores = true
33
+ warn_return_any = true
34
+
35
+ [tool.setuptools.packages.find]
36
+ where = ["src"]
37
+
38
+ [tool.setuptools.package-data]
39
+ "somnus.db" = ["schema.sql"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,9 @@
1
+ """Somnus metadata system: schema constants and package version."""
2
+
3
+ __version__ = "0.1.0"
4
+
5
+ CORE_SCHEMA = "somnus://metadata/core/2.0.0"
6
+ SPEC_PROFILE = "somnus://metadata/profile/specification/1.0.0"
7
+ BENCHMARK_PROFILE = "somnus://metadata/profile/benchmark/1.0.0"
8
+ MIGRATION_EXTENSION = "somnus://metadata/extension/migration-v0.1/1.0.0"
9
+ DB_USER_VERSION = 1
@@ -0,0 +1,8 @@
1
+ """Module entry point so `python -m somnus` behaves like the `somnus` script."""
2
+
3
+ import sys
4
+
5
+ from somnus.cli import main
6
+
7
+ if __name__ == "__main__":
8
+ sys.exit(main())
@@ -0,0 +1,167 @@
1
+ """Carrier protocol, registry, and extension-based auto-detection (SPEC §17).
2
+
3
+ A carrier works on a file's lines (without line endings). ``extract`` finds
4
+ the single authoritative envelope; ``render`` returns a splice that replaces
5
+ or inserts the envelope without touching any other line.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ from dataclasses import dataclass, field
11
+ from pathlib import Path
12
+ from typing import Optional, Protocol
13
+
14
+ SIDECAR_SUFFIX = ".somnus.yaml"
15
+
16
+
17
+ @dataclass
18
+ class Envelope:
19
+ """Location of an envelope inside a file's lines (0-based, end exclusive)."""
20
+
21
+ kind: str
22
+ start: int
23
+ end: int
24
+ payload_lines: list[str]
25
+ payload_start: int # 0-based file line of the first payload line
26
+ col_offset: int = 0 # characters stripped from each payload line (prefix width)
27
+ mask_start: int = -1 # region scanning ignores [mask_start, mask_end)
28
+ mask_end: int = -1
29
+
30
+ def __post_init__(self) -> None:
31
+ if self.mask_start < 0:
32
+ self.mask_start, self.mask_end = self.start, self.end
33
+
34
+ @property
35
+ def payload(self) -> str:
36
+ """Payload YAML text with a trailing newline."""
37
+ return "\n".join(self.payload_lines) + "\n"
38
+
39
+
40
+ @dataclass
41
+ class Issue:
42
+ """Carrier-level problem at a 1-based file position."""
43
+
44
+ line: int
45
+ col: int
46
+ code: str
47
+ message: str
48
+
49
+
50
+ @dataclass
51
+ class Extraction:
52
+ """Result of envelope extraction."""
53
+
54
+ envelope: Optional[Envelope] = None
55
+ issues: list[Issue] = field(default_factory=list)
56
+
57
+
58
+ @dataclass
59
+ class Splice:
60
+ """Replace ``lines[start:end]`` with ``new_lines``."""
61
+
62
+ start: int
63
+ end: int
64
+ new_lines: list[str]
65
+
66
+
67
+ class Carrier(Protocol):
68
+ """Interface implemented by every carrier."""
69
+
70
+ name: str
71
+ capability: str
72
+ forbid: Optional[str]
73
+ region_style: tuple
74
+
75
+ def extract(self, lines: list[str]) -> Extraction:
76
+ """Locate the envelope."""
77
+ ...
78
+
79
+ def render(self, lines: list[str], payload: str, envelope: Optional[Envelope], style: Optional[str] = None) -> Splice:
80
+ """Return the splice that writes ``payload`` into the file."""
81
+ ...
82
+
83
+
84
+ class CarrierError(ValueError):
85
+ """The carrier cannot place the envelope without altering host semantics."""
86
+
87
+ def __init__(self, code: str, message: str, line: int = 1):
88
+ self.code = code
89
+ self.line = line
90
+ super().__init__(message)
91
+
92
+
93
+ def _registry() -> dict[str, Carrier]:
94
+ from somnus.carriers.blockcomment import CSS, XML
95
+ from somnus.carriers.linecomment import HashCarrier, LineCarrier
96
+ from somnus.carriers.markdown import MarkdownCarrier
97
+
98
+ return {
99
+ "markdown": MarkdownCarrier(),
100
+ "python": HashCarrier("python"),
101
+ "shell": HashCarrier("shell"),
102
+ "powershell": HashCarrier("powershell"),
103
+ "r": HashCarrier("r"),
104
+ "toml": HashCarrier("toml"),
105
+ "yaml": HashCarrier("yaml"),
106
+ "tex": LineCarrier("tex", "% ", "somnus-adapter-tex@1", "tex"),
107
+ "slash": LineCarrier("slash", "// ", "somnus-adapter-slash-comment@1", "slash"),
108
+ "js": LineCarrier("js", "// ", "somnus-adapter-slash-comment@1", "js"),
109
+ "sql": LineCarrier("sql", "-- ", "somnus-adapter-sql-comment@1", "sql"),
110
+ "css": CSS,
111
+ "xml": XML,
112
+ }
113
+
114
+
115
+ EXTENSIONS: dict[str, str] = {
116
+ ".md": "markdown", ".markdown": "markdown", ".mdx": "markdown",
117
+ ".py": "python", ".pyw": "python",
118
+ ".sh": "shell", ".bash": "shell", ".zsh": "shell",
119
+ ".ps1": "powershell", ".psm1": "powershell", ".psd1": "powershell",
120
+ ".r": "r",
121
+ ".toml": "toml", ".yaml": "yaml", ".yml": "yaml",
122
+ ".tex": "tex", ".sty": "tex", ".cls": "tex", ".ltx": "tex",
123
+ ".js": "js", ".mjs": "js", ".cjs": "js", ".jsx": "js", ".ts": "js", ".tsx": "js",
124
+ ".rs": "slash", ".c": "slash", ".h": "slash", ".cc": "slash", ".cpp": "slash", ".hpp": "slash",
125
+ ".go": "slash", ".java": "slash", ".kt": "slash", ".swift": "slash", ".cs": "slash",
126
+ ".sql": "sql",
127
+ ".css": "css", ".scss": "css", ".less": "css",
128
+ ".html": "xml", ".htm": "xml", ".xhtml": "xml", ".xml": "xml", ".svg": "xml",
129
+ }
130
+
131
+ _CACHE: dict[str, Carrier] = {}
132
+
133
+
134
+ def get(name: str) -> Carrier:
135
+ """Return the carrier registered under ``name``."""
136
+ if not _CACHE:
137
+ _CACHE.update(_registry())
138
+ return _CACHE[name]
139
+
140
+
141
+ def is_sidecar_path(path: Path) -> bool:
142
+ """Return True for ``*.somnus.yaml`` sidecar files."""
143
+ return path.name.endswith(SIDECAR_SUFFIX)
144
+
145
+
146
+ def sidecar_for(path: Path) -> Path:
147
+ """Return the sidecar path for a host file."""
148
+ return path.with_name(path.name + SIDECAR_SUFFIX)
149
+
150
+
151
+ def host_for(sidecar: Path) -> Path:
152
+ """Return the host path a sidecar file describes by name."""
153
+ return sidecar.with_name(sidecar.name[: -len(SIDECAR_SUFFIX)])
154
+
155
+
156
+ def carrier_name_for(path: Path) -> Optional[str]:
157
+ """Return the embedded carrier name for a path, or None when a sidecar is required."""
158
+ if is_sidecar_path(path):
159
+ return None
160
+ suffix = path.suffix if path.suffix in EXTENSIONS else path.suffix.lower()
161
+ return EXTENSIONS.get(suffix)
162
+
163
+
164
+ def for_path(path: Path) -> Optional[Carrier]:
165
+ """Return the embedded carrier for a path, or None when a sidecar is required."""
166
+ name = carrier_name_for(path)
167
+ return get(name) if name else None
@@ -0,0 +1,105 @@
1
+ """Block-comment carriers: CSS ``/* */`` and XML/HTML/SVG ``<!-- -->`` (SPEC §17.4–§17.5)."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import re
6
+ from typing import Optional
7
+
8
+ from somnus.carriers import CarrierError, Envelope, Extraction, Issue, Splice
9
+
10
+ _CHARSET = re.compile(r'^@charset "[^"]*";\s*$')
11
+
12
+
13
+ class BlockCarrier:
14
+ """Envelope delimited by a block-comment opener and closer line."""
15
+
16
+ def __init__(self, name: str, opener: str, closer: str, forbidden: str, forbid: str, region_style: tuple):
17
+ self.name = name
18
+ self.capability = "somnus-adapter-block-comment@1"
19
+ self.opener = opener
20
+ self.closer = closer
21
+ self.forbidden = forbidden
22
+ self.forbid: Optional[str] = forbid
23
+ self.region_style = region_style
24
+
25
+ def preamble_end(self, lines: list[str]) -> int:
26
+ """Return the index after the host's mandatory leading declarations."""
27
+ i = 0
28
+ if self.name == "css":
29
+ if lines and lines[0].startswith("@charset"):
30
+ if not _CHARSET.match(lines[0]):
31
+ raise CarrierError("E_HOST", "@charset declaration must be alone on the first line", 1)
32
+ i = 1
33
+ return i
34
+ while i < len(lines):
35
+ stripped = lines[i].lstrip()
36
+ if stripped.startswith("<?xml"):
37
+ if "?>" not in stripped:
38
+ raise CarrierError("E_HOST", "multi-line XML declaration cannot be preserved safely", i + 1)
39
+ i += 1
40
+ elif stripped[:9].upper() == "<!DOCTYPE":
41
+ if ">" not in stripped:
42
+ raise CarrierError("E_HOST", "multi-line DOCTYPE cannot be preserved safely", i + 1)
43
+ i += 1
44
+ else:
45
+ break
46
+ return i
47
+
48
+ def _skippable(self, line: str) -> bool:
49
+ s = line.strip()
50
+ if not s:
51
+ return True
52
+ if self.name == "xml":
53
+ return s.startswith("<!--") and s.endswith("-->") and s != self.opener
54
+ return s.startswith("/*") and s.endswith("*/") and s != self.opener
55
+
56
+ def extract(self, lines: list[str]) -> Extraction:
57
+ """Scan the leading area (after declarations) for one envelope."""
58
+ result = Extraction()
59
+ try:
60
+ i = self.preamble_end(lines)
61
+ except CarrierError:
62
+ i = 0
63
+ found: list[Envelope] = []
64
+ n = len(lines)
65
+ while i < n:
66
+ if lines[i].rstrip() == self.opener:
67
+ j = i + 1
68
+ while j < n and lines[j].rstrip() != self.closer:
69
+ j += 1
70
+ if j >= n:
71
+ result.issues.append(Issue(i + 1, 1, "E_ENVELOPE", "metadata envelope is never closed"))
72
+ break
73
+ payload = lines[i + 1 : j]
74
+ for k, text in enumerate(payload):
75
+ if self.forbidden in text:
76
+ result.issues.append(Issue(i + 2 + k, text.index(self.forbidden) + 1, "E_ENVELOPE",
77
+ f"{self.forbidden!r} is forbidden inside this envelope"))
78
+ found.append(Envelope(self.name, i, j + 1, payload, i + 1))
79
+ i = j + 1
80
+ continue
81
+ if self._skippable(lines[i]):
82
+ i += 1
83
+ continue
84
+ break
85
+ for extra in found[1:]:
86
+ result.issues.append(Issue(extra.start + 1, 1, "E_ENVELOPE", "more than one metadata envelope"))
87
+ if found:
88
+ result.envelope = found[0]
89
+ return result
90
+
91
+ def render(self, lines: list[str], payload: str, envelope: Optional[Envelope], style: Optional[str] = None) -> Splice:
92
+ """Replace the envelope, or insert it after the leading declarations."""
93
+ body = payload.rstrip("\n").split("\n")
94
+ for k, text in enumerate(body):
95
+ if self.forbidden in text:
96
+ raise CarrierError("E_HOST", f"payload contains {self.forbidden!r}; use a sidecar", k + 1)
97
+ block = [self.opener, *body, self.closer]
98
+ if envelope is not None:
99
+ return Splice(envelope.start, envelope.end, block)
100
+ at = self.preamble_end(lines)
101
+ return Splice(at, at, block)
102
+
103
+
104
+ CSS = BlockCarrier("css", "/* somnus:metadata:v2", "somnus:end */", "*/", "block", ("block", "/* ", " */"))
105
+ XML = BlockCarrier("xml", "<!-- somnus:metadata:v2", "somnus:end -->", "--", "html", ("markdown",))
@@ -0,0 +1,109 @@
1
+ """Comment-prefixed carriers: ``# ``, ``% ``, ``// ``, ``-- `` (SPEC §17.3, §17.5)."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import re
6
+ from typing import Optional
7
+
8
+ from somnus.carriers import Envelope, Extraction, Issue, Splice
9
+
10
+ _COOKIE = re.compile(r"^[ \t\f]*#.*?coding[:=][ \t]*[-\w.]+")
11
+ _REQUIRES = re.compile(r"^#requires\b", re.IGNORECASE)
12
+ _TEX_MAGIC = re.compile(r"^%\s*!tex\b", re.IGNORECASE)
13
+
14
+
15
+ def preamble_end(host: str, lines: list[str]) -> int:
16
+ """Return the index of the first line after mandatory host preamble lines."""
17
+ i = 0
18
+ n = len(lines)
19
+ if host in ("python", "shell", "r", "js", "powershell") and n and lines[0].startswith("#!"):
20
+ i = 1
21
+ if host == "python":
22
+ if i == 0 and n and _COOKIE.match(lines[0]):
23
+ i = 1
24
+ elif n > 1 and lines[0].lstrip().startswith("#") and _COOKIE.match(lines[1]):
25
+ i = 2
26
+ elif host == "powershell":
27
+ while i < n and _REQUIRES.match(lines[i]):
28
+ i += 1
29
+ elif host == "tex":
30
+ while i < n and _TEX_MAGIC.match(lines[i]):
31
+ i += 1
32
+ return i
33
+
34
+
35
+ class LineCarrier:
36
+ """Envelope made of prefixed comment lines in the host's leading comment area."""
37
+
38
+ forbid: Optional[str] = None
39
+
40
+ def __init__(self, host: str, prefix: str, capability: str, name: Optional[str] = None):
41
+ self.host = host
42
+ self.prefix = prefix
43
+ self.bare = prefix.rstrip()
44
+ self.capability = capability
45
+ self.name = name or host
46
+ self.opener = f"{prefix}somnus:metadata:v2"
47
+ self.closer = f"{prefix}somnus:end"
48
+ self.region_style = ("prefix", prefix)
49
+
50
+ def _is_comment(self, line: str) -> bool:
51
+ return line.lstrip().startswith(self.bare)
52
+
53
+ def extract(self, lines: list[str]) -> Extraction:
54
+ """Scan the leading comment area for exactly one envelope."""
55
+ result = Extraction()
56
+ found: list[Envelope] = []
57
+ i = preamble_end(self.host, lines)
58
+ n = len(lines)
59
+ while i < n:
60
+ line = lines[i]
61
+ if line.rstrip() == self.opener.rstrip():
62
+ j = i + 1
63
+ payload: list[str] = []
64
+ ok = True
65
+ while j < n and lines[j].rstrip() != self.closer.rstrip():
66
+ text = lines[j]
67
+ if text.rstrip() == self.bare:
68
+ payload.append("")
69
+ elif text.startswith(self.prefix):
70
+ payload.append(text[len(self.prefix):])
71
+ else:
72
+ result.issues.append(Issue(j + 1, 1, "E_ENVELOPE",
73
+ f"envelope line must start with {self.prefix!r}"))
74
+ ok = False
75
+ break
76
+ j += 1
77
+ if ok and j >= n:
78
+ result.issues.append(Issue(i + 1, 1, "E_ENVELOPE", "metadata envelope is never closed"))
79
+ break
80
+ if not ok:
81
+ break
82
+ found.append(Envelope(self.name, i, j + 1, payload, i + 1, len(self.prefix)))
83
+ i = j + 1
84
+ continue
85
+ if not line.strip() or self._is_comment(line):
86
+ i += 1
87
+ continue
88
+ break
89
+ for extra in found[1:]:
90
+ result.issues.append(Issue(extra.start + 1, 1, "E_ENVELOPE", "more than one metadata envelope"))
91
+ if found:
92
+ result.envelope = found[0]
93
+ return result
94
+
95
+ def render(self, lines: list[str], payload: str, envelope: Optional[Envelope], style: Optional[str] = None) -> Splice:
96
+ """Replace the envelope, or insert it right after the mandatory preamble."""
97
+ body = [self.prefix + ln if ln else self.prefix for ln in payload.rstrip("\n").split("\n")]
98
+ block = [self.opener, *body, self.closer]
99
+ if envelope is not None:
100
+ return Splice(envelope.start, envelope.end, block)
101
+ at = preamble_end(self.host, lines)
102
+ return Splice(at, at, block)
103
+
104
+
105
+ class HashCarrier(LineCarrier):
106
+ """``# `` carrier for Python, shell, PowerShell, R, TOML, and YAML hosts."""
107
+
108
+ def __init__(self, host: str):
109
+ super().__init__(host, "# ", "somnus-adapter-hash-comment@1", host)