From c35e2e9a3b0d63f0aa040a790fd46036b266ea28 Mon Sep 17 00:00:00 2001 From: Renan Barreto Date: Tue, 7 Jul 2026 01:50:08 -0300 Subject: [PATCH] Consolidate rules into CLAUDE.md and fix broken paths Migrate from .agents/ to .claude/ as the single skills/rules home: - Fold the four .claude/rules/*.md files into CLAUDE.md as compact sections (Writing Style, PyPI Packaging, Worktree Map) and delete the rules/ folder to simplify the project. - Fix every stale .agents/... path in CLAUDE.md to .claude/... - Remove references to non-existent AGENTS.md symlink and MEMORY.md. - Add missing modules (gui.py, gui/) to the worktree map. - Fix the html-report-builder template path to its real location under .claude/skills/html-report-builder/assets/. - Trim and tighten all skill SKILL.md files: drop duplicated checklists, inline HTML templates, and redundant guidance. - Net reduction of ~234 lines while keeping all substance. --- .agents/rules/pypi-project-guidelines.md | 31 ---- .agents/rules/tmp-usage.md | 11 -- .agents/rules/worktree.md | 42 ----- .agents/rules/writing-style.md | 33 ---- .agents/skills/html-report-builder/SKILL.md | 155 ---------------- .agents/skills/pr-and-commit-writing/SKILL.md | 169 ------------------ .agents/skills/related-project-add/SKILL.md | 130 -------------- .agents/skills/running-unit-tests/SKILL.md | 48 ----- .claude | 1 - .claude/skills/html-report-builder/SKILL.md | 110 ++++++++++++ .../assets/report-template.html | 0 .claude/skills/pr-and-commit-writing/SKILL.md | 106 +++++++++++ .claude/skills/related-project-add/SKILL.md | 87 +++++++++ .../skills/related-projects-index/SKILL.md | 76 ++++---- .../references/goodle.md | 0 .../references/kstuff-lite.md | 0 .../references/liborbispkg-wiki.md | 0 .../references/liborbispkg.md | 0 .../references/oodle-kraken-tools.md | 0 .../references/pkg-passcode-finder.md | 0 .../references/pkgtool.md | 0 .../references/ps5-game-compressor.md | 0 .../references/psdevwiki-pfs.md | 0 .../references/psdevwiki-pkg-files.md | 0 .../references/shadowmountplus.md | 0 .../references/shadpkg-howworks.md | 0 .../references/tlou-psarc-tool.md | 0 .../references/wololo-fpkg-flatz.md | 0 .claude/skills/running-unit-tests/SKILL.md | 35 ++++ .pi | 1 - AGENTS.md | 38 ---- CLAUDE.md | 84 ++++++++- 32 files changed, 460 insertions(+), 697 deletions(-) delete mode 100644 .agents/rules/pypi-project-guidelines.md delete mode 100644 .agents/rules/tmp-usage.md delete mode 100644 .agents/rules/worktree.md delete mode 100644 .agents/rules/writing-style.md delete mode 100644 .agents/skills/html-report-builder/SKILL.md delete mode 100644 .agents/skills/pr-and-commit-writing/SKILL.md delete mode 100644 .agents/skills/related-project-add/SKILL.md delete mode 100644 .agents/skills/running-unit-tests/SKILL.md delete mode 120000 .claude create mode 100644 .claude/skills/html-report-builder/SKILL.md rename {.agents => .claude}/skills/html-report-builder/assets/report-template.html (100%) create mode 100644 .claude/skills/pr-and-commit-writing/SKILL.md create mode 100644 .claude/skills/related-project-add/SKILL.md rename {.agents => .claude}/skills/related-projects-index/SKILL.md (57%) rename {.agents => .claude}/skills/related-projects-index/references/goodle.md (100%) rename {.agents => .claude}/skills/related-projects-index/references/kstuff-lite.md (100%) rename {.agents => .claude}/skills/related-projects-index/references/liborbispkg-wiki.md (100%) rename {.agents => .claude}/skills/related-projects-index/references/liborbispkg.md (100%) rename {.agents => .claude}/skills/related-projects-index/references/oodle-kraken-tools.md (100%) rename {.agents => .claude}/skills/related-projects-index/references/pkg-passcode-finder.md (100%) rename {.agents => .claude}/skills/related-projects-index/references/pkgtool.md (100%) rename {.agents => .claude}/skills/related-projects-index/references/ps5-game-compressor.md (100%) rename {.agents => .claude}/skills/related-projects-index/references/psdevwiki-pfs.md (100%) rename {.agents => .claude}/skills/related-projects-index/references/psdevwiki-pkg-files.md (100%) rename {.agents => .claude}/skills/related-projects-index/references/shadowmountplus.md (100%) rename {.agents => .claude}/skills/related-projects-index/references/shadpkg-howworks.md (100%) rename {.agents => .claude}/skills/related-projects-index/references/tlou-psarc-tool.md (100%) rename {.agents => .claude}/skills/related-projects-index/references/wololo-fpkg-flatz.md (100%) create mode 100644 .claude/skills/running-unit-tests/SKILL.md delete mode 120000 .pi delete mode 100644 AGENTS.md mode change 120000 => 100644 CLAUDE.md diff --git a/.agents/rules/pypi-project-guidelines.md b/.agents/rules/pypi-project-guidelines.md deleted file mode 100644 index 2af438c..0000000 --- a/.agents/rules/pypi-project-guidelines.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -name: PyPI packaging guidelines -description: Practical checklist for publishing a good Python library to PyPI -type: reference ---- - -Use `pyproject.toml` as the primary source of packaging metadata. - -Keep core metadata explicit: name, version, supported Python versions, runtime dependencies, license, README, keywords, classifiers, and project URLs. - -Build and publish both source distributions and wheels. - -Prefer a package directory layout for multi-file libraries. - -Keep dependency groups separate from runtime dependencies when possible. - -For a small pure-Python library, keep metadata centralized, document the project clearly in the README, and ensure the README renders safely on PyPI. - -## README guidance - -Use a supported format: Markdown, reStructuredText, or plain text. - -Keep the README at the repository root and use it as the long description. - -Make the content renderer-safe for PyPI and validate builds before publishing. - -## Repo-specific notes - -- Package name: `mkpfs`; CLI entrypoint defined in pyproject. -- Keep README command reference aligned with CLI surface: `pack`, `verify`, `inspect`, `tree`, `unpack`. -- Validate release artifacts with `uv build` and `uv run --frozen twine check dist/*` before publishing. diff --git a/.agents/rules/tmp-usage.md b/.agents/rules/tmp-usage.md deleted file mode 100644 index ddbd1bd..0000000 --- a/.agents/rules/tmp-usage.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -name: Temporary workspace usage -description: Guidance for using ./tmp for scratch files, planning, and generated artifacts -type: reference ---- - -Use `./tmp/` for transient work only: planning notes, scratch files, ad hoc exports, generated reports, and other temporary artifacts. -Keep one-off filenames descriptive enough to find later, but never rely on anything in `./tmp/` as permanent project state. -Do not commit files from `./tmp/`. -If a task needs a temporary helper script or intermediate output, put it under `./tmp/` and delete it when the work is done. -Create a subfolder for each task/topic like `./tmp//`. diff --git a/.agents/rules/worktree.md b/.agents/rules/worktree.md deleted file mode 100644 index c8a4de1..0000000 --- a/.agents/rules/worktree.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -name: worktree -description: 2-level repository map for fast agent navigation -type: reference ---- - -# Worktree map (2 levels) - -Quick navigation map for agents. Two levels deep with short descriptions. - -- README.md — project overview, install/usage, command reference -- CLAUDE.md — development rules and workflows (AGENTS.md symlink points here) -- .claude/ - - MEMORY.md — unique pointers and links to rules/skills - - rules/ — coding/writing rules and usage guides (this file lives here) - - skills/ - - related-projects-index/ — executive index of external sources; references/*.md with deep notes - - related-project-add/ — skill to add/index a new related project entry - - pr-and-commit-writing/ — commit/PR message writer skill - - running-unit-tests/ — quick local test runner guidance - - html-report-builder/ — build HTML test/report artifacts -- mkpfs/ - - __main__.py — entry point (python -m mkpfs) - - cli.py — CLI wiring (build_cli, cmd_*) - - pfs.py — core PFS build/verify/inspect logic - - exfat.py, exfat_writer.py — exFAT reader/writer - - ampr.py — APR Emu index and helpers - - pbar.py — progress bar, scan/tree utilities - - utils.py — shared helpers - - consts.py — constants used across modules - - _exfat_upcase.py — exFAT upcase table (generated/static data) - - logging.py — logging setup/utilities -- tests/ - - integration.sh — CLI smoke harness - - mkpfs/ — pytest suite: test_cli.py, test_pfs.py, test_exfat*.py, test_utils.py, etc. -- .github/ - - workflows/ — CI, stale, release-drafter, auto-assign, gitleaks - - labels.yml, release-drafter-config.yml, FUNDING.yml, ISSUE_TEMPLATE/ -- assets/ — project assets (images/docs) -- run-tests.sh — convenience script: ruff format+check, pytest -- pyproject.toml — project metadata, tooling config -- uv.lock — dependency lockfile diff --git a/.agents/rules/writing-style.md b/.agents/rules/writing-style.md deleted file mode 100644 index eef6a9c..0000000 --- a/.agents/rules/writing-style.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -name: writing-style -description: Quick writing guide for README and short Markdown docs -type: project ---- - -# Writing Style (quick guide) - -Keep docs practical, concise, and easy to scan. Prefer bullets over long prose. - -## Tone -- Active voice, present tense. Short paragraphs, short sentences. -- Factual, no hype. Explain what it does and how to use it. - -## Examples -- Show one example per command; avoid exhaustive flag lists in README. -- Use fenced code blocks with language hints for CLI/code. - -## Formatting -- Use Markdown only; avoid inline HTML except when necessary. -- Reasonable line length (~100 cols for prose). -- Use code font for file names, commands, and flags. - -## Consistency -- Align README claims with pyproject.toml (name, version, Python, license, URLs). -- Link to CONTRIBUTING.md instead of duplicating policy. -- Don’t commit ./tmp/. - -## Skills to use for public text and reports -- Commits/PRs: load .claude/skills/pr-and-commit-writing/SKILL.md when generating commit messages or PR titles/descriptions (public text must follow that skill’s rules). -- HTML reporting: load .claude/skills/html-report-builder/SKILL.md when producing HTML summaries/reports (keeps format consistent and saved under ./tmp/). - -That’s it — keep it simple and useful. diff --git a/.agents/skills/html-report-builder/SKILL.md b/.agents/skills/html-report-builder/SKILL.md deleted file mode 100644 index 7630b1b..0000000 --- a/.agents/skills/html-report-builder/SKILL.md +++ /dev/null @@ -1,155 +0,0 @@ ---- -name: html-report-builder -description: > - Build a self-contained HTML report as a companion artifact for audits, verifications, research, or long multi-command - investigations. Always send a concise chat answer first, then save the HTML report under ./tmp/ and include a - clickable path in chat. Triggers: "report", "audit", "check", "verify", "findings", "summary". -metadata: - context: fork ---- - -# Report builder (HTML companion) - -Use this skill when the user asks for a report, audit, verification/check, research write‑up, -long-form findings, or when multi-step commands would benefit from a browsable artifact. -The skill produces two outputs: - -1. A concise chat response (always first) -2. A companion, self-contained HTML5 report saved under ./tmp/ with a clickable path in chat - -## Workflow - -1. Answer briefly in chat with the key outcome(s). -2. Generate/update the HTML report under ./tmp/ using a descriptive filename pattern: - - tmp/-report-YYYYMMDD-HHMMSS.html (example: tmp/verify-tests-report-20260514-102530.html) -3. Include a markdown link to the file path in your chat reply: ./tmp/....html -4. During long investigations, update the report incrementally to reflect progress. - -## Report structure (sections) - -- Title and timestamp -- Executive summary (1–3 sentences) -- Context (why this report exists) -- Findings (bullet points with supporting data) -- Commands run (exact commands) -- Evidence (selected logs/test output; truncate if huge and note truncation) -- Recommendations (clear next steps) -- References (clickable links to sources, tickets, docs) - -## Presentation - -- Keep the file self-contained (inline CSS only; no external assets) and UTF‑8 encoded. -- Default theme: dark blue background, white text, clean layout. Emojis (✅/❌) allowed for quick status cues. -- Add a simple progress bar when useful (see template below). - -## Safety and repo hygiene - -- Save only under ./tmp/. -- Do not commit files from ./tmp/. -- Never include secrets/credentials or large binary dumps. For long logs, write the full log to - a separate ./tmp/*.log file and link to it from the report; include only short excerpts inline. - -## Validation checklist (pre-publish) - -Use this checklist before linking the report in chat: - -- [ ] Sent a concise chat answer first (key outcomes, link follows) -- [ ] Report saved under ./tmp/ using -report-YYYYMMDD-HHMMSS.html -- [ ] Title includes the task and a human-readable timestamp -- [ ] Executive summary (1–3 sentences) is present and accurate -- [ ] Sections included and populated: - - [ ] Context (why the report exists) - - [ ] Findings (bullet points with supporting data) - - [ ] Commands run (exact commands) - - [ ] Evidence (short excerpts); note any truncation and link full logs in ./tmp/*.log - - [ ] Recommendations (clear next steps with owners if known) - - [ ] References (clickable URLs and/or local ./tmp files) -- [ ] Progress bar included when investigation was multi-step or long-running -- [ ] No secrets/PII/sensitive credentials present; redact if needed -- [ ] Large outputs/logs truncated in-page; full logs saved separately in ./tmp and linked -- [ ] Self-contained HTML (inline CSS only), UTF-8 encoded; code blocks readable -- [ ] Clickable filesystem path included in the chat message to the report (and any log files) -- [ ] All links/paths tested and resolve correctly -- [ ] If using assets/report-template.html, replaced placeholders ([TASK], [TIMESTAMP], [PROGRESS%], etc.) -- [ ] Files in ./tmp/ are not committed to git - -## Minimal HTML template - -You can start from assets/report-template.html when you need a fuller starting point. - -```html - - - - - - [TASK] Report — 2026-05-14 10:25 - - - -
-

🔎 [TASK] Report 2026-05-14 10:25

-

Context: Briefly state why this report was generated.

- -

Executive summary

-

1–3 sentences with the key outcome(s). ✅ Passed X checks. ❌ Found Y issues.

- -

Progress

-
- -

Findings

-
    -
  • Finding 1 — short statement with supporting data.
    • -
  • Finding 2 — short statement with supporting data.
    • -
- -

Commands run

- 
$ command one --flag
-[trimmed output]
-
-$ command two
-[trimmed output]
- -

Evidence (selected excerpts)

- 
[short log/test output excerpts]
-[Note: full logs saved to ./tmp/XYZ.log]
- -

Recommendations

-
    -
  1. Specific next step 1
    2. -
  2. Specific next step 2
    3. -
- -

References

- -
- - -``` - -## Minimal examples - -- Filename convention: tmp/-report-YYYYMMDD-HHMMSS.html -- Open locally (macOS/Linux): `open ./tmp/.html` or `xdg-open ./tmp/.html` - -Do not replace the chat response with the HTML. The HTML is a companion artifact only and should not hold the only copy of crucial information. diff --git a/.agents/skills/pr-and-commit-writing/SKILL.md b/.agents/skills/pr-and-commit-writing/SKILL.md deleted file mode 100644 index dee77dc..0000000 --- a/.agents/skills/pr-and-commit-writing/SKILL.md +++ /dev/null @@ -1,169 +0,0 @@ ---- -name: pr-and-commit-writing -description: > - Write commit messages, PR titles/descriptions, and GitHub comments with a user-first style; apply - release-drafter-compatible labels; produce release-note-ready PR titles. -context: fork ---- - -# Writing PRs, commit messages, and GitHub comments - -Use this skill whenever you need to: -- create or edit a pull request -- write a public commit message -- write or edit a GitHub comment that other people will read -- assign labels or tags to a PR - -## Goal - -Write public-facing GitHub content for non-technical readers first. - -Keep everything: -- short -- friendly -- easy to scan -- focused on the user problem that was solved - -## Commit message rules - -1. Use a short, natural-language title (≤50 chars). Emoji allowed but optional. -2. Focus on the user-facing problem solved; avoid deep implementation details. -3. Leave a blank line between the title and the body. -4. Optional body: keep concise (wrap ~72 cols) and include the user-visible problem and the high-level change. - -Example: - -```text -Avoid broken inner filenames by removing special characters - -Some consoles could not mount images when inner filenames had special characters. -This change sanitizes the internal filename, prefers title IDs, and warns when names are changed. -Verification still works even when external and internal names differ. -``` - -## PR title rules - -1. One short sentence (≤72 chars), plain language, user-facing. -2. Describe the problem solved or user impact; avoid deep implementation details. -3. No Conventional Commit prefixes (no `feat:`, `fix:`, etc.). -4. Titles should paste directly into release notes. - -Good examples: -- `Fix inner image names that break mounts` -- `Make single-file image names safer` -- `Avoid mount failures caused by special characters in inner image names` -- `Update the documentation about the verify command` - - -## PR description rules - -Use UTF-8 icons and Markdown. - -Recommended structure: - -```md -# Fix inner image names that break mounts - -## 🤔 Why? -- Explain the user-visible problem in plain language. - -## 🔧 What changed -- 3-5 short bullets. -- Focus on behavior, not internal code structure. - -## 🧪 How to test -- One short command or simple manual flow. -- Link related issues (e.g., Closes #123). - -## 💬 Notes for non-technical readers -- Reassure the reader what changed and what did not change. -``` - -### Example Pull Request description - -```md -# Fix inner image names that break mounts - -## 🤔 Why? -- Some consoles could not mount single-file images when the inner filename had special characters. - -## 🔧 What changed -- The inner filename is now cleaned automatically by default. -- PlayStation title IDs like `CUSA` and `PPSA` are preferred when found. -- A short warning is shown when the inner filename is renamed. -- Verification still works even when the external and internal file names differ. - -## 🧪 How to test -- Pack a single file with special characters and run `mkpfs verify --source-file`. - -## 💬 Notes for non-technical readers -- This improves compatibility. -- The file contents do not change, only the internal filename is adjusted. -``` - -### General Writing guidance - -- Use emoji lightly for scanning: ✅ 🔧 🧪 🤔 💬 ⚠️ 📦 -- Keep paragraphs short. -- Use bullets over dense prose. -- Speak like you are updating a non-technical maintainer. -- Always mention the original problem clearly in the **Why?** section. -- If the change is user-visible, lead with the user impact. -- If the contents are unchanged and only metadata or filenames changed, say that explicitly. -- Do not mention you are an AI or attribute the text edits or anything to any AI tool like Claude or OpenClaude. -- Clean up any personal information or internal details like local file paths, usernames, or PII. - -## Labels and tags - -Use labels that fit the release drafter config in `.github/release-drafter-config.yml`. - -### Labels, pick one primary -- `feature` -- `bug` -- `maintenance` -- `documentation` -- `dependencies` -- `security` -- `breaking` - -### Other labels -- `skip-changelog` only when the PR should not appear in release notes -- Area or workflow labels are fine if the repo uses them, but the main release label should stay compatible with release drafter - -### Mapping guidance -- User-visible fix: `bug` -- New user-facing capability: `feature` -- Documentation-only change: `documentation` -- Cleanup, tooling, refactor, or maintenance work: `maintenance` -- Dependency update: `dependencies` -- Security fix: `security` -- Breaking change: `breaking` - -Choose labels based on the user impact first, then the implementation details. - -## GitHub CLI notes - -When editing PRs with `gh`, prefer: -- `gh pr edit ...` -- `gh pr create ...` -- `GH_PAGER=cat gh pr edit --add-label "bug"` -- `GH_PAGER=cat gh pr edit --add-label "skip-changelog"` - -## Gotchas -- PR titles: plain sentence, no emoji, no Conventional Commit prefixes; release-note ready. -- Use repo-standard labels so release drafter categorizes the PR correctly. -- Avoid PII, local paths, or internal-only details in public text. - -## Final checklist - -Before publishing a commit message, PR body, or comment, check: -- Is the PR title release-note ready (plain sentence, ≤72 chars, no CC prefixes, no emoji)? -- Does the text explain the problem first? -- Is there a clear **Why?** section for PRs? -- Are there UTF-8 icons in the PR description (lightly used)? -- Is the language understandable to a non-technical reader? -- Did you apply the correct `type:` label and `skip-changelog` if needed? -- Did you link related issues (e.g., Closes #123)? -- Did you avoid mentioning any AI tools? -- After editing with `gh`, did you re-read the final published PR title/body and confirm it still matches this skill instead of a generic Markdown template? -- If a repository instruction says to use this skill for PR text, did you follow the full structure here rather than only invoking the skill tool? diff --git a/.agents/skills/related-project-add/SKILL.md b/.agents/skills/related-project-add/SKILL.md deleted file mode 100644 index dee191d..0000000 --- a/.agents/skills/related-project-add/SKILL.md +++ /dev/null @@ -1,130 +0,0 @@ ---- -name: related-project-add -description: > - Add a new related project or reference source to the Related Projects index. Investigate the upstream repo/website, - write an executive-summary reference file under references/, and update the index SKILL.md with a concise entry. -context: fork ---- - -# Add a related project to the index - -Use this skill when the user asks to add a new external project or reference page (GitHub repo, wiki page, website) -into our Related Projects index. - -Goal -- Create a high-signal reference file under .claude/skills/related-projects-index/references/ with upstream links only. -- Append a matching executive-summary entry to .claude/skills/related-projects-index/SKILL.md. - -Inputs you need -- Upstream URL (GitHub repo, GitHub wiki page, PSDevWiki page, technical blog, etc.) -- Optional: short display name override (defaults to repo or site name) -- Optional: category hint (tooling, wiki, kernel/payload, filesystem format, crypto) - -Workflow (do this step-by-step) -1) Identify and scope the target -- Determine if it is: GitHub repository, GitHub wiki, standalone site/page, or multi-page domain. -- Decide a short name and a slug: - - slug = lowercase kebab-case (letters, digits, hyphens), usually from repo or page title (e.g., liborbispkg, psdevwiki-pfs). - -2) Investigate upstream and extract facts -- For GitHub repos: - - Read README, top-level structure, and key source files/dirs. - - Clone the repository into a temporary folder and investigate its source code. - - Identify important modules, commands, and any tests or templates that prove behavior. -- For websites/wikis: - - Read the specific page(s); capture the strongest claims, structure/format insights, and how to use it with our work. -- Use tools: - - web_fetch on the URL for readable content; follow repo links as needed. - - Optionally web_search to find the canonical page if the provided URL looks non-canonical. - -3) Draft the executive summary (3–6 bullets) -- What it is (1 line). -- Why it is relevant to PKG/PFS/exFAT/mounting/crypto/workflows. -- 1–3 key technical points or behaviors (format structure, mount options, key derivation, performance, constraints). -- Optional gotchas/limits. - -4) Write the reference file -- Path: .claude/skills/related-projects-index/references/.md -- Structure template: - - ```md - # — Reference - - Upstream: - - Executive summary - - - - - - - - Why it matters - - - - Key upstream files/pages - - — - - ... - - Notes / gotchas - - - - Source index - - - ``` - -- Rules: - - Link to upstream only (no local mirror paths). - - Keep it compact but complete enough for quick research. - - Cite exact files/paths where possible (blob/main, wiki page permalinks, named sections). - -5) Update the index SKILL with a new entry -- File: .claude/skills/related-projects-index/SKILL.md -- Insert a new section following the existing style, for example: - - ```md - ## - - What it is: - - Relevance: - - Gotchas: - - Upstream: - - Internal reference: references/.md - ``` - -- Place the new entry near similar items (e.g., tools with tools, wikis with wikis). If unclear, add at the end of the list. - -6) Validate -- All links open and are upstream (no related-projects/* references). -- Reference file exists and has the structure above. -- Index SKILL.md was updated with the correct Internal reference path (references/.md). - -7) Commit/PR hygiene (if requested) -- If the user asks to commit, use the pr-and-commit-writing skill for public text. - -Naming conventions and grouping -- Slug: lowercase kebab-case, derived from repo/page (e.g., shadowmountplus, pkgtool, liborbispkg, psdevwiki-pfs). -- Multi-page domains (e.g., PSDevWiki): create one reference file per high-value page (psdevwiki-pfs.md, psdevwiki-pkg-files.md) and add separate index entries, mirroring how we handle PSDevWiki and ShadPKG. - -Safety and repo hygiene -- Do not create or reference local mirrors. -- Keep long quotes minimal; link upstream for details. -- Do not modify non-skill areas of the repo unless explicitly asked. - -Common pitfalls and guardrails -- Never edit README.md or public docs when using this skill; only modify files under .claude/skills/related-projects-index/* -- Prefer canonical upstream URLs (original repo/site), avoid forks unless canonicalized in the README -- Validate that references/.md follows the template and links upstream only -- Place the new index entry near similar tools (e.g., after ShadowMountPlus for mounting/compression utilities) - -Minimal example usage -- Input: https://github.com/example/repo -- Output files: - - .claude/skills/related-projects-index/references/example-repo.md (new) - - .claude/skills/related-projects-index/SKILL.md (appended index entry) - -Checklist before finishing -- [ ] Upstream link(s) verified -- [ ] Concise executive summary written (3–6 bullets) -- [ ] Clear “why it matters” mapped to MkPFS/PKG/PFS/exFAT scope -- [ ] Key files/pages cited with stable paths -- [ ] Gotchas/limits captured (if any) -- [ ] Index SKILL updated with Internal reference path -- [ ] No references to deleted related-projects/* diff --git a/.agents/skills/running-unit-tests/SKILL.md b/.agents/skills/running-unit-tests/SKILL.md deleted file mode 100644 index ef8fe48..0000000 --- a/.agents/skills/running-unit-tests/SKILL.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -name: running-unit-tests -description: > - Run formatting, linting, and tests; then iteratively fix failures until the branch is green. - Use this after implementing a feature or fixing a bug to get the branch ready to push. - Triggers: "tests", "run tests", "lint", "format", "CI red", "fix failing tests". -context: fork ---- - -# Running and Fixing Tests - -Always run `./run-tests.sh` at the end of each feature, bug fix, or refactor to ensure the branch is ready to push. -This script runs all pre-commit hooks and the full test suite, and it will fail if any issues are found. - -These are the steps to follow when you run into test failures: - -1. Inspect what changed. - - Run `git status --short` to see modified files. - - Review diffs with `git diff --stat` and `git diff` to understand the scope of changes. - -2. Run the project test/validation flow. - - Preferred: run `./run-tests.sh`. - - Ensures the virtualenv is active. - - Runs `uv sync` to keep dependencies in sync. - - Installs pre-commit hooks (`uv run pre-commit install --overwrite`). - - Formats code with `uv run ruff format .`. - - Runs linting and auto-fixes with `uv run ruff check . --fix`. - - Runs the full test suite with `uv run --frozen pytest`. - - Optional: run pre-commit checks explicitly with `uv run --frozen pre-commit run --all-files` if you want to see hook results directly. - - Lightweight option (tests only): `uv run --frozen pytest`. - -3. Loop until clean. - - Group related failures by root cause (e.g., one bug vs. multiple independent issues). - - Apply minimal, readable fixes that keep behavior stable unless tests show the behavior is incorrect. - - Add or update focused tests for each bug fix. - - Re-run `./run-tests.sh` (or `uv run --frozen pytest` for a quicker cycle) after each batch of fixes. - -4. Final readiness check. - - Confirm `./run-tests.sh` completes successfully with no failures. - - Optionally re-run `uv run --frozen pre-commit run --all-files` to catch any hook-specific issues. - - Summarize what was fixed and list any remaining risks or follow-ups before push. - -## Tips and setup notes - -- First time setup: if `.venv/` does not exist, run `uv sync` once to create it, or run `./run-tests.sh` after creating `.venv` manually. -- Using a different virtualenv: set `SKIP_VENV=1` before running the script and ensure `python3` resolves to the desired environment. -- Faster loops: during debugging, run `uv run --frozen pytest -k -q` to target specific tests, then finish with a full `./run-tests.sh` run. - diff --git a/.claude b/.claude deleted file mode 120000 index c0ca468..0000000 --- a/.claude +++ /dev/null @@ -1 +0,0 @@ -.agents \ No newline at end of file diff --git a/.claude/skills/html-report-builder/SKILL.md b/.claude/skills/html-report-builder/SKILL.md new file mode 100644 index 0000000..254954d --- /dev/null +++ b/.claude/skills/html-report-builder/SKILL.md @@ -0,0 +1,110 @@ +--- +name: html-report-builder +description: > + Build a self-contained HTML report as a companion artifact for audits, verifications, research, or long multi-command + investigations. Always send a concise chat answer first, then save the HTML report under ./tmp/ and include a + clickable path in chat. Triggers: "report", "audit", "check", "verify", "findings", "summary". +context: fork +--- + +# Report builder (HTML companion) + +Use when the user asks for a report, audit, verification/check, research write‑up, +long-form findings, or when multi-step commands would benefit from a browsable artifact. +Produces two outputs: (1) a concise chat response (always first), (2) a self-contained +HTML5 report saved under `./tmp/` with a clickable path in chat. + +## Workflow + +1. Answer briefly in chat with the key outcome(s). +2. Save the HTML report under `./tmp/` as `tmp/-report-YYYYMMDD-HHMMSS.html`. +3. Include a markdown link to the file path in your chat reply. +4. During long investigations, update the report incrementally. + +## Report structure + +- Title and timestamp +- Executive summary (1–3 sentences) +- Context (why this report exists) +- Findings (bullets with supporting data) +- Commands run (exact commands) +- Evidence (selected logs/test output; truncate if huge, note truncation, link full logs in `./tmp/*.log`) +- Recommendations (clear next steps) +- References (clickable links) + +## Presentation + +- Self-contained: inline CSS only, no external assets, UTF‑8 encoded. +- Default theme: dark blue background, white text. Emojis (✅/❌) for quick status cues. +- Add a progress bar when useful (see template). + +## Safety and repo hygiene + +- Save only under `./tmp/`. Do not commit files from `./tmp/`. +- Never include secrets/credentials or large binary dumps. Write full logs to `./tmp/*.log` and link. + +## Validation checklist (pre-publish) + +- [ ] Sent a concise chat answer first +- [ ] Report saved under `./tmp/` as `-report-YYYYMMDD-HHMMSS.html` +- [ ] Executive summary present and accurate +- [ ] Sections populated: Context, Findings, Commands run, Evidence, Recommendations, References +- [ ] Progress bar included when multi-step/long-running +- [ ] No secrets/PII; large outputs truncated in-page with full logs in `./tmp/` and linked +- [ ] Self-contained HTML (inline CSS only), UTF‑8, code blocks readable +- [ ] Clickable filesystem path included in chat +- [ ] All links/paths resolve +- [ ] If using `.claude/skills/html-report-builder/assets/report-template.html`, replaced placeholders (`[TASK]`, `[TIMESTAMP]`, `[PROGRESS%]`, etc.) + +## HTML template + +Start from `.claude/skills/html-report-builder/assets/report-template.html` when you need a fuller starting point. +The file lives at that exact path inside this skill folder. + +Minimal inline fallback (dark-blue theme, single-file): + +```html + + + + + + [TASK] Report — [TIMESTAMP] + + + +
+

🔎 [TASK] Report [TIMESTAMP]

+

Context: why this report was generated.

+

Executive summary

+

1–3 sentences with key outcomes. ✅ Passed X. ❌ Found Y.

+

Progress

+
+

Findings

+
  • Finding — short statement with data.
+

Commands run

+ 
$ command --flag
+[trimmed output]
+

Evidence

+ 
[short excerpts; full logs in ./tmp/*.log]
+

Recommendations

+
  1. Specific next step
+

References

+ +
+ + +``` + +Do not replace the chat response with the HTML. The HTML is a companion artifact only. diff --git a/.agents/skills/html-report-builder/assets/report-template.html b/.claude/skills/html-report-builder/assets/report-template.html similarity index 100% rename from .agents/skills/html-report-builder/assets/report-template.html rename to .claude/skills/html-report-builder/assets/report-template.html diff --git a/.claude/skills/pr-and-commit-writing/SKILL.md b/.claude/skills/pr-and-commit-writing/SKILL.md new file mode 100644 index 0000000..ae83b1a --- /dev/null +++ b/.claude/skills/pr-and-commit-writing/SKILL.md @@ -0,0 +1,106 @@ +--- +name: pr-and-commit-writing +description: > + Write commit messages, PR titles/descriptions, and GitHub comments with a user-first style; apply + release-drafter-compatible labels; produce release-note-ready PR titles. +context: fork +--- + +# Writing PRs, commit messages, and GitHub comments + +Use whenever you need to: create/edit a PR, write a public commit message, write/edit a GitHub comment, +or assign labels/tags to a PR. + +## Goal + +Write public-facing GitHub content for non-technical readers first. Keep everything short, friendly, +scannable, and focused on the user problem solved. + +## Commit message rules + +1. Short, natural-language title (≤50 chars). Emoji optional. +2. Focus on the user-facing problem solved; avoid deep implementation details. +3. Blank line between title and body. +4. Optional body: concise (wrap ~72 cols), user-visible problem + high-level change. + +Example: + +```text +Avoid broken inner filenames by removing special characters + +Some consoles could not mount images when inner filenames had special characters. +This change sanitizes the internal filename, prefers title IDs, and warns when names are changed. +Verification still works even when external and internal names differ. +``` + +## PR title rules + +1. One short sentence (≤72 chars), plain language, user-facing. +2. Describe the problem solved or user impact; avoid implementation details. +3. No Conventional Commit prefixes (no `feat:`, `fix:`, etc.). No emoji. +4. Titles should paste directly into release notes. + +Good examples: +- `Fix inner image names that break mounts` +- `Make single-file image names safer` +- `Update the documentation about the verify command` + +## PR description rules + +Use UTF-8 icons and Markdown. + +```md +# Fix inner image names that break mounts + +## 🤔 Why? +- Explain the user-visible problem in plain language. + +## 🔧 What changed +- 3-5 short bullets. Focus on behavior, not internal code structure. + +## 🧪 How to test +- One short command or simple manual flow. +- Link related issues (e.g., Closes #123). + +## 💬 Notes for non-technical readers +- Reassure the reader what changed and what did not change. +``` + +### Writing guidance + +- Use emoji lightly for scanning: ✅ 🔧 🧪 🤔 💬 ⚠️ 📦. +- Bullets over dense prose. Speak like you're updating a non-technical maintainer. +- Always state the original problem clearly in **Why?**. +- If contents are unchanged and only metadata/filenames changed, say so explicitly. +- Never mention AI tools or attribute text to any AI tool. +- Clean up PII, local paths, or internal-only details. + +## Labels and tags + +Use labels that fit `.github/release-drafter-config.yml`. Pick one primary: + +- `feature` — new user-facing capability +- `bug` — user-visible fix +- `maintenance` — cleanup, tooling, refactor +- `documentation` — docs-only change +- `dependencies` — dependency update +- `security` — security fix +- `breaking` — breaking change + +Other: `skip-changelog` only when the PR should not appear in release notes. +Choose based on user impact first, then implementation details. + +## GitHub CLI notes + +- `gh pr edit ...` / `gh pr create ...` +- `GH_PAGER=cat gh pr edit --add-label "bug"` + +## Final checklist + +- [ ] PR title release-note ready (plain sentence, ≤72 chars, no CC prefixes, no emoji) +- [ ] Text explains the problem first; clear **Why?** section for PRs +- [ ] UTF-8 icons used lightly; language understandable to non-technical readers +- [ ] Correct label applied; `skip-changelog` if needed +- [ ] Related issues linked (e.g., Closes #123) +- [ ] No AI attribution; no PII/local paths +- [ ] After editing with `gh`, re-read the published PR to confirm it matches this skill diff --git a/.claude/skills/related-project-add/SKILL.md b/.claude/skills/related-project-add/SKILL.md new file mode 100644 index 0000000..3ecca6b --- /dev/null +++ b/.claude/skills/related-project-add/SKILL.md @@ -0,0 +1,87 @@ +--- +name: related-project-add +description: > + Add a new related project or reference source to the Related Projects index. Investigate the upstream repo/website, + write an executive-summary reference file under references/, and update the index SKILL.md with a concise entry. +context: fork +--- + +# Add a related project to the index + +Use when the user asks to add a new external project or reference page (GitHub repo, wiki page, website) +into our Related Projects index. + +## Goal + +- Create a high-signal reference file under `.claude/skills/related-projects-index/references/` with upstream links only. +- Append a matching executive-summary entry to `.claude/skills/related-projects-index/SKILL.md`. + +## Inputs + +- Upstream URL (GitHub repo, wiki page, PSDevWiki page, technical blog, etc.) +- Optional: short display name override (defaults to repo or site name) +- Optional: category hint (tooling, wiki, kernel/payload, filesystem format, crypto) + +## Workflow + +1. **Identify and scope the target.** Determine if it's a GitHub repo, GitHub wiki, standalone site/page, or multi-page domain. Pick a slug = lowercase kebab-case (letters, digits, hyphens), usually from repo or page title (e.g., `liborbispkg`, `psdevwiki-pfs`). + +2. **Investigate upstream and extract facts.** + - GitHub repos: read README, top-level structure, key source files/dirs; optionally clone into a temp folder to investigate source. Identify important modules, commands, tests/templates that prove behavior. + - Websites/wikis: read the specific page(s); capture strongest claims, structure/format insights, how it applies to our work. + - Tools: `web_fetch` on the URL; optionally `web_search` to find the canonical page if the URL looks non-canonical. + +3. **Draft the executive summary (3–6 bullets):** what it is (1 line), why it's relevant to PKG/PFS/exFAT/mounting/crypto, 1–3 key technical points, optional gotchas/limits. + +4. **Write the reference file** at `.claude/skills/related-projects-index/references/.md`: + + ```md + # — Reference + + Upstream: + + Executive summary + - + - + + Why it matters + - + + Key upstream files/pages + - — + + Notes / gotchas + - + + Source index + - + ``` + + Link upstream only (no local mirror paths). Cite exact files/paths where possible (`blob/main`, wiki permalinks, named sections). Keep compact but complete enough for quick research. + +5. **Update the index SKILL** at `.claude/skills/related-projects-index/SKILL.md`. Insert a new section following the existing style, placed near similar items (tools near tools, wikis near wikis; if unclear, append at the end): + + ```md + ## + - What: + - Relevance: + - Gotchas: + - Upstream: + - Internal: references/.md + ``` + +6. **Validate.** All links open and are upstream (no `related-projects/*` references). Reference file exists with the structure above. Index SKILL.md updated with correct `Internal: references/.md` path. + +7. **Commit/PR hygiene** (if requested): use the `pr-and-commit-writing` skill for public text. + +## Naming and grouping + +- Slug: lowercase kebab-case, derived from repo/page (e.g., `shadowmountplus`, `pkgtool`, `liborbispkg`, `psdevwiki-pfs`). +- Multi-page domains (e.g., PSDevWiki): create one reference file per high-value page (`psdevwiki-pfs.md`, `psdevwiki-pkg-files.md`) and add separate index entries, mirroring how we handle PSDevWiki and ShadPKG. + +## Guardrails + +- Never edit README.md or public docs when using this skill; only modify files under `.claude/skills/related-projects-index/*`. +- No local mirrors. Keep long quotes minimal; link upstream for details. +- Don't modify non-skill areas of the repo unless explicitly asked. +- Prefer canonical upstream URLs (original repo/site); avoid forks unless canonicalized in the README. diff --git a/.agents/skills/related-projects-index/SKILL.md b/.claude/skills/related-projects-index/SKILL.md similarity index 57% rename from .agents/skills/related-projects-index/SKILL.md rename to .claude/skills/related-projects-index/SKILL.md index bdb0b06..e1e17e5 100644 --- a/.agents/skills/related-projects-index/SKILL.md +++ b/.claude/skills/related-projects-index/SKILL.md @@ -11,110 +11,112 @@ context: fork Use this skill whenever you need quick orientation on external projects (code, wikis, tools) that inform PKG/PFS/exFAT behavior or mounting/format details. For deeper research, open the -linked internal reference file or go to the upstream repository/wiki. +linked internal reference file under `references/` in this skill folder, or go upstream. ## How to use + - Start here to find the right project/source fast. -- If you need details, open the linked internal reference file under `references/` in this skill folder. -- When implementation specifics are required, fetch or read from the upstream links. +- For details, open the linked `references/.md` file in this skill folder. +- For implementation specifics, fetch or read from the upstream links. --- ## ShadowMountPlus -- What it is: Auto-detection and mounting tool for images; stages metadata and registers titles. -- Relevance: Shows practical mount flows for UFS/PFS/exFAT, including LVD attach + PFS nmount flags. +- What: Auto-detection and mounting tool for images; stages metadata and registers titles. +- Relevance: Practical mount flows for UFS/PFS/exFAT, including LVD attach + PFS nmount flags. - Gotchas: For PFS, validates mounted block size vs chosen sector size; requires proper image root layout. - Upstream: https://github.com/drakmor/ShadowMountPlus -- Internal reference: references/shadowmountplus.md +- Internal: references/shadowmountplus.md ## PS5 Game Compressor -- What it is: Standalone PS5 payload + web UI to compress, validate/repair, uncompress, and move ShadowMountPlus-mounted games. -- Relevance: Real-console PFSC builder with zlib windowed pipeline (64 KiB blocks) and .vhash per-block SHA‑256; validates MkPFS images under SMP with APR Emu support. +- What: Standalone PS5 payload + web UI to compress, validate/repair, uncompress, and move SMP-mounted games. +- Relevance: Real-console PFSC builder with zlib windowed pipeline (64 KiB blocks) and `.vhash` per-block SHA‑256; validates MkPFS images under SMP with APR Emu support. - Gotchas: Requires ShadowMountPlus and kstuff-lite; default nested exFAT recommended; nested PFS is experimental; destructive mode is risky and constrained. - Upstream: https://github.com/juma-sayeh/PS5-Game-Compressor -- Internal reference: references/ps5-game-compressor.md +- Internal: references/ps5-game-compressor.md ## PKGTool -- What it is: Practical `.pkg` parser/extractor with a partial repack path. +- What: Practical `.pkg` parser/extractor with a partial repack path. - Relevance: Field-tested read path; good for entry table shape and decompression logic. - Gotchas: Writer leaves CRC unimplemented; repack is basename-oriented by default. - Upstream: https://github.com/thesupersonic16/PKGTool -- Internal reference: references/pkgtool.md +- Internal: references/pkgtool.md ## LibOrbisPkg -- What it is: Full PKG/PFS toolkit (library + tools + tests). +- What: Full PKG/PFS toolkit (library + tools + tests). - Relevance: Canonical reference for PFS tree modeling, inode/dirent serialization, flat path table, signed outer image layout, and optional AES-XTS. - Gotchas: PFSC asymmetry; reader handles compressed/direct, writer emits header + full-block map for nested `pfs_image.dat`. - Upstream: https://github.com/maxton/LibOrbisPkg -- Internal reference: references/liborbispkg.md +- Internal: references/liborbispkg.md ## LibOrbisPkg Wiki -- What it is: Orientation wiki for the LibOrbisPkg ecosystem (PkgEditor, PkgTool, library notes). +- What: Orientation wiki for the LibOrbisPkg ecosystem (PkgEditor, PkgTool, library notes). - Relevance: Highest value page is the PKG crypto note (passcode-derived keys, EKPFS, PFS key derivation, ENTRY_KEYS/IMAGE_KEY roles). - Upstream (wiki git): https://github.com/maxton/LibOrbisPkg.wiki.git -- Internal reference: references/liborbispkg-wiki.md +- Internal: references/liborbispkg-wiki.md ## kstuff-lite -- What it is: PS5 payload bundle with loader, kernel hooks, mount automation, and crypto helpers. -- Relevance: Shows practical mount automation for UFS/PFS/exFAT; loader falls back to raw folder path when mount fails. +- What: PS5 payload bundle with loader, kernel hooks, mount automation, and crypto helpers. +- Relevance: Practical mount automation for UFS/PFS/exFAT; loader falls back to raw folder path when mount fails. - Gotchas: `KSTUFF_OBS=1` enables observability/snapshots; crypto focuses on FPKG/FSELF/debug NPDRM. - Upstream: https://github.com/EchoStretch/kstuff-lite -- Internal reference: references/kstuff-lite.md +- Internal: references/kstuff-lite.md ## PSDevWiki — PFS page -- What it is: Community-maintained PFS structure page (headers, inode/dirent, flat_path_table; unsigned baseline spec). +- What: Community-maintained PFS structure page (headers, inode/dirent, flat_path_table; unsigned baseline spec). - Relevance: Field offsets and packing rules MkPFS must honor for mountability; clarifies mode bits (signed/64b/encrypted/case-insensitive) and block size ranges. - Upstream: https://www.psdevwiki.com/ps4/PFS -- Internal reference: references/psdevwiki-pfs.md +- Internal: references/psdevwiki-pfs.md ## PSDevWiki — PKG files page -- What it is: Orientation + structure notes for PKG outer container and embedded PFS (header, entries, digests, PFS offsets/digests, delivery metadata). +- What: Orientation + structure notes for PKG outer container and embedded PFS (header, entries, digests, PFS offsets/digests, delivery metadata). - Relevance: Exposes where/what to validate when a PKG wraps a PFS from MkPFS; captures EKPFS→XTS key derivation narrative for production images. - Upstream: https://www.psdevwiki.com/ps4/PKG_files -- Internal reference: references/psdevwiki-pkg-files.md +- Internal: references/psdevwiki-pkg-files.md ## ShadPKG — HOWWORKS -- What it is: Deep implementation walkthrough from PKG decryption to PFS/PFSC handling. +- What: Deep implementation walkthrough from PKG decryption to PFS/PFSC handling. - Upstream: https://github.com/seregonwar/ShadPKG/blob/main/docs/HOWWORKS.md -- Internal reference: references/shadpkg-howworks.md +- Internal: references/shadpkg-howworks.md ## Wololo — flatz FPKG writeup -- What it is: Authoritative deep-dive on FSELF/FPKG enablement (kernel hooks, toolchain key swap, ShellCore patches, kernel crypto shims). +- What: Authoritative deep-dive on FSELF/FPKG enablement (kernel hooks, toolchain key swap, ShellCore patches, kernel crypto shims). - Relevance: Defines EKPFS vs EEKPFS and PFS final key derivation; clarifies why unsigned/PFSC developer flows exist versus retail. - Upstream: https://wololo.net/ps4-fpkg-writeup-by-flatz/ -- Internal reference: references/wololo-fpkg-flatz.md +- Internal: references/wololo-fpkg-flatz.md ## goodle -- What it is: Thin Go cgo wrapper for OodleLZ decompression; drop-in replacement for the `gooz` package. -- Relevance: Validates Oodle per-block decompression paths used in adjacent tooling; helpful for cross-checking outputs independent of Python. +- What: Thin Go cgo wrapper for OodleLZ decompression; drop-in replacement for the `gooz` package. +- Relevance: Validates Oodle per-block decompression paths used in adjacent tooling; cross-check outputs independent of Python. - Gotchas: Requires proprietary Oodle shared library (`oo2core_N_win64.dll`/`liboo2core.so/.dylib`). - Upstream: https://github.com/oriath-net/goodle -- Internal reference: references/goodle.md +- Internal: references/goodle.md ## TLOU PSARC Tool -- What it is: Windows GUI utility to read/extract and partially reimport Naughty Dog `.psarc` archives (big-endian headers, MD5 name table, per-block Oodle/zlib). +- What: Windows GUI utility to read/extract and partially reimport Naughty Dog `.psarc` archives (big-endian headers, MD5 name table, per-block Oodle/zlib). - Relevance: Demonstrates block size tables, MD5-based name resolution, and Oodle/zlib per-block decompression used in adjacent game assets. -- Gotchas: Windows-only, GUI-only; import path writes uncompressed, injects author signature, and does not update the name table. +- Gotchas: Windows-only, GUI-only; import path writes uncompressed, injects author signature, does not update the name table. - Upstream: https://github.com/amrshaheen61/TLOU_PSARC_Tool -- Internal reference: references/tlou-psarc-tool.md +- Internal: references/tlou-psarc-tool.md ## PKG Passcode Finder -- What it is: VB.NET WPF app that randomly brute-forces 31-char alphanumeric passcodes for PS5 PKG extraction by invoking `prospero-pub-cmd.exe`. +- What: VB.NET WPF app that randomly brute-forces 31-char alphanumeric passcodes for PS5 PKG extraction by invoking `prospero-pub-cmd.exe`. - Relevance: Confirms passcode length/charset and SDK-driven extraction flow; context for why open tooling matters. - Gotchas: Astronomical keyspace (62^31) makes naive random brute force impractical; Windows-only GUI; requires proprietary SDK tool. - Upstream: https://github.com/bobg-github/PS5PKGPasscodeFinder -- Internal reference: references/pkg-passcode-finder.md +- Internal: references/pkg-passcode-finder.md ## Oodle/Kraken Decompression Tools -- What it is: Collection of open decoders and shims for Oodle codecs (Kraken/Mermaid/Selkie/Leviathan), including a Rust decompressor and Go Oodle wrapper. +- What: Collection of open decoders and shims for Oodle codecs (Kraken/Mermaid/Selkie/Leviathan), including a Rust decompressor and Go Oodle wrapper. - Relevance: Enables verifying Oodle-compressed block behavior across ecosystems that feed into or out of PFS. - Gotchas: Official Oodle libraries are proprietary; prebuilt .so/.dll distribution may have licensing constraints. - Upstream: https://github.com/lvlvllvlvllvlvl/oozextract -- Internal reference: references/oodle-kraken-tools.md +- Internal: references/oodle-kraken-tools.md --- ## Notes -- Internal reference files live under `references/*.md` in this skill and contain the detailed notes and citations. + +- Internal reference files live under `references/*.md` in this skill and contain detailed notes and citations. - If an upstream link moves, update it here and in the corresponding internal reference. diff --git a/.agents/skills/related-projects-index/references/goodle.md b/.claude/skills/related-projects-index/references/goodle.md similarity index 100% rename from .agents/skills/related-projects-index/references/goodle.md rename to .claude/skills/related-projects-index/references/goodle.md diff --git a/.agents/skills/related-projects-index/references/kstuff-lite.md b/.claude/skills/related-projects-index/references/kstuff-lite.md similarity index 100% rename from .agents/skills/related-projects-index/references/kstuff-lite.md rename to .claude/skills/related-projects-index/references/kstuff-lite.md diff --git a/.agents/skills/related-projects-index/references/liborbispkg-wiki.md b/.claude/skills/related-projects-index/references/liborbispkg-wiki.md similarity index 100% rename from .agents/skills/related-projects-index/references/liborbispkg-wiki.md rename to .claude/skills/related-projects-index/references/liborbispkg-wiki.md diff --git a/.agents/skills/related-projects-index/references/liborbispkg.md b/.claude/skills/related-projects-index/references/liborbispkg.md similarity index 100% rename from .agents/skills/related-projects-index/references/liborbispkg.md rename to .claude/skills/related-projects-index/references/liborbispkg.md diff --git a/.agents/skills/related-projects-index/references/oodle-kraken-tools.md b/.claude/skills/related-projects-index/references/oodle-kraken-tools.md similarity index 100% rename from .agents/skills/related-projects-index/references/oodle-kraken-tools.md rename to .claude/skills/related-projects-index/references/oodle-kraken-tools.md diff --git a/.agents/skills/related-projects-index/references/pkg-passcode-finder.md b/.claude/skills/related-projects-index/references/pkg-passcode-finder.md similarity index 100% rename from .agents/skills/related-projects-index/references/pkg-passcode-finder.md rename to .claude/skills/related-projects-index/references/pkg-passcode-finder.md diff --git a/.agents/skills/related-projects-index/references/pkgtool.md b/.claude/skills/related-projects-index/references/pkgtool.md similarity index 100% rename from .agents/skills/related-projects-index/references/pkgtool.md rename to .claude/skills/related-projects-index/references/pkgtool.md diff --git a/.agents/skills/related-projects-index/references/ps5-game-compressor.md b/.claude/skills/related-projects-index/references/ps5-game-compressor.md similarity index 100% rename from .agents/skills/related-projects-index/references/ps5-game-compressor.md rename to .claude/skills/related-projects-index/references/ps5-game-compressor.md diff --git a/.agents/skills/related-projects-index/references/psdevwiki-pfs.md b/.claude/skills/related-projects-index/references/psdevwiki-pfs.md similarity index 100% rename from .agents/skills/related-projects-index/references/psdevwiki-pfs.md rename to .claude/skills/related-projects-index/references/psdevwiki-pfs.md diff --git a/.agents/skills/related-projects-index/references/psdevwiki-pkg-files.md b/.claude/skills/related-projects-index/references/psdevwiki-pkg-files.md similarity index 100% rename from .agents/skills/related-projects-index/references/psdevwiki-pkg-files.md rename to .claude/skills/related-projects-index/references/psdevwiki-pkg-files.md diff --git a/.agents/skills/related-projects-index/references/shadowmountplus.md b/.claude/skills/related-projects-index/references/shadowmountplus.md similarity index 100% rename from .agents/skills/related-projects-index/references/shadowmountplus.md rename to .claude/skills/related-projects-index/references/shadowmountplus.md diff --git a/.agents/skills/related-projects-index/references/shadpkg-howworks.md b/.claude/skills/related-projects-index/references/shadpkg-howworks.md similarity index 100% rename from .agents/skills/related-projects-index/references/shadpkg-howworks.md rename to .claude/skills/related-projects-index/references/shadpkg-howworks.md diff --git a/.agents/skills/related-projects-index/references/tlou-psarc-tool.md b/.claude/skills/related-projects-index/references/tlou-psarc-tool.md similarity index 100% rename from .agents/skills/related-projects-index/references/tlou-psarc-tool.md rename to .claude/skills/related-projects-index/references/tlou-psarc-tool.md diff --git a/.agents/skills/related-projects-index/references/wololo-fpkg-flatz.md b/.claude/skills/related-projects-index/references/wololo-fpkg-flatz.md similarity index 100% rename from .agents/skills/related-projects-index/references/wololo-fpkg-flatz.md rename to .claude/skills/related-projects-index/references/wololo-fpkg-flatz.md diff --git a/.claude/skills/running-unit-tests/SKILL.md b/.claude/skills/running-unit-tests/SKILL.md new file mode 100644 index 0000000..f7f4bd5 --- /dev/null +++ b/.claude/skills/running-unit-tests/SKILL.md @@ -0,0 +1,35 @@ +--- +name: running-unit-tests +description: > + Run formatting, linting, and tests; then iteratively fix failures until the branch is green. + Use after implementing a feature or fixing a bug to get the branch ready to push. + Triggers: "tests", "run tests", "lint", "format", "CI red", "fix failing tests". +context: fork +--- + +# Running and Fixing Tests + +Run `./run-tests.sh` at the end of each feature, bug fix, or refactor to ensure the branch is ready to push. +It activates `.venv`, runs `uv sync`, installs pre-commit hooks, formats with `ruff format`, +auto-fixes with `ruff check --fix`, then runs `uv run --frozen pytest`. + +## Workflow + +1. **Inspect what changed.** `git status --short`, `git diff --stat`, `git diff`. +2. **Run the validation flow.** + - Preferred: `./run-tests.sh` (full flow above). + - Tests only: `uv run --frozen pytest`. + - Pre-commit explicitly: `uv run --frozen pre-commit run --all-files`. +3. **Loop until clean.** + - Group failures by root cause. + - Apply minimal, readable fixes; keep behavior stable unless tests show it's incorrect. + - Add or update focused tests for each bug fix. + - Re-run `./run-tests.sh` (or `uv run --frozen pytest` for quicker cycles) after each batch. +4. **Final readiness check.** Confirm `./run-tests.sh` passes cleanly. Optionally re-run pre-commit. + Summarize what was fixed and list any remaining risks before push. + +## Setup notes + +- First-time setup: if `.venv/` doesn't exist, run `uv sync` once, or run `./run-tests.sh`. +- Different virtualenv: set `SKIP_VENV=1` and ensure `python3` resolves to the desired environment. +- Faster loops: `uv run --frozen pytest -k -q` to target tests, then finish with full `./run-tests.sh`. diff --git a/.pi b/.pi deleted file mode 120000 index c0ca468..0000000 --- a/.pi +++ /dev/null @@ -1 +0,0 @@ -.agents \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md deleted file mode 100644 index f507466..0000000 --- a/AGENTS.md +++ /dev/null @@ -1,38 +0,0 @@ -# Development Guidelines - -## Quick Start - -```bash -uv sync --group dev -uv run mkpfs --help -``` - -## Rules - -1. **Package Management**: Use `uv` only (never pip). Install: `uv add pkg`. Upgrade: `uv add --dev pkg --upgrade-package pkg`. Sync deps: `uv sync --group dev`. -2. **Code Quality**: Type hints required. Google-style docstrings. Prefer explicit keyword args. All variables need explicit type annotations (`count: int = 0`). Target Python 3.11 (use `list`, `dict`, `X | None`). -3. **CLI Structure**: Keep CLI wiring in `mkpfs/cli.py` (`build_cli`, `cmd_*`). Keep PFS logic in `mkpfs/pfs.py`. Shared modules: `consts.py` (constants), `pbar.py` (progress/scan), `utils.py` (helpers). Canonical CLI surface: `pack`, `verify`, `inspect`, `tree`, `unpack`. -4. **Testing**: `./run-tests.sh` (runs ruff format + check + pytest). Or: `uv run --frozen pytest`. New features need tests; bug fixes need regression tests. CLI smoke tests in `tests/test_main.py`. -5. **Git**: Always use the `pr-and-commit-writing` skill for commit messages and PRs. Follow its rules: commit messages use short natural-language titles (≤50 chars); PR titles are simple, release‑note‑ready sentences (≤72 chars) without Conventional Commit prefixes. -6. **Formatting**: `uv run --frozen ruff format .` / `uv run --frozen ruff check . --fix`. -7. **Imports**: Top of file (local imports only when necessary, document why). Catch specific exceptions only. -8. **Naming**: `PFS` in CamelCase symbols, `pfs` in snake_case. Never `Pfs`. -9. **Comments**: Block comments for major phases in long functions (~30+ lines). Present tense, explain why not what. -10. **CLI naming**: One canonical function per subcommand (e.g., `cli_mkpfs_pack_run`). No multiple public aliases. -11. **No AI attribution**: Never mention AI tools in public text (commits, PRs, release notes, etc.). -12. **Subagent cost**: Prefer focused, scoped subagent prompts with minimal context. Avoid passing full conversation history. Use targeted prompts with specific file paths and constraints. -13. **`tmp/` scratch**: Use `./tmp/` for ephemeral files. Never commit files from `./tmp/`. - -## GitHub CLI Tips - -- `GH_PAGER=cat gh ` to avoid interactive pager -- `GIT_PAGER='' git ` for git commands in automation - -## Docs & Skills Pointers - -- Worktree map: .agents/rules/worktree.md (2-level repository map for fast navigation) -- Writing style: .agents/rules/writing-style.md (quick guide for README/docs) -- Related projects index: .agents/skills/related-projects-index/SKILL.md (curated external sources; see references/*.md) -- Commits/PRs: .agents/skills/pr-and-commit-writing/SKILL.md (use when generating public commit/PR text) -- HTML reporting: .agents/skills/html-report-builder/SKILL.md (use for producing public commit/PR text) -- TEMP folder usage: .agents/rules/tmp-usage.md (use ./tmp/ for transient artifacts only) diff --git a/CLAUDE.md b/CLAUDE.md deleted file mode 120000 index 47dc3e3..0000000 --- a/CLAUDE.md +++ /dev/null @@ -1 +0,0 @@ -AGENTS.md \ No newline at end of file diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..f2d8ae6 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,83 @@ +# Development Guidelines + +## Quick Start + +```bash +uv sync --group dev +uv run mkpfs --help +``` + +## Rules + +1. **Package Management**: Use `uv` only (never pip). Install: `uv add pkg`. Upgrade: `uv add --dev pkg --upgrade-package pkg`. Sync deps: `uv sync --group dev`. +2. **Code Quality**: Type hints required. Google-style docstrings. Prefer explicit keyword args. All variables need explicit type annotations (`count: int = 0`). Target Python 3.11 (use `list`, `dict`, `X | None`). +3. **CLI Structure**: Keep CLI wiring in `mkpfs/cli.py` (`build_cli`, `cmd_*`). Keep PFS logic in `mkpfs/pfs.py`. Shared modules: `consts.py` (constants), `pbar.py` (progress/scan), `utils.py` (helpers). Canonical CLI surface: `pack`, `verify`, `inspect`, `tree`, `unpack`. +4. **Testing**: `./run-tests.sh` (runs ruff format + check + pytest). Or: `uv run --frozen pytest`. New features need tests; bug fixes need regression tests. CLI smoke tests in `tests/test_main.py`. +5. **Git**: Always use the `pr-and-commit-writing` skill for commit messages and PRs. Commit titles short natural-language (≤50 chars); PR titles are release-note-ready sentences (≤72 chars) without Conventional Commit prefixes. +6. **Formatting**: `uv run --frozen ruff format .` / `uv run --frozen ruff check . --fix`. +7. **Imports**: Top of file (local imports only when necessary, document why). Catch specific exceptions only. +8. **Naming**: `PFS` in CamelCase symbols, `pfs` in snake_case. Never `Pfs`. +9. **Comments**: Block comments for major phases in long functions (~30+ lines). Present tense, explain why not what. +10. **CLI naming**: One canonical function per subcommand (e.g., `cli_mkpfs_pack_run`). No multiple public aliases. +11. **No AI attribution**: Never mention AI tools in public text (commits, PRs, release notes, etc.). +12. **Subagent cost**: Prefer focused, scoped subagent prompts with minimal context. Avoid passing full conversation history. Use targeted prompts with specific file paths and constraints. +13. **`tmp/` scratch**: Use `./tmp/` for ephemeral files (create `./tmp//` subfolders per task). Never commit files from `./tmp/`. + +## Writing Style + +Keep README/docs practical, concise, scannable. Prefer bullets over long prose. +- Active voice, present tense. Short paragraphs, short sentences. Factual, no hype. +- One example per command; avoid exhaustive flag lists in README. Fenced code blocks with language hints. +- Markdown only (avoid inline HTML). Line length ~100 cols for prose. Code font for filenames, commands, flags. +- Align README claims with pyproject.toml (name, version, Python, license, URLs). +- Link to CONTRIBUTING.md instead of duplicating policy. + +## PyPI Packaging + +- Use `pyproject.toml` as the primary source of packaging metadata. Keep core metadata explicit: name, version, supported Python, runtime deps, license, README, keywords, classifiers, project URLs. +- Build and publish both source distributions and wheels. Validate with `uv build` and `uv run --frozen twine check dist/*` before publishing. +- Package name: `mkpfs`; CLI entrypoint defined in pyproject. +- Keep README command reference aligned with CLI surface: `pack`, `verify`, `inspect`, `tree`, `unpack`. +- Keep README at repo root, renderer-safe for PyPI. + +## Worktree Map (2 levels) + +Quick navigation map for agents. Two levels deep with short descriptions. + +- README.md — project overview, install/usage, command reference +- CLAUDE.md — development rules and workflows +- .claude/ + - skills/ — skills (see pointers below) +- mkpfs/ + - __main__.py — entry point (`python -m mkpfs`) + - cli.py — CLI wiring (`build_cli`, `cmd_*`) + - pfs.py — core PFS build/verify/inspect logic + - exfat.py, exfat_writer.py — exFAT reader/writer + - ampr.py — APR Emu index and helpers + - pbar.py — progress bar, scan/tree utilities + - utils.py — shared helpers + - consts.py — constants used across modules + - _exfat_upcase.py — exFAT upcase table (generated/static data) + - logging.py — logging setup/utilities + - gui.py, gui/ — optional GUI +- tests/ + - integration.sh — CLI smoke harness + - mkpfs/ — pytest suite: test_cli.py, test_pfs.py, test_exfat*.py, test_utils.py, etc. +- .github/ + - workflows/ — CI, stale, release-drafter, auto-assign, gitleaks + - labels.yml, release-drafter-config.yml, FUNDING.yml, ISSUE_TEMPLATE/ +- assets/ — project assets (images/docs) +- run-tests.sh — convenience script: ruff format+check, pytest +- pyproject.toml — project metadata, tooling config +- uv.lock — dependency lockfile + +## GitHub CLI Tips + +- `GH_PAGER=cat gh ` to avoid interactive pager +- `GIT_PAGER='' git ` for git commands in automation + +## Skills Pointers + +- Related projects index: .claude/skills/related-projects-index/SKILL.md (curated external sources; see references/*.md) +- Commits/PRs: .claude/skills/pr-and-commit-writing/SKILL.md (use when generating public commit/PR text) +- HTML reporting: .claude/skills/html-report-builder/SKILL.md (use for producing self-contained HTML reports under ./tmp/)