From 2db0a5f70d3e6122703b2817774ce60a2a8368ff Mon Sep 17 00:00:00 2001 From: bellman Date: Fri, 15 May 2026 10:43:35 +0900 Subject: [PATCH] omx(team): auto-checkpoint worker-4 [unknown] --- .github/scripts/check_release_readiness.py | 169 +++++++++++++++++++++ CODE_OF_CONDUCT.md | 32 ++++ CONTRIBUTING.md | 66 ++++++++ LICENSE | 21 +++ SECURITY.md | 49 ++++++ SUPPORT.md | 24 +++ 6 files changed, 361 insertions(+) create mode 100644 .github/scripts/check_release_readiness.py create mode 100644 CODE_OF_CONDUCT.md create mode 100644 CONTRIBUTING.md create mode 100644 LICENSE create mode 100644 SECURITY.md create mode 100644 SUPPORT.md diff --git a/.github/scripts/check_release_readiness.py b/.github/scripts/check_release_readiness.py new file mode 100644 index 00000000..d356abb2 --- /dev/null +++ b/.github/scripts/check_release_readiness.py @@ -0,0 +1,169 @@ +#!/usr/bin/env python3 +"""Validate release-readiness docs that are easy to regress. + +The check is intentionally dependency-free so it can run on developer machines, +Windows CI, and minimal release jobs. It validates: + +* required repository policy files exist; +* local Markdown links and image targets resolve; +* local heading anchors referenced from Markdown resolve; and +* command examples do not present the deprecated `cargo install claw-code` + package as an executable install path. +""" + +from __future__ import annotations + +from pathlib import Path +from urllib.parse import unquote, urlparse +import re +import sys + +ROOT = Path(__file__).resolve().parents[2] + +REQUIRED_POLICY_FILES = [ + "LICENSE", + "CONTRIBUTING.md", + "SECURITY.md", + "SUPPORT.md", + "CODE_OF_CONDUCT.md", +] + +MARKDOWN_ROOTS = [ + ROOT / "README.md", + ROOT / "USAGE.md", + ROOT / "PARITY.md", + ROOT / "PHILOSOPHY.md", + ROOT / "ROADMAP.md", + ROOT / "CONTRIBUTING.md", + ROOT / "SECURITY.md", + ROOT / "SUPPORT.md", + ROOT / "CODE_OF_CONDUCT.md", + ROOT / "docs", + ROOT / "rust" / "README.md", + ROOT / "rust" / "USAGE.md", + ROOT / "rust" / "MOCK_PARITY_HARNESS.md", +] + +LINK_PATTERN = re.compile(r"(?]*(?:href|src)=["']([^"']+)["']""", re.I) +FENCE_PATTERN = re.compile(r"```(?P[^\n`]*)\n(?P.*?)```", re.S) + + +def iter_markdown_files() -> list[Path]: + files: set[Path] = set() + for entry in MARKDOWN_ROOTS: + if entry.is_file(): + files.add(entry) + elif entry.is_dir(): + files.update(entry.rglob("*.md")) + return sorted(files) + + +def github_anchor(heading: str) -> str: + anchor = heading.strip().lower() + anchor = re.sub(r"<[^>]+>", "", anchor) + anchor = re.sub(r"`([^`]*)`", r"\1", anchor) + anchor = re.sub(r"[^a-z0-9 _-]", "", anchor) + anchor = anchor.replace(" ", "-") + anchor = re.sub(r"-+", "-", anchor) + return anchor.strip("-") + + +def anchors_for(path: Path) -> set[str]: + anchors: set[str] = set() + for line in path.read_text(encoding="utf-8").splitlines(): + match = re.match(r"^(#{1,6})\s+(.+?)\s*#*\s*$", line) + if match: + anchors.add(github_anchor(match.group(2))) + return anchors + + +def is_external(target: str) -> bool: + parsed = urlparse(target) + return parsed.scheme in {"http", "https", "mailto"} + + +def validate_policies(errors: list[str]) -> None: + for relative in REQUIRED_POLICY_FILES: + path = ROOT / relative + if not path.is_file(): + errors.append(f"missing required policy file: {relative}") + + +def validate_markdown_links(errors: list[str]) -> None: + anchor_cache: dict[Path, set[str]] = {} + for path in iter_markdown_files(): + text = path.read_text(encoding="utf-8") + candidates = [m.group(1) for m in LINK_PATTERN.finditer(text)] + candidates.extend(m.group(1) for m in HTML_LINK_PATTERN.finditer(text)) + for target in candidates: + if ( + not target + or is_external(target) + or target.startswith(("mailto:", "tel:", "data:")) + ): + continue + link_path, _, raw_anchor = target.partition("#") + if not link_path: + destination = path + else: + destination = (path.parent / unquote(link_path)).resolve() + try: + destination.relative_to(ROOT) + except ValueError: + errors.append( + f"{path.relative_to(ROOT)}: link escapes repo root: {target}" + ) + continue + if not destination.exists(): + errors.append( + f"{path.relative_to(ROOT)}: missing local link target: {target}" + ) + continue + if raw_anchor and destination.suffix.lower() == ".md": + anchor = unquote(raw_anchor).lower() + anchor_cache.setdefault(destination, anchors_for(destination)) + if anchor not in anchor_cache[destination]: + errors.append( + f"{path.relative_to(ROOT)}: missing anchor `{raw_anchor}` in " + f"{destination.relative_to(ROOT)}" + ) + + +def validate_command_examples(errors: list[str]) -> None: + for path in iter_markdown_files(): + text = path.read_text(encoding="utf-8") + for match in FENCE_PATTERN.finditer(text): + lang = match.group("lang").strip().lower() + if lang not in {"bash", "sh", "shell", "zsh", "powershell", "ps1"}: + continue + body = match.group("body") + for offset, line in enumerate(body.splitlines(), start=1): + stripped = line.strip() + if not stripped or stripped.startswith(("#", ">")): + continue + if re.search(r"\bcargo\s+install\s+claw-code\b", stripped): + line_no = text.count("\n", 0, match.start()) + offset + 1 + errors.append( + f"{path.relative_to(ROOT)}:{line_no}: deprecated " + "`cargo install claw-code` appears in an executable " + "command block; use build-from-source docs instead" + ) + + +def main() -> int: + errors: list[str] = [] + validate_policies(errors) + validate_markdown_links(errors) + validate_command_examples(errors) + if errors: + print("release-readiness check failed:", file=sys.stderr) + for error in errors: + print(f" - {error}", file=sys.stderr) + return 1 + print("release-readiness check passed") + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 00000000..f9b4e0f9 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,32 @@ +# Code of Conduct + +## Our pledge + +We aim to make Claw Code a practical, respectful, and evidence-oriented +community. Contributors and maintainers are expected to communicate with +patience, assume good intent, and focus critique on the work rather than the +person. + +## Expected behavior + +- Be respectful and direct. +- Welcome newcomers and explain project-specific context when it matters. +- Give actionable feedback with evidence, commands, logs, or links. +- Respect privacy and do not pressure others to disclose credentials, private + prompts, employer information, or personal details. + +## Unacceptable behavior + +- Harassment, threats, insults, or discriminatory language. +- Publishing another person's private information without permission. +- Sharing secrets, exploit payloads, or private vulnerability details in public + channels. +- Repeated off-topic disruption after maintainers ask for a thread to stop or + move. + +## Enforcement + +Maintainers may remove comments, close threads, restrict participation, or ban +accounts that violate this code of conduct. Report concerns through the support +or security paths described in [SUPPORT.md](./SUPPORT.md) and +[SECURITY.md](./SECURITY.md). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..92c629ae --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,66 @@ +# Contributing to Claw Code + +Thanks for helping improve Claw Code. This repository is a Rust-first CLI +workspace with supporting docs and compatibility fixtures. + +## Ground rules + +- Keep changes small, reviewable, and tied to a concrete issue or behavior. +- Do not commit secrets, API keys, session transcripts with credentials, or + generated build output. +- Prefer existing crate boundaries and utilities before adding dependencies. +- Update documentation when a user-facing command, config key, or provider + behavior changes. +- Keep examples copy/paste safe. Use placeholder keys such as `sk-ant-...` and + avoid commands that require live credentials unless the text explicitly says + so. + +## Local setup + +```bash +git clone https://github.com/ultraworkers/claw-code +cd claw-code/rust +cargo build --workspace +cargo test --workspace +``` + +On Windows PowerShell, build from the same `rust` workspace and run the binary +with the `.exe` suffix: + +```powershell +cd claw-code\rust +cargo build --workspace +.\target\debug\claw.exe --help +``` + +## Checks before opening a pull request + +Run the smallest relevant tests for your change, then the broader checks when +you touch shared runtime, CLI, or docs surfaces: + +```bash +cd rust +cargo fmt --all --check +cargo test --workspace +cargo clippy --workspace +``` + +For documentation and release-readiness changes, also run: + +```bash +python .github/scripts/check_doc_source_of_truth.py +python .github/scripts/check_release_readiness.py +``` + +## Pull request guidance + +- Describe the user-visible reason for the change. +- List the commands you ran and any known gaps. +- Call out compatibility risks for CLI output, JSON schemas, plugin contracts, + provider behavior, or Windows/PowerShell examples. +- Keep unrelated cleanup out of feature or fix pull requests. + +## License + +By contributing, you agree that your contributions are licensed under the +project's [MIT License](./LICENSE). diff --git a/LICENSE b/LICENSE new file mode 100644 index 00000000..28e6960d --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 UltraWorkers and Claw Code contributors + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 00000000..282f6887 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,49 @@ +# Security Policy + +## Supported versions + +Security fixes target the current `main` branch and the latest published +release artifacts when available. Older experimental branches are not supported +unless a maintainer explicitly marks them as supported. + +## Reporting a vulnerability + +Please do **not** open a public issue for a suspected vulnerability. Use GitHub +private vulnerability reporting for `ultraworkers/claw-code` when available, or +contact a maintainer through the repository's published support channel with a +minimal, non-destructive reproduction. + +Include: + +- affected command, crate, or workflow; +- operating system and shell, especially for Windows/PowerShell path issues; +- whether live credentials, MCP servers, plugins, or workspace filesystem + access are involved; +- expected impact and any safe proof-of-concept steps. + +Do not include real API keys, private prompts, session transcripts with secrets, +or exploit payloads that modify third-party systems. + +## Scope + +In scope: + +- workspace path traversal or symlink escapes; +- permission bypasses, sandbox misreporting, or unsafe tool execution; +- credential disclosure in logs, JSON output, telemetry, docs, or examples; +- plugin, hook, MCP, provider, or config behavior that can unexpectedly execute + code or leak secrets. + +Out of scope: + +- social engineering; +- denial-of-service without a practical security impact; +- issues that require already-compromised local developer credentials; +- reports against third-party providers or upstream tools without a Claw Code + integration issue. + +## Handling expectations + +Maintainers will acknowledge valid private reports as soon as practical, keep +discussion private until a fix or mitigation is available, and credit reporters +when requested and appropriate. diff --git a/SUPPORT.md b/SUPPORT.md new file mode 100644 index 00000000..617eea0d --- /dev/null +++ b/SUPPORT.md @@ -0,0 +1,24 @@ +# Support + +Use the lightest support path that fits the request: + +- **Usage questions:** start with [USAGE.md](./USAGE.md) and + [rust/README.md](./rust/README.md). +- **Bugs or regressions:** open a GitHub issue with the command, OS/shell, + expected behavior, actual behavior, and relevant non-secret output. +- **Security issues:** follow [SECURITY.md](./SECURITY.md) instead of opening a + public issue. +- **Community discussion:** use the UltraWorkers Discord linked from + [README.md](./README.md). + +When asking for help, include: + +```text +claw --version +claw doctor +operating system and shell +command you ran +``` + +Redact API keys, bearer tokens, private prompts, session transcripts, and local +paths that reveal sensitive information before sharing output.