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

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Sett Sarverott
+Copyright (c) 2019 Sett Sarverott
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -9,92 +9,88 @@
              ▄█ ░█░ ▄█ ░█░ ██▄ █░▀░█
 ```
 > ###### [Sett Sarverott](https://github.com/Sarverott) @ 2019-2026
+---
 
-# Blacksmith Organization System
+# The core of the Blacksmith Organization System
 
-Tools, procedures and agent skills for the **Blacksmith Organization System
-(BOS)**: an ordered digital workshop. `~/__WORKSHOP` (per user) and
-`/media/**/__WORKSHOP` (per partition) are the root of code crafting, with
-the same shape on every host:
+A programmer's work gets scattered across machines, drives and servers, and
+the copies drift apart: *variantogeddon*. BOS gives every host the same fixed
+shape, a **workshop**, and keeps that shape by code:
 
-```
-__WORKSHOP/
-├── .BOS/        BOS itself: setup, data, nests, storylines
-├── devarmory/   tools
-├── forge/       active work: <scope>/<project>
-├── craftbook/   notes, recipes, procedures
-└── archive/     work at rest
-```
+- **builds the base** of the environment: `__WORKSHOP` with its areas
+  `.BOS`, `devarmory`, `forge`, `craftbook`, `archive`, creating only what is
+  missing and never overwriting;
+- **listens** to every change in it and says where it happened: area › scope
+  › project;
+- **inspects** it as one coherent environment: every scope and project in the
+  forge (branch, version, anatomy) and what is out of order;
+- runs the **craft loop** every BOS project follows: branches, steps, phases,
+  milestones and their versions (semver `vX.Y.Z` for projects, GRIH
+  `vG.R.I.H` for scopes).
 
-What each element means: [docs/glossary](docs/glossary/README.md).
+This is the core: a TypeScript module and the `bos` command.
 
-## Quick start
+## Install
 
-```bash
-cd ~/__WORKSHOP/forge/blacksmith-organization-system
-git clone https://github.com/Sarverott/blacksmith-organization-system.git bos-skillset
-cd bos-skillset && npm install && npm link   # `bos` on PATH
+Node ≥ 22.18.
 
-bos status      # workshop tree, what is missing (read-only)
-bos open        # create missing areas, record the opening
-bos close       # keep shell history as a ttystory, record the closing
-bos repl        # every command at an interactive prompt
+```sh
+npm install --global blacksmith-organization-system   # gives the command `bos`
+npx blacksmith-organization-system help               # or without installing
 ```
 
-Documentation site: built from `docs/` with MkDocs on Read the Docs (`task docs:serve` to preview).
+## Use
 
-More: [preinstall](docs/tutorials/preinstall.md) ·
-[installation](docs/tutorials/installation.md) ·
-[getting started](docs/tutorials/GETTING_STARTED.md) ·
-[first use](docs/tutorials/first-use-example.md) ·
-[logicflows](docs/tutorials/logicflow-explanation.md)
-
-## Skills
+```sh
+bos workshop status                 # the whole workshop: areas, scopes, projects, findings
+bos workshop bootstrap --dryRun     # what is missing; without --dryRun, create it
+bos workshop watch --record         # one line per change until Ctrl+C, kept in .BOS/storylines
+bos scope bump <scope> phase        # raise a scope's GRIH version: step, phase, milestone, flip
+bos devlog state                    # where a project stands, from its docs/devlog/
+bos help                            # every tool; --json gives machines the data
+```
 
-| Skill | Description |
-| ----- | ----------- |
-| [`bos-workshop`](skills/bos-workshop/SKILL.md) | Recognize workshops, their areas and elements; place work where it belongs |
-| `bos-devarmory` `bos-forge` `bos-craftbook` `bos-archive` | the crafting areas (drafts) |
-| `bos-scope` `bos-project` `bos-sheme` `bos-throwbox` `bos-sarcophag` `bos-exhibit` `bos-craftset` | the assets inside them (drafts) |
+Which workshop: `--workshop=<path>`, else `$BOS_WORKSHOP`, else
+`$WORKSHOP_ROOT/__WORKSHOP`, else the nearest parent `__WORKSHOP`, else
+`~/__WORKSHOP`. `$WORKSHOP_RENAME` changes the name `__WORKSHOP`.
+`bos workshop locate` says which one and why. Only `bootstrap` and `bump`
+write, and they create only what is missing.
 
