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

package/skills/bos-workshop/references/bos-codebase.md

@@ -0,0 +1,116 @@
+# BOS codebase map
+
+## New core: this repository (bos-skillset → Sarverott/blacksmith-organization-system)
+
+Node ≥ 22.18, ESM plus `src/main.ts` (run directly via type stripping). Read the
+root `AGENTS.md` first: it has the architecture and the one-concern-per-file rule.
+
+- `src/main.ts`: the spine. `class BOS` holds `BOS.Bridge/Model/Procedure/Controll/View`; `bos.load()` loads the parts; `bos.workshop` is the controller; `bos.command(name)`.
+- `src/bridge/<name>/`: docker-host (dockerode: containers, images, volumes), github-api (octokit), git-client (isomorphic-git), gitea-api, subprocess-runner, docker-publish, npm-publish, ssh-link, bos-instances-link ([`TODO`])
+- `src/models/<element>/class.mjs`: standalone assets (`BOS.Model`); organs hang on their owner as `models/<owner>/hang.<name>.mjs` (`BOS.Submodule`, built from the owner: `workshop.storylines.logs`); shared anatomy in `core/basic-element.mjs`; `models/workshop/locate.mjs` finds workshops
+- `bos skills`: drafts `skills/bos-<type>/SKILL.md` per model from the glossary (procedure `skilling`), never overwrites
+- `src/procedures/<name>/`: DESCRIPTION.md + a step per file: locating, loading, inspecting, bootstrapping, opening, closing, sinking, hooking, promoting
+- `src/commands/<name>/index.json`: `{path, info, help, inline, repl}`; `bos help` lists them
+- storylines log: `.BOS/storylines/logs/workshop.jsonl`; tests: `npm test` (vitest)
+- commits: husky (`.husky/`) → `bos describe --hook` drafts a conventional commit, Skryba (raven, `resources/ravens/skryba.md`, via ollama-link) refines it, commitlint checks it, post-* hooks → storylines; `npm run commit` = commitizen (cz-commitlint)
+- releases: semantic-release (`release.config.mjs`), baseline tag v0.7.0; channels dev (developement), beta (testing), rc (releasing), latest (master); npm + GitHub Packages (@sarverott/…) + ghcr.io
+
+Everything below describes the **old core**.
+
+---
+
+Local clone: `~/__WORKSHOP/forge/blacksmith-organization-system/blacksmith-organization-system`
+Remote: https://github.com/Sarverott/OLD-VERSIONS_blacksmith-organization-system (renamed; the name now belongs to the new core)
+Node.js (CommonJS). Entry: `src/_index.js`. Run: `npm start`.
+
+The owner works in this repo in parallel with agents: new commits, removed
+files and changed remote branches between sessions are normal. Always re-check
+`git status`, `git log --all` and the tree before acting. Don't assume an
+earlier state.
+
+## Branches (as of 2026-09-30)
+
+| Branch | State |
+| ------ | ----- |
+| `developement` | Main dev line. Being cleaned radically by the owner ("massive removal of junk codes from dark past", c7da0df) |
+| `dev/reforge` | The agent's reforge work (4d71a58): the component-submodule layout, booting |
+| `dev/submodule-gits` | `developement` before the reforge (ade23b9): 14 component submodules, not booting |
+| `drafting`, `moderation`, `publishing`, `testing`, `revision`, `releasing` | Workflow branches, created at ade23b9, not used yet |
+| `master` | Old, single-repo version (767aa95). Boots, but builds the workshop inside the repo |
+
+`developement/…` names are impossible while a `developement` branch exists
+(a git ref can't be both a branch and a folder), so sub-branches use `dev/…`.
+
+Commit messages marked `░▒▓BOS.helper.tulu3╚╣Skryba╠╗UNIXUSAT=…` come from an
+automated commit-message helper. Several are garbled noise.
+
+## Layout of `developement` after the clean-up (c7da0df)
+
+Submodules are gone. The component code is flat again in `src/<type>/`:
+
+```
+src/
+├── _index.js runner.js spawner.js includer.js
+├── core/          bos.js (base class + INITIALIZE/SETUP), bos.controller.js,
+│                  bos.command.js, bos.interface.js, helperFunctions.js
+├── controllers/   Config, Models, Commands, Interfaces, Scope, … (*Controll.js)
+├── commands/      <name>/{call.js,index.json,manual.md}
+├── models/        <type>/{class.js,data.json[,README.md]}; archive keeps actions/events/…
+├── factors/       command-factory.js
+├── bridges/       integration stubs (publishers, extensions, integrators)
+└── toolsets/      old shell scripts + dev/_index.js save/test runner
+resources/cli-art/ text-art logos
+docs/              README, devlog, about-*.md, glossary/
+```
+
+Removed in the clean-up: `config/` (main/workshop/startup defaults),
+`src/interfaces/` (cli-repl, http-api, socket-server), `libs/py`, `apps/`,
+`examples/`, `.crovley`, all submodules.
+
+## Boot sequence (design)
+
+1. `_index.js` runs `runner.js` when executed directly, or exports `includer.js` (the library API) when required.
+2. `runner.js` calls `BOS.INITIALIZE(repoRoot)`, `BOS.SETUP()`, `BOS.EXECUTE()` (EXECUTE is empty).
+3. INITIALIZE loads every controller class and calls `loadAll()`: Config → Models → Commands → Interfaces → Scope → Scrapbook → Projects → Bridges → Factors → Sandbox → Publication → Deployment.
+4. Config loads `config/*.json` (copied from `*.default` if missing) into `BOS.CONFIG`.
+5. Models are exposed as `BOS.<Type>` and `BOS.MODELS[type]`.
+6. Scope builds the workshop tree from `BOS.CONFIG.workshop.content` and creates missing areas.
+7. SETUP runs `<workshop>/.SETUP/startup.bos`: one command per line, `<command> <args…>`. The default is `use-interface cli-repl open`.
+8. `cli-repl` is Node's REPL. BOS commands are dot-commands (`.show-status`).
+
+## Current boot state of `developement` (c7da0df): does not start
+
+Leftovers from the reforge still point at the removed layout:
+
+- `core/helperFunctions.js` `componentPath()` returns `src/components/<type>/ITEMS/…`. It should become `src/<type>/…`.
+- `controllers/InterfacesControll.js`, `ModelsControll.js`, `CommandsControll.js` join `"src","components",<type>,"ITEMS"`.
+- `require("blacksmith-organization-system/core/…")` (package self-reference) still works while `package.json` has `exports`. Relative `../core/…` would work again now too.
+- `config/` is gone, but ConfigControll, Scope and SETUP need `main.json` and `workshop.json` (defaults).
+- `src/interfaces/` is gone, but the startup script and InterfacesControll expect it.
+- `commands/new-component` still does `git submodule add … src/components/<name>`.
+
+Workshop root resolution (still in `helperFunctions.findWorkshopRoot`):
+`$BOS_WORKSHOP` → nearest ancestor `__WORKSHOP` → `~/__WORKSHOP`.
+Test safely with `BOS_WORKSHOP=/tmp/x/__WORKSHOP npm start`. Without it,
+running from inside `~/__WORKSHOP` uses the real workshop.
+
+## Commands (src/commands)
+
+| Command | Does |
+| ------- | ---- |
+| `show-status [workshop\|workshops\|forge\|archive\|interfaces\|tree]` | readable status |
+| `deploy-workshop` | create missing areas, write `bos-workshop.log` (port of deploy-new-workshop.sh) |
+| `new-scope <name>` | `forge/<name>` + `git init` (port of new-superproject.sh; the old one made a bare `<name>.git`) |
+| `pull-archive` | clone or fetch the repos in `.DATA/*.gitlist` into `archive/<pack>/` (port of archive_mirrors.sh) |
+| `new-component <name>` | `gh repo create bos.<name>` from template + submodule (outdated since submodules were removed) |
+| `exit` | closes the REPL |
+| `use-interface <name> open` | starts an interface |
+| `create-item`, `load-workshop` | empty stubs |
+
+## Historic defects fixed in `dev/reforge`
+
+- master built the workshop inside the repo (`BOS.PathTo(context-path)`) but wrote the startup script to `~/__WORKSHOP/setup`.
+- SETUP copied the startup file without creating its directory (ENOENT on a fresh run).
+- A stub `exit` command overrode the REPL's built-in `.exit`.
+- CLI command arguments arrived as one unsplit string.
+- A recursive `fs.watch` on every model; every file change dumped whole objects to the console.

package/skills/bos-workshop/references/bos-concept.md

@@ -0,0 +1,121 @@
+# What BOS is
+
+**Blacksmith Organization System (BOS)** by Sett Sarverott (2019–), MIT license.
+Part of the R-tier superproject "ANUBIS". Repositories:
+
+- old core: https://github.com/Sarverott/OLD-VERSIONS_blacksmith-organization-system (local: `forge/blacksmith-organization-system/blacksmith-organization-system`)
+- root of the new BOS (this skillset): https://github.com/Sarverott/blacksmith-organization-system (local: `forge/blacksmith-organization-system/bos-skillset`)
+
+The goal is to automate the management of a personal "forest of projects"
+across many machines, servers and publication targets, without version drift
+("variantogeddon"). The author's rule: *"if it is good thinking then it will be
+automated"*.
+
+**Authoritative definitions:** `docs/glossary/<element>.md` in this repository
+(bos-skillset), one page per element, index in `docs/glossary/README.md`.
+Expressed as code in `src/models/<element>/class.mjs`. The old core repo holds an older copy. This file is a
+summary; if the two disagree, the glossary wins. The author annotates the
+glossary directly: read their changes (`git diff`) before summarizing.
+
+## The skeleton: three layers
+
+### 1. Network
+
+- **Setternet (snet):** the owner's network of BOS hosts. Setup lives in `.BOS/setup/setternet/`.
+- **Host roles** (PL originals): master's outpost (Posterunek Mistrza: remote
+  management), forging point (Punkt Kuźniczy: development), trial hall (Sala
+  Prób: VMs, testing), market stall (Kram Targowy: publication only), canon
+  monolith (Monolit Kanonu: the master archive; exactly one per setternet),
+  side catacomb (Katakumb Poboczny: single-purpose archive, e.g. Ollama or deployments).
+- **Canon:** the complete, authoritative record, held by the canon monolith, and
+  in git by the `canonical` branch, which the Canon Keeper confirms.
+
+### 2. Workshop: one per host or partition
+
+```
+__WORKSHOP/
+├── .BOS/          internal, mandatory: workshop.json Taskfile.yaml .omnis.toml package.json Dockerfile compose.yaml
+│   ├── setup/     keys, VPN, routing, DNS/SSH aliases, tokens, setternet/   (mandatory)
+│   ├── data/      e.g. <pack>.gitlist
+│   ├── nests/     container/VM volumes; always .index.json + .manifest.json (mandatory)
+│   └── storylines/ ttystories/ logs/ manifests/ metadata.json            (created during use)
+├── devarmory/     tools: manifest-listed, auto-downloaded, checksum-verified, linked to PATH/desktop
+├── forge/         active work (the desk): <scope>/<project|sheme>, throwbox; defines the working branch
+├── craftbook/     knowledge: scrapnotes/, craftsets, collections, recipes
+└── archive/       at rest: sarcophags, exhibits, <pack>/<mirror>
+```
+
+The four crafting areas and `.BOS/` must always exist; BOS creates them at
+boot. Older layouts had `.SETUP`, `.DATA`, `.NESTRELM`, `.STORYLINES` and
+`.__BOS` as separate top-level dirs, `~/.__WORKSHOP` as the root, and `notes/`
+or scrapbook instead of craftbook.
+
+Views (dashboards over CLI, web, mobile, Chrome extension, Electron, OpenAPI,
+MCP, with one shared handler class) has no settled location yet.
+
+### Modes of work (`.BOS/workshop.json` → "mode"; `bos mode`)
+
+1 ALMANAC: emergency (sinking) · 2 CONFORM: establish, migrate, clean, verify,
+sync workshops · 3 SMELTRY: code, development, publishing changes ·
+4 COMMANDORATE: rules, privileges, roles, mode switching · 5 PROVISION:
+presenting what a source of truth (e.g. GitHub) delivers. Defaults for a new
+workshop: role `forging-point`, mode `conform` (`resources/workshop.default.json`;
+null = not set → default). Commands declare
+their mode in `index.json`; `bos help` groups them. Glossary: mode.md.
+
+### 3. Elements
+
+- **scope** (formerly superproject): a private repository with submodules,
+  holding a family of projects and shemes plus a throwbox. Synced through a
+  self-hosted server (e.g. Gitea) that also keeps pre-public drafts.
+- **project:** one concrete project repository.
+- **sheme:** source material that isn't code: graphics/GIMP, Blender/CAD, photos,
+  templates, third-party reference docs. A design template is a sheme; the code
+  realizing it is a project. (The old scrapnote used sheme for processing
+  routes: HF uploaders, publish and deploy routines. Unresolved.)
+- **throwbox:** automated collector of loose files per scope; swept on close into an anonymous sarcophag.
+- **sarcophag:** encrypted container holding one bare repository (archive).
+- **exhibit:** view built from sarcophags (archive). [`TODO`]
+- **scrapnote:** any note not yet promoted to a document; changelogs and release notes stay scrapnotes.
+- **craftset:** reusable kit of notes, notebooks, one-off scripts and session
+  setup; mandatory `.omnis.toml`, `metadata.json`, `manifest.json`, `Taskfile.yaml`.
+- **collection**, **postroad:** meaning unresolved.
+
+**Element anatomy** (pattern awaiting confirmation): a directory plus descriptor
+files: `metadata.json` (identity/origin), `manifest.json` (checksums/integrity),
+`.index.json` (map), `Taskfile.yaml` (procedures), `.omnis.toml` ([`TODO`]).
+
+## Lifecycles
+
+- work: forge → archive (sarcophag) → canon monolith
+- loose files: throwbox → anonymous sarcophag → sorted, reused or deleted
+- notes: scrapnote → document (or stays a scrapnote)
+- tools: manifest → download → verify checksum → link
+
+## Storylines naming
+
+`ttystory.txt`, `ttystory-$UNIXUSAT.txt`, `ttystory-$HOSTNAME-$UNIXUSAT.txt`.
+`UNIXUSAT` = Unix timestamp in milliseconds. The purpose is to reuse command
+patterns and to teach AI to use the shell the BOS way.
+
+## Ideas on record
+
+Autocommit on save; GIMP history bound to VCS (a branch per session, a commit
+per action); releases trigger social media posts; Taskfile + Husky + a standard
+command set; history proven via OpenTimestamps.
+
+## Branches and versioning
+
+Every repository (docs/infographics/branch-movement-procedures.md): `master`
+(spine of canon) → `developement` (here we code) → `revision` (approval) →
+`testing` (QA, nightly builds) → `releasing` (stamp, publish, announce) →
+`master` via pull request. Rejections go back to `developement`.
+The old core repo additionally has `drafting`, `moderation`, `publishing` and
+`dev/<topic>`; their place in the flow: [`TODO`]
+
+Versioning is `{G}.{R}.{I}.{H}`: Generation, Reconstruction, Integration, Hooking.
+
+## Related repositories
+
+Apps: bos-desktop, bos-mobile, bos-server, bos-gui, bos-vscode-extension.
+Components: `Sarverott/bos.<component>`. Library: carnival-toolbox.

