NPM client

@igentify/helix-flowgraph is the integrator CLI and library for Helix Flowgraph: query the latest workspace graph and orchestrate scans from scripts or agents.

Install

The package is published to Igentify CodeArtifact only — it is not on the public npm registry. A bare npx @igentify/helix-flowgraph … that talks to registry.npmjs.org returns 404.

1. Point `@igentify` at CodeArtifact

Add to project .npmrc and/or ~/.npmrc:

ini

# Keep the default registry for public packages (optional but typical in this monorepo)
registry=https://registry.npmjs.org/

# Required — without this, npm/npx look up @igentify/* on npmjs and fail with E404
@igentify:registry=https://igentify-488414467642.d.codeartifact.us-east-1.amazonaws.com/npm/npm/

Pitfall: a project .npmrc that sets only registry=https://registry.npmjs.org/ (no @igentify:registry=…) overrides a correct ~/.npmrc and breaks npx inside that repo. Always set the scoped line.

2. Auth token (CodeArtifact)

You need a valid _authToken for that host (SSO profile that can call CodeArtifact). Example refresh into ~/.npmrc:

bash

TOKEN=$(aws codeartifact get-authorization-token \
  --domain igentify \
  --domain-owner 488414467642 \
  --region us-east-1 \
  --profile 786064378110_QA_EKS_Architects \
  --query authorizationToken --output text) && \
sed -i.bak "s|//igentify-488414467642.d.codeartifact.us-east-1.amazonaws.com/npm/npm/:_authToken=.*|//igentify-488414467642.d.codeartifact.us-east-1.amazonaws.com/npm/npm/:_authToken=$TOKEN|" ~/.npmrc && \
rm -f ~/.npmrc.bak

Ensure ~/.npmrc also contains a line like:

ini

//igentify-488414467642.d.codeartifact.us-east-1.amazonaws.com/npm/npm/:_authToken=<token>

Tokens expire; refresh when installs or npx start failing with 401/403.

3. Install or run

bash

npm install @igentify/helix-flowgraph

# Prefer pinning when validating a release
npx @igentify/helix-flowgraph@0.5.9 --help
npx @igentify/helix-flowgraph@0.5.9 mcp --local

One-off without relying on .npmrc scope (still needs a token for that host in ~/.npmrc or the environment):

bash

npx --registry https://igentify-488414467642.d.codeartifact.us-east-1.amazonaws.com/npm/npm/ \
  @igentify/helix-flowgraph@0.5.9 --help

After the package is installed

Default mode reads the local filesystem (scans/latest or HELIX_GRAPH_PATH). Optional HTTP: --base-url http://localhost:8787 against npm run dev:api.

scan start --local runs bundled ingest + helix-agent on disk — no helix-flowgraph clone required after install. You still need CodeArtifact (above) to download the package.

Surface	Notes
`query features` / `unbridged` / `repo=` / `impact` / `path` / `explain`	Local graph (AI summaries when the scan has `ai/`)
`query report`	Reads scan `reports/*.jsonl`
`mcp`	stdio or `--transport http`
`scan start --local --repo-path …`	Synchronous ingest (+ AI unless `--technical-only`)
`query … --scan-id`	`./scans/<id>/`

Run npx @igentify/helix-flowgraph --help for the full command reference.

Current published client: @igentify/helix-flowgraph@0.5.26 (TypeScript import { fn } CALLS from class methods and script scope; 0.5.24 Ask E + compact graph + CVE kept). See Release notes.

Package version vs ingest pipeline

The npm package version (@igentify/helix-flowgraph@0.4.x) tracks the client, CLI, and publish bundle. It is not the same as the AST extractor version stamped on scan output.

After any scan, check manifest.json and reports/technical-graph.json for:

Field	Meaning
`ingestPipelineVersion`	Version of the bundled/monorepo ingest code that produced the graph
`scanId`	Immutable snapshot id — always pin comparisons to this

