needle-cloud 2.9.0 → 2.10.0-rc.1791984447.e5bbdaf

package/CHANGELOG.md

@@ -4,6 +4,28 @@ All notable changes to this package will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
+## [2.10.0] - 2026-10-14
+### Added
+- `upload --wait` to wait for a selected optimized asset and optionally download it with `--outdir`.
+- `--format json`, `--format source-url`, and `--format edit-url` on upload and optimize commands, with pinned source identities and separately labeled optimized URLs.
+- `mcp` stdio support that starts or reuses the shared local server and keeps browser/Inspector tools available through the bridge.
+- `status` to inspect the local server, port and process ID.
+- Runtime snapshot read helpers in the browser SDK.
+
+### Changed
+- Upload and optimize use one workflow; optimize remains compatible shorthand for upload with waiting enabled.
+- Upload progress and diagnostics go to stderr so structured and scalar output can be used reliably in scripts.
+- Grouped directory uploads return a source-file URL list in JSON; source-url output requires a single file.
+- Local file tools enforce project boundaries, refuse sensitive files and hard-link aliases, and redact recognizable secrets before reads, searches and previews.
+- Local MCP requests validate loopback hosts and browser origins; the stdio bridge attaches local credentials automatically.
+
+### Fixed
+- Healthy idle MCP notification streams no longer repeatedly disconnect and reconnect.
+- MCP agent names are preserved through the stdio bridge.
+- Upload and optimize accept environment access tokens without requiring an interactive login.
+- `--progressive false` is respected when selecting an optimization variant.
+- Development SDK sign-in callbacks work with local authentication tunnels.
+
 ## [2.9.0] - 2026-10-01
 ### Added
 - Approved local project commands for creating Needle projects, installing packages, building, and deploying from Cloud chat.

package/README.md

@@ -35,6 +35,51 @@ npx needle-cloud help <command>    # Help for a specific command
 - `start` — Start the local server for licensing, editor integrations, and MCP tools
 - `settings` — View CLI settings, including [local tool access for Needle Cloud AI](#local-tools-in-needle-cloud-ai)
 
+## Upload assets
+
+```bash
+# Upload the source; processing continues in the background
+npx needle-cloud upload ./model.glb --team "My Team"
+
+# Print only the URL for this exact uploaded source file
+npx needle-cloud upload ./model.glb --format source-url
+
+# Return source identity and links as JSON
+npx needle-cloud upload ./models --format json
+
+# Wait for optimization and download the result
+npx needle-cloud upload ./model.glb --wait --outdir ./optimized
+
+# Existing scripts continue to work
+npx needle-cloud optimize ./model.glb --outdir ./optimized
+```
+
+Use `--no-optimize` to upload without requesting processing. `--wait` selects the
+optimized variant with `--progressive true|false` and `--usecase product|world`.
+The latter options and `--outdir` require waiting. `optimize` always waits.
+
+Both commands support `--format cli` (default), `json`, `source-url`, and
+`edit-url`. Progress and diagnostics, including `--verbose` output, go to stderr;
+stdout contains only the selected result. Errors produce a nonzero exit code.
+Authentication supports saved login, `--token`, or `NEEDLE_CLOUD_TOKEN`; `--team`
+selects the team for saved-login uploads. Access tokens retain their team scope.
+
+JSON contains `assetId`, `versionId`, `editUrl`, `sourceUrl`, `optimizedUrl`,
+`processingStatus`, and `files`. Source URLs are pinned to the uploaded version;
+optimization never changes `versionId` or the source links. After waiting,
+`optimizedUrl` is pinned to the selected optimization and `optimization` describes
+its version, progressive setting and use case.
+
+Folders are collected recursively into one grouped upload, preserving current
+behavior. The JSON `files` array contains a path and source URL for every uploaded
+file. `sourceUrl` is null for a multi-file upload; `--format source-url` refuses
+multiple files before uploading. `edit-url` returns the group's management URL.
+
+Without waiting, `processingStatus` is `unknown`: background processing is not
+queried. `--no-optimize` reports `not_requested` for this invocation; it does not
+cancel processing from earlier uploads. Waiting reports `completed` for the
+requested variant, which can differ from other background processing jobs.
+
 Manage stored content by using the identifier shown by `list`:
 
 ```bash
@@ -93,6 +138,30 @@ npx needle-cloud settings local-project-commands false
 
 Both settings are enabled by default, but Needle Cloud chat still asks for approval before it edits a file or starts a project command. A Cloud approval cannot override a disabled local setting. Pass `true` to either command to turn that capability back on. Project commands cover creating a Needle project, installing packages, running its build or dev script, and deploying an existing build. These commands can run project or package scripts; a deployment publishes files to the selected team. `needle-cloud settings` shows the current values.
 
+To find the local server's version and process ID (for example, in Task Manager):
+
+```bash
+npx needle-cloud status
+```
+
+This only checks the running server. It does not start or restart it. For older
+servers, a PID read from the local server record is labeled `recorded`.
+
+For AI clients that support stdio, use:
+
+```toml
+[mcp_servers.needle]
+command = "npx"
+args = ["-y", "needle-cloud", "mcp"]
+```
+
+On Windows, use `npx.cmd` if your client cannot resolve `npx`.
+The command reuses or starts the local server, exposes its tools over stdio,
+and reconnects if that server restarts. Inspector and Unity tools appear as
+those apps connect. Closing the AI client stops its stdio process; the shared
+local server stays available to other apps. Cloud access follows your
+`remote-ai-tools` setting and requires a signed-in account.
+
 See the [Needle MCP documentation](https://engine.needle.tools/docs/ai/needle-mcp-server) for available tools and how to connect other AI assistants.
 
 ## CI/CD

package/bin/cli.js

@@ -1,3 +1,9 @@
 #!/usr/bin/env node
-import { program } from '../dist/cli.esm.js';
-program.run();
+import { Console } from 'node:console';
+// Configure diagnostics before loading the bundle, including SDK/startup logs.
+// Result output uses process.stdout.write explicitly in the upload action.
+if (process.argv[2] === 'upload' || process.argv[2] === 'optimize') {
+    globalThis.console = new Console({stdout:process.stderr,stderr:process.stderr});
+}
+const { program } = await import('../dist/cli.esm.js');
+program.run();