@neocompose/cli 0.1.5 → 0.2.0

package/README.md

@@ -1,84 +1,218 @@
 # `neo` — Neo Compose schema-as-code CLI
 
-Implements [specs/schema-as-code-cli.md](../specs/schema-as-code-cli.md): a
-git-like C# working copy of a project version's schema, bidirectionally
-synced with Convex, plus NeoScript and content commands.
+`neo` keeps a Git-friendly C# working copy of a Neo Compose project schema,
+syncs it bidirectionally with Convex, and exposes NeoScript and content
+commands. Schema format v2 is compiler-backed: authored files are real C# 11,
+not a handwritten C# subset.
+
+The complete contract is in
+[`specs/schema-as-code-cli.md`](../specs/schema-as-code-cli.md). The concise
+agent workflow is in
+[`cli/skills/neocompose-cli/SKILL.md`](skills/neocompose-cli/SKILL.md).
 
 ## Run
 
 ```sh
-npm i -g @neocompose/cli        # customers: standalone package, `neo` on PATH
-node cli/dist/neo.mjs <command>  # repo dev: runs TS directly via tsx
+npm i -g @neocompose/cli       # published package; installs `neo` on PATH
+node cli/bin/neo.mjs <command> # repository development
+```
+
+Neo does not install or download .NET. It first looks for a compatible Unity
+6000 runtime, then for a compatible system `dotnet`. Set `NEO_DOTNET_HOST` to
+an executable when discovery needs an explicit override. Run `neo doctor` to
+see the selected host, its compatibility result, the discovery cache, and the
+bundled schema-contract versions.
+
+## Format v2 working copy
+
+```text
+neo/
+  neo.json                         # includes formatVersion: 2
+  NeoCompose.Schema.csproj         # netstandard2.1, C# 11, IDE-only
+  Types/                           # custom classes
+  Interfaces/                      # Neo interfaces
+  Enums/                           # Neo enums
+  Root.cs                          # [NeoRegistry] roots and loose members
+  Templates/                       # typed texture/audio settings
+  Localization.cs                 # typed localization settings
+  LocalizationStatuses/*.cs       # typed workflow-status settings
+  Scripts/<Type>/<Member>.neo      # tracked NeoScript sidecars
+  Migrations/*.neo
+  .neo/
+    state.json                     # sync bases and CAS hashes
+    dotnet-host.json               # cached host discovery
+    tooling/                       # bundled SDK, analyzer, generator, compiler
+```
+
+`.neo/`, `bin/`, and `obj/` are gitignored. The C# project is an authoring
+project only; the game never references or ships it. The public
+`NeoCompose.Schema` SDK and analyzer are materialized from the npm package
+under `.neo/tooling`. There is no generated `Schema/NeoSchemaAttributes.cs`.
+
+Format v2 is a clean break. A workspace with no `formatVersion`, or with
+`formatVersion: 1`, rejects normal schema commands with an instruction to run:
+
+```sh
+neo pull --reset
+```
+
+Reset reconstructs the schema from the server as v2, refreshes tooling, and
+removes obsolete generated authoring files. There is no v1 parser or
+compatibility shim.
+
+## Real C# authoring
+
+Stable IDs remain visible so a Git rename stays a server rename. Everything
+C# already expresses is written as C#: modifiers, base classes, interfaces,
+generic parameters and constraints, nullability, defaults, declaration order,
+method arguments, return types, and deferred `Task` results.
+
+```csharp
+using System.Threading.Tasks;
+using NeoCompose.Schema;
+
+[NeoType("type-inventory-item")]
+public abstract partial class InventoryItem<
+    [NeoId("generic-stack-data")] TStackData>
+    where TStackData : InventoryStackData
+{
+    [NeoMember("attribute-name"), NeoText(SearchKey = true)]
+    public virtual string Name { get; init; } = "";
+
+    [NeoMember("attribute-type")]
+    public abstract ItemType Type { get; init; }
+
+    [NeoMember("attribute-description"), NeoComputed]
+    public virtual string Description { get; }
+
+    [NeoMember("function-use-primary"), NeoScript]
+    public virtual partial Task<bool> UsePrimary(InventoryItem<TStackData> target);
+}
 ```
 
-## Packaging (`@neocompose/cli`)
+- `virtual`, `abstract`, and `override` have their native meanings. An
+  override's base member ID is resolved from the Roslyn symbol graph.
+- Property type and nullability determine Neo kind and requiredness.
+- A property initializer is its default; declaration order is schema order.
+- Method signatures define function arguments and returns. `Task`/`Task<T>`
+  means deferred execution. The bundled source generator gives concrete
+  partial declarations inert compile-time implementations; authored schema
+  code is never executed.
+- `[NeoMember]` owns stable identity and common options. Narrow typed
+  attributes such as `[NeoText]`, `[NeoNumber]`, `[NeoList]`, `[NeoIndex]`,
+  `[NeoColumn]`, `[NeoLookup]`, `[NeoDialogue]`, and `[NeoFile]` express
+  Neo-specific behavior.
+- Nested entry graphs, texture/audio imports, localization, and uncommon
+  settings use strongly typed object initializers. Their complete option sets
+  participate in normal C# IntelliSense.
+
+Only statically analyzable expressions are accepted: literals, enum values,
+`nameof`, `typeof`, arrays/collections, object initializers, and approved
+`Neo.*` reference constructors. The compiler never loads or executes the
+authored assembly. JSON carriers and identity escape hatches such as
+`ExtraJson`, `DefaultJson`, `RetJson`, `ArgsJson`, `EntryChainJson`,
+`SchemaKeyOrderJson`, `GenericParamIds`, `ChainJson`, `SignatureJson`,
+`ExtendsId`, `isVirtual`, and `isAbstract` do not exist in v2.
 
-The CLI publishes as a standalone npm package from `cli/`:
+Localization workflow statuses are ordinary stable records rather than IDs
+hidden in localization JSON:
+
+```csharp
+[NeoLocalizationStatus("localization-status-approved")]
+public sealed partial class Approved
+{
+    public static NeoLocalizationStatusSettings Settings { get; } = new()
+    {
+        Slug = "approved",
+        Name = "Approved",
+        Color = "#16a34a",
+        TransitionRules = new[] { "localization-status-needs-review" },
+    };
+}
+```
 
-- `cli/package.json` — `bin: neo`, runtime deps are only `convex` and
-  `@inquirer/prompts`.
-- `node cli/build.mjs` (also `prepublishOnly`) bundles `src/main.ts` into
-  `dist/neo.mjs` with esbuild: all shared monorepo code (`src/models`,
-  `src/database/neoscript`, the evaluator, `convex/_generated` references)
-  is compiled INTO the bundle, so the published artifact has no source
-  dependency on this repo. The build fails if the bundle imports any
-  package not declared as a dependency.
-- `cli/dist/` is gitignored; publish with `cd cli && npm publish`.
+## NeoScript sidecars
 
-## Interactive UX
+NeoScript is tracked separately from C# metadata:
+
+- `Scripts/<DeclaringType>/<Member>.neo` is the only canonical path.
+- Every file contains its complete contextual wrapper. The outer signature
+  mirrors the C# member and its NeoScript result type (`Task<T>` is represented
+  as `T`), then adds `<DeclaringType> this, Root root`; this chrome is protected
+  in Monaco while the executable regions remain editable.
+- A computed property wrapper contains `get { ... }` and, when writable,
+  `set(<Type> value) { ... }` units.
+- A concrete `[NeoScript]` method wrapper contains a nested
+  `(<parameters>) { ... }` executable unit.
+- Abstract scripted members have no file.
+- Missing, duplicate, case-colliding, and orphaned sidecars are hard
+  diagnostics. Stable member IDs let canonical renames move sidecars safely.
+- Canonical C# includes a `// NeoScript: Scripts/...` link above each scripted
+  declaration. Definitions and navigation resolve in both directions between
+  that declaration and the sidecar wrapper.
+
+```neoscript
+string Description(InventoryItem this, Root root) {
+  get {
+    return $"{this.Name} ({this.Type})";
+  }
+}
+
+bool UsePrimary(InventoryItem this, Root root) {
+  (InventoryItem target) {
+    return target.IsStackable;
+  }
+}
+```
 
-In a terminal, missing arguments become prompts (`@inquirer/prompts`):
-`neo init` walks project → branch/version → directory; `neo login` picks the
-profile and opens the browser for the device code; `neo branch switch` /
-`neo merge` offer pickers; `neo push` confirms (and offers bump acceptance on
-rejection); `neo release cut` previews the derived floor before asking for
-the bump; pull conflicts offer markers / mine-all / theirs-all. Every prompt
-degrades in CI/pipes (no TTY, `CI`, or `NEO_NO_INTERACTIVE` set): commands
-keep their flag-driven behavior, prompts that would block instead raise an
-error naming the flag to pass, and output is plain (also `NO_COLOR`).
+The browser-safe `neoscript-language` package is authoritative for the CLI,
+server compiler, web Monaco editor, and VS Code LSP. Monaco's existing syntax
+highlighting, comments/interpolation, scaffolds and protected regions,
+project-aware completion, hover, and accurate diagnostics are a
+release-blocking compatibility floor. The shared service also adds
+parser-recovery completion, signature help, definitions into C#, references,
+rename, symbols, semantic tokens, quick fixes, formatting, richer related
+diagnostics, contextual ranking, and incremental analysis. The in-repo VSIX
+uses the same results; marketplace publication is a separate release step.
 
 ## Commands
 
-| Command                                | Purpose                                                                                                  |
-| -------------------------------------- | -------------------------------------------------------------------------------------------------------- |
-| `login`                                | Device-code OAuth (`neo-cli-editor` / `--profile release`); `--token-stdin` / `NEO_COMPOSE_TOKEN` for CI |
-| `init --project <id> [--version <id>]` | Scaffold `neo/` (csproj, attributes, .gitignore) + first pull                                            |
-| `pull [--force]`                       | Sync from server; field-level three-way merge; conflict markers on overlap                               |
-| `push [--dry-run] [--accept-bump]`     | Atomic CAS transaction; assigns ids to creates; canonical rewrite                                        |
-| `status` / `diff`                      | Working-copy changes vs base                                                                             |
-| `dev [--push]`                         | Convex websocket sync-signal subscription + file watcher                                                 |
-| `resolve --mine\|--theirs`             | Conflict-marker sugar (editing the file is the real path)                                                |
-| `script check\|compile\|eval\|apply`   | Compile/evaluate properties, actions, and typed NeoScript Functions with the web compiler/evaluator      |
-| `records` / `values` / `loc`           | Content reads + writes with JSON-array batch stdin                                                       |
-
-Working-copy layout and the C# subset are documented in
-[`cli/skills/neocompose-cli/SKILL.md`](skills/neocompose-cli/SKILL.md) (the agent onboarding surface) and the
-spec. State lives in `neo/.neo/state.json` (gitignored): per-record base
-content hashes — the compare-and-swap tokens — plus conflict bookkeeping.
-
-## Architecture notes
-
-- **Convex-direct, fully typed**: the CLI calls Convex with `api.*`
-  references and inferred types (`cli/src/convex.ts`), authenticated by a
-  Convex JWT minted from the scoped device-flow session. Pushes go through
-  the session-gated `serverProjectRecordOperations.commitFromSession`
-  (same per-change scope gates + CAS as the web's S2S commit). HTTP is used
-  only for the auth plane and for content verbs that reuse Next-side write
-  services. Record payloads are narrowed with the same `src/models` guards
-  the web app uses.
-
-- **Round-trip invariant**: `pull` → `push` is always a no-op. Enforced by
-  the consumption-model partition (`cli/src/schema/emit.ts`): every record
-  field is either expressed in C#, carried in `ExtraJson`, or held as a
-  volatile field in state and merged back at reconstruction.
-- **NeoScript Functions**: `[NeoNSFunction(Code, RetJson, ArgsJson,
-Deferred)]` projects authored source/signature while compiled `action` stays
-  volatile. `neo script check --all` validates every stored NeoScript body;
-  `eval`/`apply --function <Type.Member> --this-value <id> --args '[...]'`
-  preview typed results and write intents without committing them.
-- The parser (`cli/src/schema/parse.ts`) is a hand-rolled
-  recursive-descent parser for the constrained subset with
-  file:line:column diagnostics.
-- Server surfaces: `schema/document` (read), `schema/transactions`
-  (atomic CAS write), `projectExportData.schemaSignal` (websocket signal).
-- Tests: `npx vitest run cli` (round-trip corpus, parser, merge matrix).
+| Command                                   | Purpose                                                                                            |
+| ----------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| `login`                                   | Device-code OAuth; use `--profile release`, `--token-stdin`, or `NEO_COMPOSE_TOKEN` as appropriate |
+| `init --project <id> [--version <id>]`    | Scaffold a format-v2 working copy and perform the first pull                                       |
+| `doctor`                                  | Report runtime discovery, compatibility, cache, tooling, and contract versions                     |
+| `pull [--reset]`                          | Sync or reconstruct; normal pulls use record-level three-way merge                                 |
+| `status` / `diff`                         | Compile the working copy and compare its manifest with the base                                    |
+| `push [--dry-run] [--accept-bump]`        | Preview or commit one atomic compare-and-swap transaction                                          |
+| `dev [--push]`                            | Watch the Convex sync signal and local files; pushing remains opt-in                               |
+| `resolve --mine\|--theirs`                | Conflict-marker convenience; editing the final source is authoritative                             |
+| `script check\|compile\|eval\|apply`      | Use the shared NeoScript compiler/evaluator                                                        |
+| `records` / `values` / `loc` / `dialogue` | Read and batch-edit content without materializing it as schema files                               |
+
+The central invariant is unchanged: a pull followed immediately by status or
+push must produce no changes. The manifest contract classifies every field as
+authored, derived, or volatile and preserves derived server data from the base
+record. A newly introduced authored server field fails with “CLI contract
+upgrade required” instead of being hidden in opaque JSON.
+
+## Packaging
+
+`node cli/build.mjs` bundles the Node orchestrator and shared TypeScript code,
+builds the Roslyn sidecar, and places the prebuilt compiler, dependencies,
+runtime metadata, C# SDK, analyzer, and source generator in `dist/tooling`.
+The npm package contains the entire toolchain except a .NET host. Published
+contents and CLI/SDK/manifest contract versions are release-tested.
+
+Useful checks while developing:
+
+```sh
+npm run typecheck
+npx vitest run cli
+npm run build
+```
+
+Run the repository's full verification suite before release, package the
+VSIX, exercise the Unity and Hello World samples through their documented
+Unity workflow, verify a live `neowyn` pull/status/push dry run, and run
+`npm run doctor` last.