Bumping the npm package without ingest code changes will not change edge counts or bridge rates. To verify whether a release changed graph extraction, diff ingestPipelineVersion (or the bundled helix-ingest/dist/ tree), not the npm semver alone.

Multi-repo local scans

Merge includes only the --repo-path / repoPaths you pass. Cross-repo CALLS_REMOTE bridges need every related FE/BE root in one scan (e.g. ng-access-service and ng-access-ui). A single-repo backend scan will show more unbridged endpoints than a full FE+BE merge — expected.

Multi-repo example:

bash

npx @igentify/helix-flowgraph scan start --local \
  --repo-path ~/code/igentify/ng-access-service \
  --repo-path ~/code/igentify/ng-access-ui
# Optional: add --technical-only for faster AST-only (stderr warning; no features/AI)

typescript

await startLocalScan({
  repoPaths: [
    "~/code/igentify/ng-access-service",
    "~/code/igentify/ng-access-ui",
  ],
  // technicalOnly: true, // optional — faster; skips features + AI
});

Check out each path at the same commit you intend to compare before scanning.

Bridge and “unbridged” metrics

query unbridged lists backend ApiEndpoint nodes with no multi-hop CALLS_REMOTE chain from a frontend ApiClientCall. Custom “orphan” or “unreachable” percentages over all node types are not the same metric; define them explicitly if you compute your own.

Local mode (filesystem scan + query)

Scan a checkout on disk and query the resulting graph without touching AWS:

bash

# npx only — no helix-flowgraph clone required
npx @igentify/helix-flowgraph scan start --local \
  --repo-path ~/code/igentify/report-builder-service

npx @igentify/helix-flowgraph query features --local
npx @igentify/helix-flowgraph query repo=report-builder-service --local
npx @igentify/helix-flowgraph query unbridged --local

What	Behavior
Output	`scans/<scanId>/` under your project cwd (default `./scans`); updates `scans/latest` symlink
Default pipeline	Feature YAML binding + full helix-agent AI (disk only)
Speed	Ingest ~seconds; AI minutes–hours depending on repo size and LLM provider
Opt out	`--technical-only` — faster AST + merge pass; see warning below

--technical-only

The CLI prints a stderr warning when this flag is set.

Still runs: AST extraction, merge, and CALLS_REMOTE bridging for every --repo-path you pass.

Skips: feature YAML binding, synthetic bridge Feature nodes, and all helix-agent AI passes (enrich-repos, feature synthesis, feature insights, feature labels).

Consequences:

query features — empty or minimal (no YAML-bound features)
query repo=… — technical nodes and edges only; no data.aiSummary
No scans/<scanId>/ai/ artifacts on disk
Does not add missing repos — you still need every related FE/BE --repo-path for a complete merge

Use for fast edge / reachability iteration (e.g. P0a AST metrics). Omit the flag for the default full local pipeline.

Local options

Option	Purpose
`--local`	Local ingest (scan) or in-process graph read (query)
`--repo-path <path>`	Local repository root (`scan start --local`; repeat for multiple)
`--out <dir>`	Scans output base (default `./scans`)
`--technical-only`	Faster ingest: AST + merge + bridges only; skips features and AI (see warning above)
`--no-update-latest`	Do not symlink `scans/latest` after scan
`--graph-path <path>`	Override graph file for local query
`--scan-root <path>`	Scan folder (AI artifacts) for local query
`--scan-id <id>`	Query a specific READY scan (cloud S3 or local `./scans/<id>/`)
`--workspace-id <id>`	Cloud: query that workspace’s LATEST READY scan (default: canonical workspace)
`--language <id>`	Local scan: force ingest plugin (`typescript`, `go`, `python`) for a single `--repo-path`
`--languages <map>`	Local scan: per-repo overrides (`repoKey=go,other=python`)
`--service-map <map>`	FE gateway prefix → BE repo (`/api/v1/rainbow=rainbow-service`; comma-separated). ≥ 0.4.4 / 0.5.1
`--backend-service-map <file>`	JSON overlay (`{ "services": { "/prefix": "repo-key" } }`). ≥ 0.4.4 / 0.5.1

