@topogram/extractor-temporal-workflows

@topogram/extractor-temporal-workflows

Package-backed Topogram extractor for review-only Temporal workflow discovery.

Status: current Audience: extractor authors and maintainers Use when: you need to implement, verify, or package this Topogram extractor.

This package reads local Temporal TypeScript and Go workflow source and emits review-only workflow candidates for Topogram extraction. It does not execute workflow code, start workers, contact Temporal services, load credentials, install packages, mutate source files, or write canonical topo/**.

Author Loop

npm install
npm test
npm run docs:rag:check
npm run check
npm run release:preflight

npm run check uses TOPOGRAM_CLI, then TOPOGRAM_BIN, then the locally installed @topogram/cli. Use TOPOGRAM_CLI=/path/to/topogram/engine/src/cli.js npm run check while developing against a local Topogram checkout.

npm run check runs:

• npm test
• npm run docs:rag:check
• topogram extractor check .
• topogram extract ./fixtures/basic-source --out <tmp> --from workflows --extractor .
• topogram extract plan <tmp>
• topogram query extract-plan <tmp>/topo
• topogram adopt --list <tmp>

The extractor looks for static workflow-owned evidence:

• exported TypeScript workflow functions using @temporalio/workflow
• Go workflow functions accepting workflow.Context
• activity calls through proxyActivities or workflow.ExecuteActivity
• signal handlers through defineSignal/setHandler or Go signal APIs
• timer waits through sleep, condition, workflow.Sleep, or workflow.NewTimer
• child workflows through executeChild, startChild, or workflow.ExecuteChildWorkflow

Temporal control flow is code-native, so v1 is intentionally conservative. It records workflow relationships as review-only states and transitions rather than claiming complete runtime execution order.

Extractor packages must not mutate source files, write canonical topo/**, install packages, perform network access, or define adoption semantics.

Keep llms.txt curated and regenerate llms-full.txt after README or agent guidance changes:

npm run docs:rag:build
npm run docs:rag:check

The docs scripts resolve this package root from their own file location and refuse links or writes that escape the package root.

npm run release:preflight runs the author checks, npm pack --dry-run, and the package-local Gitleaks secret scan. If CI already ran Gitleaks, it may set TOPOGRAM_SECRET_SCAN_ALREADY_RAN=1 for this script; do not use that skip in local release prep.

Shared or published extractor packs should adopt SDLC so rules, tasks, and proof history are queryable by agents. Private one-off extractors may stay lightweight, but they should still follow the generated AGENTS.md rules.

Candidate output is validated by track. Return only review candidate buckets for the declared track, give each candidate a stable identity, keep file evidence project-relative, and never return files, patches, adoption plans, or write instructions. stacks and frameworks are string metadata buckets; API parameter shorthands such as path_params: ["id"] are normalized by Topogram. UI widget and component mapping candidates must use canonical Topogram pattern names. Do not emit layout/shell patterns such as app_header, primary_navigation, or footer_bar as widget mappings; return them as screen, layout, region, route, or action evidence instead.