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

package/src/commands/open/help.md

@@ -0,0 +1,4 @@
+# open
+
+`bos open [--dry-run]` runs bootstrap, then records the opening in
+`.BOS/storylines/logs/workshop.jsonl`.

package/src/commands/open/index.json

@@ -0,0 +1,7 @@
+{
+  "path": "/open",
+  "info": "bootstrap, then record the opening",
+  "mode": "conform",
+  "help": ["./help.md", "MD"],
+  "inline": "./exec.mjs"
+}

package/src/commands/promote/exec.mjs

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

package/src/commands/promote/help.md

@@ -0,0 +1,6 @@
+# promote
+
+`bos promote [--reject] [--apply]` moves the current branch one station:
+`master → developement → revision → testing → releasing → master`.
+`--reject` sends work back to `developement`. Without `--apply` it only shows
+the plan. `releasing → master` opens a GitHub pull request (needs `$GITHUB_TOKEN`).

package/src/commands/promote/index.json

@@ -0,0 +1,7 @@
+{
+  "path": "/promote",
+  "info": "move the current branch one station along the flow",
+  "mode": "smeltry",
+  "help": ["./help.md", "MD"],
+  "inline": "./exec.mjs"
+}

package/src/commands/repl/exec.mjs

@@ -0,0 +1,3 @@
+export default async ({ bos }) => {
+  await bos.views.startRepl(bos);
+};

package/src/commands/repl/help.md

@@ -0,0 +1,4 @@
+# repl
+
+`bos repl` gives an interactive prompt: type any command without `bos`, and
+`exit` to leave.

package/src/commands/repl/index.json

@@ -0,0 +1,6 @@
+{
+  "path": "/repl",
+  "info": "interactive BOS: every command at a prompt",
+  "help": ["./help.md", "MD"],
+  "inline": "./exec.mjs"
+}

package/src/commands/seal/exec.mjs

@@ -0,0 +1,8 @@
+import { resolve } from "node:path";
+
+import { BOS } from "../../main.ts";
+
+export default ({ operands: [dir = "."], flags }) => {
+  const manifest = new BOS.Model(resolve(dir)).seal({ dryRun: Boolean(flags.dryRun) });
+  return flags.json ? manifest : `sealed ${Object.keys(manifest.files).length} files`;
+};

package/src/commands/seal/help.md

@@ -0,0 +1,4 @@
+# seal
+
+`bos seal <dir>` records a sha256 of every file in `<dir>` into its manifest
+(`manifest.json` or `.manifest.json`).

package/src/commands/seal/index.json

@@ -0,0 +1,7 @@
+{
+  "path": "/seal",
+  "info": "write checksums of a directory into its manifest",
+  "mode": "conform",
+  "help": ["./help.md", "MD"],
+  "inline": "./exec.mjs"
+}

package/src/commands/sink/exec.mjs

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

package/src/commands/sink/help.md

@@ -0,0 +1,6 @@
+# sink
+
+`bos sink` is the first, read-only part of the sinking protocol. It lists
+every forge project with its branch and uncommitted changes, and the
+ttystories that show which tools were used. See
+`src/procedures/sinking/DESCRIPTION.md`.

package/src/commands/sink/index.json

@@ -0,0 +1,7 @@
+{
+  "path": "/sink",
+  "info": "inventory of what must be rescued from this workstation",
+  "mode": "almanac",
+  "help": ["./help.md", "MD"],
+  "inline": "./exec.mjs"
+}

package/src/commands/skills/exec.mjs

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

package/src/commands/skills/help.md

@@ -0,0 +1,5 @@
+# skills
+
+`bos skills [--dry-run]` drafts `skills/bos-<type>/SKILL.md` for every model
+that has no skill yet, using its glossary page and model class, and registers
+it in `.claude-plugin/marketplace.json`. Existing skills are never overwritten.

package/src/commands/skills/index.json

@@ -0,0 +1,7 @@
+{
+  "path": "/skills",
+  "info": "draft an agent skill for every model that has none",
+  "mode": "smeltry",
+  "help": ["./help.md", "MD"],
+  "inline": "./exec.mjs"
+}

package/src/commands/status/exec.mjs

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

package/src/commands/status/help.md

