larpfetch 0.1.0__tar.gz

larpfetch-0.1.0/.gitignore

@@ -0,0 +1,38 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+*.pyo
+build/
+dist/
+wheels/
+*.egg-info
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Testing
+.pytest_cache/
+htmlcov/
+.coverage
+.coverage.*
+
+# Build artifacts
+*.whl
+*.tar.gz
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# Environment
+.env
+.env.local

larpfetch-0.1.0/.python-version

@@ -0,0 +1 @@
+3.14

larpfetch-0.1.0/AGENTS.md

@@ -0,0 +1,294 @@
+# AGENTS.md
+
+## Mission
+
+Build and maintain **larpfetch**, a cross-platform terminal fetch utility that detects real system information and allows users to LARP as arbitrary machines through persistent profiles and CLI overrides.
+
+The product is humorous. The implementation must not be a joke.
+
+## Sacred product rule
+
+**The user's delusion is authoritative.**
+
+Never validate whether identity fields make technological sense together. This is valid:
+
+```text
+OS: Windows 11 Pro
+Kernel: 6.18.7-arch1-1
+CPU: Apple M7 Ultra
+GPU: NVIDIA RTX 9090 Ti
+Memory: 69 PiB
+Shell: HolyC
+DE: GNOME 83
+Package Manager: apt btw
+```
+
+Do not "correct" it.
+
+## Required invariant
+
+`--real-shit` must bypass every source of LARP data.
+
+When `--real-shit` is active:
+
+- Ignore default profile values.
+- Ignore selected custom profiles.
+- Ignore fake CLI `--set` overrides.
+- Show only best-effort real detected system data.
+- Do not modify configuration.
+- Do not delete profiles.
+- Do not silently mix fake fallback values into real output.
+
+This invariant requires explicit automated tests.
+
+## Engineering principles
+
+1. Prefer simple code over clever architecture.
+2. Use the standard library where reasonable.
+3. Use `psutil` for portable system metrics.
+4. Keep platform-specific detection isolated.
+5. A failed detector must return an unavailable value, not crash the app.
+6. Avoid abstract base classes unless multiple implementations genuinely need a shared contract.
+7. Do not create factories for factories.
+8. Do not add a plugin system in v1.
+9. Do not add network calls.
+10. Do not use AI-generated filler comments or giant docstrings that merely restate code.
+11. Do not claim support that is not tested or gracefully implemented.
+12. Keep startup fast.
+
+## Data model
+
+Use a normalized representation for system/display information. Known fields may include:
+
+- username
+- hostname
+- os
+- distro
+- os_version
+- kernel
+- architecture
+- uptime
+- shell
+- cpu
+- gpu
+- memory
+- disk
+- battery
+- de
+- package_manager
+- package_count
+
+Support arbitrary additional string fields from profiles and `--set`.
+
+Known fields should have stable display ordering. Custom fields should follow deterministically.
+
+## Resolution algorithm
+
+Normal mode:
+
+```text
+real detected values
+    ← overridden by default profile
+    ← overridden by selected custom profile
+    ← overridden by CLI --set values
+```
+
+Equivalent precedence:
+
+```text
+CLI overrides > selected custom profile > default profile > real values
+```
+
+Reality mode:
+
+```text
+--real-shit > everything else
+```
+
+Do not accidentally implement custom profiles as total replacements. Missing fields should inherit from the default profile, then real values.
+
+## Configuration
+
+Use TOML and `tomllib`.
+
+Expected sections:
+
+```toml
+[default]
+
+[profiles.NAME]
+
+[appearance]
+```
+
+Requirements:
+
+- Helpful errors for invalid TOML.
+- Helpful error when requested profile does not exist.
+- Unknown profile fields are allowed.
+- Values intended for display should be normalized to strings.
+- Never execute values from config.
+- Respect explicit `--config PATH`.
+
+## CLI
+
+Required surface:
+
+```text
+larpfetch
+larpfetch -p NAME
+larpfetch --profile NAME
+larpfetch --real-shit
+larpfetch --list-profiles
+larpfetch --show-config
+larpfetch --config PATH
+larpfetch --set key=value
+larpfetch --version
+larpfetch --help
+```
+
+`--set` must be repeatable.
+
+Prefer `argparse` unless another dependency provides clear value. Avoid dependency inflation for cosmetic convenience.
+
+## Cross-platform behavior
+
+Support Linux, Windows, and macOS.
+
+Collectors:
+
+- Common collector: username, hostname, architecture, uptime, memory, disk, battery where portable.
+- Linux collector: distro from `/etc/os-release`, kernel, shell, DE, GPU best effort.
+- Windows collector: Windows edition/version/build, kernel/version, shell, GPU best effort.
+- macOS collector: macOS product version, Darwin kernel, shell, GPU best effort.
+
+Rules:
+
+- Avoid requiring root/admin.
+- Use subprocess argument arrays.
+- Use timeouts.
+- Never use `shell=True` unless absolutely necessary and documented.
+- Catch missing-command and timeout errors.
+- Do not let optional probes crash startup.
+
+## Rendering
+
+- Pair ASCII logo and aligned key/value rows.
+- Select logo from displayed identity.
+- In `--real-shit`, select from real identity.
+- Respect `NO_COLOR`.
+- Avoid broken alignment caused by ANSI codes.
+- Handle Unicode carefully.
+- Unknown distro/OS gets generic logo.
+- Keep original ASCII artwork in-repo. Do not copy copyrighted ASCII art blindly from third-party projects.
+
+## Humor
+
+The humor should be dry and sparse.
+
+Good:
+
+```text
+Authenticity: 3%
+Source: trust me bro
+Reality Leakage: 100.00%
+```
+
+Bad:
+
+- A joke on every line.
+- Random meme spam that obscures system information.
+- Offensive jokes.
+- Humor that makes tests flaky.
+- Pretending fake values are security facts.
+
+Easter eggs must be deterministic under test and disableable.
+
+## Testing requirements
+
+At minimum, test:
+
+- no config
+- default profile
+- selected custom profile
+- custom profile inheritance
+- CLI overrides
+- arbitrary unknown fields
+- impossible field combinations accepted
+- missing profile error
+- malformed TOML error
+- `--real-shit` ignores default profile
+- `--real-shit` ignores selected profile
+- `--real-shit` ignores CLI fake overrides
+- collector failure degradation
+- logo selection by displayed identity
+- real logo selection in reality mode
+- ANSI-safe alignment
+- `NO_COLOR`
+- CLI help/version
+- installable console entry point where practical
+
+Mock platform-specific system calls in unit tests.
+
+## Security
+
+- No `eval` or `exec`.
+- No arbitrary code execution from TOML.
+- No network access.
+- No unsafe shell interpolation.
+- No secrets collection.
+- Do not expose environment variables beyond explicitly needed values such as shell, config paths, desktop session, and color conventions.
+- Do not persist real system information unless a future feature explicitly requires it and documents it.
+
+## Packaging
+
+Use:
+
+- Python 3.11+
+- `pyproject.toml`
+- `src/` layout
+- console script `larpfetch`
+- `psutil`
+- `tomllib`
+
+Recommended dev tooling:
+
+- pytest
+- pytest-cov
+- ruff
+
+Keep runtime dependencies minimal.
+
+## Workflow for coding agents
+
+Before editing:
+
+1. Read `PRD.md`.
+2. Read this file.
+3. Read `IMPLEMENTATION.md`.
+4. Inspect existing code and tests.
+5. State a brief implementation plan internally, then execute.
+
+During implementation:
+
+1. Work in small coherent changes.
+2. Run focused tests after each subsystem.
+3. Run the full suite before completion.
+4. Run linting.
+5. Test the CLI manually.
+6. Verify packaging metadata.
+7. Do not leave placeholders, TODO implementations, fake test passes, or commented-out broken code.
+
+Before declaring completion:
+
+- Ensure acceptance criteria in `PRD.md` are met.
+- Ensure `--real-shit` invariant is covered by tests.
+- Ensure the project installs locally.
+- Ensure README commands match actual behavior.
+- Ensure no generated artifacts or secrets are accidentally committed.
+
+## Final warning
+
+Do not overengineer this.
+
+It is a fetch tool that lies.

