@shipeasy/openapi 1.6.0 → 2.2.0

package/dist/operations/types.d.ts

@@ -1,138 +0,0 @@
-import { AdminClient } from '../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';
-
-/**
- * Operation registry — the single source of truth that drives BOTH
- * `@shipeasy/cli` (commander subcommands) and `@shipeasy/mcp` (MCP tools),
- * plus their generated docs.
- *
- * Today each surface is hand-maintained: the CLI hand-builds commander
- * commands in `packages/cli/src/commands/*`, the MCP server hand-writes tool
- * JSON Schemas in `packages/mcp/src/tools/schema.ts` and a 60-branch dispatch
- * in `server.ts`, and the percent→basis-points + `JSON.parse(rules)` mapping
- * is written *identically* in both. An Operation collapses that into one
- * definition: the params describe the ergonomic facade once, `run` performs
- * the facade→wire mapping once, and the adapters in this folder project it
- * onto each surface.
- */
-/** Param value kinds. `json` arrives as a JSON string on both surfaces and is parsed by the framework. */
-type ParamType = "string" | "number" | "boolean" | "json";
-interface Param {
-    /** Field name — also the CLI flag (`--<name>`) or positional, and the MCP property key. */
-    name: string;
-    type: ParamType;
-    /** Shown in CLI `--help`, the MCP tool input schema, and generated docs. */
-    description: string;
-    required?: boolean;
-    /** CLI only: render as a positional `<name>` argument instead of a `--flag`. Ignored by MCP. */
-    positional?: boolean;
-    /** Restrict to a fixed set (MCP `enum`, CLI validated in coercion). */
-    enum?: string[];
-}
-interface OpExample {
-    /** Why you'd run this. */
-    note?: string;
-    /** A copy-pasteable command line. */
-    run: string;
-}
-/** Coerced facade input handed to `run` — keys are param names, values coerced by `ParamType`. */
-type OpInput = Record<string, unknown>;
-interface Operation<O = unknown> {
-    /**
-     * Command-path segments BEFORE the verb, e.g. `["release", "flags"]`.
-     * This is the exact CLI nesting; nested resources just add segments
-     * (`["release", "experiments", "universes"]`). Drives grouping + naming.
-     */
-    group: string[];
-    /**
-     * The verb, e.g. `create`. Authored ONCE — every surface name derives from
-     * `group` + `name` so they can never drift:
-     *   id  = `release.flags.create`   (opId   — `.`-joined)
-     *   CLI = `release flags create`   (opCli  — space-joined, the real invocation)
-     *   MCP = `release_flags_create`   (opMcpName — `_`-joined; MCP names can't have spaces)
-     */
-    name: string;
-    /** True for writes — the CLI/MCP adapter enforces `.shipeasy` binding before running. */
-    mutates: boolean;
-    /** One-liner — CLI `.description()` and the docs heading. */
-    summary: string;
-    /** Long-form — the MCP tool `description` and the docs body. */
-    description: string;
-    params: Param[];
-    examples?: OpExample[];
-    /**
-     * The single source of behaviour: coerced facade input → typed AdminClient
-     * call → raw data. Returns data (never prints) so every surface can format
-     * it its own way (CLI table, MCP JSON envelope, …).
-     */
-    run: (client: AdminClient, input: OpInput) => Promise<O>;
-}
-/**
- * Structural subset of commander's `Command`. The CLI adapter targets this so
- * `@shipeasy/openapi` never has to depend on `commander` — commander's real
- * `Command` satisfies it.
- */
-interface CommandLike {
-    command(nameAndArgs: string): CommandLike;
-    description(text: string): CommandLike;
-    option(flags: string, description?: string, defaultValue?: unknown): CommandLike;
-    action(fn: (...args: unknown[]) => void | Promise<void>): CommandLike;
-}
-/** Everything the CLI surface injects so the adapter stays free of process/chalk/IO. */
-interface CliContext {
-    /** Resolve the typed admin client; `mutates` triggers the `requireBinding` guard. */
-    getClient: (o: {
-        mutates: boolean;
-        projectOverride?: string;
-    }) => AdminClient;
-    /** Print machine output (`--json`). */
-    printJson: (data: unknown) => void;
-    /** Print human output for a successful op (table / one-liner). */
-    printResult: (op: Operation, data: unknown, input: OpInput) => void;
-    /** Terminal error handler (prints + exits). */
-    onError: (e: unknown) => void;
-}
-type Named = Pick<Operation, "group" | "name">;
-/** Stable id, e.g. `release.flags.create`. */
-declare const opId: (op: Named) => string;
-/** MCP tool name, e.g. `release_flags_create` — the CLI path with `_` for each space. */
-declare const opMcpName: (op: Named) => string;
-/** CLI invocation, e.g. `release flags create` (full command path). */
-declare const opCli: (op: Named) => string;
-/** Plain MCP `Tool` shape — structurally compatible with `@modelcontextprotocol/sdk`'s `Tool`. */
-interface McpTool {
-    name: string;
-    description: string;
-    inputSchema: {
-        type: "object";
-        required?: string[];
-        properties: Record<string, {
-            type: string;
-            description?: string;
-            enum?: string[];
-        }>;
-    };
-}
-
-export { type CliContext, type CommandLike, type McpTool, type OpExample, type OpInput, type Operation, type Param, type ParamType, opCli, opId, opMcpName };