@@ -0,0 +1,6 @@
+# status
+
+`bos status` draws the workshop tree: **ok**, **missing** (mandatory but
+absent) or **not yet** (appears with use). Read-only.
+
+In `bos repl`, `status` also offers to create what is missing.

package/src/commands/status/index.json

@@ -0,0 +1,7 @@
+{
+  "path": "/status",
+  "info": "workshop tree and what is missing (read-only)",
+  "help": ["./help.md", "MD"],
+  "inline": "./exec.mjs",
+  "repl": "./repl.mjs"
+}

package/src/commands/status/repl.mjs

@@ -0,0 +1,14 @@
+// status, then offer to create what is missing
+import { paint } from "../../views/terminal/paint.mjs";
+
+const missing = (node) => [...(!node.exists && node.mandatory ? [node.path] : []), ...node.children.flatMap(missing)];
+
+export default async ({ bos, io }) => {
+  const context = await bos.workshop.status();
+  console.log(new bos.views.StatusView().text(context));
+  const absent = missing(context.tree);
+  if (!absent.length) return paint.green("\nnothing missing");
+  const answer = await io.question(`\n${absent.length} missing: create them now? [y/N] `);
+  if (!/^y(es)?$/i.test(answer.trim())) return paint.dim("left as it is");
+  return new bos.views.StatusView().text(await bos.workshop.bootstrap());
+};

package/src/commands/verify/exec.mjs

@@ -0,0 +1,9 @@
+import { resolve } from "node:path";
+
+import { BOS } from "../../main.ts";
+
+export default ({ operands: [dir = "."] }) => {
+  const result = new BOS.Model(resolve(dir)).verify();
+  if (!result.ok) process.exitCode = 1;
+  return result;
+};

package/src/commands/verify/help.md

@@ -0,0 +1,4 @@
+# verify
+
+`bos verify <dir>` compares `<dir>` with its manifest and lists missing,
+changed and unlisted files. Exits with 1 when something is missing or changed.

package/src/commands/verify/index.json

@@ -0,0 +1,7 @@
+{
+  "path": "/verify",
+  "info": "compare a directory with its manifest",
+  "mode": "conform",
+  "help": ["./help.md", "MD"],
+  "inline": "./exec.mjs"
+}

package/src/controllers/_index.mjs

@@ -0,0 +1,5 @@
+// Every controller: simplified management built from procedures.
+import SkillsControll from "./skills-controll.mjs";
+import WorkshopControll from "./workshop-controll.mjs";
+
+export default { WorkshopControll, SkillsControll };

package/src/controllers/skills-controll.mjs

@@ -0,0 +1,13 @@
+// Agent skills of this repository, one per model.
+import { BOS } from "../main.ts";
+import procedures from "../procedures/_index.mjs";
+
+export class SkillsControll extends BOS.Controll {
+  static flows = procedures;
+
+  scaffold(options) {
+    return this.run("skilling", options);
+  }
+}
+
+export default SkillsControll;

package/src/controllers/workshop-controll.mjs

@@ -0,0 +1,48 @@
+// The workshop as a handful of plain methods; each one runs a procedure.
+//   const workshop = new WorkshopControll({ workshop: "/tmp/x/__WORKSHOP" });
+//   await workshop.open();
+import { BOS } from "../main.ts";
+import procedures from "../procedures/_index.mjs";
+
+export class WorkshopControll extends BOS.Controll {
+  static flows = procedures;
+
+  locate() {
+    return this.run("locating");
+  }
+  status() {
+    return this.run("inspecting");
+  }
+  bootstrap(options) {
+    return this.run("bootstrapping", options);
+  }
+  open(options) {
+    return this.run("opening", options);
+  }
+  close(options) {
+    return this.run("closing", options);
+  }
+  sink() {
+    return this.run("sinking");
+  }
+  hook(hook) {
+    return this.run("hooking", { hook });
+  }
+  installHooks() {
+    return this.run("installingHooks");
+  }
+  gather(options) {
+    return this.run("gathering", options);
+  }
+  describe(options) {
+    return this.run("describing", options);
+  }
+  mode(mode) {
+    return this.run("modeSwitching", { mode });
+  }
+  promote({ reject = false, apply = false } = {}) {
+    return this.run("promoting", { reject, dryRun: !apply });
+  }
+}
+
+export default WorkshopControll;

