werk
Repositories Projects Packages

@deck/runtime (0.1.2)

Published 2026-07-26 20:23:25 +02:00 by amelie

Installation

@deck:registry=https://gitlab.amandy.love/api/packages/werk/npm/
npm install @deck/runtime@0.1.2
"@deck/runtime": "0.1.2"

About this package

@deck/runtime

Deck orchestration runtime extracted incrementally from the legacy Deck app.

Four-stage flow

  1. Harvest
  2. Intelligence
  3. Discovery
  4. Synthesis

Boundaries

  • Runtime owns orchestration, cognition flows, stores, worker cycles.
  • App owns server wiring, routes, views, static assets, local config.

Loom/Nerve integration

  • LoomAnalysisBridge adapts deterministic analysis
  • LoomAiBridge adapts packs/retrieval/context assembly
  • NerveSearchBridge adapts symbolic search backend

Migration status

This package is wrapper-first: stable runtime contracts are defined and can wrap existing Deck logic incrementally without destructive rewrites.

API consumers (thin routes)

  • apps/deck/src/api/* routes call services from getDeckServices() only (no direct ../lib/* imports).
  • orchestratorApi → DeckOrchestratorService (library, tree, presets, stream, run, pause)
  • intelApi → DeckIntelService (all intelligence/nexus/AI routes via deps)
  • issueApi → DeckIssueService + DeckExecutionService (including implied/deepen/execution)
  • repoApi → DeckRepoService (reads, worker/meta, spawn/shell integration via deps)
  • outlineApi uses DeckCodeService.isSafePath for path checks

Fourth migrated API consumer

  • apps/deck/src/api/researchApi.ts now uses DeckResearchService from @deck/runtime for POST /api/research/crawl.
  • HTTP contract remains unchanged; route still owns HTTP parsing/response formatting.
  • Crawl, condensation, and pack persistence remain app-provided via injected runCrawlAndBuildPack deps (no live AI in default runtime tests).

Fifth migrated API consumer

  • apps/deck/src/api/wikiApi.ts now uses DeckWikiService for wiki CRUD and workspace inbox reads.

Sixth migrated API consumer

  • apps/deck/src/api/codeApi.ts now uses DeckCodeService for POST /api/code/entity.

Fox-Issue Integration

This runtime now includes enhanced issue and file guidance logic inspired by the legacy Fox-Issue project:

  • Issue Learning Layer: Historical lessons from closed issues are automatically linked to affected files.
  • Issue Lifecycle: Mandatory accepted gate for feature implementation ensures human oversight.
  • Mandatory Closing Knowledge: Requires rootCause, solution, and aiLesson before closing an issue.
  • File Guidance Layer: Persistent annotations and constraints linked to specific files, including "Ghost Files" specifications.
  • Next Task Scoring: Intelligent task prioritization based on priority, age, and blocked status.

Data paths

  • createDeckDataPaths(root) — canonical paths for stores (execution, intel, orchestrator, research, test runs, etc.)
  • ensureDeckDataPaths(paths) — mkdir parent dirs for files and store directories

Dependency Policy

This ecosystem strictly enforces dependency minimalism:

  • Prefer zero external runtime dependencies.
  • Prefer Bun/Node built-ins.
  • Prefer workspace packages over external alternatives.
  • External dependencies require explicit justification.
  • Live AI is never part of default tests.
  • Generated tooling must not casually add packages.

Execution types

  • executionTypes (schemas + parsers) exported from @deck/runtime for implementation/guardian chains

Test categories

  • default/unit: bun run test in apps/deck (safe workspace default)
  • integration: bun run test:integration in apps/deck
  • live AI/manual: bun run test:ai (and combined test:manual)

Public consumer API (@deck/runtime)

Seventh migrated API consumer

  • apps/deck/src/api/workspaceApi.ts now uses DeckWorkspaceRefactorService for POST /api/workspace/refactor-symbol.
  • POST /api/workspace/refactor-symbol
  • POST /api/workspace/add-test-case: Second end-to-end agent workflow.
  • These workflows integrate @loom/workspace, @loom/analysis, and @loom/ai.

Data paths

... Import from the package entry only (not deep src/ paths):

import {
  createDeckDataPaths,
  DeckIssueService,
  DeckIntelService,
  DeckOrchestratorService,
  DeckResearchService,
  DeckWikiService,
  DeckCodeService,
  DeckRepoService,
  DeckCollaborationService,
  DeckCodingToolService,
  DeckOutlineService,
  DeckBurstService,
  DeckTestsService,
  DeckExecutionService,
  DeckWorkspaceRefactorService,
  DeckAddTestCaseService,
  DeckIssueService,
  DeckFileGuidanceService,
} from "@deck/runtime";

apps/deck wires implementations via runtimeServices.ts (single factory per process).

Postponed

  • Full internal file moves from apps/deck/src/lib (worker/orchestrator engine ownership)
  • Full Facet conversion
  • Active Loom/Nerve pipelines in harvest/intel (bridges are smoke-only)

Dependencies

Dependencies

ID Version
@loom/ai ^0.1.1
@loom/analysis ^0.1.0
@loom/sandbox ^0.1.0
@loom/workspace ^0.1.0
@nerve/search ^1.0.0

Development Dependencies

ID Version
@types/node ^22.0.0
typescript ^6.0.3
Details
npm
2026-07-26 20:23:25 +02:00
2
latest
30 KiB
Assets (1)
runtime-0.1.2.tgz 30 KiB
Versions (3) View all
0.1.2 2026-07-26
0.1.1 2026-07-26
0.1.0 2026-07-26