@promptscript/cli 1.0.0-alpha.9 → 1.0.0-rc.2

package/CHANGELOG.md

@@ -5,6 +5,27 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.0.0-rc.2](https://github.com/mrwogu/promptscript/compare/v1.0.0-rc.1...v1.0.0-rc.2) (2026-02-01)
+
+
+### chore
+
+* prepare rc release ([87b9a04](https://github.com/mrwogu/promptscript/commit/87b9a0494e2c220c0c9cc226fc751c09613494ea))
+
+## [1.0.0-rc.1](https://github.com/mrwogu/promptscript/compare/v1.0.0-alpha.10...v1.0.0-rc.1) (2026-02-01)
+
+
+### chore
+
+* prepare rc release ([756f820](https://github.com/mrwogu/promptscript/commit/756f82096a2a511e6a88aa3b45a56c92c3fab68c))
+
+## [1.0.0-alpha.10](https://github.com/mrwogu/promptscript/compare/v1.0.0-alpha.9...v1.0.0-alpha.10) (2026-01-31)
+
+
+### chore
+
+* prepare alpha release ([c6595b6](https://github.com/mrwogu/promptscript/commit/c6595b6fd639f93f0093c503e8468fbbbf057cf9))
+
 ## [1.0.0-alpha.9](https://github.com/mrwogu/promptscript/compare/v1.0.0-alpha.8...v1.0.0-alpha.9) (2026-01-30)
 
 

package/index.js

@@ -171,6 +171,79 @@ var CircularDependencyError = class extends ResolveError {
   }
 };
 
+// packages/core/src/errors/template.ts
+var MissingParamError = class extends PSError {
+  /** Name of the missing parameter */
+  paramName;
+  /** Path of the template file */
+  templatePath;
+  constructor(paramName, templatePath, options) {
+    super(
+      `Missing required parameter '${paramName}' for template '${templatePath}'`,
+      "PS2010" /* MISSING_PARAM */,
+      options
+    );
+    this.name = "MissingParamError";
+    this.paramName = paramName;
+    this.templatePath = templatePath;
+  }
+};
+var UnknownParamError = class extends PSError {
+  /** Name of the unknown parameter */
+  paramName;
+  /** Path of the template file */
+  templatePath;
+  /** Available parameter names */
+  availableParams;
+  constructor(paramName, templatePath, availableParams, options) {
+    const suggestion = availableParams.length > 0 ? `. Available parameters: ${availableParams.join(", ")}` : ". This template has no parameters.";
+    super(
+      `Unknown parameter '${paramName}' for template '${templatePath}'${suggestion}`,
+      "PS2011" /* UNKNOWN_PARAM */,
+      options
+    );
+    this.name = "UnknownParamError";
+    this.paramName = paramName;
+    this.templatePath = templatePath;
+    this.availableParams = availableParams;
+  }
+};
+var ParamTypeMismatchError = class extends PSError {
+  /** Name of the parameter */
+  paramName;
+  /** Expected type */
+  expectedType;
+  /** Actual type */
+  actualType;
+  constructor(paramName, expectedType, actualType, options) {
+    super(
+      `Type mismatch for parameter '${paramName}': expected ${expectedType}, got ${actualType}`,
+      "PS2012" /* PARAM_TYPE_MISMATCH */,
+      options
+    );
+    this.name = "ParamTypeMismatchError";
+    this.paramName = paramName;
+    this.expectedType = expectedType;
+    this.actualType = actualType;
+  }
+};
+var UndefinedVariableError = class extends PSError {
+  /** Name of the undefined variable */
+  variableName;
+  /** File where the variable was used */
+  sourceFile;
+  constructor(variableName, sourceFile, options) {
+    super(
+      `Undefined template variable '{{${variableName}}}' in '${sourceFile}'`,
+      "PS2013" /* UNDEFINED_VARIABLE */,
+      options
+    );
+    this.name = "UndefinedVariableError";
+    this.variableName = variableName;
+    this.sourceFile = sourceFile;
+  }
+};
+
 // packages/core/src/utils/merge.ts
 var DEFAULT_MERGE_OPTIONS = {
   arrayStrategy: "unique",
@@ -304,6 +377,219 @@ var noopLogger = {
   }
 };
 
+// packages/core/src/template.ts
+function paramTypeToString(paramType) {
+  switch (paramType.kind) {
+    case "string":
+      return "string";
+    case "number":
+      return "number";
+    case "boolean":
+      return "boolean";
+    case "enum":
+      return `enum(${paramType.options.map((o) => `"${o}"`).join(", ")})`;
+  }
+}
+function getValueType(value) {
+  if (value === null) return "null";
+  if (typeof value === "string") return "string";
+  if (typeof value === "number") return "number";
+  if (typeof value === "boolean") return "boolean";
+  if (Array.isArray(value)) return "array";
+  if (typeof value === "object" && "type" in value) {
+    const typed = value;
+    if (typed.type === "TextContent") return "string";
+    if (typed.type === "TemplateExpression") return "template";
+  }
+  return "object";
+}
+function validateParamType(paramName, value, expectedType, location) {
+  const actualType = getValueType(value);
+  const expected = paramTypeToString(expectedType);
+  switch (expectedType.kind) {
+    case "string":
+      if (actualType !== "string") {
+        throw new ParamTypeMismatchError(paramName, expected, actualType, { location });
+      }
+      break;
+    case "number":
+      if (actualType !== "number") {
+        throw new ParamTypeMismatchError(paramName, expected, actualType, { location });
+      }
+      break;
+    case "boolean":
+      if (actualType !== "boolean") {
+        throw new ParamTypeMismatchError(paramName, expected, actualType, { location });
+      }
+      break;
+    case "enum":
+      if (actualType !== "string" || !expectedType.options.includes(value)) {
+        throw new ParamTypeMismatchError(paramName, expected, String(value), { location });
+      }
+      break;
+  }
+}
+function bindParams(args, defs, templatePath, callLocation) {
+  const result = /* @__PURE__ */ new Map();
+  if (!defs || defs.length === 0) {
+    if (args && args.length > 0 && args[0] !== void 0) {
+      throw new UnknownParamError(args[0].name, templatePath, [], { location: callLocation });
+    }
+    return result;
+  }
+  const defMap = /* @__PURE__ */ new Map();
+  for (const def of defs) {
+    defMap.set(def.name, def);
+  }
+  const providedNames = /* @__PURE__ */ new Set();
+  if (args) {
+    for (const arg of args) {
+      const def = defMap.get(arg.name);
+      if (!def) {
+        throw new UnknownParamError(
+          arg.name,
+          templatePath,
+          defs.map((d) => d.name),
+          { location: arg.loc }
+        );
+      }
+      validateParamType(arg.name, arg.value, def.paramType, arg.loc);
+      result.set(arg.name, arg.value);
+      providedNames.add(arg.name);
+    }
+  }
+  for (const def of defs) {
+    if (!providedNames.has(def.name)) {
+      if (def.defaultValue !== void 0) {
+        result.set(def.name, def.defaultValue);
+      } else if (!def.optional) {
+        throw new MissingParamError(def.name, templatePath, { location: callLocation });
+      }
+    }
+  }
+  return result;
+}
+function valueToString(value) {
+  if (value === null) return "null";
+  if (typeof value === "string") return value;
+  if (typeof value === "number") return String(value);
+  if (typeof value === "boolean") return String(value);
+  if (Array.isArray(value)) return JSON.stringify(value);
+  if (typeof value === "object" && "type" in value) {
+    const typed = value;
+    if (typed.type === "TextContent") {
+      return value.value;
+    }
+  }
+  return JSON.stringify(value);
+}
+function interpolateText(text, ctx) {
+  const pattern = /\{\{([a-zA-Z_][a-zA-Z0-9_]*)\}\}/g;
+  return text.replace(pattern, (_match, varName) => {
+    const value = ctx.params.get(varName);
+    if (value === void 0) {
+      throw new UndefinedVariableError(varName, ctx.sourceFile);
+    }
+    return valueToString(value);
+  });
+}
+function interpolateValue(value, ctx) {
+  if (value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    return value.map((v) => interpolateValue(v, ctx));
+  }
+  if (typeof value === "object" && "type" in value) {
+    const typed = value;
+    if (typed.type === "TemplateExpression") {
+      const expr = value;
+      const resolved = ctx.params.get(expr.name);
+      if (resolved === void 0) {
+        throw new UndefinedVariableError(expr.name, ctx.sourceFile, { location: expr.loc });
+      }
+      return resolved;
+    }
+    if (typed.type === "TextContent") {
+      const text = value;
+      return {
+        ...text,
+        value: interpolateText(text.value, ctx)
+      };
+    }
+    if (typed.type === "TypeExpression") {
+      return value;
+    }
+  }
+  if (typeof value === "object") {
+    const result = {};
+    for (const [key, val] of Object.entries(value)) {
+      result[key] = interpolateValue(val, ctx);
+    }
+    return result;
+  }
+  return value;
+}
+function interpolateContent(content, ctx) {
+  switch (content.type) {
+    case "TextContent":
+      return {
+        ...content,
+        value: interpolateText(content.value, ctx)
+      };
+    case "ObjectContent":
+      return {
+        ...content,
+        properties: interpolateProperties(content.properties, ctx)
+      };
+    case "ArrayContent":
+      return {
+        ...content,
+        elements: content.elements.map((e) => interpolateValue(e, ctx))
+      };
+    case "MixedContent":
+      return {
+        ...content,
+        text: content.text ? { ...content.text, value: interpolateText(content.text.value, ctx) } : void 0,
+        properties: interpolateProperties(content.properties, ctx)
+      };
+  }
+}
+function interpolateProperties(properties, ctx) {
+  const result = {};
+  for (const [key, value] of Object.entries(properties)) {
+    result[key] = interpolateValue(value, ctx);
+  }
+  return result;
+}
+function interpolateBlock(block, ctx) {
+  return {
+    ...block,
+    content: interpolateContent(block.content, ctx)
+  };
+}
+function interpolateAST(ast, ctx) {
+  if (ctx.params.size === 0) {
+    return ast;
+  }
+  return {
+    ...ast,
+    // Interpolate meta fields (but not params definitions)
+    meta: ast.meta ? {
+      ...ast.meta,
+      fields: interpolateProperties(ast.meta.fields, ctx)
+      // Keep params as-is (they're definitions, not values to interpolate)
+    } : void 0,
+    // Interpolate blocks
+    blocks: ast.blocks.map((b) => interpolateBlock(b, ctx)),
+    // Interpolate extend blocks
+    extends: ast.extends.map((e) => ({
+      ...e,
+      content: interpolateContent(e.content, ctx)
+    }))
+  };
+}
+
 // packages/cli/src/commands/init.ts
 import { fileURLToPath } from "url";
 import { dirname as dirname3 } from "path";
@@ -15215,6 +15501,29 @@ var Enum = createToken({
   pattern: /enum/,
   longer_alt: Identifier
 });
+var StringType = createToken({
+  name: "StringType",
+  pattern: /string/,
+  longer_alt: Identifier
+});
+var NumberType = createToken({
+  name: "NumberType",
+  pattern: /number/,
+  longer_alt: Identifier
+});
+var BooleanType = createToken({
+  name: "BooleanType",
+  pattern: /boolean/,
+  longer_alt: Identifier
+});
+var TemplateOpen = createToken({
+  name: "TemplateOpen",
+  pattern: /\{\{/
+});
+var TemplateClose = createToken({
+  name: "TemplateClose",
+  pattern: /\}\}/
+});
 var At = createToken({
   name: "At",
   pattern: /@/
@@ -15288,6 +15597,9 @@ var allTokens = [
   // Paths (must be before DotDot to handle ../)
   PathReference,
   RelativePath,
+  // Template expression tokens (multi-char, before single braces)
+  TemplateOpen,
+  TemplateClose,
   // Multi-char symbols before single-char
   DotDot,
   // Keywords before Identifier
@@ -15301,6 +15613,9 @@ var allTokens = [
   Null,
   Range,
   Enum,
+  StringType,
+  NumberType,
+  BooleanType,
   // Single-char symbols
   At,
   LBrace,
@@ -15366,22 +15681,24 @@ var PromptScriptParser = class extends CstParser {
   });
   /**
    * inheritDecl
-   *   : '@' 'inherit' pathRef
+   *   : '@' 'inherit' pathRef paramCallList?
    */
   inheritDecl = this.RULE("inheritDecl", () => {
     this.CONSUME(At);
     this.CONSUME(Inherit);
     this.SUBRULE(this.pathRef);
+    this.OPTION(() => this.SUBRULE(this.paramCallList));
   });
   /**
    * useDecl
-   *   : '@' 'use' pathRef ('as' Identifier)?
+   *   : '@' 'use' pathRef paramCallList? ('as' Identifier)?
    */
   useDecl = this.RULE("useDecl", () => {
     this.CONSUME(At);
     this.CONSUME(Use);
     this.SUBRULE(this.pathRef);
-    this.OPTION(() => {
+    this.OPTION(() => this.SUBRULE(this.paramCallList));
+    this.OPTION2(() => {
       this.CONSUME(As);
       this.CONSUME(Identifier);
     });
@@ -15432,10 +15749,18 @@ var PromptScriptParser = class extends CstParser {
   });
   /**
    * field
-   *   : (Identifier | StringLiteral) '?'? ':' value ('=' value)?
+   *   : (Identifier | StringLiteral | StringType | NumberType | BooleanType) '?'? ':' value ('=' value)?
+   *
+   * Note: StringType/NumberType/BooleanType are also valid field keys (e.g., { string: "value" })
    */
   field = this.RULE("field", () => {
-    this.OR([{ ALT: () => this.CONSUME(Identifier) }, { ALT: () => this.CONSUME(StringLiteral) }]);
+    this.OR([
+      { ALT: () => this.CONSUME(Identifier) },
+      { ALT: () => this.CONSUME(StringLiteral) },
+      { ALT: () => this.CONSUME(StringType) },
+      { ALT: () => this.CONSUME(NumberType) },
+      { ALT: () => this.CONSUME(BooleanType) }
+    ]);
     this.OPTION(() => this.CONSUME(Question));
     this.CONSUME(Colon);
     this.SUBRULE(this.value);
@@ -15447,7 +15772,10 @@ var PromptScriptParser = class extends CstParser {
   /**
    * value
    *   : StringLiteral | NumberLiteral | True | False | Null
-   *   | TextBlock | array | object | typeExpr | Identifier
+   *   | TextBlock | array | paramDefList | object | typeExpr | templateExpr | Identifier
+   *
+   * Note: paramDefList must come before object since both start with LBrace,
+   * and paramDefList is more specific (contains paramType like 'string', 'number', 'boolean').
    */
   value = this.RULE("value", () => {
     this.OR([
@@ -15458,11 +15786,42 @@ var PromptScriptParser = class extends CstParser {
       { ALT: () => this.CONSUME(Null) },
       { ALT: () => this.CONSUME(TextBlock) },
       { ALT: () => this.SUBRULE(this.array) },
+      { ALT: () => this.SUBRULE(this.paramDefList), GATE: () => this.isParamDefListAhead() },
       { ALT: () => this.SUBRULE(this.object) },
       { ALT: () => this.SUBRULE(this.typeExpr) },
+      { ALT: () => this.SUBRULE(this.templateExpr) },
       { ALT: () => this.CONSUME(Identifier) }
     ]);
   });
+  /**
+   * Check if we're about to parse a paramDefList.
+   * A paramDefList starts with '{' and contains paramDef entries like 'name: string'.
+   */
+  isParamDefListAhead() {
+    const tokens = this.LA(1);
+    if (!tokens || tokens.tokenType?.name !== "LBrace") return false;
+    const second = this.LA(2);
+    if (!second || second.tokenType?.name !== "Identifier") return false;
+    const third = this.LA(3);
+    if (!third) return false;
+    if (third.tokenType?.name === "Colon") {
+      const fourth = this.LA(4);
+      if (!fourth) return false;
+      return ["StringType", "NumberType", "BooleanType", "Enum"].includes(
+        fourth.tokenType?.name ?? ""
+      );
+    }
+    if (third.tokenType?.name === "Question") {
+      const fourth = this.LA(4);
+      if (!fourth || fourth.tokenType?.name !== "Colon") return false;
+      const fifth = this.LA(5);
+      if (!fifth) return false;
+      return ["StringType", "NumberType", "BooleanType", "Enum"].includes(
+        fifth.tokenType?.name ?? ""
+      );
+    }
+    return false;
+  }
   /**
    * array
    *   : '[' (value (',' value?)*)? ']'
@@ -15547,14 +15906,90 @@ var PromptScriptParser = class extends CstParser {
       this.CONSUME2(Identifier);
     });
   });
+  // ============================================================
+  // Template Parameter Rules
+  // ============================================================
+  /**
+   * paramCallList (for @inherit/@use calls)
+   *   : '(' (paramArg (',' paramArg)*)? ')'
+   */
+  paramCallList = this.RULE("paramCallList", () => {
+    this.CONSUME(LParen);
+    this.OPTION(() => {
+      this.SUBRULE(this.paramArg);
+      this.MANY(() => {
+        this.CONSUME(Comma);
+        this.SUBRULE2(this.paramArg);
+      });
+    });
+    this.CONSUME(RParen);
+  });
+  /**
+   * paramArg
+   *   : Identifier ':' value
+   */
+  paramArg = this.RULE("paramArg", () => {
+    this.CONSUME(Identifier);
+    this.CONSUME(Colon);
+    this.SUBRULE(this.value);
+  });
+  /**
+   * paramDefList (for @meta { params: {...} })
+   *   : '{' (paramDef ','?)* '}'
+   */
+  paramDefList = this.RULE("paramDefList", () => {
+    this.CONSUME(LBrace);
+    this.MANY(() => {
+      this.SUBRULE(this.paramDef);
+      this.OPTION(() => this.CONSUME(Comma));
+    });
+    this.CONSUME(RBrace);
+  });
+  /**
+   * paramDef
+   *   : Identifier '?'? ':' paramType ('=' value)?
+   */
+  paramDef = this.RULE("paramDef", () => {
+    this.CONSUME(Identifier);
+    this.OPTION(() => this.CONSUME(Question));
+    this.CONSUME(Colon);
+    this.SUBRULE(this.paramType);
+    this.OPTION2(() => {
+      this.CONSUME(Equals);
+      this.SUBRULE(this.value);
+    });
+  });
+  /**
+   * paramType
+   *   : 'string' | 'number' | 'boolean' | enumType
+   */
+  paramType = this.RULE("paramType", () => {
+    this.OR([
+      { ALT: () => this.CONSUME(StringType) },
+      { ALT: () => this.CONSUME(NumberType) },
+      { ALT: () => this.CONSUME(BooleanType) },
+      { ALT: () => this.SUBRULE(this.enumType) }
+    ]);
+  });
+  /**
+   * templateExpr
+   *   : '{{' Identifier '}}'
+   */
+  templateExpr = this.RULE("templateExpr", () => {
+    this.CONSUME(TemplateOpen);
+    this.CONSUME(Identifier);
+    this.CONSUME(TemplateClose);
+  });
 };
 var parser = new PromptScriptParser();
 
 // packages/parser/src/grammar/visitor.ts
 var BaseVisitor = parser.getBaseCstVisitorConstructor();
+var defaultEnvProvider = (name) => process.env[name];
 var PromptScriptVisitor = class extends BaseVisitor {
   filename = "<unknown>";
   interpolateEnv = false;
+  envProvider = defaultEnvProvider;
   constructor() {
     super();
     this.validateVisitor();
@@ -15571,6 +16006,19 @@ var PromptScriptVisitor = class extends BaseVisitor {
   setInterpolateEnv(enabled) {
     this.interpolateEnv = enabled;
   }
+  /**
+   * Set a custom environment provider function.
+   * Use this to provide environment variables from sources other than process.env.
+   */
+  setEnvProvider(provider) {
+    this.envProvider = provider;
+  }
+  /**
+   * Reset the environment provider to the default (process.env).
+   */
+  resetEnvProvider() {
+    this.envProvider = defaultEnvProvider;
+  }
   /**
    * Create source location from a token.
    */
@@ -15617,27 +16065,40 @@ var PromptScriptVisitor = class extends BaseVisitor {
    */
   metaBlock(ctx) {
     const fields = {};
+    let params;
     if (ctx.field) {
       for (const fieldNode of ctx.field) {
-        const { name, value } = this.visit(fieldNode);
-        fields[name] = value;
+        const { name, value, isParamsDef, paramsDefs } = this.visit(fieldNode);
+        if (isParamsDef && paramsDefs) {
+          params = paramsDefs;
+        } else {
+          fields[name] = value;
+        }
       }
     }
-    return {
+    const meta = {
       type: "MetaBlock",
       fields,
       loc: this.loc(ctx.At[0])
     };
+    if (params) {
+      meta.params = params;
+    }
+    return meta;
   }
   /**
    * inheritDecl → InheritDeclaration
    */
   inheritDecl(ctx) {
-    return {
+    const inherit = {
       type: "InheritDeclaration",
       path: this.visit(ctx.pathRef[0]),
       loc: this.loc(ctx.At[0])
     };
+    if (ctx.paramCallList) {
+      inherit.params = this.visit(ctx.paramCallList[0]);
+    }
+    return inherit;
   }
   /**
    * useDecl → UseDeclaration
@@ -15648,6 +16109,9 @@ var PromptScriptVisitor = class extends BaseVisitor {
       path: this.visit(ctx.pathRef[0]),
       loc: this.loc(ctx.At[0])
     };
+    if (ctx.paramCallList) {
+      use.params = this.visit(ctx.paramCallList[0]);
+    }
     if (ctx.Identifier) {
       use.alias = ctx.Identifier[0].image;
     }
@@ -15769,20 +16233,31 @@ var PromptScriptVisitor = class extends BaseVisitor {
     return this.parseStringLiteral(token.image);
   }
   /**
-   * field → { name, value, optional, defaultValue }
+   * field → { name, value, optional, defaultValue, isParamsDef?, paramsDefs? }
    */
   field(ctx) {
     let name;
     if (ctx.Identifier) {
       name = ctx.Identifier[0].image;
-    } else {
+    } else if (ctx.StringLiteral) {
       name = this.parseStringLiteral(ctx.StringLiteral[0].image);
+    } else if (ctx.StringType) {
+      name = "string";
+    } else if (ctx.NumberType) {
+      name = "number";
+    } else if (ctx.BooleanType) {
+      name = "boolean";
+    } else {
+      throw new Error("Unknown field key type");
     }
     const optional = ctx.Question ? true : void 0;
     const values2 = ctx.value;
-    const value = this.visit(values2[0]);
+    const valueResult = this.visit(values2[0]);
     const defaultValue = values2.length > 1 ? this.visit(values2[1]) : void 0;
-    return { name, value, optional, defaultValue };
+    if (name === "params" && Array.isArray(valueResult) && valueResult.length > 0 && valueResult[0]?.type === "ParamDefinition") {
+      return { name, value: {}, isParamsDef: true, paramsDefs: valueResult };
+    }
+    return { name, value: valueResult, optional, defaultValue };
   }
   /**
    * value → Value
@@ -15819,12 +16294,18 @@ var PromptScriptVisitor = class extends BaseVisitor {
     if (ctx.array) {
       return this.visit(ctx.array[0]);
     }
+    if (ctx.paramDefList) {
+      return this.visit(ctx.paramDefList[0]);
+    }
     if (ctx.object) {
       return this.visit(ctx.object[0]);
     }
     if (ctx.typeExpr) {
       return this.visit(ctx.typeExpr[0]);
     }
+    if (ctx.templateExpr) {
+      return this.visit(ctx.templateExpr[0]);
+    }
     if (ctx.Identifier) {
       return ctx.Identifier[0].image;
     }
@@ -15903,6 +16384,87 @@ var PromptScriptVisitor = class extends BaseVisitor {
     return ctx.Identifier.map((token) => token.image).join(".");
   }
   // ============================================================
+  // Template Parameter Visitor Methods
+  // ============================================================
+  /**
+   * paramCallList → ParamArgument[]
+   */
+  paramCallList(ctx) {
+    if (!ctx.paramArg) {
+      return [];
+    }
+    return ctx.paramArg.map((node) => this.visit(node));
+  }
+  /**
+   * paramArg → ParamArgument
+   */
+  paramArg(ctx) {
+    return {
+      type: "ParamArgument",
+      name: ctx.Identifier[0].image,
+      value: this.visit(ctx.value[0]),
+      loc: this.loc(ctx.Identifier[0])
+    };
+  }
+  /**
+   * paramDefList → ParamDefinition[]
+   */
+  paramDefList(ctx) {
+    if (!ctx.paramDef) {
+      return [];
+    }
+    return ctx.paramDef.map((node) => this.visit(node));
+  }
+  /**
+   * paramDef → ParamDefinition
+   */
+  paramDef(ctx) {
+    const name = ctx.Identifier[0].image;
+    const optional = ctx.Question !== void 0;
+    const paramType = this.visit(ctx.paramType[0]);
+    const defaultValue = ctx.value ? this.visit(ctx.value[0]) : void 0;
+    return {
+      type: "ParamDefinition",
+      name,
+      paramType,
+      optional: optional || defaultValue !== void 0,
+      defaultValue,
+      loc: this.loc(ctx.Identifier[0])
+    };
+  }
+  /**
+   * paramType → ParamType
+   */
+  paramType(ctx) {
+    if (ctx.StringType) {
+      return { kind: "string" };
+    }
+    if (ctx.NumberType) {
+      return { kind: "number" };
+    }
+    if (ctx.BooleanType) {
+      return { kind: "boolean" };
+    }
+    if (ctx.enumType) {
+      const enumExpr = this.visit(ctx.enumType[0]);
+      return {
+        kind: "enum",
+        options: enumExpr.constraints?.options ?? []
+      };
+    }
+    throw new Error("Unknown param type");
+  }
+  /**
+   * templateExpr → TemplateExpression
+   */
+  templateExpr(ctx) {
+    return {
+      type: "TemplateExpression",
+      name: ctx.Identifier[0].image,
+      loc: this.loc(ctx.TemplateOpen[0])
+    };
+  }
+  // ============================================================
   // Helper Methods
   // ============================================================
   /**
@@ -15924,7 +16486,7 @@ var PromptScriptVisitor = class extends BaseVisitor {
   interpolateEnvVars(text) {
     const envVarPattern = /\$\{([A-Za-z_]\w*)(?::-([^}]*))?\}/g;
     return text.replace(envVarPattern, (_match, varName, defaultValue) => {
-      const envValue = process.env[varName];
+      const envValue = this.envProvider(varName);
       if (envValue !== void 0) {
         return envValue;
       }
@@ -15983,7 +16545,8 @@ function parse(source, options = {}) {
     filename = "<unknown>",
     tolerant = false,
     recovery = false,
-    interpolateEnv = false
+    interpolateEnv = false,
+    envProvider
   } = options;
   const isRecoveryMode = tolerant || recovery;
   const errors = [];
@@ -16018,6 +16581,11 @@ function parse(source, options = {}) {
   }
   try {
     visitor.setInterpolateEnv(interpolateEnv);
+    if (envProvider) {
+      visitor.setEnvProvider(envProvider);
+    } else {
+      visitor.resetEnvProvider();
+    }
     const ast = visitor.visit(cst, filename);
     return { ast, errors };
   } catch (err) {
@@ -16987,8 +17555,28 @@ var Resolver = class {
       sources.push(...parent.sources);
       errors.push(...parent.errors);
       if (parent.ast) {
+        let resolvedParent = parent.ast;
+        if (parent.ast.meta?.params || ast.inherit.params) {
+          this.logger.debug(`Binding template parameters for ${parentPath}`);
+          try {
+            const params = bindParams(
+              ast.inherit.params,
+              parent.ast.meta?.params,
+              parentPath,
+              ast.inherit.loc
+            );
+            if (params.size > 0) {
+              const ctx = { params, sourceFile: parentPath };
+              resolvedParent = interpolateAST(parent.ast, ctx);
+              this.logger.debug(`Interpolated ${params.size} parameter(s)`);
+            }
+          } catch (err) {
+            errors.push(new ResolveError(err.message, ast.inherit.loc));
+            return ast;
+          }
+        }
         this.logger.debug(`Merging with parent AST`);
-        return resolveInheritance(parent.ast, ast);
+        return resolveInheritance(resolvedParent, ast);
       }
     } catch (err) {
       if (err instanceof CircularDependencyError) {
@@ -17012,8 +17600,23 @@ var Resolver = class {
         sources.push(...imported.sources);
         errors.push(...imported.errors);
         if (imported.ast) {
+          let resolvedImport = imported.ast;
+          if (imported.ast.meta?.params || use.params) {
+            this.logger.debug(`Binding template parameters for ${importPath}`);
+            try {
+              const params = bindParams(use.params, imported.ast.meta?.params, importPath, use.loc);
+              if (params.size > 0) {
+                const ctx = { params, sourceFile: importPath };
+                resolvedImport = interpolateAST(imported.ast, ctx);
+                this.logger.debug(`Interpolated ${params.size} parameter(s)`);
+              }
+            } catch (err) {
+              errors.push(new ResolveError(err.message, use.loc));
+              continue;
+            }
+          }
           this.logger.debug(`Merging import${use.alias ? ` as "${use.alias}"` : ""}`);
-          result = resolveUses(result, use, imported.ast);
+          result = resolveUses(result, use, resolvedImport);
         }
       } catch (err) {
         if (err instanceof CircularDependencyError) {
@@ -18262,6 +18865,92 @@ var emptyBlock = {
   }
 };
 
+// packages/validator/src/rules/valid-params.ts
+function paramTypeToString2(paramType) {
+  switch (paramType.kind) {
+    case "string":
+      return "string";
+    case "number":
+      return "number";
+    case "boolean":
+      return "boolean";
+    case "enum":
+      return `enum(${paramType.options.map((o) => `"${o}"`).join(", ")})`;
+  }
+}
+function getValueType2(value) {
+  if (value === null) return "null";
+  if (typeof value === "string") return "string";
+  if (typeof value === "number") return "number";
+  if (typeof value === "boolean") return "boolean";
+  if (Array.isArray(value)) return "array";
+  if (typeof value === "object" && "type" in value) {
+    const typed = value;
+    if (typed.type === "TextContent") return "string";
+    if (typed.type === "TemplateExpression") return "template";
+    if (typed.type === "TypeExpression") return "type";
+  }
+  return "object";
+}
+function valueMatchesType(value, paramType) {
+  const actualType = getValueType2(value);
+  switch (paramType.kind) {
+    case "string":
+      return actualType === "string";
+    case "number":
+      return actualType === "number";
+    case "boolean":
+      return actualType === "boolean";
+    case "enum":
+      return actualType === "string" && paramType.options.includes(value);
+  }
+}
+var validParams = {
+  id: "PS009",
+  name: "valid-params",
+  description: "Validate parameter definitions in @meta",
+  defaultSeverity: "error",
+  validate: (ctx) => {
+    const params = ctx.ast.meta?.params;
+    if (!params || params.length === 0) {
+      return;
+    }
+    const seen = /* @__PURE__ */ new Set();
+    for (const param of params) {
+      if (seen.has(param.name)) {
+        ctx.report({
+          message: `Duplicate parameter definition: '${param.name}'`,
+          location: param.loc,
+          suggestion: "Remove the duplicate parameter definition"
+        });
+      }
+      seen.add(param.name);
+    }
+    for (const param of params) {
+      if (param.defaultValue !== void 0) {
+        if (!valueMatchesType(param.defaultValue, param.paramType)) {
+          const expectedType = paramTypeToString2(param.paramType);
+          const actualType = getValueType2(param.defaultValue);
+          ctx.report({
+            message: `Default value for '${param.name}' has wrong type: expected ${expectedType}, got ${actualType}`,
+            location: param.loc,
+            suggestion: `Change the default value to a ${expectedType}`
+          });
+        }
+      }
+    }
+    for (const param of params) {
+      if (param.optional && param.defaultValue === void 0) {
+        ctx.report({
+          message: `Optional parameter '${param.name}' has no default value`,
+          location: param.loc,
+          suggestion: "Consider adding a default value or marking as required"
+        });
+      }
+    }
+  }
+};
+
 // packages/validator/src/rules/index.ts
 var allRules = [
   // Required meta rules (PS001, PS002)
@@ -18278,7 +18967,9 @@ var allRules = [
   // Deprecated features (PS007)
   deprecated,
   // Empty blocks (PS008)
-  emptyBlock
+  emptyBlock,
+  // Valid params (PS009)
+  validParams
 ];
 
 // packages/validator/src/validator.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@promptscript/cli",
-  "version": "1.0.0-alpha.9",
+  "version": "1.0.0-rc.2",
   "description": "CLI for PromptScript - standardize AI instructions across GitHub Copilot, Claude, Cursor and other AI tools",
   "keywords": [
     "cli",