@neocompose/cli 0.88.0 → 0.89.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neocompose/cli",
-  "version": "0.88.0",
+  "version": "0.89.1",
   "description": "Neo Compose native project-source CLI with bidirectional sync.",
   "license": "MIT",
   "type": "module",

package/skills/neocompose-cli/SKILL.md

@@ -9,7 +9,7 @@ description: >-
   `@neocompose/cli` or `node cli/bin/neo.mjs` in the neo-compose repository.
 ---
 
-<!-- reviewed-through-cli: 0.88.0 -->
+<!-- reviewed-through-cli: 0.89.1 -->
 
 # Neo Compose CLI
 

package/skills/neocompose-cli/references/cli-development.md

@@ -109,7 +109,7 @@ The marker near the top of `SKILL.md` must exactly match the package version,
 and this quoted copy is checked too:
 
 ```html
-<!-- reviewed-through-cli: 0.88.0 -->
+<!-- reviewed-through-cli: 0.89.1 -->
 ```
 
 Keep this skill on current behavior. Upgrade steps, rollout prerequisites,

package/skills/neocompose-cli/references/declarations/extensions.md

@@ -0,0 +1,46 @@
+# Extensions
+
+Declare functions and computed properties in top-level extension blocks. Each
+member has its own `@id`; the block has no identity. Blocks can share any
+`.neo` definition file. Pull retains member file placement and otherwise uses
+`Extensions/<Receiver>Extensions.neo`.
+
+```neo
+extension Person {
+  @id("person-full-name")
+  public string FullName => $"{this.FirstName} {this.LastName}";
+}
+
+extension List<Item> {
+  @id("item-best")
+  Item? Best() => this.OrderByDescending((i) => i.Quality).FirstOrDefault();
+}
+
+extension<T> List<T> {
+  @id("list-first-value")
+  T? FirstValue => this.FirstOrDefault();
+}
+```
+
+Always use `this` to access the extended instance. Interface receivers are
+supported and use the ordinary writable-member rules. Extensions add no
+stored fields, constructors, inheritance, or operators. They are visible
+project-wide. Applicable declared members take priority over extensions;
+applicable extensions take priority over built-ins. Ambiguous candidates are
+errors. Receiver type parameters must appear in the receiver and cannot have
+defaults. Functions may also declare their own type parameters.
+
+Computed properties support getters and explicit `set(Type value)` bodies.
+Static extensions have no `this` and are called through the receiver type.
+Extensions cannot be listener or spy/mock targets or use builder bodies.
+
+Use `neo script check --all` to check local declarations. For direct checks,
+select an extension with `--member <stable-member-id>`. Do not pass `--this`.
+Direct evaluation accepts `--this-value <valueId>` only for a closed class or
+interface receiver. Static extensions reject `--this-value`. Evaluate scalar,
+collection, receiver-generic, and explicitly generic calls in an ordinary
+`neo script eval --source '...'` expression. Evaluate setters through ordinary
+assignments in source.
+
+Both evaluators support extension members independently of the generated C#
+version. See [Unity export](../sync/unity-export.md) for wrapper availability.

package/skills/neocompose-cli/references/neoscript/collections.md

@@ -96,3 +96,43 @@ Put type arguments on the call, never the qualifier: `List<int>.Repeat` is an
 error and bare `List` is not a value. `count` must be an `int`; a negative
 count throws at runtime. The value and then the count evaluate exactly once,
 so a reference-typed value repeats the same reference.
+
+## Sequences and generators
+
+Built-in collections implement `IEnumerable<T>` for their exact value type.
+A dictionary enumerates its values. `GetEnumerator()` creates an independent
+`IEnumerator<T>` with `MoveNext()`, `Current`, and `Dispose()`. Built-in cursors
+snapshot membership when acquired. `Current` requires a successful `MoveNext`.
+
+```neo
+public IEnumerable<int> Neighbors(int cell) {
+    yield return cell - 1;
+    yield return cell + 1;
+}
+
+public List<int> Collect(IEnumerable<int> values) => values;
+public IEnumerator<int> Cursor(List<int> values) => values;
+```
+
+Typed assignments, parameters, and returns acquire a cursor or collect a list
+implicitly. Collecting a cursor consumes its remaining values, excluding its
+current value, and disposes it. Element types must match exactly. A collection
+itself does not own an iteration position.
+
+A generator returns non-nullable `IEnumerable<T>` or `IEnumerator<T>`. Arguments
+are evaluated when called; its body starts on the first `MoveNext`. Use
+`yield return value` and `yield break`. `foreach` disposes its cursor on normal
+completion, `break`, `return`, and catchable errors. A suspended generator runs
+entered `finally` blocks when disposed. Yields cannot appear in catch/finally
+blocks or a try block with catches; generators cannot invoke async functions.
+
+`start..end` is an ascending, upper-exclusive int sequence. Reversed bounds are
+empty. `foreach (var i in 0..count)` uses a counted loop without allocating a
+cursor. Ranges require safe integer bounds.
+
+`IEnumerator<T>` and derived cursor interfaces cannot occur in stored member
+shapes, including Session storage, nested collection entries, or tuples. Use
+computed properties and callable signatures for cursors; store `List<T>` data
+explicitly. Stored enumerable interface members accept authored class rows.
+Runtime sequences are shown as unenumerated and are not expanded for previews.
+`ToSet()` rejects enumerable/cursor interface elements.

