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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (135) hide show
  1. package/dist/bridges.js +2 -2
  2. package/dist/library-edit.d.ts +51 -2
  3. package/dist/library-edit.js +160 -8
  4. package/dist/library.d.ts +14 -1
  5. package/dist/library.js +73 -5
  6. package/dist/models.d.ts +35 -0
  7. package/dist/models.js +17 -1
  8. package/dist/packaged.d.ts +45 -12
  9. package/dist/packaged.js +46 -5
  10. package/dist/packs.d.ts +57 -0
  11. package/dist/packs.js +247 -0
  12. package/dist/permissions.d.ts +3 -2
  13. package/dist/permissions.js +6 -3
  14. package/dist/profiles.js +3 -3
  15. package/dist/providers.d.ts +2 -4
  16. package/dist/providers.js +20 -4
  17. package/dist/skill-validate.d.ts +85 -0
  18. package/dist/skill-validate.js +298 -0
  19. package/dist/upgrade.d.ts +10 -0
  20. package/dist/upgrade.js +112 -6
  21. package/dist/user-settings.d.ts +2 -0
  22. package/dist/user-settings.js +40 -1
  23. package/dist/validation.d.ts +1 -0
  24. package/dist/validation.js +16 -10
  25. package/package.json +18 -2
  26. package/src/bridges.js +3 -2
  27. package/src/library-edit.js +170 -8
  28. package/src/library.js +96 -6
  29. package/src/models.js +24 -0
  30. package/src/packaged.js +77 -8
  31. package/src/packs.js +246 -0
  32. package/src/permissions.d.ts +3 -2
  33. package/src/permissions.js +13 -3
  34. package/src/profiles.js +4 -4
  35. package/src/providers.js +20 -5
  36. package/src/resolver.js +1 -1
  37. package/src/skill-validate.js +287 -0
  38. package/src/upgrade.js +54 -6
  39. package/src/user-settings.d.ts +2 -0
  40. package/src/user-settings.js +51 -1
  41. package/src/validation.d.ts +1 -0
  42. package/src/validation.js +21 -12
  43. package/templates/ALP.md +52 -52
  44. package/templates/agents/lead/AGENT.md +77 -74
  45. package/templates/agents/main/AGENT.md +153 -145
  46. package/templates/agents/oracle/AGENT.md +38 -37
  47. package/templates/agents/peer/AGENT.md +56 -52
  48. package/templates/agents/reviewer/AGENT.md +63 -65
  49. package/templates/agents/supervisor/AGENT.md +63 -63
  50. package/templates/packs/architecture/agents/architect/AGENT.md +41 -0
  51. package/templates/packs/architecture/agents/architect/agent.json +5 -0
  52. package/templates/packs/architecture/agents/docs-maintainer/AGENT.md +33 -0
  53. package/templates/packs/architecture/agents/docs-maintainer/agent.json +4 -0
  54. package/templates/packs/architecture/pack.json +7 -0
  55. package/templates/packs/architecture/teams/blueprint/HOUSE_RULES.md +12 -0
  56. package/templates/packs/architecture/teams/blueprint/team.json +19 -0
  57. package/templates/packs/backend/pack.json +6 -0
  58. package/templates/packs/backend/skills/backend-development/SKILL.md +102 -0
  59. package/templates/packs/backend/skills/backend-development/references/api-design.md +96 -0
  60. package/templates/packs/backend/skills/backend-development/references/authentication.md +78 -0
  61. package/templates/packs/backend/skills/backend-development/references/error-handling.md +86 -0
  62. package/templates/packs/backend/skills/backend-development/references/testing.md +81 -0
  63. package/templates/packs/backend/skills/databases/SKILL.md +103 -0
  64. package/templates/packs/backend/skills/databases/references/query-performance.md +87 -0
  65. package/templates/packs/backend/skills/databases/references/schema-and-migrations.md +87 -0
  66. package/templates/packs/design/pack.json +6 -0
  67. package/templates/packs/design/skills/ui-design/SKILL.md +86 -0
  68. package/templates/packs/design/skills/ui-design/references/design-tokens.md +67 -0
  69. package/templates/packs/design/skills/ui-design/references/interaction-states.md +73 -0
  70. package/templates/packs/design/skills/ui-design/references/layout-and-typography.md +71 -0
  71. package/templates/packs/design/skills/ui-design/references/ui-review.md +83 -0
  72. package/templates/packs/frontend/pack.json +6 -0
  73. package/templates/packs/frontend/skills/frontend-development/SKILL.md +105 -0
  74. package/templates/packs/frontend/skills/frontend-development/references/accessibility.md +86 -0
  75. package/templates/packs/frontend/skills/frontend-development/references/components-and-state.md +79 -0
  76. package/templates/packs/frontend/skills/frontend-development/references/data-fetching.md +86 -0
  77. package/templates/packs/frontend/skills/frontend-development/references/frameworks.md +77 -0
  78. package/templates/packs/frontend/skills/frontend-development/references/performance.md +78 -0
  79. package/templates/packs/integration/pack.json +6 -0
  80. package/templates/packs/integration/skills/mcp-integration/SKILL.md +100 -0
  81. package/templates/packs/integration/skills/mcp-integration/references/server-implementation.md +95 -0
  82. package/templates/packs/integration/skills/mcp-integration/references/testing.md +78 -0
  83. package/templates/packs/integration/skills/mcp-integration/references/tool-design.md +97 -0
  84. package/templates/packs/operations/pack.json +6 -0
  85. package/templates/packs/operations/skills/devops/SKILL.md +85 -0
  86. package/templates/packs/operations/skills/devops/references/ci-cd.md +84 -0
  87. package/templates/packs/operations/skills/devops/references/containers.md +85 -0
  88. package/templates/packs/operations/skills/devops/references/deployment-and-rollback.md +85 -0
  89. package/templates/packs/operations/skills/devops/references/observability.md +86 -0
  90. package/templates/packs/quality/pack.json +6 -0
  91. package/templates/packs/quality/skills/web-testing/SKILL.md +102 -0
  92. package/templates/packs/quality/skills/web-testing/references/e2e.md +85 -0
  93. package/templates/packs/quality/skills/web-testing/references/performance-testing.md +85 -0
  94. package/templates/packs/quality/skills/web-testing/references/security-testing.md +78 -0
  95. package/templates/packs/quality/skills/web-testing/references/unit-and-component.md +78 -0
  96. package/templates/role-skills.json +4 -4
  97. package/templates/skills/architecture-docs/SKILL.md +81 -0
  98. package/templates/skills/architecture-docs/references/adr.md +62 -0
  99. package/templates/skills/architecture-docs/references/diagrams.md +60 -0
  100. package/templates/skills/architecture-docs/references/evidence-rules.md +49 -0
  101. package/templates/skills/bug-loop/SKILL.md +41 -40
  102. package/templates/skills/bug-loop/references/test-proof.md +21 -19
  103. package/templates/skills/compact/SKILL.md +2 -2
  104. package/templates/skills/curate/SKILL.md +6 -5
  105. package/templates/skills/feature-architecture/SKILL.md +90 -0
  106. package/templates/skills/feature-architecture/references/architecture-contract.md +95 -0
  107. package/templates/skills/feature-architecture/references/feature-design.md +69 -0
  108. package/templates/skills/feature-architecture/scripts/check-boundaries.mjs +270 -0
  109. package/templates/skills/goal-griller/SKILL.md +27 -27
  110. package/templates/skills/prompt-leverage/SKILL.md +29 -27
  111. package/templates/skills/prompt-leverage/references/brief-template.md +9 -9
  112. package/templates/skills/release-readiness/SKILL.md +83 -0
  113. package/templates/skills/release-readiness/references/checklist.md +40 -0
  114. package/templates/skills/release-readiness/references/verdict-template.md +53 -0
  115. package/templates/skills/safe-refactor/SKILL.md +84 -0
  116. package/templates/skills/safe-refactor/references/characterization-tests.md +57 -0
  117. package/templates/skills/safe-refactor/references/compatibility-checklist.md +56 -0
  118. package/templates/skills/security-review/SKILL.md +87 -0
  119. package/templates/skills/security-review/references/checklist.md +74 -0
  120. package/templates/skills/security-review/references/severity.md +61 -0
  121. package/templates/skills/sequence-execution-plan/SKILL.md +41 -38
  122. package/templates/skills/sequence-execution-plan/references/plan-template.md +5 -5
  123. package/templates/skills/skill-authoring/SKILL.md +84 -0
  124. package/templates/skills/skill-authoring/references/evaluation.md +45 -0
  125. package/templates/skills/skill-authoring/references/skill-anatomy.md +74 -0
  126. package/templates/skills/skill-authoring/references/trigger-design.md +52 -0
  127. package/templates/skills/smart-commits/SKILL.md +37 -36
  128. package/templates/skills/test-strategy/SKILL.md +83 -0
  129. package/templates/skills/test-strategy/references/contract-tests.md +46 -0
  130. package/templates/skills/test-strategy/references/risk-matrix.md +53 -0
  131. package/templates/skills/xia/SKILL.md +40 -38
  132. package/templates/teams/cafe/HOUSE_RULES.md +1 -1
  133. package/templates/teams/cafe/team.json +1 -1
  134. package/templates/teams/pho/HOUSE_RULES.md +1 -1
  135. package/templates/teams/pho/team.json +1 -1
