@atproto/lex-installer 0.1.3 → 0.1.4

package/src/fs.ts

@@ -1,122 +0,0 @@
-import { mkdir, readFile, writeFile } from 'node:fs/promises'
-import { dirname } from 'node:path'
-
-/**
- * Reads and parses a JSON file from the filesystem.
- *
- * @param path - Absolute or relative path to the JSON file
- * @returns The parsed JSON content
- * @throws {Error} When the file cannot be read (e.g., ENOENT, EACCES)
- * @throws {SyntaxError} When the file contains invalid JSON
- *
- * @example
- * ```typescript
- * import { readJsonFile } from '@atproto/lex-installer'
- *
- * const manifest = await readJsonFile('./lexicons.manifest.json')
- * ```
- *
- * @example
- * Handle missing file:
- * ```typescript
- * import { readJsonFile, isEnoentError } from '@atproto/lex-installer'
- *
- * try {
- *   const data = await readJsonFile('./config.json')
- * } catch (err) {
- *   if (isEnoentError(err)) {
- *     console.log('File does not exist, using defaults')
- *   } else {
- *     throw err
- *   }
- * }
- * ```
- */
-export async function readJsonFile(path: string): Promise<unknown> {
-  const contents = await readFile(path, 'utf8')
-  return JSON.parse(contents)
-}
-
-/**
- * Writes data as formatted JSON to a file.
- *
- * The function:
- * - Creates parent directories if they don't exist
- * - Formats JSON with 2-space indentation
- * - Overwrites existing files
- * - Sets file permissions to 0o644 (rw-r--r--)
- *
- * @param path - Absolute or relative path for the output file
- * @param data - Data to serialize as JSON
- * @throws {Error} When the file cannot be written
- *
- * @example
- * ```typescript
- * import { writeJsonFile } from '@atproto/lex-installer'
- *
- * await writeJsonFile('./output/data.json', {
- *   name: 'example',
- *   values: [1, 2, 3],
- * })
- * ```
- *
- * @example
- * Write a lexicon document:
- * ```typescript
- * import { writeJsonFile } from '@atproto/lex-installer'
- *
- * await writeJsonFile('./lexicons/app/bsky/feed/post.json', lexiconDocument)
- * ```
- */
-export async function writeJsonFile(
-  path: string,
-  data: unknown,
-): Promise<void> {
-  await mkdir(dirname(path), { recursive: true })
-  const contents = JSON.stringify(data, null, 2)
-  await writeFile(path, contents, {
-    encoding: 'utf8',
-    mode: 0o644,
-    flag: 'w', // override
-  })
-}
-
-/**
- * Checks if an error is an ENOENT (file not found) error.
- *
- * Useful for handling cases where a file may or may not exist,
- * such as reading an optional configuration file.
- *
- * @param err - The error to check
- * @returns `true` if the error is an ENOENT error, `false` otherwise
- *
- * @example
- * ```typescript
- * import { readFile } from 'node:fs/promises'
- * import { isEnoentError } from '@atproto/lex-installer'
- *
- * const config = await readFile('./config.json').catch((err) => {
- *   if (isEnoentError(err)) {
- *     return { defaults: true }
- *   }
- *   throw err
- * })
- * ```
- *
- * @example
- * In try/catch:
- * ```typescript
- * try {
- *   const manifest = await readFile('./lexicons.manifest.json', 'utf8')
- * } catch (err) {
- *   if (isEnoentError(err)) {
- *     // File doesn't exist, create a new manifest
- *     return { version: 1, lexicons: [], resolutions: {} }
- *   }
- *   throw err
- * }
- * ```
- */
-export function isEnoentError(err: unknown): boolean {
-  return err instanceof Error && 'code' in err && err.code === 'ENOENT'
-}

package/src/index.ts

