@kodiak-finance/orderly-devkit 1.0.2

package/src/commands/login.js

@@ -0,0 +1,147 @@
+const crypto = require("crypto");
+const { exec } = require("child_process");
+const { heading, info, success, warn, error } = require("../shared");
+const { saveOAuthToken, isLoggedIn } = require("../internal/auth");
+const { startCallbackServer } = require("../internal/login-server");
+const {
+  CLI_CALLBACK_PORT,
+  CLI_LOGIN_TIMEOUT_MS,
+  MARKETPLACE_WEB_LOGIN_URL,
+} = require("../internal/constants");
+
+function openBrowser(url) {
+  const platform = process.platform;
+  let command;
+  if (platform === "darwin") {
+    command = `open "${url}"`;
+  } else if (platform === "win32") {
+    command = `start "" "${url}"`;
+  } else {
+    command = `xdg-open "${url}"`;
+  }
+  return new Promise((resolve, reject) => {
+    exec(command, (err) => {
+      if (err) reject(err);
+      else resolve();
+    });
+  });
+}
+
+module.exports = {
+  command: "login",
+  describe: "Login to Orderly Marketplace via GitHub",
+  builder: (yargs) => {
+    return yargs
+      .option("port", {
+        alias: "p",
+        type: "number",
+        describe:
+          "number; local callback server port used for the OAuth redirect (must be available). Default is the CLI_CALLBACK_PORT constant",
+        default: CLI_CALLBACK_PORT,
+      })
+      .option("force", {
+        alias: "f",
+        type: "boolean",
+        describe:
+          "boolean; if true, force re-login even if you're already logged in",
+        default: false,
+      })
+      .example("orderly login", "Open the browser and complete GitHub OAuth")
+      .example(
+        "orderly login --force --port 9877",
+        "Re-authenticate and use a custom callback port",
+      );
+  },
+  handler: async (argv) => {
+    heading("Login to Orderly Marketplace");
+    info("This will open your browser to authenticate via GitHub.\n");
+
+    if (isLoggedIn() && !argv.force) {
+      warn("You are already logged in.");
+      info("Use 'orderly login --force' to re-authenticate.");
+      return;
+    }
+
+    // Generate CSRF state
+    const state = crypto.randomBytes(16).toString("hex");
+    const port = argv.port;
+    const browserUrl = `${MARKETPLACE_WEB_LOGIN_URL}?port=${port}&state=${state}`;
+
+    // Start local callback server
+    const { server, waitForToken } = startCallbackServer({ port, state });
+
+    // Handle server errors (e.g. port in use)
+    const serverReady = new Promise((resolve, reject) => {
+      server.on("error", (err) => {
+        if (err.code === "EADDRINUSE") {
+          reject(
+            new Error(
+              `Port ${port} is already in use. Use --port to specify a different port.`,
+            ),
+          );
+        } else {
+          reject(err);
+        }
+      });
+      server.on("listening", resolve);
+    });
+
+    try {
+      server.listen(port);
+      await serverReady;
+    } catch (err) {
+      error(err.message);
+      server.close();
+      return;
+    }
+
+    // Open browser
+    info("Opening browser...");
+    info(`  ${browserUrl}\n`);
+    try {
+      await openBrowser(browserUrl);
+    } catch (e) {
+      info("Could not open browser automatically.");
+      info("Please open the URL above in your browser manually.\n");
+    }
+
+    info("Waiting for authentication...");
+
+    // Timeout
+    let timedOut = false;
+    const timeout = setTimeout(() => {
+      timedOut = true;
+      error("Login timed out after 3 minutes.");
+    }, CLI_LOGIN_TIMEOUT_MS);
+
+    // Handle Ctrl+C during login
+    const onSigInt = () => {
+      info("\nLogin cancelled.");
+      clearTimeout(timeout);
+      server.close();
+      process.exit(1);
+    };
+    process.on("SIGINT", onSigInt);
+
+    try {
+      const tokenData = await waitForToken;
+      clearTimeout(timeout);
+      process.removeListener("SIGINT", onSigInt);
+
+      saveOAuthToken(tokenData);
+
+      success("Login successful!");
+      const displayName = tokenData.email || tokenData.username;
+      if (displayName) {
+        info(`Logged in as: ${displayName}`);
+      }
+      info("Use 'orderly-devkit whoami' to verify your account.");
+    } catch (err) {
+      if (!timedOut) {
+        error(`Login failed: ${err.message}`);
+      }
+    } finally {
+      server.close();
+    }
+  },
+};

