@_linked/server 2.3.0 → 2.4.0

package/.github/workflows/pr.yml

@@ -0,0 +1,18 @@
+name: PR
+
+on:
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  checks:
+    uses: linked-fw/.github/.github/workflows/pr.yml@v1
+    # The changeset reminder posts a PR comment. A reusable workflow only holds what its
+    # caller granted, and the org default is read-only.
+    permissions:
+      contents: read
+      pull-requests: write
+    with:
+      require-tests: true
+      run-e2e: false

package/.github/workflows/publish.yml

@@ -1,3 +1,8 @@
+# Calls the shared workflow in linked-fw/.github.
+#
+# This FILENAME is what npm's trusted-publisher check validates — not the shared workflow's.
+# Renaming this file invalidates this package's trusted publisher, and the only symptom is
+# that releases quietly start needing manual approval again.
 name: Publish
 
 on:
@@ -9,152 +14,17 @@ concurrency: ${{ github.workflow }}-${{ github.ref }}
 
 jobs:
   release:
-    name: Publish Release
-    runs-on: ubuntu-latest
+    uses: linked-fw/.github/.github/workflows/publish.yml@v1
     permissions:
       contents: write
       pull-requests: write
-      # `npm stage publish --provenance` signs the tarball with a GitHub OIDC token, so the
-      # job needs to be able to mint one. This does NOT switch the package to OIDC trusted
-      # publishing — authentication is still the org npm token. It only lets npm attest where
-      # the tarball was built, which is worth having on a package a human is about to approve
-      # sight-unseen.
+      # Needed HERE as well as in the shared workflow: a reusable workflow cannot widen the
+      # permissions its caller was granted, and without this npm never gets an id-token and
+      # every release silently falls back to the approval queue.
       id-token: write
