adapt-api 1.0.0 → 1.0.2

package/README.md

@@ -1,75 +1,116 @@
 # adapt-api
 
-Production-oriented Node.js CLI for ADAPT API readiness assessment.
+Professional Node.js CLI package for ADAPT-based API readiness assessment.
 
-## Features
+## Contributors
 
-- `config` command for persistent defaults (`llm`, `model`, `format`, `api key`, `base url`)
-- `eval <file_path>` command to assess OpenAPI/RAML files
-- Modular ADAPT engine (spec loading, heuristic checks, LLM evaluation, disposition rules)
-- Output factory for `json`, `text`, or `pdf`
-- Spinner-based progress with `ora`
-- Local config persistence via `conf` in the user config directory
+- Pankaj Kumar Jain
+- Jahnavi Thirumalasetty
 
-## Install
+## Overview
 
-From npm (after publish):
+`adapt-api` evaluates OpenAPI/RAML specifications for agent-readiness using the ADAPT framework.  
+The installed package name is `adapt-api`, while the executable command is `apiadapt`.
+
+## Key Capabilities
+
+- Persistent CLI configuration (`llm`, `model`, `format`, `api key`, `base url`)
+- Multi-provider LLM evaluation (`ollama`, `openai`, `anthropic`)
+- Heuristic fallback assessment when LLM is unavailable
+- ADAPT disposition and summary generation
+- Output rendering in `text`, `json`, and `pdf`
+- Manual/help experience with practical command examples
+
+## Installation
+
+`adapt-api` is already published on npm, and this GitHub repository contains the same source code used for the package.
+
+Install the latest published CLI globally:
 
 ```bash
 npm install -g adapt-api
 ```
 
-For local development:
+If you want to run or modify the source from this repository:
 
 ```bash
 npm install
 ```
 
-For local command testing:
+Optionally link the local build for command testing:
 
 ```bash
 npm link
 ```
 
-## Usage
+## CLI Command
 
-### Configure defaults
+After installation, run:
 
 ```bash
-apiadapt config --llm openai --model gpt-4o-mini --format json --api-key <key>
+apiadapt --help
 ```
 
-Or interactive:
+## Quick Start
+
+Set defaults (OpenAI example):
 
 ```bash
-apiadapt config
+apiadapt config --llm openai --model gpt-4o-mini --format json --api-key <OPENAI_API_KEY>
 ```
 
-### Evaluate a spec
+Evaluate a spec:
 
 ```bash
-apiadapt eval ./openapi.yaml
+apiadapt eval ./openapi.yaml --format text --print
 ```
 
-Write explicit output:
+Generate a PDF report:
 
 ```bash
-apiadapt eval ./openapi.yaml --format pdf --output ./report.pdf
+apiadapt eval ./openapi.yaml --format pdf --output ./reports/adapt-report.pdf
 ```
 
-Print output to terminal:
+Open full manual:
 
 ```bash
-apiadapt eval ./openapi.yaml --format text --print
+apiadapt manual
 ```
 
-## Commands
+## Command Reference
 
 - `apiadapt config [--llm] [--model] [--format] [--api-key] [--base-url]`
+  - Saves persistent defaults for provider/model/output and connection settings.
 - `apiadapt eval <file_path> [--format] [--output] [--print]`
+  - Executes ADAPT assessment and prints/saves formatted output.
+- `apiadapt manual` (alias: `apiadapt man`)
+  - Displays full usage manual with examples.
+
+## LLM Provider Notes
+
+- `ollama`: defaults to `http://localhost:11434` unless `--base-url` is set.
+- `openai`: requires `--api-key`; base URL defaults to `https://api.openai.com`.
+- `anthropic`: requires `--api-key`; base URL defaults to `https://api.anthropic.com`.
+
+If LLM requests fail, evaluation gracefully falls back to heuristic ADAPT checks.
+
+## Publishing
+
+Pre-publish validation:
+
+```bash
+npm run prepublishOnly
+npm pack --dry-run
+```
+
+Publish:
+
+```bash
+npm publish --access public
+```
+
+## File Documentation
 
-## Notes
+Detailed file-by-file purpose and functionality documentation is available at:
 
