@lucern/sdk 0.2.0-alpha.7 → 0.2.0-alpha.8

package/examples/quickstart.ts

@@ -1,97 +0,0 @@
-import {
-  createExampleTopic,
-  printJson,
-  requireStringField,
-  runExample,
-} from "./shared.js";
-
-if (process.argv.includes("--dry-run")) {
-  printJson({
-    example: "quickstart",
-    mode: "dry-run",
-    steps: [
-      "create topic",
-      "create belief with text alias",
-      "add evidence",
-      "modulate confidence",
-      "fork belief",
-      "search beliefs",
-    ],
-  });
-  process.exit(0);
-}
-
-runExample("quickstart", async (context) => {
-  const topic = await createExampleTopic(context, "quickstart");
-
-  const belief = await context.lucern.beliefs.create({
-    metadata: {
-      example: "quickstart",
-      source: "lucern/packages/sdk/examples/quickstart.ts",
-    },
-    text: "Time-to-first-belief drops when the SDK ships a concrete quickstart that exercises the core lifecycle end to end.",
-    topicId: topic.topicId,
-  });
-  const beliefId = requireStringField(
-    belief.data,
-    ["nodeId", "globalId"],
-    "beliefId"
-  );
-
-  const evidence = await context.lucern.evidence.add({
-    sourceUrl: "https://example.invalid/sdk-quickstart-signal",
-    supports: {
-      nodeId: beliefId,
-      reasoning:
-        "Example-driven onboarding reduces the amount of guesswork before a first successful write.",
-      weight: 0.81,
-    },
-    text: "A runnable example moved the first successful belief write into the first five minutes for a new developer.",
-    topicId: topic.topicId,
-  });
-  const evidenceId = requireStringField(
-    evidence,
-    ["nodeId", "globalId"],
-    "evidenceId"
-  );
-
-  await context.lucern.beliefs.modulateConfidence(beliefId, {
-    confidence: 0.79,
-    rationale:
-      "The quickstart now demonstrates a complete create → evidence → confidence → fork path.",
-    trigger: "evidence_added",
-  });
-
-  const fork = await context.lucern.beliefs.fork(beliefId, {
-    forkReason: "refinement",
-    newFormulation:
-      "Time-to-first-belief drops below five minutes when the SDK ships a concrete quickstart that exercises the core lifecycle end to end.",
-    rationale: "Narrow the claim to the under-five-minute onboarding target.",
-  });
-  const forkId = requireStringField(
-    fork.data,
-    ["nodeId", "forkedNodeId", "globalId"],
-    "forkId"
-  );
-
-  const search = await context.lucern.beliefs.search({
-    limit: 5,
-    query: "time-to-first-belief",
-    topicId: topic.topicId,
-  });
-
-  return {
-    quickstart: {
-      beliefId,
-      evidenceId,
-      forkId,
-      resultCount: search.results.length,
-      searchResults: search.results.map((result) => ({
-        canonicalText: result.canonicalText,
-        confidence: result.confidence,
-        nodeId: result.nodeId,
-      })),
-    },
-    topic,
-  };
-});

package/examples/shared.ts

