@anhlp/alp-core 0.0.1-beta.6 → 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.
Files changed (135) hide show
  1. package/dist/bridges.d.ts +5 -6
  2. package/dist/bridges.js +3 -4
  3. package/dist/library-edit.d.ts +51 -2
  4. package/dist/library-edit.js +160 -8
  5. package/dist/library.d.ts +14 -1
  6. package/dist/library.js +73 -5
  7. package/dist/models.d.ts +35 -0
  8. package/dist/models.js +17 -1
  9. package/dist/packaged.d.ts +37 -45
  10. package/dist/packaged.js +42 -156
  11. package/dist/packs.d.ts +57 -0
  12. package/dist/packs.js +247 -0
  13. package/dist/permissions.d.ts +3 -2
  14. package/dist/permissions.js +6 -3
  15. package/dist/profiles.js +6 -6
  16. package/dist/providers.d.ts +2 -5
  17. package/dist/providers.js +22 -6
  18. package/dist/skill-validate.d.ts +85 -0
  19. package/dist/skill-validate.js +298 -0
  20. package/dist/template-path.d.ts +2 -2
  21. package/dist/template-path.js +0 -5
  22. package/dist/types.d.ts +2 -0
  23. package/dist/upgrade.d.ts +10 -0
  24. package/dist/upgrade.js +112 -6
  25. package/dist/validation.js +6 -6
  26. package/package.json +18 -2
  27. package/src/bridges.js +9 -10
  28. package/src/library-edit.js +170 -8
  29. package/src/library.js +96 -6
  30. package/src/models.js +24 -0
  31. package/src/packaged.js +74 -191
  32. package/src/packs.js +246 -0
  33. package/src/permissions.d.ts +3 -2
  34. package/src/permissions.js +13 -3
  35. package/src/profiles.js +7 -7
  36. package/src/providers.js +22 -8
  37. package/src/resolver.js +1 -1
  38. package/src/skill-validate.js +287 -0
  39. package/src/template-path.js +1 -6
  40. package/src/types.d.ts +2 -0
  41. package/src/upgrade.js +54 -6
  42. package/src/validation.js +8 -7
  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
package/dist/bridges.d.ts CHANGED
@@ -1,8 +1,7 @@
1
1
  /** Runs a bridge in this process, as `node -e` would. @param {string} kind */
2
2
  export function runBridge(kind: string): void;
3
3
  /**
4
- * The command an agent CLI runs to start a bridge: `node -e <source>` under Node, the executable's
5
- * `bridge <kind>` subcommand when packaged.
4
+ * The command an agent CLI runs to start a bridge: `node -e <source>` under this Node.
6
5
  * @param {'acp' | 'antigravity'} kind
7
6
  * @returns {{ command: string, args: string[] }}
8
7
  */
@@ -11,8 +10,8 @@ export function bridgeCommand(kind: "acp" | "antigravity"): {
11
10
  args: string[];
12
11
  };
13
12
  /**
14
- * Whether an MCP server entry is one of ALP's bridge launchers: the `-e` source, or the ALP
15
- * executable's `bridge <kind>` (only when its command is named alp, so another server is kept).
13
+ * Whether an MCP server entry is one of ALP's bridge launchers: the `-e` source, or `alp bridge <kind>`
14
+ * as the single-file executable of 0.0.1-beta.5/6 wrote it (only when its command is named alp, so another server is kept).
16
15
  * @param {'acp' | 'antigravity'} kind
17
16
  * @param {unknown} args
18
17
  * @param {unknown} [command]
@@ -20,8 +19,8 @@ export function bridgeCommand(kind: "acp" | "antigravity"): {
20
19
  export function isBridgeArgs(kind: "acp" | "antigravity", args: unknown, command?: unknown): boolean;
21
20
  /**
22
21
  * The stdio MCP bridges an agent CLI starts to reach alpd's tools (ACP agents and Antigravity).
23
- * Under Node they run as `node -e <source>`; the ALP executable cannot evaluate `-e`, so it runs
24
- * them as `alp bridge acp|antigravity`, which calls runBridge (t-1e02).
22
+ * They run as `node -e <source>`; `alp bridge acp|antigravity` (which calls runBridge) remains for
23
+ * the MCP entries the single-file executable of 0.0.1-beta.5/6 wrote.
25
24
  */
26
25
  export const ACP_BRIDGE: "\nconst net = require('node:net');\nconst readline = require('node:readline');\nconst socket = net.connect(process.env.ALP_BRIDGE_SOCKET);\nconst waiting = new Map();\nlet sequence = 0;\nlet buffer = '';\nsocket.setEncoding('utf8');\nsocket.write(JSON.stringify({ token: process.env.ALP_BRIDGE_TOKEN }) + '\\n');\nsocket.on('data', data => {\n buffer += data;\n for (let index; (index = buffer.indexOf('\\n')) >= 0;) {\n const line = buffer.slice(0, index); buffer = buffer.slice(index + 1);\n try { const message = JSON.parse(line); const waiter = waiting.get(message.id); if (waiter) { waiting.delete(message.id); waiter(message); } } catch {}\n }\n});\nsocket.on('close', () => process.exit(0));\nsocket.on('error', () => process.exit(1));\nconst ask = message => new Promise(resolve => { const id = ++sequence; waiting.set(id, resolve); socket.write(JSON.stringify({ ...message, id }) + '\\n'); });\nconst send = value => process.stdout.write(JSON.stringify({ jsonrpc: '2.0', ...value }) + '\\n');\nreadline.createInterface({ input: process.stdin }).on('line', async line => {\n let message; try { message = JSON.parse(line); } catch { return; }\n if (message.id === undefined || message.id === null) return;\n try {\n if (message.method === 'initialize') return send({ id: message.id, result: { protocolVersion: (message.params && message.params.protocolVersion) || '2025-06-18', capabilities: { tools: {} }, serverInfo: { name: 'alp', version: '1' } } });\n if (message.method === 'ping') return send({ id: message.id, result: {} });\n if (message.method === 'tools/list') { const reply = await ask({ op: 'list' }); return send({ id: message.id, result: { tools: reply.tools } }); }\n if (message.method === 'tools/call') { const reply = await ask({ op: 'call', name: message.params.name, arguments: message.params.arguments || {} }); return send({ id: message.id, result: reply.result }); }\n send({ id: message.id, error: { code: -32601, message: 'Method not found' } });\n } catch (error) { send({ id: message.id, error: { code: -32603, message: String((error && error.message) || error) } }); }\n});\nprocess.stdin.on('end', () => process.exit(0));\n";
