test(cli): cover offline cache, credentials, secret refs, ignore files (#734)

Author: HugoRCD

.changeset/cli-test-coverage.md

@@ -0,0 +1,5 @@
+---
+"@shelve/cli": patch
+---
+
+Add test coverage for the v5 additions — encrypted offline cache (roundtrip / TTL / token rotation / tampering), OS-keychain credentials with XDG file fallback and legacy `~/.shelve` migration, agent-ignore files, `shelve://` secret references, and `parseDuration`. Along the way, `CredentialsService` now creates `$XDG_CONFIG_HOME` on demand so writes no longer fail on freshly provisioned machines.

packages/cli/src/services/credentials.ts

@@ -1,6 +1,6 @@
-import { chmodSync, existsSync, readFileSync, unlinkSync } from 'node:fs'
+import { chmodSync, existsSync, mkdirSync, readFileSync, unlinkSync } from 'node:fs'
 import { homedir } from 'node:os'
-import { join } from 'node:path'
+import { dirname, join } from 'node:path'
 import { readUserConfig, writeUserConfig } from 'rc9'
 import consola from 'consola'
 import { DEBUG } from '../constants'
@@ -59,6 +59,16 @@ function chmod600(path: string): void {
   }
 }
 
+/**
+ * rc9 does not mkdir the target directory, so `writeUserConfig` would fail on
+ * a freshly provisioned machine where `$XDG_CONFIG_HOME` (or `~/.config`)
+ * does not yet exist. Make sure the parent exists before handing off to rc9.
+ */
+function ensureConfigDir(): void {
+  const dir = dirname(configPath())
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true, mode: 0o700 })
+}
+
 /**
  * Older versions of the CLI stored credentials at `~/.shelve`. rc9 has since
  * deprecated `readUser`/`writeUser` in favor of XDG-compliant
@@ -76,6 +86,7 @@ function migrateLegacyConfig(): void {
     const legacy = parseLegacyRc(readFileSync(LEGACY_RC_PATH, 'utf-8'))
     if (Object.keys(legacy).length === 0) return
 
+    ensureConfigDir()
     writeUserConfig(legacy, RC_FILENAME)
     chmod600(configPath())
     unlinkSync(LEGACY_RC_PATH)
@@ -104,6 +115,8 @@ export class CredentialsService {
     const factory = await loadKeyring()
     const account = accountFor(url)
 
+    ensureConfigDir()
+
     if (factory) {
       try {
         const entry = factory(KEYRING_SERVICE, account)
@@ -152,6 +165,7 @@ export class CredentialsService {
         entry.deletePassword()
       } catch { /* ignore */ }
     }
+    ensureConfigDir()
     writeUserConfig({}, RC_FILENAME)
   }
 

packages/cli/test/cache.test.ts

