@superbee/core 0.2.0-pre.17 → 0.2.0-pre.19

package/dist/builtin-recipes.js

@@ -0,0 +1,97 @@
+// Built-in recipes are an acquisition adapter: they materialize the same RecipeFile[] shape an
+// external source supplies, then delegate all interpretation to parseRecipeFiles.
+import { kindConventionDoc } from "./kinds.js";
+import { stringifyDoc } from "./frontmatter.js";
+import { parseRecipeFiles } from "./recipes.js";
+import { CONTEXT_NOTE_KIND, CONTEXT_NOTE_SEED_BODY_LOGICAL, CONTEXT_NOTES_SUMMARY, RECIPE_DESC_BODY, TASK_KIND, TASK_SEED_BODY, WORK_TRACKING_SUMMARY, WORK_TRACKING_DESC_BODY, ROADMAP_KIND, ROADMAP_SEED_BODY, ROADMAP_ITEM_KIND, ROADMAP_ITEM_SEED_BODY, ROADMAP_SUMMARY, ROADMAP_DESC_BODY, } from "./builtin-recipes/content.js";
+/** Used only to call the shared serializer; built-in source bytes discard it before parsing. */
+const PLACEHOLDER_TIMESTAMP = "1970-01-01T00:00:00.000Z";
+function unstampedConvention(kind, body) {
+    const doc = kindConventionDoc(kind, body, PLACEHOLDER_TIMESTAMP);
+    const { timestamp: _timestamp, ...frontmatter } = doc.frontmatter;
+    return { ...doc, frontmatter };
+}
+function buildContextNotesFiles() {
+    const conv = unstampedConvention(CONTEXT_NOTE_KIND, CONTEXT_NOTE_SEED_BODY_LOGICAL);
+    return [
+        {
+            path: "recipe.md",
+            bytes: stringifyDoc({
+                type: "Recipe",
+                id: "context-notes",
+                title: "Context Notes",
+                version: "1",
+                summary: CONTEXT_NOTES_SUMMARY,
+                offer: "give agents persistent memory between sessions",
+            }, RECIPE_DESC_BODY),
+        },
+        { path: "conventions/context-note.md", bytes: stringifyDoc(conv.frontmatter, conv.body) },
+    ];
+}
+function buildWorkTrackingFiles() {
+    const conv = unstampedConvention(TASK_KIND, TASK_SEED_BODY);
+    return [
+        {
+            path: "recipe.md",
+            bytes: stringifyDoc({
+                type: "Recipe",
+                id: "work-tracking",
+                title: "Work Tracking",
+                version: "1",
+                summary: WORK_TRACKING_SUMMARY,
+                offer: "set up a shared task list for this project",
+            }, WORK_TRACKING_DESC_BODY),
+        },
+        { path: "conventions/task.md", bytes: stringifyDoc(conv.frontmatter, conv.body) },
+    ];
+}
+function buildRoadmapFiles() {
+    const roadmap = unstampedConvention(ROADMAP_KIND, ROADMAP_SEED_BODY);
+    const item = unstampedConvention(ROADMAP_ITEM_KIND, ROADMAP_ITEM_SEED_BODY);
+    return [
+        {
+            path: "recipe.md",
+            bytes: stringifyDoc({
+                type: "Recipe",
+                id: "roadmap",
+                title: "Roadmap",
+                version: "1",
+                summary: ROADMAP_SUMMARY,
+                offer: "map out where the project is going",
+            }, ROADMAP_DESC_BODY),
+        },
+        { path: "conventions/roadmap.md", bytes: stringifyDoc(roadmap.frontmatter, roadmap.body) },
+        { path: "conventions/roadmap-item.md", bytes: stringifyDoc(item.frontmatter, item.body) },
+    ];
+}
+const BUILTIN_FILES = {
+    "context-notes": buildContextNotesFiles(),
+    "work-tracking": buildWorkTrackingFiles(),
+    roadmap: buildRoadmapFiles(),
+};
+export function builtinNames() {
+    return Object.keys(BUILTIN_FILES);
+}
+/** Resolve a built-in name only. Acquisition and filesystem routing belong to the caller. */
+export function loadBuiltinRecipe(name) {
+    const files = BUILTIN_FILES[name];
+    return files && Object.hasOwn(BUILTIN_FILES, name)
+        ? parseRecipeFiles(files, `builtin:${name}`, { okfVersion: "0.2" })
+        : null;
+}
+/** Detached source bytes, for consumers that need a recipe package rather than its parsed form. */
+export function builtinRecipeFiles(name) {
+    return Object.hasOwn(BUILTIN_FILES, name) ? structuredClone(BUILTIN_FILES[name]) : undefined;
+}
+/** Synchronous builtin resolution for render-path consumers (offers) that must stay pure. */
+export function resolveBuiltinSync(name) {
+    const files = builtinRecipeFiles(name);
+    if (!files)
+        throw new Error(`resolveBuiltinSync: no built-in recipe named '${name}'`);
+    const result = parseRecipeFiles(files, `builtin:${name}`, { okfVersion: "0.2" });
+    if (!result.ok)
+        throw new Error(`resolveBuiltinSync: built-in '${name}' failed to parse: ${result.error.message}`);
+    return result.recipe;
+}
+export { CONTEXT_NOTE_KIND, CONTEXT_NOTE_SEED_BODY_LOGICAL, CONTEXT_NOTE_SEED_BODY, CONTEXT_NOTES_SUMMARY, RECIPE_DESC_BODY, TASK_KIND, TASK_SEED_BODY, WORK_TRACKING_SUMMARY, WORK_TRACKING_DESC_BODY, ROADMAP_KIND, ROADMAP_SEED_BODY, ROADMAP_ITEM_KIND, ROADMAP_ITEM_SEED_BODY, ROADMAP_SUMMARY, ROADMAP_DESC_BODY } from "./builtin-recipes/content.js";
+//# sourceMappingURL=builtin-recipes.js.map

package/dist/builtin-recipes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"builtin-recipes.js","sourceRoot":"","sources":["../src/builtin-recipes.ts"],"names":[],"mappings":"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"}

package/dist/code-point-order.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The one string order for lists Superbee treats as sets (a declared `string-list` or
+ * `https-url-list` a connector owns): Unicode code point order. JavaScript's default `sort()`
+ * orders UTF-16 code units, which puts an astral character (an emoji, common in labels) before
+ * U+E000 to U+FFFF. A lone surrogate orders by its own value. Storage-neutral.
+ */
+export declare function compareCodePoints(a: string, b: string): number;
+//# sourceMappingURL=code-point-order.d.ts.map

package/dist/code-point-order.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"code-point-order.d.ts","sourceRoot":"","sources":["../src/code-point-order.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAW9D"}

package/dist/code-point-order.js

@@ -0,0 +1,20 @@
+/**
+ * The one string order for lists Superbee treats as sets (a declared `string-list` or
+ * `https-url-list` a connector owns): Unicode code point order. JavaScript's default `sort()`
+ * orders UTF-16 code units, which puts an astral character (an emoji, common in labels) before
+ * U+E000 to U+FFFF. A lone surrogate orders by its own value. Storage-neutral.
+ */
+export function compareCodePoints(a, b) {
+    let i = 0;
+    let j = 0;
+    while (i < a.length && j < b.length) {
+        const x = a.codePointAt(i);
+        const y = b.codePointAt(j);
+        if (x !== y)
+            return x < y ? -1 : 1;
+        i += x > 0xffff ? 2 : 1;
+        j += y > 0xffff ? 2 : 1;
+    }
+    return i < a.length ? 1 : j < b.length ? -1 : 0;
+}
+//# sourceMappingURL=code-point-order.js.map

