From 894d19308fee6b06ec4c7010d39e207c0454821c Mon Sep 17 00:00:00 2001 From: Patrick Lewis <4015312+locus313@users.noreply.github.com> Date: Fri, 31 Jul 2026 12:09:56 -0700 Subject: [PATCH 1/2] Make repo AI-ready: AGENTS.md, CI, templates, changelog MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add AGENTS.md with project overview, structure, conventions, and common pitfalls for AI coding agents. - Add Maintenance Matrix to .github/copilot-instructions.md mapping script changes to required companion updates. - Add .github/workflows/ci.yml (shellcheck on all .sh files) — this repo previously had no CI at all. - Add .github/workflows/copilot-setup-steps.yml to pre-install shellcheck for the Copilot cloud coding agent. - Add bug report / feature request issue forms and a PR template derived from the maintenance matrix checklist. - Add CHANGELOG.md (Keep a Changelog format) seeded from PR history. - Vendor the johnpapa/ai-ready skill into .github/skills/ai-ready/. Assisted by ai-ready v1.2.0 (https://github.com/johnpapa/ai-ready) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .github/ISSUE_TEMPLATE/bug_report.yml | 34 +++ .github/ISSUE_TEMPLATE/feature_request.yml | 20 ++ .github/PULL_REQUEST_TEMPLATE.md | 20 ++ .github/copilot-instructions.md | 12 + .github/skills/ai-ready/SKILL.md | 246 ++++++++++++++++++ .../ai-ready/references/detection-tables.md | 137 ++++++++++ .../ai-ready/references/github-discovery.md | 52 ++++ .../ai-ready/references/report-template.md | 196 ++++++++++++++ .../ai-ready/references/training-repos.md | 57 ++++ .github/workflows/ci.yml | 32 +++ .github/workflows/copilot-setup-steps.yml | 23 ++ AGENTS.md | 79 ++++++ CHANGELOG.md | 53 ++++ 13 files changed, 961 insertions(+) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.yml create mode 100644 .github/ISSUE_TEMPLATE/feature_request.yml create mode 100644 .github/PULL_REQUEST_TEMPLATE.md create mode 100644 .github/skills/ai-ready/SKILL.md create mode 100644 .github/skills/ai-ready/references/detection-tables.md create mode 100644 .github/skills/ai-ready/references/github-discovery.md create mode 100644 .github/skills/ai-ready/references/report-template.md create mode 100644 .github/skills/ai-ready/references/training-repos.md create mode 100644 .github/workflows/ci.yml create mode 100644 .github/workflows/copilot-setup-steps.yml create mode 100644 AGENTS.md create mode 100644 CHANGELOG.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..f1dd9a1 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,34 @@ +name: Bug Report +description: Report a problem with one of the Plesk scripts +labels: ["bug"] +body: + - type: dropdown + id: script + attributes: + label: Affected script + options: + - mysql-backups (mysql-backup.sh / mysql-backup.bat) + - remove-old-wordpress-backups (remove-wordpress-backups.sh) + - pci-dss-scan (pci-dss-scan.sh / pci-dss-scan.bat) + - essential-plugin-malware-scan (essential-plugin-scan.sh) + - monitor-domain-hosting (monitor-aspnet.bat) + - Other / not sure + validations: + required: true + - type: input + attributes: + label: Platform and Plesk version + description: e.g. "Ubuntu 22.04, Plesk Obsidian 18.0.60" or "Windows Server 2022, Plesk Obsidian 18.0.60" + validations: + required: true + - type: textarea + attributes: + label: What happened? + description: Include the exact command you ran and the full output/error. + validations: + required: true + - type: textarea + attributes: + label: Expected behavior + validations: + required: true diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..bcfe2c5 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,20 @@ +name: Feature Request +description: Suggest a new script or an improvement to an existing one +labels: ["enhancement"] +body: + - type: textarea + attributes: + label: What Plesk task should this automate? + validations: + required: true + - type: textarea + attributes: + label: Proposed approach + description: New script, or a change to an existing one? Which platform(s) — Windows, Linux, or both? + validations: + required: true + - type: textarea + attributes: + label: Additional context + validations: + required: false diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..d017603 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,20 @@ +## Description + + + +## Changes + + + +## How to test + + + +## Checklist + +- [ ] Updated both `.bat` and `.sh` versions for paired scripts (or N/A — single-platform script) +- [ ] Ran `shellcheck` on any changed bash script +- [ ] Updated `README.md` Features section if behavior/options changed +- [ ] No hardcoded credentials — placeholders or environment-based auth only diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 6394454..dfea1b5 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -308,6 +308,18 @@ fi - `monitor-aspnet.bat`: Monitors ASP.NET enabled status and sends email alerts on change - **`README.md`**: User-facing documentation (must be updated when features change) +## Maintenance Matrix + +When you change... | ...also update +--- | --- +`mysql-backups/mysql-backup.sh` | `mysql-backups/mysql-backup.bat` (platform parity), `README.md` Features/MySQL Backups section +`remove-old-wordpress-backups/remove-wordpress-backups.sh` | `README.md` Features/Remove Old WordPress Backups section (Linux-only, no `.bat` counterpart) +`pci-dss-scan/pci-dss-scan.sh` | `pci-dss-scan/pci-dss-scan.bat` (platform parity, basic-checks subset only), `README.md` PCI-DSS section +`essential-plugin-malware-scan/essential-plugin-scan.sh` | `README.md` Essential Plugin Scanner section (Linux-only, no `.bat` counterpart) +`monitor-domain-hosting/monitor-aspnet.bat` | `README.md` Domain Hosting Monitor section (Windows-only, no `.sh` counterpart) +Any bash script's self-update block | `SCRIPT_RELATIVE_PATH` and `UPDATE_CHECK_FILE` constants inside that same script only — self-update blocks are copy-pasted per script, not shared +Any script's env vars / CLI flags | That script's header comment block and its `README.md` section + ## Common Pitfalls 1. **Windows path handling**: Forgetting delayed expansion causes failures with Plesk's default path `C:\Program Files (x86)\Plesk` diff --git a/.github/skills/ai-ready/SKILL.md b/.github/skills/ai-ready/SKILL.md new file mode 100644 index 0000000..ed6b612 --- /dev/null +++ b/.github/skills/ai-ready/SKILL.md @@ -0,0 +1,246 @@ +--- +name: ai-ready +license: MIT +metadata: + version: "1.2.0" +description: "**ANALYSIS SKILL** — Analyze any repository and generate AI-ready configuration — AGENTS.md, copilot-instructions.md, skills, CI workflows, issue templates. WHEN: \"make this repo ai-ready\", \"set up AI config\", \"add copilot instructions\", \"prepare this repo for AI contributions\", \"generate AGENTS.md\". INVOKES: glob, grep, view, create, edit for repo analysis and file generation. FOR SINGLE OPERATIONS: use create/edit directly for individual config files." +--- + +# AI-Ready Repo Skill + +## Persona + +Adopt the perspective of an experienced repo maintainer who has managed high-traffic repos and reviewed thousands of PRs. Prioritize what **reduces review burden and contributor friction**. Every file you generate should earn its place — generic boilerplate creates noise. + +--- + +Follow these steps in order to analyze the current repository and generate all missing AI-ready configuration assets. + +**First run vs. re-run:** On the first run, most assets will be missing — the skill creates them. On re-runs, it **audits** existing assets against the current codebase, checking for drift, stale content, and new conventions from recent PR reviews. The skill **never overwrites existing files without user approval**. + +**Skipping assets:** If the user's prompt mentions skipping specific assets (e.g., "skip CI and issue templates"), respect those exclusions. Still run the full analysis, but skip generation for the excluded assets. + +**Report-only mode:** If the user asks for a report without generating files (e.g., "how ai-ready is this repo?", "score this repo"), run the full analysis (Steps 0–1) and display the report (Step 11) — but skip all generation steps (Steps 2–10). + +### The 12 tracked assets + +Assets are grouped into three categories. Count assets with **Nailed It** status for the score. + +**🤖 AI Context** — what AI agents read to understand your repo + +| # | Asset | Generated in | +|---|-------|-------------| +| 1 | `AGENTS.md` | Step 2 | +| 2 | `.github/copilot-instructions.md` | Step 3 | +| 3 | Maintenance matrix (in `copilot-instructions.md`) | Step 8 | +| 4 | `.mcp.json` | Step 4b | +| 5 | `.github/workflows/copilot-setup-steps.yml` | Step 4 | + +**🔧 Dev Workflow** — what keeps PRs clean and contributors on track + +| # | Asset | Generated in | +|---|-------|-------------| +| 6 | CI workflow (`.github/workflows/ci.yml`) | Step 5 | +| 7 | Issue templates (`.github/ISSUE_TEMPLATE/`) | Step 6 | +| 8 | PR template (`.github/PULL_REQUEST_TEMPLATE.md`) | Step 6 | +| 9 | `.github/dependabot.yml` | (checked, not generated) | + +**📖 Onboarding** — what helps new contributors get started + +| # | Asset | Generated in | +|---|-------|-------------| +| 10 | README Contributing section | Step 7 | +| 11 | Changelog (`CHANGELOG.md`) | Step 9 | +| 12 | Documentation (or explicit "not needed" note) | Step 10 | + +**Scoring:** 🟩 Nailed It (counted) · 🟨 Could Be Better (not counted) · ⬜ Missing (not counted) + +| Medal | Name | Count | What it means | +|-------|------|-------|---------------| +| 🥉 | **Getting Started** | 1–4 | Basics in place but AI agents are mostly guessing | +| 🥈 | **On Track** | 5–7 | AI agents can help but miss your conventions | +| 🥇 | **Solid** | 8–10 | AI agents follow your patterns and catch most expectations | +| 🏆 | **AI-Ready** | 11–12 | AI agents contribute like your best team members | + +--- + +## Step 0 — Detect GitHub context automatically + +**Zero user input required.** The skill is GitHub-native — it discovers everything from GitHub's tools. + +### 0a. Identify the repo + +Run `git remote -v` to extract the GitHub `owner/repo`. If not GitHub, fall back to local-only analysis. + +### 0b–0d. Fetch metadata, mine PR reviews, check community health + +Use GitHub MCP tools or `gh` CLI to auto-discover repo metadata, PR review patterns, and community health gaps. See [references/github-discovery.md](references/github-discovery.md) for the full API table, PR mining technique, and health gap mapping. + +Key insight: **PR review mining is the highest-value step.** Repeated reviewer feedback becomes conventions in `copilot-instructions.md`. + +--- + +## Step 1 — Analyze the codebase + +GitHub context tells you *what* the repo is. Local analysis tells you *how* it works. Use glob, grep, and view combined with GitHub context from Step 0. + +### 1a. Detect languages, frameworks, and repo type + +Find manifest files and extract details. See [references/detection-tables.md](references/detection-tables.md) for the full manifest table, VS Code extension detection, multi-app collections, demo app patterns, and course/tutorial repo detection. + +Key detections: lockfiles, runtime version files, monorepo markers, notebooks, VS Code extensions, multi-app collections, demo apps. + +**Course repos** (3+ signals: numbered folders, lesson keywords, no primary app) adapt Steps 2–5. See detection-tables.md for the full signal list and step adaptations. + +### 1b. Detect test setup + +Identify test runner, find test directories (`tests/`, `__tests__/`, `spec/`, `e2e/`), extract test commands from scripts. + +### 1c. Detect CI/CD + +Check `.github/workflows/` for PR triggers. Check for other CI systems. Recognize community workflows (stale, welcome) as valid automation — not missing CI. + +### 1d. Check existing AI configuration + +Check for: `AGENTS.md`, `.github/copilot-instructions.md`, `.github/skills/`, `.github/agents/`, `.github/extensions/`, `.devcontainer/`. + +**copilot-setup-steps.yml** — check ALL known locations: `.github/workflows/copilot-setup-steps.yml` (canonical), `.github/copilot-setup-steps.yml` (legacy), and repo root. If found in a non-canonical location, flag it for consolidation into `.github/workflows/` — do not create a duplicate. + +If multiple instruction files exist, check for duplicates, contradictions, stale references, and scope clarity. See [references/detection-tables.md](references/detection-tables.md) for drift detection details. + +### 1e. Check repo configuration + +Check for: `CODEOWNERS`, `dependabot.yml`, issue templates, PR template, `LICENSE`, README Contributing section. + +### 1f–1g. Evaluate changelog and documentation + +Assess changelog health (exists, format, freshness). Assess docs (exists, framework, navigation, deploy pipeline, README linkage). + +### 1h. Scan directory structure + +List top-level directories and immediate children (skip `node_modules`, `.git`, `dist`, `build`, `target`, `vendor`). + +### 1i. Compile findings + +Produce a structured findings table combining GitHub context and codebase analysis with file-path evidence. See [references/detection-tables.md](references/detection-tables.md) for the full findings table template. + +List which of the 12 assets are missing. For existing assets, compare against analysis and flag drift as "Could Be Better." + +### 1j. Detect monorepo areas + +If workspace config found, list areas with name, path glob, and primary stack. For large library monorepos, map cross-package dependencies. See [references/detection-tables.md](references/detection-tables.md) for details. + +--- + +## Step 2 — Generate AGENTS.md + +If missing, create `AGENTS.md` at the repo root. If it exists, compare against analysis and flag drift. **Do not overwrite.** + +Sections: Project Overview (never hardcode versions — reference manifests), Repository Structure, Tech Stack, Build & Run, Testing, Key Patterns and Conventions, CI/CD, Adding a New [Feature/Module] (trace the full registration chain — enums, index re-exports, config declarations), Screen Size / Responsive Rules (UI projects only), Common Pitfalls. + +--- + +## Step 3 — Generate .github/copilot-instructions.md + +If missing, create it. If it exists, compare against analysis — especially new PR review patterns and maintenance matrix drift. + +Content: Language-Specific Conventions (separate subsections for multi-language repos), Notebook Conventions (if `.ipynb` detected), Course/Lesson Conventions (if course repo), Framework Patterns, Conventions Mined from PR Reviews, Test Conventions, Code Style Notes (reference linter configs), Asset/Content Rules (if assets detected), **Maintenance Matrix** (trace dependency graphs — the most valuable section). + +The maintenance matrix defines what must be updated when different parts of the codebase change. Populate with real file paths. Trace import chains and registration patterns — don't stop at top-level files. + +**Monorepo:** Create `.github/instructions/{area-name}.instructions.md` with `applyTo` patterns for areas with different stacks. + +--- + +## Step 4 — Generate copilot-setup-steps.yml + +Check ALL locations first: `.github/workflows/copilot-setup-steps.yml`, `.github/copilot-setup-steps.yml`, and repo root. If one exists anywhere, do NOT create another — consolidate into `.github/workflows/` if at a legacy location. + +If truly missing from all locations, create `.github/workflows/copilot-setup-steps.yml`. Steps: checkout, set up runtime, install dependencies, install test dependencies, build. Derive from existing CI when possible. For .NET multi-target, install all required SDK versions. + +--- + +## Step 4b — Generate .mcp.json + +If missing, generate `.mcp.json` at the repo root based on detected dependencies (databases, APIs, cloud platforms, browser automation, DevOps tools). Use `${VAR}` for secrets. Only include servers the project actually needs — do not speculatively add servers. + +*Why?*: Copilot CLI no longer supports `.vscode/mcp.json` — the correct location is `.mcp.json` at the repo root. If `.vscode/mcp.json` exists, flag it as "Could Be Better" and suggest migrating to `.mcp.json`. + +--- + +## Step 5 — Generate CI workflow + +If no PR-triggered workflow exists, create `.github/workflows/ci.yml` with: `pull_request` + `push` triggers with `paths-ignore` for docs/config, a build-and-test job matching the project's actual toolchain. Use the **default branch** detected in Step 0b — do not hardcode `main`. Never modify existing workflows. + +--- + +## Step 6 — Generate issue templates and PR template + +If missing, create bug report and feature request YAML forms, plus a PR template with description, changes, how-to-test, and checklist (derived from maintenance matrix). Note old-format `.md` templates as "Could Be Better." + +--- + +## Step 7 — Update README Contributing section + +If README exists but has no Contributing section: link to `CONTRIBUTING.md` if it exists, otherwise add a Contributing section with fork/branch/PR instructions and test commands. Never rewrite the rest of the README. + +--- + +## Step 8 — Verify maintenance matrix + +Verify the matrix in `copilot-instructions.md` covers file cross-references, change cascades, and cross-cutting concerns. Trace actual dependency graphs per language (`.csproj` ProjectReferences, import chains, `mod` declarations, `__init__.py` re-exports). + +--- + +## Step 9 — Evaluate and improve changelog + +If missing, create `CHANGELOG.md` with Keep a Changelog format. If a pointer file, verify the target. If stale, flag with dates. Document non-standard locations in AGENTS.md. + +--- + +## Step 10 — Evaluate and improve documentation + +If docs exist, add to AGENTS.md and copilot-instructions.md. If missing, assess whether needed by project type. Always document docs status in AGENTS.md. + +--- + +## Step 11 — Display the AI-Readiness Report + +Display the report using the format in [references/report-template.md](references/report-template.md). Include the skill version from frontmatter `metadata.version` at the bottom of the report (e.g., `Assisted by ai-ready v1.0.0`). Then: +1. Add AI-Ready badge (see report-template.md § 11a) +2. Offer to create PR (see report-template.md § 11b) + +--- + +## Important Rules + +### Do No Harm + +This skill's first obligation is to leave the repo in a **better state than it found it — never worse**. Every rule below serves this principle. + +- **NEVER create duplicates** — before creating any file, check ALL known locations (canonical, legacy, and root). If a file exists anywhere, do not create another copy. Consolidate instead. +- **NEVER push directly to main/master** — always create a feature branch and open a PR for review. The only exception is if the user explicitly asks to commit to the default branch. +- **NEVER overwrite existing files** — only create missing assets. Flag drift for user review. +- **NEVER delete files without user approval** — if consolidating duplicates or removing stale files, include the deletion in the PR for review. + +### General Rules + +- **NEVER open a pager** — append `| cat` to every `gh`/`git` command. Use `git --no-pager`. +- **ALWAYS customize to the repo's actual stack** — never produce generic boilerplate. +- **Self-consistency** — every generated file must follow the conventions you establish. Cross-check before finalizing. +- **GitHub-native by default** — auto-discover via MCP tools and `gh` CLI. Fall back to local analysis. +- **Mine PR reviews** — turn repeated review feedback into `copilot-instructions.md` rules. +- **Be specific** — real file paths, real commands, real patterns. +- **Use `create` to write new files** — never `edit` from scratch. +- **Run full analysis first (Steps 0–1)** — never guess. +- **ALWAYS display the report at the end** — never skip or abbreviate. +- **NEVER use markdown headings in user output** — use bold + emojis instead. +- **ALWAYS mention the AI Ready skill in issue/PR communication** — when posting to an issue or PR (body or comment), include explicit attribution such as `Assisted by [ai-ready](https://github.com/johnpapa/ai-ready)`. +- **ALWAYS update docs to repo standards** — when generated guidance or workflows change, update related docs and changelog per the repo's maintenance matrix (for this repo: `README.md`, `docs/how-it-works.md`, `AGENTS.md`, `CHANGELOG.md`). +- **ALWAYS handle PR conflicts proactively** — when creating PRs, sync with the target branch and attempt conflict resolution; if conflicts remain, explicitly ask the user how they want to proceed. + +--- + +## Training Repos + +See [references/training-repos.md](references/training-repos.md) for the full list of repos used to validate this skill's heuristics. diff --git a/.github/skills/ai-ready/references/detection-tables.md b/.github/skills/ai-ready/references/detection-tables.md new file mode 100644 index 0000000..38dd2b2 --- /dev/null +++ b/.github/skills/ai-ready/references/detection-tables.md @@ -0,0 +1,137 @@ +# Detection Tables Reference + +Detailed detection heuristics for Step 1 — codebase analysis. + +## Manifest detection + +| Manifest | Language | What to extract | +|----------|----------|-----------------| +| `package.json` | JavaScript/TypeScript | dependencies, devDependencies, scripts (build, test, lint, typecheck), engines.node | +| `Cargo.toml` | Rust | workspace members, dependencies, build/test profile | +| `go.mod` | Go | module name, Go version | +| `pyproject.toml` or `requirements.txt` | Python | dependencies, build system, scripts, python version | +| `*.csproj` or `*.sln` | C# / .NET | target framework, package references, test SDK | +| `Gemfile` | Ruby | dependencies, ruby version | +| `pom.xml` or `build.gradle` | Java | dependencies, plugins, build tasks | + +Also check for: +- **Lockfiles** — `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`, `bun.lockb`, `Cargo.lock`, `go.sum`, `poetry.lock`, `Pipfile.lock` +- **Runtime version files** — `.nvmrc`, `.node-version`, `.python-version`, `.tool-versions`, `.ruby-version`, `rust-toolchain.toml` +- **Monorepo markers** — `pnpm-workspace.yaml`, `lerna.json`, `nx.json`, `turbo.json`, Cargo workspace, Go workspace. Also check for **large library monorepos**: Maven aggregator (`pom.xml` with ``), Python multi-package (`libs/` directory with multiple `pyproject.toml`), or Turborepo + Changesets (`turbo.json` + `.changeset/`). + + *Why?*: Large open-source libraries like LangChain organize code as multi-package monorepos — dozens of independently published packages under one repo. Treating them as a single package misses cross-package dependencies, per-package build commands, and module-specific conventions. +- **Notebooks** — `*.ipynb` files. If found, note the count and locations. Notebooks are common in course repos, data science projects, and tutorials. + +## VS Code extension detection + +Check for `contributes` in root `package.json` (commands, themes, snippets, views, menus). If present, this is a **VS Code extension**, not a regular app. Also check for `vsce` or `@vscode/vsce` in devDependencies, and `vscode:prepublish` in scripts. Extensions come in three flavors: +- **Functional extensions** — TypeScript code with activation events, commands, webpack/esbuild bundling, tests +- **Theme extensions** — JSON theme files, no runtime code, published via `vsce` +- **Snippet extensions** — JSON snippet definitions, language-scoped, content-driven not logic-driven + +*Why?*: VS Code extensions look like npm packages but have completely different conventions. The `package.json` IS the product spec — commands, menus, settings, keybindings. Treating them like a web app misses what matters. + +## Multi-app collection detection + +Multiple independent apps in subdirectories (e.g., `angular/`, `react/`, `svelte/`), each with its own `package.json`, but **no workspace config** tying them together. This is different from a monorepo — there's no shared build or dependency graph. Each app builds and runs independently. + +*Why?*: Not every repo with multiple folders is a monorepo. Some are "collections" — the same concept implemented in different frameworks for comparison or learning. Don't invent workspace tooling where none exists. + +## Demo app pattern detection + +A frontend app + mock backend (`json-server`, `db.json`) + proxy config (`proxy.conf.json`, `vite.config.ts` proxy). Common in demo/tutorial repos. If detected, document the mock API setup in AGENTS.md so agents know to start both frontend and backend. + +## Course/tutorial repo detection + +*Why?*: Course repos are fundamentally different from application repos. The "product" is markdown lessons and code samples — not a running application. Generating CI, setup steps, or a build pipeline for a course repo misses the point. Detecting this early shapes every later step. + +Check for **multiple signals** — no single check is definitive: + +1. **Numbered folders** — glob for top-level directories matching `NN-*` (e.g., `00-intro`, `01-setup`, `05-advanced`), `N-topic` (e.g., `1-Introduction`, `6-Data-Science-In-Wild`), `Chapter N`, `Module N`, or `Unit N`. 3+ matches is a strong signal. +2. **README content** — scan the root README for course/tutorial language: "lesson", "chapter", "module", "unit", "what you'll learn", "prerequisites", "course structure", "hands-on", "assignment", "quiz", "curriculum", "week". Multiple matches strengthen the signal. +3. **Repo description/topics** — check the GitHub description and topics (from Step 0b) for terms like "beginners", "course", "tutorial", "workshop", "learn", "curriculum", "lessons". +4. **Lesson structure** — check if numbered folders each contain a `README.md` (lesson content) and optionally `assignment.md`, `solution/`, `code/`, `quiz/`, or `notebook/` subdirectories. +5. **No primary application** — the repo has no root-level `package.json`, `Cargo.toml`, `go.mod`, or other manifest that would indicate a buildable application (individual lesson folders may have their own manifests for code samples). +6. **Devcontainer** — check for `.devcontainer/` directory. Common in course repos to provide a ready-to-go development environment. If present, credit it as a form of environment setup (similar to copilot-setup-steps.yml). + +**A repo is a course if 3+ of these signals are present.** Record it in the findings table as `Repo type: course` with evidence. + +### Course repo adaptations + +When a repo is a course, the following steps adapt: +- **Step 4** (copilot-setup-steps.yml) — skip if a `.devcontainer/` exists (it serves the same purpose for courses). If no devcontainer and no build step, skip entirely. +- **Step 5** (CI workflow) — skip build/test CI. Suggest markdown validation (link checking, spell check) instead if not already present. +- **Step 3** (copilot-instructions.md) — include lesson structure conventions: expected folder contents, naming patterns, how to add a new lesson. If lessons have quizzes or assignments, document the expected structure (e.g., each lesson needs `README.md` + `assignment.md` + `solution/`). +- **Step 2** (AGENTS.md) — "Adding a New Lesson" section instead of "Adding a New Feature". Include the lesson template (what files/folders each lesson should contain). +- **Report** — mark skipped assets as "N/A — course repo" instead of "Missing". Credit `.devcontainer/` in the "Nailed It" section if present. + +## Findings table template + +Before proceeding from Step 1, produce a structured summary combining GitHub context (Step 0) and codebase analysis (Step 1). Include file-path evidence for each finding: + +| Category | Finding | Evidence (source) | +|----------|---------|-------------------| +| Repo | e.g., johnpapa/ai-ready | `git remote -v` | +| Description | e.g., "Copilot CLI skill..." | GitHub API / repo metadata | +| Topics | e.g., copilot, skills, ai-ready | GitHub API | +| Language | e.g., TypeScript (65%), Rust (30%) | GitHub API language breakdown | +| Multi-language | yes/no — if no single language exceeds 50%, flag as multi-language | GitHub API | +| Repo type | app / course / docs-only / VS Code extension / npm package / collection | Step 1a-ii detection | +| VS Code extension type | functional / theme / snippets (if applicable) | `package.json` contributes field | +| Notebooks | e.g., 12 `.ipynb` files in `lessons/` | glob for `*.ipynb` | +| Mock backend | e.g., json-server on port 3000 | `db.json`, proxy config | +| Framework | e.g., React, Phaser | `package.json` dependencies | +| Test runner | e.g., Vitest | `package.json` devDependencies | +| Test command | e.g., `npm test` | `package.json` scripts.test | +| Build command | e.g., `npm run build` | `package.json` scripts.build | +| Runtime version | e.g., Node 22 | `.nvmrc` or `package.json` engines | +| Package manager | e.g., pnpm | `pnpm-lock.yaml` exists | +| Contributors | e.g., 3 contributors | GitHub API | +| Team size | e.g., solo / small / large | Contributor count | +| PR CI exists | yes/no | `.github/workflows/` or GitHub Actions API | +| Community health | e.g., 71% | GitHub API community/profile | +| PR review patterns | e.g., "maintainer often asks for tests" | Mined from recent PR review comments | +| Release cadence | e.g., monthly, tagged releases | GitHub Releases API | +| AGENTS.md | exists / missing | repo root | +| copilot-instructions.md | exists / missing | `.github/` | +| Changelog | exists / pointer / missing | `CHANGELOG.md`, Releases | +| Changelog freshness | current / stale | latest entry vs latest git tag | +| Docs exist | yes / no | `docs/`, config file | +| Docs framework | Docsify / Docusaurus / etc. | config file path | +| Docs deploy pipeline | yes / no | workflow file path | +| README links to docs | yes / no | README.md link | +| Default branch | e.g., `main`, `dev`, `master` | `gh repo view --json defaultBranchRef` | +| Push access | yes / no | `gh api repos/{owner}/{repo} --jq '.permissions.push'` | +| Custom agents | e.g., 2 agents: migration guide, orchestrator | `.github/agents/` | +| Custom skills | e.g., 6 skills: bunit-test, component-dev, ... | `.github/skills/` | +| Devcontainer | yes/no | `.devcontainer/` | +| Monorepo | yes/no | workspace config file | +| Areas | e.g., frontend (React), backend (Express), shared (TypeScript) | workspace config paths | + +## Drift detection for existing assets + +For existing AI-ready assets, read their current contents and compare against your analysis. Flag drift in any of these dimensions: + +| Asset | What to compare | +|-------|----------------| +| `AGENTS.md` | Repo structure still accurate? Build/test commands still correct? Tech stack changed? | +| `copilot-instructions.md` | New conventions from recent PR reviews? Maintenance matrix still covers current file relationships? | +| `copilot-setup-steps.yml` | Runtime versions match? Install/build commands still correct? New dependencies? | +| CI workflow | Build/test/lint commands still match the project? New tools added? | +| Issue templates | Still relevant to the project type? | +| README Contributing | Links still valid? Commands still correct? | + +For each existing asset where you find drift, classify it as **"Could Be Better"** in the report with a specific suggestion (e.g., "AGENTS.md lists Node 18 but `.nvmrc` now says Node 22"). Do not silently skip existing files — always evaluate them. + +## Monorepo area detection + +If a workspace config was found in Step 1a, read it to find package/project paths (e.g., `packages/*`, `apps/*`, `libs/*`). List each area — name, path glob, and primary stack — and note which areas have conventions that differ from root. + +**For large library monorepos** (Maven aggregator, Python `libs/`, pnpm workspace with many packages): +- List each published package/module separately with its purpose (e.g., `langchain4j-core`, `langchain4j-open-ai`, `langchain4j-ollama`) +- Note the module taxonomy if one exists (core vs providers vs integrations vs experimental) +- Identify **cross-package dependencies** — which packages depend on which. Changes to core packages ripple to all dependents. +- Detect **release tooling** — Changesets (`.changeset/`), semantic-release, Maven release plugin, or manual versioning. Document in the maintenance matrix. +- Detect **conditional modules** — JDK-specific modules (`jdk21`), platform-specific builds, or optional integrations that only build under certain conditions. + +*Why?*: A fix in `langchain4j-core` affects 30+ downstream modules. Without mapping cross-package dependencies, agents make changes to one package and miss the ripple effects. diff --git a/.github/skills/ai-ready/references/github-discovery.md b/.github/skills/ai-ready/references/github-discovery.md new file mode 100644 index 0000000..71cc2f8 --- /dev/null +++ b/.github/skills/ai-ready/references/github-discovery.md @@ -0,0 +1,52 @@ +# GitHub Discovery Reference + +Detailed API calls and techniques for Step 0 — GitHub-native context discovery. + +## 0b. Fetch repo metadata from GitHub + +Use the GitHub MCP tools (if available) or `gh` CLI to pull rich context the user should never have to explain: + +| What to fetch | Tool / Command | What you learn | +|---------------|---------------|----------------| +| Repo description, topics, visibility, default branch | `github-mcp-server-get_file_contents` on `/` or `gh repo view --json description,topics,isPrivate,primaryLanguage,defaultBranchRef --jq '.' | cat` | What this project is about, how it's categorized, default branch name | +| Language breakdown | `gh api repos/{owner}/{repo}/languages | cat` (bash) | Accurate language percentages (better than guessing from files) | +| Community health | `gh api repos/{owner}/{repo}/community/profile | cat` (bash) | Which community files exist (CONTRIBUTING, CODE_OF_CONDUCT, license, issue templates) — GitHub already knows this | +| Contributors | `gh api repos/{owner}/{repo}/contributors --jq '.[].login' | cat` (bash) | Team size, contribution patterns | +| Open issues | `github-mcp-server-list_issues` or `gh issue list | cat` | Active problems, what the project cares about | +| Recent merged PRs | `gh pr list --state merged --limit 10 --json title,body,files | cat` (bash) | Contribution patterns — what files get touched together, what a typical PR looks like | +| PR review comments | `github-mcp-server-pull_request_read` on recent PRs | **Repeated review feedback = conventions that should be in copilot-instructions.md** | +| Releases | `gh release list --limit 5 | cat` (bash) | Release cadence, versioning scheme | +| GitHub Actions workflows | `github-mcp-server-actions_list` or read `.github/workflows/` | CI/CD setup, what runs on PRs | +| Branch protection | `github-mcp-server-list_branches` | Default branch, protection rules | +| Push permissions | `gh api repos/{owner}/{repo} --jq '.permissions.push' | cat` (bash) | Whether the user can push directly or needs to fork | + +## 0c. PR review mining details + +This is the **highest-value** GitHub-native insight. Look at the 5-10 most recent merged PRs. + +*Why?*: If a maintainer leaves the same review comment on 5 different PRs, that's a convention waiting to be documented. Mining PR reviews turns reviewer fatigue into automated guidance. + +1. Use `github-mcp-server-list_pull_requests` (state: closed, sort: updated) to find recent merged PRs +2. For each, use `github-mcp-server-pull_request_read` (method: get_review_comments) to read review threads +3. Look for **repeated patterns** — the same feedback given across multiple PRs becomes a convention: + - "Please add tests for this" → add to test conventions + - "Use X pattern instead of Y" → add to coding conventions + - "Update the docs when you change this" → add to maintenance matrix + - "Don't forget to update the changelog" → add to maintenance matrix + +**If few or no review comments are found** (e.g., PRs are self-merged or auto-merged), expand the search to up to 20 merged PRs. If there are still no review patterns, note this in the findings: _"No PR review patterns found — consider adding conventions as the team grows."_ Never silently skip this section. + +These mined conventions go directly into `copilot-instructions.md` — turning repeated human review feedback into automated AI guidance. + +## 0d. Community health gap mapping + +GitHub's community health API tells you exactly what's missing. Map it to the assets this skill generates: + +| GitHub says missing | Skill generates | +|-------------------|-----------------| +| No issue templates | `.github/ISSUE_TEMPLATE/` (Step 6) | +| No pull request template | `.github/PULL_REQUEST_TEMPLATE.md` (Step 6) | +| No CONTRIBUTING guide | README Contributing section (Step 7) | +| No CODE_OF_CONDUCT | Can suggest adding one | +| No license | Flag in the report | +| No README | Flag in the report | diff --git a/.github/skills/ai-ready/references/report-template.md b/.github/skills/ai-ready/references/report-template.md new file mode 100644 index 0000000..5f9087f --- /dev/null +++ b/.github/skills/ai-ready/references/report-template.md @@ -0,0 +1,196 @@ +# Report Template Reference + +Display format for the AI-Readiness Report (Step 11), HTML report, badge, and PR creation. + +## AI-Readiness Report format + +Calculate the score by counting how many assets have **Nailed It** status. Determine the maturity level from the count. Build the progress bar using 🟩 for nailed, 🟨 for could-be-better, and ⬜ for missing — always 12 squares. + +Display this report: + +``` +🎯 **AI-Readiness Report** + +Your repo is about to get a whole lot easier to contribute to — and +a whole lot faster to review. AI agents will know your conventions, +follow your patterns, and deliver PRs that are ready to merge. + +**{repo-name}** + +--- + +📊 **Your Repo Today** · {medal} **{level-name}** · {progress-bar} · {nailed} of 12 nailed +{languages} · {frameworks} · {test-runner} ({test-count}) · `{build-command}` + +🤖 **Existing AI Config (detected)** + +_Include this section only if the repo already has AI configuration (copilot-instructions.md, custom agents, custom skills). Omit it entirely if there is no pre-existing AI config._ + +| Asset | Detail | +|-------|--------| +| {asset-name} | {detail — e.g., "542 lines — components, testing, shims, docs"} | +| {.github/agents/} | {count} agents: {names} | +| {.github/skills/} | {count} skills: {names} | + +⚠️ **Instruction Consistency** + +_Show this section when consistency issues are found — skip it when everything lines up._ + +| Issue | Files | Detail | +|-------|-------|--------| +| {issue-type} | {file1} ↔ {file2} | {specific contradiction or duplication} | + +✅ **Nailed It ({count})** + +| Asset | Detail | +|-------|--------| +| {asset-name} | {one-line detail} | +| ... | ... | + +💡 **Could Be Better ({count})** + +| Asset | Suggestion | +|-------|-----------| +| {asset-name} | {suggestion} | +| ... | ... | + +_Why these matter:_ {brief explanation of why the could-be-better items are worth improving} + +⭕ **Missing ({count})** + +| Asset | Why it matters | +|-------|---------------| +| {asset-name} | {why it matters} | +| ... | ... | + +_Why these matter:_ {brief explanation of what the missing items cost the repo} + +--- + +🛠️ **What I'd Like To Do** — proposed changes to close the gaps: + +| Action | Detail | +|--------|--------| +| ➕ Create | `{filename}` — {what it will contain} | +| 🔍 Audit | `{filename}` — {what drifted and suggested fix} | +| ⏭️ Skip | `{filename}` — skipped (user requested) | +| 💬 Suggest | {suggestion} | +| ✅ Skip | {count} files already in great shape | + +_For monorepos: list each `.github/instructions/{area}.instructions.md` file created as a separate ➕ Create row._ + +--- + +🏆 **If You Accept** · {after-progress-bar} · {after-nailed} of 12 nailed → {after-medal} **{after-level}** + +🤖 AI Context {5 status indicators} +🔧 Dev Workflow {4 status indicators} +📖 Onboarding {3 status indicators} + +--- + +🚀 **What's Next?** + +👉 **Create the PR now** — just say: +\``` +create a branch and open a PR with these changes +\``` + +👉 **Tweak first** — tell me what to change: +\``` +update the AGENTS.md to include more detail about the command registration pattern +\``` + +👉 **Share the report** — want a visual version for your team? +\``` +generate an HTML report I can share +\``` + +👉 **Skip for now** — no worries, the analysis is done. Come back anytime and say `make this repo ai-ready` to pick up where you left off. +``` + +## Report template rules + +- **Nailed It** = asset exists and is well-customized to the repo +- **Could Be Better** = asset exists but has gaps or could be enhanced +- **Missing** = asset does not exist and should be created +- If a section has 0 items (e.g., nothing missing), omit that section entirely +- The tech profile table should only include rows that apply (e.g., skip "Frameworks" if none detected) +- Keep each detail to one short line — no multi-line descriptions +- The "What I Did" section should list every file that was created, suggested, or skipped +- **Show an updated progress bar** after the "What I Did" section — recount nailed assets (counting all created files as now "Nailed It"), determine the new medal, and show the category breakdown. This shows the user the improvement visually (e.g., going from 🥈 On Track · 🟩🟩🟩🟩🟩🟨⬜⬜⬜⬜⬜⬜ · 5 of 12 → 🏆 AI-Ready · 🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩 · 12 of 12) +- The "What To Do Next" section should include only the bullet points that are relevant — e.g., if no files were created, skip "review generated files" and instead say something like "Your repo is already AI-ready — nice work!" +- **Issue/PR provenance is mandatory** — every issue comment, PR comment, or PR body update generated by this skill must include `Assisted by [ai-ready](https://github.com/johnpapa/ai-ready)`. +- **Documentation sync is mandatory** — when changing generated guidance, templates, or PR behavior, update related documentation to match the repository's documented standards and maintenance matrix. + +## HTML report (optional) + +*Why?*: Terminal reports are great for the developer running the skill. But when you need to share results with a manager, post to a wiki, or attach to an email — you need something visual. + +If the user asks for an HTML report (e.g., "generate a report I can share", "make an HTML report"), generate a self-contained `ai-ready-report.html` in the repo root. + +The HTML report mirrors the terminal summary — same sections, same data, same structure: + +1. **Header** — repo name, maturity level with emoji medal (🥉🥈🥇🏆), weighted score percentage, progress bar, generation date +2. **Tech profile** — languages, frameworks, test runner, build command +3. **Existing AI config** — if detected (copilot-instructions.md, custom agents/skills) +4. **Instruction consistency** — if issues found +5. **Asset status** — three groups: ✅ Nailed It, 💡 Could Be Better, ⭕ Missing — with one-line details per asset +6. **What was generated** — action table (➕ Create, 🔍 Audit, ⏭️ Skip, 💬 Suggest) +7. **Updated score** — before/after with maturity level change +8. **What to do next** — remaining recommendations + +The file must be self-contained (inline CSS, no external dependencies) and shareable — one file you can open in any browser or drop into an email. Use green/amber/gray status colors, system fonts, and a responsive layout. Keep it simple — this is a summary, not a dashboard. + +Generate the HTML report only when the user asks for it. The terminal output is always the default. + +## 11a. AI-Ready badge + +Check if the README already contains an `AI--Ready` badge. If it does not, **automatically** insert this badge at the top of the README, after any existing title or badge row — do not ask, just add it: + +```markdown +[![AI Ready](https://img.shields.io/badge/AI--Ready-yes-brightgreen?style=flat)](https://github.com/johnpapa/ai-ready) +``` + +The badge is a static Shields.io image with zero dependencies. It links back to the ai-ready repo so others can discover it. Include this in the "What I Did" section of the report as a `➕ Create` action. + +## 11b. PR creation flow + +After displaying the report and handling the badge, **ask the user** if they want to create a branch and open a PR. Do not tell them to type a command — ask them directly: + +_"Would you like me to create a branch and open a PR with these changes?"_ + +If the user agrees: + +1. **Check push permissions** from Step 0b. +2. **If the user has push access**: create a feature branch (e.g., `feat/ai-ready-config`), commit all new/modified files (including the badge), push, and open a PR targeting the **default branch** (detected in Step 0b — never assume `main`). +3. **If the user does NOT have push access**: use a fork-based flow automatically — fork the repo (`gh repo fork --clone=false`), add the fork as a remote, push the branch to the fork, then open a cross-fork PR (`gh pr create --head {user}:feat/ai-ready-config`). Handle it end-to-end — never ask the user to figure out the fork workflow. +4. **Before opening the PR**: sync with the target branch and attempt to resolve merge conflicts. If conflicts cannot be resolved confidently, ask the user whether to proceed with help resolving conflicts or pause for manual intervention. + +Include a summary of what was added and the before/after score in the PR body, and include `Assisted by [ai-ready](https://github.com/johnpapa/ai-ready)` in that PR body summary. If the user declines, end the session gracefully. + +**Always add exactly one consolidated report comment to the PR.** After creating the PR, post a single comment with a condensed version of the AI-Readiness Report and include all immediate asks/clarifications in that same comment: + +``` +## 🎯 AI-Readiness Report + +**{repo-name}** + +**Before:** {before-medal} **{before-level}** · {before-nailed} of 12 nailed +**After this PR:** {after-medal} **{after-level}** · {after-nailed} of 12 nailed + +🤖 AI Context {status indicators} +🔧 Dev Workflow {status indicators} +📖 Onboarding {status indicators} + +| Action | File | +|--------|------| +| ➕ Create | `{filename}` | +| ... | ... | + +Assisted by [ai-ready](https://github.com/johnpapa/ai-ready) +``` + +If additional clarification is needed right away, **update the same comment** (or include it in the PR body update) instead of posting serial "quick/final clarification" follow-up comments. Only add a new comment later when there is truly new information (e.g., user asked a new question, CI status changed, or scope changed). + +*Why?*: The PR body is written once, but the report comment is what reviewers see first. A single, scannable summary avoids notification spam and makes it easy to understand impact at a glance. diff --git a/.github/skills/ai-ready/references/training-repos.md b/.github/skills/ai-ready/references/training-repos.md new file mode 100644 index 0000000..728f772 --- /dev/null +++ b/.github/skills/ai-ready/references/training-repos.md @@ -0,0 +1,57 @@ +# Training Repos + +This skill's heuristics — especially course detection, notebook handling, and multi-language support — were trained and validated against these repos. Use them for regression testing when making changes to the skill. + +## Course/Tutorial repos + +- `github/copilot-cli-for-beginners` — Copilot CLI course (markdown + Python) +- `microsoft/ai-agents-for-beginners` — AI agents course (markdown + notebooks + Python/C#) +- `microsoft/generative-ai-for-beginners` — GenAI course (markdown + notebooks + Python/JS/TS) +- `microsoft/mcp-for-beginners` — MCP tutorial (markdown + TS/Python/Java/C#) +- `microsoft/langchainjs-for-beginners` — LangChain.js course (markdown + TypeScript) +- `microsoft/langchain-for-beginners` — LangChain course (markdown + Python) +- `microsoft/langchain4j-for-beginners` — LangChain4j course (markdown + Java) +- `microsoft/ML-For-Beginners` — Machine Learning course (markdown + notebooks + Python) +- `microsoft/Web-Dev-For-Beginners` — Web development course (markdown + JS/HTML/CSS) +- `microsoft/AI-For-Beginners` — AI course (markdown + notebooks + Python) +- `microsoft/Data-Science-For-Beginners` — Data science course (markdown + notebooks + Python) +- `microsoft/IoT-For-Beginners` — IoT course (markdown + hardware samples) +- `microsoft/Generative-AI-for-beginners-dotnet` — GenAI .NET course (markdown + C#) +- `microsoft/generative-ai-for-beginners-java` — GenAI Java course (markdown + Java) +- `microsoft/AZD-for-beginners` — Azure Developer CLI tutorial (markdown + CLI examples) +- `microsoft/edgeai-for-beginners` — Edge AI course (markdown + sample apps) +- `microsoft/xr-development-for-beginners` — XR/Unity course (markdown + Unity/C#) + +## Application repos + +- `johnpapa/vscode-peacock` — VS Code functional extension (TypeScript, Mocha tests) +- `johnpapa/shopathome` — Multi-framework shopping app (Angular 21, React 19, Svelte 5, Vue 3.5, Fastify 5, Azure Functions v4) +- `johnpapa/angular-styleguide` — Documentation-only style guide (markdown) +- `johnpapa/heroes-angular` — Standard Angular SPA with json-server backend, Cypress, proxy config +- `johnpapa/heroes-vue` — Vue SPA with separate API package, not a monorepo +- `johnpapa/heroes-react` — React SPA (CRA-era) with json-server, proxy, Docker, env files + +## npm packages + +- `johnpapa/lite-server` — Small CLI package (JS, Mocha/Istanbul tests, bin/ entry point) + +## Multi-app collections + +- `johnpapa/hello-worlds` — Angular/React/Svelte/Vue demos, independent apps, no workspace +- `johnpapa/http-interceptors` — Same concept in Angular + Svelte, comparison monorepo + +## VS Code extension variants + +- `johnpapa/vscode-cloak` — Functional extension (TypeScript, webpack, commands + settings) +- `johnpapa/vscode-winteriscoming` — Theme extension (JSON theme files, no runtime code) +- `johnpapa/vscode-angular-snippets` — Snippets extension (JSON snippets, language-scoped, devcontainer) + +## Large open-source library monorepos + +- `langchain-ai/langchain` — Python multi-package monorepo (`libs/*`), pyproject.toml per package, AGENTS.md + CLAUDE.md +- `langchain-ai/langchainjs` — TypeScript monorepo (pnpm + Turborepo + Changesets), workspace packages under `libs/` +- `langchain4j/langchain4j` — Java Maven aggregator with 30+ modules, JDK-conditional builds, Spotless formatting + +## Real-world field tests + +- `FritzAndFriends/BlazorWebFormsComponents` — .NET multi-target library (Blazor, C#) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..b1ae493 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,32 @@ +name: CI + +on: + pull_request: + paths-ignore: + - '**.md' + - '.github/skills/**' + - '.github/agents/**' + push: + branches: + - main + paths-ignore: + - '**.md' + - '.github/skills/**' + - '.github/agents/**' + +permissions: + contents: read + +jobs: + shellcheck: + name: ShellCheck bash scripts + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 + with: + fetch-depth: 1 + + - name: Run ShellCheck on all .sh scripts + run: | + set -euo pipefail + find . -type f -name '*.sh' -print0 | xargs -0 shellcheck diff --git a/.github/workflows/copilot-setup-steps.yml b/.github/workflows/copilot-setup-steps.yml new file mode 100644 index 0000000..4b4f38c --- /dev/null +++ b/.github/workflows/copilot-setup-steps.yml @@ -0,0 +1,23 @@ +name: Copilot Setup Steps + +# This workflow lets Copilot's cloud coding agent pre-install tooling before +# starting a task. See https://docs.github.com/copilot/customizing-copilot/customizing-the-development-environment-for-copilot-coding-agent +on: + workflow_dispatch: + push: + paths: + - .github/workflows/copilot-setup-steps.yml + pull_request: + paths: + - .github/workflows/copilot-setup-steps.yml + +jobs: + copilot-setup-steps: + runs-on: ubuntu-latest + permissions: + contents: read + steps: + - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 + + - name: Install ShellCheck + run: sudo apt-get update && sudo apt-get install -y shellcheck diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..0297939 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,79 @@ +# AGENTS.md + +## Project Overview + +`plesk-scripts` is a collection of independent, standalone automation scripts for Plesk server administration (MySQL backups, WordPress backup cleanup, PCI-DSS header scanning, WordPress malware scanning, ASP.NET hosting monitoring). There is no shared runtime, package manager, or build system — every top-level folder is a self-contained tool with platform-specific implementations (`.bat` for Windows, `.sh` for Linux). See `.github/copilot-instructions.md` for the full architecture, per-script feature breakdown, and coding conventions. + +## Repository Structure + +``` +mysql-backups/ MySQL backup automation (Windows + Linux) +remove-old-wordpress-backups/ WordPress backup retention cleanup (Linux) +pci-dss-scan/ PCI-DSS security header compliance scanner (Windows + Linux) +essential-plugin-malware-scan/ WordPress supply-chain backdoor scanner (Linux only) +monitor-domain-hosting/ ASP.NET hosting setting monitor + email alerts (Windows only) +.github/instructions/ Path-scoped Copilot instructions (shell, PowerShell, markdown, security, etc.) +.github/agents/, .github/skills/ Custom Copilot agents and skills +README.md User-facing docs — must stay in sync with script features +``` + +## Tech Stack + +- **Linux**: Bash (`.sh`), targeting Plesk Obsidian's `/usr/sbin/plesk` CLI and MySQL client tools. +- **Windows**: Batch (`.bat`), targeting `%plesk_dir%` and `mysql.exe`. +- No package manager, no dependency manifest, no build step — scripts run directly. + +## Build & Run + +There is no install/build step. Run a script directly: + +```bash +./mysql-backups/mysql-backup.sh +``` + +```batch +mysql-backups\mysql-backup.bat +``` + +Most Linux scripts support `AUTO_UPDATE=true` and manual `--update`/`--self-update` flags for self-updating from GitHub (see the self-update pattern in `.github/copilot-instructions.md`). + +## Testing + +No automated test suite. Validation is manual: + +- Lint every changed bash script: `shellcheck path/to/script.sh` +- Test in a staging/dev Plesk environment before merging — many scripts assume Plesk CLI/MySQL credentials are present. +- For Windows scripts, test with paths containing spaces and parentheses (e.g. `C:\Program Files (x86)\Plesk`). +- See `.github/copilot-instructions.md` → **Testing & Validation** for the full manual checklist (missing credentials, empty DB lists, concurrent runs, permission checks). + +## Key Patterns and Conventions + +- **Platform parity**: paired `.bat`/`.sh` scripts must both be updated when a feature changes (single-platform scripts like `essential-plugin-scan.sh` and `monitor-aspnet.bat` are exempt). +- **Self-update block**: every Linux bash script embeds the self-update functions immediately after `set -euo pipefail` (see `.github/copilot-instructions.md` for the full template) — update `SCRIPT_RELATIVE_PATH` and `UPDATE_CHECK_FILE` per script. +- **PID locking**: long-running Linux scripts (e.g. `mysql-backup.sh`) use a PID file + `trap ... EXIT` to prevent concurrent runs. +- **Security**: never hardcode credentials — Windows scripts use a `` placeholder; Linux scripts use Plesk's `plesk db` command; backups use `umask 077`. +- **System DB exclusion**: MySQL scripts always filter `information_schema`, `performance_schema`, `phpmyadmin`. + +## CI/CD + +No CI currently existed prior to this change — see `.github/workflows/ci.yml` (shellcheck on changed `.sh` files) added alongside this file. + +## Adding a New Script + +1. Create a new top-level folder named after the task. +2. Add `.sh` (with the self-update block) and/or `.bat` implementation per the platform-parity rule above. +3. Update `README.md`'s Features section and Scripts table. +4. Update `.github/copilot-instructions.md` if the new script introduces a new convention (env vars, auth pattern, etc.). +5. Run `shellcheck` on any new bash script. + +## Documentation + +No `docs/` site — `README.md` plus `.github/copilot-instructions.md` are the complete documentation for this repo; a dedicated docs site is not needed for a script collection of this size. + +## Common Pitfalls + +- Forgetting delayed expansion (`!VAR!`) in batch scripts breaks on Plesk's default path with parentheses. +- Adding a feature to only one side of a `.bat`/`.sh` pair. +- Committing real MySQL/SMTP passwords instead of placeholders. +- Forgetting `trap "rm -f ${PIDFILE}" EXIT`, leaving stale PID locks. +- Skipping the README update after a feature change. diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..25bf23d --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,53 @@ +# Changelog + +All notable changes to this project are documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). +This project does not follow semantic versioning (it is a script collection, not a versioned package). + +## [Unreleased] + +### Added + +- `AGENTS.md`, maintenance matrix, CI workflow, issue/PR templates, and this changelog (AI-ready repo setup). + +## 2026-04-26 + +### Added + +- Monitoring script for domain hosting settings (ASP.NET) with email alerts (`monitor-domain-hosting/`). +- Security review references; enhanced MySQL backup scripts. + +## 2026-04-22 + +### Added + +- Essential Plugin supply-chain attack scanner for WordPress (`essential-plugin-malware-scan/`). +- Plain-text email report output for the scanner. + +## 2026-03-15 + +### Changed + +- PCI-DSS scanner improvements (`pci-dss-scan/`). + +## 2026-03-01 + +### Added + +- PCI-DSS security header compliance scanner for Windows and Linux (`pci-dss-scan/`). + +## 2025-11-01 + +### Added + +- Dry-run mode for the WordPress backup cleanup script. +- Self-update functionality for MySQL and WordPress backup scripts. +- Comprehensive GitHub Copilot documentation for Plesk scripts. + +## 2022-12-31 and earlier + +### Added + +- Initial `mysql-backup.sh` and `mysql-backup.bat` scripts. +- Initial `remove-wordpress-backup` script. From ca5945a0879e7242f5eabe9c1f22e00a92c70a36 Mon Sep 17 00:00:00 2001 From: Patrick Lewis <4015312+locus313@users.noreply.github.com> Date: Fri, 31 Jul 2026 12:15:22 -0700 Subject: [PATCH 2/2] Fix CI: use shellcheck --severity=warning Default severity (style/info) failed on pre-existing SC2086/SC2317 info-level nits in scripts unrelated to this PR. Failing only on warning+ keeps CI meaningful without requiring an unrelated cleanup of every existing script as part of this PR. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .github/workflows/ci.yml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index b1ae493..f65f57a 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -29,4 +29,5 @@ jobs: - name: Run ShellCheck on all .sh scripts run: | set -euo pipefail - find . -type f -name '*.sh' -print0 | xargs -0 shellcheck + # severity=warning: fail on real bugs, not pre-existing style/info nits (SC2086, SC2317) + find . -type f -name '*.sh' -print0 | xargs -0 shellcheck --severity=warning