silvermoon 0.0.3 → 0.1.1

package/src/cli.js

@@ -1,116 +1,73 @@
 import { readFileSync } from "node:fs";
-import { Command, CommanderError, Option } from "commander";
-
+import {
+  Command,
+  CommanderError,
+  InvalidArgumentError,
+  Option,
+} from "commander";
+
+import {
+  canonicalizeLanguageTag,
+  canonicalizeOutputLanguage,
+} from "./language.js";
+import { renderCheck, renderDialogue } from "./dialogue.js";
 import { checkRepository } from "./index.js";
 import { createIdea } from "./create-idea.js";
+import { withTraceFile } from "./trace.js";
 import { whatsNext } from "./whatsnext.js";
 
 const { version: VERSION } = JSON.parse(
   readFileSync(new URL("../package.json", import.meta.url), "utf8"),
 );
 
+const TRACE_FILE_SUFFIX = ".trace.jsonl";
+
 function write(method, value) {
   const text = value.replace(/\n$/, "");
   if (text) method(text);
 }
 
+export function normalizeTraceFileName(value) {
+  return value.endsWith(TRACE_FILE_SUFFIX)
+    ? value
+    : `${value}${TRACE_FILE_SUFFIX}`;
+}
+
 function addCommonOptions(command) {
   return command
-    .option("--json", "emit the complete machine-readable report")
+    .option("--json", "serialize the conversation envelope as JSON")
+    .option(
+      "--trace <file.trace.jsonl>",
+      "write task timing spans as JSONL (suffix is appended when omitted)",
+      normalizeTraceFileName,
+    )
     .option("-r, --root <path>", "repository root", process.cwd());
 }
 