package/src/core/basic-bridge.mjs

@@ -0,0 +1,29 @@
+// A bridge shapes one outside system (docker host, github, git, a subprocess…)
+// into a few plain methods. The SDK client is created lazily, on first use.
+
+export class BasicBridge {
+  static id = "bridge";
+
+  constructor(options = {}) {
+    this.options = options;
+  }
+
+  get client() {
+    this._client ??= this.connect();
+    return this._client;
+  }
+
+  // create the SDK client (dockerode, octokit, …); null when the bridge needs none
+  connect() {
+    return null;
+  }
+
+  // can this bridge be used on this machine right now?
+  async available() {
+    return true;
+  }
+
+  toString() {
+    return `[<BOS.Bridge::${this.constructor.id}>]`;
+  }
+}

package/src/core/basic-controll.mjs

@@ -0,0 +1,26 @@
+// A controll owns a set of logicflows and runs them with a prepared context.
+import { EventEmitter } from "node:events";
+
+export class BasicControll extends EventEmitter {
+  static flows = {};
+
+  constructor(options = {}) {
+    super();
+    this.options = options;
+  }
+
+  get flowNames() {
+    return Object.keys(this.constructor.flows);
+  }
+
+  async run(flowName, options = {}) {
+    const flow = this.constructor.flows[flowName];
+    if (!flow) throw new Error(`unknown logicflow "${flowName}" (known: ${this.flowNames.join(", ")})`);
+    const merged = { ...this.options, ...options };
+    const context = { options: merged, dryRun: Boolean(merged.dryRun), changes: [], trace: [] };
+    this.emit("start", flowName, context);
+    await flow.run(context);
+    this.emit("done", flowName, context);
+    return context;
+  }
+}

package/src/core/basic-element.mjs

