@anhlp/alp-core 0.0.1-beta.7 → 0.0.1-beta.9

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.
Files changed (135) hide show
  1. package/dist/bridges.js +2 -2
  2. package/dist/library-edit.d.ts +51 -2
  3. package/dist/library-edit.js +160 -8
  4. package/dist/library.d.ts +14 -1
  5. package/dist/library.js +73 -5
  6. package/dist/models.d.ts +35 -0
  7. package/dist/models.js +17 -1
  8. package/dist/packaged.d.ts +45 -12
  9. package/dist/packaged.js +46 -5
  10. package/dist/packs.d.ts +57 -0
  11. package/dist/packs.js +247 -0
  12. package/dist/permissions.d.ts +3 -2
  13. package/dist/permissions.js +6 -3
  14. package/dist/profiles.js +3 -3
  15. package/dist/providers.d.ts +2 -4
  16. package/dist/providers.js +20 -4
  17. package/dist/skill-validate.d.ts +85 -0
  18. package/dist/skill-validate.js +298 -0
  19. package/dist/upgrade.d.ts +10 -0
  20. package/dist/upgrade.js +112 -6
  21. package/dist/user-settings.d.ts +2 -0
  22. package/dist/user-settings.js +40 -1
  23. package/dist/validation.d.ts +1 -0
  24. package/dist/validation.js +16 -10
  25. package/package.json +18 -2
  26. package/src/bridges.js +3 -2
  27. package/src/library-edit.js +170 -8
  28. package/src/library.js +96 -6
  29. package/src/models.js +24 -0
  30. package/src/packaged.js +77 -8
  31. package/src/packs.js +246 -0
  32. package/src/permissions.d.ts +3 -2
  33. package/src/permissions.js +13 -3
  34. package/src/profiles.js +4 -4
  35. package/src/providers.js +20 -5
  36. package/src/resolver.js +1 -1
  37. package/src/skill-validate.js +287 -0
  38. package/src/upgrade.js +54 -6
  39. package/src/user-settings.d.ts +2 -0
  40. package/src/user-settings.js +51 -1
  41. package/src/validation.d.ts +1 -0
  42. package/src/validation.js +21 -12
  43. package/templates/ALP.md +52 -52
  44. package/templates/agents/lead/AGENT.md +77 -74
  45. package/templates/agents/main/AGENT.md +153 -145
  46. package/templates/agents/oracle/AGENT.md +38 -37
  47. package/templates/agents/peer/AGENT.md +56 -52
  48. package/templates/agents/reviewer/AGENT.md +63 -65
  49. package/templates/agents/supervisor/AGENT.md +63 -63
  50. package/templates/packs/architecture/agents/architect/AGENT.md +41 -0
  51. package/templates/packs/architecture/agents/architect/agent.json +5 -0
  52. package/templates/packs/architecture/agents/docs-maintainer/AGENT.md +33 -0
  53. package/templates/packs/architecture/agents/docs-maintainer/agent.json +4 -0
  54. package/templates/packs/architecture/pack.json +7 -0
  55. package/templates/packs/architecture/teams/blueprint/HOUSE_RULES.md +12 -0
  56. package/templates/packs/architecture/teams/blueprint/team.json +19 -0
  57. package/templates/packs/backend/pack.json +6 -0
  58. package/templates/packs/backend/skills/backend-development/SKILL.md +102 -0
  59. package/templates/packs/backend/skills/backend-development/references/api-design.md +96 -0
  60. package/templates/packs/backend/skills/backend-development/references/authentication.md +78 -0
  61. package/templates/packs/backend/skills/backend-development/references/error-handling.md +86 -0
  62. package/templates/packs/backend/skills/backend-development/references/testing.md +81 -0
  63. package/templates/packs/backend/skills/databases/SKILL.md +103 -0
  64. package/templates/packs/backend/skills/databases/references/query-performance.md +87 -0
  65. package/templates/packs/backend/skills/databases/references/schema-and-migrations.md +87 -0
  66. package/templates/packs/design/pack.json +6 -0
  67. package/templates/packs/design/skills/ui-design/SKILL.md +86 -0
  68. package/templates/packs/design/skills/ui-design/references/design-tokens.md +67 -0
  69. package/templates/packs/design/skills/ui-design/references/interaction-states.md +73 -0
  70. package/templates/packs/design/skills/ui-design/references/layout-and-typography.md +71 -0
  71. package/templates/packs/design/skills/ui-design/references/ui-review.md +83 -0
  72. package/templates/packs/frontend/pack.json +6 -0
  73. package/templates/packs/frontend/skills/frontend-development/SKILL.md +105 -0
  74. package/templates/packs/frontend/skills/frontend-development/references/accessibility.md +86 -0
  75. package/templates/packs/frontend/skills/frontend-development/references/components-and-state.md +79 -0
  76. package/templates/packs/frontend/skills/frontend-development/references/data-fetching.md +86 -0
  77. package/templates/packs/frontend/skills/frontend-development/references/frameworks.md +77 -0
  78. package/templates/packs/frontend/skills/frontend-development/references/performance.md +78 -0
  79. package/templates/packs/integration/pack.json +6 -0
  80. package/templates/packs/integration/skills/mcp-integration/SKILL.md +100 -0
  81. package/templates/packs/integration/skills/mcp-integration/references/server-implementation.md +95 -0
  82. package/templates/packs/integration/skills/mcp-integration/references/testing.md +78 -0
  83. package/templates/packs/integration/skills/mcp-integration/references/tool-design.md +97 -0
  84. package/templates/packs/operations/pack.json +6 -0
  85. package/templates/packs/operations/skills/devops/SKILL.md +85 -0
  86. package/templates/packs/operations/skills/devops/references/ci-cd.md +84 -0
  87. package/templates/packs/operations/skills/devops/references/containers.md +85 -0
  88. package/templates/packs/operations/skills/devops/references/deployment-and-rollback.md +85 -0
  89. package/templates/packs/operations/skills/devops/references/observability.md +86 -0
  90. package/templates/packs/quality/pack.json +6 -0
  91. package/templates/packs/quality/skills/web-testing/SKILL.md +102 -0
  92. package/templates/packs/quality/skills/web-testing/references/e2e.md +85 -0
  93. package/templates/packs/quality/skills/web-testing/references/performance-testing.md +85 -0
  94. package/templates/packs/quality/skills/web-testing/references/security-testing.md +78 -0
  95. package/templates/packs/quality/skills/web-testing/references/unit-and-component.md +78 -0
  96. package/templates/role-skills.json +4 -4
  97. package/templates/skills/architecture-docs/SKILL.md +81 -0
  98. package/templates/skills/architecture-docs/references/adr.md +62 -0
  99. package/templates/skills/architecture-docs/references/diagrams.md +60 -0
  100. package/templates/skills/architecture-docs/references/evidence-rules.md +49 -0
  101. package/templates/skills/bug-loop/SKILL.md +41 -40
  102. package/templates/skills/bug-loop/references/test-proof.md +21 -19
  103. package/templates/skills/compact/SKILL.md +2 -2
  104. package/templates/skills/curate/SKILL.md +6 -5
  105. package/templates/skills/feature-architecture/SKILL.md +90 -0
  106. package/templates/skills/feature-architecture/references/architecture-contract.md +95 -0
  107. package/templates/skills/feature-architecture/references/feature-design.md +69 -0
  108. package/templates/skills/feature-architecture/scripts/check-boundaries.mjs +270 -0
  109. package/templates/skills/goal-griller/SKILL.md +27 -27
  110. package/templates/skills/prompt-leverage/SKILL.md +29 -27
  111. package/templates/skills/prompt-leverage/references/brief-template.md +9 -9
  112. package/templates/skills/release-readiness/SKILL.md +83 -0
  113. package/templates/skills/release-readiness/references/checklist.md +40 -0
  114. package/templates/skills/release-readiness/references/verdict-template.md +53 -0
  115. package/templates/skills/safe-refactor/SKILL.md +84 -0
  116. package/templates/skills/safe-refactor/references/characterization-tests.md +57 -0
  117. package/templates/skills/safe-refactor/references/compatibility-checklist.md +56 -0
  118. package/templates/skills/security-review/SKILL.md +87 -0
  119. package/templates/skills/security-review/references/checklist.md +74 -0
  120. package/templates/skills/security-review/references/severity.md +61 -0
  121. package/templates/skills/sequence-execution-plan/SKILL.md +41 -38
  122. package/templates/skills/sequence-execution-plan/references/plan-template.md +5 -5
  123. package/templates/skills/skill-authoring/SKILL.md +84 -0
  124. package/templates/skills/skill-authoring/references/evaluation.md +45 -0
  125. package/templates/skills/skill-authoring/references/skill-anatomy.md +74 -0
  126. package/templates/skills/skill-authoring/references/trigger-design.md +52 -0
  127. package/templates/skills/smart-commits/SKILL.md +37 -36
  128. package/templates/skills/test-strategy/SKILL.md +83 -0
  129. package/templates/skills/test-strategy/references/contract-tests.md +46 -0
  130. package/templates/skills/test-strategy/references/risk-matrix.md +53 -0
  131. package/templates/skills/xia/SKILL.md +40 -38
  132. package/templates/teams/cafe/HOUSE_RULES.md +1 -1
  133. package/templates/teams/cafe/team.json +1 -1
  134. package/templates/teams/pho/HOUSE_RULES.md +1 -1
  135. package/templates/teams/pho/team.json +1 -1
