Skip to content

Collapse into a single native ict binary with CLI and MCP views - #4

Merged
benfortuna merged 24 commits into
developfrom
single-native-binary
Oct 11, 2026
Merged

benfortuna merged 24 commits into
developfrom
single-native-binary

Conversation

@benfortuna

Copy link
Copy Markdown
Member

Implements the OpenSpec change single-native-binary, now archived under openspec/changes/archive/2026-10-11-single-native-binary/, with its specs synced to openspec/specs/.

What changes

  • One module, one executable. The core, cli, mcp and agent modules collapse into a single root project, org.ical4j:ict. Spring, Spring AI, langchain4j, log4j and OSGi packaging are gone, and logging is slf4j-simple to stderr.
  • Operation registry. Each operation is defined once, keyed by (verb, subject, locus), with surface-neutral parameters, a handler that returns a structured Result, and typed failures. The first cohort covers collections, calendar and card import/export/remove, and listing entities. The old command classes are quarantined in src/legacy/, and docs/dropped-commands.md maps each one to its registry tuple. A conformance spec fails the build for any operation that no specification covers.
  • CLI view: ict <verb> <type> [--options], generated from the registry at startup.
    • Global options: --workspace, --format text|json|xml, -v, -q, --lenient.
    • Exit codes: 0 success, 1 operation failure, 2 usage error.
    • ict config replaces ConfigureCommand.
  • MCP view: ict mcp serves the same registry as <verb>_<type> tools over stdio, using MCP Java SDK 2.0.1, with input schemas derived from the parameters. Failures come back as isError results, and stdout carries only protocol messages.
  • Native build:
    • GraalVM CE 25 builds a single 37 MiB file with no dylibs; median ict --help is 9 ms.
    • Reachability metadata is checked in. mergeTracedMetadata refreshes it from a smoke run under the tracing agent.
    • The smoke suite (jvmSmoke, nativeSmoke) won't run if an operation has no step in it.
  • Behaviour changes:
    • export calendar now adds a VTIMEZONE for each TZID it references.
    • import calendar adds missing time zones before merging. This works around a null-pointer crash in the connector library when several objects reference a TZID.
    • The collection operations take --collection rather than --name.
  • CI and release:
    • build.yml runs the JVM specs, the JVM smoke run and one linux x64 native smoke job.
    • New release.yml runs on ict-* tags. It builds and smoke-tests native executables for linux x64/arm64, macOS arm64 and windows x64, then publishes checksums, a GitHub Release and the jar to Maven Central.
    • The axion tag prefix is now ict-, so the version restarts at 0.1.0.
    • The S3 uploadDist target and its settings are removed.
  • Docs: README.md and docs/command-protocols.md are rewritten around the registry and its two views.

Testing

  • ./gradlew build jvmSmoke passes locally.
  • nativeSmoke and nativeStartup pass against a native binary built locally on macOS arm64 (GraalVM CE 25.3.4).
  • release.yml has not run yet; the first ict-* tag will be its first test.

Notes for reviewers

  • The MCP SDK is used as mcp-core + mcp-json-jackson2 rather than the mcp aggregate, which would put Jackson 3 into the image next to Jackson 2.
  • On macOS 27 hosts, set SDKROOT to an older SDK before building natively (see README). The build passes it through to native-image.

🤖 Generated with Claude Code

