@shipeasy/openapi 1.5.0 → 1.6.0

package/dist/node-context.d.ts

@@ -0,0 +1,37 @@
+interface ConsumerContext {
+    /** SDK token used as `X-SDK-Key`. */
+    token: string;
+    /** Resolved project id used as `X-Project-Id`. */
+    projectId: string;
+    /** Directory that held the `.shipeasy` binding, if any. */
+    boundDir: string | null;
+    /** Path to the XDG config file that supplied the session, if read. */
+    configPath: string;
+    /** Owner email from the session config, if present. */
+    userEmail: string | null;
+    /** True when a `.shipeasy` binding (or `--project`/env override) supplied the project id. */
+    bound: boolean;
+}
+/** XDG config path for the CLI/MCP session (`~/.config/shipeasy/config.json`). */
+declare function configPath(): string;
+/** Walk up from `dir` (like `.git`) to find the nearest `.shipeasy` file. */
+declare function findBoundDir(dir: string): string | null;
+/** The bound project id from the nearest `.shipeasy`, or undefined. */
+declare function getBoundProjectId(dir?: string): string | undefined;
+interface ResolveOptions {
+    /** Explicit `--project` override (highest precedence). */
+    projectOverride?: string;
+    /** Directory to resolve the binding from (defaults to cwd). */
+    cwd?: string;
+}
+/**
+ * Resolve the consumer context once: env overrides → `.shipeasy` binding →
+ * session config. Returns null if there is no usable session token.
+ *
+ * Precedence for the project id: `projectOverride` → `SHIPEASY_PROJECT_ID` →
+ * `.shipeasy` → session default. The token comes from `SHIPEASY_CLI_TOKEN` or
+ * the session config.
+ */
+declare function resolveConsumerContext(opts?: ResolveOptions): ConsumerContext | null;
+
+export { type ConsumerContext, type ResolveOptions, configPath, findBoundDir, getBoundProjectId, resolveConsumerContext };

package/dist/node-context.js

