silvermoon 0.0.1

package/src/adoption.js

@@ -0,0 +1,313 @@
+import { createHash } from "node:crypto";
+import {
+  lstat,
+  readFile,
+  readdir,
+  realpath,
+} from "node:fs/promises";
+import { dirname, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { loadConfig } from "./config.js";
+import { runGit } from "./git.js";
+
+const packageRoot = fileURLToPath(new URL("..", import.meta.url));
+const packageJson = JSON.parse(await readFile(resolve(packageRoot, "package.json"), "utf8"));
+export const SILVERMOON_VERSION = packageJson.version;
+export const REPOSITORY_SKILL_PATHS = [
+  ".agents/skills/silvermoon",
+  ".github/skills/silvermoon",
+];
+
+async function metadata(path) {
+  try {
+    return await lstat(path);
+  } catch (error) {
+    if (error.code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+async function jsonFile(path) {
+  try {
+    return JSON.parse(await readFile(path, "utf8"));
+  } catch (error) {
+    if (error.code === "ENOENT") return null;
+    return { __invalid: error.message };
+  }
+}
+
+async function directoryDigest(root) {
+  const hash = createHash("sha256");
+  async function visit(directory) {
+    const entries = (await readdir(directory, { withFileTypes: true }))
+      .sort((left, right) => left.name.localeCompare(right.name));
+    for (const entry of entries) {
+      const path = resolve(directory, entry.name);
+      if (entry.isDirectory()) {
+        await visit(path);
+      } else if (entry.isFile()) {
+        hash.update(relative(root, path).split(sep).join("/"));
+        hash.update("\0");
+        hash.update(await readFile(path));
+        hash.update("\0");
+      } else {
+        throw new Error(`Skill contains a non-regular path: ${path}`);
+      }
+    }
+  }
+  await visit(root);
+  return hash.digest("hex");
+}
+
+async function skillDigest(path) {
+  const entry = await lstat(path);
+  if (entry.isFile()) {
+    const pointer = (await readFile(path, "utf8")).trim();
+    if (!pointer) throw new Error(`Skill pointer is empty: ${path}`);
+    return directoryDigest(resolve(dirname(path), pointer));
+  }
+  if (!entry.isDirectory() && !entry.isSymbolicLink()) {
+    throw new Error(`Skill discovery path is not a directory: ${path}`);
+  }
+  return directoryDigest(path);
+}
+
+function command(executable, args, description) {
+  return { kind: "command", executable, args, description };
+}
+
+function manual(path, description) {
+  return { kind: "manual", path, description };
+}
+
+function requirement(id, title, status, blocking, dependencies, observed, remediation = null) {
+  return { id, title, status, blocking, dependencies, observed, remediation };
+}
+
+async function detectPackageManager(root, manifest) {
+  for (const [file, name] of [
+    ["pnpm-lock.yaml", "pnpm"],
+    ["yarn.lock", "yarn"],
+    ["bun.lock", "bun"],
+    ["bun.lockb", "bun"],
+    ["package-lock.json", "npm"],
+    ["npm-shrinkwrap.json", "npm"],
+  ]) {
+    if (await metadata(resolve(root, file))) return name;
+  }
+  const declared = manifest?.packageManager?.split("@")[0];
+  return ["pnpm", "npm", "yarn", "bun"].includes(declared) ? declared : "npm";
+}
+
+export async function detectExecutionSource({
+  root,
+  runtimeRoot = packageRoot,
+} = {}) {
+  const runtime = await realpath(runtimeRoot);
+  let repository;
+  try {
+    repository = await realpath(root);
+  } catch {
+    repository = resolve(root);
+  }
+  let local = null;
+  try {
+    local = await realpath(resolve(repository, "node_modules", "silvermoon"));
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+  }
+  const normalizedRuntime = runtime.toLowerCase();
+  const normalizedRoot = repository.toLowerCase();
+  const normalizedLocal = local?.toLowerCase() ?? null;
+  let kind = "unknown";
+  if (normalizedRuntime === normalizedRoot && await metadata(resolve(runtime, ".git"))) {
+    kind = "source-checkout";
+  } else if (normalizedRuntime === normalizedLocal) {
+    kind = "project-local";
+  } else if (/(^|[\\/])_npx([\\/]|$)/i.test(runtime)) {
+    kind = "temporary";
+  } else if (normalizedRuntime.includes(`${sep}node_modules${sep}`) && !normalizedRuntime.startsWith(normalizedRoot + sep)) {
+    kind = "global";
+  }
+  return { kind, packageRoot: runtime, version: SILVERMOON_VERSION };
+}
+
+function installCommand(manager, version) {
+  if (manager === "pnpm") {
+    return command("pnpm", ["add", "--save-dev", "--save-exact", `silvermoon@${version}`], `Declare Silvermoon ${version} and install it locally.`);
+  }
+  if (manager === "yarn") {
+    return command("yarn", ["add", "--dev", "--exact", `silvermoon@${version}`], `Declare Silvermoon ${version} and install it locally.`);
+  }
+  if (manager === "bun") {
+    return command("bun", ["add", "--dev", "--exact", `silvermoon@${version}`], `Declare Silvermoon ${version} and install it locally.`);
+  }
+  return command("npm", ["install", "--save-dev", "--save-exact", `silvermoon@${version}`], `Declare Silvermoon ${version} and install it locally.`);
+}
+
+export async function inspectAdoption({ root, selector } = {}) {
+  const repositoryRoot = resolve(root ?? process.cwd());
+  const source = await detectExecutionSource({ root: repositoryRoot });
+  const manifest = await jsonFile(resolve(repositoryRoot, "package.json"));
+  const manager = await detectPackageManager(repositoryRoot, manifest);
+  const sourceCheckout = source.kind === "source-checkout";
+  const desiredVersion = source.version;
+  const declared = manifest?.devDependencies?.silvermoon ?? manifest?.dependencies?.silvermoon ?? null;
+  const installedManifest = sourceCheckout
+    ? packageJson
+    : await jsonFile(resolve(repositoryRoot, "node_modules", "silvermoon", "package.json"));
+  const installedVersion = installedManifest?.version ?? null;
+  const requirements = [];
+
+  const git = runGit(repositoryRoot, ["rev-parse", "--show-toplevel"]);
+  requirements.push(requirement(
+    "repository.git",
+    "Git repository",
+    git.ok ? "satisfied" : "missing",
+    true,
+    [],
+    { root: git.ok ? git.stdout : null },
+    git.ok ? null : command("git", ["init"], "Initialize this directory as a Git repository."),
+  ));
+
+  requirements.push(requirement(
+    "runtime.execution-source",
+    "Authoritative execution source",
+    ["source-checkout", "project-local", "temporary"].includes(source.kind)
+      ? "satisfied"
+      : source.kind === "global" ? "conflicting" : "unknown",
+    !sourceCheckout && !["project-local", "temporary"].includes(source.kind),
+    ["global", "unknown"].includes(source.kind)
+      ? ["repository.git", "package.installed"]
+      : ["repository.git"],
+    source,
+    ["global", "unknown"].includes(source.kind)
+      ? command("npx", ["--no-install", "silvermoon", "whats-next", ...(selector ? [selector] : []), "--json"], "Re-run with the repository-local CLI.")
+      : null,
+  ));
+
+  requirements.push(requirement(
+    "package.manifest",
+    "Exact project dependency",
+    sourceCheckout
+      ? "inapplicable"
+      : declared === desiredVersion ? "satisfied" : declared ? "mismatched" : "missing",
+    !sourceCheckout,
+    ["repository.git"],
+    { packageManager: manager, declared, expected: sourceCheckout ? null : desiredVersion },
+    sourceCheckout ? null : installCommand(manager, desiredVersion),
+  ));
+
+  const installStatus = sourceCheckout
+    ? "satisfied"
+    : installedVersion === desiredVersion ? "satisfied" : installedVersion ? "mismatched" : "missing";
+  requirements.push(requirement(
+    "package.installed",
+    "Installed project CLI",
+    installStatus,
+    true,
+    sourceCheckout ? ["runtime.execution-source"] : ["package.manifest"],
+    { installedVersion, expected: desiredVersion },
+    installStatus === "satisfied"
+      ? null
+      : command(manager, ["install"], `Install the lockfile-resolved Silvermoon ${desiredVersion} dependency.`),
+  ));
+
+  const packagedSkill = resolve(packageRoot, "skills", "silvermoon");
+  let skillStatus = "blocked";
+  const skillObserved = { paths: [], expectedDigest: null };
+  if (installStatus === "satisfied") {
+    const expectedDigest = await directoryDigest(packagedSkill);
+    skillObserved.expectedDigest = expectedDigest;
+    for (const path of REPOSITORY_SKILL_PATHS) {
+      try {
+        skillObserved.paths.push({
+          path,
+          digest: await skillDigest(resolve(repositoryRoot, ...path.split("/"))),
+        });
+      } catch (error) {
+        if (error.code !== "ENOENT") {
+          skillObserved.paths.push({ path, error: error.message });
+        }
+      }
+    }
+    skillStatus = skillObserved.paths.length === 0
+      ? "missing"
+      : skillObserved.paths.every(({ digest }) => digest === expectedDigest)
+        ? "satisfied"
+        : skillObserved.paths.some(({ error }) => error)
+          ? "conflicting"
+          : "mismatched";
+  }
+  requirements.push(requirement(
+    "skill.repository-local",
+    "Repository-local canonical skill",
+    skillStatus,
+    true,
+    ["package.installed"],
+    skillObserved,
+    skillStatus === "satisfied" || skillStatus === "blocked"
+      ? null
+      : command(
+        "npx",
+        [
+          "skills",
+          "add",
+          "./node_modules/silvermoon/skills",
+          "--skill",
+          "silvermoon",
+          "--agent",
+          "github-copilot",
+          "--yes",
+          "--copy",
+        ],
+        "Register the installed package's canonical skill through the supported npx skills interface.",
+      ),
+  ));
+
+  const loadedConfig = await loadConfig({ root: repositoryRoot });
+  const missingConfig = loadedConfig.diagnostics.some(({ code }) => code === "config.missing");
+  const configStatus = loadedConfig.config
+    ? "satisfied"
+    : missingConfig ? "missing" : "conflicting";
+  requirements.push(requirement(
+    "repository.configuration",
+    "Silvermoon repository configuration",
+    configStatus,
+    true,
+    ["repository.git"],
+    { path: ".silvermoon/config.yaml", diagnostics: loadedConfig.diagnostics },
+    configStatus === "satisfied"
+      ? null
+      : missingConfig
+        ? manual(".silvermoon/config.yaml", "Create the documented configuration through ordinary reviewed file editing.")
+        : manual(".silvermoon/config.yaml", "Repair the reported configuration conflicts without overwriting unrelated content."),
+  ));
+
+  const blockingFindings = requirements.filter(({ blocking, status }) =>
+    blocking && !["satisfied", "inapplicable"].includes(status)
+  );
+  const recommended = requirements.find(({ remediation, status, dependencies }) =>
+    remediation
+    && !["satisfied", "inapplicable"].includes(status)
+    && dependencies.every((id) => {
+      const dependency = requirements.find((item) => item.id === id);
+      return dependency && ["satisfied", "inapplicable"].includes(dependency.status);
+    })
+  );
+  return {
+    status: blockingFindings.length === 0 ? "ready" : "blocked",
+    executionSource: source,
+    packageManager: manager,
+    desiredVersion,
+    requirements,
+    findings: requirements.filter(({ status }) => !["satisfied", "inapplicable"].includes(status)),
+    recommendedAction: recommended?.remediation ?? null,
+    recheck: command(
+      "npx",
+      ["--no-install", "silvermoon", "whats-next", ...(selector ? [selector] : []), "--json"],
+      "Re-run the complete diagnosis after an observable change.",
+    ),
+  };
+}

package/src/cli.js

@@ -0,0 +1,197 @@
+import { readFileSync } from "node:fs";
+import { Command, CommanderError, Option } from "commander";
+
+import { checkRepository } from "./index.js";
+import { createIdea } from "./create-idea.js";
+import { whatsNext } from "./whatsnext.js";
+
+const { version: VERSION } = JSON.parse(
+  readFileSync(new URL("../package.json", import.meta.url), "utf8"),
+);
+
+function write(method, value) {
+  const text = value.replace(/\n$/, "");
+  if (text) method(text);
+}
+
+function addCommonOptions(command) {
+  return command
+    .option("--json", "emit the complete machine-readable report")
+    .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}`);
+    io.log(`  runtime  ${result.onboarding.executionSource.kind} ${result.onboarding.desiredVersion}`);
+    for (const item of result.onboarding.requirements) {
+      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}`);
+  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}`);
+  }
+}
+
+function renderCreateIdea(result, io) {
+  if (!result.createdIdea) {
+    renderWhatsNext(result, io);
+    return;
+  }
+  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;
+  }
+  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) {
+  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 whats-next
+  $ silvermoon whats-next <idea>
+  $ silvermoon whats-next <idea> --json
+  $ silvermoon create-idea
+  $ silvermoon check
+  $ silvermoon check --worktree
+  $ silvermoon check --staged
+  $ silvermoon check --commit HEAD
+  $ silvermoon check --remote`);
+
+  addCommonOptions(
+    program
+      .command("whats-next [idea]")
+      .description("fetch primary and render the highest-priority next action"),
+  ).action(async (idea, options) => {
+    const report = await whatsNext({ enforceOnboarding: true, idea, root: options.root });
+    render(report, options.json, io);
+    program.setOptionValue("resultCode", report.ok ? 0 : 1);
+  });
+
+  addCommonOptions(
+    program
+      .command("create-idea")
+      .description("create one structured idea scaffold after primary hygiene"),
+  ).action(async (options) => {
+    const report = await createIdea({ root: options.root });
+    render(report, options.json, io);
+    program.setOptionValue("resultCode", report.ok ? 0 : 1);
+  });
+
+  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"]))
+      .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"])),
+  ).action(async (options) => {
+    const report = await checkRepository({
+      commit: options.commit,
+      remote: options.remote,
+      root: options.root,
+      staged: options.staged,
+      worktree: options.worktree,
+    });
+    render(report, options.json, io);
+    program.setOptionValue("resultCode", report.ok ? 0 : 1);
+  });
+
+  return program;
+}
+
+export async function runCli(args, io = console) {
+  const program = createProgram(io);
+  try {
+    await program.parseAsync(args.length === 0 ? ["--help"] : args, { from: "user" });
+  } catch (caught) {
+    if (caught instanceof CommanderError) return caught.exitCode === 0 ? 0 : 2;
+    io.error(`ERROR command.failed: ${caught.message}`);
+    return 1;
+  }
+  return program.getOptionValue("resultCode") ?? 0;
+}

package/src/config.js

@@ -0,0 +1,176 @@
+import { lstat, readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+
+import { CONFIG_PATH, METADATA_ROOT } from "./layout.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",
+];
+
+function configDiagnostic(code, path, message, remediation) {
+  return { code, level: "error", path, message, remediation };
+}
+
+async function regularRepositoryFile(root) {
+  const metadataRoot = resolve(root, METADATA_ROOT);
+  const absolutePath = resolve(root, CONFIG_PATH);
+  try {
+    const directoryMetadata = await 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);
+    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") };
+  } 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) {
+  return stringifyCanonicalYaml({
+    version: config.version,
+    primaryRepository: config.primaryRepository,
+    primaryBranch: config.primaryBranch,
+  });
+}
+
+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");
+  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 (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 order with LF endings.",
+    ));
+  }
+
+  return {
+    config: diagnostics.length === 0 ? value : null,
+    configPath: loaded.absolutePath,
+    diagnostics,
+  };
+}