@typeship-ax/cli 0.22.0 → 0.24.0

package/dist/table.js

@@ -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;
+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, primaryId) {
+    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, resource) {
+    const bare = (text) => 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) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function scalar(value) {
+    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, max) {
+    return text.length > max ? text.slice(0, Math.max(1, max - 1)) + "…" : text;
+}
+function pad(text, width) {
+    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, collectionField) {
+    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], footer: rest.length ? [rest.map(([k, v]) => k + ": " + scalar(v)).join("  ")] : [] };
+    }
+    return null;
+}
+function renderRows(rows, footer, options) {
+    const heading = options.heading ?? ((text) => 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 = [];
+    for (const row of rows)
+        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 = [];
+    let used = 0;
+    for (const key of ordered) {
+        const cells = rows.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) => 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.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, options) {
+    const fields = [];
+    const walk = (object, prefix, depth) => {
+        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) => 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, options = {}) {
+    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/dist/type-docs.d.ts

@@ -0,0 +1,61 @@
+/**
+ * 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>>;
+}
+/** The table's type names an expression mentions, in order. */
+export declare function namedTypesIn(table: InputTypes | undefined, expression: string | undefined): string[];
+/** A type by exact name, else by a case-insensitive match. */
+export declare function findInputType(table: InputTypes | undefined, name: string): string | undefined;
+/** 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 declare function inputTypeText(table: InputTypes, name: string, lookup: TypeLookupHint): string;
+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 declare function argumentPathText(table: InputTypes | undefined, root: {
+    tool: string;
+    inputSchema: Record<string, unknown>;
+    label?: string;
+} | {
+    type: string;
+}, path: string, lookup: TypeLookupHint): PathLookup;
+//# sourceMappingURL=type-docs.d.ts.map

package/dist/type-docs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"type-docs.d.ts","sourceRoot":"","sources":["../src/type-docs.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,WAAW,cAAc;IAC7B,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,IAAI,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,UAAU,CAAC,EAAE,IAAI,CAAC;CACnB;AAED,MAAM,WAAW,YAAY;IAC3B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gCAAgC;IAChC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IACxC,wBAAwB;IACxB,MAAM,CAAC,EAAE,OAAO,EAAE,CAAC;IACnB,8BAA8B;IAC9B,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB;AAED,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IACpC,wEAAwE;IACxE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CAC9C;AAUD,+DAA+D;AAC/D,wBAAgB,YAAY,CAAC,KAAK,EAAE,UAAU,GAAG,SAAS,EAAE,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,EAAE,CAGpG;AASD,8DAA8D;AAC9D,wBAAgB,aAAa,CAAC,KAAK,EAAE,UAAU,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAK7F;AAYD,4DAA4D;AAC5D,MAAM,MAAM,cAAc,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;AAEtD;4DAC4D;AAC5D,wBAAgB,aAAa,CAAC,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,GAAG,MAAM,CAyB7F;AA6BD,MAAM,MAAM,UAAU,GAClB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC1B;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;AAExD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,UAAU,GAAG,SAAS,EAC7B,IAAI,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,EAC/F,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,cAAc,GACrB,UAAU,CAyDZ"}

package/dist/type-docs.js

@@ -0,0 +1,174 @@
+/**
+ * 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.
+ */
+/** 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) {
+    return (text ?? "").replace(/\[([^\]]*)\]\([^)]*\)/g, "$1").replace(/\s+/g, " ").trim();
+}
+/** The table's type names an expression mentions, in order. */
+export function namedTypesIn(table, expression) {
+    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, expression) {
+    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, name) {
+    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, field) {
+    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 : "");
+}
+/** 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, name, lookup) {
+    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 = [];
+    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");
+}
+function inlineObject(schema) {
+    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) {
+    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");
+    if (types.includes("array")) {
+        const inner = schema.items ? inlineType(schema.items) : "any";
+        return (/[| ]/.test(inner) ? "(" + inner + ")" : inner) + "[]";
+    }
+    return types.join("|") || (schema.properties ? "object" : "any");
+}
+/**
+ * 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, root, path, lookup) {
+    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 = "type" in root ? root.type : undefined;
+    let inline = "type" in root ? undefined : root.inputSchema;
+    let expression;
+    let field;
+    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 } : {}),
+                ...(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") };
+}