@introspection-ai/pi-recipes 0.1.0-beta.0

package/dist/recipe-agent.d.ts

@@ -0,0 +1,51 @@
+export interface RecipeSystemInstructions {
+    mode: "append" | "replace";
+    content: string;
+}
+export interface RecipeAgentExtensions {
+    include?: string[];
+    exclude?: string[];
+}
+export interface RecipeAgentDefinition {
+    name: string;
+    from?: string;
+    description?: string;
+    model?: {
+        name?: string;
+        thinkingLevel?: string;
+    };
+    tools: string[];
+    skills: string[];
+    subagents: string[];
+    subagentsDeclared?: boolean;
+    extensions?: RecipeAgentExtensions;
+    systemInstructions?: RecipeSystemInstructions;
+}
+export type RequiredResolvedRecipeAgentField = "model.name" | "model.thinkingLevel" | "tools" | "skills" | "subagents" | "systemInstructions";
+export declare const REQUIRED_RECIPE_AGENT_FIELDS: RequiredResolvedRecipeAgentField[];
+export interface RecipeAgentValidationFinding {
+    agentName: string;
+    field: "name" | "from" | RequiredResolvedRecipeAgentField;
+    message: string;
+}
+export declare function loadRecipeAgentDefinitions(recipeDir: string): Map<string, RecipeAgentDefinition>;
+export declare function validateResolvedRecipeAgentDefinition(opts: {
+    recipeDir: string;
+    agentName: string;
+    requireExplicitName?: boolean;
+    requiredFields?: RequiredResolvedRecipeAgentField[];
+}): RecipeAgentValidationFinding[];
+export declare function validateRecipeAgentDefinitions(recipeDir: string): RecipeAgentValidationFinding[];
+export declare function resolveRecipeAgentName(opts: {
+    recipeDir: string;
+    agentName?: string;
+}): string;
+export declare function resolveRecipeAgentDefinition(opts: {
+    recipeDir: string;
+    agentName?: string;
+}): {
+    agentName: string;
+    agent: RecipeAgentDefinition | null;
+};
+export declare function loadRecipeSystemPrompt(recipeDir: string): string | undefined;
+//# sourceMappingURL=recipe-agent.d.ts.map

package/dist/recipe-agent.js