-    steps:
-      # Author the changesets "Version Packages" PR as the org release App (not the default
-      # GITHUB_TOKEN) so its CI runs without a manual "Approve and run" gate. Requires the org
-      # App installed on this repo + org secrets RELEASE_APP_ID / RELEASE_APP_PRIVATE_KEY.
-      - name: Generate GitHub App token
-        id: app-token
-        uses: actions/create-github-app-token@v2
-        with:
-          app-id: ${{ secrets.RELEASE_APP_ID }}
-          private-key: ${{ secrets.RELEASE_APP_PRIVATE_KEY }}
-
-      - name: Checkout
-        uses: actions/checkout@v4
-        with:
-          token: ${{ steps.app-token.outputs.token }}
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: 22.16.0
-          registry-url: 'https://registry.npmjs.org'
-
-      # `npm stage` landed in CLI 11.15.0; Node 22.16 ships npm 10.x, so the bundled one
-      # cannot stage. Pinned rather than `@latest` so a future npm release cannot change how
-      # releases behave without a commit here.
-      - name: Use an npm that can stage
-        run: npm i -g npm@^11.15.0
-
-      - name: Install dependencies
-        run: npm ci --legacy-peer-deps
-
-      - name: Build
-        run: npm run build
-
-      # No `publish:` — changesets only opens/updates the version PR here. Publishing is the
-      # step below, because `changeset publish` shells out to `npm publish`, which a
-      # stage-only token cannot do (changesets/changesets#2025 is open for first-class
-      # support). Splitting them keeps changesets doing what it is good at — versions and
-      # changelogs — and leaves the registry call to us.
-      - name: Create release Pull Request
-        id: changesets
-        uses: changesets/action@v1
-        with:
-          title: 'chore: release'
-          commit: 'chore: release'
-        env:
-          GITHUB_TOKEN: ${{ steps.app-token.outputs.token }}
-
-      # Stage the version for a human to approve.
-      #
-      # A staged version is uploaded but NOT public: a maintainer reviews it and approves with
-      # 2FA, from the Staged Packages tab in the npm user menu or `npm stage approve`. That is
-      # the point — every release keeps a proof-of-presence step even though CI is
-      # unattended — and it is why the org token is scoped "read and write (stage only)".
-      #
-      # Idempotent: this workflow runs on every push to main, including the merge of the
-      # version PR and any later commit, so it must do nothing when the version is already on
-      # the registry or already sitting in the queue.
-      - name: Stage the release for approval
-        if: steps.changesets.outputs.hasChangesets != 'true'
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_AUTH_TOKEN }}
-          NPM_TOKEN: ${{ secrets.NPM_AUTH_TOKEN }}
-        run: |
-          set -euo pipefail
-          name=$(node -p "require('./package.json').name")
-          version=$(node -p "require('./package.json').version")
-          private=$(node -p "require('./package.json').private === true")
-          if [ "$private" = "true" ]; then
-            echo "$name is private — nothing to publish."; exit 0
-          fi
-
-          if npm view "$name@$version" version >/dev/null 2>&1; then
-            echo "$name@$version is already on the registry — nothing to do."
-            exit 0
-          fi
-
-          if npm stage list "$name" 2>/dev/null | grep -q "$version"; then
-            echo "$name@$version is already staged and waiting for approval."
-            exit 0
-          fi
-
-          echo "Staging $name@$version…"
-          # Capture the output: `npm stage publish` prints the stage id, and `npm stage
-          # approve` takes ONLY that id — a package spec is rejected with "stage-id must be a
-          # valid UUID". Without this the notice below hands out a command that does not work.
-          out=$(npm stage publish --access public --provenance 2>&1 | tee /dev/stderr)
-          uuid='[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}'
-          # `|| true` because the script runs under `set -euo pipefail`: a grep that matches
-          # nothing exits 1 and would fail the step even though the staging itself succeeded.
-          stage_id=$(printf '%s' "$out" | grep -oE "$uuid" | tail -1 || true)
-
-          {
-            echo "### 📦 \`$name@$version\` is staged, not published"
-            echo
-            echo "It is uploaded and held for review. **Approve it to make it public:**"
-            echo
-            if [ -n "$stage_id" ]; then
-              echo "- **CLI:** \`npm stage approve $stage_id\`"
-            else
-              echo "- **CLI:** \`npm stage list $name\` to find the id, then"
-              echo "  \`npm stage approve <stage-id>\`"
-            fi
-            echo "- **Web:** [npmjs.com](https://www.npmjs.com) → your avatar → **Staged"
-            echo "  Packages** → **Approve**. The button stays disabled until npm has"
-            echo "  finished scanning the tarball; the page refreshes every minute."
-            echo
-            echo "Both prompt for 2FA. Until then \`npm install $name\` still resolves"
-            echo "\`$(npm view "$name" version 2>/dev/null || echo 'nothing')\`."
-          } >> "$GITHUB_STEP_SUMMARY"
-
-          if [ -n "$stage_id" ]; then
-            echo "::notice title=Approval needed::$name@$version is staged. Run: npm stage approve $stage_id"
-          else
-            echo "::notice title=Approval needed::$name@$version is staged, but the stage id could not be read from the output. Run: npm stage list $name"
-          fi
-
-      # When changesets opened/updated the version PR, merge it so the release reaches the
-      # staging queue without a manual click. App token → the merge's push re-triggers this
-      # workflow, which then stages. DIRECT-merge (not `--auto`): GitHub
-      # auto-merge ignores branch-protection review-bypass allowances; main is check-only so a
-      # direct merge lands once the required check is green — retry until then.
-      - name: Merge the version PR to stage the release
-        if: steps.changesets.outputs.hasChangesets == 'true'
-        env:
-          GH_TOKEN: ${{ steps.app-token.outputs.token }}
-        run: |
-          pr=$(gh pr list --base main --head changeset-release/main --state open --json number --jq '.[0].number // empty')
-          if [ -z "$pr" ]; then echo "No open version PR (nothing to merge)."; exit 0; fi
-          for i in $(seq 1 40); do
-            if gh pr merge "$pr" --merge 2>/tmp/merge_err; then
-              echo "Merged version PR #$pr on attempt $i."
-              exit 0
-            fi
-            echo "Attempt $i/40: version PR #$pr not mergeable yet ($(tr -d '\n' < /tmp/merge_err)); waiting for the required check…"
-            sleep 15
-          done
-          echo "::warning::Version PR #$pr not merged after retries — merge it manually."
+    # Named rather than `inherit`: `inherit` forwards everything this repo can see, which is
+    # how a community repo would end up forwarding a first-party token.
+    secrets:
+      NPM_TOKEN: ${{ secrets.NPM_AUTH_TOKEN }}
+      RELEASE_APP_ID: ${{ secrets.RELEASE_APP_ID }}
+      RELEASE_APP_PRIVATE_KEY: ${{ secrets.RELEASE_APP_PRIVATE_KEY }}

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # @\_linked/server
 
