aa-toolkit-cli 0.1.0a1__tar.gz

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 (28) hide show
  1. aa_toolkit_cli-0.1.0a1/LICENSE +21 -0
  2. aa_toolkit_cli-0.1.0a1/PKG-INFO +25 -0
  3. aa_toolkit_cli-0.1.0a1/README.md +13 -0
  4. aa_toolkit_cli-0.1.0a1/pyproject.toml +29 -0
  5. aa_toolkit_cli-0.1.0a1/pyproject.toml.orig +27 -0
  6. aa_toolkit_cli-0.1.0a1/src/aa_cli/__init__.py +1 -0
  7. aa_toolkit_cli-0.1.0a1/src/aa_cli/add.py +221 -0
  8. aa_toolkit_cli-0.1.0a1/src/aa_cli/choices.py +33 -0
  9. aa_toolkit_cli-0.1.0a1/src/aa_cli/cli.py +616 -0
  10. aa_toolkit_cli-0.1.0a1/src/aa_cli/commands.py +207 -0
  11. aa_toolkit_cli-0.1.0a1/src/aa_cli/crash.py +175 -0
  12. aa_toolkit_cli-0.1.0a1/src/aa_cli/git.py +24 -0
  13. aa_toolkit_cli-0.1.0a1/src/aa_cli/init.py +383 -0
  14. aa_toolkit_cli-0.1.0a1/src/aa_cli/output.py +101 -0
  15. aa_toolkit_cli-0.1.0a1/src/aa_cli/process.py +42 -0
  16. aa_toolkit_cli-0.1.0a1/src/aa_cli/redact.py +207 -0
  17. aa_toolkit_cli-0.1.0a1/src/aa_cli/secret.py +67 -0
  18. aa_toolkit_cli-0.1.0a1/src/aa_cli/templates/AGENTS.md.tmpl +32 -0
  19. aa_toolkit_cli-0.1.0a1/src/aa_cli/templates/CLAUDE.md.tmpl +1 -0
  20. aa_toolkit_cli-0.1.0a1/src/aa_cli/templates/LICENSE.tmpl +21 -0
  21. aa_toolkit_cli-0.1.0a1/src/aa_cli/templates/README.md.tmpl +23 -0
  22. aa_toolkit_cli-0.1.0a1/src/aa_cli/templates/ci.yml.tmpl +28 -0
  23. aa_toolkit_cli-0.1.0a1/src/aa_cli/templates/cli_init.py.tmpl +5 -0
  24. aa_toolkit_cli-0.1.0a1/src/aa_cli/templates/cli_test.py.tmpl +7 -0
  25. aa_toolkit_cli-0.1.0a1/src/aa_cli/templates/gitignore.tmpl +22 -0
  26. aa_toolkit_cli-0.1.0a1/src/aa_cli/templates/lib_init.py.tmpl +5 -0
  27. aa_toolkit_cli-0.1.0a1/src/aa_cli/templates/lib_test.py.tmpl +5 -0
  28. aa_toolkit_cli-0.1.0a1/src/aa_cli/templates/pyproject.toml.tmpl +2 -0
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Aaron Aco
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,25 @@
1
+ Metadata-Version: 2.4
2
+ Name: aa-toolkit-cli
3
+ Version: 0.1.0a1
4
+ Summary: The aa command.
5
+ License-Expression: MIT
6
+ License-File: LICENSE
7
+ Requires-Dist: aa-toolkit-redact>=0.1.0a1
8
+ Requires-Dist: aa-toolkit-settings>=0.1.0a1
9
+ Requires-Dist: typer>=0.27.3
10
+ Requires-Python: >=3.14
11
+ Description-Content-Type: text/markdown
12
+
13
+ # aa-toolkit-cli
14
+
15
+ The `aa` command. See the toolkit README for how to install and develop it.
16
+
17
+ ## Crash reports
18
+
19
+ When a command fails with an unexpected error (exit code `3`), `aa` saves a Crash report and puts its full path in the error's `fix` field (the `Fix:` line in human mode). Usage errors and Ctrl+C don't save one. Nothing is uploaded.
20
+
21
+ - **Where:** `%LOCALAPPDATA%\aa\crash\`, one Markdown file per crash, named by date and time (`2026-11-16-141205.md`). Only the newest 10 are kept.
22
+ - **What it holds:** the aa version, the Python version, the Windows build, the command name without its arguments (`aa init`, never `aa init my-app`), the error message and the traceback. Never local variables or environment variables.
23
+ - **What's taken out:** the home folder path becomes `[HOME]`, the computer name becomes `[COMPUTER]`, and the error message and traceback go through the same cleaning as `aa redact`. No tool catches everything, so read the file before you post it.
24
+
25
+ If the report can't be saved, `aa` answers as it would without one, with no `fix`.
@@ -0,0 +1,13 @@
1
+ # aa-toolkit-cli
2
+
3
+ The `aa` command. See the toolkit README for how to install and develop it.
4
+
5
+ ## Crash reports
6
+
7
+ When a command fails with an unexpected error (exit code `3`), `aa` saves a Crash report and puts its full path in the error's `fix` field (the `Fix:` line in human mode). Usage errors and Ctrl+C don't save one. Nothing is uploaded.
8
+
9
+ - **Where:** `%LOCALAPPDATA%\aa\crash\`, one Markdown file per crash, named by date and time (`2026-11-16-141205.md`). Only the newest 10 are kept.
10
+ - **What it holds:** the aa version, the Python version, the Windows build, the command name without its arguments (`aa init`, never `aa init my-app`), the error message and the traceback. Never local variables or environment variables.
11
+ - **What's taken out:** the home folder path becomes `[HOME]`, the computer name becomes `[COMPUTER]`, and the error message and traceback go through the same cleaning as `aa redact`. No tool catches everything, so read the file before you post it.
12
+
13
+ If the report can't be saved, `aa` answers as it would without one, with no `fix`.
@@ -0,0 +1,29 @@
1
+ [project]
2
+ name = "aa-toolkit-cli"
3
+ version = "0.1.0a1"
4
+ description = "The aa command."
5
+ readme = "README.md"
6
+ requires-python = ">=3.14"
7
+ license = "MIT"
8
+ license-files = ["LICENSE"]
9
+ dependencies = [
10
+ "aa-toolkit-redact>=0.1.0a1",
11
+ "aa-toolkit-settings>=0.1.0a1",
12
+ "typer>=0.27.3",
13
+ ]
14
+
15
+ [project.scripts]
16
+ aa = "aa_cli.cli:main"
17
+
18
+ [build-system]
19
+ requires = ["uv_build>=0.13.7,<0.14"]
20
+ build-backend = "uv_build"
21
+
22
+ [tool.uv.sources.aa-toolkit-redact]
23
+ workspace = true
24
+
25
+ [tool.uv.sources.aa-toolkit-settings]
26
+ workspace = true
27
+
28
+ [tool.uv.build-backend]
29
+ module-name = "aa_cli"
@@ -0,0 +1,27 @@
1
+ [project]
2
+ name = "aa-toolkit-cli"
3
+ version = "0.1.0a1"
4
+ description = "The aa command."
5
+ readme = "README.md"
6
+ requires-python = ">=3.14"
7
+ license = "MIT"
8
+ license-files = ["LICENSE"]
9
+ dependencies = [
10
+ "aa-toolkit-redact>=0.1.0a1",
11
+ "aa-toolkit-settings>=0.1.0a1",
12
+ "typer>=0.27.3",
13
+ ]
14
+
15
+ [project.scripts]
16
+ aa = "aa_cli.cli:main"
17
+
18
+ [build-system]
19
+ requires = ["uv_build>=0.13.7,<0.14"]
20
+ build-backend = "uv_build"
21
+
22
+ [tool.uv.sources]
23
+ aa-toolkit-redact = { workspace = true }
24
+ aa-toolkit-settings = { workspace = true }
25
+
26
+ [tool.uv.build-backend]
27
+ module-name = "aa_cli"
@@ -0,0 +1 @@
1
+ """The aa command."""
@@ -0,0 +1,221 @@
1
+ """``aa add``: setting up one piece in an existing project."""
2
+
3
+ __lazy_modules__ = {
4
+ "aa_cli.init",
5
+ "tomllib",
6
+ }
7
+
8
+ import re
9
+ import tomllib
10
+ from dataclasses import dataclass
11
+ from pathlib import Path
12
+ from typing import Any
13
+
14
+ from aa_cli.choices import Piece
15
+ from aa_cli.init import (
16
+ CI_TEMPLATE,
17
+ CI_WORKFLOW,
18
+ PYPROJECT,
19
+ WRITE_FILES_STEP,
20
+ file_step,
21
+ render,
22
+ step,
23
+ write,
24
+ )
25
+
26
+ UV_LOCK = "uv.lock"
27
+ NOT_A_PROJECT_FIX = "Run aa add from the project's root folder (where pyproject.toml is)."
28
+ _CI_TOOLS = ("ruff", "pytest")
29
+ LOG_PACKAGE = "aa-toolkit-log"
30
+ LOG_TAG = "log-v0.1.0"
31
+ LOG_REQUIREMENT = (
32
+ f"{LOG_PACKAGE} @ git+https://github.com/aaronaco/aa-toolkit@{LOG_TAG}"
33
+ "#subdirectory=packages/aa-toolkit-log"
34
+ )
35
+ _LOG_START_STEP = (
36
+ "Add 'from aa_log import configure_logging' and call 'configure_logging()' where the app"
37
+ " starts (only apps call it; a library should skip it)."
38
+ )
39
+ _LOG_GITIGNORE_LINES = ("*.log", "*.log.[1-3]")
40
+ _REQ_NAME = re.compile(r"\s*([A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?)")
41
+ _NORMALIZE = re.compile(r"[-_.]+")
42
+
43
+
44
+ class AddError(Exception):
45
+ """Adding a piece cannot proceed because of the target folder or an existing file."""
46
+
47
+ def __init__(self, code: str, message: str, fix: str | None = None) -> None:
48
+ super().__init__(message)
49
+ self.code = code
50
+ self.fix = fix
51
+
52
+
53
+ @dataclass(frozen=True)
54
+ class Added:
55
+ """What ``add_piece`` changed or wrote in the project."""
56
+
57
+ files: list[str]
58
+ next_steps: list[str]
59
+
60
+
61
+ def add_piece(target: Path, piece: Piece) -> Added:
62
+ """Add ``piece`` to the project in ``target``."""
63
+ pyproject = target / PYPROJECT
64
+ if not pyproject.is_file():
65
+ raise AddError("not_a_project", f"{target} has no {PYPROJECT}", fix=NOT_A_PROJECT_FIX)
66
+ return _PIECES[piece](target, pyproject)
67
+
68
+
69
+ def _add_ci(target: Path, pyproject: Path) -> Added:
70
+ workflow = target / CI_WORKFLOW
71
+ expected = render(CI_TEMPLATE)
72
+ workflow_already_there = _check_workflow_path(target, workflow, expected)
73
+ existing = _declared_dependencies(pyproject)
74
+ missing = [tool for tool in _CI_TOOLS if tool not in existing]
75
+ if workflow_already_there and not missing and (target / UV_LOCK).is_file():
76
+ return Added(files=[], next_steps=[])
77
+ if missing:
78
+ changed = _uv_step("add dev dependencies", target, "add", "--dev", *missing)
79
+ else:
80
+ changed = _uv_step("lock dependencies", target, "lock")
81
+ if not workflow_already_there:
82
+ with file_step(WRITE_FILES_STEP):
83
+ write(workflow, expected)
84
+ changed.append(CI_WORKFLOW)
85
+ return Added(files=sorted(changed), next_steps=[])
86
+
87
+
88
+ def _add_log(target: Path, pyproject: Path) -> Added:
89
+ next_steps = _log_next_steps(target)
90
+ if LOG_PACKAGE in _declared_dependencies(pyproject, include_groups=False):
91
+ return Added(files=[], next_steps=next_steps)
92
+ changed = _uv_step("add log dependency", target, "add", LOG_REQUIREMENT)
93
+ return Added(files=sorted(changed), next_steps=next_steps)
94
+
95
+
96
+ def _log_next_steps(target: Path) -> list[str]:
97
+ steps = [_LOG_START_STEP]
98
+ missing = _missing_gitignore_lines(target / ".gitignore")
99
+ if missing:
100
+ steps.append(f"Add {', '.join(missing)} to .gitignore.")
101
+ return steps
102
+
103
+
104
+ def _missing_gitignore_lines(gitignore: Path) -> list[str]:
105
+ existing: set[str] = set()
106
+ if gitignore.is_file():
107
+ try:
108
+ existing = {line.strip() for line in gitignore.read_text(encoding="utf-8").splitlines()}
109
+ except OSError, UnicodeDecodeError:
110
+ existing = set()
111
+ return [line for line in _LOG_GITIGNORE_LINES if line not in existing]
112
+
113
+
114
+ def _uv_step(step_name: str, target: Path, *args: str) -> list[str]:
115
+ before = _read_uv_files(target)
116
+ step(step_name, target, "uv", *args)
117
+ return [name for name, content in _read_uv_files(target).items() if before.get(name) != content]
118
+
119
+
120
+ _PIECES = {Piece.CI: _add_ci, Piece.LOG: _add_log}
121
+
122
+
123
+ def _check_workflow_path(target: Path, workflow: Path, expected: str) -> bool:
124
+ for parent in (workflow.parent, *workflow.parent.parents):
125
+ if parent == target:
126
+ break
127
+ if parent.exists() and not parent.is_dir():
128
+ rel = parent.relative_to(target).as_posix()
129
+ raise AddError("file_exists", f"{rel} already exists and is not a folder")
130
+ if _has_content(workflow, expected):
131
+ return True
132
+ if workflow.exists():
133
+ raise AddError("file_exists", f"{CI_WORKFLOW} already exists with different content")
134
+ return False
135
+
136
+
137
+ def _has_content(path: Path, expected: str) -> bool:
138
+ if not path.is_file():
139
+ return False
140
+ try:
141
+ return path.read_text(encoding="utf-8") == expected
142
+ except OSError, UnicodeDecodeError:
143
+ return False
144
+
145
+
146
+ def _declared_dependencies(pyproject: Path, *, include_groups: bool = True) -> set[str]:
147
+ try:
148
+ config = tomllib.loads(pyproject.read_text(encoding="utf-8"))
149
+ except OSError, UnicodeDecodeError, tomllib.TOMLDecodeError:
150
+ return set()
151
+ project = _as_dict(config.get("project"))
152
+ items: list[object] = []
153
+ project_deps = project.get("dependencies", [])
154
+ if isinstance(project_deps, list):
155
+ items.extend(project_deps)
156
+ if include_groups:
157
+ dep_groups = _as_dict(config.get("dependency-groups"))
158
+ uv_config = _as_dict(_as_dict(config.get("tool")).get("uv"))
159
+ groups = _groups_with_legacy_dev(dep_groups, uv_config)
160
+ seen: set[str] = set()
161
+ for group_name in _default_group_names(uv_config, groups):
162
+ items.extend(_expand_group(groups, group_name, seen))
163
+ names: set[str] = set()
164
+ for item in items:
165
+ if isinstance(item, str) and (match := _REQ_NAME.match(item)):
166
+ names.add(_NORMALIZE.sub("-", match.group(1)).lower())
167
+ return names
168
+
169
+
170
+ def _groups_with_legacy_dev(
171
+ dep_groups: dict[str, Any], uv_config: dict[str, Any]
172
+ ) -> dict[str, Any]:
173
+ groups = dict(dep_groups)
174
+ legacy_dev = uv_config.get("dev-dependencies")
175
+ if isinstance(legacy_dev, list):
176
+ dev_group = groups.get("dev")
177
+ existing_dev = dev_group if isinstance(dev_group, list) else []
178
+ groups["dev"] = [*existing_dev, *legacy_dev]
179
+ return groups
180
+
181
+
182
+ def _default_group_names(uv_config: dict[str, Any], dep_groups: dict[str, Any]) -> list[str]:
183
+ default_groups = uv_config.get("default-groups")
184
+ if default_groups is None:
185
+ return ["dev"]
186
+ if default_groups == "all":
187
+ return list(dep_groups)
188
+ if isinstance(default_groups, list):
189
+ return [name for name in default_groups if isinstance(name, str)]
190
+ return []
191
+
192
+
193
+ def _expand_group(dep_groups: dict[str, Any], name: str, seen: set[str]) -> list[object]:
194
+ if name in seen:
195
+ return []
196
+ seen.add(name)
197
+ group = dep_groups.get(name)
198
+ if not isinstance(group, list):
199
+ return []
200
+ expanded: list[object] = []
201
+ for item in group:
202
+ if isinstance(item, dict) and isinstance(inc := item.get("include-group"), str):
203
+ expanded.extend(_expand_group(dep_groups, inc, seen))
204
+ else:
205
+ expanded.append(item)
206
+ return expanded
207
+
208
+
209
+ def _as_dict(value: object) -> dict[str, Any]:
210
+ if not isinstance(value, dict):
211
+ return {}
212
+ mapping: dict[str, Any] = value
213
+ return mapping
214
+
215
+
216
+ def _read_uv_files(target: Path) -> dict[str, bytes]:
217
+ return {
218
+ name: (target / name).read_bytes()
219
+ for name in (PYPROJECT, UV_LOCK)
220
+ if (target / name).is_file()
221
+ }
@@ -0,0 +1,33 @@
1
+ """Cheap command choices and option values, kept free of heavy imports."""
2
+
3
+ from enum import StrEnum
4
+
5
+
6
+ class Piece(StrEnum):
7
+ CI = "ci"
8
+ LOG = "log"
9
+
10
+
11
+ class License(StrEnum):
12
+ MIT = "MIT"
13
+ NONE = "none"
14
+
15
+
16
+ class Effect(StrEnum):
17
+ READ = "read"
18
+ WRITE = "write"
19
+
20
+
21
+ WITH_KINDS: tuple[str, ...] = ("IP_ADDRESS", "PHONE")
22
+ WITHOUT_KINDS: tuple[str, ...] = (
23
+ "AWS_ACCESS_KEY",
24
+ "GITHUB_TOKEN",
25
+ "API_KEY",
26
+ "SLACK_TOKEN",
27
+ "JWT",
28
+ "BEARER_TOKEN",
29
+ "PRIVATE_KEY",
30
+ "URL_PASSWORD",
31
+ "EMAIL",
32
+ "CARD",
33
+ )