@finngi/pi-resources 0.0.0-stage → 0.1.0-alpha.0

package/node_modules/pi-resources/dist/lib/picker.js

@@ -0,0 +1,85 @@
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { writeResourceDefaults, writeResourceMode, } from "./resource-selection.js";
+/** One scope implementation for independent resources and package availability. */
+export function resourcePickerControls(options) {
+    const { ctx, setup, entries, members } = options;
+    const aggregate = (values, mixed) => values.length > 0 && values.every((value) => value === values[0]) ? values[0] : mixed;
+    const refresh = () => {
+        for (const entry of entries) {
+            const states = members(entry).map((member) => setup.state(member.kind, member.id, member.nativeDefault));
+            entry.selected = states.length > 0 && states.every((state) => state.selected);
+            if (states.length > 1)
+                entry.badge =
+                    states.some((state) => state.selected) && !entry.selected ? "partial" : undefined;
+            entry.sessionState = aggregate(states.map((state) => state.sessionState), "mixed");
+            entry.projectState = aggregate(states.map((state) => state.projectState), "mixed");
+            entry.globalState = aggregate(states.map((state) => state.globalState), "mixed");
+            entry.projectMode = aggregate(states.map((state) => state.projectMode), "mixed");
+            entry.globalMode = aggregate(states.map((state) => state.globalMode), "mixed");
+            entry.effectiveSource = aggregate(states.map((state) => state.effectiveSource), undefined);
+            entry.mode = aggregate(states.map((state) => state.mode), undefined);
+            entry.modeSource = aggregate(states.map((state) => state.modeSource), undefined);
+        }
+    };
+    const eligible = (entry, scope) => {
+        if (entry.defaultable === false || (scope === "global" && entry.globalDefaultable === false))
+            throw Error("This resource cannot be saved at that scope");
+        if (scope === "project" && !ctx.isProjectTrusted())
+            throw Error("Saving defaults requires a trusted project");
+        return members(entry).filter((member) => scope !== "global" || member.globalDefaultable !== false);
+    };
+    const saved = async (scope, rows, state) => {
+        if (scope === "project" && !ctx.isProjectTrusted())
+            throw Error("Saving defaults requires a trusted project");
+        const selections = {};
+        const targets = rows.flatMap((entry) => eligible(entry, scope));
+        // Bulk snapshots save On/Off; session types change only through the saved-scope menu.
+        for (const member of targets) {
+            const selection = (selections[member.kind] ??= { knownIds: [], values: {} });
+            selection.knownIds.push(member.id);
+            selection.values[member.id] =
+                state === undefined
+                    ? setup.state(member.kind, member.id, member.nativeDefault).selected
+                    : state === "inherit"
+                        ? undefined
+                        : state === "on";
+        }
+        await writeResourceDefaults({ scope, selections, cwd: ctx.cwd, agentDir: getAgentDir() });
+        setup.refresh(ctx);
+        refresh();
+    };
+    const setSession = (entry, state) => {
+        const byKind = new Map();
+        for (const member of members(entry))
+            byKind.set(member.kind, { ...byKind.get(member.kind), [member.id]: state });
+        for (const [kind, states] of byKind)
+            setup.setStates(kind, states, ctx);
+        refresh();
+    };
+    refresh();
+    return {
+        refresh,
+        toggle: async (entry, selected) => {
+            setSession(entry, selected ? "on" : "off");
+        },
+        setSession: async (entry, state) => {
+            setSession(entry, state);
+        },
+        setDefault: (entry, state, scope) => saved(scope, [entry], state),
+        setMode: async (entry, mode, scope) => {
+            for (const member of eligible(entry, scope))
+                await writeResourceMode({
+                    scope,
+                    kind: member.kind,
+                    id: member.id,
+                    mode,
+                    cwd: ctx.cwd,
+                    agentDir: getAgentDir(),
+                });
+            setup.refresh(ctx);
+            refresh();
+        },
+        saveDefaults: (rows) => saved("project", rows),
+        saveGlobalDefaults: (rows) => saved("global", rows),
+    };
+}

package/node_modules/pi-resources/dist/lib/resource-packages.d.ts

