@typeship-ax/cli 0.23.1 → 0.24.0

package/src/resources/deliveries.ts

@@ -90,7 +90,7 @@ export class DeliveriesResource {
       query: {
         limit: params?.limit,
         cursor: params?.cursor,
-        target_id: params?.targetId,
+        target_id: params?.target_id,
       },
       idempotent: true,
       schemaKey: "deliveries.list",
@@ -239,7 +239,7 @@ export interface DeliveriesListParams {
    */
   cursor?: string;
   /** Only Deliveries of this Target. */
-  targetId?: TargetId;
+  target_id?: TargetId;
 }
 
 /** Typed errors `list` can throw. */

package/src/resources/drafts.ts

@@ -58,7 +58,7 @@ export class DraftsResource {
       query: {
         limit: params?.limit,
         cursor: params?.cursor,
-        target_id: params?.targetId,
+        target_id: params?.target_id,
         status: params?.status,
       },
       idempotent: true,
@@ -249,7 +249,7 @@ export interface DraftsListParams {
    */
   cursor?: string;
   /** Only Drafts of this Target. */
-  targetId?: TargetId;
+  target_id?: TargetId;
   /** Only Drafts with this status. */
   status?: DraftStatus;
 }

package/src/resources/generations.ts

@@ -72,8 +72,8 @@ export class GenerationsResource {
       query: {
         limit: params?.limit,
         cursor: params?.cursor,
-        project_id: params?.projectId,
-        target_id: params?.targetId,
+        project_id: params?.project_id,
+        target_id: params?.target_id,
         status: params?.status,
       },
       idempotent: true,
@@ -173,9 +173,9 @@ export interface GenerationsListParams {
    */
   cursor?: string;
   /** Only Generations in this Project. */
-  projectId?: ProjectId;
+  project_id?: ProjectId;
   /** Only Generations of this Target. */
-  targetId?: TargetId;
+  target_id?: TargetId;
   /** Only Generations with this status. */
   status?: GenerationStatus;
 }

package/src/resources/releases.ts

@@ -45,7 +45,7 @@ export class ReleasesResource {
       query: {
         limit: params?.limit,
         cursor: params?.cursor,
-        target_id: params?.targetId,
+        target_id: params?.target_id,
       },
       idempotent: true,
       schemaKey: "releases.list",
@@ -128,7 +128,7 @@ export interface ReleasesListParams {
    */
   cursor?: string;
   /** Only releases of this Target. */
-  targetId?: TargetId;
+  target_id?: TargetId;
 }
 
 /** Typed errors `list` can throw. */

package/src/resources/spec-revisions.ts

@@ -54,7 +54,7 @@ export class SpecRevisionsResource {
       query: {
         limit: params?.limit,
         cursor: params?.cursor,
-        spec_id: params?.specId,
+        spec_id: params?.spec_id,
       },
       idempotent: true,
       schemaKey: "specRevisions.list",
@@ -151,7 +151,7 @@ export interface SpecRevisionsListParams {
    */
   cursor?: string;
   /** Only revisions of this Spec. */
-  specId?: SpecId;
+  spec_id?: SpecId;
 }
 
 /** Typed errors `list` can throw. */

package/src/resources/targets.ts

@@ -84,7 +84,7 @@ export class TargetsResource {
       query: {
         limit: params?.limit,
         cursor: params?.cursor,
-        project_id: params?.projectId,
+        project_id: params?.project_id,
       },
       idempotent: true,
       schemaKey: "targets.list",
@@ -260,7 +260,7 @@ export interface TargetsListParams {
    */
   cursor?: string;
   /** Only Targets in this Project. */
-  projectId?: ProjectId;
+  project_id?: ProjectId;
 }
 
 /** Typed errors `list` can throw. */

package/src/table.ts

@@ -0,0 +1,167 @@
+/**
+ * `--format table` for the generated CLI: an API result as text for a
+ * person at a terminal. Generated by Typeship — https://typeship.dev
+ *
+ * JSON stays the default and the automation format; this view is opt-in and
+ * lossy by design. Lists become columns chosen by name (identifiers, then
+ * names, then status-like fields) while they fit the terminal width; a single
+ * object becomes one "field  value" line per field in the same order. Cells longer than
+ * MAX_CELL characters end in "…", and the footer names every column or field
+ * that was left out. Pure: no I/O, so tests render without a terminal.
+ */
+
+/** The longest cell before it is cut with "…". */
+export const MAX_CELL = 40;
+/** A single object shows at most this many (flattened) fields. */
+export const MAX_FIELDS = 60;
+
+export interface TableOptions {
+  /** Terminal width in columns; lists add columns until it is used. */
+  width?: number;
+  /** Wraps header text, e.g. in bold when color is on. */
+  heading?: (text: string) => string;
+  /** The array property that holds a collection response's items ({data: [...]}). */
+  collectionField?: string | null;
+  /** The command's resource (shipments), so shipment_id is recognized as the row's identifier. */
+  resource?: string;
+}
+
+type Row = Record<string, unknown>;
+
+const ID_KEYS = new Set(["id", "sid", "uuid", "key", "slug", "code", "symbol", "number", "handle"]);
+const NAME_KEYS = new Set(["name", "display_name", "displayname", "friendly_name", "friendlyname", "title", "label", "email", "username", "login", "to", "from"]);
+const STATUS_KEYS = new Set(["status", "state"]);
+const DESCRIPTOR_KEYS = new Set(["type", "kind", "direction", "enabled", "active", "amount", "currency", "price", "total"]);
+
+/**
+ * Lower is shown first: identifiers, names, status, descriptors, everything
+ * else, dates, then references and URLs. `primaryId` is the row's own
+ * identifier when it is spelled like a reference (shipment_id with no id).
+ */
+function rank(key: string, primaryId: string | undefined): number {
+  const k = key.toLowerCase();
+  if (ID_KEYS.has(k) || key === primaryId) return 0;
+  if (NAME_KEYS.has(k)) return 1;
+  if (STATUS_KEYS.has(k)) return 2;
+  if (DESCRIPTOR_KEYS.has(k)) return 3;
+  if (/(^|_)(created|updated)(_at|_on)?$|^date_|^(created|updated)|At$/.test(key)) return 5;
+  if (/(_id|_sid|Id|_ids|_uri|_url|Url|Uri)$/.test(key) || k === "uri" || k === "url") return 6;
+  return 4;
+}
+
+/** Keys in display order. The resource's own *_id (shipment_id for shipments) counts as the identifier when no id-like key exists. */
+function byRank(keys: string[], resource: string | undefined): string[] {
+  const bare = (text: string) => text.toLowerCase().replace(/[^a-z0-9]/g, "");
+  const own = resource ? bare(resource).replace(/ies$/, "y").replace(/(ses|xes|s)$/, (m) => m === "s" ? "" : m.slice(0, -2)) + "id" : undefined;
+  const primaryId = keys.some((key) => ID_KEYS.has(key.toLowerCase())) ? undefined
+    : keys.find((key) => bare(key) === own) ?? keys.find((key) => /(_id|Id)$/.test(key));
+  return keys.map((key, index) => ({ key, index, rank: rank(key, primaryId) })).sort((a, b) => a.rank - b.rank || a.index - b.index).map((c) => c.key);
+}
+
+function isPlainObject(value: unknown): value is Row {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function scalar(value: unknown): string {
+  if (value === null || value === undefined) return "";
+  if (typeof value === "string") return value.replace(/\s+/g, " ").trim();
+  if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") return String(value);
+  if (Array.isArray(value)) {
+    if (value.length === 0) return "[]";
+    return value.every((v) => v === null || typeof v !== "object") ? value.map(scalar).join(", ") : "[" + value.length + " items]";
+  }
+  if (isPlainObject(value)) {
+    const entries = Object.entries(value);
+    if (entries.length === 0) return "{}";
+    return entries.every(([, v]) => v === null || typeof v !== "object")
+      ? entries.map(([k, v]) => k + "=" + scalar(v)).join(" ")
+      : "{" + entries.length + " fields}";
+  }
+  return String(value);
+}
+
+function cut(text: string, max: number): string {
+  return text.length > max ? text.slice(0, Math.max(1, max - 1)) + "…" : text;
+}
+
+function pad(text: string, width: number): string {
+  return text + " ".repeat(Math.max(0, width - text.length));
+}
+
+/** The rows and footer lines of a list-shaped result, or null for a single object. */
+function listOf(value: unknown, collectionField: string | null | undefined): { rows: unknown[]; footer: string[] } | null {
+  if (Array.isArray(value)) return { rows: value, footer: [] };
+  if (!isPlainObject(value)) return null;
+  // The CLI's page envelope: {items, hasMore, nextPage?, nextCommand?, request_id?}.
+  if (Array.isArray(value.items) && typeof value.hasMore === "boolean") {
+    return { rows: value.items, footer: typeof value.nextCommand === "string" ? ["More results: " + value.nextCommand] : [] };
+  }
+  if (collectionField && Array.isArray(value[collectionField])) {
+    const rest = Object.entries(value).filter(([k, v]) => k !== collectionField && v !== null && typeof v !== "object");
+    return { rows: value[collectionField] as unknown[], footer: rest.length ? [rest.map(([k, v]) => k + ": " + scalar(v)).join("  ")] : [] };
+  }
+  return null;
+}
+
+function renderRows(rows: unknown[], footer: string[], options: TableOptions): string {
+  const heading = options.heading ?? ((text: string) => text);
+  if (rows.length === 0) return ["No items.", ...footer].join("\n") + "\n";
+  if (!rows.every(isPlainObject)) {
+    return [...rows.map((row) => cut(scalar(row), Math.max(MAX_CELL, options.width ?? 120))), "", rows.length + (rows.length === 1 ? " item" : " items"), ...footer].join("\n") + "\n";
+  }
+  const keys: string[] = [];
+  for (const row of rows as Row[]) for (const key of Object.keys(row)) if (!keys.includes(key)) keys.push(key);
+  const ordered = byRank(keys, options.resource);
+  const width = Math.max(40, options.width ?? 120);
+  const shown: { key: string; width: number }[] = [];
+  let used = 0;
+  for (const key of ordered) {
+    const cells = (rows as Row[]).map((row) => cut(scalar(row[key]), MAX_CELL));
+    // A column empty in every row says nothing.
+    if (cells.every((cell) => cell === "")) continue;
+    const columnWidth = Math.max(Math.min(key.length, MAX_CELL), ...cells.map((cell) => cell.length));
+    if (shown.length > 0 && used + 2 + columnWidth > width) continue;
+    shown.push({ key, width: columnWidth });
+    used += (shown.length > 1 ? 2 : 0) + columnWidth;
+  }
+  const line = (cells: string[]) => cells.map((cell, i) => i === cells.length - 1 ? cell : pad(cell, shown[i]!.width)).join("  ").trimEnd();
+  const lines = [
+    heading(line(shown.map((c) => cut(c.key.toUpperCase(), c.width)))),
+    ...(rows as Row[]).map((row) => line(shown.map((c) => cut(scalar(row[c.key]), MAX_CELL)))),
+    "",
+  ];
+  const hidden = ordered.filter((key) => !shown.some((c) => c.key === key));
+  lines.push(rows.length + (rows.length === 1 ? " item" : " items") + (hidden.length ? "; not shown: " + hidden.join(", ") : ""));
+  return [...lines, ...footer].join("\n") + "\n";
+}
+
+/** One object as "field  value" lines, identifiers and status first; nested objects flatten to dotted paths. */
+function renderObject(value: Row, options: TableOptions): string {
+  const fields: [string, string][] = [];
+  const walk = (object: Row, prefix: string, depth: number) => {
+    const keys = depth === 0 ? byRank(Object.keys(object), options.resource) : Object.keys(object);
+    for (const key of keys) {
+      const v = object[key];
+      const path = prefix + key;
+      if (isPlainObject(v) && depth < 2 && Object.keys(v).length > 0) walk(v, path + ".", depth + 1);
+      else fields.push([path, scalar(v)]);
+    }
+  };
+  walk(value, "", 0);
+  if (fields.length === 0) return "No fields.\n";
+  const heading = options.heading ?? ((text: string) => text);
+  const shown = fields.slice(0, MAX_FIELDS);
+  const keyWidth = Math.min(MAX_CELL, Math.max(...shown.map(([key]) => key.length)));
+  const valueWidth = Math.max(MAX_CELL, (options.width ?? 120) - keyWidth - 2);
+  const lines = shown.map(([key, text]) => (heading(pad(cut(key, keyWidth), keyWidth)) + "  " + cut(text, valueWidth)).trimEnd());
+  if (fields.length > shown.length) lines.push("", (fields.length - shown.length) + " more fields not shown; use --format json or --fields.");
+  return lines.join("\n") + "\n";
+}
+
+/** The text --format table prints for a result that would otherwise print as JSON. */
+export function renderTable(value: unknown, options: TableOptions = {}): string {
+  const list = listOf(value, options.collectionField);
+  if (list) return renderRows(list.rows, list.footer, options);
+  if (isPlainObject(value)) return renderObject(value, options);
+  return scalar(value) + "\n";
+}

package/src/type-docs.ts

@@ -0,0 +1,205 @@
+/**
+ * Named input types for the docs surfaces (MCP read_docs, the CLI's docs
+ * command): a type's reference by name, and an argument path such as
+ * "filter.team.key" resolved to its type. Each type is described once with
+ * its fields typed by name, so a lookup is bounded and every type it
+ * mentions can be looked up the same way.
+ */
+
+export interface InputTypeField {
+  /** As an agent writes it: a type name, string[], "a"|"b", object. */
+  type: string;
+  required?: true;
+  description?: string;
+  default?: unknown;
+  deprecated?: true;
+}
+
+export interface InputTypeDoc {
+  description?: string;
+  /** An input object's fields. */
+  fields?: Record<string, InputTypeField>;
+  /** An enum's values. */
+  values?: unknown[];
+  /** A union's member types. */
+  variants?: string[];
+}
+
+export interface InputTypes {
+  types: Record<string, InputTypeDoc>;
+  /** Per tool, each argument whose type is (or contains) a named type. */
+  args: Record<string, Record<string, string>>;
+}
+
+/** Enum values a type page lists before a count. */
+const TYPE_ENUM_VALUES = 200;
+
+/** One line of prose: links reduced to their text. */
+function prose(text: string | undefined): string {
+  return (text ?? "").replace(/\[([^\]]*)\]\([^)]*\)/g, "$1").replace(/\s+/g, " ").trim();
+}
+
+/** The table's type names an expression mentions, in order. */
+export function namedTypesIn(table: InputTypes | undefined, expression: string | undefined): string[] {
+  if (!table || !expression) return [];
+  return [...new Set(expression.split(/[|()[\]\s]+/).filter((part) => Object.hasOwn(table.types, part)))];
+}
+
+/** The one input object an expression names (IssueFilter, IssueFilter[]),
+ * whose fields a path continues into. */
+function objectTypeOf(table: InputTypes, expression: string | undefined): string | undefined {
+  const objects = namedTypesIn(table, expression).filter((name) => table.types[name]!.fields);
+  return objects.length === 1 ? objects[0] : undefined;
+}
+
+/** A type by exact name, else by a case-insensitive match. */
+export function findInputType(table: InputTypes | undefined, name: string): string | undefined {
+  if (!table) return undefined;
+  if (Object.hasOwn(table.types, name)) return name;
+  const lower = name.toLowerCase();
+  return Object.keys(table.types).find((candidate) => candidate.toLowerCase() === lower);
+}
+
+function fieldLine(name: string, field: InputTypeField): string {
+  const extras = [
+    ...(field.required ? ["required"] : []),
+    ...(field.default !== undefined ? ["default " + JSON.stringify(field.default)] : []),
+    ...(field.deprecated ? ["deprecated"] : []),
+  ];
+  const description = prose(field.description);
+  return "  " + name + " (" + field.type + (extras.length ? ", " + extras.join(", ") : "") + ")" + (description ? ": " + description : "");
+}
+
+/** How to read another type, in the caller's own syntax. */
+export type TypeLookupHint = (name: string) => string;
+
+/** A named type's reference: description, then its fields, values or
+ * members, then how to read the named types it mentions. */
+export function inputTypeText(table: InputTypes, name: string, lookup: TypeLookupHint): string {
+  const doc = table.types[name]!;
+  const kind = doc.fields ? "input object" : doc.values ? "enum" : "union";
+  const lines = [name + " (" + kind + ")"];
+  if (doc.description) lines.push(prose(doc.description));
+  const mentioned: string[] = [];
+  if (doc.fields) {
+    const entries = Object.entries(doc.fields);
+    lines.push("", entries.length === 0 ? "No fields." : "Fields (" + entries.length + "):");
+    for (const [field, spec] of entries) {
+      lines.push(fieldLine(field, spec));
+      mentioned.push(...namedTypesIn(table, spec.type));
+    }
+  } else if (doc.values) {
+    const values = doc.values.slice(0, TYPE_ENUM_VALUES).map((value) => JSON.stringify(value));
+    lines.push("", "Values: " + values.join(", ") + (doc.values.length > TYPE_ENUM_VALUES ? ", … " + (doc.values.length - TYPE_ENUM_VALUES) + " more" : ""));
+  } else if (doc.variants) {
+    lines.push("", "One of: " + doc.variants.join(" | "));
+    for (const variant of doc.variants) mentioned.push(...namedTypesIn(table, variant));
+  }
+  const others = [...new Set(mentioned)].filter((other) => other !== name);
+  if (others.length > 0) {
+    lines.push("", "Types used above (" + others.length + "): " + others.join(", ") + ". Read one with " + lookup("<type>") + ".");
+  }
+  return lines.join("\n");
+}
+
+/** A field of an anonymous object in an inline JSON Schema, one level. */
+interface InlineSchema { type?: unknown; properties?: Record<string, InlineSchema>; required?: string[]; items?: InlineSchema; anyOf?: InlineSchema[]; oneOf?: InlineSchema[]; enum?: unknown[]; description?: string }
+
+function inlineObject(schema: InlineSchema | undefined): InlineSchema | undefined {
+  if (!schema || typeof schema !== "object") return undefined;
+  if (schema.properties && typeof schema.properties === "object") return schema;
+  if (schema.items) return inlineObject(schema.items);
+  const variants = schema.anyOf ?? schema.oneOf;
+  if (Array.isArray(variants)) {
+    const objects = variants.map(inlineObject).filter((variant) => variant !== undefined);
+    if (objects.length === 1) return objects[0];
+  }
+  return undefined;
+}
+
+function inlineType(schema: InlineSchema): string {
+  if (Array.isArray(schema.enum)) return schema.enum.filter((value) => value !== null).map((value) => JSON.stringify(value)).join("|");
+  const variants = schema.anyOf ?? schema.oneOf;
+  if (Array.isArray(variants)) return [...new Set(variants.map(inlineType))].filter((t) => t !== "null").join("|") || "null";
+  const types = (Array.isArray(schema.type) ? schema.type : typeof schema.type === "string" ? [schema.type] : []).filter((t) => t !== "null") as string[];
+  if (types.includes("array")) {
+    const inner = schema.items ? inlineType(schema.items) : "any";
+    return (/[| ]/.test(inner) ? "(" + inner + ")" : inner) + "[]";
+  }
+  return types.join("|") || (schema.properties ? "object" : "any");
+}
+
+export type PathLookup =
+  | { ok: true; text: string }
+  | { ok: false; message: string; available: string[] };
+
+/**
+ * What one argument path means: the field's type, whether it is required,
+ * its description, and, when its type is named, that type's reference in
+ * full (a comparator's operators, an enum's values). `root` is an
+ * operation (its tool name, inline input schema, and how the caller names
+ * it) or a named type.
+ */
+export function argumentPathText(
+  table: InputTypes | undefined,
+  root: { tool: string; inputSchema: Record<string, unknown>; label?: string } | { type: string },
+  path: string,
+  lookup: TypeLookupHint,
+): PathLookup {
+  const segments = path.split(".").map((segment) => segment.trim()).filter((segment) => segment.length > 0);
+  if (segments.length === 0) return { ok: false, message: "The path is empty.", available: [] };
+  // Walk the named-type table where the path has a type name, else the
+  // operation's inline schema.
+  let typeName: string | undefined = "type" in root ? root.type : undefined;
+  let inline: InlineSchema | undefined = "type" in root ? undefined : root.inputSchema as InlineSchema;
+  let expression: string | undefined;
+  let field: InputTypeField | undefined;
+  const label = "type" in root ? root.type : root.label ?? root.tool;
+  for (let index = 0; index < segments.length; index += 1) {
+    const segment = segments[index]!;
+    const at = index === 0 ? label : label + " " + segments.slice(0, index).join(".");
+    if (typeName && table) {
+      const fields = table.types[typeName]!.fields ?? {};
+      if (!Object.hasOwn(fields, segment)) return { ok: false, message: at + " (" + typeName + ") has no field \"" + segment + "\".", available: Object.keys(fields) };
+      field = fields[segment]!;
+      expression = field.type;
+      inline = undefined;
+    } else {
+      const object = inlineObject(inline);
+      const properties = object?.properties ?? {};
+      if (!object || !Object.hasOwn(properties, segment)) {
+        return { ok: false, message: object ? at + " has no field \"" + segment + "\"." : at + " is not an object; the path cannot continue past it.", available: Object.keys(properties) };
+      }
+      const child = properties[segment]!;
+      const topLevel = index === 0 && !("type" in root) ? table?.args[root.tool]?.[segment] : undefined;
+      expression = topLevel ?? inlineType(child);
+      field = {
+        type: expression,
+        ...(Array.isArray(object.required) && object.required.includes(segment) ? { required: true as const } : {}),
+        ...(typeof child.description === "string" ? { description: child.description } : {}),
+      };
+      inline = child;
+    }
+    typeName = table ? objectTypeOf(table, expression) : undefined;
+    if (!typeName && index < segments.length - 1 && !inlineObject(inline)) {
+      return { ok: false, message: label + " " + segments.slice(0, index + 1).join(".") + " is " + expression + ", not an object; the path cannot continue past it.", available: [] };
+    }
+  }
+  const lines = [label + " " + segments.join(".") + ": " + field!.type + (field!.required ? " (required)" : "")];
+  const description = prose(field!.description);
+  if (description) lines.push(description);
+  const named = namedTypesIn(table, expression);
+  if (named.length > 0 && table) {
+    for (const name of named) lines.push("", inputTypeText(table, name, lookup));
+  } else {
+    const object = inlineObject(inline);
+    if (object) {
+      const required = new Set(object.required ?? []);
+      lines.push("", "Fields:");
+      for (const [name, child] of Object.entries(object.properties ?? {})) {
+        lines.push(fieldLine(name, { type: inlineType(child), ...(required.has(name) ? { required: true } : {}), ...(child.description ? { description: child.description } : {}) }));
+      }
+    }
+  }
+  return { ok: true, text: lines.join("\n") };
+}