-function renderDiagnostics(report, io) {
-  for (const item of report.diagnostics) {
-    const location = item.path ? ` ${item.path}` : "";
-    const output = item.level === "error" ? io.error : io.log;
-    output(`${item.level.toUpperCase()} ${item.code}${location}: ${item.message}`);
-    output(`  Fix: ${item.remediation}`);
-  }
-}
-
-function renderIdeaIdentity(idea) {
-  return idea.alias === undefined ? idea.id : `${idea.id} (${idea.alias})`;
-}
-
-function renderRemediation(remediation) {
-  return remediation.kind === "command"
-    ? `${remediation.executable} ${remediation.args.join(" ")}`
-    : `${remediation.description} (${remediation.path})`;
-}
-
-function renderWhatsNext(result, io) {
-  if (result.onboarding) {
-    io.log(`onboarding ${result.onboarding.status}`);
-    for (const item of result.onboarding.gaps) {
-      io.log(
-        `  ${item.status.padEnd(12)} ${item.id}${item.blocking ? " [blocking]" : " [non-blocking]"}: ${item.title}`,
-      );
-      io.log(`    depends  ${item.dependencies.length ? item.dependencies.join(", ") : "none"}`);
-      io.log(`    observed ${JSON.stringify(item.observed)}`);
-      if (item.remediation) io.log(`    fix      ${renderRemediation(item.remediation)}`);
-    }
-    if (result.onboarding.recommendedAction) {
-      io.log(`  next     ${renderRemediation(result.onboarding.recommendedAction)}`);
-    }
-    io.log(`  recheck  ${renderRemediation(result.onboarding.recheck)}`);
-  }
-  io.log(`${result.action.code}: ${result.action.message}`);
-  io.log(`  language ${result.language.tag} (${result.language.source})`);
-  if (result.observedPrimaryCommit) io.log(`  primary  ${result.observedPrimaryCommit}`);
-  if (result.selectedIdea) {
-    io.log(`  idea     ${renderIdeaIdentity(result.selectedIdea)}`);
-    io.log(`  state    ${result.selectedIdea.state}`);
-    io.log(`  ideal   ${result.selectedIdea.idealRevision}`);
-    io.log(`  inner   ${result.selectedIdea.implementationRevision}`);
-    io.log(`  outer   ${result.selectedIdea.deploymentRevision}`);
-  }
-  if (result.action.details?.world) {
-    const world = result.action.details.world;
-    io.log(`  world    ${world.name} (${world.displayName})`);
-    io.log(`  entry    ${world.documentPath}`);
-    io.log(`  support  ${world.auxiliaryRoot}`);
-    io.log(`  decision ${world.decisionField}: ${world.revision}`);
-    io.log(`  cascade  ${world.cascade}`);
-  }
-  for (const idea of result.action.details?.ideas ?? []) {
-    io.log(`  option   ${renderIdeaIdentity(idea)}  ${idea.state}`);
-  }
+export function render(report, json, io) {
+  io.log(
+    json
+      ? JSON.stringify(report, null, 2)
+      : report.intention.command === "check"
+        ? renderCheck(report)
+        : renderDialogue(report),
+  );
 }
 
-function renderCreateIdea(result, io) {
-  if (!result.createdIdea) {
-    renderWhatsNext(result, io);
-    return;
+function contentLanguageArgument(value) {
+  try {
+    return canonicalizeLanguageTag(value);
+  } catch (caught) {
+    throw new InvalidArgumentError(caught.message);
   }
-  io.log(`created: ${result.createdIdea.id}`);
-  io.log(`  idea    ${result.createdIdea.ideaPath}`);
-  io.log(`  ledger  ${result.createdIdea.ledgerPath}`);
-  io.log(`  status  ${result.createdIdea.statusPath}`);
 }
 
-export function render(report, json, io) {
-  if (json) {
-    io.log(JSON.stringify(report, null, 2));
-    return;
-  }
-  renderDiagnostics(report, io);
-  if (!report.ok) {
-    io.error("FAILED");
-    return;
-  }
-  if (report.command === "whats-next") {
-    renderWhatsNext(report.result, io);
-    return;
-  }
-  if (report.command === "create-idea") {
-    renderCreateIdea(report.result, io);
-    return;
+function outputLanguageArgument(value) {
+  try {
+    return canonicalizeOutputLanguage(value);
+  } catch (caught) {
+    throw new InvalidArgumentError(caught.message);
   }
-  io.log(`OK: ${report.command}`);
-  io.log(`  target  ${report.result.target}`);
-  if (report.result.commit) io.log(`  commit  ${report.result.commit}`);
-  io.log(`  ideas   ${report.result.checked}`);
 }
 
 export function createProgram(io = console) {
@@ -133,9 +90,12 @@ export function createProgram(io = console) {
 Examples:
   $ silvermoon whats-next
   $ silvermoon whats-next <idea>
+  $ silvermoon whats-next <idea> --language zh-CN
   $ silvermoon whats-next <idea> --json
+  $ silvermoon whats-next <idea> --trace whats-next.trace.jsonl
   $ silvermoon create-idea
   $ silvermoon check
+  $ silvermoon check --language en-US
   $ silvermoon check --worktree
   $ silvermoon check --staged
   $ silvermoon check --commit HEAD
@@ -144,45 +104,94 @@ Examples:
   addCommonOptions(
     program
       .command("whats-next [idea]")
-      .description("fetch primary and render the highest-priority next action"),
+      .description("observe project, repository, and idea readiness")
+      .option(
+        "--language <tag>",
+        "use a built-in output language (en-US or zh-CN) for this invocation",
+        outputLanguageArgument,
+      ),
   ).action(async (idea, options) => {
-    const report = await whatsNext({ enforceOnboarding: true, idea, root: options.root });
+    const report = await withTraceFile(
+      options.trace,
+      "command.whats-next",
+      {
+        command: "whats-next",
+        outputLanguage: options.language ?? null,
+        processId: process.pid,
+      },
+      () => whatsNext({
+        idea,
+        language: options.language,
+        root: options.root,
+      }),
+    );
     render(report, options.json, io);
-    program.setOptionValue("resultCode", report.ok ? 0 : 1);
+    program.setOptionValue("resultCode", 0);
   });
 
   addCommonOptions(
     program
       .command("create-idea")
-      .description("create one structured idea scaffold after primary hygiene")
-      .option("--language <tag>", "persist a canonical language override on the new idea"),
+      .description("create one structured idea scaffold after readiness checks")
+      .option(
+        "--language <tag>",
+        "persist a canonical content language override on the new idea",
+        contentLanguageArgument,
+      ),
   ).action(async (options) => {
-    const report = await createIdea({
-      language: options.language,
-      root: options.root,
-    });
+    const report = await withTraceFile(
+      options.trace,
+      "command.create-idea",
+      {
+        command: "create-idea",
+        contentLanguage: options.language ?? null,
+        processId: process.pid,
+      },
+      () => createIdea({
+        language: options.language,
+        root: options.root,
+      }),
+    );
     render(report, options.json, io);
-    program.setOptionValue("resultCode", report.ok ? 0 : 1);
+    program.setOptionValue("resultCode", 0);
   });
 
   addCommonOptions(
     program
       .command("check")
-      .description("validate Silvermoon configuration, idea state, and an optional Git target")
-      .addOption(new Option("--remote", "fetch and validate the primary tip selected by HEAD").conflicts(["commit", "staged", "worktree"]))
+      .description("validate Silvermoon configuration and idea state")
+      .option(
+        "--language <tag>",
+        "use a built-in output language (en-US or zh-CN) for this invocation",
+        outputLanguageArgument,
+      )
+      .addOption(new Option("--remote", "fetch and validate the configured primary tip").conflicts(["commit", "staged", "worktree"]))
       .addOption(new Option("--commit <revision>", "validate one local commit snapshot").conflicts(["remote", "staged", "worktree"]))
       .addOption(new Option("--staged", "validate the index snapshot").conflicts(["remote", "commit", "worktree"]))
-      .addOption(new Option("--worktree", "validate HEAD plus all staged, unstaged, and untracked changes").conflicts(["remote", "commit", "staged"])),
+      .addOption(new Option("--worktree", "validate HEAD plus staged, unstaged, and untracked changes").conflicts(["remote", "commit", "staged"])),
   ).action(async (options) => {
-    const report = await checkRepository({
-      commit: options.commit,
-      remote: options.remote,
-      root: options.root,
-      staged: options.staged,
-      worktree: options.worktree,
-    });
+    const report = await withTraceFile(
+      options.trace,
+      "command.check",
+      {
+        command: "check",
+        outputLanguage: options.language ?? null,
+        processId: process.pid,
+      },
+      () => checkRepository({
+        commit: options.commit,
+        language: options.language,
+        remote: options.remote,
+        root: options.root,
+        staged: options.staged,
+        worktree: options.worktree,
+      }),
+    );
     render(report, options.json, io);
-    program.setOptionValue("resultCode", report.ok ? 0 : 1);
+    program.setOptionValue(
+      "resultCode",
+      report.observation.state === "project-ready" ? 0 : 1,
+    );
   });
 
   return program;
@@ -194,8 +203,12 @@ export async function runCli(args, io = console) {
     await program.parseAsync(args.length === 0 ? ["--help"] : args, { from: "user" });
   } catch (caught) {
     if (caught instanceof CommanderError) return caught.exitCode === 0 ? 0 : 2;
+    if (caught.exitCode === 2) {
+      io.error(`ERROR usage: ${caught.message}`);
+      return 2;
+    }
     io.error(`ERROR command.failed: ${caught.message}`);
     return 1;
   }
   return program.getOptionValue("resultCode") ?? 0;
-}
+}