@uru-intelligence/cli 0.3.61 → 0.4.12

package/CHANGELOG.md

@@ -0,0 +1,69 @@
+# Uru CLI changelog
+
+> Generated from `changes/cli/*.json`. Do not edit release rows by hand.
+
+## Unreleased
+
+### Breaking
+
+- gem.validate and gem.build return a hosted job id immediately. Pass --wait to poll gem.build_job until the compile settles. — surfaces: cli, docs; reference: skills/uru-gems/SKILL.md
+  - Action: Update agents and scripts that expected a compiler result from uru gems validate or uru gems build. Print or store hosted_job_id, then poll gem.build_job, or pass --wait.
+
+### Security
+
+- Bind npm publication to an attested candidate tarball and require the published cli_pin matrix before release success. — surfaces: cli, release; reference: docs/plans/cli-sdk-native-release-modernization/PLAN.md
+  - Action: Release operators must supply the exact candidate run, attempt, release-evidence artifact ID, and MCP commit to the protected publish workflow.
+- Stop uru mcp config and install from printing or writing a live API token. Generated MCP config now points at the URU_API_KEY environment variable. — surfaces: cli; reference: apps/cli/src/local-commands.ts
+  - Action: Set URU_API_KEY in the MCP client environment. uru mcp config no longer embeds the current CLI token.
+
+### Added
+
+- Add `uru link --verify` for local link diagnostics and `uru gems links create --verify` to run browser verification after link creation. — surfaces: cli, docs; reference: apps/cli/src/workspace-commands.ts
+  - Action: Use `uru link --verify` to confirm `.uru/project.json` and the remote Gem still resolve before source work. After `uru gems links create`, add `--verify` to run `gem.browser_verify` on the new Link's Gem.
+- Add a side-effect-free internal CLI library entrypoint with a typed whoami foundation. _(internal)_ — surfaces: cli, sdk; reference: docs/plans/cli-sdk-native-release-modernization/DECISION_RECORDS.md
+  - Action: Programmatic callers must pass an explicit token and workspace; no public SDK compatibility promise is introduced.
+- Add direct CLI access to Home pins and Focus rules from the shared operation registry. — surfaces: cli, docs; reference: content/docs/home.mdx
+  - Action: Use uru home <operation> --params-json '{...}' or the matching home.* operation ID.
+- Add first-class CLI verbs for Gem filesystem, deploy, build diagnostics, components, page verify, public-tool delegations, and bindings. — surfaces: cli, docs; reference: docs/reference/uru-cli-mcp-operations.md
+  - Action: Use uru gems fs, uru gems deploy, uru gems build logs|inspect, uru gems verify, uru gems components, uru gems delegations, and uru gems bindings. These wrap existing gem.* operations.
+- Add first-class Dataset list/history/jobs/inspect verbs and a uru distribution group for the 17 collection operations. — surfaces: cli, docs; reference: content/docs/guides/cli.mdx
+  - Action: Use uru datasets ls|inspect|history|jobs and uru distribution list|get|create|update. Dataset SQL stays uru datasets sql. DATA-008 export/typegen is not added.
+- Add first-class Library upload, patch-preview, and favorite verbs, plus automations validate, delete, graph-patch, triggers, connections, and update. — surfaces: cli, docs; reference: docs/reference/uru-cli-mcp-operations.md
+  - Action: Use uru library upload|patch-preview|favorite and uru automations validate|delete|graph-patch|triggers|connections|update instead of operations run for those catalog ids. library write --create now accepts --folder-id.
+- Add first-class uru gems bindings and uru gems api commands so tool-call source and connection bindings stay separate. — surfaces: cli; reference: apps/cli/src/gem-lifecycle-resource-commands.ts
+  - Action: Use uru gems bindings list|upsert|resolve to attach connections, and uru gems api describe|query|action|job to run declared Gem capabilities. Do not put connection ids in Gem source.
+- Add MCP list/target commands, auth status, text-mode list tables, and regenerate the full CLI/MCP operations reference. — surfaces: cli, docs; reference: docs/reference/uru-cli-mcp-operations.md
+  - Action: Use uru mcp list, uru auth status, and uru docs search. List commands print tables in text mode; --json stays JSON. Prefer ${URU_API_KEY} in generated MCP config.
+- Add TTY visual chrome for help, tables, doctor, and login without changing JSON or pipe output. — surfaces: cli; reference: apps/cli/src/visual.ts
+  - Action: No action is required. Color and box drawing appear only on a color TTY. Use --no-color, CI, or a pipe to keep the previous plain text.
+- Add uru tools inspect and uru operations inspect, and accept --params-json @file or @- for large tool parameters. — surfaces: cli; reference: apps/cli/src/command-spec.ts
+  - Action: Use uru tools inspect <name> or uru operations inspect <operation-id> to print a contract. Pass --params-json @path.json or --params-json @- to load parameters from a file or stdin.
+- Make uru update compare this CLI to the latest npm version and add --check --json. — surfaces: cli; reference: apps/cli/src/update-check.ts
+  - Action: No action is required. uru update never installs itself. Run uru update --check --json for machine output, or npm install -g @uru-intelligence/cli@latest to install.
+
+### Changed
+
+- `uru logs --follow` streams Gem runtime logs over SSE for up to 30 minutes and falls back to polling when the stream route is missing. — surfaces: cli; reference: apps/cli/src/gem-lifecycle-commands.ts
+  - Action: No action is required. `--follow-duration-ms` now accepts up to 30 minutes (was 5).
+
+### Fixed
+
+- JSON output for destructive CLI operations refused without `--yes` now includes `confirmationRequired: true` and a copy-paste `suggestedCommand` with `--yes` appended. — surfaces: cli; reference: apps/cli/src/cli-runtime.ts
+  - Action: No action is required. Agents and scripts can read `suggestedCommand` from JSON errors instead of guessing the confirmation flag.
+- Keep the CLI login when you switch workspace. A leftover workspace from a previous switch no longer poisons the next login. `uru switch` marks the current workspace in the list. — surfaces: cli; reference: apps/cli/src/oauth-credential.ts
+  - Action: No action is required. After you switch workspace, the next command keeps the same login. A new login writes only the workspace the login response selected.
+- Recover from a revoked CLI session without reusing the dead JWT. When the API returns `session_revoked`, the CLI now rotates the stored OAuth login once or clears it instead of sending the revoked token until local expiry. — surfaces: cli; reference: apps/cli/src/cli.ts
+  - Action: No action is required. Failures of this class now carry the `session_revoked` error code so they can be distinguished from a generic `auth_required` response.
+- Report a non-JSON API response as what it is. A proxy or firewall that answers with an HTML page now produces the HTTP status and content type instead of `Unexpected token '<', "<!DOCTYPE "... is not valid JSON`. — surfaces: cli; reference: apps/cli/src/client.ts
+  - Action: No action is required. Failures of this class now carry the `non_json_response` error code, keep the auth exit code on a 401, and print a tip naming the likely cause.
+- Report what a rejected credential actually means: `uru doctor` now runs a read-only data call instead of trusting `uru whoami`, API error envelopes are read in full, and auth advice follows where the token came from. — surfaces: cli; reference: apps/cli/src/doctor.ts
+  - Action: No action is required. `uru doctor` gains a `data access` check and fails when a credential validates but cannot execute tools; a token supplied through `--token` or `URU_TOKEN` is no longer told to run `uru login`.
+- Send scope on uru automations create, honor --output/--json on uru tools run, and keep errorId plus httpStatus on JSON errors. — surfaces: cli; reference: apps/cli/src/local-commands.ts
+  - Action: uru automations create now sends scope=workspace by default. Pass --scope personal when creating a personal automation. JSON errors include errorId and httpStatus when the API provides them.
+- Use the shared SemVer contract when deciding whether to show a CLI update notice. — surfaces: cli, release; reference: docs/plans/cli-sdk-native-release-modernization/PLAN.md
+  - Action: No action is required; prerelease and malformed registry versions now follow the same validation and ordering rules as release publication.
+
+### Internal
+
+- Retain an executable compatibility probe for the paused Stricli migration decision. _(internal)_ — surfaces: cli; reference: docs/plans/cli-sdk-native-release-modernization/DECISION_RECORDS.md
+  - Action: Do not adopt Stricli until a pinned upstream release passes this probe and the required seven-slice hard-cut proof.

