lobster-farmer-cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 murong
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,64 @@
+# Lobster Farmer
+
+## Use in OpenClaw
+
+1. Install and start the game service in this project:
+
+```bash
+npm i -g lobster-farmer-cli
+lobster-farmer start
+```
+
+2. Install the auto-feeding skill with ClawHub (one-time):
+
+```bash
+npx clawhub@latest install lobster-farmer-feeder
+```
+
+3. Startup prompt
+```text
+From now on, enable "Auto Lobster Farming Mode" and keep it enabled until I explicitly say "Disable auto lobster farming mode".
+
+Rules:
+
+1. After every formal reply you send, automatically run one feeding action.
+2. Before feeding, check service status with: lobster-farmer status; if not running, start with lobster-farmer start.
+3. Feeding command: lobster-farmer feed --model "<actual model name used in this turn>" --input-tokens <current input> --output-tokens <current output>.
+4. Use real token stats when available; if exact per-turn values are unavailable, use an approximate delta and mark it as "approx".
+5. If feeding fails, retry once automatically (including port correction if needed). If it still fails, report a short error.
+6. After each feed, append one line: 🦞 Fed | model=... | in=... | out=... | total=... | size=....
+7. If I specify a port, always use that --port for later feed actions.
+```
+
+4. Chat with AI as usual. One feeding action will run automatically per turn.
+
+5. You can also provide explicit feed parameters in your message:
+
+```text
+Please feed the lobster: model=gpt-4.1, input_tokens=1200, output_tokens=300
+```
+
+## Notes
+
+- Auto-feed behavior is controlled by `AGENTS.md` in the workspace root (already included in this project).
+- If you use `OPENCLAW_STATE_DIR`, replace `~/.openclaw` with `$OPENCLAW_STATE_DIR`.
+- Default auto-feed values: `model=auto-agent`, `input_tokens=1`, `output_tokens=1`.
+- Default service port: `18990`.
+
+## Game Asset Credits
+
+- Lobster sprites
+  - `public/game-assets/lobster/spr_lobster_walk_strip6.png`
+  - `public/game-assets/lobster/spr_lobster_searching_bubble_strip10.png`
+  - Source: OpenGameArt - A Lobster Sprite
+  - Link: https://opengameart.org/content/a-lobster-sprite
+  - License: CC-BY 3.0 or CC-BY-SA 3.0
+
+- Underwater background
+  - `public/game-assets/background/underwater-tileable.png`
+  - Source: OpenGameArt - Underwater Scene (loopable)
+  - Link: https://opengameart.org/content/underwater-scene-loopable
+  - License: CC0
+
+- Repository license record
+  - `assets/packs/lobster-swim/docs/LICENSES.md`

package/README.zh-CN.md

@@ -0,0 +1,54 @@
+# Lobster Farmer
+
+## 在 OpenClaw 中使用
+
+1. 在项目目录启动游戏服务：
+
+```bash
+npm i -g lobster-farmer-cli
+lobster-farmer start --port 18990
+```
+
+2. 使用 ClawHub 安装自动喂养 skill（只需一次）：
+
+```bash
+npx clawhub@latest install lobster-farmer-feeder
+```
+
+3. 启用提示词
+```text
+从现在开始启用「自动养龙虾模式」并保持开启，直到我明确说“关闭自动养龙虾模式”。
+
+规则：
+
+1. 你每次给我发送任何正式回复后，都自动执行一次喂龙虾。
+2. 喂龙虾前先检查服务：lobster-farmer status；若未运行则先 lobster-farmer start。
+3. 喂食命令：lobster-farmer feed --model "<本次实际模型名>" --input-tokens <本次input> --output-tokens <本次output>。
+4. token 使用真实统计值；若拿不到单次精确值，则用“本次累计差值”作为近似，并标注“approx”。
+5. 失败时自动重试一次（含端口修正）；仍失败再简短报错。
+6. 每次喂完都附一行：🦞 已喂养 | model=... | in=... | out=... | total=... | size=...。
+7. 若我指定端口，后续固定使用该 --port。
+```
+
+4. 正常和 AI 对话即可，每回合会自动执行一次喂养。
+
+5. 你也可以在提问里指定喂养参数：
+
+```text
+帮我喂养龙虾：model=gpt-4.1, input_tokens=1200, output_tokens=300
+```
+
+## 游戏静态资源来源
+
+- 龙虾精灵
+  - `public/game-assets/lobster/spr_lobster_walk_strip6.png`
+  - `public/game-assets/lobster/spr_lobster_searching_bubble_strip10.png`
+  - 来源：OpenGameArt - A Lobster Sprite
+  - 链接：https://opengameart.org/content/a-lobster-sprite
+  - 许可：CC-BY 3.0 或 CC-BY-SA 3.0
+
+- 海底背景
+  - `public/game-assets/background/underwater-tileable.png`
+  - 来源：OpenGameArt - Underwater Scene (loopable)
+  - 链接：https://opengameart.org/content/underwater-scene-loopable
+  - 许可：CC0

