tabwright 1.0.0

package/src/capability-auth.ts

@@ -0,0 +1,249 @@
+import path from 'node:path'
+import {
+  readCapabilitySecrets,
+  requireCapability,
+  writeCapabilitySecrets,
+  type CapabilityRecord,
+} from './capability-registry.js'
+import { writeStoredCapabilityAuthState } from './capability-auth-state.js'
+import type { ExecuteResult } from './executor.js'
+
+export interface CapabilityAuthExecutor {
+  execute(
+    code: string,
+    timeout?: number,
+    options?: { includeStructuredResult?: boolean },
+  ): Promise<ExecuteResult>
+}
+
+export interface CapabilityAuthRefreshResult {
+  capability: CapabilityRecord
+  saved: boolean
+  secretKey: string
+  cookieCount: number
+  cookieNames: string[]
+  urls: string[]
+  expiresAt?: string
+  path: string
+}
+
+export interface CapabilityAuthCookie {
+  name: string
+  value: string
+  expires?: number
+}
+
+export async function refreshCapabilityAuthWithExecutor(options: {
+  executor: CapabilityAuthExecutor
+  id: string
+  cwd?: string
+  timeout?: number
+  browserKey?: string
+}): Promise<CapabilityAuthRefreshResult> {
+  const capability = requireCapability({ id: options.id, cwd: options.cwd })
+  if (capability.manifest.auth.type !== 'cookie' || capability.manifest.auth.refresh !== 'from-browser') {
+    throw new Error(`Capability ${options.id} does not declare browser-refreshable cookie auth`)
+  }
+  if (capability.manifest.auth.browserUrls.length === 0) {
+    throw new Error(`Capability ${options.id} auth.browserUrls is required for cookie refresh`)
+  }
+
+  const executeResult = await options.executor.execute(buildCookieRefreshCode({ capability }), options.timeout || 10000, {
+    includeStructuredResult: true,
+  })
+  if (executeResult.isError) {
+    throw new Error(`Failed to refresh capability auth: ${executeResult.text}`)
+  }
+  const parsed = parseRefreshResult(executeResult.structuredResult)
+  writeStoredCapabilityAuthState({
+    capability,
+    state: {
+      schemaVersion: 1,
+      refreshedAt: new Date().toISOString(),
+      expiresAt: parsed.expiresAt,
+      cookieNames: parsed.cookieNames,
+      browserKey: options.browserKey,
+    },
+  })
+  return {
+    capability,
+    ...parsed,
+  }
+}
+
+function buildCookieRefreshCode(options: { capability: CapabilityRecord }): string {
+  const secretKey = options.capability.manifest.auth.secretKey || 'cookieHeader'
+  const secretsPath = path.join(options.capability.dir, 'secrets.json')
+  return [
+    'const fs = await globalThis.import("node:fs")',
+    `const urls = ${JSON.stringify(options.capability.manifest.auth.browserUrls)};`,
+    `const requiredCookieNames = ${JSON.stringify(options.capability.manifest.auth.requiredCookieNames)};`,
+    `const secretKey = ${JSON.stringify(secretKey)};`,
+    `const secretsPath = ${JSON.stringify(secretsPath)};`,
+    `const secretsDir = ${JSON.stringify(options.capability.dir)};`,
+    'const cdp = await getCDPSession({ page });',
+    'const result = await cdp.send("Network.getCookies", { urls });',
+    'const cookies = Array.isArray(result.cookies) ? result.cookies : [];',
+    'const cookieNames = cookies.map((cookie) => cookie.name).filter((name) => typeof name === "string");',
+    'const missingCookieNames = requiredCookieNames.filter((name) => !cookieNames.includes(name));',
+    'if (missingCookieNames.length > 0) {',
+    '  throw new Error(`Missing required cookies: ${missingCookieNames.join(", ")}`);',
+    '}',
+    'const cookieHeader = cookies.map((cookie) => `${cookie.name}=${cookie.value}`).join("; ");',
+    'if (!cookieHeader) {',
+    '  throw new Error("No cookies were available for capability auth refresh");',
+    '}',
+    'const existingSecrets = fs.existsSync(secretsPath) ? JSON.parse(fs.readFileSync(secretsPath, "utf-8")) : {};',
+    'const nextSecrets = {',
+    '  ...existingSecrets,',
+    '  [secretKey]: cookieHeader,',
+    '  updatedAt: new Date().toISOString(),',
+    '};',
+    'fs.mkdirSync(secretsDir, { recursive: true });',
+    'fs.writeFileSync(secretsPath, JSON.stringify(nextSecrets, null, 2), { mode: 0o600 });',
+    'if (process.platform !== "win32") {',
+    '  fs.chmodSync(secretsPath, 0o600);',
+    '}',
+    'const expiryCookies = requiredCookieNames.length > 0',
+    '  ? cookies.filter((cookie) => requiredCookieNames.includes(cookie.name))',
+    '  : [];',
+    'const expiryValues = expiryCookies.map((cookie) => cookie.expires).filter((expires) => typeof expires === "number" && expires > 0);',
+    'const expiresAt = expiryCookies.length > 0 && expiryValues.length === expiryCookies.length',
+    '  ? new Date(Math.min(...expiryValues) * 1000).toISOString()',
+    '  : undefined;',
+    'return {',
+    '  saved: true,',
+    '  secretKey,',
+    '  cookieCount: cookies.length,',
+    '  cookieNames,',
+    '  urls,',
+    '  expiresAt,',
+    '  path: secretsPath,',
+    '};',
+    `//# sourceURL=tabwright-capability-auth://${options.capability.manifest.id}`,
+    '',
+  ].join('\n')
+}
+
+export function refreshCapabilityAuthFromCookies(options: {
+  id: string
+  cookies: CapabilityAuthCookie[]
+  cwd?: string
+  browserKey?: string
+}): CapabilityAuthRefreshResult {
+  const capability = requireBrowserRefreshableCookieCapability({ id: options.id, cwd: options.cwd })
+  const cookieNames = options.cookies.map((cookie) => {
+    return cookie.name
+  })
+  const missingCookieNames = capability.manifest.auth.requiredCookieNames.filter((name) => {
+    return !cookieNames.includes(name)
+  })
+  if (missingCookieNames.length > 0) {
+    throw new Error(`Missing required cookies: ${missingCookieNames.join(', ')}`)
+  }
+  const cookieHeader = options.cookies
+    .map((cookie) => {
+      return `${cookie.name}=${cookie.value}`
+    })
+    .join('; ')
+  if (!cookieHeader) {
+    throw new Error('No cookies were available for capability auth refresh')
+  }
+
+  const secretKey = capability.manifest.auth.secretKey || 'cookieHeader'
+  const existingSecrets = readCapabilitySecrets({ capability })
+  writeCapabilitySecrets({
+    capability,
+    secrets: {
+      ...existingSecrets,
+      [secretKey]: cookieHeader,
+      updatedAt: new Date().toISOString(),
+    },
+  })
+
+  const requiredCookies = capability.manifest.auth.requiredCookieNames.map((name) => {
+    return options.cookies.find((cookie) => {
+      return cookie.name === name
+    })
+  })
+  const expiryValues = requiredCookies
+    .map((cookie) => {
+      return cookie?.expires
+    })
+    .filter((expires): expires is number => {
+      return typeof expires === 'number' && expires > 0
+    })
+  // Do not invent an expiry for session cookies: only all timestamped required cookies produce a deadline.
+  const expiresAt =
+    requiredCookies.length > 0 && expiryValues.length === requiredCookies.length
+      ? new Date(Math.min(...expiryValues) * 1000).toISOString()
+      : undefined
+  writeStoredCapabilityAuthState({
+    capability,
+    state: {
+      schemaVersion: 1,
+      refreshedAt: new Date().toISOString(),
+      expiresAt,
+      cookieNames,
+      browserKey: options.browserKey,
+    },
+  })
+  return {
+    capability,
+    saved: true,
+    secretKey,
+    cookieCount: options.cookies.length,
+    cookieNames,
+    urls: capability.manifest.auth.browserUrls,
+    expiresAt,
+    path: path.join(capability.dir, 'secrets.json'),
+  }
+}
+
+function parseRefreshResult(value: unknown): Omit<CapabilityAuthRefreshResult, 'capability'> {
+  if (!isRecord(value)) {
+    throw new Error('Capability auth refresh did not return an object')
+  }
+  const saved = value.saved === true
+  const secretKey = typeof value.secretKey === 'string' ? value.secretKey : ''
+  const cookieCount = typeof value.cookieCount === 'number' ? value.cookieCount : 0
+  const cookieNames = Array.isArray(value.cookieNames)
+    ? value.cookieNames.filter((item): item is string => {
+        return typeof item === 'string'
+      })
+    : []
+  const urls = Array.isArray(value.urls)
+    ? value.urls.filter((item): item is string => {
+        return typeof item === 'string'
+      })
+    : []
+  const expiresAt = typeof value.expiresAt === 'string' ? value.expiresAt : undefined
+  const secretsPath = typeof value.path === 'string' ? value.path : ''
+  if (!saved || !secretKey || !secretsPath) {
+    throw new Error('Capability auth refresh returned an incomplete result')
+  }
+  return {
+    saved,
+    secretKey,
+    cookieCount,
+    cookieNames,
+    urls,
+    expiresAt,
+    path: secretsPath,
+  }
+}
+
+function requireBrowserRefreshableCookieCapability(options: { id: string; cwd?: string }): CapabilityRecord {
+  const capability = requireCapability({ id: options.id, cwd: options.cwd })
+  if (capability.manifest.auth.type !== 'cookie' || capability.manifest.auth.refresh !== 'from-browser') {
+    throw new Error(`Capability ${options.id} does not declare browser-refreshable cookie auth`)
+  }
+  if (capability.manifest.auth.browserUrls.length === 0) {
+    throw new Error(`Capability ${options.id} auth.browserUrls is required for cookie refresh`)
+  }
+  return capability
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}

