silvermoon 0.0.1

package/src/idea-layout.js

@@ -0,0 +1,439 @@
+import { lstat, readFile, readdir } from "node:fs/promises";
+import { relative, resolve } from "node:path";
+
+import { deriveIdeaState, isValidUlid, parseIdeaStatus } from "./ideas.js";
+import { gitObjectIdLength, runGit, worktreePathTree } from "./git.js";
+import { IDEAS_ROOT, ideaPaths } from "./layout.js";
+
+const REVISION_BINDINGS = {
+  approvedRevision: "idealRevision",
+  implementationAcceptedRevision: "implementationRevision",
+  deploymentAcceptedRevision: "deploymentRevision",
+};
+
+function displayPath(root, path) {
+  return relative(root, path).replaceAll("\\", "/");
+}
+
+function error(code, path, message, remediation) {
+  return { code, level: "error", path, message, remediation };
+}
+
+async function metadata(path) {
+  try {
+    return await lstat(path);
+  } catch (caught) {
+    if (caught.code === "ENOENT") return null;
+    throw caught;
+  }
+}
+
+function validateRevisionObjects(root, statusPath, status, diagnostics) {
+  for (const key of Object.keys(REVISION_BINDINGS)) {
+    if (!status[key]) continue;
+    const type = runGit(root, ["cat-file", "-t", status[key]]);
+    if (!type.ok || type.stdout !== "tree") {
+      diagnostics.push(error(
+        "idea.revision.invalid-object",
+        `${statusPath}#${key}`,
+        `${key} must resolve to a Git tree object: ${status[key]}`,
+        "Use the current corresponding world tree object ID from Git.",
+      ));
+    }
+  }
+}
+
+function validateRevisionHistory(root, commit, idea, diagnostics) {
+  for (const [statusKey, revisionKey] of Object.entries(REVISION_BINDINGS)) {
+    const revision = idea.status[statusKey];
+    if (!revision) continue;
+    const history = runGit(root, [
+      "log",
+      "--reverse",
+      "--format=%H",
+      "-S",
+      `${statusKey}: ${revision}`,
+      commit,
+      "--",
+      idea.statusPath,
+    ]);
+    const evidenceCommit = history.ok
+      ? history.stdout.split(/\r?\n/).filter(Boolean)[0]
+      : null;
+    if (!evidenceCommit) {
+      const shallow = runGit(root, ["rev-parse", "--is-shallow-repository"]);
+      diagnostics.push(error(
+        shallow.ok && shallow.stdout === "true"
+          ? "history.incomplete"
+          : "idea.revision.history-missing",
+        `${idea.statusPath}#${statusKey}`,
+        `Primary history does not prove when ${statusKey} recorded ${revision}.`,
+        "Fetch complete primary history or repair the decision through a forward commit.",
+      ));
+      continue;
+    }
+    const tree = runGit(root, ["rev-parse", `${evidenceCommit}:${idea.worlds[revisionKey].path}`]);
+    if (!tree.ok || tree.stdout !== revision) {
+      diagnostics.push(error(
+        "idea.revision.history-mismatch",
+        `${idea.statusPath}#${statusKey}`,
+        `${statusKey} was not bound to its world tree in commit ${evidenceCommit}.`,
+        "Record the decision only for the corresponding world tree in the same candidate commit.",
+      ));
+    }
+  }
+}
+
+function validateCandidateRevisions(root, baseRevision, idea, diagnostics, objectIdLength) {
+  let previous = {};
+  if (baseRevision) {
+    const previousSource = runGit(root, ["show", `${baseRevision}:${idea.statusPath}`]);
+    if (previousSource.ok) {
+      try {
+        previous = parseIdeaStatus(previousSource.stdout + "\n", { objectIdLength });
+      } catch {
+        previous = {};
+      }
+    }
+  }
+  for (const [statusKey, revisionKey] of Object.entries(REVISION_BINDINGS)) {
+    if (
+      idea.status[statusKey] === previous[statusKey] ||
+      idea.status[statusKey] === undefined
+    ) continue;
+    const expected = idea.revisions[revisionKey];
+    if (idea.status[statusKey] !== expected) {
+      diagnostics.push(error(
+        "idea.revision.candidate-mismatch",
+        `${idea.statusPath}#${statusKey}`,
+        `${statusKey} must equal the corresponding world tree in the same candidate snapshot.`,
+        `Use ${expected} for ${revisionKey} or omit the stale mutation.`,
+      ));
+    }
+  }
+}
+
+async function requireDirectory(root, path, diagnostics) {
+  const absolute = resolve(root, path);
+  const value = await metadata(absolute);
+  if (!value || !value.isDirectory() || value.isSymbolicLink()) {
+    diagnostics.push(error(
+      "idea.world.invalid-directory",
+      path,
+      `Required world path must be a repository-owned regular directory: ${path}`,
+      `Create ${path} as a regular directory without symlinks.`,
+    ));
+    return false;
+  }
+  return true;
+}
+
+async function requireDocument(root, path, diagnostics) {
+  const absolute = resolve(root, path);
+  const value = await metadata(absolute);
+  if (!value || !value.isFile() || value.isSymbolicLink()) {
+    diagnostics.push(error(
+      "idea.world.missing-document",
+      path,
+      `Required world entry must be a repository-owned regular file: ${path}`,
+      `Create ${path} as a regular file without symlinks.`,
+    ));
+    return false;
+  }
+  return true;
+}
+
+async function requireLedger(root, path, diagnostics) {
+  const value = await metadata(resolve(root, path));
+  if (!value) {
+    diagnostics.push(error(
+      "idea.ledger.missing-file",
+      path,
+      `Required idea ledger does not exist: ${path}`,
+      `Create ${path} as a repository-owned regular file.`,
+    ));
+    return false;
+  }
+  if (!value.isFile() || value.isSymbolicLink()) {
+    diagnostics.push(error(
+      "idea.ledger.invalid-file",
+      path,
+      `Required idea ledger must be a repository-owned regular file: ${path}`,
+      `Replace ${path} with a regular file.`,
+    ));
+    return false;
+  }
+  return true;
+}
+
+async function rejectSymlinks(root, path, diagnostics) {
+  const absolute = resolve(root, path);
+  for (const entry of await readdir(absolute, { withFileTypes: true })) {
+    const entryPath = `${path}/${entry.name}`;
+    const value = await lstat(resolve(root, entryPath));
+    if (value.isSymbolicLink()) {
+      diagnostics.push(error(
+        "idea.world.symlink",
+        entryPath,
+        `World content must not use symlinks: ${entryPath}`,
+        "Replace the symlink with repository-owned regular content.",
+      ));
+      continue;
+    }
+    if (value.isDirectory()) await rejectSymlinks(root, entryPath, diagnostics);
+  }
+}
+
+function resolveTree({ gitRoot, root, snapshotTree }, path) {
+  if (snapshotTree) {
+    const resolved = runGit(gitRoot, ["rev-parse", `${snapshotTree}:${path}`]);
+    if (!resolved.ok) throw new Error(resolved.stderr || `Cannot resolve ${path}`);
+    return resolved.stdout;
+  }
+  return worktreePathTree(root, path);
+}
+
+export async function inspectIdeaLayout({
+  baseRevision,
+  config: _config,
+  historyCommit,
+  root,
+  gitRoot = root,
+  snapshotTree,
+  validateCandidate = false,
+}) {
+  const diagnostics = [];
+  const ideasRoot = resolve(root, IDEAS_ROOT);
+  const ideasRootMetadata = await metadata(ideasRoot);
+  if (!ideasRootMetadata) {
+    return {
+      diagnostics: [error(
+        "layout.ideas.missing",
+        IDEAS_ROOT,
+        `Silvermoon ideas directory does not exist: ${IDEAS_ROOT}`,
+        `Create ${IDEAS_ROOT} as a repository-owned directory.`,
+      )],
+      ideas: [],
+    };
+  }
+  if (!ideasRootMetadata.isDirectory() || ideasRootMetadata.isSymbolicLink()) {
+    return {
+      diagnostics: [error(
+        "layout.ideas.invalid",
+        IDEAS_ROOT,
+        "The Silvermoon ideas path must be a repository-owned regular directory.",
+        `Replace ${IDEAS_ROOT} with a regular directory.`,
+      )],
+      ideas: [],
+    };
+  }
+
+  let objectIdLength;
+  try {
+    objectIdLength = gitObjectIdLength(gitRoot);
+  } catch (caught) {
+    return {
+      diagnostics: [error(
+        "git.object-format.unavailable",
+        IDEAS_ROOT,
+        caught.message,
+        "Run Silvermoon inside a Git repository with a supported object format.",
+      )],
+      ideas: [],
+    };
+  }
+
+  const aliases = new Map();
+  const ideas = [];
+  const caseNames = new Map();
+  for (const entry of await readdir(ideasRoot, { withFileTypes: true })) {
+    const folderPath = resolve(ideasRoot, entry.name);
+    const folderMetadata = await lstat(folderPath);
+    const relativePath = displayPath(root, folderPath);
+    const folded = entry.name.toUpperCase();
+    const existingCase = caseNames.get(folded);
+    if (existingCase && existingCase !== entry.name) {
+      diagnostics.push(error(
+        "idea.id.case-collision",
+        relativePath,
+        `Idea identities collide by case: ${existingCase} and ${entry.name}.`,
+        "Keep exactly one canonical uppercase ULID identity.",
+      ));
+    } else {
+      caseNames.set(folded, entry.name);
+    }
+    if (!isValidUlid(entry.name)) {
+      diagnostics.push(error(
+        "idea.id.invalid",
+        relativePath,
+        `Idea folders must use canonical ULID identities: ${entry.name}`,
+        "Rename the folder to one canonical uppercase ULID.",
+      ));
+      continue;
+    }
+    if (!folderMetadata.isDirectory() || folderMetadata.isSymbolicLink()) {
+      diagnostics.push(error(
+        "idea.folder.invalid",
+        relativePath,
+        "Idea must be a repository-owned regular directory.",
+        "Replace it with a regular directory.",
+      ));
+      continue;
+    }
+
+    const paths = ideaPaths(entry.name);
+    for (const child of await readdir(folderPath, { withFileTypes: true })) {
+      if (
+        child.name === "status.yaml" ||
+        child.name === "ledger.md" ||
+        child.name === "outer"
+      ) continue;
+      diagnostics.push(error(
+        child.name.toLowerCase().includes("status")
+          ? "idea.status.unexpected-file"
+          : "idea.entry.unexpected",
+        `${paths.ideaPath}/${child.name}`,
+        `Unexpected entry at the idea root: ${child.name}`,
+        "Keep only status.yaml, ledger.md, and outer/ at the idea root; put supporting files in their world.",
+      ));
+    }
+    await requireLedger(root, paths.ledgerPath, diagnostics);
+    const requiredDirectories = [
+      paths.outerPath,
+      paths.innerPath,
+      paths.idealPath,
+    ];
+    const requiredDocuments = [
+      paths.deploymentDocumentPath,
+      paths.implementationDocumentPath,
+      paths.ideaDocumentPath,
+    ];
+    const validDirectories = (await Promise.all(
+      requiredDirectories.map((path) => requireDirectory(root, path, diagnostics)),
+    )).every(Boolean);
+    const validDocuments = (await Promise.all(
+      requiredDocuments.map((path) => requireDocument(root, path, diagnostics)),
+    )).every(Boolean);
+    if (validDirectories) await rejectSymlinks(root, paths.outerPath, diagnostics);
+
+    const statusMetadata = await metadata(resolve(root, paths.statusPath));
+    if (!statusMetadata || !statusMetadata.isFile() || statusMetadata.isSymbolicLink()) {
+      diagnostics.push(error(
+        "idea.status.invalid-file",
+        paths.statusPath,
+        "Idea status must be a repository-owned regular file named status.yaml.",
+        `Create ${paths.statusPath} as canonical YAML.`,
+      ));
+      continue;
+    }
+
+    let status;
+    try {
+      status = parseIdeaStatus(
+        await readFile(resolve(root, paths.statusPath), "utf8"),
+        { objectIdLength },
+      );
+    } catch (caught) {
+      diagnostics.push(error(
+        "idea.status.invalid",
+        paths.statusPath,
+        caught.message,
+        "Rewrite status.yaml in canonical form.",
+      ));
+      continue;
+    }
+    if (status.id !== entry.name) {
+      diagnostics.push(error(
+        "idea.status.id-mismatch",
+        `${paths.statusPath}#id`,
+        `Status id ${status.id} does not match ${entry.name}.`,
+        "Use the same canonical ULID in the folder and status id.",
+      ));
+    }
+    if (status.alias !== undefined) {
+      const aliasOwner = aliases.get(status.alias);
+      if (aliasOwner) {
+        diagnostics.push(error(
+          "idea.alias.duplicate",
+          `${paths.statusPath}#alias`,
+          `Alias ${status.alias} is shared by ${aliasOwner} and ${entry.name}.`,
+          "Assign a unique exact case-sensitive alias.",
+        ));
+      } else {
+        aliases.set(status.alias, entry.name);
+      }
+    }
+    if (
+      !validDirectories ||
+      !validDocuments ||
+      diagnostics.some(({ code, path }) =>
+        code === "idea.world.symlink" && path.startsWith(`${paths.outerPath}/`)
+      )
+    ) continue;
+
+    let revisions;
+    try {
+      revisions = {
+        idealRevision: resolveTree({ gitRoot, root, snapshotTree }, paths.idealPath),
+        implementationRevision: resolveTree(
+          { gitRoot, root, snapshotTree },
+          paths.innerPath,
+        ),
+        deploymentRevision: resolveTree(
+          { gitRoot, root, snapshotTree },
+          paths.outerPath,
+        ),
+      };
+    } catch (caught) {
+      diagnostics.push(error(
+        "idea.revision.unavailable",
+        paths.ideaPath,
+        caught.message,
+        "Ensure every world can be represented as a Git tree.",
+      ));
+      continue;
+    }
+
+    validateRevisionObjects(gitRoot, paths.statusPath, status, diagnostics);
+    const worlds = {
+      idealRevision: {
+        name: "Ideal World",
+        displayName: "道心",
+        path: paths.idealPath,
+        documentPath: paths.ideaDocumentPath,
+      },
+      implementationRevision: {
+        name: "Inner World",
+        displayName: "内景",
+        path: paths.innerPath,
+        documentPath: paths.implementationDocumentPath,
+      },
+      deploymentRevision: {
+        name: "Outer World",
+        displayName: "现世",
+        path: paths.outerPath,
+        documentPath: paths.deploymentDocumentPath,
+      },
+    };
+    const idea = {
+      id: entry.name,
+      path: folderPath,
+      relativePath: paths.ideaPath,
+      revisions,
+      ...revisions,
+      state: deriveIdeaState(revisions, status),
+      status,
+      statusPath: paths.statusPath,
+      ledgerPath: paths.ledgerPath,
+      worlds,
+    };
+    if (status.alias !== undefined) idea.alias = status.alias;
+    if (validateCandidate) {
+      validateCandidateRevisions(gitRoot, baseRevision, idea, diagnostics, objectIdLength);
+    }
+    if (historyCommit) validateRevisionHistory(gitRoot, historyCommit, idea, diagnostics);
+    ideas.push(idea);
+  }
+
+  return { diagnostics, ideas };
+}

