@neocompose/cli 0.4.1 → 0.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (168) hide show
  1. package/CHANGELOG.md +57 -0
  2. package/README.md +335 -197
  3. package/dist/neo.mjs +46251 -30564
  4. package/package.json +5 -3
  5. package/skills/neocompose-cli/SKILL.md +490 -296
  6. package/dist/tooling/Microsoft.CodeAnalysis.CSharp.dll +0 -0
  7. package/dist/tooling/Microsoft.CodeAnalysis.dll +0 -0
  8. package/dist/tooling/NeoCompose.Schema.Tooling.dll +0 -0
  9. package/dist/tooling/NeoCompose.Schema.Tooling.pdb +0 -0
  10. package/dist/tooling/NeoCompose.Schema.dll +0 -0
  11. package/dist/tooling/NeoCompose.Schema.pdb +0 -0
  12. package/dist/tooling/NeoCompose.Schema.xml +0 -1127
  13. package/dist/tooling/NeoCompose.SchemaCompiler.deps.json +0 -299
  14. package/dist/tooling/NeoCompose.SchemaCompiler.dll +0 -0
  15. package/dist/tooling/NeoCompose.SchemaCompiler.pdb +0 -0
  16. package/dist/tooling/NeoCompose.SchemaCompiler.runtimeconfig.json +0 -13
  17. package/dist/tooling/System.Collections.Immutable.dll +0 -0
  18. package/dist/tooling/System.Reflection.Metadata.dll +0 -0
  19. package/dist/tooling/System.Text.Encoding.CodePages.dll +0 -0
  20. package/dist/tooling/cs/Microsoft.CodeAnalysis.CSharp.resources.dll +0 -0
  21. package/dist/tooling/cs/Microsoft.CodeAnalysis.resources.dll +0 -0
  22. package/dist/tooling/de/Microsoft.CodeAnalysis.CSharp.resources.dll +0 -0
  23. package/dist/tooling/de/Microsoft.CodeAnalysis.resources.dll +0 -0
  24. package/dist/tooling/es/Microsoft.CodeAnalysis.CSharp.resources.dll +0 -0
  25. package/dist/tooling/es/Microsoft.CodeAnalysis.resources.dll +0 -0
  26. package/dist/tooling/fr/Microsoft.CodeAnalysis.CSharp.resources.dll +0 -0
  27. package/dist/tooling/fr/Microsoft.CodeAnalysis.resources.dll +0 -0
  28. package/dist/tooling/it/Microsoft.CodeAnalysis.CSharp.resources.dll +0 -0
  29. package/dist/tooling/it/Microsoft.CodeAnalysis.resources.dll +0 -0
  30. package/dist/tooling/ja/Microsoft.CodeAnalysis.CSharp.resources.dll +0 -0
  31. package/dist/tooling/ja/Microsoft.CodeAnalysis.resources.dll +0 -0
  32. package/dist/tooling/ko/Microsoft.CodeAnalysis.CSharp.resources.dll +0 -0
  33. package/dist/tooling/ko/Microsoft.CodeAnalysis.resources.dll +0 -0
  34. package/dist/tooling/pl/Microsoft.CodeAnalysis.CSharp.resources.dll +0 -0
  35. package/dist/tooling/pl/Microsoft.CodeAnalysis.resources.dll +0 -0
  36. package/dist/tooling/pt-BR/Microsoft.CodeAnalysis.CSharp.resources.dll +0 -0
  37. package/dist/tooling/pt-BR/Microsoft.CodeAnalysis.resources.dll +0 -0
  38. package/dist/tooling/reference-assemblies/netstandard2.1/Microsoft.Win32.Primitives.dll +0 -0
  39. package/dist/tooling/reference-assemblies/netstandard2.1/System.AppContext.dll +0 -0
  40. package/dist/tooling/reference-assemblies/netstandard2.1/System.Buffers.dll +0 -0
  41. package/dist/tooling/reference-assemblies/netstandard2.1/System.Collections.Concurrent.dll +0 -0
  42. package/dist/tooling/reference-assemblies/netstandard2.1/System.Collections.NonGeneric.dll +0 -0
  43. package/dist/tooling/reference-assemblies/netstandard2.1/System.Collections.Specialized.dll +0 -0
  44. package/dist/tooling/reference-assemblies/netstandard2.1/System.Collections.dll +0 -0
  45. package/dist/tooling/reference-assemblies/netstandard2.1/System.ComponentModel.Composition.dll +0 -0
  46. package/dist/tooling/reference-assemblies/netstandard2.1/System.ComponentModel.EventBasedAsync.dll +0 -0
  47. package/dist/tooling/reference-assemblies/netstandard2.1/System.ComponentModel.Primitives.dll +0 -0
  48. package/dist/tooling/reference-assemblies/netstandard2.1/System.ComponentModel.TypeConverter.dll +0 -0
  49. package/dist/tooling/reference-assemblies/netstandard2.1/System.ComponentModel.dll +0 -0
  50. package/dist/tooling/reference-assemblies/netstandard2.1/System.Console.dll +0 -0
  51. package/dist/tooling/reference-assemblies/netstandard2.1/System.Core.dll +0 -0
  52. package/dist/tooling/reference-assemblies/netstandard2.1/System.Data.Common.dll +0 -0
  53. package/dist/tooling/reference-assemblies/netstandard2.1/System.Data.dll +0 -0
  54. package/dist/tooling/reference-assemblies/netstandard2.1/System.Diagnostics.Contracts.dll +0 -0
  55. package/dist/tooling/reference-assemblies/netstandard2.1/System.Diagnostics.Debug.dll +0 -0
  56. package/dist/tooling/reference-assemblies/netstandard2.1/System.Diagnostics.FileVersionInfo.dll +0 -0
  57. package/dist/tooling/reference-assemblies/netstandard2.1/System.Diagnostics.Process.dll +0 -0
  58. package/dist/tooling/reference-assemblies/netstandard2.1/System.Diagnostics.StackTrace.dll +0 -0
  59. package/dist/tooling/reference-assemblies/netstandard2.1/System.Diagnostics.TextWriterTraceListener.dll +0 -0
  60. package/dist/tooling/reference-assemblies/netstandard2.1/System.Diagnostics.Tools.dll +0 -0
  61. package/dist/tooling/reference-assemblies/netstandard2.1/System.Diagnostics.TraceSource.dll +0 -0
  62. package/dist/tooling/reference-assemblies/netstandard2.1/System.Diagnostics.Tracing.dll +0 -0
  63. package/dist/tooling/reference-assemblies/netstandard2.1/System.Drawing.Primitives.dll +0 -0
  64. package/dist/tooling/reference-assemblies/netstandard2.1/System.Drawing.dll +0 -0
  65. package/dist/tooling/reference-assemblies/netstandard2.1/System.Dynamic.Runtime.dll +0 -0
  66. package/dist/tooling/reference-assemblies/netstandard2.1/System.Globalization.Calendars.dll +0 -0
  67. package/dist/tooling/reference-assemblies/netstandard2.1/System.Globalization.Extensions.dll +0 -0
  68. package/dist/tooling/reference-assemblies/netstandard2.1/System.Globalization.dll +0 -0
  69. package/dist/tooling/reference-assemblies/netstandard2.1/System.IO.Compression.FileSystem.dll +0 -0
  70. package/dist/tooling/reference-assemblies/netstandard2.1/System.IO.Compression.ZipFile.dll +0 -0
  71. package/dist/tooling/reference-assemblies/netstandard2.1/System.IO.Compression.dll +0 -0
  72. package/dist/tooling/reference-assemblies/netstandard2.1/System.IO.FileSystem.DriveInfo.dll +0 -0
  73. package/dist/tooling/reference-assemblies/netstandard2.1/System.IO.FileSystem.Primitives.dll +0 -0
  74. package/dist/tooling/reference-assemblies/netstandard2.1/System.IO.FileSystem.Watcher.dll +0 -0
  75. package/dist/tooling/reference-assemblies/netstandard2.1/System.IO.FileSystem.dll +0 -0
  76. package/dist/tooling/reference-assemblies/netstandard2.1/System.IO.IsolatedStorage.dll +0 -0
  77. package/dist/tooling/reference-assemblies/netstandard2.1/System.IO.MemoryMappedFiles.dll +0 -0
  78. package/dist/tooling/reference-assemblies/netstandard2.1/System.IO.Pipes.dll +0 -0
  79. package/dist/tooling/reference-assemblies/netstandard2.1/System.IO.UnmanagedMemoryStream.dll +0 -0
  80. package/dist/tooling/reference-assemblies/netstandard2.1/System.IO.dll +0 -0
  81. package/dist/tooling/reference-assemblies/netstandard2.1/System.Linq.Expressions.dll +0 -0
  82. package/dist/tooling/reference-assemblies/netstandard2.1/System.Linq.Parallel.dll +0 -0
  83. package/dist/tooling/reference-assemblies/netstandard2.1/System.Linq.Queryable.dll +0 -0
  84. package/dist/tooling/reference-assemblies/netstandard2.1/System.Linq.dll +0 -0
  85. package/dist/tooling/reference-assemblies/netstandard2.1/System.Memory.dll +0 -0
  86. package/dist/tooling/reference-assemblies/netstandard2.1/System.Net.Http.dll +0 -0
  87. package/dist/tooling/reference-assemblies/netstandard2.1/System.Net.NameResolution.dll +0 -0
  88. package/dist/tooling/reference-assemblies/netstandard2.1/System.Net.NetworkInformation.dll +0 -0
  89. package/dist/tooling/reference-assemblies/netstandard2.1/System.Net.Ping.dll +0 -0
  90. package/dist/tooling/reference-assemblies/netstandard2.1/System.Net.Primitives.dll +0 -0
  91. package/dist/tooling/reference-assemblies/netstandard2.1/System.Net.Requests.dll +0 -0
  92. package/dist/tooling/reference-assemblies/netstandard2.1/System.Net.Security.dll +0 -0
  93. package/dist/tooling/reference-assemblies/netstandard2.1/System.Net.Sockets.dll +0 -0
  94. package/dist/tooling/reference-assemblies/netstandard2.1/System.Net.WebHeaderCollection.dll +0 -0
  95. package/dist/tooling/reference-assemblies/netstandard2.1/System.Net.WebSockets.Client.dll +0 -0
  96. package/dist/tooling/reference-assemblies/netstandard2.1/System.Net.WebSockets.dll +0 -0
  97. package/dist/tooling/reference-assemblies/netstandard2.1/System.Net.dll +0 -0
  98. package/dist/tooling/reference-assemblies/netstandard2.1/System.Numerics.Vectors.dll +0 -0
  99. package/dist/tooling/reference-assemblies/netstandard2.1/System.Numerics.dll +0 -0
  100. package/dist/tooling/reference-assemblies/netstandard2.1/System.ObjectModel.dll +0 -0
  101. package/dist/tooling/reference-assemblies/netstandard2.1/System.Reflection.DispatchProxy.dll +0 -0
  102. package/dist/tooling/reference-assemblies/netstandard2.1/System.Reflection.Emit.ILGeneration.dll +0 -0
  103. package/dist/tooling/reference-assemblies/netstandard2.1/System.Reflection.Emit.Lightweight.dll +0 -0
  104. package/dist/tooling/reference-assemblies/netstandard2.1/System.Reflection.Emit.dll +0 -0
  105. package/dist/tooling/reference-assemblies/netstandard2.1/System.Reflection.Extensions.dll +0 -0
  106. package/dist/tooling/reference-assemblies/netstandard2.1/System.Reflection.Primitives.dll +0 -0
  107. package/dist/tooling/reference-assemblies/netstandard2.1/System.Reflection.dll +0 -0
  108. package/dist/tooling/reference-assemblies/netstandard2.1/System.Resources.Reader.dll +0 -0
  109. package/dist/tooling/reference-assemblies/netstandard2.1/System.Resources.ResourceManager.dll +0 -0
  110. package/dist/tooling/reference-assemblies/netstandard2.1/System.Resources.Writer.dll +0 -0
  111. package/dist/tooling/reference-assemblies/netstandard2.1/System.Runtime.CompilerServices.VisualC.dll +0 -0
  112. package/dist/tooling/reference-assemblies/netstandard2.1/System.Runtime.Extensions.dll +0 -0
  113. package/dist/tooling/reference-assemblies/netstandard2.1/System.Runtime.Handles.dll +0 -0
  114. package/dist/tooling/reference-assemblies/netstandard2.1/System.Runtime.InteropServices.RuntimeInformation.dll +0 -0
  115. package/dist/tooling/reference-assemblies/netstandard2.1/System.Runtime.InteropServices.dll +0 -0
  116. package/dist/tooling/reference-assemblies/netstandard2.1/System.Runtime.Numerics.dll +0 -0
  117. package/dist/tooling/reference-assemblies/netstandard2.1/System.Runtime.Serialization.Formatters.dll +0 -0
  118. package/dist/tooling/reference-assemblies/netstandard2.1/System.Runtime.Serialization.Json.dll +0 -0
  119. package/dist/tooling/reference-assemblies/netstandard2.1/System.Runtime.Serialization.Primitives.dll +0 -0
  120. package/dist/tooling/reference-assemblies/netstandard2.1/System.Runtime.Serialization.Xml.dll +0 -0
  121. package/dist/tooling/reference-assemblies/netstandard2.1/System.Runtime.Serialization.dll +0 -0
  122. package/dist/tooling/reference-assemblies/netstandard2.1/System.Runtime.dll +0 -0
  123. package/dist/tooling/reference-assemblies/netstandard2.1/System.Security.Claims.dll +0 -0
  124. package/dist/tooling/reference-assemblies/netstandard2.1/System.Security.Cryptography.Algorithms.dll +0 -0
  125. package/dist/tooling/reference-assemblies/netstandard2.1/System.Security.Cryptography.Csp.dll +0 -0
  126. package/dist/tooling/reference-assemblies/netstandard2.1/System.Security.Cryptography.Encoding.dll +0 -0
  127. package/dist/tooling/reference-assemblies/netstandard2.1/System.Security.Cryptography.Primitives.dll +0 -0
  128. package/dist/tooling/reference-assemblies/netstandard2.1/System.Security.Cryptography.X509Certificates.dll +0 -0
  129. package/dist/tooling/reference-assemblies/netstandard2.1/System.Security.Principal.dll +0 -0
  130. package/dist/tooling/reference-assemblies/netstandard2.1/System.Security.SecureString.dll +0 -0
  131. package/dist/tooling/reference-assemblies/netstandard2.1/System.ServiceModel.Web.dll +0 -0
  132. package/dist/tooling/reference-assemblies/netstandard2.1/System.Text.Encoding.Extensions.dll +0 -0
  133. package/dist/tooling/reference-assemblies/netstandard2.1/System.Text.Encoding.dll +0 -0
  134. package/dist/tooling/reference-assemblies/netstandard2.1/System.Text.RegularExpressions.dll +0 -0
  135. package/dist/tooling/reference-assemblies/netstandard2.1/System.Threading.Overlapped.dll +0 -0
  136. package/dist/tooling/reference-assemblies/netstandard2.1/System.Threading.Tasks.Extensions.dll +0 -0
  137. package/dist/tooling/reference-assemblies/netstandard2.1/System.Threading.Tasks.Parallel.dll +0 -0
  138. package/dist/tooling/reference-assemblies/netstandard2.1/System.Threading.Tasks.dll +0 -0
  139. package/dist/tooling/reference-assemblies/netstandard2.1/System.Threading.Thread.dll +0 -0
  140. package/dist/tooling/reference-assemblies/netstandard2.1/System.Threading.ThreadPool.dll +0 -0
  141. package/dist/tooling/reference-assemblies/netstandard2.1/System.Threading.Timer.dll +0 -0
  142. package/dist/tooling/reference-assemblies/netstandard2.1/System.Threading.dll +0 -0
  143. package/dist/tooling/reference-assemblies/netstandard2.1/System.Transactions.dll +0 -0
  144. package/dist/tooling/reference-assemblies/netstandard2.1/System.ValueTuple.dll +0 -0
  145. package/dist/tooling/reference-assemblies/netstandard2.1/System.Web.dll +0 -0
  146. package/dist/tooling/reference-assemblies/netstandard2.1/System.Windows.dll +0 -0
  147. package/dist/tooling/reference-assemblies/netstandard2.1/System.Xml.Linq.dll +0 -0
  148. package/dist/tooling/reference-assemblies/netstandard2.1/System.Xml.ReaderWriter.dll +0 -0
  149. package/dist/tooling/reference-assemblies/netstandard2.1/System.Xml.Serialization.dll +0 -0
  150. package/dist/tooling/reference-assemblies/netstandard2.1/System.Xml.XDocument.dll +0 -0
  151. package/dist/tooling/reference-assemblies/netstandard2.1/System.Xml.XPath.XDocument.dll +0 -0
  152. package/dist/tooling/reference-assemblies/netstandard2.1/System.Xml.XPath.dll +0 -0
  153. package/dist/tooling/reference-assemblies/netstandard2.1/System.Xml.XmlDocument.dll +0 -0
  154. package/dist/tooling/reference-assemblies/netstandard2.1/System.Xml.XmlSerializer.dll +0 -0
  155. package/dist/tooling/reference-assemblies/netstandard2.1/System.Xml.dll +0 -0
  156. package/dist/tooling/reference-assemblies/netstandard2.1/System.dll +0 -0
  157. package/dist/tooling/reference-assemblies/netstandard2.1/mscorlib.dll +0 -0
  158. package/dist/tooling/reference-assemblies/netstandard2.1/netstandard.dll +0 -0
  159. package/dist/tooling/ru/Microsoft.CodeAnalysis.CSharp.resources.dll +0 -0
  160. package/dist/tooling/ru/Microsoft.CodeAnalysis.resources.dll +0 -0
  161. package/dist/tooling/runtimes/win/lib/net6.0/System.Text.Encoding.CodePages.dll +0 -0
  162. package/dist/tooling/schema-contract.json +0 -23
  163. package/dist/tooling/tr/Microsoft.CodeAnalysis.CSharp.resources.dll +0 -0
  164. package/dist/tooling/tr/Microsoft.CodeAnalysis.resources.dll +0 -0
  165. package/dist/tooling/zh-Hans/Microsoft.CodeAnalysis.CSharp.resources.dll +0 -0
  166. package/dist/tooling/zh-Hans/Microsoft.CodeAnalysis.resources.dll +0 -0
  167. package/dist/tooling/zh-Hant/Microsoft.CodeAnalysis.CSharp.resources.dll +0 -0
  168. package/dist/tooling/zh-Hant/Microsoft.CodeAnalysis.resources.dll +0 -0