package/src/capability-cli-confirmation.test.ts

@@ -0,0 +1,90 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+import { fileURLToPath } from 'node:url'
+import { describe, expect, test } from 'vitest'
+import { createCapability, updateCapabilityManifest, updateCapabilityScript } from './capability-registry.js'
+
+const execFileAsync = promisify(execFile)
+const currentDir = path.dirname(fileURLToPath(import.meta.url))
+const tabwrightDir = path.resolve(currentDir, '..')
+const viteNodeBinary = path.join(
+  tabwrightDir,
+  'node_modules',
+  '.bin',
+  process.platform === 'win32' ? 'vite-node.cmd' : 'vite-node',
+)
+const cliPath = path.join(currentDir, 'cli.ts')
+
+function createTempDir(prefix: string): string {
+  const tempRoot = path.join(tabwrightDir, 'tmp')
+  fs.mkdirSync(tempRoot, { recursive: true })
+  return fs.mkdtempSync(path.join(tempRoot, prefix))
+}
+
+function runCli(options: { cwd: string; args: string[] }): Promise<{ stdout: string; stderr: string }> {
+  return execFileAsync(viteNodeBinary, [cliPath, ...options.args], {
+    cwd: options.cwd,
+    env: process.env,
+  })
+}
+
+describe('capability CLI confirmation', () => {
+  test('force cannot execute a confirmation-required script without the exact id', async () => {
+    const cwd = createTempDir('capability-cli-confirmation-')
+    try {
+      const capability = createCapability({
+        id: 'confirmed-cli-write',
+        location: 'project',
+        cwd,
+        runtime: 'node',
+      })
+      updateCapabilityScript({
+        id: capability.manifest.id,
+        cwd,
+        source: 'artifacts.writeText({ filename: "executed.txt", text: "yes" }); return { ok: true };',
+      })
+      updateCapabilityManifest({
+        id: capability.manifest.id,
+        cwd,
+        allowUnvalidatedTrust: true,
+        patch: { status: 'trusted', sideEffect: 'write', requiresConfirmation: true },
+      })
+      const markerPath = path.join(capability.dir, 'artifacts', 'executed.txt')
+
+      await expect(
+        runCli({
+          cwd,
+          args: ['capability', 'run', capability.manifest.id, '--force', '--input-json', '{}', '--json'],
+        }),
+      ).rejects.toMatchObject({
+        code: 1,
+        stderr: expect.stringContaining('requires explicit user confirmation'),
+      })
+      expect(fs.existsSync(markerPath)).toBe(false)
+
+      const runStartedAt = Date.now()
+      const { stdout, stderr } = await runCli({
+        cwd,
+        args: [
+          'capability',
+          'run',
+          capability.manifest.id,
+          '--force',
+          '--confirm',
+          capability.manifest.id,
+          '--input-json',
+          '{}',
+          '--json',
+        ],
+      })
+      expect(JSON.parse(stdout)).toMatchObject({ capability: capability.manifest.id, output: { ok: true } })
+      expect(stderr).toBe('')
+      expect(fs.readFileSync(markerPath, 'utf-8')).toBe('yes')
+      expect(Date.now() - runStartedAt).toBeLessThan(5000)
+    } finally {
+      fs.rmSync(cwd, { recursive: true, force: true })
+    }
+  }, 30000)
+})