27
26
  export const ANTIGRAVITY_BRIDGE: "// ALP Antigravity bridge v1\n\nconst net = require('node:net');\nconst readline = require('node:readline');\nconst socket = process.env.ALP_BRIDGE_SOCKET ? net.connect(process.env.ALP_BRIDGE_SOCKET) : null;\nconst waiting = new Map();\nlet sequence = 0;\nlet buffer = '';\nsocket?.setEncoding('utf8');\nsocket?.write(JSON.stringify({ token: process.env.ALP_BRIDGE_TOKEN }) + '\\n');\nsocket?.on('data', data => {\n buffer += data;\n for (let index; (index = buffer.indexOf('\\n')) >= 0;) {\n const line = buffer.slice(0, index); buffer = buffer.slice(index + 1);\n try { const message = JSON.parse(line); const waiter = waiting.get(message.id); if (waiter) { waiting.delete(message.id); waiter(message); } } catch {}\n }\n});\nsocket?.on('close', () => process.exit(0));\nsocket?.on('error', () => process.exit(1));\nconst ask = message => !socket ? Promise.resolve({ tools: [], result: { content: [{ type: 'text', text: 'No ALP session' }], isError: true } }) : new Promise(resolve => { const id = ++sequence; waiting.set(id, resolve); socket.write(JSON.stringify({ ...message, id }) + '\\n'); });\nconst send = value => process.stdout.write(JSON.stringify({ jsonrpc: '2.0', ...value }) + '\\n');\nreadline.createInterface({ input: process.stdin }).on('line', async line => {\n let message; try { message = JSON.parse(line); } catch { return; }\n if (message.id === undefined || message.id === null) return;\n try {\n if (message.method === 'initialize') return send({ id: message.id, result: { protocolVersion: (message.params && message.params.protocolVersion) || '2025-06-18', capabilities: { tools: {} }, serverInfo: { name: 'alp', version: '1' } } });\n if (message.method === 'ping') return send({ id: message.id, result: {} });\n if (message.method === 'tools/list') { const reply = await ask({ op: 'list' }); return send({ id: message.id, result: { tools: reply.tools } }); }\n if (message.method === 'tools/call') { const reply = await ask({ op: 'call', name: message.params.name, arguments: message.params.arguments || {} }); return send({ id: message.id, result: reply.result }); }\n send({ id: message.id, error: { code: -32601, message: 'Method not found' } });\n } catch (error) { send({ id: message.id, error: { code: -32603, message: String((error && error.message) || error) } }); }\n});\nprocess.stdin.on('end', () => process.exit(0));\n";
package/dist/bridges.js CHANGED
@@ -1,6 +1,6 @@
1
1
  // packages/core/src/bridges.js
2
2
  import { createRequire } from "node:module";
