@anhlp/alp-core 0.0.0-stage → 0.10.0

package/README.md

@@ -1,3 +1,7 @@
-# Temporary Holding Version
+# @anhlp/alp-core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Filesystem configuration, agent resolution, teams, tasks, permissions and shipped templates.
+
+Build: `npm run build --workspace=@anhlp/alp-core`. Test: `npm run test --workspace=@anhlp/alp-core`.
+
+Public imports use the package root and its explicitly exported subpaths. See [architecture, provider extension, compatibility and release instructions](../../docs/modular-monorepo.md).

package/dist/adapter.d.ts

@@ -0,0 +1,20 @@
+import type { ResolvedAgent } from './types.js';
+export type CapabilitySupport = 'native' | 'emulated' | 'unsupported';
+export interface AdapterCapabilities {
+  instructions: CapabilitySupport;
+  skills: CapabilitySupport;
+  hooks: CapabilitySupport;
+  mcp: CapabilitySupport;
+}
+export interface CompiledAgent<T = unknown> {
+  adapterId: string;
+  agentName: string;
+  projectRoot: string;
+  material: T;
+}
+export interface AlpRuntimeAdapter<T = unknown> {
+  id: string;
+  capabilities(): AdapterCapabilities;
+  compile(agent: ResolvedAgent): Promise<CompiledAgent<T>>;
+}
+export function compileAgent<T>(adapter: AlpRuntimeAdapter<T>, agent: ResolvedAgent): Promise<CompiledAgent<T>>;

package/dist/adapter.js

@@ -0,0 +1,30 @@
+// packages/core/src/adapter.js
+import { AlpError } from "./errors.js";
+import { validateResolvedAgent } from "./validation.js";
+async function compileAgent(adapter, agent) {
+  if (!adapter || typeof adapter.id !== "string" || !adapter.id.trim() || typeof adapter.capabilities !== "function" || typeof adapter.compile !== "function") {
+    throw new AlpError("INVALID_ADAPTER", "Adapter requires id, capabilities(), and compile()");
+  }
+  validateResolvedAgent(agent);
+  const capabilities = adapter.capabilities();
+  for (const key of ["instructions", "skills", "hooks", "mcp"]) {
+    if (!["native", "emulated", "unsupported"].includes(capabilities?.[key])) throw new AlpError("INVALID_CAPABILITIES", `${adapter.id}: invalid ${key} capability`);
+  }
+  const required = {
+    instructions: Boolean(agent.instructions.project || agent.instructions.agent),
+    skills: agent.skills.length > 0,
+    hooks: agent.hooks.length > 0,
+    mcp: Object.keys(agent.mcp.mcpServers).length > 0
+  };
+  for (const [key, present] of Object.entries(required)) {
+    if (present && capabilities[key] === "unsupported") throw new AlpError("UNSUPPORTED_CAPABILITY", `${adapter.id} does not support ${key} required by '${agent.name}'`);
+  }
+  const compiled = await adapter.compile(structuredClone(agent));
+  if (!compiled || compiled.adapterId !== adapter.id || compiled.agentName !== agent.name || compiled.projectRoot !== agent.projectRoot || !Object.hasOwn(compiled, "material")) {
+    throw new AlpError("INVALID_COMPILED_AGENT", `${adapter.id}: invalid compiled agent envelope`);
+  }
+  return compiled;
+}
+export {
+  compileAgent
+};

package/dist/beads.d.ts

