@anhlp/alp-core 0.0.0-beta.1

package/src/init.js

@@ -0,0 +1,92 @@
+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';
+
+/**
+ * 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 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}`);
+  // Load the complete starter before modifying the destination.
+  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 } : {}) };
+}
+
+/** 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 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;
+}

package/src/library-edit.js

@@ -0,0 +1,346 @@
+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';
+
+/**
+ * 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 = ['agents', 'skills', 'mcp', 'hooks', 'teams', 'providers'];
+const validName = name => typeof name === 'string' && /^[\w.-]+$/.test(name) && name !== '.' && name !== '..';
+const object = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+const fail = (code, message) => { throw new AlpError(code, message); };
+
+/** The files an entry has, relative to its kind's directory, and what each holds. */
+const 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']],
+};
+/** The directory an entry owns, if any: removed whole on delete and moved whole on rename. */
+const 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;
+}
+/** The directory a scope writes to. */
+function base(scope, { root, library }, kind) {
+  // A project's provider would run a command from its repository on the user's machine.
+  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}'`);
+}
+const revisionOf = content => content === undefined ? null : createHash('sha256').update(JSON.stringify(content)).digest('hex').slice(0, 16);
+
+/** Reject repository-controlled links before any entry read or mutation. This is
+ * a preflight for static repository input, not a sandbox against same-user races. */
+async function safeEntryPaths(directory, kind, name) {
+  for (const [file] of FILES[kind](name)) {
+    await assertNoSymlinks(directory, path.join(kind, file));
+  }
+}
+
+/** An entry's content as one layer holds it, or undefined when that layer has none. */
+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 === undefined) 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 }); }
+  }
+  // An agent or skill is its instructions; a team its team.json.
+  const main = { agents: 'instructions', skills: 'body', teams: 'team' }[kind];
+  return found && (!main || content[main] !== undefined) ? content : undefined;
+}
+
+/** A built-in entry's content: the agents and teams ALP ships. */
+async function readBuiltin(kind, name, templates) {
+  if (kind === 'agents') {
+    const instructions = await builtinText(`agents/${name}/AGENT.md`, templates);
+    if (instructions === undefined) return undefined;
+    const config = await builtinText(`agents/${name}/agent.json`, templates);
+    return { instructions, ...(config !== undefined ? { config: JSON.parse(config) } : {}) };
+  }
+  if (kind === 'teams') {
+    const team = await builtinText(`teams/${name}/team.json`, templates);
+    if (team === undefined) return undefined;
+    return { team: JSON.parse(team), houseRules: (await builtinText(`teams/${name}/HOUSE_RULES.md`, templates)) ?? '' };
+  }
+  return undefined;
+}
+
+/** Each layer's version of an entry, in order: built-in, library, project. */
+async function layers(kind, name, { root, library, templates }) {
+  return {
+    builtin: await readBuiltin(kind, name, templates),
+    library: library ? await readLayer(kind, name, library) : undefined,
+    project: root && kind !== 'providers' ? await readLayer(kind, name, path.join(path.resolve(root), '.alp')) : undefined,
+  };
+}
+
+/**
+ * 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 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] !== undefined);
+  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] !== undefined);
+  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) } : {}),
+  };
+}
+
+/** role-skills.json: the library's skills for each agent, by name. */
+async function readGiven(library) {
+  const file = path.join(library, 'role-skills.json');
+  const text = await optionalText(file);
+  if (text === undefined) 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 };
+}
+
+/** The skills the library gives `agent`, as role-skills.json lists them. */
+export async function givenSkills(library, agent) {
+  const { roles } = await readGiven(library);
+  return Array.isArray(roles[agent]) ? roles[agent].filter(name => typeof name === '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 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 };
+}
+
+/** Every entry of a kind with its source and users, as `alp <kind>` lists them. */
+export 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;
+}
+
+/** Who refers to an entry: agents naming it, teams with it as a member, settings and role-skills.json. */
+export async function usersOf(kind, name, { root, library, templates } = {}) {
+  const users = 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();
+  }
+  // Agents naming it in agent.json, and for skills the roles role-skills.json gives it.
+  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();
+}
+
+/** Checks content for a kind, and that what it names exists where the entry will live. */
+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] === undefined && !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 !== undefined) {
+      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 !== undefined && !['codex', 'claude'].includes(provider) && !(await libraryEntries('providers', undefined, { 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); // retried on Windows while a reader has the target open
+}
+
+const exists = target => stat(target).then(() => true, () => false);
+
+/**
+ * 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 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 !== undefined && revision !== revisionOf(current)) {
+    fail('REVISION_CONFLICT', current === undefined ? `${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: 0o700 });
+  for (const [file, key, type] of FILES[kind](name)) {
+    const target = path.join(directory, kind, file);
+    const value = content[key];
+    // An empty agent.json or house rules file is no file.
+    const empty = value === undefined || (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}\n`);
+  }
+  return { revision: revisionOf(await readLayer(kind, name, directory)) };
+}
+
+/**
+ * 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 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 === undefined) fail('NOT_FOUND', `No ${kind} entry '${name}' in the ${scope}`);
+  if (revision !== undefined && 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 : undefined, library: scope === 'project' ? library : undefined, templates });
+  const fallback = scope === 'project' ? found.library ?? found.builtin : found.builtin;
+  if (fallback === undefined) {
+    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 });
+  /** @type {'builtin' | 'library'} */
+  const now = scope === 'project' && found.library !== undefined ? 'library' : 'builtin';
+  return { removed: true, ...(fallback !== undefined ? { now } : {}) };
+}
+
+/** Copies the entry that applies under `from` to a new entry `to` in a scope; built-ins are copied this way. */
+export 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 });
+}
+
+/** Renames an entry within a scope; refused while others refer to it by its old name. */
+export 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 === undefined) fail('NOT_FOUND', `No ${kind} entry '${from}' in the ${scope}`);
+  if (await readLayer(kind, to, directory) !== undefined) 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)) };
+}
+

