@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
@@ -0,0 +1,122 @@
1
+ /** Registers this process as the native alpd. Only native-entry.ts calls it. @param {NativeDaemon} native */
2
+ export function registerNativeDaemon(native: NativeDaemon): void;
3
+ /** The native alpd's registration when this process is the native alpd, else undefined. @returns {NativeDaemon | undefined} */
4
+ export function nativeDaemon(): NativeDaemon | undefined;
5
+ /**
6
+ * The ALP bundle this Node belongs to, or undefined for any other Node (an npm install).
7
+ * @param {string} [execPath]
8
+ * @returns {BundleInfo | undefined}
9
+ */
10
+ export function bundleInfo(execPath?: string): BundleInfo | undefined;
11
+ /**
12
+ * The Node that runs JavaScript for this process: process.execPath, except in the native alpd, which
13
+ * cannot run a script (`spawn(execPath, [script])` would start alpd again, and `-e` is not evaluated):
14
+ * there it is the bundle's Node, or `node` on PATH for a native alpd outside a bundle.
15
+ */
16
+ export function nodeExecutable(): string;
17
+ /**
18
+ * `file` named through `<app>/current` when it lies inside this process's bundle and `current` points
19
+ * at that bundle; otherwise `file` unchanged. For paths written to disk for later processes.
20
+ * @param {string} file
21
+ * @param {{ bundle?: BundleInfo | undefined }} [options]
22
+ */
23
+ export function stablePath(file: string, { bundle }?: {
24
+ bundle?: BundleInfo | undefined;
25
+ }): string;
26
+ /**
27
+ * The command that starts ALP's `role` from this process: `script` under this Node.
28
+ * @param {keyof typeof ROLE_ARGS} role
29
+ * @param {{ script: string, args?: string[] }} options
30
+ * @returns {{ command: string, args: string[] }}
31
+ */
32
+ export function selfCommand(role: keyof typeof ROLE_ARGS, { script, args }: {
33
+ script: string;
34
+ args?: string[];
35
+ }): {
36
+ command: string;
37
+ args: string[];
38
+ };
39
+ /**
40
+ * The command that runs an `entry` found on disk (an install record, a service definition, a CLI
41
+ * on PATH): a script runs under `execPath`; an `alp` command (the bundle's launcher, or what a
42
+ * 0.0.1-beta.5/6 single-file install recorded) runs its role subcommand.
43
+ * @param {string} entry
44
+ * @param {keyof typeof ROLE_ARGS} role
45
+ * @param {string[]} [args]
46
+ * @param {string} [execPath]
47
+ * @param {{ scriptOnly?: boolean }} [options] scriptOnly: `entry` is always run under execPath (third-party integrations)
48
+ * @returns {{ command: string, args: string[] }}
49
+ */
50
+ export function entryCommand(entry: string, role: keyof typeof ROLE_ARGS, args?: string[], execPath?: string, { scriptOnly }?: {
51
+ scriptOnly?: boolean;
52
+ }): {
53
+ command: string;
54
+ args: string[];
55
+ };
56
+ /**
57
+ * The command that runs a user's JavaScript file (a fake provider, an npm cmd shim on Windows) with this Node.
58
+ * @param {string} script
59
+ * @param {string[]} [args]
60
+ * @returns {{ command: string, args: string[], env?: Record<string, string> }}
61
+ */
62
+ export function scriptCommand(script: string, args?: string[]): {
63
+ command: string;
64
+ args: string[];
65
+ env?: Record<string, string>;
66
+ };
67
+ /**
68
+ * Where this process's own entry lives, for records that later processes read: `script`, through
69
+ * `current` in a bundle; the native alpd's own executable in the native alpd.
70
+ * @param {string} script
71
+ */
72
+ export function selfEntry(script: string): string;
73
+ /**
74
+ * What starts alpd for this `alp`: the bundle's native alpd when the bundle ships one, else `script`
75
+ * (alpd.js), each named through `current`. ALP_NATIVE_DAEMON=0 keeps alpd on the bundle's Node.
76
+ * @param {string} script alpd.js
77
+ * @param {{ bundle?: BundleInfo | undefined, env?: NodeJS.ProcessEnv }} [options]
78
+ */
79
+ export function daemonEntry(script: string, { bundle, env }?: {
80
+ bundle?: BundleInfo | undefined;
81
+ env?: NodeJS.ProcessEnv;
82
+ }): string;
83
+ /** The native alpd's file name on this platform. */
84
+ export const NATIVE_DAEMON: "alpd.exe" | "alpd";
85
+ export function isNativeDaemonName(file: string): boolean;
86
+ export function isBundleDaemon(file: string): boolean;
87
+ /** Subcommands of `alp` that run each ALP role in that process (`alp daemon run`, `alp dashboard serve`, `alp bridge acp`). */
88
+ export const ROLE_ARGS: Readonly<{
89
+ daemon: readonly string[];
90
+ dashboard: readonly string[];
91
+ 'bridge-acp': readonly string[];
92
+ 'bridge-antigravity': readonly string[];
93
+ }>;
94
+ export function isExecutableName(file: string): boolean;
95
+ export function isScript(file: string): boolean;
96
+ export function samePath(a: string, b: string): boolean;
97
+ export function bundleNode(bundle: BundleInfo): string;
98
+ export function bundleDaemon(bundle: BundleInfo): string;
99
+ export function bundleDist(bundle: BundleInfo): string;
100
+ /**
101
+ * The native alpd (t-81b0.9): alpd compiled with `bun build --compile` into one executable, shipped as
102
+ * `<bundle>/bin/alpd` beside the bundle's Node. Only alpd is native; the `alp` CLI still runs on the
103
+ * bundle's Node. Its entry (packages/daemon/src/native-entry.ts) registers itself here before alpd loads:
104
+ * `modules` holds what alpd would otherwise import by a computed name (the Claude Agent SDK); `distDir`
105
+ * names the bundle's
106
+ */
107
+ export type NativeDaemon = {
108
+ modules: {
109
+ claudeAgentSdk?: () => Promise<any>;
110
+ };
111
+ distDir?: () => string | undefined;
112
+ };
113
+ /**
114
+ * root: the bundle directory (real path); app: its parent; current: `<app>/current` when it points at root.
115
+ */
116
+ export type BundleInfo = {
117
+ root: string;
118
+ version: string;
119
+ platform: string;
120
+ app: string;
121
+ current?: string;
122
+ };
@@ -0,0 +1,125 @@
1
+ // packages/core/src/packaged.js
2
+ import { existsSync, readFileSync, realpathSync } from "node:fs";
3
+ import path from "node:path";
4
+ var NATIVE = Symbol.for("alp.nativeDaemon");
5
+ function registerNativeDaemon(native) {
6
+ globalThis[NATIVE] = native;
7
+ }
8
+ function nativeDaemon() {
9
+ return (
10
+ /** @type {any} */
11
+ globalThis[NATIVE]
12
+ );
13
+ }
14
+ var NATIVE_DAEMON = process.platform === "win32" ? "alpd.exe" : "alpd";
15
+ var isNativeDaemonName = (file) => /^alpd(\.exe)?$/i.test(file.split(/[\\/]/).pop() ?? "");
16
+ var isBundleDaemon = (file) => isNativeDaemonName(file) && path.basename(path.dirname(file)) === "bin" && existsSync(path.join(path.dirname(path.dirname(file)), "alp-bundle.json"));
17
+ var ROLE_ARGS = Object.freeze({
18
+ daemon: Object.freeze(["daemon", "run"]),
19
+ dashboard: Object.freeze(["dashboard", "serve"]),
20
+ "bridge-acp": Object.freeze(["bridge", "acp"]),
21
+ "bridge-antigravity": Object.freeze(["bridge", "antigravity"])
22
+ });
23
+ var isExecutableName = (file) => /^alp(\.exe|\.cmd)?$/i.test(file.split(/[\\/]/).pop() ?? "");
24
+ var isScript = (file) => /\.[cm]?js$/i.test(file);
25
+ var canonical = (file) => {
26
+ let resolved = path.resolve(file);
27
+ try {
28
+ resolved = realpathSync.native(resolved);
29
+ } catch {
30
+ }
31
+ return process.platform === "darwin" || process.platform === "win32" ? resolved.toLowerCase() : resolved;
32
+ };
33
+ var samePath = (a, b) => canonical(a) === canonical(b);
34
+ function roleArgs(role) {
35
+ const args = ROLE_ARGS[role];
36
+ if (!args) throw new TypeError(`Unknown ALP role: ${role}`);
37
+ return [...args];
38
+ }
39
+ var bundles = /* @__PURE__ */ new Map();
40
+ function bundleInfo(execPath = process.execPath) {
41
+ if (bundles.has(execPath)) return bundles.get(execPath);
42
+ let info;
43
+ try {
44
+ const real = realpathSync(execPath);
45
+ const native = isNativeDaemonName(real) && path.basename(path.dirname(real)) === "bin";
46
+ const nodeDir = path.basename(path.dirname(real)) === "bin" ? path.dirname(path.dirname(real)) : path.dirname(real);
47
+ const root = native ? nodeDir : path.dirname(nodeDir);
48
+ if (native || path.basename(nodeDir) === "node") {
49
+ const manifest = JSON.parse(readFileSync(path.join(root, "alp-bundle.json"), "utf8"));
50
+ if (manifest?.name === "alp" && typeof manifest.version === "string") {
51
+ const app = path.dirname(root);
52
+ const current = path.join(app, "current");
53
+ info = { root, version: manifest.version, platform: String(manifest.platform ?? ""), app, ...existsSync(current) && samePath(current, root) ? { current } : {} };
54
+ }
55
+ }
56
+ } catch {
57
+ }
58
+ bundles.set(execPath, info);
59
+ return info;
60
+ }
61
+ var bundleNode = (bundle) => path.join(bundle.root, "node", process.platform === "win32" ? "node.exe" : "bin/node");
62
+ var bundleDaemon = (bundle) => path.join(bundle.root, "bin", NATIVE_DAEMON);
63
+ var bundleDist = (bundle) => path.join(bundle.root, "lib", "node_modules", "@anhlp", "alp-cli", "dist");
64
+ function nodeExecutable() {
65
+ if (!nativeDaemon()) return process.execPath;
66
+ const bundle = bundleInfo();
67
+ return bundle ? bundleNode(bundle) : "node";
68
+ }
69
+ function stablePath(file, { bundle = bundleInfo() } = {}) {
70
+ if (!bundle?.current) return file;
71
+ let real;
72
+ try {
73
+ real = realpathSync(file);
74
+ } catch {
75
+ return file;
76
+ }
77
+ const relative = path.relative(bundle.root, real);
78
+ if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) return file;
79
+ return path.join(bundle.current, relative);
80
+ }
81
+ function selfCommand(role, { script, args = [] }) {
82
+ roleArgs(role);
83
+ if (nativeDaemon()) {
84
+ if (role !== "daemon") throw new Error(`The native alpd cannot start ALP's ${role}`);
85
+ return { command: process.execPath, args: [...args] };
86
+ }
87
+ return { command: process.execPath, args: [script, ...args] };
88
+ }
89
+ function entryCommand(entry, role, args = [], execPath = process.execPath, { scriptOnly = false } = {}) {
90
+ if (!scriptOnly && role === "daemon" && isBundleDaemon(entry)) return { command: entry, args: [...args] };
91
+ if (scriptOnly || isScript(entry) || !isExecutableName(entry)) return { command: execPath, args: [entry, ...args] };
92
+ return { command: entry, args: [...roleArgs(role), ...args] };
93
+ }
94
+ function scriptCommand(script, args = []) {
95
+ return { command: nodeExecutable(), args: [script, ...args] };
96
+ }
97
+ function selfEntry(script) {
98
+ return stablePath(nativeDaemon() ? process.execPath : script);
99
+ }
100
+ function daemonEntry(script, { bundle = bundleInfo(), env = process.env } = {}) {
101
+ const native = bundle && env.ALP_NATIVE_DAEMON !== "0" ? bundleDaemon(bundle) : void 0;
102
+ return stablePath(native && existsSync(native) ? native : script, { bundle });
103
+ }
104
+ export {
105
+ NATIVE_DAEMON,
106
+ ROLE_ARGS,
107
+ bundleDaemon,
108
+ bundleDist,
109
+ bundleInfo,
110
+ bundleNode,
111
+ daemonEntry,
112
+ entryCommand,
113
+ isBundleDaemon,
114
+ isExecutableName,
115
+ isNativeDaemonName,
116
+ isScript,
117
+ nativeDaemon,
118
+ nodeExecutable,
119
+ registerNativeDaemon,
120
+ samePath,
121
+ scriptCommand,
122
+ selfCommand,
123
+ selfEntry,
124
+ stablePath
125
+ };
@@ -0,0 +1,57 @@
1
+ /** Checks a pack.json against the files the pack holds. */
2
+ export function validatePack(id: any, manifest: any, files: any): any;
3
+ /**
4
+ * The packs ALP ships.
5
+ * @returns {Promise<Array<{ id: string, label: string, description: string, skills: string[], agents: string[], teams: string[], assign: Record<string, string[]>, permissions: Record<string, string> }>>}
6
+ */
7
+ export function listPacks(options?: {}): Promise<Array<{
8
+ id: string;
9
+ label: string;
10
+ description: string;
11
+ skills: string[];
12
+ agents: string[];
13
+ teams: string[];
14
+ assign: Record<string, string[]>;
15
+ permissions: Record<string, string>;
16
+ }>>;
17
+ /**
18
+ * Installs a pack into the library (`scope: 'library'`) or a project's .alp/ (`scope: 'project'`).
19
+ * Each entry is written to a temporary directory, checked (skills strictly, agent.json and team.json
20
+ * by their schemas), then renamed into place; an entry of that name already there is kept as is.
21
+ * `assign` (library only) adds the pack's suggested skills to roles in role-skills.json; the
22
+ * permissions a pack's agents need (an advisor's read-only cap) are added to that scope's settings
23
+ * only when the agent has no entry there, and a different entry is reported, never changed.
24
+ * @param {string} id
25
+ * @param {{ scope: 'library' | 'project', root?: string, library?: string, assign?: boolean, templates?: Record<string, string> }} options
26
+ */
27
+ export function installPack(id: string, { scope, root, library, assign, templates }?: {
28
+ scope: "library" | "project";
29
+ root?: string;
30
+ library?: string;
31
+ assign?: boolean;
32
+ templates?: Record<string, string>;
33
+ }): Promise<{
34
+ pack: string;
35
+ scope: "library" | "project";
36
+ installed: {
37
+ kind: string;
38
+ name: any;
39
+ path: string;
40
+ }[];
41
+ kept: {
42
+ kind: string;
43
+ name: any;
44
+ path: string;
45
+ }[];
46
+ assigned: string[];
47
+ permissions: {
48
+ set: never[];
49
+ kept: never[];
50
+ conflicts: never[];
51
+ };
52
+ }>;
53
+ /** Which of a pack's entries a scope already has: for listings. */
54
+ export function packStatus(pack: any, { root, library }?: {}): Promise<{
55
+ library: boolean;
56
+ project: boolean;
57
+ }>;
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,14 +2,14 @@
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);
9
9
  var agentProfiles = (config, name) => {
10
10
  if (!config) return [];
11
11
  if (name === "oracle") return oracleProfiles(config).map(parseProfile);
12
- const { autocompact, ...legacy } = config;
12
+ const { autocompact, commands, ...legacy } = config;
13
13
  return (config.profiles ?? [legacy]).map(parseProfile);
14
14
  };
