@docyrus/docyrus 0.0.1 → 0.0.2

package/README.md

@@ -97,6 +97,17 @@ Download current tenant OpenAPI spec:
 docyrus discover api --json
 ```
 
+Discover from downloaded tenant OpenAPI spec:
+
+```bash
+docyrus discover namespaces --json
+docyrus discover path /v1/users --json
+docyrus discover endpoint /v1/users/me --json
+docyrus discover endpoint [PUT]/v1/users/me/photo --json
+docyrus discover entity UserEntity --json
+docyrus discover search users,UserEntity --json
+```
+
 Work with accounts and tenants:
 
 ```bash

package/main.js

@@ -39952,7 +39952,7 @@ function buildInputSchema(args, env, options) {
 // package.json
 var package_default = {
   name: "@docyrus/docyrus",
-  version: "0.0.1",
+  version: "0.0.2",
   private: false,
   description: "Docyrus API CLI",
   main: "./main.js",
@@ -40752,6 +40752,185 @@ function createDsCli(dependencies) {
 }
 
 // src/commands/discoverCommands.ts
+var import_promises2 = require("node:fs/promises");
+var SUPPORTED_HTTP_METHODS2 = [
+  "GET",
+  "POST",
+  "PUT",
+  "PATCH",
+  "DELETE",
+  "HEAD",
+  "OPTIONS",
+  "TRACE"
+];
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+function isEnoentError(error48) {
+  return typeof error48 === "object" && error48 !== null && "code" in error48 && error48.code === "ENOENT";
+}
+function normalizePathInput(pathValue) {
+  const trimmed = pathValue.trim();
+  if (!trimmed) {
+    throw new UserInputError("Path is required.");
+  }
+  return trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+}
+function buildPathCandidates(pathValue) {
+  const normalized = normalizePathInput(pathValue);
+  const candidates = /* @__PURE__ */ new Set([normalized]);
+  if (normalized === "/v1") {
+    candidates.add("/");
+  } else if (normalized.startsWith("/v1/")) {
+    candidates.add(normalized.substring(3));
+  } else {
+    candidates.add(`/v1${normalized}`);
+  }
+  return Array.from(candidates.values());
+}
+function toOutputPath(pathValue) {
+  const normalized = normalizePathInput(pathValue);
+  if (normalized === "/") {
+    return "/v1";
+  }
+  if (normalized.startsWith("/v1/") || normalized === "/v1") {
+    return normalized;
+  }
+  return `/v1${normalized}`;
+}
+function parseEndpointSelector(input) {
+  const trimmed = input.trim();
+  if (!trimmed) {
+    throw new UserInputError("Endpoint selector is required.");
+  }
+  const methodPathMatch = trimmed.match(/^\[([a-z]+)\](\/.*)$/i);
+  if (!methodPathMatch) {
+    return {
+      path: trimmed,
+      method: "GET"
+    };
+  }
+  return {
+    method: methodPathMatch[1].toUpperCase(),
+    path: methodPathMatch[2]
+  };
+}
+function getPaths(document) {
+  const rawPaths = document.paths;
+  return isRecord(rawPaths) ? rawPaths : {};
+}
+function getEntities(document) {
+  const components = isRecord(document.components) ? document.components : null;
+  if (components && isRecord(components.schemas)) {
+    return components.schemas;
+  }
+  const definitions = document.definitions;
+  if (isRecord(definitions)) {
+    return definitions;
+  }
+  return {};
+}
+function extractNamespaces(paths) {
+  const namespaces = /* @__PURE__ */ new Set();
+  for (const path3 of Object.keys(paths)) {
+    const segments = path3.split("/").map((item) => item.trim()).filter((item) => item.length > 0);
+    if (segments.length === 0) {
+      continue;
+    }
+    const namespace = segments[0] === "v1" ? segments[1] : segments[0];
+    if (namespace) {
+      namespaces.add(`/v1/${namespace}`);
+    }
+  }
+  return Array.from(namespaces.values()).sort((left, right) => left.localeCompare(right));
+}
+function getPathOperation(pathItem, method) {
+  if (!isRecord(pathItem)) {
+    return null;
+  }
+  const normalizedMethod = method.toLowerCase();
+  const operation = pathItem[normalizedMethod];
+  return isRecord(operation) ? operation : null;
+}
+function toEndpointMethodEntries(paths, pathFilter) {
+  const entries = [];
+  const sortedPaths = Object.keys(paths).filter(pathFilter).sort((left, right) => left.localeCompare(right));
+  for (const path3 of sortedPaths) {
+    const pathItem = paths[path3];
+    if (!isRecord(pathItem)) {
+      continue;
+    }
+    for (const method of SUPPORTED_HTTP_METHODS2) {
+      const operation = getPathOperation(pathItem, method);
+      if (!operation) {
+        continue;
+      }
+      const descriptionValue = operation.description;
+      const summaryValue = operation.summary;
+      const description = typeof descriptionValue === "string" ? descriptionValue : typeof summaryValue === "string" ? summaryValue : void 0;
+      entries.push({
+        path: toOutputPath(path3),
+        method,
+        description
+      });
+    }
+  }
+  return entries;
+}
+function parseOpenApiDocument(raw) {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error48) {
+    throw new UserInputError("Stored OpenAPI spec is invalid JSON. Run 'docyrus discover api' to re-download.", {
+      cause: error48
+    });
+  }
+  if (!isRecord(parsed)) {
+    throw new UserInputError("Stored OpenAPI spec must be a JSON object. Run 'docyrus discover api' to re-download.");
+  }
+  return parsed;
+}
+async function loadOpenApiSpec(dependencies, tenantId) {
+  let filePath = dependencies.tenantOpenApiService.getTenantOpenApiFilePath(tenantId);
+  let downloaded = false;
+  let sourceUrl;
+  let content;
+  try {
+    content = await (0, import_promises2.readFile)(filePath, "utf8");
+  } catch (error48) {
+    if (!isEnoentError(error48)) {
+      throw new UserInputError("Failed to read downloaded OpenAPI spec file.", {
+        filePath,
+        cause: error48
+      });
+    }
+    const downloadResult = await dependencies.tenantOpenApiService.downloadTenantOpenApi(tenantId);
+    downloaded = true;
+    sourceUrl = downloadResult.sourceUrl;
+    filePath = downloadResult.filePath;
+    content = await (0, import_promises2.readFile)(filePath, "utf8");
+  }
+  return {
+    filePath,
+    downloaded,
+    sourceUrl,
+    document: parseOpenApiDocument(content)
+  };
+}
+async function withActiveTenantSpec(dependencies) {
+  const apiBaseUrl = await dependencies.environmentConfigService.getActiveApiBaseUrl();
+  const activeProfile = await dependencies.authStore.getActiveProfile(apiBaseUrl);
+  if (!activeProfile) {
+    throw new AuthSessionError("No active session found. Run 'docyrus auth login'.");
+  }
+  const spec = await loadOpenApiSpec(dependencies, activeProfile.tenantId);
+  return {
+    apiBaseUrl,
+    activeProfile,
+    spec
+  };
+}
 function createDiscoverCli(dependencies) {
   const discoverCli = Cli_exports.create("discover", {
     description: "Discovery commands",
@@ -40778,6 +40957,154 @@ function createDiscoverCli(dependencies) {
       });
     }
   });
