codex-workspace-bootstrap 0.7.0__tar.gz → 0.9.0__tar.gz

{codex_workspace_bootstrap-0.7.0/src/codex_workspace_bootstrap.egg-info → codex_workspace_bootstrap-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codex-workspace-bootstrap
-Version: 0.7.0
+Version: 0.9.0
 Summary: Preflight AI coding repositories before Codex, Copilot, Cline, Claude, Gemini, Continue, or Cursor touches them.
 Author: kohli217
 License: MIT
@@ -40,10 +40,23 @@ Dynamic: license-file
 
 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)
+[日本語ガイド](docs/README.ja.md) · [Examples](docs/EXAMPLES.md) · [GitHub Action](docs/GITHUB_ACTION.md) · [GitHub App](docs/GITHUB_APP.md) · [Free GitHub App deployment](deploy/cloudflare/README.md) · [Cloud Run alternative](deploy/cloudrun/README.md) · [Integration contract](docs/INTEGRATIONS.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.
 
+## Why add this to your repository?
+
+AI coding agents can move fast, but they can also follow stale or conflicting repository instructions. `codex-workspace-bootstrap` adds one repeatable check before that happens.
+
+| Common failure | What `cwb` does |
+| --- | --- |
+| One instruction says `npm`, another says `pnpm` | Flags the mismatch before an agent edits the repository. |
+| An instruction tells the agent to run a test/lint script that does not exist | Reports the invalid command instead of letting the mistake reach the agent. |
+| A risky file such as `.env.production` is Git-tracked | Surfaces it as a blocking risk signal without printing its contents. |
+| The repository is still missing important readiness pieces | `cwb preflight . --require-ready` can fail CI until the repository reaches `READY`. |
+
+It is local-first: the core preflight does not send repository contents to a remote AI service.
+
 ## The 20-second demo
 
 ```powershell
@@ -219,6 +232,14 @@ cwb preflight . --require-ready
 
 Use `--require-ready` when CI should reject both `NEEDS ATTENTION` and `BLOCKED`, including missing repository-wide AI instructions or essential repository markers.
 
+For a remote service such as a GitHub App, skip host-machine tool availability checks while keeping repository evidence, Git tracking, risk filenames, and instruction integrity checks:
+
+```powershell
+cwb preflight . --repository-only
+```
+
+This prevents a remote scanner from reporting the scanner host's Node.js, package-manager, WSL, PowerShell, or Codex availability as if it belonged to the inspected repository.
+
 ### Detailed audit
 
 ```powershell
@@ -267,7 +288,7 @@ The reusable Action is published on GitHub Marketplace.
 - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97
   with:
     python-version: "3.13"
-- uses: kohli217/codex-workspace-bootstrap@v0.7.0
+- uses: kohli217/codex-workspace-bootstrap@v0.9.0
   with:
     path: .
     strict: "true"
@@ -281,6 +302,36 @@ 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.
 
+## GitHub App
+
+**Public App:** [CWB Preflight](https://github.com/apps/cwb-preflight) · [Install](https://github.com/apps/cwb-preflight/installations/new)
+
+For public OSS repositories, CWB can also run as a self-hosted GitHub App. A verified `push` or `pull_request` event triggers repository-only preflight against the exact event revision and publishes a **CWB Preflight** Check Run on that commit.
+
+The verified zero-cost public-OSS deployment uses:
+
+```text
+GitHub App
+  -> Cloudflare Worker + Queue (Free)
+  -> GitHub Actions in this public repository
+  -> short-lived repository-scoped installation token
+  -> CWB Preflight Check
+```
+
+This path does not require a Google Cloud billing account. It is intentionally **public-repository-only**: private-repository events are rejected before they are queued into the public Actions worker.
+
+The App keeps the minimum repository permissions documented by the project: Checks read/write, Contents read-only, and Pull requests read-only.
+
+The current public App has been revalidated after promotion: the renamed `CWB Preflight` App produced a successful `READY` Check Run through the full Cloudflare → Queue → GitHub Actions → installation-token → exact-revision checkout path.
+
+See [docs/GITHUB_APP.md](docs/GITHUB_APP.md) for the integration contract and [deploy/cloudflare/README.md](deploy/cloudflare/README.md) for the completely free deployment.
+
+## Integration boundary
+
+The CLI, reusable GitHub Action, GitHub App, and future AI-agent skills share one preflight engine and one policy evaluator. Machine-readable reports declare a schema version so integrations can detect incompatible changes instead of silently drifting.
+
+See [docs/INTEGRATIONS.md](docs/INTEGRATIONS.md). The minimum GitHub App permissions and webhook subscriptions are defined in [docs/GITHUB_APP.md](docs/GITHUB_APP.md) and mirrored by code-level regression tests.
+
 ## Where it fits
 
 This project is a **preflight layer**, not an AI coding agent and not a deep security scanner.
@@ -300,7 +351,7 @@ The intent is to complement those tools, not replace them.
 - 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.
-- Repository instruction/configuration and project-marker inputs are not trusted through symbolic links.
+- Repository instruction/configuration and project-marker contents are not trusted through symbolic links. CWB may recognize the exact lexical aliases `CLAUDE.md -> AGENTS.md` and `GEMINI.md -> AGENTS.md` (or `./AGENTS.md`) only when the sibling `AGENTS.md` is a regular file; linting reads that regular file directly rather than following either link. Gemini aliases are recognized only when `GEMINI.md` is an effective Gemini context filename.
 - `init-agents` and automatic fixes refuse symlinked `AGENTS.md` targets rather than writing through them.
 - Existing regular `AGENTS.md` files are protected unless overwrite is explicit.
 - A passing preflight is evidence about the checks performed, **not a security guarantee**.
@@ -334,7 +385,7 @@ 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.7.0/codex_workspace_bootstrap-0.7.0-py3-none-any.whl"
+py -m pip install "https://github.com/kohli217/codex-workspace-bootstrap/releases/download/v0.9.0/codex_workspace_bootstrap-0.9.0-py3-none-any.whl"
 ```
 
 ## Development

{codex_workspace_bootstrap-0.7.0 → codex_workspace_bootstrap-0.9.0}/README.md

@@ -12,10 +12,23 @@
 
 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)
+[日本語ガイド](docs/README.ja.md) · [Examples](docs/EXAMPLES.md) · [GitHub Action](docs/GITHUB_ACTION.md) · [GitHub App](docs/GITHUB_APP.md) · [Free GitHub App deployment](deploy/cloudflare/README.md) · [Cloud Run alternative](deploy/cloudrun/README.md) · [Integration contract](docs/INTEGRATIONS.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.
 
+## Why add this to your repository?
+
+AI coding agents can move fast, but they can also follow stale or conflicting repository instructions. `codex-workspace-bootstrap` adds one repeatable check before that happens.
+
+| Common failure | What `cwb` does |
+| --- | --- |
+| One instruction says `npm`, another says `pnpm` | Flags the mismatch before an agent edits the repository. |
+| An instruction tells the agent to run a test/lint script that does not exist | Reports the invalid command instead of letting the mistake reach the agent. |
+| A risky file such as `.env.production` is Git-tracked | Surfaces it as a blocking risk signal without printing its contents. |
+| The repository is still missing important readiness pieces | `cwb preflight . --require-ready` can fail CI until the repository reaches `READY`. |
+
+It is local-first: the core preflight does not send repository contents to a remote AI service.
+
 ## The 20-second demo
 
 ```powershell
@@ -191,6 +204,14 @@ cwb preflight . --require-ready
 
 Use `--require-ready` when CI should reject both `NEEDS ATTENTION` and `BLOCKED`, including missing repository-wide AI instructions or essential repository markers.
 
+For a remote service such as a GitHub App, skip host-machine tool availability checks while keeping repository evidence, Git tracking, risk filenames, and instruction integrity checks:
+
+```powershell
+cwb preflight . --repository-only
+```
+
+This prevents a remote scanner from reporting the scanner host's Node.js, package-manager, WSL, PowerShell, or Codex availability as if it belonged to the inspected repository.
+
 ### Detailed audit
 
 ```powershell
@@ -239,7 +260,7 @@ The reusable Action is published on GitHub Marketplace.
 - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97
   with:
     python-version: "3.13"
-- uses: kohli217/codex-workspace-bootstrap@v0.7.0
+- uses: kohli217/codex-workspace-bootstrap@v0.9.0
   with:
     path: .
     strict: "true"
@@ -253,6 +274,36 @@ 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.
 
+## GitHub App
+
+**Public App:** [CWB Preflight](https://github.com/apps/cwb-preflight) · [Install](https://github.com/apps/cwb-preflight/installations/new)
+
+For public OSS repositories, CWB can also run as a self-hosted GitHub App. A verified `push` or `pull_request` event triggers repository-only preflight against the exact event revision and publishes a **CWB Preflight** Check Run on that commit.
+
+The verified zero-cost public-OSS deployment uses:
+
+```text
+GitHub App
+  -> Cloudflare Worker + Queue (Free)
+  -> GitHub Actions in this public repository
+  -> short-lived repository-scoped installation token
+  -> CWB Preflight Check
+```
+
+This path does not require a Google Cloud billing account. It is intentionally **public-repository-only**: private-repository events are rejected before they are queued into the public Actions worker.
+
+The App keeps the minimum repository permissions documented by the project: Checks read/write, Contents read-only, and Pull requests read-only.
+
+The current public App has been revalidated after promotion: the renamed `CWB Preflight` App produced a successful `READY` Check Run through the full Cloudflare → Queue → GitHub Actions → installation-token → exact-revision checkout path.
+
+See [docs/GITHUB_APP.md](docs/GITHUB_APP.md) for the integration contract and [deploy/cloudflare/README.md](deploy/cloudflare/README.md) for the completely free deployment.
+
+## Integration boundary
+
+The CLI, reusable GitHub Action, GitHub App, and future AI-agent skills share one preflight engine and one policy evaluator. Machine-readable reports declare a schema version so integrations can detect incompatible changes instead of silently drifting.
+
+See [docs/INTEGRATIONS.md](docs/INTEGRATIONS.md). The minimum GitHub App permissions and webhook subscriptions are defined in [docs/GITHUB_APP.md](docs/GITHUB_APP.md) and mirrored by code-level regression tests.
+
 ## Where it fits
 
 This project is a **preflight layer**, not an AI coding agent and not a deep security scanner.
@@ -272,7 +323,7 @@ The intent is to complement those tools, not replace them.
 - 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.
-- Repository instruction/configuration and project-marker inputs are not trusted through symbolic links.
+- Repository instruction/configuration and project-marker contents are not trusted through symbolic links. CWB may recognize the exact lexical aliases `CLAUDE.md -> AGENTS.md` and `GEMINI.md -> AGENTS.md` (or `./AGENTS.md`) only when the sibling `AGENTS.md` is a regular file; linting reads that regular file directly rather than following either link. Gemini aliases are recognized only when `GEMINI.md` is an effective Gemini context filename.
 - `init-agents` and automatic fixes refuse symlinked `AGENTS.md` targets rather than writing through them.
 - Existing regular `AGENTS.md` files are protected unless overwrite is explicit.
 - A passing preflight is evidence about the checks performed, **not a security guarantee**.
@@ -306,7 +357,7 @@ 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.7.0/codex_workspace_bootstrap-0.7.0-py3-none-any.whl"
+py -m pip install "https://github.com/kohli217/codex-workspace-bootstrap/releases/download/v0.9.0/codex_workspace_bootstrap-0.9.0-py3-none-any.whl"
 ```
 
 ## Development

{codex_workspace_bootstrap-0.7.0 → codex_workspace_bootstrap-0.9.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "codex-workspace-bootstrap"
-version = "0.7.0"
+version = "0.9.0"
 description = "Preflight AI coding repositories before Codex, Copilot, Cline, Claude, Gemini, Continue, or Cursor touches them."
 readme = "README.md"
 requires-python = ">=3.10"

{codex_workspace_bootstrap-0.7.0 → codex_workspace_bootstrap-0.9.0}/src/codex_workspace_bootstrap/__init__.py

@@ -1,3 +1,3 @@
 """codex-workspace-bootstrap package."""
 
-__version__ = "0.7.0"
+__version__ = "0.9.0"

{codex_workspace_bootstrap-0.7.0 → codex_workspace_bootstrap-0.9.0}/src/codex_workspace_bootstrap/audit.py

@@ -194,7 +194,7 @@ def _preview(paths: list[str], limit: int = 8) -> str:
     return f"{visible}{suffix}"
 
 
-def audit_repository(root: Path) -> list[Check]:
+def audit_repository(root: Path, *, include_local_toolchain: bool = True) -> list[Check]:
     root = root.resolve()
     checks: list[Check] = []
 
@@ -285,8 +285,9 @@ def audit_repository(root: Path) -> list[Check]:
         )
     )
 
-    for label, command in COMMON_TOOLS:
-        checks.append(_tool_check(label, command))
+    if include_local_toolchain:
+        for label, command in COMMON_TOOLS:
+            checks.append(_tool_check(label, command))
 
     if (root / "package.json").is_file() and not (root / "package.json").is_symlink():
         managers = detect_node_package_managers(root)
@@ -300,9 +301,10 @@ def audit_repository(root: Path) -> list[Check]:
                         + ", ".join(sorted(managers)),
                     )
                 )