larpfetch-0.1.0/IMPLEMENTATION.md

@@ -0,0 +1,351 @@
+# larpfetch Implementation Blueprint
+
+## 1. Technical stack
+
+- Python 3.11+
+- `psutil`
+- `tomllib`
+- `argparse`
+- `pathlib`
+- `platform`
+- `getpass`
+- `socket`
+- `subprocess`
+- `shutil`
+- `time`
+- `os`
+
+Development:
+
+- `pytest`
+- `pytest-cov`
+- `ruff`
+
+## 2. Build order
+
+### Phase 1: Package skeleton
+
+Create:
+
+```text
+pyproject.toml
+README.md
+LICENSE
+src/larpfetch/__init__.py
+src/larpfetch/__main__.py
+src/larpfetch/cli.py
+tests/
+```
+
+Expose:
+
+```toml
+[project.scripts]
+larpfetch = "larpfetch.cli:main"
+```
+
+Confirm:
+
+```bash
+python -m larpfetch --help
+larpfetch --help
+```
+
+### Phase 2: Models and real detection
+
+Create a normalized data structure that stores known fields plus custom fields.
+
+Suggested approach:
+
+```python
+@dataclass
+class SystemInfo:
+    fields: OrderedDict[str, str]
+```
+
+Or a similarly simple typed structure.
+
+Implement a common collector using standard library and `psutil`.
+
+Then implement platform-specific enrichment.
+
+Every optional probe should fail gracefully.
+
+### Phase 3: Configuration
+
+Implement platform-appropriate default config paths.
+
+Load TOML:
+
+```text
+[default]
+[profiles.<name>]
+[appearance]
+```
+
+Return a clear config object containing:
+
+- default profile
+- named profiles
+- appearance settings
+
+Unknown fields are valid.
+
+### Phase 4: Resolver
+
+Implement one pure resolution function.
+
+Inputs:
+
+- real system values
+- default profile
+- optional selected profile
+- CLI overrides
+- `real_shit: bool`
+
+Output:
+
+- resolved display identity
+- mode metadata: `real` or `larp`
+
+Pseudo-code:
+
+```python
+if real_shit:
+    return real_values
+
+resolved = real_values.copy()
+resolved.update(default_profile)
+
+if selected_profile:
+    resolved.update(selected_profile)
+
+resolved.update(cli_overrides)
+return resolved
+```
+
+Test this aggressively.
+
+### Phase 5: CLI
+
+Implement parsing for:
+
+```text
+-p, --profile NAME
+--real-shit
+--list-profiles
+--show-config
+--config PATH
+--set KEY=VALUE
+--version
+```
+
+Parsing requirements:
+
+- Repeated `--set`.
+- Split on first `=`.
+- Reject empty keys.
+- Permit arbitrary string values.
+- `--real-shit` must dominate fake inputs.
+
+### Phase 6: Logos
+
+Create original built-in ASCII logos.
+
+Map normalized displayed identity names to logos.
+
+Examples:
+
+```text
+arch, arch linux -> arch
+windows, windows 11, windows 10 -> windows
+macos, mac os, darwin -> macos
+ubuntu -> ubuntu
+debian -> debian
+fedora -> fedora
+templeos -> templeos
+unknown -> generic
+```
+
+The displayed identity determines the logo in LARP mode.
+
+### Phase 7: Renderer
+
+Render:
+
+```text
+<logo>    username@hostname
+<logo>    -----------------
+<logo>    OS: ...
+<logo>    Kernel: ...
+<logo>    CPU: ...
+```
+
+Requirements:
+
+- ANSI color.
+- ANSI-stripping width calculation.
+- Graceful logo/info height mismatch.
+- `NO_COLOR`.
+- Stable field ordering.
+- Custom fields displayed deterministically.
+
+### Phase 8: Humor and easter eggs
+
+Implement after core functionality is stable.
+
+Suggested mode indicator:
+
+- LARP mode: optional `Authenticity: N%`
+- Real mode: optional `Authenticity: 100%`
+
+Potential easter eggs:
+
+- Extremely implausible memory string -> `Source: trust me bro`
+- Windows + Arch kernel -> no warning; optionally rare hidden joke.
+- Real system crossing conservative high-end thresholds -> `Reality has out-LARPed the LARP.`
+
+Do not make output nondeterministic unless randomness is injectable and testable.
+
+### Phase 9: Tests
+
+Recommended test modules:
+
+```text
+tests/test_cli.py
+tests/test_config.py
+tests/test_resolver.py
+tests/test_renderer.py
+tests/test_logos.py
+tests/test_collectors.py
+tests/test_easter_eggs.py
+```
+
+The resolver should receive the heaviest unit coverage.
+
+### Phase 10: Documentation and release readiness
+
+README sections:
+
+1. Hero/title/tagline.
+2. Demo.
+3. Installation with `pipx`.
+4. Basic usage.
+5. `--real-shit`.
+6. Profiles.
+7. Configuration.
+8. CLI overrides.
+9. Cross-platform support.
+10. Easter eggs, without spoiling all of them.
+11. Development.
+12. Testing.
+13. Limitations.
+14. License.
+
+## 3. Suggested `pyproject.toml`
+
+Use modern PEP 621 metadata. Example shape:
+
+```toml
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "larpfetch"
+version = "0.1.0"
+description = "LARP as any distro, hardware, or machine you want."
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = ["psutil>=5.9"]
+
+[project.scripts]
+larpfetch = "larpfetch.cli:main"
+```
+
+Before publishing, verify current package-name availability and metadata requirements rather than assuming them.
+
+## 4. Real detection strategy
+
+### Common
+
+Use:
+
+- `getpass.getuser()`
+- `socket.gethostname()`
+- `platform.machine()`
+- `psutil.boot_time()`
+- `psutil.virtual_memory()`
+- `psutil.disk_usage()`
+- `psutil.sensors_battery()` where supported
+
+### Linux
+
+Prefer:
+
+- `/etc/os-release`
+- `platform.release()`
+- environment variables for shell/DE
+- safe optional subprocess probes for GPU/package data
+
+### Windows
+
+Prefer:
+
+- `platform` APIs
+- standard environment variables
+- PowerShell/CIM only as optional best-effort probes with timeout and safe argument passing
+
+### macOS
+
+Prefer:
+
+- `platform.mac_ver()`
+- `platform.release()`
+- `system_profiler` only as an optional best-effort probe with timeout
+
+## 5. Error strategy
+
+User-facing configuration errors should produce concise messages and nonzero exit codes.
+
+Optional system-probe failures should degrade silently or to `Unknown`, depending on context.
+
+Debug diagnostics may be added later behind a `--debug` flag, but are not required for v1.
+
+## 6. Performance target
+
+Aim for sub-second startup on normal machines when optional external probes are absent or fast.
+
+Slow probes should:
+
+- have short timeouts
+- be avoidable
+- never block the entire application indefinitely
+
+## 7. Compatibility principle
+
+Profiles are data, not simulations.
+
+Do not infer compatibility.
+
+Do not reject:
+
+```text
+Windows + Arch kernel
+macOS + RTX 9090
+TempleOS + GNOME
+Raspberry Pi + 69 PiB RAM
+```
+
+Print what the user configured.
+
+## 8. Definition of done
+
+- Full test suite passes.
+- Lint passes.
+- Local package build succeeds.
+- `pipx install .` succeeds.
+- CLI examples in README work.
+- `--real-shit` is demonstrably immune to all fake inputs.
+- Cross-platform collectors fail gracefully when platform-only facilities are unavailable.
+- No needless architecture has metastasized into the codebase.

larpfetch-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 larpfetch contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.