Dash-books: delete fixture mode + Phase 1 (catalog-query model, operator-config connection, CLI DX)

[aaltshuler]

Implements dash-books-canon.md through Phase 1 (read-only). Five reviewable commits: a fixture-deletion baseline, then Phase 1A–1D.

Baseline — delete fixture mode + canon (4431942)

• Remove @modernrelay/notebook-fixture and all fixture-mode wiring; the notebook runs only against omnigraph-server via the SDK (no in-memory mock).
• Add dash-books-canon.md (concept, modules, current state, target shape, phased ledger).

Phase 1A — query model (5f94d13)

Consistency over canon (§4.1): cells bind to server-owned catalog queries by name.

• query.ref → og.queries.invoke (the default); query.rawGq → ad-hoc og.query (gated escape hatch).
• Delete the client-side compiler — translate.ts read path, the ego planner, the nodes/path/ego DSL.
• Strict v1 schema (rejects stale keys — internal tool, no version negotiation).
• Author 3 catalog .gq queries + register them in the demo cluster; migrate company-server.notebook.yaml to ref.

Phase 1B — operator-config connection (7fb956c)

• New Node-only @modernrelay/notebook-client/node resolver: ~/.omnigraph/config.yaml + credentials (0600), named servers, keyed-token chain (OMNIGRAPH_TOKEN_<SERVER> → credentials → OMNIGRAPH_BEARER_TOKEN), profiles. Wired into CLI + TUI; web stays on the view proxy.

Phase 1C — CLI DX (7977709)

• --version, per-command --help, render --watch, omnigraph-notebook bin alias.

Phase 1D — docs (451d251)

• CLAUDE / AGENTS / README refreshed to the ref/rawGq + operator-config model.

Verification

• pnpm -r build / typecheck / test green — 56 tests.
• Offline CLI (validate/catalog/schema/--version/--help) smoke-tested.

Deferred (tracked in the canon ledger)

• Live-catalog notebook validate (ref/param checks via og.queries.list()).
• view/tui live-reload --watch (needs websocket / Ink-reconciler work).
• Phase 2 (typed result envelopes + auto tier) gated on the omnigraph-side "declared query outputs" feature (§4.3, option a).

🤖 Generated with Claude Code

Greptile Summary

This PR implements Phase 1 of dash-books-canon.md: it removes fixture mode entirely, migrates the cell query model from a client-side compiled DSL to server-owned catalog queries (query.ref → og.queries.invoke) with a capability-gated raw .gq escape hatch (query.rawGq), adds the Node-only operator-config resolver (~/.omnigraph/config.yaml + credentials), and delivers CLI DX improvements (--version, per-command --help, render --watch).

• Fixture mode deleted across all packages: @modernrelay/notebook-fixture wiring removed from CLI, TUI, and web; NotebookSchema / CellSchema / QuerySchema all gain .strict() and drop the fixture / source keys.
• Operator-config resolver (packages/client/src/operator.ts): reads ~/.omnigraph/config.yaml + credentials (0600-enforced), resolves named servers, profiles, and a keyed-token chain; Client no longer reads env for tokens.
• Web canvas layout in App.tsx replaced by a responsive 6-column grid with dnd-kit drag-reorder and resize; proxy.ts now explicitly drops client-supplied Authorization before injecting the server-side token.

Confidence Score: 5/5

Safe to merge — a large but coherent refactor with no active data paths broken and 56 tests green.

The fixture-removal and query-model migration are complete end-to-end: schema, runtime, source, CLI, TUI, and web all move together. The operator-config resolver is new but isolated to Node-only entry points and has its own test coverage. The only non-trivial concern is the as SdkRead type assertion in invoke(), which is a type-safety trade-off rather than a correctness issue at runtime given the expectMutation: false server-side guard.

packages/client/src/http.ts — the invoke() cast warrants a second look once the SDK exposes a narrowed return type.

Important Files Changed

