@sunshinelife83/hearth 1.0.0

package/schema/v1/hearth.schema.json

@@ -0,0 +1,529 @@
+{
+  "$id": "https://raw.githubusercontent.com/Waishnav/hearth/main/schema/v1/hearth.schema.json",
+  "title": "Hearth configuration",
+  "description": "Versioned configuration for a local Hearth MCP server.",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "default": "https://raw.githubusercontent.com/Waishnav/hearth/main/schema/v1/hearth.schema.json",
+      "type": "string",
+      "format": "uri"
+    },
+    "configVersion": {
+      "type": "number",
+      "const": 1
+    },
+    "server": {
+      "default": {},
+      "type": "object",
+      "properties": {
+        "host": {
+          "default": "127.0.0.1",
+          "type": "string",
+          "minLength": 1
+        },
+        "port": {
+          "default": 7176,
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 65535
+        },
+        "publicBaseUrl": {
+          "default": null,
+          "anyOf": [
+            {
+              "type": "string",
+              "format": "uri"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "allowedHosts": {
+          "default": [],
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "trustProxy": {
+          "default": false,
+          "type": "boolean"
+        },
+        "issuerMode": {
+          "default": "derived",
+          "type": "string",
+          "enum": [
+            "derived",
+            "local"
+          ]
+        }
+      },
+      "additionalProperties": false
+    },
+    "workspaces": {
+      "default": {},
+      "type": "object",
+      "properties": {
+        "allowedRoots": {
+          "default": [],
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "worktreeRoot": {
+          "default": "~/.hearth/worktrees",
+          "type": "string",
+          "minLength": 1
+        },
+        "profiles": {
+          "default": [],
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "path": {
+                "type": "string",
+                "minLength": 1,
+                "description": "Absolute path (or ~-prefixed) this profile applies to; longest prefix wins."
+              },
+              "mode": {
+                "type": "string",
+                "enum": [
+                  "readonly",
+                  "supervised",
+                  "autonomous"
+                ]
+              },
+              "sandbox": {
+                "type": "string",
+                "enum": [
+                  "auto",
+                  "none"
+                ]
+              },
+              "sandboxNetwork": {
+                "type": "string",
+                "enum": [
+                  "allow",
+                  "deny"
+                ]
+              },
+              "requireSandboxForAutonomous": {
+                "type": "boolean"
+              },
+              "commandAllow": {
+                "default": [],
+                "description": "Regex allowlist; when non-empty only matching commands run.",
+                "type": "array",
+                "items": {
+                  "type": "string",
+                  "minLength": 1
+                }
+              },
+              "commandDeny": {
+                "default": [],
+                "description": "Regex denylist; matching commands are always rejected.",
+                "type": "array",
+                "items": {
+                  "type": "string",
+                  "minLength": 1
+                }
+              },
+              "agentsAllowed": {
+                "description": "Whether agent tools may run for this workspace. Defaults to true.",
+                "type": "boolean"
+              }
+            },
+            "required": [
+              "path"
+            ],
+            "additionalProperties": false
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "storage": {
+      "default": {},
+      "type": "object",
+      "properties": {
+        "stateDir": {
+          "default": "~/.local/share/hearth",
+          "type": "string",
+          "minLength": 1
+        }
+      },
+      "additionalProperties": false
+    },
+    "tools": {
+      "default": {},
+      "type": "object",
+      "properties": {
+        "mode": {
+          "default": "codex",
+          "type": "string",
+          "enum": [
+            "claude",
+            "codex"
+          ]
+        }
+      },
+      "additionalProperties": false
+    },
+    "ui": {
+      "default": {},
+      "type": "object",
+      "properties": {
+        "enabled": {
+          "default": true,
+          "type": "boolean"
+        }
+      },
+      "additionalProperties": false
+    },
+    "artifacts": {
+      "default": {},
+      "type": "object",
+      "properties": {
+        "enabled": {
+          "default": false,
+          "type": "boolean"
+        },
+        "maxFileBytes": {
+          "default": 104857600,
+          "type": "integer",
+          "exclusiveMinimum": 0,
+          "maximum": 9007199254740991
+        }
+      },
+      "additionalProperties": false
+    },
+    "skills": {
+      "default": {},
+      "type": "object",
+      "properties": {
+        "enabled": {
+          "default": true,
+          "type": "boolean"
+        },
+        "paths": {
+          "default": [],
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "agentDir": {
+          "default": "~/.codex",
+          "type": "string",
+          "minLength": 1
+        }
+      },
+      "additionalProperties": false
+    },
+    "subagents": {
+      "default": {
+        "enabled": false,
+        "providers": []
+      },
+      "type": "object",
+      "properties": {
+        "enabled": {
+          "type": "boolean"
+        },
+        "providers": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "id": {
+                "type": "string",
+                "enum": [
+                  "codex",
+                  "claude",
+                  "opencode",
+                  "pi",
+                  "cursor",
+                  "copilot",
+                  "grok"
+                ]
+              },
+              "enabled": {
+                "type": "boolean"
+              },
+              "model": {
+                "type": "string",
+                "minLength": 1
+              },
+              "effort": {
+                "type": "string",
+                "minLength": 1
+              }
+            },
+            "required": [
+              "id",
+              "enabled"
+            ],
+            "additionalProperties": false
+          }
+        }
+      },
+      "required": [
+        "enabled",
+        "providers"
+      ],
+      "additionalProperties": false
+    },
+    "fleet": {
+      "default": {
+        "lanes": {}
+      },
+      "type": "object",
+      "properties": {
+        "lanes": {
+          "default": {},
+          "type": "object",
+          "propertyNames": {
+            "type": "string"
+          },
+          "additionalProperties": {
+            "type": "object",
+            "properties": {
+              "provider": {
+                "type": "string",
+                "enum": [
+                  "codex",
+                  "claude",
+                  "opencode",
+                  "pi",
+                  "cursor",
+                  "copilot",
+                  "grok"
+                ]
+              },
+              "model": {
+                "type": "string",
+                "minLength": 1
+              },
+              "effort": {
+                "type": "string",
+                "minLength": 1
+              },
+              "writeMode": {
+                "type": "string",
+                "enum": [
+                  "read_only",
+                  "allowed",
+                  "full_access"
+                ]
+              },
+              "timeoutMs": {
+                "type": "integer",
+                "exclusiveMinimum": 0,
+                "maximum": 604800000
+              }
+            },
+            "required": [
+              "provider"
+            ],
+            "additionalProperties": false
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "execution": {
+      "default": {},
+      "type": "object",
+      "properties": {
+        "mode": {
+          "default": "supervised",
+          "type": "string",
+          "enum": [
+            "readonly",
+            "supervised",
+            "autonomous"
+          ]
+        },
+        "envAllowAll": {
+          "default": false,
+          "type": "boolean"
+        },
+        "envAllowlist": {
+          "default": [],
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "sandbox": {
+          "default": "auto",
+          "type": "string",
+          "enum": [
+            "auto",
+            "none"
+          ]
+        },
+        "sandboxNetwork": {
+          "default": "allow",
+          "type": "string",
+          "enum": [
+            "allow",
+            "deny"
+          ]
+        },
+        "requireSandboxForAutonomous": {
+          "default": true,
+          "type": "boolean"
+        }
+      },
+      "additionalProperties": false
+    },
+    "logging": {
+      "default": {},
+      "type": "object",
+      "properties": {
+        "level": {
+          "default": "info",
+          "type": "string",
+          "enum": [
+            "silent",
+            "error",
+            "warn",
+            "info",
+            "debug"
+          ]
+        },
+        "format": {
+          "default": "json",
+          "type": "string",
+          "enum": [
+            "json",
+            "pretty"
+          ]
+        },
+        "requests": {
+          "default": true,
+          "type": "boolean"
+        },
+        "assets": {
+          "default": false,
+          "type": "boolean"
+        },
+        "toolCalls": {
+          "default": true,
+          "type": "boolean"
+        },
+        "shellCommands": {
+          "default": false,
+          "type": "boolean"
+        }
+      },
+      "additionalProperties": false
+    },
+    "tls": {
+      "default": {
+        "certFile": null,
+        "keyFile": null,
+        "acmeDir": null
+      },
+      "type": "object",
+      "properties": {
+        "certFile": {
+          "default": null,
+          "anyOf": [
+            {
+              "type": "string",
+              "minLength": 1
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "keyFile": {
+          "default": null,
+          "anyOf": [
+            {
+              "type": "string",
+              "minLength": 1
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "acmeDir": {
+          "default": null,
+          "anyOf": [
+            {
+              "type": "string",
+              "minLength": 1
+            },
+            {
+              "type": "null"
+            }
+          ]
+        }
+      },
+      "additionalProperties": false
+    },
+    "oauth": {
+      "default": {},
+      "type": "object",
+      "properties": {
+        "accessTokenTtlSeconds": {
+          "default": 3600,
+          "type": "integer",
+          "exclusiveMinimum": 0,
+          "maximum": 9007199254740991
+        },
+        "refreshTokenTtlSeconds": {
+          "default": 2592000,
+          "type": "integer",
+          "exclusiveMinimum": 0,
+          "maximum": 9007199254740991
+        },
+        "scopes": {
+          "default": [
+            "hearth"
+          ],
+          "minItems": 1,
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "allowedRedirectHosts": {
+          "default": [
+            "chatgpt.com",
+            "claude.ai",
+            "anthropic.com",
+            "localhost",
+            "127.0.0.1"
+          ],
+          "minItems": 1,
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "required": [
+    "configVersion"
+  ],
+  "additionalProperties": false
+}

package/scripts/copy-dashboard.mjs

@@ -0,0 +1,9 @@
+// Copies the no-build dashboard SPA into dist/dashboard for packaging.
+import { cpSync, mkdirSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+mkdirSync(resolve(root, "dist/dashboard"), { recursive: true });
+cpSync(resolve(root, "src/dashboard"), resolve(root, "dist/dashboard"), { recursive: true });
+console.log("dashboard copied to dist/dashboard");

package/scripts/fix-node-pty-permissions.mjs

@@ -0,0 +1,22 @@
+import { chmod } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+if (process.platform === "darwin") {
+  const projectRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+  for (const architecture of ["arm64", "x64"]) {
+    const helper = resolve(
+      projectRoot,
+      "node_modules",
+      "node-pty",
+      "prebuilds",
+      `darwin-${architecture}`,
+      "spawn-helper",
+    );
+    try {
+      await chmod(helper, 0o755);
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+    }
+  }
+}

package/scripts/generate-config-schema.ts

@@ -0,0 +1,9 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import {
+  hearthConfigJsonSchema,
+} from "../src/config-schema.js";
+
+const outputPath = new URL("../schema/v1/hearth.schema.json", import.meta.url);
+
+mkdirSync(new URL(".", outputPath), { recursive: true });
+writeFileSync(outputPath, `${JSON.stringify(hearthConfigJsonSchema(), null, 2)}\n`);

package/skills/subagents/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: subagents
+description: Delegate focused coding, research, review, or verification work to a bounded Hearth subagent. Use when a task benefits from separate context, a specialist perspective, or a follow-up with the same worker.
+---
+
+# Hearth subagents
+
+Use the Hearth CLI through the shell or process tool. Run commands from the project the subagent should work on.
+
+## Choose a target
+
+Discover usable targets instead of guessing names:
+
+```bash
+hearth agents targets --json
+```
+
+Configured profiles include a description and may define provider, model, effort, and task instructions. Choose a matching profile when one fits. Use a provider target when no profile fits or a specific provider is needed.
+
+Usually rely on the target's configured model and effort. Pass `--model` or `--effort` only with a value supported by that provider. Hearth passes these values through without translating them between providers.
+
+## Start work
+
+Give the subagent a self-contained brief. Include the objective, relevant paths, constraints, decisions it needs from the current conversation, and the expected result. The subagent receives the brief and its profile instructions, not the parent conversation.
+
+```bash
+hearth agents run <profile-or-provider> "<brief>" --json
+hearth agents run <profile-or-provider> --model <model> --effort <effort> "<brief>" --json
+```
+
+The result contains a Hearth agent `id` and its current status. Execution continues independently, so retain the ID for later inspection or follow-up.
+
+## Inspect and continue
+
+```bash
+hearth agents show <id> --json
+hearth agents continue <id> "<follow-up brief>" --json
+hearth agents ls --json
+```
+
+- `show` waits briefly for active work, then returns the current status and any
+  available response or error.
+- `continue` gives the same subagent another turn with its existing provider
+  session and context.
+- `ls` returns sessions belonging to the current project.
+
+Run `hearth agents show <id> --json` again later while the status is `running`.
+`completed` includes the response. `failed` includes a structured error, and
+`stopped` is terminal without a successful response. Continue an agent when its
+existing context is useful; start another agent for unrelated work.
+
+## Good uses
+
+- Review a change for correctness, security, or missing tests.
+- Investigate a bounded part of a codebase and report findings.
+- Implement one isolated change with clear acceptance criteria.
+- Run a focused verification pass after other work.