@hypit/hypit 0.1.7 → 0.1.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypit/hypit",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "homepage": "https://hypit.ai",
   "repository": {
     "type": "git",

package/packages/cli/README.md

@@ -14,6 +14,11 @@ invent targets, candidates or Provider choices.
 Human and JSON output answer the same command-specific question. `--json` changes encoding;
 `--verbose` expands scope. Compiler, Runtime and Repository objects are not default reports.
 
+Argument errors use `CLI_USAGE` and point to the relevant `hypit help <command>`; JSON retains that
+command in `error.help`. Unknown help topics fail explicitly. Runtime and execution failures retain
+their own diagnostics and optional `--debug` trace. Result pagination changes only the `--before`
+cursor on the current query, preserving its project, Source filter and other options.
+
 | Command | Default scope | Explicit detail |
 | --- | --- | --- |
 | `check` | Validation, targets and counts | `--verbose`: exported names/types and historical references |
@@ -113,6 +118,9 @@ flow.
 execution phases and Provider diagnostics. It reads a finished Result directly, without opening the
 Runtime; an active Build is read through Runtime control. The selected Repository handles file access.
 `--lines` limits the tail and the report states the omitted count; JSON carries records plus that count.
+An unavailable log reports `source: "unavailable"` and exits unsuccessfully; a readable log with zero
+records is a successful empty result. The human report distinguishes a finished Result with no log
+from a lookup that still needs the Build's Runtime or correct project selection.
 `inspect` exposes an available log separately from authored Outputs. `hypit runtime logs` reads the
 Worker process log instead, for Runtime startup or process-level failures.
 

package/packages/cli/src/arguments.ts

@@ -13,6 +13,7 @@ import type {
   RuntimeSelectionCommand,
 } from "./command.js";
 import type { CliColorMode, CliOutputOptions } from "./output.js";
+import { CliUsageError } from "./usage-error.js";
 
 type RawOptions = {
   readonly presentation: CliOutputOptions;
@@ -48,6 +49,15 @@ type RawOptions = {
 const commonOptions = ["--json", "--color", "--no-color", "--verbose", "--debug"] as const;
 
 export function parseCommand(argv: readonly string[]): CliCommand {
+  try { return parseArguments(argv); }
+  catch (error) {
+    if (error instanceof CliUsageError) throw error;
+    throw new CliUsageError(error instanceof Error ? error.message : String(error),
+      argv[0] === undefined ? "hypit help" : `hypit help ${argv[0]}`, { cause: error });
+  }
+}
+
+function parseArguments(argv: readonly string[]): CliCommand {
   const [command, ...tail] = argv;
   switch (command) {
     case "check": {
@@ -246,7 +256,8 @@ export function parseCommand(argv: readonly string[]): CliCommand {
         ...optionalPackageRoot(options),
       };
     }
-    default: throw new Error(usage());
+    default: throw new CliUsageError(command === undefined ? "A command is required"
+      : `Unknown command ${JSON.stringify(command)}`, "hypit help");
   }
 }
 

package/packages/cli/src/commands/execution.ts

@@ -83,13 +83,19 @@ export async function runExecutionCommand(input: {
     const records = view?.records ?? [];
     const omitted = (view?.total ?? 0) - records.length;
     write({ format: "hypit.cli-logs@1", build: args.build, source, records, omittedRecords: omitted },
-      view === undefined ? "No execution log recorded" : "Build execution log", "info",
+      view === undefined ? "Execution log unavailable" : "Build execution log", view === undefined ? "warning" : "info",
       [["Build", args.build], ["Source", source]], [
+        ...(view !== undefined ? [] : [finished
+          ? "This Result has no saved execution log."
+          : activeProfile === undefined
+            ? "No saved log found in this project. Select the Build's Runtime with --runtime <profile> to check active execution."
+            : "No log found in this project's Results or the selected Runtime. Check the Build id and project selection."]),
         ...(omitted > 0 ? [`Showing last ${records.length} records; ${omitted} earlier records omitted. Use --lines to read more.`] : []),
         ...records.map((record) => `${new Date(record.time).toISOString()}  ${record.endpoint}  ${record.command}  ${
           record.kind === "phase" ? record.phase : record.kind === "diagnostic" || record.kind === "failed"
             ? `${record.kind}: ${record.message}` : record.kind}`),
       ]);
+    if (view === undefined) io.setExitCode?.(1);
     return;
   }
 

package/packages/cli/src/commands/results.ts

@@ -54,7 +54,9 @@ export async function runProjectResultCommand(input: {
       const label = item.title === undefined ? item.id : `${item.title} · ${item.id}`;
       const run = item.run === undefined ? "" : ` · ${item.run}`;
       return `${label}: ${item.outcome} · ${new Date(item.createdAt).toLocaleString()}${run} · ${item.targetCount} target${item.targetCount === 1 ? "" : "s"}`;
-    }).concat(page.next === undefined ? [] : [`Older    hypit builds --before ${page.next}`]));
+    }).concat(page.next === undefined ? [] : [
+      `Older    Repeat this command with --before ${page.next}, keeping the other options.`,
+    ]));
     return;
   }
 