@@ -0,0 +1,29 @@
+import { type SettingsManager, type SourceInfo } from "@earendil-works/pi-coding-agent";
+export interface ResourcePackage {
+    name: string;
+    root: string;
+    globalDefaultable?: boolean;
+    /** Enabled native personal skills, before project/CLI sources are added. */
+    personalSkills?: string[];
+    description: string;
+    keywords: string[];
+    skills: string[];
+    agents: string[];
+    instructions: Array<{
+        catalogue: string;
+        path: string;
+        content: string;
+    }>;
+}
+export declare function withinResourceRoot(root: string, file: string): boolean;
+/** Read package data through a bounded regular file; never execute package entrypoints. */
+export declare function readResourceFile(root: string, file: string): string;
+/** Only the two resource types missing from native Pi need a descriptor reader. */
+export declare function readResourcePackage(directory: string, skills?: string[]): ResourcePackage;
+/** Native Pi owns sources, identity, trust and skill filtering; discovery never installs packages. */
+export declare function discoverResourcePackages(settings: SettingsManager, cwd: string, agentDir: string, loaded?: SourceInfo[], temporarySources?: string[]): Promise<{
+    packs: ResourcePackage[];
+    problems: string[];
+}>;
+/** Pack metadata augments the existing resource browser search, never the model prompt. */
+export declare function resourcePackageKeywords(pack: ResourcePackage): string;

package/node_modules/pi-resources/dist/lib/resource-packages.js

