Tests. Autocomplete. Few Fixes. Mocks for Electrum Service. Template-to-Json parser. Fix global paths. Use IO Dependency injection for logging from cli. Additional commands in CLI.

tests/cli/commands/handler-contracts.test.ts

@@ -0,0 +1,86 @@
+import { describe, expect, test } from "vitest";
+
+import { handleMnemonicCommand } from "../../../src/cli/commands/mnemonic";
+import { handleTemplateCommand } from "../../../src/cli/commands/template";
+import { handleReceiveCommand } from "../../../src/cli/commands/receive";
+import { handleResourceCommand } from "../../../src/cli/commands/resource";
+import { CommandError } from "../../../src/cli/commands/types";
+import {
+  createBaseCommandDeps,
+  createCommandDeps,
+  createMockIO,
+} from "../mocks/command";
+
+const fakeApp = {
+  engine: {},
+  invitations: [],
+  unreserveAllResources: async () => 0,
+} as any;
+
+describe("command handler contracts", () => {
+  test("mnemonic throws and prints help for missing subcommand", async () => {
+    const { io, capture } = createMockIO();
+
+    await expect(
+      handleMnemonicCommand(createBaseCommandDeps(io), [], {}),
+    ).rejects.toThrow(CommandError);
+
+    try {
+      await handleMnemonicCommand(createBaseCommandDeps(io), [], {});
+    } catch (error) {
+      expect(error).toBeInstanceOf(CommandError);
+      expect((error as CommandError).event).toBe("mnemonic.subcommand.missing");
+    }
+
+    expect(capture.out.join("\n")).toContain("Usage:");
+  });
+
+  test("template throws for missing subcommand", async () => {
+    const { io, capture } = createMockIO();
+
+    await expect(
+      handleTemplateCommand(createCommandDeps(fakeApp, io), [], {}),
+    ).rejects.toThrow(CommandError);
+
+    try {
+      await handleTemplateCommand(createCommandDeps(fakeApp, io), [], {});
+    } catch (error) {
+      expect(error).toBeInstanceOf(CommandError);
+      expect((error as CommandError).event).toBe("template.subcommand.missing");
+    }
+
+    expect(capture.out.join("\n")).toContain("Usage:");
+  });
+
+  test("receive throws for missing args", async () => {
+    const { io, capture } = createMockIO();
+
+    await expect(
+      handleReceiveCommand(createCommandDeps(fakeApp, io), [], {}),
+    ).rejects.toThrow(CommandError);
+
+    try {
+      await handleReceiveCommand(createCommandDeps(fakeApp, io), [], {});
+    } catch (error) {
+      expect(error).toBeInstanceOf(CommandError);
+      expect((error as CommandError).event).toBe("receive.arguments.missing");
+    }
+
+    expect(capture.out.join("\n")).toContain("Usage:");
+  });
+
+  test("resource throws for unknown subcommand", async () => {
+    const { io } = createMockIO();
+
+    await expect(
+      handleResourceCommand(createCommandDeps(fakeApp, io), ["does-not-exist"], {}),
+    ).rejects.toThrow(CommandError);
+
+    try {
+      await handleResourceCommand(createCommandDeps(fakeApp, io), ["does-not-exist"], {});
+    } catch (error) {
+      expect(error).toBeInstanceOf(CommandError);
+      expect((error as CommandError).event).toBe("resource.subcommand.unknown");
+    }
+  });
+});

tests/cli/commands/mnemonic.test.ts

