knowns 0.1.7 → 0.2.0

package/CHANGELOG.md

@@ -5,6 +5,99 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.0] - 2025-12-27
+
+### Added
+- **Project Documentation**: Comprehensive project docs for contributors and users
+  - `PHILOSOPHY.md` - 10 core principles guiding Knowns design
+  - `ARCHITECTURE.md` - Technical overview, diagrams, data flow, sync logic
+  - `CONTRIBUTING.md` - Contribution guidelines aligned with philosophy
+  - `docs/` folder with detailed guides:
+    - `commands.md` - Full CLI command reference
+    - `workflow.md` - Task lifecycle guide
+    - `reference-system.md` - How `@doc/` and `@task-` linking works
+    - `web-ui.md` - Kanban board and document browser guide
+    - `mcp-integration.md` - Claude Desktop MCP setup
+    - `configuration.md` - Project structure and options
+    - `ai-workflow.md` - Guide for AI agents
+
+- **README Improvements**:
+  - Added TL;DR section for quick understanding
+  - Added comparison table vs Notion/Jira/Obsidian
+  - Added "How it works" 3-step explanation
+  - Added Roadmap section with Self-Hosted Team Sync (planned)
+  - New badges: Node version, TypeScript, Platform, GitHub stars, PRs welcome
+  - Links to Philosophy, Architecture, and Contributing docs
+
+- **Node.js Engine Requirement**: Added `engines.node >= 18.0.0` to package.json
+
+### Changed
+- **README Restructure**: Optimized for first impressions
+  - Moved detailed docs to `./docs/` folder
+  - Shortened main README from ~300 to ~175 lines
+  - Documentation table links to detailed guides
+- **Tagline**: Updated to "CLI-first knowledge layer that gives AI persistent memory of your project"
+- **Version Display**: Now reads directly from package.json (works with both npm and bun)
+
+### Fixed
+- **UI Version Display**: Fixed version showing "dev" or old version when built with bun
+  - Vite config now reads version directly from package.json instead of `npm_package_version`
+- **Doc Mention Regex**: Fixed badge not rendering for `@doc/path` without `.md` extension
+  - Changed regex from `/@doc\/([^\s]+\.md)/g` to `/@docs?\/([^\s)]+)/g`
+  - Added `normalizeDocPath()` to automatically add `.md` extension
+
+## [0.1.8] - 2025-12-27
+
+### Added
+- **Node.js Runtime Support**: Browser command now works with both Bun and Node.js
+  - Migrated server from `Bun.serve()` to Express + ws
+  - Added `express`, `ws`, and `cors` dependencies
+  - WebSocket real-time sync works on both runtimes
+- **Bun Compatibility Layer**: New `src/utils/bun-compat.ts` utility providing cross-runtime support
+  - `file()` - Bun.file() compatible wrapper for reading files
+  - `write()` - Bun.write() compatible wrapper for writing files
+  - `bunSpawn()` - Bun.spawn() compatible wrapper for process spawning
+  - CLI commands now work with both Bun and Node.js runtimes
+- **Build Scripts**: Added `scripts/build-cli.js` using esbuild for Node.js-compatible builds
+  - CLI can now be built with `node scripts/build-cli.js` (no Bun required)
+  - Uses ESM format with `createRequire` shim for CommonJS compatibility
+  - Builds both main CLI and MCP server
+  - Properly strips old shebangs and adds Node.js-compatible shebang
+- **CI/CD**: Updated GitHub Actions workflows to use only Node.js and npm
+  - Removed Bun dependency from CI/CD pipelines
+  - Both `ci.yml` and `publish.yml` now use `npm ci`, `npm test`, `npm run build`
+  - Added npm cache for faster builds
+- **Testing**: Migrated from `bun test` to `vitest`
+  - Added `vitest.config.ts` with path aliases support
+  - All 76 tests passing with vitest
+
+### Fixed
+- **File Deletion**: Fixed improper file deletion that was clearing files instead of deleting them
+  - Changed from `Bun.write(path, "")` to proper `unlink()` in `file-store.ts` and `version-store.ts`
+  - Tasks and version history are now properly deleted when archived or removed
+- **Browser Command**: Fixed browser opening on non-Bun runtimes with proper `spawn()` fallback
+- **Server Path Detection**: Fixed `import.meta.dir` undefined error when running with Node.js
+  - Now uses `fileURLToPath(import.meta.url)` as fallback for Node.js compatibility
+  - Added Windows path separator support
+- **Windows Build**: Fixed shebang syntax error when running built CLI on Windows
+  - Build script now strips BOM and old shebangs before adding Node.js shebang
+  - Added `.npmrc` with `legacy-peer-deps=true` for React 19 compatibility
+- **Web UI Doc Update**: Fixed "path must be string" error when updating docs
+  - Express 5 wildcard `{*path}` returns array, now properly joined to string
+
+### Changed
+- **Server Architecture**: Complete rewrite of `src/server/index.ts`
+  - Replaced `Bun.serve()` with Express HTTP server
+  - Replaced Bun WebSocket API with `ws` library
+  - All 15 API routes migrated to Express router pattern
+  - Static file serving now uses `express.static()`
+- Refactored file operations across multiple modules to use the new compatibility layer:
+  - `src/commands/task.ts` - Archive/unarchive operations
+  - `src/commands/time.ts` - Time tracking data persistence
+  - `src/storage/file-store.ts` - Task and project storage
+  - `src/storage/version-store.ts` - Version history storage
+- Simplified `src/utils/bun-compat.ts` - removed `serve()` function (now using Express)
+
 ## [0.1.7] - 2025-12-27
 
 ### Fixed
