blacksmith-organization-system 0.4.2 → 1.0.0-dev.3

package/src/models/workshop/locate.mjs

@@ -0,0 +1,60 @@
+// Finding workshops on the machine: per user (~/__WORKSHOP) and per partition (/media/**/__WORKSHOP).
+import { existsSync, readdirSync } from "node:fs";
+import { basename, dirname, join, relative, resolve, sep } from "node:path";
+
+export const WORKSHOP_DIRNAME = "__WORKSHOP";
+
+export function findAncestorWorkshop(start) {
+  let dir = resolve(start);
+  while (dir !== dirname(dir)) {
+    if (basename(dir) === WORKSHOP_DIRNAME) return dir;
+    dir = dirname(dir);
+  }
+  return null;
+}
+
+// the active workshop: first rule that answers wins
+export function resolveWorkshop({ explicit, variable, cwd, self, home }) {
+  const rules = [
+    ["--workshop option", () => explicit && resolve(explicit)],
+    ["$BOS_WORKSHOP", () => variable && resolve(variable.replace(/^~(?=$|\/)/, home))],
+    ["ancestor of current directory", () => findAncestorWorkshop(cwd)],
+    ["ancestor of BOS installation", () => findAncestorWorkshop(self)],
+    ["default per user", () => join(home, WORKSHOP_DIRNAME)],
+  ];
+  for (const [source, rule] of rules) {
+    const root = rule();
+    if (root) return { root, source };
+  }
+}
+
+export function listWorkshops(home, mediaRoot = "/media", maxDepth = 4) {
+  const found = new Set();
+  if (existsSync(join(home, WORKSHOP_DIRNAME))) found.add(join(home, WORKSHOP_DIRNAME));
+  (function scan(dir, depth) {
+    if (depth > maxDepth) return;
+    let entries = [];
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries.filter((entry) => entry.isDirectory())) {
+      const path = join(dir, entry.name);
+      if (entry.name === WORKSHOP_DIRNAME) found.add(path);
+      else scan(path, depth + 1);
+    }
+  })(mediaRoot, 1);
+  return [...found];
+}
+
+// where a path sits inside a workshop: area, and for forge its scope and project
+export function placeOf(target, workshopRoot) {
+  const rel = relative(workshopRoot, resolve(target));
+  if (rel === "") return { area: null };
+  if (rel.startsWith("..")) return null;
+  const [area, ...rest] = rel.split(sep);
+  if (area === "forge")
+    return { area, scope: rest[0] ?? null, project: rest[1] ?? null, inner: rest.slice(2).join("/") || null };
+  return { area, inner: rest.join("/") || null };
+}

package/src/models/workshop/modes.mjs

@@ -0,0 +1,31 @@
+// Modes of work: what kind of need the workshop serves right now (glossary: mode).
+// The digit is the key in the `bos mode` chooser; 0 leaves it.
+export const MODES = {
+  almanac: {
+    digit: 1,
+    title: "ALMANAC",
+    covers: "emergency protocols: sinking",
+  },
+  conform: {
+    digit: 2,
+    title: "CONFORM",
+    covers: "establishing the workshop, migrations, cleaning, verifying, syncing between fortified workshops",
+  },
+  smeltry: {
+    digit: 3,
+    title: "SMELTRY",
+    covers: "code, development, active editing, publishing changes",
+  },
+  commandorate: {
+    digit: 4,
+    title: "COMMANDORATE",
+    covers: "rulesets, privileges, roles, switching modes",
+  },
+  provision: {
+    digit: 5,
+    title: "PROVISION",
+    covers: "presenting what a source of truth delivers, e.g. a repository on GitHub",
+  },
+};
+
+export const modeByDigit = (digit) => Object.keys(MODES).find((name) => MODES[name].digit === Number(digit)) ?? null;

package/src/models/workshop/taskfile.mjs

