feat(channel): add delete, archive, unarchive subcommands (#8)

* feat(channel): add delete, archive, unarchive subcommands

Ports the remaining channel-lifecycle commands from twist-cli #246
(create already existed). Wraps the SDK's deleteChannel, archiveChannel
and unarchiveChannel endpoints so channel lifecycle no longer requires
the web UI.

- delete requires --yes to mutate, short-circuits MISSING_YES_FLAG in
  --json mode before any lookup, and translates a 403 into a clear
  FORBIDDEN CliError (deletion is typically admin-only).
- archive/unarchive share a setArchiveState helper and skip the API
  call when the channel is already in the target state.
- All three support --workspace, --dry-run and --json.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* review: bypass workspace resolution for direct channel refs

Addresses doistbot feedback on PR #8.

- Add a shared resolveChannelByRef helper: direct refs (id:/URL) are
  fetched by ID via getChannel (workspace-agnostic), so deleting or
  (un)archiving a channel in another workspace no longer fails with
  CHANNEL_NOT_FOUND. Name refs still resolve a workspace. Mirrors how
  `channel update` already special-cases direct refs.
- delete: move the non-yes/non-dry-run early return above the channel
  lookup and reference the raw ref, so the confirmation prompt no longer
  pays for API calls.
- Tests: table-driven --workspace coverage (asserts the passed workspace
  ID reaches resolveChannelRef) and direct-ref bypass coverage (asserts
  getChannel is used and no workspace is resolved) across all three
  subcommands.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: scottlovegrove

skills/comms-cli/SKILL.md

@@ -219,6 +219,10 @@ tdc channel update <ref> --description "Team discussions" # Update channel descr
 tdc channel update <ref> --clear-description # Clear channel description
 tdc channel update <ref> --public # Make a channel public (--private makes it private)
 tdc channel update <ref> --description "Team discussions" --json --full # Update and return all channel fields
+tdc channel delete <channel-ref> --yes # Permanently delete a channel (requires --yes; usually admin-only)
+tdc channel delete <ref> --dry-run # Preview deletion
+tdc channel archive <channel-ref> # Archive a channel (no-op if already archived)
+tdc channel unarchive id:<id> # Unarchive a channel (pass id:/numeric ref for archived channels)
 tdc channel threads <channel-ref>  # List threads in a channel (fuzzy name, id:, numeric ID, or URL)
 tdc channel threads "general" --unread       # Only unread threads
 tdc channel threads <ref> --archive-filter all  # Include archived threads (active|archived|all)

src/commands/channel/archive.ts

@@ -0,0 +1,49 @@
+import { getCommsClient } from '../../lib/api.js'
+import type { MutationOptions } from '../../lib/options.js'
+import { formatJson, printDryRun } from '../../lib/output.js'
+import { resolveChannelByRef } from './helpers.js'
+
+type ArchiveChannelOptions = MutationOptions & { workspace?: string }
+
+async function setArchiveState(
+    ref: string,
+    options: ArchiveChannelOptions,
+    archive: boolean,
+): Promise<void> {
+    const action = archive ? 'archive' : 'unarchive'
+    const channel = await resolveChannelByRef(ref, options.workspace)
+
+    if (options.dryRun) {
+        printDryRun(`${action} channel`, {
+            Channel: `${channel.name} (id:${channel.id})`,
+            'Currently archived': channel.archived ? 'yes' : 'no',
+        })
+        return
+    }
+
+    if (channel.archived !== archive) {
+        const client = await getCommsClient()
+        if (archive) {
+            await client.channels.archiveChannel(channel.id)
+        } else {
+            await client.channels.unarchiveChannel(channel.id)
+        }
+    }
+
+    if (options.json) {
+        console.log(formatJson({ id: channel.id, archived: archive }))
+        return
+    }
+
+    const verb = archive ? 'archived' : 'unarchived'
+    const noop = channel.archived === archive ? ' (already in target state)' : ''
+    console.log(`Channel "${channel.name}" (id:${channel.id}) ${verb}${noop}.`)
+}
+
+export async function archiveChannel(ref: string, options: ArchiveChannelOptions): Promise<void> {
+    await setArchiveState(ref, options, true)
+}
+
+export async function unarchiveChannel(ref: string, options: ArchiveChannelOptions): Promise<void> {
+    await setArchiveState(ref, options, false)
+}

src/commands/channel/channel.test.ts

@@ -3,6 +3,7 @@ import {
     createTestProgram,
     describeEmptyMachineOutput,
 } from '@doist/cli-core/testing'
+import { CommsRequestError } from '@doist/comms-sdk'
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 
 const apiMocks = vi.hoisted(() => ({
@@ -83,6 +84,9 @@ function createClient({
             getChannel: vi.fn(),
             createChannel: vi.fn().mockResolvedValue(createdChannel),
             updateChannel: vi.fn().mockResolvedValue(updatedChannel),
+            deleteChannel: vi.fn().mockResolvedValue({ status: 'ok' }),
+            archiveChannel: vi.fn().mockResolvedValue({ status: 'ok' }),
+            unarchiveChannel: vi.fn().mockResolvedValue({ status: 'ok' }),
         },
         workspaces: {
             getPublicChannels: vi.fn().mockResolvedValue(publicChannels),
@@ -626,3 +630,266 @@ describe('channels update', () => {
         ).rejects.toHaveProperty('code', 'CONFLICTING_OPTIONS')
     })
 })
+
+describe('channels delete', () => {
+    beforeEach(() => {
+        vi.clearAllMocks()
+        apiMocks.getCurrentWorkspaceId.mockResolvedValue(1)
+        refsMocks.getDirectChannelId.mockReturnValue(null)
+        refsMocks.resolveChannelRef.mockResolvedValue(
+            createChannel(500, 'Engineering', { id: 'CH500' }),
+        )
+    })
+
+    it('refuses to delete without --yes', async () => {
+        const client = createClient()
+        apiMocks.getCommsClient.mockResolvedValue(client)
+        const consoleSpy = captureConsole('log')
+
+        await runChannelCommand(['delete', 'Engineering'])
+
+        expect(client.channels.deleteChannel).not.toHaveBeenCalled()
+        expect(consoleSpy.mock.calls.some((c) => String(c[0]).includes('Use --yes'))).toBe(true)
+    })
+
+    it('deletes when --yes is passed', async () => {
+        const client = createClient()
+        apiMocks.getCommsClient.mockResolvedValue(client)
+        const consoleSpy = captureConsole('log')
+
+        await runChannelCommand(['delete', 'Engineering', '--yes'])
+
+        expect(refsMocks.resolveChannelRef).toHaveBeenCalledWith('Engineering', 1)
+        expect(client.channels.deleteChannel).toHaveBeenCalledWith('CH500')
+        expect(consoleSpy.mock.calls[0][0]).toContain('Engineering')
+    })
+
+    it('does not delete on --dry-run', async () => {
+        const client = createClient()
+        apiMocks.getCommsClient.mockResolvedValue(client)
+        const consoleSpy = captureConsole('log')
+
+        await runChannelCommand(['delete', 'Engineering', '--dry-run'])
+
+        expect(client.channels.deleteChannel).not.toHaveBeenCalled()
+        const text = consoleSpy.mock.calls.map((c) => String(c[0])).join('\n')
+        expect(text).toContain('delete channel')
+    })
+
+    it('does not delete when --yes is combined with --dry-run', async () => {
+        const client = createClient()
+        apiMocks.getCommsClient.mockResolvedValue(client)
+        const consoleSpy = captureConsole('log')
+
+        await runChannelCommand(['delete', 'Engineering', '--yes', '--dry-run'])
+
+        expect(client.channels.deleteChannel).not.toHaveBeenCalled()
+        const text = consoleSpy.mock.calls.map((c) => String(c[0])).join('\n')
+        expect(text).toContain('delete channel')
+    })
+
+    it('errors in --json mode without --yes before doing any lookups', async () => {
+        const client = createClient()
+        apiMocks.getCommsClient.mockResolvedValue(client)
+
+        await expect(runChannelCommand(['delete', 'Engineering', '--json'])).rejects.toHaveProperty(
+            'code',
+            'MISSING_YES_FLAG',
+        )
+        expect(client.channels.deleteChannel).not.toHaveBeenCalled()
+        expect(refsMocks.resolveChannelRef).not.toHaveBeenCalled()
+        expect(apiMocks.getCurrentWorkspaceId).not.toHaveBeenCalled()
+    })
+
+    it('translates a 403 from the API into a FORBIDDEN CliError', async () => {
+        const client = createClient()
+        client.channels.deleteChannel.mockRejectedValueOnce(
+            new CommsRequestError('Request failed with status 403', 403, {}),
+        )
+        apiMocks.getCommsClient.mockResolvedValue(client)
+
+        await expect(runChannelCommand(['delete', 'Engineering', '--yes'])).rejects.toHaveProperty(
+            'code',
+            'FORBIDDEN',
+        )
+    })
+
+    it('outputs JSON result with --yes --json', async () => {
+        const client = createClient()
+        apiMocks.getCommsClient.mockResolvedValue(client)
+        const consoleSpy = captureConsole('log')
+
+        await runChannelCommand(['delete', 'Engineering', '--yes', '--json'])
+
+        expect(JSON.parse(consoleSpy.mock.calls[0][0])).toEqual({ id: 'CH500', deleted: true })
+    })
+})
+
+describe('channels archive', () => {
+    beforeEach(() => {
+        vi.clearAllMocks()
+        apiMocks.getCurrentWorkspaceId.mockResolvedValue(1)
+        refsMocks.getDirectChannelId.mockReturnValue(null)
+        refsMocks.resolveChannelRef.mockResolvedValue(
+            createChannel(500, 'Engineering', { id: 'CH500' }),
+        )
+    })
+
+    it('archives the resolved channel', async () => {
+        const client = createClient()
+        apiMocks.getCommsClient.mockResolvedValue(client)
+        const consoleSpy = captureConsole('log')
+
+        await runChannelCommand(['archive', 'Engineering'])
+
+        expect(refsMocks.resolveChannelRef).toHaveBeenCalledWith('Engineering', 1)
+        expect(client.channels.archiveChannel).toHaveBeenCalledWith('CH500')
+        expect(consoleSpy.mock.calls[0][0]).toContain('archived')
+    })
+
+    it('does not call the API on --dry-run', async () => {
+        const client = createClient()
+        apiMocks.getCommsClient.mockResolvedValue(client)
+        const consoleSpy = captureConsole('log')
+
+        await runChannelCommand(['archive', 'Engineering', '--dry-run'])
+
+        expect(client.channels.archiveChannel).not.toHaveBeenCalled()
+        const text = consoleSpy.mock.calls.map((c) => String(c[0])).join('\n')
+        expect(text).toContain('archive channel')
+    })
+
+    it('outputs JSON with --json', async () => {
+        const client = createClient()
+        apiMocks.getCommsClient.mockResolvedValue(client)
+        const consoleSpy = captureConsole('log')
+
+        await runChannelCommand(['archive', 'Engineering', '--json'])
+
+        expect(JSON.parse(consoleSpy.mock.calls[0][0])).toEqual({ id: 'CH500', archived: true })
+    })
+
+    it('skips the API call when channel is already archived', async () => {
+        refsMocks.resolveChannelRef.mockResolvedValue(
+            createChannel(500, 'Engineering', { id: 'CH500', archived: true }),
+        )
+        const client = createClient()
+        apiMocks.getCommsClient.mockResolvedValue(client)
+        const consoleSpy = captureConsole('log')
+
+        await runChannelCommand(['archive', 'Engineering'])
+
+        expect(client.channels.archiveChannel).not.toHaveBeenCalled()
+        expect(consoleSpy.mock.calls[0][0]).toContain('already in target state')
+    })
+})
+
+describe('channels unarchive', () => {
+    beforeEach(() => {
+        vi.clearAllMocks()
+        apiMocks.getCurrentWorkspaceId.mockResolvedValue(1)
+        refsMocks.getDirectChannelId.mockReturnValue(null)
+        refsMocks.resolveChannelRef.mockResolvedValue(
+            createChannel(500, 'Engineering', { id: 'CH500', archived: true }),
+        )
+    })
+
+    it('unarchives the resolved channel', async () => {
+        const client = createClient()
+        apiMocks.getCommsClient.mockResolvedValue(client)
+        const consoleSpy = captureConsole('log')
+
+        await runChannelCommand(['unarchive', 'id:CH500'])
+
+        expect(refsMocks.resolveChannelRef).toHaveBeenCalledWith('id:CH500', 1)
+        expect(client.channels.unarchiveChannel).toHaveBeenCalledWith('CH500')
+        expect(consoleSpy.mock.calls[0][0]).toContain('unarchived')
+    })
+
+    it('does not call the API on --dry-run', async () => {
+        const client = createClient()
+        apiMocks.getCommsClient.mockResolvedValue(client)
+        const consoleSpy = captureConsole('log')
+
+        await runChannelCommand(['unarchive', 'id:CH500', '--dry-run'])
+
+        expect(client.channels.unarchiveChannel).not.toHaveBeenCalled()
+        const text = consoleSpy.mock.calls.map((c) => String(c[0])).join('\n')
+        expect(text).toContain('unarchive channel')
+    })
+
+    it('outputs JSON with --json', async () => {
+        const client = createClient()
+        apiMocks.getCommsClient.mockResolvedValue(client)
+        const consoleSpy = captureConsole('log')
+
+        await runChannelCommand(['unarchive', 'id:CH500', '--json'])
+
+        expect(JSON.parse(consoleSpy.mock.calls[0][0])).toEqual({ id: 'CH500', archived: false })
+    })
+})
+
+const lifecycleCommands = [
+    { name: 'delete', extraArgs: ['--yes'], method: 'deleteChannel', archived: false },
+    { name: 'archive', extraArgs: [], method: 'archiveChannel', archived: false },
+    { name: 'unarchive', extraArgs: [], method: 'unarchiveChannel', archived: true },
+] as const
+
+describe('channels lifecycle --workspace', () => {
+    beforeEach(() => {
+        vi.clearAllMocks()
+        apiMocks.getCurrentWorkspaceId.mockResolvedValue(1)
+        refsMocks.getDirectChannelId.mockReturnValue(null)
+        refsMocks.resolveWorkspaceRef.mockResolvedValue({ id: 42, name: 'Other' })
+    })
+
+    for (const cmd of lifecycleCommands) {
+        it(`${cmd.name} resolves --workspace and passes its ID to resolveChannelRef`, async () => {
+            refsMocks.resolveChannelRef.mockResolvedValue(
+                createChannel(500, 'Engineering', { id: 'CH500', archived: cmd.archived }),
+            )
+            const client = createClient()
+            apiMocks.getCommsClient.mockResolvedValue(client)
+            captureConsole('log')
+
+            await runChannelCommand([
+                cmd.name,
+                'Engineering',
+                '--workspace',
+                'Other',
+                ...cmd.extraArgs,
+            ])
+
+            expect(refsMocks.resolveWorkspaceRef).toHaveBeenCalledWith('Other')
+            expect(refsMocks.resolveChannelRef).toHaveBeenCalledWith('Engineering', 42)
+            expect(client.channels[cmd.method]).toHaveBeenCalledWith('CH500')
+            expect(apiMocks.getCurrentWorkspaceId).not.toHaveBeenCalled()
+        })
+    }
+})
+
+describe('channels lifecycle direct refs', () => {
+    beforeEach(() => {
+        vi.clearAllMocks()
+        refsMocks.getDirectChannelId.mockReturnValue('CH500')
+    })
+
+    for (const cmd of lifecycleCommands) {
+        it(`${cmd.name} fetches a direct ref by ID without resolving a workspace`, async () => {
+            const client = createClient()
+            client.channels.getChannel.mockResolvedValue(
+                createChannel(500, 'Engineering', { id: 'CH500', archived: cmd.archived }),
+            )
+            apiMocks.getCommsClient.mockResolvedValue(client)
+            captureConsole('log')
+
+            await runChannelCommand([cmd.name, 'id:CH500', ...cmd.extraArgs])
+
+            expect(client.channels.getChannel).toHaveBeenCalledWith('CH500')
+            expect(refsMocks.resolveChannelRef).not.toHaveBeenCalled()
+            expect(refsMocks.resolveWorkspaceRef).not.toHaveBeenCalled()
+            expect(apiMocks.getCurrentWorkspaceId).not.toHaveBeenCalled()
+            expect(client.channels[cmd.method]).toHaveBeenCalledWith('CH500')
+        })
+    }
+})