@meridian-flow/mars-schema 0.0.0-stage → 0.20.1

package/index.d.ts

@@ -0,0 +1,418 @@
+// Types for @meridian-flow/mars-schema. The wasm-bindgen declarations under node/ and web/
+// are untyped (`any`); this file is the contract. Every result is a plain object or array
+// (`null` for an absent value, `Uint8Array` for bytes), pinned by the shipped `fixtures/`.
+
+export type JsonValue =
+  | null
+  | boolean
+  | number
+  | string
+  | JsonValue[]
+  | { [key: string]: JsonValue };
+
+/** Build-time version of the schema crate. */
+export function version(): string;
+
+// ---------------------------------------------------------------------------------------
+// read
+// ---------------------------------------------------------------------------------------
+
+export interface Diagnostic {
+  /** Stable code, e.g. `field.unknown`, `yaml.invalid`, `field.removed`. */
+  code: string;
+  severity: "error" | "warning" | "info";
+  /** Key path into the authored file, e.g. `["model-policies", 0, "when"]`. */
+  path: (string | number)[];
+  message: string;
+  /**
+   * Byte offsets into the text. Present only for fence and YAML-syntax errors (and not yet
+   * set by any reader): locate every other diagnostic by `path`, with your own parser.
+   */
+  range?: { start: number; end: number };
+}
+
+/** The v1 reading of one file. */
+export interface DefinitionRead<Fields> {
+  /**
+   * Every top-level key with its value in file order, unknown keys included. A key whose
+   * value has no JSON form is absent and has a `yaml.non-json-value` diagnostic
+   * (`toml.non-json-value` for `mars.toml`). That covers a YAML tag, a non-string map key,
+   * an integer beyond ±(2^53 − 1), NaN or infinity (TOML), and a `__proto__` key at any depth.
+   * Mapping keys, nested ones included, are in file order (JavaScript lists integer-like keys
+   * such as `"1"` first). For `mars.toml`, the pairs of the `[package]` table in file order;
+   * a TOML datetime is its TOML text, a string (`"1979-05-27"`).
+   */
+  frontmatter: [string, JsonValue][];
+  /** Typed fields in file spellings; `null` when the file cannot be read at all. */
+  fields: Fields | null;
+  /** Text after the frontmatter; `null` for `mars.toml` or an unreadable file. */
+  body: string | null;
+  diagnostics: Diagnostic[];
+}
+
+export type Effort = "none" | "low" | "medium" | "high" | "xhigh" | "max";
+export type Sandbox = "default" | "read-only" | "workspace-write" | "danger-full-access";
+export type Approval = "default" | "auto" | "confirm" | "never";
+export type Network = "allow" | "deny" | "allowlist";
+export type Harness = "claude" | "codex" | "pi" | "opencode" | "cursor";
+
+export interface ToolRule {
+  /** A canonical capability, `*`, `mcp`, or the author's spelling of an unknown name. */
+  capability: string;
+  pattern: string | null;
+  action: "allow" | "deny" | "ask";
+}
+
+export interface ModelPolicyRule {
+  match: { model: string } | { alias: string } | { "model-glob": string };
+  override?: { effort?: Effort; sandbox?: Sandbox; approval?: Approval; network?: Network };
+  "no-fallback"?: boolean;
+  /** One non-empty line. */
+  when?: string;
+}
+
+export interface AgentFields {
+  name: string | null;
+  description: string | null;
+  harness: Harness | null;
+  model: string | null;
+  mode: "primary" | "subagent" | null;
+  "model-invocable": boolean;
+  "user-invocable": boolean;
+  approval: Approval | null;
+  sandbox: Sandbox | null;
+  /** Shell network mode; `null` follows the sandbox. */
+  network: Network | null;
+  /** Canonical hosts (lowercase, no trailing dot); `{ replace }` clears the lower layers' hosts. */
+  "network-allow": string[] | { replace: string[] };
+  "network-deny": string[];
+  effort: Effort | null;
+  skills: { load: string[]; available: string[] };
+  subagents: string[];
+  tools: ToolRule[];
+  /** Per-namespace passthrough blocks; `flow` is the consumer namespace. */
+  "harness-overrides": { [namespace: string]: { [key: string]: JsonValue } };
+  "model-policies": ModelPolicyRule[];
+}
+
+export interface SkillFields {
+  name: string | null;
+  description: string | null;
+  license: string | null;
+  compatibility: string | null;
+  metadata: JsonValue | null;
+  "model-invocable": boolean;
+  "user-invocable": boolean;
+}
+
+/** `[package]` of `mars.toml`. Absent optional keys are omitted, not `null`. */
+export interface ManifestFields {
+  name: string;
+  version: string;
+  description?: string;
+  authors?: JsonValue;
+  homepage?: JsonValue;
+  license?: JsonValue;
+  schema?: number;
+  "uses-providers"?: string[];
+  "requires-mars"?: string;
+  "requires-meridian"?: string;
+}
+
+export type Reading =
+  | DefinitionRead<ManifestFields>
+  | DefinitionRead<AgentFields>
+  | DefinitionRead<SkillFields>;
+
+/**
+ * Read one file; the package-relative `path` picks the reader. Any path other than
+ * `mars.toml`, `agents/<slug>.md` or `skills/<slug>/SKILL.md` throws.
+ */
+export function read(path: "mars.toml", text: string): DefinitionRead<ManifestFields>;
+export function read(path: `agents/${string}.md`, text: string): DefinitionRead<AgentFields>;
+export function read(path: `skills/${string}/SKILL.md`, text: string): DefinitionRead<SkillFields>;
+export function read(path: string, text: string): Reading;
+
+// ---------------------------------------------------------------------------------------
+// edit
+// ---------------------------------------------------------------------------------------
+
+/**
+ * YAML for the value of the mapping key whose own column is `indent`, to splice right after
+ * `key:`.
+ * - A scalar is one line with no leading newline: splice it after `key: `.
+ * - A non-empty collection starts with `\n`, and its children sit at column `indent + 2`:
+ *   splice it right after `key:`. An empty one is the one-line `[]` or `{}`.
+ * - The output never ends in a newline.
+ * - Strings are plain only when they are a safe word; everything else, every multi-line
+ *   string included, is JSON double-quoted. Keys follow the same rule.
+ *
+ * Floats of any finite magnitude are written so both YAML parsers read the same number
+ * (`1e+300`). Throws for an integer beyond ±(2^53 − 1), NaN, Infinity, a lone surrogate, and a
+ * mapping key written as more than 1024 characters (YAML's limit for an implicit key).
+ */
+export function emitValue(value: JsonValue, indent: number): string;
+
+/**
+ * The full frontmatter block between the `---` fences for these top-level pairs, in order,
+ * ending in exactly one newline (`""` for no keys). Mapping keys keep the order given
+ * (a JavaScript object lists integer-like keys such as `"1"` first, whatever order they
+ * were set in). Throws for a duplicate key, a key over 1024 characters, and a lone surrogate.
+ *
+ * Do not call it on a reading that has a `yaml.non-json-value` diagnostic: the keys the
+ * reading left out (tags, non-string keys, out-of-range integers, `__proto__`) are not in
+ * `frontmatter`, so the block would silently drop them from the file.
+ */
+export function rewriteBlock(frontmatter: [string, JsonValue][]): string;
+
+// ---------------------------------------------------------------------------------------
+// vocabulary
+// ---------------------------------------------------------------------------------------
+
+export type NativeEntry =
+  | { kind: "tools"; tools: string[] }
+  | { kind: "scoped-tools"; unscoped: string[]; scoped: string[]; note: string }
+  | { kind: "absent" }
+  | { kind: "no-switch"; note: string };
+
+export interface Vocabulary {
+  capabilities: { name: string; aliases: string[] }[];
+  /** Per host (`claude`, `codex`, `opencode`, `pi`, `cursor`, `flow`): capability → native tools. */
+  natives: { [host: string]: { [capability: string]: NativeEntry } };
+}
+
+export function vocabulary(): Vocabulary;
+
+// ---------------------------------------------------------------------------------------
+// prepare, inspect, normalize
+// ---------------------------------------------------------------------------------------
+
+export type Dialect = "claude" | "agent-skills" | "codex" | "opencode" | "cursor" | "mars-native";
+
+/** A foreign dialect a root is read as, and why: `prepare` classifies with it, `inspect` reports it. */
+export interface DialectChoice {
+  dialect: Dialect;
+  evidence: {
+    source: "declared" | "predicted";
+    /** The files that decided a predicted dialect; empty for a declared one. */
+    paths: string[];
+  };
+}
+
+export type Classification =
+  | { kind: "schema-1" }
+  | { kind: "mars-legacy" }
+  | { kind: "schema-newer"; schema: number }
+  | { kind: "invalid" }
+  | ({ kind: "foreign" } & DialectChoice)
+  | { kind: "marketplace" }
+  | { kind: "empty" };
+
+export type ChangeRecord =
+  | { kind: "none" }
+  /** The file has no source: `normalize` wrote it (a package's generated `mars.toml`). */
+  | { kind: "generated" }
+  | { kind: "edited"; paths: (string | number)[][] }
+  | { kind: "fully-rewritten" };
+
+export interface PreparedManifest {
+  /** Absent for a generated manifest. */
+  source_path?: string;
+  output_path: string;
+  normalized_bytes: Uint8Array;
+  reading: DefinitionRead<ManifestFields>;
+  change: ChangeRecord;
+}
+
+export type PreparedDefinition = {
+  slug: string;
+  source_path: string;
+  /** `skills/<slug>/SKILL.md` or `agents/<slug>.md` for a Claude-shaped source. */
+  output_path: string;
+  normalized_bytes: Uint8Array;
+  change: ChangeRecord;
+} & (
+  | { kind: "agent"; reading: DefinitionRead<AgentFields> }
+  | { kind: "skill"; reading: DefinitionRead<SkillFields> }
+);
+
+export interface Prepared {
+  classification: Classification;
+  manifest?: PreparedManifest;
+  definitions: PreparedDefinition[];
+  payload: { source_path: string; output_path: string }[];
+  /**
+   * Package-level findings by source path: what discovery and translation met and could not
+   * convert (`skill.*`, `agent.*`, `import.*`). A file's own reading diagnostics are on its
+   * `reading`.
+   */
+  diagnostics: { [sourcePath: string]: Diagnostic[] };
+  /**
+   * What preparing changed in each file, by source path: the keys a pre-v1 upgrade
+   * (`classification.kind === "mars-legacy"`) or a foreign translation dropped, moved or
+   * repaired (legacy keys, skill tool rules, Claude-only keys, a repaired `description`, a key
+   * set aside under `harness-overrides` or dropped). A change coded `field.restriction-lost`
+   * means a restriction (a `deny` or `ask` tool entry, `permission`, `sandbox`, `approval`) was
+   * dropped or moved, so the agent is less restricted than its file says; a caller reports
+   * these every time. A file changed when its `change.kind` is not `none` or `generated`.
+   * Absent when empty.
+   */
+  changes?: { [sourcePath: string]: Diagnostic[] };
+}
+
+/**
+ * Reads one root held in memory: classify it, select its definitions, upgrade a pre-v1 package
+ * or translate a foreign one, and read each result. This is the supported way to read a single
+ * package, a consumer's `.mars-src` (`"authored-local"`) or a project directory (`"project"`,
+ * where a `mars.toml` with no `[package]` is consumer configuration) without choosing items;
+ * `normalize` is `prepare` plus a selection, a generated `mars.toml` and provenance. Throws for
+ * an unrecognized `context` or `declaredDialect`.
+ */
+export function prepare(input: {
+  files: Map<string, Uint8Array>;
+  context?: "package" | "authored-local" | "project";
+  declaredDialect?: Dialect;
+}): Prepared;
+
+export type Tree = Map<string, Uint8Array>;
+
+export type Kind =
+  | "schema-1"
+  | "mars-legacy"
+  | "schema-newer"
+  | "marketplace"
+  | "plugin"
+  | "skill-tree"
+  | "invalid"
+  | "empty";
+
+export type Checkout =
+  | { kind: "sha"; sha: string }
+  | { kind: "ref"; name: string }
+  | { kind: "default-branch" };
+
+export type PluginSource =
+  /** A directory of the marketplace's own tree; `""` is its root. */
+  | { kind: "local"; path: string }
+  /** A Git repository the caller fetches; `path` roots the plugin inside it. */
+  | { kind: "remote"; repository: string; path?: string; checkout: Checkout }
+  /** `npm`, `archive`, `command`, or a shape this version does not know. */
+  | { kind: "unsupported"; reason: string };
+
+export interface ComponentLists {
+  skills?: string[];
+  agents?: string[];
+  commands?: string[];
+  hooks?: boolean;
+  mcp?: boolean;
+}
+
+/** One marketplace `plugins[]` entry. Pass it back as `hint.plugin.entry` for a fetched tree. */
+export interface MarketplaceEntry {
+  name: string;
+  description?: string;
+  version?: string;
+  source: PluginSource;
+  strict?: boolean;
+  lists: ComponentLists;
+}
+
+export interface Hint {
+  /** Overrides prediction, never a Mars manifest. */
+  dialect?: Dialect;
+  /** The package root inside the tree. */
+  subpath?: string;
+  /** Read the root as this plugin of a marketplace (a fetched remote plugin tree). */
+  plugin?: { entry: MarketplaceEntry; at_marketplace_root?: boolean };
+}
+
+export interface InspectedItem {
+  kind: "skill" | "agent" | "command";
+  slug: string;
+  /** The definition file: `…/SKILL.md`, `agents/x.md` or `commands/x.md`. */
+  source_path: string;
+  /** The skill's directory, whose files travel with it. */
+  skill_root?: string;
+  /** Where the definition lands in schema v1; a command is reported and has none. */
+  output_path?: string;
+  /** A skill's payload files, by source path. */
+  payload?: string[];
+}
+
+export interface Inspection {
+  kind: Kind;
+  /** The dialect read, how it was chosen, and the files that decided it. */
+  dialect?: DialectChoice;
+  /** Other harnesses' copies of the package: found, not read. A `weak` one never decides. */
+  also_found: { dialect: Dialect; paths: string[]; weak: boolean }[];
+  name?: string;
+  version?: string;
+  description?: string;
+  /** A marketplace's plugins. */
+  plugins: {
+    entry: MarketplaceEntry;
+    at_marketplace_root: boolean;
+    /** Items of a plugin in the marketplace's own tree; absent for a remote one. */
+    items?: InspectedItem[];
+    /** Why the plugin cannot be imported. */
+    refused?: string;
+    diagnostics: { [path: string]: Diagnostic[] };
+  }[];
+  /** The items of a plugin or skill tree. */
+  items: InspectedItem[];
+  diagnostics: { [path: string]: Diagnostic[] };
+}
+
+/**
+ * What a repository is, before anything is selected. For a remote marketplace plugin: fetch it,
+ * then call this on the fetched tree with `hint.plugin` set to the plugin's entry.
+ */
+export function inspect(input: { tree: Tree; hint?: Hint }): Inspection;
+
+export interface SourceInfo {
+  name?: string;
+  url?: string;
+  requested_ref?: string;
+  resolved_commit?: string;
+  subpath?: string;
+}
+
+export interface Selection {
+  /** Marketplace plugin names; absent takes every plugin. */
+  plugins?: string[];
+  /** Definition source paths by plugin name (`""` for a root that is not a plugin). */
+  items?: { [plugin: string]: string[] };
+}
+
+export interface NormalizedPackage {
+  /** The plugin name, or the package name. */
+  id: string;
+  provenance: {
+    /** The version of the rules that produced these files. */
+    translator: string;
+    dialect?: Dialect;
+    source: SourceInfo;
+    marketplace?: { plugin: string; plugin_source: PluginSource };
+    selected_items: string[];
+  };
+  prepared: Prepared;
+}
+
+export interface Normalized {
+  kind: Kind;
+  packages: NormalizedPackage[];
+  /** Marketplace-level findings and the reasons a package was left out, by path. */
+  diagnostics: { [path: string]: Diagnostic[] };
+}
+
+/**
+ * Schema v1 packages for a selection. A remote marketplace plugin is fetched by the caller (any
+ * `git-subdir` path applied) and normalized as its own tree with `hint.plugin` set to its entry;
+ * `source` then describes the fetched repository.
+ */
+export function normalize(input: {
+  tree: Tree;
+  source?: SourceInfo;
+  hint?: Hint;
+  selection?: Selection;
+}): Normalized;

