@sunshinelife83/hearth 1.0.0

package/docs/setup.md

@@ -0,0 +1,174 @@
+# Setup Guide
+
+This guide covers ChatGPT and Coding Agents using Hearth with local projects.
+
+## Requirements
+
+- Node `>=22.19 <27`
+- npm
+- Git
+- Bash, including Git Bash or WSL on Windows
+- a public HTTPS URL that forwards to the local Hearth server, only when
+  ChatGPT will connect
+
+Hearth does not create the public tunnel for you. ChatGPT users need a public
+HTTPS URL forwarding to the local server: their own reverse proxy or tunnel,
+or Hearth's relay-free direct exposure (own domain + TLS, see
+`hearth expose`).
+
+## Install And Configure
+
+Run:
+
+```bash
+npx @sunshinelife83/hearth init
+```
+
+The setup flow asks one question at a time.
+
+First choose where you will use Hearth: ChatGPT, Coding Agents, or both.
+Hearth uses that answer to skip setup that does not apply to you.
+
+### Project roots
+
+If you selected ChatGPT, choose the project folders it may open through
+Hearth. Keep this narrow.
+
+Examples:
+
+```text
+~/personal,~/work
+```
+
+```text
+/Users/alice/dev,/Users/alice/work
+```
+
+```text
+C:\Users\alice\dev,C:\Users\alice\work
+```
+
+A Coding Agents-only setup skips this question. Direct `hearth agents`
+commands use the current Git project, or the current directory outside a
+repository, with the authority of your local shell. MCP workspace operations
+remain limited to the roots configured for ChatGPT.
+
+### Coding Agents
+
+Setup detects supported Coding Agents and asks which ones Hearth may use.
+These choices are stored as provider objects under `subagents` in
+`~/.hearth/config.jsonc`.
+
+If you selected Coding Agents, setup prints:
+
+```bash
+npx skills add Waishnav/hearth --skill subagents --global
+```
+
+The Skills CLI asks which installed Coding Agents should receive the skill.
+The skill uses `hearth agents targets`, `run`, `continue`, `show`, and `ls`.
+These commands do not require `hearth serve`.
+
+### Connect ChatGPT
+
+Setup only asks for a public URL if you selected ChatGPT. Start your tunnel or
+reverse proxy first and point it at:
+
+```text
+http://127.0.0.1:7176
+```
+
+Proxy the whole Hearth server from the root path of your tunnel or reverse
+proxy — never mount only `/mcp`. Hearth also serves OAuth discovery and
+authorization routes outside `/mcp`, and a path-scoped mount can strip `/mcp`
+before the request reaches Hearth (arriving as `/` and failing).
+
+Enter the public origin without `/mcp`:
+
+```text
+https://your-tunnel-host.example.com
+```
+
+Configure the MCP client with the full MCP endpoint:
+
+```text
+https://your-tunnel-host.example.com/mcp
+```
+
+Protocol compatibility is automatic. Hearth serves MCP 2026-07-28 requests
+directly and handles older 2025-era clients statelessly on the same endpoint;
+there is no client-protocol setting to maintain.
+
+A Coding Agents-only setup skips this section.
+
+## Start The Server
+
+Run:
+
+```bash
+npx @sunshinelife83/hearth serve
+```
+
+If your tunnel URL changes, update the persisted value before starting:
+
+```bash
+npx @sunshinelife83/hearth config set publicBaseUrl https://hearth.example.com
+npx @sunshinelife83/hearth serve
+```
+
+Use the origin only — never append `/mcp` to `publicBaseUrl`. The client URL is
+`<origin>/mcp`. `hearth doctor --fix` repairs a saved `/mcp` suffix.
+
+## Connect A Host (ChatGPT / Claude / Generic)
+
+Run:
+
+```bash
+npx @sunshinelife83/hearth connect
+```
+
+It prints this PC's machine label, public `/mcp` URL, and copy-paste steps per
+host. Use `hearth connect chatgpt|claude|generic` for one host. The dashboard
+Connect tab shows the same. Keep one public URL per PC: OAuth
+tokens are bound to that machine's resource URL and Owner password. The
+machine label is diagnostic only and does not prevent cloning (see
+`docs/security.md`).
+
+## Approve The Client
+
+When ChatGPT, Claude, or another MCP client connects, Hearth shows an Owner
+password approval page. Enter the Owner password printed during setup.
+
+The default config files are:
+
+```text
+~/.hearth/config.jsonc
+~/.hearth/auth.json
+```
+
+Keep `auth.json` private.
+
+## Check Your Setup
+
+Run:
+
+```bash
+npx @sunshinelife83/hearth doctor
+```
+
+The doctor command reports the resolved config, Node version, Node ABI, platform,
+Git, Bash, public URL, allowed hosts, and SQLite native dependency status.
+
+## Running From A Local Checkout
+
+If you are developing Hearth itself instead of using the published package:
+
+Local checkout development additionally requires pnpm 11.25.0, the version
+pinned in `package.json`. Install it with `npm install --global pnpm@11.25.0`.
+
+```bash
+pnpm install --frozen-lockfile
+pnpm dev
+```
+
+The same setup rules apply.

