@lmmslab/harness 0.0.0-stage → 0.81.1

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 (170) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +124 -2
  3. package/bin/harness.js +71 -0
  4. package/package.json +34 -4
  5. package/python/harness/README.md +72 -0
  6. package/python/harness/__init__.py +8 -0
  7. package/python/harness/__main__.py +3 -0
  8. package/python/harness/bench.py +124 -0
  9. package/python/harness/builtin/benches/README.md +5 -0
  10. package/python/harness/builtin/benches/none/bench.toml +6 -0
  11. package/python/harness/builtin/configs/README.md +26 -0
  12. package/python/harness/builtin/configs/assistant.toml +11 -0
  13. package/python/harness/builtin/configs/default.toml +33 -0
  14. package/python/harness/builtin/configs/deploy/example-api.toml +10 -0
  15. package/python/harness/builtin/configs/models/deepseek-api.toml +21 -0
  16. package/python/harness/builtin/configs/models/deepseek-flash.toml +12 -0
  17. package/python/harness/builtin/configs/models/grok-low.toml +8 -0
  18. package/python/harness/builtin/configs/models/grok-medium.toml +43 -0
  19. package/python/harness/builtin/configs/models/opus-5.5.toml +11 -0
  20. package/python/harness/builtin/environment/README.md +53 -0
  21. package/python/harness/builtin/environment/constraints.txt +31 -0
  22. package/python/harness/builtin/model-settings.js +143 -0
  23. package/python/harness/builtin/prompts/conversation/core.md +5 -0
  24. package/python/harness/builtin/prompts/conversation/pack.toml +12 -0
  25. package/python/harness/builtin/prompts/core/core.md +88 -0
  26. package/python/harness/builtin/prompts/core/pack.toml +9 -0
  27. package/python/harness/builtin/prompts/reflect/core.md +45 -0
  28. package/python/harness/builtin/prompts/reflect/pack.toml +7 -0
  29. package/python/harness/builtin/prompts/shared/agent-skills.md +5 -0
  30. package/python/harness/builtin/prompts/shared/agents.md +14 -0
  31. package/python/harness/builtin/prompts/shared/checklist.md +21 -0
  32. package/python/harness/builtin/prompts/shared/entries.md +86 -0
  33. package/python/harness/builtin/prompts/shared/environments.md +21 -0
  34. package/python/harness/builtin/prompts/shared/learning-goal.md +31 -0
  35. package/python/harness/builtin/prompts/shared/learning.md +27 -0
  36. package/python/harness/builtin/prompts/shared/mcp.md +9 -0
  37. package/python/harness/builtin/prompts/shared/world.md +1 -0
  38. package/python/harness/builtin/skills/README.md +10 -0
  39. package/python/harness/builtin/skills/agents/__init__.py +88 -0
  40. package/python/harness/builtin/skills/agents/skill.toml +11 -0
  41. package/python/harness/builtin/skills/checklist/__init__.py +32 -0
  42. package/python/harness/builtin/skills/checklist/skill.toml +9 -0
  43. package/python/harness/builtin/skills/conversation/__init__.py +23 -0
  44. package/python/harness/builtin/skills/conversation/skill.toml +8 -0
  45. package/python/harness/builtin/skills/entries/__init__.py +62 -0
  46. package/python/harness/builtin/skills/entries/skill.toml +8 -0
  47. package/python/harness/builtin/skills/environments/__init__.py +69 -0
  48. package/python/harness/builtin/skills/environments/skill.toml +9 -0
  49. package/python/harness/builtin/skills/experience/__init__.py +27 -0
  50. package/python/harness/builtin/skills/experience/skill.toml +9 -0
  51. package/python/harness/builtin/skills/instructions/__init__.py +29 -0
  52. package/python/harness/builtin/skills/instructions/skill.toml +9 -0
  53. package/python/harness/builtin/skills/learning/__init__.py +189 -0
  54. package/python/harness/builtin/skills/learning/skill.toml +7 -0
  55. package/python/harness/builtin/skills/mcp/__init__.py +54 -0
  56. package/python/harness/builtin/skills/mcp/skill.toml +10 -0
  57. package/python/harness/builtin/skills/memory/__init__.py +130 -0
  58. package/python/harness/builtin/skills/memory/skill.toml +13 -0
  59. package/python/harness/builtin/skills/verify/__init__.py +31 -0
  60. package/python/harness/builtin/skills/verify/skill.toml +7 -0
  61. package/python/harness/builtin/third_party/sources.toml +40 -0
  62. package/python/harness/cli.py +1182 -0
  63. package/python/harness/config/__init__.py +224 -0
  64. package/python/harness/config/agent.py +777 -0
  65. package/python/harness/core/__init__.py +52 -0
  66. package/python/harness/core/artifacts.py +46 -0
  67. package/python/harness/core/codec.py +160 -0
  68. package/python/harness/core/contracts.py +75 -0
  69. package/python/harness/core/episodes.py +150 -0
  70. package/python/harness/core/format.py +51 -0
  71. package/python/harness/core/http.py +124 -0
  72. package/python/harness/core/lanes.py +324 -0
  73. package/python/harness/core/linux_sandbox.py +55 -0
  74. package/python/harness/core/media.py +96 -0
  75. package/python/harness/core/memory.py +147 -0
  76. package/python/harness/core/ports.py +63 -0
  77. package/python/harness/core/procs.py +227 -0
  78. package/python/harness/core/remote.py +102 -0
  79. package/python/harness/core/spans.py +166 -0
  80. package/python/harness/core/trace.py +139 -0
  81. package/python/harness/core/wait.py +12 -0
  82. package/python/harness/core/worker.py +388 -0
  83. package/python/harness/core/worker_pipe.py +119 -0
  84. package/python/harness/embodiments.py +217 -0
  85. package/python/harness/extensions.py +112 -0
  86. package/python/harness/host/__init__.py +397 -0
  87. package/python/harness/host/client.py +201 -0
  88. package/python/harness/host/http.py +720 -0
  89. package/python/harness/host/listing.py +68 -0
  90. package/python/harness/host/server.py +189 -0
  91. package/python/harness/host/sessions.py +406 -0
  92. package/python/harness/host/tasks.py +1356 -0
  93. package/python/harness/host/workers.py +257 -0
  94. package/python/harness/host/workspaces.py +256 -0
  95. package/python/harness/model_list.py +117 -0
  96. package/python/harness/packages/__init__.py +73 -0
  97. package/python/harness/packages/addons.py +121 -0
  98. package/python/harness/packages/archive.py +122 -0
  99. package/python/harness/packages/describe.py +46 -0
  100. package/python/harness/packages/environments.py +448 -0
  101. package/python/harness/packages/fetch.py +57 -0
  102. package/python/harness/packages/manager.py +587 -0
  103. package/python/harness/packages/manifest.py +232 -0
  104. package/python/harness/packages/migrate.py +68 -0
  105. package/python/harness/packages/provision.py +38 -0
  106. package/python/harness/packages/registry.py +275 -0
  107. package/python/harness/packages/resolve.py +89 -0
  108. package/python/harness/packages/sources.py +141 -0
  109. package/python/harness/packages/state.py +213 -0
  110. package/python/harness/packages/versions.py +112 -0
  111. package/python/harness/paths.py +218 -0
  112. package/python/harness/providers.py +303 -0
  113. package/python/harness/runtime/__init__.py +8 -0
  114. package/python/harness/runtime/decision/__init__.py +1 -0
  115. package/python/harness/runtime/decision/loop.py +198 -0
  116. package/python/harness/runtime/decision/messages.py +271 -0
  117. package/python/harness/runtime/decision/model.py +424 -0
  118. package/python/harness/runtime/decision/prompts.py +248 -0
  119. package/python/harness/runtime/decision/protocol.py +169 -0
  120. package/python/harness/runtime/decision/thoughts.py +199 -0
  121. package/python/harness/runtime/events.py +213 -0
  122. package/python/harness/runtime/execution/__init__.py +1 -0
  123. package/python/harness/runtime/execution/attached.py +96 -0
  124. package/python/harness/runtime/execution/control.py +211 -0
  125. package/python/harness/runtime/execution/entries.py +665 -0
  126. package/python/harness/runtime/execution/kernel.py +811 -0
  127. package/python/harness/runtime/execution/noenv.py +84 -0
  128. package/python/harness/runtime/execution/results.py +40 -0
  129. package/python/harness/runtime/execution/session.py +871 -0
  130. package/python/harness/runtime/execution/skills.py +436 -0
  131. package/python/harness/runtime/learning/__init__.py +1 -0
  132. package/python/harness/runtime/learning/active.py +314 -0
  133. package/python/harness/runtime/learning/experience.py +48 -0
  134. package/python/harness/runtime/learning/fixtures.py +167 -0
  135. package/python/harness/runtime/learning/learner.py +651 -0
  136. package/python/harness/runtime/learning/library.py +504 -0
  137. package/python/harness/runtime/learning/reflect.py +151 -0
  138. package/python/harness/runtime/learning/usage.py +30 -0
  139. package/python/harness/runtime/learning/views.py +89 -0
  140. package/python/harness/runtime/reactive/__init__.py +1 -0
  141. package/python/harness/runtime/reactive/rules.py +549 -0
  142. package/python/harness/runtime/safety/__init__.py +1 -0
  143. package/python/harness/runtime/safety/approval.py +131 -0
  144. package/python/harness/runtime/safety/input.py +62 -0
  145. package/python/harness/runtime/safety/isolation.py +419 -0
  146. package/python/harness/runtime/safety/shield.py +129 -0
  147. package/python/harness/runtime/status.py +23 -0
  148. package/python/harness/runtime/task/__init__.py +7 -0
  149. package/python/harness/runtime/task/context.py +431 -0
  150. package/python/harness/runtime/task/delegation.py +468 -0
  151. package/python/harness/runtime/task/environments.py +268 -0
  152. package/python/harness/runtime/task/run.py +2878 -0
  153. package/python/harness/runtime/tick.py +909 -0
  154. package/python/harness/sdk/__init__.py +281 -0
  155. package/python/harness/services/__init__.py +6 -0
  156. package/python/harness/services/broker.py +35 -0
  157. package/python/harness/services/connectors.py +88 -0
  158. package/python/harness/services/mcp.py +298 -0
  159. package/python/harness/services/mcp_stdio.py +131 -0
  160. package/python/harness/services/placement.py +82 -0
  161. package/python/harness/services/registry.py +156 -0
  162. package/python/harness/settings.py +536 -0
  163. package/python/harness/terminal.py +79 -0
  164. package/python/harness/transcript.py +297 -0
  165. package/python/harness/tui/__init__.py +68 -0
  166. package/python/harness/tui/chat.py +1181 -0
  167. package/python/harness/tui/pty.py +81 -0
  168. package/python/harness/tui/renderer.py +45 -0
  169. package/python/harness/tui/timeline_rows.py +58 -0
  170. package/python/harness/tui/views.py +434 -0
@@ -0,0 +1,89 @@
1
+ """Resolution: one version of each package for a run, or an error that says why not.
2
+
3
+ The requests (`harness install a b@^0.2`, a project's [packages]) and every chosen
4
+ version's `depends` are ranges a package must satisfy. A package keeps the version it
5
+ has when that satisfies them all; otherwise the registry's highest version that does
6
+ and works with this harness is taken. With a dozen packages a simple fixed point does;
7
+ a conflict names who needs what.
8
+ """
9
+
10
+ from .registry import RegistryError, harness_fits
11
+ from .versions import best, satisfies
12
+
13
+
14
+ class ResolveError(ValueError):
15
+ pass
16
+
17
+
18
+ def resolve(requests: dict, registry, *, harness: str, have: dict | None = None, fixed: dict | None = None,
19
+ depends_of=None) -> dict:
20
+ """{name: version} for `requests` ({name: range}) and their dependencies.
21
+
22
+ `have`: {name: version} already installed (kept when they fit); `fixed`: {name:
23
+ (version, depends)} of packages from other sources, which cannot change;
24
+ `depends_of(name, version)`: the depends of an installed version (default: the
25
+ registry's)."""
26
+ have, fixed = dict(have or {}), dict(fixed or {})
27
+ needs: dict[str, dict[str, str]] = {}
28
+
29
+ def need(name, wanted, by):
30
+ needs.setdefault(name, {})[by] = wanted
31
+
32
+ def depends(name, version):
33
+ if name in fixed:
34
+ return fixed[name][1]
35
+ if depends_of is not None:
36
+ found = depends_of(name, version)
37
+ if found is not None:
38
+ return found
39
+ return registry.entry(name, version).get("depends", {})
40
+
41
+ for name, wanted in requests.items():
42
+ need(name, wanted, "you")
43
+ chosen = {}
44
+ for name, (version, wants) in fixed.items():
45
+ chosen[name] = version
46
+ for other, wanted in wants.items():
47
+ need(other, wanted, f"{name} {version}")
48
+ for _ in range(200):
49
+ changed = False
50
+ for name in sorted(needs):
51
+ ranges = list(needs[name].values())
52
+ current = chosen.get(name)
53
+ if current and all(satisfies(current, wanted) for wanted in ranges):
54
+ continue
55
+ if name in fixed:
56
+ raise ResolveError(_conflict(name, needs[name], f"{name} {current} (from its source) is not in range"))
57
+ pick = have.get(name) if have.get(name) and all(satisfies(have[name], r) for r in ranges) else None
58
+ if pick is None:
59
+ try:
60
+ published = [version for version in registry.versions(name)
61
+ if harness_fits(registry.entry(name, version), harness)]
62
+ except RegistryError as error:
63
+ raise ResolveError(f"{name}: {error}") from None
64
+ if not published and name not in registry.packages():
65
+ raise ResolveError(f"no package {name} in {registry.base}" + _who(needs[name]))
66
+ pick = best(published, *ranges)
67
+ if pick is None:
68
+ raise ResolveError(_conflict(name, needs[name], f"published for harness {harness}: "
69
+ f"{', '.join(published) or 'none'}"))
70
+ if current:
71
+ for other in needs.values():
72
+ other.pop(f"{name} {current}", None)
73
+ chosen[name] = pick
74
+ for other, wanted in depends(name, pick).items():
75
+ need(other, wanted, f"{name} {pick}")
76
+ changed = True
77
+ if not changed:
78
+ return {name: chosen[name] for name in sorted(chosen) if name in needs or name in fixed}
79
+ raise ResolveError("the versions did not settle: " + ", ".join(f"{n} {v}" for n, v in sorted(chosen.items())))
80
+
81
+
82
+ def _who(needs: dict) -> str:
83
+ asked = [by for by in needs if by != "you"]
84
+ return f" (needed by {', '.join(asked)})" if asked else ""
85
+
86
+
87
+ def _conflict(name: str, needs: dict, detail: str) -> str:
88
+ wants = "; ".join(f"{by} needs {name} {wanted or 'any'}" for by, wanted in sorted(needs.items()))
89
+ return f"no version of {name} fits: {wants} ({detail})"
@@ -0,0 +1,141 @@
1
+ """Where a package comes from: the text `harness install` takes, and fetching it.
2
+
3
+ minecraft, minecraft@^0.1 the registry (registry.py), the highest version in range
4
+ git:github.com/x/y@ref#subdir a git repository at a branch, tag or commit, a folder of it
5
+ git+https://host/x/y.git@ref the same with a full URL
6
+ https://github.com/x/y/tree/ref/subdir a folder of a GitHub repository
7
+ https://host/x.tar.gz (.tgz, .tar, .zip) an archive
8
+ ./folder, ~/x.zip, C:\\x a folder or an archive on this computer
9
+
10
+ A folder or archive without package.toml but with skills (skills/<name>/skill.toml, a
11
+ skill.toml or a SKILL.md somewhere in it) is taken as one package per skill
12
+ (manager.py), as the app's "Add a skill" took them.
13
+ """
14
+
15
+ from dataclasses import dataclass
16
+ import os
17
+ from pathlib import Path
18
+ import re
19
+ import shutil
20
+ import subprocess
21
+
22
+ from . import archive
23
+ from .versions import check_range
24
+
25
+
26
+ ARCHIVES = (".tar.gz", ".tgz", ".tar", ".zip")
27
+ GITHUB_TREE = re.compile(r"^https://github\.com/([^/]+)/([^/]+?)(?:\.git)?/tree/([^/]+)/?(.*)$")
28
+ REGISTRY_NAME = re.compile(r"^([a-z0-9][a-z0-9-]{0,63})(?:@(.+))?$")
29
+ COMMIT = re.compile(r"^[0-9a-f]{7,40}$")
30
+
31
+
32
+ @dataclass(frozen=True)
33
+ class Source:
34
+ """A parsed source: kind is registry, git, url or path."""
35
+
36
+ kind: str
37
+ text: str
38
+ name: str = ""
39
+ range: str = ""
40
+ url: str = ""
41
+ ref: str = ""
42
+ subdir: str = ""
43
+ path: str = ""
44
+
45
+ @property
46
+ def official(self) -> bool:
47
+ return self.kind == "registry"
48
+
49
+
50
+ def parse(text) -> Source:
51
+ """The source `text` names; ValueError when it names none."""
52
+ text = str(text or "").strip()
53
+ if not text:
54
+ raise ValueError("give a package name, a git URL, an archive URL or a folder")
55
+ if text.startswith("git:") or text.startswith("git+"):
56
+ rest = text[4:]
57
+ rest = rest if rest.startswith(("https://", "http://", "ssh://", "git@", "file://")) else f"https://{rest}"
58
+ rest, _, subdir = rest.partition("#")
59
+ # The ref follows the last @ after the host (git@host:x/y has its own @).
60
+ head, at, ref = rest.rpartition("@")
61
+ if at and "/" in head.split("://")[-1] and "/" not in ref:
62
+ rest = head
63
+ else:
64
+ ref = ""
65
+ return Source("git", text, url=rest, ref=ref, subdir=subdir.strip("/"))
66
+ if re.match(r"^https?://", text):
67
+ github = GITHUB_TREE.match(text)
68
+ if github:
69
+ return Source("git", text, url=f"https://github.com/{github.group(1)}/{github.group(2)}",
70
+ ref=github.group(3), subdir=github.group(4).strip("/"))
71
+ if text.lower().split("?")[0].endswith(ARCHIVES):
72
+ return Source("url", text, url=text)
73
+ if text.lower().split("?")[0].endswith(".git"):
74
+ return Source("git", text, url=text)
75
+ raise ValueError(f"{text}: a URL of an archive ({', '.join(ARCHIVES)}) or of a git repository (.git)")
76
+ local = Path(os.path.expanduser(text))
77
+ # A bare name is the registry's even when a folder of that name is here (./name is the folder).
78
+ looks_local = text.startswith((".", "/", "\\", "~")) or re.match(r"^[A-Za-z]:[\\/]", text) or os.sep in text \
79
+ or "/" in text or text.lower().endswith(ARCHIVES)
80
+ if looks_local:
81
+ if not local.exists():
82
+ raise ValueError(f"{text}: no such folder or file")
83
+ if local.is_file() and not local.name.lower().endswith(ARCHIVES):
84
+ raise ValueError(f"{text}: a folder or an archive ({', '.join(ARCHIVES)})")
85
+ return Source("path", text, path=str(local.resolve()))
86
+ match = REGISTRY_NAME.match(text)
87
+ if not match:
88
+ raise ValueError(f"{text}: not a package name (lowercase letters, digits, hyphens), a URL or a folder")
89
+ return Source("registry", text, name=match.group(1), range=check_range(match.group(2) or ""))
90
+
91
+
92
+ def fetch(source: Source, into: Path, *, timeout: float = 300.0, log=print) -> tuple[Path, str]:
93
+ """The files of a git, url or path source in a folder (under `into`, except a local
94
+ folder, which is read where it is); returns the folder and the source as a lock
95
+ records it (a git source with its commit)."""
96
+ into = Path(into)
97
+ if source.kind == "path":
98
+ path = Path(source.path)
99
+ if path.is_dir():
100
+ return path, f"path:{path}"
101
+ return archive.unpack(path, into / "unpacked"), f"path:{path}"
102
+ if source.kind == "url":
103
+ from ..core.http import open_url
104
+
105
+ log(f"downloading {source.url}")
106
+ with open_url(source.url, timeout=timeout) as response:
107
+ data = response.read(archive.MAX_BYTES + 1)
108
+ if len(data) > archive.MAX_BYTES:
109
+ raise ValueError(f"{source.url}: larger than {archive.MAX_BYTES >> 20} MB")
110
+ import hashlib
111
+
112
+ return archive.unpack(data, into / "unpacked"), f"url:{source.url}#sha256={hashlib.sha256(data).hexdigest()}"
113
+ if source.kind == "git":
114
+ return _git(source, into, timeout, log)
115
+ raise ValueError(f"{source.text}: a registry package is fetched by the registry")
116
+
117
+
118
+ def _git(source: Source, into: Path, timeout: float, log) -> tuple[Path, str]:
119
+ git = shutil.which("git")
120
+ if git is None:
121
+ raise ValueError("installing from git needs git on this computer; use an archive URL instead")
122
+ target = into / "repo"
123
+
124
+ def run(*args, cwd=None):
125
+ result = subprocess.run([git, *args], cwd=cwd, capture_output=True, encoding="utf-8", errors="replace",
126
+ timeout=timeout)
127
+ if result.returncode:
128
+ raise ValueError(f"git {args[0]} failed: {(result.stderr or result.stdout).strip()[-300:]}")
129
+ return result.stdout.strip()
130
+
131
+ log(f"cloning {source.url}" + (f" at {source.ref}" if source.ref else ""))
132
+ if source.ref and COMMIT.match(source.ref):
133
+ run("clone", "--filter=blob:none", "--no-checkout", source.url, str(target))
134
+ run("checkout", "--quiet", source.ref, cwd=target)
135
+ else:
136
+ run("clone", "--depth", "1", *(["--branch", source.ref] if source.ref else []), source.url, str(target))
137
+ commit = run("rev-parse", "HEAD", cwd=target)
138
+ folder = (target / source.subdir).resolve()
139
+ if target.resolve() not in [folder, *folder.parents] or not folder.is_dir():
140
+ raise ValueError(f"no folder {source.subdir} in {source.url}")
141
+ return folder, f"git:{source.url}@{commit}" + (f"#{source.subdir}" if source.subdir else "")
@@ -0,0 +1,213 @@
1
+ """What is installed, and for whom: the store, the user's list, a project's lock.
2
+
3
+ HOME/packages/<name>/<version>-<sha8>/ an installed version, never changed once there
4
+ <data>/config.toml [packages] the user's packages (~/.harness/config.toml, settings.py)
5
+ <project>/harness.toml [packages] a project's packages: { name = "range" } or
6
+ { name = { source = "...", range = "..." } }
7
+ <project>/harness.lock what they resolved to: name, version, sha256, source
8
+
9
+ A project is the nearest folder above the working directory with a harness.toml that
10
+ has [packages]. Its packages are used only once the user trusted the project (they ran
11
+ `harness install` there); the trusted projects are listed in the user's config.toml.
12
+ """
13
+
14
+ from dataclasses import dataclass, field
15
+ import os
16
+ from pathlib import Path
17
+ import shutil
18
+ import stat
19
+ import sys
20
+ import tomllib
21
+
22
+ from ..core import atomic_write
23
+
24
+
25
+ PROJECT_FILE = "harness.toml"
26
+ LOCK_FILE = "harness.lock"
27
+ LOCK_VERSION = 1
28
+
29
+
30
+ def _toml(path: Path) -> dict:
31
+ try:
32
+ with Path(path).open("rb") as handle:
33
+ return tomllib.load(handle)
34
+ except FileNotFoundError:
35
+ return {}
36
+ except tomllib.TOMLDecodeError as error:
37
+ raise ValueError(f"{path}: {error}") from None
38
+
39
+
40
+ @dataclass
41
+ class Record:
42
+ """One installed package as a list or a lock records it."""
43
+
44
+ name: str
45
+ version: str
46
+ sha256: str = ""
47
+ source: str = "registry"
48
+ range: str = ""
49
+ path: str = ""
50
+ link: bool = False
51
+ trusted: bool = True
52
+ enabled: bool = True
53
+
54
+ def row(self) -> dict:
55
+ return {"version": self.version, "sha256": self.sha256, "source": self.source, "range": self.range,
56
+ "path": self.path, "link": self.link, "trusted": self.trusted, "enabled": self.enabled}
57
+
58
+
59
+ @dataclass
60
+ class UserList:
61
+ """The user's packages: [packages] of config.toml (settings.py), with
62
+ [packages.installed.<name>] for each one, the trusted projects, and whether the app's
63
+ installed skills were made packages (addons_migrated)."""
64
+
65
+ directory: Path
66
+ packages: dict = field(default_factory=dict)
67
+ trusted_projects: list = field(default_factory=list)
68
+ migrated: bool = False
69
+
70
+ @classmethod
71
+ def read(cls, data: Path) -> "UserList":
72
+ from .. import settings
73
+
74
+ section = settings.read(data).get("packages") or {}
75
+ packages = {}
76
+ for name, row in (section.get("installed") or {}).items():
77
+ fields = {k: row[k] for k in Record.__dataclass_fields__ if k in row and k != "name"}
78
+ packages[name] = Record(name=name, **fields)
79
+ return cls(Path(data), packages, list(section.get("trusted_projects", [])),
80
+ bool(section.get("addons_migrated", False)))
81
+
82
+ @property
83
+ def path(self) -> Path:
84
+ from .. import settings
85
+
86
+ return settings.path(self.directory)
87
+
88
+ def write(self) -> None:
89
+ from .. import settings
90
+
91
+ def apply(data):
92
+ section = data.setdefault("packages", {})
93
+ section["addons_migrated"] = self.migrated
94
+ section["trusted_projects"] = list(self.trusted_projects)
95
+ section["installed"] = {name: self.packages[name].row() for name in sorted(self.packages)}
96
+
97
+ settings.change(self.directory, apply)
98
+
99
+
100
+ @dataclass
101
+ class Project:
102
+ """A folder with a harness.toml that has [packages], and its harness.lock."""
103
+
104
+ root: Path
105
+
106
+ @classmethod
107
+ def find(cls, start=None) -> "Project | None":
108
+ folder = Path(start or os.getcwd()).resolve()
109
+ for candidate in (folder, *folder.parents):
110
+ path = candidate / PROJECT_FILE
111
+ if path.is_file():
112
+ try:
113
+ if "packages" in _toml(path):
114
+ return cls(candidate)
115
+ except ValueError:
116
+ return cls(candidate)
117
+ return None
118
+
119
+ @property
120
+ def file(self) -> Path:
121
+ return self.root / PROJECT_FILE
122
+
123
+ @property
124
+ def lock_file(self) -> Path:
125
+ return self.root / LOCK_FILE
126
+
127
+ def wanted(self) -> dict:
128
+ """[packages] of harness.toml: {name: {"range", "source"}}."""
129
+ out = {}
130
+ for name, row in (_toml(self.file).get("packages") or {}).items():
131
+ row = {"range": row} if isinstance(row, str) else dict(row)
132
+ out[name] = {"range": str(row.get("range", "")), "source": str(row.get("source", ""))}
133
+ return out
134
+
135
+ def locked(self) -> dict[str, Record]:
136
+ tree = _toml(self.lock_file)
137
+ return {row["name"]: Record(name=row["name"], version=row["version"], sha256=row.get("sha256", ""),
138
+ source=row.get("source", "registry"))
139
+ for row in tree.get("package", [])}
140
+
141
+ def set_wanted(self, wanted: dict) -> None:
142
+ """Rewrite [packages] of harness.toml, keeping the rest of the file as it is."""
143
+ from ..config import toml_key, toml_value
144
+
145
+ lines = ["[packages]"]
146
+ for name in sorted(wanted):
147
+ row = wanted[name]
148
+ item = row["range"] if not row.get("source") else \
149
+ {k: v for k, v in (("source", row["source"]), ("range", row["range"])) if v}
150
+ lines.append(f"{toml_key(name)} = {toml_value(item)}")
151
+ text = self.file.read_text(encoding="utf-8") if self.file.is_file() else ""
152
+ atomic_write(self.file, set_table(text, "packages", lines))
153
+
154
+ def write_lock(self, records) -> None:
155
+ from ..config import dumps
156
+
157
+ rows = [{"name": r.name, "version": r.version, "sha256": r.sha256, "source": r.source}
158
+ for r in sorted(records, key=lambda r: r.name)]
159
+ comment = "harness.lock: the packages harness.toml resolved to (harness install). Check it in."
160
+ atomic_write(self.lock_file, dumps({"version": LOCK_VERSION, "package": rows}, comment))
161
+
162
+
163
+ def set_table(text: str, table: str, lines: list[str]) -> str:
164
+ """`text` (TOML) with table [table] replaced by `lines` (or appended)."""
165
+ out, skipping, done = [], False, False
166
+ for line in text.splitlines():
167
+ header = line.strip()
168
+ if header.startswith("[") and not header.startswith("[["):
169
+ name = header.strip("[]").strip()
170
+ if name == table or name.startswith(table + "."):
171
+ if not done:
172
+ out += lines
173
+ done = True
174
+ skipping = True
175
+ continue
176
+ skipping = False
177
+ elif header.startswith("[["):
178
+ skipping = False
179
+ if not skipping:
180
+ out.append(line)
181
+ if not done:
182
+ if out and out[-1].strip():
183
+ out.append("")
184
+ out += lines
185
+ return "\n".join(out).rstrip("\n") + "\n"
186
+
187
+
188
+ def store_root() -> Path:
189
+ from ..paths import home
190
+
191
+ return home() / "packages"
192
+
193
+
194
+ def store_path(name: str, version: str, sha256: str) -> Path:
195
+ return store_root() / name / f"{version}-{sha256[:8]}"
196
+
197
+
198
+ def freeze(folder: Path) -> None:
199
+ """Make an installed version read-only (it never changes once installed)."""
200
+ for current, _, files in os.walk(folder):
201
+ for name in files:
202
+ path = Path(current) / name
203
+ path.chmod(path.stat().st_mode & ~(stat.S_IWUSR | stat.S_IWGRP | stat.S_IWOTH))
204
+
205
+
206
+ def delete(folder: Path) -> None:
207
+ """Remove an installed version (its files are read-only)."""
208
+ def writable(function, path, _):
209
+ os.chmod(path, stat.S_IWRITE | stat.S_IREAD | stat.S_IEXEC)
210
+ function(path)
211
+
212
+ if Path(folder).exists():
213
+ shutil.rmtree(folder, **({"onexc": writable} if sys.version_info >= (3, 12) else {"onerror": writable}))
@@ -0,0 +1,112 @@
1
+ """Versions and version ranges of packages and of the harness itself.
2
+
3
+ A version is MAJOR.MINOR.PATCH, optionally with a pre-release (`1.0.0-rc.1`); a shorter
4
+ one (`0.57`) has zeros for the parts it leaves out. A range is comparators joined by
5
+ commas, all of which must hold:
6
+
7
+ >=0.57,<2 at least 0.57, below 2
8
+ ^1.2 >=1.2.0,<2.0.0 (^0.3 is >=0.3.0,<0.4.0: below 1 the minor is the major)
9
+ ~1.2 >=1.2.0,<1.3.0
10
+ ==1.2.3, 1.2.3 exactly that version
11
+ !=1.2.3 anything but it
12
+ *, "" any version
13
+
14
+ A pre-release satisfies a range only when the range names a pre-release itself, so
15
+ `harness install x` never picks one unless asked.
16
+ """
17
+
18
+ from dataclasses import dataclass
19
+ import re
20
+
21
+
22
+ VERSION = re.compile(r"^(\d+)(?:\.(\d+))?(?:\.(\d+))?(?:-([0-9A-Za-z.-]+))?$")
23
+ COMPARATOR = re.compile(r"^(>=|<=|==|!=|>|<|\^|~)?\s*(\S+)$")
24
+
25
+
26
+ @dataclass(frozen=True, order=False)
27
+ class Version:
28
+ major: int
29
+ minor: int
30
+ patch: int
31
+ pre: str = ""
32
+
33
+ @classmethod
34
+ def parse(cls, text) -> "Version":
35
+ match = VERSION.match(str(text).strip())
36
+ if not match:
37
+ raise ValueError(f"{text!r} is not a version (MAJOR.MINOR.PATCH)")
38
+ major, minor, patch, pre = match.groups()
39
+ return cls(int(major), int(minor or 0), int(patch or 0), pre or "")
40
+
41
+ def key(self) -> tuple:
42
+ # A release sorts after its pre-releases; pre-release parts compare as numbers
43
+ # where they are numbers.
44
+ parts = tuple((0, int(part), "") if part.isdigit() else (1, 0, part) for part in self.pre.split(".")) \
45
+ if self.pre else ()
46
+ return (self.major, self.minor, self.patch, 0 if self.pre else 1, parts)
47
+
48
+ def __lt__(self, other):
49
+ return self.key() < other.key()
50
+
51
+ def __le__(self, other):
52
+ return self.key() <= other.key()
53
+
54
+ def __gt__(self, other):
55
+ return self.key() > other.key()
56
+
57
+ def __ge__(self, other):
58
+ return self.key() >= other.key()
59
+
60
+ def __str__(self):
61
+ return f"{self.major}.{self.minor}.{self.patch}" + (f"-{self.pre}" if self.pre else "")
62
+
63
+
64
+ def _comparators(text: str) -> list[tuple[str, Version]]:
65
+ out = []
66
+ for part in (piece.strip() for piece in str(text or "").split(",")):
67
+ if part in ("", "*"):
68
+ continue
69
+ match = COMPARATOR.match(part)
70
+ if not match:
71
+ raise ValueError(f"{text!r} is not a version range")
72
+ operator, version = match.group(1) or "==", Version.parse(match.group(2))
73
+ if operator == "^":
74
+ upper = Version(version.major + 1, 0, 0) if version.major else \
75
+ Version(0, version.minor + 1, 0) if version.minor else Version(0, 0, version.patch + 1)
76
+ out += [(">=", version), ("<", upper)]
77
+ elif operator == "~":
78
+ out += [(">=", version), ("<", Version(version.major, version.minor + 1, 0))]
79
+ else:
80
+ out.append((operator, version))
81
+ return out
82
+
83
+
84
+ def check_range(text) -> str:
85
+ """The range as written, or ValueError."""
86
+ _comparators(text)
87
+ return str(text or "").strip()
88
+
89
+
90
+ def satisfies(version, text) -> bool:
91
+ """Whether `version` is in range `text`."""
92
+ version = version if isinstance(version, Version) else Version.parse(version)
93
+ comparators = _comparators(text)
94
+ if version.pre and not any(bound.pre for _, bound in comparators):
95
+ return False
96
+ tests = {">=": lambda a, b: a >= b, "<=": lambda a, b: a <= b, ">": lambda a, b: a > b,
97
+ "<": lambda a, b: a < b, "==": lambda a, b: a.key() == b.key(), "!=": lambda a, b: a.key() != b.key()}
98
+ return all(tests[operator](version, bound) for operator, bound in comparators)
99
+
100
+
101
+ def best(versions, *ranges) -> str | None:
102
+ """The highest of `versions` in every range; None when none is."""
103
+ fitting = [Version.parse(version) for version in versions
104
+ if all(satisfies(version, text) for text in ranges or ("",))]
105
+ return str(max(fitting)) if fitting else None
106
+
107
+
108
+ def latest(versions) -> str | None:
109
+ """The highest release among `versions` (else the highest pre-release)."""
110
+ parsed = [Version.parse(version) for version in versions]
111
+ releases = [version for version in parsed if not version.pre]
112
+ return str(max(releases or parsed)) if parsed else None