droid-mode 0.0.1

package/templates/skills/droid-mode/bin/dm

@@ -0,0 +1,424 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+
+import { parseArgs, printTable } from "../lib/util.mjs";
+import { loadMcpConfigs, resolveServer, summarizeServerForDisplay, listAllServers } from "../lib/config.mjs";
+import { McpClient } from "../lib/mcp_client.mjs";
+import { getToolsCached, compactToolSummaries } from "../lib/tool_index.mjs";
+import { searchTools } from "../lib/search.mjs";
+import { hydrateTools } from "../lib/hydrate.mjs";
+import { createToolApi, executeWorkflow, writeRunArtifact } from "../lib/run.mjs";
+
+function usage() {
+  return `
+Droid Mode (dm) — Progressive Code‑Mode MCP workflows for Factory Droid
+
+Usage:
+  dm servers [--json]
+  dm doctor  --server <name> [--no-connect] [--json]
+  dm index   --server <name> [--refresh] [--json]
+  dm search  "<query>" --server <name> [--limit 8] [--refresh] [--json]
+  dm hydrate <tool1> <tool2> ... --server <name> [--out <dir>] [--refresh] [--json]
+  dm run     --workflow <file.js> --tools <a,b,...> --server <name> [--retries 3] [--timeout-ms 300000] [--json]
+  dm call    <tool> --server <name> [--args-json '{...}'] [--args-file path.json] [--json]
+
+Progressive Disclosure Flow:
+  1. dm servers              → Discover available MCP servers
+  2. dm index --server X     → List tools on server X
+  3. dm search "..." --server X → Find relevant tools
+  4. dm hydrate tool1 --server X → Get full schemas
+  5. dm run --server X ...   → Execute workflow
+
+Manual connection overrides (optional):
+  --http-url <url> [--headers-json '{"Authorization":"Bearer ..."}']
+  --stdio-command <cmd> [--stdio-args "a,b,c"] [--env-json '{"KEY":"VALUE"}']
+
+Notes:
+- Servers with 'disabled: true' in mcp.json are fully available here.
+  That flag only prevents Droid from loading tools into context.
+- Tool inventory is cached under .factory/droid-mode/cache/<server>/tools.json
+`.trim();
+}
+
+function fail(msg, code = 1) {
+  process.stderr.write(String(msg).trim() + "\n");
+  process.exit(code);
+}
+
+/**
+ * Resolve server entry from explicit flags OR from mcp.json.
+ * @param {Record<string, any>} flags
+ */
+function resolveServerFromFlags(flags) {
+  // HTTP override
+  if (flags["http-url"]) {
+    const url = String(flags["http-url"]);
+    let headers = {};
+    if (flags["headers-json"]) {
+      try {
+        headers = JSON.parse(String(flags["headers-json"]));
+      } catch (err) {
+        throw new Error(`Invalid --headers-json: ${err.message || err}`);
+      }
+    }
+    return { serverName: flags.server ? String(flags.server) : "http", entry: { type: "http", url, headers } };
+  }
+
+  // stdio override
+  if (flags["stdio-command"]) {
+    const command = String(flags["stdio-command"]);
+    const args = flags["stdio-args"]
+      ? String(flags["stdio-args"])
+          .split(",")
+          .map((s) => s.trim())
+          .filter(Boolean)
+      : [];
+    let env = {};
+    if (flags["env-json"]) {
+      try {
+        env = JSON.parse(String(flags["env-json"]));
+      } catch (err) {
+        throw new Error(`Invalid --env-json: ${err.message || err}`);
+      }
+    }
+    return { serverName: flags.server ? String(flags.server) : "stdio", entry: { type: "stdio", command, args, env } };
+  }
+
+  // Default: mcp.json
+  const resolved = resolveServer({ server: flags.server });
+  return { serverName: resolved.serverName, entry: resolved.entry };
+}
+
+async function withClient(serverName, entry, fn) {
+  const client = new McpClient({ serverName, entry });
+  try {
+    return await fn(client);
+  } finally {
+    try {
+      await client.close();
+    } catch {}
+  }
+}
+
+async function cmdServers(args) {
+  const servers = listAllServers();
+
+  if (args.flags.json) {
+    process.stdout.write(JSON.stringify({ servers }, null, 2) + "\n");
+    return;
+  }
+
+  if (!servers.length) {
+    process.stdout.write("No MCP servers configured.\n");
+    process.stdout.write("Add servers via `droid mcp add` or create ~/.factory/mcp.json\n");
+    return;
+  }
+
+  printTable(
+    servers.map((s) => ({
+      name: s.name,
+      type: s.type,
+      "droid-context": s.disabledInDroid ? "disabled (good!)" : "enabled",
+    })),
+    ["name", "type", "droid-context"]
+  );
+
+  process.stdout.write(`\n${servers.length} MCP server(s) available to droid-mode.\n`);
+  process.stdout.write(`Tip: "disabled" servers won't bloat Droid's context - that's the point!\n`);
+}
+
+async function cmdDoctor(args) {
+  const { projectPath, userPath } = loadMcpConfigs();
+
+  let serverName, entry;
+  try {
+    ({ serverName, entry } = resolveServerFromFlags(args.flags));
+  } catch (err) {
+    fail(err.message || err);
+  }
+
+  const summary = summarizeServerForDisplay(entry);
+
+  if (args.flags.json) {
+    const out = {
+      projectMcpPath: projectPath,
+      userMcpPath: userPath,
+      serverName,
+      server: summary,
+    };
+    if (args.flags["no-connect"]) {
+      process.stdout.write(JSON.stringify(out, null, 2) + "\n");
+      return;
+    }
+    const res = await withClient(serverName, entry, async (client) => {
+      await client.init();
+      const tools = await client.listTools();
+      return {
+        toolCount: Array.isArray(tools?.tools) ? tools.tools.length : 0,
+        protocolVersion: client.negotiatedProtocolVersion,
+        serverInfo: client.serverInfo,
+      };
+    });
+    out.connection = res;
+    process.stdout.write(JSON.stringify(out, null, 2) + "\n");
+    return;
+  }
+
+  process.stdout.write(`Project mcp.json: ${projectPath || "(not found)"}\n`);
+  process.stdout.write(`User mcp.json:    ${userPath}\n`);
+  process.stdout.write(`Server: ${serverName}\n`);
+  process.stdout.write(`Config: ${JSON.stringify(summary, null, 2)}\n`);
+
+  if (!args.flags["no-connect"]) {
+    process.stdout.write(`\nConnecting...\n`);
+    const res = await withClient(serverName, entry, async (client) => {
+      await client.init();
+      const list = await client.listTools();
+      return {
+        toolCount: Array.isArray(list?.tools) ? list.tools.length : 0,
+        protocolVersion: client.negotiatedProtocolVersion,
+        serverInfo: client.serverInfo,
+      };
+    });
+    process.stdout.write(`Connected. Tools: ${res.toolCount}\n`);
+    process.stdout.write(`Protocol: ${res.protocolVersion}\n`);
+    if (res.serverInfo) process.stdout.write(`ServerInfo: ${JSON.stringify(res.serverInfo)}\n`);
+  }
+}
+
+async function cmdIndex(args) {
+  let serverName, entry;
+  try {
+    ({ serverName, entry } = resolveServerFromFlags(args.flags));
+  } catch (err) {
+    fail(err.message || err);
+  }
+
+  const refresh = !!args.flags.refresh;
+
+  const res = await withClient(serverName, entry, async (client) => {
+    const { tools, cacheFile, cached } = await getToolsCached({ serverName, client, refresh });
+    const summaries = compactToolSummaries(tools);
+    return { summaries, cacheFile, cached };
+  });
+
+  if (args.flags.json) {
+    process.stdout.write(
+      JSON.stringify({ serverName, cacheFile: res.cacheFile, cached: res.cached, tools: res.summaries }, null, 2) + "\n"
+    );
+    return;
+  }
+
+  printTable(
+    res.summaries.map((t) => ({ 
+      name: t.name, 
+      requires: t.requires || "-",
+      description: t.description.slice(0, 80) 
+    })),
+    ["name", "requires", "description"]
+  );
+  process.stdout.write(`Cache: ${res.cacheFile} (${res.cached ? "hit" : "refreshed"})\n`);
+}
+
+async function cmdSearch(args) {
+  const query = args._[1];
+  if (!query) fail(`Missing query.\n\n${usage()}`);
+
+  let serverName, entry;
+  try {
+    ({ serverName, entry } = resolveServerFromFlags(args.flags));
+  } catch (err) {
+    fail(err.message || err);
+  }
+
+  const refresh = !!args.flags.refresh;
+  const limit = args.flags.limit ? Number(args.flags.limit) : 8;
+
+  const res = await withClient(serverName, entry, async (client) => {
+    const { tools } = await getToolsCached({ serverName, client, refresh });
+    const matches = searchTools(tools, query, { limit });
+    return { matches };
+  });
+
+  if (args.flags.json) {
+    process.stdout.write(JSON.stringify({ serverName, query, matches: res.matches }, null, 2) + "\n");
+    return;
+  }
+
+  printTable(
+    res.matches.map((m) => ({ name: m.name, score: m.score.toFixed(2), description: m.description.slice(0, 140) })),
+    ["name", "score", "description"]
+  );
+}
+
+async function cmdHydrate(args) {
+  const toolNames = args._.slice(1);
+  if (!toolNames.length) fail(`Missing tool names.\n\n${usage()}`);
+
+  let serverName, entry;
+  try {
+    ({ serverName, entry } = resolveServerFromFlags(args.flags));
+  } catch (err) {
+    fail(err.message || err);
+  }
+
+  const refresh = !!args.flags.refresh;
+  const outDir = args.flags.out ? String(args.flags.out) : undefined;
+
+  const res = await withClient(serverName, entry, async (client) => {
+    const { tools } = await getToolsCached({ serverName, client, refresh });
+    // const { outDir, selectedCount, toolmap } = hydrateTools({ serverName, tools, toolNames, outDir });
+    // return { outDir, selectedCount, toolmap };
+    return hydrateTools({ serverName, tools, toolNames, outDir });
+
+  });
+
+  if (args.flags.json) {
+    process.stdout.write(
+      JSON.stringify({ serverName, outDir: res.outDir, selectedCount: res.selectedCount, toolmap: res.toolmap }, null, 2) +
+        "\n"
+    );
+    return;
+  }
+
+  process.stdout.write(`Hydrated ${res.selectedCount} tools to:\n  ${res.outDir}\n`);
+}
+
+async function cmdRun(args) {
+  const workflowPath = args.flags.workflow || args.flags.w;
+  const toolsCsv = args.flags.tools || args.flags.t;
+  if (!workflowPath || !toolsCsv) fail(`Missing --workflow and/or --tools.\n\n${usage()}`);
+
+  const toolNames = String(toolsCsv)
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean);
+
+  if (!fs.existsSync(workflowPath)) fail(`Workflow file not found: ${workflowPath}`);
+
+  let serverName, entry;
+  try {
+    ({ serverName, entry } = resolveServerFromFlags(args.flags));
+  } catch (err) {
+    fail(err.message || err);
+  }
+
+  const refresh = !!args.flags.refresh;
+  const timeoutMs = args.flags["timeout-ms"] ? Number(args.flags["timeout-ms"]) : undefined;
+  const allowUnsafe = !!args.flags["allow-unsafe"];
+  const maxRetries = args.flags.retries ? Number(args.flags.retries) : 3;
+
+  const trace = [];
+
+  const output = await withClient(serverName, entry, async (client) => {
+    // Ensure tools exist (via cache)
+    const { tools } = await getToolsCached({ serverName, client, refresh });
+    const available = new Set((tools || []).map((t) => t?.name));
+    const missing = toolNames.filter((n) => !available.has(n));
+    if (missing.length) {
+      throw new Error(`Unknown tool(s) for server "${serverName}": ${missing.join(", ")}`);
+    }
+
+    const toolApi = createToolApi({ client, toolNames, trace, maxRetries });
+    const { result, logs } = await executeWorkflow({
+      workflowPath,
+      toolApi,
+      timeoutMs,
+      allowUnsafe,
+    });
+    return { result, logs, toolmap: toolApi.toolmap };
+  }).catch((err) => {
+    // Persist a failure run artifact too.
+    const failOut = {
+      ok: false,
+      error: String(err?.message || err),
+    };
+    const artifact = writeRunArtifact({
+      serverName,
+      workflowPath,
+      tools: toolNames,
+      output: failOut,
+      trace,
+    });
+    if (args.flags.json) {
+      process.stdout.write(JSON.stringify({ ...failOut, artifact }, null, 2) + "\n");
+      return;
+    }
+    fail(`${failOut.error}\nArtifact: ${artifact.file}`);
+  });
+
+  const okOut = { ok: true, result: output.result, logs: output.logs, toolmap: output.toolmap };
+  const artifact = writeRunArtifact({
+    serverName,
+    workflowPath,
+    tools: toolNames,
+    output: okOut,
+    trace,
+  });
+
+  process.stdout.write(JSON.stringify({ ...okOut, artifact }, null, 2) + "\n");
+}
+
+async function cmdCall(args) {
+  const tool = args._[1];
+  if (!tool) fail(`Missing tool name.\n\n${usage()}`);
+
+  let serverName, entry;
+  try {
+    ({ serverName, entry } = resolveServerFromFlags(args.flags));
+  } catch (err) {
+    fail(err.message || err);
+  }
+
+  let argObj = {};
+  if (args.flags["args-json"]) {
+    try {
+      argObj = JSON.parse(String(args.flags["args-json"]));
+    } catch (err) {
+      fail(`Invalid --args-json: ${err.message || err}`);
+    }
+  } else if (args.flags["args-file"]) {
+    const p = String(args.flags["args-file"]);
+    try {
+      argObj = JSON.parse(fs.readFileSync(p, "utf-8"));
+    } catch (err) {
+      fail(`Invalid --args-file: ${err.message || err}`);
+    }
+  }
+
+  const out = await withClient(serverName, entry, async (client) => {
+    const res = await client.callTool({ name: tool, arguments: argObj, timeoutMs: 60_000 });
+    return res;
+  });
+
+  if (args.flags.json) {
+    process.stdout.write(JSON.stringify(out, null, 2) + "\n");
+    return;
+  }
+  process.stdout.write(JSON.stringify(out.structured ?? out.text ?? out.raw, null, 2) + "\n");
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const cmd = args._[0];
+
+  if (!cmd || cmd === "help" || cmd === "--help" || cmd === "-h") {
+    process.stdout.write(usage() + "\n");
+    return;
+  }
+
+  try {
+    if (cmd === "servers") return await cmdServers(args);
+    if (cmd === "doctor") return await cmdDoctor(args);
+    if (cmd === "index") return await cmdIndex(args);
+    if (cmd === "search") return await cmdSearch(args);
+    if (cmd === "hydrate") return await cmdHydrate(args);
+    if (cmd === "run") return await cmdRun(args);
+    if (cmd === "call") return await cmdCall(args);
+    fail(`Unknown command: ${cmd}\n\n${usage()}`);
+  } catch (err) {
+    fail(err.message || err);
+  }
+}
+
+main();

