@dotflash/openapi-semantic-generator 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FlaSh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,148 @@
+# OpenAPI-Agent-Sync (oas-agent-sync)
+
+[English](#english) | [한국어](#한국어)
+
+---
+
+<a name="english"></a>
+
+## English
+
+Middleware tool that analyzes code generated by OpenAPI Generator and automatically creates semantic matching documents (`llms.txt`: A unified index mapping API intents, `operationId`, HTTP paths, and actual TypeScript source file locations; `agent.md`: A semantic guide explaining how to interpret `llms.txt`.) optimized for LLM agents.
+
+### 💡 Best Practices for AI Agents
+
+To maximize the effectiveness of this tool, reference the generated files in your AI configuration files (e.g., `.cursorrules`, `claude.md`, `copilot-instructions.md`).
+
+#### Example: `.cursorrules` or `claude.md`
+
+```markdown
+# API Usage Guidelines
+
+Always refer to the following files to understand available APIs and their usage:
+
+- [API Index](openapi/llms.txt)
+- [Agent Guide](openapi/agent.md)
+
+1. Search `llms.txt` for the desired operation.
+2. Read the implementation in the "Source File" path.
+3. Call the API as defined in the source code.
+```
+
+It provides an index and guide that allows LLMs to understand large-scale API code (even 2,500+ lines) at a glance, maximizing agent code comprehension.
+
+### Key Features
+
+- **Middleware Mode**: Analyzes already generated code folders and compares them with OpenAPI specs.
+- **Smart Path Mapping**: Automatically detects actual file locations within generated code (e.g., `typescript-axios`).
+- **URL Support**: Supports direct input from remote OpenAPI JSON/YAML URLs in addition to local files.
+- **Agent Optimized**: Provides LLM-exclusive summaries (`llms.txt`) and interaction guides (`agent.md`).
+
+### Installation
+
+```bash
+npm install -g oas-agent-sync
+```
+
+### Usage
+
+```bash
+npx oas-agent-sync <spec-url-or-path> -o <generated-code-dir> [options]
+```
+
+#### Required Arguments
+
+1. `<spec>`: Path or URL to the OpenAPI spec file (e.g., `https://.../openapi.json`)
+
+#### Options
+
+- `-o, --output <dir>`: Directory where the code is already generated (e.g., `./src/api`)
+- `--api-dir <path>`: Relative path to APIs within the output directory (e.g., `services`)
+
+### Generated Documents
+
+Two core documents are generated to help agents understand the API structure with minimal tokens and start implementation immediately.
+
+1. **llms.txt (Semantic Index)**:
+   - A unified index mapping API intents, `operationId`, HTTP paths, and **actual TypeScript source file locations**.
+   - Agents can see at a glance what functionality to use and which files to read to check types.
+
+2. **agent.md (Agent Interaction Guide)**:
+   - Provides guidelines on how the agent should utilize this package.
+   - Defines procedures for searching via `llms.txt` and implementing by referencing source code.
+
+---
+
+<a name="한국어"></a>
+
+## 한국어
+
+OpenAPI Generator로 생성된 코드들을 분석하여 LLM 에이전트가 활용하기 좋은 시맨틱 매칭 문서(`llms.txt`, `agent.md`)를 자동으로 생성해주는 미들웨어 도구입니다.
+
+2,500라인이 넘는 대규모 API 코드라도 LLM이 한눈에 파악할 수 있는 인덱스와 가이드를 제공하여 에이전트의 코드 이해도를 극대화합니다.
+
+### 핵심 기능
+
+- **Middleware Mode**: 이미 생성된 코드 폴더와 OpenAPI 스펙을 비교 분석하여 문서 생성.
+- **Smart Path Mapping**: `typescript-axios` 등 생성된 코드 내의 실제 파일 위치 자동 탐색.
+- **URL Support**: 로컬 파일뿐만 아니라 원격 OpenAPI JSON/YAML URL 직접 지원.
+- **Agent Optimized**: LLM 전용 요약(`llms.txt`) 및 상세 가이드(`agent.md`) 제공.
+
+### 설치 방법
+
+```bash
+npm install -g oas-agent-sync
+```
+
+### 사용 방법
+
+```bash
+npx oas-agent-sync <spec-url-or-path> -o <generated-code-dir> [options]
+```
+
+#### 필수 인자
+
+1. `<spec>`: OpenAPI 스펙 파일 경로 또는 URL (예: `https://.../openapi.json`)
+
+#### 옵션
+
+- `-o, --output <dir>`: 이미 생성된 코드가 위치한 디렉토리 (예: `./src/api`)
+- `--api-dir <path>`: 출력 디렉토리 내 API 파일이 위치한 상대 경로 (예: `services`)
+
+### 생성되는 문서
+
+에이전트가 최소한의 토큰으로 API 구조를 파악하고 즉시 구현에 들어갈 수 있도록 두 가지 핵심 문서를 생성합니다.
+
+1. **llms.txt (Semantic Index)**:
+   - 전체 API의 용도(Intent), `operationId`, HTTP 경로, 그리고 **실제 TypeScript 소스 파일 위치**가 매핑된 통합 인덱스입니다.
+   - 에이전트는 이 파일을 통해 어떤 기능을 써야 하는지, 그리고 해당 기능의 타입을 확인하기 위해 어떤 파일을 읽어야 하는지 한눈에 파악합니다.
+
+2. **agent.md (에이전트 인터랙션 가이드)**:
+   - `agent.md`: `llms.txt`를 어떻게 해석해야 하는지 설명하는 가이드 문서입니다.
+
+### 💡 AI 에이전트 활용 팁
+
+이 도구의 효과를 극대화하려면, 생성된 파일들을 AI 설정 파일(예: `.cursorrules`, `claude.md`, `copilot-instructions.md`)에 등록하세요.
+
+#### 예시: `.cursorrules` 또는 `claude.md`
+
+```markdown
+# API 사용 가이드라인
+
+사용 가능한 API와 사용법을 파악하기 위해 항상 다음 파일을 참조하세요:
+
+- [API 인덱스](openapi/llms.txt)
+- [에이전트 가이드](openapi/agent.md)
+
+1. `llms.txt`에서 원하는 작업을 검색하세요.
+2. "Source File" 경로에 있는 실제 구현 코드를 읽으세요.
+3. 소스 코드에 정의된 대로 올바르게 API를 호출하세요.
+```
+
+- `llms.txt`를 통한 검색 방법과 소스 코드를 참조하여 구현하는 절차를 정의합니다.
+
+---
+
+## License
+
+MIT

package/dist/chunk-JGV5ULAN.js

@@ -0,0 +1,189 @@
+// src/core/extractor.ts
+import fs from "fs-extra";
+import { parse } from "yaml";
+async function extractMetadata(specPath) {
+  let content;
+  const isUrl = specPath.startsWith("http://") || specPath.startsWith("https://");
+  if (isUrl) {
+    const response = await fetch(specPath);
+    if (!response.ok) {
+      throw new Error(
+        `Failed to fetch OpenAPI spec from ${specPath}: ${response.statusText}`
+      );
+    }
+    content = await response.text();
+  } else {
+    content = await fs.readFile(specPath, "utf-8");
+  }
+  const spec = specPath.endsWith(".yaml") || specPath.endsWith(".yml") || isUrl && !content.trim().startsWith("{") ? parse(content) : JSON.parse(content);
+  const title = spec.info?.title || "API";
+  const description = spec.info?.description;
+  const version = spec.info?.version || "1.0.0";
+  const operations = [];
+  if (spec.paths) {
+    for (const [path4, methods] of Object.entries(spec.paths)) {
+      for (const [method, details] of Object.entries(methods)) {
+        if (["get", "post", "put", "delete", "patch", "options", "head"].includes(
+          method.toLowerCase()
+        )) {
+          const typedDetails = details;
+          const parameters = (typedDetails.parameters || []).map((p) => ({
+            name: p.name,
+            type: p.schema?.type || "string",
+            required: !!p.required,
+            description: p.description,
+            in: p.in
+          }));
+          if (typedDetails.requestBody) {
+          }
+          operations.push({
+            operationId: typedDetails.operationId || `${method}_${path4.replace(/\//g, "_")}`,
+            summary: typedDetails.summary,
+            description: typedDetails.description,
+            httpMethod: method.toUpperCase(),
+            path: path4,
+            sourceFile: "",
+            // To be filled by scanner
+            className: "",
+            // To be filled by scanner
+            tags: typedDetails.tags || [],
+            parameters,
+            responseType: "any"
+            // To be improved
+          });
+        }
+      }
+    }
+  }
+  return {
+    title,
+    description,
+    version,
+    operations: operations.map((op) => ({
+      ...op,
+      description: cleanDescription(op.description || op.summary)
+    }))
+  };
+}
+function cleanDescription(desc) {
+  if (!desc) return "";
+  return desc.split("\n").filter((line) => {
+    const trimmed = line.trim();
+    return trimmed && !trimmed.startsWith(":") && !trimmed.startsWith("- ") && !trimmed.startsWith("workflow:") && !trimmed.includes("https://");
+  }).join(" ").trim().replace(/\s+/g, " ").slice(0, 60);
+}
+
+// src/core/scanner.ts
+import fs2 from "fs-extra";
+import path from "path";
+async function scanGeneratedFiles(outputDir, metadata, options = {}) {
+  const apis = [];
+  const searchDirs = options.apiDir ? [options.apiDir, ...["api", "apis", "."]] : ["api", "apis", "."];
+  for (const dirName of searchDirs) {
+    const fullDir = path.join(outputDir, dirName);
+    if (!await fs2.pathExists(fullDir)) continue;
+    const files = await fs2.readdir(fullDir);
+    for (const file of files) {
+      if ((file.endsWith("Api.ts") || file.endsWith("api.ts")) && !file.endsWith(".test.ts")) {
+        apis.push({
+          className: file.replace(".ts", ""),
+          // Simplified
+          sourceFile: path.join(dirName, file)
+        });
+      }
+    }
+  }
+  if (metadata.operations) {
+    for (const op of metadata.operations) {
+      if (apis.length > 0) {
+        op.className = apis[0].className;
+        op.sourceFile = apis[0].sourceFile;
+      }
+    }
+  }
+  return {
+    ...metadata,
+    packageName: "api-client",
+    // Default
+    importPath: "./api",
+    // Default
+    apis,
+    operations: metadata.operations || []
+  };
+}
+
+// src/core/renderer.ts
+import Mustache from "mustache";
+import fs3 from "fs-extra";
+import path2 from "path";
+async function renderDocs(metadata, outputDir) {
+  const currentDir = path2.dirname(new URL(import.meta.url).pathname);
+  let templateDir = path2.join(currentDir, "../templates");
+  if (!fs3.existsSync(templateDir)) {
+    const possiblePaths = [
+      path2.join(currentDir, "./templates"),
+      path2.join(currentDir, "../../templates"),
+      path2.join(process.cwd(), "templates"),
+      path2.join(process.cwd(), "dist/templates")
+    ];
+    for (const p of possiblePaths) {
+      if (fs3.existsSync(p)) {
+        templateDir = p;
+        break;
+      }
+    }
+  }
+  const llmsTemplate = await fs3.readFile(path2.join(templateDir, "llms-full.mustache"), "utf-8");
+  const agentTemplate = await fs3.readFile(path2.join(templateDir, "agent.mustache"), "utf-8");
+  const operationsByTag = {};
+  metadata.operations.forEach((op) => {
+    const tag = op.tags?.[0] || "Default";
+    if (!operationsByTag[tag]) operationsByTag[tag] = [];
+    operationsByTag[tag].push(op);
+  });
+  const groupedOperations = Object.entries(operationsByTag).map(([tag, ops]) => ({
+    tag,
+    ops: ops.map((op, index) => ({
+      ...op,
+      last: index === ops.length - 1
+    }))
+  }));
+  const enrichedMetadata = {
+    ...metadata,
+    groupedOperations,
+    apis: metadata.apis.map((api, index) => ({
+      ...api,
+      last: index === metadata.apis.length - 1
+    }))
+  };
+  const llms = Mustache.render(llmsTemplate, enrichedMetadata);
+  const agent = Mustache.render(agentTemplate, enrichedMetadata);
+  await fs3.writeFile(path2.join(outputDir, "llms.txt"), llms);
+  await fs3.writeFile(path2.join(outputDir, "agent.md"), agent);
+}
+
+// src/core/processor.ts
+import path3 from "path";
+import fs4 from "fs-extra";
+async function generateDocs(options) {
+  const { inputSpec, outputDir, apiDir } = options;
+  try {
+    console.log("\u{1F4DD} Generating LLM documentation...");
+    let metadata = await extractMetadata(inputSpec);
+    const fullMetadata = await scanGeneratedFiles(outputDir, metadata, { apiDir });
+    await fs4.ensureDir(outputDir);
+    await renderDocs(fullMetadata, outputDir);
+    console.log(`\u2728 Documentation generated at: ${outputDir}`);
+    console.log(`   - ${path3.join(outputDir, "llms.txt")}`);
+  } catch (err) {
+    console.error("\u274C Failed to generate LLM documentation:", err);
+    throw err;
+  }
+}
+
+export {
+  extractMetadata,
+  scanGeneratedFiles,
+  renderDocs,
+  generateDocs
+};

package/dist/cli.cjs

@@ -0,0 +1,249 @@
+#!/usr/bin/env node
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+
+// node_modules/.pnpm/tsup@8.5.1_postcss@8.5.6_typescript@5.9.3_yaml@2.8.2/node_modules/tsup/assets/cjs_shims.js
+var getImportMetaUrl = () => typeof document === "undefined" ? new URL(`file:${__filename}`).href : document.currentScript && document.currentScript.tagName.toUpperCase() === "SCRIPT" ? document.currentScript.src : new URL("main.js", document.baseURI).href;
+var importMetaUrl = /* @__PURE__ */ getImportMetaUrl();
+
+// src/cli.ts
+var import_commander = require("commander");
+var import_path4 = __toESM(require("path"), 1);
+var import_fs_extra5 = __toESM(require("fs-extra"), 1);
+
+// src/core/processor.ts
+var import_path3 = __toESM(require("path"), 1);
+var import_fs_extra4 = __toESM(require("fs-extra"), 1);
+
+// src/core/extractor.ts
+var import_fs_extra = __toESM(require("fs-extra"), 1);
+var import_yaml = require("yaml");
+async function extractMetadata(specPath) {
+  let content;
+  const isUrl = specPath.startsWith("http://") || specPath.startsWith("https://");
+  if (isUrl) {
+    const response = await fetch(specPath);
+    if (!response.ok) {
+      throw new Error(
+        `Failed to fetch OpenAPI spec from ${specPath}: ${response.statusText}`
+      );
+    }
+    content = await response.text();
+  } else {
+    content = await import_fs_extra.default.readFile(specPath, "utf-8");
+  }
+  const spec = specPath.endsWith(".yaml") || specPath.endsWith(".yml") || isUrl && !content.trim().startsWith("{") ? (0, import_yaml.parse)(content) : JSON.parse(content);
+  const title = spec.info?.title || "API";
+  const description = spec.info?.description;
+  const version = spec.info?.version || "1.0.0";
+  const operations = [];
+  if (spec.paths) {
+    for (const [path5, methods] of Object.entries(spec.paths)) {
+      for (const [method, details] of Object.entries(methods)) {
+        if (["get", "post", "put", "delete", "patch", "options", "head"].includes(
+          method.toLowerCase()
+        )) {
+          const typedDetails = details;
+          const parameters = (typedDetails.parameters || []).map((p) => ({
+            name: p.name,
+            type: p.schema?.type || "string",
+            required: !!p.required,
+            description: p.description,
+            in: p.in
+          }));
+          if (typedDetails.requestBody) {
+          }
+          operations.push({
+            operationId: typedDetails.operationId || `${method}_${path5.replace(/\//g, "_")}`,
+            summary: typedDetails.summary,
+            description: typedDetails.description,
+            httpMethod: method.toUpperCase(),
+            path: path5,
+            sourceFile: "",
+            // To be filled by scanner
+            className: "",
+            // To be filled by scanner
+            tags: typedDetails.tags || [],
+            parameters,
+            responseType: "any"
+            // To be improved
+          });
+        }
+      }
+    }
+  }
+  return {
+    title,
+    description,
+    version,
+    operations: operations.map((op) => ({
+      ...op,
+      description: cleanDescription(op.description || op.summary)
+    }))
+  };
+}
+function cleanDescription(desc) {
+  if (!desc) return "";
+  return desc.split("\n").filter((line) => {
+    const trimmed = line.trim();
+    return trimmed && !trimmed.startsWith(":") && !trimmed.startsWith("- ") && !trimmed.startsWith("workflow:") && !trimmed.includes("https://");
+  }).join(" ").trim().replace(/\s+/g, " ").slice(0, 60);
+}
+
+// src/core/scanner.ts
+var import_fs_extra2 = __toESM(require("fs-extra"), 1);
+var import_path = __toESM(require("path"), 1);
+async function scanGeneratedFiles(outputDir, metadata, options = {}) {
+  const apis = [];
+  const searchDirs = options.apiDir ? [options.apiDir, ...["api", "apis", "."]] : ["api", "apis", "."];
+  for (const dirName of searchDirs) {
+    const fullDir = import_path.default.join(outputDir, dirName);
+    if (!await import_fs_extra2.default.pathExists(fullDir)) continue;
+    const files = await import_fs_extra2.default.readdir(fullDir);
+    for (const file of files) {
+      if ((file.endsWith("Api.ts") || file.endsWith("api.ts")) && !file.endsWith(".test.ts")) {
+        apis.push({
+          className: file.replace(".ts", ""),
+          // Simplified
+          sourceFile: import_path.default.join(dirName, file)
+        });
+      }
+    }
+  }
+  if (metadata.operations) {
+    for (const op of metadata.operations) {
+      if (apis.length > 0) {
+        op.className = apis[0].className;
+        op.sourceFile = apis[0].sourceFile;
+      }
+    }
+  }
+  return {
+    ...metadata,
+    packageName: "api-client",
+    // Default
+    importPath: "./api",
+    // Default
+    apis,
+    operations: metadata.operations || []
+  };
+}
+
+// src/core/renderer.ts
+var import_mustache = __toESM(require("mustache"), 1);
+var import_fs_extra3 = __toESM(require("fs-extra"), 1);
+var import_path2 = __toESM(require("path"), 1);
+async function renderDocs(metadata, outputDir) {
+  const currentDir = import_path2.default.dirname(new URL(importMetaUrl).pathname);
+  let templateDir = import_path2.default.join(currentDir, "../templates");
+  if (!import_fs_extra3.default.existsSync(templateDir)) {
+    const possiblePaths = [
+      import_path2.default.join(currentDir, "./templates"),
+      import_path2.default.join(currentDir, "../../templates"),
+      import_path2.default.join(process.cwd(), "templates"),
+      import_path2.default.join(process.cwd(), "dist/templates")
+    ];
+    for (const p of possiblePaths) {
+      if (import_fs_extra3.default.existsSync(p)) {
+        templateDir = p;
+        break;
+      }
+    }
+  }
+  const llmsTemplate = await import_fs_extra3.default.readFile(import_path2.default.join(templateDir, "llms-full.mustache"), "utf-8");
+  const agentTemplate = await import_fs_extra3.default.readFile(import_path2.default.join(templateDir, "agent.mustache"), "utf-8");
+  const operationsByTag = {};
+  metadata.operations.forEach((op) => {
+    const tag = op.tags?.[0] || "Default";
+    if (!operationsByTag[tag]) operationsByTag[tag] = [];
+    operationsByTag[tag].push(op);
+  });
+  const groupedOperations = Object.entries(operationsByTag).map(([tag, ops]) => ({
+    tag,
+    ops: ops.map((op, index) => ({
+      ...op,
+      last: index === ops.length - 1
+    }))
+  }));
+  const enrichedMetadata = {
+    ...metadata,
+    groupedOperations,
+    apis: metadata.apis.map((api, index) => ({
+      ...api,
+      last: index === metadata.apis.length - 1
+    }))
+  };
+  const llms = import_mustache.default.render(llmsTemplate, enrichedMetadata);
+  const agent = import_mustache.default.render(agentTemplate, enrichedMetadata);
+  await import_fs_extra3.default.writeFile(import_path2.default.join(outputDir, "llms.txt"), llms);
+  await import_fs_extra3.default.writeFile(import_path2.default.join(outputDir, "agent.md"), agent);
+}
+
+// src/core/processor.ts
+async function generateDocs(options) {
+  const { inputSpec, outputDir, apiDir } = options;
+  try {
+    console.log("\u{1F4DD} Generating LLM documentation...");
+    let metadata = await extractMetadata(inputSpec);
+    const fullMetadata = await scanGeneratedFiles(outputDir, metadata, { apiDir });
+    await import_fs_extra4.default.ensureDir(outputDir);
+    await renderDocs(fullMetadata, outputDir);
+    console.log(`\u2728 Documentation generated at: ${outputDir}`);
+    console.log(`   - ${import_path3.default.join(outputDir, "llms.txt")}`);
+  } catch (err) {
+    console.error("\u274C Failed to generate LLM documentation:", err);
+    throw err;
+  }
+}
+
+// src/cli.ts
+var program = new import_commander.Command();
+program.name("oas-agent-sync").description("Generate LLM documentation for existing generated code (Middleware mode)").version("0.1.0");
+program.argument("<spec>", "OpenAPI specification file (local path or URL)").requiredOption("-o, --output <dir>", "Existing generated code directory").option("--api-dir <path>", "Relative path to APIs within output directory", "").action(async (spec, options) => {
+  try {
+    let inputSpec = spec;
+    const isUrl = inputSpec.startsWith("http://") || inputSpec.startsWith("https://");
+    if (!isUrl) {
+      inputSpec = import_path4.default.resolve(process.cwd(), inputSpec);
+      if (!await import_fs_extra5.default.pathExists(inputSpec)) {
+        console.error(`Error: Input file not found: ${inputSpec}`);
+        process.exit(1);
+      }
+    }
+    const outputDir = import_path4.default.resolve(process.cwd(), options.output);
+    if (!await import_fs_extra5.default.pathExists(outputDir)) {
+      console.error(`Error: Output directory not found: ${outputDir}`);
+      process.exit(1);
+    }
+    await generateDocs({
+      inputSpec,
+      outputDir,
+      apiDir: options.apiDir || void 0
+    });
+  } catch (error) {
+    console.error(`Error: ${error.message}`);
+    process.exit(1);
+  }
+});
+program.parse(process.argv);

package/dist/cli.d.cts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/cli.js

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+import {
+  generateDocs
+} from "./chunk-JGV5ULAN.js";
+
+// src/cli.ts
+import { Command } from "commander";
+import path from "path";
+import fs from "fs-extra";
+var program = new Command();
+program.name("oas-agent-sync").description("Generate LLM documentation for existing generated code (Middleware mode)").version("0.1.0");
+program.argument("<spec>", "OpenAPI specification file (local path or URL)").requiredOption("-o, --output <dir>", "Existing generated code directory").option("--api-dir <path>", "Relative path to APIs within output directory", "").action(async (spec, options) => {
+  try {
+    let inputSpec = spec;
+    const isUrl = inputSpec.startsWith("http://") || inputSpec.startsWith("https://");
+    if (!isUrl) {
+      inputSpec = path.resolve(process.cwd(), inputSpec);
+      if (!await fs.pathExists(inputSpec)) {
+        console.error(`Error: Input file not found: ${inputSpec}`);
+        process.exit(1);
+      }
+    }
+    const outputDir = path.resolve(process.cwd(), options.output);
+    if (!await fs.pathExists(outputDir)) {
+      console.error(`Error: Output directory not found: ${outputDir}`);
+      process.exit(1);
+    }
+    await generateDocs({
+      inputSpec,
+      outputDir,
+      apiDir: options.apiDir || void 0
+    });
+  } catch (error) {
+    console.error(`Error: ${error.message}`);
+    process.exit(1);
+  }
+});
+program.parse(process.argv);

package/dist/index.cjs

@@ -0,0 +1,234 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  extractMetadata: () => extractMetadata,
+  generateDocs: () => generateDocs,
+  renderDocs: () => renderDocs,
+  scanGeneratedFiles: () => scanGeneratedFiles
+});
+module.exports = __toCommonJS(index_exports);
+
+// node_modules/.pnpm/tsup@8.5.1_postcss@8.5.6_typescript@5.9.3_yaml@2.8.2/node_modules/tsup/assets/cjs_shims.js
+var getImportMetaUrl = () => typeof document === "undefined" ? new URL(`file:${__filename}`).href : document.currentScript && document.currentScript.tagName.toUpperCase() === "SCRIPT" ? document.currentScript.src : new URL("main.js", document.baseURI).href;
+var importMetaUrl = /* @__PURE__ */ getImportMetaUrl();
+
+// src/core/processor.ts
+var import_path3 = __toESM(require("path"), 1);
+var import_fs_extra4 = __toESM(require("fs-extra"), 1);
+
+// src/core/extractor.ts
+var import_fs_extra = __toESM(require("fs-extra"), 1);
+var import_yaml = require("yaml");
+async function extractMetadata(specPath) {
+  let content;
+  const isUrl = specPath.startsWith("http://") || specPath.startsWith("https://");
+  if (isUrl) {
+    const response = await fetch(specPath);
+    if (!response.ok) {
+      throw new Error(
+        `Failed to fetch OpenAPI spec from ${specPath}: ${response.statusText}`
+      );
+    }
+    content = await response.text();
+  } else {
+    content = await import_fs_extra.default.readFile(specPath, "utf-8");
+  }
+  const spec = specPath.endsWith(".yaml") || specPath.endsWith(".yml") || isUrl && !content.trim().startsWith("{") ? (0, import_yaml.parse)(content) : JSON.parse(content);
+  const title = spec.info?.title || "API";
+  const description = spec.info?.description;
+  const version = spec.info?.version || "1.0.0";
+  const operations = [];
+  if (spec.paths) {
+    for (const [path4, methods] of Object.entries(spec.paths)) {
+      for (const [method, details] of Object.entries(methods)) {
+        if (["get", "post", "put", "delete", "patch", "options", "head"].includes(
+          method.toLowerCase()
+        )) {
+          const typedDetails = details;
+          const parameters = (typedDetails.parameters || []).map((p) => ({
+            name: p.name,
+            type: p.schema?.type || "string",
+            required: !!p.required,
+            description: p.description,
+            in: p.in
+          }));
+          if (typedDetails.requestBody) {
+          }
+          operations.push({
+            operationId: typedDetails.operationId || `${method}_${path4.replace(/\//g, "_")}`,
+            summary: typedDetails.summary,
+            description: typedDetails.description,
+            httpMethod: method.toUpperCase(),
+            path: path4,
+            sourceFile: "",
+            // To be filled by scanner
+            className: "",
+            // To be filled by scanner
+            tags: typedDetails.tags || [],
+            parameters,
+            responseType: "any"
+            // To be improved
+          });
+        }
+      }
+    }
+  }
+  return {
+    title,
+    description,
+    version,
+    operations: operations.map((op) => ({
+      ...op,
+      description: cleanDescription(op.description || op.summary)
+    }))
+  };
+}
+function cleanDescription(desc) {
+  if (!desc) return "";
+  return desc.split("\n").filter((line) => {
+    const trimmed = line.trim();
+    return trimmed && !trimmed.startsWith(":") && !trimmed.startsWith("- ") && !trimmed.startsWith("workflow:") && !trimmed.includes("https://");
+  }).join(" ").trim().replace(/\s+/g, " ").slice(0, 60);
+}
+
+// src/core/scanner.ts
+var import_fs_extra2 = __toESM(require("fs-extra"), 1);
+var import_path = __toESM(require("path"), 1);
+async function scanGeneratedFiles(outputDir, metadata, options = {}) {
+  const apis = [];
+  const searchDirs = options.apiDir ? [options.apiDir, ...["api", "apis", "."]] : ["api", "apis", "."];
+  for (const dirName of searchDirs) {
+    const fullDir = import_path.default.join(outputDir, dirName);
+    if (!await import_fs_extra2.default.pathExists(fullDir)) continue;
+    const files = await import_fs_extra2.default.readdir(fullDir);
+    for (const file of files) {
+      if ((file.endsWith("Api.ts") || file.endsWith("api.ts")) && !file.endsWith(".test.ts")) {
+        apis.push({
+          className: file.replace(".ts", ""),
+          // Simplified
+          sourceFile: import_path.default.join(dirName, file)
+        });
+      }
+    }
+  }
+  if (metadata.operations) {
+    for (const op of metadata.operations) {
+      if (apis.length > 0) {
+        op.className = apis[0].className;
+        op.sourceFile = apis[0].sourceFile;
+      }
+    }
+  }
+  return {
+    ...metadata,
+    packageName: "api-client",
+    // Default
+    importPath: "./api",
+    // Default
+    apis,
+    operations: metadata.operations || []
+  };
+}
+
+// src/core/renderer.ts
+var import_mustache = __toESM(require("mustache"), 1);
+var import_fs_extra3 = __toESM(require("fs-extra"), 1);
+var import_path2 = __toESM(require("path"), 1);
+async function renderDocs(metadata, outputDir) {
+  const currentDir = import_path2.default.dirname(new URL(importMetaUrl).pathname);
+  let templateDir = import_path2.default.join(currentDir, "../templates");
+  if (!import_fs_extra3.default.existsSync(templateDir)) {
+    const possiblePaths = [
+      import_path2.default.join(currentDir, "./templates"),
+      import_path2.default.join(currentDir, "../../templates"),
+      import_path2.default.join(process.cwd(), "templates"),
+      import_path2.default.join(process.cwd(), "dist/templates")
+    ];
+    for (const p of possiblePaths) {
+      if (import_fs_extra3.default.existsSync(p)) {
+        templateDir = p;
+        break;
+      }
+    }
+  }
+  const llmsTemplate = await import_fs_extra3.default.readFile(import_path2.default.join(templateDir, "llms-full.mustache"), "utf-8");
+  const agentTemplate = await import_fs_extra3.default.readFile(import_path2.default.join(templateDir, "agent.mustache"), "utf-8");
+  const operationsByTag = {};
+  metadata.operations.forEach((op) => {
+    const tag = op.tags?.[0] || "Default";
+    if (!operationsByTag[tag]) operationsByTag[tag] = [];
+    operationsByTag[tag].push(op);
+  });
+  const groupedOperations = Object.entries(operationsByTag).map(([tag, ops]) => ({
+    tag,
+    ops: ops.map((op, index) => ({
+      ...op,
+      last: index === ops.length - 1
+    }))
+  }));
+  const enrichedMetadata = {
+    ...metadata,
+    groupedOperations,
+    apis: metadata.apis.map((api, index) => ({
+      ...api,
+      last: index === metadata.apis.length - 1
+    }))
+  };
+  const llms = import_mustache.default.render(llmsTemplate, enrichedMetadata);
+  const agent = import_mustache.default.render(agentTemplate, enrichedMetadata);
+  await import_fs_extra3.default.writeFile(import_path2.default.join(outputDir, "llms.txt"), llms);
+  await import_fs_extra3.default.writeFile(import_path2.default.join(outputDir, "agent.md"), agent);
+}
+
+// src/core/processor.ts
+async function generateDocs(options) {
+  const { inputSpec, outputDir, apiDir } = options;
+  try {
+    console.log("\u{1F4DD} Generating LLM documentation...");
+    let metadata = await extractMetadata(inputSpec);
+    const fullMetadata = await scanGeneratedFiles(outputDir, metadata, { apiDir });
+    await import_fs_extra4.default.ensureDir(outputDir);
+    await renderDocs(fullMetadata, outputDir);
+    console.log(`\u2728 Documentation generated at: ${outputDir}`);
+    console.log(`   - ${import_path3.default.join(outputDir, "llms.txt")}`);
+  } catch (err) {
+    console.error("\u274C Failed to generate LLM documentation:", err);
+    throw err;
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  extractMetadata,
+  generateDocs,
+  renderDocs,
+  scanGeneratedFiles
+});

