@robota-sdk/agent-command 3.0.0-beta.100

package/src/devices/devices-command-port.ts

@@ -0,0 +1,143 @@
+/**
+ * What `/devices` needs from the host that keeps this device's identity.
+ *
+ * The host owns every secret: the recovery phrase is shown and read on the host's own terminal, and
+ * private keys live in its credential store. What crosses this port back to the command is ids,
+ * names, times and closed refusal reasons — nothing the command formats can carry a secret, because
+ * the command never receives one. A thrown error's message is the host's promise to the same effect.
+ */
+
+export interface IDeviceListEntry {
+  readonly deviceId: string;
+  readonly name: string;
+  readonly thisDevice: boolean;
+  /** Whether this entry is known to hold the device-signing key. Only known for this device. */
+  readonly holdsSigningKey: boolean;
+  readonly certificateExpiresAt: number;
+}
+
+export interface IDevicesView {
+  readonly userId: string;
+  readonly devices: readonly IDeviceListEntry[];
+  readonly revokedDeviceCount: number;
+  /** When the roster and revocation list this device holds stop being accepted. */
+  readonly listsExpireAt: number;
+}
+
+/** Why an operation did not happen. Closed, so no free text from the secret path reaches a result. */
+export type TDevicesRefusal =
+  /** No interactive terminal: the phrase is never shown on or read from anything else. */
+  | 'no-terminal'
+  | 'not-initialized'
+  | 'already-initialized'
+  /** The operator cancelled at the terminal. */
+  | 'cancelled'
+  /** The re-typed words or passphrase did not match. */
+  | 'confirmation-failed'
+  | 'phrase-invalid'
+  /** The phrase is valid but derives another identity than this device's. */
+  | 'phrase-mismatch'
+  | 'no-signing-key'
+  | 'signing-key-expired'
+  | 'unknown-device'
+  | 'ambiguous-device'
+  | 'self-revocation'
+  /** Another process changed the identity while this operation waited on the operator. */
+  | 'changed-concurrently'
+  /** No signaling relay is configured to meet the other device through. */
+  | 'no-relay'
+  /** What was typed is not an enrollment code. */
+  | 'code-invalid'
+  /** The code was typed on the command line, where history keeps it. */
+  | 'code-on-command-line'
+  /** No device waits for that code or proved it: wrong, expired, already used, or something in between. */
+  | 'code-not-accepted'
+  /** Nobody joined before the code expired. */
+  | 'enrollment-expired'
+  /** Too many attempts failed to prove the code; it no longer works. */
+  | 'too-many-attempts'
+  /** The operator of either device declined. */
+  | 'enrollment-declined'
+  /** An operator did not answer in time. */
+  | 'enrollment-timed-out'
+  /** The connection or the exchange with the other device failed partway. */
+  | 'enrollment-failed';
+
+export type TDevicesOutcome<T> =
+  | { readonly ok: true; readonly value: T }
+  | { readonly ok: false; readonly reason: TDevicesRefusal };
+
+export interface IDevicesInitResult {
+  readonly userId: string;
+  readonly deviceId: string;
+  readonly signingKeyId: string;
+  /** Where the private keys were kept, for the operator. */
+  readonly keyStorage?: string;
+}
+
+export interface IDevicesRecoverResult {
+  readonly deviceId: string;
+  readonly signingKeyId: string;
+  readonly revokedSigningKeyCount: number;
+  /** Other devices that were certified by a retired signing key and must enrol again. */
+  readonly droppedDeviceCount: number;
+}
+
+export interface IDevicesRevokeResult {
+  readonly deviceId: string;
+  readonly name: string;
+}
+
+/** This session's endpoint in the device mesh. */
+export interface IDevicesMeshStatus {
+  /** `off`: the setting is off, or this run does not open the mesh. `failed`: it could not open. */
+  readonly state: 'off' | 'starting' | 'on' | 'failed';
+  /** Why it could not open, for `failed`. */
+  readonly reason?: string;
+  /** How this device looks for the others, in the operator's words. */
+  readonly sources: readonly string[];
+  /** The devices with an admitted link now. */
+  readonly linked: readonly {
+    readonly deviceId: string;
+    readonly name?: string;
+    readonly locality: 'same-host' | 'another-host';
+  }[];
+}
+
+export interface IDevicesAddResult {
+  readonly deviceId: string;
+  readonly name: string;
+  /** Whether the new device said it kept what it was given. */
+  readonly confirmed: boolean;
+}
+
+export interface IDevicesJoinResult {
+  readonly userId: string;
+  readonly deviceId: string;
+  readonly name: string;
+  /** Where the private keys were kept, for the operator. */
+  readonly keyStorage?: string;
+}
+
+export interface IDevicesCommandPort {
+  /** This device's view of the roster, or `undefined` when it has no identity yet. */
+  list(): Promise<IDevicesView | undefined>;
+  /** The device mesh as this session runs it. Absent on a host with no device mesh. */
+  meshStatus?(): IDevicesMeshStatus;
+  /** Create the identity. Runs on the operator terminal (it shows the phrase once). */
+  init(options: { readonly name?: string }): Promise<TDevicesOutcome<IDevicesInitResult>>;
+  /** Rotate the signing key from the phrase. Runs on the operator terminal. */
+  recover(): Promise<TDevicesOutcome<IDevicesRecoverResult>>;
+  /** Revoke a device by id prefix with the signing key. Confirms on the operator terminal. */
+  revoke(deviceIdPrefix: string): Promise<TDevicesOutcome<IDevicesRevokeResult>>;
+  /**
+   * Enrol another device with the signing key: show a one-time code, and certify the device that
+   * proves it once both operators confirm the string both devices show. Runs on the operator terminal.
+   */
+  add(): Promise<TDevicesOutcome<IDevicesAddResult>>;
+  /**
+   * Join the user's devices with a code another device shows, once both operators confirm the string
+   * both devices show. Runs on the operator terminal.
+   */
+  join(options: { readonly name?: string }): Promise<TDevicesOutcome<IDevicesJoinResult>>;
+}