@@ -146,6 +239,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - CLAUDE.md with complete guidelines for AI agents
 - Example workflows and patterns
 
+[0.2.0]: https://github.com/knowns-dev/knowns/compare/v0.1.8...v0.2.0
+[0.1.8]: https://github.com/knowns-dev/knowns/compare/v0.1.7...v0.1.8
 [0.1.7]: https://github.com/knowns-dev/knowns/compare/v0.1.6...v0.1.7
 [0.1.6]: https://github.com/knowns-dev/knowns/compare/v0.1.5...v0.1.6
 [0.1.5]: https://github.com/knowns-dev/knowns/compare/v0.1.3...v0.1.5

package/README.md

@@ -9,7 +9,7 @@
 </p>
 
 <p align="center">
-  CLI tool for dev teams to manage tasks and documentation with AI-first context linking.
+  CLI-first knowledge layer that gives AI persistent memory of your project.
 </p>
 
 <p align="center">
@@ -17,198 +17,149 @@
   <a href="https://www.npmjs.com/package/knowns"><img src="https://img.shields.io/npm/dm/knowns.svg?style=flat-square" alt="npm downloads"></a>
   <a href="https://github.com/knowns-dev/knowns/actions"><img src="https://img.shields.io/github/actions/workflow/status/knowns-dev/knowns/ci.yml?branch=main&style=flat-square&label=CI" alt="CI"></a>
   <a href="./LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square" alt="License: MIT"></a>
+  <br>
+  <a href="#"><img src="https://img.shields.io/node/v/knowns?style=flat-square" alt="node version"></a>
+  <a href="#"><img src="https://img.shields.io/badge/TypeScript-5.0-blue?style=flat-square&logo=typescript&logoColor=white" alt="TypeScript"></a>
+  <a href="#"><img src="https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-lightgrey?style=flat-square" alt="platform"></a>
+  <a href="https://github.com/knowns-dev/knowns/stargazers"><img src="https://img.shields.io/github/stars/knowns-dev/knowns?style=flat-square" alt="GitHub stars"></a>
+  <a href="#"><img src="https://img.shields.io/badge/PRs-welcome-brightgreen?style=flat-square" alt="PRs Welcome"></a>
 </p>
 
 ---
 
-## Why Knowns?
+> **TL;DR:** Knowns is a CLI-first knowledge layer that lets AI reliably read and reuse your project context — instead of asking the same questions every session.
 
-**Problem:** AI assistants lose context between sessions. You repeat the same architecture explanations, patterns, and decisions over and over.
+## The Problem
 
-**Solution:** Knowns links tasks to documentation with structured context that AI can understand and reference automatically.
+AI assistants are stateless — they forget your architecture, patterns, and decisions every session.
 
