patchwork-os 0.2.0-alpha.9 → 0.2.0-beta.0

package/dist/recipes/manifest.d.ts

@@ -0,0 +1,47 @@
+/**
+ * RecipeManifest — recipe.json format for the Patchwork recipe marketplace.
+ *
+ * Each recipe package directory contains a recipe.json manifest describing
+ * the package metadata, entry-point recipe file, child recipes, required
+ * connectors, and configurable variables.
+ */
+export interface RecipeManifest {
+    name: string;
+    version: string;
+    description: string;
+    author?: string;
+    license?: string;
+    tags?: string[];
+    connectors?: string[];
+    recipes: {
+        main: string;
+        children?: string[];
+    };
+    variables?: Record<string, {
+        description: string;
+        required?: boolean;
+        default?: string;
+    }>;
+    homepage?: string;
+    repository?: string;
+}
+/**
+ * Validate an unknown value as a RecipeManifest.
+ * Throws a descriptive Error if any required field is missing or invalid.
+ */
+export declare function validateManifest(manifest: unknown): RecipeManifest;
+/**
+ * Parse and validate a recipe.json string.
+ * Throws with a clear error message if invalid JSON or schema violations.
+ */
+export declare function parseManifest(json: string): RecipeManifest;
+/**
+ * Load and parse recipe.json from a directory.
+ * Returns null if the file does not exist (not a recipe package dir).
+ * Throws if file exists but is invalid.
+ */
+export declare function loadManifestFromDir(dir: string): RecipeManifest | null;
+/**
+ * Returns all recipe filenames declared in the manifest: [main, ...children].
+ */
+export declare function getManifestRecipeFiles(manifest: RecipeManifest): string[];

package/dist/recipes/manifest.js