+  discoverCli.command("namespaces", {
+    description: "List API namespaces from active tenant OpenAPI spec",
+    run: async () => {
+      const { apiBaseUrl, spec } = await withActiveTenantSpec(dependencies);
+      const namespaces = extractNamespaces(getPaths(spec.document));
+      return await injectContext({
+        apiBaseUrl,
+        authStore: dependencies.authStore,
+        payload: {
+          namespaces,
+          count: namespaces.length,
+          specFilePath: spec.filePath,
+          downloaded: spec.downloaded,
+          sourceUrl: spec.sourceUrl
+        }
+      });
+    }
+  });
+  discoverCli.command("path", {
+    description: "List endpoints with method and description for matching path prefix",
+    args: external_exports.object({
+      prefix: external_exports.string().min(1).describe("Path prefix, e.g. /v1/users")
+    }),
+    run: async (context) => {
+      const { apiBaseUrl, spec } = await withActiveTenantSpec(dependencies);
+      const paths = getPaths(spec.document);
+      const candidates = buildPathCandidates(context.args.prefix);
+      const endpoints = toEndpointMethodEntries(
+        paths,
+        (path3) => candidates.some((candidate) => path3.startsWith(candidate))
+      );
+      return await injectContext({
+        apiBaseUrl,
+        authStore: dependencies.authStore,
+        payload: {
+          prefix: context.args.prefix,
+          normalizedPrefixes: candidates,
+          endpoints,
+          count: endpoints.length,
+          specFilePath: spec.filePath,
+          downloaded: spec.downloaded,
+          sourceUrl: spec.sourceUrl
+        }
+      });
+    }
+  });
+  discoverCli.command("endpoint", {
+    description: "Return full endpoint object for a path and HTTP method",
+    args: external_exports.object({
+      selector: external_exports.string().min(1).describe("Endpoint selector, e.g. /v1/users/me or [PUT]/v1/users/me/photo")
+    }),
+    run: async (context) => {
+      const { apiBaseUrl, spec } = await withActiveTenantSpec(dependencies);
+      const paths = getPaths(spec.document);
+      const selector = parseEndpointSelector(context.args.selector);
+      const candidates = buildPathCandidates(selector.path);
+      const resolvedPath = candidates.find((candidate) => candidate in paths);
+      if (!resolvedPath) {
+        throw new UserInputError(`Endpoint '${selector.path}' was not found in downloaded OpenAPI spec.`);
+      }
+      if (!SUPPORTED_HTTP_METHODS2.includes(selector.method)) {
+        throw new UserInputError(`Unsupported HTTP method '${selector.method}'.`);
+      }
+      const operation = getPathOperation(paths[resolvedPath], selector.method);
+      if (!operation) {
+        throw new UserInputError(
+          `Method '${selector.method}' is not available for endpoint '${toOutputPath(resolvedPath)}'.`
+        );
+      }
+      return await injectContext({
+        apiBaseUrl,
+        authStore: dependencies.authStore,
+        payload: {
+          requestedSelector: context.args.selector,
+          method: selector.method,
+          resolvedPath: toOutputPath(resolvedPath),
+          endpoint: operation,
+          specFilePath: spec.filePath,
+          downloaded: spec.downloaded,
+          sourceUrl: spec.sourceUrl
+        }
+      });
+    }
+  });
+  discoverCli.command("entity", {
+    description: "Return full entity object by name",
+    args: external_exports.object({
+      name: external_exports.string().min(1).describe("Entity name, e.g. UserEntity")
+    }),
+    run: async (context) => {
+      const { apiBaseUrl, spec } = await withActiveTenantSpec(dependencies);
+      const entities = getEntities(spec.document);
+      const requestedName = context.args.name.trim();
+      if (!(requestedName in entities)) {
+        throw new UserInputError(`Entity '${context.args.name}' was not found in downloaded OpenAPI spec.`);
+      }
+      return await injectContext({
+        apiBaseUrl,
+        authStore: dependencies.authStore,
+        payload: {
+          entityName: requestedName,
+          entity: entities[requestedName],
+          specFilePath: spec.filePath,
+          downloaded: spec.downloaded,
+          sourceUrl: spec.sourceUrl
+        }
+      });
+    }
+  });
+  discoverCli.command("search", {
+    description: "Search endpoint paths and entity names (endpoint results include method and description)",
+    args: external_exports.object({
+      query: external_exports.string().min(1).describe("One or more comma-separated search strings")
+    }),
+    run: async (context) => {
+      const { apiBaseUrl, spec } = await withActiveTenantSpec(dependencies);
+      const terms = context.args.query.split(",").map((term) => term.trim()).filter((term) => term.length > 0);
+      if (terms.length === 0) {
+        throw new UserInputError("Provide at least one non-empty search term.");
+      }
+      const entityNames = Object.keys(getEntities(spec.document));
+      const pathMap = getPaths(spec.document);
+      const results = terms.map((term) => {
+        const loweredTerm = term.toLowerCase();
+        const matchingEndpoints = toEndpointMethodEntries(
+          pathMap,
+          (path3) => path3.toLowerCase().includes(loweredTerm)
+        );
+        const matchingEntities = entityNames.filter((entityName) => entityName.toLowerCase().includes(loweredTerm));
+        return {
+          term,
+          endpoints: matchingEndpoints,
+          entityNames: matchingEntities.sort((left, right) => left.localeCompare(right))
+        };
+      });
+      return await injectContext({
+        apiBaseUrl,
+        authStore: dependencies.authStore,
+        payload: {
+          terms,
+          results,
+          specFilePath: spec.filePath,
+          downloaded: spec.downloaded,
+          sourceUrl: spec.sourceUrl
+        }
+      });
+    }
+  });
   return discoverCli;
 }
 
