@kodiak-finance/orderly-devkit 1.0.2

package/README.md

@@ -0,0 +1,160 @@
+# @orderly.network/devkit
+
+CLI toolkit for scaffolding plugins and modules, authenticating with Marketplace, submitting and managing plugins, and installing MCP / agent skill integrations.
+
+## Requirements
+
+- **Node.js** v20.19.0 or newer.
+
+## Installation
+
+### From npm
+
+```bash
+pnpm add -g @orderly.network/devkit
+# or
+npm install -g @orderly.network/devkit
+```
+
+Then run:
+
+```bash
+orderly-devkit --help
+```
+
+### One-off without global install
+
+```bash
+pnpm dlx @orderly.network/devkit --help
+# or
+npx @orderly.network/devkit --help
+```
+
+## Authentication
+
+Login uses GitHub OAuth in the browser and a short-lived local callback server.
+
+- **Credentials file:** `~/.orderly/auth.json` (created automatically).
+- The CLI opens the marketplace login page and completes OAuth callback automatically.
+
+```bash
+orderly-devkit login              # open browser, complete GitHub auth
+orderly-devkit login --force      # re-authenticate even if already logged in
+orderly-devkit login --port 9877  # if default port is busy (default is 9876)
+orderly-devkit whoami
+orderly-devkit logout
+```
+
+## Commands overview
+
+Run `orderly-devkit <command> --help` for options on any command.
+
+### `create`
+
+Scaffold new artifacts (interactive).
+
+| Subcommand      | Description                                                                                                                                                                      |
+| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `create plugin` | Clone and render the plugin template (`OrderlyNetwork/orderly-plugin-template`), prompt for name/plugin id/interceptor target, and optionally generate `.orderly-manifest.json`. |
+| `create module` | Guided flow for module type (`page`, `component`, `hook`, `utils`, `module`). **File generation is not implemented yet**—it only collects choices and prints a summary.          |
+
+```bash
+orderly-devkit create plugin
+orderly-devkit create module
+orderly-devkit create module --name my-module
+```
+
+### Marketplace: `submit`, `list`, `update`, `view`
+
+These commands use the Marketplace API. You must be logged in (`orderly-devkit login`).
+
+**`submit`** — register a new plugin from a local directory.
+
+- Resolves metadata from `package.json` and/or `.orderly-manifest.json`.
+- `repoUrl` should be a GitHub URL (`https://github.com/<owner>/<repo>`); it can be filled from `git remote` when missing.
+- **Tags** must be from the allowed set: `UI`, `Indicator`, `Order Entry`, `Trading`, `Chart`, `Portfolio`, `Analytics`, `Tool`, `Widget` (max 5).
+
+```bash
+orderly-devkit submit
+orderly-devkit submit --path ./my-plugin
+orderly-devkit submit -p ./my-plugin --tags UI,Trading --dry-run
+orderly-devkit submit -p ./my-plugin --storybook-url https://example.com/storybook
+```
+
+**`list`** — list plugins associated with your account.
+
+```bash
+orderly-devkit list
+orderly-devkit list --json
+```
+
+**`update`** — PATCH plugin metadata for an existing listing (requires `pluginId` in `.orderly-manifest.json`).
+
+Updatable fields include: `name`, `description`, `tags`, `coverImages`, `storybookUrl`, `storybookTooltip`, `usagePrompt`.
+
+```bash
+orderly-devkit update --path ./my-plugin --dry-run
+orderly-devkit update -p ./my-plugin
+```
+
+**`view`** — fetch one plugin by ID as JSON.
+
+```bash
+orderly-devkit view <plugin-id>
+```
+
+### `mcp install`
+
+Install the **Orderly SDK Docs** MCP server entry for Claude, Codex, Cursor, OpenCode, etc.
+
+```bash
+orderly-devkit mcp install
+orderly-devkit mcp install --client cursor --scope project
+orderly-devkit mcp install --client all --scope user
+orderly-devkit mcp install --sdk-docs-version 0.1.0
+orderly-devkit mcp install --dry-run
+orderly-devkit mcp install --force
+```
+
+| Option     | Description                                                                               |
+| ---------- | ----------------------------------------------------------------------------------------- |
+| `--client` | `claude`, `codex`, `cursor`, `opencode`, `all`, or comma-separated list (default: `all`). |
+| `--scope`  | `user` or `project` (default: `user`).                                                    |
+| `--name`   | MCP server id in config (default: `orderly-sdk-docs`).                                    |
+
+### `skills install`
+
+Install Orderly **agent skills** for plugin workflows (create, write, add, submit) with `npx -y skills add …`.
+
+Default behavior installs four skills non-interactively: `orderly-plugin-create`, `orderly-plugin-write`, `orderly-plugin-add`, `orderly-plugin-submit`.
+
+```bash
+orderly-devkit skills install
+orderly-devkit skills install --list
+orderly-devkit skills install --dry-run
+orderly-devkit skills install other/repo --skill my-skill -y
+orderly-devkit skills install -- --some-upstream-skills-flag
+```
+
+| Option            | Description                                                             |
+| ----------------- | ----------------------------------------------------------------------- |
+| `[source]`        | GitHub `owner/repo`, URL, or local path (default source is built in).   |
+| `--list`          | List skills in the source without installing.                           |
+| `--skill` / `-s`  | Repeatable; install only named skills (replaces default four when set). |
+| `--all`           | Forward `--all` to the skills CLI.                                      |
+| `--global` / `-g` | Global install for the skills CLI.                                      |
+| `--agent` / `-a`  | Target agent(s), e.g. `-a cursor`.                                      |
+| `--copy`          | Copy files instead of symlinks.                                         |
+| `--yes` / `-y`    | With `--list` only: pass `-y` through.                                  |
+| `--`              | Everything after `--` is forwarded to the upstream `skills` CLI.        |
+
+## Troubleshooting
+
+- **Marketplace API errors** — check your network connection; if the CLI reports a failed request, try again later or verify you are logged in (`orderly-devkit whoami`).
+- **Login: port in use** — run `orderly-devkit login --port <free-port>`.
+- **Ctrl+C during prompts** — the CLI handles enquirer cancellation and exits with a clear message when possible.
+- **Invalid working directory** — if the shell’s cwd was deleted, the CLI may switch to `HOME` or the package directory and warn you.
+
+## License
+
+See the repository root license for this package’s distribution terms.

