silvermoon 0.3.0 → 0.4.0

package/src/cli.js

@@ -1,377 +0,0 @@
-import { readFileSync } from "node:fs";
-import {
-  Command,
-  CommanderError,
-  InvalidArgumentError,
-  Option,
-} from "commander";
-
-import {
-  canonicalizeLanguageTag,
-  canonicalizeOutputLanguage,
-} from "./language.js";
-import { normalizeIdeaQuery } from "./idea-query.js";
-import { listIdeas } from "./list-ideas.js";
-import { checkRepository } from "./index.js";
-import { createIdea } from "./create-idea.js";
-import { renderResponse } from "./response.js";
-import { traceAsync, 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";
-const AUDIENCES = ["human", "agent"];
-
-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", "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)",
-      normalizeTraceFileName,
-    )
-    .option("-r, --root <path>", "repository root", process.cwd());
-}
-
-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;
-    },
-  );
-}
-
-function contentLanguageArgument(value) {
-  try {
-    return canonicalizeLanguageTag(value);
-  } catch (caught) {
-    throw new InvalidArgumentError(caught.message);
-  }
-}
-
-function outputLanguageArgument(value) {
-  try {
-    return canonicalizeOutputLanguage(value);
-  } catch (caught) {
-    throw new InvalidArgumentError(caught.message);
-  }
-}
-
-function collectOption(value, previous = []) {
-  return [...previous, value];
-}
-
-export function createProgram(io = console, runtime = {}) {
-  const program = new Command();
-  program
-    .name("silvermoon")
-    .description("Derive and validate repository-owned idea state.")
-    .version(VERSION, "-v, --version", "display the installed version")
-    .addHelpCommand(false)
-    .showHelpAfterError("(run with --help for usage)")
-    .showSuggestionAfterError()
-    .configureHelp({ sortOptions: true, sortSubcommands: true })
-    .configureOutput({
-      outputError: (value, output) => output(value),
-      writeErr: (value) => write(io.error, value),
-      writeOut: (value) => write(io.log, value),
-    })
-    .exitOverride()
-    .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
-  $ silvermoon check
-  $ silvermoon check --language en-US
-  $ silvermoon check --worktree
-  $ silvermoon check --staged
-  $ silvermoon check --commit HEAD
-  $ silvermoon check --remote`);
-
-  addCommonOptions(
-    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)",
-        collectOption,
-      )
-      .option("--all", "include all five lifecycle states")
-      .option("--query <text>", "match ID, alias, or title literally")
-      .option(
-        "--created-since <timestamp>",
-        "include ideas created at or after an RFC 3339 timestamp",
-      )
-      .option(
-        "--created-before <timestamp>",
-        "include ideas created before an RFC 3339 timestamp",
-      )
-      .option("--sort <order>", "sort by creation time: newest or oldest")
-      .option("--limit <count>", "return at most this positive number of ideas"),
-  ).action(async (options) => {
-    const query = normalizeIdeaQuery({
-      all: options.all,
-      createdBefore: options.createdBefore,
-      createdSince: options.createdSince,
-      limit: options.limit,
-      query: options.query,
-      sort: options.sort,
-      states: options.state,
-    });
-    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,
-      },
-      execute: () => listIdeas({
-        ...query,
-        language: options.language,
-        root: options.root,
-      }),
-    }, io, runtime);
-    program.setOptionValue(
-      "resultCode",
-      report.observation.state === "ideas-listed" ? 0 : 1,
-    );
-  });
-
-  addCommonOptions(
-    program
-      .command("whats-next [idea]")
-      .description("observe project, repository, and idea readiness")
-      .option(
-        "--language <tag>",
-        "use a built-in output language (en, en-US, zh, or zh-CN) for this invocation",
-        outputLanguageArgument,
-      ),
-  ).action(async (idea, options) => {
-    const report = await runCommand({
-      name: "command.whats-next",
-      options,
-      attributes: {
-        command: "whats-next",
-        outputLanguage: options.language ?? null,
-      },
-      execute: () => whatsNext({
-        idea,
-        language: options.language,
-        root: options.root,
-      }),
-    }, io, runtime);
-    program.setOptionValue("resultCode", 0);
-  });
-
-  addCommonOptions(
-    program
-      .command("create-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 runCommand({
-      name: "command.create-idea",
-      options,
-      attributes: {
-        command: "create-idea",
-        contentLanguage: options.language ?? null,
-      },
-      execute: () => createIdea({
-        language: options.language,
-        root: options.root,
-      }),
-    }, io, runtime);
-    program.setOptionValue("resultCode", 0);
-  });
-
-  addCommonOptions(
-    program
-      .command("check")
-      .description("validate Silvermoon configuration and idea state")
-      .option(
-        "--language <tag>",
-        "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"]))
-      .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 staged, unstaged, and untracked changes").conflicts(["remote", "commit", "staged"])),
-  ).action(async (options) => {
-    const report = await runCommand({
-      name: "command.check",
-      options,
-      attributes: {
-        command: "check",
-        outputLanguage: options.language ?? null,
-      },
-      execute: () => checkRepository({
-        commit: options.commit,
-        language: options.language,
-        remote: options.remote,
-        root: options.root,
-        staged: options.staged,
-        worktree: options.worktree,
-      }),
-    }, io, runtime);
-    program.setOptionValue(
-      "resultCode",
-      report.observation.state === "project-ready" ? 0 : 1,
-    );
-  });
-
-  return program;
-}
-
-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) {
-    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;
-}

package/src/config.js

@@ -1,253 +0,0 @@
-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";
-import { parseStrictYaml, stringifyCanonicalYaml } from "./yaml.js";
-
-export const DEFAULT_CONFIG_NAME = CONFIG_PATH;
-
-const CONFIG_KEYS = [
-  "version",
-  "primaryRepository",
-  "primaryBranch",
-  "preferredLanguage",
-];
-const DEFAULT_FILESYSTEM = { lstat, readFile };
-
-function configDiagnostic(code, path, message, remediation) {
-  return { code, level: "error", path, message, remediation };
-}
-
-async function regularRepositoryFile(root, filesystem) {
-  const metadataRoot = resolve(root, METADATA_ROOT);
-  const absolutePath = resolve(root, CONFIG_PATH);
-  try {
-    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 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 filesystem.readFile(absolutePath, "utf8"),
-    };
-  } catch (error) {
-    const missing = error.code === "ENOENT";
-    return {
-      absolutePath,
-      diagnostic: configDiagnostic(
-        missing ? "config.missing" : "config.invalid-file",
-        CONFIG_PATH,
-        missing
-          ? `Missing Silvermoon configuration: ${CONFIG_PATH}`
-          : `Cannot read Silvermoon configuration: ${error.message}`,
-        missing
-          ? `Create ${CONFIG_PATH}.`
-          : `Replace ${METADATA_ROOT} and ${CONFIG_PATH} with repository-owned regular paths.`,
-      ),
-    };
-  }
-}
-
-export function validPrimaryBranch(_root, value) {
-  return validBranchName(value);
-}
-
-export function serializeConfig(config) {
-  const canonical = {
-    version: config.version,
-    primaryRepository: config.primaryRepository,
-    primaryBranch: config.primaryBranch,
-  };
-  if (config.preferredLanguage !== undefined) {
-    canonical.preferredLanguage = config.preferredLanguage;
-  }
-  return stringifyCanonicalYaml(canonical);
-}
-
-function parseConfigSource({ absolutePath, root, source }) {
-  const normalizedSource = source.replaceAll("\r\n", "\n");
-  let value;
-  try {
-    value = parseStrictYaml(normalizedSource);
-  } catch (error) {
-    return {
-      config: null,
-      configPath: loaded.absolutePath,
-      diagnostics: [configDiagnostic(
-        "config.invalid-yaml",
-        CONFIG_PATH,
-        `Cannot parse Silvermoon configuration: ${error.message}`,
-        `Use the strict YAML contract in ${CONFIG_PATH}.`,
-      )],
-    };
-  }
-
-  if (value === null || Array.isArray(value) || typeof value !== "object") {
-    return {
-      config: null,
-      configPath: loaded.absolutePath,
-      diagnostics: [configDiagnostic(
-        "config.invalid-type",
-        CONFIG_PATH,
-        "The Silvermoon configuration must be a YAML mapping.",
-        `Replace ${CONFIG_PATH} with the documented mapping.`,
-      )],
-    };
-  }
-
-  const diagnostics = [];
-  for (const key of Object.keys(value).sort()) {
-    if (!CONFIG_KEYS.includes(key)) {
-      diagnostics.push(configDiagnostic(
-        "config.unknown-key",
-        `${CONFIG_PATH}#${key}`,
-        `Unknown Silvermoon configuration key: ${key}`,
-        `Remove ${key}.`,
-      ));
-    }
-  }
-  for (const [key, code] of [
-    ["version", "config.missing-version"],
-    ["primaryRepository", "config.missing-primary-repository"],
-    ["primaryBranch", "config.missing-primary-branch"],
-  ]) {
-    if (!Object.hasOwn(value, key)) {
-      diagnostics.push(configDiagnostic(
-        code,
-        `${CONFIG_PATH}#${key}`,
-        `Missing required key: ${key}`,
-        `Add ${key} to ${CONFIG_PATH}.`,
-      ));
-    }
-  }
-  if (Object.hasOwn(value, "version") && value.version !== 1) {
-    diagnostics.push(configDiagnostic(
-      "config.unsupported-version",
-      `${CONFIG_PATH}#version`,
-      `Unsupported Silvermoon version: ${String(value.version)}`,
-      "Use version: 1.",
-    ));
-  }
-  if (
-    Object.hasOwn(value, "primaryRepository") &&
-    !validRepository(value.primaryRepository)
-  ) {
-    diagnostics.push(configDiagnostic(
-      "config.invalid-primary-repository",
-      `${CONFIG_PATH}#primaryRepository`,
-      "primaryRepository must be a canonical credential-free HTTPS repository URL.",
-      "Use a canonical HTTPS repository URL without credentials, query, fragment, or trailing slash.",
-    ));
-  }
-  if (
-    Object.hasOwn(value, "primaryBranch") &&
-    !validPrimaryBranch(root, value.primaryBranch)
-  ) {
-    diagnostics.push(configDiagnostic(
-      "config.invalid-primary-branch",
-      `${CONFIG_PATH}#primaryBranch`,
-      "primaryBranch must be a valid short Git branch name.",
-      "Use a branch such as main without refs/ or remote prefixes.",
-    ));
-  }
-  if (
-    Object.hasOwn(value, "preferredLanguage") &&
-    !isCanonicalLanguageTag(value.preferredLanguage)
-  ) {
-    diagnostics.push(configDiagnostic(
-      "config.invalid-preferred-language",
-      `${CONFIG_PATH}#preferredLanguage`,
-      "preferredLanguage must be a canonical BCP 47 language tag.",
-      "Use a canonical tag such as en or zh-CN.",
-    ));
-  }
-  if (diagnostics.length === 0 && serializeConfig(value) !== normalizedSource) {
-    diagnostics.push(configDiagnostic(
-      "config.noncanonical",
-      CONFIG_PATH,
-      "The Silvermoon configuration is valid but not canonical.",
-      "Rewrite properties in version, primaryRepository, primaryBranch, preferredLanguage order with LF endings.",
-    ));
-  }
-
-  return {
-    config: diagnostics.length === 0 ? value : null,
-    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"),
-  });
-}