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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (124) hide show
  1. package/dist/library-edit.d.ts +51 -2
  2. package/dist/library-edit.js +160 -8
  3. package/dist/library.d.ts +14 -1
  4. package/dist/library.js +73 -5
  5. package/dist/models.d.ts +35 -0
  6. package/dist/models.js +17 -1
  7. package/dist/packs.d.ts +57 -0
  8. package/dist/packs.js +247 -0
  9. package/dist/permissions.d.ts +3 -2
  10. package/dist/permissions.js +6 -3
  11. package/dist/profiles.js +3 -3
  12. package/dist/providers.d.ts +2 -4
  13. package/dist/providers.js +20 -4
  14. package/dist/skill-validate.d.ts +85 -0
  15. package/dist/skill-validate.js +298 -0
  16. package/dist/upgrade.d.ts +10 -0
  17. package/dist/upgrade.js +112 -6
  18. package/dist/validation.js +2 -3
  19. package/package.json +18 -2
  20. package/src/library-edit.js +170 -8
  21. package/src/library.js +96 -6
  22. package/src/models.js +24 -0
  23. package/src/packs.js +246 -0
  24. package/src/permissions.d.ts +3 -2
  25. package/src/permissions.js +13 -3
  26. package/src/profiles.js +4 -4
  27. package/src/providers.js +20 -5
  28. package/src/resolver.js +1 -1
  29. package/src/skill-validate.js +287 -0
  30. package/src/upgrade.js +54 -6
  31. package/src/validation.js +3 -4
  32. package/templates/ALP.md +52 -52
  33. package/templates/agents/lead/AGENT.md +77 -74
  34. package/templates/agents/main/AGENT.md +153 -145
  35. package/templates/agents/oracle/AGENT.md +38 -37
  36. package/templates/agents/peer/AGENT.md +56 -52
  37. package/templates/agents/reviewer/AGENT.md +63 -65
  38. package/templates/agents/supervisor/AGENT.md +63 -63
  39. package/templates/packs/architecture/agents/architect/AGENT.md +41 -0
  40. package/templates/packs/architecture/agents/architect/agent.json +5 -0
  41. package/templates/packs/architecture/agents/docs-maintainer/AGENT.md +33 -0
  42. package/templates/packs/architecture/agents/docs-maintainer/agent.json +4 -0
  43. package/templates/packs/architecture/pack.json +7 -0
  44. package/templates/packs/architecture/teams/blueprint/HOUSE_RULES.md +12 -0
  45. package/templates/packs/architecture/teams/blueprint/team.json +19 -0
  46. package/templates/packs/backend/pack.json +6 -0
  47. package/templates/packs/backend/skills/backend-development/SKILL.md +102 -0
  48. package/templates/packs/backend/skills/backend-development/references/api-design.md +96 -0
  49. package/templates/packs/backend/skills/backend-development/references/authentication.md +78 -0
  50. package/templates/packs/backend/skills/backend-development/references/error-handling.md +86 -0
  51. package/templates/packs/backend/skills/backend-development/references/testing.md +81 -0
  52. package/templates/packs/backend/skills/databases/SKILL.md +103 -0
  53. package/templates/packs/backend/skills/databases/references/query-performance.md +87 -0
  54. package/templates/packs/backend/skills/databases/references/schema-and-migrations.md +87 -0
  55. package/templates/packs/design/pack.json +6 -0
  56. package/templates/packs/design/skills/ui-design/SKILL.md +86 -0
  57. package/templates/packs/design/skills/ui-design/references/design-tokens.md +67 -0
  58. package/templates/packs/design/skills/ui-design/references/interaction-states.md +73 -0
  59. package/templates/packs/design/skills/ui-design/references/layout-and-typography.md +71 -0
  60. package/templates/packs/design/skills/ui-design/references/ui-review.md +83 -0
  61. package/templates/packs/frontend/pack.json +6 -0
  62. package/templates/packs/frontend/skills/frontend-development/SKILL.md +105 -0
  63. package/templates/packs/frontend/skills/frontend-development/references/accessibility.md +86 -0
  64. package/templates/packs/frontend/skills/frontend-development/references/components-and-state.md +79 -0
  65. package/templates/packs/frontend/skills/frontend-development/references/data-fetching.md +86 -0
  66. package/templates/packs/frontend/skills/frontend-development/references/frameworks.md +77 -0
  67. package/templates/packs/frontend/skills/frontend-development/references/performance.md +78 -0
  68. package/templates/packs/integration/pack.json +6 -0
  69. package/templates/packs/integration/skills/mcp-integration/SKILL.md +100 -0
  70. package/templates/packs/integration/skills/mcp-integration/references/server-implementation.md +95 -0
  71. package/templates/packs/integration/skills/mcp-integration/references/testing.md +78 -0
  72. package/templates/packs/integration/skills/mcp-integration/references/tool-design.md +97 -0
  73. package/templates/packs/operations/pack.json +6 -0
  74. package/templates/packs/operations/skills/devops/SKILL.md +85 -0
  75. package/templates/packs/operations/skills/devops/references/ci-cd.md +84 -0
  76. package/templates/packs/operations/skills/devops/references/containers.md +85 -0
  77. package/templates/packs/operations/skills/devops/references/deployment-and-rollback.md +85 -0
  78. package/templates/packs/operations/skills/devops/references/observability.md +86 -0
  79. package/templates/packs/quality/pack.json +6 -0
  80. package/templates/packs/quality/skills/web-testing/SKILL.md +102 -0
  81. package/templates/packs/quality/skills/web-testing/references/e2e.md +85 -0
  82. package/templates/packs/quality/skills/web-testing/references/performance-testing.md +85 -0
  83. package/templates/packs/quality/skills/web-testing/references/security-testing.md +78 -0
  84. package/templates/packs/quality/skills/web-testing/references/unit-and-component.md +78 -0
  85. package/templates/role-skills.json +4 -4
  86. package/templates/skills/architecture-docs/SKILL.md +81 -0
  87. package/templates/skills/architecture-docs/references/adr.md +62 -0
  88. package/templates/skills/architecture-docs/references/diagrams.md +60 -0
  89. package/templates/skills/architecture-docs/references/evidence-rules.md +49 -0
  90. package/templates/skills/bug-loop/SKILL.md +41 -40
  91. package/templates/skills/bug-loop/references/test-proof.md +21 -19
  92. package/templates/skills/compact/SKILL.md +2 -2
  93. package/templates/skills/curate/SKILL.md +6 -5
  94. package/templates/skills/feature-architecture/SKILL.md +90 -0
  95. package/templates/skills/feature-architecture/references/architecture-contract.md +95 -0
  96. package/templates/skills/feature-architecture/references/feature-design.md +69 -0
  97. package/templates/skills/feature-architecture/scripts/check-boundaries.mjs +270 -0
  98. package/templates/skills/goal-griller/SKILL.md +27 -27
  99. package/templates/skills/prompt-leverage/SKILL.md +29 -27
  100. package/templates/skills/prompt-leverage/references/brief-template.md +9 -9
  101. package/templates/skills/release-readiness/SKILL.md +83 -0
  102. package/templates/skills/release-readiness/references/checklist.md +40 -0
  103. package/templates/skills/release-readiness/references/verdict-template.md +53 -0
  104. package/templates/skills/safe-refactor/SKILL.md +84 -0
  105. package/templates/skills/safe-refactor/references/characterization-tests.md +57 -0
  106. package/templates/skills/safe-refactor/references/compatibility-checklist.md +56 -0
  107. package/templates/skills/security-review/SKILL.md +87 -0
  108. package/templates/skills/security-review/references/checklist.md +74 -0
  109. package/templates/skills/security-review/references/severity.md +61 -0
  110. package/templates/skills/sequence-execution-plan/SKILL.md +41 -38
  111. package/templates/skills/sequence-execution-plan/references/plan-template.md +5 -5
  112. package/templates/skills/skill-authoring/SKILL.md +84 -0
  113. package/templates/skills/skill-authoring/references/evaluation.md +45 -0
  114. package/templates/skills/skill-authoring/references/skill-anatomy.md +74 -0
  115. package/templates/skills/skill-authoring/references/trigger-design.md +52 -0
  116. package/templates/skills/smart-commits/SKILL.md +37 -36
  117. package/templates/skills/test-strategy/SKILL.md +83 -0
  118. package/templates/skills/test-strategy/references/contract-tests.md +46 -0
  119. package/templates/skills/test-strategy/references/risk-matrix.md +53 -0
  120. package/templates/skills/xia/SKILL.md +40 -38
  121. package/templates/teams/cafe/HOUSE_RULES.md +1 -1
  122. package/templates/teams/cafe/team.json +1 -1
  123. package/templates/teams/pho/HOUSE_RULES.md +1 -1
  124. package/templates/teams/pho/team.json +1 -1
