@ours.network/cli 0.1.0 → 0.2.0

package/dist/commands.d.ts

@@ -0,0 +1,178 @@
+import type { OperationName } from './operations.js';
+export interface OperationCommandSpec {
+    kind: 'operation';
+    operation: OperationName;
+    defaults?: Readonly<Record<string, unknown>>;
+}
+export type NativeCommandSpec = {
+    kind: 'daemon';
+    handler: 'serve' | 'start' | 'stop' | 'restart' | 'status' | 'install-service' | 'uninstall-service';
+    summary: string;
+    effects: string;
+    example: string;
+} | {
+    kind: 'config';
+    handler: 'show' | 'setup';
+    summary: string;
+    effects: string;
+    example: string;
+};
+export type CommandSpec = OperationCommandSpec | NativeCommandSpec;
+export interface CommandGroupSpec {
+    summary: string;
+    commands: Readonly<Record<string, CommandSpec>>;
+}
+export declare const COMMAND_GROUPS: {
+    readonly daemon: {
+        readonly summary: "Run, inspect, and integrate the shared ours daemon.";
+        readonly commands: {
+            readonly serve: {
+                readonly kind: "daemon";
+                readonly handler: "serve";
+                readonly summary: "Run the daemon in the foreground until interrupted.";
+                readonly effects: "Starts a daemon in this process. --managed also writes the CLI-owned PID record used by stop and restart.";
+                readonly example: "ours daemon serve --config /etc/ours/config.json";
+            };
+            readonly start: {
+                readonly kind: "daemon";
+                readonly handler: "start";
+                readonly summary: "Start a detached daemon managed by this CLI.";
+                readonly effects: "Spawns a background process, writes a PID record and log in the selected state directory, and waits up to 20 seconds for readiness.";
+                readonly example: "ours daemon start --config /etc/ours/config.json";
+            };
+            readonly stop: {
+                readonly kind: "daemon";
+                readonly handler: "stop";
+                readonly summary: "Stop a daemon previously started by this CLI.";
+                readonly effects: "Signals only a process corroborated by the selected daemon and CLI-owned PID record; it refuses to signal externally managed daemons.";
+                readonly example: "ours daemon stop --config /etc/ours/config.json";
+            };
+            readonly restart: {
+                readonly kind: "daemon";
+                readonly handler: "restart";
+                readonly summary: "Stop and start a CLI-managed daemon.";
+                readonly effects: "Uses the same ownership checks as stop, then starts a detached replacement.";
+                readonly example: "ours daemon restart --config /etc/ours/config.json";
+            };
+            readonly status: {
+                readonly kind: "daemon";
+                readonly handler: "status";
+                readonly summary: "Report whether the selected daemon is running and CLI-managed.";
+                readonly effects: "Read-only. Exit status is 0 when running and 3 when stopped.";
+                readonly example: "ours daemon status --json";
+            };
+            readonly 'install-service': {
+                readonly kind: "daemon";
+                readonly handler: "install-service";
+                readonly summary: "Install and enable the Linux user systemd service.";
+                readonly effects: "Changes ~/.config/systemd/user/ours.service and runs systemctl --user. Requires --yes unless --dry-run is used; --force may replace only an existing unowned unit.";
+                readonly example: "ours daemon install-service --dry-run --json";
+            };
+            readonly 'uninstall-service': {
+                readonly kind: "daemon";
+                readonly handler: "uninstall-service";
+                readonly summary: "Disable and remove the Linux user systemd service owned by this CLI.";
+                readonly effects: "Changes the user service manager. Requires --yes unless --dry-run is used and refuses to remove an unowned unit.";
+                readonly example: "ours daemon uninstall-service --dry-run --json";
+            };
+            readonly info: OperationCommandSpec;
+            readonly identities: OperationCommandSpec;
+            readonly unread: OperationCommandSpec;
+            readonly watch: OperationCommandSpec;
+        };
+    };
+    readonly config: {
+        readonly summary: "Inspect redacted connection configuration or update safe daemon settings.";
+        readonly commands: {
+            readonly show: {
+                readonly kind: "config";
+                readonly handler: "show";
+                readonly summary: "Show the resolved daemon selection and redacted stored configuration.";
+                readonly effects: "Read-only. Reports whether token/STT sections exist but never prints their secret values.";
+                readonly example: "ours config show --json";
+            };
+            readonly setup: {
+                readonly kind: "config";
+                readonly handler: "setup";
+                readonly summary: "Write one or more safe daemon settings noninteractively.";
+                readonly effects: "Writes a mode-0600 JSON config unless --dry-run is used. Unknown and secret fields already present are preserved and never printed.";
+                readonly example: "ours config setup --port 3070 --state-dir /srv/ours-a --api-visibility owner";
+            };
+        };
+    };
+    readonly identity: {
+        readonly summary: "Create, bind, inspect, pin, release, and remove identities.";
+        readonly commands: {
+            readonly create: OperationCommandSpec;
+            readonly 'create-temporary': OperationCommandSpec;
+            readonly 'close-temporary': OperationCommandSpec;
+            readonly 'create-root': OperationCommandSpec;
+            readonly pin: OperationCommandSpec;
+            readonly use: OperationCommandSpec;
+            readonly list: OperationCommandSpec;
+            readonly show: OperationCommandSpec;
+            readonly remove: OperationCommandSpec;
+            readonly release: OperationCommandSpec;
+        };
+    };
+    readonly profile: {
+        readonly summary: "Update the bound identity’s public bio or private local persona.";
+        readonly commands: {
+            readonly 'set-bio': OperationCommandSpec;
+            readonly 'set-persona': OperationCommandSpec;
+        };
+    };
+    readonly invite: {
+        readonly summary: "Create, inspect, revoke, and accept encrypted contact invitations.";
+        readonly commands: {
+            readonly create: OperationCommandSpec;
+            readonly list: OperationCommandSpec;
+            readonly revoke: OperationCommandSpec;
+            readonly accept: OperationCommandSpec;
+        };
+    };
+    readonly contact: {
+        readonly summary: "Inspect contacts and manage local introductions and contact policy.";
+        readonly commands: {
+            readonly list: OperationCommandSpec;
+            readonly local: OperationCommandSpec;
+            readonly policy: OperationCommandSpec;
+            readonly remove: OperationCommandSpec;
+            readonly rename: OperationCommandSpec;
+            readonly respond: OperationCommandSpec;
+        };
+    };
+    readonly message: {
+        readonly summary: "Send encrypted text and manage the incoming message queue.";
+        readonly commands: {
+            readonly send: OperationCommandSpec;
+            readonly list: OperationCommandSpec;
+            readonly get: OperationCommandSpec;
+            readonly defer: OperationCommandSpec;
+        };
+    };
+    readonly file: {
+        readonly summary: "Send encrypted files and authorize, retrieve, or defer received files.";
+        readonly commands: {
+            readonly send: OperationCommandSpec;
+            readonly list: OperationCommandSpec;
+            readonly get: OperationCommandSpec;
+            readonly fetch: OperationCommandSpec;
+            readonly defer: OperationCommandSpec;
+        };
+    };
+    readonly conversation: {
+        readonly summary: "Inspect retained conversations and receipts, mark them read, and set retention policy.";
+        readonly commands: {
+            readonly show: OperationCommandSpec;
+            readonly receipts: OperationCommandSpec;
+            readonly 'mark-read': OperationCommandSpec;
+            readonly policy: OperationCommandSpec;
+        };
+    };
+};
+export type CommandGroup = keyof typeof COMMAND_GROUPS;
+export declare const DESTRUCTIVE_OPERATIONS: Set<"version" | "identities" | "unread" | "create-identity" | "create-temporary-identity" | "close-temporary-identity" | "create-root-identity" | "define-local-identity-file" | "choose-identity" | "list-identities" | "current-identity" | "remove-identity" | "release-lease" | "generate-invite" | "list-invites" | "revoke-invite" | "add-contact" | "list-contacts" | "list-local-contact-book" | "set-local-book-policy" | "remove-contact" | "rename-contact" | "respond-to-introduction" | "set-bio" | "set-persona" | "send-message" | "send-file" | "list-incoming-messages" | "get-messages" | "defer-messages" | "defer-files" | "get-conversation" | "get-receipts" | "mark-read" | "set-conversation-policy" | "list-incoming-files" | "get-files" | "state-dir" | "watch-notifications" | "fetch-file">;
+export declare const IDENTITY_PREBIND_EXCEPTIONS: Set<"version" | "identities" | "unread" | "create-identity" | "create-temporary-identity" | "close-temporary-identity" | "create-root-identity" | "define-local-identity-file" | "choose-identity" | "list-identities" | "current-identity" | "remove-identity" | "release-lease" | "generate-invite" | "list-invites" | "revoke-invite" | "add-contact" | "list-contacts" | "list-local-contact-book" | "set-local-book-policy" | "remove-contact" | "rename-contact" | "respond-to-introduction" | "set-bio" | "set-persona" | "send-message" | "send-file" | "list-incoming-messages" | "get-messages" | "defer-messages" | "defer-files" | "get-conversation" | "get-receipts" | "mark-read" | "set-conversation-policy" | "list-incoming-files" | "get-files" | "state-dir" | "watch-notifications" | "fetch-file">;
+export declare function isCommandGroup(value: string): value is CommandGroup;
+export declare function commandSpec(group: CommandGroup, command: string): CommandSpec | undefined;

