@lssm/example.openbanking-powens 0.0.0-canary-20251217062139 → 0.0.0-canary-20251217072406
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.turbo/turbo-build$colon$bundle.log +74 -70
- package/.turbo/turbo-build.log +75 -29
- package/CHANGELOG.md +4 -3
- package/dist/docs/index.js +1 -1
- package/dist/docs/openbanking-powens.docblock.js +28 -12
- package/dist/example.js +39 -1
- package/dist/handlers/oauth-callback.js +63 -1
- package/dist/handlers/webhook-handler.js +87 -1
- package/dist/index.js +6 -1
- package/dist/integrations/providers-impls/dist/impls/powens-client.js +171 -1
- package/dist/integrations/providers-impls/dist/impls/powens-openbanking.js +218 -1
- package/dist/libs/contracts/dist/docs/PUBLISHING.docblock.js +16 -76
- package/dist/libs/contracts/dist/docs/accessibility_wcag_compliance_specs.docblock.js +16 -350
- package/dist/libs/contracts/dist/docs/index.js +29 -1
- package/dist/libs/contracts/dist/docs/presentations.js +71 -1
- package/dist/libs/contracts/dist/docs/registry.js +44 -1
- package/dist/libs/contracts/dist/docs/tech/PHASE_1_QUICKSTART.docblock.js +16 -383
- package/dist/libs/contracts/dist/docs/tech/PHASE_2_AI_NATIVE_OPERATIONS.docblock.js +16 -68
- package/dist/libs/contracts/dist/docs/tech/PHASE_3_AUTO_EVOLUTION.docblock.js +16 -140
- package/dist/libs/contracts/dist/docs/tech/PHASE_4_PERSONALIZATION_ENGINE.docblock.js +16 -86
- package/dist/libs/contracts/dist/docs/tech/PHASE_5_ZERO_TOUCH_OPERATIONS.docblock.js +16 -1
- package/dist/libs/contracts/dist/docs/tech/auth/better-auth-nextjs.docblock.js +24 -2
- package/dist/libs/contracts/dist/docs/tech/contracts/openapi-export.docblock.js +21 -2
- package/dist/libs/contracts/dist/docs/tech/lifecycle-stage-system.docblock.js +16 -213
- package/dist/libs/contracts/dist/docs/tech/llm/llm-integration.docblock.js +73 -5
- package/dist/libs/contracts/dist/docs/tech/mcp-endpoints.docblock.js +37 -1
- package/dist/libs/contracts/dist/docs/tech/presentation-runtime.docblock.js +16 -1
- package/dist/libs/contracts/dist/docs/tech/schema/README.docblock.js +20 -262
- package/dist/libs/contracts/dist/docs/tech/studio/learning-events.docblock.js +48 -1
- package/dist/libs/contracts/dist/docs/tech/studio/learning-journeys.docblock.js +24 -2
- package/dist/libs/contracts/dist/docs/tech/studio/platform-admin-panel.docblock.js +23 -2
- package/dist/libs/contracts/dist/docs/tech/studio/project-access-teams.docblock.js +25 -16
- package/dist/libs/contracts/dist/docs/tech/studio/project-routing.docblock.js +67 -1
- package/dist/libs/contracts/dist/docs/tech/studio/sandbox-unlogged.docblock.js +22 -2
- package/dist/libs/contracts/dist/docs/tech/studio/team-invitations.docblock.js +40 -36
- package/dist/libs/contracts/dist/docs/tech/studio/workspace-ops.docblock.js +47 -1
- package/dist/libs/contracts/dist/docs/tech/studio/workspaces.docblock.js +23 -2
- package/dist/libs/contracts/dist/docs/tech/telemetry-ingest.docblock.js +36 -3
- package/dist/libs/contracts/dist/docs/tech/templates/runtime.docblock.js +20 -1
- package/dist/libs/contracts/dist/docs/tech/vscode-extension.docblock.js +36 -3
- package/dist/libs/contracts/dist/docs/tech/workflows/overview.docblock.js +20 -1
- package/package.json +6 -5
- package/tsconfig.tsbuildinfo +1 -1
|
@@ -1,86 +1,16 @@
|
|
|
1
|
-
import{
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
Phase 4
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
### @lssm/lib.overlay-engine
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
- React hooks (\`useOverlay\`, \`useOverlayFields\`) for client-side rendering.
|
|
18
|
-
- Runtime engine audits every applied overlay for traceability.
|
|
19
|
-
|
|
20
|
-
### @lssm/lib.personalization
|
|
21
|
-
|
|
22
|
-
- Behavior tracker buffers field/feature/workflow events and exports OTel metrics.
|
|
23
|
-
- Analyzer summarizes field usage and workflow drop-offs into actionable insights.
|
|
24
|
-
- Adapter translates insights into overlay suggestions or workflow tweaks.
|
|
25
|
-
- In-memory store implementation + interface for plugging Prisma/ClickHouse later.
|
|
26
|
-
|
|
27
|
-
### @lssm/lib.workflow-composer
|
|
28
|
-
|
|
29
|
-
- \`WorkflowComposer\` merges base workflows with tenant/role/device extensions.
|
|
30
|
-
- Step injection utilities keep transitions intact and validate anchor steps.
|
|
31
|
-
- Template helpers for common tenant review/approval, plus merge helpers for multi-scope extensions.
|
|
32
|
-
|
|
33
|
-
---
|
|
34
|
-
|
|
35
|
-
## 2. Overlay Editor App
|
|
36
|
-
|
|
37
|
-
Path: \`packages/apps/overlay-editor\`
|
|
38
|
-
|
|
39
|
-
- Next.js App Router UI for toggling field visibility, renaming labels, and reordering lists.
|
|
40
|
-
- Live JSON preview powered by \`defineOverlay\`.
|
|
41
|
-
- Server action that signs overlays via PEM private keys (Ed25519 by default) using the overlay engine signer.
|
|
42
|
-
|
|
43
|
-
---
|
|
44
|
-
|
|
45
|
-
## 3. Persistence
|
|
46
|
-
|
|
47
|
-
Added Prisma models (see \`packages/libs/database/prisma/schema.prisma\`):
|
|
48
|
-
|
|
49
|
-
- \`UserBehaviorEvent\` – field/feature/workflow telemetry.
|
|
50
|
-
- \`OverlaySigningKey\` – tenant managed signing keys with revocation timestamps.
|
|
51
|
-
- \`Overlay\` – stored overlays (tenant/user/role/device scope) plus signature metadata.
|
|
52
|
-
|
|
53
|
-
---
|
|
54
|
-
|
|
55
|
-
## 4. Integration Steps
|
|
56
|
-
|
|
57
|
-
1. Track usage inside apps via \`createBehaviorTracker\`.
|
|
58
|
-
2. Periodically run \`BehaviorAnalyzer.analyze\` to generate insights.
|
|
59
|
-
3. Convert insights into OverlaySpecs or Workflow extensions.
|
|
60
|
-
4. Register tenant overlays in \`OverlayRegistry\` and serve via presentation runtimes.
|
|
61
|
-
5. Compose workflows per tenant using \`WorkflowComposer\`.
|
|
62
|
-
|
|
63
|
-
See the \`docs/tech/personalization/*\` guides for concrete examples.
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
`}]);
|
|
1
|
+
import { registerDocBlocks } from "../registry.js";
|
|
2
|
+
|
|
3
|
+
//#region ../../libs/contracts/dist/docs/tech/PHASE_4_PERSONALIZATION_ENGINE.docblock.js
|
|
4
|
+
const tech_PHASE_4_PERSONALIZATION_ENGINE_DocBlocks = [{
|
|
5
|
+
id: "docs.tech.PHASE_4_PERSONALIZATION_ENGINE",
|
|
6
|
+
title: "Phase 4: Personalization Engine",
|
|
7
|
+
summary: "**Status**: Complete",
|
|
8
|
+
kind: "reference",
|
|
9
|
+
visibility: "public",
|
|
10
|
+
route: "/docs/tech/PHASE_4_PERSONALIZATION_ENGINE",
|
|
11
|
+
tags: ["tech", "PHASE_4_PERSONALIZATION_ENGINE"],
|
|
12
|
+
body: "# Phase 4: Personalization Engine\n\n**Status**: Complete \n**Last updated**: 2025-11-21\n\nPhase 4 unlocks tenant-scoped personalization with zero bespoke code. We shipped three new libraries, a signing-aware Overlay editor, and the persistence layer required to observe usage and apply overlays safely.\n\n---\n\n## 1. Libraries\n\n### @lssm/lib.overlay-engine\n\n- OverlaySpec types + validator mirror the public spec.\n- Cryptographic signer (`ed25519`, `rsa-pss-sha256`) with canonical JSON serialization.\n- Registry that merges tenant/role/user/device overlays with predictable specificity.\n- React hooks (`useOverlay`, `useOverlayFields`) for client-side rendering.\n- Runtime engine audits every applied overlay for traceability.\n\n### @lssm/lib.personalization\n\n- Behavior tracker buffers field/feature/workflow events and exports OTel metrics.\n- Analyzer summarizes field usage and workflow drop-offs into actionable insights.\n- Adapter translates insights into overlay suggestions or workflow tweaks.\n- In-memory store implementation + interface for plugging Prisma/ClickHouse later.\n\n### @lssm/lib.workflow-composer\n\n- `WorkflowComposer` merges base workflows with tenant/role/device extensions.\n- Step injection utilities keep transitions intact and validate anchor steps.\n- Template helpers for common tenant review/approval, plus merge helpers for multi-scope extensions.\n\n---\n\n## 2. Overlay Editor App\n\nPath: `packages/apps/overlay-editor`\n\n- Next.js App Router UI for toggling field visibility, renaming labels, and reordering lists.\n- Live JSON preview powered by `defineOverlay`.\n- Server action that signs overlays via PEM private keys (Ed25519 by default) using the overlay engine signer.\n\n---\n\n## 3. Persistence\n\nAdded Prisma models (see `packages/libs/database/prisma/schema.prisma`):\n\n- `UserBehaviorEvent` – field/feature/workflow telemetry.\n- `OverlaySigningKey` – tenant managed signing keys with revocation timestamps.\n- `Overlay` – stored overlays (tenant/user/role/device scope) plus signature metadata.\n\n---\n\n## 4. Integration Steps\n\n1. Track usage inside apps via `createBehaviorTracker`.\n2. Periodically run `BehaviorAnalyzer.analyze` to generate insights.\n3. Convert insights into OverlaySpecs or Workflow extensions.\n4. Register tenant overlays in `OverlayRegistry` and serve via presentation runtimes.\n5. Compose workflows per tenant using `WorkflowComposer`.\n\nSee the `docs/tech/personalization/*` guides for concrete examples.\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n"
|
|
13
|
+
}];
|
|
14
|
+
registerDocBlocks(tech_PHASE_4_PERSONALIZATION_ENGINE_DocBlocks);
|
|
15
|
+
|
|
16
|
+
//#endregion
|
|
@@ -1 +1,16 @@
|
|
|
1
|
-
import{
|
|
1
|
+
import { registerDocBlocks } from "../registry.js";
|
|
2
|
+
|
|
3
|
+
//#region ../../libs/contracts/dist/docs/tech/PHASE_5_ZERO_TOUCH_OPERATIONS.docblock.js
|
|
4
|
+
const tech_PHASE_5_ZERO_TOUCH_OPERATIONS_DocBlocks = [{
|
|
5
|
+
id: "docs.tech.PHASE_5_ZERO_TOUCH_OPERATIONS",
|
|
6
|
+
title: "Phase 5: Zero-Touch Operations",
|
|
7
|
+
summary: "**Status**: In progress",
|
|
8
|
+
kind: "reference",
|
|
9
|
+
visibility: "public",
|
|
10
|
+
route: "/docs/tech/PHASE_5_ZERO_TOUCH_OPERATIONS",
|
|
11
|
+
tags: ["tech", "PHASE_5_ZERO_TOUCH_OPERATIONS"],
|
|
12
|
+
body: "# Phase 5: Zero-Touch Operations\n\n**Status**: In progress \n**Last updated**: 2025-11-21\n\nPhase 5 delivers progressive delivery, SLO intelligence, cost attribution, and anomaly-driven remediation so the platform can deploy continuously without pager rotations.\n\n---\n\n## 1. New Libraries\n\n### @lssm/lib.progressive-delivery\n- `DeploymentStrategy` types capture canary vs blue-green rollouts.\n- `CanaryController` + `CanaryAnalyzer` orchestrate stage evaluation against telemetry thresholds.\n- `TrafficShifter` keeps stable/candidate splits in sync with feature-flag or router state.\n- `DeploymentCoordinator` drives stage progression, emits events, and triggers rollbacks.\n- `RollbackManager` encapsulates safe revert hooks (spec version revert, traffic shift, etc.).\n\n### @lssm/lib.slo\n- Declarative `SLODefinition` with latency + availability targets per capability/spec.\n- `SLOTracker` stores rolling snapshots + error budget positions.\n- `BurnRateCalculator` implements multi-window burn computations (fast vs slow burn).\n- `SLOMonitor` pushes incidents to Ops tooling automatically when burn exceeds thresholds.\n\n### @lssm/lib.cost-tracking\n- `CostTracker` normalizes DB/API/compute metrics into per-operation cost totals.\n- `BudgetAlertManager` raises tenant budget warnings (80% default) with contextual payloads.\n- `OptimizationRecommender` suggests batching, caching, or contract tweaks to cut spend.\n\n### Observability Anomaly Toolkit\n- `BaselineCalculator` establishes rolling intent metrics (latency, error rate, throughput).\n- `AnomalyDetector` flags spikes/drops via relative deltas after 10+ samples.\n- `RootCauseAnalyzer` correlates anomalies with recent deployments.\n- `AlertManager` deduplicates notifications and feeds MCP/SRE transports.\n\n---\n\n## 2. Data Model Additions\n\nFile: `packages/libs/database/prisma/schema.prisma`\n\n| Model | Purpose |\n| --- | --- |\n| `SLODefinition`, `SLOSnapshot`, `ErrorBudget`, `SLOIncident` | Persist definitions, rolling windows, and incidents. |\n| `OperationCost`, `TenantBudget`, `CostAlert`, `OptimizationSuggestion` | Track per-operation costs, budgets, and generated recommendations. |\n| `Deployment`, `DeploymentStage`, `RollbackEvent` | Audit progressive delivery runs and automated rollbacks. |\n| `MetricBaseline`, `AnomalyEvent` | Store computed baselines and anomaly evidence for training/analytics. |\n\nRun `bun database generate` after pulling to refresh the Prisma client.\n\n---\n\n## 3. Operational Flow\n\n1. **Deploy**: Define a `DeploymentStrategy` and feed telemetry via `@lssm/lib.observability`. Canary stages run automatically.\n2. **Protect**: `CanaryAnalyzer` evaluates error rate + latency thresholds. Failures trigger `RollbackManager`.\n3. **Observe**: `SLOMonitor` consumes snapshots and opens incidents when burn rate exceeds thresholds.\n4. **Optimize**: `CostTracker` aggregates spend per tenant + capability, while `OptimizationRecommender` surfaces fixes.\n5. **Detect**: Anomaly signals route to `RootCauseAnalyzer`, which links them to specific deployments for auto-rollback.\n\n---\n\n## 4. Integration Checklist\n\n1. Instrument adapters with `createTracingMiddleware({ onSample })` to feed metric points into `AnomalyDetector`.\n2. Register SLOs per critical operation (`billing.charge`, `knowledge.search`) and wire monitors to Ops notifications.\n3. Attach `CostTracker.recordSample` to workflow runners (DB instrumentation + external call wrappers).\n4. Store deployment metadata using the new Prisma models for auditing + UI surfacing.\n5. Update `@lssm/app.ops-console` (next iteration) to list deployments, SLO status, costs, and anomalies in one timeline.\n\n---\n\n## 5. Next Steps\n\n- Wire `DeploymentCoordinator` into the Contracts CLI so `contractspec deploy` can run staged rollouts.\n- Add UI for SLO dashboards (burn rate sparkline + incident feed).\n- Ship budget suggestions into Growth Agent for automated cost optimizations.\n- Connect `AnomalyEvent` stream to MCP agents for root-cause playbooks.\n"
|
|
13
|
+
}];
|
|
14
|
+
registerDocBlocks(tech_PHASE_5_ZERO_TOUCH_OPERATIONS_DocBlocks);
|
|
15
|
+
|
|
16
|
+
//#endregion
|
|
@@ -1,4 +1,22 @@
|
|
|
1
|
-
import{
|
|
1
|
+
import { registerDocBlocks } from "../../registry.js";
|
|
2
|
+
|
|
3
|
+
//#region ../../libs/contracts/dist/docs/tech/auth/better-auth-nextjs.docblock.js
|
|
4
|
+
const tech_auth_better_auth_nextjs_DocBlocks = [{
|
|
5
|
+
id: "docs.tech.auth.better-auth-nextjs",
|
|
6
|
+
title: "Better Auth + Next.js integration (ContractSpec)",
|
|
7
|
+
summary: "How ContractSpec wires Better Auth into Next.js (server config, client singleton, and proxy cookie-only redirects).",
|
|
8
|
+
kind: "reference",
|
|
9
|
+
visibility: "public",
|
|
10
|
+
route: "/docs/tech/auth/better-auth-nextjs",
|
|
11
|
+
tags: [
|
|
12
|
+
"auth",
|
|
13
|
+
"better-auth",
|
|
14
|
+
"nextjs",
|
|
15
|
+
"cookies",
|
|
16
|
+
"proxy",
|
|
17
|
+
"hmr"
|
|
18
|
+
],
|
|
19
|
+
body: `# Better Auth + Next.js integration (ContractSpec)
|
|
2
20
|
|
|
3
21
|
This repo uses Better Auth as the primary auth layer (sessions, organizations, teams, API keys, and OAuth).
|
|
4
22
|
|
|
@@ -55,4 +73,8 @@ The Next.js proxy/middleware is used for **redirect decisions only**. It must no
|
|
|
55
73
|
- \`getCookieCache(request)\`
|
|
56
74
|
|
|
57
75
|
These checks are intentionally optimistic and should only gate routing. Full authorization must still be enforced on server-side actions/routes and GraphQL resolvers.
|
|
58
|
-
`
|
|
76
|
+
`
|
|
77
|
+
}];
|
|
78
|
+
registerDocBlocks(tech_auth_better_auth_nextjs_DocBlocks);
|
|
79
|
+
|
|
80
|
+
//#endregion
|
|
@@ -1,4 +1,19 @@
|
|
|
1
|
-
import{
|
|
1
|
+
import { registerDocBlocks } from "../../registry.js";
|
|
2
|
+
|
|
3
|
+
//#region ../../libs/contracts/dist/docs/tech/contracts/openapi-export.docblock.js
|
|
4
|
+
const tech_contracts_openapi_export_DocBlocks = [{
|
|
5
|
+
id: "docs.tech.contracts.openapi-export",
|
|
6
|
+
title: "OpenAPI export (OpenAPI 3.1) from SpecRegistry",
|
|
7
|
+
summary: "Generate a deterministic OpenAPI document from a SpecRegistry using jsonSchemaForSpec + REST transport metadata.",
|
|
8
|
+
kind: "reference",
|
|
9
|
+
visibility: "public",
|
|
10
|
+
route: "/docs/tech/contracts/openapi-export",
|
|
11
|
+
tags: [
|
|
12
|
+
"contracts",
|
|
13
|
+
"openapi",
|
|
14
|
+
"rest"
|
|
15
|
+
],
|
|
16
|
+
body: `## OpenAPI export (OpenAPI 3.1) from SpecRegistry
|
|
2
17
|
|
|
3
18
|
### Purpose
|
|
4
19
|
|
|
@@ -35,4 +50,8 @@ The registry module must export one of:
|
|
|
35
50
|
|
|
36
51
|
- Responses are generated as a basic \`200\` response (plus schemas when available).
|
|
37
52
|
- Query (GET) inputs are currently represented as a JSON request body when an input schema exists.
|
|
38
|
-
- Errors are not yet expanded into OpenAPI responses; that will be added when we standardize error envelopes.`
|
|
53
|
+
- Errors are not yet expanded into OpenAPI responses; that will be added when we standardize error envelopes.`
|
|
54
|
+
}];
|
|
55
|
+
registerDocBlocks(tech_contracts_openapi_export_DocBlocks);
|
|
56
|
+
|
|
57
|
+
//#endregion
|
|
@@ -1,213 +1,16 @@
|
|
|
1
|
-
import{
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
└───────────┬──────────┘
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
└───────────┬──────────┘ └───────────┬───────────────┘
|
|
18
|
-
│ │
|
|
19
|
-
├────────────┬──────────────┤
|
|
20
|
-
▼ ▼ ▼
|
|
21
|
-
Adapters: analytics, intent, questionnaires
|
|
22
|
-
│
|
|
23
|
-
┌───────────▼──────────┐
|
|
24
|
-
│ bundles/lifecycle- │ Managed service for Studio
|
|
25
|
-
│ managed │ (REST handlers, AI agent) │
|
|
26
|
-
└───────────┬──────────┘
|
|
27
|
-
│
|
|
28
|
-
ContractSpec Studio surfaces
|
|
29
|
-
(web/mobile APIs, CLI, docs)
|
|
30
|
-
\`\`\`
|
|
31
|
-
|
|
32
|
-
- **Libraries** provide shared vocabulary.
|
|
33
|
-
- **Modules** encapsulate logic, accepting adapters to avoid environment-specific code.
|
|
34
|
-
- **Bundles** compose modules, register agents/events, and expose APIs for Studio.
|
|
35
|
-
- **Apps** (web-landing, future Studio views) consume bundle APIs; they do not reimplement logic. For web-landing we now resolve \`@lssm/bundle.contractspec-studio\` and \`@lssm/lib.database-contractspec-studio\` directly from their \`packages/.../src\` folders via \`tsconfig\` path aliases so Prisma stays on the server build and Turbopack no longer pulls the prebundled \`dist\` artifacts into client chunks.
|
|
36
|
-
|
|
37
|
-
---
|
|
38
|
-
|
|
39
|
-
### 2. Core Library (\`@lssm/lib.lifecycle\`)
|
|
40
|
-
|
|
41
|
-
- Stage enum (0–6) with metadata (\`question\`, \`signals\`, \`traps\`).
|
|
42
|
-
- Axes types (\`ProductPhase\`, \`CompanyPhase\`, \`CapitalPhase\`).
|
|
43
|
-
- \`LifecycleSignal\` (source, metric, value, timestamp).
|
|
44
|
-
- \`LifecycleMetricSnapshot\` (aggregated numbers).
|
|
45
|
-
- \`LifecycleMilestone\`, \`LifecycleAction\`, \`LifecycleAssessment\` interfaces.
|
|
46
|
-
- Utility helpers:
|
|
47
|
-
- \`formatStageSummary(stage, assessment)\`
|
|
48
|
-
- \`rankStageCandidates(scores)\`
|
|
49
|
-
|
|
50
|
-
The library exports **no runtime dependencies** so it can be imported from apps, modules, and bundles alike.
|
|
51
|
-
|
|
52
|
-
---
|
|
53
|
-
|
|
54
|
-
### 3. Lifecycle Core Module
|
|
55
|
-
|
|
56
|
-
**Location:** \`packages/modules/lifecycle-core/\`
|
|
57
|
-
|
|
58
|
-
#### Components
|
|
59
|
-
1. **StageSignalCollector**
|
|
60
|
-
- Accepts adapter interfaces:
|
|
61
|
-
- \`AnalyticsAdapter\` (pulls metrics from \`@lssm/lib.analytics\` or fixture streams).
|
|
62
|
-
- \`IntentAdapter\` (hooks into \`@lssm/lib.observability\` intent detectors or logs).
|
|
63
|
-
- \`QuestionnaireAdapter\` (loads JSON questionnaires and responses).
|
|
64
|
-
- Produces normalized \`LifecycleSignal[]\`.
|
|
65
|
-
|
|
66
|
-
2. **StageScorer**
|
|
67
|
-
- Weighted scoring model:
|
|
68
|
-
- Base weight per stage (reflecting expected maturity).
|
|
69
|
-
- Feature weights (retention, revenue, team size, qualitative feedback).
|
|
70
|
-
- Confidence computed via variance of contributing signals.
|
|
71
|
-
- Supports pluggable scoring matrices via JSON config.
|
|
72
|
-
- Accepts sparse metric snapshots; the orchestrator sanitizes metrics to numeric-only records before persisting assessments so downstream analytics stay consistent.
|
|
73
|
-
|
|
74
|
-
3. **LifecycleOrchestrator**
|
|
75
|
-
- Coordinates collectors + scorer.
|
|
76
|
-
- Returns \`LifecycleAssessment\` with:
|
|
77
|
-
- \`stage\`, \`confidence\`, \`axisSnapshot\`, \`signalsUsed\`.
|
|
78
|
-
- Recommended focus areas (high-level categories only).
|
|
79
|
-
- Emits events (internally) when stage confidence crosses thresholds (consumed later by bundle).
|
|
80
|
-
|
|
81
|
-
4. **LifecycleMilestonePlanner**
|
|
82
|
-
- Loads \`milestones-catalog.json\` (no DB).
|
|
83
|
-
- Filters upcoming milestones per stage + axis.
|
|
84
|
-
- Tracks completion using provided IDs (caller persists).
|
|
85
|
-
|
|
86
|
-
#### Data Files
|
|
87
|
-
- \`configs/stage-weights.json\`
|
|
88
|
-
- \`configs/milestones-catalog.json\`
|
|
89
|
-
- \`questionnaires/stage-readiness.json\`
|
|
90
|
-
|
|
91
|
-
#### Extension Hooks
|
|
92
|
-
- All adapters exported as TypeScript interfaces.
|
|
93
|
-
- Implementations for analytics/intent can live in bundles or apps without modifying module code.
|
|
94
|
-
|
|
95
|
-
---
|
|
96
|
-
|
|
97
|
-
### 4. Lifecycle Advisor Module
|
|
98
|
-
|
|
99
|
-
**Location:** \`packages/modules/lifecycle-advisor/\`
|
|
100
|
-
|
|
101
|
-
#### Components
|
|
102
|
-
1. **LifecycleRecommendationEngine**
|
|
103
|
-
- Consumes \`LifecycleAssessment\`.
|
|
104
|
-
- Maps gaps to \`LifecycleAction[]\` using rule tables (\`stage-playbooks.ts\`).
|
|
105
|
-
- Supports override hooks for customer-specific rules.
|
|
106
|
-
|
|
107
|
-
2. **ContractSpecLibraryRecommender**
|
|
108
|
-
- Maintains mapping from stage → recommended libraries/modules/bundles.
|
|
109
|
-
- Returns prioritized list with rationale and adoption prerequisites.
|
|
110
|
-
|
|
111
|
-
3. **LifecycleCeremonyDesigner**
|
|
112
|
-
- Provides textual/structural data for ceremonies (title, copy, animation cues, soundtrack references).
|
|
113
|
-
- Ensures low-tech friendly instructions (clear copy, undo guidance).
|
|
114
|
-
|
|
115
|
-
4. **AI Hooks**
|
|
116
|
-
- Defines prompt templates and tool manifests for lifecycle advisor agents (consumed by bundles).
|
|
117
|
-
- Keeps actual LLM integration outside module.
|
|
118
|
-
|
|
119
|
-
---
|
|
120
|
-
|
|
121
|
-
### 5. Managed Bundle (\`lifecycle-managed\`)
|
|
122
|
-
|
|
123
|
-
**Responsibilities**
|
|
124
|
-
- Wire modules together.
|
|
125
|
-
- Provide HTTP/GraphQL handlers (exact transport optional).
|
|
126
|
-
- Register LifecycleAdvisorAgent via \`@lssm/lib.ai-agent\`.
|
|
127
|
-
- LifecycleAdvisorAgent meta: domain \`operations\`, owners \`team-lifecycle\`, stability \`experimental\`, tags \`guide/lifecycle/ops\` so ops tooling can route incidents quickly.
|
|
128
|
-
- Emit lifecycle events through \`@lssm/lib.bus\` + \`@lssm/lib.analytics\`.
|
|
129
|
-
- Integrate with \`contractspec-studio\` packages:
|
|
130
|
-
- Use Studio contracts for authentication/tenant context (without accessing tenant DBs).
|
|
131
|
-
- Store assessments in Studio-managed storage abstractions (in-memory or file-based for now).
|
|
132
|
-
|
|
133
|
-
**APIs**
|
|
134
|
-
- \`POST /lifecycle/assessments\`: Accepts metrics + optional questionnaire answers. Returns \`LifecycleAssessment\`.
|
|
135
|
-
- \`GET /lifecycle/playbooks/:stage\`: Returns stage playbook + ceremonies.
|
|
136
|
-
- \`POST /lifecycle/advise\`: Invokes LifecycleAdvisorAgent with context.
|
|
137
|
-
|
|
138
|
-
**Events**
|
|
139
|
-
- \`LifecycleAssessmentCreated\`
|
|
140
|
-
- \`LifecycleStageChanged\`
|
|
141
|
-
- \`LifecycleGuidanceConsumed\`
|
|
142
|
-
|
|
143
|
-
---
|
|
144
|
-
|
|
145
|
-
### 6. Library Enhancements
|
|
146
|
-
|
|
147
|
-
| Library | Enhancement |
|
|
148
|
-
| --- | --- |
|
|
149
|
-
| \`@lssm/lib.analytics\` | Lifecycle metric collectors, helper to emit stage events, adapter implementation used by \`StageSignalCollector\`. |
|
|
150
|
-
| \`@lssm/lib.evolution\` | Accepts \`LifecycleContext\` when ranking spec anomalies/suggestions. |
|
|
151
|
-
| \`@lssm/lib.growth\` | Stage-specific experiment templates + guardrails referencing lifecycle enums. |
|
|
152
|
-
| \`@lssm/lib.observability\` | Lifecycle KPI pipeline definitions (drift detection, regression alerts). |
|
|
153
|
-
|
|
154
|
-
Each enhancement must import stage types from \`@lssm/lib.lifecycle\`.
|
|
155
|
-
|
|
156
|
-
---
|
|
157
|
-
|
|
158
|
-
### 7. Feature Flags & Progressive Delivery
|
|
159
|
-
|
|
160
|
-
- Add new flags in progressive-delivery library:
|
|
161
|
-
- \`LIFECYCLE_DETECTION_ALPHA\`
|
|
162
|
-
- \`LIFECYCLE_ADVISOR_ALPHA\`
|
|
163
|
-
- \`LIFECYCLE_MANAGED_SERVICE\`
|
|
164
|
-
- Bundles/modules should check flags before enabling workflows.
|
|
165
|
-
- Flags referenced in docs + Studio UI to avoid accidental exposure.
|
|
166
|
-
|
|
167
|
-
---
|
|
168
|
-
|
|
169
|
-
### 8. Analytics & Telemetry
|
|
170
|
-
|
|
171
|
-
- Events defined in analytics library; consumed by bundle/app:
|
|
172
|
-
- \`lifecycle_assessment_run\`
|
|
173
|
-
- \`lifecycle_stage_changed\`
|
|
174
|
-
- \`lifecycle_guidance_consumed\`
|
|
175
|
-
- Observability pipeline includes:
|
|
176
|
-
- Composite lifecycle health metric (weighted sum of KPIs).
|
|
177
|
-
- Drift detection comparing stage predictions over time.
|
|
178
|
-
- Alert manager recipes for regression (e.g., PMF drop).
|
|
179
|
-
|
|
180
|
-
---
|
|
181
|
-
|
|
182
|
-
### 9. Testing Strategy
|
|
183
|
-
|
|
184
|
-
1. **Unit**
|
|
185
|
-
- StageScorer weight matrix.
|
|
186
|
-
- RecommendationEngine mapping.
|
|
187
|
-
- Library recommender stage coverage.
|
|
188
|
-
|
|
189
|
-
2. **Contract**
|
|
190
|
-
- Adapters: ensure mock adapters satisfy interfaces.
|
|
191
|
-
- Bundles: ensure HTTP handlers respect request/response contracts even without persistence.
|
|
192
|
-
|
|
193
|
-
3. **Integration**
|
|
194
|
-
- CLI example runs detection + guidance end-to-end on fixture data.
|
|
195
|
-
- Dashboard example renders assessments, verifying JSON structures remain stable.
|
|
196
|
-
|
|
197
|
-
---
|
|
198
|
-
|
|
199
|
-
### 10. Implementation Checklist
|
|
200
|
-
|
|
201
|
-
- [ ] Documentation (product, tech, ops, user).
|
|
202
|
-
- [ ] Library creation (\`@lssm/lib.lifecycle\`).
|
|
203
|
-
- [ ] Modules (\`lifecycle-core\`, \`lifecycle-advisor\`).
|
|
204
|
-
- [ ] Bundle (\`lifecycle-managed\`) + Studio wiring.
|
|
205
|
-
- [ ] Library enhancements (analytics/evolution/growth/observability).
|
|
206
|
-
- [ ] Examples (CLI + dashboard).
|
|
207
|
-
- [ ] Feature flags + telemetry.
|
|
208
|
-
- [ ] Automated tests + fixtures.
|
|
209
|
-
|
|
210
|
-
Keep this document in sync as modules evolve. When adding new stages or axes, update \`@lssm/lib.lifecycle\` first, then cascade to adapters, then refresh docs + Studio copy.*** End Patch*** End Patch
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
`}]);
|
|
1
|
+
import { registerDocBlocks } from "../registry.js";
|
|
2
|
+
|
|
3
|
+
//#region ../../libs/contracts/dist/docs/tech/lifecycle-stage-system.docblock.js
|
|
4
|
+
const tech_lifecycle_stage_system_DocBlocks = [{
|
|
5
|
+
id: "docs.tech.lifecycle-stage-system",
|
|
6
|
+
title: "ContractSpec Lifecycle Stage System – Technical Design",
|
|
7
|
+
summary: "This document describes how ContractSpec implements lifecycle detection and guidance. It covers architecture, module boundaries, scoring heuristics, and integration points so libraries, modules, bundles, and Studio surfaces stay synchronized.",
|
|
8
|
+
kind: "reference",
|
|
9
|
+
visibility: "public",
|
|
10
|
+
route: "/docs/tech/lifecycle-stage-system",
|
|
11
|
+
tags: ["tech", "lifecycle-stage-system"],
|
|
12
|
+
body: "## ContractSpec Lifecycle Stage System – Technical Design\n\nThis document describes how ContractSpec implements lifecycle detection and guidance. It covers architecture, module boundaries, scoring heuristics, and integration points so libraries, modules, bundles, and Studio surfaces stay synchronized.\n\n---\n\n### 1. Architecture Overview\n\n```\n┌──────────────────────┐\n│ @lssm/lib.lifecycle │ Types, enums, helpers (pure data)\n└───────────┬──────────┘\n │\n┌───────────▼──────────┐ ┌───────────────────────────┐\n│ modules/lifecycle- │ │ modules/lifecycle-advisor │\n│ core (detection) │ │ (guidance & ceremonies) │\n└───────────┬──────────┘ └───────────┬───────────────┘\n │ │\n ├────────────┬──────────────┤\n ▼ ▼ ▼\n Adapters: analytics, intent, questionnaires\n │\n┌───────────▼──────────┐\n│ bundles/lifecycle- │ Managed service for Studio\n│ managed │ (REST handlers, AI agent) │\n└───────────┬──────────┘\n │\n ContractSpec Studio surfaces\n (web/mobile APIs, CLI, docs)\n```\n\n- **Libraries** provide shared vocabulary.\n- **Modules** encapsulate logic, accepting adapters to avoid environment-specific code.\n- **Bundles** compose modules, register agents/events, and expose APIs for Studio.\n- **Apps** (web-landing, future Studio views) consume bundle APIs; they do not reimplement logic. For web-landing we now resolve `@lssm/bundle.contractspec-studio` and `@lssm/lib.database-contractspec-studio` directly from their `packages/.../src` folders via `tsconfig` path aliases so Prisma stays on the server build and Turbopack no longer pulls the prebundled `dist` artifacts into client chunks.\n\n---\n\n### 2. Core Library (`@lssm/lib.lifecycle`)\n\n- Stage enum (0–6) with metadata (`question`, `signals`, `traps`).\n- Axes types (`ProductPhase`, `CompanyPhase`, `CapitalPhase`).\n- `LifecycleSignal` (source, metric, value, timestamp).\n- `LifecycleMetricSnapshot` (aggregated numbers).\n- `LifecycleMilestone`, `LifecycleAction`, `LifecycleAssessment` interfaces.\n- Utility helpers:\n - `formatStageSummary(stage, assessment)`\n - `rankStageCandidates(scores)`\n\nThe library exports **no runtime dependencies** so it can be imported from apps, modules, and bundles alike.\n\n---\n\n### 3. Lifecycle Core Module\n\n**Location:** `packages/modules/lifecycle-core/`\n\n#### Components\n1. **StageSignalCollector**\n - Accepts adapter interfaces:\n - `AnalyticsAdapter` (pulls metrics from `@lssm/lib.analytics` or fixture streams).\n - `IntentAdapter` (hooks into `@lssm/lib.observability` intent detectors or logs).\n - `QuestionnaireAdapter` (loads JSON questionnaires and responses).\n - Produces normalized `LifecycleSignal[]`.\n\n2. **StageScorer**\n - Weighted scoring model:\n - Base weight per stage (reflecting expected maturity).\n - Feature weights (retention, revenue, team size, qualitative feedback).\n - Confidence computed via variance of contributing signals.\n - Supports pluggable scoring matrices via JSON config.\n - Accepts sparse metric snapshots; the orchestrator sanitizes metrics to numeric-only records before persisting assessments so downstream analytics stay consistent.\n\n3. **LifecycleOrchestrator**\n - Coordinates collectors + scorer.\n - Returns `LifecycleAssessment` with:\n - `stage`, `confidence`, `axisSnapshot`, `signalsUsed`.\n - Recommended focus areas (high-level categories only).\n - Emits events (internally) when stage confidence crosses thresholds (consumed later by bundle).\n\n4. **LifecycleMilestonePlanner**\n - Loads `milestones-catalog.json` (no DB).\n - Filters upcoming milestones per stage + axis.\n - Tracks completion using provided IDs (caller persists).\n\n#### Data Files\n- `configs/stage-weights.json`\n- `configs/milestones-catalog.json`\n- `questionnaires/stage-readiness.json`\n\n#### Extension Hooks\n- All adapters exported as TypeScript interfaces.\n- Implementations for analytics/intent can live in bundles or apps without modifying module code.\n\n---\n\n### 4. Lifecycle Advisor Module\n\n**Location:** `packages/modules/lifecycle-advisor/`\n\n#### Components\n1. **LifecycleRecommendationEngine**\n - Consumes `LifecycleAssessment`.\n - Maps gaps to `LifecycleAction[]` using rule tables (`stage-playbooks.ts`).\n - Supports override hooks for customer-specific rules.\n\n2. **ContractSpecLibraryRecommender**\n - Maintains mapping from stage → recommended libraries/modules/bundles.\n - Returns prioritized list with rationale and adoption prerequisites.\n\n3. **LifecycleCeremonyDesigner**\n - Provides textual/structural data for ceremonies (title, copy, animation cues, soundtrack references).\n - Ensures low-tech friendly instructions (clear copy, undo guidance).\n\n4. **AI Hooks**\n - Defines prompt templates and tool manifests for lifecycle advisor agents (consumed by bundles).\n - Keeps actual LLM integration outside module.\n\n---\n\n### 5. Managed Bundle (`lifecycle-managed`)\n\n**Responsibilities**\n- Wire modules together.\n- Provide HTTP/GraphQL handlers (exact transport optional).\n- Register LifecycleAdvisorAgent via `@lssm/lib.ai-agent`.\n- LifecycleAdvisorAgent meta: domain `operations`, owners `team-lifecycle`, stability `experimental`, tags `guide/lifecycle/ops` so ops tooling can route incidents quickly.\n- Emit lifecycle events through `@lssm/lib.bus` + `@lssm/lib.analytics`.\n- Integrate with `contractspec-studio` packages:\n - Use Studio contracts for authentication/tenant context (without accessing tenant DBs).\n - Store assessments in Studio-managed storage abstractions (in-memory or file-based for now).\n\n**APIs**\n- `POST /lifecycle/assessments`: Accepts metrics + optional questionnaire answers. Returns `LifecycleAssessment`.\n- `GET /lifecycle/playbooks/:stage`: Returns stage playbook + ceremonies.\n- `POST /lifecycle/advise`: Invokes LifecycleAdvisorAgent with context.\n\n**Events**\n- `LifecycleAssessmentCreated`\n- `LifecycleStageChanged`\n- `LifecycleGuidanceConsumed`\n\n---\n\n### 6. Library Enhancements\n\n| Library | Enhancement |\n| --- | --- |\n| `@lssm/lib.analytics` | Lifecycle metric collectors, helper to emit stage events, adapter implementation used by `StageSignalCollector`. |\n| `@lssm/lib.evolution` | Accepts `LifecycleContext` when ranking spec anomalies/suggestions. |\n| `@lssm/lib.growth` | Stage-specific experiment templates + guardrails referencing lifecycle enums. |\n| `@lssm/lib.observability` | Lifecycle KPI pipeline definitions (drift detection, regression alerts). |\n\nEach enhancement must import stage types from `@lssm/lib.lifecycle`.\n\n---\n\n### 7. Feature Flags & Progressive Delivery\n\n- Add new flags in progressive-delivery library:\n - `LIFECYCLE_DETECTION_ALPHA`\n - `LIFECYCLE_ADVISOR_ALPHA`\n - `LIFECYCLE_MANAGED_SERVICE`\n- Bundles/modules should check flags before enabling workflows.\n- Flags referenced in docs + Studio UI to avoid accidental exposure.\n\n---\n\n### 8. Analytics & Telemetry\n\n- Events defined in analytics library; consumed by bundle/app:\n - `lifecycle_assessment_run`\n - `lifecycle_stage_changed`\n - `lifecycle_guidance_consumed`\n- Observability pipeline includes:\n - Composite lifecycle health metric (weighted sum of KPIs).\n - Drift detection comparing stage predictions over time.\n - Alert manager recipes for regression (e.g., PMF drop).\n\n---\n\n### 9. Testing Strategy\n\n1. **Unit**\n - StageScorer weight matrix.\n - RecommendationEngine mapping.\n - Library recommender stage coverage.\n\n2. **Contract**\n - Adapters: ensure mock adapters satisfy interfaces.\n - Bundles: ensure HTTP handlers respect request/response contracts even without persistence.\n\n3. **Integration**\n - CLI example runs detection + guidance end-to-end on fixture data.\n - Dashboard example renders assessments, verifying JSON structures remain stable.\n\n---\n\n### 10. Implementation Checklist\n\n- [ ] Documentation (product, tech, ops, user).\n- [ ] Library creation (`@lssm/lib.lifecycle`).\n- [ ] Modules (`lifecycle-core`, `lifecycle-advisor`).\n- [ ] Bundle (`lifecycle-managed`) + Studio wiring.\n- [ ] Library enhancements (analytics/evolution/growth/observability).\n- [ ] Examples (CLI + dashboard).\n- [ ] Feature flags + telemetry.\n- [ ] Automated tests + fixtures.\n\nKeep this document in sync as modules evolve. When adding new stages or axes, update `@lssm/lib.lifecycle` first, then cascade to adapters, then refresh docs + Studio copy.*** End Patch*** End Patch\n\n\n"
|
|
13
|
+
}];
|
|
14
|
+
registerDocBlocks(tech_lifecycle_stage_system_DocBlocks);
|
|
15
|
+
|
|
16
|
+
//#endregion
|
|
@@ -1,4 +1,22 @@
|
|
|
1
|
-
import{
|
|
1
|
+
import { registerDocBlocks } from "../../registry.js";
|
|
2
|
+
|
|
3
|
+
//#region ../../libs/contracts/dist/docs/tech/llm/llm-integration.docblock.js
|
|
4
|
+
const tech_llm_integration_DocBlocks = [
|
|
5
|
+
{
|
|
6
|
+
id: "docs.tech.llm.overview",
|
|
7
|
+
title: "LLM Integration Overview",
|
|
8
|
+
summary: "Export specs to LLM-friendly formats, generate implementation guides, and verify implementations.",
|
|
9
|
+
kind: "reference",
|
|
10
|
+
visibility: "public",
|
|
11
|
+
route: "/docs/tech/llm/overview",
|
|
12
|
+
tags: [
|
|
13
|
+
"llm",
|
|
14
|
+
"ai",
|
|
15
|
+
"export",
|
|
16
|
+
"guide",
|
|
17
|
+
"verify"
|
|
18
|
+
],
|
|
19
|
+
body: `# LLM Integration
|
|
2
20
|
|
|
3
21
|
ContractSpec provides first-class LLM integration to bridge specifications and AI coding agents.
|
|
4
22
|
|
|
@@ -86,7 +104,21 @@ const result = await verifyService.verify(mySpec, implementationCode, {
|
|
|
86
104
|
tiers: ['structure', 'behavior']
|
|
87
105
|
});
|
|
88
106
|
\`\`\`
|
|
89
|
-
`
|
|
107
|
+
`
|
|
108
|
+
},
|
|
109
|
+
{
|
|
110
|
+
id: "docs.tech.llm.export-formats",
|
|
111
|
+
title: "LLM Export Formats",
|
|
112
|
+
summary: "Detailed explanation of the three export formats for LLM consumption.",
|
|
113
|
+
kind: "reference",
|
|
114
|
+
visibility: "public",
|
|
115
|
+
route: "/docs/tech/llm/export-formats",
|
|
116
|
+
tags: [
|
|
117
|
+
"llm",
|
|
118
|
+
"export",
|
|
119
|
+
"markdown"
|
|
120
|
+
],
|
|
121
|
+
body: `# LLM Export Formats
|
|
90
122
|
|
|
91
123
|
ContractSpec provides three export formats optimized for different LLM use cases.
|
|
92
124
|
|
|
@@ -151,7 +183,23 @@ The prompt format adapts based on task type:
|
|
|
151
183
|
- **test**: Test generation for existing code
|
|
152
184
|
- **refactor**: Refactoring while maintaining behavior
|
|
153
185
|
- **review**: Code review against spec
|
|
154
|
-
`
|
|
186
|
+
`
|
|
187
|
+
},
|
|
188
|
+
{
|
|
189
|
+
id: "docs.tech.llm.agent-adapters",
|
|
190
|
+
title: "Agent Adapters",
|
|
191
|
+
summary: "Adapters for different AI coding agents (Claude, Cursor, MCP).",
|
|
192
|
+
kind: "reference",
|
|
193
|
+
visibility: "public",
|
|
194
|
+
route: "/docs/tech/llm/agent-adapters",
|
|
195
|
+
tags: [
|
|
196
|
+
"llm",
|
|
197
|
+
"agents",
|
|
198
|
+
"claude",
|
|
199
|
+
"cursor",
|
|
200
|
+
"mcp"
|
|
201
|
+
],
|
|
202
|
+
body: `# Agent Adapters
|
|
155
203
|
|
|
156
204
|
ContractSpec provides specialized adapters for different AI coding agents.
|
|
157
205
|
|
|
@@ -208,7 +256,22 @@ The generic adapter is the default and works across all agents.
|
|
|
208
256
|
| Claude Code | Complex implementations | Extended thinking, detailed steps |
|
|
209
257
|
| Cursor CLI | IDE-integrated work | Cursor rules, compact format |
|
|
210
258
|
| Generic MCP | Any MCP agent | Universal compatibility |
|
|
211
|
-
`
|
|
259
|
+
`
|
|
260
|
+
},
|
|
261
|
+
{
|
|
262
|
+
id: "docs.tech.llm.verification",
|
|
263
|
+
title: "Implementation Verification",
|
|
264
|
+
summary: "Tiered verification of implementations against specifications.",
|
|
265
|
+
kind: "reference",
|
|
266
|
+
visibility: "public",
|
|
267
|
+
route: "/docs/tech/llm/verification",
|
|
268
|
+
tags: [
|
|
269
|
+
"llm",
|
|
270
|
+
"verify",
|
|
271
|
+
"validation",
|
|
272
|
+
"testing"
|
|
273
|
+
],
|
|
274
|
+
body: `# Implementation Verification
|
|
212
275
|
|
|
213
276
|
ContractSpec provides tiered verification to check if implementations comply with specs.
|
|
214
277
|
|
|
@@ -286,4 +349,9 @@ Each issue has:
|
|
|
286
349
|
- **category**: type, export, import, scenario, error_handling, semantic
|
|
287
350
|
- **message**: Description of the issue
|
|
288
351
|
- **suggestion**: How to fix it
|
|
289
|
-
`
|
|
352
|
+
`
|
|
353
|
+
}
|
|
354
|
+
];
|
|
355
|
+
registerDocBlocks(tech_llm_integration_DocBlocks);
|
|
356
|
+
|
|
357
|
+
//#endregion
|
|
@@ -1 +1,37 @@
|
|
|
1
|
-
import{
|
|
1
|
+
import { registerDocBlocks } from "../registry.js";
|
|
2
|
+
|
|
3
|
+
//#region ../../libs/contracts/dist/docs/tech/mcp-endpoints.docblock.js
|
|
4
|
+
const tech_mcp_endpoints_DocBlocks = [{
|
|
5
|
+
id: "docs.tech.mcp.endpoints",
|
|
6
|
+
title: "ContractSpec MCP endpoints",
|
|
7
|
+
summary: "Dedicated MCP servers for docs, CLI usage, and internal development.",
|
|
8
|
+
kind: "reference",
|
|
9
|
+
visibility: "mixed",
|
|
10
|
+
route: "/docs/tech/mcp/endpoints",
|
|
11
|
+
tags: [
|
|
12
|
+
"mcp",
|
|
13
|
+
"docs",
|
|
14
|
+
"cli",
|
|
15
|
+
"internal"
|
|
16
|
+
],
|
|
17
|
+
body: `# ContractSpec MCP endpoints
|
|
18
|
+
|
|
19
|
+
Three dedicated MCP servers keep AI agents efficient and scoped:
|
|
20
|
+
|
|
21
|
+
- **Docs MCP**: \`/api/mcp/docs\` — exposes DocBlocks as resources + presentations. Tool: \`docs.search\`.
|
|
22
|
+
- **CLI MCP**: \`/api/mcp/cli\` — surfaces CLI quickstart/reference/README and suggests commands. Tool: \`cli.suggestCommand\`.
|
|
23
|
+
- **Internal MCP**: \`/api/mcp/internal\` — internal routing hints, playbook, and example registry access. Tool: \`internal.describe\`.
|
|
24
|
+
|
|
25
|
+
### Usage notes
|
|
26
|
+
- Transports are HTTP POST (streamable HTTP); SSE is disabled.
|
|
27
|
+
- Resources are namespaced (\`docs://*\`, \`cli://*\`, \`internal://*\`) and are read-only.
|
|
28
|
+
- Internal MCP also exposes the examples registry via \`examples://*\` resources:
|
|
29
|
+
- \`examples://list?q=<query>\`
|
|
30
|
+
- \`examples://example/<id>\`
|
|
31
|
+
- Prompts mirror each surface (navigator, usage, bootstrap) for quick agent onboarding.
|
|
32
|
+
- GraphQL remains at \`/graphql\`; health at \`/health\`.
|
|
33
|
+
`
|
|
34
|
+
}];
|
|
35
|
+
registerDocBlocks(tech_mcp_endpoints_DocBlocks);
|
|
36
|
+
|
|
37
|
+
//#endregion
|
|
@@ -1 +1,16 @@
|
|
|
1
|
-
import{
|
|
1
|
+
import { registerDocBlocks } from "../registry.js";
|
|
2
|
+
|
|
3
|
+
//#region ../../libs/contracts/dist/docs/tech/presentation-runtime.docblock.js
|
|
4
|
+
const tech_presentation_runtime_DocBlocks = [{
|
|
5
|
+
id: "docs.tech.presentation-runtime",
|
|
6
|
+
title: "Presentation Runtime",
|
|
7
|
+
summary: "Cross-platform runtime for list pages and presentation flows.",
|
|
8
|
+
kind: "reference",
|
|
9
|
+
visibility: "public",
|
|
10
|
+
route: "/docs/tech/presentation-runtime",
|
|
11
|
+
tags: ["tech", "presentation-runtime"],
|
|
12
|
+
body: "## Presentation Runtime\n\nCross-platform runtime for list pages and presentation flows.\n\n### Packages\n\n- `@lssm/lib.presentation-runtime-core`: shared types and config helpers\n- `@lssm/lib.presentation-runtime-react`: React hooks (web/native-compatible API)\n- `@lssm/lib.presentation-runtime-react-native`: Native entrypoint (re-exports React API for now)\n\n### Next.js config helper\n\n```ts\n// next.config.mjs\nimport { withPresentationNextAliases } from '@lssm/lib.presentation-runtime-core/next';\n\nconst nextConfig = {\n webpack: (config) => withPresentationNextAliases(config),\n};\n\nexport default nextConfig;\n```\n\n### Metro config helper\n\n```js\n// metro.config.js (CJS)\nconst { getDefaultConfig } = require('expo/metro-config');\nconst {\n withPresentationMetroAliases,\n} = require('@lssm/lib.presentation-runtime-core/src/metro.cjs');\n\nconst projectRoot = __dirname;\nconst config = getDefaultConfig(projectRoot);\n\nmodule.exports = withPresentationMetroAliases(config);\n```\n\n### React hooks\n\n- `useListCoordinator`: URL + RHF + derived variables (no fetching)\n- `usePresentationController`: Same plus `fetcher` integration\n- `DataViewRenderer` (design-system): render `DataViewSpec` projections (`list`, `table`, `detail`, `grid`) using shared UI atoms\n\nBoth accept a `useUrlState` adapter. On web, use `useListUrlState` (design-system) or a Next adapter.\n\n### KYC molecules (bundle)\n\n- `ComplianceBadge` in `@lssm/bundle.strit/presentation/components/kyc` renders a status badge for KYC/compliance snapshots. It accepts a `state` (missing_core | incomplete | complete | expiring | unknown) and optional localized `labels`. Prefer consuming apps to pass translated labels (e.g., via `useT('appPlatformAdmin')`).\n\n### Markdown routes and llms.txt\n\n- Each web app exposes `/llms` (and `/llms.txt`, `/llms.md`) via rewrites. See [llmstxt.org](https://llmstxt.org/).\n- Catch‑all markdown handler lives at `app/[...slug].md/route.ts`. It resolves a page descriptor from `app/.presentations.manifest.json` and renders via the `presentations.v2` engine (target: `markdown`).\n- Per‑page companion convention: add `app/<route>/ai.ts` exporting a `PresentationDescriptorV2`.\n- Build‑time tool: `tools/generate-presentations-manifest.mjs <app-root>` populates the manifest.\n- CI check: `pnpm llms:check` verifies coverage (% of pages with descriptors) and fails if below threshold.\n"
|
|
13
|
+
}];
|
|
14
|
+
registerDocBlocks(tech_presentation_runtime_DocBlocks);
|
|
15
|
+
|
|
16
|
+
//#endregion
|