@@ -1,126 +0,0 @@
-import { isEnoentError, readJsonFile } from './fs.js'
-import { LexInstaller, LexInstallerOptions } from './lex-installer.js'
-import {
-  LexiconsManifest,
-  lexiconsManifestSchema,
-} from './lexicons-manifest.js'
-
-/**
- * Options for the {@link install} function.
- *
- * Extends {@link LexInstallerOptions} with additional options for controlling
- * the installation behavior.
- *
- * @example
- * ```typescript
- * const options: LexInstallOptions = {
- *   lexicons: './lexicons',
- *   manifest: './lexicons.manifest.json',
- *   add: ['com.example.myLexicon', 'at://did:plc:xyz/com.example.otherLexicon'],
- *   save: true,
- *   ci: false,
- * }
- * ```
- */
-export type LexInstallOptions = LexInstallerOptions & {
-  /**
-   * Array of lexicons to add to the installation. Can be NSID strings
-   * (e.g., 'com.example.myLexicon') or AT URIs
-   * (e.g., 'at://did:plc:xyz/com.example.myLexicon').
-   */
-  add?: string[]
-
-  /**
-   * Whether to save the updated manifest after installation.
-   * When `true`, the manifest file will be written with any new lexicons.
-   * @default false
-   */
-  save?: boolean
-
-  /**
-   * Enable CI mode for strict manifest verification.
-   * When `true`, throws an error if the manifest is out of date,
-   * useful for continuous integration pipelines.
-   * @default false
-   */
-  ci?: boolean
-}
-
-/**
- * Installs lexicons from the network based on the provided options.
- *
- * This is the main entry point for programmatic lexicon installation.
- * It reads an existing manifest (if present), installs any new lexicons,
- * and optionally saves the updated manifest.
- *
- * @param options - Configuration options for the installation
- * @throws {Error} When the manifest file cannot be read (unless it doesn't exist)
- * @throws {Error} When in CI mode and the manifest is out of date
- *
- * @example
- * Install lexicons and save the manifest:
- * ```typescript
- * import { install } from '@atproto/lex-installer'
- *
- * await install({
- *   lexicons: './lexicons',
- *   manifest: './lexicons.manifest.json',
- *   add: ['app.bsky.feed.post', 'app.bsky.actor.profile'],
- *   save: true,
- * })
- * ```
- *
- * @example
- * Verify manifest in CI pipeline:
- * ```typescript
- * import { install } from '@atproto/lex-installer'
- *
- * // Throws if manifest is out of date
- * await install({
- *   lexicons: './lexicons',
- *   manifest: './lexicons.manifest.json',
- *   ci: true,
- * })
- * ```
- *
- * @example
- * Install from specific AT URIs:
- * ```typescript
- * import { install } from '@atproto/lex-installer'
- *
- * await install({
- *   lexicons: './lexicons',
- *   manifest: './lexicons.manifest.json',
- *   add: ['at://did:plc:z72i7hdynmk6r22z27h6tvur/app.bsky.feed.post'],
- *   save: true,
- * })
- * ```
- */
-export async function install(options: LexInstallOptions) {
-  const manifest: LexiconsManifest | undefined = await readJsonFile(
-    options.manifest,
-  ).then(
-    (json) => lexiconsManifestSchema.parse(json),
-    (cause: unknown) => {
-      if (isEnoentError(cause)) return undefined
-      throw new Error('Failed to read lexicons manifest', { cause })
-    },
-  )
-
-  const additions = new Set(options.add)
-
-  // Perform the installation using the existing manifest as "hint"
-  await using installer = new LexInstaller(options)
-
-  await installer.install({ additions, manifest })
-
-  // Verify lockfile
-  if (options.ci && (!manifest || !installer.equals(manifest))) {
-    throw new Error('Lexicons manifest is out of date')
-  }
-
-  // Save changes if requested
-  if (options.save) {
-    await installer.save()
-  }
-}

package/src/lex-installer.ts

