@neocompose/cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+Copyright (c) Ryan Bliss and contributors. All rights reserved.
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED *AS IS*, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,79 @@
+# `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.
+
+## 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
+```
+
+## Packaging (`@neocompose/cli`)
+
+The CLI publishes as a standalone npm package from `cli/`:
+
+- `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`.
+
+## Interactive UX
+
+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`).
+
+## 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\|eval\|apply`            | Compile/evaluate NeoScript with the web's own compiler/evaluator                                         |
+| `records` / `values` / `loc`           | Content reads + writes with JSON-array batch stdin                                                       |
+
+Working-copy layout and the C# subset are documented in
+[`cli/skill/SKILL.md`](skill/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.
+- 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).