refactor: migrate all 7 CLIs onto @deniffer/cli-kit + pin argc

package.json

@@ -12,7 +12,7 @@
       "@types/bun": "^1.3.10",
       "@types/node": "^25.6.0",
       "@valibot/to-json-schema": "^1.6.0",
-      "argc": "github:ethan-huo/argc",
+      "argc": "github:ethan-huo/argc#7d7b60d",
       "bun-types": "^1.3.13",
       "dotenv": "^17.2.2",
       "typescript": "^5",

packages/backlink-cli/lib/errors.ts

@@ -1,9 +1,18 @@
 /**
  * @input machine-classified backlink provider failures
- * @output stable agent-facing error objects
- * @pos shared error contract for backlink handlers and provider calls
+ * @output stable agent-facing error objects (built on @deniffer/cli-kit)
+ * @pos backlink error contract = cli-kit core + a backlink-specific status mapper
  */
 
+import {
+  CliError,
+  type CliErrorMapper,
+  cliError,
+  normalizeCliError as normalizeWithMappers,
+} from "@deniffer/cli-kit/errors";
+
+export { CliError, cliError };
+
 export type CliErrorCode =
   | "invalid_input"
   | "auth_error"
@@ -13,36 +22,13 @@ export type CliErrorCode =
   | "parse_error"
   | "backend_failure";
 
-export class CliError extends Error {
-  code: CliErrorCode;
-  hint?: string;
-
-  constructor(input: { code: CliErrorCode; message: string; hint?: string }) {
-    super(input.message);
-    this.name = "CliError";
-    this.code = input.code;
-    this.hint = input.hint;
-  }
-}
-
-export function cliError(input: {
-  code: CliErrorCode;
-  message: string;
-  hint?: string;
-}) {
-  return new CliError(input);
-}
-
 function readStatus(error: Error) {
   const status = Reflect.get(error, "status");
   return typeof status === "number" ? status : null;
 }
 