package/src/library.js

@@ -0,0 +1,117 @@
+import { shippedTemplateRoot } from './template-path.js';
+import { mkdir, readFile, readdir, writeFile } from 'node:fs/promises';
+import { moveFile } from './atomic.js';
+import { createHash, randomUUID } from 'node:crypto';
+import os from 'node:os';
+import path from 'node:path';
+import { AlpError } from './errors.js';
+
+/**
+ * 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 = process.env) {
+  return path.resolve(env.ALP_HOME || path.join(os.homedir(), '.alp'));
+}
+
+const MANIFEST = 'library.json';
+const sha = text => createHash('sha256').update(text.replaceAll('\r\n', '\n')).digest('hex');
+
+async function optional(file) {
+  try { return await readFile(file, 'utf8'); }
+  catch (error) { if (error.code === 'ENOENT') return undefined; throw error; }
+}
+
+/** Shipped library files: role skills, skill resources and default providers. */
+async function shippedFiles({ templateRoot, templates }) {
+  if (templates) return Object.fromEntries(Object.entries(templates).filter(([name]) => name === 'role-skills.json' || name.startsWith('skills/') || name.startsWith('providers/')));
+  const root = templateRoot ?? shippedTemplateRoot();
+  const files = { 'role-skills.json': await readFile(new URL('role-skills.json', root), 'utf8') };
+  async function walk(relative) {
+    for (const entry of await readdir(new URL(`${relative}/`, root), { withFileTypes: true })) {
+      if (entry.isDirectory()) await walk(`${relative}/${entry.name}`);
+      else if (entry.isFile()) files[`${relative}/${entry.name}`] = await readFile(new URL(`${relative}/${entry.name}`, root), 'utf8');
+    }
+  }
+  await walk('skills');
+  await walk('providers');
+  return files;
+}
+
+/**
+ * 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 async function seedLibrary(home, options = {}) {
+  const shipped = await shippedFiles(options);
+  await mkdir(home, { recursive: true, mode: 0o700 });
+  const manifestPath = path.join(home, MANIFEST);
+  const manifestText = await optional(manifestPath);
+  const manifest = manifestText ? JSON.parse(manifestText) : { files: {} };
+  const created = [];
+  const updated = [];
+  for (const [name, content] of Object.entries(shipped).sort(([a], [b]) => a.localeCompare(b))) {
+    const target = path.join(home, ...name.split('/'));
+    const current = await optional(target);
+    const seeded = manifest.files[name];
+    if (seeded === undefined) {
+      // A file the user made under a shipped name stays theirs.
+      if (current !== undefined) continue;
+      await mkdir(path.dirname(target), { recursive: true });
+      await writeFile(target, content, { flag: 'wx' }).catch(error => { if (error.code !== 'EEXIST') throw error; });
+      manifest.files[name] = sha(content);
+      created.push(name);
+    } else if (current !== undefined && sha(current) === seeded && seeded !== sha(content)) {
+      await writeFile(target, content);
+      manifest.files[name] = sha(content);
+      updated.push(name);
+    }
+    // Missing after seeding: the user deleted it. Changed: the user edited it. Both are kept.
+  }
+  if (created.length || updated.length || manifestText === undefined) {
+    await mkdir(home, { recursive: true });
+    const temporary = `${manifestPath}.${randomUUID().slice(0, 8)}.tmp`;
+    await writeFile(temporary, JSON.stringify(manifest, null, 2) + '\n');
+    await moveFile(temporary, manifestPath);
+  }
+  return { created, updated };
+}
+
+const seeding = new Map();
+
+/** Seeds a library once per process; sessions call it on every open. */
+export function ensureLibrary(home, options = {}) {
+  let done = seeding.get(home);
+  if (!done) {
+    done = seedLibrary(home, options).catch(error => { seeding.delete(home); throw error; });
+    seeding.set(home, done);
+  }
+  return done;
+}
+
+const skillName = name => typeof name === 'string' && /^[\w.-]+$/.test(name) && name !== '.' && name !== '..';
+
+/** The library skills assigned to an agent, as named absolute SKILL.md paths that exist. */
+export async function librarySkills(home, agent) {
+  const file = path.join(home, 'role-skills.json');
+  const text = await optional(file);
+  if (text === undefined) return [];
+  let roles;
+  try { roles = JSON.parse(text); }
+  catch (cause) { throw new AlpError('INVALID_LIBRARY', `${file}: ${cause.message}`, { cause }); }
+  if (!roles || typeof roles !== 'object' || Array.isArray(roles)) throw new AlpError('INVALID_LIBRARY', `${file}: expected an object of role names to skill lists`);
+  const names = roles[agent] ?? [];
+  if (!Array.isArray(names) || !names.every(skillName)) throw new AlpError('INVALID_LIBRARY', `${file}: ${agent} must list skill directory names`);
+  const skills = [];
+  for (const name of new Set(names)) {
+    const skillPath = path.join(home, 'skills', name, 'SKILL.md');
+    if (await optional(skillPath) !== undefined) skills.push({ name, path: skillPath });
+  }
+  return skills;
+}