@@ -0,0 +1,359 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { basename, join } from "node:path";
+import { parse } from "yaml";
+import { packageResourcePaths, readPiPackageManifest, RecipePackageError, } from "./recipe-package.js";
+export const REQUIRED_RECIPE_AGENT_FIELDS = [
+    "model.name",
+    "model.thinkingLevel",
+    "tools",
+    "skills",
+    "subagents",
+    "systemInstructions",
+];
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : {};
+}
+function stringArray(value) {
+    return Array.isArray(value)
+        ? value.filter((item) => typeof item === "string")
+        : [];
+}
+function parseModel(data) {
+    const raw = asRecord(data.model);
+    const name = typeof raw.name === "string" ? raw.name.trim() : "";
+    const thinkingLevel = typeof raw.thinking_level === "string"
+        ? raw.thinking_level.trim()
+        : typeof raw.thinkingLevel === "string"
+            ? raw.thinkingLevel.trim()
+            : "";
+    if (!name && !thinkingLevel)
+        return undefined;
+    return {
+        ...(name ? { name } : {}),
+        ...(thinkingLevel ? { thinkingLevel } : {}),
+    };
+}
+function parseSystemInstructions(data) {
+    const raw = asRecord(data.system_instructions ?? data.systemInstructions);
+    const content = typeof raw.content === "string" ? raw.content.trim() : "";
+    if (!content) {
+        const prompt = typeof data.prompt === "string" ? data.prompt.trim() : "";
+        return prompt ? { mode: "append", content: prompt } : undefined;
+    }
+    const mode = raw.mode === "replace" ? "replace" : "append";
+    return { mode, content };
+}
+function parseExtensions(data) {
+    const raw = asRecord(data.extensions);
+    const extensions = {};
+    if (Object.hasOwn(raw, "include"))
+        extensions.include = stringArray(raw.include);
+    if (Object.hasOwn(raw, "exclude"))
+        extensions.exclude = stringArray(raw.exclude);
+    return extensions.include || extensions.exclude ? extensions : undefined;
+}
+function readYaml(path) {
+    return asRecord(parse(readFileSync(path, "utf8")));
+}
+function recipeManifest(recipeDir) {
+    try {
+        return readPiPackageManifest(recipeDir);
+    }
+    catch (err) {
+        if (err instanceof RecipePackageError)
+            return null;
+        throw err;
+    }
+}
+function yamlFilesFromPaths(paths) {
+    const files = [];
+    for (const path of paths) {
+        if (!existsSync(path))
+            continue;
+        const stats = statSync(path);
+        if (stats.isFile() && /\.ya?ml$/i.test(path)) {
+            files.push(path);
+            continue;
+        }
+        if (!stats.isDirectory())
+            continue;
+        for (const entry of readdirSync(path, { withFileTypes: true })) {
+            if (!entry.isFile() || !/\.ya?ml$/i.test(entry.name))
+                continue;
+            files.push(join(path, entry.name));
+        }
+    }
+    return files.sort();
+}
+function recipeAgentFiles(recipeDir) {
+    const manifest = recipeManifest(recipeDir);
+    if (manifest)
+        return yamlFilesFromPaths(packageResourcePaths(manifest, "agents"));
+    return yamlFilesFromPaths([join(recipeDir, "agents")]);
+}
+function readRecipeAgentSources(recipeDir) {
+    const sources = [];
+    for (const path of recipeAgentFiles(recipeDir)) {
+        const data = readYaml(path);
+        const fallbackName = basename(path).replace(/\.ya?ml$/i, "");
+        const explicitName = typeof data.name === "string" && Boolean(data.name.trim());
+        const name = explicitName ? data.name.trim() : fallbackName;
+        sources.push({
+            fallbackName,
+            explicitName,
+            definition: {
+                name,
+                from: typeof data.from === "string" && data.from.trim() ? data.from.trim() : undefined,
+                description: typeof data.description === "string" ? data.description : undefined,
+                model: parseModel(data),
+                tools: Object.hasOwn(data, "tools") ? stringArray(data.tools) : undefined,
+                skills: Object.hasOwn(data, "skills") ? stringArray(data.skills) : undefined,
+                subagents: Object.hasOwn(data, "subagents") ? stringArray(data.subagents) : undefined,
+                extensions: parseExtensions(data),
+                systemInstructions: parseSystemInstructions(data),
+            },
+        });
+    }
+    return sources;
+}
+export function loadRecipeAgentDefinitions(recipeDir) {
+    const rawDefinitions = new Map();
+    const aliases = new Map();
+    const resolvedDefinitions = new Map();
+    const definitions = new Map();
+    for (const source of readRecipeAgentSources(recipeDir)) {
+        rawDefinitions.set(source.definition.name, source.definition);
+        aliases.set(source.fallbackName, source.definition.name);
+    }
+    function resolveName(name) {
+        return rawDefinitions.has(name) ? name : aliases.get(name) ?? name;
+    }
+    function mergeModel(base, child) {
+        return base || child ? { ...base, ...child } : undefined;
+    }
+    function mergeExtensions(base, child) {
+        if (!base)
+            return child;
+        if (!child)
+            return base;
+        return {
+            ...(base.include ? { include: base.include } : {}),
+            ...(base.exclude ? { exclude: base.exclude } : {}),
+            ...(child.include ? { include: child.include } : {}),
+            ...(child.exclude ? { exclude: child.exclude } : {}),
+        };
+    }
+    function resolveDefinition(name, stack = []) {
+        const resolvedName = resolveName(name);
+        if (resolvedDefinitions.has(resolvedName))
+            return resolvedDefinitions.get(resolvedName);
+        if (stack.includes(resolvedName))
+            return undefined;
+        const raw = rawDefinitions.get(resolvedName);
+        if (!raw)
+            return undefined;
+        const base = raw.from
+            ? resolveDefinition(raw.from, [...stack, resolvedName])
+            : undefined;
+        if (raw.from && !base)
+            return undefined;
+        const definition = {
+            name: raw.name,
+            ...(raw.from ? { from: raw.from } : {}),
+            description: raw.description ?? base?.description,
+            model: mergeModel(base?.model, raw.model),
+            tools: raw.tools ?? base?.tools ?? [],
+            skills: raw.skills ?? base?.skills ?? [],
+            subagents: raw.subagents ?? base?.subagents ?? [],
+            subagentsDeclared: raw.subagents !== undefined || base?.subagentsDeclared === true,
+            extensions: mergeExtensions(base?.extensions, raw.extensions),
+            systemInstructions: raw.systemInstructions ?? base?.systemInstructions,
+        };
+        resolvedDefinitions.set(resolvedName, definition);
+        return definition;
+    }
+    for (const name of rawDefinitions.keys()) {
+        const definition = resolveDefinition(name);
+        if (!definition)
+            continue;
+        definitions.set(name, definition);
+    }
+    for (const [alias, name] of aliases) {
+        if (definitions.has(alias))
+            continue;
+        const definition = definitions.get(name);
+        if (definition)
+            definitions.set(alias, definition);
+    }
+    return definitions;
+}
+function recipeAgentFieldProvided(definition, field) {
+    if (field === "model.name")
+        return Boolean(definition.model?.name);
+    if (field === "model.thinkingLevel")
+        return Boolean(definition.model?.thinkingLevel);
+    if (field === "tools")
+        return definition.tools !== undefined;
+    if (field === "skills")
+        return definition.skills !== undefined;
+    if (field === "subagents")
+        return definition.subagents !== undefined;
+    return definition.systemInstructions !== undefined;
+}
+export function validateResolvedRecipeAgentDefinition(opts) {
+    const rawDefinitions = new Map();
+    const aliases = new Map();
+    const explicitNames = new Map();
+    for (const source of readRecipeAgentSources(opts.recipeDir)) {
+        rawDefinitions.set(source.definition.name, source.definition);
+        aliases.set(source.fallbackName, source.definition.name);
+        explicitNames.set(source.definition.name, source.explicitName);
+    }
+    function resolveName(name) {
+        return rawDefinitions.has(name) ? name : aliases.get(name) ?? name;
+    }
+    function inheritanceFinding(name, stack = []) {
+        const resolvedName = resolveName(name);
+        const definition = rawDefinitions.get(resolvedName);
+        if (!definition) {
+            return {
+                agentName: resolvedName,
+                field: "from",
+                message: `Recipe agent "${resolvedName}" was not found`,
+            };
+        }
+        if (!definition.from)
+            return undefined;
+        const resolvedFrom = resolveName(definition.from);
+        if (stack.includes(resolvedFrom)) {
+            return {
+                agentName: resolvedName,
+                field: "from",
+                message: `Recipe agent "${resolvedName}" has cyclic from chain: ${[
+                    ...stack,
+                    resolvedName,
+                    resolvedFrom,
+                ].join(" -> ")}`,
+            };
+        }
+        if (!rawDefinitions.has(resolvedFrom)) {
+            return {
+                agentName: resolvedName,
+                field: "from",
+                message: `Recipe agent "${resolvedName}" inherits from missing agent "${definition.from}"`,
+            };
+        }
+        return inheritanceFinding(definition.from, [...stack, resolvedName]);
+    }
+    function resolvedFieldProvided(name, field, stack = []) {
+        const resolvedName = resolveName(name);
+        if (stack.includes(resolvedName))
+            return false;
+        const definition = rawDefinitions.get(resolvedName);
+        if (!definition)
+            return false;
+        if (recipeAgentFieldProvided(definition, field))
+            return true;
+        return definition.from
+            ? resolvedFieldProvided(definition.from, field, [...stack, resolvedName])
+            : false;
+    }
+    const agentName = resolveName(opts.agentName);
+    const findings = [];
+    if (opts.requireExplicitName && explicitNames.get(agentName) !== true) {
+        findings.push({
+            agentName,
+            field: "name",
+            message: `Recipe agent "${agentName}" must declare name`,
+        });
+    }
+    const inheritance = inheritanceFinding(agentName);
+    if (inheritance)
+        findings.push(inheritance);
+    for (const field of opts.requiredFields ?? []) {
+        if (resolvedFieldProvided(agentName, field))
+            continue;
+        findings.push({
+            agentName,
+            field,
+            message: `Recipe agent "${agentName}" must declare ${field} directly or inherit it with from`,
+        });
+    }
+    return findings;
+}
+function validateRecipeAgentNames(sources) {
+    const findings = [];
+    const explicitNameCounts = new Map();
+    const explicitNames = new Set();
+    for (const source of sources) {
+        if (!source.explicitName)
+            continue;
+        explicitNames.add(source.definition.name);
+        explicitNameCounts.set(source.definition.name, (explicitNameCounts.get(source.definition.name) ?? 0) + 1);
+    }
+    for (const [name, count] of explicitNameCounts) {
+        if (count <= 1)
+            continue;
+        findings.push({
+            agentName: name,
+            field: "name",
+            message: `Recipe agent name "${name}" is declared by multiple files`,
+        });
+    }
+    for (const source of sources) {
+        if (source.fallbackName === source.definition.name ||
+            !explicitNames.has(source.fallbackName)) {
+            continue;
+        }
+        findings.push({
+            agentName: source.definition.name,
+            field: "name",
+            message: `Recipe agent file alias "${source.fallbackName}" conflicts with an explicit agent name`,
+        });
+    }
+    return findings;
+}
+export function validateRecipeAgentDefinitions(recipeDir) {
+    const sources = readRecipeAgentSources(recipeDir);
+    const agentNames = [...new Set(sources.map((source) => source.definition.name))].sort();
+    return [
+        ...validateRecipeAgentNames(sources),
+        ...agentNames.flatMap((agentName) => validateResolvedRecipeAgentDefinition({
+            recipeDir,
+            agentName,
+            requireExplicitName: true,
+            requiredFields: REQUIRED_RECIPE_AGENT_FIELDS,
+        })),
+    ];
+}
+export function resolveRecipeAgentName(opts) {
+    if (opts.agentName?.trim())
+        return opts.agentName.trim();
+    const definitions = loadRecipeAgentDefinitions(opts.recipeDir);
+    const defaultAgent = definitions.get("agent");
+    if (defaultAgent)
+        return defaultAgent.name;
+    const uniqueNames = [
+        ...new Set([...definitions.values()].map((definition) => definition.name)),
+    ];
+    if (uniqueNames.length === 1)
+        return uniqueNames[0];
+    if (uniqueNames.length === 0)
+        return "agent";
+    throw new Error("Recipe has multiple agents and no default entrypoint; add agents/agent.yaml or set PI_AGENT_NAME");
+}
+export function resolveRecipeAgentDefinition(opts) {
+    const agentName = resolveRecipeAgentName(opts);
+    const agent = loadRecipeAgentDefinitions(opts.recipeDir).get(agentName) ?? null;
+    return { agentName, agent };
+}
+export function loadRecipeSystemPrompt(recipeDir) {
+    const path = join(recipeDir, "SYSTEM.md");
+    if (!existsSync(path))
+        return undefined;
+    const content = readFileSync(path, "utf8").trim();
+    return content || undefined;
+}
+//# sourceMappingURL=recipe-agent.js.map