@@ -0,0 +1,21 @@
+// .BOS/Taskfile.yaml: the workshop's own procedures, pointing at this BOS installation.
+import { CLI } from "../../core/self.mjs";
+
+export const workshopTaskfile = () => `# yaml-language-server: $schema=https://taskfile.dev/schema.json
+# workshop procedures, generated by BOS bootstrap; edit freely
+version: '3'
+
+vars:
+  BOS: node ${CLI}
+
+tasks:
+  status:
+    desc: show the state of this workshop
+    cmds: ['{{.BOS}} status']
+  open:
+    desc: open the workshop (bootstrap missing areas, record opening)
+    cmds: ['{{.BOS}} open']
+  close:
+    desc: close the workshop (capture ttystory, record closing)
+    cmds: ['{{.BOS}} close']
+`;

package/src/procedures/_index.mjs

@@ -0,0 +1,32 @@
+// Every procedure: steps that close a routed routine. Each lives in its own
+// directory: DESCRIPTION.md (meaning), one file per step, _index.mjs (assembly).
+import bootstrapping from "./bootstrapping/_index.mjs";
+import closing from "./closing/_index.mjs";
+import describing from "./describing/_index.mjs";
+import gathering from "./gathering/_index.mjs";
+import { hooking, installingHooks } from "./hooking/_index.mjs";
+import inspecting from "./inspecting/_index.mjs";
+import loading from "./loading/_index.mjs";
+import locating from "./locating/_index.mjs";
+import modeSwitching from "./mode-switching/_index.mjs";
+import opening from "./opening/_index.mjs";
+import promoting from "./promoting/_index.mjs";
+import sinking from "./sinking/_index.mjs";
+import skilling from "./skilling/_index.mjs";
+
+export default {
+  locating,
+  loading,
+  inspecting,
+  bootstrapping,
+  opening,
+  closing,
+  sinking,
+  hooking,
+  installingHooks,
+  promoting,
+  skilling,
+  modeSwitching,
+  describing,
+  gathering,
+};

package/src/procedures/agent-recording/_index.mjs

@@ -0,0 +1,34 @@
+// An agent's work leaves storylines like a person's: its sessions as events, its shell
+// commands as its own ttystory (ttystory-<host>-claude-<session>.txt, one line per command:
+// unixusat, cwd, command). Storylines hold shell history: treat them like .BOS/setup.
+import { appendFileSync } from "node:fs";
+
+import { situate } from "./situate.mjs";
+
+export async function recordAgentEvent(input, event) {
+  const context = await situate(input);
+  if (!context) return null;
+  const storylines = context.workshop.storylines.ensure(context);
+  return storylines.record(
+    {
+      event,
+      agent: "claude",
+      session: input.session_id ?? null,
+      source: input.source ?? null,
+      model: input.model ?? null,
+      place: context.workshop.placeOf(input.cwd ?? process.cwd()),
+    },
+    context,
+  );
+}
+
+export async function recordAgentCommand(input) {
+  const command = input.tool_input?.command;
+  if (!command) return null;
+  const context = await situate(input);
+  if (!context) return null;
+  const storylines = context.workshop.storylines.ensure(context);
+  const file = storylines.ttystories.file(`ttystory-${context.env.host}-claude-${input.session_id ?? "unknown"}.txt`);
+  appendFileSync(file, `${Date.now()}\t${input.cwd ?? process.cwd()}\t${command.replace(/\n/g, "\\n")}\n`);
+  return file;
+}

package/src/procedures/agent-recording/situate.mjs

@@ -0,0 +1,11 @@
+// Where an agent session happens: locate and load the workshop from the hook's cwd.
+// Returns null when there is no workshop there; hooks never create one.
+import { existsSync } from "node:fs";
+
+import loading from "../loading/_index.mjs";
+
+export async function situate(input) {
+  if (input.cwd && existsSync(input.cwd)) process.chdir(input.cwd);
+  const context = await loading.run({ options: { workshop: process.env.BOS_WORKSHOP } });
+  return context.workshop.exists() ? context : null;
+}

package/src/procedures/bootstrapping/DESCRIPTION.md

@@ -0,0 +1,6 @@
+# Bootstrapping Protocol
+
+Makes the workshop whole: `.BOS/` with setup, data, nests (+ index and
+manifest), `workshop.json` and `Taskfile.yaml`; devarmory (+ manifest), forge,
+craftbook (+ scrapnotes) and archive; `AGENTS.md` and `CLAUDE.md` at the root.
+It creates only what is missing and never overwrites. With `--dry-run` it only plans.

