@fungi.computer/oyster 0.47.5 → 0.49.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -202,9 +202,13 @@ again later, since every deploy replaces the Worker's variables.
202
202
 
203
203
  The first `install-apps` takes about 15 to 20 minutes, mostly building the seven
204
204
  Apps on your Computer, two at a time. It prints a line per step and a timing
205
- table, ending with `Installed 7 Apps`. Open `$OYSTER_URL/login`, sign in with
206
- the owner key, and your Oyster opens on the Tourtois desktop. Run `install-apps`
207
- again to update the Apps; a replaced Release keeps each App's data.
205
+ table, ending with `Installed 7 Apps`. When the builds finish it shows what
206
+ built, what failed and why, and the permissions the Apps ask for, then asks you
207
+ to confirm once; nothing installs before you answer, and `--yes` confirms
208
+ without asking (required without a terminal). Open `$OYSTER_URL/login`, sign in
209
+ with the owner key, and your Oyster opens on the Tourtois desktop. Run
210
+ `install-apps` again to update the Apps; a replaced Release keeps each App's
211
+ data.
208
212
 
209
213
  Starting without `try`, deploying with an API token, upgrading, tearing down and
210
214
  the celld trial are in the [API reference](docs/api/README.md) under "Deploy and
@@ -275,6 +279,10 @@ Install an App Release that `packRelease` produced with the `oyster` command:
275
279
  oyster install ./notes-release --installation-id notes
