VS Code Features

Norn is not just a file format. The extension adds editor actions, live Kubernetes views, test integration, Swagger coverage tooling, and environment-aware execution inside VS Code.

CodeLens in .norn Files

Clickable CodeLens actions appear directly above relevant lines in .norn files.

• ▶ Send Request appears above standalone HTTP requests outside sequences.
• ▶ Run Sequence appears above runnable sequence and test sequence declarations.
• ▷ Debug Sequence appears next to runnable sequences for step-through debugging.
• env: ... or + Add env file appears next to request and sequence actions so you can switch or create environments without leaving the editor.
• Open Contract and View Contract appear on matchesSchema assertions.

GET https://api.example.com/health

test sequence ContractCheck
    GET https://api.example.com/users/1
    assert $1.body matchesSchema "./schemas/user.schema.json"
end sequence

▶ Send Request does not appear for requests inside a sequence because those requests run as part of the sequence action instead.

Norn Terminal

Run Norn: Open Terminal from the Command Palette, or use Cmd+Alt+N on macOS and Ctrl+Alt+N elsewhere, to open Norn's PTY-backed terminal in the editor area. Supported Kubernetes commands render as structured results and live tiles; other commands pass through to your normal shell.

• Simple kubectl get pods, kubectl logs, kubectl get events, and rollout commands bloom into rich views.
• Use -w or -f for live tiles, or :pin to make the latest static result live.
• Each compact terminal tab keeps its own transcript, working directory, environment, Kubernetes scope, running commands, and live views.
• Terminal IntelliSense suggests scoped Kubernetes resources and browses files and folders for cd.
• Interactive commands such as vim and kubectl exec -it stay in the terminal's raw PTY surface.
• Typing claude or codex opens Norn's native agent UI inside the terminal instead of a raw TUI.

See Kubernetes & Norn Terminal for supported blooms, meta-commands, settings, and runbook syntax.

Kubernetes Files (.nornk8s)

.nornk8s files add Kubernetes-specific CodeLens actions, context selection, resource IntelliSense, and styled views for common triage commands.

• Standalone get pods opens a live dashboard with unhealthy pods first. Standalone logs follows new lines by default, and describe pod opens structured pod details and events.
• Sequence headers get a run action, while commands inside a sequence run as part of that block.
• The context CodeLens and status bar picker choose the Kubernetes context independently from the active Norn environment.
• IntelliSense suggests cached pods, deployments, namespaces, supported flags, and complete sequence blocks.
• Background discovery and automatic live-view failures stay quiet; commands you explicitly run still report failures.
• Deployment restarts always require a modal confirmation in VS Code.

namespace default

get pods -l app=orders
logs orders-api-7d9f --tail 500

runbook sequence ClusterCheck
    get pods
end sequence

See Kubernetes & Norn Terminal for the full command model, live-view behavior, IntelliSense scoping, and CLI usage.

Contract Validation

Schema assertions integrate with the editor workflow, so you can move from a failing response to the exact contract mismatch quickly.

• Open Contract opens the schema file referenced by a matchesSchema assertion. Paths can be relative or use the @/ alias for the workspace contracts/ folder.
• View Contract reruns the enclosing sequence and opens a contract report for that assertion.
• Hovering a validated matchesSchema line shows the current pass or fail status, schema path, last run, and a shortcut to open the contract view.
• Response panel results show contract cards with the schema name, validation counts, validated properties, and the most relevant issues.
• When schema validation fails in the response panel, the assertion output includes View Contract Details so you can inspect the mismatch directly from the run results and return with Back to Results.

test sequence GetUserContract
    GET {{baseUrl}}/users/1
    assert $1.status == 200
    assert $1.body matchesSchema "@/users/get-user-200.schema.json"
end sequence

The contract report separates breaking issues from warnings and lets you switch between the issue list, validated properties, annotated response, and resolved schema.

Response-Body IntelliSense and Diagnostics

After a successful explicit VS Code run, Norn can reuse sampled response-shape metadata to make body-path authoring faster without storing live payload data.

• Send Request and Run Sequence cache bounded response-shape metadata in .norn-cache/api-response-intellisense.json.
• Later completions for $1.body. and captured response variables such as user.body. can suggest cached properties, including nested object paths.
• The cache stores property names, type summaries, request identity, and cachedAt, but not raw response values, request bodies, headers, cookies, tokens, or secrets.
• CLI runs do not write this IntelliSense cache.
• Diagnostics flag undefined base variables in bare expressions such as assert missing.status == 200 while keeping runtime-shaped JSON property paths quiet when the base variable exists.

sequence InspectUser
    var user = GET https://api.example.com/users/1

    # After the first successful VS Code run, both lines benefit from cached body-path completion.
    assert user.body.profile.email exists
    assert $1.body.profile.email exists
end sequence

Environment-Aware Hints and Hovers

Norn resolves template references in the editor using the active environment, then shows the value inline and on hover across .norn, .nornapi, .nornsql, and .nornenv files. Secret values are masked.

• In .norn files, {{name}} resolves through sequence-local var declarations, then file-level var declarations, then the active environment.
• {{$env.name}} always reads directly from the active environment.
• Runtime values such as $1.body.id, request captures, and sequence return values do not show inline values, but hover explains where they come from.
• In .nornapi and .nornsql files, {{name}} resolves from the active environment.
• In .nornsql files, connection appDb shows the matching appDb_connectionString value from .nornenv when available.

CodeLens in .nornapi Files

Swagger lines in .nornapi files expose API-definition actions.

