vibe-ideas 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 evolv3-ai
+
+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.

package/README.md

@@ -0,0 +1,275 @@
+# vibe-ideas
+
+> Random coding project ideas for AI agents and developers. 298 curated ideas, delivered instantly.
+
+```bash
+npx vibe-ideas random     # Get a random project (JSON for agents)
+npx vibe-ideas random --format human  # Human-readable output
+```
+
+## Install
+
+**No install (via npx):**
+```bash
+npx vibe-ideas random
+```
+
+**Global install:**
+```bash
+npm install -g vibe-ideas
+vibe random
+```
+
+Requires Node.js ≥ 18.
+
+## Quick Start
+
+```bash
+# Get any random project
+npx vibe-ideas random
+
+# Reproducible result (for testing)
+npx vibe-ideas random --seed 42
+
+# Browse as a human
+npx vibe-ideas random --format human
+```
+
+## Commands
+
+### `vibe random`
+
+Return random project idea(s). This is the default command.
+
+```bash
+# Single random project (default)
+npx vibe-ideas random
+
+# Multiple ideas
+npx vibe-ideas random --count 3
+
+# Filtered random
+npx vibe-ideas random --level beginner --category web
+
+# Reproducible (same seed = same result)
+npx vibe-ideas random --seed 42
+```
+
+**Example output:**
+```bash
+$ npx vibe-ideas random --seed 42
+```
+```json
+{
+  "id": "c_mcbdv98cxda9fipfliwq9b4gtxox",
+  "title": "Space Invaders using OpenGL",
+  "description": "No description available",
+  "level": "intermediate",
+  "category": "game dev",
+  "language": "JavaScript",
+  "techStack": [],
+  "source": "Xtremilicious/projectlearn-project-based-learning"
+}
+```
+
+**Human format:**
+```bash
+$ npx vibe-ideas random --seed 42 --format human
+```
+```
+📦 Space Invaders using OpenGL
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Level:    intermediate
+Category: game dev
+Language: JavaScript
+Source:   Xtremilicious/projectlearn-project-based-learning
+
+No description available
+```
+
+**Multiple results:**
+```bash
+$ npx vibe-ideas random --count 3 --seed 99
+```
+```json
+[
+  {
+    "id": "fp_mcbdv9865l23ah7zzih7sp7u7zad0a",
+    "title": "Simple Online Store",
+    "level": "intermediate",
+    "category": "general",
+    "language": "JavaScript",
+    "techStack": [],
+    "source": "florinpop17/app-ideas"
+  },
+  {
+    "id": "c_mcbdv98d4igovdv3pu5zblpopm2sid",
+    "title": "Facial Landmark Detection",
+    "level": "intermediate",
+    "category": "data science",
+    "language": "JavaScript",
+    "techStack": [],
+    "source": "Xtremilicious/projectlearn-project-based-learning"
+  },
+  {
+    "id": "c_mcbdv98ct2cxjmmwwt8awe6b1qp9ib",
+    "title": "Flipping UNO Cards using only CSS",
+    "level": "intermediate",
+    "category": "web",
+    "language": "JavaScript",
+    "techStack": ["CSS"],
+    "source": "Xtremilicious/projectlearn-project-based-learning"
+  }
+]
+```
+
+---
+
+### `vibe list`
+
+List all projects matching your filters.
+
+```bash
+# All beginner projects
+npx vibe-ideas list --level beginner
+
+# First 5 web projects
+npx vibe-ideas list --category web --count 5
+
+# All Python projects (human-readable)
+npx vibe-ideas list --language Python --format human
+```
+
+---
+
+### `vibe get <id>`
+
+Get a specific project by ID.
+
+```bash
+$ npx vibe-ideas get fp_mcbdv984s6vis732zik4la17lr3isc
+```
+```json
+{
+  "id": "fp_mcbdv984s6vis732zik4la17lr3isc",
+  "title": "Calculator CLI",
+  "description": "Create a basic calculator with addition feature.",
+  "level": "intermediate",
+  "category": "general",
+  "language": "JavaScript",
+  "techStack": [],
+  "source": "florinpop17/app-ideas"
+}
+```
+
+---
+
+### `vibe filters`
+
+Show all valid filter values. Use this to discover what's available.
+
+```bash
+$ npx vibe-ideas filters
+```
+```json
+{
+  "level": ["advanced", "beginner", "intermediate"],
+  "category": ["data science", "game dev", "general", "mobile", "web"],
+  "language": ["C#", "Go", "JavaScript", "PHP", "Python", "Ruby", "Rust", "Swift", "TypeScript"]
+}
+```
+
+## Output Schema
+
+### JSON (default)
+
+```json
+{
+  "id": "fp_mcbdv984s6vis732zik4la17lr3isc",
+  "title": "Calculator CLI",
+  "description": "Create a basic calculator with addition feature.",
+  "level": "intermediate",
+  "category": "general",
+  "language": "JavaScript",
+  "techStack": [],
+  "source": "florinpop17/app-ideas"
+}
+```
+
+### Error Response
+
+```json
+{
+  "error": "No projects match filters",
+  "code": "ERR_NO_MATCH",
+  "filters": { "level": "advanced", "category": "mobile" }
+}
+```
+
+### Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | No results match filters |
+| 2 | Invalid input |
+
+## AI Agent Integration
+
+Built for programmatic use. Pipe-friendly, deterministic, schema-stable.
+
+```bash
+# Get a title for your next build
+TITLE=$(npx vibe-ideas random --seed $RANDOM | jq -r .title)
+echo "Building: $TITLE"
+
+# Check available languages before filtering
+LANGUAGES=$(npx vibe-ideas filters | jq -r '.language | join(", ")')
+echo "Supported languages: $LANGUAGES"
+
+# Filter and validate
+npx vibe-ideas random --level beginner --language Python --format json | jq .
+
+# Reproducible builds (same seed = same project for testing)
+npx vibe-ideas random --seed 12345 --format json
+```
+
+### Filter Reference
+
+| Filter | Valid Values |
+|--------|--------------|
+| `--level` | `beginner`, `intermediate`, `advanced` |
+| `--category` | `data science`, `game dev`, `general`, `mobile`, `web` |
+| `--language` | `C#`, `Go`, `JavaScript`, `PHP`, `Python`, `Ruby`, `Rust`, `Swift`, `TypeScript` |
+
+## Flags Reference
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--level` | Filter by difficulty | — |
+| `--category` | Filter by category | — |
+| `--language` | Filter by language | — |
+| `--format` | Output format: `json`, `human`, `text` | `json` |
+| `--count` | Number of results | `1` (random), `0` (list = all) |
+| `--seed` | Reproducible randomization | — |
+
+## Data Attribution
+
+298 project ideas curated from the following open-source repositories (all MIT licensed):
+
+| Source | Projects | License | Link |
+|--------|----------|---------|------|
+| florinpop17/app-ideas | 88 | MIT | [GitHub](https://github.com/florinpop17/app-ideas) |
+| Xtremilicious/projectlearn-project-based-learning | 202 | MIT | [GitHub](https://github.com/Xtremilicious/projectlearn-project-based-learning) |
+| karan/Projects | 15 | MIT | [GitHub](https://github.com/karan/Projects) |
+| jaypancholi94/spellbook | 1 | MIT | [GitHub](https://github.com/jaypancholi94/spellbook) |
+
+Each project in the dataset includes a `source` field attributing it to its original repository.
+
+## Contributing
+
+PRs welcome for new project ideas or CLI improvements.
+
+## License
+
+MIT - see [LICENSE](LICENSE) for details.