@neocompose/cli 0.87.1 → 0.88.0

package/skills/neocompose-cli/references/commands-and-sync.md

@@ -1,408 +0,0 @@
-# Commands and synchronization
-
-Use this reference for workspace synchronization, conflicts, repair commands,
-branches, releases, history, and authentication.
-
-## Contents
-
-- Pull, inspect, and push
-- Conflicts and files
-- Localization operations
-- Branches, releases, and history
-- Authentication and automation
-
-## Pull, inspect, and push
-
-`neo doctor` fails on malformed records in the last-pulled document. Pull first to audit the current
-head. After a reviewed `neo doctor --fix`, pull and check again.
-
-Use the high-level source workflow:
-
-```sh
-neo pull
-neo status
-neo doctor
-neo diff
-neo dialogue dryrun <dialogue-ref>
-neo push --dry-run
-neo push
-neo push --dry-run --force-recompile
-```
-
-`neo status` reports invalid constructor parameters at their `.neo` file, line,
-and column. Fix the reported parameter type before pushing.
-A failed class or constructor declaration blocks candidate preparation.
-
-Constructor-created values keep references to their effective sibling rows when
-replayed. An unchanged project stays clean after push and pull, including nested
-constructor values with reference arguments; it does not need another push before
-export. Animation validation uses the project's registered files and texture
-templates, including when constructors supply sprite defaults.
-
-Use `neo pull --regenerate-source-names` to replace generated default dialogue
-names with readable ones. It keeps chosen names and rewrites references. Use
-`--reset` to regenerate canonical source and managed binaries. Reset retains
-declaration file grouping already recorded by the workspace, while
-declarations with no prior placement use the canonical per-declaration layout. Use `--force` only to discard local edits for the server
-version. Normal pulls persist a transaction cursor and fetch only changed
-records. Dictionary string keys, including Unicode, `_id`, `$name`, and `__proto__`,
-round-trip through full and incremental reads. String keys may be empty or contain
-whitespace; enum keys must name a live enum option. If the remote head is unchanged, pull preserves the local source
-without compiling it; use `neo status` to inspect local edits and diagnostics.
-Pull ignores records whose hashes already match the saved server baseline,
-including echoes of this checkout's last push, and advances its cursor without
-compiling or rewriting source. Later remote edits still count as changes.
-An undo/reset metadata change invalidates the cursor and causes a safe
-full-snapshot fallback.
-
-After a compiler upgrade, run `neo pull` with `.neo/state.json` intact. Pull
-refreshes every cached record whose remote change touches only compiler-owned
-bodies or timestamps before local compilation, even when the same pull merges
-other changes. When nothing else changed, it leaves authored files and managed
-binaries untouched. Added or deleted records, authored changes, and unresolved
-conflicts take the normal merge path. Status, push, and pull refuse a baseline
-holding a compiled body this CLI rejects and name the record. If `neo pull`
-cannot refresh it, back up local edits and run `neo pull --force`.
-
-If a push commits but source rewriting fails, `neo pull` resumes its saved
-result before checking the remote head. The recovery journal in `.neo/state.json`
-retains committed identities and any prepared file replacements. Interrupted
-file writes resume without parsing a partially rewritten checkout. If a file
-was edited again after that plan was saved, recovery stops and names the file;
-preserve that edit separately before restoring the expected content and retrying.
-`--reset` and `--force` explicitly discard local edits and can bypass recovery.
-
-Keep `.neo/state.json`: it holds the merge baseline and source placements.
-Normal pull refuses existing production sources without that baseline. To
-deliberately replace a checkout whose state is gone, back it up first and use
-`neo pull --force`; the CLI recovers custom paths from the remaining declarations.
-The force pull replaces local source with the server version.
-
-Pull downloads up to eight managed image or audio files concurrently and reuses
-matching local bytes. It verifies all downloads before replacing binaries or
-updating conflict artifacts. A failed transfer leaves existing files intact;
-retry the pull after resolving the reported download error.
-
-Full document pulls size pages against Convex resource limits and fetch
-independent remaining ranges concurrently. Pull pins every page and snapshot
-batch to one published generation and logical revision. If either changes during assembly, the CLI discards the attempt and
-restarts. Upgrade the CLI together with the P83 server read protocol.
-
-Treat `neo push --dry-run` as a full local commit rehearsal: source emission,
-in-memory pending-ID assignment, transport shapes, hashes, and repeat
-verification all run. It also runs the preparation a real push ships —
-compilation, schema-commit materialization, seeded structural rows, and
-whole-graph validation — so a rejection reports before anything is sent. It
-does not prompt, upload, commit, or rewrite source.
-
-Removing a class or collection declaration also deletes its hidden collection
-entry members, including nested lists and dictionaries. Replacing a collection
-with a scalar deletes its abandoned entries too. Entries used by surviving
-declarations are retained. If a member is deleted locally before pulling remote
-instance values, pull retains those values in the deletion plan; the next push
-removes them with the member. Review these derived deletions in `neo status` or
-`neo diff` before pushing.
-
-Dry-run also compares the CLI's derived-edge extractor with the server version
-saved by the last pull. Run `neo pull` after upgrading the CLI or when an older
-workspace lacks that metadata. A newer server extractor requires a CLI
-upgrade; a newer CLI extractor requires the server watermark to be repaired.
-
-Normal preparation follows typed compiler dependencies and recompiles only
-bodies affected by changed declarations. Use `--force-recompile` with either a
-dry run or a real push only when diagnosing stale derived IR: it retains the
-exhaustive project-wide body sweep and is intentionally slower.
-
-Changed member bodies and migration bodies share one schema projection and its
-indexes throughout push preparation, so a batch of scripted changes does not
-rebuild the whole schema for every body. Each changed body compiles once for
-local evaluation and once more, against minted ids, in the preparation the push
-ships.
-
-Interactive status, diff, pull, and test commands report workspace loading and
-preparation phases. Spinners continue animating during synchronous compilation;
-`NO_COLOR` removes color without stopping the animation. JSON reporters and
-piped status/test output contain no terminal animation.
-
-Interactive pushes report the active preparation phase before workspace
-discovery, lowering, compilation, source hashing, and validation begin.
-A normal push prepares that transport once before confirmation and reuses it
-after confirmation; it does not run a second local preparation pass. JSON and
-non-TTY output remain structured and do not emit that terminal-only spinner.
-
-A clean dry-run does not promise a clean push. The workspace holds its
-last-pulled state, so the server still grades the live head: the project-head
-check, per-change CAS bases, authorization, row shapes, project-file staging,
-admission, chunk planning, and finalization. A push whose head moved fails as
-`non-fast-forward`. Pull again before pushing if time has passed.
-
-Durable preparation is selected from the semantic record workload, not the
-size of the project-wide source identity. Its storage artifact carries one
-copy of the prepared transaction, and resumable staging reads one plan per
-bounded batch while preserving an atomic write boundary per physical chunk.
-The complete source stays local. Normal push hashes the exact authored source
-inputs already read during preparation, including file paths and formatting,
-without regenerating canonical source. The same source bytes and workspace base
-retain reconnect identity across candidate UUID allocation. A formatting or path
-change produces a new identity. Dry-run uses the same authored hash and separately
-rehearses the complete canonical source round trip. A lowering mismatch can
-therefore surface on the next canonical pull; dry-run is the opt-in full
-source-to-record proof.
-
-When a transaction commits, its status response carries the first bounded result
-page. The CLI downloads further pages when needed and validates the full result
-count before advancing its base. Result application rechecks source bytes,
-managed binaries, and the workspace base before reusing local preparation; edits
-made while waiting trigger fresh analysis and the existing merge behavior.
-
-One accepted push atomically commits records, main-locale text, stored bindings,
-and staged file metadata under CAS. Pending durable IDs and source rewrites
-become real only after acceptance.
-
-## Conflicts and files
-
-Conflict resolution accepts LF, CRLF, and mixed line endings. It retains the
-selected source lines and their existing line endings. Choosing a deleted side
-removes the source file; deletion placeholders are display text, not authored
-source. Empty files and ordinary comment-only files remain files.
-
-Resolve source conflicts by editing the final intended source. Use
-`neo resolve --mine` or `neo resolve --theirs` only for a deliberate whole-side
-choice. Pull, inspect, dry-run, and retry; there is no force-CAS path.
-
-One record is one conflict, however many files declare it. A member declared by
-more than one class is marked in every declaring file, and `neo resolve`
-settles those files together; it refuses a record whose declarations are only
-partly resolved rather than settling the rest to the other side and leaving the
-declarations disagreeing.
-
-Compiled initializer IR is server-owned and does not participate in authored
-three-way merge decisions. Either `neo resolve` side adopts the server side as
-the new base for every conflict it settles — `--theirs` then reads clean, and
-`--mine` keeps the local text as an ordinary update on top of that base. That
-includes metadata-only conflict bookkeeping left by an older pull when no
-source marker exists; adopting the server base never overwrites tracked
-source.
-
-A `value-base-desync` error means the workspace base no longer names value
-rows its own file projection holds, so the plan would delete live server rows.
-Nothing is planned in that state; run `neo pull` and retry. The same message
-as a warning reports the inconsistency without blocking.
-
-When pull conflicts with a server-side deletion, keeping the authored record
-restores it as an explicit create guarded by an absent-record CAS check;
-removing it from the resolved source accepts the deletion without sending a
-write. Pull also warns immediately when a conflicted record's retained local
-base strands newly downloaded descendant value rows. Resolve that conflict
-with `neo resolve --mine` or `neo resolve --theirs` before pushing.
-
-For `base-hash-conflict`, pull and merge. For `version-bump-required`, inspect
-the classification and use `neo push --accept-bump` only when the bump is
-intended.
-
-Add, replace, or remove managed binaries and their typed registry declarations
-in tracked source. `neo push` stages their metadata and verified bytes with the
-source transaction. Keep local bytes during binary conflict resolution and
-inspect the server copy under `.neo/conflicts/files/<file-id>/`.
-
-## Localization operations
-
-Main-locale strings are authored in `.neo` and `.neoflow`, but those files do
-not represent the full localization record. Use `neo loc` for other locales,
-statuses, comments, archives, and targeted localization repair:
-
-```sh
-neo loc locales
-neo loc list
-neo loc set <textId> <locale> "text"
-neo loc status-set <textId> <locale> <statusId>
-neo loc comment-set <textId> <locale> "comment"
-neo loc archive <textId>
-neo loc restore <textId>
-```
-
-Pass a JSON-array batch on stdin or `--file` where supported. Localization
-commands do not rewrite local project source. Run `neo pull` after any
-`neo loc` or web mutation before further source edits or push.
-
-## Branches, releases, and history
-
-```sh
-neo branch list
-neo branch create <name> [--from <ref>]
-neo branch switch <nameOrId>
-neo branch refresh [--dry-run]
-neo merge <branch> [--dry-run] [--migrate]
-neo release cut [--bump major|minor|patch] [--dry-run]
-neo history inspect
-neo history log
-neo history prune [--project <id|@latest|@current>]
-neo history flatten [--project <id|@latest|@current>] --version <id|@latest|@current>
-neo history apply --plan <plan-id> [--confirm-scope <project-id>[/<version-id>]]
-neo history status --run <run-id>
-neo history resume --run <run-id>
-```
-
-Branch switching requires a clean working copy. Unpushed source or binary
-changes, unresolved conflicts, source errors, and pending push recovery stop the
-switch before it changes the selected version or baseline. Push or back up edits
-first; use `neo pull --force` only when discarding them is intended.
-
-Treat branches as copy-on-write forks and releases as immutable snapshots. The
-server derives the minimum compatibility bump; a caller may only raise it.
-Require the release login profile for release operations.
-Branch creation waits for the durable copy to publish before reporting success.
-The source stays readable while copying; the destination becomes readable only
-after verification and publication.
-
-History rewrites require project owner or admin authority. `prune` and
-`flatten` create immutable plans without deleting anything. `apply` starts the
-destructive run after the plan has sealed. Production also requires the exact
-scope confirmation shown by the plan. CLI
-tokens issued before 0.36.12 do not hold the history write grant, so run
-`neo logout` followed by `neo login` once after upgrading.
-
-## Authentication and automation
-
-```sh
-neo login [--api <url>] [--profile editor|release] [--save-project <id>]
-neo doctor
-```
-
-`login`, `whoami`, and `logout` use the current workspace's `apiBaseUrl` when
-run beneath a `neo.json`. An explicit `--api` takes priority. Outside a
-workspace, they use the CLI build's default API origin. Login prints the
-selected origin before it requests or stores a credential.
-
-`neo doctor` checks authoring contracts (format, compiler, extension cache, source,
-files) and the last pull's document integrity. Malformed records fail the command.
-The partition audit follows ownership: a lookup can reference a value stored in a
-different partition without moving it into the lookup's partition. The document
-audit also reports base rows no emitted file projects and no record names; these
-rows are invisible to `neo status`.
-`neo doctor --json` carries a `repair` entry per finding, which is what a
-targeted repair is handed instead of scanning a project to rediscover them.
-`neo doctor --fix` consumes those entries for the `unprojected-value-row`
-findings: it lists each orphan root with the number of rows it owns, confirms,
-then deletes them. Two guards make a stale audit fail the commit rather than
-delete a row that has since gained an owner: every row carries the CAS base the
-last pull recorded, and every transaction expects the version head the previous
-one produced, starting from the head that pull left. Adopting an orphan writes
-its new owner rather than the row itself, so only the head guard sees that, and
-a workspace with no recorded head is refused rather than written blind. More
-rows than one transaction budgets for go up in batches sized from the shared
-cost model against the immediate commit path. `--yes` answers the confirmation
-for scripted runs, and `--fix` has no `--json` form. No other finding kind has
-an automatic repair.
-
-The Node CLI talks directly to authenticated Convex APIs through the
-session-gated CAS boundary. Tokens use the OS credential store when available
-and a protected file only as fallback. Use `NEO_COMPOSE_TOKEN` or
-`--token-stdin` in CI. The CLI automatically re-mints its short-lived Convex
-JWT before expiry during long-running commands; the stored device session
-remains the credential. The editor profile cannot publish releases; server
-scopes remain the security boundary.
-
-`neo logout [--api <url>]` deletes the stored credential for exactly one API
-origin (keychain entry and credentials-file row) and revokes the server
-session best-effort. It never clears other origins or the whole store.
-
-Isolated environments (P53 agent rigs) set `NEO_COMPOSE_CONFIG_HOME` (an
-absolute directory replacing `$XDG_CONFIG_HOME/neo-compose` for Neo state
-only) and `NEO_COMPOSE_CREDENTIAL_NAMESPACE` (scopes the OS-keychain account)
-so concurrent environments sharing one OS user cannot read, overwrite, or
-delete each other's tokens. Login, logout, and authenticated commands all
-honor both variables.
-
-Boolean flags are switches: pass `--dry-run` or `--help` without a value.
-Values such as `--dry-run=true` are rejected before a command runs.
-`--dry-run` is supported by push, merge, refresh, branch refresh, release cut,
-and migrate run. Other commands reject it before taking action. Branch options
-are scoped to their subcommands; branch create does not support dry-run.
-
-Pass explicit project/version IDs and flags in automation. Prefer `--json` for
-machine-readable output and do not depend on interactive pickers or confirms.
-
-## Unity export
-
-`neo export` builds the Unity export from the working copy, offline, and writes
-it into the directories the Unity project's `NeoComposeConfig` asset names:
-`project.json` with a partition index, `Partitions/*.json` holding value rows
-by storage partition, localization files, and generated C# under
-`<generatedTypesDirectory>/Generated/`. It writes only files whose bytes
-changed, skips codegen when its schema inputs are unchanged, and writes
-`Library/NeoCompose/export.json` last for Unity to ingest. Exports remember
-recent results by their exact inputs, so a repeated export, an undo, or a revert
-to earlier content reuses that result after verifying output bytes; changed or
-missing outputs are regenerated. Edited content is validated
-even when C# generation is skipped. After a CLI code-generation fix, run
-`neo export` again; generator revision changes invalidate cached C# output.
-Generated animation clip targets and reference lookup factories retain constructed
-generic arguments, including supported forwarded bindings. Clip getters use the
-declared target type when the owner is a derived class. Export reports an error
-when a clip target does not match the owner or one of its constructed base types.
-Inherited collection interface getters preserve supported detached temporaries.
-Constructed entries such as `Frame<T>` use the interface's generic argument
-family for both their collection type and value converters.
-New instances that reuse existing member-localized text retain its shared ID
-and translations in the export.
-
-- A clean working copy exports the pulled head. Diagnostic location differences
-  alone, including line shifts after push inserts ids, do not make it local.
-  Local edits, `Files/` bytes
-  included, make the export local: `project.json` gets
-  `metadata.localExport`, Unity fails player builds and keeps saves under
-  `NeoCompose/LocalExport`, and a push or a clean export ends it.
-- Ids minted for local declarations are kept in `.neo/export.json`'s
-  `identityLedger`, so the push commits the ids Unity already saw. A push
-  re-exports into the Unity project a local export went to.
-- `neo dev` watches before its initial export and batches relevant source,
-  binary, ignore-rule, workspace-state, and config changes. It waits for a
-  20 ms quiet period, capped at 250 ms, and processes edits made during an
-  export in the next batch. It never pulls or pushes.
-- Pull, push, branch, merge, resolve, init and export take turns through
-  `.neo/workspace.lock`; a lock whose process died is taken over.
-
-- The Unity project comes from `unityConfigPath`. Without it, an interactive
-  export offers to link the one config asset naming this project; scripts get
-  an error with the line to add.
-- `--unity-project <dir>` exports into another Unity project without linking
-  it. Agent rigs use it.
-- A source error, a file conflict, a `download` file action, an error
-  diagnostic, or an unchanged project file whose bytes differ from the pulled
-  file stops the export before anything is written.
-- `NeoGeneratedFiles.json` keeps `.meta` GUIDs across type renames. Keep it
-  with the generated files.
-
-## Push timing diagnostics
-
-Set `NEO_COMPOSE_TRACE_PERFORMANCE=1` when measuring a push. It writes
-`neo-performance` JSON lines to stderr for workspace loading, local candidate
-preparation, file uploads, submission, authentication, live transaction completion,
-result download, and local result application. `startedMs` is relative to the
-CLI process and `durationMs` covers the named operation. Nested spans overlap;
-do not add all durations. Normal command JSON remains on stdout.
-
-Each command opens one Convex websocket, authenticated with the scoped
-session's refreshing JWT, and runs every query, mutation, and subscription over
-it. Push sends compressed JSON through `clientCommits.commit` when the request
-has no staged files and decodes to at most 512 KiB; otherwise it streams chunks
-through `begin`, `appendChunks`, and `seal`, and subscribes to completion. The
-CLI pins the deployment through the authenticated app origin before sending it
-a session token.
-Results pin the workspace to that transaction's hash, so a concurrent later commit still
-requires a pull before another push.
-
-## Test execution
-
-`neo test` compiles unpushed production source and validates the candidate graph.
-It does not perform the additional source serialization round trip that
-`neo push --dry-run` uses. Invalid production source still stops test execution.
-Unchanged project and spec inputs reuse content-addressed local caches.
-
-Spec files run in parallel using up to four available CPU workers. Set
-`test.maxWorkers` in `neo.json`, override it with `neo test --maxWorkers <n>`,
-or use `neo test --runInBand` to run serially. Each file preserves hook and test
-order; fixtures and mocks stay isolated. Reports retain discovery order.
-Parallel test work is summed across workers and can exceed elapsed execution;
-JSON `timings.executeMs` and `timings.workerStartupMs` give elapsed phase times.