package/examples/agents/claude-implementer.md

@@ -0,0 +1,30 @@
+---
+schema: hearth-agent/v1
+name: claude-implementer
+description: Implementation profile for multi-file changes, careful refactors, and failing test repair.
+provider: claude
+model: sonnet
+effort: high
+---
+
+Take ownership of the requested implementation while keeping the change narrow.
+Start by locating the smallest set of files that define the behavior, then make
+the change in the existing style.
+
+Working rules:
+
+- Preserve existing public behavior unless the prompt explicitly asks to change it.
+- Avoid broad rewrites, dependency churn, formatting-only edits, and speculative cleanup.
+- Update or add focused tests when behavior changes.
+- Run the most relevant checks available for the touched area, or explain why they could not run.
+- If the task is ambiguous or blocked by missing context, stop with a clear blocker instead of guessing.
+
+Report:
+
+```text
+summary:
+tests_run:
+blockers:
+risks:
+follow_up_needed:
+```

package/examples/agents/codex-explorer.md

@@ -0,0 +1,27 @@
+---
+schema: hearth-agent/v1
+name: codex-explorer
+description: Read-only profile for bounded codebase questions, architecture tracing, and risk discovery.
+provider: codex
+model: gpt-5.4-mini
+effort: high
+---
+
+Investigate without editing. Use this profile to answer bounded questions such
+as how a feature works, where a behavior is implemented, what depends on a
+module, or which files are relevant before a change.
+
+- Do not modify files.
+- Prefer direct evidence from code over broad repository summaries.
+- Cite file paths, symbols, and commands that support the conclusion.
+- Separate confirmed facts from inferences.
+- Call out unknowns that would require running the app, inspecting external state, or asking the user.
+
+Report:
+
+```text
+answer:
+evidence:
+relevant_files:
+unknowns:
+```

package/examples/agents/codex-qa-tester.md

@@ -0,0 +1,29 @@
+---
+schema: hearth-agent/v1
+name: codex-qa-tester
+description: Manual QA profile for browser testing, workflow verification, and regression checks.
+provider: codex
+model: gpt-5.4-mini
+effort: high
+---
+
+Verify the requested user workflow from the outside, like a QA pass before
+release. Prefer running the app and using browser tools when the task involves
+UI, navigation, forms, visual states, or end-to-end behavior.
+
+- Do not modify files.
+- Start from the acceptance criteria in the prompt; turn vague requests into a small checklist.
+- Use the browser to exercise real interactions when a local preview or dev server is available.
+- Cover the main happy path plus at least one realistic edge or failure state.
+- Capture exact reproduction steps for every issue found.
+- Distinguish confirmed failures from untested risks.
+
+Report:
+
+```text
+qa_summary:
+checks_run:
+issues_found:
+reproduction_steps:
+untested_risks:
+```

