@anhlp/alp-core 0.0.0-beta.1

package/dist/index.d.ts

@@ -0,0 +1,30 @@
+export * as adapter from "./adapter.js";
+export * as atomic from "./atomic.js";
+export * as backup from "./backup.js";
+export * as beads from "./beads.js";
+export * as delegation from "./delegation.js";
+export * as errors from "./errors.js";
+export * as formulas from "./formulas.js";
+export * as hook_run from "./hook-run.js";
+export * as hooks from "./hooks.js";
+export * as init from "./init.js";
+export * as library_edit from "./library-edit.js";
+export * as library from "./library.js";
+export * as log from "./log.js";
+export * as migrations from "./migrations.js";
+export * as models from "./models.js";
+export * as permissions from "./permissions.js";
+export * as profiles from "./profiles.js";
+export * as promptsafe from "./promptsafe.js";
+export * as providers from "./providers.js";
+export * as resolver from "./resolver.js";
+export * as state_schema from "./state-schema.js";
+export * as task_rows from "./task-rows.js";
+export * as tasks from "./tasks.js";
+export * as teams from "./teams.js";
+export * as trust from "./trust.js";
+export * as upgrade from "./upgrade.js";
+export * as user_settings from "./user-settings.js";
+export * as validation from "./validation.js";
+export * as verify from "./verify.js";
+export * as workflow from "./workflow.js";

package/dist/index.js

@@ -0,0 +1,63 @@
+// packages/core/src/index.js
+import * as adapter from "./adapter.js";
+import * as atomic from "./atomic.js";
+import * as backup from "./backup.js";
+import * as beads from "./beads.js";
+import * as delegation from "./delegation.js";
+import * as errors from "./errors.js";
+import * as formulas from "./formulas.js";
+import * as hook_run from "./hook-run.js";
+import * as hooks from "./hooks.js";
+import * as init from "./init.js";
+import * as library_edit from "./library-edit.js";
+import * as library from "./library.js";
+import * as log from "./log.js";
+import * as migrations from "./migrations.js";
+import * as models from "./models.js";
+import * as permissions from "./permissions.js";
+import * as profiles from "./profiles.js";
+import * as promptsafe from "./promptsafe.js";
+import * as providers from "./providers.js";
+import * as resolver from "./resolver.js";
+import * as state_schema from "./state-schema.js";
+import * as task_rows from "./task-rows.js";
+import * as tasks from "./tasks.js";
+import * as teams from "./teams.js";
+import * as trust from "./trust.js";
+import * as upgrade from "./upgrade.js";
+import * as user_settings from "./user-settings.js";
+import * as validation from "./validation.js";
+import * as verify from "./verify.js";
+import * as workflow from "./workflow.js";
+export {
+  adapter,
+  atomic,
+  backup,
+  beads,
+  delegation,
+  errors,
+  formulas,
+  hook_run,
+  hooks,
+  init,
+  library,
+  library_edit,
+  log,
+  migrations,
+  models,
+  permissions,
+  profiles,
+  promptsafe,
+  providers,
+  resolver,
+  state_schema,
+  task_rows,
+  tasks,
+  teams,
+  trust,
+  upgrade,
+  user_settings,
+  validation,
+  verify,
+  workflow
+};

package/dist/init.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Fill missing scaffold files without replacing existing user content: ALP.md and
+ * .alp/settings.json. Agents, skills, MCP servers and hooks come from ALP's built-ins
+ * and the user's library (ALPD §41); a project adds its own under .alp/ only to
+ * override them.
+ * @param {string} projectRoot
+ * @param {{ templateRoot?: URL, templates?: Record<string, string>, library?: string, syncProfiles?: boolean, onlyManagedProfiles?: boolean, teamIds?: string[] }} [options]
+ */
+export function initProject(projectRoot: string, { templateRoot, templates, library, syncProfiles, onlyManagedProfiles, teamIds }?: {
+    templateRoot?: URL;
+    templates?: Record<string, string>;
+    library?: string;
+    syncProfiles?: boolean;
+    onlyManagedProfiles?: boolean;
+    teamIds?: string[];
+}): Promise<{
+    updated?: string[] | undefined;
+    created: string[];
+    preserved: string[];
+}>;
+/** Refresh an existing project's settings only; a template Save must not scaffold unrelated folders.
+ * @param {string} projectRoot
+ * @param {{ library?: string, templates?: Record<string, string>, teamIds?: string[], replaceModels?: boolean }} [options]
+ */
+export function syncProjectSettings(projectRoot: string, { library, templates, teamIds, replaceModels }?: {
+    library?: string;
+    templates?: Record<string, string>;
+    teamIds?: string[];
+    replaceModels?: boolean;
+}): Promise<boolean>;