-export function normalizeCliError(error: unknown) {
-  if (error instanceof CliError) {
-    return error;
-  }
-
+// The backlink-specific divergence, plugged into cli-kit's normalizer seam.
+export const backlinkErrorMapper: CliErrorMapper = (error) => {
   if (error instanceof TypeError) {
     return cliError({
       code: "network_error",
@@ -51,44 +37,40 @@ export function normalizeCliError(error: unknown) {
     });
   }
 
-  if (error instanceof Error) {
-    const status = readStatus(error);
-
-    if (status === 401 || status === 403) {
-      return cliError({
-        code: "auth_error",
-        message: error.message,
-        hint: "Check backlink provider credentials.",
-      });
-    }
-
-    if (status === 402 || status === 429) {
-      return cliError({
-        code: "quota_error",
-        message: error.message,
-        hint: "Check backlink provider credits, subscription, rate limits, and retry policy.",
-      });
-    }
-
-    if (status !== null) {
-      return cliError({
-        code: "provider_error",
-        message: error.message,
-        hint:
-          status >= 500
-            ? "The backlink provider returned a server error. Retry later."
-            : "The backlink provider rejected the request. Check input fields.",
-      });
-    }
+  if (!(error instanceof Error)) {
+    return null;
+  }
 
+  const status = readStatus(error);
+  if (status === 401 || status === 403) {
+    return cliError({
+      code: "auth_error",
+      message: error.message,
+      hint: "Check backlink provider credentials.",
+    });
+  }
+  if (status === 402 || status === 429) {
     return cliError({
-      code: "backend_failure",
+      code: "quota_error",
       message: error.message,
+      hint: "Check backlink provider credits, subscription, rate limits, and retry policy.",
     });
   }
+  if (status !== null) {
+    return cliError({
+      code: "provider_error",
+      message: error.message,
+      hint:
+        status >= 500
+          ? "The backlink provider returned a server error. Retry later."
+          : "The backlink provider rejected the request. Check input fields.",
+    });
+  }
+
+  // Defer Error-without-status and non-Error to cli-kit's backend_failure fallback.
+  return null;
+};
 
-  return cliError({
-    code: "backend_failure",
-    message: "Unknown CLI error",
-  });
+export function normalizeCliError(error: unknown) {
+  return normalizeWithMappers(error, [backlinkErrorMapper]);
 }

packages/backlink-cli/output.ts

@@ -1,84 +1,24 @@
 /**
  * @input CLI output mode plus success or error payloads
- * @output agent-first JSON output with optional pretty rendering
+ * @output agent-first JSON output (built on @deniffer/cli-kit)
  * @pos serialization boundary between backlink handlers and terminal
  */
 
-import { inspect } from "node:util";
-import type { CliContext } from "./context";
-import { normalizeCliError } from "./lib/errors";
-
-export type Output<T> =
-  | { ok: true; data: T }
-  | { ok: false; error: { code: string; message: string; hint?: string } };
-
-export type HumanLines<T> = string[] | ((data: T) => string[]);
-
-export type OutputService = {
-  success: <T>(data: T, human?: HumanLines<T>) => void;
-  error: (error: unknown, human?: string[]) => void;
-};
-
-function printJson<T>(value: Output<T>) {
-  process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
-}
-
-function formatUnknown(value: unknown) {
-  return inspect(value, {
-    depth: null,
-    colors: false,
-    compact: false,
-    sorted: true,
-  });
-}
+import {
+  createOutputService as createBaseOutputService,
+  type HumanLines,
+  type Output,
+  type OutputService,
+} from "@deniffer/cli-kit/output";
 
-function resolveHumanLines<T>(data: T, human?: HumanLines<T>) {
-  if (!human) {
-    return [formatUnknown(data)];
-  }
+import type { CliContext } from "./context";
+import { backlinkErrorMapper } from "./lib/errors";
 
-  return typeof human === "function" ? human(data) : human;
-}
+export type { HumanLines, Output, OutputService };
 
 export function createOutputService(context: CliContext): OutputService {
-  const pretty = context.pretty ?? false;
-
-  return {
-    success<T>(data: T, human?: HumanLines<T>) {
-      if (!pretty) {
-        printJson({ ok: true, data });
-        return;
-      }
-
-      process.stdout.write(`${resolveHumanLines(data, human).join("\n")}\n`);
-    },
-    error(error: unknown, human?: string[]) {
-      const resolved = normalizeCliError(error);
-
-      if (!pretty) {
-        process.stderr.write(
-          `${JSON.stringify(
-            {
-              ok: false,
-              error: {
-                code: resolved.code,
-                message: resolved.message,
-                ...(resolved.hint ? { hint: resolved.hint } : {}),
-              },
-            } satisfies Output<never>,
-            null,
-            2
-          )}\n`
-        );
-        return;
-      }
-
-      const lines = human ?? [
-        `Error Code: ${resolved.code}`,
-        `Error: ${resolved.message}`,
-        ...(resolved.hint ? [`Hint: ${resolved.hint}`] : []),
-      ];
-      process.stderr.write(`${lines.join("\n")}\n`);
-    },
-  };
+  return createBaseOutputService({
+    pretty: context.pretty,
+    errorMappers: [backlinkErrorMapper],
+  });
 }

packages/backlink-cli/package.json

@@ -37,9 +37,10 @@
     "test:once": "vitest run"
   },
   "dependencies": {
+    "@deniffer/cli-kit": "github:Deniffer001/cli-kit#v0.1.2",
     "@standard-schema/spec": "^1.0.0",
     "@valibot/to-json-schema": "^1.6.0",
-    "argc": "github:ethan-huo/argc",
+    "argc": "github:ethan-huo/argc#7d7b60d",
     "dotenv": "^17.2.2",
     "valibot": "^1.2.0"
   },