package/src/commands/logout.js

@@ -0,0 +1,22 @@
+const { heading, info, success, warn } = require("../shared");
+const { isLoggedIn, logout } = require("../internal/auth");
+
+module.exports = {
+  command: "logout",
+  describe: "Logout from Orderly Marketplace",
+  handler: async () => {
+    heading("Logout from Orderly Marketplace");
+
+    if (!isLoggedIn()) {
+      warn("You are not logged in.");
+      return;
+    }
+
+    info("This command will clear your stored authentication.\n");
+
+    logout();
+
+    success("Logout successful!");
+    console.log("Your session has been cleared.");
+  },
+};

package/src/commands/mcp/detect.js

@@ -0,0 +1,128 @@
+const chalk = require("chalk");
+const { heading, info, dim } = require("../../shared");
+const {
+  ALL_CLIENTS,
+  getOrderlySdkDocsMcpReport,
+} = require("../../internal/orderlySdkDocsMcpDetect");
+
+/**
+ * @param {string} clientArg
+ * @returns {string[]}
+ */
+function parseClients(clientArg) {
+  const raw = String(clientArg || "all").trim();
+  if (raw === "all") {
+    return [...ALL_CLIENTS];
+  }
+  const parts = raw
+    .split(",")
+    .map((x) => x.trim())
+    .filter(Boolean);
+  for (const p of parts) {
+    if (!ALL_CLIENTS.includes(p)) {
+      throw new Error(
+        `Invalid --client value: ${p}. Use: ${ALL_CLIENTS.join(", ")}, or all (comma-separated).`,
+      );
+    }
+  }
+  return parts;
+}
+
+/**
+ * @param {{ cwd: string; defaultServerName: string; clients: Record<string, { user: { configured: boolean }; project: { configured: boolean } }> }} report
+ */
+function printHumanReport(report) {
+  heading("Orderly SDK Docs MCP — detect");
+  info(`Working directory: ${report.cwd}`);
+  info(`Default server name: ${report.defaultServerName}\n`);
+
+  for (const client of Object.keys(report.clients)) {
+    const row = report.clients[client];
+    console.log(chalk.bold.cyan(client));
+    for (const scope of /** @type {const} */ (["user", "project"])) {
+      const cell = row[scope];
+      const scopeLabel = scope === "user" ? "user" : "proj";
+      const pathLine = chalk.dim(cell.configPath);
+      if (cell.error) {
+        console.log(
+          `  [${scopeLabel}] ${chalk.red("invalid JSON")} — ${cell.error}`,
+        );
+        console.log(` ${pathLine}`);
+        continue;
+      }
+      if (!cell.exists) {
+        console.log(`  [${scopeLabel}] ${chalk.yellow("no file")}`);
+        console.log(`         ${pathLine}`);
+        continue;
+      }
+      if (cell.configured) {
+        const key = cell.serverKey ? ` (${cell.serverKey})` : "";
+        console.log(`  [${scopeLabel}] ${chalk.green("configured")}${key}`);
+      } else {
+        console.log(`  [${scopeLabel}] ${chalk.yellow("not detected")}`);
+      }
+      console.log(`         ${pathLine}`);
+    }
+    console.log();
+  }
+
+  const anyConfigured = Object.values(report.clients).some(
+    (row) => row.user.configured || row.project.configured,
+  );
+  if (!anyConfigured) {
+    dim("Orderly SDK Docs MCP was not found in any checked config.");
+    info("Install MCP for your agent(s):");
+    info("  orderly-devkit mcp install");
+    info("  orderly-devkit mcp install --client cursor --scope project");
+    info("Install plugin workflow skills for your coding agent:");
+    info("  orderly-devkit skills install");
+  }
+}
+
+module.exports = {
+  command: "detect",
+  describe:
+    "Detect whether Orderly SDK Docs MCP is present in agent config files (user + project scope)",
+  builder: (yargs) => {
+    return yargs
+      .option("client", {
+        type: "string",
+        describe:
+          "claude|codex|cursor|opencode|all, or comma-separated list (default: all)",
+        default: "all",
+      })
+      .option("json", {
+        type: "boolean",
+        default: false,
+        describe: "Print machine-readable JSON to stdout",
+      })
+      .example(
+        "orderly-devkit mcp detect",
+        "Scan all supported agents (user + project configs for cwd)",
+      )
+      .example(
+        "orderly-devkit mcp detect --client cursor",
+        "Only inspect Cursor mcp.json paths",
+      )
+      .example("orderly-devkit mcp detect --json", "JSON report for scripting");
+  },
+  handler: async (argv) => {
+    let clients;
+    try {
+      clients = parseClients(argv.client);
+    } catch (e) {
+      console.error(chalk.red(e instanceof Error ? e.message : String(e)));
+      process.exitCode = 1;
+      return;
+    }
+
+    const report = getOrderlySdkDocsMcpReport(process.cwd(), { clients });
+
+    if (argv.json) {
+      console.log(JSON.stringify(report, null, 2));
+      return;
+    }
+
+    printHumanReport(report);
+  },
+};

