@frockbot/plugin-shell 0.3.22 → 0.3.24

package/src/client/applet-building-view.test.ts

@@ -0,0 +1,69 @@
+/**
+ * The building view, as the two surfaces that draw it are written.
+ *
+ * Bun has no single-file-component loader, so a `.vue` file is read as text
+ * here — the same thing `ComputerCard.test.ts` does. It proves the wiring the
+ * unit tests for the projection cannot: that the panel and the phone chip both
+ * read the one projection, and that neither still shows the fixed line it used
+ * to show for the whole of a build.
+ */
+import { describe, expect, test } from "bun:test";
+import { parse } from "@vue/compiler-sfc";
+
+const canvas = await Bun.file(
+  new URL("./AppletCanvas.vue", import.meta.url),
+).text();
+const app = await Bun.file(
+  new URL("./FrockBotApp.vue", import.meta.url),
+).text();
+const styles = await Bun.file(new URL("./styles.css", import.meta.url)).text();
+
+describe("the Applet canvas while the Bot is still building", () => {
+  test("the file parses as a single-file component", () => {
+    expect(parse(canvas).errors).toEqual([]);
+  });
+
+  test("the panel draws the projection rather than a fixed line", () => {
+    expect(canvas).toContain('from "./applet-progress.js"');
+    expect(canvas).toContain('data-testid="applet-canvas-progress"');
+    expect(canvas).toContain("progress.label");
+    expect(canvas).toContain("progress.failure");
+    expect(canvas).toContain("progress.output");
+    // The line the panel used to show for minutes on end, whatever happened.
+    expect(canvas).not.toContain("Not published yet");
+  });
+
+  test("the progress block is announced and is gone once the Applet runs", () => {
+    expect(canvas).toContain('role="status"');
+    expect(canvas).toContain(
+      'v-if="applet && !loading && progress && beingBuilt"',
+    );
+  });
+
+  test("the build output is monospace and cannot grow without bound", () => {
+    expect(canvas).toContain("font-family: var(--frock-font-mono);");
+    expect(canvas).toContain("max-height: 180px;");
+  });
+
+  test("the working dot stops moving where motion is not wanted", () => {
+    expect(canvas).toContain("@media (prefers-reduced-motion: reduce)");
+    expect(canvas).toContain(
+      ".applet-canvas-progress-dot {\n    animation: none;",
+    );
+  });
+});
+
+describe("the phone's way in", () => {
+  test("the chip carries the same line and opens the same panel", () => {
+    expect(app).toContain('from "./applet-progress.js"');
+    expect(app).toContain("appletChipStatus");
+    // The one overlay: the right panel drawer, opened by the one toggle.
+    expect(app).toContain('class="applet-chip"');
+    expect(app).toContain('@click="toggleRightPanel"');
+  });
+
+  test("the chip has room for a second line", () => {
+    expect(styles).toContain(".applet-chip-status {");
+    expect(styles).toContain("min-height: var(--frock-control-md);");
+  });
+});

package/src/client/applet-progress.test.ts

