v1.0.0-alpha1

Naftiko Framework v1.0.0-alpha1 — "Sloop" ⛵ — Release Notes

🚀 The first Alpha is here! This release marks the transition from preview to a stable specification target. Naftiko v1.0.0-alpha1 brings a complete tutorial experience, critical engine fixes, and a hardened CI/CD pipeline.

What is the Naftiko Framework?

The Naftiko Framework is an open-source Java runtime that lets you declare, compose, and expose API capabilities — from simple HTTP proxies to AI-ready MCP tools — using a declarative, specification-driven approach.

This v1.0.0-alpha1 release builds on the v0.5 preview with a focus on developer onboarding, engine reliability, and specification maturity. The Shipyard tutorial now covers 10 complete steps, and the engine handles real-world edge cases that earlier versions missed.

✨ Highlights

💬 Community Feedback

Based on early adopter feedback, we've streamlined the contribution workflow:

• Issue templates — structured Bug Report and Feature Request forms with required fields, so nothing gets lost
• PR templates — standardized checklist covering tests, docs, and conventional commit format
• Agent context blocks — dedicated sections in issues and PRs to document AI-assisted contributions

⚓ The Shipyard Tutorial

A brand-new, end-to-end tutorial that goes far beyond a basic "hello world". Instead of a toy example, you build a realistic maritime fleet management system across 10 guided steps — consuming real-shaped APIs, wiring auth, shaping outputs, orchestrating lookups, and assembling a full voyage manifest.

The tutorial is split into two parts:

• Part 1 — Foundations (Steps 1–6): Build your first tool, add inputs, wire authentication, shape outputs, consume multiple APIs, and write your first POST operation. Everything you need to get productive with Naftiko.
• Part 2 — Going Further (Steps 7–10): Organize tools into skill groups, add a REST front door, orchestrate server-side lookups, and chain it all into a complete fleet manifest. For those who want to push the concept further.

All 10 steps are available as validated YAML fixtures in src/main/resources/tutorial/, with automated CI tests ensuring they stay in sync with the engine.

📐 Capability Model Refinements — Specification v1.0.0-alpha1

The spec has been promoted from preview to its first alpha milestone:

• externalRefs renamed to binds for clarity and conciseness
• JSON capability format removed — YAML is the single source format
• Schema fix: MappedItemArray replaced with direct MappedOutputParameter ref
• Spectral ruleset refactored for clarity and expanded with namespace uniqueness checks across exposes and consumes

🤖 Agent & Contributor Experience

• AGENTS.md replaces claude.md — standardized agent guidelines with bug workflow, build instructions, and capability design rules
• Naftiko Capability SKILL file for VS Code Copilot — context-aware assistance when authoring YAML capabilities
• CONTRIBUTING.md revised and validated as proper Markdown

🔧 Engine Fixes

Several critical runtime bugs have been fixed:

• Mustache template resolution in with parameters — MCP tool with bindings now correctly resolve {{templates}} (#204)
• Array parameter serialization — array params in Mustache body templates are now JSON-serialized with HTML escaping disabled (#213)
• Nested object property resolution — the resolver now recurses into nested object properties without requiring a top-level mapping (#209)
• Query parameter resolution — resourceRef is now set before resolving query input parameters, fixing silent failures
• Namespace-qualified references — the MCP tool with-injector now correctly resolves namespace-qualified references
• Relative file:/// paths — BindingResolver supports relative file:///./path URIs and handles Windows path resolution

📦 CI/CD & Quality

A significantly strengthened pipeline:

• Maven artifact publishing to GitHub Packages
• CLI binary smoke tests — automated runtime validation for native binaries after each build
• Tutorial example tests — dedicated CI workflow validates all tutorial YAML fixtures
• Wiki publishing via GitHub Actions
• Expanded unit test coverage with non-regression tests for all resolved bugs
• Meta-linting proposals for HTML and Markdown

⚠️ Known Issues & Limitations

• Sonar Bugs — 37 Sonar-reported bugs to resolve for Quality Gate recovery (#216)
• NPE in HttpClientAdapter — null pointer when API key auth placement is not set (#212)
• Malformed URLs — baseUri without trailing slash produces broken request URLs (#184)
• CLI pre-built binaries are only available for macOS ARM64, Linux AMD64, and Windows AMD64
• MCP Prompts and Resources wiki documentation still pending

🔢 By the Numbers

• ~70 commits merged since v0.5
• 183 files changed, +16,183 / −4,859 lines
• 4 contributors

🙏 Contributors

Huge thanks to the team for shipping this release:

• @eskenazit — Specification v1.0.0-alpha1, tutorial (steps 1–6), schema fixes, wiki restructuring, agent customization
• @farah-t-trigui — CI/CD pipeline improvements, tutorial test workflows, Maven publishing
• @jlouvel — Engine fixes (resolver, Mustache, namespace references), orchestration improvements, documentation
• @jeremnaf — CLI smoke tests, tutorial testing, Publishing

Full Changelog: v0.5...v1.0.0-alpha1

v0.5

Naftiko Framework v0.5 — Release Notes

🎉 v0.5 is here! One more step toward the Alpha — this release brings major new capabilities for AI agent integration and a stronger developer experience.

---

What is the Naftiko Framework?

The Naftiko Framework is an open-source Java runtime that lets you declare, compose, and expose API capabilities — from simple HTTP proxies to AI-ready MCP tools — using a declarative, specification-driven approach.

This v0.5 release builds on the v0.4 Friends & Family preview with a focus on Context Engineering, AI agent integration, and a more polished developer experience. We're getting closer to the Alpha — stay tuned.

---

✨ Highlights

🧠 Skill Server Adapter

A brand-new exposition adapter that lets you package and distribute capability skills to AI agents:

• Declare skills with full metadata — name, description, license, compatibility notes, and arbitrary key-value tags
• Reference tools from sibling API or MCP adapters, or define local file-based instructions
• Expose a read-only skill catalog over HTTP for agent discovery
• Aligned with the emerging Agent Skills Spec (allowed-tools, argument-hint, user-invocable, disable-model-invocation)

🤖 MCP Resources & Prompts

The MCP adapter now goes beyond Tools:

• Resources — expose structured data that MCP clients can read
• Prompts — provide reusable prompt templates for AI agents
• Full support for Streamable HTTP transport alongside stdio

🔐 Server-Side Authentication

Protect your exposed APIs with declarative authentication:

• Bearer token and API Key verification with constant-time comparison
• HTTP Basic and Digest authentication via Restlet's native challenge authenticators
• Secret resolution via environment variable templates — no plaintext secrets in config
• Auth gate positioned before the router to guarantee no unauthenticated access

🔗 Improved Orchestration

Multi-step operations are now more powerful and reliable:

• Lookup step — join data across consumed sources by matching field values
• Cross-step template resolution — reference outputs from prior steps in subsequent step parameters
• Fixes to output value honoring and mapped step outputs

📐 Specification v0.5

The Naftiko Specification has been updated to v0.5:

• New Skill Server (type: "skill") exposition adapter
• New import directive for consumes adapter reuse — share consumed source definitions across capabilities
• info and description fields are now optional for quicker prototyping
• Schema renamed from capability-schema.json to naftiko-schema.json for clarity
• Updated related specifications comparison table with key strengths

🛠️ CLI

• Windows binary now available alongside Linux AMD64 and macOS Apple Silicon
• Updated project templates reflecting v0.5 spec changes
• Smoke tests integrated into the CI pipeline to validate binaries after each build

📦 CI/CD & Quality

A significantly strengthened delivery pipeline:

• Quality Assurance workflow — Maven tests + JaCoCo coverage + SonarQube analysis + Trivy vulnerability scanning + GitLeaks secret scanning
• Tutorial examples validation — automated tests ensure wiki tutorials stay in sync with the engine
• CLI binary publishing — automated GitHub Actions for Linux, macOS, and Windows
• Docker image publishing — automated build and push to GitHub Container Registry on every merge to main
• JSON Structure validation — automated checks on schema modifications
• Branch protection rules requiring all checks green before merge

📖 Documentation

• FAQ page added to the wiki
• Wiki and blueprints markdown integrated into the monorepo for easier management
• Expanded tutorial files with authentication examples (bearer, API key)
• Updated README with visuals, use cases, and improved project description
• Apache 2.0 license converted to Markdown

---

⚠️ Known Issues & Limitations

• MCP Prompts and Resources are not yet covered in the wiki blueprints — the online wiki will be updated separately
• CLI pre-built binaries are only available for macOS ARM64, Linux AMD64, and Windows AMD64
• Test coverage is still ramping up (~52% JaCoCo)

---

🔢 By the Numbers

• ~36 pull requests merged on the framework repo alone
• 4 contributors
• 3 new CI/CD workflows

---

🙏 Contributors

Huge thanks to the team for shipping this release:

• @jlouvel — Skill adapter, MCP resources & prompts, server-side authentication, orchestration improvements, lookup steps
• @jeremnaf — CLI packaging (Windows support), Docker, CI/CD workflows, tutorials
• @eskenazit — Specification v0.5, schema renaming, consumes import, JSON structure validation
• @farah-t-trigui — CI pipeline improvements

---

Full Changelog: v0.5

Friends & Family prerelease

🎉 Our very first release! This is a Friends & Family preview — thanks for being part of the journey from day one.

---

What is the Naftiko Framework?

The Naftiko Framework is an open-source integration project that lets you declare, compose, and expose API capabilities — from simple HTTP proxies to AI-ready MCP tools — using a declarative, specification-driven approach.

This v0.4 release is our first public milestone. It lays the foundation for everything that comes next.

---

✨ Highlights

Declarative Capability Engine

Define API capabilities without writing boilerplate code. The runtime handles the heavy lifting:

• Pass-through proxy with automatic header forwarding
• API adapter for structured request/response mapping
• No-adapter mode for lightweight capabilities that don't need an external backend
• Basic and advanced capability modes — start simple for straightforward problems, scale up to more complex configurations as needed
• Mocking mode — prototype and test capabilities without a live backend

🤖 MCP Server Adapter

Expose your capabilities as Model Context Protocol (MCP) tools, ready to be consumed by AI agents:

• First implementation of the MCP server adapter
• Support for stdio transport — plug directly into Claude, Cursor, and other MCP-compatible clients

🛠️ CLI

A brand-new command-line interface to scaffold, validate, and run capabilities locally:

• naftiko CLI with help commands and options
• Packaged as a standalone binary for easy distribution
• Project templates to get started fast

📐 Specification & Validation

The Capability Specification Schema is now part of the framework monorepo:

• JSON structure validation at design time
• External reference keys with pattern control
• Tutorial files validation to ensure examples stay in sync with the spec
• Early and minimal AI-assisted development guidelines (claude.md) — this is a first iteration, expect it to evolve significantly

📦 CI/CD & Distribution

• Docker image published automatically via GitHub Actions
• Binary build validation in CI pipeline
• GitHub Actions for automated packaging and publishing

📖 Documentation

• User documentation and getting-started guides
• Specification README and capability design guidelines
• CLI documentation

---

⚠️ Known Issues & Limitations

• Pre-built binaries are currently available for AMD64 Linux and Apple Silicon (macOS) only
• inputParameter in header may not work correctly — investigation ongoing

---

🔢 By the Numbers

• 35 pull requests merged
• 4 contributors
• 1 brand-new open-source project 🎁

---

🙏 Contributors

Huge thanks to the founding team who made this first release happen:

• @jlouvel — Core runtime, API adapter, MCP adapter, mocking mode
• @jeremnaf — CLI, Docker, CI/CD, documentation
• @eskenazit — Specification schema, validation, capability simplification
• @farah-t-trigui — CI pipeline improvements 🎉 (first contribution!)

---

⚠️ What's Next

This is a Friends & Family preview. Expect breaking changes as we iterate through the 0.x series toward a stable 1.0 GA release.

Up next, v0.5 will be our Alpha release, focusing on Context Engineering use cases and a more polished developer experience.

Check out our public roadmap to see what's coming.

---

Full Changelog: v0.4