@anhlp/alp-core 0.0.0-beta.1

package/dist/teams.d.ts

@@ -0,0 +1,69 @@
+/** Checks a team.json; the delegation graph must name members and stay acyclic. */
+export function validateTeam(config: any, source: any): any;
+/**
+ * Where each team comes from: built in, then the library, then the project. A team
+ * directory counts only with a team.json. `root` may be undefined outside a project.
+ * @returns {Promise<Map<string, { source: 'builtin' | 'library' | 'project', directory?: string, overrides?: 'builtin' | 'library' }>>}
+ */
+export function teamSources(root: any, { library, templates }?: {}): Promise<Map<string, {
+    source: "builtin" | "library" | "project";
+    directory?: string;
+    overrides?: "builtin" | "library";
+}>>;
+/**
+ * A team by id, with its house rules.
+ * @returns {Promise<{ id: string, source: 'builtin' | 'library' | 'project', label: string, description?: string, main: string,
+ *   members: Record<string, { role?: string, model?: string, thinking?: string }>, delegation: Record<string, string[]>,
+ *   oracleThinking?: Record<string, string>, oracleModels?: string[], maxPeers?: number, supervisor: false | { agent: string, model?: string, thinking?: string }, houseRules: string }>}
+ */
+export function resolveTeam(root: any, id: any, { library, templates }?: {}): Promise<{
+    id: string;
+    source: "builtin" | "library" | "project";
+    label: string;
+    description?: string;
+    main: string;
+    members: Record<string, {
+        role?: string;
+        model?: string;
+        thinking?: string;
+    }>;
+    delegation: Record<string, string[]>;
+    oracleThinking?: Record<string, string>;
+    oracleModels?: string[];
+    maxPeers?: number;
+    supervisor: false | {
+        agent: string;
+        model?: string;
+        thinking?: string;
+    };
+    houseRules: string;
+}>;
+/**
+ * Every team a project can use, in order: built-in, library, project; with what each overrides.
+ * A team that does not load is listed with its error.
+ * @param {string | undefined} root
+ * @param {{ library?: string, templates?: Record<string, string> }} [options]
+ * @returns {Promise<Array<{ id: string, source: 'builtin' | 'library' | 'project', label?: string, description?: string, overrides?: 'builtin' | 'library', path?: string, error?: string }>>}
+ */
+export function listTeams(root: string | undefined, options?: {
+    library?: string;
+    templates?: Record<string, string>;
+}): Promise<Array<{
+    id: string;
+    source: "builtin" | "library" | "project";
+    label?: string;
+    description?: string;
+    overrides?: "builtin" | "library";
+    path?: string;
+    error?: string;
+}>>;
+/**
+ * Teams (ALPD §42): a main agent, its members, who may delegate to whom, and the
+ * house rules every member follows. Phở and Cafe ship as built-in teams; the user's
+ * library (ALP_HOME/teams) and the project (.alp/teams) add teams or override one by
+ * its id, the later layer replacing the team whole.
+ */
+export const BUILTIN_TEAMS: string[];
+export const TEAM_SETTINGS: string[];
+export const TEAM_ROLES: string[];
+export function teamOf(id: any): any;

package/dist/teams.js

