@unconfirmed/sui-effect 0.1.0

package/examples/extension-template/README.md

@@ -0,0 +1,170 @@
+# `@your-org/example-extension`
+
+A copyable skeleton for a sui-effect extension: one Effect service built on
+`Sui` and `Tx`, its errors, its three layers, its tests on the sui-effect
+harness, and the derived Promise face a `client.$extend(...)` consumer sees.
+
+`docs/extensions.md` in the sui-effect repository is the authoring guide, and
+every code block in it is copied from this directory.
+
+## What is in it
+
+| File | What it shows |
+|---|---|
+| `src/schema.ts` | Move layouts through `SuiSchema.bcs`, so an object's type tag is checked before its bytes are parsed |
+| `src/errors.ts` | Two `Schema.TaggedError` classes, each declaring the `outcome` a script's exit code is derived from |
+| `src/Escrow.ts` | The service: a read, a recipe fragment, a submit-on-behalf operation, a nested namespace, and `layer` / `layerConfig` / `layerTest` |
+| `src/upstream.ts` | A stand-in for a third-party Promise SDK, wrapped in `src/Escrow.ts` with `SuiCore.use` and `Effect.tryPromise` |
+| `src/extension.ts` | `SuiExtension.fromService`: the Promise face, derived, never hand-written |
+| `test/escrow.test.ts` | The whole test suite on `layerExtensionTest` and `SuiTest` from `@unconfirmed/sui-effect/testing`. No network, no mocks of its own |
+
+## Running it here
+
+```bash
+cd examples/extension-template
+bun run check        # tsc --noEmit && bun test
+```
+
+From the repository root, `bun run check:template` does the same thing.
+
+Do **not** run `bun install` in this directory while it lives inside the
+sui-effect repository. It needs no install: `effect` and `@mysten/sui` resolve
+from the repository's own `node_modules`, and `@unconfirmed/sui-effect` resolves through the
+`paths` block in `tsconfig.json`. Installing here would put a second copy of
+`effect` in scope, and two copies of `effect` in one process means two
+`Context.Service` identities and layers that silently do not match.
+
+## Consuming it from a separate checkout
+
+If you are developing your extension against a sui-effect **checkout** rather
+than a published version, use the packed tarball, not `link:` or `bun link`:
+
+```bash
+cd /path/to/sui-effect && bun run build && npm pack
+mkdir -p vendor && cp /path/to/sui-effect/unconfirmed-sui-effect-*.tgz vendor/
+bun add -d ./vendor/unconfirmed-sui-effect-0.1.0.tgz
+```
+
+`link:` and `bun link` symlink the checkout, and **module resolution follows the
+symlink's real path**: the linked checkout resolves `effect` and `@mysten/sui`
+from its own `node_modules`, your package resolves them from yours, and the two
+copies are nominally distinct. Every class that crosses the boundary then fails
+to typecheck with `#private` mismatches, and at runtime two `Context.Service`
+identities mean layers that silently do not match. Reserve `link:` for a real
+workspace member, where one `node_modules` serves both.
+
+Re-pack whenever the library changes, and **diff before you install**: `tar -tzf`
+the new tarball against the old one, so a file that stopped shipping is caught
+here rather than in a consumer. Record which sui-effect commit or tag the vendor
+copy came from — a line in your README, or the tarball's own filename — so a
+conversion can be re-run against the same library.
+
+## Copying it out
+
+1. Copy the directory somewhere of your own and rename it in `package.json`
+   (`name`, `description`, and the `escrow` property name in `src/extension.ts`).
+2. Delete the `baseUrl` and `paths` blocks from `tsconfig.json` **and
+   `tsconfig.build.json`**, and install the dependencies:
+
+   ```bash
+   bun add -d @unconfirmed/sui-effect effect@4.0.0-rc.112 @mysten/sui@2.30.0 @mysten/bcs \
+     @effect/language-service @types/bun typescript
+   ```
+
+   Note the `-d`. `@unconfirmed/sui-effect`, `effect` and `@mysten/sui` belong in
+   **`peerDependencies` and `devDependencies`**, never in `dependencies` — a
+   library that depends on any of them directly puts a second copy in the
+   consumer's process, and two copies of `effect` means two `Context.Service`
+   identities and layers that silently do not match. The `peerDependencies`
+   block this template ships already says so; `devDependencies` is what pins
+   the exact versions you build and test against.
+
+   `effect` is pinned **exactly** (`4.0.0-rc.112`), not to a range: rc.113
+   renamed `Config.nonEmptyString`, `Config.string` and `Config.redacted` to
+   `Config.NonEmptyString`, `Config.String` and `Config.Redacted`, so the
+   neighbouring rcs are not interchangeable. Match whatever `@unconfirmed/sui-effect`'s own
+   `peerDependencies` pins.
+
+   **Until `@unconfirmed/sui-effect` is published**, bun probes the registry for every
+   `peerDependencies` entry — even one a local dependency already satisfies —
+   and a 404 fails the install. That is what the
+   `peerDependenciesMeta["@unconfirmed/sui-effect"].optional: true` block in `package.json` is
+   for. Delete that block on the swap to the published package, and make it a
+   line on your release checklist: left in, it turns a genuinely missing peer
+   into a silent `undefined` at import time.
+3. Rename the service and its identifier. `"example-extension/Escrow"` is a
+   runtime key: pick `"<your-package>/<Name>"` once and never change it after
+   publishing.
+4. Replace `ESCROW_PACKAGE`, the BCS layouts and the Move call targets with
+   yours, and delete `src/upstream.ts` unless you really are wrapping a
+   third-party Promise package. Note that every type-shaped value —
+   `EscrowContent`, `escrowType`, `receiptType`, `SettlementContent` — is a
+   **function of the package id**, because a Move type name contains one:
+   configuring a different package has to move the codecs with it. Keep that
+   shape.
+5. Keep the shape: reads through `Sui`, writes through `Tx`, contributions as
+   recipe fragments, signers as parameters, every error a `Schema.TaggedError`
+   with an `outcome`, and the Promise face derived from the service.
+
+## Building and publishing
+
+`exports` points into `dist`, so the package has to be built before it is
+published or consumed:
+
+```bash
+bun run build      # tsc -p tsconfig.build.json, emitting dist/ with declarations
+bun run check      # typecheck, tests, and the packed-tarball check below
+```
+
+`bun run check:package` is the step that matters and the one most templates
+lack: it builds, packs the tarball with `bun pm pack`, unpacks it into a
+throwaway `node_modules`, and imports the package the way a consumer will.
+`tsc --noEmit` and `bun test` both import `src/`, so both pass for a package
+whose `dist` is never built and whose `files` list therefore ships nothing —
+which is exactly the state this template was in before. Keep the script.
+
+**It works after you copy the template out.** `check-package.ts` resolves
+`@unconfirmed/sui-effect`, `effect` and `@mysten/*` from this package's own `node_modules`
+first, which is what a copied-out package has after `bun install`, and only
+falls back to the sui-effect repository two directories up when that repository
+is really there (it checks the `name` in its `package.json`). Whichever copy of
+`@unconfirmed/sui-effect` it finds has to be **built**, because the consumer imports its
+`exports` map; a published tarball always is.
+
+To publish:
+
+1. Set `name`, `version` and, for a scoped package, `publishConfig.access`.
+   The template is `0.0.0` and deliberately **not** `private`: a package meant
+   to be copied and published must not carry a flag that silently refuses to.
+2. `bun run check`.
+3. `npm publish` (or `bun publish`). The `files` list ships `dist` and the
+   README and nothing else — no sources, no tests, no tsconfig.
+
+## Registering it on a client
+
+`src/extension.ts` and `src/Platform.ts` both register `warm` and both thread
+an `options.chainId` through. That is deliberate and it is the rule:
+
+- **Every registration on one client gets the same chain id.** The base `Sui`,
+  its transport and its **sender-lock map** are shared per client per effective
+  chain id. Two registrations that disagree — or one `warm` on a pinned id and
+  one lazy with none — get two of everything, and two `Tx.run`s for one address
+  stop serializing.
+- **`warm` needs a chain id it can take.** It builds the runtime inside
+  `register`, synchronously, so it never asks the node. `mainnet` and `testnet`
+  are in the built-in table; `devnet`, `localnet` and any custom network are
+  not, and `register` throws without `options.chainId`. `test/escrow.test.ts`
+  has that case.
+- **`warm` is what makes synchronous members real.** A recipe builder, a
+  package id or a codec read off a lazy registration before its first `await`
+  throws `ExtensionNotReady`.
+
+## The review checklist
+
+The guide's checklist, in short. Reject an extension that has a `Promise` in an
+interface, calls `executeTransaction` directly, holds a consumer signer in a
+layer, has `unknown` in an error channel, maintains a Promise facade by hand,
+or builds its own client instead of requiring `Sui`. Also reject one that
+declares `@unconfirmed/sui-effect` in `dependencies`, hand-builds a `TransportError` instead
+of `TransportError.fromUnknown`, or registers two extensions on one client with
+different chain ids.

