@anhlp/alp-core 0.0.0-beta.1

package/dist/validation.d.ts

@@ -0,0 +1,17 @@
+export const PROJECT_SETTINGS: string[];
+export const USER_SETTINGS: string[];
+export const RETIRED_SETTINGS: { project: Record<string, string>; user: Record<string, string> };
+export function settingsKeys(settings: unknown, known: string[], retired?: Record<string, string>): { unknown: Array<{ key: string; suggestion?: string }>; retired: Array<{ key: string; instead: string }> };
+export function settingsWarnings(settings: unknown, scope: 'project' | 'user'): string[];
+export function validateSettings(settings: unknown, source: string): { provider?: string; model?: string; reasoning?: string };
+export function validateUserSettings(settings: unknown, source: string): { language?: string; permissions?: unknown; limits?: { autoResume?: boolean }; recovery?: { autoResume?: boolean } };
+export function normalizeMcp(raw: unknown, directory: string, source: string): { mcpServers: Record<string, Record<string, unknown>> };
+export function validateResolvedAgent(agent: unknown): unknown;
+export const AGENT_SETTINGS: string[];
+export const CONTEXT_TOKENS: { min: number; max: number };
+export function validateAgentConfig(config: unknown, source: string): { description?: string; provider?: string; model?: string; thinking?: string; mode?: 'read-only' | 'workspace-write' | 'full-access'; skills?: string[]; mcp?: string[]; hooks?: string[] };
+export const HOOK_SETTINGS: string[];
+export const HOOK_EVENTS: string[];
+export const BLOCKING_HOOK_EVENTS: string[];
+export function validateHook(config: unknown, source: string): { description?: string; event: string; command: string; blocking?: boolean; timeoutSec?: number; match?: { agent?: string; label?: string } };
+export function unknownMessage(unknown: { key: string; suggestion?: string }, known: string[]): string;

package/dist/validation.js

