@anhlp/alp-core 0.0.0-beta.2 → 0.0.1-beta.10

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 (158) hide show
  1. package/dist/backup.js +106 -4
  2. package/dist/bridges.d.ts +26 -0
  3. package/dist/bridges.js +96 -0
  4. package/dist/gate-ledger.d.ts +30 -0
  5. package/dist/gate-ledger.js +99 -0
  6. package/dist/index.d.ts +1 -0
  7. package/dist/index.js +2 -0
  8. package/dist/library-edit.d.ts +57 -5
  9. package/dist/library-edit.js +216 -11
  10. package/dist/library.d.ts +14 -1
  11. package/dist/library.js +73 -5
  12. package/dist/migrations.js +1 -1
  13. package/dist/models.d.ts +74 -0
  14. package/dist/models.js +67 -1
  15. package/dist/packaged.d.ts +122 -0
  16. package/dist/packaged.js +125 -0
  17. package/dist/packs.d.ts +57 -0
  18. package/dist/packs.js +247 -0
  19. package/dist/permissions.d.ts +3 -2
  20. package/dist/permissions.js +6 -3
  21. package/dist/profiles.js +6 -6
  22. package/dist/providers.d.ts +4 -5
  23. package/dist/providers.js +26 -5
  24. package/dist/skill-validate.d.ts +85 -0
  25. package/dist/skill-validate.js +298 -0
  26. package/dist/task-rows.d.ts +5 -0
  27. package/dist/task-rows.js +1 -1
  28. package/dist/tasks.d.ts +23 -4
  29. package/dist/tasks.js +103 -9
  30. package/dist/types.d.ts +3 -0
  31. package/dist/upgrade.d.ts +10 -0
  32. package/dist/upgrade.js +112 -6
  33. package/dist/user-settings.d.ts +2 -0
  34. package/dist/user-settings.js +40 -1
  35. package/dist/user-worktree.d.ts +29 -0
  36. package/dist/user-worktree.js +242 -0
  37. package/dist/validation.d.ts +1 -0
  38. package/dist/validation.js +35 -13
  39. package/package.json +34 -2
  40. package/src/backup.js +106 -5
  41. package/src/bridges.js +113 -0
  42. package/src/gate-ledger.js +125 -0
  43. package/src/index.js +1 -0
  44. package/src/library-edit.js +227 -12
  45. package/src/library.js +96 -6
  46. package/src/migrations.js +1 -1
  47. package/src/models.js +87 -1
  48. package/src/packaged.js +207 -0
  49. package/src/packs.js +246 -0
  50. package/src/permissions.d.ts +3 -2
  51. package/src/permissions.js +13 -3
  52. package/src/profiles.js +7 -7
  53. package/src/providers.js +23 -7
  54. package/src/resolver.js +1 -1
  55. package/src/skill-validate.js +287 -0
  56. package/src/task-rows.js +1 -1
  57. package/src/tasks.d.ts +23 -4
  58. package/src/tasks.js +137 -10
  59. package/src/types.d.ts +3 -0
  60. package/src/upgrade.js +54 -6
  61. package/src/user-settings.d.ts +2 -0
  62. package/src/user-settings.js +51 -1
  63. package/src/user-worktree.js +259 -0
  64. package/src/validation.d.ts +1 -0
  65. package/src/validation.js +43 -14
  66. package/templates/ALP.md +52 -52
  67. package/templates/agents/lead/AGENT.md +77 -74
  68. package/templates/agents/main/AGENT.md +153 -141
  69. package/templates/agents/oracle/AGENT.md +38 -37
  70. package/templates/agents/peer/AGENT.md +56 -52
  71. package/templates/agents/reviewer/AGENT.md +63 -65
  72. package/templates/agents/supervisor/AGENT.md +63 -63
  73. package/templates/packs/architecture/agents/architect/AGENT.md +41 -0
  74. package/templates/packs/architecture/agents/architect/agent.json +5 -0
  75. package/templates/packs/architecture/agents/docs-maintainer/AGENT.md +33 -0
  76. package/templates/packs/architecture/agents/docs-maintainer/agent.json +4 -0
  77. package/templates/packs/architecture/pack.json +7 -0
  78. package/templates/packs/architecture/teams/blueprint/HOUSE_RULES.md +12 -0
  79. package/templates/packs/architecture/teams/blueprint/team.json +19 -0
  80. package/templates/packs/backend/pack.json +6 -0
  81. package/templates/packs/backend/skills/backend-development/SKILL.md +102 -0
  82. package/templates/packs/backend/skills/backend-development/references/api-design.md +96 -0
  83. package/templates/packs/backend/skills/backend-development/references/authentication.md +78 -0
  84. package/templates/packs/backend/skills/backend-development/references/error-handling.md +86 -0
  85. package/templates/packs/backend/skills/backend-development/references/testing.md +81 -0
  86. package/templates/packs/backend/skills/databases/SKILL.md +103 -0
  87. package/templates/packs/backend/skills/databases/references/query-performance.md +87 -0
  88. package/templates/packs/backend/skills/databases/references/schema-and-migrations.md +87 -0
  89. package/templates/packs/design/pack.json +6 -0
  90. package/templates/packs/design/skills/ui-design/SKILL.md +86 -0
  91. package/templates/packs/design/skills/ui-design/references/design-tokens.md +67 -0
  92. package/templates/packs/design/skills/ui-design/references/interaction-states.md +73 -0
  93. package/templates/packs/design/skills/ui-design/references/layout-and-typography.md +71 -0
  94. package/templates/packs/design/skills/ui-design/references/ui-review.md +83 -0
  95. package/templates/packs/frontend/pack.json +6 -0
  96. package/templates/packs/frontend/skills/frontend-development/SKILL.md +105 -0
  97. package/templates/packs/frontend/skills/frontend-development/references/accessibility.md +86 -0
  98. package/templates/packs/frontend/skills/frontend-development/references/components-and-state.md +79 -0
  99. package/templates/packs/frontend/skills/frontend-development/references/data-fetching.md +86 -0
  100. package/templates/packs/frontend/skills/frontend-development/references/frameworks.md +77 -0
  101. package/templates/packs/frontend/skills/frontend-development/references/performance.md +78 -0
  102. package/templates/packs/integration/pack.json +6 -0
  103. package/templates/packs/integration/skills/mcp-integration/SKILL.md +100 -0
  104. package/templates/packs/integration/skills/mcp-integration/references/server-implementation.md +95 -0
  105. package/templates/packs/integration/skills/mcp-integration/references/testing.md +78 -0
  106. package/templates/packs/integration/skills/mcp-integration/references/tool-design.md +97 -0
  107. package/templates/packs/operations/pack.json +6 -0
  108. package/templates/packs/operations/skills/devops/SKILL.md +85 -0
  109. package/templates/packs/operations/skills/devops/references/ci-cd.md +84 -0
  110. package/templates/packs/operations/skills/devops/references/containers.md +85 -0
  111. package/templates/packs/operations/skills/devops/references/deployment-and-rollback.md +85 -0
  112. package/templates/packs/operations/skills/devops/references/observability.md +86 -0
  113. package/templates/packs/quality/pack.json +6 -0
  114. package/templates/packs/quality/skills/web-testing/SKILL.md +102 -0
  115. package/templates/packs/quality/skills/web-testing/references/e2e.md +85 -0
  116. package/templates/packs/quality/skills/web-testing/references/performance-testing.md +85 -0
  117. package/templates/packs/quality/skills/web-testing/references/security-testing.md +78 -0
  118. package/templates/packs/quality/skills/web-testing/references/unit-and-component.md +78 -0
  119. package/templates/role-skills.json +4 -4
  120. package/templates/skills/architecture-docs/SKILL.md +81 -0
  121. package/templates/skills/architecture-docs/references/adr.md +62 -0
  122. package/templates/skills/architecture-docs/references/diagrams.md +60 -0
  123. package/templates/skills/architecture-docs/references/evidence-rules.md +49 -0
  124. package/templates/skills/bug-loop/SKILL.md +41 -40
  125. package/templates/skills/bug-loop/references/test-proof.md +21 -19
  126. package/templates/skills/compact/SKILL.md +34 -0
  127. package/templates/skills/curate/SKILL.md +36 -0
  128. package/templates/skills/feature-architecture/SKILL.md +90 -0
  129. package/templates/skills/feature-architecture/references/architecture-contract.md +95 -0
  130. package/templates/skills/feature-architecture/references/feature-design.md +69 -0
  131. package/templates/skills/feature-architecture/scripts/check-boundaries.mjs +270 -0
  132. package/templates/skills/goal-griller/SKILL.md +27 -27
  133. package/templates/skills/prompt-leverage/SKILL.md +29 -27
  134. package/templates/skills/prompt-leverage/references/brief-template.md +9 -9
  135. package/templates/skills/release-readiness/SKILL.md +83 -0
  136. package/templates/skills/release-readiness/references/checklist.md +40 -0
  137. package/templates/skills/release-readiness/references/verdict-template.md +53 -0
  138. package/templates/skills/safe-refactor/SKILL.md +84 -0
  139. package/templates/skills/safe-refactor/references/characterization-tests.md +57 -0
  140. package/templates/skills/safe-refactor/references/compatibility-checklist.md +56 -0
  141. package/templates/skills/security-review/SKILL.md +87 -0
  142. package/templates/skills/security-review/references/checklist.md +74 -0
  143. package/templates/skills/security-review/references/severity.md +61 -0
  144. package/templates/skills/sequence-execution-plan/SKILL.md +41 -38
  145. package/templates/skills/sequence-execution-plan/references/plan-template.md +5 -5
  146. package/templates/skills/skill-authoring/SKILL.md +84 -0
  147. package/templates/skills/skill-authoring/references/evaluation.md +45 -0
  148. package/templates/skills/skill-authoring/references/skill-anatomy.md +74 -0
  149. package/templates/skills/skill-authoring/references/trigger-design.md +52 -0
  150. package/templates/skills/smart-commits/SKILL.md +37 -36
  151. package/templates/skills/test-strategy/SKILL.md +83 -0
  152. package/templates/skills/test-strategy/references/contract-tests.md +46 -0
  153. package/templates/skills/test-strategy/references/risk-matrix.md +53 -0
  154. package/templates/skills/xia/SKILL.md +40 -38
  155. package/templates/teams/cafe/HOUSE_RULES.md +1 -1
  156. package/templates/teams/cafe/team.json +1 -1
  157. package/templates/teams/pho/HOUSE_RULES.md +1 -1
  158. package/templates/teams/pho/team.json +1 -1
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/migrations.js CHANGED
@@ -98,7 +98,7 @@ export async function migrateState(home, { by = 'alp', migrations = MIGRATIONS,
98
98
  throw new AlpError('STATE_MIGRATION_ROLLBACK_FAILED', `state migration ${step.name} failed (${error?.message ?? error}) and putting the state back from ${backup} failed too (${rollback?.message ?? rollback}); the next start tries the migration again. See docs/alp/data-recovery.md`, { cause: error });
99
99
  }
100
100
  await rm(migrationFile(home), { force: true });
101
- throw new AlpError('STATE_MIGRATION_FAILED', `state migration ${step.name} (schema ${step.from} → ${step.to}) failed: ${error?.message ?? error}; the state was put back from ${backup} and is unchanged. See docs/alp/data-recovery.md`, { cause: error });
101
+ throw new AlpError('STATE_MIGRATION_FAILED', `state migration ${step.name} (schema ${step.from} → ${step.to}) failed: ${error?.message ?? error}; data was restored from ${backup} with workspace authority checks. See docs/alp/data-recovery.md`, { cause: error });
102
102
  }
