first commit

plugins/library-navigator/skills/sp-network-transport-libp2p/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: sp-network-transport-libp2p
+description: libp2p transport for @suaveplan/network — node creation, stream handlers, frame encoding, peer messaging, dial management, and OTel metrics.
+---
+
+# sp-network-transport-libp2p
+
+| Symbol | Kind | Responsibility |
+|---|---|---|
+| `Libp2pTransport` | Class | `Transport` implementation using libp2p |
+| `Libp2pPlugin` | Class | Network plugin wrapping libp2p transport |
+| `createAndStartNode` | Function | Creates and starts a libp2p node |
+| `stopNode` | Function | Gracefully stops a libp2p node |
+| `dialPeerAddress` | Function | Dials a peer by multiaddr |
+| `registerStreamHandler` | Function | Registers a protocol stream handler |
+| `consumeInboundStream` | Function | Consumes data from inbound stream |
+| `encodeFrame` | Function | Encodes message to wire frame |
+| `FrameDecoder` | Class | Decodes frames from libp2p stream |
+| `encodePeerMessage` | Function | Encodes peer message envelope |
+| `decodePeerMessage` | Function | Decodes peer message envelope |
+| `peerIdToString` | Function | Converts libp2p peer ID to string |
+| `sendEnvelope` | Function | Sends envelope over libp2p stream |
+| `sendEnvelopeFrame` | Function | Sends pre-encoded frame |
+| `NET_LIBP2P_CODES` | Constant | Error codes via `defineCodes` |
+| `NetLibp2pError` | Class | Typed error with libp2p codes |
+| `Libp2pConfigSchema` | Schema | Zod schema for transport configuration |
+
+**File Structure:** `packages/networking/network/network-transport-libp2p/src/{transport,plugin,connection,messaging,streams,errors,otel,types}/`
+
+**Sibling packages:**
+- `@suaveplan/network` — core network interfaces
+- `@suaveplan/network-plugin-transport-manager` — transport management
+- `@suaveplan/network-libp2p-server` — libp2p relay server
+
+**Patterns:**
+
+*Quick Start:*
+```ts
+import { Libp2pTransport } from "@suaveplan/network-transport-libp2p";
+const transport = new Libp2pTransport({ listenAddrs: ["/ip4/0.0.0.0/tcp/4001"] });
+```
+
+*Plugin:*
+```ts
+import { Libp2pPlugin } from "@suaveplan/network-transport-libp2p";
+node.use(new Libp2pPlugin({ listenAddrs: ["/ip4/0.0.0.0/tcp/4001"] }));
+```
+
+*Node lifecycle:*
+```ts
+import { createAndStartNode, stopNode } from "@suaveplan/network-transport-libp2p";
+const node = await createAndStartNode({ listenAddrs: ["/ip4/0.0.0.0/tcp/4001"] });
+await stopNode(node);
+```
+
+*Stream handling:*
+```ts
+import { registerStreamHandler, consumeInboundStream } from "@suaveplan/network-transport-libp2p";
+registerStreamHandler(node, "/my-protocol/1.0.0", async (stream) => {
+  for await (const data of consumeInboundStream(stream)) { /* ... */ }
+});
+```
+
+**Constraints:**
+- Implements `Transport` from `@suaveplan/network`
+- Uses libp2p for peer identity, transport, and protocol multiplexing
+- `createAndStartNode` configures and starts a libp2p node with defaults
+- `FrameDecoder` handles stream-based frame parsing
+- `registerStreamHandler` binds protocol handlers for inbound streams
+- OTel metrics: active peers, bytes, dials, stream opens, stream TTFB
+- Subpath exports: `transport`, `plugin`, `connection`, `messaging`, `streams`, `types`
+
+**Checklist:**
+- [ ] `Libp2pTransport` implements `Transport` interface
+- [ ] `createAndStartNode` creates functional libp2p node
+- [ ] `stopNode` gracefully shuts down connections
+- [ ] `dialPeerAddress` connects to remote peers
+- [ ] `FrameDecoder` parses frames from streams
+- [ ] `registerStreamHandler` binds protocol handlers
+- [ ] OTel metrics record transport activity
+- [ ] Error codes use `defineCodes` from `@suaveplan/error`