blacksmith-organization-system 0.4.2 → 1.1.0

package/README.md

@@ -1,83 +1,96 @@
-
-# Blacksmith Organization System
-
 ```
-      █▄▄ █░░ ▄▀█ █▀▀ █▄▀ █▀ █▀▄▀█ █ ▀█▀ █░█
-      █▄█ █▄▄ █▀█ █▄▄ █░█ ▄█ █░▀░█ █ ░█░ █▀█
+      █▄▄ █░░ ▄▀█ █▀▀ █▄▀ █▀ █▀▄▀█ █ ▀█▀ █░█
+      █▄█ █▄▄ █▀█ █▄▄ █░█ ▄█ █░▀░█ █ ░█░ █▀█
 
-   █▀█ █▀█ █▀▀ ▄▀█ █▄░█ █ ▀█ ▄▀█ ▀█▀ █ █▀█ █▄░█
-   █▄█ █▀▄ █▄█ █▀█ █░▀█ █ █▄ █▀█ ░█░ █ █▄█ █░▀█
+   █▀█ █▀█ █▀▀ ▄▀█ █▄░█ █ ▀█ ▄▀█ ▀█▀ █ █▀█ █▄░█
+   █▄█ █▀▄ █▄█ █▀█ █░▀█ █ █▄ █▀█ ░█░ █ █▄█ █░▀█
 
-             █▀ █▄█ █▀ ▀█▀ █▀▀ █▀▄▀█
-             ▄█ ░█░ ▄█ ░█░ ██▄ █░▀░█
+             █▀ █▄█ █▀ ▀█▀ █▀▀ █▀▄▀█
+             ▄█ ░█░ ▄█ ░█░ ██▄ █░▀░█
 ```
-
-### automation of management in personal forest of projects  
-> ###### Sett Sarverott @ 2019-2024
-> Part of R tier project "ANUBIS",
-
+> ###### [Sett Sarverott](https://github.com/Sarverott) @ 2019-2026
 ---
 
-### about:
-
-- basic and effective metodology of catalogization of project types, gouping parts of project and families of related projects and maintenance working condition
-
-- strategy invented espesialy for mad science of wast and divesed chaos of technomantic workspaces, tested in action, with clearified concrete concept
-
-- software system, that proofs mechanically, that it can be easy automated to help automate many casual software tasks
-
-- perfect solution for long term maintain and archivisation of life work in multiple areas of artistical and informatical activity.
+# The core of the Blacksmith Organization System
 
----
-
-### results of usage:
+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:
 
-- enjoy passion
-- skip mindless routines
-- keep productivity and quality of production
-- protect your work from version collisions and data losts
-- organize your life like ultimate boss of all cyberpunk blacksmiths
-- take controll of your forge.
----
+- **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).
 
-###### Source problems that makes me able to think it's more than possible
+This is the core: a TypeScript module and the `bos` command.
 
-The basic idea was to automate repository controll and make order in project folders for better workspaces' view and controll with easier projects and publication management. Basic idea was work well and just methods of workshop dirtree was big success in local workspace area. Problem appears when new workspaces joins area of my operations and variantogeddon from desynchronization of version grows to uncontrollable sizes. Next issues become visible, after attempts to maintain speed of commiting and supporting publications boundles in thesame time, using conventional methods. But this was only beginning...
+## Install
 
----
+Node ≥ 22.18.
 
-### Details of project:
+```sh
+npm install --global blacksmith-organization-system   # gives the command `bos`
+npx blacksmith-organization-system help               # or without installing
+```
 
-- [About Models](./system/models/README.md) - workspace tree elements
+## Use
 
-- [About Interfaces](./system/interfaces/README.md) - for standard interactions
+```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
+```
 
-- [About Bridges](./system/bridges/README.md) - integration with other systems
+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.
 
-- [About BOS Core](./system/core/README.md) - heart of cyberpunk blacksmith work
+As a library:
 
-- [About Factories](./system/factors/README.md) - templates for elements of BOS
+```ts
+import { BOS, NodeHost } from "blacksmith-organization-system";
 
-- [About Commands](./system/commands/README.md) - common set of commands
+const bos = new BOS(new NodeHost());
+await bos.bootstrap();
+const report = await bos.inspect();
+console.log(report.forge.scopes.length, report.findings.length);
+```
 
-- [About resources](./system/resources/README.md) - non-executable files
+## Documentation
 
-- ~[Documentation](./docs/README.md) - main documentation~
+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).
 
-- [DEV-LOG](./docs/devlog.md) - some scrap notes
+The agents' skills and the Claude Code plugin are
+[bos-skillset](https://github.com/Sarverott/bos-skillset), which builds on
+this core.
 
----
+## Where the idea came from
 
-### References:
+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…
 
-- ~npm REPO: https://www.npmjs.com/package/blacksmith-organization-system~
-- GitHub REPO: https://github.com/Sarverott/blacksmith-organization-system
-- also good to see about:
- - uses [carnival-toolbox](https://github.com/Sarverott/carnival-toolbox): npm library with many usefull tools
- - part of [project anubis](https://github.com/Sarverott/anubis-helpmate): ultimate acolyte assisting programm
- - ~[article about BOS metodology](https://sarverott.com/)~
+The legacy CommonJS core (v0.6.1) is kept as the git tag `legacy/v0.6.1`.
 
- ---
+## License
 
-### LICENSE:
-> Copyright (c) 2019 Sett Sarverott, released on terms of MIT 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":"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"}

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;