package/dist/index.d.cts

@@ -0,0 +1,49 @@
+interface ProjectMetadata {
+    title: string;
+    description?: string;
+    version: string;
+    packageName: string;
+    importPath: string;
+    apis: ApiClass[];
+    operations: OperationMetadata[];
+}
+interface ApiClass {
+    className: string;
+    sourceFile: string;
+}
+interface OperationMetadata {
+    operationId: string;
+    summary?: string;
+    description?: string;
+    httpMethod: string;
+    path: string;
+    sourceFile: string;
+    className: string;
+    tags?: string[];
+    parameters: ParameterMetadata[];
+    responseType: string;
+}
+interface ParameterMetadata {
+    name: string;
+    type: string;
+    required: boolean;
+    description?: string;
+    in: 'path' | 'query' | 'header' | 'body' | 'cookie';
+}
+interface SyncOptions {
+    inputSpec: string;
+    outputDir: string;
+    apiDir?: string;
+}
+
+declare function generateDocs(options: SyncOptions): Promise<void>;
+
+declare function extractMetadata(specPath: string): Promise<Partial<ProjectMetadata>>;
+
+declare function scanGeneratedFiles(outputDir: string, metadata: Partial<ProjectMetadata>, options?: {
+    apiDir?: string;
+}): Promise<ProjectMetadata>;
+
+declare function renderDocs(metadata: ProjectMetadata, outputDir: string): Promise<void>;
+
+export { type ApiClass, type OperationMetadata, type ParameterMetadata, type ProjectMetadata, type SyncOptions, extractMetadata, generateDocs, renderDocs, scanGeneratedFiles };