@@ -0,0 +1,149 @@
+// Element anatomy shared by models and submodules: a directory plus descriptor
+// files (metadata.json, manifest.json, .index.json, Taskfile.yaml, .omnis.toml…).
+// A model stands on its own (built from a path); a submodule hangs on its owner
+// (built from the owner). Moving a class between the two is one `extends` line.
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, join, relative, sep } from "node:path";
+
+const MANIFEST_NAMES = ["manifest.json", ".manifest.json"];
+const NEVER_SEALED = new Set([".git", "node_modules", ...MANIFEST_NAMES]);
+
+export class BasicElement {
+  static type = "element";
+  static dirname = null; // fixed directory name (relative to the parent or owner); null for freely named assets
+  static mandatory = true; // created together with its parent when missing
+  static children = []; // fixed child models (areas)
+  static submodules = {}; // { property: Submodule } organs hanging on this element
+  static descriptors = {}; // { filename: (element, context) => default content }
+
+  constructor(path, parent = null) {
+    this.path = path;
+    this.parent = parent;
+    // every submodule becomes a lazy property: workshop.storylines
+    for (const [name, Submodule] of Object.entries(this.constructor.submodules)) {
+      let cached;
+      Object.defineProperty(this, name, { get: () => (cached ??= new Submodule(this)), enumerable: false });
+    }
+  }
+
+  get type() {
+    return this.constructor.type;
+  }
+  get name() {
+    return basename(this.path);
+  }
+  file(...names) {
+    return join(this.path, ...names);
+  }
+  exists() {
+    return existsSync(this.path);
+  }
+
+  // fixed children: areas first, then organs, in declaration order
+  childElements() {
+    return [
+      ...this.constructor.children.map((Child) => new Child(this.file(Child.dirname), this)),
+      ...Object.keys(this.constructor.submodules).map((name) => this[name]),
+    ];
+  }
+
+  // create what is missing and never overwrite; with context.dryRun only plan it
+  ensure(context = {}) {
+    createIfMissing(this.path, () => mkdirSync(this.path, { recursive: true }), context);
+    for (const [name, content] of Object.entries(this.constructor.descriptors)) {
+      const target = this.file(name);
+      createIfMissing(target, () => writeFileSync(target, serialize(content(this, context))), context);
+    }
+    for (const child of this.childElements()) {
+      if (child.constructor.mandatory) child.ensure(context);
+    }
+    return this;
+  }
+
+  // state of this element and its fixed areas, without touching the disk
+  inspect(parentMandatory = true) {
+    const mandatory = parentMandatory && this.constructor.mandatory;
+    const nodes = this.childElements().map((child) => child.inspect(mandatory));
+    return { type: this.type, path: this.path, exists: this.exists(), mandatory, children: nest(nodes) };
+  }
+
+  readJSON(name, fallback = null) {
+    try {
+      return JSON.parse(readFileSync(this.file(name), "utf8"));
+    } catch {
+      return fallback;
+    }
+  }
+
+  get manifestName() {
+    return (
+      MANIFEST_NAMES.find((name) => existsSync(this.file(name))) ??
+      Object.keys(this.constructor.descriptors).find((name) => MANIFEST_NAMES.includes(name)) ??
+      MANIFEST_NAMES[0]
+    );
+  }
+
+  // record checksums of every file into the manifest (integrity guard)
+  seal(context = {}) {
+    const manifest = this.readJSON(this.manifestName, {});
+    manifest.files = Object.fromEntries(walkFiles(this.path).map((path) => [relative(this.path, path), sha256(path)]));
+    manifest.sealedAt = Date.now();
+    if (!context.dryRun) writeFileSync(this.file(this.manifestName), serialize(manifest));
+    return manifest;
+  }
+
+  // compare the manifest checksums with the files on disk
+  verify() {
+    const manifest = this.readJSON(this.manifestName);
+    if (!manifest) return { ok: false, reason: `no ${this.manifestName}`, missing: [], changed: [], unlisted: [] };
+    const listed = manifest.files ?? {};
+    const missing = [];
+    const changed = [];
+    for (const [rel, expected] of Object.entries(listed)) {
+      const target = this.file(rel);
+      if (!existsSync(target)) missing.push(rel);
+      else if (sha256(target) !== expected) changed.push(rel);
+    }
+    const unlisted = walkFiles(this.path)
+      .map((path) => relative(this.path, path))
+      .filter((rel) => !(rel in listed));
+    return { ok: !missing.length && !changed.length, missing, changed, unlisted };
+  }
+}
+
+// organs declared with deeper paths (.BOS/storylines) sit under the node of their folder (.BOS)
+function nest(nodes) {
+  const inside = (node, other) => node !== other && node.path.startsWith(other.path + sep);
+  const tops = nodes.filter((node) => !nodes.some((other) => inside(node, other)));
+  return tops.map((top) => ({
+    ...top,
+    children: [...top.children, ...nest(nodes.filter((node) => inside(node, top)))],
+  }));
+}
+
+export function createIfMissing(target, create, context = {}) {
+  context.changes ??= [];
+  if (existsSync(target)) return false;
+  if (!context.dryRun) create();
+  context.changes.push(target);
+  return true;
+}
+
+export function sha256(path) {
+  return createHash("sha256").update(readFileSync(path)).digest("hex");
+}
+
+export function walkFiles(root) {
+  if (!existsSync(root)) return [];
+  return readdirSync(root, { withFileTypes: true }).flatMap((entry) => {
+    if (NEVER_SEALED.has(entry.name)) return [];
+    const path = join(root, entry.name);
+    if (entry.isDirectory()) return walkFiles(path);
+    return entry.isFile() ? [path] : [];
+  });
+}
+
+function serialize(content) {
+  return typeof content === "string" ? content : `${JSON.stringify(content, null, 2)}\n`;
+}

package/src/core/basic-model.mjs

@@ -0,0 +1,7 @@
+// A model is an asset of the workshop that stands on its own: built from any path.
+//   new Project("/home/smith/__WORKSHOP/forge/scope/project")
+import { BasicElement } from "./basic-element.mjs";
+
+export class BasicModel extends BasicElement {}
+
+export { createIfMissing, sha256, walkFiles } from "./basic-element.mjs";

package/src/core/basic-procedure.mjs