-## Features
-
-| Feature | Description |
-|---------|-------------|
-| 🎯 **Task Management** | Create, track, and manage tasks with acceptance criteria |
-| 📚 **Documentation** | Nested folder structure with markdown support |
-| ⏱️ **Time Tracking** | Built-in timers and time reports |
-| 🔗 **Context Linking** | `@task-42` and `@doc/patterns/auth` references |
-| 🤖 **AI Integration** | MCP Server for Claude Desktop, `--plain` output for AI |
-| 🌐 **Web UI** | Kanban board, document browser, dark mode |
-| 🔄 **Agent Sync** | Sync guidelines to Claude, Gemini, Copilot |
-
-## Installation
+```
+Session 1: "Implement feature X" → AI: "How does your auth work?" → You explain
 
-```bash
-# Using npm
-npm install -g knowns
+Session 2: "Implement feature Y" → AI: "How does your auth work?" → You explain AGAIN
 
-# Using bun
-bun install -g knowns
+Session 100: Still explaining the same thing...
 ```
 
-## Quick Start
+## The Solution
 
 ```bash
-# Initialize project
-knowns init
-
-# Create documentation
-knowns doc create "Auth Pattern" -d "JWT authentication" -t "patterns" -f patterns
+# Document once
+knowns doc create "Auth Pattern" -d "JWT with guards" -f patterns
 
-# Create task with context
-knowns task create "Add authentication" \
-  -d "Implement JWT auth following @doc/patterns/auth-pattern" \
-  --ac "User can login" \
-  --ac "Session persists"
+# Reference everywhere
+knowns task create "Add login" -d "Follow @doc/patterns/auth-pattern"
 
-# View task (AI-readable)
-knowns task view 1 --plain
-
-# Open Web UI
-knowns browser
+# AI reads context automatically — never forgets
 ```
 
-## Commands
+**How it works:**
 
-### Tasks
+1. **You plan** — Create tasks with acceptance criteria in Web UI or CLI
+2. **You link** — Reference docs like `@doc/patterns/auth` in task descriptions
+3. **AI executes** — Tell AI *"Work on task 42"*, it reads the task, follows the refs, and implements
 
-```bash
-knowns task create "Title" -d "Description" --ac "Criterion"
-knowns task view <id> --plain
-knowns task list --plain
-knowns task edit <id> -s in-progress -a @me
-knowns task edit <id> --check-ac 1 --check-ac 2
-knowns task edit <id> --plan "1. Step 1\n2. Step 2"
-knowns task edit <id> --notes "Implementation summary"
-```
+Knowns resolves `@doc/...` and `@task-...` into real files. AI reads them via [MCP](./docs/mcp-integration.md) or `--plain` output — no copy-paste needed.
 
-### Documentation
+## Install
 
 ```bash
-knowns doc create "Title" -d "Description" -t "tags" -f "folder"
-knowns doc view "doc-name" --plain
-knowns doc list --plain
-knowns doc edit "doc-name" -c "New content"
-knowns doc edit "doc-name" -a "Appended content"
-```
-
-### Time Tracking
+# using npm
+npm install -g knowns
 
-```bash
-knowns time start <task-id>
-knowns time stop
-knowns time status
-knowns time report --from "2025-01-01" --to "2025-12-31"
-```
+# using bun
+bun install -g knowns
 
-### Search
 
-```bash
-knowns search "query" --plain
-knowns search "auth" --type task --plain
-knowns search "patterns" --type doc --plain
+knowns init
+knowns browser  # Open Web UI
 ```
 
-### Other
+---
 
-```bash
-knowns browser              # Open Web UI
-knowns agents --update-instructions  # Sync AI guidelines
-knowns mcp                  # Start MCP server
-```
+## Why Knowns over Notion / Jira / Obsidian?
 
-## Reference System
+| | Knowns | Notion/Jira | Obsidian |
+|---|--------|-------------|----------|
+| **AI-readable** | `--plain` output, MCP server | Copy-paste manually | Plugins needed |
+| **File-based** | Git-friendly `.knowns/` folder | Cloud-locked | Local files |
+| **CLI-first** | Full CLI + Web UI | Web only | GUI only |
+| **Context linking** | `@doc/...` `@task-42` refs | Manual links | Wiki links |
+| **Source of truth** | Local files (Git-versioned) | Remote database | Local vault |
+| **Minimal setup** | `knowns init` and done | Complex setup | Many plugins |
 
-Link tasks and docs using `@` syntax:
+**Best for:** Dev teams who pair with AI and want persistent project memory.
 
-| Type | Input | Output |
-|------|-------|--------|
-| Task | `@task-42` | `@.knowns/tasks/task-42 - Title.md` |
-| Doc | `@doc/patterns/auth` | `@.knowns/docs/patterns/auth.md` |
+## Features
 
-**Example:**
-```markdown
-Implement auth following @doc/patterns/guards
-Related: @task-42 @task-38
-```
+| Feature | Description |
+|---------|-------------|
+| **Task Management** | Create, track tasks with acceptance criteria |
+| **Documentation** | Nested folders with markdown support |
+| **Time Tracking** | Built-in timers and reports |
+| **Context Linking** | `@task-42` and `@doc/patterns/auth` references |
+| **AI Integration** | MCP Server for Claude, `--plain` output |
+| **Web UI** | Kanban board, doc browser, dark mode |
 
-AI reads task → sees refs → fetches context → implements correctly.
+---
 
-## Web UI
+## Quick Reference
 
 ```bash