@@ -0,0 +1,156 @@
+/**
+ * RecipeManifest — recipe.json format for the Patchwork recipe marketplace.
+ *
+ * Each recipe package directory contains a recipe.json manifest describing
+ * the package metadata, entry-point recipe file, child recipes, required
+ * connectors, and configurable variables.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+const NAME_RE = /^(@[a-z0-9-]+\/)?[a-z0-9][a-z0-9\-_.]*$/;
+const VERSION_RE = /^\d+\.\d+\.\d+/;
+const YAML_EXT_RE = /\.ya?ml$/;
+/**
+ * Recipe filenames in the manifest must be plain basenames, not paths.
+ * Rejects "../escape.yaml", "subdir/foo.yaml", "/etc/passwd.yaml", control
+ * characters, and so on — anything that could resolve outside the install
+ * directory when the consumer does `path.join(installDir, recipes.main)`.
+ */
+function isSafeRecipeBasename(filename) {
+    if (typeof filename !== "string" || filename.length === 0)
+        return false;
+    if (filename === "." || filename === "..")
+        return false;
+    if (filename.includes("/") || filename.includes("\\"))
+        return false;
+    // biome-ignore lint/suspicious/noControlCharactersInRegex: explicit control-char check
+    if (/[\x00-\x1F\x7F]/.test(filename))
+        return false;
+    return YAML_EXT_RE.test(filename);
+}
+/**
+ * Validate an unknown value as a RecipeManifest.
+ * Throws a descriptive Error if any required field is missing or invalid.
+ */
+export function validateManifest(manifest) {
+    if (typeof manifest !== "object" || manifest === null) {
+        throw new Error("recipe.json must be a JSON object");
+    }
+    const m = manifest;
+    // name
+    if (typeof m.name !== "string" || !m.name) {
+        throw new Error('recipe.json: "name" is required and must be a string');
+    }
+    if (!NAME_RE.test(m.name)) {
+        throw new Error(`recipe.json: "name" must match pattern (@scope/)?[a-z0-9][a-z0-9-_.]*  — got "${m.name}"`);
+    }
+    // version
+    if (typeof m.version !== "string" || !m.version) {
+        throw new Error('recipe.json: "version" is required and must be a string');
+    }
+    if (!VERSION_RE.test(m.version)) {
+        throw new Error(`recipe.json: "version" must be valid semver (e.g. "1.0.0") — got "${m.version}"`);
+    }
+    // description
+    if (typeof m.description !== "string" || !m.description) {
+        throw new Error('recipe.json: "description" is required and must be a non-empty string');
+    }
+    // recipes
+    if (typeof m.recipes !== "object" || m.recipes === null) {
+        throw new Error('recipe.json: "recipes" is required and must be an object');
+    }
+    const recipes = m.recipes;
+    if (!isSafeRecipeBasename(recipes.main)) {
+        throw new Error(`recipe.json: "recipes.main" must be a .yaml or .yml basename without path separators or control characters — got "${recipes.main}"`);
+    }
+    if (recipes.children !== undefined) {
+        if (!Array.isArray(recipes.children)) {
+            throw new Error('recipe.json: "recipes.children" must be an array');
+        }
+        for (let i = 0; i < recipes.children.length; i++) {
+            if (!isSafeRecipeBasename(recipes.children[i])) {
+                throw new Error(`recipe.json: "recipes.children[${i}]" must be a .yaml or .yml basename without path separators or control characters — got "${recipes.children[i]}"`);
+            }
+        }
+    }
+    // optional string fields
+    for (const field of [
+        "author",
+        "license",
+        "homepage",
+        "repository",
+    ]) {
+        if (m[field] !== undefined && typeof m[field] !== "string") {
+            throw new Error(`recipe.json: "${field}" must be a string`);
+        }
+    }
+    // optional string[] fields
+    for (const field of ["tags", "connectors"]) {
+        if (m[field] !== undefined) {
+            if (!Array.isArray(m[field])) {
+                throw new Error(`recipe.json: "${field}" must be an array of strings`);
+            }
+            for (let i = 0; i < m[field].length; i++) {
+                if (typeof m[field][i] !== "string") {
+                    throw new Error(`recipe.json: "${field}[${i}]" must be a string`);
+                }
+            }
+        }
+    }
+    // variables
+    if (m.variables !== undefined) {
+        if (typeof m.variables !== "object" || m.variables === null) {
+            throw new Error('recipe.json: "variables" must be an object');
+        }
+        for (const [key, val] of Object.entries(m.variables)) {
+            if (typeof val !== "object" || val === null) {
+                throw new Error(`recipe.json: "variables.${key}" must be an object with a "description" field`);
+            }
+            const v = val;
+            if (typeof v.description !== "string" || !v.description) {
+                throw new Error(`recipe.json: "variables.${key}.description" is required and must be a non-empty string`);
+            }
+            if (v.required !== undefined && typeof v.required !== "boolean") {
+                throw new Error(`recipe.json: "variables.${key}.required" must be a boolean`);
+            }
+            if (v.default !== undefined && typeof v.default !== "string") {
+                throw new Error(`recipe.json: "variables.${key}.default" must be a string`);
+            }
+        }
+    }
+    return m;
+}
+/**
+ * Parse and validate a recipe.json string.
+ * Throws with a clear error message if invalid JSON or schema violations.
+ */
+export function parseManifest(json) {
+    let parsed;
+    try {
+        parsed = JSON.parse(json);
+    }
+    catch (err) {
+        throw new Error(`recipe.json: invalid JSON — ${err instanceof Error ? err.message : String(err)}`);
+    }
+    return validateManifest(parsed);
+}
+/**
+ * Load and parse recipe.json from a directory.
+ * Returns null if the file does not exist (not a recipe package dir).
+ * Throws if file exists but is invalid.
+ */
+export function loadManifestFromDir(dir) {
+    const manifestPath = path.join(dir, "recipe.json");
+    if (!existsSync(manifestPath)) {
+        return null;
+    }
+    const raw = readFileSync(manifestPath, "utf-8");
+    return parseManifest(raw);
+}
+/**
+ * Returns all recipe filenames declared in the manifest: [main, ...children].
+ */
+export function getManifestRecipeFiles(manifest) {
+    return [manifest.recipes.main, ...(manifest.recipes.children ?? [])];
+}
+//# sourceMappingURL=manifest.js.map

package/dist/recipes/manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../../src/recipes/manifest.ts"],"names":[],"mappings":"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"}

package/dist/recipes/migrationWarnings.d.ts