@@ -1,9 +1,19 @@
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;
1
5
  /**
2
6
  * The ALP bundle this Node belongs to, or undefined for any other Node (an npm install).
3
7
  * @param {string} [execPath]
4
8
  * @returns {BundleInfo | undefined}
5
9
  */
6
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;
7
17
  /**
8
18
  * `file` named through `<app>/current` when it lies inside this process's bundle and `current` points
9
19
  * at that bundle; otherwise `file` unchanged. For paths written to disk for later processes.
@@ -54,29 +64,52 @@ export function scriptCommand(script: string, args?: string[]): {
54
64
  args: string[];
55
65
  env?: Record<string, string>;
56
66
  };
57
- /** Where this process's own entry lives, for records that later processes read: `script`, through `current` in a bundle. @param {string} script */
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
+ */
58
72
  export function selfEntry(script: string): string;
59
73
  /**
60
- * How ALP starts its own processes, and where its bundle lives. ALP always runs under Node: from npm
61
- * (`node cli.js`, `node alpd.js`) or from the ALP bundle (t-1807), which is the same npm install
62
- * beside an official Node release, started by `bin/alp`:
63
- *
64
- * <app>/<version>/{bin/alp, node/bin/node, lib/node_modules/@anhlp/alp-cli, alp-bundle.json}
65
- * <app>/current → <version> (install.sh and `alp update` move it)
66
- *
67
- * Paths that outlive this process (a launchd/systemd service, alpd's install record) name the bundle
68
- * through `current`, so an update never leaves them on a removed version.
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]
69
78
  */