benfortuna and others added 24 commits September 5, 2026 15:13
Add the single-native-binary OpenSpec change: proposal, design, spec
deltas and tasks for one GraalVM executable with CLI and MCP surfaces
generated from a shared operation registry. Also ignore the
machine-specific .dkf workspace pointer.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014G7s6EEb4vJud4aCUkgJQU
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014G7s6EEb4vJud4aCUkgJQU
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014G7s6EEb4vJud4aCUkgJQU
Record the spike outcome in design D6: GraalVM CE 25, explicit
sharedLibrary=false, picocli runtime generators, no wholesale JDK type
registration, and a 13-entry hand-written metadata base. Retire the
Quarkus fallback and align tasks 1.4, 5.1 and 5.2 with those findings.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014G7s6EEb4vJud4aCUkGJQU
The Spring AI MCP module returned placeholder strings, the agent module
was excluded from the build, and model-context-protocol held only an
ignored sample build. Drop them with their Spring, Spring AI and
langchain4j catalog entries; MCP returns as an ict subcommand in task 4.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014G7s6EEb4vJud4aCUkGJQU
Move Verb, EntityType, Locus, SerializationFamily and SendMethod to
org.ical4j.command.vocab inside ical4j-command-cli and delete the
ical4j-command-core module. Nothing consumed the enums yet; the
operation registry (task 2) will.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014G7s6EEb4vJud4aCUkGJQU
Move ical4j-command-cli/src to the root, drop settings.gradle includes,
and replace the subprojects build with one build.gradle carrying the
application, native-image and publishing configuration. The native
block comes from the spike: explicit sharedLibrary=false, toolchain
detection off, picocli's runtime metadata generators with the
java.net.URL strip. Publishing coordinates become org.ical4j:ict.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014G7s6EEb4vJud4aCUkGJQU
Remove module-info.java, bnd.bnd, the bnd builder plugin and the OSGi
annotation processors. Native image ignores JPMS, nothing in the tree
used OSGi annotations, and an OSGi bundle was never a goal of the tool.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014G7s6EEb4vJud4aCUkGJQU
Log everything to stderr through slf4j-simple so stdout carries only
command output (and, later, the MCP protocol stream). slf4j-simple fixes
its level when the first logger is created, before picocli has parsed
--verbose, so LogLevel picks the level in main from the raw arguments
and ICT_LOG_LEVEL and publishes it as a system property. The -v flag
stays declared for help and parsing.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014G7s6EEb4vJud4aCUkGJQU
Move the 65 picocli command classes, their 11 support classes, the 13
Spock specs and the geo.ics fixture to src/legacy, which no source set
compiles. Package paths are unchanged so each operation can be moved
back as it is re-admitted to the registry. CommandMain now declares no
subcommands; the build is green with help, version and the LogLevel
spec only.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014G7s6EEb4vJud4aCUkGJQU
Add docs/dropped-commands.md listing the 65 legacy commands with their
old invocation, intended (verb, type, locus), cohort and known issues,
plus the vocabulary gaps the mapping exposes for the registry design.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014G7s6EEb4vJud4aCUkGJQU
Add org.ical4j.command.ops: Operation and OperationId (verb, subject,
locus), surface-neutral Param descriptors with typed Params access and
default/required resolution, structured Result records, a Context that
carries stores and stdin, Handler, typed OperationException, and
Surface. Settle the vocabulary gaps: Subject unifies entity types,
serialization families and container loci as the type axis; Locus
gains NONE and CHANNEL, which cannot be subjects.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014G7s6EEb4vJud4aCUkGJQU
An immutable table of operations built once at startup. The builder
rejects a second registration of the same (verb, subject, locus) tuple,
and the registry offers lookup by identity, filtering by surface,
grouping by verb for help output, and execution by identity.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014G7s6EEb4vJud4aCUkGJQU
CommandConfig now takes an explicit data directory (ICT_DATA_DIR
overrides the platform default), passes the TOML format to night-config
explicitly so native images need no reflection entry, creates its
application directory, and loads defaults from the renamed
ictrc.default.toml, which the old code never found. context() yields a
Context with the active workspace, lazily opened local stores and
stdin. The static INSTANCE singleton is gone; surfaces build one.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014G7s6EEb4vJud4aCUkGJQU
Operations.standard() is the single assembly point for admitted
operations. RegistryConformanceTest fails if any registered tuple is
not named, as the literal text of OperationId.toString(), by some spec
under src/test/groovy, and if any operation is exposed to no surface.
OperationId.parse() turns that literal back into an identity so specs
fetch their operation by the same text. The scanner is checked against
a fake registry in a temp dir.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014G7s6EEb4vJud4aCUkGJQU
Register add/get/remove/list collection in workspace, import/export/
remove calendar and card in collection, and list event/action/note/
entity in collection, as handlers over the connector API with connector
failures mapped to typed OperationExceptions. Each group has a Spock
spec against LocalCalendarStore/LocalCardStore on a temp directory,
naming its tuples for the conformance test. The ten legacy command
classes and their mock-based specs are deleted from src/legacy.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014G7s6EEb4vJud4aCUkGJQU
Renderer turns any Result into text in a Format: iCalendar/vCard,
aligned tables and plain lines for TEXT; jCal/jCard and plain JSON for
JSON; xCal/xCard for XML. jCard is applied per entity, which is what
the serializer expects and why the legacy converter cycled on VCard.
Validation results carry severity, context and message and render in
the old report format. Descriptor attributes keep insertion order.
The legacy DefaultOutputHandlers and its spec are deleted.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014G7s6EEb4vJud4aCUkGJQU
Main builds a verb-first picocli tree from the registry at startup:
one subcommand per verb, one per (verb, subject) under it, options
from the Param descriptors. Global options are inherited, exit codes
are 0/1/2, and diagnostics go to stderr only. `ict config` replaces
ConfigureCommand. The collection operations take `--collection`
rather than `--name`.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Each MCP-exposed operation becomes a `<verb>_<subject>` tool whose
input schema is generated from its Param descriptors, served by the
MCP Java SDK's synchronous server on stdio. Calendars and cards are
returned as text and other results as JSON; operation failures come
back as isError results. stdout carries protocol messages only, and
the server exits when its input closes.

Uses mcp-core with mcp-json-jackson2 rather than the `mcp` aggregate,
which would bring a second Jackson.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Reachability metadata is the spike's base file merged with a capture
from running the smoke suite under the tracing agent
(mergeTracedMetadata). The smoke suite drives any `ict` command
prefix, covering --help, every registered operation and an MCP
handshake, and refuses to run if an operation has no step.
nativeStartup fails if the median `ict --help` exceeds 100 ms.

`export calendar` now adds a VTIMEZONE for each referenced TZID.
`import calendar` adds missing time zones before merging, because the
connector fails with an NPE on multi-object input without them.
SDKROOT is passed through to native-image for macOS 27 hosts.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
build.yml runs the JVM specs and smoke suite on every push and pull
request, plus one linux x64 native smoke and startup job. release.yml
builds and smoke-tests the executable for linux x64/arm64, macOS
arm64 and windows x64, then attaches them with SHA-256 checksums to a
GitHub Release and publishes the jar to Maven Central.
publish-snapshots.yml tests locally instead of calling ical4j's
reusable workflow. The Makefile gains native and smoke targets and
loses the S3 uploadDist. Release tags take the ict- prefix.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The README covers installing a release executable, verb-first usage,
output formats, exit codes, configuration and MCP client setup.
command-protocols.md describes the registry, its CLI and MCP views,
and how an operation is admitted, in place of per-class listings.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Syncs its delta specs into openspec/specs. This adds the cli-surface,
mcp-surface, native-binary and operation-registry capabilities, and
updates command-vocabulary: the vocabulary now lives in the vocab
package and dispatch goes through the registry.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@benfortuna
benfortuna merged commit 0e40854 into develop Oct 11, 2026
4 checks passed
@benfortuna
benfortuna deleted the single-native-binary branch October 11, 2026 02:53
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant