joshuacc / ahkpm Goto Github PK

This command looks at the current list of dependencies in ahkpm.json and attempts to reinstall them all.

Right now it has a lot of filler inherited from the Doks child theme, but nothing specific to the ahkpm site. It should be updated to be more focused and to provide basic information on editing the site.

This is a relatively simple change to make. The install function just needs to take the current logic for a single argument and run it in a loop over all arguments.

Change should be made here: https://github.com/joshuacc/ahkpm/blob/main/src/cmd/install.go#L41

Some limitations that need to be called out.

• GitHub only for the time being
• Doesn't resolve transitive dependencies yet (so not yet useful in building a package that depends on other packages)
• Doesn't support version ranges a la npm
• Doesn't have a lockfile, so reinstalling a mutable version (technically everything in git, but most problematic for branches) may result in the code changing out from under you. For this reason stick to semver (tags underneath), tags, or commits for versions, not branches
• No installer for ahkpm itself, or mechanism to update automatically
• Doesn't warn about incompatibilities between a package's expected version of AutoHotKey and the version actually installed

To minimize disruption by network failures, keep a cache of libraries recently downloaded using their name and version as the cache key.

#42 is a prerequisite

Preferably with a minimum coverage threshold (or at least a report)

In order to get accurate code coverage results. We need to require this for PRs so that we don't accidentally regress the next time we create a new package.

Perhaps add a new mage script that scans the src folder, extracts all packages with a regex, dedupes them, and ensures that every package not ending in _test has a corresponding _test package?

That script should be added to the verify script as well.

It should support easily bumping path, minor, or major versions, ideally in a guided way to minimize the amount of incorrect version bumps.

Similar in spirit to bower's version command.

Because ahkpm uses git for dependencies, almost everything that we rely on to identify the correct version of a dependency's code is mutable. That means that if a user reinstalls branch:main, the code may have changed out from under the user without their knowledge. To mitigate this, we should add a lockfile (ahkpm.lock?) which records, at a minimum, the exact commit that a dependency resolved to when it was first installed. And when reinstalling that dependency, we should use that commit rather than whatever commit version identifier now resolves to.

Upgrading direct dependencies should be a conscious choice, not accidental or automatic.

This involves the following:

• Deciding on a lockfile format
• Recording/updating the lockfile on installations
• Install purely from the lockfile if there are no dependency changes
• Using the contents of the lockfile to guide ahkpm install when a dependency's version has changed
• Using the contents of the lockfile to guide ahkpm install when there is a new dependency

These are just my initial thoughts. Would love to hear from others as well.

AutoHotKey

✅ It's the language of the AHK community
❌ It's not really that great for general purpose programming
❌ No package management (yet) so would have to rely on a lot of copy-paste and/or custom code that could be left to libraries in other languages
❌ I don't know it very well

JavaScript/TypeScript

✅ I know it extremely well
✅ Commonly known
✅ Good package management
❌ Not a good way to produce standalone binaries

Rust

✅ Easily compiles to a standalone binary
✅ Plenty fast enough
✅ Good package management
❌ Very complicated language relative to what is needed (the memory model being the most complicated piece)
❌ I don't know it (yet)

Go

✅ Easily compiles to a standalone binary
✅ Plenty fast enough
✅ Well suited to the task at hand
❓ Package management
❌ I don't know it (yet)

As of right now, ahkpm does not resolve dependencies of dependencies which are declared through ahkpm.json. (It does, however, resolve nested git modules.)

Consider a package github.com/joshuacc/top-level had an ahkpm.json file which declared a dependncy on github.com/joshuacc/second-level. If a consumer runs ahkpm install github.com/joshuacc/top-level, they will get the code for top-level, but not the code for second-level.

To be viable beyond personal use as a convenient downloader, ahkpm must resolve those dependencies and install them as well.

In order to make it easier to contribute.

At the moment the entire contents of a module's git repo gets copied into ahkpm-modules, but the .git directories are useless at best and a waste of space at worst.

I suspect that it is a relatively simple change to fix this behavior.

The implementation of the file copying is here: https://github.com/joshuacc/ahkpm/blob/main/src/core/packages_repository.go#L27

It should go under docs > advanced.

ahkpm install <package>@<version> <package2>@<version>

Add to branch protection

The current binary size is about 18 megabytes(!) due to embedding the entire spdx license list into the binary. We may need to split it out entirely in the future, but just eliminating all the unnecessary details should shrink the size substantially.

This involves:

• Setting up a build hook with Netlify for ahkpm.dev
• Adding a new GitHub action that invokes the hook when a new release is created.

Ideally, we should also have a shortcode that allows us to easily reference the latest version in the content of ahkpm.dev.

Add to branch protection

Something like the following.

> ahkpm install
Installing all dependencies
No dependency changes found. Installing from lockfile.

A newer version of ahkpm is available.
Installed version: ahkpm 0.3.0
Latest version:    ahkpm 0.4.0