@@ -0,0 +1,159 @@
+// packages/core/src/teams.js
+import { readdir } from "node:fs/promises";
+import path from "node:path";
+import { AlpError } from "./errors.js";
+import { builtinText, optionalText } from "./resolver.js";
+import { settingsKeys, unknownMessage } from "./validation.js";
+var BUILTIN_TEAMS = ["pho", "cafe"];
+var TEAM_SETTINGS = ["$schema", "label", "description", "main", "members", "delegation", "maxPeers", "supervisor", "oracleModels", "oracleThinking", "modelSetup"];
+var TEAM_ROLES = ["lead", "peer", "advisor", "reviewer"];
+var MEMBER_SETTINGS = ["role", "model", "thinking"];
+var SUPERVISOR_SETTINGS = ["agent", "model", "thinking"];
+var aliases = { smart: "pho", supervised: "cafe" };
+var teamOf = (id) => aliases[id] ?? id;
+var object = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+var nonempty = (value) => typeof value === "string" && value.trim().length > 0;
+var validName = (name) => typeof name === "string" && /^[\w.-]+$/.test(name) && name !== "." && name !== "..";
+function keys(value, known, check, where) {
+  const { unknown } = settingsKeys(value, known);
+  check(!unknown.length, unknown.length ? `${where}${unknownMessage(unknown[0], known)}` : "");
+}
+function validateTeam(config, source) {
+  const check = (ok, message) => {
+    if (!ok) throw new AlpError("INVALID_TEAM", `${source}: ${message}`);
+  };
+  check(object(config), "expected an object");
+  keys(config, TEAM_SETTINGS, check, "");
+  if (config.modelSetup !== void 0) {
+    const setup = config.modelSetup;
+    check(object(setup) && ["default", "custom"].includes(setup.mode), "modelSetup.mode must be default or custom");
+    keys(setup, ["mode", "preset"], check, "modelSetup: ");
+    if (setup.mode === "default") check(["claude", "codex", "opencode", "antigravity", "mix"].includes(setup.preset), "modelSetup.preset must name a preset");
+    else check(setup.preset === void 0, "custom modelSetup has no preset");
+  }
+  check(nonempty(config.label), "label must be a nonempty string");
+  if (config.description !== void 0) check(typeof config.description === "string", "description must be a string");
+  check(validName(config.main), "main must name an agent");
+  check(object(config.members), "members must map agent names to { role, model, thinking }");
+  check(Object.hasOwn(config.members, config.main), `members must include main (${config.main})`);
+  for (const [name, member] of Object.entries(config.members)) {
+    const where = `members.${name}`;
+    check(validName(name) && object(member), `${where} must be an object under an agent name`);
+    keys(member, MEMBER_SETTINGS, check, `${where}: `);
+    if (name === config.main) check(member.role === void 0 || member.role === "main", `${where}.role: main's role is main`);
+    else check(TEAM_ROLES.includes(member.role), `${where}.role must be one of ${TEAM_ROLES.join(", ")}`);
+    for (const key of ["model", "thinking"]) if (member[key] !== void 0) check(nonempty(member[key]), `${where}.${key} must be a nonempty string`);
+  }
+  check(object(config.delegation), "delegation must map members to the members they may delegate to");
+  for (const [owner, targets] of Object.entries(config.delegation)) {
+    check(Object.hasOwn(config.members, owner), `delegation.${owner}: not a member`);
+    check(Array.isArray(targets) && new Set(targets).size === targets.length, `delegation.${owner} must list members once each`);
+    for (const target of targets) check(Object.hasOwn(config.members, target) && target !== config.main, `delegation.${owner}: ${target} is not a member main can be assigned to`);
+  }
+  const visiting = /* @__PURE__ */ new Set();
+  const visited = /* @__PURE__ */ new Set();
+  const visit = (owner) => {
+    check(!visiting.has(owner), `delegation cycle at '${owner}'`);
+    if (visited.has(owner)) return;
+    visiting.add(owner);
+    for (const target of config.delegation[owner] ?? []) visit(target);
+    visiting.delete(owner);
+    visited.add(owner);
+  };
+  for (const owner of Object.keys(config.delegation)) visit(owner);
+  if (config.oracleModels !== void 0) {
+    check(Array.isArray(config.oracleModels) && config.oracleModels.length > 0, "oracleModels must list runtime-prefixed models");
+    check(config.oracleModels.every((model) => typeof model === "string" && /^(codex|claude|antigravity|acp):[^\s]+$/.test(model)) && new Set(config.oracleModels).size === config.oracleModels.length, "oracleModels must list each model once");
+  }
+  if (config.oracleThinking !== void 0) {
+    check(object(config.oracleThinking), "oracleThinking must map providers to effort");
+    for (const [provider, effort] of Object.entries(config.oracleThinking)) check((["codex", "claude", "antigravity", "acp"].includes(provider) || /^(codex|claude|antigravity|acp):[^\s]+$/.test(provider)) && ["none", "off", "low", "medium", "high", "xhigh", "max", "ultra", "ultracode"].includes(effort), "oracleThinking requires a provider or model ID and a supported effort");
+  }
+  if (config.maxPeers !== void 0) check(Number.isSafeInteger(config.maxPeers) && config.maxPeers >= 1, "maxPeers must be a positive integer");
+  if (config.supervisor !== void 0 && config.supervisor !== false) {
+    check(object(config.supervisor), "supervisor must be false or { agent, model, thinking }");
+    keys(config.supervisor, SUPERVISOR_SETTINGS, check, "supervisor: ");
+    check(validName(config.supervisor.agent), "supervisor.agent must name an agent");
+    check(!Object.hasOwn(config.members, config.supervisor.agent), "supervisor.agent watches the team and cannot be a member");
+    for (const key of ["model", "thinking"]) if (config.supervisor[key] !== void 0) check(nonempty(config.supervisor[key]), `supervisor.${key} must be a nonempty string`);
+  }
+  return config;
+}
+async function directories(directory) {
+  try {
+    return (await readdir(directory, { withFileTypes: true })).filter((entry) => entry.isDirectory() && validName(entry.name)).map((entry) => entry.name).sort();
+  } catch (error) {
+    if (error.code === "ENOENT") return [];
+    throw error;
+  }
+}
+async function teamSources(root, { library, templates } = {}) {
+  const found = /* @__PURE__ */ new Map();
+  for (const id of BUILTIN_TEAMS) if (await builtinText(`teams/${id}/team.json`, templates) !== void 0) found.set(id, { source: "builtin" });
+  const layer = async (directory, source) => {
+    for (const id of await directories(directory)) {
+      if (await optionalText(path.join(directory, id, "team.json")) === void 0) continue;
+      const previous = found.get(id);
+      found.set(id, { source, directory: path.join(directory, id), ...previous ? { overrides: previous.source } : {} });
+    }
+  };
+  if (library) await layer(path.join(library, "teams"), "library");
+  if (root !== void 0) await layer(path.join(path.resolve(root), ".alp", "teams"), "project");
+  return found;
+}
+async function resolveTeam(root, id, { library, templates } = {}) {
+  const team = teamOf(id);
+  const sources = await teamSources(root, { library, templates });
+  const found = sources.get(team);
+  if (!found) throw new AlpError("TEAM_NOT_FOUND", `Team '${id}' not found; teams: ${[...sources.keys()].join(", ")}`);
+  const where = found.directory ? path.join(found.directory, "team.json") : `built-in teams/${team}/team.json`;
+  const text = found.directory ? await optionalText(where) : await builtinText(`teams/${team}/team.json`, templates);
+  let config;
+  try {
+    config = JSON.parse(text ?? "");
+  } catch (cause) {
+    throw new AlpError("INVALID_TEAM", `${where}: ${cause.message}`, { cause });
+  }
+  validateTeam(config, where);
+  const houseRules = (found.directory ? await optionalText(path.join(found.directory, "HOUSE_RULES.md")) : await builtinText(`teams/${team}/HOUSE_RULES.md`, templates)) ?? "";
+  return {
+    id: team,
+    source: found.source,
+    label: config.label,
+    ...config.description !== void 0 ? { description: config.description } : {},
+    main: config.main,
+    members: config.members,
+    delegation: config.delegation,
+    ...config.maxPeers !== void 0 ? { maxPeers: config.maxPeers } : {},
+    supervisor: config.supervisor ?? false,
+    oracleModels: config.oracleModels,
+    oracleThinking: config.oracleThinking,
+    ...config.modelSetup ? { modelSetup: config.modelSetup } : {},
+    houseRules: houseRules.trim()
+  };
+}
+async function listTeams(root, options = {}) {
+  const rows = [];
+  for (const [id, source] of await teamSources(root, options)) {
+    let team;
+    try {
+      team = await resolveTeam(root, id, options);
+    } catch (error) {
+      rows.push({ id, source: source.source, ...source.overrides ? { overrides: source.overrides } : {}, error: error.message });
+      continue;
+    }
+    rows.push({ id, source: source.source, label: team.label, ...team.description !== void 0 ? { description: team.description } : {}, ...source.overrides ? { overrides: source.overrides } : {}, ...source.directory ? { path: source.directory } : {} });
+  }
+  const rank = { builtin: 0, library: 1, project: 2 };
+  return rows.sort((a, b) => rank[a.source] - rank[b.source] || (BUILTIN_TEAMS.indexOf(a.id) + 1 || 99) - (BUILTIN_TEAMS.indexOf(b.id) + 1 || 99) || a.id.localeCompare(b.id));
+}
+export {
+  BUILTIN_TEAMS,
+  TEAM_ROLES,
+  TEAM_SETTINGS,
+  listTeams,
+  resolveTeam,
+  teamOf,
+  teamSources,
+  validateTeam
+};

