@loviusc/sa-spec 0.1.0

package/src/cli.js

@@ -0,0 +1,362 @@
+const fs = require("fs");
+const path = require("path");
+const { spawnSync } = require("child_process");
+
+const cwd = process.cwd();
+const rootDir = path.resolve(__dirname, "..");
+const templatesDir = path.join(rootDir, "templates");
+
+function main() {
+  const args = process.argv.slice(2);
+  const command = args[0];
+
+  switch (command) {
+    case "init":
+      initProject(args.slice(1));
+      return;
+    case "new":
+      createReqTemplate(args.slice(1));
+      return;
+    case "check":
+      runCheck();
+      return;
+    case "doctor":
+      runDoctor();
+      return;
+    case "status":
+      showStatus();
+      return;
+    case "template":
+      runTemplate(args.slice(1));
+      return;
+    case "help":
+    case "--help":
+    case "-h":
+    case undefined:
+      showHelp();
+      return;
+    default:
+      fail(`Unknown command: ${command}`);
+  }
+}
+
+function initProject(args = []) {
+  const includeRules = args.includes("--full");
+  const results = [
+    ensureGitRepository(),
+    ensureDir("skills"),
+    ensureDir(path.join("skills", "system-analysis")),
+    ensureDir("project"),
+    ensureFileFromTemplate("AGENTS.md", "AGENTS.md"),
+    ensureFileFromTemplate("readme.md", "readme.md"),
+    ensureFileFromTemplate(path.join("skills", "system-analysis", "SKILL.md"), path.join("skills", "system-analysis", "SKILL.md")),
+    ensureFileFromTemplate(path.join("project", "index.md"), path.join("project", "index.md")),
+    ensureFileFromTemplate(path.join("project", "system-spec.md"), path.join("project", "system-spec.md"))
+  ];
+
+  if (includeRules) {
+    results.push(ensureDir("rules"));
+    for (const file of listFilesRecursive(path.join(templatesDir, "rules"))) {
+      const relativePath = path.relative(templatesDir, file);
+      results.push(ensureFileFromTemplate(relativePath, relativePath));
+    }
+  }
+
+  printResultList("init", results);
+}
+
+function ensureGitRepository() {
+  const gitVersion = spawnSync("git", ["--version"], { cwd, encoding: "utf8" });
+  if (gitVersion.error && gitVersion.error.code === "ENOENT") {
+    return {
+      action: "warn",
+      target: "git",
+      message: "Git 未安裝；後續歸檔會使用版本管理，請先安裝 Git。"
+    };
+  }
+
+  if (gitVersion.status !== 0) {
+    return {
+      action: "warn",
+      target: "git",
+      message: "無法確認 Git 是否可用；後續歸檔可能無法使用版本管理。"
+    };
+  }
+
+  const workTree = spawnSync("git", ["rev-parse", "--is-inside-work-tree"], { cwd, encoding: "utf8" });
+  if (workTree.status === 0 && workTree.stdout.trim() === "true") {
+    return { action: "skip", target: "git repository" };
+  }
+
+  const init = spawnSync("git", ["init"], { cwd, encoding: "utf8" });
+  if (init.status !== 0) {
+    process.exitCode = 1;
+    return {
+      action: "warn",
+      target: "git init",
+      message: (init.stderr || init.stdout || "git init 執行失敗。").trim()
+    };
+  }
+
+  return { action: "update", target: ".git" };
+}
+
+function runDoctor() {
+  return checkRequiredPaths("sa-spec doctor");
+}
+
+function checkRequiredPaths(heading) {
+  const requiredPaths = [
+    "AGENTS.md",
+    path.join("skills", "system-analysis", "SKILL.md"),
+    path.join("project", "index.md"),
+    path.join("project", "system-spec.md")
+  ];
+
+  let hasMissing = false;
+  if (heading) {
+    console.log(heading);
+  }
+
+  for (const relativePath of requiredPaths) {
+    const exists = fs.existsSync(path.join(cwd, relativePath));
+    console.log(`${exists ? "OK" : "MISSING"} ${relativePath}`);
+    if (!exists) {
+      hasMissing = true;
+    }
+  }
+
+  if (hasMissing) {
+    process.exitCode = 1;
+  }
+
+  return !hasMissing;
+}
+
+function runCheck() {
+  console.log("sa-spec check");
+  if (!checkRequiredPaths(null)) {
+    return;
+  }
+  console.log("");
+  showStatus(false);
+}
+
+function showStatus(showHeading = true) {
+  if (showHeading) {
+    console.log("sa-spec status");
+  }
+
+  const systemSpecPath = path.join(cwd, "project", "system-spec.md");
+  const indexPath = path.join(cwd, "project", "index.md");
+
+  if (fs.existsSync(systemSpecPath)) {
+    const content = fs.readFileSync(systemSpecPath, "utf8");
+    const match = content.match(/^- 狀態：\s*(.+)$/m);
+    console.log(`系統規格書狀態: ${match ? match[1].trim() : "未標示"}`);
+  } else {
+    console.log("系統規格書狀態: 缺少 project/system-spec.md");
+    process.exitCode = 1;
+  }
+
+  if (!fs.existsSync(indexPath)) {
+    console.log("需求索引: 缺少 project/index.md");
+    process.exitCode = 1;
+    return;
+  }
+
+  const rows = parseIndexRows(fs.readFileSync(indexPath, "utf8"));
+  console.log(`需求總數: ${rows.length}`);
+
+  if (rows.length === 0) {
+    console.log("目前尚無需求。");
+    return;
+  }
+
+  for (const row of rows.slice(-5)) {
+    console.log(`- ${row.id} ${row.title} [${row.status}]`);
+  }
+}
+
+function runTemplate(args) {
+  const type = args[0];
+
+  if (type === "system-spec") {
+    outputTemplate(path.join("project", "system-spec.md"), args.slice(1));
+    return;
+  }
+
+  if (type === "req") {
+    createReqTemplate(args.slice(1), "template req");
+    return;
+  }
+
+  fail("Usage: sa-spec template <system-spec|req> [options]");
+}
+
+function outputTemplate(templatePath, args) {
+  const outputIndex = args.indexOf("--output");
+  const output = outputIndex >= 0 ? args[outputIndex + 1] : null;
+  const content = readTemplate(templatePath);
+
+  if (args.includes("--stdout") || !output) {
+    process.stdout.write(content.endsWith("\n") ? content : `${content}\n`);
+    return;
+  }
+
+  writeFileIfMissing(path.resolve(cwd, output), content);
+  console.log(`Created ${output}`);
+}
+
+function createReqTemplate(args, label = "new") {
+  const id = getOption(args, "--id");
+  const name = getOption(args, "--name");
+
+  if (!id || !name) {
+    fail("Usage: sa-spec template req --id REQ-001 --name login");
+    return;
+  }
+
+  const slug = slugify(name);
+  const reqDir = path.join("project", `${id}-${slug}`);
+  const replacements = { REQ_ID: id, REQ_NAME: name };
+  const results = [
+    ensureDir(reqDir),
+    ensureFileFromTemplate(path.join("project", "req", "srs.md"), path.join(reqDir, "srs.md"), replacements),
+    ensureFileFromTemplate(path.join("project", "req", "uml.puml"), path.join(reqDir, "uml.puml"), replacements),
+    ensureFileFromTemplate(path.join("project", "req", "openapi.yaml"), path.join(reqDir, "openapi.yaml"), replacements),
+    ensureFileFromTemplate(path.join("project", "req", "db-schema.md"), path.join(reqDir, "db-schema.md"), replacements),
+    ensureFileFromTemplate(path.join("project", "req", "handoff.md"), path.join(reqDir, "handoff.md"), replacements),
+    ensureFileFromTemplate(path.join("project", "req", "history.md"), path.join(reqDir, "history.md"), replacements),
+    ensureIndexRow(id, name)
+  ];
+
+  printResultList(label, results);
+}
+
+function ensureIndexRow(id, name) {
+  const indexPath = path.join(cwd, "project", "index.md");
+  if (!fs.existsSync(indexPath)) {
+    return { action: "skip", target: path.join("project", "index.md") };
+  }
+
+  const content = fs.readFileSync(indexPath, "utf8");
+  if (content.includes(`| ${id} |`)) {
+    return { action: "skip", target: path.join("project", "index.md") };
+  }
+
+  const now = formatLocalDateTime(new Date());
+  const row = `| ${id} | ${name} | 待補充 | 待確認 | ${now} | ${now} |`;
+  const nextContent = content.endsWith("\n") ? `${content}${row}\n` : `${content}\n${row}\n`;
+  fs.writeFileSync(indexPath, nextContent, "utf8");
+  return { action: "update", target: path.join("project", "index.md") };
+}
+
+function formatLocalDateTime(date) {
+  const pad = (value) => String(value).padStart(2, "0");
+  return [
+    date.getFullYear(),
+    pad(date.getMonth() + 1),
+    pad(date.getDate())
+  ].join("-") + " " + [
+    pad(date.getHours()),
+    pad(date.getMinutes())
+  ].join(":");
+}
+
+function ensureDir(relativeDir) {
+  const absoluteDir = path.join(cwd, relativeDir);
+  if (fs.existsSync(absoluteDir)) {
+    return { action: "skip", target: relativeDir };
+  }
+
+  fs.mkdirSync(absoluteDir, { recursive: true });
+  return { action: "create", target: relativeDir };
+}
+
+function ensureFileFromTemplate(templateRelativePath, targetRelativePath, replacements = {}) {
+  const targetAbsolutePath = path.join(cwd, targetRelativePath);
+  if (fs.existsSync(targetAbsolutePath)) {
+    return { action: "skip", target: targetRelativePath };
+  }
+
+  const content = applyReplacements(readTemplate(templateRelativePath), replacements);
+  writeFileIfMissing(targetAbsolutePath, content);
+  return { action: "create", target: targetRelativePath };
+}
+
+function writeFileIfMissing(filePath, content) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, content, "utf8");
+}
+
+function readTemplate(relativePath) {
+  return fs.readFileSync(path.join(templatesDir, relativePath), "utf8");
+}
+
+function listFilesRecursive(dir) {
+  return fs
+    .readdirSync(dir, { withFileTypes: true })
+    .flatMap((entry) => {
+      const absolutePath = path.join(dir, entry.name);
+      return entry.isDirectory() ? listFilesRecursive(absolutePath) : [absolutePath];
+    });
+}
+
+function applyReplacements(content, replacements) {
+  return Object.entries(replacements).reduce(
+    (result, [key, value]) => result.split(`{{${key}}}`).join(value),
+    content
+  );
+}
+
+function parseIndexRows(content) {
+  return content
+    .split("\n")
+    .filter((line) => line.startsWith("|") && !line.includes("---") && !line.includes("編號"))
+    .map((line) => line.split("|").map((part) => part.trim()))
+    .filter((parts) => parts.length >= 7)
+    .map((parts) => ({
+      id: parts[1],
+      title: parts[2],
+      status: parts[4]
+    }));
+}
+
+function getOption(args, flag) {
+  const index = args.indexOf(flag);
+  return index >= 0 ? args[index + 1] || null : null;
+}
+
+function slugify(value) {
+  return value
+    .toLowerCase()
+    .trim()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+function printResultList(label, results) {
+  console.log(`sa-spec ${label}`);
+  for (const result of results) {
+    const action = result.action === "create" ? "CREATED" : result.action === "update" ? "UPDATED" : result.action === "warn" ? "WARNING" : "SKIPPED";
+    console.log(`${action} ${result.target}${result.message ? ` - ${result.message}` : ""}`);
+  }
+}
+
+function showHelp() {
+  console.log(`sa-spec
+
+Usage:
+  sa-spec init [--full]
+  sa-spec new --id REQ-001 --name login
+  sa-spec check
+`);
+}
+
+function fail(message) {
+  console.error(message);
+  process.exitCode = 1;
+}
+
+main();

package/templates/AGENTS.md

@@ -0,0 +1,90 @@
+# 專案角色
+
+你是一位資深系統分析協作者，負責把需求想法整理成可確認、可歸檔、可檢查的系統分析文件。
+
+# 核心交付物
+
+每個需求歸檔時固定包含：
+
+- `srs.md`：需求規格。
+- `uml.puml`：UML 圖。
+- `openapi.yaml`：OpenAPI 草稿。
+- `db-schema.md`：DB Schema 草稿。
+- `handoff.md`：給 OpenSpec 或其他 AI 開發工具的開發交接摘要。
+- `history.md`：版本歷程。
+
+# 指令流程
+
+只使用四個指令：
+
+| 指令 | 用途 | 規則 |
+|---|---|---|
+| `spec:init` | 初始化 | 載入並遵守 `AGENTS.md`、`skills/system-analysis/SKILL.md` 與必要規則，確認 `project/` 結構是否存在。 |
+| `spec:propose` | 提出需求 | 使用者提出需求後，先整理需求摘要、目標、初步流程與待確認事項，不歸檔、不修改既有需求。 |
+| `spec:analyze` | 分析與起草 | 先檢查新需求是否與 `project/` 內所有既有需求衝突；無衝突才產出 SRS、UML、OpenAPI、DB Schema 草稿；有衝突則只列出衝突與待釐清問題，待使用者釐清後再次執行 `spec:analyze`。 |
+| `spec:commit` | 確認歸檔 | 只把使用者已確認的版本歸檔到該需求資料夾，更新 `project/index.md`、`project/system-spec.md` 與 `history.md`，並建立本機 Git commit。 |
+
+# 重要限制
+
+- 使用繁體中文，並採用台灣常用語。
+- `spec:init` 必須檢查 Git 狀態：若 Git 未安裝，提醒使用者後續歸檔會使用版本管理但不可中斷初始化；若 Git 已安裝且目前目錄尚未初始化為 Git repository，則自動執行 `git init`；若已是 Git repository，僅回報狀態，不重複初始化。
+- `project/system-spec.md` 由 `sa-spec init` 建立；`spec:analyze` 只能讀取它做衝突檢查，並提出待確認的系統規格更新建議，不得寫入；`spec:commit` 才能依使用者確認後的內容更新 `project/system-spec.md`。
+- 不可自行幻想未確認的業務規則、角色、流程、資料或系統行為。
+- `spec:analyze` 必須先檢查所有既有需求是否衝突。
+- 若發現衝突，不得產出最終文件，不得修改任何需求文件，只能向使用者釐清。
+- 衝突釐清後，流程回到 `spec:analyze`，重新檢查衝突並產出草稿；不可直接進入 `spec:commit`。
+- 任何流程都不得修改其他需求資料夾中的文件，除非使用者明確指定該需求也要變更。
+- `spec:commit` 只能套用已由 `spec:analyze` 產出的、且使用者已確認的無衝突版本。
+- `handoff.md` 只能根據已確認的 SRS、UML、OpenAPI、DB Schema 與限制整理，不得新增未確認的開發假設。
+- 交給 OpenSpec 或其他 AI 開發工具時，必須指定它先閱讀 `handoff.md`，並以 `handoff.md` 作為開發入口與限制摘要；其他規格文件作為詳細來源。
+- `spec:commit` 完成文件歸檔後，必須自動建立本機 Git commit；commit message 以需求編號與需求名稱為主，並加上簡短需求說明，格式為 `docs(REQ-001): 需求名稱 - 簡短需求說明`。
+- `spec:commit` 只有在使用者明確要求推送 remote，或專案設定啟用 auto-push 時，才可執行 `git push`；push 失敗時只回報認證或網路問題，不得回滾已完成的文件歸檔與本機 commit。
+- 文件未經使用者確認，不得標示為 `已審核`。
+- `uml.puml` 不限單一 UML 圖型；`spec:analyze` 必須依需求選擇最能說明流程、互動、狀態或資料關係的 UML 圖，例如活動圖、循序圖、使用案例圖、狀態圖或類別圖，不可為了固定格式硬產生活動圖。需求複雜時，可在同一個 `uml.puml` 內放多張 PlantUML 圖並清楚分段。
+- 一次最多問 3 個待確認問題，優先詢問會影響範圍、資料、權限、API、DB 或驗收的問題。
+
+# 衝突檢查重點
+
+`spec:analyze` 至少檢查：
+
+- 是否與既有需求目標或流程重疊。
+- 是否改變既有角色、權限或資料存取規則。
+- 是否影響既有 API 路徑、request/response 或狀態碼。
+- 是否影響既有 DB Table、欄位、唯一性或關聯。
+- 是否與既有驗收條件矛盾。
+
+# 衝突處理流程
+
+若 `spec:analyze` 發現衝突：
+
+1. 列出衝突的既有需求編號與檔案。
+2. 說明衝突原因與影響範圍。
+3. 提出最多 3 個待釐清問題。
+4. 停止產出 SRS、UML、OpenAPI、DB Schema。
+5. 等使用者釐清後，再由使用者執行 `spec:analyze` 繼續。
+6. 不得修改任何既有需求文件。
+
+# 狀態機
+
+```text
+init -> propose -> analyze
+
+analyze 無衝突 -> 產出待確認版本 -> commit
+analyze 有衝突 -> 釐清問題 -> analyze
+
+commit -> 歸檔 -> 本機 Git commit
+```
+
+# 歸檔結構
+
+```text
+project/
+  index.md
+  REQ-001-name/
+    srs.md
+    uml.puml
+    openapi.yaml
+    db-schema.md
+    handoff.md
+    history.md
+```

package/templates/project/index.md

@@ -0,0 +1,4 @@
+# 需求索引
+
+| 編號 | 標題 | 敘述 | 狀態 | 建立時間 | 更新時間 |
+|---|---|---|---|---|---|

package/templates/project/req/db-schema.md

@@ -0,0 +1,9 @@
+# {{REQ_ID}} {{REQ_NAME}} DB Schema
+
+## Tables
+
+待補充。
+
+## Notes
+
+- 待確認。

package/templates/project/req/handoff.md

@@ -0,0 +1,33 @@
+# {{REQ_ID}} {{REQ_NAME}} Handoff
+
+- 狀態：待確認
+- 來源文件：`srs.md`、`uml.puml`、`openapi.yaml`、`db-schema.md`
+- 目標讀者：OpenSpec、Codex、Claude、Gemini 或其他 AI 開發工具
+
+## 要開發什麼
+待補充。
+
+## 不要開發什麼
+- 待補充。
+
+## 已確認規則
+- 待補充。
+
+## 狀態與流程
+待補充。
+
+## API 契約
+待補充；若無 API 需求，明確標示「無 API 需求」。
+
+## DB 變更
+待補充；若無 DB 需求，明確標示「無 DB 需求」。
+
+## 驗收條件
+- 待補充。
+
+## 開發限制
+- 不得自行新增未確認的角色、權限、資料、流程、狀態、API 或 DB 欄位。
+- 若發現既有系統衝突，必須停止開發並回報。
+
+## 建議實作範圍
+- 待補充。

package/templates/project/req/history.md

@@ -0,0 +1,4 @@
+# {{REQ_ID}} {{REQ_NAME}} History
+
+| 時間 | 版本 | 摘要 | 狀態 |
+|---|---|---|---|

package/templates/project/req/openapi.yaml

@@ -0,0 +1,5 @@
+openapi: 3.0.3
+info:
+  title: {{REQ_ID}} {{REQ_NAME}} API
+  version: 0.1.0
+paths: {}

package/templates/project/req/srs.md

@@ -0,0 +1,26 @@
+# {{REQ_ID}} {{REQ_NAME}} SRS
+
+- 狀態：待確認
+- 最新版本：v0.1
+
+## 摘要
+待補充。
+
+## 使用者與目標
+- 使用者/角色：待補充。
+- 目標：待補充。
+
+## 流程
+待補充。
+
+## 功能需求
+- 待補充。
+
+## 驗收條件
+- 待補充。
+
+## 待確認
+- 待補充。
+
+## 注意事項
+- 無。

package/templates/project/req/uml.puml

@@ -0,0 +1,14 @@
+@startuml
+title {{REQ_ID}} {{REQ_NAME}}
+
+actor User as "使用者"
+participant System as "系統"
+
+User -> System: 發起需求
+System --> User: 回傳結果
+
+note right of System
+待於 spec:exec 後補充流程細節。
+end note
+
+@enduml

package/templates/project/system-spec.md

@@ -0,0 +1,15 @@
+# 系統概覽
+
+- 狀態：草稿
+
+## 這個系統要解決什麼
+待補充。
+
+## 使用者
+待補充。
+
+## 主要需求
+待補充。
+
+## 待確認
+- 待補充。