When a FE path’s service prefix is not mapped, ingest logs distinct unmapped prefixes (with suggested --service-map flags) and writes reports/unmapped-service-prefixes.jsonl. You can also place backendServiceRepos.json next to --out or a scanned repo root, or set HELIX_BACKEND_SERVICE_MAP to a file path.

Local environment variables

Variable	Purpose
`HELIX_GRAPH_PATH`	Graph file for `query --local` (default: `scans/latest/reports/technical-graph.json`)
`HELIX_SCAN_ROOT`	Scan folder for AI artifact paths
`HELIX_SCANS_DIR`	Override scans output directory
`HELIX_LOCAL=1`	Same as `--local`
`HELIX_BACKEND_SERVICE_MAP`	Path to a `backendServiceRepos.json` overlay (≥ 0.4.4 / 0.5.1)
`HELIX_JAVA_SOURCE_ROOTS`	Extra Java trees (colon/semicolon-separated) for unresolved `@MappedSuperclass` / parent types (≥ 0.5.21). Sibling Java `--roots` are included automatically.
`HELIX_MAVEN_LOCAL`	Maven local repository for `-sources.jar` lookup (default `~/.m2/repository`, ≥ 0.5.21*)

typescript

import { startLocalScan, queryFeatures, queryRepos, detectIngestPlugin } from "@igentify/helix-flowgraph";

const plugin = await detectIngestPlugin("~/code/my-go-service");
const result = await startLocalScan({
  repoPaths: ["~/code/my-go-service"],
  language: plugin ?? "go",
});
// result: { local: true, scanId, status: "READY", graphPath, scanRoot,
//   ingestErrorsPath, unresolvedWiringPath?, questionableHttpPath?, runtime: "bundle", ... }
await queryRepos("report-builder-service", { local: true });

From 0.4.2, when ingest cannot resolve DI/JPA/AOP (or Java @Query / QueryDSL / JDBC hints), it writes JSONL under the scan and surfaces absolute paths:

Field / log line	File
`result.unresolvedWiringPath`	`reports/unresolved-wiring.jsonl`
`result.questionableHttpPath`	`reports/questionable-http.jsonl`
`result.ingestErrorsPath`	`reports/ingest-errors.log`

manifest.json artifacts lists the same report keys when they exist. CLI scan start --local prints these fields in the JSON result; the ingest process also prints absolute paths on stdout.

Query commands

Read data from a READY scan graph (default: canonical workspace LATEST; override with --scan-id or --workspace-id).

Command	What it does
`query features`	List Feature nodes (id, name, flowKey). Use to discover feature ids before opening a feature neighbourhood.
`query unbridged`	List backend ApiEndpoint nodes with no FE→BE bridge — no `CALLS_REMOTE` chain from a frontend client call. Same set as the UI “Unbridged endpoints” view.
`query impact --purl <purl>`	CVE / change blast radius from a lockfile package URL (optional `--symbols`, or `--node-id` instead of `--purl`). Requires a graph built with ingest ≥ 0.4.0.
`query repo=<repoKey>`	Repo subgraph: nodes, edges, and AI summaries on each (`data.aiSummary`).
`query repo=… --format mermaid\|text\|ascii`	Same subgraph slice as the Flowgraph UI sequence diagram (`mermaid`, `ascii`) or a text listing (`text`). Requires `--endpoint` when multiple entry points exist.
`query repo=a,b,c`	Combined subgraph for multiple repos (comma-separated keys). Includes cross-repo edges (e.g. `CALLS_REMOTE`) when both endpoint repos are in the list.
`query … --local`	Same commands against `scans/latest` (or `HELIX_GRAPH_PATH`); no AWS.
`query … --scan-id <id>`	Pin to one READY scan (historical graph, pre-feature commit scan, etc.).
`query … --workspace-id <id>`	Pin to LATEST READY for an ephemeral or alternate workspace.

