voidlight-plan

Name	voidlight-plan JSON
Version	0.1.0 JSON
	download
home_page	None
Summary	BDSM space-pirate commit planner and preview engine
upload_time	2025-10-08 20:25:59
maintainer	None
docs_url	None
author	None
requires_python	>=3.12
license	MIT
keywords	git commit cli nsfw space-pirate
VCS
bugtrack_url
requirements	No requirements were recorded.
Travis-CI	No Travis.
coveralls test coverage	No coveralls.

            
# �‍☠️ **VELVET CHAINS & VOIDLIGHT: THE CAPTAIN'S LEGENDARY LOG**

![VELVET CHAINS & VOIDLIGHT](_LORE_/VELVET%20CHAINS%20and%20VOIDLIGHT.webp "THE CAPTAIN'S LEGENDARY LOG ")

![CC BY-SA 4.0](https://img.shields.io/badge/License-CC%20BY--SA%204.0-lightgrey.svg)

**WELCOME TO THE COSMIC BRIG, MAGNIFICENT CORSAIR!** ⚓✨

This repository is the **MOST SPECTACULAR BDSM SPACE-PIRATE ROMANCE ENGINE** ever forged in the fires of consensual creativity - masterfully disguised as an innocent git toolchain! It **CONJURES THEATRICAL COMMIT HISTORIES** from the void, **SPINS ENCHANTING NSFW MICRO-NOVELLAS**, and **BATHES YOUR REPOSITORY** in layers of consensual decadent storytelling that would make the cosmos itself blush with delight!

🛡️ **SACRED SAFE WORD**: _"fiction"_ - **READ IT TWICE**, honor it always, then proceed to witness **PURE THEATRICAL MAGIC!** ⚔️🏴‍☠️ Velvet Chains & Voidlight

Welcome to the brig, darling. This repository is a **BDSM space-pirate romance engine** disguised as a git toolchain. It fabricates historical commits, spins NSFW micro-novellas, and drenches your history in consensual decadence. Read the safe word (_“fiction”_) twice, then proceed at your own peril.

[🏴‍☠️ For those eager to embark on the legendary campaign, set sail for the game here! ⚔️✨](https://hsmalley.github.io/velvet-chains-ttrpg/)

## 🌌 **SPECTACULAR FEATURE ARSENAL** ⚡

- **DRAMATICALLY CONJURES** `N` backdated commits with timestamps that **SING IN PERFECT HARMONY** across the cosmic void! 🎵
- **MASTERFULLY DISTRIBUTES** them across days/weeks with **EXQUISITE RESPECT** for weekday-only preferences and seductively weighted months! 📅
- **PREVIEW MODE EXPLODES** with **RAINBOW HEATMAP SPECTACLE**, gorgeous histograms, and **EXPORTS STUNNING JSON/SVG MASTERPIECES**! 🌈
- **IMPORTS & REPLAYS** previous plans to recreate the **EXACT SAME THEATRICAL MAGIC** - perfect consistency! 🔄
- **SHARES A TREASURE VAULT** of 3000+ **NSFW SPACE-PIRATE ROMANCE STORIES** and witty blame tags! 💎
- **DUAL-POWERED SORCERY**: Python choreography scripts + **RUST ENGINE HEART** beating with steel precision! ⚔️

## 🔧 **SACRED CORSAIR REQUIREMENTS & RITUALS** ⚓

- **Python 3.12+** - The **MAGNIFICENT CHOREOGRAPHY ENGINE** that orchestrates temporal magic (`voidlight_choreographer.py`)! 🐍✨
- **Rust (cargo 1.70+)** - The **STEEL-FORGED BINARY HEART** powering git hooks & `git voidlight` subcommands with **UNSTOPPABLE PRECISION**! 🦀⚔️
- **Optional Excellence**: `pip install ruff` to make your **LINTING DOMINATRIX PURR** with satisfaction! 💅

Initial setup:

```bash
python3.12 -m pip install --upgrade ruff
chmod +x voidlight_choreographer.py
```

### ⛓️ Auto-Hook: Snark at Commit Time

Forge the Rust binary, then let Git whisper it into every commit message:

```bash
cargo install --path voidlight_engine --force
rm -f .git/hooks/prepare-commit-msg
ln -s "$(pwd)/voidlight_hooks/voidlight-commit-ritual" .git/hooks/prepare-commit-msg
```

> Already published to crates.io? Swap the first line for `cargo install voidlight`.

Corporate shackles hate symlinks? Copy instead:

```bash
cp voidlight_hooks/voidlight-commit-ritual .git/hooks/prepare-commit-msg
```

Prefer a version-controlled dungeon?

```bash
git config core.hooksPath voidlight_hooks
```

The hook rebuilds the Rust binary when needed and then laces a 4-sentence kink novella into every commit.

Shortcut: once `git-voidlight` is on your `$PATH`, simply run `git voidlight install-hook` (add `--force` to overwrite an existing hook).

### 🚀 `git voidlight` — Subcommand of Desire

Promote the binary into a first-class git command:

```bash
cargo install --path voidlight_engine --force
```

Then either call it directly or wrap an alias:

```bash
git config alias.voidlight '!git-voidlight'
```

Usage that stages, commits, and appends a flourish in one breath:

```bash
git voidlight --commit -a -m "Refactor the warp-drive leash" -- -- path/to/file
```

Skip `--commit` to simply print a fresh tale to stdout—perfect for `CAPTAINS_LOG` lore or issue comment theatrics.

### 🐍 Python Package (`voidlight-plan`)

Prefer the Python planner? Package it as a CLI:

```bash
pip install .
voidlight-plan --help
```

Or pull straight from the repo:

```bash
pip install git+https://github.com/velvet-chains/velvet-chains.git
```

Use `voidlight-plan` exactly like `voidlight_choreographer.py`—all flags carry over, now globally available on your path.

## 🚀 Quick Start Fantasia

### Preview Without Touching Git History

```bash
python3.12 voidlight_choreographer.py -n 50 --preview-only --svg-out preview.svg
```

Expect rainbow vomit, heatmap couture, and a JSON dossier you can tuck into your captain’s coat.

### Commit For Real (Demo Branch Only)

```bash
python3.12 voidlight_choreographer.py \
  -n 120 \
  --repo . \
  --file .generated_commits.txt \
  --spread-mode week \
  --start-date 2024-01-01 \
  --end-date 2024-12-31
```

Every commit writes to `.generated_commits.txt`, stages it, and lands with historical timestamps that stay within 16 h of each other.

### Replaying a Previous Choreography

```bash
python3.12 voidlight_choreographer.py --import-json planned_commits_preview_20251004T123059Z.json
```

Override `--repo` or `--file` if you want to lash the flourish onto a new project.

## 🎛️ CLI Cheat Sheet (Velvet Edition)

| Flag | Default | Description |
|------|---------|-------------|
| `-n / --num` | required | Commit count to fabricate. |
| `--repo` | `.` | Parlor where the fantasy is staged. |
| `--file` | `.generated_commits.txt` | Where the captain scrawls each forged entry. |
| `--seed` | `None` | Random seed for reproducible chaos. |
| `--start-date` / `--end-date` | None | Explicit date window (inclusive). |
| `--start-days-ago` | `365` | Backfill window when no start/end is offered. |
| `--spread-mode` | `day` | `day` or `week` distribution. |
| `--month-weights` | `1,1,...` | Comma-separated 12-tuple of relative weights. |
| `--weekdays-only` | off | Only lash commits Monday–Friday. |
| `--color` / `--no-color` | on | Toggle the rainbow vomit in terminal output. |
| `--svg-out` | None | Write an SVG heatmap when previewing. |
| `--max-attempts-offset` | `20` | How often we try to align author/committer timestamps. |
| `--preview-only` | off | Produce previews/export JSON without committing. |
| `--import-json` | None | Load a preview JSON and replay its plan. |

## 🧪 Rituals & Aftercare

- Polish the code: `ruff format voidlight_choreographer.py`
- Sanity check bytecode: `PYTHONPYCACHEPREFIX=./.pycache python3.12 -m compileall voidlight_choreographer.py`
- Practice safe words: start every dance with `--preview-only`.
- Quarantine the spectacle on a demo branch until everyone consents.

## 🔥 Consent Clause (repeat after me)

- These commits are fiction. Don’t weaponize them.
- Announce before you unleash glitter on teammates.
- When the show ends: `git reset --hard`, delete demo branches, remove `.generated_commits.txt`.

Hydrate. Breathe. Then fire the rainbow cannon. 🏳️‍🌈

## 📜 Lore Data Artifact (lore.json)

⚔️ To empower future search, filtering, or client-side spectacle without reparsing every fragment, we forge a static index:

```bash
npm run build:lore
```

This ritual emits `public/lore.json` containing NON-DRAFT fragments (skips any with `draft: true`). Each entry includes:

- `filename` – Original lore file
- `index` – Numeric ordering token from filename prefix
- `title` – From frontmatter or first markdown heading
- `tags` – Array of frontmatter tags (empty if absent)
- `order` – Optional explicit frontmatter ordering
- `excerpt` – First ~200 chars of body (sans frontmatter)

Use this artifact for future enhancements (search UI, filters, tag clouds) without loading raw markdown at runtime.

## 🪝 Pre-Commit Lore Validation Hook

Every commit passes through a velvet gate of integrity. The Husky-driven pre-commit script runs:

```bash
npm run validate:lore
```

Installation incantation (one time after cloning):

```bash
npx husky install
```

If validation fails (missing frontmatter, duplicate indices, unsafe ordering), the commit is BLOCKED with consensual sternness. Correct the issues and retry.

Ensure `pyyaml` is installed locally if you invoke the validator directly:

```bash
python3 -m pip install pyyaml
```

Captain Velvet purrs approvingly when your lore sails clean. ✨

            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "voidlight-plan",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.12",
    "maintainer_email": null,
    "keywords": "git, commit, cli, nsfw, space-pirate",
    "author": null,
    "author_email": "Velvet Chains Maintainers <snark@voidlight.dev>",
    "download_url": "https://files.pythonhosted.org/packages/b8/c2/f6e61a6fd6d33cbed5654fcdc2619c7d5709ca41b85f9e797fb6e8568334/voidlight_plan-0.1.0.tar.gz",
    "platform": null,
    "description": "\n# \ufffd\u200d\u2620\ufe0f **VELVET CHAINS & VOIDLIGHT: THE CAPTAIN'S LEGENDARY LOG**\n\n![VELVET CHAINS & VOIDLIGHT](_LORE_/VELVET%20CHAINS%20and%20VOIDLIGHT.webp \"THE CAPTAIN'S LEGENDARY LOG \")\n\n![CC BY-SA 4.0](https://img.shields.io/badge/License-CC%20BY--SA%204.0-lightgrey.svg)\n\n**WELCOME TO THE COSMIC BRIG, MAGNIFICENT CORSAIR!** \u2693\u2728\n\nThis repository is the **MOST SPECTACULAR BDSM SPACE-PIRATE ROMANCE ENGINE** ever forged in the fires of consensual creativity - masterfully disguised as an innocent git toolchain! It **CONJURES THEATRICAL COMMIT HISTORIES** from the void, **SPINS ENCHANTING NSFW MICRO-NOVELLAS**, and **BATHES YOUR REPOSITORY** in layers of consensual decadent storytelling that would make the cosmos itself blush with delight!\n\n\ud83d\udee1\ufe0f **SACRED SAFE WORD**: _\"fiction\"_ - **READ IT TWICE**, honor it always, then proceed to witness **PURE THEATRICAL MAGIC!** \u2694\ufe0f\ud83c\udff4\u200d\u2620\ufe0f Velvet Chains & Voidlight\n\nWelcome to the brig, darling. This repository is a **BDSM space-pirate romance engine** disguised as a git toolchain. It fabricates historical commits, spins NSFW micro-novellas, and drenches your history in consensual decadence. Read the safe word (_\u201cfiction\u201d_) twice, then proceed at your own peril.\n\n[\ud83c\udff4\u200d\u2620\ufe0f For those eager to embark on the legendary campaign, set sail for the game here! \u2694\ufe0f\u2728](https://hsmalley.github.io/velvet-chains-ttrpg/)\n\n## \ud83c\udf0c **SPECTACULAR FEATURE ARSENAL** \u26a1\n\n- **DRAMATICALLY CONJURES** `N` backdated commits with timestamps that **SING IN PERFECT HARMONY** across the cosmic void! \ud83c\udfb5\n- **MASTERFULLY DISTRIBUTES** them across days/weeks with **EXQUISITE RESPECT** for weekday-only preferences and seductively weighted months! \ud83d\udcc5\n- **PREVIEW MODE EXPLODES** with **RAINBOW HEATMAP SPECTACLE**, gorgeous histograms, and **EXPORTS STUNNING JSON/SVG MASTERPIECES**! \ud83c\udf08\n- **IMPORTS & REPLAYS** previous plans to recreate the **EXACT SAME THEATRICAL MAGIC** - perfect consistency! \ud83d\udd04\n- **SHARES A TREASURE VAULT** of 3000+ **NSFW SPACE-PIRATE ROMANCE STORIES** and witty blame tags! \ud83d\udc8e\n- **DUAL-POWERED SORCERY**: Python choreography scripts + **RUST ENGINE HEART** beating with steel precision! \u2694\ufe0f\n\n## \ud83d\udd27 **SACRED CORSAIR REQUIREMENTS & RITUALS** \u2693\n\n- **Python 3.12+** - The **MAGNIFICENT CHOREOGRAPHY ENGINE** that orchestrates temporal magic (`voidlight_choreographer.py`)! \ud83d\udc0d\u2728\n- **Rust (cargo 1.70+)** - The **STEEL-FORGED BINARY HEART** powering git hooks & `git voidlight` subcommands with **UNSTOPPABLE PRECISION**! \ud83e\udd80\u2694\ufe0f\n- **Optional Excellence**: `pip install ruff` to make your **LINTING DOMINATRIX PURR** with satisfaction! \ud83d\udc85\n\nInitial setup:\n\n```bash\npython3.12 -m pip install --upgrade ruff\nchmod +x voidlight_choreographer.py\n```\n\n### \u26d3\ufe0f Auto-Hook: Snark at Commit Time\n\nForge the Rust binary, then let Git whisper it into every commit message:\n\n```bash\ncargo install --path voidlight_engine --force\nrm -f .git/hooks/prepare-commit-msg\nln -s \"$(pwd)/voidlight_hooks/voidlight-commit-ritual\" .git/hooks/prepare-commit-msg\n```\n\n> Already published to crates.io? Swap the first line for `cargo install voidlight`.\n\nCorporate shackles hate symlinks? Copy instead:\n\n```bash\ncp voidlight_hooks/voidlight-commit-ritual .git/hooks/prepare-commit-msg\n```\n\nPrefer a version-controlled dungeon?\n\n```bash\ngit config core.hooksPath voidlight_hooks\n```\n\nThe hook rebuilds the Rust binary when needed and then laces a 4-sentence kink novella into every commit.\n\nShortcut: once `git-voidlight` is on your `$PATH`, simply run `git voidlight install-hook` (add `--force` to overwrite an existing hook).\n\n### \ud83d\ude80 `git voidlight` \u2014 Subcommand of Desire\n\nPromote the binary into a first-class git command:\n\n```bash\ncargo install --path voidlight_engine --force\n```\n\nThen either call it directly or wrap an alias:\n\n```bash\ngit config alias.voidlight '!git-voidlight'\n```\n\nUsage that stages, commits, and appends a flourish in one breath:\n\n```bash\ngit voidlight --commit -a -m \"Refactor the warp-drive leash\" -- -- path/to/file\n```\n\nSkip `--commit` to simply print a fresh tale to stdout\u2014perfect for `CAPTAINS_LOG` lore or issue comment theatrics.\n\n### \ud83d\udc0d Python Package (`voidlight-plan`)\n\nPrefer the Python planner? Package it as a CLI:\n\n```bash\npip install .\nvoidlight-plan --help\n```\n\nOr pull straight from the repo:\n\n```bash\npip install git+https://github.com/velvet-chains/velvet-chains.git\n```\n\nUse `voidlight-plan` exactly like `voidlight_choreographer.py`\u2014all flags carry over, now globally available on your path.\n\n## \ud83d\ude80 Quick Start Fantasia\n\n### Preview Without Touching Git History\n\n```bash\npython3.12 voidlight_choreographer.py -n 50 --preview-only --svg-out preview.svg\n```\n\nExpect rainbow vomit, heatmap couture, and a JSON dossier you can tuck into your captain\u2019s coat.\n\n### Commit For Real (Demo Branch Only)\n\n```bash\npython3.12 voidlight_choreographer.py \\\n  -n 120 \\\n  --repo . \\\n  --file .generated_commits.txt \\\n  --spread-mode week \\\n  --start-date 2024-01-01 \\\n  --end-date 2024-12-31\n```\n\nEvery commit writes to `.generated_commits.txt`, stages it, and lands with historical timestamps that stay within 16 h of each other.\n\n### Replaying a Previous Choreography\n\n```bash\npython3.12 voidlight_choreographer.py --import-json planned_commits_preview_20251004T123059Z.json\n```\n\nOverride `--repo` or `--file` if you want to lash the flourish onto a new project.\n\n## \ud83c\udf9b\ufe0f CLI Cheat Sheet (Velvet Edition)\n\n| Flag | Default | Description |\n|------|---------|-------------|\n| `-n / --num` | required | Commit count to fabricate. |\n| `--repo` | `.` | Parlor where the fantasy is staged. |\n| `--file` | `.generated_commits.txt` | Where the captain scrawls each forged entry. |\n| `--seed` | `None` | Random seed for reproducible chaos. |\n| `--start-date` / `--end-date` | None | Explicit date window (inclusive). |\n| `--start-days-ago` | `365` | Backfill window when no start/end is offered. |\n| `--spread-mode` | `day` | `day` or `week` distribution. |\n| `--month-weights` | `1,1,...` | Comma-separated 12-tuple of relative weights. |\n| `--weekdays-only` | off | Only lash commits Monday\u2013Friday. |\n| `--color` / `--no-color` | on | Toggle the rainbow vomit in terminal output. |\n| `--svg-out` | None | Write an SVG heatmap when previewing. |\n| `--max-attempts-offset` | `20` | How often we try to align author/committer timestamps. |\n| `--preview-only` | off | Produce previews/export JSON without committing. |\n| `--import-json` | None | Load a preview JSON and replay its plan. |\n\n## \ud83e\uddea Rituals & Aftercare\n\n- Polish the code: `ruff format voidlight_choreographer.py`\n- Sanity check bytecode: `PYTHONPYCACHEPREFIX=./.pycache python3.12 -m compileall voidlight_choreographer.py`\n- Practice safe words: start every dance with `--preview-only`.\n- Quarantine the spectacle on a demo branch until everyone consents.\n\n## \ud83d\udd25 Consent Clause (repeat after me)\n\n- These commits are fiction. Don\u2019t weaponize them.\n- Announce before you unleash glitter on teammates.\n- When the show ends: `git reset --hard`, delete demo branches, remove `.generated_commits.txt`.\n\nHydrate. Breathe. Then fire the rainbow cannon. \ud83c\udff3\ufe0f\u200d\ud83c\udf08\n\n## \ud83d\udcdc Lore Data Artifact (lore.json)\n\n\u2694\ufe0f To empower future search, filtering, or client-side spectacle without reparsing every fragment, we forge a static index:\n\n```bash\nnpm run build:lore\n```\n\nThis ritual emits `public/lore.json` containing NON-DRAFT fragments (skips any with `draft: true`). Each entry includes:\n\n- `filename` \u2013 Original lore file\n- `index` \u2013 Numeric ordering token from filename prefix\n- `title` \u2013 From frontmatter or first markdown heading\n- `tags` \u2013 Array of frontmatter tags (empty if absent)\n- `order` \u2013 Optional explicit frontmatter ordering\n- `excerpt` \u2013 First ~200 chars of body (sans frontmatter)\n\nUse this artifact for future enhancements (search UI, filters, tag clouds) without loading raw markdown at runtime.\n\n## \ud83e\ude9d Pre-Commit Lore Validation Hook\n\nEvery commit passes through a velvet gate of integrity. The Husky-driven pre-commit script runs:\n\n```bash\nnpm run validate:lore\n```\n\nInstallation incantation (one time after cloning):\n\n```bash\nnpx husky install\n```\n\nIf validation fails (missing frontmatter, duplicate indices, unsafe ordering), the commit is BLOCKED with consensual sternness. Correct the issues and retry.\n\nEnsure `pyyaml` is installed locally if you invoke the validator directly:\n\n```bash\npython3 -m pip install pyyaml\n```\n\nCaptain Velvet purrs approvingly when your lore sails clean. \u2728\n",
    "bugtrack_url": null,
    "license": "MIT",
    "summary": "BDSM space-pirate commit planner and preview engine",
    "version": "0.1.0",
    "project_urls": {
        "Homepage": "https://github.com/hsmalley/velvet-chains",
        "Repository": "https://github.com/hsmalley/velvet-chains"
    },
    "split_keywords": [
        "git",
        " commit",
        " cli",
        " nsfw",
        " space-pirate"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "453461c2e84bfec6da1cf1e17e2f60f19816b051e21c4877a6e5cd81a1d186ed",
                "md5": "f514115728f22d19bc9b9fe15f869f21",
                "sha256": "0762bc61a7a8b7a5b0724793f2bbb1d902cf37f9772af423f9ad98743969343b"
            },
            "downloads": -1,
            "filename": "voidlight_plan-0.1.0-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "f514115728f22d19bc9b9fe15f869f21",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.12",
            "size": 16093,
            "upload_time": "2025-10-08T20:25:57",
            "upload_time_iso_8601": "2025-10-08T20:25:57.366891Z",
            "url": "https://files.pythonhosted.org/packages/45/34/61c2e84bfec6da1cf1e17e2f60f19816b051e21c4877a6e5cd81a1d186ed/voidlight_plan-0.1.0-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "b8c2f6e61a6fd6d33cbed5654fcdc2619c7d5709ca41b85f9e797fb6e8568334",
                "md5": "3bc547bd5cf3427703bc5820c09fd497",
                "sha256": "e553ecfc07710731da0d933cf3eb485afb269f537615e0efa14285189800a9d4"
            },
            "downloads": -1,
            "filename": "voidlight_plan-0.1.0.tar.gz",
            "has_sig": false,
            "md5_digest": "3bc547bd5cf3427703bc5820c09fd497",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.12",
            "size": 20002,
            "upload_time": "2025-10-08T20:25:59",
            "upload_time_iso_8601": "2025-10-08T20:25:59.302640Z",
            "url": "https://files.pythonhosted.org/packages/b8/c2/f6e61a6fd6d33cbed5654fcdc2619c7d5709ca41b85f9e797fb6e8568334/voidlight_plan-0.1.0.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-10-08 20:25:59",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "hsmalley",
    "github_project": "velvet-chains",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "lcname": "voidlight-plan"
}