From ccac453cdbf612f46db63257efb1e53875b2f070 Mon Sep 17 00:00:00 2001 From: Wesam Abousaid Date: Mon, 18 May 2026 20:00:51 +0200 Subject: [PATCH] =?UTF-8?q?chore(oss):=20add=20OSS=20infrastructure=20?= =?UTF-8?q?=E2=80=94=20CoC,=20security,=20contributing,=20CI?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Community and contributor support: - CONTRIBUTING.md: what we welcome, what we don't, style guide, templates for MCP walkthroughs and specialized-agent prompts. - CODE_OF_CONDUCT.md: Contributor Covenant 2.1. - SECURITY.md: scope (this is a docs repo, not application code), how to report a vulnerability in the example plugins or in misleading documentation, where OpenCode-core bugs should go instead. GitHub plumbing: - .github/PULL_REQUEST_TEMPLATE.md: type, sources, hygiene checklist. - .github/ISSUE_TEMPLATE/{bug_report,feature_request}.md and config.yml that redirects OpenCode-tool issues to the right place. - .github/workflows/lint-docs.yml: three jobs on every push and PR — markdownlint, link check (with sensible ignore patterns for ../../issues, security advisories, localhost), codespell with a project-specific ignore list. Lint/style configs: - .markdownlint.json + .markdownlintignore: ATX headings, ordered list numbering, line-length and inline-HTML rules tuned for our content. - .editorconfig: LF, UTF-8, 2-space indent, trim trailing whitespace except in markdown (where trailing spaces are line breaks). --- .editorconfig | 21 ++++++ .github/ISSUE_TEMPLATE/bug_report.md | 29 ++++++++ .github/ISSUE_TEMPLATE/config.yml | 11 +++ .github/ISSUE_TEMPLATE/feature_request.md | 25 +++++++ .github/PULL_REQUEST_TEMPLATE.md | 30 +++++++++ .github/codespell-ignore.txt | 13 ++++ .github/markdown-link-check.json | 15 +++++ .github/workflows/lint-docs.yml | 54 +++++++++++++++ .markdownlint.json | 17 +++++ .markdownlintignore | 5 ++ CODE_OF_CONDUCT.md | 39 +++++++++++ CONTRIBUTING.md | 81 +++++++++++++++++++++++ SECURITY.md | 38 +++++++++++ 13 files changed, 378 insertions(+) create mode 100644 .editorconfig create mode 100644 .github/ISSUE_TEMPLATE/bug_report.md create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/feature_request.md create mode 100644 .github/PULL_REQUEST_TEMPLATE.md create mode 100644 .github/codespell-ignore.txt create mode 100644 .github/markdown-link-check.json create mode 100644 .github/workflows/lint-docs.yml create mode 100644 .markdownlint.json create mode 100644 .markdownlintignore create mode 100644 CODE_OF_CONDUCT.md create mode 100644 CONTRIBUTING.md create mode 100644 SECURITY.md diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 0000000..ddcfd63 --- /dev/null +++ b/.editorconfig @@ -0,0 +1,21 @@ +root = true + +[*] +charset = utf-8 +end_of_line = lf +indent_size = 2 +indent_style = space +insert_final_newline = true +trim_trailing_whitespace = true + +[*.md] +trim_trailing_whitespace = false # markdown uses trailing spaces for line breaks + +[*.{json,jsonc}] +indent_size = 2 + +[*.{js,ts,mjs,cjs}] +indent_size = 2 + +[LICENSE] +insert_final_newline = false diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000..89e173b --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,29 @@ +--- +name: Documentation issue +about: Something here is wrong, outdated, or misleading +title: "[doc] " +labels: ["doc-bug"] +--- + +## What's wrong + + + +## Source for the correction + + + +## Suggested fix (optional) + + diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..21b60c6 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,11 @@ +blank_issues_enabled: false +contact_links: + - name: OpenCode itself — bugs, features, install issues + url: https://github.com/anomalyco/opencode/issues + about: This repo is a community guide. For bugs in the OpenCode tool, file there. + - name: OpenCode docs + url: https://opencode.ai/docs + about: Official documentation. + - name: OpenCode community Discord + url: https://discord.gg/opencode + about: Real-time chat with the OpenCode community. diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 0000000..87129c3 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,25 @@ +--- +name: Content request +about: Suggest a new section, walkthrough, or specialized-agent prompt +title: "[content] " +labels: ["content-request"] +--- + +## What you want covered + + + +## Why it matters + + + +## Are you willing to draft it? + +- [ ] Yes — I'll open a PR +- [ ] No — but I can review one + + diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..3cd9374 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,30 @@ +## What this changes + + + +## Type + +- [ ] Fact correction (something here is out of date or wrong) +- [ ] New content (doc, MCP walkthrough, specialized-agent prompt, etc.) +- [ ] Restructure / cleanup +- [ ] Typo / formatting / lint fix + +## Sources + + + +## Checklist + +- [ ] I read [`CONTRIBUTING.md`](../CONTRIBUTING.md) +- [ ] Every factual claim cites a source (in the PR or inline in the doc) +- [ ] In-page anchors and cross-doc links still resolve +- [ ] No trailing whitespace; code fences have language tags +- [ ] Emoji follow the [`AGENTS.md` policy](../AGENTS.md#style-conventions) (H2 navigation + callout prefixes only) +- [ ] If I touched the README, I updated the "Last reviewed" line at the bottom diff --git a/.github/codespell-ignore.txt b/.github/codespell-ignore.txt new file mode 100644 index 0000000..6f0f184 --- /dev/null +++ b/.github/codespell-ignore.txt @@ -0,0 +1,13 @@ +opencode +anomalyco +opncd +mkdir +typecheck +keybind +keybinds +keybindings +codeagent +toolset +async +codespell +markdownlint diff --git a/.github/markdown-link-check.json b/.github/markdown-link-check.json new file mode 100644 index 0000000..1c5da64 --- /dev/null +++ b/.github/markdown-link-check.json @@ -0,0 +1,15 @@ +{ + "ignorePatterns": [ + { "pattern": "^https://github.com/anomalyco/opencode/issues" }, + { "pattern": "^https://github.com/anomalyco/opencode/security/advisories" }, + { "pattern": "^https?://localhost" }, + { "pattern": "^http://server.local" }, + { "pattern": "^\\.\\./\\.\\./issues" }, + { "pattern": "^\\.\\./\\.\\./discussions" } + ], + "timeout": "15s", + "retryOn429": true, + "retryCount": 3, + "fallbackRetryDelay": "30s", + "aliveStatusCodes": [200, 206, 301, 302, 403, 429] +} diff --git a/.github/workflows/lint-docs.yml b/.github/workflows/lint-docs.yml new file mode 100644 index 0000000..49e66d0 --- /dev/null +++ b/.github/workflows/lint-docs.yml @@ -0,0 +1,54 @@ +name: Lint docs + +on: + push: + branches: [main] + pull_request: + branches: [main] + +permissions: + contents: read + +jobs: + markdownlint: + name: markdownlint + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v5 + + - name: Run markdownlint-cli2 + uses: DavidAnson/markdownlint-cli2-action@v20 + with: + globs: | + **/*.md + !node_modules + + link-check: + name: Link check + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v5 + + - name: Markdown link check + uses: gaurav-nelson/github-action-markdown-link-check@v1 + with: + use-quiet-mode: "yes" + use-verbose-mode: "yes" + config-file: ".github/markdown-link-check.json" + # Only changed files on PR; everything on push + check-modified-files-only: ${{ github.event_name == 'pull_request' && 'yes' || 'no' }} + base-branch: main + + spellcheck: + name: Spell check + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v5 + + - name: codespell + uses: codespell-project/actions-codespell@v2 + with: + # Tune by adding words to .github/codespell-ignore.txt + ignore_words_file: .github/codespell-ignore.txt + # Skip files we don't author + skip: ./LICENSE,./.git,./node_modules diff --git a/.markdownlint.json b/.markdownlint.json new file mode 100644 index 0000000..195c33b --- /dev/null +++ b/.markdownlint.json @@ -0,0 +1,17 @@ +{ + "default": true, + "MD003": { "style": "atx" }, + "MD007": { "indent": 2 }, + "MD013": false, + "MD024": { "siblings_only": true }, + "MD025": { "front_matter_title": "" }, + "MD026": { "punctuation": ".,;:" }, + "MD029": { "style": "ordered" }, + "MD033": false, + "MD036": false, + "MD040": false, + "MD041": false, + "MD046": { "style": "fenced" }, + "MD049": { "style": "asterisk" }, + "MD050": { "style": "asterisk" } +} diff --git a/.markdownlintignore b/.markdownlintignore new file mode 100644 index 0000000..96d1be9 --- /dev/null +++ b/.markdownlintignore @@ -0,0 +1,5 @@ +node_modules/ +.opencode/cache/ +.opencode/logs/ +.opencode/sessions/ +.opencode/audit.jsonl diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..ea86417 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,39 @@ +# Code of Conduct + +## Our pledge + +We — maintainers and contributors — pledge to make participation in this project a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation. + +We commit to acting in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community. + +## Our standards + +**Examples of behavior that contributes to a positive environment:** + +- Demonstrating empathy and kindness toward other people +- Being respectful of differing opinions, viewpoints, and experiences +- Giving and gracefully accepting constructive feedback +- Accepting responsibility, apologizing to those affected by mistakes, and learning from the experience +- Focusing on what is best for the overall community + +**Examples of unacceptable behavior:** + +- The use of sexualized language or imagery, and unwelcome sexual attention or advances +- Trolling, insulting or derogatory comments, and personal or political attacks +- Public or private harassment +- Publishing others' private information (physical or email address) without explicit permission +- Other conduct which could reasonably be considered inappropriate in a professional setting + +## Scope + +This Code of Conduct applies within all project spaces — issues, pull requests, discussions, commit comments, and any community channels associated with the project — and also applies when an individual is officially representing the project in public spaces. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the maintainers by opening a confidential issue or contacting the repository owner directly. All complaints will be reviewed and investigated promptly and fairly. + +Maintainers are obligated to respect the privacy and security of the reporter of any incident. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant, version 2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct.html). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..b574014 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,81 @@ +# Contributing + +Thank you for considering a contribution. This repo is a community-maintained guide to [OpenCode](https://opencode.ai) — every typo fix, fact correction, and new example helps the next reader. + +## What we welcome + +| Contribution | What's helpful | +|---|---| +| **Fact corrections** | OpenCode moves fast. If something here is out of date, fix it and cite the source. | +| **New MCP walkthroughs** | A short page in [`mcp-servers/`](mcp-servers/) with verified setup steps, example prompts, and gotchas. | +| **New specialized-agent prompts** | A new role under [`specialized-agents/system-prompts/`](specialized-agents/system-prompts/) + a one-page description. | +| **Better examples** | Real-world patterns that worked for you. | +| **Typo and grammar fixes** | Just send the PR. | +| **Image / diagram contributions** | Drop PNG/SVG in [`Images/`](Images/) and reference them inline. | + +## What we don't accept + +- **Unverified claims.** Every factual statement must trace back to [opencode.ai/docs](https://opencode.ai/docs/), the [OpenCode GitHub repo](https://github.com/anomalyco/opencode), or a primary source. No "I heard that…". +- **Marketing language.** This guide is practical, not a sales pitch. +- **Affiliate links or sponsored content** without prior agreement. +- **AI-generated content that hasn't been read and verified by you.** If you used an AI to draft, that's fine — but read it carefully, fact-check, and remove fluff before submitting. + +## How to contribute + +1. **Open an issue first** for non-trivial changes (new sections, restructuring) so we can align on scope. +2. **Fork → branch → PR.** One topic per PR; smaller is better. +3. **Match the existing style.** See [AGENTS.md](AGENTS.md) for style conventions (markdown, tone, link form). +4. **Cite your sources.** If you're updating a fact, include a link to the source in the PR description. +5. **Update the "Last reviewed" date** at the bottom of the README if you've made material changes. + +## Style basics + +- Short lines, plain English. +- Lead with the mental model, then the syntax, then the example. +- Comparison tables when there's a choice to make. +- Code fences with language tags. JSON examples should be valid `opencode.json` snippets. +- Emoji callouts: `> 💡 Pro Tip`, `> ⚠️ Warning`, `> 🆕 New`, `> 📚 Further reading`. + +## Tips for adding a new MCP walkthrough + +A good walkthrough has: + +1. **When to reach for it** — one-line use case +2. **Setup** — exact JSON snippet for `opencode.json` and any auth steps +3. **Example prompts** — 2–3 realistic prompts (not "hello world") +4. **What it can do / won't do** — set expectations +5. **Gotchas** — things you wish you'd known +6. **Resources** — links to the upstream project + +See [`mcp-servers/playwright.md`](mcp-servers/playwright.md) as a template. + +## Tips for adding a new specialized-agent prompt + +A good system prompt has: + +1. **Frontmatter** with `description`, `mode`, `model`, `temperature`, `permission` — use the format in [`docs/agents.md`](docs/agents.md). +2. **Principles** — 3–5 numbered, prescriptive items. What the agent prioritizes. +3. **Workflow** — concrete steps the agent should follow. +4. **Defaults** — the stack and tools the agent uses. +5. **What I won't do** — explicit constraints. This is what makes specialized agents different from a generic LLM. +6. **Communication style** — how the agent talks (terse, surfaces trade-offs, etc.). + +Add the matching short description under [`specialized-agents/descriptions/`](specialized-agents/descriptions/) and update the table in [`specialized-agents/README.md`](specialized-agents/README.md). + +## Local check + +There's no build system to run, but a quick mental checklist before submitting: + +- [ ] All links resolve (in-page anchors and external URLs) +- [ ] Code fences have language tags +- [ ] No trailing whitespace +- [ ] No emoji clutter +- [ ] Facts cite a source + +## Questions + +Open a [GitHub Discussion](../../discussions) or an [issue](../../issues). Drive-by PRs are welcome too — we'll suggest changes in review. + +--- + +*Thanks for making this resource better.* diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..655b79a --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,38 @@ +# Security Policy + +## Scope + +This repository is a **documentation guide**, not application code. It ships: + +- Markdown documentation +- Two example JS plugins ([`.opencode/plugins/`](.opencode/plugins/)) +- Example agent / command / skill files + +The plugins are simple and self-contained, but because they're meant to run inside a user's OpenCode session, security still matters. + +## Reporting a vulnerability + +If you find a security issue in: + +| Where | Report to | +|---|---| +| **OpenCode itself** (the tool) | Open a [security advisory on `anomalyco/opencode`](https://github.com/anomalyco/opencode/security/advisories/new) | +| **The example plugins in this repo** | Open a confidential issue or contact the maintainer directly via GitHub | +| **A factual error in documentation** that could mislead a user into a vulnerable configuration | Open a normal issue or PR | + +Please **don't** disclose security issues publicly until they've been addressed. We'll acknowledge receipt within 7 days and aim to resolve within 30. + +## What counts as a vulnerability here + +- An example plugin that doesn't do what its docstring claims (e.g. fails to block a sensitive path it says it blocks). +- A doc example that demonstrates an insecure configuration without warning. +- A copy-pasteable command in the docs that exfiltrates data, executes arbitrary code unexpectedly, or weakens the user's setup. + +## What doesn't count + +- OpenCode core bugs — those belong to [`anomalyco/opencode`](https://github.com/anomalyco/opencode/issues). +- General "plugins can run arbitrary code" concerns — this is documented behavior of the plugin system itself. + +## Supply-chain notes + +This repo has **no runtime dependencies** and **no build step**. The two example plugins use only Node built-ins (`node:fs/promises`, `node:path`).