package/dist/index.d.ts

@@ -0,0 +1,49 @@
+interface ProjectMetadata {
+    title: string;
+    description?: string;
+    version: string;
+    packageName: string;
+    importPath: string;
+    apis: ApiClass[];
+    operations: OperationMetadata[];
+}
+interface ApiClass {
+    className: string;
+    sourceFile: string;
+}
+interface OperationMetadata {
+    operationId: string;
+    summary?: string;
+    description?: string;
+    httpMethod: string;
+    path: string;
+    sourceFile: string;
+    className: string;
+    tags?: string[];
+    parameters: ParameterMetadata[];
+    responseType: string;
+}
+interface ParameterMetadata {
+    name: string;
+    type: string;
+    required: boolean;
+    description?: string;
+    in: 'path' | 'query' | 'header' | 'body' | 'cookie';
+}
+interface SyncOptions {
+    inputSpec: string;
+    outputDir: string;
+    apiDir?: string;
+}
+
+declare function generateDocs(options: SyncOptions): Promise<void>;
+
+declare function extractMetadata(specPath: string): Promise<Partial<ProjectMetadata>>;
+
+declare function scanGeneratedFiles(outputDir: string, metadata: Partial<ProjectMetadata>, options?: {
+    apiDir?: string;
+}): Promise<ProjectMetadata>;
+
+declare function renderDocs(metadata: ProjectMetadata, outputDir: string): Promise<void>;
+
+export { type ApiClass, type OperationMetadata, type ParameterMetadata, type ProjectMetadata, type SyncOptions, extractMetadata, generateDocs, renderDocs, scanGeneratedFiles };