package/README.md CHANGED
@@ -1,15 +1,33 @@
1
- # `neo` — Neo Compose schema-as-code CLI
1
+ # `neo` — Neo Compose project-source CLI
2
2
 
3
- `neo` keeps a Git-friendly C# working copy of a Neo Compose project schema,
4
- syncs it bidirectionally with Convex, and exposes NeoScript and content
5
- commands. Schema format v3 is compiler-backed: authored files are real C# 11,
6
- not a handwritten C# subset.
3
+ `neo` synchronizes a Git-friendly Neo Compose project working copy with the
4
+ web editor. Working-copy format 4 is Neo-native: `.neo` defines the project
5
+ model and authored values, `.neoflow` defines dialogue flows, and managed image
6
+ and audio files stay as ordinary binaries.
7
7
 
8
8
  The complete contract is in
9
- [`specs/schema-as-code-cli.md`](../specs/schema-as-code-cli.md). The concise
10
- agent workflow is in
9
+ [`specs/neo-project-source-authoring.md`](../specs/neo-project-source-authoring.md).
10
+ The concise agent workflow is in
11
11
  [`cli/skills/neocompose-cli/SKILL.md`](skills/neocompose-cli/SKILL.md).
12
12
 
13
+ ## Source architecture
14
+
15
+ The CLI source separates authoring, document projection, and synchronization:
16
+
17
+ ```text
18
+ project-source/ parse, lower, and emit .neo/.neoflow plus managed binaries
19
+ project-manifest/ semantic bridge between authored source and project documents
20
+ project-sync/ diff, merge, conflict, migration, and CAS state handling
21
+ ```
22
+
23
+ The flow is `project source -> ProjectSchemaManifest -> project documents ->
24
+ sync`. `ProjectSchemaManifest` carries an independently versioned serialized
25
+ contract so source syntax and server documents can evolve without coupling
26
+ their version numbers. The current workspace format is still format 4; the
27
+ manifest's numeric contract version is not a second working-copy format.
28
+ Dependencies point downward: `project-source` may use both lower layers, while
29
+ `project-sync` never imports source-authoring or manifest code.
30
+
13
31
  ## Run
14
32
 
15
33
  ```sh
@@ -17,241 +35,361 @@ npm i -g @neocompose/cli # published package; installs `neo` on PATH
17
35
  node cli/bin/neo.mjs <command> # repository development
18
36
  ```
19
37
 
20
- Neo does not install or download .NET. It first looks for a compatible Unity
21
- 6000 runtime, then for a compatible system `dotnet`. Set `NEO_DOTNET_HOST` to
22
- an executable when discovery needs an explicit override. Run `neo doctor` to
23
- see the selected host, its compatibility result, the discovery cache, and the
24
- bundled schema-contract versions.
38
+ Set up a working copy with explicit IDs in automation:
25
39
 
26
- ## Format v3 working copy
40
+ ```sh
41
+ neo login --profile editor
42
+ neo init --project <id> --version <id> --dir neo
43
+ ```
44
+
45
+ Interactive terminals may select the project, version, and directory. Neo
46
+ does not install, discover, or require .NET. `neo doctor` validates the
47
+ format-4 browser-safe compiler, VS Code analysis contract, tracked source, and
48
+ managed-file capabilities.
49
+
50
+ ## Format-4 working copy
27
51
 
28
52
  ```text
29
53
  neo/
30
- neo.json # includes formatVersion: 3
31
- NeoCompose.Schema.csproj # netstandard2.1, C# 11, IDE-only
32
- Classes/ # class declarations
33
- Interfaces/ # Neo interfaces
34
- Enums/ # Neo enums
35
- Root.cs # [NeoRegistry] roots and loose members
36
- Templates/ # typed texture/audio settings
37
- Localization.cs # typed localization settings
38
- LocalizationStatuses/*.cs # typed workflow-status settings
39
- Scripts/<Class>/<Member>.neo # tracked NeoScript sidecars
54
+ neo.json # formatVersion: 4
55
+ Project.neo # project defaults/settings
56
+ Root.neo # protected root shape; editable root values
57
+ Classes/
58
+ Interfaces/
59
+ Enums/
60
+ Relations.neo # generic project relations, when present
61
+ Templates/
62
+ Localization.neo
63
+ LocalizationStatuses/
64
+ Files/
65
+ Images.neo # ImageRegistry Images
66
+ AudioClips.neo # AudioClipRegistry AudioClips
67
+ Images/ # tracked image bytes
68
+ AudioClips/ # tracked audio bytes
69
+ DialogueGroups/
70
+ Dialogues/*.neoflow
40
71
  Migrations/*.neo
41
72
  .neo/
42
- state.json # sync bases and CAS hashes
43
- dotnet-host.json # cached host discovery
44
- tooling/ # bundled SDK, analyzer, generator, compiler
73
+ state.json # private merge/CAS bases; never hand-edit
74
+ conflicts/
45
75
  ```
