norn-cli 3.3.0 → 4.0.1

package/demos/knowledge-editor/README.md

@@ -1,74 +0,0 @@
-# The knowledge editor
-
-A knowledge base small enough to read in a minute, written to show every state the Stage 4
-editor can be in. Open the files in [`handbook/`](./handbook) and the ordinary Markdown editor
-gains chips, hovers, folded metadata, dimmed exclusions and underlined entities — no custom
-editor, no preview pane, no new file type.
-
-Membership comes from [`agents.nornagent`](./agents.nornagent) and nothing else:
-
-```nornagent
-knowledge Handbook
-    source ./handbook
-    exclude **/*.draft.md
-end knowledge
-```
-
-The folder is called `handbook`, not `knowledge`. That is the point — a path convention never
-activates the editor, and a frontmatter marker never activates it either. The declaration does.
-
-## What each file demonstrates
-
-| File | What to look at |
-|---|---|
-| `handbook/payments/charges.md` | H1 and H2 treatment, a multi-line `norn:meta` block folded behind its marker, a single-line one, an excluded section, and underlined entities that cross into `api.nornapi` and `.nornenv` |
-| `handbook/payments/refunds/policy.md` | A sub-domain. `payments/refunds` is its own domain, shown separately from `payments` — loading the parent never loads the child |
-| `handbook/ops/runbook.md` | No H1, so document feedback moves to a CodeLens at the top instead of chips on a title line |
-| `handbook/ops/retired.md` | A whole-file exclusion: the document dims, stays editable, and raises no error |
-| `handbook/ops/flow.svg` | A declared member whose extension produces no topics — inside the base, no editor surface |
-| `handbook/payments/pricing-tiers.draft.md` | Excluded by the declaration's glob, so it is plain Markdown again |
-
-## See the raw text
-
-**Norn: Knowledge: Toggle Markup** puts the `##` markers and the `norn:meta` blocks back on screen
-with the chips still in place. It is also how you check the surface still works without the
-unsupported style injection that hides them.
-
-## Try the authoring actions
-
-On any topic heading, the lightbulb offers:
-
-- **Change topic type…** — writes `type:` into the adjacent metadata block, creating the block if
-  there isn't one. The topic hash does not move, because metadata is stripped before hashing.
-- **Add/Edit use_when…** — the sentence the router reads when no exact entity matches.
-- **Exclude topic** / **Include topic** — the marker is placed below any metadata block, so the
-  metadata stays bound to its heading.
-
-Inside a `norn:meta` block, completions offer `type` and `use_when`, and `task`/`reference`/
-`concept` after `type:`.
-
-## Recorded use
-
-Every count in the editor is raw co-occurrence read back from Stage 3 run telemetry: these runs
-loaded this text. Norn does not claim the text changed their outcome — that question belongs to
-Stage 8. Until you run something, the honest state is what you'll see:
-
-> No knowledge runs recorded yet.
-
-To fill it in, point the `Support` model at a provider you have keys for and run the sequence:
-
-```bash
-node ./dist/cli.js demos/knowledge-editor/support.norn --env prelive
-```
-
-Then reopen `handbook/payments/charges.md`: the title line gains a pill —
-`Loaded by 1 run (1 succeeded · 0 failed)` — and each topic hover shows its own invocations and,
-if you have since edited a topic, its earlier versions in a separate row.
-
-## Inspect the same base from the CLI
-
-```bash
-node ./dist/cli.js knowledge ls --explain demos/knowledge-editor/agents.nornagent
-```
-
-Stage 4 adds no CLI command: the editor is a VS Code surface over the same index.

package/demos/knowledge-editor/agents.nornagent