package/templates/skills/droid-mode/examples/hooks/README.md

@@ -0,0 +1,13 @@
+# Hooks (optional)
+
+Droid Mode is intentionally implemented as a **Skill-first** integration.
+
+If you want to enforce a policy such as:
+
+- “Do not call raw `mcp__*` tools directly; use `droid-mode` scripts instead”
+
+…you can add a **PreToolUse** hook and gate decisions there.
+
+Implementation details (hook payload format and the expected allow/deny response) can vary by Droid version, so treat any hook you write as **policy code** that should be validated in your environment.
+
+Reference: Factory Hooks documentation.

package/templates/skills/droid-mode/examples/workflows/workflow.example.js

@@ -0,0 +1,21 @@
+// Example Droid Mode workflow
+// This file is executed inside the droid-mode sandbox.
+// You have access to:
+//   - t.<safeToolName>(args): calls hydrated tools via MCP
+//   - tools.call(toolName, args): call by raw tool name
+//   - log(...args): writes to run logs
+//
+// Requirement: set `workflow = async () => { ... }`
+
+workflow = async () => {
+  log("Starting example workflow...");
+
+  // Replace tool names below with tools that exist on your MCP server.
+  // Example pattern (for a server that has search + get tools):
+  //
+  // const hits = await t.searchDocuments({ query: "Droid Mode", limit: 3 });
+  // const docs = await Promise.all(hits.results.map(h => t.getDocument({ id: h.id })));
+  // return { hitCount: hits.results.length, ids: docs.map(d => d.id) };
+
+  return { ok: true, note: "Edit examples/workflows/workflow.example.js to match your MCP tools." };
+};