@@ -0,0 +1,65 @@
+/** Tasks as beads issues, sorted by id like bd export. */
+export function exportBeads(tasks: any): {
+    metadata?: {
+        alp: {
+            formula?: any;
+            step?: any;
+            compacted?: any;
+            closed?: any;
+            handoff?: any;
+            gates?: any;
+            paths?: any;
+            status?: string | undefined;
+        };
+    } | undefined;
+    external_ref?: any;
+    source_system?: any;
+    defer_until?: any;
+    closed_at?: any;
+    close_reason?: any;
+    created_at: any;
+    created_by: any;
+    updated_at: any;
+    dependencies?: {
+        issue_id: any;
+        depends_on_id: any;
+        type: any;
+    }[] | undefined;
+    labels?: any;
+    assignee?: any;
+    status: any;
+    priority: any;
+    issue_type: any;
+    description?: any;
+    id: any;
+    title: any;
+}[];
+/** Parses JSONL, keeping the line number of every record or error. */
+export function parseJsonl(text: any): {
+    records: any[];
+    errors: any[];
+};
+/**
+ * Upserts beads issues into the project's tasks, as bd import does: an issue
+ * whose id is an ALP task id, or that ALP imported before (external beads id),
+ * updates that task; any other becomes a new task. Missing records are never deleted.
+ * @returns {Promise<{ created: Array<{ id: string, from: string }>, updated: Array<{ id: string, from: string }>, skipped: Array<{ line: number, reason: string }>, warnings: string[] }>}
+ */
+export function importBeads(projectRoot: any, records: any, { dryRun, by }?: {
+    dryRun?: boolean | undefined;
+    by?: string | undefined;
+}): Promise<{
+    created: Array<{
+        id: string;
+        from: string;
+    }>;
+    updated: Array<{
+        id: string;
+        from: string;
+    }>;
+    skipped: Array<{
+        line: number;
+        reason: string;
+    }>;
+    warnings: string[];
+}>;

package/dist/beads.js

