@agimon-ai/doompi-help 0.0.1-alpha.41 → 0.0.1-alpha.47

package/dist/adapters/helpStorage.cjs

@@ -1,2 +1,2 @@
-const e=require("../_virtual/_rolldown/runtime.cjs"),t=require("../services/llmsContent.cjs");let n=require("node:crypto"),r=require("node:fs");r=e.__toESM(r,1);let i=require("node:os");i=e.__toESM(i,1);let a=require("node:path");a=e.__toESM(a,1);let o=require("node:url");const s=`llms.txt`,c=`.complete`,l=`metadata.json`,u=`SKILL.md`,d=/^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/u,f=/^(?:@[a-z0-9][a-z0-9._~-]*\/)?[a-z0-9][a-z0-9._~-]*$/u;function p(e){if(e.aborted)throw Error(`Help activation was cancelled.`)}function m(e){return typeof e==`object`&&!!e&&!Array.isArray(e)}function h(e,t){let n=a.default.relative(e,t);return n===``||!n.startsWith(`..${a.default.sep}`)&&n!==`..`&&!a.default.isAbsolute(n)}function g(e){let t;try{t=JSON.parse(r.default.readFileSync(e,`utf8`))}catch(t){throw Error(`Cannot read Help package manifest at ${e}: ${t instanceof Error?t.message:String(t)}`)}if(!m(t))throw Error(`Help package manifest at ${e} must contain an object.`);return t}function _(e,t){if(!f.test(t))throw Error(`Help source '${t}' must be a valid lowercase npm package name.`);let n;try{let t=new URL(e);if(t.protocol!==`file:`)throw Error(`Help module URL must use file:, received ${t.protocol}`);n=r.default.realpathSync((0,o.fileURLToPath)(t))}catch(t){throw Error(`Invalid Help contributor module URL '${e}': ${t instanceof Error?t.message:String(t)}`)}if(!r.default.lstatSync(n).isFile())throw Error(`Help contributor module is not a regular file: ${n}`);let i=a.default.dirname(n);for(;;){let e=a.default.join(i,`package.json`);if(r.default.existsSync(e)){let a=g(e),o=a.name,s=a.version;if(o!==t)throw Error(`Help source '${t}' does not match nearest package '${String(o)}'.`);if(typeof s!=`string`||!d.test(s))throw Error(`Help package '${t}' must declare an exact semantic version.`);let c=r.default.realpathSync(i);if(!h(c,n))throw Error(`Help contributor module escapes its resolved package root.`);return{source:t,version:s,packageRoot:c,modulePath:n}}let o=a.default.dirname(i);if(o===i)break;i=o}throw Error(`Cannot find a package manifest for Help contributor ${n}.`)}function v(e=i.default.homedir()){return a.default.join(e,`.pi`,`.doom`,`llms-cache`)}function y(e){return(0,n.createHash)(`sha256`).update(e).digest(`hex`)}function b(e,t){if(m(e)&&e.schemaVersion===1&&e.source===t.source&&e.version===t.version&&e.path===s&&typeof e.integrity==`string`&&typeof e.digest==`string`&&typeof e.referenceBase==`string`)return e}function x(e){try{let t=r.default.lstatSync(e);return t.isFile()&&!t.isSymbolicLink()}catch{return!1}}var S=class{root;constructor(e=v()){this.root=e}entryDirectory(e){let t=y(`${e.source}\0${e.version}\0${s}`);return a.default.join(this.root,t)}discard(e){r.default.rmSync(this.entryDirectory(e),{recursive:!0,force:!0})}read(e){let t=this.entryDirectory(e),n=a.default.join(t,c),i=a.default.join(t,s),o=a.default.join(t,l);if(!(!x(n)||!x(i)||!x(o)))try{let t=b(JSON.parse(r.default.readFileSync(o,`utf8`)),e);if(!t)return;let a=r.default.readFileSync(i);return y(a)!==t.digest||r.default.readFileSync(n,`utf8`).trim()!==t.digest?void 0:{bytes:a,filePath:i,integrity:t.integrity,digest:t.digest,referenceBase:t.referenceBase}}catch{return}}publish(e,t,i,o,u){p(u);let d=this.read(e);if(d)return d;let f=this.entryDirectory(e);r.default.mkdirSync(this.root,{mode:448,recursive:!0}),r.default.existsSync(f)&&r.default.rmSync(f,{recursive:!0,force:!0});let m=`${f}.${process.pid}.${(0,n.randomUUID)()}.tmp`,h=y(t),g={schemaVersion:1,source:e.source,version:e.version,path:s,integrity:i,digest:h,referenceBase:o};try{r.default.mkdirSync(m,{mode:448}),r.default.writeFileSync(a.default.join(m,s),t,{mode:384}),r.default.writeFileSync(a.default.join(m,l),`${JSON.stringify(g,null,2)}\n`,{mode:384}),p(u),r.default.writeFileSync(a.default.join(m,c),`${h}\n`,{mode:384});try{r.default.renameSync(m,f)}catch(t){let n=this.read(e);if(n)return n;throw t}return{bytes:Uint8Array.from(t),filePath:a.default.join(f,s),integrity:i,digest:h,referenceBase:o}}finally{r.default.rmSync(m,{recursive:!0,force:!0})}}},C=class{cacheRoot;constructor(e=v()){this.cacheRoot=e}async materialize(e,i,o){let s=[];for(let c of e.skills){p(o);let l=y(`${i.identity.source}\0${i.identity.version}\0${c.name}\0${c.description}\0${i.digest}`),d=a.default.join(this.cacheRoot,`wrappers`,l),f=a.default.join(d,u),m=t.renderHelpSkillWrapper(c,i);if(!x(f)||r.default.readFileSync(f,`utf8`)!==m){r.default.mkdirSync(a.default.dirname(d),{mode:448,recursive:!0}),r.default.existsSync(d)&&r.default.rmSync(d,{recursive:!0,force:!0});let e=`${d}.${process.pid}.${(0,n.randomUUID)()}.tmp`;try{r.default.mkdirSync(e,{mode:448}),r.default.writeFileSync(a.default.join(e,u),m,{mode:384}),p(o);try{r.default.renameSync(e,d)}catch(e){if(!x(f)||r.default.readFileSync(f,`utf8`)!==m)throw e}}finally{r.default.rmSync(e,{recursive:!0,force:!0})}}s.push({source:e.source,name:c.name,description:c.description,filePath:f,baseDir:d})}return s}};exports.DefaultHelpSkillMaterializer=C,exports.HelpIndexCache=S,exports.defaultHelpCacheRoot=v,exports.resolveHelpPackageIdentity=_,exports.sha256Hex=y;
+const e=require("../_virtual/_rolldown/runtime.cjs"),t=require("../services/llmsContent.cjs");let n=require("node:crypto"),r=require("node:fs");r=e.__toESM(r,1);let i=require("node:os");i=e.__toESM(i,1);let a=require("node:path");a=e.__toESM(a,1);let o=require("node:url");const s=`llms.txt`,c=`.complete`,l=`metadata.json`,u=`SKILL.md`,d=/^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/u,f=/^(?:@[a-z0-9][a-z0-9._~-]*\/)?[a-z0-9][a-z0-9._~-]*$/u;function p(e){if(e.aborted)throw Error(`Help activation was cancelled.`)}function m(e){return typeof e==`object`&&!!e&&!Array.isArray(e)}function h(e,t){let n=a.default.relative(e,t);return n===``||!n.startsWith(`..${a.default.sep}`)&&n!==`..`&&!a.default.isAbsolute(n)}function g(e){let t;try{t=JSON.parse(r.default.readFileSync(e,`utf8`))}catch(t){throw Error(`Cannot read Help package manifest at ${e}: ${t instanceof Error?t.message:String(t)}`)}if(!m(t))throw Error(`Help package manifest at ${e} must contain an object.`);return t}function _(e,t){if(!f.test(t))throw Error(`Help source '${t}' must be a valid lowercase npm package name.`);let n;try{let t=new URL(e);if(t.protocol!==`file:`)throw Error(`Help module URL must use file:, received ${t.protocol}`);n=r.default.realpathSync((0,o.fileURLToPath)(t))}catch(t){throw Error(`Invalid Help contributor module URL '${e}': ${t instanceof Error?t.message:String(t)}`)}if(!r.default.lstatSync(n).isFile())throw Error(`Help contributor module is not a regular file: ${n}`);let i=a.default.dirname(n);for(;;){let e=a.default.join(i,`package.json`);if(r.default.existsSync(e)){let a=g(e),o=a.name,s=a.version;if(o!==t)throw Error(`Help source '${t}' does not match nearest package '${String(o)}'.`);if(typeof s!=`string`||!d.test(s))throw Error(`Help package '${t}' must declare an exact semantic version.`);let c=r.default.realpathSync(i);if(!h(c,n))throw Error(`Help contributor module escapes its resolved package root.`);return{source:t,version:s,packageRoot:c,modulePath:n}}let o=a.default.dirname(i);if(o===i)break;i=o}throw Error(`Cannot find a package manifest for Help contributor ${n}.`)}function v(e=i.default.homedir()){return a.default.join(e,`.pi`,`.doom`,`llms-cache`)}function y(e){return(0,n.createHash)(`sha256`).update(e).digest(`hex`)}function b(e,t){if(m(e)&&e.schemaVersion===1&&e.source===t.source&&e.version===t.version&&e.path===s&&typeof e.integrity==`string`&&typeof e.digest==`string`&&typeof e.referenceBase==`string`)return e}function x(e){try{let t=r.default.lstatSync(e);return t.isFile()&&!t.isSymbolicLink()}catch{return!1}}var S=class{root;constructor(e=v()){this.root=e}entryDirectory(e){let t=y(`${e.source}\0${e.version}\0${s}`);return a.default.join(this.root,t)}discard(e){r.default.rmSync(this.entryDirectory(e),{recursive:!0,force:!0})}read(e){let t=this.entryDirectory(e),n=a.default.join(t,c),i=a.default.join(t,s),o=a.default.join(t,l);if(x(n)&&x(i)&&x(o))try{let t=b(JSON.parse(r.default.readFileSync(o,`utf8`)),e);if(!t)return;let a=r.default.readFileSync(i);return y(a)!==t.digest||r.default.readFileSync(n,`utf8`).trim()!==t.digest?void 0:{bytes:a,filePath:i,integrity:t.integrity,digest:t.digest,referenceBase:t.referenceBase}}catch{return}}publish(e,t,i,o,u){p(u);let d=this.read(e);if(d)return d;let f=this.entryDirectory(e);r.default.mkdirSync(this.root,{mode:448,recursive:!0}),r.default.existsSync(f)&&r.default.rmSync(f,{recursive:!0,force:!0});let m=`${f}.${process.pid}.${(0,n.randomUUID)()}.tmp`,h=y(t),g={schemaVersion:1,source:e.source,version:e.version,path:s,integrity:i,digest:h,referenceBase:o};try{r.default.mkdirSync(m,{mode:448}),r.default.writeFileSync(a.default.join(m,s),t,{mode:384}),r.default.writeFileSync(a.default.join(m,l),`${JSON.stringify(g,null,2)}\n`,{mode:384}),p(u),r.default.writeFileSync(a.default.join(m,c),`${h}\n`,{mode:384});try{r.default.renameSync(m,f)}catch(t){let n=this.read(e);if(n)return n;throw t}return{bytes:Uint8Array.from(t),filePath:a.default.join(f,s),integrity:i,digest:h,referenceBase:o}}finally{r.default.rmSync(m,{recursive:!0,force:!0})}}},C=class{cacheRoot;constructor(e=v()){this.cacheRoot=e}async materialize(e,i,o){let s=[];for(let c of e.skills){p(o);let l=y(`${i.identity.source}\0${i.identity.version}\0${c.name}\0${c.description}\0${i.digest}`),d=a.default.join(this.cacheRoot,`wrappers`,l),f=a.default.join(d,u),m=t.renderHelpSkillWrapper(c,i);if(!x(f)||r.default.readFileSync(f,`utf8`)!==m){r.default.mkdirSync(a.default.dirname(d),{mode:448,recursive:!0}),r.default.existsSync(d)&&r.default.rmSync(d,{recursive:!0,force:!0});let e=`${d}.${process.pid}.${(0,n.randomUUID)()}.tmp`;try{r.default.mkdirSync(e,{mode:448}),r.default.writeFileSync(a.default.join(e,u),m,{mode:384}),p(o);try{r.default.renameSync(e,d)}catch(e){if(!x(f)||r.default.readFileSync(f,`utf8`)!==m)throw e}}finally{r.default.rmSync(e,{recursive:!0,force:!0})}}s.push({source:e.source,name:c.name,description:c.description,filePath:f,baseDir:d})}return s}};exports.DefaultHelpSkillMaterializer=C,exports.HelpIndexCache=S,exports.defaultHelpCacheRoot=v,exports.resolveHelpPackageIdentity=_,exports.sha256Hex=y;
 //# sourceMappingURL=helpStorage.cjs.map