package/dist/operations/types.js

@@ -1,9 +0,0 @@
-// 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(" ");
-export {
-  opCli,
-  opId,
-  opMcpName
-};

package/dist/operations/universes.d.ts

@@ -1,28 +0,0 @@
-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 universeOperations: Operation[];
-
-export { universeOperations };

package/dist/operations/universes.js

@@ -1,93 +0,0 @@
-// src/transport.ts
-var ApiError = class extends Error {
-  constructor(message, status) {
-    super(message);
-    this.status = status;
-    this.name = "ApiError";
-  }
-  status;
-};
-
-// src/operations/util.ts
-var str = (i, k) => i[k] === void 0 ? void 0 : i[k];
-
-// src/operations/universes.ts
-var GROUP = ["release", "experiments", "universes"];
-function parseHoldout(raw) {
-  if (raw === void 0 || raw === "" || raw === "null") return null;
-  const [lo, hi] = raw.split(",").map((s) => Number(s.trim()));
-  if (!Number.isFinite(lo) || !Number.isFinite(hi)) {
-    throw new ApiError("holdout must be 'lo,hi' integers in [0,9999]", 400);
-  }
-  return [lo, hi];
-}
-var universeOperations = [
-  {
-    group: GROUP,
-    name: "list",
-    mutates: false,
-    summary: "List universes",
-    description: "Return every experiment universe (allocation %, holdout %).",
-    params: [],
-    examples: [{ run: "shipeasy release experiments universes list" }],
-    run: (client) => client.universes.listAll()
-  },
-  {
-    group: GROUP,
-    name: "create",
-    mutates: true,
-    summary: "Create a universe",
-    description: "Create an experiment universe (container + optional holdout).",
-    params: [
-      { name: "name", type: "string", description: "Universe name.", required: true, positional: true },
-      { name: "unitType", type: "string", description: "Unit type (e.g. user_id, account_id). Defaults to user_id." },
-      { name: "holdout", type: "string", description: "Holdout range as 'lo,hi' (0\u20139999); omit for no holdout." }
-    ],
-    examples: [
-      { note: "Default user_id unit, no holdout", run: "shipeasy release experiments universes create web" },
-      { note: "Holdout 0\u2013999, keyed on account_id", run: "shipeasy release experiments universes create web --unit-type account_id --holdout 0,999" }
-    ],
-    run: (client, i) => client.universes.create({
-      name: i.name,
-      unit_type: str(i, "unitType") ?? "user_id",
-      holdout_range: parseHoldout(str(i, "holdout"))
-    })
-  },
-  {
-    group: GROUP,
-    name: "update",
-    mutates: true,
-    summary: "Update a universe's holdout range",
-    description: "Update the holdout range. Pass 'null' to clear the holdout.",
-    params: [
-      { name: "name", type: "string", description: "Universe name.", required: true, positional: true },
-      { name: "holdout", type: "string", description: "Holdout range as 'lo,hi' (0\u20139999), or 'null' to clear." }
-    ],
-    examples: [
-      { note: "Set a 5% holdout", run: "shipeasy release experiments universes update web --holdout 0,499" },
-      { note: "Clear the holdout", run: "shipeasy release experiments universes update web --holdout null" }
-    ],
-    run: async (client, i) => {
-      const x = await client.universes.resolve(i.name);
-      const patch = i.holdout === void 0 ? {} : { holdout_range: parseHoldout(str(i, "holdout")) };
-      return client.universes.update(x.id, patch);
-    }
-  },
-  {
-    group: GROUP,
-    name: "archive",
-    mutates: true,
-    summary: "Archive a universe",
-    description: "Archive (soft-delete) a universe by name.",
-    params: [{ name: "name", type: "string", description: "Universe name.", required: true, positional: true }],
-    examples: [{ run: "shipeasy release experiments universes archive web" }],
-    run: async (client, i) => {
-      const x = await client.universes.resolve(i.name);
-      await client.universes.delete(x.id);
-      return { ok: true, archived: i.name };
-    }
-  }
-];
-export {
-  universeOperations
-};

