@tridha643/hestia 1.0.0

package/dist/proc-relay.js

@@ -0,0 +1,117 @@
+#!/usr/bin/env bun
+// @bun
+
+// packages/engine/src/proc/proc-relay.ts
+import {
+  chmodSync,
+  closeSync,
+  existsSync,
+  openSync,
+  renameSync,
+  rmSync,
+  statSync,
+  writeSync
+} from "fs";
+import { spawn } from "child_process";
+var MAX_LOG_BYTES = 25 * 1024 * 1024;
+var ARCHIVE_COUNT = 3;
+var RELAY_SPEC_ENV = "HESTIA_PROC_RELAY_SPEC";
+function relaySpec() {
+  const encoded = process.env[RELAY_SPEC_ENV];
+  delete process.env[RELAY_SPEC_ENV];
+  if (encoded === undefined)
+    throw new Error(`${RELAY_SPEC_ENV} is missing`);
+  const value = JSON.parse(Buffer.from(encoded, "base64").toString("utf8"));
+  if (!Array.isArray(value.argv) || value.argv.length === 0 || typeof value.cwd !== "string" || typeof value.logPath !== "string") {
+    throw new Error("invalid proc relay spec");
+  }
+  return value;
+}
+
+class RotatingLogWriter {
+  path;
+  maxLogBytes;
+  archiveCount;
+  #fd;
+  #bytes;
+  constructor(path, maxLogBytes = MAX_LOG_BYTES, archiveCount = ARCHIVE_COUNT) {
+    this.path = path;
+    this.maxLogBytes = maxLogBytes;
+    this.archiveCount = archiveCount;
+    this.#fd = openSync(path, "a", 384);
+    chmodSync(path, 384);
+    this.#bytes = statSync(path).size;
+  }
+  write(chunk) {
+    let offset = 0;
+    while (offset < chunk.byteLength) {
+      if (this.#bytes >= this.maxLogBytes)
+        this.rotate();
+      const length = Math.min(chunk.byteLength - offset, this.maxLogBytes - this.#bytes);
+      writeSync(this.#fd, chunk, offset, length);
+      offset += length;
+      this.#bytes += length;
+    }
+  }
+  close() {
+    closeSync(this.#fd);
+  }
+  rotate() {
+    closeSync(this.#fd);
+    rmSync(`${this.path}.${this.archiveCount}`, { force: true });
+    for (let index = this.archiveCount - 1;index >= 1; index -= 1) {
+      const source = `${this.path}.${index}`;
+      if (existsSync(source))
+        renameSync(source, `${this.path}.${index + 1}`);
+    }
+    if (existsSync(this.path))
+      renameSync(this.path, `${this.path}.1`);
+    this.#fd = openSync(this.path, "a", 384);
+    chmodSync(this.path, 384);
+    this.#bytes = 0;
+  }
+}
+function forwardSignal(child, signal) {
+  if (child.exitCode !== null || child.signalCode !== null)
+    return;
+  try {
+    child.kill(signal);
+  } catch {}
+}
+async function main() {
+  const spec = relaySpec();
+  const writer = new RotatingLogWriter(spec.logPath);
+  const child = spawn(spec.argv[0], spec.argv.slice(1), {
+    cwd: spec.cwd,
+    env: spec.env,
+    stdio: ["ignore", "pipe", "pipe"]
+  });
+  child.stdout?.on("data", (chunk) => writer.write(chunk));
+  child.stderr?.on("data", (chunk) => writer.write(chunk));
+  process.on("SIGTERM", () => forwardSignal(child, "SIGTERM"));
+  process.on("SIGINT", () => forwardSignal(child, "SIGINT"));
+  const result = await new Promise((resolve) => {
+    child.once("error", (error) => {
+      writer.write(Buffer.from(`hestia proc relay: ${error.message}
+`));
+      resolve({ code: 127, signal: null });
+    });
+    child.once("exit", (code, signal) => resolve({ code, signal }));
+  });
+  writer.close();
+  if (result.signal !== null)
+    process.exit(1);
+  process.exit(result.code ?? 1);
+}
+if (import.meta.main) {
+  main().catch((error) => {
+    process.stderr.write(`hestia proc relay failed: ${error.message}
+`);
+    process.exit(1);
+  });
+}
+export {
+  RotatingLogWriter
+};
+
+//# debugId=D0D371B26D9A99F264756E2164756E21

package/dist/proc-relay.js.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["../packages/engine/src/proc/proc-relay.ts"],
+  "sourcesContent": [
+    "#!/usr/bin/env bun\nimport {\n  chmodSync,\n  closeSync,\n  existsSync,\n  openSync,\n  renameSync,\n  rmSync,\n  statSync,\n  writeSync,\n} from \"node:fs\";\nimport { spawn, type ChildProcess } from \"node:child_process\";\n\nconst MAX_LOG_BYTES = 25 * 1024 * 1024;\nconst ARCHIVE_COUNT = 3;\nconst RELAY_SPEC_ENV = \"HESTIA_PROC_RELAY_SPEC\";\n\ninterface RelaySpec {\n  argv: string[];\n  cwd: string;\n  env: Record<string, string | undefined>;\n  logPath: string;\n}\n\nfunction relaySpec(): RelaySpec {\n  const encoded = process.env[RELAY_SPEC_ENV];\n  delete process.env[RELAY_SPEC_ENV];\n  if (encoded === undefined) throw new Error(`${RELAY_SPEC_ENV} is missing`);\n  const value = JSON.parse(Buffer.from(encoded, \"base64\").toString(\"utf8\")) as RelaySpec;\n  if (!Array.isArray(value.argv) || value.argv.length === 0 ||\n    typeof value.cwd !== \"string\" || typeof value.logPath !== \"string\") {\n    throw new Error(\"invalid proc relay spec\");\n  }\n  return value;\n}\n\nexport class RotatingLogWriter {\n  #fd: number;\n  #bytes: number;\n\n  constructor(\n    readonly path: string,\n    readonly maxLogBytes = MAX_LOG_BYTES,\n    readonly archiveCount = ARCHIVE_COUNT,\n  ) {\n    this.#fd = openSync(path, \"a\", 0o600);\n    chmodSync(path, 0o600);\n    this.#bytes = statSync(path).size;\n  }\n\n  write(chunk: Buffer): void {\n    let offset = 0;\n    while (offset < chunk.byteLength) {\n      if (this.#bytes >= this.maxLogBytes) this.rotate();\n      const length = Math.min(chunk.byteLength - offset, this.maxLogBytes - this.#bytes);\n      writeSync(this.#fd, chunk, offset, length);\n      offset += length;\n      this.#bytes += length;\n    }\n  }\n\n  close(): void {\n    closeSync(this.#fd);\n  }\n\n  private rotate(): void {\n    closeSync(this.#fd);\n    rmSync(`${this.path}.${this.archiveCount}`, { force: true });\n    for (let index = this.archiveCount - 1; index >= 1; index -= 1) {\n      const source = `${this.path}.${index}`;\n      if (existsSync(source)) renameSync(source, `${this.path}.${index + 1}`);\n    }\n    if (existsSync(this.path)) renameSync(this.path, `${this.path}.1`);\n    this.#fd = openSync(this.path, \"a\", 0o600);\n    chmodSync(this.path, 0o600);\n    this.#bytes = 0;\n  }\n}\n\nfunction forwardSignal(child: ChildProcess, signal: NodeJS.Signals): void {\n  if (child.exitCode !== null || child.signalCode !== null) return;\n  try {\n    child.kill(signal);\n  } catch {}\n}\n\nasync function main(): Promise<void> {\n  const spec = relaySpec();\n  const writer = new RotatingLogWriter(spec.logPath);\n  const child = spawn(spec.argv[0]!, spec.argv.slice(1), {\n    cwd: spec.cwd,\n    env: spec.env as NodeJS.ProcessEnv,\n    stdio: [\"ignore\", \"pipe\", \"pipe\"],\n  });\n  child.stdout?.on(\"data\", (chunk: Buffer) => writer.write(chunk));\n  child.stderr?.on(\"data\", (chunk: Buffer) => writer.write(chunk));\n  process.on(\"SIGTERM\", () => forwardSignal(child, \"SIGTERM\"));\n  process.on(\"SIGINT\", () => forwardSignal(child, \"SIGINT\"));\n  const result = await new Promise<{ code: number | null; signal: NodeJS.Signals | null }>((resolve) => {\n    child.once(\"error\", (error) => {\n      writer.write(Buffer.from(`hestia proc relay: ${error.message}\\n`));\n      resolve({ code: 127, signal: null });\n    });\n    child.once(\"exit\", (code, signal) => resolve({ code, signal }));\n  });\n  writer.close();\n  if (result.signal !== null) process.exit(1);\n  process.exit(result.code ?? 1);\n}\n\nif (import.meta.main) {\n  void main().catch((error) => {\n    process.stderr.write(`hestia proc relay failed: ${(error as Error).message}\\n`);\n    process.exit(1);\n  });\n}\n"
+  ],
+  "mappings": "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",
+  "debugId": "D0D371B26D9A99F264756E2164756E21",
+  "names": []
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@tridha643/hestia",
+  "version": "1.0.0",
+  "description": "Per-worktree isolated development stacks for humans and coding agents",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tridha643/hestia"
+  },
+  "type": "module",
+  "workspaces": ["packages/*"],
+  "bin": {
+    "hestia": "./dist/cli.js"
+  },
+  "scripts": {
+    "hestia": "bun run packages/cli/src/index.ts",
+    "test": "bun test",
+    "test:tui": "bun test packages/tui/test test/pty",
+    "build": "bun run scripts/build-dist.ts",
+    "prepack": "bun run build"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/react": "19.2.14",
+    "portless": "0.15.1",
+    "tuistory": "0.0.16",
+    "typescript": "^5.9.0"
+  },
+  "dependencies": {
+    "@opentui/core": "0.4.3",
+    "@opentui/react": "0.4.3",
+    "react": "19.2.4",
+    "yaml": "^2.6.0"
+  },
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "os": ["darwin"],
+  "cpu": ["arm64", "x64"],
+  "files": [
+    "dist",
+    "skills/hestia",
+    "README.md",
+    "NOTICES.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}

package/skills/hestia/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: hestia
+description: Discover, configure, run, inspect, expose, and tear down isolated macOS/Bun development workloads in parallel Git worktrees.
+---
+
+# Hestia agent workflow
+
+Hestia owns development workload lifecycle and reachability for this worktree.
+Do not choose ports, start configured dev servers directly, or run a second
+Cloudflare connector beside Hestia.
+
+## Start with discovery
+
+```bash
+hestia version --json
+hestia discover --json
+hestia doctor --json
+```
+
+Discovery is read-only. Inspect:
+
+- `repository`: exact repo, `repoId`, branch, and absolute worktree.
+- `runnableWorkloads` and `candidateWorkloads`.
+- `bindings` and configured endpoint aliases.
+- `decisionSource`: `discovery`, `repository`, `machine`, or `worktree`.
+- `missingDecisions`, `conflicts`, and `suggestions`.
+
+Do not guess when discovery reports a missing decision. If repository changes
+are authorized, use a suggested `hestia init ... --scope repository --write`.
+For personal/non-portable setup use `--scope machine --write`. Without
+`--write`, init prints the complete proposed TOML and changes nothing. Hestia
+never commits.
+
+Examples:
+
+```bash
+hestia init dockerfile web Dockerfile --scope repository
+hestia init proc consumer --scope machine --no-port -- bun run consume
+hestia init endpoint dashboard web 3000/tcp http --scope repository --write
+hestia init wrangler slack-worker apps/slack/wrangler.toml --scope repository --write
+hestia discover --json
+```
+
+Configuration layers are worktree runtime intent, machine repository overlay
+at `~/.hestia/repositories/<repoId>.toml`, optional committed `hestia.toml`,
+then automatic discovery. Conflicts fail rather than silently overriding a
+workload source. `.hestia/` must remain ignored.
+
+## Run and consume structured endpoints
+
+```bash
+hestia up --json
+hestia endpoint list --json
+hestia endpoint get dashboard --json
+hestia logs web -f --json
+```
+
+A workload is a lifecycle/logging unit. A binding is an owned socket such as
+`api:8080/tcp`. An endpoint alias assigns protocol meaning to a binding.
+Resolution order is exact alias, canonical `workload:target/protocol`, then a
+uniquely-bound workload. Handle `service-port-ambiguous` by using a reported
+selector or configured alias.
+
+Canonical port variables look like `HESTIA_API_9090_TCP_PORT`. Only a unique
+binding receives `HESTIA_API_PORT`. HTTP aliases also receive direct/local URL
+variables. Never invent an HTTP URL for a raw TCP/UDP endpoint.
+
+Use `hestia run` only for explicit ad-hoc processes not already declared as a
+workload:
+
+```bash
+hestia run --name web -- bun run dev
+hestia run --name consumer --no-port -- bun run consume
+```
+
+Hestia injects `$PORT` and substitutes `{port}`. Raw `--env` values remain in
+memory and are not persisted. Logs are bounded by the rotating relay.
+
+## Routes and exposure
+
+```bash
+hestia route add dashboard --json
+hestia route disable dashboard --json
+hestia route reset dashboard --json
+hestia open dashboard --local --json
+hestia expose dashboard --json
+hestia expose dashboard --tunnel tri --zone example.dev --json
+```
+
+Local route overrides are per worktree. `disable` suppresses repository or
+machine defaults; `reset` removes the override and restores defaults.
+
+Public ingress is fail-closed but unauthenticated. Hestiad verifies the current
+process/container identity and port ownership before every origin connection.
+If a port is recycled, the foreign listener receives zero bytes.
+
+Named mode never writes DNS. It requires:
+
+```text
+*.<zone> CNAME <tunnel-uuid>.cfargotunnel.com
+```
+
+Handle `dns-route-required` by reporting its `wildcardTarget` to the human.
+Never use the removed `--overwrite-dns`. Named mode may use
+`--keep-host-header`; quick mode rejects it. Never start another
+`cloudflared tunnel run` for an adopted tunnel.
+
+## Inspect and finish
+
+```bash
+hestia status --json
+hestia env --json
+hestia doctor --json
+hestia tui
+hestia down
+```
+
+Fleet shows the repository, selected branch, absolute worktree, project,
+workloads, endpoints, and logs. It is for human operation; agents should use
+JSON/NDJSON commands.
+
+Run `down` before switching or deleting the branch. After deletion, use the
+recorded project with `hestia down --project <project>`. Docker workloads
+cannot be stopped individually (`backend-not-stoppable`); proc/Wrangler
+workloads can. Named volumes are retained unless `--destroy` is explicit.
+
+## Stable error remedies
+
+| code | remedy |
+|---|---|
+| `setup-required` | follow `discover --json` suggestions with explicit authorization |
+| `config-conflict` / `config-invalid` | fix the reported layer/path; do not guess precedence |
+| `state-not-ignored` | add the exact `.hestia/` line reported by `doctor` |
+| `state-corrupt` | inspect the path, then use the reported `down --project` recovery |
+| `migration-required` | inspect if needed, then down the legacy stack |
+| `stack-identity-changed` | down the recorded project before continuing on this checkout |
+| `env-key-conflict` | rename one workload/alias so normalized env keys differ |
+| `compose-unsupported` | replace the unsupported global/shared construct or use a supported topology |
+| `service-port-ambiguous` | use a canonical selector or endpoint alias |
+| `proc-ready-timeout` | inspect logs; use `--no-port` only for non-servers |
+| `stack-limit` | down an owned stack or retry with `--wait=120` |
+| `dns-route-required` | configure its wildcard CNAME target |
+| `tunnel-busy` | stop the foreign connector; do not kill processes Hestia did not start |
+| `route-origin-unavailable` | restart the workload through Hestia |
+| `backend-not-stoppable` | use `hestia down` for Docker workloads |
+
+`--json` failures are `{ "error": { "code", "message", "details"? } }`.
+`hestia logs --json` is NDJSON, one `LogLine` per line.