package/dist/template-path.d.ts

@@ -0,0 +1,2 @@
+/** Source packages carry templates beside src; legacy bundles live one directory deeper. */
+export function shippedTemplateRoot(): URL;

package/dist/template-path.js

@@ -0,0 +1,10 @@
+// packages/core/src/template-path.js
+import { existsSync } from "node:fs";
+function shippedTemplateRoot() {
+  const packaged = new URL("../templates/", import.meta.url);
+  const candidates = [packaged, new URL("../../templates/", import.meta.url), new URL("../../../templates/", import.meta.url), new URL("../../../../templates/", import.meta.url), new URL("../../../../../templates/", import.meta.url)];
+  return candidates.find((candidate) => existsSync(candidate)) ?? packaged;
+}
+export {
+  shippedTemplateRoot
+};

package/dist/trust.d.ts

@@ -0,0 +1,8 @@
+/** Whether the user trusts this project's hooks. */
+export function isTrusted(home: any, projectRoot: any): Promise<boolean>;
+/** Records that the user trusts this project's hooks; `by` says how they agreed. */
+export function trustProject(home: any, projectRoot: any, by?: string): Promise<void>;
+/** Forgets a project's trust: ALP asks again before its hooks run. Returns whether it was trusted. */
+export function revokeProject(home: any, projectRoot: any): Promise<boolean>;
+/** Every trusted project, with when and how the user agreed. */
+export function trustedProjects(home: any): Promise<any[]>;