package/dist/index.js

@@ -0,0 +1,12 @@
+import {
+  extractMetadata,
+  generateDocs,
+  renderDocs,
+  scanGeneratedFiles
+} from "./chunk-JGV5ULAN.js";
+export {
+  extractMetadata,
+  generateDocs,
+  renderDocs,
+  scanGeneratedFiles
+};

package/dist/templates/agent.mustache

@@ -0,0 +1,12 @@
+# AI Agent Semantic Guide
+
+This package provides tools to help AI agents semantically search and use APIs based on OpenAPI specifications.
+
+## Core Features
+1. **llms.txt**: A primary index file mapping all API intents, operationIDs, paths, and actual source code locations.
+
+## Agent Interaction Guide
+1. **Search & Implement**: Search for the required functionality in `llms.txt` to fulfill the user's request.
+2. **Understand**: Read the actual code at the `Source File` path provided in `llms.txt` to understand exact parameters and return types before writing code.
+
+This guide is designed to help agents select the correct API without unnecessary token waste and move quickly to the implementation phase.

package/dist/templates/llms-full.mustache

@@ -0,0 +1,9 @@
+# {{title}} APIs
+{{#groupedOperations}}
+## {{tag}}
+|Intent|API|Path|Source File|
+|:---|:---|:---|:---|
+{{#ops}}
+|{{{description}}}|`{{{operationId}}}`|`{{{httpMethod}}} {{{path}}}`|`{{{sourceFile}}}`|
+{{/ops}}
+{{/groupedOperations}}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@dotflash/openapi-semantic-generator",
+  "version": "0.1.0",
+  "description": "Semantic mapping automation tool for LLM agents and OpenAPI generated code",
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "oas-agent-sync": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "templates",
+    "src/templates"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup src/index.ts src/cli.ts --format cjs,esm --watch --shims",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "gen:example": "openapi-generator-cli generate -i test/fixtures/petstore.yaml -g typescript-axios -o test/generated/petstore && node dist/cli.js test/fixtures/petstore.yaml -o test/generated/petstore --api-dir api"
+  },
+  "keywords": [
+    "openapi",
+    "generator",
+    "llm",
+    "agent",
+    "semantic-mapping",
+    "documentation"
+  ],
+  "author": "no1flash",
+  "license": "MIT",
+  "dependencies": {
+    "commander": "^13.1.0",
+    "fs-extra": "^11.3.0",
+    "mustache": "^4.2.0",
+    "yaml": "^2.7.0"
+  },
+  "devDependencies": {
+    "@openapitools/openapi-generator-cli": "^2.28.2",
+    "@types/fs-extra": "^11.0.4",
+    "@types/mustache": "^4.2.5",
+    "@types/node": "^22.13.1",
+    "tsup": "^8.3.6",
+    "typescript": "^5.7.3",
+    "vitest": "^3.0.5"
+  }
+}

package/src/templates/agent.mustache

@@ -0,0 +1,12 @@
+# AI Agent Semantic Guide
+
+This package provides tools to help AI agents semantically search and use APIs based on OpenAPI specifications.
+
+## Core Features
+1. **llms.txt**: A primary index file mapping all API intents, operationIDs, paths, and actual source code locations.
+
+## Agent Interaction Guide
+1. **Search & Implement**: Search for the required functionality in `llms.txt` to fulfill the user's request.
+2. **Understand**: Read the actual code at the `Source File` path provided in `llms.txt` to understand exact parameters and return types before writing code.
+
+This guide is designed to help agents select the correct API without unnecessary token waste and move quickly to the implementation phase.

package/src/templates/llms-full.mustache

@@ -0,0 +1,9 @@
+# {{title}} APIs
+{{#groupedOperations}}
+## {{tag}}
+|Intent|API|Path|Source File|
+|:---|:---|:---|:---|
+{{#ops}}
+|{{{description}}}|`{{{operationId}}}`|`{{{httpMethod}}} {{{path}}}`|`{{{sourceFile}}}`|
+{{/ops}}
+{{/groupedOperations}}