@fitchmultz/pi-subagents 0.49.1 → 0.50.0

package/src/agents/skill-files.ts

@@ -1,182 +0,0 @@
-import * as fs from "node:fs";
-import * as os from "node:os";
-import * as path from "node:path";
-import { getGlobalNpmRoot } from "./skill-search-paths.ts";
-import type {
-  SkillSource,
-  SkillSearchPath,
-  CachedSkillEntry,
-  ResolvedSkill,
-} from "./skill-types.ts";
-
-const skillCache = new Map<string, { mtime: number; skill: ResolvedSkill }>();
-const MAX_CACHE_SIZE = 50;
-
-function stripFrontmatter(content: string): string {
-  const normalized = content.replace(/\r\n/g, "\n");
-  if (!normalized.startsWith("---")) {
-    return normalized;
-  }
-  const end = normalized.indexOf("\n---", 3);
-  return end === -1 ? normalized : normalized.slice(end + 4).trim();
-}
-
-function isWithinPath(filePath: string, dir: string): boolean {
-  const relative = path.relative(dir, filePath);
-  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
-}
-
-function inferSource(
-  filePath: string,
-  cwd: string,
-  agentDir: string,
-  hint?: SkillSource,
-): SkillSource {
-  if (hint !== undefined) {
-    return hint;
-  }
-  const roots: { path: string; source: SkillSource }[] = [
-    { path: path.resolve(cwd, ".pi", "npm", "node_modules"), source: "project-package" },
-    { path: path.resolve(cwd, ".pi", "skills"), source: "project" },
-    { path: path.resolve(cwd, ".agents"), source: "project" },
-    { path: path.resolve(cwd, ".pi"), source: "project-settings" },
-    { path: path.resolve(agentDir, "npm", "node_modules"), source: "user-package" },
-    { path: path.resolve(agentDir, "skills"), source: "user" },
-    { path: path.resolve(os.homedir(), ".agents"), source: "user" },
-    { path: path.resolve(agentDir), source: "user-settings" },
-  ];
-  const matched = roots.find((root) => isWithinPath(filePath, root.path));
-  if (matched !== undefined) {
-    return matched.source;
-  }
-  const globalRoot = getGlobalNpmRoot();
-  return globalRoot !== null && globalRoot.length > 0 && isWithinPath(filePath, globalRoot)
-    ? "user-package"
-    : "unknown";
-}
-
-function description(filePath: string): string | undefined {
-  try {
-    const normalized = fs.readFileSync(filePath, "utf-8").replace(/\r\n/g, "\n");
-    if (!normalized.startsWith("---")) {
-      return undefined;
-    }
-    const end = normalized.indexOf("\n---", 3);
-    if (end === -1) {
-      return undefined;
-    }
-    return normalized
-      .slice(3, end)
-      .trim()
-      .match(/^description:\s*(.+)$/m)?.[1]
-      ?.trim()
-      .replace(/^['"]|['"]$/g, "");
-  } catch {
-    // Descriptions are optional metadata; failure does not hide an otherwise readable skill.
-    return undefined;
-  }
-}
-
-function childSkills(dir: string): { name: string; filePath: string }[] {
-  let children: fs.Dirent[];
-  try {
-    children = fs.readdirSync(dir, { withFileTypes: true });
-  } catch {
-    return [];
-  }
-  return children.flatMap((child) => {
-    if (child.name.startsWith(".")) {
-      return [];
-    }
-    const childPath = path.join(dir, child.name);
-    if (child.isDirectory() || child.isSymbolicLink()) {
-      return [{ name: child.name, filePath: path.join(childPath, "SKILL.md") }];
-    }
-    return child.isFile() && child.name.toLowerCase().endsWith(".md")
-      ? [{ name: path.basename(child.name, path.extname(child.name)), filePath: childPath }]
-      : [];
-  });
-}
-
-function pathSkills(skillPath: string): { name: string; filePath: string }[] {
-  let stat: fs.Stats;
-  try {
-    stat = fs.statSync(skillPath);
-  } catch {
-    return [];
-  }
-  if (stat.isFile()) {
-    const fileName = path.basename(skillPath);
-    if (!fileName.toLowerCase().endsWith(".md")) {
-      return [];
-    }
-    const name =
-      fileName.toLowerCase() === "skill.md"
-        ? path.basename(path.dirname(skillPath))
-        : path.basename(fileName, path.extname(fileName));
-    return [{ name, filePath: skillPath }];
-  }
-  return stat.isDirectory()
-    ? [
-        { name: path.basename(skillPath), filePath: path.join(skillPath, "SKILL.md") },
-        ...childSkills(skillPath),
-      ]
-    : [];
-}
-
-export function collectFilesystemSkills(
-  cwd: string,
-  agentDir: string,
-  skillPaths: readonly SkillSearchPath[],
-): CachedSkillEntry[] {
-  const entries: CachedSkillEntry[] = [];
-  const seen = new Set<string>();
-  for (const skillPath of skillPaths) {
-    for (const entry of pathSkills(skillPath.path)) {
-      const filePath = path.resolve(entry.filePath);
-      if (seen.has(filePath) || !fs.existsSync(filePath)) {
-        continue;
-      }
-      seen.add(filePath);
-      entries.push({
-        name: entry.name,
-        filePath,
-        source: inferSource(filePath, cwd, agentDir, skillPath.source),
-        description: description(filePath),
-        order: entries.length,
-      });
-    }
-  }
-  return entries;
-}
-
-export function readSkill(
-  skillName: string,
-  skillPath: string,
-  source: SkillSource,
-): ResolvedSkill | undefined {
-  try {
-    const stat = fs.statSync(skillPath);
-    const cached = skillCache.get(skillPath);
-    if (cached !== undefined && cached.mtime === stat.mtimeMs) {
-      return cached.skill;
-    }
-    const skill = {
-      name: skillName,
-      path: skillPath,
-      content: stripFrontmatter(fs.readFileSync(skillPath, "utf-8")),
-      source,
-    };
-    skillCache.set(skillPath, { mtime: stat.mtimeMs, skill });
-    if (skillCache.size > MAX_CACHE_SIZE) {
-      const firstKey = skillCache.keys().next().value;
-      if (firstKey !== undefined && firstKey.length > 0) {
-        skillCache.delete(firstKey);
-      }
-    }
-    return skill;
-  } catch {
-    // Resolution surfaces unreadable files as missing rather than failing the invocation.
-    return undefined;
-  }
-}

package/src/agents/skill-search-paths.ts

@@ -1,289 +0,0 @@
-import { execSync } from "node:child_process";
-import * as fs from "node:fs";
-import * as os from "node:os";
-import * as path from "node:path";
-import type { SkillSource, SkillSearchPath } from "./skill-types.ts";
-import { isConfigObject, errorMessage } from "./config-values.ts";
-
-const CONFIG_DIR = ".pi";
-let cachedGlobalNpmRoot: string | null = null;
-
-export function getGlobalNpmRoot(): string | null {
-  if (cachedGlobalNpmRoot !== null) {
-    return cachedGlobalNpmRoot;
-  }
-  try {
-    cachedGlobalNpmRoot = execSync("npm root -g", {
-      encoding: "utf-8",
-      timeout: 5000,
-      stdio: "pipe",
-    }).trim();
-    return cachedGlobalNpmRoot;
-  } catch {
-    // The empty cache value records the failed optional lookup.
-    cachedGlobalNpmRoot = "";
-    return null;
-  }
-}
-
-function readJson(filePath: string, label: string, bestEffort = false): unknown {
-  try {
-    return JSON.parse(fs.readFileSync(filePath, "utf-8"));
-  } catch (error) {
-    if (bestEffort || (isConfigObject(error) && error.code === "ENOENT")) {
-      return null;
-    }
-    throw new Error(`Failed to read ${label} '${filePath}': ${errorMessage(error)}`, {
-      cause: error,
-    });
-  }
-}
-
-function extractSkillPaths(
-  packageRoot: string,
-  source: SkillSource,
-  bestEffort = false,
-): SkillSearchPath[] {
-  const pkg = readJson(path.join(packageRoot, "package.json"), "package manifest", bestEffort);
-  if (!isConfigObject(pkg) || !isConfigObject(pkg.pi) || !Array.isArray(pkg.pi.skills)) {
-    return [];
-  }
-  return pkg.pi.skills
-    .filter((entry: unknown): entry is string => typeof entry === "string")
-    .map((entry) => ({ path: path.resolve(packageRoot, entry), source }));
-}
-
-function packageDirectories(dir: string): string[] {
-  let entries: fs.Dirent[];
-  try {
-    entries = fs.readdirSync(dir, { withFileTypes: true });
-  } catch {
-    return [];
-  }
-  return entries
-    .filter(
-      (entry) => !entry.name.startsWith(".") && (entry.isDirectory() || entry.isSymbolicLink()),
-    )
-    .map((entry) => path.join(dir, entry.name));
-}
-
-function installedPackagePaths(
-  cwd: string,
-  agentDir: string,
-  projectTrusted: boolean,
-): SkillSearchPath[] {
-  const dirs: SkillSearchPath[] = [
-    { path: path.join(agentDir, "npm", "node_modules"), source: "user-package" },
-  ];
-  if (projectTrusted) {
-    dirs.unshift({
-      path: path.join(cwd, CONFIG_DIR, "npm", "node_modules"),
-      source: "project-package",
-    });
-  }
-  const globalRoot = getGlobalNpmRoot();
-  if (globalRoot !== null && globalRoot.length > 0) {
-    dirs.push({ path: globalRoot, source: "user-package" });
-  }
-  const results: SkillSearchPath[] = [];
-  for (const dir of dirs) {
-    for (const packageDir of packageDirectories(dir.path)) {
-      const roots = path.basename(packageDir).startsWith("@")
-        ? packageDirectories(packageDir)
-        : [packageDir];
-      for (const root of roots) {
-        results.push(...extractSkillPaths(root, dir.source, true));
-      }
-    }
-  }
-  return results;
-}
-
-function isSafePackagePath(value: string): boolean {
-  return (
-    value.length > 0 &&
-    !path.isAbsolute(value) &&
-    value.split(/[\\/]/).every((part) => part.length > 0 && part !== "." && part !== "..")
-  );
-}
-
-function npmPackageName(source: string): string | undefined {
-  const spec = source.slice(4).trim();
-  if (spec.length === 0) {
-    return undefined;
-  }
-  const packageName = spec.match(/^(@?[^@]+(?:\/[^@]+)?)(?:@(.+))?$/)?.[1] ?? spec;
-  return isSafePackagePath(packageName) ? packageName : undefined;
-}
-
-function stripGitRef(repoPath: string): string {
-  const refIndex = [repoPath.indexOf("@"), repoPath.indexOf("#")]
-    .filter((index) => index >= 0)
-    .sort((a, b) => a - b)
-    .at(0);
-  return refIndex === undefined ? repoPath : repoPath.slice(0, refIndex);
-}
-
-function gitLocation(spec: string): { host: string; repoPath: string } | undefined {
-  const scpLike: RegExpMatchArray | null = spec.match(/^git@([^:]+):(.+)$/);
-  if (scpLike) {
-    return { host: scpLike.at(1) ?? "", repoPath: scpLike.at(2) ?? "" };
-  }
-  if (/^[a-z][a-z0-9+.-]*:\/\//i.test(spec)) {
-    try {
-      const url = new URL(spec);
-      return { host: url.hostname, repoPath: url.pathname.replace(/^\/+/, "") };
-    } catch {
-      return undefined;
-    }
-  }
-  const slashIndex = spec.indexOf("/");
-  return slashIndex < 0
-    ? undefined
-    : { host: spec.slice(0, slashIndex), repoPath: spec.slice(slashIndex + 1) };
-}
-
-function gitPackagePath(source: string): { host: string; repoPath: string } | undefined {
-  const spec = source.slice(4).trim();
-  if (spec.length === 0) {
-    return undefined;
-  }
-  const parsed = gitLocation(spec);
-  if (parsed === undefined) {
-    return undefined;
-  }
-  const repoPath = stripGitRef(parsed.repoPath)
-    .replace(/\.git$/, "")
-    .replace(/^\/+/, "");
-  if (
-    !isSafePackagePath(parsed.host) ||
-    !isSafePackagePath(repoPath) ||
-    repoPath.split(/[\\/]/).length < 2
-  ) {
-    return undefined;
-  }
-  return { host: parsed.host, repoPath };
-}
-
-function settingsPackageRoot(source: string, baseDir: string): string | undefined {
-  const trimmed = source.trim();
-  if (trimmed.length === 0) {
-    return undefined;
-  }
-  if (trimmed.startsWith("git:")) {
-    const parsed = gitPackagePath(trimmed);
-    return parsed === undefined
-      ? undefined
-      : path.join(baseDir, "git", parsed.host, parsed.repoPath);
-  }
-  if (trimmed.startsWith("npm:")) {
-    const name = npmPackageName(trimmed);
-    return name === undefined ? undefined : path.join(baseDir, "npm", "node_modules", name);
-  }
-  return localPackageRoot(trimmed, baseDir);
-}
-
-function localPackageRoot(trimmed: string, baseDir: string): string | undefined {
-  const normalized = trimmed.startsWith("file:") ? trimmed.slice(5) : trimmed;
-  if (normalized === "~") {
-    return os.homedir();
-  }
-  if (normalized.startsWith("~/")) {
-    return path.join(os.homedir(), normalized.slice(2));
-  }
-  if (path.isAbsolute(normalized)) {
-    return normalized;
-  }
-  return normalized === "." ||
-    normalized === ".." ||
-    normalized.startsWith("./") ||
-    normalized.startsWith("../")
-    ? path.resolve(baseDir, normalized)
-    : undefined;
-}
-
-function settingsPaths(
-  cwd: string,
-  agentDir: string,
-  projectTrusted: boolean,
-  packages: boolean,
-): SkillSearchPath[] {
-  const files = [
-    { base: path.join(cwd, CONFIG_DIR), source: packages ? "project-package" : "project-settings" },
-    { base: agentDir, source: packages ? "user-package" : "user-settings" },
-  ] satisfies { base: string; source: SkillSource }[];
-  const results: SkillSearchPath[] = [];
-  for (const { base, source } of files) {
-    if (!projectTrusted && source.startsWith("project-")) {
-      continue;
-    }
-    const settings = readJson(path.join(base, "settings.json"), "skills settings file");
-    if (!isConfigObject(settings)) {
-      continue;
-    }
-    const entries = packages ? settings.packages : settings.skills;
-    if (!Array.isArray(entries)) {
-      continue;
-    }
-    results.push(
-      ...entries.flatMap((entry: unknown) => settingEntryPaths(entry, base, source, packages)),
-    );
-  }
-  return results;
-}
-
-function settingEntryPaths(
-  entry: unknown,
-  base: string,
-  source: SkillSource,
-  packages: boolean,
-): SkillSearchPath[] {
-  if (packages) {
-    let packageSource: unknown = entry;
-    if (isConfigObject(entry)) {
-      packageSource = entry.source;
-    }
-    if (typeof packageSource !== "string" || packageSource.length === 0) {
-      return [];
-    }
-    const root = settingsPackageRoot(packageSource, base);
-    return root === undefined ? [] : extractSkillPaths(root, source);
-  }
-  if (typeof entry !== "string") {
-    return [];
-  }
-  const resolved = entry.startsWith("~/")
-    ? path.join(os.homedir(), entry.slice(2))
-    : path.resolve(base, entry);
-  return [{ path: resolved, source }];
-}
-
-export function buildSkillPaths(
-  cwd: string,
-  agentDir: string,
-  projectTrusted: boolean,
-): SkillSearchPath[] {
-  const projectPaths: SkillSearchPath[] = projectTrusted
-    ? [
-        { path: path.join(cwd, CONFIG_DIR, "skills"), source: "project" },
-        { path: path.join(cwd, ".agents", "skills"), source: "project" },
-      ]
-    : [];
-  const paths: SkillSearchPath[] = [
-    ...projectPaths,
-    ...installedPackagePaths(cwd, agentDir, projectTrusted),
-    ...settingsPaths(cwd, agentDir, projectTrusted, true),
-    ...(projectTrusted ? extractSkillPaths(cwd, "project-package") : []),
-    ...settingsPaths(cwd, agentDir, projectTrusted, false),
-    { path: path.join(agentDir, "skills"), source: "user" },
-    { path: path.join(os.homedir(), ".agents", "skills"), source: "user" },
-  ];
-  const deduped = new Map<string, SkillSearchPath>();
-  for (const entry of paths) {
-    const resolvedPath = path.resolve(entry.path);
-    if (!deduped.has(resolvedPath)) {
-      deduped.set(resolvedPath, { path: resolvedPath, source: entry.source });
-    }
-  }
-  return [...deduped.values()];
-}

package/src/agents/skill-types.ts

@@ -1,31 +0,0 @@
-/** Caller-owned skill metadata shared by discovery and content resolution. */
-export type SkillSource =
-  | "project"
-  | "user"
-  | "project-package"
-  | "user-package"
-  | "project-settings"
-  | "user-settings"
-  | "extension"
-  | "builtin"
-  | "unknown";
-export interface ResolvedSkill {
-  readonly name: string;
-  readonly path: string;
-  readonly content: string;
-  readonly source: SkillSource;
-}
-export interface CachedSkillEntry {
-  readonly name: string;
-  readonly filePath: string;
-  readonly source: SkillSource;
-  readonly description?: string;
-  readonly order: number;
-}
-export interface SkillSearchPath {
-  readonly path: string;
-  readonly source: SkillSource;
-}
-export interface SkillDiscoveryOptions {
-  readonly projectTrusted?: boolean;
-}

package/src/agents/skills.ts

@@ -1,179 +0,0 @@
-import * as path from "node:path";
-import { getAgentDir } from "../shared/agent-dir.ts";
-import { buildSkillPaths } from "./skill-search-paths.ts";
-import { collectFilesystemSkills, readSkill } from "./skill-files.ts";
-import type {
-  SkillSource,
-  ResolvedSkill,
-  CachedSkillEntry,
-  SkillDiscoveryOptions,
-} from "./skill-types.ts";
-export type { SkillSource } from "./skill-types.ts";
-
-const SUBAGENT_ORCHESTRATION_SKILL = "pi-subagents";
-const LOAD_SKILLS_CACHE_TTL_MS = 5000;
-const SOURCE_PRIORITY: Readonly<Record<SkillSource, number>> = {
-  project: 700,
-  "project-settings": 650,
-  "project-package": 600,
-  user: 300,
-  "user-settings": 250,
-  "user-package": 200,
-  extension: 150,
-  builtin: 100,
-  unknown: 0,
-};
-let loadSkillsCache: {
-  cwd: string;
-  agentDir: string;
-  projectTrusted: boolean;
-  skills: CachedSkillEntry[];
-  timestamp: number;
-} | null = null;
-
-function chooseHigherPrioritySkill(
-  existing: CachedSkillEntry | undefined,
-  candidate: CachedSkillEntry,
-): CachedSkillEntry {
-  if (existing === undefined) {
-    return candidate;
-  }
-  const existingPriority = SOURCE_PRIORITY[existing.source];
-  const candidatePriority = SOURCE_PRIORITY[candidate.source];
-  if (candidatePriority > existingPriority) {
-    return candidate;
-  }
-  if (candidatePriority < existingPriority) {
-    return existing;
-  }
-  return candidate.order < existing.order ? candidate : existing;
-}
-
-function getCachedSkills(cwd: string, projectTrusted = true): CachedSkillEntry[] {
-  const now = Date.now();
-  const agentDir = getAgentDir();
-  if (
-    loadSkillsCache !== null &&
-    loadSkillsCache.cwd === cwd &&
-    loadSkillsCache.agentDir === agentDir &&
-    loadSkillsCache.projectTrusted === projectTrusted &&
-    now - loadSkillsCache.timestamp < LOAD_SKILLS_CACHE_TTL_MS
-  ) {
-    return loadSkillsCache.skills;
-  }
-  const loaded = collectFilesystemSkills(
-    cwd,
-    agentDir,
-    buildSkillPaths(cwd, agentDir, projectTrusted),
-  );
-  const deduped = new Map<string, CachedSkillEntry>();
-  for (const entry of loaded) {
-    deduped.set(entry.name, chooseHigherPrioritySkill(deduped.get(entry.name), entry));
-  }
-  const skills = [...deduped.values()].sort((a, b) => a.order - b.order);
-  loadSkillsCache = { cwd, agentDir, projectTrusted, skills, timestamp: now };
-  return skills;
-}
-
-export function resolveSkillPath(
-  skillName: string,
-  cwd: string,
-  options: SkillDiscoveryOptions = {},
-): { path: string; source: SkillSource } | undefined {
-  const skill = getCachedSkills(cwd, options.projectTrusted ?? true).find(
-    (entry) => entry.name === skillName,
-  );
-  return skill === undefined ? undefined : { path: skill.filePath, source: skill.source };
-}
-
-export function resolveSkills(
-  skillNames: readonly string[],
-  cwd: string,
-  options: SkillDiscoveryOptions = {},
-): { resolved: ResolvedSkill[]; missing: string[] } {
-  const resolved: ResolvedSkill[] = [];
-  const missing: string[] = [];
-  for (const name of skillNames) {
-    const trimmed = name.trim();
-    if (trimmed.length === 0) {
-      continue;
-    }
-    const location =
-      trimmed === SUBAGENT_ORCHESTRATION_SKILL
-        ? undefined
-        : resolveSkillPath(trimmed, cwd, options);
-    const skill =
-      location === undefined ? undefined : readSkill(trimmed, location.path, location.source);
-    if (skill === undefined) {
-      missing.push(trimmed);
-    } else {
-      resolved.push(skill);
-    }
-  }
-  return { resolved, missing };
-}
-
-export function resolveSkillsWithFallback(
-  skillNames: readonly string[],
-  primaryCwd: string,
-  fallbackCwd?: string,
-  options: SkillDiscoveryOptions = {},
-): { resolved: ResolvedSkill[]; missing: string[] } {
-  const primary = resolveSkills(skillNames, primaryCwd, options);
-  if (
-    fallbackCwd === undefined ||
-    fallbackCwd.length === 0 ||
-    primary.missing.length === 0 ||
-    path.resolve(primaryCwd) === path.resolve(fallbackCwd)
-  ) {
-    return primary;
-  }
-  const fallback = resolveSkills(primary.missing, fallbackCwd, options);
-  return { resolved: [...primary.resolved, ...fallback.resolved], missing: fallback.missing };
-}
-
-export function buildSkillInjection(skills: readonly ResolvedSkill[]): string {
-  return skills
-    .map((skill) => `<skill name="${skill.name}">\n${skill.content}\n</skill>`)
-    .join("\n\n");
-}
-
-function normalizedNames(input: readonly string[]): string[] {
-  return [...new Set(input.map((name) => name.trim()).filter((name) => name.length > 0))];
-}
-
-export function normalizeSkillInput(
-  input: string | readonly string[] | boolean | undefined,
-): string[] | false | undefined {
-  if (input === false) {
-    return false;
-  }
-  if (input === true || input === undefined) {
-    return undefined;
-  }
-  if (typeof input !== "string") {
-    return normalizedNames(input);
-  }
-  const trimmed = input.trim();
-  if (trimmed.startsWith("[")) {
-    try {
-      const parsed: unknown = JSON.parse(trimmed);
-      if (Array.isArray(parsed) && parsed.every((item: unknown) => typeof item === "string")) {
-        return normalizedNames(parsed);
-      }
-    } catch {
-      // Invalid JSON keeps the historical comma-separated input fallback.
-    }
-  }
-  return normalizedNames(input.split(","));
-}
-
-export function discoverAvailableSkills(
-  cwd: string,
-  options: SkillDiscoveryOptions = {},
-): Array<{ name: string; source: SkillSource; description?: string }> {
-  return getCachedSkills(cwd, options.projectTrusted ?? true)
-    .filter((skill) => skill.name !== SUBAGENT_ORCHESTRATION_SKILL)
-    .map((skill) => ({ name: skill.name, source: skill.source, description: skill.description }))
-    .sort((a, b) => a.name.localeCompare(b.name));
-}