@fungi.computer/parakeet-testing 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jamstack Consulting LLC
+
+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,80 @@
-# Temporary Holding Version
+# Parakeet Testing (`@fungi.computer/parakeet-testing`)
 
-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.
+Parakeet Testing provides shared fixtures for tests of Parakeet renderers. The
+fixtures model Shiitake Session activity and one extension catalog so each
+renderer can exercise the same extension and slash-completion cases.
+
+## Install or set up
+
+This package provides shared test fixtures, not a runtime dependency of shipped
+renderers. From the repository root, build it with:
+
+```sh
+pnpm turbo:run run build --filter=@fungi.computer/parakeet-testing
+```
+
+Import fixtures from `@fungi.computer/parakeet-testing` in workspace test code.
+
+## Quick start
+
+This illustrative example gives a Session a running test extension slot and
+checks the fixture's response to a command:
+
+```ts
+import {
+  gardenCall,
+  gardenExtensionId,
+  gardenSlots,
+} from "@fungi.computer/parakeet-testing";
+
+const slots = gardenSlots();
+const extension = slots[gardenExtensionId];
+if (extension?.status !== "running") throw new Error("Fixture is not running");
+
+const reply = await gardenCall("water", { bed: "fern" });
+```
+
+The fixture test verifies slot construction and the garden reply in
+[`test/garden.test.ts`](test/garden.test.ts). Renderer tests should exercise
+their own Session and UI seams with these shared inputs.
+
+## Core concepts
+
+`idleActivity`, `queuedActivity`, and `runningActivity` create common Session
+activity states. `gardenExtensionId`, `gardenCatalog`, and `gardenSlots()`
+provide a running `test-garden` extension advertising `/water`. Its `gardenCall`
+function answers that command with a choice prompt when no bed is given and a
+success result when one is provided.
+
+`slashParityCases` lists composer drafts and the completion rows every renderer
+should show for built-in commands plus `/water`. `slashParityFlow` describes the
+shared flow: enter `/water`, choose the fern bed, and receive the success
+notice.
+
+## API reference
+
+See the generated [fixture API reference](docs/api/README.md) for exported
+fixtures and types.
+
+## Examples and checks
+
+Run the fixture contract tests with:
+
+```sh
+pnpm --filter @fungi.computer/parakeet-testing test
+```
+
+Consumer tests live with their renderer. This package's test verifies its
+fixtures; it does not prove every renderer uses them correctly.
+
+## Limits and errors
+
+These fixtures model a small extension and a fixed completion flow. They do not
+provide production Session state, execute real tools, or replace tests of a
+renderer's own input, completion, and dispatch behavior. The package is not
+packed for publication.
+
+## Contribute and license
+
+Keep shared cases deterministic and suitable for renderer tests. The package
+declares an MIT license.

package/dist/index.d.ts

@@ -0,0 +1,42 @@
+import type { SessionActivity, SessionExtensionSlots } from "@fungi.computer/shiitake/client";
+import { type Json } from "@fungi.computer/shiitake/extensions";
+import type { WhistleCatalogV1 } from "@fungi.computer/whistle/catalog";
+/** Activity facts for a Session with nothing queued or running. */
+export declare const idleActivity: SessionActivity;
+/** Activity facts for accepted Session work awaiting its host. */
+export declare function queuedActivity(commandId: string): SessionActivity;
+/** Activity facts for a Session whose work is running; override what differs. */
+export declare function runningActivity(overrides?: Partial<SessionActivity>): SessionActivity;
+/** Activity facts for a Session with a compaction running now. */
+export declare function compactingActivity(trigger?: NonNullable<SessionActivity["compaction"]>["trigger"]): SessionActivity;
+/**
+ * A test-only extension that no client names: it advertises `/water` through
+ * its Session slot and answers through the ordinary extension door. Every
+ * Parakeet renderer proves it can offer and run it with no client change.
+ */
+export declare const gardenExtensionId = "test-garden";
+/** The catalog the garden extension advertises. */
+export declare const gardenCatalog: WhistleCatalogV1;
+/** The slots a Session that rosters the garden extension reports. */
+export declare function gardenSlots(): SessionExtensionSlots;
+/** The garden extension's door: one stateless step per call. */
+export declare function gardenCall(command: string, input: Json): Promise<Json>;
+/** One input every renderer must complete identically. */
+export type SlashParityCase = Readonly<{
+    /** The composer draft. */
+    draft: string;
+    /** The row labels every renderer must show, in order. */
+    rows: readonly string[];
+}>;
+/**
+ * Completion cases for a runtime holding only Parakeet's built-ins and the
+ * garden extension. Renderers type each draft and compare the rows they draw.
+ */
+export declare const slashParityCases: readonly SlashParityCase[];
+/** The flow every renderer runs: `/water`, choose the fern bed, see the result. */
+export declare const slashParityFlow: {
+    readonly draft: "/water";
+    readonly prompt: "Which bed?";
+    readonly choose: "Fern bed";
+    readonly notice: "Watered the fern bed.";
+};

package/dist/index.js

