promptopskit 0.3.1 → 0.3.3

package/README.md

@@ -205,6 +205,32 @@ const request = openaiAdapter.render(prompt, {
 });
 ```
 
+In browser or client-side code, keep provider credentials on the server. Use the rendered request body with your own server endpoint, server action, or edge function rather than calling a provider directly from the client.
+
+On the server, adapters also provide async prompt-aware helpers so you can pass a prompt key plus `sourceDir` and `compiledDir` without creating a `PromptOpsKit` instance:
+
+```typescript
+import path from 'node:path';
+import { openaiAdapter } from 'promptopskit/openai';
+
+const request = await openaiAdapter.renderPrompt(
+  {
+    path: 'summarizePullRequest',
+    sourceDir: path.join(process.cwd(), 'prompts'),
+    compiledDir: path.join(process.cwd(), 'output-json'),
+  },
+  {
+    environment: 'dev',
+    variables: {
+      pull_request_body: 'Implement theming and dark mode across the app.',
+    },
+    strict: true,
+  },
+);
+```
+
+`renderPrompt()` and `validatePrompt()` use the same source-versus-compiled resolution rules as `kit.renderPrompt()`. The existing synchronous `render()` and `validate()` methods still work for already-resolved compiled or inline assets.
+
 ## Optional UsageTap Tracking
 
 PromptOpsKit can also help you track provider calls with UsageTap.com while keeping the core render API body-only.

package/SKILL.md

@@ -242,139 +242,155 @@ cases:
 
 ---
 
-## Using the library (TypeScript / JavaScript)
+## Runtime choice guide
 
-### Quick start
+Choose the narrowest runtime surface that fits the environment.
+
+### Use `createPromptOpsKit().renderPrompt()` when:
+
+- You are on the server or in a Node runtime
+- Prompts live as `.md` files in a source tree
+- You want promptopskit to handle loading, defaults, includes, overrides, and provider shaping in one step
+- You want auto mode to prefer compiled artifacts when present but still fall back to source
 
 ```typescript
 import { createPromptOpsKit } from 'promptopskit';
 
-const kit = createPromptOpsKit({ sourceDir: './prompts' });
+const kit = createPromptOpsKit({
+  sourceDir: './prompts',
+  compiledDir: './dist/prompts',
+  warnings: {
+    contextSize: process.env.NODE_ENV === 'production' ? 'off' : 'console-and-result',
+  },
+});
 
