npm package: @henkas/schedyx
Description: Local-first timeblocking assistant for macOS
Author: Henki Papp
Latest version: 0.1.1

# SchedyX

[![CI](https://github.com/henkas/schedyx/workflows/CI/badge.svg)](https://github.com/henkas/schedyx/actions)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![macOS](https://img.shields.io/badge/platform-macOS-blue.svg)](https://www.apple.com/macos/)
[![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org/)

Local-first timeblocking and scheduling assistant for macOS. SchedyX reads tasks (initially Apple Reminders), finds open time around meetings, and blocks time on your calendar while respecting work hours and constraints. No cloud account required. Optional AI planning can be added later.

> **Status:** Pre-alpha v0.1.0 — core scheduling engine ready for testing.

## Why SchedyX
- **Local-first**: data stays on your Mac.
- **Safe by design**: only touches events it created (tagged with `#autoblock`).
- **Deterministic core**: rules engine decides; AI (optional) only suggests.
- **Mock-first**: develop and test without touching real calendars.

## Key Features
- ✅ CLI commands: `init`, `plan`, `apply`, `reconcile`, `check`, `clear`
- ✅ Smart locking (free → busy at lock window)
- ✅ Task splitting for long tasks (>90m)
- ✅ Diff previews for `apply` and safe reconciliation
- ✅ Mock adapters for safe development
- ✅ Comprehensive test suite

## Screenshots & Demo

![CLI demo output](docs/assets/cli-demo.svg)

Want a live demo? Run the mock workflow below and compare output with the screenshot.

## Installation

### Prerequisites
- **Node.js** 18+ (recommended)
- **macOS** (for real Calendar/Reminders integration)

### Install
```bash
npm install
npm run build
```

## Quick Start (Mock Mode)
1) Create config at `~/.config/schedyx/config.yaml`:
```yaml
mode: mock
writesEnabled: false
workHours:
  start: "09:00"
  end: "17:00"
lockMinutes: 30
breakMinutes: 10
cooldownMinutes: 5
writeCalendar: "SchedyX Auto"
readCalendar: "SchedyX Auto"
busyCalendars:
  - "Work"
remindersList: "SchedyX Test"
fixtures:
  tasks: "data/fixtures/tasks.json"
  events: "data/fixtures/events.json"
```

2) Run the planner:
```bash
npm start plan
```

3) Preview apply (no writes):
```bash
npm start apply --diff
```

4) Simulate reconciliation:
```bash
npm start reconcile --dry-run
```

> Full walkthrough: **[docs/QUICKSTART.md](docs/QUICKSTART.md)**

## Usage Examples

### Initialize real config (interactive)
```bash
npm start init
```

### Plan (dry-run)
```bash
npm start plan
npm start plan --json
```

### Apply blocks
```bash
npm start apply --diff
npm start apply --write
```

### Reconcile after calendar changes
```bash
npm start reconcile --dry-run
npm start reconcile
```

### Check recently ended blocks
```bash
npm start check
npm start check --write
npm start check --window 10
```

Manual: run `schedyx check` after a block ends to confirm completion.

Periodic: wire it into cron or launchd to poll every few minutes. Example (cron, every 5 minutes):
```bash
*/5 * * * * /usr/local/bin/node /path/to/schedyx/dist/cli/index.js check --write
```

### Clear auto-blocks and stored state
```bash
npm start clear
```

## How It Works (High-Level)
1. Load tasks and calendar events
2. Build available slots (work hours minus meetings + buffers)
3. Schedule tasks into slots (split long tasks as needed)
4. Apply locking (blocks become busy at `lockMinutes`)
5. Write blocks **only when explicitly enabled**

State is stored in a local SQLite database at `~/.config/schedyx/state.db`.

## Troubleshooting

**“Config not found”**
- Ensure `~/.config/schedyx/config.yaml` exists
- Use the exact YAML structure shown above

**“Writes are disabled”**
- SchedyX is safe-by-default. Use `--write` or enable `writesEnabled: true` in config.

**“Cannot find module”**
- Run `npm install` and `npm run build`

**AppleScript / Permissions errors**
- Grant Calendar/Reminders access in **System Settings → Privacy & Security → Automation**
- Run `npm start init` to regenerate config

## Documentation
- **[docs/QUICKSTART.md](docs/QUICKSTART.md)** — Step-by-step getting started guide
- **[docs/FEATURES.md](docs/FEATURES.md)** — Locking, safety, output
- **[docs/TECH_SPEC.md](docs/TECH_SPEC.md)** — Architecture and design
- **[docs/TESTING.md](docs/TESTING.md)** — Test suite and manual checklist
- **[docs/ROADMAP.md](docs/ROADMAP.md)** — Planned features (v0.1, v0.2 self-hosted, v1.0)
- **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)** — Code structure
- **[docs/DEVELOPMENT.md](docs/DEVELOPMENT.md)** — Local dev setup & workflow
- **[docs/CONTRIBUTING.md](docs/CONTRIBUTING.md)** — How to contribute
- **[docs/LIMITATIONS.md](docs/LIMITATIONS.md)** — Known constraints & edge cases
- **[docs/SECURITY.md](docs/SECURITY.md)** — Security considerations & reporting
- **[docs/CHANGELOG.md](docs/CHANGELOG.md)** — Version history

## AI-Assisted Development
This project uses AI tools to assist with research, drafting, and code/documentation improvements. All changes are reviewed and tested by a human maintainer before merging.

## License
MIT — see [LICENSE](LICENSE).