@@ -0,0 +1,295 @@
+// packages/core/src/validation.js
+import path from "node:path";
+import { AlpError } from "./errors.js";
+import { MODELS } from "./models.js";
+import { validatePermissions } from "./permissions.js";
+import { validateVerify } from "./verify.js";
+var object = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+var nonempty = (value) => typeof value === "string" && value.trim().length > 0;
+var stringMap = (value) => object(value) && Object.values(value).every((v) => typeof v === "string");
+function requireValue(condition, code, source, message) {
+  if (!condition) throw new AlpError(code, `${source}: ${message}`);
+}
+var EFFORTS = ["none", "off", "low", "medium", "high", "xhigh", "max", "ultra", "ultracode"];
+var PROJECT_SETTINGS = ["$schema", "defaultAgent", "workflow", "runtime", "permissions", "verify", "delegation", "team", "profile", "templateDefaults"];
+var USER_SETTINGS = ["$schema", "language", "permissions", "limits", "recovery", "web"];
+var RETIRED_SETTINGS = { project: {}, user: {} };
+function distance(a, b) {
+  const row = Array.from({ length: b.length + 1 }, (_, index) => index);
+  for (let i = 1; i <= a.length; i++) {
+    let previous = row[0];
+    row[0] = i;
+    for (let j = 1; j <= b.length; j++) {
+      const kept = row[j];
+      row[j] = Math.min(row[j] + 1, row[j - 1] + 1, previous + (a[i - 1].toLowerCase() === b[j - 1].toLowerCase() ? 0 : 1));
+      previous = kept;
+    }
+  }
+  return row[b.length];
+}
+function settingsKeys(settings, known, retired = {}) {
+  const unknown = [];
+  const old = [];
+  for (const key of Object.keys(object(settings) ? settings : {})) {
+    if (known.includes(key)) continue;
+    if (Object.hasOwn(retired, key)) {
+      old.push({ key, instead: retired[key] });
+      continue;
+    }
+    const near = known.filter((candidate) => !candidate.startsWith("$")).map((candidate) => ({ candidate, d: distance(key, candidate) })).sort((a, b) => a.d - b.d)[0];
+    unknown.push({ key, ...near && near.d <= 2 ? { suggestion: near.candidate } : {} });
+  }
+  return { unknown, retired: old };
+}
+var unknownMessage = (unknown, known) => `unknown setting '${unknown.key}'${unknown.suggestion ? `; did you mean '${unknown.suggestion}'?` : `; known settings are ${known.filter((key) => !key.startsWith("$")).join(", ")}`}`;
+function settingsWarnings(settings, scope) {
+  return settingsKeys(settings, scope === "user" ? USER_SETTINGS : PROJECT_SETTINGS, RETIRED_SETTINGS[scope]).retired.map(({ key, instead }) => `setting '${key}' is no longer read; ${instead}`);
+}
+function validateSettings(settings, source) {
+  const check = (ok, message) => requireValue(ok, "INVALID_SETTINGS", source, message);
+  check(object(settings), "expected an object");
+  const { unknown } = settingsKeys(settings, PROJECT_SETTINGS, RETIRED_SETTINGS.project);
+  check(!unknown.length, unknown.length ? unknownMessage(unknown[0], PROJECT_SETTINGS) : "");
+  if (settings.defaultAgent !== void 0) check(nonempty(settings.defaultAgent), "defaultAgent must be a nonempty string");
+  if (settings.workflow !== void 0) {
+    check(object(settings.workflow), "workflow must be an object");
+    check(Object.keys(settings.workflow).every((key) => ["mode", "maxPeers", "supervisor"].includes(key)), "unsupported workflow field");
+    if (settings.workflow.mode !== void 0) check(typeof settings.workflow.mode === "string" && /^[\w.-]+$/.test(settings.workflow.mode) && settings.workflow.mode !== "custom", "workflow.mode must name a team, such as pho or cafe");
+    if (settings.workflow.maxPeers !== void 0) check(Number.isSafeInteger(settings.workflow.maxPeers) && settings.workflow.maxPeers > 0, "workflow.maxPeers must be a positive integer");
+    if (settings.workflow.supervisor !== void 0) check(typeof settings.workflow.supervisor === "boolean", "workflow.supervisor must be true or false");
+  }
+  if (settings.templateDefaults !== void 0) {
+    check(object(settings.templateDefaults), "templateDefaults must map teams to profile fingerprints");
+    for (const [team, agents] of Object.entries(settings.templateDefaults)) {
+      check(/^[\w.-]+$/.test(team) && object(agents), "templateDefaults must map teams to profile fingerprints");
+      for (const [agent, hash] of Object.entries(agents)) check(/^[\w.-]+$/.test(agent) && typeof hash === "string" && /^[a-f0-9]{64}$/.test(hash), "templateDefaults requires profile fingerprints");
+    }
+  }
+  for (const key of ["team", "profile"]) {
+    if (settings[key] === void 0) continue;
+    check(object(settings[key]), `${key} must map team names to agent configurations`);
+    const validateChoice = (config, where) => {
+      check(object(config), `${where} must be an object`);
+      check(Object.keys(config).every((key2) => ["provider", "model", "effort"].includes(key2)), `${where}: use provider, model and effort`);
+      if (config.provider !== void 0) check(["codex", "claude", "antigravity", "acp"].includes(config.provider), `${where}.provider must be codex, claude or antigravity`);
+      if (config.model !== void 0) {
+        check(nonempty(config.model) && !/\s/.test(config.model), `${where}.model must be a model ID`);
+        check(config.provider !== void 0 || /^(codex|claude|antigravity|acp):.+$/.test(config.model), `${where}: model needs a provider`);
+        if (config.model.includes(":")) check(/^(codex|claude|antigravity|acp):.+$/.test(config.model) && (!config.provider || config.model.startsWith(`${config.provider}:`)), `${where}: model and provider disagree`);
+      }
+      if (config.effort !== void 0) check(EFFORTS.includes(config.effort), `${where}.effort is unsupported`);
+    };
+    for (const [team, agents] of Object.entries(settings[key])) {
+      check(/^[\w.-]+$/.test(team) && object(agents), `${key}.${team} must map agent names to configurations`);
+      for (const [agent, config] of Object.entries(agents)) {
+        const where = `${key}.${team}.${agent}`;
+        check(object(config), `${where} must be an object`);
+        if (config.autocompact !== void 0) validateAutoCompact(config.autocompact, check, `${where}.autocompact`);
+        if (Object.hasOwn(config, "profiles")) {
+          check(Object.keys(config).every((key2) => ["profiles", "autocompact"].includes(key2)), `${where}: use profiles and autocompact`);
+          check(Array.isArray(config.profiles) && config.profiles.length > 0, `${where}.profiles must be a nonempty list`);
+          const models = [];
+          for (const [index, entry] of config.profiles.entries()) {
+            if (typeof entry === "string") {
+              const at = `${where}.profiles[${index}]`;
+              check(/^(codex|claude|antigravity):(\*|[^\s:*]+(:[a-z]+)?)$/.test(entry) || /^acp:[\w.-]+(?:\/[^\s:*]+)?$/.test(entry), `${at} must be "provider:model", "provider:model:effort" (such as "claude:claude-opus-5-5:high"), "acp:provider/model", or "codex:*" / "claude:*" for any model of that provider`);
+              const [provider, model, effort] = entry.split(":");
+              check(model !== "*" || agent !== "oracle" && agent !== "main", `${at}: ${agent} runs on a named model, not any model`);
+              if (effort !== void 0) {
+                const known = MODELS.find((candidate) => candidate.runtime === provider && candidate.id === model);
+                check(EFFORTS.includes(effort), `${at}: effort ${effort} is unsupported`);
+                check(!known?.efforts.length || known.efforts.includes(effort), `${at}: ${provider}:${model} takes effort ${known?.efforts.join(", ")}`);
+              }
+              models.push(`${provider}:${model}`);
+              continue;
+            }
+            validateChoice(entry, `${where}.profiles[${index}]`);
+            check(["claude", "codex", "antigravity"].includes(entry.provider) && nonempty(entry.model), `${where}.profiles[${index}]: specify provider and model`);
+            models.push(entry.model.includes(":") ? entry.model : `${entry.provider}:${entry.model}`);
+          }
+          check(new Set(models).size === models.length, `${where}.profiles must not repeat the same model`);
+          check(agent !== "main" || config.profiles.length === 1, `${where}.profiles: main runs on exactly one model`);
+        } else if (agent === "oracle") {
+          const entries = Object.entries(config).filter(([key2]) => key2 !== "autocompact");
+          check(entries.length > 0 && entries.every(([provider]) => ["claude", "codex"].includes(provider)), `${where} must define profiles or claude/codex lenses`);
+          for (const [provider, lens] of entries) {
+            validateChoice(lens, `${where}.${provider}`);
+            check(lens.provider === provider && nonempty(lens.model), `${where}.${provider}: specify matching provider and model`);
+          }
+        } else {
+          const { autocompact, ...legacy } = config;
+          validateChoice(legacy, where);
+        }
+      }
+    }
+  }
+  validatePermissions(settings.permissions, source);
+  validateVerify(settings.verify, source);
+  const runtime = settings.runtime ?? {};
+  if (settings.runtime !== void 0) check(object(settings.runtime), "runtime must be an object");
+  for (const key of Object.keys(runtime)) {
+    check(["provider", "model", "reasoning"].includes(key), `unsupported runtime field '${key}'`);
+    check(nonempty(runtime[key]), `runtime.${key} must be a nonempty string`);
+  }
+  return { ...runtime };
+}
+function validateUserSettings(settings, source) {
+  const check = (ok, message) => requireValue(ok, "INVALID_SETTINGS", source, message);
+  check(object(settings), "expected an object");
+  const { unknown } = settingsKeys(settings, USER_SETTINGS, RETIRED_SETTINGS.user);
+  check(!unknown.length, unknown.length ? unknownMessage(unknown[0], USER_SETTINGS) : "");
+  for (const key of ["limits", "recovery"]) {
+    if (settings[key] === void 0) continue;
+    check(object(settings[key]), `${key} must be an object`);
+    const extra = Object.keys(settings[key]).find((field) => field !== "autoResume");
+    check(!extra, `unsupported ${key} field '${extra}'; use autoResume`);
+    if (settings[key].autoResume !== void 0) check(typeof settings[key].autoResume === "boolean", `${key}.autoResume must be true or false`);
+  }
+  if (settings.web !== void 0) {
+    check(object(settings.web), "web must be an object");
+    const extra = Object.keys(settings.web).find((field) => !["enabled", "port", "relay"].includes(field));
+    check(!extra, `unsupported web field '${extra}'; use enabled, port or relay`);
+    const relay = settings.web.relay;
+    if (relay !== void 0) {
+      check(object(relay), "web.relay must be an object");
+      const unsupported = Object.keys(relay).find((field) => !["enabled", "endpoint", "useTls"].includes(field));
+      check(!unsupported, `unsupported web.relay field '${unsupported}'; use enabled, endpoint or useTls`);
+      if (relay.enabled !== void 0) check(typeof relay.enabled === "boolean", "web.relay.enabled must be true or false");
+      if (relay.endpoint !== void 0) check(typeof relay.endpoint === "string" && /^[a-z0-9.-]+:\d{1,5}$/i.test(relay.endpoint), "web.relay.endpoint must be host:port, such as relay.paseo.sh:443");
+      if (relay.useTls !== void 0) check(typeof relay.useTls === "boolean", "web.relay.useTls must be true or false");
+    }
+    if (settings.web.enabled !== void 0) check(typeof settings.web.enabled === "boolean", "web.enabled must be true or false");
+    if (settings.web.port !== void 0) check(Number.isInteger(settings.web.port) && settings.web.port >= 1024 && settings.web.port <= 65535, "web.port must be a port from 1024 to 65535");
+  }
+  if (settings.language !== void 0) check(nonempty(settings.language) && settings.language.trim().length <= 40, "language must be a language name of at most 40 characters, such as Vietnamese or English");
+  validatePermissions(settings.permissions, source);
+  return settings;
+}
+var AGENT_SETTINGS = ["$schema", "description", "provider", "model", "thinking", "mode", "context", "autocompact", "skills", "mcp", "hooks"];
+var CONTEXT_TOKENS = { min: 1e5, max: 1e6 };
+function validateAutoCompact(value, check, where) {
+  check(
+    value === "auto" || Number.isSafeInteger(value) && value >= CONTEXT_TOKENS.min && value <= CONTEXT_TOKENS.max,
+    `${where} must be "auto" or a number of tokens from ${CONTEXT_TOKENS.min} to ${CONTEXT_TOKENS.max}`
+  );
+}
+var AGENT_MODES = ["read-only", "workspace-write", "full-access"];
+var entryName = (value) => typeof value === "string" && /^[\w.-]+$/.test(value) && value !== "." && value !== "..";
+var HOOK_SETTINGS = ["$schema", "description", "event", "command", "blocking", "timeoutSec", "match"];
+var HOOK_EVENTS = ["session.start", "turn.end", "assignment.start", "assignment.end", "handoff", "task.close", "merge"];
+var BLOCKING_HOOK_EVENTS = ["handoff", "task.close", "merge"];
+function validateHook(config, source) {
+  const check = (ok, message) => requireValue(ok, "INVALID_HOOK", source, message);
+  check(object(config), "expected an object");
+  const { unknown } = settingsKeys(config, HOOK_SETTINGS);
+  check(!unknown.length, unknown.length ? unknownMessage(unknown[0], HOOK_SETTINGS) : "");
+  if (config.description !== void 0) check(typeof config.description === "string", "description must be a string");
+  check(HOOK_EVENTS.includes(config.event), `event must be one of ${HOOK_EVENTS.join(", ")}`);
+  check(nonempty(config.command), "command must be a nonempty string");
+  if (config.blocking !== void 0) {
+    check(typeof config.blocking === "boolean", "blocking must be true or false");
+    check(!config.blocking || BLOCKING_HOOK_EVENTS.includes(config.event), `only ${BLOCKING_HOOK_EVENTS.join(", ")} hooks can block`);
+  }
+  if (config.timeoutSec !== void 0) check(Number.isInteger(config.timeoutSec) && config.timeoutSec >= 1 && config.timeoutSec <= 3600, "timeoutSec must be a whole number of seconds from 1 to 3600");
+  if (config.match !== void 0) {
+    check(object(config.match) && Object.keys(config.match).every((key) => ["agent", "label"].includes(key)), "match may hold only agent and label");
+    for (const key of ["agent", "label"]) if (config.match[key] !== void 0) check(nonempty(config.match[key]), `match.${key} must be a nonempty string`);
+  }
+  return config;
+}
+function validateAgentConfig(config, source) {
+  const check = (ok, message) => requireValue(ok, "INVALID_AGENT_CONFIG", source, message);
+  check(object(config), "expected an object");
+  const { unknown } = settingsKeys(config, AGENT_SETTINGS);
+  check(!unknown.length, unknown.length ? unknownMessage(unknown[0], AGENT_SETTINGS) : "");
+  if (config.description !== void 0) check(typeof config.description === "string", "description must be a string");
+  for (const key of ["provider", "model", "thinking"]) if (config[key] !== void 0) check(nonempty(config[key]), `${key} must be a nonempty string`);
+  if (config.mode !== void 0) check(AGENT_MODES.includes(config.mode), `mode must be one of ${AGENT_MODES.join(", ")}`);
+  if (config.context !== void 0) {
+    check(
+      config.context === "auto" || Number.isSafeInteger(config.context) && config.context >= CONTEXT_TOKENS.min && config.context <= CONTEXT_TOKENS.max,
+      `context must be "auto" or a number of tokens from ${CONTEXT_TOKENS.min} to ${CONTEXT_TOKENS.max}`
+    );
+  }
+  if (config.autocompact !== void 0) validateAutoCompact(config.autocompact, check, "autocompact");
+  for (const key of ["skills", "mcp", "hooks"]) {
+    if (config[key] === void 0) continue;
+    check(Array.isArray(config[key]) && config[key].every(entryName), `${key} must list names of letters, digits, '.', '_' or '-'`);
+    check(new Set(config[key]).size === config[key].length, `${key} lists a name twice`);
+  }
+  return config;
+}
+function normalizeMcp(raw, directory, source) {
+  const check = (ok, message) => requireValue(ok, "INVALID_MCP", source, message);
+  check(object(raw), "expected an object");
+  check(Object.keys(raw).every((k) => k === "mcpServers"), "only mcpServers is supported");
+  const servers = raw.mcpServers === void 0 ? {} : raw.mcpServers;
+  check(object(servers), "mcpServers must be an object");
+  const normalized = [];
+  for (const [name, server] of Object.entries(servers)) {
+    check(nonempty(name) && object(server), `invalid server '${name}'`);
+    check(Object.keys(server).every((k) => ["command", "args", "cwd", "env", "url", "headers"].includes(k)), `${name}: unsupported server field`);
+    check(nonempty(server.command) !== nonempty(server.url), `${name}: specify exactly one of command or url`);
+    const result = { ...server };
+    if (server.command !== void 0) check(nonempty(server.command), `${name}.command must be nonempty`);
+    if (server.url !== void 0) {
+      check(nonempty(server.url), `${name}.url must be nonempty`);
+      let url;
+      try {
+        url = new URL(server.url);
+      } catch {
+      }
+      check(url && ["https:", "http:"].includes(url.protocol), `${name}.url must be an HTTP(S) URL`);
+      check(server.args === void 0 && server.cwd === void 0 && server.env === void 0, `${name}: args/cwd/env require command`);
+    }
+    if (server.args !== void 0) check(Array.isArray(server.args) && server.args.every((v) => typeof v === "string"), `${name}.args must be strings`);
+    for (const key of ["env", "headers"]) if (server[key] !== void 0) check(stringMap(server[key]), `${name}.${key} must map strings to strings`);
+    if (server.command !== void 0) check(server.headers === void 0, `${name}: headers require url`);
+    if (server.cwd !== void 0) {
+      check(nonempty(server.cwd), `${name}.cwd must be nonempty`);
+      result.cwd = path.resolve(directory, server.cwd);
+    }
+    if (server.command && /[\\/]/.test(server.command)) result.command = path.resolve(directory, server.command);
+    normalized.push([name, result]);
+  }
+  return { mcpServers: Object.fromEntries(normalized) };
+}
+function validateResolvedAgent(agent) {
+  const check = (ok, message) => requireValue(ok, "INVALID_RESOLVED_AGENT", "ResolvedAgent", message);
+  check(object(agent), "expected an object");
+  check(nonempty(agent.name), "name is required");
+  check(typeof agent.projectRoot === "string" && path.isAbsolute(agent.projectRoot), "projectRoot must be absolute");
+  check(object(agent.instructions) && typeof agent.instructions.project === "string" && typeof agent.instructions.agent === "string", "instructions must contain project and agent strings");
+  for (const key of ["skills", "hooks"]) {
+    check(Array.isArray(agent[key]), `${key} must be an array`);
+    for (const resource of agent[key]) check(object(resource) && nonempty(resource.name) && typeof resource.path === "string" && path.isAbsolute(resource.path), `${key} must contain named absolute paths`);
+  }
+  check(object(agent.runtime), "runtime must be an object");
+  validateSettings({ runtime: agent.runtime }, "ResolvedAgent.runtime");
+  normalizeMcp(agent.mcp, agent.projectRoot, "ResolvedAgent.mcp");
+  check(object(agent.mcp.mcpServers), "MCP must contain a normalized mcpServers map");
+  for (const server of Object.values(agent.mcp.mcpServers)) {
+    if (server.cwd !== void 0) check(path.isAbsolute(server.cwd), "MCP cwd must already be absolute");
+    if (server.command && /[\\/]/.test(server.command)) check(path.isAbsolute(server.command), "MCP command paths must already be absolute");
+  }
+  return agent;
+}
+export {
+  AGENT_SETTINGS,
+  BLOCKING_HOOK_EVENTS,
+  CONTEXT_TOKENS,
+  HOOK_EVENTS,
+  HOOK_SETTINGS,
+  PROJECT_SETTINGS,
+  RETIRED_SETTINGS,
+  USER_SETTINGS,
+  normalizeMcp,
+  settingsKeys,
+  settingsWarnings,
+  unknownMessage,
+  validateAgentConfig,
+  validateHook,
+  validateResolvedAgent,
+  validateSettings,
+  validateUserSettings
+};