package/index.web.d.ts

@@ -0,0 +1,7 @@
+// Types for the web (browser) build of @meridian-flow/mars-schema: the same API, which must be
+// instantiated first with `await init()`. The Node build is synchronous and has no `init`.
+export * from "./index";
+
+export default function init(
+  module_or_path?: RequestInfo | URL | Response | BufferSource | WebAssembly.Module | Promise<unknown>,
+): Promise<unknown>;

package/node/mars_schema_wasm.d.ts

@@ -0,0 +1,45 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/**
+ * YAML for the value of the key at column `indent`; see `index.d.ts`.
+ */
+export function emitValue(value: any, indent: number): string;
+
+/**
+ * What a repository is: `{tree: Map<path, Uint8Array>, hint?}` to an `Inspection`. Reads
+ * manifests, listings and definitions, never payload bytes.
+ */
+export function inspect(input: any): any;
+
+/**
+ * Schema v1 packages for a selection: `{tree, source?, hint?, selection?}` to a `Normalized`.
+ * A remote marketplace plugin is fetched by the caller and normalized as its own tree, with
+ * `hint.plugin` set to the plugin's entry.
+ */
+export function normalize(input: any): any;
+
+/**
+ * Prepare one root from `{files: Map<path, Uint8Array>, context?, declaredDialect?}`. A supported
+ * export in its own right: `normalize` is this plus a selection, a generated manifest and
+ * provenance. An unrecognized `context` or `declaredDialect` throws.
+ */
+export function prepare(input: any): any;
+
+/**
+ * Read one schema file. `path` is package-relative and picks the reader: `mars.toml`,
+ * `agents/<slug>.md` or `skills/<slug>/SKILL.md`. Any other path throws.
+ */
+export function read(path: string, text: string): any;
+
+/**
+ * The full frontmatter block for `[key, value][]`, ending in exactly one newline.
+ */
+export function rewriteBlock(frontmatter: any): string;
+
+/**
+ * Returns the Mars schema package version.
+ */
+export function version(): string;
+
+export function vocabulary(): any;