@@ -1,318 +0,0 @@
-import { randomUUID } from "node:crypto";
-import { Client } from "@modelcontextprotocol/sdk/client/index.js";
-import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
-import {
-  createGatewayRequestClient,
-  createLucernClient,
-  LucernApiError,
-} from "../src/index.js";
-
-type AnyRecord = Record<string, unknown>;
-
-export type ExampleEnv = {
-  apiKey: string;
-  baseTopicId: string;
-  baseUrl: string;
-  environment: "production" | "sandbox";
-};
-
-export type ExampleContext = {
-  env: ExampleEnv;
-  gateway: ReturnType<typeof createGatewayRequestClient>;
-  lucern: ReturnType<typeof createLucernClient>;
-};
-
-function asRecord(value: unknown): AnyRecord {
-  return value && typeof value === "object" ? (value as AnyRecord) : {};
-}
-
-function normalizeEnvironment(
-  value: string | undefined
-): "production" | "sandbox" {
-  const normalized = value?.trim().toLowerCase();
-  if (
-    normalized === "sandbox" ||
-    normalized === "preview" ||
-    normalized === "development"
-  ) {
-    return "sandbox";
-  }
-  return "production";
-}
-
-function readEnv(...names: string[]): string | undefined {
-  for (const name of names) {
-    const value = process.env[name];
-    if (typeof value === "string" && value.trim().length > 0) {
-      return value.trim();
-    }
-  }
-  return;
-}
-
-function requireEnv(label: string, ...names: string[]): string {
-  const value = readEnv(...names);
-  if (!value) {
-    throw new Error(
-      `Missing required env var for ${label}: ${names.join(" or ")}`
-    );
-  }
-  return value;
-}
-
-function parseMcpPayload(result: unknown): unknown {
-  const record = asRecord(result);
-  const content = Array.isArray(record.content) ? record.content : [];
-  const first = content[0];
-  const text =
-    typeof asRecord(first).text === "string"
-      ? String(asRecord(first).text)
-      : "";
-  if (!text) {
-    return result;
-  }
-
-  try {
-    return JSON.parse(text) as unknown;
-  } catch {
-    return text;
-  }
-}
-
-export function slugify(value: string): string {
-  return value
-    .toLowerCase()
-    .replace(/[^a-z0-9]+/g, "-")
-    .replace(/^-+|-+$/g, "")
-    .slice(0, 48);
-}
-
-export function loadExampleEnv(): ExampleEnv {
-  return {
-    apiKey: requireEnv("API key", "LUCERN_API_KEY", "LUCERN_KEY"),
-    baseTopicId: requireEnv(
-      "base topic",
-      "LUCERN_TOPIC_ID",
-      "LUCERN_PROJECT_ID"
-    ),
-    baseUrl: requireEnv(
-      "deployment URL",
-      "LUCERN_BASE_URL",
-      "LUCERN_API_BASE_URL"
-    ),
-    environment: normalizeEnvironment(
-      readEnv("LUCERN_ENVIRONMENT", "LUCERN_API_ENVIRONMENT")
-    ),
-  };
-}
-
-export function createExampleContext(): ExampleContext {
-  const env = loadExampleEnv();
-  const getAuthHeaders = async () => ({
-    "x-lucern-environment": env.environment,
-    "x-lucern-key": env.apiKey,
-  });
-
-  return {
-    env,
-    gateway: createGatewayRequestClient({
-      baseUrl: env.baseUrl,
-      getAuthHeaders,
-    }),
-    lucern: createLucernClient({
-      apiKey: env.apiKey,
-      baseUrl: env.baseUrl,
-      environment: env.environment,
-    }),
-  };
-}
-
-export function listItems<T = AnyRecord>(
-  value: unknown,
-  legacyKey?: string
-): T[] {
-  if (Array.isArray(value)) {
-    return value as T[];
-  }
-
-  const record = asRecord(value);
-  if (Array.isArray(record.items)) {
-    return record.items as T[];
-  }
-  if (legacyKey && Array.isArray(record[legacyKey])) {
-    return record[legacyKey] as T[];
-  }
-  return [];
-}
-
-export function readStringField(
-  value: unknown,
-  keys: string[]
-): string | undefined {
-  const record = asRecord(value);
-  for (const key of keys) {
-    const candidate = record[key];
-    if (typeof candidate === "string" && candidate.trim().length > 0) {
-      return candidate.trim();
-    }
-  }
-  return;
-}
-
-export function requireStringField(
-  value: unknown,
-  keys: string[],
-  label: string
-): string {
-  const resolved = readStringField(value, keys);
-  if (!resolved) {
-    throw new Error(`Unable to resolve ${label} from response payload.`);
-  }
-  return resolved;
-}
-
-export function summarizeError(error: unknown): AnyRecord {
-  if (error instanceof LucernApiError) {
-    return {
-      type: error.name,
-      code: error.code,
-      status: error.status,
-      message: error.message,
-      invariant: error.invariant ?? null,
-      suggestion: error.suggestion ?? null,
-      correlationId: error.correlationId ?? null,
-      policyTraceId: error.policyTraceId ?? null,
-    };
-  }
-
-  if (error instanceof Error) {
-    return {
-      type: error.name,
-      message: error.message,
-    };
-  }
-
-  return {
-    type: "UnknownError",
-    message: String(error),
-  };
-}
-
-export function printJson(payload: unknown): void {
-  console.log(JSON.stringify(payload, null, 2));
-}
-
-export async function createExampleTopic(
-  context: ExampleContext,
-  label: string
-): Promise<{
-  name: string;
-  parentTopicId: string;
-  raw: unknown;
-  topicId: string;
-}> {
-  const suffix = `${slugify(label)}-${randomUUID().slice(0, 8)}`;
-  const response = await context.gateway.request<AnyRecord>({
-    path: "/api/platform/v1/topics",
-    method: "POST",
-    body: {
-      description: `Created by lucern/packages/sdk/examples/${slugify(label)}.ts`,
-      name: `SDK Example ${suffix}`,
-      parentTopicId: context.env.baseTopicId,
-      type: "project",
-    },
-  });
-
-  const topicId = requireStringField(
-    response.data,
-    ["topicId", "_id", "id"],
-    "topicId"
-  );
-
-  return {
-    topicId,
-    name: readStringField(response.data, ["name"]) ?? `SDK Example ${suffix}`,
-    parentTopicId: context.env.baseTopicId,
-    raw: response.data,
-  };
-}
-
-export async function callHostedMcpTool(
-  context: ExampleContext,
-  name: string,
-  args: Record<string, unknown>
-): Promise<{
-  endpoint: string;
-  ok: boolean;
-  payload: unknown;
-  raw: unknown;
-}> {
-  const endpoint = new URL("/api/platform/mcp", context.env.baseUrl);
-  const transport = new StreamableHTTPClientTransport(endpoint, {
-    requestInit: {
-      headers: {
-        "x-lucern-environment": context.env.environment,
-        "x-lucern-key": context.env.apiKey,
-      },
-    },
-  });
-  const client = new Client({
-    name: `sdk-example-${slugify(name)}`,
-    version: "0.1.0",
-  });
-
-  try {
-    await client.connect(transport);
-    const result = await client.callTool({
-      name,
-      arguments: args,
-    });
-
-    return {
-      endpoint: endpoint.toString(),
-      ok: result.isError !== true,
-      payload: parseMcpPayload(result),
-      raw: result,
-    };
-  } catch (error) {
-    return {
-      endpoint: endpoint.toString(),
-      ok: false,
-      payload: summarizeError(error),
-      raw: null,
-    };
-  } finally {
-    // biome-ignore lint/suspicious/noEmptyBlockStatements: intentional swallow on cleanup
-    await client.close().catch(() => {});
-    // biome-ignore lint/suspicious/noEmptyBlockStatements: intentional swallow on cleanup
-    await transport.close().catch(() => {});
-  }
-}
-
-export async function runExample(
-  name: string,
-  executor: (context: ExampleContext) => Promise<AnyRecord>
-): Promise<void> {
-  const startedAt = Date.now();
-  const context = createExampleContext();
-
-  try {
-    const result = await executor(context);
-    printJson({
-      example: name,
-      status: "ok",
-      durationMs: Date.now() - startedAt,
-      environment: context.env.environment,
-      ...result,
-    });
-  } catch (error) {
-    printJson({
-      example: name,
-      status: "error",
-      durationMs: Date.now() - startedAt,
-      environment: context.env.environment,
-      error: summarizeError(error),
-    });
-    process.exit(1);
-  }
-}

package/examples/strict-public-types.ts

@@ -1,143 +0,0 @@
-import type {
-  AudienceGrantInput,
-  CreateBeliefInput,
-  CreateEdgeInput,
-  CreateNodeInput,
-  HarnessAgentWriteInput,
-  HarnessRunReportInput,
-  PackInstallInput,
-  PlatformBeliefRecord,
-  PlatformGraphEdge,
-  PlatformGraphNode,
-  WorkflowWorktreeRecord,
-} from "../src";
-
-type HasUnknownStringIndex<T> = string extends keyof T
-  ? unknown extends T[string]
-    ? true
-    : false
-  : false;
-
-type AssertFalse<T extends false> = T;
-
-type _platformBeliefRecordHasNoUnknownIndex = AssertFalse<
-  HasUnknownStringIndex<PlatformBeliefRecord>
->;
-type _platformGraphNodeHasNoUnknownIndex = AssertFalse<
-  HasUnknownStringIndex<PlatformGraphNode>
->;
-type _platformGraphEdgeHasNoUnknownIndex = AssertFalse<
-  HasUnknownStringIndex<PlatformGraphEdge>
->;
-type _workflowWorktreeRecordHasNoUnknownIndex = AssertFalse<
-  HasUnknownStringIndex<WorkflowWorktreeRecord>
->;
-type _createBeliefInputHasNoUnknownIndex = AssertFalse<
-  HasUnknownStringIndex<CreateBeliefInput>
->;
-type _createNodeInputHasNoUnknownIndex = AssertFalse<
-  HasUnknownStringIndex<CreateNodeInput>
->;
-type _createEdgeInputHasNoUnknownIndex = AssertFalse<
-  HasUnknownStringIndex<CreateEdgeInput>
->;
-type _packInstallInputHasNoUnknownIndex = AssertFalse<
-  HasUnknownStringIndex<PackInstallInput>
->;
-type _audienceGrantInputHasNoUnknownIndex = AssertFalse<
-  HasUnknownStringIndex<AudienceGrantInput>
->;
-type _harnessAgentWriteInputHasNoUnknownIndex = AssertFalse<
-  HasUnknownStringIndex<HarnessAgentWriteInput>
->;
-type _harnessRunReportInputHasNoUnknownIndex = AssertFalse<
-  HasUnknownStringIndex<HarnessRunReportInput>
->;
-
-const createBeliefInput: CreateBeliefInput = {
-  canonicalText: "Strict SDK public types compile against JSON metadata.",
-  topicId: "topic_123",
-  metadata: {
-    source: "sdk",
-    tags: ["strict", "types"],
-    nested: {
-      enabled: true,
-    },
-  },
-};
-
-const createNodeInput: CreateNodeInput = {
-  canonicalText: "Belief node",
-  nodeType: "belief",
-  metadata: {
-    scope: "sdk",
-  },
-};
-
-const createEdgeInput: CreateEdgeInput = {
-  fromNodeId: "node_a",
-  toNodeId: "node_b",
-  edgeType: "tests",
-  weight: 0.75,
-};
-
-const packInstallInput: PackInstallInput = {
-  tenantId: "tenant_123",
-  packKey: "strict-types",
-  metadata: {
-    actor: "sdk",
-  },
-};
-
-const audienceGrantInput: AudienceGrantInput = {
-  audienceKey: "developers",
-  principalId: "principal_123",
-  metadata: {
-    source: "sdk",
-  },
-};
-
-const harnessAgentInput: HarnessAgentWriteInput = {
-  tenantId: "tenant_123",
-  agentKey: "sdk-audit",
-  displayName: "SDK Audit",
-  description: "Compile-time type contract audit",
-  version: "0.0.1",
-  executionAdapter: "sdk_invocation",
-  parameterSchema: {
-    type: "object",
-  },
-  exampleInvocations: [
-    {
-      input: {
-        query: "strict types",
-      },
-      expectedOutput: {
-        ok: true,
-      },
-    },
-  ],
-};
-
-const harnessRunReportInput: HarnessRunReportInput = {
-  reportingToken: "token_123",
-  type: "tool_call",
-  toolName: "search_beliefs",
-  input: {
-    query: "strict types",
-  },
-  result: {
-    success: true,
-  },
-};
-
-// Export type-check fixtures so the compiler verifies them without void expressions
-export {
-  createBeliefInput,
-  createNodeInput,
-  createEdgeInput,
-  packInstallInput,
-  audienceGrantInput,
-  harnessAgentInput,
-  harnessRunReportInput,
-};