package/dist/adapters/helpStorage.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"helpStorage.cjs","names":["path","fs","fileURLToPath","os","createHash","randomUUID","renderHelpSkillWrapper"],"sources":["../../src/adapters/helpStorage.ts"],"sourcesContent":["import { createHash, randomUUID } from 'node:crypto';\nimport fs from 'node:fs';\nimport os from 'node:os';\nimport path from 'node:path';\nimport { fileURLToPath } from 'node:url';\nimport type { DoomHelpContribution, DoomHelpSkill } from '@agimon-ai/doompi-extension-contracts/help';\nimport { renderHelpSkillWrapper } from '../services/llmsContent.ts';\nimport type { HelpPackageIdentity, HelpSkillMaterializer, ResolvedHelpIndex } from '../types/help.ts';\n\nconst PACKAGE_MANIFEST = 'package.json';\nconst HELP_INDEX_PATH = 'llms.txt';\nconst CACHE_SCHEMA_VERSION = 1;\nconst PRIVATE_FILE_MODE = 0o600;\nconst PRIVATE_DIRECTORY_MODE = 0o700;\nconst COMPLETION_FILE = '.complete';\nconst CACHE_METADATA_FILE = 'metadata.json';\nconst WRAPPER_DIRECTORY = 'wrappers';\nconst SKILL_FILE = 'SKILL.md';\nconst EXACT_SEMVER_PATTERN =\n  /^(?:0|[1-9]\\d*)\\.(?:0|[1-9]\\d*)\\.(?:0|[1-9]\\d*)(?:-[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*)?(?:\\+[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*)?$/u;\nconst NPM_PACKAGE_NAME_PATTERN = /^(?:@[a-z0-9][a-z0-9._~-]*\\/)?[a-z0-9][a-z0-9._~-]*$/u;\n\ninterface CacheMetadata {\n  schemaVersion: typeof CACHE_SCHEMA_VERSION;\n  source: string;\n  version: string;\n  path: typeof HELP_INDEX_PATH;\n  integrity: string;\n  digest: string;\n  referenceBase: string;\n}\n\nexport interface CachedHelpIndex {\n  bytes: Uint8Array;\n  filePath: string;\n  integrity: string;\n  digest: string;\n  referenceBase: string;\n}\n\nfunction assertNotAborted(signal: AbortSignal): void {\n  if (signal.aborted) throw new Error('Help activation was cancelled.');\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === 'object' && value !== null && !Array.isArray(value);\n}\n\nfunction isContained(root: string, candidate: string): boolean {\n  const relative = path.relative(root, candidate);\n  return relative === '' || (!relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative));\n}\n\nfunction readManifest(filePath: string): Record<string, unknown> {\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(fs.readFileSync(filePath, 'utf8')) as unknown;\n  } catch (error) {\n    throw new Error(\n      `Cannot read Help package manifest at ${filePath}: ${error instanceof Error ? error.message : String(error)}`,\n    );\n  }\n  if (!isRecord(parsed)) throw new Error(`Help package manifest at ${filePath} must contain an object.`);\n  return parsed;\n}\n\nexport function resolveHelpPackageIdentity(moduleUrl: string, expectedSource: string): HelpPackageIdentity {\n  if (!NPM_PACKAGE_NAME_PATTERN.test(expectedSource)) {\n    throw new Error(`Help source '${expectedSource}' must be a valid lowercase npm package name.`);\n  }\n  let modulePath: string;\n  try {\n    const url = new URL(moduleUrl);\n    if (url.protocol !== 'file:') throw new Error(`Help module URL must use file:, received ${url.protocol}`);\n    modulePath = fs.realpathSync(fileURLToPath(url));\n  } catch (error) {\n    throw new Error(\n      `Invalid Help contributor module URL '${moduleUrl}': ${error instanceof Error ? error.message : String(error)}`,\n    );\n  }\n  if (!fs.lstatSync(modulePath).isFile())\n    throw new Error(`Help contributor module is not a regular file: ${modulePath}`);\n\n  let directory = path.dirname(modulePath);\n  while (true) {\n    const manifestPath = path.join(directory, PACKAGE_MANIFEST);\n    if (fs.existsSync(manifestPath)) {\n      const manifest = readManifest(manifestPath);\n      const source = manifest.name;\n      const version = manifest.version;\n      if (source !== expectedSource) {\n        throw new Error(`Help source '${expectedSource}' does not match nearest package '${String(source)}'.`);\n      }\n      if (typeof version !== 'string' || !EXACT_SEMVER_PATTERN.test(version)) {\n        throw new Error(`Help package '${expectedSource}' must declare an exact semantic version.`);\n      }\n      const packageRoot = fs.realpathSync(directory);\n      if (!isContained(packageRoot, modulePath))\n        throw new Error('Help contributor module escapes its resolved package root.');\n      return { source: expectedSource, version, packageRoot, modulePath };\n    }\n    const parent = path.dirname(directory);\n    if (parent === directory) break;\n    directory = parent;\n  }\n  throw new Error(`Cannot find a package manifest for Help contributor ${modulePath}.`);\n}\n\nexport function defaultHelpCacheRoot(homeDirectory = os.homedir()): string {\n  return path.join(homeDirectory, '.pi', '.doom', 'llms-cache');\n}\n\nexport function sha256Hex(bytes: Uint8Array | string): string {\n  return createHash('sha256').update(bytes).digest('hex');\n}\n\nfunction parseCacheMetadata(value: unknown, identity: HelpPackageIdentity): CacheMetadata | undefined {\n  if (!isRecord(value)) return undefined;\n  if (\n    value.schemaVersion !== CACHE_SCHEMA_VERSION ||\n    value.source !== identity.source ||\n    value.version !== identity.version ||\n    value.path !== HELP_INDEX_PATH ||\n    typeof value.integrity !== 'string' ||\n    typeof value.digest !== 'string' ||\n    typeof value.referenceBase !== 'string'\n  ) {\n    return undefined;\n  }\n  return value as unknown as CacheMetadata;\n}\n\nfunction regularFile(filePath: string): boolean {\n  try {\n    const metadata = fs.lstatSync(filePath);\n    return metadata.isFile() && !metadata.isSymbolicLink();\n  } catch {\n    return false;\n  }\n}\n\nexport class HelpIndexCache {\n  readonly root: string;\n\n  constructor(root = defaultHelpCacheRoot()) {\n    this.root = root;\n  }\n\n  entryDirectory(identity: HelpPackageIdentity): string {\n    const key = sha256Hex(`${identity.source}\\0${identity.version}\\0${HELP_INDEX_PATH}`);\n    return path.join(this.root, key);\n  }\n\n  discard(identity: HelpPackageIdentity): void {\n    fs.rmSync(this.entryDirectory(identity), { recursive: true, force: true });\n  }\n\n  read(identity: HelpPackageIdentity): CachedHelpIndex | undefined {\n    const directory = this.entryDirectory(identity);\n    const completionPath = path.join(directory, COMPLETION_FILE);\n    const indexPath = path.join(directory, HELP_INDEX_PATH);\n    const metadataPath = path.join(directory, CACHE_METADATA_FILE);\n    if (!regularFile(completionPath) || !regularFile(indexPath) || !regularFile(metadataPath)) return undefined;\n    try {\n      const metadata = parseCacheMetadata(JSON.parse(fs.readFileSync(metadataPath, 'utf8')) as unknown, identity);\n      if (!metadata) return undefined;\n      const bytes = fs.readFileSync(indexPath);\n      if (sha256Hex(bytes) !== metadata.digest) return undefined;\n      if (fs.readFileSync(completionPath, 'utf8').trim() !== metadata.digest) return undefined;\n      return {\n        bytes,\n        filePath: indexPath,\n        integrity: metadata.integrity,\n        digest: metadata.digest,\n        referenceBase: metadata.referenceBase,\n      };\n    } catch {\n      return undefined;\n    }\n  }\n\n  publish(\n    identity: HelpPackageIdentity,\n    bytes: Uint8Array,\n    integrity: string,\n    referenceBase: string,\n    signal: AbortSignal,\n  ): CachedHelpIndex {\n    assertNotAborted(signal);\n    const existing = this.read(identity);\n    if (existing) return existing;\n    const directory = this.entryDirectory(identity);\n    fs.mkdirSync(this.root, { mode: PRIVATE_DIRECTORY_MODE, recursive: true });\n    if (fs.existsSync(directory)) fs.rmSync(directory, { recursive: true, force: true });\n    const temporary = `${directory}.${process.pid}.${randomUUID()}.tmp`;\n    const digest = sha256Hex(bytes);\n    const metadata: CacheMetadata = {\n      schemaVersion: CACHE_SCHEMA_VERSION,\n      source: identity.source,\n      version: identity.version,\n      path: HELP_INDEX_PATH,\n      integrity,\n      digest,\n      referenceBase,\n    };\n    try {\n      fs.mkdirSync(temporary, { mode: PRIVATE_DIRECTORY_MODE });\n      fs.writeFileSync(path.join(temporary, HELP_INDEX_PATH), bytes, { mode: PRIVATE_FILE_MODE });\n      fs.writeFileSync(path.join(temporary, CACHE_METADATA_FILE), `${JSON.stringify(metadata, null, 2)}\\n`, {\n        mode: PRIVATE_FILE_MODE,\n      });\n      assertNotAborted(signal);\n      fs.writeFileSync(path.join(temporary, COMPLETION_FILE), `${digest}\\n`, { mode: PRIVATE_FILE_MODE });\n      try {\n        fs.renameSync(temporary, directory);\n      } catch (error) {\n        const winner = this.read(identity);\n        if (winner) return winner;\n        throw error;\n      }\n      return {\n        bytes: Uint8Array.from(bytes),\n        filePath: path.join(directory, HELP_INDEX_PATH),\n        integrity,\n        digest,\n        referenceBase,\n      };\n    } finally {\n      fs.rmSync(temporary, { recursive: true, force: true });\n    }\n  }\n}\n\nexport class DefaultHelpSkillMaterializer implements HelpSkillMaterializer {\n  constructor(private readonly cacheRoot = defaultHelpCacheRoot()) {}\n\n  async materialize(\n    contribution: DoomHelpContribution,\n    index: ResolvedHelpIndex,\n    signal: AbortSignal,\n  ): Promise<readonly DoomHelpSkill[]> {\n    const skills: DoomHelpSkill[] = [];\n    for (const descriptor of contribution.skills) {\n      assertNotAborted(signal);\n      const key = sha256Hex(\n        `${index.identity.source}\\0${index.identity.version}\\0${descriptor.name}\\0${descriptor.description}\\0${index.digest}`,\n      );\n      const directory = path.join(this.cacheRoot, WRAPPER_DIRECTORY, key);\n      const filePath = path.join(directory, SKILL_FILE);\n      const content = renderHelpSkillWrapper(descriptor, index);\n      if (!regularFile(filePath) || fs.readFileSync(filePath, 'utf8') !== content) {\n        fs.mkdirSync(path.dirname(directory), { mode: PRIVATE_DIRECTORY_MODE, recursive: true });\n        if (fs.existsSync(directory)) fs.rmSync(directory, { recursive: true, force: true });\n        const temporary = `${directory}.${process.pid}.${randomUUID()}.tmp`;\n        try {\n          fs.mkdirSync(temporary, { mode: PRIVATE_DIRECTORY_MODE });\n          fs.writeFileSync(path.join(temporary, SKILL_FILE), content, { mode: PRIVATE_FILE_MODE });\n          assertNotAborted(signal);\n          try {\n            fs.renameSync(temporary, directory);\n          } catch (error) {\n            if (!regularFile(filePath) || fs.readFileSync(filePath, 'utf8') !== content) throw error;\n          }\n        } finally {\n          fs.rmSync(temporary, { recursive: true, force: true });\n        }\n      }\n      skills.push({\n        source: contribution.source,\n        name: descriptor.name,\n        description: descriptor.description,\n        filePath,\n        baseDir: directory,\n      });\n    }\n    return skills;\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"helpStorage.cjs","names":["path","fs","fileURLToPath","os","createHash","randomUUID","renderHelpSkillWrapper"],"sources":["../../src/adapters/helpStorage.ts"],"sourcesContent":["import { createHash, randomUUID } from 'node:crypto';\nimport fs from 'node:fs';\nimport os from 'node:os';\nimport path from 'node:path';\nimport { fileURLToPath } from 'node:url';\nimport type { DoomHelpContribution, DoomHelpSkill } from '@agimon-ai/doompi-extension-contracts/help';\nimport { renderHelpSkillWrapper } from '../services/llmsContent.ts';\nimport type { HelpPackageIdentity, HelpSkillMaterializer, ResolvedHelpIndex } from '../types/help.ts';\n\nconst PACKAGE_MANIFEST = 'package.json';\nconst HELP_INDEX_PATH = 'llms.txt';\nconst CACHE_SCHEMA_VERSION = 1;\nconst PRIVATE_FILE_MODE = 0o600;\nconst PRIVATE_DIRECTORY_MODE = 0o700;\nconst COMPLETION_FILE = '.complete';\nconst CACHE_METADATA_FILE = 'metadata.json';\nconst WRAPPER_DIRECTORY = 'wrappers';\nconst SKILL_FILE = 'SKILL.md';\nconst EXACT_SEMVER_PATTERN =\n  /^(?:0|[1-9]\\d*)\\.(?:0|[1-9]\\d*)\\.(?:0|[1-9]\\d*)(?:-[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*)?(?:\\+[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*)?$/u;\nconst NPM_PACKAGE_NAME_PATTERN = /^(?:@[a-z0-9][a-z0-9._~-]*\\/)?[a-z0-9][a-z0-9._~-]*$/u;\n\ninterface CacheMetadata {\n  schemaVersion: typeof CACHE_SCHEMA_VERSION;\n  source: string;\n  version: string;\n  path: typeof HELP_INDEX_PATH;\n  integrity: string;\n  digest: string;\n  referenceBase: string;\n}\n\nexport interface CachedHelpIndex {\n  bytes: Uint8Array;\n  filePath: string;\n  integrity: string;\n  digest: string;\n  referenceBase: string;\n}\n\nfunction assertNotAborted(signal: AbortSignal): void {\n  if (signal.aborted) throw new Error('Help activation was cancelled.');\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === 'object' && value !== null && !Array.isArray(value);\n}\n\nfunction isContained(root: string, candidate: string): boolean {\n  const relative = path.relative(root, candidate);\n  return relative === '' || (!relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative));\n}\n\nfunction readManifest(filePath: string): Record<string, unknown> {\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(fs.readFileSync(filePath, 'utf8')) as unknown;\n  } catch (error) {\n    throw new Error(\n      `Cannot read Help package manifest at ${filePath}: ${error instanceof Error ? error.message : String(error)}`,\n    );\n  }\n  if (!isRecord(parsed)) throw new Error(`Help package manifest at ${filePath} must contain an object.`);\n  return parsed;\n}\n\nexport function resolveHelpPackageIdentity(moduleUrl: string, expectedSource: string): HelpPackageIdentity {\n  if (!NPM_PACKAGE_NAME_PATTERN.test(expectedSource)) {\n    throw new Error(`Help source '${expectedSource}' must be a valid lowercase npm package name.`);\n  }\n  let modulePath: string;\n  try {\n    const url = new URL(moduleUrl);\n    if (url.protocol !== 'file:') throw new Error(`Help module URL must use file:, received ${url.protocol}`);\n    modulePath = fs.realpathSync(fileURLToPath(url));\n  } catch (error) {\n    throw new Error(\n      `Invalid Help contributor module URL '${moduleUrl}': ${error instanceof Error ? error.message : String(error)}`,\n    );\n  }\n  if (!fs.lstatSync(modulePath).isFile())\n    throw new Error(`Help contributor module is not a regular file: ${modulePath}`);\n\n  let directory = path.dirname(modulePath);\n  while (true) {\n    const manifestPath = path.join(directory, PACKAGE_MANIFEST);\n    if (fs.existsSync(manifestPath)) {\n      const manifest = readManifest(manifestPath);\n      const source = manifest.name;\n      const version = manifest.version;\n      if (source !== expectedSource) {\n        throw new Error(`Help source '${expectedSource}' does not match nearest package '${String(source)}'.`);\n      }\n      if (typeof version !== 'string' || !EXACT_SEMVER_PATTERN.test(version)) {\n        throw new Error(`Help package '${expectedSource}' must declare an exact semantic version.`);\n      }\n      const packageRoot = fs.realpathSync(directory);\n      if (!isContained(packageRoot, modulePath))\n        throw new Error('Help contributor module escapes its resolved package root.');\n      return { source: expectedSource, version, packageRoot, modulePath };\n    }\n    const parent = path.dirname(directory);\n    if (parent === directory) break;\n    directory = parent;\n  }\n  throw new Error(`Cannot find a package manifest for Help contributor ${modulePath}.`);\n}\n\nexport function defaultHelpCacheRoot(homeDirectory = os.homedir()): string {\n  return path.join(homeDirectory, '.pi', '.doom', 'llms-cache');\n}\n\nexport function sha256Hex(bytes: Uint8Array | string): string {\n  return createHash('sha256').update(bytes).digest('hex');\n}\n\nfunction parseCacheMetadata(value: unknown, identity: HelpPackageIdentity): CacheMetadata | undefined {\n  if (!isRecord(value)) return undefined;\n  if (\n    value.schemaVersion !== CACHE_SCHEMA_VERSION ||\n    value.source !== identity.source ||\n    value.version !== identity.version ||\n    value.path !== HELP_INDEX_PATH ||\n    typeof value.integrity !== 'string' ||\n    typeof value.digest !== 'string' ||\n    typeof value.referenceBase !== 'string'\n  ) {\n    return undefined;\n  }\n  return value as unknown as CacheMetadata;\n}\n\nfunction regularFile(filePath: string): boolean {\n  try {\n    const metadata = fs.lstatSync(filePath);\n    return metadata.isFile() && !metadata.isSymbolicLink();\n  } catch {\n    return false;\n  }\n}\n\nexport class HelpIndexCache {\n  readonly root: string;\n\n  constructor(root = defaultHelpCacheRoot()) {\n    this.root = root;\n  }\n\n  entryDirectory(identity: HelpPackageIdentity): string {\n    const key = sha256Hex(`${identity.source}\\0${identity.version}\\0${HELP_INDEX_PATH}`);\n    return path.join(this.root, key);\n  }\n\n  discard(identity: HelpPackageIdentity): void {\n    fs.rmSync(this.entryDirectory(identity), { recursive: true, force: true });\n  }\n\n  read(identity: HelpPackageIdentity): CachedHelpIndex | undefined {\n    const directory = this.entryDirectory(identity);\n    const completionPath = path.join(directory, COMPLETION_FILE);\n    const indexPath = path.join(directory, HELP_INDEX_PATH);\n    const metadataPath = path.join(directory, CACHE_METADATA_FILE);\n    if (!regularFile(completionPath) || !regularFile(indexPath) || !regularFile(metadataPath)) return undefined;\n    try {\n      const metadata = parseCacheMetadata(JSON.parse(fs.readFileSync(metadataPath, 'utf8')) as unknown, identity);\n      if (!metadata) return undefined;\n      const bytes = fs.readFileSync(indexPath);\n      if (sha256Hex(bytes) !== metadata.digest) return undefined;\n      if (fs.readFileSync(completionPath, 'utf8').trim() !== metadata.digest) return undefined;\n      return {\n        bytes,\n        filePath: indexPath,\n        integrity: metadata.integrity,\n        digest: metadata.digest,\n        referenceBase: metadata.referenceBase,\n      };\n    } catch {\n      return undefined;\n    }\n  }\n\n  publish(\n    identity: HelpPackageIdentity,\n    bytes: Uint8Array,\n    integrity: string,\n    referenceBase: string,\n    signal: AbortSignal,\n  ): CachedHelpIndex {\n    assertNotAborted(signal);\n    const existing = this.read(identity);\n    if (existing) return existing;\n    const directory = this.entryDirectory(identity);\n    fs.mkdirSync(this.root, { mode: PRIVATE_DIRECTORY_MODE, recursive: true });\n    if (fs.existsSync(directory)) fs.rmSync(directory, { recursive: true, force: true });\n    const temporary = `${directory}.${process.pid}.${randomUUID()}.tmp`;\n    const digest = sha256Hex(bytes);\n    const metadata: CacheMetadata = {\n      schemaVersion: CACHE_SCHEMA_VERSION,\n      source: identity.source,\n      version: identity.version,\n      path: HELP_INDEX_PATH,\n      integrity,\n      digest,\n      referenceBase,\n    };\n    try {\n      fs.mkdirSync(temporary, { mode: PRIVATE_DIRECTORY_MODE });\n      fs.writeFileSync(path.join(temporary, HELP_INDEX_PATH), bytes, { mode: PRIVATE_FILE_MODE });\n      fs.writeFileSync(path.join(temporary, CACHE_METADATA_FILE), `${JSON.stringify(metadata, null, 2)}\\n`, {\n        mode: PRIVATE_FILE_MODE,\n      });\n      assertNotAborted(signal);\n      fs.writeFileSync(path.join(temporary, COMPLETION_FILE), `${digest}\\n`, { mode: PRIVATE_FILE_MODE });\n      try {\n        fs.renameSync(temporary, directory);\n      } catch (error) {\n        const winner = this.read(identity);\n        if (winner) return winner;\n        throw error;\n      }\n      return {\n        bytes: Uint8Array.from(bytes),\n        filePath: path.join(directory, HELP_INDEX_PATH),\n        integrity,\n        digest,\n        referenceBase,\n      };\n    } finally {\n      fs.rmSync(temporary, { recursive: true, force: true });\n    }\n  }\n}\n\nexport class DefaultHelpSkillMaterializer implements HelpSkillMaterializer {\n  constructor(private readonly cacheRoot = defaultHelpCacheRoot()) {}\n\n  async materialize(\n    contribution: DoomHelpContribution,\n    index: ResolvedHelpIndex,\n    signal: AbortSignal,\n  ): Promise<readonly DoomHelpSkill[]> {\n    const skills: DoomHelpSkill[] = [];\n    for (const descriptor of contribution.skills) {\n      assertNotAborted(signal);\n      const key = sha256Hex(\n        `${index.identity.source}\\0${index.identity.version}\\0${descriptor.name}\\0${descriptor.description}\\0${index.digest}`,\n      );\n      const directory = path.join(this.cacheRoot, WRAPPER_DIRECTORY, key);\n      const filePath = path.join(directory, SKILL_FILE);\n      const content = renderHelpSkillWrapper(descriptor, index);\n      if (!regularFile(filePath) || fs.readFileSync(filePath, 'utf8') !== content) {\n        fs.mkdirSync(path.dirname(directory), { mode: PRIVATE_DIRECTORY_MODE, recursive: true });\n        if (fs.existsSync(directory)) fs.rmSync(directory, { recursive: true, force: true });\n        const temporary = `${directory}.${process.pid}.${randomUUID()}.tmp`;\n        try {\n          fs.mkdirSync(temporary, { mode: PRIVATE_DIRECTORY_MODE });\n          fs.writeFileSync(path.join(temporary, SKILL_FILE), content, { mode: PRIVATE_FILE_MODE });\n          assertNotAborted(signal);\n          try {\n            fs.renameSync(temporary, directory);\n          } catch (error) {\n            if (!regularFile(filePath) || fs.readFileSync(filePath, 'utf8') !== content) throw error;\n          }\n        } finally {\n          fs.rmSync(temporary, { recursive: true, force: true });\n        }\n      }\n      skills.push({\n        source: contribution.source,\n        name: descriptor.name,\n        description: descriptor.description,\n        filePath,\n        baseDir: directory,\n      });\n    }\n    return skills;\n  }\n}\n"],"mappings":"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"}

package/dist/adapters/helpStorage.mjs

@@ -1,2 +1,2 @@
-import{renderHelpSkillWrapper as e}from"../services/llmsContent.mjs";import{createHash as t,randomUUID as n}from"node:crypto";import r from"node:fs";import i from"node:os";import a from"node:path";import{fileURLToPath as o}from"node:url";const s=`llms.txt`,c=`.complete`,l=`metadata.json`,u=`SKILL.md`,d=/^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/u,f=/^(?:@[a-z0-9][a-z0-9._~-]*\/)?[a-z0-9][a-z0-9._~-]*$/u;function p(e){if(e.aborted)throw Error(`Help activation was cancelled.`)}function m(e){return typeof e==`object`&&!!e&&!Array.isArray(e)}function h(e,t){let n=a.relative(e,t);return n===``||!n.startsWith(`..${a.sep}`)&&n!==`..`&&!a.isAbsolute(n)}function g(e){let t;try{t=JSON.parse(r.readFileSync(e,`utf8`))}catch(t){throw Error(`Cannot read Help package manifest at ${e}: ${t instanceof Error?t.message:String(t)}`)}if(!m(t))throw Error(`Help package manifest at ${e} must contain an object.`);return t}function _(e,t){if(!f.test(t))throw Error(`Help source '${t}' must be a valid lowercase npm package name.`);let n;try{let t=new URL(e);if(t.protocol!==`file:`)throw Error(`Help module URL must use file:, received ${t.protocol}`);n=r.realpathSync(o(t))}catch(t){throw Error(`Invalid Help contributor module URL '${e}': ${t instanceof Error?t.message:String(t)}`)}if(!r.lstatSync(n).isFile())throw Error(`Help contributor module is not a regular file: ${n}`);let i=a.dirname(n);for(;;){let e=a.join(i,`package.json`);if(r.existsSync(e)){let a=g(e),o=a.name,s=a.version;if(o!==t)throw Error(`Help source '${t}' does not match nearest package '${String(o)}'.`);if(typeof s!=`string`||!d.test(s))throw Error(`Help package '${t}' must declare an exact semantic version.`);let c=r.realpathSync(i);if(!h(c,n))throw Error(`Help contributor module escapes its resolved package root.`);return{source:t,version:s,packageRoot:c,modulePath:n}}let o=a.dirname(i);if(o===i)break;i=o}throw Error(`Cannot find a package manifest for Help contributor ${n}.`)}function v(e=i.homedir()){return a.join(e,`.pi`,`.doom`,`llms-cache`)}function y(e){return t(`sha256`).update(e).digest(`hex`)}function b(e,t){if(m(e)&&e.schemaVersion===1&&e.source===t.source&&e.version===t.version&&e.path===s&&typeof e.integrity==`string`&&typeof e.digest==`string`&&typeof e.referenceBase==`string`)return e}function x(e){try{let t=r.lstatSync(e);return t.isFile()&&!t.isSymbolicLink()}catch{return!1}}var S=class{root;constructor(e=v()){this.root=e}entryDirectory(e){let t=y(`${e.source}\0${e.version}\0${s}`);return a.join(this.root,t)}discard(e){r.rmSync(this.entryDirectory(e),{recursive:!0,force:!0})}read(e){let t=this.entryDirectory(e),n=a.join(t,c),i=a.join(t,s),o=a.join(t,l);if(!(!x(n)||!x(i)||!x(o)))try{let t=b(JSON.parse(r.readFileSync(o,`utf8`)),e);if(!t)return;let a=r.readFileSync(i);return y(a)!==t.digest||r.readFileSync(n,`utf8`).trim()!==t.digest?void 0:{bytes:a,filePath:i,integrity:t.integrity,digest:t.digest,referenceBase:t.referenceBase}}catch{return}}publish(e,t,i,o,u){p(u);let d=this.read(e);if(d)return d;let f=this.entryDirectory(e);r.mkdirSync(this.root,{mode:448,recursive:!0}),r.existsSync(f)&&r.rmSync(f,{recursive:!0,force:!0});let m=`${f}.${process.pid}.${n()}.tmp`,h=y(t),g={schemaVersion:1,source:e.source,version:e.version,path:s,integrity:i,digest:h,referenceBase:o};try{r.mkdirSync(m,{mode:448}),r.writeFileSync(a.join(m,s),t,{mode:384}),r.writeFileSync(a.join(m,l),`${JSON.stringify(g,null,2)}\n`,{mode:384}),p(u),r.writeFileSync(a.join(m,c),`${h}\n`,{mode:384});try{r.renameSync(m,f)}catch(t){let n=this.read(e);if(n)return n;throw t}return{bytes:Uint8Array.from(t),filePath:a.join(f,s),integrity:i,digest:h,referenceBase:o}}finally{r.rmSync(m,{recursive:!0,force:!0})}}},C=class{cacheRoot;constructor(e=v()){this.cacheRoot=e}async materialize(t,i,o){let s=[];for(let c of t.skills){p(o);let l=y(`${i.identity.source}\0${i.identity.version}\0${c.name}\0${c.description}\0${i.digest}`),d=a.join(this.cacheRoot,`wrappers`,l),f=a.join(d,u),m=e(c,i);if(!x(f)||r.readFileSync(f,`utf8`)!==m){r.mkdirSync(a.dirname(d),{mode:448,recursive:!0}),r.existsSync(d)&&r.rmSync(d,{recursive:!0,force:!0});let e=`${d}.${process.pid}.${n()}.tmp`;try{r.mkdirSync(e,{mode:448}),r.writeFileSync(a.join(e,u),m,{mode:384}),p(o);try{r.renameSync(e,d)}catch(e){if(!x(f)||r.readFileSync(f,`utf8`)!==m)throw e}}finally{r.rmSync(e,{recursive:!0,force:!0})}}s.push({source:t.source,name:c.name,description:c.description,filePath:f,baseDir:d})}return s}};export{C as DefaultHelpSkillMaterializer,S as HelpIndexCache,v as defaultHelpCacheRoot,_ as resolveHelpPackageIdentity,y as sha256Hex};
+import{renderHelpSkillWrapper as e}from"../services/llmsContent.mjs";import{createHash as t,randomUUID as n}from"node:crypto";import r from"node:fs";import i from"node:os";import a from"node:path";import{fileURLToPath as o}from"node:url";const s=`llms.txt`,c=`.complete`,l=`metadata.json`,u=`SKILL.md`,d=/^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/u,f=/^(?:@[a-z0-9][a-z0-9._~-]*\/)?[a-z0-9][a-z0-9._~-]*$/u;function p(e){if(e.aborted)throw Error(`Help activation was cancelled.`)}function m(e){return typeof e==`object`&&!!e&&!Array.isArray(e)}function h(e,t){let n=a.relative(e,t);return n===``||!n.startsWith(`..${a.sep}`)&&n!==`..`&&!a.isAbsolute(n)}function g(e){let t;try{t=JSON.parse(r.readFileSync(e,`utf8`))}catch(t){throw Error(`Cannot read Help package manifest at ${e}: ${t instanceof Error?t.message:String(t)}`)}if(!m(t))throw Error(`Help package manifest at ${e} must contain an object.`);return t}function _(e,t){if(!f.test(t))throw Error(`Help source '${t}' must be a valid lowercase npm package name.`);let n;try{let t=new URL(e);if(t.protocol!==`file:`)throw Error(`Help module URL must use file:, received ${t.protocol}`);n=r.realpathSync(o(t))}catch(t){throw Error(`Invalid Help contributor module URL '${e}': ${t instanceof Error?t.message:String(t)}`)}if(!r.lstatSync(n).isFile())throw Error(`Help contributor module is not a regular file: ${n}`);let i=a.dirname(n);for(;;){let e=a.join(i,`package.json`);if(r.existsSync(e)){let a=g(e),o=a.name,s=a.version;if(o!==t)throw Error(`Help source '${t}' does not match nearest package '${String(o)}'.`);if(typeof s!=`string`||!d.test(s))throw Error(`Help package '${t}' must declare an exact semantic version.`);let c=r.realpathSync(i);if(!h(c,n))throw Error(`Help contributor module escapes its resolved package root.`);return{source:t,version:s,packageRoot:c,modulePath:n}}let o=a.dirname(i);if(o===i)break;i=o}throw Error(`Cannot find a package manifest for Help contributor ${n}.`)}function v(e=i.homedir()){return a.join(e,`.pi`,`.doom`,`llms-cache`)}function y(e){return t(`sha256`).update(e).digest(`hex`)}function b(e,t){if(m(e)&&e.schemaVersion===1&&e.source===t.source&&e.version===t.version&&e.path===s&&typeof e.integrity==`string`&&typeof e.digest==`string`&&typeof e.referenceBase==`string`)return e}function x(e){try{let t=r.lstatSync(e);return t.isFile()&&!t.isSymbolicLink()}catch{return!1}}var S=class{root;constructor(e=v()){this.root=e}entryDirectory(e){let t=y(`${e.source}\0${e.version}\0${s}`);return a.join(this.root,t)}discard(e){r.rmSync(this.entryDirectory(e),{recursive:!0,force:!0})}read(e){let t=this.entryDirectory(e),n=a.join(t,c),i=a.join(t,s),o=a.join(t,l);if(x(n)&&x(i)&&x(o))try{let t=b(JSON.parse(r.readFileSync(o,`utf8`)),e);if(!t)return;let a=r.readFileSync(i);return y(a)!==t.digest||r.readFileSync(n,`utf8`).trim()!==t.digest?void 0:{bytes:a,filePath:i,integrity:t.integrity,digest:t.digest,referenceBase:t.referenceBase}}catch{return}}publish(e,t,i,o,u){p(u);let d=this.read(e);if(d)return d;let f=this.entryDirectory(e);r.mkdirSync(this.root,{mode:448,recursive:!0}),r.existsSync(f)&&r.rmSync(f,{recursive:!0,force:!0});let m=`${f}.${process.pid}.${n()}.tmp`,h=y(t),g={schemaVersion:1,source:e.source,version:e.version,path:s,integrity:i,digest:h,referenceBase:o};try{r.mkdirSync(m,{mode:448}),r.writeFileSync(a.join(m,s),t,{mode:384}),r.writeFileSync(a.join(m,l),`${JSON.stringify(g,null,2)}\n`,{mode:384}),p(u),r.writeFileSync(a.join(m,c),`${h}\n`,{mode:384});try{r.renameSync(m,f)}catch(t){let n=this.read(e);if(n)return n;throw t}return{bytes:Uint8Array.from(t),filePath:a.join(f,s),integrity:i,digest:h,referenceBase:o}}finally{r.rmSync(m,{recursive:!0,force:!0})}}},C=class{cacheRoot;constructor(e=v()){this.cacheRoot=e}async materialize(t,i,o){let s=[];for(let c of t.skills){p(o);let l=y(`${i.identity.source}\0${i.identity.version}\0${c.name}\0${c.description}\0${i.digest}`),d=a.join(this.cacheRoot,`wrappers`,l),f=a.join(d,u),m=e(c,i);if(!x(f)||r.readFileSync(f,`utf8`)!==m){r.mkdirSync(a.dirname(d),{mode:448,recursive:!0}),r.existsSync(d)&&r.rmSync(d,{recursive:!0,force:!0});let e=`${d}.${process.pid}.${n()}.tmp`;try{r.mkdirSync(e,{mode:448}),r.writeFileSync(a.join(e,u),m,{mode:384}),p(o);try{r.renameSync(e,d)}catch(e){if(!x(f)||r.readFileSync(f,`utf8`)!==m)throw e}}finally{r.rmSync(e,{recursive:!0,force:!0})}}s.push({source:t.source,name:c.name,description:c.description,filePath:f,baseDir:d})}return s}};export{C as DefaultHelpSkillMaterializer,S as HelpIndexCache,v as defaultHelpCacheRoot,_ as resolveHelpPackageIdentity,y as sha256Hex};
 //# sourceMappingURL=helpStorage.mjs.map

package/dist/adapters/helpStorage.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"helpStorage.mjs","names":[],"sources":["../../src/adapters/helpStorage.ts"],"sourcesContent":["import { createHash, randomUUID } from 'node:crypto';\nimport fs from 'node:fs';\nimport os from 'node:os';\nimport path from 'node:path';\nimport { fileURLToPath } from 'node:url';\nimport type { DoomHelpContribution, DoomHelpSkill } from '@agimon-ai/doompi-extension-contracts/help';\nimport { renderHelpSkillWrapper } from '../services/llmsContent.ts';\nimport type { HelpPackageIdentity, HelpSkillMaterializer, ResolvedHelpIndex } from '../types/help.ts';\n\nconst PACKAGE_MANIFEST = 'package.json';\nconst HELP_INDEX_PATH = 'llms.txt';\nconst CACHE_SCHEMA_VERSION = 1;\nconst PRIVATE_FILE_MODE = 0o600;\nconst PRIVATE_DIRECTORY_MODE = 0o700;\nconst COMPLETION_FILE = '.complete';\nconst CACHE_METADATA_FILE = 'metadata.json';\nconst WRAPPER_DIRECTORY = 'wrappers';\nconst SKILL_FILE = 'SKILL.md';\nconst EXACT_SEMVER_PATTERN =\n  /^(?:0|[1-9]\\d*)\\.(?:0|[1-9]\\d*)\\.(?:0|[1-9]\\d*)(?:-[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*)?(?:\\+[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*)?$/u;\nconst NPM_PACKAGE_NAME_PATTERN = /^(?:@[a-z0-9][a-z0-9._~-]*\\/)?[a-z0-9][a-z0-9._~-]*$/u;\n\ninterface CacheMetadata {\n  schemaVersion: typeof CACHE_SCHEMA_VERSION;\n  source: string;\n  version: string;\n  path: typeof HELP_INDEX_PATH;\n  integrity: string;\n  digest: string;\n  referenceBase: string;\n}\n\nexport interface CachedHelpIndex {\n  bytes: Uint8Array;\n  filePath: string;\n  integrity: string;\n  digest: string;\n  referenceBase: string;\n}\n\nfunction assertNotAborted(signal: AbortSignal): void {\n  if (signal.aborted) throw new Error('Help activation was cancelled.');\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === 'object' && value !== null && !Array.isArray(value);\n}\n\nfunction isContained(root: string, candidate: string): boolean {\n  const relative = path.relative(root, candidate);\n  return relative === '' || (!relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative));\n}\n\nfunction readManifest(filePath: string): Record<string, unknown> {\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(fs.readFileSync(filePath, 'utf8')) as unknown;\n  } catch (error) {\n    throw new Error(\n      `Cannot read Help package manifest at ${filePath}: ${error instanceof Error ? error.message : String(error)}`,\n    );\n  }\n  if (!isRecord(parsed)) throw new Error(`Help package manifest at ${filePath} must contain an object.`);\n  return parsed;\n}\n\nexport function resolveHelpPackageIdentity(moduleUrl: string, expectedSource: string): HelpPackageIdentity {\n  if (!NPM_PACKAGE_NAME_PATTERN.test(expectedSource)) {\n    throw new Error(`Help source '${expectedSource}' must be a valid lowercase npm package name.`);\n  }\n  let modulePath: string;\n  try {\n    const url = new URL(moduleUrl);\n    if (url.protocol !== 'file:') throw new Error(`Help module URL must use file:, received ${url.protocol}`);\n    modulePath = fs.realpathSync(fileURLToPath(url));\n  } catch (error) {\n    throw new Error(\n      `Invalid Help contributor module URL '${moduleUrl}': ${error instanceof Error ? error.message : String(error)}`,\n    );\n  }\n  if (!fs.lstatSync(modulePath).isFile())\n    throw new Error(`Help contributor module is not a regular file: ${modulePath}`);\n\n  let directory = path.dirname(modulePath);\n  while (true) {\n    const manifestPath = path.join(directory, PACKAGE_MANIFEST);\n    if (fs.existsSync(manifestPath)) {\n      const manifest = readManifest(manifestPath);\n      const source = manifest.name;\n      const version = manifest.version;\n      if (source !== expectedSource) {\n        throw new Error(`Help source '${expectedSource}' does not match nearest package '${String(source)}'.`);\n      }\n      if (typeof version !== 'string' || !EXACT_SEMVER_PATTERN.test(version)) {\n        throw new Error(`Help package '${expectedSource}' must declare an exact semantic version.`);\n      }\n      const packageRoot = fs.realpathSync(directory);\n      if (!isContained(packageRoot, modulePath))\n        throw new Error('Help contributor module escapes its resolved package root.');\n      return { source: expectedSource, version, packageRoot, modulePath };\n    }\n    const parent = path.dirname(directory);\n    if (parent === directory) break;\n    directory = parent;\n  }\n  throw new Error(`Cannot find a package manifest for Help contributor ${modulePath}.`);\n}\n\nexport function defaultHelpCacheRoot(homeDirectory = os.homedir()): string {\n  return path.join(homeDirectory, '.pi', '.doom', 'llms-cache');\n}\n\nexport function sha256Hex(bytes: Uint8Array | string): string {\n  return createHash('sha256').update(bytes).digest('hex');\n}\n\nfunction parseCacheMetadata(value: unknown, identity: HelpPackageIdentity): CacheMetadata | undefined {\n  if (!isRecord(value)) return undefined;\n  if (\n    value.schemaVersion !== CACHE_SCHEMA_VERSION ||\n    value.source !== identity.source ||\n    value.version !== identity.version ||\n    value.path !== HELP_INDEX_PATH ||\n    typeof value.integrity !== 'string' ||\n    typeof value.digest !== 'string' ||\n    typeof value.referenceBase !== 'string'\n  ) {\n    return undefined;\n  }\n  return value as unknown as CacheMetadata;\n}\n\nfunction regularFile(filePath: string): boolean {\n  try {\n    const metadata = fs.lstatSync(filePath);\n    return metadata.isFile() && !metadata.isSymbolicLink();\n  } catch {\n    return false;\n  }\n}\n\nexport class HelpIndexCache {\n  readonly root: string;\n\n  constructor(root = defaultHelpCacheRoot()) {\n    this.root = root;\n  }\n\n  entryDirectory(identity: HelpPackageIdentity): string {\n    const key = sha256Hex(`${identity.source}\\0${identity.version}\\0${HELP_INDEX_PATH}`);\n    return path.join(this.root, key);\n  }\n\n  discard(identity: HelpPackageIdentity): void {\n    fs.rmSync(this.entryDirectory(identity), { recursive: true, force: true });\n  }\n\n  read(identity: HelpPackageIdentity): CachedHelpIndex | undefined {\n    const directory = this.entryDirectory(identity);\n    const completionPath = path.join(directory, COMPLETION_FILE);\n    const indexPath = path.join(directory, HELP_INDEX_PATH);\n    const metadataPath = path.join(directory, CACHE_METADATA_FILE);\n    if (!regularFile(completionPath) || !regularFile(indexPath) || !regularFile(metadataPath)) return undefined;\n    try {\n      const metadata = parseCacheMetadata(JSON.parse(fs.readFileSync(metadataPath, 'utf8')) as unknown, identity);\n      if (!metadata) return undefined;\n      const bytes = fs.readFileSync(indexPath);\n      if (sha256Hex(bytes) !== metadata.digest) return undefined;\n      if (fs.readFileSync(completionPath, 'utf8').trim() !== metadata.digest) return undefined;\n      return {\n        bytes,\n        filePath: indexPath,\n        integrity: metadata.integrity,\n        digest: metadata.digest,\n        referenceBase: metadata.referenceBase,\n      };\n    } catch {\n      return undefined;\n    }\n  }\n\n  publish(\n    identity: HelpPackageIdentity,\n    bytes: Uint8Array,\n    integrity: string,\n    referenceBase: string,\n    signal: AbortSignal,\n  ): CachedHelpIndex {\n    assertNotAborted(signal);\n    const existing = this.read(identity);\n    if (existing) return existing;\n    const directory = this.entryDirectory(identity);\n    fs.mkdirSync(this.root, { mode: PRIVATE_DIRECTORY_MODE, recursive: true });\n    if (fs.existsSync(directory)) fs.rmSync(directory, { recursive: true, force: true });\n    const temporary = `${directory}.${process.pid}.${randomUUID()}.tmp`;\n    const digest = sha256Hex(bytes);\n    const metadata: CacheMetadata = {\n      schemaVersion: CACHE_SCHEMA_VERSION,\n      source: identity.source,\n      version: identity.version,\n      path: HELP_INDEX_PATH,\n      integrity,\n      digest,\n      referenceBase,\n    };\n    try {\n      fs.mkdirSync(temporary, { mode: PRIVATE_DIRECTORY_MODE });\n      fs.writeFileSync(path.join(temporary, HELP_INDEX_PATH), bytes, { mode: PRIVATE_FILE_MODE });\n      fs.writeFileSync(path.join(temporary, CACHE_METADATA_FILE), `${JSON.stringify(metadata, null, 2)}\\n`, {\n        mode: PRIVATE_FILE_MODE,\n      });\n      assertNotAborted(signal);\n      fs.writeFileSync(path.join(temporary, COMPLETION_FILE), `${digest}\\n`, { mode: PRIVATE_FILE_MODE });\n      try {\n        fs.renameSync(temporary, directory);\n      } catch (error) {\n        const winner = this.read(identity);\n        if (winner) return winner;\n        throw error;\n      }\n      return {\n        bytes: Uint8Array.from(bytes),\n        filePath: path.join(directory, HELP_INDEX_PATH),\n        integrity,\n        digest,\n        referenceBase,\n      };\n    } finally {\n      fs.rmSync(temporary, { recursive: true, force: true });\n    }\n  }\n}\n\nexport class DefaultHelpSkillMaterializer implements HelpSkillMaterializer {\n  constructor(private readonly cacheRoot = defaultHelpCacheRoot()) {}\n\n  async materialize(\n    contribution: DoomHelpContribution,\n    index: ResolvedHelpIndex,\n    signal: AbortSignal,\n  ): Promise<readonly DoomHelpSkill[]> {\n    const skills: DoomHelpSkill[] = [];\n    for (const descriptor of contribution.skills) {\n      assertNotAborted(signal);\n      const key = sha256Hex(\n        `${index.identity.source}\\0${index.identity.version}\\0${descriptor.name}\\0${descriptor.description}\\0${index.digest}`,\n      );\n      const directory = path.join(this.cacheRoot, WRAPPER_DIRECTORY, key);\n      const filePath = path.join(directory, SKILL_FILE);\n      const content = renderHelpSkillWrapper(descriptor, index);\n      if (!regularFile(filePath) || fs.readFileSync(filePath, 'utf8') !== content) {\n        fs.mkdirSync(path.dirname(directory), { mode: PRIVATE_DIRECTORY_MODE, recursive: true });\n        if (fs.existsSync(directory)) fs.rmSync(directory, { recursive: true, force: true });\n        const temporary = `${directory}.${process.pid}.${randomUUID()}.tmp`;\n        try {\n          fs.mkdirSync(temporary, { mode: PRIVATE_DIRECTORY_MODE });\n          fs.writeFileSync(path.join(temporary, SKILL_FILE), content, { mode: PRIVATE_FILE_MODE });\n          assertNotAborted(signal);\n          try {\n            fs.renameSync(temporary, directory);\n          } catch (error) {\n            if (!regularFile(filePath) || fs.readFileSync(filePath, 'utf8') !== content) throw error;\n          }\n        } finally {\n          fs.rmSync(temporary, { recursive: true, force: true });\n        }\n      }\n      skills.push({\n        source: contribution.source,\n        name: descriptor.name,\n        description: descriptor.description,\n        filePath,\n        baseDir: directory,\n      });\n    }\n    return skills;\n  }\n}\n"],"mappings":"8OASA,MACM,EAAkB,WAIlB,EAAkB,YAClB,EAAsB,gBAEtB,EAAa,WACb,EACJ,mIACI,EAA2B,wDAoBjC,SAAS,EAAiB,EAA2B,CACnD,GAAI,EAAO,QAAS,MAAU,MAAM,gCAAgC,CACtE,CAEA,SAAS,EAAS,EAAkD,CAClE,OAAO,OAAO,GAAU,YAAY,GAAkB,CAAC,MAAM,QAAQ,CAAK,CAC5E,CAEA,SAAS,EAAY,EAAc,EAA4B,CAC7D,IAAM,EAAW,EAAK,SAAS,EAAM,CAAS,EAC9C,OAAO,IAAa,IAAO,CAAC,EAAS,WAAW,KAAK,EAAK,KAAK,GAAK,IAAa,MAAQ,CAAC,EAAK,WAAW,CAAQ,CACpH,CAEA,SAAS,EAAa,EAA2C,CAC/D,IAAI,EACJ,GAAI,CACF,EAAS,KAAK,MAAM,EAAG,aAAa,EAAU,MAAM,CAAC,CACvD,OAAS,EAAO,CACd,MAAU,MACR,wCAAwC,EAAS,IAAI,aAAiB,MAAQ,EAAM,QAAU,OAAO,CAAK,GAC5G,CACF,CACA,GAAI,CAAC,EAAS,CAAM,EAAG,MAAU,MAAM,4BAA4B,EAAS,yBAAyB,EACrG,OAAO,CACT,CAEA,SAAgB,EAA2B,EAAmB,EAA6C,CACzG,GAAI,CAAC,EAAyB,KAAK,CAAc,EAC/C,MAAU,MAAM,gBAAgB,EAAe,8CAA8C,EAE/F,IAAI,EACJ,GAAI,CACF,IAAM,EAAM,IAAI,IAAI,CAAS,EAC7B,GAAI,EAAI,WAAa,QAAS,MAAU,MAAM,4CAA4C,EAAI,UAAU,EACxG,EAAa,EAAG,aAAa,EAAc,CAAG,CAAC,CACjD,OAAS,EAAO,CACd,MAAU,MACR,wCAAwC,EAAU,KAAK,aAAiB,MAAQ,EAAM,QAAU,OAAO,CAAK,GAC9G,CACF,CACA,GAAI,CAAC,EAAG,UAAU,CAAU,CAAC,CAAC,OAAO,EACnC,MAAU,MAAM,kDAAkD,GAAY,EAEhF,IAAI,EAAY,EAAK,QAAQ,CAAU,EACvC,OAAa,CACX,IAAM,EAAe,EAAK,KAAK,EAAW,cAAgB,EAC1D,GAAI,EAAG,WAAW,CAAY,EAAG,CAC/B,IAAM,EAAW,EAAa,CAAY,EACpC,EAAS,EAAS,KAClB,EAAU,EAAS,QACzB,GAAI,IAAW,EACb,MAAU,MAAM,gBAAgB,EAAe,oCAAoC,OAAO,CAAM,EAAE,GAAG,EAEvG,GAAI,OAAO,GAAY,UAAY,CAAC,EAAqB,KAAK,CAAO,EACnE,MAAU,MAAM,iBAAiB,EAAe,0CAA0C,EAE5F,IAAM,EAAc,EAAG,aAAa,CAAS,EAC7C,GAAI,CAAC,EAAY,EAAa,CAAU,EACtC,MAAU,MAAM,4DAA4D,EAC9E,MAAO,CAAE,OAAQ,EAAgB,UAAS,cAAa,YAAW,CACpE,CACA,IAAM,EAAS,EAAK,QAAQ,CAAS,EACrC,GAAI,IAAW,EAAW,MAC1B,EAAY,CACd,CACA,MAAU,MAAM,uDAAuD,EAAW,EAAE,CACtF,CAEA,SAAgB,EAAqB,EAAgB,EAAG,QAAQ,EAAW,CACzE,OAAO,EAAK,KAAK,EAAe,MAAO,QAAS,YAAY,CAC9D,CAEA,SAAgB,EAAU,EAAoC,CAC5D,OAAO,EAAW,QAAQ,CAAC,CAAC,OAAO,CAAK,CAAC,CAAC,OAAO,KAAK,CACxD,CAEA,SAAS,EAAmB,EAAgB,EAA0D,CAC/F,KAAS,CAAK,GAEjB,EAAM,gBAAkB,GACxB,EAAM,SAAW,EAAS,QAC1B,EAAM,UAAY,EAAS,SAC3B,EAAM,OAAS,GACf,OAAO,EAAM,WAAc,UAC3B,OAAO,EAAM,QAAW,UACxB,OAAO,EAAM,eAAkB,SAIjC,OAAO,CACT,CAEA,SAAS,EAAY,EAA2B,CAC9C,GAAI,CACF,IAAM,EAAW,EAAG,UAAU,CAAQ,EACtC,OAAO,EAAS,OAAO,GAAK,CAAC,EAAS,eAAe,CACvD,MAAQ,CACN,MAAO,EACT,CACF,CAEA,IAAa,EAAb,KAA4B,CAC1B,KAEA,YAAY,EAAO,EAAqB,EAAG,CACzC,KAAK,KAAO,CACd,CAEA,eAAe,EAAuC,CACpD,IAAM,EAAM,EAAU,GAAG,EAAS,OAAO,IAAI,EAAS,QAAQ,IAAI,GAAiB,EACnF,OAAO,EAAK,KAAK,KAAK,KAAM,CAAG,CACjC,CAEA,QAAQ,EAAqC,CAC3C,EAAG,OAAO,KAAK,eAAe,CAAQ,EAAG,CAAE,UAAW,GAAM,MAAO,EAAK,CAAC,CAC3E,CAEA,KAAK,EAA4D,CAC/D,IAAM,EAAY,KAAK,eAAe,CAAQ,EACxC,EAAiB,EAAK,KAAK,EAAW,CAAe,EACrD,EAAY,EAAK,KAAK,EAAW,CAAe,EAChD,EAAe,EAAK,KAAK,EAAW,CAAmB,EACzD,MAAC,EAAY,CAAc,GAAK,CAAC,EAAY,CAAS,GAAK,CAAC,EAAY,CAAY,GACxF,GAAI,CACF,IAAM,EAAW,EAAmB,KAAK,MAAM,EAAG,aAAa,EAAc,MAAM,CAAC,EAAc,CAAQ,EAC1G,GAAI,CAAC,EAAU,OACf,IAAM,EAAQ,EAAG,aAAa,CAAS,EAGvC,OAFI,EAAU,CAAK,IAAM,EAAS,QAC9B,EAAG,aAAa,EAAgB,MAAM,CAAC,CAAC,KAAK,IAAM,EAAS,OAAQ,OACjE,CACL,QACA,SAAU,EACV,UAAW,EAAS,UACpB,OAAQ,EAAS,OACjB,cAAe,EAAS,aAC1B,CACF,MAAQ,CACN,MACF,CACF,CAEA,QACE,EACA,EACA,EACA,EACA,EACiB,CACjB,EAAiB,CAAM,EACvB,IAAM,EAAW,KAAK,KAAK,CAAQ,EACnC,GAAI,EAAU,OAAO,EACrB,IAAM,EAAY,KAAK,eAAe,CAAQ,EAC9C,EAAG,UAAU,KAAK,KAAM,CAAE,KAAM,IAAwB,UAAW,EAAK,CAAC,EACrE,EAAG,WAAW,CAAS,GAAG,EAAG,OAAO,EAAW,CAAE,UAAW,GAAM,MAAO,EAAK,CAAC,EACnF,IAAM,EAAY,GAAG,EAAU,GAAG,QAAQ,IAAI,GAAG,EAAW,EAAE,MACxD,EAAS,EAAU,CAAK,EACxB,EAA0B,CAC9B,cAAe,EACf,OAAQ,EAAS,OACjB,QAAS,EAAS,QAClB,KAAM,EACN,YACA,SACA,eACF,EACA,GAAI,CACF,EAAG,UAAU,EAAW,CAAE,KAAM,GAAuB,CAAC,EACxD,EAAG,cAAc,EAAK,KAAK,EAAW,CAAe,EAAG,EAAO,CAAE,KAAM,GAAkB,CAAC,EAC1F,EAAG,cAAc,EAAK,KAAK,EAAW,CAAmB,EAAG,GAAG,KAAK,UAAU,EAAU,KAAM,CAAC,EAAE,IAAK,CACpG,KAAM,GACR,CAAC,EACD,EAAiB,CAAM,EACvB,EAAG,cAAc,EAAK,KAAK,EAAW,CAAe,EAAG,GAAG,EAAO,IAAK,CAAE,KAAM,GAAkB,CAAC,EAClG,GAAI,CACF,EAAG,WAAW,EAAW,CAAS,CACpC,OAAS,EAAO,CACd,IAAM,EAAS,KAAK,KAAK,CAAQ,EACjC,GAAI,EAAQ,OAAO,EACnB,MAAM,CACR,CACA,MAAO,CACL,MAAO,WAAW,KAAK,CAAK,EAC5B,SAAU,EAAK,KAAK,EAAW,CAAe,EAC9C,YACA,SACA,eACF,CACF,QAAU,CACR,EAAG,OAAO,EAAW,CAAE,UAAW,GAAM,MAAO,EAAK,CAAC,CACvD,CACF,CACF,EAEa,EAAb,KAA2E,CAC5C,UAA7B,YAAY,EAA6B,EAAqB,EAAG,CAApC,KAAA,UAAA,CAAqC,CAElE,MAAM,YACJ,EACA,EACA,EACmC,CACnC,IAAM,EAA0B,CAAC,EACjC,IAAK,IAAM,KAAc,EAAa,OAAQ,CAC5C,EAAiB,CAAM,EACvB,IAAM,EAAM,EACV,GAAG,EAAM,SAAS,OAAO,IAAI,EAAM,SAAS,QAAQ,IAAI,EAAW,KAAK,IAAI,EAAW,YAAY,IAAI,EAAM,QAC/G,EACM,EAAY,EAAK,KAAK,KAAK,UAAW,WAAmB,CAAG,EAC5D,EAAW,EAAK,KAAK,EAAW,CAAU,EAC1C,EAAU,EAAuB,EAAY,CAAK,EACxD,GAAI,CAAC,EAAY,CAAQ,GAAK,EAAG,aAAa,EAAU,MAAM,IAAM,EAAS,CAC3E,EAAG,UAAU,EAAK,QAAQ,CAAS,EAAG,CAAE,KAAM,IAAwB,UAAW,EAAK,CAAC,EACnF,EAAG,WAAW,CAAS,GAAG,EAAG,OAAO,EAAW,CAAE,UAAW,GAAM,MAAO,EAAK,CAAC,EACnF,IAAM,EAAY,GAAG,EAAU,GAAG,QAAQ,IAAI,GAAG,EAAW,EAAE,MAC9D,GAAI,CACF,EAAG,UAAU,EAAW,CAAE,KAAM,GAAuB,CAAC,EACxD,EAAG,cAAc,EAAK,KAAK,EAAW,CAAU,EAAG,EAAS,CAAE,KAAM,GAAkB,CAAC,EACvF,EAAiB,CAAM,EACvB,GAAI,CACF,EAAG,WAAW,EAAW,CAAS,CACpC,OAAS,EAAO,CACd,GAAI,CAAC,EAAY,CAAQ,GAAK,EAAG,aAAa,EAAU,MAAM,IAAM,EAAS,MAAM,CACrF,CACF,QAAU,CACR,EAAG,OAAO,EAAW,CAAE,UAAW,GAAM,MAAO,EAAK,CAAC,CACvD,CACF,CACA,EAAO,KAAK,CACV,OAAQ,EAAa,OACrB,KAAM,EAAW,KACjB,YAAa,EAAW,YACxB,WACA,QAAS,CACX,CAAC,CACH,CACA,OAAO,CACT,CACF"}
+{"version":3,"file":"helpStorage.mjs","names":[],"sources":["../../src/adapters/helpStorage.ts"],"sourcesContent":["import { createHash, randomUUID } from 'node:crypto';\nimport fs from 'node:fs';\nimport os from 'node:os';\nimport path from 'node:path';\nimport { fileURLToPath } from 'node:url';\nimport type { DoomHelpContribution, DoomHelpSkill } from '@agimon-ai/doompi-extension-contracts/help';\nimport { renderHelpSkillWrapper } from '../services/llmsContent.ts';\nimport type { HelpPackageIdentity, HelpSkillMaterializer, ResolvedHelpIndex } from '../types/help.ts';\n\nconst PACKAGE_MANIFEST = 'package.json';\nconst HELP_INDEX_PATH = 'llms.txt';\nconst CACHE_SCHEMA_VERSION = 1;\nconst PRIVATE_FILE_MODE = 0o600;\nconst PRIVATE_DIRECTORY_MODE = 0o700;\nconst COMPLETION_FILE = '.complete';\nconst CACHE_METADATA_FILE = 'metadata.json';\nconst WRAPPER_DIRECTORY = 'wrappers';\nconst SKILL_FILE = 'SKILL.md';\nconst EXACT_SEMVER_PATTERN =\n  /^(?:0|[1-9]\\d*)\\.(?:0|[1-9]\\d*)\\.(?:0|[1-9]\\d*)(?:-[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*)?(?:\\+[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*)?$/u;\nconst NPM_PACKAGE_NAME_PATTERN = /^(?:@[a-z0-9][a-z0-9._~-]*\\/)?[a-z0-9][a-z0-9._~-]*$/u;\n\ninterface CacheMetadata {\n  schemaVersion: typeof CACHE_SCHEMA_VERSION;\n  source: string;\n  version: string;\n  path: typeof HELP_INDEX_PATH;\n  integrity: string;\n  digest: string;\n  referenceBase: string;\n}\n\nexport interface CachedHelpIndex {\n  bytes: Uint8Array;\n  filePath: string;\n  integrity: string;\n  digest: string;\n  referenceBase: string;\n}\n\nfunction assertNotAborted(signal: AbortSignal): void {\n  if (signal.aborted) throw new Error('Help activation was cancelled.');\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === 'object' && value !== null && !Array.isArray(value);\n}\n\nfunction isContained(root: string, candidate: string): boolean {\n  const relative = path.relative(root, candidate);\n  return relative === '' || (!relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative));\n}\n\nfunction readManifest(filePath: string): Record<string, unknown> {\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(fs.readFileSync(filePath, 'utf8')) as unknown;\n  } catch (error) {\n    throw new Error(\n      `Cannot read Help package manifest at ${filePath}: ${error instanceof Error ? error.message : String(error)}`,\n    );\n  }\n  if (!isRecord(parsed)) throw new Error(`Help package manifest at ${filePath} must contain an object.`);\n  return parsed;\n}\n\nexport function resolveHelpPackageIdentity(moduleUrl: string, expectedSource: string): HelpPackageIdentity {\n  if (!NPM_PACKAGE_NAME_PATTERN.test(expectedSource)) {\n    throw new Error(`Help source '${expectedSource}' must be a valid lowercase npm package name.`);\n  }\n  let modulePath: string;\n  try {\n    const url = new URL(moduleUrl);\n    if (url.protocol !== 'file:') throw new Error(`Help module URL must use file:, received ${url.protocol}`);\n    modulePath = fs.realpathSync(fileURLToPath(url));\n  } catch (error) {\n    throw new Error(\n      `Invalid Help contributor module URL '${moduleUrl}': ${error instanceof Error ? error.message : String(error)}`,\n    );\n  }\n  if (!fs.lstatSync(modulePath).isFile())\n    throw new Error(`Help contributor module is not a regular file: ${modulePath}`);\n\n  let directory = path.dirname(modulePath);\n  while (true) {\n    const manifestPath = path.join(directory, PACKAGE_MANIFEST);\n    if (fs.existsSync(manifestPath)) {\n      const manifest = readManifest(manifestPath);\n      const source = manifest.name;\n      const version = manifest.version;\n      if (source !== expectedSource) {\n        throw new Error(`Help source '${expectedSource}' does not match nearest package '${String(source)}'.`);\n      }\n      if (typeof version !== 'string' || !EXACT_SEMVER_PATTERN.test(version)) {\n        throw new Error(`Help package '${expectedSource}' must declare an exact semantic version.`);\n      }\n      const packageRoot = fs.realpathSync(directory);\n      if (!isContained(packageRoot, modulePath))\n        throw new Error('Help contributor module escapes its resolved package root.');\n      return { source: expectedSource, version, packageRoot, modulePath };\n    }\n    const parent = path.dirname(directory);\n    if (parent === directory) break;\n    directory = parent;\n  }\n  throw new Error(`Cannot find a package manifest for Help contributor ${modulePath}.`);\n}\n\nexport function defaultHelpCacheRoot(homeDirectory = os.homedir()): string {\n  return path.join(homeDirectory, '.pi', '.doom', 'llms-cache');\n}\n\nexport function sha256Hex(bytes: Uint8Array | string): string {\n  return createHash('sha256').update(bytes).digest('hex');\n}\n\nfunction parseCacheMetadata(value: unknown, identity: HelpPackageIdentity): CacheMetadata | undefined {\n  if (!isRecord(value)) return undefined;\n  if (\n    value.schemaVersion !== CACHE_SCHEMA_VERSION ||\n    value.source !== identity.source ||\n    value.version !== identity.version ||\n    value.path !== HELP_INDEX_PATH ||\n    typeof value.integrity !== 'string' ||\n    typeof value.digest !== 'string' ||\n    typeof value.referenceBase !== 'string'\n  ) {\n    return undefined;\n  }\n  return value as unknown as CacheMetadata;\n}\n\nfunction regularFile(filePath: string): boolean {\n  try {\n    const metadata = fs.lstatSync(filePath);\n    return metadata.isFile() && !metadata.isSymbolicLink();\n  } catch {\n    return false;\n  }\n}\n\nexport class HelpIndexCache {\n  readonly root: string;\n\n  constructor(root = defaultHelpCacheRoot()) {\n    this.root = root;\n  }\n\n  entryDirectory(identity: HelpPackageIdentity): string {\n    const key = sha256Hex(`${identity.source}\\0${identity.version}\\0${HELP_INDEX_PATH}`);\n    return path.join(this.root, key);\n  }\n\n  discard(identity: HelpPackageIdentity): void {\n    fs.rmSync(this.entryDirectory(identity), { recursive: true, force: true });\n  }\n\n  read(identity: HelpPackageIdentity): CachedHelpIndex | undefined {\n    const directory = this.entryDirectory(identity);\n    const completionPath = path.join(directory, COMPLETION_FILE);\n    const indexPath = path.join(directory, HELP_INDEX_PATH);\n    const metadataPath = path.join(directory, CACHE_METADATA_FILE);\n    if (!regularFile(completionPath) || !regularFile(indexPath) || !regularFile(metadataPath)) return undefined;\n    try {\n      const metadata = parseCacheMetadata(JSON.parse(fs.readFileSync(metadataPath, 'utf8')) as unknown, identity);\n      if (!metadata) return undefined;\n      const bytes = fs.readFileSync(indexPath);\n      if (sha256Hex(bytes) !== metadata.digest) return undefined;\n      if (fs.readFileSync(completionPath, 'utf8').trim() !== metadata.digest) return undefined;\n      return {\n        bytes,\n        filePath: indexPath,\n        integrity: metadata.integrity,\n        digest: metadata.digest,\n        referenceBase: metadata.referenceBase,\n      };\n    } catch {\n      return undefined;\n    }\n  }\n\n  publish(\n    identity: HelpPackageIdentity,\n    bytes: Uint8Array,\n    integrity: string,\n    referenceBase: string,\n    signal: AbortSignal,\n  ): CachedHelpIndex {\n    assertNotAborted(signal);\n    const existing = this.read(identity);\n    if (existing) return existing;\n    const directory = this.entryDirectory(identity);\n    fs.mkdirSync(this.root, { mode: PRIVATE_DIRECTORY_MODE, recursive: true });\n    if (fs.existsSync(directory)) fs.rmSync(directory, { recursive: true, force: true });\n    const temporary = `${directory}.${process.pid}.${randomUUID()}.tmp`;\n    const digest = sha256Hex(bytes);\n    const metadata: CacheMetadata = {\n      schemaVersion: CACHE_SCHEMA_VERSION,\n      source: identity.source,\n      version: identity.version,\n      path: HELP_INDEX_PATH,\n      integrity,\n      digest,\n      referenceBase,\n    };\n    try {\n      fs.mkdirSync(temporary, { mode: PRIVATE_DIRECTORY_MODE });\n      fs.writeFileSync(path.join(temporary, HELP_INDEX_PATH), bytes, { mode: PRIVATE_FILE_MODE });\n      fs.writeFileSync(path.join(temporary, CACHE_METADATA_FILE), `${JSON.stringify(metadata, null, 2)}\\n`, {\n        mode: PRIVATE_FILE_MODE,\n      });\n      assertNotAborted(signal);\n      fs.writeFileSync(path.join(temporary, COMPLETION_FILE), `${digest}\\n`, { mode: PRIVATE_FILE_MODE });\n      try {\n        fs.renameSync(temporary, directory);\n      } catch (error) {\n        const winner = this.read(identity);\n        if (winner) return winner;\n        throw error;\n      }\n      return {\n        bytes: Uint8Array.from(bytes),\n        filePath: path.join(directory, HELP_INDEX_PATH),\n        integrity,\n        digest,\n        referenceBase,\n      };\n    } finally {\n      fs.rmSync(temporary, { recursive: true, force: true });\n    }\n  }\n}\n\nexport class DefaultHelpSkillMaterializer implements HelpSkillMaterializer {\n  constructor(private readonly cacheRoot = defaultHelpCacheRoot()) {}\n\n  async materialize(\n    contribution: DoomHelpContribution,\n    index: ResolvedHelpIndex,\n    signal: AbortSignal,\n  ): Promise<readonly DoomHelpSkill[]> {\n    const skills: DoomHelpSkill[] = [];\n    for (const descriptor of contribution.skills) {\n      assertNotAborted(signal);\n      const key = sha256Hex(\n        `${index.identity.source}\\0${index.identity.version}\\0${descriptor.name}\\0${descriptor.description}\\0${index.digest}`,\n      );\n      const directory = path.join(this.cacheRoot, WRAPPER_DIRECTORY, key);\n      const filePath = path.join(directory, SKILL_FILE);\n      const content = renderHelpSkillWrapper(descriptor, index);\n      if (!regularFile(filePath) || fs.readFileSync(filePath, 'utf8') !== content) {\n        fs.mkdirSync(path.dirname(directory), { mode: PRIVATE_DIRECTORY_MODE, recursive: true });\n        if (fs.existsSync(directory)) fs.rmSync(directory, { recursive: true, force: true });\n        const temporary = `${directory}.${process.pid}.${randomUUID()}.tmp`;\n        try {\n          fs.mkdirSync(temporary, { mode: PRIVATE_DIRECTORY_MODE });\n          fs.writeFileSync(path.join(temporary, SKILL_FILE), content, { mode: PRIVATE_FILE_MODE });\n          assertNotAborted(signal);\n          try {\n            fs.renameSync(temporary, directory);\n          } catch (error) {\n            if (!regularFile(filePath) || fs.readFileSync(filePath, 'utf8') !== content) throw error;\n          }\n        } finally {\n          fs.rmSync(temporary, { recursive: true, force: true });\n        }\n      }\n      skills.push({\n        source: contribution.source,\n        name: descriptor.name,\n        description: descriptor.description,\n        filePath,\n        baseDir: directory,\n      });\n    }\n    return skills;\n  }\n}\n"],"mappings":"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"}

package/dist/adapters/pi/extension.d.cts

@@ -3,9 +3,9 @@ import { Context } from "@deepseek-ai/cordis";
 import { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 //#region src/adapters/pi/extension.d.ts
 /** Install Help resources into its host-owned Cordis plugin fiber. */
-declare function installHelpRuntime(cordis: Context, pi: ExtensionAPI, options?: HelpRuntimeOptions): void;
+export declare function installHelpRuntime(cordis: Context, pi: ExtensionAPI, options?: HelpRuntimeOptions): void;
 /** The package's single standard Pi factory, including optional typed Doom integrations. */
-declare function helpExtension(pi: ExtensionAPI): Promise<void>;
+export declare function helpExtension(pi: ExtensionAPI): Promise<void>;
 //#endregion
-export { helpExtension as default, helpExtension, installHelpRuntime };
+export { helpExtension as default };
 //# sourceMappingURL=extension.d.cts.map

package/dist/adapters/pi/extension.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"extension.d.cts","names":[],"sources":["../../../src/adapters/pi/extension.ts"],"mappings":";;;;;iBAsBgB,mBAAmB,QAAQ,SAAS,IAAI,cAAc,UAAS;;iBAiDzD,cAAc,IAAI,eAAe"}
+{"version":3,"file":"extension.d.cts","names":[],"sources":["../../../src/adapters/pi/extension.ts"],"mappings":";;;;;wBAsBgB,mBAAmB,QAAQ,SAAS,IAAI,cAAc,UAAS;;wBAiDzD,cAAc,IAAI,eAAe"}

