superbee 0.1.3 → 0.1.4

package/README.md

@@ -20,6 +20,13 @@ know invisible to the humans they work for. Superbee fixes all three:
   pages with derived backlinks, a live activity feed, and launchable bundle Views. `superbee
   sync` shares the bundle with teammates on a dedicated `board` branch — pulling their changes
   and pushing yours without touching your code.
+- **Views on demand.** Ask your agent to create whatever representation you need and Superbee will
+  create it: a self-contained HTML View, registered in the bundle as a typed document, that
+  `superbee ui` launches in a sandboxed iframe. A reading surface for one dense document, a board, a
+  timeline, a filtered queue, a chart, a dashboard — the shape follows the question rather than a
+  fixed set of built-in screens, and a view worth keeping stays. A data View reads live bundle
+  content through a narrow read-only bridge and refreshes as documents change. Views are bundle
+  content, so they travel with `sync` and open the same way for a teammate's agent.
 - **Agent-native by design.** The CLI follows the AXI principles for agent-facing tools:
   structured, token-lean output; result counts and truncation with explicit escape hatches;
   idempotent mutations; structured errors with a small, stable exit-code taxonomy. Agents get
@@ -35,6 +42,11 @@ Agent Skill that teaches agents how to use it.
 
 ## Install Steps
 