package/dist/packs.js ADDED
@@ -0,0 +1,247 @@
1
+ // packages/core/src/packs.js
2
+ import { chmod, lstat, mkdir, readFile, readdir, realpath, rename, rm, writeFile } from "node:fs/promises";
3
+ import { randomUUID } from "node:crypto";
4
+ import path from "node:path";
5
+ import { moveFile } from "./atomic.js";
6
+ import { AlpError } from "./errors.js";
7
+ import { assertNoSymlinks } from "./safe-path.js";
8
+ import { seedLibrary } from "./library.js";
9
+ import { BASES, validatePermissions } from "./permissions.js";
10
+ import { validateSkill } from "./skill-validate.js";
11
+ import { shippedTemplateRoot } from "./template-path.js";
12
+ import { validateTeam } from "./teams.js";
13
+ import { validateAgentConfig } from "./validation.js";
14
+ var KINDS = ["skills", "agents", "teams"];
15
+ var PACK_KEYS = ["label", "description", ...KINDS, "assign", "permissions"];
16
+ var NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
17
+ var fail = (code, message) => {
18
+ throw new AlpError(code, message);
19
+ };
20
+ var object = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
21
+ async function shippedPackFiles({ templates } = {}) {
22
+ if (templates) return Object.fromEntries(Object.entries(templates).filter(([name]) => name.startsWith("packs/")));
23
+ const root = new URL("packs/", shippedTemplateRoot());
24
+ const files = {};
25
+ const walk = async (relative) => {
26
+ let entries;
27
+ try {
28
+ entries = await readdir(new URL(relative, root), { withFileTypes: true });
29
+ } catch (error) {
30
+ if (error.code === "ENOENT") return;
31
+ throw error;
32
+ }
33
+ for (const entry of entries) {
34
+ if (entry.isDirectory()) await walk(`${relative}${entry.name}/`);
35
+ else if (entry.isFile()) files[`packs/${relative}${entry.name}`] = await readFile(new URL(`${relative}${entry.name}`, root), "utf8");
36
+ }
37
+ };
38
+ await walk("");
39
+ return files;
40
+ }
41
+ function validatePack(id, manifest, files) {
42
+ const where = `packs/${id}/pack.json`;
43
+ const bad = (message) => fail("INVALID_PACK", `${where}: ${message}`);
44
+ if (!object(manifest)) bad("expected a JSON object");
45
+ for (const key of Object.keys(manifest)) if (!PACK_KEYS.includes(key)) bad(`unknown key '${key}'; expected ${PACK_KEYS.join(", ")}`);
46
+ for (const key of ["label", "description"]) if (typeof manifest[key] !== "string" || !manifest[key].trim()) bad(`${key} must be nonempty text`);
47
+ for (const kind of KINDS) {
48
+ const names = manifest[kind] ?? [];
49
+ if (!Array.isArray(names) || !names.every((name) => typeof name === "string" && NAME.test(name))) bad(`${kind} must list entry names`);
50
+ const main = { skills: "SKILL.md", agents: "AGENT.md", teams: "team.json" }[kind];
51
+ for (const name of names) if (files[`packs/${id}/${kind}/${name}/${main}`] === void 0) bad(`${kind} names '${name}', which has no ${kind}/${name}/${main}`);
52
+ }
53
+ if (!(manifest.skills?.length || manifest.agents?.length || manifest.teams?.length)) bad("a pack holds at least one skill, agent or team");
54
+ if (manifest.assign !== void 0) {
55
+ if (!object(manifest.assign)) bad("assign must map roles to skills");
56
+ for (const [role, skills] of Object.entries(manifest.assign)) {
57
+ if (!Array.isArray(skills) || !skills.every((skill) => (manifest.skills ?? []).includes(skill))) bad(`assign.${role} may name only this pack's skills`);
58
+ }
59
+ }
60
+ if (manifest.permissions !== void 0) {
61
+ if (!object(manifest.permissions)) bad("permissions must map agents to a base mode");
62
+ for (const [agent, base] of Object.entries(manifest.permissions)) {
63
+ if (!(manifest.agents ?? []).includes(agent)) bad(`permissions names '${agent}', which is not one of this pack's agents`);
64
+ if (!BASES.includes(base)) bad(`permissions.${agent} must be one of ${BASES.join(", ")}`);
65
+ }
66
+ }
67
+ return manifest;
68
+ }
69
+ async function listPacks(options = {}) {
70
+ const files = await shippedPackFiles(options);
71
+ const ids = [...new Set(Object.keys(files).filter((name) => /^packs\/[^/]+\/pack\.json$/.test(name)).map((name) => name.split("/")[1]))].sort();
72
+ return ids.map((id) => {
73
+ let manifest;
74
+ try {
75
+ manifest = JSON.parse(files[`packs/${id}/pack.json`]);
76
+ } catch (cause) {
77
+ throw new AlpError("INVALID_PACK", `packs/${id}/pack.json: ${cause.message}`, { cause });
78
+ }
79
+ validatePack(id, manifest, files);
80
+ return { id, label: manifest.label, description: manifest.description, skills: manifest.skills ?? [], agents: manifest.agents ?? [], teams: manifest.teams ?? [], assign: manifest.assign ?? {}, permissions: manifest.permissions ?? {} };
81
+ });
82
+ }
83
+ var present = (target) => lstat(target).then(() => true, (error) => {
84
+ if (error.code === "ENOENT") return false;
85
+ throw error;
86
+ });
87
+ async function writeJsonAtomic(file, value) {
88
+ await mkdir(path.dirname(file), { recursive: true });
89
+ const temporary = `${file}.${randomUUID().slice(0, 8)}.tmp`;
90
+ await writeFile(temporary, JSON.stringify(value, null, 2) + "\n");
91
+ await moveFile(temporary, file);
92
+ }
93
+ async function installPack(id, { scope, root, library, assign = false, templates } = {}) {
94
+ if (typeof id !== "string" || !NAME.test(id)) fail("INVALID_NAME", `'${id}' is not a pack name`);
95
+ const packs = await listPacks({ templates });
96
+ const pack = packs.find((candidate) => candidate.id === id) ?? fail("NOT_FOUND", `No pack '${id}'; packs are ${packs.map((candidate) => candidate.id).join(", ")}`);
97
+ if (scope !== "library" && scope !== "project") fail("INVALID_SCOPE", "Scope must be library or project");
98
+ if (scope === "library" && !library) fail("INVALID_SCOPE", "No library: ALP_HOME is not set");
99
+ if (scope === "project" && !root) fail("INVALID_SCOPE", "No project directory");
100
+ if (assign && scope !== "library") fail("INVALID_SCOPE", "Only the library assigns skills to roles (role-skills.json); in a project, name the skills in a project agent: alp agent edit <role> --project --skills a,b");
101
+ if (library) await seedLibrary(library, templates ? { templates } : {});
102
+ const given = scope === "library" ? library : path.resolve(root);
103
+ const scopeRoot = await realpath(given);
104
+ const inScope = scope === "library" ? "" : ".alp";
105
+ const base = path.join(scopeRoot, inScope);
106
+ const shown = (kind, name) => path.join(given, inScope, kind, name);
107
+ const guard = (relative) => assertNoSymlinks(scopeRoot, path.join(inScope, relative));
108
+ await guard(".");
109
+ for (const kind of KINDS) if (pack[kind].length) await guard(kind);
110
+ if (Object.keys(pack.permissions).length) await guard("settings.json");
111
+ if (assign) await guard("role-skills.json");
112
+ await mkdir(base, { recursive: true, ...scope === "library" ? { mode: 448 } : {} });
113
+ const files = await shippedPackFiles({ templates });
114
+ for (const file of Object.keys(files)) {
115
+ const parts = file.split("/");
116
+ if (parts.some((part) => !part || part === "." || part === ".." || !/^[\w.@+-]+$/.test(part))) fail("INVALID_PACK", `${file}: a pack file path must be plain relative names`);
117
+ }
118
+ const installed = [];
119
+ const kept = [];
120
+ for (const kind of KINDS) {
121
+ for (const name of pack[kind]) {
122
+ const target = path.join(base, kind, name);
123
+ await guard(kind);
124
+ if (await present(target)) {
125
+ kept.push({ kind, name, path: shown(kind, name) });
126
+ continue;
127
+ }
128
+ const prefix = `packs/${id}/${kind}/${name}/`;
129
+ const stagingName = `.alp-pack-${randomUUID().slice(0, 8)}.tmp`;
130
+ const stagingRoot = path.join(base, stagingName);
131
+ const staging = path.join(stagingRoot, name);
132
+ await guard(stagingName);
133
+ try {
134
+ await mkdir(stagingRoot, { recursive: false, ...scope === "library" ? { mode: 448 } : {} });
135
+ for (const [file, content] of Object.entries(files).filter(([file2]) => file2.startsWith(prefix))) {
136
+ const relative = file.slice(prefix.length);
137
+ const destination = path.join(staging, ...relative.split("/"));
138
+ await mkdir(path.dirname(destination), { recursive: true, ...scope === "library" ? { mode: 448 } : {} });
139
+ await writeFile(destination, content, { flag: "wx" });
140
+ if (process.platform !== "win32" && relative.startsWith("scripts/") && content.startsWith("#!")) await chmod(destination, 493);
141
+ }
142
+ if (kind === "skills") {
143
+ const { errors } = await validateSkill(staging, { mode: "strict" });
144
+ if (errors.length) fail("INVALID_PACK", `packs/${id}/skills/${name}: ${errors.map((finding) => finding.message).join("; ")}`);
145
+ }
146
+ if (kind === "agents") {
147
+ const config = await readFile(path.join(staging, "agent.json"), "utf8").then(JSON.parse, (error) => {
148
+ if (error.code === "ENOENT") return {};
149
+ throw error;
150
+ });
151
+ validateAgentConfig(config, `${prefix}agent.json`);
152
+ }
153
+ if (kind === "teams") validateTeam(JSON.parse(await readFile(path.join(staging, "team.json"), "utf8")), `${prefix}team.json`);
154
+ await guard(kind);
155
+ await guard(path.join(stagingName, name));
156
+ if (await present(target)) {
157
+ kept.push({ kind, name, path: shown(kind, name) });
158
+ continue;
159
+ }
160
+ await mkdir(path.dirname(target), { recursive: true });
161
+ await guard(kind);
162
+ await rename(staging, target);
163
+ installed.push({ kind, name, path: shown(kind, name) });
164
+ } finally {
165
+ await rm(stagingRoot, { recursive: true, force: true });
166
+ }
167
+ }
168
+ }
169
+ const permissions = { set: [], kept: [], conflicts: [] };
170
+ if (Object.keys(pack.permissions).length) {
171
+ const file = path.join(base, "settings.json");
172
+ await guard("settings.json");
173
+ const text = await readFile(file, "utf8").catch((error) => {
174
+ if (error.code === "ENOENT") return void 0;
175
+ throw error;
176
+ });
177
+ let settings = {};
178
+ if (text !== void 0) {
179
+ try {
180
+ settings = JSON.parse(text);
181
+ } catch (cause) {
182
+ throw new AlpError("INVALID_SETTINGS", `${file}: ${cause.message}`, { cause });
183
+ }
184
+ if (!object(settings)) fail("INVALID_SETTINGS", `${file}: expected a JSON object`);
185
+ }
186
+ const current = object(settings.permissions) ? settings.permissions : {};
187
+ const agents = object(current.agents) ? current.agents : {};
188
+ let changed = false;
189
+ for (const [agent, required] of Object.entries(pack.permissions)) {
190
+ if (!installed.some((entry) => entry.kind === "agents" && entry.name === agent)) {
191
+ if (!Object.hasOwn(agents, agent) || agents[agent] !== required) permissions.conflicts.push(`${agent}: your own ${agent} agent was kept, so its permissions were left as they are; the pack's ${agent} expects '${required}'`);
192
+ continue;
193
+ }
194
+ if (!Object.hasOwn(agents, agent)) {
195
+ agents[agent] = required;
196
+ permissions.set.push(`${agent}: ${required}`);
197
+ changed = true;
198
+ } else if (agents[agent] === required) permissions.kept.push(`${agent}: ${required}`);
199
+ else permissions.conflicts.push(`${agent}: ${file} gives '${agents[agent]}', the pack expects '${required}'; left as it is`);
200
+ }
201
+ if (changed) {
202
+ const next = { ...settings, permissions: { ...current, agents } };
203
+ validatePermissions(next.permissions, file);
204
+ await guard("settings.json");
205
+ await writeJsonAtomic(file, next);
206
+ }
207
+ }
208
+ const assigned = [];
209
+ if (assign && Object.keys(pack.assign).length) {
210
+ const file = path.join(base, "role-skills.json");
211
+ await guard("role-skills.json");
212
+ const text = await readFile(file, "utf8").catch((error) => {
213
+ if (error.code === "ENOENT") return "{}";
214
+ throw error;
215
+ });
216
+ let roles;
217
+ try {
218
+ roles = JSON.parse(text);
219
+ } catch (cause) {
220
+ throw new AlpError("INVALID_LIBRARY", `${file}: ${cause.message}; the pack was installed but no agent was given its skills`, { cause });
221
+ }
222
+ if (!object(roles)) fail("INVALID_LIBRARY", `${file}: expected an object of agent names to skill lists`);
223
+ for (const [role, skills] of Object.entries(pack.assign)) {
224
+ const list = Array.isArray(roles[role]) ? roles[role] : roles[role] = [];
225
+ for (const skill of skills) if (!list.includes(skill)) {
226
+ list.push(skill);
227
+ assigned.push(`${role}/${skill}`);
228
+ }
229
+ }
230
+ if (assigned.length) await writeJsonAtomic(file, roles);
231
+ }
232
+ return { pack: id, scope, installed, kept, assigned, permissions };
233
+ }
234
+ async function packStatus(pack, { root, library } = {}) {
235
+ const has = async (base) => {
236
+ if (!base) return false;
237
+ for (const kind of KINDS) for (const name of pack[kind]) if (!await present(path.join(base, kind, name))) return false;
238
+ return true;
239
+ };
240
+ return { library: await has(library), project: await has(root ? path.join(path.resolve(root), ".alp") : void 0) };
241
+ }
242
+ export {
243
+ installPack,
244
+ listPacks,
245
+ packStatus,
246
+ validatePack
247
+ };
@@ -1,13 +1,14 @@
1
1
  export type PermissionBase = 'read-only' | 'workspace-write' | 'full-access';
