@_linked/cli 1.17.0 → 1.19.0

package/CHANGELOG.md

@@ -1,5 +1,98 @@
 # Changelog
 
+## 1.19.0
+
+### Minor Changes
+
+- [#100](https://github.com/linked-fw/cli/pull/100) [`8ef0fd7`](https://github.com/linked-fw/cli/commit/8ef0fd7f810dfff26b95f5390565661b8c38c7ac) Thanks [@flyon](https://github.com/flyon)! - ## App release pipeline on the file-store API
+
+  A manifest-driven build/publish/serve flow for Linked apps, replacing the old recursive upload of
+  everything under `public/`.
+
+  ### New commands
+
+  ```bash
+  linked build-app --env <env> --target web        # build + write public/bundles/linked-release.json
+  linked build-app --env <env> --publish           # ...and upload it in the same run
+  linked build-app --env <env> --target capacitor  # local, non-publishable manifest; never uploads
+  linked build-app --revision <sha>                # identify the release outside a git checkout
+  linked build-app --allow-dirty                   # build uncommitted work as <sha>-dirty
+  linked publish-app --env <env>                   # dry run by default; pass --yes to upload
+  linked publish-app --manifest <path>             # publish a manifest from another path
+  linked serve-app --env <env>                     # compiled runtime, no Vite/HMR
+  ```
+
+  `build-app` never uploads on its own — it writes a release manifest, and `publish-app` uploads
+  exactly the files that manifest lists.
+
+  ### Publishing destination
+
+  Uploads go through `LinkedFileStorage.getStore(FileStorePurposes.appAssets)`. An app that dedicates a
+  bundle store configures `setStore(FileStorePurposes.appAssets, store)`; an app with a single store
+  configures only `setDefaultStore(store)` and publishing reaches it through the purpose fallback, with
+  no extra configuration and no error.
+
+  ### Behaviour
+  - Object keys are `releases/<appVersion>-<revision>/<path>`, so releases no longer overwrite each
+    other. `publish.releasePrefix` in `linked.config.js` changes the base. A manifest may only upload
+    to its own prefix: each `objectKey` is recomputed from the prefix and source path before any
+    write, so an edited or foreign manifest cannot overwrite a different release, and source paths
+    that leave the app root (`../`, absolute, or through a symlink) are refused.
+  - The client bundle is built with `base = <accessURL>/<releasePrefix>/public/bundles/`, so the URLs
+    it emits for its own chunks and assets resolve under the release prefix on a plain static store
+    with no server rewrite. The value is recorded as `destination.baseURL`; the unused `publicRoot`
+    field is gone. The store is therefore resolved before Vite runs, and a release is built for one
+    store.
+  - The release revision comes from a clean `git rev-parse HEAD`. A dirty tree is refused (two builds
+    of the same uncommitted work would share a prefix and overwrite each other); `--allow-dirty`
+    builds as `<sha>-dirty`. `--revision <sha>`, `LINKED_RELEASE_REVISION` and `GITHUB_SHA` work
+    outside a Git checkout.
+  - Cache policy follows a file's origin, not its name: files in the Vite manifest are hashed by
+    construction and get `public, max-age=31536000, immutable`; declared static assets and the
+    release manifest get `public, max-age=60, must-revalidate`. The old filename heuristic gave
+    `og-image-1200x630.png` and `sw-v20260101.js` a year of immutable caching.
+  - `publish.staticAssets` globs are checked per match, not only per pattern, so brace expansion
+    (`public/{,../}secret/**`) and symlinks can no longer pull in files from outside `public/`.
+  - `APP_ENV` selects the Capacitor target only when it is literally `capacitor`. Any other value
+    (`production`, `staging`, …) builds web instead of silently producing an empty, non-publishable
+    manifest.
+  - Files are re-hashed locally against the manifest before upload. The post-upload check uses the
+    optional `IFileStore.statFile`; a store that lacks it, or reports no `sha256`, is warned about once
+    and skipped rather than failing. `etag` is never treated as a content hash.
+  - The manifest records the store's `accessURL` and publishing refuses a store that no longer matches.
+  - Objects are written with `preventDuplicates: false` and a store that reports a different location
+    than the key it was given fails the publish, rather than scattering renamed files.
+  - A failure partway through an upload names the file, the object key, the store and how many objects
+    were already uploaded, and says that re-running resumes the release.
+  - Standalone `publish-app` is a dry run unless `--yes`; only publishable `target: 'web'` manifests
+    upload; the manifest is read before a store is resolved, so a Capacitor manifest fails with a
+    manifest error rather than a storage error; nothing is ever deleted remotely; credentials are
+    redacted from publisher errors.
+  - `build-app`, `publish-app` and `serve-app` print a single error and exit 1 instead of surfacing an
+    unhandled rejection, and `--target`/`--publish`/`--revision`/`--allow-dirty` are rejected on the
+    legacy webpack path instead of being ignored.
+
+  ### New exports
+
+  From `@_linked/cli`: `buildViteApp`, `hasViteConfig`, `publishApp`, `serveCompiledApp`,
+  `validateCompiledAppArtifacts`, `createReleaseManifest`, `serializeReleaseManifest`,
+  `writeReleaseManifest`, `buildReleasePrefix`, `releaseObjectKey`, `getCacheControl`,
+  `planReleasePublish`, `publishRelease`, `loadReleaseManifest`, `resolveAppAssetsStore`,
+  `normalizeAccessURL`, `resolveBuildTarget`, `resolveDeclaredStaticAssets`, `resolveReleaseIdentity`,
+  `resolveSourceRevision`, `releaseBaseURL`, `VITE_OUTPUT_DIR`, the path helpers, and the release
+  types.
+
+  Apps must build with `build.outDir: 'public/bundles'` and `build.manifest: true` (both already set
+  by `createViteConfig`) and must not set `base` themselves; see the README.
+
+  Requires `@_linked/core` 2.20.1 for the purpose-named file stores and `IFileStore.statFile`.
+
+## 1.18.0
+
+### Minor Changes
+
+- [#98](https://github.com/linked-fw/cli/pull/98) [`0d2c4c0`](https://github.com/linked-fw/cli/commit/0d2c4c04f7354af8add4a31c2780597b61d27098) Thanks [@flyon](https://github.com/flyon)! - `setup-publish` scaffolds the consolidated pipeline: two thin caller stubs (`pr.yml`, `publish.yml`) for the shared reusable workflows in `linked-fw/.github` instead of three standalone workflows, and `--configure-github` applies the uniform branch-protection profile (required check `checks / Build & Test`, non-strict, admins enforced). `publishConfig.provenance` is no longer stripped now that publishing is OIDC-first, and `--dual-branch` is a deprecated no-op.
+
 ## 1.17.0
 
 ### Minor Changes

package/README.md

@@ -34,6 +34,8 @@ linked create-component <name>    # add a React component file
 ```bash
 linked build                      # build the current package (tsc + checks)
 linked build-app                  # build frontend + backend for the current app
+linked build-app --target web     # web release: build and write public/bundles/linked-release.json
+linked build-app --target capacitor  # Capacitor/local native build: local manifest only, never published
 linked build-workspace            # build all linked packages in the workspace in dependency order
 linked build-updated              # incremental: only packages that changed since last build
 linked build-package <file>       # walk up from a file path to find its package and rebuild
@@ -43,18 +45,135 @@ linked build-package <file>       # walk up from a file path to find its package
 in a package without `"linkedPackage": true` (it used to exit 0 there). A build that finishes with warnings still
 exits 0.
 
+### App release / production runtime
+
+```bash
+linked build-app                  # build and write the release manifest (never uploads)
+linked build-app --publish        # ...and upload it in the same run
+linked build-app --revision <sha> # identify the release without asking git
+linked build-app --allow-dirty    # allow uncommitted changes; revision gets a "-dirty" suffix
+linked publish-app                # dry-run the release manifest upload (pass --yes to write)
+linked publish-app --yes          # upload the release described by the manifest
+linked publish-app --manifest <p> # publish a manifest other than the default path
+linked serve-app                  # run the compiled backend without Vite/HMR (production runtime)
+```
+
+**Required Vite config.** The release flow reads `vite build` output directly, and the paths are
+hardcoded: the client bundle must land in `public/bundles` and Vite must write its manifest.
+`createViteConfig()` from `@_linked/cli/vite` already sets both; a hand-written `vite.config.ts`
+needs them explicitly:
+
+```ts
+export default defineConfig({
+  build: {
+    outDir: 'public/bundles',  // release object keys are <prefix>/public/bundles/...
+    manifest: true,            // build-app reads public/bundles/.vite/manifest.json
+  },
+});
+```
+
+Without `manifest: true` the build fails with a missing `public/bundles/.vite/manifest.json`; with a
+different `outDir` nothing is found to publish. Do not set `base` yourself — `build-app` passes it
+(see "How a release is served").
+
+**Building is not publishing.** `build-app` compiles the app and writes
+`public/bundles/linked-release.json`, a manifest listing every file of the release with its sha256,
+size, content type and cache policy. `publish-app` uploads exactly the files in that manifest —
+nothing else in `public/` is touched. Pass `--publish` to `build-app` only when you want the two
+chained in one command. `publish-app` is a dry run unless `--yes` is given, and `--manifest <path>`
+publishes a manifest from somewhere other than `public/bundles/linked-release.json` (the path is
+relative to the app root and must stay inside it).
+
+**Where it publishes.** Uploads go to the store returned by
+`LinkedFileStorage.getStore(FileStorePurposes.appAssets)`. Configure a dedicated bundle store with
+`LinkedFileStorage.setStore(FileStorePurposes.appAssets, store)`; an app that configures only
+`setDefaultStore(store)` publishes to that store through the purpose fallback, which needs no extra
+configuration.
+
+**Every release gets its own prefix.** Object keys are
+`releases/<appVersion>-<revision>/<path>`, so publishing a new release cannot overwrite the
+previous one and a rollback means pointing at an older prefix. Set `publish.releasePrefix` in
+`linked.config.js` to change the `releases` base. A manifest may only upload to its own prefix: every
+`objectKey` is recomputed from the prefix and the source path before anything is written, so an
+edited or foreign manifest cannot reach into another release.
+
+**How a release is served.** Because every release has its own key prefix, the bundle's own URLs have
+to carry that prefix — nothing rewrites them at request time. `build-app` therefore resolves the
+store and the release prefix *before* running Vite and passes
+
+```
+base = <store accessURL>/<releasePrefix>/public/bundles/
+```
+
+so the chunk and asset URLs the bundle emits are absolute URLs into the release prefix. This works on
+a plain static store or CDN with no rewrite rules, and two releases can be served side by side. The
+value is recorded as `destination.baseURL` in the release manifest.
+
+The HTML entry tags are not part of the bundle — `@_linked/server` renders them as
+`${STATIC_ACCESS_URL}/public/bundles/<file>`. So serving a particular release is one deployment
+variable, which `build-app` prints when it finishes:
+
+```
+STATIC_ACCESS_URL=<store accessURL>/releases/<appVersion>-<revision>
+```
+
+Set that on the app server (or roll back by setting it to an older release prefix) and the entry
+tags and everything the bundle loads resolve to the same release. Note the consequence of baking the
+base in: a release is built for one store, and pointing it at another means rebuilding.
+
+**Which revision identifies a release.** By default the short `git rev-parse HEAD` of a **clean**
+tree. A dirty tree is refused, because two builds of the same uncommitted work would share a release
+ID and prefix and silently overwrite each other while removed files linger; pass `--allow-dirty` to
+build anyway as `<sha>-dirty`. Outside a Git checkout (an exported tarball, some CI images) pass
+`--revision <sha>`, or set `LINKED_RELEASE_REVISION` or `GITHUB_SHA`; those win over Git and skip
+the clean-tree check.
+
+**Verification.** Files are re-hashed from disk and compared against the manifest immediately before
+upload, so a build that changed since the manifest was written is refused. After upload the store is
+asked for `statFile`; that method is optional and may report no `sha256`, in which case the remote
+check is skipped with a single warning rather than a failure. An `etag` is never used as a content
+hash. The manifest also records the store's `accessURL`, and publishing refuses to run against a
+store that now writes somewhere else. A failure partway through names the file, the object key, the
+store and how many objects were already uploaded; the manifest is uploaded last, so an incomplete
+release is never marked complete, and re-running `publish-app` resumes it.
+
+**The store must keep keys verbatim.** A release object has to be stored under exactly the key it
+was given, or the URLs baked into the bundle point at nothing, so publishing passes
+`preventDuplicates: false` and fails with a clear message if the store reports a different location.
+`@_linked/server`'s `LocalFileStore` lowercases the keys it is handed, so an app publishing to it
+needs lowercase asset filenames (`rollupOptions.output.hashCharacters: 'hex'` in `vite.config`).
+
+**Cache policy follows the origin, not the filename.** Files listed in the Vite manifest are
+content-hashed by construction and get `public, max-age=31536000, immutable`. Everything else —
+declared `publish.staticAssets` and the release manifest — gets
+`public, max-age=60, must-revalidate`. (Guessing from the filename was tried and dropped:
+`og-image-1200x630.png` and `sw-v20260101.js` read as hashed, and a year of immutable caching on
+those cannot be undone without renaming the file.)
+
+**Extra static assets.** `publish.staticAssets` in `linked.config.js` lists globs of files under
+`public/` to ship besides the bundle. Both the pattern and every match must resolve inside
+`public/`, so brace expansion and symlinks cannot pull in files from elsewhere in the repo.
+
+**Capacitor.** `--target capacitor` (or `APP_ENV=capacitor`, matched literally) writes a local,
+non-publishable manifest for inspection. Its assets ship inside the native app, so no file store is
+resolved, no `base` is set and nothing is uploaded, even with `--publish`. Any other `APP_ENV` value
+(`production`, `staging`, …) is ignored by the target choice and builds web.
+
+Use `linked start` for development; use `linked serve-app` after `linked build-app` for
+staging/production.
+
 ### Publishing / release
 
 ```bash
-linked setup-publish              # install a changesets-based publish workflow in the current repo
-linked setup-publish --dual-branch          # use main + dev with @next prereleases
-linked setup-publish --configure-github     # also set branch protection via gh CLI
+linked setup-publish              # install the changesets-based publish pipeline in the current repo
+linked setup-publish --configure-github     # also apply the uniform branch protection via gh CLI
 linked setup-publish --scope community      # use NPM_AUTH_TOKEN_CM instead of NPM_AUTH_TOKEN
 ```
 
 `setup-publish` writes:
 
-- `.github/workflows/ci.yml`, `publish.yml`, `changeset-check.yml`
+- `.github/workflows/pr.yml` and `publish.yml` — thin callers of the shared reusable workflows in
+  `linked-fw/.github`, pinned `@v1`. Any pre-consolidation `ci.yml` / `changeset-check.yml` is removed.
 - `.changeset/config.json` + `README.md`
 - `.gitignore` entries
 - `publishConfig: {access: public}` + `@changesets/cli` devDeps in `package.json`
@@ -140,7 +259,7 @@ Templates live in `defaults/`:
 - `defaults/app-with-backend/` — used by `linked create-app`
 - `defaults/app-static/` — minimal static app
 - `defaults/package/` — used by `linked create-package`
-- `defaults/setup-publish/` — workflow + changeset files written by `linked setup-publish` (single-branch default; `dual-branch/` subdirectory for the `--dual-branch` variant)
+- `defaults/setup-publish/` — caller workflows + changeset files written by `linked setup-publish` (`main`-only; `--dual-branch` is a deprecated no-op)
 
 ### `linked create-app` template structure
 

package/defaults/setup-publish/github/workflows/pr.yml

@@ -0,0 +1,29 @@
+# Calls the shared workflow in linked-fw/.github, which runs both PR gates — `Build & Test` and
+# `Check for changeset` — as jobs of one workflow. The per-repo ci.yml and changeset-check.yml
+# this replaces shared a trigger and were both PR gates.
+#
+# The required status check on `main` is `checks / Build & Test`: GitHub reports a job invoked
+# through `workflow_call` as `<caller-job-id> / <job name>`, and the caller job below is `checks`.
+# Renaming this job renames the check, and a branch protection still pinning the old name waits
+# forever on a check that no longer reports.
+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 it, and the org default is read-only.
+    permissions:
+      contents: read
+      pull-requests: write
+    with:
+      # Left false so a package with no test script passes instead of failing on a missing one.
+      # Set to true — and `test-script` to the unit-only script where `test` is not CI-safe —
+      # once this package has a suite that must exist.
+      require-tests: false
+      run-e2e: false

package/defaults/setup-publish/github/workflows/publish.yml

@@ -1,3 +1,9 @@
+# Calls the shared workflow in linked-fw/.github. That repo is public, so community repos in
+# linked-cm call the same workflow — only the npm secret differs.
+#
+# 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,76 +15,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
-    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'
-
-      - name: Install dependencies
-        run: npm ci --legacy-peer-deps
-
-      - name: Build
-        run: npm run build
-
-      - name: Create release Pull Request or Publish
-        id: changesets
-        uses: changesets/action@v1
-        with:
-          publish: npx changeset publish
-          title: 'chore: release'
-          commit: 'chore: release'
-        # npm auth uses the npm token below. Do NOT switch to OIDC trusted publishing
-        # (id-token: write + publishConfig.provenance) unless you FIRST register this package's
-        # trusted publisher on npmjs.com — otherwise publishes fail with 404 / permission errors.
-        env:
-          GITHUB_TOKEN: ${{ steps.app-token.outputs.token }}
-          NODE_AUTH_TOKEN: ${{ secrets.{{NPM_SECRET_NAME}} }}
-          NPM_TOKEN: ${{ secrets.{{NPM_SECRET_NAME}} }}
-
-      # When changesets opened/updated the version PR (rather than publishing), merge it so the
-      # release ships without a manual click. The App token is used so the merge's push to `main`
-      # re-triggers this workflow, which — now that no changesets remain — runs `changeset publish`.
-      #
-      # NB: DIRECT-merge (not `--auto`). If `main` requires a review, GitHub's auto-merge queue does
-      # NOT honor branch-protection review-bypass allowances and would wait forever on
-      # REVIEW_REQUIRED; a required *status check* is not bypassable either. This repo's `main` is
-      # check-only (no required review), so a direct merge succeeds once the required check is
-      # green — we retry until then.
-      - name: Merge the version PR to publish
-        if: steps.changesets.outputs.hasChangesets == 'true' && steps.changesets.outputs.published != '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 — publish will run on the resulting push to main."
-              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 to publish."
+      # 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 staged approval queue.
+      id-token: write
+    # 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_SECRET_NAME}} }}
+      RELEASE_APP_ID: ${{ secrets.RELEASE_APP_ID }}
+      RELEASE_APP_PRIVATE_KEY: ${{ secrets.RELEASE_APP_PRIVATE_KEY }}

package/lib/esm/app-release/app-assets-store.d.ts

@@ -0,0 +1,23 @@
+import type { IFileStore } from '@_linked/core/interfaces/IFileStore';
+export interface ResolveAppAssetsStoreDependencies {
+    /**
+     * Loads the app's storage bootstrap file. Importing it is what registers the
+     * stores on `LinkedFileStorage`; the module's own exports are not inspected.
+     */
+    loadStorageConfig?: () => Promise<unknown>;
+    /** Injection point for tests. Defaults to `LinkedFileStorage.getStore`. */
+    getStore?: (purpose: string) => IFileStore;
+}
+/**
+ * Resolve the store that release artifacts are published to.
+ *
+ * Apps that dedicate a CDN bucket to bundles configure
+ * `LinkedFileStorage.setStore(FileStorePurposes.appAssets, …)`. Apps with a
+ * single store configure only a default store and `getStore` falls back to it
+ * — that is a supported setup, not an error, so there is no check for a
+ * dedicated store here.
+ */
+export declare const resolveAppAssetsStore: (dependencies?: ResolveAppAssetsStoreDependencies) => Promise<IFileStore>;
+/** `accessURL` values are compared ignoring a trailing slash. */
+export declare const normalizeAccessURL: (accessURL: string) => string;
+//# sourceMappingURL=app-assets-store.d.ts.map

package/lib/esm/app-release/app-assets-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-assets-store.d.ts","sourceRoot":"","sources":["../../../src/app-release/app-assets-store.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,qCAAqC,CAAC;AAEpE,MAAM,WAAW,iCAAiC;IAChD;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IAC3C,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,UAAU,CAAC;CAC5C;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,qBAAqB,GAChC,eAAc,iCAAsC,KACnD,OAAO,CAAC,UAAU,CAapB,CAAC;AAEF,iEAAiE;AACjE,eAAO,MAAM,kBAAkB,GAAI,WAAW,MAAM,KAAG,MACT,CAAC"}

package/lib/esm/app-release/app-assets-store.js

@@ -0,0 +1,33 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { FileStorePurposes, LinkedFileStorage, } from '@_linked/core/utils/LinkedFileStorage';
+/**
+ * Resolve the store that release artifacts are published to.
+ *
+ * Apps that dedicate a CDN bucket to bundles configure
+ * `LinkedFileStorage.setStore(FileStorePurposes.appAssets, …)`. Apps with a
+ * single store configure only a default store and `getStore` falls back to it
+ * — that is a supported setup, not an error, so there is no check for a
+ * dedicated store here.
+ */
+export const resolveAppAssetsStore = (...args_1) => __awaiter(void 0, [...args_1], void 0, function* (dependencies = {}) {
+    const loadStorageConfig = dependencies.loadStorageConfig ||
+        (() => __awaiter(void 0, void 0, void 0, function* () {
+            const { loadBackendStorageConfig } = yield import('../lifecycle.js');
+            return loadBackendStorageConfig();
+        }));
+    yield loadStorageConfig();
+    const getStore = dependencies.getStore ||
+        ((purpose) => LinkedFileStorage.getStore(purpose));
+    return getStore(FileStorePurposes.appAssets);
+});
+/** `accessURL` values are compared ignoring a trailing slash. */
+export const normalizeAccessURL = (accessURL) => (accessURL || '').trim().replace(/\/+$/, '');
+//# sourceMappingURL=app-assets-store.js.map

package/lib/esm/app-release/app-assets-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-assets-store.js","sourceRoot":"","sources":["../../../src/app-release/app-assets-store.ts"],"names":[],"mappings":";;;;;;;;;AAAA,OAAO,EACL,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,uCAAuC,CAAC;AAa/C;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,YAEd,EAAE,mDADvB,eAAkD,EAAE;IAEpD,MAAM,iBAAiB,GACrB,YAAY,CAAC,iBAAiB;QAC9B,CAAC,GAAS,EAAE;YACV,MAAM,EAAC,wBAAwB,EAAC,GAAG,MAAM,MAAM,CAAC,iBAAiB,CAAC,CAAC;YACnE,OAAO,wBAAwB,EAAE,CAAC;QACpC,CAAC,CAAA,CAAC,CAAC;IACL,MAAM,iBAAiB,EAAE,CAAC;IAE1B,MAAM,QAAQ,GACZ,YAAY,CAAC,QAAQ;QACrB,CAAC,CAAC,OAAe,EAAE,EAAE,CAAC,iBAAiB,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC;IAC7D,OAAO,QAAQ,CAAC,iBAAiB,CAAC,SAAS,CAAC,CAAC;AAC/C,CAAC,CAAA,CAAC;AAEF,iEAAiE;AACjE,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,SAAiB,EAAU,EAAE,CAC9D,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC"}

package/lib/esm/app-release/create-release-manifest.d.ts

@@ -0,0 +1,114 @@
+import type { AppBuildTarget, LinkedAppReleaseManifest } from './types.js';
+export interface CreateReleaseManifestOptions {
+    appRoot: string;
+    environmentNames: string[];
+    target: AppBuildTarget;
+    /**
+     * `accessURL` of the store this release will be published to. Omitted (or
+     * null) for a Capacitor build, which produces a local, non-publishable
+     * manifest and never touches a file store.
+     */
+    accessURL?: string | null;
+    staticAssets?: string[];
+    /** Base key releases are nested under. Defaults to `releases`. */
+    releasePrefix?: string;
+    builtAt?: string;
+    sourceRevision?: string;
+    /** Allow a revision derived from a working tree with uncommitted changes. */
+    allowDirty?: boolean;
+    /**
+     * Public URL every asset of this release is served from — the release
+     * prefix resolved against the store's `accessURL`, and the value the client
+     * bundle was built with as Vite's `base`. Empty for a Capacitor build.
+     */
+    baseURL?: string;
+}
+export declare const DEFAULT_RELEASE_PREFIX = "releases";
+export declare const MANIFEST_FILE_NAME = "linked-release.json";
+export declare const MANIFEST_SOURCE_PATH = "public/bundles/linked-release.json";
+export declare const MANIFEST_CONTENT_TYPE = "application/json; charset=utf-8";
+/**
+ * Cache-Control rule, decided by where a file came from rather than by what it
+ * is called.
+ *
+ * Files listed in the Vite manifest are content-hashed by construction — Vite
+ * emitted the name, so the bytes behind that key can never change and the
+ * object is immutable for a year. Everything else (declared static assets, the
+ * release manifest) is revalidated after a minute, so a re-published release is
+ * picked up quickly. Guessing "is this hashed?" from the filename was tried and
+ * removed: `og-image-1200x630.png`, `sw-v20260101.js` and `icon-FacebookRound.svg`
+ * all read as hashed, and a year of immutable caching on those cannot be undone
+ * without renaming the file.
+ */
+export declare const IMMUTABLE_CACHE_CONTROL = "public, max-age=31536000, immutable";
+export declare const ENTRY_CACHE_CONTROL = "public, max-age=60, must-revalidate";
+/** Where a release file came from; this is what decides its cache policy. */
+export type ReleaseFileOrigin = 'vite-bundle' | 'static-asset';
+export declare const getCacheControl: (origin: ReleaseFileOrigin) => string;
+export interface ResolveSourceRevisionOptions {
+    appRoot: string;
+    /** `--revision`, or a caller-supplied value. Used verbatim when given. */
+    revision?: string;
+    /** `--allow-dirty`: build from a dirty tree, tagging the revision `-dirty`. */
+    allowDirty?: boolean;
+    env?: NodeJS.ProcessEnv;
+}
+/**
+ * Determine the revision that identifies this release.
+ *
+ * An explicit `--revision`, then `LINKED_RELEASE_REVISION`, then `GITHUB_SHA`
+ * win over Git, so a release can be built from an exported tarball or a CI
+ * checkout that is not a working repository. Falling back to `git rev-parse`
+ * requires a clean tree: two builds of the same uncommitted work would
+ * otherwise share a release ID and a prefix, silently overwriting each other
+ * while files removed in between linger under the prefix.
+ */
+export declare const resolveSourceRevision: ({ appRoot, revision, allowDirty, env, }: ResolveSourceRevisionOptions) => string;
+/**
+ * Build the key prefix for one release. Every object of a release lives under
+ * it, so publishing a new release cannot overwrite the previous one and a
+ * rollback is a matter of pointing at the older prefix.
+ */
+export declare const buildReleasePrefix: (releaseId: string, basePrefix?: string) => string;
+export declare const releaseObjectKey: (releasePrefix: string, sourcePath: string) => string;
+/** Directory `vite build` writes the client bundle to. See the README. */
+export declare const VITE_OUTPUT_DIR = "public/bundles";
+/**
+ * Public URL the client bundle of a release is served from. Object keys are
+ * `<releasePrefix>/public/bundles/…` under the store's `accessURL`, and this is
+ * the value the build passes to Vite as `base`, so the root-absolute URLs the
+ * bundle emits for its own chunks and assets resolve under the release prefix
+ * without any server rewrite.
+ */
+export declare const releaseBaseURL: (accessURL: string, releasePrefix: string) => string;
+/**
+ * The release's root URL: `accessURL` plus the release prefix, without the
+ * bundle directory. `@_linked/server` builds the HTML entry tags as
+ * `${STATIC_ACCESS_URL}/public/bundles/<file>`, so pointing `STATIC_ACCESS_URL`
+ * at this value is what makes a running app serve one particular release —
+ * a value to deploy, not server code to write or a rewrite rule to configure.
+ */
+export declare const releaseStaticAccessURL: (accessURL: string, releasePrefix: string) => string;
+export interface ReleaseIdentity {
+    appName: string;
+    appVersion: string;
+    sourceRevision: string;
+    releaseId: string;
+    releasePrefix: string;
+}
+/**
+ * Work out the release ID and prefix before anything is built. The client
+ * bundle has to be built with the release prefix as its `base`, so the prefix
+ * cannot wait until the manifest is written.
+ */
+export declare const resolveReleaseIdentity: (options: {
+    appRoot: string;
+    releasePrefix?: string;
+    sourceRevision?: string;
+    allowDirty?: boolean;
+    env?: NodeJS.ProcessEnv;
+}) => ReleaseIdentity;
+export declare const createReleaseManifest: (options: CreateReleaseManifestOptions) => LinkedAppReleaseManifest;
+export declare const serializeReleaseManifest: (manifest: LinkedAppReleaseManifest) => string;
+export declare const writeReleaseManifest: (appRoot: string, manifest: LinkedAppReleaseManifest) => string;
+//# sourceMappingURL=create-release-manifest.d.ts.map

package/lib/esm/app-release/create-release-manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-release-manifest.d.ts","sourceRoot":"","sources":["../../../src/app-release/create-release-manifest.ts"],"names":[],"mappings":"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"}