refactor: type-safe snapshot system derived from OpenAPI schemas

.github/workflows/spec-check.yml

@@ -31,10 +31,13 @@ jobs:
       - run: npm run build
       - run: npm test
 
+      - name: Regenerate types from spec
+        run: npm run typegen
+
       - name: Check for type changes
         id: diff
         run: |
-          if git diff --quiet src/lib/api.generated.ts docs/openapi/monitoring-api.json; then
+          if git diff --quiet src/lib/api.generated.ts docs/openapi/; then
             echo "changed=false" >> "$GITHUB_OUTPUT"
           else
             echo "changed=true" >> "$GITHUB_OUTPUT"

package.json

@@ -63,10 +63,12 @@
     "@oclif/plugin-not-found": "^3.2.80",
     "chalk": "^5.6.2",
     "cli-table3": "^0.6.5",
+    "lodash-es": "^4.18.1",
     "openapi-fetch": "^0.17.0",
     "yaml": "^2.8.3"
   },
   "devDependencies": {
+    "@types/lodash-es": "^4.17.12",
     "@types/node": "^25.5.2",
     "@typescript-eslint/eslint-plugin": "^8.58.1",
     "@typescript-eslint/parser": "^8.58.1",

scripts/extract-descriptions.mjs

@@ -16,7 +16,8 @@ const OUT_PATH = resolve(__dirname, '../src/lib/descriptions.generated.ts');
 const spec = JSON.parse(readFileSync(SPEC_PATH, 'utf8'));
 const schemas = spec.components?.schemas ?? {};
 
-// Schemas we care about for CLI flag descriptions
+// Schemas we care about for CLI flag descriptions.
+// Keep in sync with MUST_HAVE in tests/spec/test_openapi_descriptions.py (monorepo).
 const TARGET_SCHEMAS = [
   'CreateMonitorRequest', 'UpdateMonitorRequest',
   'CreateManualIncidentRequest',
@@ -29,6 +30,7 @@ const TARGET_SCHEMAS = [
   'CreateWebhookEndpointRequest', 'UpdateWebhookEndpointRequest',
   'CreateApiKeyRequest', 'UpdateApiKeyRequest',
   'ResolveIncidentRequest', 'MonitorTestRequest',
+  'AcquireDeployLockRequest',
   'HttpMonitorConfig', 'TcpMonitorConfig', 'DnsMonitorConfig',
   'IcmpMonitorConfig', 'HeartbeatMonitorConfig', 'McpServerMonitorConfig',
   'SlackChannelConfig', 'DiscordChannelConfig', 'EmailChannelConfig',

src/commands/alert-channels/test.ts

@@ -11,10 +11,7 @@ export default class AlertChannelsTest extends Command {
   async run() {
     const {args, flags} = await this.parse(AlertChannelsTest)
     const client = buildClient(flags)
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    const resp = await checkedFetch(client.POST(`/api/v1/alert-channels/${args.id}/test` as any, {} as any))
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    const result = (resp as any)?.data ?? resp
-    this.log(result.success ? 'Test notification sent successfully.' : 'Test notification failed.')
+    const resp = await checkedFetch(client.POST('/api/v1/alert-channels/{id}/test', {params: {path: {id: args.id}}}))
+    this.log(resp.data?.success ? 'Test notification sent successfully.' : 'Test notification failed.')
   }
 }

src/commands/api-keys/revoke.ts

@@ -11,8 +11,7 @@ export default class ApiKeysRevoke extends Command {
   async run() {
     const {args, flags} = await this.parse(ApiKeysRevoke)
     const client = buildClient(flags)
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    await checkedFetch(client.POST(`/api/v1/api-keys/${args.id}/revoke` as any, {} as any))
+    await checkedFetch(client.POST('/api/v1/api-keys/{id}/revoke', {params: {path: {id: Number(args.id)}}}))
     this.log(`API key '${args.id}' revoked.`)
   }
 }

src/commands/auth/login.ts

@@ -1,6 +1,6 @@
 import {Command, Flags} from '@oclif/core'
 import {globalFlags} from '../../lib/base-command.js'
-import {createApiClient, checkedFetch} from '../../lib/api-client.js'
+import {createApiClient, checkedFetch, apiGet} from '../../lib/api-client.js'
 import {saveContext, resolveApiUrl} from '../../lib/auth.js'
 import * as readline from 'node:readline'
 
@@ -24,20 +24,16 @@ export default class AuthLogin extends Command {
     this.log('Validating token...')
     const client = createApiClient({baseUrl: apiUrl, token})
 
-    // Try /api/v1/auth/me first (API key — returns rich identity info).
-    // Falls back to /api/v1/dashboard/overview for non-API-key tokens (dev tokens, JWTs).
     try {
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      const resp = await checkedFetch(client.GET('/api/v1/auth/me' as any, {} as any))
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      const me = (resp as any)?.data ?? resp
+      const resp = await checkedFetch(client.GET('/api/v1/auth/me'))
+      const me = resp.data
 
       saveContext({name: flags.name, apiUrl, token}, true)
       this.log('')
       this.log(`  Authenticated successfully.`)
-      this.log(`  Organization: ${me.organization?.name ?? 'unknown'} (ID: ${me.organization?.id ?? '?'})`)
-      this.log(`  Key:          ${me.key?.name ?? 'unknown'}`)
-      this.log(`  Plan:         ${me.plan?.tier ?? 'unknown'}`)
+      this.log(`  Organization: ${me?.organization?.name ?? 'unknown'} (ID: ${me?.organization?.id ?? '?'})`)
+      this.log(`  Key:          ${me?.key?.name ?? 'unknown'}`)
+      this.log(`  Plan:         ${me?.plan?.tier ?? 'unknown'}`)
       this.log('')
       this.log(`  Context '${flags.name}' saved to ~/.devhelm/contexts.json`)
       return
@@ -46,8 +42,7 @@ export default class AuthLogin extends Command {
     }
 
     try {
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      await checkedFetch(client.GET('/api/v1/dashboard/overview' as any, {} as any))
+      await apiGet(client, '/api/v1/dashboard/overview')
       saveContext({name: flags.name, apiUrl, token}, true)
       this.log('')
       this.log(`  Authenticated successfully.`)

src/commands/auth/me.ts

@@ -11,21 +11,19 @@ export default class AuthMe extends Command {
   async run() {
     const {flags} = await this.parse(AuthMe)
     const client = buildClient(flags)
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    const resp = await checkedFetch(client.GET('/api/v1/auth/me' as any, {} as any))
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    const me = (resp as any)?.data ?? resp
+    const resp = await checkedFetch(client.GET('/api/v1/auth/me'))
+    const me = resp.data
 
     const format = flags.output as OutputFormat
     if (format === 'json' || format === 'yaml') {
       this.log(formatOutput(me, format))
       return
     }
 
-    const k = me.key ?? {}
-    const o = me.organization ?? {}
-    const p = me.plan ?? {}
-    const r = me.rateLimits ?? {}
+    const k = me?.key ?? {}
+    const o = me?.organization ?? {}
+    const p = me?.plan ?? {}
+    const r = me?.rateLimits ?? {}
 
     this.log('')
     this.log('  API Key')
@@ -42,8 +40,8 @@ export default class AuthMe extends Command {
     this.log('  Rate Limits')
     this.log(`    Limit: ${r.requestsPerMinute ?? '–'} req/min    Remaining: ${r.remaining ?? '–'}    Window: ${r.windowMs ? `${r.windowMs / 1000}s` : '–'}`)
 
-    const usage = p.usage as Record<string, number> | undefined
-    const entitlements = p.entitlements as Record<string, {value: number}> | undefined
+    const usage = p.usage
+    const entitlements = p.entitlements
     if (usage && entitlements) {
       this.log('')
       this.log('  Usage')

src/commands/data/services/status.ts

@@ -11,10 +11,7 @@ export default class DataServicesStatus extends Command {
   async run() {
     const {args, flags} = await this.parse(DataServicesStatus)
     const client = buildClient(flags)
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    const resp = await checkedFetch(client.GET(`/api/v1/services/${args.slug}` as any, {} as any))
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    const service = (resp as any)?.data ?? resp
-    display(this, service, flags.output)
+    const resp = await checkedFetch(client.GET('/api/v1/services/{slugOrId}', {params: {path: {slugOrId: args.slug}}}))
+    display(this, resp.data ?? resp, flags.output)
   }
 }

src/commands/data/services/uptime.ts

@@ -1,6 +1,6 @@
 import {Command, Args, Flags} from '@oclif/core'
 import {globalFlags, buildClient, display} from '../../../lib/base-command.js'
-import {checkedFetch} from '../../../lib/api-client.js'
+import {apiGet} from '../../../lib/api-client.js'
 
 export default class DataServicesUptime extends Command {
   static description = 'Get uptime data for a service'
@@ -18,12 +18,9 @@ export default class DataServicesUptime extends Command {
   async run() {
     const {args, flags} = await this.parse(DataServicesUptime)
     const client = buildClient(flags)
-    let path = `/api/v1/services/${args.slug}/uptime?period=${flags.period}`
-    if (flags.granularity) path += `&granularity=${flags.granularity}`
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    const resp = await checkedFetch(client.GET(path as any, {} as any))
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    const uptime = (resp as any)?.data ?? resp
-    display(this, uptime, flags.output)
+    const query: Record<string, string> = {period: flags.period}
+    if (flags.granularity) query.granularity = flags.granularity
+    const resp = await apiGet<{data?: unknown}>(client, `/api/v1/services/${args.slug}/uptime`, {query})
+    display(this, resp.data ?? resp, flags.output)
   }
 }

src/commands/dependencies/track.ts

@@ -11,10 +11,7 @@ export default class DependenciesTrack extends Command {
   async run() {
     const {args, flags} = await this.parse(DependenciesTrack)
     const client = buildClient(flags)
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    const resp = await checkedFetch(client.POST(`/api/v1/service-subscriptions/${args.slug}` as any, {} as any))
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    const sub = (resp as any)?.data ?? resp
-    this.log(`Now tracking '${sub.serviceName}' as a dependency.`)
+    const resp = await checkedFetch(client.POST('/api/v1/service-subscriptions/{slug}', {params: {path: {slug: args.slug}}}))
+    this.log(`Now tracking '${resp.data?.name}' as a dependency.`)
   }
 }

src/commands/deploy/force-unlock.ts

@@ -0,0 +1,63 @@
+import {Command, Flags} from '@oclif/core'
+import {createApiClient, apiDelete} from '../../lib/api-client.js'
+import {resolveToken, resolveApiUrl} from '../../lib/auth.js'
+
+export default class DeployForceUnlock extends Command {
+  static description = 'Force-release a stuck deploy lock on the current workspace'
+
+  static examples = [
+    '<%= config.bin %> deploy force-unlock',
+    '<%= config.bin %> deploy force-unlock --yes',
+  ]
+
+  static flags = {
+    yes: Flags.boolean({
+      char: 'y',
+      description: 'Skip confirmation prompt',
+      default: false,
+    }),
+    'api-url': Flags.string({description: 'Override API base URL'}),
+    'api-token': Flags.string({description: 'Override API token'}),
+    verbose: Flags.boolean({char: 'v', description: 'Show verbose output', default: false}),
+  }
+
+  async run() {
+    const {flags} = await this.parse(DeployForceUnlock)
+
+    if (!flags.yes) {
+      const {createInterface} = await import('node:readline')
+      const rl = createInterface({input: process.stdin, output: process.stdout})
+      const answer = await new Promise<string>((resolve) => {
+        rl.question('Force-unlock removes any active deploy lock. This is dangerous if another deploy is in progress.\nContinue? (yes/no): ', resolve)
+      })
+      rl.close()
+      if (answer.toLowerCase() !== 'yes' && answer.toLowerCase() !== 'y') {
+        this.log('Cancelled.')
+        return
+      }
+    }
+
+    const token = flags['api-token'] ?? resolveToken()
+    if (!token) {
+      this.error('No API token configured. Run "devhelm auth login" or set DEVHELM_API_TOKEN.', {exit: 1})
+    }
+
+    const client = createApiClient({
+      baseUrl: flags['api-url'] ?? resolveApiUrl(),
+      token,
+      verbose: flags.verbose,
+    })
+
+    try {
+      await apiDelete(client, '/api/v1/deploy/lock/force')
+      this.log('Deploy lock released.')
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err)
+      if (msg.includes('404') || msg.includes('Not Found')) {
+        this.log('No active deploy lock found.')
+        return
+      }
+      this.error(`Failed to release lock: ${msg}`, {exit: 1})
+    }
+  }
+}