package/dist/verify.d.ts

@@ -0,0 +1,15 @@
+export const VERIFY_STEPS: readonly ['setup', 'typecheck', 'test'];
+export const VERIFY_TIMEOUT_SEC: number;
+export const VERIFY_GRACE_MS: number;
+export const VERIFY_INFRA_EXIT: number;
+
+export type VerifyConfig = { setup?: string; typecheck?: string; test?: string; timeoutSec: number; idleSec?: number };
+
+export type VerifyCommand = { step: 'setup' | 'typecheck' | 'test'; command: string; exitCode: number; ms: number; output: string; timedOut?: boolean; idle?: boolean };
+
+export type Verification = { passed: boolean; cwd: string; commands: VerifyCommand[]; skipped?: string };
+
+export function validateVerify(verify: unknown, source: string): VerifyConfig | undefined;
+export function verifyConfig(projectRoot: string): Promise<VerifyConfig | undefined>;
+export function runVerify(cwd: string, config: VerifyConfig, options?: { env?: NodeJS.ProcessEnv }): Promise<Verification>;
+export function describeVerification(verified: { passed: boolean; commands: Array<{ step: string; exitCode: number; timedOut?: boolean; idle?: boolean }>; skipped?: string }): string;

package/dist/verify.js

@@ -0,0 +1,123 @@
+// packages/core/src/verify.js
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { AlpError } from "./errors.js";
+import { signalShell, spawnShell } from "./shell.js";
+var VERIFY_STEPS = ["setup", "typecheck", "test"];
+var VERIFY_TIMEOUT_SEC = 600;
+var VERIFY_GRACE_MS = 5e3;
+var VERIFY_INFRA_EXIT = 75;
+var COMMAND_CHARS = 2e3;
+var OUTPUT_CHARS = 4e3;
+var object = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+var fail = (source, message) => {
+  throw new AlpError("INVALID_SETTINGS", `${source}: ${message}`);
+};
+function validateVerify(verify, source) {
+  if (verify === void 0) return void 0;
+  if (!object(verify)) fail(source, "verify must be an object");
+  const extra = Object.keys(verify).filter((key) => ![...VERIFY_STEPS, "timeoutSec", "idleSec"].includes(key));
+  if (extra.length) fail(source, `unsupported verify field '${extra[0]}'; use ${VERIFY_STEPS.join(", ")}, timeoutSec and idleSec`);
+  for (const step of VERIFY_STEPS) {
+    if (verify[step] !== void 0 && (typeof verify[step] !== "string" || !verify[step].trim() || verify[step].length > COMMAND_CHARS)) fail(source, `verify.${step} must be a command of at most ${COMMAND_CHARS} characters`);
+  }
+  if (!VERIFY_STEPS.some((step) => verify[step] !== void 0)) fail(source, `verify needs at least one of ${VERIFY_STEPS.join(", ")}`);
+  if (verify.timeoutSec !== void 0 && (!Number.isSafeInteger(verify.timeoutSec) || verify.timeoutSec < 1 || verify.timeoutSec > 7200)) fail(source, "verify.timeoutSec must be 1 to 7200 seconds");
+  if (verify.idleSec !== void 0 && (!Number.isSafeInteger(verify.idleSec) || verify.idleSec < 1 || verify.idleSec > 7200)) fail(source, "verify.idleSec must be 1 to 7200 seconds");
+  return {
+    ...Object.fromEntries(VERIFY_STEPS.filter((step) => verify[step] !== void 0).map((step) => [step, verify[step].trim()])),
+    timeoutSec: verify.timeoutSec ?? VERIFY_TIMEOUT_SEC,
+    ...verify.idleSec !== void 0 ? { idleSec: verify.idleSec } : {}
+  };
+}
+async function verifyConfig(projectRoot) {
+  const file = path.join(projectRoot, ".alp", "settings.json");
+  let text;
+  try {
+    text = await readFile(file, "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT") return void 0;
+    throw error;
+  }
+  let settings;
+  try {
+    settings = JSON.parse(text);
+  } catch (error) {
+    fail(file, `invalid JSON: ${error.message}`);
+  }
+  return object(settings) ? validateVerify(settings.verify, file) : void 0;
+}
+function runCommand(command, cwd, { timeoutMs, idleMs }, env) {
+  return new Promise((resolve) => {
+    const started = Date.now();
+    const child = spawnShell(command, { cwd, env, stdio: ["ignore", "pipe", "pipe"] });
+    let output = "";
+    let stopped;
+    let idle;
+    const signal = (name) => signalShell(child, name);
+    const stop = (reason) => {
+      if (stopped) return;
+      stopped = reason;
+      signal("SIGTERM");
+      setTimeout(() => signal("SIGKILL"), VERIFY_GRACE_MS).unref();
+    };
+    const quiet = () => {
+      if (!idleMs) return;
+      clearTimeout(idle);
+      idle = setTimeout(() => stop("idle"), idleMs);
+    };
+    const keep = (chunk) => {
+      output = (output + chunk).slice(-OUTPUT_CHARS * 2);
+      quiet();
+    };
+    child.stdout.on("data", keep);
+    child.stderr.on("data", keep);
+    quiet();
+    const timer = setTimeout(() => stop("timeout"), timeoutMs);
+    let done = false;
+    const finish = (exitCode, error) => {
+      if (done) return;
+      done = true;
+      clearTimeout(timer);
+      clearTimeout(idle);
+      const tail = output.length > OUTPUT_CHARS ? `\u2026${output.slice(-OUTPUT_CHARS)}` : output;
+      resolve({
+        exitCode,
+        ms: Date.now() - started,
+        output: error ? `${tail}${error}` : tail,
+        ...stopped === "timeout" ? { timedOut: true } : stopped === "idle" ? { idle: true } : {},
+        ...error ? { spawnError: true } : {}
+      });
+    };
+    child.once("error", (error) => finish(127, error.message));
+    child.once("close", (code, signal2) => finish(stopped ? 124 : code ?? (signal2 ? 128 : 1)));
+  });
+}
+async function runVerify(cwd, config, { env = process.env } = {}) {
+  const commands = [];
+  for (const step of VERIFY_STEPS) {
+    if (!config[step]) continue;
+    const { spawnError, ...result } = await runCommand(config[step], cwd, { timeoutMs: config.timeoutSec * 1e3, idleMs: config.idleSec ? config.idleSec * 1e3 : void 0 }, { ...env, ALP_VERIFY: "1" });
+    commands.push({ step, command: config[step], ...result });
+    if (spawnError || result.exitCode === VERIFY_INFRA_EXIT) {
+      return { passed: false, cwd, commands, skipped: `infra: ${step} could not run (${spawnError ? "the shell did not start" : `exit ${VERIFY_INFRA_EXIT}`})` };
+    }
+    if (result.exitCode !== 0) return { passed: false, cwd, commands };
+  }
+  return { passed: true, cwd, commands };
+}
+function describeVerification(verified) {
+  if (verified.skipped) return `verification skipped: ${verified.skipped}`;
+  const failed = verified.commands.find((command) => command.exitCode !== 0);
+  return verified.passed ? `verified (${verified.commands.map((command) => command.step).join(", ")})` : `verification failed: ${failed.step} ${failed.timedOut ? "timed out" : failed.idle ? "printed nothing for too long" : `exited ${failed.exitCode}`}`;
+}
+export {
+  VERIFY_GRACE_MS,
+  VERIFY_INFRA_EXIT,
+  VERIFY_STEPS,
+  VERIFY_TIMEOUT_SEC,
+  describeVerification,
+  runVerify,
+  validateVerify,
+  verifyConfig
+};