@@ -0,0 +1,187 @@
+import { closeSync, constants, existsSync, fstatSync, lstatSync, openSync, readdirSync, readSync, realpathSync, statSync, } from "node:fs";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { DefaultPackageManager, parseArgs, } from "@earendil-works/pi-coding-agent";
+export function withinResourceRoot(root, file) {
+    const rel = relative(root, file);
+    return rel === "" || (rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel));
+}
+/** Read package data through a bounded regular file; never execute package entrypoints. */
+export function readResourceFile(root, file) {
+    const canonical = realpathSync(file);
+    if (!withinResourceRoot(root, canonical))
+        throw Error("resource path escapes pack root");
+    let fd;
+    try {
+        fd = openSync(canonical, constants.O_RDONLY | constants.O_NONBLOCK | constants.O_NOFOLLOW);
+        const info = fstatSync(fd);
+        if (!info.isFile() || info.nlink !== 1 || info.size > 1024 * 1024)
+            throw Error("resource must be a bounded regular file without hard links");
+        const bytes = Buffer.allocUnsafe(1024 * 1024 + 1);
+        let length = 0;
+        while (length < bytes.length) {
+            const read = readSync(fd, bytes, length, bytes.length - length, length);
+            if (!read)
+                break;
+            length += read;
+        }
+        if (length > 1024 * 1024)
+            throw Error("resource exceeds the discovery byte limit");
+        const body = bytes.subarray(0, length).toString("utf8");
+        const after = lstatSync(canonical);
+        if (realpathSync(file) !== canonical ||
+            after.dev !== info.dev ||
+            after.ino !== info.ino ||
+            after.nlink !== 1)
+            throw Error("resource changed during discovery");
+        return body;
+    }
+    finally {
+        if (fd !== undefined)
+            closeSync(fd);
+    }
+}
+function declaredDirectories(root, value) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value) || value.some((path) => typeof path !== "string" || isAbsolute(path)))
+        throw Error("pi.agents and pi.instructions must be relative directory arrays");
+    return [
+        ...new Set(value.map((path) => {
+            const canonical = realpathSync(resolve(root, path));
+            if (!withinResourceRoot(root, canonical) || !statSync(canonical).isDirectory())
+                throw Error("resource directory escapes package root or is not a directory");
+            return canonical;
+        })),
+    ];
+}
+/** Only the two resource types missing from native Pi need a descriptor reader. */
+export function readResourcePackage(directory, skills = []) {
+    const root = realpathSync(directory);
+    const manifest = JSON.parse(readResourceFile(root, join(root, "package.json")));
+    if (!manifest || typeof manifest.name !== "string" || !manifest.name.trim())
+        throw Error("package.json requires a package name");
+    if (manifest.description !== undefined && typeof manifest.description !== "string")
+        throw Error("package description must be a string");
+    if (manifest.keywords !== undefined &&
+        (!Array.isArray(manifest.keywords) ||
+            manifest.keywords.some((word) => typeof word !== "string")))
+        throw Error("package keywords must be strings");
+    const agents = declaredDirectories(root, manifest.pi?.agents);
+    const catalogues = declaredDirectories(root, manifest.pi?.instructions);
+    const instructions = catalogues.flatMap((catalogue) => readdirSync(catalogue)
+        .filter((name) => name.endsWith(".md"))
+        .sort()
+        .map((name) => ({
+        catalogue,
+        path: join(catalogue, name),
+        content: readResourceFile(root, join(catalogue, name)),
+    })));
+    return {
+        name: manifest.name,
+        root,
+        description: manifest.description ?? "",
+        keywords: manifest.keywords ?? [],
+        skills,
+        agents,
+        instructions,
+    };
+}
+/** Native Pi owns sources, identity, trust and skill filtering; discovery never installs packages. */
+export async function discoverResourcePackages(settings, cwd, agentDir, loaded, temporarySources = parseArgs(process.argv.slice(2)).extensions ?? []) {
+    const manager = new DefaultPackageManager({ settingsManager: settings, cwd, agentDir });
+    const skipped = new Set();
+    const paths = await manager.resolve(async (source) => {
+        skipped.add(source);
+        return "skip";
+    });
+    const roots = new Map();
+    const personalRoots = new Set();
+    const personalSkills = new Map();
+    const temporaryRoots = new Set();
+    const problems = [];
+    // CLI packages have already passed Pi's resolver. Look up their roots without installing again.
+    for (const source of temporarySources) {
+        if (source.startsWith("builtin:"))
+            continue;
+        try {
+            // Pi 1.2 implements this scope, but its exported declaration omits it.
+            // @ts-expect-error Native getInstalledPath supports temporary package locations.
+            const directory = manager.getInstalledPath(source, "temporary");
+            if (!directory || !statSync(directory).isDirectory())
+                continue;
+            const root = realpathSync(directory);
+            temporaryRoots.add(root);
+            roots.set(root, (loaded ?? [])
+                .filter((skill) => {
+                try {
+                    return withinResourceRoot(root, realpathSync(skill.path));
+                }
+                catch {
+                    return false;
+                }
+            })
+                .map((skill) => skill.path));
+        }
+        catch {
+            problems.push(`${source}: temporary package resources could not be resolved`);
+        }
+    }
+    for (const [kind, resources] of Object.entries(paths))
+        for (const resource of resources) {
+            if (!resource.metadata.packageRoot)
+                continue;
+            const root = realpathSync(resource.metadata.packageRoot);
+            const skills = roots.get(root) ?? [];
+            if (resource.metadata.scope === "user") {
+                personalRoots.add(root);
+                if (kind === "skills" && resource.enabled)
+                    personalSkills.set(root, [...(personalSkills.get(root) ?? []), resource.path]);
+            }
+            if (kind === "skills" &&
+                resource.enabled &&
+                (!loaded || loaded.some((source) => source.path === resource.path)))
+                skills.push(resource.path);
+            roots.set(root, skills);
+        }
+    // Native resolution has no output record for a package containing only custom resource types.
+    for (const entry of manager.listConfiguredPackages().reverse()) {
+        // Pi supplies the installed root for local, Git and npm sources; never resolve caches ourselves.
+        if (!entry.installedPath || skipped.has(entry.source))
+            continue;
+        const root = realpathSync(entry.installedPath);
+        if (entry.scope === "user")
+            personalRoots.add(root);
+        if (statSync(root).isDirectory() && !roots.has(root))
+            roots.set(root, []);
+    }
+    const packs = [], names = new Set(), temporaryNames = new Set();
+    for (const [root, skills] of roots) {
+        if (!existsSync(join(root, "package.json")))
+            continue;
+        try {
+            const pack = readResourcePackage(root, [...new Set(skills)]);
+            pack.globalDefaultable = personalRoots.has(root);
+            pack.personalSkills = personalSkills.get(root) ?? [];
+            // Availability gates only skills, agents and instructions; extension code always loads.
+            if (!pack.skills.length && !pack.agents.length && !pack.instructions.length)
+                continue;
+            // Explicit CLI content takes precedence over another configured copy of that package.
+            if (names.has(pack.name) && !temporaryRoots.has(root) && temporaryNames.has(pack.name))
+                continue;
+            if (names.has(pack.name))
+                throw Error("duplicate package name");
+            names.add(pack.name);
+            if (temporaryRoots.has(root))
+                temporaryNames.add(pack.name);
+            packs.push(pack);
+        }
+        catch {
+            problems.push(`${root}: package resources could not be read`);
+        }
+    }
+    return { packs, problems };
+}
+/** Pack metadata augments the existing resource browser search, never the model prompt. */
+export function resourcePackageKeywords(pack) {
+    return [pack.name, pack.description, ...pack.keywords].join(" ");
+}

package/node_modules/pi-resources/dist/lib/resource-selection.d.ts

