oatty 0.1.0-placeholder.0

package/README.md

@@ -0,0 +1,340 @@
+![Oatty Logo](assets/branding/oatty-lockup-github-v6.1.svg)
+
+[![CI](https://github.com/oattyio/oatty/actions/workflows/ci.yml/badge.svg)](https://github.com/oattyio/oatty/actions/workflows/ci.yml)
+![Rust](https://img.shields.io/badge/rust-1.93%2B-orange)
+![License](https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-blue)
+![Status](https://img.shields.io/badge/status-experimental-yellow)
+
+# Oatty - Schema-driven CLI + TUI + MCP
+
+A vendor-agnostic operations surface for teams that are tired of juggling near-identical CLIs, partial API coverage, and
+separate MCP servers with different constraints.
+
+Oatty turns OpenAPI documents into runnable commands, lets you execute them from one consistent CLI/TUI, and extends
+that surface with MCP tools and reusable workflows.
+
+## Why Oatty Exists
+
+Modern developer tooling has a strange paradox:  
+the APIs are powerful and well-documented, but the tools built on top of them are fragmented, incomplete, and
+inconsistent.
+
+Most vendor CLIs are thin wrappers around an API with a small set of hand-crafted workflows.  
+When you work across vendors, the experience converges into the same problems:
+
+- Nearly identical commands with different naming conventions
+- Partial API coverage that forces you back to curl or custom scripts
+- Separate MCP servers that expose even *less* functionality than the CLI
+- Automation that lives in brittle scripts instead of reusable, inspectable workflows
+
+Oatty was built to collapse this complexity into **one coherent operational surface**.
+
+---
+
+## Core UX Principles
+
+Oatty is not just a CLI replacement — it is a **carefully designed terminal experience** built around four core
+principles.
+
+### 1. Discoverability
+
+You should never need to memorize commands.
+
+- Every command, workflow, and option is searchable and browsable.
+- The TUI acts as a living catalog derived directly from schemas and plugins.
+- If the API supports it, you can *find it* — even if you’ve never used it before.
+
+This makes Oatty approachable for new users and powerful for experts.
+
+---
+
+### 2. Simplicity
+
+Each screen does **one thing**, clearly.
+
+- Search commands
+- Inspect details
+- Run an action
+- Monitor progress or results
+
+There is no clutter, no overloaded views, and no hidden modes.  
+Familiar interaction patterns (lists, tables, forms, logs) keep cognitive load low, even when the underlying task is
+complex.
+
+---
+
+### 3. Speed
+
+Oatty is designed for real work, not demos.
+
+- Fast startup and low-latency interactions
+- Keyboard-first navigation with the mouse interactions you'd expect from a beautiful terminal UI
+- Reliable execution paths for long-running workflows and streaming output
+
+Power users can move as fast as they can type — without sacrificing safety or clarity.
+
+---
+
+### 4. Consistency
+
+Once you learn Oatty, you’ve learned every vendor's CLI, workflow, and MCP server.
+
+- The same command model powers the CLI, the TUI, workflows, and MCP tools
+- Flags, arguments, outputs, and behaviors follow consistent patterns
+- Vendor-specific quirks are normalized behind a shared execution model
+
+This consistency dramatically reduces context switching and relearning.
+
+---
+
+## The Big Idea
+
+Treat vendor APIs and MCP servers as **inputs**, not product boundaries.
+
+Oatty ingests OpenAPI schemas to build a runtime command catalog, exposes that catalog through a unified CLI and TUI,
+and allows vendors or teams to extend it via MCP — all while enabling first-class, filesystem-backed workflows.
+
+Instead of maintaining:
+
+- N vendor CLIs
+- N MCP servers
+- N incompatible automation approaches
+
+You get **one interface**, one mental model, and one place to operate.
+
+---
+
+## What This Unlocks
+
+- Full API coverage without waiting for vendors to implement it their CLI
+- Workflows that span multiple vendors and MCP servers
+- A single MCP surface instead of fragmented plugin ecosystems
+- Shareable, reviewable workflows instead of opaque scripts
+- A terminal UX that scales from quick commands to complex operations
+
+## Quick Example
+
+Use one interface for API-derived commands and workflow execution:
+
+```bash
+# Start interactive mode
+cargo run -p oatty
+
+# Execute a command from a loaded catalog
+cargo run -p oatty -- apps list
+
+# Run a workflow from runtime storage
+cargo run -p oatty -- workflow list
+```
+
+## Usage
+
+- Build: `cargo build --workspace`
+- Run TUI (no args): `cargo run -p oatty` (or the installed binary `oatty`)
+- CLI examples:
+    - `cargo run -p oatty -- apps list`
+    - `cargo run -p oatty -- apps info my-app`
+    - `cargo run -p oatty -- workflow list`
+    - `cargo run -p oatty -- workflow preview --file workflows/create_app_and_db.yaml`
+
+Note: available commands depend on which registry catalogs and MCP plugins are configured/enabled.
+
+## NPM Distribution
+
+Oatty can be installed via npm and will download the matching prebuilt binary for your platform during `postinstall`.
+
+```bash
+npm i -g oatty
+oatty --help
+```
+
+How it works:
+
+- npm installs a small Node launcher package (`oatty`).
+- The installer detects your OS/arch and fetches the matching GitHub release asset for the npm package version.
+- The download is verified against the release `SHA256SUMS` before extraction.
+
+Currently mapped platforms:
+
+- macOS `x64` -> `x86_64-apple-darwin`
+- macOS `arm64` -> `aarch64-apple-darwin`
+- Linux `x64` -> `x86_64-unknown-linux-gnu`
+- Windows `x64` -> `x86_64-pc-windows-msvc`
+
+If your platform is not currently mapped, install from source (`cargo build --release`) or use a directly downloaded binary.
+
+Maintainers:
+
+- GitHub release assets are built/published via `.github/workflows/release.yml`.
+- npm publication is handled by `.github/workflows/npm-publish.yml` when a non-prerelease GitHub Release is published and npm Trusted Publishing is configured.
+
+### First-time: import a registry catalog
+
+If you have no catalogs configured yet, the fastest way to get started is via the TUI:
+
+1. Run `cargo run -p oatty`.
+2. In the Library view, import a local OpenAPI document (e.g., `schemas/samples/render-public-api.json`) or a URL.
+3. Accept the default command prefix (or enter your own).
+4. The registry configuration is saved to `~/.config/oatty/registry.json` and manifests are stored under
+   `~/.config/oatty/catalogs/`.
+
+## Architecture (high level)
+
+- **Registry** (`crates/registry`): loads registry catalogs from `~/.config/oatty/registry.json` and reads per-catalog
+  manifest files (typically `~/.config/oatty/catalogs/*.bin`).
+- **MCP** (`crates/mcp`): loads `~/.config/oatty/mcp.json`, manages plugin lifecycles, and can inject MCP tool commands
+  into the registry at runtime.
+- **CLI** (`crates/cli`): builds a Clap tree from the registry, routes `workflow` commands, and executes HTTP/MCP
+  commands.
+- **TUI** (`crates/tui`): interactive UI built on Ratatui/Crossterm; includes in-app help and log panes.
+- **Engine** (`crates/engine`): workflow parsing and execution utilities used by `oatty workflow ...`.
+
+## Environment & Config
+
+- `OATTY_LOG`: tracing level for stderr logs in CLI mode (`error`, `warn`, `info` [default], `debug`, `trace`).
+- `TUI_THEME`: theme override for the TUI (`dracula`, `dracula_hc`, `nord`, `nord_hc`, `cyberpunk`, `cyberpunk_hc`,
+  `ansi256`, `ansi256_hc`).
+- `MCP_CONFIG_PATH`: overrides MCP config path (default: `~/.config/oatty/mcp.json`).
+- `REGISTRY_CONFIG_PATH`: overrides registry config path (default: `~/.config/oatty/registry.json`).
+- `REGISTRY_CATALOGS_PATH`: overrides the directory where catalog manifest files are stored (default:
+  `~/.config/oatty/catalogs`).
+- `REGISTRY_WORKFLOWS_PATH`: overrides workflow manifest storage (default: `~/.config/oatty/workflows`).
+
+Authentication headers/tokens are configured per catalog in the Library view (or persisted catalog configuration), not
+via a global API token environment variable.
+
+### Logging behavior
+
+- TUI mode silences tracing output to stderr while the UI is active to prevent overlaying the terminal UI; logs are
+  routed into in-app panes where applicable.
+- CLI mode writes logs to stderr as usual.
+
+## Development
+
+- Toolchain: `rust-toolchain.toml` pins the project to Rust `stable`.
+- Workspace crates: `cli`, `tui`, `registry`, `registry-gen`, `engine`, `api`, `util`, `types`, `mcp`.
+- Common commands:
+    - Build: `cargo build --workspace`
+    - Test: `cargo test --workspace`
+    - Lint: `cargo clippy --workspace -- -D warnings`
+    - Format: `cargo fmt --all`
+
+### Registry catalogs (manifests)
+
+- Generator crate: `crates/registry-gen` (`oatty-registry-gen`) can derive a manifest from OpenAPI documents.
+- At runtime, the registry reads catalog manifests from paths referenced in `~/.config/oatty/registry.json`.
+
+## Registry Generator (Library)
+
+The registry is derived from OpenAPI documents using the `registry-gen` crate.
+
+### Library Usage
+
+Add a dependency on the generator crate from within the workspace:
+
+```toml
+[dependencies]
+oatty-registry-gen = { path = "crates/registry-gen" }
+```
+
+Generate a manifest file (postcard):
+
+```rust
+use std::path::PathBuf;
+use oatty_registry_gen::{io::ManifestInput, write_manifest};
+
+fn main() -> anyhow::Result<()> {
+    let schema = PathBuf::from("schemas/samples/render-public-api.json");
+    let output = PathBuf::from("target/manifest.bin");
+    write_manifest(ManifestInput::new(Some(schema), None, None), output)?;
+    Ok(())
+}
+```
+
+Generate a manifest file (JSON):
+
+```rust
+use std::path::PathBuf;
+use oatty_registry_gen::{io::ManifestInput, write_manifest_json};
+
+fn main() -> anyhow::Result<()> {
+    let schema = PathBuf::from("schemas/samples/render-public-api.json");
+    let output = PathBuf::from("target/manifest.json");
+    write_manifest_json(ManifestInput::new(Some(schema), None, None), output)?;
+    Ok(())
+}
+```
+
+Derive commands in-memory from an OpenAPI document:
+
+```rust
+use oatty_registry_gen::openapi::{derive_commands_from_openapi, derive_vendor_from_document};
+
+fn load_commands(openapi_json: &str) -> anyhow::Result<Vec<oatty_types::CommandSpec>> {
+    let document: serde_json::Value = serde_json::from_str(openapi_json)?;
+    let vendor = derive_vendor_from_document(&document);
+    let cmds = derive_commands_from_openapi(&document, &vendor)?;
+    Ok(cmds)
+}
+```
+
+## Flow
+
+```mermaid
+flowchart LR
+  subgraph Runtime
+    A[oatty no args] -->|Launch| TUI[TUI]
+    A2[oatty group cmd] -->|Parse| CLI[CLI Router]
+  end
+
+  subgraph Registry
+    S[OpenAPI Document] --> D["Derive Manifest (registry-gen)"]
+    D --> M["Catalog Manifest (.bin)"]
+    M --> RC[Registry Catalogs]
+    RC --> C[Clap Tree]
+  end
+
+  TUI -->|Search/Select| C
+  TUI -->|Compose| RUN[Execute]
+  CLI -->|Match| C
+  CLI -->|Execute| RUN
+
+  RUN -->|HTTP| HTTP[Oatty API]
+  RUN -->|MCP| MCP[MCP Tool]
+  HTTP --> OUT2[Status + Body]
+  MCP --> OUT2
+
+  subgraph Policy
+    REDACT[Redact secrets in output]
+  end
+  OUT2 --> REDACT
+  RUN --> LOGS[Logs Panel / stdout]
+```
+
+## Security
+
+- Secrets are redacted from output by default (headers/payload in output and logs).
+- Network calls go through reqwest with default timeouts.
+- Release artifact verification guide: `VERIFY.md`.
+- Release publish secrets setup: `RELEASE_SECRETS.md`.
+
+## Status
+
+- Schema-driven registry, CLI router, TUI, MCP plugin engine, and workflow support are implemented. Some HTTP client
+  behaviors (retries/backoff) are minimal.
+
+## Theme Architecture
+
+- Location: `crates/tui/src/ui/theme` (roles, helpers, Dracula/Nord themes)
+- Docs: `specs/THEME.md` (theme mapping, usage, and guidelines)
+- Select theme via env var `TUI_THEME`:
+    - `dracula` (default), `dracula_hc`
+    - `nord`, `nord_hc`
+    - `cyberpunk`, `cyberpunk_hc`
+    - `ansi256`, `ansi256_hc`
+    - Example: `TUI_THEME=dracula cargo run -p oatty`
+
+## Release Trust
+
+- Artifact/user verification steps: `VERIFY.md`
+- CI publish setup (npm Trusted Publishing): `RELEASE_SECRETS.md`

package/npm/bin/oatty.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+"use strict";
+
+const path = require("node:path");
+const fs = require("node:fs");
+const { spawn } = require("node:child_process");
+
+const binaryPath = path.join(__dirname, process.platform === "win32" ? "oatty.exe" : "oatty");
+
+if (!fs.existsSync(binaryPath)) {
+  process.stderr.write(
+    "[oatty] Binary not found. Reinstall with `npm rebuild oatty` or verify release assets exist for your platform.\n"
+  );
+  process.exit(1);
+}
+
+const child = spawn(binaryPath, process.argv.slice(2), {
+  stdio: "inherit",
+  env: process.env,
+  cwd: process.cwd()
+});
+
+child.on("exit", (code, signal) => {
+  if (signal) {
+    process.kill(process.pid, signal);
+    return;
+  }
+  process.exit(code ?? 1);
+});
+
+child.on("error", (error) => {
+  process.stderr.write(`[oatty] Failed to launch binary at ${binaryPath}: ${error.message}\n`);
+  process.exit(1);
+});

package/npm/scripts/platform.js

@@ -0,0 +1,27 @@
+"use strict";
+
+const PLATFORM_TARGETS = {
+  darwin: {
+    x64: { target: "x86_64-apple-darwin", archiveExtension: ".zip", binaryName: "oatty" },
+    arm64: { target: "aarch64-apple-darwin", archiveExtension: ".zip", binaryName: "oatty" }
+  },
+  linux: {
+    x64: { target: "x86_64-unknown-linux-gnu", archiveExtension: ".tar.gz", binaryName: "oatty" }
+  },
+  win32: {
+    x64: { target: "x86_64-pc-windows-msvc", archiveExtension: ".zip", binaryName: "oatty.exe" }
+  }
+};
+
+function resolvePlatformTarget(platform, architecture) {
+  const platformEntry = PLATFORM_TARGETS[platform];
+  if (!platformEntry) {
+    return null;
+  }
+
+  return platformEntry[architecture] || null;
+}
+
+module.exports = {
+  resolvePlatformTarget
+};

package/npm/scripts/postinstall.js

@@ -0,0 +1,182 @@
+"use strict";
+
+const fs = require("node:fs");
+const fsp = require("node:fs/promises");
+const https = require("node:https");
+const path = require("node:path");
+const crypto = require("node:crypto");
+const os = require("node:os");
+const tar = require("tar");
+const AdmZip = require("adm-zip");
+const { resolvePlatformTarget } = require("./platform");
+
+const PACKAGE_ROOT = path.resolve(__dirname, "..", "..");
+const BIN_DIRECTORY = path.join(PACKAGE_ROOT, "npm", "bin");
+const OUTPUT_EXECUTABLE_PATH = path.join(BIN_DIRECTORY, process.platform === "win32" ? "oatty.exe" : "oatty");
+const OUTPUT_MARKER_PATH = path.join(BIN_DIRECTORY, ".oatty-installed-version");
+const RELEASE_REPOSITORY = process.env.OATTY_NPM_RELEASE_REPOSITORY || "oattyio/oatty";
+const RELEASE_TAG_PREFIX = process.env.OATTY_NPM_RELEASE_TAG_PREFIX || "v";
+const RELEASE_BASE_URL = process.env.OATTY_NPM_RELEASE_BASE_URL || `https://github.com/${RELEASE_REPOSITORY}/releases/download`;
+
+async function main() {
+  const packageJsonPath = path.join(PACKAGE_ROOT, "package.json");
+  const packageJson = JSON.parse(await fsp.readFile(packageJsonPath, "utf8"));
+  const packageVersion = packageJson.version;
+  const releaseTag = `${RELEASE_TAG_PREFIX}${packageVersion}`;
+
+  const platformTarget = resolvePlatformTarget(process.platform, process.arch);
+  if (!platformTarget) {
+    emitWarning(
+      `No prebuilt oatty binary is published for platform=${process.platform} arch=${process.arch}.` +
+        " Skipping binary download."
+    );
+    return;
+  }
+
+  const assetFileName = `oatty-${releaseTag}-${platformTarget.target}${platformTarget.archiveExtension}`;
+  const checksumFileName = "SHA256SUMS";
+  const assetUrl = `${RELEASE_BASE_URL}/${releaseTag}/${assetFileName}`;
+  const checksumUrl = `${RELEASE_BASE_URL}/${releaseTag}/${checksumFileName}`;
+
+  await fsp.mkdir(BIN_DIRECTORY, { recursive: true });
+  if (await isAlreadyInstalled(packageVersion)) {
+    return;
+  }
+
+  const temporaryDirectory = await fsp.mkdtemp(path.join(os.tmpdir(), "oatty-npm-"));
+  const archivePath = path.join(temporaryDirectory, assetFileName);
+  const checksumPath = path.join(temporaryDirectory, checksumFileName);
+  try {
+    await downloadToPath(assetUrl, archivePath);
+    await downloadToPath(checksumUrl, checksumPath);
+    await verifyArchiveChecksum(archivePath, checksumPath, assetFileName);
+
+    if (platformTarget.archiveExtension === ".tar.gz") {
+      await extractTarArchive(archivePath, BIN_DIRECTORY);
+    } else {
+      extractZipArchive(archivePath, BIN_DIRECTORY);
+    }
+
+    await ensureExecutablePermissions(OUTPUT_EXECUTABLE_PATH);
+    await fsp.writeFile(OUTPUT_MARKER_PATH, packageVersion, "utf8");
+  } catch (error) {
+    emitWarning(`Failed to install oatty binary from ${assetUrl}. ${error.message}`);
+    emitWarning("You can retry later with: npm rebuild oatty");
+  } finally {
+    await fsp.rm(temporaryDirectory, { recursive: true, force: true });
+  }
+}
+
+async function isAlreadyInstalled(packageVersion) {
+  try {
+    const version = (await fsp.readFile(OUTPUT_MARKER_PATH, "utf8")).trim();
+    const binaryExists = await fileExists(OUTPUT_EXECUTABLE_PATH);
+    return version === packageVersion && binaryExists;
+  } catch {
+    return false;
+  }
+}
+
+async function verifyArchiveChecksum(archivePath, checksumPath, assetFileName) {
+  const expectedChecksum = await readExpectedChecksum(checksumPath, assetFileName);
+  const actualChecksum = await hashFileSha256(archivePath);
+  if (actualChecksum !== expectedChecksum) {
+    throw new Error(`Checksum mismatch for ${assetFileName}. expected=${expectedChecksum} actual=${actualChecksum}`);
+  }
+}
+
+async function readExpectedChecksum(checksumPath, assetFileName) {
+  const checksumContent = await fsp.readFile(checksumPath, "utf8");
+  const lines = checksumContent.split(/\r?\n/);
+  for (const line of lines) {
+    if (!line.trim()) {
+      continue;
+    }
+    const match = line.match(/^([a-fA-F0-9]{64})\s+\*?(.+)$/);
+    if (!match) {
+      continue;
+    }
+    const [, checksum, fileName] = match;
+    if (fileName.trim() === assetFileName) {
+      return checksum.toLowerCase();
+    }
+  }
+  throw new Error(`Checksum for ${assetFileName} not found in SHA256SUMS`);
+}
+
+async function hashFileSha256(filePath) {
+  const hash = crypto.createHash("sha256");
+  await new Promise((resolve, reject) => {
+    const stream = fs.createReadStream(filePath);
+    stream.on("error", reject);
+    stream.on("data", (chunk) => hash.update(chunk));
+    stream.on("end", resolve);
+  });
+  return hash.digest("hex");
+}
+
+async function downloadToPath(url, destinationPath) {
+  await new Promise((resolve, reject) => {
+    const request = https.get(url, (response) => {
+      if (response.statusCode && response.statusCode >= 300 && response.statusCode < 400 && response.headers.location) {
+        response.resume();
+        downloadToPath(response.headers.location, destinationPath).then(resolve).catch(reject);
+        return;
+      }
+
+      if (response.statusCode !== 200) {
+        response.resume();
+        reject(new Error(`Request failed for ${url}. status=${response.statusCode}`));
+        return;
+      }
+
+      const file = fs.createWriteStream(destinationPath);
+      response.pipe(file);
+      file.on("finish", () => file.close(resolve));
+      file.on("error", reject);
+    });
+
+    request.on("error", reject);
+  });
+}
+
+async function extractTarArchive(archivePath, destinationPath) {
+  await tar.x({
+    cwd: destinationPath,
+    file: archivePath
+  });
+}
+
+function extractZipArchive(archivePath, destinationPath) {
+  const zipArchive = new AdmZip(archivePath);
+  zipArchive.extractAllTo(destinationPath, true);
+}
+
+async function ensureExecutablePermissions(binaryPath) {
+  if (process.platform === "win32") {
+    return;
+  }
+
+  if (!(await fileExists(binaryPath))) {
+    throw new Error(`Expected binary not found after extraction: ${binaryPath}`);
+  }
+
+  await fsp.chmod(binaryPath, 0o755);
+}
+
+async function fileExists(filePath) {
+  try {
+    await fsp.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function emitWarning(message) {
+  process.stderr.write(`[oatty npm installer] ${message}\n`);
+}
+
+main().catch((error) => {
+  emitWarning(error.message);
+});

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "oatty",
+  "version": "0.1.0-placeholder.0",
+  "description": "Schema-driven CLI + TUI + MCP runtime",
+  "license": "MIT OR Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/oattyio/oatty.git"
+  },
+  "homepage": "https://github.com/oattyio/oatty",
+  "bugs": {
+    "url": "https://github.com/oattyio/oatty/issues"
+  },
+  "bin": {
+    "oatty": "npm/bin/oatty.js"
+  },
+  "files": [
+    "npm/bin",
+    "npm/scripts",
+    "README.md",
+    "LICENSE*"
+  ],
+  "scripts": {
+    "postinstall": "node npm/scripts/postinstall.js"
+  },
+  "keywords": [
+    "cli",
+    "tui",
+    "mcp",
+    "openapi",
+    "workflow"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "adm-zip": "^0.5.16",
+    "tar": "^7.4.3"
+  }
+}