@contractspec/bundle.library 0.0.0-canary-20260206014742

package/src/components/docs/reference/DocsMarkdownContent.tsx

@@ -0,0 +1,94 @@
+'use client';
+
+import { CodeBlock, type CodeLanguage } from '@contractspec/lib.design-system';
+import { VStack, HStack } from '@contractspec/lib.ui-kit-web/ui/stack';
+import {
+  BlockQuote,
+  H2,
+  H3,
+  H4,
+  Muted,
+  P,
+} from '@contractspec/lib.ui-kit-web/ui/typography';
+import { parseDocsMarkdown } from './docsMarkdownParser';
+
+const CODE_LANGUAGES = new Set<CodeLanguage>([
+  'typescript',
+  'tsx',
+  'javascript',
+  'jsx',
+  'bash',
+  'shell',
+  'json',
+  'yaml',
+  'graphql',
+  'sql',
+  'python',
+  'go',
+  'rust',
+  'css',
+  'scss',
+  'html',
+  'markdown',
+  'text',
+]);
+
+function toCodeLanguage(language?: string): CodeLanguage {
+  if (!language) return 'text';
+  const normalized = language.toLowerCase() as CodeLanguage;
+  return CODE_LANGUAGES.has(normalized) ? normalized : 'text';
+}
+
+function renderHeading(level: number, text: string) {
+  if (level <= 2) return <H2>{text}</H2>;
+  if (level === 3) return <H3>{text}</H3>;
+  return <H4>{text}</H4>;
+}
+
+export function DocsMarkdownContent({ content }: { content: string }) {
+  const blocks = parseDocsMarkdown(content);
+
+  if (!blocks.length) {
+    return <Muted>No reference content available.</Muted>;
+  }
+
+  return (
+    <VStack gap="md">
+      {blocks.map((block, index) => {
+        switch (block.type) {
+          case 'heading':
+            return (
+              <VStack key={index}>
+                {renderHeading(block.level, block.text)}
+              </VStack>
+            );
+          case 'paragraph':
+            return <P key={index}>{block.text}</P>;
+          case 'quote':
+            return <BlockQuote key={index}>{block.text}</BlockQuote>;
+          case 'code':
+            return (
+              <CodeBlock
+                key={index}
+                language={toCodeLanguage(block.language)}
+                code={block.code}
+              />
+            );
+          case 'list':
+            return (
+              <VStack key={index} gap="xs">
+                {block.items.map((item, itemIndex) => (
+                  <HStack key={itemIndex} gap="sm" align="start">
+                    <Muted>{block.ordered ? `${itemIndex + 1}.` : '•'}</Muted>
+                    <P className="leading-relaxed">{item}</P>
+                  </HStack>
+                ))}
+              </VStack>
+            );
+          default:
+            return null;
+        }
+      })}
+    </VStack>
+  );
+}

package/src/components/docs/reference/DocsReferenceContent.tsx

@@ -0,0 +1,73 @@
+'use client';
+
+import { DataViewRenderer } from '@contractspec/lib.design-system';
+import { VStack } from '@contractspec/lib.ui-kit-web/ui/stack';
+import { ContractReferenceDataView } from '@contractspec/lib.contracts/docs';
+import type { DocsIndexEntry } from '../generated/docs-index.generated';
+import { DocsMarkdownContent } from './DocsMarkdownContent';
+
+interface DocsReferenceContentProps {
+  entry: DocsIndexEntry;
+  content: string;
+}
+
+function extractMeta(content: string, label: string) {
+  const match = content.match(new RegExp(`- \\*\\*${label}\\*\\*: (.+)`, 'i'));
+  return match?.[1]?.trim();
+}
+
+function cleanSummary(summary?: string) {
+  if (!summary) return undefined;
+  return summary
+    .replace(/<!--.*?-->/g, '')
+    .replace(/[ \t]+/g, ' ')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim();
+}
+
+export function DocsReferenceContent({
+  entry,
+  content,
+}: DocsReferenceContentProps) {
+  const summary = cleanSummary(entry.summary);
+  const type = extractMeta(content, 'Type');
+  const version = extractMeta(content, 'Version') ?? entry.version;
+  const tags = extractMeta(content, 'Tags')
+    ?.split(',')
+    .map((tag) => tag.trim())
+    .filter(Boolean);
+  const owners = extractMeta(content, 'Owners')
+    ?.split(',')
+    .map((owner) => owner.trim())
+    .filter(Boolean);
+  const stability = extractMeta(content, 'Stability') ?? entry.visibility;
+
+  const referenceItem = {
+    reference: {
+      key: entry.title ?? entry.id,
+      version,
+      type,
+      title: entry.title ?? entry.id,
+      description: summary,
+      tags: tags ?? entry.tags,
+      owners: owners ?? entry.owners,
+      stability,
+    },
+  };
+
+  const detailSpec = {
+    ...ContractReferenceDataView,
+    meta: {
+      ...ContractReferenceDataView.meta,
+      title: entry.title ?? ContractReferenceDataView.meta.title,
+      description: summary ?? ContractReferenceDataView.meta.description,
+    },
+  };
+
+  return (
+    <VStack gap="xl">
+      <DataViewRenderer spec={detailSpec} item={referenceItem} />
+      <DocsMarkdownContent content={content} />
+    </VStack>
+  );
+}