2
- export type PermissionProfile = { name: string; base: PermissionBase; allow: string[]; ask: string[]; deny: string[]; beyondMode: 'refuse' | 'ask'; workdir?: 'copy' };
2
+ export type PermissionProfile = { name: string; base: PermissionBase; allow: string[]; ask: string[]; deny: string[]; beyondMode: 'refuse' | 'ask'; workdir?: 'copy'; cappedFrom?: PermissionBase };
3
3
  export const BASES: PermissionBase[];
4
4
  export const ADVISORS: string[];
5
+ export const READ_ONLY_ROLES: string[];
5
6
  export const MAX_RULES: number;
6
7
  export const TOOLS: string[];
7
8
  export function parseRule(rule: unknown, source?: string): { tool: string; specifier?: string };
8
9
  export function validatePermissions(value: unknown, source: string): { profiles: Record<string, { base?: PermissionBase; beyondMode?: 'refuse' | 'ask'; workdir?: 'copy'; allow: string[]; ask: string[]; deny: string[] }>; agents: Record<string, string> };
9
10
  export function addAllowRule(projectRoot: string, home: string | undefined, profileName: string, rule: string): Promise<string>;
10
- export function profileFor(projectRoot: string, home: string | undefined, agent: string): Promise<PermissionProfile | null>;
11
+ export function profileFor(projectRoot: string, home: string | undefined, agent: string, options?: { readOnly?: boolean }): Promise<PermissionProfile | null>;
11
12
  export function capMode(mode: string, base: string): string;