package/bin/cli.js

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const path = require("path");
+const yargs = require("yargs/yargs");
+const { hideBin } = require("yargs/helpers");
+const chalk = require("chalk");
+
+// Resolve commands directory relative to this file's location
+const commandsDir = path.resolve(__dirname, "../src/commands");
+
+/**
+ * Detect known enquirer cancel crash on newer Node runtimes.
+ * This keeps Ctrl+C behavior user-friendly while preserving real errors.
+ * @param {unknown} err
+ * @returns {boolean}
+ */
+function isEnquirerReadlineCancelError(err) {
+  if (!err || typeof err !== "object") {
+    return false;
+  }
+
+  const error =
+    /** @type {{ code?: string; stack?: string; message?: string }} */ (err);
+  const stack = typeof error.stack === "string" ? error.stack : "";
+  const message = typeof error.message === "string" ? error.message : "";
+
+  return (
+    error.code === "ERR_USE_AFTER_CLOSE" &&
+    message.includes("readline") &&
+    stack.includes("enquirer/lib/")
+  );
+}
+
+/**
+ * Gracefully handle Ctrl+C prompt cancellation emitted by enquirer.
+ * Only swallows the known cancellation crash and rethrows everything else.
+ */
+function setupGracefulPromptInterruptHandling() {
+  process.on("uncaughtException", (err) => {
+    if (!isEnquirerReadlineCancelError(err)) {
+      throw err;
+    }
+
+    console.log();
+    console.log(chalk.yellow("Operation cancelled."));
+    process.exit(130);
+  });
+}
+
+/**
+ * Ensure process cwd is valid before yargs initialization.
+ * Yargs reads cwd eagerly; when users run CLI from a deleted directory,
+ * Node throws ENOENT before command parsing starts.
+ */
+function ensureValidWorkingDirectory() {
+  const cwd = process.cwd();
+  try {
+    fs.accessSync(cwd);
+    return;
+  } catch {
+    const fallbackDir =
+      process.env.HOME ||
+      process.env.USERPROFILE ||
+      path.resolve(__dirname, "..");
+
+    try {
+      fs.accessSync(fallbackDir);
+      process.chdir(fallbackDir);
+      console.warn(
+        chalk.yellow(
+          `Current working directory is unavailable. Switched to: ${fallbackDir}`,
+        ),
+      );
+    } catch {
+      // Fallback also unavailable — let the error surface naturally.
+      throw new Error(
+        `Current working directory "${cwd}" is inaccessible. ` +
+          `Please change to a valid directory and try again.`,
+      );
+    }
+  }
+}
+
+setupGracefulPromptInterruptHandling();
+ensureValidWorkingDirectory();
+
+yargs(hideBin(process.argv))
+  .scriptName("orderly-devkit")
+  .usage(chalk.cyan("Usage:") + " $0 <command> [options]")
+  .alias("v", "version")
+  .alias("h", "help")
+  .showHelpOnFail(true)
+  .strictCommands()
+  .demandCommand(1, "Please specify a command.")
+  .command("create", "Create a new plugin or module", (yargs) => {
+    return yargs.commandDir(path.join(commandsDir, "create"));
+  })
+  .commandDir(commandsDir)
+  .recommendCommands()
+  .fail((message, error, parser) => {
+    // Always show usage/help for missing or invalid command input.
+    parser.showHelp();
+    if (message) {
+      console.error(chalk.red(`\n${message}`));
+    }
+    if (error && !message) {
+      console.error(chalk.red(`\n${error.message}`));
+    }
+    process.exit(1);
+  })
+  .parse();

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@kodiak-finance/orderly-devkit",
+  "version": "1.0.2",
+  "description": "CLI toolkit for scaffolding and building DEXs, plugins, and modules with Orderly",
+  "main": "",
+  "bin": {
+    "kodiak-orderly-devkit": "./bin/cli.js"
+  },
+  "files": [
+    "bin",
+    "src"
+  ],
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "chalk": "^4.1.2",
+    "degit": "^2.8.4",
+    "enquirer": "^2.4.1",
+    "fast-glob": "^3.3.3",
+    "fs-extra": "^11.3.0",
+    "handlebars": "^4.7.9",
+    "yargs": "^17.7.2"
+  },
+  "devDependencies": {
+    "rimraf": "^5.0.0",
+    "tsconfig": "0.11.34-alpha.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "clean": "rimraf dist",
+    "link-global": "pnpm link --global"
+  }
+}

