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,131 @@
1
+ """Read Task declarations and the Stub handoff blocks in summary.md."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from pathlib import Path
6
+ import re
7
+ from typing import Any
8
+
9
+ import yaml
10
+
11
+ from trigrams_toolkit.shared.errors import ProtocolError, require
12
+ from .model import PlanDefinition, REBUILD_INSTRUCTION, STUB_FIELDS, StubDefinition, TaskDefinition
13
+
14
+
15
+ class _HeaderLoader(yaml.SafeLoader):
16
+ pass
17
+
18
+
19
+ def _mapping(loader: _HeaderLoader, node: yaml.MappingNode) -> dict:
20
+ result = {}
21
+ for key_node, value_node in node.value:
22
+ key = loader.construct_object(key_node)
23
+ require(isinstance(key, str), "invalid_task", "Task header keys must be strings.")
24
+ require(key not in result, "invalid_task", f"Duplicate Task header: {key}")
25
+ result[key] = loader.construct_object(value_node)
26
+ return result
27
+
28
+
29
+ _HeaderLoader.add_constructor(yaml.resolver.BaseResolver.DEFAULT_MAPPING_TAG, _mapping)
30
+
31
+
32
+ def read_text(path: Path) -> str:
33
+ try:
34
+ return path.read_text(encoding="utf-8-sig")
35
+ except (OSError, UnicodeError) as error:
36
+ raise ProtocolError("plan_unreadable", f"Cannot read {path}: {error}") from error
37
+
38
+
39
+ def _header(body: str, path: Path) -> dict[str, Any]:
40
+ lines = body.splitlines()
41
+ if not lines or lines[0] != "---":
42
+ return {}
43
+ require("---" in lines[1:], "invalid_task", f"Close the YAML header in {path}.")
44
+ try:
45
+ value = yaml.load("\n".join(lines[1:lines.index("---", 1)]), Loader=_HeaderLoader)
46
+ except yaml.YAMLError as error:
47
+ raise ProtocolError("invalid_task", f"Invalid YAML in {path}: {error}") from error
48
+ require(value is None or isinstance(value, dict), "invalid_task", f"Task header must be a mapping: {path}")
49
+ value = value or {}
50
+ allowed = {"dependsOn", "specs", "workspace", *STUB_FIELDS}
51
+ require(not set(value) - allowed, "invalid_task", f"Unknown Task header fields in {path}: {sorted(set(value) - allowed)}")
52
+ return value
53
+
54
+
55
+ def _identities(value: Any, label: str) -> tuple[str, ...]:
56
+ require(isinstance(value, list) and all(isinstance(item, str) and item.strip() for item in value),
57
+ "invalid_task", f"{label} must be an array of nonempty IDs.")
58
+ require(len(value) == len(set(value)), "invalid_task", f"{label} contains duplicate IDs.")
59
+ return tuple(value)
60
+
61
+
62
+ def _stub_refs(value: Any, label: str, stubs: dict[str, StubDefinition]) -> tuple[str, ...]:
63
+ require(isinstance(value, list), "invalid_task", f"{label} must be an array of Stub IDs and names.")
64
+ identities = []
65
+ for item in value:
66
+ require(isinstance(item, dict) and set(item) == {"id", "name"},
67
+ "invalid_task", f"{label} entries accept only id and name.")
68
+ identity = item["id"]
69
+ require(isinstance(identity, str) and identity in stubs,
70
+ "invalid_stub", f"{label} references unknown Stub: {identity}")
71
+ require(item["name"] == stubs[identity].name, "invalid_stub", f"{label}.{identity} has a different name from summary.md.")
72
+ identities.append(identity)
73
+ return _identities(identities, label)
74
+
75
+
76
+ def _task(path: Path, root: Path, stubs: dict[str, StubDefinition]) -> TaskDefinition:
77
+ require(path.resolve().is_relative_to(root), "invalid_task", f"Task file escapes the Plan: {path}")
78
+ identity = path.parent.name
79
+ require(re.fullmatch(r"T[0-9]+", identity) is not None,
80
+ "invalid_task", f"Use a Task directory ID such as T01: {path.parent}")
81
+ body = read_text(path)
82
+ header = _header(body, path)
83
+ require(not stubs or all(field in header for field in STUB_FIELDS),
84
+ "invalid_task", f"Declare installs, fills and uses (empty arrays when unused) in {path}.")
85
+ dependencies = _identities(header.get("dependsOn", []), f"{identity}.dependsOn")
86
+ specs = _identities(header.get("specs", []), f"{identity}.specs")
87
+ workspace = header.get("workspace")
88
+ require(workspace is None or isinstance(workspace, str) and bool(workspace.strip()),
89
+ "invalid_task", f"{identity}.workspace must be a nonempty path.")
90
+ refs = {field: _stub_refs(header.get(field, []), f"{identity}.{field}", stubs) for field in STUB_FIELDS}
91
+ return TaskDefinition(identity, path, body, dependencies, specs, workspace, **refs)
92
+
93
+
94
+ def _stubs(summary: str) -> dict[str, StubDefinition]:
95
+ result: dict[str, StubDefinition] = {}
96
+ opened: tuple[str, int] | None = None
97
+ markers = list(re.finditer(r"<!--\s*(/?)harness:stub\b(.*?)-->", summary, re.DOTALL))
98
+ require(len(markers) == len(re.findall(r"<!--\s*/?harness:stub\b", summary)),
99
+ "invalid_stub", "Unclosed Stub marker comment in summary.md.")
100
+ for marker in markers:
101
+ closing, identity = marker[1], marker[2].strip()
102
+ require(re.fullmatch(r"S[0-9]+", identity) is not None, "invalid_stub", f"Invalid Stub ID in summary.md: {identity}")
103
+ if not closing:
104
+ require(opened is None and identity not in result, "invalid_stub", f"Duplicate or nested Stub block in summary.md: {identity}")
105
+ opened = identity, marker.end()
106
+ continue
107
+ require(opened is not None and opened[0] == identity, "invalid_stub", f"Unmatched Stub closing marker in summary.md: {identity}")
108
+ assert opened is not None
109
+ body = summary[opened[1]:marker.start()].strip()
110
+ title, _, content = body.partition("\n")
111
+ heading = re.fullmatch(rf"### {identity} (\S[^\r\n]*)", title.strip())
112
+ require(heading is not None and bool(content.strip()), "invalid_stub", f"Stub {identity} needs a '### {identity} NAME' heading and requirements in summary.md.")
113
+ assert heading is not None
114
+ result[identity] = StubDefinition(identity, heading[1].strip(), body)
115
+ opened = None
116
+ require(opened is None, "invalid_stub", f"Unclosed Stub block in summary.md: {opened}")
117
+ return result
118
+
119
+
120
+ def read_definition(root: Path) -> PlanDefinition:
121
+ root = root.resolve()
122
+ require(root.is_dir(), "plan_unreadable", f"Plan directory does not exist: {root}")
123
+ summary_path = root / "summary.md"
124
+ require(summary_path.resolve().is_relative_to(root), "plan_unreadable", "summary.md escapes the Plan.")
125
+ summary = read_text(summary_path)
126
+ require("<!-- to-plan:data -->" not in summary and not any((root / "tasks").glob("T[0-9]*.md")),
127
+ "unsupported_plan", f"Unsupported Plan layout. {REBUILD_INSTRUCTION}")
128
+ stubs = _stubs(summary)
129
+ tasks = tuple(_task(path, root, stubs) for path in sorted((root / "tasks").glob("*/task.md")))
130
+ require(bool(tasks), "invalid_plan", f"Create at least one tasks/T01/task.md under {root}.")
131
+ return PlanDefinition(root, tasks, tuple(stubs.values()))
@@ -0,0 +1,61 @@
1
+ """Plan definitions and the six current states."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from dataclasses import dataclass
6
+ from enum import StrEnum
7
+ from pathlib import Path
8
+ from typing import Any, Final
9
+
10
+ from trigrams_toolkit.shared.errors import ProtocolError
11
+
12
+ JsonObject = dict[str, Any]
13
+
14
+
15
+ class Status(StrEnum):
16
+ PENDING = "pending"
17
+ DOING = "doing"
18
+ REWORK = "rework"
19
+ BLOCKED = "blocked"
20
+ DONE = "done"
21
+ CANCELLED = "cancelled"
22
+
23
+
24
+ MARK_STATES: Final = (Status.PENDING, Status.DOING, Status.REWORK, Status.DONE)
25
+ ACTIVE_STATES: Final = (Status.PENDING, Status.DOING, Status.REWORK)
26
+ REBUILD_INSTRUCTION: Final = "Archive the old state and rebuild the Plan with initialize."
27
+ STUB_FIELDS: Final = ("installs", "fills", "uses")
28
+ SCHEDULE_FIELDS: Final = ("dependsOn", *STUB_FIELDS)
29
+
30
+
31
+ class PlanError(ProtocolError):
32
+ def __init__(self, code: str, message: str, issues: list[JsonObject]) -> None:
33
+ super().__init__(code, message)
34
+ self.issues = issues
35
+
36
+
37
+ @dataclass(frozen=True)
38
+ class StubDefinition:
39
+ identity: str
40
+ name: str
41
+ body: str
42
+
43
+
44
+ @dataclass(frozen=True)
45
+ class TaskDefinition:
46
+ identity: str
47
+ path: Path
48
+ body: str
49
+ dependencies: tuple[str, ...] = ()
50
+ specs: tuple[str, ...] = ()
51
+ workspace: str | None = None
52
+ installs: tuple[str, ...] = ()
53
+ fills: tuple[str, ...] = ()
54
+ uses: tuple[str, ...] = ()
55
+
56
+
57
+ @dataclass(frozen=True)
58
+ class PlanDefinition:
59
+ root: Path
60
+ tasks: tuple[TaskDefinition, ...]
61
+ stubs: tuple[StubDefinition, ...] = ()
@@ -0,0 +1,126 @@
1
+ """One dependency model for validation, eligibility and state transitions."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from dataclasses import dataclass
6
+ import heapq
7
+
8
+ from trigrams_toolkit.shared.errors import require
9
+ from .model import JsonObject, PlanDefinition, PlanError, Status, TaskDefinition
10
+
11
+
12
+ @dataclass(frozen=True)
13
+ class Schedule:
14
+ predecessors: dict[str, set[str]]
15
+ producers: dict[str, tuple[str, str]]
16
+ order: tuple[str, ...]
17
+
18
+
19
+ def _cycle(graph: dict[str, set[str]], unresolved: set[str]) -> list[str]:
20
+ # Follow predecessor links; reverse the result to report execution direction.
21
+ path: list[str] = []
22
+ positions: dict[str, int] = {}
23
+ current = min(unresolved)
24
+ while current not in positions:
25
+ positions[current] = len(path)
26
+ path.append(current)
27
+ current = min(graph[current] & unresolved)
28
+ return list(reversed([*path[positions[current]:], current]))
29
+
30
+
31
+ def _order(graph: dict[str, set[str]]) -> tuple[str, ...]:
32
+ successors: dict[str, list[str]] = {identity: [] for identity in graph}
33
+ indegrees = {identity: len(dependencies) for identity, dependencies in graph.items()}
34
+ for identity, dependencies in graph.items():
35
+ for predecessor in dependencies:
36
+ successors[predecessor].append(identity)
37
+ ready = [identity for identity, degree in indegrees.items() if degree == 0]
38
+ heapq.heapify(ready)
39
+ ordered = []
40
+ while ready:
41
+ identity = heapq.heappop(ready)
42
+ ordered.append(identity)
43
+ for successor in successors[identity]:
44
+ indegrees[successor] -= 1
45
+ if indegrees[successor] == 0:
46
+ heapq.heappush(ready, successor)
47
+ unresolved = set(graph) - set(ordered)
48
+ if unresolved:
49
+ chain = _cycle(graph, unresolved)
50
+ raise PlanError("dependency_cycle", "Dependency cycle: " + " -> ".join(chain), [{"chain": chain}])
51
+ return tuple(ordered)
52
+
53
+
54
+ def build_schedule(definition: PlanDefinition) -> Schedule:
55
+ graph = {task.identity: set(task.dependencies) for task in definition.tasks}
56
+ stub_ids = {stub.identity for stub in definition.stubs}
57
+ for task in definition.tasks:
58
+ missing = set(task.dependencies) - graph.keys()
59
+ require(not missing, "invalid_dependency", f"{task.identity} references missing Tasks: {sorted(missing)}")
60
+ unknown = set((*task.installs, *task.fills, *task.uses)) - stub_ids
61
+ require(not unknown, "invalid_stub", f"{task.identity} references missing Stubs: {sorted(unknown)}")
62
+ producers = {}
63
+ for stub in definition.stubs:
64
+ installers = [task.identity for task in definition.tasks if stub.identity in task.installs]
65
+ fillers = [task.identity for task in definition.tasks if stub.identity in task.fills]
66
+ require(len(installers) == len(fillers) == 1, "invalid_stub",
67
+ f"{stub.identity} requires exactly one installer and one filler; installs={installers}, fills={fillers}.")
68
+ require(installers[0] != fillers[0], "invalid_stub", f"{stub.identity} must be installed and filled by different Tasks.")
69
+ producers[stub.identity] = installers[0], fillers[0]
70
+ for task in definition.tasks:
71
+ graph[task.identity].update(producers[identity][0] for identity in (*task.fills, *task.uses))
72
+ return Schedule(graph, producers, _order(graph))
73
+
74
+
75
+ def stub_states(schedule: Schedule, tasks: JsonObject) -> dict[str, str]:
76
+ result = {}
77
+ for identity, (installer, filler) in schedule.producers.items():
78
+ status = "uninstalled"
79
+ if tasks[installer]["status"] == Status.DONE:
80
+ status = "filled" if tasks[filler]["status"] == Status.DONE else "installed"
81
+ result[identity] = status
82
+ return result
83
+
84
+
85
+ def blockers(task: TaskDefinition, state: JsonObject) -> list[JsonObject]:
86
+ result = [{"type": "task", "id": identity, "required": "done"}
87
+ for identity in task.dependencies if state["tasks"][identity]["status"] != Status.DONE]
88
+ for identity in sorted(set((*task.fills, *task.uses))):
89
+ if state["stubs"][identity]["status"] == "uninstalled":
90
+ result.append({"type": "stub", "id": identity, "required": "installed"})
91
+ return result
92
+
93
+
94
+ def validate_current(definition: PlanDefinition, state: JsonObject) -> None:
95
+ issues = []
96
+ for task in definition.tasks:
97
+ if state["tasks"][task.identity]["status"] not in (Status.DOING, Status.DONE):
98
+ continue
99
+ unmet = blockers(task, state)
100
+ if unmet:
101
+ issues.append({"task": task.identity, "blockers": unmet})
102
+ if issues:
103
+ raise PlanError("invalid_progress", "Active or completed Tasks have unmet prerequisites.", issues)
104
+ if state["status"] == Status.DONE:
105
+ unfinished = [identity for identity, record in state["tasks"].items()
106
+ if record["status"] not in (Status.DONE, Status.CANCELLED)]
107
+ unfilled = [identity for identity, record in state["stubs"].items() if record["status"] != "filled"]
108
+ require(not unfinished and not unfilled, "not_ready", f"Plan has unfinished Tasks {unfinished} or Stubs {unfilled}.")
109
+
110
+
111
+ def validate_completion(schedule: Schedule, state: JsonObject) -> None:
112
+ reachable: set[str] = set()
113
+ issues = []
114
+ for identity in schedule.order:
115
+ if state["tasks"][identity]["status"] == Status.CANCELLED:
116
+ continue
117
+ unmet = schedule.predecessors[identity] - reachable
118
+ if unmet:
119
+ issues.append({"task": identity, "unreachablePredecessors": sorted(unmet)})
120
+ else:
121
+ reachable.add(identity)
122
+ for identity, producers in schedule.producers.items():
123
+ if not set(producers) <= reachable:
124
+ issues.append({"stub": identity, "unreachableProducers": sorted(set(producers) - reachable)})
125
+ if issues:
126
+ raise PlanError("unreachable_plan", "Cancelled prerequisites prevent this Plan from completing.", issues)
@@ -0,0 +1,139 @@
1
+ """Read Plan handoffs and atomically maintain declaration snapshots and progress."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from pathlib import Path
6
+ from typing import Callable
7
+
8
+ from trigrams_toolkit.shared.errors import require
9
+ from trigrams_toolkit.shared.paths import confined
10
+ from trigrams_toolkit.shared.serialization import canonical, read_json
11
+ from .definitions import read_definition
12
+ from trigrams_toolkit.shared.locking import atomic_write, locked
13
+ from .model import ACTIVE_STATES, JsonObject, PlanDefinition, SCHEDULE_FIELDS, Status, TaskDefinition
14
+ from .scheduling import Schedule, blockers, build_schedule, validate_completion
15
+ from .state import change_state, compile_state, read_state, read_stored
16
+
17
+
18
+ def _task_view(task: TaskDefinition, state: JsonObject) -> JsonObject:
19
+ result = {**state["tasks"][task.identity], "path": str(task.path), "blockers": blockers(task, state)}
20
+ if task.workspace is not None:
21
+ result["workspace"] = task.workspace
22
+ return result
23
+
24
+
25
+ def _compact_progress(record: JsonObject) -> JsonObject:
26
+ return {key: record[key] for key in ("status", "note", "reason", "workspace", "blockers")
27
+ if record.get(key)}
28
+
29
+
30
+ def _contents(directory: Path, root: Path) -> list[str]:
31
+ entries = []
32
+ for path in sorted(directory.rglob("*")):
33
+ require(path.resolve().is_relative_to(root), "invalid_task", f"Task content escapes the Plan: {path}")
34
+ if path.is_file():
35
+ entries.append(path.relative_to(directory).as_posix())
36
+ return entries
37
+
38
+
39
+ class PlanService:
40
+ def __init__(self, root: Path) -> None:
41
+ self.root = root.resolve()
42
+
43
+ def _load(self, *, required: bool = False) -> tuple[PlanDefinition, Schedule, JsonObject]:
44
+ definition = read_definition(self.root)
45
+ schedule = build_schedule(definition)
46
+ return definition, schedule, read_state(definition, required=required)
47
+
48
+ def _candidate(self) -> JsonObject:
49
+ definition = read_definition(self.root)
50
+ schedule = build_schedule(definition)
51
+ candidate = compile_state(definition, read_stored(self.root, allow_legacy=True))
52
+ validate_completion(schedule, candidate)
53
+ return candidate
54
+
55
+ def _save(self, state: JsonObject) -> bool:
56
+ path = self.root / "plan.json"
57
+ changed = not path.exists() or read_json(path) != state
58
+ if changed:
59
+ atomic_write(path, canonical(state) + b"\n")
60
+ return changed
61
+
62
+ def validate(self, *, sync: bool = False) -> JsonObject:
63
+ if not sync:
64
+ _, schedule, state = self._load(required=True)
65
+ validate_completion(schedule, state)
66
+ return {"valid": True, "changed": False}
67
+ self._candidate()
68
+ with locked(confined(self.root, ".plan.lock"), timeout=0):
69
+ candidate = self._candidate()
70
+ changed = self._save(candidate)
71
+ return {"valid": True, "changed": changed}
72
+
73
+ def get_tasks(self) -> JsonObject:
74
+ definition, schedule, state = self._load(required=True)
75
+ validate_completion(schedule, state)
76
+ ready = []
77
+ waiting = {}
78
+ active = state["status"] in ACTIVE_STATES
79
+ for task in definition.tasks:
80
+ record = state["tasks"][task.identity]
81
+ unmet = blockers(task, state)
82
+ if record["status"] == Status.BLOCKED:
83
+ waiting[task.identity] = [*unmet, {"type": "manual", "reason": record["reason"]}]
84
+ elif record["status"] in (Status.PENDING, Status.REWORK):
85
+ if unmet:
86
+ waiting[task.identity] = unmet
87
+ elif active:
88
+ ready.append({"id": task.identity, "path": str(task.path)})
89
+ return {"status": state["status"], "ready": ready, "waiting": waiting}
90
+
91
+ def inspect(self, target: str | None = None,
92
+ locate_spec: Callable[[str], JsonObject] | None = None, *, full: bool = False) -> JsonObject:
93
+ definition, _, state = self._load()
94
+ if target is None:
95
+ if full:
96
+ return {**state, "directory": str(self.root), "summary": str(self.root / "summary.md"),
97
+ "tasks": {task.identity: _task_view(task, state) for task in definition.tasks}}
98
+ result = {"directory": str(self.root), **_compact_progress(state),
99
+ "tasks": {task.identity: _compact_progress(_task_view(task, state))
100
+ for task in definition.tasks}}
101
+ if state["stubs"]:
102
+ result["stubs"] = state["stubs"]
103
+ return result
104
+ task = next((task for task in definition.tasks if task.identity == target), None)
105
+ require(task is not None, "unknown_task", f"Task {target} does not exist in {self.root}.")
106
+ assert task is not None
107
+ selected = set((*task.installs, *task.fills, *task.uses))
108
+ view = _task_view(task, state)
109
+ result = {"id": target, **view} if full else {
110
+ "id": target, "path": str(task.path), **_compact_progress(view)}
111
+ if full:
112
+ result.update(directory=str(task.path.parent), body=task.body,
113
+ contents=_contents(task.path.parent, self.root))
114
+ stubs = {stub.identity: {**state["stubs"][stub.identity], **({"body": stub.body} if full else {})}
115
+ for stub in definition.stubs if stub.identity in selected}
116
+ if stubs or full:
117
+ result["stubs"] = stubs
118
+ if task.specs or full:
119
+ result["specs"] = [locate_spec(identity) if locate_spec is not None else {"id": identity}
120
+ for identity in task.specs]
121
+ return result
122
+
123
+ def update(self, target: str | None, record: JsonObject) -> JsonObject:
124
+ definition, _, current = self._load(required=True)
125
+ change_state(definition, current, target, record)
126
+ with locked(confined(self.root, ".plan.lock"), timeout=0):
127
+ definition, _, current = self._load(required=True)
128
+ updated = change_state(definition, current, target, record)
129
+ changed = self._save(updated)
130
+ selected = updated if target is None else updated["tasks"][target]
131
+ progress = {key: value for key, value in selected.items() if key not in (*SCHEDULE_FIELDS, "tasks", "stubs")}
132
+ result = {"changed": changed, "directory": str(self.root), **progress}
133
+ if target is not None:
134
+ result["id"] = target
135
+ changes = {identity: stub["status"] for identity, stub in updated["stubs"].items()
136
+ if stub["status"] != current["stubs"][identity]["status"]}
137
+ if changes:
138
+ result["stubChanges"] = changes
139
+ return result
@@ -0,0 +1,146 @@
1
+ """Compile declaration snapshots and preserve validated current progress."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import copy
6
+ from pathlib import Path
7
+
8
+ from jsonschema import Draft202012Validator
9
+
10
+ from trigrams_toolkit.shared.errors import require
11
+ from trigrams_toolkit.shared.serialization import read_json
12
+ from .model import (ACTIVE_STATES, JsonObject, PlanDefinition, PlanError, REBUILD_INSTRUCTION,
13
+ SCHEDULE_FIELDS, STUB_FIELDS, Status, StubDefinition, TaskDefinition)
14
+ from .scheduling import blockers, build_schedule, stub_states, validate_current
15
+
16
+ from trigrams_toolkit.resources import resource_path
17
+
18
+ SCHEMA_PATH = resource_path("plan/plan.schema.json")
19
+
20
+
21
+ def _validate_schema(value: JsonObject, *, legacy: bool = False, record: bool = False) -> None:
22
+ schema = read_json(SCHEMA_PATH)
23
+ if legacy:
24
+ schema["required"].remove("stubs")
25
+ del schema["properties"]["stubs"]
26
+ schema["properties"]["tasks"]["additionalProperties"] = {"$ref": "#/$defs/record"}
27
+ schema["properties"]["tasks"].pop("minProperties", None)
28
+ if record:
29
+ schema = {"$defs": schema["$defs"], "$ref": "#/$defs/record"}
30
+ issues = [{"path": "/" + "/".join(map(str, error.absolute_path)), "message": error.message}
31
+ for error in Draft202012Validator(schema).iter_errors(value)]
32
+ if issues:
33
+ raise PlanError("invalid_state", "Invalid Plan state; see issues for field locations.", issues)
34
+
35
+
36
+ def task_snapshot(task: TaskDefinition) -> JsonObject:
37
+ return {"dependsOn": sorted(task.dependencies), **{field: sorted(getattr(task, field)) for field in STUB_FIELDS}}
38
+
39
+
40
+ def _stored_definition(root: Path, state: JsonObject) -> PlanDefinition:
41
+ tasks = tuple(TaskDefinition(identity, root / f"tasks/{identity}/task.md", "",
42
+ tuple(record["dependsOn"]), installs=tuple(record["installs"]), fills=tuple(record["fills"]), uses=tuple(record["uses"]))
43
+ for identity, record in state["tasks"].items())
44
+ stubs = tuple(StubDefinition(identity, record["name"], "") for identity, record in state["stubs"].items())
45
+ return PlanDefinition(root, tasks, stubs)
46
+
47
+
48
+ def _validate_progress(root: Path, state: JsonObject) -> None:
49
+ definition = _stored_definition(root, state)
50
+ expected = stub_states(build_schedule(definition), state["tasks"])
51
+ for identity, status in expected.items():
52
+ require(state["stubs"][identity]["status"] == status, "invalid_state",
53
+ f"Stub {identity} status does not match its completed producer Tasks.")
54
+ validate_current(definition, state)
55
+
56
+
57
+ def read_stored(root: Path, *, allow_legacy: bool = False) -> JsonObject | None:
58
+ path = root / "plan.json"
59
+ if not path.exists():
60
+ return None
61
+ require(path.resolve().is_relative_to(root), "invalid_state", "plan.json escapes the Plan.")
62
+ value = read_json(path)
63
+ require(not isinstance(value, dict) or "schemaVersion" not in value and "schema_version" not in value,
64
+ "unsupported_plan", f"Unsupported Plan state. {REBUILD_INSTRUCTION}")
65
+ legacy = isinstance(value, dict) and "stubs" not in value
66
+ _validate_schema(value, legacy=legacy)
67
+ require(not legacy or allow_legacy, "definition_out_of_sync", "Run validate PLAN --sync to compile the declaration snapshot.")
68
+ if not legacy:
69
+ _validate_progress(root, value)
70
+ return value
71
+
72
+
73
+ def _guard_revision(definition: PlanDefinition, current: JsonObject) -> None:
74
+ existing = current["tasks"]
75
+ declared = {task.identity: task for task in definition.tasks}
76
+ for identity, record in existing.items():
77
+ if identity not in declared:
78
+ require(record["status"] == Status.PENDING, "progress_conflict", f"Do not remove started Task {identity}; preserve its progress.")
79
+ continue
80
+ if record["status"] not in (Status.DOING, Status.DONE):
81
+ continue
82
+ expected = task_snapshot(declared[identity])
83
+ fields = SCHEDULE_FIELDS if "stubs" in current else STUB_FIELDS
84
+ require(all(record.get(field, []) == expected[field] for field in fields), "progress_conflict",
85
+ f"Do not change handoff declarations of active or completed Task {identity}.")
86
+ retained = {stub.identity for stub in definition.stubs}
87
+ for identity, record in current.get("stubs", {}).items():
88
+ require(identity in retained or record["status"] == "uninstalled", "progress_conflict",
89
+ f"Do not discard accepted Stub {identity}.")
90
+
91
+
92
+ def compile_state(definition: PlanDefinition, current: JsonObject | None) -> JsonObject:
93
+ if current is not None:
94
+ _guard_revision(definition, current)
95
+ result = {key: value for key, value in (current or {"status": Status.PENDING}).items() if key not in ("tasks", "stubs")}
96
+ previous = current["tasks"] if current is not None else {}
97
+ result["tasks"] = {}
98
+ for task in definition.tasks:
99
+ progress = {key: value for key, value in previous.get(task.identity, {"status": Status.PENDING}).items()
100
+ if key not in SCHEDULE_FIELDS}
101
+ result["tasks"][task.identity] = {**progress, **task_snapshot(task)}
102
+ stages = stub_states(build_schedule(definition), result["tasks"])
103
+ result["stubs"] = {stub.identity: {"name": stub.name, "status": stages[stub.identity]} for stub in definition.stubs}
104
+ _validate_schema(result)
105
+ validate_current(definition, result)
106
+ return result
107
+
108
+
109
+ def read_state(definition: PlanDefinition, *, required: bool = False) -> JsonObject:
110
+ current = read_stored(definition.root)
111
+ if current is None:
112
+ require(not required, "missing_state", "Run validate PLAN --sync before scheduling this Plan.")
113
+ return compile_state(definition, None)
114
+ expected_tasks = {task.identity: task_snapshot(task) for task in definition.tasks}
115
+ stored_tasks = {identity: {field: record[field] for field in SCHEDULE_FIELDS}
116
+ for identity, record in current["tasks"].items()}
117
+ names = {stub.identity: stub.name for stub in definition.stubs}
118
+ require(expected_tasks == stored_tasks and names == {identity: record["name"] for identity, record in current["stubs"].items()},
119
+ "definition_out_of_sync", "Plan declarations changed; run validate PLAN --sync before scheduling.")
120
+ return current
121
+
122
+
123
+ def change_state(definition: PlanDefinition, state: JsonObject, target: str | None,
124
+ record: JsonObject) -> JsonObject:
125
+ _validate_schema(record, record=True)
126
+ status = record["status"]
127
+ if target is not None:
128
+ task = next((task for task in definition.tasks if task.identity == target), None)
129
+ require(task is not None, "unknown_task", f"Task {target} does not exist in {definition.root}.")
130
+ assert task is not None
131
+ if status == Status.DOING and state["tasks"][target]["status"] != Status.DOING:
132
+ require(state["status"] in ACTIVE_STATES, "not_ready", "Resume the Plan before starting a Task.")
133
+ if status in (Status.DOING, Status.REWORK, Status.DONE):
134
+ unmet = blockers(task, state)
135
+ if unmet:
136
+ raise PlanError("not_ready", f"Task {target} has unmet prerequisites.", [{"task": target, "blockers": unmet}])
137
+ updated = copy.deepcopy(state)
138
+ if target is None:
139
+ updated = {**record, "tasks": updated["tasks"], "stubs": updated["stubs"]}
140
+ else:
141
+ assert task is not None
142
+ updated["tasks"][target] = {**record, **task_snapshot(task)}
143
+ for identity, status in stub_states(build_schedule(definition), updated["tasks"]).items():
144
+ updated["stubs"][identity]["status"] = status
145
+ validate_current(definition, updated)
146
+ return updated
@@ -0,0 +1,16 @@
1
+ """The physical working directory is the project root for all public CLIs."""
2
+ from pathlib import Path
3
+
4
+ from trigrams_toolkit.shared.errors import require
5
+
6
+
7
+ def current_project_root(cwd: Path | None = None) -> Path:
8
+ try:
9
+ root = (Path.cwd() if cwd is None else cwd).resolve(strict=True)
10
+ except RuntimeError as error:
11
+ raise OSError(str(error)) from error
12
+ require(root.is_dir(), "invalid_reference", f"Project root must be a directory: {root}")
13
+ return root
14
+
15
+
16
+ __all__ = ["current_project_root"]
@@ -0,0 +1,36 @@
1
+ """Native physical paths, including nonexistent final components."""
2
+ from __future__ import annotations
3
+
4
+ import errno
5
+ import os
6
+ from pathlib import Path
7
+
8
+ from trigrams_toolkit.shared.errors import require
9
+
10
+
11
+ def physical_path(value: Path) -> Path:
12
+ try:
13
+ return value.resolve()
14
+ except RuntimeError as error:
15
+ raise OSError(errno.ELOOP, str(error), str(value)) from error
16
+
17
+
18
+ def path_key(value: Path | str) -> str:
19
+ path = str(value)
20
+ if os.name == "nt":
21
+ if path.startswith("\\\\?\\UNC\\"):
22
+ path = "\\\\" + path[8:]
23
+ elif path.startswith("\\\\?\\"):
24
+ path = path[4:]
25
+ return os.path.normcase(os.path.normpath(path))
26
+
27
+
28
+ def within(root: Path, target: Path) -> bool:
29
+ return Path(path_key(target)).is_relative_to(Path(path_key(root)))
30
+
31
+
32
+ def confined(root: Path, value: Path | str) -> Path:
33
+ require(bool(str(value)) and "\0" not in str(value), "invalid_reference", "Expected a project path.")
34
+ target = physical_path(root / value)
35
+ require(within(root.resolve(strict=True), target), "path_outside_root", f"Real path escapes project: {value}")
36
+ return target
File without changes