@macula-io/martha 1.0.0 → 1.0.2

package/README.md

@@ -1,6 +1,17 @@
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/macula-io/martha/main/assets/martha-full-dark.svg">
+    <img src="https://raw.githubusercontent.com/macula-io/martha/main/assets/martha-full-light.svg" alt="Macula Martha" width="320">
+  </picture>
+</p>
+
 # @macula-io/martha
 
-Installs [Martha](https://github.com/macula-io/martha) from its signed public package, with nothing but Node.
+**Goal:** one developer, or a whole team, runs a crew of coding agents that plans, builds, reviews and releases
+software, with one method and one tool.
+
+This is the installer for [Martha](https://github.com/macula-io/martha): it installs Martha from its signed public
+package, with nothing but Node.
 
 ```sh
 npx -y --ignore-scripts @macula-io/martha@<exact version> [<martha version>]
@@ -34,26 +45,8 @@ martha-install [<version>] [--downgrade] [--digest sha256:<hex>]
 
 ## How a release is made
 
-1. The release dry run (`release-dry-run.yml`, started by hand on a branch) pushes the packed tree into the release
-   package under a `dry-run-<run>-<attempt>` tag, which is never a version, so no install ever takes it. It signs it
-   through the same signing workflow, then checks that the signature verifies for that branch and is refused for
-   `refs/tags/v<version>`, that an unsigned image is refused, and that the layer is exactly the committed tree.
-   Its two tags are kept in the public package, not pruned: one pair per run, and runs are started by hand.
-   Neither is ever installed: no tag of that shape is a version, and the signature is for a branch, so an install,
-   which demands `refs/tags/v<version>`, refuses it. Pruning would need a workflow that can delete package versions,
-   and none of Martha's workflows holds that power. A maintainer may delete old ones by hand in the package settings.
-2. The first dry run is what makes the release package. The maintainers then link it to this repository and make it
-   public, before any release tag: every install pulls anonymously, and a refused pull must never read as
-   "unsigned".
-3. `installer-v<version>` publishes this installer to npm, with provenance, through trusted publishing.
-4. `v<version>` publishes a signed Martha release into the package, pinning that installer.
-
-Neither tag publishes while a dependency of Martha or of this installer carries a known published advisory
-(`advisories.yml`, which also runs on every pull request). An advisory is fixed or waived by a dated, named, expiring
-row in `.github/advisories-waivers.txt`; there is no baseline. The `overrides` in `package.json` are such fixes:
-sigstore 5.0.0 resolves glob 13 and minimatch 10, which carry GHSA-3g3m-2fjr-6pw4 and GHSA-g3hv-75wg-m249, so the
-installer pins their first patched releases. Its callers use only `glob(pattern, options)` and
-`minimatch(path, pattern)`, which both majors keep. Drop an override once sigstore resolves a patched release itself.
+For maintainers: how a release is built, signed and published, and what stops one, is in
+[the repository's docs](https://github.com/macula-io/martha/tree/main/docs), in `how-a-release-is-made.md`.
 
 ## License
 

package/keep_the_names_in_one_place/names.mjs

@@ -17,6 +17,7 @@ const manifest = createRequire(import.meta.url)('../package.json')
  * @property {string} issuer            the OIDC issuer of the signing certificate
  * @property {string} command           the command an installed release puts on PATH
  * @property {string} releaseFolder     the one top-level folder a release's layer holds
+ * @property {string} pinFile           the file the packer generates in that folder: the installer a release pins
  * @property {string} releaseTagPrefix  what a release tag starts with
  * @property {string} installerTagPrefix what an installer tag starts with
  * @property {string} installerPublishWorkflow the workflow whose run publishes this installer, and signs that publish

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@macula-io/martha",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@macula-io/martha",
-      "version": "1.0.0",
+      "version": "1.0.2",
       "bundleDependencies": [
         "sigstore"
       ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@macula-io/martha",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Install Martha from its signed public package: verifies the release's sigstore signature, then installs it",
   "type": "module",
   "license": "Apache-2.0",
@@ -59,6 +59,7 @@
     "releaseTagPrefix": "v",
     "installerTagPrefix": "installer-v",
     "releaseFolder": "martha",
+    "pinFile": "installer.json",
     "dryRunTagPrefix": "dry-run-",
     "installerPublishWorkflow": ".github/workflows/installer.yml"
   }

package/verify_the_release_signature/verify_the_release_signature.mjs

@@ -156,7 +156,7 @@ async function failure ({ bundle, sha, ref, source, makeVerifier, tufCachePath }
  * { sha } of the listed signer whose identity one of `bundles` verifies under, for `version` of `digest`; or
  * { reasons } saying why each try failed. A trust root that could not be fetched throws CouldNotCheck instead.
  * `ref` is refs/tags/v<version>; only the release dry run, from a test file, names its branch's ref.
- * @param {{ bundles: any[], digest: string, version: string, signers: string[], source?: string, ref?: string, makeVerifier?: MakeVerifier, tufCachePath?: string | undefined }} request
+ * @param {{ bundles: any[], digest: string, version: string, signers: string[], source?: string, ref?: string | undefined, makeVerifier?: MakeVerifier, tufCachePath?: string | undefined }} request
  * @returns {Promise<{ sha: string } | { reasons: string[] }>}
  */
 export async function signedBy ({ bundles, digest, version, signers, source = NAMES.sourceRepository, ref = releaseRef(version), makeVerifier = createVerifier, tufCachePath }) {