70
- /** Subcommands of `alp` that run each ALP role in that process (`alp daemon run`, `alp web serve`, `alp bridge acp`). */
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`). */
71
88
  export const ROLE_ARGS: Readonly<{
72
89
  daemon: readonly string[];
73
- web: readonly string[];
90
+ dashboard: readonly string[];
74
91
  'bridge-acp': readonly string[];
75
92
  'bridge-antigravity': readonly string[];
76
93
  }>;
77
94
  export function isExecutableName(file: string): boolean;
78
95
  export function isScript(file: string): boolean;
79
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
+ };
80
113
  /**
81
114
  * root: the bundle directory (real path); app: its parent; current: `<app>/current` when it points at root.
82
115
  */
package/dist/packaged.js CHANGED
@@ -1,9 +1,22 @@
1
1
  // packages/core/src/packaged.js
2
2
  import { existsSync, readFileSync, realpathSync } from "node:fs";
3
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"));
4
17
  var ROLE_ARGS = Object.freeze({
5
18
  daemon: Object.freeze(["daemon", "run"]),
6
- web: Object.freeze(["web", "serve"]),
19
+ dashboard: Object.freeze(["dashboard", "serve"]),
7
20
  "bridge-acp": Object.freeze(["bridge", "acp"]),
8
21
  "bridge-antigravity": Object.freeze(["bridge", "antigravity"])
9
22
  });
@@ -29,9 +42,10 @@ function bundleInfo(execPath = process.execPath) {
29
42
  let info;
30
43
  try {
31
44
  const real = realpathSync(execPath);
45
+ const native = isNativeDaemonName(real) && path.basename(path.dirname(real)) === "bin";
32
46
  const nodeDir = path.basename(path.dirname(real)) === "bin" ? path.dirname(path.dirname(real)) : path.dirname(real);
33
- const root = path.dirname(nodeDir);
34
- if (path.basename(nodeDir) === "node") {
47
+ const root = native ? nodeDir : path.dirname(nodeDir);
48
+ if (native || path.basename(nodeDir) === "node") {
35
49
  const manifest = JSON.parse(readFileSync(path.join(root, "alp-bundle.json"), "utf8"));
36
50
  if (manifest?.name === "alp" && typeof manifest.version === "string") {
37
51
  const app = path.dirname(root);
@@ -44,6 +58,14 @@ function bundleInfo(execPath = process.execPath) {
44
58
  bundles.set(execPath, info);
45
59
  return info;
46
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
+ }
47
69
  function stablePath(file, { bundle = bundleInfo() } = {}) {
48
70
  if (!bundle?.current) return file;
49
71
  let real;
@@ -58,24 +80,43 @@ function stablePath(file, { bundle = bundleInfo() } = {}) {
58
80
  }
59
81
  function selfCommand(role, { script, args = [] }) {
60
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
+ }
61
87
  return { command: process.execPath, args: [script, ...args] };
62
88
  }
63
89
  function entryCommand(entry, role, args = [], execPath = process.execPath, { scriptOnly = false } = {}) {
90
+ if (!scriptOnly && role === "daemon" && isBundleDaemon(entry)) return { command: entry, args: [...args] };
64
91
  if (scriptOnly || isScript(entry) || !isExecutableName(entry)) return { command: execPath, args: [entry, ...args] };
65
92
  return { command: entry, args: [...roleArgs(role), ...args] };
66
93
  }
67
94
  function scriptCommand(script, args = []) {
68
- return { command: process.execPath, args: [script, ...args] };
95
+ return { command: nodeExecutable(), args: [script, ...args] };
69
96
  }
70
97
  function selfEntry(script) {
71
- return stablePath(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 });
72
103
  }
73
104
  export {
105
+ NATIVE_DAEMON,
74
106
  ROLE_ARGS,
107
+ bundleDaemon,
108
+ bundleDist,
75
109
  bundleInfo,
110
+ bundleNode,
111
+ daemonEntry,
76
112
  entryCommand,
113
+ isBundleDaemon,
77
114
  isExecutableName,
115
+ isNativeDaemonName,
78
116
  isScript,
117
+ nativeDaemon,
118
+ nodeExecutable,
119
+ registerNativeDaemon,
79
120
  samePath,
80
121
  scriptCommand,
81
122
  selfCommand,
@@ -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,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