hakonook 0.9.0

package/README.md

@@ -0,0 +1,453 @@
+# hakonook
+
+a cozy CLI for your local projects ✿
+
+---
+
+## about
+
+I built this for myself. It helps me keep track of scattered projects across my dev folder — what's active, what's on pause, what I forgot about months ago. Probably not for everyone, but if you tend to accumulate projects like I do, it might be useful.
+
+The idea is simple: one root folder, projects organized by status, and a quick way to navigate between them.
+
+---
+
+## concepts
+
+**root** — your development folder (default: `~/development`)
+
+**statuses** — projects live in status folders:
+- `active` — currently working on
+- `paused` — taking a break
+- `archived` — done or abandoned
+- `stable` — shipped and maintained
+
+**index** — cached metadata about your projects, auto-refreshes hourly
+
+---
+
+## install
+
+```bash
+npm i -g hakonook
+```
+
+Or build from source (requires [Bun](https://bun.sh)):
+
+```bash
+git clone https://github.com/chrisdevelops/hakonook.git
+cd hakonook
+bun install
+bun run build
+```
+
+**macOS:**
+
+```bash
+cp ./dist/hako ~/.local/bin/
+codesign --sign - --force ~/.local/bin/hako
+```
+
+**Linux:**
+
+```bash
+cp ./dist/hako ~/.local/bin/
+```
+
+**Windows (PowerShell):**
+
+```powershell
+New-Item -ItemType Directory -Force -Path "$env:LOCALAPPDATA\hako"
+Copy-Item ./dist/hako.exe "$env:LOCALAPPDATA\hako\hako.exe"
+```
+
+Then add `%LOCALAPPDATA%\hako` to your PATH.
+
+---
+
+## quick start
+
+```bash
+hako scan              # index your projects
+hako                   # open interactive picker
+hako create my-app     # create a project
+hako code my-app       # open in IDE
+```
+
+---
+
+## interactive mode
+
+Run `hako` with no arguments to open the TUI.
+
+| key | action |
+|-----|--------|
+| `↑` `↓` `j` `k` | navigate |
+| `enter` `o` | open in Finder |
+| `i` | open in IDE |
+| `c` | open in Claude Code |
+| `t` | open terminal |
+| `a` | archive project |
+| `p` | pause project |
+| `n` | new project wizard |
+| `/` | search |
+| `?` | help |
+| `q` | quit |
+
+---
+
+## commands
+
+### navigation
+
+**hako** — interactive project picker
+
+**hako list** — list projects
+
+```bash
+hako list                    # all projects
+hako list -s active          # filter by status
+hako list --json             # machine-readable output
+```
+
+| option | description |
+|--------|-------------|
+| `-s, --status <status>` | filter by status |
+| `--json` | output as JSON |
+
+**hako open \<name\>** — open project in file manager
+
+**hako code \<name\>** — open project in IDE
+
+**hako claude \<name\>** — open project in Claude Code
+
+```bash
+hako claude my-app           # default
+hako claude my-app --yolo    # skip permissions
+hako claude my-app -p custom # use custom profile
+```
+
+| option | description |
+|--------|-------------|
+| `-p, --profile <name>` | use named profile from config |
+| `--yolo` | shortcut for `--profile yolo` |
+
+**hako info \<project\>** — show detailed project information
+
+```bash
+hako info my-project         # show project details
+hako info my-project --json  # machine-readable output
+```
+
+| option | description |
+|--------|-------------|
+| `--json` | output as JSON |
+
+**hako path \<name\>** — print project path (for shell integration)
+
+---
+
+### creation
+
+**hako create [name]** — create a new project
+
+```bash
+hako create                        # launch wizard
+hako create my-app                 # create blank project
+hako create my-app -t sveltekit    # from template
+hako create my-app -g user/repo    # clone from GitHub
+hako create my-app --remote <url>  # clone from any git remote
+hako create my-app -f other-proj   # fork from existing project
+hako create my-app -s paused       # start as paused
+hako create my-app --no-open       # don't open after
+```
+
+| option | description |
+|--------|-------------|
+| `-t, --template <name>` | use registered template |
+| `-g, --github <repo>` | clone from GitHub (user/repo or user/repo/subdir) |
+| `--remote <url>` | clone from any git remote URL |
+| `-f, --fork <project>` | create from an existing project |
+| `--blank` | create empty project with git init |
+| `-s, --status <status>` | initial status (default: active) |
+| `--no-open` | skip opening in IDE after creation |
+
+---
+
+### status
+
+**hako update \<name\>** — update project properties
+
+```bash
+hako update my-app -s paused       # pause the project
+hako update my-app -s archived     # archive the project
+hako update my-app -s active       # reactivate
+```
+
+| option | description |
+|--------|-------------|
+| `-s, --status <status>` | change status (active, paused, archived, stable) |
+
+**hako delete \<name\>** — permanently delete a project
+
+```bash
+hako delete my-old-project         # delete with confirmation
+hako delete my-old-project -f      # delete without confirmation
+```
+
+| option | description |
+|--------|-------------|
+| `-f, --force` | skip confirmation prompt |
+
+Warns about uncommitted changes, unpushed commits, and missing remotes before deleting.
+
+---
+
+### templates
+
+**hako template list** — show registered templates
+
+**hako template add \<name\>** — register a template
+
+```bash
+hako template add starter -g user/repo
+hako template add gitlab --remote <url>
+hako template add local-kit --local templates/kit
+```
+
+| option | description |
+|--------|-------------|
+| `-g, --github <repo>` | GitHub repository (user/repo or user/repo/subdir) |
+| `--remote <url>` | any git remote URL |
+| `--local <path>` | local template path |
+
+**hako template remove \<name\>** — unregister a template
+
+---
+
+### ai resources
+
+**hako ai** — manage AI resources (skills, agents, prompts, MCP configs, snippets)
+
+Run `hako ai` with no arguments to open an interactive browser.
+
+**hako ai list** — list all resources
+
+```bash
+hako ai list                 # all resources
+hako ai list --type skill    # filter by type
+hako ai list --json          # machine-readable
+```
+
+| option | description |
+|--------|-------------|
+| `--type <type>` | filter by type (skill, agent, prompt, mcp, snippet) |
+| `--json` | output as JSON |
+
+**hako ai use \<resource\>** — install a resource into the current project
+
+```bash
+hako ai use skill/my-skill
+hako ai use my-agent
+```
+
+**hako ai publish \<path\>** — add a local resource to the library
+
+```bash
+hako ai publish .claude/skills/my-skill
+hako ai publish .claude/agents/helper.md --description "Helper agent"
+```
+
+| option | description |
+|--------|-------------|
+| `--description <text>` | resource description |
+| `--tags <tags>` | comma-separated tags |
+| `--type <type>` | resource type (auto-detected if not specified) |
+| `--name <name>` | resource name (auto-detected if not specified) |
+
+**hako ai remove \<resource\>** — remove a resource from the library
+
+**hako ai sync** — sync the library with its git remote
+
+**hako ai init** — initialize the AI resources library
+
+```bash
+hako ai init
+hako ai init -g user/ai-resources
+hako ai init --remote git@github.com:user/ai-resources.git
+```
+
+| option | description |
+|--------|-------------|
+| `-g, --github <repo>` | GitHub repository (user/repo) |
+| `--remote <url>` | git remote URL for syncing |
+
+**hako ai info** — show library status
+
+| option | description |
+|--------|-------------|
+| `--json` | output as JSON |
+
+---
+
+### processes
+
+**hako process run \<project\> [script]** — run a script
+
+```bash
+hako process run my-app          # run default (dev)
+hako process run my-app start    # run specific script
+hako process run my-app -b       # run in background
+hako process run my-app -l       # list available scripts
+```
+
+| option | description |
+|--------|-------------|
+| `-b, --background` | run detached, track process |
+| `-l, --list` | list available scripts |
+
+**hako process list** — show tracked processes (TUI)
+
+```bash
+hako process list            # interactive
+hako process list --json     # machine-readable
+hako process list -a         # include dead processes
+```
+
+| option | description |
+|--------|-------------|
+| `--json` | output as JSON |
+| `-a, --all` | show all including stopped |
+
+**hako process kill \<target\>** — stop a process
+
+```bash
+hako process kill my-app     # by project name
+hako process kill 12345      # by PID
+hako process kill my-app -f  # force kill
+```
+
+| option | description |
+|--------|-------------|
+| `-s, --signal <signal>` | signal to send (default: SIGTERM) |
+| `-f, --force` | use SIGKILL |
+
+**hako ps** — alias for `process list`
+
+---
+
+### maintenance
+
+**hako scan [project]** — rebuild project index
+
+```bash
+hako scan                    # rescan all project directories
+hako scan my-project         # scan single project for AI resources
+hako scan --ai               # also detect AI resources
+hako scan --ai --publish     # auto-publish all new AI resources
+```
+
+| option | description |
+|--------|-------------|
+| `--ai` | also detect AI resources across projects |
+| `--publish` | auto-publish all detected AI resources (use with --ai) |
+
+**hako stale** — find inactive projects
+
+```bash
+hako stale                   # 30+ days inactive
+hako stale -d 60             # 60+ days inactive
+hako stale --json            # machine-readable
+```
+
+| option | description |
+|--------|-------------|
+| `-d, --days <n>` | days threshold (default: 30) |
+| `--json` | output as JSON |
+
+**hako doctor** — health check
+
+```bash
+hako doctor                  # run all checks
+hako doctor --json           # machine-readable
+```
+
+Checks config validity, root directory, status folders, index freshness, git initialization, and active project count.
+
+---
+
+### configuration
+
+**hako config show** — display current config
+
+**hako config edit** — open config in editor
+
+**hako config set \<key\> \<value\>** — set a config value
+
+```bash
+hako config set root ~/projects
+hako config set default_ide code
+hako config set active_limit 10
+```
+
+**hako config path** — print config file path
+
+---
+
+## configuration
+
+Config file: `~/.config/hako/config.toml`
+
+```toml
+# where your projects live
+root = "~/development"
+
+# IDE command
+default_ide = "cursor"
+
+# warn when active projects exceed this
+active_limit = 5
+
+[editor]
+command = "cursor"
+
+[github]
+username = ""
+
+[claude_code]
+command = "claude"
+default_args = []
+
+[claude_code.profiles]
+yolo = ["--dangerously-skip-permissions"]
+
+[statuses]
+active = "active"
+paused = "paused"
+archived = "archived"
+stable = "stable"
+
+[processes]
+log_dir = "~/.config/hako/logs"
+capture_output = false
+default_script = "dev"
+
+[templates]
+# add your own templates here
+# starter = { type = "github", repo = "user/repo" }
+```
+
+---
+
+## shell integration
+
+Add to your `.zshrc` or `.bashrc`:
+
+```bash
+# cd to a project by name
+hcd() { cd "$(hako path "$1")"; }
+```
+
+---
+
+made with ♡