promptopskit 0.0.1 → 0.0.2

package/dist/cli/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/cli/commands/validate.ts
-import { readdir, readFile as readFile2 } from "fs/promises";
+import { readdir, readFile as readFile3 } from "fs/promises";
 import { join, extname } from "path";
 
 // src/parser/parser.ts
@@ -75,7 +75,7 @@ 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", "openrouter", "any"]).optional(),
+  provider: z.enum(["openai", "anthropic", "google", "gemini", "openrouter", "any"]).optional(),
   model: z.string().optional(),
   fallback_models: z.array(z.string()).optional(),
   reasoning: ReasoningSchema.optional(),
@@ -182,6 +182,45 @@ function extractVariables(template) {
   return [...vars];
 }
 
+// src/composition/resolve-includes.ts
+import { readFile as readFile2 } from "fs/promises";
+import { resolve, dirname } from "path";
+async function resolveIncludes(asset, basePath, visited = /* @__PURE__ */ new Set()) {
+  if (!asset.includes || asset.includes.length === 0) {
+    return asset;
+  }
+  const baseDir = dirname(basePath);
+  const resolvedPath = resolve(basePath);
+  if (visited.has(resolvedPath)) {
+    throw new Error(`Circular include detected: ${resolvedPath}`);
+  }
+  visited.add(resolvedPath);
+  let mergedSystemInstructions = "";
+  for (const includePath of asset.includes) {
+    const fullPath = resolve(baseDir, includePath);
+    if (visited.has(fullPath)) {
+      throw new Error(`Circular include detected: ${fullPath} (included from ${basePath})`);
+    }
+    const content = await readFile2(fullPath, "utf-8");
+    const { asset: includedAsset } = parsePrompt(content, fullPath);
+    const resolved = await resolveIncludes(includedAsset, fullPath, new Set(visited));
+    if (resolved.sections?.system_instructions) {
+      mergedSystemInstructions += resolved.sections.system_instructions + "\n\n";
+    }
+  }
+  const localSystem = asset.sections?.system_instructions ?? "";
+  const combinedSystem = (mergedSystemInstructions + localSystem).trim() || void 0;
+  return {
+    ...asset,
+    sections: {
+      ...asset.sections,
+      system_instructions: combinedSystem
+    },
+    // Drop includes from the resolved asset — they've been inlined
+    includes: void 0
+  };
+}
+
 // src/validation/levenshtein.ts
 function levenshtein(a, b) {
   const m = a.length;
@@ -299,6 +338,24 @@ function validateAsset(asset, frontMatterKeys, filePath) {
     warnings
   };
 }
