@dcasegr/skein 0.0.0-stage → 0.1.2

package/dist/dev/cli.js

@@ -0,0 +1,248 @@
+#!/usr/bin/env -S node --experimental-strip-types --no-warnings
+// `skein-dev`: the developer's tools. OUTSIDE the machine: this process reads
+// the disk and opens an instance's store file directly, which the kernel
+// itself never lets anything do.
+//
+//   - bootstrap: `install` puts the pinned wasm modules into the store file
+//     (they exceed a message; docs/OPEN.md). Trees and commands come from the
+//     client (bin/skein) through the messagebox.
+//   - inspection: `log`, `ls`, `show`, `refs` read the store.
+//
+// Replay is the kernel's: `skein-kernel replay <source.db> <out.db>`.
+import { readFile } from "node:fs/promises";
+import { mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { fmt, isCID, parse } from "../runtime/cid.js";
+import { readLog } from "../runtime/log.js";
+import { MODULES, rawCid } from "../runtime/programs.js";
+import { openStoreFile } from "../runtime/index-store.js";
+const skeinHome = () => process.env.SKEIN_HOME || join(homedir(), ".skein");
+export const dbPath = () => process.env.SKEIN_DB || join(skeinHome(), "runtime.db");
+const WASM_DIR = fileURLToPath(new URL("../../wasm/", import.meta.url));
+function openDefault(path) {
+    const p = path || dbPath();
+    mkdirSync(dirname(p), { recursive: true });
+    return openStoreFile(p);
+}
+class UsageError extends Error {
+}
+function parseArgs(argv, flags) {
+    const out = { pos: [], opts: {} };
+    const all = { help: "boolean", ...flags };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === "--") {
+            out.pos.push(...argv.slice(i + 1));
+            break;
+        }
+        if (a === "-h") {
+            out.opts.help = true;
+            continue;
+        }
+        if (!a.startsWith("--")) {
+            out.pos.push(a);
+            continue;
+        }
+        const eq = a.indexOf("=");
+        const name = a.slice(2, eq < 0 ? undefined : eq);
+        const kind = all[name];
+        if (!kind)
+            throw new UsageError(`unknown flag --${name}`);
+        if (kind === "boolean") {
+            out.opts[name] = true;
+            continue;
+        }
+        const v = eq >= 0 ? a.slice(eq + 1) : argv[++i];
+        if (v === undefined)
+            throw new UsageError(`--${name} needs a value`);
+        out.opts[name] = v;
+    }
+    return out;
+}
+const short = (c) => c.toString().slice(-12);
+const text = (b) => (b instanceof Uint8Array ? Buffer.from(b).toString("utf8") : String(b ?? ""));
+function jsonify(v) {
+    if (isCID(v))
+        return { "/": fmt(v) };
+    if (v instanceof Uint8Array)
+        return v.length <= 64 ? { bytes: Buffer.from(v).toString("hex") } : { text: text(v) };
+    if (Array.isArray(v))
+        return v.map(jsonify);
+    if (v && typeof v === "object")
+        return Object.fromEntries(Object.entries(v).map(([k, x]) => [k, jsonify(x)]));
+    return v;
+}
+/** Put the pinned wasm modules into the store under their CIDs (the shell's are the shell app's, #83: installed with it). */
+export async function install(store) {
+    const out = [];
+    const all = Object.entries(MODULES).map(([n, c]) => [`${n}.wasm`, c]);
+    for (const [file, cid] of all) {
+        const name = file.replace(/\.wasm$/, "");
+        if (await store.has(cid))
+            continue;
+        const bytes = await readFile(join(WASM_DIR, file));
+        if (!rawCid(bytes).equals(cid))
+            throw new Error(`wasm/${file} does not match the pinned ${fmt(cid)} (rebuilt? update src/runtime/programs.ts)`);
+        await store.putBlock(cid, bytes);
+        out.push(`${name} ${fmt(cid)}`);
+    }
+    return out;
+}
+export async function resolveCid(store, s) {
+    try {
+        return parse(s);
+    }
+    catch { /* a prefix or suffix */ }
+    const all = await store.findByPrefix("");
+    const hits = all.filter((c) => fmt(c).startsWith(s) || fmt(c).startsWith(`bafy${s}`) || fmt(c).endsWith(s));
+    if (hits.length !== 1)
+        throw new Error(hits.length ? `ambiguous: ${s}` : `no thread matches ${s}`);
+    return hits[0];
+}
+async function withStore(fn, path) {
+    const store = openDefault(path);
+    try {
+        return await fn(store);
+    }
+    finally {
+        await store.close();
+    }
+}
+const COMMANDS = {
+    install: {
+        usage: `skein-dev install
+  Put the pinned wasm modules (the shell's brush, coreutils and tools, the
+  wallet) into the store file under their CIDs: the bootstrap side door
+  (docs/OPEN.md); objects bigger than a message cannot arrive any other way yet.`,
+        flags: {},
+        async run(_a, env) {
+            const done = await withStore(install);
+            env.out(done.length ? done.map((l) => `installed ${l}`).join("\n") : "modules already in the store");
+            return 0;
+        },
+    },
+    log: {
+        usage: `skein-dev log [--limit n]
+  The input log: position, admission stamp, entry CID (the last is the state hash), and what it admits.`,
+        flags: { limit: "string" },
+        async run(a, env) {
+            await withStore(async (store) => {
+                const all = await readLog(store);
+                const lim = a.opts.limit ? Number(a.opts.limit) : all.length;
+                for (const { cid, entry } of all.slice(-lim)) {
+                    const when = new Date(entry.time[0] * 1000 + Math.floor(entry.time[1] / 1e6)).toISOString();
+                    const e8 = entry;
+                    const what = entry.genesis ? `genesis ${fmt(entry.genesis)}` : e8.request ? `${e8.transport} request ${fmt(e8.request)}`
+                        : e8.mail ? `mail ${fmt(e8.mail)}` : e8.event ? `${entry.box} event ${fmt(e8.event)}` : entry.envelope ? `${entry.box} envelope ${fmt(entry.envelope)}`
+                            : entry.outcome ? `outcome ${entry.outcome.status} emit ${fmt(entry.outcome.emit)}${entry.outcome.reason ? `: ${entry.outcome.reason}` : ""}` : `wake ${entry.wake ? fmt(entry.wake) : "?"}`;
+                    env.out(`${String(entry.n).padStart(4)}  ${when}  ${fmt(cid)}  ${what}`);
+                }
+                const tip = await store.log.tip();
+                env.out(`state ${tip ? fmt(tip) : "(empty)"} · processed ${await store.live.cursor.get()}/${all.length}`);
+            });
+            return 0;
+        },
+    },
+    ls: {
+        usage: `skein-dev ls [--limit 20]   threads, newest first: cid, state, command`,
+        flags: { limit: "string" },
+        async run(a, env) {
+            await withStore(async (store) => {
+                for await (const t of store.edges.query({ kind: "thread", limit: Number(a.opts.limit ?? 20) })) {
+                    const o = await store.get(t);
+                    const tip = await store.chains.tip(t);
+                    const u = tip.equals(t) ? undefined : await store.get(tip);
+                    env.out(`${short(t)}  ${(u?.state ?? "new").padEnd(8)}  ${o.args?.cmd ?? ""}`);
+                }
+            });
+            return 0;
+        },
+    },
+    show: {
+        usage: `skein-dev show <cid-or-suffix>   a thread (origin and updates) or any record as JSON`,
+        flags: {},
+        async run(a, env) {
+            if (!a.pos[0])
+                throw new UsageError("missing <cid>");
+            await withStore(async (store) => {
+                const cid = await resolveCid(store, a.pos[0]);
+                const b = await store.get(cid);
+                env.out(`${fmt(cid)}\n${JSON.stringify(jsonify(b), null, 2)}`);
+                if (b.kind !== "thread")
+                    return;
+                for await (const u of store.chains.history(cid)) {
+                    if (u.equals(cid))
+                        continue;
+                    const x = await store.get(u);
+                    const res = x.result;
+                    env.out(`#${x.seq} ${x.state}${x.waitingFrom ? ` from ${x.waitingFrom.slice(0, 12)}` : ""}  input …${x.input ? short(x.input) : "?"}  ${fmt(u)}`);
+                    if (res)
+                        env.out(`  exit ${res.exitCode} · tree ${res.tree ? fmt(res.tree) : "?"}\n  stdout: ${text(res.stdout).trimEnd().replace(/\n/g, "\n          ")}${res.stderr?.length ? `\n  stderr: ${text(res.stderr).trimEnd()}` : ""}`);
+                    if (x.error)
+                        env.out(`  ${x.error.kind}: ${x.error.message}`);
+                }
+            });
+            return 0;
+        },
+    },
+    refs: {
+        usage: `skein-dev refs <cid-or-suffix>   pointers out of the record's chain, and into it`,
+        flags: {},
+        async run(a, env) {
+            if (!a.pos[0])
+                throw new UsageError("missing <cid>");
+            await withStore(async (store) => {
+                const cid = await resolveCid(store, a.pos[0]);
+                const origin = await store.chains.originOf(cid).catch(() => cid);
+                const line = (r, other) => `  ${r.rel.padEnd(11)} ${isCID(other) ? fmt(other) : String(other)}${r.locator ? ` ${r.locator}` : ""}`;
+                env.out(`from ${fmt(origin)}`);
+                for (const r of await store.edges.refsFrom(origin))
+                    env.out(line(r, r.to));
+                env.out(`to ${fmt(cid)}`);
+                for (const r of await store.edges.refsTo(cid))
+                    env.out(line(r, r.from));
+            });
+            return 0;
+        },
+    },
+};
+const HELP = `skein-dev — developer tools, outside the machine
+
+  skein-dev install                        put the pinned wasm modules into the store file (bootstrap)
+  skein-dev log | ls | show <cid> | refs <cid>
+
+Trees and commands come from the client (bin/skein import / run) through the
+instance's front door. Replay: skein-kernel replay <source.db> <out.db>. Env: SKEIN_HOME (~/.skein), SKEIN_DB ($SKEIN_HOME/runtime.db).`;
+export async function main(argv) {
+    const env = {
+        out: (l) => process.stdout.write(`${l}\n`),
+        err: (l) => process.stderr.write(`${l}\n`),
+        write: (fd, b) => void (fd === 1 ? process.stdout : process.stderr).write(b),
+    };
+    const [name, ...rest] = argv;
+    if (!name || name === "--help" || name === "-h" || name === "help") {
+        env.out(HELP);
+        return name ? 0 : 1;
+    }
+    const cmd = COMMANDS[name];
+    if (!cmd) {
+        env.err(`unknown command: ${name}\n\n${HELP}`);
+        return 2;
+    }
+    try {
+        const a = parseArgs(rest, cmd.flags);
+        if (a.opts.help) {
+            env.out(cmd.usage);
+            return 0;
+        }
+        return await cmd.run(a, env);
+    }
+    catch (e) {
+        env.err(e instanceof UsageError ? `${e.message}\n\n${cmd.usage}` : `skein-dev ${name}: ${e.message}`);
+        return e instanceof UsageError ? 2 : 1;
+    }
+}
+if (import.meta.main)
+    process.exitCode = await main(process.argv.slice(2));

