flockbay 0.10.15

package/README.md

@@ -0,0 +1,56 @@
+# Flockbay CLI
+
+Code on the go controlling Claude/Codex sessions from your mobile device.
+
+Code anywhere.
+
+Flockbay CLI is the command-line tool for running and controlling Flockbay sessions (including daemon and Codex mode).
+
+## Installation
+
+```bash
+npm install -g flockbay
+```
+
+## Usage
+
+```bash
+flockbay
+```
+
+This will:
+1. Start a Claude Code session
+2. Display a QR code to connect from your mobile device
+3. Allow real-time session sharing between Claude Code and your mobile app
+
+## Commands
+
+- `flockbay auth` – Manage authentication
+- `flockbay codex` – Start Codex mode
+- `flockbay connect` – Store AI vendor API keys in Flockbay
+- `flockbay notify` – Send a push notification to your devices
+- `flockbay daemon` – Manage background service
+- `flockbay doctor` – System diagnostics & troubleshooting
+
+## Options
+
+- `-h, --help` - Show help
+- `-v, --version` - Show version
+- `-m, --model <model>` - Claude model to use (default: sonnet)
+- `-p, --permission-mode <mode>` - Permission mode: auto, default, or plan
+- `--claude-env KEY=VALUE` - Set environment variable for Claude Code (e.g., for [claude-code-router](https://github.com/musistudio/claude-code-router))
+- `--claude-arg ARG` - Pass additional argument to Claude CLI
+
+Run `flockbay --help` for the complete list of options.
+
+## Requirements
+
+- Node.js >= 20.0.0
+  - Required by `eventsource-parser@3.0.5`, which is required by
+  `@modelcontextprotocol/sdk`, which we used to implement permission forwarding
+  to mobile app
+- Claude CLI installed & logged in (`claude` command available in PATH)
+
+## License
+
+Proprietary. Copyright (c) 2024-2026 Flockbay. All rights reserved.

package/bin/flockbay-mcp.mjs

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+
+import { execFileSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// Ensure Node flags to reduce noisy warnings on stdout (which could interfere with MCP).
+const hasNoWarnings = process.execArgv.includes('--no-warnings');
+const hasNoDeprecation = process.execArgv.includes('--no-deprecation');
+
+const projectRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+const distEntrypoint = join(projectRoot, 'dist', 'codex', 'flockbayMcpStdioBridge.mjs');
+const devEntrypoint = join(projectRoot, 'src', 'codex', 'flockbayMcpStdioBridge.ts');
+const entrypoint = existsSync(distEntrypoint) ? distEntrypoint : devEntrypoint;
+const useTsx = entrypoint.endsWith('.ts');
+const invokedCwd = process.cwd();
+
+function resolveTsxImportArgs() {
+  if (!useTsx) return [];
+  const candidates = [
+    join(projectRoot, 'node_modules', 'tsx', 'dist', 'esm', 'index.mjs'),
+    join(projectRoot, 'node_modules', 'tsx', 'dist', 'esm', 'index.js'),
+    join(projectRoot, 'node_modules', 'tsx', 'dist', 'index.mjs'),
+    join(projectRoot, 'node_modules', 'tsx', 'dist', 'index.js'),
+  ];
+  const resolved = candidates.find(existsSync);
+  return resolved ? ['--import', resolved] : ['--import', 'tsx'];
+}
+
+if (!hasNoWarnings || !hasNoDeprecation || useTsx) {
+  try {
+    execFileSync(
+      process.execPath,
+      [
+        '--no-warnings',
+        '--no-deprecation',
+        ...resolveTsxImportArgs(),
+        entrypoint,
+        ...process.argv.slice(2),
+      ],
+      {
+        stdio: 'inherit',
+        ...(useTsx ? { cwd: projectRoot } : {}),
+        env: {
+          ...process.env,
+          ...(useTsx ? { FLOCKBAY_INVOKED_CWD: invokedCwd } : {}),
+        },
+      },
+    );
+  } catch (error) {
+    process.exit(error?.status || 1);
+  }
+} else {
+  await import('../dist/codex/flockbayMcpStdioBridge.mjs');
+}

package/bin/flockbay.mjs

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+
+import { execFileSync } from 'node:child_process';
+import { existsSync, statSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// Ensure Node flags to reduce noisy warnings on stdout.
+const hasNoWarnings = process.execArgv.includes('--no-warnings');
+const hasNoDeprecation = process.execArgv.includes('--no-deprecation');
+
+const projectRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+const distEntrypoint = join(projectRoot, 'dist', 'index.mjs');
+const devEntrypoint = join(projectRoot, 'src', 'index.ts');
+const entrypoint = (() => {
+  const forceSrc = process.env.FLOCKBAY_USE_SRC === '1';
+  const forceDist = process.env.FLOCKBAY_USE_DIST === '1';
+
+  const hasDist = existsSync(distEntrypoint);
+  const hasDev = existsSync(devEntrypoint);
+
+  if (forceSrc && hasDev) return devEntrypoint;
+  if (forceDist && hasDist) return distEntrypoint;
+
+  if (hasDist && hasDev) {
+    try {
+      const devTime = statSync(devEntrypoint).mtimeMs;
+      const distTime = statSync(distEntrypoint).mtimeMs;
+      if (devTime > distTime) return devEntrypoint;
+    } catch {
+      // ignore
+    }
+    return distEntrypoint;
+  }
+
+  return hasDist ? distEntrypoint : devEntrypoint;
+})();
+const useTsx = entrypoint.endsWith('.ts');
+const invokedCwd = process.cwd();
+
+function resolveTsxImportArgs() {
+  if (!useTsx) return [];
+  const candidates = [
+    join(projectRoot, 'node_modules', 'tsx', 'dist', 'esm', 'index.mjs'),
+    join(projectRoot, 'node_modules', 'tsx', 'dist', 'esm', 'index.js'),
+    join(projectRoot, 'node_modules', 'tsx', 'dist', 'index.mjs'),
+    join(projectRoot, 'node_modules', 'tsx', 'dist', 'index.js'),
+  ];
+  const resolved = candidates.find(existsSync);
+  return resolved ? ['--import', resolved] : ['--import', 'tsx'];
+}
+
+if (!hasNoWarnings || !hasNoDeprecation || useTsx) {
+  try {
+    execFileSync(
+      process.execPath,
+      [
+        '--no-warnings',
+        '--no-deprecation',
+        ...resolveTsxImportArgs(),
+        entrypoint,
+        ...process.argv.slice(2),
+      ],
+      {
+        stdio: 'inherit',
+        ...(useTsx ? { cwd: projectRoot } : {}),
+        env: {
+          ...process.env,
+          ...(useTsx ? { FLOCKBAY_INVOKED_CWD: invokedCwd } : {}),
+        },
+      },
+    );
+  } catch (error) {
+    process.exit(error?.status || 1);
+  }
+} else {
+  await import('../dist/index.mjs');
+}

package/dist/codex/flockbayMcpStdioBridge.cjs

@@ -0,0 +1,383 @@
+'use strict';
+
+var mcp_js = require('@modelcontextprotocol/sdk/server/mcp.js');
+var stdio_js = require('@modelcontextprotocol/sdk/server/stdio.js');
+var index_js = require('@modelcontextprotocol/sdk/client/index.js');
+var streamableHttp_js = require('@modelcontextprotocol/sdk/client/streamableHttp.js');
+var z = require('zod');
+
+function getToolCallTimeoutMs(name, args) {
+  return void 0;
+}
+function parseArgs(argv) {
+  let url = null;
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--url" && i + 1 < argv.length) {
+      url = argv[i + 1];
+      i++;
+    }
+  }
+  return { url };
+}
+async function main() {
+  const { url: urlFromArgs } = parseArgs(process.argv.slice(2));
+  const baseUrl = urlFromArgs || process.env.FLOCKBAY_HTTP_MCP_URL || "";
+  if (!baseUrl) {
+    process.stderr.write(
+      "[flockbay-mcp] Missing target URL. Set FLOCKBAY_HTTP_MCP_URL or pass --url <http://127.0.0.1:PORT>\n"
+    );
+    process.exit(2);
+  }
+  let httpClient = null;
+  async function ensureHttpClient() {
+    if (httpClient) return httpClient;
+    const client = new index_js.Client(
+      { name: "flockbay-stdio-bridge", version: "1.0.0" },
+      { capabilities: {} }
+    );
+    const transport = new streamableHttp_js.StreamableHTTPClientTransport(new URL(baseUrl));
+    await client.connect(transport);
+    httpClient = client;
+    return client;
+  }
+  const server = new mcp_js.McpServer({
+    name: "Flockbay MCP Bridge",
+    version: "1.0.0"
+  });
+  function forwardTool(name, inputSchema, title, description) {
+    server.registerTool(
+      name,
+      { title, description, inputSchema },
+      async (args) => {
+        try {
+          const client = await ensureHttpClient();
+          const timeout = getToolCallTimeoutMs(name, args);
+          const response = await client.callTool(
+            { name, arguments: args },
+            void 0,
+            timeout ? { timeout } : void 0
+          );
+          return response;
+        } catch (error) {
+          return {
+            content: [
+              { type: "text", text: `Failed to call tool "${name}": ${error instanceof Error ? error.message : String(error)}` }
+            ],
+            isError: true
+          };
+        }
+      }
+    );
+  }
+  forwardTool(
+    "change_title",
+    { title: z.z.string().describe("The new title for the chat session") },
+    "Change Chat Title",
+    "Change the title of the current chat session"
+  );
+  forwardTool(
+    "latest_user_images",
+    {
+      limit: z.z.number().int().positive().optional().describe("Max number of images to return (default 4).")
+    },
+    "Latest User Images",
+    "Return the latest image attachments sent by the user (as image content blocks)."
+  );
+  forwardTool(
+    "read_images",
+    {
+      paths: z.z.array(z.z.string()).describe("Image paths (absolute or relative to the session directory). PNG only."),
+      limit: z.z.number().int().positive().optional().describe("Max number of images to include (default 10)."),
+      upload: z.z.boolean().optional().describe("Upload images to the session screenshots store and return HTTPS URLs (default true)."),
+      includeBase64: z.z.boolean().optional().describe("Include base64 data in the payload (default false)."),
+      maxBytesPerImage: z.z.number().int().positive().optional().describe("Max bytes per image when includeBase64=true (default 2500000).")
+    },
+    "Read Images",
+    "Read one or more local PNG images by path and return a `{ views: [...] }` payload for the UI."
+  );
+  forwardTool(
+    "ask_user_question",
+    {
+      questions: z.z.array(
+        z.z.object({
+          key: z.z.string().optional().describe("Stable key for this question (defaults to header)."),
+          header: z.z.string().describe("Short label for the question."),
+          question: z.z.string().describe("The question to show to the user."),
+          options: z.z.array(z.z.object({
+            label: z.z.string().describe("Option label"),
+            description: z.z.string().optional().describe("Optional short description")
+          })).min(1).describe("Available choices"),
+          multiSelect: z.z.boolean().optional().describe("Allow multiple selections")
+        })
+      ).describe("Questions to ask the user")
+    },
+    "Ask User Question",
+    "Ask the user one or more multiple-choice questions and return structured answers."
+  );
+  forwardTool(
+    "coordination_ledger_snapshot",
+    {},
+    "Coordination Ledger Snapshot",
+    "Fetch the current coordination ledger snapshot (work items + intent) for this project."
+  );
+  forwardTool(
+    "ledger_read",
+    {},
+    "Ledger Read",
+    "Alias for coordination_ledger_snapshot: fetch the current shared coordination ledger snapshot for this project."
+  );
+  forwardTool(
+    "coordination_update_intent",
+    {
+      summary: z.z.string().optional().describe("Optional short summary/title for this work item."),
+      status: z.z.string().optional().describe("Optional work item status (e.g. wip, blocked)."),
+      plannedFiles: z.z.array(z.z.string()).optional().describe("Repo-relative file paths you plan to touch."),
+      activeFiles: z.z.array(z.z.string()).optional().describe("Repo-relative file paths you are actively editing right now."),
+      doneFiles: z.z.array(z.z.string()).optional().describe("Repo-relative file paths you are done with (safe for others to start)."),
+      waitingOnFiles: z.z.array(z.z.string()).optional().describe("Repo-relative file paths you are waiting on (owned/planned by others)."),
+      leaseMs: z.z.number().int().positive().optional().describe("Soft lease TTL for this ledger entry (ms). UI-only staleness hint; default ~2h.")
+    },
+    "Coordination Update Intent",
+    "Update this work item\u2019s coordination intent (planned/active/done/waiting). Communication-only (trust-first), not an enforced lock."
+  );
+  forwardTool(
+    "coordination_check_files",
+    {
+      files: z.z.array(z.z.string()).describe('Repo-relative file paths to check (e.g. "Config/DefaultGame.ini").'),
+      includeSelf: z.z.boolean().optional().describe("Include this work item in results (default true).")
+    },
+    "Coordination Check Files",
+    "Check which work items currently claim the given files (planned/active), ignoring stale/done entries."
+  );
+  forwardTool(
+    "coordination_claim_files",
+    {
+      files: z.z.array(z.z.string()).describe("Repo-relative file paths to claim."),
+      mode: z.z.enum(["planned", "active", "planned_and_active"]).optional().describe("How to claim: planned or active (default active)."),
+      leaseMs: z.z.number().int().positive().optional().describe("Soft lease TTL for this ledger entry (ms). Used to avoid stale blocks; default ~2h.")
+    },
+    "Coordination Claim Files",
+    "Atomically claim files for this work item if they are not currently owned by another active work item."
+  );
+  forwardTool(
+    "ledger_claim",
+    {
+      summary: z.z.string().optional().describe("Optional short summary/title for this work item."),
+      status: z.z.string().optional().describe("Optional work item status (e.g. wip, blocked)."),
+      plannedFiles: z.z.array(z.z.string()).optional().describe("Repo-relative file paths you plan to touch."),
+      files: z.z.array(z.z.string()).describe("Repo-relative file paths to claim."),
+      mode: z.z.enum(["planned", "active", "planned_and_active"]).optional().describe("How to claim: planned or active (default active)."),
+      leaseMs: z.z.number().int().positive().optional().describe("Soft lease TTL for this ledger entry (ms). Used to avoid stale blocks; default ~2h.")
+    },
+    "Ledger Claim",
+    "Alias for intent+claim: updates intent (optional) then atomically claims files for this work item."
+  );
+  forwardTool(
+    "ledger_release",
+    {
+      status: z.z.string().optional().describe('Status to set (default "done").'),
+      doneFiles: z.z.array(z.z.string()).optional().describe("Repo-relative file paths you finished (will be unioned with existing doneFiles)."),
+      clearActive: z.z.boolean().optional().describe("If true, clears activeFiles (default true)."),
+      clearPlanned: z.z.boolean().optional().describe("If true, clears plannedFiles too (default false)."),
+      commitHash: z.z.string().optional().describe("Optional commit hash to record on the work item.")
+    },
+    "Ledger Release",
+    "Mark work item complete/released: union doneFiles, clear active (and optionally planned), and set status (default done)."
+  );
+  forwardTool(
+    "docs_index_read",
+    {},
+    "Docs Index Read",
+    "Read the required game Documentation index (index.md) and a compact tree summary."
+  );
+  forwardTool(
+    "docs_tree",
+    {},
+    "Docs Tree",
+    "Fetch the Documentation Library tree (folders + docs metadata; no bodies)."
+  );
+  forwardTool(
+    "docs_get",
+    {
+      nodeId: z.z.string().describe("Document node id.")
+    },
+    "Docs Get",
+    "Fetch a single Documentation document node (includes markdown body)."
+  );
+  forwardTool(
+    "docs_search",
+    {
+      q: z.z.string().describe("Search query."),
+      limit: z.z.number().int().positive().optional().describe("Max results (default 50).")
+    },
+    "Docs Search",
+    "Search documentation by title/body (server-side)."
+  );
+  forwardTool(
+    "docs_create_folder",
+    {
+      name: z.z.string().describe("Folder name."),
+      parentId: z.z.string().optional().describe("Parent folder node id (defaults to root).")
+    },
+    "Docs Create Folder",
+    "Create a folder node in the Documentation Library."
+  );
+  forwardTool(
+    "docs_create_doc",
+    {
+      name: z.z.string().describe("Doc name (e.g. Design.md)."),
+      parentId: z.z.string().optional().describe("Parent folder node id (defaults to root)."),
+      bodyMarkdown: z.z.string().optional().describe("Markdown body."),
+      metadata: z.z.record(z.z.any()).optional().describe("Metadata object (JSON).")
+    },
+    "Docs Create Doc",
+    "Create a document node in the Documentation Library."
+  );
+  forwardTool(
+    "docs_claim",
+    {
+      nodeId: z.z.string().describe("Document node id."),
+      leaseMs: z.z.number().int().positive().optional().describe("Lease TTL (ms).")
+    },
+    "Docs Claim",
+    "Claim a documentation document for editing (exclusive lease)."
+  );
+  forwardTool(
+    "docs_release",
+    {
+      nodeId: z.z.string().describe("Document node id.")
+    },
+    "Docs Release",
+    "Release a documentation document lease."
+  );
+  forwardTool(
+    "docs_update",
+    {
+      nodeId: z.z.string().describe("Document node id."),
+      name: z.z.string().optional().describe("Optional new name (rename; index.md cannot be renamed)."),
+      bodyMarkdown: z.z.string().optional().describe("Markdown body."),
+      metadata: z.z.record(z.z.any()).optional().describe("Metadata object (JSON)."),
+      expectedBodyVersion: z.z.number().int().nonnegative().optional().describe("Optional optimistic concurrency check.")
+    },
+    "Docs Update",
+    "Update a documentation document. Claims the lease automatically if required."
+  );
+  forwardTool(
+    "docs_delete",
+    {
+      nodeId: z.z.string().describe("Node id (folder or document).")
+    },
+    "Docs Delete",
+    "Delete a documentation node (folders must be empty; deleting docs requires active lease; index.md cannot be deleted)."
+  );
+  forwardTool(
+    "docs_import",
+    {
+      entries: z.z.array(
+        z.z.object({
+          path: z.z.string().describe("Relative path (within the imported folder)."),
+          bodyMarkdown: z.z.string().describe("Markdown content.")
+        })
+      ).describe("Markdown entries to import.")
+    },
+    "Docs Import",
+    "Import markdown files into the Documentation Library (copy into backend DB)."
+  );
+  forwardTool(
+    "unreal_latest_screenshots",
+    {
+      uprojectPath: z.z.string().describe("Absolute path to the .uproject file."),
+      limit: z.z.number().int().positive().optional().describe("Max number of screenshots to return (default 12)."),
+      includeBase64: z.z.boolean().optional().describe("Include base64 image data in the payload (default false)."),
+      maxBytesPerImage: z.z.number().int().positive().optional().describe("Max bytes per image when includeBase64=true (default 2500000).")
+    },
+    "Latest Unreal Screenshots",
+    "Fetch the latest PNG screenshots from Saved/Screenshots/Flockbay and return views for the UI to display."
+  );
+  forwardTool(
+    "unreal_mcp_command",
+    {
+      type: z.z.string().describe('UnrealMCP command type (e.g. "get_actors_in_level", "spawn_actor").'),
+      params: z.z.record(z.z.any()).optional().describe("Optional params object for the command."),
+      timeoutMs: z.z.number().int().positive().optional().describe("Socket timeout in ms (default 5000).")
+    },
+    "Unreal Editor Command (UnrealMCP)",
+    "Send a single UnrealMCP command to the running Unreal Editor (engine plugin) and return the JSON response."
+  );
+  forwardTool(
+    "unreal_mcp_get_actors_in_level",
+    {
+      timeoutMs: z.z.number().int().positive().optional().describe("Socket timeout in ms (default 5000).")
+    },
+    "Unreal Actors In Level (UnrealMCP)",
+    "List all actors in the current Unreal Editor level via the UnrealMCP engine plugin."
+  );
+  forwardTool(
+    "unreal_mcp_get_play_in_editor_status",
+    {
+      timeoutMs: z.z.number().int().positive().optional().describe("Socket timeout in ms (default 5000).")
+    },
+    "Unreal Play Status (PIE)",
+    "Get Play-In-Editor status from the UnrealMCP engine plugin."
+  );
+  forwardTool(
+    "unreal_mcp_editor_health",
+    {
+      timeoutMs: z.z.number().int().positive().optional().describe("Socket timeout in ms (default 1500).")
+    },
+    "Unreal Editor Health (UnrealMCP)",
+    "Best-effort health check for Unreal Editor + UnrealMCP (detects if the editor is reachable)."
+  );
+  forwardTool(
+    "unreal_mcp_play_in_editor",
+    {
+      timeoutMs: z.z.number().int().positive().optional().describe("Socket timeout in ms (default 5000).")
+    },
+    "Unreal Play In Editor (Viewport)",
+    "Start Play-In-Editor (PIE) in the active editor viewport via the UnrealMCP engine plugin."
+  );
+  forwardTool(
+    "unreal_mcp_play_in_editor_windowed",
+    {
+      timeoutMs: z.z.number().int().positive().optional().describe("Socket timeout in ms (default 5000).")
+    },
+    "Unreal Play In Editor (New Window)",
+    "Start Play-In-Editor (PIE) in a new editor window via the UnrealMCP engine plugin."
+  );
+  forwardTool(
+    "unreal_mcp_stop_play_in_editor",
+    {
+      timeoutMs: z.z.number().int().positive().optional().describe("Socket timeout in ms (default 5000).")
+    },
+    "Unreal Stop Play In Editor",
+    "Stop a running Play-In-Editor session via the UnrealMCP engine plugin."
+  );
+  forwardTool(
+    "unreal_mechanic_run",
+    {
+      uprojectPath: z.z.string().describe("Absolute path to the .uproject file."),
+      engineRoot: z.z.string().optional().describe(
+        "Unreal Engine install root (e.g. /Users/Shared/Epic Games/UE_5.7). Defaults to UE_ENGINE_ROOT / ENGINE_ROOT env vars."
+      ),
+      slug: z.z.string().optional().describe("Optional slug used for naming the test map (default: dash)."),
+      prompt: z.z.string().optional().describe("Optional prompt string to record in the receipt."),
+      cooldownSeconds: z.z.number().optional().describe("Dash cooldown seconds (default 1.0)."),
+      staminaCost: z.z.number().optional().describe("Dash stamina cost (default 20.0)."),
+      dashStrength: z.z.number().optional().describe("Dash horizontal strength (default 1200.0)."),
+      dashUpwardStrength: z.z.number().optional().describe("Dash upward strength (default 0.0).")
+    },
+    "Unreal Mechanic Builder (Dash MVP)",
+    "Create a project-safe mechanic test map (Parallel mode) and prove it works with Flockbay screenshot evidence. V1 supports dash only."
+  );
+  const stdio = new stdio_js.StdioServerTransport();
+  await server.connect(stdio);
+}
+main().catch((err) => {
+  try {
+    process.stderr.write(`[flockbay-mcp] Fatal: ${err instanceof Error ? err.message : String(err)}
+`);
+  } finally {
+    process.exit(1);
+  }
+});

package/dist/codex/flockbayMcpStdioBridge.d.cts

@@ -0,0 +1,2 @@
+
+export { };

package/dist/codex/flockbayMcpStdioBridge.d.mts

@@ -0,0 +1,2 @@
+
+export { };