trigrams-toolkit 0.1.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- trigrams_toolkit/__init__.py +1 -0
- trigrams_toolkit/handbook/__init__.py +6 -0
- trigrams_toolkit/handbook/cli.py +122 -0
- trigrams_toolkit/handbook/guide_headers.py +43 -0
- trigrams_toolkit/handbook/guides.py +141 -0
- trigrams_toolkit/handbook/location.py +79 -0
- trigrams_toolkit/handbook/model.py +4 -0
- trigrams_toolkit/handbook/package.py +165 -0
- trigrams_toolkit/handbook/principle_import.py +101 -0
- trigrams_toolkit/handbook/project_resources.py +80 -0
- trigrams_toolkit/handbook/skill_sources.py +59 -0
- trigrams_toolkit/handbook/source_catalog.py +55 -0
- trigrams_toolkit/handbook/sources.py +16 -0
- trigrams_toolkit/installation/__init__.py +0 -0
- trigrams_toolkit/installation/archive_project.py +50 -0
- trigrams_toolkit/installation/global_skills.py +45 -0
- trigrams_toolkit/installation/harness_install.py +89 -0
- trigrams_toolkit/installation/installation_candidate.py +135 -0
- trigrams_toolkit/installation/installation_help.py +49 -0
- trigrams_toolkit/installation/installation_materials.py +73 -0
- trigrams_toolkit/installation/installation_service.py +14 -0
- trigrams_toolkit/installation/installation_sources.py +34 -0
- trigrams_toolkit/installation/operation_files.py +94 -0
- trigrams_toolkit/installation/operation_runtime.py +144 -0
- trigrams_toolkit/installation/package_metadata.py +48 -0
- trigrams_toolkit/plan/__init__.py +5 -0
- trigrams_toolkit/plan/cli.py +136 -0
- trigrams_toolkit/plan/definitions.py +131 -0
- trigrams_toolkit/plan/model.py +61 -0
- trigrams_toolkit/plan/scheduling.py +126 -0
- trigrams_toolkit/plan/service.py +139 -0
- trigrams_toolkit/plan/state.py +146 -0
- trigrams_toolkit/project_context/__init__.py +16 -0
- trigrams_toolkit/project_context/paths.py +36 -0
- trigrams_toolkit/py.typed +0 -0
- trigrams_toolkit/resources/__init__.py +35 -0
- trigrams_toolkit/resources/adapters/claude/README.md +7 -0
- trigrams_toolkit/resources/adapters/claude/evaluator.md +7 -0
- trigrams_toolkit/resources/adapters/claude/task_developer.md +7 -0
- trigrams_toolkit/resources/adapters/codex/README.md +9 -0
- trigrams_toolkit/resources/adapters/codex/evaluator.toml +6 -0
- trigrams_toolkit/resources/adapters/codex/task_developer.toml +6 -0
- trigrams_toolkit/resources/adapters/pi-web/evaluator.md +7 -0
- trigrams_toolkit/resources/adapters/pi-web/task_developer.md +7 -0
- trigrams_toolkit/resources/handbook/PROTOCOL.md +82 -0
- trigrams_toolkit/resources/handbook/README.md +45 -0
- trigrams_toolkit/resources/handbook/commands.json +31 -0
- trigrams_toolkit/resources/handbook/guides.schema.json +253 -0
- trigrams_toolkit/resources/installation/PROTOCOL.md +35 -0
- trigrams_toolkit/resources/installation/cli.schema.json +89 -0
- trigrams_toolkit/resources/installation/commands.json +23 -0
- trigrams_toolkit/resources/installation/examples/install-apply-input.json +48 -0
- trigrams_toolkit/resources/installation/examples/install-preview-input.json +7 -0
- trigrams_toolkit/resources/installation/examples/installation.json +20 -0
- trigrams_toolkit/resources/installation/global-skills.json +6 -0
- trigrams_toolkit/resources/installation/installation.schema.json +295 -0
- trigrams_toolkit/resources/plan/PROTOCOL.md +89 -0
- trigrams_toolkit/resources/plan/README.md +61 -0
- trigrams_toolkit/resources/plan/commands.json +36 -0
- trigrams_toolkit/resources/plan/plan.schema.json +192 -0
- trigrams_toolkit/resources/shared/GLOBAL-TOOLS.md +31 -0
- trigrams_toolkit/resources/shared/common.schema.json +234 -0
- trigrams_toolkit/resources/state/PROTOCOL.md +85 -0
- trigrams_toolkit/resources/state/README.md +88 -0
- trigrams_toolkit/resources/state/cli.schema.json +326 -0
- trigrams_toolkit/resources/state/commands.json +55 -0
- trigrams_toolkit/resources/state/core-types.json +5 -0
- trigrams_toolkit/resources/state/help.json +86 -0
- trigrams_toolkit/resources/state/sources.schema.json +89 -0
- trigrams_toolkit/resources/state/state.schema.json +200 -0
- trigrams_toolkit/shared/__init__.py +1 -0
- trigrams_toolkit/shared/cli_help.py +195 -0
- trigrams_toolkit/shared/errors.py +29 -0
- trigrams_toolkit/shared/files.py +66 -0
- trigrams_toolkit/shared/locking.py +49 -0
- trigrams_toolkit/shared/paths.py +89 -0
- trigrams_toolkit/shared/process_lock.py +77 -0
- trigrams_toolkit/shared/schema.py +60 -0
- trigrams_toolkit/shared/serialization.py +84 -0
- trigrams_toolkit/shared/skill_installations.py +66 -0
- trigrams_toolkit/shared/state_json.py +45 -0
- trigrams_toolkit/state/__init__.py +4 -0
- trigrams_toolkit/state/arguments.py +68 -0
- trigrams_toolkit/state/cli.py +37 -0
- trigrams_toolkit/state/frontmatter.py +176 -0
- trigrams_toolkit/state/help.py +25 -0
- trigrams_toolkit/state/identity.py +123 -0
- trigrams_toolkit/state/location.py +59 -0
- trigrams_toolkit/state/model.py +76 -0
- trigrams_toolkit/state/providers.py +77 -0
- trigrams_toolkit/state/registration.py +82 -0
- trigrams_toolkit/state/relations.py +105 -0
- trigrams_toolkit/state/service.py +90 -0
- trigrams_toolkit/state/store.py +33 -0
- trigrams_toolkit/state/views.py +64 -0
- trigrams_toolkit/version.py +6 -0
- trigrams_toolkit-0.1.0.dist-info/METADATA +69 -0
- trigrams_toolkit-0.1.0.dist-info/RECORD +103 -0
- trigrams_toolkit-0.1.0.dist-info/WHEEL +5 -0
- trigrams_toolkit-0.1.0.dist-info/entry_points.txt +5 -0
- trigrams_toolkit-0.1.0.dist-info/licenses/LICENSE +21 -0
- trigrams_toolkit-0.1.0.dist-info/licenses/THIRD_PARTY_NOTICES.md +18 -0
- trigrams_toolkit-0.1.0.dist-info/top_level.txt +1 -0
|
@@ -0,0 +1,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,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())
|