package/src/commands/create/module.js

@@ -0,0 +1,49 @@
+const { input, select, heading, info, success } = require("../../shared");
+const { MODULE_TYPES } = require("../../internal/constants");
+
+// create module command - default export for yargs commandDir
+module.exports = {
+  command: "module",
+  describe: "Create a new module",
+  builder: (yargs) => {
+    return yargs
+      .option("template", {
+        alias: "t",
+        type: "string",
+        describe:
+          "string; currently a placeholder and is not used by this command (module type is always prompted interactively)",
+        demandOption: false,
+      })
+      .positional("name", {
+        type: "string",
+        describe:
+          "string; module name used only for display in the guided flow (actual generation is implemented later)",
+        default: "my-module",
+      })
+      .example(
+        "orderly create module",
+        "Run guided module creation (prompt for module type)",
+      )
+      .example(
+        "orderly create module --name my-module",
+        "Provide a module name (still prompts for module type)",
+      );
+  },
+  handler: async (argv) => {
+    heading("Create a New Module");
+    info("This command will guide you through creating a new module.\n");
+
+    // Module type: use argv or prompt
+    const moduleType = await select("Select module type:", MODULE_TYPES, 0);
+
+    console.log("\n--- Module Creation Details ---");
+    console.log("Module name:", argv.name || "my-module");
+    console.log("Module type:", moduleType);
+    console.log("-----------------------------\n");
+
+    success("Module creation flow completed!");
+    success(`Module: ${argv.name || "my-module"}`);
+    success(`Type: ${moduleType}`);
+    console.log("\nNote: Actual file generation will be implemented later.");
+  },
+};

package/src/commands/create/plugin.js