+async function validateAssetWithIncludes(asset, filePath, frontMatterKeys) {
+  const result = validateAsset(asset, frontMatterKeys, filePath);
+  if (asset.includes && asset.includes.length > 0) {
+    try {
+      await resolveIncludes(asset, filePath);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      const isCircular = message.includes("Circular include");
+      result.errors.push({
+        code: isCircular ? "POK021" : "POK020",
+        message: isCircular ? `Circular include detected: ${message}` : `Include resolution failed: ${message}`,
+        filePath
+      });
+      result.valid = false;
+    }
+  }
+  return result;
+}
 function findClosestMatch(input, candidates) {
   let best;
   let bestDist = Infinity;
@@ -342,9 +399,9 @@ async function validate(args) {
   let warnCount = 0;
   for (const file of files) {
     try {
-      const content = await readFile2(file, "utf-8");
+      const content = await readFile3(file, "utf-8");
       const { asset, raw } = parsePrompt(content, file);
-      const result = validateAsset(asset, Object.keys(raw.frontMatter), file);
+      const result = await validateAssetWithIncludes(asset, file, Object.keys(raw.frontMatter));
       if (result.errors.length > 0) {
         errorCount += result.errors.length;
         console.error(`  \u2717 ${file}`);
@@ -386,8 +443,8 @@ async function collectPromptFiles(dir) {
 }
 
 // src/cli/commands/compile.ts
-import { readdir as readdir2, readFile as readFile3, writeFile, mkdir, rm } from "fs/promises";
-import { join as join2, extname as extname2, relative, dirname } from "path";
+import { readdir as readdir2, readFile as readFile4, writeFile, mkdir, rm } from "fs/promises";
+import { join as join2, extname as extname2, relative, dirname as dirname2 } from "path";
 var HELP2 = `
 promptopskit compile <sourceDir> <outputDir> [options]
 
@@ -434,12 +491,13 @@ async function compile(args) {
     const outExt = format === "esm" ? ".mjs" : ".json";
     const outPath = join2(outputDir, rel + outExt);
     try {
-      const content = await readFile3(file, "utf-8");
-      const { asset } = parsePrompt(content, file);
+      const content = await readFile4(file, "utf-8");
+      const { asset: parsed } = parsePrompt(content, file);
+      const asset = parsed.includes && parsed.includes.length > 0 ? await resolveIncludes(parsed, file) : parsed;
       if (dryRun) {
         console.log(`  Would create: ${outPath}`);
       } else {
-        await mkdir(dirname(outPath), { recursive: true });
+        await mkdir(dirname2(outPath), { recursive: true });
         if (format === "esm") {
           const esmContent = `export default ${JSON.stringify(asset, null, 2)};
 `;
@@ -486,7 +544,7 @@ async function collectPromptFiles2(dir) {
 }
 
 // src/cli/commands/render.ts
-import { readFile as readFile4 } from "fs/promises";
+import { readFile as readFile5 } from "fs/promises";
 import { existsSync } from "fs";
 
 // src/overrides/apply-overrides.ts
@@ -549,25 +607,26 @@ async function render(args) {
   const jsonOutput = args.includes("--json");
   let variables = {};
   if (varsFile) {
-    const varsContent = await readFile4(varsFile, "utf-8");
+    const varsContent = await readFile5(varsFile, "utf-8");
     variables = JSON.parse(varsContent);
   } else {
     const sidecarPath = file.replace(/\.md$/, ".test.yaml");
     if (existsSync(sidecarPath)) {
       const { default: yaml } = await import("gray-matter");
-      const sidecarContent = await readFile4(sidecarPath, "utf-8");
-      const parsed = yaml(`---
+      const sidecarContent = await readFile5(sidecarPath, "utf-8");
+      const parsed2 = yaml(`---
 ${sidecarContent}---
 `);
-      const data = parsed.data;
+      const data = parsed2.data;
       if (data.cases?.[0]?.variables) {
         variables = data.cases[0].variables;
       }
     }
   }
-  const content = await readFile4(file, "utf-8");
-  const { asset } = parsePrompt(content, file);
-  const overridden = applyOverrides(asset, {
+  const content = await readFile5(file, "utf-8");
+  const { asset: parsed } = parsePrompt(content, file);
+  const resolved = parsed.includes && parsed.includes.length > 0 ? await resolveIncludes(parsed, file) : parsed;
+  const overridden = applyOverrides(resolved, {
     environment: env,
     tier
   });
@@ -612,7 +671,7 @@ function getFlag2(args, flag) {
 }
 
 // src/cli/commands/inspect.ts
-import { readFile as readFile5 } from "fs/promises";
+import { readFile as readFile6 } from "fs/promises";
 var HELP4 = `
 promptopskit inspect <file>
 
@@ -631,14 +690,15 @@ async function inspect(args) {
     console.error("Error: Please provide a prompt file to inspect.");
     process.exit(1);
   }
-  const content = await readFile5(file, "utf-8");
-  const { asset } = parsePrompt(content, file);
+  const content = await readFile6(file, "utf-8");
+  const { asset: parsed } = parsePrompt(content, file);
+  const asset = parsed.includes && parsed.includes.length > 0 ? await resolveIncludes(parsed, file) : parsed;
   console.log(JSON.stringify(asset, null, 2));
 }
 
 // src/cli/commands/init.ts
 import { writeFile as writeFile2, mkdir as mkdir2 } from "fs/promises";
-import { join as join3, dirname as dirname2 } from "path";
+import { join as join3, dirname as dirname3 } from "path";
 import { existsSync as existsSync2, readFileSync } from "fs";
 var HELP5 = `
 promptopskit init [dir]
@@ -704,7 +764,7 @@ async function init(args) {
       skipped++;
       continue;
     }
-    await mkdir2(dirname2(file.path), { recursive: true });
+    await mkdir2(dirname3(file.path), { recursive: true });
     await writeFile2(file.path, file.content, "utf-8");
     console.log(`  \u2713 ${file.path}`);
     created++;
@@ -724,8 +784,371 @@ async function init(args) {
   }
 }
 
-// src/cli/index.ts
+// src/cli/commands/skill.ts
+import { writeFile as writeFile3, mkdir as mkdir3 } from "fs/promises";
+import { dirname as dirname4 } from "path";
+import { existsSync as existsSync3 } from "fs";
 var HELP6 = `
+promptopskit skill [--target <target>] [--force]
+
+Deploy AI agent instructions so coding assistants know how to
+create and manage prompts using promptopskit.
+
+Targets:
+  copilot   (default) .github/instructions/promptopskit.instructions.md
+  cursor    .cursor/rules/promptopskit.mdc
+  generic   .ai/promptopskit-skill.md
+
+Options:
+  --target, -t     Target AI tool (copilot, cursor, generic)
+  --force, -f      Overwrite existing file
+  --help, -h       Show this help
+`.trim();
+var TARGETS = {
+  copilot: {
+    path: ".github/instructions/promptopskit.instructions.md",
+    wrap: (content) => `---
+applyTo: "**"
+---
+
+${content}`
+  },
+  cursor: {
+    path: ".cursor/rules/promptopskit.mdc",
+    wrap: (content) => `---
+description: How to create and manage prompts using promptopskit
+globs: "**"
+alwaysApply: true
+---
+
+${content}`
+  },
+  generic: {
+    path: ".ai/promptopskit-skill.md",
+    wrap: (content) => content
+  }
+};
+async function skill(args) {
+  if (args.includes("--help") || args.includes("-h")) {
+    console.log(HELP6);
+    return;
+  }
+  const force = args.includes("--force") || args.includes("-f");
+  let target = "copilot";
+  const targetIdx = args.findIndex((a) => a === "--target" || a === "-t");
+  if (targetIdx !== -1 && args[targetIdx + 1]) {
+    target = args[targetIdx + 1];
+  }
+  const config = TARGETS[target];
+  if (!config) {
+    console.error(`Unknown target: ${target}`);
+    console.error(`Valid targets: ${Object.keys(TARGETS).join(", ")}`);
+    process.exit(1);
+  }
+  const filePath = config.path;
+  if (existsSync3(filePath) && !force) {
+    console.log(`  skip ${filePath} (already exists, use --force to overwrite)`);
+    return;
+  }
+  const content = config.wrap(SKILL_CONTENT);
+  await mkdir3(dirname4(filePath), { recursive: true });
+  await writeFile3(filePath, content, "utf-8");
+  console.log(`  \u2713 ${filePath}`);
+  console.log();
+  console.log(`AI agents will now understand how to create and manage prompts with promptopskit.`);
+}
+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.
+
+---
+
+## Environment & tier overrides
+
+Override model settings per environment or tier:
+
+\`\`\`yaml
+environments:
+  development:
+    model: gpt-4.1-mini
+    sampling:
+      temperature: 0.9
+  production:
+    model: gpt-5.4
+    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 |
+| \`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
+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. **Variable names** should be \`snake_case\`
+10. **Prompt file names** should be \`kebab-case.md\`
+`.trimEnd();
+
+// src/cli/index.ts
+var HELP7 = `
 promptopskit \u2014 Manage prompts, system instructions, tools, and model settings as code
 
 Usage:
@@ -737,6 +1160,7 @@ Commands:
   compile <src> <out> [options]        Compile .md prompts to JSON/ESM artifacts
   render <file> [options]              Render a prompt preview
   inspect <file>                       Print normalized prompt asset
+  skill [options]                      Deploy AI agent instructions into your project
 
 Options:
   --help, -h                           Show this help message
@@ -748,7 +1172,7 @@ async function main() {
   const args = process.argv.slice(2);
   const command = args[0];
   if (!command || command === "--help" || command === "-h") {
-    console.log(HELP6);
+    console.log(HELP7);
     process.exit(0);
   }
   if (command === "--version" || command === "-v") {
@@ -772,9 +1196,12 @@ async function main() {
     case "inspect":
       await inspect(commandArgs);
       break;
+    case "skill":
+      await skill(commandArgs);
+      break;
     default:
       console.error(`Unknown command: ${command}`);
-      console.log(HELP6);
+      console.log(HELP7);
       process.exit(1);
   }
 }