@hardfin/cli 0.1.1-dev.83 → 0.2.0-dev.85
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +85 -23
- package/dist/check-Di68wbxY.js +907 -0
- package/dist/cli.js +5 -5
- package/dist/completion-tree.json +1 -1
- package/dist/{notice-C6Hg9htX.js → notice-BKhXs3Hh.js} +57 -13
- package/dist/{program-B6qcp52R.js → program-mlz1idzc.js} +116 -76
- package/package.json +2 -10
- package/templates/AGENTS.md +3 -1
- package/dist/check-CPd5pMmK.js +0 -502
- package/skills/hardfin-cli/SKILL.md +0 -222
package/README.md
CHANGED
|
@@ -27,8 +27,9 @@ hardfin init
|
|
|
27
27
|
hardfin login
|
|
28
28
|
```
|
|
29
29
|
|
|
30
|
-
`init`
|
|
31
|
-
|
|
30
|
+
`init` downloads the Hardfin skills from [hardfinhq/skills](https://github.com/hardfinhq/skills)
|
|
31
|
+
and writes a Hardfin section in `AGENTS.md`. Coding agents load both on their own. The skills
|
|
32
|
+
say how to find records, count them, import them and read errors.
|
|
32
33
|
[Setting up a project for agents](#setting-up-a-project-for-agents) lists every file `init`
|
|
33
34
|
writes.
|
|
34
35
|
|
|
@@ -75,22 +76,22 @@ off. A run with `CI` set never checks, and neither does `hardfin mcp`.
|
|
|
75
76
|
|
|
76
77
|
`hardfin update` installs only where it owns the install. It never runs `sudo`.
|
|
77
78
|
|
|
78
|
-
| Installed with | `hardfin update`
|
|
79
|
-
| ---------------------------------------------------- |
|
|
80
|
-
| `npm install -g`, in a folder this account can write | Runs `npm install -g` with the same prefix, then refreshes the
|
|
81
|
-
| `npm install -g`, in a folder another account owns | Prints `npm install -g @hardfin/cli@latest`, and fails
|
|
82
|
-
| `npx` | Prints `npx -y @hardfin/cli@latest`, and fails
|
|
83
|
-
| Volta, pnpm, Yarn or Bun | Prints that tool's install command, and fails
|
|
84
|
-
| A project's `package.json` | Prints `npm install @hardfin/cli@latest` for that project, and fails
|
|
85
|
-
| A clone of this repository | Prints the git and build commands, and fails
|
|
79
|
+
| Installed with | `hardfin update` |
|
|
80
|
+
| ---------------------------------------------------- | --------------------------------------------------------------------- |
|
|
81
|
+
| `npm install -g`, in a folder this account can write | Runs `npm install -g` with the same prefix, then refreshes the skills |
|
|
82
|
+
| `npm install -g`, in a folder another account owns | Prints `npm install -g @hardfin/cli@latest`, and fails |
|
|
83
|
+
| `npx` | Prints `npx -y @hardfin/cli@latest`, and fails |
|
|
84
|
+
| Volta, pnpm, Yarn or Bun | Prints that tool's install command, and fails |
|
|
85
|
+
| A project's `package.json` | Prints `npm install @hardfin/cli@latest` for that project, and fails |
|
|
86
|
+
| A clone of this repository | Prints the git and build commands, and fails |
|
|
86
87
|
|
|
87
88
|
A failure here has the code `update_unavailable`, and its message ends with the command to
|
|
88
89
|
run. A preview updates to the newer of the next preview and the next release.
|
|
89
90
|
|
|
90
91
|
After installing, `hardfin update` runs `hardfin init --skills-only` with the new version when
|
|
91
|
-
the working directory holds the
|
|
92
|
-
and leaves `AGENTS.md` and the MCP configs alone. Run
|
|
93
|
-
other project you set up.
|
|
92
|
+
the working directory holds the skills `hardfin init` wrote. That downloads the newest skills
|
|
93
|
+
release the new version works with, and leaves `AGENTS.md` and the MCP configs alone. Run
|
|
94
|
+
`hardfin init --skills-only` in any other project you set up.
|
|
94
95
|
|
|
95
96
|
## The command surface
|
|
96
97
|
|
|
@@ -585,14 +586,14 @@ hardfin init --local # set up the server this CLI runs, in place of the hoste
|
|
|
585
586
|
`hardfin init` gets a project ready for a coding agent to use Hardfin, the way EmDash's starter
|
|
586
587
|
projects come ready. Running it again updates only what it wrote.
|
|
587
588
|
|
|
588
|
-
| File
|
|
589
|
-
|
|
|
590
|
-
| `.agents/skills
|
|
591
|
-
| `.claude/skills
|
|
592
|
-
| `AGENTS.md`
|
|
593
|
-
| `.mcp.json`
|
|
594
|
-
| `.cursor/mcp.json`
|
|
595
|
-
| `.vscode/mcp.json`
|
|
589
|
+
| File | What init writes |
|
|
590
|
+
| ------------------------- | ------------------------------------------------------------------- |
|
|
591
|
+
| `.agents/skills/<skill>/` | Every Hardfin skill, which Codex and most agents read |
|
|
592
|
+
| `.claude/skills/<skill>/` | The same skills, where Claude Code reads them |
|
|
593
|
+
| `AGENTS.md` | A Hardfin section between `hardfin:start` and `hardfin:end` markers |
|
|
594
|
+
| `.mcp.json` | The `hardfin` server, for Claude Code |
|
|
595
|
+
| `.cursor/mcp.json` | The `hardfin` server, for Cursor |
|
|
596
|
+
| `.vscode/mcp.json` | The `hardfin` server, for VS Code |
|
|
596
597
|
|
|
597
598
|
The server is the hosted one at the authorization server's host, `https://api.hardfin.com/mcp`
|
|
598
599
|
by default. [Serving an agent](#serving-an-agent) says how it differs from the local server
|
|
@@ -608,8 +609,69 @@ without `--local` to go back to the hosted server.
|
|
|
608
609
|
address goes into files every agent in the project reads. Pass `--issuer-url` to use it. The
|
|
609
610
|
address must be https, or this machine.
|
|
610
611
|
|
|
611
|
-
The
|
|
612
|
-
|
|
612
|
+
The section lives in `templates/AGENTS.md`, which ships in the npm package. The skills do not.
|
|
613
|
+
|
|
614
|
+
### The skills
|
|
615
|
+
|
|
616
|
+
The skills are authored in [hardfinhq/skills](https://github.com/hardfinhq/skills), and each
|
|
617
|
+
release publishes them as one archive with its SHA-256 checksum beside it. A CLI release declares
|
|
618
|
+
the skills releases it works with, `SKILLS_RANGE` in `src/skills/release.ts`, now `>=1.0.0 <2.0.0`,
|
|
619
|
+
because the `hardfin-cli` skill names commands and flags.
|
|
620
|
+
|
|
621
|
+
| Step | What `init` does |
|
|
622
|
+
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
|
|
623
|
+
| Find the release | The newest in the range, or the one `--skills-version` names, from GitHub's API |
|
|
624
|
+
| Download | Over HTTPS, without git. With `GH_TOKEN` or `GITHUB_TOKEN` set, through the API, which also reaches a private repository |
|
|
625
|
+
| Check | Refuses an archive whose SHA-256 differs from the published one, or that holds a link or a path outside its folder |
|
|
626
|
+
| Write | Every skill, into `.agents/skills/` and `.claude/skills/`. Each `SKILL.md` records the release under `metadata.hardfin-skills-release` |
|
|
627
|
+
|
|
628
|
+
When GitHub cannot be reached, or answers 404 for a private repository, `init` still writes
|
|
629
|
+
`AGENTS.md` and the MCP configs and exits 0. Its output carries `skills.status: "unavailable"`,
|
|
630
|
+
the reason, and how to install the skills by hand without git.
|
|
631
|
+
|
|
632
|
+
### The skills check
|
|
633
|
+
|
|
634
|
+
Every command checks for the skills an agent working in the folder would read. It looks in
|
|
635
|
+
`.agents/skills/` and `.claude/skills/` from the working folder up to the repository root, which
|
|
636
|
+
it finds by its `.git` folder, then in the user's own `~/.agents/skills/` and `~/.claude/skills/`,
|
|
637
|
+
then for the `hardfin-skills.json` a plugin install leaves:
|
|
638
|
+
|
|
639
|
+
| Tool | Folder searched |
|
|
640
|
+
| ------------------ | -------------------------------------------------------------------------------------------------------- |
|
|
641
|
+
| Claude Code | `~/.claude/plugins`, or `$CLAUDE_CONFIG_DIR/plugins` |
|
|
642
|
+
| Codex | `~/.codex/plugins`, or `$CODEX_HOME/plugins` |
|
|
643
|
+
| Cursor | `~/.cursor/plugins` |
|
|
644
|
+
| GitHub Copilot CLI | `~/.copilot/installed-plugins`, or `$COPILOT_HOME/installed-plugins` |
|
|
645
|
+
| VS Code | `agentPlugins` in its user data folder, such as `~/.config/Code` on Linux, and `~/.vscode/agent-plugins` |
|
|
646
|
+
|
|
647
|
+
A `marketplaces` folder is skipped, because a marketplace catalog holds the marker without the
|
|
648
|
+
plugin being installed.
|
|
649
|
+
|
|
650
|
+
| State | When | Notice |
|
|
651
|
+
| ---------- | ----------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
|
|
652
|
+
| `current` | Every copy is in the range | None |
|
|
653
|
+
| `missing` | No copy anywhere | `skills_missing`, naming `hardfin init` |
|
|
654
|
+
| `outdated` | A copy older than the range, or one a CLI bundled before releases | `skills_outdated`, naming `hardfin init --skills-only` and the `hardfin-upgrade` skill |
|
|
655
|
+
| `newer` | A copy newer than the range | `skills_newer`, naming `hardfin update` and the `hardfin-upgrade` skill |
|
|
656
|
+
|
|
657
|
+
- The notice is one line on stderr. Without a terminal it is a JSON line with `event: "skills_check"` and a `code`
|
|
658
|
+
- An agent hears it on every call. A person at a terminal hears it once a day in each folder
|
|
659
|
+
- When an update notice is due too, the two are one line, and the JSON carries the skills under `skills`
|
|
660
|
+
- `init`, `update` and `status` never print it. `hardfin status --json` carries the state as `skills`
|
|
661
|
+
- `hardfin mcp` leads its instructions with the state, and each tool result carries the command's own notice
|
|
662
|
+
- The check has no opt-out, and never fails a command or changes an exit code
|
|
663
|
+
|
|
664
|
+
### Keeping the CLI and the skills in step
|
|
665
|
+
|
|
666
|
+
`spec/skills-surface.json` holds every command, flag and argument the newest skills release in
|
|
667
|
+
the range was written against. `src/skills/surface.test.ts` fails when one of them is removed or
|
|
668
|
+
renamed, since a skill may name it. A new command or flag passes, and the next skills release
|
|
669
|
+
describes it. Refresh the file after a skills release, without git:
|
|
670
|
+
|
|
671
|
+
```sh
|
|
672
|
+
node scripts/update-skills-surface.mjs # the newest release in the range
|
|
673
|
+
node scripts/update-skills-surface.mjs 1.0.0 # one release
|
|
674
|
+
```
|
|
613
675
|
|
|
614
676
|
## Serving an agent
|
|
615
677
|
|