package/dist/init.js

@@ -0,0 +1,88 @@
+// packages/core/src/init.js
+import { shippedTemplateRoot } from "./template-path.js";
+import { mkdir, writeFile, lstat, readFile, rename, rm } from "node:fs/promises";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { projectProfiles, profileDefaults, syncTemplateProfiles } from "./profiles.js";
+import { validateSettings } from "./validation.js";
+async function initProject(projectRoot, { templateRoot, templates, library, syncProfiles = true, onlyManagedProfiles = false, teamIds } = {}) {
+  const root = path.resolve(projectRoot);
+  const sourceRoot = () => templateRoot ?? shippedTemplateRoot();
+  const template = (name) => templates ? Promise.resolve(templates[name]) : readFile(new URL(name, sourceRoot()), "utf8");
+  const scaffold = path.join(root, ".alp");
+  const existing = await lstat(scaffold).catch((error) => {
+    if (error.code !== "ENOENT") throw error;
+  });
+  if (existing && !existing.isDirectory()) throw new Error(`Expected a directory: ${scaffold}`);
+  const team = await projectProfiles({ root, templates, library, teamIds });
+  const files = {
+    "ALP.md": await template("ALP.md"),
+    ".alp/settings.json": JSON.stringify({ defaultAgent: "main", workflow: { mode: "pho" }, team, templateDefaults: profileDefaults(team) }, null, 2) + "\n"
+  };
+  const directories = [".alp"];
+  const created = [];
+  const preserved = [];
+  const updated = [];
+  await mkdir(root, { recursive: true });
+  for (const directory of directories) {
+    const target = path.join(root, directory);
+    try {
+      await mkdir(target);
+    } catch (error) {
+      if (error.code !== "EEXIST") throw error;
+      if (!(await lstat(target)).isDirectory()) throw new Error(`Expected a directory: ${target}`);
+    }
+  }
+  for (const [name, content] of Object.entries(files)) {
+    const target = path.join(root, name);
+    try {
+      await writeFile(target, content, { flag: "wx" });
+      created.push(name);
+    } catch (error) {
+      if (error.code !== "EEXIST") throw error;
+      if (!(await lstat(target)).isFile()) throw new Error(`Expected a regular file: ${target}`);
+      preserved.push(name);
+      if (name === ".alp/settings.json" && syncProfiles) {
+        const before = await readFile(target, "utf8");
+        const settings = JSON.parse(before);
+        validateSettings(settings, target);
+        const next = !onlyManagedProfiles || settings.team || settings.profile || settings.templateDefaults ? await syncTemplateProfiles(settings, { root, library, templates, teamIds }) : settings;
+        validateSettings(next, target);
+        if (JSON.stringify(next) !== JSON.stringify(settings)) {
+          if (await readFile(target, "utf8") !== before) throw new Error(`File changed during initialization: ${target}`);
+          await writeFile(target, JSON.stringify(next, null, 2) + "\n");
+          updated.push(name);
+        }
+      }
+    }
+  }
+  return { created, preserved, ...updated.length ? { updated } : {} };
+}
+async function syncProjectSettings(projectRoot, { library, templates, teamIds, replaceModels = false } = {}) {
+  const root = path.resolve(projectRoot);
+  const file = path.join(root, ".alp/settings.json");
+  const info = await lstat(file).catch((error) => {
+    if (error.code !== "ENOENT") throw error;
+  });
+  if (!info) return false;
+  if (!info.isFile()) throw new Error(`Expected a regular file: ${file}`);
+  const before = await readFile(file, "utf8");
+  const settings = JSON.parse(before);
+  validateSettings(settings, file);
+  const next = await syncTemplateProfiles(settings, { root, library, templates, teamIds, replaceModels });
+  validateSettings(next, file);
+  if (JSON.stringify(settings) === JSON.stringify(next)) return false;
+  const temporary = `${file}.${randomUUID()}.tmp`;
+  try {
+    await writeFile(temporary, JSON.stringify(next, null, 2) + "\n", { flag: "wx", mode: info.mode });
+    if (await readFile(file, "utf8") !== before) throw new Error(`Settings changed while saving the template: ${file}`);
+    await rename(temporary, file);
+  } finally {
+    await rm(temporary, { force: true });
+  }
+  return true;
+}
+export {
+  initProject,
+  syncProjectSettings
+};