package/src/procedures/bootstrapping/_index.mjs

@@ -0,0 +1,13 @@
+import { BOS } from "../../main.ts";
+import loading from "../loading/_index.mjs";
+import { deployGuides } from "./deploy-guides.mjs";
+import { ensureTree } from "./ensure-tree.mjs";
+
+export const bootstrapSteps = new BOS.Procedure("bootstrapping", [], {
+  description: "create missing areas and descriptors, deploy agent guides",
+})
+  .step("ensure workshop tree", ensureTree)
+  .step("deploy agent guides", deployGuides);
+
+export const bootstrapping = loading.chain(bootstrapSteps, "bootstrapping");
+export default bootstrapping;

package/src/procedures/bootstrapping/deploy-guides.mjs

@@ -0,0 +1,15 @@
+import { copyFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { createIfMissing } from "../../core/basic-element.mjs";
+import { RESOURCES } from "../../core/self.mjs";
+
+export const AGENT_GUIDES = ["AGENTS.md", "CLAUDE.md"];
+
+// the workshop-root guides for AI agents; an existing one is never replaced
+export const deployGuides = (context) => {
+  for (const guide of AGENT_GUIDES) {
+    const target = join(context.workshopRoot, guide);
+    createIfMissing(target, () => copyFileSync(join(RESOURCES, "workshop-root", guide), target), context);
+  }
+};

package/src/procedures/bootstrapping/ensure-tree.mjs

@@ -0,0 +1,4 @@
+// every mandatory area and descriptor; creates only what is missing
+export const ensureTree = (context) => {
+  context.workshop.ensure(context);
+};

package/src/procedures/closing/DESCRIPTION.md

@@ -0,0 +1,6 @@
+# Closing Protocol
+
+related to all models - requires stuff to be open first, it is being done before shutdown
+
+Steps: locating → loading → copy the shell history to
+`.BOS/storylines/ttystories/ttystory-<host>-<unixusat>.txt` → record the closing.

package/src/procedures/closing/_index.mjs

@@ -0,0 +1,11 @@
+import { BOS } from "../../main.ts";
+import loading from "../loading/_index.mjs";
+import { captureTtystory } from "./capture-ttystory.mjs";
+import { recordClosing } from "./record-closing.mjs";
+
+const own = new BOS.Procedure("closing")
+  .step("capture ttystory", captureTtystory)
+  .step("record closing", recordClosing);
+
+export const closing = loading.chain(own, "closing");
+export default closing;

package/src/procedures/closing/capture-ttystory.mjs

@@ -0,0 +1,14 @@
+import { copyFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+
+import { createIfMissing } from "../../core/basic-element.mjs";
+
+// bash writes history on exit: run `history -a` first to include the current shell
+export const captureTtystory = (context) => {
+  const storylines = context.workshop.storylines.ensure(context);
+  const history = process.env.HISTFILE || join(context.env.home, ".bash_history");
+  if (!existsSync(history)) return;
+  const target = storylines.ttystories.file(storylines.ttystoryName(context));
+  createIfMissing(target, () => copyFileSync(history, target), context);
+  context.ttystory = target;
+};

package/src/procedures/closing/record-closing.mjs

@@ -0,0 +1,6 @@
+export const recordClosing = (context) => {
+  context.event = context.workshop.storylines.record(
+    { event: "close", user: context.env.user, ttystory: context.ttystory ?? null },
+    context,
+  );
+};

package/src/procedures/describing/DESCRIPTION.md

@@ -0,0 +1,23 @@
+# Describing Protocol
+
+Part of SMELTRY. A commit should describe its own content. This protocol reads
+the staged changes and drafts a conventional-commit message:
+
+- **type**: `docs`, `test`, `ci` or `build` when only that part changed; `feat`
+  when new source files appear; otherwise `chore`
+- **scope**: the part of the project (`procedures`, `bridge`, `models`, `docs`, …),
+  from `scopes.mjs`
+- **subject**: add / update / remove, plus what the paths are about
+- **body**: every file, marked A / M / D
+
+Then **Skryba**, the scribe raven (`resources/ravens/skryba.md`), reads the
+trimmed staged diff through ollama and proposes a better subject and a short
+body. He answers in a fixed JSON shape, so the header is always a valid
+conventional commit, and the file list stays. When ollama or the model is
+missing, or the answer is unusable, the plain draft is used.
+`BOS_SKRYBA=0` turns him off; `BOS_SKRYBA_MODEL` picks another model.
+
+Husky's `prepare-commit-msg` runs it (`bos describe --hook`), so a plain
+`git commit` opens the editor with the draft. A message given with `-m`, a
+merge, a squash or an amend is never touched. commitlint then checks the
+format, and semantic-release turns the type into the next version.

package/src/procedures/describing/_index.mjs

@@ -0,0 +1,15 @@
+import { BOS } from "../../main.ts";
+import { askSkryba } from "./ask-skryba.mjs";
+import { composeDraft } from "./compose-message.mjs";
+import { readStaged } from "./read-staged.mjs";
+import { writeMessage } from "./write-message.mjs";
+
+export const describing = new BOS.Procedure("describing", [], {
+  description: "draft a conventional commit message from the staged changes",
+})
+  .step("read staged changes", readStaged)
+  .step("compose draft", composeDraft)
+  .step("ask Skryba", askSkryba)
+  .step("write into commit message", writeMessage);
+
+export default describing;

package/src/procedures/describing/ask-skryba.mjs

@@ -0,0 +1,82 @@
+// Skryba, the scribe raven (resources/ravens/skryba.md), rewrites the draft's header
+// and adds a short body. He only proposes: the file list stays, and without ollama,
+// or with a bad answer, the deterministic draft is used as it is.
+import OllamaLink from "../../bridge/ollama-link/_index.mjs";
+import SubprocessRunner from "../../bridge/subprocess-runner/_index.mjs";
+import { stagedDiff } from "./staged-diff.mjs";
+
+export const TYPES = ["feat", "fix", "docs", "style", "refactor", "perf", "test", "build", "ci", "chore", "revert"];
+
+export const ANSWER = {
+  type: "object",
+  properties: {
+    type: { type: "string", enum: TYPES },
+    scope: { type: "string" },
+    subject: { type: "string" },
+    body: { type: "string" },
+  },
+  required: ["type", "scope", "subject", "body"],
+};
+
+// Skryba's answer + the draft → a message; null when the answer can't be trusted
+export function assemble(answer, draft, signature) {
+  let parsed;
+  try {
+    parsed = typeof answer === "string" ? JSON.parse(answer) : answer;
+  } catch {
+    return null;
+  }
+  const subject = String(parsed?.subject ?? "")
+    .trim()
+    .replace(/\.$/, "");
+  if (!TYPES.includes(parsed?.type) || !subject) return null;
+  const scope = String(parsed.scope ?? "")
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9,._-]/g, "");
+  const header = `${parsed.type}${scope ? `(${scope})` : ""}: ${subject}`.slice(0, 100);
+  const body = String(parsed.body ?? "")
+    .trim()
+    .split("\n")
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .join("\n");
+  const files = draft.split("\n\n").slice(1).join("\n\n").trim();
+  return `${[header, body, files, signature].filter(Boolean).join("\n\n")}\n`;
+}
+
+export const askSkryba = async (context) => {
+  const wanted = context.options.skryba ?? process.env.BOS_SKRYBA !== "0";
+  if (!wanted || !context.message) return;
+  const ollama = context.options.ollama ?? new OllamaLink();
+  const raven = ollama.raven("skryba");
+  const model = process.env.BOS_SKRYBA_MODEL ?? raven.model;
+  if (!(await ollama.available(model))) {
+    context.skryba = { used: false, reason: `ollama or model ${model} not available` };
+    return;
+  }
+  const { stat, diff } = stagedDiff(context.repo);
+  const recent = new SubprocessRunner().try("git", ["log", "-8", "--format=%s"], { cwd: context.repo }) ?? "";
+  const [, type, scope] = context.message.match(/^(\w+)(?:\(([^)]*)\))?:/) ?? [];
+  const prompt = [
+    `Hint from the file paths: type "${type}", scope "${scope ?? ""}". Keep them unless the diff clearly shows otherwise.`,
+    "Write the subject about the purpose of the change: what it makes possible or fixes, not which files changed.",
+    "",
+    "Recent commit subjects of this repository (for style):",
+    recent || "(none)",
+    "",
+    "Staged changes, stat:",
+    stat,
+    "",
+    "Staged changes, diff (may be trimmed):",
+    diff,
+  ].join("\n");
+  const answer = await ollama.ask("skryba", prompt, {
+    format: ANSWER,
+    model,
+    timeout: context.options.timeout ?? 90000,
+  });
+  const message = answer && assemble(answer, context.message, `Drafted-by: Skryba (${model} via ollama)`);
+  context.skryba = { used: Boolean(message), model, reason: message ? null : "no usable answer" };
+  if (message) context.message = message;
+};