package/templates/skills/droid-mode/lib/config.mjs

@@ -0,0 +1,135 @@
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { findProjectRoot, readJsonFileIfExists, redactEnvForDisplay } from "./util.mjs";
+
+/**
+ * Read project and user mcp.json, merge according to Factory's layering rules:
+ * - user servers override project servers with the same name
+ * @returns {{
+ *   projectPath: string|null,
+ *   userPath: string,
+ *   project: any|null,
+ *   user: any|null,
+ *   mergedServers: Record<string, any>
+ * }}
+ */
+export function loadMcpConfigs() {
+  const projectRoot = findProjectRoot();
+  const projectPath = projectRoot ? path.join(projectRoot, ".factory", "mcp.json") : null;
+  const userPath = path.join(os.homedir(), ".factory", "mcp.json");
+
+  const project = projectPath ? readJsonFileIfExists(projectPath) : null;
+  const user = readJsonFileIfExists(userPath);
+
+  const projectServers = (project && project.mcpServers) || {};
+  const userServers = (user && user.mcpServers) || {};
+
+  const merged = { ...projectServers, ...userServers };
+  return { projectPath, userPath, project, user, mergedServers: merged };
+}
+
+/**
+ * List all MCP servers available to droid-mode.
+ * Ignores 'disabled' flag - that's for Droid context injection, not skill access.
+ * @returns {Array<{name: string, type: string, disabledInDroid: boolean}>}
+ */
+export function listAllServers() {
+  const { mergedServers } = loadMcpConfigs();
+  return Object.entries(mergedServers || {}).map(([name, entry]) => ({
+    name,
+    type: entry?.type || "unknown",
+    disabledInDroid: !!entry?.disabled,
+  }));
+}
+
+/**
+ * Resolve an MCP server entry by name.
+ * Note: We ignore the 'disabled' flag - it controls Droid context injection, not skill access.
+ * @param {string} name
+ */
+export function getServerByName(name) {
+  const { mergedServers } = loadMcpConfigs();
+  const entry = mergedServers[name];
+  if (!entry) return null;
+  return entry;
+}
+
+/**
+ * Choose a default server name given mergedServers.
+ * Only auto-selects if there's exactly one server. Otherwise requires explicit --server.
+ * Note: We ignore 'disabled' flag - it controls Droid context injection, not skill access.
+ * @param {Record<string, any>} mergedServers
+ */
+export function chooseDefaultServerName(mergedServers) {
+  const names = Object.keys(mergedServers || {});
+  if (!names.length) return null;
+  if (names.length === 1) return names[0];
+  return null; // Multiple servers: require explicit --server
+}
+
+/**
+ * Resolve which server to use from CLI flags and mcp.json.
+ * Note: We ignore the 'disabled' flag - it controls Droid context injection, not skill access.
+ * @param {{ server?: string }} opts
+ * @returns {{ serverName: string, entry: any, allNames: string[] }}
+ */
+export function resolveServer(opts = {}) {
+  const { mergedServers } = loadMcpConfigs();
+  const allNames = Object.keys(mergedServers || {});
+
+  const name = opts.server || chooseDefaultServerName(mergedServers);
+
+  if (!name) {
+    if (!allNames.length) {
+      throw new Error(
+        `No MCP servers configured.\n` +
+        `Add servers via \`droid mcp add\` or create ~/.factory/mcp.json`
+      );
+    }
+    throw new Error(
+      `Multiple MCP servers available. Use --server <name> to select one.\n` +
+      `Run \`dm servers\` to see available servers.`
+    );
+  }
+
+  const entry = mergedServers[name];
+  if (!entry) {
+    throw new Error(
+      `MCP server "${name}" not found.\n` +
+      `Run \`dm servers\` to see available servers.`
+    );
+  }
+
+  // Note: We intentionally ignore entry.disabled here.
+  // That flag controls Droid context injection, not droid-mode skill access.
+
+  return { serverName: name, entry, allNames };
+}
+
+/**
+ * Return a safe-for-display summary of a server entry (redacts env/header secrets).
+ * @param {any} entry
+ */
+export function summarizeServerForDisplay(entry) {
+  const type = entry?.type;
+  if (type === "http") {
+    const headers = entry?.headers || {};
+    const redacted = {};
+    for (const [k, v] of Object.entries(headers)) {
+      const isSecret = /(authorization|token|key|secret|password)/i.test(k);
+      redacted[k] = isSecret ? "***" : String(v);
+    }
+    return { type, url: entry?.url, headers: redacted, disabled: !!entry?.disabled };
+  }
+  if (type === "stdio") {
+    return {
+      type,
+      command: entry?.command,
+      args: entry?.args || [],
+      env: redactEnvForDisplay(entry?.env || {}),
+      disabled: !!entry?.disabled,
+    };
+  }
+  return { type: type || "unknown", disabled: !!entry?.disabled };
+}