@fungi.computer/inkcap 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,107 @@
-# Temporary Holding Version
+# Inkcap (`@fungi.computer/inkcap`)
 
-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.
+Inkcap edits the files on your Computer: a file explorer, tabs and a code editor
+in the browser.
+
+![Inkcap with the koi-pond project open in the explorer and src/fish.ts in the editor beside README.md](docs/media/editor.png)
+
+Inkcap is one of the starter Apps of
+[Oyster](https://github.com/fungi-computer/oyster), the open App host that runs
+on your own Cloudflare account. On Oyster, the Computer is a Linux workspace in
+a Cloudflare Container, and Inkcap reads and writes its `/workspace`.
+
+## What you can do
+
+- Browse the Computer's folders and open files in tabs.
+- Edit text with syntax highlighting, and save with **Ctrl+S** / **⌘S**.
+- Preview images (PNG, JPEG, GIF, WebP, SVG and AVIF) and video (MP4 and WebM).
+- Turn on **Preview Markdown** for any `.md` file.
+- Create files and folders, **Save file as** another path, or download a draft
+  without writing it.
+- Resolve conflicts: when a file changed on the Computer after you opened it,
+  choose **Keep mine**, **Reload theirs** or **Compare** before anything is
+  overwritten.
+
+Closing a tab or the App with unsaved edits asks whether to save, discard or
+cancel. On a phone, **Open file explorer** brings the explorer over the editor.
+
+<img alt="Inkcap on a phone in the light theme, with no file open and a New draft button" src="docs/media/new-draft-phone.png" width="300">
+
+## Get it
+
+Inkcap installs with the other starter Apps. On a deployed Oyster (see the
+[Oyster quick start](https://github.com/fungi-computer/oyster#quick-start-deploy-your-own-oyster)),
+run:
+
+```sh
+export OYSTER_URL=https://oyster.<your-subdomain>.workers.dev
+export OYSTER_OWNER_KEY=<your owner key>
+npx oyster install-apps
+```
+
+The installer clones this repository and the six others, seeds each on your
+Oyster with `git push`, builds them on your Computer and installs them. Sign in
+at `$OYSTER_URL/login` with the owner key and open Inkcap from the Tourtois
+desktop. Run `install-apps` again to update; each App keeps its data.
+
+## Change it
+
+Every installed App is also a template you can fork on your own Oyster. Fork
+Inkcap into a Bonsai repository and clone it with ordinary `git`:
+
+```sh
+curl -X POST -H "Authorization: Bearer $OYSTER_OWNER_KEY" -H 'content-type: application/json' \
+  -d '{"appId":"app_inkcap","name":"my-inkcap"}' \
+  $OYSTER_URL/apps/bonsai/methods/apps.fork
+git -c http.extraHeader="Authorization: Bearer $OYSTER_OWNER_KEY" \
+  clone $OYSTER_URL/git/bonsai/my-inkcap.git
+```
+
+The reply names your fork's App id and repository. Push your edits, open the
+repository in Bonsai and choose **Settings**, then **Build & install** with that
+App id and your commit as `git:<sha>`. Install the Release at `inkcap` to
+replace the running Inkcap, or at a new id to keep both.
+
+To work from GitHub instead, fork this repository and point the installer at
+your forks with `--repositories <base URL>` and `--ref <branch or tag>`. The
+installer reads all seven starter Apps from that base, so fork them under one
+account.
+
+## Agent tools
+
+Agents call Inkcap through Oyster's MCP endpoint, or at
+`POST $OYSTER_URL/apps/inkcap/methods/<name>` with a key; see
+[Git, keys and MCP](https://github.com/fungi-computer/oyster#git-keys-and-mcp).
+
+| Method                                         | What it does                                                                  |
+| ---------------------------------------------- | ----------------------------------------------------------------------------- |
+| `listFiles({path?, limit?, offset?})`          | Reads one page of a directory, up to 256 entries.                             |
+| `readFile({path, byteOffset?, byteLength?})`   | Reads up to 128 KiB of a file as base64.                                      |
+| `writeFile({path, content, expectedContent?})` | Writes UTF-8 text, optionally only if the file still holds `expectedContent`. |
+| `documents.recent`                             | Lists the documents most recently opened and edited in Inkcap.                |
+
+Paths are absolute and cannot contain `..`. A read-only attachment cannot write,
+and the host picks the Computer: no argument selects one.
+
+## Build and check
+
+Inkcap is a React App built with Vite. The file tree and editor come from
+`@pierre/trees` and `@pierre/diffs`, and the controls from
+[Caps](https://github.com/fungi-computer/caps).
+
+```sh
+pnpm install
+pnpm build
+pnpm typecheck
+pnpm test
+```
+
+[src/InkcapApp.tsx](src/InkcapApp.tsx) owns the tabs, the selected Computer and
+the close checks. [src/useFileDocument.ts](src/useFileDocument.ts) owns each
+draft, its saved baseline and conflict recovery. The agent tools are in
+[backend/methods.ts](backend/methods.ts), and [package.json](package.json)
+declares the permissions the App asks for.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/backend/document-activity.ts

@@ -0,0 +1,77 @@
+import * as z from "zod";
+import {
+  documentActivitySchema,
+  documentIds,
+  documentsRecentSchema,
+} from "../src/document-activity-contract.js";
+import {
+  createReadCopies,
+  type ReadCopySql,
+} from "@fungi.computer/agar/read-copy";
+
+/** Bounded owner SQLite rows for each actor's recent Computer documents. */
+export type DocumentActivityStore = ReturnType<typeof createReadCopies>;
+export function createDocumentActivityStore(
+  sql: ReadCopySql,
+): DocumentActivityStore {
+  return createReadCopies(sql, {
+    version: 1,
+    maxRows: 256,
+    // One row holds up to 100 entries whose paths reach 4,096 characters.
+    maxValueBytes: 4 * 1024 * 1024,
+    // Activity rows store no blobs; the store's grammar requires positive bounds.
+    maxBlobBytes: 1,
+    maxBlobTotalBytes: 1,
+  });
+}
+
+const stateSchema = z.strictObject({
+  sequence: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER),
+  rows: z.array(documentActivitySchema).max(100),
+});
+/** Member/Agent/key identity is supplied only by the admitting host. */
+export function documentActivity(
+  activity: DocumentActivityStore,
+  actorId: string,
+  computerId: string,
+) {
+  const store = activity.open("document-activity-v1", stateSchema);
+  const key = JSON.stringify([actorId, computerId]);
+  function state() {
+    const saved = store.read(key);
+    return saved.kind === "ready" ? saved.value : { sequence: 0, rows: [] };
+  }
+  return {
+    record(path: string, activity: "opened" | "edited") {
+      const previous = state();
+      const row = documentActivitySchema.parse({
+        id:
+          previous.rows.find((item) => item.path === path)?.id ??
+          documentIds.document.generate(),
+        computerId,
+        path,
+        activity,
+        occurredAt: Date.now(),
+        sequence: previous.sequence + 1,
+      });
+      store.write(key, null, {
+        sequence: row.sequence,
+        rows: [
+          row,
+          ...previous.rows.filter((item) => item.path !== path),
+        ].slice(0, 100),
+      });
+      return row.sequence;
+    },
+    recent(limit: number, after?: { before: number }) {
+      const rows = state().rows.filter(
+        (row) => after === undefined || row.sequence < after.before,
+      );
+      const page = rows.slice(0, limit);
+      return documentsRecentSchema.parse({
+        rows: page,
+        next: rows.length > limit ? { before: page.at(-1)?.sequence } : null,
+      });
+    },
+  };
+}

package/backend/documents-changed.ts

@@ -0,0 +1,31 @@
+import * as S from "effect/Schema";
+import {
+  AppStorageError,
+  appStorageReadResultSchema,
+  appStorageMutationResultSchema,
+  type AppStorageWire,
+} from "@fungi.computer/agar/storage";
+import { documentsChangedKey } from "../src/document-activity-contract.js";
+
+/** Publish a scoped invalidation only after the real activity row was saved. */
+export async function markDocumentsChanged(
+  storage: Pick<AppStorageWire, "read" | "write">,
+  computerId: string,
+  sequence: number,
+) {
+  const current = S.decodeUnknownSync(appStorageReadResultSchema, {
+    onExcessProperty: "error",
+  })(await storage.read(documentsChangedKey));
+  if (current.kind === "rejected") throw new AppStorageError(current.code);
+  const result = S.decodeUnknownSync(appStorageMutationResultSchema, {
+    onExcessProperty: "error",
+  })(
+    await storage.write({
+      key: documentsChangedKey,
+      scope: "member",
+      basedOn: current.value.member?.revision ?? null,
+      value: { computerId, sequence },
+    }),
+  );
+  if (result.kind === "rejected") throw new AppStorageError(result.code);
+}

package/backend/gills.ts

@@ -0,0 +1,55 @@
+import { defineAppGill, type AppBackendGill } from "@fungi.computer/agar/gills";
+import {
+  documentActivityRefusalSchema,
+  documentsChangedKey,
+  documentsRecentInputSchema,
+  documentsRecentSchema,
+} from "../src/document-activity-contract.js";
+
+/** The source pages saved actor/Computer activity; rendering never probes files. */
+export const recentFilesGill = defineAppGill({
+  id: "recent-files",
+  title: "Recent Files",
+  source: "documents.recent",
+  limit: 10,
+  sizes: ["M", "L"],
+  params: [
+    { key: "computer", label: "Computer", kind: "computer", required: true },
+  ],
+  watch: { storage: documentsChangedKey },
+  input: ({ limit, after }): ReturnType<AppBackendGill["input"]> => {
+    const cursor: unknown = after === undefined ? undefined : JSON.parse(after);
+    const input = documentsRecentInputSchema.parse(
+      cursor === undefined ? { limit } : { limit, after: cursor },
+    );
+    return input.after === undefined
+      ? { limit: input.limit }
+      : { limit: input.limit, after: input.after };
+  },
+  rows: (output) => {
+    const identity = { viewId: "recent-files", title: "Recent Files" };
+    if (documentActivityRefusalSchema.safeParse(output).success)
+      return {
+        ...identity,
+        state: "error",
+        rows: [],
+        error: "Choose a Computer and allow Inkcap to read its files.",
+        recovery: { kind: "configure", param: "computer" },
+      };
+    const page = documentsRecentSchema.parse(output);
+    if (page.rows.length === 0)
+      return { ...identity, state: "empty", rows: [] };
+    const rows = page.rows.map((record) => {
+      const name = record.path.split("/").at(-1);
+      return {
+        id: record.id,
+        title: name === undefined || name.length === 0 ? record.path : name,
+        detail: `${record.activity === "edited" ? "Edited" : "Opened"} · ${record.path}`,
+        open: { params: [{ key: "path", value: record.path }] },
+      };
+    });
+    return page.next === null
+      ? { ...identity, state: "full", rows }
+      : { ...identity, state: "full", rows, next: JSON.stringify(page.next) };
+  },
+});

package/backend/index.ts

@@ -0,0 +1,52 @@
+import { markDocumentsChanged } from "./documents-changed.js";
+import * as Redacted from "effect/Redacted";
+import { DurableObject } from "cloudflare:workers";
+import * as z from "zod";
+import {
+  appBackendActorHeader,
+  appBackendComputerHeader,
+} from "@fungi.computer/agar/backend";
+import { createDocumentActivityStore } from "./document-activity.js";
+import { appBackend, type InkcapBackendContext } from "./methods.js";
+
+const requestSchema = z.strictObject({
+  method: z.enum(["documents.opened", "documents.edited", "documents.recent"]),
+  input: z.json(),
+});
+class InkcapFacet extends DurableObject<InkcapBackendContext["env"]> {
+  declare public readonly env: InkcapBackendContext["env"];
+  readonly activity;
+  constructor(ctx: DurableObjectState, env: InkcapBackendContext["env"]) {
+    super(ctx, env);
+    this.activity = createDocumentActivityStore(ctx.storage.sql);
+  }
+  readonly documentsChanged = (
+    computerId: string,
+    sequence: number,
+  ): Promise<void> =>
+    markDocumentsChanged(this.env.APP_STORAGE, computerId, sequence);
+  override async fetch(request: Request): Promise<Response> {
+    if (request.method !== "PUT")
+      return new Response(null, { status: 405, headers: { Allow: "PUT" } });
+    const memberId = request.headers.get(appBackendActorHeader);
+    if (!memberId)
+      return Response.json({ error: "App actor unavailable" }, { status: 403 });
+    try {
+      const input = requestSchema.parse(await request.json());
+      return Response.json(
+        await appBackend.call(input.method, input.input, this, {
+          actor: { kind: "member", memberId },
+          computerId: request.headers.get(appBackendComputerHeader),
+        }),
+      );
+    } catch (cause) {
+      console.error("Inkcap action failed", Redacted.make(cause));
+      // Never reflect provider errors, remote addresses or headers into the UI.
+      return Response.json(
+        { error: "Inkcap could not complete this action" },
+        { status: 400 },
+      );
+    }
+  }
+}
+export const Inkcap = appBackend.implement(InkcapFacet);

package/backend/methods.ts

@@ -0,0 +1,216 @@
+import { resultRows } from "@fungi.computer/agar/method-presentation";
+import { recentFilesGill } from "./gills.js";
+import {
+  documentIdentitySchema,
+  documentsRecentInputSchema,
+  documentsRecentSchema,
+  documentRecordedSchema,
+  documentActivityRefusalSchema,
+} from "../src/document-activity-contract.js";
+import {
+  documentActivity,
+  type DocumentActivityStore,
+} from "./document-activity.js";
+import * as z from "zod";
+import { filesNavigateIntent } from "@fungi.computer/agar/roles/files";
+import type { AppMethodCallContext } from "@fungi.computer/puffball/app-method-runtime";
+import {
+  defineAppBackend,
+  defineAppMethod,
+} from "@fungi.computer/agar/backend-definition";
+import type { WhistleJsonValue } from "@fungi.computer/whistle";
+import type { AppStorageWire } from "@fungi.computer/agar/storage";
+import {
+  pathSchema,
+  listInputSchema,
+  listOutputSchema,
+  readBytesInputSchema,
+  writeOutputSchema,
+} from "@fungi.computer/computer/operations";
+export type InkcapBackendContext = {
+  activity: DocumentActivityStore;
+  documentsChanged(computerId: string, sequence: number): Promise<void>;
+  env: {
+    APP_STORAGE: Pick<AppStorageWire, "read" | "write">;
+    COMPUTER?: {
+      list?(input: z.output<typeof listInput>): Promise<WhistleJsonValue>;
+      read?(input: z.output<typeof readInput>): Promise<WhistleJsonValue>;
+      write?(input: z.output<typeof writeInput>): Promise<WhistleJsonValue>;
+    };
+  };
+};
+const computerPath = pathSchema.refine(
+  (value) => !value.split("/").includes(".."),
+  "Parent path segments are not allowed",
+);
+const listInput = listInputSchema.extend({ path: computerPath.default("/") });
+const readInput = readBytesInputSchema.extend({
+  path: computerPath,
+  byteOffset: z
+    .number()
+    .int()
+    .nonnegative()
+    .max(Number.MAX_SAFE_INTEGER)
+    .default(0),
+  byteLength: z
+    .number()
+    .int()
+    .min(1)
+    .max(128 * 1024)
+    .default(128 * 1024),
+});
+const text = z.string().max(48 * 1024);
+const writeInput = z
+  .strictObject({
+    path: computerPath,
+    content: text,
+    expectedContent: text.optional(),
+  })
+  .refine(
+    (value) =>
+      new TextEncoder().encode(value.content).byteLength +
+        new TextEncoder().encode(value.expectedContent ?? "").byteLength <=
+      48 * 1024,
+    "Combined content exceeds 48 KiB",
+  );
+const readOutput = z.strictObject({
+  path: computerPath,
+  byteOffset: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER),
+  content: z.base64().max(174764),
+  encoding: z.literal("base64"),
+  truncated: z.boolean(),
+});
+const refusal = z.union([
+  z.strictObject({
+    error: z.enum([
+      "not_granted",
+      "revoked",
+      "grantor_lost_authority",
+      "unavailable",
+      "invalid",
+      "invalid_path",
+      "too_large",
+      "conflict",
+      "not_found",
+    ]),
+  }),
+  z.strictObject({
+    error: z.literal("attachment_budget_exceeded"),
+    kind: z.literal("write"),
+    retryAfterMs: z.number().int().min(1).max(86400000),
+  }),
+]);
+const listReply = z.union([listOutputSchema, refusal]);
+const readReply = z.union([readOutput, refusal]);
+const writeReply = z.union([writeOutputSchema, refusal]);
+async function recordDocument(
+  input: z.output<typeof documentIdentitySchema>,
+  context: InkcapBackendContext,
+  caller: AppMethodCallContext,
+  activity: "opened" | "edited",
+) {
+  if (caller.computerId === null || caller.computerId !== input.computerId)
+    return { error: "not_granted" as const };
+  const sequence = documentActivity(
+    context.activity,
+    JSON.stringify(caller.actor),
+    caller.computerId,
+  ).record(input.path, activity);
+  await context.documentsChanged(caller.computerId, sequence);
+  return { recorded: true as const };
+}
+export const appBackend = defineAppBackend({
+  gills: [recentFilesGill],
+  methods: {
+    "documents.opened": defineAppMethod({
+      description: "Record a successfully opened foreground Computer document",
+      effect: "write",
+      requires: ["computer.readFile", "app.storage"],
+      input: documentIdentitySchema,
+      output: z.union([documentRecordedSchema, documentActivityRefusalSchema]),
+      handler: (input, context: InkcapBackendContext, caller) =>
+        recordDocument(input, context, caller, "opened"),
+    }),
+    "documents.edited": defineAppMethod({
+      description: "Record an accepted Computer document save",
+      effect: "write",
+      requires: ["computer.writeFile", "app.storage"],
+      input: documentIdentitySchema,
+      output: z.union([documentRecordedSchema, documentActivityRefusalSchema]),
+      handler: (input, context: InkcapBackendContext, caller) =>
+        recordDocument(input, context, caller, "edited"),
+    }),
+    "documents.recent": defineAppMethod({
+      description:
+        "Read one saved recent-documents page for the actor and admitted Computer; no provider calls",
+      effect: "read",
+      requires: ["computer.readFile"],
+      input: documentsRecentInputSchema,
+      output: z.union([documentsRecentSchema, documentActivityRefusalSchema]),
+      handler: (input, context: InkcapBackendContext, caller) =>
+        caller.computerId === null
+          ? { error: "not_granted" as const }
+          : documentActivity(
+              context.activity,
+              JSON.stringify(caller.actor),
+              caller.computerId,
+            ).recent(input.limit, input.after),
+    }),
+    listFiles: defineAppMethod({
+      description:
+        "List one bounded directory page on the attached Computer. Continue with nextOffset; no Computer selector is accepted.",
+      effect: "read",
+      requires: ["computer.list"],
+      input: listInput,
+      output: listReply,
+      handler: async (input, context: InkcapBackendContext, caller) =>
+        caller.computerId === null || !context.env.COMPUTER?.list
+          ? refusal.parse({ error: "not_granted" })
+          : listReply.parse(await context.env.COMPUTER.list(input)),
+    }),
+    readFile: defineAppMethod({
+      description:
+        "Read up to 128 KiB of a file on the attached Computer as base64. Use byteOffset for the next chunk.",
+      effect: "read",
+      requires: ["computer.readFile"],
+      input: readInput,
+      output: readReply,
+      handler: async (input, context: InkcapBackendContext, caller) =>
+        caller.computerId === null || !context.env.COMPUTER?.read
+          ? refusal.parse({ error: "not_granted" })
+          : readReply.parse(await context.env.COMPUTER.read(input)),
+    }),
+    writeFile: defineAppMethod({
+      description:
+        "Write UTF-8 text on the attached Computer. Supply expectedContent for a compare-and-swap; combined content is limited to 48 KiB. The host owns attribution and the attachment write budget.",
+      effect: "write",
+      requires: ["computer.writeFile"],
+      input: writeInput,
+      output: writeReply,
+      present: {
+        rows: resultRows,
+        verb: "wrote",
+        row: ({ output }) =>
+          "error" in output
+            ? {
+                id: "refused",
+                title: "Inkcap could not write the file",
+                detail: output.error,
+                tone: "error",
+              }
+            : {
+                id: output.path,
+                title: `Inkcap wrote ${output.path.split("/").at(-1) ?? output.path}`,
+                detail: `${output.path} · ${String(output.bytes)} bytes`,
+                open: {
+                  params: filesNavigateIntent({ path: output.path }).params,
+                },
+              },
+      },
+      handler: async (input, context: InkcapBackendContext, caller) =>
+        caller.computerId === null || !context.env.COMPUTER?.write
+          ? refusal.parse({ error: "not_granted" })
+          : writeReply.parse(await context.env.COMPUTER.write(input)),
+    }),
+  },
+});

package/backend/test/cloudflare-workers.fixture.ts

@@ -0,0 +1 @@
+export { DurableObject } from "../../../../packages/shiitake/test/fixtures/cloudflare-workers.fixture.js";