@lssm/example.learning-journey-registry 0.0.0-canary-20251212230121 → 0.0.0-canary-20251215220103

package/dist/libs/contracts/src/docs/tech/telemetry-ingest.docblock.js

@@ -0,0 +1,122 @@
+import{registerDocBlocks as e}from"../registry.js";e([{id:`docs.tech.telemetry.ingest`,title:`Telemetry Ingest Endpoint`,summary:`Server-side telemetry ingestion for ContractSpec clients (VS Code extension, CLI, etc.).`,kind:`reference`,visibility:`internal`,route:`/docs/tech/telemetry/ingest`,tags:[`telemetry`,`api`,`posthog`,`analytics`],body:`# Telemetry Ingest Endpoint
+
+The ContractSpec API provides a telemetry ingest endpoint for clients to send product analytics events.
+
+## Endpoint
+
+\`\`\`
+POST /api/telemetry/ingest
+\`\`\`
+
+## Request
+
+\`\`\`json
+{
+  "event": "contractspec.vscode.command_run",
+  "distinct_id": "client-uuid",
+  "properties": {
+    "command": "validate"
+  },
+  "timestamp": "2024-01-15T10:30:00.000Z"
+}
+\`\`\`
+
+### Headers
+
+| Header | Description |
+|--------|-------------|
+| \`x-contractspec-client-id\` | Optional client identifier (used as fallback for distinct_id) |
+| \`Content-Type\` | Must be \`application/json\` |
+
+### Body
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| \`event\` | string | Yes | Event name (e.g., \`contractspec.vscode.activated\`) |
+| \`distinct_id\` | string | Yes | Anonymous client identifier |
+| \`properties\` | object | No | Event properties |
+| \`timestamp\` | string | No | ISO 8601 timestamp |
+
+## Response
+
+\`\`\`json
+{
+  "success": true
+}
+\`\`\`
+
+## Configuration
+
+The endpoint requires \`POSTHOG_PROJECT_KEY\` environment variable to be set. If not configured, events are accepted but not forwarded.
+
+| Environment Variable | Description | Default |
+|---------------------|-------------|---------|
+| \`POSTHOG_HOST\` | PostHog host URL | \`https://eu.posthog.com\` |
+| \`POSTHOG_PROJECT_KEY\` | PostHog project API key | (required) |
+
+## Privacy
+
+- No PII is collected or stored
+- \`distinct_id\` is an anonymous client-generated UUID
+- File paths and source code are never included in events
+- Respects VS Code telemetry settings on the client side
+
+## Events
+
+### Extension Events
+
+| Event | Description | Properties |
+|-------|-------------|------------|
+| \`contractspec.vscode.activated\` | Extension activated | \`version\` |
+| \`contractspec.vscode.command_run\` | Command executed | \`command\` |
+| \`contractspec.vscode.mcp_call\` | MCP call made | \`endpoint\`, \`tool\` |
+
+### API Events
+
+| Event | Description | Properties |
+|-------|-------------|------------|
+| \`contractspec.api.mcp_request\` | MCP request processed | \`endpoint\`, \`method\`, \`success\`, \`duration_ms\` |
+`},{id:`docs.tech.telemetry.hybrid`,title:`Hybrid Telemetry Model`,summary:`How ContractSpec clients choose between direct PostHog and API-routed telemetry.`,kind:`usage`,visibility:`internal`,route:`/docs/tech/telemetry/hybrid`,tags:[`telemetry`,`architecture`,`posthog`],body:`# Hybrid Telemetry Model
+
+ContractSpec uses a hybrid telemetry model where clients can send events either directly to PostHog or via the API server.
+
+## Decision Flow
+
+\`\`\`
+Is contractspec.api.baseUrl configured?
+├── Yes → Send via /api/telemetry/ingest
+└── No → Is posthogProjectKey configured?
+    ├── Yes → Send directly to PostHog
+    └── No → Telemetry disabled
+\`\`\`
+
+## Benefits
+
+### Direct PostHog
+- No server dependency
+- Works offline (with batching)
+- Lower latency
+
+### Via API
+- Centralized key management (no client-side keys)
+- Server-side enrichment and validation
+- Rate limiting and abuse prevention
+- Easier migration to other providers
+
+## Recommendation
+
+- **Development**: Use direct PostHog with a dev project key
+- **Production**: Route via API for better governance
+
+## Future: OpenTelemetry
+
+The current PostHog implementation is behind a simple interface that can be swapped for OpenTelemetry:
+
+\`\`\`typescript
+interface TelemetryClient {
+  send(event: TelemetryEvent): Promise<void>;
+}
+\`\`\`
+
+This allows future migration without changing client code.
+`}]);

package/dist/libs/contracts/src/docs/tech/vscode-extension.docblock.js

@@ -0,0 +1,68 @@
+import{registerDocBlocks as e}from"../registry.js";e([{id:`docs.tech.vscode.extension`,title:`ContractSpec VS Code Extension`,summary:`VS Code extension for spec-first development with validation, scaffolding, and MCP integration.`,kind:`reference`,visibility:`public`,route:`/docs/tech/vscode/extension`,tags:[`vscode`,`extension`,`tooling`,`dx`],body:`# ContractSpec VS Code Extension
+
+The ContractSpec VS Code extension provides spec-first development tooling directly in your editor.
+
+## Features
+
+- **Real-time Validation**: Get instant feedback on spec errors and warnings as you save files
+- **Build/Scaffold**: Generate handler and component skeletons from specs (no AI required)
+- **Spec Explorer**: List and navigate all specs in your workspace
+- **Dependency Analysis**: Visualize spec dependencies and detect cycles
+- **MCP Integration**: Search ContractSpec documentation via Model Context Protocol
+- **Snippets**: Code snippets for common ContractSpec patterns
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| \`ContractSpec: Validate Current Spec\` | Validate the currently open spec file |
+| \`ContractSpec: Validate All Specs\` | Validate all spec files in the workspace |
+| \`ContractSpec: Build/Scaffold\` | Generate handler/component from the current spec |
+| \`ContractSpec: List All Specs\` | Show all specs in the workspace |
+| \`ContractSpec: Analyze Dependencies\` | Analyze and visualize spec dependencies |
+| \`ContractSpec: Search Docs (MCP)\` | Search documentation via MCP |
+
+## Configuration
+
+| Setting | Description | Default |
+|---------|-------------|---------|
+| \`contractspec.api.baseUrl\` | Base URL for ContractSpec API (enables MCP + remote telemetry) | \`""\` |
+| \`contractspec.telemetry.posthogHost\` | PostHog host URL for direct telemetry | \`"https://eu.posthog.com"\` |
+| \`contractspec.telemetry.posthogProjectKey\` | PostHog project key for direct telemetry | \`""\` |
+| \`contractspec.validation.onSave\` | Run validation on save | \`true\` |
+| \`contractspec.validation.onOpen\` | Run validation on open | \`true\` |
+
+## Architecture
+
+The extension uses:
+- \`@lssm/module.contractspec-workspace\` for pure analysis + templates
+- \`@lssm/bundle.contractspec-workspace\` for workspace services + adapters
+
+This allows the extension to work without requiring the CLI to be installed.
+
+## Telemetry
+
+The extension uses a hybrid telemetry approach:
+1. If \`contractspec.api.baseUrl\` is configured → send to API \`/api/telemetry/ingest\`
+2. Otherwise → send directly to PostHog (if project key configured)
+
+Telemetry respects VS Code's telemetry settings. No file paths, source code, or PII is collected.
+`},{id:`docs.tech.vscode.snippets`,title:`ContractSpec Snippets`,summary:`Code snippets for common ContractSpec patterns in VS Code.`,kind:`reference`,visibility:`public`,route:`/docs/tech/vscode/snippets`,tags:[`vscode`,`snippets`,`dx`],body:`# ContractSpec Snippets
+
+The VS Code extension includes snippets for common ContractSpec patterns.
+
+## Available Snippets
+
+| Prefix | Description |
+|--------|-------------|
+| \`contractspec-command\` | Create a new command (write operation) |
+| \`contractspec-query\` | Create a new query (read-only operation) |
+| \`contractspec-event\` | Create a new event |
+| \`contractspec-docblock\` | Create a new DocBlock |
+| \`contractspec-telemetry\` | Create a new TelemetrySpec |
+| \`contractspec-presentation\` | Create a new Presentation |
+
+## Usage
+
+Type the prefix in a TypeScript file and press Tab to expand the snippet. Tab through the placeholders to fill in your values.
+`}]);

package/dist/tracks.js