package/dist/recipe-dev.d.ts

@@ -0,0 +1,30 @@
+import { type RecipePackageManifest, type RecipePackageResources, type RecipeValidationFinding } from "./recipe-package.js";
+export interface RecipeScaffoldFile {
+    path: string;
+    action: "created" | "overwritten" | "existing";
+}
+export interface RecipeScaffoldResult {
+    recipeDir: string;
+    name: string;
+    files: RecipeScaffoldFile[];
+}
+export interface RecipeDevelopmentReport {
+    valid: boolean;
+    manifest: RecipePackageManifest;
+    findings: RecipeValidationFinding[];
+    resources: Partial<Record<keyof RecipePackageResources, string[]>>;
+}
+export interface RecipePublishGuide {
+    manifest: RecipePackageManifest;
+    report: RecipeDevelopmentReport;
+    sourceExamples: string[];
+    checklist: string[];
+}
+export declare function createRecipeScaffold(target: string, opts?: {
+    cwd?: string;
+    name?: string;
+    force?: boolean;
+}): RecipeScaffoldResult;
+export declare function validateRecipeDirectory(recipeDir: string): RecipeDevelopmentReport;
+export declare function createRecipePublishGuide(recipeDir: string): RecipePublishGuide;
+//# sourceMappingURL=recipe-dev.d.ts.map