package/skills/bos-workshop/scripts/find-workshop.sh

@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+# Locate BOS workshops. First line: active workshop root.
+# Remaining lines: all other workshops found (home + /media partitions).
+set -euo pipefail
+
+active=""
+
+if [[ -n "${BOS_WORKSHOP:-}" && -d "$BOS_WORKSHOP" ]]; then
+  active="$BOS_WORKSHOP"
+else
+  dir="$PWD"
+  while [[ "$dir" != "/" ]]; do
+    if [[ "$(basename "$dir")" == "__WORKSHOP" ]]; then
+      active="$dir"
+      break
+    fi
+    dir="$(dirname "$dir")"
+  done
+fi
+
+if [[ -z "$active" && -d "$HOME/__WORKSHOP" ]]; then
+  active="$HOME/__WORKSHOP"
+fi
+
+[[ -n "$active" ]] && echo "$active"
+
+{
+  [[ -d "$HOME/__WORKSHOP" ]] && echo "$HOME/__WORKSHOP"
+  [[ -d /media ]] && find /media -maxdepth 4 -type d -name __WORKSHOP 2>/dev/null
+} | sort -u | grep -vxF "${active:-/nonexistent}" || true

package/src/agent-hook.mjs

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+// Claude Code hooks → BOS (hooks/hooks.json). Reads the hook's JSON from stdin.
+//   session-start  prints a short brief (becomes the agent's context) and records the session
+//   bash           appends the agent's shell command to its ttystory in storylines
+//   session-end    records the end of the session
+// Loads no bridges, so it stays fast; never fails the agent (always exits 0).
+import { brief, recordAgentCommand, recordAgentEvent } from "./views/agent/_index.mjs";
+
+const event = process.argv[2];
+let input = {};
+try {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  input = JSON.parse(Buffer.concat(chunks).toString("utf8") || "{}");
+} catch {}
+
+try {
+  if (event === "session-start") {
+    const text = await brief(input);
+    if (text) process.stdout.write(text);
+    await recordAgentEvent(input, "agent-session-start");
+  } else if (event === "bash") {
+    await recordAgentCommand(input);
+  } else if (event === "session-end") {
+    await recordAgentEvent(input, "agent-session-end");
+  }
+} catch {}
+process.exit(0);