package/src/log.d.ts

@@ -0,0 +1,37 @@
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+export const LEVELS: Readonly<Record<LogLevel, number>>;
+export const REDACTED: string;
+export const OMITTED: string;
+export type LogFields = {
+  code?: string;
+  error?: unknown;
+  sessionId?: string;
+  rootId?: string;
+  assignmentId?: string;
+  clientMessageId?: string;
+  requestId?: string;
+  agent?: string;
+  [key: string]: unknown;
+};
+export type LogRecord = {
+  time: string;
+  level: LogLevel;
+  component: string;
+  code?: string;
+  msg: string;
+  error?: { name?: string; code?: string | number; message: string; stack?: string; cause?: unknown };
+  [key: string]: unknown;
+};
+export type Logger = {
+  component: string;
+  debug(message: string, fields?: LogFields): void;
+  info(message: string, fields?: LogFields): void;
+  warn(message: string, fields?: LogFields): void;
+  error(message: string, fields?: LogFields): void;
+  child(extra?: LogFields, component?: string): Logger;
+};
+export function scrubText(text: unknown, options?: { env?: Record<string, string | undefined>; max?: number }): string;
+export function describeError(error: unknown, options?: { env?: Record<string, string | undefined> }): { name?: string; code?: string | number; message: string; stack?: string; cause?: unknown };
+export function redact(value: unknown, options?: { env?: Record<string, string | undefined> }): any;
+export function createLogger(options: { component: string; level?: LogLevel; context?: LogFields; write?: (line: string) => void; now?: () => Date; env?: Record<string, string | undefined> }): Logger;
+export function readLogTail(file: string, options?: { bytes?: number; env?: Record<string, string | undefined> }): Promise<Array<LogRecord | { legacy: string }>>;