@maias/core 0.2.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,5 @@
+MAIAS — Mobile App Information Architecture Schema
+Copyright 2026 Mark Chitty
+
+This product includes software developed as part of the MAIAS project
+(https://github.com/MAIAS-project/maias).

package/README.md

@@ -0,0 +1,46 @@
+# @maias/core — the MAIAS core library
+
+The single TypeScript implementation of everything MAIAS: parse → typed object model → serialise with round-trip fidelity, validation, graph utilities, safe edits, and the canonical formatter. The [CLI](../cli/README.md), the [MCP server](../mcp/README.md), and the MAIAS Browser are all thin wrappers over this package — one implementation, so the three surfaces can never disagree about what a valid document is.
+
+**Environment constraint that shaped it:** the same code runs in Node (CLI, MCP), the browser, and React Native/Hermes. Hermes forbids runtime codegen, so schema validation uses an interpreting validator (`@cfworker/json-schema`, not Ajv — decision D11), and the JSON Schema is embedded at build time (`maias-schema.gen.ts`): a published `@maias/core` validates with **no network and no external files, ever**.
+
+## Quick taste
+
+```ts
+import { parse, validate, editElements, format } from '@maias/core';
+
+const { parsed } = parse(readFileSync('my-app.maias.yaml', 'utf8'));
+
+// Safe element edit — atomic batch, refuses dangling targets & stale indices
+const result = editElements(parsed!, 'home', [
+  { op: 'insert', index: 2, element: { label: 'Send feedback', type: 'link', target: 'feedback' } },
+]);
+if (!result.ok) throw new Error(result.reason);
+
+const output = format(parsed!);          // canonical form, comments intact
+console.log(validate(output).valid);     // re-check before writing
+```
+
+## Module surface
+
+| Module | Exports | Job |
+|---|---|---|
+| `parse` | `parse`, `ParsedDocument` | YAML/JSON text → typed model **plus** the underlying CST (`yaml` package, D10). Comments and source ranges survive; `position(path)` maps any document path to line/col. |
+| `model` | `MaiasDocument`, `Screen`, `Element`, `Flow`, … | The spec, 1:1, as TypeScript types. `x_` extension fields are typed on every object. |
+| `validate` | `validate`, `lint`, `schemaValidate` | Two layers: embedded JSON Schema, then semantic lint (dangling targets `MAIAS-E003`, orphans, registry membership, duplicates, path collisions — E001–E009 / W001–W008), all as `Diagnostic { code, severity, message, path, line, col }`. |
+| `graph` | `screenIndex`, `reachableScreens`, `orphanScreens`, `whatLinksHere`, `outboundRefs` | The document as a navigation graph. |
+| `edit` | `renameScreen`, `addScreen`, `removeScreen`, `editElements` | Safe mutations through the CST: renames cascade to every reference; removal refuses to leave dangling targets unless `cascade`; `editElements` applies an atomic insert/update/remove/move batch with `expect` guards (R6.5, D20). Every operation returns `EditResult { ok, reason?, changes }` and, on refusal, leaves the document untouched. |
+| `fmt` | `format`, `canonicalize` | Canonical form (spec §11): fixed key order, derived screen ordering, omit-empty. Idempotent; comments move with their nodes. |
+
+## Guarantees
+
+- **Round-trip fidelity (D10):** parse → edit → serialise keeps every comment and leaves untouched lines byte-identical — machine edits diff as exactly the change.
+- **Safe by default:** every edit operation validates its inputs first and refuses with an actionable `reason` rather than writing a broken document.
+- **One validation everywhere (D11):** CLI, MCP, and the in-app browser all call this `validate()`; a document valid in one place is valid in all.
+
+## Development
+
+```sh
+npm run build -w @maias/core     # regenerates the embedded schema, then compiles
+npx vitest run packages/core    # round-trip, lint fixtures, fmt idempotence, edit ops
+```

package/dist/diagnostics.d.ts

@@ -0,0 +1,42 @@
+import type { DocPath } from './model.js';
+export type Severity = 'error' | 'warning';
+/**
+ * A single validation/lint finding. `line`/`col` are 1-based and present when
+ * the source text position of `path` could be resolved (YAML and JSON input).
+ * The shape is the stable contract of `maias validate --json`.
+ */
+export interface Diagnostic {
+    /** Stable rule code: MAIAS-S### (schema), MAIAS-E### (lint error), MAIAS-W### (lint warning), MAIAS-P### (parse). */
+    code: string;
+    severity: Severity;
+    message: string;
+    /** JSON path to the offending node, e.g. ['screens', 3, 'path']. */
+    path: DocPath;
+    line?: number;
+    col?: number;
+}
+export declare const CODES: {
+    readonly PARSE: "MAIAS-P001";
+    readonly SCHEMA: "MAIAS-S001";
+    readonly DUPLICATE_ID: "MAIAS-E001";
+    readonly DUPLICATE_PATH: "MAIAS-E002";
+    readonly DANGLING_TARGET: "MAIAS-E003";
+    readonly FLOW_ENTRY: "MAIAS-E004";
+    readonly FLOW_UNKNOWN_SCREEN: "MAIAS-E005";
+    readonly UNREGISTERED_SCREEN: "MAIAS-E006";
+    readonly DOUBLY_REGISTERED_SCREEN: "MAIAS-E007";
+    readonly REGISTRY_UNKNOWN_SCREEN: "MAIAS-E008";
+    readonly DUPLICATE_FLOW: "MAIAS-E009";
+    readonly MISSING_DESCRIPTION: "MAIAS-W001";
+    readonly UNREACHABLE_SCREEN: "MAIAS-W002";
+    readonly ORPHAN_SCREEN: "MAIAS-W003";
+    readonly SELF_TARGET: "MAIAS-W004";
+    readonly UNKNOWN_ELEMENT_TYPE: "MAIAS-W005";
+    readonly DEEP_LINK_NO_SCHEME: "MAIAS-W006";
+    readonly PRIMARY_NAV_MISUSE: "MAIAS-W007";
+    readonly SHEET_PRESENTATION: "MAIAS-W008";
+    readonly VERSION_FEATURE_MISMATCH: "MAIAS-W009";
+};
+export declare function hasErrors(diagnostics: Diagnostic[]): boolean;
+/** Stable ordering for output: by line, then col, then code. */
+export declare function sortDiagnostics(diagnostics: Diagnostic[]): Diagnostic[];

package/dist/diagnostics.js

@@ -0,0 +1,29 @@
+export const CODES = {
+    PARSE: 'MAIAS-P001',
+    SCHEMA: 'MAIAS-S001',
+    DUPLICATE_ID: 'MAIAS-E001',
+    DUPLICATE_PATH: 'MAIAS-E002',
+    DANGLING_TARGET: 'MAIAS-E003',
+    FLOW_ENTRY: 'MAIAS-E004',
+    FLOW_UNKNOWN_SCREEN: 'MAIAS-E005',
+    UNREGISTERED_SCREEN: 'MAIAS-E006',
+    DOUBLY_REGISTERED_SCREEN: 'MAIAS-E007',
+    REGISTRY_UNKNOWN_SCREEN: 'MAIAS-E008',
+    DUPLICATE_FLOW: 'MAIAS-E009',
+    MISSING_DESCRIPTION: 'MAIAS-W001',
+    UNREACHABLE_SCREEN: 'MAIAS-W002',
+    ORPHAN_SCREEN: 'MAIAS-W003',
+    SELF_TARGET: 'MAIAS-W004',
+    UNKNOWN_ELEMENT_TYPE: 'MAIAS-W005',
+    DEEP_LINK_NO_SCHEME: 'MAIAS-W006',
+    PRIMARY_NAV_MISUSE: 'MAIAS-W007',
+    SHEET_PRESENTATION: 'MAIAS-W008',
+    VERSION_FEATURE_MISMATCH: 'MAIAS-W009',
+};
+export function hasErrors(diagnostics) {
+    return diagnostics.some((d) => d.severity === 'error');
+}
+/** Stable ordering for output: by line, then col, then code. */
+export function sortDiagnostics(diagnostics) {
+    return [...diagnostics].sort((a, b) => (a.line ?? 0) - (b.line ?? 0) || (a.col ?? 0) - (b.col ?? 0) || a.code.localeCompare(b.code));
+}

package/dist/edit.d.ts

@@ -0,0 +1,84 @@
+import type { Element, Screen } from './model.js';
+import { type InboundRef } from './graph.js';
+import type { ParsedDocument } from './parse.js';
+export interface EditResult {
+    ok: boolean;
+    /** Human-readable reason when ok is false. */
+    reason?: string;
+    /** Number of scalar/node updates applied. */
+    changes: number;
+}
+/**
+ * Rename a screen, cascading to every reference: flows (entry_screen, screens),
+ * the navigation registry, and all targets (navigation items, elements, state
+ * elements). Edits go through the YAML document so comments and unrelated
+ * formatting are untouched — the diff is exactly the renamed references.
+ */
+export declare function renameScreen(parsed: ParsedDocument, oldId: string, newId: string): EditResult;
+export interface AddScreenOptions {
+    /** Which registry list the screen joins. Default: secondary. */
+    registry?: 'primary' | 'secondary';
+    /** Flow to append the screen to (added to its `screens` list). */
+    flow?: string;
+}
+/** Add a screen and register it. The screen object should follow canonical key order (use fmt afterwards to be sure). */
+export declare function addScreen(parsed: ParsedDocument, screen: Screen, opts?: AddScreenOptions): EditResult;
+export interface RemoveScreenOptions {
+    /**
+     * When true, inbound references are removed too (navigation items pointing at
+     * the screen are deleted; elements keep their content but lose their target).
+     * When false (default), removal is refused if inbound references exist.
+     */
+    cascade?: boolean;
+}
+export interface RemoveScreenResult extends EditResult {
+    /** References that pointed at the screen (removed when cascade, blocking otherwise). */
+    inboundRefs: InboundRef[];
+}
+/** Remove a screen plus its registry and flow entries. Safe by default: refuses to leave dangling targets. */
+export declare function removeScreen(parsed: ParsedDocument, id: string, opts?: RemoveScreenOptions): RemoveScreenResult;
+export type ElementStateKey = 'empty' | 'loading' | 'error';
+/** Stale-index guard: when given, the op is refused unless the addressed element matches. */
+export interface ElementGuard {
+    type?: string;
+    label?: string;
+}
+/**
+ * Patch for an `update` op: keys present are written, keys absent are left
+ * untouched (so `x_` extension fields survive), an explicit `null` deletes
+ * the key. `type` cannot be deleted.
+ */
+export type ElementPatch = Record<string, unknown>;
+export type ElementOp = {
+    op: 'insert';
+    state?: ElementStateKey;
+    index: number;
+    element: Element;
+} | {
+    op: 'update';
+    state?: ElementStateKey;
+    index: number;
+    set: ElementPatch;
+    expect?: ElementGuard;
+} | {
+    op: 'remove';
+    state?: ElementStateKey;
+    index: number;
+    expect?: ElementGuard;
+} | {
+    op: 'move';
+    state?: ElementStateKey;
+    index: number;
+    to: number;
+    expect?: ElementGuard;
+};
+/**
+ * Edit a screen's `elements` list (or a declared state's list) in place:
+ * insert, update, remove, move. The batch is atomic — every op is checked
+ * against a simulated copy first, so a failing op leaves the document
+ * untouched. Ops apply sequentially: each op's `index` addresses the list as
+ * left by the previous ops. Safe by default: an op that would introduce a
+ * `target` not matching any screen is refused, as is editing a state the
+ * screen does not declare (declaring states is a screen-shape decision).
+ */
+export declare function editElements(parsed: ParsedDocument, screenId: string, ops: ElementOp[]): EditResult;