package/dist/recipe-dev.js

@@ -0,0 +1,180 @@
+import { existsSync, mkdirSync, statSync, writeFileSync, } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { loadRecipeAgentDefinitions, resolveRecipeAgentDefinition, validateRecipeAgentDefinitions, } from "./recipe-agent.js";
+import { packageResourcePaths, readPiPackageManifest, validatePiPackageManifest, } from "./recipe-package.js";
+const RESOURCE_KEYS = [
+    "agents",
+    "extensions",
+    "skills",
+    "prompts",
+    "themes",
+];
+function recipeNameFromTarget(target) {
+    const name = basename(resolve(target)).replace(/[^a-zA-Z0-9._-]+/g, "-");
+    return name && name !== "." && name !== ".." ? name : "my-recipe";
+}
+function finding(severity, code, message, packageName) {
+    return {
+        severity,
+        code,
+        message,
+        packageName,
+    };
+}
+function writeScaffoldFile(path, content, opts) {
+    const exists = existsSync(path);
+    if (exists && !opts.force)
+        return { path, action: "existing" };
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, content);
+    return { path, action: exists ? "overwritten" : "created" };
+}
+function assertScaffoldTargetWritable(files, opts) {
+    if (opts.force)
+        return;
+    const existing = files.filter((path) => existsSync(path));
+    if (existing.length === 0)
+        return;
+    throw new Error([
+        "Recipe scaffold would overwrite existing files:",
+        ...existing.map((path) => `  - ${path}`),
+        "Re-run with --force to overwrite them.",
+    ].join("\n"));
+}
+export function createRecipeScaffold(target, opts = {}) {
+    const cwd = opts.cwd ?? process.cwd();
+    const recipeDir = resolve(cwd, target);
+    const name = (opts.name?.trim() || recipeNameFromTarget(recipeDir)).replace(/[^a-zA-Z0-9._-]+/g, "-");
+    const files = [
+        join(recipeDir, "package.json"),
+        join(recipeDir, "SYSTEM.md"),
+        join(recipeDir, "agents", "agent.yaml"),
+        join(recipeDir, "README.md"),
+    ];
+    if (existsSync(recipeDir) && !statSync(recipeDir).isDirectory()) {
+        throw new Error(`Recipe target exists and is not a directory: ${recipeDir}`);
+    }
+    assertScaffoldTargetWritable(files, opts);
+    mkdirSync(join(recipeDir, "agents"), { recursive: true });
+    const written = [
+        writeScaffoldFile(files[0], `${JSON.stringify({
+            name,
+            version: "0.1.0",
+            description: "Describe what this recipe helps users do.",
+            type: "module",
+            pi: {
+                agents: ["agents/*.yaml"],
+            },
+        }, null, 2)}\n`, opts),
+        writeScaffoldFile(files[1], [
+            "# Recipe Workflow",
+            "",
+            "Describe the durable workflow guidance this recipe should add to the session.",
+            "",
+        ].join("\n"), opts),
+        writeScaffoldFile(files[2], [
+            "name: agent",
+            "description: Main recipe agent.",
+            "model:",
+            "  name: openai/gpt-5.4",
+            "  thinking_level: medium",
+            "tools:",
+            "  - read",
+            "  - bash",
+            "skills: []",
+            "subagents: []",
+            "system_instructions:",
+            "  mode: append",
+            "  content: |",
+            "    Follow the recipe workflow.",
+            "",
+        ].join("\n"), opts),
+        writeScaffoldFile(files[3], [
+            `# ${name}`,
+            "",
+            "## Develop",
+            "",
+            "```bash",
+            "recipes doctor .",
+            "recipes install .",
+            `pi --recipe ${name}`,
+            "```",
+            "",
+            "## Publish",
+            "",
+            "Commit this directory to Git and share the repository locator:",
+            "",
+            "```bash",
+            `recipes install github:owner/${name}`,
+            "```",
+            "",
+        ].join("\n"), opts),
+    ];
+    return { recipeDir, name, files: written };
+}
+export function validateRecipeDirectory(recipeDir) {
+    const manifest = readPiPackageManifest(recipeDir);
+    const baseReport = validatePiPackageManifest(manifest);
+    const findings = [...baseReport.findings];
+    const resources = {};
+    for (const key of RESOURCE_KEYS) {
+        try {
+            resources[key] = packageResourcePaths(manifest, key);
+        }
+        catch (err) {
+            findings.push(finding("error", `package.${key}_invalid`, err instanceof Error ? err.message : String(err), manifest.name));
+        }
+    }
+    try {
+        const agents = loadRecipeAgentDefinitions(recipeDir);
+        const uniqueAgents = new Set([...agents.values()].map((agent) => agent.name));
+        if (uniqueAgents.size === 0) {
+            findings.push(finding("warning", "agent.none_loaded", "No recipe agent definitions were loaded", manifest.name));
+        }
+        for (const agentFinding of validateRecipeAgentDefinitions(recipeDir)) {
+            findings.push(finding("error", `agent.${agentFinding.field}_missing`, agentFinding.message, manifest.name));
+        }
+        if (uniqueAgents.size > 0) {
+            try {
+                resolveRecipeAgentDefinition({ recipeDir });
+            }
+            catch (err) {
+                findings.push(finding("warning", "agent.default_missing", err instanceof Error ? err.message : String(err), manifest.name));
+            }
+        }
+    }
+    catch (err) {
+        findings.push(finding("error", "agent.invalid", err instanceof Error ? err.message : String(err), manifest.name));
+    }
+    return {
+        valid: findings.every((item) => item.severity !== "error"),
+        manifest,
+        findings,
+        resources,
+    };
+}
+export function createRecipePublishGuide(recipeDir) {
+    const report = validateRecipeDirectory(recipeDir);
+    const name = report.manifest.name;
+    const repositoryName = name.startsWith("@")
+        ? name.slice(1).split("/").at(-1) ?? name.slice(1)
+        : name;
+    return {
+        manifest: report.manifest,
+        report,
+        checklist: [
+            "Run `recipes doctor .` and fix any errors.",
+            `Run \`recipes publish . --github owner/${repositoryName} --visibility private\` to create, commit, and push a GitHub repository.`,
+            "Commit package.json, agents, prompts, skills, themes, extensions, and SYSTEM.md.",
+            "If extensions have runtime dependencies, commit the package lockfile.",
+            "Push the recipe to a Git repository.",
+            "Tag releases when users should install a stable version.",
+        ],
+        sourceExamples: [
+            `recipes install github:owner/${repositoryName}`,
+            `recipes install github:owner/${repositoryName}#v${report.manifest.version}`,
+            `recipes install git@github.com:owner/${repositoryName}.git`,
+        ],
+    };
+}
+//# sourceMappingURL=recipe-dev.js.map