3
- import { isExecutableName, isPackaged, isSelf, ROLE_ARGS } from "./packaged.js";
3
+ import { isExecutableName, stablePath } from "./packaged.js";
4
4
  var ACP_BRIDGE = `
5
5
  const net = require('node:net');
6
6
  const readline = require('node:readline');
@@ -79,14 +79,13 @@ function runBridge(kind) {
79
79
  }
80
80
  function bridgeCommand(kind) {
81
81
  if (!Object.hasOwn(BRIDGES, kind)) throw new Error(`Unknown bridge: ${kind}; expected acp or antigravity`);
82
- if (isPackaged()) return { command: process.execPath, args: [...ROLE_ARGS[kind === "acp" ? "bridge-acp" : "bridge-antigravity"]] };
83
- return { command: process.execPath, args: ["-e", BRIDGES[kind]] };
82
+ return { command: stablePath(process.execPath), args: ["-e", BRIDGES[kind]] };
84
83
  }
85
84
  function isBridgeArgs(kind, args, command = void 0) {
86
85
  if (!Array.isArray(args)) return false;
87
86
  const marker = kind === "antigravity" ? "// ALP Antigravity bridge v1" : void 0;
88
87
  if (marker && args.some((arg) => typeof arg === "string" && arg.startsWith(marker))) return true;
89
- return typeof command === "string" && (isExecutableName(command) || isSelf(command)) && args.length === 2 && args[0] === "bridge" && args[1] === kind;
88
+ return typeof command === "string" && isExecutableName(command) && args.length === 2 && args[0] === "bridge" && args[1] === kind;
90
89
  }
91
90
  export {
92
91
  ACP_BRIDGE,
@@ -1,3 +1,8 @@
1
+ /**
2
+ * A SKILL.md with its frontmatter `name` set to `name`, so a copied or renamed skill stays valid:
3
+ * the name must equal the skill's directory. A SKILL.md without frontmatter is left as it is.
4
+ */
5
+ export function withSkillName(body: any, name: any): any;
1
6
  /** Strict payload contract for opt-in project-data writes. Instructions carry prompt authority;
2
7
  * executable configuration and references to it have no place in this policy. */
3
8
  export function assertProjectDataContent(kind: any, content: any): void;
@@ -33,6 +38,31 @@ export function givenSkills(library: any, agent: any): Promise<string[]>;
33
38
  export function setGivenSkills(agent: any, skills: any, { library }?: {}): Promise<{
34
39
  skills: string[];
35
40
  }>;
41
+ /**
42
+ * The library's retired skills, newest first. `roles` is what retired.json recorded,
43
+ * or null for a skill retired before ALP wrote it.
44
+ * @returns {Promise<{ name: string, directory: string, retiredAt: string, roles: string[] | null, agent: string | null }[]>}
45
+ */
46
+ export function listRetiredSkills({ library }?: {}): Promise<{
47
+ name: string;
48
+ directory: string;
49
+ retiredAt: string;
50
+ roles: string[] | null;
51
+ agent: string | null;
52
+ }[]>;
53
+ /**
54
+ * Moves a retired skill back to <library>/skills/<name> and gives it to roles again in
55
+ * role-skills.json: `roles` when given ([] for none), else the roles retired.json recorded.
56
+ * Takes `from` when given, else the newest retired copy of the name. Refuses when the
57
+ * library already has the skill, or when neither `roles` nor retired.json says the roles.
58
+ * @returns {Promise<{ name: string, restored: string, from: string, roles: string[] }>}
59
+ */
60
+ export function restoreSkill(name: any, { library, from, roles }?: {}): Promise<{
61
+ name: string;
62
+ restored: string;
63
+ from: string;
64
+ roles: string[];
65
+ }>;
36
66
  /** Every entry of a kind with its source and users, as `alp <kind>` lists them. */
37
67
  export function listEntries(kind: any, { root, library, templates }?: {}): Promise<{
38
68
  name: string;
@@ -53,10 +83,25 @@ export function usersOf(kind: any, name: any, { root, library, templates }?: {})
53
83
  /**
54
84
  * Creates or replaces an entry in a scope. `revision` is what getEntry returned for
55
85
  * that scope (null to create); a different current revision refuses the save.
56
- * @returns {Promise<{ revision: string | null }>}
86
+ * `strict` (the CLI creating a skill): a new skill must meet the skill format; `warnings` names
87
+ * files its SKILL.md points to that are not there yet. Edits and other callers are unchanged.
88
+ * @param {string} kind
89
+ * @param {string} name
90
+ * @param {any} content
91
+ * @param {{ scope?: any, root?: string, library?: string, templates?: Record<string, string>, revision?: string | null, policy?: string, strict?: boolean }} [options]
92
+ * @returns {Promise<{ revision: string | null, warnings?: string[] }>}
57
93
  */
58
- export function saveEntry(kind: any, name: any, content: any, { scope, root, library, templates, revision, policy }?: {}): Promise<{
94
+ export function saveEntry(kind: string, name: string, content: any, { scope, root, library, templates, revision, policy, strict }?: {
95
+ scope?: any;
96
+ root?: string;
97
+ library?: string;
98
+ templates?: Record<string, string>;
99
+ revision?: string | null;
100
+ policy?: string;
101
+ strict?: boolean;
102
+ }): Promise<{
59
103
  revision: string | null;
104
+ warnings?: string[];
60
105
  }>;
61
106
  /**
62
107
  * Removes an entry from a scope. When nothing else of that name is left below it, an
@@ -70,6 +115,7 @@ export function deleteEntry(kind: any, name: any, { scope, root, library, templa
70
115
  /** Copies the entry that applies under `from` to a new entry `to` in a scope; built-ins are copied this way. */
71
116
  export function duplicateEntry(kind: any, from: any, to: any, { scope, root, library, templates, policy }?: {}): Promise<{
72
117
  revision: string | null;
118
+ warnings?: string[];
73
119
  }>;
74
120
  /** Renames an entry within a scope; refused while others refer to it by its old name. */
75
121
  export function renameEntry(kind: any, from: any, to: any, { scope, root, library, templates, policy }?: {}): Promise<{
@@ -91,3 +137,6 @@ export function renameEntry(kind: any, from: any, to: any, { scope, root, librar
91
137
  * providers { provider } providers/<name>.json, in the library only (ALPD §46)
92
138
  */
93
139
  export const EDIT_KINDS: string[];
140
+ /** Where alp_skill_retire keeps retired skills, and the metadata file it writes in each. */
141
+ export const RETIRED_SKILLS: "retired-skills";
142
+ export const RETIRED_METADATA: "retired.json";
@@ -1,5 +1,5 @@
1
1
  // packages/core/src/library-edit.js
2
- import { lstat, mkdir, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
2
+ import { cp, lstat, mkdir, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
3
3
  import { createHash, randomUUID } from "node:crypto";
4
4
  import path from "node:path";
5
5
  import { moveFile } from "./atomic.js";
@@ -9,6 +9,19 @@ import { agentSources, builtinText, jsonObject, libraryEntries, optionalText } f
9
9
  import { teamSources, validateTeam } from "./teams.js";
10
10
  import { normalizeMcp, validateAgentConfig, validateHook } from "./validation.js";
11
11
  import { validateProvider } from "./providers.js";
12
+ import { checkFrontmatter, skillReferences, specName, splitSkill } from "./skill-validate.js";
13
+ function withSkillName(body, name) {
14
+ const match = /^(\uFEFF?---(\r?\n))([\s\S]*?)(\r?\n---[ \t]*(?:\r?\n|$))/.exec(body);
15
+ if (!match) return body;
16
+ const lines = match[3].split(/\r?\n/);
17
+ const at = lines.findIndex((line) => /^name[ \t]*:/.test(line));
18
+ if (at >= 0) lines[at] = `name: ${name}`;
19
+ else lines.unshift(`name: ${name}`);
20
+ return match[1] + lines.join(match[2]) + match[4] + body.slice(match[0].length);
21
+ }
22
+ function skillTarget(body, name) {
23
+ if (splitSkill(body).frontmatter !== void 0 && !specName(name)) fail("INVALID_NAME", `'${name}' is not a skill name: use 1-64 lowercase letters, digits and single hyphens`);
24
+ }
12
25
  var EDIT_KINDS = ["agents", "skills", "mcp", "hooks", "teams", "providers"];
13
26
  var validName = (name) => typeof name === "string" && /^[\w.-]+$/.test(name) && name !== "." && name !== "..";
14
27
  var object = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
@@ -152,7 +165,7 @@ async function getEntry(kind, name, { root, library, templates, scope } = {}) {
152
165
  async function readGiven(library) {
153
166
  const file = path.join(library, "role-skills.json");
154
167
  const text = await optionalText(file);
155
- if (text === void 0) return { file, roles: {} };
168
+ if (text === void 0) return { file, roles: /* @__PURE__ */ Object.create(null) };
156
169
  let roles;
157
170
  try {
158
171
  roles = JSON.parse(text);
@@ -160,7 +173,7 @@ async function readGiven(library) {
160
173
  throw new AlpError("INVALID_LIBRARY", `${file}: ${cause.message}`, { cause });
161
174
  }
162
175
  if (!object(roles)) fail("INVALID_LIBRARY", `${file}: expected an object of agent names to skill lists`);
163
- return { file, roles };
176
+ return { file, roles: Object.assign(/* @__PURE__ */ Object.create(null), roles) };
164
177
  }
165
178
  async function givenSkills(library, agent) {
166
179
  const { roles } = await readGiven(library);
@@ -178,6 +191,99 @@ async function setGivenSkills(agent, skills, { library } = {}) {
178
191
  await writeAtomic(file, JSON.stringify(roles, null, 2) + "\n");
179
192
  return { skills: unique };
180
193
  }
194
+ var RETIRED_SKILLS = "retired-skills";
195
+ var RETIRED_METADATA = "retired.json";
196
+ var RETIRED_FOLDER = /^(.+)-(\d{4}-\d\d-\d\dT\d\d-\d\d-\d\d-\d{3}Z)$/;
197
+ async function retiredMetadata(directory) {
198
+ const text = await optionalText(path.join(directory, RETIRED_METADATA));
199
+ if (text === void 0) return void 0;
200
+ let data;
201
+ try {
202
+ data = JSON.parse(text);
203
+ } catch (cause) {
204
+ throw new AlpError("INVALID_LIBRARY", `${path.join(directory, RETIRED_METADATA)}: ${cause.message}`, { cause });
205
+ }
206
+ if (!object(data) || !Array.isArray(data.roles) || !data.roles.every(validName)) fail("INVALID_LIBRARY", `${path.join(directory, RETIRED_METADATA)}: expected { name, roles: [...] }`);
207
+ return data;
208
+ }
209
+ async function listRetiredSkills({ library } = {}) {
210
+ if (!library) fail("INVALID_SCOPE", "No library: ALP_HOME is not set");
211
+ const root = path.join(library, RETIRED_SKILLS);
212
+ const entries = await readdir(root, { withFileTypes: true }).catch((error) => {
213
+ if (error.code === "ENOENT") return [];
214
+ throw error;
215
+ });
216
+ const rows = [];
217
+ for (const entry of entries) {
218
+ const match = entry.isDirectory() && RETIRED_FOLDER.exec(entry.name);
219
+ if (!match) continue;
220
+ const directory = path.join(root, entry.name);
221
+ let meta, invalid;
222
+ try {
223
+ meta = await retiredMetadata(directory);
224
+ } catch (error) {
225
+ invalid = error.message;
226
+ }
227
+ const stamp = match[2].replace(/T(\d\d)-(\d\d)-(\d\d)-(\d{3})Z$/, "T$1:$2:$3.$4Z");
228
+ 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 } : {} });
229
+ }
230
+ return rows.sort((a, b) => b.retiredAt.localeCompare(a.retiredAt) || b.directory.localeCompare(a.directory));
231
+ }
232
+ async function restoreSkill(name, { library, from, roles } = {}) {
233
+ nameOf(name);
234
+ if (!library) fail("INVALID_SCOPE", "No library: ALP_HOME is not set");
235
+ if (roles !== void 0 && (!Array.isArray(roles) || !roles.every(validName))) fail("INVALID_ENTRY", "Roles must be a list of agent names");
236
+ let source;
237
+ if (from !== void 0) {
238
+ source = path.resolve(from);
239
+ const info = await lstat(source).catch(() => void 0);
240
+ if (info?.isSymbolicLink()) fail("INVALID_ENTRY", `${source} is a symbolic link; pass the directory itself`);
241
+ if (!info?.isDirectory()) fail("NOT_FOUND", `${source} is not a directory`);
242
+ } else {
243
+ const found = (await listRetiredSkills({ library })).find((row) => row.name === name);
244
+ if (!found) fail("NOT_FOUND", `No retired skill '${name}' in ${path.join(library, RETIRED_SKILLS)}`);
245
+ source = found.directory;
246
+ }
247
+ if (!await exists(path.join(source, "SKILL.md"))) fail("NOT_FOUND", `${source} has no SKILL.md`);
248
+ const target = path.join(library, "skills", name);
249
+ if (await lstat(target).then(() => true, () => false)) fail("ALREADY_EXISTS", `The library already has a skill '${name}' (${target}); nothing was restored`);
250
+ const metaFile = path.join(source, RETIRED_METADATA);
251
+ const metaText = await optionalText(metaFile);
252
+ let meta;
253
+ try {
254
+ meta = await retiredMetadata(source);
255
+ } catch (error) {
256
+ if (error?.code !== "INVALID_LIBRARY" || roles === void 0) throw error;
257
+ }
258
+ if (meta && meta.name !== void 0 && meta.name !== name) fail("INVALID_ENTRY", `${metaFile} is for the skill '${meta.name}', not '${name}'`);
259
+ const given = roles ?? meta?.roles;
260
+ if (!given) fail("ROLES_REQUIRED", `${source} does not record the roles that had '${name}'; pass --roles a,b or --no-roles`);
261
+ const unique = [...new Set(given)];
262
+ const { file: rolesFile, roles: current } = await readGiven(library);
263
+ const before = await optionalText(rolesFile);
264
+ await mkdir(path.dirname(target), { recursive: true });
265
+ await moveFile(source, target);
266
+ try {
267
+ if (metaText !== void 0) await rm(path.join(target, RETIRED_METADATA), { force: true });
268
+ if (unique.length) {
269
+ for (const role of unique) {
270
+ const list = Array.isArray(current[role]) ? current[role] : [];
271
+ if (!list.includes(name)) list.push(name);
272
+ current[role] = list;
273
+ }
274
+ await writeAtomic(rolesFile, JSON.stringify(current, null, 2) + "\n");
275
+ }
276
+ } catch (error) {
277
+ if (before !== void 0) await writeAtomic(rolesFile, before).catch(() => {
278
+ });
279
+ if (metaText !== void 0) await writeFile(path.join(target, RETIRED_METADATA), metaText).catch(() => {
280
+ });
281
+ await moveFile(target, source).catch(() => {
282
+ });
283
+ throw error;
284
+ }
285
+ return { name, restored: target, from: source, roles: unique };
286
+ }
181
287
  async function listEntries(kind, { root, library, templates } = {}) {
182
288
  kindOf(kind);
183
289
  if (kind !== "teams") return libraryEntries(kind, root, { library, templates });
@@ -272,9 +378,16 @@ async function writeAtomic(file, text) {
272
378
  await moveFile(temporary, file);
273
379
  }
274
380
  var exists = (target) => stat(target).then(() => true, () => false);
275
- async function saveEntry(kind, name, content, { scope, root, library, templates, revision, policy } = {}) {
381
+ async function saveEntry(kind, name, content, { scope, root, library, templates, revision, policy, strict = false } = {}) {
276
382
  kindOf(kind);
277
383
  nameOf(name);
384
+ const warnings = [];
385
+ if (strict && kind === "skills" && revision === null && typeof content?.body === "string") {
386
+ const errors = checkFrontmatter(splitSkill(content.body).frontmatter, name, { strict: true }).findings.filter((finding) => finding.level === "error");
387
+ if (errors.length) fail("INVALID_ENTRY", `skills '${name}' does not meet the skill format: ${errors.map((finding) => finding.message).join("; ")}`);
388
+ const links = skillReferences(splitSkill(content.body).body);
389
+ 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`);
390
+ }
278
391
  if (policy === "project-data") {
279
392
  assertProjectDataContent(kind, content);
280
393
  await projectDataEntry(kind, name, { scope, root, library, templates });
@@ -298,7 +411,7 @@ async function saveEntry(kind, name, content, { scope, root, library, templates,
298
411
  await writeAtomic(target, type === "json" ? JSON.stringify(value, null, 2) + "\n" : value.endsWith("\n") ? value : `${value}
299
412
  `);
300
413
  }
301
- return { revision: revisionOf(await readLayer(kind, name, directory)) };
414
+ return { revision: revisionOf(await readLayer(kind, name, directory)), ...warnings.length ? { warnings } : {} };
302
415
  }
303
416
  async function deleteEntry(kind, name, { scope, root, library, templates, revision, policy } = {}) {
304
417
  kindOf(kind);
@@ -327,8 +440,40 @@ async function duplicateEntry(kind, from, to, { scope, root, library, templates,
327
440
  await projectDataEntry(kind, from, { scope, root, library, templates });
328
441
  await projectDataEntry(kind, to, { scope, root, library, templates });
329
442
  }
330
- const { content } = await getEntry(kind, from, { root, library, templates });
331
- return saveEntry(kind, to, structuredClone(content), { scope, root, library, templates, revision: null, policy });
443
+ const entry = await getEntry(kind, from, { root, library, templates });
444
+ if (kind === "skills") {
445
+ skillTarget(entry.content.body, to);
446
+ entry.content.body = withSkillName(entry.content.body, to);
447
+ }
448
+ 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)) : [];
449
+ const saved = await saveEntry(kind, to, structuredClone(entry.content), { scope, root, library, templates, revision: null, policy });
450
+ if (resources.length) {
451
+ const target = path.join(base(scope, { root, library }, kind), kind, to);
452
+ try {
453
+ for (const [source, relative] of resources) await cp(source, path.join(target, relative), { recursive: true, errorOnExist: true, force: false });
454
+ } catch (error) {
455
+ await rm(target, { recursive: true, force: true });
456
+ throw error;
457
+ }
458
+ }
459
+ return saved;
460
+ }
461
+ async function skillResources(directory) {
462
+ const found = [];
463
+ const walk = async (relative) => {
464
+ for (const item of await readdir(path.join(directory, relative), { withFileTypes: true }).catch((error) => {
465
+ if (error.code === "ENOENT") return [];
466
+ throw error;
467
+ })) {
468
+ const rel = path.join(relative, item.name);
469
+ if (item.name === ".git" || item.name === "node_modules") continue;
470
+ if (item.isSymbolicLink()) fail("UNSAFE_LIBRARY_WRITE", `${path.join(directory, rel)} is a symbolic link; copy the skill by hand`);
471
+ if (item.isDirectory()) await walk(rel);
472
+ else if (item.isFile() && rel !== "SKILL.md") found.push([path.join(directory, rel), rel]);
473
+ }
474
+ };
475
+ await walk("");
476
+ return found;
332
477
  }