@@ -1,460 +0,0 @@
-import { join } from 'node:path'
-import { LexiconDirectoryIndexer } from '@atproto/lex-builder'
-import { cidForLex } from '@atproto/lex-cbor'
-import { Cid, lexEquals } from '@atproto/lex-data'
-import {
-  LexiconDocument,
-  LexiconParameters,
-  LexiconPermission,
-  LexiconRef,
-  LexiconRefUnion,
-  LexiconUnknown,
-  MainLexiconDefinition,
-  NamedLexiconDefinition,
-} from '@atproto/lex-document'
-import { LexResolver, LexResolverOptions } from '@atproto/lex-resolver'
-import { AtUriString, NsidString } from '@atproto/lex-schema'
-import { AtUri, NSID } from '@atproto/syntax'
-import { isEnoentError, writeJsonFile } from './fs.js'
-import {
-  LexiconsManifest,
-  normalizeLexiconsManifest,
-} from './lexicons-manifest.js'
-import { NsidMap } from './nsid-map.js'
-import { NsidSet } from './nsid-set.js'
-
-/**
- * Configuration options for the {@link LexInstaller} class.
- *
- * Extends {@link LexResolverOptions} with paths for lexicon storage
- * and manifest management.
- *
- * @example
- * ```typescript
- * const options: LexInstallerOptions = {
- *   lexicons: './lexicons',
- *   manifest: './lexicons.manifest.json',
- *   update: false,
- * }
- * ```
- */
-export type LexInstallerOptions = LexResolverOptions & {
-  /**
-   * Path to the directory where lexicon JSON files will be stored.
-   * The directory structure mirrors the NSID hierarchy
-   * (e.g., 'app.bsky.feed.post' becomes 'app/bsky/feed/post.json').
-   */
-  lexicons: string
-
-  /**
-   * Path to the manifest file that tracks installed lexicons and their resolutions.
-   */
-  manifest: string
-
-  /**
-   * When `true`, forces re-fetching of lexicons from the network even if they
-   * already exist locally. Useful for updating to newer versions.
-   * @default false
-   */
-  update?: boolean
-}
-
-/**
- * Manages the installation of Lexicon schemas from the AT Protocol network.
- *
- * The `LexInstaller` class handles fetching, caching, and organizing lexicon
- * documents. It tracks dependencies between lexicons and ensures all referenced
- * schemas are installed. The class implements `AsyncDisposable` for proper
- * resource cleanup.
- *
- * @example
- * Basic usage with async disposal:
- * ```typescript
- * import { LexInstaller } from '@atproto/lex-installer'
- *
- * await using installer = new LexInstaller({
- *   lexicons: './lexicons',
- *   manifest: './lexicons.manifest.json',
- * })
- *
- * await installer.install({
- *   additions: ['app.bsky.feed.post'],
- * })
- *
- * await installer.save()
- * // Resources automatically cleaned up when block exits
- * ```
- *
- * @example
- * Manual disposal:
- * ```typescript
- * const installer = new LexInstaller({
- *   lexicons: './lexicons',
- *   manifest: './lexicons.manifest.json',
- * })
- *
- * try {
- *   await installer.install({ additions: ['app.bsky.actor.profile'] })
- *   await installer.save()
- * } finally {
- *   await installer[Symbol.asyncDispose]()
- * }
- * ```
- */
-export class LexInstaller implements AsyncDisposable {
-  protected readonly lexiconResolver: LexResolver
-  protected readonly indexer: LexiconDirectoryIndexer
-  protected readonly documents = new NsidMap<LexiconDocument>()
-  protected readonly manifest: LexiconsManifest = {
-    version: 1,
-    lexicons: [],
-    resolutions: {},
-  }
-
-  constructor(protected readonly options: LexInstallerOptions) {
-    this.lexiconResolver = new LexResolver(options)
-    this.indexer = new LexiconDirectoryIndexer({
-      lexicons: options.lexicons,
-    })
-  }
-
-  async [Symbol.asyncDispose](): Promise<void> {
-    await this.indexer[Symbol.asyncDispose]()
-  }
-
-  /**
-   * Compares the current manifest state with another manifest for equality.
-   *
-   * Both manifests are normalized before comparison to ensure consistent
-   * ordering of entries. Useful for detecting changes during CI verification.
-   *
-   * @param manifest - The manifest to compare against
-   * @returns `true` if the manifests are equivalent, `false` otherwise
-   */
-  equals(manifest: LexiconsManifest): boolean {
-    return lexEquals(
-      normalizeLexiconsManifest(manifest),
-      normalizeLexiconsManifest(this.manifest),
-    )
-  }
-
-  /**
-   * Installs lexicons and their dependencies.
-   *
-   * This method processes explicit additions and restores entries from an
-   * existing manifest. It recursively resolves and installs all referenced
-   * lexicons to ensure complete dependency trees.
-   *
-   * @param options - Installation options
-   * @param options.additions - Iterable of lexicon identifiers to add.
-   *   Can be NSID strings or AT URIs.
-   * @param options.manifest - Existing manifest to use as a baseline.
-   *   Previously resolved URIs are preserved unless explicitly overridden.
-   *
-   * @example
-   * Install new lexicons:
-   * ```typescript
-   * await installer.install({
-   *   additions: ['app.bsky.feed.post', 'app.bsky.actor.profile'],
-   * })
-   * ```
-   *
-   * @example
-   * Install with existing manifest as hint:
-   * ```typescript
-   * const existingManifest = await readJsonFile('./lexicons.manifest.json')
-   * await installer.install({
-   *   additions: ['com.example.newLexicon'],
-   *   manifest: existingManifest,
-   * })
-   * ```
-   *
-   * @example
-   * Install from specific AT URIs:
-   * ```typescript
-   * await installer.install({
-   *   additions: [
-   *     'at://did:plc:z72i7hdynmk6r22z27h6tvur/app.bsky.feed.post',
-   *   ],
-   * })
-   * ```
-   */
-  async install({
-    additions,
-    manifest,
-  }: {
-    additions?: Iterable<string>
-    manifest?: LexiconsManifest
-  } = {}): Promise<void> {
-    const roots = new NsidMap<AtUri | null>()
-
-    // First, process explicit additions
-    for (const lexicon of new Set(additions)) {
-      const [nsid, uri]: [NSID, AtUri | null] = lexicon.startsWith('at://')
-        ? ((uri) => [NSID.from(uri.rkey), uri])(new AtUri(lexicon))
-        : [NSID.from(lexicon), null]
-
-      if (roots.has(nsid)) {
-        throw new Error(
-          `Duplicate lexicon addition: ${nsid} (${roots.get(nsid) ?? lexicon})`,
-        )
-      }
-
-      roots.set(nsid, uri)
-      console.debug(`Adding new lexicon: ${nsid} (${uri ?? 'from NSID'})`)
-    }
-
-    // Next, restore previously existing manifest entries
-    if (manifest) {
-      for (const lexicon of manifest.lexicons) {
-        const nsid = NSID.from(lexicon)
-
-        // Skip entries already added explicitly
-        if (!roots.has(nsid)) {
-          const uri = manifest.resolutions[lexicon]
-            ? new AtUri(manifest.resolutions[lexicon].uri)
-            : null
-
-          roots.set(nsid, uri)
-
-          console.debug(
-            `Adding lexicon from manifest: ${nsid} (${uri ?? 'from NSID'})`,
-          )
-        }
-      }
-    }
-
-    // Install all root lexicons (and store them in the manifest)
-    await Promise.all(
-      Array.from(roots, async ([nsid, sourceUri]) => {
-        console.debug(`Installing lexicon: ${nsid}`)
-
-        const { lexicon: document } = sourceUri
-          ? await this.installFromUri(sourceUri)
-          : await this.installFromNsid(nsid)
-
-        // Store the direct reference in the new manifest
-        this.manifest.lexicons.push(document.id)
-      }),
-    )
-
-    // Then recursively install all referenced lexicons
-    let results: unknown[]
-    do {
-      results = await Promise.all(
-        Array.from(this.getMissingIds(), async (nsid) => {
-          console.debug(`Resolving dependency lexicon: ${nsid}`)
-
-          const nsidStr = nsid.toString() as NsidString
-          const resolvedUri = manifest?.resolutions[nsidStr]?.uri
-            ? new AtUri(manifest.resolutions[nsidStr].uri)
-            : null
-          if (resolvedUri) {
-            await this.installFromUri(resolvedUri)
-          } else {
-            await this.installFromNsid(nsid)
-          }
-        }),
-      )
-    } while (results.length > 0)
-  }
-
-  protected getMissingIds(): NsidSet {
-    const missing = new NsidSet()
-
-    for (const document of this.documents.values()) {
-      for (const nsid of listDocumentNsidRefs(document)) {
-        if (!this.documents.has(nsid)) {
-          missing.add(nsid)
-        }
-      }
-    }
-
-    return missing
-  }
-
-  protected async installFromNsid(nsid: NSID) {
-    const uri = await this.lexiconResolver.resolve(nsid)
-    return this.installFromUri(uri)
-  }
-
-  protected async installFromUri(uri: AtUri): Promise<{
-    lexicon: LexiconDocument
-    uri: AtUri
-  }> {
-    const { lexicon, cid } = this.options.update
-      ? await this.fetch(uri)
-      : await this.indexer.get(uri.rkey).then(
-          async (lexicon) => {
-            console.debug(`Re-using existing lexicon ${uri.rkey} from indexer`)
-            const cid = await cidForLex(lexicon)
-            return { cid, lexicon }
-          },
-          (err) => {
-            if (isEnoentError(err)) return this.fetch(uri)
-            throw err
-          },
-        )
-
-    this.documents.set(NSID.from(lexicon.id), lexicon)
-    this.manifest.resolutions[lexicon.id] = {
-      cid: cid.toString(),
-      uri: uri.toString() as AtUriString,
-    }
-
-    return { lexicon, uri }
-  }
-
-  /**
-   * Fetches a lexicon document from the network and saves it locally.
-   *
-   * The lexicon is retrieved from the specified AT URI, written to the
-   * local lexicons directory, and its metadata is recorded for the manifest.
-   *
-   * @param uri - The AT URI pointing to the lexicon document
-   * @returns An object containing the fetched lexicon document and its CID
-   */
-  async fetch(uri: AtUri): Promise<{ lexicon: LexiconDocument; cid: Cid }> {
-    console.debug(`Fetching lexicon from ${uri}...`)
-
-    const { lexicon, cid } = await this.lexiconResolver.fetch(uri, {
-      noCache: this.options.update,
-    })
-
-    const basePath = join(this.options.lexicons, ...lexicon.id.split('.'))
-    await writeJsonFile(`${basePath}.json`, lexicon)
-
-    return { lexicon, cid }
-  }
-
-  /**
-   * Saves the current manifest to disk.
-   *
-   * The manifest is normalized before saving to ensure consistent ordering
-   * of entries, making it suitable for version control.
-   */
-  async save(): Promise<void> {
-    await writeJsonFile(
-      this.options.manifest,
-      normalizeLexiconsManifest(this.manifest),
-    )
-  }
-}
-
-function* listDocumentNsidRefs(doc: LexiconDocument): Iterable<NSID> {
-  try {
-    for (const def of Object.values(doc.defs)) {
-      if (def) {
-        for (const ref of defRefs(def)) {
-          const [nsid] = ref.split('#', 1)
-          if (nsid) yield NSID.from(nsid)
-        }
-      }
-    }
-  } catch (cause) {
-    throw new Error(`Failed to extract refs from lexicon ${doc.id}`, { cause })
-  }
-}
-
-function* defRefs(
-  def:
-    | MainLexiconDefinition
-    | NamedLexiconDefinition
-    | LexiconPermission
-    | LexiconUnknown
-    | LexiconParameters
-    | LexiconRef
-    | LexiconRefUnion,
-): Iterable<string> {
-  switch (def.type) {
-    case 'string':
-      if (def.knownValues) {
-        for (const val of def.knownValues) {
-          // Tokens ?
-          const { length, 0: nsid, 1: hash } = val.split('#')
-          if (length === 2 && hash) {
-            try {
-              NSID.from(nsid)
-              yield val
-            } catch {
-              // ignore invalid nsid
-            }
-          }
-        }
-      }
-      return
-    case 'array':
-      return yield* defRefs(def.items)
-    case 'params':
-    case 'object':
-      for (const prop of Object.values(def.properties)) {
-        yield* defRefs(prop)
-      }
-      return
-    case 'union':
-      yield* def.refs
-      return
-    case 'ref': {
-      yield def.ref
-      return
-    }
-    case 'record':
-      yield* defRefs(def.record)
-      return
-    case 'procedure':
-      if (def.input?.schema) {
-        yield* defRefs(def.input.schema)
-      }
-    // fallthrough
-    case 'query':
-      if (def.output?.schema) {
-        yield* defRefs(def.output.schema)
-      }
-    // fallthrough
-    case 'subscription':
-      if (def.parameters) {
-        yield* defRefs(def.parameters)
-      }
-      if ('message' in def && def.message?.schema) {
-        yield* defRefs(def.message.schema)
-      }
-      return
-    case 'permission-set':
-      for (const permission of def.permissions) {
-        yield* defRefs(permission)
-      }
-      return
-    case 'permission':
-      if (def.resource === 'rpc') {
-        if (Array.isArray(def.lxm)) {
-          for (const lxm of def.lxm) {
-            if (typeof lxm === 'string') {
-              yield lxm
-            }
-          }
-        }
-      } else if (def.resource === 'repo') {
-        if (Array.isArray(def.collection)) {
-          for (const lxm of def.collection) {
-            if (typeof lxm === 'string') {
-              yield lxm
-            }
-          }
-        }
-      }
-      return
-    case 'boolean':
-    case 'cid-link':
-    case 'token':
-    case 'bytes':
-    case 'blob':
-    case 'integer':
-    case 'unknown':
-      // @NOTE We explicitly list all types here to ensure exhaustiveness
-      // causing TS to error if a new type is added without updating this switch
-      return
-    default:
-      // @ts-expect-error
-      throw new Error(`Unknown lexicon def type: ${def.type}`)
-  }
-}