Filename	Overview
packages/client/src/operator.ts	New Node-only operator-config resolver: reads ~/.omnigraph/config.yaml + credentials with 0600 enforcement, keyed-token chain, named-server registry, and profile support. Logic is clean and handles all precedence levels correctly.
packages/client/src/http.ts	Adds invoke() for server-owned catalog queries; removes env-fallback token resolution from Client constructor. The as SdkRead cast in invoke() is the only concern.
packages/core/src/spec/index.ts	Strict v1 schema: removes fixture DSL, migrates query model to ref/rawGq XOR, adds Timeline/Card/Quote lens kinds, cell width, and .strict() across all schemas.
packages/core/src/runtime/types.ts	SourceCapabilities simplified to namedQueries + rawGq; ReadRequest gets queryRef field; FixtureQuery types removed.
packages/core/src/runtime/compatibility.ts	Compatibility validation migrated: ref cells check namedQueries capability; rawGq without capability is now a hard error.
packages/cli/src/source.ts	resolveConnection delegates to operator resolver; Connection interface tightened (server/graphId now required). buildSource removes fixture branch cleanly.
packages/cli/src/serve.ts	Fixture mode removed; bare-host redirect added; allowRawGq forwarded as ?allowRawGq=1.
packages/cli/src/proxy.ts	BFF proxy now explicitly deletes client-supplied Authorization/Proxy-Authorization before injecting the server-side token — security improvement.
packages/cli/src/cli.ts	Adds --version/-v, per-command --help, COMMAND_HELP registry, SOURCE_FLAGS constant. Clean DX improvements.
packages/cli/src/commands/render.ts	Adds --watch mode with 50ms debounce; splits into renderOnce + safeRender helpers; watch mode holds event loop intentionally.
packages/web/src/App.tsx	Major UI rework: 6-column responsive canvas grid with dnd-kit drag-reorder, resize in edit mode, auto-animate, localStorage-persisted overrides.
packages/web/src/config.ts	Fixture mode removed; token fallback changed from devtoken to undefined; allowRawGq wired via isTruthyParam.
packages/client/src/source.ts	ServerSource.read dispatches on queryRef (invoke) vs querySource (rawGq); all client-side translation removed.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
    participant CLI as CLI / TUI
    participant OpRes as operator.ts resolveConnection
    participant Config as ~/.omnigraph/config.yaml + credentials
    participant Client as Client (http.ts)
    participant Source as ServerSource
    participant Server as omnigraph-server

    CLI->>OpRes: flags + notebook.server/graph
    OpRes->>Config: loadOperatorConfig() + loadCredentials()
    Config-->>OpRes: servers, profiles, defaults, tokens
    OpRes-->>CLI: ResolvedConnection
    CLI->>Client: new Client
    CLI->>Source: new ServerSource

    Note over Source,Server: query.ref path (canonical)
    Source->>Client: invoke(name, params)
    Client->>Server: "POST /graphs/{id}/queries/{name}"
    Server-->>Client: Read response
    Client-->>Source: ReadOutput

    Note over Source,Server: query.rawGq path (escape hatch, gated)
    Source->>Client: "query({ query: rawGq })"
    Client->>Server: "POST /graphs/{id}/query"
    Server-->>Client: Read response
    Client-->>Source: ReadOutput

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
    participant CLI as CLI / TUI
    participant OpRes as operator.ts resolveConnection
    participant Config as ~/.omnigraph/config.yaml + credentials
    participant Client as Client (http.ts)
    participant Source as ServerSource
    participant Server as omnigraph-server

    CLI->>OpRes: flags + notebook.server/graph
    OpRes->>Config: loadOperatorConfig() + loadCredentials()
    Config-->>OpRes: servers, profiles, defaults, tokens
    OpRes-->>CLI: ResolvedConnection
    CLI->>Client: new Client
    CLI->>Source: new ServerSource

    Note over Source,Server: query.ref path (canonical)
    Source->>Client: invoke(name, params)
    Client->>Server: "POST /graphs/{id}/queries/{name}"
    Server-->>Client: Read response
    Client-->>Source: ReadOutput

    Note over Source,Server: query.rawGq path (escape hatch, gated)
    Source->>Client: "query({ query: rawGq })"
    Client->>Server: "POST /graphs/{id}/query"
    Server-->>Client: Read response
    Client-->>Source: ReadOutput

Loading

Comments Outside Diff (1)

1. packages/web/src/config.ts, line 35-47 (link)

   notebook.server can now be an operator-config name, producing a confusing error in the browser

   NotebookSchema.server was widened from z.url() to z.string().min(1) to allow operator-config server names (e.g. server: prod). In buildConfig, notebook.server is the fallback when no ?server= URL param is present. If a CLI-targeted notebook has server: "prod", this code passes "prod" to new Client({ baseUrl: "prod" }), which fails at the SDK layer with an opaque fetch error rather than a clear schema validation message. The previous z.url() constraint would have caught this at parse time.

   

_{Reviews (4): Last reviewed commit: "Interactive canvas: drag/resize tiles, r..." | Re-trigger Greptile}

[greptile-apps]

query.name can be set alongside query.ref with no validation error, but is silently ignored

name is documented as "Selects a query within a multi-query rawGq payload" and is only consumed by ServerSource.read on the rawGq code path. When a cell uses query.ref, runtime.ts copies cell.query.name into ReadRequest.queryName, but ServerSource.invoke never reads it. An author who writes query: { ref: "foo", name: "bar" } will get no error and no effect. A refinement guarding name to the rawGq branch would make the constraint explicit.