Validating a new npm version: query repo=… without --local reads the graph the server already built — it does not run ingest. To test AST changes from a published package, use scan start --local and then query repo=… --local (or read result.graphPath).

CVE reachability (`query impact`, ≥ 0.4.0)

From 0.4.0, local and cloud scans inventorialize third-party packages from lockfiles (npm, PyPI, Go) as ExternalDependency nodes with a Package URL (purl). From 0.5.2, Java scans also inventory Maven/Gradle coordinates (pom.xml, build.gradle / .kts, optional gradle.lockfile) as pkg:maven/group/artifact@version. From 0.5.3, Java imports / type-receiver calls emit the same tiered usage edges as other languages. From 0.5.25, npm inventory falls back to package.json dependencies / devDependencies when package-lock.json is absent (node_modules is never required):

Tier	Edge	When
symbol	`CALLS_EXTERNAL` → `ExternalSymbol`	Resolved call (e.g. `jwt.verify()`)
module	`USES_EXTERNAL` → `ExternalDependency`	Import present, no resolved call site

Analyst playbook (Trivy / OSV → Helix):

Take the finding’s purl (and optional vulnerable symbol names).
Ensure the graph was built with ingestPipelineVersion ≥ 0.4.0 (re-scan with @igentify/helix-flowgraph@0.4.0+ if needed).
Run query impact and read captureSummary (symbol vs module hit counts).

bash

# Pin install (recommended when documenting against a release)
npm install @igentify/helix-flowgraph@0.4.0

# Scan (writes ExternalDependency + usage edges)
npx @igentify/helix-flowgraph@0.4.0 scan start --local --technical-only \
  --repo-path ~/code/igentify/ng-access-service

# Blast radius from a vulnerable package (optional OSV symbols)
npx @igentify/helix-flowgraph@0.4.0 query impact \
  --purl pkg:npm/aws-jwt-verify@5.1.1 \
  --symbols verify,create \
  --local

# Or seed from an arbitrary graph node
npx @igentify/helix-flowgraph@0.4.0 query impact --node-id 'repo:…|method:…' --local

Response shape (abridged):

json

{
  "seed": { "nodeIds": ["repo:…|extsym:…"], "purl": "pkg:npm/…", "symbols": ["verify"] },
  "captureSummary": { "symbol": 1, "module": 0 },
  "impactedAppNodes": [{ "id": "…", "label": "Method", "filePath": "src/…", "startLine": 4 }],
  "impactedEndpoints": [],
  "impactedFrontendSurfaces": [],
  "impactedFeatures": []
}

Field	Meaning
`seed`	Resolved graph seeds for the purl / symbols / nodeId
`captureSummary`	How many direct usage edges were symbol- vs module-tier
`impactedAppNodes`	Controllers, services, methods in the reverse closure
`impactedEndpoints`	Backend `ApiEndpoint` nodes (when route edges reach them)
`impactedFrontendSurfaces`	Hooks, `ApiClientCall`, components, etc.
`impactedFeatures`	Feature ids via `USES` (empty on `--technical-only` scans)

Library:

typescript

import {
  queryImpact,
  computeImpactAnalysis,
  buildPurl,
  buildPurlIndex,
} from "@igentify/helix-flowgraph";

await queryImpact(
  { purl: "pkg:npm/jsonwebtoken@9.0.0", vulnerableSymbols: ["verify"] },
  { local: true },
);

// Still supported: seed by node id
await queryImpact("repo:…|method:…", { local: true });

// Offline helper when you already have nodes/edges in memory
computeImpactAnalysis({
  nodes,
  edges,
  purl: buildPurl("npm", "jsonwebtoken", "9.0.0"),
  vulnerableSymbols: ["verify"],
});

Known false negatives (v1): dynamic import() / require(expr) (no edge); type-only imports (intentionally skipped); transitive usage into nested deps (lockfile inventory still lists transitive packages for CVE join — Trivy owns the dep chain).

Java Spring Security (≥ 0.5.4 / 0.5.6): Ingest links JWT verifiers and servlet filters to secured endpoints (TRIGGERS / ROUTE_THEN with confidenceReason: security_guard). isSecurityLibraryPurl matches JWT/oauth verifier libs only — not spring-security-core/web (0.5.5 over-tagged those). From 0.5.5+, query impact fans guard edges out only for auth-library seeds or an explicit --node-id that already emits security_guard TRIGGERS; from 0.5.6, fan-out during a library CVE walk is further limited to direct users of the seed. Re-scan at pipeline ≥ 0.5.6 for corrected guard edges.

HTTP request/response shapes (`REFERENCES_TYPE`, AST ≥ 0.3.4)

Technical ingest emits REFERENCES_TYPE from each ApiEndpoint (and its handler Method) to HTTP contract nodes:

Edge `label`	Meaning
`requestBody`	`validateDto(Dto, 'body')` on route middleware and/or `req.body as …` in the handler
`requestQuery`	`req.validated?.query as …`
`response`	TS: `res.json(…)` payload traced to a service/use-case callee return type. Java ≥ 0.4.3: handler method return type (`ResponseEntity<T>`, `List<T>`, `Page<T>`, …) unwrapped to `T`.

Response targets (0.3.4+ / Java 0.4.3+):

responseShape: shaped — edge targets a resolved Type / Interface / DataModel node.
responseShape: unshaped — return type is any, a JDK/opaque type (String, JsonNode, …), inline res.json({…}), or otherwise untyped; edge targets the service Method (or handler) with data.responseTypeName set so it is distinguishable from endpoints with no response edge.

Unresolved wiring JSONL (Java DI/JPA/AOP) may include scope: "app" | "framework" so Spring/JDK/AWS/test noise is separable from app-internal misses.

Each edge sets top-level label, data.httpShapeRole, and for responses also data.responseShape and data.responseTypeName when known.

Java dataflow provenance (AST ≥ 0.5.7):

Surface	Where	Contents
Response field origins	`REFERENCES_TYPE` response edge `data.fieldProvenance[]` and `ApiEndpoint.data.responseFieldProvenance[]`	`field` path, `transform` (`passthrough` \| `renamed` \| `computed` \| `constant` \| `unresolved`), `directCopy`, `sources[{typeId,typeName,field}]`, confidence
Request inputs	`ApiEndpoint.data.requestParams[]`	`location` (`path` \| `query` \| `body` \| `modelAttribute` \| `pageable` \| …), `name`, `typeHint`, `required`, `defaultValue?`, `enumValues?`, `enumStatus?` (`local` \| `unresolved`)
Query-param bindings (Java ≥ 0.5.21)	`ApiEndpoint.data.queryParamBindings[]`	`param` (keys `requestParams[]`), `column` (`table.column` or `null` when computed), `operator` (`eq` \| `like` \| `in` \| `range` \| `isNull` \| `computed`), `expression?`
Handler branches	`ApiEndpoint.data.handlerBranches[]`	`if` / `switch` / `ternary` with `conditionPreview`, `startLine`, `hasReturn`

Java also emits requestBody / requestQuery REFERENCES_TYPE edges for @RequestBody / @ModelAttribute when the type resolves in-scan. Local Java enum types are ingested as Type nodes so filter enums can list constants; JAR enums are enumStatus: unresolved (never dropped).

Java association / table metadata (AST ≥ 0.5.8): On each DataModel.data.schemaFields[] association, structured join facts include relationKind, owning, joinColumn, referencedColumn, mappedBy, and joinTable. Scalars may carry id: true (@Id) and physical column. DataModel.data.tableName is the top-level @Table(name=…) only (never a nested @Index / @UniqueConstraint name).

Method overloads & external symbols (AST ≥ 0.5.9): Java Method/Service node ids include parameter types (Class.method(Type,…)). npm/TS scans emit ExternalSymbol nodes for imported bindings and bare named-import calls. technical-graph.json / manifest.json carry symbolCoverageByEcosystem (dependencies, symbols, ratio per ecosystem).

Coverage metric: technical-graph.json and manifest.json include httpShapeCoverage — apiEndpointsWithResponseShape / apiEndpointsTotal (shaped + unshaped count as captured; missing edge = not captured).

--technical-only vs full local scan: both run the same AST graph; full scan only adds feature YAML + ai/ artifacts. It does not infer extra HTTP-shape edges.

bash

npx @igentify/helix-flowgraph query features
npx @igentify/helix-flowgraph query features --local
npx @igentify/helix-flowgraph query features --scan-id 01KX0JWPM83J
npx @igentify/helix-flowgraph query unbridged
npx @igentify/helix-flowgraph query repo=ng-access-service
npx @igentify/helix-flowgraph query repo=ng-access-service --scan-id 01KX0JWPM83J
npx @igentify/helix-flowgraph query repo=ng-access-service --local
npx @igentify/helix-flowgraph query repo=ng-access-service,ng-work-space-ui
npx @igentify/helix-flowgraph query repo=ng-access-service --endpoint '<ApiEndpoint-id>' --format mermaid --local
npx @igentify/helix-flowgraph query repo=ng-access-ui --endpoint '<ApiClientCall-id>' --component '<Component-id>' --format ascii --local
npx @igentify/helix-flowgraph query repo=ng-access-ui --endpoint '<ApiClientCall-id>' --format text --local
npx @igentify/helix-flowgraph@0.4.0 query impact --purl pkg:npm/jsonwebtoken@9.0.0 --symbols verify --local

Querying a previous scan or branch

A branch name is not a query parameter — scan the commit first, then query by scanId.

For commit-level or pre-release baselines, prefer cloud startScan (below). Local startLocalScan does not upload to S3, does not appear in scan list, and does not seed other workspace repos into the merge. Re-scanning an old commit locally is fine for AST experiments; it is not a substitute for a pinned cloud scanId when comparing against production graphs.

typescript

import { startScan, watchScan, queryFeatures, queryRepos } from "@igentify/helix-flowgraph";

// Scan pre-feature commit into an ephemeral workspace
const { scanId, workspaceId } = await startScan({
  workspaceId: "pre-feature-enrollments",
  repos: [{
    repoKey: "ng-access-service",
    fullName: "igentify/ng-access-service",
    commit: "abc123def456", // pre-feature SHA
  }],
});
await watchScan(scanId);

// Query that scan (not canonical LATEST)
const { features } = await queryFeatures({ scanId });
await queryRepos("ng-access-service", { scanId });

// Or: latest READY in that workspace only
await queryFeatures({ workspaceId });

bash

npx @igentify/helix-flowgraph scan list --workspace-id pre-feature-enrollments --completed
npx @igentify/helix-flowgraph query features --scan-id 01KX...

Scan commands

Start and monitor the ingest + AI pipeline (clone → AST → merge → AI enrichment → READY).

Command	What it does
`list` / `scan list`	List workspace scans, newest first. Default: today only (local midnight → now). Response includes `from` / `to` bounds applied.
`list --from <dt>`	Lower bound on `startedAt` (ISO 8601). `--to` defaults to now.
`list --to <dt>`	Upper bound; `--from` defaults to start of that local calendar day.
`list --from <dt> --to <dt>`	Explicit window (e.g. `--from 2026-07-01 --to 2026-07-08`).
`list --completed`	Same, but only READY (successful) scans.
`scan start --local --repo-path <path>`	Local ingest on a filesystem checkout. Writes `scans/<scanId>/`, updates `scans/latest`. No AWS. Bundled in npm package (no clone required).
`scan start --repo <key>`	Start a single-repo rescan. Seeds merge inputs and AI artifacts from the latest READY scan for other repos, then re-runs workspace feature synthesis/insights/labels.
`scan start`	Scan the full workspace roster (all configured repos).
`scan status <scanId>`	Current state: overall status, `progressPercent` (0–100), per-repo stage/status, branch, commit SHA, execution ARN.
`scan watch <scanId>`	Poll until READY or FAILED; prints JSON on each change (includes `progressPercent`). Exit code 1 on failure.
`scan cancel <scanId>`	Stop the Step Functions execution and mark the scan cancelled.

bash

npx @igentify/helix-flowgraph list
npx @igentify/helix-flowgraph list --from 2026-07-01
npx @igentify/helix-flowgraph list --completed
npx @igentify/helix-flowgraph scan start --repo ng-access-service
npx @igentify/helix-flowgraph scan start --local --repo-path ~/code/igentify/report-builder-service
npx @igentify/helix-flowgraph query repo=report-builder-service --local
npx @igentify/helix-flowgraph scan status 01JABC...
npx @igentify/helix-flowgraph scan watch 01JABC...
npx @igentify/helix-flowgraph scan cancel 01JABC...

Common options

Option	Purpose
`--local`	Local filesystem scan or in-process query (no AWS)
`--scan-id <id>`	Query a specific READY scan
`--workspace-id <id>`	Query LATEST READY for a workspace (cloud)
`--repo-path <path>`	With `scan start --local`: local repository root
`--profile <name>`	AWS profile for SSM API key lookup (cloud only)
`--region <name>`	AWS region (default `us-east-1`)
`--base-url <url>`	Override API base URL (cloud only)
`--interval <ms>`	Poll interval for `scan watch` (default `5000`)
`--compact`	Minified JSON on stdout (json format only)
`--format json\|mermaid\|text\|ascii`	`query repo=…` output (default: `json`)
`--endpoint <id>`	`ApiEndpoint` or `ApiClientCall` node id for mermaid/text/ascii
`--component <id>`	FE UI surface when `--endpoint` is `ApiClientCall` (optional)
`--purl <purl>`	With `query impact`: lockfile package URL seed (e.g. `pkg:npm/jsonwebtoken@9.0.0`)
`--symbols <list>`	With `query impact`: comma-separated OSV vulnerable symbol names
`--node-id <id>`	With `query impact`: arbitrary graph node seed (instead of `--purl`)

Library — query

Typed helpers wrap the Query REST API. Request body schemas live in shared/src/queries.ts; each helper below maps to a route handler in backend/src/routes.ts.

typescript

import {
  queryFeatures,
  queryFeature,
  queryRepos,
  queryUnbridged,
  queryCompareFeatures,
  queryImplementationAnchor,
  queryEndpointQa,
  queryEndpointPotentialIssues,
  queryEndpointQaFe,
  queryEndpointPotentialIssuesFe,
  queryFeatureInsights,
  queryFeatureDisplayTitles,
  queryImpact,
  queryNode,
  queryHealth,
  computeImpactAnalysis,
  buildPurl,
  buildPurlIndex,
} from "@igentify/helix-flowgraph";

// Feature catalogue from latest READY scan
const { features, scanId } = await queryFeatures();
await queryFeatures({ local: true }); // scans/latest on disk
await queryFeatures({ scanId: "01KX…" }); // historical / branch scan
await queryFeatures({ workspaceId: "pre-feature-enrollments" });

// One feature neighbourhood
await queryFeature("feature:…");

// Endpoints missing a FE→BE bridge
const { endpoints, counts } = await queryUnbridged();

// Repo slice with AI summaries
await queryRepos("ng-access-service");
await queryRepos(["ng-access-service", "ng-work-space-ui"]);

// Shared vs unique nodes between two features
await queryCompareFeatures("feature:…", "feature:…");

// Heuristic “where to implement?” anchor lookup
await queryImplementationAnchor({ featureQuery: "searchUsers" });

// AI artifacts (lazy S3 read — 404 or `{ error }` when not generated yet)
await queryEndpointQa("repo:…|ApiEndpoint:…");
await queryEndpointPotentialIssues("repo:…|ApiEndpoint:…");
await queryEndpointQaFe("repo:…|ApiClientCall:…");
await queryEndpointPotentialIssuesFe("repo:…|ApiClientCall:…");
await queryFeatureInsights("feature:…");
await queryFeatureDisplayTitles();

// CVE / change impact (≥ 0.4.0) — purl + optional OSV symbols, or node id
await queryImpact(
  { purl: "pkg:npm/jsonwebtoken@9.0.0", vulnerableSymbols: ["verify"] },
  { local: true },
);
await queryImpact("repo:…|method:…");
await queryNode("feature:…");

// Liveness
await queryHealth();

For routes without a named helper yet (/query/technical-graph inline delivery), use queryGraph("/query/…") (GET) or call the REST API directly (POST).

Verify exports after install:

bash

node -e "import('@igentify/helix-flowgraph').then(m=>console.log(typeof m.queryImpact, typeof m.computeImpactAnalysis, typeof m.buildPurl))"
# expect: function function function

Library — scan

typescript

import {
  startScan,
  startLocalScan,
  listScans,
  getScanStatus,
  watchScan,
  cancelScan,
} from "@igentify/helix-flowgraph";

const { scans, from, to } = await listScans({ completed: true });
await listScans({ from: "2026-07-01T00:00:00Z", to: "2026-07-08T23:59:59Z" });

const { scanId } = await startScan({ repoKey: "ng-access-service" });

// Scan a specific commit (POST body — use library, not CLI --repo alone)
await startScan({
  workspaceId: "my-experiment",
  repos: [{ repoKey: "ng-access-service", fullName: "igentify/ng-access-service", commit: "abc123" }],
});

// Local filesystem scan (no AWS, no clone)
await startLocalScan({
  repoPaths: ["~/code/igentify/report-builder-service"],
});

await watchScan(scanId, {
  pollIntervalMs: 5000,
  onUpdate: (run) => console.log(run.status, run.repos),
});

const final = await getScanStatus(scanId);
await cancelScan(scanId); // while running

REST endpoint details: Query REST API.

NPM client ​

Install ​

1. Point @igentify at CodeArtifact ​

2. Auth token (CodeArtifact) ​

3. Install or run ​

After the package is installed ​

Package version vs ingest pipeline ​

Multi-repo local scans ​

Bridge and “unbridged” metrics ​

Local mode (filesystem scan + query) ​

Local options ​

Local environment variables ​

Query commands ​

CVE reachability (query impact, ≥ 0.4.0) ​

HTTP request/response shapes (REFERENCES_TYPE, AST ≥ 0.3.4) ​

Querying a previous scan or branch ​

Scan commands ​

Common options ​

Library — query ​

Library — scan ​

NPM client

Install

1. Point `@igentify` at CodeArtifact

2. Auth token (CodeArtifact)

3. Install or run

After the package is installed

Package version vs ingest pipeline

Multi-repo local scans

Bridge and “unbridged” metrics

Local mode (filesystem scan + query)

Local options

Local environment variables

Query commands

CVE reachability (`query impact`, ≥ 0.4.0)

HTTP request/response shapes (`REFERENCES_TYPE`, AST ≥ 0.3.4)

Querying a previous scan or branch

Scan commands

Common options

Library — query

Library — scan