silvermoon 0.3.0-rc.2 → 0.4.0

package/src/idea-metadata.js

@@ -1,48 +0,0 @@
-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-query.js

@@ -1,230 +0,0 @@
-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/idea-templates.js

@@ -1,242 +0,0 @@
-export const IDEA_TEMPLATE = `# Replace with a specific title for this 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
-
-### Implementation steps
-
-- [ ] **I-S01:** Step title
-
-### Implementation acceptance criteria
-
-- [ ] **I-AC01:** Criterion title
-
-## Deployment
-
-### Deployment steps
-
-- [ ] **D-S01:** Step title
-
-### Deployment acceptance criteria
-
-- [ ] **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/ideas.js

@@ -1,142 +0,0 @@
-import { parseStrictYaml, stringifyCanonicalYaml } from "./yaml.js";
-import { isCanonicalLanguageTag } from "./language.js";
-
-export const IDEA_STATES = [
-  "preparing",
-  "implementing",
-  "deploying",
-  "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})$/;
-const CONTROL_CHARACTER = /[\u0000-\u001f\u007f-\u009f]/u;
-const STATUS_KEYS = new Set([
-  "version",
-  "id",
-  "alias",
-  "language",
-  "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, "language") &&
-    !isCanonicalLanguageTag(value.language)
-  ) {
-    throw ideaStatusError("language must be a canonical BCP 47 language tag");
-  }
-  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 (Object.hasOwn(value, "language")) canonical.language = value.language;
-  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";
-}