package/src/procedures/describing/compose-message.mjs

@@ -0,0 +1,25 @@
+// A conventional-commit draft from the staged changes alone: deterministic, no guessing beyond paths.
+import { scopeOf, targetOf } from "./scopes.mjs";
+
+const ONLY = { docs: "docs", tests: "test", ci: "ci", build: "build" };
+const MARK = { added: "A", modified: "M", deleted: "D" };
+
+export function composeMessage(staged) {
+  if (!staged.length) return null;
+  const scopes = [...new Set(staged.map(([path]) => scopeOf(path)))];
+  const states = new Set(staged.map(([, state]) => state));
+  const addsCode = staged.some(([path, state]) => state === "added" && path.startsWith("src/"));
+  const type = scopes.length === 1 && ONLY[scopes[0]] ? ONLY[scopes[0]] : addsCode ? "feat" : "chore";
+  const scope = scopes.length <= 2 ? `(${scopes.join(",")})` : "";
+  const verb = states.size === 1 ? { added: "add", deleted: "remove", modified: "update" }[[...states][0]] : "update";
+  const targets = [...new Set(staged.map(([path]) => targetOf(path)))];
+  const named = targets.slice(0, 3).join(", ") + (targets.length > 3 ? ` +${targets.length - 3} more` : "");
+  const header = `${type}${scope}: ${verb} ${named}`.slice(0, 100);
+  const body = staged.slice(0, 40).map(([path, state]) => `${MARK[state]} ${path}`);
+  if (staged.length > 40) body.push(`… ${staged.length - 40} more files`);
+  return `${header}\n\n${body.join("\n")}\n`;
+}
+
+export const composeDraft = (context) => {
+  context.message = composeMessage(context.staged);
+};

