Files in the top-level directory of check-in 0939f53cd9b0996a

Package Client Toolset (pkgt)

Secure, cross‑platform package delivery for Tcl and Eagle — designed to fetch on‑demand or pre‑install packages with cryptographic verification.

Why pkgt?
What’s in this repo
Security model at a glance
Supported runtimes & prerequisites
Quick start (consumers)
- Tcl
- Eagle
Quick start (package producers & maintainers)
How it works (architecture)
Configuration
FAQ
Contributing
License

Why pkgt?

Distributing Tcl/Eagle packages has traditionally involved a mix of ad‑hoc steps, platform quirks, and trust problems. pkgt addresses this by:

Fetching on demand (transparent to package require) or pre‑installing ahead of time.
Verifying everything: package metadata and files are OpenPGP signed; Eagle scripts are also signed with Harpy.
Working for both Tcl and Eagle with the same client toolset.

What’s in this repo

.
├─ client/1.0/neutral/
│  ├─ VERSION               # current toolset version (e.g., 1.0.10)
│  ├─ common.tcl            # shared Tcl helpers
│  ├─ pkgIndex.tcl          # Tcl-side integration
│  ├─ pkgIndex.eagle        # Eagle-side integration (Harpy-signed variants included)
│  ├─ pkgd.eagle            # package downloader library (client side)
│  ├─ pkgr.eagle            # package repository client library
│  ├─ pkgu.eagle            # package uploads client library
│  ├─ pkgr_setup.eagle      # setup/configure repositories & keys
│  ├─ pkgr_install.eagle    # install/persist packages locally
│  └─ pkgr_upload.eagle     # upload/publish packages (maintainers)
├─ externals/
│  ├─ Eagle/lib/Eagle1.0/   # Eagle library packaged for Tcl
│  └─ Harpy/Tools/sign.eagle# Harpy code-sign tooling
├─ tools/
│  ├─ deploy.bat
│  ├─ pkgr_an_d_get.sh
│  └─ pkgr_an_d_install.sh  # helper scripts to fetch/install the client
└─ doc/
   └─ v1.html               # v1 toolset documentation (reference)

File names and layout above come from the initial import. See the commit tree for the authoritative list. The current version is 1.0.10.

Security model at a glance

Metadata path: The client asks a repository service for a package that satisfies a TIP #268 version requirement. The server returns a small signed script that knows what to fetch.
File path: The client downloads one or more OpenPGP‑signed files and verifies them before the package is made available to the interpreter.
Eagle scripts: In addition to OpenPGP, Harpy signatures are verified for Eagle files.

Result: You get transparent, on‑demand package resolution with end‑to‑end verification — suitable for both public and private repositories.

Supported runtimes & prerequisites

Tcl: Standard Tcl (8.5+) environments.
Eagle: Any environment that can run Eagle scripts.
Platforms: Windows, Linux, macOS (no OS‑specific assumptions in the client libraries).
OpenPGP: An implementation of the OpenPGP standard (e.g. GPG).
Tools inside this repo:
- Tcl integration via client/1.0/neutral/pkgIndex.tcl and client/1.0/neutral/common.tcl.
- Eagle integration via client/1.0/neutral/pkgIndex.eagle (+ Harpy-signed variants).
- Harpy signing utility at externals/Harpy/Tools/sign.eagle.
- Eagle library packaged for Tcl under externals/Eagle/lib/Eagle1.0/.

When using the official Package Client Toolset, Package Repository Server, or Package Downloads Server, you will need to add the Primary Package Signing Key (dated "2003-06-09", with fingerprint "C3C7 5138 83EE DD3A ED1F E425 502C 96AF 495D C2D9") to your local OpenPGP key ring.

Quick start (consumers)

Tcl (consumers)

Vendor the client (recommended layout):

   your-project/
     vendor/pkgt/           # this repo (or a release snapshot)
       client/1.0/neutral/  # Tcl/Eagle indices + client libs
       externals/           # Eagle + Harpy helpers

Add pkgt to Tcl’s search path (e.g., early in your app bootstrap):

```tcl # Point this to where you vendored pkgt set pkgtRoot [file normalize [file join [pwd] vendor pkgt]]

# Add pkgt client + externals to Tcl's auto_path: lappend ::auto_path [file join $pkgtRoot client 1.0 neutral] lappend ::auto_path [file join $pkgtRoot externals Eagle lib Eagle1.0] ```

Configure repositories / keys The easiest path is to use the Eagle setup script (ships with the client):

   # From Tcl, invoke Eagle to run the setup, or run it once offline with an
   # Eagle interpreter (see the Eagle quick start below).
   # After setup, your configuration will be persisted for subsequent runs.

Use packages normally With the indices on your path, package require <name> ?version? will be satisfied locally or resolved via pkgt’s secure repository client (on demand).

Tip: If you prefer to pre‑install packages into an application image or cache, run the pkgr_install.eagle helper once and ship the resulting package tree with your app.

Eagle (consumers)

Vendor the client as above.
Add pkgt to the Eagle package path, then run setup:

```tcl # Inside Eagle set pkgtRoot [file normalize "./vendor/pkgt"] path add [file join $pkgtRoot client 1.0 neutral]

# Optional: also add externals if not on your path already path add [file join $pkgtRoot externals Eagle lib Eagle1.0]

# Run interactive/CLI setup to register repository endpoints and API keys: source [file join $pkgtRoot client 1.0 neutral pkgr_setup.eagle] ```

Pre‑install (optional):

   # Still in Eagle
   source [file join $pkgtRoot client 1.0 neutral pkgr_install.eagle]
   # Follow prompts or pass arguments to install and persist selected packages.

Use packages:

   # Resolve on-demand (transparent)
   package require MyPkg 1.2

All of the above entry points (pkgr_setup.eagle, pkgr_install.eagle) are part of the client client/1.0/neutral directory.

Quick start (package producers & maintainers)

Authoring a package

Write your package the normal Tcl/Eagle way:
- Provide a pkgIndex.tcl and/or pkgIndex.eagle that does package provide <name> <version>.
- Organize your files under a single directory named after your package.
Test locally: ensure package require <name> <version> works from a clean interpreter when your package directory is on auto_path (Tcl) or path (Eagle).
Decide distribution mode:
- On‑demand: pkgt can fetch files individually as directed by repository metadata.
- Pre‑installable: you can ship the package directory as a ready‑to‑use tree.

The pkgt repository server resolves a TIP #268 version constraint, returns a small signed script, and instructs the downloader which files to fetch. All files are OpenPGP‑signed; Eagle files are also Harpy‑signed.

Signing your artifacts

Harpy (Eagle): use the included Harpy tool to sign Eagle scripts:

  # Eagle
  source [file join $pkgtRoot externals Harpy Tools sign.eagle]
  # See 'sign.eagle' usage for signing options.

(Tool location: externals/Harpy/Tools/sign.eagle.)

OpenPGP (all files): ensure each distributed file has an OpenPGP signature the client can verify. (The client will refuse unsigned or invalidly signed files.)

Uploading / publishing

Use the uploads client and/or helper:

# Eagle
set pkgtRoot [file normalize "./vendor/pkgt"]
path add [file join $pkgtRoot client 1.0 neutral]

# Upload tool:
source [file join $pkgtRoot client 1.0 neutral pkgr_upload.eagle]

The repository (metadata) server is managed via a web UI; the file server typically runs on Fossil and uses repository users/keys for access. Public and private publishing models are supported.

How it works (architecture)

Repository Client (pkgr.eagle) Locates packages meeting a TIP #268 constraint by talking to the repository service, receives a signed resolver script, verifies it, and evaluates it (in Tcl or Eagle as appropriate).
Downloader (pkgd.eagle) Fetches one or more OpenPGP‑signed files, verifies signatures, and exposes the package to the interpreter. Optionally persists installed packages to a local cache or application image.
Uploads Client (pkgu.eagle) Assists maintainers in pushing new versions to the repository/file server.
Language integration pkgIndex.tcl and pkgIndex.eagle provide seamless integration so ordinary package require requests trigger the above flow if the package isn’t present locally. Harpy‑signed index variants are provided for Eagle.

A short slide deck from Tcl’16 gives a good overview of this flow and security model.

Configuration

Run once: pkgr_setup.eagle to register:
- One or more repository endpoints (metadata server URLs).
- File server base URLs.
- API keys (read and full) for private/personal repositories.
Persisted settings: setup writes settings that subsequent runs of the client will use automatically (both for on‑demand resolution and pre‑installation). See doc/v1.html for parameter names and advanced options.

FAQ

Q. Does this replace pkgIndex.tcl? A. No. pkgt uses normal package metadata; it just enables secure remote resolution and delivery when a required package is not available locally.

Q. How are Eagle scripts treated differently? A. They carry two signatures: OpenPGP (like all files) and Harpy (Eagle‑specific). Both must validate before the package is exposed to the interpreter.

Q. Can I keep some packages private? A. Yes. Repository access uses API keys; file serving can be on a private Fossil instance. Public/private mixes are supported.

Q. What version of the pkgt client is this? A. See client/1.0/neutral/VERSION (currently 1.0.10).

Contributing

Open issues and PRs are welcome.
Please test on both Tcl and Eagle when touching shared client code (client/1.0/neutral/).
Keep security guarantees intact: never merge changes that weaken signature checks or disable verification by default. (Harpy and OpenPGP verification are core to pkgt.)

License

This project is available under the BSD 3‑Clause license. See LICENSE.

References & further reading

Repo overview & purpose: “securely obtain and use packages for both Tcl and Eagle” — GitHub repo description.
Initial import & file layout (client libraries, indices, tools, externals, docs).
Version file (client/1.0/neutral/VERSION: 1.0.10).
Security & architecture slides (Tcl’16 talk: Package Repository Client & Server).

Maintainers: if you’d like, I can also add a minimal Makefile (or simple tclsh/Eagle scripts) to automate setup → install → smoke-test locally using the helper entry points above.