@@ -40972,7 +41299,7 @@ var ApiClient = class {
 };
 
 // src/services/authSession.ts
-function isRecord(value) {
+function isRecord2(value) {
   return typeof value === "object" && value !== null;
 }
 function extractRecordValue(record2, keys) {
@@ -41271,11 +41598,11 @@ var AuthSessionService = class {
       fetchFn: this.params.fetchFn
     });
     const payload = response.data;
-    const dataCandidate = isRecord(payload) && isRecord(payload.data) ? payload.data : payload;
-    if (!isRecord(dataCandidate)) {
+    const dataCandidate = isRecord2(payload) && isRecord2(payload.data) ? payload.data : payload;
+    if (!isRecord2(dataCandidate)) {
       throw new AuthSessionError("Unable to parse /users/me response.");
     }
-    const tenantCandidate = isRecord(dataCandidate.tenant) ? dataCandidate.tenant : void 0;
+    const tenantCandidate = isRecord2(dataCandidate.tenant) ? dataCandidate.tenant : void 0;
     const userId = extractString(dataCandidate, ["id", "user_id"]);
     const email3 = extractString(dataCandidate, ["email"]);
     const tenantId = tenantCandidate ? extractString(tenantCandidate, ["id"]) : extractString(dataCandidate, ["tenant_id", "tenantId"]);
@@ -41301,13 +41628,13 @@ var AuthSessionService = class {
       fetchFn: this.params.fetchFn
     });
     const payload = response.data;
-    const listCandidate = Array.isArray(payload) ? payload : isRecord(payload) && Array.isArray(payload.data) ? payload.data : null;
+    const listCandidate = Array.isArray(payload) ? payload : isRecord2(payload) && Array.isArray(payload.data) ? payload.data : null;
     if (!listCandidate) {
       throw new AuthSessionError("Unable to parse tenant catalog response.");
     }
     const mapped = [];
     for (const item of listCandidate) {
-      if (!isRecord(item)) {
+      if (!isRecord2(item)) {
         continue;
       }
       const tenantId = extractString(item, ["id", "tenant_id"]);
@@ -41466,7 +41793,7 @@ var AuthSessionService = class {
 };
 
 // src/services/authStore.ts
-var import_promises2 = require("node:fs/promises");
+var import_promises3 = require("node:fs/promises");
 var import_node_path4 = require("node:path");
 function createEmptyState() {
   return {
@@ -41506,7 +41833,7 @@ var AuthStore = class {
   }
   async readState() {
     try {
-      const raw = await (0, import_promises2.readFile)(this.authFilePath, "utf8");
+      const raw = await (0, import_promises3.readFile)(this.authFilePath, "utf8");
       const parsed = JSON.parse(raw);
       const legacy = LegacyAuthSessionSchema.safeParse(parsed);
       if (legacy.success) {
@@ -41543,16 +41870,16 @@ var AuthStore = class {
     }
     const normalized = normalizeState(validated.data);
     const directory = (0, import_node_path4.dirname)(this.authFilePath);
-    await (0, import_promises2.mkdir)(directory, {
+    await (0, import_promises3.mkdir)(directory, {
       recursive: true,
       mode: 448
     });
-    await (0, import_promises2.writeFile)(this.authFilePath, `${JSON.stringify(normalized, null, 2)}
+    await (0, import_promises3.writeFile)(this.authFilePath, `${JSON.stringify(normalized, null, 2)}
 `, {
       encoding: "utf8",
       mode: 384
     });
-    await (0, import_promises2.chmod)(this.authFilePath, 384);
+    await (0, import_promises3.chmod)(this.authFilePath, 384);
   }
   async getActiveProfile(apiBaseUrl) {
     const normalizedApiBaseUrl = normalizeApiBaseUrl(apiBaseUrl);
@@ -41749,14 +42076,14 @@ var AuthStore = class {
     await this.writeState(state);
   }
   async clear() {
-    await (0, import_promises2.rm)(this.authFilePath, {
+    await (0, import_promises3.rm)(this.authFilePath, {
       force: true
     });
   }
 };
 
 // src/services/environmentConfig.ts
-var import_promises3 = require("node:fs/promises");
+var import_promises4 = require("node:fs/promises");
 var import_node_path5 = require("node:path");
 var ENVIRONMENT_ID_ALIASES = {
   "local-development": "dev",
@@ -41843,7 +42170,7 @@ var EnvironmentConfigService = class {
   }
   async readState() {
     try {
-      const raw = await (0, import_promises3.readFile)(this.configFilePath, "utf8");
+      const raw = await (0, import_promises4.readFile)(this.configFilePath, "utf8");
       const parsed = JSON.parse(raw);
       const validated = EnvironmentConfigStateSchema.safeParse(parsed);
       if (!validated.success) {
@@ -41878,16 +42205,16 @@ var EnvironmentConfigService = class {
     }
     const normalized = normalizeState2(validated.data);
     const directory = (0, import_node_path5.dirname)(this.configFilePath);
-    await (0, import_promises3.mkdir)(directory, {
+    await (0, import_promises4.mkdir)(directory, {
       recursive: true,
       mode: 448
     });
-    await (0, import_promises3.writeFile)(this.configFilePath, `${JSON.stringify(normalized, null, 2)}
+    await (0, import_promises4.writeFile)(this.configFilePath, `${JSON.stringify(normalized, null, 2)}
 `, {
       encoding: "utf8",
       mode: 384
     });
-    await (0, import_promises3.chmod)(this.configFilePath, 384);
+    await (0, import_promises4.chmod)(this.configFilePath, 384);
   }
   async getActiveEnvironment() {
     const state = await this.#readStateWithDefaults();
@@ -41953,7 +42280,7 @@ var EnvironmentConfigService = class {
 };
 
 // src/services/tenantOpenApi.ts
-var import_promises4 = require("node:fs/promises");
+var import_promises5 = require("node:fs/promises");
 var import_node_path6 = require("node:path");
 function resolveSourceUrl(tenantId, template) {
   return template.replace("{tenantId}", encodeURIComponent(tenantId));
@@ -41962,6 +42289,14 @@ var TenantOpenApiService = class {
   constructor(params) {
     this.params = params;
   }
+  getTenantOpenApiFilePath(tenantId) {
+    const normalizedTenantId = tenantId.trim();
+    if (!normalizedTenantId) {
+      throw new AuthSessionError("Tenant ID is required to resolve OpenAPI spec path.");
+    }
+    const rootPath = this.params?.rootPath || TENANT_OPENAPI_ROOT_PATH;
+    return (0, import_node_path6.join)(rootPath, normalizedTenantId, "openapi.json");
+  }
   async downloadTenantOpenApi(tenantId) {
     const normalizedTenantId = tenantId.trim();
     if (!normalizedTenantId) {
@@ -41993,18 +42328,17 @@ var TenantOpenApiService = class {
         cause: error48
       });
     }
-    const rootPath = this.params?.rootPath || TENANT_OPENAPI_ROOT_PATH;
-    const filePath = (0, import_node_path6.join)(rootPath, normalizedTenantId, "openapi.json");
-    await (0, import_promises4.mkdir)((0, import_node_path6.dirname)(filePath), {
+    const filePath = this.getTenantOpenApiFilePath(normalizedTenantId);
+    await (0, import_promises5.mkdir)((0, import_node_path6.dirname)(filePath), {
       recursive: true,
       mode: 448
     });
-    await (0, import_promises4.writeFile)(filePath, `${JSON.stringify(parsedContent, null, 2)}
+    await (0, import_promises5.writeFile)(filePath, `${JSON.stringify(parsedContent, null, 2)}
 `, {
       encoding: "utf8",
       mode: 384
     });
-    await (0, import_promises4.chmod)(filePath, 384);
+    await (0, import_promises5.chmod)(filePath, 384);
     return {
       tenantId: normalizedTenantId,
       sourceUrl,
@@ -42021,6 +42355,11 @@ var ROOT_HELP_COMMANDS = [
   { command: "auth accounts list", description: "List saved user accounts" },
   { command: "auth tenants use --tenantId <id>", description: "Switch active tenant for selected user" },
   { command: "discover api", description: "Download active tenant OpenAPI spec" },
+  { command: "discover namespaces", description: "List namespaces from tenant OpenAPI spec" },
+  { command: "discover path <prefix>", description: "List endpoint paths by prefix" },
+  { command: "discover endpoint <path>", description: "Show endpoint object by exact path" },
+  { command: "discover entity <name>", description: "Show entity object by name" },
+  { command: "discover search <terms>", description: "Search in endpoint paths and entity names" },
   { command: "ds list <appSlug> <dataSourceSlug>", description: "List data source items" },
   { command: "apps list", description: "List apps" },
   { command: "curl <path>", description: "Send arbitrary API requests" }