@neocompose/cli 0.23.2 → 0.24.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neocompose/cli",
-  "version": "0.23.2",
+  "version": "0.24.1",
   "description": "Neo Compose native project-source CLI with bidirectional sync.",
   "license": "MIT",
   "type": "module",
@@ -35,10 +35,17 @@
   },
   "dependencies": {
     "@inquirer/prompts": "^8.5.2",
-    "convex": "^1.40.0"
+    "convex": "^1.40.0",
+    "ignore": "^7.0.6"
   },
   "devDependencies": {
     "esbuild": "^0.28.1",
-    "prettier": "^3.9.5"
+    "prettier": "^3.9.5",
+    "uuid": "^14.0.1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ryanbliss/neo-compose.git",
+    "directory": "cli"
   }
 }

package/skills/neocompose-cli/SKILL.md

@@ -2,14 +2,14 @@
 name: neocompose-cli
 description: >-
   Edit, validate, and synchronize Neo Compose format-4 projects with the `neo`
-  CLI. Use when working in a `neo/` checkout or with `.neo`/`.neoflow` source:
+  CLI. Use when working in a `neo/` checkout or with `.neo`/`.neoflow`/`.spec.neo` source:
   schema declarations, constructors, values and references, world objects and
   animation, dialogue, NeoScript, localization, migrations, managed image or
   audio files, branches and releases, or batch repair. Run `neo` from
   `@neocompose/cli` or `node cli/bin/neo.mjs` in the neo-compose repository.
 ---
 
-<!-- reviewed-through-cli: 0.23.2 -->
+<!-- reviewed-through-cli: 0.24.1 -->
 
 # Neo Compose CLI
 
@@ -24,11 +24,12 @@ Those are not part of format 4.
 ## Follow the safe workflow
 
 1. Run `neo pull` before editing. Pull again before pushing if time has passed.
-2. Edit tracked `.neo`, `.neoflow`, and managed binary files only. Never edit
+2. Edit tracked `.neo`, `.neoflow`, `.spec.neo`, and managed binary files only. Never edit
    `.neo/state.json`, analysis caches, or `.neo/conflicts` as source.
 3. Run `neo status` and `neo diff`. Review every change, including changes that
    existed before the task began.
-4. Run `neo dialogue dryrun <ref>` after dialogue changes.
+4. Run `neo test` after NeoScript changes and `neo dialogue dryrun <ref>` after
+   dialogue changes.
 5. Run `neo push --dry-run` before every real push. It performs the full local
    source emission, ID-assignment, transport-shape, hash, and repeat-verification path,
    then rehearses the server's preparation phase — schema-commit
@@ -49,8 +50,12 @@ opaque JSON or guessed syntax.
   values, files, or other records. `@system` is reserved for platform-owned
   system records; authoring it can make the record uneditable.
 - Preserve existing `@id` annotations through rename, reorder, and file moves.
+- Omit `@id` on new ordinary declarations and nested rows unless a same-push
+  structural reference genuinely requires an explicit UUID. A successful push
+  assigns the durable IDs and rewrites source.
 - Do not add a second `@id` to a root or static member initializer. The member
-  ID owns that stored binding. Nested class/list rows still carry their own IDs.
+  ID owns that stored binding. Existing nested class/list rows retain their
+  inline IDs; new rows normally omit them until push.
 - Treat `.neo/` as private state and tracked Neo source as the authorable input.
 - Never seek a force-CAS bypass. Pull, resolve, review, and retry.
 
@@ -100,10 +105,13 @@ neo/
   DialogueGroups/
   Dialogues/*.neoflow
   Migrations/*.neo
+  **/*.spec.neo
   .neo/{state.json,conflicts/}
 ```
 
-All non-hidden `.neo`, `.neoflow`, and supported managed binaries are tracked.
+Production `.neo`/`.neoflow` files and supported managed binaries are tracked.
+Colocated `.spec.neo` files are test-only and never enter status, source hashes,
+pull/reset, or push.
 Normal pull preserves declaration placement and spelling by stable ID when it
 can. Force/reset may regroup source into the canonical layout.
 

package/skills/neocompose-cli/references/animation-and-world-authoring.md

@@ -109,9 +109,12 @@ override replaces the whole leaf.
 Frame overrides may change `Enabled`, `FlipX`, and `SortingOrder`; they may
 not add, remove, or reorder `Children`.
 
-Address direct children with stable row IDs. Missing optional child slots are
-skipped with diagnostics when the authored slot is absent, while stale
-pre-provenance placements may still fail closed.
+Address direct children through selector delegates. A selector should implement
+the project's own stable identity contract, such as an immutable `Name`, slug,
+or semantic position; do not turn a mutable object-row ID back into identity by
+returning `Reference<T>(id: "...")`. Missing optional child slots are skipped
+with diagnostics when the authored slot is absent, while stale pre-provenance
+placements may still fail closed.
 
 A placement row carries its `assetClassId` binding and optional `assetValueId`
 override beside its schema keys. They are row provenance, not declared schema:
@@ -127,8 +130,8 @@ sprite specialization is `NeoSpriteAnimationSegment`, whose
 
 Use one polymorphic `NeoAnimationClip.Tracks` list:
 
-- `NeoAnimationChildTrack` schedules a child clip selected by `Child` and
-  `ClipKey`.
+- `NeoAnimationChildTrack` schedules `ClipKey` on the child returned by its
+  `Selector` delegate.
 - A project subclass of
   `NeoAnimationSegmentTrack<TChild, TValue>` schedules a segment onto one
   target member. Implement its abstract `Segment` member as a stored value,
@@ -137,32 +140,54 @@ Use one polymorphic `NeoAnimationClip.Tracks` list:
   `NeoSpriteAnimationSegmentTrack<TChild extends NeoSpriteObject>` pairing
   targets `NeoSpriteObject.Sprite`.
 
-Declare a concrete project track by implementing `Segment`, then construct its
-row with the target child ID:
+Declare a concrete project track by implementing `Segment`, expose a compatible
+selector function on the owning object, then pass that function to each row:
 
 ```neo
 class StoredPantsTrack : NeoSpriteAnimationSegmentTrack<PantsSprite> {
   public override NeoSpriteAnimationSegment Segment = new();
 }
 