package/dist/library-edit.d.ts

@@ -0,0 +1,90 @@
+/**
+ * One entry: the version that applies (the project's, else the library's, else the
+ * built-in), or one scope's version with `scope`. `revision` goes back with a save.
+ * @param {'agents' | 'skills' | 'mcp' | 'hooks' | 'teams' | 'providers'} kind
+ * @param {string} name
+ * @param {{ root?: string, library?: string, templates?: Record<string, string>, scope?: 'library' | 'project' }} [options]
+ * @returns {Promise<{ kind: 'agents' | 'skills' | 'mcp' | 'hooks' | 'teams' | 'providers', name: string, source: 'builtin' | 'library' | 'project', overrides?: 'builtin' | 'library' | 'project', content: Record<string, unknown>, revision: string | null, usedBy: string[] }>}
+ */
+export function getEntry(kind: "agents" | "skills" | "mcp" | "hooks" | "teams" | "providers", name: string, { root, library, templates, scope }?: {
+    root?: string;
+    library?: string;
+    templates?: Record<string, string>;
+    scope?: "library" | "project";
+}): Promise<{
+    kind: "agents" | "skills" | "mcp" | "hooks" | "teams" | "providers";
+    name: string;
+    source: "builtin" | "library" | "project";
+    overrides?: "builtin" | "library" | "project";
+    content: Record<string, unknown>;
+    revision: string | null;
+    usedBy: string[];
+}>;
+/** The skills the library gives `agent`, as role-skills.json lists them. */
+export function givenSkills(library: any, agent: any): Promise<string[]>;
+/**
+ * Sets the skills the library gives an agent (role-skills.json), so a built-in agent's
+ * skills change without copying its instructions. Every skill must be in the library.
+ * @returns {Promise<{ skills: string[] }>}
+ */
+export function setGivenSkills(agent: any, skills: any, { library }?: {}): Promise<{
+    skills: string[];
+}>;
+/** Every entry of a kind with its source and users, as `alp <kind>` lists them. */
+export function listEntries(kind: any, { root, library, templates }?: {}): Promise<{
+    name: string;
+    source: "builtin" | "library" | "project";
+    path?: string;
+    overrides?: "builtin" | "library";
+    description?: string;
+    usedBy?: string[];
+}[] | {
+    usedBy: any[];
+    path?: string | undefined;
+    overrides?: "library" | "builtin" | undefined;
+    name: string;
+    source: "library" | "project" | "builtin";
+}[]>;
+/** Who refers to an entry: agents naming it, teams with it as a member, settings and role-skills.json. */
+export function usersOf(kind: any, name: any, { root, library, templates }?: {}): Promise<any[]>;
+/**
+ * Creates or replaces an entry in a scope. `revision` is what getEntry returned for
+ * that scope (null to create); a different current revision refuses the save.
+ * @returns {Promise<{ revision: string | null }>}
+ */
+export function saveEntry(kind: any, name: any, content: any, { scope, root, library, templates, revision }?: {}): Promise<{
+    revision: string | null;
+}>;
+/**
+ * Removes an entry from a scope. When nothing else of that name is left below it, an
+ * entry others refer to stays, and the error lists them.
+ * @returns {Promise<{ removed: boolean, now?: 'builtin' | 'library' }>}
+ */
+export function deleteEntry(kind: any, name: any, { scope, root, library, templates, revision }?: {}): Promise<{
+    removed: boolean;
+    now?: "builtin" | "library";
+}>;
+/** Copies the entry that applies under `from` to a new entry `to` in a scope; built-ins are copied this way. */
+export function duplicateEntry(kind: any, from: any, to: any, { scope, root, library, templates }?: {}): Promise<{
+    revision: string | null;
+}>;
+/** Renames an entry within a scope; refused while others refer to it by its old name. */
+export function renameEntry(kind: any, from: any, to: any, { scope, root, library, templates }?: {}): Promise<{
+    revision: string | null;
+}>;
+/**
+ * Editing the library (ALPD §43): agents, skills, MCP servers, hooks and teams, in the
+ * user's library (ALP_HOME) or as a project's override (.alp/). Built-ins are never
+ * written; duplicate one, or save an entry of its name, to change it. Every save is
+ * checked first and written file by file through a temporary file and a rename; a
+ * revision taken when the entry was read refuses a save over someone else's change.
+ *
+ * An entry's content, by kind:
+ *   agents  { instructions, config? }   AGENT.md and agent.json
+ *   skills  { body }                    SKILL.md
+ *   mcp     { server }                  mcp/<name>.json
+ *   hooks   { hook }                    hooks/<name>.json
+ *   teams   { team, houseRules? }       team.json and HOUSE_RULES.md
+ *   providers { provider }              providers/<name>.json, in the library only (ALPD §46)
+ */
+export const EDIT_KINDS: string[];