@@ -0,0 +1,213 @@
+// packages/core/src/beads.js
+import { DESCRIPTION_CHARS, MAX_LABELS, TASK_TYPES, batch, isTaskId } from "./tasks.js";
+var DEPENDENCY = { blockedBy: "blocks", parent: "parent-child", discoveredFrom: "discovered-from", related: "related" };
+var RELATION = Object.fromEntries(Object.entries(DEPENDENCY).map(([relation, type]) => [type, relation]));
+var LABEL = /^[\w.:/-]{1,50}$/;
+function exportBeads(tasks) {
+  return [...tasks].sort((a, b) => a.id.localeCompare(b.id)).map((task) => {
+    const dependencies = [
+      ...task.blockedBy.map((id) => [id, "blocks"]),
+      ...task.parent ? [[task.parent, "parent-child"]] : [],
+      ...task.discoveredFrom ? [[task.discoveredFrom, "discovered-from"]] : [],
+      ...task.related.map((id) => [id, "related"])
+    ].map(([dependsOn, type]) => ({ issue_id: task.id, depends_on_id: dependsOn, type }));
+    const timers = task.gates.filter((gate) => gate.kind === "timer" && !gate.resolved).map((gate) => gate.until).sort();
+    const alp = {
+      ...task.status === "review" ? { status: "review" } : {},
+      ...task.paths.length ? { paths: task.paths } : {},
+      ...task.gates.length ? { gates: task.gates } : {},
+      ...task.handoff ? { handoff: task.handoff } : {},
+      ...task.closed ? { closed: task.closed } : {},
+      ...task.compacted ? { compacted: task.compacted } : {},
+      ...task.step ? { step: task.step } : {},
+      ...task.formula ? { formula: task.formula } : {}
+    };
+    return {
+      id: task.id,
+      title: task.title,
+      ...task.description ? { description: task.description } : {},
+      status: task.status === "review" ? "in_progress" : task.status,
+      priority: task.priority,
+      issue_type: task.type,
+      ...task.assignee ? { assignee: task.assignee.agent } : {},
+      ...task.labels.length ? { labels: task.labels } : {},
+      ...dependencies.length ? { dependencies } : {},
+      created_at: task.createdAt,
+      created_by: task.createdBy,
+      updated_at: task.updatedAt,
+      ...task.closed ? { closed_at: task.closed.at, close_reason: task.closed.summary ?? task.closed.reason } : {},
+      ...timers.length ? { defer_until: timers.at(-1) } : {},
+      ...task.external ? { external_ref: task.external.id, source_system: task.external.system } : {},
+      ...Object.keys(alp).length ? { metadata: { alp } } : {}
+    };
+  });
+}
+function parseJsonl(text) {
+  const records = [];
+  const errors = [];
+  text.split("\n").forEach((line, index) => {
+    if (!line.trim()) return;
+    try {
+      const record = JSON.parse(line);
+      if (!record || typeof record !== "object" || Array.isArray(record)) throw new Error("not a JSON object");
+      records.push({ line: index + 1, record });
+    } catch (error) {
+      errors.push({ line: index + 1, reason: error.message });
+    }
+  });
+  return { records, errors };
+}
+var sections = (record) => [
+  typeof record.description === "string" ? record.description : "",
+  ...[["design", "Design"], ["acceptance_criteria", "Acceptance criteria"], ["notes", "Notes"]].filter(([key]) => typeof record[key] === "string" && record[key].trim()).map(([key, title]) => `## ${title}
+
+${record[key].trim()}`)
+].filter(Boolean).join("\n\n");
+function alpOf(record) {
+  let metadata = record.metadata;
+  if (typeof metadata === "string") {
+    try {
+      metadata = JSON.parse(metadata);
+    } catch {
+      return {};
+    }
+  }
+  return metadata?.alp && typeof metadata.alp === "object" && !Array.isArray(metadata.alp) ? metadata.alp : {};
+}
+var clip = (text, limit) => text.length > limit ? `${text.slice(0, limit - 1)}\u2026` : text;
+function taskFields(record) {
+  const type = TASK_TYPES.includes(record.issue_type) ? record.issue_type : "task";
+  const labels = [
+    ...Array.isArray(record.labels) ? record.labels.filter((label) => typeof label === "string" && LABEL.test(label)) : [],
+    ...record.issue_type && type !== record.issue_type && LABEL.test(`beads:${record.issue_type}`) ? [`beads:${record.issue_type}`] : []
+  ];
+  const priority = Number.isInteger(record.priority) ? Math.min(4, Math.max(0, record.priority)) : 2;
+  const alp = alpOf(record);
+  return {
+    title: clip(String(record.title).trim(), 200),
+    description: clip(sections(record), DESCRIPTION_CHARS),
+    type,
+    priority,
+    labels: [...new Set(labels)].slice(0, MAX_LABELS),
+    ...Array.isArray(alp.paths) ? { paths: alp.paths.filter((entry) => typeof entry === "string") } : {}
+  };
+}
+function byParent(entries, parentOf) {
+  const ordered = [];
+  const placed = /* @__PURE__ */ new Set();
+  const visit = (entry, trail = /* @__PURE__ */ new Set()) => {
+    if (placed.has(entry.record.id) || trail.has(entry.record.id)) return;
+    trail.add(entry.record.id);
+    const parent = entries.find((candidate) => candidate.record.id === parentOf(entry.record));
+    if (parent) visit(parent, trail);
+    placed.add(entry.record.id);
+    ordered.push(entry);
+  };
+  for (const entry of entries) visit(entry);
+  return ordered;
+}
+async function importBeads(projectRoot, records, { dryRun = false, by = "user" } = {}) {
+  const report = { created: [], updated: [], skipped: [], warnings: [] };
+  const usable = [];
+  for (const { line, record } of records) {
+    if (record._type !== void 0 && record._type !== "issue") report.skipped.push({ line, reason: `${record._type} record, not an issue` });
+    else if (typeof record.title !== "string" || !record.title.trim()) report.skipped.push({ line, reason: "no title" });
+    else if (typeof record.id !== "string" || !record.id.trim()) report.skipped.push({ line, reason: "no id" });
+    else if (record.status === "tombstone") report.skipped.push({ line, reason: `${record.id} is deleted (tombstone)` });
+    else if (record.ephemeral === true || record.wisp === true) report.skipped.push({ line, reason: `${record.id} is ephemeral` });
+    else usable.push({ line, record });
+  }
+  const dependencies = (record) => (Array.isArray(record.dependencies) ? record.dependencies : []).filter((dep) => dep && typeof dep.depends_on_id === "string" && (dep.issue_id === void 0 || dep.issue_id === record.id));
+  const parentOf = (record) => dependencies(record).find((dep) => dep.type === "parent-child")?.depends_on_id ?? (typeof record.parent === "string" ? record.parent : void 0);
+  return batch(projectRoot, ({ tasks, add, touch, link }) => {
+    const ids = /* @__PURE__ */ new Map();
+    const find = (foreign) => ids.get(foreign) ?? tasks.find((task) => task.id === foreign && isTaskId(foreign))?.id ?? tasks.find((task) => task.external?.system === "beads" && task.external.id === foreign)?.id;
+    for (const { line, record } of byParent(usable, parentOf)) {
+      try {
+        const values = taskFields(record);
+        const alp = alpOf(record);
+        const existing = find(record.id);
+        let task;
+        let before;
+        if (existing) {
+          task = tasks.find((entry) => entry.id === existing);
+          before = JSON.stringify(task);
+          Object.assign(task, values);
+        } else {
+          const parent = parentOf(record) ? find(parentOf(record)) : void 0;
+          if (parentOf(record) && !parent) report.warnings.push(`${record.id}: parent ${parentOf(record)} is not in the file or the project`);
+          task = add({ ...values, ...parent ? { parent } : {} }, by, {
+            id: record.id,
+            createdAt: typeof record.created_at === "string" ? record.created_at : void 0,
+            event: "imported",
+            details: { from: record.id },
+            extra: {
+              ...typeof record.created_by === "string" && record.created_by ? { createdBy: record.created_by } : {},
+              ...Array.isArray(alp.gates) ? { gates: alp.gates } : {},
+              ...alp.step ? { step: alp.step } : {},
+              ...alp.formula ? { formula: alp.formula } : {}
+            }
+          });
+          if (task.id !== record.id) task.external = { system: "beads", id: record.id };
+          report.created.push({ id: task.id, from: record.id });
+        }
+        ids.set(record.id, task.id);
+        applyStatus(task, record, alp, by, report);
+        const deferred = typeof record.defer_until === "string" && Date.parse(record.defer_until) > Date.now() ? new Date(record.defer_until).toISOString() : void 0;
+        if (deferred && !task.gates.some((gate) => gate.kind === "timer" && Math.abs(Date.parse(gate.until) - Date.parse(deferred)) < 1e3)) {
+          const next = Math.max(0, ...task.gates.map((gate) => Number(gate.id.slice(1)) || 0)) + 1;
+          task.gates = [...task.gates, { id: `g${next}`, kind: "timer", until: deferred, at: (/* @__PURE__ */ new Date()).toISOString(), by }];
+        }
+        if (existing && JSON.stringify(task) !== before) {
+          touch(task, by, "imported", { from: record.id });
+          report.updated.push({ id: task.id, from: record.id });
+        }
+      } catch (error) {
+        report.skipped.push({ line, reason: `${record.id}: ${error.message}` });
+      }
+    }
+    for (const { record } of usable) {
+      const id = ids.get(record.id);
+      if (!id) continue;
+      const task = tasks.find((entry) => entry.id === id);
+      for (const dep of dependencies(record)) {
+        const relation = RELATION[dep.type];
+        if (!relation) {
+          report.warnings.push(`${record.id}: dependency type ${dep.type} has no ALP relation; skipped`);
+          continue;
+        }
+        const other = find(dep.depends_on_id);
+        if (!other) {
+          report.warnings.push(`${record.id}: ${dep.type} ${dep.depends_on_id} is not in the file or the project; skipped`);
+          continue;
+        }
+        const before = JSON.stringify(task);
+        const refused = link(task, relation, other);
+        if (refused) report.warnings.push(`${record.id}: ${dep.type} ${dep.depends_on_id} skipped: ${refused}`);
+        else if (JSON.stringify(task) !== before) touch(task);
+      }
+    }
+    return report;
+  }, { dryRun });
+}
+function applyStatus(task, record, alp, by, report) {
+  const status = record.status ?? "open";
+  if (status === "closed") {
+    if (task.status === "closed") return;
+    task.status = "closed";
+    task.assignee = null;
+    task.closed = alp.closed && typeof alp.closed === "object" ? alp.closed : { at: typeof record.closed_at === "string" ? record.closed_at : (/* @__PURE__ */ new Date()).toISOString(), by: "beads", reason: "done", ...typeof record.close_reason === "string" && record.close_reason ? { summary: record.close_reason } : {} };
+  } else if (alp.status === "review" && alp.handoff) {
+    task.status = "review";
+    task.handoff = alp.handoff;
+  } else if (status === "in_progress" && task.status === "open") {
+    report.warnings.push(`${record.id}: was in progress${record.assignee ? ` with ${record.assignee}` : ""} in beads; imported as open`);
+  } else if (!["open", "in_progress", "blocked", "deferred"].includes(status)) {
+    report.warnings.push(`${record.id}: beads status ${status} imported as open`);
+  }
+}
+export {
+  exportBeads,
+  importBeads,
+  parseJsonl
+};