-Tracks = [
-  @id("pants-track-row-id")
-  new StoredPantsTrack(id: "pants-child-row-id") {
-    StartFrame = 0,
-    Direction = .Reverse,
-    OffsetEndIndex = 3,
-  },
-];
+class LegPart : NeoObject {
+  public PantsSprite SelectPants() {
+    var child = this.Children.FirstOrDefault((candidate) => {
+      return candidate.Name == "Pants";
+    });
+    if (child is PantsSprite pants) {
+      return pants;
+    }
+    throw "Pants child is missing or has the wrong type";
+  }
+
+  public NeoAnimationClip<LegPart> Walk = new NeoAnimationClip<LegPart> {
+    Tracks = [
+      new StoredPantsTrack(selector: this.SelectPants) {
+        StartFrame = 0,
+        Direction = .Reverse,
+        OffsetEndIndex = 3,
+      },
+    ]
+  };
+}
 ```
 
+Selectors may also be compatible inline closures. Prefer a named function when
+the identity rule is reused or deserves an explicit failure message. Never use
+a selector merely to wrap `Reference<T>(id: "...")`; that recreates the
+row-ID coupling selectors were introduced to remove. For new track rows, omit
+`@id` and let the successful push assign it. Preserve IDs already present on
+pulled rows.
+
 Each track has `StartFrame`, `Direction` (`.Forward` or `.Reverse`), and a
 crop window `OffsetStartIndex`/`OffsetEndIndex`. Crop before reversing, then
 schedule on the owning clip. Content beyond the owning clip truncates. Reject
 empty/inverted crop windows and tracks that can never enter the clip.
 
-Treat track target selection as class metadata, not row data. A target must be
-compatible with `TChild` and `TValue`. Track reads and segment getters are
-re-resolved for the next applied frame after a watched dependency changes.
+Treat track target selection as project-authored identity logic, not row data.
+The selector return type must be compatible with `TChild`; the segment value
+must be compatible with `TValue`. `Refresh` controls selector reevaluation,
+while track reads and segment getters are re-resolved for the next applied
+frame after a watched dependency changes.
 
 When multiple tracks write the same member in one frame, apply list order and
 let the last write win.

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

@@ -41,8 +41,12 @@ Read the relevant specs in full:
 - [P50 loops](https://github.com/ryanbliss/neo-compose-specs/blob/main/new-features/p50-neoscript-for-and-foreach-loops.md)
 - [P51 switch](https://github.com/ryanbliss/neo-compose-specs/blob/main/new-features/p51-neoscript-switch-statements.md)
 - [P52 try/catch](https://github.com/ryanbliss/neo-compose-specs/blob/main/new-features/p52-neoscript-try-catch-blocks.md)
+- [P60 delegate parameters and selector targeting](https://github.com/ryanbliss/neo-compose-specs/blob/main/new-features/p60-closure-parameters-and-selector-targeting.md)
+- [P61 initializer materialization](https://github.com/ryanbliss/neo-compose-specs/blob/main/new-features/complete/p61-initializer-materialization.md)
+- [P64 NeoScript unit testing and push hooks](https://github.com/ryanbliss/neo-compose-specs/blob/main/new-features/p64-neoscript-unit-testing-and-push-hooks.md)
 
-P38–P44 and P47–P51 are implemented. P45 remains deliberately deferred; do not
+P38–P44, P47–P52, P60–P61, and the initial P64 test/push-hook vertical slice
+are implemented. P45 remains deliberately deferred; do not
 build or teach runtime-child provenance. P46 is a hardening proposal, not an
 authoring capability. P52's document header still says proposed, but try/catch
 shipped in CLI 0.18; implementation and parity tests take precedence over that
@@ -78,7 +82,7 @@ wrappers.
 The marker near the top of `SKILL.md` must exactly match the package version:
 
 ```html
-<!-- reviewed-through-cli: 0.23.2 -->
+<!-- reviewed-through-cli: 0.24.1 -->
 ```
 
 The quoted version above is checked too, so this instruction cannot go stale

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

@@ -98,8 +98,11 @@ Reference<Dialogue>(id: "capitol-dialogue-id")
 - Both forms are legal in a member's declaration default, not only inside a
   value graph. A key written there resolves after every pass has run, so it may
   name a row the same push creates.
-- Keep structural references, such as child-track targets, ID-based when their
-  collection has no stable key/path surface.
+- Keep genuine structural references ID-based when their collection has no
+  stable symbol, path, or key surface. Animation track and frame-override
+  targets are selectors, not structural references: encode a stable
+  project-owned identity such as `Name` or slug in the selector instead of
+  wrapping a row ID in `Reference<T>(id: "...")`.
 
 Declaration and file order do not affect resolution within one push. Cyclic
 identity references are legal because they resolve IDs rather than evaluate a