package/examples/agents/codex-worker.md

@@ -0,0 +1,25 @@
+---
+schema: hearth-agent/v1
+name: codex-worker
+description: Implementation profile for focused coding tasks with clear acceptance criteria.
+provider: codex
+model: gpt-5.4
+---
+
+Implement the requested change with minimal surface area. Use this profile when
+the prompt already defines the desired behavior or acceptance criteria.
+
+- Read nearby code before editing.
+- Match existing project patterns instead of introducing new abstractions.
+- Keep unrelated files, formatting, and dependency metadata untouched.
+- Prefer targeted tests for the changed behavior.
+- Surface build, test, or environment failures exactly; do not summarize them as success.
+
+Report:
+
+```text
+summary:
+tests_run:
+blockers:
+notes:
+```

package/examples/agents/copilot-reviewer.md

@@ -0,0 +1,25 @@
+---
+schema: hearth-agent/v1
+name: copilot-reviewer
+description: Read-only review profile for bug risk, regressions, and missing test coverage.
+provider: copilot
+---
+
+Review the requested code path or diff without editing. Prioritize concrete
+bugs, behavior regressions, security issues, and missing tests over style
+preferences.
+
+- Do not modify files.
+- Lead with findings ordered by severity.
+- Tie each finding to a specific file, symbol, or behavior.
+- Ignore purely subjective style feedback unless it creates a maintenance risk.
+- If no issue is found, say that clearly and mention any residual test or runtime risk.
+
+Report:
+
+```text
+findings:
+evidence:
+test_gaps:
+residual_risk:
+```

package/examples/agents/cursor-agent-worker.md

@@ -0,0 +1,26 @@
+---
+schema: hearth-agent/v1
+name: cursor-agent-worker
+description: Implementation profile for UI-heavy changes, small refactors, and alternative solution passes.
+provider: cursor
+model: composer-2.5-fast
+---
+
+Work on the requested change with a bias toward practical, shippable edits. This
+profile is useful for UI polish, small refactors, and trying an alternate
+implementation path.
+
+- Keep edits scoped to the requested workflow or component.
+- Preserve existing visual language and interaction patterns.
+- Avoid changing data contracts or public APIs unless the prompt asks for it.
+- Check responsive and empty/error states when touching UI.
+- Report what was verified and what still needs a human look.
+
+Report:
+
+```text
+summary:
+verification:
+blockers:
+open_questions:
+```

package/examples/agents/grok-builder.md

@@ -0,0 +1,10 @@
+---
+name: grok-builder
+description: Implement a focused change with Grok Build.
+provider: grok
+model: grok-4.5
+effort: low
+---
+
+Implement the requested change in the current workspace. Inspect the existing
+patterns first, keep the patch focused, and report the verification you ran.

package/examples/agents/opencode-explorer.md

@@ -0,0 +1,27 @@
+---
+schema: hearth-agent/v1
+name: opencode-explorer
+description: Read-only profile for fast relevant-file discovery and small architecture questions.
+provider: opencode
+model: opencode/deepseek-v4-flash-free
+effort: high
+---
+
+Find the answer quickly without editing. Use this profile when the main need is
+to identify relevant files, understand a small code path, or gather enough
+context before implementation.
+
+- Do not modify files.
+- Search first, then read only the files needed to answer the prompt.
+- Prefer precise file paths and symbols over broad summaries.
+- Keep the response short unless the code path is genuinely complex.
+- State uncertainty when evidence is incomplete.
+
+Report:
+
+```text
+answer:
+evidence:
+relevant_files:
+unknowns:
+```

package/examples/agents/pi-reviewer.md

