promptopskit 0.2.3 → 0.2.5

package/dist/cli/index.js

@@ -413,7 +413,7 @@ function validateAsset(asset, frontMatterKeys, filePath) {
     }
   }
   for (const v of usedVars) {
-    if (declaredInputs.size > 0 && !declaredInputs.has(v)) {
+    if (!declaredInputs.has(v)) {
       warnings.push({
         code: "POK011",
         message: `Variable "{{ ${v} }}" is used but not declared in context.inputs`,
@@ -990,6 +990,12 @@ Options:
   --force, -f      Overwrite entire file instead of merging
   --help, -h       Show this help
 `.trim();
+var STUB_CONTENT = `# promptopskit
+
+This project uses **promptopskit** to manage LLM prompts as code.
+Read the full guide at \`node_modules/promptopskit/SKILL.md\` before
+creating or editing prompt files.`;
+var CLAUDE_LINE = "@AGENTS.md";
 var TARGETS = {
   agents: {
     path: "AGENTS.md",
@@ -997,7 +1003,7 @@ var TARGETS = {
   },
   claude: {
     path: "CLAUDE.md",
-    wrap: () => "@AGENTS.md\n"
+    wrap: () => CLAUDE_LINE + "\n"
   },
   copilot: {
     path: ".github/instructions/promptopskit.instructions.md",
@@ -1041,7 +1047,11 @@ async function skill(args) {
   for (const target of targets) {
     const config = TARGETS[target];
     const filePath = config.path;
-    const markedContent = config.wrap(wrapMarkers(SKILL_CONTENT));
+    if (target === "claude") {
+      written += await deployClaude(filePath, force);
+      continue;
+    }
+    const markedContent = config.wrap(wrapMarkers(STUB_CONTENT));
     if (existsSync3(filePath) && !force) {
       const existing = await readFile4(filePath, "utf-8");
       const merged = mergeContent(existing, markedContent);
@@ -1064,6 +1074,24 @@ async function skill(args) {
     console.log(`AI agents will now understand how to create and manage prompts with promptopskit.`);
   }
 }
+async function deployClaude(filePath, force) {
+  const content = CLAUDE_LINE + "\n";
+  if (!existsSync3(filePath) || force) {
+    await mkdir3(dirname5(filePath), { recursive: true });
+    await writeFile3(filePath, content, "utf-8");
+    console.log(`  \u2713 ${filePath}`);
+    return 1;
+  }
+  const existing = await readFile4(filePath, "utf-8");
+  if (existing.split("\n").some((line) => line.trim() === CLAUDE_LINE)) {
+    console.log(`  skip ${filePath} (already up to date)`);
+    return 0;
+  }
+  const separator = existing.endsWith("\n") ? "\n" : "\n\n";
+  await writeFile3(filePath, existing + separator + content, "utf-8");
+  console.log(`  \u2713 ${filePath} (merged)`);
+  return 1;
+}
 function wrapMarkers(content) {
   return `${MARKER_START}
 ${content}
@@ -1078,334 +1106,6 @@ function mergeContent(existing, markedContent) {
   const separator = existing.endsWith("\n") ? "\n" : "\n\n";
   return existing + separator + markedContent + "\n";
 }
-var SKILL_CONTENT = `# promptopskit \u2014 Prompt Engineering Skill
-
-This project uses **promptopskit** to manage LLM prompts as code.
-Prompts live in markdown files with YAML front matter, are validated against
-a schema, and render into provider-specific request bodies (OpenAI, Anthropic,
-Gemini, OpenRouter). Follow these instructions when creating or editing prompts.
-
----
-
-## Prompt file format
-
-Every prompt is a \`.md\` file with two parts:
-
-1. **YAML front matter** \u2014 model settings, provider config, variables, overrides
-2. **Markdown body** \u2014 sections separated by H1 headings
-
-### Minimal example
-
-\`\`\`markdown
----
-id: greeting
-schema_version: 1
-provider: openai
-model: gpt-5.4
-context:
-  inputs:
-    - name
----
-
-# System instructions
-
-You are a helpful assistant.
-
-# Prompt template
-
-Hello {{ name }}, how can I help you?
-\`\`\`
-
----
-
-## Front matter reference
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| \`id\` | string | **yes** | Unique identifier for the prompt |
-| \`schema_version\` | number | yes | Always \`1\` |
-| \`description\` | string | no | Human-readable description |
-| \`provider\` | enum | no | \`openai\`, \`anthropic\`, \`google\`, \`gemini\`, \`openrouter\`, or \`any\` |
-| \`model\` | string | no | Model identifier (e.g. \`gpt-5.4\`, \`claude-sonnet-4-20250514\`) |
-| \`fallback_models\` | string[] | no | Ordered fallback model list |
-| \`reasoning\` | object | no | \`{ effort: low|medium|high, budget_tokens: number }\` |
-| \`sampling\` | object | no | \`{ temperature, top_p, frequency_penalty, presence_penalty, stop, max_output_tokens }\` |
-| \`response\` | object | no | \`{ format: text|json|markdown, stream: boolean }\` |
-| \`tools\` | array | no | Tool names (strings) or inline definitions with \`{ name, description, input_schema }\` |
-| \`mcp\` | object | no | \`{ servers: [string | { name, config }] }\` |
-| \`context.inputs\` | string[] | no | Declared variable names used in templates |
-| \`context.history\` | object | no | \`{ max_items: number }\` |
-| \`includes\` | string[] | no | Relative paths to other prompt files to include |
-| \`environments\` | object | no | Per-environment overrides (see Overrides) |
-| \`tiers\` | object | no | Per-tier overrides (see Overrides) |
-| \`metadata\` | object | no | \`{ owner, tags, review_required, stable }\` |
-
----
-
-## Sections (markdown body)
-
-Use H1 headings to define sections. The parser recognizes these headings
-(case-insensitive):
-
-| Heading | Maps to | Purpose |
-|---------|---------|---------|
-| \`# System instructions\` | \`system_instructions\` | System/developer message |
-| \`# Prompt template\` | \`prompt_template\` | User message template |
-| \`# Notes\` | \`notes\` | Documentation only \u2014 not sent to the model |
-
-If the body has **no H1 headings**, the entire body becomes the \`prompt_template\`.
-
----
-
-## Variable interpolation
-
-Use \`{{ variable_name }}\` syntax in system instructions and prompt template
-sections. Variables are replaced at render time.
-
-Rules:
-- Declare all variables in \`context.inputs\` \u2014 validation warns on undeclared usage
-- Escape literal braces with \`\\\\{{\` and \`\\\\}}\`
-- In strict mode, missing variables throw an error
-- In permissive mode, unresolved placeholders are left intact
-
----
-
-## Includes (composition)
-
-Compose prompts from shared fragments:
-
-\`\`\`yaml
-includes:
-  - ./shared/tone.md
-  - ./shared/safety.md
-\`\`\`
-
-Included files are parsed and their \`system_instructions\` are **prepended**
-before the including file's own system instructions. Includes resolve
-recursively. Circular includes are detected and rejected.
-
-> **Note:** Included files do not inherit folder defaults. Only the top-level
-> prompt that is loaded via \`loadPromptFile\` receives defaults.
-
----
-
-## Folder defaults (\`defaults.md\`)
-
-Define shared defaults for a prompt tree by adding a \`defaults.md\` file in any
-folder:
-
-\`\`\`text
-prompts/
-\u251C\u2500\u2500 defaults.md          # global provider, model, metadata + system instructions
-\u2514\u2500\u2500 support/
-    \u251C\u2500\u2500 defaults.md      # overrides for support/*
-    \u2514\u2500\u2500 reply.md         # inherits from support/defaults.md
-\`\`\`
-
-Supported default fields:
-- \`provider\` (front matter) \u2014 default provider for the folder
-- \`model\` (front matter) \u2014 default model for the folder
-- \`metadata\` (front matter) \u2014 merged with prompt-local metadata
-- \`# System instructions\` (body section) \u2014 used when the prompt has none
-
-This lets you configure app-wide settings like \`provider\` and \`model\`
-in a single root \`defaults.md\`, so individual prompts only declare what\u2019s unique to them.
-
-Rules:
-- Nearest subfolder \`defaults.md\` overrides parent defaults
-- Prompt-local values always take precedence over defaults
-- \`defaults.md\` files are skipped during compilation and validation
-- \`loadPromptFile\` defaults the search boundary to the file's own directory;
-  pass \`defaultsRoot\` to enable ancestor traversal
-
----
-
-## Environment & tier overrides
-
-Override model settings per environment or tier:
-
-\`\`\`yaml
-environments:
-  development:
-    model: gpt-4.1-mini
-    reasoning:
-      effort: low
-    sampling:
-      temperature: 0.9
-  production:
-    model: gpt-5.4
-    reasoning:
-      effort: high
-    sampling:
-      temperature: 0.3
-
-tiers:
-  free:
-    model: gpt-4.1-mini
-    sampling:
-      max_output_tokens: 500
-  premium:
-    model: gpt-5.4
-\`\`\`
-
-Overridable fields: \`model\`, \`fallback_models\`, \`reasoning\`, \`sampling\`,
-\`response\`, \`tools\`.
-
-Override application order: **base \u2192 environment \u2192 tier \u2192 runtime**.
-
----
-
-## Test sidecars
-
-Create a \`.test.yaml\` file alongside a prompt to define test cases:
-
-\`\`\`yaml
-# greeting.test.yaml
-cases:
-  - name: basic
-    variables:
-      name: "World"
-  - name: formal
-    variables:
-      name: "Dr. Smith"
-\`\`\`
-
----
-
-## Using the library (TypeScript / JavaScript)
-
-### Quick start
-
-\`\`\`typescript
-import { createPromptOpsKit } from 'promptopskit';
-
-const kit = createPromptOpsKit({ sourceDir: './prompts' });
-
-// Load \u2192 resolve includes \u2192 apply overrides \u2192 render
-const request = await kit.renderPrompt('greeting', {
-  variables: { name: 'Alice' },
-  environment: 'production',
-});
-
-// 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}\`,
-  },
-  body: JSON.stringify(request.body),
-});
-\`\`\`
-
-### Step-by-step API
-
-\`\`\`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',
-});
-
-// 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' },
-  ],
-});
-\`\`\`
-
-### Available provider adapters
-
-| 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
-
-\`\`\`typescript
-import { validateAsset, parsePrompt } from 'promptopskit';
-
-const asset = parsePrompt(source);
-const result = validateAsset(asset);
-
-if (!result.valid) {
-  console.error(result.errors); // Error codes: POK001-POK021
-}
-\`\`\`
-
-### Testing helpers
-
-\`\`\`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
-schema_version: 1
-provider: openai
-model: gpt-5.4
----
-
-# Prompt template
-
-Hello {{ name }}
-\`);
-\`\`\`
-
----
-
-## CLI commands
-
-| Command | Description |
-|---------|-------------|
-| \`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 inspect <file>\` | Print the normalized prompt asset |
-
----
-
-## Conventions to follow
-
-1. **One prompt per file** \u2014 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
-4. **Use includes** for shared system instructions (tone, safety, formatting)
-5. **Keep prompt templates focused** \u2014 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
-10. **Variable names** should be \`snake_case\`
-11. **Prompt file names** should be \`kebab-case.md\`
-`.trimEnd();
 
 // src/cli/index.ts
 var HELP7 = `