@@ -1 +1 @@
-import{crmLearningTracks as e}from"@lssm/example.learning-journey.crm-onboarding/track";import{drillTracks as t}from"@lssm/example.learning-journey.duo-drills/track";import{ambientCoachTracks as n}from"@lssm/example.learning-journey.ambient-coach/track";import{questTracks as r}from"@lssm/example.learning-journey.quest-challenges/track";import{platformLearningTracks as i}from"@lssm/example.learning-journey.platform-tour/track";import{studioLearningTracks as a}from"@lssm/example.learning-journey.studio-onboarding/track";const o=e=>({id:e.id,title:e.title,description:e.description,completionEvent:e.completion.eventName,completionCondition:e.completion,xpReward:e.xpReward,isRequired:e.isRequired,canSkip:e.canSkip,actionUrl:e.actionUrl,actionLabel:e.actionLabel,availability:e.availability,metadata:e.metadata}),s=e=>({id:e.id,name:e.name,description:e.description,productId:e.productId,targetUserSegment:e.targetUserSegment,targetRole:e.targetRole,totalXp:e.totalXp,streakRule:e.streakRule,completionRewards:e.completionRewards,steps:e.steps.map(o),metadata:e.metadata}),c=[...a,...i,...e,...t,...n,...r],l=c.map(s);export{e as crmLearningTracks,c as learningJourneyTracks,o as mapStep,s as mapTrackSpecToDto,l as onboardingTrackCatalog,i as platformLearningTracks,a as studioLearningTracks};
+import{crmLearningTracks as e}from"@lssm/example.learning-journey-crm-onboarding/track";import{drillTracks as t}from"@lssm/example.learning-journey-duo-drills/track";import{ambientCoachTracks as n}from"@lssm/example.learning-journey-ambient-coach/track";import{questTracks as r}from"@lssm/example.learning-journey-quest-challenges/track";import{platformLearningTracks as i}from"@lssm/example.learning-journey-platform-tour/track";import{studioLearningTracks as a}from"@lssm/example.learning-journey-studio-onboarding/track";const o=e=>({id:e.id,title:e.title,description:e.description,completionEvent:e.completion.eventName,completionCondition:e.completion,xpReward:e.xpReward,isRequired:e.isRequired,canSkip:e.canSkip,actionUrl:e.actionUrl,actionLabel:e.actionLabel,availability:e.availability,metadata:e.metadata}),s=e=>({id:e.id,name:e.name,description:e.description,productId:e.productId,targetUserSegment:e.targetUserSegment,targetRole:e.targetRole,totalXp:e.totalXp,streakRule:e.streakRule,completionRewards:e.completionRewards,steps:e.steps.map(o),metadata:e.metadata}),c=[...a,...i,...e,...t,...n,...r],l=c.map(s);export{e as crmLearningTracks,c as learningJourneyTracks,o as mapStep,s as mapTrackSpecToDto,l as onboardingTrackCatalog,i as platformLearningTracks,a as studioLearningTracks};

package/example.ts

@@ -0,0 +1 @@
+export { default } from './src/example';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lssm/example.learning-journey-registry",
-  "version": "0.0.0-canary-20251212230121",
+  "version": "0.0.0-canary-20251215220103",
   "description": "Registry that aggregates learning journey example tracks.",
   "type": "module",
   "main": "./dist/index.js",
@@ -11,6 +11,7 @@
     "./api-types": "./src/api-types.ts",
     "./docs": "./src/docs/index.ts",
     "./docs/learning-journey-registry.docblock": "./src/docs/learning-journey-registry.docblock.ts",
+    "./example": "./src/example.ts",
     "./presentations": "./src/presentations/index.ts",
     "./progress-store": "./src/progress-store.ts",
     "./tracks": "./src/tracks.ts",