package/dist/adapters/pi/extension.d.mts

@@ -3,9 +3,9 @@ import { Context } from "@deepseek-ai/cordis";
 import { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 //#region src/adapters/pi/extension.d.ts
 /** Install Help resources into its host-owned Cordis plugin fiber. */
-declare function installHelpRuntime(cordis: Context, pi: ExtensionAPI, options?: HelpRuntimeOptions): void;
+export declare function installHelpRuntime(cordis: Context, pi: ExtensionAPI, options?: HelpRuntimeOptions): void;
 /** The package's single standard Pi factory, including optional typed Doom integrations. */
-declare function helpExtension(pi: ExtensionAPI): Promise<void>;
+export declare function helpExtension(pi: ExtensionAPI): Promise<void>;
 //#endregion
-export { helpExtension as default, helpExtension, installHelpRuntime };
+export { helpExtension as default };
 //# sourceMappingURL=extension.d.mts.map

package/dist/adapters/pi/extension.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"extension.d.mts","names":[],"sources":["../../../src/adapters/pi/extension.ts"],"mappings":";;;;;iBAsBgB,mBAAmB,QAAQ,SAAS,IAAI,cAAc,UAAS;;iBAiDzD,cAAc,IAAI,eAAe"}
+{"version":3,"file":"extension.d.mts","names":[],"sources":["../../../src/adapters/pi/extension.ts"],"mappings":";;;;;wBAsBgB,mBAAmB,QAAQ,SAAS,IAAI,cAAc,UAAS;;wBAiDzD,cAAc,IAAI,eAAe"}

