@zackbart/connecta 0.25.0 → 0.26.1

package/templates/node/README.md

@@ -46,11 +46,32 @@ reproducible `npm ci` path.
 
 ## Select optional modules
 
+For scheduled artifact pages, uncomment the `artifacts()` module and hourly
+`setInterval` block in `src/index.ts`. The module uses the same CAS-capable
+state file and exposes `runDue()` for the timer; core starts no job on its own.
+Each tick starts at most 10 due pages. Refresh programs can call only shared
+connectors' explicitly read-only tools within the program owner's current
+grants. Revoking refresh or pool access stops future runs. Failed runs leave the last good data
+and mark the viewer stale.
+
 The template explicitly enables `ui: operatorUi()` from
 `@zackbart/connecta/ui`. Open `http://localhost:8787/` and supply the configured
 bearer to inspect Connections. Omit that option and import for an API-only
 server. OAuth callbacks remain in core even with no UI.
 
+The page labels whether each tool runs in programs or needs approval. For
+classified connection failures it offers a fixed repair prompt, and its
+endpoint section has client setup commands for `/mcp` and any pool available
+to the signed-in identity. Those commands contain no bearer token.
+
+Branding belongs in `operatorUi({ branding })`: `productName`, `ownerName`,
+their URLs, `description`, `pageTitle`, `favicon`, and `theme`. The theme is
+five tokens — `accent`, `radius`, `fontFamily`, `monoFamily`, and
+`colorScheme` — and every other color is mixed from them, so one accent themes
+the whole page. A value that fails its gate falls back to the default, and the
+startup warning names it. `src/index.ts` carries the full shape commented out
+above `ui: operatorUi()`.
+
 Connection management needs an interactive identity. A configured bearer is a
 client key and never authorizes browser credential mutations. To enable Clerk:
 
@@ -89,6 +110,12 @@ it through `await ctx.credential?.get()`, or use a provider such as `notion()`
 that declares its own slot. Authorized humans manage the slot inside that
 connection on `/`; there is no separate Credentials tab.
 
+In 0.25.0, this vault also seals downstream OAuth tokens on their first read.
+That is a one-way state migration for those tokens: rolling back to 0.24.x
+requires authorizing each OAuth connector again. See the
+[0.25.0 changelog](../../CHANGELOG.md#0250--2026-09-23) before upgrading a
+deployment with existing OAuth connections.
+
 A saved replacement takes effect on the next call. Connecta tests credentials
 only on an explicit action and otherwise fails at use. Without a vault or UI,
 static credential recovery reports unavailable instead of offering a dead link.
@@ -132,16 +159,17 @@ npm run typecheck
 CONNECTA_TOKEN=dev-token npm run doctor
 ```
 
-Doctor checks health, the executor, and the exact prescribed seven-tool
+Doctor checks health, the executor, and the exact prescribed eight-tool
 model-facing surface by running a harmless sandbox program. It reads the bearer
 from `CONNECTA_TOKEN`; it never accepts the secret as a command-line argument.
 Remote URLs must use HTTPS.
 
 A fully-wired deployment reports exactly the same line as a bare one —
-connector count, QuickJS executed, seven tools, plus any catalog drift:
+connector count, QuickJS executed, eight tools, plus any catalog drift, and
+a note if resumable writes are off:
 
 ```text
-Connecta doctor passed: 1 connector(s), QuickJS executed, prescribed seven-tool surface.
+Connecta doctor passed: 1 connector(s), QuickJS executed, prescribed eight-tool surface.
 ```
 
 `QuickJS` is this deployment's sandbox, reported by the deployment itself —

package/templates/node/package.json

@@ -15,7 +15,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zackbart/connecta": "0.25.0",
+    "@zackbart/connecta": "0.26.1",
     "quickjs-emscripten": "0.32.0"
   },
   "devDependencies": {

package/templates/node/src/index.ts

@@ -27,6 +27,7 @@ import { operatorUi } from "@zackbart/connecta/ui";
 import { api, createConnecta } from "@zackbart/connecta";
 import { fileStorage, listen } from "@zackbart/connecta/node";
 import { quickJsExecutor } from "@zackbart/connecta/quickjs";
+// import { artifacts, kvArtifactStore } from "@zackbart/connecta/artifacts";
 // Operator sign-in. Needs `npm install @clerk/backend` — it is an optional
 // peer, so it does not install with Connecta.
 // import { clerkAuth } from "@zackbart/connecta/auth/clerk";
@@ -45,6 +46,8 @@ const port = Number(process.env.PORT ?? 8787);
 const stateFile = process.env.CONNECTA_STATE_FILE || "./.connecta-state.json";
 const publicUrl = process.env.PUBLIC_URL || `http://localhost:${port}`;
 const storage = fileStorage(stateFile);
+// Optional artifact pages and refresh jobs use the same CAS-capable state file:
+// const artifactModule = artifacts({ store: kvArtifactStore(storage) });
 
 // Operator sign-in. A bearer token is a client key: it may call tools and read
 // connector status, but only a Clerk-authenticated human may write a visible
@@ -103,7 +106,25 @@ const connecta = createConnecta({
   //   ),
   //   deploymentId: "production",
   // }),
+  // The operator UI at /. Its branding is code, like everything else here:
+  // name, owner, description, favicon, and five theme tokens that every
+  // other color is mixed from. A value that fails its check falls back to the
+  // default, and the startup warning names it.
+  // ui: operatorUi({
+  //   branding: {
+  //     productName: "Acme Tools",
+  //     ownerName: "Acme",
+  //     theme: {
+  //       accent: "#2f5fe0", // hex only
+  //       radius: 10, // pixels, or a CSS length such as "0.5rem"
+  //       fontFamily: "Inter, system-ui, sans-serif",
+  //       monoFamily: "ui-monospace, monospace",
+  //       colorScheme: "system", // or "light" | "dark"
+  //     },
+  //   },
+  // }),
   ui: operatorUi(),
+  // artifacts: artifactModule,
   connectors: [
     api("time", {
       description: "Time — current timestamp",
@@ -126,3 +147,9 @@ const connecta = createConnecta({
 
 listen(connecta, port);
 console.log(`connecta listening on port ${port}; MCP at ${publicUrl}/mcp`);
+// The deployment owns this timer; core starts no background work. Uncomment
+// with artifactModule above. Each tick starts at most 10 due pages.
+// const refreshTimer = setInterval(() => {
+//   void artifactModule.runDue().catch((error) => console.error("artifact refresh failed", error));
+// }, 60 * 60 * 1000);
+// refreshTimer.unref();