@@ -30,28 +31,28 @@
     "lint:check": "eslint src"
   },
   "dependencies": {
-    "@lssm/example.learning-journey.ambient-coach": "workspace:*",
-    "@lssm/example.learning-journey.duo-drills": "workspace:*",
-    "@lssm/example.learning-journey.crm-onboarding": "workspace:*",
-    "@lssm/example.learning-journey.platform-tour": "workspace:*",
-    "@lssm/example.learning-journey.quest-challenges": "workspace:*",
-    "@lssm/example.learning-journey.studio-onboarding": "workspace:*",
+    "@lssm/example.learning-journey-ambient-coach": "workspace:*",
+    "@lssm/example.learning-journey-duo-drills": "workspace:*",
+    "@lssm/example.learning-journey-crm-onboarding": "workspace:*",
+    "@lssm/example.learning-journey-platform-tour": "workspace:*",
+    "@lssm/example.learning-journey-quest-challenges": "workspace:*",
+    "@lssm/example.learning-journey-studio-onboarding": "workspace:*",
     "@lssm/example.learning-journey-ui-shared": "workspace:*",
     "@lssm/example.learning-journey-ui-gamified": "workspace:*",
     "@lssm/example.learning-journey-ui-onboarding": "workspace:*",
     "@lssm/example.learning-journey-ui-coaching": "workspace:*",
     "@lssm/module.learning-journey": "workspace:*",
-    "react": "^19.1.0"
+    "react": "^19.2.3"
   },
   "devDependencies": {
     "@lssm/tool.tsdown": "workspace:*",
     "@lssm/tool.typescript": "workspace:*",
     "@types/react": "^19.1.6",
-    "tsdown": "^0.17.0",
+    "tsdown": "^0.17.4",
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "react": "^18.0.0 || ^19.0.0"
+    "react": "^19.2.3"
   },
   "module": "./dist/index.js",
   "publishConfig": {
@@ -61,6 +62,7 @@
       "./api-types": "./dist/api-types.js",
       "./docs": "./dist/docs/index.js",
       "./docs/learning-journey-registry.docblock": "./dist/docs/learning-journey-registry.docblock.js",
+      "./example": "./dist/example.js",
       "./presentations": "./dist/presentations/index.js",
       "./progress-store": "./dist/progress-store.js",
       "./tracks": "./dist/tracks.js",

package/src/example.ts

@@ -0,0 +1,24 @@
+const example = {
+  id: 'learning-journey-registry',
+  title: 'Learning Journey Registry',
+  summary:
+    'Registry of learning journey tracks + presentations + UI mini-app bindings.',
+  tags: ['learning', 'journey', 'registry'],
+  kind: 'library',
+  visibility: 'public',
+  docs: {
+    rootDocId: 'docs.examples.learning-journey-registry',
+  },
+  entrypoints: {
+    packageName: '@lssm/example.learning-journey-registry',
+    docs: './docs',
+  },
+  surfaces: {
+    templates: true,
+    sandbox: { enabled: true, modes: ['markdown', 'specs'] },
+    studio: { enabled: true, installable: true },
+    mcp: { enabled: true },
+  },
+} as const;
+
+export default example;

package/src/index.ts

@@ -4,3 +4,4 @@ export * from './tracks';
 export * from './api';
 export * from './presentations';
 export * from './ui';
+export { default as example } from './example';

package/src/tracks.ts

@@ -4,12 +4,12 @@ import type {
   StepAvailabilitySpec,
   StepCompletionConditionSpec,
 } from '@lssm/module.learning-journey/track-spec';
-import { crmLearningTracks } from '@lssm/example.learning-journey.crm-onboarding/track';
-import { drillTracks } from '@lssm/example.learning-journey.duo-drills/track';
-import { ambientCoachTracks } from '@lssm/example.learning-journey.ambient-coach/track';
-import { questTracks } from '@lssm/example.learning-journey.quest-challenges/track';
-import { platformLearningTracks } from '@lssm/example.learning-journey.platform-tour/track';
-import { studioLearningTracks } from '@lssm/example.learning-journey.studio-onboarding/track';
+import { crmLearningTracks } from '@lssm/example.learning-journey-crm-onboarding/track';
+import { drillTracks } from '@lssm/example.learning-journey-duo-drills/track';
+import { ambientCoachTracks } from '@lssm/example.learning-journey-ambient-coach/track';
+import { questTracks } from '@lssm/example.learning-journey-quest-challenges/track';
+import { platformLearningTracks } from '@lssm/example.learning-journey-platform-tour/track';
+import { studioLearningTracks } from '@lssm/example.learning-journey-studio-onboarding/track';
 
 export interface OnboardingStepDto {
   id: string;

package/src/ui/LearningMiniApp.tsx

@@ -119,4 +119,3 @@ export function isLearningTemplate(
 export function getLearningTemplateIds(): LearningTemplateId[] {
   return Object.keys(TEMPLATE_TO_TRACK) as LearningTemplateId[];
 }
-

package/src/ui/index.ts

@@ -3,4 +3,3 @@ export {
   isLearningTemplate,
   getLearningTemplateIds,
 } from './LearningMiniApp';
-