package/dist/dev/scan.d.ts

@@ -0,0 +1,15 @@
+import type { CID } from "multiformats/cid";
+import { type TreeBlocks } from "../runtime/tree.ts";
+export interface ScanOptions {
+    /** relPath is "/"-separated from the scanned root. Replaces the default. */
+    ignore?: (relPath: string) => boolean;
+}
+export declare function defaultIgnore(rel: string): boolean;
+/** Hash a directory into the store; returns the root tree. Empty directories vanish, as in git. */
+export declare function scan(blocks: TreeBlocks, dir: string, opts?: ScanOptions): Promise<CID>;
+/**
+ * Check `tree` out into `dir`: afterwards scan(dir) === tree. Anything not in the
+ * tree is removed, except paths `ignore` matches (by default .git and node_modules).
+ * Never writes through an existing symlink.
+ */
+export declare function materialize(blocks: TreeBlocks, tree: CID, dir: string, opts?: ScanOptions): Promise<void>;

package/dist/dev/scan.js

@@ -0,0 +1,173 @@
+// Directory <-> tree objects on a real disk. Outside the machine: the runtime
+// never reads or writes a disk. This is the client's job (docs/ARCH.md, "How a
+// file gets in and out"); skein-dev uses it as a stand-in for the client.
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+import * as fs from "node:fs/promises";
+import { join, resolve, sep } from "node:path";
+import { blobCid, hashBlob, hashTree, header, readBlob, readTree, sha1Cid } from "../runtime/tree.js";
+// Above this, hash from a stream first so a file the store already has is never held whole.
+const STREAM_OVER = 1 << 20;
+export function defaultIgnore(rel) {
+    const base = rel.slice(rel.lastIndexOf("/") + 1);
+    return base === ".git" || base === "node_modules";
+}
+// Bounds open file descriptors; directory recursion itself is unbounded (readdir holds no fd across awaits).
+function gate(n) {
+    let active = 0;
+    const waiting = [];
+    return async (fn) => {
+        while (active >= n)
+            await new Promise((r) => waiting.push(r));
+        active++;
+        try {
+            return await fn();
+        }
+        finally {
+            active--;
+            waiting.shift()?.();
+        }
+    };
+}
+async function putBlob(blocks, bytes) {
+    const cid = blobCid(bytes);
+    if (!(await blocks.has(cid)))
+        await blocks.putBlock(cid, hashBlob(bytes).object);
+    return cid;
+}
+async function streamCid(path, size) {
+    const h = createHash("sha1").update(header("blob", size));
+    let n = 0;
+    for await (const chunk of createReadStream(path)) {
+        h.update(chunk);
+        n += chunk.length;
+    }
+    return n === size ? sha1Cid(h.digest()) : undefined; // changed underfoot: caller rereads
+}
+async function scanFile(blocks, path, name) {
+    const st = await fs.lstat(path);
+    // git records only the owner's execute bit (core.filemode).
+    const mode = st.mode & 0o100 ? "100755" : "100644";
+    if (st.size > STREAM_OVER) {
+        const cid = await streamCid(path, st.size);
+        if (cid && (await blocks.has(cid)))
+            return { mode, name, cid };
+    }
+    return { mode, name, cid: await putBlob(blocks, await fs.readFile(path)) };
+}
+/** Hash a directory into the store; returns the root tree. Empty directories vanish, as in git. */
+export async function scan(blocks, dir, opts = {}) {
+    const ignore = opts.ignore ?? defaultIgnore;
+    const limit = gate(64);
+    const tree = async (abs, rel) => {
+        const dirents = await fs.readdir(abs, { withFileTypes: true });
+        const found = await Promise.all(dirents.map(async (d) => {
+            const r = rel ? `${rel}/${d.name}` : d.name;
+            if (ignore(r))
+                return undefined;
+            const p = join(abs, d.name);
+            if (d.isDirectory()) {
+                const cid = await tree(p, r);
+                return cid && { mode: "40000", name: d.name, cid };
+            }
+            if (d.isSymbolicLink()) {
+                return limit(async () => ({ mode: "120000", name: d.name, cid: await putBlob(blocks, await fs.readlink(p, { encoding: "buffer" })) }));
+            }
+            if (d.isFile())
+                return limit(() => scanFile(blocks, p, d.name));
+            return undefined; // fifos, sockets, devices: git skips them too
+        }));
+        const entries = found.filter((e) => e !== undefined);
+        if (entries.length === 0 && rel !== "")
+            return undefined;
+        const { cid, object } = hashTree(entries);
+        if (!(await blocks.has(cid)))
+            await blocks.putBlock(cid, object);
+        return cid;
+    };
+    return (await tree(resolve(dir), ""));
+}
+// ---------------------------------------------------------------- materialize
+function checkName(name, rel) {
+    // Trees come from anywhere; a name is one path segment or nothing. ".git" is refused as git does.
+    if (!name || name === "." || name === ".." || name.includes("/") || name.includes("\0") || name.toLowerCase() === ".git") {
+        throw new Error(`refusing tree entry ${JSON.stringify(name)} under ${JSON.stringify(rel || ".")}`);
+    }
+}
+async function lstatOr(path) {
+    try {
+        return await fs.lstat(path);
+    }
+    catch (e) {
+        if (e.code === "ENOENT")
+            return undefined;
+        throw e;
+    }
+}
+/**
+ * Check `tree` out into `dir`: afterwards scan(dir) === tree. Anything not in the
+ * tree is removed, except paths `ignore` matches (by default .git and node_modules).
+ * Never writes through an existing symlink.
+ */
+export async function materialize(blocks, tree, dir, opts = {}) {
+    const ignore = opts.ignore ?? defaultIgnore;
+    const root = resolve(dir);
+    await fs.mkdir(root, { recursive: true });
+    const limit = gate(32);
+    const inside = (p) => {
+        if (p !== root && !p.startsWith(root + sep))
+            throw new Error(`refusing to write outside ${root}: ${p}`);
+    };
+    const leaf = async (e, p, st) => {
+        const data = await readBlob(blocks, e.cid);
+        if (e.mode === "120000") {
+            if (st?.isSymbolicLink() && (await fs.readlink(p, { encoding: "buffer" })).equals(data))
+                return;
+            if (st)
+                await fs.rm(p, { recursive: true, force: true });
+            await fs.symlink(Buffer.from(data), p);
+            return;
+        }
+        const exec = e.mode === "100755";
+        if (st?.isFile()) {
+            if (st.size !== data.length || !(await fs.readFile(p)).equals(data))
+                await fs.writeFile(p, data);
+            if (Boolean(st.mode & 0o100) !== exec) {
+                // Add x wherever r is set (git's 0777&~umask shape); drop all x otherwise.
+                await fs.chmod(p, exec ? st.mode | ((st.mode & 0o444) >> 2) : st.mode & ~0o111);
+            }
+            return;
+        }
+        if (st)
+            await fs.rm(p, { recursive: true, force: true });
+        // "wx": O_EXCL refuses to follow anything that raced into place.
+        await fs.writeFile(p, data, { mode: exec ? 0o777 : 0o666, flag: "wx" });
+    };
+    const checkout = async (cid, abs, rel) => {
+        const entries = await readTree(blocks, cid);
+        for (const e of entries)
+            checkName(e.name, rel);
+        const want = new Set(entries.map((e) => e.name));
+        // Clear stale entries first so a file<->dir swap finds its slot empty.
+        for (const name of await fs.readdir(abs)) {
+            if (!want.has(name) && !ignore(rel ? `${rel}/${name}` : name))
+                await fs.rm(join(abs, name), { recursive: true, force: true });
+        }
+        await Promise.all(entries.map(async (e) => {
+            const p = join(abs, e.name);
+            inside(p);
+            const st = await lstatOr(p);
+            if (e.mode === "40000" || e.mode === "160000") {
+                if (st && !st.isDirectory())
+                    await fs.rm(p, { force: true }); // a symlink here must not be descended
+                if (!st?.isDirectory())
+                    await fs.mkdir(p);
+                if (e.mode === "40000")
+                    await checkout(e.cid, p, rel ? `${rel}/${e.name}` : e.name);
+                return;
+            }
+            await limit(() => leaf(e, p, st));
+        }));
+    };
+    await checkout(tree, root, "");
+}