@@ -0,0 +1,56 @@
+// src/node-context.ts
+import { existsSync, readFileSync } from "fs";
+import { homedir } from "os";
+import { dirname, join, resolve } from "path";
+function configPath() {
+  const base = process.env.XDG_CONFIG_HOME || join(homedir(), ".config");
+  return join(base, "shipeasy", "config.json");
+}
+function readJson(path) {
+  if (!existsSync(path)) return null;
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+function findBoundDir(dir) {
+  let cur = resolve(dir);
+  for (; ; ) {
+    if (existsSync(join(cur, ".shipeasy"))) return cur;
+    const parent = dirname(cur);
+    if (parent === cur) return null;
+    cur = parent;
+  }
+}
+function getBoundProjectId(dir = process.cwd()) {
+  const boundDir = findBoundDir(dir);
+  if (!boundDir) return void 0;
+  return readJson(join(boundDir, ".shipeasy"))?.project_id;
+}
+function resolveConsumerContext(opts = {}) {
+  const cwd = opts.cwd ?? process.cwd();
+  const cfgPath = configPath();
+  const cfg = readJson(cfgPath) ?? {};
+  const token = process.env.SHIPEASY_CLI_TOKEN || cfg.cli_token;
+  if (!token) return null;
+  const boundDir = findBoundDir(cwd);
+  const boundId = boundDir ? readJson(join(boundDir, ".shipeasy"))?.project_id : void 0;
+  const envProject = process.env.SHIPEASY_PROJECT_ID;
+  const projectId = opts.projectOverride || envProject || boundId || cfg.project_id;
+  if (!projectId) return null;
+  return {
+    token,
+    projectId,
+    boundDir: boundId ? boundDir : null,
+    configPath: cfgPath,
+    userEmail: cfg.user_email ?? null,
+    bound: Boolean(opts.projectOverride || envProject || boundId)
+  };
+}
+export {
+  configPath,
+  findBoundDir,
+  getBoundProjectId,
+  resolveConsumerContext
+};

package/dist/operations/attributes.d.ts

@@ -0,0 +1,33 @@
+import { Operation } from './types.js';
+import '../resources/index.js';
+import 'zod/v4/core';
+import 'zod';
+import '../resources/attributes.js';
+import '../transport.js';
+import '../resources/i18n.js';
+import '../resources/projects.js';
+import '../resources/ops.js';
+import '../resources/events.js';
+import '../resources/metrics.js';
+import '../resources/alert-rules.js';
+import '../schemas/alert-rules.js';
+import '../resources/killswitches.js';
+import '../schemas/killswitches.js';
+import '../schemas/pagination.js';
+import '../resources/universes.js';
+import '../schemas/universes.js';
+import '../resources/configs.js';
+import '../schemas/configs.js';
+import '../resources/experiments.js';
+import '../schemas/experiments.js';
+import '../resources/gates.js';
+import '../schemas/gates.js';
+
+/**
+ * Attribute operations — `attributes …`. One read-only op so the typed
+ * `attributes_list` MCP tool replaces the `attributes` kind of the deleted
+ * generic-read path (doc 21 §A4.3).
+ */
+declare const attributeOperations: Operation[];
+
+export { attributeOperations };

package/dist/operations/attributes.js

@@ -0,0 +1,16 @@
+// src/operations/attributes.ts
+var attributeOperations = [
+  {
+    group: ["attributes"],
+    name: "list",
+    mutates: false,
+    summary: "List targeting attributes",
+    description: "List the auto-inferred user-attribute schema available for gate/experiment targeting.",
+    params: [],
+    examples: [{ run: "shipeasy attributes list" }],
+    run: (client) => client.attributes.list()
+  }
+];
+export {
+  attributeOperations
+};

package/dist/operations/cli-adapter.d.ts

@@ -0,0 +1,35 @@
+import { CommandLike, Operation, CliContext } from './types.js';
+import '../resources/index.js';
+import 'zod/v4/core';
+import 'zod';
+import '../resources/attributes.js';
+import '../transport.js';
+import '../resources/i18n.js';
+import '../resources/projects.js';
+import '../resources/ops.js';
+import '../resources/events.js';
+import '../resources/metrics.js';
+import '../resources/alert-rules.js';
+import '../schemas/alert-rules.js';
+import '../resources/killswitches.js';
+import '../schemas/killswitches.js';
+import '../schemas/pagination.js';
+import '../resources/universes.js';
+import '../schemas/universes.js';
+import '../resources/configs.js';
+import '../schemas/configs.js';
+import '../resources/experiments.js';
+import '../schemas/experiments.js';
+import '../resources/gates.js';
+import '../schemas/gates.js';
+
+/**
+ * Mount every operation as a commander subcommand under `group`. The CLI passes
+ * its own commander `Command` (which satisfies `CommandLike`) and a `CliContext`
+ * carrying the bits `@shipeasy/openapi` must not own (client resolution, table
+ * formatting, process.exit). Replaces the per-command hand-wiring in
+ * `packages/cli/src/commands/*`.
+ */
+declare function mountOperations(group: CommandLike, ops: Operation[], ctx: CliContext): void;
+
+export { mountOperations };

package/dist/operations/cli-adapter.js

@@ -0,0 +1,91 @@
+// src/transport.ts
+var ApiError = class extends Error {
+  constructor(message, status) {
+    super(message);
+    this.status = status;
+    this.name = "ApiError";
+  }
+  status;
+};
+
+// src/operations/coerce.ts
+function coerceValue(param, raw) {
+  if (raw === void 0 || raw === null) return void 0;
+  switch (param.type) {
+    case "number": {
+      const n = typeof raw === "number" ? raw : Number(raw);
+      if (!Number.isFinite(n)) throw new ApiError(`--${param.name} must be a number`, 400);
+      return n;
+    }
+    case "boolean":
+      return raw === true || raw === "true" || raw === "1";
+    case "json":
+      if (typeof raw !== "string") return raw;
+      try {
+        return JSON.parse(raw);
+      } catch {
+        throw new ApiError(`--${param.name} must be valid JSON`, 400);
+      }
+    case "string":
+    default: {
+      const s = String(raw);
+      if (param.enum && !param.enum.includes(s)) {
+        throw new ApiError(`--${param.name} must be one of: ${param.enum.join(", ")}`, 400);
+      }
+      return s;
+    }
+  }
+}
+function coerceInput(op, raw) {
+  const out = {};
+  for (const param of op.params) {
+    const value = coerceValue(param, raw[param.name]);
+    if (value === void 0) {
+      if (param.required) throw new ApiError(`${param.name} is required`, 400);
+      continue;
+    }
+    out[param.name] = value;
+  }
+  return out;
+}
+
+// src/operations/cli-adapter.ts
+var toKebab = (s) => s.replace(/[A-Z]/g, (m) => `-${m.toLowerCase()}`);
+function commandSignature(op) {
+  const positionals = op.params.filter((p) => p.positional).map((p) => p.required === false ? `[${p.name}]` : `<${p.name}>`);
+  return [op.name, ...positionals].join(" ");
+}
+function mountOperations(group, ops, ctx) {
+  for (const op of ops) {
+    const positionals = op.params.filter((p) => p.positional);
+    const flags = op.params.filter((p) => !p.positional);
+    const cmd = group.command(commandSignature(op)).description(op.summary);
+    for (const p of flags) {
+      cmd.option(`--${toKebab(p.name)} <value>`, p.description);
+    }
+    cmd.option("--json", "Output as JSON");
+    cmd.option("--project <id>", "Project ID override");
+    cmd.action(async (...argv) => {
+      try {
+        const opts = argv.find((a) => a && typeof a === "object" && !Array.isArray(a)) ?? {};
+        const raw = { ...opts };
+        positionals.forEach((p, i) => {
+          raw[p.name] = argv[i];
+        });
+        const input = coerceInput(op, raw);
+        const client = ctx.getClient({
+          mutates: op.mutates,
+          projectOverride: opts.project
+        });
+        const data = await op.run(client, input);
+        if (opts.json) ctx.printJson(data);
+        else ctx.printResult(op, data, input);
+      } catch (e) {
+        ctx.onError(e);
+      }
+    });
+  }
+}
+export {
+  mountOperations
+};

package/dist/operations/coerce.d.ts

@@ -0,0 +1,32 @@
+import { Operation, OpInput } from './types.js';
+import '../resources/index.js';
+import 'zod/v4/core';
+import 'zod';
+import '../resources/attributes.js';
+import '../transport.js';
+import '../resources/i18n.js';
+import '../resources/projects.js';
+import '../resources/ops.js';
+import '../resources/events.js';
+import '../resources/metrics.js';
+import '../resources/alert-rules.js';
+import '../schemas/alert-rules.js';
+import '../resources/killswitches.js';
+import '../schemas/killswitches.js';
+import '../schemas/pagination.js';
+import '../resources/universes.js';
+import '../schemas/universes.js';
+import '../resources/configs.js';
+import '../schemas/configs.js';
+import '../resources/experiments.js';
+import '../schemas/experiments.js';
+import '../resources/gates.js';
+import '../schemas/gates.js';
+
+/**
+ * Build the coerced facade input `run` expects from a raw key→value bag
+ * (commander's merged args+opts, or MCP's `arguments`). Enforces `required`.
+ */
+declare function coerceInput(op: Operation, raw: Record<string, unknown>): OpInput;
+
+export { coerceInput };

package/dist/operations/coerce.js

@@ -0,0 +1,53 @@
+// src/transport.ts
+var ApiError = class extends Error {
+  constructor(message, status) {
+    super(message);
+    this.status = status;
+    this.name = "ApiError";
+  }
+  status;
+};
+
+// src/operations/coerce.ts
+function coerceValue(param, raw) {
+  if (raw === void 0 || raw === null) return void 0;
+  switch (param.type) {
+    case "number": {
+      const n = typeof raw === "number" ? raw : Number(raw);
+      if (!Number.isFinite(n)) throw new ApiError(`--${param.name} must be a number`, 400);
+      return n;
+    }
+    case "boolean":
+      return raw === true || raw === "true" || raw === "1";
+    case "json":
+      if (typeof raw !== "string") return raw;
+      try {
+        return JSON.parse(raw);
+      } catch {
+        throw new ApiError(`--${param.name} must be valid JSON`, 400);
+      }
+    case "string":
+    default: {
+      const s = String(raw);
+      if (param.enum && !param.enum.includes(s)) {
+        throw new ApiError(`--${param.name} must be one of: ${param.enum.join(", ")}`, 400);
+      }
+      return s;
+    }
+  }
+}
+function coerceInput(op, raw) {
+  const out = {};
+  for (const param of op.params) {
+    const value = coerceValue(param, raw[param.name]);
+    if (value === void 0) {
+      if (param.required) throw new ApiError(`${param.name} is required`, 400);
+      continue;
+    }
+    out[param.name] = value;
+  }
+  return out;
+}
+export {
+  coerceInput
+};

package/dist/operations/configs.d.ts

@@ -0,0 +1,28 @@
+import { Operation } from './types.js';
+import '../resources/index.js';
+import 'zod/v4/core';
+import 'zod';
+import '../resources/attributes.js';
+import '../transport.js';
+import '../resources/i18n.js';
+import '../resources/projects.js';
+import '../resources/ops.js';
+import '../resources/events.js';
+import '../resources/metrics.js';
+import '../resources/alert-rules.js';
+import '../schemas/alert-rules.js';
+import '../resources/killswitches.js';
+import '../schemas/killswitches.js';
+import '../schemas/pagination.js';
+import '../resources/universes.js';
+import '../schemas/universes.js';
+import '../resources/configs.js';
+import '../schemas/configs.js';
+import '../resources/experiments.js';
+import '../schemas/experiments.js';
+import '../resources/gates.js';
+import '../schemas/gates.js';
+
+declare const configOperations: Operation[];
+
+export { configOperations };

package/dist/operations/configs.js

@@ -0,0 +1,119 @@
+// src/operations/util.ts
+var str = (i, k) => i[k] === void 0 ? void 0 : i[k];
+
+// src/operations/configs.ts
+var GROUP = ["release", "configs"];
+var configOperations = [
+  {
+    group: GROUP,
+    name: "list",
+    mutates: false,
+    summary: "List all configs",
+    description: "Return every dynamic config (name, schema, last updated).",
+    params: [],
+    examples: [{ run: "shipeasy release configs list" }],
+    run: (client) => client.configs.listAll()
+  },
+  {
+    group: GROUP,
+    name: "get",
+    mutates: false,
+    summary: "Show a config by name",
+    description: "Resolve a config by name and return its full detail (schema + per-env values + drafts).",
+    params: [{ name: "name", type: "string", description: "Config name.", required: true, positional: true }],
+    examples: [{ run: "shipeasy release configs get pricing" }],
+    run: async (client, i) => {
+      const c = await client.configs.resolve(i.name);
+      return client.configs.get(c.id);
+    }
+  },
+  {
+    group: GROUP,
+    name: "create",
+    mutates: true,
+    summary: "Create a config",
+    description: "Create a dynamic config. Configs are JSON objects validated against a JSON Schema (object-only).",
+    params: [
+      { name: "name", type: "string", description: "Config name.", required: true, positional: true },
+      { name: "schema", type: "json", description: "JSON Schema (top-level type=object). Defaults to a permissive object schema." },
+      { name: "value", type: "json", description: "Initial value as a JSON object. Defaults to {}." },
+      { name: "description", type: "string", description: "Human-readable description." }
+    ],
+    examples: [
+      { note: "Permissive schema, empty value", run: "shipeasy release configs create pricing" },
+      { note: "Seed an initial value", run: `shipeasy release configs create pricing --value '{"free_trial_days":14}'` }
+    ],
+    run: (client, i) => client.configs.create({
+      name: i.name,
+      schema: i.schema ?? { type: "object", properties: {}, additionalProperties: true },
+      value: i.value ?? {},
+      ...i.description ? { description: i.description } : {}
+    })
+  },
+  {
+    group: GROUP,
+    name: "update",
+    mutates: true,
+    summary: "Update a config's value (flat, all envs)",
+    description: "Legacy flat value update across all envs. Use draft + publish for per-env staging.",
+    params: [
+      { name: "name", type: "string", description: "Config name.", required: true, positional: true },
+      { name: "value", type: "json", description: "New value (JSON object).", required: true }
+    ],
+    examples: [{ note: "Overwrite the value (all envs)", run: `shipeasy release configs update pricing --value '{"free_trial_days":30}'` }],
+    run: async (client, i) => {
+      const c = await client.configs.resolve(i.name);
+      return client.configs.update(c.id, { value: i.value });
+    }
+  },
+  {
+    group: GROUP,
+    name: "draft",
+    mutates: true,
+    summary: "Save a draft value for one env",
+    description: "Stage a draft value for the given env, to publish later.",
+    params: [
+      { name: "name", type: "string", description: "Config name.", required: true, positional: true },
+      { name: "env", type: "string", description: "Target env (e.g. prod, staging, dev).", required: true },
+      { name: "value", type: "json", description: "Draft value (JSON object).", required: true }
+    ],
+    examples: [{ note: "Stage a prod value", run: `shipeasy release configs draft pricing --env prod --value '{"free_trial_days":30}'` }],
+    run: async (client, i) => {
+      const c = await client.configs.resolve(i.name);
+      return client.configs.saveDraft(c.id, { env: i.env, value: i.value });
+    }
+  },
+  {
+    group: GROUP,
+    name: "publish",
+    mutates: true,
+    summary: "Publish the saved draft for one env",
+    description: "Promote the staged draft for the given env to live.",
+    params: [
+      { name: "name", type: "string", description: "Config name.", required: true, positional: true },
+      { name: "env", type: "string", description: "Target env to publish.", required: true }
+    ],
+    examples: [{ note: "Promote staged draft to prod", run: "shipeasy release configs publish pricing --env prod" }],
+    run: async (client, i) => {
+      const c = await client.configs.resolve(i.name);
+      return client.configs.publish(c.id, { env: str(i, "env") });
+    }
+  },
+  {
+    group: GROUP,
+    name: "archive",
+    mutates: true,
+    summary: "Archive a config",
+    description: "Archive (soft-delete) a config by name.",
+    params: [{ name: "name", type: "string", description: "Config name.", required: true, positional: true }],
+    examples: [{ run: "shipeasy release configs archive pricing" }],
+    run: async (client, i) => {
+      const c = await client.configs.resolve(i.name);
+      await client.configs.delete(c.id);
+      return { ok: true, archived: i.name };
+    }
+  }
+];
+export {
+  configOperations
+};

package/dist/operations/docs.d.ts

@@ -0,0 +1,37 @@
+import { Operation } from './types.js';
+import '../resources/index.js';
+import 'zod/v4/core';
+import 'zod';
+import '../resources/attributes.js';
+import '../transport.js';
+import '../resources/i18n.js';
+import '../resources/projects.js';
+import '../resources/ops.js';
+import '../resources/events.js';
+import '../resources/metrics.js';
+import '../resources/alert-rules.js';
+import '../schemas/alert-rules.js';
+import '../resources/killswitches.js';
+import '../schemas/killswitches.js';
+import '../schemas/pagination.js';
+import '../resources/universes.js';
+import '../schemas/universes.js';
+import '../resources/configs.js';
+import '../schemas/configs.js';
+import '../resources/experiments.js';
+import '../schemas/experiments.js';
+import '../resources/gates.js';
+import '../schemas/gates.js';
+
+/**
+ * Render the registry to Markdown — the "documentation comes along for free"
+ * half of the proposal. Both `cli/scripts/gen-cli-docs.ts` and
+ * `mcp/scripts/gen-mcp-docs.ts` can call this instead of re-describing every
+ * command/tool by hand, so help text, tool descriptions, and the docs site all
+ * derive from the same `summary`/`description`/`params`/`examples`.
+ */
+declare function renderOperationsMarkdown(ops: Operation[], opts?: {
+    title?: string;
+}): string;
+
+export { renderOperationsMarkdown };

package/dist/operations/docs.js

@@ -0,0 +1,39 @@
+// src/operations/types.ts
+var opId = (op) => [...op.group, op.name].join(".");
+var opMcpName = (op) => [...op.group, op.name].join("_");
+var opCli = (op) => [...op.group, op.name].join(" ");
+
+// src/operations/docs.ts
+function renderOperationsMarkdown(ops, opts = {}) {
+  const lines = [];
+  if (opts.title) lines.push(`# ${opts.title}`, "");
+  for (const op of ops) {
+    lines.push(`## \`${opId(op)}\``, "");
+    lines.push(op.summary, "");
+    if (op.description && op.description !== op.summary) lines.push(op.description, "");
+    lines.push(
+      `- **CLI:** \`shipeasy ${opCli(op)}\`  \xB7  **MCP tool:** \`${opMcpName(op)}\`  \xB7  ${op.mutates ? "write (needs project binding)" : "read"}`,
+      ""
+    );
+    if (op.params.length) {
+      lines.push("| Param | Type | Required | Description |", "| --- | --- | --- | --- |");
+      for (const p of op.params) {
+        const kind = p.positional ? `${p.type} (positional)` : p.type;
+        lines.push(`| \`${p.name}\` | ${kind} | ${p.required ? "yes" : "no"} | ${p.description} |`);
+      }
+      lines.push("");
+    }
+    if (op.examples?.length) {
+      lines.push("**Examples**", "");
+      for (const ex of op.examples) {
+        if (ex.note) lines.push(`- ${ex.note}:`);
+        lines.push("```sh", ex.run, "```");
+      }
+      lines.push("");
+    }
+  }
+  return lines.join("\n");
+}
+export {
+  renderOperationsMarkdown
+};

package/dist/operations/events.d.ts

@@ -0,0 +1,28 @@
+import { Operation } from './types.js';
+import '../resources/index.js';
+import 'zod/v4/core';
+import 'zod';
+import '../resources/attributes.js';
+import '../transport.js';
+import '../resources/i18n.js';
+import '../resources/projects.js';
+import '../resources/ops.js';
+import '../resources/events.js';
+import '../resources/metrics.js';
+import '../resources/alert-rules.js';
+import '../schemas/alert-rules.js';
+import '../resources/killswitches.js';
+import '../schemas/killswitches.js';
+import '../schemas/pagination.js';
+import '../resources/universes.js';
+import '../schemas/universes.js';
+import '../resources/configs.js';
+import '../schemas/configs.js';
+import '../resources/experiments.js';
+import '../schemas/experiments.js';
+import '../resources/gates.js';
+import '../schemas/gates.js';
+
+declare const eventOperations: Operation[];
+
+export { eventOperations };