-- OpenAI and Anthropic providers require an API key (`--api-key` in config).
-- Ollama defaults to `http://localhost:11434`; override with `--base-url`.
-- If LLM evaluation fails, the CLI falls back to heuristic assessment and still returns output.
+- `docs/FILE_REFERENCE.md`

package/docs/FILE_REFERENCE.md

@@ -0,0 +1,83 @@
+# File Reference
+
+This document explains the purpose and functionality of each maintained source file in `adapt-api`.
+
+## Root Files
+
+- `package.json`  
+  Defines npm package metadata, dependencies, scripts, publish settings, and CLI binary mapping.
+
+- `package-lock.json`  
+  Locks dependency versions for reproducible installs.
+
+- `README.md`  
+  Primary user/developer documentation including installation, usage, and publishing.
+
+- `LICENSE`  
+  Project license terms and contributor copyright notice.
+
+- `.gitignore`  
+  Excludes local artifacts (`node_modules`, temp config, generated reports, tarballs).
+
+## CLI Entrypoint
+
+- `bin/apiadapt.js`  
+  Executable entry script (with shebang) that invokes the main CLI runner and handles top-level errors.
+
+## Core CLI Wiring
+
+- `src/cli.js`  
+  Registers commands/options using `commander`, defines help text, and routes commands to handlers.
+
+## Command Handlers
+
+- `src/commands/config.js`  
+  Implements `apiadapt config`; supports flag-based and interactive configuration updates.
+
+- `src/commands/eval.js`  
+  Implements `apiadapt eval`; runs assessment flow, renders output, and writes/prints results.
+
+- `src/commands/manual.js`  
+  Implements `apiadapt manual`; prints complete command manual and examples.
+
+## Engine Layer
+
+- `src/engine/evaluator.js`  
+  Orchestrates full evaluation pipeline: file loading, heuristic pass, LLM pass, disposition, and metadata.
+
+- `src/engine/heuristics.js`  
+  Provides deterministic baseline ADAPT checks when LLM output is unavailable or invalid.
+
+- `src/engine/disposition.js`  
+  Encapsulates ADAPT disposition rules and human-readable summary generation from identified gaps.
+
+- `src/engine/llmClients.js`  
+  Integrates provider-specific LLM calls (Ollama/OpenAI/Anthropic), parsing, normalization, and timeout/error handling.
+
+- `src/engine/SystemPrompt.txt`  
+  Canonical ADAPT system prompt consumed by `llmClients.js` for LLM assessment requests.
+
+## Output Formatters
+
+- `src/formatters/index.js`  
+  Selects formatter by output type and centralizes output file write behavior.
+
+- `src/formatters/jsonFormatter.js`  
+  Serializes report payloads into pretty-printed JSON.
+
+- `src/formatters/textFormatter.js`  
+  Builds readable plain-text report output for terminal or file usage.
+
+- `src/formatters/pdfFormatter.js`  
+  Generates a headless PDF assessment report using `pdfkit`.
+
+## Utility Modules
+
+- `src/utils/configStore.js`  
+  Manages persistent local configuration with validation and lazy config initialization.
+
+- `src/utils/specLoader.js`  
+  Reads API spec files, infers type (JSON/YAML/RAML), parses content, and returns normalized metadata.
+
+- `src/utils/prompts.js`  
+  Provides small interactive question helper for CLI prompt flows.

package/package.json

@@ -1,12 +1,16 @@
 {
   "name": "adapt-api",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "ADAPT API readiness assessment CLI",
   "license": "MIT",
   "type": "module",
-  "homepage": "https://www.npmjs.com/package/adapt-api",
+  "homepage": "https://github.com/apiadapt/adapt-framework#readme",
   "bugs": {
-    "url": "https://www.npmjs.com/package/adapt-api"
+    "url": "https://github.com/apiadapt/adapt-framework/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/apiadapt/adapt-framework.git"
   },
   "bin": {
     "apiadapt": "./bin/apiadapt.js"
@@ -14,6 +18,7 @@
   "files": [
     "bin/",
     "src/",
+    "docs/",
     "README.md",
     "LICENSE"
   ],
@@ -41,6 +46,6 @@
     "fs-extra": "^11.3.2",
     "js-yaml": "^4.1.0",
     "ora": "^9.0.0",
-    "pdfkit": "^0.17.2"
+    "pdfkit": "^0.18.0"
   }
 }