103
103
  await writeStateSchema(home, step.to, by);
104
104
  await rm(migrationFile(home), { force: true });
package/src/models.js CHANGED
@@ -1,4 +1,7 @@
1
- /** Models ALP offers, with the efforts each takes: the runtime's catalog and alp setup read this list. */
1
+ import { readFileSync } from 'node:fs';
2
+ import path from 'node:path';
3
+
4
+ /** Models ALP offers when no provider has answered yet (the live catalog, t-e5ee, merges provider lists over these), with the efforts each takes: the runtime's catalog and alp setup read this list. */
2
5
  const codexFull = ['low', 'medium', 'high', 'xhigh', 'max', 'ultra'];
3
6
  const codexStandard = ['low', 'medium', 'high', 'xhigh', 'max'];
4
7
  const claudeFull = ['low', 'medium', 'high', 'xhigh', 'max', 'ultracode'];
@@ -43,3 +46,86 @@ export const MODELS = [
43
46
  ['antigravity', 'claude-opus-4-6-thinking', 'Claude Opus 4.6 Thinking', 'Opus 4.6 with thinking via Antigravity.', [], undefined],
44
47
  ['antigravity', 'gpt-oss-120b-medium', 'GPT-OSS 120B (Medium)', 'Open weights model via Antigravity.', [], undefined],
45
48
  ].map(([runtime, id, label, description, efforts, effort]) => ({ runtime, id, label, description, efforts, ...(effort ? { effort } : {}) }));