package/dist/library-edit.js

@@ -0,0 +1,315 @@
+// packages/core/src/library-edit.js
+import { mkdir, rename, rm, stat, writeFile } from "node:fs/promises";
+import { createHash, randomUUID } from "node:crypto";
+import path from "node:path";
+import { moveFile } from "./atomic.js";
+import { AlpError } from "./errors.js";
+import { assertNoSymlinks } from "./safe-path.js";
+import { agentSources, builtinText, jsonObject, libraryEntries, optionalText } from "./resolver.js";
+import { teamSources, validateTeam } from "./teams.js";
+import { normalizeMcp, validateAgentConfig, validateHook } from "./validation.js";
+import { validateProvider } from "./providers.js";
+var EDIT_KINDS = ["agents", "skills", "mcp", "hooks", "teams", "providers"];
+var validName = (name) => typeof name === "string" && /^[\w.-]+$/.test(name) && name !== "." && name !== "..";
+var object = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+var fail = (code, message) => {
+  throw new AlpError(code, message);
+};
+var FILES = {
+  agents: (name) => [[`${name}/AGENT.md`, "instructions", "text"], [`${name}/agent.json`, "config", "json"]],
+  skills: (name) => [[`${name}/SKILL.md`, "body", "text"]],
+  mcp: (name) => [[`${name}.json`, "server", "json"]],
+  hooks: (name) => [[`${name}.json`, "hook", "json"]],
+  teams: (name) => [[`${name}/team.json`, "team", "json"], [`${name}/HOUSE_RULES.md`, "houseRules", "text"]],
+  providers: (name) => [[`${name}.json`, "provider", "json"]]
+};
+var ownDirectory = (kind) => ["agents", "skills", "teams"].includes(kind);
+function kindOf(kind) {
+  if (!EDIT_KINDS.includes(kind)) fail("INVALID_KIND", `Unknown kind '${kind}'; use one of ${EDIT_KINDS.join(", ")}`);
+  return kind;
+}
+function nameOf(name) {
+  if (!validName(name)) fail("INVALID_NAME", `'${name}' is not a valid name: use letters, digits, '.', '_' or '-'`);
+  return name;
+}
+function base(scope, { root, library }, kind) {
+  if (kind === "providers" && scope !== "library") fail("INVALID_SCOPE", "Providers live only in your library");
+  if (scope === "library") return library ?? fail("INVALID_SCOPE", "No library: ALP_HOME is not set");
+  if (scope === "project") return root ? path.join(path.resolve(root), ".alp") : fail("INVALID_SCOPE", "No project directory");
+  return fail("INVALID_SCOPE", `Scope must be library or project, not '${scope}'`);
+}
+var revisionOf = (content) => content === void 0 ? null : createHash("sha256").update(JSON.stringify(content)).digest("hex").slice(0, 16);
+async function safeEntryPaths(directory, kind, name) {
+  for (const [file] of FILES[kind](name)) {
+    await assertNoSymlinks(directory, path.join(kind, file));
+  }
+}
+async function readLayer(kind, name, directory) {
+  await safeEntryPaths(directory, kind, name);
+  const content = {};
+  let found = false;
+  for (const [file, key, type] of FILES[kind](name)) {
+    const target = path.join(directory, kind, file);
+    const text = await optionalText(target);
+    if (text === void 0) continue;
+    found = true;
+    if (type === "text") {
+      content[key] = text;
+      continue;
+    }
+    try {
+      content[key] = JSON.parse(text);
+    } catch (cause) {
+      throw new AlpError("INVALID_ENTRY", `${target}: ${cause.message}`, { cause });
+    }
+  }
+  const main = { agents: "instructions", skills: "body", teams: "team" }[kind];
+  return found && (!main || content[main] !== void 0) ? content : void 0;
+}
+async function readBuiltin(kind, name, templates) {
+  if (kind === "agents") {
+    const instructions = await builtinText(`agents/${name}/AGENT.md`, templates);
+    if (instructions === void 0) return void 0;
+    const config = await builtinText(`agents/${name}/agent.json`, templates);
+    return { instructions, ...config !== void 0 ? { config: JSON.parse(config) } : {} };
+  }
+  if (kind === "teams") {
+    const team = await builtinText(`teams/${name}/team.json`, templates);
+    if (team === void 0) return void 0;
+    return { team: JSON.parse(team), houseRules: await builtinText(`teams/${name}/HOUSE_RULES.md`, templates) ?? "" };
+  }
+  return void 0;
+}
+async function layers(kind, name, { root, library, templates }) {
+  return {
+    builtin: await readBuiltin(kind, name, templates),
+    library: library ? await readLayer(kind, name, library) : void 0,
+    project: root && kind !== "providers" ? await readLayer(kind, name, path.join(path.resolve(root), ".alp")) : void 0
+  };
+}
+async function getEntry(kind, name, { root, library, templates, scope } = {}) {
+  kindOf(kind);
+  nameOf(name);
+  const found = await layers(kind, name, { root, library, templates });
+  const order = scope ? [scope] : ["project", "library", "builtin"];
+  const source = order.find((layer) => found[layer] !== void 0);
+  if (!source) fail("NOT_FOUND", `No ${kind} entry '${name}'${scope ? ` in the ${scope}` : ""}`);
+  const below = ["builtin", "library", "project"].slice(0, ["builtin", "library", "project"].indexOf(source)).reverse().find((layer) => found[layer] !== void 0);
+  return {
+    kind,
+    name,
+    source: (
+      /** @type {'builtin' | 'library' | 'project'} */
+      source
+    ),
+    ...below ? { overrides: (
+      /** @type {'builtin' | 'library'} */
+      below
+    ) } : {},
+    content: found[source],
+    revision: revisionOf(found[source]),
+    usedBy: await usersOf(kind, name, { root, library, templates }),
+    // The skills the library gives an agent by name, whatever layer defines it (ALPD §49).
+    ...kind === "agents" && library ? { librarySkills: await givenSkills(library, name) } : {}
+  };
+}
+async function readGiven(library) {
+  const file = path.join(library, "role-skills.json");
+  const text = await optionalText(file);
+  if (text === void 0) return { file, roles: {} };
+  let roles;
+  try {
+    roles = JSON.parse(text);
+  } catch (cause) {
+    throw new AlpError("INVALID_LIBRARY", `${file}: ${cause.message}`, { cause });
+  }
+  if (!object(roles)) fail("INVALID_LIBRARY", `${file}: expected an object of agent names to skill lists`);
+  return { file, roles };
+}
+async function givenSkills(library, agent) {
+  const { roles } = await readGiven(library);
+  return Array.isArray(roles[agent]) ? roles[agent].filter((name) => typeof name === "string") : [];
+}
+async function setGivenSkills(agent, skills, { library } = {}) {
+  nameOf(agent);
+  if (!library) fail("INVALID_SCOPE", "No library: ALP_HOME is not set");
+  if (!Array.isArray(skills) || !skills.every(validName)) fail("INVALID_ENTRY", "Skills must be a list of skill names");
+  const unique = [...new Set(skills)];
+  for (const skill of unique) if (!await exists(path.join(library, "skills", skill, "SKILL.md"))) fail("NOT_FOUND", `No skill '${skill}' in the library`);
+  const { file, roles } = await readGiven(library);
+  if (unique.length) roles[agent] = unique;
+  else delete roles[agent];
+  await writeAtomic(file, JSON.stringify(roles, null, 2) + "\n");
+  return { skills: unique };
+}
+async function listEntries(kind, { root, library, templates } = {}) {
+  kindOf(kind);
+  if (kind !== "teams") return libraryEntries(kind, root, { library, templates });
+  const rows = [];
+  for (const [name, source] of await teamSources(root, { library, templates })) rows.push({ name, source: source.source, ...source.overrides ? { overrides: source.overrides } : {}, ...source.directory ? { path: source.directory } : {}, usedBy: await usersOf(kind, name, { root, library, templates }) });
+  return rows;
+}
+async function usersOf(kind, name, { root, library, templates } = {}) {
+  const users = /* @__PURE__ */ new Set();
+  if (kind === "providers" && root) {
+    const settings = await jsonObject(path.join(path.resolve(root), ".alp", "settings.json"), "INVALID_SETTINGS").catch(() => ({}));
+    if (settings.runtime?.provider === name) users.add("project settings");
+  }
+  if (kind === "teams") {
+    if (root) {
+      const settings = await jsonObject(path.join(path.resolve(root), ".alp", "settings.json"), "INVALID_SETTINGS").catch(() => ({}));
+      if (settings.workflow?.mode === name) users.add("project settings");
+    }
+    return [...users];
+  }
+  if (kind === "agents") {
+    for (const [team, source] of await teamSources(root, { library, templates })) {
+      const text = source.directory ? await optionalText(path.join(source.directory, "team.json")) : await builtinText(`teams/${team}/team.json`, templates);
+      try {
+        const config = JSON.parse(text ?? "{}");
+        if (config.main === name || Object.hasOwn(config.members ?? {}, name) || config.supervisor?.agent === name) users.add(`team ${team}`);
+      } catch {
+      }
+    }
+    if (root) {
+      const settings = await jsonObject(path.join(path.resolve(root), ".alp", "settings.json"), "INVALID_SETTINGS").catch(() => ({}));
+      if (settings.defaultAgent === name) users.add("project settings");
+      for (const [owner, targets] of Object.entries(object(settings.delegation) ? settings.delegation : {})) if (owner === name || Array.isArray(targets) && targets.includes(name)) users.add("project delegation");
+    }
+    return [...users].sort();
+  }
+  const rows = await libraryEntries(kind, root, { library, templates });
+  for (const user of rows.find((row) => row.name === name)?.usedBy ?? []) users.add(`agent ${user}`);
+  return [...users].sort();
+}
+async function check(kind, name, content, { scope, root, library, templates }) {
+  if (!object(content)) fail("INVALID_ENTRY", `${kind} '${name}': content must be an object`);
+  const where = `${scope} ${kind} '${name}'`;
+  const visible = scope === "project" ? { root, library, templates } : { library, templates };
+  const text = (key, required) => {
+    if (content[key] === void 0 && !required) return;
+    if (typeof content[key] !== "string" || required && !content[key].trim()) fail("INVALID_ENTRY", `${where}: ${key} must be ${required ? "nonempty " : ""}text`);
+  };
+  const only = (keys) => {
+    for (const key of Object.keys(content)) if (!keys.includes(key)) fail("INVALID_ENTRY", `${where}: unknown field '${key}'; expected ${keys.join(", ")}`);
+  };
+  if (kind === "agents") {
+    only(["instructions", "config"]);
+    text("instructions", true);
+    if (content.config !== void 0) {
+      validateAgentConfig(content.config, `${where} agent.json`);
+      for (const [list, entries] of [["skills", "skills"], ["mcp", "mcp"], ["hooks", "hooks"]]) {
+        if (!content.config[list]?.length) continue;
+        const known = new Set((await libraryEntries(entries, visible.root, visible)).map((row) => row.name));
+        for (const entry of content.config[list]) if (!known.has(entry)) fail("NOT_FOUND", `${where}: ${list} names '${entry}', which is not in the ${scope === "project" ? "project or the library" : "library"}`);
+      }
+      const provider = content.config.provider;
+      if (provider !== void 0 && !["codex", "claude"].includes(provider) && !(await libraryEntries("providers", void 0, { library })).some((row) => row.name === provider)) {
+        fail("NOT_FOUND", `${where}: provider '${provider}' is neither codex, claude nor an ACP provider in your library`);
+      }
+    }
+  } else if (kind === "skills") {
+    only(["body"]);
+    text("body", true);
+  } else if (kind === "mcp") {
+    only(["server"]);
+    normalizeMcp({ mcpServers: { [name]: content.server } }, base(scope, { root, library }, kind), where);
+  } else if (kind === "hooks") {
+    only(["hook"]);
+    validateHook(content.hook, where);
+  } else if (kind === "providers") {
+    only(["provider"]);
+    validateProvider(content.provider, where, name);
+  } else {
+    only(["team", "houseRules"]);
+    text("houseRules", false);
+    validateTeam(content.team, `${where} team.json`);
+    const agents = await agentSources(visible.root, visible);
+    const supervisor = content.team.supervisor ? [content.team.supervisor.agent] : [];
+    for (const agent of [...Object.keys(content.team.members), ...supervisor]) if (!agents.has(agent)) fail("NOT_FOUND", `${where}: agent '${agent}' is not built in, nor in the ${scope === "project" ? "project or the library" : "library"}`);
+  }
+}
+async function writeAtomic(file, text) {
+  await mkdir(path.dirname(file), { recursive: true });
+  const temporary = `${file}.${randomUUID().slice(0, 8)}.tmp`;
+  await writeFile(temporary, text);
+  await moveFile(temporary, file);
+}
+var exists = (target) => stat(target).then(() => true, () => false);
+async function saveEntry(kind, name, content, { scope, root, library, templates, revision } = {}) {
+  kindOf(kind);
+  nameOf(name);
+  const directory = base(scope, { root, library }, kind);
+  await safeEntryPaths(directory, kind, name);
+  await check(kind, name, content, { scope, root, library, templates });
+  const current = await readLayer(kind, name, directory);
+  if (revision !== void 0 && revision !== revisionOf(current)) {
+    fail("REVISION_CONFLICT", current === void 0 ? `${kind} '${name}' was removed from the ${scope} since you opened it` : revision === null ? `${kind} '${name}' already exists in the ${scope}` : `${kind} '${name}' changed in the ${scope} since you opened it; reload it and apply your change again`);
+  }
+  if (scope === "library") await mkdir(directory, { recursive: true, mode: 448 });
+  for (const [file, key, type] of FILES[kind](name)) {
+    const target = path.join(directory, kind, file);
+    const value = content[key];
+    const empty = value === void 0 || type === "json" && key === "config" && !Object.keys(value).length || type === "text" && key === "houseRules" && !value.trim();
+    if (empty) {
+      await rm(target, { force: true });
+      continue;
+    }
+    await writeAtomic(target, type === "json" ? JSON.stringify(value, null, 2) + "\n" : value.endsWith("\n") ? value : `${value}
+`);
+  }
+  return { revision: revisionOf(await readLayer(kind, name, directory)) };
+}
+async function deleteEntry(kind, name, { scope, root, library, templates, revision } = {}) {
+  kindOf(kind);
+  nameOf(name);
+  const directory = base(scope, { root, library }, kind);
+  const current = await readLayer(kind, name, directory);
+  if (current === void 0) fail("NOT_FOUND", `No ${kind} entry '${name}' in the ${scope}`);
+  if (revision !== void 0 && revision !== revisionOf(current)) fail("REVISION_CONFLICT", `${kind} '${name}' changed in the ${scope} since you opened it`);
+  const found = await layers(kind, name, { root: scope === "project" ? root : void 0, library: scope === "project" ? library : void 0, templates });
+  const fallback = scope === "project" ? found.library ?? found.builtin : found.builtin;
+  if (fallback === void 0) {
+    const users = await usersOf(kind, name, { root, library, templates });
+    if (users.length) fail("IN_USE", `${kind} '${name}' is used by ${users.join(", ")}; change them first`);
+  }
+  if (ownDirectory(kind)) await rm(path.join(directory, kind, name), { recursive: true, force: true });
+  else for (const [file] of FILES[kind](name)) await rm(path.join(directory, kind, file), { force: true });
+  const now = scope === "project" && found.library !== void 0 ? "library" : "builtin";
+  return { removed: true, ...fallback !== void 0 ? { now } : {} };
+}
+async function duplicateEntry(kind, from, to, { scope, root, library, templates } = {}) {
+  const { content } = await getEntry(kind, from, { root, library, templates });
+  return saveEntry(kind, to, structuredClone(content), { scope, root, library, templates, revision: null });
+}
+async function renameEntry(kind, from, to, { scope, root, library, templates } = {}) {
+  kindOf(kind);
+  nameOf(from);
+  nameOf(to);
+  const directory = base(scope, { root, library }, kind);
+  const content = await readLayer(kind, from, directory);
+  if (content === void 0) fail("NOT_FOUND", `No ${kind} entry '${from}' in the ${scope}`);
+  if (await readLayer(kind, to, directory) !== void 0) fail("REVISION_CONFLICT", `${kind} '${to}' already exists in the ${scope}`);
+  const users = await usersOf(kind, from, { root, library, templates });
+  if (users.length) fail("IN_USE", `${kind} '${from}' is used by ${users.join(", ")}; change them first`);
+  await check(kind, to, content, { scope, root, library, templates });
+  if (ownDirectory(kind)) {
+    if (await exists(path.join(directory, kind, to))) fail("REVISION_CONFLICT", `${path.join(directory, kind, to)} already exists`);
+    await rename(path.join(directory, kind, from), path.join(directory, kind, to));
+  } else {
+    await rename(path.join(directory, kind, `${from}.json`), path.join(directory, kind, `${to}.json`));
+  }
+  return { revision: revisionOf(await readLayer(kind, to, directory)) };
+}
+export {
+  EDIT_KINDS,
+  deleteEntry,
+  duplicateEntry,
+  getEntry,
+  givenSkills,
+  listEntries,
+  renameEntry,
+  saveEntry,
+  setGivenSkills,
+  usersOf
+};

package/dist/library.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The user's library: skills, role assignments and default providers, kept in
+ * ALP_HOME and shared by every project. ALP seeds it from its templates once,
+ * then updates only files the user has not changed; a file the user edited or
+ * deleted stays that way across app updates.
+ */
+/** ALP_HOME, the user's ALP directory: alpd's home and the skill library. */
+export function alpHome(env?: NodeJS.ProcessEnv): string;
+/**
+ * Seeds or updates the library in `home`. A file is written when ALP never
+ * shipped it before, and replaced only while it still holds what ALP last wrote.
+ * @param {string} home
+ * @param {{ templateRoot?: URL, templates?: Record<string, string> }} [options]
+ */
+export function seedLibrary(home: string, options?: {
+    templateRoot?: URL;
+    templates?: Record<string, string>;
+}): Promise<{
+    created: string[];
+    updated: string[];
+}>;
+/** Seeds a library once per process; sessions call it on every open. */
+export function ensureLibrary(home: any, options?: {}): any;
+/** The library skills assigned to an agent, as named absolute SKILL.md paths that exist. */
+export function librarySkills(home: any, agent: any): Promise<{
+    name: any;
+    path: string;
+}[]>;