package/src/procedures/describing/read-staged.mjs

@@ -0,0 +1,7 @@
+import GitClient from "../../bridge/git-client/_index.mjs";
+
+export const readStaged = async (context) => {
+  const git = new GitClient();
+  context.repo = (await git.root(context.options.cwd ?? process.cwd())) ?? process.cwd();
+  context.staged = await git.staged(context.repo);
+};

package/src/procedures/describing/scopes.mjs

@@ -0,0 +1,38 @@
+// Which part of the project a path belongs to: the scope of a conventional commit.
+const BUILD = new Set([
+  "package.json",
+  "package-lock.json",
+  "Taskfile.yml",
+  "vitest.config.mjs",
+  "commitlint.config.mjs",
+  "release.config.mjs",
+  "biome.json",
+  "Dockerfile",
+  "compose.yaml",
+  ".dockerignore",
+  "mkdocs.yml",
+  ".readthedocs.yaml",
+  ".gitignore",
+]);
+
+export function scopeOf(path) {
+  const [top, part] = path.split("/");
+  if (top === "src") return ["main.ts", "cli.mjs", "index.mjs"].includes(part) ? "core" : part;
+  if (top === "tests") return "tests";
+  if (top === "docs") return "docs";
+  if (top === ".github") return "ci";
+  if (top === "resources") return "resources";
+  if (["skills", "template", ".claude-plugin"].includes(top)) return "skills";
+  if (top === ".husky" || BUILD.has(path)) return "build";
+  return "repo";
+}
+
+// the thing a path is about: src/procedures/closing/x.mjs → closing; docs/glossary/mode.md → mode
+export function targetOf(path) {
+  const parts = path.split("/");
+  const base = parts.at(-1).replace(/\.[^.]+$/, "");
+  if (parts[0] === "src" && parts.length > 3) return parts[2];
+  return ["_index", "index", "class", "README", "exec", "help"].includes(base) && parts.length > 1
+    ? parts.at(-2)
+    : base;
+}