@@ -0,0 +1,270 @@
+const {
+  generateFromTemplate,
+  toPascalCase,
+  toKebabCase,
+  toCamelCase,
+  validateName,
+} = require("../../internal/templateGenerator");
+const {
+  input,
+  select,
+  confirm,
+  heading,
+  info,
+  success,
+  error,
+  warn,
+} = require("../../shared");
+const { INTERCEPTOR_TARGETS } = require("../../internal/constants");
+const { generateManifest } = require("../../internal/manifest");
+const {
+  maybePrintOrderlyDevEnvironmentHints,
+} = require("../../internal/orderlySdkDocsMcpDetect");
+const path = require("path");
+
+const TEMPLATE_REPO = "OrderlyNetwork/orderly-plugin-template";
+
+/**
+ * Validate npm package name for scoped and unscoped formats.
+ * Keep this check intentionally strict to prevent publishing failures.
+ * @param {string} name
+ * @returns {boolean}
+ */
+function isValidNpmPackageName(name) {
+  if (!name || typeof name !== "string") {
+    return false;
+  }
+  const scoped = /^@[a-z0-9][a-z0-9-._]*\/[a-z0-9][a-z0-9-._]*$/;
+  const unscoped = /^[a-z0-9][a-z0-9-._]*$/;
+  return scoped.test(name) || unscoped.test(name);
+}
+
+/**
+ * Build a npm-compliant package name before template rendering.
+ * Prefer pluginId so users can control the final published package name.
+ * @param {string} pluginId
+ * @param {string} pluginName
+ * @returns {string}
+ */
+function buildNpmName(pluginId, pluginName) {
+  const candidate = typeof pluginId === "string" ? pluginId.trim() : "";
+  if (isValidNpmPackageName(candidate)) {
+    return candidate;
+  }
+  return toKebabCase(pluginName);
+}
+
+// Build template variables from user answers
+function buildVars(pluginName, pluginId, interceptorTarget, npmName) {
+  return {
+    name: pluginName,
+    pluginName,
+    pluginId,
+    npmName,
+    pluginIdCamel: toCamelCase(pluginId),
+    interceptorTarget,
+    pluginVersion: "1.0.0",
+    date: new Date().toISOString().split("T")[0],
+  };
+}
+
+// Interactive prompts
+async function promptPluginName(existing) {
+  let name;
+  let validation;
+  do {
+    name = await input("Enter plugin name:", existing || "");
+    name = toPascalCase(name);
+    validation = validateName(name);
+    if (!validation.valid) {
+      console.log(`  ${validation.error}`);
+    }
+  } while (!validation.valid);
+  return name;
+}
+
+async function promptPluginId(pluginName, existing) {
+  const defaultId = toKebabCase(pluginName);
+  return await input("Enter plugin ID:", existing || defaultId);
+}
+
+async function promptInterceptorTarget() {
+  return await select("Select interceptor target:", INTERCEPTOR_TARGETS, 0);
+}
+
+async function promptTargetDir(pluginName) {
+  return await input("Enter target directory:", `./${pluginName}`);
+}
+
+// Main command
+module.exports = {
+  command: "plugin",
+  describe: "Create a new plugin from template",
+  builder: (yargs) => {
+    return yargs
+      .option("name", {
+        alias: "n",
+        type: "string",
+        describe:
+          "string; plugin name in PascalCase (input is normalized to PascalCase and validated). Required when `--no-interactive` is set",
+        demandOption: false,
+      })
+      .option("id", {
+        alias: "i",
+        type: "string",
+        describe:
+          "string; plugin ID in kebab-case. If omitted in `--no-interactive` mode, derived from `--name` via toKebabCase()",
+        demandOption: false,
+      })
+      .option("target", {
+        alias: "t",
+        type: "string",
+        describe:
+          "string; output directory. Must be empty or non-existent (template generator throws if non-empty). If omitted in `--no-interactive` mode, defaults to `./<PluginName>`",
+        demandOption: false,
+      })
+      .option("interceptor", {
+        type: "string",
+        choices: INTERCEPTOR_TARGETS,
+        describe:
+          "string; interceptor target (must be one of the listed values). Required when `--no-interactive` is set",
+        demandOption: false,
+      })
+      .option("skip-install", {
+        type: "boolean",
+        describe:
+          "boolean; if true, skip `npm install` in the generated plugin folder",
+        default: false,
+      })
+      .option("no-interactive", {
+        type: "boolean",
+        default: false,
+        describe:
+          "boolean; if true, do not prompt. Requires `--name` and `--interceptor`. If `--id`/`--target` are omitted, they default from `--name`. Prompts are also skipped when `--name --id --interceptor --target` are all provided",
+      })
+      .example(
+        "orderly create plugin --no-interactive --name MyPlugin --id my-plugin --interceptor Trading.Layout.Desktop --target ./my-plugin --skip-install",
+        "Create plugin without prompts (explicit id/target) and skip npm install",
+      )
+      .example(
+        "orderly create plugin",
+        "Interactive mode: prompt for name, id, interceptor, and target directory",
+      );
+  },
+  handler: async (argv) => {
+    heading("Create a New Plugin");
+
+    // Determine if all required params are provided (non-interactive mode)
+    const hasAllParams =
+      argv.name && argv.id && argv.interceptor && argv.target;
+    const nonInteractive = argv["no-interactive"] || hasAllParams;
+
+    if (!nonInteractive) {
+      info(
+        "This command will download a plugin template and customize it for you.\n",
+      );
+    }
+
+    // Gather inputs (from flags or interactive prompts)
+    let pluginName = argv.name ? toPascalCase(argv.name) : null;
+    if (!pluginName) {
+      if (nonInteractive) {
+        error("Missing required option: --name");
+        process.exitCode = 1;
+        return;
+      }
+      pluginName = await promptPluginName("");
+    }
+
+    let pluginId = argv.id || null;
+    if (!pluginId) {
+      if (nonInteractive) {
+        pluginId = toKebabCase(pluginName);
+      } else {
+        pluginId = await promptPluginId(pluginName, "");
+      }
+    }
+
+    let interceptorTarget = argv.interceptor || null;
+    if (!interceptorTarget) {
+      if (nonInteractive) {
+        error("Missing required option: --interceptor");
+        process.exitCode = 1;
+        return;
+      }
+      interceptorTarget = await promptInterceptorTarget();
+    }
+
+    let targetDir = argv.target || null;
+    if (!targetDir) {
+      if (nonInteractive) {
+        targetDir = `./${pluginName}`;
+      } else {
+        targetDir = await promptTargetDir(pluginName);
+      }
+    }
+
+    const skipInstall = argv["skip-install"];
+
+    // Summary
+    console.log("\n--- Plugin Creation Summary ---");
+    console.log(`Plugin Name:       ${pluginName}`);
+    console.log(`Plugin ID:         ${pluginId}`);
+    console.log(`Interceptor Target: ${interceptorTarget}`);
+    console.log(`Target Directory:  ${targetDir}`);
+    console.log(`-----------------------------\n`);
+
+    if (!nonInteractive) {
+      const proceed = await confirm("Proceed with creation?");
+      if (!proceed) {
+        info("Cancelled.");
+        return;
+      }
+    }
+
+    // Build npm-safe package name up front and pass into template variables.
+    const npmName = buildNpmName(pluginId, pluginName);
+    if (npmName !== pluginId) {
+      warn(
+        `Plugin ID "${pluginId}" is not npm-compliant, using "${npmName}" as package name.`,
+      );
+    }
+
+    // Build vars and generate
+    const vars = buildVars(pluginName, pluginId, interceptorTarget, npmName);
+
+    try {
+      await generateFromTemplate({
+        repo: TEMPLATE_REPO,
+        targetDir: path.resolve(targetDir),
+        vars,
+        skipInstall,
+      });
+
+      // Generate orderly manifest file
+      const resolvedDir = path.resolve(targetDir);
+      try {
+        generateManifest(resolvedDir, {
+          pluginId: pluginId,
+          tags: [],
+        });
+        info(
+          `Manifest file generated at ${resolvedDir}/.orderly-manifest.json`,
+        );
+      } catch (manifestErr) {
+        warn(`Could not generate manifest: ${manifestErr.message}`);
+      }
+
+      success(`\nPlugin created successfully!`);
+      info(`Next steps:`);
+      info(`  cd ${targetDir}`);
+      info(`  npm run dev  # or your setup command`);
+      maybePrintOrderlyDevEnvironmentHints(resolvedDir);
+    } catch (err) {
+      error(`Failed to create plugin: ${err.message}`);
+      if (err.stack) {
+        console.error(err.stack);
+      }
+    }
+  },
+};