@drawcall/market 0.1.98 → 0.2.0

package/src/pack.ts

@@ -1,15 +1,26 @@
+import { createHash } from 'crypto'
 import * as fs from 'fs/promises'
 import * as path from 'path'
 import { unzipSync, zipSync } from 'fflate'
 import ignore from 'ignore'
+import type { MarketClient } from './client.js'
 import type { AssetInstallMetadata } from './contract.js'
 import { findInstallRoot } from './install.js'
-import { readMarketLock, sha256 } from './market-lock.js'
 import {
+  packageJsonAssetDependencies,
   packageJsonAssetDependenciesFromFiles,
   packageJsonNpmDependenciesFromFiles,
+  parsePackageJson,
 } from './package-json.js'
-import { MAX_UPLOAD_ZIP_SIZE_BYTES, type AssetType } from './schemas.js'
+import {
+  MAX_UPLOAD_ZIP_SIZE_BYTES,
+  assetDependencyAlias,
+  assetDependencyRange,
+  assetDependencyValue,
+  semverSchema,
+  type AssetDependencies,
+  type AssetType,
+} from './schemas.js'
 
 export interface PackDependencySpecs {
   npm?: string[]
@@ -28,16 +39,17 @@ export interface PackPolicy {
   omitUnchangedInstalledFiles: boolean
 }
 
-export type FetchFileManifest = (name: string, version: string) => Promise<Record<string, string>>
+export type FetchFileManifest = (name: string, range: string) => Promise<Record<string, string>>
 
 export interface PackAssetOptions {
   cwd?: string
   dependencies: ParsedPackDependencies
   policy?: PackPolicy
   /**
-   * Fetch the server's content hashes for an installed dependency version (see `asset.fileManifest`),
-   * so a template omits its unchanged installed dependency files. Content hashes are no longer stored
-   * locally, so omitting needs the API — omit this (or a failing fetch) and those files are kept.
+   * Fetch the server's content hashes for a dependency's files (see `asset.fileManifest`), given
+   * the declared range. Pack matches local files against these hashes by content — independent of
+   * path, so renamed installed files are omitted too and recorded as aliases. Omit this (or a
+   * failing fetch) and the dependency's files are kept.
    */
   fetchFileManifest?: FetchFileManifest
 }
@@ -46,13 +58,41 @@ export interface PackedAsset {
   sourcePath: string
   zip: Uint8Array
   npmDependencies: Record<string, string>
-  assetDependencies: Record<string, string>
+  assetDependencies: AssetDependencies
   skillDependencies: Record<string, string>
   omittedUnchangedInstalledFiles: boolean
   /** Number of zip entries dropped because a `.gitignore` inside the zip excluded them. */
   gitignoredFiles: number
 }
 
+export function sha256(bytes: Uint8Array): string {
+  return createHash('sha256').update(bytes).digest('hex')
+}
+
+/**
+ * A `FetchFileManifest` backed by the Market API. The manifest endpoint needs an exact version, so
+ * an exact declared range is used directly and any other range resolves to the latest version —
+ * without a local lockfile the installed version is not recorded, and content addressing keeps a
+ * mismatch safe: a stale hash simply fails to match and the file is kept.
+ */
+export function fileManifestForRange(asset: MarketClient['asset']): FetchFileManifest {
+  return async (name, range) => {
+    const exact = exactRangeVersion(range)
+    const meta = await asset.exact({
+      name,
+      ...(exact ? { version: exact } : {}),
+      includeUnapproved: true,
+    })
+    if (!meta) return {}
+    return asset.fileManifest({ name, version: meta.version ?? meta.latestVersion })
+  }
+}
+
+function exactRangeVersion(range: string): string | null {
+  const candidate = range.trim().replace(/^=/u, '')
+  return semverSchema.safeParse(candidate).success ? candidate : null
+}
+
 export async function packAsset(zipFilter: string, opts: PackAssetOptions): Promise<PackedAsset> {
   const cwd = opts.cwd ?? process.cwd()
 
@@ -85,17 +125,21 @@ export async function packAsset(zipFilter: string, opts: PackAssetOptions): Prom
   const npmDependencies = { ...packageJsonNpmDependencies, ...opts.dependencies.npmDependencies }
 
   // Drop anything the zip's own .gitignore excludes (node_modules, build output, secrets…), then —
-  // for templates — omit unchanged installed dependency files. Only removals happen, so a smaller
-  // count means something was dropped; re-zip only then.
+  // for templates — omit each installed dependency file at its resolved location (matched by
+  // content hash, so renamed copies are dropped too and recorded as aliases; duplicates ship).
+  // Only removals happen, so a smaller count means something was dropped; re-zip only then.
   const { kept: withoutIgnored, gitignored } = applyGitignore(sourceFiles)
-  const files = policy.omitUnchangedInstalledFiles
-    ? await withoutUnchangedInstalledFiles(
-        withoutIgnored,
-        assetDependencies,
-        cwd,
-        opts.fetchFileManifest,
-      )
-    : withoutIgnored
+  let files = withoutIgnored
+  let finalAssetDependencies = assetDependencies
+  if (policy.omitUnchangedInstalledFiles) {
+    const omitted = await withoutInstalledDependencyFiles(
+      withoutIgnored,
+      assetDependencies,
+      opts.fetchFileManifest,
+    )
+    files = omitted.kept
+    finalAssetDependencies = omitted.assetDependencies
+  }
 
   const originalCount = Object.keys(sourceFiles).length
   const afterIgnoreCount = Object.keys(withoutIgnored).length
@@ -105,7 +149,7 @@ export async function packAsset(zipFilter: string, opts: PackAssetOptions): Prom
     sourcePath: zipFile,
     zip: finalCount < originalCount ? zipSync(files) : sourceZip,
     npmDependencies,
-    assetDependencies,
+    assetDependencies: finalAssetDependencies,
     skillDependencies: opts.dependencies.skillDependencies,
     omittedUnchangedInstalledFiles: finalCount < afterIgnoreCount,
     gitignoredFiles: gitignored,
@@ -113,8 +157,11 @@ export async function packAsset(zipFilter: string, opts: PackAssetOptions): Prom
 }
 
 // Pack straight from a project directory. Walk order matters for speed: `.gitignore` rules prune
-// whole subtrees before anything is read, lock-hash checks read only files a dependency owns, and
-// only the survivors are ever held in memory / compressed.
+// whole subtrees before anything is read, and only the survivors are ever held in memory /
+// compressed. Installed dependency files are matched by content hash — independent of their path —
+// so renamed copies are omitted too (exactly one per dependency file; duplicates ship). The
+// resolved location is recorded as an alias on the dependency entry and written back to
+// package.json, which is how a later install restores the renamed layout.
 async function packDirectory(dir: string, opts: PackAssetOptions): Promise<PackedAsset> {
   const hasRootPackageJson = Boolean(await maybeStat(path.join(dir, 'package.json')))
   const policy = opts.policy ?? {
@@ -143,24 +190,43 @@ async function packDirectory(dir: string, opts: PackAssetOptions): Promise<Packe
     ...opts.dependencies.npmDependencies,
   }
 
-  // Content hashes of installed dependency files (from the server), so an unchanged one is dropped
-  // after a single read.
-  const hashesByPath = policy.omitUnchangedInstalledFiles
-    ? await installedDependencyHashes(dir, assetDependencies, opts.fetchFileManifest)
-    : new Map<string, string>()
+  const index = policy.omitUnchangedInstalledFiles
+    ? await dependencyFileIndex(assetDependencies, opts.fetchFileManifest)
+    : emptyDependencyFileIndex()
+  const dependencyHashes = new Set(index.files.map((file) => file.hash))
 
+  // Files whose bytes match a dependency file are deferred: whether one is omitted or ships (a
+  // duplicate copy) is only known once the whole tree is hashed, and deferring keeps dependency
+  // bytes out of memory during the walk.
   const files: Record<string, Uint8Array> = {}
-  let omittedInstalled = 0
+  const hashesByPath = new Map<string, string>()
+  const deferred: string[] = []
   for (const relative of walk.kept) {
     const content = new Uint8Array(await fs.readFile(path.join(dir, relative)))
-    const lockedHash = hashesByPath.get(relative)
-    if (lockedHash && lockedHash === sha256(content)) {
-      omittedInstalled += 1
+    if (dependencyHashes.size === 0) {
+      files[relative] = content
+      continue
+    }
+    const hash = sha256(content)
+    hashesByPath.set(relative, hash)
+    if (dependencyHashes.has(hash)) {
+      deferred.push(relative)
       continue
     }
     files[relative] = content
   }
 
+  const layout = resolveDependencyLayout(assetDependencies, index, hashesByPath)
+  for (const relative of deferred) {
+    if (layout.omit.has(relative)) continue
+    files[relative] = new Uint8Array(await fs.readFile(path.join(dir, relative)))
+  }
+
+  if (policy.readPackageJsonDependencies && hasRootPackageJson) {
+    const rewritten = await writeBackAssetDependencies(dir, layout.assetDependencies)
+    if (rewritten && files['package.json']) files['package.json'] = rewritten
+  }
+
   const zip = zipSync(files)
   if (zip.byteLength >= MAX_UPLOAD_ZIP_SIZE_BYTES) {
     throw new Error('Packed zip must be smaller than 1 GB')
@@ -170,9 +236,9 @@ async function packDirectory(dir: string, opts: PackAssetOptions): Promise<Packe
     sourcePath: dir,
     zip,
     npmDependencies,
-    assetDependencies,
+    assetDependencies: layout.assetDependencies,
     skillDependencies: opts.dependencies.skillDependencies,
-    omittedUnchangedInstalledFiles: omittedInstalled > 0,
+    omittedUnchangedInstalledFiles: layout.omit.size > 0,
     gitignoredFiles: walk.ignored,
   }
 }
@@ -220,8 +286,9 @@ function toPosix(p: string): string {
 const GITIGNORE_FILENAME = '.gitignore'
 
 // Directories that never belong in a published asset — VCS/tooling metadata, reinstallable
-// dependencies, and the market's own lock dir (`.drawcall/market-lock.json`). Excluded structurally
-// in every pack path, regardless of any `.gitignore`, so a re-uploaded asset never ships them.
+// dependencies, and the market's own state dir (`.drawcall`, holding the install mutex). Excluded
+// structurally in every pack path, regardless of any `.gitignore`, so a re-uploaded asset never
+// ships them.
 const ALWAYS_IGNORED_DIRS = new Set(['.git', 'node_modules', '.drawcall'])
 
 function hasAlwaysIgnoredSegment(posixPath: string): boolean {
@@ -350,17 +417,21 @@ export function parseSkillDeps(specs: string[]): Record<string, string> {
 }
 
 function mergeAssetDependencies(
-  fromPackageJson: Record<string, string>,
+  fromPackageJson: AssetDependencies,
   explicit: Record<string, string>,
-): Record<string, string> {
+): AssetDependencies {
   const merged = { ...fromPackageJson }
   for (const [name, range] of Object.entries(explicit)) {
-    if (name in merged && merged[name] !== range) {
+    const existing = merged[name]
+    if (existing !== undefined && assetDependencyRange(existing) !== range) {
       throw new Error(
-        `Conflicting asset dependency "${name}": package.json has ${merged[name]}, --asset has ${range}`,
+        `Conflicting asset dependency "${name}": package.json has ${assetDependencyRange(
+          existing,
+        )}, --asset has ${range}`,
       )
     }
-    merged[name] = range
+    // A matching package.json entry wins: it may carry aliases the flag form cannot express.
+    if (existing === undefined) merged[name] = range
   }
   return merged
 }
@@ -373,60 +444,236 @@ function inferPackPolicy(files: Record<string, Uint8Array>): PackPolicy {
   }
 }
 
-// Drop dependency files whose bytes still match the installed asset's canonical content, so a
-// template ships only its own (edited or new) files. Returns the surviving entries.
-async function withoutUnchangedInstalledFiles(
+// Drop each dependency file at its resolved location (one copy per file — duplicates ship as the
+// user's own content) so a template ships only its own (edited or new) files. Returns the
+// surviving entries plus the dependencies with freshly resolved aliases applied.
+async function withoutInstalledDependencyFiles(
   files: Record<string, Uint8Array>,
-  assetDependencies: Record<string, string>,
-  cwd: string,
+  assetDependencies: AssetDependencies,
   fetchFileManifest: FetchFileManifest | undefined,
-): Promise<Record<string, Uint8Array>> {
-  const hashesByPath = await installedDependencyHashes(cwd, assetDependencies, fetchFileManifest)
-  if (hashesByPath.size === 0) return files
+): Promise<{ kept: Record<string, Uint8Array>; assetDependencies: AssetDependencies }> {
+  const index = await dependencyFileIndex(assetDependencies, fetchFileManifest)
+  if (index.files.length === 0) return { kept: files, assetDependencies }
 
-  const kept: Record<string, Uint8Array> = {}
+  const hashesByPath = new Map<string, string>()
+  const entryByNormalized = new Map<string, string>()
   for (const [file, content] of Object.entries(files)) {
     const normalizedPath = normalizedZipPath(file)
-    const canonicalHash = normalizedPath ? hashesByPath.get(normalizedPath) : undefined
-    if (canonicalHash && canonicalHash === sha256(content)) continue
-    kept[file] = content
+    if (!normalizedPath || normalizedPath.endsWith('/')) continue
+    hashesByPath.set(normalizedPath, sha256(content))
+    entryByNormalized.set(normalizedPath, file)
   }
 
-  return kept
+  const layout = resolveDependencyLayout(assetDependencies, index, hashesByPath)
+  const omittedEntries = new Set(
+    [...layout.omit].flatMap((omitted) => entryByNormalized.get(omitted) ?? []),
+  )
+  const kept = Object.fromEntries(
+    Object.entries(files).filter(([file]) => !omittedEntries.has(file)),
+  )
+  return { kept, assetDependencies: layout.assetDependencies }
+}
+
+interface DependencyFile {
+  name: string
+  canonicalPath: string
+}
+
+interface DependencyFileEntry extends DependencyFile {
+  /** sha256 hex of the file's canonical content, from the server manifest. */
+  hash: string
+}
+
+interface DependencyFileIndex {
+  files: DependencyFileEntry[]
+  /** Dependencies whose manifest was fetched — only their aliases are re-derived. */
+  fetched: Set<string>
+}
+
+function emptyDependencyFileIndex(): DependencyFileIndex {
+  return { files: [], fetched: new Set() }
 }
 
 /**
- * The canonical content hash of every file belonging to a declared asset dependency, keyed by install
- * path. Read the installed version of each dependency from the lock, then fetch that version's hashes
- * from the server (`asset.fileManifest`). Returns an empty map when there's nothing to omit or no way
+ * The canonical content hash of every file belonging to a declared asset dependency, fetched from
+ * the server (`asset.fileManifest`). Returns an empty index when there's nothing to omit or no way
  * to fetch (offline / no client) — pack then keeps all files rather than guessing.
  */
-async function installedDependencyHashes(
-  root: string,
-  assetDependencies: Record<string, string>,
+async function dependencyFileIndex(
+  assetDependencies: AssetDependencies,
   fetchFileManifest: FetchFileManifest | undefined,
-): Promise<Map<string, string>> {
-  const hashesByPath = new Map<string, string>()
-  const dependencyNames = Object.keys(assetDependencies)
-  if (!fetchFileManifest || dependencyNames.length === 0) return hashesByPath
+): Promise<DependencyFileIndex> {
+  const index = emptyDependencyFileIndex()
+  const entries = Object.entries(assetDependencies)
+  if (!fetchFileManifest || entries.length === 0) return index
 
-  const lock = await readMarketLock(await findInstallRoot(root))
   const manifests = await Promise.all(
-    dependencyNames.map(async (name) => {
-      const installed = lock.assets[name]
-      if (!installed) return {}
+    entries.map(async ([name, value]) => {
       try {
-        return await fetchFileManifest(name, installed.version)
+        return { name, manifest: await fetchFileManifest(name, assetDependencyRange(value)) }
       } catch {
         // Can't reach the server for this dependency — keep its files rather than wrongly omitting them.
-        return {}
+        return null
       }
     }),
   )
-  for (const manifest of manifests) {
-    for (const [file, hash] of Object.entries(manifest)) hashesByPath.set(file, hash)
+  for (const result of manifests) {
+    // An empty manifest is "unavailable", not "zero files": a real version always has files, but
+    // the server returns {} for an unresolvable asset (deleted / private without access) or one
+    // too large for manifest computation. Treating it as fetched would wipe the dep's aliases.
+    if (!result || Object.keys(result.manifest).length === 0) continue
+    index.fetched.add(result.name)
+    for (const [file, hash] of Object.entries(result.manifest)) {
+      index.files.push({ name: result.name, canonicalPath: file, hash })
+    }
   }
-  return hashesByPath
+  return index
+}
+
+interface DependencyLayout {
+  /** Project paths holding a dependency file — exactly one per dependency file found. */
+  omit: Set<string>
+  /** The declared dependencies with re-resolved aliases (fetched deps only; others untouched). */
+  assetDependencies: AssetDependencies
+  /** Dependency files whose canonical bytes were found nowhere (locally modified or deleted). */
+  missing: DependencyFile[]
+}
+
+/**
+ * Resolve where each dependency file lives in the project, by content hash. Exactly one project
+ * copy is claimed per dependency file: the already-recorded alias target if its bytes still match
+ * (stable across runs), else the canonical path, else the lexicographically first matching copy —
+ * that copy is omitted from packs and recorded as the alias; further identical copies are the
+ * user's own content. Stale aliases drop: a renamed file that was since modified ships as user
+ * content and reinstall restores the canonical path.
+ */
+function resolveDependencyLayout(
+  declared: AssetDependencies,
+  index: DependencyFileIndex,
+  hashesByPath: Map<string, string>,
+): DependencyLayout {
+  const pathsByHash = new Map<string, string[]>()
+  for (const [filePath, hash] of hashesByPath) {
+    pathsByHash.set(hash, [...(pathsByHash.get(hash) ?? []), filePath])
+  }
+  for (const paths of pathsByHash.values()) paths.sort()
+
+  const omit = new Set<string>()
+  const missing: DependencyFile[] = []
+  const aliases: Record<string, Record<string, string>> = {}
+  for (const file of index.files) {
+    const declaredValue = declared[file.name]
+    const declaredAlias =
+      declaredValue === undefined
+        ? undefined
+        : assetDependencyAlias(declaredValue)[file.canonicalPath]
+    const candidates = (pathsByHash.get(file.hash) ?? []).filter((p) => !omit.has(p))
+    if (candidates.length === 0) {
+      missing.push({ name: file.name, canonicalPath: file.canonicalPath })
+      continue
+    }
+
+    const target =
+      declaredAlias !== undefined && candidates.includes(declaredAlias)
+        ? declaredAlias
+        : candidates.includes(file.canonicalPath)
+          ? file.canonicalPath
+          : candidates[0]
+    omit.add(target)
+    if (target !== file.canonicalPath) {
+      aliases[file.name] = { ...(aliases[file.name] ?? {}), [file.canonicalPath]: target }
+    }
+  }
+
+  const assetDependencies: AssetDependencies = {}
+  for (const [name, value] of Object.entries(declared)) {
+    assetDependencies[name] = index.fetched.has(name)
+      ? assetDependencyValue(assetDependencyRange(value), aliases[name] ?? {})
+      : value
+  }
+  return { omit, assetDependencies, missing }
+}
+
+export interface AssetDependencySync {
+  projectRoot: string
+  /** Whether package.json was rewritten. */
+  changed: boolean
+  assetDependencies: AssetDependencies
+  /** Dependency files whose canonical bytes were found nowhere (locally modified or deleted). */
+  missing: Array<{ name: string; path: string }>
+  /** Dependencies left untouched because their manifest could not be fetched. */
+  skipped: string[]
+}
+
+/**
+ * Update the aliases in package.json `assetDependencies` to match where each dependency's files
+ * currently live — the standalone form of what pack does before omitting (`market sync`). Renamed
+ * files gain an alias, files back at their canonical path lose theirs, and dependencies whose
+ * manifest cannot be fetched are reported as skipped rather than blindly rewritten.
+ */
+export async function syncAssetDependencies(
+  cwd: string,
+  fetchFileManifest: FetchFileManifest,
+): Promise<AssetDependencySync> {
+  const projectRoot = await findInstallRoot(cwd)
+  const pkgPath = path.join(projectRoot, 'package.json')
+  if (!(await maybeStat(pkgPath))?.isFile()) {
+    throw new Error(`No package.json found at ${projectRoot}. Run sync inside a project.`)
+  }
+  const declared = packageJsonAssetDependencies(await fs.readFile(pkgPath, 'utf-8'), pkgPath)
+  const names = Object.keys(declared)
+  if (names.length === 0) {
+    return { projectRoot, changed: false, assetDependencies: {}, missing: [], skipped: [] }
+  }
+
+  const index = await dependencyFileIndex(declared, fetchFileManifest)
+  const walk = await walkWithGitignore(projectRoot)
+  const hashesByPath = new Map<string, string>()
+  for (const relative of walk.kept) {
+    hashesByPath.set(
+      relative,
+      sha256(new Uint8Array(await fs.readFile(path.join(projectRoot, relative)))),
+    )
+  }
+
+  const layout = resolveDependencyLayout(declared, index, hashesByPath)
+  const rewritten = await writeBackAssetDependencies(projectRoot, layout.assetDependencies)
+  return {
+    projectRoot,
+    changed: rewritten !== null,
+    assetDependencies: layout.assetDependencies,
+    missing: layout.missing.map((file) => ({ name: file.name, path: file.canonicalPath })),
+    skipped: names.filter((name) => !index.fetched.has(name)),
+  }
+}
+
+/**
+ * Persist detected aliases into the project's package.json (only for dependencies it already
+ * declares — flag-only deps stay out of the file). Returns the serialized bytes when something
+ * changed so the packed zip can carry the same content.
+ */
+async function writeBackAssetDependencies(
+  dir: string,
+  assetDependencies: AssetDependencies,
+): Promise<Uint8Array | null> {
+  const pkgPath = path.join(dir, 'package.json')
+  const pkg = parsePackageJson(await fs.readFile(pkgPath, 'utf-8'), pkgPath)
+  const declared = pkg.assetDependencies
+  if (!declared) return null
+
+  let changed = false
+  for (const name of Object.keys(declared)) {
+    const next = assetDependencies[name]
+    if (next === undefined) continue
+    if (JSON.stringify(declared[name]) === JSON.stringify(next)) continue
+    declared[name] = next
+    changed = true
+  }
+  if (!changed) return null
+
+  const serialized = JSON.stringify(pkg, null, 2) + '\n'
+  await fs.writeFile(pkgPath, serialized)
+  return new TextEncoder().encode(serialized)
 }
 
 function normalizedZipPath(file: string): string | null {

package/src/package-json.ts

@@ -1,30 +1,33 @@
 import { z } from 'zod'
+import { assetDependencyValueSchema, type AssetDependencies } from './schemas.js'
 
 export interface PackageJson {
   name?: string
   private?: boolean
   dependencies?: Record<string, string>
-  assetDependencies?: Record<string, string>
+  assetDependencies?: AssetDependencies
   [key: string]: unknown
 }
 
 const stringRecordSchema = z.record(z.string(), z.string())
 
+const assetDependenciesRecordSchema = z.record(z.string(), assetDependencyValueSchema)
+
 export function packageJsonAssetDependenciesFromFiles(
   files: Record<string, Uint8Array>,
-): Record<string, string> {
+): AssetDependencies {
   const bytes = files['package.json']
   if (!bytes) return {}
 
   return packageJsonAssetDependencies(new TextDecoder().decode(bytes), 'package.json')
 }
 
-export function packageJsonAssetDependencies(json: string, source: string): Record<string, string> {
+export function packageJsonAssetDependencies(json: string, source: string): AssetDependencies {
   const parsed = parsePackageJson(json, source)
   const dependencies = parsed.assetDependencies
   if (dependencies === undefined) return {}
 
-  return stringRecordSchema.parse(dependencies)
+  return assetDependenciesRecordSchema.parse(dependencies)
 }
 
 // A template ships a full app, so its package.json `dependencies` ARE its npm dependencies: capture

package/src/resolve.ts

@@ -12,7 +12,12 @@
 import * as semver from 'semver'
 import type { MarketClient } from './client.js'
 import type { AssetExactResult } from './contract.js'
-import { semverSchema } from './schemas.js'
+import {
+  assetDependencyAlias,
+  assetDependencyRange,
+  semverSchema,
+  type AssetDependencies,
+} from './schemas.js'
 
 export interface ResolvedAsset {
   name: string
@@ -20,7 +25,7 @@ export interface ResolvedAsset {
   version: string
   description: string | null
   npmDependencies: Record<string, string>
-  assetDependencies: Record<string, string>
+  assetDependencies: AssetDependencies
   skillDependencies: Record<string, string>
 }
 
@@ -28,6 +33,12 @@ export interface ResolveResult {
   assets: ResolvedAsset[]
   npmDependencies: Record<string, string>
   skillDependencies: Record<string, string>
+  /**
+   * File aliases declared by dependents, keyed by dependency name: canonical install path → the
+   * path the dependent's project keeps the file at. Install writes files through this map (a
+   * template whose author renamed a dependency's files reinstalls them at the renamed locations).
+   */
+  assetAliases?: Record<string, Record<string, string>>
 }
 
 interface AssetRequest {
@@ -96,6 +107,7 @@ export async function resolve(
       assets,
       npmDependencies: mergeNpmDependencies(assets),
       skillDependencies: mergeSkillDependencies(assets),
+      assetAliases: mergeAssetAliases(assets),
     }
   }
 
@@ -141,7 +153,7 @@ async function resolvePass(
     const selectedVersion = exactVersion
       ? exactMetadataVersion(meta, assetName, exactVersion)
       : latestMetadataVersion(meta)
-    const assetDependencies = parseDependencies(meta.assetDependencies, assetName, 'asset')
+    const assetDependencies = parseAssetDependencies(meta.assetDependencies, assetName)
     resolved.set(assetName, {
       name: assetName,
       type: meta.type,
@@ -152,7 +164,8 @@ async function resolvePass(
       skillDependencies: parseDependencies(meta.skillDependencies, assetName, 'skill'),
     })
 
-    for (const [dependencyName, dependencyRange] of Object.entries(assetDependencies)) {
+    for (const [dependencyName, dependencyValue] of Object.entries(assetDependencies)) {
+      const dependencyRange = assetDependencyRange(dependencyValue)
       addConstraint(constraints, dependencyName, dependencyRange, `${assetName}@${selectedVersion}`)
       pending.push(dependencyName)
     }
@@ -203,6 +216,36 @@ function mergeSkillDependencies(assets: ResolvedAsset[]): Record<string, string>
   return merged
 }
 
+/**
+ * Merge file aliases from every resolved asset, keyed by the dependency they apply to. Two
+ * dependents rarely alias the same file; when they do, the first resolved asset wins — a
+ * deterministic choice that keeps installs reproducible.
+ */
+function mergeAssetAliases(assets: ResolvedAsset[]): Record<string, Record<string, string>> {
+  const merged: Record<string, Record<string, string>> = {}
+  for (const asset of assets) {
+    for (const [dependencyName, value] of Object.entries(asset.assetDependencies)) {
+      const alias = assetDependencyAlias(value)
+      if (Object.keys(alias).length === 0) continue
+      merged[dependencyName] = { ...alias, ...(merged[dependencyName] ?? {}) }
+    }
+  }
+  return merged
+}
+
+/** Like parseDependencies, but asset dependency values may also be `{ version, alias }` objects. */
+function parseAssetDependencies(value: string, assetName: string): AssetDependencies {
+  try {
+    const parsed = JSON.parse(value || '{}') as unknown
+    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+      return parsed as AssetDependencies
+    }
+  } catch {
+    // fall through to a clear error below
+  }
+  throw new ResolutionError(`Asset "${assetName}" has malformed asset dependency metadata.`)
+}
+
 function parseDependencies(
   value: string,
   assetName: string,