silvermoon 0.2.1 → 0.3.0-rc.1

package/src/adoption.js

@@ -15,6 +15,7 @@ import { traceAsync } from "./trace.js";
 
 const packageRoot = fileURLToPath(new URL("..", import.meta.url));
 const packageJson = JSON.parse(await readFile(resolve(packageRoot, "package.json"), "utf8"));
+const DEFAULT_FILESYSTEM = { lstat, readFile, readdir };
 const packagedSkillsRoot = resolve(packageRoot, "skills");
 const packagedSkill = resolve(packagedSkillsRoot, "silvermoon");
 const localSkillsRoot = "./node_modules/silvermoon/skills";
@@ -95,7 +96,7 @@ function packageManagerDescriptor(manager, workspace, reason = null) {
   };
 }
 
-async function detectPackageManager(root, manifest) {
+async function detectPackageManager(root, manifest, filesystem) {
   const workspace = workspaceRoot(manifest);
   if (Object.hasOwn(manifest, "packageManager")) {
     const declaration = manifest.packageManager;
@@ -116,7 +117,7 @@ async function detectPackageManager(root, manifest) {
   const uncertain = [];
   for (const [filename, manager] of lockfileManagers) {
     try {
-      const metadata = await lstat(resolve(root, filename));
+      const metadata = await filesystem.lstat(resolve(root, filename));
       if (metadata.isFile()) detected.push({ filename, manager });
       else uncertain.push(filename);
     } catch (caught) {
@@ -141,13 +142,13 @@ async function detectPackageManager(root, manifest) {
   return packageManagerDescriptor(managers[0] ?? "npm", workspace);
 }
 
-export function dependencyInstallCommand(manager, workspace, version = SILVERMOON_VERSION) {
+export function dependencyInstallCommands(manager, workspace, version = SILVERMOON_VERSION) {
   const packageSpecifier = `silvermoon@^${version}`;
   if (manager === "npm") {
-    return { executable: "npm", args: ["install", "--save-dev", packageSpecifier] };
+    return [{ executable: "npm", args: ["install", "--save-dev", packageSpecifier] }];
   }
   if (manager === "pnpm") {
-    return {
+    return [{
       executable: "pnpm",
       args: [
         "add",
@@ -155,21 +156,19 @@ export function dependencyInstallCommand(manager, workspace, version = SILVERMOO
         packageSpecifier,
         ...(workspace ? ["--workspace-root"] : []),
       ],
-    };
+    }];
   }
   if (manager === "yarn") {
-    return {
-      executable: "yarn",
-      args: [
-        "add",
-        packageSpecifier,
-        "--dev",
-        ...(workspace ? ["--ignore-workspace-root-check"] : []),
-      ],
-    };
+    return [
+      {
+        executable: "npm",
+        args: ["pkg", "set", `devDependencies.silvermoon=^${version}`],
+      },
+      { executable: "yarn", args: ["install"] },
+    ];
   }
   if (manager === "bun") {
-    return { executable: "bun", args: ["add", packageSpecifier, "--dev"] };
+    return [{ executable: "bun", args: ["add", packageSpecifier, "--dev"] }];
   }
   return null;
 }
@@ -183,12 +182,12 @@ function renderCommand({ executable, args }) {
 }
 
 export function renderDependencyCommand(manager, workspace, version = SILVERMOON_VERSION) {
-  const command = dependencyInstallCommand(manager, workspace, version);
-  return command ? renderCommand(command) : null;
+  const commands = dependencyInstallCommands(manager, workspace, version);
+  return commands ? commands.map(renderCommand).join("\n") : null;
 }
 
 function dependencyInstruction(packageManager) {
-  const command = packageManager.manager
+  const renderedCommands = packageManager.manager
     ? renderDependencyCommand(
       packageManager.manager,
       packageManager.workspace,
@@ -198,10 +197,14 @@ function dependencyInstruction(packageManager) {
   if (!expectedDependency) {
     return `The running Silvermoon version ${JSON.stringify(SILVERMOON_VERSION)} is not a supported SemVer version; repair the package before declaring its dependency.`;
   }
-  if (!command) {
+  if (!renderedCommands) {
     return `Do not guess a package-manager command. ${packageManager.reason} Resolve the root package-manager/workspace configuration, then add silvermoon@${expectedDependency} to the root devDependencies.`;
   }
-  return `From the repository root, run \`${command}\` to set root devDependencies.silvermoon to ${expectedDependency}.`;
+  const commands = renderedCommands.split("\n");
+  if (commands.length === 1) {
+    return `From the repository root, run \`${commands[0]}\` to set root devDependencies.silvermoon to ${expectedDependency}.`;
+  }
+  return `From the repository root, run these commands in order: ${commands.map((command) => `\`${command}\``).join(", then ")} to set root devDependencies.silvermoon to ${expectedDependency}.`;
 }
 
 function skillInstruction(skill, packageManager) {
@@ -218,12 +221,15 @@ function skillInstruction(skill, packageManager) {
 export async function inspectNpmProject(
   snapshotRoot,
   repositoryRoot,
-  { readManifest = readFile } = {},
+  {
+    filesystem = DEFAULT_FILESYSTEM,
+    readManifest = filesystem.readFile,
+  } = {},
 ) {
   const manifestPath = resolve(snapshotRoot, "package.json");
   let metadata;
   try {
-    metadata = await lstat(manifestPath);
+    metadata = await filesystem.lstat(manifestPath);
   } catch (caught) {
     if (caught.code === "ENOENT") return { npmProject: false, findings: [] };
     return {
@@ -293,7 +299,11 @@ export async function inspectNpmProject(
     };
   }
 
-  const packageManager = await detectPackageManager(snapshotRoot, manifest);
+  const packageManager = await detectPackageManager(
+    snapshotRoot,
+    manifest,
+    filesystem,
+  );
   const findings = [];
   const sourceCheckout = isSilvermoonSourceCheckout(repositoryRoot, manifest);
   if (!expectedDependency) {
@@ -367,11 +377,13 @@ function canonicalSkillBytes(content) {
   }
 }
 
-async function directoryDigest(root) {
+async function directoryDigest(root, filesystem) {
   const hash = createHash("sha256");
 
   async function visit(directory) {
-    const entries = (await readdir(directory, { withFileTypes: true }))
+    const entries = (
+      await filesystem.readdir(directory, { withFileTypes: true })
+    )
       .sort((left, right) => left.name.localeCompare(right.name));
     for (const entry of entries) {
       const path = resolve(directory, entry.name);
@@ -380,7 +392,7 @@ async function directoryDigest(root) {
       } else if (entry.isFile()) {
         hash.update(relative(root, path).split(sep).join("/"));
         hash.update("\0");
-        hash.update(canonicalSkillBytes(await readFile(path)));
+        hash.update(canonicalSkillBytes(await filesystem.readFile(path)));
         hash.update("\0");
       } else if (entry.isSymbolicLink()) {
         await visit(path);
@@ -394,16 +406,16 @@ async function directoryDigest(root) {
   return hash.digest("hex");
 }
 
-async function inspectSkill(contentRoot) {
+async function inspectSkill(contentRoot, filesystem) {
   const path = resolve(contentRoot, ...REPOSITORY_SKILL_PATH.split("/"));
   const expectedDigest = await traceAsync(
     "skill.digest-packaged",
     {},
-    () => directoryDigest(packagedSkill),
+    () => directoryDigest(packagedSkill, DEFAULT_FILESYSTEM),
   );
   let metadata;
   try {
-    metadata = await lstat(path);
+    metadata = await filesystem.lstat(path);
   } catch (caught) {
     if (caught.code !== "ENOENT") {
       return {
@@ -442,7 +454,7 @@ async function inspectSkill(contentRoot) {
     actualDigest = await traceAsync(
       "skill.digest-repository",
       {},
-      () => directoryDigest(path),
+      () => directoryDigest(path, filesystem),
     );
   } catch (caught) {
     return {
@@ -471,10 +483,14 @@ async function inspectSkill(contentRoot) {
 
 export async function inspectAdoption({
   contentRoot,
+  filesystem = DEFAULT_FILESYSTEM,
+  repositoryRoot: knownRepositoryRoot,
   root = process.cwd(),
 } = {}) {
   const requestedRoot = resolve(root);
-  const git = runGit(requestedRoot, ["rev-parse", "--show-toplevel"]);
+  const git = knownRepositoryRoot === undefined
+    ? runGit(requestedRoot, ["rev-parse", "--show-toplevel"])
+    : { ok: true, stdout: resolve(knownRepositoryRoot) };
   const repositoryRoot = git.ok ? resolve(git.stdout) : requestedRoot;
   const snapshotRoot = resolve(contentRoot ?? repositoryRoot);
   const findings = [];
@@ -493,7 +509,7 @@ export async function inspectAdoption({
   const loadedConfig = await traceAsync(
     "config.load",
     {},
-    () => loadConfig({ root: snapshotRoot }),
+    () => loadConfig({ filesystem, root: snapshotRoot }),
   );
   for (const diagnostic of loadedConfig.diagnostics) {
     findings.push({
@@ -507,7 +523,7 @@ export async function inspectAdoption({
   const npm = await traceAsync(
     "npm-project.inspect",
     {},
-    () => inspectNpmProject(snapshotRoot, repositoryRoot),
+    () => inspectNpmProject(snapshotRoot, repositoryRoot, { filesystem }),
   );
   findings.push(...npm.findings);
   const skillSource = npm.npmProject && !npm.sourceCheckout
@@ -516,7 +532,7 @@ export async function inspectAdoption({
   const skill = await traceAsync(
     "skill.inspect",
     {},
-    () => inspectSkill(snapshotRoot, skillSource),
+    () => inspectSkill(snapshotRoot, filesystem),
   );
   if (!skill.ok) {
     findings.push({

package/src/cli.js

@@ -15,7 +15,7 @@ import { listIdeas } from "./list-ideas.js";
 import { checkRepository } from "./index.js";
 import { createIdea } from "./create-idea.js";
 import { renderResponse } from "./response.js";
-import { withTraceFile } from "./trace.js";
+import { traceAsync, withTraceFile } from "./trace.js";
 import { whatsNext } from "./whatsnext.js";
 
 const { version: VERSION } = JSON.parse(
@@ -23,6 +23,7 @@ const { version: VERSION } = JSON.parse(
 );
 
 const TRACE_FILE_SUFFIX = ".trace.jsonl";
+const AUDIENCES = ["human", "agent"];
 
 function write(method, value) {
   const text = value.replace(/\n$/, "");
@@ -38,6 +39,14 @@ export function normalizeTraceFileName(value) {
 function addCommonOptions(command) {
   return command
     .option("--json", "serialize all four command projections as JSON")
+    .addOption(
+      new Option(
+        "--audience <audience>",
+        "select human TUI or agent Markdown output (default: human)",
+      )
+        .choices(AUDIENCES)
+        .conflicts("json"),
+    )
     .option(
       "--trace <file.trace.jsonl>",
       "write domain and timing events as JSONL (suffix is appended when omitted)",
@@ -46,11 +55,106 @@ function addCommonOptions(command) {
     .option("-r, --root <path>", "repository root", process.cwd());
 }
 
-export function render(report, json, io) {
-  io.log(
-    json
-      ? JSON.stringify(report, null, 2)
-      : renderResponse(report.response),
+export function selectOutputRenderer({
+  audience = "human",
+  json = false,
+  stdinIsTTY = false,
+  stdoutIsTTY = false,
+}) {
+  if (json) return "json";
+  if (audience === "human" && stdinIsTTY && stdoutIsTTY) return "tui";
+  return "markdown";
+}
+
+async function defaultTuiRenderer(content, terminal) {
+  const { renderTuiMarkdown } = await import("./tui.js");
+  await renderTuiMarkdown(content, terminal);
+}
+
+export async function render(
+  report,
+  { audience = "human", json = false } = {},
+  io = console,
+  {
+    renderTui = defaultTuiRenderer,
+    terminal = { stdin: process.stdin, stdout: process.stdout },
+  } = {},
+) {
+  const renderer = selectOutputRenderer({
+    audience,
+    json,
+    stdinIsTTY: terminal.stdin.isTTY === true,
+    stdoutIsTTY: terminal.stdout.isTTY === true,
+  });
+  if (renderer === "json") {
+    io.log(JSON.stringify(report, null, 2));
+    return;
+  }
+
+  const markdown = renderResponse(report.response);
+  if (renderer === "tui") {
+    await renderTui(markdown, terminal);
+    return;
+  }
+  io.log(markdown);
+}
+
+function outputRenderer(options, runtime) {
+  const terminal = runtime.terminal ?? {
+    stdin: process.stdin,
+    stdout: process.stdout,
+  };
+  return selectOutputRenderer({
+    audience: options.audience,
+    json: options.json,
+    stdinIsTTY: terminal.stdin.isTTY === true,
+    stdoutIsTTY: terminal.stdout.isTTY === true,
+  });
+}
+
+function bootstrapDuration(runtime) {
+  if (typeof runtime.bootstrapStartedAt !== "bigint") return {};
+  const elapsed = process.hrtime.bigint() - runtime.bootstrapStartedAt;
+  return {
+    bootstrapDurationMs: Math.round(Number(elapsed) / 1_000) / 1_000,
+  };
+}
+
+async function runCommand({
+  attributes,
+  execute,
+  name,
+  options,
+}, io, runtime) {
+  const renderer = outputRenderer(options, runtime);
+  const traceAttributes = {
+    ...attributes,
+    outputRenderer: renderer,
+    ...bootstrapDuration(runtime),
+  };
+  if (renderer === "tui") {
+    const report = await withTraceFile(
+      options.trace,
+      name,
+      traceAttributes,
+      execute,
+    );
+    await render(report, options, io, runtime);
+    return report;
+  }
+  return withTraceFile(
+    options.trace,
+    name,
+    traceAttributes,
+    async () => {
+      const report = await execute();
+      await traceAsync(
+        "output.render",
+        { renderer },
+        () => render(report, options, io, runtime),
+      );
+      return report;
+    },
   );
 }
 
@@ -74,7 +178,7 @@ function collectOption(value, previous = []) {
   return [...previous, value];
 }
 
-export function createProgram(io = console) {
+export function createProgram(io = console, runtime = {}) {
   const program = new Command();
   program
     .name("silvermoon")
@@ -93,10 +197,12 @@ export function createProgram(io = console) {
     .addHelpText("after", `
 Examples:
   $ silvermoon list-ideas
+  $ silvermoon list-ideas --language zh-CN
   $ silvermoon list-ideas --state completed --sort oldest --limit 10
   $ silvermoon whats-next
   $ silvermoon whats-next <idea>
   $ silvermoon whats-next <idea> --language zh-CN
+  $ silvermoon whats-next <idea> --audience agent
   $ silvermoon whats-next <idea> --json
   $ silvermoon whats-next <idea> --trace whats-next.trace.jsonl
   $ silvermoon create-idea
@@ -111,6 +217,11 @@ Examples:
     program
       .command("list-ideas")
       .description("query the current local idea inventory")
+      .option(
+        "--language <tag>",
+        "use a built-in output language (en, en-US, zh, or zh-CN) for this invocation",
+        outputLanguageArgument,
+      )
       .option(
         "--state <state>",
         "include a lifecycle state or active (repeatable)",
@@ -138,20 +249,21 @@ Examples:
       sort: options.sort,
       states: options.state,
     });
-    const report = await withTraceFile(
-      options.trace,
-      "command.list-ideas",
-      {
+    const report = await runCommand({
+      name: "command.list-ideas",
+      options,
+      attributes: {
         command: "list-ideas",
         hasQuery: query.query !== null,
+        outputLanguage: options.language ?? null,
         stateCount: query.states.length,
       },
-      () => listIdeas({
+      execute: () => listIdeas({
         ...query,
+        language: options.language,
         root: options.root,
       }),
-    );
-    render(report, options.json, io);
+    }, io, runtime);
     program.setOptionValue(
       "resultCode",
       report.observation.state === "ideas-listed" ? 0 : 1,
@@ -164,24 +276,23 @@ Examples:
       .description("observe project, repository, and idea readiness")
       .option(
         "--language <tag>",
-        "use a built-in output language (en-US or zh-CN) for this invocation",
+        "use a built-in output language (en, en-US, zh, or zh-CN) for this invocation",
         outputLanguageArgument,
       ),
   ).action(async (idea, options) => {
-    const report = await withTraceFile(
-      options.trace,
-      "command.whats-next",
-      {
+    const report = await runCommand({
+      name: "command.whats-next",
+      options,
+      attributes: {
         command: "whats-next",
         outputLanguage: options.language ?? null,
       },
-      () => whatsNext({
+      execute: () => whatsNext({
         idea,
         language: options.language,
         root: options.root,
       }),
-    );
-    render(report, options.json, io);
+    }, io, runtime);
     program.setOptionValue("resultCode", 0);
   });
 
@@ -195,19 +306,18 @@ Examples:
         contentLanguageArgument,
       ),
   ).action(async (options) => {
-    const report = await withTraceFile(
-      options.trace,
-      "command.create-idea",
-      {
+    const report = await runCommand({
+      name: "command.create-idea",
+      options,
+      attributes: {
         command: "create-idea",
         contentLanguage: options.language ?? null,
       },
-      () => createIdea({
+      execute: () => createIdea({
         language: options.language,
         root: options.root,
       }),
-    );
-    render(report, options.json, io);
+    }, io, runtime);
     program.setOptionValue("resultCode", 0);
   });
 
@@ -217,7 +327,7 @@ Examples:
       .description("validate Silvermoon configuration and idea state")
       .option(
         "--language <tag>",
-        "use a built-in output language (en-US or zh-CN) for this invocation",
+        "use a built-in output language (en, en-US, zh, or zh-CN) for this invocation",
         outputLanguageArgument,
       )
       .addOption(new Option("--remote", "fetch and validate the configured primary tip").conflicts(["commit", "staged", "worktree"]))
@@ -225,14 +335,14 @@ Examples:
       .addOption(new Option("--staged", "validate the index snapshot").conflicts(["remote", "commit", "worktree"]))
       .addOption(new Option("--worktree", "validate HEAD plus staged, unstaged, and untracked changes").conflicts(["remote", "commit", "staged"])),
   ).action(async (options) => {
-    const report = await withTraceFile(
-      options.trace,
-      "command.check",
-      {
+    const report = await runCommand({
+      name: "command.check",
+      options,
+      attributes: {
         command: "check",
         outputLanguage: options.language ?? null,
       },
-      () => checkRepository({
+      execute: () => checkRepository({
         commit: options.commit,
         language: options.language,
         remote: options.remote,
@@ -240,8 +350,7 @@ Examples:
         staged: options.staged,
         worktree: options.worktree,
       }),
-    );
-    render(report, options.json, io);
+    }, io, runtime);
     program.setOptionValue(
       "resultCode",
       report.observation.state === "project-ready" ? 0 : 1,
@@ -251,8 +360,8 @@ Examples:
   return program;
 }
 
-export async function runCli(args, io = console) {
-  const program = createProgram(io);
+export async function runCli(args, io = console, runtime = {}) {
+  const program = createProgram(io, runtime);
   try {
     await program.parseAsync(args.length === 0 ? ["--help"] : args, { from: "user" });
   } catch (caught) {

package/src/config.js

@@ -1,6 +1,7 @@
 import { lstat, readFile } from "node:fs/promises";
 import { resolve } from "node:path";
 
+import { inspectTreeLineage, readGitBlobs } from "./git.js";
 import { CONFIG_PATH, METADATA_ROOT } from "./layout.js";
 import { isCanonicalLanguageTag } from "./language.js";
 import { validBranchName, validRepository } from "./repository.js";
@@ -14,28 +15,32 @@ const CONFIG_KEYS = [
   "primaryBranch",
   "preferredLanguage",
 ];
+const DEFAULT_FILESYSTEM = { lstat, readFile };
 
 function configDiagnostic(code, path, message, remediation) {
   return { code, level: "error", path, message, remediation };
 }
 
-async function regularRepositoryFile(root) {
+async function regularRepositoryFile(root, filesystem) {
   const metadataRoot = resolve(root, METADATA_ROOT);
   const absolutePath = resolve(root, CONFIG_PATH);
   try {
-    const directoryMetadata = await lstat(metadataRoot);
+    const directoryMetadata = await filesystem.lstat(metadataRoot);
     if (!directoryMetadata.isDirectory() || directoryMetadata.isSymbolicLink()) {
       throw Object.assign(new Error(`${METADATA_ROOT} must be a regular directory`), {
         code: "EINVAL",
       });
     }
-    const fileMetadata = await lstat(absolutePath);
+    const fileMetadata = await filesystem.lstat(absolutePath);
     if (!fileMetadata.isFile() || fileMetadata.isSymbolicLink()) {
       throw Object.assign(new Error("Configuration must be a regular file"), {
         code: "EINVAL",
       });
     }
-    return { absolutePath, source: await readFile(absolutePath, "utf8") };
+    return {
+      absolutePath,
+      source: await filesystem.readFile(absolutePath, "utf8"),
+    };
   } catch (error) {
     const missing = error.code === "ENOENT";
     return {
@@ -70,17 +75,8 @@ export function serializeConfig(config) {
   return stringifyCanonicalYaml(canonical);
 }
 
-export async function loadConfig({ root }) {
-  const loaded = await regularRepositoryFile(root);
-  if (loaded.diagnostic) {
-    return {
-      config: null,
-      configPath: loaded.absolutePath,
-      diagnostics: [loaded.diagnostic],
-    };
-  }
-
-  const normalizedSource = loaded.source.replaceAll("\r\n", "\n");
+function parseConfigSource({ absolutePath, root, source }) {
+  const normalizedSource = source.replaceAll("\r\n", "\n");
   let value;
   try {
     value = parseStrictYaml(normalizedSource);
@@ -187,7 +183,71 @@ export async function loadConfig({ root }) {
 
   return {
     config: diagnostics.length === 0 ? value : null,
-    configPath: loaded.absolutePath,
+    configPath: absolutePath,
     diagnostics,
   };
 }
+
+export async function loadConfig({
+  filesystem = DEFAULT_FILESYSTEM,
+  root,
+}) {
+  const loaded = await regularRepositoryFile(root, filesystem);
+  if (loaded.diagnostic) {
+    return {
+      config: null,
+      configPath: loaded.absolutePath,
+      diagnostics: [loaded.diagnostic],
+    };
+  }
+  return parseConfigSource({
+    absolutePath: loaded.absolutePath,
+    root,
+    source: loaded.source,
+  });
+}
+
+export async function loadConfigSnapshot({ gitRoot, tree }) {
+  const absolutePath = resolve(gitRoot, CONFIG_PATH);
+  const entries = inspectTreeLineage(gitRoot, tree, CONFIG_PATH);
+  const metadataRoot = entries.find(({ name }) => name === METADATA_ROOT);
+  const config = entries.find(({ name }) => name === CONFIG_PATH);
+  if (metadataRoot === undefined || config === undefined) {
+    return {
+      config: null,
+      configPath: absolutePath,
+      diagnostics: [configDiagnostic(
+        "config.missing",
+        CONFIG_PATH,
+        `Missing Silvermoon configuration: ${CONFIG_PATH}`,
+        `Create ${CONFIG_PATH}.`,
+      )],
+    };
+  }
+  if (
+    metadataRoot.type !== "tree"
+    || metadataRoot.mode !== "040000"
+    || config.type !== "blob"
+    || !["100644", "100755"].includes(config.mode)
+  ) {
+    return {
+      config: null,
+      configPath: absolutePath,
+      diagnostics: [configDiagnostic(
+        "config.invalid-file",
+        CONFIG_PATH,
+        "Cannot read Silvermoon configuration: configuration paths must be regular",
+        `Replace ${METADATA_ROOT} and ${CONFIG_PATH} with repository-owned regular paths.`,
+      )],
+    };
+  }
+  const source = readGitBlobs(gitRoot, [config.object]).get(config.object);
+  if (source === undefined) {
+    throw new Error(`Cannot read Silvermoon configuration blob ${config.object}`);
+  }
+  return parseConfigSource({
+    absolutePath,
+    root: gitRoot,
+    source: source.toString("utf8"),
+  });
+}