codex-workspace-bootstrap 0.3.0__tar.gz → 0.5.0__tar.gz

codex_workspace_bootstrap-0.5.0/PKG-INFO

@@ -0,0 +1,306 @@
+Metadata-Version: 2.4
+Name: codex-workspace-bootstrap
+Version: 0.5.0
+Summary: Preflight AI coding repositories before Codex, Copilot, Cline, Claude, Gemini, Continue, or Cursor touches them.
+Author: kohli217
+License: MIT
+Project-URL: Homepage, https://github.com/kohli217/codex-workspace-bootstrap
+Project-URL: Repository, https://github.com/kohli217/codex-workspace-bootstrap
+Project-URL: Issues, https://github.com/kohli217/codex-workspace-bootstrap/issues
+Project-URL: Changelog, https://github.com/kohli217/codex-workspace-bootstrap/blob/main/CHANGELOG.md
+Keywords: ai-coding,codex,openai,windows,github-actions,developer-tools,cli,agents-md
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# codex-workspace-bootstrap
+
+[![CI](https://github.com/kohli217/codex-workspace-bootstrap/actions/workflows/ci.yml/badge.svg)](https://github.com/kohli217/codex-workspace-bootstrap/actions/workflows/ci.yml)
+[![CodeQL](https://github.com/kohli217/codex-workspace-bootstrap/actions/workflows/codeql.yml/badge.svg)](https://github.com/kohli217/codex-workspace-bootstrap/actions/workflows/codeql.yml)
+[![Release](https://img.shields.io/github/v/release/kohli217/codex-workspace-bootstrap)](https://github.com/kohli217/codex-workspace-bootstrap/releases/latest)
+[![PyPI](https://img.shields.io/pypi/v/codex-workspace-bootstrap)](https://pypi.org/project/codex-workspace-bootstrap/)
+[![License](https://img.shields.io/github/license/kohli217/codex-workspace-bootstrap)](LICENSE)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](pyproject.toml)
+
+**Preflight your repository before an AI coding agent touches it — and catch instruction drift before different agents follow different rules.**
+
+Windows-first. Local by default. CI-friendly. Designed for repositories used with Codex, Copilot, Cline, Claude Code, Gemini CLI, Continue, Cursor, and similar coding agents.
+
+[日本語ガイド](docs/README.ja.md) · [Examples](docs/EXAMPLES.md) · [GitHub Action](docs/GITHUB_ACTION.md) · [Roadmap](docs/ROADMAP.md) · [Releases](https://github.com/kohli217/codex-workspace-bootstrap/releases)
+
+> Community-maintained project. Not an official OpenAI product and not affiliated with OpenAI.
+
+## The 20-second demo
+
+```powershell
+py -m pip install codex-workspace-bootstrap
+cwb preflight .
+```
+
+Typical output:
+
+```text
+AI Repository Preflight
+State: NEEDS ATTENTION
+Project: Python
+AI instructions: none detected
+Audit: 10 passed, 4 warnings, 0 blocking
+Instruction integrity: 0 findings, 0 drift, 0 invalid commands, 0 metadata
+Next actions:
+  [P1] Add repository instructions for AI coding agents -> cwb init-agents .
+  [P2] Make the Codex CLI available when local Codex workflows are intended -> codex --version
+```
+
+Fix the highest-value gap:
+
+```powershell
+cwb init-agents .
+cwb preflight .
+```
+
+The goal is not a vanity score. The result is one of:
+
+- **READY** — core repository signals and AI instructions are present, with no blocking finding;
+- **NEEDS ATTENTION** — usable, but important repository or AI-instruction signals are missing;
+- **BLOCKED** — a blocking finding such as a tracked secret-risk filename needs review.
+
+## What it checks
+
+### Repository readiness
+
+- Git repository
+- README
+- license
+- `.gitignore`
+- common project manifests
+- local Git / Python / Node.js / npm / PowerShell / WSL / Codex signals
+
+### AI instruction coverage
+
+The preflight detects repository instruction/config signals for:
+
+- **Codex / OpenAI agents** — `AGENTS.md`
+- **GitHub Copilot** — repository instructions
+- **Cline**
+- **Claude Code**
+- **Gemini CLI**
+- **Continue**
+- **Cursor**
+
+It does not claim these files are correct merely because they exist. It tells you what was detected so a maintainer can review the actual instructions.
+
+### Cross-agent instruction integrity
+
+When multiple AI instruction files exist, `cwb` reads executable-looking commands and checks them against repository evidence. It understands nested `AGENTS.md` / `AGENTS.override.md`, nested Cursor `.cursor/rules`, and common path-specific frontmatter such as Copilot `applyTo` and rule `globs`. It can flag:
+
+- package-manager mismatches against `packageManager` and lockfiles;
+- cross-agent package-manager drift;
+- missing `package.json` scripts referenced by instructions;
+- conflicting test/lint/build validation commands when instruction files have no shared command for the same validation family.
+
+The lint is intentionally conservative: different files may contain additional commands without being treated as conflicts when they share a compatible validation baseline. Commands from different scopes are not compared as if they were global rules. Path-specific rules are validated individually against repository evidence but are not cross-compared for drift unless their full selector semantics can be represented safely. A repository is not marked READY when it only has nested/path-specific instructions and no repository-wide instruction baseline.
+
+### Risk signals
+
+The audit warns about common secret-bearing filenames without printing their contents. When Git is available, it distinguishes **tracked**, **ignored**, and **untracked/unknown** candidates. Tracked risky filenames can become blocking findings in strict mode.
+
+This is intentionally a lightweight preflight check, not a replacement for deep scanners such as Gitleaks or Trivy.
+
+## Why this exists
+
+AI coding tools are good at editing code. They are not a substitute for repository hygiene.
+
+Before handing a repository to an agent, maintainers still need answers to questions such as:
+
+- Is this the right repository root?
+- Is the expected toolchain available?
+- Does the repository explain how to validate changes?
+- Are AI instructions present?
+- Are risky files accidentally tracked?
+- Can CI surface the same checks for every pull request?
+
+`codex-workspace-bootstrap` turns those questions into one repeatable preflight.
+
+## Short CLI
+
+The package installs both command names:
+
+```powershell
+cwb --version
+codex-workspace-bootstrap --version
+```
+
+Use `cwb` for day-to-day work.
+
+## Commands
+
+### One-command preflight
+
+```powershell
+cwb preflight .
+```
+
+Write reports for automation or review:
+
+```powershell
+cwb preflight . --json preflight.json
+cwb preflight . --markdown preflight.md
+cwb preflight . --sarif preflight.sarif
+```
+
+Use strict mode when blocking findings should return a non-zero exit code:
+
+```powershell
+cwb preflight . --strict
+```
+
+Fail CI on any instruction-integrity finding:
+
+```powershell
+cwb preflight . --fail-on-integrity
+```
+
+### Detailed audit
+
+```powershell
+cwb audit .
+cwb audit . --json audit.json
+cwb audit . --sarif audit.sarif
+cwb audit . --strict
+```
+
+### Safe fix preview
+
+```powershell
+cwb fix .
+```
+
+This is preview-only by default. To apply only low-risk supported fixes:
+
+```powershell
+cwb fix . --apply
+```
+
+Existing conflicting instruction files are never auto-rewritten. They remain human-review findings.
+
+### Non-destructive doctor
+
+```powershell
+cwb doctor .
+```
+
+`doctor` prints remediation guidance only. It does not install software or modify system configuration.
+
+### Generate `AGENTS.md`
+
+```powershell
+cwb init-agents .
+```
+
+Generation is evidence-based: the tool cross-checks project manifests, package scripts, pytest configuration, and README commands. Plausible but unconfirmed commands are separated for maintainer review. Existing `AGENTS.md` files are never overwritten unless `--force` is explicit.
+
+## GitHub Action
+
+The reusable Action is published on GitHub Marketplace.
+
+```yaml
+- uses: actions/checkout@v7
+- uses: actions/setup-python@v7
+  with:
+    python-version: "3.13"
+- uses: kohli217/codex-workspace-bootstrap@v0.5.0
+  with:
+    path: .
+    strict: "true"
+    fail_on_integrity: "true"
+```
+
+The Action adds the preflight Markdown report to the **GitHub Actions job summary**, so maintainers get a readable readiness snapshot without digging through raw logs. Optional SARIF output contains both repository-audit and instruction-integrity findings and can be uploaded to GitHub Code Scanning.
+
+See [docs/GITHUB_ACTION.md](docs/GITHUB_ACTION.md).
+
+Read-only evaluations against real public repositories are documented in [docs/PUBLIC_REPO_EVALUATIONS.md](docs/PUBLIC_REPO_EVALUATIONS.md). They are reproducible technical evaluations, not claims of third-party adoption.
+
+## Where it fits
+
+This project is a **preflight layer**, not an AI coding agent and not a deep security scanner.
+
+| Need | Use |
+| --- | --- |
+| Edit or generate code | Codex, Copilot, Cline, Claude Code, Continue, etc. |
+| Deep secret/vulnerability scanning | Gitleaks, Trivy, dedicated security tooling |
+| Reproducible toolchain management | Dev Containers, mise, project-specific tooling |
+| **Check whether a repository is ready before AI coding starts** | **codex-workspace-bootstrap** |
+
+The intent is to complement those tools, not replace them.
+
+## Safety model
+
+- Core checks run locally.
+- Suspected secret files are not opened or printed by the filename-risk check.
+- Repository contents are not sent to a remote AI service by the core audit.
+- Instruction files are read locally for deterministic linting; extracted commands are never executed by the integrity lint.
+- Existing `AGENTS.md` files are protected unless overwrite is explicit.
+- A passing preflight is evidence about the checks performed, **not a security guarantee**.
+
+See [SECURITY.md](SECURITY.md).
+
+## Maintainer workflow
+
+The project itself uses issue → branch → pull request → CI → merge → release.
+
+Automated validation includes:
+
+- Windows and Ubuntu;
+- Python 3.10 and 3.13;
+- built-wheel smoke tests;
+- Action self-tests;
+- strict self-audit;
+- CodeQL;
+- Dependabot;
+- SARIF validation;
+- PyPI publishing through GitHub OIDC Trusted Publishing.
+
+## Install
+
+PyPI:
+
+```powershell
+py -m pip install codex-workspace-bootstrap
+```
+
+Pinned GitHub release artifact:
+
+```powershell
+py -m pip install "https://github.com/kohli217/codex-workspace-bootstrap/releases/download/v0.5.0/codex_workspace_bootstrap-0.5.0-py3-none-any.whl"
+```
+
+## Development
+
+```powershell
+git clone https://github.com/kohli217/codex-workspace-bootstrap.git
+cd codex-workspace-bootstrap
+py -m venv .venv
+.\.venv\Scripts\Activate.ps1
+python -m pip install -e . pytest
+pytest -q
+```
+
+Contributions and real-world usage reports are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md), [SUPPORT.md](SUPPORT.md), [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md), and [docs/ADOPTION.md](docs/ADOPTION.md).
+
+## License
+
+MIT. See [LICENSE](LICENSE).

codex_workspace_bootstrap-0.5.0/README.md

@@ -0,0 +1,278 @@
+# codex-workspace-bootstrap
+
+[![CI](https://github.com/kohli217/codex-workspace-bootstrap/actions/workflows/ci.yml/badge.svg)](https://github.com/kohli217/codex-workspace-bootstrap/actions/workflows/ci.yml)
+[![CodeQL](https://github.com/kohli217/codex-workspace-bootstrap/actions/workflows/codeql.yml/badge.svg)](https://github.com/kohli217/codex-workspace-bootstrap/actions/workflows/codeql.yml)
+[![Release](https://img.shields.io/github/v/release/kohli217/codex-workspace-bootstrap)](https://github.com/kohli217/codex-workspace-bootstrap/releases/latest)
+[![PyPI](https://img.shields.io/pypi/v/codex-workspace-bootstrap)](https://pypi.org/project/codex-workspace-bootstrap/)
+[![License](https://img.shields.io/github/license/kohli217/codex-workspace-bootstrap)](LICENSE)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](pyproject.toml)
+
+**Preflight your repository before an AI coding agent touches it — and catch instruction drift before different agents follow different rules.**
+
+Windows-first. Local by default. CI-friendly. Designed for repositories used with Codex, Copilot, Cline, Claude Code, Gemini CLI, Continue, Cursor, and similar coding agents.
+
+[日本語ガイド](docs/README.ja.md) · [Examples](docs/EXAMPLES.md) · [GitHub Action](docs/GITHUB_ACTION.md) · [Roadmap](docs/ROADMAP.md) · [Releases](https://github.com/kohli217/codex-workspace-bootstrap/releases)
+
+> Community-maintained project. Not an official OpenAI product and not affiliated with OpenAI.
+
+## The 20-second demo
+
+```powershell
+py -m pip install codex-workspace-bootstrap
+cwb preflight .
+```
+
+Typical output:
+
+```text
+AI Repository Preflight
+State: NEEDS ATTENTION
+Project: Python
+AI instructions: none detected
+Audit: 10 passed, 4 warnings, 0 blocking
+Instruction integrity: 0 findings, 0 drift, 0 invalid commands, 0 metadata
+Next actions:
+  [P1] Add repository instructions for AI coding agents -> cwb init-agents .
+  [P2] Make the Codex CLI available when local Codex workflows are intended -> codex --version
+```
+
+Fix the highest-value gap:
+
+```powershell
+cwb init-agents .
+cwb preflight .
+```
+
+The goal is not a vanity score. The result is one of:
+
+- **READY** — core repository signals and AI instructions are present, with no blocking finding;
+- **NEEDS ATTENTION** — usable, but important repository or AI-instruction signals are missing;
+- **BLOCKED** — a blocking finding such as a tracked secret-risk filename needs review.
+
+## What it checks
+
+### Repository readiness
+
+- Git repository
+- README
+- license
+- `.gitignore`
+- common project manifests
+- local Git / Python / Node.js / npm / PowerShell / WSL / Codex signals
+
+### AI instruction coverage
+
+The preflight detects repository instruction/config signals for:
+
+- **Codex / OpenAI agents** — `AGENTS.md`
+- **GitHub Copilot** — repository instructions
+- **Cline**
+- **Claude Code**
+- **Gemini CLI**
+- **Continue**
+- **Cursor**
+
+It does not claim these files are correct merely because they exist. It tells you what was detected so a maintainer can review the actual instructions.
+
+### Cross-agent instruction integrity
+
+When multiple AI instruction files exist, `cwb` reads executable-looking commands and checks them against repository evidence. It understands nested `AGENTS.md` / `AGENTS.override.md`, nested Cursor `.cursor/rules`, and common path-specific frontmatter such as Copilot `applyTo` and rule `globs`. It can flag:
+
+- package-manager mismatches against `packageManager` and lockfiles;
+- cross-agent package-manager drift;
+- missing `package.json` scripts referenced by instructions;
+- conflicting test/lint/build validation commands when instruction files have no shared command for the same validation family.
+
+The lint is intentionally conservative: different files may contain additional commands without being treated as conflicts when they share a compatible validation baseline. Commands from different scopes are not compared as if they were global rules. Path-specific rules are validated individually against repository evidence but are not cross-compared for drift unless their full selector semantics can be represented safely. A repository is not marked READY when it only has nested/path-specific instructions and no repository-wide instruction baseline.
+
+### Risk signals
+
+The audit warns about common secret-bearing filenames without printing their contents. When Git is available, it distinguishes **tracked**, **ignored**, and **untracked/unknown** candidates. Tracked risky filenames can become blocking findings in strict mode.
+
+This is intentionally a lightweight preflight check, not a replacement for deep scanners such as Gitleaks or Trivy.
+
+## Why this exists
+
+AI coding tools are good at editing code. They are not a substitute for repository hygiene.
+
+Before handing a repository to an agent, maintainers still need answers to questions such as:
+
+- Is this the right repository root?
+- Is the expected toolchain available?
+- Does the repository explain how to validate changes?
+- Are AI instructions present?
+- Are risky files accidentally tracked?
+- Can CI surface the same checks for every pull request?
+
+`codex-workspace-bootstrap` turns those questions into one repeatable preflight.
+
+## Short CLI
+
+The package installs both command names:
+
+```powershell
+cwb --version
+codex-workspace-bootstrap --version
+```
+
+Use `cwb` for day-to-day work.
+
+## Commands
+
+### One-command preflight
+
+```powershell
+cwb preflight .
+```
+
+Write reports for automation or review:
+
+```powershell
+cwb preflight . --json preflight.json
+cwb preflight . --markdown preflight.md
+cwb preflight . --sarif preflight.sarif
+```
+
+Use strict mode when blocking findings should return a non-zero exit code:
+
+```powershell
+cwb preflight . --strict
+```
+
+Fail CI on any instruction-integrity finding:
+
+```powershell
+cwb preflight . --fail-on-integrity
+```
+
+### Detailed audit
+
+```powershell
+cwb audit .
+cwb audit . --json audit.json
+cwb audit . --sarif audit.sarif
+cwb audit . --strict
+```
+
+### Safe fix preview
+
+```powershell
+cwb fix .
+```
+
+This is preview-only by default. To apply only low-risk supported fixes:
+
+```powershell
+cwb fix . --apply
+```
+
+Existing conflicting instruction files are never auto-rewritten. They remain human-review findings.
+
+### Non-destructive doctor
+
+```powershell
+cwb doctor .
+```
+
+`doctor` prints remediation guidance only. It does not install software or modify system configuration.
+
+### Generate `AGENTS.md`
+
+```powershell
+cwb init-agents .
+```
+
+Generation is evidence-based: the tool cross-checks project manifests, package scripts, pytest configuration, and README commands. Plausible but unconfirmed commands are separated for maintainer review. Existing `AGENTS.md` files are never overwritten unless `--force` is explicit.
+
+## GitHub Action
+
+The reusable Action is published on GitHub Marketplace.
+
+```yaml
+- uses: actions/checkout@v7
+- uses: actions/setup-python@v7
+  with:
+    python-version: "3.13"
+- uses: kohli217/codex-workspace-bootstrap@v0.5.0
+  with:
+    path: .
+    strict: "true"
+    fail_on_integrity: "true"
+```
+
+The Action adds the preflight Markdown report to the **GitHub Actions job summary**, so maintainers get a readable readiness snapshot without digging through raw logs. Optional SARIF output contains both repository-audit and instruction-integrity findings and can be uploaded to GitHub Code Scanning.
+
+See [docs/GITHUB_ACTION.md](docs/GITHUB_ACTION.md).
+
+Read-only evaluations against real public repositories are documented in [docs/PUBLIC_REPO_EVALUATIONS.md](docs/PUBLIC_REPO_EVALUATIONS.md). They are reproducible technical evaluations, not claims of third-party adoption.
+
+## Where it fits
+
+This project is a **preflight layer**, not an AI coding agent and not a deep security scanner.
+
+| Need | Use |
+| --- | --- |
+| Edit or generate code | Codex, Copilot, Cline, Claude Code, Continue, etc. |
+| Deep secret/vulnerability scanning | Gitleaks, Trivy, dedicated security tooling |
+| Reproducible toolchain management | Dev Containers, mise, project-specific tooling |
+| **Check whether a repository is ready before AI coding starts** | **codex-workspace-bootstrap** |
+
+The intent is to complement those tools, not replace them.
+
+## Safety model
+
+- Core checks run locally.
+- Suspected secret files are not opened or printed by the filename-risk check.
+- Repository contents are not sent to a remote AI service by the core audit.
+- Instruction files are read locally for deterministic linting; extracted commands are never executed by the integrity lint.
+- Existing `AGENTS.md` files are protected unless overwrite is explicit.
+- A passing preflight is evidence about the checks performed, **not a security guarantee**.
+
+See [SECURITY.md](SECURITY.md).
+
+## Maintainer workflow
+
+The project itself uses issue → branch → pull request → CI → merge → release.
+
+Automated validation includes:
+
+- Windows and Ubuntu;
+- Python 3.10 and 3.13;
+- built-wheel smoke tests;
+- Action self-tests;
+- strict self-audit;
+- CodeQL;
+- Dependabot;
+- SARIF validation;
+- PyPI publishing through GitHub OIDC Trusted Publishing.
+
+## Install
+
+PyPI:
+
+```powershell
+py -m pip install codex-workspace-bootstrap
+```
+
+Pinned GitHub release artifact:
+
+```powershell
+py -m pip install "https://github.com/kohli217/codex-workspace-bootstrap/releases/download/v0.5.0/codex_workspace_bootstrap-0.5.0-py3-none-any.whl"
+```
+
+## Development
+
+```powershell
+git clone https://github.com/kohli217/codex-workspace-bootstrap.git
+cd codex-workspace-bootstrap
+py -m venv .venv
+.\.venv\Scripts\Activate.ps1
+python -m pip install -e . pytest
+pytest -q
+```
+
+Contributions and real-world usage reports are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md), [SUPPORT.md](SUPPORT.md), [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md), and [docs/ADOPTION.md](docs/ADOPTION.md).
+
+## License
+
+MIT. See [LICENSE](LICENSE).

{codex_workspace_bootstrap-0.3.0 → codex_workspace_bootstrap-0.5.0}/pyproject.toml

@@ -4,13 +4,13 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "codex-workspace-bootstrap"
-version = "0.3.0"
-description = "Audit and bootstrap Windows repositories for effective Codex workflows."
+version = "0.5.0"
+description = "Preflight AI coding repositories before Codex, Copilot, Cline, Claude, Gemini, Continue, or Cursor touches them."
 readme = "README.md"
 requires-python = ">=3.10"
 license = { text = "MIT" }
 authors = [{ name = "kohli217" }]
-keywords = ["codex", "openai", "windows", "developer-tools", "cli", "oss", "agents-md"]
+keywords = ["ai-coding", "codex", "openai", "windows", "github-actions", "developer-tools", "cli", "agents-md"]
 classifiers = [
   "Development Status :: 3 - Alpha",
   "Environment :: Console",
@@ -34,6 +34,7 @@ Changelog = "https://github.com/kohli217/codex-workspace-bootstrap/blob/main/CHA
 
 [project.scripts]
 codex-workspace-bootstrap = "codex_workspace_bootstrap.cli:main"
+cwb = "codex_workspace_bootstrap.cli:main"
 
 [tool.setuptools.packages.find]
 where = ["src"]

{codex_workspace_bootstrap-0.3.0 → codex_workspace_bootstrap-0.5.0}/src/codex_workspace_bootstrap/__init__.py

@@ -1,3 +1,3 @@
 """codex-workspace-bootstrap package."""
 
-__version__ = "0.3.0"
+__version__ = "0.5.0"