@neocompose/cli 0.19.3 → 0.19.5

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

@@ -0,0 +1,150 @@
+# NeoScript
+
+Use this reference for inline code, snippets, nullability, control flow,
+runtime ownership, evaluation, and migrations.
+
+## Contents
+
+- Inline bodies and snippets
+- Nullability and ownership
+- Loops and transfer
+- Switch
+- Try/catch
+- Evaluation and migrations
+
+## Inline bodies and snippets
+
+Keep computed getters, setters, functions, dialogue logic, group logic, and
+constructors inline in their owning `.neo` or `.neoflow` declaration. Do not
+create `Scripts/<Class>/<Member>.neo` sidecars.
+
+Use the shared language service through focused commands:
+
+```sh
+neo script check --all
+neo script check --this Outpost --returns string 'return $"{this.Name}!";'
+neo script check --mode setter --member ComputedName 'root.Session.Name = value;'
+neo script check --mode nsfunction --member Outpost.RefreshUnlock 'return this.Level > 0;'
+neo script compile --mode nsfunction --member Outpost.RefreshUnlock 'return this.Level > 0;'
+neo script eval --returns string 'return root.Assets.Outposts[0].FullDisplayText;'
+neo script eval --function Outpost.RefreshUnlock --this-value <id> --args '[3]'
+neo script apply --mode action '...'
+```
+
+Prefer `--json` for automation.
+
+## Nullability and ownership
+
+Do not access a nullable receiver directly. First narrow it with a condition, or
+use null propagation `?.`, coalescing `??`, or explicit force unwrap `!` when
+failure is intended:
+
+```neo
+if (player.Target != null) {
+  return player.Target.Name;
+}
+return player.Target?.Name ?? "Unknown";
+```
+
+Treat lookup-return values with the same nullable narrowing rules.
+
+Let runtime ownership—not body kind—decide whether a write target is Immutable,
+Save, Session, Setter, or otherwise writable. A constructor writes only its
+`this` instance. A writable structured-leaf field still inherits the receiver's
+effective storage restrictions.
+
+## Loops and transfer
+
+Use C#-shaped loops:
+
+```neo
+for (int i = 0; i < Items.Count; i++) {
+  if (Items[i].Disabled) {
+    continue;
+  }
+  Visit(Items[i]);
+}
+
+foreach (var item in root.Save.Items) {
+  item.Enabled = true;
+}
+```
+
+A `foreach` receiver must be non-null. It snapshots membership/order once at
+entry, so adding/removing collection rows does not alter the scheduled
+iterations. Dictionary iteration binds values, not keys. The iterator binding
+is read-only, although writes through a writable entry remain valid.
+
+Use `break` for the nearest loop or switch and `continue` for the nearest
+loop. A `continue` inside a switch nested in a loop continues the loop.
+
+All nested loops and called NeoScript bodies share a 10,000-iteration budget.
+Do not use or teach `while` or `do`; they are not supported.
+
+## Switch
+
+Use scalar, enum, or nullable selectors with compile-time constant labels:
+
+```neo
+switch (direction) {
+  case Direction.North:
+    Move(0, 1);
+    break;
+  case Direction.East:
+  case Direction.West:
+    Stop();
+    break;
+  default:
+    throw $"Unknown direction: {direction}";
+}
+```
+
+Permit `int`, `string`, `bool`, enum, and nullable forms. Stack labels when
+they share one body. End every reachable non-empty section with `break`,
+`return`, `throw`, or `continue` when a surrounding loop makes it valid.
+Do not use implicit fallthrough, switch expressions, pattern cases, guards, or
+`goto`.
+
+## Try/catch
+
+Catch the string-valued NeoScript runtime-error channel with ordered filters:
+
+```neo
+try {
+  return GetUnsafe();
+}
+catch (string message) when (message == "1") {
+  return "Site moved";
+}
+catch (string message) {
+  throw;
+}
+```
+
+Require braces and at least one `catch (string name)`. The catch binding is
+read-only and scoped to its filter/body. Put at most one unfiltered catch last.
+A false or failing filter continues matching the original error. Bare
+`throw;` is valid only inside a catch and rethrows the original message.
+
+Do not use typed exception classes, parameterless catch, `finally`, `using`,
+patterns, or host-exception recovery. Completed writes before an error are not
+rolled back.
+
+## Evaluation and migrations
+
+`neo script eval` uses authored values and the same evaluator as the web app.
+`neo script apply` previews ordered write intents unless its explicit command
+contract offers a commit mode.
+
+Keep migrations as tracked action files under `Migrations/`:
+
+```sh
+neo migrate new <name> --target <ClassName|project>
+neo migrate list
+neo migrate check
+neo migrate run [--dry-run] [--skip-invalid]
+neo migrate prune
+```
+
+Run checks before migration execution. Review storage ownership and every write
+intent; do not assume an action body is writable merely because it compiled.

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

@@ -0,0 +1,158 @@
+# Values, identities, and references
+
+Use this reference for root/static values, nested identities, references,
+localization, and managed project files.
+
+## Contents
+
+- Root and static bindings
+- Identity rules
+- Same-push references
+- Defaults and localization
+- Managed files
+
+## Root and static bindings
+
+Edit only the initializer after `=` in the compiler-owned `Root.neo` envelope.
+The root member name, type, member ID, lock, and storage metadata are read-only.
+
+```neo
+Root root = new() {
+  @id("root-assets-member-id")
+  @locked
+  @storage(allowed: .Immutable)
+  Assets Assets = new() {
+    Outposts = [Assets.Capitol],
+  };
+}
+```
+
+Do not place another `@id` immediately before the root initializer. The member
+ID owns the binding. Apply the same rule to static stored members:
+
+```neo
+@id("assets-class-id")
+class Assets {
+  @id("capitol-member-id")
+  static Outpost Capitol = new {
+    Name = "Capitol",
+  };
+
+  @id("home-getter-id")
+  static Outpost Home {
+    get { return Assets.Capitol; }
+  }
+}
+```
+
+A computed static getter is an alias; it creates neither a binding nor a row.
+
+## Identity rules
+
+Preserve every existing ID through rename, reorder, and file moves. For a new
+ordinary record, omit `@id` and let a successful real push assign and insert
+it. Dry-run and failed pushes leave tracked source unchanged.
+
+Nested class/list rows remain independently addressable and keep inline IDs:
+
+```neo
+Tags = [
+  @id("story-tag-item-id")
+  "story",
+];
+```
+
+Never match an existing ordered row by index or payload. A bare row is pending
+create shorthand.
+
+When a same-push structural reference has no symbolic, path, or unique-key
+form, an author may assign a previously unseen UUID-v4 with `@id` to the new
+row and reference it in the same edit. Reusing an existing ID means update, not
+create. The server validates authored new IDs for UUID-v4 shape and uniqueness.
+Prefer generated IDs unless the structural reference needs an ID immediately.
+
+Do not invent IDs for structural rows whose identities derive from an owner
+role. Do not add a separate root/static initializer ID.
+
+## Same-push references
+
+Use the `Reference` intrinsic. Prefer the most readable form the target
+supports:
+
+```neo
+Reference(Assets.Capitol)
+Reference(root.Assets.Cosmetics.Pants)
+Reference<Outpost>(id: "capitol-value-id")
+Reference<PantsAsset>(key: "pants.long")
+Reference<PantsAsset>(key: "pants.long", index: Slug)
+Reference<Dialogue>(id: "capitol-dialogue-id")
+```
+
+- Use a symbol or root path when source can name the value directly.
+- Use `key:` only for a collection with a unique index. Omit `index:` when the
+  collection has exactly one usable unique index; supply the bare member name
+  when it has more than one.
+- Use the generic `id:` form when the ID is the only target information. A
+  `Reference` call whose argument is neither `id:` nor `key:` is rejected by
+  name rather than read as an 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.
+
+Declaration and file order do not affect resolution within one push. Cyclic
+identity references are legal because they resolve IDs rather than evaluate a
+dependency graph. Validate against the project after the push: a row deleted by
+the edit is not a target, and lookup/dialogue references must still satisfy
+assignability, collection membership, multiplicity, and group constraints.
+
+`collectionValue` references follow the same post-push resolution and
+membership rules as member defaults.
+
+## Defaults and localization
+
+Materialize omitted members from their current defaults only when an instance
+is created. Do not expect later class-default changes to update existing rows.
+Removing an explicitly materialized field from an existing initializer requests
+a reset through the current default; require that change to appear in
+`neo diff`.
+
+Write main-locale text directly in localizable string initializers. Pull/lower
+preserves other locales, comments, statuses, archive state, and unrelated
+localized-text links. Do not author localized-text IDs in place of prose.
+
+## Managed files
+
+Declare 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");
+}
+```
+
+Reference a sprite with `Images.Sword.Slice(0)` and an audio clip with
+`AudioClips.SwordHit`. A bare `Images.Sword` represents the file ID only in a
+file-valued context such as `SpriteInfo.FileId`; it is not a complete sprite.
+
+Dropping a supported binary under `Files/Images/` or `Files/AudioClips/`
+creates a pending file with a provisional deterministic symbol. Status,
+diff, and dry-run do not rewrite its registry. A successful push creates the
+record, uploads verified bytes, and materializes its declaration and ID.
+
+Use `neo files add <path> [--template <Name>]` to scaffold a declaration before
+push when desired.
+
+Pull/push compare server-verified SHA-256, not storage ETags. A divergent
+binary keeps local bytes and writes the verified remote side under
+`.neo/conflicts/files/<file-id>/`. A retained declaration with a missing binary
+is an error; remove the declaration to request deletion.