@jigs.design/server 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tom Bates
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,63 @@
-# Temporary Holding Version
+# @jigs.design/server
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`createPickleServer` turns a host into one fetch handler. That handler streams checked programs, runs queries and mutations, and serves the sandbox frame. You give it a `run` function per procedure, a `context` for each request, and a `model` function that calls your LLM.
+
+Import it from server code only.
+
+```ts
+import { createPickleServer, PickleError } from "@jigs.design/server";
+import { aiSdkModel } from "@jigs.design/ai-sdk";
+import { host } from "./host";
+
+export const pickle = createPickleServer({
+	host,
+	context: async (request) => ({ userId: await userIdFrom(request) }),
+	run: {
+		orders: (input, { ctx, signal }) =>
+			db.listOrders(ctx.userId, input.status, { signal }),
+		archiveOrder: async (input, { ctx }) => {
+			if (!(await db.archiveOrder(ctx.userId, input.id))) {
+				throw new PickleError("NOT_FOUND", "That order is gone.");
+			}
+		},
+	},
+	model: aiSdkModel("anthropic/claude-sonnet-5.5"),
+	instructions: "You are Acme's order assistant. Today is 2026-10-18.",
+});
+
+// Mount it as GET, POST and OPTIONS on one route, e.g. /api/pickle.
+export const handler = pickle.handler;
+```
+
+The server renders the prompt from the host, calls the model, checks each streamed prefix and compiles it to a program. `instructions`, such as who the assistant is and today's date, reach every prompt: document-mode sessions, chat and repairs. When the checker finds errors, it runs repair rounds. A call carries its procedure's `kind`, and the server refuses one that does not match the host. A follow-up turn may answer with SEARCH/REPLACE edits instead of a whole document.
+
+Specs need not come from the model. `pickle.spec(name)` returns a spec your product ships in `specs`, compiled once at startup. `pickle.compile(source)` checks and compiles one a user saved.
+
+## Exports
+
+| Export                     | What it is                                                                          |
+| -------------------------- | ----------------------------------------------------------------------------------- |
+| `createPickleServer`       | The server: `handler`, `spec`, `compile`, `chat`, and the functions `handler` wraps |
+| `defineRun`                | Types `run` functions outside a server, to share them between two servers           |
+| `PickleError`              | Throw from `context` or `run` with a code the browser can read                      |
+| `PickleCompileError`       | What a strict `pickle.compile` rejects with, carrying the `diagnostics`             |
+| `chatBlockText`            | Writes a chat block back as a fenced block, for the model's history                 |
+| `@jigs.design/server/node` | `nodeHandler`, for Node's `http` and Express                                        |
+
+It re-exports the shared types from `@jigs.design/runtime`.
+
+## Source
+
+- `src/server.ts`: `createPickleServer` and the request routing.
+- `src/session.ts`: one turn: prompt, model, checking, repair and edits.
+- `src/compile.ts`: compiling a document against the host's catalog and recipes.
+- `src/inputs.ts`, `src/literal.ts`: literal procedure inputs checked against their schemas.
+- `src/chat.ts`: chat mode, where a Markdown reply carries fenced `pickle` blocks.
+- `src/invalidation.ts`: which queries a mutation refreshes.
+- `src/pragma.ts`: the `{@pickle 0 catalog=3}` version line.
+- `src/node.ts`: the Node adapter.
+- `src/errors.ts`, `src/types.ts`: errors and the public types.
+
+## Docs
+
+[Server](../../apps/docs/docs/running/server.mdx), [Session](../../apps/docs/docs/running/session.mdx), [Chat](../../apps/docs/docs/running/chat.mdx), [Diagnostics](../../apps/docs/docs/running/diagnostics.mdx), [Transport](../../apps/docs/docs/running/transport.mdx).

package/dist/chat.d.ts

@@ -0,0 +1,12 @@
+import "./design.js";
+import { ChatBlockSource } from "./types.js";
+import "./session.js";
+import "@jigs.design/compiler";
+import { ChatBlock, Diagnostic, Program } from "@jigs.design/runtime";
+//#region src/chat.d.ts
+/**
+ * A block as the model wrote it, for the model's history: a fenced `pickle`
+ * block with its id, and its source without the pragma line.
+ */
+export declare function chatBlockText(block: ChatBlockSource): string;
+//#endregion