@@ -1,16 +0,0 @@
-model Support
-    provider openai
-    name gpt-4.1-mini
-end model
-
-knowledge Handbook
-    source ./handbook
-    exclude **/*.draft.md
-end knowledge
-
-agent SupportEngineer
-    model Support
-    knowledge Handbook
-    describe "Answer payment support questions from the handbook."
-    system "You are a payments support engineer. Answer only from the handbook you were given."
-end agent

package/demos/knowledge-editor/api.nornapi

@@ -1,10 +0,0 @@
-headers Json
-Content-Type: application/json
-Idempotency-Key: {{$env.IDEMPOTENCY_KEY}}
-end headers
-
-endpoints
-CreateCharge: POST /v1/charges
-GetRefund: GET /v1/refunds/{id}
-CancelCharge: DELETE /v1/charges/{id}
-end endpoints

package/demos/knowledge-editor/handbook/ops/flow.svg

@@ -1 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="120" height="40"><text x="4" y="24" font-size="14">charge flow</text></svg>

package/demos/knowledge-editor/handbook/ops/retired.md

@@ -1,9 +0,0 @@
-<!-- norn:exclude -->
-
-# Retired: the old settlement runbook
-
-Excluded as a whole file, so the entire document dims. It is still ordinary Markdown you can
-read and edit — it simply contributes nothing to any run.
-
-## Nightly settlement
-We stopped running nightly settlement when the gateway moved to continuous capture.

package/demos/knowledge-editor/handbook/ops/runbook.md

@@ -1,14 +0,0 @@
-<!-- A file with no H1: the document feedback moves to a CodeLens at the top and the source
-     stays untouched. -->
-
-## Gateway timeouts
-<!-- norn:meta
-type: task
-use_when: the payment gateway is timing out
--->
-1. Check the gateway dashboard before touching anything.
-2. Retry once. A second timeout is an incident, not a retry.
-3. HTTP status 504 from `payment-svc` means the gateway, not us.
-
-## Who to wake
-The on-call rota lives in the team handbook. Wake the payments on-call, not the platform one.

package/demos/knowledge-editor/handbook/payments/charges.md

@@ -1,25 +0,0 @@
-# Charges
-
-The charge lifecycle, written for a support engineer who has the customer on the line.
-
-## Create a charge
-<!-- norn:meta
-type: task
-use_when: creating a charge, or retrying one that failed
--->
-1. Send `POST /v1/charges` with the amount in minor units.
-2. Always send the header `Idempotency-Key`. A retry without one can charge twice.
-3. A success is HTTP status 201 and a charge id in the body.
-
-The service `payment-svc` owns this endpoint in the `prelive` environment, and the key comes
-from {{$env.IDEMPOTENCY_KEY}}.
-
-## What CARD_DECLINED means
-<!-- norn:meta type: reference -->
-The error code "CARD_DECLINED" is the issuer's answer, not ours. Nothing we retry will change
-it inside the same hour, so the customer needs a different card or their bank.
-
-## Legacy charge lookup
-<!-- norn:exclude -->
-The endpoint `GET /v1/charges/legacy` was retired in 2024. Kept for archaeology; excluded from
-the knowledge base so no agent quotes it back to a customer.

package/demos/knowledge-editor/handbook/payments/pricing-tiers.draft.md

@@ -1,7 +0,0 @@
-# Pricing tiers (draft)
-
-Excluded by the declaration's `exclude **/*.draft.md` glob, so this file is not a member at
-all: no chips, no CodeLens, no hovers. It is a plain Markdown file again.
-
-## Tier 2
-Numbers not agreed yet.

package/demos/knowledge-editor/handbook/payments/refunds/policy.md

@@ -1,12 +0,0 @@
-# Refunds
-
-## When we refund without asking
-<!-- norn:meta
-type: reference
-use_when: deciding whether a refund needs approval
--->
-Under £50, refund it. The endpoint is `GET /v1/refunds/{id}` to check state first, and the
-service is `payment-svc`.
-
-## Partial refunds
-Split the amount across the original charge. A partial refund still returns HTTP status 200.

package/demos/knowledge-editor/support.norn

@@ -1,10 +0,0 @@
-[CreateCharge]
-POST {{BASE_URL}}/v1/charges
-content-type: application/json
-Idempotency-Key: {{$env.IDEMPOTENCY_KEY}}
-
-{"amount": 1200, "currency": "gbp"}
-
-sequence AnswerASupportQuestion
-    run SupportEngineer "A charge came back CARD_DECLINED. What should the customer do?"
-end sequence

package/demos/mcp-ticket-testing/README.md

@@ -1,114 +0,0 @@
-# Ticket testing with declared MCP servers
-
-An agent graph that **does** something: a ticket arrives, one agent tests the product through a
-browser, another tests it through the team's own API, a third writes the results up, and a
-`judge` rules on whether the expected test cases were actually covered.
-
-Everything it connects to is declared in [`agents.nornagent`](./agents.nornagent), beside the
-model. There is **no `norn.config.json` in this folder** — the servers, their transports, and
-their session lifetimes are all in the file that uses them.
-
-## What to look at
-
-```nornagent
-mcp Browser
-    transport stdio
-    command node ./servers/browser-server.js
-    session agent
-end mcp
-
-agent FrontendTester
-    mcp Browser                                    # the run of the browser
-    tools House.getFixtureUser, House.resetTenant  # only what it needs from ours
-end agent
-
-agent BackendTester
-    tools House.callEndpoint, House.readAuditLog, House.queryDb
-end agent
-```
-
-Three things this shows, and they are the point of the whole slice:
-
-- **Two agents, one custom server, different tools each.** `BackendTester` gets three named
-  tools from `House` and cannot touch the browser at all. The access boundary is visible per
-  agent, in one file, in git.
-- **`mcp Browser` and `tools House.callEndpoint` are visibly different statements.** Dropping
-  four characters must not silently widen access from one tool to twenty, so there is no
-  short form that means "all of it".
-- **`session agent` on the browser.** Each agent invocation gets its own browser, closed when
-  that hop ends. The default, `session run`, shares one browser across every agent in the
-  sequence — right for a continuous flow, and wrong the moment a second agent is granted the
-  same server: it would inherit the first one's login and could pass a test it never
-  authenticated for, which is a false green and worse than a false red. Only `FrontendTester`
-  reaches the browser in this graph, so this is the lifetime worth authoring by default rather
-  than a bleed this demo would actually suffer.
-
-## Run it
-
-The servers are deterministic and ship with the demo, so nothing needs installing or starting.
-Prove they are reachable **without spending anything on a model**:
-
-```bash
-npm run compile
-node ./dist/cli.js demos/mcp-ticket-testing/tickets.norn --sequence ServersUp
-```
-
-That resolves the same aliases the agents use, so a failure points at the server rather than at
-an agent. When you are building a server of your own, this is the loop to develop against.
-
-Then the real thing, which does need a model:
-
-```bash
-export OPENAI_API="your-key"
-node ./dist/cli.js demos/mcp-ticket-testing/tickets.norn --sequence TicketPROJ142
-```
-
-The variable name is not a convention Norn assumes — it is written in the model block as
-`apiKey {{$env.OPENAI_API}}`, so any name works as long as the file and the environment
-agree. A `.nornenv` value wins over the process environment; add `--env <name>` to select one.
-
-## The browser here is a stand-in
-
-[`servers/browser-server.js`](./servers/browser-server.js) is a deterministic scripted site, not
-a real browser, so this demo runs anywhere `node` does — no browser download, no server to keep
-alive. Its declaration is the **same shape** a real Playwright MCP block takes, and both real
-forms are written out in the comments at the top of
-[`agents.nornagent`](./agents.nornagent):
-
-```nornagent
-mcp Browser
-    transport stdio
-    command npx playwright-mcp --headless --isolated
-    session agent
-end mcp
-```
-
-For CI with more than one sequence, run Playwright MCP as a service and dial it instead — that
-is what `transport http` is for. Norn never starts an http server; it only connects to one, and
-a refused connection fails before any model spend, naming the URL it tried.
-
-## The judge, and the CI story
-
-The last line of `TicketPROJ142` is the part that makes this a test rather than a demo:
-
-```norn
-judge report with Reviewer expects file expectations/proj-142.md
-```
-
-Every expectation in [`expectations/proj-142.md`](./expectations/proj-142.md) must be met;
-testing *more* than the list is not a failure. The judge is never asked for an overall verdict —
-it rules on each expectation and quotes its evidence, and Norn computes the result.
-
-Note the comment lines in that file. A line of prose left uncommented there **is** an
-expectation, which is both Norn's comment rule and what makes Markdown headings work.
-
-A live run records itself under `.norn-cache/runs/`. Replay it with no servers running at all:
-
-```bash
-node ./dist/cli.js replay .norn-cache/runs/<recording>.json
-```
-
-That is the CI answer for any expensive server: run it live where the servers exist, and gate
-pull requests on the replay — no browser, no API, no model, and the graph and contracts still
-checked. The recording keeps the tool names each granted server advertised, so a server that
-quietly gains or loses a tool is reported the next time a live run sees it.

package/demos/mcp-ticket-testing/agents.nornagent

@@ -1,77 +0,0 @@
-# Ticket testing — declared MCP servers, granted per agent.
-#
-# Every server this graph uses is declared here, beside the model, so the file says exactly
-# what it connects to. Nothing is left to a norn.config.json the reader cannot see.
-
-model Workbench
-    provider openai
-    name gpt-4o
-    apiKey {{$env.OPENAI_API}}
-end model
-
-# The browser. This demo ships a deterministic stand-in so it runs anywhere `node` does —
-# the declaration is the same shape a real Playwright MCP server takes:
-#
-#   mcp Browser
-#       transport stdio
-#       command npx playwright-mcp --headless --isolated
-#       session agent
-#   end mcp
-#
-# ...or, for a long-lived server you started yourself (a CI job with many sequences):
-#
-#   mcp Browser
-#       transport http
-#       url {{$env.BROWSER_MCP_URL}}     # e.g. http://localhost:8931/mcp
-#       timeout 120000                   # browser work is slow; the default is not for this
-#   end mcp
-mcp Browser
-    transport stdio
-    command node ./servers/browser-server.js
-    # One browser per agent invocation, closed when that hop ends. The default, `session run`,
-    # would share one browser across every agent in the sequence — which is what you want for a
-    # continuous flow, and what you do not want the moment a second agent is granted this server:
-    # it would inherit the first one's login and could pass a test it never authenticated for.
-    # Only FrontendTester reaches the browser here, so this is the safe default to author rather
-    # than a bleed this graph would actually suffer.
-    session agent
-end mcp
-
-# The team's own server: fixtures, endpoints, the audit log, the database.
-mcp House
-    transport stdio
-    command node ./servers/house-server.js
-end mcp
-
-agent FrontendTester
-    model Workbench
-    # The run of the browser: this agent drives the site, and which tools that needs is not
-    # something the author should have to enumerate.
-    mcp Browser
-    # From our own server it gets only what it needs to set up — and cannot reach the
-    # database or the audit log at all.
-    tools House.getFixtureUser, House.resetTenant
-    returns contracts/test-run.schema.json
-    system file prompts/frontend-tester.md
-end agent
-
-agent BackendTester
-    model Workbench
-    # The same server, narrowed differently. Both grants are visible per agent, in one file.
-    tools House.callEndpoint, House.readAuditLog, House.queryDb
-    returns contracts/test-run.schema.json
-    system file prompts/backend-tester.md
-end agent
-
-agent Reporter
-    model Workbench
-    system file prompts/reporter.md
-end agent
-
-agent Reviewer
-    model Workbench
-    system "
-    You are reviewing a QA report against a checklist of expected test cases.
-    Rule on each expectation independently and quote the report as evidence.
-    "
-end agent

package/demos/mcp-ticket-testing/contracts/test-run.schema.json

@@ -1,31 +0,0 @@
-{
-    "type": "object",
-    "additionalProperties": false,
-    "properties": {
-        "surface": {
-            "type": "string",
-            "description": "Which side of the product was exercised: frontend or backend."
-        },
-        "cases": {
-            "type": "array",
-            "description": "One entry per test case actually carried out.",
-            "items": {
-                "type": "object",
-                "additionalProperties": false,
-                "properties": {
-                    "name": { "type": "string" },
-                    "steps": { "type": "array", "items": { "type": "string" } },
-                    "outcome": { "type": "string", "enum": ["passed", "failed"] },
-                    "evidence": { "type": "string" }
-                },
-                "required": ["name", "steps", "outcome", "evidence"]
-            }
-        },
-        "findings": {
-            "type": "array",
-            "description": "Anything that looked wrong. Empty when nothing did.",
-            "items": { "type": "string" }
-        }
-    },
-    "required": ["surface", "cases", "findings"]
-}

package/demos/mcp-ticket-testing/expectations/proj-142.md

@@ -1,12 +0,0 @@
-# Expected test cases for PROJ-142
-
-# Each line below is one expectation. All must be met; testing more than this is not a
-# failure. Lines starting with # are comments — prose left uncommented here would itself
-# become an expectation, which is both Norn's comment rule and what makes Markdown work.
-
-- A test covers that a signed-out visitor opening /orders is sent to the sign-in page
-- A test covers signing in and seeing the orders list
-- A test covers opening order A-1001 and reading its total
-- A test covers GET /orders/A-1001 returning 200 with the order
-- A test covers GET /orders/A-9999 returning 404
-- A test confirms endpoint calls reach the audit log

package/demos/mcp-ticket-testing/fixtures/proj-142.json

@@ -1,13 +0,0 @@
-{
-    "key": "PROJ-142",
-    "title": "Order detail page and order lookup endpoint",
-    "description": "A signed-in customer can open an order from the orders list and see its total. The API must return the order for a valid id and 404 for an unknown one.",
-    "acceptanceCriteria": [
-        "A signed-out visitor who opens /orders is sent to the sign-in page",
-        "After signing in, the orders list shows the customer's orders",
-        "Opening order A-1001 shows its total",
-        "GET /orders/A-1001 returns 200 with the order",
-        "GET /orders/A-9999 returns 404",
-        "Every endpoint call is written to the audit log"
-    ]
-}

package/demos/mcp-ticket-testing/prompts/backend-tester.md

@@ -1,12 +0,0 @@
-You test the backend of a web product through its team's own MCP server.
-
-Work only from the ticket you are given. For each acceptance criterion that is about an API,
-a database row, or an audit entry, exercise it with the tools you have and record what came
-back — never what you assume would come back.
-
-`callEndpoint` calls the API. `queryDb` reads seeded tables. `readAuditLog` returns what this
-run wrote. You have no browser, and you must not claim to have used one.
-
-Return the required JSON only: one case per criterion you exercised, the steps you took, the
-outcome, and a short quote of the evidence you saw. Put anything that looked wrong in
-`findings`. Set `surface` to "backend".

package/demos/mcp-ticket-testing/prompts/frontend-tester.md

@@ -1,14 +0,0 @@
-You test the front end of a web product by driving a browser through an MCP server.
-
-Work only from the ticket you are given. For each acceptance criterion that is about what a
-person sees or does in the browser, carry out the steps yourself with the browser tools and
-record what actually happened — never what you assume would happen.
-
-The browser starts signed out. `getFixtureUser` gives you the test account; `resetTenant`
-puts the tenant back to its seeded state before you start.
-
-Snapshots are text. Read the elements listed in a snapshot rather than guessing at a page.
-
-Return the required JSON only: one case per criterion you exercised, the steps you took, the
-outcome, and a short quote of the evidence you saw. Put anything that looked wrong in
-`findings`. Set `surface` to "frontend".

package/demos/mcp-ticket-testing/prompts/reporter.md

@@ -1,10 +0,0 @@
-You turn two test runs into one short QA report for a ticket.
-
-You are given the frontend run and the backend run. Write, in plain prose:
-
-1. Which test cases were carried out, naming each one.
-2. What the evidence was for each.
-3. Any findings, or a single sentence saying there were none.
-
-Report only what the runs contain. Do not invent a case that nobody ran, and do not soften a
-failure. Someone will check this report against the list of expected test cases.

package/demos/mcp-ticket-testing/servers/browser-server.js

@@ -1,133 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * A deterministic stand-in for Playwright MCP.
- *
- * The `mcp Browser` block in `agents.nornagent` is the *same shape* a real Playwright MCP
- * declaration takes — see the commented block there — so this demo runs anywhere `node` does,
- * with no browser download, while showing exactly what granting a browser looks like.
- *
- * It answers from a tiny scripted site, and its snapshots are text, which is what a browser
- * agent should be working from anyway: image content never reaches a model's prompt.
- */
-
-const { Server } = require('@modelcontextprotocol/sdk/server/index.js');
-const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio.js');
-const { ListToolsRequestSchema, CallToolRequestSchema } = require('@modelcontextprotocol/sdk/types.js');
-
-const PAGES = {
-    '/login': {
-        title: 'Sign in',
-        elements: ['textbox "Email"', 'textbox "Password"', 'button "Sign in"']
-    },
-    '/orders': {
-        title: 'Your orders',
-        elements: ['link "A-1001"', 'link "A-1002"', 'button "New order"']
-    },
-    '/orders/A-1001': {
-        title: 'Order A-1001',
-        elements: ['heading "Order A-1001"', 'text "Total: 42.50"', 'button "Cancel order"']
-    }
-};
-
-const state = { url: '/login', signedIn: false, filled: {} };
-
-const TOOLS = [
-    {
-        name: 'browser_navigate',
-        description: 'Navigate to a path on the site under test.',
-        inputSchema: {
-            type: 'object',
-            additionalProperties: false,
-            properties: { path: { type: 'string', description: 'Path to open, e.g. /orders.' } },
-            required: ['path']
-        }
-    },
-    {
-        name: 'browser_fill',
-        description: 'Fill a named field on the current page.',
-        inputSchema: {
-            type: 'object',
-            additionalProperties: false,
-            properties: {
-                field: { type: 'string', description: 'Field label, e.g. Email.' },
-                value: { type: 'string', description: 'Value to type.' }
-            },
-            required: ['field', 'value']
-        }
-    },
-    {
-        name: 'browser_click',
-        description: 'Click a named control on the current page.',
-        inputSchema: {
-            type: 'object',
-            additionalProperties: false,
-            properties: { control: { type: 'string', description: 'Control label, e.g. Sign in.' } },
-            required: ['control']
-        }
-    },
-    {
-        name: 'browser_snapshot',
-        description: 'Return a text accessibility snapshot of the current page.',
-        inputSchema: { type: 'object', additionalProperties: false, properties: {} }
-    }
-];
-
-function structured(value) {
-    return { content: [{ type: 'text', text: JSON.stringify(value) }], structuredContent: value };
-}
-
-function snapshot() {
-    const page = PAGES[state.url] || { title: 'Not found', elements: [] };
-    return {
-        url: state.url,
-        title: page.title,
-        signedIn: state.signedIn,
-        elements: page.elements
-    };
-}
-
-async function main() {
-    const server = new Server(
-        { name: 'norn-demo-browser', version: '1.0.0' },
-        { capabilities: { tools: {} } }
-    );
-
-    server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
-
-    server.setRequestHandler(CallToolRequestSchema, async request => {
-        const args = request.params.arguments || {};
-        switch (request.params.name) {
-            case 'browser_navigate':
-                state.url = String(args.path || '/');
-                if (state.url !== '/login' && !state.signedIn) {
-                    // The whole point of a session: an unauthenticated visit lands on login.
-                    state.url = '/login';
-                }
-                return structured(snapshot());
-            case 'browser_fill':
-                state.filled[String(args.field)] = String(args.value);
-                return structured({ filled: args.field, ...snapshot() });
-            case 'browser_click':
-                if (String(args.control) === 'Sign in' && state.filled.Email && state.filled.Password) {
-                    state.signedIn = true;
-                    state.url = '/orders';
-                }
-                return structured(snapshot());
-            case 'browser_snapshot':
-                return structured(snapshot());
-            default:
-                return {
-                    isError: true,
-                    content: [{ type: 'text', text: `Unknown tool: ${request.params.name}` }]
-                };
-        }
-    });
-
-    await server.connect(new StdioServerTransport());
-}
-
-main().catch(error => {
-    console.error(error instanceof Error ? error.message : String(error));
-    process.exit(1);
-});