46
76
 
47
- `.neo/`, `bin/`, and `obj/` are gitignored. The C# project is an authoring
48
- project only; the game never references or ships it. The public
49
- `NeoCompose.Schema` SDK and analyzer are materialized from the npm package
50
- under `.neo/tooling`. There is no generated `Schema/NeoSchemaMembers.cs`.
77
+ All non-hidden `.neo`, `.neoflow`, and supported managed binaries are tracked.
78
+ `.neo/` is ignored private state. There is no schema `.csproj`, C# authoring
79
+ tree, Roslyn compiler, generated authoring DLL, per-function sidecar tree, or
80
+ checked-in dialogue JSON.
51
81
 
52
- Format v3 is a clean break and `neo.json` must contain `formatVersion: 3`.
53
- A workspace with a missing or different format version is unsupported. Preserve
54
- any source you need, then create a fresh v3 working copy with:
82
+ Only `formatVersion: 4` is accepted. Format 4 is a clean break; it does not
83
+ read or convert a format-3 C# checkout. Push intended changes with the older
84
+ CLI first, preserve any local source you need, then reconstruct from the
85
+ authoritative server:
55
86
 
56
87
  ```sh
57
- neo init --project <id> [--version <id>] [--dir neo]
88
+ neo init --project <id> --version <id> --dir neo
58
89
  ```
59
90
 
60
- `neo pull --reset` remains available for an existing v3 workspace: it
61
- reconstructs its managed schema files from the server and refreshes tooling.
62
-
63
- ## Real C# authoring
91
+ For an existing format-4 workspace, `neo pull --reset` regenerates canonical
92
+ source and managed binaries. Normal `neo pull` performs a stable-ID-aware
93
+ three-way merge and preserves source placement when possible.
64
94
 
65
- Stable IDs remain visible so a Git rename stays a server rename. Everything
66
- C# already expresses is written as C#: modifiers, base classes, interfaces,
67
- generic parameters and constraints, nullability, defaults, declaration order,
68
- method arguments, return types, and deferred `Task` results.
95
+ In Unity projects, `neo.json` may use `unityConfigPath` instead of storing
96
+ `projectId` and `versionId`. The referenced `NeoComposeConfig.asset` then owns
97
+ those IDs and receives branch/version switches.
69
98
 
70
- ```csharp
71
- using System.Threading.Tasks;
72
- using NeoCompose.Schema;
99
+ ## Native Neo authoring
73
100
 
74
- [NeoSchemaClass("class-inventory-item")]
75
- public abstract partial class InventoryItem<
76
- [NeoId("generic-stack-data")] TStackData>
77
- where TStackData : InventoryStackData
78
- {
79
- [NeoMember("member-name"), NeoText(SearchKey = true)]
80
- public virtual string Name { get; init; } = "";
101
+ Classes, interfaces, and enums are top-level declarations. Schema functions,
102
+ getters, and setters live inline and compile as NeoScript; they do not have
103
+ separate source files.
81
104
 
82
- [NeoMember("member-type")]
83
- public abstract ItemType Type { get; init; }
105
+ ```neo
106
+ @id("enum-item-rarity-id")
107
+ enum ItemRarity {
108
+ @id("rarity-common-id")
109
+ Common = "Common text",
110
+ }
84
111
 
85
- [NeoMember("member-description"), NeoComputed]
86
- public virtual string Description { get; }
112
+ @id("class-inventory-item-id")
113
+ @storage(allowed: .Immutable)
114
+ abstract class InventoryItem<
115
+ @id("inventory-context-generic-id")
116
+ TContext extends SomeClass
117
+ > {
118
+ @id("item-name-id")
119
+ @settings(localizable: true, searchKey: true)
120
+ virtual string Name = "";
121
+
122
+ @id("item-rarity-id")
123
+ abstract ItemRarity Rarity;
124
+
125
+ @id("item-stack-size-id")
126
+ @settings(min: 1, max: 999)
127
+ int StackSize = 1;
128
+
129
+ @id("item-display-name-id")
130
+ string DisplayName {
131
+ get {
132
+ return $"{Name} ({Rarity})";
133
+ }
134
+ }
87
135
 
88
- [NeoMember("function-use-primary"), NeoScript]
89
- public virtual partial Task<bool> UsePrimary(InventoryItem<TStackData> target);
136
+ @id("item-use-id")
137
+ abstract void Use(TContext context);
90
138
  }
91
139
  ```
92
140
 
93
- - `virtual`, `abstract`, and `override` have their native meanings. An
94
- override's base member ID is resolved from the Roslyn symbol graph.
95
- - Property type and nullability determine Neo kind and requiredness.
96
- - A property initializer is its default; declaration order is schema order.
97
- - A `static` property or method is class-owned. Stored static properties use a
98
- replaceable binding and are not copied into instances; instance and static
99
- receiver kinds cannot be changed in place.
100
- - Method signatures define function arguments and returns. `Task`/`Task<T>`
101
- means deferred execution. The bundled source generator gives concrete
102
- partial declarations inert compile-time implementations; authored schema
103
- code is never executed.
104
- - `[NeoMember]` owns stable identity and common options. Narrow typed
105
- attributes such as `[NeoText]`, `[NeoNumber]`, `[NeoList]`, `[NeoIndex]`,
106
- `[NeoColumn]`, `[NeoLookup]`, `[NeoDialogue]`, and `[NeoFile]` express
107
- Neo-specific behavior.
108
- - Nested entry graphs, texture/audio imports, localization, and uncommon
109
- settings use strongly typed object initializers. Their complete option sets
110
- participate in normal C# IntelliSense.
111
-
112
- For example, a concrete non-generic class can declare a class-owned stored
113
- member:
114
-
115
- ```csharp
116
- [NeoSchemaClass("class-game-rules")]
117
- public partial class GameRules
118
- {
119
- [NeoMember("member-encounter-count")]
120
- public static int EncounterCount { get; set; }
121
- }
141
+ The source identifier is the persisted name. `@settings` and `@storage` are
142
+ typed by their declaration context; invalid fields and enum cases are
143
+ diagnostics. Swift-like `.EnumCase` syntax works whenever the expected enum
144
+ type is known. Focused annotations such as `@id`, `@locked`, `@system`, and
145
+ `@relations` carry cross-cutting behavior.
146
+
147
+ Stable IDs preserve identity across rename, reorder, and file moves. Omit an
148
+ `@id` only to create something. A successful real push assigns the ID and
149
+ rewrites source; dry-run, validation failure, upload failure, and CAS failure
150
+ leave source byte-for-byte unchanged. Collection item identity uses the same
151
+ native annotation:
152
+
153
+ ```neo
154
+ Tags = [
155
+ @id("story-tag-item-id")
156
+ "story",
157
+ ];
122
158
  ```
123
159
 
124
- Only statically analyzable expressions are accepted: literals, enum values,
125
- `nameof`, `typeof`, arrays/collections, object initializers, and approved
126
- `Neo.*` reference constructors. The compiler never loads or executes the
127
- authored assembly. JSON carriers and identity escape hatches such as
128
- `ExtraJson`, `DefaultJson`, `RetJson`, `ArgsJson`, `EntryChainJson`,
129
- `SchemaKeyOrderJson`, `GenericParamIds`, `ChainJson`, `SignatureJson`,
130
- `ExtendsId`, `isVirtual`, and `isAbstract` do not exist in v3.
131
-
132
- Localization workflow statuses are ordinary stable records rather than IDs
133
- hidden in localization JSON:
134
-
135
- ```csharp
136
- [NeoLocalizationStatus("localization-status-approved")]
137
- public sealed partial class Approved
138
- {
139
- public static NeoLocalizationStatusSettings Settings { get; } = new()
140
- {
141
- Slug = "approved",
142
- Name = "Approved",
143
- Color = "#16a34a",
144
- TransitionRules = new[] { "localization-status-needs-review" },
160
+ ## Root values and class-owned values
161
+
162
+ `Root.neo` contains the compiler-owned `Root root = new() { ... }` envelope.
163
+ Its member names, types, IDs, lock annotations, and storage settings are
164
+ protected, while the `root.Assets`, `root.Save`, and `root.Session` value
165
+ initializers are editable.
166
+
167
+ Reusable values are stored static members on ordinary project classes. There
168
+ is no `ValueRegistry` or generated `Values` namespace.
169
+
170
+ ```neo
171
+ @id("assets-class-id")
172
+ @storage(allowed: .Immutable)
173
+ class Assets {
174
+ @id("capitol-member-id")
175
+ static Outpost Capitol =
176
+ @id("capitol-value-id")
177
+ new {
178
+ Name = "Capitol",
179
+ Image = Images.Capitol.Slice(0),
145
180
  };
181
+
182
+ @id("home-getter-id")
183
+ static Outpost Home {
184
+ get {
185
+ return Assets.Capitol;
186
+ }
187
+ }
146
188
  }
147
189
  ```
148
190
 
149
- ## NeoScript sidecars
150
-
151
- NeoScript is tracked separately from C# metadata:
152
-
153
- - `Scripts/<DeclaringClass>/<Member>.neo` is the only canonical path.
154
- - Every file contains its complete contextual wrapper. The outer signature
155
- mirrors the C# member and its NeoScript result type (`Task<T>` is represented
156
- as `T`), then adds `<DeclaringClass> this, Root root`; this chrome is protected
157
- in Monaco while the executable regions remain editable.
158
- - A computed property wrapper contains `get { ... }` and, when writable,
159
- `set(<Type> value) { ... }` units.
160
- - A concrete `[NeoScript]` method wrapper contains a nested
161
- `(<parameters>) { ... }` executable unit.
162
- - Abstract scripted members have no file.
163
- - Missing, duplicate, case-colliding, and orphaned sidecars are hard
164
- diagnostics. Stable member IDs let canonical renames move sidecars safely.
165
- - Canonical C# includes a `// NeoScript: Scripts/...` link above each scripted
166
- declaration. Definitions and navigation resolve in both directions between
167
- that declaration and the sidecar wrapper.
168
-
169
- ```neoscript
170
- string Description(InventoryItem this, Root root) {
171
- get {
172
- return $"{this.Name} ({this.Type})";
173
- }
191
+ Defaults materialize once when a value is created. Existing instances do not
192
+ stay linked to later class-default changes. Logical lookup/dialogue references
193
+ use the native typed intrinsic:
194
+
195
+ ```neo
196
+ Reference(Assets.Capitol)
197
+ Reference<Outpost>(id: "capitol-value-id")
198
+ Reference<Dialogue>(id: "dialogue-id")
199
+ ```
200
+
201
+ `Project.neo`, typed texture/audio templates, localization configuration and
202
+ statuses, priority groups/options, dialogue groups, and direct relations use
203
+ the same top-level typed declaration grammar. The compiler derives structural
204
+ row identities, storage placement, generic stamps, localized-text links, and
205
+ other persistence details that are not authorable source.
206
+
207
+ ## Files
208
+
209
+ Images and audio are declared in typed registries and referenced directly:
210
+
211
+ ```neo
212
+ ImageRegistry Images = new() {
213
+ @id("sword-image-file-id")
214
+ @settings(template: PixelArt)
215
+ NeoImage Sword = new("Files/Images/Sword.png");
174
216
  }
175
217
 
176
- bool UsePrimary(InventoryItem this, Root root) {
177
- (InventoryItem target) {
178
- return target.IsStackable;
218
+ AudioClipRegistry AudioClips = new() {
219
+ @id("sword-hit-audio-file-id")
220
+ @settings(template: SoundEffect)
221
+ NeoAudioClip SwordHit = new("Files/AudioClips/SwordHit.wav");
222
+ }
223
+ ```
224
+
225
+ Use `Images.Sword.Slice(0)` for a sprite and `AudioClips.SwordHit` for an audio
226
+ member. Dropping a supported binary into `Files/Images/` or
227
+ `Files/AudioClips/` creates a provisional symbol; status/diff report it, and a
228
+ successful push writes the explicit declaration and assigned ID. `neo files
229
+ add` can create that pending declaration before push.
230
+
231
+ Pull and push compare server-verified SHA-256 digests. Divergent local/remote
232
+ bytes keep the local file and place the verified remote side under
233
+ `.neo/conflicts/files/<file-id>/` until explicitly resolved.
234
+
235
+ ## NeoFlow dialogue authoring
236
+
237
+ Each `.neoflow` file contains exactly one sealed, non-generic class directly
238
+ derived from the system `Dialogue` type and exactly one required trigger
239
+ override. Dialogue functions and lexical value bindings are ordinary typed
240
+ Neo code. Main-locale prose is inline; other locales and workflow metadata
241
+ remain in localized-text records.
242
+
243
+ Graph constructors use NeoFlow-only trailing bodies. `=> Node` and a final
244
+ `return Node;` are equivalent destinations; there is no authorable `to:`
245
+ argument. Terminal text/actions nodes may omit a destination, while triggers,
246
+ options, and outcomes require one.
247
+
248
+ ```neoflow
249
+ @id("capitol-dialogue-id")
250
+ @settings(name: "Capitol: cold boot", saveOptionChoices: true)
251
+ sealed class CapitolColdBoot : Dialogue {
252
+ @primary Outpost capitol = Assets.Capitol;
253
+
254
+ @id("can-start-function-id")
255
+ bool CanStart() {
256
+ return capitol.Name == "Capitol";
257
+ }
258
+
259
+ @id("capitol-trigger-id")
260
+ override Trigger Trigger = new(
261
+ group: CapitolDialogues.High,
262
+ when: [
263
+ @id("can-start-condition-use-id")
264
+ CanStart,
265
+ ]
266
+ ) => Welcome;
267
+
268
+ @id("welcome-node-id")
269
+ Text Welcome = new(name: "Welcome!") {
270
+ """
271
+ Welcome to {capitol.Name}.
272
+ """
273
+
274
+ @id("continue-option-id")
275
+ Option Continue = new() {
276
+ """
277
+ Tell me more.
278
+ """
279
+ return Finish;
280
+ }
281
+ }
282
+
283
+ @id("finish-node-id")
284
+ Text Finish = new() {
285
+ """
286
+ Until next time.
287
+ """
179
288
  }
180
289
  }
181
290
  ```
182
291
 
183
- All executable body kinds use the same mutation-capable resolver and executor.
184
- Getters and code-authored conditions may write to Save, Session, runtime, or
185
- setter-backed targets; Immutable targets remain read-only. Body kind still
186
- controls return/deferred-call rules, not storage writability.
187
-
188
- Locals may use either an explicit type or `var`; inferred locals retain the
189
- same exact type and language features. Concrete, closed, writable Classes
190
- support `new ClassName(...)` in the same required-then-optional parameter order as
191
- generated C#. Optional parameters have inferred `null` defaults and are
192
- positional, so pass `null` to skip an earlier optional slot. Constructor-call
193
- signature help and parameter-name inlay hints come from that shared signature;
194
- the names are previews, not authored named-argument syntax.
195
- Fresh constructor graphs use Session ownership and are reclaimed at invocation
196
- completion unless attached, returned, passed onward, or otherwise escaped.
197
-
198
- Static access uses the declaring Class (`GameRules.EncounterCount`); stored
199
- static members resolve through their authored, Save, or Session binding layer.
200
-
201
- The browser-safe `neoscript-language` package is authoritative for the CLI,
202
- server compiler, web Monaco editor, and VS Code LSP. Monaco's existing syntax
203
- highlighting, comments/interpolation, scaffolds and protected regions,
204
- project-aware completion, hover, and accurate diagnostics are a
205
- release-blocking compatibility floor. The shared service also adds
206
- parser-recovery completion, signature help, definitions into C#, references,
207
- rename, symbols, semantic tokens, quick fixes, formatting, richer related
208
- diagnostics, contextual ranking, and incremental analysis. The in-repo VSIX
209
- uses the same results; marketplace publication is a separate release step.
292
+ Persisted condition uses, action invocations, mutations, pauses, options, and
293
+ outcomes each have their own stable `@id`. References made through lexical
294
+ bindings and transitive function calls derive the same linked values as the
295
+ web editor. Run `neo dialogue dryrun <ref>` after dialogue edits to traverse
296
+ option paths against a fresh save and catch runtime storage-ownership errors.
297
+
298
+ ## Synchronization workflow
299
+
300
+ ```sh
301
+ neo pull
302
+ # edit .neo, .neoflow, and managed binaries
303
+ neo status
304
+ neo diff
305
+ neo dialogue dryrun <ref>
306
+ neo push --dry-run
307
+ neo push
308
+ ```
309
+
310
+ A pull followed immediately by status or push dry-run must be a semantic
311
+ no-op. If it reports authoring changes, stop and report a round-trip bug rather
312
+ than pushing.
313
+
314
+ Pull merges source concepts and collections by stable identity, never by
315
+ index. Conflicts are explicit and block compilation. Edit source to the
316
+ desired result, or use `neo resolve --mine|--theirs` as a whole-side
317
+ convenience. There is no force-CAS bypass. Accept a required compatibility
318
+ bump only after reviewing it with `neo push --accept-bump`.
319
+
320
+ One push recompiles the complete source bundle at the trusted server boundary
321
+ and atomically commits semantic record changes, localized main-locale edits,
322
+ and staged files under CAS. Client AST, compiled IR, placement stamps, and
323
+ derived links are not trusted.
324
+
325
+ Optional scaffolds edit pending local source and never push:
326
+
327
+ ```sh
328
+ neo class new InventoryItem --abstract
329
+ neo value new Outpost --member Assets.Capitol --into root.Assets.Outposts
330
+ neo files add Files/Images/Sword.png --template PixelArt
331
+ neo dialogue new CapitolColdBoot --primary Outpost=Assets.Capitol --group CapitolDialogues
332
+ ```
210
333
 
211
334
  ## Commands
212
335
 
213
- | Command | Purpose |
214
- | ----------------------------------------- | -------------------------------------------------------------------------------------------------- |
215
- | `login` | Device-code OAuth; use `--profile release`, `--token-stdin`, or `NEO_COMPOSE_TOKEN` as appropriate |
216
- | `init --project <id> [--version <id>]` | Scaffold a format-v3 working copy and perform the first pull |
217
- | `doctor` | Report runtime discovery, compatibility, cache, tooling, and contract versions |
218
- | `pull [--reset]` | Sync or reconstruct; normal pulls use record-level three-way merge |
219
- | `status` / `diff` | Compile the working copy and compare its manifest with the base |
220
- | `push [--dry-run] [--accept-bump]` | Preview or commit one atomic compare-and-swap transaction |
221
- | `dev [--push]` | Watch the Convex sync signal and local files; pushing remains opt-in |
222
- | `resolve --mine\|--theirs` | Conflict-marker convenience; editing the final source is authoritative |
223
- | `script check\|compile\|eval\|apply` | Use the shared NeoScript compiler/evaluator and report values, writes, and surviving Session rows |
224
- | `records` / `values` / `loc` / `dialogue` | Read and batch-edit content, including stored static bindings, without schema-source value files |
225
-
226
- `neo script eval --json` reports `value`, ordered `writes`, and
227
- `createdSessionValues`. The last field contains only constructor rows that
228
- escaped invocation cleanup. Use `neo values bind`, `neo values unbind`, or an
229
- atomic `neo values create ... --bind <staticMemberId>` operation to manage
230
- an authored stored-static binding.
231
-
232
- The central invariant is unchanged: a pull followed immediately by status or
233
- push must produce no changes. The manifest contract classifies every field as
234
- authored, derived, or volatile and preserves derived server data from the base
235
- record. A newly introduced authored server field fails with “CLI contract
236
- upgrade required” instead of being hidden in opaque JSON.
336
+ | Command | Purpose |
337
+ | -------------------------------------------------------- | ---------------------------------------------------------------------------- |
338
+ | `login` / `whoami` | Authenticate and inspect the selected profile. |
339
+ | `init --project <id> [--version <id>]` | Create a format-4 working copy and perform its first reset pull. |
340
+ | `doctor` | Validate format/compiler/editor/source/file contracts; no .NET discovery. |
341
+ | `pull [--force\|--reset]` | Merge remote changes or regenerate canonical source and binaries. |
342
+ | `status [--json]` / `diff [--json]` | Compile source and show semantic records, spans, digests, and upload intent. |
343
+ | `push [--dry-run] [--accept-bump]` | Validate or commit one atomic compare-and-swap transaction. |
344
+ | `dev [--push]` | Watch remote/local changes; pushing remains opt-in. |
345
+ | `resolve --mine\|--theirs` | Resolve all current source/binary conflicts with one side. |
346
+ | `class new` / `value new` / `files add` / `dialogue new` | Create pending native source scaffolds. |
347
+ | `script check\|compile\|eval\|apply` | Compile or preview NeoScript with project context. |
348
+ | `migrate new\|list\|check\|run\|prune` | Author and manage tracked NeoScript migrations. |
349
+ | `branch` / `merge` / `release` / `channel` / `history` | Manage branches, releases, channels, and retained history. |
350
+ | `records` / `values` / `loc` / `dialogue` / `files` | Low-level content and repair operations. |
351
+ | `export unity` | Export the runtime Unity projection. |
352
+
353
+ Low-level write commands mutate the same authoritative records as the web
354
+ editor. They are useful for repair and automation, but do not edit checked-in
355
+ source; run `neo pull` immediately afterward. Whole-dialogue JSON
356
+ export/apply is not a source format and is not available.
357
+
358
+ Tokens use the OS credential store when available and a protected local file
359
+ only as fallback. CI can use `NEO_COMPOSE_TOKEN` or `--token-stdin`. The
360
+ editor profile cannot publish releases; server authorization remains the
361
+ security boundary.
362
+
363
+ ## Regenerating dialogue source names
364
+
365
+ Normal pull preserves source filenames and symbols by stable record ID. To
366
+ deliberately replace older machine-generated dialogue names with readable
367
+ names derived from the editor, run:
368
+
369
+ ```sh
370
+ neo pull --reset --regenerate-source-names
371
+ neo status
372
+ neo push --dry-run
373
+ ```
374
+
375
+ The reset leaves the regenerated names as local changes. IDs are unchanged,
376
+ and nothing is written to the server until `neo push` succeeds.
237
377
 
238
378
  ## Packaging
239
379
 
240
- `node cli/build.mjs` bundles the Node orchestrator and shared TypeScript code,
241
- builds the Roslyn sidecar, and places the prebuilt compiler, dependencies,
242
- runtime metadata, C# SDK, analyzer, and source generator in `dist/tooling`.
243
- The npm package contains the entire toolchain except a .NET host. Published
244
- contents and CLI/SDK/manifest contract versions are release-tested.
380
+ `node cli/build.mjs` bundles the Node orchestrator and browser-safe Neo
381
+ language/compiler/editor assets. The npm package contains no C# SDK, Roslyn
382
+ application, DLL, or .NET runtime metadata. Package checks reject those
383
+ artifacts and verify that the shared compiler assets and skill are present.
245
384
 
246
385
  Useful checks while developing:
247
386
 
248
387
  ```sh
249
388
  npm run typecheck
250
389
  npx vitest run cli
251
- npm run build
390
+ npm --prefix cli run test:package
252
391
  ```
253
392
 
254
- Run the repository's full verification suite before release, package the
255
- VSIX, exercise the Unity and Hello World samples through their documented
256
- Unity workflow, verify a live `neowyn` pull/status/push dry run, and run
257
- `npm run doctor` last.
393
+ Run the repository's full verification suite before release, package and
394
+ exercise the VS Code extension, verify the Hello World and live `neowyn`
395
+ format-4 no-op workflows, and run `npm run doctor` last.