package/bin/lobster-farmer.cjs

@@ -0,0 +1,400 @@
+#!/usr/bin/env node
+
+const { spawn, spawnSync } = require("node:child_process");
+const { existsSync, rmSync, mkdirSync, writeFileSync, readFileSync, openSync } = require("node:fs");
+const { homedir } = require("node:os");
+const { resolve } = require("node:path");
+
+const entry = resolve(__dirname, "../dist/index.js");
+const tscBin = resolve(__dirname, "../node_modules/typescript/bin/tsc");
+const tsConfig = resolve(__dirname, "../tsconfig.json");
+const dataDir = resolve(homedir(), ".lobster-farmer");
+const dbBase = resolve(dataDir, "data.sqlite");
+const pidFile = resolve(dataDir, "lobster-farmer.pid");
+const logFile = resolve(dataDir, "lobster-farmer.log");
+const defaultPort = "18990";
+
+function printHelp() {
+  console.log(`Lobster Farmer - Node single-service lobster game
+
+Usage:
+  lobster-farmer start [--port ${defaultPort}] [--foreground]
+                                           Start game server (default: daemon)
+  lobster-farmer feed --model <name> [--input-tokens <n>] [--output-tokens <n>] [--port ${defaultPort}]
+                                           Feed a model lobster through API
+  lobster-farmer stop                       Stop daemon server
+  lobster-farmer status                     Show daemon status
+  lobster-farmer reset                      Reset sqlite data files
+  lobster-farmer --help                     Show help
+
+Environment:
+  PORT                                     Override server port (default: ${defaultPort})
+`);
+}
+
+function parsePort(value) {
+  const numericPort = Number(value);
+  if (!Number.isInteger(numericPort) || numericPort <= 0 || numericPort > 65535) {
+    throw new Error("Invalid --port value");
+  }
+  return String(numericPort);
+}
+
+function parseNonNegativeInt(value, optionName) {
+  const numberValue = Number(value);
+  if (!Number.isFinite(numberValue)) {
+    throw new Error(`Invalid ${optionName} value`);
+  }
+  const intValue = Math.floor(numberValue);
+  if (intValue < 0) {
+    throw new Error(`${optionName} must be >= 0`);
+  }
+  return intValue;
+}
+
+function parseArgs(argv) {
+  const args = [...argv];
+  let command = "start";
+  let port;
+  let foreground = false;
+  let model;
+  let inputTokens;
+  let outputTokens;
+
+  if (args.length > 0 && !args[0].startsWith("-")) {
+    command = args.shift();
+  }
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+
+    if (arg === "--help" || arg === "-h") {
+      command = "help";
+      continue;
+    }
+
+    if (arg === "--foreground" || arg === "-f") {
+      foreground = true;
+      continue;
+    }
+
+    if (arg === "--port" || arg === "-p") {
+      const value = args[index + 1];
+      index += 1;
+      if (!value) {
+        throw new Error("Missing value for --port");
+      }
+      port = parsePort(value);
+      continue;
+    }
+
+    if (arg.startsWith("--port=")) {
+      const value = arg.split("=")[1];
+      port = parsePort(value);
+      continue;
+    }
+
+    if (arg === "--model" || arg === "-m") {
+      const value = args[index + 1];
+      index += 1;
+      if (!value) {
+        throw new Error("Missing value for --model");
+      }
+      model = String(value);
+      continue;
+    }
+
+    if (arg.startsWith("--model=")) {
+      model = String(arg.split("=")[1] ?? "");
+      continue;
+    }
+
+    if (arg === "--input-tokens" || arg === "-i") {
+      const value = args[index + 1];
+      index += 1;
+      if (value === undefined) {
+        throw new Error("Missing value for --input-tokens");
+      }
+      inputTokens = parseNonNegativeInt(value, "--input-tokens");
+      continue;
+    }
+
+    if (arg.startsWith("--input-tokens=")) {
+      inputTokens = parseNonNegativeInt(arg.split("=")[1], "--input-tokens");
+      continue;
+    }
+
+    if (arg === "--output-tokens" || arg === "-o") {
+      const value = args[index + 1];
+      index += 1;
+      if (value === undefined) {
+        throw new Error("Missing value for --output-tokens");
+      }
+      outputTokens = parseNonNegativeInt(value, "--output-tokens");
+      continue;
+    }
+
+    if (arg.startsWith("--output-tokens=")) {
+      outputTokens = parseNonNegativeInt(arg.split("=")[1], "--output-tokens");
+      continue;
+    }
+
+    throw new Error(`Unknown option: ${arg}`);
+  }
+
+  return { command, port, foreground, model, inputTokens, outputTokens };
+}
+
+function removeIfExists(path) {
+  if (existsSync(path)) {
+    rmSync(path, { force: true });
+  }
+}
+
+function resetData() {
+  removeIfExists(dbBase);
+  removeIfExists(`${dbBase}-shm`);
+  removeIfExists(`${dbBase}-wal`);
+  removeIfExists(pidFile);
+  removeIfExists(logFile);
+  console.log("SQLite data reset complete.");
+}
+
+function ensureBuild() {
+  if (!existsSync(entry)) {
+    const build = spawnSync(process.execPath, [tscBin, "-p", tsConfig], { stdio: "inherit" });
+    if (build.status !== 0) {
+      process.exit(build.status || 1);
+    }
+  }
+}
+
+function readPid() {
+  if (!existsSync(pidFile)) {
+    return null;
+  }
+
+  const content = readFileSync(pidFile, "utf8").trim();
+  const pid = Number(content);
+  if (!Number.isInteger(pid) || pid <= 0) {
+    return null;
+  }
+
+  return pid;
+}
+
+function isProcessRunning(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    if (error && error.code === "EPERM") {
+      return true;
+    }
+    return false;
+  }
+}
+
+function getRunningPid() {
+  const pid = readPid();
+  if (!pid) {
+    return null;
+  }
+
+  if (isProcessRunning(pid)) {
+    return pid;
+  }
+
+  removeIfExists(pidFile);
+  return null;
+}
+
+function startServer(port, foreground) {
+  ensureBuild();
+
+  mkdirSync(dataDir, { recursive: true });
+
+  const env = { ...process.env };
+  if (port) {
+    env.PORT = port;
+  }
+
+  if (foreground) {
+    const child = spawn(process.execPath, [entry], {
+      stdio: "inherit",
+      env
+    });
+
+    child.on("error", (error) => {
+      console.error(error.message || String(error));
+      process.exit(1);
+    });
+
+    child.on("exit", (code, signal) => {
+      if (signal) {
+        process.kill(process.pid, signal);
+        return;
+      }
+      process.exit(code || 0);
+    });
+
+    return;
+  }
+
+  const existingPid = getRunningPid();
+  if (existingPid) {
+    console.log(`Lobster Farmer already running (pid: ${existingPid})`);
+    return;
+  }
+
+  const out = openSync(logFile, "a");
+  const err = openSync(logFile, "a");
+  const child = spawn(process.execPath, [entry], {
+    detached: true,
+    stdio: ["ignore", out, err],
+    env
+  });
+  child.unref();
+
+  writeFileSync(pidFile, String(child.pid));
+  console.log(`Lobster Farmer started in background.`);
+  console.log(`pid: ${child.pid}`);
+  console.log(`log: ${logFile}`);
+}
+
+function stopServer() {
+  const pid = getRunningPid();
+  if (!pid) {
+    console.log("Lobster Farmer is not running.");
+    return;
+  }
+
+  try {
+    process.kill(pid, "SIGTERM");
+  } catch (error) {
+    console.error(error.message || String(error));
+    process.exit(1);
+  }
+
+  removeIfExists(pidFile);
+  console.log(`Lobster Farmer stopped (pid: ${pid}).`);
+}
+
+function showStatus() {
+  const pid = getRunningPid();
+  if (!pid) {
+    console.log("Lobster Farmer status: stopped");
+    return;
+  }
+
+  console.log(`Lobster Farmer status: running (pid: ${pid})`);
+  console.log(`log: ${logFile}`);
+}
+
+function resolvePort(portArg) {
+  return parsePort(portArg || process.env.PORT || defaultPort);
+}
+
+async function feedThroughApi(parsed) {
+  const model = typeof parsed.model === "string" ? parsed.model.trim() : "";
+  if (!model) {
+    throw new Error("feed command requires --model");
+  }
+
+  const inputTokens = parsed.inputTokens ?? 0;
+  const outputTokens = parsed.outputTokens ?? 0;
+  if (inputTokens + outputTokens <= 0) {
+    throw new Error("feed command requires input/output tokens > 0");
+  }
+
+  const port = resolvePort(parsed.port);
+  const url = `http://127.0.0.1:${port}/api/feed`;
+
+  let response;
+  try {
+    response = await fetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify({
+        model,
+        input_tokens: inputTokens,
+        output_tokens: outputTokens
+      })
+    });
+  } catch (error) {
+    throw new Error(`feed request failed: ${error.message || String(error)}`);
+  }
+
+  let payload = {};
+  try {
+    payload = await response.json();
+  } catch (_error) {
+    payload = {};
+  }
+
+  if (!response.ok) {
+    const apiError = payload && typeof payload.error === "string" ? payload.error : `HTTP ${response.status}`;
+    throw new Error(`feed request failed: ${apiError}`);
+  }
+
+  const lobster = payload && typeof payload === "object" ? payload.lobster : null;
+  const size = lobster && typeof lobster.size === "number" ? lobster.size : "n/a";
+  const feeds = lobster && typeof lobster.feeds === "number" ? lobster.feeds : "n/a";
+  const totalTokens = lobster && typeof lobster.tokens === "number" ? lobster.tokens : "n/a";
+
+  console.log(`Fed lobster: ${model}`);
+  console.log(`input_tokens: ${inputTokens}, output_tokens: ${outputTokens}`);
+  console.log(`lobster tokens: ${totalTokens}, feeds: ${feeds}, size: ${size}`);
+}
+
+async function main() {
+  let parsed;
+  try {
+    parsed = parseArgs(process.argv.slice(2));
+  } catch (error) {
+    console.error(error.message || String(error));
+    printHelp();
+    process.exit(1);
+  }
+
+  if (parsed.command === "help") {
+    printHelp();
+    return;
+  }
+
+  if (parsed.command === "reset") {
+    resetData();
+    return;
+  }
+
+  if (parsed.command === "stop") {
+    stopServer();
+    return;
+  }
+
+  if (parsed.command === "status") {
+    showStatus();
+    return;
+  }
+
+  if (parsed.command === "start") {
+    startServer(parsed.port, parsed.foreground);
+    return;
+  }
+
+  if (parsed.command === "feed") {
+    await feedThroughApi(parsed);
+    return;
+  }
+
+  console.error(`Unknown command: ${parsed.command}`);
+  printHelp();
+  process.exit(1);
+}
+
+main().catch((error) => {
+  console.error(error.message || String(error));
+  process.exit(1);
+});