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,49 @@
1
+ """Command help for project installation and explicit path archival."""
2
+ from pathlib import Path
3
+ from typing import Sequence
4
+
5
+ from trigrams_toolkit.shared.cli_help import HelpSchemas, render_help
6
+ from trigrams_toolkit.resources import resource_path, schema_paths
7
+ from trigrams_toolkit.shared.serialization import read_json
8
+
9
+ FIELDS = {
10
+ "agent": "Vercel agent: codex, claude-code or pi. Omitted uses the project record or codex.",
11
+ "packages": "Explicit absolute source roots for local development.",
12
+ "extensions": "Selected extension names; omit to retain, or pass [] to remove all.",
13
+ "platforms": "Target hosts: codex, claude, pi-web; select any combination.",
14
+ "preview": "Exact reviewed preview returned by install preview.",
15
+ "confirmedBy": "Approver identity: {id, kind}; kind is human, agent or service.",
16
+ }
17
+
18
+
19
+ def options(mutation: bool) -> list[tuple[str, str]]:
20
+ rows = [
21
+ ("--input FILE|-", "Required. UTF-8 JSON file, or - for stdin."),
22
+ ]
23
+ if mutation:
24
+ rows.extend([("--request-id req_ID", "Required. Latest write identity; an identical successful retry returns its receipt."),
25
+ ("--expected-revision N", "Required. Use the preview baseRevision.")])
26
+ return rows
27
+
28
+
29
+ def help_text(tool: str, argv: Sequence[str]) -> str:
30
+ commands = read_json(resource_path("installation/commands.json"))["commands"]
31
+ for item in commands:
32
+ action = item["name"].split()[-1]
33
+ if action == "archive":
34
+ item.update(summary="Move selected paths into .harness-archive without parsing their contents.",
35
+ usage="PATH [PATH ...]", options=[],
36
+ arguments=[("PATH", "Project-relative file or directory; repeat for multiple paths.")],
37
+ notes="Run from the target project root.",
38
+ result="JSON data contains the archive directory and original relative paths.")
39
+ continue
40
+ item.update(summary={"preview": "Compute a read-only, offline preview before project changes.",
41
+ "apply": "Apply reviewed changes; keep one backup and roll back write errors."}[action],
42
+ usage="--input FILE|- [options]", options=options(item["mutation"]), fields=FIELDS,
43
+ group_summary="Preview and install project resource snapshots.",
44
+ notes={"preview": "Run from the target project root. The preview binds apply to this directory.",
45
+ "apply": "Run from the project root used for preview. Apply may install missing Skills "
46
+ "in the selected agent's global Skill directory."}[action],
47
+ result={"preview": "JSON data is the preview; retain it and baseRevision for apply.",
48
+ "apply": "JSON data contains operationId, phase, changed and stateRevision."}[action])
49
+ return render_help(tool, argv, commands, HelpSchemas(schema_paths()))
@@ -0,0 +1,73 @@
1
+ """Build the files owned by a provider snapshot."""
2
+ from __future__ import annotations
3
+
4
+ import os
5
+ from pathlib import Path
6
+
7
+ from trigrams_toolkit.handbook.package import ProviderPackage, manifest_owner, runtime_cache
8
+ from trigrams_toolkit.shared.errors import require
9
+ from trigrams_toolkit.shared.paths import confined, files_under, relative_path
10
+ from trigrams_toolkit.shared.serialization import canonical
11
+ from .operation_files import file_record
12
+
13
+
14
+ class ProjectMaterials:
15
+ def __init__(self, platforms: list[str]) -> None:
16
+ self.platforms = platforms
17
+ self.records: dict[str, dict] = {}
18
+ self.files: dict[str, bytes] = {}
19
+ self.path_keys: set[str] = set()
20
+
21
+ def add(self, name: str, provider: str, raw: bytes) -> None:
22
+ relative_path(name)
23
+ key = os.path.normcase(name)
24
+ require(key not in self.path_keys, "resource_conflict", f"Installation sources share a target: {name}")
25
+ self.path_keys.add(key)
26
+ self.records[name] = file_record(name, provider, raw)
27
+ self.files[name] = raw
28
+
29
+ def _copy(self, root: Path, source: Path, target: str, provider: str) -> None:
30
+ require(source != root, "invalid_reference", "An install mapping must select material within the provider.")
31
+ for path in files_under(root, source, exclude=runtime_cache):
32
+ suffix = path.relative_to(source).as_posix() if source.is_dir() else ""
33
+ name = f"{target}/{suffix}" if suffix else target
34
+ require(path.name.casefold() != "skill.md", "invalid_reference",
35
+ f"Install mappings cannot copy a Skill: {path}")
36
+ self.add(name, provider, path.read_bytes())
37
+
38
+ def extension(self, package: ProviderPackage) -> None:
39
+ root, manifest = package.root, package.manifest
40
+ owner = manifest_owner(manifest)
41
+ prefix = f".agents/extensions/{owner}"
42
+ self.add(f"{prefix}/extension.json", owner, canonical(manifest))
43
+ for folder in ("principles", "workbooks"):
44
+ source = root / folder
45
+ if source.exists():
46
+ self._copy(root, source, f"{prefix}/{folder}", owner)
47
+
48
+ def declared(self, package: ProviderPackage) -> None:
49
+ manifest, root = package.manifest, package.root
50
+ owner = manifest_owner(manifest)
51
+ for mapping in manifest["install"]:
52
+ if "platforms" in mapping and not set(mapping["platforms"]) & set(self.platforms):
53
+ continue
54
+ name = mapping["target"]
55
+ relative_path(name)
56
+ normalized = name.casefold()
57
+ prefix = f".agents/extensions/{owner}/"
58
+ owns_target = normalized.startswith(prefix) and normalized[len(prefix):].split("/")[0] not in (
59
+ "principles", "workbooks", "extension.json", "resources.json")
60
+ reserved = (".agents/skills", ".claude/skills", ".codex/skills",
61
+ ".pi/skills", ".pi/agent/skills", "skills-lock.json", ".git", ".harness",
62
+ ".harness-archive", ".project-state", ".agents/scripts", ".agents/tools",
63
+ ".agents/runtime", ".agents/harness.json", "docs", "agents.md", "claude.md",
64
+ "product.md", "design.md", "devtech.md", "readme.md", ".codex/agents",
65
+ ".claude/agents", ".pi/agents") + (() if owns_target else (".agents/extensions",))
66
+ require(not any(normalized == path or normalized.startswith(path + "/")
67
+ or path.startswith(normalized + "/") for path in reserved)
68
+ and not normalized.endswith("/project-tools.zip"),
69
+ "invalid_reference", f"Material target belongs to another project owner: {name}")
70
+ source = confined(root, mapping["source"])
71
+ require(not source.is_relative_to(root / "tools"),
72
+ "invalid_reference", f"Public tools cannot be installed as project material: {source}")
73
+ self._copy(root, source, name, owner)
@@ -0,0 +1,14 @@
1
+ """Apply installation ownership changes and retain only the latest backup."""
2
+ from pathlib import Path
3
+ from typing import Callable
4
+
5
+ from trigrams_toolkit.shared.schema import SchemaCatalog
6
+ from .installation_candidate import build_candidate
7
+ from .operation_runtime import OperationEngine
8
+
9
+
10
+ def apply_installation(project: Path, data: dict, schemas: SchemaCatalog, request_id: str, expected_revision: int,
11
+ *, checkpoint: Callable[[str], None] | None = None) -> dict:
12
+ engine = OperationEngine(project, schemas, checkpoint)
13
+ return engine.apply(data, request_id, expected_revision,
14
+ lambda preview: build_candidate(project, preview["parameters"], schemas, preview["operationId"]))
@@ -0,0 +1,34 @@
1
+ """Read current project installation ownership."""
2
+ from pathlib import Path
3
+
4
+ from trigrams_toolkit.shared.errors import ProtocolError, require
5
+ from trigrams_toolkit.shared.paths import is_link
6
+ from trigrams_toolkit.shared.schema import SchemaCatalog
7
+ from trigrams_toolkit.shared.serialization import read_json
8
+ from .operation_files import target_path, validate_owned_paths
9
+
10
+ INSTALLATION = ".agents/harness.json"
11
+ INSTALLATION_SCHEMA = "urn:harness:installation#/$defs/installation"
12
+ SNAPSHOT_SCHEMA = "urn:harness:installation#/$defs/snapshotInstallation"
13
+
14
+
15
+ def read_installation(project: Path, schemas: SchemaCatalog) -> dict | None:
16
+ path = target_path(project, INSTALLATION)
17
+ require(not is_link(path), "invalid_reference", f"Installation record must be a regular file: {path}")
18
+ if not path.exists():
19
+ return None
20
+ value = read_json(path)
21
+ try:
22
+ schemas.validate(INSTALLATION_SCHEMA, value)
23
+ except ProtocolError as error:
24
+ raise ProtocolError(error.code, f"{path}: {error}. Archive unsupported records before rebuilding.",
25
+ conflicts=(str(path),)) from error
26
+ extensions = [item["extension"] for item in value["extensions"]]
27
+ require(len(set(extensions)) == len(extensions), "resource_conflict", "Duplicate installed extension.")
28
+ validate_owned_paths([item["path"] for item in value["managed"]], INSTALLATION)
29
+ return value
30
+
31
+
32
+ def installation_record(path: Path, schemas: SchemaCatalog) -> dict:
33
+ return read_installation(path.parent.parent, schemas) or {
34
+ "schemaVersion": 2, "stateRevision": 0, "extensions": [], "platforms": [], "managed": []}
@@ -0,0 +1,94 @@
1
+ """File ownership and updates for project installation."""
2
+ from __future__ import annotations
3
+
4
+ from hashlib import sha256
5
+ import os
6
+ from pathlib import Path
7
+
8
+ from trigrams_toolkit.shared.errors import require
9
+ from trigrams_toolkit.shared.paths import is_link, relative_path
10
+ from trigrams_toolkit.shared.locking import atomic_write
11
+
12
+
13
+ def validate_owned_paths(paths: list[str], commit_path: str) -> None:
14
+ normalized = [os.path.normcase(path).replace("\\", "/") for path in paths]
15
+ marker = os.path.normcase(commit_path).replace("\\", "/")
16
+ require(len(normalized) == len(set(normalized)), "identity_conflict", "Duplicate managed paths.")
17
+ for index, path in enumerate(normalized):
18
+ relative_path(paths[index])
19
+ protected = (".git", ".harness", ".harness-archive", ".project-state", "docs", "skills-lock.json",
20
+ "agents.md", "claude.md", "product.md", "design.md", "devtech.md", "readme.md")
21
+ require(not any(path.casefold() == root or path.casefold().startswith(root + "/") for root in protected),
22
+ "invalid_reference", f"Managed target overlaps protected project content: {paths[index]}")
23
+ require(path != marker and not marker.startswith(path + "/") and not path.startswith(marker + "/"),
24
+ "invalid_reference", "Package target overlaps the installation record.")
25
+ require(not any(other.startswith(path + "/") or path.startswith(other + "/")
26
+ for other in normalized[:index]),
27
+ "identity_conflict", f"Managed targets overlap: {paths[index]}")
28
+
29
+
30
+ def target_path(project: Path, relative: str) -> Path:
31
+ relative_path(relative)
32
+ path = project / relative
33
+ require(path.parent.resolve() == path.parent,
34
+ "path_outside_root", f"Target parent is linked: {relative}")
35
+ return path
36
+
37
+
38
+ def blocked_parent(project: Path, path: Path) -> bool:
39
+ return any(parent.exists() and not parent.is_dir()
40
+ for parent in path.parents if parent != project and parent.is_relative_to(project))
41
+
42
+
43
+ def content_digest(raw: bytes) -> str:
44
+ return "sha256:" + sha256(raw).hexdigest()
45
+
46
+
47
+ def file_record(path: str, source: str, raw: bytes) -> dict:
48
+ return {"path": path, "source": source, "kind": "file", "contentDigest": content_digest(raw)}
49
+
50
+
51
+ def matches(path: Path, record: dict | None) -> bool:
52
+ if record is None:
53
+ return not os.path.lexists(path)
54
+ if is_link(path) or not path.is_file():
55
+ return False
56
+ return record.get("contentDigest") == content_digest(path.read_bytes())
57
+
58
+
59
+ def prune_extension_container(project: Path, path: Path) -> None:
60
+ parts = path.relative_to(project).parts
61
+ if len(parts) < 4 or parts[:2] != (".agents", "extensions"):
62
+ return
63
+ boundary, parent = project.joinpath(*parts[:3]), path.parent
64
+ while parent.is_relative_to(boundary):
65
+ if is_link(parent):
66
+ return
67
+ try:
68
+ parent.rmdir()
69
+ except OSError:
70
+ return
71
+ parent = parent.parent
72
+
73
+
74
+ def ordered_changes(changes: list, commit_path: str) -> list:
75
+ return sorted((c for c in changes if c["path"] != commit_path),
76
+ key=lambda c: (c["action"] != "remove", c["path"]))
77
+
78
+
79
+ def apply_change(project: Path, change: dict, raw: bytes | None) -> None:
80
+ path = target_path(project, change["path"])
81
+ if change["action"] == "remove":
82
+ remove_target(path)
83
+ prune_extension_container(project, path)
84
+ return
85
+ require(raw is not None, "invalid_reference", f"Missing installation bytes: {path}")
86
+ assert raw is not None
87
+ atomic_write(path, raw)
88
+
89
+
90
+ def remove_target(path: Path) -> None:
91
+ if is_link(path) and not path.is_symlink():
92
+ path.rmdir()
93
+ else:
94
+ path.unlink(missing_ok=True)
@@ -0,0 +1,144 @@
1
+ """Install managed materials with one backup and synchronous failure rollback."""
2
+ from __future__ import annotations
3
+
4
+ from dataclasses import dataclass
5
+ from pathlib import Path
6
+ from typing import Callable, Mapping, Any
7
+ import os
8
+ import re
9
+ import shutil
10
+
11
+ from trigrams_toolkit.shared.errors import require
12
+ from trigrams_toolkit.shared.paths import confined, is_link, path_key
13
+ from trigrams_toolkit.shared.schema import SchemaCatalog
14
+ from trigrams_toolkit.shared.serialization import canonical, parse_json, read_json
15
+ from trigrams_toolkit.shared.locking import atomic_write, locked
16
+ from trigrams_toolkit.shared.skill_installations import SkillAgent
17
+ from .global_skills import ensure_global_skills
18
+ from .operation_files import target_path, matches, apply_change, ordered_changes, remove_target, prune_extension_container
19
+ from .installation_sources import INSTALLATION, SNAPSHOT_SCHEMA, installation_record
20
+
21
+
22
+ @dataclass(frozen=True)
23
+ class OperationCandidate:
24
+ preview: dict[str, Any]
25
+ files: Mapping[str, bytes]
26
+ commit_path: str
27
+ changed: bool
28
+ dependency_agent: SkillAgent | None
29
+
30
+
31
+ class OperationEngine:
32
+ def __init__(self, project: Path, schemas: SchemaCatalog,
33
+ checkpoint: Callable[[str], None] | None = None) -> None:
34
+ self.project, self.schemas, self.checkpoint = project.resolve(), schemas, checkpoint
35
+
36
+ def _point(self, phase: str) -> None:
37
+ if self.checkpoint is not None:
38
+ self.checkpoint(phase)
39
+
40
+ def apply(self, data: dict, request_id: str, expected_revision: int,
41
+ rebuild: Callable[[dict], OperationCandidate]) -> dict:
42
+ self.schemas.validate("urn:harness:installation-cli#/$defs/applyInput", data)
43
+ self.schemas.validate("urn:harness:common#/$defs/revision", expected_revision)
44
+ require(re.fullmatch(r"req_[A-Za-z0-9_-]+", request_id) is not None,
45
+ "invalid_arguments", "Invalid request ID.")
46
+ preview = data["preview"]
47
+ preview_root = Path(preview["projectRoot"])
48
+ require(preview_root.is_absolute() and path_key(preview_root) == path_key(self.project),
49
+ "basis_changed", "Installation preview belongs to a different project. Run apply from its project root.")
50
+ request = {"data": data, "expectedRevision": expected_revision}
51
+ folder = target_path(self.project, ".harness/previous")
52
+ lock = target_path(self.project, ".harness/install.lock")
53
+ require(not is_link(folder) and not is_link(lock), "path_outside_root", "Installation storage cannot be linked.")
54
+ with locked(lock):
55
+ state = installation_record(target_path(self.project, INSTALLATION), self.schemas)
56
+ saved = read_json(folder / "receipt.json") if (folder / "receipt.json").is_file() else None
57
+ if saved is not None and saved["requestId"] == request_id and saved["phase"] == "committed":
58
+ require(saved["request"] == request and saved["result"]["stateRevision"] == state["stateRevision"],
59
+ "request_conflict", "Request ID already belongs to another installation.")
60
+ self._remove_storage("operations")
61
+ return saved["result"]
62
+ require(saved is None or saved["phase"] != "applying", "recovery_required",
63
+ "Restore .harness/previous before replacing an interrupted installation.")
64
+ require(expected_revision == preview["baseRevision"] == state["stateRevision"],
65
+ "revision_conflict", "Expected revision differs from current installation.")
66
+ candidate = rebuild(preview)
67
+ require(preview == candidate.preview, "basis_changed",
68
+ "Confirmed preview differs from current sources or target state. Refresh the preview.")
69
+ require(not preview["conflicts"], "local_modification",
70
+ "Installation preview contains conflicts. Review and preserve the indicated paths before retrying.",
71
+ *preview["conflicts"])
72
+ self._validate(candidate)
73
+ if candidate.dependency_agent is not None:
74
+ ensure_global_skills(candidate.dependency_agent, self.project)
75
+ self._remove_storage("previous")
76
+ folder.mkdir(parents=True)
77
+ changes = [*ordered_changes(preview["changes"], candidate.commit_path),
78
+ next(c for c in preview["changes"] if c["path"] == candidate.commit_path)]
79
+ for change in changes:
80
+ relative = change["path"]
81
+ if change["before"] is not None:
82
+ path = target_path(self.project, relative)
83
+ atomic_write(confined(folder / "backup", relative), path.read_bytes())
84
+ receipt = {"schemaVersion": 1, "requestId": request_id, "request": request,
85
+ "phase": "applying", "backups": changes, "result": None}
86
+ self.schemas.validate("urn:harness:installation#/$defs/operation", receipt)
87
+ atomic_write(folder / "receipt.json", canonical(receipt))
88
+ attempted = []
89
+ try:
90
+ self._point("backed_up")
91
+ for change in changes:
92
+ relative = change["path"]
93
+ path = target_path(self.project, relative)
94
+ require(matches(path, change["before"]), "local_modification", f"Target changed during install: {path}")
95
+ attempted.append(change)
96
+ apply_change(self.project, change, candidate.files.get(relative))
97
+ self._point("item:" + relative)
98
+ require(matches(path, change["after"]), "io_error", f"Installation failed: {path}")
99
+ result = {"operationId": preview["operationId"], "phase": "committed",
100
+ "changed": candidate.changed, "stateRevision": expected_revision + 1}
101
+ receipt.update(phase="committed", result=result)
102
+ self.schemas.validate("urn:harness:installation#/$defs/operation", receipt)
103
+ atomic_write(folder / "receipt.json", canonical(receipt))
104
+ except Exception:
105
+ for change in reversed(attempted):
106
+ path = target_path(self.project, change["path"])
107
+ before = change["before"]
108
+ if before is None:
109
+ remove_target(path)
110
+ prune_extension_container(self.project, path)
111
+ else:
112
+ restore = {"path": change["path"], "action": "write", "after": before}
113
+ raw = confined(folder / "backup", change["path"]).read_bytes()
114
+ apply_change(self.project, restore, raw)
115
+ receipt.update(phase="rolled_back", result=None)
116
+ atomic_write(folder / "receipt.json", canonical(receipt))
117
+ raise
118
+ self._remove_storage("operations")
119
+ return result
120
+
121
+ def _remove_storage(self, name: str) -> None:
122
+ path = self.project / ".harness" / name
123
+ require(not is_link(path)
124
+ and path.resolve().parent == (self.project / ".harness").resolve(),
125
+ "path_outside_root", "Installation backup must stay inside .harness.")
126
+ if path.exists():
127
+ shutil.rmtree(path)
128
+
129
+ def _validate(self, candidate: OperationCandidate) -> None:
130
+ require(candidate.commit_path == ".agents/harness.json", "invalid_reference",
131
+ "Installation must commit its ownership record.")
132
+ changes = candidate.preview["changes"]
133
+ names = [c["path"] for c in changes]
134
+ require(len(names) == len({os.path.normcase(p) for p in names}) and candidate.commit_path in names,
135
+ "invalid_reference", "Duplicate changes or missing installation record.")
136
+ require(set(candidate.files) == {c["path"] for c in changes if c["action"] == "write"},
137
+ "invalid_reference", "Candidate bytes do not match write changes.")
138
+ for change in changes:
139
+ path = target_path(self.project, change["path"])
140
+ require(matches(path, change["before"]), "local_modification", f"Target ownership changed: {path}")
141
+ for record in (change["before"], change["after"]):
142
+ require(record is None or record["path"] == change["path"],
143
+ "invalid_reference", "Ownership path differs from change path.")
144
+ self.schemas.validate(SNAPSHOT_SCHEMA, parse_json(candidate.files[candidate.commit_path]))
@@ -0,0 +1,48 @@
1
+ """Read YAML metadata used by toolkit packaging and installation."""
2
+ from __future__ import annotations
3
+
4
+ from pathlib import Path
5
+ from typing import Any
6
+
7
+ import yaml
8
+
9
+
10
+ class UniqueLoader(yaml.SafeLoader):
11
+ """Reject duplicate YAML keys in package metadata."""
12
+
13
+
14
+ def unique_mapping(loader: UniqueLoader, node: yaml.MappingNode) -> dict:
15
+ loader.flatten_mapping(node)
16
+ result = {}
17
+ for key_node, value_node in node.value:
18
+ key = loader.construct_object(key_node, deep=True)
19
+ if not isinstance(key, str) or key in result:
20
+ raise ValueError(f"Expected unique string YAML key: {key!r}")
21
+ result[key] = loader.construct_object(value_node, deep=True)
22
+ return result
23
+
24
+
25
+ UniqueLoader.add_constructor(yaml.resolver.BaseResolver.DEFAULT_MAPPING_TAG, unique_mapping)
26
+
27
+
28
+ def read_yaml(path: Path) -> dict[str, Any]:
29
+ value = yaml.load(path.read_text(encoding="utf-8-sig"), Loader=UniqueLoader)
30
+ if not isinstance(value, dict):
31
+ raise ValueError(f"Expected a YAML mapping: {path}")
32
+ return value
33
+
34
+
35
+ def frontmatter(path: Path) -> dict[str, Any]:
36
+ lines = path.read_text(encoding="utf-8-sig").splitlines()
37
+ if not lines or lines[0] != "---":
38
+ return {}
39
+ try:
40
+ end = lines.index("---", 1)
41
+ except ValueError as error:
42
+ raise ValueError(f"Unclosed YAML frontmatter: {path}") from error
43
+ value = yaml.load("\n".join(lines[1:end]), Loader=UniqueLoader)
44
+ if value is None:
45
+ return {}
46
+ if not isinstance(value, dict):
47
+ raise ValueError(f"Expected mapping frontmatter: {path}")
48
+ return value
@@ -0,0 +1,5 @@
1
+ """Current Plan files and state, with isolated read-only historical formats."""
2
+
3
+ from .service import PlanService
4
+
5
+ __all__ = ["PlanService"]
@@ -0,0 +1,136 @@
1
+ """Validate, inspect and schedule Plans with concise JSON results."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import argparse
6
+ from dataclasses import dataclass
7
+ import json
8
+ from pathlib import Path
9
+ import sys
10
+ from typing import NoReturn, Sequence
11
+
12
+ from trigrams_toolkit.project_context import current_project_root
13
+ from trigrams_toolkit.project_context.paths import confined
14
+ from trigrams_toolkit.shared.cli_help import HelpFormatter
15
+ from trigrams_toolkit.shared.errors import ProtocolError, require
16
+ from trigrams_toolkit.state import locate_identity
17
+ from trigrams_toolkit.version import version
18
+ from .model import JsonObject, MARK_STATES, Status
19
+ from .service import PlanService
20
+
21
+
22
+ @dataclass(frozen=True)
23
+ class Invocation:
24
+ operation: str
25
+ plan: Path
26
+ target: str | None
27
+ project_root: Path
28
+ record: JsonObject | None = None
29
+ sync: bool = False
30
+ full: bool = False
31
+
32
+
33
+ class Parser(argparse.ArgumentParser):
34
+ def error(self, message: str) -> NoReturn:
35
+ raise ProtocolError("invalid_arguments", message)
36
+
37
+
38
+ def parser() -> Parser:
39
+ root = Parser(prog="plan-toolkit", description="Validate Plan handoffs and record current state. "
40
+ "Run commands from the target project root.", formatter_class=HelpFormatter)
41
+ root.add_argument("-v", "--version", action="version", version=version())
42
+ commands = root.add_subparsers(dest="operation", required=True, title="Commands")
43
+ for operation, description in (
44
+ ("validate", "Check declarations, progress and completion; optionally sync the snapshot."),
45
+ ("get-task", "List Tasks eligible to start using current Stub and Task progress."),
46
+ ("inspect", "Read concise Plan or Task status; use --full for the complete view."),
47
+ ("mark", "Record pending, doing, rework or done."),
48
+ ("block", "Record a blocking reason."),
49
+ ("cancel", "Record a cancellation reason.")):
50
+ command = commands.add_parser(operation, help=description, description=description,
51
+ formatter_class=HelpFormatter,
52
+ epilog="Output: JSON; exit 0 on success, 1 on error.")
53
+ command.add_argument("plan", metavar="PLAN", type=Path, help="Plan directory within the current project root.")
54
+ if operation not in ("validate", "get-task"):
55
+ command.add_argument("target", metavar="TASK", nargs="?",
56
+ help="Task directory ID, for example T01; omit to target the Plan itself.")
57
+ if operation == "validate":
58
+ command.add_argument("--sync", action="store_true", help="Compile declarations, preserving existing progress.")
59
+ elif operation == "inspect":
60
+ command.add_argument("--full", action="store_true",
61
+ help="Include declarations, paths and Task/Stub bodies omitted by default.")
62
+ if operation == "mark":
63
+ command.add_argument("state", metavar="STATE", choices=MARK_STATES,
64
+ help="New state: pending, doing, rework or done.")
65
+ command.add_argument("--note", help="Optional note for this state.")
66
+ elif operation in ("block", "cancel"):
67
+ command.add_argument("--reason", required=True, help="Reason; for a block, include where to continue.")
68
+ return root
69
+
70
+
71
+ def _record(args: argparse.Namespace) -> JsonObject | None:
72
+ if args.operation in ("inspect", "validate", "get-task"):
73
+ return None
74
+ state = args.state if args.operation == "mark" else (
75
+ Status.BLOCKED if args.operation == "block" else Status.CANCELLED)
76
+ result = {"status": state}
77
+ for field in ("note", "reason"):
78
+ text = getattr(args, field, None)
79
+ if text is not None:
80
+ require(bool(text.strip()), "invalid_arguments", f"--{field} must not be empty.")
81
+ result[field] = text
82
+ return result
83
+
84
+
85
+ def parse_invocation(argv: Sequence[str]) -> Invocation:
86
+ args = parser().parse_args(argv)
87
+ record = _record(args)
88
+ project_root = current_project_root()
89
+ plan = confined(project_root, args.plan)
90
+ return Invocation(args.operation, plan, getattr(args, "target", None), project_root, record,
91
+ sync=getattr(args, "sync", False), full=getattr(args, "full", False))
92
+
93
+
94
+ def locate_spec(identity: str, invocation: Invocation) -> JsonObject:
95
+ try:
96
+ return {"id": identity, **locate_identity(invocation.project_root, identity)}
97
+ except ProtocolError as error:
98
+ return {"id": identity, "error": error.state_error()}
99
+ except (OSError, ValueError, TypeError, RecursionError) as error:
100
+ return {"id": identity, "error": {"code": "io_error", "message": str(error)}}
101
+
102
+
103
+ def dispatch(invocation: Invocation) -> JsonObject:
104
+ service = PlanService(invocation.plan)
105
+ if invocation.operation == "validate":
106
+ return service.validate(sync=invocation.sync)
107
+ if invocation.operation == "get-task":
108
+ return service.get_tasks()
109
+ if invocation.operation == "inspect":
110
+ return service.inspect(invocation.target, lambda identity: locate_spec(identity, invocation),
111
+ full=invocation.full)
112
+ require(invocation.record is not None, "invalid_arguments", "A state change requires a current-state record.")
113
+ assert invocation.record is not None
114
+ return service.update(invocation.target, invocation.record)
115
+
116
+
117
+ def main(argv: Sequence[str] | None = None) -> int:
118
+ arguments = list(sys.argv[1:] if argv is None else argv)
119
+ if hasattr(sys.stdout, "reconfigure"):
120
+ sys.stdout.reconfigure(encoding="utf-8")
121
+ try:
122
+ invocation = parse_invocation(arguments)
123
+ response = {"ok": True, "data": dispatch(invocation)}
124
+ except SystemExit as result:
125
+ return int(result.code or 0)
126
+ except ProtocolError as error:
127
+ issues = getattr(error, "issues", [{"code": error.code, "message": str(error)}])
128
+ response = {"ok": False, "error": {"code": error.code, "message": str(error), "issues": issues}}
129
+ except (OSError, UnicodeError) as error:
130
+ response = {"ok": False, "error": {"code": "io_error", "message": str(error)}}
131
+ print(json.dumps(response, ensure_ascii=False, allow_nan=False))
132
+ return 0 if response["ok"] else 1
133
+
134
+
135
+ if __name__ == "__main__":
136
+ raise SystemExit(main())