feat(zig-core): introduce build.zig + opsm.zig + ffi.zig bridge

Adds the Zig side of the OPSM ABI/FFI standard layout:

  build.zig          builds the unified \`opsm\` CLI executable and
                     a dynamic \`libodds_and_sods_package_manager\`
                     shared library for Idris2 to call back into
  src/opsm.zig       unified CLI entry — both main \`opsm\` binary
                     and the tool-shim dispatcher when invoked via
                     symlink
  src/abi/ffi.zig    C-compatible FFI implementation matching the
                     %foreign declarations in src/abi/Foreign.idr

Function exports use the \`odds_and_sods_package_manager_\` prefix
required by the Idris2 ABI Foreign module.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: hyperpolymath

build.zig

@@ -0,0 +1,36 @@
+// SPDX-License-Identifier: PMPL-1.0-or-later
+// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath)
+//
+// OPSM Unified CLI — Build Configuration
+
+const std = @import("std");
+
+pub fn build(b: *std.Build) void {
+    const target = b.standardTargetOptions(.{});
+    const optimize = b.standardOptimizeOption(.{});
+
+    // Main CLI (unified binary)
+    const exe = b.addExecutable(.{
+        .name = "opsm",
+        .root_module = b.createModule(.{
+            .root_source_file = b.path("src/opsm.zig"),
+            .target = target,
+            .optimize = optimize,
+        }),
+    });
+    exe.linkLibC();
+    b.installArtifact(exe);
+
+    // FFI Bridge as a shared library (for Idris2 to call)
+    const ffi = b.addLibrary(.{
+        .name = "odds_and_sods_package_manager",
+        .linkage = .dynamic,
+        .root_module = b.createModule(.{
+            .root_source_file = b.path("src/abi/ffi.zig"),
+            .target = target,
+            .optimize = optimize,
+        }),
+    });
+    ffi.linkLibC();
+    b.installArtifact(ffi);
+}

src/abi/ffi.zig

@@ -0,0 +1,134 @@
+// SPDX-License-Identifier: PMPL-1.0-or-later
+// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath)
+//
+// OPSM Idris2 ABI — Zig FFI Implementation
+// =========================================
+// This module implements the C-compatible FFI declared in src/abi/Foreign.idr.
+// All functions are exported with the "odds_and_sods_package_manager_" prefix
+// to match the Idris2 %foreign declarations.
+
+const std = @import("std");
+const mem = std.mem;
+const fs = std.fs;
+const process = std.process;
+
+// --- Types (must match src/abi/Types.idr) ---
+
+pub const Result = enum(u32) {
+    ok = 0,
+    @"error" = 1,
+    invalid_param = 2,
+    out_of_memory = 3,
+    null_pointer = 4,
+};
+
+/// Opaque library handle.
+pub const Handle = struct {
+    allocator: std.mem.Allocator,
+    config_dir: []const u8,
+    runtime_dir: []const u8,
+    shim_dir: []const u8,
+    last_error: ?[]const u8 = null,
+};
+
+// --- Global state ---
+
+var global_allocator = std.heap.c_allocator;
+
+// --- FFI Implementations ---
+
+/// Initialize the OPSM library state.
+/// Returns a pointer to a Handle (u64 in Idris).
+pub export fn odds_and_sods_package_manager_init() ?*Handle {
+    const handle = global_allocator.create(Handle) catch return null;
+
+    // Resolve paths from environment or defaults
+    const home = process.getEnvVarOwned(global_allocator, "HOME") catch "/tmp";
+    const config_dir = std.fmt.allocPrint(global_allocator, "{s}/.opsm", .{home}) catch ".opsm";
+    const runtime_dir = std.fmt.allocPrint(global_allocator, "{s}/runtimes", .{config_dir}) catch ".opsm/runtimes";
+    const shim_dir = std.fmt.allocPrint(global_allocator, "{s}/shims", .{config_dir}) catch ".opsm/shims";
+
+    handle.* = .{
+        .allocator = global_allocator,
+        .config_dir = config_dir,
+        .runtime_dir = runtime_dir,
+        .shim_dir = shim_dir,
+        .last_error = null,
+    };
+
+    return handle;
+}
+
+/// Free the library handle.
+pub export fn odds_and_sods_package_manager_free(handle: ?*Handle) void {
+    const h = handle orelse return;
+    const allocator = h.allocator;
+
+    allocator.free(h.config_dir);
+    allocator.free(h.runtime_dir);
+    allocator.free(h.shim_dir);
+    if (h.last_error) |err| allocator.free(err);
+
+    allocator.destroy(h);
+}
+
+/// Check if library is initialized.
+pub export fn odds_and_sods_package_manager_is_initialized(handle: ?*Handle) u32 {
+    return if (handle != null) 1 else 0;
+}
+
+/// Process data (entry point for commands).
+pub export fn odds_and_sods_package_manager_process(handle: ?*Handle, input: u32) u32 {
+    const h = handle orelse return 0;
+    _ = h;
+    _ = input;
+    // Placeholder for command dispatch
+    return 1; // Ok
+}
+
+/// Get string result from library.
+/// Returns a C string that must be freed with odds_and_sods_package_manager_free_string.
+pub export fn odds_and_sods_package_manager_get_string(handle: ?*Handle) ?[*:0]const u8 {
+    const h = handle orelse return null;
+    _ = h;
+    return null;
+}
+
+/// Free a C string returned by the library.
+pub export fn odds_and_sods_package_manager_free_string(str: ?[*:0]const u8) void {
+    const s = str orelse return;
+    global_allocator.free(mem.span(s));
+}
+
+/// Process array data.
+pub export fn odds_and_sods_package_manager_process_array(handle: ?*Handle, buffer: ?[*]const u8, len: u32) u32 {
+    const h = handle orelse return 1; // Error
+    _ = h;
+    _ = buffer;
+    _ = len;
+    return 0; // Ok
+}
+
+/// Get last error message.
+pub export fn odds_and_sods_package_manager_last_error() ?[*:0]const u8 {
+    // For now, no thread-local storage of last error, just return null or static
+    return null;
+}
+
+/// Get library version.
+pub export fn odds_and_sods_package_manager_version() [*:0]const u8 {
+    return "1.2.0";
+}
+
+/// Get build information.
+pub export fn odds_and_sods_package_manager_build_info() [*:0]const u8 {
+    return "OPSM Unified Zig/Idris2 ABI v1.2.0";
+}
+
+/// Register a callback (C ABI).
+pub export fn odds_and_sods_package_manager_register_callback(handle: ?*Handle, callback: ?*const anyopaque) u32 {
+    const h = handle orelse return 1; // Error
+    _ = h;
+    _ = callback;
+    return 0; // Ok
+}

src/opsm.zig

@@ -0,0 +1,110 @@
+// SPDX-License-Identifier: PMPL-1.0-or-later
+// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath)
+//
+// OPSM Unified CLI
+// ================
+// Principally in Zig, using the Idris2 ABI for type assurance.
+// This binary acts as both the main CLI (when invoked as 'opsm')
+// and the tool shim dispatcher (when invoked via symlink).
+
+const std = @import("std");
+const mem = std.mem;
+const fs = std.fs;
+const process = std.process;
+
+// Import the FFI bridge
+const abi = @import("abi/ffi.zig");
+
+// --- Constants ---
+const VERSION = "1.2.0";
+const HELP_TEXT =
+    \\OPSM — Odds and Sods Package Manager v{s}
+    \\Principally in Zig | Idris2 ABI Assurance | Nickel Metadata
+    \\
+    \\Usage:
+    \\  opsm <command> [args...]
+    \\
+    \\Commands:
+    \\  install <tool> <ver>   Install a tool version
+    \\  remove <tool> [ver]    Remove a tool (or specific version)
+    \\  list                   List installed tools
+    \\  set [-g] <tool> <ver>  Set version in .tool-versions
+    \\  import [file]          Import from asdf .tool-versions
+    \\  doctor                 Check system health
+    \\  version                Show version info
+    \\
+    \\Shim Mode:
+    \\  When symlinked as a tool name (e.g., 'zig', 'deno'), this binary
+    \\  automatically resolves the version and execs the real binary.
+    \\
+;
+
+pub fn main() !void {
+    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
+    defer _ = gpa.deinit();
+    const allocator = gpa.allocator();
+
+    const args = try process.argsAlloc(allocator);
+    defer process.argsFree(allocator, args);
+
+    if (args.len == 0) return;
+
+    const exe_name = fs.path.basename(args[0]);
+
+    // --- Shim Mode Detection ---
+    if (!mem.eql(u8, exe_name, "opsm") and !mem.eql(u8, exe_name, "opsm-shim")) {
+        // Run as shim dispatcher (placeholder: shell out to the existing shim for now
+        // while we migrate the logic into this unified binary)
+        return runShim(allocator, exe_name, args[1..]);
+    }
+
+    // --- CLI Mode ---
+    if (args.len < 2) {
+        std.debug.print(HELP_TEXT, .{VERSION});
+        return;
+    }
+
+    const command = args[1];
+
+    if (mem.eql(u8, command, "version")) {
+        std.debug.print("OPSM v{s}\n", .{VERSION});
+        std.debug.print("ABI: {s}\n", .{abi.odds_and_sods_package_manager_build_info()});
+    } else if (mem.eql(u8, command, "doctor")) {
+        try runShellScript(allocator, "/var/mnt/eclipse/repos/verification-ecosystem/odds-and-sods-package-manager/runtime/opsm-runtime", args[1..]);
+    } else if (mem.eql(u8, command, "import")) {
+        try runShellScript(allocator, "/var/mnt/eclipse/repos/verification-ecosystem/odds-and-sods-package-manager/runtime/opsm-runtime", args[1..]);
+    } else if (mem.eql(u8, command, "plugin")) {
+        // asdf compatibility: 'asdf plugin list' -> 'opsm-runtime plugin list'
+        try runShellScript(allocator, "/var/mnt/eclipse/repos/verification-ecosystem/odds-and-sods-package-manager/runtime/opsm-runtime", args[1..]);
+    } else if (mem.eql(u8, command, "current")) {
+        try runShellScript(allocator, "/var/mnt/eclipse/repos/verification-ecosystem/odds-and-sods-package-manager/runtime/opsm-runtime", args[1..]);
+    } else if (mem.eql(u8, command, "latest")) {
+        try runShellScript(allocator, "/var/mnt/eclipse/repos/verification-ecosystem/odds-and-sods-package-manager/runtime/opsm-runtime", args[1..]);
+    } else {
+        std.debug.print("Command '{s}' not yet implemented in Zig CLI.\n", .{command});
+        std.debug.print("Falling back to opsm-runtime (bash)...\n", .{});
+        try runShellScript(allocator, "/var/mnt/eclipse/repos/verification-ecosystem/odds-and-sods-package-manager/runtime/opsm-runtime", args[1..]);
+    }
+}
+
+fn runShim(allocator: mem.Allocator, exe: []const u8, args: [][:0]u8) !void {
+    _ = allocator;
+    _ = args;
+    // Placeholder: exec existing shim binary
+    // In production, the logic from runtime/shim/src/main.zig will be merged here.
+    std.debug.print("OPSM Unified Shim: Resolving {s}...\n", .{exe});
+}
+
+fn runShellScript(allocator: mem.Allocator, path: []const u8, args: [][:0]u8) !void {
+    const full_args = try allocator.alloc([]const u8, args.len + 1);
+    defer allocator.free(full_args);
+
+    // Find the absolute path to the script relative to the workspace root
+    full_args[0] = path;
+    for (args, 0..) |arg, i| {
+        full_args[i + 1] = arg;
+    }
+
+    var child = process.Child.init(full_args, allocator);
+    _ = try child.spawnAndWait();
+}