package/dist/code-point-order.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"code-point-order.js","sourceRoot":"","sources":["../src/code-point-order.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,CAAS,EAAE,CAAS;IACpD,IAAI,CAAC,GAAG,CAAC,CAAC;IACV,IAAI,CAAC,GAAG,CAAC,CAAC;IACV,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,IAAI,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC;QACpC,MAAM,CAAC,GAAG,CAAC,CAAC,WAAW,CAAC,CAAC,CAAE,CAAC;QAC5B,MAAM,CAAC,GAAG,CAAC,CAAC,WAAW,CAAC,CAAC,CAAE,CAAC;QAC5B,IAAI,CAAC,KAAK,CAAC;YAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACnC,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACxB,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC1B,CAAC;IACD,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAClD,CAAC"}

package/dist/connectors.d.ts

@@ -0,0 +1,223 @@
+import { type KindConvention, type KindRegistry } from "./kinds.js";
+import type { Finding, OverlayPolicy, RecordChange } from "./record-overlay/types.js";
+import type { ConceptId, Frontmatter, OkfDocument } from "./types.js";
+import type { ValidationWarning } from "./validation.js";
+export declare const CONNECTOR_TYPE = "Connector";
+export declare const CONNECTORS_PREFIX = "connectors/";
+/** The normalization rules of {@link connectorPinDigest}; bumped whenever a default or sort rule changes. */
+export declare const CONNECTOR_PIN_RULES = 1;
+/**
+ * Credential providers: provider key to the exact hostnames a `token` or `oauth2` credential may be
+ * sent to. A document names a row; it never states a host. Each row is added in its own reviewed
+ * change, verified against the vendor's primary documentation. The pin records the hosts a row
+ * resolves to, so adding a host to an existing row changes the pin of every Connection on that
+ * provider, which then needs approving again.
+ */
+export declare const AUTH_PROVIDERS: Readonly<Record<string, readonly string[]>>;
+/** The accepted keys of every closed block. The shape check and the pin digest read only this table. */
+export declare const CONNECTOR_KEYS: Readonly<{
+    auth: readonly string[];
+    source: readonly string[];
+    identity: readonly string[];
+    mapping: readonly string[];
+    action: readonly string[];
+    input: readonly string[];
+    event: readonly string[];
+    signature: readonly string[];
+}>;
+export type ConnectorBlock = keyof typeof CONNECTOR_KEYS;
+export declare const CONNECTOR_ERROR_CODES: readonly ["CONNECTOR_MALFORMED", "CONNECTOR_UNKNOWN_KEY", "CONNECTOR_AUTH_INVALID", "CONNECTOR_SECRET_PRESENT", "CONNECTOR_DOMAIN_INVALID", "CONNECTOR_DUPLICATE", "CONNECTOR_PROFILE_INVALID", "CONNECTOR_TARGET_KIND_INVALID", "CONNECTOR_MODE_UNSUPPORTED", "CONNECTOR_IDENTITY_UNSTABLE", "CONNECTOR_FIELD_INVALID", "CONNECTOR_FIELD_NEVER_OWNED", "CONNECTOR_FIELD_UNDECLARED", "CONNECTOR_VALUES_INVALID", "CONNECTOR_LIST_FIELD_UNSUPPORTED", "CONNECTOR_ACTION_INVALID", "CONNECTOR_EVENT_INVALID"];
+export type ConnectorErrorCode = (typeof CONNECTOR_ERROR_CODES)[number];
+/** One refusal; `path` is a JSON pointer into the frontmatter (empty for the whole document). */
+export interface ConnectorError {
+    code: ConnectorErrorCode;
+    path: string;
+    message: string;
+}
+export type ConnectorAuthKind = "none" | "token" | "github-app" | "oauth2" | "signed-webhook";
+export interface ConnectorAuth {
+    kind: ConnectorAuthKind;
+    /** `token` and `oauth2`: an {@link AUTH_PROVIDERS} row. */
+    provider?: string;
+    /** `github-app`: permission name to access. */
+    permissions?: Record<string, "read" | "write">;
+    /** `signed-webhook`. */
+    scheme?: "hmac-sha256";
+}
+export interface ConnectorMapping {
+    /** A dotted record path. */
+    from: string;
+    /** Native value (as a string) to target value. */
+    values?: Record<string, string>;
+    /** Present exactly when `values` is: what a native outside the table does. */
+    unmapped?: "keep" | "refuse";
+}
+export interface ConnectorSource {
+    name: string;
+    profile: string;
+    target_kind: string;
+    mode: "overlay";
+    identity: {
+        resource: string;
+        id: string;
+    };
+    /** Target field to mapping; the keys are the fields a Source Feed may own. */
+    fields: Record<string, ConnectorMapping>;
+    completeness: "complete" | "partial";
+}
+export interface ConnectorInput {
+    type: "string" | "text" | "integer" | "boolean";
+    required: boolean;
+    values?: string[];
+}
+export interface ConnectorAction {
+    name: string;
+    method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+    host: string;
+    input: Record<string, ConnectorInput>;
+    confirm: "always" | "never";
+}
+export interface ConnectorEvent {
+    name: string;
+    signature: {
+        scheme: "hmac-sha256";
+        header: string;
+    };
+    references: string[];
+}
+export interface Connector {
+    id: ConceptId;
+    title: string;
+    description?: string;
+    version?: string;
+    auth: ConnectorAuth;
+    domains: string[];
+    sources: ConnectorSource[];
+    actions: ConnectorAction[];
+    events: ConnectorEvent[];
+}
+export type ConnectorParseResult = {
+    ok: true;
+    connector: Connector;
+    warnings: ValidationWarning[];
+} | {
+    ok: false;
+    errors: ConnectorError[];
+};
+/** The hosts a credential of this kind may be sent to: a table row or a fixed set, never document text. */
+export declare function credentialHosts(auth: Pick<ConnectorAuth, "kind" | "provider">): readonly string[];
+/**
+ * Parse one Connector document, returning every refusal found. With `ctx.kinds`, a source whose
+ * target Kind is in the registry is also checked against it; one whose Kind is absent is left to
+ * {@link checkConnectorAgainstKinds} with a warning. A secret-shaped key or value, or a YAML alias,
+ * refuses the document alone, so no other refusal can echo the one or expand the other.
+ */
+export declare function parseConnectorDoc(doc: OkfDocument, ctx?: {
+    kinds?: KindRegistry;
+}): ConnectorParseResult;
+/** The Kind rules over a bundle's registry; a source whose target Kind is not declared is refused. */
+export declare function checkConnectorAgainstKinds(connector: Connector, kinds: KindRegistry): ConnectorError[];
+/**
+ * The digest a Connection records at enable time: every key {@link CONNECTOR_KEYS} accepts, with
+ * defaults filled and order-free lists sorted, plus the credential hosts core resolves the auth kind
+ * to, under the recipe stamp's canonical JSON. Blind to
+ * `title`, `description`, `version`, the body, `x_recipe` and unknown top-level keys.
+ */
+export declare function connectorPinDigest(connector: Connector): string;
+export interface BoundFeed {
+    /** The overlay policy, with the source's target Kind and completeness. */
+    policy: OverlayPolicy;
+    source: ConnectorSource;
+    kind: KindConvention;
+    parameters: Record<string, string>;
+    /** Equal to the feed's `url` byte for byte; identity only, never a fetch target. */
+    resource: string;
+}
+/**
+ * Bind a Source Feed to one source of a Connector. The feed chooses only among the resources the
+ * identity template admits, within the mapping keys, under the source's own completeness and
+ * profile. Every refusal is `POLICY_INVALID` naming the feed and the key. `okfVersion` is the content
+ * bundle's edition; absent means v0.1, as an undeclared edition does, and an owned list field needs
+ * v0.2 because only field actions write lists.
+ */
+export declare function bindSourceFeed(connector: Connector, feed: {
+    id: ConceptId;
+    frontmatter: Frontmatter;
+}, kinds: KindRegistry, options?: {
+    okfVersion?: "0.1" | "0.2";
+}): BoundFeed;
+export type MappingDiagnosticCode = "VALUE_UNMAPPED" | "VALUE_NOT_SCALAR" | "VALUE_NOT_LIST" | "VALUE_MISSING" | "RECORD_REFUSED" | "IDENTITY_MISSING" | "IDENTITY_INVALID";
+/** Why a record's value was not written; `native` is the provider value, `external_id` the record's. */
+export interface MappingDiagnostic {
+    code: MappingDiagnosticCode;
+    /** The target field, or `identity`. */
+    field: string;
+    /** The record path read. */
+    from: string;
+    native: unknown;
+    external_id: string | null;
+}
+export type MappedRecord = {
+    kind: "mapped";
+    external_id: string;
+    /** Values to write. */
+    fields: Record<string, unknown>;
+    /** Not observed this time: carried from the last accepted value, never removed. */
+    unobserved: string[];
+    /** Optional fields the provider says are empty: removed. */
+    cleared: string[];
+    diagnostics: MappingDiagnostic[];
+} | {
+    kind: "refused";
+    present: boolean;
+    external_id: string | null;
+    diagnostics: MappingDiagnostic[];
+};
+export type IdentityResult = {
+    ok: true;
+    resource: string;
+    id: string;
+} | {
+    ok: false;
+    diagnostic: MappingDiagnostic;
+};
+/** The record's identity: the bound resource and the id template rendered over the record. */
+export declare function renderIdentity(source: ConnectorSource, bound: Pick<BoundFeed, "resource">, value: unknown): IdentityResult;
+/**
+ * Map one normalized record onto the target Kind's fields. An absent path leaves the field
+ * unobserved. An empty value (`null` or blank text) clears an optional field and leaves a
+ * required one, or `title`, unobserved with `VALUE_MISSING`. A list or mapping is unobserved with
+ * `VALUE_NOT_SCALAR`. A native outside a values table is looked up as its string (a number as
+ * `String(n)`, a boolean as `true` or `false`) and then follows `unmapped`: `keep` leaves the field
+ * unobserved with `VALUE_UNMAPPED`; `refuse` refuses the whole record, which still counts as present.
+ * A record whose identity cannot be rendered is refused and not present.
+ *
+ * A field the Kind declares as `string-list` or `https-url-list` is always a list: a list of
+ * nonblank text is written deduplicated and in code point order, and `null` is `[]` (empty, so the
+ * owned list empties). An empty list on a required field is `VALUE_MISSING`; anything else, a
+ * member that is not nonblank text included, is unobserved with `VALUE_NOT_LIST`.
+ */
+export declare function mapRecord(source: ConnectorSource, value: unknown, kind: Pick<KindConvention, "fields">): MappedRecord;
+/**
+ * The record-overlay change between the last accepted `after` of this record (carried values
+ * included; null for a first observation) and a new mapping. An unobserved field is carried from
+ * `previous` and left out of `changed_fields`, so no write and no removal is planned for it; a
+ * cleared field is absent from `after`. Only the source's mapping keys can change.
+ */
+export declare function changeBetween(previous: Readonly<Record<string, unknown>> | null, next: Extract<MappedRecord, {
+    kind: "mapped";
+}>, meta: {
+    external_id: string;
+    change_kind: string;
+}): RecordChange;
+/**
+ * Findings for `planFindings`, so one problem across many records raises one Signal: an unknown
+ * value one per source, field, code and native value; a value of the wrong shape or an empty one
+ * one per source, field, code and shape; identity gaps one per source. `facts` hold the code, field
+ * and the clipped native value or the shape, never a record id, so a dismissed finding stays
+ * dismissed until they change; the summary names the count and a sample of record ids.
+ */
+export declare function findingsFor(diagnostics: readonly MappingDiagnostic[], scope: {
+    source: string;
+}): Finding[];
+//# sourceMappingURL=connectors.d.ts.map

package/dist/connectors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connectors.d.ts","sourceRoot":"","sources":["../src/connectors.ts"],"names":[],"mappings":"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"}