@mrclrchtr/supi-skills 4.7.0

package/node_modules/@mrclrchtr/supi-core/src/terminal.ts

@@ -0,0 +1,60 @@
+/**
+ * Shared terminal title formatting and signaling utilities.
+ *
+ * Centralized place for pi title convention (π prefix), completion (✓)
+ * and waiting (●) indicators, and the audible terminal bell.
+ */
+import path from "node:path";
+
+/** Unicode checkmark shown when the agent finishes a turn. */
+export const DONE_SYMBOL = "\u2713";
+/** Unicode dot shown when waiting for user input. */
+export const WAITING_SYMBOL = "\u25CF";
+
+/** Minimal UI surface needed for title operations. */
+export interface TitleTarget {
+  ui: {
+    setTitle?(title: string): void;
+  };
+}
+
+/**
+ * Format pi's canonical terminal title from session name and cwd.
+ * Falls back gracefully when either is missing.
+ *
+ * @example
+ *   formatTitle("my-session", "/home/projects/foo")  // "π - my-session - foo"
+ *   formatTitle(undefined, "/home/projects/foo")      // "π - foo"
+ *   formatTitle("my-session")                         // "π - my-session"
+ *   formatTitle()                                     // "π"
+ */
+export function formatTitle(sessionName?: string, cwd?: string): string {
+  const base = cwd ? path.basename(cwd) : undefined;
+  if (sessionName && base) return `π - ${sessionName} - ${base}`;
+  if (sessionName) return `π - ${sessionName}`;
+  if (base) return `π - ${base}`;
+  return "π";
+}
+
+/** Sound the audible terminal bell (ASCII BEL). */
+export function signalBell(): void {
+  process.stdout.write("\x07");
+}
+
+/**
+ * Set the terminal title to indicate the agent is waiting for user input.
+ * Prefixes with ● and sounds the terminal bell.
+ */
+export function signalWaiting(ctx: TitleTarget, title: string): void {
+  ctx.ui.setTitle?.(`${WAITING_SYMBOL}  ${title}`);
+  signalBell();
+}
+
+/**
+ * Set the terminal title to indicate the agent turn has completed.
+ * Prefixes with ✓ and sounds the terminal bell.
+ */
+export function signalDone(ctx: TitleTarget, title: string): void {
+  ctx.ui.setTitle?.(`${DONE_SYMBOL} ${title}`);
+  signalBell();
+}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@mrclrchtr/supi-skills",
+  "version": "4.7.0",
+  "description": "Scoped skill controls and skill input shortcuts for PI",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mrclrchtr/supi.git",
+    "directory": "packages/supi-skills"
+  },
+  "homepage": "https://github.com/mrclrchtr/supi/tree/main/packages/supi-skills#readme",
+  "bugs": {
+    "url": "https://github.com/mrclrchtr/supi/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-coding-agent",
+    "pi-extension",
+    "skills",
+    "skill-settings",
+    "shortcuts"
+  ],
+  "type": "module",
+  "files": [
+    "src/**/*.ts",
+    "README.md"
+  ],
+  "dependencies": {
+    "@mrclrchtr/supi-core": "workspace:*"
+  },
+  "bundledDependencies": [
+    "@mrclrchtr/supi-core"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "@earendil-works/pi-tui": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@mrclrchtr/supi-test-utils": "workspace:*",
+    "vitest": "4.1.10"
+  },
+  "pi": {
+    "extensions": [
+      "./src/extension.ts"
+    ],
+    "image": "https://raw.githubusercontent.com/mrclrchtr/supi/main/packages/supi-skills/assets/social-preview.png"
+  },
+  "exports": {
+    "./extension": "./src/extension.ts",
+    "./package.json": "./package.json"
+  }
+}

package/src/extension.ts

@@ -0,0 +1,9 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import skillSettings from "./skill-settings.ts";
+import skillShortcut from "./skill-shortcut.ts";
+
+/** Register scoped skill controls and `$skill-name` input shortcuts. */
+export default function supiSkills(pi: ExtensionAPI): void {
+  skillShortcut(pi);
+  skillSettings(pi);
+}

package/src/skill-catalog.ts

