promptopskit 0.0.2 → 0.1.0

package/dist/cli/index.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 
 // src/cli/commands/validate.ts
-import { readdir, readFile as readFile3 } from "fs/promises";
-import { join, extname } from "path";
+import { readdir } from "fs/promises";
+import { join as join2, extname } from "path";
 
 // src/parser/parser.ts
 import matter from "gray-matter";
@@ -71,6 +71,12 @@ var SectionsSchema = z.object({
   prompt_template: z.string().optional(),
   notes: z.string().optional()
 });
+var PromptDefaultsSchema = z.object({
+  metadata: MetadataSchema.optional(),
+  sections: z.object({
+    system_instructions: z.string().optional()
+  }).optional()
+});
 var PromptAssetSchema = z.object({
   id: z.string(),
   schema_version: z.number().int().positive().default(1),
@@ -152,6 +158,91 @@ function parsePrompt(content, filePath) {
 
 // src/parser/loader.ts
 import { readFile } from "fs/promises";
+import { dirname, join, resolve } from "path";
+import matter2 from "gray-matter";
+var DEFAULTS_FILE_NAME = "defaults.md";
+async function loadPromptFile(filePath, options = {}) {
+  const content = await readFile(filePath, "utf-8");
+  const parsed = parsePrompt(content, filePath);
+  const root = options.defaultsRoot ?? dirname(filePath);
+  const defaults = await loadDefaultsForPath(filePath, root);
+  const asset = applyDefaults(parsed.asset, defaults);
+  return {
+    ...parsed,
+    asset
+  };
+}
+async function loadDefaultsForPath(filePath, defaultsRoot) {
+  const directories = getDirectoriesToCheck(filePath, defaultsRoot);
+  let merged = {};
+  for (const dir of directories) {
+    const defaultsPath = join(dir, DEFAULTS_FILE_NAME);
+    try {
+      const defaultsContent = await readFile(defaultsPath, "utf-8");
+      const defaults = parseDefaults(defaultsContent);
+      merged = mergeDefaults(merged, defaults);
+    } catch (error) {
+      if (error.code !== "ENOENT") {
+        throw error;
+      }
+    }
+  }
+  return merged;
+}
+function getDirectoriesToCheck(filePath, defaultsRoot) {
+  const dirs = [];
+  let current = resolve(dirname(filePath));
+  const boundary = defaultsRoot ? resolve(defaultsRoot) : void 0;
+  while (true) {
+    dirs.unshift(current);
+    if (boundary && current === boundary || current === dirname(current)) {
+      break;
+    }
+    current = dirname(current);
+  }
+  return dirs;
+}
+function parseDefaults(content) {
+  const { data: frontMatter, content: body } = matter2(content);
+  const sections = extractSections(body);
+  return PromptDefaultsSchema.parse({
+    ...frontMatter,
+    sections: {
+      system_instructions: sections.system_instructions
+    }
+  });
+}
+function mergeDefaults(base, local) {
+  return {
+    metadata: {
+      ...base.metadata ?? {},
+      ...local.metadata ?? {}
+    },
+    sections: {
+      ...base.sections ?? {},
+      ...local.sections ?? {}
+    }
+  };
+}
+function applyDefaults(asset, defaults) {
+  const hasDefaultMetadata = defaults.metadata && Object.keys(defaults.metadata).length > 0;
+  const hasDefaultSystem = !!defaults.sections?.system_instructions;
+  if (!hasDefaultMetadata && !hasDefaultSystem) {
+    return asset;
+  }
+  const mergedMetadata = {
+    ...defaults.metadata ?? {},
+    ...asset.metadata ?? {}
+  };
+  const metadata = Object.keys(mergedMetadata).length > 0 ? mergedMetadata : void 0;
+  const systemInstructions = asset.sections?.system_instructions ?? defaults.sections?.system_instructions;
+  const sections = asset.sections ? { ...asset.sections, system_instructions: systemInstructions } : systemInstructions ? { system_instructions: systemInstructions } : void 0;
+  return {
+    ...asset,
+    metadata,
+    sections
+  };
+}
 
 // src/renderer/interpolate.ts
 var VARIABLE_RE = /\{\{\s*([a-zA-Z_][a-zA-Z0-9_]*)\s*\}\}/g;
@@ -184,20 +275,20 @@ function extractVariables(template) {
 
 // src/composition/resolve-includes.ts
 import { readFile as readFile2 } from "fs/promises";
-import { resolve, dirname } from "path";
+import { resolve as resolve2, dirname as dirname2 } 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);
+  const baseDir = dirname2(basePath);
+  const resolvedPath = resolve2(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);
+    const fullPath = resolve2(baseDir, includePath);
     if (visited.has(fullPath)) {
       throw new Error(`Circular include detected: ${fullPath} (included from ${basePath})`);
     }
@@ -399,8 +490,7 @@ async function validate(args) {
   let warnCount = 0;
   for (const file of files) {
     try {
-      const content = await readFile3(file, "utf-8");
-      const { asset, raw } = parsePrompt(content, file);
+      const { asset, raw } = await loadPromptFile(file, { defaultsRoot: dir });
       const result = await validateAssetWithIncludes(asset, file, Object.keys(raw.frontMatter));
       if (result.errors.length > 0) {
         errorCount += result.errors.length;
@@ -435,16 +525,16 @@ async function collectPromptFiles(dir) {
   const results = [];
   const entries = await readdir(dir, { withFileTypes: true, recursive: true });
   for (const entry of entries) {
-    if (entry.isFile() && extname(entry.name) === ".md" && !entry.name.endsWith(".test.md")) {
-      results.push(join(entry.parentPath ?? dir, entry.name));
+    if (entry.isFile() && extname(entry.name) === ".md" && !entry.name.endsWith(".test.md") && entry.name !== "defaults.md") {
+      results.push(join2(entry.parentPath ?? dir, entry.name));
     }
   }
   return results.sort();
 }
 
 // src/cli/commands/compile.ts
-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";
+import { readdir as readdir2, writeFile, mkdir, rm } from "fs/promises";
+import { join as join3, extname as extname2, relative, dirname as dirname3 } from "path";
 var HELP2 = `
 promptopskit compile <sourceDir> <outputDir> [options]
 
@@ -489,15 +579,14 @@ async function compile(args) {
   for (const file of files) {
     const rel = relative(sourceDir, file).replace(/\.md$/, "");
     const outExt = format === "esm" ? ".mjs" : ".json";
-    const outPath = join2(outputDir, rel + outExt);
+    const outPath = join3(outputDir, rel + outExt);
     try {
-      const content = await readFile4(file, "utf-8");
-      const { asset: parsed } = parsePrompt(content, file);
+      const { asset: parsed } = await loadPromptFile(file, { defaultsRoot: sourceDir });
       const asset = parsed.includes && parsed.includes.length > 0 ? await resolveIncludes(parsed, file) : parsed;
       if (dryRun) {
         console.log(`  Would create: ${outPath}`);
       } else {
-        await mkdir(dirname2(outPath), { recursive: true });
+        await mkdir(dirname3(outPath), { recursive: true });
         if (format === "esm") {
           const esmContent = `export default ${JSON.stringify(asset, null, 2)};
 `;
@@ -536,15 +625,15 @@ async function collectPromptFiles2(dir) {
   const results = [];
   const entries = await readdir2(dir, { withFileTypes: true, recursive: true });
   for (const entry of entries) {
-    if (entry.isFile() && extname2(entry.name) === ".md" && !entry.name.endsWith(".test.md")) {
-      results.push(join2(entry.parentPath ?? dir, entry.name));
+    if (entry.isFile() && extname2(entry.name) === ".md" && !entry.name.endsWith(".test.md") && entry.name !== "defaults.md") {
+      results.push(join3(entry.parentPath ?? dir, entry.name));
     }
   }
   return results.sort();
 }
 
 // src/cli/commands/render.ts
-import { readFile as readFile5 } from "fs/promises";
+import { readFile as readFile3 } from "fs/promises";
 import { existsSync } from "fs";
 
 // src/overrides/apply-overrides.ts
@@ -607,13 +696,13 @@ async function render(args) {
   const jsonOutput = args.includes("--json");
   let variables = {};
   if (varsFile) {
-    const varsContent = await readFile5(varsFile, "utf-8");
+    const varsContent = await readFile3(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 readFile5(sidecarPath, "utf-8");
+      const sidecarContent = await readFile3(sidecarPath, "utf-8");
       const parsed2 = yaml(`---
 ${sidecarContent}---
 `);
@@ -623,8 +712,7 @@ ${sidecarContent}---
       }
     }
   }
-  const content = await readFile5(file, "utf-8");
-  const { asset: parsed } = parsePrompt(content, file);
+  const { asset: parsed } = await loadPromptFile(file);
   const resolved = parsed.includes && parsed.includes.length > 0 ? await resolveIncludes(parsed, file) : parsed;
   const overridden = applyOverrides(resolved, {
     environment: env,
@@ -671,7 +759,6 @@ function getFlag2(args, flag) {
 }
 
 // src/cli/commands/inspect.ts
-import { readFile as readFile6 } from "fs/promises";
 var HELP4 = `
 promptopskit inspect <file>
 
@@ -690,15 +777,14 @@ async function inspect(args) {
     console.error("Error: Please provide a prompt file to inspect.");
     process.exit(1);
   }
-  const content = await readFile6(file, "utf-8");
-  const { asset: parsed } = parsePrompt(content, file);
+  const { asset: parsed } = await loadPromptFile(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 dirname3 } from "path";
+import { join as join4, dirname as dirname4 } from "path";
 import { existsSync as existsSync2, readFileSync } from "fs";
 var HELP5 = `
 promptopskit init [dir]
@@ -716,6 +802,7 @@ model: gpt-5.4
 context:
   inputs:
     - name
+    - app_context
 includes:
   - ./shared/tone.md
 ---
@@ -723,6 +810,7 @@ includes:
 # System instructions
 
 You are a friendly assistant. Be helpful and concise.
+Current app context: {{ app_context }}.
 
 # Prompt template
 
@@ -737,13 +825,25 @@ schema_version: 1
 
 Always be polite, professional, and concise. Avoid jargon unless the user uses it first.
 `.trimStart();
+var DEFAULTS = `---
+metadata:
+  owner: my-team
+  review_required: true
+---
+
+# System instructions
+
+You are a helpful AI assistant. Follow company guidelines at all times.
+`.trimStart();
 var TEST_SIDECAR = `cases:
   - name: basic-greeting
     variables:
       name: "World"
+      app_context: "Welcome screen"
   - name: named-greeting
     variables:
       name: "Alice"
+      app_context: "Settings page"
 `;
 async function init(args) {
   if (args.includes("--help") || args.includes("-h")) {
@@ -752,9 +852,10 @@ async function init(args) {
   }
   const dir = args.find((a) => !a.startsWith("--")) ?? "./prompts";
   const files = [
-    { path: join3(dir, "hello.md"), content: HELLO_PROMPT },
-    { path: join3(dir, "hello.test.yaml"), content: TEST_SIDECAR },
-    { path: join3(dir, "shared", "tone.md"), content: TONE_INCLUDE }
+    { path: join4(dir, "defaults.md"), content: DEFAULTS },
+    { path: join4(dir, "hello.md"), content: HELLO_PROMPT },
+    { path: join4(dir, "hello.test.yaml"), content: TEST_SIDECAR },
+    { path: join4(dir, "shared", "tone.md"), content: TONE_INCLUDE }
   ];
   let created = 0;
   let skipped = 0;
@@ -764,7 +865,7 @@ async function init(args) {
       skipped++;
       continue;
     }
-    await mkdir2(dirname3(file.path), { recursive: true });
+    await mkdir2(dirname4(file.path), { recursive: true });
     await writeFile2(file.path, file.content, "utf-8");
     console.log(`  \u2713 ${file.path}`);
     created++;
@@ -786,7 +887,7 @@ async function init(args) {
 
 // src/cli/commands/skill.ts
 import { writeFile as writeFile3, mkdir as mkdir3 } from "fs/promises";
-import { dirname as dirname4 } from "path";
+import { dirname as dirname5 } from "path";
 import { existsSync as existsSync3 } from "fs";
 var HELP6 = `
 promptopskit skill [--target <target>] [--force]
@@ -851,7 +952,7 @@ async function skill(args) {
     return;
   }
   const content = config.wrap(SKILL_CONTENT);
-  await mkdir3(dirname4(filePath), { recursive: true });
+  await mkdir3(dirname5(filePath), { recursive: true });
   await writeFile3(filePath, content, "utf-8");
   console.log(`  \u2713 ${filePath}`);
   console.log();
@@ -963,6 +1064,35 @@ 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 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:
+- \`metadata\` (front matter) \u2014 merged with prompt-local metadata
+- \`# System instructions\` (body section) \u2014 used when the prompt has none
+
+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
@@ -1125,7 +1255,7 @@ Hello {{ name }}
 
 | Command | Description |
 |---------|-------------|
-| \`promptopskit init [dir]\` | Scaffold a prompts directory with starter files |
+| \`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 |
@@ -1143,8 +1273,9 @@ Hello {{ name }}
 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\`
+9. **Use \`defaults.md\`** to share 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