package/skills/neocompose-cli/references/neoscript/neoscript.md

@@ -102,6 +102,7 @@ Read only the leaf the task needs:
 Related branches:
 
 - [References](../values/references.md): `Reference<T>` handles and slots.
+- [Extensions](../declarations/extensions.md): typed receiver functions and computed properties.
 - [Overloads](../declarations/overloads.md): declaring and calling overloads.
 - [Constructors](../declarations/constructors.md) and
   [initializers](../declarations/initializers.md): construction order and

package/skills/neocompose-cli/references/sync/unity-export.md

@@ -45,3 +45,19 @@ an export go into the next batch. It never pulls or pushes.
 
 Pull, push, branch, merge, resolve, init, and export take turns through
 `.neo/workspace.lock`; a lock whose process died is taken over.
+
+## C# target and extension wrappers
+
+Set `codegen.csharpVersion` in `neo.json` to a numeric language version such as
+`"14"`. `latest` and `preview` are rejected. Without an override, export uses
+the supported Unity compiler mapping or the SDK's C# 9 baseline. It reads
+`codegen.unityVersion` first, then the linked Unity project's
+`ProjectSettings/ProjectVersion.txt`. `neo doctor` reports the effective target
+and its source. An unrecognized Unity version produces a baseline warning.
+
+Closed instance extension functions can generate classic C# extension methods.
+Interface receivers, open receiver types, static extensions, and computed
+extension properties require C# 14. Export omits an unavailable wrapper and
+reports its member ID, receiver, and missing capability. It keeps the member
+available to the NeoScript evaluators and SDK direct invocation API. Changing
+the target regenerates wrappers and removes obsolete owned wrapper files.

package/skills/neocompose-cli/references/values/references.md

@@ -26,7 +26,8 @@ public Reference<int> TrackedStat;          // another member's int
 
 - `Reference<T>` also works as a parameter, collection element, dictionary
   value, and unbound generic argument (`Box<Reference<int>>`), and keeps that
-  storage type through push and pull. Use `Set<T>` parameters for several
+  storage type through push and pull, including nested generic collections
+  and named tuples. Use `Set<T>` parameters for several
   selections.
 - `@settings(collection: Owner.Member)` binds a class reference to one
   collection. Unbound references select any stored row of `T` or a subclass,
@@ -47,20 +48,31 @@ public Reference<int> TrackedStat;          // another member's int
 
 ```neo
 public Reference<Item> StarterSeed = root.Assets.Items.Index.Slug["seed.carrot"]!;
-public Reference<int> Gold = Reference(root.Player.Gold);
-public Reference<string> Greeting = Reference(root.Npcs.Index.Slug["mira"]!.Greeting);
-public Reference<NeoVariant<Tree>> Look = Reference(root.Garden.Felled);
+public Reference<int> Gold = root.Player.Gold;
+public Reference<string> Greeting = root.Npcs.Index.Slug["mira"]!.Greeting;
+public Reference<NeoVariant<Tree>> Look = root.Garden.Felled;
 ```
 
 - An unbound handle default may name its row by a unique index: a `root`
   path to a List, `.Index.<Name>`, and a string literal key. Other shapes are
   initializer code.
-- Slot defaults wrap a member path in `Reference()`. A plain value is not a
-  default, and `this` doesn't exist yet. A `NeoVariant<T>` member's own
-  default stays the bare variant path.
+- Slot defaults accept compatible stored member paths directly; `Reference()`
+  remains valid. Literals and computed values cannot supply a slot, and `this`
+  does not exist yet. A `NeoVariant<T>` member's own default stays the bare
+  variant path.
 - List and dictionary defaults may hold slot references, nested too:
-  `List<Reference<int>> Counts = [Reference(root.Save.Bits)]`. Each instance
+  `List<Reference<int>> Counts = [root.Save.Bits]`. Each instance
   owns the collection; entries target the original slots.