package/dist/envelope-cbor.d.ts

@@ -0,0 +1,110 @@
+import type { WalletInterface } from "@bsv/sdk";
+import { type Envelope } from "./envelope.ts";
+import { CID } from "multiformats/cid";
+export interface CborEnvelope {
+    metanetHandles: "1.0";
+    recipient: {
+        handle: string;
+        tag?: string;
+        domain: string;
+    };
+    sender: {
+        identityKey: Uint8Array;
+        handle?: string;
+        domain?: string;
+    };
+    created: string;
+    quoteId?: string;
+    contentHash: Uint8Array;
+    content: Uint8Array;
+    signature: Uint8Array;
+}
+export type CborSigned = Omit<CborEnvelope, "content">;
+export declare function isCborSigned(x: unknown): x is CborSigned;
+export declare const isCborEnvelope: (x: unknown) => x is CborEnvelope;
+/** The preimage: dag-cbor of the envelope without content and signature. */
+export declare function preimage(env: Partial<CborEnvelope>): Uint8Array;
+export declare function cborSignedPart(env: CborEnvelope | CborSigned): CborSigned;
+export declare function verifyCbor(env: CborEnvelope | CborSigned): boolean;
+/** Seal `body` (dag-cbor) to `recipient` in the §7.3 form. */
+export declare function sealCbor(wallet: WalletInterface, args: {
+    recipient: {
+        identityKey: string;
+        handle: string;
+        domain: string;
+    };
+    sender?: {
+        handle?: string;
+        domain?: string;
+    };
+    body: Uint8Array;
+    created?: string;
+}): Promise<CborEnvelope>;
+/** Decrypt a §7.3 envelope's content as its recipient; checked against contentHash. */
+export declare function openCbor(wallet: WalletInterface, env: CborEnvelope): Promise<{
+    body: Uint8Array;
+    senderIdentityKey: string;
+}>;
+/** Either form: what a recipient needs from an envelope it was handed. */
+export type AnyEnvelope = Envelope | CborEnvelope;
+export declare function formOf(x: unknown): "json" | "cbor" | undefined;
+/** The sender's identity key (hex), the recipient (hex, from BRC-78), whether the signature verifies, the signed part and the message id (its CID as kept). */
+export declare function inspect(env: AnyEnvelope): {
+    form: "json" | "cbor";
+    sender: string;
+    recipient: string;
+    verified: boolean;
+    signed: object;
+    id: CID;
+};
+/**
+ * A reply on a BRC-104 session with the recipient's native messagebox: the
+ * compact §7.3 form, {type: "reply", replyTo, body} — sender, recipient,
+ * host and the envelope signature left out, because the session supplies
+ * them. It travels as BRC-231 bytes (so the signed request carries the body
+ * itself). The first message on a session, and anything for an external box,
+ * is a full envelope.
+ */
+export interface CompactReply {
+    type: "reply";
+    replyTo: CID;
+    body: Uint8Array;
+}
+export declare function isCompactReply(x: unknown): x is CompactReply;
+/**
+ * The record a session reply is kept as — the same entry shape as a full
+ * envelope's ({envelope, box, body}), its envelope record carrying the proof:
+ * the BRC-104 signature over `payload` (the signed request) with the session
+ * nonces; `messageId` is SHA-256 of that payload.
+ */
+export declare function sessionRecord(r: CompactReply, sender: string, created: string, s: {
+    payload: Uint8Array;
+    signature: Uint8Array;
+    nonce: string;
+    yourNonce: string;
+}): {
+    type: "reply";
+    replyTo: CID<unknown, number, number, import("multiformats/cid").Version>;
+    sender: {
+        identityKey: Uint8Array<ArrayBuffer>;
+    };
+    created: string;
+    contentHash: Uint8Array<ArrayBuffer>;
+    messageId: Uint8Array<ArrayBuffer>;
+    session: {
+        payload: Uint8Array<ArrayBufferLike>;
+        signature: Uint8Array<ArrayBufferLike>;
+        nonce: string;
+        yourNonce: string;
+    };
+};
+/** How a JSON client carries §7.3 bytes in a BRC-33 JSON body: {"dag-cbor": "<base64>"}. */
+export declare const wrapCbor: (env: CborEnvelope) => {
+    "dag-cbor": string;
+};
+/**
+ * A BRC-33 body as an envelope: §7.3 dag-cbor (its bytes, as BRC-231 carries
+ * them, or `{"dag-cbor": "<base64>"}`, how a JSON client carries those bytes,
+ * or the decoded map), or §7.2 JSON (the object, or its JSON text).
+ */
+export declare function asEnvelope(raw: unknown): AnyEnvelope | undefined;