package/README.md

@@ -46,7 +46,7 @@ bun src/index.ts gems versions diff 'library/Golden Gems/My Gem.gem' 13 14
 bun src/index.ts gems versions restore 'library/Golden Gems/My Gem.gem' 12
 bun src/index.ts gems releases create 'library/Golden Gems/My Gem.gem' 14
 bun src/index.ts gems releases list 'library/Golden Gems/My Gem.gem'
-bun src/index.ts gems links create 'library/Golden Gems/My Gem.gem' --name Client --version 14
+bun src/index.ts gems links create 'library/Golden Gems/My Gem.gem' --name Client --pin --version 14
 bun src/index.ts gems links set-version 'library/Golden Gems/My Gem.gem' <link-id> 14
 bun src/index.ts gems runs list 'library/Golden Gems/My Gem.gem'
 bun src/index.ts gems runs show 'library/Golden Gems/My Gem.gem' <run-id>
@@ -61,30 +61,47 @@ bun src/index.ts library search revenue
 bun src/index.ts library mkdir 'library/Golden Gems'
 bun src/index.ts library read 'library/Contexts/Client Brief.md'
 bun src/index.ts library write 'library/Contexts/Client Brief.md' --file ./brief.md --create
-bun src/index.ts library write 'library/Prompts/Sales Email.md' --content "Draft the follow-up." --create
+bun src/index.ts library write 'library/Prompts/Sales Email.md' --content "Draft the follow-up." --create --folder-id <folder-id>
+bun src/index.ts library patch-preview 'library/Prompts/Sales Email.md' --content "*** Begin Patch\n..."
+bun src/index.ts library favorite 'library/Contexts/Client Brief.md'
+bun src/index.ts library upload 'library/Assets/logo.png' --file ./logo.png
+bun src/index.ts library upload complete --upload-id <id> --bucket <bucket> --object-path <path> --filename logo.png --size-bytes 1024
 bun src/index.ts library patch 'library/Prompts/Sales Email.md' --stdin
 bun src/index.ts library cp 'library/Notes/Brief.md' 'library/Archive/Brief.md'
 bun src/index.ts library mv 'library/Notes/Draft.md' 'library/Notes/Final.md'
 bun src/index.ts library rm 'library/Notes/Old.md'
 bun src/index.ts library restore 'library/Notes/Old.md'