@@ -0,0 +1,127 @@
+import { parseExtensionJson, } from "@fungi.computer/shiitake/extensions";
+import { z } from "zod";
+/** Activity facts for a Session with nothing queued or running. */
+export const idleActivity = {
+    queue: { state: "idle" },
+    cancellationRequested: false,
+    retry: null,
+    activeTool: null,
+    lastModelChoiceSequence: null,
+    compaction: null,
+};
+/** Activity facts for accepted Session work awaiting its host. */
+export function queuedActivity(commandId) {
+    return {
+        ...idleActivity,
+        queue: { state: "queued", commandId, runningWork: null },
+    };
+}
+/** Activity facts for a Session whose work is running; override what differs. */
+export function runningActivity(overrides = {}) {
+    return {
+        ...idleActivity,
+        queue: { state: "running", commandId: "running-command" },
+        ...overrides,
+    };
+}
+/** Activity facts for a Session with a compaction running now. */
+export function compactingActivity(trigger = "manual") {
+    return runningActivity({ compaction: { trigger } });
+}
+/**
+ * A test-only extension that no client names: it advertises `/water` through
+ * its Session slot and answers through the ordinary extension door. Every
+ * Parakeet renderer proves it can offer and run it with no client change.
+ */
+export const gardenExtensionId = "test-garden";
+/** The catalog the garden extension advertises. */
+export const gardenCatalog = {
+    protocol: "whistle.catalog/v1",
+    commands: [
+        {
+            id: "water",
+            title: "Water a garden bed",
+            category: "Conversation",
+            description: "Water one bed, or every bed at once",
+            projections: {
+                help: { order: 20 },
+                slash: {
+                    aliases: ["water"],
+                    order: 20,
+                    arguments: {
+                        hint: "<bed> | all",
+                        words: [
+                            {
+                                word: "all",
+                                description: "Water every bed",
+                                arguments: { bed: "all" },
+                            },
+                        ],
+                        text: { field: "bed", arguments: {} },
+                    },
+                },
+            },
+        },
+    ],
+};
+/** The slots a Session that rosters the garden extension reports. */
+export function gardenSlots() {
+    return {
+        [gardenExtensionId]: {
+            status: "running",
+            revision: "sha256:garden",
+            value: null,
+            catalog: parseExtensionJson(JSON.stringify(gardenCatalog)),
+        },
+    };
+}
+const waterInput = z.strictObject({ bed: z.string().min(1).optional() });
+/** The garden extension's door: one stateless step per call. */
+export function gardenCall(command, input) {
+    if (command !== "water")
+        return Promise.reject(new Error(`Unknown garden command ${command}`));
+    const { bed } = waterInput.parse(input);
+    if (bed === undefined)
+        return Promise.resolve({
+            type: "prompt",
+            prompt: {
+                type: "choice",
+                message: "Which bed?",
+                options: [
+                    { value: "fern", label: "Fern bed" },
+                    { value: "moss", label: "Moss bed" },
+                ],
+            },
+            next: { arguments: {}, answer: "bed" },
+        });
+    return Promise.resolve({
+        type: "done",
+        notice: {
+            type: "success",
+            message: bed === "all" ? "Watered every bed." : `Watered the ${bed} bed.`,
+        },
+    });
+}
+/**
+ * Completion cases for a runtime holding only Parakeet's built-ins and the
+ * garden extension. Renderers type each draft and compare the rows they draw.
+ */
+export const slashParityCases = [
+    { draft: "/", rows: ["/help", "/water"] },
+    { draft: "/w", rows: ["/water"] },
+    { draft: "/wtr", rows: ["/water"] },
+    { draft: "/e", rows: ["/water"] },
+    { draft: "/he", rows: ["/help"] },
+    { draft: "/se", rows: [] },
+    { draft: "/water ", rows: ["all"] },
+    { draft: "/water a", rows: ["all"] },
+    { draft: "/water fern", rows: [] },
+    { draft: "/zzz", rows: [] },
+];
+/** The flow every renderer runs: `/water`, choose the fern bed, see the result. */
+export const slashParityFlow = {
+    draft: "/water",
+    prompt: "Which bed?",
+    choose: "Fern bed",
+    notice: "Watered the fern bed.",
+};

package/docs/api/README.md