+## 2.4.0
+
+### Minor Changes
+
+- [#38](https://github.com/linked-fw/server/pull/38) [`bf1e83c`](https://github.com/linked-fw/server/commit/bf1e83cdfc949baec88a645c2750479bc33f1637) Thanks [@flyon](https://github.com/flyon)! - `LocalFileStore` accepts the new `SaveFileOptions` third argument of `saveFile`
+  (still accepting a positional mime-type string) and gains `statFile()`, which
+  returns the size and a sha256 of a stored file, or `null` when it does not
+  exist, for verify-after-upload. A local file has no headers, so `cacheControl`
+  and `metadata` are accepted and ignored.
+
+  Core reports an unspecified `preventDuplicates` as `undefined` and applies no
+  default of its own, so this store keeps applying its own: a caller that says
+  nothing still gets the random file-name suffix, and only an explicit
+  `preventDuplicates: false` overwrites an existing name.
+
+## 2.3.1
+
+### Patch Changes
+
+- [#40](https://github.com/linked-fw/server/pull/40) [`804851d`](https://github.com/linked-fw/server/commit/804851d16f005b56893c73561aaf72ad64a78434) Thanks [@flyon](https://github.com/flyon)! - Point `repository.url` at the linked-fw organisation, so npm provenance verification matches the repository that builds the package.
+
 ## 2.3.0
 
 ### Minor Changes

package/lib/esm/backend.js

@@ -7,8 +7,8 @@ import fs from 'fs/promises';
 export * from './shapes/quadstores/BackendAPIStoreProvider.js';
 export default class LincdServerBackendProvider extends BackendProvider {
     async setupBeforeControllers() {
-        if (!LinkedFileStorage.getDefaultDataset()) {
-            LinkedFileStorage.setDefaultDataset(new LocalFileStore(process.env.NODE_ENV + '-filestore'));
+        if (!LinkedFileStorage.getDefaultStore()) {
+            LinkedFileStorage.setDefaultStore(new LocalFileStore(process.env.NODE_ENV + '-filestore'));
         }
         let fileSystemUploadPath = path.join('data', 'filestores');
         try {

package/lib/esm/backend.js.map

@@ -1 +1 @@
-{"version":3,"file":"backend.js","sourceRoot":"","sources":["../../src/backend.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,6CAA6C,CAAC;AAC9E,OAAO,EAAE,iBAAiB,EAAE,MAAM,uCAAuC,CAAC;AAC1E,OAAO,EAAE,cAAc,EAAE,MAAM,uCAAuC,CAAC;AACvE,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,IAAI,MAAM,MAAM,CAAC;AACxB,OAAO,EAAE,MAAM,aAAa,CAAC;AAE7B,cAAc,gDAAgD,CAAC;AAE/D,MAAM,CAAC,OAAO,OAAO,0BAA2B,SAAQ,eAAe;IACrE,KAAK,CAAC,sBAAsB;QAC1B,IAAI,CAAC,iBAAiB,CAAC,iBAAiB,EAAE,EAAE,CAAC;YAC3C,iBAAiB,CAAC,iBAAiB,CACjC,IAAI,cAAc,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,GAAG,YAAY,CAAC,CACxD,CAAC;QACJ,CAAC;QACD,IAAI,oBAAoB,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;QAC3D,IAAI,CAAC;YACH,MAAM,EAAE,CAAC,MAAM,CAAC,oBAAoB,CAAC,CAAC;QACxC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,oBAAoB,EAAE,YAAY,CAAC,EAAE;gBAC5D,SAAS,EAAE,IAAI;aAChB,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,SAAS;QACP,OAAO,aAAa,EAAE,CAAC;IACzB,CAAC;CACF"}
+{"version":3,"file":"backend.js","sourceRoot":"","sources":["../../src/backend.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,6CAA6C,CAAC;AAC9E,OAAO,EAAE,iBAAiB,EAAE,MAAM,uCAAuC,CAAC;AAC1E,OAAO,EAAE,cAAc,EAAE,MAAM,uCAAuC,CAAC;AACvE,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,IAAI,MAAM,MAAM,CAAC;AACxB,OAAO,EAAE,MAAM,aAAa,CAAC;AAE7B,cAAc,gDAAgD,CAAC;AAE/D,MAAM,CAAC,OAAO,OAAO,0BAA2B,SAAQ,eAAe;IACrE,KAAK,CAAC,sBAAsB;QAC1B,IAAI,CAAC,iBAAiB,CAAC,eAAe,EAAE,EAAE,CAAC;YACzC,iBAAiB,CAAC,eAAe,CAC/B,IAAI,cAAc,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,GAAG,YAAY,CAAC,CACxD,CAAC;QACJ,CAAC;QACD,IAAI,oBAAoB,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;QAC3D,IAAI,CAAC;YACH,MAAM,EAAE,CAAC,MAAM,CAAC,oBAAoB,CAAC,CAAC;QACxC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,oBAAoB,EAAE,YAAY,CAAC,EAAE;gBAC5D,SAAS,EAAE,IAAI;aAChB,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,SAAS;QACP,OAAO,aAAa,EAAE,CAAC;IACzB,CAAC;CACF"}

package/lib/esm/shapes/filestores/LocalFileStore.d.ts

@@ -1,4 +1,4 @@
-import { IFileStore } from '@_linked/core/interfaces/IFileStore';
+import { FileStat, IFileStore, SaveFileOptions } from '@_linked/core/interfaces/IFileStore';
 import { Shape } from '@_linked/core/shapes/Shape';
 export declare class LocalFileStore extends Shape implements IFileStore {
     private readonly basePath;
@@ -36,7 +36,26 @@ export declare class LocalFileStore extends Shape implements IFileStore {
      * Save a file to the local filesystem
      * @param filePath The path to save the file to, relative to the base upload folder
      * @param fileContent The contents of the file as a buffer
+     * @param options Save options, or a string read as the old positional mimeType.
+     *   A local file has no headers to attach, so only `mimeType` (used to add a
+     *   missing extension) and `preventDuplicates` mean anything here;
+     *   `cacheControl` and `metadata` are accepted and ignored.
+     * @param preventDuplicates Only honoured when `options` is a string
      * @returns A promise that resolves to the public URL of the file
      */
-    saveFile(filePath: string, fileContent: Buffer, mimeType?: string): Promise<string>;
+    saveFile(filePath: string, fileContent: Buffer, options?: SaveFileOptions | string, preventDuplicates?: boolean): Promise<string>;
+    /**
+     * Read back the metadata of a stored file, for verify-after-upload.
+     *
+     * The path is resolved exactly like getFile/fileExists/deleteFile do, against
+     * the base upload folder, which by default is the same folder saveFile writes
+     * into, so a file that was just saved can be stat'ed by its stored name.
+     *
+     * The sha256 is computed on demand from the bytes: statFile is only called
+     * during publish verification, not on every upload.
+     *
+     * @param filePath The path to the file, relative to the base upload folder
+     * @returns The size and sha256 of the file, or null if it does not exist
+     */
+    statFile(filePath: string): Promise<FileStat | null>;
 }

package/lib/esm/shapes/filestores/LocalFileStore.js

@@ -1,5 +1,7 @@
 import { relativeFileSystemUploadPath, getUploadTarget, } from '@_linked/server-utils/utils/Upload';
+import { normalizeSaveFileOptions, } from '@_linked/core/interfaces/IFileStore';
 import { Shape } from '@_linked/core/shapes/Shape';
+import { createHash } from 'node:crypto';
 import * as fsSync from 'node:fs';
 import fs from 'node:fs/promises';
 import path from 'node:path';
@@ -78,10 +80,21 @@ export class LocalFileStore extends Shape {
      * Save a file to the local filesystem
      * @param filePath The path to save the file to, relative to the base upload folder
      * @param fileContent The contents of the file as a buffer
+     * @param options Save options, or a string read as the old positional mimeType.
+     *   A local file has no headers to attach, so only `mimeType` (used to add a
+     *   missing extension) and `preventDuplicates` mean anything here;
+     *   `cacheControl` and `metadata` are accepted and ignored.
+     * @param preventDuplicates Only honoured when `options` is a string
      * @returns A promise that resolves to the public URL of the file
      */
-    async saveFile(filePath, fileContent, mimeType) {
-        const { publicURL, targetFilePath } = getUploadTarget(filePath, mimeType, null, '', this.accessURL);
+    async saveFile(filePath, fileContent, options, preventDuplicates) {
+        var _a;
+        const normalized = normalizeSaveFileOptions(options, preventDuplicates);
+        // Core reports an unspecified preventDuplicates as undefined, leaving the
+        // default to each store. This one has always let getUploadTarget append its
+        // random suffix, so only an explicit `false` turns that off.
+        const suffixDuplicates = (_a = normalized.preventDuplicates) !== null && _a !== void 0 ? _a : true;
+        const { publicURL, targetFilePath } = getUploadTarget(filePath, normalized.mimeType, null, '', this.accessURL, suffixDuplicates);
         //make sure the target folder exists
         if (!fsSync.existsSync(path.dirname(targetFilePath))) {
             fsSync.mkdirSync(path.dirname(targetFilePath), { recursive: true });
@@ -89,5 +102,34 @@ export class LocalFileStore extends Shape {
         await fs.writeFile(targetFilePath, fileContent);
         return publicURL;
     }
+    /**
+     * Read back the metadata of a stored file, for verify-after-upload.
+     *
+     * The path is resolved exactly like getFile/fileExists/deleteFile do, against
+     * the base upload folder, which by default is the same folder saveFile writes
+     * into, so a file that was just saved can be stat'ed by its stored name.
+     *
+     * The sha256 is computed on demand from the bytes: statFile is only called
+     * during publish verification, not on every upload.
+     *
+     * @param filePath The path to the file, relative to the base upload folder
+     * @returns The size and sha256 of the file, or null if it does not exist
+     */
+    async statFile(filePath) {
+        const fileToStat = path.join(this.basePath, filePath);
+        let stat;
+        try {
+            stat = await fs.stat(fileToStat);
+        }
+        catch (err) {
+            return null;
+        }
+        if (!stat.isFile()) {
+            return null;
+        }
+        const contents = await fs.readFile(fileToStat);
+        const sha256 = createHash('sha256').update(contents).digest('hex');
+        return { size: stat.size, sha256 };
+    }
 }
 //# sourceMappingURL=LocalFileStore.js.map

package/lib/esm/shapes/filestores/LocalFileStore.js.map

@@ -1 +1 @@
-{"version":3,"file":"LocalFileStore.js","sourceRoot":"","sources":["../../../../src/shapes/filestores/LocalFileStore.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"LocalFileStore.js","sourceRoot":"","sources":["../../../../src/shapes/filestores/LocalFileStore.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -8,9 +8,9 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/linked-cm/server.git"
+    "url": "git+https://github.com/linked-fw/server.git"
   },
-  "version": "2.3.0",
+  "version": "2.4.0",
   "linkedPackage": true,
   "type": "module",
   "main": "lib/esm/index.js",
@@ -35,7 +35,7 @@
   ],
   "dependencies": {
     "@_linked/cli": "^1.2",
-    "@_linked/core": "^2.18.1",
+    "@_linked/core": "^2.20.0",
     "@_linked/server-utils": "^1.2.0",
     "adm-zip": "^0.5.16",
     "archiver": "^7.0.1",

package/readme.md

@@ -319,8 +319,8 @@ shape.
 
 ### LocalFileStore
 
-This is the default file store for LINCD. It is a simple file store that stores files in a local directory. Its usage
-follows the general pattern of other file stores in LINCD:
+An `IFileStore` that stores files in a local directory. Its usage follows the general pattern of other file stores in
+LINCD:
 
 - Define all storage locations when the server or application starts up
 - Access methods of the file store through the `LinkedFileStorage` class
@@ -330,15 +330,71 @@ It's important to note that this file store is not suitable for frontend usage -
 environment that has access to the [`fs` module](https://nodejs.org/api/fs.html).
 
 ```ts
-import { LinkedFileStorage } from '@_linked/core/lib/utils/LinkedFileStorage';
-import { LocalFileStore } from 'lincd-server/lib/shapes/LocalFileStore';
+import { LinkedFileStorage } from '@_linked/core/utils/LinkedFileStorage';
+import { LocalFileStore } from '@_linked/server/shapes/filestores/LocalFileStore';
 import path from 'path';
 
+// the second argument is the base folder on disk; it defaults to the server's
+// upload folder (`./data/uploads`, relative to the working directory)
 const pathToStore = path.join(process.cwd(), 'my-file-store');
 const store = new LocalFileStore('my-file-store', pathToStore);
 LinkedFileStorage.setDefaultStore(store);
 ```
 
+`accessURL` comes from `SITE_ROOT`, and every path you pass to `saveFile`, `getFile`, `fileExists`, `deleteFile` and
+`statFile` is relative to that base folder.
+
+Registering stores per purpose (`LinkedFileStorage.setStore`, `getStore`, `registerPurpose`) is core's concern — see
+[`@_linked/core`](https://github.com/linked-cm/core), `utils/LinkedFileStorage` and `interfaces/IFileStore`.
+
+#### Saving files
+
+`saveFile` takes core's `SaveFileOptions` as its third argument:
+
+```ts
+await store.saveFile('report.pdf', fileBuffer, {
+  mimeType: 'application/pdf',
+  preventDuplicates: true,
+});
+```
+
+A local file has no headers to attach, so only two of the options do anything here:
+
+- `mimeType` — used to add a missing file extension.
+- `preventDuplicates` — see below.
+- `cacheControl` and `metadata` are accepted (so the same call works against an S3-backed store) and ignored.
+
+The old positional form still works: a plain string third argument is read as the mime type, with `preventDuplicates`
+following it.
+
+```ts
+await store.saveFile('report.pdf', fileBuffer, 'application/pdf', true);
+```
+
+##### LocalFileStore suffixes by default
+
+`preventDuplicates` left unspecified means `true` **here**. A second save of the same name does **not** overwrite the
+first: the store appends a random suffix, so `report.pdf` becomes `report_a1b2c3.pdf`. Only an explicit `false`
+overwrites.
+
+Core supplies no default of its own — an unspecified `preventDuplicates` reaches the store as `undefined` and each store
+decides. Do not assume this store's choice holds elsewhere: `S3FileStore` in `@_linked/s3` overwrites by default.
+
+#### Reading file metadata
+
+`statFile(filePath)` returns `{size, sha256}` for a stored file, or `null` when it does not exist (or is not a regular
+file). The `sha256` is a hex digest computed from the file's bytes on demand, so a caller can verify an upload it just
+made:
+
+```ts
+const stat = await store.statFile('report.pdf');
+if (stat === null) throw new Error('upload went missing');
+if (stat.sha256 !== expectedSha256) throw new Error('content mismatch');
+```
+
+`statFile` is optional on `IFileStore`, so a caller holding an `IFileStore` rather than a `LocalFileStore` must check
+that it exists before calling it.
+
 ## TODO
 
 - [ ] Add tests

package/.github/workflows/changeset-check.yml

@@ -1,44 +0,0 @@
-name: Changeset Check
-
-on:
-  pull_request:
-    branches:
-      - main
-
-jobs:
-  changeset-check:
-    name: Check for changeset
-    # Skip the check on the automated Release PR.
-    if: ${{ github.head_ref != 'changeset-release/main' }}
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - name: Check for changeset files
-        uses: actions/github-script@v7
-        with:
-          script: |
-            const { data: files } = await github.rest.pulls.listFiles({
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              pull_number: context.issue.number,
-            });
-
-            const hasChangeset = files.some(f =>
-              f.filename.startsWith('.changeset/') &&
-              f.filename.endsWith('.md') &&
-              f.filename !== '.changeset/README.md'
-            );
-
-            if (!hasChangeset) {
-              await github.rest.issues.createComment({
-                owner: context.repo.owner,
-                repo: context.repo.repo,
-                issue_number: context.issue.number,
-                body: "No changeset found. If this PR should trigger a release, run `npx changeset` and commit the generated file.\n\nIf this change doesn't need a release (docs, CI config, etc.), you can ignore this message."
-              });
-              core.warning('No changeset file found in this PR.');
-            }

package/.github/workflows/ci.yml

@@ -1,43 +0,0 @@
-name: CI
-
-on:
-  pull_request:
-    branches:
-      - main
-
-jobs:
-  build-and-test:
-    name: Build & Test
-    runs-on: ubuntu-latest
-    steps:
-      - name: Detect Release PR
-        id: rpr
-        run: |
-          if [[ "${{ github.event.pull_request.head.ref }}" == "changeset-release/main" ]]; then
-            echo "is_release_pr=true" >> $GITHUB_OUTPUT
-            echo "Release PR from changesets/action detected — skipping build/test (auto-generated version+CHANGELOG only)."
-          else
-            echo "is_release_pr=false" >> $GITHUB_OUTPUT
-          fi
-
-      - name: Checkout
-        if: steps.rpr.outputs.is_release_pr == 'false'
-        uses: actions/checkout@v4
-
-      - name: Setup Node.js
-        if: steps.rpr.outputs.is_release_pr == 'false'
-        uses: actions/setup-node@v4
-        with:
-          node-version: 22.16.0
-
-      - name: Install dependencies
-        if: steps.rpr.outputs.is_release_pr == 'false'
-        run: npm ci --legacy-peer-deps
-
-      - name: Build
-        if: steps.rpr.outputs.is_release_pr == 'false'
-        run: npm run build
-
-      - name: Test
-        if: steps.rpr.outputs.is_release_pr == 'false'
-        run: npm test --if-present