package/src/procedures/describing/staged-diff.mjs

@@ -0,0 +1,25 @@
+// What Skryba reads: the stat of the staged changes, and a trimmed diff
+// (lock files skipped, each file and the whole capped) so it fits a small model.
+import SubprocessRunner from "../../bridge/subprocess-runner/_index.mjs";
+
+const SKIP = /(^|\/)(package-lock\.json|uv\.lock|yarn\.lock|pnpm-lock\.yaml)$/;
+
+export function stagedDiff(repo, { perFile = 1500, total = 8000 } = {}) {
+  const git = new SubprocessRunner();
+  const stat = git.try("git", ["diff", "--cached", "--stat"], { cwd: repo }) ?? "";
+  const diff = git.try("git", ["diff", "--cached", "-U2", "--no-color"], { cwd: repo }) ?? "";
+  let budget = total;
+  const parts = diff
+    .split(/^(?=diff --git )/m)
+    .filter((part) => {
+      const path = part.match(/^diff --git a\/(\S+)/)?.[1] ?? "";
+      return path && !SKIP.test(path);
+    })
+    .map((part) => {
+      const cut = part.slice(0, Math.max(0, Math.min(perFile, budget)));
+      budget -= cut.length;
+      return cut.length < part.length ? `${cut}\n… (trimmed)\n` : cut;
+    })
+    .filter(Boolean);
+  return { stat, diff: parts.join("") };
+}

package/src/procedures/describing/write-message.mjs

@@ -0,0 +1,15 @@
+import { readFileSync, writeFileSync } from "node:fs";
+
+// prepare-commit-msg: fill the editor only for a plain `git commit`, never over a
+// message given with -m, a merge, a squash or an amend
+const KEEP = new Set(["message", "merge", "squash", "commit"]);
+
+export const writeMessage = (context) => {
+  const { file, source } = context.options;
+  if (!file || !context.message || KEEP.has(source)) return;
+  const current = readFileSync(file, "utf8");
+  if (current.split("\n").some((line) => line.trim() && !line.startsWith("#"))) return;
+  const hint = "# drafted by BOS from the staged changes: edit the type, scope and subject freely\n";
+  if (!context.dryRun) writeFileSync(file, context.message + hint + current);
+  context.written = file;
+};

package/src/procedures/gathering/DESCRIPTION.md

@@ -0,0 +1,13 @@
+# Gathering Protocol
+
+Part of PROVISION. Shows the House of Anubis as it is, along three axes:
+
+- **children**: the adopted, named residents of `resources/house/children/`,
+  with their state (active, resting, frozen) and presence
+- **orders**: groups with a duty, such as RavensArmy (`resources/house/orders/`),
+  with local units (ravens) and remote ones
+- **bloodlines**: every served model grouped by releaser, found by following
+  its `parent_model` back to the root (`resources/house/bloodlines.json`)
+
+Only the list of models is read from ollama; no model is started or prompted,
+so resting residents are never disturbed.

package/src/procedures/gathering/_index.mjs

@@ -0,0 +1,13 @@
+import { BOS } from "../../main.ts";
+import { listServed } from "./list-served.mjs";
+import { mergeResidents } from "./merge-residents.mjs";
+import { readRegistry } from "./read-registry.mjs";
+
+export const gathering = new BOS.Procedure("gathering", [], {
+  description: "the House of Anubis: registry merged with what ollama serves",
+})
+  .step("read the House registry", readRegistry)
+  .step("list served models", listServed)
+  .step("merge residents", mergeResidents);
+
+export default gathering;