@@ -0,0 +1,146 @@
+import { expect, test, describe, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+
+import { DEFAULT_SEED } from "../mocks/engine";
+
+import { handleMnemonicCommand } from "../../../src/cli/commands/mnemonic";
+import { CommandError } from "../../../src/cli/commands/types";
+import { createMockIO, createMockPaths, expectLogs, type LogExpectation } from "../mocks/command";
+import { BCHMnemonicURL } from "../../../src/utils/bch-mnemonic-url";
+
+type TestCase = {
+  inputs: string[];
+  options?: Record<string, string>;
+  shouldThrow: boolean;
+  expectedEvent?: string;
+  expectedData?: Record<string, unknown>;
+  logs?: LogExpectation[];
+};
+
+const testCases: TestCase[] = [
+  // Successful creation of a mnemonic file
+  {
+    inputs: ["create"],
+    shouldThrow: false,
+    expectedData: {
+      savedAs: expect.stringMatching(/^mnemonic-\w+$/),
+    },
+    logs: [{ out: "Mnemonic file created" }],
+  },
+  // Successfully creating a mnemonic file with a custom filename
+  {
+    inputs: ["create"],
+    options: { output: "custom-filename" },
+    shouldThrow: false,
+    expectedData: {
+      savedAs: "custom-filename",
+    },
+    logs: [{ out: "custom-filename" }],
+  },
+  // Successfully listing mnemonic files
+  {
+    inputs: ["list"],
+    shouldThrow: false,
+    expectedData: {
+      count: expect.toSatisfy((count: number) => count >= 1),
+    },
+    logs: [{ out: "mnemonic-test" }],
+  },
+  // Successfully exposing a mnemonic file
+  {
+    inputs: ["expose", "mnemonic-test"],
+    shouldThrow: false,
+    expectedData: {
+      mnemonic: DEFAULT_SEED,
+    },
+    logs: [{ out: DEFAULT_SEED }],
+  },
+  // Successfully importing a mnemonic file
+  {
+    inputs: ["import", ...DEFAULT_SEED.split(" ")],
+    shouldThrow: false,
+    expectedData: {
+      savedAs: expect.stringMatching(/^mnemonic-\w+$/),
+    },
+    logs: [{ out: "Mnemonic file created" }],
+  },
+  // Failure to import a mnemonic file due to missing arguments
+  {
+    inputs: ["import"],
+    shouldThrow: true,
+    expectedEvent: "mnemonic.import.seed_missing",
+  },
+  // Failure to expose a mnemonic file due to missing arguments
+  {
+    inputs: ["expose"],
+    shouldThrow: true,
+    expectedEvent: "mnemonic.expose.file_missing",
+  },
+  // Failure to expose a mnemonic file due to unknown mnemonic file
+  {
+    inputs: ["expose", "unknown-mnemonic-file"],
+    shouldThrow: true,
+    expectedEvent: "mnemonic.expose.file_not_found",
+  },
+  // Missing sub-command
+  {
+    inputs: [],
+    shouldThrow: true,
+    expectedEvent: "mnemonic.subcommand.missing",
+  },
+  // Unknown sub-command
+  {
+    inputs: ["unknown"],
+    shouldThrow: true,
+    expectedEvent: "mnemonic.subcommand.unknown",
+  },
+];
+
+describe("mnemonic commands", () => {
+  let tempDir: string;
+
+  beforeEach(async () => {
+    tempDir = mkdtempSync(path.join(tmpdir(), "xo-cli-mnemonic-tests-"));
+    
+    // Write a single test mnemonic file to the temp directory
+    writeFileSync(
+      path.join(tempDir, "mnemonic-test"),
+      BCHMnemonicURL.fromSeed(DEFAULT_SEED).toURL(),
+      "utf8",
+    );
+  });
+
+  afterEach(async () => {
+    rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  test.each(testCases)("mnemonic command: $inputs", async ({ inputs, options, shouldThrow, expectedEvent, expectedData, logs }) => {
+    const { io, spies } = createMockIO();
+    const paths = createMockPaths(tempDir);
+
+    if (shouldThrow) {
+      try {
+        await handleMnemonicCommand({ io, paths }, inputs, options ?? {});
+        expect.fail("Expected command to throw");
+      } catch (error) {
+        if (expectedEvent) {
+          expect(error).toBeInstanceOf(CommandError);
+          expect((error as CommandError).event).toBe(expectedEvent);
+        }
+      }
+    } else {
+      const result = await handleMnemonicCommand({ io, paths }, inputs, options ?? {});
+      if (expectedData) {
+        Object.entries(expectedData).forEach(([key, value]) => {
+          expect(result[key as keyof typeof result]).toEqual(value);
+        });
+      }
+    }
+
+    if (logs) {
+      expectLogs(spies, logs);
+    }
+  });
+});

tests/cli/commands/receive.test.ts

@@ -0,0 +1,114 @@
+import { expect, test, describe, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+
+import { createMockAppService, createMockEngine, DEFAULT_SEED } from "../mocks/engine";
+import { type Engine } from "@xo-cash/engine";
+import { p2pkhTemplate } from "../mocks/template-p2pkh";
+import { AppService } from "../../../src/services/app";
+
+import { handleReceiveCommand } from "../../../src/cli/commands/receive";
+import { CommandError } from "../../../src/cli/commands/types";
+import { createCommandDeps, createMockIO, expectLogs, type LogExpectation } from "../mocks/command";
+
+type TestCase = {
+  name: string;
+  inputs: string[];
+  options?: Record<string, string>;
+  shouldThrow: boolean;
+  expectedEvent?: string;
+  expectedData?: Record<string, unknown>;
+  logs?: LogExpectation[];
+};
+
+const testCases: TestCase[] = [
+  // Successful address generation with template name and output identifier
+  {
+    name: "generates address with template name and output",
+    inputs: ["Wallet (P2PKH)", "receiveOutput"],
+    shouldThrow: false,
+    expectedData: {
+      address: expect.stringMatching(/^bitcoincash:q[a-z0-9]+$/),
+    },
+    logs: [{ out: "bitcoincash:q" }],
+  },
+  // Successful address generation with role specified
+  {
+    name: "generates address with template name, output, and role",
+    inputs: ["Wallet (P2PKH)", "receiveOutput", "receiver"],
+    shouldThrow: false,
+    expectedData: {
+      address: expect.stringMatching(/^bitcoincash:q[a-z0-9]+$/),
+    },
+    logs: [{ out: "bitcoincash:q" }],
+  },
+  // Missing all required arguments
+  {
+    name: "throws when no arguments provided",
+    inputs: [],
+    shouldThrow: true,
+    expectedEvent: "receive.arguments.missing",
+  },
+  // Missing output identifier
+  {
+    name: "throws when output identifier missing",
+    inputs: ["Wallet (P2PKH)"],
+    shouldThrow: true,
+    expectedEvent: "receive.arguments.missing",
+  },
+  // Unknown template
+  {
+    name: "throws when template not found",
+    inputs: ["unknown-template", "receiveOutput"],
+    shouldThrow: true,
+    expectedEvent: "template.resolve.not_found",
+  },
+];
+
+describe("receive command", () => {
+  let engine: Engine;
+  let app: AppService;
+  let tempDir: string;
+
+  beforeEach(async () => {
+    engine = await createMockEngine(DEFAULT_SEED);
+    await engine.importTemplate(p2pkhTemplate);
+
+    app = await createMockAppService(engine);
+
+    tempDir = mkdtempSync(path.join(tmpdir(), "xo-cli-receive-tests-"));
+  });
+
+  afterEach(async () => {
+    await engine.stop();
+    rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  test.each(testCases)("$name", async ({ inputs, options, shouldThrow, expectedEvent, expectedData, logs }) => {
+    const { io, spies } = createMockIO();
+
+    if (shouldThrow) {
+      try {
+        await handleReceiveCommand(createCommandDeps(app, io), inputs, options ?? {});
+        expect.fail("Expected command to throw");
+      } catch (error) {
+        if (expectedEvent) {
+          expect(error).toBeInstanceOf(CommandError);
+          expect((error as CommandError).event).toBe(expectedEvent);
+        }
+      }
+    } else {
+      const result = await handleReceiveCommand(createCommandDeps(app, io), inputs, options ?? {});
+      if (expectedData) {
+        Object.entries(expectedData).forEach(([key, value]) => {
+          expect(result[key as keyof typeof result]).toEqual(value);
+        });
+      }
+    }
+
+    if (logs) {
+      expectLogs(spies, logs);
+    }
+  });
+});

tests/cli/commands/resource.test.ts

@@ -0,0 +1,279 @@
+import { expect, test, describe, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+
+import { addFakeResource, createMockAppService, createMockEngine, DEFAULT_SEED, reserveResource } from "../mocks/engine";
+import { type Engine } from "@xo-cash/engine";
+import { p2pkhTemplate } from "../mocks/template-p2pkh";
+import { AppService } from "../../../src/services/app";
+
+import { handleResourceCommand } from "../../../src/cli/commands/resource";
+import { CommandError } from "../../../src/cli/commands/types";
+import { createCommandDeps, createMockIO, expectLogs, type LogExpectation } from "../mocks/command";
+
+type TestCase = {
+  name: string;
+  inputs: string[];
+  options?: Record<string, string>;
+  shouldThrow: boolean;
+  expectedEvent?: string;
+  expectedData?: Record<string, unknown>;
+  logs?: LogExpectation[];
+};
+
+const testCases: TestCase[] = [
+  // List commands (no resources in empty wallet)
+  {
+    name: "list returns empty count when no resources",
+    inputs: ["list"],
+    shouldThrow: false,
+    expectedData: {
+      count: 0,
+    },
+    logs: [{ out: "No resources found" }],
+  },
+  {
+    name: "list reserved returns empty count when no reserved resources",
+    inputs: ["list", "reserved"],
+    shouldThrow: false,
+    expectedData: {
+      count: 0,
+    },
+    logs: [{ out: "No resources found" }],
+  },
+  {
+    name: "list all returns empty count when no resources",
+    inputs: ["list", "all"],
+    shouldThrow: false,
+    expectedData: {
+      count: 0,
+    },
+    logs: [{ out: "No resources found" }],
+  },
+  // Unreserve-all with no resources
+  {
+    name: "unreserve-all returns zero count when no reserved resources",
+    inputs: ["unreserve-all"],
+    shouldThrow: false,
+    expectedData: {
+      count: 0,
+    },
+    logs: [{ out: "No reserved resources" }],
+  },
+  // Error cases
+  {
+    name: "throws when no subcommand provided",
+    inputs: [],
+    shouldThrow: true,
+    expectedEvent: "resource.subcommand.missing",
+  },
+  {
+    name: "throws when unknown subcommand provided",
+    inputs: ["unknown-subcommand"],
+    shouldThrow: true,
+    expectedEvent: "resource.subcommand.unknown",
+  },
+  {
+    name: "throws when unreserve called without outpoint",
+    inputs: ["unreserve"],
+    shouldThrow: true,
+    expectedEvent: "resource.unreserve.outpoint_missing",
+  },
+  {
+    name: "throws when unreserve called with invalid outpoint format (no colon)",
+    inputs: ["unreserve", "invalid-outpoint"],
+    shouldThrow: true,
+    expectedEvent: "resource.unreserve.outpoint_invalid",
+  },
+  {
+    name: "throws when unreserve called with invalid outpoint format (no vout)",
+    inputs: ["unreserve", "abc123:"],
+    shouldThrow: true,
+    expectedEvent: "resource.unreserve.outpoint_invalid",
+  },
+  {
+    name: "throws when unreserve called with non-existent UTXO",
+    inputs: ["unreserve", "0000000000000000000000000000000000000000000000000000000000000000:0"],
+    shouldThrow: true,
+    expectedEvent: "resource.unreserve.utxo_missing",
+  },
+];
+
+describe("resource command", () => {
+  let engine: Engine;
+  let app: AppService;
+  let tempDir: string;
+
+  beforeEach(async () => {
+    engine = await createMockEngine(DEFAULT_SEED);
+    await engine.importTemplate(p2pkhTemplate);
+
+    app = await createMockAppService(engine);
+
+    tempDir = mkdtempSync(path.join(tmpdir(), "xo-cli-resource-tests-"));
+  });
+
+  afterEach(async () => {
+    await engine.stop();
+    rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  test.each(testCases)("$name", async ({ inputs, options, shouldThrow, expectedEvent, expectedData, logs }) => {
+    const { io, spies } = createMockIO();
+
+    if (shouldThrow) {
+      try {
+        await handleResourceCommand(createCommandDeps(app, io), inputs, options ?? {});
+        expect.fail("Expected command to throw");
+      } catch (error) {
+        if (expectedEvent) {
+          expect(error).toBeInstanceOf(CommandError);
+          expect((error as CommandError).event).toBe(expectedEvent);
+        }
+      }
+    } else {
+      const result = await handleResourceCommand(createCommandDeps(app, io), inputs, options ?? {});
+      if (expectedData) {
+        Object.entries(expectedData).forEach(([key, value]) => {
+          expect(result[key as keyof typeof result]).toEqual(value);
+        });
+      }
+    }
+
+    if (logs) {
+      expectLogs(spies, logs);
+    }
+  });
+});
+
+describe("resource command with populated data", () => {
+  let engine: Engine;
+  let app: AppService;
+  let tempDir: string;
+
+  beforeEach(async () => {
+    engine = await createMockEngine(DEFAULT_SEED);
+    await engine.importTemplate(p2pkhTemplate);
+    app = await createMockAppService(engine);
+    tempDir = mkdtempSync(path.join(tmpdir(), "xo-cli-resource-tests-"));
+  });
+
+  afterEach(async () => {
+    await engine.stop();
+    rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  test("list returns count when resources exist", async () => {
+    await addFakeResource(engine, { valueSatoshis: 50000 });
+    await addFakeResource(engine, { valueSatoshis: 25000 });
+
+    const { io, spies } = createMockIO();
+    const result = await handleResourceCommand(createCommandDeps(app, io), ["list"], {});
+
+    expect(result.count).toBe(2);
+    expectLogs(spies, [{ out: "Total resources: 2" }]);
+  });
+
+  test("list shows total satoshis", async () => {
+    await addFakeResource(engine, { valueSatoshis: 50000 });
+    await addFakeResource(engine, { valueSatoshis: 25000 });
+
+    const { io, spies } = createMockIO();
+    await handleResourceCommand(createCommandDeps(app, io), ["list"], {});
+
+    expectLogs(spies, [{ out: "Total satoshis: 75000" }]);
+  });
+
+  test("list excludes reserved resources by default", async () => {
+    await addFakeResource(engine, { valueSatoshis: 50000 });
+    await addFakeResource(engine, { valueSatoshis: 25000, reservedBy: "inv-123" });
+
+    const { io } = createMockIO();
+    const result = await handleResourceCommand(createCommandDeps(app, io), ["list"], {});
+
+    expect(result.count).toBe(1);
+  });
+
+  test("list reserved shows only reserved resources", async () => {
+    await addFakeResource(engine, { valueSatoshis: 50000 });
+    await addFakeResource(engine, { valueSatoshis: 25000, reservedBy: "inv-123" });
+    await addFakeResource(engine, { valueSatoshis: 10000, reservedBy: "inv-456" });
+
+    const { io, spies } = createMockIO();
+    const result = await handleResourceCommand(createCommandDeps(app, io), ["list", "reserved"], {});
+
+    expect(result.count).toBe(2);
+    expectLogs(spies, [{ out: "reserved for inv-123" }]);
+  });
+
+  test("list all shows both reserved and unreserved", async () => {
+    await addFakeResource(engine, { valueSatoshis: 50000 });
+    await addFakeResource(engine, { valueSatoshis: 25000, reservedBy: "inv-123" });
+
+    const { io } = createMockIO();
+    const result = await handleResourceCommand(createCommandDeps(app, io), ["list", "all"], {});
+
+    expect(result.count).toBe(2);
+  });
+
+  test("unreserve releases a reserved UTXO", async () => {
+    const resource = await addFakeResource(engine, { valueSatoshis: 25000, reservedBy: "inv-123" });
+
+    const { io, spies } = createMockIO();
+    await handleResourceCommand(
+      createCommandDeps(app, io),
+      ["unreserve", `${resource.outpointTransactionHash}:${resource.outpointIndex}`],
+      {},
+    );
+
+    expectLogs(spies, [{ out: "Unreserved" }, { out: "was reserved for inv-123" }]);
+
+    const resources = await engine.listUnspentOutputsData();
+    const target = resources.find(
+      r => r.outpointTransactionHash === resource.outpointTransactionHash,
+    );
+    expect(target?.reservedBy).toBeUndefined();
+  });
+
+  test("unreserve reports when UTXO is not reserved", async () => {
+    const resource = await addFakeResource(engine, { valueSatoshis: 25000 });
+
+    const { io, spies } = createMockIO();
+    await handleResourceCommand(
+      createCommandDeps(app, io),
+      ["unreserve", `${resource.outpointTransactionHash}:${resource.outpointIndex}`],
+      {},
+    );
+
+    expectLogs(spies, [{ out: "UTXO is not reserved" }]);
+  });
+
+  test("unreserve-all releases all reserved UTXOs", async () => {
+    await addFakeResource(engine, { valueSatoshis: 50000 });
+    await addFakeResource(engine, { valueSatoshis: 25000, reservedBy: "inv-123" });
+    await addFakeResource(engine, { valueSatoshis: 10000, reservedBy: "inv-456" });
+
+    const { io, spies } = createMockIO();
+    const result = await handleResourceCommand(createCommandDeps(app, io), ["unreserve-all"], {});
+
+    expect(result.count).toBe(2);
+    expectLogs(spies, [{ out: "Unreserved" }, { out: "2" }]);
+
+    const resources = await engine.listUnspentOutputsData();
+    const reserved = resources.filter(r => r.reservedBy);
+    expect(reserved).toHaveLength(0);
+  });
+
+  test("list displays outpoint information", async () => {
+    const resource = await addFakeResource(engine, { valueSatoshis: 12345 });
+
+    const { io, spies } = createMockIO();
+    await handleResourceCommand(createCommandDeps(app, io), ["list"], {});
+
+    expectLogs(spies, [
+      { out: resource.outpointTransactionHash },
+      { out: "12345 sats" },
+    ]);
+  });
+});

tests/cli/commands/template.test.ts

@@ -0,0 +1,235 @@
+import { expect, test, describe, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+
+import { createMockAppService, createMockEngine, DEFAULT_SEED } from "../mocks/engine";
+import { type Engine } from "@xo-cash/engine";
+import { p2pkhTemplate, p2pkhTemplateIdentifier } from "../mocks/template-p2pkh";
+import { AppService } from "../../../src/services/app";
+
+import { handleTemplateCommand } from "../../../src/cli/commands/template";
+import { CommandError } from "../../../src/cli/commands/types";
+import { createCommandDeps, createMockIO, expectLogs, type LogExpectation } from "../mocks/command";
+
+type TestCase = {
+  name: string;
+  inputs: string[];
+  options?: Record<string, string>;
+  shouldThrow: boolean;
+  expectedEvent?: string;
+  expectedData?: Record<string, unknown>;
+  logs?: LogExpectation[];
+};
+
+const testCases: TestCase[] = [
+  // List command
+  {
+    name: "list returns count of imported templates",
+    inputs: ["list"],
+    shouldThrow: false,
+    expectedData: {
+      count: 1,
+    },
+    logs: [{ out: "Wallet (P2PKH)" }],
+  },
+  // List by category
+  {
+    name: "list action returns actions for template",
+    inputs: ["list", "action", p2pkhTemplateIdentifier],
+    shouldThrow: false,
+    expectedData: {},
+    logs: [{ out: "receive" }],
+  },
+  {
+    name: "list output returns outputs for template",
+    inputs: ["list", "output", p2pkhTemplateIdentifier],
+    shouldThrow: false,
+    expectedData: {},
+    logs: [{ out: "receiveOutput" }],
+  },
+  {
+    name: "list variable returns variables for template",
+    inputs: ["list", "variable", p2pkhTemplateIdentifier],
+    shouldThrow: false,
+    expectedData: {},
+    logs: [{ out: "ownerKey" }],
+  },
+  {
+    name: "list transaction returns transactions for template",
+    inputs: ["list", "transaction", p2pkhTemplateIdentifier],
+    shouldThrow: false,
+    expectedData: {},
+  },
+  {
+    name: "list lockingscript returns locking scripts for template",
+    inputs: ["list", "lockingscript", p2pkhTemplateIdentifier],
+    shouldThrow: false,
+    expectedData: {},
+  },
+  // Inspect command
+  {
+    name: "inspect action returns action details",
+    inputs: ["inspect", "action", p2pkhTemplateIdentifier, "receive"],
+    shouldThrow: false,
+    expectedData: {},
+  },
+  {
+    name: "inspect output returns output details",
+    inputs: ["inspect", "output", p2pkhTemplateIdentifier, "receiveOutput"],
+    shouldThrow: false,
+    expectedData: {},
+  },
+  {
+    name: "inspect variable returns variable details",
+    inputs: ["inspect", "variable", p2pkhTemplateIdentifier, "ownerKey"],
+    shouldThrow: false,
+    expectedData: {},
+  },
+  // Error cases - subcommand
+  {
+    name: "throws when no subcommand provided",
+    inputs: [],
+    shouldThrow: true,
+    expectedEvent: "template.subcommand.missing",
+  },
+  {
+    name: "throws when unknown subcommand provided",
+    inputs: ["unknown-subcommand"],
+    shouldThrow: true,
+    expectedEvent: "template.subcommand.unknown",
+  },
+  // Error cases - import
+  {
+    name: "throws when import called without file",
+    inputs: ["import"],
+    shouldThrow: true,
+    expectedEvent: "template.import.file_missing",
+  },
+  {
+    name: "throws when import called with non-existent file",
+    inputs: ["import", "non-existent-file.json"],
+    shouldThrow: true,
+    expectedEvent: "template.import.file_not_found",
+  },
+  // Error cases - list category
+  {
+    name: "throws when list category called without template identifier",
+    inputs: ["list", "action"],
+    shouldThrow: true,
+    expectedEvent: "template.list.identifier_missing",
+  },
+  {
+    name: "throws when list category called with unknown template",
+    inputs: ["list", "action", "unknown-template"],
+    shouldThrow: true,
+    expectedEvent: "template.list.not_found",
+  },
+  {
+    name: "throws when list called with unknown category",
+    inputs: ["list", "unknown-category", p2pkhTemplateIdentifier],
+    shouldThrow: true,
+    expectedEvent: "template.list.category_unknown",
+  },
+  // Error cases - inspect
+  {
+    name: "throws when inspect called without all arguments",
+    inputs: ["inspect", "action"],
+    shouldThrow: true,
+    expectedEvent: "template.inspect.arguments_missing",
+  },
+  {
+    name: "throws when inspect called with unknown template",
+    inputs: ["inspect", "action", "unknown-template", "receive"],
+    shouldThrow: true,
+    expectedEvent: "template.resolve.not_found",
+  },
+  {
+    name: "throws when inspect called with unknown action",
+    inputs: ["inspect", "action", p2pkhTemplateIdentifier, "unknown-action"],
+    shouldThrow: true,
+    expectedEvent: "template.inspect.action_missing",
+  },
+  {
+    name: "throws when inspect called with unknown category",
+    inputs: ["inspect", "unknown-category", p2pkhTemplateIdentifier, "field"],
+    shouldThrow: true,
+    expectedEvent: "template.inspect.category_unknown",
+  },
+  // Error cases - set-default
+  {
+    name: "throws when set-default called without all arguments",
+    inputs: ["set-default", "template"],
+    shouldThrow: true,
+    expectedEvent: "template.default.arguments_missing",
+  },
+];
+
+describe("template command", () => {
+  let engine: Engine;
+  let app: AppService;
+  let tempDir: string;
+
+  beforeEach(async () => {
+    engine = await createMockEngine(DEFAULT_SEED);
+    await engine.importTemplate(p2pkhTemplate);
+
+    app = await createMockAppService(engine);
+
+    tempDir = mkdtempSync(path.join(tmpdir(), "xo-cli-template-tests-"));
+  });
+
+  afterEach(async () => {
+    await engine.stop();
+    rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  test.each(testCases)("$name", async ({ inputs, options, shouldThrow, expectedEvent, expectedData, logs }) => {
+    const { io, spies } = createMockIO();
+
+    if (shouldThrow) {
+      try {
+        await handleTemplateCommand(createCommandDeps(app, io), inputs, options ?? {});
+        expect.fail("Expected command to throw");
+      } catch (error) {
+        if (expectedEvent) {
+          expect(error).toBeInstanceOf(CommandError);
+          expect((error as CommandError).event).toBe(expectedEvent);
+        }
+      }
+    } else {
+      const result = await handleTemplateCommand(createCommandDeps(app, io), inputs, options ?? {});
+      if (expectedData) {
+        Object.entries(expectedData).forEach(([key, value]) => {
+          expect(result[key as keyof typeof result]).toEqual(value);
+        });
+      }
+    }
+
+    if (logs) {
+      expectLogs(spies, logs);
+    }
+  });
+
+  test("import imports template from file", async () => {
+    const templatePath = path.join(tempDir, "test-template.json");
+    writeFileSync(templatePath, JSON.stringify(p2pkhTemplate));
+
+    const { io } = createMockIO();
+    
+    const originalCwd = process.cwd();
+    process.chdir(tempDir);
+    
+    try {
+      const result = await handleTemplateCommand(
+        createCommandDeps(app, io),
+        ["import", "test-template.json"],
+        {},
+      );
+
+      expect(result.templateFile).toBe("test-template.json");
+    } finally {
+      process.chdir(originalCwd);
+    }
+  });
+});