-knowns browser
-```
+# Tasks
+knowns task create "Title" -d "Description" --ac "Criterion"
+knowns task list --plain
+knowns task view <id> --plain
+knowns task edit <id> -s in-progress -a @me
 
-Features:
-- **Kanban Board** - Drag & drop tasks
-- **Document Browser** - Tree view with markdown preview
-- **Task Details** - Inline editing with acceptance criteria
-- **Dark Mode** - System preference aware
-- **Global Search** - Cmd+K
-
-## MCP Server (Claude Desktop)
-
-Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
-
-```json
-{
-  "mcpServers": {
-    "knowns": {
-      "command": "knowns",
-      "args": ["mcp"]
-    }
-  }
-}
+# Documentation
+knowns doc create "Title" -d "Description" -f "folder"
+knowns doc view "doc-name" --plain
+
+# Time & Search
+knowns time start <id> && knowns time stop
+knowns search "query" --plain
 ```
 
-Claude can now read your tasks and documentation automatically.
+---
 
-## Project Structure
+## Documentation
 
-```
-.knowns/
-├── tasks/              # Task markdown files
-├── docs/               # Documentation
-│   ├── patterns/
-│   ├── guides/
-│   └── architecture/
-└── config.json         # Project config
-```
+| Guide | Description |
+|-------|-------------|
+| [Command Reference](./docs/commands.md) | All CLI commands with examples |
+| [Workflow Guide](./docs/workflow.md) | Task lifecycle from creation to completion |
+| [Reference System](./docs/reference-system.md) | How `@doc/` and `@task-` linking works |
+| [Web UI](./docs/web-ui.md) | Kanban board and document browser |
+| [MCP Integration](./docs/mcp-integration.md) | Claude Desktop setup |
+| [Configuration](./docs/configuration.md) | Project structure and options |
+| [AI Workflow](./docs/ai-workflow.md) | Guide for AI agents |
 
-## Task Workflow
+---
 
-```bash
-# 1. Take task
-knowns task edit <id> -s in-progress -a @me
+## Roadmap
 
-# 2. Start timer
-knowns time start <id>
+### Self-Hosted Team Sync 🚧 (Planned)
 
-# 3. Create plan
-knowns task edit <id> --plan "1. Research\n2. Implement\n3. Test"
+Knowns will optionally support a self-hosted sync server — for teams that want shared visibility without giving up local-first workflows.
 
-# 4. Work & check criteria
-knowns task edit <id> --check-ac 1 --check-ac 2
+- **Real-time visibility** — See who is working on what
+- **Shared knowledge** — Sync tasks and documentation across the team
+- **Progress tracking** — Track activity over time
+- **Full data control** — Self-hosted, no cloud dependency
 
-# 5. Add notes
-knowns task edit <id> --notes "Implementation complete"
+The CLI and local `.knowns/` folder remain the source of truth.
+The server acts only as a sync and visibility layer.
 
-# 6. Stop timer & complete
-knowns time stop
-knowns task edit <id> -s done
-```
+---
 
 ## Development
 
 ```bash
-bun install
-bun run dev      # Dev mode
-bun run build    # Build
-bun run lint     # Lint
+npm install
+npm run dev      # Dev mode
+npm run build    # Build
+npm run test     # Test
 ```
 
 ## Links
@@ -217,6 +168,10 @@ bun run lint     # Lint
 - [GitHub](https://github.com/knowns-dev/knowns)
 - [Changelog](./CHANGELOG.md)
 
+For design principles and long-term direction, see [Philosophy](./PHILOSOPHY.md).
+
+For technical details, see [Architecture](./ARCHITECTURE.md) and [Contributing](./CONTRIBUTING.md).
+
 ---
 
 <p align="center">