package/dist/container/index.d.cts

@@ -2,12 +2,11 @@ import { HelpFetch } from "../types/help.cjs";
 import "../services/helpActivation.cjs";
 import "@agimon-ai/doompi-extension-contracts/help";
 //#region src/container/index.d.ts
-interface HelpRuntimeOptions {
+export interface HelpRuntimeOptions {
   cacheRoot?: string;
   fetch?: HelpFetch;
   timeoutMs?: number;
   onBackgroundError?(error: unknown): void;
 }
 //#endregion
-export { HelpRuntimeOptions };
 //# sourceMappingURL=index.d.cts.map

package/dist/container/index.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.cts","names":[],"sources":["../../src/container/index.ts"],"mappings":";;;;UAMiB;EACf;EACA,QAAQ;EACR;EACA,mBAAmB"}
+{"version":3,"file":"index.d.cts","names":[],"sources":["../../src/container/index.ts"],"mappings":";;;;iBAMiB;EACf;EACA,QAAQ;EACR;EACA,mBAAmB"}

package/dist/container/index.d.mts

@@ -2,12 +2,11 @@ import { HelpFetch } from "../types/help.mjs";
 import "../services/helpActivation.mjs";
 import "@agimon-ai/doompi-extension-contracts/help";
 //#region src/container/index.d.ts
-interface HelpRuntimeOptions {
+export interface HelpRuntimeOptions {
   cacheRoot?: string;
   fetch?: HelpFetch;
   timeoutMs?: number;
   onBackgroundError?(error: unknown): void;
 }
 //#endregion
-export { HelpRuntimeOptions };
 //# sourceMappingURL=index.d.mts.map

package/dist/container/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/container/index.ts"],"mappings":";;;;UAMiB;EACf;EACA,QAAQ;EACR;EACA,mBAAmB"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/container/index.ts"],"mappings":";;;;iBAMiB;EACf;EACA,QAAQ;EACR;EACA,mBAAmB"}

