theam / theam/facility

Publish the CLI to npm (+ release automation)

Open
#1 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement
Dominant language
TypeScript
Stars
71
Forks
64
Avg merge
15h 38m
Merged PRs (30d)
66

Description

Problem

@theagilemonkeys/facility is not published, so npx @theagilemonkeys/facility … fails for anyone who has not cloned this repository. The CLI only runs from a checkout today, which the README and the CLI reference both say out loud.

That matters beyond convenience: the CLI is how the process gets installed into a repository, and how the platform is operated from a script.

Decided

  • Registry: public npm, under the organization scope theagilemonkeys (@theam on npm belongs to an unrelated developer). The package is already named @theagilemonkeys/facility in packages/cli/package.json and licensed Apache-2.0, matching the repository.
  • Trigger: a tag, never a merge. .github/workflows/release.yml (PR #43) checks that the tag and package.json agree, runs the CLI's tests, installs the packed tarball the way npx would and runs the binary from it, then publishes with provenance.

Remaining

  • Add an npm automation token as the NPM_TOKEN repository secret.
  • Pick the first published version. init stamps FACILITY_VERSION into every rendered file and records facility: <version> in .facility.json, so the published version and the generated artifacts have to stay in lockstep — this is what facility upgrade re-syncs against.
  • Run the workflow manually first; it defaults to a dry run.
  • Publish, then verify npx @theagilemonkeys/facility init end to end from a machine that has never seen this repository.
  • Remove the two "not yet on npm" statements — in README.md and apps/docs/docs/reference/cli.md — once the package is live.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with packages/cli/package.json and .github/workflows/release.yml, then review the version handling described for init and upgrade. Run the release workflow in its default dry-run mode and verify the packed tarball and CLI tests. Done means the package is published under the agreed scope, npx init works on a clean machine, and the outdated statements in README.md and apps/docs/docs/reference/cli.md are removed.

Written by the indexing model from the issue text.

Assessment

Tech stack
github-actions, typescript
Domain
ci-cd, cli, release
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.