@mokronos/wfkit 0.1.0 → 0.1.2

package/GUIDE.md

@@ -0,0 +1,123 @@
+# Use wfkit with an agent
+
+Use these instructions when a user asks you to set up or test `@mokronos/wfkit`. Work in the user's project directory and use a project-local installation so the setup is reproducible.
+
+## Communication contract
+
+Before running a workflow, tell the user about every action they may need to take. This includes providing credentials, authorizing an account, approving a network request, or responding to a human-in-the-loop signal. Explain what is needed and why before the workflow reaches that point.
+
+Never invent credentials, silently substitute a different service, or leave the user with a workflow that appears to hang. If `wf` prints a pending signal command, relay that command and the expected payload to the user verbatim.
+
+The example below only reads a public file from GitHub. It does not need an account or token and does not change anything on GitHub. Before running it, tell the user that it will:
+
+- send one outbound `GET` request to `raw.githubusercontent.com`;
+- create local workflow state under `.wf/`;
+- read a public repository without sending credentials.
+
+If the environment blocks outbound network access, tell the user that network permission is required and wait for their direction.
+
+## Install and verify the CLI
+
+Check that Bun 1.2 or newer is available, then install wfkit locally:
+
+```sh
+bun --version
+bun add --dev @mokronos/wfkit
+bunx wf --help
+```
+
+If Bun is unavailable, tell the user that wfkit currently requires Bun and ask before installing or changing their runtime setup.
+
+## Create a real integration workflow
+
+Create `workflows/github-file-preview.ts` with this source:
+
+```ts
+import { defineStep, defineWorkflow, t } from "@mokronos/wfkit"
+
+const DownloadFailed = t.taggedStruct("DownloadFailed", {
+  url: t.string,
+  status: t.number
+})
+
+const fetchPublicGitHubFile = defineStep({
+  name: "FetchPublicGitHubFile",
+  input: t.struct({
+    owner: t.string,
+    repository: t.string,
+    path: t.string
+  }),
+  output: t.struct({
+    url: t.string,
+    bytes: t.number,
+    preview: t.string
+  }),
+  errors: DownloadFailed,
+  retry: { attempts: 3, backoff: "exponential" },
+  execute: async (input, step) => {
+    const encodedPath = input.path
+      .split("/")
+      .map((segment) => encodeURIComponent(segment))
+      .join("/")
+    const url = `https://raw.githubusercontent.com/${encodeURIComponent(input.owner)}/${encodeURIComponent(input.repository)}/HEAD/${encodedPath}`
+    const response = await fetch(url, {
+      headers: { "user-agent": "wfkit-agent-example" }
+    })
+
+    if (!response.ok) {
+      return step.fail({
+        _tag: "DownloadFailed",
+        url,
+        status: response.status
+      })
+    }
+
+    const contents = await response.text()
+    return {
+      url,
+      bytes: new TextEncoder().encode(contents).byteLength,
+      preview: contents.slice(0, 240)
+    }
+  }
+})
+
+export const GitHubFilePreviewWorkflow = defineWorkflow({
+  name: "GitHubFilePreviewWorkflow",
+  version: 1,
+  input: t.struct({
+    owner: t.string,
+    repository: t.string,
+    path: t.string
+  }),
+  output: t.struct({
+    url: t.string,
+    bytes: t.number,
+    preview: t.string
+  }),
+  errors: DownloadFailed,
+  run: function* (input, ctx) {
+    return yield* ctx.run(fetchPublicGitHubFile, input)
+  }
+})
+```
+
+Register and run it:
+
+```sh
+bunx wf create github-file-preview --file workflows/github-file-preview.ts --version 1
+bunx wf list
+bunx wf run github-file-preview '{"owner":"Effect-TS","repository":"effect","path":"README.md"}'
+bunx wf runs
+```
+
+Report the returned URL, byte count, and preview to the user. The completed run and its event history are persisted in `.wf/`; use the run ID printed by `wf run` to inspect it:
+
+```sh
+bunx wf history <run-id>
+```
+
+## Continue from here
+
+When adapting this example to an authenticated API, do not place secret values in workflow inputs or source code. Tell the user which secret is required, arrange an approved secret source, and use wfkit secret references so durable history stores the reference rather than the value.
+
+For human approval flows, explain the decision and payload to the user before starting. When the run suspends, copy the exact `wf signal ...` command printed by the CLI and wait for the user's response before sending it.

package/README.md

@@ -1,3 +1,5 @@
+> **[Use with your agent →](https://github.com/mokronos/wf/blob/main/packages/wf/GUIDE.md)** Copy the guide into your chat so your agent can install wfkit and run a real workflow for you.
+
 # @mokronos/wfkit
 
 @mokronos/wfkit is the Bun-first SDK for authoring and running durable workflows in plain TypeScript. Workflows have typed inputs, outputs, and errors; the engine (built on `@effect/workflow`) persists every step result, timer, and signal wait in SQLite, so executions replay deterministically and survive process restarts.

package/dist/sdk/loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../src/sdk/loader.ts"],"names":[],"mappings":"AAAA,OAAO,EAAyB,KAAK,eAAe,EAAE,MAAM,YAAY,CAAA;AACxE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAA;AAErD,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAA;IACnC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAA;CACnC;AAED,eAAO,MAAM,iBAAiB,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,eAK3D,CAAA;AA6CD,eAAO,MAAM,oBAAoB,GAC/B,UAAU,gBAAgB,KACzB,OAAO,CAAC,cAAc,CAqCxB,CAAA"}
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../src/sdk/loader.ts"],"names":[],"mappings":"AAAA,OAAO,EAAyB,KAAK,eAAe,EAAE,MAAM,YAAY,CAAA;AACxE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAA;AAErD,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAA;IACnC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAA;CACnC;AAED,eAAO,MAAM,iBAAiB,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,eAK3D,CAAA;AA8CD,eAAO,MAAM,oBAAoB,GAC/B,UAAU,gBAAgB,KACzB,OAAO,CAAC,cAAc,CAqCxB,CAAA"}

package/dist/sdk/loader.js

@@ -37,7 +37,8 @@ const compileWorkflowSource = async (artifact) => {
     }).outputText}\n//# sourceURL=wf:${artifact.id}@${artifact.version}\n`;
 };
 const rewriteWfImports = (source) => {
-    const wfModuleUrl = new URL("../authoring.ts", import.meta.url).href;
+    const authoringModule = import.meta.url.endsWith(".ts") ? "../authoring.ts" : "../authoring.js";
+    const wfModuleUrl = new URL(authoringModule, import.meta.url).href;
     return source
         .replaceAll(`from "@mokronos/wfkit"`, `from "${wfModuleUrl}"`)
         .replaceAll(`from '@mokronos/wfkit'`, `from '${wfModuleUrl}'`)

package/dist/sdk/loader.js.map

@@ -1 +1 @@
-{"version":3,"file":"loader.js","sourceRoot":"","sources":["../../src/sdk/loader.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"loader.js","sourceRoot":"","sources":["../../src/sdk/loader.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mokronos/wfkit",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "type": "module",
   "description": "The workflow authoring surface — the stable API agents design against.",
   "license": "MIT",
@@ -28,7 +28,8 @@
   "files": [
     "src",
     "dist",
-    "README.md"
+    "README.md",
+    "GUIDE.md"
   ],
   "bin": {
     "wf": "dist/cli/main.js",
@@ -59,9 +60,10 @@
     "prepublishOnly": "bun run build"
   },
   "dependencies": {
-    "@effect/platform-bun": "^4.0.0-beta.93",
-    "@effect/platform-node": "^4.0.0-beta.93",
-    "@effect/sql-sqlite-bun": "^4.0.0-beta.93",
-    "effect": "^4.0.0-beta.93"
+    "@effect/platform-bun": "4.0.0-beta.93",
+    "@effect/platform-node": "4.0.0-beta.93",
+    "@effect/platform-node-shared": "4.0.0-beta.93",
+    "@effect/sql-sqlite-bun": "4.0.0-beta.93",
+    "effect": "4.0.0-beta.93"
   }
 }

package/src/sdk/loader.ts

@@ -49,7 +49,8 @@ const compileWorkflowSource = async (artifact: WorkflowArtifact): Promise<string
 }
 
 const rewriteWfImports = (source: string): string => {
-  const wfModuleUrl = new URL("../authoring.ts", import.meta.url).href
+  const authoringModule = import.meta.url.endsWith(".ts") ? "../authoring.ts" : "../authoring.js"
+  const wfModuleUrl = new URL(authoringModule, import.meta.url).href
   return source
     .replaceAll(`from "@mokronos/wfkit"`, `from "${wfModuleUrl}"`)
     .replaceAll(`from '@mokronos/wfkit'`, `from '${wfModuleUrl}'`)