@@ -89,7 +91,9 @@ export async function runProjectResultCommand(input: {
       const label = item.title === undefined ? item.build : `${item.title} · ${item.build}`;
       return `${label}: ${item.outcome} · ${new Date(item.createdAt).toLocaleString()}`
         + (args.presentation.verbose ? ` · ${item.output.kind} · ${item.output.type}` : "");
-    }).concat(page.next === undefined ? [] : [`Older    hypit history ${args.outputName} --before ${page.next}`]));
+    }).concat(page.next === undefined ? [] : [
+      `Older    Repeat this command with --before ${page.next}, keeping the other options.`,
+    ]));
     return;
   }
 

package/packages/cli/src/main.ts

@@ -62,7 +62,8 @@ export async function runCli(
   distribution: CliDistribution,
 ): Promise<void> {
   if (argv.length === 0 || argv[0] === "help" || argv.includes("--help")) {
-    const topic = argv[0] === "help" ? argv[1] : argv.includes("--help") ? argv[0] : undefined;
+    const topic = argv[0] === "help" ? argv[1] : argv[0] === "--help" ? undefined
+      : argv.includes("--help") ? argv[0] : undefined;
     writeCliHelp(io, topic);
     return;
   }

package/packages/cli/src/output.ts

@@ -3,6 +3,7 @@ import { relative, resolve } from "node:path";
 import type { CanonicalValue } from "@hypit/protocol";
 
 import type { OperationalMachineView } from "./machine-view.js";
+import { CliUsageError } from "./usage-error.js";
 
 export type CliTerminal = {
   readonly isTTY: boolean;
@@ -986,6 +987,7 @@ export function writeCliHelp(io: CliIo, topic?: string): void {
       io.write(`${selected.join("\n")}\n`);
       return;
     }
+    throw new CliUsageError(`Unknown help topic ${JSON.stringify(topic)}`, "hypit help");
   }
   io.write([
     colors.accent(colors.strong("Hypit")),
@@ -1044,6 +1046,7 @@ export function renderCliError(error: unknown, options: {
       error: {
         code,
         message: source.message,
+        ...(source instanceof CliUsageError ? { help: source.help } : {}),
         ...(options.debug && trace !== undefined && trace.length > 0 ? { trace } : {}),
       },
     }, null, 2)}\n`;
@@ -1058,6 +1061,8 @@ export function renderCliError(error: unknown, options: {
   ];
   if (options.debug && trace !== undefined && trace.length > 0) {
     lines.push("", colors.dim(trace));
+  } else if (source instanceof CliUsageError) {
+    lines.push("", `Usage    ${source.help}`);
   } else {
     lines.push("", colors.dim("Run with --debug to include the internal stack trace."));
   }

package/packages/cli/src/usage-error.ts

@@ -0,0 +1,8 @@
+/** Argument errors point to public usage rather than an internal stack trace. */
+export class CliUsageError extends Error {
+  readonly code = "CLI_USAGE";
+  constructor(message: string, readonly help: string, options?: ErrorOptions) {
+    super(message, options);
+    this.name = "CliUsageError";
+  }
+}