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.
Files changed (103) hide show
  1. trigrams_toolkit/__init__.py +1 -0
  2. trigrams_toolkit/handbook/__init__.py +6 -0
  3. trigrams_toolkit/handbook/cli.py +122 -0
  4. trigrams_toolkit/handbook/guide_headers.py +43 -0
  5. trigrams_toolkit/handbook/guides.py +141 -0
  6. trigrams_toolkit/handbook/location.py +79 -0
  7. trigrams_toolkit/handbook/model.py +4 -0
  8. trigrams_toolkit/handbook/package.py +165 -0
  9. trigrams_toolkit/handbook/principle_import.py +101 -0
  10. trigrams_toolkit/handbook/project_resources.py +80 -0
  11. trigrams_toolkit/handbook/skill_sources.py +59 -0
  12. trigrams_toolkit/handbook/source_catalog.py +55 -0
  13. trigrams_toolkit/handbook/sources.py +16 -0
  14. trigrams_toolkit/installation/__init__.py +0 -0
  15. trigrams_toolkit/installation/archive_project.py +50 -0
  16. trigrams_toolkit/installation/global_skills.py +45 -0
  17. trigrams_toolkit/installation/harness_install.py +89 -0
  18. trigrams_toolkit/installation/installation_candidate.py +135 -0
  19. trigrams_toolkit/installation/installation_help.py +49 -0
  20. trigrams_toolkit/installation/installation_materials.py +73 -0
  21. trigrams_toolkit/installation/installation_service.py +14 -0
  22. trigrams_toolkit/installation/installation_sources.py +34 -0
  23. trigrams_toolkit/installation/operation_files.py +94 -0
  24. trigrams_toolkit/installation/operation_runtime.py +144 -0
  25. trigrams_toolkit/installation/package_metadata.py +48 -0
  26. trigrams_toolkit/plan/__init__.py +5 -0
  27. trigrams_toolkit/plan/cli.py +136 -0
  28. trigrams_toolkit/plan/definitions.py +131 -0
  29. trigrams_toolkit/plan/model.py +61 -0
  30. trigrams_toolkit/plan/scheduling.py +126 -0
  31. trigrams_toolkit/plan/service.py +139 -0
  32. trigrams_toolkit/plan/state.py +146 -0
  33. trigrams_toolkit/project_context/__init__.py +16 -0
  34. trigrams_toolkit/project_context/paths.py +36 -0
  35. trigrams_toolkit/py.typed +0 -0
  36. trigrams_toolkit/resources/__init__.py +35 -0
  37. trigrams_toolkit/resources/adapters/claude/README.md +7 -0
  38. trigrams_toolkit/resources/adapters/claude/evaluator.md +7 -0
  39. trigrams_toolkit/resources/adapters/claude/task_developer.md +7 -0
  40. trigrams_toolkit/resources/adapters/codex/README.md +9 -0
  41. trigrams_toolkit/resources/adapters/codex/evaluator.toml +6 -0
  42. trigrams_toolkit/resources/adapters/codex/task_developer.toml +6 -0
  43. trigrams_toolkit/resources/adapters/pi-web/evaluator.md +7 -0
  44. trigrams_toolkit/resources/adapters/pi-web/task_developer.md +7 -0
  45. trigrams_toolkit/resources/handbook/PROTOCOL.md +82 -0
  46. trigrams_toolkit/resources/handbook/README.md +45 -0
  47. trigrams_toolkit/resources/handbook/commands.json +31 -0
  48. trigrams_toolkit/resources/handbook/guides.schema.json +253 -0
  49. trigrams_toolkit/resources/installation/PROTOCOL.md +35 -0
  50. trigrams_toolkit/resources/installation/cli.schema.json +89 -0
  51. trigrams_toolkit/resources/installation/commands.json +23 -0
  52. trigrams_toolkit/resources/installation/examples/install-apply-input.json +48 -0
  53. trigrams_toolkit/resources/installation/examples/install-preview-input.json +7 -0
  54. trigrams_toolkit/resources/installation/examples/installation.json +20 -0
  55. trigrams_toolkit/resources/installation/global-skills.json +6 -0
  56. trigrams_toolkit/resources/installation/installation.schema.json +295 -0
  57. trigrams_toolkit/resources/plan/PROTOCOL.md +89 -0
  58. trigrams_toolkit/resources/plan/README.md +61 -0
  59. trigrams_toolkit/resources/plan/commands.json +36 -0
  60. trigrams_toolkit/resources/plan/plan.schema.json +192 -0
  61. trigrams_toolkit/resources/shared/GLOBAL-TOOLS.md +31 -0
  62. trigrams_toolkit/resources/shared/common.schema.json +234 -0
  63. trigrams_toolkit/resources/state/PROTOCOL.md +85 -0
  64. trigrams_toolkit/resources/state/README.md +88 -0
  65. trigrams_toolkit/resources/state/cli.schema.json +326 -0
  66. trigrams_toolkit/resources/state/commands.json +55 -0
  67. trigrams_toolkit/resources/state/core-types.json +5 -0
  68. trigrams_toolkit/resources/state/help.json +86 -0
  69. trigrams_toolkit/resources/state/sources.schema.json +89 -0
  70. trigrams_toolkit/resources/state/state.schema.json +200 -0
  71. trigrams_toolkit/shared/__init__.py +1 -0
  72. trigrams_toolkit/shared/cli_help.py +195 -0
  73. trigrams_toolkit/shared/errors.py +29 -0
  74. trigrams_toolkit/shared/files.py +66 -0
  75. trigrams_toolkit/shared/locking.py +49 -0
  76. trigrams_toolkit/shared/paths.py +89 -0
  77. trigrams_toolkit/shared/process_lock.py +77 -0
  78. trigrams_toolkit/shared/schema.py +60 -0
  79. trigrams_toolkit/shared/serialization.py +84 -0
  80. trigrams_toolkit/shared/skill_installations.py +66 -0
  81. trigrams_toolkit/shared/state_json.py +45 -0
  82. trigrams_toolkit/state/__init__.py +4 -0
  83. trigrams_toolkit/state/arguments.py +68 -0
  84. trigrams_toolkit/state/cli.py +37 -0
  85. trigrams_toolkit/state/frontmatter.py +176 -0
  86. trigrams_toolkit/state/help.py +25 -0
  87. trigrams_toolkit/state/identity.py +123 -0
  88. trigrams_toolkit/state/location.py +59 -0
  89. trigrams_toolkit/state/model.py +76 -0
  90. trigrams_toolkit/state/providers.py +77 -0
  91. trigrams_toolkit/state/registration.py +82 -0
  92. trigrams_toolkit/state/relations.py +105 -0
  93. trigrams_toolkit/state/service.py +90 -0
  94. trigrams_toolkit/state/store.py +33 -0
  95. trigrams_toolkit/state/views.py +64 -0
  96. trigrams_toolkit/version.py +6 -0
  97. trigrams_toolkit-0.1.0.dist-info/METADATA +69 -0
  98. trigrams_toolkit-0.1.0.dist-info/RECORD +103 -0
  99. trigrams_toolkit-0.1.0.dist-info/WHEEL +5 -0
  100. trigrams_toolkit-0.1.0.dist-info/entry_points.txt +5 -0
  101. trigrams_toolkit-0.1.0.dist-info/licenses/LICENSE +21 -0
  102. trigrams_toolkit-0.1.0.dist-info/licenses/THIRD_PARTY_NOTICES.md +18 -0
  103. 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,4 @@
1
+ """Registry queries and identity services."""
2
+ from .service import execute, locate_identity
3
+
4
+ __all__ = ["execute", "locate_identity"]
@@ -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.", ""])