15
15
  var parseProfile = (profile) => {
@@ -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);
@@ -31,7 +31,7 @@ function normalizeAgentProfiles(config, name) {
31
31
  if (config.profiles) return { ...config, profiles: config.profiles.map((profile) => typeof profile === "string" ? profile : profileString(profile)), autocompact: config.autocompact ?? "auto" };
32
32
  const profiles = agentProfiles(config, name);
33
33
  if (!profiles.length || profiles.some((profile) => !profile.model)) return config;
34
- return { profiles: profiles.map((profile) => profileString({ ...profile, provider: profile.provider ?? profile.model.split(":")[0] })), autocompact: config.autocompact ?? "auto" };
34
+ return { profiles: profiles.map((profile) => profileString({ ...profile, provider: profile.provider ?? profile.model.split(":")[0] })), autocompact: config.autocompact ?? "auto", ...config.commands ? { commands: config.commands } : {} };
35
35
  }
36
36
  var profileModel = (config) => config?.model ? config.model.includes(":") ? config.model : `${config.provider}:${config.model}` : void 0;
37
37
  var withEffort = (model, effort) => {
@@ -92,7 +92,7 @@ async function syncTemplateProfiles(settings, options = {}) {
92
92
  for (const name of /* @__PURE__ */ new Set([...Object.keys(previous[id] ?? {}), ...options.replaceModels ? Object.keys(current) : [], ...Object.keys(desired)])) {
93
93
  const config = current[name];
94
94
  if (!options.replaceModels && config && profileFingerprint(config, name) !== previous[id]?.[name]) continue;
95
- if (desired[name]) current[name] = { ...desired[name], autocompact: config?.autocompact ?? desired[name].autocompact };
95
+ if (desired[name]) current[name] = { ...desired[name], autocompact: config?.autocompact ?? desired[name].autocompact, ...config?.commands ? { commands: config.commands } : {} };
96
96
  else delete current[name];
97
97
  }
98
98
  if (Object.keys(current).length) next.team[id] = current;