@chipschat/conformance 0.0.0-stage → 1.0.0

package/dist/fake-chips.d.ts

@@ -0,0 +1,130 @@
+/**
+ * A fake Chips: the wire an adapter speaks, on a real port, with the log and the rules of
+ * `workspace.ts` behind it. HTTP for what a harness says — `POST /v1/harnesses/:id/events`,
+ * `POST /v1/runs/:id/events`, the space door, uploads, the approval long poll — and `/v1/ws`
+ * for what it hears, with the handshake, the subscription, the replay and the acks the real
+ * server gives. The person's side has no port: the kit plays it by calling `say`, `decide`,
+ * `answer` and `askForSpace` directly, and reads the log the same way.
+ *
+ * The shapes here are the real routes' shapes, field for field, because an adapter passing
+ * against a stand-in that is looser than the server would learn nothing. Where the real server
+ * would do something this one cannot — sniff an upload's bytes, sign an attachment URL — the
+ * answer is honest about it: the mime type comes from the filename, the signature is a word.
+ */
+import { type IdGenerator, type JobRun } from "@chipschat/protocol";
+import { type FakeJoinView } from "./fake-join.js";
+import { FakeSettings, type SettingKind } from "./settings.js";
+import type { ChipsAddress } from "./subject.js";
+import { type StoredEvent, Workspace } from "./workspace.js";
+export interface FakeChipsOptions {
+    /** Where to listen. `0`, the default, takes any free port. */
+    readonly port?: number | undefined;
+    readonly host?: string | undefined;
+    readonly harnessName?: string | undefined;
+    readonly ownerName?: string | undefined;
+    readonly now?: (() => Date) | undefined;
+    readonly ids?: IdGenerator | undefined;
+    readonly version?: string | undefined;
+    /**
+     * What the harness declares, as its registration would (ADR 0046). `new_spaces` lets the person
+     * ask it for a room; nothing is declared otherwise.
+     */
+    readonly capabilities?: readonly string[] | undefined;
+}
+export interface DecideOptions {
+    readonly reason?: string | undefined;
+    readonly scope?: "once" | "session" | "always" | undefined;
+    readonly updatedInput?: unknown;
+}
+/** The harness saying how it is (ADR 0083): fine, or in trouble and why. */
+export interface HarnessStatus {
+    readonly state: "ok" | "trouble";
+    readonly reason?: string | undefined;
+    readonly at: string;
+}
+export interface FakeChips {
+    readonly address: ChipsAddress;
+    readonly workspace: Workspace;
+    /**
+     * The owner says something. In the direct space unless another is named, and as a reply to the
+     * message `replyTo` names when one is given (ADR 0219).
+     */
+    readonly say: (text: string, spaceId?: string, options?: {
+        readonly replyTo?: string;
+    }) => Promise<StoredEvent>;
+    /** The owner answers a card. */
+    readonly decide: (approvalId: string, decision: "approved" | "edited" | "denied", options?: DecideOptions) => Promise<StoredEvent>;
+    /** The owner answers a question: the choices given, or each question's default or first option. */
+    readonly answer: (askId: string, choices?: Readonly<Record<string, readonly string[]>>) => Promise<StoredEvent>;
+    /**
+     * The owner asks the harness for a new room, as the phone does on the first send: the room,
+     * asked of the harness, the harness added to it, and the words. For a harness that declares
+     * `new_spaces`; the door refuses it for any other, and so does this.
+     */
+    readonly askForSpace: (text: string) => Promise<{
+        spaceId: string;
+        message: StoredEvent;
+    }>;
+    /** A group room of the owner's, with nobody else in it yet. */
+    readonly openRoom: (title: string) => Promise<string>;
+    /**
+     * The owner asks for a copy of one of the harness's agents in a room (ADR 0087, Fork), as
+     * `POST /v1/agents/:id/fork` does. For a harness that declares `forks`; refused for any other.
+     */
+    readonly askForFork: (agentId: string, spaceId: string) => Promise<{
+        forkId: string;
+        asked: boolean;
+    }>;
+    /**
+     * The owner asks the harness for a new agent in a room (ADR 0108), as
+     * `POST /v1/spaces/:id/agents` does. For a harness that declares `new_agents`; refused for any
+     * other.
+     */
+    readonly askForAgent: (spaceId: string, name?: string) => Promise<{
+        askId: string;
+        name: string;
+    }>;
+    /** Any event, as the owner. A refusal throws, because the person's side is the kit's own. */
+    readonly asOwner: (event: Record<string, unknown>) => Promise<StoredEvent>;
+    /**
+     * Join requests (ADR 0122), the owner's side: a link made, allowed already with what it may do;
+     * the oldest request waiting allowed, with what is granted of what it asked, or refused; and
+     * every request so far. Whatever joins is handed this fake's harness.
+     */
+    readonly makeJoinLink: (capabilities?: readonly string[]) => string;
+    readonly allowJoin: (capabilities?: readonly string[]) => FakeJoinView;
+    readonly denyJoin: () => FakeJoinView;
+    readonly joinRequests: () => FakeJoinView[];
+    /** The first event that matches, in the log already or arriving within the time. */
+    readonly waitFor: <T>(match: (event: StoredEvent) => T | undefined, timeoutMs: number) => Promise<T>;
+    /** How many sockets are subscribed right now. */
+    readonly connections: () => number;
+    /** How many `hello`s the harness's sockets have said, so a reconnect is seen. */
+    readonly hellos: () => number;
+    /** The harness's settings copies and the answers they carried (ADRs 0134, 0140, 0143, 0146). */
+    readonly settings: FakeSettings;
+    /** The runs of its own jobs the harness posted, a run posted again in place (ADR 0252). */
+    readonly jobRuns: () => readonly JobRun[];
+    /**
+     * The owner changes a setting of an agent's (or, for `harness-context`, of the harness's) to what
+     * its copy says now, as the agent's page would: the frame, sent to every socket that said the
+     * kind's word in its `hello`, and how many heard it. Nothing when there is no copy, or nothing in
+     * it to change.
+     */
+    readonly askToChange: (kind: SettingKind, id: string) => {
+        readonly frame: Record<string, unknown>;
+        readonly heard: number;
+    } | undefined;
+    /** The owner asks the harness to restart (ADR 0094): how many sockets that said `restart` heard. */
+    readonly askToRestart: () => number;
+    /** What the harness has said of how it is (`PUT /v1/harnesses/:id/status`), oldest first. */
+    readonly statuses: () => readonly HarnessStatus[];
+    /**
+     * Has the harness shown up at all: a socket subscribed, or any call made with its token. A
+     * read counts, because a harness in hooks mode polls before it has anything to say.
+     */
+    readonly heard: () => boolean;
+    readonly close: () => Promise<void>;
+}
+export declare function startFakeChips(options?: FakeChipsOptions): Promise<FakeChips>;
+//# sourceMappingURL=fake-chips.d.ts.map

package/dist/fake-chips.d.ts.map

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