package/src/capability-options.test.ts

@@ -0,0 +1,89 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { describe, expect, test } from 'vitest'
+import { createCapability } from './capability-registry.js'
+import { listCapabilityOptions } from './capability-options.js'
+
+function createTempDir(prefix: string): string {
+  const tempRoot = path.join(process.cwd(), 'tmp')
+  fs.mkdirSync(tempRoot, { recursive: true })
+  return fs.mkdtempSync(path.join(tempRoot, prefix))
+}
+
+describe('capability options view', () => {
+  test('lists capabilities with read-only agent skill status', () => {
+    const cwd = createTempDir('capability-options-')
+    try {
+      const capability = createCapability({
+        id: 'options-tool',
+        title: 'Options Tool',
+        location: 'project',
+        cwd,
+      })
+      const skillPath = path.join(capability.dir, 'agent-skills', 'codex', 'SKILL.md')
+      fs.mkdirSync(path.dirname(skillPath), { recursive: true })
+      fs.writeFileSync(skillPath, '---\nname: options-tool\n---\n')
+
+      const response = listCapabilityOptions({ cwd })
+      expect(response.cwd).toBe(cwd)
+      expect(response.capabilities).toEqual(
+        expect.arrayContaining([
+          expect.objectContaining({
+            id: 'options-tool',
+            title: 'Options Tool',
+            agentSkill: expect.objectContaining({
+              draftExists: true,
+              initCommand: 'tabwright capability skill init options-tool',
+              installCommand: 'tabwright capability skill install options-tool',
+            }),
+          }),
+        ]),
+      )
+    } finally {
+      fs.rmSync(cwd, { recursive: true, force: true })
+    }
+  })
+
+  test('keeps the capability list available when run logs or entry scripts are damaged', () => {
+    const cwd = createTempDir('capability-options-damaged-')
+    try {
+      const damagedRuns = createCapability({
+        id: 'damaged-runs',
+        title: 'Damaged Runs',
+        location: 'project',
+        cwd,
+      })
+      fs.writeFileSync(path.join(damagedRuns.dir, 'runs.jsonl'), '{"id":\n')
+
+      const missingScript = createCapability({
+        id: 'missing-script',
+        title: 'Missing Script',
+        location: 'project',
+        cwd,
+      })
+      fs.rmSync(missingScript.scriptPath)
+
+      const response = listCapabilityOptions({ cwd })
+      const damagedRunsItem = response.capabilities.find((capability) => capability.id === 'damaged-runs')
+      const missingScriptItem = response.capabilities.find((capability) => capability.id === 'missing-script')
+
+      expect(damagedRunsItem).toEqual(expect.objectContaining({ recentRuns: [] }))
+      expect(missingScriptItem).toEqual(
+        expect.objectContaining({
+          lifecycle: expect.objectContaining({
+            stage: 'drifted',
+            contractHealth: expect.objectContaining({
+              state: 'drifted',
+              reasons: expect.arrayContaining([expect.stringContaining('Cannot validate the capability entry script')]),
+            }),
+          }),
+          autonomousInvocation: expect.objectContaining({
+            allowed: false,
+          }),
+        }),
+      )
+    } finally {
+      fs.rmSync(cwd, { recursive: true, force: true })
+    }
+  })
+})

