@drawcall/market 0.1.35 → 0.1.37

package/src/install.ts

@@ -16,18 +16,20 @@ import * as path from 'path'
 import { unzipSync } from 'fflate'
 import { detectPackageManager, installDependencies } from 'nypm'
 import type { MarketClient } from './client.js'
+import type { AssetInstallMetadata } from './contract.js'
+import { readMarketLock, sha256, writeMarketLock } from './market-lock.js'
+import { parsePackageJson, type PackageJson } from './package-json.js'
 import type { ResolveResult } from './resolve.js'
 
-interface PackageJson {
-  name?: string
-  private?: boolean
-  dependencies?: Record<string, string>
-  [key: string]: unknown
-}
-
 export interface InstallOptions {
   /** Directory to start project root discovery from (default: cwd) */
   cwd?: string
+  /** Overwrite existing files that differ from the asset zip. */
+  force?: boolean
+  /** Top-level assets requested by the user, used for package.json assetDependencies. */
+  rootRequests?: InstallRootRequest[]
+  /** Asset-type install policy from the Market API. */
+  installMetadata?: Record<string, AssetInstallMetadata>
   /** Log progress */
   onProgress?: (message: string) => void
   /**
@@ -38,6 +40,13 @@ export interface InstallOptions {
   runSkillAdd?: (source: string, cwd: string) => Promise<void>
 }
 
+export interface InstallRootRequest {
+  name: string
+  range: string
+  saveRange: string
+  save: boolean
+}
+
 export interface InstalledAsset {
   name: string
   type: string
@@ -51,6 +60,17 @@ export interface InstallResult {
   npmDependencies: Record<string, string>
   /** Installed skills, keyed by label, with the source passed to `skills add`. */
   skillDependencies: Record<string, string>
+  warnings: string[]
+}
+
+interface DownloadedAsset extends InstalledAsset {
+  fileHashes: Record<string, { sha256: string }>
+}
+
+interface DownloadResult {
+  assets: DownloadedAsset[]
+  wrotePackageJson: boolean
+  warnings: string[]
 }
 
 export async function install(
@@ -60,11 +80,21 @@ export async function install(
 ): Promise<InstallResult> {
   const log = opts.onProgress ?? (() => {})
   const installRoot = await findInstallRoot(opts.cwd ?? process.cwd())
+  const metadata = opts.installMetadata ?? {}
 
-  const [assets] = await Promise.all([
-    downloadAssets(client, resolution, installRoot, log),
-    installNpmDeps(resolution, installRoot, log),
-  ])
+  const download = await downloadAssets(client, resolution, installRoot, {
+    force: opts.force ?? false,
+    log,
+  })
+  await writeInstalledAssetLock(installRoot, download.assets)
+  const packageJsonUpdate = await updatePackageJson(resolution, installRoot, {
+    rootRequests: opts.rootRequests ?? [],
+    installMetadata: metadata,
+    packageManagerNeeded: download.wrotePackageJson,
+  })
+  if (packageJsonUpdate.packageManagerNeeded) {
+    await runPackageManagerInstall(installRoot, log)
+  }
 
   // Skills are installed after asset files land on disk: a skill source may be
   // a local path pointing at a skill directory shipped inside an installed
@@ -77,9 +107,16 @@ export async function install(
   )
 
   return {
-    assets,
+    assets: download.assets.map((asset) => ({
+      name: asset.name,
+      type: asset.type,
+      version: asset.version,
+      description: asset.description,
+      files: asset.files,
+    })),
     npmDependencies: resolution.npmDependencies,
     skillDependencies,
+    warnings: download.warnings,
   }
 }
 
@@ -100,16 +137,22 @@ async function downloadAssets(
   client: MarketClient,
   resolution: ResolveResult,
   projectRoot: string,
-  log: (msg: string) => void,
-): Promise<InstalledAsset[]> {
-  const installedAssets: InstalledAsset[] = []
+  opts: {
+    force: boolean
+    log: (msg: string) => void
+  },
+): Promise<DownloadResult> {
+  const installedAssets: DownloadedAsset[] = []
+  const warnings: string[] = []
+  let wrotePackageJson = false
 
   for (const asset of resolution.assets) {
-    log(`Downloading ${asset.name}@${asset.version}...`)
+    opts.log(`Downloading ${asset.name}@${asset.version}...`)
 
     const zip = await client.asset.downloadZip({ name: asset.name, version: asset.version })
     const files = unzipSync(new Uint8Array(await zip.arrayBuffer()))
     const installedFiles: string[] = []
+    const fileHashes: Record<string, { sha256: string }> = {}
 
     for (const [relativePath, content] of Object.entries(files) as [string, Uint8Array][]) {
       const zipPath = relativePath.replace(/\\/g, '/')
@@ -124,16 +167,31 @@ async function downloadAssets(
       const normalizedPath = path.posix.normalize(zipPath)
       if (
         normalizedPath === '.' ||
-        normalizedPath === 'README.md' ||
+        (normalizedPath === 'README.md' && asset.type !== 'template') ||
         normalizedPath.endsWith('/')
       ) {
         continue
       }
 
       const filePath = path.join(projectRoot, normalizedPath)
-      await fs.mkdir(path.dirname(filePath), { recursive: true })
-      await fs.writeFile(filePath, content)
+      const existing = await maybeReadFile(filePath)
+      if (existing && !bytesEqual(existing, content) && !opts.force) {
+        warnings.push(
+          `Skipped ${normalizedPath} from ${asset.name}@${asset.version}; file already exists. Re-run with --force to overwrite.`,
+        )
+        continue
+      }
+
+      if (!existing || !bytesEqual(existing, content)) {
+        await fs.mkdir(path.dirname(filePath), { recursive: true })
+        await fs.writeFile(filePath, content)
+        if (normalizedPath === 'package.json') {
+          wrotePackageJson = true
+        }
+      }
+
       installedFiles.push(normalizedPath)
+      fileHashes[normalizedPath] = { sha256: sha256(content) }
     }
 
     installedAssets.push({
@@ -142,12 +200,13 @@ async function downloadAssets(
       version: asset.version,
       description: asset.description,
       files: installedFiles,
+      fileHashes,
     })
 
-    log(`Downloaded ${installedFiles.length} files.`)
+    opts.log(`Downloaded ${installedFiles.length} files.`)
   }
 
-  return installedAssets
+  return { assets: installedAssets, wrotePackageJson, warnings }
 }
 
 async function isFile(file: string): Promise<boolean> {
@@ -158,26 +217,60 @@ async function isFile(file: string): Promise<boolean> {
   }
 }
 
-async function installNpmDeps(
+async function maybeReadFile(file: string): Promise<Uint8Array | null> {
+  try {
+    return await fs.readFile(file)
+  } catch (error) {
+    if (isMissingFile(error)) return null
+    throw error
+  }
+}
+
+function isMissingFile(error: unknown): boolean {
+  return error instanceof Error && 'code' in error && error.code === 'ENOENT'
+}
+
+async function updatePackageJson(
   resolution: ResolveResult,
   projectRoot: string,
-  log: (msg: string) => void,
-): Promise<void> {
-  const deps = resolution.npmDependencies
-  if (Object.keys(deps).length === 0) return
-
+  opts: {
+    rootRequests: InstallRootRequest[]
+    installMetadata: Record<string, AssetInstallMetadata>
+    packageManagerNeeded: boolean
+  },
+): Promise<{ packageManagerNeeded: boolean }> {
   const pkgPath = path.join(projectRoot, 'package.json')
-  // Only synthesize a package.json when none exists. A malformed existing file
-  // is a real error that must surface — never silently overwrite it.
-  const pkg: PackageJson = (await isFile(pkgPath))
-    ? (JSON.parse(await fs.readFile(pkgPath, 'utf-8')) as PackageJson)
-    : { name: 'my-project', private: true, dependencies: {} }
+  const pkg = (await isFile(pkgPath))
+    ? parsePackageJson(await fs.readFile(pkgPath, 'utf-8'), pkgPath)
+    : defaultPackageJson()
+
+  let changed = false
+  let packageManagerNeeded = opts.packageManagerNeeded
 
-  pkg.dependencies = { ...pkg.dependencies, ...deps }
-  await fs.writeFile(pkgPath, JSON.stringify(pkg, null, 2) + '\n')
+  const npmChanged = mergeRecord(pkg, 'dependencies', resolution.npmDependencies)
+  if (npmChanged) {
+    changed = true
+    packageManagerNeeded = true
+  }
 
-  log(`Installing npm dependencies: ${Object.keys(deps).join(', ')}`)
+  const assetDependencies = assetDependenciesToSave(
+    resolution,
+    opts.rootRequests,
+    opts.installMetadata,
+  )
+  if (mergeRecord(pkg, 'assetDependencies', assetDependencies)) {
+    changed = true
+  }
 
+  if (changed) {
+    await fs.writeFile(pkgPath, JSON.stringify(pkg, null, 2) + '\n')
+  }
+
+  return { packageManagerNeeded }
+}
+
+async function runPackageManagerInstall(projectRoot: string, log: (msg: string) => void) {
+  log('Installing npm dependencies...')
   const pm = await detectPackageManager(projectRoot)
   const pmName = pm?.name ?? 'npm'
 
@@ -186,6 +279,75 @@ async function installNpmDeps(
   log('npm dependencies installed.')
 }
 
+async function writeInstalledAssetLock(
+  projectRoot: string,
+  assets: DownloadedAsset[],
+): Promise<void> {
+  const lock = await readMarketLock(projectRoot)
+  for (const asset of assets) {
+    lock.assets[asset.name] = {
+      version: asset.version,
+      type: asset.type,
+      files: asset.fileHashes,
+    }
+  }
+  await writeMarketLock(projectRoot, lock)
+}
+
+function defaultPackageJson(): PackageJson {
+  return { name: 'my-project', private: true, dependencies: {} }
+}
+
+function mergeRecord(
+  pkg: PackageJson,
+  field: 'dependencies' | 'assetDependencies',
+  values: Record<string, string>,
+): boolean {
+  const entries = Object.entries(values)
+  if (entries.length === 0) return false
+
+  const current = pkg[field] ?? {}
+  let changed = false
+
+  for (const [name, range] of entries) {
+    if (current[name] === range) continue
+    current[name] = range
+    changed = true
+  }
+
+  pkg[field] = current
+  return changed
+}
+
+function assetDependenciesToSave(
+  resolution: ResolveResult,
+  rootRequests: InstallRootRequest[],
+  metadata: Record<string, AssetInstallMetadata>,
+): Record<string, string> {
+  const resolvedByName = new Map(resolution.assets.map((asset) => [asset.name, asset]))
+  const out: Record<string, string> = {}
+
+  for (const request of rootRequests) {
+    if (!request.save) continue
+
+    const asset = resolvedByName.get(request.name)
+    if (!asset) continue
+
+    if ((metadata[asset.type]?.saveOnInstall ?? true) === false) continue
+    out[asset.name] = request.saveRange
+  }
+
+  return out
+}
+
+function bytesEqual(a: Uint8Array, b: Uint8Array): boolean {
+  if (a.length !== b.length) return false
+  for (let i = 0; i < a.length; i += 1) {
+    if (a[i] !== b[i]) return false
+  }
+  return true
+}
+
 async function installSkills(
   resolution: ResolveResult,
   projectRoot: string,

package/src/market-lock.ts

@@ -0,0 +1,65 @@
+import { createHash } from 'crypto'
+import * as fs from 'fs/promises'
+import * as path from 'path'
+import { z } from 'zod'
+
+export const MARKET_LOCK_PATH = '.drawcall/market-lock.json'
+
+export interface MarketLockAsset {
+  version: string
+  type: string
+  files: Record<string, { sha256: string }>
+}
+
+export interface MarketLock {
+  version: 1
+  assets: Record<string, MarketLockAsset>
+}
+
+const marketLockSchema = z.object({
+  version: z.literal(1),
+  assets: z.record(
+    z.string(),
+    z.object({
+      version: z.string(),
+      type: z.string(),
+      files: z.record(
+        z.string(),
+        z.object({
+          sha256: z.string(),
+        }),
+      ),
+    }),
+  ),
+})
+
+export async function readMarketLock(projectRoot: string): Promise<MarketLock> {
+  const lockPath = path.join(projectRoot, MARKET_LOCK_PATH)
+  try {
+    return marketLockSchema.parse(JSON.parse(await fs.readFile(lockPath, 'utf-8')))
+  } catch (error) {
+    if (isMissingFile(error)) return emptyMarketLock()
+    throw error
+  }
+}
+
+export async function writeMarketLock(projectRoot: string, lock: MarketLock): Promise<void> {
+  const lockPath = path.join(projectRoot, MARKET_LOCK_PATH)
+  await fs.mkdir(path.dirname(lockPath), { recursive: true })
+  await fs.writeFile(lockPath, JSON.stringify(lock, null, 2) + '\n')
+}
+
+export function emptyMarketLock(): MarketLock {
+  return {
+    version: 1,
+    assets: {},
+  }
+}
+
+export function sha256(bytes: Uint8Array): string {
+  return createHash('sha256').update(bytes).digest('hex')
+}
+
+function isMissingFile(error: unknown): boolean {
+  return error instanceof Error && 'code' in error && error.code === 'ENOENT'
+}

package/src/output.ts

@@ -1,4 +1,5 @@
-import type { AssetSearchResult } from './contract.js'
+import type { AssetInstallMetadata, AssetSearchResult } from './contract.js'
+import type { ListInstalledAssetsResult } from './commands/list.js'
 import type { InstallResult } from './install.js'
 
 export function assetVersionRef(name: string, version?: string): string {
@@ -33,22 +34,19 @@ export function assetSearchResultLine(item: AssetSearchResult): string {
 
 export function installResult(
   result: InstallResult,
-  postInstallMessages: Record<string, string> = {},
+  installMetadata: Record<string, AssetInstallMetadata> = {},
 ): string {
   const npmDependencies = Object.entries(result.npmDependencies)
 
   const lines = ['Installed:']
 
   for (const asset of result.assets) {
-    const files = unique(asset.files)
-    lines.push(`- ${assetVersionRef(asset.name, asset.version)} (${asset.type})`)
+    lines.push(assetLine(asset))
     if (asset.description) {
       lines.push(...block('  description: ', asset.description))
     }
-    if (files.length > 0) {
-      lines.push('  files:', ...indent(fileTree(files), '    '))
-    }
-    const message = postInstallMessages[asset.type]
+    lines.push(...assetFileLines(asset.files))
+    const message = installMetadata[asset.type]?.installMessage
     if (message) {
       lines.push(...block('  note: ', message))
     }
@@ -71,9 +69,39 @@ export function installResult(
     )
   }
 
+  if (result.warnings.length > 0) {
+    lines.push('Warnings:', ...result.warnings.map((warning) => `- ${warning}`))
+  }
+
+  return lines.join('\n')
+}
+
+export function listResult(result: ListInstalledAssetsResult): string {
+  if (result.assets.length === 0) {
+    return 'No installed assets found.'
+  }
+
+  const lines = [`Installed assets: ${result.assets.length}`]
+  for (const asset of result.assets) {
+    lines.push(assetLine(asset), ...assetFileLines(asset.files))
+  }
+
   return lines.join('\n')
 }
 
+function assetLine(asset: { name: string; version: string; type: string }): string {
+  return `- ${assetVersionRef(asset.name, asset.version)} (${asset.type})`
+}
+
+function assetFileLines(paths: string[]): string[] {
+  const lines: string[] = []
+  const files = unique(paths)
+  if (files.length > 0) {
+    lines.push('  files:', ...indent(fileTree(files), '    '))
+  }
+  return lines
+}
+
 function block(label: string, message: string, width = 68): string[] {
   const hang = ' '.repeat(label.length)
   const words = normalizeInline(message).split(' ').filter(Boolean)

package/src/package-json.ts

@@ -0,0 +1,37 @@
+import { z } from 'zod'
+
+export interface PackageJson {
+  name?: string
+  private?: boolean
+  dependencies?: Record<string, string>
+  assetDependencies?: Record<string, string>
+  [key: string]: unknown
+}
+
+const stringRecordSchema = z.record(z.string(), z.string())
+
+export function packageJsonAssetDependenciesFromFiles(
+  files: Record<string, Uint8Array>,
+): Record<string, string> {
+  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> {
+  const parsed = parsePackageJson(json, source)
+  const dependencies = parsed.assetDependencies
+  if (dependencies === undefined) return {}
+
+  return stringRecordSchema.parse(dependencies)
+}
+
+export function parsePackageJson(json: string, source: string): PackageJson {
+  const parsed = JSON.parse(json) as unknown
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error(`${source} must contain a JSON object`)
+  }
+
+  return parsed as PackageJson
+}

package/src/skill.ts

@@ -12,20 +12,22 @@ Use the \`market\` CLI. Keep commands short and read the summary lines.
 \`\`\`sh
 market search "wooden chair" --type model --limit 3
 market install wooden-chair --cwd "$PWD"
+market list --cwd "$PWD"
 market preview wooden-chair --out /tmp/wooden-chair.png
 \`\`\`
 
 ## Workflow
 
-1. Search first unless the user already gave an exact asset name. \`search\` requires \`--type\`; use \`model\` unless the user names another supported type: \`humanoid-model\`, \`texture\`, \`humanoid-animation\`, \`template\`, \`sound-effect\`, \`background-music\`, \`environment\`, or \`flipbook\`.
-2. Use \`--limit 1\` for lookup, \`--limit 3\` for choice. Search caps at 5 and prints full descriptions.
-3. \`install\` takes one or more exact asset names (optionally \`name@range\`); it does not search or generate. Find names with \`search\` first. No \`--type\` is needed — asset names are unique.
-4. \`preview <name>\` saves the preview image; no \`--type\` is needed. Not every type has previews (e.g. \`humanoid-animation\`, \`template\`, \`sound-effect\`, \`background-music\`); the CLI reports when one is unavailable.
-5. Use \`--unapproved\` only when the user asks for unapproved/private/admin assets. Do not install unapproved assets without explicit acceptance.
-6. \`generate --type <type> "<prompt>"\` creates a new asset; it requires login and a type that supports generation. No asset type currently supports generation.
-7. Upload only when publishing is requested: \`market upload <name> <zip> "<description>" --type <type>\`. Declare dependencies with repeatable flags: \`--npm name@range\`, \`--asset name@range\`, \`--skill label=source\`. A skill source is a \`skills add\` argument: a whole repo (\`owner/repo\` or a git URL), a single skill via the full URL form \`https://github.com/owner/repo/tree/<branch>/<subpath>\` (the \`tree/<branch>/<subpath>\` shorthand needs the full URL, not \`owner/repo\`), or a local path to a skill directory inside the zip. Example: \`market upload my-scene scene.zip "A scene" --type model --npm three@^0.178.0 --skill web-design=https://github.com/vercel-labs/agent-skills/tree/main/skills/web-design-guidelines\`.
-8. Installed \`environment\` assets contain \`public/environment/<name>.hdr\` for Three.js IBL lighting and \`public/environment/<name>-background.webp\` for the visible equirectangular background. Use \`market preview\` to fetch the preview image separately.
-9. Installed \`flipbook\` assets contain \`public/flipbook/<name>.ktx2\`. Render them with \`@drawcall/flipbook\`'s \`Flipbook\` class and Three.js \`KTX2Loader\` for Basis-compressed files; \`market preview\` fetches the middle frame from the flipbook.
+1. In an existing repo, run \`list --cwd "$PWD"\` first to see installed local assets from \`.drawcall/market-lock.json\`. Use the listed names with \`preview <name>\` when you want preview images.
+2. Search first unless the user already gave an exact asset name. \`search\` requires \`--type\`; use \`model\` unless the user names another supported type: \`humanoid-model\`, \`texture\`, \`humanoid-animation\`, \`template\`, \`sound-effect\`, \`background-music\`, \`environment\`, or \`flipbook\`.
+3. Use \`--limit 1\` for lookup, \`--limit 3\` for choice. Search caps at 5 and prints full descriptions.
+4. \`install\` takes zero or more exact asset names (optionally \`name@range\`). With names, it installs those assets; with no names, it installs \`assetDependencies\` from the nearest \`package.json\`. It does not search or generate. Find names with \`search\` first. No \`--type\` is needed — asset names are unique. Use \`--force\` only when the user agrees to overwrite changed local files.
+5. \`preview <name>\` saves the preview image; no \`--type\` is needed. Not every type has previews (e.g. \`humanoid-animation\`, \`template\`, \`sound-effect\`, \`background-music\`); the CLI reports when one is unavailable.
+6. Use \`--unapproved\` only when the user asks for unapproved/private/admin assets. Do not install unapproved assets without explicit acceptance.
+7. \`generate --type <type> "<prompt>"\` creates a new asset; it requires login and a type that supports generation. No asset type currently supports generation.
+8. Upload only when publishing is requested: \`market upload <name> <zip> "<description>" --type <type>\`. Declare dependencies with repeatable flags: \`--npm name@range\`, \`--asset name@range\`, \`--skill label=source\`. Template uploads also read root \`package.json.assetDependencies\`; \`--asset\` flags are additive and must not conflict. Template upload omits installed dependency files whose hashes still match \`.drawcall/market-lock.json\`, so edited local files stay in the template. A skill source is a \`skills add\` argument: a whole repo (\`owner/repo\` or a git URL), a single skill via the full URL form \`https://github.com/owner/repo/tree/<branch>/<subpath>\` (the \`tree/<branch>/<subpath>\` shorthand needs the full URL, not \`owner/repo\`), or a local path to a skill directory inside the zip. Example: \`market upload my-scene scene.zip "A scene" --type model --npm three@^0.178.0 --skill web-design=https://github.com/vercel-labs/agent-skills/tree/main/skills/web-design-guidelines\`.
+9. Installed \`environment\` assets contain \`public/environment/<name>.hdr\` for Three.js IBL lighting and \`public/environment/<name>-background.webp\` for the visible equirectangular background. Use \`market preview\` to fetch the preview image separately.
+10. Installed \`flipbook\` assets contain \`public/flipbook/<name>.ktx2\`. Render them with \`@drawcall/flipbook\`'s \`Flipbook\` class and Three.js \`KTX2Loader\` for Basis-compressed files; \`market preview\` fetches the middle frame from the flipbook.
 
 ## Humanoid animations
 
@@ -48,10 +50,19 @@ Installed:
     └─ wooden-chair.glb
 - three@^0.178.0 (npm)
 - web-design ← https://github.com/vercel-labs/agent-skills/tree/main/skills/web-design-guidelines (skill)
+Installed assets: 1
+- wooden-chair@1.0.0 (model)
+  files:
+    public/model
+    └─ wooden-chair.glb
 Saved preview for wooden-chair@1.0.0: /tmp/wooden-chair.png
 \`\`\`
 
 Assets may also declare \`skill\` dependencies, installed for you via the \`skills\` CLI (\`skills add\`) during \`install\`. Sources are either a GitHub/git ref or a local path to a skill directory shipped inside the asset. This requires \`npx\` to be available.
 
+Installed non-template assets are saved to \`package.json.assetDependencies\`; templates are scaffolds and are not saved as project asset dependencies. Exact installed versions and file hashes are recorded in \`.drawcall/market-lock.json\`.
+
+\`list\` is offline: it reads \`.drawcall/market-lock.json\` from the nearest package root and prints exact installed names, versions, types, and installed file paths.
+
 If search returns no results, try one broader noun phrase. If a command returns \`Error: Not logged in...\`, ask before running \`market login\`.
 `

package/tests/install-command.test.ts

@@ -31,7 +31,29 @@ test('resolveArg keeps explicit versioned refs exact when the asset exists', asy
 
   const request = await resolveArg(client, 'fresh-sky@1.2.3', false)
 
-  assert.deepEqual(request, { name: 'fresh-sky', range: '1.2.3' })
+  assert.deepEqual(request, {
+    name: 'fresh-sky',
+    range: '1.2.3',
+    saveRange: '1.2.3',
+    save: true,
+  })
+})
+
+test('resolveArg saves an implicit range from the selected latest version', async () => {
+  const client = {
+    asset: {
+      exact: async () => ({ name: 'fresh-sky', latestVersion: '1.2.3', approved: true }),
+    },
+  } as never
+
+  const request = await resolveArg(client, 'fresh-sky', false)
+
+  assert.deepEqual(request, {
+    name: 'fresh-sky',
+    range: '*',
+    saveRange: '^1.2.3',
+    save: true,
+  })
 })
 
 test('resolveArg errors when the asset does not exist instead of deferring', async () => {