@fedify/cli 2.0.0-pr.458.1796 → 2.0.0-pr.467.1877

package/deno.json

@@ -1,6 +1,6 @@
 {
   "name": "@fedify/cli",
-  "version": "2.0.0-pr.458.1796+f091195d",
+  "version": "2.0.0-pr.467.1877+dc12636d",
   "license": "MIT",
   "exports": "./src/mod.ts",
   "imports": {

package/dist/deno.js

@@ -3,7 +3,7 @@
     
 //#region deno.json
 var name = "@fedify/cli";
-var version = "2.0.0-pr.458.1796+f091195d";
+var version = "2.0.0-pr.467.1877+dc12636d";
 var license = "MIT";
 var exports = "./src/mod.ts";
 var imports = {

package/dist/generate-vocab/command.js

@@ -1,21 +1,21 @@
 
       import { Temporal } from "@js-temporal/polyfill";
     
-import { command, constant, message, object, option } from "@optique/core";
+import { argument, command, constant, message, object, option, withDefault } from "@optique/core";
 import { path } from "@optique/run";
 
 //#region src/generate-vocab/command.ts
-const schemaDir = option("-i", "--input", path({
+const schemaDir = withDefault(option("-i", "--input", path({
 	metavar: "DIR",
 	type: "directory",
 	mustExist: true
-}));
-const generatedPath = option("-o", "--output", path({
+}), { description: message`Directory containing schema files.` }), ".");
+const generatedPath = argument(path({
 	metavar: "PATH",
 	type: "file",
 	allowCreate: true
-}));
-const generateVocabCommand = command("generate-vocab", object({
+}), { description: message`Path to output the generated vocabulary classes.  Should end with ${".ts"} suffix.` });
+const generateVocabCommand = command("generate-vocab", object("Generation options", {
 	command: constant("generate-vocab"),
 	schemaDir,
 	generatedPath

package/dist/inbox.js

@@ -27,11 +27,14 @@ const logger = getLogger([
 const inboxCommand = command("inbox", merge(object("Inbox options", {
 	command: constant("inbox"),
 	follow: optional(multiple(option("-f", "--follow", string({ metavar: "URI" }), { description: message`Follow the given actor. The argument can be either an actor URI or a handle. Can be specified multiple times.` }))),
-	acceptFollow: optional(multiple(option("-a", "--accept-follow", string({ metavar: "URI" }), { description: message`Accept follow requests from the given actor. The argument can be either an actor URI or a handle, or a wildcard (*). Can be specified multiple times. If a wildcard is specified, all follow requests will be accepted.` }))),
+	acceptFollow: optional(multiple(option("-a", "--accept-follow", string({ metavar: "URI" }), { description: message`Accept follow requests from the given actor. The argument can be either an actor URI or a handle, or a wildcard (${"*"}). Can be specified multiple times. If a wildcard is specified, all follow requests will be accepted.` }))),
 	noTunnel: option("-T", "--no-tunnel", { description: message`Do not tunnel the ephemeral ActivityPub server to the public Internet.` }),
 	actorName: withDefault(option("--actor-name", string({ metavar: "NAME" }), { description: message`Customize the actor display name.` }), "Fedify Ephemeral Inbox"),
 	actorSummary: withDefault(option("--actor-summary", string({ metavar: "SUMMARY" }), { description: message`Customize the actor description.` }), "An ephemeral ActivityPub inbox for testing purposes.")
-}), debugOption), { description: message`Spins up an ephemeral server that serves the ActivityPub inbox with an one-time actor, through a short-lived public DNS with HTTPS. You can monitor the incoming activities in real-time.` });
+}), debugOption), {
+	brief: message`Run an ephemeral ActivityPub inbox server.`,
+	description: message`Spins up an ephemeral server that serves the ActivityPub inbox with an one-time actor, through a short-lived public DNS with HTTPS. You can monitor the incoming activities in real-time.`
+});
 async function runInbox(command$1) {
 	const fetch = createFetchHandler({
 		actorName: command$1.actorName,

package/dist/init/command.js

@@ -1,25 +1,33 @@
 
       import { Temporal } from "@js-temporal/polyfill";
     
+import { debugOption } from "../globals.js";
 import { KV_STORE, MESSAGE_QUEUE, PACKAGE_MANAGER, WEB_FRAMEWORK } from "./const.js";
-import { argument, choice, command, constant, message, object, option, optional } from "@optique/core";
+import { argument, choice, command, constant, message, object, option, optionNames, optional } from "@optique/core";
 import { path } from "@optique/run";
 
 //#region src/init/command.ts
-const joinSep = (str) => str.join(" | ");
-const webFramework = optional(option("-w", "--web-framework", choice(WEB_FRAMEWORK, { metavar: `WEB_FRAMEWORK: ${joinSep(WEB_FRAMEWORK)}` })));
-const packageManager = optional(option("-p", "--package-manager", choice(PACKAGE_MANAGER, { metavar: `PACKAGE_MANAGER: ${joinSep(PACKAGE_MANAGER)}` })));
-const kvStore = optional(option("-k", "--kv-store", choice(KV_STORE, { metavar: `KV_STORE: ${joinSep(KV_STORE)}` })));
-const messageQueue = optional(option("-m", "--message-queue", choice(MESSAGE_QUEUE, { metavar: `MESSAGE_QUEUE: ${joinSep(MESSAGE_QUEUE)}` })));
-const initCommand = command("init", object({
+const webFramework = optional(option("-w", "--web-framework", choice(WEB_FRAMEWORK, { metavar: "WEB_FRAMEWORK" }), { description: message`The web framework to integrate Fedify with.` }));
+const packageManager = optional(option("-p", "--package-manager", choice(PACKAGE_MANAGER, { metavar: "PACKAGE_MANAGER" }), { description: message`The package manager to use for installing dependencies.` }));
+const kvStore = optional(option("-k", "--kv-store", choice(KV_STORE, { metavar: "KV_STORE" }), { description: message`The key-value store to use for caching and some other features.` }));
+const messageQueue = optional(option("-m", "--message-queue", choice(MESSAGE_QUEUE, { metavar: "MESSAGE_QUEUE" }), { description: message`The message queue to use for background tasks.` }));
+const initCommand = command("init", object("Initialization options", {
 	command: constant("init"),
-	dir: optional(argument(path({ metavar: "DIRECTORY" }))),
+	dir: optional(argument(path({ metavar: "DIR" }), { description: message`The project directory to initialize.  If a specified directory does not exist, it will be created.` })),
 	webFramework,
 	packageManager,
 	kvStore,
 	messageQueue,
-	dryRun: option("-d", "--dry-run")
-}), { description: message`Initialize a new Fedify project directory.` });
+	dryRun: option("-d", "--dry-run", { description: message`Perform a trial run with no changes made.` }),
+	debugOption
+}), {
+	brief: message`Initialize a new Fedify project directory.`,
+	description: message`Initialize a new Fedify project directory.
+
+By default, it initializes the current directory.  You can specify a different directory as an argument.
+
+Unless you specify all options (${optionNames(["-w", "--web-framework"])}, ${optionNames(["-p", "--package-manager"])}, ${optionNames(["-k", "--kv-store"])}, and ${optionNames(["-m", "--message-queue"])}), it will prompt you to select the options interactively.`
+});
 
 //#endregion
 export { initCommand };

package/dist/init/templates/defaults/federation.ts.tpl

@@ -0,0 +1,23 @@
+import { createFederation, Person } from "@fedify/fedify";
+import { getLogger } from "@logtape/logtape";
+/* imports */
+
+const logger = getLogger(/* logger */);
+
+const federation = createFederation({
+  kv: /* kv */,
+  queue: /* queue */,
+});
+
+federation.setActorDispatcher(
+  "/users/{identifier}",
+  async (ctx, identifier) => {
+    return new Person({
+      id: ctx.getActorUri(identifier),
+      preferredUsername: identifier,
+      name: identifier,
+    });
+  },
+);
+
+export default federation;

package/dist/init/templates/defaults/logging.ts.tpl

@@ -0,0 +1,23 @@
+import { configure, getConsoleSink } from "@logtape/logtape";
+import { AsyncLocalStorage } from "node:async_hooks";
+
+await configure({
+  contextLocalStorage: new AsyncLocalStorage(),
+  sinks: {
+    console: getConsoleSink(),
+  },
+  filters: {},
+  loggers: [
+    {
+      category: /* project name */,
+      lowestLevel: "debug",
+      sinks: ["console"],
+    },
+    { category: "fedify", lowestLevel: "info", sinks: ["console"] },
+    {
+      category: ["logtape", "meta"],
+      lowestLevel: "warning",
+      sinks: ["console"],
+    },
+  ],
+});

package/dist/init/templates/express/app.ts.tpl

@@ -0,0 +1,16 @@
+import { integrateFederation } from "@fedify/express";
+import { getLogger } from "@logtape/logtape";
+import express from "express";
+import federation from "./federation.ts";
+
+const logger = getLogger("/* logger */");
+
+export const app = express();
+
+app.set("trust proxy", true);
+
+app.use(integrateFederation(federation, () => undefined));
+
+app.get("/", (_, res) => res.send("Hello, Fedify!"));
+
+export default app;

package/dist/init/templates/express/index.ts.tpl

@@ -0,0 +1,6 @@
+import app from "./app.ts";
+import "./logging.ts";
+
+app.listen(8000, () => {
+  console.log("Server started at http://localhost:8000");
+});

package/dist/init/templates/hono/app.tsx.tpl

@@ -0,0 +1,14 @@
+// @ts-nocheck this file is just a template
+import { Hono } from "/* hono */";
+import { federation } from "@fedify/hono";
+import { getLogger } from "@logtape/logtape";
+import fedi from "./federation.ts";
+
+const logger = getLogger("/* logger */");
+
+const app = new Hono();
+app.use(federation(fedi, () => undefined));
+
+app.get("/", (c) => c.text("Hello, Fedify!"));
+
+export default app;

package/dist/init/templates/hono/index/bun.ts.tpl

@@ -0,0 +1,10 @@
+import { behindProxy } from "x-forwarded-fetch";
+import app from "./app.tsx";
+import "./logging.ts";
+
+const server = Bun.serve({
+  port: 8000,
+  fetch: behindProxy(app.fetch.bind(app)),
+});
+
+console.log("Server started at", server.url.href);

package/dist/init/templates/hono/index/deno.ts.tpl

@@ -0,0 +1,13 @@
+import { behindProxy } from "@hongminhee/x-forwarded-fetch";
+import "@std/dotenv/load";
+import app from "./app.tsx";
+import "./logging.ts";
+
+Deno.serve(
+  {
+    port: 8000,
+    onListen: ({ port, hostname }) =>
+      console.log("Server started at http://" + hostname + ":" + port),
+  },
+  behindProxy(app.fetch.bind(app)),
+);

package/dist/init/templates/hono/index/node.ts.tpl

@@ -0,0 +1,14 @@
+// @ts-nocheck this file is just a template
+import { serve } from "@hono/node-server";
+import { behindProxy } from "x-forwarded-fetch";
+import app from "./app.tsx";
+import "./logging.ts";
+
+serve(
+  {
+    port: 8000,
+    fetch: behindProxy(app.fetch.bind(app)),
+  },
+  (info) =>
+    console.log("Server started at http://" + info.address + ":" + info.port),
+);

package/dist/init/templates/next/middleware.ts.tpl

@@ -0,0 +1,45 @@
+import { fedifyWith } from "@fedify/next";
+import federation from "./federation";
+
+export default fedifyWith(federation)(
+/*
+  function (request: Request) {
+    // If you need to handle other requests besides federation
+    // requests in middleware, you can do it here.
+    // If you handle only federation requests in middleware,
+    // you don't need this function.
+    return NextResponse.next();
+  },
+*/
+)
+
+// This config needs because middleware process only requests with the
+// "Accept" header matching the federation accept regex.
+// More details: https://nextjs.org/docs/app/api-reference/file-conventions/middleware#config-object-optional
+export const config = {
+  runtime: "nodejs",
+  matcher: [
+    {
+      source: "/:path*",
+      has: [
+        {
+          type: "header",
+          key: "Accept",
+          value: ".*application\\/((jrd|activity|ld)\\+json|xrd\\+xml).*",
+        },
+      ],
+    },
+    {
+      source: "/:path*",
+      has: [
+        {
+          type: "header",
+          key: "content-type",
+          value: ".*application\\/((jrd|activity|ld)\\+json|xrd\\+xml).*",
+        },
+      ],
+    },
+    { source: "/.well-known/nodeinfo" },
+    { source: "/.well-known/x-nodeinfo2" },
+  ],
+};

package/dist/init/templates/nitro/nitro.config.ts.tpl

@@ -0,0 +1,5 @@
+// https://nitro.unjs.io/config
+export default defineNitroConfig({
+  srcDir: "server",
+  errorHandler: "~/error"
+});

package/dist/init/templates/nitro/server/error.ts.tpl

@@ -0,0 +1,3 @@
+import { onError } from "@fedify/h3";
+
+export default onError;

package/dist/init/templates/nitro/server/middleware/federation.ts.tpl

@@ -0,0 +1,8 @@
+
+import { integrateFederation } from "@fedify/h3";
+import federation from "../federation"
+
+export default integrateFederation(
+  federation,
+  (event, request) => undefined,
+);

package/dist/lookup.js

@@ -6,7 +6,7 @@ import { configureLogging, debugOption } from "./globals.js";
 import { spawnTemporaryServer } from "./tempserver.js";
 import { colorEnabled, colors, formatObject } from "./utils.js";
 import { renderImages } from "./imagerenderer.js";
-import { argument, choice, command, constant, flag, float, map, merge, message, multiple, object, option, optional, or, string, withDefault } from "@optique/core";
+import { argument, choice, command, constant, flag, float, map, merge, message, multiple, object, option, optionNames, optional, or, string, withDefault } from "@optique/core";
 import { path, print, printError } from "@optique/run";
 import process from "node:process";
 import { Application, Collection, CryptographicKey, Object as Object$1, generateCryptoKeyPair, getAuthenticatedDocumentLoader, lookupObject, respondWithObject, traverseCollection } from "@fedify/fedify";
@@ -22,7 +22,7 @@ const logger = getLogger([
 ]);
 const authorizedFetchOption = withDefault(object({
 	authorizedFetch: flag("-a", "--authorized-fetch", { description: message`Sign the request with an one-time key.` }),
-	firstKnock: withDefault(option("--first-knock", choice(["draft-cavage-http-signatures-12", "rfc9421"]), { description: message`The first-knock spec for -a/--authorized-fetch. It is used for the double-knocking technique.` }), "draft-cavage-http-signatures-12")
+	firstKnock: withDefault(option("--first-knock", choice(["draft-cavage-http-signatures-12", "rfc9421"]), { description: message`The first-knock spec for ${optionNames(["-a", "--authorized-fetch"])}. It is used for the double-knocking technique.` }), "draft-cavage-http-signatures-12")
 }), { authorizedFetch: false });
 const traverseOption = withDefault(object({
 	traverse: flag("-t", "--traverse", { description: message`Traverse the given collection(s) to fetch all items.` }),
@@ -42,7 +42,12 @@ const lookupCommand = command("lookup", merge("Looking up options", object({ com
 		min: 0,
 		metavar: "SECONDS"
 	}), { description: message`Set timeout for network requests in seconds.` }))
-})), { description: message`Lookup an Activity Streams object by URL or the actor handle. The argument can be either a URL or an actor handle (e.g., @username@domain), and it can be multiple.` });
+})), {
+	brief: message`Look up Activity Streams objects.`,
+	description: message`Look up Activity Streams objects by URL or actor handle.
+
+The arguments can be either URLs or actor handles (e.g., ${"@username@domain"}), and they can be multiple.`
+});
 var TimeoutError = class extends Error {
 	name = "TimeoutError";
 	constructor(message$1) {

package/dist/nodeinfo.js

@@ -27,15 +27,20 @@ const Jimp = createJimp({
 	plugins: defaultPlugins
 });
 const nodeInfoOption = optional(or(object({ raw: flag("-r", "--raw", { description: message`Show NodeInfo document in the raw JSON format` }) }), object({
-	bestEffort: optional(flag("-b", "--best-effort", { description: message`Parse the NodeInfo document with best effort. If the NodeInfo document is not well-formed, the option will try to parse it as much as possible.` })),
+	bestEffort: optional(flag("-b", "--best-effort", { description: message`Parse the NodeInfo document with best effort.  If the NodeInfo document is not well-formed, the option will try to parse it as much as possible.` })),
 	noFavicon: optional(flag("--no-favicon", { description: message`Disable fetching the favicon of the instance` })),
-	metadata: optional(flag("-m", "--metadata", { description: message`show the extra metadata of the NodeInfo, i.e., the metadata field of the document.` }))
+	metadata: optional(flag("-m", "--metadata", { description: message`Show the extra metadata of the NodeInfo, i.e., the metadata field of the document.` }))
 })));
-const userAgentOption = optional(object({ userAgent: option("-u", "--user-agent", string()) }));
+const userAgentOption = optional(object({ userAgent: option("-u", "--user-agent", string(), { description: message`The custom User-Agent header value.` }) }));
 const nodeInfoCommand = command("nodeinfo", merge(object({
 	command: constant("nodeinfo"),
-	host: argument(string({ metavar: "hostname or URL" }), { description: message`Bare hostname or a full URL of the instance` })
-}), debugOption, nodeInfoOption, userAgentOption), { description: message`Get information about a remote node using the NodeInfo protocol. The argument is the hostname of the remote node, or the URL of the remote node.` });
+	host: argument(string({ metavar: "HOST" }), { description: message`Bare hostname or a full URL of the instance` })
+}), debugOption, nodeInfoOption, userAgentOption), {
+	brief: message`Get information about a remote node using the NodeInfo protocol`,
+	description: message`Get information about a remote node using the NodeInfo protocol.
+
+The argument is the hostname of the remote node, or the URL of the remote node.`
+});
 async function runNodeInfo(command$1) {
 	const spinner = ora({
 		text: "Fetching a NodeInfo document...",

package/dist/tunnel.js

@@ -20,8 +20,13 @@ const tunnelCommand = command("tunnel", merge("Tunnel options", object({ command
 		"localhost.run",
 		"serveo.net",
 		"pinggy.io"
-	]), { description: message`The localtunnel service to use.` }))
-}), debugOption), { description: message`Expose a local HTTP server to the public internet using a secure tunnel.\nNote that the HTTP requests through the tunnel have X-Forwarded-* headers.` });
+	], { metavar: "SERVICE" }), { description: message`The tunneling service to use.` }))
+}), debugOption), {
+	brief: message`Expose a local HTTP server to the public internet using a secure tunnel.`,
+	description: message`Expose a local HTTP server to the public internet using a secure tunnel.
+
+Note that the HTTP requests through the tunnel have X-Forwarded-* headers.`
+});
 async function runTunnel(command$1, deps = {
 	openTunnel,
 	ora,

package/dist/webfinger/command.js

@@ -10,11 +10,16 @@ const allowPrivateAddresses = optional(flag("-p", "--allow-private-address", { d
 const maxRedirection = withDefault(option("--max-redirection", integer({ min: 0 }), { description: message`Maximum number of redirections to follow.` }), 5);
 const webFingerCommand = command("webfinger", merge(object({
 	command: constant("webfinger"),
-	resources: multiple(argument(string({ metavar: "RESOURCE" }), { description: message`WebFinger resource(s) to look up.` })),
+	resources: multiple(argument(string({ metavar: "RESOURCE" }), { description: message`WebFinger resource(s) to look up.` }), { min: 1 }),
 	userAgent,
 	allowPrivateAddresses,
 	maxRedirection
-}), debugOption), { description: message`Look up WebFinger resources. The argument can be multiple.` });
+}), debugOption), {
+	brief: message`Look up WebFinger resources.`,
+	description: message`Look up WebFinger resources.
+
+The argument can be multiple.`
+});
 
 //#endregion
 export { webFingerCommand };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fedify/cli",
-  "version": "2.0.0-pr.458.1796+f091195d",
+  "version": "2.0.0-pr.467.1877+dc12636d",
   "description": "CLI toolchain for Fedify and debugging ActivityPub",
   "keywords": [
     "fedify",
@@ -71,16 +71,16 @@
     "ora": "^8.2.0",
     "shiki": "^1.6.4",
     "srvx": "^0.8.7",
-    "@fedify/fedify": "2.0.0-pr.458.1796+f091195d",
-    "@fedify/sqlite": "2.0.0-pr.458.1796+f091195d",
-    "@fedify/vocab-runtime": "2.0.0-pr.458.1796+f091195d",
-    "@fedify/vocab-tools": "2.0.0-pr.458.1796+f091195d"
+    "@fedify/fedify": "2.0.0-pr.467.1877+dc12636d",
+    "@fedify/sqlite": "2.0.0-pr.467.1877+dc12636d",
+    "@fedify/vocab-runtime": "2.0.0-pr.467.1877+dc12636d",
+    "@fedify/vocab-tools": "2.0.0-pr.467.1877+dc12636d"
   },
   "devDependencies": {
     "@types/bun": "^1.2.23",
     "@types/node": "^22.17.0",
     "tsdown": "^0.12.9",
-    "typescript": "^5.9.2"
+    "typescript": "^5.9.3"
   },
   "scripts": {
     "codegen": "deno task -f @fedify/fedify codegen",

package/scripts/pack.ts

@@ -24,7 +24,9 @@ async function compile(os: OS, arch: Arch, into: string): Promise<void> {
   if (!target) {
     throw new Error(`Unsupported os/arch: ${os}/${arch}`);
   }
-  await $`deno compile --allow-all --target=${target} --output=${into} ${
+  await $`deno compile --allow-all --include=${
+    join("src", "init", "templates")
+  } --target=${target} --output=${into} ${
     join(dirname(import.meta.dirname!), "src", "mod.ts")
   }`;
 }
@@ -51,10 +53,15 @@ async function pack(os: OS, arch: Arch): Promise<void> {
   }
 }
 
+const osFilter = Deno.env.get("OS")?.toLowerCase();
+const archFilter = Deno.env.get("ARCH")?.toLowerCase();
+
 const promises: Promise<void>[] = [];
 for (const osKey in triplets) {
   const os = osKey as OS;
+  if (osFilter != null && osFilter !== os) continue;
   for (const arch in triplets[os]) {
+    if (archFilter != null && archFilter !== arch) continue;
     const promise = pack(os, arch as Arch);
     promises.push(promise);
   }

package/src/generate-vocab/command.ts

@@ -1,27 +1,35 @@
 import {
+  argument,
   command,
   constant,
   type InferValue,
   message,
   object,
   option,
+  withDefault,
 } from "@optique/core";
 import { path } from "@optique/run";
 
-const schemaDir = option(
-  "-i",
-  "--input",
-  path({ metavar: "DIR", type: "directory", mustExist: true }),
+const schemaDir = withDefault(
+  option(
+    "-i",
+    "--input",
+    path({ metavar: "DIR", type: "directory", mustExist: true }),
+    { description: message`Directory containing schema files.` },
+  ),
+  ".",
 );
-const generatedPath = option(
-  "-o",
-  "--output",
+const generatedPath = argument(
   path({ metavar: "PATH", type: "file", allowCreate: true }),
+  {
+    description:
+      message`Path to output the generated vocabulary classes.  Should end with ${".ts"} suffix.`,
+  },
 );
 
 const generateVocabCommand = command(
   "generate-vocab",
-  object({
+  object("Generation options", {
     command: constant("generate-vocab"),
     schemaDir,
     generatedPath,

package/src/inbox.tsx

@@ -79,7 +79,7 @@ export const inboxCommand = command(
         multiple(
           option("-a", "--accept-follow", string({ metavar: "URI" }), {
             description:
-              message`Accept follow requests from the given actor. The argument can be either an actor URI or a handle, or a wildcard (*). Can be specified multiple times. If a wildcard is specified, all follow requests will be accepted.`,
+              message`Accept follow requests from the given actor. The argument can be either an actor URI or a handle, or a wildcard (${"*"}). Can be specified multiple times. If a wildcard is specified, all follow requests will be accepted.`,
           }),
         ),
       ),
@@ -107,6 +107,7 @@ export const inboxCommand = command(
     debugOption,
   ),
   {
+    brief: message`Run an ephemeral ActivityPub inbox server.`,
     description:
       message`Spins up an ephemeral server that serves the ActivityPub inbox with an one-time actor, through a short-lived public DNS with HTTPS. You can monitor the incoming activities in real-time.`,
   },

package/src/init/command.ts

@@ -8,6 +8,7 @@ import {
   object,
   option,
   optional,
+  optionNames,
 } from "@optique/core";
 import { path } from "@optique/run";
 import {
@@ -16,48 +17,71 @@ import {
   PACKAGE_MANAGER,
   WEB_FRAMEWORK,
 } from "./const.ts";
+import { debugOption } from "../globals.ts";
 
-const joinSep = (str: readonly string[]) => str.join(" | ");
 const webFramework = optional(option(
   "-w",
   "--web-framework",
-  choice(WEB_FRAMEWORK, {
-    metavar: `WEB_FRAMEWORK: ${joinSep(WEB_FRAMEWORK)}`,
-  }),
+  choice(WEB_FRAMEWORK, { metavar: "WEB_FRAMEWORK" }),
+  {
+    description: message`The web framework to integrate Fedify with.`,
+  },
 ));
 const packageManager = optional(option(
   "-p",
   "--package-manager",
-  choice(PACKAGE_MANAGER, {
-    metavar: `PACKAGE_MANAGER: ${joinSep(PACKAGE_MANAGER)}`,
-  }),
+  choice(PACKAGE_MANAGER, { metavar: "PACKAGE_MANAGER" }),
+  {
+    description:
+      message`The package manager to use for installing dependencies.`,
+  },
 ));
 const kvStore = optional(option(
   "-k",
   "--kv-store",
-  choice(KV_STORE, { metavar: `KV_STORE: ${joinSep(KV_STORE)}` }),
+  choice(KV_STORE, { metavar: "KV_STORE" }),
+  {
+    description:
+      message`The key-value store to use for caching and some other features.`,
+  },
 ));
 const messageQueue = optional(option(
   "-m",
   "--message-queue",
-  choice(MESSAGE_QUEUE, {
-    metavar: `MESSAGE_QUEUE: ${joinSep(MESSAGE_QUEUE)}`,
-  }),
+  choice(MESSAGE_QUEUE, { metavar: "MESSAGE_QUEUE" }),
+  {
+    description: message`The message queue to use for background tasks.`,
+  },
 ));
 
 export const initCommand = command(
   "init",
-  object({
+  object("Initialization options", {
     command: constant("init"),
-    dir: optional(argument(path({ metavar: "DIRECTORY" }))),
+    dir: optional(argument(path({ metavar: "DIR" }), {
+      description:
+        message`The project directory to initialize.  If a specified directory does not exist, it will be created.`,
+    })),
     webFramework,
     packageManager,
     kvStore,
     messageQueue,
-    dryRun: option("-d", "--dry-run"),
+    dryRun: option("-d", "--dry-run", {
+      description: message`Perform a trial run with no changes made.`,
+    }),
+    debugOption,
   }),
   {
-    description: message`Initialize a new Fedify project directory.`,
+    brief: message`Initialize a new Fedify project directory.`,
+    description: message`Initialize a new Fedify project directory.
+
+By default, it initializes the current directory.  You can specify a different directory as an argument.
+
+Unless you specify all options (${optionNames(["-w", "--web-framework"])}, ${
+      optionNames(["-p", "--package-manager"])
+    }, ${optionNames(["-k", "--kv-store"])}, and ${
+      optionNames(["-m", "--message-queue"])
+    }), it will prompt you to select the options interactively.`,
   },
 );
 

package/src/lookup.ts

@@ -28,6 +28,7 @@ import {
   object,
   option,
   optional,
+  optionNames,
   or,
   string,
   withDefault,
@@ -54,8 +55,9 @@ export const authorizedFetchOption = withDefault(
         "--first-knock",
         choice(["draft-cavage-http-signatures-12", "rfc9421"]),
         {
-          description:
-            message`The first-knock spec for -a/--authorized-fetch. It is used for the double-knocking technique.`,
+          description: message`The first-knock spec for ${
+            optionNames(["-a", "--authorized-fetch"])
+          }. It is used for the double-knocking technique.`,
         },
       ),
       "draft-cavage-http-signatures-12" as const,
@@ -147,8 +149,11 @@ export const lookupCommand = command(
     }),
   ),
   {
+    brief: message`Look up Activity Streams objects.`,
     description:
-      message`Lookup an Activity Streams object by URL or the actor handle. The argument can be either a URL or an actor handle (e.g., @username@domain), and it can be multiple.`,
+      message`Look up Activity Streams objects by URL or actor handle.
+
+The arguments can be either URLs or actor handles (e.g., ${"@username@domain"}), and they can be multiple.`,
   },
 );
 

package/src/nodeinfo.ts

@@ -44,21 +44,23 @@ const nodeInfoOption = optional(
     object({
       bestEffort: optional(flag("-b", "--best-effort", {
         description:
-          message`Parse the NodeInfo document with best effort. If the NodeInfo document is not well-formed, the option will try to parse it as much as possible.`,
+          message`Parse the NodeInfo document with best effort.  If the NodeInfo document is not well-formed, the option will try to parse it as much as possible.`,
       })),
       noFavicon: optional(flag("--no-favicon", {
         description: message`Disable fetching the favicon of the instance`,
       })),
       metadata: optional(flag("-m", "--metadata", {
         description:
-          message`show the extra metadata of the NodeInfo, i.e., the metadata field of the document.`,
+          message`Show the extra metadata of the NodeInfo, i.e., the metadata field of the document.`,
       })),
     }),
   ),
 );
 
 const userAgentOption = optional(object({
-  userAgent: option("-u", "--user-agent", string()),
+  userAgent: option("-u", "--user-agent", string(), {
+    description: message`The custom User-Agent header value.`,
+  }),
 }));
 
 export const nodeInfoCommand = Command(
@@ -66,7 +68,7 @@ export const nodeInfoCommand = Command(
   merge(
     object({
       command: constant("nodeinfo"),
-      host: argument(string({ metavar: "hostname or URL" }), {
+      host: argument(string({ metavar: "HOST" }), {
         description: message`Bare hostname or a full URL of the instance`,
       }),
     }),
@@ -75,8 +77,12 @@ export const nodeInfoCommand = Command(
     userAgentOption,
   ),
   {
+    brief:
+      message`Get information about a remote node using the NodeInfo protocol`,
     description:
-      message`Get information about a remote node using the NodeInfo protocol. The argument is the hostname of the remote node, or the URL of the remote node.`,
+      message`Get information about a remote node using the NodeInfo protocol.
+
+The argument is the hostname of the remote node, or the URL of the remote node.`,
   },
 );
 

package/src/tunnel.ts

@@ -32,18 +32,22 @@ export const tunnelCommand = command(
         option(
           "-s",
           "--service",
-          choice(["localhost.run", "serveo.net", "pinggy.io"]),
-          {
-            description: message`The localtunnel service to use.`,
-          },
+          choice(["localhost.run", "serveo.net", "pinggy.io"], {
+            metavar: "SERVICE",
+          }),
+          { description: message`The tunneling service to use.` },
         ),
       ),
     }),
     debugOption,
   ),
   {
+    brief:
+      message`Expose a local HTTP server to the public internet using a secure tunnel.`,
     description:
-      message`Expose a local HTTP server to the public internet using a secure tunnel.\nNote that the HTTP requests through the tunnel have X-Forwarded-* headers.`,
+      message`Expose a local HTTP server to the public internet using a secure tunnel.
+
+Note that the HTTP requests through the tunnel have X-Forwarded-* headers.`,
   },
 );
 

package/src/webfinger/command.ts

@@ -41,9 +41,12 @@ export const webFingerCommand = command(
   merge(
     object({
       command: constant("webfinger"),
-      resources: multiple(argument(string({ metavar: "RESOURCE" }), {
-        description: message`WebFinger resource(s) to look up.`,
-      })),
+      resources: multiple(
+        argument(string({ metavar: "RESOURCE" }), {
+          description: message`WebFinger resource(s) to look up.`,
+        }),
+        { min: 1 },
+      ),
       userAgent,
       allowPrivateAddresses,
       maxRedirection,
@@ -51,8 +54,10 @@ export const webFingerCommand = command(
     debugOption,
   ),
   {
-    description:
-      message`Look up WebFinger resources. The argument can be multiple.`,
+    brief: message`Look up WebFinger resources.`,
+    description: message`Look up WebFinger resources.
+
+The argument can be multiple.`,
   },
 );
 

package/tsdown.config.ts

@@ -1,3 +1,5 @@
+import { cp } from "node:fs/promises";
+import { join } from "node:path";
 import { defineConfig } from "tsdown";
 
 export default defineConfig({
@@ -21,4 +23,13 @@ export default defineConfig({
     `;
     return outputOptions;
   },
+  hooks: {
+    "build:done": async (ctx) => {
+      await cp(
+        join("src", "init", "templates"),
+        join(ctx.options.outDir, "init", "templates"),
+        { recursive: true },
+      );
+    },
+  },
 });