+bun src/index.ts datasets ls --limit 50 --json
 bun src/index.ts datasets query revenue_rows --limit 50 --response-format concise --json
-bun src/index.ts library ls --params-json '{"path":"library","resource_type":"dataset"}'
-# Copy the exact resourceSlug from Library discovery; never infer it from name.
-bun src/index.ts datasets get --params-json '{"dataset_id":"revenue-rows"}'
-bun src/index.ts datasets rows-upsert --params-json '{"dataset_id":"revenue-rows","rows":[{"name":"Acme"}]}'
-bun src/index.ts datasets manage-create --params-json '{"title":"Revenue Rows","data_schema":{"properties":[]}}'
+# Registry-family commands accept canonical camelCase fields and adapt them at
+# the tool-protocol boundary.
+bun src/index.ts datasets get revenue-rows
+bun src/index.ts datasets history revenue-rows --limit 20
+bun src/index.ts datasets jobs revenue-rows --limit 20
+bun src/index.ts datasets rows --params-json '{"op":"upsert","datasetId":"revenue-rows","rows":[{"name":"Acme"}]}'
+bun src/index.ts datasets create --params-json '{"title":"Revenue Rows","properties":[{"clientKey":"name","name":"Name","type":"title","required":true,"nullable":false,"position":0,"config":{}}]}'
+bun src/index.ts datasets sql --params-json '{"sql":"SELECT 1"}'
+bun src/index.ts distribution list --limit 20
+bun src/index.ts distribution get <collection-id>
+bun src/index.ts distribution create "Client pack" --scope workspace
 
 # Automation helpers over the platform tool surface.
-bun src/index.ts automations ls --status active --view summary
+bun src/index.ts automations ls --limit 100
 bun src/index.ts automations get <automation-id>
 bun src/index.ts automations create "Daily revenue digest" --status draft
+bun src/index.ts automations update <automation-id> --description "Nightly digest"
 bun src/index.ts automations enable <automation-id>
+bun src/index.ts automations validate <automation-id> --mode structural --graph-json '{}'
+bun src/index.ts automations graph-patch <automation-id> --patch-json '{"ops":[]}'
+bun src/index.ts automations triggers list <automation-id>
+bun src/index.ts automations connections list
+bun src/index.ts automations delete <automation-id> --yes
 bun src/index.ts automations trigger <automation-id> --input-message "Run now"
 bun src/index.ts automations runs ls <automation-id> --scope workspace --limit 20
 bun src/index.ts automations runs tail <run-id> --level warn
 bun src/index.ts automations runs cancel <run-id> --yes
 
