Tently — Context Graph Toolkit

An extracted Apache-2.0 toolkit for connecting product intent, contracts, implementation, tests and observed runtime evidence. Derived from LaunchEcho Context Graph; see NOTICE and the source inventory.

This standalone implementation uses small, recorded delivery milestones. See roadmap and validation for completed checks and limitations.

Set up a project

The npm package is @launch-echo/tently; its neutral @launch-echo/tently-core dependency is installed automatically. Core 0.1.0 is published and verified; the toolkit's first registry release still requires completion by an authenticated publisher in the launch-echo organization. The commands below become available from the public registry after publication; local archive testing is described below.

From your TypeScript project's directory, after publication:

npx @launch-echo/tently init
npx @launch-echo/tently config validate
npx @launch-echo/tently doctor

init asks for the repository ID, code roots, selected document paths and model, then writes context-graph.config.json and adds .context-graph/ to .gitignore. It fills in the internal version fields, requires no Git commit or Codex login to run, and refuses to overwrite existing configuration. Setup makes no model requests. For automation:

npx @launch-echo/tently init --yes --repository-id your-org/your-project --code-root src --semantic-source docs/product --evidence-root tests

Source flags may be repeated. Without --semantic-source, non-interactive setup selects no documents. Owner-approved sources always start empty; explicitly review and set approvedIntentSources in the JSON file. Select contracts using contractPatterns. Use --config .config/context-graph.json for another configuration location, --directory /path/to/project to initialize another project, or --no-gitignore to leave ignore rules alone. Configuration remains JSON; config show displays the validated settings.

Review the selected sources, configure Codex authentication when using semantic documents, and commit the inputs you want indexed before hydrating:

npx @launch-echo/tently hydrate --ref HEAD
npx @launch-echo/tently impact scan --changed-file src/search.ts --json

Hydration with selected documents may incur model charges. Saved queries do not call a model. Docker is optional for openCAESAR; the default RDF backend needs no Docker. For a project-local dependency, install npm install --save-dev @launch-echo/tently and use npx tently or npx context-graph. MCP clients can launch npx --yes --package @launch-echo/tently context-graph-mcp with CONTEXT_GRAPH_CONFIG set to the project's absolute configuration path. Pin a reviewed version for reproducible agent setup.

Linux/WSL is the validated full-suite path. Native Windows has a live Codex pass but still has archive-byte and concurrent snapshot replacement issues; see the validation record.

Development

The toolkit requires Node.js 24 or newer; Node 24 is the validated runtime. Use pnpm 10.18.2 for development. The neutral core package has no toolkit runtime dependencies and retains its separate Node.js 20.11+ declaration.

git clone https://github.com/jchewitt/tently.git
cd tently
nvm install
nvm use
pnpm install --frozen-lockfile
pnpm build
pnpm test
pnpm context-graph:publication-check

The .nvmrc selects Node 24. If you do not use nvm, install Node 24 through your usual version manager. The project rejects unsupported Node versions during installation, and CLI/MCP startup reports a version error before loading runtime dependencies.

The publication check packs and installs into a disposable consumer, indexes actual TypeScript and exercises the installed toolkit. It does not publish. Core and toolkit retain separate package boundaries; no product adapter is required.

Independent repository

Copy examples/generic-typescript into a separate repository, or adapt its context-graph.config.json beside your own sources. Paths resolve relative to that configuration. Configure semantic source selection, TypeScript roots/indexer arguments, contract aliases, evidence roots, runtime evidence, storage and optional adapter explicitly.

Install the locally packed core and toolkit tarballs together. The installed commands are tently, context-graph and context-graph-mcp. For example, after preparing a release:

npm install --save-dev /path/to/tently/.release/launch-echo-tently-core-0.1.0.tgz /path/to/tently/.release/launch-echo-tently-0.1.0.tgz
npx tently init

Pass --config /absolute/path/context-graph.config.json to the CLI or set CONTEXT_GRAPH_CONFIG for MCP. No launcher rebuild is required for installed packages. node mcp-launcher.mjs is for development in this repository.

context-graph hydrate --config context-graph.config.json --ref HEAD
context-graph impact scan --config context-graph.config.json --capability search --json
context-graph visualize --config context-graph.config.json --capability search --output graph.html

Semantic hydration requires a working configured provider. Direct RDF is the default; Docker/openCAESAR is an optional explicit backend. Run context-graph doctor for setup diagnostics. Committed indexing and ontology input use disposable archives, preserving the active checkout. Saved-snapshot queries do not invoke either dependency or refresh automatically. Responses report commit, configuration, source scope and excluded working changes. Use hydrate explicitly to refresh evidence; --snapshot selects historical evidence. Working-change overlays are a separate operation. context-graph overlay --base-snapshot <id> --agent <name> captures a bounded draft implementation overlay; query its returned ID with --snapshot. Changed prose is invalidated pending re-extraction. Queries compare captured file digests with current working bytes and report subsequent edits separately from captured and excluded changes. Older overlays without capture metadata have unknown freshness. Historical or draft evidence cannot validate a current diff.

Evidence limits

Approved owner documents govern intent. Code describes implementation; tests describe what was checked; traces describe observed behavior for their deployment. Model assertions require valid citations and remain inferred/unreviewed even when their source is explicitly approved. Source approval is recorded separately from assertion review. Missing coverage is not a pass.

The current implementation supports TypeScript SCIP indexing, immutable JSON snapshot envelopes, a lossless RDF/SPARQL query path, SHACL integrity checks, paginated impact.scan traversal and HTML/DOT/SVG output. Active OWL reasoning and a complete interactive explorer are not claimed. See examples/pipeline for a six-stage asynchronous flow and docs/ADR-004-rdf-query-path.md for query bounds and authority configuration.

Never submit credentials, account data or private runtime payloads as semantic sources. Live provider tests are separate from deterministic CI. The maintainer authorized the GitHub export and requested npm publication under @launch-echo. Registry publication still requires an authorized npm identity. Repository visibility changes require separate authorization.

See npm release instructions for prepared archives, integrity checks and the core-before-toolkit publication sequence.

See provider contract for bounded extraction and adapters, and architecture policy for deterministic governance.

See the bounded viewer guide and cloud setup.