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