@@ -0,0 +1,153 @@
+import { realpathSync } from "node:fs";
+import { resolve } from "node:path";
+import {
+  type ExtensionCommandContext,
+  type ExtensionContext,
+  loadSkills,
+  type ResolvedResource,
+  type Skill,
+} from "@earendil-works/pi-coding-agent";
+import type { SettingsScope } from "@mrclrchtr/supi-core/settings";
+
+export interface SkillSource {
+  skill: Skill;
+  resource?: ResolvedResource;
+  runtime: boolean;
+}
+
+export interface SkillRecord {
+  name: string;
+  description: string;
+  sources: SkillSource[];
+  activeSkill?: Skill;
+}
+
+export type SkillCatalog = Map<string, SkillRecord>;
+
+function canonicalPath(path: string): string {
+  try {
+    return realpathSync(path);
+  } catch {
+    return resolve(path);
+  }
+}
+
+export function skillSourceIdentity(skill: Skill): string {
+  return [
+    canonicalPath(skill.filePath),
+    skill.sourceInfo.source,
+    skill.sourceInfo.scope,
+    skill.sourceInfo.origin,
+  ].join("\0");
+}
+
+function hasStaticProvenance(skill: Skill, source: SkillSource): boolean {
+  const resource = source.resource;
+  if (!resource) return false;
+  const scope = resource.metadata.scope === "project" ? "project" : "user";
+  return (
+    skill.sourceInfo.source === resource.metadata.source &&
+    skill.sourceInfo.scope === scope &&
+    skill.sourceInfo.origin === resource.metadata.origin
+  );
+}
+
+function addSource(catalog: SkillCatalog, source: SkillSource): void {
+  const current = catalog.get(source.skill.name);
+  if (current) {
+    current.sources.push(source);
+    return;
+  }
+  catalog.set(source.skill.name, {
+    name: source.skill.name,
+    description: source.skill.description,
+    sources: [source],
+  });
+}
+
+/** Load every resolved resource, including resources that PI currently filters out. */
+export function buildSkillCatalog(
+  resources: ResolvedResource[],
+  cwd: string,
+  agentDir: string,
+): SkillCatalog {
+  const catalog: SkillCatalog = new Map();
+  for (const resource of resources) {
+    const result = loadSkills({
+      cwd,
+      agentDir,
+      skillPaths: [resource.path],
+      includeDefaults: false,
+    });
+    for (const skill of result.skills) {
+      addSource(catalog, { skill, resource, runtime: false });
+    }
+  }
+  return catalog;
+}
+
+function cloneCatalog(catalog: SkillCatalog): SkillCatalog {
+  return new Map(
+    Array.from(catalog, ([name, record]) => [
+      name,
+      { ...record, sources: record.sources.map((source) => ({ ...source })) },
+    ]),
+  );
+}
+
+function contextSkills(ctx?: ExtensionContext): Skill[] {
+  const commandCtx = ctx as Partial<ExtensionCommandContext> | undefined;
+  return commandCtx?.getSystemPromptOptions?.().skills ?? [];
+}
+
+/**
+ * Reconcile PI's active winner with resolved static sources.
+ *
+ * A pending identity suppresses only the stale pre-reload static winner. A
+ * different public provenance remains a runtime source and prevents full disable.
+ */
+function mergeRuntimeSkill(
+  catalog: SkillCatalog,
+  skill: Skill,
+  pendingDisabled: ReadonlyMap<string, ReadonlySet<string>>,
+): void {
+  const record = catalog.get(skill.name);
+  if (!record) {
+    addSource(catalog, { skill, runtime: true });
+    const added = catalog.get(skill.name);
+    if (added) added.activeSkill = skill;
+    return;
+  }
+  if (pendingDisabled.get(skill.name)?.has(skillSourceIdentity(skill))) return;
+  const path = canonicalPath(skill.filePath);
+  const staticSource = record.sources.find(
+    (source) => source.resource && canonicalPath(source.skill.filePath) === path,
+  );
+  if (staticSource && hasStaticProvenance(skill, staticSource)) {
+    if (staticSource.resource?.enabled) record.activeSkill = skill;
+    else {
+      record.activeSkill = skill;
+      record.sources.push({ skill, runtime: true });
+    }
+    return;
+  }
+  // ponytail: PI exposes only winning runtime skills; use an aggregate resource API if PI adds one.
+  record.activeSkill = skill;
+  record.sources.push({ skill, runtime: true });
+}
+
+/** Merge skills that runtime resource events added outside PI's configurable catalog. */
+export function mergeRuntimeSkills(
+  base: SkillCatalog,
+  ctx: ExtensionContext | undefined,
+  scope: SettingsScope,
+  pendingDisabled: ReadonlyMap<string, ReadonlySet<string>> = new Map(),
+): SkillCatalog {
+  const catalog = cloneCatalog(base);
+  for (const skill of contextSkills(ctx)) {
+    if (scope !== "global" || skill.sourceInfo.scope !== "project") {
+      mergeRuntimeSkill(catalog, skill, pendingDisabled);
+    }
+  }
+  return catalog;
+}