package/src/bridge/_index.mjs

@@ -0,0 +1,24 @@
+// Every bridge, by name. Each one shapes an outside system into plain methods.
+import BosInstancesLink from "./bos-instances-link/_index.mjs";
+import DockerHost from "./docker-host/_index.mjs";
+import DockerPublish from "./docker-publish/_index.mjs";
+import GitClient from "./git-client/_index.mjs";
+import GiteaApi from "./gitea-api/_index.mjs";
+import GithubApi from "./github-api/_index.mjs";
+import NpmPublish from "./npm-publish/_index.mjs";
+import OllamaLink from "./ollama-link/_index.mjs";
+import SshLink from "./ssh-link/_index.mjs";
+import SubprocessRunner from "./subprocess-runner/_index.mjs";
+
+export default {
+  subprocessRunner: SubprocessRunner,
+  dockerHost: DockerHost,
+  dockerPublish: DockerPublish,
+  gitClient: GitClient,
+  giteaApi: GiteaApi,
+  githubApi: GithubApi,
+  npmPublish: NpmPublish,
+  ollamaLink: OllamaLink,
+  sshLink: SshLink,
+  BOSLINK: BosInstancesLink,
+};

package/src/bridge/bos-instances-link/_index.mjs

@@ -0,0 +1,18 @@
+// Links between BOS instances of one setternet (glossary: setternet, host-role).
+// [TODO] transport and protocol are not decided yet; this names the handler.
+import { BOS } from "../../main.ts";
+
+export class BosInstancesLink extends BOS.Bridge {
+  static id = "bos-instances-link";
+
+  async available() {
+    return false;
+  }
+
+  // hosts known to this workshop, from .BOS/setup/setternet/ [TODO] format
+  hosts() {
+    return [];
+  }
+}
+
+export default BosInstancesLink;

