sh3-core 0.22.0 → 0.22.2

package/dist/registry/permission-descriptions.test.js

@@ -40,7 +40,7 @@ describe('describePermission — documents:read / documents:write', () => {
 function shardWithPerms(id, perms) {
     return {
         manifest: { id, label: id, version: '0.0.0', views: [], permissions: perms },
-        activate: () => { },
+        register: () => { },
     };
 }
 function appWithPerms(id, perms) {
@@ -54,7 +54,7 @@ function appWithPerms(id, perms) {
             layoutVersion: 1,
             permissions: perms,
         },
-        activate: () => { },
+        register: () => { },
     };
 }
 describe('extractBundlePermissions', () => {

package/dist/registry/register.js

@@ -8,7 +8,7 @@
  * manifests; the authoritative value comes from the persisted/server
  * metadata and must be stamped here before any consumer reads the manifest.
  */
-import { registerShard } from '../shards/activate.svelte';
+import { registerShard } from '../shards/lifecycle.svelte';
 import { registerApp } from '../apps/registry.svelte';
 export function registerLoadedBundle(loaded, meta) {
     for (const shard of loaded.shards) {

package/dist/registry/register.test.js

@@ -3,7 +3,7 @@ import { resetFramework } from '../__test__/reset';
 import { makeApp, makeAppManifest, makeShard, makeShardManifest } from '../__test__/fixtures';
 import { registerLoadedBundle } from './register';
 import { registeredApps } from '../apps/registry.svelte';
-import { registeredShards } from '../shards/activate.svelte';
+import { registeredShards } from '../shards/lifecycle.svelte';
 describe('registerLoadedBundle', () => {
     beforeEach(resetFramework);
     it('stamps meta.version onto every shard manifest before registering', () => {

package/dist/runtime/runVerb-shell.test.js

@@ -12,7 +12,7 @@
 import { describe, it, expect, beforeEach } from 'vitest';
 import { MemoryDocumentBackend } from '../documents/backends';
 import { __setDocumentBackend, __setActiveScope } from '../documents/config';
-import { registerShard, activateShard, __resetShardRegistryForTest, } from '../shards/activate.svelte';
+import { registerShard, activateShard, __resetShardRegistryForTest, } from '../shards/lifecycle.svelte';
 import { __resetViewRegistryForTest } from '../shards/registry';
 import { __resetActionsRegistryForTest } from '../actions/registry';
 import { runVerbProgrammatic } from './runVerb';

package/dist/runtime/runVerb.js

@@ -1,7 +1,7 @@
 /*
  * runVerbProgrammatic — programmatic verb dispatch with synthesized VerbContext.
  *
- * Used by `ctx.runVerb(...)` (see shards/activate.svelte.ts). Builds a
+ * Used by `ctx.runVerb(...)` (see shards/lifecycle.svelte.ts). Builds a
  * sink scrollback that captures entries into an array, a headless Sh3Api
  * (no terminal-bound state), a stub SessionClient, and a real TenantFsClient.
  * Verbs that opt in via `programmatic: true` run against this synthesized
@@ -15,7 +15,7 @@
  * Resolution: prefixed names (`'sh3-store:install'`) look up directly;
  * unprefixed sh3 names (`'apps'`) resolve against shardId 'sh3'.
  */
-import { activeShards } from '../shards/activate.svelte';
+import { activeShards } from '../shards/lifecycle.svelte';
 import { getVerb, listVerbsWithShard } from '../shards/registry';
 import { makeSh3Api } from '../sh3Api/headless';
 import { Scrollback } from '../shell-shard/scrollback.svelte';

package/dist/runtime/runVerb.test.js

@@ -1,7 +1,7 @@
 import { describe, it, expect, beforeEach } from 'vitest';
 import { MemoryDocumentBackend } from '../documents/backends';
 import { __setDocumentBackend, __setActiveScope } from '../documents/config';
-import { registerShard, activateShard, __resetShardRegistryForTest, } from '../shards/activate.svelte';
+import { registerShard, activateShard, __resetShardRegistryForTest, } from '../shards/lifecycle.svelte';
 import { __resetViewRegistryForTest } from '../shards/registry';
 import { runVerbProgrammatic } from './runVerb';
 function makeVerb(name, programmatic, body = async () => undefined) {
@@ -27,7 +27,7 @@ describe('runVerbProgrammatic', () => {
     it('rejects on unknown verb', async () => {
         registerShard({
             manifest: { id: 'tester', label: 'T', version: '0.0.0', views: [] },
-            activate(ctx) {
+            register(ctx) {
                 ctx.registerVerb(makeVerb('echo', true));
             },
         });
@@ -37,7 +37,7 @@ describe('runVerbProgrammatic', () => {
     it('rejects when verb is not programmatic', async () => {
         registerShard({
             manifest: { id: 'tester', label: 'T', version: '0.0.0', views: [] },
-            activate(ctx) {
+            register(ctx) {
                 ctx.registerVerb(makeVerb('plain', false));
             },
         });
@@ -47,7 +47,7 @@ describe('runVerbProgrammatic', () => {
     it('invokes a programmatic verb and resolves with { result, scrollback }', async () => {
         registerShard({
             manifest: { id: 'tester', label: 'T', version: '0.0.0', views: [] },
-            activate(ctx) {
+            register(ctx) {
                 ctx.registerVerb(makeVerb('echo', true, async (vctx, args) => {
                     vctx.scrollback.push({
                         kind: 'status',
@@ -71,7 +71,7 @@ describe('runVerbProgrammatic', () => {
         let observed = undefined;
         registerShard({
             manifest: { id: 'tester', label: 'T', version: '0.0.0', views: [] },
-            activate(ctx) {
+            register(ctx) {
                 ctx.registerVerb(makeVerb('capture', true, async (vctx) => {
                     observed = vctx.structuredArgs;
                 }));
@@ -85,7 +85,7 @@ describe('runVerbProgrammatic', () => {
         let received;
         registerShard({
             manifest: { id: 'tester', label: 'T', version: '0.0.0', views: [] },
-            activate(ctx) {
+            register(ctx) {
                 ctx.registerVerb(makeVerb('peek', true, async (vctx) => {
                     received = vctx.signal;
                 }));
@@ -99,7 +99,7 @@ describe('runVerbProgrammatic', () => {
     it('inner dispatch re-enters runVerb and merges scrollback into the outer capture', async () => {
         registerShard({
             manifest: { id: 'tester', label: 'T', version: '0.0.0', views: [] },
-            activate(ctx) {
+            register(ctx) {
                 ctx.registerVerb(makeVerb('inner', true, async (vctx) => {
                     vctx.scrollback.push({ kind: 'status', text: 'inner-fired', level: 'info', ts: 0 });
                 }));
@@ -120,7 +120,7 @@ describe('runVerbProgrammatic', () => {
     it('propagates an error thrown by the verb', async () => {
         registerShard({
             manifest: { id: 'tester', label: 'T', version: '0.0.0', views: [] },
-            activate(ctx) {
+            register(ctx) {
                 ctx.registerVerb(makeVerb('boom', true, async () => {
                     throw new Error('kaboom');
                 }));
@@ -133,7 +133,7 @@ describe('runVerbProgrammatic', () => {
         let observed = undefined;
         registerShard({
             manifest: { id: 'tester', label: 'T', version: '0.0.0', views: [] },
-            activate(ctx) {
+            register(ctx) {
                 ctx.registerVerb(makeVerb('peek-sh3', true, async (vctx) => {
                     observed = vctx.sh3.dispatchToTerminal('foo');
                 }));

package/dist/server-shard/types.d.ts

@@ -12,6 +12,19 @@
  */
 import type { DocumentMeta } from '../documents/types';
 import type { SyncPolicy, ConflictFile } from '../documents/sync-types';
+/** Public shape of an API key — never includes the secret value. */
+export interface ApiKeyPublic {
+    id: string;
+    label: string;
+    scopeId: string | null;
+    ownerUserId: string | null;
+    mintedByShardId: string | null;
+    scopes: string[];
+    peerRole?: 'primary' | 'replica';
+    peerId?: string;
+    createdAt: string;
+    expiresAt?: string;
+}
 /**
  * Per-tenant document API exposed to server shards via
  * `ServerShardContext.documents(tenantId)`. Every method is
@@ -95,6 +108,49 @@ export interface ServerShardContext {
      * Absent => 'primary' behavior at the store.
      */
     setPeerRole(tenant: string, role: 'primary' | 'replica'): void;
+    /**
+     * Redeem a consent ticket and return the freshly-minted key.
+     *
+     * The browser side of your shard calls `POST /api/keys/consent` to issue
+     * a ticket bound to the user's session. The server side hands the
+     * ticket to this method to mint the key. The ticket carries the
+     * `(scopeId, userId, shardId, label, scopes, expiresIn?)` from consent
+     * — none of those are caller-controlled here, so a shard cannot escalate
+     * its own scopes or mint for a different tenant.
+     *
+     * The caller's `scopeId` is read from the Hono request context (`c`) and
+     * must match the scope recorded on the ticket; mismatches return `null`
+     * (same as expired / unknown ticket — probe-resistant).
+     *
+     * The returned `key` is the full secret string. Return it to the user
+     * exactly once and never persist it server-side; subsequent calls only
+     * see `key.id` via `listKeys`.
+     *
+     * @param c The Hono request context for the route handler.
+     * @param ticket The opaque token issued by /api/keys/consent.
+     * @returns `{ id, key }` on success, `null` on invalid / expired / scope-mismatch.
+     */
+    redeemKeyTicket(c: unknown, ticket: string): Promise<{
+        id: string;
+        key: string;
+    } | null>;
+    /**
+     * List API keys this shard has minted for the calling caller's scope.
+     * Filtered to `mintedByShardId === ctx.shardId`. Other shards' keys are
+     * invisible. Returns an empty array if the caller has no scope.
+     */
+    listKeys(c: unknown): Promise<ApiKeyPublic[]>;
+    /**
+     * Revoke an API key by id. Only revokes keys minted by this shard
+     * (`mintedByShardId === ctx.shardId`) for the calling caller's scope.
+     * Attempting to revoke another shard's key or a key in a different
+     * tenant returns `false` without raising.
+     *
+     * Successful revocations fire `onKeyRevoked` on the client side via
+     * the existing SSE channel — same path the browser-driven DELETE
+     * already takes.
+     */
+    revokeKey(c: unknown, id: string): Promise<boolean>;
     /**
      * Translate an SH3 document path to a real filesystem path on the host.
      *

package/dist/sh3Api/headless.js

@@ -15,7 +15,7 @@
  */
 import { listRegisteredApps, getActiveApp } from '../apps/registry.svelte';
 import { launchApp } from '../apps/lifecycle';
-import { registeredShards, listStandaloneViews } from '../shards/activate.svelte';
+import { registeredShards, listStandaloneViews } from '../shards/lifecycle.svelte';
 import { inspectActiveLayout, focusView, closeTab, popoutView, dockFloat, dockIntoActiveLayout, locateSlot as locateSlotInActiveLayout, } from '../layout/inspection';
 import { floatManager } from '../overlays/float';
 import { getUser, isAdmin } from '../auth/index';

package/dist/sh3core-shard/sh3coreShard.svelte.js

@@ -65,7 +65,7 @@ export const sh3coreShard = {
             { id: 'sh3:keys-and-peers', label: 'Keys & Peers' },
         ],
     },
-    activate(ctx) {
+    register(ctx) {
         const zones = ctx.state({
             user: {
                 bindings: {},
@@ -165,9 +165,4 @@ export const sh3coreShard = {
             });
         });
     },
-    autostart() {
-        // Intentionally empty. Defining this field is what puts the sh3core
-        // pseudo-shard on the self-starting path at boot (see bootstrap),
-        // so `sh3core:home` is available before any app launches.
-    },
 };

package/dist/shards/ctx-fetch.test.js

@@ -2,7 +2,7 @@ import { describe, expect, it, vi, beforeEach, afterEach } from 'vitest';
 import { MemoryDocumentBackend } from '../documents/backends';
 import { __setDocumentBackend, __setActiveScope } from '../documents/config';
 import { __setEnvServerUrl } from '../env/index';
-import { registerShard, activateShard, __resetShardRegistryForTest, } from './activate.svelte';
+import { registerShard, activateShard, __resetShardRegistryForTest, } from './lifecycle.svelte';
 import { __resetViewRegistryForTest } from './registry';
 describe('ctx.fetch', () => {
     let originalFetch;
@@ -27,7 +27,7 @@ describe('ctx.fetch', () => {
         let captured = null;
         registerShard({
             manifest: { id: 'test', label: 'test', version: '0.0.0', views: [] },
-            activate(ctx) { captured = ctx; },
+            register(ctx) { captured = ctx; },
         });
         await activateShard('test');
         await captured.fetch('/api/foo');
@@ -42,7 +42,7 @@ describe('ctx.fetch', () => {
         let captured = null;
         registerShard({
             manifest: { id: 'test', label: 'test', version: '0.0.0', views: [] },
-            activate(ctx) { captured = ctx; },
+            register(ctx) { captured = ctx; },
         });
         await activateShard('test');
         await captured.fetch('https://other.example.com/api/bar');
@@ -57,7 +57,7 @@ describe('ctx.fetch', () => {
         let captured = null;
         registerShard({
             manifest: { id: 'test', label: 'test', version: '0.0.0', views: [] },
-            activate(ctx) { captured = ctx; },
+            register(ctx) { captured = ctx; },
         });
         await activateShard('test');
         await captured.fetch('api/baz');
@@ -79,7 +79,7 @@ describe('ctx.serverUrl', () => {
         let captured = null;
         registerShard({
             manifest: { id: 'test', label: 'test', version: '0.0.0', views: [] },
-            activate(ctx) { captured = ctx; },
+            register(ctx) { captured = ctx; },
         });
         await activateShard('test');
         expect(captured.serverUrl).toBe('https://example.com');
@@ -89,7 +89,7 @@ describe('ctx.serverUrl', () => {
         let captured = null;
         registerShard({
             manifest: { id: 'test', label: 'test', version: '0.0.0', views: [] },
-            activate(ctx) { captured = ctx; },
+            register(ctx) { captured = ctx; },
         });
         await activateShard('test');
         expect(captured.serverUrl).toBe('');
@@ -110,7 +110,7 @@ describe('ctx.resolveUrl', () => {
         let captured = null;
         registerShard({
             manifest: { id: 'test', label: 'test', version: '0.0.0', views: [] },
-            activate(ctx) { captured = ctx; },
+            register(ctx) { captured = ctx; },
         });
         await activateShard('test');
         expect(captured.resolveUrl('/api/foo')).toBe('https://example.com/api/foo');
@@ -119,7 +119,7 @@ describe('ctx.resolveUrl', () => {
         let captured = null;
         registerShard({
             manifest: { id: 'test', label: 'test', version: '0.0.0', views: [] },
-            activate(ctx) { captured = ctx; },
+            register(ctx) { captured = ctx; },
         });
         await activateShard('test');
         expect(captured.resolveUrl('https://other.example.com/ws')).toBe('https://other.example.com/ws');
@@ -128,7 +128,7 @@ describe('ctx.resolveUrl', () => {
         let captured = null;
         registerShard({
             manifest: { id: 'test', label: 'test', version: '0.0.0', views: [] },
-            activate(ctx) { captured = ctx; },
+            register(ctx) { captured = ctx; },
         });
         await activateShard('test');
         expect(captured.resolveUrl('api/ws')).toBe('https://example.com/api/ws');

package/dist/shards/lifecycle.svelte.d.ts

@@ -0,0 +1,108 @@
+import type { Shard, ShardContext } from './types';
+/**
+ * Reactive registry of every shard known to the host. Keys are shard ids.
+ * Populated by `registerShard`.
+ */
+export declare const registeredShards: Map<string, Shard>;
+/**
+ * Reactive map of shard ids that failed during the lifecycle. Populated
+ * by registerAllShards and related operations.
+ */
+export interface ShardErrorEntry {
+    id: string;
+    error: unknown;
+    phase: 'register' | 'launch' | 'satellite';
+    timestamp: number;
+}
+export declare const erroredShards: Map<string, ShardErrorEntry>;
+/** Read the app id currently bound to this shard, or null. */
+export declare function getShardBinding(shardId: string): string | null;
+/**
+ * Update which app's namespace this shard's `ctx.documents` resolves to.
+ * Pass `appId` to bind, `null` to unbind. Internal — only the lifecycle
+ * module and `apps/lifecycle.ts` call this.
+ */
+export declare function rotateShardDocumentNamespace(shardId: string, appId: string | null): void;
+export interface ShardEntry {
+    shard: Shard;
+    ctx: ShardContext;
+    viewIds: Set<string>;
+    verbNames: Set<string>;
+    /** Cleanup fns from things registered inside `register()`. Disposed only on shard re-register or framework teardown. */
+    bootCleanupFns: (() => Promise<void> | void)[];
+    /** Per-(shardId, appId) cleanup bags for things registered inside `onAppActivate`. Keyed by appId. */
+    appCleanupBags: Map<string, (() => Promise<void> | void)[]>;
+    /** Active appId during `onAppActivate` invocation, so register sites can route disposers to the right bag. */
+    activeAppId: string | null;
+}
+export declare function __setScopeResolver(resolver: (() => 'tenant' | 'project') | null): void;
+/**
+ * Build a ShardContext for the given shard. The ctx is permanent for the
+ * shard's lifetime; the same instance is passed to `register`, every
+ * `onAppActivate`/`onAppDeactivate`, and every auxiliary hook.
+ *
+ * `entry` tracks cleanup bags. When the shard is inside an `onAppActivate`
+ * call, register sites route disposers to the per-app bag (keyed by
+ * `entry.activeAppId`); otherwise they go to the boot bag.
+ */
+export declare function buildShardContext(shard: Shard, entry: ShardEntry): ShardContext;
+export declare const shardEntries: Map<string, ShardEntry>;
+export declare const activeShards: Map<string, Shard>;
+/**
+ * Run `register(ctx)` on every registered shard. Idempotent — calling on
+ * an already-entered shard is a no-op. Errors are recorded in
+ * `erroredShards` with phase 'register'; one failure does not block others.
+ */
+export declare function registerAllShards(): Promise<void>;
+export declare function runAppActivate(shardId: string, appId: string): Promise<void>;
+export declare function runAppDeactivate(shardId: string, appId: string): Promise<void>;
+/**
+ * Tear down the active entry for a shard and rebuild it from the current
+ * `registeredShards.get(id)` value. Used by `registerShard` when replacing
+ * an existing shard with a fresh module (package update, dev hot-reload).
+ *
+ * Fires `onAppDeactivate` for every bound app, calls `deactivate?.()`,
+ * flushes all cleanup bags, builds a fresh ctx, then re-runs `register()`.
+ * Caller is responsible for re-invoking `runAppActivate` for any apps
+ * currently active that require this shard.
+ */
+export declare function rebuildShardEntry(shardId: string): Promise<void>;
+/**
+ * Register (or re-register) a shard. Records the shard in `registeredShards`.
+ * If the shard is already active (in `shardEntries`), triggers a hot-swap
+ * via `rebuildShardEntry` so the new module replaces the old one cleanly.
+ */
+export declare function registerShard(shard: Shard): void;
+/** True if the shard has been registered AND its register() has run. */
+export declare function isActive(id: string): boolean;
+/** Return the ShardContext for an active shard, or undefined. */
+export declare function getShardContext(id: string): ShardContext | undefined;
+/**
+ * Enumerate every view declared as `standalone` across the currently
+ * registered/active shards.
+ */
+export declare function listStandaloneViews(): Array<{
+    shardId: string;
+    viewId: string;
+    label: string;
+}>;
+/** Test-only reset. */
+export declare function __resetLifecycleForTest(): void;
+/**
+ * Test-only reset for the full shard registry. Wipes all live entries,
+ * registered shards, and error records.
+ */
+export declare function __resetShardRegistryForTest(): void;
+/**
+ * @deprecated v2 compat shim — use `registerAllShards()` to run register
+ * for every registered shard. This shim activates a single shard by
+ * invoking its register hook directly. Retained for test fixtures during
+ * the migration; Phase 7 sweeps callers.
+ */
+export declare function activateShard(id: string): Promise<void>;
+/**
+ * @deprecated v2 compat shim — in v3, shards stay alive for the whole
+ * session. This shim performs a full teardown of the entry (for tests
+ * that explicitly want to verify cleanup paths).
+ */
+export declare function deactivateShard(id: string): void;