{"record":{"id":"45990906df7c9655","repo":"moeru-ai/airi","slug":"label-must-be-a-regular-file-path","errorCode":null,"errorMessage":"${label} must be a regular file: ${path}","messagePattern":"(.+?) must be a regular file: (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"apps/stage-tamagotchi/src/main/services/airi/plugins/host/directory-import.ts","lineNumber":116,"sourceCode":"      optional: kit.optional ?? false,\n    })),\n  ]\n}\n\nasync function assertRegularFile(path: string, label: string): Promise<Stats> {\n  let stats: Stats\n  try {\n    stats = await lstat(path)\n  }\n  catch (error) {\n    if (isMissingPathError(error)) {\n      throw new Error(`${label} does not exist: ${path}`)\n    }\n    throw error\n  }\n\n  if (stats.isSymbolicLink() || !stats.isFile()) {\n    throw new Error(`${label} must be a regular file: ${path}`)\n  }\n  return stats\n}\n\nasync function readManifestSnapshot(path: string, expectedSize: number): Promise<Buffer> {\n  const handle = await open(path, 'r')\n  try {\n    // One extra byte distinguishes the maximum valid manifest from a file\n    // that grew past the limit after the directory walk.\n    const buffer = Buffer.allocUnsafe(extensionPackageLimits.manifestBytes + 1)\n    let bytesRead = 0\n    while (bytesRead < buffer.byteLength) {\n      const result = await handle.read(buffer, bytesRead, buffer.byteLength - bytesRead, bytesRead)\n      if (result.bytesRead === 0) {\n        break\n      }\n      bytesRead += result.bytesRead\n    }","sourceCodeStart":98,"sourceCodeEnd":134,"githubUrl":"https://github.com/moeru-ai/airi/blob/438a067dde47aa0bdb46c2323d1fe293dc805218/apps/stage-tamagotchi/src/main/services/airi/plugins/host/directory-import.ts#L98-L134","documentation":"assertRegularFile rejects paths that are symlinks or not regular files, because manifests and package contents must be real files inside the imported directory. This hardens the extension importer against symlink-based escapes and special files (FIFOs, devices, directories).","triggerScenarios":"The manifest (or other labeled file) is a symlink, a directory, or a device/fifo at the inspected path.","commonSituations":"Repository checkouts where package.json is a symlink to a shared config; macOS alias-like links in downloaded archives; pointing at a directory instead of the manifest file.","solutions":["Replace the symlink with a real copy of the file in the extension folder","Ensure the labeled path is a regular file, not a directory or special file","Avoid packaging extensions with symlinks; zip real files"],"exampleFix":"// before\nln -s ~/shared/package.json extensions/myext/package.json\n// after\ncp ~/shared/package.json extensions/myext/package.json","handlingStrategy":"validation","validationCode":"import { lstat } from 'node:fs/promises'\nasync function isRegularFile(p: string): Promise<boolean> {\n  try {\n    const s = await lstat(p)\n    return s.isFile() && !s.isSymbolicLink()\n  } catch { return false }\n}","typeGuard":"function isRegularStats(s: { isFile(): boolean; isSymbolicLink(): boolean }): boolean {\n  return s.isFile() && !s.isSymbolicLink()\n}","tryCatchPattern":"try {\n  await importFromDirectory(dir)\n} catch (e) {\n  if (e instanceof Error && /must be a regular file:/.test(e.message)) {\n    console.warn(`${e.message} — replace symlinks with real copies before importing`)\n    return null\n  }\n  throw e\n}","preventionTips":["Package extensions with real files, never symlinks","lstat the manifest before import to catch symlink/directory issues early","Watch for tools that replace package.json with a link to shared config"],"tags":["filesystem","symlink","security"],"backgroundTag":"incompatible-source-type","analyzedSha":"438a067dde47aa0bdb46c2323d1fe293dc805218","analyzedAt":"2026-09-17T01:14:42.644Z","contentChangedAt":"2026-09-17T01:14:42.644Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}