@neocompose/cli 0.87.1 → 0.88.0

package/package.json

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

package/skills/neocompose-cli/SKILL.md

@@ -9,74 +9,56 @@ description: >-
   `@neocompose/cli` or `node cli/bin/neo.mjs` in the neo-compose repository.
 ---
 
-<!-- reviewed-through-cli: 0.87.1 -->
+<!-- reviewed-through-cli: 0.88.0 -->
 
 # Neo Compose CLI
 
-Treat a format-4 `neo/` directory as a Git-like checkout of one Neo Compose
-project version. Tracked native source is the CLI authoring source of truth:
-edit it and use `neo push` for schema, values, dialogues, and managed files.
-The web UI remains a peer authoring surface over the shared server records.
+A format-4 `neo/` directory is a Git-like checkout of one Neo Compose project
+version. Tracked native source is the CLI's source of truth: edit it and
+`neo push` schema, values, dialogues, and managed files. The web UI edits the
+same server records.
 
-Do not look for a C# schema project, Roslyn compiler, authoring DLL, generated
+Format 4 has no C# schema project, Roslyn compiler, authoring DLL, generated
 SDK, `ValueRegistry`, per-member script sidecars, or checked-in dialogue JSON.
-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`, `.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. Newly authored value seeds are grouped under
-   the `.neo` source that owns them and are included in JSON output even when
-   they are the only pending work.
-4. Run `neo test` after NeoScript changes and `neo dialogue dryrun <ref>` after
-   dialogue changes.
-   `neo test` compiles the complete pending candidate, including idless nested
-   construction rows, so tests must work before the first push; do not add IDs
-   or push merely to obtain compiled initializer bodies.
-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 runs the preparation a real push ships — compilation, schema-commit
-   materialization, and whole-graph validation — against the pulled document,
-   without prompting, uploading, committing, or rewriting the checkout. Pull
-   once with the installed CLI so the workspace carries compatible
-   derived-edge extractor metadata. Pending getters and functions compile before
-   local initializer evaluation, including on a project's first push. Initializers
-   resolve pending value dependencies before their consumers; cyclic dependencies
-   report the participating values.
-6. Push one reviewed atomic change with `neo push`.
-   Completion arrives through a live subscription. Progress counts refresh every
-   five seconds while the durable job runs; a disconnect does not cancel it.
-
-Treat pull followed immediately by status or dry-run as a semantic no-op. If it
-reports project changes, stop and report a round-trip bug instead of pushing.
-
-The compiler reports file:line:column diagnostics and fails closed. Unknown
-authorable server fields require a CLI contract update; never preserve them as
-opaque JSON or guessed syntax.
-
-## Honor hard authoring invariants
-
-- Never add `@system` to project-authored declarations, members, overrides,
-  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.
-  A copy must get a new ID. A stored nested class value may keep its UUID-v4
-  when moved between compatible empty fields on existing parents, provided
-  its old parent no longer declares it. See the identity reference for limits.
-- 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 inserts them into the authored source. Files that
-  get no new IDs keep their bytes.
-- Do not add a second `@id` to a root or static member initializer. The member
-  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.
-
-## Set up a format-4 workspace
+Don't look for them.
+
+## Workflow
+
+1. `neo pull` before editing, and again before pushing if time has passed.
+2. Edit only tracked `.neo`, `.neoflow`, `.spec.neo`, and managed binaries.
+   Never edit `.neo/state.json`, analysis caches, or `.neo/conflicts`.
+3. `neo status` and `neo diff`. Review every change, including ones that
+   predate your task.
+4. `neo test` after NeoScript changes; `neo dialogue dryrun <ref>` after
+   dialogue changes. Both work before the first push, so never add IDs or
+   push just to test.
+5. `neo push --dry-run`, the full local commit rehearsal.
+6. `neo push` one reviewed, atomic change. On `non-fast-forward`, pull and
+   push again.
+
+Pull followed immediately by status or dry-run must be a no-op. If it reports
+changes, stop and report a round-trip bug instead of pushing.
+
+Diagnostics are file:line:column and the compiler fails closed. An unknown
+authorable server field needs a CLI contract update; never keep it as opaque
+JSON or guessed syntax.
+
+## Invariants
+
+- Never author `@system`. It marks platform-owned records and can make a
+  record uneditable.
+- Keep existing `@id`s through renames, reorders, and file moves. Copies get
+  new IDs.
+- Omit `@id` on new declarations and rows unless a same-push structural
+  reference needs an explicit UUID-v4. Push assigns IDs and writes them into
+  source; files without new IDs keep their bytes.
+- A root or static member's ID owns its stored binding. Never add a second
+  `@id` to its initializer.
+- Class, List, Set, and Dictionary values have one owner. Use `Clone()` for a
+  copy or `Reference(...)` to share.
+- Never seek a force-CAS bypass. Pull, resolve, review, retry.
+
+## Setup
 
 ```sh
 npm i -g @neocompose/cli
@@ -85,240 +67,74 @@ neo init --project <id> [--version <id>] [--dir neo]
 neo doctor
 ```
 
-Use `node cli/bin/neo.mjs` while developing the repository. Pass explicit flags
-and IDs in automation. Non-TTY/CI commands never wait for pickers or confirms.
-
-`neo init` requires a new or empty destination, apart from `.git` and
-`.gitignore`. It refuses other existing entries before writing anything; choose
-a separate directory when recovering a checkout whose config is missing.
-
-Require `formatVersion: 4` in `neo.json`. There is no format-3 reader or
-upgrader. Reconstruct an authoritative format-4 checkout with `neo init`.
-
-For an existing checkout:
-
-- `neo pull --reset` regenerates canonical source and managed binaries.
-- `neo pull --force` discards local edits in favor of the server.
-- `neo pull --regenerate-source-names` replaces generated default dialogue
-  names with readable ones, keeps chosen names, and rewrites references.
-
-Use reset and force only when their destructive effect is intended.
-
-In Unity projects, `neo.json` may use `unityConfigPath` instead of
-`projectId`/`versionId`. The referenced `NeoComposeConfig.asset` then owns those
-IDs and is updated by branch/version switches; do not duplicate them.
-
-## Recognize the workspace
+Use `node cli/bin/neo.mjs` inside the neo-compose repository. Pass explicit
+flags and IDs in automation; non-TTY runs never prompt. `neo init` needs an
+empty destination apart from `.git` and `.gitignore`, so recover a checkout
+with missing config in a separate directory. `neo.json` must have
+`formatVersion: 4`. In Unity projects it may use `unityConfigPath` instead of
+`projectId`/`versionId`; the referenced `NeoComposeConfig.asset` then owns the
+IDs, so don't duplicate them.
 
 ```text
 neo/
-  neo.json
-  Project.neo
-  Root.neo
-  Classes/{System/, ...}
-  Interfaces/{System/, ...}
-  Enums/{System/, ...}
-  Relations.neo
-  Templates/
-  Localization.neo
-  LocalizationStatuses/
+  neo.json  Project.neo  Root.neo  Relations.neo  Localization.neo
+  Classes/  Interfaces/  Enums/      (system declarations under System/)
+  Templates/  LocalizationStatuses/  DialogueGroups/
   Files/{Images.neo,AudioClips.neo,Images/,AudioClips/}
-  DialogueGroups/
   Variants/{<Class>.neo,<Class>/<Folder path>.neo}
   Dialogues/*.neoflow
   Migrations/*.neo
-  **/*.spec.neo
-  .neo/{state.json,conflicts/}
+  **/*.spec.neo                      (tests; never synced)
+  .neo/{state.json,conflicts/}       (private state)
 ```
 
-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 regenerates canonical text while retaining the current declaration
-paths and extracted initializer bindings, including moves made since the last
-sync. New server declarations use the default layout. System declarations
-default to a `System` subfolder under their category, including classes, enums,
-interfaces, templates, localization statuses, and priority/dialogue groups.
-Ownership comes from the reserved system identity, not the declaration name.
-
-## Load the focused contract you need
-
-Read only the references relevant to the task, but read each selected reference
-completely before editing:
+Declarations may live in any `.neo` file; pull keeps their placement by ID.
 
-- [Declarations and construction](references/declarations-and-construction.md):
-  classes, interfaces, enums, annotations, storage, required/header
-  constructors, declared constructors, settlement, and inheritance.
-- [Values, identities, and references](references/values-identities-and-references.md):
-  root/static bindings, nested/list identities, same-push references, unique
-  keys, files, localization, and virtual default projection.
-- [Animation and world authoring](references/animation-and-world-authoring.md):
-  objects, sorting, optional children, structured leaves, object variants and
-  variant folders, partial animation overrides, segments, tracks, and NeoFlow
-  dialogues.
-- [NeoScript](references/neoscript.md): inline bodies, snippets, nullability,
-  numeric and list builtins, loops, switch, try/catch, ownership, evaluation,
-  and migrations.
-- [Commands and synchronization](references/commands-and-sync.md): pull/push,
-  conflicts, low-level repair, branches, releases, and history.
-- [CLI development](references/cli-development.md): implementation source of
-  truth, shipped/proposed spec status, package boundaries, release maintenance,
-  and repository verification.
+## Source shape
 
-## Use native typed source
-
-Declare top-level project objects with typed declarations:
+Top-level project objects are typed declarations:
 
 ```neo
 Type Name = expression;
 Type Name = new(arguments) {
-  // Typed owned declarations supported by Type.
-}
-```
-
-Do not invent lowercase persistence-kind declarations such as `project`,
-`values`, `files`, or `relations`. Named arguments and contextual enum literals
-come from generated contracts; do not invent raw fields or property bags.
-
-Persisted reusable values are static members on ordinary project classes:
-
-```neo
-@id("assets-class-id")
-@storage(allowed: .Immutable)
-class Assets {
-  @id("capitol-member-id")
-  static Outpost Capitol = new {
-    Name = "Capitol",
-    Image = Images.Capitol.Slice(0),
-  };
-}
-```
-
-The member ID anchors the stored binding. A computed static getter is an alias
-and creates no stored binding or value row.
-
-Local project initializers may live in any `.neo` file and need no imports:
-
-```neo
-List<NeoSortingLayer> SORTING_LAYERS = [
-  @id("existing-layer-id")
-  new NeoSortingLayer() { Name = "Default" }
-];
-```
-
-Use `SortingLayers = SORTING_LAYERS` in Root or another stored initializer.
-The consuming member owns the value identity; do not add an ID at the use.
-Preserve existing nested IDs when extracting, and omit IDs on new rows.
-An aggregate has one owning assignment. Use `Reference(SORTING_LAYERS)` only
-where the receiving member permits that reference type. For independent
-copies, use the editor's duplicate action or copy the initializer without IDs.
-Scalars may have several owners. If those values diverge in web, pull keeps
-the different server values by inlining the differing uses. Initializer
-aliases are local source organization, not runtime globals or server records.
-Complete member and collection entries compose owned values, including inside
-constructor-backed initializers. A class local used as a constructor argument or
-executable operand refers to its single stored instance. Nested targets need an
-existing `@id` or an authored UUID-v4; a direct static owner supports pending IDs.
-Scalar executable expressions such as `BASE + 1` still require inlining the
-scalar expression. Locals are unavailable inside executable closures.
-The shared editor offers extract-to-file on a selected complete initializer,
-inline on its sole use, and duplicate at a use. Move the created file freely.
-
-Declare managed files in typed registries:
-
-```neo
-ImageRegistry Images = new() {
-  @id("sword-image-file-id")
-  @settings(template: PixelArt)
-  NeoImage Sword = new("Files/Images/Sword.png");
-}
-
-AudioClipRegistry AudioClips = new() {
-  @id("sword-hit-audio-file-id")
-  @settings(template: SoundEffect)
-  NeoAudioClip SwordHit = new("Files/AudioClips/SwordHit.wav");
+  // typed owned declarations supported by Type
 }
 ```
 
-Use `Images.Sword.Slice(0)` for a sprite and `AudioClips.SwordHit` for audio.
-Registry declarations and their image/audio paths may be in any project folder
-outside ignored/private directories. Update the registry path when moving a
-binary file. Renaming the registry symbol or replacing bytes retains the file
-ID when the declaration keeps its `@id`; keep the symbol aligned with the
-persisted file name, or set `@settings(name: ...)` explicitly. The name must
-end with the binary's extension, as in `@settings(name: "ClinkingCoin1.mp3")`,
-because pull rebuilds the file's path from it.
-
-A declaration can also live in its own file, with the registry listing it by
-name the way a member lists a local value. Its `@id` and `@settings` stay on
-the declaration:
-
-```neo
-// Values/Audio/SWORD_HIT.neo
-@id("sword-hit-audio-file-id")
-@settings(template: SoundEffect)
-NeoAudioClip SWORD_HIT = new("Files/AudioClips/SwordHit.wav");
-
-// Files/AudioClips.neo
-AudioClipRegistry AudioClips = new() {
-  NeoAudioClip SwordHit = SWORD_HIT;
-}
-```
-
-Pull preserves unchanged registry entries, comments, and authored order. New remote
-entries append to the registry; deleted entries are removed in place. Generated
-entries include `@settings(name: ...)` when the persisted name differs from the
-binary basename.
-Omitting `@settings(template: ...)` uses the complete built-in Unity import
-defaults for that file kind.
-
-## Resolve conflicts by identity
-
-Pull performs a record-aware three-way merge. Disjoint fields and children
-merge; collection and graph children merge by ID, never by index. Conflicting
-scalars, edges, order, delete/edit pairs, and binaries become explicit.
-
-Conflict source deliberately fails compilation. Edit the desired final source,
-or use `neo resolve --mine|--theirs` as a whole-side convenience. Then pull,
-review, dry-run, and push again.
-
-Either `neo resolve` side adopts the server side as the new base for every
-conflict it settles, so the next push plans against what the server holds:
-`--theirs` reads clean afterwards, `--mine` reads as an ordinary local update.
-Server-derived compilation metadata is not authored source and does not create
-a pull conflict by itself; if an older CLI retained such a metadata-only
-conflict without writing source markers, either side settles it the same way
-while preserving any real local source edit.
-
-`neo push` prepares the commit locally, recompiling changed NeoScript bodies
-and schema-affected callers, and the server commits the prepared changes under
-CAS. If another commit lands after your pull, the push fails as
-`non-fast-forward`: pull, then push again. Use
-`neo push --dry-run` for the complete source-to-record round-trip check; a
-normal push deliberately does not upload or re-lower the whole source tree. On
-`base-hash-conflict`, pull and resolve. On `version-bump-required`, inspect the
-classification and pass `neo push --accept-bump` only when intended.
-If a push committed but its local rewrite failed, run `neo pull` to resume the
-saved result. Keep `.neo/state.json`; status and push require that recovery first.
+Never invent lowercase persistence kinds such as `project`, `values`,
+`files`, or `relations`, raw fields, or property bags. Named arguments and
+contextual enum literals come from generated contracts.
+
+Formatting comes from `.editorconfig` (`indent_style`, `indent_size`,
+`end_of_line`, `insert_final_newline`; defaults two spaces, LF, final
+newline), shared by the CLI and VS Code. Formatting-only edits never create a
+push.
+
+## References
+
+Open the domain page for the task, then only the leaf it points to:
+
+- [NeoScript](references/neoscript/neoscript.md): bodies, names, nullability,
+  writes. Leaves: math and random, strings, collections, control flow, types
+  and narrowing, delegates and listeners, testing and migrations.
+- [Declarations](references/declarations/declarations.md): classes,
+  interfaces, enums, modifiers, members. Leaves: annotations and storage,
+  constructors, initializers, member kinds, overloads.
+- [Values](references/values/values.md): Root and static bindings, locals,
+  ownership. Leaves: identities, `Reference<T>`, defaults and localization,
+  managed files.
+- [World objects](references/world/world.md): tiles, objects, sorting,
+  structured leaves. Leaves: grids and cell patterns, variants, animation.
+- [Dialogues](references/dialogues.md): NeoFlow files, groups, labels,
+  triggering from NeoScript.
+- [Sync commands](references/sync/sync.md): pull, status, dry-run, push.
+  Leaves: conflicts and recovery, branches and access, Unity export.
+- [CLI development](references/cli-development.md): only when changing the
+  CLI, language service, package, or this skill.
 
 ## Finish with evidence
 
-Before a real push, report the files changed, the relevant `neo diff`, dialogue
-dry-run results when applicable, and `neo push --dry-run`. Do not claim success
-from parsing alone when construction, reference membership, runtime ownership,
-or server verification is involved.
-
-## Formatting
-
-The CLI and VS Code extension share NeoScript formatting and read `.editorconfig`
-for `.neo` and `.neoflow` files. Set `indent_style`, `indent_size`, `end_of_line`,
-and `insert_final_newline` there to keep regenerated source consistent with your
-editor. Defaults are two spaces, LF, and a final newline. A NeoFlow prose
-block's content and closing `"""` lines follow its opening `"""`, so re-indenting
-never changes the text. Push preserves authored
-text when regeneration has the same tokens; pull preserves semantically unchanged
-files. Formatting-only body or source-location changes do not create a subsequent
-push, including stored initializer recipes, computed member defaults, and inline
-constructor delegates; real code and string-content edits still do. Formatting preferences belong
-to the checkout, not stored script bodies.
+Before a real push, report the changed files, the relevant `neo diff`,
+dialogue dry-run results when applicable, and `neo push --dry-run`. Parsing
+alone doesn't prove construction, reference membership, runtime ownership, or
+server verification.