package/dist/commands.js

@@ -0,0 +1,14 @@
+import {
+  COMMAND_GROUPS,
+  DESTRUCTIVE_OPERATIONS,
+  IDENTITY_PREBIND_EXCEPTIONS,
+  commandSpec,
+  isCommandGroup
+} from "./chunk-YSHMCQ2B.js";
+export {
+  COMMAND_GROUPS,
+  DESTRUCTIVE_OPERATIONS,
+  IDENTITY_PREBIND_EXCEPTIONS,
+  commandSpec,
+  isCommandGroup
+};

package/dist/help.d.ts

@@ -0,0 +1,4 @@
+export declare function renderTopHelp(version: string): string;
+export declare function helpRequestPath(argv: string[]): string[] | null;
+export declare function renderHelp(path: string[], version: string): string;
+export declare function helpHint(group?: string, action?: string): string;

package/dist/help.js

@@ -0,0 +1,15 @@
+import {
+  helpHint,
+  helpRequestPath,
+  renderHelp,
+  renderTopHelp
+} from "./chunk-HNBWRI4O.js";
+import "./chunk-QRNZFPNJ.js";
+import "./chunk-6NFATG6P.js";
+import "./chunk-YSHMCQ2B.js";
+export {
+  helpHint,
+  helpRequestPath,
+  renderHelp,
+  renderTopHelp
+};

