basstler-notes 4.2.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.
basstler/setup/gate.py ADDED
@@ -0,0 +1,283 @@
1
+ """
2
+ The setup gate a skill passes before its first step: check-setup.sh reports only the
3
+ checks that skill needs, so a row it does not use never stops it.
4
+
5
+ Usage:
6
+ basstler.sh setup.gate --skill <skill>
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ import os
12
+ from abc import ABC, abstractmethod
13
+ from dataclasses import dataclass
14
+ from enum import StrEnum
15
+ from pathlib import Path
16
+ from typing import Annotated
17
+
18
+ from cyclopts import App, Parameter
19
+
20
+ from basstler.class_name import HyphenatedClassName
21
+ from basstler.class_property import classproperty
22
+ from basstler.exit_codes import CommandFailure, ExitCode
23
+ from basstler.locations import ClaudeCodeVariable
24
+ from basstler.plugin_root import PluginRoot
25
+ from basstler.setup.exceptions import UnknownSkillError
26
+ from basstler.setup.report import (
27
+ ReportRowField,
28
+ SetupCheck,
29
+ SetupCheckScript,
30
+ SetupReport,
31
+ )
32
+ from basstler.standard_streams import StandardStreamHandler
33
+
34
+ logger = StandardStreamHandler.logger_for(__name__)
35
+ """
36
+ This module's logger, which is also what its command prints through.
37
+ """
38
+
39
+ # %% the skills that gate on their setup
40
+
41
+
42
+ class CheckSetupOption(StrEnum):
43
+ """
44
+ The check-setup.sh flags a gate passes.
45
+ """
46
+
47
+ ONLY = "--only"
48
+ """
49
+ Reports only the check named after it, and exits for the named checks alone.
50
+ """
51
+
52
+ REQUIRE_UPSTREAM = "--require-upstream"
53
+ """
54
+ Makes a project naming no upstream a check that needs setup.
55
+ """
56
+
57
+
58
+ @dataclass(frozen=True)
59
+ class BasstlerSkill(HyphenatedClassName, ABC):
60
+ """
61
+ A skill that checks its setup before its first step.
62
+
63
+ A subclass declares the checks it needs beyond the ones every skill needs, and the
64
+ gate follows; :meth:`named` finds it among the direct subclasses.
65
+ """
66
+
67
+ @classproperty
68
+ def skill_name(cls) -> str:
69
+ """
70
+ The name a session invokes the skill with: its class name, hyphenated.
71
+ """
72
+ return cls.hyphenated_class_name()
73
+
74
+ @classproperty
75
+ @abstractmethod
76
+ def additional_checks(cls) -> frozenset[SetupCheck]:
77
+ """
78
+ The checks this skill needs beyond :attr:`shared_checks`.
79
+ """
80
+
81
+ @classproperty
82
+ def shared_checks(cls) -> frozenset[SetupCheck]:
83
+ """
84
+ What every gated skill needs: the plugin, the session start it registers, the
85
+ package its commands run at the plugin's own release, and the notes branch.
86
+ """
87
+ return frozenset(
88
+ {
89
+ SetupCheck.TOOLING_FILES,
90
+ SetupCheck.SESSION_START_HOOK,
91
+ SetupCheck.CLAUDE_LOCAL_MD_IGNORED,
92
+ SetupCheck.PACKAGE_DEPENDENCIES,
93
+ SetupCheck.BASSTLER_VERSION,
94
+ SetupCheck.CLAUDE_LOCAL_MD,
95
+ SetupCheck.NOTES_REPOSITORY_ACCESS,
96
+ SetupCheck.NOTES_BRANCH,
97
+ }
98
+ )
99
+
100
+ @classproperty
101
+ def required_checks(cls) -> frozenset[SetupCheck]:
102
+ """
103
+ The checks this skill's steps depend on; no other row stops it.
104
+ """
105
+ return cls.shared_checks | cls.additional_checks
106
+
107
+ @classmethod
108
+ def check_setup_arguments(cls) -> list[str]:
109
+ """
110
+ :return: The flags that make check-setup.sh report exactly :attr:`required_checks`,
111
+ requiring an upstream when :attr:`SetupCheck.STACK_UPSTREAM` is among them.
112
+ """
113
+ upstream = (
114
+ [CheckSetupOption.REQUIRE_UPSTREAM]
115
+ if SetupCheck.STACK_UPSTREAM in cls.required_checks
116
+ else []
117
+ )
118
+ return [
119
+ *upstream,
120
+ *(
121
+ argument
122
+ for check in SetupCheck
123
+ if check in cls.required_checks
124
+ for argument in (CheckSetupOption.ONLY, check)
125
+ ),
126
+ ]
127
+
128
+ @classmethod
129
+ def gate(cls, script: SetupCheckScript) -> SetupReport:
130
+ """
131
+ :param script: The clone's check-setup.sh.
132
+ :return: What it reports for this skill's checks, exiting for them alone.
133
+ :raises CheckSetupFailedError: If it exits with a status that carries no report,
134
+ or its report lacks one of those checks or holds an unreadable row.
135
+ """
136
+ return SetupReport.from_completed_process(
137
+ script.run(*cls.check_setup_arguments()), cls.required_checks
138
+ )
139
+
140
+ @classmethod
141
+ def every_skill(cls) -> tuple[type[BasstlerSkill], ...]:
142
+ """
143
+ :return: Every gated skill, in the order they are defined.
144
+ """
145
+ return tuple(
146
+ skill for family in cls.__subclasses__() for skill in family.leaves()
147
+ )
148
+
149
+ @classmethod
150
+ def leaves(cls) -> tuple[type[BasstlerSkill], ...]:
151
+ """
152
+ :return: This class when no skill subclasses it, else the skills that do.
153
+ """
154
+ subclasses = cls.__subclasses__()
155
+ if not subclasses:
156
+ return (cls,)
157
+ return tuple(skill for subclass in subclasses for skill in subclass.leaves())
158
+
159
+ @classmethod
160
+ def named(cls, skill_name: str) -> type[BasstlerSkill]:
161
+ """
162
+ :param skill_name: A name a session invokes a skill with.
163
+ :return: The gated skill of that name.
164
+ :raises UnknownSkillError: If no gated skill has that name.
165
+ """
166
+ for skill in BasstlerSkill.every_skill():
167
+ if skill.skill_name == skill_name:
168
+ return skill
169
+ raise UnknownSkillError(
170
+ skill_name, [skill.skill_name for skill in BasstlerSkill.every_skill()]
171
+ )
172
+
173
+
174
+ class PlanSavingSkill(BasstlerSkill, ABC):
175
+ """
176
+ A skill that saves a plan, so it needs the notes file, a session that can start the
177
+ plan site's build, and the identity its commits carry.
178
+ """
179
+
180
+ @classproperty
181
+ def additional_checks(cls) -> frozenset[SetupCheck]:
182
+ return frozenset(
183
+ {
184
+ SetupCheck.NOTES_FILE,
185
+ SetupCheck.PLAN_SITE_ACCESS,
186
+ SetupCheck.GIT_IDENTITY,
187
+ }
188
+ )
189
+
190
+
191
+ class PlanCreate(PlanSavingSkill):
192
+ """
193
+ Creates a plan on the personal-notes branch.
194
+ """
195
+
196
+
197
+ class AddPlanItem(PlanSavingSkill):
198
+ """
199
+ Decides where new work belongs and adds it to a plan.
200
+ """
201
+
202
+
203
+ class PlanItemKickoff(PlanSavingSkill):
204
+ """
205
+ Starts a plan item.
206
+ """
207
+
208
+
209
+ class PlanItemResolve(PlanSavingSkill):
210
+ """
211
+ Unblocks or resumes a plan item already underway.
212
+ """
213
+
214
+
215
+ class UpstreamReviews(BasstlerSkill):
216
+ """
217
+ Reports a fork branch's upstream pull request.
218
+ """
219
+
220
+ @classproperty
221
+ def additional_checks(cls) -> frozenset[SetupCheck]:
222
+ return frozenset(
223
+ {SetupCheck.STACK_UPSTREAM, SetupCheck.UPSTREAM_REVIEWS_ACTION}
224
+ )
225
+
226
+
227
+ # %% the command line
228
+
229
+
230
+ class GateOption(StrEnum):
231
+ """
232
+ The options the command takes.
233
+ """
234
+
235
+ SKILL = "--skill"
236
+ """
237
+ The skill about to start.
238
+ """
239
+
240
+
241
+ gate_app = App(help=__doc__)
242
+ """
243
+ The command, which takes the skill about to start.
244
+ """
245
+
246
+
247
+ @gate_app.default
248
+ def check_skill_setup(
249
+ *, skill: Annotated[str, Parameter(name=GateOption.SKILL)]
250
+ ) -> ExitCode:
251
+ """
252
+ Print check-setup.sh's rows for the checks a skill needs, and exit as it does.
253
+
254
+ :param skill: The name of the skill about to start.
255
+ :return: check-setup.sh's status for that skill's checks.
256
+ :raises UnknownSkillError: If no gated skill has that name.
257
+ """
258
+ project_root = Path(
259
+ os.environ.get(ClaudeCodeVariable.PROJECT_DIRECTORY, Path.cwd())
260
+ )
261
+ report = BasstlerSkill.named(skill).gate(
262
+ SetupCheckScript(project_root, os.environ, PluginRoot.locate(os.environ))
263
+ )
264
+ for check, result in report.results.items():
265
+ logger.info(f"{check}{ReportRowField.SEPARATOR}{result.fields}")
266
+ return report.exit_code
267
+
268
+
269
+ def main() -> ExitCode:
270
+ """
271
+ Run the gate, ending with the status a refusal carries.
272
+
273
+ :return: The process exit code.
274
+ """
275
+ try:
276
+ return gate_app(result_action="return_value")
277
+ except CommandFailure as failure:
278
+ logger.error(f"{failure}")
279
+ return failure.exit_code
280
+
281
+
282
+ if __name__ == "__main__":
283
+ raise SystemExit(main())