wip: refactor+test: simplifying documentation structure

- spec/Agent.spec.ts.md -> agent/README.md
- spec/Agent.test.ts -> agent/agent.test.ts

etc.

spec/Agent.test.ts → agent/agent.test.ts

@@ -1,9 +1,8 @@
-import { StubChain as Chain, StubAgent as Agent, Batch, Error, Console } from '@fadroma/agent'
+import { StubChain as Chain, StubAgent as Agent, Batch, Error, Console } from './agent'
 import assert from 'node:assert'
 
-import testEntrypoint from './testSelector'
+import { testEntrypoint, testSuite } from '@hackbg/ensuite'
 export default testEntrypoint(import.meta.url, {
-  'docs':    () => import('./Agent.spec.ts.md'),
   'obtain':  testAgentObtain,
   'batch':   testAgentBatch,
   'errors':  testAgentErrors,
@@ -69,7 +68,7 @@ export async function testAgentBatch () {
   //assert.throws(()=>batch.nextBlock)
   //assert.throws(()=>batch.balance)
 
-  let chain: Chain = Chain.mocknet()
+  let chain: Chain = new Chain({ id: 'stub' })
   let agent: Agent = await chain.getAgent({ address: 'testing1agent0' })
   let batch: Batch
 
@@ -151,3 +150,4 @@ export async function testAgentConsole () {
     if (typeof method==='function') try { method.bind(log)() } catch (e) { console.warn(e) }
   }
 }
+

connect/README.md

@@ -9,3 +9,54 @@ Catalog of Fadroma Agent implementations.
 See https://fadroma.tech for more info.
 
 </div>
+
+This package acts as a hub for the available Fadroma Agent API implementations.
+In practical terms, it allows you to connect to every chain (or other backend)
+that Fadroma supports.
+
+## Connect CLI
+
+```sh
+$ fadroma chain list
+```
+
+### Connection configuration
+
+## Connect API
+
+```typescript
+import connect from '@fadroma/connect'
+
+for (const platform of ['secretjs', 'secretcli']) {
+  for (const mode of ['mainnet', 'testnet', 'devnet', 'mocknet']) {
+    const { chain, agent } = connect({ platform, mode, mnemonic: '...' })
+  }
+}
+```
+
+## Configuration
+
+```typescript
+import { ConnectConfig } from '@fadroma/connect'
+const config = new ConnectConfig()
+config.getChain()
+config.getChain(null)
+assert.throws(()=>config.getChain('NoSuchChain'))
+config.getAgent()
+config.listChains()
+```
+
+## Errors
+
+```typescript
+import { ConnectError, ConnectConsole } from '@fadroma/connect'
+new ConnectError.NoChainSelected()
+new ConnectError.UnknownChainSelected()
+new ConnectConsole().selectedChain()
+```
+
+---
+
+```typescript
+import assert from 'node:assert'
+```

connect/connect.test.ts

@@ -0,0 +1,6 @@
+import { testEntrypoint } from '@hackbg/ensuite'
+
+export default testEntrypoint(import.meta.url, {
+  'docs': () => import('../spec/Connect.spec.ts.md'),
+})
+

connect/cw/README.md

@@ -12,75 +12,60 @@ See https://fadroma.tech for more info.
 
 ## Supported networks
 
-### [OKP4](https://okp4.network/)
+### Others
 
-OKP4 is an Open Knowledge Platform For decentralized ontologies.
+There is basic support for all chains accessible via `@cosmjs/stargate`.
+However, chain-specific features may not be directly available.
 
 ```typescript
-import { OKP4 } from '@fadroma/cw'
-
-// select chain and authenticate
-const okp4 = await OKP4.testnet().getAgent({ mnemonic: '...' }).ready
-
-// deploy cognitarium
-const { address: cognitariumAddress } = await okp4.instantiate(OKP4.Cognitarium.init())
-
-// select cognitarium
-const cognitarium = okp4.cognitarium(cognitariumAddress, okpAgent)
-
-// insert triples
-await cognitarium.insert('turtle', `
-  @prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
-  @prefix dc: <http://purl.org/dc/elements/1.1/> .
-  @prefix ex: <http://example.org/stuff/1.0/> .
-
-  <http://www.w3.org/TR/rdf-syntax-grammar>
-    dc:title "RDF/XML Syntax Specification (Revised)" ;
-    ex:editor [
-      ex:fullname "Dave Beckett";
-      ex:homePage <http://purl.org/net/dajobe/>
-    ] .
-`)
-
-// query triples
-const result = await cognitarium.select(1, [
-  /* prefixes */
-], [
-  /* selected variables */
-], [
-  /* where clauses */
-])
-
-// deploy objectarium
-const { address: objectariumAddress } = await okp4.instantiate(OKP4.Objectarium.init('fadroma'))
-
-// select objectarium
-const objectarium = okp4.objectarium(objectariumAddress, okpAgent)
-
-// use objectarium
-const { id: objectariumDataId } = await objectarium.store(false, 'somedatainbase64')
-await objectarium.pin(id)
-await objectarium.unpin(id)
-await objectarium.forget(id)
-
-// deploy law stone
-const { address: lawStoneAddress } = await okp4.instantiate(OKP4.LawStone.init('okp1...', `
-   admin_addr('${okp4.address}').
-`))
-
-// select law stone
-const lawStone = okp4.lawStone(lawStoneAddress, okpAgent)
-
-// use law stone
-await lawStone.ask(`admin_addr(${okp4.address})`)
-await lawStone.break()
+// TODO add example for connecting to generic CW-enabled chain
 ```
 
-### Others
+---
 
-There is basic support for all chains accessible via `@cosmjs/stargate`.
-However, chain-specific features may not be directly available.
+# Generic CosmWasm-enabled chains
 
 ```typescript
-// TODO add example for connecting to generic CW-enabled chain
+import assert from 'node:assert'
+```
+
+Fadroma supports connecting to any chain that supports CosmWasm.
+
+For this, we currently use our own fork of the `@cosmjs/*` packages,
+unified into a single package, [`@hackbg/cosmjs-esm`](https://www.npmjs.com/package/@hackbg/cosmjs-esm).
+
+## OKP4 support
+
+In these tests, we'll connect to a local OKP4 devnet
+managed by Fadroma on your local Docker installation.
+(Make sure you can call `docker` without `sudo`!)
+
+```typescript
+import '@hackbg/fadroma' // installs devnet support
+import { OKP4 } from '@fadroma/connect'
+
+const okp4 = await OKP4.devnet({ deleteOnExit: true }).ready
+assert(okp4 instanceof OKP4.Chain)
+```
+
+You can use the `cognitaria`, `objectaria` and `lawStones` methods
+to get lists of the corresponding contracts.
+
+```typescript
+console.log(await okp4.cognitaria())
+console.log(await okp4.objectaria())
+console.log(await okp4.lawStones())
+```
+
+To interact with them, you need to authenticate. This is done with
+the `getAgent` method. The returned `OKP4Agent` has the same listing
+methods - only this time the contracts are returned ready to use.
+
+```typescript
+const signer = { /* get this from keplr */ }
+const agent = await okp4.getAgent({ signer }).ready
+
+console.log(await agent.cognitaria())
+console.log(await agent.objectaria())
+console.log(await agent.lawStones())
 ```

connect/cw/okp4/README.md

@@ -0,0 +1,63 @@
+# [OKP4](https://okp4.network/) support in [Fadroma](https://fadroma.tech)
+
+OKP4 is an Open Knowledge Platform For decentralized ontologies.
+
+```typescript
+import { OKP4 } from '@fadroma/cw'
+
+// select chain and authenticate
+const okp4 = await OKP4.testnet().getAgent({ mnemonic: '...' }).ready
+
+// deploy cognitarium
+const { address: cognitariumAddress } = await okp4.instantiate(OKP4.Cognitarium.init())
+
+// select cognitarium
+const cognitarium = okp4.cognitarium(cognitariumAddress, okpAgent)
+
+// insert triples
+await cognitarium.insert('turtle', `
+  @prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
+  @prefix dc: <http://purl.org/dc/elements/1.1/> .
+  @prefix ex: <http://example.org/stuff/1.0/> .
+
+  <http://www.w3.org/TR/rdf-syntax-grammar>
+    dc:title "RDF/XML Syntax Specification (Revised)" ;
+    ex:editor [
+      ex:fullname "Dave Beckett";
+      ex:homePage <http://purl.org/net/dajobe/>
+    ] .
+`)
+
+// query triples
+const result = await cognitarium.select(1, [
+  /* prefixes */
+], [
+  /* selected variables */
+], [
+  /* where clauses */
+])
+
+// deploy objectarium
+const { address: objectariumAddress } = await okp4.instantiate(OKP4.Objectarium.init('fadroma'))
+
+// select objectarium
+const objectarium = okp4.objectarium(objectariumAddress, okpAgent)
+
+// use objectarium
+const { id: objectariumDataId } = await objectarium.store(false, 'somedatainbase64')
+await objectarium.pin(id)
+await objectarium.unpin(id)
+await objectarium.forget(id)
+
+// deploy law stone
+const { address: lawStoneAddress } = await okp4.instantiate(OKP4.LawStone.init('okp1...', `
+   admin_addr('${okp4.address}').
+`))
+
+// select law stone
+const lawStone = okp4.lawStone(lawStoneAddress, okpAgent)
+
+// use law stone
+await lawStone.ask(`admin_addr(${okp4.address})`)
+await lawStone.break()
+```