@@ -0,0 +1,12 @@
+export interface PermissionsSidecarWarningResult {
+    count: number;
+    warned: boolean;
+}
+/**
+ * Scans `recipesDir` for legacy permissions sidecar files. Emits a single
+ * `console.warn` if any are found (skipped in test env). Returns the count
+ * for caller observability + tests.
+ */
+export declare function warnAboutLegacyPermissionsSidecars(recipesDir: string, options?: {
+    warn?: (msg: string) => void;
+}): PermissionsSidecarWarningResult;

package/dist/recipes/migrationWarnings.js

@@ -0,0 +1,44 @@
+import { readdirSync } from "node:fs";
+/**
+ * Boot-time scan for legacy `<name>.permissions.json` sidecars left over from
+ * pre-alpha.36 installs. The sidecar files were decorative — never read by
+ * toolRegistry — so they're safe to ignore on disk. Emits a single warning
+ * pointing users at the canonical permission location (~/.claude/settings.json).
+ *
+ * Per recipe-dogfood-2026-05-01/PLAN-MASTER-V2.md A-PR4 §6 (R2 L-2):
+ * - Fires ONCE per boot, not per recipe.
+ * - Skipped under NODE_ENV=test so vitest output stays clean.
+ * - Migration script for users who want to archive:
+ *     find ~/.patchwork/recipes -name '*.permissions.json' \
+ *       -exec mv {} ~/.patchwork/recipes/.permissions-archive/ \;
+ */
+const DOC_URL = "https://github.com/Oolab-labs/patchwork-os/blob/main/docs/dogfood/recipe-dogfood-2026-05-01/PLAN-MASTER-V2.md";
+/**
+ * Scans `recipesDir` for legacy permissions sidecar files. Emits a single
+ * `console.warn` if any are found (skipped in test env). Returns the count
+ * for caller observability + tests.
+ */
+export function warnAboutLegacyPermissionsSidecars(recipesDir, options = {}) {
+    let entries;
+    try {
+        entries = readdirSync(recipesDir);
+    }
+    catch {
+        return { count: 0, warned: false };
+    }
+    const sidecars = entries.filter((f) => f.endsWith(".permissions.json"));
+    const count = sidecars.length;
+    if (count === 0) {
+        return { count: 0, warned: false };
+    }
+    if (process.env.NODE_ENV === "test" && !options.warn) {
+        return { count, warned: false };
+    }
+    const warn = options.warn ?? ((msg) => console.warn(msg));
+    warn(`[patchwork] Found ${count} legacy <name>.permissions.json sidecar file${count === 1 ? "" : "s"} in ${recipesDir}. ` +
+        `These are decorative and no longer generated (alpha.36+). ` +
+        `Configure tool gating in ~/.claude/settings.json. ` +
+        `Migration guide: ${DOC_URL}`);
+    return { count, warned: true };
+}
+//# sourceMappingURL=migrationWarnings.js.map

package/dist/recipes/migrationWarnings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrationWarnings.js","sourceRoot":"","sources":["../../src/recipes/migrationWarnings.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAEtC;;;;;;;;;;;;GAYG;AAEH,MAAM,OAAO,GACX,+GAA+G,CAAC;AAOlH;;;;GAIG;AACH,MAAM,UAAU,kCAAkC,CAChD,UAAkB,EAClB,UAA4C,EAAE;IAE9C,IAAI,OAAiB,CAAC;IACtB,IAAI,CAAC;QACH,OAAO,GAAG,WAAW,CAAC,UAAU,CAAC,CAAC;IACpC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;IACrC,CAAC;IAED,MAAM,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,mBAAmB,CAAC,CAAC,CAAC;IACxE,MAAM,KAAK,GAAG,QAAQ,CAAC,MAAM,CAAC;IAE9B,IAAI,KAAK,KAAK,CAAC,EAAE,CAAC;QAChB,OAAO,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;IACrC,CAAC;IAED,IAAI,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;QACrD,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;IAClC,CAAC;IAED,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,CAAC,CAAC,GAAW,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IAClE,IAAI,CACF,qBAAqB,KAAK,+CACxB,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GACrB,OAAO,UAAU,IAAI;QACnB,4DAA4D;QAC5D,oDAAoD;QACpD,oBAAoB,OAAO,EAAE,CAChC,CAAC;IACF,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;AACjC,CAAC"}

package/dist/recipes/migrations/index.d.ts