package/dist/workflow.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The team a session runs in (ALPD §42): the one the caller selects, the one a resumed
+ * session ran in, or settings' workflow.mode. Without any, the session is `custom`: its
+ * graph is settings' delegation and no supervisor watches it.
+ * @returns {Promise<{ mode: string, maxPeers: number, supervisor: boolean, team?: Awaited<ReturnType<typeof resolveTeam>> }>}
+ */
+export function resolveWorkflow(root: any, selected: any, restored: any, { library, templates }?: {}): Promise<{
+    mode: string;
+    maxPeers: number;
+    supervisor: boolean;
+    team?: Awaited<ReturnType<typeof resolveTeam>>;
+}>;
+export { teamOf as profileOf } from "./teams.js";
+import { resolveTeam } from './teams.js';

package/dist/workflow.js

@@ -0,0 +1,24 @@
+// packages/core/src/workflow.js
+import path from "node:path";
+import { jsonObject } from "./resolver.js";
+import { applyProfile } from "./profiles.js";
+import { validateSettings } from "./validation.js";
+import { resolveTeam, teamOf } from "./teams.js";
+import { teamOf as teamOf2 } from "./teams.js";
+async function resolveWorkflow(root, selected, restored, { library, templates } = {}) {
+  const settings = await jsonObject(path.join(root, ".alp/settings.json"), "INVALID_SETTINGS");
+  validateSettings(settings, ".alp/settings.json");
+  const chosen = selected === void 0 ? void 0 : teamOf(selected);
+  if (chosen === "custom") throw new Error("Choose a team, such as pho (Ph\u1EDF) or cafe (Cafe)");
+  const mode = chosen ?? teamOf(restored?.mode ?? settings.workflow?.mode ?? "custom");
+  if (restored && mode !== teamOf(restored.mode)) throw new Error("Cannot change team in an existing session");
+  const team = mode === "custom" ? void 0 : applyProfile(await resolveTeam(root, mode, { library, templates }), (settings.team ?? settings.profile)?.[mode]);
+  const maxPeers = restored?.maxPeers ?? settings.workflow?.maxPeers ?? team?.maxPeers ?? 2;
+  if (!Number.isSafeInteger(maxPeers) || maxPeers < 1) throw new Error("workflow.maxPeers must be a positive integer");
+  const supervisor = !!team?.supervisor && (restored?.supervisor ?? settings.workflow?.supervisor ?? true);
+  return { mode, maxPeers, supervisor, ...team ? { team } : {} };
+}
+export {
+  teamOf2 as profileOf,
+  resolveWorkflow
+};