package/src/devices/index.ts

@@ -0,0 +1,14 @@
+export { createDevicesCommandModule } from './devices-command-module.js';
+export type {
+  IDeviceListEntry,
+  IDevicesCommandPort,
+  IDevicesInitResult,
+  IDevicesMeshStatus,
+  IDevicesRecoverResult,
+  IDevicesAddResult,
+  IDevicesJoinResult,
+  IDevicesRevokeResult,
+  IDevicesView,
+  TDevicesOutcome,
+  TDevicesRefusal,
+} from './devices-command-port.js';

package/src/doctor/__tests__/doctor-command-module.test.ts

@@ -0,0 +1,145 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { createDoctorCommandModule } from '../doctor-command-module.js';
+import {
+  createDoctorFixture,
+  fixtureProviderDefinition,
+  installBrokenHome,
+} from './doctor-fixture.js';
+
+import type { IDoctorFixture } from './doctor-fixture.js';
+import { CommandRegistry, SystemCommandExecutor } from '@robota-sdk/agent-framework';
+import { createTestCommandHost } from '@robota-sdk/agent-framework/testing';
+
+import type { IUserInteraction, TActionResponse } from '@robota-sdk/agent-core';
+
+const fixtures: IDoctorFixture[] = [];
+afterEach(() => {
+  for (const fixture of fixtures.splice(0)) fixture.cleanup();
+});
+
+/** The published conformant double, with only the interaction port overridden. */
+function contextWith(interaction: IUserInteraction | undefined) {
+  return createTestCommandHost({ overrides: { getUserInteraction: () => interaction } });
+}
+
+function answering(
+  response: TActionResponse,
+): IUserInteraction & { ask: ReturnType<typeof vi.fn> } {
+  return { ask: vi.fn(async () => response) };
+}
+
+describe('/doctor command module (OBSERVABILITY-1991 TC-06)', () => {
+  it('advertises repair arguments consistently in the palette and executable metadata', () => {
+    const fixture = createDoctorFixture({ env: {} });
+    fixtures.push(fixture);
+    const module = createDoctorCommandModule(fixture.inputs, fixture.deps);
+    const registry = new CommandRegistry();
+    registry.addModule(module);
+    const executor = new SystemCommandExecutor([...(module.systemCommands ?? [])]);
+    const entry = registry.getCommands().find((command) => command.name === 'doctor');
+    const command = executor.getCommand('doctor');
+    expect(entry).toMatchObject({ argumentHint: '[repair <check-id>]', modelInvocable: false });
+    expect(command).toMatchObject({
+      argumentHint: '[repair <check-id>]',
+      modelInvocable: false,
+      userInvocable: true,
+      requiresPermission: false,
+      lifecycle: 'inline',
+    });
+    expect(registry.getCapabilityDescriptors()).toContainEqual(
+      expect.objectContaining({
+        name: 'doctor',
+        argumentHint: '[repair <check-id>]',
+        userInvocable: true,
+        modelInvocable: false,
+      }),
+    );
+    expect(command?.description).toBe(entry?.description);
+    expect(executor.isModelInvocable('doctor')).toBe(false);
+  });
+
+  it('renders the same check set without constructing a provider or submitting input', async () => {
+    const createProvider = vi.fn(() => {
+      throw new Error('must not be called');
+    });
+    const fixture = createDoctorFixture({
+      env: {},
+      providerDefinitions: [fixtureProviderDefinition({ createProvider })],
+    });
+    fixtures.push(fixture);
+    installBrokenHome(fixture);
+    const module = createDoctorCommandModule(fixture.inputs, fixture.deps);
+    const command = module.systemCommands?.[0];
+    expect(command?.name).toBe('doctor');
+    const result = await command!.execute(contextWith(undefined), '');
+    expect(result.success).toBe(false);
+    expect(result.message).toContain('settings.user.fixture-product');
+    expect(result.message).toContain('plugin.broken-plugin@fixture-market');
+    expect(result.data).toMatchObject({
+      failCount: expect.any(Number),
+      repairable: ['settings.user.fixture-product'],
+    });
+    expect(createProvider).not.toHaveBeenCalled();
+  });
+
+  it('renders host-selected product wording in the interactive command', async () => {
+    const fixture = createDoctorFixture({ env: {} });
+    fixtures.push(fixture);
+    installBrokenHome(fixture);
+    const command = createDoctorCommandModule(fixture.inputs, fixture.deps, {
+      title: 'Atlas doctor',
+      productName: 'Atlas',
+      formatRepairCommand: (id) => `atlas doctor --repair ${id}`,
+      repairOffer: 'run atlas doctor --repair <check-id>',
+    }).systemCommands![0]!;
+
+    const result = await command.execute(contextWith(undefined), '');
+    expect(result.message).toContain('Atlas doctor');
+    expect(result.message).toContain('Atlas');
+    expect(result.message).toContain('atlas doctor --repair settings.user.fixture-product');
+    expect(result.message).toContain('run atlas doctor --repair <check-id>');
+  });
+
+  it('repair without an interaction port or with a cancelled answer writes nothing', async () => {
+    const fixture = createDoctorFixture({ env: {} });
+    fixtures.push(fixture);
+    installBrokenHome(fixture);
+    const path = join(fixture.home, '.fixture-product', 'settings.json');
+    const command = createDoctorCommandModule(fixture.inputs, fixture.deps).systemCommands![0]!;
+
+    const noPort = await command.execute(contextWith(undefined), 'repair settings.user.fixture-product');
+    expect(noPort.success).toBe(false);
+    expect(readFileSync(path, 'utf8')).toBe('');
+
+    const cancelled = answering({ type: 'cancelled' });
+    const declined = await command.execute(contextWith(cancelled), 'repair settings.user.fixture-product');
+    expect(declined.success).toBe(false);
+    expect(cancelled.ask).toHaveBeenCalledTimes(1);
+    expect(readFileSync(path, 'utf8')).toBe('');
+
+    const usage = await command.execute(contextWith(cancelled), 'repair');
+    expect(usage.message).toContain('Usage');
+  });
+
+  it('repair with a confirmed answer applies the allowlisted writer and re-renders', async () => {
+    const fixture = createDoctorFixture({ env: {} });
+    fixtures.push(fixture);
+    installBrokenHome(fixture);
+    const path = join(fixture.home, '.fixture-product', 'settings.json');
+    const command = createDoctorCommandModule(fixture.inputs, fixture.deps).systemCommands![0]!;
+    const yes = answering({ type: 'answer', values: ['yes'] });
+    const result = await command.execute(contextWith(yes), 'repair settings.user.fixture-product');
+    expect(result.success).toBe(true);
+    expect(JSON.parse(readFileSync(path, 'utf8'))).toEqual({});
+    expect(result.data).toMatchObject({
+      repair: 'settings.user.fixture-product',
+      applied: true,
+      status: 'ok',
+    });
+    expect(yes.ask.mock.calls[0]?.[0]).toMatchObject({ id: 'doctor-repair:settings.user.fixture-product' });
+  });
+});