@@ -0,0 +1,24 @@
+import type { WarnFn } from "./types.js";
+export type { RecipeMigration, WarnFn } from "./types.js";
+export { v1Migration } from "./v1.js";
+/** apiVersion produced by the most recent migration. */
+export declare const CURRENT_API_VERSION = "patchwork.sh/v1";
+export interface MigrationResult {
+    /** Migrated recipe object. Same reference if no migrations applied. */
+    recipe: unknown;
+    /** Sequence of "<from> -> <to>" strings describing applied migrations. */
+    applied: string[];
+}
+/**
+ * Migrate a recipe object up to `CURRENT_API_VERSION`.
+ *
+ * Behavior:
+ * - Non-record inputs are returned as-is with no migrations applied.
+ * - Each iteration looks for a registered migration whose `from`
+ *   matches the current `apiVersion` and applies it.
+ * - The loop stops when the recipe declares `CURRENT_API_VERSION`,
+ *   when no matching migration exists for an unversioned recipe (no-op),
+ *   or when the recipe declares an unknown future apiVersion (passed
+ *   through unchanged so downstream schema lint can flag it).
+ */
+export declare function migrateRecipeToCurrent(recipe: unknown, warn?: WarnFn): MigrationResult;

package/dist/recipes/migrations/index.js

@@ -0,0 +1,55 @@
+import { v1Migration } from "./v1.js";
+export { v1Migration } from "./v1.js";
+/** apiVersion produced by the most recent migration. */
+export const CURRENT_API_VERSION = "patchwork.sh/v1";
+/**
+ * Ordered list of available migrations. Each step's `to` is consumed
+ * by the next step's `from` (or matches `CURRENT_API_VERSION`).
+ */
+const REGISTRY = [v1Migration];
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function readApiVersion(recipe) {
+    return typeof recipe.apiVersion === "string" ? recipe.apiVersion : null;
+}
+/**
+ * Migrate a recipe object up to `CURRENT_API_VERSION`.
+ *
+ * Behavior:
+ * - Non-record inputs are returned as-is with no migrations applied.
+ * - Each iteration looks for a registered migration whose `from`
+ *   matches the current `apiVersion` and applies it.
+ * - The loop stops when the recipe declares `CURRENT_API_VERSION`,
+ *   when no matching migration exists for an unversioned recipe (no-op),
+ *   or when the recipe declares an unknown future apiVersion (passed
+ *   through unchanged so downstream schema lint can flag it).
+ */
+export function migrateRecipeToCurrent(recipe, warn) {
+    if (!isRecord(recipe)) {
+        return { recipe, applied: [] };
+    }
+    let current = { ...recipe };
+    const applied = [];
+    // Bound the loop defensively so a malformed registry can never
+    // produce an infinite cycle.
+    const maxIterations = REGISTRY.length + 1;
+    for (let i = 0; i < maxIterations; i++) {
+        const version = readApiVersion(current);
+        if (version === CURRENT_API_VERSION) {
+            break;
+        }
+        const migration = REGISTRY.find((m) => m.from === version);
+        if (!migration) {
+            // Unknown future/unsupported apiVersion: leave the recipe alone
+            // and let schema lint surface the enum mismatch with a clear
+            // message instead of throwing here.
+            break;
+        }
+        const next = migration.migrate(current, warn);
+        current = isRecord(next) ? next : current;
+        applied.push(`${migration.from ?? "(unversioned)"} -> ${migration.to}`);
+    }
+    return { recipe: current, applied };
+}
+//# sourceMappingURL=index.js.map

