@lumea-labs/skills-polpo 0.1.0

package/README.md

@@ -0,0 +1,21 @@
+# @lumea-labs/skills-polpo
+
+Tier 2 wiring of @lumea-labs/skills to the Polpo skills API.
+
+## Install
+
+```bash
+npm install @lumea-labs/skills-polpo
+```
+
+## Usage
+
+```tsx
+import { /* … */ } from "@lumea-labs/skills-polpo";
+```
+
+See the [Lumea Agents repo](https://github.com/Lumea-Technologies/lumea-agents/tree/main/packages/skills-polpo) for the full source and a playground example.
+
+## License
+
+Apache-2.0

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { UsePolpoSkillsAdapterReturn, usePolpoSkillsAdapter } from './use-polpo-skills-adapter.js';
+export { PolpoSkills, PolpoSkillsProps } from './polpo-skills.js';
+export { mapLoadedSkill, mapPolpoSkill } from './map-polpo-skill.js';
+import '@lumea-labs/skills';
+import 'react';
+import '@polpo-ai/sdk';

package/dist/index.js

@@ -0,0 +1,11 @@
+import {
+  usePolpoSkillsAdapter
+} from "./use-polpo-skills-adapter";
+import { PolpoSkills } from "./polpo-skills";
+import { mapPolpoSkill, mapLoadedSkill } from "./map-polpo-skill";
+export {
+  PolpoSkills,
+  mapLoadedSkill,
+  mapPolpoSkill,
+  usePolpoSkillsAdapter
+};

package/dist/map-polpo-skill.d.ts

@@ -0,0 +1,7 @@
+import { LoadedSkill, SkillWithAssignment, SkillInfo } from '@polpo-ai/sdk';
+import { Skill } from '@lumea-labs/skills';
+
+declare function mapPolpoSkill(s: SkillWithAssignment | SkillInfo): Skill;
+declare function mapLoadedSkill(loaded: LoadedSkill, base?: Skill): Skill;
+
+export { mapLoadedSkill, mapPolpoSkill };

package/dist/map-polpo-skill.js

@@ -0,0 +1,34 @@
+function mapScope(source) {
+  switch (source) {
+    case "project":
+      return "project";
+    case "global":
+    case "home":
+      return "personal";
+    case "polpo":
+    case "claude":
+      return "plugin";
+  }
+}
+function mapPolpoSkill(s) {
+  const tags = s.tags ?? [];
+  const assignedTo = "assignedTo" in s && Array.isArray(s.assignedTo) ? s.assignedTo : void 0;
+  return {
+    id: s.name,
+    name: s.name,
+    description: s.description,
+    tags: s.category ? [s.category, ...tags] : tags,
+    installPath: s.path,
+    installed: true,
+    enabled: assignedTo ? assignedTo.length > 0 : void 0,
+    scope: mapScope(s.source)
+  };
+}
+function mapLoadedSkill(loaded, base) {
+  const mapped = base ?? mapPolpoSkill(loaded);
+  return { ...mapped, readme: loaded.content };
+}
+export {
+  mapLoadedSkill,
+  mapPolpoSkill
+};

package/dist/polpo-skills.d.ts

@@ -0,0 +1,30 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { SkillsLabels, SkillsQuery } from '@lumea-labs/skills';
+
+interface PolpoSkillsProps {
+    labels?: Partial<SkillsLabels>;
+    initialQuery?: SkillsQuery;
+    autoLoad?: boolean;
+    autoLoadInstalled?: boolean;
+    children: ReactNode;
+}
+/**
+ * Convenience wrapper: builds a Polpo-wired `SkillsAdapter` and mounts
+ * `<SkillsProvider>` with it. Use this when you don't need the adapter
+ * outside the tree — otherwise call `usePolpoSkillsAdapter()` and wire
+ * `<SkillsProvider>` yourself.
+ *
+ *   <PolpoSkills>
+ *     <SkillsSearchBar />
+ *     <SkillsList onOpenSkill={(s) => router.push(`/skills/${s.id}`)} />
+ *   </PolpoSkills>
+ *
+ * Internally a `<PolpoSkillsSync>` mounts inside the provider and
+ * republishes a refresh whenever Polpo's `useSkills` data changes —
+ * the provider only auto-loads once, so without this the cached list
+ * stays empty if Polpo's fetch resolves after the first render.
+ */
+declare function PolpoSkills({ labels, initialQuery, autoLoad, autoLoadInstalled, children, }: PolpoSkillsProps): react.JSX.Element;
+
+export { PolpoSkills, type PolpoSkillsProps };

package/dist/polpo-skills.js

@@ -0,0 +1,43 @@
+"use client";
+import { useEffect } from "react";
+import {
+  SkillsProvider,
+  useSkills as useSkillsPackage
+} from "@lumea-labs/skills";
+import { usePolpoSkillsAdapter } from "./use-polpo-skills-adapter";
+function PolpoSkills({
+  labels,
+  initialQuery,
+  autoLoad,
+  autoLoadInstalled,
+  children
+}) {
+  const { adapter, skills } = usePolpoSkillsAdapter();
+  return /* @__PURE__ */ React.createElement(
+    SkillsProvider,
+    {
+      adapter,
+      labels,
+      initialQuery,
+      autoLoad,
+      autoLoadInstalled
+    },
+    /* @__PURE__ */ React.createElement(PolpoSkillsSync, { polpoSkills: skills }),
+    children
+  );
+}
+function PolpoSkillsSync({ polpoSkills }) {
+  const { actions } = useSkillsPackage();
+  const key = polpoSkills.map((s) => s.id).join("|");
+  useEffect(() => {
+    const t = setTimeout(() => {
+      void actions.refresh();
+      void actions.refreshInstalled();
+    }, 0);
+    return () => clearTimeout(t);
+  }, [key]);
+  return null;
+}
+export {
+  PolpoSkills
+};

package/dist/use-polpo-skills-adapter.d.ts

@@ -0,0 +1,53 @@
+import { SkillsAdapter, Skill } from '@lumea-labs/skills';
+
+interface UsePolpoSkillsAdapterReturn {
+    adapter: SkillsAdapter;
+    skills: Skill[];
+    isLoading: boolean;
+    error: Error | null;
+    refetch: () => Promise<void>;
+    /** Pending flags for the currently in-flight mutation, surfaced so
+     *  consumers can disable buttons without re-deriving them. */
+    isCreating: boolean;
+    isInstalling: boolean;
+    isDeleting: boolean;
+    /** Polpo-specific assignment ops — not part of the
+     *  `@lumea/skills` adapter contract because that package doesn't
+     *  yet model agent-level assignments. Surface them here so
+     *  consumers (e.g. an agent detail page) can wire UI on top. */
+    assignSkill: (skillName: string, agentName: string) => Promise<void>;
+    unassignSkill: (skillName: string, agentName: string) => Promise<void>;
+    isAssigning: boolean;
+    isUnassigning: boolean;
+}
+/**
+ * Tier-2 wiring: build a `SkillsAdapter` from `@polpo-ai/react`'s
+ * `useSkills` hook + the `PolpoClient` (for content fetching).
+ *
+ * The mapping is opinionated:
+ *
+ *  - `listSkills` and `listInstalled` both return Polpo's local pool.
+ *    There is no separate "registry" surface — Polpo doesn't expose
+ *    one — so the browse view shows installed skills filtered by
+ *    `query.search` / `query.tags`.
+ *
+ *  - `installSkill(skill)` reads the source from
+ *    `skill.repositoryUrl ?? skill.repository ?? skill.installPath`
+ *    and forwards to Polpo's `installSkills(source)`. Skills coming
+ *    out of `listSkills` set `installPath` so re-installing is a
+ *    no-op (`force: true` would be the consumer's call).
+ *
+ *  - `getSkill(id)` does a deep fetch via
+ *    `client.getSkillContent(name)` to populate `readme`.
+ *
+ *  - `createSkill(input)` maps the lumea wizard shape to Polpo's
+ *    `CreateSkillRequest`. `frontmatter.allowedTools` flows through;
+ *    `scope` is dropped (Polpo decides where to write).
+ *
+ *  - `toggleSkill` is intentionally not implemented — Polpo's enable
+ *    state is per-agent assignment, not per-skill. Use the dedicated
+ *    `assignSkill` / `unassignSkill` returned alongside the adapter.
+ */
+declare function usePolpoSkillsAdapter(): UsePolpoSkillsAdapterReturn;
+
+export { type UsePolpoSkillsAdapterReturn, usePolpoSkillsAdapter };

package/dist/use-polpo-skills-adapter.js

@@ -0,0 +1,185 @@
+"use client";
+import { useCallback, useMemo } from "react";
+import { usePolpo, useSkills } from "@polpo-ai/react";
+import { mapLoadedSkill, mapPolpoSkill } from "./map-polpo-skill";
+function usePolpoSkillsAdapter() {
+  const { client } = usePolpo();
+  const {
+    skills: polpoSkills,
+    isLoading,
+    error,
+    refetch,
+    createSkill: polpoCreate,
+    isCreating,
+    installSkills,
+    isInstalling,
+    deleteSkill,
+    isDeleting,
+    assignSkill: polpoAssign,
+    unassignSkill: polpoUnassign,
+    isAssigning,
+    isUnassigning
+  } = useSkills();
+  const skills = useMemo(
+    () => polpoSkills.map(mapPolpoSkill),
+    [polpoSkills]
+  );
+  const matchesQuery = useCallback(
+    (skill, q) => {
+      if (!q) return true;
+      if (q.search) {
+        const needle = q.search.toLowerCase();
+        const hay = `${skill.name} ${skill.description ?? ""}`.toLowerCase();
+        if (!hay.includes(needle)) return false;
+      }
+      if (q.tags && q.tags.length > 0) {
+        const have = new Set((skill.tags ?? []).map((t) => t.toLowerCase()));
+        const want = q.tags.map((t) => t.toLowerCase());
+        if (!want.every((t) => have.has(t))) return false;
+      }
+      if (q.installedOnly && !skill.installed) return false;
+      return true;
+    },
+    []
+  );
+  const sortSkills = useCallback(
+    (list, sort) => {
+      const out = [...list];
+      switch (sort) {
+        case "alphabetical":
+          out.sort((a, b) => a.name.localeCompare(b.name));
+          break;
+        case "popular":
+        case "trending":
+          out.sort(
+            (a, b) => (b.installs ?? 0) - (a.installs ?? 0) || a.name.localeCompare(b.name)
+          );
+          break;
+        case "recent":
+          out.sort(
+            (a, b) => (b.updatedAt ?? "").localeCompare(a.updatedAt ?? "")
+          );
+          break;
+        default:
+          break;
+      }
+      return out;
+    },
+    []
+  );
+  const listSkills = useCallback(
+    async (q) => {
+      const filtered = skills.filter((s) => matchesQuery(s, q));
+      const sorted = sortSkills(filtered, q?.sort);
+      const offset = q?.offset ?? 0;
+      const limit = q?.limit ?? sorted.length;
+      return sorted.slice(offset, offset + limit);
+    },
+    [skills, matchesQuery, sortSkills]
+  );
+  const listInstalled = useCallback(async () => {
+    return skills;
+  }, [skills]);
+  const getSkill = useCallback(
+    async (id) => {
+      const base = skills.find((s) => s.id === id);
+      try {
+        const [loaded, listing] = await Promise.all([
+          client.getSkillContent(id),
+          // The skill folder lives at `installPath` (Polpo's `path`).
+          // Listing it gives us the file tree for `<SkillFileTree>`.
+          base?.installPath ? client.listFiles(base.installPath).catch(() => null) : Promise.resolve(null)
+        ]);
+        const files = listing?.entries?.map((e) => ({
+          path: e.name,
+          type: e.type,
+          size: e.size
+        })) ?? [];
+        return { ...mapLoadedSkill(loaded, base), files };
+      } catch {
+        return base ?? null;
+      }
+    },
+    [skills, client]
+  );
+  const installSkill = useCallback(
+    async (skill) => {
+      const source = skill.repositoryUrl ?? skill.repository ?? skill.installPath;
+      if (!source) {
+        throw new Error(
+          `Cannot install skill "${skill.id}" \u2014 no source (repositoryUrl, repository or installPath).`
+        );
+      }
+      await installSkills(source, { skillNames: [skill.name] });
+    },
+    [installSkills]
+  );
+  const uninstallSkill = useCallback(
+    async (id) => {
+      await deleteSkill(id);
+    },
+    [deleteSkill]
+  );
+  const createSkill = useCallback(
+    async (input) => {
+      const created = await polpoCreate({
+        name: input.name,
+        description: input.description,
+        content: input.body,
+        allowedTools: input.frontmatter.allowedTools
+      });
+      const fresh = skills.find((s) => s.name === created.name) ?? {
+        id: created.name,
+        name: created.name,
+        description: input.description,
+        installed: true,
+        installPath: created.path,
+        scope: input.scope,
+        tags: [],
+        frontmatter: input.frontmatter
+      };
+      return fresh;
+    },
+    [polpoCreate, skills]
+  );
+  const adapter = useMemo(
+    () => ({
+      listSkills,
+      listInstalled,
+      getSkill,
+      installSkill,
+      uninstallSkill,
+      createSkill
+    }),
+    [listSkills, listInstalled, getSkill, installSkill, uninstallSkill, createSkill]
+  );
+  const assignSkill = useCallback(
+    async (skillName, agentName) => {
+      await polpoAssign(skillName, agentName);
+    },
+    [polpoAssign]
+  );
+  const unassignSkill = useCallback(
+    async (skillName, agentName) => {
+      await polpoUnassign(skillName, agentName);
+    },
+    [polpoUnassign]
+  );
+  return {
+    adapter,
+    skills,
+    isLoading,
+    error,
+    refetch,
+    isCreating,
+    isInstalling,
+    isDeleting,
+    assignSkill,
+    unassignSkill,
+    isAssigning,
+    isUnassigning
+  };
+}
+export {
+  usePolpoSkillsAdapter
+};

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@lumea-labs/skills-polpo",
+  "version": "0.1.0",
+  "description": "Tier 2 wiring of @lumea-labs/skills to the Polpo skills API.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "peerDependencies": {
+    "react": ">=19",
+    "lucide-react": "*",
+    "@lumea-labs/skills": "*",
+    "@polpo-ai/react": ">=0.6.0",
+    "@polpo-ai/sdk": ">=0.6.0"
+  },
+  "license": "Apache-2.0",
+  "module": "./dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "build:watch": "tsup --watch",
+    "clean": "rm -rf dist"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Lumea-Technologies/lumea-agents.git",
+    "directory": "packages/skills-polpo"
+  },
+  "homepage": "https://github.com/Lumea-Technologies/lumea-agents/tree/main/packages/skills-polpo"
+}