package/dist/delegation.d.ts

@@ -0,0 +1,2 @@
+/** The graph is project data, not a registry or provider-specific role enum. */
+export function resolveDelegation(projectRoot: any): Promise<any>;

package/dist/delegation.js

@@ -0,0 +1,32 @@
+// packages/core/src/delegation.js
+import path from "node:path";
+import { jsonObject } from "./resolver.js";
+import { AlpError } from "./errors.js";
+var name = (value) => typeof value === "string" && value.trim() && ![".", ".."].includes(value) && !/[\\/\x00]/.test(value);
+async function resolveDelegation(projectRoot) {
+  const source = path.join(projectRoot, ".alp", "settings.json");
+  const settings = await jsonObject(source, "INVALID_SETTINGS");
+  const graph = settings.delegation === void 0 ? {} : settings.delegation;
+  const invalid = (message) => {
+    throw new AlpError("INVALID_DELEGATION", `${source}: ${message}`);
+  };
+  if (!graph || typeof graph !== "object" || Array.isArray(graph)) invalid("delegation must map agent names to target arrays");
+  for (const [owner, targets] of Object.entries(graph)) {
+    if (!name(owner) || !Array.isArray(targets) || !targets.every(name) || new Set(targets).size !== targets.length) invalid(`invalid targets for '${owner}'`);
+  }
+  const visiting = /* @__PURE__ */ new Set();
+  const visited = /* @__PURE__ */ new Set();
+  function visit(owner) {
+    if (visiting.has(owner)) invalid(`delegation cycle at '${owner}'`);
+    if (visited.has(owner)) return;
+    visiting.add(owner);
+    for (const target of Object.hasOwn(graph, owner) ? graph[owner] : []) visit(target);
+    visiting.delete(owner);
+    visited.add(owner);
+  }
+  for (const owner of Object.keys(graph)) visit(owner);
+  return graph;
+}
+export {
+  resolveDelegation
+};