package/dist/recipes/migrations/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/recipes/migrations/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAGtC,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAEtC,wDAAwD;AACxD,MAAM,CAAC,MAAM,mBAAmB,GAAG,iBAAiB,CAAC;AAErD;;;GAGG;AACH,MAAM,QAAQ,GAAmC,CAAC,WAAW,CAAC,CAAC;AAS/D,SAAS,QAAQ,CAAC,KAAc;IAC9B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC;AAED,SAAS,cAAc,CAAC,MAA+B;IACrD,OAAO,OAAO,MAAM,CAAC,UAAU,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC;AAC1E,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,sBAAsB,CACpC,MAAe,EACf,IAAa;IAEb,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;QACtB,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;IACjC,CAAC;IAED,IAAI,OAAO,GAA4B,EAAE,GAAG,MAAM,EAAE,CAAC;IACrD,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,+DAA+D;IAC/D,6BAA6B;IAC7B,MAAM,aAAa,GAAG,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC;IAE1C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,aAAa,EAAE,CAAC,EAAE,EAAE,CAAC;QACvC,MAAM,OAAO,GAAG,cAAc,CAAC,OAAO,CAAC,CAAC;QACxC,IAAI,OAAO,KAAK,mBAAmB,EAAE,CAAC;YACpC,MAAM;QACR,CAAC;QAED,MAAM,SAAS,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,OAAO,CAAC,CAAC;QAC3D,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,gEAAgE;YAChE,6DAA6D;YAC7D,oCAAoC;YACpC,MAAM;QACR,CAAC;QAED,MAAM,IAAI,GAAG,SAAS,CAAC,OAAO,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;QAC9C,OAAO,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC;QAC1C,OAAO,CAAC,IAAI,CAAC,GAAG,SAAS,CAAC,IAAI,IAAI,eAAe,OAAO,SAAS,CAAC,EAAE,EAAE,CAAC,CAAC;IAC1E,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;AACtC,CAAC"}

package/dist/recipes/migrations/types.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Recipe apiVersion migration layer.
+ *
+ * A `RecipeMigration` upgrades a recipe object from one declared
+ * `apiVersion` to the next. Migrations are chained by the registry in
+ * `./index.ts` until the recipe carries the current apiVersion or no
+ * matching migration exists.
+ *
+ * Field-level legacy compatibility (e.g. `output -> into`,
+ * `params` flattening, `trigger.schedule -> trigger.at`) lives in
+ * `../legacyRecipeCompat.ts` and runs alongside this layer; migrations
+ * here are reserved for changes that are explicitly version-bumped.
+ */
+export type WarnFn = (msg: string) => void;
+export interface RecipeMigration {
+    /**
+     * apiVersion this migration consumes. `null` means "no apiVersion
+     * field present" (i.e. an unversioned legacy recipe).
+     */
+    from: string | null;
+    /** apiVersion this migration produces. */
+    to: string;
+    /**
+     * Migrate a shallow-cloned record. Implementations should return a
+     * new object rather than mutating the input.
+     */
+    migrate: (recipe: Record<string, unknown>, warn?: WarnFn) => Record<string, unknown>;
+}

package/dist/recipes/migrations/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/recipes/migrations/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/recipes/migrations/types.ts"],"names":[],"mappings":""}

package/dist/recipes/migrations/v1.d.ts

@@ -0,0 +1,11 @@
+import type { RecipeMigration } from "./types.js";
+/**
+ * Migrate an unversioned (no `apiVersion`) recipe to `patchwork.sh/v1`.
+ *
+ * The shape changes that distinguished pre-v1 from v1 (e.g. flat
+ * `agent: true`, `params`, `output`, `trigger.schedule`) are still
+ * accepted at runtime and lint via `../legacyRecipeCompat.ts`. This
+ * migration's job is the explicit version stamp plus a single
+ * deprecation warning telling authors to add `apiVersion` themselves.
+ */
+export declare const v1Migration: RecipeMigration;

package/dist/recipes/migrations/v1.js

@@ -0,0 +1,18 @@
+/**
+ * Migrate an unversioned (no `apiVersion`) recipe to `patchwork.sh/v1`.
+ *
+ * The shape changes that distinguished pre-v1 from v1 (e.g. flat
+ * `agent: true`, `params`, `output`, `trigger.schedule`) are still
+ * accepted at runtime and lint via `../legacyRecipeCompat.ts`. This
+ * migration's job is the explicit version stamp plus a single
+ * deprecation warning telling authors to add `apiVersion` themselves.
+ */
+export const v1Migration = {
+    from: null,
+    to: "patchwork.sh/v1",
+    migrate(recipe, warn) {
+        warn?.("Recipe missing 'apiVersion' — implicitly migrated to 'patchwork.sh/v1'. Add `apiVersion: patchwork.sh/v1` to silence this warning (will be required in a future major version).");
+        return { apiVersion: "patchwork.sh/v1", ...recipe };
+    },
+};
+//# sourceMappingURL=v1.js.map