package/src/commands/mcp/install.js

@@ -0,0 +1,122 @@
+const { spawnSync } = require("child_process");
+const chalk = require("chalk");
+
+/** stderr-only; set ORDERLY_MCP_INSTALL_DEBUG=1 to trace spawn failures / hangs */
+function debugMcpInstall(...parts) {
+  if (
+    process.env.ORDERLY_MCP_INSTALL_DEBUG !== "1" &&
+    process.env.ORDERLY_MCP_INSTALL_DEBUG !== "true"
+  ) {
+    return;
+  }
+  console.error(chalk.dim("[orderly-devkit mcp install:debug]"), ...parts);
+}
+
+/**
+ * Forward MCP install to sdk-docs so install ownership stays centralized.
+ * Uses an explicit bin invocation to avoid npx argument parsing ambiguity
+ * across npm versions and caches.
+ */
+function forwardToSdkDocs(argv) {
+  console.log(
+    chalk.cyan("orderly-devkit:") +
+      " Installing Orderly SDK Docs MCP config via npx…",
+  );
+  console.log(
+    chalk.dim("First run may download @orderly.network/sdk-docs; please wait."),
+  );
+
+  /** Pinned package spec for npx -y <spec> … (must match sdk-docs install merge). */
+  const rawSdkVer = argv.sdkDocsVersion ?? argv["sdk-docs-version"];
+  const ver =
+    rawSdkVer && String(rawSdkVer).trim() ? String(rawSdkVer).trim() : "";
+  const pkgSpec = ver
+    ? `@orderly.network/sdk-docs@${ver}`
+    : "@orderly.network/sdk-docs";
+  if (ver) {
+    console.log(chalk.dim(`Using package: ${pkgSpec}`));
+  }
+
+  const command = "npx";
+  const args = ["-y", pkgSpec, "orderly-sdk-docs-mcp", "install"];
+
+  if (argv.client) args.push("--client", String(argv.client));
+  if (argv.scope) args.push("--scope", String(argv.scope));
+  if (argv.name) args.push("--name", String(argv.name));
+  if (ver) args.push("--sdk-docs-version", ver);
+  if (argv["dry-run"]) args.push("--dry-run");
+  if (argv.force) args.push("--force");
+
+  debugMcpInstall("cwd", process.cwd());
+  debugMcpInstall("spawn", command, args);
+
+  const result = spawnSync(command, args, {
+    stdio: "inherit",
+    shell: process.platform === "win32",
+  });
+
+  debugMcpInstall(
+    "spawnSync done",
+    "status",
+    result.status,
+    "signal",
+    result.signal,
+    "error",
+    result.error,
+  );
+
+  if (result.error) {
+    throw result.error;
+  }
+  return result.status ?? 1;
+}
+
+module.exports = {
+  command: "install",
+  describe:
+    "Install Orderly SDK Docs MCP config for Claude/Codex/Cursor/OpenCode",
+  builder: (yargs) => {
+    return yargs
+      .option("client", {
+        type: "string",
+        describe:
+          "Target client(s): claude|codex|cursor|opencode|all (comma-separated supported)",
+        default: "all",
+      })
+      .option("scope", {
+        type: "string",
+        choices: ["user", "project"],
+        default: "user",
+      })
+      .option("name", {
+        type: "string",
+        describe: "MCP server name in config mcpServers map",
+        default: "orderly-sdk-docs",
+      })
+      .option("dry-run", {
+        type: "boolean",
+        default: false,
+      })
+      .option("force", {
+        type: "boolean",
+        default: false,
+      })
+      .option("sdk-docs-version", {
+        type: "string",
+        describe:
+          "Pin @orderly.network/sdk-docs (semver or dist-tag, e.g. 0.1.0 or beta); applies to this run and merged MCP config",
+      })
+      .example(
+        "orderly-devkit mcp install --client cursor --scope project",
+        "Install MCP entry for Cursor in project scope",
+      )
+      .example(
+        "orderly-devkit mcp install --sdk-docs-version 0.1.0 --scope user",
+        "Pin a specific sdk-docs release for npx and editor MCP configs",
+      );
+  },
+  handler: async (argv) => {
+    const status = forwardToSdkDocs(argv);
+    process.exitCode = status;
+  },
+};