package/src/procedures/gathering/list-served.mjs

@@ -0,0 +1,9 @@
+import OllamaLink from "../../bridge/ollama-link/_index.mjs";
+
+// what ollama serves right now (names, architectures, parents); listing starts no model.
+// null when ollama is unreachable
+export const listServed = async (context) => {
+  const ollama = context.options.ollama ?? new OllamaLink();
+  const catalog = await ollama.catalog();
+  context.catalog = catalog.length ? catalog : null;
+};

package/src/procedures/gathering/merge-residents.mjs

@@ -0,0 +1,31 @@
+import { groupOf, sameModel } from "../../models/house/groups.mjs";
+
+// children and orders with presence, bloodline of each served model, and bloodlines grouped by releaser
+export const mergeResidents = (context) => {
+  const catalog = context.catalog ?? [];
+  const served = catalog.map((entry) => entry.name);
+  const present = (model) => (context.catalog ? served.some((name) => sameModel(name, model)) : null);
+  const withPresence = (group) => {
+    const claimed = served
+      .filter((model) => groupOf([group], model) && !group.members.some((m) => m.model && sameModel(m.model, model)))
+      .map((model) => ({ model, kind: "local" }));
+    const members = [...group.members, ...claimed].map((member) => ({
+      ...member,
+      state: member.state ?? group.state,
+      present: member.kind === "remote" ? null : present(member.model),
+      bloodline: member.model && context.catalog ? context.house.bloodlineOf(catalog, member.model) : null,
+    }));
+    return { ...group, members };
+  };
+  context.children = context.children.map(withPresence);
+  context.orders = context.orders.map(withPresence);
+  const lines = {};
+  for (const model of served) {
+    const { releaser } = context.house.bloodlineOf(catalog, model);
+    lines[releaser] ??= [];
+    lines[releaser].push(model);
+  }
+  context.bloodlines = Object.entries(lines)
+    .map(([releaser, models]) => ({ releaser, models }))
+    .sort((a, b) => b.models.length - a.models.length);
+};

package/src/procedures/gathering/read-registry.mjs

@@ -0,0 +1,7 @@
+import House from "../../models/house/class.mjs";
+
+export const readRegistry = (context) => {
+  context.house = new House(context.options.housePath);
+  context.children = context.house.children();
+  context.orders = context.house.orders();
+};

package/src/procedures/hooking/DESCRIPTION.md

@@ -0,0 +1,6 @@
+# Hooking Protocol
+
+Git hooks of any repository inside the workshop report to storylines: the
+commit, branch or merge, and where the repository sits
+(`forge / <scope> / <project>`). `bos hooks install` links a repository's
+`post-commit`, `post-checkout` and `post-merge` to `bos hook <name>`.

package/src/procedures/hooking/_index.mjs

@@ -0,0 +1,12 @@
+import { BOS } from "../../main.ts";
+import loading from "../loading/_index.mjs";
+import locating from "../locating/_index.mjs";
+import { installHooks } from "./install-hooks.mjs";
+import { recordHook } from "./record-hook.mjs";
+
+export const hooking = loading.chain(new BOS.Procedure("hooking").step("record hook", recordHook), "hooking");
+export const installingHooks = locating.chain(
+  new BOS.Procedure("installing-hooks").step("link hooks", installHooks),
+  "installing-hooks",
+);
+export default hooking;

package/src/procedures/hooking/hooks.mjs

@@ -0,0 +1,10 @@
+// what each git hook adds to its storyline entry
+import GitClient from "../../bridge/git-client/_index.mjs";
+
+const git = new GitClient();
+
+export const HOOKS = {
+  "post-commit": async (repo) => ({ commit: (await git.log(repo, 1))[0] ?? null }),
+  "post-checkout": async (repo) => ({ branch: await git.branch(repo) }),
+  "post-merge": async (repo) => ({ head: (await git.log(repo, 1))[0]?.oid ?? null }),
+};