@plurnk/plurnk-grammar 0.1.1 → 0.2.1

package/src/types.generated.ts

@@ -0,0 +1,497 @@
+// @generated by scriptify/generate-types.ts from schema/*.json
+// DO NOT EDIT — run `npm run build:types` to regenerate.
+
+export interface Agent {
+version: number
+provider: ProviderDeclaration
+/**
+ * Agent-wide default scheme registrations. The v0 inventory ships with `plurnk`, `known`, `unknown`; everything else is plugin-registered.
+ */
+scheme_registry: SchemeRegistration[]
+}
+/**
+ * Declaration of the active provider for an agent. The grammar package owns these four fields; auth/connection config lives in the agent repo.
+ */
+
+export interface ProviderDeclaration {
+/**
+ * API vendor identifier (e.g. "anthropic", "openai", "google", "local").
+ */
+provider: string
+/**
+ * Model family (e.g. "claude", "gpt", "gemini", "llama").
+ */
+family: string
+/**
+ * Specific model id (e.g. "claude-opus-4-7").
+ */
+model: string
+/**
+ * Total context window in tokens.
+ */
+contextSize: number
+/**
+ * ISO 4217 code; the unit `cost_pico` is denominated in.
+ */
+currency: string
+}
+/**
+ * A scheme entry in the agent's scheme registry. Defines what `<name>://` resolves to and how it's accessible.
+ */
+
+export interface SchemeRegistration {
+/**
+ * Scheme name without `://`. Matches the URL scheme character class.
+ */
+name: string
+model_visible: boolean
+category: string
+default_scope: ("agent" | "session")
+/**
+ * Channel name selected when an op against this scheme has no fragment. Conventionally `body`; exec schemes typically declare `stdout`.
+ */
+default_channel: string
+/**
+ * Per-channel content-orientation hints. `head` = whole-document or front-anchored (readers care about the beginning); `tail` = append-temporal stream (readers care about the latest content). Channels not listed default to `head`. Renderers use this to pick truncation direction; the amount to render is a core/runtime concern, not a contract field.
+ */
+channel_orientations?: {
+[k: string]: ("head" | "tail")
+}
+writable_by: ("model" | "client" | "system" | "plugin")[]
+volatile: boolean
+handler: (string | null)
+}
+
+export interface ChannelContent {
+/**
+ * Raw content bytes/string for this channel. Binary content awaits a future encoding pass (see AGENTS.md).
+ */
+content: string
+mimetype: string
+/**
+ * Token count of `content` under the active model's tokenizer.
+ */
+tokens: number
+}
+
+export type Entry = ({
+[k: string]: unknown
+} & {
+id: number
+version: number
+scope: ("agent" | "session")
+session_id: (number | null)
+scheme: (string | null)
+username: (string | null)
+password: (string | null)
+hostname: (string | null)
+port: (number | null)
+pathname: string
+params: (Params | null)
+/**
+ * Named channels on this entry. Keys are channel names (lowercase identifiers); values are ChannelContent. Must be non-empty. The scheme registry declares which channel is the default for unspecified ops.
+ */
+channels: {
+[k: string]: ChannelContent
+}
+attributes: {
+
+}
+tags: string[]
+})
+
+/**
+ * URL query parameters parsed into a JSON object. Single-value keys map to strings; multi-value keys (repeated in the original query string) map to arrays of strings. Empty object when the URL has no query string; nullable usages wrap this schema in a oneOf with null.
+ */
+
+export interface Params {
+[k: string]: (string | string[])
+}
+/**
+ * One named stream of content on an entry. Channels carry distinct, parallel views of an entry (e.g. `stdout` and `stderr` on `exec://`; `body` and `headers` on `https://`; `body` and `symbols` on a code file). Each channel has its own content bytes, mimetype, and token count.
+ */
+
+export interface LineMarker {
+first: number
+last: (number | null)
+}
+
+export type LogEntry = ({
+[k: string]: unknown
+} & {
+id: number
+version: number
+run_id: number
+loop_id: number
+turn_id: number
+action_index: number
+at: string
+origin: ("model" | "client" | "system" | "plugin")
+op: ("FIND" | "READ" | "EDIT" | "COPY" | "MOVE" | "SHOW" | "HIDE" | "SEND" | "EXEC")
+suffix: string
+signal: (string[] | number | string | null)
+target_scheme: (string | null)
+target_username: (string | null)
+target_password: (string | null)
+target_hostname: (string | null)
+target_port: (number | null)
+target_pathname: (string | null)
+target_params: (Params | null)
+/**
+ * Channel selector at request time. Names the channel the op targeted; null when the op used the scheme's default channel.
+ */
+target_fragment: (string | null)
+lineMarker: (LineMarker | null)
+/**
+ * Raw request payload. For origin=model: the literal plurnk DSL substring of assistant.content. For origin=system/client/plugin: whatever the originator emitted, with `mimetype_tx` declaring the structure.
+ */
+tx: string
+/**
+ * Mimetype of `tx`. Typically `text/x-plurnk` for model-origin rows; arbitrary per-origin for system/client/plugin.
+ */
+mimetype_tx: string
+/**
+ * Raw response payload bytes/string.
+ */
+rx: string
+mimetype_rx: string
+status_rx: number
+tokens: number
+})
+
+/**
+ * URL query parameters parsed into a JSON object. Single-value keys map to strings; multi-value keys (repeated in the original query string) map to arrays of strings. Empty object when the URL has no query string; nullable usages wrap this schema in a oneOf with null.
+ */
+
+export interface Loop {
+id: number
+version: number
+run_id: number
+/**
+ * 1-based within the run.
+ */
+sequence: number
+/**
+ * 102 = continuing; 200 = terminal success; 499 = terminal cancellation.
+ */
+status: (102 | 200 | 499)
+/**
+ * The original user prompt for this loop, replayed on every turn.
+ */
+prompt: string
+}
+
+export type MatcherBody = (XPathBody | RegexBody | JsonPathBody | GlobBody)
+
+/**
+ * XPath 1.0 expression. Validated at parse time via the xpath library.
+ */
+
+export interface XPathBody {
+dialect: "xpath"
+raw: string
+}
+/**
+ * JavaScript regex literal `/pattern/flags`. Pattern and flags are split out for direct use. `raw` preserves the literal form for round-tripping.
+ */
+
+export interface RegexBody {
+dialect: "regex"
+raw: string
+pattern: string
+flags: string
+}
+/**
+ * JSONPath expression. Validated at parse time via jsonpath-plus.
+ */
+
+export interface JsonPathBody {
+dialect: "jsonpath"
+raw: string
+}
+/**
+ * Pattern with no dialect prefix; treated as a glob/literal match.
+ */
+
+export interface GlobBody {
+dialect: "glob"
+raw: string
+}
+
+export type PlurnkStatement = (FindStatement | ReadStatement | ShowStatement | HideStatement | EditStatement | CopyStatement | MoveStatement | SendStatement | ExecStatement)
+/**
+ * A parsed path slot from a plurnk statement. Discriminated on `kind`: either a bare local path (no scheme) or a fully decomposed URL.
+ */
+
+export type ParsedPath = (LocalPath | UrlPath)
+/**
+ * Parsed body of a FIND/READ/SHOW/HIDE statement, discriminated on `dialect`. The dialect is determined by the body's leading characters (`//` xpath, `/` regex, `$` jsonpath, else glob). The regex variant carries pattern/flags split out of the `/pattern/flags` literal; the compiled `RegExp` object on the in-memory AST is a runtime ergonomic only and is not part of the persisted/wire contract.
+ */
+
+export interface Packet {
+/**
+ * Total packet tokens — sum of section subtotals.
+ */
+tokens: number
+system: {
+tokens: number
+/**
+ * text/markdown — plurnk grammar + scheme registry refs.
+ */
+system_definition: string
+/**
+ * text/markdown — identity / mission.
+ */
+persona: string
+index: Entry[]
+log: LogEntry[]
+}
+user: {
+tokens: number
+/**
+ * Copy of loop.prompt — never null on a continuation turn.
+ */
+prompt: string
+/**
+ * text/markdown — dynamically generated tables for budget/status/counts.
+ */
+turn: string
+/**
+ * text/markdown — per-turn rules.
+ */
+system_requirements: string
+}
+assistant: {
+tokens: number
+/**
+ * Raw DSL string emitted by the model.
+ */
+content: string
+/**
+ * Parsed PlurnkStatement[] derived from `content`.
+ */
+ops: PlurnkStatement[]
+/**
+ * text/plain — provider-exposed CoT when present, null otherwise.
+ */
+reasoning: (string | null)
+[k: string]: unknown
+}
+assistantRaw: unknown
+}
+/**
+ * URL query parameters parsed into a JSON object. Single-value keys map to strings; multi-value keys (repeated in the original query string) map to arrays of strings. Empty object when the URL has no query string; nullable usages wrap this schema in a oneOf with null.
+ */
+
+export interface FindStatement {
+op: "FIND"
+suffix: string
+signal: (string[] | null)
+path: (ParsedPath | null)
+lineMarker: (LineMarker | null)
+body: (MatcherBody | null)
+position: Position
+}
+/**
+ * A bare local path with no `scheme://` prefix. The raw string is stored verbatim; resolution is the runtime's job.
+ */
+
+export interface LocalPath {
+kind: "local"
+raw: string
+}
+/**
+ * A path with a `scheme://` prefix, fully decomposed via WHATWG URL.
+ */
+
+export interface UrlPath {
+kind: "url"
+raw: string
+scheme: string
+username: (string | null)
+password: (string | null)
+hostname: (string | null)
+port: (number | null)
+pathname: string
+params: Params
+fragment: (string | null)
+}
+/**
+ * XPath 1.0 expression. Validated at parse time via the xpath library.
+ */
+
+export interface Position {
+line: number
+column: number
+}
+
+export interface ReadStatement {
+op: "READ"
+suffix: string
+signal: (string[] | null)
+path: (ParsedPath | null)
+lineMarker: (LineMarker | null)
+body: (MatcherBody | null)
+position: Position
+}
+
+export interface ShowStatement {
+op: "SHOW"
+suffix: string
+signal: (string[] | null)
+path: (ParsedPath | null)
+lineMarker: (LineMarker | null)
+body: (MatcherBody | null)
+position: Position
+}
+
+export interface HideStatement {
+op: "HIDE"
+suffix: string
+signal: (string[] | null)
+path: (ParsedPath | null)
+lineMarker: (LineMarker | null)
+body: (MatcherBody | null)
+position: Position
+}
+
+export interface EditStatement {
+op: "EDIT"
+suffix: string
+signal: (string[] | null)
+path: (ParsedPath | null)
+lineMarker: (LineMarker | null)
+body: (string | null)
+position: Position
+}
+
+export interface CopyStatement {
+op: "COPY"
+suffix: string
+signal: (string[] | null)
+path: (ParsedPath | null)
+lineMarker: (LineMarker | null)
+body: (ParsedPath | null)
+position: Position
+}
+
+export interface MoveStatement {
+op: "MOVE"
+suffix: string
+signal: (string[] | null)
+path: (ParsedPath | null)
+lineMarker: (LineMarker | null)
+body: (ParsedPath | null)
+position: Position
+}
+
+export interface SendStatement {
+op: "SEND"
+suffix: string
+signal: (number | null)
+path: (ParsedPath | null)
+lineMarker: null
+body: (SendBody | null)
+position: Position
+}
+/**
+ * Parsed body of a SEND statement. `raw` is the literal body text; `json` is the best-effort `JSON.parse(raw)` result, or null when the body isn't valid JSON.
+ */
+
+export interface SendBody {
+raw: string
+json: unknown
+}
+
+export interface ExecStatement {
+op: "EXEC"
+suffix: string
+signal: (string | null)
+path: (ParsedPath | null)
+lineMarker: null
+body: (string | null)
+position: Position
+}
+
+export type TagSignal = (string[] | null)
+
+export type PathOrNull = (ParsedPath | null)
+/**
+ * A parsed path slot from a plurnk statement. Discriminated on `kind`: either a bare local path (no scheme) or a fully decomposed URL.
+ */
+
+export type LineMarkerOrNull = (LineMarker | null)
+
+export type MatcherBodyOrNull = (MatcherBody | null)
+/**
+ * Parsed body of a FIND/READ/SHOW/HIDE statement, discriminated on `dialect`. The dialect is determined by the body's leading characters (`//` xpath, `/` regex, `$` jsonpath, else glob). The regex variant carries pattern/flags split out of the `/pattern/flags` literal; the compiled `RegExp` object on the in-memory AST is a runtime ergonomic only and is not part of the persisted/wire contract.
+ */
+
+export type SendBodyOrNull = (SendBody | null)
+
+export interface Run {
+id: number
+version: number
+session_id: number
+created_at: string
+/**
+ * FK to parent run when this is a fork; null for the trunk run.
+ */
+parent_run_id: (number | null)
+/**
+ * Cumulative cost across this run's turns, in pico-units of the active provider's currency.
+ */
+cost_pico: number
+}
+
+export interface Session {
+id: number
+version: number
+/**
+ * Unique within the agent. Default form: `{modelAlias}-{unixtime}` until renamed.
+ */
+name: string
+created_at: string
+/**
+ * Cumulative cost across this session's runs.
+ */
+cost_pico: number
+scheme_registry_additions: SchemeRegistration[]
+}
+/**
+ * A scheme entry in the agent's scheme registry. Defines what `<name>://` resolves to and how it's accessible.
+ */
+
+export interface Turn {
+id: number
+version: number
+loop_id: number
+/**
+ * 1-based within the loop; resets at each new loop.
+ */
+sequence: number
+timestamp: string
+status: number
+/**
+ * Provider-returned token counts and computed cost.
+ */
+usage: {
+prompt: number
+completion: number
+cached: number
+/**
+ * Per-turn cost in pico-units of the active provider's currency.
+ */
+cost_pico: number
+}
+packet: Packet
+}
+/**
+ * One turn's full exchange with the provider: { system, user, assistant, assistantRaw }. system aggregates durable + accumulating context (definition, persona, indexed entries, in-scope log rows). user carries the per-turn ephemera. assistant is the provider-normalized output. assistantRaw is opaque.
+ */
+
+export interface Visibility {
+entry_id: number
+channel: string
+indexed: boolean
+}

package/src/types.ts

@@ -0,0 +1,30 @@
+// Schema-derived types are generated from schema/*.json — re-exported here as
+// the single import surface for consumers. Run `npm run build:types` to regenerate.
+export * from "./types.generated.ts";
+
+import type { Position, PlurnkStatement } from "./types.generated.ts";
+import type PlurnkParseError from "./PlurnkParseError.ts";
+
+// Non-schema types — depend on the PlurnkParseError class and so can't be
+// expressed in JSON Schema. Hand-maintained.
+
+export type PlurnkOp =
+    | "FIND"
+    | "READ"
+    | "EDIT"
+    | "COPY"
+    | "MOVE"
+    | "SHOW"
+    | "HIDE"
+    | "SEND"
+    | "EXEC";
+
+export type ParseItem =
+    | { kind: "statement"; statement: PlurnkStatement }
+    | { kind: "error"; error: PlurnkParseError }
+    | { kind: "text"; text: string; position: Position };
+
+export type ParseResult = {
+    items: ParseItem[];
+    unparsedTail?: { from: Position; reason: string };
+};