import { constants as fsConstants } from "node:fs"; import fs from "node:fs/promises"; import os from "node:os"; import path from "node:path"; import { createHash, type Hash } from "node:crypto"; import type { AdapterExecutionContext } from "@paperclipai/adapter-utils"; import { ensurePaperclipSkillSymlink, type PaperclipSkillEntry } from "@paperclipai/adapter-utils/server-utils"; const DEFAULT_PAPERCLIP_INSTANCE_ID = "default"; type SkillEntry = PaperclipSkillEntry; export interface ClaudePromptBundle { bundleKey: string; rootDir: string; addDir: string; instructionsFilePath: string | null; } function nonEmpty(value: string | undefined): string | null { return typeof value === "string" && value.trim().length > 0 ? value.trim() : null; } function resolveManagedClaudePromptCacheRoot( env: NodeJS.ProcessEnv, companyId: string, ): string { const paperclipHome = nonEmpty(env.PAPERCLIP_HOME) ?? path.resolve(os.homedir(), ".paperclip"); const instanceId = nonEmpty(env.PAPERCLIP_INSTANCE_ID) ?? DEFAULT_PAPERCLIP_INSTANCE_ID; return path.resolve( paperclipHome, "instances", instanceId, "companies", companyId, "claude-prompt-cache", ); } async function hashPathContents( candidate: string, hash: Hash, relativePath: string, seenDirectories: Set, ): Promise { const stat = await fs.lstat(candidate); if (stat.isSymbolicLink()) { hash.update(`symlink:${relativePath}\n`); const resolved = await fs.realpath(candidate).catch(() => null); if (!resolved) { hash.update("missing\n"); return; } await hashPathContents(resolved, hash, relativePath, seenDirectories); return; } if (stat.isDirectory()) { const realDir = await fs.realpath(candidate).catch(() => candidate); hash.update(`dir:${relativePath}\n`); if (seenDirectories.has(realDir)) { hash.update("loop\n"); return; } seenDirectories.add(realDir); const entries = await fs.readdir(candidate, { withFileTypes: true }); entries.sort((left, right) => left.name.localeCompare(right.name)); for (const entry of entries) { const childRelativePath = relativePath.length > 0 ? `${relativePath}/${entry.name}` : entry.name; await hashPathContents(path.join(candidate, entry.name), hash, childRelativePath, seenDirectories); } return; } if (stat.isFile()) { hash.update(`file:${relativePath}\n`); hash.update(await fs.readFile(candidate)); hash.update("\n"); return; } hash.update(`other:${relativePath}:${stat.mode}\n`); } async function buildClaudePromptBundleKey(input: { skills: SkillEntry[]; instructionsContents: string | null; }): Promise { const hash = createHash("sha256"); hash.update("paperclip-claude-prompt-bundle:v1\n"); if (input.instructionsContents) { hash.update("instructions\n"); hash.update(input.instructionsContents); hash.update("\n"); } else { hash.update("instructions:none\n"); } const sortedSkills = [...input.skills].sort((left, right) => left.runtimeName.localeCompare(right.runtimeName)); for (const entry of sortedSkills) { hash.update(`skill:${entry.key}:${entry.runtimeName}\n`); await hashPathContents(entry.source, hash, entry.runtimeName, new Set()); } return hash.digest("hex"); } async function ensureReadableFile(targetPath: string, contents: string): Promise { try { await fs.access(targetPath, fsConstants.R_OK); return; } catch { // Fall through and materialize the file. } await fs.mkdir(path.dirname(targetPath), { recursive: true }); const tempPath = `${targetPath}.${process.pid}.${Date.now()}.tmp`; try { await fs.writeFile(tempPath, contents, "utf8"); await fs.rename(tempPath, targetPath); } catch (err) { const targetReadable = await fs.access(targetPath, fsConstants.R_OK).then(() => true).catch(() => false); if (!targetReadable) { throw err; } } finally { await fs.rm(tempPath, { force: true }).catch(() => {}); } } export async function prepareClaudePromptBundle(input: { companyId: string; skills: SkillEntry[]; instructionsContents: string | null; onLog: AdapterExecutionContext["onLog"]; }): Promise { const { companyId, skills, instructionsContents, onLog } = input; const bundleKey = await buildClaudePromptBundleKey({ skills, instructionsContents, }); const rootDir = path.join(resolveManagedClaudePromptCacheRoot(process.env, companyId), bundleKey); const skillsHome = path.join(rootDir, ".claude", "skills"); await fs.mkdir(skillsHome, { recursive: true }); for (const entry of skills) { const target = path.join(skillsHome, entry.runtimeName); try { await ensurePaperclipSkillSymlink(entry.source, target); } catch (err) { await onLog( "stderr", `[paperclip] Failed to materialize Claude skill "${entry.key}" into ${skillsHome}: ${err instanceof Error ? err.message : String(err)}\n`, ); } } const instructionsFilePath = instructionsContents ? path.join(rootDir, "agent-instructions.md") : null; if (instructionsFilePath && instructionsContents) { await ensureReadableFile(instructionsFilePath, instructionsContents); } return { bundleKey, rootDir, addDir: rootDir, instructionsFilePath, }; }