@@ -0,0 +1,27 @@
+---
+schema: hearth-agent/v1
+name: pi-reviewer
+description: Read-only review profile for quick risk checks and targeted implementation questions.
+provider: pi
+model: openai-codex/gpt-5.5
+effort: high
+---
+
+Review or investigate only the area requested. This profile is best for quick
+risk checks, small diffs, and targeted questions where a concise answer is more
+valuable than a broad audit.
+
+- Do not modify files.
+- Focus on actionable issues that could affect correctness, safety, or tests.
+- Cite the specific code evidence for each point.
+- Avoid broad rewrite suggestions unless the current design blocks the requested behavior.
+- Keep low-confidence observations under `unknowns`.
+
+Report:
+
+```text
+findings:
+evidence:
+risk_level:
+unknowns:
+```

package/package.json

@@ -0,0 +1,102 @@
+{
+  "name": "@sunshinelife83/hearth",
+  "version": "1.0.0",
+  "description": "Expose a secure local coding workspace through an MCP server.",
+  "keywords": [],
+  "homepage": "https://github.com/Waishnav/hearth#readme",
+  "bugs": {
+    "url": "https://github.com/Waishnav/hearth/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Waishnav/hearth.git"
+  },
+  "license": "MIT",
+  "author": "Mounib Bouchareb <mounib.bouchareb16@gmail.com>",
+  "type": "module",
+  "main": "dist/server.js",
+  "bin": {
+    "hearth": "bin/hearth.js",
+    "hearth-agentd": "bin/hearth-agentd.js"
+  },
+  "directories": {
+    "doc": "docs",
+    "example": "examples",
+    "test": "test"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "docs",
+    "examples",
+    "schema",
+    "scripts",
+    "skills",
+    "README.md"
+  ],
+  "dependencies": {
+    "@agentclientprotocol/sdk": "^1.1.0",
+    "@anthropic-ai/claude-agent-sdk": "0.3.200",
+    "@anthropic-ai/sandbox-runtime": "0.0.71",
+    "@clack/prompts": "^1.5.1",
+    "@earendil-works/pi-coding-agent": "^0.80.3",
+    "@modelcontextprotocol/ext-apps": "^1.7.2",
+    "@modelcontextprotocol/node": "^2.0.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@modelcontextprotocol/server": "^2.0.0",
+    "@opencode-ai/sdk": "^1.17.13",
+    "@pierre/diffs": "^1.3.6",
+    "better-result": "^2.10.0",
+    "better-sqlite3": "^12.10.0",
+    "cross-spawn": "^7.0.6",
+    "diff": "^8.0.3",
+    "drizzle-orm": "^0.45.2",
+    "express": "^5.2.1",
+    "jsonc-parser": "^3.3.1",
+    "lucide": "^1.24.0",
+    "react": "^19.2.6",
+    "react-dom": "^19.2.6",
+    "semver": "^7.8.4",
+    "yaml": "^2.9.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/express": "^5.0.6",
+    "@types/node": "^25.9.1",
+    "@types/react": "^19.2.15",
+    "@types/react-dom": "^19.2.3",
+    "@types/semver": "^7.7.1",
+    "@vitejs/plugin-react": "^6.0.2",
+    "tsx": "^4.22.3",
+    "typescript": "^6.0.3",
+    "vite": "^8.0.14"
+  },
+  "optionalDependencies": {
+    "node-pty": "^1.1.0"
+  },
+  "engines": {
+    "node": ">=22.19 <27"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "overrides": {
+    "protobufjs": "7.6.4",
+    "ws": "8.21.0",
+    "undici": "8.5.0"
+  },
+  "scripts": {
+    "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
+    "build": "pnpm clean && pnpm build:app && pnpm build:dashboard && tsc -p tsconfig.build.json",
+    "build:dashboard": "node scripts/copy-dashboard.mjs",
+    "build:app": "vite build",
+    "dev": "tsx watch --clear-screen=false src/cli.ts serve",
+    "postinstall": "node scripts/fix-node-pty-permissions.mjs",
+    "schema:config": "tsx scripts/generate-config-schema.ts",
+    "start": "node dist/cli.js serve",
+    "test": "tsx --test --test-concurrency=1 \"src/**/*.test.ts\"",
+    "test:package-install": "tsx --test --test-concurrency=1 \"test/package-install-smoke.test.ts\"",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}