package/dist/recipe-package.d.ts

@@ -0,0 +1,38 @@
+export interface RecipePackageResources {
+    agents: string[];
+    extensions: string[];
+    skills: string[];
+    prompts: string[];
+    themes: string[];
+}
+export interface RecipePackageManifest {
+    name: string;
+    version: string;
+    description?: string;
+    path: string;
+    resources: RecipePackageResources;
+}
+export type PiPackageResources = RecipePackageResources;
+export type PiPackageManifest = RecipePackageManifest;
+export type RecipeValidationSeverity = "error" | "warning";
+export interface RecipeValidationFinding {
+    severity: RecipeValidationSeverity;
+    code: string;
+    message: string;
+    packageName?: string;
+}
+export interface RecipeValidationReport {
+    valid: boolean;
+    findings: RecipeValidationFinding[];
+}
+export declare class RecipePackageError extends Error {
+    constructor(message: string);
+}
+export declare function readPiPackageManifest(packageDir: string): RecipePackageManifest;
+export declare function resolvePiPackageResourcePaths(pkg: RecipePackageManifest, key: keyof RecipePackageResources, opts?: {
+    allowEmptyGlobMatches?: boolean;
+}): string[];
+export declare function defaultPiPackageResourcePaths(pkg: RecipePackageManifest, key: keyof RecipePackageResources): string[];
+export declare function packageResourcePaths(pkg: RecipePackageManifest, key: keyof RecipePackageResources): string[];
+export declare function validatePiPackageManifest(pkg: RecipePackageManifest): RecipeValidationReport;
+//# sourceMappingURL=recipe-package.d.ts.map