package/dist/operations/util.d.ts

@@ -1,33 +0,0 @@
-import { 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';
-
-/** Read a coerced number param (already `Number()`-ed by the framework), or undefined. */
-declare const num: (i: OpInput, k: string) => number | undefined;
-/** Read a string param, or undefined. */
-declare const str: (i: OpInput, k: string) => string | undefined;
-/** Read a boolean param, or undefined. */
-declare const bool: (i: OpInput, k: string) => boolean | undefined;
-
-export { bool, num, str };

package/dist/operations/util.js

@@ -1,9 +0,0 @@
-// src/operations/util.ts
-var num = (i, k) => i[k] === void 0 ? void 0 : i[k];
-var str = (i, k) => i[k] === void 0 ? void 0 : i[k];
-var bool = (i, k) => i[k] === void 0 ? void 0 : i[k];
-export {
-  bool,
-  num,
-  str
-};

package/dist/resources/alert-rules.d.ts

@@ -1,50 +0,0 @@
-import { z } from 'zod';
-import { NotificationTarget, alertRuleCreateSchema, alertRuleUpdateSchema } from '../schemas/alert-rules.js';
-import { Transport } from '../transport.js';
-
-type AlertRuleCreateInput = z.input<typeof alertRuleCreateSchema>;
-type AlertRuleUpdateInput = z.input<typeof alertRuleUpdateSchema>;
-/**
- * One metric-threshold alert rule. The cron evaluates `agg(metric)` over the
- * trailing `windowHours` and raises an alert at `severity` when the value
- * `comparator` `threshold` holds.
- *
- * `metricId` is fixed at create time — there is no update path for it (the
- * metric also pins the aggregation). Tune `threshold`/`comparator`/
- * `windowHours`/`severity`/`name`/`enabled` instead, or delete + recreate to
- * repoint the rule at a different metric.
- */
-interface AlertRule {
-    id: string;
-    name: string;
-    metricId: string;
-    metricName: string | null;
-    comparator: "gt" | "gte" | "lt" | "lte";
-    threshold: number;
-    windowHours: number;
-    severity: "danger" | "warn" | "info";
-    enabled: boolean;
-    /** Delivery target for this rule's alert; null = use project default. */
-    notify: NotificationTarget | null;
-    createdAt: string;
-    updatedAt: string;
-}
-interface AlertRulesClient {
-    /** All alert rules for the bound project (the list endpoint is not paginated). */
-    list(): Promise<AlertRule[]>;
-    /** Resolve a rule by exact id, unique id-prefix, or exact (unique) name. */
-    resolve(idOrName: string): Promise<AlertRule>;
-    create(input: AlertRuleCreateInput): Promise<{
-        id: string;
-    }>;
-    /** Patch tunable knobs. `metricId` is rejected by the schema (immutable). */
-    update(id: string, input: AlertRuleUpdateInput): Promise<{
-        id: string;
-    }>;
-    delete(id: string): Promise<{
-        ok: true;
-    }>;
-}
-declare function alertRulesClient(t: Transport): AlertRulesClient;
-
-export { type AlertRule, type AlertRuleCreateInput, type AlertRuleUpdateInput, type AlertRulesClient, alertRulesClient };

package/dist/resources/alert-rules.js

@@ -1,75 +0,0 @@
-// src/schemas/alert-rules.ts
-import { z } from "zod";
-var ALERT_COMPARATORS = ["gt", "gte", "lt", "lte"];
-var ALERT_SEVERITIES = ["danger", "warn", "info"];
-var notificationTargetSchema = z.object({
-  slackChannel: z.object({
-    id: z.string().min(1).describe("Slack channel id (e.g. C0123ABCD)."),
-    name: z.string().min(1).describe("Slack channel name (without the leading #).")
-  }).nullish().describe("Slack channel to post this rule's alert to. Requires a Slack connector."),
-  email: z.string().email().nullish().describe("Email address to notify for this rule (overrides the default recipient).")
-}).strict();
-var alertRuleCreateSchema = z.object({
-  name: z.string().min(1).max(120).describe("Human label for the rule, shown on the alert and the rules list."),
-  metricId: z.string().min(1).describe("Id of the metric to evaluate."),
-  comparator: z.enum(ALERT_COMPARATORS).describe("How the metric value is compared to the threshold (gt/gte/lt/lte)."),
-  threshold: z.number().finite().describe("Threshold the metric value is compared against."),
-  windowHours: z.number().int().min(1).max(720).default(24).describe("Lookback window (hours) the metric is aggregated over. 1\u2013720."),
-  severity: z.enum(ALERT_SEVERITIES).default("warn").describe("Severity of the raised alert."),
-  enabled: z.boolean().default(true).describe("Whether the rule is evaluated by the cron."),
-  notify: notificationTargetSchema.nullish().describe("Where to deliver this rule's alert (Slack channel and/or email target).")
-}).strict();
-var alertRuleUpdateSchema = z.object({
-  name: z.string().min(1).max(120),
-  comparator: z.enum(ALERT_COMPARATORS),
-  threshold: z.number().finite(),
-  windowHours: z.number().int().min(1).max(720),
-  severity: z.enum(ALERT_SEVERITIES),
-  enabled: z.boolean(),
-  notify: notificationTargetSchema.nullish()
-}).partial().strict();
-
-// src/transport.ts
-var ApiError = class extends Error {
-  constructor(message, status) {
-    super(message);
-    this.status = status;
-    this.name = "ApiError";
-  }
-  status;
-};
-
-// src/resources/alert-rules.ts
-var BASE = "/api/admin/alert-rules";
-function alertRulesClient(t) {
-  async function list() {
-    return t.request("GET", BASE);
-  }
-  async function resolve(idOrName) {
-    const all = await list();
-    const byId = all.find((r) => r.id === idOrName);
-    if (byId) return byId;
-    const byPrefix = all.filter((r) => r.id.startsWith(idOrName));
-    if (byPrefix.length === 1) return byPrefix[0];
-    if (byPrefix.length > 1)
-      throw new ApiError(`Alert rule id prefix '${idOrName}' is ambiguous`, 400);
-    const byName = all.filter((r) => r.name === idOrName);
-    if (byName.length === 1) return byName[0];
-    if (byName.length > 1)
-      throw new ApiError(
-        `Alert rule name '${idOrName}' is ambiguous \u2014 pass an id instead`,
-        400
-      );
-    throw new ApiError(`Alert rule '${idOrName}' not found`, 404);
-  }
-  return {
-    list,
-    resolve,
-    create: (input) => t.request("POST", BASE, alertRuleCreateSchema.parse(input)),
-    update: (id, input) => t.request("PATCH", `${BASE}/${id}`, alertRuleUpdateSchema.parse(input)),
-    delete: (id) => t.request("DELETE", `${BASE}/${id}`)
-  };
-}
-export {
-  alertRulesClient
-};

package/dist/resources/attributes.d.ts

@@ -1,19 +0,0 @@
-import { Transport } from '../transport.js';
-
-/**
- * Targeting attributes — the auto-inferred user-attribute schema the dashboard
- * surfaces for gate/experiment targeting. Read-only; this exists so the typed
- * `attributes list` op can replace the `attributes` kind of the old MCP-only
- * "generic read" (`list_resources`), which is being deleted (see doc 21 §A4.3).
- */
-interface Attribute {
-    name: string;
-    type?: string;
-    [key: string]: unknown;
-}
-interface AttributesClient {
-    list(): Promise<Attribute[]>;
-}
-declare function attributesClient(t: Transport): AttributesClient;
-
-export { type Attribute, type AttributesClient, attributesClient };

package/dist/resources/attributes.js

@@ -1,10 +0,0 @@
-// src/resources/attributes.ts
-var BASE = "/api/admin/attributes";
-function attributesClient(t) {
-  return {
-    list: () => t.request("GET", BASE)
-  };
-}
-export {
-  attributesClient
-};