package/src/doctor/__tests__/doctor-display-vocabulary.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, it } from 'vitest';
+
+import { renderDoctorReport } from '../doctor-render.js';
+
+import type { IDoctorReport } from '../doctor-types.js';
+
+const REPORT: IDoctorReport = {
+  checks: [{ id: 'storage.user', label: 'Storage', status: 'warn', repair: 'storage.user' }],
+  failCount: 0,
+  warnCount: 1,
+  repairable: ['storage.user'],
+  exitCode: 0,
+};
+
+describe('doctor display vocabulary', () => {
+  it('uses neutral report and repair text without a host vocabulary', () => {
+    const text = renderDoctorReport(REPORT).join('\n');
+    expect(text).not.toContain('product name');
+    expect(text).not.toContain('--repair');
+    expect(text).toContain('storage.user');
+  });
+
+  it('uses the host-selected title, product name, and repair command', () => {
+    const text = renderDoctorReport(REPORT, 'Atlas doctor', {
+      productName: 'Atlas',
+      formatRepairCommand: (id) => `atlas doctor --repair ${id}`,
+      repairOffer: 'run atlas doctor --repair <check-id>',
+    }).join('\n');
+    expect(text).toContain('Atlas doctor');
+    expect(text).toContain('atlas doctor --repair storage.user');
+    expect(text).toContain('Atlas may work');
+    expect(text).toContain('run atlas doctor --repair <check-id>');
+  });
+
+  it('preserves the public string title argument', () => {
+    expect(renderDoctorReport(REPORT, 'Atlas doctor')).toContain('Atlas doctor');
+  });
+});