333
478
  async function renameEntry(kind, from, to, { scope, root, library, templates, policy } = {}) {
334
479
  kindOf(kind);
@@ -345,9 +490,11 @@ async function renameEntry(kind, from, to, { scope, root, library, templates, po
345
490
  const users = await usersOf(kind, from, { root, library, templates });
346
491
  if (users.length) fail("IN_USE", `${kind} '${from}' is used by ${users.join(", ")}; change them first`);
347
492
  await check(kind, to, content, { scope, root, library, templates });
493
+ if (kind === "skills") skillTarget(content.body, to);
348
494
  if (ownDirectory(kind)) {
349
495
  if (await exists(path.join(directory, kind, to))) fail("REVISION_CONFLICT", `${path.join(directory, kind, to)} already exists`);
350
496
  await rename(path.join(directory, kind, from), path.join(directory, kind, to));
497
+ if (kind === "skills" && withSkillName(content.body, to) !== content.body) await writeAtomic(path.join(directory, kind, to, "SKILL.md"), withSkillName(content.body, to));
351
498
  } else {
352
499
  await rename(path.join(directory, kind, `${from}.json`), path.join(directory, kind, `${to}.json`));
353
500
  }
@@ -355,14 +502,19 @@ async function renameEntry(kind, from, to, { scope, root, library, templates, po
355
502
  }
356
503
  export {
357
504
  EDIT_KINDS,
505
+ RETIRED_METADATA,
506
+ RETIRED_SKILLS,
358
507
  assertProjectDataContent,
359
508
  deleteEntry,
360
509
  duplicateEntry,
361
510
  getEntry,
362
511
  givenSkills,
363
512
  listEntries,
513
+ listRetiredSkills,
364
514
  renameEntry,
515
+ restoreSkill,
365
516
  saveEntry,
366
517
  setGivenSkills,
367
- usersOf
518
+ usersOf,
519
+ withSkillName
368
520
  };
package/dist/library.d.ts CHANGED
@@ -9,15 +9,20 @@ export function alpHome(env?: NodeJS.ProcessEnv): string;
9
9
  /**
10
10
  * Seeds or updates the library in `home`. A file is written when ALP never
11
11
  * shipped it before, and replaced only while it still holds what ALP last wrote.
12
+ * With `offerRoleSkills` (alp upgrade, alp update-template), an edited role-skills.json
13
+ * is also offered the built-in role skills it never was (offerRoleSkills above).
12
14
  * @param {string} home
13
- * @param {{ templateRoot?: URL, templates?: Record<string, string> }} [options]
15
+ * @param {{ templateRoot?: URL, templates?: Record<string, string>, offerRoleSkills?: boolean }} [options]
16
+ * @returns {Promise<{ created: string[], updated: string[], offered?: string[] }>} offered only with offerRoleSkills
14
17
  */
15
18
  export function seedLibrary(home: string, options?: {
16
19
  templateRoot?: URL;
17
20
  templates?: Record<string, string>;
21
+ offerRoleSkills?: boolean;
18
22
  }): Promise<{
19
23
  created: string[];
20
24
  updated: string[];
25
+ offered?: string[];
21
26
  }>;
22
27
  /** Seeds a library once per process; sessions call it on every open. */
23
28
  export function ensureLibrary(home: any, options?: {}): any;
@@ -26,3 +31,11 @@ export function librarySkills(home: any, agent: any): Promise<{
26
31
  name: any;
27
32
  path: string;
28
33
  }[]>;
34
+ /**
35
+ * Every role-skills.json ALP shipped, by sha (CRLF-normalized), with what it gave each role. A
36
+ * library's manifest names the one ALP last wrote, so the built-in skills its user has already been
37
+ * offered are known for a library from before `roleSkillsOffered` was recorded (t-de1a). Add each
38
+ * new shipped version here (packages/core/tests/role-skills-offer.test.js checks the current one is).
39
+ * @type {Readonly<Record<string, Record<string, string[]>>>}
40
+ */
41
+ export const SHIPPED_ROLE_SKILLS: Readonly<Record<string, Record<string, string[]>>>;
package/dist/library.js CHANGED
@@ -1,6 +1,6 @@
1
1
  // packages/core/src/library.js
2
2
  import { shippedTemplateRoot } from "./template-path.js";
3
- import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
3
+ import { chmod, mkdir, readFile, readdir, writeFile } from "node:fs/promises";
4
4
  import { moveFile } from "./atomic.js";
5
5
  import { createHash, randomUUID } from "node:crypto";
6
6
  import os from "node:os";
@@ -33,6 +33,64 @@ async function shippedFiles({ templateRoot, templates }) {
33
33
  await walk("providers");
34
34
  return files;
35
35
  }
36
+ var SHIPPED_ROLE_SKILLS = Object.freeze({
37
+ // 0086846 (2026-10-07)
38
+ "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"] },
39
+ // 9ccd54c (2026-10-08): oracle and reviewer, with none
40
+ "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"] },
41
+ // 61181b5 (2026-10-09): supervisor, with none
42
+ "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"] },
43
+ // 9180aa1 (2026-10-29): compact for main
44
+ "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"] },
45
+ // f4d7986 (2026-10-29): curate for main
46
+ "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"] },
47
+ // Skill system v2 (2026-11-05): engineering core skills; reviewer gets its first two
48
+ "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"] }
49
+ });
50
+ var rolePairs = (roles) => roles && typeof roles === "object" && !Array.isArray(roles) ? Object.entries(roles).flatMap(([role, names]) => Array.isArray(names) ? names.filter(skillName).map((name) => `${role}/${name}`) : []) : [];
51
+ async function offerRoleSkills(home, manifest, shippedText, seeded) {
52
+ const name = "role-skills.json";
53
+ const shipped = rolePairs(JSON.parse(shippedText));
54
+ const baseline = Array.isArray(manifest.roleSkillsOffered) ? manifest.roleSkillsOffered : seeded !== void 0 && Object.hasOwn(SHIPPED_ROLE_SKILLS, seeded) ? rolePairs(SHIPPED_ROLE_SKILLS[seeded]) : shipped;
55
+ const offered = new Set(baseline.filter((pair) => typeof pair === "string"));
56
+ const fresh = shipped.filter((pair) => !offered.has(pair));
57
+ const record = () => {
58
+ manifest.roleSkillsOffered = [.../* @__PURE__ */ new Set([...offered, ...shipped])].sort();
59
+ };
60
+ if (!fresh.length) {
61
+ const before = JSON.stringify(manifest.roleSkillsOffered);
62
+ record();
63
+ return { added: [], changed: before !== JSON.stringify(manifest.roleSkillsOffered) };
64
+ }
65
+ const target = path.join(home, name);
66
+ const text = await optional(target);
67
+ if (text === void 0) {
68
+ record();
69
+ return { added: [], changed: true };
70
+ }
71
+ let roles;
72
+ try {
73
+ roles = JSON.parse(text);
74
+ } catch {
75
+ return { added: [], changed: false };
76
+ }
77
+ if (!roles || typeof roles !== "object" || Array.isArray(roles)) return { added: [], changed: false };
78
+ const added = [];
79
+ for (const pair of fresh) {
80
+ const [role, skill] = pair.split("/");
81
+ if (!Array.isArray(roles[role]) || roles[role].includes(skill)) continue;
82
+ roles[role].push(skill);
83
+ added.push(pair);
84
+ }
85
+ if (added.length) {
86
+ const next = JSON.stringify(roles, null, 2) + "\n";
87
+ const temporary = `${target}.${randomUUID().slice(0, 8)}.tmp`;
88
+ await writeFile(temporary, next);
89
+ await moveFile(temporary, target);
90
+ }
91
+ record();
92
+ return { added, changed: true };
93
+ }
36
94
  async function seedLibrary(home, options = {}) {
37
95
  const shipped = await shippedFiles(options);
38
96
  await mkdir(home, { recursive: true, mode: 448 });
@@ -41,6 +99,7 @@ async function seedLibrary(home, options = {}) {
41
99
  const manifest = manifestText ? JSON.parse(manifestText) : { files: {} };
42
100
  const created = [];
43
101
  const updated = [];
102
+ const seededRoles = manifest.files["role-skills.json"];
44
103
  for (const [name, content] of Object.entries(shipped).sort(([a], [b]) => a.localeCompare(b))) {
45
104
  const target = path.join(home, ...name.split("/"));
46
105
  const current = await optional(target);
@@ -48,24 +107,32 @@ async function seedLibrary(home, options = {}) {
48
107
  if (seeded === void 0) {
49
108
  if (current !== void 0) continue;
50
109
  await mkdir(path.dirname(target), { recursive: true });
51
- await writeFile(target, content, { flag: "wx" }).catch((error) => {
110
+ const wrote = await writeFile(target, content, { flag: "wx" }).then(() => true, (error) => {
52
111
  if (error.code !== "EEXIST") throw error;
112
+ return false;
53
113
  });
114
+ if (wrote) await keepExecutable(name, target, content);
54
115
  manifest.files[name] = sha(content);
55
116
  created.push(name);
56
117
  } else if (current !== void 0 && sha(current) === seeded && seeded !== sha(content)) {
57
118
  await writeFile(target, content);
119
+ await keepExecutable(name, target, content);
58
120
  manifest.files[name] = sha(content);
59
121
  updated.push(name);
60
122
  }
61
123
  }
62
- if (created.length || updated.length || manifestText === void 0) {
124
+ const offer = options.offerRoleSkills && shipped["role-skills.json"] !== void 0 ? await offerRoleSkills(home, manifest, shipped["role-skills.json"], seededRoles) : void 0;
125
+ if (created.length || updated.length || offer?.changed || manifestText === void 0) {
63
126
  await mkdir(home, { recursive: true });
64
127
  const temporary = `${manifestPath}.${randomUUID().slice(0, 8)}.tmp`;
65
128
  await writeFile(temporary, JSON.stringify(manifest, null, 2) + "\n");
66
129
  await moveFile(temporary, manifestPath);
67
130
  }
68
- return { created, updated };
131
+ return { created, updated, ...options.offerRoleSkills ? { offered: offer?.added ?? [] } : {} };
132
+ }
133
+ async function keepExecutable(name, target, content) {
134
+ if (process.platform === "win32" || !/^skills\/[^/]+\/scripts\//.test(name) || !content.startsWith("#!")) return;
135
+ await chmod(target, 493);
69
136
  }
70
137
  var seeding = /* @__PURE__ */ new Map();
71
138
  function ensureLibrary(home, options = {}) {
@@ -90,7 +157,7 @@ async function librarySkills(home, agent) {
90
157
  } catch (cause) {
91
158
  throw new AlpError("INVALID_LIBRARY", `${file}: ${cause.message}`, { cause });
92
159
  }
93
- if (!roles || typeof roles !== "object" || Array.isArray(roles)) throw new AlpError("INVALID_LIBRARY", `${file}: expected an object of role names to skill lists`);
160
+ if (!roles || typeof roles !== "object" || Array.isArray(roles)) throw new AlpError("INVALID_LIBRARY", `${file}: expected an object of agent names to skill lists`);
94
161
  const names = roles[agent] ?? [];
95
162
  if (!Array.isArray(names) || !names.every(skillName)) throw new AlpError("INVALID_LIBRARY", `${file}: ${agent} must list skill directory names`);
96
163
  const skills = [];
@@ -101,6 +168,7 @@ async function librarySkills(home, agent) {
101
168
  return skills;
102
169
  }
103
170
  export {
171
+ SHIPPED_ROLE_SKILLS,
104
172
  alpHome,
105
173
  ensureLibrary,
106
174
  librarySkills,
package/dist/models.d.ts CHANGED
@@ -17,6 +17,31 @@ export function mergeCatalog(base: typeof MODELS, live: Partial<Record<string, A
17
17
  }> | undefined>>): Array<(typeof MODELS)[number] & {
18
18
  source?: "live" | "fallback" | "static";
19
19
  }>;
20
+ /**
21
+ * The rows effort checks consult in this process (t-086c): alpd's runtime installs its live catalog
22
+ * here as it changes, and alp setup the cached one it read. Nothing here reads the network; without
23
+ * rows, MODELS serve. @param {typeof MODELS | undefined} rows
24
+ */
25
+ export function useLiveModels(rows: typeof MODELS | undefined): void;
26
+ /**
27
+ * The row for a runtime-prefixed model id, its efforts kept to EFFORTS; undefined for a model no
28
+ * catalog lists (any effort in EFFORTS stays accepted for it). @param {string} id
29
+ */
30
+ export function knownModel(id: string): {
31
+ effort: string;
32
+ efforts: string[];
33
+ runtime: "codex" | "claude" | "antigravity";
34
+ id: string;
35
+ label: string;
36
+ description: string;
37
+ } | {
38
+ effort: undefined;
39
+ efforts: string[];
40
+ runtime: "codex" | "claude" | "antigravity";
41
+ id: string;
42
+ label: string;
43
+ description: string;
44
+ } | undefined;
20
45
  /**
21
46
  * The catalog as alpd last saw it, for readers outside alpd (alp setup, the Paseo plugin): static rows
22
47
  * when there is no cache or it is unreadable. @param {string | undefined} home
@@ -47,4 +72,14 @@ export const MODEL_POLICY: {
47
72
  effort: string;
48
73
  };
49
74
  };
75
+ /** Every effort ALP knows; no catalog widens a model beyond these. */
76
+ export const EFFORTS: string[];
77
+ export function knownModels(): {
78
+ runtime: "codex" | "claude" | "antigravity";
79
+ id: string;
80
+ label: string;
81
+ description: string;
82
+ efforts: string[];
83
+ effort?: string;
84
+ }[];
50
85
  export function catalogCacheFile(home: string): string;
package/dist/models.js CHANGED
@@ -74,6 +74,18 @@ function mergeCatalog(base, live) {
74
74
  return policy ? { ...entry, ...policy } : entry;
75
75
  });
76
76
  }
77
+ var EFFORTS = ["none", "off", "low", "medium", "high", "xhigh", "max", "ultra", "ultracode"];
78
+ var liveRows;
79
+ function useLiveModels(rows) {
80
+ liveRows = Array.isArray(rows) && rows.length ? rows : void 0;
81
+ }
82
+ var knownModels = () => liveRows ?? MODELS;
83
+ function knownModel(id) {
84
+ const row = knownModels().find((model) => `${model.runtime}:${model.id}` === id);
85
+ if (!row) return void 0;
86
+ const efforts = (row.efforts ?? []).filter((effort) => EFFORTS.includes(effort));
87
+ return { ...row, efforts, ...row.effort && efforts.includes(row.effort) ? { effort: row.effort } : { effort: void 0 } };
88
+ }
77
89
  var catalogCacheFile = (home) => path.join(home, "cache", "models.json");
78
90
  function catalogModels(home) {
79
91
  if (!home) return MODELS;
@@ -86,9 +98,13 @@ function catalogModels(home) {
86
98
  }
87
99
  }
88
100
  export {
101
+ EFFORTS,
89
102
  MODELS,
90
103
  MODEL_POLICY,
91
104
  catalogCacheFile,
92
105
  catalogModels,
93
- mergeCatalog
106
+ knownModel,
107
+ knownModels,
108
+ mergeCatalog,
109
+ useLiveModels
94
110
  };