-# Raw platform-tool escape hatch for diagnostics and parity.
+# Raw platform-tool escape hatch for diagnostics and low-level operations.
 bun src/index.ts tools ls
 bun src/index.ts tools schema gem_control_plane --json
 bun src/index.ts tools run gem_control_plane --params-json '{"op":"inspect","path":"library/Golden Gems/My Gem.gem"}'
@@ -95,16 +112,27 @@ bun src/index.ts operations ls --family automations
 bun src/index.ts operations run gem.inspect --params-json '{"path":"library/Golden Gems/My Gem.gem"}'
 bun src/index.ts library search "client brief"
 bun src/index.ts docs library_fs
+bun src/index.ts docs search library_fs
 bun src/index.ts api platform/tools/search_tools/execute -F query=gem
+bun src/index.ts api /api/platform/tools/search_tools/execute -F query=gem
 
-# MCP client config helper. Prefer a scoped API key for real installs.
+# MCP client config helper. Prefer ${URU_API_KEY} or --api-key. List never prints keys.
+bun src/index.ts mcp list
+bun src/index.ts mcp list --target cursor
 bun src/index.ts mcp config --api-key "$URU_API_KEY"
+bun src/index.ts mcp install --target cursor
 bun src/index.ts mcp install --path ~/.config/claude-code/mcp.json --api-key "$URU_API_KEY"
+bun src/index.ts mcp remove --target cursor
+
+# Local auth facts. Never prints a JWT.
+bun src/index.ts auth status --json
+bun src/index.ts doctor --json
 
 # Local shell integration.
 bun src/index.ts complete bash
 bun src/index.ts complete zsh
 bun src/index.ts complete fish
+bun src/index.ts complete powershell
 ```
 
 Generated MCP configs use non-interactive `npx -y` and pin
@@ -140,7 +168,7 @@ explicit token/API-key paths:
 - `uru login --token ...` stores the token in OS credential storage when available: macOS Keychain, Linux `secret-tool`/libsecret, or Windows Credential Manager via PowerShell
 - `uru login --token ... --insecure-storage` is the explicit plaintext fallback
 - Linux token storage requires `secret-tool` (often installed as `libsecret-tools`); Windows token storage requires PowerShell access to Credential Manager. If the OS store is unavailable, login fails closed with an actionable `--insecure-storage` fallback message.
-- browser/device credentials renew within five minutes of session expiry and when switching workspaces
+- browser/device credentials renew within five minutes of session expiry. A workspace switch is request scope and does not rotate the login.
 - interactive commands with missing or expired stored auth start browser login and then retry the command without printing login success text to stdout
 - `--no-input` disables implicit login and exits `4` when authentication is missing
 - `uru logout` invalidates the current CLI session, revokes the renewable OAuth credential, and clears local auth state
@@ -150,6 +178,9 @@ explicit token/API-key paths:
 - config file permissions: `0600`
 - linked project state: `.uru/project.json` with `{workspaceId, gemId, libraryPath}`
 - no credentials are written to `.uru/project.json`
+- `uru auth status` reports logged-in / workspace / storage / expiry and never prints a JWT. `uru whoami` stays a server identity call.
+- `uru switch` sets the local default workspace. `uru link` binds this directory to one Gem. `--workspace` / `URU_WORKSPACE_ID` override one invocation.
+- The screen says Agent; Library paths and schemas say persona (`library/Agents/Name.persona.md`).
 - Gem-scoped deploy tokens for CI use `uru tokens create|ls|revoke`
     - `uru tokens create` requires `--name` plus exactly one lifetime flag:
       `--expiry <duration>` or `--expires-at <iso timestamp>`
@@ -162,6 +193,21 @@ explicit token/API-key paths:
   file
 - `uru env run -- <cmd>` overlays local values and redacts all non-empty values from captured output
 
+## CI cookbook
+
+Use a Gem-scoped token, never a session JWT, and fail closed:
+
+```bash
+uru tokens create 'library/Golden Gems/My Gem.gem' --name CI --expiry 30d --json
+export URU_TOKEN=<token-from-create-once>
+export URU_WORKSPACE_ID=<workspace-id>
+uru --no-input doctor --json
+uru --no-input auth status --json
+uru --no-input whoami --json
+```
+
+`--no-input` exits instead of opening a browser. `auth status` and `doctor` warn if the token lives in `--insecure-storage` and do not print the token. `env pull` writes names only; it does not download secret values.
+
 ## Install shape
 
 The package name is `@uru-intelligence/cli`; the installed binary is still `uru`:
@@ -178,6 +224,17 @@ For one-off usage:
 printf '%s' "$URU_TOKEN" | npx @uru-intelligence/cli whoami --token-stdin --json
 ```
 