package/dist/types/help.d.cts

@@ -1,6 +1,6 @@
 import "@agimon-ai/doompi-extension-contracts/help";
 //#region src/types/help.d.ts
-interface HelpFetchResponse {
+export interface HelpFetchResponse {
   ok: boolean;
   status: number;
   headers: {
@@ -9,10 +9,9 @@ interface HelpFetchResponse {
   text(): Promise<string>;
   arrayBuffer(): Promise<ArrayBuffer>;
 }
-type HelpFetch = (input: string, init: {
+export type HelpFetch = (input: string, init: {
   signal: AbortSignal;
   redirect: 'manual';
 }) => Promise<HelpFetchResponse>;
 //#endregion
-export { HelpFetch, HelpFetchResponse };
 //# sourceMappingURL=help.d.cts.map

package/dist/types/help.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"help.d.cts","names":[],"sources":["../../src/types/help.ts"],"mappings":";;UA+DiB;EACf;EACA;EACA;IAAW,IAAI;;EACf,QAAQ;EACR,eAAe,QAAQ;;KAGb,aACV,eACA;EAAQ,QAAQ;EAAa;MAC1B,QAAQ"}
+{"version":3,"file":"help.d.cts","names":[],"sources":["../../src/types/help.ts"],"mappings":";;iBA+DiB;EACf;EACA;EACA;IAAW,IAAI;;EACf,QAAQ;EACR,eAAe,QAAQ;;YAGb,aACV,eACA;EAAQ,QAAQ;EAAa;MAC1B,QAAQ"}

package/dist/types/help.d.mts

@@ -1,6 +1,6 @@
 import "@agimon-ai/doompi-extension-contracts/help";
 //#region src/types/help.d.ts
-interface HelpFetchResponse {
+export interface HelpFetchResponse {
   ok: boolean;
   status: number;
   headers: {
@@ -9,10 +9,9 @@ interface HelpFetchResponse {
   text(): Promise<string>;
   arrayBuffer(): Promise<ArrayBuffer>;
 }
-type HelpFetch = (input: string, init: {
+export type HelpFetch = (input: string, init: {
   signal: AbortSignal;
   redirect: 'manual';
 }) => Promise<HelpFetchResponse>;
 //#endregion
-export { HelpFetch, HelpFetchResponse };
 //# sourceMappingURL=help.d.mts.map

package/dist/types/help.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"help.d.mts","names":[],"sources":["../../src/types/help.ts"],"mappings":";;UA+DiB;EACf;EACA;EACA;IAAW,IAAI;;EACf,QAAQ;EACR,eAAe,QAAQ;;KAGb,aACV,eACA;EAAQ,QAAQ;EAAa;MAC1B,QAAQ"}
+{"version":3,"file":"help.d.mts","names":[],"sources":["../../src/types/help.ts"],"mappings":";;iBA+DiB;EACf;EACA;EACA;IAAW,IAAI;;EACf,QAAQ;EACR,eAAe,QAAQ;;YAGb,aACV,eACA;EAAQ,QAAQ;EAAa;MAC1B,QAAQ"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agimon-ai/doompi-help",
-  "version": "0.0.1-alpha.41",
+  "version": "0.0.1-alpha.47",
   "description": "Activation-gated package guidance and help skills for DoomPi and Pi extensions.",
   "keywords": [
     "agent-documentation",
@@ -56,21 +56,21 @@
     "access": "public"
   },
   "dependencies": {
-    "@deepseek-ai/cordis": "4.0.1",
-    "@agimon-ai/doompi-web-contracts": "0.0.1-alpha.20",
-    "@agimon-ai/doompi-extension-contracts": "0.0.1-alpha.57"
+    "@deepseek-ai/cordis": "4.0.2",
+    "@agimon-ai/doompi-extension-contracts": "0.0.1-alpha.63",
+    "@agimon-ai/doompi-web-contracts": "0.0.1-alpha.26"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "0.85.0",
-    "@types/node": "26.4.0",
-    "@vitest/coverage-v8": "4.1.11",
-    "tsdown": "0.22.14",
+    "@earendil-works/pi-coding-agent": "0.85.1",
+    "@types/node": "26.4.1",
+    "@vitest/coverage-v8": "5.0.0",
+    "tsdown": "0.23.0",
     "typescript": "7.0.2",
-    "vitest": "4.1.11",
-    "@agimon-ai/vibe-lint-plugin-doom-extension": "0.0.1-alpha.54"
+    "vitest": "5.0.0",
+    "@agimon-ai/vibe-lint-plugin-doom-extension": "0.0.1-alpha.60"
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "0.85.0"
+    "@earendil-works/pi-coding-agent": "0.85.1"
   },
   "peerDependenciesMeta": {
     "@earendil-works/pi-coding-agent": {