docs: some more typedoc wrangling

devnet/devnet-impl.ts

@@ -363,14 +363,15 @@ function defineExitHandler (
 ) {
   let called = false
   return async function exitHandler (
-    this: Parameters<typeof setExitHandler>[0]
+    this: Parameters<typeof setExitHandler>[0],
+    ...args: unknown[]
   ) {
     if (called) {
       this.log.trace('Exit handler called more than once')
       return
     }
     called = true
-    this.log.debug('Running exit handler')
+    this.log.debug('Running exit handler', { args })
     if (this.onExit === 'delete') {
       this.log.log(`Exit handler: stopping and deleting ${this.chainId}`)
       await this.paused

oci/README.md

@@ -6,44 +6,40 @@ Here's a really simple way to achieve that with containers.
 ## Overview
 
 This library builds upon [Dockerode](https://www.npmjs.com/package/dockerode),
-and provides the `Engine`, `Image` and `Container` abstractions, which
+and provides the `OCIConnection`, `OCIImage` and `OCIContainer` abstractions, which
 make it easy and performant to package and run reproducible operations
 (such as containerized builds or ETL pipelines).
 
-* The **`Engine`** class connects to the Docker runtime at `/var/run/docker.sock`
+* The **`OCIConnection`** class connects to the Docker runtime at `/var/run/docker.sock`
   or the path specified by the `DOCKER_HOST` environment variable.
-* The **`Image`** class supports specifying both an upstream tag to pull from Docker Hub,
+* The **`OCIImage`** class supports specifying both an upstream tag to pull from Docker Hub,
   and/or a local fallback Dockerfile. This allows for fast iteration when constructing
   the Dockerized runtime environment.
-* From an `Image` instance, you can launch one or more **`Container`**s.
+* From an `OCIImage` instance, you can launch one or more **`OCIContainer`**s.
   If you like, you can run multiple parallel operations in identical contexts
   (as specified by a single local `Dockerfile`), and the `Image` will
   build itself locally, only once and without touching Docker Hub.
 
 ## Example
 
 ```typescript
-import Docker from '@fadroma/oci'
+import { OCIConnection } from '@fadroma/oci'
 
-const engine = new Docker.Engine()
+const docker = new OCIConnection()
 
-const image = engine.image(
+const image = docker.image(
   'my-org/my-build-image:v1', // This image will be pulled
   '/path/to/my/Dockerfile',   // If the pull fails, build from this Dockerfile
   [] // Any local paths referenced from the Dockerfile should be added here
 )
 
 const container = await image.run(`build_${+new Date()}`, {
- readonly: { '/my/project/sources':   '/src'  }, // -v ro
- writable: { '/my/project/artifacts': '/dist' }, // -v rw
- mapped: { 80: 8080 } // container:host
+  readonly: { '/my/project/sources':   '/src'  }, // -v ro
+  writable: { '/my/project/artifacts': '/dist' }, // -v rw
+  mapped: { 80: 8080 } // container:host
 })
 ```
 
-## Roadmap
-
-* [ ] Support Podman for fully rootless operation
-
 ---
 
 <div align="center">

oci/oci-mock.ts

@@ -38,8 +38,12 @@ export function mockDockerode (callback: Function = () => {}): DockerHandle {
 export function mockDockerodeContainer (callback: Function = () => {}) {
   return {
     id: 'mockmockmock',
-    logs (options: any, cb: Function) {
-      cb(...(callback({ createContainer: options })||[null, mockStream()]))
+    async logs (options: any, cb: Function) {
+      if (cb) {
+        cb(...(callback({ createContainer: options })||[null, mockStream()]))
+      } else {
+        return mockStream()
+      }
     },
     async start   () {},
     async attach  () { return {setEncoding(){},pipe(){}} },

oci/oci.ts

@@ -141,7 +141,7 @@ export class OCIImage extends ContractTemplate {
 
   protected _available: Promise<this>|null = null
 
-  async ensure (): Promise<this> {
+  async pullOrBuild (): Promise<this> {
     this._available ??= new Promise(async(resolve, reject)=>{
       this.log.ensuring()
       try {
@@ -243,7 +243,7 @@ export class OCIImage extends ContractTemplate {
     outputStream?: Writable
   } = {}) {
     const { name, options, command, entrypoint, outputStream } = parameters
-    await this.ensure()
+    await this.pullOrBuild()
     const container = new OCIContainer({ image: this, name, options, command, entrypoint })
     await container.create()
     if (outputStream) {
@@ -350,6 +350,8 @@ export class OCIContainer extends ContractInstance {
         this.log.boundPort(containerPort, HostPort)
       }
     }
+    // Make sure the image exists
+    await this.image.pullOrBuild()
     // Create the container
     this.container = await this.api.createContainer(opts)
     // Update the logger tag with the container id
@@ -421,7 +423,9 @@ export class OCIContainer extends ContractInstance {
       throw new OCIError.NoContainer()
     }
     const id = this.container.id.slice(0,8)
-    const stream = await this.container.logs({ stdout: true, stderr: true, follow: true, })
+    const stream = await this.container.logs({
+      stdout: true, stderr: true, follow: true
+    })
     if (!stream) {
       throw new OCIError('no stream returned from container')
     }

package.json

@@ -33,9 +33,7 @@
     "cov": "ensuite-cov fadroma.test.ts",
     "docs:dev": "ensuite-dev",
     "docs:render": "ensuite-render",
-    "docs:typedoc": "typedoc --customCss ./typedoc.css --tsconfig ./tsconfig.json --entryPointStrategy Packages --entryPoints agent --entryPoints connect --entryPoints ensuite --entryPoints ensuite/ganesha --entryPoints ensuite/toolbox --entryPoints .",
-    "docs:typedoc2": "typedoc --customCss ./typedoc.css --name Fadroma",
-    "docs:typedoc3": "typedoc --customCss ./typedoc.css --name Fadroma fadroma.ts",
+    "docs:typedoc": "typedoc",
     "fadroma": "FADROMA_PROJECT=./examples fadroma",
     "prepare": "husky install",
     "repl": "./fadroma.cli.cjs repl",
@@ -91,11 +89,11 @@
     "@types/prompts": "^2.4.8",
     "@types/secure-random": "^1.1.3",
 
-    "express": "^4.18.2",
-    "husky": "^8.0.3",
+    "typescript":  "^5.2.2",
+    "typedoc":     "0.25.7",
+    "husky":       "^8.0.3",
     "lint-staged": "^13.3.0",
-    "typedoc": "0.25.3",
-    "typescript": "^5.2.2"
+    "express":     "^4.18.2"
   },
   "pnpm": {
     "peerDependencyRules": {

tsconfig.json

@@ -3,8 +3,13 @@
     "fadroma.ts",
     "fadroma.browser.ts"
   ],
-  "include": [],
-  "exclude": [ ".ubik", "*.dist.*", "node_modules" ],
+  "include": [
+  ],
+  "exclude": [
+    ".ubik",
+    "*.dist.*",
+    "node_modules"
+  ],
   "compilerOptions": {
     "composite": true,
     "target": "esnext",

typedoc.css

@@ -0,0 +1,11 @@
+body {
+  font-family: "Cantarell", sans-serif;
+  background: rgb(101, 179, 76);
+}
+
+.container-main {
+  background: var(--color-background);
+  margin: 1rem auto;
+  padding: 1.5rem;
+  border-radius: 1rem;
+}

typedoc.json

@@ -1,14 +1,16 @@
 {
-  "$schema": "https://typedoc.org/schema.json",
-  "out": "docs",
-  "entryPoints": [
-    "fadroma.ts",
-    "fadroma.browser.ts",
-    "agent/agent.ts",
-    "ops/build.ts",
-    "connect/connect.ts",
-    "connect/scrt/scrt.ts",
-    "connect/cw/cw.ts"
-  ],
-  "entryPointStrategy": "resolve"
+    "$schema": "https://typedoc.org/schema.json",
+    "out": "docs",
+    "customCss": "./typedoc.css",
+    "entryPointStrategy": "packages",
+    "entryPoints": [
+      "./fadroma.ts",
+      "./agent",
+      "./create",
+      "./compile",
+      "./devnet",
+      "./cw",
+      "./scrt",
+      "./oci"
+    ]
 }