# -*- tcl -*-
# Maintenance Instruction: leave the 999999.xxx.x as is and use 'pmix make' or src/make.tcl to update from <pkg>-buildversion.txt
#
# Please consider using a BSD or MIT style license for greatest compatibility with the Tcl ecosystem.
# Code using preferred Tcl licenses can be eligible for inclusion in Tcllib, Tklib and the punk package repository.
# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++
# (C) 2026
#
# @@ Meta Begin
# Application punk::platform 999999.0a1.0
# Meta platform     tcl
# Meta license      BSD
# @@ Meta End


# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++
##  Requirements
package require platform ;#Tcl's own platform package (vendored 1.0.19 in kits; 1.1.x in tcl9 core) - the RAW identifier underneath this module's normalization


# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++
namespace eval punk::platform {
    #punk::platform - the CANONICAL punkshell platform naming layer (2026-07-22
    #platform-folder synchronization; groundwork for the G-105 cross-target arc).
    #
    #punkshell artifact trees are organized by PLATFORM-DIR names of the form
    #<os>-<cpu> (e.g win32-x86_64), used by: the punkbin artifact repo's top-level
    #folders, bin/runtime/<platform>/ (the runtime store punk-runtime manages),
    #lib_tclX/<platform> + vendorlib_tclX/<platform> auto_path dirs (wired by the
    #boot machinery), and the G-103 runtime artifact metadata 'target' field.
    #
    #Tcl's platform package remains the raw identifier (platform::generic /
    #platform::identify) but its outputs vary by version and pass some machine
    #names through unmapped - the differences this module's normalize absorbs:
    #  - cpu 'amd64' (BSD machine names)   -> x86_64
    #  - cpu 'aarch64' (linux arm64)       -> arm64
    #  - os  'macos' (platform 1.1.x on osVersion>19; older versions and the
    #    boot's snipped copy say 'macosx') -> macosx
    #  - macosx cpu 'arm' -> arm64 (platform::generic's 'arm*' glob collapses
    #    the darwin 'arm64' machine name to 'arm'; Apple silicon is 64-bit only,
    #    so the arm token on macosx always means arm64. Elsewhere 'arm' is a
    #    genuine 32-bit token and is preserved.)
    #The special name 'macosx' (no cpu suffix) is the RUNTIME-tier convention for
    #universal (multi-arch) macOS binaries - punkbin and bin/runtime keep one
    #universal folder; the per-arch macosx-x86_64/macosx-arm64 names serve the
    #lib-tree tier where per-arch payloads are the norm.
    #
    #The boot machinery (punkboot::lib in src/vfs/_config/punk_main.tcl /
    #project_main.tcl and src/make.tcl) cannot 'package require' at its stage and
    #carries a snipped platform::generic plus an inline copy of THIS module's
    #normalization mapping - if the mapping here changes, those copies must
    #change with it (each carries a pointer comment to this module).

    namespace eval argdoc {
        variable PUNKARGS
    }

    #canonical platform records. status:
    #  supported  - a punkshell target: artifact trees exist or are planned and
    #               tooling/build arcs (G-103/G-105) treat it as a real target
    #  dormant    - recognized and folders may exist, but utility is under review
    #  recognized - a name the naming scheme reserves; no artifacts or tooling yet
    #tiers: which artifact-tree tiers use the name -
    #  runtime = punkbin platform folders + bin/runtime/<platform>/
    #  lib     = lib_tclX/<platform> + vendorlib_tclX/<platform> auto_path dirs
    variable platforms {
        win32-x86_64        {status supported  tiers {runtime lib} notes "primary development platform"}
        linux-x86_64        {status supported  tiers {runtime lib} notes ""}
        linux-arm64         {status supported  tiers {runtime lib} notes "aarch64; punkbin's existing arm kit predates the arm64 name and sits in linux-arm"}
        linux-arm           {status supported  tiers {runtime lib} notes "32-bit arm"}
        macosx              {status supported  tiers {runtime}     notes "universal (multi-arch) macOS binaries - runtime tier keeps one folder"}
        macosx-x86_64       {status supported  tiers {lib}         notes ""}
        macosx-arm64        {status supported  tiers {lib}         notes "Apple silicon"}
        freebsd-x86_64      {status supported  tiers {runtime lib} notes ""}
        freebsd-arm64       {status supported  tiers {runtime lib} notes "no artifacts yet"}
        msys-x86_64         {status dormant    tiers {lib}         notes "msys/cygwin-built tclsh runtimes; utility under review"}
        openbsd-x86_64      {status recognized tiers {}            notes ""}
        netbsd-x86_64       {status recognized tiers {}            notes ""}
        dragonflybsd-x86_64 {status recognized tiers {}            notes ""}
    }