@@ -0,0 +1,37 @@
+// A procedure is an ordered list of named steps sharing one context object.
+// Every logicflow is a procedure; every run leaves a trace in context.trace.
+
+export class BasicProcedure {
+  constructor(name, steps = [], { description = "" } = {}) {
+    this.name = name;
+    this.steps = steps;
+    this.description = description;
+  }
+
+  step(name, action) {
+    this.steps.push({ name, action, owner: this.name });
+    return this;
+  }
+
+  // a new procedure made of this one's steps followed by the other's
+  chain(other, name = `${this.name}+${other.name}`) {
+    return new BasicProcedure(name, [...this.steps, ...other.steps], { description: this.description });
+  }
+
+  async run(context = {}) {
+    context.trace ??= [];
+    context.changes ??= [];
+    for (const { name, action, owner } of this.steps) {
+      const started = Date.now();
+      try {
+        await action(context);
+        context.trace.push({ procedure: owner, step: name, ok: true, ms: Date.now() - started });
+      } catch (error) {
+        context.trace.push({ procedure: owner, step: name, ok: false, error: error.message });
+        error.procedure ??= `${owner} › ${name}`;
+        throw error;
+      }
+    }
+    return context;
+  }
+}

package/src/core/basic-submodule.mjs

@@ -0,0 +1,21 @@
+// A submodule is an organ of its owner: it exists only inside that owner and is
+// built from it, never from a bare path. Its dirname is relative to the owner.
+//   workshop.storylines        (declared as  static submodules = { storylines: Storylines })
+import { BasicElement } from "./basic-element.mjs";
+
+export class BasicSubmodule extends BasicElement {
+  static ownerType = null; // the type of element this organ belongs to, e.g. "workshop"
+
+  constructor(owner) {
+    const { ownerType, dirname, name } = new.target;
+    if (!owner || !(owner instanceof BasicElement))
+      throw new Error(`${name} is a submodule: build it from its owner, not from a path`);
+    if (ownerType && owner.type !== ownerType)
+      throw new Error(`${name} hangs on a ${ownerType}, not on a ${owner.type}`);
+    super(owner.file(dirname), owner);
+  }
+
+  get owner() {
+    return this.parent;
+  }
+}

package/src/core/basic-view.mjs

@@ -0,0 +1,21 @@
+// One shared handler for every way BOS presents state (CLI text, JSON for
+// web / OpenAPI / MCP, ...). Subclasses only describe how state reads as text.
+
+export class BasicView {
+  static formats = ["text", "json"];
+
+  render(state, format = "text") {
+    if (format === "json") return JSON.stringify(this.data(state), null, 2);
+    if (format === "text") return this.text(state);
+    throw new Error(`unknown view format "${format}" (known: ${this.constructor.formats.join(", ")})`);
+  }
+
+  // what a machine interface receives; defaults to the whole state
+  data(state) {
+    return state;
+  }
+
+  text(state) {
+    return String(state);
+  }
+}

package/src/core/self.mjs

@@ -0,0 +1,10 @@
+// Where this BOS installation itself lives on the machine, and which version it is.
+// BOS is a project like any other: normally forge/<scope>/<project> inside a workshop.
+import { readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const REPO_ROOT = resolve(fileURLToPath(new URL("../..", import.meta.url)));
+export const RESOURCES = join(REPO_ROOT, "resources");
+export const CLI = join(REPO_ROOT, "src", "cli.mjs");
+export const VERSION = JSON.parse(readFileSync(join(REPO_ROOT, "package.json"), "utf8")).version;

package/src/index.mjs

@@ -0,0 +1,24 @@
+// Library entry: the spine, and every part by name.
+//   import { BOS } from "blacksmith-organization-system";
+//   const bos = await new BOS().load();  await bos.workshop.status();
+
+export { default as bridges } from "./bridge/_index.mjs";
+export { loadCommands } from "./commands/_index.mjs";
+export { default as controllers } from "./controllers/_index.mjs";
+export { createIfMissing, sha256, walkFiles } from "./core/basic-element.mjs";
+export { CLI, REPO_ROOT, RESOURCES, VERSION } from "./core/self.mjs";
+export { BOS, default } from "./main.ts";
+export {
+  default as models,
+  findAncestorWorkshop,
+  HOST_ROLES,
+  listWorkshops,
+  MODES,
+  modeByDigit,
+  placeOf,
+  resolveWorkshop,
+  submodules,
+} from "./models/_index.mjs";
+export { default as procedures } from "./procedures/_index.mjs";
+export { BRANCHES, PROMOTION, REJECTION } from "./procedures/promoting/branch-flow.mjs";
+export { default as views } from "./views/_index.mjs";