Documentation on ketch

Manifests

Mon, 01 Jan 0001 00:00:00 +0000

A manifest is the config for one package: where it comes from, which release asset to take, and what to expose once it is unpacked.

You rarely need one. ketch infers a manifest from owner/repo alone, and that is enough for most projects. Write one when inference gets it wrong — an unusually named asset, a binary that should be linked under a different name, an .app bundle, a short alias worth remembering.

The package registry

Mon, 01 Jan 0001 00:00:00 +0000

The registry is an ordinary GitHub repository. Every top-level folder is a package, and holds one ketch.toml describing it:

ketch-registry/
├── README.md ← not a package: no ketch.toml
├── fd/
│ └── ketch.toml
├── jq/
│ └── ketch.toml
└── ripgrep/
 └── ketch.toml

The folder name is the package name — it is what ketch install <name> matches. There is no index file to keep in step with the contents, and a folder without a ketch.toml is simply not a package, so the repository can carry a README, a licence and CI config alongside the packages.

Source plugins

Mon, 01 Jan 0001 00:00:00 +0000

GitHub is built in. Anything else — GitLab, Gitea, an internal artifact server — can be added as a plugin, without recompiling ketch and without a ketch release.

A plugin is an executable named ketch-source-<scheme>. ketch runs it with a subcommand and reads one JSON document from its stdout. That is the whole contract, so a plugin can be written in any language.

Discovery

ketch looks in ~/.ketch/plugins first, then every directory on PATH. The first ketch-source-<name> found wins, so a copy in the plugins directory shadows one on PATH. ketch plugin list shows what was found and ketch plugin dir prints the directory.

The lockfile

Mon, 01 Jan 0001 00:00:00 +0000

ketch.lock is one machine’s set of tools, pinned to exact releases. Write it, commit it next to your dotfiles, and any other machine can reproduce the same set:

ketch lock # write ./ketch.lock from what is installed
ketch lock --check # has the tree drifted from it?
ketch sync # install what the lockfile names, at those versions

It is not the lock ketch takes while it works — that one is a mutex over the install tree, held for the length of a command and released at the end.

Roadmap

Mon, 01 Jan 0001 00:00:00 +0000

What ketch does not do yet, and what it would take. Order is rough priority, not a schedule.

Linux and Windows

Shipped: src/platform/linux.rs and src/platform/windows.rs, selected from platform::host(). Linux places bin-dir symlinks; Windows copies into the bin dir and records CopiedFile. Trust is NotApplicable until signature verification exists.

ketch path install on Windows writes the user PATH. install.sh fetches the host tarball on macOS, Linux and Windows (Git Bash). release.yml publishes Linux and Windows tarballs next to the signed macOS ones. CI runs each OS’s suite on that OS.

Plan

Mon, 01 Jan 0001 00:00:00 +0000

https://github.com/listepo/ketch Catch releases straight from GitHub — a package manager for GitHub-released binaries and apps.

#	Статус	Приоритет	Сложность	Готовность	Агент
F1	in progress	P2	3	95%	Cursor / grok 4.6
F2	in progress	P2	3	70%	Cursor / grok 4.6
M3	in progress	P2	5	95%	Claude Code / claude-opus-5

F1. Notarisation

The release binaries are signed with a Developer ID but not notarised, which is fine for a curl-fetched tarball and not fine the day ketch ships anything a browser downloads. Needs an App Store Connect key, xcrun notarytool submit --wait in the build job, and a stapled check in the smoke test.

Contributing

Mon, 01 Jan 0001 00:00:00 +0000

Notes for coding agents working in this repository. Humans are welcome to read it too — nothing here is agent-specific except the framing and the rule below.

Mandatory for every agent

The human is the only author. No agent adds a Co-Authored-By trailer, a “Generated with …” line or itself as author to a commit, merge or PR — whatever its harness defaults to. no-agent-attribution in commitlint.config.mjs rejects such a trailer or line in every commit a pull request brings, and in the commit-msg hook. A pull request description is not checked — that part is on the agent.
If a directory above this repository contains an AGENTS.md or CLAUDE.md, follow it too. If it conflicts with this file, ask the creator.

What ketch is

A single-binary CLI package manager that installs command-line tools and macOS apps straight from GitHub releases. No taps, no formulae, no build step: it downloads what a project already ships, verifies it, unpacks it into a store, and links it onto PATH.