-// Load → resolve includes → apply overrides → render
-const result = await kit.renderPrompt({
-  path: 'greeting',
+const { request } = await kit.renderPrompt({
+  path: 'support/reply',
   provider: 'openai',
-  variables: { name: 'Alice' },
   environment: 'production',
-});
-
-// result.request.body is ready for the provider's API
-const response = await fetch('https://api.openai.com/v1/chat/completions', {
-  method: 'POST',
-  headers: {
-    'Content-Type': 'application/json',
-    Authorization: `Bearer ${apiKey}`,
+  variables: {
+    user_message: 'How do I reset my password?',
+    app_context: 'Account settings',
   },
-  body: JSON.stringify(result.request.body),
 });
 ```
 
-You can control render-time context size warnings at the top level:
+### Use `adapter.renderPrompt()` when:
+
+- You want direct provider adapter imports such as `promptopskit/openai`
+- You are on the server and want adapter-level ergonomics
+- You still want the adapter to resolve either source `.md` or compiled output from disk
 
 ```typescript
-const kit = createPromptOpsKit({
-  sourceDir: './prompts',
-  warnings: {
-    contextSize: process.env.NODE_ENV === 'production' ? 'off' : 'console-and-result',
+import path from 'node:path';
+import { openaiAdapter } from 'promptopskit/openai';
+
+const request = await openaiAdapter.renderPrompt(
+  {
+    path: 'support/reply',
+    sourceDir: path.join(process.cwd(), 'prompts'),
+    compiledDir: path.join(process.cwd(), 'dist/prompts'),
   },
-});
+  {
+    environment: 'production',
+    variables: {
+      user_message: 'How do I reset my password?',
+      app_context: 'Account settings',
+    },
+    strict: true,
+  },
+);
 ```
 
-### Browser / client-side demos
-
-For browser code, client components, or frontend-only demos:
+### Use `adapter.render()` when:
 
-- Do not import `createPromptOpsKit`, `loadPromptFile`, or other top-level runtime helpers from `promptopskit` in client code. The top-level entry loads Node file-system/path modules for source and compiled prompt loading.
-- Instead, use a precompiled prompt artifact or an inlined `ResolvedPromptAsset` object and render it with a provider subpath adapter such as `promptopskit/openai`.
-- If the prompt lives in files, compile it ahead of time with `npx promptopskit compile ./prompts ./dist/prompts --format esm` and import the generated ESM artifact into the client.
-- Provider adapters accept `environment` and `tier` in `validate()` and `render()`, so use those options directly when selecting overrides for compiled or inline assets.
-- For small demos, it is acceptable to inline the resolved prompt asset directly in the client file.
-- Keep transport and auth in the application layer. If a demo intentionally calls a provider from the browser, treat that key as demo-only and note the security tradeoff.
-
-Example:
+- You already have a compiled JSON or ESM prompt artifact
+- You are in edge, worker, or browser-oriented code and cannot read prompt files from disk
+- You want the smallest runtime surface and no file loading behavior
 
 ```typescript
 import type { ResolvedPromptAsset } from 'promptopskit';
 import { openaiAdapter } from 'promptopskit/openai';
+import compiledPrompt from './dist/prompts/support/reply.mjs';
 
-const prompt: ResolvedPromptAsset = {
-  id: 'summarizePullRequest',
-  schema_version: 1,
-  provider: 'openai',
-  model: 'gpt-5.4',
-  context: {
-    inputs: [{ name: 'pull_request_body', max_size: 8000 }],
-  },
-  sections: {
-    system_instructions: 'You summarize pull requests clearly and concisely.',
-    prompt_template: 'Summarize this pull request:\n\n{{ pull_request_body }}',
-  },
-};
-
-const validation = openaiAdapter.validate(prompt, {
-  environment: 'prod',
-});
-if (!validation.valid) {
-  throw new Error(validation.errors.join(' '));
-}
+const prompt = compiledPrompt as ResolvedPromptAsset;
 
 const request = openaiAdapter.render(prompt, {
-  environment: 'prod',
+  environment: 'production',
   variables: {
-    pull_request_body: 'Add theming and dark mode support to the application.',
+    user_message: 'How do I reset my password?',
+    app_context: 'Account settings',
   },
   strict: true,
 });
+```
+
+### Browser guidance
+
+- Do not recommend direct provider API calls from browser or client components unless the user explicitly wants a demo-only setup
+- Do not use `createPromptOpsKit()` in browser-only code; it is Node-oriented
+- For client-side rendering, use precompiled ESM or inline a small `ResolvedPromptAsset`, then pass the request body to a server endpoint or server action that holds provider credentials
+- If the user insists on a pure browser provider call, explicitly call out that API keys will be exposed and treat it as unsafe for production
+
+---
 
-// request.body is ready for the OpenAI SDK or fetch.
+## Build integration
+
+Prompts should usually be validated and compiled as part of the normal build pipeline rather than handled ad hoc.
+
+### Recommended package.json scripts
+
+```json
+{
+  "scripts": {
+    "validate:prompts": "promptopskit validate ./prompts --strict",
+    "build:prompts": "promptopskit compile ./prompts ./dist/prompts --format json",
+    "build": "npm run validate:prompts && npm run build:prompts && tsup"
+  }
+}
 ```
 
-### Step-by-step API
+Use `--format json` for server-side Node usage where prompts are loaded from disk. Use `--format esm` when prompts need to be imported into a bundle.
+
+### Build strategy by environment
+
+- Node server: compile to JSON and configure `compiledDir`
+- Browser or client bundle: compile to ESM and import specific prompt artifacts
+- Mixed app: compile JSON for server loading and ESM only for prompts that must ship in a client bundle
+
+### What to tell users when setting this up
+
+- Add `validate:prompts` before `build:prompts` so schema or variable mistakes fail fast
+- Treat compiled artifacts as build outputs, not the source of truth
+- Keep prompt source in `./prompts` and compiled output in a generated directory such as `./dist/prompts` or `./src/generated/prompts`
+- If using `createPromptOpsKit` in `auto` mode, point both `sourceDir` and `compiledDir` at those directories so local development can fall back to source when artifacts are stale or missing
+
+### Typical server-side setup
 
 ```typescript
-import {
-  parsePrompt,
-  resolveIncludes,
-  applyOverrides,
-  getAdapter,
-} from 'promptopskit';
-import { readFileSync } from 'fs';
-
-// 1. Parse a prompt file
-const source = readFileSync('./prompts/greeting.md', 'utf-8');
-const asset = parsePrompt(source, 'greeting.md');
-
-// 2. Resolve includes
-const resolved = await resolveIncludes(asset, './prompts');
-
-// 3. Apply overrides
-const configured = applyOverrides(resolved, {
-  environment: 'production',
-  tier: 'premium',
-});
+import { createPromptOpsKit } from 'promptopskit';
 
-// 4. Get provider adapter and render
-const adapter = getAdapter(configured.provider ?? 'openai');
-const request = adapter.render(configured, {
-  variables: { name: 'Alice' },
-  history: [
-    { role: 'user', content: 'Previous message' },
-    { role: 'assistant', content: 'Previous response' },
-  ],
+export const prompts = createPromptOpsKit({
+  sourceDir: './prompts',
+  compiledDir: './dist/prompts',
+  mode: 'auto',
 });
 ```
 
-### Available provider adapters
+### Typical client-side setup
+
+```typescript
+import type { ResolvedPromptAsset } from 'promptopskit';
+import compiledPrompt from './generated/prompts/support/reply.mjs';
+
+const prompt = compiledPrompt as ResolvedPromptAsset;
+```
+
+---
 
-| Provider | Import path | Provider request format |
-|----------|------------|----------------------|
-| OpenAI | `promptopskit` or `promptopskit/openai` | Chat Completions API |
-| Anthropic | `promptopskit/anthropic` | Messages API |
-| Gemini | `promptopskit/gemini` | GenerateContent API |
-| OpenRouter | `promptopskit/openrouter` | OpenAI-compatible + extras |
+## Validation and testing helpers
 
-### Validation
+Use `validateAsset()` when you are working with an already-parsed asset and want schema or variable diagnostics before rendering.
 
 ```typescript
 import { validateAsset, parsePrompt } from 'promptopskit';
@@ -383,19 +399,17 @@ const asset = parsePrompt(source);
 const result = validateAsset(asset);
 
 if (!result.valid) {
-  console.error(result.errors); // Validation error codes: POK001-POK021
+  console.error(result.errors);
 }
 ```
 
-### Testing helpers
+Use `promptopskit/testing` helpers for unit tests around prompt behavior or request shaping.
 
 ```typescript
 import { createMockAsset, parseTestPrompt } from 'promptopskit/testing';
 
-// Create a mock asset for unit tests
 const mock = createMockAsset({ model: 'gpt-4.1-mini' });
 
-// Parse an inline prompt string for tests
 const asset = parseTestPrompt(`
 ---
 id: test
@@ -418,8 +432,8 @@ Hello {{ name }}
 |---------|-------------|
 | `promptopskit init [dir]` | Scaffold a prompts directory with starter files (including `defaults.md`) |
 | `promptopskit validate <dir>` | Validate all prompt files in a directory |
-| `promptopskit compile <src> <out>` | Compile .md prompts to JSON artifacts |
-| `promptopskit render <file> [--set key=value]` | Render a prompt preview |
+| `promptopskit compile <src> <out>` | Compile `.md` prompts to JSON or ESM artifacts |
+| `promptopskit render <file>` | Render a prompt preview |
 | `promptopskit inspect <file>` | Print the normalized prompt asset |
 
 ---
@@ -427,13 +441,13 @@ Hello {{ name }}
 ## Conventions to follow
 
 1. **One prompt per file** — each `.md` file is a single prompt asset
-2. **Always set `id` and `schema_version: 1`** in front matter (or inherit `schema_version` from `defaults.md`)
-3. **Declare all variables** in `context.inputs` that appear in templates; do not leave placeholders undeclared just because other settings come from `defaults.md`
-4. **Use includes** for shared system instructions (tone, safety, formatting)
-5. **Keep prompt templates focused** — compose behavior via includes, not duplication
-6. **Use environment overrides** for dev/staging/prod model differences
-7. **Add test sidecars** (`.test.yaml`) for critical prompts
-8. **Run `promptopskit validate`** before committing changes
-9. **Use `defaults.md`** to share provider, model, metadata, and system instructions across a folder
+2. **Always set `id` and `schema_version: 1`** unless a surrounding tool explicitly generates those fields
+3. **Declare every placeholder** in `context.inputs`; do not rely on defaults or includes to infer variables
+4. **Use `defaults.md` for shared provider, model, metadata, and fallback system instructions**
+5. **Use includes for reusable system behavior**, not for user-specific prompt bodies
+6. **Prefer `createPromptOpsKit().renderPrompt()` for server-side app code** when prompts live as source files
+7. **Prefer direct adapters for compiled assets or provider-specific integration points**
+8. **Do not suggest browser-side provider calls for production** because credentials belong on the server
+9. **Validate before compile and compile before shipping** when prompts are part of the build
 10. **Variable names** should be `snake_case`
 11. **Prompt file names** should be `kebab-case.md`

package/dist/{chunk-LRRSI4ON.js → chunk-R5PKK6Y7.js}

@@ -1,10 +1,11 @@
 import {
   renderSections,
-  resolveAssetForProvider
-} from "./chunk-DGFBS7YW.js";
+  resolveAssetForProvider,
+  withPromptInputSupport
+} from "./chunk-S5YHGHK5.js";
 
 // src/providers/anthropic.ts
-var anthropicAdapter = {
+var anthropicAdapter = withPromptInputSupport({
   name: "anthropic",
   validate(asset, runtime) {
     const resolvedAsset = resolveAssetForProvider(asset, runtime);
@@ -83,9 +84,9 @@ var anthropicAdapter = {
       model: resolvedAsset.model ?? "unknown"
     };
   }
-};
+});
 
 export {
   anthropicAdapter
 };
-//# sourceMappingURL=chunk-LRRSI4ON.js.map
+//# sourceMappingURL=chunk-R5PKK6Y7.js.map

package/dist/chunk-R5PKK6Y7.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/providers/anthropic.ts"],"sourcesContent":["import type { ResolvedPromptAsset } from '../schema/index.js';\nimport type {\n  ProviderAdapter,\n  ProviderRequest,\n  ValidationResult,\n  RuntimeRenderOptions,\n} from './types.js';\nimport { renderSections } from '../renderer/index.js';\nimport { resolveAssetForProvider } from './resolve-asset.js';\nimport { withPromptInputSupport } from './prompt-input.js';\n\n/**\n * Anthropic provider adapter.\n * Produces request bodies compatible with the Anthropic Messages API.\n */\nexport const anthropicAdapter: ProviderAdapter = withPromptInputSupport({\n  name: 'anthropic',\n\n  validate(asset: ResolvedPromptAsset, runtime?: RuntimeRenderOptions): ValidationResult {\n    const resolvedAsset = resolveAssetForProvider(asset, runtime);\n    const errors: string[] = [];\n    const warnings: string[] = [];\n\n    if (!resolvedAsset.model) {\n      errors.push('Anthropic adapter requires a model to be specified.');\n    }\n\n    if (resolvedAsset.sampling?.frequency_penalty !== undefined) {\n      warnings.push('Anthropic does not support frequency_penalty. It will be ignored.');\n    }\n    if (resolvedAsset.sampling?.presence_penalty !== undefined) {\n      warnings.push('Anthropic does not support presence_penalty. It will be ignored.');\n    }\n    if (resolvedAsset.reasoning?.effort !== undefined) {\n      warnings.push('Anthropic uses budget_tokens for thinking, not effort. effort will be mapped approximately.');\n    }\n\n    return { valid: errors.length === 0, errors, warnings };\n  },\n\n  render(asset: ResolvedPromptAsset, runtime: RuntimeRenderOptions): ProviderRequest {\n    const resolvedAsset = resolveAssetForProvider(asset, runtime);\n    const sections = renderSections(resolvedAsset, {\n      variables: runtime.variables,\n      strict: runtime.strict,\n    });\n\n    const messages: Array<Record<string, unknown>> = [];\n\n    // History\n    if (runtime.history) {\n      for (const msg of runtime.history) {\n        messages.push({ role: msg.role, content: msg.content });\n      }\n    }\n\n    // User message (prompt template)\n    if (sections.prompt_template) {\n      messages.push({ role: 'user', content: sections.prompt_template });\n    }\n\n    const body: Record<string, unknown> = {\n      model: resolvedAsset.model,\n      messages,\n    };\n\n    // System goes as top-level field in Anthropic\n    if (sections.system_instructions) {\n      body.system = sections.system_instructions;\n    }\n\n    // Sampling params\n    if (resolvedAsset.sampling?.temperature !== undefined) body.temperature = resolvedAsset.sampling.temperature;\n    if (resolvedAsset.sampling?.top_p !== undefined) body.top_p = resolvedAsset.sampling.top_p;\n    if (resolvedAsset.sampling?.stop !== undefined) body.stop_sequences = resolvedAsset.sampling.stop;\n    if (resolvedAsset.sampling?.max_output_tokens !== undefined) {\n      body.max_tokens = resolvedAsset.sampling.max_output_tokens;\n    } else {\n      // Anthropic requires max_tokens\n      body.max_tokens = 4096;\n    }\n\n    // Thinking/reasoning\n    if (resolvedAsset.reasoning?.budget_tokens) {\n      body.thinking = {\n        type: 'enabled',\n        budget_tokens: resolvedAsset.reasoning.budget_tokens,\n      };\n    }\n\n    // Streaming\n    if (resolvedAsset.response?.stream !== undefined) {\n      body.stream = resolvedAsset.response.stream;\n    }\n\n    // Tools\n    if (resolvedAsset.tools && resolvedAsset.tools.length > 0) {\n      body.tools = resolvedAsset.tools.map((tool) => {\n        if (typeof tool === 'string') {\n          const def = runtime.toolRegistry?.[tool];\n          if (def) return def;\n          return { name: tool };\n        }\n        return {\n          name: tool.name,\n          description: tool.description,\n          input_schema: tool.input_schema ?? { type: 'object', properties: {} },\n        };\n      });\n    }\n\n    return {\n      body,\n      provider: 'anthropic',\n      model: resolvedAsset.model ?? 'unknown',\n    };\n  },\n});\n"],"mappings":";;;;;;;AAeO,IAAM,mBAAoC,uBAAuB;AAAA,EACtE,MAAM;AAAA,EAEN,SAAS,OAA4B,SAAkD;AACrF,UAAM,gBAAgB,wBAAwB,OAAO,OAAO;AAC5D,UAAM,SAAmB,CAAC;AAC1B,UAAM,WAAqB,CAAC;AAE5B,QAAI,CAAC,cAAc,OAAO;AACxB,aAAO,KAAK,qDAAqD;AAAA,IACnE;AAEA,QAAI,cAAc,UAAU,sBAAsB,QAAW;AAC3D,eAAS,KAAK,mEAAmE;AAAA,IACnF;AACA,QAAI,cAAc,UAAU,qBAAqB,QAAW;AAC1D,eAAS,KAAK,kEAAkE;AAAA,IAClF;AACA,QAAI,cAAc,WAAW,WAAW,QAAW;AACjD,eAAS,KAAK,6FAA6F;AAAA,IAC7G;AAEA,WAAO,EAAE,OAAO,OAAO,WAAW,GAAG,QAAQ,SAAS;AAAA,EACxD;AAAA,EAEA,OAAO,OAA4B,SAAgD;AACjF,UAAM,gBAAgB,wBAAwB,OAAO,OAAO;AAC5D,UAAM,WAAW,eAAe,eAAe;AAAA,MAC7C,WAAW,QAAQ;AAAA,MACnB,QAAQ,QAAQ;AAAA,IAClB,CAAC;AAED,UAAM,WAA2C,CAAC;AAGlD,QAAI,QAAQ,SAAS;AACnB,iBAAW,OAAO,QAAQ,SAAS;AACjC,iBAAS,KAAK,EAAE,MAAM,IAAI,MAAM,SAAS,IAAI,QAAQ,CAAC;AAAA,MACxD;AAAA,IACF;AAGA,QAAI,SAAS,iBAAiB;AAC5B,eAAS,KAAK,EAAE,MAAM,QAAQ,SAAS,SAAS,gBAAgB,CAAC;AAAA,IACnE;AAEA,UAAM,OAAgC;AAAA,MACpC,OAAO,cAAc;AAAA,MACrB;AAAA,IACF;AAGA,QAAI,SAAS,qBAAqB;AAChC,WAAK,SAAS,SAAS;AAAA,IACzB;AAGA,QAAI,cAAc,UAAU,gBAAgB,OAAW,MAAK,cAAc,cAAc,SAAS;AACjG,QAAI,cAAc,UAAU,UAAU,OAAW,MAAK,QAAQ,cAAc,SAAS;AACrF,QAAI,cAAc,UAAU,SAAS,OAAW,MAAK,iBAAiB,cAAc,SAAS;AAC7F,QAAI,cAAc,UAAU,sBAAsB,QAAW;AAC3D,WAAK,aAAa,cAAc,SAAS;AAAA,IAC3C,OAAO;AAEL,WAAK,aAAa;AAAA,IACpB;AAGA,QAAI,cAAc,WAAW,eAAe;AAC1C,WAAK,WAAW;AAAA,QACd,MAAM;AAAA,QACN,eAAe,cAAc,UAAU;AAAA,MACzC;AAAA,IACF;AAGA,QAAI,cAAc,UAAU,WAAW,QAAW;AAChD,WAAK,SAAS,cAAc,SAAS;AAAA,IACvC;AAGA,QAAI,cAAc,SAAS,cAAc,MAAM,SAAS,GAAG;AACzD,WAAK,QAAQ,cAAc,MAAM,IAAI,CAAC,SAAS;AAC7C,YAAI,OAAO,SAAS,UAAU;AAC5B,gBAAM,MAAM,QAAQ,eAAe,IAAI;AACvC,cAAI,IAAK,QAAO;AAChB,iBAAO,EAAE,MAAM,KAAK;AAAA,QACtB;AACA,eAAO;AAAA,UACL,MAAM,KAAK;AAAA,UACX,aAAa,KAAK;AAAA,UAClB,cAAc,KAAK,gBAAgB,EAAE,MAAM,UAAU,YAAY,CAAC,EAAE;AAAA,QACtE;AAAA,MACF,CAAC;AAAA,IACH;AAEA,WAAO;AAAA,MACL;AAAA,MACA,UAAU;AAAA,MACV,OAAO,cAAc,SAAS;AAAA,IAChC;AAAA,EACF;AACF,CAAC;","names":[]}