package/src/components/docs/reference/DocsReferenceIndexClient.tsx

@@ -0,0 +1,137 @@
+'use client';
+
+import { useMemo, useState } from 'react';
+import {
+  DataViewList,
+  formRenderer,
+  StatusChip,
+} from '@contractspec/lib.design-system';
+import { VStack, HStack } from '@contractspec/lib.ui-kit-web/ui/stack';
+import { H1, Muted } from '@contractspec/lib.ui-kit-web/ui/typography';
+import {
+  DocsIndexDataView,
+  DocsSearchForm,
+} from '@contractspec/lib.contracts/docs';
+import type { DocsIndexEntry } from '../generated/docs-index.generated';
+
+interface Filters {
+  query?: string;
+  visibility?: string;
+  kind?: string;
+}
+
+interface DocsReferenceIndexClientProps {
+  entries: readonly DocsIndexEntry[];
+}
+
+function cleanSummary(summary?: string) {
+  if (!summary) return undefined;
+  return summary
+    .replace(/<!--.*?-->/g, '')
+    .replace(/[ \t]+/g, ' ')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim();
+}
+
+function normalizeEntry(entry: DocsIndexEntry): DocsIndexEntry {
+  const summary = cleanSummary(entry.summary);
+  const kind =
+    entry.kind ?? (entry.source === 'generated' ? 'reference' : undefined);
+  const visibility =
+    entry.visibility ?? (entry.source === 'generated' ? 'public' : undefined);
+
+  return {
+    ...entry,
+    summary,
+    kind,
+    visibility,
+  };
+}
+
+function matchesQuery(entry: DocsIndexEntry, query: string) {
+  if (!query) return true;
+  const haystack = [entry.title, entry.summary, entry.id, ...(entry.tags ?? [])]
+    .filter(Boolean)
+    .join(' ')
+    .toLowerCase();
+  return haystack.includes(query.toLowerCase());
+}
+
+export function DocsReferenceIndexClient({
+  entries,
+}: DocsReferenceIndexClientProps) {
+  const [filters, setFilters] = useState<Filters>({});
+
+  const normalizedEntries = useMemo(
+    () => entries.map(normalizeEntry),
+    [entries]
+  );
+
+  const filteredEntries = useMemo(() => {
+    const query = filters.query?.trim() ?? '';
+    return normalizedEntries.filter((entry) => {
+      if (filters.kind && entry.kind !== filters.kind) return false;
+      if (filters.visibility && entry.visibility !== filters.visibility)
+        return false;
+      return matchesQuery(entry, query);
+    });
+  }, [filters, normalizedEntries]);
+
+  const searchForm = formRenderer.render(DocsSearchForm, {
+    defaultValues: {
+      query: filters.query ?? '',
+      visibility: filters.visibility ?? '',
+      kind: filters.kind ?? '',
+    },
+    overrides: {
+      onSubmitOverride: (values: unknown) => {
+        const submitted = values as Filters;
+        setFilters({
+          query: submitted.query ?? '',
+          visibility: submitted.visibility ?? '',
+          kind: submitted.kind ?? '',
+        });
+      },
+    },
+  });
+
+  return (
+    <VStack gap="xl">
+      <VStack gap="sm">
+        <H1>Contract Reference</H1>
+        <Muted>
+          Auto-generated reference docs for operations, events, forms, data
+          views, and presentations.
+        </Muted>
+      </VStack>
+
+      <VStack gap="sm" className="max-w-2xl">
+        {searchForm}
+      </VStack>
+
+      <DataViewList
+        spec={DocsIndexDataView}
+        items={filteredEntries}
+        emptyState={<Muted>No reference docs match your filters.</Muted>}
+        onSelect={(entry) => {
+          if (entry.route) {
+            window.location.assign(entry.route);
+          }
+        }}
+        renderActions={(entry) => {
+          return (
+            <HStack gap="xs" justify="end">
+              {entry.kind ? <StatusChip size="sm" label={entry.kind} /> : null}
+              {entry.visibility ? (
+                <StatusChip size="sm" label={entry.visibility} />
+              ) : null}
+              {entry.version ? (
+                <StatusChip size="sm" label={`v${entry.version}`} />
+              ) : null}
+            </HStack>
+          );
+        }}
+      />
+    </VStack>
+  );
+}

package/src/components/docs/reference/DocsReferenceIndexPage.tsx

@@ -0,0 +1,7 @@
+import { listGeneratedDocs } from '../generated/loader';
+import { DocsReferenceIndexClient } from './DocsReferenceIndexClient';
+
+export async function DocsReferenceIndexPage() {
+  const entries = await listGeneratedDocs();
+  return <DocsReferenceIndexClient entries={entries} />;
+}

package/src/components/docs/reference/DocsReferencePage.tsx

@@ -0,0 +1,11 @@
+import type { DocsIndexEntry } from '../generated/docs-index.generated';
+import { DocsReferenceContent } from './DocsReferenceContent';
+
+interface DocsReferencePageProps {
+  entry: DocsIndexEntry;
+  content: string;
+}
+
+export function DocsReferencePage({ entry, content }: DocsReferencePageProps) {
+  return <DocsReferenceContent entry={entry} content={content} />;
+}

package/src/components/docs/reference/docsMarkdownParser.ts

@@ -0,0 +1,99 @@
+export type DocsMarkdownBlock =
+  | { type: 'heading'; level: number; text: string }
+  | { type: 'paragraph'; text: string }
+  | { type: 'list'; ordered: boolean; items: string[] }
+  | { type: 'code'; language?: string; code: string }
+  | { type: 'quote'; text: string };
+const METADATA_SECTION = /^##\s+Metadata[\s\S]*?(?=^##\s|^#\s|Z)/m;
+function stripMetadata(content: string) {
+  const withoutTitle = content.replace(/^#\s+.*\n+/m, '');
+  return withoutTitle.replace(METADATA_SECTION, '');
+}
+function isBlockStart(line: string) {
+  return (
+    /^#{1,4}\s+/.test(line) ||
+    /^```/.test(line) ||
+    /^\s*[-*]\s+/.test(line) ||
+    /^\s*\d+\.\s+/.test(line) ||
+    /^>\s+/.test(line)
+  );
+}
+export function parseDocsMarkdown(content: string): DocsMarkdownBlock[] {
+  const lines = stripMetadata(content).split(/\r?\n/);
+  const blocks: DocsMarkdownBlock[] = [];
+  let i = 0;
+  while (i < lines.length) {
+    const line = lines[i] ?? '';
+    if (line.startsWith('<!-- @generated')) {
+      i += 1;
+      continue;
+    }
+
+    const trimmed = line.trim();
+    if (!trimmed) {
+      i += 1;
+      continue;
+    }
+    if (trimmed.startsWith('```')) {
+      const language = trimmed.slice(3).trim();
+      const codeLines: string[] = [];
+      i += 1;
+      while (i < lines.length && !(lines[i] ?? '').trim().startsWith('```')) {
+        codeLines.push(lines[i] ?? '');
+        i += 1;
+      }
+      i += 1;
+      blocks.push({
+        type: 'code',
+        language: language || 'text',
+        code: codeLines.join('\n'),
+      });
+      continue;
+    }
+    if (/^#{1,4}\s+/.test(trimmed)) {
+      const level = trimmed.match(/^#{1,4}/)?.[0].length ?? 2;
+      blocks.push({
+        type: 'heading',
+        level,
+        text: trimmed.replace(/^#{1,4}\s+/, ''),
+      });
+      i += 1;
+      continue;
+    }
+    if (/^>\s+/.test(trimmed)) {
+      const quoteLines: string[] = [];
+      while (i < lines.length && /^>\s+/.test((lines[i] ?? '').trim())) {
+        quoteLines.push((lines[i] ?? '').trim().replace(/^>\s+/, ''));
+        i += 1;
+      }
+      blocks.push({ type: 'quote', text: quoteLines.join(' ') });
+      continue;
+    }
+    if (/^[-*]\s+/.test(trimmed) || /^\d+\.\s+/.test(trimmed)) {
+      const ordered = /^\d+\.\s+/.test(trimmed);
+      const items: string[] = [];
+      while (i < lines.length && isBlockStart((lines[i] ?? '').trim())) {
+        const itemLine = (lines[i] ?? '').trim();
+        if (ordered && /^\d+\.\s+/.test(itemLine)) {
+          items.push(itemLine.replace(/^\d+\.\s+/, ''));
+        } else if (!ordered && /^[-*]\s+/.test(itemLine)) {
+          items.push(itemLine.replace(/^[-*]\s+/, ''));
+        } else {
+          break;
+        }
+        i += 1;
+      }
+      blocks.push({ type: 'list', ordered, items });
+      continue;
+    }
+    const paragraphLines: string[] = [];
+    while (i < lines.length && !isBlockStart((lines[i] ?? '').trim())) {
+      const paragraphLine = (lines[i] ?? '').trim();
+      if (!paragraphLine) break;
+      paragraphLines.push(paragraphLine);
+      i += 1;
+    }
+    blocks.push({ type: 'paragraph', text: paragraphLines.join(' ') });
+  }
+  return blocks;
+}

package/src/components/docs/reference/index.ts

@@ -0,0 +1,2 @@
+export { DocsReferenceIndexPage } from './DocsReferenceIndexPage';
+export { DocsReferencePage } from './DocsReferencePage';

package/src/components/docs/safety/SafetyAuditingPage.tsx

@@ -0,0 +1,238 @@
+import Link from '@contractspec/lib.ui-link';
+import { ChevronRight } from 'lucide-react';
+
+// export const metadata = {
+//   title: 'Audit Logs: ContractSpec Docs',
+//   description:
+//     'Learn how ContractSpec captures and stores audit logs for accountability, security, compliance, and debugging.',
+// };
+
+export function SafetyAuditingPage() {
+  return (
+    <div className="space-y-8">
+      <div className="space-y-4">
+        <h1 className="text-4xl font-bold">Audit Logs</h1>
+        <p className="text-muted-foreground">
+          An <strong>audit log</strong> (also called an audit trail) is a
+          chronological record of system activities. According to{' '}
+          <a
+            href="https://www.sumologic.com/glossary/audit-log/"
+            target="_blank"
+            rel="noopener noreferrer"
+            className="text-violet-400 hover:text-violet-300"
+          >
+            Sumo Logic
+          </a>
+          , audit logs "provide a detailed record of events and changes within a
+          system, enabling organizations to track user actions, system changes,
+          and access to sensitive data."
+        </p>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Why audit logs matter</h2>
+        <div className="space-y-3">
+          <div>
+            <h3 className="text-lg font-semibold">Accountability</h3>
+            <p className="text-muted-foreground">
+              Audit logs answer the question "who did what, when?" This is
+              essential for holding users and administrators accountable for
+              their actions. If data is deleted or modified, the audit log shows
+              exactly who made the change.
+            </p>
+          </div>
+          <div>
+            <h3 className="text-lg font-semibold">Security</h3>
+            <p className="text-muted-foreground">
+              Audit logs help detect and investigate security incidents. For
+              example, if an attacker gains unauthorized access, the logs reveal
+              which resources they accessed and what actions they performed.
+              This information is critical for incident response and forensics.
+            </p>
+          </div>
+          <div>
+            <h3 className="text-lg font-semibold">Compliance</h3>
+            <p className="text-muted-foreground">
+              Many regulations (GDPR, HIPAA, SOC 2, PCI DSS) require
+              organizations to maintain audit logs. These logs must be
+              tamper-evident, retained for a specified period, and available for
+              inspection by auditors.
+            </p>
+          </div>
+          <div>
+            <h3 className="text-lg font-semibold">Debugging</h3>
+            <p className="text-muted-foreground">
+              When something goes wrong in production, audit logs provide a
+              detailed timeline of events leading up to the failure. This makes
+              it much easier to diagnose and fix issues.
+            </p>
+          </div>
+        </div>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">What ContractSpec logs</h2>
+        <p className="text-muted-foreground">
+          ContractSpec automatically logs every significant operation,
+          including:
+        </p>
+        <ul className="text-muted-foreground list-inside list-disc space-y-2">
+          <li>
+            <strong>API calls</strong> – Every invocation of a capability,
+            including inputs, outputs, and the user who made the call.
+          </li>
+          <li>
+            <strong>Policy decisions</strong> – Every decision made by the{' '}
+            <Link
+              href="/docs/safety/pdp"
+              className="text-violet-400 hover:text-violet-300"
+            >
+              Policy Decision Point
+            </Link>
+            , including the rule that matched and the reason for the decision.
+          </li>
+          <li>
+            <strong>Data access</strong> – Every query to a data view, including
+            which fields were accessed and whether any were redacted.
+          </li>
+          <li>
+            <strong>Workflow execution</strong> – Every step in a workflow,
+            including retries, compensations, and failures.
+          </li>
+          <li>
+            <strong>Administrative actions</strong> – Spec deployments,
+            configuration changes, user role assignments, and other privileged
+            operations.
+          </li>
+          <li>
+            <strong>Authentication events</strong> – Login attempts, password
+            resets, and session expirations.
+          </li>
+        </ul>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Audit log format</h2>
+        <p className="text-muted-foreground">
+          Each audit log entry is a structured JSON object containing:
+        </p>
+        <div className="bg-background/50 border-border text-muted-foreground overflow-x-auto rounded-lg border p-4 font-mono text-sm">
+          <pre>{`{
+  "timestamp": "2025-11-13T14:32:15.123Z",
+  "eventId": "evt_abc123",
+  "eventType": "capability.invoked",
+  "actor": {
+    "userId": "user_xyz789",
+    "role": "admin",
+    "ipAddress": "203.0.113.42"
+  },
+  "resource": {
+    "type": "capability",
+    "id": "transferFunds",
+    "version": "1.2.0"
+  },
+  "action": "execute",
+  "result": "success",
+  "metadata": {
+    "inputs": {
+      "recipient": "user_def456",
+      "amount": 100.00
+    },
+    "outputs": {
+      "transactionId": "txn_ghi789",
+      "timestamp": "2025-11-13T14:32:15.456Z"
+    }
+  },
+  "policyDecision": {
+    "decision": "PERMIT",
+    "ruleId": "allow-admin-transfers",
+    "reason": "User has admin role"
+  }
+}`}</pre>
+        </div>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Storage and retention</h2>
+        <p className="text-muted-foreground">
+          Audit logs are stored in a tamper-evident append-only log. Once
+          written, entries cannot be modified or deleted. This ensures the
+          integrity of the audit trail.
+        </p>
+        <p className="text-muted-foreground">
+          ContractSpec supports multiple storage backends:
+        </p>
+        <ul className="text-muted-foreground list-inside list-disc space-y-2">
+          <li>
+            <strong>Local file system</strong> – For development and testing.
+          </li>
+          <li>
+            <strong>Cloud object storage</strong> – S3, GCS, or Azure Blob
+            Storage for production.
+          </li>
+          <li>
+            <strong>SIEM integration</strong> – Forward logs to Splunk, Datadog,
+            or other security information and event management systems.
+          </li>
+        </ul>
+        <p className="text-muted-foreground">
+          You can configure retention policies to automatically archive or
+          delete old logs after a specified period (e.g., 7 years for GDPR
+          compliance).
+        </p>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Querying audit logs</h2>
+        <p className="text-muted-foreground">
+          ContractSpec provides a query API for searching audit logs. You can
+          filter by:
+        </p>
+        <ul className="text-muted-foreground list-inside list-disc space-y-2">
+          <li>Time range</li>
+          <li>Event type</li>
+          <li>Actor (user ID, role, IP address)</li>
+          <li>Resource (capability, data view, workflow)</li>
+          <li>Result (success, failure, denied)</li>
+        </ul>
+        <p className="text-muted-foreground">
+          Example query: "Show all failed login attempts from IP address
+          203.0.113.42 in the last 24 hours."
+        </p>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Best practices</h2>
+        <ul className="text-muted-foreground list-inside list-disc space-y-2">
+          <li>
+            <strong>Review logs regularly</strong> – Set up alerts for
+            suspicious activity (e.g., repeated failed login attempts,
+            unauthorized access attempts).
+          </li>
+          <li>
+            <strong>Protect log access</strong> – Only authorized personnel
+            should be able to view audit logs. Use role-based access control to
+            restrict access.
+          </li>
+          <li>
+            <strong>Retain logs long enough</strong> – Check your compliance
+            requirements and configure retention policies accordingly.
+          </li>
+          <li>
+            <strong>Test log integrity</strong> – Periodically verify that logs
+            have not been tampered with by checking cryptographic signatures.
+          </li>
+        </ul>
+      </div>
+
+      <div className="flex items-center gap-4 pt-4">
+        <Link href="/docs/safety/pdp" className="btn-ghost">
+          Previous: Policy Decision Points
+        </Link>
+        <Link href="/docs/safety/migrations" className="btn-primary">
+          Next: Migrations <ChevronRight size={16} />
+        </Link>
+      </div>
+    </div>
+  );
+}