package/dist/main.js

@@ -1,3 +1,8 @@
+import {
+  processIo,
+  writeError,
+  writeResult
+} from "./chunk-YC7QBGVC.js";
 import {
   createLinuxUserSystemdAdapter
 } from "./chunk-67BC2E5U.js";
@@ -6,96 +11,49 @@ import {
   showConfig
 } from "./chunk-G2GHHOYX.js";
 import {
-  inspectDaemon,
-  serveDaemon,
-  startDaemonManaged,
-  stopDaemonManaged
-} from "./chunk-4IFFMMQO.js";
-import {
-  attachClient,
-  defaultConfigPath,
-  resolveSelection
-} from "./chunk-6W3RHW3C.js";
+  helpHint,
+  helpRequestPath,
+  renderHelp
+} from "./chunk-HNBWRI4O.js";
 import {
   invokeOperation,
   isOperationName,
+  operationEmptyValueFlags,
   operationInputFromFlags,
   operationNames,
   operationValueFlags,
   parseOperationJson
-} from "./chunk-IUZOQT4D.js";
+} from "./chunk-QRNZFPNJ.js";
 import {
   CliUsageError,
   parseBoolean,
   parseFlags,
   parseInteger
-} from "./chunk-AXXFFER2.js";
+} from "./chunk-6NFATG6P.js";
 import {
-  processIo,
-  writeError,
-  writeResult
-} from "./chunk-YC7QBGVC.js";
+  DESTRUCTIVE_OPERATIONS,
+  IDENTITY_PREBIND_EXCEPTIONS,
+  commandSpec,
+  isCommandGroup
+} from "./chunk-YSHMCQ2B.js";
+import {
+  inspectDaemon,
+  serveDaemon,
+  startDaemonManaged,
+  stopDaemonManaged
+} from "./chunk-4IFFMMQO.js";
+import {
+  attachClient,
+  defaultConfigPath,
+  resolveSelection
+} from "./chunk-6W3RHW3C.js";
 
 // src/main.ts
 import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
