trigrams-toolkit 0.1.0__py3-none-any.whl
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.
- trigrams_toolkit/__init__.py +1 -0
- trigrams_toolkit/handbook/__init__.py +6 -0
- trigrams_toolkit/handbook/cli.py +122 -0
- trigrams_toolkit/handbook/guide_headers.py +43 -0
- trigrams_toolkit/handbook/guides.py +141 -0
- trigrams_toolkit/handbook/location.py +79 -0
- trigrams_toolkit/handbook/model.py +4 -0
- trigrams_toolkit/handbook/package.py +165 -0
- trigrams_toolkit/handbook/principle_import.py +101 -0
- trigrams_toolkit/handbook/project_resources.py +80 -0
- trigrams_toolkit/handbook/skill_sources.py +59 -0
- trigrams_toolkit/handbook/source_catalog.py +55 -0
- trigrams_toolkit/handbook/sources.py +16 -0
- trigrams_toolkit/installation/__init__.py +0 -0
- trigrams_toolkit/installation/archive_project.py +50 -0
- trigrams_toolkit/installation/global_skills.py +45 -0
- trigrams_toolkit/installation/harness_install.py +89 -0
- trigrams_toolkit/installation/installation_candidate.py +135 -0
- trigrams_toolkit/installation/installation_help.py +49 -0
- trigrams_toolkit/installation/installation_materials.py +73 -0
- trigrams_toolkit/installation/installation_service.py +14 -0
- trigrams_toolkit/installation/installation_sources.py +34 -0
- trigrams_toolkit/installation/operation_files.py +94 -0
- trigrams_toolkit/installation/operation_runtime.py +144 -0
- trigrams_toolkit/installation/package_metadata.py +48 -0
- trigrams_toolkit/plan/__init__.py +5 -0
- trigrams_toolkit/plan/cli.py +136 -0
- trigrams_toolkit/plan/definitions.py +131 -0
- trigrams_toolkit/plan/model.py +61 -0
- trigrams_toolkit/plan/scheduling.py +126 -0
- trigrams_toolkit/plan/service.py +139 -0
- trigrams_toolkit/plan/state.py +146 -0
- trigrams_toolkit/project_context/__init__.py +16 -0
- trigrams_toolkit/project_context/paths.py +36 -0
- trigrams_toolkit/py.typed +0 -0
- trigrams_toolkit/resources/__init__.py +35 -0
- trigrams_toolkit/resources/adapters/claude/README.md +7 -0
- trigrams_toolkit/resources/adapters/claude/evaluator.md +7 -0
- trigrams_toolkit/resources/adapters/claude/task_developer.md +7 -0
- trigrams_toolkit/resources/adapters/codex/README.md +9 -0
- trigrams_toolkit/resources/adapters/codex/evaluator.toml +6 -0
- trigrams_toolkit/resources/adapters/codex/task_developer.toml +6 -0
- trigrams_toolkit/resources/adapters/pi-web/evaluator.md +7 -0
- trigrams_toolkit/resources/adapters/pi-web/task_developer.md +7 -0
- trigrams_toolkit/resources/handbook/PROTOCOL.md +82 -0
- trigrams_toolkit/resources/handbook/README.md +45 -0
- trigrams_toolkit/resources/handbook/commands.json +31 -0
- trigrams_toolkit/resources/handbook/guides.schema.json +253 -0
- trigrams_toolkit/resources/installation/PROTOCOL.md +35 -0
- trigrams_toolkit/resources/installation/cli.schema.json +89 -0
- trigrams_toolkit/resources/installation/commands.json +23 -0
- trigrams_toolkit/resources/installation/examples/install-apply-input.json +48 -0
- trigrams_toolkit/resources/installation/examples/install-preview-input.json +7 -0
- trigrams_toolkit/resources/installation/examples/installation.json +20 -0
- trigrams_toolkit/resources/installation/global-skills.json +6 -0
- trigrams_toolkit/resources/installation/installation.schema.json +295 -0
- trigrams_toolkit/resources/plan/PROTOCOL.md +89 -0
- trigrams_toolkit/resources/plan/README.md +61 -0
- trigrams_toolkit/resources/plan/commands.json +36 -0
- trigrams_toolkit/resources/plan/plan.schema.json +192 -0
- trigrams_toolkit/resources/shared/GLOBAL-TOOLS.md +31 -0
- trigrams_toolkit/resources/shared/common.schema.json +234 -0
- trigrams_toolkit/resources/state/PROTOCOL.md +85 -0
- trigrams_toolkit/resources/state/README.md +88 -0
- trigrams_toolkit/resources/state/cli.schema.json +326 -0
- trigrams_toolkit/resources/state/commands.json +55 -0
- trigrams_toolkit/resources/state/core-types.json +5 -0
- trigrams_toolkit/resources/state/help.json +86 -0
- trigrams_toolkit/resources/state/sources.schema.json +89 -0
- trigrams_toolkit/resources/state/state.schema.json +200 -0
- trigrams_toolkit/shared/__init__.py +1 -0
- trigrams_toolkit/shared/cli_help.py +195 -0
- trigrams_toolkit/shared/errors.py +29 -0
- trigrams_toolkit/shared/files.py +66 -0
- trigrams_toolkit/shared/locking.py +49 -0
- trigrams_toolkit/shared/paths.py +89 -0
- trigrams_toolkit/shared/process_lock.py +77 -0
- trigrams_toolkit/shared/schema.py +60 -0
- trigrams_toolkit/shared/serialization.py +84 -0
- trigrams_toolkit/shared/skill_installations.py +66 -0
- trigrams_toolkit/shared/state_json.py +45 -0
- trigrams_toolkit/state/__init__.py +4 -0
- trigrams_toolkit/state/arguments.py +68 -0
- trigrams_toolkit/state/cli.py +37 -0
- trigrams_toolkit/state/frontmatter.py +176 -0
- trigrams_toolkit/state/help.py +25 -0
- trigrams_toolkit/state/identity.py +123 -0
- trigrams_toolkit/state/location.py +59 -0
- trigrams_toolkit/state/model.py +76 -0
- trigrams_toolkit/state/providers.py +77 -0
- trigrams_toolkit/state/registration.py +82 -0
- trigrams_toolkit/state/relations.py +105 -0
- trigrams_toolkit/state/service.py +90 -0
- trigrams_toolkit/state/store.py +33 -0
- trigrams_toolkit/state/views.py +64 -0
- trigrams_toolkit/version.py +6 -0
- trigrams_toolkit-0.1.0.dist-info/METADATA +69 -0
- trigrams_toolkit-0.1.0.dist-info/RECORD +103 -0
- trigrams_toolkit-0.1.0.dist-info/WHEEL +5 -0
- trigrams_toolkit-0.1.0.dist-info/entry_points.txt +5 -0
- trigrams_toolkit-0.1.0.dist-info/licenses/LICENSE +21 -0
- trigrams_toolkit-0.1.0.dist-info/licenses/THIRD_PARTY_NOTICES.md +18 -0
- trigrams_toolkit-0.1.0.dist-info/top_level.txt +1 -0
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
"""Project State's SQLite ownership protocol; JSON remains the data store."""
|
|
2
|
+
from __future__ import annotations
|
|
3
|
+
|
|
4
|
+
from contextlib import contextmanager
|
|
5
|
+
from dataclasses import dataclass
|
|
6
|
+
from pathlib import Path
|
|
7
|
+
import sqlite3
|
|
8
|
+
import time
|
|
9
|
+
from typing import Iterator
|
|
10
|
+
|
|
11
|
+
from .errors import ProtocolError
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
@dataclass
|
|
15
|
+
class ProcessLock:
|
|
16
|
+
state_file: Path
|
|
17
|
+
lock_file: Path
|
|
18
|
+
_connection: sqlite3.Connection | None
|
|
19
|
+
|
|
20
|
+
def release(self) -> None:
|
|
21
|
+
if self._connection is not None:
|
|
22
|
+
try:
|
|
23
|
+
self._connection.close()
|
|
24
|
+
except sqlite3.Error as error:
|
|
25
|
+
raise _lock_io_error(self.state_file, self.lock_file, error) from error
|
|
26
|
+
self._connection = None
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
def _lock_io_error(state_file: Path, lock_file: Path, error: Exception) -> ProtocolError:
|
|
30
|
+
return ProtocolError("FILE_WRITE_FAILED", f"Lock IO failed: {lock_file}",
|
|
31
|
+
details={"stateFile": str(state_file), "lockFile": str(lock_file), "cause": str(error)})
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
def acquire_process_lock(state_file: Path, timeout_ms: int = 0) -> ProcessLock:
|
|
35
|
+
if type(timeout_ms) is not int or not 0 <= timeout_ms <= 9007199254740991:
|
|
36
|
+
raise ProtocolError("INVALID_INPUT", "Invalid lock timeout")
|
|
37
|
+
lock_file = Path(str(state_file) + ".lock.sqlite")
|
|
38
|
+
connection = None
|
|
39
|
+
deadline = time.monotonic() + timeout_ms / 1000
|
|
40
|
+
try:
|
|
41
|
+
lock_file.parent.mkdir(parents=True, exist_ok=True)
|
|
42
|
+
connection = sqlite3.connect(lock_file, timeout=0, isolation_level=None)
|
|
43
|
+
while True:
|
|
44
|
+
try:
|
|
45
|
+
assert connection is not None
|
|
46
|
+
connection.execute("BEGIN IMMEDIATE")
|
|
47
|
+
handle = ProcessLock(state_file, lock_file, connection)
|
|
48
|
+
connection = None
|
|
49
|
+
return handle
|
|
50
|
+
except sqlite3.OperationalError as error:
|
|
51
|
+
if (getattr(error, "sqlite_errorcode", 0) & 0xFF) not in (sqlite3.SQLITE_BUSY, sqlite3.SQLITE_LOCKED):
|
|
52
|
+
raise
|
|
53
|
+
if time.monotonic() >= deadline:
|
|
54
|
+
raise ProtocolError("FILE_LOCK_TIMEOUT", f"Timed out waiting for lock: {lock_file}",
|
|
55
|
+
details={"stateFile": str(state_file), "lockFile": str(lock_file), "timeoutMs": timeout_ms})
|
|
56
|
+
time.sleep(min(0.01, max(0.001, deadline - time.monotonic())))
|
|
57
|
+
except (OSError, sqlite3.Error) as error:
|
|
58
|
+
raise _lock_io_error(state_file, lock_file, error) from error
|
|
59
|
+
finally:
|
|
60
|
+
if connection is not None:
|
|
61
|
+
connection.close()
|
|
62
|
+
|
|
63
|
+
|
|
64
|
+
@contextmanager
|
|
65
|
+
def state_lock(state_file: Path) -> Iterator[None]:
|
|
66
|
+
try:
|
|
67
|
+
handle = acquire_process_lock(state_file)
|
|
68
|
+
except ProtocolError as error:
|
|
69
|
+
code = "lock_conflict" if error.code == "FILE_LOCK_TIMEOUT" else "io_error"
|
|
70
|
+
raise ProtocolError(code, str(error), details=error.details) from error
|
|
71
|
+
try:
|
|
72
|
+
yield
|
|
73
|
+
finally:
|
|
74
|
+
try:
|
|
75
|
+
handle.release()
|
|
76
|
+
except ProtocolError as error:
|
|
77
|
+
raise ProtocolError("io_error", f"Cannot release lock: {state_file}", details=error.details) from error
|
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
"""Local contract registration; schema retrieval never uses the network."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from pathlib import Path
|
|
6
|
+
from typing import Any, Sequence
|
|
7
|
+
from jsonschema import Draft202012Validator, FormatChecker
|
|
8
|
+
from jsonschema.exceptions import SchemaError
|
|
9
|
+
from referencing import Registry, Resource
|
|
10
|
+
from referencing.exceptions import Unresolvable
|
|
11
|
+
|
|
12
|
+
from .errors import ProtocolError, require
|
|
13
|
+
from .serialization import read_json, scalar_json
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
class SchemaCatalog:
|
|
17
|
+
"""@to-plan P04/S01
|
|
18
|
+
|
|
19
|
+
Register source schemas by their own $id and reject unresolved local URNs.
|
|
20
|
+
T02 uses jsonschema Draft202012Validator plus referencing.Registry; callers
|
|
21
|
+
supply the contract files and no validator may fetch a missing remote schema.
|
|
22
|
+
"""
|
|
23
|
+
|
|
24
|
+
def __init__(self, paths: Sequence[Path]) -> None:
|
|
25
|
+
self.paths = tuple(paths)
|
|
26
|
+
schemas: dict[str, Any] = {}
|
|
27
|
+
try:
|
|
28
|
+
for path in self.paths:
|
|
29
|
+
schema = read_json(path)
|
|
30
|
+
Draft202012Validator.check_schema(schema)
|
|
31
|
+
identity = schema["$id"]
|
|
32
|
+
require(identity not in schemas, "invalid_schema", f"Duplicate schema: {identity}")
|
|
33
|
+
schemas[identity] = schema
|
|
34
|
+
self._registry = Registry().with_resources(
|
|
35
|
+
(identity, Resource.from_contents(value)) for identity, value in schemas.items())
|
|
36
|
+
for identity, schema in schemas.items():
|
|
37
|
+
for ref in _references(schema):
|
|
38
|
+
self._registry.resolver(identity).lookup(ref)
|
|
39
|
+
except (SchemaError, Unresolvable, KeyError) as error:
|
|
40
|
+
raise ProtocolError("invalid_schema", f"Invalid local contract closure: {error}") from error
|
|
41
|
+
|
|
42
|
+
def validate(self, reference: str, value: Any) -> None:
|
|
43
|
+
scalar_json(value)
|
|
44
|
+
try:
|
|
45
|
+
validator = Draft202012Validator({"$ref": reference}, registry=self._registry,
|
|
46
|
+
format_checker=FormatChecker())
|
|
47
|
+
error = next(validator.iter_errors(value), None)
|
|
48
|
+
if error is not None:
|
|
49
|
+
raise ProtocolError("invalid_schema", f"{error.json_path}: {error.message}")
|
|
50
|
+
except Unresolvable as error:
|
|
51
|
+
raise ProtocolError("invalid_schema", f"Missing local schema: {reference}") from error
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
def _references(value: Any) -> list[str]:
|
|
55
|
+
if isinstance(value, dict):
|
|
56
|
+
own = [value["$ref"]] if "$ref" in value else []
|
|
57
|
+
return own + [ref for item in value.values() for ref in _references(item)]
|
|
58
|
+
if isinstance(value, list):
|
|
59
|
+
return [ref for item in value for ref in _references(item)]
|
|
60
|
+
return []
|
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
"""Strict protocol JSON and canonical serialization."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import json
|
|
6
|
+
from pathlib import Path
|
|
7
|
+
from typing import Any
|
|
8
|
+
|
|
9
|
+
from .errors import ProtocolError, require
|
|
10
|
+
|
|
11
|
+
MAX_INTEGER = 9007199254740991
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
def _unique(pairs: list[tuple[str, Any]]) -> dict[str, Any]:
|
|
15
|
+
result: dict[str, Any] = {}
|
|
16
|
+
for key, value in pairs:
|
|
17
|
+
require(key not in result, "invalid_json", f"Duplicate JSON key: {key}")
|
|
18
|
+
result[key] = value
|
|
19
|
+
return result
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
def _reject_number(value: str) -> None:
|
|
23
|
+
raise ProtocolError("invalid_json", f"Only finite integer numbers are permitted: {value}")
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
def scalar_json(value: Any) -> None:
|
|
27
|
+
if value is None or type(value) is bool:
|
|
28
|
+
return
|
|
29
|
+
if isinstance(value, str):
|
|
30
|
+
require(not any(0xD800 <= ord(c) <= 0xDFFF for c in value),
|
|
31
|
+
"invalid_json", "Strings must contain Unicode scalar values.")
|
|
32
|
+
return
|
|
33
|
+
if type(value) is int:
|
|
34
|
+
require(abs(value) <= MAX_INTEGER, "invalid_json", "Integer exceeds the shared safe range.")
|
|
35
|
+
return
|
|
36
|
+
if isinstance(value, list):
|
|
37
|
+
for item in value:
|
|
38
|
+
scalar_json(item)
|
|
39
|
+
return
|
|
40
|
+
if isinstance(value, dict):
|
|
41
|
+
for key, item in value.items():
|
|
42
|
+
require(isinstance(key, str), "invalid_json", "JSON object keys must be strings.")
|
|
43
|
+
scalar_json(key)
|
|
44
|
+
scalar_json(item)
|
|
45
|
+
return
|
|
46
|
+
raise ProtocolError("invalid_json", f"Unsupported protocol JSON value: {type(value).__name__}")
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
def parse_json_document(raw: str | bytes) -> Any:
|
|
50
|
+
"""Parse UTF-8 JSON with unique keys and integer numbers.
|
|
51
|
+
|
|
52
|
+
Share duplicate-key/number rules and JSON/Unicode error conversion.
|
|
53
|
+
Keep check_protocols' document boundary: arbitrary-size integers and escaped
|
|
54
|
+
surrogate strings are accepted here; runtime values pass scalar_json too.
|
|
55
|
+
Invalid encoding, syntax, duplicate keys or non-integers raise ProtocolError
|
|
56
|
+
with invalid_json. File IO errors belong to the caller.
|
|
57
|
+
"""
|
|
58
|
+
try:
|
|
59
|
+
text = raw.decode("utf-8") if isinstance(raw, bytes) else raw
|
|
60
|
+
return json.loads(text, object_pairs_hook=_unique,
|
|
61
|
+
parse_float=_reject_number, parse_constant=_reject_number)
|
|
62
|
+
except (UnicodeError, json.JSONDecodeError) as error:
|
|
63
|
+
raise ProtocolError("invalid_json", str(error)) from error
|
|
64
|
+
|
|
65
|
+
|
|
66
|
+
def parse_json(raw: str | bytes) -> Any:
|
|
67
|
+
"""Parse document JSON and enforce runtime-safe integers/scalar strings."""
|
|
68
|
+
result = parse_json_document(raw)
|
|
69
|
+
scalar_json(result)
|
|
70
|
+
return result
|
|
71
|
+
|
|
72
|
+
|
|
73
|
+
def read_json(path: Path) -> Any:
|
|
74
|
+
return parse_json(path.read_bytes())
|
|
75
|
+
|
|
76
|
+
|
|
77
|
+
def canonical(value: Any) -> bytes:
|
|
78
|
+
scalar_json(value)
|
|
79
|
+
return json.dumps(value, ensure_ascii=False, sort_keys=True,
|
|
80
|
+
separators=(",", ":"), allow_nan=False).encode("utf-8")
|
|
81
|
+
|
|
82
|
+
|
|
83
|
+
def sorted_refs(refs: list[dict[str, Any]]) -> list[dict[str, Any]]:
|
|
84
|
+
return [parse_json(raw) for raw in sorted({canonical(ref) for ref in refs})]
|
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
"""Filesystem locations used by the supported Vercel skills agents."""
|
|
2
|
+
from __future__ import annotations
|
|
3
|
+
|
|
4
|
+
from dataclasses import dataclass
|
|
5
|
+
import os
|
|
6
|
+
from pathlib import Path
|
|
7
|
+
from typing import Final
|
|
8
|
+
|
|
9
|
+
from .errors import require
|
|
10
|
+
from .paths import confined, files_under, relative_path
|
|
11
|
+
|
|
12
|
+
|
|
13
|
+
@dataclass(frozen=True)
|
|
14
|
+
class SkillAgent:
|
|
15
|
+
name: str
|
|
16
|
+
directory: str
|
|
17
|
+
|
|
18
|
+
|
|
19
|
+
DEFAULT_AGENT: Final = "codex"
|
|
20
|
+
AGENTS: Final = {
|
|
21
|
+
"codex": SkillAgent("codex", ".agents/skills"),
|
|
22
|
+
"claude-code": SkillAgent("claude-code", ".claude/skills"),
|
|
23
|
+
"pi": SkillAgent("pi", ".agents/skills"),
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
def skill_agent(name: str | None = None) -> SkillAgent:
|
|
28
|
+
selected = name or DEFAULT_AGENT
|
|
29
|
+
require(selected in AGENTS, "invalid_arguments",
|
|
30
|
+
f"Unsupported Vercel skills agent: {selected}. Choose codex, claude-code or pi.")
|
|
31
|
+
return AGENTS[selected]
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
def skill_directory(agent: SkillAgent, project: Path | None = None) -> Path:
|
|
35
|
+
if project is not None:
|
|
36
|
+
return confined(project, agent.directory)
|
|
37
|
+
if agent.name == "claude-code" and (location := os.environ.get("CLAUDE_CONFIG_DIR", "").strip()):
|
|
38
|
+
require(Path(location).is_absolute(), "invalid_arguments", "CLAUDE_CONFIG_DIR must be absolute.")
|
|
39
|
+
return Path(location) / "skills"
|
|
40
|
+
return Path.home() / agent.directory
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
def _same_tree(first: Path, second: Path) -> bool:
|
|
44
|
+
# Vercel can create a second copy when a Claude link fails on Windows.
|
|
45
|
+
files = {path.relative_to(first) for child in first.iterdir() for path in files_under(first, child)}
|
|
46
|
+
return (files == {path.relative_to(second) for child in second.iterdir() for path in files_under(second, child)}
|
|
47
|
+
and all((first / path).read_bytes() == (second / path).read_bytes() for path in files))
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
def installed_skill(name: str, agent: SkillAgent, project: Path | None = None,
|
|
51
|
+
*, required: bool = True) -> Path | None:
|
|
52
|
+
relative_path(name)
|
|
53
|
+
target = skill_directory(agent, project) / name
|
|
54
|
+
scope = "global" if project is None else f"project ({project})"
|
|
55
|
+
if not (target / "SKILL.md").is_file():
|
|
56
|
+
require(not required, "missing_capability",
|
|
57
|
+
f"Missing {scope} Skill {name} for {agent.name}: {target}. Install it with Vercel skills and retry.")
|
|
58
|
+
return None
|
|
59
|
+
root = target.resolve()
|
|
60
|
+
confined(root, "SKILL.md")
|
|
61
|
+
if agent.name == "claude-code":
|
|
62
|
+
shared = (skill_directory(AGENTS["codex"], project) / name).resolve()
|
|
63
|
+
if shared != root and (shared / "SKILL.md").is_file() and confined(shared, "SKILL.md").is_file():
|
|
64
|
+
require(_same_tree(root, shared), "resource_conflict",
|
|
65
|
+
f"Different {scope} sources for Skill {name} ({agent.name}): {target}, {shared}. Reconcile the installations and retry.")
|
|
66
|
+
return root
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
"""Legacy Project State JSON.parse boundary (separate from strict CLI JSON)."""
|
|
2
|
+
from __future__ import annotations
|
|
3
|
+
|
|
4
|
+
import json
|
|
5
|
+
import math
|
|
6
|
+
from pathlib import Path
|
|
7
|
+
from typing import Any
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
def _invalid_constant(value: str) -> None:
|
|
11
|
+
raise ValueError(f"Invalid JSON constant: {value}")
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
def _number(value: str) -> int | float:
|
|
15
|
+
number = float(value)
|
|
16
|
+
return int(number) if math.isfinite(number) and number.is_integer() else number
|
|
17
|
+
|
|
18
|
+
|
|
19
|
+
def parse_state_json(raw: str | bytes, *, bom: bool = False) -> Any:
|
|
20
|
+
text = raw.decode("utf-8", errors="replace") if isinstance(raw, bytes) else raw
|
|
21
|
+
if bom:
|
|
22
|
+
text = text.removeprefix("\ufeff")
|
|
23
|
+
return json.loads(text, parse_int=_number, parse_float=_number, parse_constant=_invalid_constant)
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
def optional_bytes(path: Path) -> bytes | None:
|
|
27
|
+
try:
|
|
28
|
+
return path.read_bytes()
|
|
29
|
+
except FileNotFoundError:
|
|
30
|
+
return None
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
def json_bytes(value: Any) -> bytes:
|
|
34
|
+
return (json.dumps(_json_value(value), ensure_ascii=False, indent=2, allow_nan=False) + "\n").encode("utf-8", errors="backslashreplace")
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
def _json_value(value: Any) -> Any:
|
|
38
|
+
"""JSON.stringify emits null for overflowed numbers in unmanaged fields."""
|
|
39
|
+
if isinstance(value, float) and not math.isfinite(value):
|
|
40
|
+
return None
|
|
41
|
+
if isinstance(value, dict):
|
|
42
|
+
return {key: _json_value(item) for key, item in value.items()}
|
|
43
|
+
if isinstance(value, list):
|
|
44
|
+
return [_json_value(item) for item in value]
|
|
45
|
+
return value
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
"""The eight-command argument contract, independent of project state."""
|
|
2
|
+
from __future__ import annotations
|
|
3
|
+
|
|
4
|
+
from dataclasses import dataclass, field
|
|
5
|
+
from typing import Literal, Sequence
|
|
6
|
+
from trigrams_toolkit.shared.errors import require
|
|
7
|
+
|
|
8
|
+
SPECIFIC = {
|
|
9
|
+
"register module": ("--id",),
|
|
10
|
+
"register feature": ("--id", "--module"), "register artifact": ("--kind", "--module", "--feature"),
|
|
11
|
+
"locate": (), "list": ("--kind",), "related": ("--direction",), "relate": ("--remove",), "validate": (),
|
|
12
|
+
}
|
|
13
|
+
ARITY = dict(zip(SPECIFIC, (1, 1, 1, 1, 0, 1, 3, 0)))
|
|
14
|
+
COMMAND_NAMES = tuple(SPECIFIC)
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
@dataclass(frozen=True)
|
|
18
|
+
class Invocation:
|
|
19
|
+
command: str = ""
|
|
20
|
+
args: tuple[str, ...] = ()
|
|
21
|
+
options: dict[str, list[str]] = field(default_factory=dict)
|
|
22
|
+
kind: Literal["command", "help", "version"] = "command"
|
|
23
|
+
|
|
24
|
+
def option(self, flag: str) -> str | None:
|
|
25
|
+
values = self.options.get(flag)
|
|
26
|
+
return values[0] if values else None
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
def parse_arguments(argv: Sequence[str]) -> Invocation:
|
|
30
|
+
words: list[str] = []
|
|
31
|
+
options: dict[str, list[str]] = {}
|
|
32
|
+
index = 0
|
|
33
|
+
while index < len(argv):
|
|
34
|
+
token = argv[index]
|
|
35
|
+
index += 1
|
|
36
|
+
require(bool(token) and "\0" not in token, "invalid_arguments", "Empty or invalid argument.")
|
|
37
|
+
if not token.startswith("-"):
|
|
38
|
+
words.append(token)
|
|
39
|
+
continue
|
|
40
|
+
flag, equal, value = token.partition("=")
|
|
41
|
+
require(flag == "--feature" or flag not in options, "invalid_arguments", f"Duplicate option: {flag}")
|
|
42
|
+
toggle = flag in ("--help", "-h", "--version", "-v", "--remove")
|
|
43
|
+
if toggle:
|
|
44
|
+
value = "true"
|
|
45
|
+
elif not equal:
|
|
46
|
+
value = argv[index] if index < len(argv) else ""
|
|
47
|
+
index += 1
|
|
48
|
+
require(bool(value) and not value.startswith("--") and not (toggle and equal), "invalid_arguments", f"Expected a value for {flag}.")
|
|
49
|
+
options.setdefault(flag, []).append(value)
|
|
50
|
+
if "--version" in options or "-v" in options:
|
|
51
|
+
require(not words and len(options) == 1, "invalid_arguments", "--version is a root option.")
|
|
52
|
+
return Invocation(kind="version")
|
|
53
|
+
grouped = bool(words) and words[0] == "register"
|
|
54
|
+
count = 2 if grouped else 1
|
|
55
|
+
name = " ".join(words[:count])
|
|
56
|
+
allowed = {"-h", "--help", *SPECIFIC.get(name, ())}
|
|
57
|
+
for flag in options:
|
|
58
|
+
require(flag in allowed, "invalid_arguments", f"Unknown option: {flag}")
|
|
59
|
+
if "--help" in options or "-h" in options or not argv or (grouped and len(words) == 1):
|
|
60
|
+
require(name in SPECIFIC or name in ("", "register"), "invalid_arguments", f"Unknown command: {name}")
|
|
61
|
+
return Invocation(command=name, kind="help")
|
|
62
|
+
require(name in SPECIFIC, "invalid_arguments", f"Unknown command: {name}. Use project-state --help.")
|
|
63
|
+
args = tuple(words[count:])
|
|
64
|
+
require(len(args) == ARITY[name], "invalid_arguments", f"Expected {ARITY[name]} argument(s) for {name}. Use --help.")
|
|
65
|
+
require("--direction" not in options or options["--direction"][0] in ("both", "incoming", "outgoing"),
|
|
66
|
+
"invalid_arguments", "direction must be both, incoming or outgoing.")
|
|
67
|
+
require("--feature" not in options or "--module" in options, "invalid_arguments", "--feature requires --module MODULE_ID in the same command.")
|
|
68
|
+
return Invocation(name, args, options)
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
"""Project State's JSON/stdout/exit-code boundary."""
|
|
2
|
+
from __future__ import annotations
|
|
3
|
+
|
|
4
|
+
import json
|
|
5
|
+
import sys
|
|
6
|
+
from typing import Sequence
|
|
7
|
+
|
|
8
|
+
from trigrams_toolkit.shared.errors import ProtocolError
|
|
9
|
+
from trigrams_toolkit.version import version
|
|
10
|
+
from .arguments import parse_arguments
|
|
11
|
+
from .help import help_text
|
|
12
|
+
from .service import execute
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
def main(argv: Sequence[str] | None = None) -> int:
|
|
16
|
+
if hasattr(sys.stdout, "reconfigure"):
|
|
17
|
+
sys.stdout.reconfigure(encoding="utf-8")
|
|
18
|
+
try:
|
|
19
|
+
invocation = parse_arguments(sys.argv[1:] if argv is None else argv)
|
|
20
|
+
if invocation.kind == "help":
|
|
21
|
+
print(help_text(invocation.command), end="")
|
|
22
|
+
return 0
|
|
23
|
+
if invocation.kind == "version":
|
|
24
|
+
print(version())
|
|
25
|
+
return 0
|
|
26
|
+
response = {"ok": True, "data": execute(invocation)}
|
|
27
|
+
except ProtocolError as error:
|
|
28
|
+
response = {"ok": False, "error": error.state_error()}
|
|
29
|
+
except (OSError, ValueError, TypeError, RecursionError) as error:
|
|
30
|
+
response = {"ok": False, "error": {"code": "io_error", "message": str(error)}}
|
|
31
|
+
output = json.dumps(response, ensure_ascii=False, allow_nan=False)
|
|
32
|
+
print(output.encode("utf-8", errors="backslashreplace").decode("utf-8"))
|
|
33
|
+
return 0 if response["ok"] else 1
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
if __name__ == "__main__":
|
|
37
|
+
raise SystemExit(main())
|
|
@@ -0,0 +1,176 @@
|
|
|
1
|
+
"""Validate legacy YAML metadata and edit only managed nodes in the header."""
|
|
2
|
+
from __future__ import annotations
|
|
3
|
+
|
|
4
|
+
from io import StringIO
|
|
5
|
+
import re
|
|
6
|
+
from typing import Iterator
|
|
7
|
+
|
|
8
|
+
from ruamel.yaml import YAML
|
|
9
|
+
from ruamel.yaml.anchor import Anchor
|
|
10
|
+
from ruamel.yaml.error import YAMLError
|
|
11
|
+
from ruamel.yaml.nodes import MappingNode, Node, ScalarNode, SequenceNode
|
|
12
|
+
from ruamel.yaml.resolver import VersionedResolver
|
|
13
|
+
from ruamel.yaml.tag import Tag
|
|
14
|
+
|
|
15
|
+
_YAML_TAG = "tag:yaml.org,2002:"
|
|
16
|
+
_STR = _YAML_TAG + "str"
|
|
17
|
+
_NULL = _YAML_TAG + "null"
|
|
18
|
+
_MERGE = _YAML_TAG + "merge"
|
|
19
|
+
_MAP = _YAML_TAG + "map"
|
|
20
|
+
_SEQ = _YAML_TAG + "seq"
|
|
21
|
+
_MANAGED = ("artifact-id", "title", "moduleId", "featureIds")
|
|
22
|
+
|
|
23
|
+
# YAML 1.1's legacy JS resolver also accepts leading zeroes in sexagesimal
|
|
24
|
+
# and decimal numbers and single digits in timestamps.
|
|
25
|
+
_NUMBER = re.compile(
|
|
26
|
+
r"[-+]?(?:[0-9][0-9_]*(?::[0-5]?[0-9])*|0b[01_]+|0x[0-9a-fA-F_]+)"
|
|
27
|
+
)
|
|
28
|
+
_FLOAT = re.compile(
|
|
29
|
+
r"[-+]?(?:[0-9][0-9_]*)?(?:\.[0-9_]*)?[eE][-+]?[0-9]+"
|
|
30
|
+
r"|[-+]?(?:[0-9][0-9_]*(?::[0-5]?[0-9])*)?\.[0-9_]*"
|
|
31
|
+
r"|[-+]?\.(?:inf|Inf|INF)|\.(?:nan|NaN|NAN)"
|
|
32
|
+
)
|
|
33
|
+
_TIMESTAMP = re.compile(
|
|
34
|
+
r"[0-9]{4}-[0-9]{1,2}-[0-9]{1,2}(?:(?:[tT]|[ \t]+)"
|
|
35
|
+
r"[0-9]{1,2}:[0-9]{1,2}:[0-9]{1,2}(?:\.[0-9]+)?"
|
|
36
|
+
r"(?:[ \t]*(?:Z|[-+][012]?[0-9](?::[0-9]{2})?))?)?"
|
|
37
|
+
)
|
|
38
|
+
_RECLASSIFIED = {_YAML_TAG + name for name in ("int", "float", "timestamp", "value", "yaml")}
|
|
39
|
+
_SCALAR_TAGS = {_YAML_TAG + name for name in ("str", "null", "merge", "bool", "int", "float", "binary", "timestamp")}
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
class _LegacyResolver(VersionedResolver):
|
|
43
|
+
def resolve(self, kind: type[Node], value: str, implicit: tuple[bool, ...]) -> Tag:
|
|
44
|
+
tag = super().resolve(kind, value, implicit)
|
|
45
|
+
if kind is ScalarNode and implicit[0] and self.processing_version == (1, 1):
|
|
46
|
+
for pattern, name in ((_NUMBER, "int"), (_FLOAT, "float"), (_TIMESTAMP, "timestamp")):
|
|
47
|
+
if pattern.fullmatch(value):
|
|
48
|
+
return Tag(suffix=_YAML_TAG + name)
|
|
49
|
+
if str(tag) in _RECLASSIFIED:
|
|
50
|
+
return self.DEFAULT_SCALAR_TAG
|
|
51
|
+
return tag
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
def _nodes(root: Node) -> Iterator[Node]:
|
|
55
|
+
pending = [root]
|
|
56
|
+
seen: set[Node] = set()
|
|
57
|
+
while pending:
|
|
58
|
+
node = pending.pop()
|
|
59
|
+
if node in seen:
|
|
60
|
+
continue
|
|
61
|
+
seen.add(node)
|
|
62
|
+
yield node
|
|
63
|
+
if isinstance(node, MappingNode):
|
|
64
|
+
pending.extend(child for pair in node.value for child in pair)
|
|
65
|
+
elif isinstance(node, SequenceNode):
|
|
66
|
+
pending.extend(node.value)
|
|
67
|
+
|
|
68
|
+
|
|
69
|
+
def _mapping_fields(node: MappingNode, active: frozenset[Node] = frozenset()) -> dict[str, Node]:
|
|
70
|
+
if node in active:
|
|
71
|
+
raise ValueError("Recursive YAML merge")
|
|
72
|
+
fields: dict[str, Node] = {}
|
|
73
|
+
merged = False
|
|
74
|
+
for key, value in node.value:
|
|
75
|
+
entries: list[tuple[str, Node]]
|
|
76
|
+
if key.tag == _MERGE:
|
|
77
|
+
if merged:
|
|
78
|
+
raise ValueError("Expected one YAML merge key per mapping")
|
|
79
|
+
merged = True
|
|
80
|
+
sources = value.value if isinstance(value, SequenceNode) else [value]
|
|
81
|
+
entries = []
|
|
82
|
+
for source in sources:
|
|
83
|
+
if not isinstance(source, MappingNode):
|
|
84
|
+
raise ValueError("Expected YAML maps in merge")
|
|
85
|
+
entries.extend(_mapping_fields(source, active | {node}).items())
|
|
86
|
+
else:
|
|
87
|
+
if not isinstance(key, ScalarNode) or key.tag != _STR:
|
|
88
|
+
raise ValueError("Expected string YAML key")
|
|
89
|
+
entries = [(key.value, value)]
|
|
90
|
+
for name, child in entries:
|
|
91
|
+
if name in fields:
|
|
92
|
+
raise ValueError(f"Expected unique string YAML key: {name}")
|
|
93
|
+
fields[name] = child
|
|
94
|
+
return fields
|
|
95
|
+
|
|
96
|
+
|
|
97
|
+
def _document(source: str) -> tuple[YAML, MappingNode | None, dict[str, Node]]:
|
|
98
|
+
parser = YAML(typ="rt")
|
|
99
|
+
parser.Resolver = _LegacyResolver
|
|
100
|
+
parser.version = (1, 1)
|
|
101
|
+
try:
|
|
102
|
+
node = parser.compose(source)
|
|
103
|
+
except YAMLError as error:
|
|
104
|
+
raise ValueError(str(error)) from error
|
|
105
|
+
if node is None:
|
|
106
|
+
return parser, None, {}
|
|
107
|
+
if not isinstance(node, MappingNode) or node.tag != _MAP:
|
|
108
|
+
raise ValueError("Expected mapping frontmatter")
|
|
109
|
+
fields = _mapping_fields(node)
|
|
110
|
+
for child in _nodes(node):
|
|
111
|
+
if isinstance(child, MappingNode) and child.tag in (_MAP, _YAML_TAG + "set"):
|
|
112
|
+
if child is not node:
|
|
113
|
+
_mapping_fields(child)
|
|
114
|
+
elif isinstance(child, SequenceNode) and child.tag in (_SEQ, _YAML_TAG + "pairs", _YAML_TAG + "omap"):
|
|
115
|
+
continue
|
|
116
|
+
elif not isinstance(child, ScalarNode) or child.tag not in _SCALAR_TAGS:
|
|
117
|
+
raise ValueError(f"Unsupported YAML tag: {child.tag}")
|
|
118
|
+
return parser, node, fields
|
|
119
|
+
|
|
120
|
+
|
|
121
|
+
def _managed_value(node: Node) -> str | list[str] | Node | None:
|
|
122
|
+
if node.tag == _NULL:
|
|
123
|
+
return None
|
|
124
|
+
if isinstance(node, ScalarNode) and node.tag == _STR:
|
|
125
|
+
return node.value
|
|
126
|
+
if isinstance(node, SequenceNode) and node.tag == _SEQ and all(
|
|
127
|
+
isinstance(child, ScalarNode) and child.tag == _STR for child in node.value
|
|
128
|
+
):
|
|
129
|
+
return [child.value for child in node.value]
|
|
130
|
+
return node
|
|
131
|
+
|
|
132
|
+
|
|
133
|
+
def metadata(source: str) -> dict[str, str | list[str] | Node | None]:
|
|
134
|
+
"""Read the managed values without constructing unmatched YAML scalars or aliases."""
|
|
135
|
+
_, _, fields = _document(source)
|
|
136
|
+
return {key: _managed_value(fields[key]) for key in _MANAGED if key in fields}
|
|
137
|
+
|
|
138
|
+
|
|
139
|
+
def update_metadata(source: str, identity: str, module: str | None, features: list[str]) -> str:
|
|
140
|
+
source = source.replace("\r\n", "\n").replace("\r", "\n")
|
|
141
|
+
parser, node, _ = _document(source)
|
|
142
|
+
parser.width = 1000000
|
|
143
|
+
preamble = source if node is None else ""
|
|
144
|
+
if node is None:
|
|
145
|
+
node = MappingNode(_MAP, [])
|
|
146
|
+
updates: dict[str, Node | None] = {
|
|
147
|
+
"artifact-id": ScalarNode(_STR, identity),
|
|
148
|
+
"moduleId": ScalarNode(_STR, module) if module is not None else None,
|
|
149
|
+
"featureIds": SequenceNode(_SEQ, [ScalarNode(_STR, item) for item in features]) if features else None,
|
|
150
|
+
}
|
|
151
|
+
updated: list[tuple[Node, Node]] = []
|
|
152
|
+
for key, value in node.value:
|
|
153
|
+
if not isinstance(key, ScalarNode) or key.tag != _STR or key.value not in updates:
|
|
154
|
+
updated.append((key, value))
|
|
155
|
+
continue
|
|
156
|
+
replacement = updates.pop(key.value)
|
|
157
|
+
if replacement is not None:
|
|
158
|
+
replacement.comment = value.comment
|
|
159
|
+
if isinstance(value, ScalarNode) and isinstance(replacement, ScalarNode):
|
|
160
|
+
replacement.style = value.style
|
|
161
|
+
updated.append((key, replacement))
|
|
162
|
+
updated.extend((ScalarNode(_STR, key), value) for key, value in updates.items() if value is not None)
|
|
163
|
+
node.value = updated
|
|
164
|
+
for child in _nodes(node):
|
|
165
|
+
if isinstance(child.anchor, str):
|
|
166
|
+
name = child.anchor
|
|
167
|
+
child.anchor = Anchor()
|
|
168
|
+
child.anchor.value = name
|
|
169
|
+
child.anchor.always_dump = True
|
|
170
|
+
output = StringIO()
|
|
171
|
+
try:
|
|
172
|
+
parser.serialize(node, output)
|
|
173
|
+
except YAMLError as error:
|
|
174
|
+
raise ValueError(str(error)) from error
|
|
175
|
+
rendered = output.getvalue().removeprefix("%YAML 1.1\n---")
|
|
176
|
+
return preamble + rendered.removeprefix("\n").removeprefix(" ")
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
"""Side-effect-free help from package-owned command descriptions."""
|
|
2
|
+
from trigrams_toolkit.resources import resource_path
|
|
3
|
+
from trigrams_toolkit.shared.serialization import read_json
|
|
4
|
+
from trigrams_toolkit.shared.cli_help import help_rows, paragraph
|
|
5
|
+
|
|
6
|
+
|
|
7
|
+
def help_text(command: str) -> str:
|
|
8
|
+
entries = read_json(resource_path("state/help.json"))
|
|
9
|
+
options = [("-h, --help", "Show help.")]
|
|
10
|
+
if command in entries:
|
|
11
|
+
entry = entries[command]
|
|
12
|
+
lines = [paragraph("Usage: project-state " + entry["usage"]), "", paragraph(entry["summary"])]
|
|
13
|
+
if entry.get("details"):
|
|
14
|
+
lines.extend(["", paragraph(entry["details"])])
|
|
15
|
+
return "\n".join([*lines, "", "Options:", *help_rows([*entry.get("options", []), *options]), "",
|
|
16
|
+
"Output: JSON; exit 0 on success, 1 on error.", ""])
|
|
17
|
+
names = [name for name in entries if not command or name.startswith(command + " ")]
|
|
18
|
+
rows = [(name[len(command) + 1:] if command else name, entries[name]["summary"]) for name in names]
|
|
19
|
+
if not command:
|
|
20
|
+
options.append(("-v, --version", "Show toolkit version."))
|
|
21
|
+
prefix = "project-state" + (" " + command if command else "")
|
|
22
|
+
return "\n".join([f"Usage: {prefix} COMMAND [options]", "",
|
|
23
|
+
"Run commands from the project root to manage architecture entities and relations.",
|
|
24
|
+
"", "Commands:", *help_rows(rows), "", "Options:", *help_rows(options), "",
|
|
25
|
+
f"Use {prefix} COMMAND -h for command details.", ""])
|