    namespace eval argdoc {
        variable PUNKARGS
        lappend PUNKARGS [list {
            @id     -id     ::punk::platform::platforms
            @cmd    -name   punk::platform::platforms\
                -summary\
                    "Canonical punkshell platform records."\
                -help\
                    "Return the canonical punkshell platform-name records as a dict
                    keyed by platform-dir name (e.g win32-x86_64). Each value is a
                    dict with keys:
                      status  supported|dormant|recognized
                      tiers   which artifact-tree tiers use the name
                              (runtime = punkbin + bin/runtime folders,
                               lib = lib_tclX/vendorlib_tclX auto_path dirs)
                      notes   free-text qualifiers
                    These names are the contract for punkbin platform folders,
                    bin/runtime/<platform>/, lib_tclX/vendorlib_tclX platform
                    dirs and the G-103 runtime-artifact metadata target field.
                    See also 'help platforms' in the punk shell."
            @values -min 0 -max 0
        }]
    }
    proc platforms {} {
        variable platforms
        return $platforms
    }

    namespace eval argdoc {
        variable PUNKARGS
        lappend PUNKARGS [list {
            @id     -id     ::punk::platform::normalize
            @cmd    -name   punk::platform::normalize\
                -summary\
                    "Normalize a platform identifier to the canonical punkshell name."\
                -help\
                    "Normalize a platform::generic-style <os>-<cpu> identifier (or an
                    already-canonical punkshell name) to the canonical punkshell
                    platform-dir name:
                      cpu amd64 -> x86_64, aarch64 -> arm64
                      os macos -> macosx (Tcl platform 1.1.x renamed modern macOS)
                      macosx cpu arm -> arm64 (platform::generic's arm* glob folds
                      the darwin arm64 machine name to arm; Apple silicon is
                      64-bit only - non-macosx 'arm' stays 32-bit arm)
                    Unrecognized os/cpu tokens pass through unchanged - normalize
                    never invents names, it only folds known aliases."
            @values -min 1 -max 1
                platform -type string -help\
                    "Platform identifier, e.g the result of platform::generic."
        }]
    }
    proc normalize {platform} {
        set parts [split $platform -]
        if {[llength $parts] < 2} {
            #single-token names (e.g the universal 'macosx') - fold macos only
            if {$platform eq "macos"} {
                return macosx
            }
            return $platform
        }
        #os may itself contain a dash in principle - treat last token as cpu
        set cpu [lindex $parts end]
        set os  [join [lrange $parts 0 end-1] -]
        switch -- $os {
            macos {set os macosx}
        }
        switch -- $cpu {
            amd64   {set cpu x86_64}
            aarch64 {set cpu arm64}
            arm {
                if {$os eq "macosx"} {
                    set cpu arm64
                }
            }
        }
        return "${os}-${cpu}"
    }

    namespace eval argdoc {
        variable PUNKARGS
        lappend PUNKARGS [list {
            @id     -id     ::punk::platform::local
            @cmd    -name   punk::platform::local\
                -summary\
                    "Canonical punkshell platform name of the running interpreter."\
                -help\
                    "Return the canonical punkshell platform-dir name for the running
                    interpreter: platform::generic normalized per
                    punk::platform::normalize.
                    With -tier runtime, macosx per-arch names collapse to the
                    universal 'macosx' (the runtime-store convention: punkbin and
                    bin/runtime keep one universal macOS folder; the same collapse
                    src/make.tcl applies when locating bin/runtime/<platform>).
                    -tier lib (the default) returns the per-arch name used by the
                    lib_tclX/vendorlib_tclX auto_path dirs."
            @opts
                -tier -type string -default lib -choices {lib runtime} -help\
                    "Artifact-tree tier the name is for."
            @values -min 0 -max 0
        }]
    }
    proc local {args} {
        set tier lib
        foreach {k v} $args {
            switch -- $k {
                -tier {
                    if {$v ni {lib runtime}} {
                        error "punk::platform::local - invalid -tier '$v' (expected lib|runtime)"
                    }
                    set tier $v
                }
                default {
                    error "punk::platform::local - unknown option '$k' (known: -tier)"
                }
            }
        }
        set p [normalize [::platform::generic]]
        if {$tier eq "runtime" && [string match macosx-* $p]} {
            return macosx
        }
        return $p
    }
}


namespace eval ::punk::args::register {
    #use fully qualified so 8.6 doesn't find existing var in global namespace
    lappend ::punk::args::register::NAMESPACES ::punk::platform
}


# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++
##  Ready
package provide punk::platform [namespace eval punk::platform {
    variable version
    set version 999999.0a1.0
}]
return