-var CLI_VERSION = false ? "0.0.0-dev" : "0.1.0";
+var CLI_VERSION = false ? "0.0.0-dev" : "0.2.0";
 var COMMON_VALUES = /* @__PURE__ */ new Set(["--endpoint", "--port", "--state-dir", "--config", "--identity"]);
 var COMMON_BOOLEANS = /* @__PURE__ */ new Set(["--json", "--yes", "--help"]);
-var DESTRUCTIVE = /* @__PURE__ */ new Set(["close-temporary-identity", "remove-identity", "revoke-invite", "remove-contact"]);
-var GROUPED = {
-  daemon: {
-    info: { operation: "version" },
-    identities: { operation: "identities" },
-    unread: { operation: "unread" },
-    watch: { operation: "watch-notifications" }
-  },
-  identity: {
-    create: { operation: "create-identity", defaults: { bio: "", exposeLocal: true, localAutoAccept: true } },
-    "create-temporary": { operation: "create-temporary-identity", defaults: { bio: "", exposeLocal: false, localAutoAccept: true } },
-    "close-temporary": { operation: "close-temporary-identity" },
-    "create-root": { operation: "create-root-identity", defaults: { bio: "", exposeLocal: true, localAutoAccept: true, skipIfRootExists: true } },
-    pin: { operation: "define-local-identity-file", defaults: { force: false, exposeLocal: true, localAutoAccept: true, overwrite: false } },
-    use: { operation: "choose-identity", defaults: { force: false } },
-    list: { operation: "list-identities" },
-    show: { operation: "current-identity" },
-    remove: { operation: "remove-identity" },
-    release: { operation: "release-lease" }
-  },
-  profile: { "set-bio": { operation: "set-bio" }, "set-persona": { operation: "set-persona" } },
-  invite: { create: { operation: "generate-invite" }, list: { operation: "list-invites" }, revoke: { operation: "revoke-invite" }, accept: { operation: "add-contact" } },
-  contact: {
-    list: { operation: "list-contacts" },
-    local: { operation: "list-local-contact-book" },
-    policy: { operation: "set-local-book-policy" },
-    remove: { operation: "remove-contact" },
-    rename: { operation: "rename-contact" },
-    respond: { operation: "respond-to-introduction" }
-  },
-  message: { send: { operation: "send-message" }, list: { operation: "list-incoming-messages" }, get: { operation: "get-messages" }, defer: { operation: "defer-messages" } },
-  file: { send: { operation: "send-file" }, list: { operation: "list-incoming-files" }, get: { operation: "get-files" }, fetch: { operation: "fetch-file" }, defer: { operation: "defer-files" } },
-  conversation: {
-    show: { operation: "get-conversation" },
-    receipts: { operation: "get-receipts" },
-    "mark-read": { operation: "mark-read" },
-    policy: { operation: "set-conversation-policy" }
-  }
-};
-var HELP = `ours ${CLI_VERSION} \u2014 operator CLI for the shared ours daemon
-
-Usage:
-  ours daemon serve|start|stop|restart|status [selection options]
-  ours daemon install-service|uninstall-service --yes [--dry-run]
-  ours daemon info|identities|unread|watch [operation options]
-  ours config show|setup [configuration options]
-  ours identity|profile|invite|contact|message|file|conversation <command> [options]
-  ours api list | ours api <operation> [--input JSON|--input-file PATH]
-  ours version
-
-Selection: --endpoint URL --port N --state-dir PATH --config PATH
-Output: --json. Destructive operations require --yes.
-Run \`ours api list --json\` for the expert operation allowlist.
-`;
 function selectionFrom(values) {
   return {
     endpoint: values["--endpoint"],
@@ -105,11 +63,11 @@ function selectionFrom(values) {
   };
 }
 function requireYes(operation, yes) {
-  if (DESTRUCTIVE.has(operation) && !yes) throw new CliUsageError(`${operation} is destructive; re-run with --yes`);
+  if (DESTRUCTIVE_OPERATIONS.has(operation) && !yes) throw new CliUsageError(`${operation} is destructive; re-run with --yes`);
 }
 async function runOperation(operation, input, selection, identity, io, json) {
   const client = await attachClient(await resolveSelection(selection));
-  if (identity !== void 0 && !["choose-identity", "create-identity", "create-temporary-identity", "create-root-identity"].includes(operation)) {
+  if (identity !== void 0 && !IDENTITY_PREBIND_EXCEPTIONS.has(operation)) {
     await client.chooseIdentity({ name: identity, force: false });
   }
   if (operation === "watch-notifications") {
@@ -133,7 +91,8 @@ async function runOperation(operation, input, selection, identity, io, json) {
 async function runApi(args, io) {
   const operation = args[0];
   if (operation === "list") {
-    const flags2 = parseFlags(args.filter((value) => value !== "list"), /* @__PURE__ */ new Set(), /* @__PURE__ */ new Set(["--json", "--help"]));
+    const flags2 = parseFlags(args.slice(1), /* @__PURE__ */ new Set(), /* @__PURE__ */ new Set(["--json", "--help"]));
+    if (flags2.positionals.length !== 0) throw new CliUsageError("api list accepts no positional arguments");
     writeResult(io, operationNames(), flags2.booleans.has("--json"), "operations");
     return 0;
   }
@@ -150,9 +109,14 @@ async function runApi(args, io) {
 }
 async function runGrouped(group, args, io) {
   const action = args[0];
-  const spec = action === void 0 ? void 0 : GROUPED[group]?.[action];
-  if (!action || !spec) throw new CliUsageError(`unknown ${group} command ${JSON.stringify(action ?? "")}`);
-  const flags = parseFlags(args, /* @__PURE__ */ new Set([...COMMON_VALUES, ...operationValueFlags(spec.operation)]), COMMON_BOOLEANS);
+  const spec = action === void 0 ? void 0 : commandSpec(group, action);
+  if (!action || !spec || spec.kind !== "operation") throw new CliUsageError(`unknown ${group} command ${JSON.stringify(action ?? "")}`);
+  const flags = parseFlags(
+    args,
+    /* @__PURE__ */ new Set([...COMMON_VALUES, ...operationValueFlags(spec.operation)]),
+    COMMON_BOOLEANS,
+    operationEmptyValueFlags(spec.operation)
+  );
   if (flags.positionals.length !== 1) throw new CliUsageError(`${group} accepts exactly one command`);
   requireYes(spec.operation, flags.booleans.has("--yes"));
   const input = operationInputFromFlags(spec.operation, flags.values, spec.defaults);
@@ -163,9 +127,10 @@ async function runConfig(args, io) {
   const values = /* @__PURE__ */ new Set([...COMMON_VALUES, "--broker-url", "--gc-interval-ms", "--auto-start", "--api-visibility"]);
   const flags = parseFlags(args, values, /* @__PURE__ */ new Set(["--json", "--dry-run", "--help"]));
   const action = flags.positionals[0];
-  if (flags.positionals.length !== 1 || !["show", "setup"].includes(action)) throw new CliUsageError("config requires show or setup");
+  const spec = action === void 0 ? void 0 : commandSpec("config", action);
+  if (flags.positionals.length !== 1 || !spec || spec.kind !== "config") throw new CliUsageError("config requires show or setup");
   const json = flags.booleans.has("--json");
-  if (action === "show") {
+  if (spec.handler === "show") {
     writeResult(io, await showConfig(selectionFrom(flags.values)), json, "config");
     return 0;
   }
@@ -186,48 +151,54 @@ async function runConfig(args, io) {
 }
 async function runDaemon(args, io) {
   const action = args[0];
-  if (action && GROUPED.daemon[action]) return runGrouped("daemon", args, io);
+  const spec = action === void 0 ? void 0 : commandSpec("daemon", action);
+  if (spec?.kind === "operation") return runGrouped("daemon", args, io);
   const values = new Set(COMMON_VALUES);
   const booleans = /* @__PURE__ */ new Set([...COMMON_BOOLEANS, "--managed", "--dry-run", "--force"]);
   const flags = parseFlags(args, values, booleans);
   if (flags.positionals.length !== 1) throw new CliUsageError("daemon accepts exactly one command");
+  if (!spec || spec.kind !== "daemon") throw new CliUsageError(`unknown daemon command ${JSON.stringify(action ?? "")}`);
+  const handler = spec.handler;
   const selection = selectionFrom(flags.values);
   const json = flags.booleans.has("--json");
-  if (action === "serve") return serveDaemon(selection, flags.booleans.has("--managed"));
-  if (action === "status") {
+  if (handler === "serve") return serveDaemon(selection, flags.booleans.has("--managed"));
+  if (handler === "status") {
     const status = await inspectDaemon(await resolveSelection(selection));
     writeResult(io, status, json, status.state);
     return status.state === "running" ? 0 : 3;
   }
-  if (action === "start") {
+  if (handler === "start") {
     writeResult(io, await startDaemonManaged(selection), json, "started");
     return 0;
   }
-  if (action === "stop") {
+  if (handler === "stop") {
     writeResult(io, await stopDaemonManaged(await resolveSelection(selection)), json, "stopped");
     return 0;
   }
-  if (action === "restart") {
+  if (handler === "restart") {
+    if (selection.endpoint !== void 0) throw new CliUsageError("--endpoint selects a running daemon and cannot be used with daemon restart");
     await stopDaemonManaged(await resolveSelection(selection));
     writeResult(io, await startDaemonManaged(selection), json, "restarted");
     return 0;
   }
-  if (action === "install-service" || action === "uninstall-service") {
+  if (handler === "install-service" || handler === "uninstall-service") {
     const dryRun = flags.booleans.has("--dry-run");
-    if (!dryRun && !flags.booleans.has("--yes")) throw new CliUsageError(`${action} changes the user service manager; re-run with --yes or preview with --dry-run`);
+    if (!dryRun && !flags.booleans.has("--yes")) throw new CliUsageError(`${handler} changes the user service manager; re-run with --yes or preview with --dry-run`);
     const adapter = createLinuxUserSystemdAdapter();
     const context = { cliPath: process.argv[1], configPath: selection.configPath, dryRun, force: flags.booleans.has("--force") };
-    const result = action === "install-service" ? await adapter.install(context) : await adapter.uninstall(context);
-    writeResult(io, result, json, action);
+    const result = handler === "install-service" ? await adapter.install(context) : await adapter.uninstall(context);
+    writeResult(io, result, json, handler);
     return 0;
   }
-  throw new CliUsageError(`unknown daemon command ${JSON.stringify(action ?? "")}`);
+  const unsupported = handler;
+  throw new Error(`unsupported daemon handler: ${String(unsupported)}`);
 }
 async function runCli(argv, io = processIo) {
   const wantsJson = argv.includes("--json");
   try {
-    if (argv.length === 0 || argv.includes("--help") || argv[0] === "help") {
-      io.stdout(HELP);
+    const helpPath = helpRequestPath(argv);
+    if (helpPath !== null) {
+      io.stdout(renderHelp(helpPath, CLI_VERSION));
       return 0;
     }
     const [command, ...args] = argv;
@@ -235,14 +206,18 @@ async function runCli(argv, io = processIo) {
       writeResult(io, wantsJson ? { name: "@ours.network/cli", version: CLI_VERSION } : `ours ${CLI_VERSION}`, wantsJson);
       return 0;
     }
-    if (command === "daemon") return await runDaemon(args, io);
-    if (command === "config") return await runConfig(args, io);
     if (command === "api") return await runApi(args, io);
-    if (GROUPED[command]) return await runGrouped(command, args, io);
+    if (isCommandGroup(command)) {
+      if (command === "daemon") return await runDaemon(args, io);
+      if (command === "config") return await runConfig(args, io);
+      return await runGrouped(command, args, io);
+    }
     throw new CliUsageError(`unknown command ${JSON.stringify(command)}`);
   } catch (error) {
-    writeError(io, error, wantsJson);
-    return error instanceof CliUsageError ? error.exitCode : 1;
+    const reported = error instanceof CliUsageError && !/run `ours help/i.test(error.message) ? new CliUsageError(`${error.message}
+${helpHint(argv[0], argv[1])}`) : error;
+    writeError(io, reported, wantsJson);
+    return reported instanceof CliUsageError ? reported.exitCode : 1;
   }
 }
 export {