feat: add Codex wiki bundle export workflow and local artifact ignore rules#1677
feat: add Codex wiki bundle export workflow and local artifact ignore rules#1677Juanzitooh wants to merge 4 commits intoopentibiabr:mainfrom
Conversation
not tested by explicit user decision
not tested by explicit user decision
not tested by explicit user decision
📝 WalkthroughWalkthroughAdds documentation, .gitignore entries, and a new CLI tool to collect referenced wiki files and produce a compressed "wiki bundle" ZIP for distribution and use with Codex/OTClient. Changes
Sequence Diagram(s)sequenceDiagram
autonumber
participant User as User (CLI)
participant Script as export_wiki_bundle.py
participant FS as Repository FS
participant Zip as ZIP Archive
rect rgba(135,206,250,0.5)
User->>Script: run `python3 tools/export_wiki_bundle.py`
end
rect rgba(144,238,144,0.5)
Script->>FS: locate `wiki.md` (root or docs/)
Script->>FS: read wiki content
Script->>Script: parse backtick-delimited paths (dedupe, order)
Script->>Script: filter out excluded prefixes
Script->>FS: resolve each path (file or directory)
FS-->>Script: return files (or missing warnings)
end
rect rgba(255,182,193,0.5)
Script->>Zip: write resolved files with repo-relative paths
Zip-->>Script: confirm archive written
Script->>User: print summary, warnings, output path
end
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Poem
🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🧹 Nitpick comments (1)
tools/export_wiki_bundle.py (1)
68-68: Prefer iterable unpacking over concatenation.Using
[*items]syntax is more idiomatic and avoids creating an intermediate list.♻️ Suggested fix
- paths = [wiki_path.relative_to(repo_root).as_posix(), "AGENTS.global.md"] + raw_paths + paths = [wiki_path.relative_to(repo_root).as_posix(), "AGENTS.global.md", *raw_paths]🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@tools/export_wiki_bundle.py` at line 68, The paths list is built by concatenating lists; update the assignment of paths to use iterable unpacking so the first two elements (derived from wiki_path.relative_to(repo_root).as_posix() and the literal "AGENTS.global.md") are followed by the expanded raw_paths iterable (use the * unpacking operator on raw_paths) to avoid creating an extra intermediate list; modify the line that assigns paths (referencing variables paths, wiki_path, repo_root, and raw_paths) accordingly.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/README.md`:
- Around line 100-104: Update the two constants used in the English section so
they point to the upstream repository: replace the values assigned to
RELEASE_PAGE_URL and WIKI_BUNDLE_URL (the lines containing
`RELEASE_PAGE_URL=...` and `WIKI_BUNDLE_URL=...`) so the host path uses
`opentibiabr/otclient` instead of `Juanzitooh/otclient`, ensuring both the
release tag URL and the direct zip download URL are corrected.
- Around line 29-33: The RELEASE_PAGE_URL and WIKI_BUNDLE_URL values currently
point to the fork `Juanzitooh/otclient`; update both constants (RELEASE_PAGE_URL
and WIKI_BUNDLE_URL) to use the target repository `opentibiabr/otclient`
instead, and make the same replacements in the English section occurrences
referenced (lines around the English section, currently at lines 100 and 104) so
all download/release links point to opentibiabr/otclient.
In `@tools/export_wiki_bundle.py`:
- Around line 60-68: Add a short docstring or inline comment near the top of
export_wiki_bundle.py (close to wiki_path, parse_paths, and the logic that
builds paths = [..., "AGENTS.global.md"] + raw_paths) clarifying that wiki.md
(or docs/wiki.md) is mandatory and the script will exit with error if missing,
while AGENTS.global.md is optional and will be included only if present; update
the comment near the filtering logic that skips non-slash paths to note this
behavior so future readers understand the hard vs soft dependency.
---
Nitpick comments:
In `@tools/export_wiki_bundle.py`:
- Line 68: The paths list is built by concatenating lists; update the assignment
of paths to use iterable unpacking so the first two elements (derived from
wiki_path.relative_to(repo_root).as_posix() and the literal "AGENTS.global.md")
are followed by the expanded raw_paths iterable (use the * unpacking operator on
raw_paths) to avoid creating an extra intermediate list; modify the line that
assigns paths (referencing variables paths, wiki_path, repo_root, and raw_paths)
accordingly.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 82f448eb-ba1f-4db1-9470-3ac6d1d71fe1
📒 Files selected for processing (3)
.gitignoredocs/README.mdtools/export_wiki_bundle.py
| `RELEASE_PAGE_URL=https://github.com/Juanzitooh/otclient/releases/tag/codex` | ||
|
|
||
| Download direto do zip: | ||
|
|
||
| `WIKI_BUNDLE_URL=https://github.com/Juanzitooh/otclient/releases/download/codex/codex_export_otclient.zip` |
There was a problem hiding this comment.
Update URLs to point to the target repository, not the fork.
The URLs reference Juanzitooh/otclient (the author's fork) but this PR targets opentibiabr/otclient. After merge, users following this documentation will download from the wrong location or get 404s if the fork release doesn't exist.
🔧 Suggested fix
-`RELEASE_PAGE_URL=https://github.com/Juanzitooh/otclient/releases/tag/codex`
+`RELEASE_PAGE_URL=https://github.com/opentibiabr/otclient/releases/tag/codex`
Download direto do zip:
-`WIKI_BUNDLE_URL=https://github.com/Juanzitooh/otclient/releases/download/codex/codex_export_otclient.zip`
+`WIKI_BUNDLE_URL=https://github.com/opentibiabr/otclient/releases/download/codex/codex_export_otclient.zip`Also apply the same fix to lines 100 and 104 in the English section.
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| `RELEASE_PAGE_URL=https://github.com/Juanzitooh/otclient/releases/tag/codex` | |
| Download direto do zip: | |
| `WIKI_BUNDLE_URL=https://github.com/Juanzitooh/otclient/releases/download/codex/codex_export_otclient.zip` | |
| `RELEASE_PAGE_URL=https://github.com/opentibiabr/otclient/releases/tag/codex` | |
| Download direto do zip: | |
| `WIKI_BUNDLE_URL=https://github.com/opentibiabr/otclient/releases/download/codex/codex_export_otclient.zip` |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/README.md` around lines 29 - 33, The RELEASE_PAGE_URL and
WIKI_BUNDLE_URL values currently point to the fork `Juanzitooh/otclient`; update
both constants (RELEASE_PAGE_URL and WIKI_BUNDLE_URL) to use the target
repository `opentibiabr/otclient` instead, and make the same replacements in the
English section occurrences referenced (lines around the English section,
currently at lines 100 and 104) so all download/release links point to
opentibiabr/otclient.
| `RELEASE_PAGE_URL=https://github.com/Juanzitooh/otclient/releases/tag/codex` | ||
|
|
||
| Direct zip download: | ||
|
|
||
| `WIKI_BUNDLE_URL=https://github.com/Juanzitooh/otclient/releases/download/codex/codex_export_otclient.zip` |
There was a problem hiding this comment.
Same URL issue in English section.
These URLs also need to be updated to point to opentibiabr/otclient instead of the fork.
🔧 Suggested fix
-`RELEASE_PAGE_URL=https://github.com/Juanzitooh/otclient/releases/tag/codex`
+`RELEASE_PAGE_URL=https://github.com/opentibiabr/otclient/releases/tag/codex`
Direct zip download:
-`WIKI_BUNDLE_URL=https://github.com/Juanzitooh/otclient/releases/download/codex/codex_export_otclient.zip`
+`WIKI_BUNDLE_URL=https://github.com/opentibiabr/otclient/releases/download/codex/codex_export_otclient.zip`📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| `RELEASE_PAGE_URL=https://github.com/Juanzitooh/otclient/releases/tag/codex` | |
| Direct zip download: | |
| `WIKI_BUNDLE_URL=https://github.com/Juanzitooh/otclient/releases/download/codex/codex_export_otclient.zip` | |
| `RELEASE_PAGE_URL=https://github.com/opentibiabr/otclient/releases/tag/codex` | |
| Direct zip download: | |
| `WIKI_BUNDLE_URL=https://github.com/opentibiabr/otclient/releases/download/codex/codex_export_otclient.zip` |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/README.md` around lines 100 - 104, Update the two constants used in the
English section so they point to the upstream repository: replace the values
assigned to RELEASE_PAGE_URL and WIKI_BUNDLE_URL (the lines containing
`RELEASE_PAGE_URL=...` and `WIKI_BUNDLE_URL=...`) so the host path uses
`opentibiabr/otclient` instead of `Juanzitooh/otclient`, ensuring both the
release tag URL and the direct zip download URL are corrected.
tools/export_wiki_bundle.py
Outdated
| if wiki_path is None: | ||
| print("Erro: wiki.md (raiz) ou docs/wiki.md nao encontrado no repo.", file=sys.stderr) | ||
| return 1 | ||
|
|
||
| wiki_text = wiki_path.read_text(encoding="utf-8") | ||
| raw_paths = parse_paths(wiki_text) | ||
|
|
||
| # Sempre inclui a wiki encontrada e o AGENTS global. | ||
| paths = [wiki_path.relative_to(repo_root).as_posix(), "AGENTS.global.md"] + raw_paths |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Check if wiki.md or AGENTS.global.md exist in the repository
echo "=== Checking for wiki.md ==="
fd -t f -i "wiki.md"
echo "=== Checking for AGENTS.global.md ==="
fd -t f -i "AGENTS.global.md"
echo "=== Listing docs/ contents if exists ==="
if [ -d "docs" ]; then
tree docs -L 2 2>/dev/null || ls -la docs/
fiRepository: opentibiabr/otclient
Length of output: 320
🏁 Script executed:
# Read the full script to understand context and any comments about required files
wc -l tools/export_wiki_bundle.pyRepository: opentibiabr/otclient
Length of output: 95
🏁 Script executed:
# Check the full script content with line numbers
cat -n tools/export_wiki_bundle.pyRepository: opentibiabr/otclient
Length of output: 4787
🏁 Script executed:
# Search for any documentation or README that mentions wiki.md or AGENTS.global.md
rg -i "wiki\.md|agents\.global" --type mdRepository: opentibiabr/otclient
Length of output: 674
🏁 Script executed:
# Check if there's any documentation in the PR or script comments about these files
rg -i "wiki\.md|agents\.global" -A 2 -B 2Repository: opentibiabr/otclient
Length of output: 3629
Script documentation could clarify file requirements.
The script has a hard requirement for wiki.md (or docs/wiki.md) which will cause it to exit with error if missing. This is intentional and documented in docs/README.md. However, AGENTS.global.md is already designed to be optional—it's included in the bundle if it exists, but silently skipped if missing (line 43-44 filters reporting to only paths containing "/" to avoid "ruido de tokens textuais").
Consider adding a docstring clarification or comment in the script distinguishing the requirements: wiki.md is mandatory for the script to function, while AGENTS.global.md is a soft dependency included only if present. This would prevent confusion when running the script on fresh setups.
🧰 Tools
🪛 Ruff (0.15.7)
[warning] 68-68: Consider iterable unpacking instead of concatenation
Replace with iterable unpacking
(RUF005)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@tools/export_wiki_bundle.py` around lines 60 - 68, Add a short docstring or
inline comment near the top of export_wiki_bundle.py (close to wiki_path,
parse_paths, and the logic that builds paths = [..., "AGENTS.global.md"] +
raw_paths) clarifying that wiki.md (or docs/wiki.md) is mandatory and the script
will exit with error if missing, while AGENTS.global.md is optional and will be
included only if present; update the comment near the filtering logic that skips
non-slash paths to note this behavior so future readers understand the hard vs
soft dependency.
There was a problem hiding this comment.
🧹 Nitpick comments (2)
tools/export_wiki_bundle.py (2)
68-72: Consider iterable unpacking instead of list concatenation.Ruff flagged this as RUF005. Using unpacking is slightly more idiomatic in modern Python.
♻️ Proposed fix using iterable unpacking
- paths = [ - wiki_path.relative_to(repo_root).as_posix(), - "AGENTS.global.md", - "tools/export_wiki_bundle.py", - ] + raw_paths + paths = [ + wiki_path.relative_to(repo_root).as_posix(), + "AGENTS.global.md", + "tools/export_wiki_bundle.py", + *raw_paths, + ]🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@tools/export_wiki_bundle.py` around lines 68 - 72, Replace the list concatenation used to build the paths variable with iterable unpacking: when constructing the paths list where wiki_path, "AGENTS.global.md", and "tools/export_wiki_bundle.py" are combined with raw_paths, expand raw_paths into the literal list using unpacking so raw_paths items are inlined rather than appended via +; update the expression that assigns to paths (referencing variables paths, raw_paths, wiki_path, repo_root) accordingly.
64-64: Consider handling encoding errors gracefully.
read_text(encoding="utf-8")will raiseUnicodeDecodeErrorifwiki.mdcontains invalid UTF-8 bytes. For a local dev tool this is low risk, but a try-except with a user-friendly message would improve robustness.♻️ Optional fix for encoding error handling
- wiki_text = wiki_path.read_text(encoding="utf-8") + try: + wiki_text = wiki_path.read_text(encoding="utf-8") + except UnicodeDecodeError as e: + print(f"Erro: falha ao ler {wiki_path} como UTF-8: {e}", file=sys.stderr) + return 1🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@tools/export_wiki_bundle.py` at line 64, Wrap the wiki_path.read_text(encoding="utf-8") call in a try/except that catches UnicodeDecodeError, referencing the wiki_text assignment and wiki_path.read_text call; on error, log or raise a user-friendly message that includes the file name and the decode error, then optionally fallback to a tolerant decode (e.g., read bytes via wiki_path.read_bytes() and decode(..., errors="replace")) so the tool can proceed instead of crashing.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In `@tools/export_wiki_bundle.py`:
- Around line 68-72: Replace the list concatenation used to build the paths
variable with iterable unpacking: when constructing the paths list where
wiki_path, "AGENTS.global.md", and "tools/export_wiki_bundle.py" are combined
with raw_paths, expand raw_paths into the literal list using unpacking so
raw_paths items are inlined rather than appended via +; update the expression
that assigns to paths (referencing variables paths, raw_paths, wiki_path,
repo_root) accordingly.
- Line 64: Wrap the wiki_path.read_text(encoding="utf-8") call in a try/except
that catches UnicodeDecodeError, referencing the wiki_text assignment and
wiki_path.read_text call; on error, log or raise a user-friendly message that
includes the file name and the decode error, then optionally fallback to a
tolerant decode (e.g., read bytes via wiki_path.read_bytes() and decode(...,
errors="replace")) so the tool can proceed instead of crashing.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 9ca4027f-643b-4b0f-8653-a399d5c8ffb3
📒 Files selected for processing (1)
tools/export_wiki_bundle.py
|
Agents.md should not contain any language other than English. It's a waste of tokens Yeah buddy, hard no go for me. |
2 participants
Description
This PR adds a Codex wiki bundle workflow for local documentation export and usage.
Summary of changes:
tools/export_wiki_bundle.pyto export a local wiki bundle for Codex usage.docs/README.mdwith instructions for generating and using the wiki bundle (python3 tools/export_wiki_bundle.py), including expected output flow.Motivation/context:
Dependencies:
Behavior
Actual
There was no standardized tool + documented flow to export a Codex wiki bundle, and local generated artifacts could leak into branch changes.
Expected
Contributors can run a single script to export the wiki bundle, follow documented steps in
docs/README.md, and keep local generated artifacts ignored by git.Fixes
(issue)
Type of change
How Has This Been Tested
python3 tools/export_wiki_bundle.pylocally and validated script execution/output generation.docs/README.mdmatch the implemented script flow.Test Configuration:
feat/codex)Checklist
Summary by CodeRabbit
Documentation
New Features