@@ -0,0 +1,177 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+**@fungi.computer/parakeet-testing**
+
+---
+
+# @fungi.computer/parakeet-testing
+
+## Type Aliases
+
+### SlashParityCase
+
+```ts
+type SlashParityCase = Readonly<{
+  draft: string;
+  rows: readonly string[];
+}>;
+```
+
+One input every renderer must complete identically.
+
+## Variables
+
+### idleActivity
+
+```ts
+const idleActivity: SessionActivity;
+```
+
+Activity facts for a Session with nothing queued or running.
+
+---
+
+### gardenExtensionId
+
+```ts
+const gardenExtensionId: "test-garden" = "test-garden";
+```
+
+A test-only extension that no client names: it advertises `/water` through its
+Session slot and answers through the ordinary extension door. Every Parakeet
+renderer proves it can offer and run it with no client change.
+
+---
+
+### gardenCatalog
+
+```ts
+const gardenCatalog: WhistleCatalogV1;
+```
+
+The catalog the garden extension advertises.
+
+---
+
+### slashParityCases
+
+```ts
+const slashParityCases: readonly SlashParityCase[];
+```
+
+Completion cases for a runtime holding only Parakeet's built-ins and the garden
+extension. Renderers type each draft and compare the rows they draw.
+
+---
+
+### slashParityFlow
+
+```ts
+const slashParityFlow: object;
+```
+
+The flow every renderer runs: `/water`, choose the fern bed, see the result.
+
+#### Type Declaration
+
+| Name                                  | Type                      | Default value             |
+| ------------------------------------- | ------------------------- | ------------------------- |
+| <a id="property-draft"></a> `draft`   | `"/water"`                | `"/water"`                |
+| <a id="property-prompt"></a> `prompt` | `"Which bed?"`            | `"Which bed?"`            |
+| <a id="property-choose"></a> `choose` | `"Fern bed"`              | `"Fern bed"`              |
+| <a id="property-notice"></a> `notice` | `"Watered the fern bed."` | `"Watered the fern bed."` |
+
+## Functions
+
+### queuedActivity()
+
+```ts
+function queuedActivity(commandId): SessionActivity;
+```
+
+Activity facts for accepted Session work awaiting its host.
+
+#### Parameters
+
+| Parameter   | Type     |
+| ----------- | -------- |
+| `commandId` | `string` |
+
+#### Returns
+
+`SessionActivity`
+
+---
+
+### runningActivity()
+
+```ts
+function runningActivity(overrides?): SessionActivity;
+```
+
+Activity facts for a Session whose work is running; override what differs.
+
+#### Parameters
+
+| Parameter   | Type                           |
+| ----------- | ------------------------------ |
+| `overrides` | `Partial`\<`SessionActivity`\> |
+
+#### Returns
+
+`SessionActivity`
+
+---
+
+### compactingActivity()
+
+```ts
+function compactingActivity(trigger?): SessionActivity;
+```
+
+Activity facts for a Session with a compaction running now.
+
+#### Parameters
+
+| Parameter | Type                       | Default value |
+| --------- | -------------------------- | ------------- |
+| `trigger` | `SessionCompactionTrigger` | `"manual"`    |
+
+#### Returns
+
+`SessionActivity`
+
+---
+
+### gardenSlots()
+
+```ts
+function gardenSlots(): SessionExtensionSlots;
+```
+
+The slots a Session that rosters the garden extension reports.
+
+#### Returns
+
+`SessionExtensionSlots`
+
+---
+
+### gardenCall()
+
+```ts
+function gardenCall(command, input): Promise<Json>;
+```
+
+The garden extension's door: one stateless step per call.
+
+#### Parameters
+
+| Parameter | Type     |
+| --------- | -------- |
+| `command` | `string` |
+| `input`   | `Json`   |
+
+#### Returns
+
+`Promise`\<`Json`\>

package/package.json

@@ -1,6 +1,72 @@
 {
   "name": "@fungi.computer/parakeet-testing",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "author": "Levi <levi@technomancy.dev>",
+  "description": "Test-only garden extension and slash-parity fixtures for a typed Shiitake Session, shared by every Parakeet-protocol renderer's tests",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "docs/api",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@fungi.computer/shiitake": "0.2.0",
+    "@fungi.computer/whistle": "0.0.2",
+    "zod": "4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "24.13.3",
+    "typescript": "5.9.3",
+    "vitest": "4.1.11"
+  },
+  "license": "MIT",
+  "botanical": {
+    "role": "package",
+    "operations": {
+      "lint": "required",
+      "typecheck": "required",
+      "build": "required",
+      "test": "required",
+      "docs": "required",
+      "pack": {
+        "status": "not-applicable",
+        "reason": "Test-only fixtures for workspace renderers, like the Parakeet source it was split from; shared pack tooling not yet wired for this package"
+      },
+      "smoke": {
+        "status": "not-applicable",
+        "reason": "No runtime entry point beyond the typed fixtures its own test and consumers exercise"
+      },
+      "stranger": {
+        "status": "not-applicable",
+        "reason": "Shared stranger consumer proof not yet wired for this package, like the Parakeet source it was split from"
+      }
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fungi-computer/parakeet-testing.git"
+  },
+  "scripts": {
+    "lint": "eslint src test --max-warnings=0 && ../../node_modules/.bin/oxlint --config ../../oxlint.config.ts --deny-warnings src test",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "build": "pnpm run clean && tsc -p tsconfig.build.json",
+    "clean": "node --input-type=module --eval \"import { rm } from 'node:fs/promises'; await rm('dist', { recursive: true, force: true });\"",
+    "test": "vitest run",
+    "docs": "tsx ../../tooling/repository/src/docs/cli.ts check --root ../..",
+    "docs:write": "tsx ../../tooling/repository/src/docs/cli.ts write --root ../..",
+    "format:check": "node ../../tooling/repository/scripts/format-package-check.mjs",
+    "lint:anti-slop": "node ../../tooling/repository/scripts/lint-package-anti-slop.mjs"
+  }
 }