silvermoon 0.1.3 → 0.2.0-rc.1

package/src/idea-query.js

@@ -0,0 +1,230 @@
+import { fromMarkdown } from "mdast-util-from-markdown";
+
+import {
+  ACTIVE_IDEA_STATES,
+  IDEA_STATES,
+  isValidUlid,
+} from "./ideas.js";
+
+const QUERY_STATES = new Set([...IDEA_STATES, "active"]);
+const SORTS = new Set(["newest", "oldest"]);
+const RFC3339 =
+  /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.(\d+))?(Z|[+-](\d{2}):(\d{2}))$/;
+const CROCKFORD_BASE32 = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+
+function usageError(message) {
+  const error = new Error(message);
+  error.exitCode = 2;
+  return error;
+}
+
+function normalizeStates(states, all) {
+  if (all !== undefined && typeof all !== "boolean") {
+    throw usageError("all must be a boolean");
+  }
+  if (states !== undefined && all === true) {
+    throw usageError("state and all are mutually exclusive");
+  }
+  if (states === undefined) {
+    return all === true ? [...IDEA_STATES] : [...ACTIVE_IDEA_STATES];
+  }
+  const requested = Array.isArray(states) ? states : [states];
+  if (requested.length === 0) {
+    throw usageError("state must not be empty");
+  }
+  const selected = new Set();
+  for (const state of requested) {
+    if (typeof state !== "string" || !QUERY_STATES.has(state)) {
+      throw usageError(
+        `state must be one of active, ${IDEA_STATES.join(", ")}; received ${JSON.stringify(state)}`,
+      );
+    }
+    for (const expanded of state === "active" ? ACTIVE_IDEA_STATES : [state]) {
+      selected.add(expanded);
+    }
+  }
+  return IDEA_STATES.filter((state) => selected.has(state));
+}
+
+function normalizeQueryText(query) {
+  if (query === undefined || query === null) return null;
+  if (typeof query !== "string" || query.trim().length === 0) {
+    throw usageError("query must be a non-empty string");
+  }
+  return query.trim();
+}
+
+function normalizeTimestamp(value, name) {
+  if (value === undefined || value === null) return null;
+  if (typeof value !== "string") {
+    throw usageError(`${name} must be an RFC 3339 timestamp`);
+  }
+  const match = RFC3339.exec(value);
+  if (!match) throw usageError(`${name} must be an RFC 3339 timestamp with a timezone`);
+  const [, year, month, day, hour, minute, second, , zone, offsetHour, offsetMinute] =
+    match;
+  const numeric = [year, month, day, hour, minute, second].map(Number);
+  if (
+    numeric[1] < 1
+    || numeric[1] > 12
+    || numeric[2] < 1
+    || numeric[2] > 31
+    || numeric[3] > 23
+    || numeric[4] > 59
+    || numeric[5] > 59
+    || (
+      zone !== "Z"
+      && (Number(offsetHour) > 23 || Number(offsetMinute) > 59)
+    )
+  ) {
+    throw usageError(`${name} must be a valid RFC 3339 timestamp`);
+  }
+  const calendar = new Date(0);
+  calendar.setUTCFullYear(numeric[0], numeric[1] - 1, numeric[2]);
+  calendar.setUTCHours(0, 0, 0, 0);
+  if (
+    calendar.getUTCFullYear() !== numeric[0]
+    || calendar.getUTCMonth() !== numeric[1] - 1
+    || calendar.getUTCDate() !== numeric[2]
+  ) {
+    throw usageError(`${name} must be a valid RFC 3339 timestamp`);
+  }
+  const timestamp = Date.parse(value);
+  if (!Number.isFinite(timestamp)) {
+    throw usageError(`${name} must be a valid RFC 3339 timestamp`);
+  }
+  return new Date(timestamp).toISOString();
+}
+
+function normalizeSort(sort) {
+  const value = sort ?? "newest";
+  if (typeof value !== "string" || !SORTS.has(value)) {
+    throw usageError("sort must be newest or oldest");
+  }
+  return value;
+}
+
+function normalizeLimit(limit) {
+  if (limit === undefined || limit === null) return null;
+  const value = typeof limit === "number"
+    ? limit
+    : typeof limit === "string" && /^[1-9]\d*$/.test(limit)
+      ? Number(limit)
+      : Number.NaN;
+  if (!Number.isSafeInteger(value) || value <= 0) {
+    throw usageError("limit must be a positive integer");
+  }
+  return value;
+}
+
+export function normalizeIdeaQuery({
+  all,
+  createdBefore,
+  createdSince,
+  limit,
+  query,
+  sort,
+  states,
+} = {}) {
+  const normalized = {
+    states: normalizeStates(states, all),
+    query: normalizeQueryText(query),
+    createdSince: normalizeTimestamp(createdSince, "createdSince"),
+    createdBefore: normalizeTimestamp(createdBefore, "createdBefore"),
+    sort: normalizeSort(sort),
+    limit: normalizeLimit(limit),
+  };
+  if (
+    normalized.createdSince !== null
+    && normalized.createdBefore !== null
+    && Date.parse(normalized.createdSince) >= Date.parse(normalized.createdBefore)
+  ) {
+    throw usageError("createdSince must be earlier than createdBefore");
+  }
+  return normalized;
+}
+
+export function ideaCreatedAt(id) {
+  if (!isValidUlid(id)) throw new Error(`Cannot decode invalid idea ULID: ${id}`);
+  let timestamp = 0;
+  for (const character of id.slice(0, 10)) {
+    timestamp = timestamp * 32 + CROCKFORD_BASE32.indexOf(character);
+  }
+  return new Date(timestamp).toISOString();
+}
+
+function markdownText(node) {
+  if (node.type === "text" || node.type === "inlineCode") return node.value;
+  if (node.type === "image") return node.alt ?? "";
+  return (node.children ?? []).map(markdownText).join("");
+}
+
+export function extractIdeaTitle(source) {
+  if (typeof source !== "string") {
+    throw new TypeError("Idea document source must be a string");
+  }
+  const heading = fromMarkdown(source).children.find(
+    (node) => node.type === "heading" && node.depth === 1,
+  );
+  if (!heading) return undefined;
+  const title = markdownText(heading).replaceAll(/\s+/g, " ").trim();
+  return title.length === 0 ? undefined : title;
+}
+
+export function ideaInventoryItem(idea, title) {
+  const item = {
+    id: idea.id,
+    state: idea.state,
+    createdAt: ideaCreatedAt(idea.id),
+  };
+  if (idea.alias !== undefined) item.alias = idea.alias;
+  if (title !== undefined) item.title = title;
+  return item;
+}
+
+function compareText(left, right) {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+
+export function queryIdeaInventory(items, input) {
+  const query = normalizeIdeaQuery(input);
+  const states = new Set(query.states);
+  const needle = query.query?.toLowerCase();
+  const createdSince = query.createdSince === null
+    ? null
+    : Date.parse(query.createdSince);
+  const createdBefore = query.createdBefore === null
+    ? null
+    : Date.parse(query.createdBefore);
+  const filtered = items.filter((idea) => {
+    if (!states.has(idea.state)) return false;
+    if (
+      needle !== undefined
+      && ![idea.id, idea.alias, idea.title]
+        .filter((value) => value !== undefined)
+        .some((value) => value.toLowerCase().includes(needle))
+    ) {
+      return false;
+    }
+    const createdAt = Date.parse(idea.createdAt);
+    if (createdSince !== null && createdAt < createdSince) return false;
+    return createdBefore === null || createdAt < createdBefore;
+  });
+  const direction = query.sort === "newest" ? -1 : 1;
+  filtered.sort((left, right) => direction * compareText(left.id, right.id));
+  const counts = Object.fromEntries(IDEA_STATES.map((state) => [state, 0]));
+  for (const idea of filtered) counts[idea.state] += 1;
+  const ideas = query.limit === null
+    ? filtered
+    : filtered.slice(0, query.limit);
+  return {
+    query,
+    summary: {
+      matched: filtered.length,
+      returned: ideas.length,
+      truncated: ideas.length < filtered.length,
+      counts,
+    },
+    ideas,
+  };
+}

package/src/ideas.js

@@ -8,6 +8,7 @@ export const IDEA_STATES = [
   "completed",
   "abandoned",
 ];
+export const ACTIVE_IDEA_STATES = IDEA_STATES.slice(0, 3);
 
 const ULID = /^[0-7][0-9A-HJKMNP-TV-Z]{25}$/;
 const OBJECT_ID = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;

package/src/index.js

@@ -4,6 +4,7 @@ import {
   diagnosticProblem,
 } from "./dialogue.js";
 import { loadConfig } from "./config.js";
+import { createCommandRun } from "./domain.js";
 import {
   fetchPrimary,
   indexSnapshot,
@@ -32,21 +33,22 @@ function targetArgument({ commit, remote, staged, worktree }) {
 }
 
 function failureReport({
-  intention,
+  runtime,
   outputLanguage,
   problem,
   root,
   version,
 }) {
-  return {
-    intention,
-    observation: unavailableObservation({
+  return runtime.complete(
+    unavailableObservation({
       outputLanguage,
       problem,
       root,
       version,
     }),
-  };
+    {},
+    { factType: "validation.failed" },
+  );
 }
 
 async function inspectTree({
@@ -71,8 +73,12 @@ async function inspectTree({
   );
 }
 
-function finishCheck(intention, observed) {
-  return { intention, observation: observed.observation };
+function finishCheck(runtime, observed) {
+  return runtime.complete(
+    observed.observation,
+    {},
+    { factType: "validation.completed" },
+  );
 }
 
 export async function checkRepository({
@@ -106,6 +112,7 @@ export async function checkRepository({
       language: canonicalLanguage ?? null,
     },
   };
+  const runtime = createCommandRun(intention);
   const repository = runGit(requestedRoot, ["rev-parse", "--show-toplevel"]);
   if (!repository.ok) {
     const observed = await observeSnapshot({
@@ -119,7 +126,7 @@ export async function checkRepository({
           ? { type: "remote", commit: null }
           : { type: target.type },
     });
-    return finishCheck(intention, observed);
+    return finishCheck(runtime, observed);
   }
   const repositoryRoot = resolve(repository.stdout);
 
@@ -129,7 +136,7 @@ export async function checkRepository({
       head = resolveCommit(repositoryRoot, "HEAD");
     } catch (caught) {
       return failureReport({
-        intention,
+        runtime,
         outputLanguage: fallbackOutputLanguage,
         problem: {
           type: "head-unavailable",
@@ -148,7 +155,7 @@ export async function checkRepository({
       );
     } catch (caught) {
       return failureReport({
-        intention,
+        runtime,
         outputLanguage: fallbackOutputLanguage,
         problem: {
           type: "snapshot-inspection-failed",
@@ -159,9 +166,7 @@ export async function checkRepository({
       });
     }
     if (!bootstrap.config) {
-      return {
-        intention,
-        observation: {
+      return runtime.complete({
           state: "project-setup-required",
           observedThrough: "version",
           root: repositoryRoot,
@@ -170,23 +175,35 @@ export async function checkRepository({
           problems: bootstrap.diagnostics.map((diagnostic) =>
             diagnosticProblem(diagnostic, fallbackOutputLanguage)
           ),
-        },
-      };
+        });
     }
 
-    let primary;
-    try {
-      primary = fetchPrimary(repositoryRoot, bootstrap.config);
-    } catch (caught) {
-      const summary = sanitizeGitMessage(caught.message);
+    const fetched = await runtime.performAction(
+      {
+        type: "fetch-primary",
+        repository: bootstrap.config.primaryRepository,
+        branch: bootstrap.config.primaryBranch,
+      },
+      () => ({
+        commit: fetchPrimary(repositoryRoot, bootstrap.config),
+      }),
+      (caught) => ({
+        problem: {
+          type: "primary-fetch-failed",
+          summary: sanitizeGitMessage(caught.message),
+        },
+      }),
+    );
+    if (fetched.status === "failure") {
       return failureReport({
-        intention,
+        runtime,
         outputLanguage: fallbackOutputLanguage,
         root: repositoryRoot,
         version: { type: "remote", commit: null },
-        problem: { type: "primary-fetch-failed", summary },
+        problem: fetched.problem,
       });
     }
+    const primary = fetched.result.commit;
     try {
       const observed = await withTemporaryWorktree(
         repositoryRoot,
@@ -202,10 +219,10 @@ export async function checkRepository({
           version: { type: "remote", commit: primary },
         }),
       );
-      return finishCheck(intention, observed);
+      return finishCheck(runtime, observed);
     } catch (caught) {
       return failureReport({
-        intention,
+        runtime,
         outputLanguage: fallbackOutputLanguage,
         problem: {
           type: "snapshot-inspection-failed",
@@ -224,7 +241,7 @@ export async function checkRepository({
       resolvedCommit = resolveCommit(repositoryRoot, revision);
     } catch (caught) {
       return failureReport({
-        intention,
+        runtime,
         outputLanguage: fallbackOutputLanguage,
         problem: {
           type: "commit-unavailable",
@@ -249,10 +266,10 @@ export async function checkRepository({
           version: { type: "commit", commit: resolvedCommit },
         }),
       );
-      return finishCheck(intention, observed);
+      return finishCheck(runtime, observed);
     } catch (caught) {
       return failureReport({
-        intention,
+        runtime,
         outputLanguage: fallbackOutputLanguage,
         problem: {
           type: "snapshot-inspection-failed",
@@ -275,10 +292,10 @@ export async function checkRepository({
         userHome,
         version: { type: "staged" },
       });
-      return finishCheck(intention, observed);
+      return finishCheck(runtime, observed);
     } catch (caught) {
       return failureReport({
-        intention,
+        runtime,
         outputLanguage: fallbackOutputLanguage,
         problem: {
           type: "snapshot-inspection-failed",
@@ -300,10 +317,10 @@ export async function checkRepository({
       userHome,
       version: { type: "worktree" },
     });
-    return finishCheck(intention, observed);
+    return finishCheck(runtime, observed);
   } catch (caught) {
     return failureReport({
-      intention,
+      runtime,
       outputLanguage: fallbackOutputLanguage,
       problem: {
         type: "snapshot-inspection-failed",
@@ -316,15 +333,43 @@ export async function checkRepository({
 }
 
 export {
+  ACTIVE_IDEA_STATES,
   deriveIdeaState,
+  IDEA_STATES,
   isValidUlid,
   parseIdeaStatus,
   serializeIdeaStatus,
   validateIdeaStatus,
 } from "./ideas.js";
+export {
+  extractIdeaTitle,
+  ideaCreatedAt,
+  ideaInventoryItem,
+  normalizeIdeaQuery,
+  queryIdeaInventory,
+} from "./idea-query.js";
+export { listIdeas } from "./list-ideas.js";
 export { createIdea, generateUlid } from "./create-idea.js";
 export {
   inspectAdoption,
   SILVERMOON_VERSION,
 } from "./adoption.js";
+export {
+  CommandRun,
+  DOMAIN_MESSAGE_SCHEMA_VERSION,
+  DomainInvariantError,
+  driveCommand,
+  initialInternalObservation,
+  projectActions,
+  projectIntention,
+  projectPublicObservation,
+  projectReport,
+  reduceObservation,
+  replayObservation,
+} from "./domain.js";
+export {
+  renderResponse,
+  respond,
+} from "./response.js";
+export { TRACE_SCHEMA_VERSION } from "./trace.js";
 export { whatsNext } from "./whatsnext.js";

package/src/language.js

@@ -3,6 +3,14 @@ export const OUTPUT_LANGUAGES = Object.freeze(["en-US", "zh-CN"]);
 
 const OUTPUT_LANGUAGE_SET = new Set(OUTPUT_LANGUAGES);
 
+export function isChinese(language) {
+  return language?.toLowerCase().startsWith("zh") ?? false;
+}
+
+export function localize(language, english, chinese) {
+  return isChinese(language) ? chinese : english;
+}
+
 export function canonicalizeLanguageTag(value) {
   if (typeof value !== "string" || value.length === 0 || value.trim() !== value) {
     throw new Error("language tag must be a non-empty trimmed string");

package/src/list-ideas.js

@@ -0,0 +1,133 @@
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+
+import { createCommandRun } from "./domain.js";
+import {
+  extractIdeaTitle,
+  ideaInventoryItem,
+  normalizeIdeaQuery,
+  queryIdeaInventory,
+} from "./idea-query.js";
+import { localize } from "./language.js";
+import { observeSnapshot } from "./observation.js";
+import { traceAsync } from "./trace.js";
+
+async function readInventoryItem(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 },
+    );
+  }
+}
+
+function metadataFailureObservation(observed, caught) {
+  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 `silvermoon list-ideas`.",
+        "修复报告的 idea document 后，重新运行 `silvermoon list-ideas`。",
+      ),
+    },
+  };
+}
+
+export async function listIdeas({
+  all,
+  createdBefore,
+  createdSince,
+  limit,
+  query,
+  root = process.cwd(),
+  sort,
+  states,
+  userHome,
+} = {}) {
+  const normalizedQuery = normalizeIdeaQuery({
+    all,
+    createdBefore,
+    createdSince,
+    limit,
+    query,
+    sort,
+    states,
+  });
+  const intention = {
+    command: "list-ideas",
+    args: normalizedQuery,
+  };
+  const runtime = createCommandRun(intention);
+  const observed = await observeSnapshot({
+    root,
+    userHome,
+    version: { type: "worktree" },
+  });
+  if (!observed.projectReady) {
+    return runtime.complete(
+      observed.observation,
+      { nextSteps: observed.findings.map(({ instruction }) => instruction) },
+      { factType: "ideas.inventory-unavailable" },
+    );
+  }
+
+  let items;
+  try {
+    items = await traceAsync(
+      "ideas.inventory-metadata",
+      { ideaCount: observed.layout.ideas.length },
+      () => Promise.all(
+        observed.layout.ideas.map((idea) =>
+          readInventoryItem(observed.observation.root, idea)
+        ),
+      ),
+    );
+  } catch (caught) {
+    const failure = metadataFailureObservation(observed, caught);
+    return runtime.complete(
+      failure.observation,
+      failure.responseContext,
+      { factType: "ideas.inventory-unavailable" },
+    );
+  }
+
+  const inventory = queryIdeaInventory(items, normalizedQuery);
+  const {
+    configuration,
+    outputLanguage,
+    root: repositoryRoot,
+    version,
+  } = observed.observation;
+  return runtime.complete({
+    state: "ideas-listed",
+    root: repositoryRoot,
+    version,
+    configuration,
+    outputLanguage,
+    problems: [],
+    summary: inventory.summary,
+    ideas: inventory.ideas,
+  }, {}, { factType: "ideas.listed" });
+}