package/src/idea-templates.js

@@ -0,0 +1,109 @@
+export const IDEA_TEMPLATE = `# Idea
+
+## Intent
+
+<!-- State the desired outcome in one or two sentences. -->
+
+## Context
+
+<!-- Describe the current problem, situation, or opportunity. -->
+
+## Desired outcome
+
+<!-- Describe the externally meaningful state that should become true. -->
+
+## Scope
+
+### In scope
+
+<!-- Describe what this idea includes. -->
+
+### Out of scope
+
+<!-- Describe adjacent work this idea intentionally excludes. -->
+
+## Constraints
+
+<!-- Record material product, repository, compatibility, or operational constraints. -->
+
+## Open questions
+
+<!-- Record unresolved decisions. Remove this section when none remain. -->
+`;
+
+export const IMPLEMENTATION_TEMPLATE = `# Implementation
+
+## Steps
+
+<!--
+Give every step a stable I-Sxx identifier and a level-three heading.
+Describe what will change, its boundaries, and important design details.
+Do not use task-list checkboxes in this document.
+-->
+
+### I-S01: Step title
+
+<!-- Describe this implementation step. -->
+
+## Acceptance criteria
+
+<!--
+Give every criterion a stable I-ACxx identifier and a level-three heading.
+Describe both the observable outcome and the method that proves it.
+Do not create a separate validation section or use task-list checkboxes.
+-->
+
+### I-AC01: Criterion title
+
+<!-- Describe the required outcome and how an Agent can prove it. -->
+`;
+
+export const DEPLOYMENT_TEMPLATE = `# Deployment
+
+## Steps
+
+<!--
+Give every step a stable D-Sxx identifier and a level-three heading.
+Describe deployment or external-world verification work.
+Do not use task-list checkboxes in this document.
+-->
+
+### D-S01: Step title
+
+<!-- Describe this deployment or external-verification step. -->
+
+## Acceptance criteria
+
+<!--
+Give every criterion a stable D-ACxx identifier and a level-three heading.
+Describe both the observable external outcome and the method that proves it.
+Do not create a separate validation section or use task-list checkboxes.
+-->
+
+### D-AC01: Criterion title
+
+<!-- Describe the required external outcome and how an Agent can prove it. -->
+`;
+
+export const LEDGER_TEMPLATE = `# Ledger
+
+## Implementation
+
+### Steps
+
+- [ ] **I-S01:** Step title
+
+### Acceptance criteria
+
+- [ ] **I-AC01:** Criterion title
+
+## Deployment
+
+### Steps
+
+- [ ] **D-S01:** Step title
+
+### Acceptance criteria
+
+- [ ] **D-AC01:** Criterion title
+`;