package/examples/extension-template/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@your-org/example-extension",
+  "version": "0.0.0",
+  "description": "A copyable sui-effect extension package: one service, three layers, a derived Promise face.",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "check:package": "bun scripts/check-package.ts",
+    "check": "tsc --noEmit && bun test && bun scripts/check-package.ts"
+  },
+  "peerDependencies": {
+    "@mysten/bcs": "^2.1.1",
+    "@mysten/sui": "^2.28",
+    "effect": "4.0.0-rc.112",
+    "@unconfirmed/sui-effect": "^0.1.0"
+  },
+  "peerDependenciesMeta": {
+    "@unconfirmed/sui-effect": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@effect/language-service": "0.87.2",
+    "@mysten/bcs": "2.1.1",
+    "@mysten/sui": "2.30.0",
+    "@types/bun": "1.4.2",
+    "effect": "4.0.0-rc.112",
+    "typescript": "5.9.3"
+  }
+}

package/examples/extension-template/scripts/check-package.ts

@@ -0,0 +1,147 @@
+/**
+ * The check the template's own tests cannot do: build the package, pack the
+ * tarball, install it into a throwaway consumer, and import it.
+ *
+ * `tsc --noEmit` and `bun test` both import `src/`, so both pass for a package
+ * whose `exports` point at a `dist/` that is never built and whose `files` list
+ * therefore ships nothing. That is exactly the state this template was in. The
+ * only way to catch it is to look at what `npm pack` produces and to load it
+ * the way a consumer will.
+ *
+ * It runs offline, and it works **after you copy the template out**: the
+ * consumer's `@unconfirmed/sui-effect`, `effect` and `@mysten/*` are symlinked out of this
+ * package's own `node_modules` when it has them, which is what a copied-out
+ * package has after `bun install`. Only when neither is there does it fall back
+ * to the sui-effect repository two directories up, which is how it runs inside
+ * that repository with no install of its own. Keep the script when you copy;
+ * you should not have to rewrite it.
+ */
+import { $ } from "bun"
+import { existsSync, readFileSync } from "node:fs"
+import { mkdir, mkdtemp, readdir, rm, symlink, writeFile } from "node:fs/promises"
+import { tmpdir } from "node:os"
+import { join, resolve } from "node:path"
+
+const template = resolve(import.meta.dir, "..")
+const templateModules = join(template, "node_modules")
+
+/**
+ * The sui-effect checkout this template lives inside, or `undefined` when it
+ * has been copied out.
+ *
+ * Two directories up is only the library when it really is: a copied-out
+ * template's grandparent is somebody's `projects/` directory, and symlinking
+ * that in as `@unconfirmed/sui-effect` is how a copier's first `bun run check` failed with a
+ * message about a `dist` that was never going to exist.
+ */
+const repoOf = (): string | undefined => {
+  const candidate = resolve(template, "..", "..")
+  const manifest = join(candidate, "package.json")
+  if (!existsSync(manifest)) return undefined
+  try {
+    return JSON.parse(readFileSync(manifest, "utf8")).name === "@unconfirmed/sui-effect" ? candidate : undefined
+  } catch {
+    return undefined
+  }
+}
+
+const repo = repoOf()
+
+const fail = (message: string): never => {
+  console.error(`check-package: ${message}`)
+  process.exit(1)
+}
+
+/**
+ * Where the consumer's copy of one package comes from: this template's own
+ * `node_modules` first, the sui-effect repository's second.
+ */
+const sourceOf = (name: string): string | undefined => {
+  const own = join(templateModules, name)
+  if (existsSync(own)) return own
+  if (repo === undefined) return undefined
+  const inRepo = name === "@unconfirmed/sui-effect" ? repo : join(repo, "node_modules", name)
+  return existsSync(inRepo) ? inRepo : undefined
+}
+
+const suiEffect = sourceOf("@unconfirmed/sui-effect")
+if (suiEffect === undefined) {
+  fail(
+    "no @unconfirmed/sui-effect to check against: run `bun install` in this package, or run the script " +
+      "from inside the sui-effect repository"
+  )
+}
+// Whichever copy it is, the consumer imports its `exports` map, so it must be
+// built. A published tarball always is; a repository checkout may not be.
+if (!existsSync(join(suiEffect!, "dist", "index.js"))) {
+  fail(
+    `the @unconfirmed/sui-effect at ${suiEffect} is not built; run \`bun run build\` there first`
+  )
+}
+
+await rm(join(template, "dist"), { recursive: true, force: true })
+await $`bun x tsc -p ${join(template, "tsconfig.build.json")}`.cwd(template).quiet()
+
+const work = await mkdtemp(join(tmpdir(), "sui-effect-template-"))
+try {
+  await $`bun pm pack --destination ${work}`.cwd(template).quiet()
+  const packed = (await readdir(work)).filter((name) => name.endsWith(".tgz"))
+  const tarball = packed[0]
+  if (tarball === undefined) fail("bun pm pack produced no tarball")
+
+  // Extracted straight into the consumer's `node_modules`, where a real
+  // install would put it: a package resolves its own dependencies from where it
+  // lives, so unpacking it elsewhere and linking it in would fail on `effect`
+  // for reasons that have nothing to do with the package.
+  const consumer = join(work, "consumer")
+  const modules = join(consumer, "node_modules")
+  const name = JSON.parse(readFileSync(join(template, "package.json"), "utf8")).name as string
+  const [scope, bare] = name.startsWith("@") ? name.split("/") : [undefined, name]
+  const installed = join(modules, ...(scope === undefined ? [bare!] : [scope, bare!]))
+  await mkdir(scope === undefined ? modules : join(modules, scope), { recursive: true })
+  const extracted = join(work, "extracted")
+  await mkdir(extracted, { recursive: true })
+  await $`tar -xzf ${join(work, tarball!)} -C ${extracted}`.quiet()
+  await $`mv ${join(extracted, "package")} ${installed}`.quiet()
+
+  // What a consumer actually gets: the files the `files` list shipped, at the
+  // paths the `exports` map names.
+  for (const required of ["dist/index.js", "dist/index.d.ts", "package.json", "README.md"]) {
+    if (!existsSync(join(installed, required))) {
+      fail(`the packed tarball has no ${required}; check "files" and the build script`)
+    }
+  }
+
+  const suiEffectScope = join(modules, "@unconfirmed")
+  await mkdir(suiEffectScope, { recursive: true })
+  await symlink(suiEffect!, join(suiEffectScope, "sui-effect"), "dir")
+  for (const peer of ["effect", "@mysten"]) {
+    const source = sourceOf(peer)
+    if (source === undefined) {
+      fail(`no ${peer} to link into the consumer: run \`bun install\` in this package first`)
+    }
+    await symlink(source!, join(modules, peer), "dir")
+  }
+  await writeFile(
+    join(consumer, "package.json"),
+    JSON.stringify({ name: "consumer", private: true, type: "module" }, null, 2)
+  )
+  await writeFile(
+    join(consumer, "consume.ts"),
+    [
+      `import { Escrow, escrow, receiptType } from "${name}"`,
+      `if (typeof Escrow.layerTest !== "function") throw new Error("Escrow.layerTest is missing")`,
+      `if (typeof escrow !== "function") throw new Error("the registration factory is missing")`,
+      `if (!receiptType("0x2").endsWith("::escrow::Receipt")) throw new Error("receiptType is wrong")`,
+      `console.log("ok")`,
+      ""
+    ].join("\n")
+  )
+  const ran = await $`bun run ${join(consumer, "consume.ts")}`.cwd(consumer).quiet().nothrow()
+  if (ran.exitCode !== 0) {
+    fail(`the packed package did not import in a consumer:\n${ran.stderr.toString()}`)
+  }
+  console.log("check-package: the packed tarball imports in a fresh consumer")
+} finally {
+  await rm(work, { recursive: true, force: true })
+}