@almadar/extensions 1.0.15 → 2.0.0

package/LICENSE

@@ -1,72 +1,21 @@
-Business Source License 1.1
-
-Parameters
-
-Licensor:             Almadar FZE
-Licensed Work:        KFlow Builder / Almadar
-                      The Licensed Work is (c) 2025-2026 Almadar FZE.
-Additional Use Grant: You may make production use of the Licensed Work for
-                      non-commercial purposes and for internal evaluation.
-                      Production use for commercial purposes requires a
-                      commercial license from the Licensor.
-Change Date:          2030-02-01
-Change License:       Apache License, Version 2.0
-
-Terms
-
-The Licensor hereby grants you the right to copy, modify, create derivative
-works, redistribute, and make non-production use of the Licensed Work. The
-Licensor may make an Additional Use Grant, above, permitting limited
-production use.
-
-Effective on the Change Date, or the fourth anniversary of the first publicly
-available distribution of a specific version of the Licensed Work under this
-License, whichever comes first, the Licensor hereby grants you rights under
-the terms of the Change License, and the rights granted in the paragraph
-above terminate.
-
-If your use of the Licensed Work does not comply with the requirements
-currently in effect as described in this License, you must purchase a
-commercial license from the Licensor, its affiliated entities, or authorized
-resellers, or you must refrain from using the Licensed Work.
-
-All copies of the original and modified Licensed Work, and derivative works
-of the Licensed Work, are subject to this License. This License applies
-separately for each version of the Licensed Work and the Change Date may vary
-for each version of the Licensed Work released by Licensor.
-
-You must conspicuously display this License on each original or modified copy
-of the Licensed Work. If you receive the Licensed Work in original or
-modified form from a third party, the terms and conditions set forth in this
-License apply to your use of that work.
-
-Any use of the Licensed Work in violation of this License will automatically
-terminate your rights under this License for the current and all other
-versions of the Licensed Work.
-
-This License does not grant you any right in any trademark or logo of
-Licensor or its affiliates (provided that you may use a trademark or logo of
-Licensor as expressly required by this License).
-
-TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
-AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
-EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
-TITLE.
-
----
-
-License text copyright (c) 2017 MariaDB Corporation Ab, All Rights Reserved.
-"Business Source License" is a trademark of MariaDB Corporation Ab.
-
-ADDITIONAL TERMS:
-
-Documentation (builder/packages/website/docs/) is licensed under CC BY 4.0.
-
-TRADEMARKS:
-
-"Orbital", "KFlow", "Almadar", and the Almadar logo are trademarks of
-Almadar FZE. You may not use these trademarks without prior written
-permission from Almadar FZE.
-
-For licensing inquiries: licensing@almadar.io
+MIT License
+
+Copyright (c) 2026 Almadar Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,25 @@
+# @almadar/extensions
+
+> Editor extension utilities for .orb files — virtual document wrapper and S-expression grammar generator
+
+Part of the [Almadar](https://github.com/almadar-io/almadar) platform.
+
+## Installation
+
+```bash
+npm install @almadar/extensions
+```
+
+## Usage
+
+```typescript
+import { /* ... */ } from '@almadar/extensions';
+```
+
+## API
+
+<!-- Document public exports here -->
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@almadar/extensions",
-  "version": "1.0.15",
+  "version": "2.0.0",
   "description": "Editor extension utilities for .orb files — virtual document wrapper and S-expression grammar generator",
   "type": "module",
   "main": "./dist/index.js",
@@ -19,17 +19,18 @@
     "access": "public"
   },
   "dependencies": {
-    "@almadar/core": "1.0.17",
-    "@almadar/operators": "1.0.14"
+    "@almadar/core": ">=2.0.0",
+    "@almadar/operators": ">=2.0.0"
   },
   "devDependencies": {
     "tsup": "^8.0.0",
-    "typescript": "^5.4.0"
+    "typescript": "^5.4.0",
+    "tsx": "^4.0.0"
   },
   "repository": {
     "type": "git",
     "url": "https://github.com/almadar-io/almadar.git",
-    "directory": "packages/almadar-extensions"
+    "directory": "docs/packages/extensions"
   },
   "license": "MIT",
   "keywords": [
@@ -40,6 +41,7 @@
     "vscode",
     "zed"
   ],