@@ -0,0 +1,91 @@
+import type { SettingsManager } from "@earendil-works/pi-coding-agent";
+import { type ResourcePackage } from "./resource-packages.ts";
+export type ResourceKind = "packages" | "skills" | "agents" | "instructions";
+export type ResourceDefaultState = "inherit" | "on" | "off";
+export type ResourceSelectionValue = Record<string, boolean> | undefined;
+export type ResourceMode = "any" | "interactive";
+export type ResourceModeState = "inherit" | ResourceMode;
+export type ResourceModes = Record<string, ResourceMode> | undefined;
+export declare function readResourceModes(settings: SettingsManager, scope: "project" | "global", kind: ResourceKind): ResourceModes;
+export declare function validateResourceModes(value: unknown): ResourceModes;
+export declare function resourceModeState(value: ResourceModes, id: string): ResourceModeState;
+export declare function resolveResourceMode(global: ResourceModes, project: ResourceModes, id: string): {
+    mode: ResourceMode;
+    source: "project" | "global" | "native";
+};
+export declare function resourceApplies(settings: SettingsManager, kind: ResourceKind, id: string, interactive: boolean, packName?: string): boolean;
+export declare function packageApplies(settings: SettingsManager, name: string, interactive: boolean): boolean;
+/** Whether a package's resources load here, or why they do not. */
+export type PackageAvailability = "available" | "off" | "interactive";
+export declare function packageAvailability(settings: SettingsManager, name: string, interactive: boolean): PackageAvailability;
+export interface SkillChoice {
+    name: string;
+    description: string;
+    path: string;
+    toggleable: boolean;
+    defaultSelected: boolean;
+    manualOnly?: boolean;
+    packName?: string;
+    packKeywords?: string;
+}
+export interface GlobalSelectionSnapshot {
+    present: boolean;
+    values?: Record<string, boolean>;
+}
+export declare function readResourceSelection(settings: SettingsManager, scope: "project" | "global", kind: ResourceKind): ResourceSelectionValue;
+export declare function validateResourceSelection(value: unknown, kind: ResourceKind): ResourceSelectionValue;
+export declare function resourceSelectionState(value: ResourceSelectionValue, id: string): ResourceDefaultState;
+export declare function resolveResourceSelection(global: ResourceSelectionValue, project: ResourceSelectionValue, id: string, nativeDefault: boolean, session?: ResourceSelectionValue): {
+    globalState: ResourceDefaultState;
+    projectState: ResourceDefaultState;
+    effective: boolean;
+    source: "session" | "project" | "global" | "native";
+};
+export interface ResourceDefaultWrite {
+    scope: "project" | "global";
+    kind: ResourceKind;
+    id: string;
+    state: ResourceDefaultState;
+    knownIds: string[];
+    cwd?: string;
+    agentDir?: string;
+}
+export interface ResourceDefaultsWrite {
+    scope: "project" | "global";
+    selections: Partial<Record<ResourceKind, {
+        values: Record<string, boolean | undefined>;
+        knownIds: string[];
+        /** Bulk save: discard saved IDs that are no longer known in this category. */
+        snapshot?: boolean;
+    }>>;
+    cwd?: string;
+    agentDir?: string;
+}
+export declare function writeResourceDefault(options: ResourceDefaultWrite): Promise<void>;
+export declare function writeResourceDefaults(options: ResourceDefaultsWrite): Promise<void>;
+export declare function writeResourceMode(options: {
+    scope: "project" | "global";
+    kind: ResourceKind;
+    id: string;
+    mode: ResourceModeState;
+    cwd?: string;
+    agentDir?: string;
+}): Promise<void>;
+export declare function configuredSkillChoices(cwd: string, agentDir: string, loaded: Array<{
+    name: string;
+    path: string;
+}>, packs?: ResourcePackage[]): SkillChoice[];
+export declare function selectedSkills(settings: SettingsManager, choices: SkillChoice[], ignoreInvalidProjectSelection?: boolean, globalSnapshot?: GlobalSelectionSnapshot, interactive?: boolean): SkillChoice[];
+export declare function filterPromptSkills<T extends {
+    name: string;
+}>(skills: T[], selected: SkillChoice[]): T[];
+export declare function selectedAgents<T extends {
+    name: string;
+    catalogueOnly?: boolean;
+    packName?: string;
+}>(settings: SettingsManager, agents: T[], globalSnapshot?: GlobalSelectionSnapshot, interactive?: boolean): {
+    agents: T[];
+    configured: boolean;
+    error?: string;
+};
+export declare function assertSafeProjectSettingsLocation(cwd: string): Promise<void>;