package/src/capability-options.ts

@@ -0,0 +1,57 @@
+import {
+  listCapabilities,
+  toCapabilityContract,
+  type CapabilityRecord,
+} from './capability-registry.js'
+import {
+  getCapabilityAgentSkillStatus,
+  type CapabilityAgentSkillStatus,
+} from './capability-agent-skill.js'
+import { getCapabilityAuthState } from './capability-auth-state.js'
+
+export interface CapabilityOptionsItem extends Record<string, unknown> {
+  agentSkill: CapabilityAgentSkillStatus
+}
+
+export interface CapabilityOptionsListResponse {
+  cwd: string
+  capabilities: CapabilityOptionsItem[]
+}
+
+export interface CapabilityOptionsDetailResponse {
+  cwd: string
+  capability: CapabilityOptionsItem
+}
+
+export function listCapabilityOptions(options: { cwd: string }): CapabilityOptionsListResponse {
+  return {
+    cwd: options.cwd,
+    capabilities: listCapabilities({ cwd: options.cwd }).map((capability) => {
+      return toCapabilityOptionsItem(capability)
+    }),
+  }
+}
+
+export function getCapabilityOptionsDetail(options: {
+  cwd: string
+  id: string
+}): CapabilityOptionsDetailResponse | null {
+  const capability = listCapabilities({ cwd: options.cwd }).find((candidate) => {
+    return candidate.manifest.id === options.id
+  })
+  if (!capability) {
+    return null
+  }
+  return {
+    cwd: options.cwd,
+    capability: toCapabilityOptionsItem(capability),
+  }
+}
+
+function toCapabilityOptionsItem(capability: CapabilityRecord): CapabilityOptionsItem {
+  return {
+    ...toCapabilityContract(capability),
+    authState: getCapabilityAuthState({ capability }),
+    agentSkill: getCapabilityAgentSkillStatus({ capability }),
+  }
+}

package/src/capability-package.test.ts

@@ -0,0 +1,204 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { installCapabilityPackage, packCapability } from './capability-package.js'
+import { createCapability, updateCapabilityManifest, updateCapabilityScript, writeCapabilitySecrets } from './capability-registry.js'
+
+describe('capability package sharing', () => {
+  let testRoot: string
+  let sourceCwd: string
+  let recipientCwd: string
+
+  beforeEach(() => {
+    const tmpRoot = path.join(process.cwd(), 'tmp')
+    fs.mkdirSync(tmpRoot, { recursive: true })
+    testRoot = fs.mkdtempSync(path.join(tmpRoot, 'capability-package-'))
+    sourceCwd = path.join(testRoot, 'source')
+    recipientCwd = path.join(testRoot, 'recipient')
+    fs.mkdirSync(sourceCwd, { recursive: true })
+    fs.mkdirSync(recipientCwd, { recursive: true })
+  })
+
+  afterEach(() => {
+    vi.unstubAllGlobals()
+    fs.rmSync(testRoot, { recursive: true, force: true })
+  })
+
+  it('packs only shareable files and installs the recipient copy as draft', async () => {
+    const source = createCapability({
+      id: 'shared-query',
+      title: 'Shared query',
+      description: 'Queries shared data.',
+      location: 'project',
+      cwd: sourceCwd,
+      runtime: 'node',
+    })
+    updateCapabilityScript({
+      id: source.manifest.id,
+      cwd: sourceCwd,
+      source: 'return { ok: true }\n',
+    })
+    updateCapabilityManifest({
+      id: source.manifest.id,
+      cwd: sourceCwd,
+      allowUnvalidatedTrust: true,
+      patch: {
+        status: 'trusted',
+        auth: {
+          type: 'cookie',
+          refresh: 'from-browser',
+          browserUrls: ['https://example.com'],
+          requiredCookieNames: ['session'],
+          failureSignals: ['unauthorized'],
+        },
+      },
+    })
+    const capabilityDir = source.dir
+    writeCapabilitySecrets({ capability: source, secrets: { cookieHeader: 'secret-value' } })
+    fs.writeFileSync(path.join(capabilityDir, 'runs.jsonl'), '{"private":"run"}\n')
+    fs.mkdirSync(path.join(capabilityDir, 'artifacts'), { recursive: true })
+    fs.writeFileSync(path.join(capabilityDir, 'artifacts', 'private.json'), '{}\n')
+    fs.mkdirSync(path.join(capabilityDir, 'agent-skills', 'codex', 'agents'), { recursive: true })
+    fs.writeFileSync(
+      path.join(capabilityDir, 'agent-skills', 'codex', 'SKILL.md'),
+      '---\nname: shared-query\ndescription: Use shared query.\n---\n',
+    )
+    fs.writeFileSync(path.join(capabilityDir, 'agent-skills', 'codex', 'agents', 'openai.yaml'), 'name: Shared query\n')
+
+    const archivePath = path.join(testRoot, 'shared-query.tgz')
+    const packed = await packCapability({ id: source.manifest.id, cwd: sourceCwd, output: archivePath })
+    const installed = await installCapabilityPackage({
+      source: packed.path,
+      cwd: recipientCwd,
+      location: 'project',
+    })
+
+    expect(packed.files).toEqual([
+      'README.md',
+      'agent-skills/codex/SKILL.md',
+      'agent-skills/codex/agents/openai.yaml',
+      'capability.json',
+      'script.js',
+    ])
+    expect(installed.capability.manifest.status).toBe('draft')
+    expect(fs.readFileSync(installed.capability.scriptPath, 'utf-8')).toBe('return { ok: true }\n')
+    expect(installed.agentSkillAvailable).toBe(true)
+    expect(fs.existsSync(path.join(installed.capability.dir, 'secrets.json'))).toBe(false)
+    expect(fs.existsSync(path.join(installed.capability.dir, 'runs.jsonl'))).toBe(false)
+    expect(fs.existsSync(path.join(installed.capability.dir, 'artifacts'))).toBe(false)
+    expect(installed.integrity).toBe(packed.integrity)
+  })
+
+  it('installs directly from a capability directory without copying local state', async () => {
+    const source = createCapability({
+      id: 'directory-query',
+      location: 'project',
+      cwd: sourceCwd,
+      runtime: 'node',
+    })
+    updateCapabilityScript({ id: source.manifest.id, cwd: sourceCwd, source: 'return input\n' })
+    writeCapabilitySecrets({ capability: source, secrets: { token: 'do-not-copy' } })
+
+    const installed = await installCapabilityPackage({
+      source: source.dir,
+      cwd: recipientCwd,
+      location: 'project',
+    })
+
+    expect(installed.capability.manifest.status).toBe('draft')
+    expect(fs.existsSync(path.join(installed.capability.dir, 'secrets.json'))).toBe(false)
+    expect(installed.files).toEqual(['README.md', 'capability.json', 'script.js'])
+  })
+
+  it('requires force before replacing package files and clears recipient authentication', async () => {
+    const source = createCapability({
+      id: 'replace-query',
+      location: 'project',
+      cwd: sourceCwd,
+      runtime: 'node',
+    })
+    updateCapabilityScript({ id: source.manifest.id, cwd: sourceCwd, source: 'return { version: 2 }\n' })
+    const archive = await packCapability({
+      id: source.manifest.id,
+      cwd: sourceCwd,
+      output: path.join(testRoot, 'replace-query.tgz'),
+    })
+    const existing = createCapability({
+      id: source.manifest.id,
+      location: 'project',
+      cwd: recipientCwd,
+      runtime: 'node',
+    })
+    writeCapabilitySecrets({ capability: existing, secrets: { token: 'recipient-only' } })
+    fs.writeFileSync(path.join(existing.dir, 'auth-state.json'), '{"schemaVersion":1}\n')
+
+    await expect(
+      installCapabilityPackage({ source: archive.path, cwd: recipientCwd, location: 'project' }),
+    ).rejects.toThrow('Use --force')
+
+    const installed = await installCapabilityPackage({
+      source: archive.path,
+      cwd: recipientCwd,
+      location: 'project',
+      overwrite: true,
+    })
+    expect(fs.readFileSync(installed.capability.scriptPath, 'utf-8')).toBe('return { version: 2 }\n')
+    expect(fs.existsSync(path.join(installed.capability.dir, 'secrets.json'))).toBe(false)
+    expect(fs.existsSync(path.join(installed.capability.dir, 'auth-state.json'))).toBe(false)
+  })
+
+  it('installs a package downloaded from an HTTPS URL', async () => {
+    const source = createCapability({
+      id: 'remote-query',
+      location: 'project',
+      cwd: sourceCwd,
+      runtime: 'node',
+    })
+    const packed = await packCapability({
+      id: source.manifest.id,
+      cwd: sourceCwd,
+      output: path.join(testRoot, 'remote-query.tgz'),
+    })
+    const archive = fs.readFileSync(packed.path)
+    vi.stubGlobal(
+      'fetch',
+      vi.fn(async () => {
+        return new Response(archive, {
+          status: 200,
+          headers: { 'content-length': String(archive.length) },
+        })
+      }),
+    )
+
+    const installed = await installCapabilityPackage({
+      source: 'https://example.com/remote-query.tgz',
+      cwd: recipientCwd,
+      location: 'project',
+    })
+
+    expect(installed.source).toBe('https://example.com/remote-query.tgz')
+    expect(installed.capability.manifest.id).toBe('remote-query')
+    expect(installed.capability.manifest.status).toBe('draft')
+  })
+
+  it('requires force before overwriting an existing package archive', async () => {
+    const source = createCapability({
+      id: 'archive-overwrite',
+      location: 'project',
+      cwd: sourceCwd,
+      runtime: 'node',
+    })
+    const output = path.join(testRoot, 'archive-overwrite.tgz')
+    await packCapability({ id: source.manifest.id, cwd: sourceCwd, output })
+
+    await expect(packCapability({ id: source.manifest.id, cwd: sourceCwd, output })).rejects.toThrow('Use --force')
+
+    const overwritten = await packCapability({
+      id: source.manifest.id,
+      cwd: sourceCwd,
+      output,
+      overwrite: true,
+    })
+    expect(fs.existsSync(overwritten.path)).toBe(true)
+  })
+})