@@ -1,5 +1,6 @@
1
1
  export const PROJECT_SETTINGS: string[];
2
2
  export const USER_SETTINGS: string[];
3
+ export const DASHBOARD_SETTINGS: readonly string[];
3
4
  export const RETIRED_SETTINGS: { project: Record<string, string>; user: Record<string, string> };
4
5
  export function settingsKeys(settings: unknown, known: string[], retired?: Record<string, string>): { unknown: Array<{ key: string; suggestion?: string }>; retired: Array<{ key: string; instead: string }> };
5
6
  export function settingsWarnings(settings: unknown, scope: 'project' | 'user'): string[];
@@ -1,7 +1,7 @@
1
1
  // packages/core/src/validation.js
2
2
  import path from "node:path";
3
3
  import { AlpError } from "./errors.js";
4
- import { MODELS } from "./models.js";
4
+ import { EFFORTS, knownModel } from "./models.js";
5
5
  import { validatePermissions } from "./permissions.js";
6
6
  import { validateVerify } from "./verify.js";
7
7
  var object = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
@@ -10,9 +10,9 @@ var stringMap = (value) => object(value) && Object.values(value).every((v) => ty
10
10
  function requireValue(condition, code, source, message) {
11
11
  if (!condition) throw new AlpError(code, `${source}: ${message}`);
12
12
  }
13
- var EFFORTS = ["none", "off", "low", "medium", "high", "xhigh", "max", "ultra", "ultracode"];
14
13
  var PROJECT_SETTINGS = ["$schema", "defaultAgent", "workflow", "runtime", "permissions", "verify", "delegation", "team", "profile", "templateDefaults", "compact", "curate"];
15
- var USER_SETTINGS = ["$schema", "language", "permissions", "limits", "recovery", "web", "curate"];
14
+ var USER_SETTINGS = ["$schema", "language", "permissions", "limits", "recovery", "dashboard", "web", "curate"];
15
+ var DASHBOARD_SETTINGS = Object.freeze(["enabled", "port", "permissions"]);
16
16
  var RETIRED_SETTINGS = { project: {}, user: {} };
17
17
  function distance(a, b) {
18
18
  const row = Array.from({ length: b.length + 1 }, (_, index) => index);
@@ -110,7 +110,7 @@ function validateSettings(settings, source) {
110
110
  const [provider, model, effort] = entry.split(":");
111
111
  check(model !== "*" || agent !== "oracle" && agent !== "main", `${at}: ${agent} runs on a named model, not any model`);
112
112
  if (effort !== void 0) {
113
- const known = MODELS.find((candidate) => candidate.runtime === provider && candidate.id === model);
113
+ const known = knownModel(`${provider}:${model}`);
114
114
  check(EFFORTS.includes(effort), `${at}: effort ${effort} is unsupported`);
115
115
  check(!known?.efforts.length || known.efforts.includes(effort), `${at}: ${provider}:${model} takes effort ${known?.efforts.join(", ")}`);
116
116
  }
@@ -160,11 +160,18 @@ function validateUserSettings(settings, source) {
160
160
  check(!extra, `unsupported ${key} field '${extra}'; use autoResume`);
161
161
  if (settings[key].autoResume !== void 0) check(typeof settings[key].autoResume === "boolean", `${key}.autoResume must be true or false`);
162
162
  }
163
+ for (const key of ["dashboard", "web"]) {
164
+ const section = settings[key];
165
+ if (section === void 0) continue;
166
+ check(object(section), `${key} must be an object`);
167
+ const allowed = key === "web" ? [...DASHBOARD_SETTINGS, "relay"] : DASHBOARD_SETTINGS;
168
+ const extra = Object.keys(section).find((field) => !allowed.includes(field));
169
+ check(!extra, `unsupported ${key} field '${extra}'; use ${allowed.slice(0, -1).join(", ")} or ${allowed.at(-1)}`);
170
+ if (section.permissions !== void 0) check(Array.isArray(section.permissions) && section.permissions.every((entry) => typeof entry === "string" && /^[a-z][a-z.]*$/.test(entry)), `${key}.permissions must be a list of permission names, such as files.read`);
171
+ if (section.enabled !== void 0) check(typeof section.enabled === "boolean", `${key}.enabled must be true or false`);
172
+ if (section.port !== void 0) check(Number.isInteger(section.port) && section.port >= 1024 && section.port <= 65535, `${key}.port must be a port from 1024 to 65535`);
173
+ }
163
174
  if (settings.web !== void 0) {
164
- check(object(settings.web), "web must be an object");
165
- const extra = Object.keys(settings.web).find((field) => !["enabled", "port", "relay", "permissions"].includes(field));
166
- check(!extra, `unsupported web field '${extra}'; use enabled, port, relay or permissions`);
167
- if (settings.web.permissions !== void 0) check(Array.isArray(settings.web.permissions) && settings.web.permissions.every((entry) => typeof entry === "string" && /^[a-z][a-z.]*$/.test(entry)), "web.permissions must be a list of permission names, such as files.read");
168
175
  const relay = settings.web.relay;
169
176
  if (relay !== void 0) {
170
177
  check(object(relay), "web.relay must be an object");
@@ -174,8 +181,6 @@ function validateUserSettings(settings, source) {
174
181
  if (relay.endpoint !== void 0) check(typeof relay.endpoint === "string" && /^[a-z0-9.-]+:\d{1,5}$/i.test(relay.endpoint), "web.relay.endpoint must be host:port, such as relay.paseo.sh:443");
175
182
  if (relay.useTls !== void 0) check(typeof relay.useTls === "boolean", "web.relay.useTls must be true or false");
176
183
  }
177
- if (settings.web.enabled !== void 0) check(typeof settings.web.enabled === "boolean", "web.enabled must be true or false");
178
- if (settings.web.port !== void 0) check(Number.isInteger(settings.web.port) && settings.web.port >= 1024 && settings.web.port <= 65535, "web.port must be a port from 1024 to 65535");
179
184
  }
180
185
  if (settings.language !== void 0) check(nonempty(settings.language) && settings.language.trim().length <= 40, "language must be a language name of at most 40 characters, such as Vietnamese or English");
181
186
  validatePermissions(settings.permissions, source);
@@ -294,6 +299,7 @@ export {
294
299
  AGENT_SETTINGS,
295
300
  BLOCKING_HOOK_EVENTS,
296
301
  CONTEXT_TOKENS,
302
+ DASHBOARD_SETTINGS,
297
303
  HOOK_EVENTS,
298
304
  HOOK_SETTINGS,
299
305
  PROJECT_SETTINGS,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@anhlp/alp-core",
3
- "version": "0.0.1-beta.7",
3
+ "version": "0.0.1-beta.9",
4
4
  "type": "module",
5
5
  "description": "ALP core module",
6
6
  "files": [
@@ -294,13 +294,29 @@
294
294
  },
295
295
  "types": "./dist/packaged.d.ts",
296
296
  "default": "./src/packaged.js"
297
+ },
298
+ "./skill-validate": {
299
+ "alp-source": {
300
+ "types": "./src/skill-validate.js",
301
+ "default": "./src/skill-validate.js"
302
+ },
303
+ "types": "./dist/skill-validate.d.ts",
304
+ "default": "./src/skill-validate.js"
305
+ },
306
+ "./packs": {
307
+ "alp-source": {
308
+ "types": "./src/packs.js",
309
+ "default": "./src/packs.js"
310
+ },
311
+ "types": "./dist/packs.d.ts",
312
+ "default": "./src/packs.js"
297
313
  }
298
314
  },
299
315
  "engines": {
300
316
  "node": ">=22.12"
301
317
  },
302
318
  "dependencies": {
303
- "@anhlp/alp-protocol": "0.0.1-beta.7"
319
+ "@anhlp/alp-protocol": "0.0.1-beta.9"
304
320
  },
305
321
  "scripts": {
306
322
  "build": "node ../../scripts/build-workspace.mjs core",
package/src/bridges.js CHANGED
@@ -1,5 +1,5 @@
1
1
  import { createRequire } from 'node:module';
2
- import { isExecutableName, stablePath } from './packaged.js';
2
+ import { isExecutableName, nodeExecutable, stablePath } from './packaged.js';
3
3
 
4
4
  /**
5
5
  * The stdio MCP bridges an agent CLI starts to reach alpd's tools (ACP agents and Antigravity).
@@ -94,7 +94,8 @@ export function runBridge(kind) {
94
94
  export function bridgeCommand(kind) {
95
95
  if (!Object.hasOwn(BRIDGES, kind)) throw new Error(`Unknown bridge: ${kind}; expected acp or antigravity`);
96
96
  // Agents keep this command in their MCP configuration: name the ALP bundle's Node through app/current.
97
- return { command: stablePath(process.execPath), args: ['-e', BRIDGES[kind]] };
97
+ // In the native alpd (t-81b0.9) that is still the bundle's Node: the native alpd does not evaluate -e.
98
+ return { command: stablePath(nodeExecutable()), args: ['-e', BRIDGES[kind]] };
98
99
  }
99
100
 
100
101
  /**
@@ -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
- * @returns {Promise<{ revision: string | null }>}
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 { content } = await getEntry(kind, from, { root, library, templates });
375
- return saveEntry(kind, to, structuredClone(content), { scope, root, library, templates, revision: null, policy });
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> }} [options]
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' }).catch(error => { if (error.code !== 'EEXIST') throw error; });
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
- if (created.length || updated.length || manifestText === undefined) {
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 role names to skill lists`);
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