feat: agent profiles describe each agent's commands

Co-Authored-By: Ovis Fast (Claude) <[email protected]>
This commit is contained in:
FactorandOvis Fast committed 2026-11-20 08:54:16 +01:00
1 parent 89ac517cab
commit 1a78b5dcf3
3 files changed
+337 -64

No files matched your search

@@ -50,69 +50,8 @@ export const NO_MATCH_MESSAGE = "Żadna komenda nie pasuje. Zmień słowo albo p
/** The same, for the files of an `@`. */ /** The same, for the files of an `@`. */
export const NO_FILE_MATCH_MESSAGE = "Żaden plik nie pasuje. Zmień słowo albo pisz dalej."; export const NO_FILE_MATCH_MESSAGE = "Żaden plik nie pasuje. Zmień słowo albo pisz dalej.";
/** export { BUILTINS } from "./profiles.js";
* The built-in commands of the agents. The list is kept by hand, in the import { BUILTINS as PROFILE_BUILTINS } from "./profiles.js";
* alphabetical order: when a new version of Claude Code brings a command,
* add it here.
*/
export const BUILTINS = {
"claude-code": [
{ key: "add-dir", desc: "Dodaje katalog roboczy." },
{ key: "agents", desc: "Zarządza subagentami." },
{ key: "bashes", desc: "Pokazuje zadania w tle." },
{ key: "bug", desc: "Zgłasza błąd Claude Code." },
{ key: "clear", desc: "Czyści historię rozmowy." },
{ key: "code-review", desc: "Przegląd zmian pod kątem błędów." },
{ key: "compact", desc: "Zwija historię do podsumowania." },
{ key: "config", desc: "Otwiera ustawienia." },
{ key: "context", desc: "Pokazuje zużycie kontekstu." },
{ key: "cost", desc: "Pokazuje koszt i zużycie tokenów." },
{ key: "doctor", desc: "Sprawdza instalację Claude Code." },
{ key: "exit", desc: "Kończy sesję." },
{ key: "export", desc: "Eksportuje rozmowę." },
{ key: "fast", desc: "Przełącza tryb szybki." },
{ key: "feedback", desc: "Wysyła opinię o Claude Code." },
{ key: "fewer-permission-prompts", desc: "Dodaje bezpieczne komendy do listy dozwolonych." },
{ key: "help", desc: "Pomoc." },
{ key: "hooks", desc: "Zarządza hookami." },
{ key: "ide", desc: "Łączy z IDE." },
{ key: "init", desc: "Tworzy CLAUDE.md dla projektu." },
{ key: "install-github-app", desc: "Instaluje aplikację GitHub." },
{ key: "keybindings", desc: "Ustawia skróty klawiszowe." },
{ key: "login", desc: "Logowanie." },
{ key: "logout", desc: "Wylogowanie." },
{ key: "loop", desc: "Uruchamia polecenie cyklicznie." },
{ key: "mcp", desc: "Zarządza serwerami MCP." },
{ key: "memory", desc: "Edytuje pliki pamięci." },
{ key: "model", desc: "Wybiera model." },
{ key: "output-style", desc: "Ustawia styl odpowiedzi." },
{ key: "permissions", desc: "Ustawia uprawnienia narzędzi." },
{ key: "plugin", desc: "Zarządza pluginami." },
{ key: "pr-comments", desc: "Pokazuje komentarze PR." },
{ key: "privacy-settings", desc: "Ustawienia prywatności." },
{ key: "release-notes", desc: "Pokazuje informacje o wydaniu." },
{ key: "resume", desc: "Wznawia wcześniejszą sesję." },
{ key: "review", desc: "Przegląd pull requesta." },
{ key: "rewind", desc: "Cofa rozmowę lub kod." },
{ key: "schedule", desc: "Planuje zadania w chmurze." },
{ key: "security-review", desc: "Przegląd bezpieczeństwa zmian." },
{ key: "simplify", desc: "Upraszcza zmieniony kod." },
{ key: "status", desc: "Pokazuje stan sesji." },
{ key: "statusline", desc: "Ustawia linię statusu." },
{ key: "terminal-setup", desc: "Konfiguruje terminal." },
{ key: "todos", desc: "Pokazuje listę zadań." },
{ key: "upgrade", desc: "Zmienia plan." },
{ key: "usage", desc: "Pokazuje limity użycia." },
{ key: "vim", desc: "Przełącza tryb vim." },
{ key: "workflows", desc: "Pokazuje przebieg workflow." },
],
codex: [
{ key: "model", desc: "Wybiera model." },
{ key: "approvals", desc: "Ustawia sposób zatwierdzania poleceń." },
{ key: "new", desc: "Zaczyna nową sesję." },
{ key: "resume", desc: "Wznawia wcześniejszą sesję." },
],
};
/** The same agent under the name the program's table gives it. */ /** The same agent under the name the program's table gives it. */
const AGENT_ALIASES = { claude: "claude-code" }; const AGENT_ALIASES = { claude: "claude-code" };
@@ -380,7 +319,7 @@ export async function files(cwd, exec, options = {}) {
/** The built-in commands of one agent - an agent we do not know has none. */ /** The built-in commands of one agent - an agent we do not know has none. */
function builtinItems(agent) { function builtinItems(agent) {
const name = String(agent ?? ""); const name = String(agent ?? "");
const list = BUILTINS[name] ?? BUILTINS[AGENT_ALIASES[name]]; const list = PROFILE_BUILTINS[name] ?? PROFILE_BUILTINS[AGENT_ALIASES[name]];
if (!list) return []; if (!list) return [];
return list.map((item) => ({ return list.map((item) => ({
key: item.key, key: item.key,
@@ -0,0 +1,188 @@
// profiles.js - what the composer knows about each agent.
//
// Pure: no GPUI, no herdr, no IO. A profile says which `agentName()` values
// belong to an agent, its built-in commands and where its own commands live
// (a folder of the project and a folder of the person's home). The defaults
// are here; the person adds or replaces profiles in `composer-agents.json`.
// A profile of the file with the id of a default one replaces it whole.
//
// Source = {scope:"project"|"home", path, pattern:"*.md"|"*/SKILL.md", prefix}
// | {scope:"home", kind:"claude-plugins"}
// Profile = {id, match:string[], builtins:{key, desc}[], sources:Source[]}
/** The file the person's profiles live in, in the app's home folder. */
export const PROFILES_FILE = "composer-agents.json";
/**
* The built-in commands of the agents. The list is kept by hand, in the
* alphabetical order: when a new version of Claude Code brings a command,
* add it here.
*/
export const BUILTINS = {
"claude-code": [
{ key: "add-dir", desc: "Dodaje katalog roboczy." },
{ key: "agents", desc: "Zarządza subagentami." },
{ key: "bashes", desc: "Pokazuje zadania w tle." },
{ key: "bug", desc: "Zgłasza błąd Claude Code." },
{ key: "clear", desc: "Czyści historię rozmowy." },
{ key: "code-review", desc: "Przegląd zmian pod kątem błędów." },
{ key: "compact", desc: "Zwija historię do podsumowania." },
{ key: "config", desc: "Otwiera ustawienia." },
{ key: "context", desc: "Pokazuje zużycie kontekstu." },
{ key: "cost", desc: "Pokazuje koszt i zużycie tokenów." },
{ key: "doctor", desc: "Sprawdza instalację Claude Code." },
{ key: "exit", desc: "Kończy sesję." },
{ key: "export", desc: "Eksportuje rozmowę." },
{ key: "fast", desc: "Przełącza tryb szybki." },
{ key: "feedback", desc: "Wysyła opinię o Claude Code." },
{ key: "fewer-permission-prompts", desc: "Dodaje bezpieczne komendy do listy dozwolonych." },
{ key: "help", desc: "Pomoc." },
{ key: "hooks", desc: "Zarządza hookami." },
{ key: "ide", desc: "Łączy z IDE." },
{ key: "init", desc: "Tworzy CLAUDE.md dla projektu." },
{ key: "install-github-app", desc: "Instaluje aplikację GitHub." },
{ key: "keybindings", desc: "Ustawia skróty klawiszowe." },
{ key: "login", desc: "Logowanie." },
{ key: "logout", desc: "Wylogowanie." },
{ key: "loop", desc: "Uruchamia polecenie cyklicznie." },
{ key: "mcp", desc: "Zarządza serwerami MCP." },
{ key: "memory", desc: "Edytuje pliki pamięci." },
{ key: "model", desc: "Wybiera model." },
{ key: "output-style", desc: "Ustawia styl odpowiedzi." },
{ key: "permissions", desc: "Ustawia uprawnienia narzędzi." },
{ key: "plugin", desc: "Zarządza pluginami." },
{ key: "pr-comments", desc: "Pokazuje komentarze PR." },
{ key: "privacy-settings", desc: "Ustawienia prywatności." },
{ key: "release-notes", desc: "Pokazuje informacje o wydaniu." },
{ key: "resume", desc: "Wznawia wcześniejszą sesję." },
{ key: "review", desc: "Przegląd pull requesta." },
{ key: "rewind", desc: "Cofa rozmowę lub kod." },
{ key: "schedule", desc: "Planuje zadania w chmurze." },
{ key: "security-review", desc: "Przegląd bezpieczeństwa zmian." },
{ key: "simplify", desc: "Upraszcza zmieniony kod." },
{ key: "status", desc: "Pokazuje stan sesji." },
{ key: "statusline", desc: "Ustawia linię statusu." },
{ key: "terminal-setup", desc: "Konfiguruje terminal." },
{ key: "todos", desc: "Pokazuje listę zadań." },
{ key: "upgrade", desc: "Zmienia plan." },
{ key: "usage", desc: "Pokazuje limity użycia." },
{ key: "vim", desc: "Przełącza tryb vim." },
{ key: "workflows", desc: "Pokazuje przebieg workflow." },
],
codex: [
{ key: "model", desc: "Wybiera model." },
{ key: "approvals", desc: "Ustawia sposób zatwierdzania poleceń." },
{ key: "new", desc: "Zaczyna nową sesję." },
{ key: "resume", desc: "Wznawia wcześniejszą sesję." },
],
};
const CC_SOURCES = [
{ scope: "project", path: ".claude/commands", pattern: "*.md", prefix: "/" },
{ scope: "project", path: ".claude/skills", pattern: "*/SKILL.md", prefix: "/" },
{ scope: "home", path: ".claude/commands", pattern: "*.md", prefix: "/" },
{ scope: "home", path: ".claude/skills", pattern: "*/SKILL.md", prefix: "/" },
{ scope: "home", kind: "claude-plugins" },
];
/** The profiles the composer brings. */
export const DEFAULT_PROFILES = [
{
id: "claude-code",
match: ["claude-code", "claude"],
builtins: BUILTINS["claude-code"],
sources: CC_SOURCES,
},
{ id: "codex", match: ["codex"], builtins: BUILTINS.codex, sources: [] },
];
const PATTERNS = new Set(["*.md", "*/SKILL.md"]);
/** A relative path with no `..` segment: absolute forms are not allowed. */
function safePath(path) {
if (typeof path !== "string" || path.trim() === "") return false;
if (/^[\\/]/.test(path) || /^[A-Za-z]:/.test(path)) return false;
return !path.split(/[\\/]/).includes("..");
}
/** One source, normalised, or `null` when it is not valid. */
function parseSource(raw) {
if (!raw || typeof raw !== "object") return null;
if (raw.scope === "home" && raw.kind === "claude-plugins") {
return { scope: "home", kind: "claude-plugins" };
}
if (raw.scope !== "project" && raw.scope !== "home") return null;
if (!safePath(raw.path) || !PATTERNS.has(raw.pattern)) return null;
const prefix = typeof raw.prefix === "string" ? raw.prefix : "/";
const path = raw.path.replace(/\\/g, "/").replace(/\/+$/, "");
return { scope: raw.scope, path, pattern: raw.pattern, prefix };
}
/**
* The profiles of the person's file.
*
* @param {string|null|undefined} text - the file, `null` when it is missing
* @returns {{profiles: object[], problem: string|null}}
*/
export function parseProfiles(text) {
if (text === null || text === undefined) return { profiles: [], problem: null };
let data;
try {
data = JSON.parse(String(text).replace(/^\uFEFF/, ""));
} catch {
return { profiles: [], problem: "nieczytelny JSON" };
}
if (!data || !Array.isArray(data.agents)) return { profiles: [], problem: "brak listy agents" };
let skipped = 0;
const profiles = [];
for (const raw of data.agents) {
const match = Array.isArray(raw?.match) ? raw.match : null;
if (
!raw ||
typeof raw.id !== "string" ||
raw.id.trim() === "" ||
!match ||
match.length === 0 ||
!match.every((m) => typeof m === "string")
) {
skipped++;
continue;
}
const builtins = [];
for (const b of Array.isArray(raw.builtins) ? raw.builtins : []) {
if (!b || typeof b.key !== "string" || b.key === "") {
skipped++;
continue;
}
builtins.push({ key: b.key, desc: typeof b.desc === "string" ? b.desc : "" });
}
const sources = [];
for (const s of Array.isArray(raw.sources) ? raw.sources : []) {
const source = parseSource(s);
if (source) sources.push(source);
else skipped++;
}
profiles.push({ id: raw.id, match: match.map((m) => m.trim()), builtins, sources });
}
return { profiles, problem: skipped > 0 ? `pominięto ${skipped} wpisów` : null };
}
/**
* The profile of an agent: the person's first, then the defaults. `""` and
* `"default"` match nothing unless a profile lists them.
*
* @param {object[]} userProfiles
* @param {string} agent - `agentName()` of the pane
* @returns {object|null}
*/
export function resolveProfile(userProfiles, agent) {
const name = String(agent ?? "").trim().toLowerCase();
for (const profile of [...(userProfiles ?? []), ...DEFAULT_PROFILES]) {
if (profile.match.some((m) => String(m).trim().toLowerCase() === name)) return profile;
}
return null;
}
+146
View File
@@ -0,0 +1,146 @@
import test from "node:test";
import assert from "node:assert/strict";
import {
BUILTINS,
DEFAULT_PROFILES,
PROFILES_FILE,
parseProfiles,
resolveProfile,
} from "../herdr/herdr-composer/mods/herdr-composer/profiles.js";
test("PROFILES_FILE is composer-agents.json", () => {
assert.equal(PROFILES_FILE, "composer-agents.json");
});
test("resolveProfile: defaults, case-insensitive, unknown and default are null", () => {
assert.equal(resolveProfile([], "claude").id, "claude-code");
assert.equal(resolveProfile([], "Claude-Code").id, "claude-code");
assert.equal(resolveProfile([], "codex").id, "codex");
assert.equal(resolveProfile([], "kiro-cli"), null);
assert.equal(resolveProfile([], "default"), null);
assert.equal(resolveProfile([], ""), null);
});
test("resolveProfile: match is case-insensitive for a user profile", () => {
const { profiles } = parseProfiles('{"agents":[{"id":"kiro","match":["kiro-cli"]}]}');
assert.equal(resolveProfile(profiles, "Kiro-CLI").id, "kiro");
assert.equal(resolveProfile(profiles, " kiro-cli ").id, "kiro");
});
test("resolveProfile: a user profile with the same id replaces the default whole", () => {
const { profiles } = parseProfiles(
'{"agents":[{"id":"claude-code","match":["claude-code"],"builtins":[{"key":"x"}]}]}',
);
const profile = resolveProfile(profiles, "claude-code");
assert.deepEqual(profile.builtins, [{ key: "x", desc: "" }]);
assert.deepEqual(profile.sources, []);
});
test("parseProfiles: no file is normal", () => {
assert.deepEqual(parseProfiles(null), { profiles: [], problem: null });
assert.deepEqual(parseProfiles(undefined), { profiles: [], problem: null });
});
test("parseProfiles: BOM and CRLF are fine, prefix kept", () => {
const text =
'\uFEFF{"agents":[{"id":"kiro","match":["kiro-cli"],"sources":[{"scope":"home","path":".kiro/prompts","pattern":"*.md","prefix":"@"}]}]}\r\n';
const { profiles, problem } = parseProfiles(text);
assert.equal(problem, null);
assert.equal(profiles.length, 1);
assert.deepEqual(profiles[0].sources, [
{ scope: "home", path: ".kiro/prompts", pattern: "*.md", prefix: "@" },
]);
});
test("parseProfiles: broken JSON", () => {
assert.deepEqual(parseProfiles("{nope"), { profiles: [], problem: "nieczytelny JSON" });
});
test("parseProfiles: agents is not a list", () => {
assert.deepEqual(parseProfiles('{"agents":{}}'), { profiles: [], problem: "brak listy agents" });
assert.deepEqual(parseProfiles("{}"), { profiles: [], problem: "brak listy agents" });
});
test("parseProfiles: bad sources are dropped, the good one stays", () => {
const text = JSON.stringify({
agents: [
{
id: "a",
match: ["a"],
sources: [
{ scope: "project", path: "../x", pattern: "*.md" },
{ scope: "home", path: "C:/x", pattern: "*.md" },
{ scope: "project", path: ".a/cmds", pattern: "*.md" },
],
},
],
});
const { profiles, problem } = parseProfiles(text);
assert.equal(profiles[0].sources.length, 1);
assert.equal(profiles[0].sources[0].prefix, "/");
assert.equal(problem, "pominięto 2 wpisów");
});
test("parseProfiles: absolute and traversal path forms are rejected", () => {
for (const path of ["/x", "C:/x", "C:\\x", "\\\\x", "a/../b", "a\\..\\b", ".."]) {
const text = JSON.stringify({
agents: [{ id: "a", match: ["a"], sources: [{ scope: "home", path, pattern: "*.md" }] }],
});
assert.deepEqual(parseProfiles(text).profiles[0].sources, [], path);
}
});
test("parseProfiles: a profile without match is dropped, the next stays", () => {
const text = JSON.stringify({ agents: [{ id: "bad" }, { id: "ok", match: ["ok"] }] });
const { profiles, problem } = parseProfiles(text);
assert.deepEqual(profiles.map((p) => p.id), ["ok"]);
assert.equal(problem, "pominięto 1 wpisów");
});
test("parseProfiles: unknown pattern, scope and keyless builtin are dropped", () => {
const text = JSON.stringify({
agents: [
{
id: "a",
match: ["a"],
builtins: [{ key: "ok", desc: "d" }, { desc: "no key" }],
sources: [
{ scope: "home", path: "p", pattern: "**/*.md" },
{ scope: "nowhere", path: "p", pattern: "*.md" },
],
},
],
});
const { profiles, problem } = parseProfiles(text);
assert.deepEqual(profiles[0].builtins, [{ key: "ok", desc: "d" }]);
assert.deepEqual(profiles[0].sources, []);
assert.equal(problem, "pominięto 3 wpisów");
});
test("parseProfiles: claude-plugins source is kept for home only", () => {
const text = JSON.stringify({
agents: [{ id: "a", match: ["a"], sources: [{ scope: "home", kind: "claude-plugins" }] }],
});
assert.deepEqual(parseProfiles(text).profiles[0].sources, [{ scope: "home", kind: "claude-plugins" }]);
});
test("DEFAULT_PROFILES: claude-code keeps the builtins and the five sources", () => {
const cc = DEFAULT_PROFILES[0];
assert.equal(cc.id, "claude-code");
assert.deepEqual(cc.match, ["claude-code", "claude"]);
assert.deepEqual(
cc.builtins.map((b) => b.key),
BUILTINS["claude-code"].map((b) => b.key),
);
assert.deepEqual(cc.sources, [
{ scope: "project", path: ".claude/commands", pattern: "*.md", prefix: "/" },
{ scope: "project", path: ".claude/skills", pattern: "*/SKILL.md", prefix: "/" },
{ scope: "home", path: ".claude/commands", pattern: "*.md", prefix: "/" },
{ scope: "home", path: ".claude/skills", pattern: "*/SKILL.md", prefix: "/" },
{ scope: "home", kind: "claude-plugins" },
]);
const codex = DEFAULT_PROFILES[1];
assert.equal(codex.id, "codex");
assert.deepEqual(codex.sources, []);
assert.equal(codex.builtins.length, 4);
});