@fungi.computer/nacre 0.0.0-stage → 0.0.2

package/docs/api/README.md

@@ -0,0 +1,21 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+**@fungi.computer/nacre**
+
+---
+
+# @fungi.computer/nacre
+
+## Modules
+
+| Module                                        | Description |
+| --------------------------------------------- | ----------- |
+| [app-directory](app-directory.md)             | -           |
+| [command-host](command-host.md)               | -           |
+| [commands](commands.md)                       | -           |
+| [index](index.md)                             | -           |
+| [keys](keys.md)                               | -           |
+| [shell-module](shell-module.md)               | -           |
+| [window-manager](window-manager.md)           | -           |
+| [workbench-directory](workbench-directory.md) | -           |
+| [workbench](workbench.md)                     | -           |

package/docs/api/app-directory.md

@@ -0,0 +1,587 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/nacre**](README.md)
+
+---
+
+[@fungi.computer/nacre](README.md) / app-directory
+
+# app-directory
+
+## Type Aliases
+
+### AppAddress
+
+```ts
+type AppAddress = z.output<typeof appAddressSchema>;
+```
+
+Decoded address of a default App or an installation.
+
+---
+
+### AppAuthorityEnforcement
+
+```ts
+type AppAuthorityEnforcement = z.output<typeof appAuthorityEnforcementSchema>;
+```
+
+A host-reported authority change and its remaining work.
+
+---
+
+### AppDirectoryGill
+
+```ts
+type AppDirectoryGill = {
+  [
+    Field in keyof Schema.Schema.Type<typeof appDeclaredGillSchema>
+  ]: Schema.Schema.Type<typeof appDeclaredGillSchema>[Field];
+};
+```
+
+A Release-declared Gill carried by the host's App directory. The named mapped
+type keeps consumer declarations attached to this public contract.
+
+---
+
+### AppDirectoryEntry
+
+```ts
+type AppDirectoryEntry = z.output<typeof appDirectoryEntrySchema>;
+```
+
+An App directory row before host-specific permissions are attached.
+
+---
+
+### AppComputerOperation
+
+```ts
+type AppComputerOperation = Extract<
+  z.output<typeof appComputerPermissionSchema>,
+  {
+    kind: "all-team-computers";
+  }
+>["operations"][number];
+```
+
+One operation an App may request for a Computer.
+
+---
+
+### AppComputerPermission
+
+```ts
+type AppComputerPermission = z.output<typeof appComputerPermissionSchema>;
+```
+
+Decoded Computer permission scope attached to an App directory entry.
+
+---
+
+### AppAgentPermission
+
+```ts
+type AppAgentPermission = z.output<typeof appAgentPermissionSchema>;
+```
+
+Decoded Agent permission scope attached to an App directory entry.
+
+---
+
+### AppGenerationPermissions
+
+```ts
+type AppGenerationPermissions = z.output<typeof appGenerationPermissionsSchema>;
+```
+
+Decoded generation permissions attached to an App directory entry.
+
+---
+
+### AppMarketplacePermissions
+
+```ts
+type AppMarketplacePermissions = z.output<
+  typeof appMarketplacePermissionsSchema
+>;
+```
+
+Decoded marketplace permissions attached to an App directory entry.
+
+---
+
+### AppDirectory
+
+```ts
+type AppDirectory = z.output<typeof appDirectoryResponseSchema>;
+```
+
+The host-resolved Team App directory and its permission projections.
+
+---
+
+### AppCatalog
+
+```ts
+type AppCatalog = z.output<typeof appCatalogResponseSchema>;
+```
+
+Parsed metadata returned by the read-only APPS.catalog binding.
+
+## Variables
+
+### appAddressSchema
+
+```ts
+const appAddressSchema: ZodLazy<
+  ZodUnion<
+    readonly [
+      ZodObject<
+        {
+          kind: ZodLiteral<"default">;
+          appId: ZodString;
+        },
+        $strict
+      >,
+      ZodObject<
+        {
+          kind: ZodLiteral<"installation">;
+          installationId: ZodString;
+        },
+        $strict
+      >,
+    ]
+  >
+>;
+```
+
+An App address selects a host default or a specific installation.
+
+---
+
+### appAuthorityEnforcementSchema
+
+```ts
+const appAuthorityEnforcementSchema: ZodLazy<
+  ZodObject<
+    {
+      requestId: ZodString;
+      address: ZodLazy<
+        ZodUnion<
+          readonly [
+            ZodObject<
+              {
+                kind: ZodLiteral<"default">;
+                appId: ZodString;
+              },
+              $strict
+            >,
+            ZodObject<
+              {
+                kind: ZodLiteral<"installation">;
+                installationId: ZodString;
+              },
+              $strict
+            >,
+          ]
+        >
+      >;
+      authorityVersion: ZodNumber;
+      state: ZodEnum<{
+        unaffected: "unaffected";
+        pending: "pending";
+        applied: "applied";
+        expired: "expired";
+      }>;
+      outstanding: ZodNumber;
+    },
+    $strict
+  >
+>;
+```
+
+Host-reported progress of applying a revised App authority version.
+
+---
+
+### appDirectoryEntrySchema
+
+```ts
+const appDirectoryEntrySchema: ZodObject<{
+  address: ZodLazy<ZodUnion<readonly [ZodObject<{
+     kind: ZodLiteral<"default">;
+     appId: ZodString;
+   }, $strict>, ZodObject<{
+     kind: ZodLiteral<"installation">;
+     installationId: ZodString;
+  }, $strict>]>>;
+  installationId: ZodNullable<ZodString>;
+  surfaceId: ZodString;
+  appId: ZodString;
+  displayName: ZodOptional<ZodString>;
+  icon: ZodOptional<ZodNullable<ZodString>>;
+  releaseId: ZodNullable<ZodString>;
+  authorityVersion: ZodNumber;
+  enforcement: ZodNullable<ZodLazy<ZodObject<{
+     requestId: ZodString;
+     address: ZodLazy<ZodUnion<readonly [ZodObject<{
+        kind: ...;
+        appId: ...;
+      }, $strict>, ZodObject<{
+        kind: ...;
+        installationId: ...;
+     }, $strict>]>>;
+     authorityVersion: ZodNumber;
+     state: ZodEnum<{
+        unaffected: "unaffected";
+        pending: "pending";
+        applied: "applied";
+        expired: "expired";
+     }>;
+     outstanding: ZodNumber;
+  }, $strict>>>;
+  handlers: ZodArray<ZodLiteral<"file.open">>;
+  roles: ZodArray<ZodString>;
+  declaredCapabilities: ZodArray<ZodString>;
+  calls: ZodOptional<ZodPipe<ZodUnknown, ZodTransform<readonly object[], unknown>>>;
+  commands: ZodPipe<ZodArray<ZodUnknown>, ZodTransform<Readonly<{
+     id: string;
+     title: string;
+     category: string;
+     description?: string;
+     sigil?: string;
+     projections?: Readonly<{
+        bindings?: ... | ...;
+        agent?: ... | ...;
+        help?: ... | ...;
+        menu?: ... | ...;
+        palette?: ... | ...;
+        slash?: ... | ...;
+     }>;
+  }>[], unknown[]>>;
+  gills: ZodPipe<ZodArray<ZodUnknown>, ZodTransform<AppDirectoryGill[], unknown[]>>;
+  availability: ZodEnum<{
+     available: "available";
+     unavailable: "unavailable";
+  }>;
+  surface: ZodNullable<ZodObject<{
+     stableRoute: ZodString;
+  }, $strict>>;
+  surfacePath: ZodString;
+}, $strict>;
+```
+
+Reusable App metadata supplied by an embedding host; it conveys no permissions.
+
+---
+
+### appRoleSelectionSchema
+
+```ts
+const appRoleSelectionSchema: ZodObject<
+  {
+    surfaceId: ZodNullable<ZodString>;
+    chosen: ZodBoolean;
+  },
+  $strict
+>;
+```
+
+A host-resolved role selection; a surface address is not launch authority.
+
+---
+
+### appComputerPermissionSchema
+
+```ts
+const appComputerPermissionSchema: ZodDiscriminatedUnion<[ZodLazy<ZodObject<{
+  kind: ZodLiteral<"selected-computers">;
+  computers: ZodArray<ZodObject<{
+     computerId: ZodString;
+     operations: ZodArray<ZodEnum<{
+        computer.list: ...;
+        computer.readFile: ...;
+        computer.writeFile: ...;
+        computer.execute: ...;
+     }>>;
+  }, $strict>>;
+}, $strict>>, ZodLazy<ZodObject<{
+  kind: ZodLiteral<"all-team-computers">;
+  operations: ZodArray<ZodEnum<{
+     computer.list: "computer.list";
+     computer.readFile: "computer.readFile";
+     computer.writeFile: "computer.writeFile";
+     computer.execute: "computer.execute";
+  }>>;
+}, $strict>>], "kind">;
+```
+
+App Computer permissions limited to selected Computers or the Team's Computers.
+
+---
+
+### appAgentPermissionSchema
+
+```ts
+const appAgentPermissionSchema: ZodDiscriminatedUnion<[ZodObject<{
+  kind: ZodLiteral<"all-team-agents">;
+  directoryOperations: ZodArray<ZodEnum<{
+     agent.list: "agent.list";
+  }>>;
+  sessionOperations: ZodArray<ZodEnum<{
+     agent.read: "agent.read";
+     agent.send: "agent.send";
+     agent.manage: "agent.manage";
+  }>>;
+}, $strict>, ZodObject<{
+  kind: ZodLiteral<"selected-agents">;
+  directoryOperations: ZodArray<ZodEnum<{
+     agent.list: "agent.list";
+  }>>;
+  agents: ZodArray<ZodObject<{
+     agentId: ZodString;
+     sessionOperations: ZodArray<ZodEnum<{
+        agent.read: "agent.read";
+        agent.send: "agent.send";
+        agent.manage: "agent.manage";
+     }>>;
+  }, $strict>>;
+}, $strict>], "kind">;
+```
+
+Agent directory and session operations an App may request from its host.
+
+---
+
+### appGenerationPermissionsSchema
+
+```ts
+const appGenerationPermissionsSchema: ZodObject<
+  {
+    llm: ZodBoolean;
+    media: ZodBoolean;
+  },
+  $strict
+>;
+```
+
+Whether an App may use language-model and media generation services.
+
+---
+
+### appMarketplacePermissionsSchema
+
+```ts
+const appMarketplacePermissionsSchema: ZodObject<
+  {
+    browse: ZodBoolean;
+    purchase: ZodBoolean;
+    installFree: ZodBoolean;
+  },
+  $strict
+>;
+```
+
+Whether an App may browse, buy, or install free marketplace entries.
+
+---
+
+### appDirectoryResponseSchema
+
+```ts
+const appDirectoryResponseSchema: ZodLazy<ZodObject<{
+  actorIsTeamOwner: ZodBoolean;
+  needsUpdate: ZodOptional<ZodArray<ZodObject<{
+     installationId: ZodNullable<ZodString>;
+     appId: ZodNullable<ZodString>;
+     displayName: ZodString;
+  }, $strict>>>;
+  apps: ZodArray<ZodObject<{
+     address: ZodLazy<ZodUnion<readonly [ZodObject<{
+        kind: ...;
+        appId: ...;
+      }, $strict>, ZodObject<{
+        kind: ...;
+        installationId: ...;
+     }, $strict>]>>;
+     installationId: ZodNullable<ZodString>;
+     surfaceId: ZodString;
+     appId: ZodString;
+     displayName: ZodOptional<ZodString>;
+     icon: ZodOptional<ZodNullable<ZodString>>;
+     releaseId: ZodNullable<ZodString>;
+     authorityVersion: ZodNumber;
+     enforcement: ZodNullable<ZodLazy<ZodObject<{
+        requestId: ZodString;
+        address: ZodLazy<...>;
+        authorityVersion: ZodNumber;
+        state: ZodEnum<...>;
+        outstanding: ZodNumber;
+     }, $strict>>>;
+     handlers: ZodArray<ZodLiteral<"file.open">>;
+     roles: ZodArray<ZodString>;
+     declaredCapabilities: ZodArray<ZodString>;
+     calls: ZodOptional<ZodPipe<ZodUnknown, ZodTransform<readonly object[], unknown>>>;
+     commands: ZodPipe<ZodArray<ZodUnknown>, ZodTransform<Readonly<{
+        id: ...;
+        title: ...;
+        category: ...;
+        description?: ...;
+        sigil?: ...;
+        projections?: ...;
+     }>[], unknown[]>>;
+     gills: ZodPipe<ZodArray<ZodUnknown>, ZodTransform<AppDirectoryGill[], unknown[]>>;
+     availability: ZodEnum<{
+        available: "available";
+        unavailable: "unavailable";
+     }>;
+     surface: ZodNullable<ZodObject<{
+        stableRoute: ZodString;
+     }, $strict>>;
+     surfacePath: ZodString;
+     override: ZodNullable<ZodObject<{
+        appId: ZodOptional<ZodString>;
+        releaseId: ZodString;
+        surfaceRoute: ZodNullable<ZodString>;
+     }, $strict>>;
+     grants: ZodArray<ZodObject<{
+        operation: ZodString;
+        resourceId: ZodString;
+     }, $strict>>;
+     computerPermission: ZodOptional<ZodNullable<ZodDiscriminatedUnion<[ZodLazy<...>, ZodLazy<...>], "kind">>>;
+     generationPermissions: ZodObject<{
+        llm: ZodBoolean;
+        media: ZodBoolean;
+     }, $strict>;
+     marketplacePermissions: ZodObject<{
+        browse: ZodBoolean;
+        purchase: ZodBoolean;
+        installFree: ZodBoolean;
+     }, $strict>;
+     agentPermission: ZodDiscriminatedUnion<[ZodObject<{
+        kind: ZodLiteral<...>;
+        directoryOperations: ZodArray<...>;
+        sessionOperations: ZodArray<...>;
+      }, $strict>, ZodObject<{
+        kind: ZodLiteral<...>;
+        directoryOperations: ZodArray<...>;
+        agents: ZodArray<...>;
+     }, $strict>], "kind">;
+  }, $strict>>;
+  roles: ZodRecord<ZodString, ZodObject<{
+     surfaceId: ZodNullable<ZodString>;
+     chosen: ZodBoolean;
+  }, $strict>>;
+}, $strict>>;
+```
+
+A host's Team App directory with its permission projection, parsed strictly by
+every consumer: an unknown field is a contract change both sides make.
+
+---
+
+### appCatalogEntrySchema
+
+```ts
+const appCatalogEntrySchema: ZodObject<{
+  surfaceId: ZodString;
+  appId: ZodString;
+  displayName: ZodOptional<ZodString>;
+  gills: ZodArray<ZodObject<{
+     id: ZodString;
+     title: ZodString;
+     params: ZodOptional<ZodLazy<ZodArray<ZodObject<{
+        key: ...;
+        label: ...;
+        kind: ...;
+        required: ...;
+        options: ...;
+     }, $strict>> & ZodType<readonly object[], object[], $ZodTypeInternals<readonly ...[], ...[]>>>>;
+     desktop: ZodOptional<ZodObject<{
+        sizes: ZodArray<ZodEnum<{
+           S: ...;
+           M: ...;
+           L: ...;
+        }>>;
+     }, $strict>>;
+  }, $strict>>;
+}, $strict>;
+```
+
+Read-only catalog metadata for one App, without host-specific role policy.
+
+---
+
+### appCatalogResponseSchema
+
+```ts
+const appCatalogResponseSchema: ZodLazy<ZodObject<{
+  apps: ZodArray<ZodObject<{
+     surfaceId: ZodString;
+     appId: ZodString;
+     displayName: ZodOptional<ZodString>;
+     gills: ZodArray<ZodObject<{
+        id: ZodString;
+        title: ZodString;
+        params: ZodOptional<ZodLazy<...>>;
+        desktop: ZodOptional<ZodObject<..., ...>>;
+     }, $strict>>;
+  }, $strict>>;
+  roles: ZodObject<{
+     inbox: ZodOptional<ZodObject<{
+        surfaceId: ZodNullable<ZodString>;
+        chosen: ZodBoolean;
+     }, $strict>>;
+  }, $strict>;
+}, $strict>>;
+```
+
+Read-only desktop metadata; identities are surface addresses, never launch
+authority.
+
+---
+
+### appCatalogBrokerResultSchema
+
+```ts
+const appCatalogBrokerResultSchema: ZodLazy<ZodUnion<readonly [ZodLazy<ZodObject<{
+  apps: ZodArray<ZodObject<{
+     surfaceId: ZodString;
+     appId: ZodString;
+     displayName: ZodOptional<ZodString>;
+     gills: ZodArray<ZodObject<..., ...>>;
+  }, $strict>>;
+  roles: ZodObject<{
+     inbox: ZodOptional<ZodObject<{
+        surfaceId: ...;
+        chosen: ...;
+     }, $strict>>;
+  }, $strict>;
+}, $strict>>, ZodObject<{
+  error: ZodString;
+}, $strict>]>>;
+```
+
+Complete APPS.catalog reply, including broker admission failures.
+
+## Functions
+
+### addressKey()
+
+```ts
+function addressKey(address): string;
+```
+
+Stable identity of one App address across directory and settings views.
+
+#### Parameters
+
+| Parameter | Type                                                                                                            |
+| --------- | --------------------------------------------------------------------------------------------------------------- |
+| `address` | \| \{ `kind`: `"default"`; `appId`: `string`; \} \| \{ `kind`: `"installation"`; `installationId`: `string`; \} |
+
+#### Returns
+
+`string`