Feat/api command

[gu-stav]

Description

Note

Related to https://docs.google.com/document/d/1gcakkHcmTFI36RBTN6MoNNfgUz3PJIHIujQXYF5NSu4/edit?tab=t.0

What to review

Testing

[claude]

Claude finished @gu-stav's task in 3m 15s —— View job

---

Review

• Gather context and understand the PR
• Read changed files
• Check for changeset
• Post review feedback

---

Missing changeset

No .changeset/*.md file was included. This PR adds two new user-facing CLI commands (sanity api list, sanity api spec) and deprecation forwarders for the old openapi commands — that's a runtime behavior change requiring a minor bump changeset. Fix this →

---

parser.ts:388 — asObject(schema.properties).constructor === Object is always true

asObject() always returns a plain object (either the cast value or {}), so {}.constructor === Object is always true. This silently swallows the else if (type === 'array') branch — it is dead code.

// parser.ts lines 388–395
if (asString(schema.type) === 'object' || asObject(schema.properties).constructor === Object) {
  field.fields = walkProperties(schema)
} else if (asString(schema.type) === 'array') {  // ← never reached
  const items = asObject(schema.items)
  if (asString(items.type) === 'object' || asObject(items.properties).constructor === Object) {
    field.fields = walkProperties(items)           // ← never executes
  }
}

Effect: request body fields whose schema is type: array with object items never have their child fields walked. field.fields is set by calling walkProperties(schema) (the array schema itself, which has no properties), returning []. The same pattern appears in the nested check on line 392.

Fix: replace the constructor check with an explicit properties presence check:

if (asString(schema.type) === 'object' || Object.keys(asObject(schema.properties)).length > 0) {

No existing test covers array-of-object body fields, which is why this slipped through. Fix this →

---

views.ts:330–333 — formatValue has a dead conditional branch

Both branches of the if do the same thing:

// views.ts lines 330–333
function formatValue(value: unknown): string {
  if (typeof value === 'string') return JSON.stringify(value)
  return JSON.stringify(value)  // same call
}

The string-specific branch does nothing different. Collapse to a single return JSON.stringify(value). Fix this →

---

spec.test.ts — --schema flag has no tests

The --schema path in spec.ts:88–161 (schema lookup and error case) has no coverage:

• sanity api spec jobs --schema SomeName → prints YAML
• sanity api spec jobs --schema SomeName --format=json → prints JSON
• sanity api spec jobs --schema Unknown → errors and lists known schemas

This is one of the feature's key workflows (resolving $ref pointers for agent use). Fix this →

---

cache.ts:50,59 — user-supplied slug used unvalidated in file paths

readSpec(slug) and writeSpec(slug, yaml) construct file paths by embedding the slug directly:

// cache.ts line 51
const file = path.join(getCacheDir(), 'specs', `${slug}.yaml`)

path.join does not block traversal sequences. A slug like ../foo resolves to a path outside the specs/ directory. The write path is mitigated because writeSpec is only called with the server-returned slug (from revalidateSpecs), but readSpec is called with the user-provided slug in spec.ts:119. Consider normalizing with path.basename(slug) or rejecting slugs containing / or ... Fix this →

[github-actions]

📦 Bundle Stats — @sanity/cli

Compared against main (cc636d1f)

@sanity/cli

Metric	Value	vs main (cc636d1)
Internal (raw)	2.1 KB	-
Internal (gzip)	799 B	-
Bundled (raw)	10.97 MB	-
Bundled (gzip)	2.06 MB	-
Import time	820ms	+1ms, +0.1%

bin:sanity

Metric	Value	vs main (cc636d1)
Internal (raw)	975 B	-
Internal (gzip)	460 B	-
Bundled (raw)	9.84 MB	-
Bundled (gzip)	1.77 MB	-
Import time	1.96s	-6ms, -0.3%

🗺️ View treemap · Artifacts

Details

• Import time regressions over 10% are flagged with ⚠️
• Sizes shown as raw / gzip 🗜️. Internal bytes = own code only. Total bytes = with all dependencies. Import time = Node.js cold-start median.

📦 Bundle Stats — @sanity/cli-core

Compared against main (cc636d1f)

Metric	Value	vs main (cc636d1)
Internal (raw)	95.5 KB	-
Internal (gzip)	22.5 KB	-
Bundled (raw)	21.60 MB	-
Bundled (gzip)	3.42 MB	-
Import time	777ms	+0ms, +0.0%

🗺️ View treemap · Artifacts

Details

• Import time regressions over 10% are flagged with ⚠️
• Sizes shown as raw / gzip 🗜️. Internal bytes = own code only. Total bytes = with all dependencies. Import time = Node.js cold-start median.

📦 Bundle Stats — create-sanity

Compared against main (cc636d1f)

Metric	Value	vs main (cc636d1)
Internal (raw)	976 B	-
Internal (gzip)	507 B	-
Bundled (raw)	50.7 KB	-
Bundled (gzip)	12.6 KB	-
Import time	❌ ChildProcess denied: node	-

Details

• Import time regressions over 10% are flagged with ⚠️
• Sizes shown as raw / gzip 🗜️. Internal bytes = own code only. Total bytes = with all dependencies. Import time = Node.js cold-start median.

[github-actions]

Preview this PR with pkg.pr.new

Run the Sanity CLI

npx https://pkg.pr.new/sanity-io/cli/@sanity/cli@d4f492e <command>

...Or upgrade project dependencies

📦 @sanity/cli

pnpm install https://pkg.pr.new/@sanity/cli@d4f492e

📦 @sanity/cli-core

pnpm install https://pkg.pr.new/@sanity/cli-core@d4f492e

📦 @sanity/cli-test

pnpm install https://pkg.pr.new/@sanity/cli-test@d4f492e

📦 @sanity/eslint-config-cli

pnpm install https://pkg.pr.new/@sanity/eslint-config-cli@d4f492e

View Commit (d4f492e)

[github-actions]

Coverage Delta

File	Statements
packages/@sanity/cli/scripts/check-topic-aliases.ts	0.0% (±0%)
packages/@sanity/cli/src/api/cache.ts	85.7% (new)
packages/@sanity/cli/src/api/docsClient.ts	86.4% (new)
packages/@sanity/cli/src/api/parser.ts	84.8% (new)
packages/@sanity/cli/src/api/revalidate.ts	87.0% (new)
packages/@sanity/cli/src/api/views.ts	56.3% (new)
packages/@sanity/cli/src/commands/api/list.ts	92.6% (new)
packages/@sanity/cli/src/commands/api/spec.ts	77.0% (new)
packages/@sanity/cli/src/commands/openapi/get.ts	100.0% (±0%)
packages/@sanity/cli/src/commands/openapi/list.ts	100.0% (±0%)

Comparing 10 changed files against main @ af84de168c307df818477672f0f5ecb20bb9180a

Overall Coverage

Metric	Coverage
Statements	83.9% (- 0.3%)
Branches	73.2% (- 0.9%)
Functions	84.2% (+ 0.1%)
Lines	84.6% (- 0.1%)