package/src/doctor/__tests__/doctor-fixture.ts

@@ -0,0 +1,146 @@
+import { chmodSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import {
+  createNodeHostContributionSource,
+  createNodeHostSettingsSource,
+  createRestrictedWorkspaceProjectAccess,
+} from '@robota-sdk/agent-framework';
+
+import { inspectPathFacts } from '../doctor-node-deps.js';
+
+import type { IDoctorDeps, IDoctorInputs } from '../doctor-types.js';
+import type { IProviderDefinition } from '@robota-sdk/agent-core';
+
+export const MARKERS = {
+  env: 'sk-doctor-marker-env-1a2b3c',
+  profile: 'sk-doctor-marker-profile-4d5e6f',
+  mcp: 'sk-doctor-marker-mcp-9f8e7d',
+  adjacent: 'sk-doctor-marker-adjacent-7c8d9e',
+} as const;
+
+export interface IDoctorFixture {
+  readonly home: string;
+  readonly inputs: IDoctorInputs;
+  readonly deps: IDoctorDeps;
+  readonly probes: { host: string; port: number }[];
+  write(relative: string, content: string): string;
+  mkdir(relative: string, mode?: number): string;
+  cleanup(): void;
+}
+
+/** A provider definition whose SDK-embedded host is declared through `endpoint`, like anthropic. */
+export function fixtureProviderDefinition(
+  overrides: Partial<IProviderDefinition> = {},
+): IProviderDefinition {
+  return {
+    type: 'fixture',
+    displayName: 'Fixture',
+    defaults: { model: 'fixture-model', apiKey: '$ENV:FIXTURE_DOCTOR_API_KEY' },
+    endpoint: { host: 'api.fixture.example', port: 443 },
+    createProvider: () => {
+      throw new Error('the doctor must never construct a provider');
+    },
+    ...overrides,
+  };
+}
+
+interface IDoctorFixtureOptions {
+  env?: Record<string, string | undefined>;
+  providerDefinitions?: readonly IProviderDefinition[];
+  reachable?: boolean;
+  resolvable?: readonly string[];
+  guarantee?: 'posix-mode' | 'windows-acl';
+}
+
+function fixtureDeps(
+  options: IDoctorFixtureOptions,
+  probes: { host: string; port: number }[],
+): IDoctorDeps {
+  const resolvable = new Set(options.resolvable ?? []);
+  return {
+    probeEndpoint: async (host, port) => {
+      probes.push({ host, port });
+      return options.reachable === false
+        ? { reachable: false, error: 'connect ECONNREFUSED' }
+        : { reachable: true, elapsedMs: 1 };
+    },
+    // Real filesystem facts, so the storage probe is exercised against the fixture HOME.
+    inspectPath: inspectPathFacts,
+    resolveCommand: (command) => resolvable.has(command.split(/\s+/)[0] ?? command),
+    ownerOnlyGuarantee: () => options.guarantee ?? 'posix-mode',
+  };
+}
+
+export function createDoctorFixture(options: IDoctorFixtureOptions = {}): IDoctorFixture {
+  const home = mkdtempSync(join(tmpdir(), 'agent-doctor-fixture-'));
+  const write = (relative: string, content: string): string => {
+    const path = join(home, relative);
+    mkdirSync(join(path, '..'), { recursive: true });
+    writeFileSync(path, content, 'utf8');
+    return path;
+  };
+  const mkdir = (relative: string, mode = 0o700): string => {
+    const path = join(home, relative);
+    mkdirSync(path, { recursive: true });
+    chmodSync(path, mode);
+    return path;
+  };
+  const probes: { host: string; port: number }[] = [];
+  const env = options.env ?? {};
+  const inputs: IDoctorInputs = {
+    cwd: home,
+    userHome: home,
+    userSettingsPath: join(home, '.fixture-product', 'settings.json'),
+    userStorage: { root: join(home, '.fixture-product'), sessions: join(home, '.fixture-product', 'sessions') },
+    settingsSources: [
+      createNodeHostSettingsSource('user', join(home, '.fixture-product', 'settings.json')),
+      createNodeHostSettingsSource('user', join(home, '.claude', 'settings.json')),
+    ],
+    projectAccess: createRestrictedWorkspaceProjectAccess('untrusted', home),
+    providerDefinitions: options.providerDefinitions ?? [fixtureProviderDefinition()],
+    env,
+    contributionSources: [createNodeHostContributionSource(home)],
+    skillRoots: [{ root: join('.fixture-product', 'skills'), kind: 'skills' }],
+    pluginsDirs: [join(home, '.fixture-product', 'plugins')],
+    hostChecks: [
+      { id: 'host.fixture', label: 'Fixture host check', status: 'ok', cause: 'present' },
+    ],
+  };
+  const deps = fixtureDeps(options, probes);
+  return {
+    home,
+    inputs,
+    deps,
+    probes,
+    write,
+    mkdir,
+    cleanup: () => rmSync(home, { recursive: true, force: true }),
+  };
+}
+
+/** The "broken HOME" of the built-CLI scenario, as a unit fixture. */
+export function installBrokenHome(fixture: IDoctorFixture): void {
+  fixture.mkdir('.fixture-product');
+  fixture.mkdir('.fixture-product/sessions');
+  fixture.write('.fixture-product/settings.json', '');
+  fixture.write('.claude/settings.json', '{"defaultTrustLevel":42}');
+  fixture.write(
+    '.fixture-product/plugins/cache/fixture-market/broken-plugin/1.0.0/.claude-plugin/plugin.json',
+    '{',
+  );
+  fixture.write(
+    '.fixture-product/plugins/cache/fixture-market/mcp-plugin/1.0.0/.claude-plugin/plugin.json',
+    JSON.stringify({ name: 'mcp-plugin', version: '1.0.0', description: 'doctor fixture' }),
+  );
+  fixture.write(
+    '.fixture-product/plugins/cache/fixture-market/mcp-plugin/1.0.0/.mcp.json',
+    JSON.stringify({
+      mcpServers: {
+        ghost: { command: 'agent-test-doctor-missing-binary', env: { GHOST_TOKEN: MARKERS.mcp } },
+        ready: { type: 'http', url: 'https://mcp.example.test' },
+      },
+    }),
+  );
+}

package/src/doctor/__tests__/doctor-redaction.test.ts

@@ -0,0 +1,29 @@
+import { describe, expect, it } from 'vitest';
+
+import { redactDiagnosticText } from '../doctor-redaction.js';
+
+describe('doctor redaction', () => {
+  it('still masks URL userinfo', () => {
+    expect(redactDiagnosticText('see https://user:hunter22@example.com/x')).toBe(
+      'see https://[redacted]@example.com/x',
+    );
+  });
+
+  it('stays linear on long word runs that never reach a URL scheme', () => {
+    const timeFor = (n: number): number => {
+      const text = `x-${'a-'.repeat(n / 2)}`;
+      let best = Number.POSITIVE_INFINITY;
+      for (let i = 0; i < 3; i += 1) {
+        const started = performance.now();
+        redactDiagnosticText(text);
+        best = Math.min(best, performance.now() - started);
+      }
+      return best;
+    };
+    const small = timeFor(16 * 1024);
+    const large = timeFor(64 * 1024);
+    // Linear growth is about 4x for 4x input; the old unbounded scheme run grew about 16x.
+    if (large >= 50) expect(large / Math.max(small, 1)).toBeLessThan(10);
+    expect(large).toBeLessThan(500);
+  });
+});