@_linked/cli 1.18.0 → 1.19.0

package/CHANGELOG.md

@@ -1,5 +1,92 @@
 # 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

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,6 +45,123 @@ 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

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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"}

package/lib/esm/app-release/create-release-manifest.js

@@ -0,0 +1,238 @@
+import crypto from 'crypto';
+import { execFileSync } from 'child_process';
+import fs from 'fs';
+import path from 'path';
+import { joinObjectKey, normalizeReleasePath, resolveExistingPathWithinRoot, } from './paths.js';
+import { resolveDeclaredStaticAssets } from './static-assets.js';
+const MIME_TYPES = {
+    '.css': 'text/css; charset=utf-8',
+    '.gif': 'image/gif',
+    '.html': 'text/html; charset=utf-8',
+    '.ico': 'image/x-icon',
+    '.jpeg': 'image/jpeg',
+    '.jpg': 'image/jpeg',
+    '.js': 'text/javascript; charset=utf-8',
+    '.json': 'application/json; charset=utf-8',
+    '.map': 'application/json; charset=utf-8',
+    '.png': 'image/png',
+    '.svg': 'image/svg+xml',
+    '.webp': 'image/webp',
+    '.woff': 'font/woff',
+    '.woff2': 'font/woff2',
+};
+export const DEFAULT_RELEASE_PREFIX = 'releases';
+export const MANIFEST_FILE_NAME = 'linked-release.json';
+export const MANIFEST_SOURCE_PATH = `public/bundles/${MANIFEST_FILE_NAME}`;
+export 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 const IMMUTABLE_CACHE_CONTROL = 'public, max-age=31536000, immutable';
+export const ENTRY_CACHE_CONTROL = 'public, max-age=60, must-revalidate';
+const getContentType = (filePath) => MIME_TYPES[path.extname(filePath).toLowerCase()] || 'application/octet-stream';
+export const getCacheControl = (origin) => origin === 'vite-bundle' ? IMMUTABLE_CACHE_CONTROL : ENTRY_CACHE_CONTROL;
+/** A revision has to be safe to embed in an object key and a URL. */
+const SAFE_REVISION = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+const runGit = (appRoot, args) => execFileSync('git', args, {
+    cwd: appRoot,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'ignore'],
+});
+/**
+ * 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 const resolveSourceRevision = ({ appRoot, revision, allowDirty, env = process.env, }) => {
+    const explicit = (revision ||
+        env.LINKED_RELEASE_REVISION ||
+        env.GITHUB_SHA ||
+        '').trim();
+    if (explicit) {
+        if (!SAFE_REVISION.test(explicit)) {
+            throw new Error(`Invalid release revision "${explicit}". Use letters, digits, ".", "-" or "_".`);
+        }
+        return explicit;
+    }
+    let head;
+    try {
+        head = runGit(appRoot, ['rev-parse', '--short=12', 'HEAD']).trim();
+    }
+    catch (_a) {
+        throw new Error('Cannot determine the Git revision for this release. Build from a Git checkout, ' +
+            'or pass --revision <sha> (or set LINKED_RELEASE_REVISION / GITHUB_SHA).');
+    }
+    let dirty = false;
+    try {
+        dirty = runGit(appRoot, ['status', '--porcelain']).trim().length > 0;
+    }
+    catch (_b) {
+        // `rev-parse` worked, so this is a repository; treat an unreadable status
+        // as clean rather than blocking the build on a Git quirk.
+    }
+    if (!dirty)
+        return head;
+    if (!allowDirty) {
+        throw new Error(`The working tree has uncommitted changes, so release ${head} would not identify ` +
+            'what was built: a second build of the same edits reuses the prefix and overwrites it. ' +
+            'Commit or stash the changes, pass --allow-dirty to publish as ' +
+            `"${head}-dirty", or pass --revision <sha>.`);
+    }
+    return `${head}-dirty`;
+};
+const collectViteOutputPaths = (manifest) => {
+    const files = new Set();
+    for (const [entryName, entry] of Object.entries(manifest)) {
+        if (!entry || typeof entry.file !== 'string') {
+            throw new Error(`Invalid Vite manifest entry: ${entryName}`);
+        }
+        files.add(joinObjectKey('public/bundles', entry.file));
+        for (const relativePath of [...(entry.css || []), ...(entry.assets || [])]) {
+            files.add(joinObjectKey('public/bundles', relativePath));
+        }
+        for (const importedEntry of [
+            ...(entry.imports || []),
+            ...(entry.dynamicImports || []),
+        ]) {
+            if (!manifest[importedEntry]) {
+                throw new Error(`Vite manifest entry ${entryName} references missing import ${importedEntry}`);
+            }
+        }
+    }
+    return [...files];
+};
+/**
+ * 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 const buildReleasePrefix = (releaseId, basePrefix = DEFAULT_RELEASE_PREFIX) => joinObjectKey(basePrefix, releaseId);
+export const releaseObjectKey = (releasePrefix, sourcePath) => joinObjectKey(releasePrefix, sourcePath);
+/** Directory `vite build` writes the client bundle to. See the README. */
+export 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 const releaseBaseURL = (accessURL, releasePrefix) => `${releaseStaticAccessURL(accessURL, releasePrefix)}/${VITE_OUTPUT_DIR}/`;
+/**
+ * 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 const releaseStaticAccessURL = (accessURL, releasePrefix) => `${(accessURL || '').trim().replace(/\/+$/, '')}/${releasePrefix}`;
+/**
+ * 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 const resolveReleaseIdentity = (options) => {
+    const packageJson = JSON.parse(fs.readFileSync(path.join(options.appRoot, 'package.json'), 'utf8'));
+    const sourceRevision = resolveSourceRevision({
+        appRoot: options.appRoot,
+        revision: options.sourceRevision,
+        allowDirty: options.allowDirty,
+        env: options.env,
+    });
+    const releaseId = `${packageJson.version}-${sourceRevision}`;
+    return {
+        appName: packageJson.name,
+        appVersion: packageJson.version,
+        sourceRevision,
+        releaseId,
+        releasePrefix: buildReleasePrefix(releaseId, options.releasePrefix),
+    };
+};
+const describeReleaseFile = (appRoot, releasePrefix, sourcePath, origin) => {
+    const normalizedSourcePath = normalizeReleasePath(sourcePath, 'source path');
+    const absolutePath = resolveExistingPathWithinRoot(appRoot, normalizedSourcePath);
+    const content = fs.readFileSync(absolutePath);
+    return {
+        sourcePath: normalizedSourcePath,
+        objectKey: releaseObjectKey(releasePrefix, normalizedSourcePath),
+        sha256: crypto.createHash('sha256').update(content).digest('hex'),
+        size: content.byteLength,
+        contentType: getContentType(normalizedSourcePath),
+        cacheControl: getCacheControl(origin),
+    };
+};
+export const createReleaseManifest = (options) => {
+    var _a;
+    const identity = resolveReleaseIdentity({
+        appRoot: options.appRoot,
+        releasePrefix: options.releasePrefix,
+        sourceRevision: options.sourceRevision,
+        allowDirty: options.allowDirty,
+    });
+    const { releasePrefix } = identity;
+    // A Capacitor build ships its assets inside the native app, so it produces a
+    // manifest for local inspection only and is never uploaded. That is why it
+    // needs no destination and is marked unpublishable.
+    const publishable = options.target === 'web';
+    if (publishable && options.accessURL === undefined) {
+        throw new Error('A web release manifest requires the accessURL of the store it will be published to');
+    }
+    // Origin decides the cache policy: Vite named these files after their own
+    // content, so they are immutable; declared static assets keep their name
+    // across releases and must be revalidated.
+    const origins = new Map();
+    if (options.target === 'web') {
+        const viteManifestPath = path.join(options.appRoot, `${VITE_OUTPUT_DIR}/.vite/manifest.json`);
+        const viteManifest = JSON.parse(fs.readFileSync(viteManifestPath, 'utf8'));
+        for (const sourcePath of collectViteOutputPaths(viteManifest)) {
+            origins.set(sourcePath, 'vite-bundle');
+        }
+    }
+    for (const sourcePath of resolveDeclaredStaticAssets(options.appRoot, options.staticAssets)) {
+        if (!origins.has(sourcePath))
+            origins.set(sourcePath, 'static-asset');
+    }
+    const files = [...origins.entries()]
+        .map(([sourcePath, origin]) => describeReleaseFile(options.appRoot, releasePrefix, sourcePath, origin))
+        .sort((a, b) => a.objectKey.localeCompare(b.objectKey));
+    return {
+        schemaVersion: 1,
+        appName: identity.appName,
+        appVersion: identity.appVersion,
+        releaseId: identity.releaseId,
+        target: options.target,
+        publishable,
+        builtAt: options.builtAt || new Date().toISOString(),
+        environmentNames: [...options.environmentNames],
+        destination: {
+            accessURL: options.accessURL || '',
+            releasePrefix,
+            baseURL: (_a = options.baseURL) !== null && _a !== void 0 ? _a : (options.accessURL
+                ? releaseBaseURL(options.accessURL, releasePrefix)
+                : ''),
+        },
+        files,
+    };
+};
+export const serializeReleaseManifest = (manifest) => `${JSON.stringify(manifest, null, 2)}\n`;
+export const writeReleaseManifest = (appRoot, manifest) => {
+    const outputPath = path.join(appRoot, MANIFEST_SOURCE_PATH);
+    fs.writeFileSync(outputPath, serializeReleaseManifest(manifest));
+    return outputPath;
+};
+//# sourceMappingURL=create-release-manifest.js.map