@kodiak-finance/orderly-devkit 1.0.2

package/src/internal/orderlySdkDocsMcpDetect.js

@@ -0,0 +1,255 @@
+const fs = require("fs");
+const path = require("path");
+const { dim } = require("../shared");
+const { DEFAULT_ORDERLY_SDK_DOCS_MCP_NAME } = require("./constants");
+
+// Config paths per agent — keep in sync with packages/sdk-docs/src/install/clients.ts.
+
+const ALL_CLIENTS = /** @type {const} */ ([
+  "claude",
+  "codex",
+  "cursor",
+  "opencode",
+]);
+
+const CANONICAL_COMMAND = "npx";
+const CANONICAL_ARGS = [
+  "-y",
+  "@orderly.network/sdk-docs",
+  "orderly-sdk-docs-mcp",
+];
+
+/**
+ * @returns {Record<string, { user: string; project: string }>}
+ */
+function getClientPaths() {
+  const home = process.env.HOME || process.env.USERPROFILE || "";
+  return {
+    claude: {
+      user: path.join(home, ".claude.json"),
+      project: ".claude.json",
+    },
+    codex: {
+      user: path.join(home, ".codex", "config.json"),
+      project: ".codex/config.json",
+    },
+    cursor: {
+      user: path.join(home, ".cursor", "mcp.json"),
+      project: ".cursor/mcp.json",
+    },
+    opencode: {
+      user: path.join(home, ".opencode", "config.json"),
+      project: ".opencode/config.json",
+    },
+  };
+}
+
+/**
+ * Same semantics as sdk-docs readJsonConfig: missing/empty → {}.
+ * @param {string} configPath
+ * @returns {{ ok: true; data: Record<string, unknown> } | { ok: false; error: string }}
+ */
+function readJsonConfigSafe(configPath) {
+  if (!fs.existsSync(configPath)) {
+    return { ok: true, data: {} };
+  }
+  const rawText = fs.readFileSync(configPath, "utf8").trim();
+  if (!rawText) {
+    return { ok: true, data: {} };
+  }
+  try {
+    const parsed = JSON.parse(rawText);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      return { ok: false, error: "Root value must be an object" };
+    }
+    return { ok: true, data: /** @type {Record<string, unknown>} */ (parsed) };
+  } catch (e) {
+    return {
+      ok: false,
+      error: e instanceof Error ? e.message : String(e),
+    };
+  }
+}
+
+/**
+ * @param {unknown} args
+ * @returns {boolean}
+ */
+function argsMatchCanonical(args) {
+  if (!Array.isArray(args)) {
+    return false;
+  }
+  return JSON.stringify(args) === JSON.stringify(CANONICAL_ARGS);
+}
+
+/**
+ * Strict match for the default server key (same as sdk-docs merge noop check).
+ * @param {unknown} entry
+ * @returns {boolean}
+ */
+function entryMatchesCanonical(entry) {
+  if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+    return false;
+  }
+  const o = /** @type {Record<string, unknown>} */ (entry);
+  return o.command === CANONICAL_COMMAND && argsMatchCanonical(o.args);
+}
+
+/**
+ * Loose match for custom --name installs.
+ * @param {unknown} entry
+ * @returns {boolean}
+ */
+function entryMatchesFuzzyOrderly(entry) {
+  if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+    return false;
+  }
+  const o = /** @type {Record<string, unknown>} */ (entry);
+  if (o.command !== "npx") {
+    return false;
+  }
+  const args = o.args;
+  if (!Array.isArray(args)) {
+    return false;
+  }
+  return (
+    args.includes("orderly-sdk-docs-mcp") &&
+    args.includes("@orderly.network/sdk-docs")
+  );
+}
+
+/**
+ * @param {Record<string, unknown>} data
+ * @param {string} defaultName
+ * @returns {{ configured: boolean; serverKey?: string }}
+ */
+function analyzeMcpServers(data, defaultName) {
+  const mcpServersRaw = data.mcpServers;
+  const mcpServers =
+    mcpServersRaw &&
+    typeof mcpServersRaw === "object" &&
+    !Array.isArray(mcpServersRaw)
+      ? /** @type {Record<string, unknown>} */ (mcpServersRaw)
+      : {};
+
+  const named = mcpServers[defaultName];
+  if (named && entryMatchesCanonical(named)) {
+    return { configured: true, serverKey: defaultName };
+  }
+
+  for (const [key, val] of Object.entries(mcpServers)) {
+    if (entryMatchesFuzzyOrderly(val)) {
+      return { configured: true, serverKey: key };
+    }
+  }
+  return { configured: false };
+}
+
+/**
+ * @param {string} configPath
+ * @param {string} defaultName
+ * @returns {{
+ *   configPath: string;
+ *   exists: boolean;
+ *   configured: boolean;
+ *   serverKey?: string;
+ *   error?: string;
+ * }}
+ */
+function inspectConfigFile(configPath, defaultName) {
+  const exists = fs.existsSync(configPath);
+  if (!exists) {
+    return { configPath, exists: false, configured: false };
+  }
+  const read = readJsonConfigSafe(configPath);
+  if (!read.ok) {
+    return {
+      configPath,
+      exists: true,
+      configured: false,
+      error: read.error,
+    };
+  }
+  const { configured, serverKey } = analyzeMcpServers(read.data, defaultName);
+  return {
+    configPath,
+    exists: true,
+    configured,
+    ...(serverKey ? { serverKey } : {}),
+  };
+}
+
+/**
+ * @param {string} cwd
+ * @param {{ serverName?: string; clients?: string[] }} [options]
+ */
+function getOrderlySdkDocsMcpReport(cwd, options = {}) {
+  const resolvedCwd = path.resolve(cwd);
+  const defaultName = options.serverName || DEFAULT_ORDERLY_SDK_DOCS_MCP_NAME;
+  const paths = getClientPaths();
+  const want =
+    options.clients && options.clients.length > 0
+      ? ALL_CLIENTS.filter((c) => options.clients.includes(c))
+      : ALL_CLIENTS;
+
+  /** @type {Record<string, { user: ReturnType<typeof inspectConfigFile>; project: ReturnType<typeof inspectConfigFile> }>} */
+  const clients = {};
+
+  for (const client of want) {
+    const p = paths[client];
+    clients[client] = {
+      user: inspectConfigFile(p.user, defaultName),
+      project: inspectConfigFile(
+        path.join(resolvedCwd, p.project),
+        defaultName,
+      ),
+    };
+  }
+
+  return {
+    cwd: resolvedCwd,
+    defaultServerName: defaultName,
+    clients,
+  };
+}
+
+/**
+ * True if any checked user or project config for this cwd shows Orderly SDK Docs MCP.
+ * @param {string} cwd
+ * @param {{ serverName?: string; clients?: string[] }} [options]
+ * @returns {boolean}
+ */
+function isOrderlySdkDocsMcpConfiguredAnywhere(cwd, options = {}) {
+  const report = getOrderlySdkDocsMcpReport(cwd, options);
+  for (const row of Object.values(report.clients)) {
+    if (row.user.configured || row.project.configured) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * One-time style hint after scaffold/submit when MCP is missing (opt-out via env).
+ * @param {string} cwd
+ */
+function maybePrintOrderlyDevEnvironmentHints(cwd) {
+  if (process.env.ORDERLY_DEVKIT_NO_ENV_HINTS) {
+    return;
+  }
+  if (isOrderlySdkDocsMcpConfiguredAnywhere(cwd)) {
+    return;
+  }
+  console.log();
+  dim("Tip: Orderly SDK Docs MCP was not detected in your agent config files.");
+  dim("  Install: orderly-devkit mcp install");
+  dim("  Verify:  orderly-devkit mcp detect");
+  dim("  Skills:  orderly-devkit skills install");
+}
+
+module.exports = {
+  ALL_CLIENTS,
+  getOrderlySdkDocsMcpReport,
+  isOrderlySdkDocsMcpConfiguredAnywhere,
+  maybePrintOrderlyDevEnvironmentHints,
+};

package/src/internal/templateGenerator.js

@@ -0,0 +1,294 @@
+const degit = require("degit");
+const path = require("path");
+const fs = require("fs-extra");
+const Handlebars = require("handlebars");
+const fg = require("fast-glob");
+const { execSync } = require("child_process");
+
+// ============================================================================
+// Core API
+// ============================================================================
+
+/**
+ * Download a template from a GitHub repository using degit.
+ * @param {string} repo - e.g. "OrderlyNetwork/orderly-plugin-template"
+ * @param {string} targetDir - local directory to clone into
+ * @param {object} options
+ * @param {boolean} options.force - overwrite existing files (default: true)
+ */
+async function downloadTemplate(repo, targetDir, options = {}) {
+  const { force = true } = options;
+  console.log(`\n  Downloading template from https://github.com/${repo}...`);
+  const emitter = degit(repo, { cache: false, force });
+  await emitter.clone(targetDir);
+  console.log("  Template download completed");
+}
+
+/**
+ * Replace all Handlebars template variables in file contents.
+ * @param {string} dir - directory to scan
+ * @param {object} vars - key-value pairs for replacement
+ */
+async function replaceTemplateVars(dir, vars) {
+  const files = await fg(["**/*", "**/.*"], {
+    cwd: dir,
+    absolute: true,
+    ignore: ["**/node_modules/**", "**/.git/**"],
+  });
+
+  await Promise.all(
+    files.map(async (filePath) => {
+      if (isBinaryFile(filePath)) return;
+      const content = await fs.readFile(filePath, "utf-8");
+      const template = Handlebars.compile(content);
+      const result = template(vars);
+      await fs.writeFile(filePath, result);
+    }),
+  );
+}
+
+/**
+ * Rename files and directories that contain __name__ to the actual name.
+ * @param {string} dir - directory to scan
+ * @param {string} nameVar - the name to replace __name__ with (PascalCase)
+ */
+async function renameTemplateFiles(dir, nameVar) {
+  // Get directories first (deepest first to rename children before parents)
+  const dirs = await fg(["**/*", "**/.*"], {
+    cwd: dir,
+    absolute: true,
+    ignore: ["**/node_modules/**", "**/.git/**"],
+    onlyDirectories: true,
+  });
+  dirs.sort((a, b) => b.split(path.sep).length - a.split(path.sep).length);
+
+  // Then get files
+  const files = await fg(["**/*", "**/.*"], {
+    cwd: dir,
+    absolute: true,
+    ignore: ["**/node_modules/**", "**/.git/**"],
+    onlyDirectories: false,
+    onlyFiles: true,
+  });
+
+  for (const dirPath of dirs) {
+    await renamePath(dirPath, nameVar);
+  }
+
+  for (const filePath of files) {
+    await renamePath(filePath, nameVar);
+  }
+}
+
+/**
+ * Run npm install in the target directory.
+ * @param {string} dir - directory to install deps
+ * @param {boolean} skipInstall - if true, skip installation
+ */
+function installDeps(dir, skipInstall = false) {
+  if (skipInstall) {
+    console.log("  Skipping dependency installation");
+    return;
+  }
+  console.log("\n  Installing dependencies...");
+  execSync("npm install", { cwd: dir, stdio: "inherit" });
+}
+
+// ============================================================================
+// Full Generation Pipeline
+// ============================================================================
+
+/**
+ * Check if a directory exists and is non-empty.
+ * @param {string} dirPath
+ * @returns {Promise<boolean>}
+ */
+async function isNonEmptyDir(dirPath) {
+  if (!(await fs.pathExists(dirPath))) return false;
+  const stat = await fs.stat(dirPath);
+  if (!stat.isDirectory()) return false;
+  const entries = await fs.readdir(dirPath);
+  const visible = entries.filter((e) => !e.startsWith("."));
+  return visible.length > 0;
+}
+
+/**
+ * Verify a GitHub repo exists before attempting clone.
+ * Uses `git ls-remote` which fails fast if repo doesn't exist.
+ * @param {string} repo - e.g. "OrderlyNetwork/orderly-plugin-template"
+ * @returns {Promise<boolean>}
+ */
+async function verifyGitHubRepo(repo) {
+  console.log(`  Checking repository https://github.com/${repo}...`);
+  try {
+    execSync(`git ls-remote https://github.com/${repo} HEAD`, {
+      cwd: process.cwd(),
+      stdio: "pipe",
+      timeout: 15000,
+    });
+    return true;
+  } catch (err) {
+    if (err.status === 128) {
+      throw new Error(
+        `Repository "https://github.com/${repo}" not found or is not accessible. ` +
+          "Please verify the repository exists and you have access to it.",
+      );
+    }
+    if (
+      err.status === null &&
+      err.message &&
+      err.message.includes("timed out")
+    ) {
+      throw new Error(
+        `Network timeout while connecting to https://github.com/${repo}. ` +
+          "Please check your internet connection.",
+      );
+    }
+    throw new Error(
+      `Failed to access repository https://github.com/${repo}: ${err.message}`,
+    );
+  }
+}
+
+/**
+ * Run the full template generation pipeline.
+ * @param {object} config
+ * @param {string} config.repo - GitHub repo (e.g. "OrderlyNetwork/orderly-plugin-template")
+ * @param {string} config.targetDir - local output directory
+ * @param {object} config.vars - template variables
+ * @param {string} config.vars.name - the PascalCase name (e.g. "MyPlugin")
+ * @param {boolean} config.skipInstall
+ */
+async function generateFromTemplate(config) {
+  const { repo, targetDir, vars, skipInstall = false } = config;
+
+  // Ensure target dir is empty or does not exist
+  if (await isNonEmptyDir(targetDir)) {
+    throw new Error(
+      `Target directory "${targetDir}" is not empty. Please use an empty directory or a non-existent path.`,
+    );
+  }
+
+  // Create the target directory if it doesn't exist
+  await fs.ensureDir(targetDir);
+
+  // Step 0: Verify repo exists
+  await verifyGitHubRepo(repo);
+
+  // Step 1: Download
+  await downloadTemplate(repo, targetDir);
+
+  // Step 2: Replace content
+  await replaceTemplateVars(targetDir, vars);
+
+  // Step 3: Rename files
+  await renameTemplateFiles(targetDir, vars.name);
+
+  // Step 4: Install deps
+  installDeps(targetDir, skipInstall);
+
+  console.log(`\n  Plugin generated at: ${targetDir}`);
+}
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+/**
+ * Determine if a file is binary (should skip template processing).
+ */
+function isBinaryFile(filePath) {
+  const ext = path.extname(filePath).toLowerCase();
+  const binaryExts = [
+    ".png",
+    ".jpg",
+    ".jpeg",
+    ".gif",
+    ".bmp",
+    ".ico",
+    ".woff",
+    ".woff2",
+    ".ttf",
+    ".eot",
+    ".otf",
+    ".pdf",
+    ".zip",
+    ".tar",
+    ".gz",
+    ".rar",
+  ];
+  return binaryExts.includes(ext);
+}
+
+/**
+ * Rename a file or directory if its name contains __name__.
+ */
+async function renamePath(filePath, nameVar) {
+  const dir = path.dirname(filePath);
+  const basename = path.basename(filePath);
+
+  if (basename.includes("__name__")) {
+    const newBasename = basename.replace(/__name__/g, nameVar);
+    const newPath = path.join(dir, newBasename);
+    await fs.move(filePath, newPath);
+  }
+}
+
+/**
+ * Convert a string to PascalCase.
+ */
+function toPascalCase(str) {
+  return str
+    .replace(/[-_\s]+(.)/g, (_, c) => c.toUpperCase())
+    .replace(/^(.)/, (c) => c.toUpperCase());
+}
+
+/**
+ * Convert a string to kebab-case.
+ */
+function toKebabCase(str) {
+  return str
+    .replace(/([a-z])([A-Z])/g, "$1-$2")
+    .replace(/[\s_]+/g, "-")
+    .toLowerCase();
+}
+
+/**
+ * Convert a string to camelCase.
+ */
+function toCamelCase(str) {
+  return str
+    .replace(/[-_\s]+(.)/g, (_, c) => c.toUpperCase())
+    .replace(/^(.)/, (c) => c.toLowerCase());
+}
+
+/**
+ * Validate that a name is in PascalCase.
+ */
+function validateName(name) {
+  if (!name || typeof name !== "string") {
+    return { valid: false, error: "Name cannot be empty" };
+  }
+  if (!/^[A-Z][A-Za-z0-9]*$/.test(name)) {
+    return {
+      valid: false,
+      error: "Name must be in PascalCase (e.g. MyPlugin)",
+    };
+  }
+  return { valid: true };
+}
+
+module.exports = {
+  downloadTemplate,
+  replaceTemplateVars,
+  renameTemplateFiles,
+  installDeps,
+  generateFromTemplate,
+  isNonEmptyDir,
+  verifyGitHubRepo,
+  isBinaryFile,
+  toPascalCase,
+  toKebabCase,
+  toCamelCase,
+  validateName,
+};

package/src/shared.js

@@ -0,0 +1,136 @@
+const chalk = require("chalk");
+const { prompt } = require("enquirer");
+
+// Logger utilities
+function log(message) {
+  console.log(message);
+}
+
+function info(message) {
+  console.log(chalk.blue("ℹ"), message);
+}
+
+function success(message) {
+  console.log(chalk.green("✓"), message);
+}
+
+function warn(message) {
+  console.log(chalk.yellow("⚠"), message);
+}
+
+function error(message) {
+  console.error(chalk.red("✗"), message);
+}
+
+function heading(message) {
+  console.log(chalk.bold.cyan(message));
+}
+
+function dim(message) {
+  console.log(chalk.dim(message));
+}
+
+// Interactive prompts
+async function input(message, initial) {
+  const result = await prompt({
+    type: "input",
+    name: "value",
+    message,
+    initial: initial || "",
+  });
+  return result.value;
+}
+
+async function select(message, choices, initial) {
+  const result = await prompt({
+    type: "select",
+    name: "value",
+    message,
+    choices,
+    initial: initial || 0,
+  });
+  return result.value;
+}
+
+async function confirm(message) {
+  const result = await prompt({
+    type: "confirm",
+    name: "confirm",
+    message,
+    initial: true,
+  });
+  return result.confirm;
+}
+
+/**
+ * Normalize backend error payload into a human-readable message.
+ * @param {unknown} responseData
+ * @param {number} status
+ * @returns {string}
+ */
+function getErrorMessage(responseData, status) {
+  const candidates = [
+    responseData?.message,
+    responseData?.error,
+    responseData?.details,
+  ];
+
+  for (const candidate of candidates) {
+    if (typeof candidate === "string" && candidate.trim()) {
+      return candidate;
+    }
+
+    if (Array.isArray(candidate) && candidate.length > 0) {
+      const firstString = candidate.find((item) => typeof item === "string");
+      if (firstString) {
+        return firstString;
+      }
+      return JSON.stringify(candidate);
+    }
+
+    if (candidate && typeof candidate === "object") {
+      if (typeof candidate.message === "string" && candidate.message.trim()) {
+        return candidate.message;
+      }
+      return JSON.stringify(candidate);
+    }
+  }
+
+  return `HTTP ${status}`;
+}
+
+/**
+ * Extract a stable error code/message pair from backend payloads.
+ * Supports legacy `{ message }` and structured `{ error: { code, message } }`.
+ *
+ * @param {unknown} responseData
+ * @param {number} status
+ * @returns {{ code: string | null, message: string }}
+ */
+function getApiErrorInfo(responseData, status) {
+  const codeCandidate = responseData?.error?.code;
+  const normalizedCode =
+    typeof codeCandidate === "string" && codeCandidate.trim()
+      ? codeCandidate.trim()
+      : null;
+
+  return {
+    code: normalizedCode,
+    message: getErrorMessage(responseData, status),
+  };
+}
+
+module.exports = {
+  log,
+  info,
+  success,
+  warn,
+  error,
+  heading,
+  dim,
+  input,
+  select,
+  confirm,
+  getErrorMessage,
+  getApiErrorInfo,
+};

package/src/version.ts

@@ -0,0 +1,13 @@
+declare global {
+  interface Window {
+    __ORDERLY_VERSION__?: {
+      [key: string]: string;
+    };
+  }
+}
+if (typeof window !== "undefined") {
+  window.__ORDERLY_VERSION__ = window.__ORDERLY_VERSION__ || {};
+  window.__ORDERLY_VERSION__["@orderly.network/devkit"] = "1.0.2";
+}
+
+export default "1.0.2";