package/src/bridge/docker-host/_index.mjs

@@ -0,0 +1,43 @@
+// The docker host (local socket or $DOCKER_HOST) through dockerode.
+//   const docker = new DockerHost();  await docker.containers.list()
+import Docker from "dockerode";
+
+import { BOS } from "../../main.ts";
+import * as container from "./container.mjs";
+import * as image from "./image.mjs";
+import * as volume from "./volume.mjs";
+
+// bind every helper to this host's client: containers.run(image, …)
+const bound = (bridge, helpers) =>
+  Object.fromEntries(
+    Object.entries(helpers).map(([name, helper]) => [name, (...args) => helper(bridge.client, ...args)]),
+  );
+
+export class DockerHost extends BOS.Bridge {
+  static id = "docker-host";
+
+  connect() {
+    return new Docker(this.options); // no options: $DOCKER_HOST or /var/run/docker.sock
+  }
+
+  async available() {
+    try {
+      await this.client.ping();
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  get containers() {
+    return bound(this, container);
+  }
+  get images() {
+    return bound(this, image);
+  }
+  get volumes() {
+    return bound(this, volume);
+  }
+}
+
+export default DockerHost;

package/src/bridge/docker-host/container.mjs

@@ -0,0 +1,32 @@
+// Containers of a docker host (dockerode client in, plain data out).
+
+export const list = async (docker, { all = true } = {}) =>
+  (await docker.listContainers({ all })).map((c) => ({
+    id: c.Id.slice(0, 12),
+    name: c.Names[0]?.replace(/^\//, ""),
+    image: c.Image,
+    state: c.State,
+    status: c.Status,
+  }));
+
+export async function run(docker, image, { name, cmd, env = {}, binds = [], labels = {} } = {}) {
+  const container = await docker.createContainer({
+    Image: image,
+    name,
+    Cmd: cmd,
+    Env: Object.entries(env).map(([key, value]) => `${key}=${value}`),
+    Labels: { "bos.managed": "true", ...labels },
+    HostConfig: { Binds: binds },
+  });
+  await container.start();
+  return container.id;
+}
+
+export const start = (docker, id) => docker.getContainer(id).start();
+export const stop = (docker, id) => docker.getContainer(id).stop();
+export const remove = (docker, id, { force = false } = {}) => docker.getContainer(id).remove({ force });
+
+export async function logs(docker, id, { tail = 100 } = {}) {
+  const buffer = await docker.getContainer(id).logs({ stdout: true, stderr: true, tail });
+  return buffer.toString("utf8");
+}

package/src/bridge/docker-host/image.mjs

@@ -0,0 +1,23 @@
+// Images of a docker host.
+
+export const list = async (docker) =>
+  (await docker.listImages()).map((i) => ({
+    id: i.Id.replace(/^sha256:/, "").slice(0, 12),
+    tags: i.RepoTags ?? [],
+    size: i.Size,
+  }));
+
+// resolve when every layer is pulled / pushed
+const follow = (docker, stream) =>
+  new Promise((resolve, reject) =>
+    docker.modem.followProgress(stream, (error, output) => (error ? reject(error) : resolve(output))),
+  );
+
+export const pull = async (docker, name) => follow(docker, await docker.pull(name));
+
+export const tag = (docker, name, repo, tagName = "latest") => docker.getImage(name).tag({ repo, tag: tagName });
+
+export const push = async (docker, name, auth) =>
+  follow(docker, await docker.getImage(name).push({ authconfig: auth }));
+
+export const remove = (docker, name, { force = false } = {}) => docker.getImage(name).remove({ force });

package/src/bridge/docker-host/volume.mjs

@@ -0,0 +1,12 @@
+// Volumes of a docker host. BOS nests (glossary: nestrelm) are volumes labeled bos.nest.
+
+export const list = async (docker, { nestsOnly = false } = {}) => {
+  const { Volumes = [] } = await docker.listVolumes(nestsOnly ? { filters: { label: ["bos.nest"] } } : {});
+  return Volumes.map((v) => ({ name: v.Name, driver: v.Driver, mountpoint: v.Mountpoint, labels: v.Labels ?? {} }));
+};
+
+export const create = (docker, name, { nest = true, labels = {} } = {}) =>
+  docker.createVolume({ Name: name, Labels: { ...(nest ? { "bos.nest": name } : {}), ...labels } });
+
+export const inspect = (docker, name) => docker.getVolume(name).inspect();
+export const remove = (docker, name) => docker.getVolume(name).remove();

package/src/bridge/docker-publish/_index.mjs

@@ -0,0 +1,24 @@
+// Publishing an image: tag it for a registry and push it, over the docker host.
+import { BOS } from "../../main.ts";
+import DockerHost from "../docker-host/_index.mjs";
+
+export class DockerPublish extends BOS.Bridge {
+  static id = "docker-publish";
+
+  get host() {
+    this._host ??= new DockerHost(this.options.docker);
+    return this._host;
+  }
+
+  available() {
+    return this.host.available();
+  }
+
+  // publish("bos:local", "ghcr.io/sarverott/bos", "0.0.1")
+  async publish(localImage, repo, tag = "latest", auth = this.options.auth) {
+    await this.host.images.tag(localImage, repo, tag);
+    return this.host.images.push(`${repo}:${tag}`, auth);
+  }
+}
+
+export default DockerPublish;

package/src/bridge/git-client/_index.mjs

@@ -0,0 +1,121 @@
+// Local repositories through isomorphic-git (no git binary needed); remotes over
+// http(s), e.g. the internal Gitea. Every method takes the repository dir first.
+import fs from "node:fs";
+
+import git from "isomorphic-git";
+import http from "isomorphic-git/http/node";
+
+import { BOS } from "../../main.ts";
+import { resolveAuthor } from "./author.mjs";
+
+export class GitClient extends BOS.Bridge {
+  static id = "git-client";
+
+  // credentials for remotes: options.token / $GITEA_TOKEN (username optional)
+  get auth() {
+    const password = this.options.token ?? process.env.GITEA_TOKEN;
+    return password ? () => ({ username: this.options.username ?? "bos", password }) : undefined;
+  }
+
+  root(path) {
+    return git.findRoot({ fs, filepath: path }).catch(() => null);
+  }
+  init(dir) {
+    return git.init({ fs, dir, defaultBranch: "master" });
+  }
+  branch(dir) {
+    return git.currentBranch({ fs, dir });
+  }
+  branches(dir) {
+    return git.listBranches({ fs, dir });
+  }
+  hasBranch(dir, ref) {
+    return this.branches(dir).then((all) => all.includes(ref));
+  }
+  createBranch(dir, ref, from) {
+    return git.branch({ fs, dir, ref, object: from });
+  }
+  checkout(dir, ref) {
+    return git.checkout({ fs, dir, ref });
+  }
+
+  async log(dir, depth = 10) {
+    return (await git.log({ fs, dir, depth })).map(({ oid, commit }) => ({
+      oid,
+      message: commit.message.trim(),
+      author: commit.author.name,
+      at: commit.author.timestamp * 1000,
+    }));
+  }
+
+  // changed files only: [path, "modified" | "added" | "deleted" | "untracked"]
+  async changes(dir) {
+    const names = {
+      "0,2,0": "untracked",
+      "0,2,2": "added",
+      "1,2,1": "modified",
+      "1,2,2": "modified",
+      "1,0,1": "deleted",
+      "1,0,0": "deleted",
+      "1,1,0": "deleted",
+    };
+    return (await git.statusMatrix({ fs, dir }))
+      .filter(([, head, work, stage]) => !(head === 1 && work === 1 && stage === 1))
+      .map(([path, ...state]) => [path, names[state.join(",")] ?? state.join(",")]);
+  }
+
+  // what the next commit will contain: [path, "added" | "modified" | "deleted"]
+  async staged(dir) {
+    const status = (head, stage) =>
+      head === 0 && stage > 0
+        ? "added"
+        : head === 1 && stage === 0
+          ? "deleted"
+          : head === 1 && stage > 1
+            ? "modified"
+            : null;
+    return (await git.statusMatrix({ fs, dir }))
+      .map(([path, head, , stage]) => [path, status(head, stage)])
+      .filter(([, state]) => state);
+  }
+
+  hooksPath(dir) {
+    return git.getConfig({ fs, dir, path: "core.hooksPath" });
+  }
+
+  async commit(dir, message, paths = ["."]) {
+    for (const filepath of paths) await git.add({ fs, dir, filepath });
+    return git.commit({ fs, dir, message, author: await resolveAuthor(git, fs, dir) });
+  }
+
+  // merge `from` into `to` as a merge commit, then leave `to` checked out
+  async merge(dir, from, to, message = `${from} → ${to}`) {
+    await this.checkout(dir, to);
+    const result = await git.merge({
+      fs,
+      dir,
+      ours: to,
+      theirs: from,
+      fastForward: false,
+      message,
+      author: await resolveAuthor(git, fs, dir),
+    });
+    await this.checkout(dir, to);
+    return result;
+  }
+
+  addRemote(dir, remote, url) {
+    return git.addRemote({ fs, dir, remote, url });
+  }
+  clone(url, dir, { ref, depth } = {}) {
+    return git.clone({ fs, http, dir, url, ref, depth, singleBranch: Boolean(ref), onAuth: this.auth });
+  }
+  fetch(dir, remote = "origin") {
+    return git.fetch({ fs, http, dir, remote, onAuth: this.auth });
+  }
+  push(dir, ref, remote = "origin") {
+    return git.push({ fs, http, dir, remote, ref, onAuth: this.auth });
+  }
+}
+
+export default GitClient;

package/src/bridge/git-client/author.mjs

@@ -0,0 +1,26 @@
+// Who signs commits: repository config, then ~/.gitconfig, then the system user.
+// (isomorphic-git reads only the repository's own config.)
+import { readFileSync } from "node:fs";
+import { homedir, userInfo } from "node:os";
+import { join } from "node:path";
+
+function globalConfig() {
+  try {
+    const text = readFileSync(join(homedir(), ".gitconfig"), "utf8");
+    const user = text.split(/^\[/m).find((section) => section.startsWith("user]")) ?? "";
+    const value = (key) => user.match(new RegExp(`^\\s*${key}\\s*=\\s*(.+)$`, "m"))?.[1].trim();
+    return { name: value("name"), email: value("email") };
+  } catch {
+    return {};
+  }
+}
+
+export async function resolveAuthor(git, fs, dir) {
+  const local = {
+    name: await git.getConfig({ fs, dir, path: "user.name" }),
+    email: await git.getConfig({ fs, dir, path: "user.email" }),
+  };
+  const global = globalConfig();
+  const name = local.name ?? global.name ?? userInfo().username;
+  return { name, email: local.email ?? global.email ?? `${name}@localhost` };
+}