tabwright 1.0.0

package/src/capability-package.ts

@@ -0,0 +1,555 @@
+import crypto from 'node:crypto'
+import fs from 'node:fs'
+import path from 'node:path'
+import { Readable } from 'node:stream'
+import { pipeline } from 'node:stream/promises'
+import zlib from 'node:zlib'
+import * as tar from 'tar-stream'
+import { z } from 'zod'
+import {
+  getCapabilityDir,
+  parseCapabilityManifest,
+  readCapability,
+  requireCapability,
+  type CapabilityLocation,
+  type CapabilityManifest,
+  type CapabilityRecord,
+} from './capability-registry.js'
+import { removeCapabilityAuthFiles } from './capability-auth-state.js'
+
+const PACKAGE_METADATA_PATH = 'tabwright-package.json'
+const LEGACY_PACKAGE_METADATA_PATH = 'playwriter-package.json'
+const PACKAGE_ROOT = 'package'
+const MAX_ARCHIVE_BYTES = 10 * 1024 * 1024
+const MAX_EXTRACTED_BYTES = 20 * 1024 * 1024
+const MAX_PACKAGE_FILES = 100
+
+const CapabilityPackageMetadataSchema = z.object({
+  schemaVersion: z.literal(1),
+  capabilityId: z.string(),
+  packedAt: z.string(),
+  files: z.array(
+    z.object({
+      path: z.string(),
+      sha256: z.string(),
+    }),
+  ),
+})
+
+interface CapabilityPackageFile {
+  path: string
+  content: Buffer
+}
+
+export interface PackedCapability {
+  capabilityId: string
+  path: string
+  files: string[]
+  integrity: string
+}
+
+export interface InstalledCapabilityPackage {
+  source: string
+  capability: CapabilityRecord
+  files: string[]
+  integrity: string
+  agentSkillAvailable: boolean
+}
+
+export async function packCapability(options: {
+  id: string
+  cwd?: string
+  output?: string
+  overwrite?: boolean
+}): Promise<PackedCapability> {
+  const capability = requireCapability({ id: options.id, cwd: options.cwd })
+  const files = readCapabilityPackageFiles({
+    sourceDir: capability.dir,
+    manifest: {
+      ...capability.manifest,
+      status: 'draft',
+    },
+  })
+  const metadata = buildPackageMetadata({ capabilityId: capability.manifest.id, files })
+  const archiveFiles: CapabilityPackageFile[] = [
+    ...files,
+    {
+      path: PACKAGE_METADATA_PATH,
+      content: Buffer.from(`${JSON.stringify(metadata, null, 2)}\n`),
+    },
+  ]
+  const outputPath = path.resolve(options.cwd || process.cwd(), options.output || `${capability.manifest.id}.tgz`)
+  if (fs.existsSync(outputPath) && !options.overwrite) {
+    throw new Error(`Capability package already exists: ${outputPath}. Use --force to overwrite it.`)
+  }
+  fs.mkdirSync(path.dirname(outputPath), { recursive: true })
+  const temporaryPath = `${outputPath}.partial-${process.pid}`
+
+  try {
+    await writeArchive({ outputPath: temporaryPath, files: archiveFiles })
+    if (options.overwrite) {
+      fs.rmSync(outputPath, { force: true })
+    }
+    fs.renameSync(temporaryPath, outputPath)
+  } catch (error) {
+    if (fs.existsSync(temporaryPath)) {
+      fs.rmSync(temporaryPath, { force: true })
+    }
+    throw new Error(`Failed to pack capability ${capability.manifest.id}`, { cause: error })
+  }
+
+  return {
+    capabilityId: capability.manifest.id,
+    path: outputPath,
+    files: files.map((file) => {
+      return file.path
+    }),
+    integrity: fileIntegrity(outputPath),
+  }
+}
+
+export async function installCapabilityPackage(options: {
+  source: string
+  cwd?: string
+  location?: CapabilityLocation
+  overwrite?: boolean
+}): Promise<InstalledCapabilityPackage> {
+  const cwd = options.cwd || process.cwd()
+  const source = await readPackageSource({ source: options.source, cwd })
+  const manifestFile = requirePackageFile({ files: source.files, filePath: 'capability.json' })
+  const manifest = parsePackageManifest(manifestFile.content)
+  validatePackageMetadata({ files: source.files, metadataFile: source.metadataFile, manifest })
+  const files = normalizeInstallFiles({ files: source.files, manifest })
+
+  const location = options.location || 'user'
+  const capabilityDir = getCapabilityDir({ id: manifest.id, location, cwd })
+  if (fs.existsSync(capabilityDir) && !options.overwrite) {
+    throw new Error(`Capability already exists: ${manifest.id}. Use --force to overwrite package files.`)
+  }
+  if (options.overwrite) {
+    fs.rmSync(path.join(capabilityDir, 'agent-skills'), { recursive: true, force: true })
+    removeCapabilityAuthFiles({ capabilityDir })
+  }
+  fs.mkdirSync(capabilityDir, { recursive: true })
+  files.map((file) => {
+    const destination = resolvePackageDestination({ capabilityDir, filePath: file.path })
+    fs.mkdirSync(path.dirname(destination), { recursive: true })
+    fs.writeFileSync(destination, file.content)
+    return destination
+  })
+
+  const capability = readCapability({ dir: capabilityDir, location })
+  return {
+    source: source.label,
+    capability,
+    files: files.map((file) => {
+      return file.path
+    }),
+    integrity: source.integrity,
+    agentSkillAvailable: fs.existsSync(path.join(capabilityDir, 'agent-skills', 'codex', 'SKILL.md')),
+  }
+}
+
+function readCapabilityPackageFiles(options: {
+  sourceDir: string
+  manifest: CapabilityManifest
+}): CapabilityPackageFile[] {
+  const entryPath = normalizeRelativePath(options.manifest.entry)
+  const requiredPaths = ['capability.json', entryPath]
+  const missing = requiredPaths.filter((filePath) => {
+    return !fs.existsSync(path.join(options.sourceDir, ...filePath.split('/')))
+  })
+  if (missing.length > 0) {
+    throw new Error(`Capability package is missing required files: ${missing.join(', ')}`)
+  }
+  const optionalPaths = ['README.md'].filter((filePath) => {
+    return fs.existsSync(path.join(options.sourceDir, filePath))
+  })
+  const agentSkillDir = path.join(options.sourceDir, 'agent-skills')
+  const agentSkillPaths = fs.existsSync(agentSkillDir)
+    ? listRegularFiles({ dir: agentSkillDir }).map((filePath) => {
+        return path.posix.join('agent-skills', filePath)
+      })
+    : []
+  const packagePaths = [...new Set([...requiredPaths, ...optionalPaths, ...agentSkillPaths])].sort()
+  assertPackageLimits({ paths: packagePaths })
+
+  const files = packagePaths.map((filePath) => {
+    if (filePath === 'capability.json') {
+      return {
+        path: filePath,
+        content: Buffer.from(`${JSON.stringify(options.manifest, null, 2)}\n`),
+      }
+    }
+    const sourcePath = resolvePackageDestination({ capabilityDir: options.sourceDir, filePath })
+    const sourceStat = fs.lstatSync(sourcePath)
+    if (!sourceStat.isFile() || sourceStat.isSymbolicLink()) {
+      throw new Error(`Capability packages can only contain regular files: ${filePath}`)
+    }
+    return { path: filePath, content: fs.readFileSync(sourcePath) }
+  })
+  assertExtractedSize(files)
+  return files
+}
+
+function listRegularFiles(options: { dir: string; prefix?: string }): string[] {
+  return fs.readdirSync(options.dir, { withFileTypes: true }).flatMap((entry) => {
+    const relativePath = path.posix.join(options.prefix || '', entry.name)
+    const absolutePath = path.join(options.dir, entry.name)
+    if (entry.isSymbolicLink()) {
+      throw new Error(`Capability packages cannot contain symbolic links: ${relativePath}`)
+    }
+    if (entry.isDirectory()) {
+      return listRegularFiles({ dir: absolutePath, prefix: relativePath })
+    }
+    if (!entry.isFile()) {
+      throw new Error(`Capability packages can only contain regular files: ${relativePath}`)
+    }
+    return [relativePath]
+  })
+}
+
+function buildPackageMetadata(options: {
+  capabilityId: string
+  files: CapabilityPackageFile[]
+}): z.infer<typeof CapabilityPackageMetadataSchema> {
+  return {
+    schemaVersion: 1,
+    capabilityId: options.capabilityId,
+    packedAt: new Date().toISOString(),
+    files: options.files.map((file) => {
+      return { path: file.path, sha256: bufferSha256(file.content) }
+    }),
+  }
+}
+
+async function writeArchive(options: { outputPath: string; files: CapabilityPackageFile[] }): Promise<void> {
+  const archive = tar.pack()
+  const output = pipeline(archive, zlib.createGzip({ level: 9 }), fs.createWriteStream(options.outputPath))
+  await Promise.all(
+    options.files.map((file) => {
+      return new Promise<void>((resolve, reject) => {
+        archive.entry(
+          {
+            name: path.posix.join(PACKAGE_ROOT, file.path),
+            size: file.content.length,
+            mode: 0o644,
+            mtime: new Date(0),
+            type: 'file',
+          },
+          file.content,
+          (error) => {
+            if (error) {
+              reject(error)
+              return
+            }
+            resolve()
+          },
+        )
+      })
+    }),
+  )
+  archive.finalize()
+  await output
+}
+
+async function readPackageSource(options: {
+  source: string
+  cwd: string
+}): Promise<{
+  label: string
+  files: CapabilityPackageFile[]
+  metadataFile?: CapabilityPackageFile
+  integrity: string
+}> {
+  const localPath = path.resolve(options.cwd, options.source)
+  if (fs.existsSync(localPath)) {
+    if (fs.statSync(localPath).isDirectory()) {
+      const manifestPath = path.join(localPath, 'capability.json')
+      if (!fs.existsSync(manifestPath)) {
+        throw new Error(`Capability directory is missing capability.json: ${localPath}`)
+      }
+      const manifest = parsePackageManifest(fs.readFileSync(manifestPath))
+      const files = readCapabilityPackageFiles({ sourceDir: localPath, manifest: { ...manifest, status: 'draft' } })
+      return {
+        label: localPath,
+        files,
+        integrity: filesIntegrity(files),
+      }
+    }
+    const archive = fs.readFileSync(localPath)
+    assertArchiveSize({ size: archive.length, label: localPath })
+    const extracted = await readArchive(archive)
+    return {
+      label: localPath,
+      files: extracted.files,
+      metadataFile: extracted.metadataFile,
+      integrity: bufferIntegrity(archive),
+    }
+  }
+
+  if (!/^https?:\/\//.test(options.source)) {
+    throw new Error(`Capability source not found: ${options.source}`)
+  }
+  const response = await fetch(options.source, { redirect: 'follow' })
+  if (!response.ok) {
+    throw new Error(`Failed to download capability package: ${response.status} ${response.statusText}`)
+  }
+  const contentLength = Number(response.headers.get('content-length') || 0)
+  assertArchiveSize({ size: contentLength, label: options.source })
+  const archive = Buffer.from(await response.arrayBuffer())
+  assertArchiveSize({ size: archive.length, label: options.source })
+  const extracted = await readArchive(archive)
+  return {
+    label: options.source,
+    files: extracted.files,
+    metadataFile: extracted.metadataFile,
+    integrity: bufferIntegrity(archive),
+  }
+}
+
+async function readArchive(archive: Buffer): Promise<{
+  files: CapabilityPackageFile[]
+  metadataFile: CapabilityPackageFile
+}> {
+  const extracted = await extractArchiveFiles(archive)
+  const metadataFile =
+    extracted.find((file) => {
+      return file.path === PACKAGE_METADATA_PATH
+    }) || requirePackageFile({ files: extracted, filePath: LEGACY_PACKAGE_METADATA_PATH })
+  const files = extracted.filter((file) => {
+    return file.path !== PACKAGE_METADATA_PATH && file.path !== LEGACY_PACKAGE_METADATA_PATH
+  })
+  return { files, metadataFile }
+}
+
+async function extractArchiveFiles(archive: Buffer): Promise<CapabilityPackageFile[]> {
+  const extractor = tar.extract()
+  const files: CapabilityPackageFile[] = []
+  let totalBytes = 0
+  const extraction = new Promise<void>((resolve, reject) => {
+    extractor.on('entry', (header, stream, next) => {
+      const relativePath = normalizeArchiveEntryPath(header.name)
+      if (header.type === 'directory') {
+        stream.resume()
+        next()
+        return
+      }
+      if (header.type !== 'file' && header.type !== null && header.type !== undefined) {
+        stream.resume()
+        next(new Error(`Capability archives cannot contain ${header.type} entries: ${header.name}`))
+        return
+      }
+      readStreamWithLimit({ stream, limit: MAX_EXTRACTED_BYTES })
+        .then((content) => {
+          if (files.some((file) => file.path === relativePath)) {
+            next(new Error(`Capability package contains duplicate path: ${relativePath}`))
+            return
+          }
+          totalBytes += content.length
+          if (totalBytes > MAX_EXTRACTED_BYTES) {
+            next(new Error(`Capability package expands beyond ${MAX_EXTRACTED_BYTES} bytes`))
+            return
+          }
+          files.push({ path: relativePath, content })
+          if (files.length > MAX_PACKAGE_FILES) {
+            next(new Error(`Capability package exceeds ${MAX_PACKAGE_FILES} files`))
+            return
+          }
+          next()
+        })
+        .catch((error: unknown) => {
+          next(error)
+        })
+    })
+    extractor.on('finish', resolve)
+    extractor.on('error', reject)
+  })
+  await pipeline(Readable.from(archive), zlib.createGunzip(), extractor)
+  await extraction
+  assertExtractedSize(files, totalBytes)
+  return files
+}
+
+async function readStreamWithLimit(options: { stream: Readable; limit: number }): Promise<Buffer> {
+  const chunks: Buffer[] = []
+  let size = 0
+  for await (const rawChunk of options.stream) {
+    const chunk = Buffer.isBuffer(rawChunk) ? rawChunk : Buffer.from(rawChunk)
+    size += chunk.length
+    if (size > options.limit) {
+      throw new Error(`Capability package entry exceeds ${options.limit} bytes`)
+    }
+    chunks.push(chunk)
+  }
+  return Buffer.concat(chunks)
+}
+
+function parsePackageManifest(content: Buffer): CapabilityManifest {
+  const raw: unknown = (() => {
+    try {
+      return JSON.parse(content.toString('utf-8'))
+    } catch (error) {
+      throw new Error('Capability package has invalid capability.json', { cause: error })
+    }
+  })()
+  return parseCapabilityManifest({
+    ...assertJsonObject(raw),
+    status: 'draft',
+  })
+}
+
+function normalizeInstallFiles(options: {
+  files: CapabilityPackageFile[]
+  manifest: CapabilityManifest
+}): CapabilityPackageFile[] {
+  const entryPath = normalizeRelativePath(options.manifest.entry)
+  const allowed = options.files.filter((file) => {
+    return (
+      file.path === 'capability.json' ||
+      file.path === entryPath ||
+      file.path === 'README.md' ||
+      file.path.startsWith('agent-skills/')
+    )
+  })
+  requirePackageFile({ files: allowed, filePath: entryPath })
+  const normalizedManifest = {
+    ...options.manifest,
+    status: 'draft' as const,
+    updatedAt: new Date().toISOString(),
+  }
+  return allowed.map((file) => {
+    if (file.path !== 'capability.json') {
+      return file
+    }
+    return {
+      path: file.path,
+      content: Buffer.from(`${JSON.stringify(normalizedManifest, null, 2)}\n`),
+    }
+  })
+}
+
+function validatePackageMetadata(options: {
+  files: CapabilityPackageFile[]
+  metadataFile?: CapabilityPackageFile
+  manifest: CapabilityManifest
+}): void {
+  if (!options.metadataFile) {
+    return
+  }
+  const metadata = CapabilityPackageMetadataSchema.parse(JSON.parse(options.metadataFile.content.toString('utf-8')))
+  if (metadata.capabilityId !== options.manifest.id) {
+    throw new Error(`Capability package id mismatch: ${metadata.capabilityId} !== ${options.manifest.id}`)
+  }
+  const actualHashes = new Map(
+    options.files.map((file) => {
+      return [file.path, bufferSha256(file.content)]
+    }),
+  )
+  const mismatches = metadata.files.filter((file) => {
+    return actualHashes.get(file.path) !== file.sha256
+  })
+  if (mismatches.length > 0 || metadata.files.length !== options.files.length) {
+    const detail = mismatches.length > 0 ? mismatches.map((file) => file.path).join(', ') : 'file count mismatch'
+    throw new Error(`Capability package integrity check failed: ${detail}`)
+  }
+}
+
+function requirePackageFile(options: {
+  files: CapabilityPackageFile[]
+  filePath: string
+}): CapabilityPackageFile {
+  const file = options.files.find((candidate) => {
+    return candidate.path === options.filePath
+  })
+  if (!file) {
+    throw new Error(`Capability package is missing ${options.filePath}`)
+  }
+  return file
+}
+
+function normalizeArchiveEntryPath(entryPath: string): string {
+  const normalized = normalizeRelativePath(entryPath)
+  if (!normalized.startsWith(`${PACKAGE_ROOT}/`)) {
+    throw new Error(`Capability archive entries must stay under ${PACKAGE_ROOT}/: ${entryPath}`)
+  }
+  return normalizeRelativePath(normalized.slice(PACKAGE_ROOT.length + 1))
+}
+
+function normalizeRelativePath(filePath: string): string {
+  const slashPath = filePath.replaceAll('\\', '/')
+  const normalized = path.posix.normalize(slashPath)
+  if (
+    normalized === '.' ||
+    normalized.startsWith('/') ||
+    normalized === '..' ||
+    normalized.startsWith('../') ||
+    normalized.includes('\0')
+  ) {
+    throw new Error(`Capability package path must be relative and stay inside the package: ${filePath}`)
+  }
+  return normalized
+}
+
+function resolvePackageDestination(options: { capabilityDir: string; filePath: string }): string {
+  const normalized = normalizeRelativePath(options.filePath)
+  const root = path.resolve(options.capabilityDir)
+  const destination = path.resolve(root, ...normalized.split('/'))
+  if (destination !== root && !destination.startsWith(`${root}${path.sep}`)) {
+    throw new Error(`Capability package path escapes its destination: ${options.filePath}`)
+  }
+  return destination
+}
+
+function assertPackageLimits(options: { paths: string[] }): void {
+  if (options.paths.length > MAX_PACKAGE_FILES) {
+    throw new Error(`Capability package exceeds ${MAX_PACKAGE_FILES} files`)
+  }
+}
+
+function assertArchiveSize(options: { size: number; label: string }): void {
+  if (options.size > MAX_ARCHIVE_BYTES) {
+    throw new Error(`Capability package exceeds ${MAX_ARCHIVE_BYTES} bytes: ${options.label}`)
+  }
+}
+
+function assertExtractedSize(files: CapabilityPackageFile[], knownSize?: number): void {
+  const totalBytes =
+    knownSize ??
+    files.reduce((total, file) => {
+      return total + file.content.length
+    }, 0)
+  if (totalBytes > MAX_EXTRACTED_BYTES) {
+    throw new Error(`Capability package expands beyond ${MAX_EXTRACTED_BYTES} bytes`)
+  }
+}
+
+function assertJsonObject(value: unknown): Record<string, unknown> {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    throw new Error('Capability package manifest must be an object')
+  }
+  return value as Record<string, unknown>
+}
+
+function bufferSha256(content: Buffer): string {
+  return crypto.createHash('sha256').update(content).digest('hex')
+}
+
+function bufferIntegrity(content: Buffer): string {
+  return `sha256-${crypto.createHash('sha256').update(content).digest('base64')}`
+}
+
+function fileIntegrity(filePath: string): string {
+  return bufferIntegrity(fs.readFileSync(filePath))
+}
+
+function filesIntegrity(files: CapabilityPackageFile[]): string {
+  const hash = crypto.createHash('sha256')
+  files.map((file) => {
+    hash.update(file.path)
+    hash.update('\0')
+    hash.update(file.content)
+    return file.path
+  })
+  return `sha256-${hash.digest('base64')}`
+}