View release notes and download at: https://github.com/joshuacc/ahkpm/releases/tag/0.4.0

• ahkpm update to update all dependencies
• ahkpm update <name> to update a specific dependency (and entire sub tree)

ahkpm install github.com/joshuacc/[email protected] should present a friendly message stating that the package doesn't exist.

ahkpm install github.com/joshuacc/doesexist@tag:doesnotexist should present a friendly message stating that the version doesn't exist.

In addition to the unit tests we currently have, we also need to add end-to-end tests which exercise all critical paths in the ahkpm.

• ahkpm init
• ahkpm install with a new dependency
• ahkpm install with no dependency changes
• ahkpm update

The tests should assert that the commands made the real world changes they were expected to. Mostly changes to ahkpm.json, ahkpm.lock, and the ahkpm-modules folder.

Ideally should cache both go modules and the golangci-lint binary.

https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows

Running ahkpm install github.com/user/repo should do the following:

1. Attempt to download the tarball from the repo (from the main/master branch)
2. If successful, extract it into ahkpm_libs
3. If successful, record it into ahkpm.json as "github.com/user/repo": "${branch/commit identifier}"

Open question: What version identifier should we use by default? Branch name? Then things may break when the branch is updated. Specific commit? It won't change, but it's pretty inscrutable. Tag name? Seems reasonable, but would require either decent knowledge of git by the user or adherence to a naming/versioning convention by library authors.

We might be able to get adherence to a convention, but that would be a long slow slog of evangelizing ahkpm to AHK library authors.

TODO:

• Scaffold command
• Save results to ahkpm.json
• Support tag: version identifiers
• Support branch: version identifiers
• Support commit: version identifiers
• Support exact SemVer version identifiers

Defer to future version

• Support omitting version identifiers
• Support version ranges/shorthands

This involves setting up GitHub pages (or Netlify?) to build a site based on the ahkpm docs, as well as getting the ahkpm.dev domain pointing at the site.

• Set up ahkpm.dev to publish on Netlify with a decent Hugo theme
• Outline contents of the site
• Add basic getting started info
• Open issues for additional documentation

Upgrades ahkpm itself to the latest version

While there are several open documentation issues already, this issue is for discussion of documentation improvements as a whole.

Docs that we have:

• Minimal help at the command line
• The README
• ahkpm.dev, which is basically a nicer looking rehash of the README
  • The repo for the site: https://github.com/joshuacc/ahkpm.dev

Questions to answer:

• What are the biggest shortcomings in ahkpm's documentation?
• How specifically do we address them?
• Will doing piecemeal improvements get us to where we want to go? Or do we need to be more deliberate in planning out the documentation?

@hwayne, I'd be especially interested in your input.

Ideal scenario:

• User attempts to install a library
• That library has specified the version of AHK it requires
• ahkpm checks that version against the version of AHK installed/running on the user's machine
• If the versions are not compatible it issues a friendly warning

See the comment here for how to do it: #7 (comment)

ahkpm list should list all local packages and their installed versions
ahkpm list <name> should list the specified package with its version

Going forward we need to keep a changelog, so for version 0.2.0, I'll write the first one.

• Right now ahkpm init prompts for several pieces of information, but many of them could be populated by sensible defaults. See code comments for details.
• Implement validation on inputs, including the "Is this correct?" prompt

Perhaps using this? https://github.com/mh-cbon/go-msi

Perhaps using a github topic like ahkpm-package to filter github repositories gh docs

So ahkpm search mypackage would look for repositories with the topic ahkpm-package which match mypackage

• Write fuller help descriptions for all commands in the code itself
• Reorganize commands code to get better docs from cobra
• Add a mage script to automatically generate markdown from the code
• Update ahkpm.dev with the new command docs
• Update readme with new command docs

If a package is located on GitHub, users should be able to install it and refer to it via shorthand. For example, github.com/joshuacc/my-lib could be shortened to joshuacc/my-lib.

This should work in any command that accepts a package identifier, such as ahkpm install and ahkpm list. The shorthand should not be recorded into ahkpm.json, however.

If ahkpm encounters the shorthand in ahkpm.json it should either error or automatically correct it.

Following up from #42

Since #74, running ahkpm install without any top level dependency changes means that the dependency tree as a whole will remain the same. However, if a new dependency is added or an existing dependency is updated, the entire dependency tree is recalculated for all top-level dependencies, potentially resulting in transitive dependency churn even if the top-level dependency and version didn't change.

This is likely fine most of the time, but would likely be confusing and hard to debug without fairly deep understanding of ahkpm (or package management in general).

To fix this, we need to do the following:

• Take the existing dependency tree from ahkpm.lock
• For each new top-level dependency, fully resolve it's dependency subtree and add it to the tree
• For each updated top-level dependency, fully resolve it's dependency subtree and splice it into the tree, replacing the existing subtree