@@ -0,0 +1,109 @@
+import { mkdtempSync, readFileSync, writeFileSync, rmSync, utimesSync, existsSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import type { CacheKeyInput } from '../src/services/cache'
+
+type CacheModule = typeof import('../src/services/cache')
+
+// `src/services/cache.ts` captures `homedir()` and `CACHE_DIR` at module load
+// time. We therefore need to mutate HOME and then dynamically import the
+// module so the cache lands under the test sandbox instead of the real user
+// home directory.
+describe('CacheService', () => {
+  const originalHome = process.env.HOME
+  const originalUserProfile = process.env.USERPROFILE
+  let sandbox: string
+  let cache: CacheModule
+
+  const input: CacheKeyInput = {
+    url: 'https://shelve.cloud',
+    teamSlug: 'acme',
+    projectName: 'web',
+    environmentName: 'production',
+  }
+  const token = 'she_live_'.concat('a'.repeat(40))
+  const variables = [
+    { key: 'DATABASE_URL', value: 'postgres://prod' },
+    { key: 'API_KEY', value: 'sk-abc' },
+  ]
+
+  beforeEach(async () => {
+    sandbox = mkdtempSync(join(tmpdir(), 'shelve-cache-'))
+    process.env.HOME = sandbox
+    process.env.USERPROFILE = sandbox
+    vi.resetModules()
+    cache = await import('../src/services/cache')
+  })
+
+  afterEach(() => {
+    rmSync(sandbox, { recursive: true, force: true })
+    process.env.HOME = originalHome
+    process.env.USERPROFILE = originalUserProfile
+  })
+
+  it('writes and reads back variables with the same token', () => {
+    cache.CacheService.write(input, token, variables)
+    const read = cache.CacheService.read(input, token, 60_000)
+    expect(read).toEqual(variables)
+  })
+
+  it('returns null when the file does not exist', () => {
+    expect(cache.CacheService.read(input, token, 60_000)).toBeNull()
+  })
+
+  it('refuses to write without a token', () => {
+    cache.CacheService.write(input, '', variables)
+    expect(cache.CacheService.read(input, token, 60_000)).toBeNull()
+  })
+
+  it('returns null when reading without a token', () => {
+    cache.CacheService.write(input, token, variables)
+    expect(cache.CacheService.read(input, '', 60_000)).toBeNull()
+  })
+
+  it('fails decryption (returns null) when the token changes', () => {
+    cache.CacheService.write(input, token, variables)
+    const tampered = cache.CacheService.read(input, 'she_live_'.concat('b'.repeat(40)), 60_000)
+    expect(tampered).toBeNull()
+  })
+
+  it('respects TTL: stale entries are not returned', () => {
+    cache.CacheService.write(input, token, variables)
+    const file = cache.cacheFilePath(input)
+    const past = (Date.now() - 60 * 60 * 1000) / 1000
+    utimesSync(file, past, past)
+    expect(cache.CacheService.read(input, token, 60_000)).toBeNull()
+  })
+
+  it('returns the payload when ttlMs is 0 (no expiry)', () => {
+    cache.CacheService.write(input, token, variables)
+    const file = cache.cacheFilePath(input)
+    const past = (Date.now() - 365 * 24 * 60 * 60 * 1000) / 1000
+    utimesSync(file, past, past)
+    const read = cache.CacheService.read(input, token, 0)
+    expect(read).toEqual(variables)
+  })
+
+  it('returns null when the ciphertext is tampered with', () => {
+    cache.CacheService.write(input, token, variables)
+    const file = cache.cacheFilePath(input)
+    expect(existsSync(file)).toBe(true)
+    const blob = readFileSync(file)
+    blob[blob.length - 1] = (blob[blob.length - 1] ?? 0) ^ 0xff
+    writeFileSync(file, blob)
+    expect(cache.CacheService.read(input, token, 60_000)).toBeNull()
+  })
+
+  it('produces different cache keys for different envs', () => {
+    const a = cache.cacheFilePath(input)
+    const b = cache.cacheFilePath({ ...input, environmentName: 'staging' })
+    expect(a).not.toBe(b)
+  })
+
+  it('ignores trailing slashes in the base URL for the cache key', () => {
+    const a = cache.cacheFilePath(input)
+    const b = cache.cacheFilePath({ ...input, url: 'https://shelve.cloud/' })
+    expect(a).toBe(b)
+  })
+})

packages/cli/test/credentials.test.ts

@@ -0,0 +1,108 @@
+import { mkdtempSync, existsSync, writeFileSync, rmSync, readFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+// Force the keyring import to throw so CredentialsService falls back to the
+// file-based storage. This keeps the test hermetic (no OS keychain touched)
+// while still exercising the migration + file paths.
+vi.mock('@napi-rs/keyring', () => {
+  throw new Error('keyring unavailable in tests')
+})
+
+type CredentialsModule = typeof import('../src/services/credentials')
+
+describe('CredentialsService (file fallback)', () => {
+  const originalHome = process.env.HOME
+  const originalXdg = process.env.XDG_CONFIG_HOME
+  const originalUserProfile = process.env.USERPROFILE
+  let sandbox: string
+
+  beforeEach(() => {
+    sandbox = mkdtempSync(join(tmpdir(), 'shelve-creds-'))
+    process.env.HOME = sandbox
+    process.env.USERPROFILE = sandbox
+    process.env.XDG_CONFIG_HOME = join(sandbox, '.config')
+    vi.resetModules()
+  })
+
+  afterEach(() => {
+    rmSync(sandbox, { recursive: true, force: true })
+    process.env.HOME = originalHome
+    process.env.USERPROFILE = originalUserProfile
+    process.env.XDG_CONFIG_HOME = originalXdg
+  })
+
+  async function loadModule(): Promise<CredentialsModule> {
+    return await import('../src/services/credentials')
+  }
+
+  it('writes and reads back a token via the file fallback', async () => {
+    const creds = await loadModule()
+    await creds.CredentialsService.writeToken('https://shelve.cloud', 'she_live_token', {
+      email: 'u@example.com',
+      username: 'u',
+    })
+
+    const token = await creds.CredentialsService.readToken('https://shelve.cloud')
+    expect(token).toBe('she_live_token')
+
+    const meta = creds.CredentialsService.readMeta()
+    expect(meta.email).toBe('u@example.com')
+    expect(meta.username).toBe('u')
+    expect(meta.storage).toBe('file')
+  })
+
+  it('writes the config under XDG_CONFIG_HOME', async () => {
+    const creds = await loadModule()
+    await creds.CredentialsService.writeToken('https://shelve.cloud', 'tkn', {
+      email: 'a@b.co',
+      username: 'ab',
+    })
+    expect(existsSync(join(sandbox, '.config', '.shelve'))).toBe(true)
+  })
+
+  it('clearToken removes the stored token', async () => {
+    const creds = await loadModule()
+    await creds.CredentialsService.writeToken('https://shelve.cloud', 'tkn', {
+      email: 'a@b.co',
+      username: 'ab',
+    })
+    await creds.CredentialsService.clearToken('https://shelve.cloud')
+    const after = await creds.CredentialsService.readToken('https://shelve.cloud')
+    expect(after).toBeUndefined()
+  })
+
+  it('migrates a legacy ~/.shelve file on first read and deletes it', async () => {
+    const legacyPath = join(sandbox, '.shelve')
+    writeFileSync(
+      legacyPath,
+      ['token=legacy_tkn', 'email=legacy@example.com', 'username=legacy', 'url=https://shelve.cloud'].join('\n'),
+      'utf-8'
+    )
+
+    const creds = await loadModule()
+    const token = await creds.CredentialsService.readToken('https://shelve.cloud')
+    expect(token).toBe('legacy_tkn')
+    expect(existsSync(legacyPath)).toBe(false)
+
+    const xdgFile = join(sandbox, '.config', '.shelve')
+    expect(existsSync(xdgFile)).toBe(true)
+    const content = readFileSync(xdgFile, 'utf-8')
+    expect(content).toContain('legacy_tkn')
+    expect(content).toContain('legacy@example.com')
+  })
+
+  it('does not migrate when the XDG file already holds data', async () => {
+    const creds = await loadModule()
+    await creds.CredentialsService.writeToken('https://shelve.cloud', 'new_tkn', {
+      email: 'new@example.com',
+      username: 'new',
+    })
+
+    writeFileSync(join(sandbox, '.shelve'), 'token=legacy_tkn\n', 'utf-8')
+
+    const token = await creds.CredentialsService.readToken('https://shelve.cloud')
+    expect(token).toBe('new_tkn')
+  })
+})

packages/cli/test/duration.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, it } from 'vitest'
+import { parseDuration } from '../src/utils/duration'
+
+describe('parseDuration', () => {
+  const DEFAULT = 12345
+
+  it('returns the default for null/undefined/empty', () => {
+    expect(parseDuration(undefined, DEFAULT)).toBe(DEFAULT)
+    expect(parseDuration(null, DEFAULT)).toBe(DEFAULT)
+    expect(parseDuration('', DEFAULT)).toBe(DEFAULT)
+  })
+
+  it('accepts a positive finite number (ms)', () => {
+    expect(parseDuration(500, DEFAULT)).toBe(500)
+    expect(parseDuration(0, DEFAULT)).toBe(0)
+  })
+
+  it('falls back to default for negative or non-finite numbers', () => {
+    expect(parseDuration(-1, DEFAULT)).toBe(DEFAULT)
+    expect(parseDuration(Number.NaN, DEFAULT)).toBe(DEFAULT)
+    expect(parseDuration(Number.POSITIVE_INFINITY, DEFAULT)).toBe(DEFAULT)
+  })
+
+  it('parses unit suffixes', () => {
+    expect(parseDuration('500ms', DEFAULT)).toBe(500)
+    expect(parseDuration('30s', DEFAULT)).toBe(30_000)
+    expect(parseDuration('15m', DEFAULT)).toBe(15 * 60_000)
+    expect(parseDuration('2h', DEFAULT)).toBe(2 * 3_600_000)
+    expect(parseDuration('7d', DEFAULT)).toBe(7 * 86_400_000)
+  })
+
+  it('treats a bare number string as milliseconds', () => {
+    expect(parseDuration('250', DEFAULT)).toBe(250)
+  })
+
+  it('is case-insensitive and tolerates whitespace', () => {
+    expect(parseDuration(' 1H ', DEFAULT)).toBe(3_600_000)
+    expect(parseDuration('10S', DEFAULT)).toBe(10_000)
+  })
+
+  it('accepts decimal values', () => {
+    expect(parseDuration('1.5h', DEFAULT)).toBe(Math.floor(1.5 * 3_600_000))
+  })
+
+  it('returns the default for garbage input', () => {
+    expect(parseDuration('soon', DEFAULT)).toBe(DEFAULT)
+    expect(parseDuration('5x', DEFAULT)).toBe(DEFAULT)
+    expect(parseDuration('--5s', DEFAULT)).toBe(DEFAULT)
+  })
+})