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

package/src/bridge/gitea-api/_index.mjs

@@ -0,0 +1,62 @@
+// The self-hosted Gitea that carries private scope repositories and pre-public drafts.
+// Address: options.url or $GITEA_URL (e.g. http://gitea.lan:3000); token: options.token or $GITEA_TOKEN.
+import { BOS } from "../../main.ts";
+
+export class GiteaApi extends BOS.Bridge {
+  static id = "gitea-api";
+
+  get url() {
+    const url = this.options.url ?? process.env.GITEA_URL;
+    if (!url) throw new Error("Gitea address unknown: set $GITEA_URL");
+    return url.replace(/\/+$/, "");
+  }
+
+  get token() {
+    return this.options.token ?? process.env.GITEA_TOKEN;
+  }
+
+  async request(method, path, body) {
+    const response = await fetch(`${this.url}/api/v1${path}`, {
+      method,
+      headers: {
+        "content-type": "application/json",
+        ...(this.token ? { authorization: `token ${this.token}` } : {}),
+      },
+      body: body && JSON.stringify(body),
+    });
+    if (!response.ok) throw new Error(`gitea ${method} ${path}: ${response.status} ${response.statusText}`);
+    return response.status === 204 ? null : response.json();
+  }
+
+  async available() {
+    try {
+      await this.request("GET", "/version");
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  async me() {
+    return (await this.request("GET", "/user")).login;
+  }
+
+  async repos() {
+    return (await this.request("GET", "/user/repos")).map((r) => ({
+      name: r.full_name,
+      private: r.private,
+      url: r.clone_url,
+    }));
+  }
+
+  // scopes are private by default
+  createRepo(name, { private: isPrivate = true, description = "" } = {}) {
+    return this.request("POST", "/user/repos", { name, private: isPrivate, description, default_branch: "master" });
+  }
+
+  cloneUrl(owner, repo) {
+    return `${this.url}/${owner}/${repo}.git`;
+  }
+}
+
+export default GiteaApi;

package/src/bridge/github-api/_index.mjs

@@ -0,0 +1,45 @@
+// GitHub through octokit. Token: options.token, $GITHUB_TOKEN or $GH_TOKEN.
+import { Octokit } from "octokit";
+
+import { BOS } from "../../main.ts";
+
+export class GithubApi extends BOS.Bridge {
+  static id = "github-api";
+
+  connect() {
+    return new Octokit({ auth: this.options.token ?? process.env.GITHUB_TOKEN ?? process.env.GH_TOKEN });
+  }
+
+  async available() {
+    try {
+      await this.me();
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  async me() {
+    return (await this.client.rest.users.getAuthenticated()).data.login;
+  }
+
+  async repos() {
+    const repos = await this.client.paginate(this.client.rest.repos.listForAuthenticatedUser, { per_page: 100 });
+    return repos.map((r) => ({ name: r.full_name, private: r.private, url: r.clone_url, branch: r.default_branch }));
+  }
+
+  async repo(owner, repo) {
+    return (await this.client.rest.repos.get({ owner, repo })).data;
+  }
+
+  async createRepo(name, { private: isPrivate = false, description = "" } = {}) {
+    return (await this.client.rest.repos.createForAuthenticatedUser({ name, private: isPrivate, description })).data;
+  }
+
+  // releasing → master lands in canon through a pull request
+  async pullRequest({ owner, repo, head, base = "master", title = `${head} → ${base}`, body = "" }) {
+    return (await this.client.rest.pulls.create({ owner, repo, head, base, title, body })).data;
+  }
+}
+
+export default GithubApi;

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

@@ -0,0 +1,19 @@
+// Publishing a package to npm. Dry run unless told otherwise.
+import { BOS } from "../../main.ts";
+import SubprocessRunner from "../subprocess-runner/_index.mjs";
+
+const npm = new SubprocessRunner({ command: "npm" });
+
+export class NpmPublish extends BOS.Bridge {
+  static id = "npm-publish";
+
+  available() {
+    return npm.available();
+  }
+
+  publish(dir, { dryRun = true, tag = "latest" } = {}) {
+    return npm.run("npm", ["publish", "--tag", tag, ...(dryRun ? ["--dry-run"] : [])], { cwd: dir, inherit: true });
+  }
+}
+
+export default NpmPublish;

package/src/bridge/ollama-link/_index.mjs

@@ -0,0 +1,93 @@
+// Local language models through the ollama client (host: options.host, $OLLAMA_HOST
+// or http://127.0.0.1:11434). Ravens (resources/ravens/) speak through it.
+// Before any call the House (resources/house/) is asked: only active residents are called.
+import { Ollama } from "ollama";
+
+import { BOS } from "../../main.ts";
+import House from "../../models/house/class.mjs";
+import { listRavens, readRaven } from "./ravens.mjs";
+
+export class OllamaLink extends BOS.Bridge {
+  static id = "ollama-link";
+
+  connect() {
+    return new Ollama({ host: this.options.host ?? process.env.OLLAMA_HOST ?? "http://127.0.0.1:11434" });
+  }
+
+  // give up after `ms`, abort the request, and answer null instead of throwing
+  async within(ms, work) {
+    let timer;
+    const timeout = new Promise((resolve) => {
+      timer = setTimeout(() => {
+        this.client.abort();
+        resolve(null);
+      }, ms);
+    });
+    try {
+      return await Promise.race([work(), timeout]);
+    } catch {
+      return null;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  // names, architectures and parents of the served models: reading the list starts no model
+  async catalog() {
+    const listed = await this.within(2000, () => this.client.list());
+    return (
+      listed?.models.map((m) => ({
+        name: m.name,
+        family: m.details?.family ?? null,
+        parent: m.details?.parent_model || null,
+      })) ?? []
+    );
+  }
+
+  async models() {
+    return (await this.catalog()).map((entry) => entry.name);
+  }
+
+  get house() {
+    this._house ??= new House();
+    return this._house;
+  }
+
+  async available(model) {
+    if (model && !this.house.mayCall(model)) return false;
+    const models = await this.models();
+    return model ? models.some((name) => name === model || name === `${model}:latest`) : models.length > 0;
+  }
+
+  raven(name) {
+    return readRaven(name);
+  }
+  ravens() {
+    return listRavens();
+  }
+
+  // one question to one raven; `format` is a JSON schema for structured answers
+  // a cold model can take a minute to load; keep_alive keeps it warm for the next calls
+  async ask(ravenName, prompt, { format, timeout = 90000, model, keepAlive = "30m" } = {}) {
+    const raven = this.raven(ravenName);
+    const chosen = model ?? process.env[`BOS_${ravenName.toUpperCase()}_MODEL`] ?? raven.model;
+    const { state, reason } = this.house.stateOf(chosen);
+    if (state !== "active") throw new Error(`${chosen} is ${state} and is not called.${reason ? ` ${reason}` : ""}`);
+    const response = await this.within(timeout, () =>
+      this.client.chat({
+        model: chosen,
+        messages: [
+          { role: "system", content: raven.system },
+          { role: "user", content: prompt },
+        ],
+        format,
+        stream: false,
+        keep_alive: keepAlive,
+        options: { temperature: 0.2 },
+      }),
+    );
+    return response?.message?.content ?? null;
+  }
+}
+
+export default OllamaLink;

package/src/bridge/ollama-link/ravens.mjs

@@ -0,0 +1,29 @@
+// Ravens: AI helpers of the workshop, one markdown file each in resources/ravens/.
+// Frontmatter (model, duty) + the text below it as the raven's system prompt.
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { RESOURCES } from "../../core/self.mjs";
+
+const DIR = join(RESOURCES, "ravens");
+
+export function readRaven(name) {
+  const path = join(DIR, `${name}.md`);
+  if (!existsSync(path)) throw new Error(`no raven "${name}" in resources/ravens/`);
+  const [, head = "", system = ""] = readFileSync(path, "utf8").match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/) ?? [];
+  const meta = Object.fromEntries(
+    head
+      .split("\n")
+      .map((line) => line.match(/^(\w+):\s*(.*)$/))
+      .filter(Boolean)
+      .map(([, k, v]) => [k, v.trim()]),
+  );
+  return { name, ...meta, system: system.trim() };
+}
+
+export const listRavens = () =>
+  existsSync(DIR)
+    ? readdirSync(DIR)
+        .filter((file) => file.endsWith(".md"))
+        .map((file) => readRaven(file.slice(0, -3)))
+    : [];

package/src/bridge/ssh-link/_index.mjs

@@ -0,0 +1,33 @@
+// Other hosts over ssh; aliases come from ~/.ssh/config (glossary: setup).
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+import { BOS } from "../../main.ts";
+import SubprocessRunner from "../subprocess-runner/_index.mjs";
+
+const ssh = new SubprocessRunner({ command: "ssh" });
+
+export class SshLink extends BOS.Bridge {
+  static id = "ssh-link";
+
+  available() {
+    return Promise.resolve(ssh.try("ssh", ["-V"]) !== null);
+  }
+
+  aliases(config = join(homedir(), ".ssh", "config")) {
+    try {
+      return [...readFileSync(config, "utf8").matchAll(/^\s*Host\s+(.+)$/gim)]
+        .flatMap((match) => match[1].split(/\s+/))
+        .filter((alias) => !alias.includes("*"));
+    } catch {
+      return [];
+    }
+  }
+
+  run(host, command) {
+    return ssh.run("ssh", ["-o", "BatchMode=yes", host, command]);
+  }
+}
+
+export default SshLink;

package/src/bridge/subprocess-runner/_index.mjs

@@ -0,0 +1,33 @@
+// Any command-line tool as a bridge: run it, or ask whether it is installed.
+import { execFileSync, spawnSync } from "node:child_process";
+
+import { BOS } from "../../main.ts";
+
+export class SubprocessRunner extends BOS.Bridge {
+  static id = "subprocess-runner";
+
+  async available(command = this.options.command) {
+    if (!command) return false;
+    return spawnSync(command, ["--version"], { stdio: "ignore" }).status === 0;
+  }
+
+  run(command, args = [], { cwd = process.cwd(), inherit = false } = {}) {
+    const output = execFileSync(command, args, {
+      cwd,
+      encoding: "utf8",
+      stdio: inherit ? "inherit" : ["ignore", "pipe", "pipe"],
+    });
+    return typeof output === "string" ? output.trim() : "";
+  }
+
+  // like run, but null instead of throwing
+  try(command, args, options) {
+    try {
+      return this.run(command, args, options);
+    } catch {
+      return null;
+    }
+  }
+}
+
+export default SubprocessRunner;

package/src/cli.mjs

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+// bos <command> [operands] [--json] [--dry-run] [--workshop=PATH]
+import { VERSION } from "./core/self.mjs";
+import { BOS } from "./main.ts";
+
+const args = process.argv.slice(2);
+const flags = Object.fromEntries(
+  args
+    .filter((arg) => arg.startsWith("--"))
+    .map((arg) => {
+      const [key, value = true] = arg.slice(2).split("=");
+      return [key.replace(/-(\w)/g, (_, c) => c.toUpperCase()), value];
+    }),
+);
+const [name = "help", ...operands] = args.filter((arg) => !arg.startsWith("--"));
+
+if (flags.version) {
+  console.log(VERSION);
+  process.exit(0);
+}
+
+try {
+  const bos = await new BOS({ workshop: flags.workshop }).load();
+  const output = await bos.command(name, operands, flags);
+  if (output !== undefined) console.log(typeof output === "string" ? output : JSON.stringify(output, null, 2));
+} catch (error) {
+  console.error(`bos ${name}: ${error.message}${error.procedure ? `\n  in ${error.procedure}` : ""}`);
+  process.exitCode = 1;
+}

package/src/commands/_index.mjs

@@ -0,0 +1,51 @@
+/*
+based on index.json in dirs generate commands
+{
+    "path": "/status", # url path for apis
+    "info": "status information", # shortest explanation
+    "help": ["./help.md", "MD"], # detailed usage with render filetype handling
+    "inline": "./exec.mjs", # when called as oneline command with subcommand to return output to standard output, if it is streamable command then piping of input-output should be also handled there somewhere... it can be splitted to another file but have to be imported later
+    "repl": "./repl.mjs" # interactive cli menu that allows standard input of choice or more advanced nice-looking terminal gui based on universal ascii base
+    "mode": "conform" # mode of work the command serves (almanac, conform, smeltry, commandorate, provision); none: general
+}
+not all of these are required, most minimalistic now is "help" - only show universal help on general error or invoking help
+should list commands and what they does
+*/
+
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+// "./exec.mjs" → a function that imports the module on first call and runs its default export
+const lazy = (dir, file) => async (context) => (await import(pathToFileURL(join(dir, file)))).default(context);
+
+export function loadCommand(dir, name = dir.split("/").pop()) {
+  const index = JSON.parse(readFileSync(join(dir, "index.json"), "utf8"));
+  const [helpFile, helpType = "MD"] = [].concat(index.help ?? []);
+  return {
+    name,
+    path: index.path ?? `/${name}`,
+    info: index.info ?? "",
+    mode: index.mode ?? null, // the mode of work this command serves; null: any mode
+    help: () =>
+      helpFile && existsSync(join(dir, helpFile))
+        ? { text: readFileSync(join(dir, helpFile), "utf8"), type: helpType }
+        : null,
+    inline: index.inline
+      ? lazy(dir, index.inline)
+      : async () => {
+          throw new Error(`${name} has no inline form; see: bos help ${name}`);
+        },
+    repl: index.repl ? lazy(dir, index.repl) : null,
+  };
+}
+
+export async function loadCommands(root = HERE) {
+  return Object.fromEntries(
+    readdirSync(root, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory() && existsSync(join(root, entry.name, "index.json")))
+      .map((entry) => [entry.name, loadCommand(join(root, entry.name), entry.name)]),
+  );
+}

package/src/commands/bootstrap/exec.mjs

@@ -0,0 +1,7 @@
+export default async ({ bos, flags }) =>
+  new bos.views.StatusView().render(
+    await bos.workshop.bootstrap({
+      dryRun: Boolean(flags.dryRun),
+    }),
+    flags.json ? "json" : "text",
+  );

package/src/commands/bootstrap/help.md

@@ -0,0 +1,5 @@
+# bootstrap
+
+`bos bootstrap [--dry-run]` creates every missing area and descriptor of the
+workshop, plus `AGENTS.md` and `CLAUDE.md` at its root. It never overwrites.
+`--dry-run` lists what would be created.

package/src/commands/bootstrap/index.json

@@ -0,0 +1,7 @@
+{
+  "path": "/bootstrap",
+  "info": "create missing areas, descriptors and agent guides",
+  "mode": "conform",
+  "help": ["./help.md", "MD"],
+  "inline": "./exec.mjs"
+}

package/src/commands/close/exec.mjs

@@ -0,0 +1,4 @@
+export default async ({ bos, flags }) => {
+  const context = await bos.workshop.close();
+  return flags.json ? context.event : `closed · ttystory: ${context.ttystory ?? "no shell history found"}`;
+};

package/src/commands/close/help.md

@@ -0,0 +1,5 @@
+# close
+
+`bos close` copies the shell history to
+`.BOS/storylines/ttystories/ttystory-<host>-<unixusat>.txt` and records the
+closing. Run `history -a` first so the current shell is included.

package/src/commands/close/index.json

@@ -0,0 +1,7 @@
+{
+  "path": "/close",
+  "info": "keep shell history as a ttystory, record the closing",
+  "mode": "conform",
+  "help": ["./help.md", "MD"],
+  "inline": "./exec.mjs"
+}

package/src/commands/describe/exec.mjs

@@ -0,0 +1,11 @@
+export default async ({ bos, operands: [file, source], flags }) => {
+  const context = await bos.workshop.describe({
+    ...(flags.hook ? { file, source } : {}),
+    ...(flags.skryba === "0" || flags.plain ? { skryba: false } : {}),
+  });
+  if (flags.hook) {
+    return undefined;
+  }
+  const note = context.skryba && !context.skryba.used ? `\n# Skryba: ${context.skryba.reason}` : "";
+  return (context.message ?? "nothing staged") + note;
+};

package/src/commands/describe/help.md

@@ -0,0 +1,5 @@
+# describe
+
+`bos describe` prints a conventional-commit draft of what is staged.
+`bos describe --hook <file> [source]` is what husky's `prepare-commit-msg`
+calls: it writes the draft into the commit message file of a plain `git commit`.

package/src/commands/describe/index.json

@@ -0,0 +1,7 @@
+{
+  "path": "/describe",
+  "info": "draft a conventional commit message from the staged changes",
+  "mode": "smeltry",
+  "help": ["./help.md", "MD"],
+  "inline": "./exec.mjs"
+}

package/src/commands/help/exec.mjs

@@ -0,0 +1,6 @@
+export default ({ bos, operands: [name], flags }) => {
+  const view = new bos.views.HelpView();
+  const state = { commands: bos.commands, command: name, help: name && bos.commands[name]?.help() };
+  if (name && !bos.commands[name]) throw new Error(`unknown command "${name}"`);
+  return view.render(state, flags.json ? "json" : "text");
+};

package/src/commands/help/help.md

@@ -0,0 +1,3 @@
+# help
+
+`bos help` lists every command. `bos help <command>` shows its help.

package/src/commands/help/index.json

@@ -0,0 +1,6 @@
+{
+  "path": "/help",
+  "info": "list commands, or show the help of one",
+  "help": ["./help.md", "MD"],
+  "inline": "./exec.mjs"
+}

package/src/commands/hook/exec.mjs

@@ -0,0 +1,3 @@
+export default async ({ bos, operands: [name] }) => {
+  await bos.workshop.hook(name);
+};

package/src/commands/hook/help.md

@@ -0,0 +1,4 @@
+# hook
+
+`bos hook <name>` is called by git hooks. It records the event, and the
+repository's place in the workshop, in storylines.

package/src/commands/hook/index.json

@@ -0,0 +1,7 @@
+{
+  "path": "/hook",
+  "info": "(called by git) record a hook in storylines",
+  "mode": "smeltry",
+  "help": ["./help.md", "MD"],
+  "inline": "./exec.mjs"
+}

package/src/commands/hooks/exec.mjs

@@ -0,0 +1,5 @@
+export default async ({ bos, operands: [action] }) => {
+  if (action !== "install") throw new Error("usage: bos hooks install");
+  const context = await bos.workshop.installHooks();
+  return { installed: context.changes, skipped: context.skipped };
+};

package/src/commands/hooks/help.md

@@ -0,0 +1,4 @@
+# hooks
+
+`bos hooks install`, inside a git repository, links its `post-commit`,
+`post-checkout` and `post-merge` hooks to BOS. Existing hooks are left alone.

package/src/commands/hooks/index.json

@@ -0,0 +1,7 @@
+{
+  "path": "/hooks",
+  "info": "link this repository's git hooks to BOS",
+  "mode": "smeltry",
+  "help": ["./help.md", "MD"],
+  "inline": "./exec.mjs"
+}

package/src/commands/house/exec.mjs

@@ -0,0 +1,8 @@
+export default async ({ bos, flags }) =>
+  new bos.views.HouseView().render(
+    {
+      ...(await bos.workshop.gather()),
+      options: { all: Boolean(flags.all) },
+    },
+    flags.json ? "json" : "text",
+  );

package/src/commands/house/help.md

@@ -0,0 +1,8 @@
+# house
+
+`bos house [--all]` shows the House of Anubis: each family of
+`resources/house/families/` with its state (active, resting, frozen), its
+residents, their duties, and whether ollama serves them now. `--all` also
+lists the served models no family claims yet.
+
+Only model names are read from ollama; no resident is started or prompted.

package/src/commands/house/index.json

@@ -0,0 +1,7 @@
+{
+  "path": "/house",
+  "info": "the House of Anubis: families, residents, states, duties",
+  "mode": "provision",
+  "help": ["./help.md", "MD"],
+  "inline": "./exec.mjs"
+}

package/src/commands/locate/exec.mjs

@@ -0,0 +1,2 @@
+export default async ({ bos, flags }) =>
+  new bos.views.StatusView().render(await bos.workshop.locate(), flags.json ? "json" : "text");

package/src/commands/locate/help.md

@@ -0,0 +1,6 @@
+# locate
+
+`bos locate` prints the active workshop and the rule that found it:
+`--workshop`, then `$BOS_WORKSHOP`, the nearest parent `__WORKSHOP`, the
+workshop BOS is installed in, and `~/__WORKSHOP`. Also shows where BOS itself
+sits, e.g. `forge / blacksmith-organization-system / bos-skillset`.

package/src/commands/locate/index.json

@@ -0,0 +1,6 @@
+{
+  "path": "/locate",
+  "info": "active workshop, how it was found, where BOS sits",
+  "help": ["./help.md", "MD"],
+  "inline": "./exec.mjs"
+}

package/src/commands/mode/exec.mjs

@@ -0,0 +1,17 @@
+import { modeByDigit } from "../../models/workshop/modes.mjs";
+
+export default async ({ bos, operands: [asked], flags }) => {
+  const view = new bos.views.ModeView();
+  const format = flags.json ? "json" : "text";
+
+  if (asked === undefined) {
+    const { config } = await bos.workshop.status();
+    const digit = await bos.views.chooseDigit(`${view.menu(config.mode)}choose 0-5: `, 5);
+    if (digit === 0) {
+      return undefined;
+    }
+    asked = modeByDigit(digit);
+  }
+
+  return view.render(await bos.workshop.mode(asked), format);
+};

package/src/commands/mode/help.md

@@ -0,0 +1,14 @@
+# mode
+
+`bos mode <name|digit>` switches the mode of work of this workshop.
+`bos mode` shows the menu and waits for one digit (no Enter needed); `0` leaves it.
+
+| digit | mode | covers |
+| ----- | ---- | ------ |
+| 1 | ALMANAC | emergency protocols: sinking |
+| 2 | CONFORM | establishing the workshop, migrations, cleaning, verifying, syncing between fortified workshops |
+| 3 | SMELTRY | code, development, active editing, publishing changes |
+| 4 | COMMANDORATE | rulesets, privileges, roles, switching modes |
+| 5 | PROVISION | presenting what a source of truth delivers, e.g. a repository on GitHub |
+
+The mode is kept in `.BOS/workshop.json`, and every switch is recorded in storylines.

package/src/commands/mode/index.json

@@ -0,0 +1,8 @@
+{
+  "path": "/mode",
+  "info": "show or switch the mode of work (1-5), or choose it by one digit",
+  "mode": "commandorate",
+  "help": ["./help.md", "MD"],
+  "inline": "./exec.mjs",
+  "repl": "./repl.mjs"
+}

package/src/commands/mode/repl.mjs

@@ -0,0 +1,18 @@
+import { modeByDigit } from "../../models/workshop/modes.mjs";
+
+// inside `bos repl` the prompt owns the input, so the digit is confirmed with Enter
+export default async ({ bos, operands: [asked], io }) => {
+  const view = new bos.views.ModeView();
+
+  if (asked === undefined) {
+    const { config } = await bos.workshop.status();
+    console.log(view.menu(config.mode));
+    const digit = Number((await io.question("choose 0-5: ")).trim()[0]);
+    if (!digit || digit > 5) {
+      return undefined;
+    }
+    asked = modeByDigit(digit);
+  }
+
+  return view.text(await bos.workshop.mode(asked));
+};

package/src/commands/open/exec.mjs

@@ -0,0 +1,5 @@
+export default async ({ bos, flags }) =>
+  new bos.views.StatusView().render(
+    await bos.workshop.open({ dryRun: Boolean(flags.dryRun) }),
+    flags.json ? "json" : "text",
+  );