package/examples/worktree-lifecycle.ts

@@ -1,79 +0,0 @@
-import {
-  createExampleTopic,
-  listItems,
-  requireStringField,
-  runExample,
-  slugify,
-} from "./shared.js";
-
-runExample("worktree-lifecycle", async (context) => {
-  const topic = await createExampleTopic(context, "worktree-lifecycle");
-
-  const branchName = `sdk-example-${slugify(topic.name)}-${Date.now()}`;
-  const branch = await context.lucern.worktrees.createBranch({
-    description: "Branch for the SDK worktree lifecycle example.",
-    name: branchName,
-    topicId: topic.topicId,
-  });
-  const branchId = requireStringField(
-    branch.data,
-    ["branchId", "nodeId"],
-    "branchId"
-  );
-
-  const belief = await context.lucern.beliefs.create({
-    text: "A short-lived worktree lets SDK adopters test a belief without mutating scored state.",
-    topicId: topic.topicId,
-  });
-  const beliefId = requireStringField(
-    belief.data,
-    ["nodeId", "globalId"],
-    "beliefId"
-  );
-
-  const worktree = await context.lucern.worktrees.create({
-    beliefIds: [beliefId],
-    branchId,
-    gate: "gate:sdk-example-worktree",
-    hypothesis:
-      "A lightweight worktree example makes the draft-to-merge lifecycle concrete.",
-    objective: "Demonstrate worktree creation from the public SDK surface.",
-    title: "SDK Example Worktree Lifecycle",
-    topicId: topic.topicId,
-  });
-  const worktreeId = requireStringField(
-    worktree.data,
-    ["worktreeId", "nodeId"],
-    "worktreeId"
-  );
-
-  const activation = await context.lucern.worktrees.activate(worktreeId);
-
-  const listed = await context.lucern.worktrees.list({
-    topicId: topic.topicId,
-  });
-  const visibleWorktrees = listItems<Record<string, unknown>>(
-    listed.data,
-    "worktrees"
-  )
-    .filter((entry) => entry.worktreeId === worktreeId)
-    .map((entry) => ({
-      status: typeof entry.status === "string" ? entry.status : null,
-      title: typeof entry.title === "string" ? entry.title : null,
-      worktreeId:
-        typeof entry.worktreeId === "string" ? entry.worktreeId : worktreeId,
-    }));
-
-  return {
-    activation: activation.data,
-    branch: {
-      branchId,
-      name: branchName,
-    },
-    topic,
-    worktree: {
-      visibleWorktrees,
-      worktreeId,
-    },
-  };
-});

package/src/README.md

@@ -1,6 +0,0 @@
-# @lucern/sdk
-
-Official TypeScript SDK for the Lucern reasoning platform.
-
-Generated from and validated against `@lucern/contracts`.
-Migrates from `front-end/lucern/packages/sdk/`.