package/src/skill-load-settings.ts

@@ -0,0 +1,305 @@
+import { homedir } from "node:os";
+import { basename, isAbsolute, join, posix, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  CONFIG_DIR_NAME,
+  type PackageSource,
+  type ResolvedResource,
+  type SettingsManager,
+} from "@earendil-works/pi-coding-agent";
+import type { SettingsScope } from "@mrclrchtr/supi-core/settings";
+
+export type SkillLoadOverride = "load" | "unload" | "inherit";
+
+type PackageConfig = Exclude<PackageSource, string>;
+
+interface SkillLoadContext {
+  settingsManager: SettingsManager;
+  scope: SettingsScope;
+  cwd: string;
+  agentDir: string;
+}
+
+const FILTER_PREFIXES = new Set(["!", "+", "-"]);
+const PACKAGE_FILTER_KEYS = ["extensions", "skills", "prompts", "themes"] as const;
+
+function normalizeExactTarget(target: string): string {
+  const normalized = target.replaceAll("\\", "/");
+  return normalized.startsWith("./") ? normalized.slice(2) : normalized;
+}
+
+function stripFilterPrefix(entry: string): string {
+  const target = FILTER_PREFIXES.has(entry[0] ?? "") ? entry.slice(1) : entry;
+  return normalizeExactTarget(target);
+}
+
+function exactTargets(paths: string[]): Set<string> {
+  const targets = new Set(paths.map(normalizeExactTarget));
+  for (const path of paths) {
+    if (basename(path) === "SKILL.md") targets.add(posix.dirname(normalizeExactTarget(path)));
+  }
+  return targets;
+}
+
+function isExactOverride(entry: string): boolean {
+  return entry.startsWith("+") || entry.startsWith("-");
+}
+
+function removeExactOverrides(entries: string[], targets: ReadonlySet<string>): string[] {
+  return entries.filter(
+    (entry) => !(isExactOverride(entry) && targets.has(stripFilterPrefix(entry))),
+  );
+}
+
+function sourceScope(resource: ResolvedResource): SettingsScope {
+  return resource.metadata.scope === "project" ? "project" : "global";
+}
+
+function scopeBaseDir(scope: SettingsScope, cwd: string, agentDir: string): string {
+  return scope === "project" ? join(cwd, CONFIG_DIR_NAME) : agentDir;
+}
+
+function resourcePattern(
+  resource: ResolvedResource,
+  scope: SettingsScope,
+  cwd: string,
+  agentDir: string,
+): string {
+  if (scope !== sourceScope(resource)) return resource.path;
+  const baseDir = resource.metadata.baseDir ?? scopeBaseDir(sourceScope(resource), cwd, agentDir);
+  return relative(baseDir, resource.path);
+}
+
+function topLevelTargets(
+  resource: ResolvedResource,
+  scope: SettingsScope,
+  cwd: string,
+  agentDir: string,
+): Set<string> {
+  const paths = [
+    resourcePattern(resource, scope, cwd, agentDir),
+    resource.path,
+    relative(scopeBaseDir(scope, cwd, agentDir), resource.path),
+  ];
+  if (resource.metadata.baseDir) paths.push(relative(resource.metadata.baseDir, resource.path));
+  return exactTargets(paths);
+}
+
+/**
+ * Replace only SuPi-managed exact overrides for one top-level resource.
+ * Broad patterns stay unchanged; inherited resources also receive a plain
+ * support path because PI applies project filters only to project resources.
+ */
+function updateTopLevelEntries(
+  entries: string[],
+  resource: ResolvedResource,
+  state: SkillLoadOverride,
+  context: SkillLoadContext,
+): string[] {
+  const { scope, cwd, agentDir } = context;
+  const pattern = resourcePattern(resource, scope, cwd, agentDir);
+  const targets = topLevelTargets(resource, scope, cwd, agentDir);
+  const inherited = scope === "project" && sourceScope(resource) === "global";
+  const hadOverride = entries.some(
+    (entry) => isExactOverride(entry) && targets.has(stripFilterPrefix(entry)),
+  );
+  const updated = removeExactOverrides(entries, targets);
+
+  if (state === "inherit") {
+    return inherited && hadOverride
+      ? updated.filter((entry) => normalizeExactTarget(entry) !== normalizeExactTarget(pattern))
+      : updated;
+  }
+  if (inherited && !updated.includes(pattern)) updated.push(pattern);
+  updated.push(`${state === "load" ? "+" : "-"}${pattern}`);
+  return updated;
+}
+
+function isLocalPackageSource(source: string): boolean {
+  const value = source.trim();
+  return !["npm:", "git:", "github:", "http:", "https:", "ssh:"].some((prefix) =>
+    value.startsWith(prefix),
+  );
+}
+
+function resolvePackageSource(source: string, baseDir: string): string {
+  const value = source.trim();
+  if (value.startsWith("file:")) return fileURLToPath(value);
+  if (value === "~") return homedir();
+  if (value.startsWith("~/") || value.startsWith("~\\")) {
+    return resolve(homedir(), value.slice(2));
+  }
+  return isAbsolute(value) ? resolve(value) : resolve(baseDir, value);
+}
+
+/** Match package identity with the scope-relative local-path rules used by PI. */
+function packageSourcesMatch(options: {
+  left: string;
+  leftScope: SettingsScope;
+  right: string;
+  rightScope: SettingsScope;
+  cwd: string;
+  agentDir: string;
+}): boolean {
+  const { left, leftScope, right, rightScope, cwd, agentDir } = options;
+  const leftIsLocal = isLocalPackageSource(left);
+  const rightIsLocal = isLocalPackageSource(right);
+  if (!leftIsLocal || !rightIsLocal) return !leftIsLocal && !rightIsLocal && left === right;
+  return (
+    resolvePackageSource(left, scopeBaseDir(leftScope, cwd, agentDir)) ===
+    resolvePackageSource(right, scopeBaseDir(rightScope, cwd, agentDir))
+  );
+}
+
+function packagePattern(resource: ResolvedResource): string {
+  return relative(resource.metadata.baseDir ?? resource.path, resource.path);
+}
+
+function packageTargets(resource: ResolvedResource): Set<string> {
+  return exactTargets([packagePattern(resource), resource.path]);
+}
+
+function createProjectPackageOverride(
+  resource: ResolvedResource,
+  cwd: string,
+  agentDir: string,
+): PackageConfig {
+  const source = resource.metadata.source;
+  if (!isLocalPackageSource(source)) return { source, autoload: false };
+  const absolute = resolvePackageSource(source, scopeBaseDir(sourceScope(resource), cwd, agentDir));
+  return {
+    source: relative(scopeBaseDir("project", cwd, agentDir), absolute) || ".",
+    autoload: false,
+  };
+}
+
+function findPackageIndex(
+  packages: PackageSource[],
+  resource: ResolvedResource,
+  context: SkillLoadContext,
+): number {
+  return packages.findIndex((entry) =>
+    packageSourcesMatch({
+      left: resource.metadata.source,
+      leftScope: sourceScope(resource),
+      right: typeof entry === "string" ? entry : entry.source,
+      rightScope: context.scope,
+      cwd: context.cwd,
+      agentDir: context.agentDir,
+    }),
+  );
+}
+
+function cleanPackageEntry(packages: PackageSource[], index: number, scope: SettingsScope): void {
+  const entry = packages[index];
+  if (!entry || typeof entry === "string") return;
+  const hasFilters = PACKAGE_FILTER_KEYS.some((key) => entry[key] !== undefined);
+  if (hasFilters) return;
+  if (scope === "project" && entry.autoload === false) packages.splice(index, 1);
+  else if (entry.autoload !== false) packages[index] = entry.source;
+}
+
+/**
+ * Apply one exact package-skill delta while preserving broad filters and
+ * explicit deny-all semantics. Project autoload:false entries remain deltas.
+ */
+function updatePackageEntries(
+  packages: PackageSource[],
+  resource: ResolvedResource,
+  state: SkillLoadOverride,
+  context: SkillLoadContext,
+): void {
+  let index = findPackageIndex(packages, resource, context);
+  if (index === -1) {
+    if (state === "inherit") return;
+    packages.push(createProjectPackageOverride(resource, context.cwd, context.agentDir));
+    index = packages.length - 1;
+  }
+
+  const current = packages[index];
+  if (!current) return;
+  const config: PackageConfig = typeof current === "string" ? { source: current } : { ...current };
+  packages[index] = config;
+  const pattern = packagePattern(resource);
+  const targets = packageTargets(resource);
+  const explicitDenyAll =
+    config.autoload !== false && config.skills !== undefined && config.skills.length === 0;
+  const entries = removeExactOverrides([...(config.skills ?? [])], targets);
+  if (state !== "inherit") {
+    if (explicitDenyAll) entries.push("!**");
+    entries.push(`${state === "load" ? "+" : "-"}${pattern}`);
+  }
+  config.skills = entries.length > 0 ? entries : explicitDenyAll ? [] : undefined;
+  cleanPackageEntry(packages, index, context.scope);
+}
+
+/** Update only exact PI skill filters and preserve broad user patterns. */
+export function updateSkillLoadOverrides(
+  input: SkillLoadContext & { resources: ResolvedResource[]; state: SkillLoadOverride },
+): void {
+  const { settingsManager, resources, scope, state } = input;
+  const relevant = resources.filter(
+    (resource) => scope === "project" || sourceScope(resource) === "global",
+  );
+  const settings =
+    scope === "project"
+      ? settingsManager.getProjectSettings()
+      : settingsManager.getGlobalSettings();
+
+  const topLevelResources = relevant.filter((item) => item.metadata.origin === "top-level");
+  if (topLevelResources.length > 0) {
+    let skillPaths = [...(settings.skills ?? [])];
+    for (const resource of topLevelResources) {
+      skillPaths = updateTopLevelEntries(skillPaths, resource, state, input);
+    }
+    if (scope === "project") settingsManager.setProjectSkillPaths(skillPaths);
+    else settingsManager.setSkillPaths(skillPaths);
+  }
+
+  const packageResources = relevant.filter((item) => item.metadata.origin === "package");
+  if (packageResources.length > 0) {
+    const packages = [...(settings.packages ?? [])];
+    for (const resource of packageResources) {
+      updatePackageEntries(packages, resource, state, input);
+    }
+    if (scope === "project") settingsManager.setProjectPackages(packages);
+    else settingsManager.setPackages(packages);
+  }
+}
+
+/** Return true when the selected scope has an exact load override for any source. */
+export function hasExactSkillLoadOverride(
+  input: SkillLoadContext & { resources: ResolvedResource[] },
+): boolean {
+  const { settingsManager, resources, scope, cwd, agentDir } = input;
+  const settings =
+    scope === "project"
+      ? settingsManager.getProjectSettings()
+      : settingsManager.getGlobalSettings();
+  const skillEntries = settings.skills ?? [];
+
+  for (const resource of resources.filter((item) => item.metadata.origin === "top-level")) {
+    const targets = topLevelTargets(resource, scope, cwd, agentDir);
+    if (
+      skillEntries.some((entry) => isExactOverride(entry) && targets.has(stripFilterPrefix(entry)))
+    ) {
+      return true;
+    }
+  }
+
+  const packages = settings.packages ?? [];
+  for (const resource of resources.filter((item) => item.metadata.origin === "package")) {
+    const index = findPackageIndex(packages, resource, input);
+    const entry = index >= 0 ? packages[index] : undefined;
+    if (!entry || typeof entry === "string") continue;
+    const targets = packageTargets(resource);
+    if (
+      (entry.skills ?? []).some(
+        (filter) => isExactOverride(filter) && targets.has(stripFilterPrefix(filter)),
+      )
+    ) {
+      return true;
+    }
+  }
+  return false;
+}