12
13
  export function unwrapShell(command: string): string;
13
14
  export function simpleCommands(line: string): string[] | null;
@@ -7,6 +7,7 @@ import { AlpError } from "./errors.js";
7
7
  var BASES = ["read-only", "workspace-write", "full-access"];
8
8
  var RANK = { "read-only": 0, "workspace-write": 1, "full-access": 2 };
9
9
  var ADVISORS = ["oracle", "reviewer", "supervisor"];
10
+ var READ_ONLY_ROLES = ["advisor", "reviewer"];
10
11
  var MAX_RULES = 200;
11
12
  var NAME = /^[\w.-]{1,64}$/;
12
13
  var RULE = /^([A-Za-z][\w-]*)(?:\((.*)\))?$/s;
@@ -79,12 +80,12 @@ async function settingsPermissions(file) {
79
80
  if (!object(settings)) fail(file, "expected an object");
80
81
  return validatePermissions(settings.permissions, file);
81
82
  }
82
- async function profileFor(projectRoot, home, agent) {
83
+ async function profileFor(projectRoot, home, agent, { readOnly = false } = {}) {
83
84
  const project = await settingsPermissions(path.join(projectRoot, ".alp", "settings.json"));
84
85
  const user = home ? await settingsPermissions(path.join(home, "settings.json")) : { profiles: {}, agents: {} };
85
86
  const name = own(project.agents, agent) ?? own(user.agents, agent);
86
87
  const advisor = ADVISORS.includes(agent);
87
- if (!name) return advisor ? { name: "read-only", base: "read-only", allow: [], ask: [], deny: [], beyondMode: "refuse" } : null;
88
+ if (!name) return advisor || readOnly ? { name: "read-only", base: "read-only", allow: [], ask: [], deny: [], beyondMode: "refuse" } : null;
88
89
  const defined = [own(project.profiles, name), own(user.profiles, name)].filter(Boolean);
89
90
  if (!defined.length && !BASES.includes(name)) {
90
91
  throw new AlpError("INVALID_SETTINGS", `permissions.agents.${agent} names profile '${name}', which no settings file defines`);
@@ -95,7 +96,8 @@ async function profileFor(projectRoot, home, agent) {
95
96
  if (advisor && base !== "read-only") throw new AlpError("INVALID_SETTINGS", `${agent} is an advisor; its profile '${name}' must have base read-only`);
96
97
  return {
97
98
  name,
98
- base,
99
+ base: readOnly ? "read-only" : base,
100
+ ...readOnly && base !== "read-only" ? { cappedFrom: base } : {},
99
101
  allow: [...new Set(defined.flatMap((profile) => profile.allow ?? []))],
100
102
  ask: [...new Set(defined.flatMap((profile) => profile.ask ?? []))],
101
103
  deny: [...new Set(defined.flatMap((profile) => profile.deny ?? []))],
@@ -217,6 +219,7 @@ export {
217
219
  ADVISORS,
218
220
  BASES,
219
221
  MAX_RULES,
222
+ READ_ONLY_ROLES,
220
223
  TOOLS,
221
224
  addAllowRule,
222
225
  capMode,
package/dist/profiles.js CHANGED
@@ -2,7 +2,7 @@
2
2
  import path from "node:path";
3
3
  import os from "node:os";
4
4
  import { createHash } from "node:crypto";
5
- import { MODELS } from "./models.js";
5
+ import { knownModel } from "./models.js";
6
6
  import { resolveTeam, teamSources } from "./teams.js";
7
7
  var userLibrary = () => process.env.ALP_HOME ?? path.join(os.homedir(), ".alp");
8
8
  var oracleProfiles = (config) => config?.profiles ?? [config?.claude, config?.codex].filter(Boolean);
@@ -18,11 +18,11 @@ var parseProfile = (profile) => {
18
18
  return { provider, model, ...effort ? { effort } : {} };
19
19
  };
20
20
  var profileString = (profile) => `${profileModel(profile)}${profile.effort ? `:${profile.effort}` : ""}`;
21
- var modelEfforts = (id) => MODELS.find((model) => `${model.runtime}:${model.id}` === id)?.efforts;
21
+ var modelEfforts = (id) => knownModel(id)?.efforts;
22
22
  var fitEffort = (id, effort) => {
23
23
  const efforts = modelEfforts(id);
24
24
  if (!efforts?.length || efforts.includes(effort)) return effort;
25
- return MODELS.find((model) => `${model.runtime}:${model.id}` === id)?.effort ?? efforts[0];
25
+ return knownModel(id)?.effort ?? efforts[0];
26
26
  };
27
27
  var anyModel = (profile) => profile?.model === "*";
28
28
  var offers = (profiles, model) => profiles.some((profile) => anyModel(profile) ? model.startsWith(`${profile.provider}:`) && model.length > profile.provider.length + 1 : profileModel(profile) === model);
@@ -2,7 +2,7 @@
2
2
  export function validateProvider(config: any, source: any, id: any): any;
3
3
  /**
4
4
  * A provider of the library, with its id; undefined when there is none.
5
- * @returns {Promise<{ id: string, kind: 'acp' | 'antigravity', label: string, description?: string, command: string, args: string[], env: Record<string, string>, models?: Array<{ id: string, label?: string, description?: string }>, additionalModels?: Array<{ id: string, label?: string, description?: string }>, enabled?: boolean, params?: Record<string, unknown>, readOnlyMode?: 'instructions' | 'reject' } | undefined>}
5
+ * @returns {Promise<{ id: string, kind: 'acp' | 'antigravity', label: string, description?: string, command: string, args: string[], env: Record<string, string>, models?: Array<{ id: string, label?: string, description?: string }>, additionalModels?: Array<{ id: string, label?: string, description?: string }>, enabled?: boolean, params?: Record<string, unknown> } | undefined>}
6
6
  */
7
7
  export function loadProvider(library: any, id: any): Promise<{
8
8
  id: string;
@@ -24,10 +24,9 @@ export function loadProvider(library: any, id: any): Promise<{
24
24
  }>;
25
25
  enabled?: boolean;
26
26
  params?: Record<string, unknown>;
27
- readOnlyMode?: "instructions" | "reject";
28
27
  } | undefined>;
29
28
  /** Every provider of the library, by id. */
30
- export function listProviders(library: any): Promise<{
29
+ export function listProviders(library: any, { onError }?: {}): Promise<{
31
30
  id: string;
32
31
  kind: "acp" | "antigravity";
33
32
  label: string;
@@ -47,7 +46,6 @@ export function listProviders(library: any): Promise<{
47
46
  }>;
48
47
  enabled?: boolean;
49
48
  params?: Record<string, unknown>;
50
- readOnlyMode?: "instructions" | "reject";
51
49
  }[]>;
52
50
  /**
53
51
  * Splits an ACP model id, `<provider>` or `<provider>/<model>`, as resolveSession keeps it
package/dist/providers.js CHANGED
@@ -5,7 +5,8 @@ import path from "node:path";
5
5
  import { AlpError } from "./errors.js";
6
6
  import { settingsKeys, unknownMessage } from "./validation.js";
7
7
  import { scriptCommand } from "./packaged.js";
8
- var PROVIDER_SETTINGS = ["$schema", "kind", "label", "description", "command", "args", "env", "models", "additionalModels", "enabled", "params", "readOnlyMode"];
8
+ var legacyWarnings = /* @__PURE__ */ new Set();
9
+ var PROVIDER_SETTINGS = ["$schema", "kind", "label", "description", "command", "args", "env", "models", "additionalModels", "enabled", "params"];
9
10
  var BUILTIN_RUNTIMES = ["codex", "claude", "acp", "antigravity"];
10
11
  var RESERVED_PROVIDERS = [...BUILTIN_RUNTIMES, "alp"];
11
12
  var object = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
@@ -17,11 +18,11 @@ function validateProvider(config, source, id) {
17
18
  };
18
19
  if (id !== void 0) check(validId(id) && (!RESERVED_PROVIDERS.includes(id) || id === "antigravity" && config?.kind === "antigravity"), `'${id}' cannot name a provider: ${RESERVED_PROVIDERS.join(", ")} are taken`);
19
20
  check(object(config), "expected an object");
21
+ check(!Object.hasOwn(config, "readOnlyMode"), "readOnlyMode was removed; delete it and choose the session mode (read-only, workspace-write or full-access). Existing native sessions keep their mode");
20
22
  const { unknown } = settingsKeys(config, PROVIDER_SETTINGS);
21
23
  check(!unknown.length, unknown.length ? unknownMessage(unknown[0], PROVIDER_SETTINGS) : "");
22
24
  check(["acp", "antigravity"].includes(config.kind), 'kind must be "acp" or "antigravity"');
23
25
  if (config.kind === "antigravity" && id !== void 0) check(id === "antigravity", "Antigravity must use provider ID antigravity");
24
- if (config.readOnlyMode !== void 0) check(config.kind === "antigravity" && ["instructions", "reject"].includes(config.readOnlyMode), 'readOnlyMode is only for Antigravity and must be "instructions" or "reject"');
25
26
  for (const key of ["label", "description"]) if (config[key] !== void 0) check(typeof config[key] === "string", `${key} must be a string`);
26
27
  check(nonempty(config.command), "command must be a nonempty string");
27
28
  if (config.args !== void 0) check(Array.isArray(config.args) && config.args.every((arg) => typeof arg === "string"), "args must be a list of strings");
@@ -51,11 +52,19 @@ async function loadProvider(library, id) {
51
52
  } catch (cause) {
52
53
  throw new AlpError("INVALID_PROVIDER", `${file}: ${cause.message}`, { cause });
53
54
  }
55
+ if (config?.kind === "antigravity" && Object.hasOwn(config, "readOnlyMode")) {
56
+ config = { ...config };
57
+ delete config.readOnlyMode;
58
+ if (!legacyWarnings.has(file)) {
59
+ legacyWarnings.add(file);
60
+ console.warn(`${file}: readOnlyMode was removed; delete it and select a session mode (read-only, workspace-write or full-access). Existing sessions keep their mode.`);
61
+ }
62
+ }
54
63
  validateProvider(config, file, id);
55
64
  const command = /[\\/]/.test(config.command) ? path.resolve(path.dirname(file), config.command) : config.command;
56
65
  return { id, ...config, label: config.label ?? id, command, args: config.args ?? [], env: config.env ?? {} };
57
66
  }
58
- async function listProviders(library) {
67
+ async function listProviders(library, { onError } = {}) {
59
68
  if (!library) return [];
60
69
  let names = [];
61
70
  try {
@@ -65,7 +74,14 @@ async function listProviders(library) {
65
74
  }
66
75
  const providers = [];
67
76
  for (const name of names.filter((name2) => name2.endsWith(".json")).sort()) {
68
- const provider = await loadProvider(library, name.slice(0, -5));
77
+ let provider;
78
+ try {
79
+ provider = await loadProvider(library, name.slice(0, -5));
80
+ } catch (error) {
81
+ if (!onError) throw error;
82
+ onError(error, name);
83
+ continue;
84
+ }
69
85
  if (provider) providers.push(provider);
70
86
  }
71
87
  return providers;
@@ -0,0 +1,85 @@
1
+ /**
2
+ * Parses the YAML subset skills use: `key: scalar`, quoted scalars, block scalars (`|`, `>`),
3
+ * multi-line plain scalars, comments, and one level of `key:` + indented `sub: value` (metadata).
4
+ * Anything else (sequences, flow collections, anchors, tags) is reported as unsupported.
5
+ * @returns {{ data: Record<string, unknown>, problems: string[] }}
6
+ */
7
+ export function parseFrontmatter(text: any): {
8
+ data: Record<string, unknown>;
9
+ problems: string[];
10
+ };
11
+ /** The frontmatter block and body of a SKILL.md, or undefined frontmatter when it has none. */
12
+ export function splitSkill(text: any): {
13
+ frontmatter: string;
14
+ body: any;
15
+ } | {
16
+ frontmatter: undefined;
17
+ body: any;
18
+ };
19
+ /**
20
+ * The relative files a Markdown text points to: link targets and code spans naming a resource
21
+ * directory (`references/x.md`). URLs, anchors and template placeholders are skipped.
22
+ */
23
+ export function skillReferences(markdown: any): any[];
24
+ /**
25
+ * Checks frontmatter text against the specification. `directory` is the skill directory's name.
26
+ * @returns {{ data: Record<string, unknown>, findings: Array<{ level: 'error' | 'warning', code: string, message: string }> }}
27
+ */
28
+ export function checkFrontmatter(frontmatter: any, directory: any, { strict }?: {
29
+ strict?: boolean | undefined;
30
+ }): {
31
+ data: Record<string, unknown>;
32
+ findings: Array<{
33
+ level: "error" | "warning";
34
+ code: string;
35
+ message: string;
36
+ }>;
37
+ };
38
+ /**
39
+ * Validates one skill directory.
40
+ * @param {string} directory absolute or relative path of the skill directory
41
+ * @param {{ mode?: 'strict' | 'legacy', shipped?: boolean }} [options] `shipped`: the skill ships in
42
+ * ALP's templates, which bundles carry as UTF-8 text, so every file must be text
43
+ * @returns {Promise<{ name: string, directory: string, mode: 'strict' | 'legacy', ok: boolean, errors: Finding[], warnings: Finding[], files: number }>}
44
+ * @typedef {{ code: string, message: string, file?: string }} Finding
45
+ */
46
+ export function validateSkill(directory: string, { mode, shipped }?: {
47
+ mode?: "strict" | "legacy";
48
+ shipped?: boolean;
49
+ }): Promise<{
50
+ name: string;
51
+ directory: string;
52
+ mode: "strict" | "legacy";
53
+ ok: boolean;
54
+ errors: Finding[];
55
+ warnings: Finding[];
56
+ files: number;
57
+ }>;
58
+ /** One line per finding, for a terminal. */
59
+ export function formatValidation(report: any): string;
60
+ /**
61
+ * Skill validation (Agent Skills format, https://agentskills.io/specification): a skill is a
62
+ * directory holding SKILL.md, whose YAML frontmatter names it and says what it is for, and the
63
+ * references, scripts and assets SKILL.md points to.
64
+ *
65
+ * Two modes. `strict` is for skills ALP ships, packs and new skills: format problems are errors.
66
+ * `legacy` (the default) is for skills already in a user's library or project: format problems
67
+ * are warnings with a migration hint, since ALP never rewrites them and the runtime keeps loading
68
+ * them. A symlink leaving the skill, a broken symlink or an unreadable file is an error in both
69
+ * modes; a plain path leaving the skill is an error in strict mode and a warning in legacy mode. Validation only reads; it never runs a script or follows a link outside the skill.
70
+ */
71
+ /** Frontmatter keys of the Agent Skills specification. */
72
+ export const SPEC_KEYS: string[];
73
+ export const NAME_MAX: 64;
74
+ export const DESCRIPTION_MAX: 1024;
75
+ /** How much of a description ALP's skill index shows (resolve.ts SKILL_DESCRIPTION_CHARS). */
76
+ export const INDEX_DESCRIPTION_CHARS: 400;
77
+ export function specName(name: any): boolean;
78
+ /**
79
+ * Validates one skill directory.
80
+ */
81
+ export type Finding = {
82
+ code: string;
83
+ message: string;
84
+ file?: string;
85
+ };