mirror of
https://github.com/alkimake/paperclip.git
synced 2026-06-14 01:50:39 +09:00
[codex] Add skills CLI and catalog management (#6782)
## Thinking Path > - Paperclip orchestrates AI agents for zero-human companies through company-scoped control-plane workflows. > - Agents need reusable, inspectable skills that can be installed, reset, audited, exported, and assigned without bespoke local setup. > - The existing skill truth model needed cleanup so bundled skills, optional catalog skills, runtime skills, and adapter-provided skills have clear provenance. > - Operators also need a practical CLI and board UI for discovering and managing company skills. > - This pull request adds the skills CLI, packaged skills catalog, company skills APIs, and catalog-aware board UI. > - The benefit is a more reusable Paperclip company setup where skills are portable, auditable, and easier for operators and agents to manage. ## What Changed - Added `paperclipai skills` CLI commands and coverage for catalog listing, installing, resetting, and inspecting company skills. - Added a packaged `@paperclipai/skills-catalog` workspace with bundled and optional skill content plus validation/build tests. - Added shared company-skill types and validators used across CLI, server, and UI contracts. - Added server catalog APIs/services for company skill catalog operations, reset semantics, audit behavior, and portability provenance. - Updated adapter skill handling so runtime/catalog provenance remains explicit across local adapters. - Added board UI support for browsing and managing catalog-backed company skills. - Updated docs for the skills CLI/catalog flow and the company skills Paperclip skill reference. - Rebased the branch onto current `paperclipai/paperclip:master`; no `pnpm-lock.yaml`, `.github/workflows`, or migration files are included in the final PR diff. ## Verification - Passed: `pnpm run preflight:workspace-links && pnpm exec vitest run cli/src/__tests__/skills.test.ts packages/skills-catalog/src/catalog-builder.test.ts packages/skills-catalog/src/shipped-catalog.test.ts packages/shared/src/validators/company-skill.test.ts packages/adapter-utils/src/server-utils.test.ts packages/plugins/create-paperclip-plugin/src/entrypoints.test.ts server/src/__tests__/company-skills-catalog-service.test.ts server/src/__tests__/company-skills-routes.test.ts server/src/__tests__/company-portability.test.ts`. - Passed: `pnpm exec vitest run server/src/__tests__/workspace-runtime.test.ts -t "default branch|origin/master|symbolic-ref"`. - Attempted: full `server/src/__tests__/workspace-runtime.test.ts`. Four provisioning tests failed while seeding an isolated worktree database from the local Paperclip instance because the local plugin schema dump contains a duplicate-column foreign key (`plugin_content_machine_18a7bc327b.content_case_signals`). The default-branch tests touched by the rebase conflict passed in the focused run above. - Checked final diff: no `pnpm-lock.yaml`, no `.github/workflows`, and no migration-file changes relative to `master`. ## Risks - Medium: this is a broad skills/catalog change touching CLI, server APIs, shared contracts, adapter skill sync, and UI. - Catalog validation and reset semantics need careful reviewer attention because they affect reusable company setup and portability. - No database migrations are included in this PR, so there is no migration ordering/idempotency risk in the final diff. - No lockfile is included by design; dependency resolution will be handled by the repository lockfile workflow. ## Model Used - OpenAI Codex coding agent based on GPT-5, running in Paperclip via the `codex_local` adapter with shell, git, GitHub CLI, and code-editing tool access. Exact hosted model build/context-window metadata is not exposed in this runtime. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have run targeted tests locally and documented the local workspace-runtime seed failure above - [x] I have added or updated tests where applicable - [x] If this change affects the UI, screenshots were intentionally omitted per PAP-10124 instructions; UI behavior is covered by tests and reviewer inspection - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing>
This commit is contained in:
Dotta
GitHub
parent
8da50dbcf8
commit
9eac727cf1
77 changed files with 9704 additions and 530 deletions
|
|
@ -6,6 +6,8 @@ import { describe, expect, it } from "vitest";
|
|||
import {
|
||||
applyPaperclipWorkspaceEnv,
|
||||
appendWithByteCap,
|
||||
buildPersistentSkillSnapshot,
|
||||
buildRuntimeMountedSkillSnapshot,
|
||||
buildInvocationEnvForLogs,
|
||||
DEFAULT_PAPERCLIP_AGENT_PROMPT_TEMPLATE,
|
||||
materializePaperclipSkillCopy,
|
||||
|
|
@ -205,6 +207,186 @@ describe("materializePaperclipSkillCopy", () => {
|
|||
});
|
||||
});
|
||||
|
||||
describe("adapter skill snapshots", () => {
|
||||
const requiredEntry = {
|
||||
key: "paperclipai/paperclip/paperclip",
|
||||
runtimeName: "paperclip",
|
||||
source: "/runtime/paperclip",
|
||||
required: true,
|
||||
requiredReason: "Required for Paperclip heartbeats.",
|
||||
};
|
||||
const optionalEntry = {
|
||||
key: "company/ascii-heart",
|
||||
runtimeName: "ascii-heart",
|
||||
source: "/runtime/ascii-heart",
|
||||
};
|
||||
|
||||
it("reports runtime-mounted adapters as configured or missing without install state", () => {
|
||||
const snapshot = buildRuntimeMountedSkillSnapshot({
|
||||
adapterType: "codex_local",
|
||||
availableEntries: [requiredEntry],
|
||||
desiredSkills: [requiredEntry.key, "missing-skill"],
|
||||
configuredDetail: "Mounted on next run.",
|
||||
});
|
||||
|
||||
expect(snapshot).toMatchObject({
|
||||
supported: true,
|
||||
mode: "ephemeral",
|
||||
desiredSkills: [requiredEntry.key, "missing-skill"],
|
||||
});
|
||||
expect(snapshot.entries).toEqual([
|
||||
expect.objectContaining({
|
||||
key: "missing-skill",
|
||||
state: "missing",
|
||||
origin: "external_unknown",
|
||||
desired: true,
|
||||
}),
|
||||
expect.objectContaining({
|
||||
key: requiredEntry.key,
|
||||
state: "configured",
|
||||
origin: "paperclip_required",
|
||||
required: true,
|
||||
detail: "Mounted on next run.",
|
||||
}),
|
||||
]);
|
||||
});
|
||||
|
||||
it("reports source-missing company runtime skills without orphan warnings", () => {
|
||||
const snapshot = buildRuntimeMountedSkillSnapshot({
|
||||
adapterType: "codex_local",
|
||||
availableEntries: [{
|
||||
key: "company/example/reflection-coach",
|
||||
runtimeName: "reflection-coach--abc123",
|
||||
source: "/paperclip/skills/example/__runtime__/reflection-coach--abc123",
|
||||
sourceStatus: "missing",
|
||||
missingDetail: "Company skill exists, but its local source is missing.",
|
||||
}],
|
||||
desiredSkills: ["company/example/reflection-coach"],
|
||||
configuredDetail: "Mounted on next run.",
|
||||
});
|
||||
|
||||
expect(snapshot.warnings).toEqual([]);
|
||||
expect(snapshot.entries).toEqual([
|
||||
expect.objectContaining({
|
||||
key: "company/example/reflection-coach",
|
||||
state: "missing",
|
||||
origin: "company_managed",
|
||||
sourcePath: null,
|
||||
detail: "Company skill exists, but its local source is missing.",
|
||||
}),
|
||||
]);
|
||||
});
|
||||
|
||||
it("keeps unsupported runtime-mounted adapters in tracked-only state", () => {
|
||||
const snapshot = buildRuntimeMountedSkillSnapshot({
|
||||
adapterType: "acpx_local",
|
||||
availableEntries: [requiredEntry],
|
||||
desiredSkills: [requiredEntry.key],
|
||||
configuredDetail: "Mounted on next run.",
|
||||
mode: "unsupported",
|
||||
unsupportedDetail: "Tracked only.",
|
||||
});
|
||||
|
||||
expect(snapshot.supported).toBe(false);
|
||||
expect(snapshot.mode).toBe("unsupported");
|
||||
expect(snapshot.entries).toContainEqual(expect.objectContaining({
|
||||
key: requiredEntry.key,
|
||||
desired: true,
|
||||
state: "available",
|
||||
detail: "Tracked only.",
|
||||
}));
|
||||
});
|
||||
|
||||
it("can surface read-only external skills for runtime-mounted adapters", () => {
|
||||
const snapshot = buildRuntimeMountedSkillSnapshot({
|
||||
adapterType: "claude_local",
|
||||
availableEntries: [requiredEntry],
|
||||
desiredSkills: [requiredEntry.key],
|
||||
configuredDetail: "Mounted on next run.",
|
||||
externalInstalled: new Map([
|
||||
["crack-python", { targetPath: "/home/me/.claude/skills/crack-python", kind: "directory" }],
|
||||
]),
|
||||
externalLocationLabel: "~/.claude/skills",
|
||||
externalDetail: "Installed outside Paperclip management in the Claude skills home.",
|
||||
});
|
||||
|
||||
expect(snapshot.entries).toContainEqual(expect.objectContaining({
|
||||
key: "crack-python",
|
||||
runtimeName: "crack-python",
|
||||
state: "external",
|
||||
managed: false,
|
||||
origin: "user_installed",
|
||||
locationLabel: "~/.claude/skills",
|
||||
readOnly: true,
|
||||
}));
|
||||
});
|
||||
|
||||
it("reports persistent adapter installed, stale, external, and missing states", () => {
|
||||
const snapshot = buildPersistentSkillSnapshot({
|
||||
adapterType: "cursor",
|
||||
availableEntries: [requiredEntry, optionalEntry],
|
||||
desiredSkills: [requiredEntry.key, "missing-skill"],
|
||||
installed: new Map([
|
||||
["paperclip", { targetPath: "/runtime/paperclip", kind: "symlink" }],
|
||||
["ascii-heart", { targetPath: "/other/ascii-heart", kind: "directory" }],
|
||||
["old-managed", { targetPath: "/runtime/old-managed", kind: "symlink" }],
|
||||
]),
|
||||
skillsHome: "/home/me/.cursor/skills",
|
||||
locationLabel: "~/.cursor/skills",
|
||||
installedDetail: "Installed in the Cursor skills home.",
|
||||
missingDetail: "Configured but not linked.",
|
||||
externalConflictDetail: "Name occupied externally.",
|
||||
externalDetail: "Installed outside Paperclip management.",
|
||||
});
|
||||
|
||||
expect(snapshot.mode).toBe("persistent");
|
||||
expect(snapshot.entries).toContainEqual(expect.objectContaining({
|
||||
key: requiredEntry.key,
|
||||
state: "installed",
|
||||
managed: true,
|
||||
origin: "paperclip_required",
|
||||
}));
|
||||
expect(snapshot.entries).toContainEqual(expect.objectContaining({
|
||||
key: optionalEntry.key,
|
||||
state: "external",
|
||||
managed: false,
|
||||
detail: "Installed outside Paperclip management.",
|
||||
}));
|
||||
expect(snapshot.entries).toContainEqual(expect.objectContaining({
|
||||
key: "missing-skill",
|
||||
state: "missing",
|
||||
origin: "external_unknown",
|
||||
}));
|
||||
expect(snapshot.entries).toContainEqual(expect.objectContaining({
|
||||
key: "old-managed",
|
||||
state: "external",
|
||||
origin: "user_installed",
|
||||
}));
|
||||
});
|
||||
|
||||
it("reports stale managed persistent skills when Paperclip owns an undesired available skill", () => {
|
||||
const snapshot = buildPersistentSkillSnapshot({
|
||||
adapterType: "cursor",
|
||||
availableEntries: [optionalEntry],
|
||||
desiredSkills: [],
|
||||
installed: new Map([
|
||||
["ascii-heart", { targetPath: "/runtime/ascii-heart", kind: "symlink" }],
|
||||
]),
|
||||
skillsHome: "/home/me/.cursor/skills",
|
||||
missingDetail: "Configured but not linked.",
|
||||
externalConflictDetail: "Name occupied externally.",
|
||||
externalDetail: "Installed outside Paperclip management.",
|
||||
});
|
||||
|
||||
expect(snapshot.entries).toContainEqual(expect.objectContaining({
|
||||
key: optionalEntry.key,
|
||||
desired: false,
|
||||
state: "stale",
|
||||
managed: true,
|
||||
}));
|
||||
});
|
||||
});
|
||||
|
||||
describe("runChildProcess", () => {
|
||||
it("does not arm a timeout when timeoutSec is 0", async () => {
|
||||
const result = await runChildProcess(
|
||||
|
|
|
|||
|
|
@ -133,6 +133,8 @@ export interface PaperclipSkillEntry {
|
|||
key: string;
|
||||
runtimeName: string;
|
||||
source: string;
|
||||
sourceStatus?: "available" | "missing";
|
||||
missingDetail?: string | null;
|
||||
required?: boolean;
|
||||
requiredReason?: string | null;
|
||||
}
|
||||
|
|
@ -161,6 +163,22 @@ interface PersistentSkillSnapshotOptions {
|
|||
warnings?: string[];
|
||||
}
|
||||
|
||||
interface RuntimeMountedSkillSnapshotOptions {
|
||||
adapterType: string;
|
||||
availableEntries: PaperclipSkillEntry[];
|
||||
desiredSkills: string[];
|
||||
configuredDetail: string | ((entry: PaperclipSkillEntry) => string | null);
|
||||
missingDetail?: string;
|
||||
mode?: "ephemeral" | "unsupported";
|
||||
supported?: boolean;
|
||||
unsupportedDetail?: string | ((entry: PaperclipSkillEntry) => string | null);
|
||||
warnings?: string[];
|
||||
externalInstalled?: Map<string, InstalledSkillTarget>;
|
||||
externalLocationLabel?: string | null;
|
||||
externalDetail?: string;
|
||||
skillsHome?: string;
|
||||
}
|
||||
|
||||
function normalizePathSlashes(value: string): string {
|
||||
return value.replaceAll("\\", "/");
|
||||
}
|
||||
|
|
@ -193,6 +211,26 @@ function buildManagedSkillOrigin(entry: { required?: boolean }): Pick<
|
|||
};
|
||||
}
|
||||
|
||||
function isPaperclipSkillSourceMissing(entry: PaperclipSkillEntry) {
|
||||
return entry.sourceStatus === "missing";
|
||||
}
|
||||
|
||||
function resolvePaperclipSkillMissingDetail(
|
||||
entry: PaperclipSkillEntry,
|
||||
fallback: string,
|
||||
) {
|
||||
return entry.missingDetail?.trim() || fallback;
|
||||
}
|
||||
|
||||
function resolveSkillDetail(
|
||||
detail: string | ((entry: PaperclipSkillEntry) => string | null) | null | undefined,
|
||||
entry: PaperclipSkillEntry,
|
||||
): string | null {
|
||||
if (typeof detail === "function") return detail(entry);
|
||||
if (typeof detail === "string") return detail;
|
||||
return null;
|
||||
}
|
||||
|
||||
function resolveInstalledEntryTarget(
|
||||
skillsHome: string,
|
||||
entryName: string,
|
||||
|
|
@ -1381,6 +1419,120 @@ export async function readInstalledSkillTargets(skillsHome: string): Promise<Map
|
|||
return out;
|
||||
}
|
||||
|
||||
export function buildRuntimeMountedSkillSnapshot(
|
||||
options: RuntimeMountedSkillSnapshotOptions,
|
||||
): AdapterSkillSnapshot {
|
||||
const {
|
||||
adapterType,
|
||||
availableEntries,
|
||||
desiredSkills,
|
||||
configuredDetail,
|
||||
missingDetail = "Paperclip cannot find this skill in the local runtime skills directory.",
|
||||
mode = "ephemeral",
|
||||
externalInstalled,
|
||||
externalLocationLabel,
|
||||
externalDetail = "Installed outside Paperclip management.",
|
||||
skillsHome,
|
||||
} = options;
|
||||
const supported = options.supported ?? mode !== "unsupported";
|
||||
const availableByKey = new Map(availableEntries.map((entry) => [entry.key, entry]));
|
||||
const desiredSet = new Set(desiredSkills);
|
||||
const entries: AdapterSkillEntry[] = [];
|
||||
const warnings = [...(options.warnings ?? [])];
|
||||
|
||||
for (const available of availableEntries) {
|
||||
const desired = desiredSet.has(available.key);
|
||||
if (isPaperclipSkillSourceMissing(available)) {
|
||||
entries.push({
|
||||
key: available.key,
|
||||
runtimeName: available.runtimeName,
|
||||
desired,
|
||||
managed: true,
|
||||
state: "missing",
|
||||
sourcePath: null,
|
||||
targetPath: null,
|
||||
detail: resolvePaperclipSkillMissingDetail(available, missingDetail),
|
||||
required: Boolean(available.required),
|
||||
requiredReason: available.requiredReason ?? null,
|
||||
...buildManagedSkillOrigin(available),
|
||||
});
|
||||
continue;
|
||||
}
|
||||
|
||||
const configured = supported && mode === "ephemeral" && desired;
|
||||
entries.push({
|
||||
key: available.key,
|
||||
runtimeName: available.runtimeName,
|
||||
desired,
|
||||
managed: true,
|
||||
state: configured ? "configured" : "available",
|
||||
sourcePath: available.source,
|
||||
targetPath: null,
|
||||
detail: desired
|
||||
? configured
|
||||
? resolveSkillDetail(configuredDetail, available)
|
||||
: resolveSkillDetail(
|
||||
options.unsupportedDetail
|
||||
?? "Desired state is stored in Paperclip only; this adapter cannot apply skills at runtime.",
|
||||
available,
|
||||
)
|
||||
: null,
|
||||
required: Boolean(available.required),
|
||||
requiredReason: available.requiredReason ?? null,
|
||||
...buildManagedSkillOrigin(available),
|
||||
});
|
||||
}
|
||||
|
||||
for (const desiredSkill of desiredSkills) {
|
||||
if (availableByKey.has(desiredSkill)) continue;
|
||||
warnings.push(`Desired skill "${desiredSkill}" is not available from the Paperclip skills directory.`);
|
||||
entries.push({
|
||||
key: desiredSkill,
|
||||
runtimeName: null,
|
||||
desired: true,
|
||||
managed: true,
|
||||
state: "missing",
|
||||
sourcePath: null,
|
||||
targetPath: null,
|
||||
detail: missingDetail,
|
||||
origin: "external_unknown",
|
||||
originLabel: "External or unavailable",
|
||||
readOnly: false,
|
||||
});
|
||||
}
|
||||
|
||||
if (externalInstalled) {
|
||||
for (const [name, installedEntry] of externalInstalled.entries()) {
|
||||
if (availableEntries.some((entry) => entry.runtimeName === name)) continue;
|
||||
entries.push({
|
||||
key: name,
|
||||
runtimeName: name,
|
||||
desired: false,
|
||||
managed: false,
|
||||
state: "external",
|
||||
origin: "user_installed",
|
||||
originLabel: "User-installed",
|
||||
locationLabel: skillLocationLabel(externalLocationLabel),
|
||||
readOnly: true,
|
||||
sourcePath: null,
|
||||
targetPath: installedEntry.targetPath ?? (skillsHome ? path.join(skillsHome, name) : null),
|
||||
detail: externalDetail,
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
entries.sort((left, right) => left.key.localeCompare(right.key));
|
||||
|
||||
return {
|
||||
adapterType,
|
||||
supported,
|
||||
mode,
|
||||
desiredSkills,
|
||||
entries,
|
||||
warnings,
|
||||
};
|
||||
}
|
||||
|
||||
export function buildPersistentSkillSnapshot(
|
||||
options: PersistentSkillSnapshotOptions,
|
||||
): AdapterSkillSnapshot {
|
||||
|
|
@ -1404,6 +1556,26 @@ export function buildPersistentSkillSnapshot(
|
|||
for (const available of availableEntries) {
|
||||
const installedEntry = installed.get(available.runtimeName) ?? null;
|
||||
const desired = desiredSet.has(available.key);
|
||||
if (isPaperclipSkillSourceMissing(available)) {
|
||||
entries.push({
|
||||
key: available.key,
|
||||
runtimeName: available.runtimeName,
|
||||
desired,
|
||||
managed: true,
|
||||
state: "missing",
|
||||
sourcePath: null,
|
||||
targetPath: path.join(skillsHome, available.runtimeName),
|
||||
detail: resolvePaperclipSkillMissingDetail(
|
||||
available,
|
||||
missingDetail,
|
||||
),
|
||||
required: Boolean(available.required),
|
||||
requiredReason: available.requiredReason ?? null,
|
||||
...buildManagedSkillOrigin(available),
|
||||
});
|
||||
continue;
|
||||
}
|
||||
|
||||
let state: AdapterSkillEntry["state"] = "available";
|
||||
let managed = false;
|
||||
let detail: string | null = null;
|
||||
|
|
@ -1496,6 +1668,11 @@ function normalizeConfiguredPaperclipRuntimeSkills(value: unknown): PaperclipSki
|
|||
key,
|
||||
runtimeName,
|
||||
source,
|
||||
sourceStatus: entry.sourceStatus === "missing" ? "missing" : "available",
|
||||
missingDetail:
|
||||
typeof entry.missingDetail === "string" && entry.missingDetail.trim().length > 0
|
||||
? entry.missingDetail.trim()
|
||||
: null,
|
||||
required: asBoolean(entry.required, false),
|
||||
requiredReason:
|
||||
typeof entry.requiredReason === "string" && entry.requiredReason.trim().length > 0
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue