@anhlp/alp-core 0.0.1-beta.7 → 0.0.1-beta.8
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/library-edit.d.ts +51 -2
- package/dist/library-edit.js +160 -8
- package/dist/library.d.ts +14 -1
- package/dist/library.js +73 -5
- package/dist/models.d.ts +35 -0
- package/dist/models.js +17 -1
- package/dist/packs.d.ts +57 -0
- package/dist/packs.js +247 -0
- package/dist/permissions.d.ts +3 -2
- package/dist/permissions.js +6 -3
- package/dist/profiles.js +3 -3
- package/dist/providers.d.ts +2 -4
- package/dist/providers.js +20 -4
- package/dist/skill-validate.d.ts +85 -0
- package/dist/skill-validate.js +298 -0
- package/dist/upgrade.d.ts +10 -0
- package/dist/upgrade.js +112 -6
- package/dist/validation.js +2 -3
- package/package.json +18 -2
- package/src/library-edit.js +170 -8
- package/src/library.js +96 -6
- package/src/models.js +24 -0
- package/src/packs.js +246 -0
- package/src/permissions.d.ts +3 -2
- package/src/permissions.js +13 -3
- package/src/profiles.js +4 -4
- package/src/providers.js +20 -5
- package/src/resolver.js +1 -1
- package/src/skill-validate.js +287 -0
- package/src/upgrade.js +54 -6
- package/src/validation.js +3 -4
- package/templates/ALP.md +52 -52
- package/templates/agents/lead/AGENT.md +77 -74
- package/templates/agents/main/AGENT.md +153 -145
- package/templates/agents/oracle/AGENT.md +38 -37
- package/templates/agents/peer/AGENT.md +56 -52
- package/templates/agents/reviewer/AGENT.md +63 -65
- package/templates/agents/supervisor/AGENT.md +63 -63
- package/templates/packs/architecture/agents/architect/AGENT.md +41 -0
- package/templates/packs/architecture/agents/architect/agent.json +5 -0
- package/templates/packs/architecture/agents/docs-maintainer/AGENT.md +33 -0
- package/templates/packs/architecture/agents/docs-maintainer/agent.json +4 -0
- package/templates/packs/architecture/pack.json +7 -0
- package/templates/packs/architecture/teams/blueprint/HOUSE_RULES.md +12 -0
- package/templates/packs/architecture/teams/blueprint/team.json +19 -0
- package/templates/packs/backend/pack.json +6 -0
- package/templates/packs/backend/skills/backend-development/SKILL.md +102 -0
- package/templates/packs/backend/skills/backend-development/references/api-design.md +96 -0
- package/templates/packs/backend/skills/backend-development/references/authentication.md +78 -0
- package/templates/packs/backend/skills/backend-development/references/error-handling.md +86 -0
- package/templates/packs/backend/skills/backend-development/references/testing.md +81 -0
- package/templates/packs/backend/skills/databases/SKILL.md +103 -0
- package/templates/packs/backend/skills/databases/references/query-performance.md +87 -0
- package/templates/packs/backend/skills/databases/references/schema-and-migrations.md +87 -0
- package/templates/packs/design/pack.json +6 -0
- package/templates/packs/design/skills/ui-design/SKILL.md +86 -0
- package/templates/packs/design/skills/ui-design/references/design-tokens.md +67 -0
- package/templates/packs/design/skills/ui-design/references/interaction-states.md +73 -0
- package/templates/packs/design/skills/ui-design/references/layout-and-typography.md +71 -0
- package/templates/packs/design/skills/ui-design/references/ui-review.md +83 -0
- package/templates/packs/frontend/pack.json +6 -0
- package/templates/packs/frontend/skills/frontend-development/SKILL.md +105 -0
- package/templates/packs/frontend/skills/frontend-development/references/accessibility.md +86 -0
- package/templates/packs/frontend/skills/frontend-development/references/components-and-state.md +79 -0
- package/templates/packs/frontend/skills/frontend-development/references/data-fetching.md +86 -0
- package/templates/packs/frontend/skills/frontend-development/references/frameworks.md +77 -0
- package/templates/packs/frontend/skills/frontend-development/references/performance.md +78 -0
- package/templates/packs/integration/pack.json +6 -0
- package/templates/packs/integration/skills/mcp-integration/SKILL.md +100 -0
- package/templates/packs/integration/skills/mcp-integration/references/server-implementation.md +95 -0
- package/templates/packs/integration/skills/mcp-integration/references/testing.md +78 -0
- package/templates/packs/integration/skills/mcp-integration/references/tool-design.md +97 -0
- package/templates/packs/operations/pack.json +6 -0
- package/templates/packs/operations/skills/devops/SKILL.md +85 -0
- package/templates/packs/operations/skills/devops/references/ci-cd.md +84 -0
- package/templates/packs/operations/skills/devops/references/containers.md +85 -0
- package/templates/packs/operations/skills/devops/references/deployment-and-rollback.md +85 -0
- package/templates/packs/operations/skills/devops/references/observability.md +86 -0
- package/templates/packs/quality/pack.json +6 -0
- package/templates/packs/quality/skills/web-testing/SKILL.md +102 -0
- package/templates/packs/quality/skills/web-testing/references/e2e.md +85 -0
- package/templates/packs/quality/skills/web-testing/references/performance-testing.md +85 -0
- package/templates/packs/quality/skills/web-testing/references/security-testing.md +78 -0
- package/templates/packs/quality/skills/web-testing/references/unit-and-component.md +78 -0
- package/templates/role-skills.json +4 -4
- package/templates/skills/architecture-docs/SKILL.md +81 -0
- package/templates/skills/architecture-docs/references/adr.md +62 -0
- package/templates/skills/architecture-docs/references/diagrams.md +60 -0
- package/templates/skills/architecture-docs/references/evidence-rules.md +49 -0
- package/templates/skills/bug-loop/SKILL.md +41 -40
- package/templates/skills/bug-loop/references/test-proof.md +21 -19
- package/templates/skills/compact/SKILL.md +2 -2
- package/templates/skills/curate/SKILL.md +6 -5
- package/templates/skills/feature-architecture/SKILL.md +90 -0
- package/templates/skills/feature-architecture/references/architecture-contract.md +95 -0
- package/templates/skills/feature-architecture/references/feature-design.md +69 -0
- package/templates/skills/feature-architecture/scripts/check-boundaries.mjs +270 -0
- package/templates/skills/goal-griller/SKILL.md +27 -27
- package/templates/skills/prompt-leverage/SKILL.md +29 -27
- package/templates/skills/prompt-leverage/references/brief-template.md +9 -9
- package/templates/skills/release-readiness/SKILL.md +83 -0
- package/templates/skills/release-readiness/references/checklist.md +40 -0
- package/templates/skills/release-readiness/references/verdict-template.md +53 -0
- package/templates/skills/safe-refactor/SKILL.md +84 -0
- package/templates/skills/safe-refactor/references/characterization-tests.md +57 -0
- package/templates/skills/safe-refactor/references/compatibility-checklist.md +56 -0
- package/templates/skills/security-review/SKILL.md +87 -0
- package/templates/skills/security-review/references/checklist.md +74 -0
- package/templates/skills/security-review/references/severity.md +61 -0
- package/templates/skills/sequence-execution-plan/SKILL.md +41 -38
- package/templates/skills/sequence-execution-plan/references/plan-template.md +5 -5
- package/templates/skills/skill-authoring/SKILL.md +84 -0
- package/templates/skills/skill-authoring/references/evaluation.md +45 -0
- package/templates/skills/skill-authoring/references/skill-anatomy.md +74 -0
- package/templates/skills/skill-authoring/references/trigger-design.md +52 -0
- package/templates/skills/smart-commits/SKILL.md +37 -36
- package/templates/skills/test-strategy/SKILL.md +83 -0
- package/templates/skills/test-strategy/references/contract-tests.md +46 -0
- package/templates/skills/test-strategy/references/risk-matrix.md +53 -0
- package/templates/skills/xia/SKILL.md +40 -38
- package/templates/teams/cafe/HOUSE_RULES.md +1 -1
- package/templates/teams/cafe/team.json +1 -1
- package/templates/teams/pho/HOUSE_RULES.md +1 -1
- package/templates/teams/pho/team.json +1 -1
package/src/library-edit.js
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { lstat, mkdir, readdir, rename, rm, stat, writeFile } from 'node:fs/promises';
|
|
1
|
+
import { cp, lstat, mkdir, readdir, rename, rm, stat, writeFile } from 'node:fs/promises';
|
|
2
2
|
import { createHash, randomUUID } from 'node:crypto';
|
|
3
3
|
import path from 'node:path';
|
|
4
4
|
import { moveFile } from './atomic.js';
|
|
@@ -8,6 +8,26 @@ import { agentSources, builtinText, jsonObject, libraryEntries, optionalText } f
|
|
|
8
8
|
import { teamSources, validateTeam } from './teams.js';
|
|
9
9
|
import { normalizeMcp, validateAgentConfig, validateHook } from './validation.js';
|
|
10
10
|
import { validateProvider } from './providers.js';
|
|
11
|
+
import { checkFrontmatter, skillReferences, specName, splitSkill } from './skill-validate.js';
|
|
12
|
+
|
|
13
|
+
/**
|
|
14
|
+
* A SKILL.md with its frontmatter `name` set to `name`, so a copied or renamed skill stays valid:
|
|
15
|
+
* the name must equal the skill's directory. A SKILL.md without frontmatter is left as it is.
|
|
16
|
+
*/
|
|
17
|
+
export function withSkillName(body, name) {
|
|
18
|
+
const match = /^(\uFEFF?---(\r?\n))([\s\S]*?)(\r?\n---[ \t]*(?:\r?\n|$))/.exec(body);
|
|
19
|
+
if (!match) return body;
|
|
20
|
+
const lines = match[3].split(/\r?\n/);
|
|
21
|
+
const at = lines.findIndex(line => /^name[ \t]*:/.test(line));
|
|
22
|
+
if (at >= 0) lines[at] = `name: ${name}`;
|
|
23
|
+
else lines.unshift(`name: ${name}`);
|
|
24
|
+
return match[1] + lines.join(match[2]) + match[4] + body.slice(match[0].length);
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
/** A skill's new name, when it carries the format's name into its frontmatter: the format's rules. */
|
|
28
|
+
function skillTarget(body, name) {
|
|
29
|
+
if (splitSkill(body).frontmatter !== undefined && !specName(name)) fail('INVALID_NAME', `'${name}' is not a skill name: use 1-64 lowercase letters, digits and single hyphens`);
|
|
30
|
+
}
|
|
11
31
|
|
|
12
32
|
/**
|
|
13
33
|
* Editing the library (ALPD §43): agents, skills, MCP servers, hooks and teams, in the
|
|
@@ -178,12 +198,12 @@ export async function getEntry(kind, name, { root, library, templates, scope } =
|
|
|
178
198
|
async function readGiven(library) {
|
|
179
199
|
const file = path.join(library, 'role-skills.json');
|
|
180
200
|
const text = await optionalText(file);
|
|
181
|
-
if (text === undefined) return { file, roles:
|
|
201
|
+
if (text === undefined) return { file, roles: Object.create(null) };
|
|
182
202
|
let roles;
|
|
183
203
|
try { roles = JSON.parse(text); }
|
|
184
204
|
catch (cause) { throw new AlpError('INVALID_LIBRARY', `${file}: ${cause.message}`, { cause }); }
|
|
185
205
|
if (!object(roles)) fail('INVALID_LIBRARY', `${file}: expected an object of agent names to skill lists`);
|
|
186
|
-
return { file, roles };
|
|
206
|
+
return { file, roles: Object.assign(Object.create(null), roles) };
|
|
187
207
|
}
|
|
188
208
|
|
|
189
209
|
/** The skills the library gives `agent`, as role-skills.json lists them. */
|
|
@@ -209,6 +229,102 @@ export async function setGivenSkills(agent, skills, { library } = {}) {
|
|
|
209
229
|
return { skills: unique };
|
|
210
230
|
}
|
|
211
231
|
|
|
232
|
+
/** Where alp_skill_retire keeps retired skills, and the metadata file it writes in each. */
|
|
233
|
+
export const RETIRED_SKILLS = 'retired-skills';
|
|
234
|
+
export const RETIRED_METADATA = 'retired.json';
|
|
235
|
+
// <name>-<ISO time with ':' and '.' replaced by '-'>, as alp_skill_retire names the folder.
|
|
236
|
+
const RETIRED_FOLDER = /^(.+)-(\d{4}-\d\d-\d\dT\d\d-\d\d-\d\d-\d{3}Z)$/;
|
|
237
|
+
|
|
238
|
+
async function retiredMetadata(directory) {
|
|
239
|
+
const text = await optionalText(path.join(directory, RETIRED_METADATA));
|
|
240
|
+
if (text === undefined) return undefined;
|
|
241
|
+
let data;
|
|
242
|
+
try { data = JSON.parse(text); } catch (cause) { throw new AlpError('INVALID_LIBRARY', `${path.join(directory, RETIRED_METADATA)}: ${cause.message}`, { cause }); }
|
|
243
|
+
if (!object(data) || !Array.isArray(data.roles) || !data.roles.every(validName)) fail('INVALID_LIBRARY', `${path.join(directory, RETIRED_METADATA)}: expected { name, roles: [...] }`);
|
|
244
|
+
return data;
|
|
245
|
+
}
|
|
246
|
+
|
|
247
|
+
/**
|
|
248
|
+
* The library's retired skills, newest first. `roles` is what retired.json recorded,
|
|
249
|
+
* or null for a skill retired before ALP wrote it.
|
|
250
|
+
* @returns {Promise<{ name: string, directory: string, retiredAt: string, roles: string[] | null, agent: string | null }[]>}
|
|
251
|
+
*/
|
|
252
|
+
export async function listRetiredSkills({ library } = {}) {
|
|
253
|
+
if (!library) fail('INVALID_SCOPE', 'No library: ALP_HOME is not set');
|
|
254
|
+
const root = path.join(library, RETIRED_SKILLS);
|
|
255
|
+
const entries = await readdir(root, { withFileTypes: true }).catch(error => { if (error.code === 'ENOENT') return []; throw error; });
|
|
256
|
+
const rows = [];
|
|
257
|
+
for (const entry of entries) {
|
|
258
|
+
const match = entry.isDirectory() && RETIRED_FOLDER.exec(entry.name);
|
|
259
|
+
if (!match) continue;
|
|
260
|
+
const directory = path.join(root, entry.name);
|
|
261
|
+
// A corrupt retired.json must not hide the other retired skills: list the copy
|
|
262
|
+
// without roles, and restore then asks for --roles or --no-roles.
|
|
263
|
+
let meta, invalid;
|
|
264
|
+
try { meta = await retiredMetadata(directory); } catch (error) { invalid = error.message; }
|
|
265
|
+
const stamp = match[2].replace(/T(\d\d)-(\d\d)-(\d\d)-(\d{3})Z$/, 'T$1:$2:$3.$4Z');
|
|
266
|
+
rows.push({ name: match[1], directory, retiredAt: typeof meta?.retiredAt === 'string' ? meta.retiredAt : stamp, roles: meta ? meta.roles : null, agent: typeof meta?.agent === 'string' ? meta.agent : null, ...(invalid ? { invalid } : {}) });
|
|
267
|
+
}
|
|
268
|
+
return rows.sort((a, b) => b.retiredAt.localeCompare(a.retiredAt) || b.directory.localeCompare(a.directory));
|
|
269
|
+
}
|
|
270
|
+
|
|
271
|
+
/**
|
|
272
|
+
* Moves a retired skill back to <library>/skills/<name> and gives it to roles again in
|
|
273
|
+
* role-skills.json: `roles` when given ([] for none), else the roles retired.json recorded.
|
|
274
|
+
* Takes `from` when given, else the newest retired copy of the name. Refuses when the
|
|
275
|
+
* library already has the skill, or when neither `roles` nor retired.json says the roles.
|
|
276
|
+
* @returns {Promise<{ name: string, restored: string, from: string, roles: string[] }>}
|
|
277
|
+
*/
|
|
278
|
+
export async function restoreSkill(name, { library, from, roles } = {}) {
|
|
279
|
+
nameOf(name);
|
|
280
|
+
if (!library) fail('INVALID_SCOPE', 'No library: ALP_HOME is not set');
|
|
281
|
+
if (roles !== undefined && (!Array.isArray(roles) || !roles.every(validName))) fail('INVALID_ENTRY', 'Roles must be a list of agent names');
|
|
282
|
+
let source;
|
|
283
|
+
if (from !== undefined) {
|
|
284
|
+
source = path.resolve(from);
|
|
285
|
+
const info = await lstat(source).catch(() => undefined);
|
|
286
|
+
if (info?.isSymbolicLink()) fail('INVALID_ENTRY', `${source} is a symbolic link; pass the directory itself`);
|
|
287
|
+
if (!info?.isDirectory()) fail('NOT_FOUND', `${source} is not a directory`);
|
|
288
|
+
} else {
|
|
289
|
+
const found = (await listRetiredSkills({ library })).find(row => row.name === name);
|
|
290
|
+
if (!found) fail('NOT_FOUND', `No retired skill '${name}' in ${path.join(library, RETIRED_SKILLS)}`);
|
|
291
|
+
source = found.directory;
|
|
292
|
+
}
|
|
293
|
+
if (!(await exists(path.join(source, 'SKILL.md')))) fail('NOT_FOUND', `${source} has no SKILL.md`);
|
|
294
|
+
const target = path.join(library, 'skills', name);
|
|
295
|
+
if (await lstat(target).then(() => true, () => false)) fail('ALREADY_EXISTS', `The library already has a skill '${name}' (${target}); nothing was restored`);
|
|
296
|
+
const metaFile = path.join(source, RETIRED_METADATA);
|
|
297
|
+
const metaText = await optionalText(metaFile);
|
|
298
|
+
let meta;
|
|
299
|
+
try { meta = await retiredMetadata(source); } catch (error) { if (error?.code !== 'INVALID_LIBRARY' || roles === undefined) throw error; }
|
|
300
|
+
if (meta && meta.name !== undefined && meta.name !== name) fail('INVALID_ENTRY', `${metaFile} is for the skill '${meta.name}', not '${name}'`);
|
|
301
|
+
const given = roles ?? meta?.roles;
|
|
302
|
+
if (!given) fail('ROLES_REQUIRED', `${source} does not record the roles that had '${name}'; pass --roles a,b or --no-roles`);
|
|
303
|
+
const unique = [...new Set(given)];
|
|
304
|
+
const { file: rolesFile, roles: current } = await readGiven(library);
|
|
305
|
+
const before = await optionalText(rolesFile);
|
|
306
|
+
await mkdir(path.dirname(target), { recursive: true });
|
|
307
|
+
await moveFile(source, target);
|
|
308
|
+
try {
|
|
309
|
+
if (metaText !== undefined) await rm(path.join(target, RETIRED_METADATA), { force: true });
|
|
310
|
+
if (unique.length) {
|
|
311
|
+
for (const role of unique) {
|
|
312
|
+
const list = Array.isArray(current[role]) ? current[role] : [];
|
|
313
|
+
if (!list.includes(name)) list.push(name);
|
|
314
|
+
current[role] = list;
|
|
315
|
+
}
|
|
316
|
+
await writeAtomic(rolesFile, JSON.stringify(current, null, 2) + '\n');
|
|
317
|
+
}
|
|
318
|
+
} catch (error) {
|
|
319
|
+
// Put everything back, so a failed restore changes nothing.
|
|
320
|
+
if (before !== undefined) await writeAtomic(rolesFile, before).catch(() => {});
|
|
321
|
+
if (metaText !== undefined) await writeFile(path.join(target, RETIRED_METADATA), metaText).catch(() => {});
|
|
322
|
+
await moveFile(target, source).catch(() => {});
|
|
323
|
+
throw error;
|
|
324
|
+
}
|
|
325
|
+
return { name, restored: target, from: source, roles: unique };
|
|
326
|
+
}
|
|
327
|
+
|
|
212
328
|
/** Every entry of a kind with its source and users, as `alp <kind>` lists them. */
|
|
213
329
|
export async function listEntries(kind, { root, library, templates } = {}) {
|
|
214
330
|
kindOf(kind);
|
|
@@ -312,10 +428,24 @@ const exists = target => stat(target).then(() => true, () => false);
|
|
|
312
428
|
/**
|
|
313
429
|
* Creates or replaces an entry in a scope. `revision` is what getEntry returned for
|
|
314
430
|
* that scope (null to create); a different current revision refuses the save.
|
|
315
|
-
*
|
|
431
|
+
* `strict` (the CLI creating a skill): a new skill must meet the skill format; `warnings` names
|
|
432
|
+
* files its SKILL.md points to that are not there yet. Edits and other callers are unchanged.
|
|
433
|
+
* @param {string} kind
|
|
434
|
+
* @param {string} name
|
|
435
|
+
* @param {any} content
|
|
436
|
+
* @param {{ scope?: any, root?: string, library?: string, templates?: Record<string, string>, revision?: string | null, policy?: string, strict?: boolean }} [options]
|
|
437
|
+
* @returns {Promise<{ revision: string | null, warnings?: string[] }>}
|
|
316
438
|
*/
|
|
317
|
-
export async function saveEntry(kind, name, content, { scope, root, library, templates, revision, policy } = {}) {
|
|
439
|
+
export async function saveEntry(kind, name, content, { scope, root, library, templates, revision, policy, strict = false } = {}) {
|
|
318
440
|
kindOf(kind); nameOf(name);
|
|
441
|
+
// A new skill made by the CLI (strict) meets the skill format; existing skills are saved as before.
|
|
442
|
+
const warnings = [];
|
|
443
|
+
if (strict && kind === 'skills' && revision === null && typeof content?.body === 'string') {
|
|
444
|
+
const errors = checkFrontmatter(splitSkill(content.body).frontmatter, name, { strict: true }).findings.filter(finding => finding.level === 'error');
|
|
445
|
+
if (errors.length) fail('INVALID_ENTRY', `skills '${name}' does not meet the skill format: ${errors.map(finding => finding.message).join('; ')}`);
|
|
446
|
+
const links = skillReferences(splitSkill(content.body).body);
|
|
447
|
+
if (links.length) warnings.push(`SKILL.md points to ${links.join(', ')}: add ${links.length > 1 ? 'those files' : 'that file'} beside it, in the skill's directory`);
|
|
448
|
+
}
|
|
319
449
|
if (policy === 'project-data') {
|
|
320
450
|
assertProjectDataContent(kind, content);
|
|
321
451
|
await projectDataEntry(kind, name, { scope, root, library, templates });
|
|
@@ -336,7 +466,7 @@ export async function saveEntry(kind, name, content, { scope, root, library, tem
|
|
|
336
466
|
if (empty) { await rm(target, { force: true }); continue; }
|
|
337
467
|
await writeAtomic(target, type === 'json' ? JSON.stringify(value, null, 2) + '\n' : value.endsWith('\n') ? value : `${value}\n`);
|
|
338
468
|
}
|
|
339
|
-
return { revision: revisionOf(await readLayer(kind, name, directory)) };
|
|
469
|
+
return { revision: revisionOf(await readLayer(kind, name, directory)), ...(warnings.length ? { warnings } : {}) };
|
|
340
470
|
}
|
|
341
471
|
|
|
342
472
|
/**
|
|
@@ -371,8 +501,37 @@ export async function duplicateEntry(kind, from, to, { scope, root, library, tem
|
|
|
371
501
|
await projectDataEntry(kind, from, { scope, root, library, templates });
|
|
372
502
|
await projectDataEntry(kind, to, { scope, root, library, templates });
|
|
373
503
|
}
|
|
374
|
-
const
|
|
375
|
-
|
|
504
|
+
const entry = await getEntry(kind, from, { root, library, templates });
|
|
505
|
+
if (kind === 'skills') { skillTarget(entry.content.body, to); entry.content.body = withSkillName(entry.content.body, to); }
|
|
506
|
+
// A skill is its directory: its references, scripts and assets go with SKILL.md, bytes and modes kept.
|
|
507
|
+
const resources = kind === 'skills' && policy !== 'project-data' ? await skillResources(entry.source === 'project' ? path.join(path.resolve(root), '.alp', 'skills', from) : path.join(library, 'skills', from)) : [];
|
|
508
|
+
const saved = await saveEntry(kind, to, structuredClone(entry.content), { scope, root, library, templates, revision: null, policy });
|
|
509
|
+
if (resources.length) {
|
|
510
|
+
const target = path.join(base(scope, { root, library }, kind), kind, to);
|
|
511
|
+
try { for (const [source, relative] of resources) await cp(source, path.join(target, relative), { recursive: true, errorOnExist: true, force: false }); }
|
|
512
|
+
catch (error) {
|
|
513
|
+
// Half a copy is no skill: the new entry (made just above, so nobody else's) goes again.
|
|
514
|
+
await rm(target, { recursive: true, force: true });
|
|
515
|
+
throw error;
|
|
516
|
+
}
|
|
517
|
+
}
|
|
518
|
+
return saved;
|
|
519
|
+
}
|
|
520
|
+
|
|
521
|
+
/** A skill directory's entries besides SKILL.md, as [absolute, relative]; refused when it holds a link. */
|
|
522
|
+
async function skillResources(directory) {
|
|
523
|
+
const found = [];
|
|
524
|
+
const walk = async relative => {
|
|
525
|
+
for (const item of await readdir(path.join(directory, relative), { withFileTypes: true }).catch(error => { if (error.code === 'ENOENT') return []; throw error; })) {
|
|
526
|
+
const rel = path.join(relative, item.name);
|
|
527
|
+
if (item.name === '.git' || item.name === 'node_modules') continue;
|
|
528
|
+
if (item.isSymbolicLink()) fail('UNSAFE_LIBRARY_WRITE', `${path.join(directory, rel)} is a symbolic link; copy the skill by hand`);
|
|
529
|
+
if (item.isDirectory()) await walk(rel);
|
|
530
|
+
else if (item.isFile() && rel !== 'SKILL.md') found.push([path.join(directory, rel), rel]);
|
|
531
|
+
}
|
|
532
|
+
};
|
|
533
|
+
await walk('');
|
|
534
|
+
return found;
|
|
376
535
|
}
|
|
377
536
|
|
|
378
537
|
/** Renames an entry within a scope; refused while others refer to it by its old name. */
|
|
@@ -389,9 +548,12 @@ export async function renameEntry(kind, from, to, { scope, root, library, templa
|
|
|
389
548
|
const users = await usersOf(kind, from, { root, library, templates });
|
|
390
549
|
if (users.length) fail('IN_USE', `${kind} '${from}' is used by ${users.join(', ')}; change them first`);
|
|
391
550
|
await check(kind, to, content, { scope, root, library, templates });
|
|
551
|
+
if (kind === 'skills') skillTarget(content.body, to);
|
|
392
552
|
if (ownDirectory(kind)) {
|
|
393
553
|
if (await exists(path.join(directory, kind, to))) fail('REVISION_CONFLICT', `${path.join(directory, kind, to)} already exists`);
|
|
394
554
|
await rename(path.join(directory, kind, from), path.join(directory, kind, to));
|
|
555
|
+
// The moved skill's frontmatter names its new directory.
|
|
556
|
+
if (kind === 'skills' && withSkillName(content.body, to) !== content.body) await writeAtomic(path.join(directory, kind, to, 'SKILL.md'), withSkillName(content.body, to));
|
|
395
557
|
} else {
|
|
396
558
|
await rename(path.join(directory, kind, `${from}.json`), path.join(directory, kind, `${to}.json`));
|
|
397
559
|
}
|
package/src/library.js
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { shippedTemplateRoot } from './template-path.js';
|
|
2
|
-
import { mkdir, readFile, readdir, writeFile } from 'node:fs/promises';
|
|
2
|
+
import { chmod, mkdir, readFile, readdir, writeFile } from 'node:fs/promises';
|
|
3
3
|
import { moveFile } from './atomic.js';
|
|
4
4
|
import { createHash, randomUUID } from 'node:crypto';
|
|
5
5
|
import os from 'node:os';
|
|
@@ -42,11 +42,84 @@ async function shippedFiles({ templateRoot, templates }) {
|
|
|
42
42
|
return files;
|
|
43
43
|
}
|
|
44
44
|
|
|
45
|
+
/**
|
|
46
|
+
* Every role-skills.json ALP shipped, by sha (CRLF-normalized), with what it gave each role. A
|
|
47
|
+
* library's manifest names the one ALP last wrote, so the built-in skills its user has already been
|
|
48
|
+
* offered are known for a library from before `roleSkillsOffered` was recorded (t-de1a). Add each
|
|
49
|
+
* new shipped version here (packages/core/tests/role-skills-offer.test.js checks the current one is).
|
|
50
|
+
* @type {Readonly<Record<string, Record<string, string[]>>>}
|
|
51
|
+
*/
|
|
52
|
+
export const SHIPPED_ROLE_SKILLS = Object.freeze({
|
|
53
|
+
// 0086846 (2026-10-07)
|
|
54
|
+
'7132b9ef1f10db55caea23dbe705a0ab06c83c86f51f074e663d12043a79327a': { main: ['goal-griller', 'xia', 'sequence-execution-plan', 'prompt-leverage', 'bug-loop', 'smart-commits'], lead: ['xia', 'sequence-execution-plan', 'prompt-leverage', 'bug-loop', 'smart-commits'], peer: ['xia', 'bug-loop', 'smart-commits'] },
|
|
55
|
+
// 9ccd54c (2026-10-08): oracle and reviewer, with none
|
|
56
|
+
'c03f7bcecd61e26e70ef05b268aa7881a75f9e9c45ae5486ae9659cefd6bb449': { main: ['goal-griller', 'xia', 'sequence-execution-plan', 'prompt-leverage', 'bug-loop', 'smart-commits'], lead: ['xia', 'sequence-execution-plan', 'prompt-leverage', 'bug-loop', 'smart-commits'], peer: ['xia', 'bug-loop', 'smart-commits'] },
|
|
57
|
+
// 61181b5 (2026-10-09): supervisor, with none
|
|
58
|
+
'8c5664042d4a4ecd3ded61240d8febbffa6e8965a88af0e9ba0420ad2f2ce8fe': { main: ['goal-griller', 'xia', 'sequence-execution-plan', 'prompt-leverage', 'bug-loop', 'smart-commits'], lead: ['xia', 'sequence-execution-plan', 'prompt-leverage', 'bug-loop', 'smart-commits'], peer: ['xia', 'bug-loop', 'smart-commits'] },
|
|
59
|
+
// 9180aa1 (2026-10-29): compact for main
|
|
60
|
+
'b12b52102c358119cf834e5f3be54e6a69aa4c9f388fe889dffbb529755292dc': { main: ['goal-griller', 'xia', 'sequence-execution-plan', 'prompt-leverage', 'bug-loop', 'smart-commits', 'compact'], lead: ['xia', 'sequence-execution-plan', 'prompt-leverage', 'bug-loop', 'smart-commits'], peer: ['xia', 'bug-loop', 'smart-commits'] },
|
|
61
|
+
// f4d7986 (2026-10-29): curate for main
|
|
62
|
+
'a84b035d0058cbfcda7e32dc1706b9e83e67764eed24e2e121bdfcd60f924e46': { main: ['goal-griller', 'xia', 'sequence-execution-plan', 'prompt-leverage', 'bug-loop', 'smart-commits', 'compact', 'curate'], lead: ['xia', 'sequence-execution-plan', 'prompt-leverage', 'bug-loop', 'smart-commits'], peer: ['xia', 'bug-loop', 'smart-commits'] },
|
|
63
|
+
// Skill system v2 (2026-11-05): engineering core skills; reviewer gets its first two
|
|
64
|
+
'e60be7eec8d9b5180866c9b5a2c14cf0d95a9f1331ed771e93791f7b524af9b1': { main: ['goal-griller', 'xia', 'sequence-execution-plan', 'prompt-leverage', 'bug-loop', 'smart-commits', 'compact', 'curate', 'skill-authoring', 'architecture-docs', 'feature-architecture', 'test-strategy', 'safe-refactor', 'security-review', 'release-readiness'], lead: ['xia', 'sequence-execution-plan', 'prompt-leverage', 'bug-loop', 'smart-commits', 'architecture-docs', 'feature-architecture', 'test-strategy', 'safe-refactor', 'security-review', 'release-readiness'], peer: ['xia', 'bug-loop', 'smart-commits', 'feature-architecture', 'test-strategy', 'safe-refactor'], reviewer: ['security-review', 'release-readiness'] },
|
|
65
|
+
});
|
|
66
|
+
|
|
67
|
+
/** An agent → skills object's pairs as `agent/skill` strings (role-skills.json is keyed by agent name); anything else gives none. @param {unknown} roles */
|
|
68
|
+
const rolePairs = roles => roles && typeof roles === 'object' && !Array.isArray(roles)
|
|
69
|
+
? Object.entries(roles).flatMap(([role, names]) => Array.isArray(names) ? names.filter(skillName).map(name => `${role}/${name}`) : [])
|
|
70
|
+
: [];
|
|
71
|
+
|
|
72
|
+
/**
|
|
73
|
+
* Offers the built-in role skills an edited role-skills.json has never been offered (t-de1a): each
|
|
74
|
+
* goes to the end of its role's list, when that role is listed and lacks it. What was offered is
|
|
75
|
+
* recorded in the manifest (`roleSkillsOffered`), so a skill the user then removes stays removed, and
|
|
76
|
+
* nothing the user wrote is removed or reordered. A role the user's file does not list (setGivenSkills
|
|
77
|
+
* drops a role given none) gets nothing; a file that is missing or not a JSON object is left alone, and
|
|
78
|
+
* its skills are offered again once it can be read. Before the record exists, what the user was offered
|
|
79
|
+
* is what the role-skills.json ALP last wrote gave (SHIPPED_ROLE_SKILLS); an unknown one offers nothing.
|
|
80
|
+
* @returns {Promise<string[]>} the `role/skill` pairs added
|
|
81
|
+
*/
|
|
82
|
+
async function offerRoleSkills(home, manifest, shippedText, seeded) {
|
|
83
|
+
const name = 'role-skills.json';
|
|
84
|
+
const shipped = rolePairs(JSON.parse(shippedText));
|
|
85
|
+
const baseline = Array.isArray(manifest.roleSkillsOffered) ? manifest.roleSkillsOffered
|
|
86
|
+
: seeded !== undefined && Object.hasOwn(SHIPPED_ROLE_SKILLS, seeded) ? rolePairs(SHIPPED_ROLE_SKILLS[seeded])
|
|
87
|
+
: shipped;
|
|
88
|
+
const offered = new Set(baseline.filter(pair => typeof pair === 'string'));
|
|
89
|
+
const fresh = shipped.filter(pair => !offered.has(pair));
|
|
90
|
+
const record = () => { manifest.roleSkillsOffered = [...new Set([...offered, ...shipped])].sort(); };
|
|
91
|
+
if (!fresh.length) { const before = JSON.stringify(manifest.roleSkillsOffered); record(); return { added: [], changed: before !== JSON.stringify(manifest.roleSkillsOffered) }; }
|
|
92
|
+
const target = path.join(home, name);
|
|
93
|
+
const text = await optional(target);
|
|
94
|
+
if (text === undefined) { record(); return { added: [], changed: true }; }
|
|
95
|
+
let roles;
|
|
96
|
+
try { roles = JSON.parse(text); } catch { return { added: [], changed: false }; }
|
|
97
|
+
if (!roles || typeof roles !== 'object' || Array.isArray(roles)) return { added: [], changed: false };
|
|
98
|
+
const added = [];
|
|
99
|
+
for (const pair of fresh) {
|
|
100
|
+
const [role, skill] = pair.split('/');
|
|
101
|
+
if (!Array.isArray(roles[role]) || roles[role].includes(skill)) continue;
|
|
102
|
+
roles[role].push(skill);
|
|
103
|
+
added.push(pair);
|
|
104
|
+
}
|
|
105
|
+
if (added.length) {
|
|
106
|
+
const next = JSON.stringify(roles, null, 2) + '\n';
|
|
107
|
+
const temporary = `${target}.${randomUUID().slice(0, 8)}.tmp`;
|
|
108
|
+
await writeFile(temporary, next);
|
|
109
|
+
await moveFile(temporary, target);
|
|
110
|
+
}
|
|
111
|
+
record();
|
|
112
|
+
return { added, changed: true };
|
|
113
|
+
}
|
|
114
|
+
|
|
45
115
|
/**
|
|
46
116
|
* Seeds or updates the library in `home`. A file is written when ALP never
|
|
47
117
|
* shipped it before, and replaced only while it still holds what ALP last wrote.
|
|
118
|
+
* With `offerRoleSkills` (alp upgrade, alp update-template), an edited role-skills.json
|
|
119
|
+
* is also offered the built-in role skills it never was (offerRoleSkills above).
|
|
48
120
|
* @param {string} home
|
|
49
|
-
* @param {{ templateRoot?: URL, templates?: Record<string, string
|
|
121
|
+
* @param {{ templateRoot?: URL, templates?: Record<string, string>, offerRoleSkills?: boolean }} [options]
|
|
122
|
+
* @returns {Promise<{ created: string[], updated: string[], offered?: string[] }>} offered only with offerRoleSkills
|
|
50
123
|
*/
|
|
51
124
|
export async function seedLibrary(home, options = {}) {
|
|
52
125
|
const shipped = await shippedFiles(options);
|
|
@@ -56,6 +129,8 @@ export async function seedLibrary(home, options = {}) {
|
|
|
56
129
|
const manifest = manifestText ? JSON.parse(manifestText) : { files: {} };
|
|
57
130
|
const created = [];
|
|
58
131
|
const updated = [];
|
|
132
|
+
// What ALP last wrote of role-skills.json, before this run's update of it (offerRoleSkills).
|
|
133
|
+
const seededRoles = manifest.files['role-skills.json'];
|
|
59
134
|
for (const [name, content] of Object.entries(shipped).sort(([a], [b]) => a.localeCompare(b))) {
|
|
60
135
|
const target = path.join(home, ...name.split('/'));
|
|
61
136
|
const current = await optional(target);
|
|
@@ -64,23 +139,38 @@ export async function seedLibrary(home, options = {}) {
|
|
|
64
139
|
// A file the user made under a shipped name stays theirs.
|
|
65
140
|
if (current !== undefined) continue;
|
|
66
141
|
await mkdir(path.dirname(target), { recursive: true });
|
|
67
|
-
await writeFile(target, content, { flag: 'wx' }).
|
|
142
|
+
const wrote = await writeFile(target, content, { flag: 'wx' }).then(() => true, error => { if (error.code !== 'EEXIST') throw error; return false; });
|
|
143
|
+
if (wrote) await keepExecutable(name, target, content);
|
|
68
144
|
manifest.files[name] = sha(content);
|
|
69
145
|
created.push(name);
|
|
70
146
|
} else if (current !== undefined && sha(current) === seeded && seeded !== sha(content)) {
|
|
71
147
|
await writeFile(target, content);
|
|
148
|
+
await keepExecutable(name, target, content);
|
|
72
149
|
manifest.files[name] = sha(content);
|
|
73
150
|
updated.push(name);
|
|
74
151
|
}
|
|
75
152
|
// Missing after seeding: the user deleted it. Changed: the user edited it. Both are kept.
|
|
76
153
|
}
|
|
77
|
-
|
|
154
|
+
const offer = options.offerRoleSkills && shipped['role-skills.json'] !== undefined
|
|
155
|
+
? await offerRoleSkills(home, manifest, shipped['role-skills.json'], seededRoles)
|
|
156
|
+
: undefined;
|
|
157
|
+
if (created.length || updated.length || offer?.changed || manifestText === undefined) {
|
|
78
158
|
await mkdir(home, { recursive: true });
|
|
79
159
|
const temporary = `${manifestPath}.${randomUUID().slice(0, 8)}.tmp`;
|
|
80
160
|
await writeFile(temporary, JSON.stringify(manifest, null, 2) + '\n');
|
|
81
161
|
await moveFile(temporary, manifestPath);
|
|
82
162
|
}
|
|
83
|
-
return { created, updated };
|
|
163
|
+
return { created, updated, ...(options.offerRoleSkills ? { offered: offer?.added ?? [] } : {}) };
|
|
164
|
+
}
|
|
165
|
+
|
|
166
|
+
/**
|
|
167
|
+
* Bundles carry shipped templates as text, so a script's executable bit cannot travel with it: a
|
|
168
|
+
* shipped skill script that starts with `#!` is made executable where ALP writes it (Level 3
|
|
169
|
+
* resources; the validator holds shipped skills to UTF-8 text). Nothing runs it.
|
|
170
|
+
*/
|
|
171
|
+
async function keepExecutable(name, target, content) {
|
|
172
|
+
if (process.platform === 'win32' || !/^skills\/[^/]+\/scripts\//.test(name) || !content.startsWith('#!')) return;
|
|
173
|
+
await chmod(target, 0o755);
|
|
84
174
|
}
|
|
85
175
|
|
|
86
176
|
const seeding = new Map();
|
|
@@ -105,7 +195,7 @@ export async function librarySkills(home, agent) {
|
|
|
105
195
|
let roles;
|
|
106
196
|
try { roles = JSON.parse(text); }
|
|
107
197
|
catch (cause) { throw new AlpError('INVALID_LIBRARY', `${file}: ${cause.message}`, { cause }); }
|
|
108
|
-
if (!roles || typeof roles !== 'object' || Array.isArray(roles)) throw new AlpError('INVALID_LIBRARY', `${file}: expected an object of
|
|
198
|
+
if (!roles || typeof roles !== 'object' || Array.isArray(roles)) throw new AlpError('INVALID_LIBRARY', `${file}: expected an object of agent names to skill lists`);
|
|
109
199
|
const names = roles[agent] ?? [];
|
|
110
200
|
if (!Array.isArray(names) || !names.every(skillName)) throw new AlpError('INVALID_LIBRARY', `${file}: ${agent} must list skill directory names`);
|
|
111
201
|
const skills = [];
|
package/src/models.js
CHANGED
|
@@ -90,6 +90,30 @@ export function mergeCatalog(base, live) {
|
|
|
90
90
|
});
|
|
91
91
|
}
|
|
92
92
|
|
|
93
|
+
/** Every effort ALP knows; no catalog widens a model beyond these. */
|
|
94
|
+
export const EFFORTS = ['none', 'off', 'low', 'medium', 'high', 'xhigh', 'max', 'ultra', 'ultracode'];
|
|
95
|
+
|
|
96
|
+
/** @type {typeof MODELS | undefined} */
|
|
97
|
+
let liveRows;
|
|
98
|
+
/**
|
|
99
|
+
* The rows effort checks consult in this process (t-086c): alpd's runtime installs its live catalog
|
|
100
|
+
* here as it changes, and alp setup the cached one it read. Nothing here reads the network; without
|
|
101
|
+
* rows, MODELS serve. @param {typeof MODELS | undefined} rows
|
|
102
|
+
*/
|
|
103
|
+
export function useLiveModels(rows) { liveRows = Array.isArray(rows) && rows.length ? rows : undefined; }
|
|
104
|
+
/** The live rows when this process has them, else MODELS. */
|
|
105
|
+
export const knownModels = () => liveRows ?? MODELS;
|
|
106
|
+
/**
|
|
107
|
+
* The row for a runtime-prefixed model id, its efforts kept to EFFORTS; undefined for a model no
|
|
108
|
+
* catalog lists (any effort in EFFORTS stays accepted for it). @param {string} id
|
|
109
|
+
*/
|
|
110
|
+
export function knownModel(id) {
|
|
111
|
+
const row = knownModels().find(model => `${model.runtime}:${model.id}` === id);
|
|
112
|
+
if (!row) return undefined;
|
|
113
|
+
const efforts = (row.efforts ?? []).filter(effort => EFFORTS.includes(effort));
|
|
114
|
+
return { ...row, efforts, ...(row.effort && efforts.includes(row.effort) ? { effort: row.effort } : { effort: undefined }) };
|
|
115
|
+
}
|
|
116
|
+
|
|
93
117
|
/** Where alpd caches the live catalog: ALP_HOME/cache/models.json. @param {string} home */
|
|
94
118
|
export const catalogCacheFile = home => path.join(home, 'cache', 'models.json');
|
|
95
119
|
|