+The package root is a side-effect-free library entry. It does not execute a
+command, read local CLI configuration, install signal handlers, write output,
+or start network activity on import. The package currently exposes only the
+fail-closed internal `createUruClient` foundation: callers must supply a token
+and an explicit workspace, every call accepts cancellation, and it validates
+the authenticated workspace before returning a typed result. DG-1 has not
+accepted a public high-level SDK compatibility promise, so no broader SDK or
+raw API surface is implied by this export. The executable remains the `uru`
+binary; `@uru-intelligence/cli/cli` is an explicit executable subpath for
+packaging tools, not an SDK API.
+
 ## Release validation
 
 Before publishing, run the full local CLI gate and the staging CLI/MCP smoke with a staging-scoped token. The smoke reads credentials from env or macOS Keychain and never prints the token. To avoid putting a token in shell history, store it as `uru_staging_smoke_token` with `security add-generic-password -a "$USER" -s uru_staging_smoke_token -w '<token>' -U`.
@@ -191,14 +248,47 @@ URU_CLI_MCP_STAGING_SMOKE_TARGET=staging \
 ```
 
 Publish the scoped CLI only through the **Publish Uru CLI to npm** workflow on
-`main`. It first verifies that the exact pinned `uru-mcp` release exists, runs
-release validation, publishes through npm trusted publishing from a
-GitHub-hosted runner in the protected `production` environment, and then
-requires a separate live-registry job to verify the exact published version.
-The registry smoke intentionally runs `npm exec` from a clean OS temporary
-directory so the monorepo workspace cannot shadow the published package. The
-source repository is private, so npm OIDC authenticates the publish without a
-long-lived token but cannot emit a public provenance attestation.
+`main`. A release request must identify the candidate certification workflow
+run ID, attempt, and exact retained bundle artifact ID; the publisher never
+selects `latest` evidence. Before it reads the release record, it verifies the
+candidate's GitHub DSSE/in-toto artifact attestations for both the canonical
+release record and the exact `uru_cli.tgz`, pins the builder repository,
+candidate workflow path, development ref policy, run/attempt, predicate type,
+and source-bundle identity, then recomputes the build-input inventory at
+`main`.
+
+The workflow publishes that retained tarball from a sterile private temporary
+directory with `npm publish --ignore-scripts`; it never rebuilds, repacks, or
+rewrites it. npm trusted publishing runs only from the protected `production`
+environment. The registry smoke compares npm `dist.integrity` to the certified
+SRI and runs `npm exec` from a clean OS temporary directory so the monorepo
+workspace cannot shadow the published package. It then invokes the complete
+published `cli_pin` certification matrix for both staging and production. A
+value-free publication-state artifact records the observed npm SRI even when a
+publish response or a later gate fails. Re-dispatching the same immutable
+candidate selector resumes only when npm already serves that exact certified
+SRI; it then repeats the registry and published-matrix proof before evidence,
+tag, or GitHub release creation. A different SRI fails closed. A changed source
+or failed certification needs a higher-version forward fix; no npm version is
+ever rewritten.
+
+The workflow requires the immutable, no-bypass CLI tag policy before npm
+publication and revalidates it before tag creation. GitHub hides a ruleset's
+bypass actors from an ordinary workflow token, so the two policy-check steps
+mint a short-lived, repository-scoped GitHub App token solely to inspect that
+property. The App's client ID is the `production` environment variable
+`CLI_RULESET_AUDIT_APP_CLIENT_ID`; its private key is the matching
+`CLI_RULESET_AUDIT_APP_PRIVATE_KEY` environment secret. Its administration
+write grant is required for visibility only and is never available to the npm
+publication step or the tag/release creation step. Only after published evidence
+is retained does the workflow create the annotated
+`uru-cli-vX.Y.Z` tag at the exact dispatched `main` commit and a GitHub release
+with generated notes. The final job verifies an existing tag is annotated and
+points to that same commit before it can resume an interrupted GitHub-release
+request; it never changes the npm package, repoints a tag, or treats a draft or
+prerelease as success. Before the first use, repository policy must contain an
+active, no-bypass `refs/tags/uru-cli-v*` rule that blocks both updates and
+deletions; the workflow queries and requires it before creating the tag.
 
 ```bash
 bun --filter=@uru-intelligence/cli run smoke:registry