@hasna/prompts 0.1.0

package/README.md

@@ -0,0 +1,269 @@
+# @hasna/prompts
+
+Reusable prompt library for AI agents. Save prompts from any session, search them instantly, render templates, and reuse across agents via MCP, CLI, or SDK.
+
+```bash
+bun install -g @hasna/prompts
+```
+
+---
+
+## Quick Start
+
+```bash
+# Save a prompt
+open-prompts save "TypeScript Code Review" \
+  --body "Review this TypeScript code for correctness, types, and style:\n\n{{code}}" \
+  --tags "code,review,typescript" \
+  --collection "code"
+
+# Use it (prints body, increments counter)
+open-prompts use typescript-code-review
+
+# Render a template
+open-prompts render typescript-code-review --var code="$(cat myfile.ts)"
+
+# Search
+open-prompts search "code review"
+```
+
+---
+
+## MCP Server
+
+Add to your Claude/agent config:
+
+```json
+{
+  "mcpServers": {
+    "prompts": {
+      "command": "open-prompts-mcp"
+    }
+  }
+}
+```
+
+Then in any AI session:
+
+```
+Save this as a reusable prompt called "deploy-checklist"
+→ prompts_save(title="Deploy Checklist", body="...", collection="devops")
+
+Later, in any session:
+→ prompts_use("deploy-checklist")    // body + increments counter
+→ prompts_render("deploy-checklist", { env: "production" })
+→ prompts_search("deploy")
+```
+
+### Available MCP Tools
+
+| Tool | Description |
+|------|-------------|
+| `prompts_save` | Create or update a prompt (upsert by slug) |
+| `prompts_get` | Get by ID, slug, or partial ID |
+| `prompts_list` | List with filters (collection, tags, is_template, source) |
+| `prompts_use` | Get body + increment use counter |
+| `prompts_delete` | Delete a prompt |
+| `prompts_update` | Update fields |
+| `prompts_search` | FTS5 full-text search (BM25 ranking) |
+| `prompts_similar` | Find similar prompts by tag overlap |
+| `prompts_render` | Fill `{{variables}}` in a template |
+| `prompts_list_templates` | List templates only |
+| `prompts_variables` | Inspect template variables |
+| `prompts_validate_vars` | Check which vars are required/optional/extra |
+| `prompts_collections` | List collections with counts |
+| `prompts_move` | Move prompt to a different collection |
+| `prompts_ensure_collection` | Create a collection |
+| `prompts_history` | Version history |
+| `prompts_restore` | Restore previous version |
+| `prompts_export` | Export as JSON |
+| `prompts_import` | Import from JSON array |
+| `prompts_register_agent` | Register an agent for attribution |
+| `prompts_stats` | Usage stats |
+
+---
+
+## CLI Reference
+
+```bash
+open-prompts save <title>        # Save a prompt (--body, --file, or stdin)
+open-prompts use <id|slug>       # Get body, increment counter
+open-prompts get <id|slug>       # Get details without incrementing
+open-prompts list                # List all prompts
+open-prompts search <query>      # Full-text search
+open-prompts render <id> -v k=v  # Render template with variables
+open-prompts templates           # List templates
+open-prompts inspect <id>        # Show template variables
+open-prompts update <id>         # Update fields
+open-prompts delete <id>         # Delete
+open-prompts history <id>        # Version history
+open-prompts restore <id> <v>    # Restore version
+open-prompts collections         # List collections
+open-prompts move <id> <col>     # Move to collection
+open-prompts export              # Export as JSON
+open-prompts import <file>       # Import from JSON
+open-prompts stats               # Usage statistics
+
+# Global flags
+open-prompts list --json         # Machine-readable output
+open-prompts list -c code        # Filter by collection
+open-prompts list -t review,ts   # Filter by tags
+```
+
+---
+
+## Templates
+
+Prompts with `{{variable}}` syntax are automatically detected as templates.
+
+```bash
+# Save a template
+open-prompts save "PR Description" \
+  --body "Write a PR description for this {{language|TypeScript}} change:\n\n{{diff}}\n\nFocus on: {{focus|what changed and why}}"
+
+# Inspect variables
+open-prompts inspect pr-description
+# Variables for pr-description:
+#   language  optional  (default: "TypeScript")
+#   diff      required
+#   focus     optional  (default: "what changed and why")
+
+# Render
+open-prompts render pr-description \
+  --var diff="$(git diff main)" \
+  --var language=Go
+```
+
+**Syntax:**
+- `{{name}}` — required variable
+- `{{name|default value}}` — optional variable with default
+
+---
+
+## SDK
+
+```typescript
+import {
+  savePrompt, getPrompt, usePrompt, listPrompts,
+  searchPrompts, renderTemplate, extractVariables,
+  upsertPrompt, importFromJson, exportToJson
+} from "@hasna/prompts"
+
+// Save from a session
+const { prompt } = await upsertPrompt({
+  title: "Summarize Issue",
+  body: "Summarize this GitHub issue in 3 bullets:\n\n{{issue_body}}",
+  collection: "github",
+  tags: ["github", "summary"],
+  source: "ai-session",
+})
+
+// Use it
+const p = usePrompt("summarize-issue")
+console.log(p.body)
+
+// Render a template
+const result = renderTemplate(p.body, { issue_body: "..." })
+console.log(result.rendered)
+console.log(result.missing_vars)   // vars not provided
+console.log(result.used_defaults)  // vars that fell back to defaults
+
+// Search
+const results = searchPrompts("github issue", { collection: "github" })
+
+// Import from Claude Code slash commands
+import { importFromClaudeCommands } from "@hasna/prompts"
+importFromClaudeCommands([
+  { filename: "code-review.md", content: fs.readFileSync(".claude/commands/code-review.md", "utf-8") }
+])
+```
+
+---
+
+## REST API
+
+```bash
+open-prompts-serve   # starts on port 19430
+```
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/api/prompts` | List (supports `?collection=`, `?tags=`, `?templates=1`, `?limit=`) |
+| POST | `/api/prompts` | Create/upsert |
+| GET | `/api/prompts/:id` | Get by ID or slug |
+| PUT | `/api/prompts/:id` | Update |
+| DELETE | `/api/prompts/:id` | Delete |
+| POST | `/api/prompts/:id/use` | Use (increment counter) |
+| POST | `/api/prompts/:id/render` | Render template `{ vars: {...} }` |
+| GET | `/api/prompts/:id/history` | Version history |
+| POST | `/api/prompts/:id/restore` | Restore version `{ version: N }` |
+| GET | `/api/prompts/:id/similar` | Similar prompts |
+| GET | `/api/prompts/:id/variables` | Template variables |
+| GET | `/api/search?q=` | Full-text search |
+| GET | `/api/templates` | Templates only |
+| GET | `/api/collections` | All collections |
+| POST | `/api/collections` | Create collection |
+| GET | `/api/stats` | Usage stats |
+| GET | `/api/export` | Export JSON |
+| POST | `/api/import` | Import JSON |
+
+---
+
+## Web Dashboard
+
+```bash
+open-prompts-serve   # start API on :19430
+# open dashboard/dist/index.html or run dashboard dev server
+```
+
+Features: browse/search prompts, view/edit body, template renderer with variable inputs, collection sidebar, version history, stats view, create modal.
+
+---
+
+## Data Model
+
+Each prompt has:
+
+| Field | Description |
+|-------|-------------|
+| `id` | Sequential ID: `PRMT-00001` |
+| `slug` | Unique kebab-case slug (auto-generated from title) |
+| `title` | Human display name |
+| `body` | Prompt content |
+| `collection` | Namespace (default: `default`) |
+| `tags` | String array for filtering |
+| `variables` | Detected `{{vars}}` with required/default info |
+| `is_template` | Auto-set when body contains `{{}}` |
+| `source` | `manual` \| `ai-session` \| `imported` |
+| `use_count` | Times retrieved via `use` |
+| `last_used_at` | Last use timestamp |
+| `version` | Increments on every edit |
+
+---
+
+## Database Location
+
+Priority order:
+1. `PROMPTS_DB_PATH` env var
+2. `PROMPTS_DB_SCOPE=project` — uses `.prompts/prompts.db` at git root
+3. Global: `~/.prompts/prompts.db`
+
+---
+
+## Import from Claude Code Slash Commands
+
+```bash
+# Export existing slash commands as prompts
+for f in .claude/commands/*.md; do
+  name=$(basename "$f" .md)
+  open-prompts save "$name" --file "$f" --collection claude-commands --tags "slash-command"
+done
+```
+
+Or programmatically via SDK using `importFromClaudeCommands()`.
+
+---
+
+## License
+
+Apache-2.0

package/dashboard/README.md

@@ -0,0 +1,73 @@
+# React + TypeScript + Vite
+
+This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
+
+Currently, two official plugins are available:
+
+- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Oxc](https://oxc.rs)
+- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/)
+
+## React Compiler
+
+The React Compiler is not enabled on this template because of its impact on dev & build performances. To add it, see [this documentation](https://react.dev/learn/react-compiler/installation).
+
+## Expanding the ESLint configuration
+
+If you are developing a production application, we recommend updating the configuration to enable type-aware lint rules:
+
+```js
+export default defineConfig([
+  globalIgnores(['dist']),
+  {
+    files: ['**/*.{ts,tsx}'],
+    extends: [
+      // Other configs...
+
+      // Remove tseslint.configs.recommended and replace with this
+      tseslint.configs.recommendedTypeChecked,
+      // Alternatively, use this for stricter rules
+      tseslint.configs.strictTypeChecked,
+      // Optionally, add this for stylistic rules
+      tseslint.configs.stylisticTypeChecked,
+
+      // Other configs...
+    ],
+    languageOptions: {
+      parserOptions: {
+        project: ['./tsconfig.node.json', './tsconfig.app.json'],
+        tsconfigRootDir: import.meta.dirname,
+      },
+      // other options...
+    },
+  },
+])
+```
+
+You can also install [eslint-plugin-react-x](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-dom) for React-specific lint rules:
+
+```js
+// eslint.config.js
+import reactX from 'eslint-plugin-react-x'
+import reactDom from 'eslint-plugin-react-dom'
+
+export default defineConfig([
+  globalIgnores(['dist']),
+  {
+    files: ['**/*.{ts,tsx}'],
+    extends: [
+      // Other configs...
+      // Enable lint rules for React
+      reactX.configs['recommended-typescript'],
+      // Enable lint rules for React DOM
+      reactDom.configs.recommended,
+    ],
+    languageOptions: {
+      parserOptions: {
+        project: ['./tsconfig.node.json', './tsconfig.app.json'],
+        tsconfigRootDir: import.meta.dirname,
+      },
+      // other options...
+    },
+  },
+])
+```

package/dist/cli/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env bun
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/cli/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.tsx"],"names":[],"mappings":""}