@menasehk/sera 1.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tagcodi
+
+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,376 @@
+# SERA / ስራ — Your AI-Powered Work Command Center
+
+> **ስራ** means *work* in Amharic. Manage tasks, appointments, notes, calendar, contacts, and system automation through natural language — directly from your terminal.
+
+```
+╔══════════════════════════════════════════════════╗
+║                                                  ║
+║   ███████╗███████╗██████╗  █████╗                ║
+║   ██╔════╝██╔════╝██╔══██╗██╔══██╗               ║
+║   ██╔████║██║   ██║██║   ██║ ███████║          ║
+║   ██║╚███║██║   ██║╚██╗ ██╔╝ ██╔══██║          ║
+║   ██║ ╚██║╚██████╔╝ ╚████╔╝  ██║  ██║          ║
+║   ╚═╝  ╚═╝ ╚═════╝   ╚═══╝   ╚═╝  ╚═╝          ║
+║                                                 ║
+║   Your AI-Powered Daily Command Center  v1.0.0  ║
+╚═════════════════════════════════════════════════╝
+```
+
+---
+
+## What is SERA?
+
+SERA is a CLI productivity assistant powered by your choice of AI model. You talk to it in plain English and it acts — creating tasks, scheduling appointments, running shell commands, querying your custom databases, and more. It runs entirely on your machine with full access to your filesystem, controlled by a granular permission system.
+
+**Supported AI providers:** OpenAI · Anthropic (Claude) · Ollama (local) · Groq
+
+---
+
+## Installation
+
+**Prerequisites:** Node.js 18 or higher
+
+```bash
+# 1. Clone and enter the project
+git clone <repo-url>
+cd sera
+
+# 2. Install dependencies
+npm install
+
+# 3. Build
+npm run build
+
+# 4. Install globally
+npm install -g .
+```
+
+After installation, run `sera` from any directory.
+
+---
+
+## Quick Start
+
+```bash
+sera setup      # Configure your AI provider and preferences (run this first)
+sera            # Launch interactive AI chat
+sera today      # See today's tasks and appointments
+sera how        # Full usage guide
+```
+
+---
+
+## Configuration
+
+Run `sera setup` to configure SERA interactively. Settings are saved to `~/.sera/config.json`.
+
+| Setting | Description |
+|---|---|
+| **AI Provider** | OpenAI, Anthropic, Ollama, or Groq |
+| **Model** | e.g. `gpt-4o`, `claude-sonnet-4-20250514`, `llama3.1` |
+| **API Key** | Your provider API key (not needed for Ollama) |
+| **Storage** | JSON (default) or SQLite |
+| **Permissions** | How strictly to ask before running tools |
+
+```bash
+sera config           # View current settings
+sera config --reset   # Reset and re-run setup
+```
+
+---
+
+## Commands
+
+### Core
+
+| Command | Description |
+|---|---|
+| `sera` | Start interactive AI chat session |
+| `sera setup` | Run the interactive setup wizard |
+| `sera today` | Today's summary: tasks, appointments, overdue items |
+| `sera how` | Full usage guide with examples |
+
+### Tasks
+
+```bash
+sera add "Fix the login bug"                    # Quick-add (AI infers priority)
+sera add "Submit report" -p high -d friday      # With priority and due date
+sera done "Fix the login bug"                   # Mark done by name
+sera tasks                                      # View active tasks
+sera tasks --all                                # Include done & cancelled
+sera tasks --priority urgent                    # Filter by priority
+sera tasks --status in_progress                 # Filter by status
+```
+
+**Priority levels:** `low` · `medium` · `high` · `urgent`
+
+**In chat:**
+```
+"Mark all overdue tasks as cancelled"
+"Show me everything due this week"
+"What's still in progress?"
+```
+
+### Appointments & Reminders
+
+```bash
+sera cal                       # Upcoming appointments (next 7 days)
+sera cal --days 30             # Next 30 days
+sera remind 30 "Take meds"     # Desktop notification in 30 minutes
+```
+
+**In chat:**
+```
+"Add dentist appointment next Tuesday 2pm"
+"Reschedule my 3pm meeting to 4:30pm"
+"Remind me to call mom at 6pm"
+"What do I have this week?"
+```
+
+### Notes
+
+```bash
+sera note "Buy oat milk"                  # Quick capture
+sera note "Meeting notes" -t work,q2      # With tags
+sera notes                                # View all notes
+```
+
+**In chat:**
+```
+"Search my notes for anything about the Q2 launch"
+"Summarise my work notes from this week"
+```
+
+### Custom Database Collections
+
+SERA can create and manage custom data collections for anything you want to track — expenses, contacts, gym logs, medications, habits, reading lists, and more.
+
+```bash
+sera db                          # List all collections
+sera db --show expenses          # View records in a collection
+sera db --schema expenses        # View the schema (fields and types)
+```
+
+**In chat:**
+```
+"Create a collection to track my expenses with: amount, category, description, date"
+"Add an expense: $45 lunch, category: food"
+"Show all expenses over $100 this month"
+"Add a 'notes' field to my expenses collection"
+"Create a contacts table: name, email, phone, company"
+"Delete the old habits collection"
+"Back up all my data"
+```
+
+**Field types:** `string` · `number` · `boolean` · `date` · `json`
+
+### AI Memory
+
+SERA remembers facts about you across sessions — name, timezone, preferences, work context, goals, and more. No prompting needed; it picks things up naturally from your conversations.
+
+```bash
+sera memory                        # View all stored memories
+sera memory --category work        # Filter by category
+sera memory --forget "timezone"    # Delete a specific memory
+sera memory --forget-all           # Clear everything
+```
+
+**In chat:**
+```
+"Remember that I prefer concise answers"
+"My timezone is CET"
+"Forget that I work at Acme"
+```
+**Slash command (interactive mode):** `/memory`
+
+**Categories:** `personal` · `work` · `preferences` · `health` · `goals` · `context`
+
+### Calendar & Contacts
+
+SERA can add events to your calendar and contacts to your address book directly from chat.
+
+**macOS** — uses Calendar.app and Contacts.app natively (no extra setup).
+**Other platforms** — creates an `.ics` or `.vcf` file and opens it with your default app.
+
+```
+"Add a dentist appointment on Friday at 3pm"
+"Create an event: Team standup every Monday 9am"
+"Add John Smith to my contacts, phone 555-1234, email john@acme.com"
+"Look up Alice in my contacts"
+"Add this to Google Calendar: product launch party, Saturday 7pm"
+```
+
+SERA will always ask your permission before touching your calendar or contacts.
+
+### Background Daemon
+
+The daemon runs quietly in the background and sends desktop notifications so you never miss anything — even when SERA isn't open.
+
+```bash
+sera daemon start      # Start the background monitor
+sera daemon stop       # Stop it
+sera daemon restart    # Restart
+sera daemon status     # Is it running?
+sera daemon logs       # View recent log output
+sera daemon install    # Auto-start at login (launchd on macOS, systemd on Linux)
+```
+
+**What the daemon monitors:**
+- Task overdue alerts — fires the moment a task deadline passes
+- Appointment reminders — 15 minutes before + when it starts
+- Morning briefing — 9 AM summary of the day's tasks and appointments
+
+### Backup & Export
+
+```bash
+sera export                          # Export all data → ~/sera-backup-<date>.json
+sera export -o ~/my-backup.json      # Export to a specific path
+sera import ~/my-backup.json         # Restore from a backup file
+```
+
+### System Automation (in chat)
+
+SERA can run shell commands, read/write files, and interact with your OS — subject to your permission settings.
+
+```
+"Run my backup script at ~/scripts/backup.sh"
+"List all PDF files in my Downloads folder"
+"Create a folder called Projects on my Desktop"
+"Open github.com in my browser"
+"What's my current git branch?"
+"Copy 'hello world' to my clipboard"
+"Show me system memory usage"
+```
+
+---
+
+## In-Chat Slash Commands
+
+While in an interactive session (`sera`), these commands are available:
+
+| Command | Description |
+|---|---|
+| `/help` | Show this list |
+| `/guide` | Full usage guide with examples |
+| `/clear` | Clear the conversation and screen |
+| `/history` | Recent chat messages |
+| `/tools` | All available AI tools by category and risk level |
+| `/perms` | Saved permission rules |
+| `/config` | Current configuration |
+| `/db` | Quick view of all custom collections |
+| `/memory` | View stored memories about you |
+| `/tokens` | Current conversation message count |
+| `/quit` | Exit SERA |
+
+---
+
+## Permissions
+
+SERA asks for confirmation before running tools that touch your system. You control how strict this is.
+
+**Permission levels** (set during `sera setup`):
+
+- `ask` — prompt for every tool call *(most secure)*
+- `auto` — auto-approve low-risk tools, ask for high-risk
+- `allow` — allow everything without asking *(fastest)*
+
+When prompted, you can choose:
+- **Allow once** — allow this single call
+- **Always allow** — save a permanent rule for this tool
+- **Allow this session** — allow until you exit
+- **Deny** / **Deny always**
+
+```bash
+sera perms              # View saved rules
+sera perms --clear      # Reset all rules
+```
+
+---
+
+## Error Handling
+
+SERA gives clear, actionable error messages. For example, if your API key doesn't have access to a model:
+
+```
+  ✖  Project does not have access to model gpt-4-turbo  [model_not_found]
+
+  ◆  Run  sera setup  to pick a different model (e.g. gpt-4o-mini).
+```
+
+SERA also automatically retries on rate limits (429) and transient server errors (5xx) with exponential backoff, so temporary blips don't interrupt your workflow.
+
+---
+
+## Data & Privacy
+
+All your data lives locally on your machine:
+
+| File | Contents |
+|---|---|
+| `~/.sera/config.json` | Configuration and permission rules |
+| `~/.sera/data.json` | Tasks, appointments, and notes |
+| `~/.sera/collections.json` | Custom database collections |
+
+Your data is never sent anywhere other than your chosen AI provider's API for chat completions. SERA does not phone home.
+
+---
+
+## Development
+
+```bash
+npm run build            # Compile TypeScript → dist/
+npm run dev              # Run directly with ts-node (no build step)
+npm test                 # Run the test suite
+npm run test:watch       # Watch mode
+npm run test:coverage    # With coverage report
+```
+
+**Test suite covers:**
+- Shell command sanitization (safe commands + 14 blocked dangerous patterns)
+- Retry logic (rate limits, server errors, network failures, custom predicates)
+- AI provider response parsing (OpenAI + Anthropic, including tool calls)
+- Database CRUD, schema management, field validation, backup/restore
+
+### Project Structure
+
+```
+src/
+├── index.ts              # CLI commands, UI rendering, interactive loop
+├── types.ts              # Shared TypeScript interfaces
+├── providers/            # AI provider adapters
+│   ├── openai.ts         # OpenAI & Groq (same API format)
+│   ├── anthropic.ts      # Anthropic Claude
+│   ├── ollama.ts         # Ollama (local models)
+│   └── index.ts          # Provider factory
+├── tools/                # AI-callable tools
+│   ├── shell.ts          # Shell command execution (with sanitization)
+│   ├── filesystem.ts     # File read/write/list/delete
+│   ├── browser.ts        # Open URL, web search
+│   ├── system.ts         # System info, datetime, clipboard
+│   ├── notification.ts   # Desktop notifications
+│   ├── tasks.ts          # Task, appointment & note tools
+│   ├── database.ts       # Custom collection manager + tools
+│   └── index.ts          # Tool registry
+├── managers/
+│   ├── conversation.ts   # Agentic AI loop with tool calling
+│   └── setup.ts          # Interactive setup wizard
+├── storage/              # Storage backends (JSON / SQLite)
+├── utils/
+│   ├── config.ts         # Config read/write
+│   ├── permissions.ts    # Permission prompt system
+│   ├── retry.ts          # Exponential backoff for API calls
+│   ├── sanitize.ts       # Shell command safety filter
+│   ├── errors.ts         # API error parsing & friendly messages
+│   └── logger.ts         # Debug logger
+└── __tests__/            # Jest test suite
+    ├── sanitize.test.ts
+    ├── retry.test.ts
+    ├── providers.test.ts
+    └── database.test.ts
+```
+
+---
+
+## License
+
+MIT

package/dist/index.d.ts

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

package/dist/index.d.ts.map

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