@pithy-sh/core 0.10.0 → 0.11.0

package/src/capability/settings.ts

@@ -2,6 +2,7 @@
 // SPDX-License-Identifier: MIT
 
 import { z } from "zod";
+import { InternalError } from "../error/pithyError";
 import type { HostEnvReport } from "../workflow/hostEnv";
 import { hostEnvProviderSentence } from "../workflow/hostEnv";
 
@@ -115,8 +116,8 @@ export interface SettingsCheckContext {
  *
  * Closed for the reason `CapabilityHealth` is: handing a capability a raw Cloudflare client would make
  * every capability a place a network call can be invented, and would put `@pithy-sh/cloudflare` in the
- * dependency list of packages that need none of it. Three questions cover what the first checks ask; a
- * fourth lands here, once, when a capability actually needs it.
+ * dependency list of packages that need none of it. A question lands here once a capability actually needs
+ * it, and not before: six cover what the checks ask.
  *
  * Every method may throw. A throw is the account failing to answer, and the runner reports that
  * capability's account tier as unchecked rather than as a pass.
@@ -141,6 +142,47 @@ export interface SettingsAccountReader {
    * created it with, so the check looks where the value went.
    */
   storeEntry(name: string): Promise<boolean>;
+  /**
+   * The ids of the rows in one of the kit's own tables whose column holds one of `values`, in the app
+   * database a Worker binds as `DB` in one deployed environment (#727).
+   *
+   * Asked by media and storage after a project narrows `visibility.allowed`: narrowing never rewrites a
+   * record, so the records left outside the policy have to be *named*, and only the deployed database
+   * holds them. Closed in its own way — the table must be a `pithy_` one and the column an identifier,
+   * both refused otherwise, and the values are bound, never interpolated — so it reads a fact about a
+   * capability's own rows and cannot become a query language.
+   */
+  appRows(request: AppRowsRequest): Promise<readonly string[]>;
+  /**
+   * Whether that environment's **D1 vault** holds a `json` secret that still carries a top-level `field` —
+   * asked of its manager Worker, which opens the value and answers a bit, never the value (#728). `false`
+   * for a secret that is not stored, since it carries nothing.
+   *
+   * Asked by media of `media-storage-credentials`, which held a supplied Cloudflare token until the runtime
+   * token replaced it: the upgrade is finished only once the bundle has been rewritten without it.
+   */
+  vaultSecretField(request: { name: string; environment: string; field: string }): Promise<boolean>;
+  /**
+   * Whether the account holds a Cloudflare API token of exactly this name (#728). The name is the token's,
+   * composed with the namer that minted it — never a pattern, so a check names one credential it can see.
+   *
+   * Asked by secrets of the manager token the runtime token superseded, which nothing revokes for you.
+   */
+  accountToken(name: string): Promise<boolean>;
+}
+
+/** What {@link SettingsAccountReader.appRows} is asked. */
+export interface AppRowsRequest {
+  /** The deployed environment whose app database is read. `dev` is refused: it has no deployed database. */
+  readonly environment: string;
+  /** The Worker's `apps/` directory — whose `wrangler.jsonc` names the database for that environment. */
+  readonly workerDirectory: string;
+  /** The kit table, as it is named in SQL — `pithy_media_assets`. Must carry the `pithy_` prefix. */
+  readonly table: string;
+  /** The column compared, as it is named in SQL — `visibility`. */
+  readonly column: string;
+  /** The values that make a row worth naming. */
+  readonly values: readonly string[];
 }
 
 /** What the account tier is told: everything the local tier gets, plus the account it may ask. */
@@ -149,6 +191,56 @@ export interface SettingsAccountContext extends SettingsCheckContext {
   account: SettingsAccountReader;
 }
 
+/** One environment an account check could not answer for, and why. */
+export interface UnansweredEnvironment {
+  /** The environment id. */
+  readonly environment: string;
+  /** What the account, or the project, said instead of an answer. */
+  readonly cause: unknown;
+}
+
+/**
+ * An account check that answered for some environments and not for others.
+ *
+ * A check that asks per environment must not let one unanswerable environment cost the others their
+ * findings: staging stood up before prod is the ordinary bring-up, and a check that threw on prod's missing
+ * database would throw away what it had already found in staging. So it collects what it can, and throws
+ * this at the end carrying those findings. The runner reports them as findings and the tier as unchecked,
+ * both — a fault and an unanswered question are two facts, and neither hides the other.
+ */
+export class SettingsAccountIncomplete extends InternalError {
+  /** What the environments that did answer were found to have wrong. */
+  readonly findings: readonly SettingsFinding[];
+  /** The environments that did not answer, in the order they were asked. */
+  readonly unanswered: readonly string[];
+
+  constructor(findings: readonly SettingsFinding[], unanswered: readonly UnansweredEnvironment[]) {
+    const reasons = unanswered.map(({ environment, cause }) => `${environment}: ${describeCause(cause)}`).join("; ");
+    super(
+      {
+        message: `The account check could not answer for ${unanswered.map(({ environment }) => environment).join(", ")}.`,
+        detail: reasons,
+      },
+      { cause: unanswered[0]?.cause },
+    );
+    this.findings = findings;
+    this.unanswered = unanswered.map(({ environment }) => environment);
+  }
+}
+
+/** A cause, as one line. */
+function describeCause(cause: unknown): string {
+  return cause instanceof Error ? cause.message : String(cause);
+}
+
+/**
+ * The findings an account check reached before it threw — none for an ordinary throw, and what it had
+ * collected for a {@link SettingsAccountIncomplete}.
+ */
+export function settingsFindingsBefore(error: unknown): readonly SettingsFinding[] {
+  return error instanceof SettingsAccountIncomplete ? error.findings : [];
+}
+
 /**
  * A capability's settings check, as it hangs off the capability.
  *
@@ -163,6 +255,58 @@ export interface CapabilitySettings {
   account?(context: SettingsAccountContext): Promise<SettingsFinding[]>;
 }
 
+/**
+ * **Two or more checks on one capability, as the one `settings` it declares (#728).** Media names records a
+ * narrowed visibility no longer admits and a bundle still holding a superseded token: two questions, one
+ * capability, one seam.
+ *
+ * Each tier runs every check's, in declaration order. A check that could not answer for some environments
+ * costs those environments and nothing else: the others' findings are kept, and the run ends in one
+ * {@link SettingsAccountIncomplete} carrying every finding and every unanswered environment. A check that
+ * throws outright is unanswered for every environment the context declares.
+ */
+export function allSettings(...checks: readonly CapabilitySettings[]): CapabilitySettings {
+  const accounts = checks.flatMap((check) => (check.account ? [check.account.bind(check)] : []));
+  return {
+    async local(context) {
+      const findings: SettingsFinding[] = [];
+      for (const check of checks) findings.push(...(await check.local(context)));
+      return findings;
+    },
+    ...(accounts.length === 0
+      ? {}
+      : {
+          async account(context) {
+            const findings: SettingsFinding[] = [];
+            const unanswered: UnansweredEnvironment[] = [];
+            for (const account of accounts) {
+              try {
+                findings.push(...(await account(context)));
+              } catch (cause) {
+                findings.push(...settingsFindingsBefore(cause));
+                if (cause instanceof SettingsAccountIncomplete) {
+                  for (const environment of cause.unanswered) {
+                    if (!unanswered.some((entry) => entry.environment === environment)) {
+                      unanswered.push({ environment, cause: cause.cause ?? cause });
+                    }
+                  }
+                  continue;
+                }
+                // With no environment to name, there is nothing the throw could be reported against.
+                if (context.environments.length === 0) throw cause;
+                for (const { name } of context.environments) {
+                  if (!unanswered.some((entry) => entry.environment === name))
+                    unanswered.push({ environment: name, cause });
+                }
+              }
+            }
+            if (unanswered.length > 0) throw new SettingsAccountIncomplete(findings, unanswered);
+            return findings;
+          },
+        }),
+  };
+}
+
 /**
  * Turn a host env's own parse report into findings — the bridge that makes "one schema, two readers" real.
  *

package/src/cli/commandCatalog.generated.ts

@@ -161,6 +161,41 @@ export const COMMANDS = {
     },
     "groups": []
   },
+  "completion": {
+    "positionals": [
+      {
+        "name": "shell",
+        "required": false,
+        "variadic": false
+      }
+    ],
+    "flags": {
+      "--remove": {
+        "type": "boolean",
+        "required": false,
+        "repeatable": false
+      },
+      "--status": {
+        "type": "boolean",
+        "required": false,
+        "repeatable": false
+      },
+      "--json": {
+        "type": "boolean",
+        "required": false,
+        "repeatable": false
+      }
+    },
+    "groups": [
+      {
+        "kind": "atMostOne",
+        "flags": [
+          "--remove",
+          "--status"
+        ]
+      }
+    ]
+  },
   "contract": {
     "positionals": [],
     "flags": {
@@ -251,6 +286,16 @@ export const COMMANDS = {
         "type": "string",
         "required": false,
         "repeatable": false
+      },
+      "--purpose": {
+        "type": "string",
+        "required": false,
+        "repeatable": false
+      },
+      "--kind": {
+        "type": "string",
+        "required": false,
+        "repeatable": false
       }
     },
     "groups": [
@@ -278,13 +323,22 @@ export const COMMANDS = {
         ],
         "any": false
       },
+      {
+        "kind": "requires",
+        "flag": "--kind",
+        "needs": [
+          "--public-key"
+        ],
+        "any": false
+      },
       {
         "kind": "requires",
         "flag": "--update",
         "needs": [
           "--worker-url",
           "--scope",
-          "--public-key"
+          "--public-key",
+          "--purpose"
         ],
         "any": true
       }
@@ -1042,11 +1096,6 @@ export const COMMANDS = {
         "required": false,
         "repeatable": false
       },
-      "--api-token": {
-        "type": "string",
-        "required": false,
-        "repeatable": false
-      },
       "--r2-access-key-id": {
         "type": "string",
         "required": false,
@@ -1057,11 +1106,6 @@ export const COMMANDS = {
         "required": false,
         "repeatable": false
       },
-      "--r2-api-token": {
-        "type": "string",
-        "required": false,
-        "repeatable": false
-      },
       "--json": {
         "type": "boolean",
         "required": false,
@@ -1447,6 +1491,28 @@ export const COMMANDS = {
     },
     "groups": []
   },
+  "secrets tables": {
+    "positionals": [],
+    "flags": {
+      "--env": {
+        "type": "string",
+        "required": false,
+        "repeatable": false,
+        "default": "dev"
+      },
+      "--worker": {
+        "type": "string",
+        "required": false,
+        "repeatable": false
+      },
+      "--json": {
+        "type": "boolean",
+        "required": false,
+        "repeatable": false
+      }
+    },
+    "groups": []
+  },
   "secrets update": {
     "positionals": [
       {
@@ -1547,6 +1613,27 @@ export const COMMANDS = {
     },
     "groups": []
   },
+  "setup": {
+    "positionals": [],
+    "flags": {
+      "--skip-install": {
+        "type": "boolean",
+        "required": false,
+        "repeatable": false
+      },
+      "--dry-run": {
+        "type": "boolean",
+        "required": false,
+        "repeatable": false
+      },
+      "--json": {
+        "type": "boolean",
+        "required": false,
+        "repeatable": false
+      }
+    },
+    "groups": []
+  },
   "storage deprovision": {
     "positionals": [],
     "flags": {
@@ -1586,11 +1673,6 @@ export const COMMANDS = {
         "required": false,
         "repeatable": false
       },
-      "--api-token": {
-        "type": "string",
-        "required": false,
-        "repeatable": false
-      },
       "--r2-access-key-id": {
         "type": "string",
         "required": false,
@@ -1986,6 +2068,34 @@ export const COMMANDS = {
     },
     "groups": []
   },
+  "token forget": {
+    "positionals": [
+      {
+        "name": "profile",
+        "required": true,
+        "variadic": false
+      }
+    ],
+    "flags": {
+      "--env": {
+        "type": "string",
+        "required": false,
+        "repeatable": false,
+        "default": "dev"
+      },
+      "--force": {
+        "type": "boolean",
+        "required": false,
+        "repeatable": false
+      },
+      "--json": {
+        "type": "boolean",
+        "required": false,
+        "repeatable": false
+      }
+    },
+    "groups": []
+  },
   "token list": {
     "positionals": [],
     "flags": {
@@ -2046,7 +2156,12 @@ export const COMMANDS = {
           "vectorize:write",
           "ai:read",
           "zone:read",
-          "routes:write"
+          "routes:write",
+          "analytics:read",
+          "images:write",
+          "stream:write",
+          "queues:write",
+          "artifacts:write"
         ]
       },
       "--json": {
@@ -2123,7 +2238,12 @@ export const COMMANDS = {
           "vectorize:write",
           "ai:read",
           "zone:read",
-          "routes:write"
+          "routes:write",
+          "analytics:read",
+          "images:write",
+          "stream:write",
+          "queues:write",
+          "artifacts:write"
         ]
       },
       "--keep-previous": {
@@ -2416,6 +2536,32 @@ export const COMMANDS = {
     },
     "groups": []
   },
+  "worker bind": {
+    "positionals": [],
+    "flags": {
+      "--from": {
+        "type": "string",
+        "required": false,
+        "repeatable": false
+      },
+      "--to": {
+        "type": "string",
+        "required": false,
+        "repeatable": false
+      },
+      "--binding": {
+        "type": "string",
+        "required": false,
+        "repeatable": false
+      },
+      "--json": {
+        "type": "boolean",
+        "required": false,
+        "repeatable": false
+      }
+    },
+    "groups": []
+  },
   "worker list": {
     "positionals": [],
     "flags": {
@@ -2447,17 +2593,27 @@ export const COMMANDS = {
   "worker rename": {
     "positionals": [
       {
-        "name": "from",
-        "required": true,
+        "name": "old",
+        "required": false,
         "variadic": false
       },
       {
-        "name": "to",
-        "required": true,
+        "name": "new",
+        "required": false,
         "variadic": false
       }
     ],
     "flags": {
+      "--from": {
+        "type": "string",
+        "required": false,
+        "repeatable": false
+      },
+      "--to": {
+        "type": "string",
+        "required": false,
+        "repeatable": false
+      },
       "--force": {
         "type": "boolean",
         "required": false,
@@ -2496,6 +2652,40 @@ export const COMMANDS = {
       }
     },
     "groups": []
+  },
+  "worker unbind": {
+    "positionals": [],
+    "flags": {
+      "--from": {
+        "type": "string",
+        "required": false,
+        "repeatable": false
+      },
+      "--to": {
+        "type": "string",
+        "required": false,
+        "repeatable": false
+      },
+      "--binding": {
+        "type": "string",
+        "required": false,
+        "repeatable": false
+      },
+      "--json": {
+        "type": "boolean",
+        "required": false,
+        "repeatable": false
+      }
+    },
+    "groups": [
+      {
+        "kind": "exactlyOne",
+        "flags": [
+          "--to",
+          "--binding"
+        ]
+      }
+    ]
   }
 } as const;
 

package/src/cli/commandFacts.ts

@@ -62,6 +62,7 @@ export const WORKER_NARROWS = [
   "env",
   "init",
   "migrate",
+  "secrets tables",
   "seed",
   "support deprovision",
   "upgrade",

package/src/controlPlane/capability.ts

@@ -13,11 +13,18 @@ import { ControlPlaneConfig, type ControlPlaneConfigInput } from "./config/confi
 import { ControlPlaneConnection } from "./data/connection";
 import { CONTROL_PLANE_CONNECTIONS_TABLE, type ControlPlaneDatabase, controlPlaneTables } from "./data/tables";
 import type { CapabilityDeclaration } from "./discovery/adminRoute";
-import { type CapabilityHealthSource, capabilityHealthSources } from "./discovery/health";
+import { type CapabilityHealthSource, capabilityHealthSources, defineCapabilityHealth } from "./discovery/health";
 import { createControlPlaneVerifier } from "./http/guard";
 import { controlPlaneRouteDescriptors, registerControlPlaneRoutes } from "./http/routes";
+import {
+  type ComposedMigrationDatabase,
+  composeMigrationDatabases,
+  MIGRATION_HEALTH_KEYS,
+  readMigrationHealth,
+} from "./migrationState/migrationState";
 import { controlplane_0001_init } from "./migrations/0001_init";
 import { controlplane_0002_management_origin } from "./migrations/0002_management_origin";
+import { controlplane_0003_connection_principal } from "./migrations/0003_connection_principal";
 import { d1ReplayGuard } from "./replay/d1Guard";
 import type { ReplayGuard } from "./replay/guard";
 import {
@@ -79,6 +86,7 @@ export function controlplane(options: ControlPlaneOptions = {}): ControlPlaneCap
   const migrations: Record<string, Migration> = {
     "0001_init": controlplane_0001_init,
     "0002_management_origin": controlplane_0002_management_origin,
+    "0003_connection_principal": controlplane_0003_connection_principal,
   };
   const requiredBindings: BindingSpecInput[] = [
     // The app database — the connections table lives here, beside auth's and audit's. Not the secrets
@@ -132,6 +140,12 @@ export function controlplane(options: ControlPlaneOptions = {}): ControlPlaneCap
   // assembly, because an adopter is never offered such a scope and the number could never be granted.
   let health: ReadonlyMap<string, CapabilityHealthSource> = new Map();
 
+  // Every database this Worker binds and what this build declares for it (#729), composed by the same hook
+  // through `collectMigrationSets` — the function `pithy migrate` uses, so the route and `pithy doctor`
+  // compose the same way. The inputs differ on a D1 two Workers share: the CLI merges every co-bound
+  // Worker's sets and this Worker holds only its own, so `pending` and `undeclared` can differ there.
+  let migrationDatabases: readonly ComposedMigrationDatabase[] = [];
+
   const capability = defineCapability({
     name: "controlplane",
     // `@pithy-sh/core`'s version, stamped by `scripts/stampVersions.ts` — a Worker cannot read its own
@@ -164,6 +178,14 @@ export function controlplane(options: ControlPlaneOptions = {}): ControlPlaneCap
     // The seam describes itself too. Built from the same resolved `basePath` the routes mount on, so a
     // moved mount point is reported rather than becoming a lie a client believes.
     adminRoutes: controlPlaneRouteDescriptors(config.basePath),
+    // Two counts on the seam's own manifest entry, so a client sees *this environment is behind* on the read
+    // it already makes and calls the route only to see what. Behind `migrations:read`, which the route above
+    // requires — a connection without it gets no number rather than a zero. A database that cannot be read
+    // fails the producer, and the seam reports the summary unavailable rather than a partial total.
+    health: defineCapabilityHealth({
+      keys: MIGRATION_HEALTH_KEYS,
+      read: (c) => readMigrationHealth(c.env as Record<string, unknown>, migrationDatabases),
+    }),
     compose: ({ capabilities }) => {
       // Every capability, including those exposing nothing. A client rendering a capability it cannot
       // act on is useful; a client that cannot tell "no admin surface" from "not installed" is not.
@@ -186,6 +208,7 @@ export function controlplane(options: ControlPlaneOptions = {}): ControlPlaneCap
         config: { ...(cap.manifestConfig?.values ?? {}) },
       }));
       health = capabilityHealthSources(capabilities);
+      migrationDatabases = composeMigrationDatabases(capabilities);
     },
     middleware: [
       (app) => {
@@ -228,6 +251,7 @@ export function controlplane(options: ControlPlaneOptions = {}): ControlPlaneCap
         database,
         composedCapabilities: () => composed,
         composedHealth: () => health,
+        composedMigrations: () => migrationDatabases,
         now,
       });
     },

package/src/controlPlane/context.ts

@@ -2,6 +2,7 @@
 // SPDX-License-Identifier: MIT
 
 import { z } from "zod";
+import { ControlPlaneActorKind } from "./data/connection";
 import { ControlPlaneScope } from "./scope/scope";
 
 /**
@@ -56,6 +57,9 @@ export const ControlPlaneContext = z
     tokenId: z
       .string()
       .describe("The token's `jti`, already claimed in the replay set. Recorded to tie one audit event to one call."),
+    actorKind: ControlPlaneActorKind.nullable().describe(
+      "What kind of client the connection is for — `agent`, `dashboard` or `script` — read from the adopter's own row, never from the token. The gate stamps it onto every control-plane audit row this call writes. Null for a connection registered before the kind was recorded (#721).",
+    ),
   })
   .describe(
     "The verified control-plane caller for one request. Never an AuthContext: a management client is not a user of the adopter's app.",