+  "homepage": "https://github.com/almadar-io/almadar#readme",
   "scripts": {
     "build": "tsup && pnpm run generate-grammar && pnpm run build:editors",
     "build:core": "tsup && pnpm run generate-grammar",

package/dist/index.d.ts

@@ -1,213 +0,0 @@
-/**
- * Virtual Document — The TypeScript Wrapper Trick
- *
- * Wraps .orb JSON content inside a TypeScript file that imports
- * OrbitalSchema from @almadar/core. This lets the TypeScript
- * language server validate the entire .orb structure for free.
- *
- * @packageDocumentation
- */
-/**
- * Number of lines the prefix adds before .orb content begins.
- * Used to offset diagnostics back to original .orb line numbers.
- *
- * The prefix is exactly 2 lines:
- *   Line 1: import type { OrbitalSchema } from '@almadar/core';
- *   Line 2: const _orbital = ... (the .orb content starts on THIS line)
- *
- * So .orb line 1 corresponds to virtual .ts line 2.
- */
-declare const WRAPPER_LINE_OFFSET = 1;
-/**
- * Number of characters on the prefix line before .orb content begins.
- * `const _orbital = ` is 18 characters.
- */
-declare const WRAPPER_COL_OFFSET = 18;
-/**
- * Wrap raw .orb JSON content into a virtual TypeScript file.
- *
- * @param orbContent - The raw JSON string from the .orb file
- * @returns The complete TypeScript source that tsserver can validate
- *
- * @example
- * ```ts
- * const orbJson = fs.readFileSync('app.orb', 'utf-8');
- * const tsContent = wrapOrbContent(orbJson);
- * // tsContent is now a valid .ts file that TypeScript can check
- * ```
- */
-declare function wrapOrbContent(orbContent: string): string;
-/**
- * Extract the original .orb content from a wrapped virtual TypeScript file.
- *
- * @param virtualContent - The virtual .ts file content
- * @returns The original .orb JSON string, or null if not a valid wrapper
- */
-declare function unwrapOrbContent(virtualContent: string): string | null;
-/**
- * Generate the virtual .ts filename for a given .orb file path.
- *
- * @param orbFilePath - Absolute path to the .orb file
- * @returns The virtual .ts file path (same directory, `.orb.ts` extension)
- *
- * @example
- * ```ts
- * getVirtualPath('/projects/app.orb')
- * // → '/projects/app.orb.ts'
- * ```
- */
-declare function getVirtualPath(orbFilePath: string): string;
-
-/**
- * Diagnostic Mapper
- *
- * Maps TypeScript diagnostics from the virtual .ts file back to
- * the original .orb file positions, adjusting for the wrapper prefix.
- *
- * @packageDocumentation
- */
-/**
- * A position in a text document (0-indexed line and character).
- */
-interface Position {
-    /** 0-indexed line number */
-    line: number;
-    /** 0-indexed character offset within the line */
-    character: number;
-}
-/**
- * A range in a text document.
- */
-interface Range {
-    start: Position;
-    end: Position;
-}
-/**
- * Severity levels matching both VSCode and Zed conventions.
- */
-type DiagnosticSeverity = 'error' | 'warning' | 'info' | 'hint';
-/**
- * An editor-agnostic diagnostic — the universal unit that
- * VSCode and Zed extensions translate into their native format.
- */
-interface OrbDiagnostic {
-    /** Human-readable error message */
-    message: string;
-    /** Location in the .orb file (already adjusted from virtual .ts) */
-    range: Range;
-    /** Severity level */
-    severity: DiagnosticSeverity;
-    /** TypeScript error code (e.g. 2322, 2353) for filtering */
-    code?: number;
-    /** Source identifier */
-    source: 'almadar-ts';
-}
-/**
- * Raw TypeScript diagnostic (minimal shape matching ts.Diagnostic).
- * Extensions should map their TS server output to this shape.
- */
-interface TsDiagnostic {
-    /** 0-indexed line in the virtual .ts file */
-    line: number;
-    /** 0-indexed character in the virtual .ts file */
-    character: number;
-    /** End line (optional, defaults to same as line) */
-    endLine?: number;
-    /** End character (optional) */
-    endCharacter?: number;
-    /** Error message text */
-    messageText: string;
-    /** TS error code */
-    code?: number;
-    /** 1 = error, 2 = warning, 3 = info, 4 = hint */
-    category?: number;
-}
-/**
- * Map a virtual .ts file position back to the original .orb position.
- *
- * @param virtualLine - 0-indexed line in the virtual .ts file
- * @param virtualChar - 0-indexed character in the virtual .ts file
- * @returns Adjusted position in the .orb file
- */
-declare function mapPositionToOrb(virtualLine: number, virtualChar: number): Position;
-/**
- * Map a single TypeScript diagnostic to an OrbDiagnostic.
- *
- * @param tsDiag - The raw TypeScript diagnostic
- * @returns An editor-agnostic diagnostic with adjusted positions
- */
-declare function mapDiagnostic(tsDiag: TsDiagnostic): OrbDiagnostic;
-/**
- * Map an array of TypeScript diagnostics to OrbDiagnostics.
- * Filters out diagnostics that fall within the wrapper prefix.
- *
- * @param diagnostics - Array of raw TypeScript diagnostics
- * @returns Array of editor-agnostic diagnostics
- */
-declare function mapDiagnostics(diagnostics: TsDiagnostic[]): OrbDiagnostic[];
-
-/**
- * S-Expression Grammar Generator
- *
- * Generates a TextMate injection grammar for S-expression syntax
- * highlighting inside .orb files. The grammar is derived from
- * @almadar/operators — the single source of truth for all operator names.
- *
- * This means new operators automatically get highlighting when
- * the package is rebuilt. No manual grammar maintenance.
- *
- * @packageDocumentation
- */
-/**
- * TextMate grammar rule
- */
-interface TmRule {
-    name: string;
-    match: string;
-}
-/**
- * TextMate injection grammar structure
- */
-interface TmInjectionGrammar {
-    scopeName: string;
-    injectionSelector: string;
-    patterns: TmRule[];
-}
-/**
- * Generate a TextMate injection grammar for S-expression highlighting.
- *
- * The grammar injects into `.orb` files (JSON scope) and highlights:
- * - **Operators** by category (arithmetic, effect, control, etc.)
- * - **Bindings** (`@entity.field`, `@payload.value`)
- * - **Events** (UPPER_CASE_NAMES)
- *
- * @returns A complete TextMate injection grammar object
- *
- * @example
- * ```ts
- * import { generateSExprGrammar } from '@almadar/extensions';
- * import { writeFileSync } from 'fs';
- *
- * const grammar = generateSExprGrammar();
- * writeFileSync('sexpr.injection.json', JSON.stringify(grammar, null, 2));
- * ```
- */
-declare function generateSExprGrammar(): TmInjectionGrammar;
-/**
- * Serialize the grammar to a formatted JSON string.
- * Ready to be written to `sexpr.injection.json`.
- */
-declare function generateSExprGrammarJson(): string;
-/**
- * Get a flat list of all operator names from the registry.
- * Useful for editor extensions that need the operator list without
- * importing @almadar/operators directly.
- */
-declare function getOperatorNames(): string[];
-/**
- * Get operators grouped by category.
- * Useful for autocomplete that groups suggestions by category.
- */
-declare function getOperatorsByCategory(): Record<string, string[]>;
-
-export { type DiagnosticSeverity, type OrbDiagnostic, type Position, type Range, type TmInjectionGrammar, type TsDiagnostic, WRAPPER_COL_OFFSET, WRAPPER_LINE_OFFSET, generateSExprGrammar, generateSExprGrammarJson, getOperatorNames, getOperatorsByCategory, getVirtualPath, mapDiagnostic, mapDiagnostics, mapPositionToOrb, unwrapOrbContent, wrapOrbContent };