feat(skills): add ns-download-asset skill; stream fetch-asset.cjs to disk

.claude-plugin/plugin.json

@@ -19,6 +19,7 @@
     "./skills/ns-audit-dependencies",
     "./skills/ns-benchmark-run",
     "./skills/ns-cpu-spike-analysis",
+    "./skills/ns-download-asset",
     "./skills/ns-generate-asset",
     "./skills/ns-generate-sbom",
     "./skills/ns-memory-spike-analysis",

bundle.json

@@ -51,6 +51,12 @@
       "description": "Profile CPU usage of running production processes to identify bottlenecks",
       "requiresMcp": ["nsolid-console"]
     },
+    {
+      "name": "ns-download-asset",
+      "path": "skills/ns-download-asset",
+      "description": "Download a raw N|Solid diagnostic asset (heap snapshot, CPU profile, heap profile) to local disk",
+      "requiresMcp": ["nsolid-console"]
+    },
     {
       "name": "ns-generate-asset",
       "path": "skills/ns-generate-asset",
@@ -66,7 +72,7 @@
     {
       "name": "ns-memory-spike-analysis",
       "path": "skills/ns-memory-spike-analysis",
-      "description": "Analyze memory spikes and suspected leaks via baseline/peak heap sampling, with optional track-heap-objects for retainer analysis",
+      "description": "Analyze memory spikes and suspected leaks via baseline/peak heap sampling comparison",
       "requiresMcp": ["nsolid-console"]
     },
     {

packages/core/bundle.json

@@ -51,6 +51,12 @@
       "description": "Profile CPU usage of running production processes to identify bottlenecks",
       "requiresMcp": ["nsolid-console"]
     },
+    {
+      "name": "ns-download-asset",
+      "path": "skills/ns-download-asset",
+      "description": "Download a raw N|Solid diagnostic asset (heap snapshot, CPU profile, heap profile) to local disk",
+      "requiresMcp": ["nsolid-console"]
+    },
     {
       "name": "ns-generate-asset",
       "path": "skills/ns-generate-asset",
@@ -66,7 +72,7 @@
     {
       "name": "ns-memory-spike-analysis",
       "path": "skills/ns-memory-spike-analysis",
-      "description": "Analyze memory spikes and suspected leaks via baseline/peak heap sampling, with optional track-heap-objects for retainer analysis",
+      "description": "Analyze memory spikes and suspected leaks via baseline/peak heap sampling comparison",
       "requiresMcp": ["nsolid-console"]
     },
     {

packages/core/scripts/skill-assets.manifest.json

@@ -12,6 +12,7 @@
     "ns-advanced-memory-leak-hunter",
     "ns-analyze-asset",
     "ns-cpu-spike-analysis",
+    "ns-download-asset",
     "ns-generate-asset",
     "ns-memory-spike-analysis"
   ]

packages/core/test/unit/skills/fetch-asset.test.ts

@@ -3,7 +3,14 @@ import assert from 'node:assert/strict'
 import { promises as dns } from 'node:dns'
 import { fileURLToPath, pathToFileURL } from 'node:url'
 import { dirname, join } from 'node:path'
+import { mkdtemp, readFile, readdir, rm, stat } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import https from 'node:https'
+import { EventEmitter } from 'node:events'
+import { Readable } from 'node:stream'
+import { gzipSync } from 'node:zlib'
 import type { TestContext } from 'node:test'
+import type { ClientRequest, IncomingMessage, RequestOptions } from 'node:http'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
 const fetchAssetPath = join(__dirname, '../../../../../skill-assets/fetch-asset.cjs')
@@ -30,7 +37,8 @@ async function loadFetchAsset () {
   return mod as {
     isPrivateOrLocalIp: (ip: string) => boolean
     resolveHostnameIps: (hostname: string) => Promise<string[]>
-    validateConsoleUrl: (consoleUrl: string) => Promise<void>
+    validateConsoleUrl: (consoleUrl: string) => Promise<string[] | null>
+    downloadAsset: (consoleUrl: string, token: string, assetId: string, destPath: string, validatedIps?: string[] | null) => Promise<number>
   }
 }
 
@@ -236,7 +244,7 @@ describe('validateConsoleUrl', () => {
   it('allows public hostnames', async (t) => {
     mockDnsLookup(t, ['93.184.216.34'])
     const { validateConsoleUrl } = await loadFetchAsset()
-    await assert.doesNotReject(() => validateConsoleUrl('https://example.com'))
+    assert.deepEqual(await validateConsoleUrl('https://example.com'), ['93.184.216.34'])
   })
 
   it('rejects invalid URLs', async () => {
@@ -247,3 +255,187 @@ describe('validateConsoleUrl', () => {
     )
   })
 })
+
+function makeFakeRequest (respond: () => void) {
+  const req = new EventEmitter() as ClientRequest
+  req.end = (() => {
+    respond()
+    return req
+  }) as ClientRequest['end']
+  req.destroy = ((error?: Error) => {
+    if (error) queueMicrotask(() => req.emit('error', error))
+    return req
+  }) as ClientRequest['destroy']
+  return req
+}
+
+function makeFakeResponse (body: Buffer | ((this: Readable) => void), statusCode = 200, statusMessage = 'OK', headers: Record<string, string> = {}) {
+  let readCount = 0
+  const res = new Readable({
+    read () {
+      if (readCount++ === 0) {
+        if (Buffer.isBuffer(body)) {
+          this.push(body)
+        } else {
+          // Function bodies own the stream lifecycle (EOF and/or error).
+          body.call(this)
+        }
+        return
+      }
+      if (Buffer.isBuffer(body)) {
+        this.push(null)
+      }
+    }
+  }) as IncomingMessage
+  res.statusCode = statusCode
+  res.statusMessage = statusMessage
+  res.headers = headers
+  return res
+}
+
+describe('downloadAsset', () => {
+  let tempDir: string
+
+  beforeEach(async () => {
+    tempDir = await mkdtemp(join(tmpdir(), 'fetch-asset-download-'))
+  })
+
+  afterEach(async () => {
+    await rm(tempDir, { recursive: true, force: true })
+  })
+
+  it('streams the asset body to disk and returns the file size', async (t) => {
+    const payload = Buffer.from([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])
+    const calls: Array<{
+      url: string
+      headers: Record<string, string | string[] | undefined>
+      lookup: unknown
+    }> = []
+    t.mock.method(https, 'request', ((input: string | URL, options: RequestOptions, callback?: (res: IncomingMessage) => void) => {
+      calls.push({
+        url: String(input),
+        headers: (options.headers ?? {}) as Record<string, string>,
+        lookup: options.lookup
+      })
+      return makeFakeRequest(() => { callback?.(makeFakeResponse(payload)) })
+    }) as typeof https.request)
+
+    const { downloadAsset } = await loadFetchAsset()
+    const destPath = join(tempDir, 'heapsnapshot-test.heapsnapshot')
+
+    const size = await downloadAsset(
+      'https://console.example.test',
+      'secret-token',
+      'asset-id-1',
+      destPath,
+      ['93.184.216.34']
+    )
+
+    const stats = await stat(destPath)
+    assert.equal(size, stats.size, 'returns the on-disk file size')
+    assert.equal(size, payload.byteLength)
+    assert.deepEqual(await readFile(destPath), payload, 'file bytes match the response body')
+    assert.equal(calls.length, 1)
+    assert.equal(calls[0].url, 'https://console.example.test/api/v3/asset/asset-id-1')
+    assert.equal(calls[0].headers['x-nsolid-service-token'], 'secret-token')
+    assert.equal(calls[0].headers.Accept, 'application/json')
+    assert.equal(typeof calls[0].lookup, 'function', 'uses a lookup pinned to validated addresses')
+    assert.deepEqual(await readdir(tempDir), ['heapsnapshot-test.heapsnapshot'])
+  })
+
+  it('URL-encodes the asset ID in the request path', async (t) => {
+    const urls: string[] = []
+    t.mock.method(https, 'request', ((input: string | URL, _options: RequestOptions, callback?: (res: IncomingMessage) => void) => {
+      urls.push(String(input))
+      return makeFakeRequest(() => { callback?.(makeFakeResponse(Buffer.from([1, 2, 3]))) })
+    }) as typeof https.request)
+
+    const { downloadAsset } = await loadFetchAsset()
+    await downloadAsset(
+      'https://console.example.test',
+      'token',
+      'id/with space',
+      join(tempDir, 'a.heapsnapshot'),
+      ['93.184.216.34']
+    )
+
+    assert.equal(urls[0], 'https://console.example.test/api/v3/asset/id%2Fwith%20space')
+  })
+
+  it('throws on non-ok responses without creating a file', async (t) => {
+    t.mock.method(https, 'request', ((_input: string | URL, _options: RequestOptions, callback?: (res: IncomingMessage) => void) => {
+      return makeFakeRequest(() => { callback?.(makeFakeResponse(Buffer.from('not found'), 404, 'Not Found')) })
+    }) as typeof https.request)
+
+    const { downloadAsset } = await loadFetchAsset()
+    const destPath = join(tempDir, 'missing.heapsnapshot')
+    await assert.rejects(
+      () => downloadAsset('https://console.example.test', 'token', 'missing-id', destPath, ['93.184.216.34']),
+      /404 Not Found for asset missing-id/
+    )
+    await assert.rejects(() => stat(destPath), /ENOENT/)
+  })
+
+  it('removes temporary bytes when the response stream fails', async (t) => {
+    t.mock.method(https, 'request', ((_input: string | URL, _options: RequestOptions, callback?: (res: IncomingMessage) => void) => {
+      return makeFakeRequest(() => {
+        callback?.(makeFakeResponse(function (this: Readable) {
+          this.push(Buffer.from([1, 2, 3]))
+          queueMicrotask(() => this.destroy(new Error('stream interrupted')))
+        }))
+      })
+    }) as typeof https.request)
+
+    const { downloadAsset } = await loadFetchAsset()
+    const destPath = join(tempDir, 'partial.heapsnapshot')
+
+    await assert.rejects(
+      () => downloadAsset('https://console.example.test', 'token', 'partial-id', destPath, ['93.184.216.34']),
+      /stream interrupted/
+    )
+    await assert.rejects(() => stat(destPath), /ENOENT/)
+    assert.deepEqual(await readdir(tempDir), [], 'does not leave a temporary file behind')
+  })
+
+  it('decompresses gzip-encoded responses before writing to disk', async (t) => {
+    const payload = Buffer.from('heap snapshot payload '.repeat(64))
+    t.mock.method(https, 'request', ((_input: string | URL, _options: RequestOptions, callback?: (res: IncomingMessage) => void) => {
+      return makeFakeRequest(() => {
+        callback?.(makeFakeResponse(gzipSync(payload), 200, 'OK', { 'content-encoding': 'gzip' }))
+      })
+    }) as typeof https.request)
+
+    const { downloadAsset } = await loadFetchAsset()
+    const destPath = join(tempDir, 'gzipped.heapsnapshot')
+
+    const size = await downloadAsset(
+      'https://console.example.test',
+      'token',
+      'gzip-id',
+      destPath,
+      ['93.184.216.34']
+    )
+
+    assert.equal(size, payload.byteLength, 'reports the decompressed size')
+    assert.deepEqual(await readFile(destPath), payload, 'file holds decompressed bytes')
+    assert.deepEqual(await readdir(tempDir), ['gzipped.heapsnapshot'])
+  })
+
+  it('aborts when the whole exchange exceeds the 10-minute deadline', async (t) => {
+    t.mock.timers.enable({ apis: ['setTimeout'] })
+    // The request never responds: covers connect/headers stalling past the
+    // absolute deadline (req.setTimeout would not catch this — it only
+    // measures socket inactivity, and the body timer only starts after
+    // headers arrive).
+    t.mock.method(https, 'request', (() => makeFakeRequest(() => {})) as typeof https.request)
+
+    const { downloadAsset } = await loadFetchAsset()
+    const destPath = join(tempDir, 'stalled.heapsnapshot')
+    const pending = downloadAsset('https://console.example.test', 'token', 'stalled-id', destPath, ['93.184.216.34'])
+    const assertion = assert.rejects(pending, /exceeded 10 minutes/)
+    t.mock.timers.tick(600_000)
+    await assertion
+    await assert.rejects(() => stat(destPath), /ENOENT/)
+    assert.deepEqual(await readdir(tempDir), [], 'does not leave a temporary file behind')
+  })
+})