package/dist/trust.js

@@ -0,0 +1,47 @@
+// packages/core/src/trust.js
+import { mkdir, readFile, realpath, writeFile } from "node:fs/promises";
+import { moveFile } from "./atomic.js";
+import { randomUUID } from "node:crypto";
+import path from "node:path";
+var file = (home) => path.join(home, "state", "trust.json");
+var key = (root) => realpath(path.resolve(root)).catch(() => path.resolve(root));
+async function load(home) {
+  try {
+    const value = JSON.parse(await readFile(file(home), "utf8"));
+    return value && typeof value === "object" && value.projects && typeof value.projects === "object" ? value : { projects: {} };
+  } catch (error) {
+    if (error.code === "ENOENT" || error instanceof SyntaxError) return { projects: {} };
+    throw error;
+  }
+}
+async function store(home, value) {
+  await mkdir(path.dirname(file(home)), { recursive: true });
+  const temporary = `${file(home)}.${randomUUID().slice(0, 8)}.tmp`;
+  await writeFile(temporary, JSON.stringify(value, null, 2) + "\n");
+  await moveFile(temporary, file(home));
+}
+async function isTrusted(home, projectRoot) {
+  return Object.hasOwn((await load(home)).projects, await key(projectRoot));
+}
+async function trustProject(home, projectRoot, by = "user") {
+  const value = await load(home);
+  value.projects[await key(projectRoot)] = { trustedAt: (/* @__PURE__ */ new Date()).toISOString(), by };
+  await store(home, value);
+}
+async function revokeProject(home, projectRoot) {
+  const value = await load(home);
+  const root = await key(projectRoot);
+  if (!Object.hasOwn(value.projects, root)) return false;
+  delete value.projects[root];
+  await store(home, value);
+  return true;
+}
+async function trustedProjects(home) {
+  return Object.entries((await load(home)).projects).map(([root, entry]) => ({ root, ...entry })).sort((a, b) => a.root.localeCompare(b.root));
+}
+export {
+  isTrusted,
+  revokeProject,
+  trustProject,
+  trustedProjects
+};

package/dist/types.d.ts