package/src/ideas.js

@@ -0,0 +1,132 @@
+import { parseStrictYaml, stringifyCanonicalYaml } from "./yaml.js";
+
+export const IDEA_STATES = [
+  "preparing",
+  "implementing",
+  "deploying",
+  "completed",
+  "abandoned",
+];
+
+const ULID = /^[0-7][0-9A-HJKMNP-TV-Z]{25}$/;
+const OBJECT_ID = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
+const CONTROL_CHARACTER = /[\u0000-\u001f\u007f-\u009f]/u;
+const STATUS_KEYS = new Set([
+  "version",
+  "id",
+  "alias",
+  "abandoned",
+  "approvedRevision",
+  "implementationAcceptedRevision",
+  "deploymentAcceptedRevision",
+]);
+const REVISION_KEYS = [
+  "approvedRevision",
+  "implementationAcceptedRevision",
+  "deploymentAcceptedRevision",
+];
+
+function ideaStatusError(message) {
+  return new Error(`Invalid idea status: ${message}`);
+}
+
+function isMapping(value) {
+  return value !== null && !Array.isArray(value) && typeof value === "object";
+}
+
+function isValidAlias(value) {
+  return (
+    typeof value === "string" &&
+    value.length > 0 &&
+    value.trim() === value &&
+    [...value].length <= 120 &&
+    !CONTROL_CHARACTER.test(value)
+  );
+}
+
+export function isValidUlid(value) {
+  return typeof value === "string" && ULID.test(value);
+}
+
+export function validateIdeaStatus(value, { objectIdLength } = {}) {
+  if (!isMapping(value)) throw ideaStatusError("document must be a mapping");
+  for (const key of Object.keys(value)) {
+    if (!STATUS_KEYS.has(key)) throw ideaStatusError(`unknown field: ${key}`);
+  }
+  for (const key of ["version", "id"]) {
+    if (!Object.hasOwn(value, key)) throw ideaStatusError(`missing ${key}`);
+  }
+  if (value.version !== 1) throw ideaStatusError("version must be 1");
+  if (!isValidUlid(value.id)) throw ideaStatusError("id must be a canonical ULID");
+  if (Object.hasOwn(value, "alias") && !isValidAlias(value.alias)) {
+    throw ideaStatusError("alias must be 1 to 120 trimmed characters without controls");
+  }
+  if (Object.hasOwn(value, "abandoned") && value.abandoned !== true) {
+    throw ideaStatusError("abandoned must be omitted or true");
+  }
+  if (
+    objectIdLength !== undefined &&
+    (!Number.isInteger(objectIdLength) || objectIdLength <= 0)
+  ) {
+    throw ideaStatusError("objectIdLength must be a positive integer");
+  }
+  for (const key of REVISION_KEYS) {
+    if (!Object.hasOwn(value, key)) continue;
+    if (
+      typeof value[key] !== "string" ||
+      !OBJECT_ID.test(value[key]) ||
+      (objectIdLength !== undefined && value[key].length !== objectIdLength)
+    ) {
+      throw ideaStatusError(`${key} must be a lowercase hexadecimal Git object ID`);
+    }
+  }
+  return value;
+}
+
+export function serializeIdeaStatus(value, options) {
+  validateIdeaStatus(value, options);
+  const canonical = {
+    version: 1,
+    id: value.id,
+  };
+  if (Object.hasOwn(value, "alias")) canonical.alias = value.alias;
+  if (value.abandoned === true) canonical.abandoned = true;
+  for (const key of REVISION_KEYS) {
+    if (Object.hasOwn(value, key)) canonical[key] = value[key];
+  }
+  return stringifyCanonicalYaml(canonical);
+}
+
+export function parseIdeaStatus(source, options) {
+  const normalizedSource = source.replaceAll("\r\n", "\n");
+  let value;
+  try {
+    value = parseStrictYaml(normalizedSource);
+  } catch (error) {
+    throw ideaStatusError(error.message);
+  }
+  validateIdeaStatus(value, options);
+  if (serializeIdeaStatus(value, options) !== normalizedSource) {
+    throw ideaStatusError("status is not canonical");
+  }
+  return value;
+}
+
+export function deriveIdeaState(revisions, status) {
+  if (revisions === null || Array.isArray(revisions) || typeof revisions !== "object") {
+    throw ideaStatusError("revisions must be a mapping");
+  }
+  for (const key of ["idealRevision", "implementationRevision", "deploymentRevision"]) {
+    if (typeof revisions[key] !== "string" || !OBJECT_ID.test(revisions[key])) {
+      throw ideaStatusError(`${key} must be a lowercase hexadecimal Git object ID`);
+    }
+  }
+  validateIdeaStatus(status);
+  if (status.abandoned) return "abandoned";
+  if (status.approvedRevision !== revisions.idealRevision) return "preparing";
+  if (
+    status.implementationAcceptedRevision !== revisions.implementationRevision
+  ) return "implementing";
+  if (status.deploymentAcceptedRevision !== revisions.deploymentRevision) return "deploying";
+  return "completed";
+}