package/dist/recipes/migrations/v1.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"v1.js","sourceRoot":"","sources":["../../../src/recipes/migrations/v1.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,WAAW,GAAoB;IAC1C,IAAI,EAAE,IAAI;IACV,EAAE,EAAE,iBAAiB;IACrB,OAAO,CAAC,MAA+B,EAAE,IAA4B;QACnE,IAAI,EAAE,CACJ,iLAAiL,CAClL,CAAC;QACF,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,GAAG,MAAM,EAAE,CAAC;IACtD,CAAC;CACF,CAAC"}

package/dist/recipes/names.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Canonical name + variable-name rules for recipes.
+ *
+ * Single source of truth used by:
+ *   - `src/recipesHttp.ts`        — file-system + HTTP route validation
+ *   - `src/recipes/validation.ts` — `validateRecipeDefinition` lint
+ *   - `dashboard/src/app/recipes/new/page.tsx` — form-side mirroring
+ *     (the dashboard package re-declares them, kept in sync by hand)
+ *   - `schemas/recipe.v1.json`    — IDE-time JSON-Schema validation
+ *
+ * Lives in its own module to avoid the circular import that arises if
+ * the constants live in `recipesHttp.ts` (which imports
+ * `validateRecipeDefinition` from `validation.ts`, which would then
+ * import the constants back).
+ */
+/**
+ * Canonical recipe-name regex. kebab-case, 1–64 chars, must start with
+ * a letter or digit. Survey of all 22 production recipes in
+ * `~/.patchwork/recipes/` confirmed none use underscore filenames; this
+ * matches the JSON Schema `pattern` and the previous strict server
+ * regex (which disagreed with the schema by also allowing `_`).
+ */
+export declare const RECIPE_NAME_RE: RegExp;
+/**
+ * Canonical variable-name regex (for `trigger.vars[].name` and
+ * `trigger.inputs[].name`). Mirrors the runtime template-reference
+ * regex root group in `validation.ts:extractTemplateDottedPaths`,
+ * minus `-` (hyphens in var names parse oddly in template expressions).
+ * Permits both SCREAMING_SNAKE and lowercase_snake conventions seen in
+ * production recipes.
+ */
+export declare const RECIPE_VAR_NAME_RE: RegExp;
+/**
+ * Built-in context keys reserved by the runtime. Declaring a `vars` or
+ * `inputs` entry with any of these names would shadow trigger-emitted
+ * data silently. The simple-identifier subset of
+ * `registerRecipeContextKeys` + `extractTemplateExpressions builtinKeys`
+ * (see `src/recipes/validation.ts`).
+ */
+export declare const RESERVED_VAR_NAMES: ReadonlySet<string>;

package/dist/recipes/names.js

@@ -0,0 +1,66 @@
+/**
+ * Canonical name + variable-name rules for recipes.
+ *
+ * Single source of truth used by:
+ *   - `src/recipesHttp.ts`        — file-system + HTTP route validation
+ *   - `src/recipes/validation.ts` — `validateRecipeDefinition` lint
+ *   - `dashboard/src/app/recipes/new/page.tsx` — form-side mirroring
+ *     (the dashboard package re-declares them, kept in sync by hand)
+ *   - `schemas/recipe.v1.json`    — IDE-time JSON-Schema validation
+ *
+ * Lives in its own module to avoid the circular import that arises if
+ * the constants live in `recipesHttp.ts` (which imports
+ * `validateRecipeDefinition` from `validation.ts`, which would then
+ * import the constants back).
+ */
+/**
+ * Canonical recipe-name regex. kebab-case, 1–64 chars, must start with
+ * a letter or digit. Survey of all 22 production recipes in
+ * `~/.patchwork/recipes/` confirmed none use underscore filenames; this
+ * matches the JSON Schema `pattern` and the previous strict server
+ * regex (which disagreed with the schema by also allowing `_`).
+ */
+export const RECIPE_NAME_RE = /^[a-z0-9][a-z0-9-]{0,63}$/;
+/**
+ * Canonical variable-name regex (for `trigger.vars[].name` and
+ * `trigger.inputs[].name`). Mirrors the runtime template-reference
+ * regex root group in `validation.ts:extractTemplateDottedPaths`,
+ * minus `-` (hyphens in var names parse oddly in template expressions).
+ * Permits both SCREAMING_SNAKE and lowercase_snake conventions seen in
+ * production recipes.
+ */
+export const RECIPE_VAR_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]{0,63}$/;
+/**
+ * Built-in context keys reserved by the runtime. Declaring a `vars` or
+ * `inputs` entry with any of these names would shadow trigger-emitted
+ * data silently. The simple-identifier subset of
+ * `registerRecipeContextKeys` + `extractTemplateExpressions builtinKeys`
+ * (see `src/recipes/validation.ts`).
+ */
+export const RESERVED_VAR_NAMES = new Set([
+    "date",
+    "time",
+    "YYYY",
+    "ISO_NOW",
+    "HH",
+    "MM",
+    "SS",
+    "this",
+    "hash",
+    "message",
+    "branch",
+    "payload",
+    "webhook_payload",
+    "hook_path",
+    "webhook_path",
+    "file",
+    "file_ext",
+    "file_basename",
+    "runner",
+    "failed",
+    "passed",
+    "total",
+    "failures",
+    "event",
+]);
+//# sourceMappingURL=names.js.map

