Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
/**
* Share Bucket — exporter.
*
* Gathers a pipeline series / universe / media item from local state, copies
* the referenced asset blobs (image/video files + per-asset media-job records
* for full-fidelity re-render metadata) into the bucket, then writes a manifest
* pointing at the bundled records.
*
* Asset blobs are content-addressed by SHA-256 and stored at
* `<bucket>/assets/blobs/<hash>` (sidecar metadata at `<hash>.metadata.json`).
* Two manifests that reference identical content under different filenames
* share one blob on disk — the recipient maps the manifest's per-entry
* filename back to the local `data/{kind}/<filename>` location. The asset ref
* carries `{ kind, ref, hash }`; legacy v1 manifests without `hash` still
* import via the `assets/{kind}/<filename>` fallback path.
*/
import { join, basename } from 'path';
import { readFile, stat } from 'fs/promises';
import { existsSync } from 'fs';
import { PATHS, ensureDir, atomicWrite, readJSONFile, sha256File, copyFileGuarded } from '../../lib/fileUtils.js';
import { createKeyCachedQueue } from '../../lib/createKeyCachedQueue.js';
import { getOrComputeImageSha256 } from '../../lib/assetHash.js';
import { isPlainObject } from '../../lib/objects.js';
import { getBucket, ensureBucketLayout, bucketBlobsDir, bucketBlobPath, bucketBlobSidecarPath, bucketBlobIndexPath, bucketRecordsDir, bucketRecordPath, imageSidecarName, isHexHash } from './buckets.js';
import { buildManifest, writeManifest, pruneBucketManifests } from './manifest.js';
import { listSeries, getSeries } from '../pipeline/series.js';
import { listIssuesForSeries } from '../pipeline/issues.js';
import { getReview } from '../pipeline/manuscriptReview.js';
import { getStoredOutline } from '../pipeline/reverseOutline.js';
import { getUniverse } from '../universeBuilder.js';
import { findCollectionByUniverseId, findCollectionBySeriesId } from '../mediaCollections.js';
import { getJob } from '../mediaJobQueue/index.js';
import { getInstanceId } from '../instanceIdentity.js';
import { getSettings } from '../settings.js';
import { getProducedByVersion } from './version.js';
import { PORTOS_SCHEMA_VERSIONS } from '../../lib/schemaVersions.js';
import { listSheetPointers } from '../../lib/storyBible.js';
import { resolveBucketSourceName as resolveSourceName } from './annotationIdentity.js';
import { isStr } from '../../lib/textUtils.js';
import { isSafeRecordId } from '../../lib/validation.js';
/**
* Best-effort cap on the bucket's manifest directory after each export.
* Subscription manifests + peer-authored manifests are exempt — see
* `pruneBucketManifests` for the policy. Failures are logged + swallowed
* so the export response isn't blocked on an archive miss.
*/
async function pruneAfterExport(bucket, senderInstanceId) {
await pruneBucketManifests(bucket, { localInstanceId: senderInstanceId }).catch((err) => {
console.log(`⚠️ sharing.exporter: pruneBucketManifests failed for bucket=${bucket.name}: ${err.message}`);
});
}
async function resolveSourceBio(bucket) {
if (bucket.bioOverride) return bucket.bioOverride;
const settings = await getSettings().catch(() => ({}));
if (isStr(settings?.sharingBio) && settings.sharingBio.trim()) {
return settings.sharingBio.trim();
}
return null;
}
/**
* Copy `<sourceDir>/<filename>` into the bucket's content-addressed blob store.
* Returns `{ kind, ref, hash }`; the recipient maps `ref` (the original
* filename) back to its `data/{kind}/<ref>` slot. Two manifests that ship
* identical bytes under different filenames share one blob.
*
* First-writer wins on sidecar collision: identical bytes imply identical
* gen params in practice, so the second writer's (possibly missing) sidecar
* doesn't overwrite the first's.
*/
// 'image-ref' covers files under data/image-refs/ (multi-ref upload inputs
// + generated character reference sheets). No sidecar handling — these
// don't carry the gen-params metadata sidecar that gallery images do.
const ASSET_SOURCE_DIRS = Object.freeze({
video: PATHS.videos,
image: PATHS.images,
'image-ref': PATHS.imageRefs,
});
/**
* Per-bucket sidecar mapping `<sourcePath>:<mtimeMs>:<size> → <hash>` so a
* re-export of an unchanged asset skips both `sha256File` (multi-GB stream
* read) and the redundant `copyFile`. mtime change invalidates because it's
* part of the key. The cache lives next to the blobs so it shares lifetime
* with the bucket. See `[sharing-exporter-cache-sourcefile-hash-by-mtime]`.
*
* `withAssetHashCache` owns the load/mutate/save lifetime: it loads once,
* runs the body, and only writes when entries were added. Pre-write, it
* re-reads from disk and merges so a sibling exporter (e.g. `exportByKind`
* fanning out parallel `exportSeries` against the same bucket) doesn't get
* its accumulated entries clobbered — same-key collisions converge to the
* same hash since the hash derives from bytes and the key embeds mtime+size.
*/
async function loadAssetHashCache(bucketPath) {
// Rebuildable cache only: a miss hashes/copies the authoritative source bytes;
// the index owns no records, memberships, or deletion history.
const raw = await readJSONFile(bucketBlobIndexPath(bucketPath), {}, { logError: false });
return isPlainObject(raw) ? raw : {};
}
// Per-bucket cache-write queue — serializes the re-load → merge → atomicWrite
// step so two concurrent exporters (e.g. `exportByKind` fanning out parallel
// `exportSeries`) accumulate entries instead of clobbering. The shared queue
// also recovers after a rejected write so one transient bucket failure does not
// poison every later export for the process lifetime.
const cacheWriteQueue = createKeyCachedQueue();
async function withAssetHashCache(bucketPath, fn) {
const cache = await loadAssetHashCache(bucketPath);
const initialKeys = Object.keys(cache).length;
const result = await fn(cache);
if (Object.keys(cache).length !== initialKeys) {
await cacheWriteQueue(bucketPath, async () => {
const onDisk = await loadAssetHashCache(bucketPath);
await atomicWrite(bucketBlobIndexPath(bucketPath), { ...onDisk, ...cache });
});
}
return result;
}
async function copyAssetIfPresent(filename, kind, bucketPath, cache) {
if (!filename || typeof filename !== 'string') return null;
const base = basename(filename);
if (!base || base !== filename) return null; // refuse path traversal
const sourceDir = ASSET_SOURCE_DIRS[kind] || PATHS.images;
await ensureDir(bucketBlobsDir(bucketPath));
const sourcePath = join(sourceDir, base);
const info = await stat(sourcePath).catch(() => null);
if (!info) {
console.log(`⚠️ sharing.exporter: asset not found locally, skipping: ${sourcePath}`);
return null;
}
const cacheKey = `${sourcePath}:${info.mtimeMs}:${info.size}`;
let hash = cache && isHexHash(cache[cacheKey]) ? cache[cacheKey] : null;
if (!hash || !existsSync(bucketBlobPath(bucketPath, hash))) {
// For images, prefer the cross-transport sidecar cache (lib/assetHash) —
// it persists the hash next to the asset so the peer-sync push pipeline
// (which has no bucket context) can read the same value. The bucket
// cache is still populated so future exports inside this bucket take
// the fast path. For non-image kinds (videos), no sidecar exists yet so
// fall through to direct sha256File.
if (kind === 'image') {
const sidecarResult = await getOrComputeImageSha256(sourcePath);
hash = sidecarResult?.hash || (await sha256File(sourcePath));
} else {
hash = await sha256File(sourcePath);
}
if (cache) cache[cacheKey] = hash;
}
const blobPath = bucketBlobPath(bucketPath, hash);
if (!existsSync(blobPath)) await copyFileGuarded(sourcePath, blobPath);
if (kind === 'image') {
const sidecarSource = join(sourceDir, imageSidecarName(base));
if (existsSync(sidecarSource)) {
const sidecarTarget = bucketBlobSidecarPath(bucketPath, hash);
if (!existsSync(sidecarTarget)) await copyFileGuarded(sidecarSource, sidecarTarget);
}
}
return { kind, ref: base, hash };
}
/**
* Build a synthetic job record from a `.metadata.json` sidecar when the
* in-memory queue/archive no longer holds the job (>24h TTL). The sidecar
* lives alongside the image file so its lifetime is tied to the asset.
*
* Guards against path traversal: rejects any jobId that contains a path
* separator, parent-directory token, or otherwise normalizes to something
* other than its bare basename. A corrupted or hostile imageJobId
* (`../../etc/passwd`, `..\foo`, absolute paths) could otherwise read
* arbitrary JSON outside `PATHS.images`. Same posture as `copyAssetIfPresent`.
*/
async function jobFromSidecar(jobId) {
if (typeof jobId !== 'string' || !jobId) return null;
if (basename(jobId) !== jobId) return null;
if (jobId.includes('/') || jobId.includes('\\') || jobId.includes('..')) return null;
// Input-only image metadata: copied into a new export, never written back here.
const sc = await readJSONFile(join(PATHS.images, `${jobId}.metadata.json`));
if (!sc) return null;
// Sidecar schema differs between paths:
// codex.js writes { mode: 'codex', model }
// local.js writes { modelId } and omits `mode` (it's locally-rendered)
// Map both to a unified { mode, model } so re-render fidelity is preserved
// for local renders too (without this, local-render shares lost both fields
// once the in-memory job queue aged out and re-render fell back to defaults).
return {
// The sidecar arrives from buckets and peers verbatim; its own `id` must
// not rename the record written into the bucket (a `../` id escapes it).
id: jobId,
kind: 'image',
owner: null,
status: 'completed',
completedAt: sc.createdAt || null,
params: {
prompt: sc.prompt,
negativePrompt: sc.negativePrompt,
width: sc.width,
height: sc.height,
mode: sc.mode || (sc.modelId ? 'local' : null),
model: sc.model || sc.modelId || null,
seed: sc.seed,
steps: sc.steps,
guidance: sc.guidance,
},
result: { filename: sc.filename },
};
}
/**
* For each `imageJobId`, fetch the live media-job (or look it up in the persisted
* archive) and write a sanitized copy into the bucket records/media/ so the
* recipient can re-render with identical prompt/seed/params. Falls back to the
* per-image `.metadata.json` sidecar for jobs older than the 24h archive TTL.
* Returns the asset refs (image filenames) discovered.
*/
async function exportMediaJobAndAsset(jobId, bucketPath, cache) {
// jobId comes from shared records (imageJobId) and names the bucket record
// file; archives imported before ids were checked may still hold a `../` id.
if (!isSafeRecordId(jobId)) return [];
const job = getJob(jobId) || await jobFromSidecar(jobId);
if (!job) {
console.log(`⚠️ sharing.exporter: imageJobId ${jobId} not found in live queue, archive, or sidecar`);
return [];
}
// Trim transient/runtime fields — keep enough to re-render with full fidelity.
const exported = {
id: job.id,
kind: job.kind,
owner: job.owner,
status: job.status,
completedAt: job.completedAt,
params: job.params,
result: job.result,
};
await ensureDir(bucketRecordsDir(bucketPath, 'media'));
await atomicWrite(bucketRecordPath(bucketPath, 'media', job.id), exported);
// Copy the produced asset(s).
const assetKind = job.kind === 'video' ? 'video' : 'image';
const refs = [];
// result.filename is the canonical single-output shape; some video paths use
// result.videoPath / result.thumbnail; handle both defensively.
if (job.result?.filename) {
const ref = await copyAssetIfPresent(job.result.filename, assetKind, bucketPath, cache);
if (ref) refs.push(ref);
}
if (job.result?.videoPath) {
// videoPath is a filesystem path; we only need its basename here since
// copyAssetIfPresent rebuilds the source dir.
const ref = await copyAssetIfPresent(basename(job.result.videoPath), 'video', bucketPath, cache);
if (ref) refs.push(ref);
}
if (Array.isArray(job.result?.images)) {
for (const im of job.result.images) {
const fname = im?.filename || im?.path;
if (!fname) continue;
const ref = await copyAssetIfPresent(basename(fname), assetKind, bucketPath, cache);
if (ref) refs.push(ref);
}
}
return refs;
}
/**
* Walk a record and collect every (imageJobId, imageRefs, videoPath, sceneVideoJobId)
* it references. Used by the series exporter to enumerate what to copy. The
* caller decides whether to fetch + write the media-job records.
*
* Exported so the peer-sync push pipeline (services/sharing/peerSync.js) can
* build its asset manifest from the same field-walk used for share-bucket
* exports — both transports MUST agree on what counts as "an asset of this
* record" so a missing-assets diff matches what the sender actually owns.
*/
export function collectAssetReferences(record) {
const jobIds = new Set();
const directImageFilenames = new Set();
const directVideoFilenames = new Set();
// Character reference sheets — files live under data/image-refs/, distinct
// from the gallery (data/images/). Tracked separately so the export loop
// can route them through the 'image-ref' source-dir branch.
const directImageRefFilenames = new Set();
const walk = (node) => {
if (!node) return;
if (Array.isArray(node)) { node.forEach(walk); return; }
if (typeof node !== 'object') return;
// Known shape carriers
if (isStr(node.imageJobId)) jobIds.add(node.imageJobId);
if (isStr(node.sceneVideoJobId)) jobIds.add(node.sceneVideoJobId);
if (Array.isArray(node.imageRefs)) {
for (const r of node.imageRefs) if (isStr(r)) directImageFilenames.add(r);
}
// Every character-sheet variant the renderer produced — legacy + map.
// listSheetPointers yields one entry per non-empty pointer regardless of
// storage shape, so the export bundle includes every render.
for (const { filename } of listSheetPointers(node)) {
if (isStr(filename)) directImageRefFilenames.add(filename);
}
if (isStr(node.videoPath)) directVideoFilenames.add(basename(node.videoPath));
for (const k of Object.keys(node)) {
const v = node[k];
if (v && (Array.isArray(v) || typeof v === 'object')) walk(v);
}
};
walk(record);
return {
jobIds: [...jobIds],
directImageFilenames: [...directImageFilenames],
directVideoFilenames: [...directVideoFilenames],
directImageRefFilenames: [...directImageRefFilenames],
};
}
/**
* Walk a collection's items and return:
* - assetFilenames: every {kind, ref} pair to copy into the bucket
* - jobIds: every media-job record the items resolve to (for re-render
* metadata fidelity on the recipient side — same logic as imageJobId
* resolution on canon entries)
*
* The serialized `collection` payload in the manifest carries the raw
* items + the linked owner id (universeId OR seriesId) + the canonical
* name; the recipient's importer reuses these to find-or-create a local
* collection of the same name and add the items.
*/
function collectCollectionAssets(collection) {
const assetFilenames = [];
const jobIds = new Set();
if (!collection) return { assetFilenames, jobIds: [] };
for (const it of collection.items || []) {
if (!it?.ref || typeof it.ref !== 'string') continue;
assetFilenames.push({ kind: it.kind, ref: it.ref });
// Strip extension to recover the media-job id (matches the convention
// used in exportMedia's lookup path: filenames are `<jobId>.<ext>`).
const baseId = it.ref.replace(/\.[a-z0-9]+$/i, '');
if (baseId && baseId !== it.ref) jobIds.add(baseId);
}
return { assetFilenames, jobIds: [...jobIds] };
}
/** Stamp the outgoing record with origin metadata. */
function stampOrigin(record, { bucket, source, sourceBio, manifestId }) {
// `importDraft` (issue #727) is a LOCAL-only importer-orphan GC marker — it
// must never travel in a share bucket, or an importing peer could inherit it
// and have its copy swept by the orphan GC. Strip it here so the exported
// record honors the local-only contract (the importer also strips inbound,
// belt-and-suspenders). In practice only universes/series ever carry it.
const { importDraft: _importDraft, ...rest } = record;
return {
...rest,
origin: {
bucketId: bucket.id,
bucketName: bucket.name,
source,
sourceBio,
manifestId,
importedAt: new Date().toISOString(),
},
};
}
/**
* Export a full series (with its issues + linked universe + every asset).
*
* `opts.subscription` (optional): when set to `{ recordKind, recordId }` the
* manifest is marked as a subscription — bucket-side filename becomes
* deterministic (`sub-series-<id>-<senderInstanceId>.json`) so re-exports
* overwrite in place instead of accumulating, and two peers sharing the same
* series don't collide on the bucket file. Omit for one-shot legacy shares.
*
* `opts.isLive` (optional async predicate): consulted right before the
* manifest is written. When it resolves false (the subscription was removed
* mid-export) the manifest write is skipped and the export returns `null`;
* already-copied records/blobs are left for blob GC.
*/
export async function exportSeries(seriesId, bucketId, opts = {}) {
const bucket = await getBucket(bucketId);
await ensureBucketLayout(bucket);
const series = await getSeries(seriesId);
const issues = await listIssuesForSeries(seriesId, { includeDeleted: false });
let universe = null;
let linkedCollection = null;
if (series.universeId) {
universe = await getUniverse(series.universeId).catch(() => null);
if (universe) linkedCollection = await findCollectionByUniverseId(universe.id);
}
// Per-series fallback so a universeless series still ships with its
// auto-filed cover renders via the seriesId-stamped collection. Gate on
// `series.universeId` being absent — a series that has been linked to a
// universe must always export under the universe-collection contract,
// even if a stale seriesId-stamped collection survives from before the
// link (orphaned mid-flight by `unlinkCollectionsForUniverse` recovery, or
// a legacy bucket from an earlier universeless state).
if (!linkedCollection && !series.universeId) {
linkedCollection = await findCollectionBySeriesId(series.id);
}
const [source, sourceBio, senderInstanceId, producedByVersion] = await Promise.all([
resolveSourceName(bucket),
resolveSourceBio(bucket),
getInstanceId().catch(() => null),
getProducedByVersion(),
]);
// Pre-build manifest id so we can stamp it onto every record's origin.
const manifestStub = buildManifest({
kind: 'series',
senderInstanceId,
source, sourceBio,
producedByVersion,
portosSchemaVersions: PORTOS_SCHEMA_VERSIONS,
subscription: opts.subscription || null,
collection: linkedCollection,
bucketId: bucket.id,
bucketName: bucket.name,
recordIds: [],
assetRefs: [],
});
const manifestId = manifestStub.id;
// Write records.
const recordIds = [series.id];
const stampedSeries = stampOrigin(series, { bucket, source, sourceBio, manifestId });
await atomicWrite(bucketRecordPath(bucket.path, 'series', series.id), stampedSeries);
// Bundle the manuscript-review sibling doc (the "Finish the draft" comment
// set) so it travels with the series. It's keyed by seriesId — not a record
// id of its own — so it lives under records/reviews/ and is NOT added to
// `recordIds` (the importer reads it by seriesId after the series merges).
// Skip when empty so we don't litter the bucket with no-op review files; an
// importer that finds no file simply leaves the local review untouched.
const review = await getReview(series.id).catch(() => null);
const reviewRefs = [];
if (review && Array.isArray(review.comments) && review.comments.length > 0) {
await atomicWrite(bucketRecordPath(bucket.path, 'reviews', series.id), review);
reviewRefs.push(series.id);
}
// Bundle the reverse-outline sibling doc (#1348) on the same terms as the
// review: keyed by seriesId under records/outlines/, NOT in `recordIds` (read
// by seriesId after the series merges). Only a `complete` outline is shipped;
// an importer that finds no file leaves the local outline untouched.
const outline = await getStoredOutline(series.id).catch(() => null);
const outlineRefs = [];
if (outline && outline.status === 'complete') {
await atomicWrite(bucketRecordPath(bucket.path, 'outlines', series.id), outline);
outlineRefs.push(series.id);
}
for (const issue of issues) {
recordIds.push(issue.id);
const stamped = stampOrigin(issue, { bucket, source, sourceBio, manifestId });
await atomicWrite(bucketRecordPath(bucket.path, 'issues', issue.id), stamped);
}
if (universe) {
recordIds.push(universe.id);
const stampedUni = stampOrigin(universe, { bucket, source, sourceBio, manifestId });
await atomicWrite(bucketRecordPath(bucket.path, 'universes', universe.id), stampedUni);
}
// Gather asset refs across every record, plus the universe's linked
// collection items (if any) so universe-render output ships alongside
// the series.
const allJobIds = new Set();
const allImageFiles = new Set();
const allVideoFiles = new Set();
const allImageRefFiles = new Set();
for (const rec of [series, ...issues, universe].filter(Boolean)) {
const refs = collectAssetReferences(rec);
refs.jobIds.forEach((j) => allJobIds.add(j));
refs.directImageFilenames.forEach((f) => allImageFiles.add(f));
refs.directVideoFilenames.forEach((f) => allVideoFiles.add(f));
refs.directImageRefFilenames.forEach((f) => allImageRefFiles.add(f));
}
if (linkedCollection) {
const collAssets = collectCollectionAssets(linkedCollection);
collAssets.jobIds.forEach((j) => allJobIds.add(j));
for (const a of collAssets.assetFilenames) {
if (a.kind === 'video') allVideoFiles.add(a.ref); else allImageFiles.add(a.ref);
}
}
// Copy media-job records + their assets — run all four groups in parallel.
const assetRefs = await withAssetHashCache(bucket.path, async (cache) => {
const [jobRefGroups, imageRefs, videoRefs, imageRefRefs] = await Promise.all([
Promise.all([...allJobIds].map((jobId) => exportMediaJobAndAsset(jobId, bucket.path, cache))),
Promise.all([...allImageFiles].map((f) => copyAssetIfPresent(f, 'image', bucket.path, cache))),
Promise.all([...allVideoFiles].map((f) => copyAssetIfPresent(f, 'video', bucket.path, cache))),
Promise.all([...allImageRefFiles].map((f) => copyAssetIfPresent(f, 'image-ref', bucket.path, cache))),
]);
return [...jobRefGroups.flat(), ...imageRefs.filter(Boolean), ...videoRefs.filter(Boolean), ...imageRefRefs.filter(Boolean)];
});
const manifest = { ...manifestStub, recordIds, assetRefs, reviewRefs, outlineRefs };
if (opts.isLive && !(await opts.isLive())) return null;
const filename = await writeManifest(bucket.path, manifest);
await pruneAfterExport(bucket, senderInstanceId);
return { manifestId, filename, recordCount: recordIds.length, assetCount: assetRefs.length };
}
/** Export a universe on its own (no series attached). See exportSeries for opts. */
export async function exportUniverse(universeId, bucketId, opts = {}) {
const bucket = await getBucket(bucketId);
await ensureBucketLayout(bucket);
const universe = await getUniverse(universeId);
const linkedCollection = await findCollectionByUniverseId(universe.id);
const [source, sourceBio, senderInstanceId, producedByVersion] = await Promise.all([
resolveSourceName(bucket),
resolveSourceBio(bucket),
getInstanceId().catch(() => null),
getProducedByVersion(),
]);
const manifestStub = buildManifest({
kind: 'universe',
senderInstanceId,
source, sourceBio,
producedByVersion,
portosSchemaVersions: PORTOS_SCHEMA_VERSIONS,
subscription: opts.subscription || null,
collection: linkedCollection,
bucketId: bucket.id,
bucketName: bucket.name,
recordIds: [],
assetRefs: [],
});
const manifestId = manifestStub.id;
const stamped = stampOrigin(universe, { bucket, source, sourceBio, manifestId });
await atomicWrite(bucketRecordPath(bucket.path, 'universes', universe.id), stamped);
// Combine universe-record asset refs with the linked collection's assets
// so a single export pass pulls everything the universe needs.
const universeRefs = collectAssetReferences(universe);
const collectionAssets = collectCollectionAssets(linkedCollection);
const allJobIds = new Set([...universeRefs.jobIds, ...collectionAssets.jobIds]);
const allImageFiles = new Set([
...universeRefs.directImageFilenames,
...collectionAssets.assetFilenames.filter((a) => a.kind === 'image').map((a) => a.ref),
]);
const allVideoFiles = new Set(
collectionAssets.assetFilenames.filter((a) => a.kind === 'video').map((a) => a.ref),
);
const allImageRefFiles = new Set(universeRefs.directImageRefFilenames);
const assetRefs = await withAssetHashCache(bucket.path, async (cache) => {
const [jobRefGroups, imageRefs, videoRefs, imageRefRefs] = await Promise.all([
Promise.all([...allJobIds].map((jobId) => exportMediaJobAndAsset(jobId, bucket.path, cache))),
Promise.all([...allImageFiles].map((f) => copyAssetIfPresent(f, 'image', bucket.path, cache))),
Promise.all([...allVideoFiles].map((f) => copyAssetIfPresent(f, 'video', bucket.path, cache))),
Promise.all([...allImageRefFiles].map((f) => copyAssetIfPresent(f, 'image-ref', bucket.path, cache))),
]);
return [...jobRefGroups.flat(), ...imageRefs.filter(Boolean), ...videoRefs.filter(Boolean), ...imageRefRefs.filter(Boolean)];
});
const manifest = { ...manifestStub, recordIds: [universe.id], assetRefs };
if (opts.isLive && !(await opts.isLive())) return null;
const filename = await writeManifest(bucket.path, manifest);
await pruneAfterExport(bucket, senderInstanceId);
return { manifestId, filename, recordCount: 1, assetCount: assetRefs.length };
}
/**
* Export individual media items (images / videos identified by `{ kind, ref }`).
* Looks up each ref's media-job (best effort) to bundle prompt/params alongside
* the blob. If no job is found (manually uploaded image), the blob still ships
* but without re-render metadata — recipient sees the file with no params.
*/
export async function exportMedia(items, bucketId) {
const bucket = await getBucket(bucketId);
await ensureBucketLayout(bucket);
const [source, sourceBio, senderInstanceId, producedByVersion] = await Promise.all([
resolveSourceName(bucket),
resolveSourceBio(bucket),
getInstanceId().catch(() => null),
getProducedByVersion(),
]);
const manifestStub = buildManifest({
kind: 'media',
senderInstanceId,
source, sourceBio,
producedByVersion,
portosSchemaVersions: PORTOS_SCHEMA_VERSIONS,
bucketId: bucket.id,
bucketName: bucket.name,
recordIds: [],
assetRefs: [],
});
const manifestId = manifestStub.id;
// Pre-resolve each item to a job (or null) so we know what to parallelize
// and what record ids to collect for the manifest.
const resolved = (items || []).flatMap((item) => {
if (!item || typeof item !== 'object') return [];
const ref = isStr(item.ref) ? item.ref.trim() : '';
if (!ref) return [];
const kind = item.kind === 'video' ? 'video' : 'image';
const baseId = ref.replace(/\.[a-z0-9]+$/i, '');
return [{ ref, kind, job: getJob(baseId) }];
});
const recordIds = resolved.filter((r) => r.job).map((r) => r.job.id);
const assetRefs = await withAssetHashCache(bucket.path, async (cache) => {
const results = await Promise.all(resolved.map(async (r) => {
if (r.job) return exportMediaJobAndAsset(r.job.id, bucket.path, cache);
const copied = await copyAssetIfPresent(r.ref, r.kind, bucket.path, cache);
return copied ? [copied] : [];
}));
return results.flat();
});
const manifest = { ...manifestStub, recordIds, assetRefs };
const filename = await writeManifest(bucket.path, manifest);
await pruneAfterExport(bucket, senderInstanceId);
return { manifestId, filename, recordCount: recordIds.length, assetCount: assetRefs.length };
}
/** Dispatch by kind. */
export async function exportByKind({ kind, ids, items, bucketId }) {
if (kind === 'series') {
if (!Array.isArray(ids) || ids.length === 0) throw new Error('exportByKind: ids required for series');
const results = await Promise.all(ids.map((id) => exportSeries(id, bucketId)));
return { exports: results };
}
if (kind === 'universe') {
if (!Array.isArray(ids) || ids.length === 0) throw new Error('exportByKind: ids required for universe');
const results = await Promise.all(ids.map((id) => exportUniverse(id, bucketId)));
return { exports: results };
}
if (kind === 'media') {
if (!Array.isArray(items) || items.length === 0) throw new Error('exportByKind: items required for media');
return { exports: [await exportMedia(items, bucketId)] };
}
throw new Error(`exportByKind: unknown kind '${kind}'`);
}