promptopskit 0.3.8 → 0.4.0

package/dist/cli/index.js

@@ -39,7 +39,66 @@ var SamplingSchema = z.object({
 });
 var ResponseSchema = z.object({
   format: z.enum(["text", "json", "markdown"]).optional(),
-  stream: z.boolean().optional()
+  stream: z.boolean().optional(),
+  schema: z.record(z.unknown()).optional(),
+  schema_name: z.string().optional(),
+  schema_description: z.string().optional(),
+  schema_strict: z.boolean().optional()
+});
+var AnthropicProviderOptionsSchema = z.object({
+  top_k: z.number().int().min(0).optional(),
+  tool_choice: z.record(z.unknown()).optional(),
+  output_config: z.record(z.unknown()).optional()
+});
+var GeminiProviderOptionsSchema = z.object({
+  candidate_count: z.number().int().positive().optional(),
+  top_k: z.number().int().min(0).optional(),
+  seed: z.number().int().optional(),
+  response_schema: z.record(z.unknown()).optional(),
+  response_json_schema: z.record(z.unknown()).optional(),
+  response_modalities: z.array(z.string()).optional(),
+  thinking_budget_tokens: z.number().int().positive().optional()
+});
+var OpenRouterProviderOptionsSchema = z.object({
+  provider: z.record(z.unknown()).optional(),
+  transforms: z.array(z.string()).optional(),
+  plugins: z.array(z.record(z.unknown())).optional(),
+  models: z.array(z.string()).optional()
+});
+var ProviderOptionsSchema = z.object({
+  anthropic: AnthropicProviderOptionsSchema.optional(),
+  gemini: GeminiProviderOptionsSchema.optional(),
+  openrouter: OpenRouterProviderOptionsSchema.optional()
+});
+var RawProviderBodySchema = z.object({
+  openai: z.record(z.unknown()).optional(),
+  "openai-responses": z.record(z.unknown()).optional(),
+  openai_responses: z.record(z.unknown()).optional(),
+  anthropic: z.record(z.unknown()).optional(),
+  gemini: z.record(z.unknown()).optional(),
+  google: z.record(z.unknown()).optional(),
+  openrouter: z.record(z.unknown()).optional()
+});
+var OpenAICacheSchema = z.object({
+  prompt_cache_key: z.string().min(1).optional(),
+  retention: z.enum(["in_memory", "24h"]).optional()
+});
+var AnthropicCacheSchema = z.object({
+  mode: z.enum(["automatic", "explicit"]).optional(),
+  type: z.literal("ephemeral").optional(),
+  ttl: z.enum(["5m", "1h"]).optional(),
+  cache_system_instructions: z.boolean().optional(),
+  cache_tools: z.boolean().optional(),
+  cache_prompt_template: z.boolean().optional()
+});
+var GeminiCacheSchema = z.object({
+  cached_content: z.string().min(1).optional()
+});
+var CacheSchema = z.object({
+  openai: OpenAICacheSchema.optional(),
+  anthropic: AnthropicCacheSchema.optional(),
+  gemini: GeminiCacheSchema.optional(),
+  google: GeminiCacheSchema.optional()
 });
 var HistorySchema = z.object({
   max_items: z.number().int().positive().optional()
@@ -90,7 +149,10 @@ var PromptAssetOverridesSchema = z.object({
   reasoning: ReasoningSchema.optional(),
   sampling: SamplingSchema.optional(),
   response: ResponseSchema.optional(),
-  tools: z.array(ToolRefSchema).optional()
+  cache: CacheSchema.optional(),
+  raw: RawProviderBodySchema.optional(),
+  tools: z.array(ToolRefSchema).optional(),
+  provider_options: ProviderOptionsSchema.optional()
 });
 var SourceSchema = z.object({
   file_path: z.string().optional(),
@@ -102,8 +164,9 @@ var SectionsSchema = z.object({
   notes: z.string().optional()
 });
 var PromptDefaultsSchema = z.object({
-  provider: z.enum(["openai", "anthropic", "google", "gemini", "openrouter", "any"]).optional(),
+  provider: z.enum(["openai", "openai-responses", "anthropic", "google", "gemini", "openrouter", "any"]).optional(),
   model: z.string().optional(),
+  cache: CacheSchema.optional(),
   metadata: MetadataSchema.optional(),
   sections: z.object({
     system_instructions: z.string().optional()
@@ -113,13 +176,16 @@ var PromptAssetSchema = z.object({
   id: z.string(),
   schema_version: z.number().int().positive().default(1),
   description: z.string().optional(),
-  provider: z.enum(["openai", "anthropic", "google", "gemini", "openrouter", "any"]).optional(),
+  provider: z.enum(["openai", "openai-responses", "anthropic", "google", "gemini", "openrouter", "any"]).optional(),
   model: z.string().optional(),
   fallback_models: z.array(z.string()).optional(),
   reasoning: ReasoningSchema.optional(),
   sampling: SamplingSchema.optional(),
   response: ResponseSchema.optional(),
+  cache: CacheSchema.optional(),
+  raw: RawProviderBodySchema.optional(),
   tools: z.array(ToolRefSchema).optional(),
+  provider_options: ProviderOptionsSchema.optional(),
   mcp: MCPSchema.optional(),
   context: ContextSchema.optional(),
   includes: z.array(z.string()).optional(),
@@ -131,6 +197,123 @@ var PromptAssetSchema = z.object({
   source: SourceSchema.optional()
 });
 
+// src/parser/frontmatter-guard.ts
+var FRONT_MATTER_DELIMITER = /^---[ \t]*$/;
+var REGEX_FIELD = /^(?<indent>\s*)(?<field>allow_regex|deny_regex)\s*:\s*(?<value>.*)$/;
+var PATTERN_FIELD = /^(?<indent>\s*)pattern\s*:\s*(?<value>.*)$/;
+var INLINE_PATTERN_FIELD = /(?:^|[{,]\s*)pattern\s*:\s*(?<value>"(?:\\.|[^"\\])*")/;
+function assertRegexFrontMatterQuoting(content, filePath) {
+  const frontMatter = extractFrontMatter(content);
+  if (!frontMatter) {
+    return;
+  }
+  let pendingRegex;
+  for (const [index, line] of frontMatter.lines.entries()) {
+    const lineNumber = frontMatter.startLine + index;
+    const regexMatch = line.match(REGEX_FIELD);
+    if (regexMatch?.groups) {
+      const field = regexMatch.groups.field;
+      const indent2 = regexMatch.groups.indent.length;
+      const value = regexMatch.groups.value.trim();
+      pendingRegex = value === "" ? { field, indent: indent2 } : void 0;
+      assertNoUnescapedBackslashInDoubleQuotedRegex(value, field, filePath, lineNumber);
+      assertNoUnescapedBackslashInInlinePattern(value, field, filePath, lineNumber);
+      continue;
+    }
+    if (!pendingRegex) {
+      continue;
+    }
+    if (line.trim() === "" || line.trimStart().startsWith("#")) {
+      continue;
+    }
+    const indent = line.match(/^\s*/)?.[0].length ?? 0;
+    if (indent <= pendingRegex.indent) {
+      pendingRegex = void 0;
+      continue;
+    }
+    const patternMatch = line.match(PATTERN_FIELD);
+    if (!patternMatch?.groups) {
+      continue;
+    }
+    assertNoUnescapedBackslashInDoubleQuotedRegex(
+      patternMatch.groups.value.trim(),
+      `${pendingRegex.field}.pattern`,
+      filePath,
+      lineNumber
+    );
+  }
+}
+function assertNoUnescapedBackslashInInlinePattern(value, field, filePath, lineNumber) {
+  const match = value.match(INLINE_PATTERN_FIELD);
+  const pattern = match?.groups?.value;
+  if (!pattern) {
+    return;
+  }
+  assertNoUnescapedBackslashInDoubleQuotedRegex(pattern, `${field}.pattern`, filePath, lineNumber);
+}
+function extractFrontMatter(content) {
+  const lines = content.split(/\r?\n/);
+  if (!FRONT_MATTER_DELIMITER.test(lines[0] ?? "")) {
+    return void 0;
+  }
+  for (let index = 1; index < lines.length; index += 1) {
+    if (FRONT_MATTER_DELIMITER.test(lines[index] ?? "")) {
+      return {
+        lines: lines.slice(1, index),
+        startLine: 2
+      };
+    }
+  }
+  return void 0;
+}
+function assertNoUnescapedBackslashInDoubleQuotedRegex(value, field, filePath, lineNumber) {
+  if (!value.startsWith('"')) {
+    return;
+  }
+  const quoted = readDoubleQuotedScalar(value);
+  if (!quoted) {
+    return;
+  }
+  if (!hasUnescapedBackslash(quoted)) {
+    return;
+  }
+  const location = filePath ? `${filePath}:${lineNumber}` : `line ${lineNumber}`;
+  throw new Error(
+    `POK013: Invalid context regex YAML at ${location}, field "${field}": double-quoted regex strings treat backslashes as YAML escapes. Use unquoted /pattern/i literal form, single quotes, or double each backslash.`
+  );
+}
+function readDoubleQuotedScalar(value) {
+  let result = "";
+  for (let index = 1; index < value.length; index += 1) {
+    const char = value[index];
+    if (char === '"') {
+      return result;
+    }
+    result += char;
+    if (char === "\\" && index + 1 < value.length) {
+      index += 1;
+      result += value[index];
+    }
+  }
+  return void 0;
+}
+function hasUnescapedBackslash(value) {
+  for (let index = 0; index < value.length; index += 1) {
+    if (value[index] !== "\\") {
+      continue;
+    }
+    let count = 1;
+    while (value[index + count] === "\\") {
+      count += 1;
+    }
+    if (count % 2 === 1) {
+      return true;
+    }
+    index += count - 1;
+  }
+  return false;
+}
+
 // src/parser/sections.ts
 var SECTION_MAP = {
   "system instructions": "system_instructions",
@@ -171,6 +354,7 @@ function extractSections(body) {
 
 // src/parser/parser.ts
 function parsePrompt(content, filePath) {
+  assertRegexFrontMatterQuoting(content, filePath);
   const { data: frontMatter, content: body } = matter(content);
   const sections = extractSections(body);
   const raw = {
@@ -496,8 +680,22 @@ var KNOWN_FRONT_MATTER_KEYS = /* @__PURE__ */ new Set([
   "includes",
   "environments",
   "tiers",
-  "metadata"
+  "metadata",
+  "cache",
+  "provider_options",
+  "raw"
 ]);
+var RISKY_UNBOUNDED_INPUT_NAMES = [
+  "message",
+  "prompt",
+  "history",
+  "transcript",
+  "document",
+  "content",
+  "input",
+  "body",
+  "context"
+];
 function validateAsset(asset, frontMatterKeys, filePath) {
   const errors = [];
   const warnings = [];
@@ -568,7 +766,32 @@ function validateAsset(asset, frontMatterKeys, filePath) {
       });
     }
   }
+  if (usedVars.size > 0 && (!asset.context?.inputs || asset.context.inputs.length === 0)) {
+    warnings.push({
+      code: "POK046",
+      message: `Template uses ${usedVars.size === 1 ? "a variable" : "variables"} but context.inputs is not declared.`,
+      filePath,
+      suggestion: "Declare context.inputs to enable input policy validation."
+    });
+  }
   for (const input of getContextInputs(asset)) {
+    const lowerName = input.name.toLowerCase();
+    if (input.max_size === void 0 && RISKY_UNBOUNDED_INPUT_NAMES.some((needle) => lowerName.includes(needle))) {
+      warnings.push({
+        code: "POK040",
+        message: `Context input "${input.name}" has no max_size and appears unbounded.`,
+        filePath,
+        suggestion: "Add max_size to constrain prompt payload growth."
+      });
+    }
+    if (input.allow_regex === void 0 && input.deny_regex === void 0 && input.non_empty === void 0 && input.reject_secrets === void 0) {
+      warnings.push({
+        code: "POK041",
+        message: `Context input "${input.name}" has no input hardening validators.`,
+        filePath,
+        suggestion: "Consider non_empty/reject_secrets and allow/deny regex validators."
+      });
+    }
     if (input.trim !== void 0 && input.trim !== false && input.max_size === void 0) {
       warnings.push({
         code: "POK014",
@@ -596,6 +819,91 @@ function validateAsset(asset, frontMatterKeys, filePath) {
       }
     }
   }
+  if (asset.provider) {
+    let providerCache;
+    let cacheSuggestionField;
+    switch (asset.provider) {
+      case "openai":
+        providerCache = asset.cache?.openai;
+        cacheSuggestionField = "cache.openai";
+        break;
+      case "anthropic":
+        providerCache = asset.cache?.anthropic;
+        cacheSuggestionField = "cache.anthropic";
+        break;
+      case "gemini":
+      case "google":
+        providerCache = asset.cache?.gemini ?? asset.cache?.google;
+        cacheSuggestionField = "cache.gemini";
+        break;
+      default:
+        break;
+    }
+    if (cacheSuggestionField && providerCache === void 0) {
+      warnings.push({
+        code: "POK042",
+        message: `Provider "${asset.provider}" has no provider-specific cache settings.`,
+        filePath,
+        suggestion: `Consider configuring ${cacheSuggestionField} for better cache-hit behavior.`
+      });
+    }
+    if (!asset.model) {
+      warnings.push({
+        code: "POK044",
+        message: `Provider "${asset.provider}" is configured without a model.`,
+        filePath,
+        suggestion: "Set model in prompt or defaults to avoid adapter-time errors."
+      });
+    }
+  }
+  if (asset.cache?.gemini?.cached_content && asset.cache.google?.cached_content && asset.cache.gemini.cached_content !== asset.cache.google.cached_content) {
+    warnings.push({
+      code: "POK043",
+      message: "cache.gemini.cached_content and cache.google.cached_content are both set to different values.",
+      filePath,
+      suggestion: "Use one canonical value; Gemini prefers cache.gemini.cached_content."
+    });
+  }
+  for (const [envName, overrides] of Object.entries(asset.environments ?? {})) {
+    if (asset.cache && (!isRecord(overrides) || !overrides.cache)) {
+      warnings.push({
+        code: "POK045",
+        message: `Environment "${envName}" does not override cache while prompt-level cache is defined.`,
+        filePath,
+        suggestion: "Confirm cache strategy is intentionally shared across environments."
+      });
+    }
+  }
+  for (const [tierName, overrides] of Object.entries(asset.tiers ?? {})) {
+    if (asset.cache && (!isRecord(overrides) || !overrides.cache)) {
+      warnings.push({
+        code: "POK045",
+        message: `Tier "${tierName}" does not override cache while prompt-level cache is defined.`,
+        filePath,
+        suggestion: "Confirm cache strategy is intentionally shared across tiers."
+      });
+    }
+  }
+  for (const tool of asset.tools ?? []) {
+    if (isRecord(tool)) {
+      if (!tool.description) {
+        warnings.push({
+          code: "POK047",
+          message: `Inline tool "${tool.name}" is missing a description.`,
+          filePath,
+          suggestion: "Add description to improve model tool-selection quality."
+        });
+      }
+      if (!tool.input_schema) {
+        warnings.push({
+          code: "POK047",
+          message: `Inline tool "${tool.name}" is missing input_schema.`,
+          filePath,
+          suggestion: "Add input_schema so tool inputs are strongly typed."
+        });
+      }
+    }
+  }
   return {
     valid: errors.length === 0,
     errors,
@@ -632,6 +940,9 @@ function findClosestMatch(input, candidates) {
   }
   return best;
 }
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
 
 // src/prompt-resolution.ts
 import { readFile as readFile3 } from "fs/promises";
@@ -712,8 +1023,53 @@ function mergeOverride(base, override) {
   if (override.response !== void 0) {
     result.response = { ...result.response, ...override.response };
   }
+  if (override.cache !== void 0) {
+    result.cache = {
+      ...result.cache,
+      ...override.cache,
+      openai: mergeRecordBlock(result.cache?.openai, override.cache.openai),
+      anthropic: mergeRecordBlock(result.cache?.anthropic, override.cache.anthropic),
+      gemini: mergeRecordBlock(result.cache?.gemini, override.cache.gemini),
+      google: mergeRecordBlock(result.cache?.google, override.cache.google)
+    };
+  }
+  if (override.raw !== void 0) {
+    result.raw = {
+      ...result.raw,
+      ...override.raw,
+      openai: mergeRecordBlock(result.raw?.openai, override.raw.openai),
+      "openai-responses": mergeRecordBlock(result.raw?.["openai-responses"], override.raw["openai-responses"]),
+      openai_responses: mergeRecordBlock(result.raw?.openai_responses, override.raw.openai_responses),
+      anthropic: mergeRecordBlock(result.raw?.anthropic, override.raw.anthropic),
+      gemini: mergeRecordBlock(result.raw?.gemini, override.raw.gemini),
+      google: mergeRecordBlock(result.raw?.google, override.raw.google),
+      openrouter: mergeRecordBlock(result.raw?.openrouter, override.raw.openrouter)
+    };
+  }
+  if (override.provider_options !== void 0) {
+    result.provider_options = {
+      ...result.provider_options,
+      ...override.provider_options,
+      anthropic: {
+        ...result.provider_options?.anthropic,
+        ...override.provider_options.anthropic
+      },
+      gemini: {
+        ...result.provider_options?.gemini,
+        ...override.provider_options.gemini
+      },
+      openrouter: {
+        ...result.provider_options?.openrouter,
+        ...override.provider_options.openrouter
+      }
+    };
+  }
   return result;
 }
+function mergeRecordBlock(base, override) {
+  if (override === void 0) return base;
+  return { ...base, ...override };
+}
 
 // src/prompt-resolution.ts
 var DEFAULT_PROMPTS_DIR = "./prompts";
@@ -1097,7 +1453,7 @@ async function inspect(args) {
 
 // src/cli/commands/init.ts
 import { writeFile as writeFile2, mkdir as mkdir2 } from "fs/promises";
-import { join as join5, dirname as dirname5 } from "path";
+import { join as join5, dirname as dirname5, relative as relative2 } from "path";
 import { existsSync as existsSync4, readFileSync } from "fs";
 var HELP5 = `
 promptopskit init [dir]
@@ -1118,6 +1474,11 @@ context:
     - app_context
 includes:
   - ./shared/tone.md
+cache:
+  openai:
+    # Keep this stable across requests that share a long static prefix.
+    prompt_cache_key: hello-v1
+    retention: in_memory
 reasoning:
   effort: high
 environments:
@@ -1164,10 +1525,14 @@ var TEST_SIDECAR = `cases:
     variables:
       name: "World"
       app_context: "Welcome screen"
+    response:
+      message: "Hello, World! How can I help you today?"
   - name: named-greeting
     variables:
       name: "Alice"
       app_context: "Settings page"
+    response:
+      message: "Hello, Alice! How can I help you today?"
 `;
 var EXAMPLE_USAGE = `// Example: render the hello prompt and send it to OpenAI
 // Full docs: https://promptopskit.com/docs/index.html#/
@@ -1239,12 +1604,16 @@ async function init(args) {
     return;
   }
   const dir = args.find((a) => !a.startsWith("--")) ?? "./prompts";
+  const testFilePath = join5(dirname5(dir), "tests", "hello.prompt.test.mjs");
+  const promptsDirFromTest = relative2(dirname5(testFilePath), dir) || ".";
+  const helloPromptTest = createHelloPromptTest(promptsDirFromTest);
   const files = [
     { path: join5(dir, "defaults.md"), content: DEFAULTS },
     { path: join5(dir, "hello.md"), content: HELLO_PROMPT },
     { path: join5(dir, "hello.test.yaml"), content: TEST_SIDECAR },
     { path: join5(dir, "shared", "tone.md"), content: TONE_INCLUDE },
-    { path: join5(dir, "example-usage.ts"), content: EXAMPLE_USAGE }
+    { path: join5(dir, "example-usage.ts"), content: EXAMPLE_USAGE },
+    { path: testFilePath, content: helloPromptTest }
   ];
   let created = 0;
   let skipped = 0;
@@ -1269,10 +1638,57 @@ async function init(args) {
         console.log(`Tip: Add to your package.json scripts:`);
         console.log(`  "build:prompts": "promptopskit compile ${dir}"`);
       }
+      if (!pkg.scripts?.test) {
+        console.log();
+        console.log(`Tip: Add a test script to run the generated prompt test:`);
+        console.log(`  "test": "node --test tests/*.test.mjs"`);
+      }
     } catch {
     }
   }
 }
+function createHelloPromptTest(promptsDirFromTest) {
+  return `import assert from 'node:assert/strict';
+import { dirname, resolve } from 'node:path';
+import test from 'node:test';
+import { fileURLToPath } from 'node:url';
+import { createPromptOpsKit } from 'promptopskit';
+import {
+  getHardcodedPromptResponse,
+  loadPromptTestSidecar,
+  renderPromptTestCase,
+} from 'promptopskit/testing';
+
+const testDir = dirname(fileURLToPath(import.meta.url));
+const promptsDir = resolve(testDir, ${JSON.stringify(promptsDirFromTest)});
+
+test('hello prompt renders every sidecar case', async () => {
+  const kit = createPromptOpsKit({ sourceDir: promptsDir, cache: false });
+  const sidecar = await loadPromptTestSidecar(resolve(promptsDir, 'hello.test.yaml'));
+
+  for (const testCase of sidecar.cases) {
+    const { rendered } = await renderPromptTestCase(kit, {
+      sidecar,
+      caseName: testCase.name,
+      path: 'hello',
+      provider: 'openai',
+      environment: 'dev',
+      strict: true,
+    });
+
+    assert.ok(rendered.request?.body?.messages);
+  }
+});
+
+test('hello prompt can return a deterministic response without calling a model', async () => {
+  const sidecar = await loadPromptTestSidecar(resolve(promptsDir, 'hello.test.yaml'));
+
+  assert.deepEqual(getHardcodedPromptResponse(sidecar, 'basic-greeting'), {
+    message: 'Hello, World! How can I help you today?',
+  });
+});
+`;
+}
 
 // src/cli/commands/skill.ts
 import { writeFile as writeFile3, readFile as readFile5, mkdir as mkdir3 } from "fs/promises";