package/src/commands/mcp.js

@@ -0,0 +1,9 @@
+module.exports = {
+  command: "mcp <subcommand>",
+  describe: "MCP related commands",
+  builder: (yargs) => {
+    return yargs
+      .commandDir("mcp")
+      .demandCommand(1, "Please provide an MCP subcommand.");
+  },
+};

package/src/commands/skills/install.js

@@ -0,0 +1,211 @@
+const { spawnSync } = require("child_process");
+const chalk = require("chalk");
+const {
+  ORDERLY_SKILLS_REPO,
+  ORDERLY_PLUGIN_SKILL_NAMES,
+} = require("../../internal/constants");
+
+/**
+ * Extra argv after `--` is forwarded verbatim to `skills add` (upstream flags).
+ * @returns {string[]}
+ */
+function getPassthroughArgs() {
+  const idx = process.argv.indexOf("--");
+  if (idx === -1) {
+    return [];
+  }
+  return process.argv.slice(idx + 1);
+}
+
+/**
+ * @param {unknown} value
+ * @returns {string[]}
+ */
+function asStringArray(value) {
+  if (value == null) {
+    return [];
+  }
+  if (Array.isArray(value)) {
+    return value.map(String).filter(Boolean);
+  }
+  return [String(value)];
+}
+
+/**
+ * Build argv for: npx -y skills add …
+ * @param {Record<string, unknown>} argv
+ * @returns {string[]}
+ */
+function buildSkillsAddArgs(argv) {
+  const source =
+    typeof argv.source === "string" && argv.source.trim() !== ""
+      ? argv.source.trim()
+      : ORDERLY_SKILLS_REPO;
+
+  const args = [source];
+  const passthrough = getPassthroughArgs();
+
+  if (argv.list) {
+    args.push("--list");
+    if (argv.yes === true) {
+      args.push("-y");
+    }
+    appendSharedTail(args, argv);
+    args.push(...passthrough);
+    return args;
+  }
+
+  if (argv.all === true) {
+    args.push("--all");
+    appendSharedTail(args, argv);
+    args.push(...passthrough);
+    return args;
+  }
+
+  const userSkills = asStringArray(argv.skill);
+  if (userSkills.length > 0) {
+    for (const name of userSkills) {
+      args.push("--skill", name);
+    }
+  } else {
+    for (const name of ORDERLY_PLUGIN_SKILL_NAMES) {
+      args.push("--skill", name);
+    }
+  }
+  args.push("-y");
+
+  appendSharedTail(args, argv);
+  args.push(...passthrough);
+  return args;
+}
+
+/**
+ * @param {string[]} args
+ * @param {Record<string, unknown>} argv
+ */
+function appendSharedTail(args, argv) {
+  if (argv.global === true) {
+    args.push("-g");
+  }
+  const agents = asStringArray(argv.agent);
+  for (const a of agents) {
+    args.push("-a", a);
+  }
+  if (argv.copy === true) {
+    args.push("--copy");
+  }
+}
+
+/**
+ * @param {string[]} skillsAddArgs
+ * @returns {string[]}
+ */
+function buildNpxArgv(skillsAddArgs) {
+  return ["-y", "skills", "add", ...skillsAddArgs];
+}
+
+/**
+ * @param {string[]} argv
+ */
+function printDryRun(argv) {
+  const line = [
+    "npx",
+    ...argv.map((a) => (/\s/.test(a) ? JSON.stringify(a) : a)),
+  ].join(" ");
+  console.log(chalk.cyan("Dry run — would execute:"));
+  console.log(line);
+}
+
+module.exports = {
+  command: "install [source]",
+  describe:
+    "Install Orderly plugin workflow agent skills (defaults: official repo + four skills + -y)",
+  builder: (yargs) => {
+    return yargs
+      .positional("source", {
+        type: "string",
+        describe:
+          "GitHub owner/repo, URL, or local path (default: OrderlyNetwork/orderly-skills)",
+      })
+      .option("list", {
+        type: "boolean",
+        default: false,
+        describe:
+          "List skills in the source repo without installing (no default --skill/-y)",
+      })
+      .option("skill", {
+        alias: "s",
+        type: "array",
+        describe:
+          "Install only these skill names (replaces default four when set; not used with --list)",
+      })
+      .option("all", {
+        type: "boolean",
+        default: false,
+        describe:
+          "Forward --all to skills CLI (install all skills/agents; skips default four + auto -y)",
+      })
+      .option("global", {
+        alias: "g",
+        type: "boolean",
+        default: false,
+        describe: "Install globally (forward -g to skills CLI)",
+      })
+      .option("agent", {
+        alias: "a",
+        type: "array",
+        describe: "Target agent(s), e.g. -a cursor -a claude-code",
+      })
+      .option("copy", {
+        type: "boolean",
+        default: false,
+        describe: "Copy files instead of symlinks (--copy)",
+      })
+      .option("yes", {
+        alias: "y",
+        type: "boolean",
+        describe:
+          "With --list only: also pass -y to skills CLI (default install already uses -y)",
+      })
+      .option("dry-run", {
+        type: "boolean",
+        default: false,
+        describe: "Print the npx command without running it",
+      })
+      .example(
+        "orderly-devkit skills install",
+        "Install all four Orderly plugin skills from the official repo (-y, non-interactive)",
+      )
+      .example(
+        "orderly-devkit skills install --list",
+        "List available skills in the official repo",
+      )
+      .example(
+        "orderly-devkit skills install other/repo --skill my-skill -y",
+        "Advanced: different repo and explicit skills (default four skipped)",
+      )
+      .example(
+        "orderly-devkit skills install -- --some-new-skills-flag",
+        "Forward extra flags after -- to the skills CLI",
+      );
+  },
+  handler: async (argv) => {
+    const skillsAddArgs = buildSkillsAddArgs(argv);
+    const npxArgs = buildNpxArgv(skillsAddArgs);
+
+    if (argv["dry-run"]) {
+      printDryRun(npxArgs);
+      return;
+    }
+
+    const result = spawnSync("npx", npxArgs, {
+      stdio: "inherit",
+      shell: process.platform === "win32",
+    });
+
+    if (result.error) {
+      throw result.error;
+    }
+    process.exitCode = result.status ?? 1;
+  },
+};

package/src/commands/skills.js

@@ -0,0 +1,10 @@
+module.exports = {
+  command: "skills <subcommand>",
+  describe:
+    "Install Orderly agent skills for plugin workflows (create, write, add, submit)",
+  builder: (yargs) => {
+    return yargs
+      .commandDir("skills")
+      .demandCommand(1, "Please provide a skills subcommand.");
+  },
+};