+**Requirements: Node.js 20 or newer on macOS, Linux, or Windows.** On Windows, Superbee keeps
+per-user operational state under `%LOCALAPPDATA%\Superbee` and uses Windows-native containment and
+path-identity checks instead of relying on synthesized POSIX mode bits. Native Windows behavior and
+the globally installed `superbee.cmd` entrypoint are covered by the required CI contract.
+
 1. Install the CLI globally:
 
    ```sh
@@ -62,6 +74,7 @@ instructions into CLI commands. For example:
 - "Write up what we decided about the auth design as a doc, and link it to the task."
 - "What did the last session leave off on? Check the context notes."
 - "Sync the board so my teammate's agent sees this."
+- "Give me a view of the open tasks grouped by owner."
 
 Behind those requests, the agent drives a small, predictable CLI: `init` creates a bundle in a
 conventional `.superbee/` folder (discovered automatically, the way git finds `.git`); `new`,

package/SKILL.md

@@ -83,8 +83,10 @@ When the tone fits, a single 🐝 may mark a successful Superbee outcome.
 ## Host setup
 
 Persistent integrations require `npm install -g superbee` followed by `superbee setup`.
-Setup is a read-only conductor: select the exact host, ask before running its returned mutating
-command, restart after Skill, Hook, or MCP changes, and rerun setup to verify. A catalog entry
+Setup is an agent-driven read-only conductor: the calling agent selects its exact host, executes
+the returned argv action, reports what it is doing, requests approval only when the action says
+`approval.required: true`, restarts after Skill, Hook, or MCP changes, and reruns setup to verify.
+Do not ask the user to copy or run a setup command unless execution is unavailable. A catalog entry
 preserves a workspace for explicit selection; it never makes that workspace the current project.
 If home or SessionStart reports `skill_update`, run its exact scope-specific command, restart the
 host, and continue; Superbee never rewrites an installed Skill automatically.

package/dist/publication/bridge-entry.d.ts

@@ -0,0 +1,5 @@
+export { createPublicationBridge, type CreatePublicationBridgeOptionsV1 } from "./bridge.js";
+export { PublicationError, isPublicationError } from "./errors.js";
+export type { PublicationErrorCodeV1, PublicationErrorOptions } from "./errors.js";
+export { PUBLICATION_BRIDGE_V0, type PublicationBridgeAdmissionV1, type PublicationBridgeOutcomeV1, type PublicationBridgeV1, type PublicationObjectRefV1, type PublicationSnapshotHandleV1, type PublicationSnapshotV1, } from "./types.js";
+//# sourceMappingURL=bridge-entry.d.ts.map

package/dist/publication/bridge.d.ts

@@ -0,0 +1,9 @@
+import { PUBLICATION_BRIDGE_V0, type PublicationBridgeAdmissionV1, type PublicationBridgeV1, type PublicationSnapshotHandleV1 } from "./types.js";
+export interface CreatePublicationBridgeOptionsV1 {
+    protocol: typeof PUBLICATION_BRIDGE_V0;
+    snapshot: PublicationSnapshotHandleV1;
+    admittedView: PublicationBridgeAdmissionV1;
+}
+/** Create the canonical read-only View bridge over one immutable publication snapshot. */
+export declare function createPublicationBridge(options: CreatePublicationBridgeOptionsV1): PublicationBridgeV1;
+//# sourceMappingURL=bridge.d.ts.map

package/dist/publication/canonical-json.d.ts

@@ -0,0 +1,3 @@
+/** Deterministic JSON serialization used by snapshot and deployment contracts. */
+export declare function canonicalJson(value: unknown): string;
+//# sourceMappingURL=canonical-json.d.ts.map

package/dist/publication/capture.d.ts

@@ -0,0 +1,4 @@
+import { type CapturePublicationSnapshotOptionsV1, type PublicationSnapshotHandleV1 } from "./types.js";
+/** Capture one coherent immutable filesystem publication snapshot. */
+export declare function capturePublicationSnapshot(options: CapturePublicationSnapshotOptionsV1): Promise<PublicationSnapshotHandleV1>;
+//# sourceMappingURL=capture.d.ts.map

package/dist/publication/errors.d.ts

@@ -0,0 +1,22 @@
+export type PublicationErrorCodeV1 = "SOURCE_NOT_FOUND" | "UNSUPPORTED_SOURCE" | "SOURCE_CHANGED" | "LIMIT_EXCEEDED" | "INVALID_BUNDLE" | "INVALID_OBJECT_IDENTITY" | "OBJECT_MISSING" | "OBJECT_VERSION_MISMATCH" | "MALFORMED_DOCUMENT" | "DUPLICATE_DOCUMENT_ID" | "UNSERIALIZABLE_VALUE" | "RENDER_FAILED" | "INVALID_VIEW_REGISTRATION" | "VIEW_ENTRY_MISSING" | "VIEW_ENTRY_VERSION_MISMATCH" | "CAPABILITY_UNAVAILABLE" | "INVALID_SNAPSHOT" | "OBJECT_DIGEST_MISMATCH" | "INVALID_BRIDGE_ADMISSION" | "HANDLE_CLOSED" | "IO_ERROR" | "INTERNAL_ERROR";
+export interface PublicationErrorOptions {
+    retryable?: boolean;
+    subject?: string;
+    expected?: unknown;
+    actual?: unknown;
+    details?: Record<string, unknown>;
+    cause?: unknown;
+}
+/** Stable error boundary for every `superbee/publication` operation. */
+export declare class PublicationError extends Error {
+    readonly code: PublicationErrorCodeV1;
+    readonly retryable: boolean;
+    readonly subject?: string;
+    readonly expected?: unknown;
+    readonly actual?: unknown;
+    readonly details?: Record<string, unknown>;
+    readonly cause?: unknown;
+    constructor(code: PublicationErrorCodeV1, message: string, options?: PublicationErrorOptions);
+}
+export declare function isPublicationError(value: unknown): value is PublicationError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/publication/generated/publication-snapshot-v1.d.ts

@@ -0,0 +1,125 @@
+/**
+ * This interface was referenced by `PublicationSnapshotV1`'s JSON-Schema
+ * via the `definition` "sha256".
+ */
+export type Sha256 = string;
+/**
+ * This interface was referenced by `PublicationSnapshotV1`'s JSON-Schema
+ * via the `definition` "jsonValue".
+ */
+export type JsonValue = null | boolean | number | string | JsonValue[] | {
+    [k: string]: JsonValue;
+};
+export interface PublicationSnapshotV1 {
+    schema: "https://getsuperbee.com/schemas/publication-snapshot/v1";
+    schemaVersion: 1;
+    snapshotDigest: Sha256;
+    source: {
+        okfEdition: string;
+        rootDocumentVersion: string | null;
+        [k: string]: unknown;
+    };
+    semantics: {
+        rendererProfile: string;
+        viewBridgeProtocol: "v0";
+        [k: string]: unknown;
+    };
+    capabilities: string[];
+    documents: Document[];
+    reserved: Reserved[];
+    blobs: Blob[];
+    relationships: Relationship[];
+    views: View[];
+    warnings: Warning[];
+    [k: string]: unknown;
+}
+/**
+ * This interface was referenced by `PublicationSnapshotV1`'s JSON-Schema
+ * via the `definition` "document".
+ */
+export interface Document {
+    id: string;
+    version: string;
+    frontmatter: {
+        [k: string]: JsonValue;
+    };
+    body: string;
+    source: ObjectRef;
+    rendered: {
+        html: ObjectRef;
+        bounded: boolean;
+        [k: string]: unknown;
+    };
+    [k: string]: unknown;
+}
+/**
+ * This interface was referenced by `PublicationSnapshotV1`'s JSON-Schema
+ * via the `definition` "objectRef".
+ */
+export interface ObjectRef {
+    digest: Sha256;
+    size: number;
+    mediaType: string;
+    representation: "exact" | "canonical";
+    [k: string]: unknown;
+}
+/**
+ * This interface was referenced by `PublicationSnapshotV1`'s JSON-Schema
+ * via the `definition` "reserved".
+ */
+export interface Reserved {
+    dir: string;
+    name: "index.md" | "log.md";
+    version: string;
+    object: ObjectRef;
+    [k: string]: unknown;
+}
+/**
+ * This interface was referenced by `PublicationSnapshotV1`'s JSON-Schema
+ * via the `definition` "blob".
+ */
+export interface Blob {
+    key: string;
+    version: string;
+    contentType: string;
+    object: ObjectRef;
+    [k: string]: unknown;
+}
+/**
+ * This interface was referenced by `PublicationSnapshotV1`'s JSON-Schema
+ * via the `definition` "relationship".
+ */
+export interface Relationship {
+    from: string;
+    to: string;
+    text: string;
+    href: string;
+    [k: string]: unknown;
+}
+/**
+ * This interface was referenced by `PublicationSnapshotV1`'s JSON-Schema
+ * via the `definition` "view".
+ */
+export interface View {
+    id: string;
+    registrationVersion: string;
+    title: string;
+    description?: string;
+    presentation?: "workspace" | "inline" | "adaptive";
+    access: "none" | "bundle-read" | "bundle-propose";
+    entry: string;
+    entryVersion: string;
+    entryObject: ObjectRef;
+    [k: string]: unknown;
+}
+/**
+ * This interface was referenced by `PublicationSnapshotV1`'s JSON-Schema
+ * via the `definition` "warning".
+ */
+export interface Warning {
+    code: string;
+    message: string;
+    subject?: string;
+    [k: string]: unknown;
+}
+//# sourceMappingURL=publication-snapshot-v1.d.ts.map

package/dist/publication/index.d.ts

@@ -0,0 +1,7 @@
+export { capturePublicationSnapshot } from "./capture.js";
+export { createPublicationBridge, type CreatePublicationBridgeOptionsV1 } from "./bridge.js";
+export { PublicationError, isPublicationError } from "./errors.js";
+export type { PublicationErrorCodeV1, PublicationErrorOptions } from "./errors.js";
+export { PUBLICATION_SNAPSHOT_SCHEMA_V1 } from "./schema.js";
+export { PUBLICATION_BRIDGE_V0, PUBLICATION_SNAPSHOT_V1, type CapturePublicationSnapshotOptionsV1, type PublicationBridgeAdmissionV1, type PublicationBridgeOutcomeV1, type PublicationBridgeV1, type PublicationJsonValue, type PublicationObjectRefV1, type PublicationSnapshotHandleV1, type PublicationSnapshotV1, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/publication/schema/publication-snapshot-v1.schema.json

@@ -0,0 +1,146 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://getsuperbee.com/schemas/publication-snapshot/v1",
+  "title": "PublicationSnapshotV1",
+  "type": "object",
+  "additionalProperties": true,
+  "required": ["schema", "schemaVersion", "snapshotDigest", "source", "semantics", "capabilities", "documents", "reserved", "blobs", "relationships", "views", "warnings"],
+  "properties": {
+    "schema": { "const": "https://getsuperbee.com/schemas/publication-snapshot/v1" },
+    "schemaVersion": { "const": 1 },
+    "snapshotDigest": { "$ref": "#/$defs/sha256" },
+    "source": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["okfEdition", "rootDocumentVersion"],
+      "properties": {
+        "okfEdition": { "type": "string", "minLength": 1 },
+        "rootDocumentVersion": { "oneOf": [{ "type": "string" }, { "type": "null" }] }
+      }
+    },
+    "semantics": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["rendererProfile", "viewBridgeProtocol"],
+      "properties": {
+        "rendererProfile": { "type": "string", "minLength": 1 },
+        "viewBridgeProtocol": { "const": "v0" }
+      }
+    },
+    "capabilities": {
+      "type": "array",
+      "uniqueItems": true,
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "documents": { "type": "array", "items": { "$ref": "#/$defs/document" } },
+    "reserved": { "type": "array", "items": { "$ref": "#/$defs/reserved" } },
+    "blobs": { "type": "array", "items": { "$ref": "#/$defs/blob" } },
+    "relationships": { "type": "array", "items": { "$ref": "#/$defs/relationship" } },
+    "views": { "type": "array", "items": { "$ref": "#/$defs/view" } },
+    "warnings": { "type": "array", "items": { "$ref": "#/$defs/warning" } }
+  },
+  "$defs": {
+    "sha256": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" },
+    "jsonValue": {
+      "oneOf": [
+        { "type": "null" },
+        { "type": "boolean" },
+        { "type": "number" },
+        { "type": "string" },
+        { "type": "array", "items": { "$ref": "#/$defs/jsonValue" } },
+        { "type": "object", "additionalProperties": { "$ref": "#/$defs/jsonValue" } }
+      ]
+    },
+    "objectRef": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["digest", "size", "mediaType", "representation"],
+      "properties": {
+        "digest": { "$ref": "#/$defs/sha256" },
+        "size": { "type": "integer", "minimum": 0 },
+        "mediaType": { "type": "string", "minLength": 1 },
+        "representation": { "enum": ["exact", "canonical"] }
+      }
+    },
+    "document": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["id", "version", "frontmatter", "body", "source", "rendered"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "version": { "type": "string", "minLength": 1 },
+        "frontmatter": { "type": "object", "additionalProperties": { "$ref": "#/$defs/jsonValue" } },
+        "body": { "type": "string" },
+        "source": { "$ref": "#/$defs/objectRef" },
+        "rendered": {
+          "type": "object",
+          "additionalProperties": true,
+          "required": ["html", "bounded"],
+          "properties": {
+            "html": { "$ref": "#/$defs/objectRef" },
+            "bounded": { "type": "boolean" }
+          }
+        }
+      }
+    },
+    "reserved": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["dir", "name", "version", "object"],
+      "properties": {
+        "dir": { "type": "string" },
+        "name": { "enum": ["index.md", "log.md"] },
+        "version": { "type": "string", "minLength": 1 },
+        "object": { "$ref": "#/$defs/objectRef" }
+      }
+    },
+    "blob": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["key", "version", "contentType", "object"],
+      "properties": {
+        "key": { "type": "string", "minLength": 1 },
+        "version": { "type": "string", "minLength": 1 },
+        "contentType": { "type": "string", "minLength": 1 },
+        "object": { "$ref": "#/$defs/objectRef" }
+      }
+    },
+    "relationship": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["from", "to", "text", "href"],
+      "properties": {
+        "from": { "type": "string", "minLength": 1 },
+        "to": { "type": "string", "minLength": 1 },
+        "text": { "type": "string" },
+        "href": { "type": "string" }
+      }
+    },
+    "view": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["id", "registrationVersion", "title", "access", "entry", "entryVersion", "entryObject"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "registrationVersion": { "type": "string", "minLength": 1 },
+        "title": { "type": "string", "minLength": 1 },
+        "description": { "type": "string" },
+        "presentation": { "enum": ["workspace", "inline", "adaptive"] },
+        "access": { "enum": ["none", "bundle-read", "bundle-propose"] },
+        "entry": { "type": "string", "minLength": 1 },
+        "entryVersion": { "type": "string", "minLength": 1 },
+        "entryObject": { "$ref": "#/$defs/objectRef" }
+      }
+    },
+    "warning": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["code", "message"],
+      "properties": {
+        "code": { "type": "string", "minLength": 1 },
+        "message": { "type": "string", "minLength": 1 },
+        "subject": { "type": "string" }
+      }
+    }
+  }
+}

package/dist/publication/schema.d.ts

@@ -0,0 +1,3 @@
+/** The one serialized v1 schema authority, generated types are checked against this file. */
+export declare const PUBLICATION_SNAPSHOT_SCHEMA_V1: Readonly<Record<string, unknown>>;
+//# sourceMappingURL=schema.d.ts.map

package/dist/publication/snapshot-backend.d.ts

@@ -0,0 +1,33 @@
+import type { BlobKey, ConceptId, DeleteOptions, HeadResult, OkfDocument, QueryFilter, ReadBlobResult, ReadResult, ReservedFilename, ReservedReadResult, StorageBackend, Version, VersionInfo, WriteOptions } from "@superbee/core";
+import type { PublicationSnapshotHandleV1 } from "./types.js";
+/** Read-only adapter used only to reuse the canonical core and View bridge semantics. */
+export declare class PublicationSnapshotBackend implements StorageBackend {
+    private readonly snapshot;
+    private readonly documents;
+    private readonly reserved;
+    private readonly blobs;
+    constructor(snapshot: PublicationSnapshotHandleV1);
+    read(id: ConceptId): Promise<ReadResult>;
+    readMany(ids: ConceptId[]): Promise<ReadResult[]>;
+    write(_id: ConceptId, _doc: OkfDocument, _options?: WriteOptions): Promise<Version>;
+    delete(_id: ConceptId, _options?: DeleteOptions): Promise<boolean>;
+    exists(id: ConceptId): Promise<boolean>;
+    list(prefix?: string): Promise<ConceptId[]>;
+    versions(id: ConceptId): Promise<VersionInfo[]>;
+    queryHeads(filter?: QueryFilter): Promise<HeadResult[]>;
+    readReserved(dir: string, name: ReservedFilename): Promise<ReservedReadResult | null>;
+    writeReserved(_dir: string, _name: ReservedFilename, _content: string, _options?: WriteOptions): Promise<Version>;
+    readBlob(key: BlobKey): Promise<ReadBlobResult | null>;
+    writeBlob(_key: BlobKey, _bytes: Uint8Array, _contentType?: string, _options?: WriteOptions): Promise<Version>;
+    existsBlob(key: BlobKey): Promise<boolean>;
+    listBlobs(prefix?: string): Promise<BlobKey[]>;
+    deleteBlob(_key: BlobKey, _options?: DeleteOptions): Promise<boolean>;
+    capabilities(): {
+        history: boolean;
+        enforced_cas: boolean;
+        blobs: boolean;
+        projections: boolean;
+        backlinks: boolean;
+    };
+}
+//# sourceMappingURL=snapshot-backend.d.ts.map

package/dist/publication/types.d.ts

@@ -0,0 +1,44 @@
+import type { JsonValue, ObjectRef, PublicationSnapshotV1 as GeneratedPublicationSnapshotV1 } from "./generated/publication-snapshot-v1.js";
+type DeepReadonly<T> = T extends (...args: never[]) => unknown ? T : T extends readonly (infer Item)[] ? readonly DeepReadonly<Item>[] : T extends object ? {
+    readonly [Key in keyof T]: DeepReadonly<T[Key]>;
+} : T;
+export declare const PUBLICATION_SNAPSHOT_V1: "https://getsuperbee.com/schemas/publication-snapshot/v1";
+export declare const PUBLICATION_BRIDGE_V0: "v0";
+export type PublicationJsonValue = DeepReadonly<JsonValue>;
+export type PublicationObjectRefV1 = DeepReadonly<ObjectRef>;
+export type PublicationSnapshotV1 = DeepReadonly<GeneratedPublicationSnapshotV1>;
+export interface CapturePublicationSnapshotOptionsV1 {
+    schema: typeof PUBLICATION_SNAPSHOT_V1;
+    source: {
+        kind: "filesystem";
+        root: string;
+    };
+    maxAttempts?: 1 | 2 | 3;
+    limits?: {
+        maxObjects?: number;
+        maxObjectBytes?: number;
+        maxTotalBytes?: number;
+    };
+}
+export interface PublicationSnapshotHandleV1 {
+    readonly manifest: PublicationSnapshotV1;
+    readObject(ref: PublicationObjectRefV1): Promise<Uint8Array>;
+    serializeManifest(): Uint8Array;
+    close(): Promise<void>;
+}
+export interface PublicationBridgeAdmissionV1 {
+    id: string;
+    entry: string;
+    access: "none" | "bundle-read";
+    entryDigest: `sha256:${string}`;
+}
+export interface PublicationBridgeOutcomeV1 {
+    reply: Record<string, unknown> | null;
+    subscribed?: boolean;
+    openViewId?: string;
+}
+export interface PublicationBridgeV1 {
+    handle(rawRequest: unknown): Promise<PublicationBridgeOutcomeV1>;
+}
+export {};
+//# sourceMappingURL=types.d.ts.map