package/dist/errors.d.ts

@@ -0,0 +1,4 @@
+export class AlpError extends Error {
+    constructor(code: any, message: any, options: any);
+    code: any;
+}

package/dist/errors.js

@@ -0,0 +1,11 @@
+// packages/core/src/errors.js
+var AlpError = class extends Error {
+  constructor(code, message, options) {
+    super(message, options);
+    this.name = "AlpError";
+    this.code = code;
+  }
+};
+export {
+  AlpError
+};

package/dist/formulas.d.ts

@@ -0,0 +1,25 @@
+import type { Task } from './tasks.js';
+
+export type FormulaStep = { id: string; title: string; description?: string; type: string; needs: string[]; priority?: number; labels?: string[]; paths?: string[] };
+export type Formula = {
+  formula: string;
+  title?: string;
+  description?: string;
+  version?: number;
+  priority?: number;
+  vars: Record<string, { description?: string; required: boolean; default?: string }>;
+  steps: FormulaStep[];
+};
+/** Parses TOML text; the core has none of its own (e.g. smol-toml's parse). */
+export type TomlParser = (text: string) => unknown;
+type Parsers = { toml?: TomlParser };
+export type FormulaEntry = { name: string; file: string; formula?: Formula; error?: string };
+
+export const MAX_STEPS: number;
+export function formulaDirs(projectRoot: string, home?: string): string[];
+export function listFormulas(projectRoot: string, home?: string, parsers?: Parsers): Promise<FormulaEntry[]>;
+export function findFormula(projectRoot: string, home: string | undefined, name: string, parsers?: Parsers): Promise<FormulaEntry & { formula: Formula }>;
+export function loadFormula(file: string, parsers?: Parsers): Promise<Formula>;
+export function validateFormula(data: unknown): Formula;
+export function resolveVars(formula: Formula, given?: Record<string, string>): Record<string, string>;
+export function pourFormula(projectRoot: string, formula: Formula, given: Record<string, string> | undefined, by: string, options?: { dryRun?: boolean; parent?: string }): Promise<{ epic: Task; tasks: Task[] }>;

