silvermoon 0.2.2 → 0.3.0-rc.2

package/src/idea-layout.js

@@ -5,6 +5,8 @@ import { deriveIdeaState, isValidUlid, parseIdeaStatus } from "./ideas.js";
 import { inspectTreePaths, worktreeSnapshot } from "./git.js";
 import { IDEAS_ROOT, ideaPaths } from "./layout.js";
 
+const DEFAULT_FILESYSTEM = { lstat, readFile, readdir };
+
 function displayPath(root, path) {
   return relative(root, path).replaceAll("\\", "/");
 }
@@ -13,18 +15,18 @@ function error(code, path, message, remediation) {
   return { code, level: "error", path, message, remediation };
 }
 
-async function metadata(path) {
+async function metadata(path, filesystem) {
   try {
-    return await lstat(path);
+    return await filesystem.lstat(path);
   } catch (caught) {
     if (caught.code === "ENOENT") return null;
     throw caught;
   }
 }
 
-async function requireDirectory(root, path, diagnostics) {
+async function requireDirectory(root, path, diagnostics, filesystem) {
   const absolute = resolve(root, path);
-  const value = await metadata(absolute);
+  const value = await metadata(absolute, filesystem);
   if (!value || !value.isDirectory() || value.isSymbolicLink()) {
     diagnostics.push(error(
       "idea.world.invalid-directory",
@@ -37,9 +39,9 @@ async function requireDirectory(root, path, diagnostics) {
   return true;
 }
 
-async function requireDocument(root, path, diagnostics) {
+async function requireDocument(root, path, diagnostics, filesystem) {
   const absolute = resolve(root, path);
-  const value = await metadata(absolute);
+  const value = await metadata(absolute, filesystem);
   if (!value || !value.isFile() || value.isSymbolicLink()) {
     diagnostics.push(error(
       "idea.world.missing-document",
@@ -52,8 +54,8 @@ async function requireDocument(root, path, diagnostics) {
   return true;
 }
 
-async function requireLedger(root, path, diagnostics) {
-  const value = await metadata(resolve(root, path));
+async function requireLedger(root, path, diagnostics, filesystem) {
+  const value = await metadata(resolve(root, path), filesystem);
   if (!value) {
     diagnostics.push(error(
       "idea.ledger.missing-file",
@@ -75,11 +77,13 @@ async function requireLedger(root, path, diagnostics) {
   return true;
 }
 
-async function rejectSymlinks(root, path, diagnostics) {
+async function rejectSymlinks(root, path, diagnostics, filesystem) {
   const absolute = resolve(root, path);
-  for (const entry of await readdir(absolute, { withFileTypes: true })) {
+  for (
+    const entry of await filesystem.readdir(absolute, { withFileTypes: true })
+  ) {
     const entryPath = `${path}/${entry.name}`;
-    const value = await lstat(resolve(root, entryPath));
+    const value = await filesystem.lstat(resolve(root, entryPath));
     if (value.isSymbolicLink()) {
       diagnostics.push(error(
         "idea.world.symlink",
@@ -89,7 +93,9 @@ async function rejectSymlinks(root, path, diagnostics) {
       ));
       continue;
     }
-    if (value.isDirectory()) await rejectSymlinks(root, entryPath, diagnostics);
+    if (value.isDirectory()) {
+      await rejectSymlinks(root, entryPath, diagnostics, filesystem);
+    }
   }
 }
 
@@ -109,13 +115,14 @@ function requiredTree(objects, path) {
 
 export async function inspectIdeaLayout({
   config: _config,
+  filesystem = DEFAULT_FILESYSTEM,
   root,
   gitRoot = root,
   snapshotTree,
 }) {
   const diagnostics = [];
   const ideasRoot = resolve(root, IDEAS_ROOT);
-  const ideasRootMetadata = await metadata(ideasRoot);
+  const ideasRootMetadata = await metadata(ideasRoot, filesystem);
   if (!ideasRootMetadata) {
     return {
       diagnostics: [error(
@@ -160,7 +167,9 @@ export async function inspectIdeaLayout({
   const aliases = new Map();
   const ideas = [];
   const caseNames = new Map();
-  const entries = (await readdir(ideasRoot, { withFileTypes: true }))
+  const entries = (
+    await filesystem.readdir(ideasRoot, { withFileTypes: true })
+  )
     .sort((left, right) => left.name.localeCompare(right.name));
   const ideaIds = new Set(
     entries.filter((entry) => isValidUlid(entry.name)).map((entry) => entry.name),
@@ -171,7 +180,18 @@ export async function inspectIdeaLayout({
   });
   let worldObjects;
   try {
-    worldObjects = inspectTreePaths(gitRoot, resolvedSnapshotTree, worldPaths);
+    worldObjects = typeof filesystem.snapshotEntry === "function"
+      ? new Map(worldPaths.map((path) => {
+          const entry = filesystem.snapshotEntry(path);
+          return [
+            path,
+            {
+              object: entry?.object ?? null,
+              type: entry?.type ?? "missing",
+            },
+          ];
+        }))
+      : inspectTreePaths(gitRoot, resolvedSnapshotTree, worldPaths);
   } catch (caught) {
     return {
       diagnostics: [error(
@@ -185,7 +205,7 @@ export async function inspectIdeaLayout({
   }
   for (const entry of entries) {
     const folderPath = resolve(ideasRoot, entry.name);
-    const folderMetadata = await lstat(folderPath);
+    const folderMetadata = await filesystem.lstat(folderPath);
     const relativePath = displayPath(root, folderPath);
     const folded = entry.name.toUpperCase();
     const existingCase = caseNames.get(folded);
@@ -219,7 +239,9 @@ export async function inspectIdeaLayout({
     }
 
     const paths = ideaPaths(entry.name);
-    const children = (await readdir(folderPath, { withFileTypes: true }))
+    const children = (
+      await filesystem.readdir(folderPath, { withFileTypes: true })
+    )
       .sort((left, right) => left.name.localeCompare(right.name));
     for (const child of children) {
       if (
@@ -236,7 +258,7 @@ export async function inspectIdeaLayout({
         "Keep only status.yaml, ledger.md, and outer/ at the idea root; put supporting files in their world.",
       ));
     }
-    await requireLedger(root, paths.ledgerPath, diagnostics);
+    await requireLedger(root, paths.ledgerPath, diagnostics, filesystem);
     const requiredDirectories = [
       paths.outerPath,
       paths.innerPath,
@@ -248,14 +270,28 @@ export async function inspectIdeaLayout({
       paths.ideaDocumentPath,
     ];
     const validDirectories = (await Promise.all(
-      requiredDirectories.map((path) => requireDirectory(root, path, diagnostics)),
+      requiredDirectories.map((path) =>
+        requireDirectory(root, path, diagnostics, filesystem)
+      ),
     )).every(Boolean);
     const validDocuments = (await Promise.all(
-      requiredDocuments.map((path) => requireDocument(root, path, diagnostics)),
+      requiredDocuments.map((path) =>
+        requireDocument(root, path, diagnostics, filesystem)
+      ),
     )).every(Boolean);
-    if (validDirectories) await rejectSymlinks(root, paths.outerPath, diagnostics);
+    if (validDirectories) {
+      await rejectSymlinks(
+        root,
+        paths.outerPath,
+        diagnostics,
+        filesystem,
+      );
+    }
 
-    const statusMetadata = await metadata(resolve(root, paths.statusPath));
+    const statusMetadata = await metadata(
+      resolve(root, paths.statusPath),
+      filesystem,
+    );
     if (!statusMetadata || !statusMetadata.isFile() || statusMetadata.isSymbolicLink()) {
       diagnostics.push(error(
         "idea.status.invalid-file",
@@ -269,7 +305,7 @@ export async function inspectIdeaLayout({
     let status;
     try {
       status = parseIdeaStatus(
-        await readFile(resolve(root, paths.statusPath), "utf8"),
+        await filesystem.readFile(resolve(root, paths.statusPath), "utf8"),
         { objectIdLength: repositoryObjectIdLength },
       );
     } catch (caught) {

package/src/idea-metadata.js

@@ -0,0 +1,48 @@
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+
+import { extractIdeaTitle, ideaInventoryItem } from "./idea-query.js";
+import { localize } from "./language.js";
+
+export async function readIdeaInventoryItem(root, idea) {
+  const documentPath = idea.worlds.idealRevision.documentPath;
+  try {
+    const source = await readFile(
+      resolve(root, ...documentPath.split("/")),
+      "utf8",
+    );
+    return ideaInventoryItem(idea, extractIdeaTitle(source));
+  } catch (caught) {
+    throw new Error(
+      `Cannot read idea metadata for ${idea.id} at ${documentPath}: ${caught.message}`,
+      { cause: caught },
+    );
+  }
+}
+
+export function metadataFailureObservation(observed, caught, command) {
+  const { ideas: _ideas, ...base } = observed.observation;
+  const problem = {
+    type: "idea-metadata-unavailable",
+    summary: localize(
+      observed.outputLanguage,
+      caught.message,
+      `无法读取 idea metadata：${caught.message}`,
+    ),
+  };
+  return {
+    observation: {
+      ...base,
+      state: "project-setup-required",
+      observedThrough: "configuration",
+      problems: [problem],
+    },
+    responseContext: {
+      nextSteps: localize(
+        observed.outputLanguage,
+        `Repair the reported idea document and retry \`${command}\`.`,
+        `修复报告的 idea document 后，重新运行 \`${command}\`。`,
+      ),
+    },
+  };
+}

package/src/idea-templates.js

@@ -107,3 +107,136 @@ export const LEDGER_TEMPLATE = `# Ledger
 
 - [ ] **D-AC01:** Criterion title
 `;
+
+const CHINESE_IDEA_TEMPLATE = `# 将标题替换为这个 idea 的具体名称
+
+## 意图
+
+<!-- 用一两句话说明期望结果。 -->
+
+## 背景
+
+<!-- 描述当前问题、情境或机会。 -->
+
+## 期望结果
+
+<!-- 描述应当实现的、对外有意义的状态。 -->
+
+## 范围
+
+### 范围内
+
+<!-- 描述这个 idea 包含的内容。 -->
+
+### 范围外
+
+<!-- 描述这个 idea 有意排除的相邻工作。 -->
+
+## 约束
+
+<!-- 记录重要的产品、仓库、兼容性或操作约束。 -->
+
+## 待解决问题
+
+<!-- 记录尚未解决的决定；没有时删除本节。 -->
+`;
+
+const CHINESE_IMPLEMENTATION_TEMPLATE = `# Implementation
+
+## Steps
+
+<!--
+为每个步骤分配稳定的 I-Sxx 标识符和三级标题。
+说明修改内容、边界和重要设计细节。
+不要在本文档中使用任务列表复选框。
+-->
+
+### I-S01: 步骤标题
+
+<!-- 描述该实施步骤。 -->
+
+## Acceptance criteria
+
+<!--
+为每项标准分配稳定的 I-ACxx 标识符和三级标题。
+同时说明可观察结果及其证明方法。
+不要创建单独的验证章节，也不要使用任务列表复选框。
+-->
+
+### I-AC01: 标准标题
+
+<!-- 描述所需结果以及 Agent 如何证明该结果。 -->
+`;
+
+const CHINESE_DEPLOYMENT_TEMPLATE = `# Deployment
+
+## Steps
+
+<!--
+为每个步骤分配稳定的 D-Sxx 标识符和三级标题。
+描述部署或现实世界验证工作。
+不要在本文档中使用任务列表复选框。
+-->
+
+### D-S01: 步骤标题
+
+<!-- 描述该部署或外部验证步骤。 -->
+
+## Acceptance criteria
+
+<!--
+为每项标准分配稳定的 D-ACxx 标识符和三级标题。
+同时说明可观察的外部结果及其证明方法。
+不要创建单独的验证章节，也不要使用任务列表复选框。
+-->
+
+### D-AC01: 标准标题
+
+<!-- 描述所需外部结果以及 Agent 如何证明该结果。 -->
+`;
+
+const CHINESE_LEDGER_TEMPLATE = `# Ledger
+
+## Implementation
+
+### Implementation steps
+
+- [ ] **I-S01:** 步骤标题
+
+### Implementation acceptance criteria
+
+- [ ] **I-AC01:** 标准标题
+
+## Deployment
+
+### Deployment steps
+
+- [ ] **D-S01:** 步骤标题
+
+### Deployment acceptance criteria
+
+- [ ] **D-AC01:** 标准标题
+`;
+
+export function ideaTemplates(contentLanguage) {
+  const normalized = contentLanguage.toLowerCase();
+  if (normalized === "zh" || normalized.startsWith("zh-")) {
+    return {
+      idea: CHINESE_IDEA_TEMPLATE,
+      implementation: CHINESE_IMPLEMENTATION_TEMPLATE,
+      deployment: CHINESE_DEPLOYMENT_TEMPLATE,
+      ledger: CHINESE_LEDGER_TEMPLATE,
+      localized: true,
+      templateLanguage: "zh-CN",
+    };
+  }
+  const localized = normalized === "en" || normalized.startsWith("en-");
+  return {
+    idea: IDEA_TEMPLATE,
+    implementation: IMPLEMENTATION_TEMPLATE,
+    deployment: DEPLOYMENT_TEMPLATE,
+    ledger: LEDGER_TEMPLATE,
+    localized,
+    templateLanguage: "en-US",
+  };
+}

package/src/index.js

@@ -1,20 +1,20 @@
 import { resolve } from "node:path";
 
+import { REPOSITORY_SKILL_PATH } from "./adoption.js";
 import {
   diagnosticProblem,
 } from "./dialogue.js";
-import { loadConfig } from "./config.js";
+import { loadConfigSnapshot } from "./config.js";
 import { createCommandRun } from "./domain.js";
 import {
   fetchPrimary,
   indexSnapshot,
-  resolveCommit,
+  resolveSnapshot,
   runGit,
   sanitizeGitMessage,
   worktreeSnapshot,
-  withTemporaryTree,
-  withTemporaryWorktree,
 } from "./git.js";
+import { createGitSnapshotFileSystem } from "./git-snapshot.js";
 import {
   canonicalizeOutputLanguage,
   DEFAULT_LANGUAGE,
@@ -23,6 +23,24 @@ import {
   observeSnapshot,
   unavailableObservation,
 } from "./observation.js";
+import {
+  CONFIG_PATH,
+  GUIDANCE_ROOT,
+  IDEAS_ROOT,
+} from "./layout.js";
+
+function preloadCheckBlob({ name }) {
+  return (
+    name === CONFIG_PATH
+    || name === "package.json"
+    || name.startsWith(`${REPOSITORY_SKILL_PATH}/`)
+    || name.startsWith(`${GUIDANCE_ROOT}/`)
+    || (
+      name.startsWith(`${IDEAS_ROOT}/`)
+      && name.endsWith("/status.yaml")
+    )
+  );
+}
 
 function targetArgument({ commit, remote, staged, worktree }) {
   if (remote) return { type: "remote" };
@@ -59,18 +77,23 @@ async function inspectTree({
   userHome,
   version,
 }) {
-  return withTemporaryTree(gitRoot, tree, (contentRoot) =>
-    observeSnapshot({
-      contentRoot,
-      gitRoot,
-      outputLanguage,
-      root,
-      projectOnly: true,
-      snapshotTree: tree,
-      userHome,
-      version,
-    })
-  );
+  const filesystem = createGitSnapshotFileSystem({
+    gitRoot,
+    preload: preloadCheckBlob,
+    root,
+    tree,
+  });
+  return observeSnapshot({
+    contentRoot: root,
+    filesystem,
+    gitRoot,
+    outputLanguage,
+    root,
+    projectOnly: true,
+    snapshotTree: tree,
+    userHome,
+    version,
+  });
 }
 
 function finishCheck(runtime, observed) {
@@ -133,7 +156,7 @@ export async function checkRepository({
   if (remote) {
     let head;
     try {
-      head = resolveCommit(repositoryRoot, "HEAD");
+      head = resolveSnapshot(repositoryRoot, "HEAD");
     } catch (caught) {
       return failureReport({
         runtime,
@@ -148,11 +171,10 @@ export async function checkRepository({
     }
     let bootstrap;
     try {
-      bootstrap = await withTemporaryWorktree(
-        repositoryRoot,
-        head,
-        (contentRoot) => loadConfig({ root: contentRoot }),
-      );
+      bootstrap = await loadConfigSnapshot({
+        gitRoot: repositoryRoot,
+        tree: head.tree,
+      });
     } catch (caught) {
       return failureReport({
         runtime,
@@ -205,20 +227,15 @@ export async function checkRepository({
     }
     const primary = fetched.result.commit;
     try {
-      const observed = await withTemporaryWorktree(
-        repositoryRoot,
-        primary,
-        (contentRoot, tree) => observeSnapshot({
-          contentRoot,
-          gitRoot: repositoryRoot,
-          outputLanguage: canonicalLanguage,
-          root: repositoryRoot,
-          projectOnly: true,
-          snapshotTree: tree,
-          userHome,
-          version: { type: "remote", commit: primary },
-        }),
-      );
+      const snapshot = resolveSnapshot(repositoryRoot, primary);
+      const observed = await inspectTree({
+        gitRoot: repositoryRoot,
+        outputLanguage: canonicalLanguage,
+        root: repositoryRoot,
+        tree: snapshot.tree,
+        userHome,
+        version: { type: "remote", commit: primary },
+      });
       return finishCheck(runtime, observed);
     } catch (caught) {
       return failureReport({
@@ -236,9 +253,9 @@ export async function checkRepository({
 
   if (commit !== undefined || (!staged && !worktree)) {
     const revision = commit ?? "HEAD";
-    let resolvedCommit;
+    let snapshot;
     try {
-      resolvedCommit = resolveCommit(repositoryRoot, revision);
+      snapshot = resolveSnapshot(repositoryRoot, revision);
     } catch (caught) {
       return failureReport({
         runtime,
@@ -252,20 +269,14 @@ export async function checkRepository({
       });
     }
     try {
-      const observed = await withTemporaryWorktree(
-        repositoryRoot,
-        resolvedCommit,
-        (contentRoot, tree) => observeSnapshot({
-          contentRoot,
-          gitRoot: repositoryRoot,
-          outputLanguage: canonicalLanguage,
-          root: repositoryRoot,
-          projectOnly: true,
-          snapshotTree: tree,
-          userHome,
-          version: { type: "commit", commit: resolvedCommit },
-        }),
-      );
+      const observed = await inspectTree({
+        gitRoot: repositoryRoot,
+        outputLanguage: canonicalLanguage,
+        root: repositoryRoot,
+        tree: snapshot.tree,
+        userHome,
+        version: { type: "commit", commit: snapshot.commit },
+      });
       return finishCheck(runtime, observed);
     } catch (caught) {
       return failureReport({
@@ -276,7 +287,7 @@ export async function checkRepository({
           summary: sanitizeGitMessage(caught.message),
         },
         root: repositoryRoot,
-        version: { type: "commit", commit: resolvedCommit },
+        version: { type: "commit", commit: snapshot.commit },
       });
     }
   }

package/src/language.js

@@ -40,6 +40,10 @@ export function canonicalizeOutputLanguage(value) {
     caught.exitCode = 2;
     throw caught;
   }
+  canonical = {
+    en: "en-US",
+    zh: "zh-CN",
+  }[canonical.toLowerCase()] ?? canonical;
   if (!OUTPUT_LANGUAGE_SET.has(canonical)) {
     const error = new Error(
       `unsupported output language: ${canonical}; expected ${OUTPUT_LANGUAGES.join(" or ")}`,