@@ -0,0 +1,300 @@
+import { describe, expect, test } from "bun:test";
+import {
+  APPLET_PROGRESS_OUTPUT_LINES_V1,
+  appletCommandOutputV1,
+  appletIsBeingBuiltV1,
+  appletProgressV1,
+} from "./applet-progress.js";
+import type { WebToolActivity } from "../shared.js";
+
+const draft = {
+  appletId: "u1abc.todo",
+  displayName: "Weekly Todos",
+  status: "draft" as const,
+  tools: [],
+  createdAt: "2026-09-05T00:00:00.000Z",
+};
+const published = {
+  ...draft,
+  status: "published" as const,
+  currentGenerationId: "generation-2",
+};
+
+const sourceOf = (...paths: string[]) => ({
+  appletId: draft.appletId,
+  truncated: false,
+  files: paths.map((path) => ({
+    path,
+    text: "export default class {}",
+    generationId: "w-1",
+    changedAt: "2026-09-05T00:01:00.000Z",
+  })),
+});
+
+function tool(
+  name: string,
+  status: WebToolActivity["status"],
+  extra: Partial<WebToolActivity> = {},
+): WebToolActivity {
+  return { id: `${name}-${status}`, name, status, ...extra };
+}
+
+describe("what the Bot is doing to the focused Applet", () => {
+  test("no Applet is no line at all", () => {
+    expect(appletProgressV1({})).toBeUndefined();
+    expect(appletProgressV1({ applet: null })).toBeUndefined();
+  });
+
+  test("a draft nothing has been said about yet reads as still being built", () => {
+    // The same words the Applets list uses, so the two surfaces agree.
+    expect(appletProgressV1({ applet: draft })).toMatchObject({
+      stage: "unknown",
+      label: "Still being built",
+      working: false,
+    });
+  });
+
+  test("the create call is the first thing worth saying", () => {
+    expect(
+      appletProgressV1({
+        applet: draft,
+        tools: [tool("applets/applet_create", "completed")],
+      })?.stage,
+    ).toBe("created");
+  });
+
+  test("a native tool name counts the same as a namespaced one", () => {
+    expect(
+      appletProgressV1({
+        applet: draft,
+        tools: [tool("applet_create", "running")],
+      }),
+    ).toMatchObject({ stage: "created", working: true });
+  });
+
+  test("source on the Workspace means the Bot has been writing", () => {
+    expect(
+      appletProgressV1({
+        applet: draft,
+        source: sourceOf("server.ts", "ui.tsx"),
+        tools: [tool("applets/applet_create", "completed")],
+      })?.label,
+    ).toBe("Writing the code");
+  });
+
+  test("a check that passed moves the line on and shows what it printed", () => {
+    const progress = appletProgressV1({
+      applet: draft,
+      source: sourceOf("server.ts"),
+      tools: [
+        tool("computer_exec", "completed", {
+          text: "applet check: no problems found",
+        }),
+      ],
+    });
+    expect(progress).toMatchObject({
+      stage: "checking",
+      label: "The code checks out",
+      done: true,
+    });
+    expect(progress?.output).toEqual(["applet check: no problems found"]);
+    expect(progress?.failure).toBeUndefined();
+  });
+
+  test("a check that found errors is a failure in plain words", () => {
+    const progress = appletProgressV1({
+      applet: draft,
+      tools: [
+        tool("computer_exec", "failed", {
+          text: "ui.tsx:3:1 Unexpected any\napplet check: 1 error(s)",
+        }),
+      ],
+    });
+    expect(progress?.stage).toBe("checking");
+    expect(progress?.failure).toBe("The code has problems that need fixing.");
+    expect(progress?.output).toEqual([
+      "ui.tsx:3:1 Unexpected any",
+      "applet check: 1 error(s)",
+    ]);
+  });
+
+  test("a build is recognised by the files it says it wrote", () => {
+    const progress = appletProgressV1({
+      applet: draft,
+      tools: [
+        tool("computer_exec", "completed", {
+          text: [
+            "dist/server.js 0a1b2c3d4e5f",
+            "dist/ui.html f5e4d3c2b1a0",
+            "dist/manifest.json 1 tool(s): add_todo",
+          ].join("\n"),
+        }),
+      ],
+    });
+    expect(progress).toMatchObject({
+      stage: "building",
+      label: "Built and ready to go live",
+      done: true,
+    });
+    expect(progress?.output).toHaveLength(3);
+  });
+
+  test("a shell command that is not the Applet CLI says nothing", () => {
+    expect(
+      appletCommandOutputV1("total 0\ndrwxr-xr-x  2 box box"),
+    ).toBeUndefined();
+    expect(appletCommandOutputV1(undefined)).toBeUndefined();
+    expect(
+      appletProgressV1({
+        applet: draft,
+        source: sourceOf("server.ts"),
+        tools: [tool("computer_exec", "completed", { text: "hello" })],
+      })?.stage,
+    ).toBe("writing");
+  });
+
+  test("a shell command still running is the Bot working, not a new step", () => {
+    const progress = appletProgressV1({
+      applet: draft,
+      source: sourceOf("server.ts"),
+      tools: [tool("computer_exec", "running")],
+    });
+    expect(progress).toMatchObject({ stage: "writing", working: true });
+  });
+
+  test("output is bounded, newest lines kept", () => {
+    const lines = Array.from(
+      { length: 40 },
+      (_, index) => `ui.tsx:${index}:1 problem`,
+    );
+    const progress = appletProgressV1({
+      applet: draft,
+      tools: [
+        tool("computer_exec", "failed", {
+          text: [...lines, "applet check: 40 error(s)"].join("\n"),
+        }),
+      ],
+    });
+    expect(progress?.output).toHaveLength(APPLET_PROGRESS_OUTPUT_LINES_V1);
+    expect(progress?.output?.at(-1)).toBe("applet check: 40 error(s)");
+  });
+
+  test("a very long line is cut rather than allowed to run off the panel", () => {
+    const progress = appletProgressV1({
+      applet: draft,
+      tools: [
+        tool("computer_exec", "failed", {
+          text: `applet check: 1 error(s)\n${"x".repeat(500)}`,
+        }),
+      ],
+    });
+    expect(progress?.output?.at(-1)?.length).toBe(200);
+    expect(progress?.output?.at(-1)?.endsWith("…")).toBe(true);
+  });
+
+  test("a publish in flight is the last step, and clears an earlier complaint", () => {
+    const progress = appletProgressV1({
+      applet: draft,
+      tools: [
+        tool("computer_exec", "failed", { text: "applet check: 2 error(s)" }),
+        tool("applets/applet_publish", "running", {
+          input: { appletId: draft.appletId },
+        }),
+      ],
+    });
+    expect(progress).toMatchObject({
+      stage: "publishing",
+      label: "Getting it ready to open",
+      working: true,
+    });
+    expect(progress?.failure).toBeUndefined();
+  });
+
+  test("a publish that was refused says why, in the words it was refused with", () => {
+    const progress = appletProgressV1({
+      applet: draft,
+      tools: [
+        tool("applets/applet_publish", "failed", {
+          input: { appletId: draft.appletId },
+          text: 'Publishing u1abc.todo failed: "add_todo" is already a tool of "Shopping"',
+        }),
+      ],
+    });
+    expect(progress?.stage).toBe("publishing");
+    expect(progress?.failure).toBe(
+      'Publishing u1abc.todo failed: "add_todo" is already a tool of "Shopping"',
+    );
+  });
+
+  test("a publish of another Applet never moves this one's line", () => {
+    expect(
+      appletProgressV1({
+        applet: draft,
+        tools: [
+          tool("applets/applet_publish", "running", {
+            input: { appletId: "u1abc.other" },
+          }),
+        ],
+      })?.stage,
+    ).toBe("unknown");
+  });
+
+  test("a live Applet is ready, and the canvas stops showing progress", () => {
+    const progress = appletProgressV1({ applet: published });
+    expect(progress).toMatchObject({
+      stage: "published",
+      label: "Ready to use",
+      done: true,
+    });
+    expect(appletIsBeingBuiltV1(progress)).toBe(false);
+    expect(appletIsBeingBuiltV1(appletProgressV1({ applet: draft }))).toBe(
+      true,
+    );
+    expect(appletIsBeingBuiltV1(undefined)).toBe(false);
+  });
+
+  test("a step still going never claims it finished", () => {
+    const progress = appletProgressV1({
+      applet: draft,
+      tools: [
+        tool("computer_exec", "completed", {
+          text: "applet check: no problems found",
+        }),
+        tool("computer_exec", "running"),
+      ],
+    });
+    expect(progress).toMatchObject({ done: false, working: true });
+    expect(progress?.label).toBe("Checking the code");
+  });
+
+  test("a Turn still running says so even when no Applet tool has been called", () => {
+    expect(appletProgressV1({ applet: draft, running: true })?.working).toBe(
+      true,
+    );
+  });
+
+  test("the outcome the Applet authority recorded is used when it has one", () => {
+    const progress = appletProgressV1({
+      applet: draft,
+      build: {
+        status: "failed",
+        command: "build",
+        summary: "dist/manifest.json is invalid",
+        diagnostics: ["hashes.server must be a sha-256 hex digest"],
+      },
+    });
+    expect(progress).toMatchObject({
+      stage: "building",
+      failure: "dist/manifest.json is invalid",
+    });
+    expect(progress?.output).toEqual([
+      "hashes.server must be a sha-256 hex digest",
+    ]);
+  });
+
+  test("an unknown recorded outcome is not a step that happened", () => {
+    expect(
+      appletProgressV1({ applet: draft, build: { status: "unknown" } })?.stage,
+    ).toBe("unknown");
+  });
+});

package/src/client/applet-progress.ts

@@ -0,0 +1,339 @@
+/**
+ * What the Bot is doing to the focused Applet, in words a person reads.
+ *
+ * Building an Applet takes minutes: the Bot scaffolds it, edits the files on
+ * the Computer, runs `applet check` and `applet build` there, and only then
+ * publishes it. Until that publish lands there is nothing to run, so the
+ * canvas beside the conversation used to say "Not published yet" for the whole
+ * of it — true, unchanging, and no help to somebody watching. This module is
+ * the missing sentence: it reads what the client already knows and returns the
+ * one line that says where the work has got to.
+ *
+ * It is a projection, never an authority. Nothing here is stored, nothing here
+ * is asked of the backend, and every input is something the thread was already
+ * drawing. When the signals say nothing specific, the answer is the honest
+ * fallback rather than an invented step.
+ */
+import type {
+  AppletBuildViewV1,
+  AppletSourceViewV1,
+  AppletSummaryV1,
+} from "@frockbot/kernel-contracts";
+import type { WebChatMessage, WebToolActivity } from "../shared.js";
+
+/**
+ * Where the work has got to.
+ *
+ * The order is the order the Bot does them in, and the projection takes the
+ * furthest one it has evidence for. `unknown` is a draft with nothing said
+ * about it yet — the Bot has been asked, and the Turn that answers has not
+ * reached the Applet.
+ */
+export type AppletProgressStageV1 =
+  | "unknown"
+  | "created"
+  | "writing"
+  | "checking"
+  | "building"
+  | "publishing"
+  | "published";
+
+/** The tail of a check or a build, so a long log never fills the panel. */
+export const APPLET_PROGRESS_OUTPUT_LINES_V1 = 12;
+export const APPLET_PROGRESS_LINE_CHARACTERS_V1 = 200;
+/** A failure is a sentence in the panel, not a wall of text. */
+export const APPLET_PROGRESS_FAILURE_CHARACTERS_V1 = 400;
+
+export interface AppletProgressV1 {
+  stage: AppletProgressStageV1;
+  /** The line the canvas and the phone both show. */
+  label: string;
+  /** True while the Turn doing this is still going. */
+  working: boolean;
+  /** True when this step finished and finished cleanly. */
+  done: boolean;
+  /** What went wrong, in the words of whatever refused. */
+  failure?: string;
+  /** The last lines the check or the build printed. */
+  output?: string[];
+}
+
+export interface AppletProgressInputV1 {
+  /** The focused Applet's directory entry, when there is one. */
+  applet?: AppletSummaryV1 | null;
+  /** The Applet's source, as the canvas already reads it. */
+  source?: AppletSourceViewV1;
+  /** The outcome the Applet authority recorded, when it has recorded one. */
+  build?: AppletBuildViewV1;
+  /** The newest Turn's tool activity, oldest first. */
+  tools?: readonly WebToolActivity[];
+  /** True while that Turn is still running. */
+  running?: boolean;
+}
+
+/**
+ * The words for each step, and for the step having finished.
+ *
+ * A check that has come back clean is worth its own sentence: "Checking the
+ * code" would keep saying a thing was happening after it stopped happening.
+ */
+const LABELS: Record<AppletProgressStageV1, { doing: string; done: string }> = {
+  // Matches the Applets list, which says "Still being built" for a draft.
+  unknown: { doing: "Still being built", done: "Still being built" },
+  created: { doing: "Just getting started", done: "Just getting started" },
+  writing: { doing: "Writing the code", done: "Writing the code" },
+  checking: { doing: "Checking the code", done: "The code checks out" },
+  building: {
+    doing: "Putting it together",
+    done: "Built and ready to go live",
+  },
+  publishing: {
+    doing: "Getting it ready to open",
+    done: "Getting it ready to open",
+  },
+  published: { doing: "Ready to use", done: "Ready to use" },
+};
+
+const ORDER: AppletProgressStageV1[] = [
+  "unknown",
+  "created",
+  "writing",
+  "checking",
+  "building",
+  "publishing",
+  "published",
+];
+
+function furthest(
+  left: AppletProgressStageV1,
+  right: AppletProgressStageV1,
+): AppletProgressStageV1 {
+  return ORDER.indexOf(right) > ORDER.indexOf(left) ? right : left;
+}
+
+/** The bare tool name, whether it arrived namespaced or native. */
+function toolName(activity: WebToolActivity): string {
+  const slash = activity.name.lastIndexOf("/");
+  return slash < 0 ? activity.name : activity.name.slice(slash + 1);
+}
+
+/**
+ * Whether this tool call is about the Applet in the canvas.
+ *
+ * A dynamic call carries its parsed arguments, so a publish of some other
+ * Applet never moves this one's line. `applet_create` names no id — it is
+ * making one — so it counts for whichever Applet the Session then focuses,
+ * which is the one it just created.
+ */
+function namesApplet(activity: WebToolActivity, appletId: string): boolean {
+  const input = activity.input;
+  if (!input || typeof input !== "object" || Array.isArray(input)) return true;
+  const named = (input as Record<string, unknown>).appletId;
+  return typeof named === "string" ? named === appletId : true;
+}
+
+function trimLine(line: string): string {
+  return line.length > APPLET_PROGRESS_LINE_CHARACTERS_V1
+    ? `${line.slice(0, APPLET_PROGRESS_LINE_CHARACTERS_V1 - 1)}…`
+    : line;
+}
+
+function tail(text: string): string[] {
+  const lines = text
+    .split("\n")
+    .map((line) => line.trimEnd())
+    .filter((line) => line.length > 0);
+  return lines.slice(-APPLET_PROGRESS_OUTPUT_LINES_V1).map(trimLine);
+}
+
+function sentence(text: string): string {
+  const trimmed = text.trim();
+  if (trimmed.length === 0) return "";
+  return trimmed.length > APPLET_PROGRESS_FAILURE_CHARACTERS_V1
+    ? `${trimmed.slice(0, APPLET_PROGRESS_FAILURE_CHARACTERS_V1 - 1)}…`
+    : trimmed;
+}
+
+/**
+ * Whether a shell command's output is the `applet` CLI reporting on itself.
+ *
+ * The client is never told what a `computer_exec` ran: the Turn projection
+ * carries the input of dynamic tool calls only, and `computer_exec` is a
+ * native tool. What it does carry is the result, and the CLI's output is a
+ * stated contract — `applet check:` on one line, and the three `dist/` paths a
+ * build writes — so recognising it is reading a published shape rather than
+ * guessing at a command. Anything else the Bot ran on the Computer looks like
+ * nothing here and is ignored, which is the right failure: no line rather than
+ * a wrong one.
+ */
+export function appletCommandOutputV1(
+  text: string | undefined,
+): { command: "check" | "build"; output: string[] } | undefined {
+  if (!text) return undefined;
+  if (/^applet check:/m.test(text)) {
+    return { command: "check", output: tail(text) };
+  }
+  if (/dist\/manifest\.json\b/.test(text) && /dist\/server\.js\b/.test(text)) {
+    return { command: "build", output: tail(text) };
+  }
+  return undefined;
+}
+
+/** Whether the `applet check` output the CLI printed found errors. */
+function checkFailed(text: string): boolean {
+  return /^applet check: \d+ error/m.test(text);
+}
+
+/**
+ * The one line about the focused Applet, and what sits under it.
+ *
+ * Returns `undefined` when there is no Applet in the canvas to say it about.
+ */
+export function appletProgressV1(
+  input: AppletProgressInputV1,
+): AppletProgressV1 | undefined {
+  const applet = input.applet;
+  if (!applet) return undefined;
+
+  let stage: AppletProgressStageV1 = "unknown";
+  let failure: string | undefined;
+  let output: string[] | undefined;
+  let done = false;
+
+  // The directory entry is the settled fact: a generation is current, so the
+  // Applet runs. A Turn working on it now moves the line off this again.
+  if (applet.currentGenerationId) {
+    stage = "published";
+    done = true;
+  }
+
+  // What the Applet authority recorded, where it has recorded anything. It is
+  // read before the Turn's own evidence so a running Turn wins.
+  const recorded = input.build;
+  if (recorded && recorded.status !== "unknown") {
+    stage = furthest(
+      stage,
+      recorded.command === "build" ? "building" : "checking",
+    );
+    done = recorded.status === "passed";
+    if (recorded.status === "failed") {
+      failure = sentence(recorded.summary ?? "The last check did not pass.");
+      if (recorded.diagnostics && recorded.diagnostics.length > 0) {
+        output = recorded.diagnostics
+          .slice(-APPLET_PROGRESS_OUTPUT_LINES_V1)
+          .map(trimLine);
+      }
+    }
+  }
+
+  // Source on the Workspace means the Bot has written files, whether or not
+  // this Turn is the one that wrote them.
+  if ((input.source?.files.length ?? 0) > 0) stage = furthest(stage, "writing");
+
+  let working = false;
+  for (const activity of input.tools ?? []) {
+    const name = toolName(activity);
+    if (name === "computer_exec") {
+      const ran = appletCommandOutputV1(activity.text);
+      if (activity.status === "running") {
+        // A shell command in flight during a build is the Bot working on the
+        // Applet; which command it is only becomes knowable when it returns.
+        working = true;
+        done = false;
+        continue;
+      }
+      if (!ran) continue;
+      stage = furthest(
+        stage,
+        ran.command === "build" ? "building" : "checking",
+      );
+      output = ran.output;
+      const wrong =
+        activity.status === "failed" ||
+        (ran.command === "check" && checkFailed(activity.text ?? ""));
+      failure = wrong
+        ? ran.command === "build"
+          ? "Putting it together did not work."
+          : "The code has problems that need fixing."
+        : undefined;
+      done = !wrong;
+      continue;
+    }
+    if (!namesApplet(activity, applet.appletId)) continue;
+    if (name === "applet_create") {
+      stage = furthest(stage, "created");
+      if (activity.status === "running") {
+        working = true;
+        done = false;
+      } else if (activity.status === "failed") {
+        failure = sentence(activity.text ?? "This Applet could not be made.");
+        done = false;
+      } else done = true;
+      continue;
+    }
+    if (name === "applet_publish") {
+      if (activity.status === "running") {
+        stage = furthest(stage, "publishing");
+        working = true;
+        failure = undefined;
+        done = false;
+        continue;
+      }
+      if (activity.status === "failed") {
+        stage = furthest(stage, "publishing");
+        failure = sentence(
+          activity.text ?? "It could not be made ready to open.",
+        );
+        done = false;
+        continue;
+      }
+      stage = furthest(stage, "published");
+      failure = undefined;
+      done = true;
+      continue;
+    }
+  }
+
+  if (input.running) working = true;
+
+  return {
+    stage,
+    label: done ? LABELS[stage].done : LABELS[stage].doing,
+    working,
+    done,
+    ...(failure ? { failure } : {}),
+    ...(output && output.length > 0 ? { output } : {}),
+  };
+}
+
+/**
+ * The tool activity the line is read from: every Turn's, oldest first.
+ *
+ * Not just the Turn that is running. Building an Applet takes several Turns —
+ * the Bot writes, checks, fixes, builds, publishes, and the User says things
+ * in between — and the last thing that happened to the Applet is what a person
+ * wants to know, whether or not it happened in the Turn still open. The
+ * reducer takes the last relevant activity, so a settled failure stays on
+ * screen until something newer replaces it.
+ */
+export function appletProgressToolsV1(
+  messages: readonly Pick<WebChatMessage, "role" | "tools">[],
+): WebToolActivity[] {
+  const tools: WebToolActivity[] = [];
+  for (const message of messages) {
+    if (message.role !== "assistant") continue;
+    tools.push(...message.tools);
+  }
+  return tools;
+}
+
+/**
+ * Whether the canvas should be showing the building view rather than the
+ * Applet. A published Applet with a Turn working on it keeps showing what it
+ * has: replacing a working Applet with a progress line takes something away.
+ */
+export function appletIsBeingBuiltV1(
+  progress: AppletProgressV1 | undefined,
+): boolean {
+  return Boolean(progress && progress.stage !== "published");
+}