@hearthlog/tooling 0.1.1 → 0.1.3

package/bin/hearthlog.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// The `hearthlog` command: runs the TypeScript tools through tsx. `build`, `init`, `export`, `check-module`, `artifact`, and
+// The `hearthlog` command: runs the TypeScript tools through tsx. `build`, `init`, `export`, `check-module`, `lock`, `artifact`, and
 // `gallery-public:build` start before a site has generated files (or write their own), so they run alone; the
 // `apple:*` commands run the build and then the tools of `@hearthlog/native` (a dependency of the site, not of this
 // package); `ensure`, `deploy`, `deploy-ledger`, and `split` run the build and then a deploy tool; every other
@@ -46,7 +46,8 @@ if (deployTools[command]) {
 if (command === 'plan') {
     const site = rest[rest.indexOf('--site') + 1];
     const env = { ...process.env, ...(rest.includes('--site') && site ? { VITE_STOR_TENANT: site } : {}) };
-    const built = spawnSync(process.execPath, [tsx, source('generate/build-generated.ts'), '--quiet'], { stdio: 'inherit', env }).status ?? 1;
+    // The build's messages go to stderr: `plan --json` writes only the plan to stdout.
+    const built = spawnSync(process.execPath, [tsx, source('generate/build-generated.ts'), '--quiet'], { stdio: ['inherit', 2, 'inherit'], env }).status ?? 1;
     if (built !== 0) process.exit(built);
 }
 
@@ -55,6 +56,7 @@ const entry = {
     init: 'init/init.ts',
     export: 'init/export-tenant.ts',
     'check-module': 'init/check-module.ts',
+    lock: 'tenants/module-lock.ts',
     'gallery-public:build': 'public-workers/build-gallery-public.ts',
     artifact: 'deploy/artifact.ts',
 }[command];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hearthlog/tooling",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "license": "AGPL-3.0-only",
   "repository": {
     "type": "git",
@@ -28,7 +28,7 @@
   },
   "dependencies": {
     "tsx": "^4.23.15",
-    "@hearthlog/contracts": "0.1.1"
+    "@hearthlog/contracts": "0.1.3"
   },
   "bin": {
     "hearthlog": "./bin/hearthlog.mjs"

package/src/init/init.ts

@@ -100,6 +100,7 @@ export function renderSite(options: InitOptions): Array<[string, string]> {
         ["pnpm-workspace.yaml", template("pnpm-workspace.yaml.tmpl")],
         ["patches/sqlocal@0.18.0.patch", template("patches/sqlocal@0.18.0.patch")],
         [".github/workflows/deploy.yml", renderWorkflow(id)],
+        [".github/dependabot.yml", template("dependabot.yml.tmpl")],
         [".gitignore", template("gitignore.tmpl")],
         ["README.md", render(template("README.md.tmpl"), values)],
     ];

package/src/tenants/lock-file.ts

@@ -1,5 +1,8 @@
 /**
- * The lock file's content: which modules a site ships and the exact manifest each was composed from. It
+ * The lock file's content: which modules a site ships and the exact manifest each was composed from. It names no version:
+ * a release that keeps a module's manifest changes nothing here (the package manager's lockfile adopts it), and a release
+ * that moves the contract changes `manifestSha256`, so `hearthlog lock --check` fails until the lock is regenerated and the
+ * diff names the module. It
  * imports nothing generated, so `hearthlog init` can write one before a site has any generated files.
  */
 
@@ -14,7 +17,6 @@ import { modulesForFeatures, type LoadedModule } from "../compose/compose-module
 export interface ModuleLockEntry {
     id: string;
     package: string;
-    version: string;
     /** The site's enabled features this module provides. */
     features: string[];
     /** SHA-256 of the module's `hearthlog.module.json`. */
@@ -32,7 +34,6 @@ export function lockFor(modules: readonly LoadedModule[], features: readonly str
     const entries: ModuleLockEntry[] = modulesForFeatures(modules, features).map(({ directory, manifest }) => ({
         id: manifest.id,
         package: manifest.package,
-        version: manifest.version,
         features: manifest.features.map((feature) => feature.id).filter((id) => features.includes(id)),
         manifestSha256: createHash("sha256").update(readFileSync(join(directory, "hearthlog.module.json"))).digest("hex"),
     }));

package/src/tenants/module-lock.ts

@@ -33,8 +33,17 @@ export async function buildModuleLock(site: Pick<ResolvedSite, "features">): Pro
 export async function moduleLockProblems(site: Pick<ResolvedSite, "id" | "features">): Promise<string[]> {
     const expected = renderModuleLock(await buildModuleLock(site));
     const current = await readFile(moduleLockPath(site.id), "utf8").catch(() => null);
-    if (current === null) return [`tenants/${site.id}/modules.lock.json is missing; run pnpm lock:modules`];
-    return current === expected ? [] : [`tenants/${site.id}/modules.lock.json is stale; run pnpm lock:modules`];
+    if (current === null) return [`tenants/${site.id}/modules.lock.json is missing; run pnpm lock:modules (hearthlog lock)`];
+    // Older locks also recorded each module's version; it is not part of the contract.
+    const withoutVersions = (text: string) => {
+        try {
+            const lock = JSON.parse(text) as { modules?: Array<Record<string, unknown>> };
+            return renderModuleLock({ ...lock, modules: (lock.modules ?? []).map(({ version: _version, ...entry }) => entry) } as unknown as ModuleLock);
+        } catch {
+            return text;
+        }
+    };
+    return withoutVersions(current) === expected ? [] : [`tenants/${site.id}/modules.lock.json is stale; run pnpm lock:modules (hearthlog lock)`];
 }
 
 if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {

package/templates/module/release.yml.tmpl

@@ -1,7 +1,7 @@
 name: Release
 
 # Set "version" in package.json, commit, then push the tag `v<version>`. The publish job waits for approval in the
-# protected `npm` environment; the registry credential is the organization secret NPM_TOKEN.
+# protected `npm` environment; the package is published through npm's trusted publishing, so no registry token is stored.
 on:
   push:
     tags: ["v*"]
@@ -37,10 +37,16 @@ jobs:
         with:
           node-version: 24
           registry-url: https://registry.npmjs.org
+      # npm's trusted publishing (OIDC) needs npm 11.5.1 or later; no token is stored anywhere.
+      - run: npm install --global npm@11
       - run: pnpm install
-      - run: pnpm publish --no-git-checks
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+      - name: Publish the version in package.json unless the registry has it
+        run: |
+          name=$(node -p "require('./package.json').name")
+          version=$(node -p "require('./package.json').version")
+          if [ "$(npm view "$name@$version" version 2>/dev/null)" = "$version" ]; then echo "$name@$version is already published"; exit 0; fi
+          pnpm pack --pack-destination "$RUNNER_TEMP/pack"
+          npm publish "$RUNNER_TEMP/pack/"*.tgz --access public --provenance
 
   release:
     needs: publish

package/templates/tenant/dependabot.yml.tmpl

@@ -0,0 +1,13 @@
+# Releases of the platform and of the modules arrive as pull requests that change the lockfile (and nothing else, unless a
+# module's contract moved: then `hearthlog lock` rewrites tenants/<id>/modules.lock.json and the diff names the module).
+# The build job of this repository's workflow builds each one; merge it to deploy, with the approval of the environment.
+version: 2
+updates:
+  - package-ecosystem: npm
+    directory: "/"
+    schedule:
+      interval: weekly
+    groups:
+      hearthlog:
+        patterns:
+          - "@hearthlog/*"

package/templates/tenant/github-workflows/deploy.yml.tmpl

@@ -46,7 +46,10 @@ jobs:
           pnpm exec hearthlog gallery-public:build --site {{id}}
           pnpm exec vite build
           pnpm exec hearthlog artifact manifest --site {{id}}
-      # After the build: the plan reads the generated files the build writes.
+      # After the build: the lock and the plan read the generated files the build writes. The lock fails when a module's
+      # contract changed since `tenants/{{id}}/modules.lock.json` was written: run `pnpm exec hearthlog lock` and commit it.
+      - name: Check the module lock
+        run: pnpm exec hearthlog lock --check
       - name: Plan (read-only)
         run: pnpm exec hearthlog plan --site {{id}}
       - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2