-A model's skill is drafted from its glossary page by `bos skills` and then grown by hand.
+As a library:
 
-BOS is also a Claude Code plugin, an agent's suit: a session brief, read-only
-MCP tools over the workshop and the House, `bos` on PATH, the skills, and the
-agent's work recorded in storylines ([agent suit](docs/tutorials/agent-suit.md)):
+```ts
+import { BOS, NodeHost } from "blacksmith-organization-system";
 
-```
-/plugin marketplace add ~/__WORKSHOP/forge/blacksmith-organization-system/bos-skillset
-/plugin install bos@bos-skillset
+const bos = new BOS(new NodeHost());
+await bos.bootstrap();
+const report = await bos.inspect();
+console.log(report.forge.scopes.length, report.findings.length);
 ```
 
-Or link one skill manually: `ln -s "$PWD/skills/bos-workshop" ~/.claude/skills/bos-workshop`.
-New skills start from `template/SKILL.md` and are registered in `.claude-plugin/marketplace.json`.
+## Documentation
 
-## Repository layout
+https://blacksmith-organization-system.readthedocs.io/: the
+[glossary](https://blacksmith-organization-system.readthedocs.io/en/latest/glossary/)
+(every element of a workshop), the architecture of the core, the devlog and
+the changelog. To work on BOS itself:
+[CONTRIBUTING](https://github.com/Sarverott/blacksmith-organization-system/blob/development/.github/CONTRIBUTING.md).
 
-```
-src/
-├── main.ts         spine (class BOS)          ├── controllers/  management methods
-├── core/           skeleton logic             ├── commands/     index.json per command
-├── bridge/         docker, github, git, gitea ├── views/        status tree, help, repl
-├── models/         workshop assets            ├── cli.mjs       bos
-├── procedures/     protocols, step per file   └── index.mjs     library entry
-resources/  tests/  docs/  skills/  template/  .claude-plugin/
-Taskfile.yml  Dockerfile  compose.yaml  AGENTS.md  CLAUDE.md
-```
+The agents' skills and the Claude Code plugin are
+[bos-skillset](https://github.com/Sarverott/bos-skillset), which builds on
+this core.
 
-Details and the reasons behind the split: [AGENTS.md](AGENTS.md).
+## Where the idea came from
 
-## Branches
+The basic idea was to automate repository control and make order in project
+folders for better workspaces' view and control, with easier projects and
+publication management. The workshop dirtree worked well in one local
+workspace. Problems appeared when new workspaces joined, and variantogeddon
+from desynchronized versions grew out of control; then more, when keeping up
+the speed of commits and publication bundles at the same time with
+conventional methods. But this was only the beginning…
 
-`master` (spine of canon) → `developement` (here we code) → `revision` →
-`testing` → `releasing` → `master` through a pull request.
-See [branch movement procedures](docs/infographics/branch-movement-procedures.md); `bos promote` walks it.
-Every push releases: `x.y.z-dev.N` from developement, `-beta.N` from testing, `-rc.N`
-from releasing, `x.y.z` from master, on npm, GitHub Packages and ghcr.io
-([committing and releasing](docs/tutorials/committing-and-releasing.md)).
+The legacy CommonJS core (v0.6.1) is kept as the git tag `legacy/v0.6.1`.
 
 ## License
 
-MIT — see [LICENSE](LICENSE).
+Copyright (c) 2019-2026 Sett Sarverott, released on terms of the [MIT license](LICENSE).

package/dist/bridges/git.d.ts

@@ -0,0 +1,8 @@
+import type { Host } from "../core/host.ts";
+export declare class Git {
+    readonly host: Host;
+    readonly cwd: string;
+    constructor(host: Host, cwd: string);
+    git(args: string[]): string;
+    tagExists(tag: string): boolean;
+}

package/dist/bridges/git.js

@@ -0,0 +1,20 @@
+export class Git {
+    host;
+    // the directory of the repository
+    cwd;
+    constructor(host, cwd) {
+        this.host = host;
+        this.cwd = cwd;
+    }
+    git(args) {
+        const { status, stdout, stderr } = this.host.run("git", args, { cwd: this.cwd });
+        if (status !== 0)
+            throw new Error(`git ${args.slice(0, 2).join(" ")}: ${(stderr || stdout).trim()}`);
+        return stdout.trim();
+    }
+    // is the tag in this clone (in CI: checked out with its tags)
+    tagExists(tag) {
+        return this.git(["tag", "--list", tag]) === tag;
+    }
+}
+//# sourceMappingURL=git.js.map

package/dist/bridges/git.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"git.js","sourceRoot":"","sources":["../../src/bridges/git.ts"],"names":[],"mappings":"AAGA,MAAM,OAAO,GAAG;IACL,IAAI,CAAO;IACpB,kCAAkC;IACzB,GAAG,CAAS;IAErB,YAAY,IAAU,EAAE,GAAW;QACjC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC;IACjB,CAAC;IAED,GAAG,CAAC,IAAc;QAChB,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;QACjF,IAAI,MAAM,KAAK,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,IAAI,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QACrG,OAAO,MAAM,CAAC,IAAI,EAAE,CAAC;IACvB,CAAC;IAED,8DAA8D;IAC9D,SAAS,CAAC,GAAW;QACnB,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,QAAQ,EAAE,GAAG,CAAC,CAAC,KAAK,GAAG,CAAC;IAClD,CAAC;CACF"}

package/dist/bridges/github.d.ts

@@ -0,0 +1,28 @@
+import type { Host } from "../core/host.ts";
+export type Comparison = {
+    aheadBy: number;
+    commits: {
+        parents: number;
+        message: string;
+    }[];
+};
+export type PullRequest = {
+    number: number;
+    state: string;
+    base: string;
+    head: string;
+    crossRepository: boolean;
+};
+export declare class GitHub {
+    readonly host: Host;
+    readonly cwd: string;
+    constructor(host: Host, cwd: string);
+    gh(args: string[]): string;
+    json<T>(args: string[]): T;
+    repository(): string;
+    compare(base: string, head: string): Comparison;
+    openPullRequest(head: string, base: string): number | null;
+    createPullRequest(head: string, base: string, title: string, body: string): number;
+    pullRequest(number: number): PullRequest;
+    merge(number: number): void;
+}

package/dist/bridges/github.js

@@ -0,0 +1,71 @@
+export class GitHub {
+    host;
+    // the directory of the repository; gh finds the repository from its remote
+    cwd;
+    constructor(host, cwd) {
+        this.host = host;
+        this.cwd = cwd;
+    }
+    gh(args) {
+        const { status, stdout, stderr } = this.host.run("gh", args, { cwd: this.cwd });
+        if (status !== 0)
+            throw new Error(`gh ${args.slice(0, 2).join(" ")}: ${(stderr || stdout).trim()}`);
+        return stdout.trim();
+    }
+    json(args) {
+        return JSON.parse(this.gh(args));
+    }
+    // owner/name: $GITHUB_REPOSITORY inside Actions, else asked from gh
+    repository() {
+        return (this.host.env("GITHUB_REPOSITORY") ||
+            this.gh(["repo", "view", "--json", "nameWithOwner", "--jq", ".nameWithOwner"]));
+    }
+    // what head has that base has not
+    compare(base, head) {
+        const raw = this.json([
+            "api",
+            `repos/${this.repository()}/compare/${base}...${head}`,
+        ]);
+        return {
+            aheadBy: raw.ahead_by,
+            commits: raw.commits.map((c) => ({ parents: c.parents.length, message: c.commit.message })),
+        };
+    }
+    // the open pull request from head into base, if any
+    openPullRequest(head, base) {
+        const found = this.json([
+            "pr",
+            "list",
+            "--head",
+            head,
+            "--base",
+            base,
+            "--state",
+            "open",
+            "--json",
+            "number",
+        ]);
+        return found[0]?.number ?? null;
+    }
+    createPullRequest(head, base, title, body) {
+        const url = this.gh(["pr", "create", "--head", head, "--base", base, "--title", title, "--body", body]);
+        const number = Number(url.replace(/\/+$/, "").split("/").pop());
+        if (!Number.isInteger(number))
+            throw new Error(`gh pr create: no pull request number in "${url}"`);
+        return number;
+    }
+    pullRequest(number) {
+        const raw = this.json(["pr", "view", String(number), "--json", "number,state,baseRefName,headRefName,isCrossRepository"]);
+        return {
+            number: raw.number,
+            state: raw.state,
+            base: raw.baseRefName,
+            head: raw.headRefName,
+            crossRepository: raw.isCrossRepository,
+        };
+    }
+    merge(number) {
+        this.gh(["pr", "merge", String(number), "--merge"]);
+    }
+}
+//# sourceMappingURL=github.js.map

package/dist/bridges/github.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"github.js","sourceRoot":"","sources":["../../src/bridges/github.ts"],"names":[],"mappings":"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"}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+// bos <model> <tool> [operands] [--flags]  ·  bos help  ·  bos --version
+import { existsSync, readFileSync } from "node:fs";
+import { inputFor, parseArgs } from "./core/tool.js";
+import { NodeHost } from "./hosts/node.js";
+import { BOS } from "./main.js";
+import { findTool, TOOLS } from "./tools/_index.js";
+import { helpText } from "./views/help.js";
+const VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+// A checkout of the core may carry its own .env (see .env.example): the workshop it is developed
+// against, e.g. WORKSHOP_ROOT on a test partition, so the home workshop stays out of sight.
+// An installed package has none; variables already set in the shell win.
+const CHECKOUT_ENV = new URL("../.env", import.meta.url);
+if (existsSync(CHECKOUT_ENV))
+    process.loadEnvFile(CHECKOUT_ENV);
+async function main(argv) {
+    const { operands, flags } = parseArgs(argv);
+    const { workshop, json, ...toolFlags } = flags;
+    if (flags.version) {
+        console.log(VERSION);
+        return 0;
+    }
+    const [model, name, ...rest] = operands;
+    if (!model || model === "help") {
+        console.log(helpText(TOOLS, VERSION));
+        return 0;
+    }
+    const entry = findTool(model, name);
+    if (json && entry.args.some((arg) => arg.name === "json"))
+        toolFlags.json = json;
+    const input = inputFor(entry, rest, toolFlags);
+    const bos = new BOS(new NodeHost(), { workshop: typeof workshop === "string" ? workshop : undefined });
+    const stop = new AbortController();
+    process.once("SIGINT", () => stop.abort());
+    const result = await entry.run(bos, input, { print: (line) => console.log(line), signal: stop.signal });
+    // a streaming tool prints its lines itself; its closing summary goes to stderr, so stdout holds only data
+    const streams = entry.args.some((arg) => arg.name === "json");
+    const text = entry.render ? entry.render(result, input) : JSON.stringify(result ?? null, null, 2);
+    if (streams)
+        console.error(text);
+    else if (json)
+        console.log(JSON.stringify(result ?? null, null, 2));
+    else
+        console.log(text);
+    return 0;
+}
+main(process.argv.slice(2)).then((code) => {
+    process.exitCode = code;
+}, (error) => {
+    console.error(`bos: ${error instanceof Error ? error.message : String(error)}`);
+    process.exitCode = 1;
+});
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/core/context.d.ts

@@ -0,0 +1,18 @@
+import type { Host } from "./host.ts";
+export type TraceEntry = {
+    procedure: string;
+    step: string;
+    ok: boolean;
+    ms?: number;
+    error?: string;
+};
+export type Context = {
+    host: Host;
+    dryRun: boolean;
+    changes: string[];
+    trace: TraceEntry[];
+};
+export declare function createContext(host: Host, { dryRun }?: {
+    dryRun?: boolean | undefined;
+}): Context;
+export declare function createIfMissing(context: Context, target: string, create: () => void): boolean;

package/dist/core/context.js

@@ -0,0 +1,14 @@
+export function createContext(host, { dryRun = false } = {}) {
+    return { host, dryRun, changes: [], trace: [] };
+}
+// create target with create() only when it is missing; never overwrite.
+// In a dry run nothing is written, but the plan is still recorded in changes.
+export function createIfMissing(context, target, create) {
+    if (context.host.exists(target))
+        return false;
+    if (!context.dryRun)
+        create();
+    context.changes.push(target);
+    return true;
+}
+//# sourceMappingURL=context.js.map

package/dist/core/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/core/context.ts"],"names":[],"mappings":"AAaA,MAAM,UAAU,aAAa,CAAC,IAAU,EAAE,EAAE,MAAM,GAAG,KAAK,EAAE,GAAG,EAAE;IAC/D,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC;AAClD,CAAC;AAED,wEAAwE;AACxE,8EAA8E;AAC9E,MAAM,UAAU,eAAe,CAAC,OAAgB,EAAE,MAAc,EAAE,MAAkB;IAClF,IAAI,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC;QAAE,OAAO,KAAK,CAAC;IAC9C,IAAI,CAAC,OAAO,CAAC,MAAM;QAAE,MAAM,EAAE,CAAC;IAC9B,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC7B,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/core/element.d.ts

@@ -0,0 +1,49 @@
+import { type Context } from "./context.ts";
+import type { Host } from "./host.ts";
+export type Descriptor = (element: Element, context: Context) => string | object;
+export type ElementClass = {
+    new (host: Host, path: string, parent?: Element | null): Element;
+    type: string;
+    dirname: string | null;
+    mandatory: boolean;
+    children: ElementClass[];
+    descriptors: Record<string, Descriptor>;
+};
+export type ElementNode = {
+    type: string;
+    path: string;
+    exists: boolean;
+    mandatory: boolean;
+    descriptors: {
+        name: string;
+        exists: boolean;
+    }[];
+    children: ElementNode[];
+};
+export declare class Element {
+    static type: string;
+    static dirname: string | null;
+    static mandatory: boolean;
+    static children: ElementClass[];
+    static descriptors: Record<string, Descriptor>;
+    readonly host: Host;
+    readonly path: string;
+    readonly parent: Element | null;
+    constructor(host: Host, path: string, parent?: Element | null);
+    get kind(): ElementClass;
+    get type(): string;
+    get name(): string;
+    file(...names: string[]): string;
+    exists(): boolean;
+    child<T extends Element>(Kind: {
+        new (host: Host, path: string, parent?: Element | null): T;
+        dirname: string | null;
+    }): T;
+    childElements(): Element[];
+    ensure(context: Context): this;
+    inspect(parentMandatory?: boolean): ElementNode;
+    readJSON<T>(name: string, fallback: T): T;
+    writeJSON(name: string, value: object, context: Context): void;
+    toString(): string;
+}
+export declare function serialize(content: string | object): string;

package/dist/core/element.js

@@ -0,0 +1,97 @@
+// Element anatomy (glossary: element-anatomy): a directory plus descriptor files.
+// Every model of the workshop is an Element. Its fixed parts are declared once,
+// statically, and the same declaration drives creating (ensure) and reading (inspect).
+//   class Forge extends Element { static type = "forge"; static dirname = "forge"; }
+import { createIfMissing } from "./context.js";
+import { basename, join } from "./paths.js";
+export class Element {
+    static type = "element";
+    // fixed directory name, relative to the parent; null for freely named elements (a scope, a project)
+    static dirname = null;
+    // created together with its parent when missing
+    static mandatory = true;
+    // fixed child elements (areas, organs), in the order they are shown
+    static children = [];
+    // { filename: default content } written when missing, never overwritten
+    static descriptors = {};
+    host;
+    path;
+    parent;
+    constructor(host, path, parent = null) {
+        this.host = host;
+        this.path = path;
+        this.parent = parent;
+    }
+    get kind() {
+        return this.constructor;
+    }
+    get type() {
+        return this.kind.type;
+    }
+    get name() {
+        return basename(this.path);
+    }
+    file(...names) {
+        return join(this.path, ...names);
+    }
+    exists() {
+        return this.host.isDirectory(this.path);
+    }
+    child(Kind) {
+        return new Kind(this.host, this.file(Kind.dirname ?? ""), this);
+    }
+    childElements() {
+        return this.kind.children.map((Kind) => this.child(Kind));
+    }
+    // create the directory, missing descriptors and mandatory children; never overwrite
+    ensure(context) {
+        createIfMissing(context, this.path, () => this.host.mkdir(this.path));
+        for (const [name, content] of Object.entries(this.kind.descriptors)) {
+            const target = this.file(name);
+            createIfMissing(context, target, () => this.host.writeText(target, serialize(content(this, context))));
+        }
+        for (const child of this.childElements()) {
+            if (child.kind.mandatory)
+                child.ensure(context);
+        }
+        return this;
+    }
+    // what exists of this element and its fixed parts; reads only
+    inspect(parentMandatory = true) {
+        const mandatory = parentMandatory && this.kind.mandatory;
+        return {
+            type: this.type,
+            path: this.path,
+            exists: this.exists(),
+            mandatory,
+            descriptors: Object.keys(this.kind.descriptors).map((name) => ({
+                name,
+                exists: this.host.exists(this.file(name)),
+            })),
+            children: this.childElements().map((child) => child.inspect(mandatory)),
+        };
+    }
+    readJSON(name, fallback) {
+        const text = this.host.readText(this.file(name));
+        if (text === null)
+            return fallback;
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return fallback;
+        }
+    }
+    writeJSON(name, value, context) {
+        if (!context.dryRun)
+            this.host.writeText(this.file(name), serialize(value));
+        context.changes.push(this.file(name));
+    }
+    toString() {
+        return `[<BOS.${this.type}::${this.path}>]`;
+    }
+}
+export function serialize(content) {
+    return typeof content === "string" ? content : `${JSON.stringify(content, null, 2)}\n`;
+}
+//# sourceMappingURL=element.js.map

package/dist/core/element.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"element.js","sourceRoot":"","sources":["../../src/core/element.ts"],"names":[],"mappings":"AAAA,kFAAkF;AAClF,gFAAgF;AAChF,uFAAuF;AACvF,qFAAqF;AACrF,OAAO,EAAgB,eAAe,EAAE,MAAM,cAAc,CAAC;AAE7D,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAsB5C,MAAM,OAAO,OAAO;IAClB,MAAM,CAAC,IAAI,GAAG,SAAS,CAAC;IACxB,oGAAoG;IACpG,MAAM,CAAC,OAAO,GAAkB,IAAI,CAAC;IACrC,gDAAgD;IAChD,MAAM,CAAC,SAAS,GAAG,IAAI,CAAC;IACxB,oEAAoE;IACpE,MAAM,CAAC,QAAQ,GAAmB,EAAE,CAAC;IACrC,wEAAwE;IACxE,MAAM,CAAC,WAAW,GAA+B,EAAE,CAAC;IAE3C,IAAI,CAAO;IACX,IAAI,CAAS;IACb,MAAM,CAAiB;IAEhC,YAAY,IAAU,EAAE,IAAY,EAAE,SAAyB,IAAI;QACjE,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;IAED,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,WAA2B,CAAC;IAC1C,CAAC;IAED,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;IACxB,CAAC;IAED,IAAI,IAAI;QACN,OAAO,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC7B,CAAC;IAED,IAAI,CAAC,GAAG,KAAe;QACrB,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,KAAK,CAAC,CAAC;IACnC,CAAC;IAED,MAAM;QACJ,OAAO,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC1C,CAAC;IAED,KAAK,CAAoB,IAGxB;QACC,OAAO,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,IAAI,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC;IAClE,CAAC;IAED,aAAa;QACX,OAAO,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;IAC5D,CAAC;IAED,oFAAoF;IACpF,MAAM,CAAC,OAAgB;QACrB,eAAe,CAAC,OAAO,EAAE,IAAI,CAAC,IAAI,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;QACtE,KAAK,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC;YACpE,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAC/B,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,SAAS,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;QACzG,CAAC;QACD,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,aAAa,EAAE,EAAE,CAAC;YACzC,IAAI,KAAK,CAAC,IAAI,CAAC,SAAS;gBAAE,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QAClD,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,8DAA8D;IAC9D,OAAO,CAAC,eAAe,GAAG,IAAI;QAC5B,MAAM,SAAS,GAAG,eAAe,IAAI,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC;QACzD,OAAO;YACL,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE;YACrB,SAAS;YACT,WAAW,EAAE,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;gBAC7D,IAAI;gBACJ,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;aAC1C,CAAC,CAAC;YACH,QAAQ,EAAE,IAAI,CAAC,aAAa,EAAE,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;SACxE,CAAC;IACJ,CAAC;IAED,QAAQ,CAAI,IAAY,EAAE,QAAW;QACnC,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;QACjD,IAAI,IAAI,KAAK,IAAI;YAAE,OAAO,QAAQ,CAAC;QACnC,IAAI,CAAC;YACH,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAM,CAAC;QAC/B,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,QAAQ,CAAC;QAClB,CAAC;IACH,CAAC;IAED,SAAS,CAAC,IAAY,EAAE,KAAa,EAAE,OAAgB;QACrD,IAAI,CAAC,OAAO,CAAC,MAAM;YAAE,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC;QAC5E,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IACxC,CAAC;IAED,QAAQ;QACN,OAAO,SAAS,IAAI,CAAC,IAAI,KAAK,IAAI,CAAC,IAAI,IAAI,CAAC;IAC9C,CAAC;;AAGH,MAAM,UAAU,SAAS,CAAC,OAAwB;IAChD,OAAO,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC;AACzF,CAAC"}

package/dist/core/host.d.ts

@@ -0,0 +1,32 @@
+export type Entry = {
+    name: string;
+    directory: boolean;
+};
+export type Change = {
+    path: string;
+    kind: "change" | "rename";
+};
+export type RunResult = {
+    status: number;
+    stdout: string;
+    stderr: string;
+};
+export interface Host {
+    exists(path: string): boolean;
+    isDirectory(path: string): boolean;
+    list(path: string): Entry[];
+    readText(path: string): string | null;
+    writeText(path: string, text: string): void;
+    appendText(path: string, text: string): void;
+    mkdir(path: string): void;
+    watch(root: string, onChange: (change: Change) => void, onError: (error: Error) => void, skip?: (relative: string) => boolean): () => void;
+    run(command: string, args: string[], options?: {
+        cwd?: string;
+    }): RunResult;
+    env(name: string): string | undefined;
+    home(): string;
+    cwd(): string;
+    hostname(): string;
+    user(): string;
+    now(): number;
+}

package/dist/core/host.js

@@ -0,0 +1,5 @@
+// The one door between the core and the machine it runs on. Models and procedures
+// touch files, clocks and the environment only through a Host, so the same core can
+// run on Node (hosts/node.ts) today and on other runtimes later.
+export {};
+//# sourceMappingURL=host.js.map

package/dist/core/host.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"host.js","sourceRoot":"","sources":["../../src/core/host.ts"],"names":[],"mappings":"AAAA,kFAAkF;AAClF,oFAAoF;AACpF,iEAAiE"}

package/dist/core/paths.d.ts

@@ -0,0 +1,5 @@
+export declare function join(...parts: string[]): string;
+export declare function normalize(path: string): string;
+export declare function basename(path: string): string;
+export declare function dirname(path: string): string;
+export declare function inside(root: string, target: string): string | null;