package/dist/recipes/names.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"names.js","sourceRoot":"","sources":["../../src/recipes/names.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,2BAA2B,CAAC;AAE1D;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,+BAA+B,CAAC;AAElE;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAwB,IAAI,GAAG,CAAC;IAC7D,MAAM;IACN,MAAM;IACN,MAAM;IACN,SAAS;IACT,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,MAAM;IACN,MAAM;IACN,SAAS;IACT,QAAQ;IACR,SAAS;IACT,iBAAiB;IACjB,WAAW;IACX,cAAc;IACd,MAAM;IACN,UAAU;IACV,eAAe;IACf,QAAQ;IACR,QAAQ;IACR,QAAQ;IACR,OAAO;IACP,UAAU;IACV,OAAO;CACR,CAAC,CAAC"}

package/dist/recipes/nestedRecipeStep.d.ts

@@ -0,0 +1,58 @@
+/**
+ * NestedRecipeStep — handler for calling recipes from within recipes.
+ *
+ * Supports:
+ *   - Variable passing via template resolution
+ *   - Isolated OutputRegistry for child
+ *   - Risk escalation (child risk > parent risk uses child's)
+ *   - Depth limiting (prevent infinite recursion)
+ */
+import type { OutputRegistry } from "./outputRegistry.js";
+import type { TemplateContext, TemplateError } from "./templateEngine.js";
+export interface NestedRecipeConfig {
+    recipe: string;
+    vars: Record<string, string>;
+    output?: string;
+    risk?: "low" | "medium" | "high";
+    id: string;
+}
+export interface NestedRecipeContext {
+    parentRegistry: OutputRegistry;
+    parentEnv: Record<string, string | undefined>;
+    recipeMaxDepth: number;
+    currentDepth: number;
+    dryRun: boolean;
+}
+export interface NestedRecipeResult {
+    success: boolean;
+    data?: unknown;
+    error?: string;
+    childOutputs?: Record<string, unknown>;
+}
+export interface RecipeLoader {
+    loadRecipe(name: string): Promise<{
+        steps: unknown[];
+    } | null>;
+}
+/** Resolve template variables against parent context */
+export declare function resolveNestedVars(vars: Record<string, string>, context: TemplateContext): {
+    resolved: Record<string, string>;
+    errors: TemplateError[];
+};
+/** Validate nested recipe call before execution */
+export declare function validateNestedRecipe(config: NestedRecipeConfig, context: NestedRecipeContext): {
+    valid: boolean;
+    error?: string;
+};
+/** Calculate effective risk tier */
+export declare function calculateNestedRisk(parentRisk: "low" | "medium" | "high" | undefined, childRisk: "low" | "medium" | "high" | undefined): "low" | "medium" | "high";
+/** Format nested recipe result for parent registry */
+export declare function formatNestedOutput(result: NestedRecipeResult, config: NestedRecipeConfig): {
+    stepId: string;
+    output: {
+        status: "success" | "error" | "skipped";
+        data: unknown;
+    };
+};
+/** Mock nested recipe execution for dry-run mode */
+export declare function mockNestedRecipe(config: NestedRecipeConfig, context: NestedRecipeContext): Promise<NestedRecipeResult>;