@@ -0,0 +1,51 @@
+export interface AgentModelConfig { provider?: 'codex' | 'claude' | 'acp' | 'antigravity'; model?: string; effort?: string }
+export type AutoCompact = 'auto' | number;
+export type AgentProfilesConfig = {
+  /** "provider:model", "provider:*" for any model of that provider, or the earlier object form. */
+  profiles?: Array<string | AgentModelConfig>;
+  autocompact?: AutoCompact;
+  claude?: AgentModelConfig;
+  codex?: AgentModelConfig;
+} & AgentModelConfig;
+/** Disk configuration; no provider SDK types. */
+export interface RawSettings {
+  templateDefaults?: Record<string, Record<string, string>>;
+  team?: Record<string, Record<string, AgentProfilesConfig>>;
+  /** Legacy settings key; use team. */
+  profile?: Record<string, Record<string, AgentProfilesConfig>>;
+  defaultAgent?: string;
+  workflow?: { mode?: 'pho' | 'cafe' | 'smart' | 'supervised'; maxPeers?: number; supervisor?: boolean };
+  delegation?: Record<string, string[]>;
+  runtime?: { provider?: string; model?: string; reasoning?: string };
+}
+export interface RawMcpServer {
+  command?: string;
+  args?: string[];
+  cwd?: string;
+  env?: Record<string, string>;
+  url?: string;
+  headers?: Record<string, string>;
+}
+export interface RawMcpConfig { mcpServers?: Record<string, RawMcpServer> }
+export interface ResolvedResource { name: string; path: string }
+export interface ResolvedMcpConfig { mcpServers: Record<string, RawMcpServer> }
+/** JSON-serializable adapter input. All filesystem resource paths/cwd are absolute. */
+export interface ResolvedAgent {
+  name: string;
+  projectRoot: string;
+  instructions: { project: string; agent: string };
+  skills: ResolvedResource[];
+  hooks: ResolvedResource[];
+  mcp: ResolvedMcpConfig;
+  runtime: { provider?: string; model?: string; reasoning?: string };
+  /** The part of runtime that settings.json sets for every agent; it comes before a team's or the agent's choice. */
+  projectRuntime?: { provider?: string; model?: string; reasoning?: string };
+  /** Where the agent is defined: ALP's built-ins, the user's library, or the project (ALPD §41). */
+  source?: 'builtin' | 'library' | 'project';
+  /** The permission mode the agent runs in unless its caller asks for another. */
+  mode?: 'read-only' | 'workspace-write' | 'full-access';
+  description?: string;
+  /** The context window it works in before its runtime compacts, in tokens; absent: the model's (ALPD §57). */
+  context?: number;
+  autocompact?: AutoCompact;
+}

package/dist/upgrade.d.ts

@@ -0,0 +1,10 @@
+/** Explicit migration of the original scaffold; custom instructions remain owned by the user. */
+export function upgradeProject(projectRoot: any, { library, templates }?: {}): Promise<{
+    updated: never[];
+    removed: never[];
+    customSkills: never[];
+    customInstructions: never[];
+    backup: undefined;
+    created: string[];
+    preserved: string[];
+}>;

package/dist/upgrade.js