276
280
  ```
277
281
 
282
+ It lists what the App asks for and asks you to confirm once. Several Releases
283
+ may be given, and then one list covers them all. Add `--yes` to confirm without
284
+ asking; a run with no terminal and no `--yes` installs nothing.
285
+
278
286
  When you need more, add one layer at a time:
279
287
 
280
288
  - `@fungi.computer/oyster/workers-git`: `oysterGitRoot` adds the git door, keys,
@@ -4,4 +4,5 @@ export { permissionPinsSchema, permissionSaveSchema, type PermissionPins, appPer
4
4
  export { admits, admitMethodMetadata, appInvocationCeiling, approvedBindingGrants, scopedBindings, grantsFor, gateRefusalSchema, gateRequestSchema, invocationGrantsSchema, type AppMethodDeclaration, type AppMethodMetadataDecision, type GateDecision, type GateFacts, type GateRequest, type HostPrincipal, type InvocationGrants, } from "./gate.js";
5
5
  export { deriveDeclaredOperations, appCallOperation } from "./operations.js";
6
6
  export { appToolPolicySchema, type AppToolAccess, type AppToolEntry, type AppToolPolicy, } from "./tools.js";
7
+ export { installConfirmation, type InstallConfirmation, type InstallConfirmationLine, } from "./install-confirmation.js";
7
8
  export { permissionCatalog, type PermissionCatalogEntry } from "./catalog.js";
@@ -4,4 +4,5 @@ export { permissionPinsSchema, permissionSaveSchema, appPermissionsWireSchema, a
4
4
  export { admits, admitMethodMetadata, appInvocationCeiling, approvedBindingGrants, scopedBindings, grantsFor, gateRefusalSchema, gateRequestSchema, invocationGrantsSchema, } from "./gate.js";
5
5
  export { deriveDeclaredOperations, appCallOperation } from "./operations.js";
6
6
  export { appToolPolicySchema, } from "./tools.js";
7
+ export { installConfirmation, } from "./install-confirmation.js";
7
8
  export { permissionCatalog } from "./catalog.js";
@@ -0,0 +1,26 @@
1
+ import type { AppCapabilityId } from "@fungi.computer/puffball/app";
2
+ import type { TeamRole } from "@fungi.computer/cairn/team-role";
3
+ /** One declared permission as the install confirmation words it. */
4
+ export type InstallConfirmationLine = Readonly<{
5
+ capability: AppCapabilityId;
6
+ label: string;
7
+ description: string;
8
+ warning: string | null;
9
+ /** The Apps in this install that declare it. */
10
+ apps: readonly string[];
11
+ }>;
12
+ /**
13
+ * Every permission an install declares, once, for one confirmation. `granted`
14
+ * is what confirming approves; `needsApproval` is what stays refused until an
15
+ * owner approves it. Both come from the rule the install reducer applies, so
16
+ * the list cannot promise more or less than the install does.
17
+ */
18
+ export type InstallConfirmation = Readonly<{
19
+ granted: readonly InstallConfirmationLine[];
20
+ needsApproval: readonly InstallConfirmationLine[];
21
+ }>;
22
+ /** Merge any number of Apps into one combined, once-per-permission list. */
23
+ export declare function installConfirmation(role: TeamRole | null, apps: readonly Readonly<{
24
+ name: string;
25
+ capabilities: readonly AppCapabilityId[];
26
+ }>[]): InstallConfirmation;
@@ -0,0 +1,28 @@
1
+ import { permissionCatalog } from "./catalog.js";
2
+ import { installApprovedCapabilities } from "./installation.js";
3
+ /** Merge any number of Apps into one combined, once-per-permission list. */
4
+ export function installConfirmation(role, apps) {
5
+ const granted = new Map();
6
+ const waiting = new Map();
7
+ for (const { name, capabilities } of apps) {
8
+ const approved = new Set(installApprovedCapabilities(role, capabilities));
9
+ for (const capability of capabilities) {
10
+ // Affordances grant nothing and need no consent, so they are not listed.
11
+ if (permissionCatalog[capability].consent === "affordance")
12
+ continue;
13
+ const into = approved.has(capability) ? granted : waiting;
14
+ into.set(capability, [...(into.get(capability) ?? []), name]);
15
+ }
16
+ }
17
+ const lines = (rows) => [...rows].map(([capability, names]) => {
18
+ const entry = permissionCatalog[capability];
19
+ return {
20
+ capability,
21
+ label: entry.label,
22
+ description: entry.description,
23
+ warning: entry.warning,
24
+ apps: [...new Set(names)],
25
+ };
26
+ });
27
+ return { granted: lines(granted), needsApproval: lines(waiting) };
28
+ }
@@ -130,6 +130,12 @@ export type GrantRefusal = Readonly<{
130
130
  kind: "refused";
131
131
  code: "stale_authority" | "not_approver" | "not_declared" | "invalid_command";
132
132
  }>;
133
+ /**
134
+ * What an install approves, for the reducer and for the confirmation shown
135
+ * before it. An approver's install approves the install-class set; a member's
136
+ * approves only the App's own storage, so every other capability waits.
137
+ */
138
+ export declare function installApprovedCapabilities<Capability extends ApprovedGrant["capability"]>(role: TeamRole | null, capabilities: readonly Capability[], builtInShell?: boolean): Capability[];
133
139
  /**
134
140
  * The part of a stored approval the current declaration still covers: an
135
141
  * operation carries only when it is declared and its stored fingerprint equals
@@ -129,6 +129,17 @@ export const grantCommandSchema = z.discriminatedUnion("kind", [
129
129
  ]);
130
130
  /** Owners and admins approve App permissions; members manage installs only. */
131
131
  const approves = (role) => role !== null && teamRoleAtLeast(role, "admin");
132
+ /**
133
+ * What an install approves, for the reducer and for the confirmation shown
134
+ * before it. An approver's install approves the install-class set; a member's
135
+ * approves only the App's own storage, so every other capability waits.
136
+ */
137
+ export function installApprovedCapabilities(role, capabilities, builtInShell = false) {
138
+ return capabilities.filter((capability) => capability === "app.storage" ||
139
+ (approves(role) &&
140
+ (permissionCatalog[capability].consent === "install" ||
141
+ (capability === "team.workbenchHost" && builtInShell))));
142
+ }
132
143
  const declaredRow = (declared, capability) => declared.capabilities.find((row) => row.capability === capability);
133
144
  /** Fingerprints the declaration currently assigns to these operations. */
134
145
  function fingerprintsOf(declared, capability, operations) {
@@ -181,13 +192,7 @@ export function applyGrantCommand(current, rawCommand, context) {
181
192
  // An approver's install approves the install-class set. A member's
182
193
  // install approves only the App's own storage, which touches nothing
183
194
  // beyond the App's own data; every other capability waits for an approver.
184
- grants = context.declaration.capabilities
185
- .filter((capability) => capability === "app.storage" ||
186
- (approves(context.principal.role) &&
187
- (permissionCatalog[capability].consent === "install" ||
188
- (capability === "team.workbenchHost" &&
189
- context.builtInShell === true))))
190
- .map((capability) => ({
195
+ grants = installApprovedCapabilities(context.principal.role, context.declaration.capabilities, context.builtInShell === true).map((capability) => ({
191
196
  capability,
192
197
  capabilityApproved: true,
193
198
  operations: declared(capability),