+- `Set<Reference<T>>` selections can mix bare paths and explicit references.
+  Computed selections deduplicate by target identity, not by current value.
+  A literal selection of fixed targets must not repeat the same target.
+- A bare path to an existing reference copies its current target when the
+  object is constructed. Later rebinding of that source reference does not
+  rebind the copy.
+- A nullable target still needs a stored row. Pin an otherwise absent
+  nullable member in its owner's initializer, for example
+  `new() { Maybe = null }`, before referencing it. A declaration default alone
+  does not create that row.
 
 ## Source forms
 
@@ -89,11 +101,18 @@ Reference<NeoDialogue>(id: "capitol-dialogue-id")
 
 ## Runtime semantics
 
-`Reference(place)` forms a reference to a stored member: `this.Gold`,
-`root.Player.Gold`, `item.Count`. Locals, parameters, list or dictionary
-elements, vector components, getters, query results, and new values have no
-row. When `Selected` is `Reference<Item>`, `Reference(this.Selected)` is
-`Reference<Reference<Item>>`. Access checks apply where it is formed.
+When executable code expects `Reference<T>`, pass a compatible stored member
+such as `this.Gold`, `root.Player.Gold`, or `item.Count` directly. This works
+for constructor and function arguments, returns, typed locals, object
+initializers, and collection entries. The reference keeps following that
+slot when its value changes. `Reference(place)` remains valid when an
+explicit reference is needed.
+
+Locals, parameters, list or dictionary elements, vector components, getters,
+query results, and new scalar values have no row. A narrowed nullable member
+still names its declared storage type. When `Selected` is `Reference<Item>`,
+`Reference(this.Selected)` is `Reference<Reference<Item>>`. Access checks
+apply where the reference is formed.
 
 ```neo
 this.A = 5;                       // writes 5 into A's target
@@ -106,8 +125,8 @@ this.A += 1;                      // reads A's target, writes it back
 - Assigning a same-typed reference rebinds; anything else writes through.
   `this.A = c ? first : second` rebinds when both arms are references, writes
   when both are scalars, and reads the chosen target when mixed.
-- A plain value never becomes a reference: passing `3` to a `Reference<int>`
-  parameter is an error.
+- A value without a stored slot never becomes a reference: passing `3` to a
+  `Reference<int>` parameter is an error.
 - Constructors may initialize their own reference fields but can't write
   through external targets.
 - `==` compares handles by identity and slots by value. Collections of
@@ -138,6 +157,10 @@ Lookup assignment still needs an existing backing row.
 (`root.Assets.Quests.Daily` or `Reference(root.Assets.Quests.Daily)`) and
 follow the same rules. The path may cross construction defaults and
 declarations from the same push; no preliminary push or manual ID is needed.
+Pull emits bare paths in `collectionValue` settings when the target is reachable
+from a root; otherwise it retains `Reference(id: "...")`. Lookup variant folder
+bindings and `.Bind(root.Assets.Items.Index.Slug["seed.carrot"]!)` use the same
+implicit reference conversion.
 Invalid reference settings are errors, never silently dropped.
 
 ## Init-built objects
@@ -145,7 +168,7 @@ Invalid reference settings are errors, never silently dropped.
 An object `Root.neo` writes is init-built when its class has an `init` block.
 A declaration binding may name a member inside it, and push stores that
 member's row. A reference captured by `init` or a constructor
-(`new Rule(Reference(this.Weather))`) keeps its target's row. Status refuses a
+(`new Rule(this.Weather)`) keeps its target's row. Status refuses a
 value row's reference to a member of an init-built object (bind it from a
 declaration instead) and a binding to a class or list that an `init` block
 builds.

package/skills/neocompose-cli/references/world/variants.md

@@ -86,7 +86,7 @@ class root.
 NeoLookupVariantFolder<ExampleObject, NeoSortingLayer> Root = new(
   path: "",
   collection: Assets.SortingLayers,
-  collectionValue: Reference(root.Assets.SortingLayers),
+  collectionValue: root.Assets.SortingLayers,
 );
 
 @id("736dddf8-2881-47e1-a1d3-55fb65ea9f2a")
@@ -97,13 +97,14 @@ NeoLookupVariant<ExampleObject, NeoSortingLayer> Layered = new(
 ```
 
 - `collection` names the eligible list member; `collectionValue` the stored
-  list whose rows it enumerates. Prefer the `Reference(root...)` form pull
+  list whose rows it enumerates. Prefer the bare `root...` path pull
   emits.
 - Lookup `initialize` receives the row; lookup `apply` receives the object,
   then the row.
 - A `NeoLookupVariant<TObject, TValue>` member holds an unbound handle. A
   plain `NeoVariant<TObject>` member may pick one row with
-  `.Bind(Reference(...))`; never bind a row to the lookup-handle type.
+  `.Bind(root.Assets.Items.Index.Slug["seed.carrot"]!)`; explicit
+  `Reference(...)` remains valid. Never bind a row to the lookup-handle type.
 
 ## Type restrictions