@@ -0,0 +1,200 @@
+// packages/core/src/upgrade.js
+import { shippedTemplateRoot } from "./template-path.js";
+import { projectProfiles, normalizeAgentProfiles, syncTemplateProfiles } from "./profiles.js";
+import { readFile, writeFile, mkdir, mkdtemp, lstat, readdir, rename, rm, rmdir } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { createHash } from "node:crypto";
+import { initProject } from "./init.js";
+import { validateSettings } from "./validation.js";
+import { resolveDelegation } from "./delegation.js";
+var legacy = {
+  "ALP.md": "# Project instructions\n\nAdd project-wide instructions here.\n",
+  ".alp/agents/main/AGENT.md": "# Main agent\n\nHelp with tasks in this project.\n"
+};
+var teamV1 = {
+  "ALP.md": ["c2785aac6538d10e79bd6fb59b11066ccdec77287edf950fad59aa57bf3417f1", "0875293195d35d965effb70bb150d1edbc789f66f72c545f7760dea4346b1a9a"],
+  ".alp/agents/main/AGENT.md": ["15d217cbc5ede782790d1086124598d9a2b5ff13bcf971a37231962fcef1b47c", "e7201a1ed7800d7500b5c8091bd8a435aa9d5138f247c2b02b8bf76299387c90", "5001b807bbb686aa1a3b7ecadf9501428909e052e8231281454fd41cbe0ebf27", "90f9903fcc97ddf6336e1a28b81103dddc60a6038dcf74d326be8998862cb022", "9085ab906e2744a4151ae5c63dd66a545115cd4c876be1fd80f0a0ed4e623da8", "fb55cfb0852d07592090de2c49e6c5c2b57936cbffc823dd24767c2db5e5f7fb"],
+  ".alp/agents/lead/AGENT.md": ["c259b085a3c102445f97e5c7d402ca68347bcc1a9b02d6ab96e02be6d8b6f9af", "2eef2a4474f757cd89b35b50638a1b23fe49a54c26bf0dedb24a96d7117ddd92", "6c71393c9b3aa655c4731bda96396ea3ec0d4da62cddb3ad50d1a24113416b77", "a382f0faa724e23a0ba9c212205978aa3fef87c3aecdf8823fba136e04568487", "547e3f8fc354b22c7beb3432182d68f4de1f24938375c8bfb167ae8afbf97de2"],
+  ".alp/agents/peer/AGENT.md": ["f3dcf16c8c899a5378a468e922ca3956fd72cbb3e3798ed1109f11e01aa8f476", "39ccf3317eba3003faad77ebad4489fae3eb3c4d89258a03f619d1d3d65af0b7", "c59e45e8f22eb0daca9b8b5e1b19e90666156807f160e75a21eca48b5fee1102", "9623dbf76eda598f6267629e993663c149acb0efd253f3900a4ee1eda8f2f9e7"],
+  ".alp/agents/oracle/AGENT.md": ["cdce1babcd587a190dc94a32a951ed70ce2c75f99c205a4049df940851ac7059"],
+  ".alp/agents/reviewer/AGENT.md": ["6eab9f918c79335a0665bf4e3a3a26b66258684d6725c4c95637e70e8d355123"]
+};
+var renamedProfiles = { smart: "pho", supervised: "cafe" };
+async function skillFiles(directory) {
+  const files = /* @__PURE__ */ new Map();
+  async function walk(relative) {
+    for (const entry of await readdir(path.join(directory, relative), { withFileTypes: true })) {
+      const name = relative ? `${relative}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) {
+        if (!await walk(name)) return false;
+      } else if (entry.isFile()) files.set(name, (await readFile(path.join(directory, name), "utf8")).replaceAll("\r\n", "\n"));
+      else return false;
+    }
+    return true;
+  }
+  try {
+    const info = await lstat(directory);
+    if (!info.isDirectory() || info.isSymbolicLink()) return void 0;
+    return await walk("") ? files : void 0;
+  } catch (error) {
+    if (error.code === "ENOENT") return void 0;
+    throw error;
+  }
+}
+async function upgradeProject(projectRoot, { library, templates } = {}) {
+  const root = path.resolve(projectRoot);
+  let settingsText;
+  try {
+    settingsText = await readFile(path.join(root, ".alp/settings.json"), "utf8");
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+  }
+  const settings = settingsText === void 0 ? void 0 : JSON.parse(settingsText);
+  if (settings !== void 0) validateSettings(settings, ".alp/settings.json");
+  await resolveDelegation(root);
+  const result = { ...await initProject(root, { library, templates, syncProfiles: false }), updated: [], removed: [], customSkills: [], customInstructions: [], backup: void 0 };
+  async function backupPath(name) {
+    if (!result.backup) {
+      const backups = path.join(root, ".alp/backups");
+      await mkdir(backups, { recursive: true });
+      result.backup = await mkdtemp(path.join(backups, "upgrade-"));
+    }
+    const backup = path.join(result.backup, name);
+    await mkdir(path.dirname(backup), { recursive: true });
+    return backup;
+  }
+  async function replace(name, before, after) {
+    const target = path.join(root, name);
+    if (!(await lstat(target)).isFile() || await readFile(target, "utf8") !== before) throw new Error(`File changed during upgrade: ${target}`);
+    const backup = await backupPath(name);
+    await writeFile(backup, before, { flag: "wx" });
+    await writeFile(target, after);
+    result.updated.push(name);
+  }
+  for (const name of ["ALP.md"]) {
+    const current = await readFile(path.join(root, name), "utf8");
+    const template = name === "ALP.md" ? "ALP.md" : name.slice(".alp/".length);
+    const desired = await readFile(new URL(`${template}`, shippedTemplateRoot()), "utf8");
+    const normalized = current.replaceAll("\r\n", "\n");
+    const known2 = normalized === legacy[name] || teamV1[name]?.includes(createHash("sha256").update(normalized).digest("hex"));
+    if (current !== desired && known2) await replace(name, current, desired);
+    else if (current !== desired) result.customInstructions.push(name);
+  }
+  const oldGraph = settings?.delegation;
+  const shippedGraph = oldGraph && Object.keys(oldGraph).length === 2 && JSON.stringify(oldGraph.main) === '["lead"]' && JSON.stringify(oldGraph.lead) === '["peer"]';
+  if (settings !== void 0) {
+    let next = structuredClone(settings);
+    if (next.workflow === void 0 && (oldGraph === void 0 || shippedGraph)) {
+      if (shippedGraph) delete next.delegation;
+      next.workflow = { mode: shippedGraph ? "cafe" : "pho", maxPeers: 2 };
+    } else if (Object.hasOwn(renamedProfiles, next.workflow?.mode)) next.workflow.mode = renamedProfiles[next.workflow.mode];
+    next.team = next.team || next.profile ? { ...next.profile ?? {}, ...next.team ?? {} } : await projectProfiles({ root, library, templates, runtime: next.runtime });
+    delete next.profile;
+    for (const profile of Object.values(next.team ?? {})) {
+      for (const [name, config] of Object.entries(profile)) profile[name] = normalizeAgentProfiles(config, name);
+    }
+    next = await syncTemplateProfiles(next, { root, library, templates });
+    validateSettings(next, ".alp/settings.json");
+    if (JSON.stringify(next) !== JSON.stringify(settings)) await replace(".alp/settings.json", settingsText, JSON.stringify(next, null, 2) + "\n");
+  }
+  const shipped = JSON.parse(await readFile(new URL("role-skills.json", shippedTemplateRoot()), "utf8"));
+  for (const [role, skills] of Object.entries(shipped)) {
+    for (const skill of skills) {
+      const relative = `.alp/agents/${role}/skills/${skill}`;
+      const files = await skillFiles(path.join(root, relative));
+      if (!files) continue;
+      const template = await skillFiles(fileURLToPath(new URL(`skills/${skill}`, shippedTemplateRoot())));
+      const same = template && files.size === template.size && [...files].every(([name, text]) => template.get(name) === text);
+      if (!same) {
+        result.customSkills.push(relative);
+        continue;
+      }
+      for (const name of files.keys()) await rename(path.join(root, relative, name), await backupPath(`${relative}/${name}`));
+      await rm(path.join(root, relative), { recursive: true });
+      result.removed.push(relative);
+    }
+  }
+  for (const role of ["main", "lead", "peer"]) {
+    const relative = `.alp/agents/${role}/skills/ask-alp`;
+    const directory = path.join(root, relative);
+    try {
+      const info = await lstat(directory);
+      if (!info.isDirectory() || info.isSymbolicLink()) {
+        result.customSkills.push(relative);
+        continue;
+      }
+      const names = await readdir(directory);
+      const file = path.join(directory, "SKILL.md");
+      if (names.length !== 1 || names[0] !== "SKILL.md" || !(await lstat(file)).isFile()) {
+        result.customSkills.push(relative);
+        continue;
+      }
+      const content = await readFile(file, "utf8");
+      const hash = createHash("sha256").update(content.replaceAll("\r\n", "\n")).digest("hex");
+      if (hash !== "f38128fafa2e8a75a0237a2fda9a71fc92ed3f1e0e62878db50e5a07376f2108") {
+        result.customSkills.push(relative);
+        continue;
+      }
+      await rename(file, await backupPath(`${relative}/SKILL.md`));
+      await rmdir(directory);
+      result.removed.push(relative);
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+    }
+  }
+  await retireAgentCopies(root, result, backupPath, replace);
+  return result;
+}
+var known = (name, text) => {
+  const normalized = text.replaceAll("\r\n", "\n");
+  return normalized === legacy[name] || teamV1[name]?.includes(createHash("sha256").update(normalized).digest("hex"));
+};
+async function onlyInstructions(directory) {
+  for (const entry of await readdir(directory, { withFileTypes: true })) {
+    if (entry.name === "AGENT.md" && entry.isFile()) continue;
+    if (entry.name === ".mcp.json" && entry.isFile()) {
+      try {
+        const mcp = JSON.parse(await readFile(path.join(directory, entry.name), "utf8"));
+        if (!Object.keys(mcp.mcpServers ?? {}).length && Object.keys(mcp).every((key) => key === "mcpServers")) continue;
+      } catch {
+      }
+      return false;
+    }
+    if ((entry.name === "skills" || entry.name === "hooks") && entry.isDirectory() && !(await readdir(path.join(directory, entry.name))).length) continue;
+    return false;
+  }
+  return true;
+}
+async function retireAgentCopies(root, result, backupPath, replace) {
+  for (const name of ["main", "lead", "peer", "oracle", "reviewer", "supervisor"]) {
+    const relative = `.alp/agents/${name}`;
+    const directory = path.join(root, relative);
+    const info = await lstat(directory).catch(() => void 0);
+    if (!info?.isDirectory() || info.isSymbolicLink()) continue;
+    const file = `${relative}/AGENT.md`;
+    const current = await readFile(path.join(root, file), "utf8").catch(() => void 0);
+    if (current === void 0) continue;
+    const desired = await readFile(new URL(`agents/${name}/AGENT.md`, shippedTemplateRoot()), "utf8");
+    const shipped = current === desired || known(file, current);
+    if (!shipped) {
+      result.customInstructions.push(file);
+      continue;
+    }
+    if (await onlyInstructions(directory)) {
+      for (const entry of await readdir(directory, { withFileTypes: true })) {
+        if (entry.isDirectory()) await rmdir(path.join(directory, entry.name));
+        else await rename(path.join(directory, entry.name), await backupPath(`${relative}/${entry.name}`));
+      }
+      await rmdir(directory);
+      result.removed.push(relative);
+    } else if (current !== desired) {
+      await replace(file, current, desired);
+    }
+  }
+  await rmdir(path.join(root, ".alp/agents")).catch(() => {
+  });
+}
+export {
+  upgradeProject
+};

package/dist/user-settings.d.ts

@@ -0,0 +1,6 @@
+export const DEFAULT_LANGUAGE: string;
+export const LANGUAGE_CHARS: number;
+export function userLanguage(home?: string): Promise<string>;
+export function languageSetting(home: string): Promise<{ language: string | null; applies: string; default: string }>;
+export function setLanguage(home: string | undefined, language: string | null): Promise<{ language: string | null; applies: string; default: string }>;
+export function setWebRelay(home: string, patch: { enabled?: boolean; endpoint?: string; useTls?: boolean }): Promise<{ enabled?: boolean; endpoint?: string; useTls?: boolean }>;

package/dist/user-settings.js

@@ -0,0 +1,72 @@
+// packages/core/src/user-settings.js
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { moveFile } from "./atomic.js";
+import { randomUUID } from "node:crypto";
+import path from "node:path";
+import { AlpError } from "./errors.js";
+import { validateUserSettings } from "./validation.js";
+var DEFAULT_LANGUAGE = "Vietnamese";
+var LANGUAGE_CHARS = 40;
+async function readSettings(home) {
+  const file = path.join(home, "settings.json");
+  let text;
+  try {
+    text = await readFile(file, "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT") return { file, settings: {} };
+    throw error;
+  }
+  let settings;
+  try {
+    settings = JSON.parse(text);
+  } catch (cause) {
+    throw new AlpError("INVALID_SETTINGS", `${file}: ${cause.message}`, { cause });
+  }
+  return { file, settings: validateUserSettings(settings, file) };
+}
+async function userLanguage(home) {
+  if (!home) return DEFAULT_LANGUAGE;
+  try {
+    return (await readSettings(home)).settings.language ?? DEFAULT_LANGUAGE;
+  } catch {
+    return DEFAULT_LANGUAGE;
+  }
+}
+async function languageSetting(home) {
+  const { settings } = await readSettings(home);
+  return { language: settings.language ?? null, applies: settings.language ?? DEFAULT_LANGUAGE, default: DEFAULT_LANGUAGE };
+}
+async function setLanguage(home, language) {
+  if (!home) throw new AlpError("INVALID_SCOPE", "No library: ALP_HOME is not set");
+  if (language !== null && (typeof language !== "string" || !language.trim() || language.trim().length > LANGUAGE_CHARS)) {
+    throw new AlpError("INVALID_SETTINGS", `A language is a name of at most ${LANGUAGE_CHARS} characters, such as Vietnamese or English`);
+  }
+  const { file, settings } = await readSettings(home);
+  const next = { ...settings };
+  if (language === null) delete next.language;
+  else next.language = language.trim();
+  validateUserSettings(next, file);
+  await mkdir(home, { recursive: true, mode: 448 });
+  const temporary = `${file}.${randomUUID().slice(0, 8)}.tmp`;
+  await writeFile(temporary, JSON.stringify(next, null, 2) + "\n");
+  await moveFile(temporary, file);
+  return languageSetting(home);
+}
+async function setWebRelay(home, patch) {
+  const { file, settings } = await readSettings(home);
+  const next = { ...settings, web: { ...settings.web, relay: { ...settings.web?.relay, ...patch } } };
+  validateUserSettings(next, file);
+  await mkdir(home, { recursive: true, mode: 448 });
+  const temporary = `${file}.${randomUUID().slice(0, 8)}.tmp`;
+  await writeFile(temporary, JSON.stringify(next, null, 2) + "\n");
+  await moveFile(temporary, file);
+  return next.web.relay;
+}
+export {
+  DEFAULT_LANGUAGE,
+  LANGUAGE_CHARS,
+  languageSetting,
+  setLanguage,
+  setWebRelay,
+  userLanguage
+};