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

package/dist/recipe-package.js

@@ -0,0 +1,231 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { isAbsolute, join, relative, resolve } from "node:path";
+const RESOURCE_KEYS = [
+    "agents",
+    "extensions",
+    "skills",
+    "prompts",
+    "themes",
+];
+function stringArray(value) {
+    return Array.isArray(value)
+        ? value.filter((item) => typeof item === "string")
+        : [];
+}
+function emptyResources() {
+    return {
+        agents: [],
+        extensions: [],
+        skills: [],
+        prompts: [],
+        themes: [],
+    };
+}
+function normalizeResourcePath(path) {
+    return path.replace(/\\/g, "/").replace(/^\.\//, "");
+}
+function hasTraversalSegment(path) {
+    return normalizeResourcePath(path)
+        .split("/")
+        .some((segment) => segment === "." || segment === "..");
+}
+function assertPackageResourcePath(pkg, key, resource, resolved) {
+    if (isAbsolute(resource) || hasTraversalSegment(resource)) {
+        throw new RecipePackageError(`Recipe ${pkg.name} declares ${key} resource outside the package: ${resource}`);
+    }
+    const relativePath = relative(resolve(pkg.path), resolved);
+    if (relativePath === ".." ||
+        relativePath.startsWith("../") ||
+        relativePath.startsWith("..\\") ||
+        isAbsolute(relativePath)) {
+        throw new RecipePackageError(`Recipe ${pkg.name} declares ${key} resource outside the package: ${resource}`);
+    }
+}
+function hasGlob(value) {
+    return /[*?[\]{}]/.test(value);
+}
+function escapeRegExp(value) {
+    return value.replace(/[|\\{}()[\]^$+?.]/g, "\\$&");
+}
+function globToRegExp(glob) {
+    const normalized = normalizeResourcePath(glob);
+    let pattern = "^";
+    for (let index = 0; index < normalized.length; index += 1) {
+        const char = normalized[index];
+        const next = normalized[index + 1];
+        if (char === "*" && next === "*") {
+            const after = normalized[index + 2];
+            if (after === "/") {
+                pattern += "(?:.*/)?";
+                index += 2;
+            }
+            else {
+                pattern += ".*";
+                index += 1;
+            }
+        }
+        else if (char === "*") {
+            pattern += "[^/]*";
+        }
+        else if (char === "?") {
+            pattern += "[^/]";
+        }
+        else {
+            pattern += escapeRegExp(char);
+        }
+    }
+    pattern += "$";
+    return new RegExp(pattern);
+}
+function listPackageEntries(root) {
+    const entries = [];
+    function visit(dir, relativeDir = "") {
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+            const relative = relativeDir ? `${relativeDir}/${entry.name}` : entry.name;
+            const fullPath = join(dir, entry.name);
+            entries.push(relative);
+            if (entry.isDirectory())
+                visit(fullPath, relative);
+        }
+    }
+    visit(root);
+    return entries;
+}
+function finding(severity, code, message, packageName) {
+    return {
+        severity,
+        code,
+        message,
+        packageName,
+    };
+}
+export class RecipePackageError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "RecipePackageError";
+    }
+}
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : {};
+}
+function readJsonFile(path) {
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+            ? parsed
+            : {};
+    }
+    catch (err) {
+        throw new RecipePackageError(`Recipe package at ${path} has invalid JSON: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+function stringValue(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+function packageJsonPath(packageDir) {
+    const packagePath = join(packageDir, "package.json");
+    return existsSync(packagePath) ? packagePath : undefined;
+}
+function piPackageManifestBlock(raw) {
+    const pi = asRecord(raw.pi);
+    return Object.keys(pi).length > 0 ? pi : undefined;
+}
+function piPackageManifestPath(packageDir) {
+    const manifestPath = packageJsonPath(packageDir);
+    if (!manifestPath)
+        return undefined;
+    const raw = readJsonFile(manifestPath);
+    return piPackageManifestBlock(raw) ? manifestPath : undefined;
+}
+export function readPiPackageManifest(packageDir) {
+    const packagePath = packageJsonPath(packageDir);
+    if (!packagePath) {
+        throw new RecipePackageError(`Recipe package at ${packageDir} is missing package.json with a pi manifest`);
+    }
+    const raw = readJsonFile(packagePath);
+    const pi = piPackageManifestBlock(raw);
+    if (!pi) {
+        throw new RecipePackageError(`Recipe package at ${packageDir} is missing package.json pi manifest`);
+    }
+    const resources = emptyResources();
+    for (const key of RESOURCE_KEYS) {
+        resources[key] = stringArray(pi[key]).map(normalizeResourcePath);
+    }
+    return {
+        name: stringValue(raw.name) ?? "",
+        version: stringValue(raw.version) ?? "0.0.0",
+        ...(stringValue(raw.description) ? { description: stringValue(raw.description) } : {}),
+        path: packageDir,
+        resources,
+    };
+}
+export function resolvePiPackageResourcePaths(pkg, key, opts = {}) {
+    const globs = pkg.resources[key];
+    const resolved = new Set();
+    const entries = globs.some(hasGlob) ? listPackageEntries(pkg.path) : [];
+    for (const glob of globs) {
+        if (!glob.trim())
+            continue;
+        assertPackageResourcePath(pkg, key, glob, resolve(pkg.path, glob));
+        if (!hasGlob(glob)) {
+            const direct = resolve(pkg.path, glob);
+            if (!existsSync(direct)) {
+                throw new RecipePackageError(`Recipe ${pkg.name} declares missing ${key} resource: ${glob}`);
+            }
+            resolved.add(direct);
+            continue;
+        }
+        const matcher = globToRegExp(glob);
+        const matches = entries
+            .filter((entry) => matcher.test(normalizeResourcePath(entry)))
+            .map((entry) => resolve(pkg.path, entry));
+        if (matches.length === 0) {
+            if (opts.allowEmptyGlobMatches)
+                continue;
+            throw new RecipePackageError(`Recipe ${pkg.name} declares ${key} glob with no matches: ${glob}`);
+        }
+        for (const match of matches)
+            resolved.add(match);
+    }
+    return [...resolved].sort();
+}
+export function defaultPiPackageResourcePaths(pkg, key) {
+    const defaults = {
+        agents: [join(pkg.path, "agents")],
+        skills: [join(pkg.path, "skills")],
+        prompts: [join(pkg.path, "prompts")],
+        themes: [join(pkg.path, "themes")],
+    };
+    return (defaults[key] ?? []).filter((path) => existsSync(path));
+}
+export function packageResourcePaths(pkg, key) {
+    if (pkg.resources[key].length > 0) {
+        return resolvePiPackageResourcePaths(pkg, key, {
+            allowEmptyGlobMatches: key === "extensions" ||
+                key === "skills" ||
+                key === "prompts" ||
+                key === "themes",
+        });
+    }
+    return defaultPiPackageResourcePaths(pkg, key);
+}
+export function validatePiPackageManifest(pkg) {
+    const findings = [];
+    if (!pkg.name.trim()) {
+        findings.push(finding("error", "package.name_missing", "Package is missing name"));
+    }
+    if (!piPackageManifestPath(pkg.path)) {
+        findings.push(finding("error", "package.manifest_missing", "Package is missing package.json with a pi manifest", pkg.name));
+    }
+    if (pkg.resources.agents.length === 0 &&
+        !existsSync(join(pkg.path, "agents"))) {
+        findings.push(finding("warning", "package.no_agents", "Package declares no agents and has no agents directory", pkg.name));
+    }
+    return {
+        valid: findings.every((item) => item.severity !== "error"),
+        findings,
+    };
+}
+//# sourceMappingURL=recipe-package.js.map

package/dist/recipe-publish.d.ts

@@ -0,0 +1,30 @@
+import { type InstalledRecipe, type RecipeStoreOptions } from "./recipe-store.js";
+export type RecipePublishVisibility = "public" | "private";
+export interface RecipePublishCommandResult {
+    stdout: string;
+    stderr: string;
+}
+export type RecipePublishCommandRunner = (command: string, args: string[], opts: {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+}) => Promise<RecipePublishCommandResult>;
+export interface RecipePublishOptions extends RecipeStoreOptions {
+    github: string;
+    visibility: RecipePublishVisibility;
+    message?: string;
+    force?: boolean;
+    commandRunner?: RecipePublishCommandRunner;
+}
+export interface PublishedRecipe {
+    recipe: InstalledRecipe;
+    recipeDir: string;
+    github: string;
+    packageName: string;
+    shortName: string;
+    scopedName: string;
+    createdRepository: boolean;
+    committed: boolean;
+    pushed: boolean;
+}
+export declare function publishRecipe(target: string, opts: RecipePublishOptions): Promise<PublishedRecipe>;
+//# sourceMappingURL=recipe-publish.d.ts.map

package/dist/recipe-publish.js

@@ -0,0 +1,192 @@
+import { execFile } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { promisify } from "node:util";
+import { validateRecipeDirectory } from "./recipe-dev.js";
+import { readPiPackageManifest } from "./recipe-package.js";
+import { addRecipe, customizeRecipe, defaultRecipeStoreDir, findInstalledRecipe, recipePreferredIdentifier, recipeScopedIdentifier, } from "./recipe-store.js";
+const execFileAsync = promisify(execFile);
+function isSafeGithubName(value) {
+    return /^[a-zA-Z0-9_.-]+$/.test(value) && value !== "." && value !== "..";
+}
+function parseGithubTarget(input) {
+    const trimmed = input.trim().replace(/^github:/, "").replace(/^@/, "");
+    const parts = trimmed.split("/").filter(Boolean);
+    const [owner, repo] = parts;
+    if (parts.length !== 2 || !owner || !repo || !isSafeGithubName(owner) || !isSafeGithubName(repo)) {
+        throw new Error("--github must be in owner/repo form");
+    }
+    return {
+        owner,
+        repo,
+        fullName: `${owner}/${repo}`,
+        packageName: `@${owner}/${repo}`,
+        gitUrl: `https://github.com/${owner}/${repo}.git`,
+    };
+}
+async function runCommand(command, args, opts, runner) {
+    if (runner)
+        return runner(command, args, opts);
+    try {
+        return await execFileAsync(command, args, {
+            cwd: opts.cwd,
+            env: opts.env,
+            maxBuffer: 1024 * 1024,
+        });
+    }
+    catch (err) {
+        if (err && typeof err === "object") {
+            const maybe = err;
+            const detail = [maybe.stderr, maybe.stdout, maybe.message]
+                .filter((value) => typeof value === "string" && value.trim().length > 0)
+                .join("\n")
+                .trim();
+            if (detail)
+                throw new Error(detail);
+        }
+        throw err;
+    }
+}
+async function commandSucceeds(command, args, opts, runner) {
+    try {
+        await runCommand(command, args, opts, runner);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function readPackageJson(recipeDir) {
+    return JSON.parse(readFileSync(join(recipeDir, "package.json"), "utf8"));
+}
+function writePackageName(recipeDir, packageName) {
+    const packagePath = join(recipeDir, "package.json");
+    const pkg = readPackageJson(recipeDir);
+    if (pkg.name === packageName)
+        return false;
+    pkg.name = packageName;
+    writeFileSync(packagePath, `${JSON.stringify(pkg, null, 2)}\n`);
+    return true;
+}
+function ensureGitignore(recipeDir) {
+    const gitignorePath = join(recipeDir, ".gitignore");
+    const desired = ["node_modules/", "dist/", ".DS_Store", ".env", ".env.*"];
+    const existing = existsSync(gitignorePath)
+        ? readFileSync(gitignorePath, "utf8").split(/\r?\n/)
+        : [];
+    const existingSet = new Set(existing.map((line) => line.trim()).filter(Boolean));
+    const missing = desired.filter((line) => !existingSet.has(line));
+    if (missing.length === 0)
+        return false;
+    const prefix = existing.length > 0 && existing.some((line) => line.trim()) ? "\n" : "";
+    writeFileSync(gitignorePath, `${existing.join("\n").replace(/\n*$/, "")}${prefix}${missing.join("\n")}\n`);
+    return true;
+}
+function localPathForInput(input, cwd) {
+    const expanded = input === "~"
+        ? process.env.HOME ?? input
+        : input.startsWith("~/")
+            ? join(process.env.HOME ?? "", input.slice(2))
+            : input;
+    return isAbsolute(expanded) ? expanded : resolve(cwd, expanded);
+}
+async function editableRecipeDir(target, opts) {
+    const cwd = opts.cwd ?? process.cwd();
+    const storeDir = opts.storeDir ?? defaultRecipeStoreDir(opts.env);
+    const installed = findInstalledRecipe(target, opts);
+    if (!installed) {
+        const path = localPathForInput(target, cwd);
+        if (!existsSync(path))
+            throw new Error(`Recipe not found: ${target}`);
+        return path;
+    }
+    if (installed.id.startsWith("local:"))
+        return installed.path;
+    const customized = await customizeRecipe(target, {
+        storeDir,
+        cwd,
+        env: opts.env,
+        force: opts.force,
+    });
+    return customized.path;
+}
+async function ensureGitRepository(recipeDir, env, runner) {
+    if (!existsSync(join(recipeDir, ".git"))) {
+        await runCommand("git", ["init"], { cwd: recipeDir, env }, runner);
+    }
+    const hasHead = await commandSucceeds("git", ["rev-parse", "--verify", "HEAD"], { cwd: recipeDir, env }, runner);
+    if (!hasHead) {
+        await runCommand("git", ["branch", "-M", "main"], { cwd: recipeDir, env }, runner);
+    }
+}
+async function commitRecipe(recipeDir, message, env, runner) {
+    await runCommand("git", ["add", "-A"], { cwd: recipeDir, env }, runner);
+    const hasChanges = !(await commandSucceeds("git", ["diff", "--cached", "--quiet"], { cwd: recipeDir, env }, runner));
+    if (!hasChanges)
+        return false;
+    await runCommand("git", ["commit", "-m", message], { cwd: recipeDir, env }, runner);
+    return true;
+}
+async function ensureGithubRepository(target, visibility, recipeDir, env, runner) {
+    const exists = await commandSucceeds("gh", ["repo", "view", target.fullName, "--json", "nameWithOwner"], { cwd: recipeDir, env }, runner);
+    if (exists)
+        return false;
+    try {
+        await runCommand("gh", ["repo", "create", target.fullName, `--${visibility}`], { cwd: recipeDir, env }, runner);
+        return true;
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error([
+            `Failed to create GitHub repository ${target.fullName}.`,
+            message,
+            "",
+            "Make sure GitHub CLI is installed and authenticated:",
+            "  gh auth login",
+        ].join("\n"));
+    }
+}
+async function setOrigin(target, recipeDir, env, runner) {
+    const hasOrigin = await commandSucceeds("git", ["remote", "get-url", "origin"], { cwd: recipeDir, env }, runner);
+    if (hasOrigin) {
+        await runCommand("git", ["remote", "set-url", "origin", target.gitUrl], { cwd: recipeDir, env }, runner);
+    }
+    else {
+        await runCommand("git", ["remote", "add", "origin", target.gitUrl], { cwd: recipeDir, env }, runner);
+    }
+}
+export async function publishRecipe(target, opts) {
+    const github = parseGithubTarget(opts.github);
+    const recipeDir = await editableRecipeDir(target, opts);
+    mkdirSync(dirname(recipeDir), { recursive: true });
+    readPiPackageManifest(recipeDir);
+    const report = validateRecipeDirectory(recipeDir);
+    const errors = report.findings.filter((finding) => finding.severity === "error");
+    if (errors.length > 0) {
+        throw new Error([
+            `Recipe ${report.manifest.name} is not ready to publish.`,
+            ...errors.map((finding) => `- ${finding.message}`),
+        ].join("\n"));
+    }
+    writePackageName(recipeDir, github.packageName);
+    ensureGitignore(recipeDir);
+    const env = opts.env ?? process.env;
+    await ensureGitRepository(recipeDir, env, opts.commandRunner);
+    const committed = await commitRecipe(recipeDir, opts.message ?? `Publish ${github.packageName}`, env, opts.commandRunner);
+    const createdRepository = await ensureGithubRepository(github, opts.visibility, recipeDir, env, opts.commandRunner);
+    await setOrigin(github, recipeDir, env, opts.commandRunner);
+    await runCommand("git", ["push", "-u", "origin", "HEAD:main"], { cwd: recipeDir, env }, opts.commandRunner);
+    const recipe = await addRecipe(recipeDir, opts);
+    return {
+        recipe,
+        recipeDir,
+        github: github.fullName,
+        packageName: github.packageName,
+        shortName: recipePreferredIdentifier(recipe),
+        scopedName: recipeScopedIdentifier(recipe),
+        createdRepository,
+        committed,
+        pushed: true,
+    };
+}
+//# sourceMappingURL=recipe-publish.js.map

package/dist/recipe-store.d.ts

@@ -0,0 +1,66 @@
+export interface RecipeStoreOptions {
+    storeDir?: string;
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+}
+export interface InstalledRecipe {
+    id: string;
+    source: string;
+    path: string;
+    installedAt: string;
+    name: string;
+    version: string;
+    description?: string;
+}
+export interface RecipeStoreFile {
+    version: 1;
+    recipes: InstalledRecipe[];
+}
+export interface CustomizedRecipe {
+    original: InstalledRecipe;
+    recipe: InstalledRecipe;
+    path: string;
+    overwritten: boolean;
+}
+interface GithubRecipeSource {
+    kind: "github";
+    input: string;
+    host: "github.com";
+    owner: string;
+    repo: string;
+    ref?: string;
+    subdir?: string;
+}
+interface GitRecipeSource {
+    kind: "git";
+    input: string;
+    url: string;
+    ref?: string;
+}
+interface LocalRecipeSource {
+    kind: "local";
+    input: string;
+    path: string;
+}
+export type RecipeSource = GithubRecipeSource | GitRecipeSource | LocalRecipeSource;
+export declare function defaultRecipeStoreDir(env?: NodeJS.ProcessEnv): string;
+export declare function recipeStoreFilePath(storeDir?: string): string;
+export declare function parseRecipeSource(input: string, opts?: RecipeStoreOptions): RecipeSource;
+export declare function recipeSourceId(source: RecipeSource): string;
+export declare function readRecipeStore(storeDir?: string): RecipeStoreFile;
+export declare function addRecipe(input: string, opts?: RecipeStoreOptions & {
+    force?: boolean;
+}): Promise<InstalledRecipe>;
+export declare function listRecipes(opts?: RecipeStoreOptions): InstalledRecipe[];
+export declare function recipeScopedIdentifier(recipe: InstalledRecipe): string;
+export declare function recipePreferredIdentifier(recipe: InstalledRecipe): string;
+export declare function findInstalledRecipe(identifier: string, opts?: RecipeStoreOptions): InstalledRecipe | undefined;
+export declare function removeRecipe(identifier: string, opts?: RecipeStoreOptions): InstalledRecipe | undefined;
+export declare function customizeRecipe(identifier: string, opts?: RecipeStoreOptions & {
+    force?: boolean;
+}): Promise<CustomizedRecipe>;
+export declare function resolveRecipeDirectory(input: string, opts?: RecipeStoreOptions): string;
+export declare function recipeDisplayName(recipe: InstalledRecipe): string;
+export declare function recipeBasename(path: string): string;
+export {};
+//# sourceMappingURL=recipe-store.d.ts.map