needle-cloud 2.9.0 → 2.10.0-rc.1791986367.11d2809

package/CHANGELOG.md

@@ -4,6 +4,30 @@ 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
+- `label list` and `label set` to inspect labels, promote a completed version, create custom labels, or roll back, with JSON output and token/team support.
+- `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
+- Failed SDK label updates no longer print a success message; strict callers receive the HTTP failure details.
+- 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
@@ -50,6 +95,44 @@ Deleting content immediately frees total storage capacity, but it does not refun
 the current month's upload usage. Deleted content can be restored from Trash for
 31 days when the account has enough total storage available for it.
 
+## Content labels
+
+Labels keep a stable URL while you change the version it serves:
+
+```bash
+npx needle-cloud label list <content-id> --team "My Team"
+
+# Promote the source version currently served by latest
+npx needle-cloud label set <content-id> main --from latest
+
+# Move a label to an explicit completed version, including an older version
+npx needle-cloud label set <content-id> main --version <version-id>
+
+# Create or move a custom label and return the result as JSON
+npx needle-cloud label set <content-id> staging --from latest --format json
+```
+
+`label set` requires exactly one of `--version` or `--from`. The selected version
+must belong to this content item and have completed processing. The server also
+moves the label for related completed outputs. `latest` updates automatically;
+it can be used with `--from` but cannot be assigned manually. New label names use
+lowercase letters, numbers, hyphens or underscores.
+
+Both commands support `--token`, `NEEDLE_CLOUD_TOKEN`, saved login, `--team`, and
+`--format cli|json`. Listing requires read access; setting also requires write
+access. Use the content ID and version ID returned by upload, or the IDs shown by
+`list` and `label list`.
+
+JSON lists each label's `sourceVersionIds` and `targets`. Each target includes
+`versionId`, `sourceVersionId`, `displayName` and `url`, so source and derived
+outputs remain distinguishable. A null or hidden URL is retained as returned by
+Cloud. Setting returns `contentId`, `label`, the selected `versionId`, observed
+`previousVersionIds`, and the confirmed `targets`. The previous state is a
+snapshot; concurrent updates are not locked. If the update succeeds but cannot
+be confirmed afterward, the command reports that explicitly and exits nonzero.
+
+Diagnostics go to stderr; stdout contains only the requested result.
+
 ## Local tools in Needle Cloud AI
 
 [Needle Cloud AI](https://cloud.needle.tools/team#ai) can use local tools provided by this CLI to read project files, search your code, and inspect logs. You can enable or disable local tools in an individual chat. See the [Needle Cloud AI documentation](https://engine.needle.tools/docs/cloud/#needle-cloud-ai) for how this works with your Unity or Blender project.
@@ -93,6 +176,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 command actions.
+if (process.argv[2] === 'upload' || process.argv[2] === 'optimize' || process.argv[2] === 'label') {
+    globalThis.console = new Console({stdout:process.stderr,stderr:process.stderr});
+}
+const { program } = await import('../dist/cli.esm.js');
+program.run();