-            for manager in sorted(managers):
-                command = NODE_PACKAGE_MANAGER_COMMANDS[manager]
-                checks.append(_tool_check(manager, command))
+            if include_local_toolchain:
+                for manager in sorted(managers):
+                    command = NODE_PACKAGE_MANAGER_COMMANDS[manager]
+                    checks.append(_tool_check(manager, command))
         else:
             checks.append(
                 Check(

{codex_workspace_bootstrap-0.7.0 → codex_workspace_bootstrap-0.9.0}/src/codex_workspace_bootstrap/cli.py

@@ -10,7 +10,7 @@ from .agents import generate_agents
 from .audit import audit_repository, summary
 from .doctor import doctor_findings
 from .fixes import apply_fix_plan, build_fix_plan
-from .preflight import build_preflight, render_markdown
+from .preflight import build_preflight, evaluate_preflight_policy, render_markdown
 from .sarif import checks_to_sarif, preflight_report_to_sarif
 
 
@@ -46,6 +46,11 @@ def _parser() -> argparse.ArgumentParser:
         action="store_true",
         help="Return a non-zero exit code unless the preflight state is READY",
     )
+    preflight.add_argument(
+        "--repository-only",
+        action="store_true",
+        help="Skip local toolchain availability checks and evaluate repository evidence only",
+    )
 
     fix = sub.add_parser("fix", help="Preview safe repository-readiness fixes")
     fix.add_argument("path", nargs="?", default=".")
@@ -91,13 +96,17 @@ def _run_preflight(
     strict: bool,
     fail_on_integrity: bool,
     require_ready: bool,
+    repository_only: bool,
 ) -> int:
     root = Path(path).expanduser().resolve()
     if not root.exists() or not root.is_dir():
         print(f"error: repository path does not exist or is not a directory: {root}", file=sys.stderr)
         return 2
 
-    report = build_preflight(root)
+    report = build_preflight(
+        root,
+        include_local_toolchain=not repository_only,
+    )
 
     print("AI Repository Preflight")
     print(f"Repository: {root}")
@@ -163,13 +172,13 @@ def _run_preflight(
             "Preflight SARIF report",
         )
 
-    if strict and report["state"] == "BLOCKED":
-        return 1
-    if fail_on_integrity and report["instruction_summary"]["findings"]:
-        return 1
-    if require_ready and report["state"] != "READY":
-        return 1
-    return 0
+    decision = evaluate_preflight_policy(
+        report,
+        strict=strict,
+        fail_on_integrity=fail_on_integrity,
+        require_ready=require_ready,
+    )
+    return 0 if decision.passed else 1
 
 
 def _run_fix(path: str, apply: bool) -> int:
@@ -301,6 +310,7 @@ def main(argv: list[str] | None = None) -> int:
             args.strict,
             args.fail_on_integrity,
             args.require_ready,
+            args.repository_only,
         )
     if args.command == "fix":
         return _run_fix(args.path, args.apply)