codex-workspace-bootstrap 0.3.0__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.
- codex_workspace_bootstrap-0.3.0/LICENSE +21 -0
- codex_workspace_bootstrap-0.3.0/PKG-INFO +235 -0
- codex_workspace_bootstrap-0.3.0/README.md +207 -0
- codex_workspace_bootstrap-0.3.0/pyproject.toml +43 -0
- codex_workspace_bootstrap-0.3.0/setup.cfg +4 -0
- codex_workspace_bootstrap-0.3.0/src/codex_workspace_bootstrap/__init__.py +3 -0
- codex_workspace_bootstrap-0.3.0/src/codex_workspace_bootstrap/__main__.py +4 -0
- codex_workspace_bootstrap-0.3.0/src/codex_workspace_bootstrap/agents.py +108 -0
- codex_workspace_bootstrap-0.3.0/src/codex_workspace_bootstrap/audit.py +217 -0
- codex_workspace_bootstrap-0.3.0/src/codex_workspace_bootstrap/cli.py +111 -0
- codex_workspace_bootstrap-0.3.0/src/codex_workspace_bootstrap/sarif.py +83 -0
- codex_workspace_bootstrap-0.3.0/src/codex_workspace_bootstrap.egg-info/PKG-INFO +235 -0
- codex_workspace_bootstrap-0.3.0/src/codex_workspace_bootstrap.egg-info/SOURCES.txt +17 -0
- codex_workspace_bootstrap-0.3.0/src/codex_workspace_bootstrap.egg-info/dependency_links.txt +1 -0
- codex_workspace_bootstrap-0.3.0/src/codex_workspace_bootstrap.egg-info/entry_points.txt +2 -0
- codex_workspace_bootstrap-0.3.0/src/codex_workspace_bootstrap.egg-info/top_level.txt +1 -0
- codex_workspace_bootstrap-0.3.0/tests/test_audit.py +78 -0
- codex_workspace_bootstrap-0.3.0/tests/test_cli.py +106 -0
- codex_workspace_bootstrap-0.3.0/tests/test_sarif.py +44 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 kohli217
|
|
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,235 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: codex-workspace-bootstrap
|
|
3
|
+
Version: 0.3.0
|
|
4
|
+
Summary: Audit and bootstrap Windows repositories for effective Codex workflows.
|
|
5
|
+
Author: kohli217
|
|
6
|
+
License: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/kohli217/codex-workspace-bootstrap
|
|
8
|
+
Project-URL: Repository, https://github.com/kohli217/codex-workspace-bootstrap
|
|
9
|
+
Project-URL: Issues, https://github.com/kohli217/codex-workspace-bootstrap/issues
|
|
10
|
+
Project-URL: Changelog, https://github.com/kohli217/codex-workspace-bootstrap/blob/main/CHANGELOG.md
|
|
11
|
+
Keywords: codex,openai,windows,developer-tools,cli,oss,agents-md
|
|
12
|
+
Classifier: Development Status :: 3 - Alpha
|
|
13
|
+
Classifier: Environment :: Console
|
|
14
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
15
|
+
Classifier: Operating System :: Microsoft :: Windows
|
|
16
|
+
Classifier: Operating System :: POSIX :: Linux
|
|
17
|
+
Classifier: Programming Language :: Python :: 3
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
22
|
+
Classifier: Topic :: Software Development :: Quality Assurance
|
|
23
|
+
Classifier: Topic :: Software Development :: Testing
|
|
24
|
+
Requires-Python: >=3.10
|
|
25
|
+
Description-Content-Type: text/markdown
|
|
26
|
+
License-File: LICENSE
|
|
27
|
+
Dynamic: license-file
|
|
28
|
+
|
|
29
|
+
# codex-workspace-bootstrap
|
|
30
|
+
|
|
31
|
+
[](https://github.com/kohli217/codex-workspace-bootstrap/actions/workflows/ci.yml)
|
|
32
|
+
[](https://github.com/kohli217/codex-workspace-bootstrap/actions/workflows/codeql.yml)
|
|
33
|
+
[](https://github.com/kohli217/codex-workspace-bootstrap/releases/latest)
|
|
34
|
+
[](LICENSE)
|
|
35
|
+
[](pyproject.toml)
|
|
36
|
+
|
|
37
|
+
Make Windows repositories **Codex-ready** with automated environment checks, project instructions, safety audits, and maintainer workflows.
|
|
38
|
+
|
|
39
|
+
[日本語ガイド](docs/README.ja.md) · [Examples](docs/EXAMPLES.md) · [Roadmap](docs/ROADMAP.md) · [Releases](https://github.com/kohli217/codex-workspace-bootstrap/releases)
|
|
40
|
+
|
|
41
|
+
> Community-maintained project. It is not an official OpenAI product and is not affiliated with OpenAI.
|
|
42
|
+
|
|
43
|
+
## What problem does it solve?
|
|
44
|
+
|
|
45
|
+
Codex works better when a repository clearly states its toolchain, validation commands, constraints, and maintenance workflow. On Windows, those details are often scattered across README files, shell history, and machine-specific assumptions.
|
|
46
|
+
|
|
47
|
+
`codex-workspace-bootstrap` gives maintainers one repeatable entry point to:
|
|
48
|
+
|
|
49
|
+
- audit Git, Python, Node.js, npm, PowerShell, WSL, and Codex availability;
|
|
50
|
+
- inspect repository basics such as README, license, ignore rules, manifests, and `AGENTS.md`;
|
|
51
|
+
- warn about common secret-bearing filenames without reading their contents;
|
|
52
|
+
- distinguish tracked risky files from ignored or untracked files when Git is available;
|
|
53
|
+
- generate a project-aware `AGENTS.md` for Python, Node.js, mixed, or unknown projects;
|
|
54
|
+
- write machine-readable JSON and SARIF 2.1.0 reports;
|
|
55
|
+
- fail CI on blocking findings with `--strict`;
|
|
56
|
+
- validate releases through automated tests, self-audit, and build checks.
|
|
57
|
+
|
|
58
|
+
## Why Windows-first?
|
|
59
|
+
|
|
60
|
+
The project targets a real repository-readiness problem around Windows and Windows+WSL development. It does not claim to fix upstream Codex product bugs. See [docs/MOTIVATION.md](docs/MOTIVATION.md) for the scope and public upstream references.
|
|
61
|
+
|
|
62
|
+
## 30-second start
|
|
63
|
+
|
|
64
|
+
Install the pinned v0.3.0 wheel:
|
|
65
|
+
|
|
66
|
+
```powershell
|
|
67
|
+
py -m pip install "https://github.com/kohli217/codex-workspace-bootstrap/releases/download/v0.3.0/codex_workspace_bootstrap-0.3.0-py3-none-any.whl"
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
Audit the current repository:
|
|
71
|
+
|
|
72
|
+
```powershell
|
|
73
|
+
codex-workspace-bootstrap audit .
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
Generate project instructions:
|
|
77
|
+
|
|
78
|
+
```powershell
|
|
79
|
+
codex-workspace-bootstrap init-agents .
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
Check the installed version:
|
|
83
|
+
|
|
84
|
+
```powershell
|
|
85
|
+
codex-workspace-bootstrap --version
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
For more examples, see [docs/EXAMPLES.md](docs/EXAMPLES.md).
|
|
89
|
+
|
|
90
|
+
## Why a pinned release instead of `irm ... | iex`?
|
|
91
|
+
|
|
92
|
+
The recommended quick start installs a specific published wheel so users can see exactly which release they are installing. A PowerShell helper script remains available in [scripts/install.ps1](scripts/install.ps1), but piping remote scripts directly into PowerShell is not the recommended path.
|
|
93
|
+
|
|
94
|
+
## GitHub Action
|
|
95
|
+
|
|
96
|
+
Use the tool directly in an OSS repository workflow:
|
|
97
|
+
|
|
98
|
+
```yaml
|
|
99
|
+
- uses: actions/checkout@v7
|
|
100
|
+
- uses: actions/setup-python@v7
|
|
101
|
+
with:
|
|
102
|
+
python-version: "3.13"
|
|
103
|
+
- uses: kohli217/codex-workspace-bootstrap@v0.3.0
|
|
104
|
+
with:
|
|
105
|
+
path: .
|
|
106
|
+
strict: "true"
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
See [docs/GITHUB_ACTION.md](docs/GITHUB_ACTION.md) for the full workflow and input reference.
|
|
110
|
+
|
|
111
|
+
## Commands
|
|
112
|
+
|
|
113
|
+
### Audit a repository
|
|
114
|
+
|
|
115
|
+
```powershell
|
|
116
|
+
codex-workspace-bootstrap audit .
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
Write JSON output:
|
|
120
|
+
|
|
121
|
+
```powershell
|
|
122
|
+
codex-workspace-bootstrap audit . --json audit-report.json
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
Use strict mode in CI:
|
|
126
|
+
|
|
127
|
+
```powershell
|
|
128
|
+
codex-workspace-bootstrap audit . --strict
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
### SARIF / Code Scanning
|
|
132
|
+
|
|
133
|
+
```powershell
|
|
134
|
+
codex-workspace-bootstrap audit . --sarif codex-workspace-bootstrap.sarif
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
Blocking findings are emitted as SARIF errors and other warnings as SARIF warnings. See [docs/SARIF.md](docs/SARIF.md) for GitHub Code Scanning integration.
|
|
138
|
+
|
|
139
|
+
### Generate `AGENTS.md`
|
|
140
|
+
|
|
141
|
+
```powershell
|
|
142
|
+
codex-workspace-bootstrap init-agents .
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
The generator inspects common project manifests and layout signals, then writes conservative validation guidance. Existing `AGENTS.md` files are never overwritten unless `--force` is explicit.
|
|
146
|
+
|
|
147
|
+
## Safety model
|
|
148
|
+
|
|
149
|
+
- The core audit path performs local inspection only.
|
|
150
|
+
- The tool does **not** read or print the contents of suspected secret files.
|
|
151
|
+
- The tool does **not** send repository contents to a remote service.
|
|
152
|
+
- A passing audit is evidence about the checks performed, **not** a security guarantee.
|
|
153
|
+
- File modifications are opt-in; existing `AGENTS.md` files are protected by default.
|
|
154
|
+
|
|
155
|
+
See [SECURITY.md](SECURITY.md) for reporting guidance.
|
|
156
|
+
|
|
157
|
+
## Maintainer workflow
|
|
158
|
+
|
|
159
|
+
This project uses an issue → branch → pull request → CI → merge → release workflow.
|
|
160
|
+
|
|
161
|
+
Current automated checks include:
|
|
162
|
+
|
|
163
|
+
- Windows and Ubuntu test matrices on Python 3.10 and 3.13;
|
|
164
|
+
- built-wheel smoke testing;
|
|
165
|
+
- strict self-audit before releases;
|
|
166
|
+
- CodeQL static analysis;
|
|
167
|
+
- weekly dependency update checks for Python and GitHub Actions;
|
|
168
|
+
- validated one-click GitHub releases with attached wheel and source distribution.
|
|
169
|
+
|
|
170
|
+
Release history began with [v0.1.0](https://github.com/kohli217/codex-workspace-bootstrap/releases/tag/v0.1.0).
|
|
171
|
+
|
|
172
|
+
## Codex-oriented workflow
|
|
173
|
+
|
|
174
|
+
A practical repository workflow is:
|
|
175
|
+
|
|
176
|
+
1. run `audit`;
|
|
177
|
+
2. review warnings and blocking findings;
|
|
178
|
+
3. generate or review `AGENTS.md`;
|
|
179
|
+
4. give Codex a scoped issue or task;
|
|
180
|
+
5. run the repository tests and the audit again;
|
|
181
|
+
6. inspect the diff before merge;
|
|
182
|
+
7. release only after CI passes.
|
|
183
|
+
|
|
184
|
+
See [AGENTS.md](AGENTS.md) for this repository's own agent instructions and [skills/codex-workspace-bootstrap/SKILL.md](skills/codex-workspace-bootstrap/SKILL.md) for the reusable skill.
|
|
185
|
+
|
|
186
|
+
## Project scope
|
|
187
|
+
|
|
188
|
+
### In scope
|
|
189
|
+
|
|
190
|
+
- Windows-first repository readiness checks;
|
|
191
|
+
- Codex-oriented project instructions;
|
|
192
|
+
- maintainer automation that is deterministic and reviewable;
|
|
193
|
+
- CI-friendly reporting and safe defaults.
|
|
194
|
+
|
|
195
|
+
### Not in scope
|
|
196
|
+
|
|
197
|
+
- claiming that a repository is secure because an audit passed;
|
|
198
|
+
- silently changing user configuration;
|
|
199
|
+
- uploading repository contents by default;
|
|
200
|
+
- replacing project-specific documentation or human review.
|
|
201
|
+
|
|
202
|
+
## Development
|
|
203
|
+
|
|
204
|
+
```powershell
|
|
205
|
+
git clone https://github.com/kohli217/codex-workspace-bootstrap.git
|
|
206
|
+
cd codex-workspace-bootstrap
|
|
207
|
+
py -m venv .venv
|
|
208
|
+
.\.venv\Scripts\Activate.ps1
|
|
209
|
+
python -m pip install -e . pytest
|
|
210
|
+
pytest -q
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md), [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md), and [SUPPORT.md](SUPPORT.md).
|
|
214
|
+
|
|
215
|
+
## Maintainer and adoption
|
|
216
|
+
|
|
217
|
+
Primary maintainer identity and responsibilities are documented in [MAINTAINERS.md](MAINTAINERS.md).
|
|
218
|
+
|
|
219
|
+
If you use the project, please share a real usage report through the GitHub issue template. The project deliberately avoids fabricated testimonials or adoption claims. See [docs/ADOPTION.md](docs/ADOPTION.md).
|
|
220
|
+
|
|
221
|
+
## Roadmap
|
|
222
|
+
|
|
223
|
+
See [docs/ROADMAP.md](docs/ROADMAP.md).
|
|
224
|
+
|
|
225
|
+
## Releasing
|
|
226
|
+
|
|
227
|
+
Maintainers can create a tested GitHub release from the Actions UI. See [docs/RELEASING.md](docs/RELEASING.md).
|
|
228
|
+
|
|
229
|
+
## Citation
|
|
230
|
+
|
|
231
|
+
Machine-readable citation metadata is available in [CITATION.cff](CITATION.cff).
|
|
232
|
+
|
|
233
|
+
## License
|
|
234
|
+
|
|
235
|
+
MIT. See [LICENSE](LICENSE).
|
|
@@ -0,0 +1,207 @@
|
|
|
1
|
+
# codex-workspace-bootstrap
|
|
2
|
+
|
|
3
|
+
[](https://github.com/kohli217/codex-workspace-bootstrap/actions/workflows/ci.yml)
|
|
4
|
+
[](https://github.com/kohli217/codex-workspace-bootstrap/actions/workflows/codeql.yml)
|
|
5
|
+
[](https://github.com/kohli217/codex-workspace-bootstrap/releases/latest)
|
|
6
|
+
[](LICENSE)
|
|
7
|
+
[](pyproject.toml)
|
|
8
|
+
|
|
9
|
+
Make Windows repositories **Codex-ready** with automated environment checks, project instructions, safety audits, and maintainer workflows.
|
|
10
|
+
|
|
11
|
+
[日本語ガイド](docs/README.ja.md) · [Examples](docs/EXAMPLES.md) · [Roadmap](docs/ROADMAP.md) · [Releases](https://github.com/kohli217/codex-workspace-bootstrap/releases)
|
|
12
|
+
|
|
13
|
+
> Community-maintained project. It is not an official OpenAI product and is not affiliated with OpenAI.
|
|
14
|
+
|
|
15
|
+
## What problem does it solve?
|
|
16
|
+
|
|
17
|
+
Codex works better when a repository clearly states its toolchain, validation commands, constraints, and maintenance workflow. On Windows, those details are often scattered across README files, shell history, and machine-specific assumptions.
|
|
18
|
+
|
|
19
|
+
`codex-workspace-bootstrap` gives maintainers one repeatable entry point to:
|
|
20
|
+
|
|
21
|
+
- audit Git, Python, Node.js, npm, PowerShell, WSL, and Codex availability;
|
|
22
|
+
- inspect repository basics such as README, license, ignore rules, manifests, and `AGENTS.md`;
|
|
23
|
+
- warn about common secret-bearing filenames without reading their contents;
|
|
24
|
+
- distinguish tracked risky files from ignored or untracked files when Git is available;
|
|
25
|
+
- generate a project-aware `AGENTS.md` for Python, Node.js, mixed, or unknown projects;
|
|
26
|
+
- write machine-readable JSON and SARIF 2.1.0 reports;
|
|
27
|
+
- fail CI on blocking findings with `--strict`;
|
|
28
|
+
- validate releases through automated tests, self-audit, and build checks.
|
|
29
|
+
|
|
30
|
+
## Why Windows-first?
|
|
31
|
+
|
|
32
|
+
The project targets a real repository-readiness problem around Windows and Windows+WSL development. It does not claim to fix upstream Codex product bugs. See [docs/MOTIVATION.md](docs/MOTIVATION.md) for the scope and public upstream references.
|
|
33
|
+
|
|
34
|
+
## 30-second start
|
|
35
|
+
|
|
36
|
+
Install the pinned v0.3.0 wheel:
|
|
37
|
+
|
|
38
|
+
```powershell
|
|
39
|
+
py -m pip install "https://github.com/kohli217/codex-workspace-bootstrap/releases/download/v0.3.0/codex_workspace_bootstrap-0.3.0-py3-none-any.whl"
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
Audit the current repository:
|
|
43
|
+
|
|
44
|
+
```powershell
|
|
45
|
+
codex-workspace-bootstrap audit .
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
Generate project instructions:
|
|
49
|
+
|
|
50
|
+
```powershell
|
|
51
|
+
codex-workspace-bootstrap init-agents .
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
Check the installed version:
|
|
55
|
+
|
|
56
|
+
```powershell
|
|
57
|
+
codex-workspace-bootstrap --version
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
For more examples, see [docs/EXAMPLES.md](docs/EXAMPLES.md).
|
|
61
|
+
|
|
62
|
+
## Why a pinned release instead of `irm ... | iex`?
|
|
63
|
+
|
|
64
|
+
The recommended quick start installs a specific published wheel so users can see exactly which release they are installing. A PowerShell helper script remains available in [scripts/install.ps1](scripts/install.ps1), but piping remote scripts directly into PowerShell is not the recommended path.
|
|
65
|
+
|
|
66
|
+
## GitHub Action
|
|
67
|
+
|
|
68
|
+
Use the tool directly in an OSS repository workflow:
|
|
69
|
+
|
|
70
|
+
```yaml
|
|
71
|
+
- uses: actions/checkout@v7
|
|
72
|
+
- uses: actions/setup-python@v7
|
|
73
|
+
with:
|
|
74
|
+
python-version: "3.13"
|
|
75
|
+
- uses: kohli217/codex-workspace-bootstrap@v0.3.0
|
|
76
|
+
with:
|
|
77
|
+
path: .
|
|
78
|
+
strict: "true"
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
See [docs/GITHUB_ACTION.md](docs/GITHUB_ACTION.md) for the full workflow and input reference.
|
|
82
|
+
|
|
83
|
+
## Commands
|
|
84
|
+
|
|
85
|
+
### Audit a repository
|
|
86
|
+
|
|
87
|
+
```powershell
|
|
88
|
+
codex-workspace-bootstrap audit .
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
Write JSON output:
|
|
92
|
+
|
|
93
|
+
```powershell
|
|
94
|
+
codex-workspace-bootstrap audit . --json audit-report.json
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
Use strict mode in CI:
|
|
98
|
+
|
|
99
|
+
```powershell
|
|
100
|
+
codex-workspace-bootstrap audit . --strict
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
### SARIF / Code Scanning
|
|
104
|
+
|
|
105
|
+
```powershell
|
|
106
|
+
codex-workspace-bootstrap audit . --sarif codex-workspace-bootstrap.sarif
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
Blocking findings are emitted as SARIF errors and other warnings as SARIF warnings. See [docs/SARIF.md](docs/SARIF.md) for GitHub Code Scanning integration.
|
|
110
|
+
|
|
111
|
+
### Generate `AGENTS.md`
|
|
112
|
+
|
|
113
|
+
```powershell
|
|
114
|
+
codex-workspace-bootstrap init-agents .
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
The generator inspects common project manifests and layout signals, then writes conservative validation guidance. Existing `AGENTS.md` files are never overwritten unless `--force` is explicit.
|
|
118
|
+
|
|
119
|
+
## Safety model
|
|
120
|
+
|
|
121
|
+
- The core audit path performs local inspection only.
|
|
122
|
+
- The tool does **not** read or print the contents of suspected secret files.
|
|
123
|
+
- The tool does **not** send repository contents to a remote service.
|
|
124
|
+
- A passing audit is evidence about the checks performed, **not** a security guarantee.
|
|
125
|
+
- File modifications are opt-in; existing `AGENTS.md` files are protected by default.
|
|
126
|
+
|
|
127
|
+
See [SECURITY.md](SECURITY.md) for reporting guidance.
|
|
128
|
+
|
|
129
|
+
## Maintainer workflow
|
|
130
|
+
|
|
131
|
+
This project uses an issue → branch → pull request → CI → merge → release workflow.
|
|
132
|
+
|
|
133
|
+
Current automated checks include:
|
|
134
|
+
|
|
135
|
+
- Windows and Ubuntu test matrices on Python 3.10 and 3.13;
|
|
136
|
+
- built-wheel smoke testing;
|
|
137
|
+
- strict self-audit before releases;
|
|
138
|
+
- CodeQL static analysis;
|
|
139
|
+
- weekly dependency update checks for Python and GitHub Actions;
|
|
140
|
+
- validated one-click GitHub releases with attached wheel and source distribution.
|
|
141
|
+
|
|
142
|
+
Release history began with [v0.1.0](https://github.com/kohli217/codex-workspace-bootstrap/releases/tag/v0.1.0).
|
|
143
|
+
|
|
144
|
+
## Codex-oriented workflow
|
|
145
|
+
|
|
146
|
+
A practical repository workflow is:
|
|
147
|
+
|
|
148
|
+
1. run `audit`;
|
|
149
|
+
2. review warnings and blocking findings;
|
|
150
|
+
3. generate or review `AGENTS.md`;
|
|
151
|
+
4. give Codex a scoped issue or task;
|
|
152
|
+
5. run the repository tests and the audit again;
|
|
153
|
+
6. inspect the diff before merge;
|
|
154
|
+
7. release only after CI passes.
|
|
155
|
+
|
|
156
|
+
See [AGENTS.md](AGENTS.md) for this repository's own agent instructions and [skills/codex-workspace-bootstrap/SKILL.md](skills/codex-workspace-bootstrap/SKILL.md) for the reusable skill.
|
|
157
|
+
|
|
158
|
+
## Project scope
|
|
159
|
+
|
|
160
|
+
### In scope
|
|
161
|
+
|
|
162
|
+
- Windows-first repository readiness checks;
|
|
163
|
+
- Codex-oriented project instructions;
|
|
164
|
+
- maintainer automation that is deterministic and reviewable;
|
|
165
|
+
- CI-friendly reporting and safe defaults.
|
|
166
|
+
|
|
167
|
+
### Not in scope
|
|
168
|
+
|
|
169
|
+
- claiming that a repository is secure because an audit passed;
|
|
170
|
+
- silently changing user configuration;
|
|
171
|
+
- uploading repository contents by default;
|
|
172
|
+
- replacing project-specific documentation or human review.
|
|
173
|
+
|
|
174
|
+
## Development
|
|
175
|
+
|
|
176
|
+
```powershell
|
|
177
|
+
git clone https://github.com/kohli217/codex-workspace-bootstrap.git
|
|
178
|
+
cd codex-workspace-bootstrap
|
|
179
|
+
py -m venv .venv
|
|
180
|
+
.\.venv\Scripts\Activate.ps1
|
|
181
|
+
python -m pip install -e . pytest
|
|
182
|
+
pytest -q
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md), [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md), and [SUPPORT.md](SUPPORT.md).
|
|
186
|
+
|
|
187
|
+
## Maintainer and adoption
|
|
188
|
+
|
|
189
|
+
Primary maintainer identity and responsibilities are documented in [MAINTAINERS.md](MAINTAINERS.md).
|
|
190
|
+
|
|
191
|
+
If you use the project, please share a real usage report through the GitHub issue template. The project deliberately avoids fabricated testimonials or adoption claims. See [docs/ADOPTION.md](docs/ADOPTION.md).
|
|
192
|
+
|
|
193
|
+
## Roadmap
|
|
194
|
+
|
|
195
|
+
See [docs/ROADMAP.md](docs/ROADMAP.md).
|
|
196
|
+
|
|
197
|
+
## Releasing
|
|
198
|
+
|
|
199
|
+
Maintainers can create a tested GitHub release from the Actions UI. See [docs/RELEASING.md](docs/RELEASING.md).
|
|
200
|
+
|
|
201
|
+
## Citation
|
|
202
|
+
|
|
203
|
+
Machine-readable citation metadata is available in [CITATION.cff](CITATION.cff).
|
|
204
|
+
|
|
205
|
+
## License
|
|
206
|
+
|
|
207
|
+
MIT. See [LICENSE](LICENSE).
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=68"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "codex-workspace-bootstrap"
|
|
7
|
+
version = "0.3.0"
|
|
8
|
+
description = "Audit and bootstrap Windows repositories for effective Codex workflows."
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
requires-python = ">=3.10"
|
|
11
|
+
license = { text = "MIT" }
|
|
12
|
+
authors = [{ name = "kohli217" }]
|
|
13
|
+
keywords = ["codex", "openai", "windows", "developer-tools", "cli", "oss", "agents-md"]
|
|
14
|
+
classifiers = [
|
|
15
|
+
"Development Status :: 3 - Alpha",
|
|
16
|
+
"Environment :: Console",
|
|
17
|
+
"License :: OSI Approved :: MIT License",
|
|
18
|
+
"Operating System :: Microsoft :: Windows",
|
|
19
|
+
"Operating System :: POSIX :: Linux",
|
|
20
|
+
"Programming Language :: Python :: 3",
|
|
21
|
+
"Programming Language :: Python :: 3.10",
|
|
22
|
+
"Programming Language :: Python :: 3.11",
|
|
23
|
+
"Programming Language :: Python :: 3.12",
|
|
24
|
+
"Programming Language :: Python :: 3.13",
|
|
25
|
+
"Topic :: Software Development :: Quality Assurance",
|
|
26
|
+
"Topic :: Software Development :: Testing",
|
|
27
|
+
]
|
|
28
|
+
|
|
29
|
+
[project.urls]
|
|
30
|
+
Homepage = "https://github.com/kohli217/codex-workspace-bootstrap"
|
|
31
|
+
Repository = "https://github.com/kohli217/codex-workspace-bootstrap"
|
|
32
|
+
Issues = "https://github.com/kohli217/codex-workspace-bootstrap/issues"
|
|
33
|
+
Changelog = "https://github.com/kohli217/codex-workspace-bootstrap/blob/main/CHANGELOG.md"
|
|
34
|
+
|
|
35
|
+
[project.scripts]
|
|
36
|
+
codex-workspace-bootstrap = "codex_workspace_bootstrap.cli:main"
|
|
37
|
+
|
|
38
|
+
[tool.setuptools.packages.find]
|
|
39
|
+
where = ["src"]
|
|
40
|
+
|
|
41
|
+
[tool.pytest.ini_options]
|
|
42
|
+
testpaths = ["tests"]
|
|
43
|
+
pythonpath = ["src"]
|
|
@@ -0,0 +1,108 @@
|
|
|
1
|
+
from __future__ import annotations
|
|
2
|
+
|
|
3
|
+
import json
|
|
4
|
+
from pathlib import Path
|
|
5
|
+
|
|
6
|
+
|
|
7
|
+
PYTHON_MARKERS = ("pyproject.toml", "requirements.txt", "setup.py", "setup.cfg")
|
|
8
|
+
NODE_MARKER = "package.json"
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
def detect_project_signals(root: Path) -> list[str]:
|
|
12
|
+
signals: list[str] = []
|
|
13
|
+
if any((root / marker).exists() for marker in PYTHON_MARKERS):
|
|
14
|
+
signals.append("Python")
|
|
15
|
+
if (root / NODE_MARKER).exists():
|
|
16
|
+
signals.append("Node.js")
|
|
17
|
+
return signals
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
def _node_script_names(root: Path) -> set[str]:
|
|
21
|
+
package_json = root / NODE_MARKER
|
|
22
|
+
if not package_json.exists():
|
|
23
|
+
return set()
|
|
24
|
+
|
|
25
|
+
try:
|
|
26
|
+
data = json.loads(package_json.read_text(encoding="utf-8"))
|
|
27
|
+
except (OSError, json.JSONDecodeError, UnicodeDecodeError):
|
|
28
|
+
return set()
|
|
29
|
+
|
|
30
|
+
scripts = data.get("scripts")
|
|
31
|
+
if not isinstance(scripts, dict):
|
|
32
|
+
return set()
|
|
33
|
+
|
|
34
|
+
return {name for name, value in scripts.items() if isinstance(name, str) and isinstance(value, str)}
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
def validation_commands(root: Path) -> list[str]:
|
|
38
|
+
signals = detect_project_signals(root)
|
|
39
|
+
commands: list[str] = []
|
|
40
|
+
|
|
41
|
+
if "Python" in signals:
|
|
42
|
+
if (root / "tests").is_dir():
|
|
43
|
+
commands.append("python -m pytest")
|
|
44
|
+
else:
|
|
45
|
+
commands.append("python -m compileall .")
|
|
46
|
+
|
|
47
|
+
if "Node.js" in signals:
|
|
48
|
+
scripts = _node_script_names(root)
|
|
49
|
+
if "test" in scripts:
|
|
50
|
+
commands.append("npm test")
|
|
51
|
+
if "lint" in scripts:
|
|
52
|
+
commands.append("npm run lint")
|
|
53
|
+
if not {"test", "lint"} & scripts:
|
|
54
|
+
commands.append("npm install --ignore-scripts --package-lock-only --dry-run")
|
|
55
|
+
|
|
56
|
+
commands.extend(
|
|
57
|
+
[
|
|
58
|
+
"codex-workspace-bootstrap audit . --strict",
|
|
59
|
+
"git diff --check",
|
|
60
|
+
"git status --short",
|
|
61
|
+
]
|
|
62
|
+
)
|
|
63
|
+
return commands
|
|
64
|
+
|
|
65
|
+
|
|
66
|
+
def generate_agents(root: Path) -> str:
|
|
67
|
+
signals = detect_project_signals(root)
|
|
68
|
+
signal_text = ", ".join(signals) if signals else "No common Python or Node.js manifest detected"
|
|
69
|
+
commands = validation_commands(root)
|
|
70
|
+
command_lines = "\n".join(f"- `{command}`" for command in commands)
|
|
71
|
+
|
|
72
|
+
return f"""# AGENTS.md
|
|
73
|
+
|
|
74
|
+
## Purpose
|
|
75
|
+
|
|
76
|
+
This repository is maintained with assistance from Codex.
|
|
77
|
+
|
|
78
|
+
## Detected project signals
|
|
79
|
+
|
|
80
|
+
{signal_text}
|
|
81
|
+
|
|
82
|
+
These signals are derived only from files present in the repository. Review this file before relying on the generated commands.
|
|
83
|
+
|
|
84
|
+
## Working rules
|
|
85
|
+
|
|
86
|
+
- Read README files and relevant project manifests before editing.
|
|
87
|
+
- Keep changes scoped to the requested issue or task.
|
|
88
|
+
- Do not add secrets, credentials, tokens, private data, or generated environment files.
|
|
89
|
+
- Prefer deterministic, scriptable commands over manual steps.
|
|
90
|
+
- Preserve existing platform support unless the task explicitly changes it.
|
|
91
|
+
- Add or update tests for behavior changes when the repository has a test suite.
|
|
92
|
+
- Explain user-visible behavior changes in the pull request or commit summary.
|
|
93
|
+
- Inspect the final diff before proposing completion.
|
|
94
|
+
|
|
95
|
+
## Suggested validation
|
|
96
|
+
|
|
97
|
+
Run the commands that apply to the change:
|
|
98
|
+
|
|
99
|
+
{command_lines}
|
|
100
|
+
|
|
101
|
+
If a generated command does not match the repository's documented workflow, follow the repository documentation and update this file rather than forcing the command to run.
|
|
102
|
+
|
|
103
|
+
## Safety
|
|
104
|
+
|
|
105
|
+
- Do not print the contents of files suspected to contain secrets.
|
|
106
|
+
- Do not overwrite user files without explicit approval.
|
|
107
|
+
- Treat successful automated checks as evidence, not as a security guarantee.
|
|
108
|
+
"""
|