@taskforcehq/taskforce 0.3.168

package/README.md

@@ -0,0 +1,241 @@
+# Taskforce
+
+<p align="center">
+  <img src="https://img.shields.io/npm/v/%40taskforcehq%2Ftaskforce?style=for-the-badge&color=8b5cf6" alt="NPM Version" />
+  <img src="https://img.shields.io/npm/l/%40taskforcehq%2Ftaskforce?style=for-the-badge&color=14b8a6" alt="License" />
+  <img src="https://img.shields.io/badge/Status-Beta-amber?style=for-the-badge" alt="Status" />
+  <img src="https://img.shields.io/badge/Powered%20By-Vite-646CFF?style=for-the-badge&logo=vite" alt="Powered by Vite" />
+</p>
+
+<h3 align="center">The High-Bandwidth Collaborative Synapse for AI-Developer Pairs</h3>
+
+---
+
+> **Beta Release:** Taskforce is under active development. For the latest experimental features, use `npm i -g @taskforcehq/taskforce@beta`.
+> **Development Tooling:** This is strictly a development-time tool. It is designed to automatically **not render** in production environments to ensure zero overhead.
+
+Taskforce is more than just a task manager; it's a **contextual bridge**. In the age of AI-assisted coding, the gap between "what needs to be done" and "how it was implemented" can grow exponentially. 
+
+Taskforce bridges this gap by providing a persistent, AI-accessible layer of intent that sits directly atop your live application during development. It transforms ephemeral chat history into structured project state.
+
+## ✨ Key Features
+
+- 📍 **Intelligent Context Capture**: Automatically tracks URLs, timestamps, and contextual metadata. Screenshots can be attached directly to tasks for visual debugging.
+- ⚡ **Model Context Protocol (MCP)**: Built-in MCP server allows AI agents (like Claude) to read from and write to your project's task nexus with full awareness of your workspace.
+- 🎨 **Premium Visual Engine**: Hand-crafted Light, Dark, and Midnight themes with a sophisticated token-based color system.
+- ⌨️ **Quick-Access Flow**: Configurable global hotkeys (`Alt+T` default) to toggle the nexus without breaking your flow.
+- 🤝 **Collaborative Loop**: AI-friendly JSON storage enables "staged" updates—AI suggests changes, and you approve the final state.
+
+---
+
+## 🛠️ Getting Started
+
+### Installation
+
+Recommendation: Install **globally** to use the CLI and MCP server across any project:
+
+```bash
+npm i -g @taskforcehq/taskforce
+```
+
+#### 🧪 Trying the Latest Unstable Features
+If you want to test the latest untested/beta version (e.g., `v0.3.13-beta.0`):
+
+```bash
+npm i -g @taskforcehq/taskforce@beta
+```
+
+Taskforce is installed globally for all supported usage patterns:
+
+```bash
+npm i -g @taskforcehq/taskforce
+```
+
+*Note: Taskforce includes a dashboard server, so you can use it with ANY framework (Next.js, Angular, Python, etc.) without needing Vite config.*
+
+### Database Backend (Preparation)
+
+Taskforce currently runs on SQLite by default. Backend selection is scaffolded:
+
+- `TASKFORCE_DB_PROVIDER=sqlite` (default)
+- `TASKFORCE_DB_PROVIDER=postgres` (requires `TASKFORCE_DATABASE_URL`)
+- `TASKFORCE_TENANT_ID=default` (optional; enables tenant scoping groundwork)
+
+Readiness endpoint:
+
+- `GET /api/taskforce/health` returns API + database health state.
+
+Migration prep utilities:
+
+- Postgres schema: `src/migrations/postgres/001_init.sql`
+- SQLite export script: `npm run db:export:postgres` (writes `.taskforce/postgres-bootstrap.sql` by default)
+
+### Cloud App Endpoint Configuration
+
+For cloud deployments where the frontend host differs from the API/websocket host, set:
+
+- `VITE_TASKFORCE_API_BASE_URL` (example: `https://app-api.taskforcehq.ai`)
+- `VITE_TASKFORCE_WS_BASE_URL` (optional; defaults to `VITE_TASKFORCE_API_BASE_URL`)
+
+For local runtime with cloud-only authentication (while keeping local SQLite task APIs):
+
+- The standalone app is configured to use `https://app.taskforcehq.ai` for cloud auth by default (see `apps/app/main.tsx`).
+- No environment-variable setup is required for end users of the packaged local app.
+
+Behavior:
+
+- `/api/taskforce/*` requests are routed to `VITE_TASKFORCE_API_BASE_URL` when set.
+- websocket connects to `${VITE_TASKFORCE_WS_BASE_URL}/taskforce-ws` using `wss` on HTTPS pages.
+
+### API Auth Gate (Cloud Hardening)
+
+To protect API routes at the application layer (in addition to Cloudflare Access), configure:
+
+- `TASKFORCE_RUNTIME_MODE=cloud` (recommended for hosted app; `local` for standalone/local usage)
+- `TASKFORCE_AUTH_ENABLED=true`
+- `TASKFORCE_AUTH_SESSION_SECRET=<strong-random-secret>`
+- `TASKFORCE_EMAIL_PROVIDER=console|resend|google-workspace` (default: `console`)
+- `TASKFORCE_EMAIL_FROM='Taskforce <no-reply@yourdomain.com>'`
+- `TASKFORCE_EMAIL_REPLY_TO='support@yourdomain.com'` (optional)
+- `TASKFORCE_EMAIL_RESEND_API_KEY=<resend-api-key>` (required when provider=`resend`)
+- `TASKFORCE_EMAIL_GOOGLE_APP_PASSWORD=<google-app-password>` (required when provider=`google-workspace`)
+- Optional canonical secret key for either live provider: `TASKFORCE_EMAIL_PROVIDER_API_KEY=<provider-secret>`
+- Note: live delivery provider settings are only configurable in cloud runtime; local runtime uses `console`.
+- For production deliverability, configure sender domain records: SPF, DKIM, and DMARC.
+- Rotate `TASKFORCE_EMAIL_PROVIDER_API_KEY` regularly and use Admin > Settings > Email > `Clear Saved Key` during rotation cutovers.
+- Optional: `TASKFORCE_AUTH_REQUIRED_FOR_API=true` (default `true`)
+- Optional: `TASKFORCE_AUTH_EXCLUDED_PATHS=/api/taskforce/health` (comma-separated)
+- Optional: `TASKFORCE_API_RATE_LIMIT_ENABLED=true` (default `true`)
+- Optional: `TASKFORCE_API_RATE_LIMIT_MAX_REQUESTS=120` (default `120` per `60s`)
+- Optional: `TASKFORCE_API_RATE_LIMIT_WINDOW_MS=60000`
+- Auth rate-limit controls are configured in Admin > System Settings and persisted in Taskforce global settings.
+
+Defaults:
+- `cloud` mode: auth defaults to enabled + required for API routes.
+- `local` mode: guest usage is allowed unless auth is explicitly enabled.
+
+Request auth options:
+
+- `Cookie: taskforce_session=<signed-session-cookie>`
+
+### Integration
+
+Wrap your app or specific routes with the Taskforce component. It's designed to be transparent.
+
+Standalone app guide: `docs/guides/widget-standalone-integration.md`
+
+```tsx
+import { Taskforce } from '@taskforcehq/taskforce';
+
+const App = () => {
+    return (
+        <BrowserRouter>
+            {/* Your Application Logic */}
+            <Taskforce config={{
+                theme: 'midnight',
+                categories: ['Frontend', 'Backend', 'Refactor'],
+                position: 'bottom-right'
+            }} />
+        </BrowserRouter>
+    );
+};
+```
+
+---
+
+## 🖥️ Usage Modes
+
+Taskforce adapts to your current working style.
+
+### 📊 The Dashboard
+For heavy-duty project management. Drag-and-drop task prioritization, bulk archiving, and deep-linking support for sharing specific tasks.
+
+To launch dashboard mode (works in any project folder):
+```bash
+npx @taskforcehq/taskforce open [port]
+# Example: npx @taskforcehq/taskforce open 5174
+```
+
+### App/Website Surfaces
+
+- `apps/app` - full product app source (built to `dist/ui`, served by standalone server / Railway runtime).
+- `apps/site` - public website/landing source (Cloudflare Pages).
+- `apps/admin` - admin web surface source (Cloudflare Pages).
+- `taskforce open` behavior is unchanged and continues to use the built app bundle in `dist/ui`.
+
+### 🧭 Initiatives
+Initiatives provide template-based planning for complex work (for example `launch`, `migration`, `incident`) with reusable Definition of Done and Rollback checklist blocks.
+
+Guide: `docs/guides/initiatives-guide.md`
+
+Initiative API endpoints:
+- `GET /api/taskforce/initiative-templates`
+- `POST /api/taskforce/initiative-templates/create`
+- `POST /api/taskforce/initiative-templates/clone-checklists`
+
+---
+
+## 🤖 AI Superpowers (MCP Server)
+
+Empower your AI agents to be productive members of your team. By exposing Taskforce via the Model Context Protocol, your agent can:
+
+- **Discover**: Find where tasks are stored and what specialists are available.
+- **Plan**: Create complex multi-step choreographies for large features.
+- **Refine**: Update task statuses as code is written and tests are passed.
+
+### Configuration for Claude Desktop
+Add the following to your `claude_desktop_config.json`:
+
+#### Recommended (Global Install)
+If you have Taskforce installed globally (`npm install -g @taskforcehq/taskforce`):
+```json
+{
+  "mcpServers": {
+    "taskforce": {
+      "command": "npx",
+      "args": ["-y", "@taskforcehq/taskforce", "mcp", "/path/to/your/project"],
+      "env": {
+        "TASKFORCE_TENANT_ID": "your-tenant-id",
+        "TASKFORCE_WORKSPACE_ID": "your-workspace-id"
+      }
+    }
+  }
+}
+```
+
+`TASKFORCE_TENANT_ID` and `TASKFORCE_WORKSPACE_ID` should be set explicitly for MCP to avoid scope drift. `TASKFORCE_WORKSPACE_ID=default` is not allowed.
+
+---
+
+## ⚙️ Configuration
+
+| Option | Type | Default | Description |
+|:---|:---|:---|:---|
+| `theme` | `'dark' \| 'light' \| 'midnight'` | `'dark'` | Visual aesthetic style. |
+| `categories` | `CategoryConfig[]` | `['General']` | Custom groupings with specific path mapping. |
+| `taxonomies` | `TaxonomyDefinition[]` | `[]` | Advanced custom metadata fields for tasks. |
+
+---
+
+## 🧱 Project Architecture
+
+- `apps/app/` - Product app entrypoint (`index.html`, `main.tsx`, websocket hook).
+- `apps/site/` - Public website source.
+- `apps/admin/` - Admin web surface source.
+- `src/config/surfaceBase.ts` - single source-of-truth for Vite surface base paths (`app`, `site`, `admin`).
+- `src/StandalonePage.tsx` - High-density management board.
+- `src/TaskforceCore.tsx` - Shared state and UI primitives.
+- `src/mcp/` - Native Model Context Protocol implementation.
+- `src/types.ts` - Centralized contract for project state.
+
+Deployment runbooks:
+- `docs/launch/deployment-surfaces.md`
+- `docs/launch/runtime-boundaries.md`
+- `docs/launch/stage0-slo-observability.md`
+- `docs/launch/docker-runtime-runbook.md`
+
+---
+
+<p align="center">
+  Built with ❤️ by <a href="https://stratnexus.ai">Stratnexus</a>.
+</p>

package/dist/Taskforce.d.ts

@@ -0,0 +1,3 @@
+import { TaskforceWidget } from './TaskforceWidget';
+export { TaskforceWidget as Taskforce };
+export default TaskforceWidget;

package/dist/Taskforce.js

@@ -0,0 +1,3 @@
+import { TaskforceWidget } from './TaskforceWidget';
+export { TaskforceWidget as Taskforce };
+export default TaskforceWidget;