• Import Endpoints parses the OpenAPI/Swagger spec and generates endpoint definitions.
• Generate Schemas creates JSON Schema files from response definitions.
• Show Coverage opens API coverage for that .nornapi file and its folder scope.
• Endpoint URLs and header groups highlight {{variables}} the same way as .norn files, and diagnostics flag unresolved environment-backed endpoint variables.

swagger "https://petstore.swagger.io/v2/swagger.json"

CodeLens in .nornenv Files

.nornenv files get editor support for environment authoring and secret-management actions.

• Template references such as {{appDb_server}} get IntelliSense, including single-brace completion while typing.
• Template tokens are highlighted inside variable and connection-string values.
• Diagnostics catch unsupported template references, missing variables, and invalid references between environment-specific values.
• A Refactor ... templates CodeLens appears when Norn detects a flat stage/region matrix such as dev_us, dev_uk, prod_us, and prod_uk.
• Encrypt Secret appears on plaintext secret values.
• View Decrypted, Rotate Secret, and Delete Secret appear on encrypted secret lines.

[env:prelive]
secret apiKey = ENC[NORN_AGE_V1:kid=team-main:abc123xyz]

[env:dev_us]
var baseUrl = https://dev.example.com

[env:dev_uk]
var baseUrl = https://dev.example.com

[env:prod_us]
var baseUrl = https://api.example.com

[env:prod_uk]
var baseUrl = https://api.example.com

SQL Files (.nornsql)

SQL files get dedicated editor support so database setup and verification behave like first-class Norn assets instead of opaque scripts.

• .nornsql files have syntax highlighting for declaration lines and SQL bodies.
• The connection line shows and explains the resolved NAME_connectionString value from the active environment.
• Import completion in .norn files suggests .nornsql files alongside other Norn imports.
• Diagnostics catch invalid SQL-file structure, bad imports, duplicate SQL operation names, and invalid run sql calls.
• The sidebar starter catalogue includes a runnable SQL demo and a separate real database connection starter.

connection appDb

query ListUsersByStatus(status)
select Id, Email, Status
from Users
where Status = :status
end query

command UpdateUserStatus(id, status)
update Users
set Status = :status
where Id = :id
end command

Project Setup and MCP Tools

The sidebar home card includes a Project Setup menu so teams can scaffold starter samples and MCP configuration without leaving VS Code.

• Starter catalogue opens a sample list with a Back button. Each selected sample is created in its own new folder to avoid collisions.
• The catalogue includes simple requests, scripts with JSON data, a runnable SQL demo, a real SQL connection starter, and an advanced end-to-end flow with contract validation.
• Create MCP starter config remains a direct setup action that scaffolds a minimal norn.config.json; schema-backed IntelliSense covers optional fields and alias setup.
• The Explorer folder context menu can open the same starter catalogue and still includes the MCP setup action.
• norn.config.json gets JSON schema validation in the editor.
• run mcp list and run mcp call get syntax highlighting, diagnostics, server-alias completions, cached tool-name completions, and parameter hints after a successful list call.
• MCP steps show up in the response panel with dedicated styling instead of sharing SQL visuals.

test sequence TimeTools
    var tools = run mcp list localTools
    var result = run mcp call localTools get_current_time("UTC")

    assert tools.count > 0
    assert result.isError == false
end sequence

Test Explorer

Norn integrates with VS Code's built-in Testing sidebar.

• All test sequence blocks are discovered automatically.
• Plain sequence blocks stay as helpers and do not show up as tests.
• Tests are grouped by file, and then by their primary tag when tags exist.
• @data and @theory sequences show one child test per data case.
• Both run and debug profiles are available.
• Execution output streams into the test run so you can inspect requests, assertions, waits, scripts, and print statements.

@smoke
test sequence HealthCheck
    GET {{baseUrl}}/health
    assert $1.status == 200
end sequence

@data(1, 2, 3)
test sequence TodoTest(id)
    GET {{baseUrl}}/todos/{{id}}
    assert $1.status == 200
end sequence

Swagger Coverage

Norn can calculate coverage for Swagger-defined endpoints and response codes.

• Coverage counts response codes separately, not just endpoints.
• Show Coverage on a swagger line scopes coverage to that .nornapi file and its folder plus subfolders.
• When a .nornapi file is active and Swagger data exists, the status bar shows Coverage with a shortcut to the coverage panel.
• Norn: Refresh API Coverage recalculates the panel.
• Coverage updates after sequence execution.

test sequence OrderTests
    var found = GET GetOrderById(1)
    assert found.status == 200

    var missing = GET GetOrderById(999999)
    assert missing.status == 404
end sequence

TLS Verification

HTTPS certificate verification is enabled by default in the extension.

{
  "norn.security.verifyTlsCertificates": true
}

Set norn.security.verifyTlsCertificates to false only for trusted local development environments with self-signed certificates. The setting affects both request execution and Swagger/OpenAPI fetches.

If you need the same behavior in the CLI, use --insecure for that run instead of changing editor settings globally.

HTTP Request Timeouts

VS Code request and sequence runs use the same project timeout config as the CLI. Put team defaults in norn.config.json, then use the VS Code setting only when your local editor needs a different timeout.

{
  "version": 1,
  "http": {
    "timeoutMs": 180000
  }
}

{
  "norn.request.timeoutMs": 240000
}

Open Settings and search for norn request timeout to edit Norn › Request: Timeout Ms. Leave the setting unset to use norn.config.json; if neither is set, Norn uses the built-in 30 second default. Precedence is the VS Code setting, then norn.config.json, then the default.