package/dist/formulas.js

@@ -0,0 +1,201 @@
+// packages/core/src/formulas.js
+import { readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import { AlpError } from "./errors.js";
+import { DESCRIPTION_CHARS, TASK_TYPES, batch } from "./tasks.js";
+var fail = (message) => {
+  throw new AlpError("INVALID_FORMULA", message);
+};
+var NAME = /^[\w.-]{1,64}$/;
+var STEP_ID = /^[\w-]{1,64}$/;
+var VAR = /\{\{\s*([\w-]+)\s*\}\}/g;
+var MAX_STEPS = 50;
+function formulaDirs(projectRoot, home) {
+  return [
+    path.join(path.resolve(projectRoot), ".alp", "formulas"),
+    ...home ? [path.join(home, "formulas")] : [],
+    path.join(path.resolve(projectRoot), ".beads", "formulas")
+  ];
+}
+var FILE = /^(.+)\.formula\.(toml|json)$/;
+async function listFormulas(projectRoot, home, { toml } = {}) {
+  const found = /* @__PURE__ */ new Map();
+  for (const dir of formulaDirs(projectRoot, home)) {
+    let names;
+    try {
+      names = await readdir(dir);
+    } catch (error) {
+      if (error.code === "ENOENT") continue;
+      throw error;
+    }
+    for (const name of names.sort()) {
+      const match = FILE.exec(name);
+      if (!match || found.has(match[1])) continue;
+      const file = path.join(dir, name);
+      try {
+        const formula = await loadFormula(file, { toml });
+        found.set(match[1], { name: match[1], file, formula });
+      } catch (error) {
+        found.set(match[1], { name: match[1], file, error: error.message });
+      }
+    }
+  }
+  return [...found.values()];
+}
+async function findFormula(projectRoot, home, name, { toml } = {}) {
+  if (!NAME.test(name ?? "")) fail("A formula name has letters, digits, dots, dashes and underscores");
+  const entry = (await listFormulas(projectRoot, home, { toml })).find((candidate) => candidate.name === name);
+  if (!entry) fail(`No formula ${name} in ${formulaDirs(projectRoot, home).join(", ")}`);
+  if (entry.error) fail(`${entry.file}: ${entry.error}`);
+  return entry;
+}
+async function loadFormula(file, { toml } = {}) {
+  const text = await readFile(file, "utf8");
+  if (!file.endsWith(".json") && !toml) fail("reading TOML formulas needs a TOML parser");
+  let data;
+  try {
+    data = file.endsWith(".json") ? JSON.parse(text) : toml(text);
+  } catch (error) {
+    fail(`cannot parse: ${error.message.split("\n")[0]}`);
+  }
+  return validateFormula(data);
+}
+var optionalText = (value, name, limit) => {
+  if (value === void 0) return void 0;
+  if (typeof value !== "string" || value.length > limit) fail(`${name} must be text of at most ${limit} characters`);
+  return value;
+};
+function validateFormula(data) {
+  if (!data || typeof data !== "object" || Array.isArray(data)) fail("A formula is an object");
+  if (typeof data.formula !== "string" || !NAME.test(data.formula)) fail("formula must name it: letters, digits, dots, dashes and underscores");
+  const vars = {};
+  if (data.vars !== void 0) {
+    if (!data.vars || typeof data.vars !== "object" || Array.isArray(data.vars)) fail("vars must be a table of variables");
+    for (const [name, spec] of Object.entries(data.vars)) {
+      if (!/^[\w-]{1,64}$/.test(name)) fail(`Variable ${name} has an invalid name`);
+      const value = spec && typeof spec === "object" ? spec : {};
+      vars[name] = {
+        ...typeof value.description === "string" ? { description: value.description } : {},
+        required: value.required === true,
+        ...value.default !== void 0 ? { default: String(value.default) } : {}
+      };
+    }
+  }
+  if (!Array.isArray(data.steps) || !data.steps.length || data.steps.length > MAX_STEPS) fail(`steps must list 1 to ${MAX_STEPS} steps`);
+  const ids = /* @__PURE__ */ new Set();
+  const steps = data.steps.map((step, index) => {
+    if (!step || typeof step !== "object") fail(`Step ${index + 1} is not a table`);
+    if (typeof step.id !== "string" || !STEP_ID.test(step.id)) fail(`Step ${index + 1} needs an id of letters, digits, dashes and underscores`);
+    if (ids.has(step.id)) fail(`Two steps have id ${step.id}`);
+    ids.add(step.id);
+    if (typeof step.title !== "string" || !step.title.trim()) fail(`Step ${step.id} needs a title`);
+    const needs = step.needs === void 0 ? [] : step.needs;
+    if (!Array.isArray(needs) || !needs.every((need) => typeof need === "string")) fail(`Step ${step.id}: needs must list step ids`);
+    if (step.priority !== void 0 && (!Number.isInteger(step.priority) || step.priority < 0 || step.priority > 4)) fail(`Step ${step.id}: priority must be 0 to 4`);
+    return {
+      id: step.id,
+      title: step.title,
+      ...optionalText(step.description, `Step ${step.id} description`, DESCRIPTION_CHARS) ? { description: step.description } : {},
+      type: typeof step.type === "string" ? step.type : "task",
+      needs: [...new Set(needs)],
+      ...step.priority !== void 0 ? { priority: step.priority } : {},
+      ...Array.isArray(step.labels) ? { labels: step.labels.filter((label) => typeof label === "string") } : {},
+      ...Array.isArray(step.paths) ? { paths: step.paths.filter((entry) => typeof entry === "string") } : {}
+    };
+  });
+  for (const step of steps) for (const need of step.needs) if (!ids.has(need)) fail(`Step ${step.id} needs unknown step ${need}`);
+  const state = /* @__PURE__ */ new Map();
+  const visit = (id, trail) => {
+    if (state.get(id) === "done") return;
+    if (state.get(id) === "open") fail(`Steps form a cycle: ${[...trail, id].join(" \u2192 ")}`);
+    state.set(id, "open");
+    for (const need of steps.find((step) => step.id === id).needs) visit(need, [...trail, id]);
+    state.set(id, "done");
+  };
+  for (const step of steps) visit(step.id, []);
+  return {
+    formula: data.formula,
+    ...optionalText(data.title, "title", 200) ? { title: data.title } : {},
+    ...optionalText(data.description, "description", DESCRIPTION_CHARS) ? { description: data.description } : {},
+    ...Number.isInteger(data.version) ? { version: data.version } : {},
+    ...Number.isInteger(data.priority) && data.priority >= 0 && data.priority <= 4 ? { priority: data.priority } : {},
+    vars,
+    steps
+  };
+}
+function resolveVars(formula, given = {}) {
+  const unknown = Object.keys(given).filter((name) => !(name in formula.vars));
+  if (unknown.length) fail(`${formula.formula} has no variable ${unknown.join(", ")}; it takes ${Object.keys(formula.vars).join(", ") || "none"}`);
+  const values = {};
+  for (const [name, spec] of Object.entries(formula.vars)) {
+    const value = given[name] ?? spec.default;
+    if (value === void 0 && spec.required) fail(`${formula.formula} needs --var ${name}=\u2026${spec.description ? ` (${spec.description})` : ""}`);
+    if (value !== void 0) values[name] = String(value);
+  }
+  return values;
+}
+function fill(text, values, where) {
+  return text.replace(VAR, (whole, name) => {
+    if (!(name in values)) fail(`${where} uses {{${name}}}, which has no value`);
+    return values[name];
+  });
+}
+async function pourFormula(projectRoot, formula, given, by, { dryRun = false, parent } = {}) {
+  const values = resolveVars(formula, given);
+  const summary = Object.entries(values).map(([name, value]) => `${name}=${value}`).join(", ");
+  const title = formula.title ? fill(formula.title, values, "title") : `${formula.formula}${summary ? ` (${summary})` : ""}`;
+  const steps = formula.steps.map((step) => ({
+    ...step,
+    title: fill(step.title, values, `Step ${step.id}`),
+    ...step.description ? { description: fill(step.description, values, `Step ${step.id}`) } : {}
+  }));
+  return batch(projectRoot, ({ add, link }) => {
+    const epic = add({
+      title: title.slice(0, 200),
+      type: "epic",
+      priority: formula.priority ?? 2,
+      labels: [`formula:${formula.formula}`.slice(0, 50)],
+      ...formula.description ? { description: fill(formula.description, values, "description") } : {},
+      ...parent ? { parent } : {}
+    }, by, { event: "poured", details: { formula: formula.formula }, extra: { formula: { name: formula.formula, ...formula.version ? { version: formula.version } : {}, vars: values } } });
+    const made = /* @__PURE__ */ new Map();
+    for (const step of steps) {
+      const human = step.type === "human";
+      const type = TASK_TYPES.includes(step.type) && step.type !== "epic" ? step.type : "task";
+      const task = add({
+        title: step.title.slice(0, 200),
+        type,
+        priority: step.priority ?? formula.priority ?? 2,
+        parent: epic.id,
+        ...step.description ? { description: step.description } : {},
+        ...step.labels ? { labels: step.labels } : {},
+        ...step.paths ? { paths: step.paths } : {}
+      }, by, {
+        event: "poured",
+        details: { formula: formula.formula, step: step.id },
+        extra: {
+          step: { formula: formula.formula, id: step.id, ...human ? { human: true } : {} },
+          ...human ? { gates: [{ id: "g1", kind: "human", note: `Your step: ${step.title}`.slice(0, 2e3), at: (/* @__PURE__ */ new Date()).toISOString(), by }] } : {}
+        }
+      });
+      made.set(step.id, task);
+    }
+    for (const step of steps) {
+      for (const need of step.needs) {
+        const refused = link(made.get(step.id), "blockedBy", made.get(need).id);
+        if (refused) fail(`Step ${step.id} cannot need ${need}: ${refused}`);
+      }
+    }
+    return { epic, tasks: [...made.values()] };
+  }, { dryRun });
+}
+export {
+  MAX_STEPS,
+  findFormula,
+  formulaDirs,
+  listFormulas,
+  loadFormula,
+  pourFormula,
+  resolveVars,
+  validateFormula
+};

package/dist/hook-run.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Runs a hook's command once (ALPD §43): through /bin/sh in `cwd`, with the event as JSON
+ * on stdin and `env` added to ALP's environment. It runs in its own process group, so
+ * past its timeout the whole group gets SIGTERM, then SIGKILL two seconds later; a
+ * shell's children do not outlive it. Output beyond 64 KiB per stream is cut.
+ * @param {{ command: string, timeoutSec?: number }} hook
+ * @param {unknown} payload
+ * @param {{ cwd: string, env?: Record<string, string>, timeoutMs?: number }} options
+ * @returns {Promise<{ exitCode: number | null, signal: string | null, timedOut: boolean, stdout: string, stderr: string, durationMs: number }>}
+ */
+export function runHook(hook: {
+    command: string;
+    timeoutSec?: number;
+}, payload: unknown, { cwd, env, timeoutMs }?: {
+    cwd: string;
+    env?: Record<string, string>;
+    timeoutMs?: number;
+}): Promise<{
+    exitCode: number | null;
+    signal: string | null;
+    timedOut: boolean;
+    stdout: string;
+    stderr: string;
+    durationMs: number;
+}>;
+/** A payload like the one ALP sends for an event, for trying a hook out. */
+export function samplePayload(event: any, { project, agent, session, task }?: {
+    agent?: string | undefined;
+    session?: string | undefined;
+}): {
+    branch?: string | undefined;
+    files?: never[] | undefined;
+    task?: any;
+    reason?: string | undefined;
+    handoff?: {
+        outcome: string;
+        summary: string;
+    } | undefined;
+    event: any;
+    sample: boolean;
+    project: any;
+    session: string;
+    agent: string;
+};