49
+
50
+ /** ALP policy applied over whatever a provider reports. */
51
+ export const MODEL_POLICY = {
52
+ // ALP runs GPT-6 Astra at low effort only.
53
+ 'codex:gpt-6-astra': { efforts: ['low'], effort: 'low' },
54
+ };
55
+ const CATALOG_RUNTIMES = ['codex', 'claude', 'antigravity'];
56
+
57
+ /**
58
+ * Live over static (t-e5ee): a runtime with a live list shows its live models first, in the provider's
59
+ * order, with the provider's label and description; a live model ALP knows keeps ALP's efforts (plus any
60
+ * new ones the provider adds) and ALP's default effort, a new one takes the provider's. Static rows the
61
+ * provider did not report stay as `fallback` (aliases, 1M variants). A runtime without a live list keeps
62
+ * its static rows. MODEL_POLICY applies last.
63
+ * @param {typeof MODELS} base
64
+ * @param {Partial<Record<string, Array<{ id: string, label?: string, description?: string, efforts?: string[], effort?: string }> | undefined>>} live
65
+ * @returns {Array<(typeof MODELS)[number] & { source?: 'live' | 'fallback' | 'static' }>}
66
+ */
67
+ export function mergeCatalog(base, live) {
68
+ const out = [];
69
+ for (const runtime of CATALOG_RUNTIMES) {
70
+ const known = base.filter(entry => entry.runtime === runtime);
71
+ const listed = live?.[runtime];
72
+ const reported = (Array.isArray(listed) ? listed : []).filter(model => typeof model?.id === 'string' && model.id.trim());
73
+ if (!reported.length) { out.push(...known); continue; }
74
+ const seen = new Set();
75
+ for (const model of reported) {
76
+ if (seen.has(model.id)) continue;
77
+ seen.add(model.id);
78
+ const prior = known.find(entry => entry.id === model.id);
79
+ const priorEfforts = prior?.efforts ?? [];
80
+ const efforts = [...priorEfforts, ...(Array.isArray(model.efforts) ? model.efforts : []).filter(effort => typeof effort === 'string' && !priorEfforts.includes(effort))];
81
+ const effort = prior?.effort ?? (typeof model.effort === 'string' && efforts.includes(model.effort) ? model.effort : undefined);
82
+ const text = value => typeof value === 'string' && value ? value : undefined;
83
+ out.push({ runtime, id: model.id, label: text(model.label) ?? prior?.label ?? model.id, description: text(model.description) ?? prior?.description ?? '', efforts, ...(effort ? { effort } : {}), source: 'live' });
84
+ }
85
+ for (const entry of known) if (!seen.has(entry.id)) out.push({ ...entry, source: 'fallback' });
86
+ }
87
+ return out.map(entry => {
88
+ const policy = MODEL_POLICY[`${entry.runtime}:${entry.id}`];
89
+ return policy ? { ...entry, ...policy } : entry;
90
+ });
91
+ }
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
+
117
+ /** Where alpd caches the live catalog: ALP_HOME/cache/models.json. @param {string} home */
118
+ export const catalogCacheFile = home => path.join(home, 'cache', 'models.json');
119
+
120
+ /**
121
+ * The catalog as alpd last saw it, for readers outside alpd (alp setup, the Paseo plugin): static rows
122
+ * when there is no cache or it is unreadable. @param {string | undefined} home
123
+ */
124
+ export function catalogModels(home) {
125
+ if (!home) return MODELS;
126
+ try {
127
+ const cached = JSON.parse(readFileSync(catalogCacheFile(home), 'utf8'));
128
+ const providers = cached?.providers && typeof cached.providers === 'object' ? cached.providers : {};
129
+ return mergeCatalog(MODELS, Object.fromEntries(Object.entries(providers).map(([runtime, state]) => [runtime, Array.isArray(state?.models) ? state.models : undefined])));
130
+ } catch { return MODELS; }
131
+ }
@@ -0,0 +1,207 @@
1
+ import { existsSync, readFileSync, realpathSync } from 'node:fs';
2
+ import path from 'node:path';
3
+
4
+ /**
5
+ * How ALP starts its own processes, and where its bundle lives. ALP always runs under Node: from npm
6
+ * (`node cli.js`, `node alpd.js`) or from the ALP bundle (t-1807), which is the same npm install
7
+ * beside an official Node release, started by `bin/alp`:
8
+ *
9
+ * <app>/<version>/{bin/alp, node/bin/node, lib/node_modules/@anhlp/alp-cli, alp-bundle.json}
10
+ * <app>/current → <version> (install.sh and `alp update` move it)
11
+ *
12
+ * Paths that outlive this process (a launchd/systemd service, alpd's install record) name the bundle
13
+ * through `current`, so an update never leaves them on a removed version.
14
+ */
15
+
16
+ /**
17
+ * The native alpd (t-81b0.9): alpd compiled with `bun build --compile` into one executable, shipped as
18
+ * `<bundle>/bin/alpd` beside the bundle's Node. Only alpd is native; the `alp` CLI still runs on the
19
+ * bundle's Node. Its entry (packages/daemon/src/native-entry.ts) registers itself here before alpd loads:
20
+ * `modules` holds what alpd would otherwise import by a computed name (the Claude Agent SDK); `distDir`
21
+ * names the bundle's @anhlp/alp-cli dist, where the terminal helper is (undefined outside a bundle).
22
+ * @typedef {{ modules: { claudeAgentSdk?: () => Promise<any> }, distDir?: () => string | undefined }} NativeDaemon
23
+ */
24
+ const NATIVE = Symbol.for('alp.nativeDaemon');
25
+
26
+ /** Registers this process as the native alpd. Only native-entry.ts calls it. @param {NativeDaemon} native */
27
+ export function registerNativeDaemon(native) { /** @type {any} */ (globalThis)[NATIVE] = native; }
28
+
29
+ /** The native alpd's registration when this process is the native alpd, else undefined. @returns {NativeDaemon | undefined} */
30
+ export function nativeDaemon() { return /** @type {any} */ (globalThis)[NATIVE]; }
31
+
32
+ /** The native alpd's file name on this platform. */
33
+ export const NATIVE_DAEMON = process.platform === 'win32' ? 'alpd.exe' : 'alpd';
34
+
35
+ /** Whether `file` is named like the native alpd (alpd, alpd.exe). @param {string} file */
36
+ export const isNativeDaemonName = file => /^alpd(\.exe)?$/i.test(file.split(/[\\/]/).pop() ?? '');
37
+
38
+ /** Whether `file` is an ALP bundle's native alpd: `<bundle>/bin/alpd` beside alp-bundle.json. @param {string} file */
39
+ export const isBundleDaemon = file => isNativeDaemonName(file) && path.basename(path.dirname(file)) === 'bin' && existsSync(path.join(path.dirname(path.dirname(file)), 'alp-bundle.json'));
40
+
41
+ /** Subcommands of `alp` that run each ALP role in that process (`alp daemon run`, `alp dashboard serve`, `alp bridge acp`). */
42
+ export const ROLE_ARGS = Object.freeze({
43
+ daemon: Object.freeze(['daemon', 'run']),
44
+ dashboard: Object.freeze(['dashboard', 'serve']),
45
+ 'bridge-acp': Object.freeze(['bridge', 'acp']),
46
+ 'bridge-antigravity': Object.freeze(['bridge', 'antigravity']),
47
+ });
48
+
49
+ /**
50
+ * Whether `file` is named like the `alp` command (alp, alp.exe, alp.cmd) rather than a script: an
51
+ * install record or service written by the single-file executable of 0.0.1-beta.5/6 names it, and the
52
+ * bundle's launcher keeps that name.
53
+ * @param {string} file
54
+ */
55
+ export const isExecutableName = file => /^alp(\.exe|\.cmd)?$/i.test(file.split(/[\\/]/).pop() ?? '');
56
+
57
+ /** A file path that names a JavaScript entry rather than a command. @param {string} file */
58
+ export const isScript = file => /\.[cm]?js$/i.test(file);
59
+
60
+ /** The canonical form of a path: symlinks resolved when it exists, case-folded where the filesystem usually is. @param {string} file */
61
+ const canonical = file => {
62
+ let resolved = path.resolve(file);
63
+ try { resolved = realpathSync.native(resolved); } catch {}
64
+ return process.platform === 'darwin' || process.platform === 'win32' ? resolved.toLowerCase() : resolved;
65
+ };
66
+
67
+ /** Whether two paths name the same file (a symlink, or a differently cased path on macOS/Windows). @param {string} a @param {string} b */
68
+ export const samePath = (a, b) => canonical(a) === canonical(b);
69
+
70
+ /** The role's argument prefix. @param {keyof typeof ROLE_ARGS} role */
71
+ function roleArgs(role) {
72
+ const args = ROLE_ARGS[role];
73
+ if (!args) throw new TypeError(`Unknown ALP role: ${role}`);
74
+ return [...args];
75
+ }
76
+
77
+ /**
78
+ * @typedef {{ root: string, version: string, platform: string, app: string, current?: string }} BundleInfo
79
+ * root: the bundle directory (real path); app: its parent; current: `<app>/current` when it points at root.
80
+ */
81
+
82
+ const bundles = new Map();
83
+
84
+ /**
85
+ * The ALP bundle this Node belongs to, or undefined for any other Node (an npm install).
86
+ * @param {string} [execPath]
87
+ * @returns {BundleInfo | undefined}
88
+ */
89
+ export function bundleInfo(execPath = process.execPath) {
90
+ if (bundles.has(execPath)) return bundles.get(execPath);
91
+ let info;
92
+ try {
93
+ const real = realpathSync(execPath);
94
+ // node/bin/node on macOS and Linux, node/node.exe on Windows; or the native alpd, bin/alpd.
95
+ const native = isNativeDaemonName(real) && path.basename(path.dirname(real)) === 'bin';
96
+ const nodeDir = path.basename(path.dirname(real)) === 'bin' ? path.dirname(path.dirname(real)) : path.dirname(real);
97
+ const root = native ? nodeDir : path.dirname(nodeDir);
98
+ if (native || path.basename(nodeDir) === 'node') {
99
+ const manifest = JSON.parse(readFileSync(path.join(root, 'alp-bundle.json'), 'utf8'));
100
+ if (manifest?.name === 'alp' && typeof manifest.version === 'string') {
101
+ const app = path.dirname(root);
102
+ const current = path.join(app, 'current');
103
+ info = { root, version: manifest.version, platform: String(manifest.platform ?? ''), app, ...(existsSync(current) && samePath(current, root) ? { current } : {}) };
104
+ }
105
+ }
106
+ } catch {}
107
+ bundles.set(execPath, info);
108
+ return info;
109
+ }
110
+
111
+ /** The bundle's own Node executable. @param {BundleInfo} bundle */
112
+ export const bundleNode = bundle => path.join(bundle.root, 'node', process.platform === 'win32' ? 'node.exe' : 'bin/node');
113
+
114
+ /** The bundle's native alpd, whether or not it exists. @param {BundleInfo} bundle */
115
+ export const bundleDaemon = bundle => path.join(bundle.root, 'bin', NATIVE_DAEMON);
116
+
117
+ /** Where @anhlp/alp-cli's dist lies in the bundle (alpd.js, the terminal helper). @param {BundleInfo} bundle */
118
+ export const bundleDist = bundle => path.join(bundle.root, 'lib', 'node_modules', '@anhlp', 'alp-cli', 'dist');
119
+
120
+ /**
121
+ * The Node that runs JavaScript for this process: process.execPath, except in the native alpd, which
122
+ * cannot run a script (`spawn(execPath, [script])` would start alpd again, and `-e` is not evaluated):
123
+ * there it is the bundle's Node, or `node` on PATH for a native alpd outside a bundle.
124
+ */
125
+ export function nodeExecutable() {
126
+ if (!nativeDaemon()) return process.execPath;
127
+ const bundle = bundleInfo();
128
+ return bundle ? bundleNode(bundle) : 'node';
129
+ }
130
+
131
+ /**
132
+ * `file` named through `<app>/current` when it lies inside this process's bundle and `current` points
133
+ * at that bundle; otherwise `file` unchanged. For paths written to disk for later processes.
134
+ * @param {string} file
135
+ * @param {{ bundle?: BundleInfo | undefined }} [options]
136
+ */
137
+ export function stablePath(file, { bundle = bundleInfo() } = {}) {
138
+ if (!bundle?.current) return file;
139
+ let real;
140
+ try { real = realpathSync(file); } catch { return file; }
141
+ const relative = path.relative(bundle.root, real);
142
+ if (!relative || relative.startsWith('..') || path.isAbsolute(relative)) return file;
143
+ return path.join(bundle.current, relative);
144
+ }
145
+
146
+ /**
147
+ * The command that starts ALP's `role` from this process: `script` under this Node.
148
+ * @param {keyof typeof ROLE_ARGS} role
149
+ * @param {{ script: string, args?: string[] }} options
150
+ * @returns {{ command: string, args: string[] }}
151
+ */
152
+ export function selfCommand(role, { script, args = [] }) {
153
+ roleArgs(role);
154
+ // The native alpd is its own entry: it starts itself with its options only, never a script path.
155
+ if (nativeDaemon()) {
156
+ if (role !== 'daemon') throw new Error(`The native alpd cannot start ALP's ${role}`);
157
+ return { command: process.execPath, args: [...args] };
158
+ }
159
+ return { command: process.execPath, args: [script, ...args] };
160
+ }
161
+
162
+ /**
163
+ * The command that runs an `entry` found on disk (an install record, a service definition, a CLI
164
+ * on PATH): a script runs under `execPath`; an `alp` command (the bundle's launcher, or what a
165
+ * 0.0.1-beta.5/6 single-file install recorded) runs its role subcommand.
166
+ * @param {string} entry
167
+ * @param {keyof typeof ROLE_ARGS} role
168
+ * @param {string[]} [args]
169
+ * @param {string} [execPath]
170
+ * @param {{ scriptOnly?: boolean }} [options] scriptOnly: `entry` is always run under execPath (third-party integrations)
171
+ * @returns {{ command: string, args: string[] }}
172
+ */
173
+ export function entryCommand(entry, role, args = [], execPath = process.execPath, { scriptOnly = false } = {}) {
174
+ // The native alpd (t-81b0.9) runs on its own, with alpd's options: only a bundle's bin/alpd, so an
175
+ // extensionless script named alpd (an npm .bin shim, a source checkout) still runs under execPath.
176
+ if (!scriptOnly && role === 'daemon' && isBundleDaemon(entry)) return { command: entry, args: [...args] };
177
+ if (scriptOnly || isScript(entry) || !isExecutableName(entry)) return { command: execPath, args: [entry, ...args] };
178
+ return { command: entry, args: [...roleArgs(role), ...args] };
179
+ }
180
+
181
+ /**
182
+ * The command that runs a user's JavaScript file (a fake provider, an npm cmd shim on Windows) with this Node.
183
+ * @param {string} script
184
+ * @param {string[]} [args]
185
+ * @returns {{ command: string, args: string[], env?: Record<string, string> }}
186
+ */
187
+ export function scriptCommand(script, args = []) {
188
+ return { command: nodeExecutable(), args: [script, ...args] };
189
+ }
190
+
191
+ /**
192
+ * Where this process's own entry lives, for records that later processes read: `script`, through
193
+ * `current` in a bundle; the native alpd's own executable in the native alpd.
194
+ * @param {string} script
195
+ */
196
+ export function selfEntry(script) { return stablePath(nativeDaemon() ? process.execPath : script); }
197
+
198
+ /**
199
+ * What starts alpd for this `alp`: the bundle's native alpd when the bundle ships one, else `script`
200
+ * (alpd.js), each named through `current`. ALP_NATIVE_DAEMON=0 keeps alpd on the bundle's Node.
201
+ * @param {string} script alpd.js
202
+ * @param {{ bundle?: BundleInfo | undefined, env?: NodeJS.ProcessEnv }} [options]
203
+ */
204
+ export function daemonEntry(script, { bundle = bundleInfo(), env = process.env } = {}) {
205
+ const native = bundle && env.ALP_NATIVE_DAEMON !== '0' ? bundleDaemon(bundle) : undefined;
206
+ return stablePath(native && existsSync(native) ? native : script, { bundle });
207
+ }