pupt-lib 1.3.5 → 1.3.6

package/dist/index.js

@@ -3854,6 +3854,12 @@ function createRuntimeConfig() {
     uuid: crypto.randomUUID()
   };
 }
+function isWarningCode(code) {
+  return code.startsWith("warn_") || code === "validation_warning";
+}
+function isPromptSource(value) {
+  return value !== null && typeof value === "object" && "getPrompts" in value && typeof value.getPrompts === "function";
+}
 const COMPONENT_MARKER = Symbol.for("pupt-lib:component:v1");
 _a = COMPONENT_MARKER;
 class Component {
@@ -4002,7 +4008,9 @@ async function render(element, options = {}) {
   const {
     inputs = /* @__PURE__ */ new Map(),
     env = DEFAULT_ENVIRONMENT,
-    trim = true
+    trim = true,
+    throwOnWarnings = false,
+    ignoreWarnings = []
   } = options;
   const postExecution = [];
   const errors = [];
@@ -4021,13 +4029,26 @@ async function render(element, options = {}) {
   seedAskDefaults(element, context);
   const text = await renderNode(element, state);
   const trimmedText = trim ? text.trim() : text;
-  const warnings = errors.filter((e) => e.code === "validation_warning");
-  const hardErrors = errors.filter((e) => e.code !== "validation_warning");
+  const ignoreSet = new Set(ignoreWarnings);
+  const warnings = [];
+  const hardErrors = [];
+  for (const err of errors) {
+    if (isWarningCode(err.code)) {
+      if (ignoreSet.has(err.code)) continue;
+      if (throwOnWarnings) {
+        hardErrors.push(err);
+      } else {
+        warnings.push(err);
+      }
+    } else {
+      hardErrors.push(err);
+    }
+  }
   if (hardErrors.length > 0) {
     return {
       ok: false,
       text: trimmedText,
-      errors,
+      errors: [...hardErrors, ...warnings],
       postExecution
     };
   }
@@ -43178,6 +43199,49 @@ ${imports}
 
 ${usesSection}${result}`;
 }
+const CUSTOM_COMPONENTS_GLOBAL = "__PUPT_CUSTOM_COMPONENTS__";
+async function createPromptFromSource(source, filename, options = {}) {
+  const { components } = options;
+  let processedSource = preprocessSource(source, { filename });
+  if (components && Object.keys(components).length > 0) {
+    globalThis[CUSTOM_COMPONENTS_GLOBAL] = components;
+    const componentNames = Object.keys(components);
+    const extractCode = `const { ${componentNames.join(", ")} } = globalThis.${CUSTOM_COMPONENTS_GLOBAL};
+`;
+    let lastImportEnd = 0;
+    const fullImportRegex = /import\s+(?:(?:\{[^}]*\}|[^;{]*)\s+from\s+)?['"][^'"]+['"];?/g;
+    let match;
+    while ((match = fullImportRegex.exec(processedSource)) !== null) {
+      const matchEnd = match.index + match[0].length;
+      if (matchEnd > lastImportEnd) {
+        lastImportEnd = matchEnd;
+      }
+    }
+    if (lastImportEnd > 0) {
+      processedSource = processedSource.slice(0, lastImportEnd) + "\n" + extractCode + processedSource.slice(lastImportEnd);
+    } else {
+      processedSource = extractCode + processedSource;
+    }
+  }
+  try {
+    const transformer = new Transformer2();
+    const code = await transformer.transformSourceAsync(processedSource, filename);
+    const module = await evaluateModule(code, { filename });
+    if (module.default === void 0) {
+      throw new Error(`${filename} must have a default export`);
+    }
+    return module.default;
+  } finally {
+    if (components) {
+      delete globalThis[CUSTOM_COMPONENTS_GLOBAL];
+    }
+  }
+}
+async function createPrompt(filePath, options = {}) {
+  const { readFile } = await import("fs/promises");
+  const source = await readFile(filePath, "utf-8");
+  return createPromptFromSource(source, filePath, options);
+}
 const isNode = typeof process !== "undefined" && ((_b = process.versions) == null ? void 0 : _b.node);
 async function resolveLocalPath(source) {
   if (!isNode) {
@@ -43253,7 +43317,7 @@ class ModuleLoader {
     if (this.loading.has(normalizedSource)) {
       return this.loading.get(normalizedSource);
     }
-    const promise = this.doLoad(normalizedSource);
+    const promise = this.doLoad(source);
     this.loading.set(normalizedSource, promise);
     try {
       const library = await promise;
@@ -43266,6 +43330,67 @@ class ModuleLoader {
       this.loading.delete(normalizedSource);
     }
   }
+  /**
+   * Load a module entry of any type (string, PromptSource, or package reference).
+   * Dispatches to the appropriate loading strategy based on entry type.
+   */
+  async loadEntry(entry) {
+    if (typeof entry === "string") {
+      return this.load(entry);
+    }
+    if (isPromptSource(entry)) {
+      return this.loadPromptSource(entry);
+    }
+    if (typeof entry === "object" && entry !== null && "source" in entry && "config" in entry) {
+      return this.loadPackageReference(entry);
+    }
+    throw new Error("Invalid module entry: must be a string, PromptSource, or { source, config } object");
+  }
+  /**
+   * Load prompts from a PromptSource instance.
+   */
+  async loadPromptSource(source, name) {
+    var _a2;
+    const prompts = await this.discoverAndCompilePrompts(source);
+    return {
+      name: name ?? ((_a2 = source.constructor) == null ? void 0 : _a2.name) ?? "PromptSource",
+      components: {},
+      prompts,
+      dependencies: []
+    };
+  }
+  /**
+   * Load prompts from a dynamic package reference.
+   * Imports the source module, instantiates its default export with the config,
+   * and calls getPrompts() on it.
+   */
+  async loadPackageReference(ref) {
+    let resolvedSource = ref.source;
+    if (isNode && (ref.source.startsWith("./") || ref.source.startsWith("/") || ref.source.startsWith("../"))) {
+      const path = await import("path");
+      const url = await import("url");
+      const absolutePath = path.resolve(process.cwd(), ref.source);
+      resolvedSource = url.pathToFileURL(absolutePath).href;
+    }
+    const module = await import(
+      /* @vite-ignore */
+      resolvedSource
+    );
+    const SourceClass = module.default;
+    if (typeof SourceClass !== "function") {
+      throw new Error(
+        `Package reference source "${ref.source}" must have a default export that is a class or constructor function`
+      );
+    }
+    const sourceInstance = new SourceClass(ref.config);
+    const prompts = await this.discoverAndCompilePrompts(sourceInstance);
+    return {
+      name: ref.source,
+      components: {},
+      prompts,
+      dependencies: []
+    };
+  }
   /**
    * Detect Component classes in module exports
    */
@@ -43301,9 +43426,25 @@ class ModuleLoader {
     return props !== null && typeof props === "object" && "name" in props;
   }
   /**
-   * Normalize a source string for consistent caching
+   * Normalize a source string for consistent deduplication.
+   * Resolves relative paths to absolute, normalizes package names to lowercase.
    */
   normalizeSource(source) {
+    const sourceType = this.resolveSourceType(source);
+    if (sourceType === "local" && isNode) {
+      try {
+        if (source.startsWith("./") || source.startsWith("../")) {
+          const cwd = process.cwd();
+          return `${cwd}/${source}`.replace(/\/\.\//g, "/");
+        }
+      } catch {
+      }
+    }
+    if (sourceType === "npm") {
+      const parsed = this.parsePackageSource(source);
+      const normalizedName = parsed.name.toLowerCase();
+      return parsed.version ? `${normalizedName}@${parsed.version}` : normalizedName;
+    }
     return source;
   }
   /**
@@ -43325,49 +43466,130 @@ class ModuleLoader {
         throw new Error(`Unsupported source type: ${sourceType}`);
     }
   }
+  /**
+   * Discover and compile .prompt files from a PromptSource.
+   * Each file is compiled through createPromptFromSource() and metadata extracted.
+   */
+  async discoverAndCompilePrompts(source) {
+    const files = await source.getPrompts();
+    return this.compilePromptFiles(files);
+  }
+  /**
+   * Compile an array of discovered prompt files into CompiledPrompt records.
+   */
+  async compilePromptFiles(files) {
+    const prompts = {};
+    for (const file of files) {
+      const element = await createPromptFromSource(file.content, file.filename);
+      const props = element[PROPS];
+      const name = (props == null ? void 0 : props.name) ?? file.filename.replace(/\.prompt$/, "");
+      prompts[name] = {
+        element,
+        id: crypto.randomUUID(),
+        name,
+        description: (props == null ? void 0 : props.description) ?? "",
+        tags: (props == null ? void 0 : props.tags) ?? [],
+        version: props == null ? void 0 : props.version
+      };
+    }
+    return prompts;
+  }
   /**
    * Load a local module
    */
   async loadLocal(source) {
+    let components = {};
+    let dependencies = [];
+    let prompts = {};
     try {
       const resolvedPath = await resolveLocalPath(source);
       const module = await import(
         /* @vite-ignore */
         resolvedPath
       );
-      return {
-        name: this.extractNameFromPath(source),
-        components: this.detectComponents(module),
-        dependencies: module.dependencies ?? []
-      };
-    } catch (error) {
+      components = this.detectComponents(module);
+      dependencies = module.dependencies ?? [];
+    } catch {
+    }
+    if (isNode) {
+      try {
+        const { LocalPromptSource: LocalPromptSource2 } = await Promise.resolve().then(() => localPromptSource);
+        const promptSource = new LocalPromptSource2(source);
+        prompts = await this.discoverAndCompilePrompts(promptSource);
+      } catch {
+      }
+    }
+    if (Object.keys(components).length === 0 && Object.keys(prompts).length === 0) {
       throw new Error(
-        `Failed to load local module "${source}": ${error instanceof Error ? error.message : String(error)}`
+        `Failed to load local module "${source}": no JS module or .prompt files found`
       );
     }
+    return {
+      name: this.extractNameFromPath(source),
+      components,
+      prompts,
+      dependencies
+    };
   }
   /**
-   * Load an npm package
+   * Load an npm package.
+   * Tries to import as a JS module and additionally discovers .prompt files.
    */
   async loadNpm(source) {
     const parsed = this.parsePackageSource(source);
+    let components = {};
+    let dependencies = [];
+    let prompts = {};
+    let jsLoaded = false;
     try {
       const module = await import(parsed.name);
-      return {
-        name: parsed.name,
-        components: this.detectComponents(module),
-        dependencies: module.dependencies ?? []
-      };
-    } catch (error) {
+      components = this.detectComponents(module);
+      dependencies = module.dependencies ?? [];
+      jsLoaded = true;
+    } catch {
+    }
+    if (isNode) {
+      try {
+        const { NpmLocalPromptSource: NpmLocalPromptSource2 } = await Promise.resolve().then(() => npmLocalPromptSource);
+        const promptSource = new NpmLocalPromptSource2(parsed.name);
+        prompts = await this.discoverAndCompilePrompts(promptSource);
+      } catch {
+      }
+    }
+    if (!jsLoaded && Object.keys(prompts).length === 0) {
       throw new Error(
-        `Failed to load npm package "${source}": ${error instanceof Error ? error.message : String(error)}`
+        `Failed to load npm package "${source}": no JS module or .prompt files found`
       );
     }
+    return {
+      name: parsed.name,
+      components,
+      prompts,
+      dependencies
+    };
   }
   /**
-   * Load a module from a URL
+   * Check if a URL looks like an npm tarball or CDN package URL.
+   */
+  isTarballOrCdnUrl(url) {
+    if (url.endsWith(".tgz")) return true;
+    try {
+      const parsed = new URL(url);
+      const host = parsed.hostname;
+      return host === "cdn.jsdelivr.net" || host === "unpkg.com" || host === "esm.sh" || host === "registry.npmjs.org";
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * Load a module from a URL.
+   * Routes tarball/CDN URLs to NpmRegistryPromptSource for prompt discovery.
+   * Other URLs are loaded as JS modules via dynamic import.
    */
   async loadUrl(source) {
+    if (this.isTarballOrCdnUrl(source)) {
+      return this.loadUrlAsPromptSource(source);
+    }
     try {
       const module = await import(
         /* webpackIgnore: true */
@@ -43376,6 +43598,7 @@ class ModuleLoader {
       return {
         name: this.extractNameFromUrl(source),
         components: this.detectComponents(module),
+        prompts: {},
         dependencies: module.dependencies ?? []
       };
     } catch (error) {
@@ -43385,7 +43608,22 @@ class ModuleLoader {
     }
   }
   /**
-   * Load a module from GitHub
+   * Load prompts from a tarball or CDN URL via NpmRegistryPromptSource.
+   */
+  async loadUrlAsPromptSource(source) {
+    const { NpmRegistryPromptSource: NpmRegistryPromptSource2 } = await Promise.resolve().then(() => npmRegistryPromptSource);
+    const promptSource = NpmRegistryPromptSource2.fromUrl(source);
+    const prompts = await this.discoverAndCompilePrompts(promptSource);
+    return {
+      name: this.extractNameFromUrl(source),
+      components: {},
+      prompts,
+      dependencies: []
+    };
+  }
+  /**
+   * Load a module from GitHub.
+   * Tries to import index.js and additionally discovers .prompt files via GitHubPromptSource.
    */
   async loadGithub(source) {
     const match = source.match(/^github:([^/]+)\/([^#]+)(?:#(.+))?$/);
@@ -43393,8 +43631,35 @@ class ModuleLoader {
       throw new Error(`Invalid GitHub source format: ${source}`);
     }
     const [, user, repo, ref] = match;
-    const url = `https://raw.githubusercontent.com/${user}/${repo}/${ref ?? "main"}/index.js`;
-    return this.loadUrl(url);
+    let components = {};
+    let dependencies = [];
+    let prompts = {};
+    try {
+      const url = `https://raw.githubusercontent.com/${user}/${repo}/${ref ?? "main"}/index.js`;
+      const library = await this.loadUrl(url);
+      components = library.components;
+      dependencies = library.dependencies;
+    } catch {
+    }
+    try {
+      const { GitHubPromptSource: GitHubPromptSource2 } = await Promise.resolve().then(() => githubPromptSource);
+      const ownerRepo = `${user}/${repo}`;
+      const options = ref ? { ref } : void 0;
+      const promptSource = new GitHubPromptSource2(ownerRepo, options);
+      prompts = await this.discoverAndCompilePrompts(promptSource);
+    } catch {
+    }
+    if (Object.keys(components).length === 0 && Object.keys(prompts).length === 0) {
+      throw new Error(
+        `Failed to load GitHub module "${source}": no JS module or .prompt files found`
+      );
+    }
+    return {
+      name: `${user}/${repo}`,
+      components,
+      prompts,
+      dependencies
+    };
   }
   /**
    * Extract a module name from a file path
@@ -43426,6 +43691,376 @@ class ModuleLoader {
     this.versions.clear();
   }
 }
+class LocalPromptSource {
+  constructor(dirPath) {
+    __publicField(this, "dirPath");
+    this.dirPath = dirPath;
+  }
+  async getPrompts() {
+    const fs = await import("fs/promises");
+    const path = await import("path");
+    const resolvedPath = path.resolve(this.dirPath);
+    try {
+      await fs.access(resolvedPath);
+    } catch {
+      throw new Error(`Directory not found: ${resolvedPath}`);
+    }
+    let scanDir = resolvedPath;
+    const entries = await fs.readdir(resolvedPath);
+    const hasPromptFiles = entries.some((e) => e.endsWith(".prompt"));
+    if (!hasPromptFiles) {
+      const promptsSubdir = path.join(resolvedPath, "prompts");
+      try {
+        await fs.access(promptsSubdir);
+        scanDir = promptsSubdir;
+      } catch {
+        return [];
+      }
+    }
+    const dirEntries = await fs.readdir(scanDir);
+    const promptFiles = dirEntries.filter((e) => e.endsWith(".prompt"));
+    const results = [];
+    for (const filename of promptFiles) {
+      const filePath = path.join(scanDir, filename);
+      const content = await fs.readFile(filePath, "utf-8");
+      results.push({ filename, content });
+    }
+    return results;
+  }
+}
+const localPromptSource = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.defineProperty({
+  __proto__: null,
+  LocalPromptSource
+}, Symbol.toStringTag, { value: "Module" }));
+class NpmLocalPromptSource {
+  constructor(packageName) {
+    __publicField(this, "packageName");
+    this.packageName = packageName;
+  }
+  async getPrompts() {
+    const packageDir = await this.resolvePackagePath(this.packageName);
+    const fs = await import("fs/promises");
+    const path = await import("path");
+    const promptsDir = path.join(packageDir, "prompts");
+    try {
+      await fs.access(promptsDir);
+    } catch {
+      return [];
+    }
+    const entries = await fs.readdir(promptsDir);
+    const promptFiles = entries.filter((e) => e.endsWith(".prompt"));
+    const results = [];
+    for (const filename of promptFiles) {
+      const filePath = path.join(promptsDir, filename);
+      const content = await fs.readFile(filePath, "utf-8");
+      results.push({ filename, content });
+    }
+    return results;
+  }
+  /**
+   * Resolve a bare package name to its directory path in node_modules.
+   * Uses import.meta.resolve() when available, with createRequire fallback.
+   */
+  async resolvePackagePath(packageName) {
+    const path = await import("path");
+    const pkgJsonSpecifier = `${packageName}/package.json`;
+    if (typeof import.meta.resolve === "function") {
+      try {
+        const resolved = import.meta.resolve(pkgJsonSpecifier);
+        const { fileURLToPath } = await import("url");
+        const pkgJsonPath = fileURLToPath(resolved);
+        return path.dirname(pkgJsonPath);
+      } catch {
+      }
+    }
+    try {
+      const { createRequire } = await import("module");
+      const esmRequire = createRequire(import.meta.url);
+      const pkgJsonPath = esmRequire.resolve(pkgJsonSpecifier);
+      return path.dirname(pkgJsonPath);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new Error(
+        `Cannot resolve npm package "${packageName}": ${message}`
+      );
+    }
+  }
+}
+const npmLocalPromptSource = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.defineProperty({
+  __proto__: null,
+  NpmLocalPromptSource
+}, Symbol.toStringTag, { value: "Module" }));
+function parseGitHubSource(source) {
+  const hashIndex = source.indexOf("#");
+  let ownerRepo = source;
+  let ref;
+  if (hashIndex !== -1) {
+    ownerRepo = source.slice(0, hashIndex);
+    ref = source.slice(hashIndex + 1);
+  }
+  const slashIndex = ownerRepo.indexOf("/");
+  if (slashIndex === -1) {
+    throw new Error(`Invalid GitHub source format: expected "owner/repo", got "${source}"`);
+  }
+  return {
+    owner: ownerRepo.slice(0, slashIndex),
+    repo: ownerRepo.slice(slashIndex + 1),
+    ref
+  };
+}
+class GitHubPromptSource {
+  constructor(ownerRepo, options) {
+    __publicField(this, "owner");
+    __publicField(this, "repo");
+    __publicField(this, "ref");
+    __publicField(this, "token");
+    const parsed = parseGitHubSource(ownerRepo);
+    this.owner = parsed.owner;
+    this.repo = parsed.repo;
+    this.ref = (options == null ? void 0 : options.ref) ?? parsed.ref ?? "main";
+    this.token = options == null ? void 0 : options.token;
+  }
+  async getPrompts() {
+    const tree = await this.fetchTree();
+    const promptEntries = this.filterPromptFiles(tree);
+    if (promptEntries.length === 0) {
+      return [];
+    }
+    const results = [];
+    for (const entry of promptEntries) {
+      const content = await this.fetchFileContent(entry.path);
+      const filename = entry.path.split("/").pop();
+      results.push({ filename, content });
+    }
+    return results;
+  }
+  async fetchTree() {
+    var _a2;
+    const url = `https://api.github.com/repos/${this.owner}/${this.repo}/git/trees/${this.ref}?recursive=1`;
+    let response;
+    try {
+      response = await fetch(url, { headers: this.getHeaders() });
+    } catch (error) {
+      throw new Error(
+        `Failed to fetch GitHub tree for ${this.owner}/${this.repo}: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+    if (response.status === 403) {
+      const body = await response.json();
+      if ((_a2 = body.message) == null ? void 0 : _a2.toLowerCase().includes("rate limit")) {
+        throw new Error(`GitHub API rate limit exceeded for ${this.owner}/${this.repo}`);
+      }
+      throw new Error(`GitHub API access forbidden for ${this.owner}/${this.repo}: ${body.message ?? "Unknown error"}`);
+    }
+    if (!response.ok) {
+      throw new Error(
+        `Failed to fetch GitHub tree for ${this.owner}/${this.repo}: HTTP ${response.status}`
+      );
+    }
+    const data = await response.json();
+    return data.tree;
+  }
+  filterPromptFiles(tree) {
+    return tree.filter(
+      (entry) => entry.type === "blob" && entry.path.startsWith("prompts/") && entry.path.endsWith(".prompt")
+    );
+  }
+  async fetchFileContent(path) {
+    const url = `https://raw.githubusercontent.com/${this.owner}/${this.repo}/${this.ref}/${path}`;
+    let response;
+    try {
+      response = await fetch(url, { headers: this.getHeaders() });
+    } catch (error) {
+      throw new Error(
+        `Failed to fetch file ${path} from ${this.owner}/${this.repo}: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+    if (!response.ok) {
+      throw new Error(
+        `Failed to fetch file ${path} from ${this.owner}/${this.repo}: HTTP ${response.status}`
+      );
+    }
+    return response.text();
+  }
+  getHeaders() {
+    const headers = {
+      "Accept": "application/vnd.github.v3+json"
+    };
+    if (this.token) {
+      headers["Authorization"] = `token ${this.token}`;
+    }
+    return headers;
+  }
+}
+const githubPromptSource = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.defineProperty({
+  __proto__: null,
+  GitHubPromptSource,
+  parseGitHubSource
+}, Symbol.toStringTag, { value: "Module" }));
+async function decompressGzip(compressed) {
+  const stream = new DecompressionStream("gzip");
+  const writer = stream.writable.getWriter();
+  writer.write(new Uint8Array(compressed));
+  writer.close();
+  const reader = stream.readable.getReader();
+  const chunks = [];
+  let totalLength = 0;
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    chunks.push(value);
+    totalLength += value.length;
+  }
+  const result = new Uint8Array(totalLength);
+  let offset = 0;
+  for (const chunk of chunks) {
+    result.set(chunk, offset);
+    offset += chunk.length;
+  }
+  return result.buffer;
+}
+function parseTar(buffer) {
+  const data = new Uint8Array(buffer);
+  const entries = [];
+  let offset = 0;
+  while (offset + 512 <= data.length) {
+    const header = data.slice(offset, offset + 512);
+    if (header.every((b) => b === 0)) {
+      break;
+    }
+    const name = readString(header, 0, 100);
+    const sizeStr = readString(header, 124, 12);
+    const size = parseInt(sizeStr, 8) || 0;
+    const typeFlag = header[156];
+    offset += 512;
+    if ((typeFlag === 48 || typeFlag === 0) && size > 0) {
+      const content = data.slice(offset, offset + size);
+      entries.push({ name, size, content });
+    }
+    offset += Math.ceil(size / 512) * 512;
+  }
+  return entries;
+}
+function readString(data, offset, maxLength) {
+  let end = offset;
+  while (end < offset + maxLength && data[end] !== 0) {
+    end++;
+  }
+  return new TextDecoder("ascii").decode(data.slice(offset, end)).trim();
+}
+async function extractPromptFiles(tarballBuffer) {
+  const decompressed = await decompressGzip(tarballBuffer);
+  const entries = parseTar(decompressed);
+  const promptFiles = [];
+  for (const entry of entries) {
+    const normalizedName = entry.name.replace(/^package\//, "");
+    if (normalizedName.startsWith("prompts/") && normalizedName.endsWith(".prompt")) {
+      const filename = normalizedName.split("/").pop();
+      const content = new TextDecoder("utf-8").decode(entry.content);
+      promptFiles.push({ filename, content });
+    }
+  }
+  return promptFiles;
+}
+class NpmRegistryPromptSource {
+  constructor(specifier, options) {
+    __publicField(this, "packageName");
+    __publicField(this, "version");
+    __publicField(this, "tarballUrl");
+    __publicField(this, "registryUrl");
+    this.registryUrl = (options == null ? void 0 : options.registryUrl) ?? "https://registry.npmjs.org";
+    if (specifier.startsWith("https://") || specifier.startsWith("http://")) {
+      this.tarballUrl = specifier;
+    } else {
+      const { name, version } = this.parseSpecifier(specifier);
+      this.packageName = name;
+      this.version = version;
+    }
+  }
+  /**
+   * Create an NpmRegistryPromptSource from a direct tarball URL.
+   */
+  static fromUrl(url) {
+    return new NpmRegistryPromptSource(url);
+  }
+  async getPrompts() {
+    const tarballUrl = this.tarballUrl ?? await this.resolveTarballUrl();
+    const tarballBuffer = await this.downloadTarball(tarballUrl);
+    return extractPromptFiles(tarballBuffer);
+  }
+  /**
+   * Parse a package specifier into name and optional version.
+   */
+  parseSpecifier(specifier) {
+    if (specifier.startsWith("@")) {
+      const atIndex2 = specifier.indexOf("@", 1);
+      if (atIndex2 !== -1) {
+        return {
+          name: specifier.slice(0, atIndex2),
+          version: specifier.slice(atIndex2 + 1)
+        };
+      }
+      return { name: specifier };
+    }
+    const atIndex = specifier.indexOf("@");
+    if (atIndex !== -1) {
+      return {
+        name: specifier.slice(0, atIndex),
+        version: specifier.slice(atIndex + 1)
+      };
+    }
+    return { name: specifier };
+  }
+  /**
+   * Resolve the tarball URL by fetching package metadata from the registry.
+   */
+  async resolveTarballUrl() {
+    var _a2;
+    const version = this.version ?? "latest";
+    const url = `${this.registryUrl}/${this.packageName}/${version}`;
+    let response;
+    try {
+      response = await fetch(url);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new Error(`Fetch failed for "${this.packageName}@${version}": ${message}`);
+    }
+    if (!response.ok) {
+      throw new Error(
+        `Fetch failed for "${this.packageName}@${version}": HTTP ${response.status} ${response.statusText}`
+      );
+    }
+    const metadata = await response.json();
+    if (!((_a2 = metadata.dist) == null ? void 0 : _a2.tarball)) {
+      throw new Error(
+        `No tarball URL found in registry metadata for "${this.packageName}@${version}"`
+      );
+    }
+    return metadata.dist.tarball;
+  }
+  /**
+   * Download a tarball from the given URL.
+   */
+  async downloadTarball(url) {
+    let response;
+    try {
+      response = await fetch(url);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new Error(`Fetch failed for tarball at "${url}": ${message}`);
+    }
+    if (!response.ok) {
+      throw new Error(
+        `Fetch failed for tarball at "${url}": HTTP ${response.status} ${response.statusText}`
+      );
+    }
+    return response.arrayBuffer();
+  }
+}
+const npmRegistryPromptSource = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.defineProperty({
+  __proto__: null,
+  NpmRegistryPromptSource
+}, Symbol.toStringTag, { value: "Module" }));
 const CDN_TEMPLATES = {
   "esm.sh": "https://esm.sh/{name}@{version}",
   "unpkg": "https://unpkg.com/{name}@{version}",
@@ -43515,18 +44150,7 @@ class Role extends Component {
       children
     } = props;
     if (this.hasContent(children)) {
-      const parts2 = [children];
-      if (expertise) {
-        const expertiseStr = Array.isArray(expertise) ? expertise.join(", ") : expertise;
-        parts2.push(`
-with expertise in ${expertiseStr}`);
-      }
-      if (domain) {
-        parts2.push(`
-specializing in the ${domain} domain`);
-      }
-      const content = parts2.length === 1 ? parts2[0] : parts2;
-      return wrapWithDelimiter(content, "role", delimiter);
+      return wrapWithDelimiter(children, "role", delimiter);
     }
     const config = preset ? ROLE_PRESETS[preset] : void 0;
     const provider = this.getProvider(context);
@@ -43962,6 +44586,37 @@ class References extends Component {
   }
 }
 __publicField(References, "schema", referencesSchema);
+const chainOfThoughtSchema = objectType({
+  style: enumType(["step-by-step", "think-aloud", "structured", "minimal"]).optional(),
+  showReasoning: booleanType().optional(),
+  delimiter: enumType(["xml", "markdown", "none"]).optional()
+}).passthrough();
+const STYLE_INSTRUCTIONS = {
+  "step-by-step": "Think through this step by step before providing your answer.",
+  "think-aloud": "Reason through your thought process as you work on this.",
+  "structured": "Break down your reasoning into: 1) Understanding, 2) Analysis, 3) Conclusion.",
+  "minimal": "Consider the problem carefully before answering."
+};
+class ChainOfThought extends Component {
+  render(props, _resolvedValue, _context) {
+    const { style = "step-by-step", showReasoning = true, delimiter = "xml", children } = props;
+    const sections = [];
+    if (this.hasContent(children)) {
+      const parts = [children];
+      if (showReasoning) {
+        parts.push("\nShow your reasoning process.");
+      }
+      return wrapWithDelimiter(parts, "reasoning", delimiter);
+    }
+    sections.push(STYLE_INSTRUCTIONS[style]);
+    if (showReasoning) {
+      sections.push("Show your reasoning process.");
+    }
+    const content = sections.join("\n");
+    return wrapWithDelimiter(content, "reasoning", delimiter);
+  }
+}
+__publicField(ChainOfThought, "schema", chainOfThoughtSchema);
 const promptDefaultsObjectSchema = objectType({
   role: booleanType().optional(),
   format: booleanType().optional(),
@@ -44028,7 +44683,7 @@ class Prompt extends Component {
         component: "Prompt",
         prop: null,
         message: "Prompt has no Task child. Consider adding a <Task> element to define the objective.",
-        code: "validation_warning",
+        code: "warn_missing_task",
         path: []
       });
     }
@@ -44039,6 +44694,23 @@ class Prompt extends Component {
     findChildrenOfType(childArray, EdgeCases).length > 0;
     findChildrenOfType(childArray, Fallbacks).length > 0;
     findChildrenOfType(childArray, References).length > 0;
+    if (hasFormat) {
+      const formatElements = findChildrenOfType(childArray, Format);
+      const cotElements = findChildrenOfType(childArray, ChainOfThought);
+      if (cotElements.length > 0) {
+        const formatIsStrict = formatElements.some((el) => el[PROPS].strict === true);
+        const cotShowsReasoning = cotElements.some((el) => el[PROPS].showReasoning !== false);
+        if (formatIsStrict && cotShowsReasoning) {
+          context.errors.push({
+            component: "Prompt",
+            prop: null,
+            message: "<Format strict> and <ChainOfThought showReasoning> produce contradictory instructions. Format strict tells the LLM to return ONLY formatted output, while ChainOfThought asks it to show reasoning. Consider setting showReasoning={false} or removing strict.",
+            code: "warn_conflicting_instructions",
+            path: []
+          });
+        }
+      }
+    }
     const sections = [];
     const includeRole = this.shouldIncludeSection(resolvedDefaults.role, promptConfig.includeRole);
     if (includeRole && !hasRole) {
@@ -45674,37 +46346,6 @@ class Steps extends Component {
   }
 }
 __publicField(Steps, "schema", stepsSchema);
-const chainOfThoughtSchema = objectType({
-  style: enumType(["step-by-step", "think-aloud", "structured", "minimal"]).optional(),
-  showReasoning: booleanType().optional(),
-  delimiter: enumType(["xml", "markdown", "none"]).optional()
-}).passthrough();
-const STYLE_INSTRUCTIONS = {
-  "step-by-step": "Think through this step by step before providing your answer.",
-  "think-aloud": "Reason through your thought process as you work on this.",
-  "structured": "Break down your reasoning into: 1) Understanding, 2) Analysis, 3) Conclusion.",
-  "minimal": "Consider the problem carefully before answering."
-};
-class ChainOfThought extends Component {
-  render(props, _resolvedValue, _context) {
-    const { style = "step-by-step", showReasoning = true, delimiter = "xml", children } = props;
-    const sections = [];
-    if (this.hasContent(children)) {
-      const parts = [children];
-      if (showReasoning) {
-        parts.push("\nShow your reasoning process.");
-      }
-      return wrapWithDelimiter(parts, "reasoning", delimiter);
-    }
-    sections.push(STYLE_INSTRUCTIONS[style]);
-    if (showReasoning) {
-      sections.push("Show your reasoning process.");
-    }
-    const content = sections.join("\n");
-    return wrapWithDelimiter(content, "reasoning", delimiter);
-  }
-}
-__publicField(ChainOfThought, "schema", chainOfThoughtSchema);
 const codeSchema = objectType({
   language: stringType().optional(),
   filename: stringType().optional()
@@ -45981,49 +46622,6 @@ const _allComponentExports = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Objec
   WhenUncertain,
   Xml
 }, Symbol.toStringTag, { value: "Module" }));
-const CUSTOM_COMPONENTS_GLOBAL = "__PUPT_CUSTOM_COMPONENTS__";
-async function createPromptFromSource(source, filename, options = {}) {
-  const { components } = options;
-  let processedSource = preprocessSource(source, { filename });
-  if (components && Object.keys(components).length > 0) {
-    globalThis[CUSTOM_COMPONENTS_GLOBAL] = components;
-    const componentNames = Object.keys(components);
-    const extractCode = `const { ${componentNames.join(", ")} } = globalThis.${CUSTOM_COMPONENTS_GLOBAL};
-`;
-    let lastImportEnd = 0;
-    const fullImportRegex = /import\s+(?:(?:\{[^}]*\}|[^;{]*)\s+from\s+)?['"][^'"]+['"];?/g;
-    let match;
-    while ((match = fullImportRegex.exec(processedSource)) !== null) {
-      const matchEnd = match.index + match[0].length;
-      if (matchEnd > lastImportEnd) {
-        lastImportEnd = matchEnd;
-      }
-    }
-    if (lastImportEnd > 0) {
-      processedSource = processedSource.slice(0, lastImportEnd) + "\n" + extractCode + processedSource.slice(lastImportEnd);
-    } else {
-      processedSource = extractCode + processedSource;
-    }
-  }
-  try {
-    const transformer = new Transformer2();
-    const code = await transformer.transformSourceAsync(processedSource, filename);
-    const module = await evaluateModule(code, { filename });
-    if (module.default === void 0) {
-      throw new Error(`${filename} must have a default export`);
-    }
-    return module.default;
-  } finally {
-    if (components) {
-      delete globalThis[CUSTOM_COMPONENTS_GLOBAL];
-    }
-  }
-}
-async function createPrompt(filePath, options = {}) {
-  const { readFile } = await import("fs/promises");
-  const source = await readFile(filePath, "utf-8");
-  return createPromptFromSource(source, filePath, options);
-}
 const ENTRIES = "ENTRIES";
 const KEYS = "KEYS";
 const VALUES = "VALUES";
@@ -47903,6 +48501,7 @@ class Pupt {
     __publicField(this, "moduleLoader", new ModuleLoader());
     __publicField(this, "searchEngine");
     __publicField(this, "prompts", []);
+    __publicField(this, "warnings", []);
     __publicField(this, "initialized", false);
     this.config = config;
     this.searchEngine = createSearchEngine(config.searchConfig);
@@ -47929,6 +48528,9 @@ class Pupt {
   getPrompt(name) {
     return this.prompts.find((p) => p.name === name);
   }
+  getPromptById(id) {
+    return this.prompts.find((p) => p.id === id);
+  }
   searchPrompts(query, options) {
     return this.searchEngine.search(query, options);
   }
@@ -47938,31 +48540,80 @@ class Pupt {
   getPromptsByTag(tag) {
     return this.prompts.filter((p) => p.tags.includes(tag));
   }
+  getWarnings() {
+    return [...this.warnings];
+  }
   async discoverPrompts() {
+    var _a2;
     const discovered = [];
-    for (const source of this.config.modules ?? []) {
-      const library = await this.moduleLoader.load(source);
+    const processedLibraries = /* @__PURE__ */ new Set();
+    for (const entry of this.config.modules ?? []) {
       try {
-        const moduleExports = await this.loadModuleExports(source);
-        for (const [, value] of Object.entries(moduleExports)) {
-          if (this.isPromptElement(value)) {
-            const element = value;
-            const props = element[PROPS];
-            const prompt = this.createDiscoveredPrompt(
-              props.name,
-              props.description ?? "",
-              props.tags ?? [],
-              library.name,
-              element
-            );
-            discovered.push(prompt);
+        const dedupKey = this.getEntryDedupKey(entry);
+        if (dedupKey !== null) {
+          if (processedLibraries.has(dedupKey)) {
+            continue;
           }
+          processedLibraries.add(dedupKey);
+        }
+        const library = await this.moduleLoader.loadEntry(entry);
+        for (const compiled of Object.values(library.prompts)) {
+          const prompt = this.createDiscoveredPrompt(
+            compiled.id,
+            compiled.name,
+            compiled.description,
+            compiled.tags,
+            library.name,
+            compiled.element
+          );
+          discovered.push(prompt);
         }
-      } catch {
+        if (typeof entry === "string" && !isPromptSource(entry)) {
+          try {
+            const moduleExports = await this.loadModuleExports(entry);
+            for (const [, value] of Object.entries(moduleExports)) {
+              if (this.isPromptElement(value)) {
+                const element = value;
+                const props = element[PROPS];
+                const prompt = this.createDiscoveredPrompt(
+                  crypto.randomUUID(),
+                  props.name,
+                  props.description ?? "",
+                  props.tags ?? [],
+                  library.name,
+                  element
+                );
+                discovered.push(prompt);
+              }
+            }
+          } catch {
+          }
+        }
+      } catch (error) {
+        const sourceId = typeof entry === "string" ? entry : isPromptSource(entry) ? ((_a2 = entry.constructor) == null ? void 0 : _a2.name) ?? "PromptSource" : `{ source: ${entry.source} }`;
+        const message = error instanceof Error ? error.message : String(error);
+        this.warnings.push(`Failed to load module "${sourceId}": ${message}`);
       }
     }
     return discovered;
   }
+  /**
+   * Get a deduplication key for a module entry.
+   * Returns null for PromptSource instances (cannot be deduplicated).
+   */
+  getEntryDedupKey(entry) {
+    if (typeof entry === "string") {
+      return this.moduleLoader.normalizeSource(entry);
+    }
+    if (isPromptSource(entry)) {
+      return null;
+    }
+    if (typeof entry === "object" && entry !== null && "source" in entry && "config" in entry) {
+      const ref = entry;
+      return `pkg:${ref.source}:${JSON.stringify(ref.config)}`;
+    }
+    return null;
+  }
   async loadModuleExports(source) {
     var _a2;
     const isNode2 = typeof process !== "undefined" && ((_a2 = process.versions) == null ? void 0 : _a2.node);
@@ -47985,8 +48636,9 @@ class Pupt {
     const props = value[PROPS];
     return props !== null && typeof props === "object" && "name" in props;
   }
-  createDiscoveredPrompt(name, description, tags, library, element) {
+  createDiscoveredPrompt(id, name, description, tags, library, element) {
     return {
+      id,
       name,
       description,
       tags,
@@ -48348,14 +49000,18 @@ export {
   FileSearchEngine,
   ForEach,
   Format,
+  GitHubPromptSource,
   Guardrails,
   Hostname,
   If,
   Json,
   LANGUAGE_CONVENTIONS,
   LLM_PROVIDERS,
+  LocalPromptSource,
   ModuleLoader,
   NegativeExample,
+  NpmLocalPromptSource,
+  NpmRegistryPromptSource,
   Objective,
   OpenUrl,
   PROPS,
@@ -48416,8 +49072,11 @@ export {
   isDeferredRef,
   isElementOfType,
   isPromptFile,
+  isPromptSource,
   isPuptElement,
+  isWarningCode,
   loadNodeModules,
+  parseGitHubSource,
   partitionChildren,
   preprocessSource,
   render,