@kenkyou/supekku 0.1.0-alpha.0 → 0.1.0-alpha.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (30) hide show
  1. package/README.md +42 -4
  2. package/dist/agent-onboarding.md +51 -1
  3. package/dist/{archive-zV-1FPIG.mjs → archive-C9H-mmH5.mjs} +1 -1
  4. package/dist/archive-CHD4Te38.mjs +1 -0
  5. package/dist/artifact-DpGEBZwh.mjs +2 -0
  6. package/dist/{artifact-DFA13JnU.mjs → artifact-F8toITED.mjs} +3 -3
  7. package/dist/{connect-Bfgp9Y_w.mjs → connect-BzygwM5L.mjs} +2 -2
  8. package/dist/doctor-BBRvUMOX.mjs +1 -0
  9. package/dist/{doctor-DYGXldO4.mjs → doctor-CiotyxFb.mjs} +3 -3
  10. package/dist/{feedback-CS1HHQqT.mjs → feedback-BmygGL4q.mjs} +1 -1
  11. package/dist/{feedback-C2zx-BMA.mjs → feedback-DBsutUQW.mjs} +1 -1
  12. package/dist/index.mjs +184 -16
  13. package/dist/init-C5RDDwUf.mjs +95 -0
  14. package/dist/{project-YL4kEL7c.mjs → project-BXsAoMV1.mjs} +9 -5
  15. package/dist/project-BejWazB8.mjs +1 -0
  16. package/dist/project-JhzSd3ia.mjs +1 -0
  17. package/dist/{project-Djy7qwQy.mjs → project-Ru88VeXP.mjs} +1 -1
  18. package/dist/{publish-CPyVtYSl.mjs → publish-BZXi-1Iu.mjs} +1 -1
  19. package/dist/skills/supekku-development/SKILL.md +4 -0
  20. package/dist/skills/supekku-development/references/agent-onboarding.md +51 -1
  21. package/dist/{skills-BmMLLF83.mjs → skills-DcxDoyH7.mjs} +3 -3
  22. package/dist/skills-YRZw153S.mjs +1 -0
  23. package/dist/status-BzK0I8Ni.mjs +124 -0
  24. package/dist/status-DJee7WIX.mjs +1 -0
  25. package/dist/{status-BvBBIdUu.mjs → status-DrNLYKef.mjs} +30 -15
  26. package/package.json +1 -1
  27. package/dist/artifact-BTrZyotV.mjs +0 -2
  28. package/dist/project-B4BDXHwA.mjs +0 -1
  29. package/dist/project-DAv2aODU.mjs +0 -1
  30. package/dist/skills-CtT50_yk.mjs +0 -1
package/README.md CHANGED
@@ -2,11 +2,11 @@
2
2
 
3
3
  以規格驅動 AI Agent 開發:討論、提案、規格/設計、Tasks、驗證、TDD/Review、正式規格合併與封存。Artifact 是可選的討論材料;純本機開發流程不需要 Web 帳號或 Google 登入。
4
4
 
5
- 目前為 `0.1.0-alpha.0` 預覽候選。此版本尚在發布準備;以下 npm 指令在套件發布後才可使用。
5
+ 此套件為 `0.1.0-alpha.2` 預覽版,建議明確使用 `@next`;預覽版不代表穩定版。
6
6
 
7
7
  ## 安裝
8
8
 
9
- 需要 Node.js **24.22.1 或以上**。發布後安裝指定的預覽標籤:
9
+ 需要 Node.js **24.22.1 或以上**。安裝指定的預覽標籤:
10
10
 
11
11
  ```sh
12
12
  npm install -g @kenkyou/supekku@next
@@ -25,6 +25,26 @@ npm install @kenkyou/supekku@next
25
25
 
26
26
  未發布的候選可將套件名稱替換成取得的 `.tgz` 絕對路徑。以下命令中的 `supekku` 須使用你選擇的新版執行路徑。
27
27
 
28
+ ## 一次完成初始化(alpha.2)
29
+
30
+ 在專案根目錄執行 `supekku init`,終端會詢問 Agent,依序初始化、安裝兩套 skills 並執行 doctor。此入口自 0.1.0-alpha.2 提供。
31
+
32
+ ```sh
33
+ supekku init
34
+ supekku init --agent codex --json
35
+ supekku init --independent --agent codex --json
36
+ supekku init --project /path/to/project --agent claude --json
37
+ supekku init --target .agents/skills --json
38
+ ```
39
+
40
+ Agent 選項:`codex` → `.codex/skills`、`claude` → `.claude/skills`、`agents` → `.agents/skills`。自訂 `--target` 與 `--agent` 互斥;不猜測 Agent 或寫入全域目錄。安裝後自行重新載入 Agent。
41
+
42
+ `--json` 或非互動程序必須提供 agent/target,不會等待輸入。互動選單沒有預設選項,取消、EOF 或非法選擇均不寫入。init 的 `--independent` 可使用目前目錄,底層 local init 仍要求搭配明確 --project。
43
+
44
+ 先預檢目標及 skill 衝突再寫入;既有修改與中斷檔案保留。多步操作不是單一交易,失敗不自動回滾或重送。JSON 的 `ok:true` 表示已產生流程結果,只有 `data.completed:true` 才代表全部就緒;部分失敗退出2,回報 failedStage、error、completedStages。先處理原因,再以相同選項明確重跑。doctor.ready 不代表 DB 健康或 Agent 已載入。
45
+
46
+ 底層 `local init`、`skills install/status`、`doctor` 保留;不登入、不綁 Web、不啟動任務,也不改寫 AGENTS.md。
47
+
28
48
  ## 純本機使用
29
49
 
30
50
  在要管理的專案執行,不在 CLI 安裝目錄初始化:
@@ -37,7 +57,7 @@ supekku doctor --project /path/to/project --target .agents/skills --json
37
57
 
38
58
  兩套隨附 skill 為 `supekku-development` 與 `supekku-artifacts`。請選擇 Agent 支援的目錄並重新載入;安裝不代表 Agent 已載入。使用 development skill 完成提案到封存;CLI 不會因評論或規格確認自動授權實作。
39
59
 
40
- 正式文件保存在 `.supekku/`,建議進 Git;`.supekku/.local/` 是私有日誌,不進 Git,也不是可隨意刪除的快取。已有上層 Supekku 專案時不能再建立巢狀根目錄。
60
+ 正式文件保存在 `.supekku/`,建議進 Git;`.supekku/.local/` 是私有日誌,不進 Git,也不是可隨意刪除的快取。預設拒絕在上層 Supekku 專案內初始化;新版原始碼支援明確指定 `local init --project <root> --independent` 建立獨立根目錄,不修改上層資料。此選項自 0.1.0-alpha.1 提供。
41
61
 
42
62
  ## 選用 Web 協作
43
63
 
@@ -52,8 +72,26 @@ supekku artifact template document review-notes --json
52
72
 
53
73
  ## 平台與更新
54
74
 
55
- 目前 macOS arm64 有本機驗證;macOS x64、Linux x64 glibc、Windows x64 的這個發布候選尚待獨立驗證,不把安裝成功或預覽標籤當成四平台認證。原生依賴需要對應預編譯產物。
75
+ 0.1.0-alpha.0 已在 macOS arm64/x64、Linux x64 glibc、Windows x64 的 CI 以同一份 tarball 通過乾淨安裝與 CLI 行為驗證,停用安裝腳本以確認不依賴現場編譯。此結果不代表最低 OS/glibc 或所有遠端憑證操作已驗證。
56
76
 
57
77
  由早期內部 `@supekku/cli` 改名為 `@kenkyou/supekku`。舊套件與既有專案不會自動搬移;舊 scope 的 skill 收據會被當成不同套件,請保留自訂內容、使用新的支援目錄安裝,不修改收據來繞過保護。
58
78
 
59
79
  隨套件的 `dist/agent-onboarding.md`、`dist/change-workflow.md`、`dist/task-execution.md`、`dist/change-archive.md` 與 `dist/cli-publication.md` 提供完整操作說明。資料修改前請先備份;測試或留言不是執行授權。
80
+
81
+ ## 快捷入口(alpha.2)
82
+
83
+ ```sh
84
+ supekku status
85
+ supekku status --agent codex --json
86
+ supekku status --remote --json
87
+ supekku check my-change --json
88
+ supekku feedback my-document --limit 20 --json
89
+ supekku feedback my-document --version <versionId> --after <nextCursor> --json
90
+ supekku skills update --agent codex --json
91
+ ```
92
+
93
+ 所有入口可加 --project。status 預設不連線、不載入憑證、不初始化;省略 agent/target 時明示 skills 未檢查。顯示目前提案、Task runtime 狀態與待恢復封存/發布;不代表授權實作或自動恢復。--remote 只確認綁定與帳號的專案存取,不查所有 Artifact 版本;版本比較仍用 artifact status <id> --remote。
94
+
95
+ status 每次最多20提案、每案50任務、100筆 pending 發布,明示 hasMore;個案不可讀、缺少 journal、截斷或遠端失敗保留其他結果,complete:false 並退出2。缺資料不代表已驗證沒有待恢復操作。SQLite 讀取可能產生 WAL 協調檔;無業務寫入或恢復。
96
+
97
+ check 保留 change validate 的 valid、findings 和退出碼;ok:true 不等於 valid:true。feedback 是遠端只讀 list 捷徑,保留版本、cursor、limit 與現有授權,不回覆或標記完成。skills update 使用隨目前 CLI 的 skills,不更新 npm、不初始化專案、不覆寫自行修改內容。需明確 agent 或 target;可安全更新狀態不等於 Agent 已重新載入。原始底層指令持續支援。
@@ -1,6 +1,26 @@
1
1
  # Agent 安裝與專案啟用
2
2
 
3
- 需要 Node 24.22.1 或以上的受測版本。請使用已建置/安裝的新版 `@kenkyou/supekku`;`--version` 取自執行套件的 package.json。目前候選預覽版本為 0.1.0-alpha.0,不代表已公開發布或完成四平台發行認證。專案裡若還有舊版同名 CLI,先確認你執行的檔案路徑;以下 `supekku` 都指新版安裝後的 bin。
3
+ 需要 Node 24.22.1 或以上的受測版本。請使用已建置/安裝的新版 `@kenkyou/supekku`;`--version` 取自執行套件的 package.json。本指南對應 0.1.0-alpha.2;發行驗證以各版 release 紀錄為準。專案裡若還有舊版同名 CLI,先確認你執行的檔案路徑;以下 `supekku` 都指新版安裝後的 bin。
4
+
5
+ ## 一次完成初始化(alpha.2)
6
+
7
+ 在專案根目錄執行 `supekku init`,終端會詢問 Agent,依序初始化、安裝兩套 skills 並執行 doctor。此入口自 0.1.0-alpha.2 提供。
8
+
9
+ ```sh
10
+ supekku init
11
+ supekku init --agent codex --json
12
+ supekku init --independent --agent codex --json
13
+ supekku init --project /path/to/project --agent claude --json
14
+ supekku init --target .agents/skills --json
15
+ ```
16
+
17
+ Agent 選項:`codex` → `.codex/skills`、`claude` → `.claude/skills`、`agents` → `.agents/skills`。自訂 `--target` 與 `--agent` 互斥;不猜測 Agent 或寫入全域目錄。安裝後自行重新載入 Agent。
18
+
19
+ `--json` 或非互動程序必須提供 agent/target,不會等待輸入。互動選單沒有預設選項,取消、EOF 或非法選擇均不寫入。init 的 `--independent` 可使用目前目錄,底層 local init 仍要求搭配明確 --project。
20
+
21
+ 先預檢目標及 skill 衝突再寫入;既有修改與中斷檔案保留。多步操作不是單一交易,失敗不自動回滾或重送。JSON 的 `ok:true` 表示已產生流程結果,只有 `data.completed:true` 才代表全部就緒;部分失敗退出2,回報 failedStage、error、completedStages。先處理原因,再以相同選項明確重跑。doctor.ready 不代表 DB 健康或 Agent 已載入。
22
+
23
+ 底層 `local init`、`skills install/status`、`doctor` 保留;不登入、不綁 Web、不啟動任務,也不改寫 AGENTS.md。
4
24
 
5
25
  ## 第一次使用
6
26
 
@@ -14,6 +34,18 @@ supekku doctor --project /path/to/project --target .agents/skills --json
14
34
 
15
35
  `local init` 建立 .supekku/.local 的本機 journal 與排除規則,不登入、不綁 Web,也不建立提案。既有根目錄可重複執行;在已管理專案的子目錄初始化會被拒絕並指出既有根目錄,不自動另建巢狀專案。舊 supekku/ 必須明確 migrate-directory;舊 journal 必須明確 db upgrade,不刪除資料繞過。
16
36
 
37
+ ### 在上層專案內明確建立獨立根目錄
38
+
39
+ 若上層有舊 `supekku/` 或 `.supekku/`,但目標資料夾應是另一個專案,可以明確指定:
40
+
41
+ ```sh
42
+ supekku local init --project /path/to/hakulax --independent --json
43
+ ```
44
+
45
+ 此選項僅適用 local init,必須同時提供 --project。只初始化指定資料夾,不掃描或遷移上層管理資料。後續指令從新根目錄或其子目錄尋找最近的 `.supekku/`。不加此選項時仍保留原本拒絕巢狀初始化的行為。
46
+
47
+ 目標本身若有舊 supekku/、新舊目錄衝突、symlink 或不安全 journal,仍拒絕;沒有 force 覆寫。此功能不會安裝 skills、綁定網站或授權實作。不要把獨立子專案目錄列入父專案 Task scope。此選項自 0.1.0-alpha.1 提供,alpha.0 不支援。
48
+
17
49
  `--target` 是專案根目錄相對路徑,必須明確指定。`.agents/skills` 是一個例子;只有所用 Agent 支援該位置時才使用。也可指定支援的專案內 `.codex/skills`。不支援全域路徑、自動偵測 Agent 或改寫 AGENTS.md。安裝後請依 Agent 的設定重新載入/重開對話,doctor 不會假裝能確認 Agent 已載入。
18
50
 
19
51
  兩套隨執行中 CLI 發行的 skill 都會安裝:`supekku-development`(提案、TDD、Review、封存)與 `supekku-artifacts`(可選的討論材料與發布)。此流程完全離線;只有需要 Web 發布/評論時再依 CLI 發布指南 connect。
@@ -68,3 +100,21 @@ doctor 的 `readiness.inspection.available` 表示 Node 與原生目錄足以開
68
100
  沒有 journal 時,活動 Task 的 `status/snapshot` 以空事件計算目前狀態;Markdown 宣告 done 不會產生 runtime 完成證據。Git 中的 `.supekku/archive/` 文件與 receipt 是歷史依據,不能轉成本機 done、當作本次驗證或新授權。`change archive-list` 查的是本機 journal 的操作,不是 Git 歷史文件清單。
69
101
 
70
102
  禁止直接讀取、複製私有 SQLite;這不禁止已授權的原生 CLI 正常使用 journal。既有 journal 的 status/snapshot 可能需要本機鎖與檔案存取權限,不保證在唯讀檔案系統可執行。禁止讀取環境檔;本機接手不需要 Web 登入或環境密鑰。
103
+
104
+ ## 快捷入口(alpha.2)
105
+
106
+ ```sh
107
+ supekku status
108
+ supekku status --agent codex --json
109
+ supekku status --remote --json
110
+ supekku check my-change --json
111
+ supekku feedback my-document --limit 20 --json
112
+ supekku feedback my-document --version <versionId> --after <nextCursor> --json
113
+ supekku skills update --agent codex --json
114
+ ```
115
+
116
+ 所有入口可加 --project。status 預設不連線、不載入憑證、不初始化;省略 agent/target 時明示 skills 未檢查。顯示目前提案、Task runtime 狀態與待恢復封存/發布;不代表授權實作或自動恢復。--remote 只確認綁定與帳號的專案存取,不查所有 Artifact 版本;版本比較仍用 artifact status <id> --remote。
117
+
118
+ status 每次最多20提案、每案50任務、100筆 pending 發布,明示 hasMore;個案不可讀、缺少 journal、截斷或遠端失敗保留其他結果,complete:false 並退出2。缺資料不代表已驗證沒有待恢復操作。SQLite 讀取可能產生 WAL 協調檔;無業務寫入或恢復。
119
+
120
+ check 保留 change validate 的 valid、findings 和退出碼;ok:true 不等於 valid:true。feedback 是遠端只讀 list 捷徑,保留版本、cursor、limit 與現有授權,不回覆或標記完成。skills update 使用隨目前 CLI 的 skills,不更新 npm、不初始化專案、不覆寫自行修改內容。需明確 agent 或 target;可安全更新狀態不等於 Agent 已重新載入。原始底層指令持續支援。
@@ -272,4 +272,4 @@ async function archiveCommand(action, args, project, hook = async () => {}) {
272
272
  }
273
273
  });
274
274
  }
275
- export { archiveCommand };
275
+ export { archiveCommand as t };
@@ -0,0 +1 @@
1
+ export { t as archiveCommand } from "./archive-C9H-mmH5.mjs";
@@ -0,0 +1,2 @@
1
+ import "./project-directory-w_ITkI7O.mjs";
2
+ export { t as artifactCommand } from "./artifact-F8toITED.mjs";
@@ -136,7 +136,7 @@ async function artifactCommand(action, args, project) {
136
136
  if (action === "template") return artifactTemplate(args[0], args[1]);
137
137
  const root = await findProject(project);
138
138
  if (action === "status") {
139
- const { artifactStatus } = await import("./status-BvBBIdUu.mjs");
139
+ const { artifactStatus } = await import("./status-DJee7WIX.mjs");
140
140
  if (!args.includes("--remote")) return artifactStatus(root, args[0]);
141
141
  const { createConnection } = await import("./connection-BXfXx-wo.mjs");
142
142
  const { credentials } = await import("./credentials-CxkhjmnO.mjs");
@@ -147,7 +147,7 @@ async function artifactCommand(action, args, project) {
147
147
  "publish-status",
148
148
  "publish-resume"
149
149
  ].includes(action)) {
150
- const { publishArtifact, resumePublication } = await import("./publish-CPyVtYSl.mjs");
150
+ const { publishArtifact, resumePublication } = await import("./publish-BZXi-1Iu.mjs");
151
151
  const { createConnection } = await import("./connection-BXfXx-wo.mjs");
152
152
  const { credentials } = await import("./credentials-CxkhjmnO.mjs");
153
153
  const remote = createConnection({ store: credentials });
@@ -229,7 +229,7 @@ async function artifactCommand(action, args, project) {
229
229
  return { artifacts };
230
230
  }
231
231
  if (action === "feedback") {
232
- const { feedback } = await import("./feedback-CS1HHQqT.mjs");
232
+ const { feedback } = await import("./feedback-BmygGL4q.mjs");
233
233
  return feedback(root, args);
234
234
  }
235
235
  if (action === "serve") {
@@ -1,8 +1,8 @@
1
1
  import { t as CoreError } from "./src-CRhxwFAN.mjs";
2
2
  import { t as findProject } from "./project-directory-w_ITkI7O.mjs";
3
- import "./artifact-DFA13JnU.mjs";
3
+ import "./artifact-F8toITED.mjs";
4
4
  import { n as serverOrigin } from "./connection-DaxqQEdP.mjs";
5
- import { r as readBinding, t as linkProject } from "./project-Djy7qwQy.mjs";
5
+ import { r as readBinding, t as linkProject } from "./project-Ru88VeXP.mjs";
6
6
  // src/remote/connect.ts
7
7
  async function connectProject(start, options, connection, notice) {
8
8
  const root = await findProject(start);
@@ -0,0 +1 @@
1
+ export { t as doctor } from "./doctor-CiotyxFb.mjs";
@@ -1,7 +1,7 @@
1
1
  import { t as CoreError } from "./src-CRhxwFAN.mjs";
2
- import { n as directoryPresence, o as projectObservation } from "./project-YL4kEL7c.mjs";
2
+ import { n as directoryPresence, s as projectObservation } from "./project-BXsAoMV1.mjs";
3
3
  import { t as nodeSupported } from "./package-Ci4aNmkW.mjs";
4
- import { i as targetPath, r as skillStatus } from "./skills-BmMLLF83.mjs";
4
+ import { a as targetPath, i as skillStatus } from "./skills-DcxDoyH7.mjs";
5
5
  import { join } from "node:path";
6
6
  import { lstat } from "node:fs/promises";
7
7
  // src/onboarding/doctor.ts
@@ -67,4 +67,4 @@ async function doctor(start, target, identity, nodeVersion = process.versions.no
67
67
  next
68
68
  };
69
69
  }
70
- export { doctor };
70
+ export { doctor as t };
@@ -3,7 +3,7 @@ import { i as resolveFeedback, n as listFeedback, r as replyFeedback } from "./f
3
3
  // src/commands/artifact/feedback.ts
4
4
  async function feedback(root, args) {
5
5
  if (args.includes("--remote")) {
6
- const { readRemoteFeedback } = await import("./feedback-C2zx-BMA.mjs");
6
+ const { readRemoteFeedback } = await import("./feedback-DBsutUQW.mjs");
7
7
  const { createConnection } = await import("./connection-BXfXx-wo.mjs");
8
8
  const { credentials } = await import("./credentials-CxkhjmnO.mjs");
9
9
  return readRemoteFeedback(root, args, createConnection({ store: credentials }));
@@ -1,7 +1,7 @@
1
1
  import { l as Check, n as Hash, r as SnapshotSchema, t as CoreError, u as Type } from "./src-CRhxwFAN.mjs";
2
2
  import { a as artifactId, r as LocalId } from "./artifact-local-Bfy69a9H.mjs";
3
3
  import { t as Uuid } from "./api-D-iVy-AK.mjs";
4
- import { r as readBinding } from "./project-Djy7qwQy.mjs";
4
+ import { r as readBinding } from "./project-Ru88VeXP.mjs";
5
5
  // ../../packages/contracts/src/collaboration.ts
6
6
  const object = (properties) => Type.Object(properties, { additionalProperties: false });
7
7
  const text = (maxLength) => Type.String({
package/dist/index.mjs CHANGED
@@ -3,6 +3,48 @@ import { i as exitCode, o as normalizeError, t as CoreError } from "./src-CRhxwF
3
3
  import { a as snapshot, i as prepare, n as inspect, r as plan } from "./src-DeDtBfdV.mjs";
4
4
  import { r as readMarkdown } from "./files-DphxaLNK.mjs";
5
5
  import { n as workflowId } from "./change-BGLzKkKO.mjs";
6
+ // src/commands/shortcuts.ts
7
+ const agentTargets = {
8
+ codex: ".codex/skills",
9
+ claude: ".claude/skills",
10
+ agents: ".agents/skills"
11
+ };
12
+ function expandShortcuts(raw) {
13
+ if (raw[0] === "check") return [
14
+ "change",
15
+ "validate",
16
+ ...raw.slice(1)
17
+ ];
18
+ if (raw[0] === "feedback") {
19
+ if (!raw[1] || raw[1].startsWith("--")) throw new CoreError("INVALID_ARGUMENT", "feedback requires an Artifact ID");
20
+ return [
21
+ "artifact",
22
+ "feedback",
23
+ "list",
24
+ raw[1],
25
+ "--remote",
26
+ ...raw.slice(2)
27
+ ];
28
+ }
29
+ if (raw[0] === "skills" && raw[1] === "update") {
30
+ const next = ["skills", "install"];
31
+ let selection = false;
32
+ for (let i = 2; i < raw.length; i++) {
33
+ const key = raw[i];
34
+ if (key === "--agent" || key === "--target") {
35
+ if (selection) throw new CoreError("INVALID_ARGUMENT", "Choose exactly one agent or target");
36
+ selection = true;
37
+ const value = raw[++i];
38
+ const target = key === "--agent" && Object.hasOwn(agentTargets, value) ? agentTargets[value] : key === "--target" ? value : void 0;
39
+ if (!target || target.startsWith("--")) throw new CoreError("INVALID_ARGUMENT", "Expected a supported agent or target");
40
+ next.push("--target", target);
41
+ } else next.push(key);
42
+ }
43
+ if (!selection) throw new CoreError("INVALID_ARGUMENT", "skills update requires --agent or --target");
44
+ return next;
45
+ }
46
+ return raw;
47
+ }
6
48
  // src/commands/arguments.ts
7
49
  const commands = {
8
50
  "document check": 1,
@@ -20,7 +62,12 @@ const commands = {
20
62
  "operation show": 1
21
63
  };
22
64
  const help = [
23
- "local init [--project <root>] [--lock-wait <0..60000>] [--json]",
65
+ "status [--project <root>] [--agent codex|claude|agents | --target <directory>] [--remote] [--json]",
66
+ "check <change-id> [--project <root>] [--json]",
67
+ "feedback <artifact-id> [--version <UUID>] [--after <UUID>] [--limit <1..100>] [--project <root>] [--json]",
68
+ "skills update --agent codex|claude|agents | --target <directory> [--project <root>] [--json]",
69
+ "init [--project <root>] [--agent codex|claude|agents | --target <directory>] [--independent] [--lock-wait <0..60000>] [--json]",
70
+ "local init [--project <root>] [--independent] [--lock-wait <0..60000>] [--json]",
24
71
  "skills install|status --target <project-relative-directory> [--project <path>] [--json]",
25
72
  "doctor [--project <path>] [--target <project-relative-directory>] [--json]",
26
73
  "change archive-list [--all] [--project <path>] [--json]",
@@ -54,6 +101,86 @@ const help = [
54
101
  "--lock-wait <0..60000> (local commands only)"
55
102
  ];
56
103
  function parseArguments(raw) {
104
+ raw = expandShortcuts(raw);
105
+ if (raw[0] === "status") {
106
+ let project = process.cwd(), target, json = false, reportRemote = false;
107
+ const seen = /* @__PURE__ */ new Set();
108
+ for (let i = 1; i < raw.length; i++) {
109
+ const key = raw[i];
110
+ if (seen.has(key)) throw new CoreError("INVALID_ARGUMENT", "Duplicate status option");
111
+ seen.add(key);
112
+ if (key === "--json") json = true;
113
+ else if (key === "--remote") reportRemote = true;
114
+ else if ([
115
+ "--project",
116
+ "--agent",
117
+ "--target"
118
+ ].includes(key)) {
119
+ const value = raw[++i];
120
+ if (!value || value.startsWith("--")) throw new CoreError("INVALID_ARGUMENT", "Expected status option value");
121
+ if (key === "--project") project = value;
122
+ else {
123
+ if (target !== void 0) throw new CoreError("INVALID_ARGUMENT", "Choose agent or target");
124
+ if (key === "--agent" && !Object.hasOwn(agentTargets, value)) throw new CoreError("INVALID_ARGUMENT", "Unknown Agent");
125
+ target = key === "--agent" ? agentTargets[value] : value;
126
+ }
127
+ } else throw new CoreError("INVALID_ARGUMENT", "Unknown status option");
128
+ }
129
+ return {
130
+ command: "status",
131
+ args: target ? [target] : [],
132
+ project,
133
+ json,
134
+ reportRemote
135
+ };
136
+ }
137
+ if (raw[0] === "init") {
138
+ let project = process.cwd(), agent, target;
139
+ let independent = false, json = false, waitMs = 0;
140
+ const seen = /* @__PURE__ */ new Set();
141
+ for (let i = 1; i < raw.length; i++) {
142
+ const key = raw[i];
143
+ if (seen.has(key)) throw new CoreError("INVALID_ARGUMENT", "Duplicate init option");
144
+ seen.add(key);
145
+ if (key === "--json") json = true;
146
+ else if (key === "--independent") independent = true;
147
+ else if ([
148
+ "--project",
149
+ "--agent",
150
+ "--target",
151
+ "--lock-wait"
152
+ ].includes(key)) {
153
+ const value = raw[++i];
154
+ if (!value || value.startsWith("--")) throw new CoreError("INVALID_ARGUMENT", "Expected init option value");
155
+ if (key === "--project") project = value;
156
+ else if (key === "--agent") {
157
+ if (![
158
+ "codex",
159
+ "claude",
160
+ "agents"
161
+ ].includes(value)) throw new CoreError("INVALID_ARGUMENT", "Agent must be codex, claude or agents");
162
+ agent = value;
163
+ } else if (key === "--target") target = value;
164
+ else {
165
+ if (!/^\d+$/.test(value) || Number(value) > 6e4) throw new CoreError("INVALID_ARGUMENT", "Invalid lock wait");
166
+ waitMs = Number(value);
167
+ }
168
+ } else throw new CoreError("INVALID_ARGUMENT", "Unknown init option");
169
+ }
170
+ if (agent && target) throw new CoreError("INVALID_ARGUMENT", "Choose --agent or --target, not both");
171
+ return {
172
+ command: "init",
173
+ args: [],
174
+ project,
175
+ json,
176
+ waitMs,
177
+ initOptions: {
178
+ agent,
179
+ target,
180
+ independent
181
+ }
182
+ };
183
+ }
57
184
  if (raw[0] === "doctor" || raw[0] === "skills" || raw[0] === "local" && raw[1] === "init") {
58
185
  const command = raw[0] === "doctor" ? "doctor" : `${raw[0]} ${raw[1]}`;
59
186
  if (![
@@ -62,13 +189,14 @@ function parseArguments(raw) {
62
189
  "skills status",
63
190
  "local init"
64
191
  ].includes(command)) throw new CoreError("INVALID_ARGUMENT", "Unknown onboarding command");
65
- let project = process.cwd(), target, json = false, waitMs = 0;
192
+ let project = process.cwd(), target, json = false, waitMs = 0, independent = false;
66
193
  const seen = /* @__PURE__ */ new Set();
67
194
  for (let i = command === "doctor" ? 1 : 2; i < raw.length; i++) {
68
195
  const key = raw[i];
69
196
  if (seen.has(key)) throw new CoreError("INVALID_ARGUMENT", "Duplicate onboarding option");
70
197
  seen.add(key);
71
- if (key === "--json") json = true;
198
+ if (key === "--independent" && command === "local init") independent = true;
199
+ else if (key === "--json") json = true;
72
200
  else if (key === "--project" || key === "--target" && command !== "local init") {
73
201
  const value = raw[++i];
74
202
  if (!value || value.startsWith("--")) throw new CoreError("INVALID_ARGUMENT", "Expected an option path");
@@ -81,12 +209,14 @@ function parseArguments(raw) {
81
209
  } else throw new CoreError("INVALID_ARGUMENT", "Unexpected onboarding option");
82
210
  }
83
211
  if (command.startsWith("skills ") && target === void 0) throw new CoreError("INVALID_ARGUMENT", "Expected --target <project-relative-directory>");
212
+ if (independent && !seen.has("--project")) throw new CoreError("INVALID_ARGUMENT", "--independent requires explicit --project <root>");
84
213
  return {
85
214
  command,
86
215
  args: target === void 0 ? [] : [target],
87
216
  project,
88
217
  json,
89
- waitMs
218
+ waitMs,
219
+ independent
90
220
  };
91
221
  }
92
222
  if (raw[0] === "change" && raw[1] === "archive-list") {
@@ -484,22 +614,53 @@ try {
484
614
  command = parsed.command;
485
615
  json = parsed.json;
486
616
  const args = parsed.args;
617
+ const displayCommand = raw[0] === "check" || raw[0] === "feedback" ? raw[0] : raw[0] === "skills" && raw[1] === "update" ? "skills update" : command;
487
618
  let data;
488
- if (command === "doctor" || command.startsWith("skills ")) {
619
+ if (command === "status") {
620
+ const { packageIdentity } = await import("./package-Dg68Av6x.mjs");
621
+ const { projectSummary } = await import("./status-BzK0I8Ni.mjs");
622
+ const remoteCheck = parsed.reportRemote ? async (root) => {
623
+ const { projectStatus, readBinding } = await import("./project-JhzSd3ia.mjs");
624
+ if (!(await readBinding(root)).binding) return { remote: { state: "unbound" } };
625
+ const { createConnection } = await import("./connection-BXfXx-wo.mjs");
626
+ const { credentials } = await import("./credentials-CxkhjmnO.mjs");
627
+ return projectStatus(root, createConnection({ store: credentials }).identity);
628
+ } : void 0;
629
+ data = await projectSummary(parsed.project ?? process.cwd(), args[0], await packageIdentity(), remoteCheck);
630
+ if (!data.complete) process.exitCode = 2;
631
+ } else if (command === "init" && parsed.initOptions) {
632
+ const { packageIdentity } = await import("./package-Dg68Av6x.mjs");
633
+ const { selectTarget, initProject } = await import("./init-C5RDDwUf.mjs");
634
+ const { withLockOptions } = await import("./locks-ePa5rQ2P.mjs");
635
+ const target = await selectTarget(parsed.initOptions, !json && !!process.stdin.isTTY && !!process.stderr.isTTY);
636
+ const identity = await packageIdentity();
637
+ const controller = new AbortController();
638
+ const interrupt = () => controller.abort();
639
+ process.once("SIGINT", interrupt);
640
+ try {
641
+ data = await withLockOptions({
642
+ waitMs: parsed.waitMs,
643
+ signal: controller.signal
644
+ }, () => initProject(parsed.project, target, parsed.initOptions.independent, identity));
645
+ } finally {
646
+ process.off("SIGINT", interrupt);
647
+ }
648
+ if (!data.completed) process.exitCode = 2;
649
+ } else if (command === "doctor" || command.startsWith("skills ")) {
489
650
  const { packageIdentity } = await import("./package-Dg68Av6x.mjs");
490
651
  const identity = await packageIdentity();
491
652
  if (command === "doctor") {
492
- const { doctor } = await import("./doctor-DYGXldO4.mjs");
653
+ const { doctor } = await import("./doctor-BBRvUMOX.mjs");
493
654
  data = await doctor(parsed.project ?? process.cwd(), args[0], identity);
494
655
  if (!data.ready) process.exitCode = 2;
495
656
  } else {
496
- const { initializedProject, nativeProject } = await import("./project-B4BDXHwA.mjs");
657
+ const { initializedProject, nativeProject } = await import("./project-BejWazB8.mjs");
497
658
  const root = await (command === "skills install" ? initializedProject : nativeProject)(parsed.project ?? process.cwd());
498
- const { installSkills, skillStatus } = await import("./skills-CtT50_yk.mjs");
659
+ const { installSkills, skillStatus } = await import("./skills-YRZw153S.mjs");
499
660
  data = command === "skills install" ? await installSkills(root, args[0], identity) : await skillStatus(root, args[0], identity);
500
661
  }
501
662
  } else if (command.startsWith("change archive")) {
502
- const { archiveCommand } = await import("./archive-zV-1FPIG.mjs");
663
+ const { archiveCommand } = await import("./archive-CHD4Te38.mjs");
503
664
  data = await archiveCommand(command.slice(7), args, parsed.project ?? process.cwd());
504
665
  if (command === "change archive-plan" && !data.ready) process.exitCode = 2;
505
666
  } else if (command.startsWith("task ")) {
@@ -517,7 +678,7 @@ try {
517
678
  } else if (command === "connect" && parsed.connectOptions) {
518
679
  const { createConnection } = await import("./connection-BXfXx-wo.mjs");
519
680
  const { credentials } = await import("./credentials-CxkhjmnO.mjs");
520
- const { connectProject } = await import("./connect-Bfgp9Y_w.mjs");
681
+ const { connectProject } = await import("./connect-BzygwM5L.mjs");
521
682
  const { handoffBrowser } = await import("./browser-xnEH9tG1.mjs");
522
683
  const connection = createConnection({ store: credentials });
523
684
  let handoff = Promise.resolve();
@@ -547,12 +708,12 @@ try {
547
708
  } else if (command.startsWith("project ") && parsed.bindingOptions) {
548
709
  const { createConnection } = await import("./connection-BXfXx-wo.mjs");
549
710
  const { credentials } = await import("./credentials-CxkhjmnO.mjs");
550
- const { linkProject, projectStatus } = await import("./project-DAv2aODU.mjs");
711
+ const { linkProject, projectStatus } = await import("./project-JhzSd3ia.mjs");
551
712
  const connection = createConnection({ store: credentials });
552
713
  const options = parsed.bindingOptions;
553
714
  data = command === "project link" ? await linkProject(parsed.project, options.server, options.projectId, options.replace, connection.identity) : await projectStatus(parsed.project, connection.identity);
554
715
  } else if (command.startsWith("artifact ")) {
555
- const { artifactCommand } = await import("./artifact-BTrZyotV.mjs");
716
+ const { artifactCommand } = await import("./artifact-DpGEBZwh.mjs");
556
717
  data = await artifactCommand(command.slice(9), args, parsed.project ?? process.cwd());
557
718
  } else if (command === "version") {
558
719
  const { packageIdentity } = await import("./package-Dg68Av6x.mjs");
@@ -580,8 +741,8 @@ try {
580
741
  signal: controller.signal
581
742
  }, async () => {
582
743
  if (command === "local init") {
583
- const { initializeProject } = await import("./project-B4BDXHwA.mjs");
584
- return initializeProject(parsed.project ?? process.cwd());
744
+ const { initializeProject } = await import("./project-BejWazB8.mjs");
745
+ return initializeProject(parsed.project ?? process.cwd(), "independent" in parsed && parsed.independent);
585
746
  }
586
747
  if (command === "operation show" || command === "operation list") {
587
748
  const local = await import("./local-DrJ8z2qm.mjs");
@@ -598,6 +759,7 @@ try {
598
759
  process.off("SIGINT", interrupt);
599
760
  }
600
761
  }
762
+ command = displayCommand;
601
763
  if (json) process.stdout.write(JSON.stringify({
602
764
  outputVersion: 1,
603
765
  command,
@@ -610,10 +772,16 @@ try {
610
772
  process.stdout.write((connected.changed ? "已完成專案連接" : "已確認既有專案連接") + "\n帳號:" + connected.identity.user.name + "\n本機資料夾:" + connected.root + "\n網站:" + connected.binding.remote.origin + "\n專案:" + connected.binding.remote.projectId + "\n後續可直接由 Agent 使用此綁定;本次沒有發布 Artifact。\n");
611
773
  } else if (command === "version") process.stdout.write(data.version + "\n");
612
774
  else if (command === "help") process.stdout.write("Supekku — specifications, changes and Artifact feedback\n\n" + help.join("\n") + "\n\nRevision approval workflow retired. Discuss feedback with your Agent and publish a new version; use auth login, project link and artifact publish for explicit Web publication.\n");
613
- else if (command === "doctor") process.stdout.write("Local onboarding prerequisites " + (data.ready ? "ready" : "needs attention") + "\nDocument inspection: " + (data.readiness.inspection.available ? "available (content not validated)" : "unavailable") + "\n" + JSON.stringify(data, null, 2) + "\n");
614
- else if (command === "change validate") process.stdout.write("Change validation " + (data.valid ? "passed" : "failed") + "\n" + JSON.stringify(data, null, 2) + "\n");
775
+ else if (command === "init") {
776
+ const result = data;
777
+ process.stdout.write(`${result.completed ? "初始化完成" : "初始化未完成"}\n專案:${result.root}\nSkills:${result.target}\n已完成:${result.completedStages.join(", ") || "無"}\n` + (result.error ? `${result.failedStage}: ${result.error.message}\n` : "") + result.next.join("\n") + "\n");
778
+ } else if (command === "doctor") process.stdout.write("Local onboarding prerequisites " + (data.ready ? "ready" : "needs attention") + "\nDocument inspection: " + (data.readiness.inspection.available ? "available (content not validated)" : "unavailable") + "\n" + JSON.stringify(data, null, 2) + "\n");
779
+ else if (command === "status") process.stdout.write((data.complete ? "狀態查詢完成" : "狀態查詢需要注意;部分結果不完整") + "\n" + JSON.stringify(data, null, 2) + "\n");
780
+ else if (command === "change validate" || command === "check") process.stdout.write("Change validation " + (data.valid ? "passed" : "failed") + "\n" + JSON.stringify(data, null, 2) + "\n");
615
781
  else process.stdout.write(command + " succeeded\n" + JSON.stringify(data, null, 2) + "\n");
616
782
  } catch (e) {
783
+ if (raw[0] === "check" || raw[0] === "feedback") command = raw[0];
784
+ else if (raw[0] === "skills" && raw[1] === "update") command = "skills update";
617
785
  const error = normalizeError(e);
618
786
  if (json) process.stdout.write(JSON.stringify({
619
787
  outputVersion: 1,
@@ -0,0 +1,95 @@
1
+ import { o as normalizeError, t as CoreError } from "./src-CRhxwFAN.mjs";
2
+ import { i as initializeProject, r as initializationObservation } from "./project-BXsAoMV1.mjs";
3
+ import { t as nodeSupported } from "./package-Ci4aNmkW.mjs";
4
+ import { i as skillStatus, n as checkSkillResults, r as installSkills } from "./skills-DcxDoyH7.mjs";
5
+ import { t as doctor } from "./doctor-CiotyxFb.mjs";
6
+ import { createInterface } from "node:readline/promises";
7
+ // src/onboarding/init.ts
8
+ const targets = {
9
+ codex: ".codex/skills",
10
+ claude: ".claude/skills",
11
+ agents: ".agents/skills"
12
+ };
13
+ async function selectTarget(options, interactive, ask = askAgent) {
14
+ if (options.target) return options.target;
15
+ if (options.agent) {
16
+ if (!targets[options.agent]) throw new CoreError("INVALID_ARGUMENT", "Unknown Agent");
17
+ return targets[options.agent];
18
+ }
19
+ if (!interactive) throw new CoreError("INVALID_ARGUMENT", "Noninteractive init requires --agent codex|claude|agents or --target <directory>");
20
+ const selected = {
21
+ "1": "codex",
22
+ "2": "claude",
23
+ "3": "agents"
24
+ }[(await ask()).trim()];
25
+ if (!selected) throw new CoreError("INVALID_ARGUMENT", "Initialization cancelled or invalid Agent selection; no files written");
26
+ return targets[selected];
27
+ }
28
+ async function askAgent() {
29
+ const rl = createInterface({
30
+ input: process.stdin,
31
+ output: process.stderr
32
+ });
33
+ const abort = new AbortController();
34
+ const cancel = () => abort.abort();
35
+ rl.once("SIGINT", cancel);
36
+ rl.once("close", cancel);
37
+ try {
38
+ return await rl.question("選擇 Agent:\n1. Codex (.codex/skills)\n2. Claude Code (.claude/skills)\n3. 共用 skills (.agents/skills)\n輸入 1–3,或 Ctrl+C 取消:", { signal: abort.signal });
39
+ } catch {
40
+ throw new CoreError("INVALID_ARGUMENT", "Initialization cancelled; no files written");
41
+ } finally {
42
+ rl.off("SIGINT", cancel);
43
+ rl.off("close", cancel);
44
+ rl.close();
45
+ }
46
+ }
47
+ async function initProject(start, target, independent, identity, operations = {
48
+ initialize: initializeProject,
49
+ install: installSkills,
50
+ diagnose: doctor
51
+ }) {
52
+ if (!nodeSupported(process.versions.node, identity.nodeMinimum)) throw new CoreError("INVALID_ARGUMENT", `Use Node ${identity.nodeMinimum} or newer`);
53
+ const root = (await initializationObservation(start, independent)).root;
54
+ const preflight = await skillStatus(root, target, identity);
55
+ checkSkillResults(preflight.skills.map((report) => ({ report })));
56
+ const completedStages = [];
57
+ let stage = "initialize";
58
+ let initialization;
59
+ try {
60
+ initialization = await operations.initialize(root, independent);
61
+ completedStages.push("initialize");
62
+ stage = "skills";
63
+ const skills = await operations.install(root, target, identity);
64
+ completedStages.push("skills");
65
+ stage = "doctor";
66
+ const report = await operations.diagnose(root, target, identity);
67
+ completedStages.push("doctor");
68
+ return {
69
+ completed: report.ready,
70
+ root,
71
+ target,
72
+ completedStages,
73
+ initialization,
74
+ skills,
75
+ doctor: report,
76
+ next: ["Reload skills in your Agent; initialization does not authorize implementation", ...!report.ready ? report.next : []]
77
+ };
78
+ } catch (cause) {
79
+ const error = normalizeError(cause);
80
+ return {
81
+ completed: false,
82
+ root,
83
+ target,
84
+ completedStages,
85
+ initialization,
86
+ failedStage: stage,
87
+ error: {
88
+ code: error.code,
89
+ message: error.message
90
+ },
91
+ next: ["Completed state was preserved; inspect the error before explicitly rerunning init with the same target", "Use skills status and doctor for diagnosis; preserve edited skills and interrupted-install files"]
92
+ };
93
+ }
94
+ }
95
+ export { initProject, selectTarget };
@@ -34,7 +34,7 @@ async function canonicalRoot(start) {
34
34
  root: await realpath(requested)
35
35
  };
36
36
  }
37
- async function projectObservation(start) {
37
+ async function projectObservation(start, exact = false) {
38
38
  const { requested, root } = await canonicalRoot(start);
39
39
  let candidate = root;
40
40
  for (;;) {
@@ -47,7 +47,7 @@ async function projectObservation(start) {
47
47
  state: current && legacy ? "conflict" : legacy ? "legacy" : "current"
48
48
  };
49
49
  const parent = dirname(candidate);
50
- if (parent === candidate) return {
50
+ if (exact || parent === candidate) return {
51
51
  requested,
52
52
  root,
53
53
  discoveredRoot: null,
@@ -68,11 +68,15 @@ async function initializedProject(start) {
68
68
  if (!await directoryPresence(join(root, ".supekku/.local"))) throw new CoreError("NOT_INITIALIZED", "Run local init --project <root> first");
69
69
  return root;
70
70
  }
71
- async function initializeProject(start) {
72
- const observed = await projectObservation(start);
71
+ async function initializationObservation(start, independent = false) {
72
+ const observed = await projectObservation(start, independent);
73
73
  if (observed.state === "conflict") throw new CoreError("INVALID_PATH", "Both .supekku and supekku exist; never merge automatically");
74
74
  if (observed.state === "legacy") throw new CoreError("MIGRATION_REQUIRED", "Run project migrate-directory explicitly");
75
75
  if (observed.discoveredRoot && observed.discoveredRoot !== observed.root) throw new CoreError("LOCAL_CONFLICT", `An existing project is rooted at ${observed.discoveredRoot}; initialize that exact root instead`);
76
+ return observed;
77
+ }
78
+ async function initializeProject(start, independent = false) {
79
+ const observed = await initializationObservation(start, independent);
76
80
  const local = join(observed.root, ".supekku/.local");
77
81
  const existed = observed.state === "current" && await directoryPresence(local);
78
82
  let journal = false;
@@ -92,4 +96,4 @@ async function initializeProject(start) {
92
96
  next: ["Choose a project-relative skill target, then run skills install --project <root> --target <directory>", "Run doctor --project <root> --target <directory>; reload skills in your Agent"]
93
97
  };
94
98
  }
95
- export { nativeProject as a, initializedProject as i, directoryPresence as n, projectObservation as o, initializeProject as r, canonicalRoot as t };
99
+ export { initializedProject as a, initializeProject as i, directoryPresence as n, nativeProject as o, initializationObservation as r, projectObservation as s, canonicalRoot as t };
@@ -0,0 +1 @@
1
+ export { i as initializeProject, a as initializedProject, o as nativeProject } from "./project-BXsAoMV1.mjs";
@@ -0,0 +1 @@
1
+ export { t as linkProject, n as projectStatus, r as readBinding } from "./project-Ru88VeXP.mjs";
@@ -1,7 +1,7 @@
1
1
  import { t as CoreError } from "./src-CRhxwFAN.mjs";
2
2
  import { t as findProject } from "./project-directory-w_ITkI7O.mjs";
3
3
  import { a as withStore, o as withArtifactLock, t as artifactLocal } from "./store-jFj2Dhgl.mjs";
4
- import "./artifact-DFA13JnU.mjs";
4
+ import "./artifact-F8toITED.mjs";
5
5
  import { n as serverOrigin } from "./connection-DaxqQEdP.mjs";
6
6
  import { randomUUID } from "node:crypto";
7
7
  import { join } from "node:path";
@@ -4,7 +4,7 @@ import { i as revisionBytes, n as getRevision } from "./revisions-CZyZmV7P.mjs";
4
4
  import { a as withStore, c as digest, o as withArtifactLock, t as artifactLocal } from "./store-jFj2Dhgl.mjs";
5
5
  import { r as requestLimit } from "./connection-DaxqQEdP.mjs";
6
6
  import { a as validatePublication, i as isPublicationView, n as isPreparePublication, r as isPublicationReceipt, t as canonicalPublication } from "./publications-DaNXLqrj.mjs";
7
- import { r as readBinding } from "./project-Djy7qwQy.mjs";
7
+ import { r as readBinding } from "./project-Ru88VeXP.mjs";
8
8
  import { randomUUID } from "node:crypto";
9
9
  // src/commands/artifact/publication-plan.ts
10
10
  async function planPublication(root, id, revision) {
@@ -26,3 +26,7 @@ For a new or resumed conversation, use [stage and continuation guidance](referen
26
26
  The CLI records Agent attestations and checks content fingerprints; it cannot prove tests ran or authenticate user consent. Keep secrets and full raw logs out of evidence. Preserve operation IDs for exact retries; use a new ID for new evidence. Report remaining limitations honestly. Task finish alone does not merge, archive, commit, publish or deploy. Archive is a separate explicitly authorized operation and never automatically commits.
27
27
 
28
28
  For optional discussion Artifacts, follow [handoff and version provenance](references/handoff.md). The companion skill is named `supekku-artifacts`; development without it or a Web account remains supported. Preserve the pinned reference and agreed conclusions before starting tasks.
29
+
30
+ For explicitly authorized project activation, `supekku init --agent codex --project <root> --json` composes initialization, protected skills installation and doctor. Use claude/agents or explicit --target only for the chosen host. Noninteractive runs must specify a destination. Use --independent only when the user wants a separate root beneath an existing managed parent. Inspect data.completed and partial-stage errors; do not assume ok:true means ready or retry blindly. This does not authorize implementation or connect Web. Lower-level commands remain available.
31
+
32
+ Convenience commands: `status --project <root> --json` is local only; `--remote` explicitly checks binding authorization. Inspect complete, section errors and hasMore; no result authorizes recovery. `check <change> --json` preserves change validate semantics. `skills update --agent codex --project <root> --json` updates only protected managed skills from the executing package. Do not use it to overwrite edited content.
@@ -1,6 +1,26 @@
1
1
  # Agent 安裝與專案啟用
2
2
 
3
- 需要 Node 24.22.1 或以上的受測版本。請使用已建置/安裝的新版 `@kenkyou/supekku`;`--version` 取自執行套件的 package.json。目前候選預覽版本為 0.1.0-alpha.0,不代表已公開發布或完成四平台發行認證。專案裡若還有舊版同名 CLI,先確認你執行的檔案路徑;以下 `supekku` 都指新版安裝後的 bin。
3
+ 需要 Node 24.22.1 或以上的受測版本。請使用已建置/安裝的新版 `@kenkyou/supekku`;`--version` 取自執行套件的 package.json。本指南對應 0.1.0-alpha.2;發行驗證以各版 release 紀錄為準。專案裡若還有舊版同名 CLI,先確認你執行的檔案路徑;以下 `supekku` 都指新版安裝後的 bin。
4
+
5
+ ## 一次完成初始化(alpha.2)
6
+
7
+ 在專案根目錄執行 `supekku init`,終端會詢問 Agent,依序初始化、安裝兩套 skills 並執行 doctor。此入口自 0.1.0-alpha.2 提供。
8
+
9
+ ```sh
10
+ supekku init
11
+ supekku init --agent codex --json
12
+ supekku init --independent --agent codex --json
13
+ supekku init --project /path/to/project --agent claude --json
14
+ supekku init --target .agents/skills --json
15
+ ```
16
+
17
+ Agent 選項:`codex` → `.codex/skills`、`claude` → `.claude/skills`、`agents` → `.agents/skills`。自訂 `--target` 與 `--agent` 互斥;不猜測 Agent 或寫入全域目錄。安裝後自行重新載入 Agent。
18
+
19
+ `--json` 或非互動程序必須提供 agent/target,不會等待輸入。互動選單沒有預設選項,取消、EOF 或非法選擇均不寫入。init 的 `--independent` 可使用目前目錄,底層 local init 仍要求搭配明確 --project。
20
+
21
+ 先預檢目標及 skill 衝突再寫入;既有修改與中斷檔案保留。多步操作不是單一交易,失敗不自動回滾或重送。JSON 的 `ok:true` 表示已產生流程結果,只有 `data.completed:true` 才代表全部就緒;部分失敗退出2,回報 failedStage、error、completedStages。先處理原因,再以相同選項明確重跑。doctor.ready 不代表 DB 健康或 Agent 已載入。
22
+
23
+ 底層 `local init`、`skills install/status`、`doctor` 保留;不登入、不綁 Web、不啟動任務,也不改寫 AGENTS.md。
4
24
 
5
25
  ## 第一次使用
6
26
 
@@ -14,6 +34,18 @@ supekku doctor --project /path/to/project --target .agents/skills --json
14
34
 
15
35
  `local init` 建立 .supekku/.local 的本機 journal 與排除規則,不登入、不綁 Web,也不建立提案。既有根目錄可重複執行;在已管理專案的子目錄初始化會被拒絕並指出既有根目錄,不自動另建巢狀專案。舊 supekku/ 必須明確 migrate-directory;舊 journal 必須明確 db upgrade,不刪除資料繞過。
16
36
 
37
+ ### 在上層專案內明確建立獨立根目錄
38
+
39
+ 若上層有舊 `supekku/` 或 `.supekku/`,但目標資料夾應是另一個專案,可以明確指定:
40
+
41
+ ```sh
42
+ supekku local init --project /path/to/hakulax --independent --json
43
+ ```
44
+
45
+ 此選項僅適用 local init,必須同時提供 --project。只初始化指定資料夾,不掃描或遷移上層管理資料。後續指令從新根目錄或其子目錄尋找最近的 `.supekku/`。不加此選項時仍保留原本拒絕巢狀初始化的行為。
46
+
47
+ 目標本身若有舊 supekku/、新舊目錄衝突、symlink 或不安全 journal,仍拒絕;沒有 force 覆寫。此功能不會安裝 skills、綁定網站或授權實作。不要把獨立子專案目錄列入父專案 Task scope。此選項自 0.1.0-alpha.1 提供,alpha.0 不支援。
48
+
17
49
  `--target` 是專案根目錄相對路徑,必須明確指定。`.agents/skills` 是一個例子;只有所用 Agent 支援該位置時才使用。也可指定支援的專案內 `.codex/skills`。不支援全域路徑、自動偵測 Agent 或改寫 AGENTS.md。安裝後請依 Agent 的設定重新載入/重開對話,doctor 不會假裝能確認 Agent 已載入。
18
50
 
19
51
  兩套隨執行中 CLI 發行的 skill 都會安裝:`supekku-development`(提案、TDD、Review、封存)與 `supekku-artifacts`(可選的討論材料與發布)。此流程完全離線;只有需要 Web 發布/評論時再依 CLI 發布指南 connect。
@@ -68,3 +100,21 @@ doctor 的 `readiness.inspection.available` 表示 Node 與原生目錄足以開
68
100
  沒有 journal 時,活動 Task 的 `status/snapshot` 以空事件計算目前狀態;Markdown 宣告 done 不會產生 runtime 完成證據。Git 中的 `.supekku/archive/` 文件與 receipt 是歷史依據,不能轉成本機 done、當作本次驗證或新授權。`change archive-list` 查的是本機 journal 的操作,不是 Git 歷史文件清單。
69
101
 
70
102
  禁止直接讀取、複製私有 SQLite;這不禁止已授權的原生 CLI 正常使用 journal。既有 journal 的 status/snapshot 可能需要本機鎖與檔案存取權限,不保證在唯讀檔案系統可執行。禁止讀取環境檔;本機接手不需要 Web 登入或環境密鑰。
103
+
104
+ ## 快捷入口(alpha.2)
105
+
106
+ ```sh
107
+ supekku status
108
+ supekku status --agent codex --json
109
+ supekku status --remote --json
110
+ supekku check my-change --json
111
+ supekku feedback my-document --limit 20 --json
112
+ supekku feedback my-document --version <versionId> --after <nextCursor> --json
113
+ supekku skills update --agent codex --json
114
+ ```
115
+
116
+ 所有入口可加 --project。status 預設不連線、不載入憑證、不初始化;省略 agent/target 時明示 skills 未檢查。顯示目前提案、Task runtime 狀態與待恢復封存/發布;不代表授權實作或自動恢復。--remote 只確認綁定與帳號的專案存取,不查所有 Artifact 版本;版本比較仍用 artifact status <id> --remote。
117
+
118
+ status 每次最多20提案、每案50任務、100筆 pending 發布,明示 hasMore;個案不可讀、缺少 journal、截斷或遠端失敗保留其他結果,complete:false 並退出2。缺資料不代表已驗證沒有待恢復操作。SQLite 讀取可能產生 WAL 協調檔;無業務寫入或恢復。
119
+
120
+ check 保留 change validate 的 valid、findings 和退出碼;ok:true 不等於 valid:true。feedback 是遠端只讀 list 捷徑,保留版本、cursor、limit 與現有授權,不回覆或標記完成。skills update 使用隨目前 CLI 的 skills,不更新 npm、不初始化專案、不覆寫自行修改內容。需明確 agent 或 target;可安全更新狀態不等於 Agent 已重新載入。原始底層指令持續支援。
@@ -217,7 +217,7 @@ async function skillStatus(root, target, bundle) {
217
217
  ready: skills.every((s) => s.state === "current")
218
218
  };
219
219
  }
220
- function check(results) {
220
+ function checkSkillResults(results) {
221
221
  const recovery = results.find((r) => r.report.state === "recovery-required");
222
222
  if (recovery) throw new CoreError("RECOVERY_REQUIRED", recovery.report.message);
223
223
  if (results.some((r) => ["modified", "unmanaged"].includes(r.report.state))) throw new CoreError("LOCAL_CONFLICT", "Skill content differs from its receipt; preserve edits and compare manually or choose a fresh target");
@@ -258,7 +258,7 @@ async function installSkills(root, target, bundle, io = { rename }) {
258
258
  return withLocks(local, "maintenance", async () => {
259
259
  await targetPath(root, target);
260
260
  const results = await Promise.all(sources.map((s) => inspect(destination.path, s.name, bundle, s.tree)));
261
- check(results);
261
+ checkSkillResults(results);
262
262
  if (results.every((r) => r.report.state === "current")) return {
263
263
  ...await skillStatus(root, target, bundle),
264
264
  changed: false
@@ -309,4 +309,4 @@ async function installSkills(root, target, bundle, io = { rename }) {
309
309
  };
310
310
  });
311
311
  }
312
- export { targetPath as i, installSkills as n, skillStatus as r, SKILLS as t };
312
+ export { targetPath as a, skillStatus as i, checkSkillResults as n, installSkills as r, SKILLS as t };
@@ -0,0 +1 @@
1
+ export { r as installSkills, i as skillStatus } from "./skills-DcxDoyH7.mjs";
@@ -0,0 +1,124 @@
1
+ import { o as normalizeError } from "./src-CRhxwFAN.mjs";
2
+ import { n as inspectWorkflow } from "./verification-BEG80Jm9.mjs";
3
+ import { n as changeCommand } from "./change-C4CjlVny.mjs";
4
+ import { n as taskCommand } from "./task-F-xMfIdb.mjs";
5
+ import { t as archiveCommand } from "./archive-C9H-mmH5.mjs";
6
+ import { n as pendingPublications } from "./status-DrNLYKef.mjs";
7
+ import { t as doctor } from "./doctor-CiotyxFb.mjs";
8
+ // src/onboarding/status.ts
9
+ function errorOf(cause) {
10
+ const e = normalizeError(cause);
11
+ return {
12
+ code: e.code,
13
+ message: e.message
14
+ };
15
+ }
16
+ async function projectSummary(start, target, identity, remoteCheck) {
17
+ const report = await doctor(start, target, identity);
18
+ const root = report.project.discoveredRoot ?? report.project.root;
19
+ let complete = report.readiness.inspection.available && report.journal.state === "present" && report.node.supported && (!target || report.ready);
20
+ const changes = {
21
+ items: [],
22
+ hasMore: false
23
+ };
24
+ let archive = { state: "not-checked" }, publications = { state: "not-checked" };
25
+ let remote = { state: "not-checked" };
26
+ if (report.project.state === "current") {
27
+ try {
28
+ const listed = await changeCommand("change list", [], root);
29
+ changes.hasMore = listed.changes.length > 20;
30
+ if (changes.hasMore) complete = false;
31
+ for (const change of listed.changes.slice(0, 20)) try {
32
+ const doc = await changeCommand("change show", [change.id], root);
33
+ const meta = inspectWorkflow(doc.files["tasks.md"]).meta;
34
+ if (meta.kind !== "tasks") throw Error("Invalid tasks");
35
+ const validation = await changeCommand("change validate", [change.id], root);
36
+ if (!validation.valid) complete = false;
37
+ const tasks = [];
38
+ for (const task of meta.tasks.slice(0, 50)) try {
39
+ const s = await taskCommand("status", [change.id, task.id], root);
40
+ tasks.push({
41
+ id: task.id,
42
+ state: s.state
43
+ });
44
+ } catch (e) {
45
+ complete = false;
46
+ tasks.push({
47
+ id: task.id,
48
+ state: "unavailable",
49
+ error: errorOf(e)
50
+ });
51
+ }
52
+ if (meta.tasks.length > 50) complete = false;
53
+ changes.items.push({
54
+ ...change,
55
+ valid: validation.valid,
56
+ tasks,
57
+ hasMore: meta.tasks.length > 50
58
+ });
59
+ } catch (e) {
60
+ complete = false;
61
+ changes.items.push({
62
+ ...change,
63
+ error: errorOf(e)
64
+ });
65
+ }
66
+ } catch (e) {
67
+ complete = false;
68
+ changes.error = errorOf(e);
69
+ }
70
+ try {
71
+ archive = {
72
+ state: "available",
73
+ ...await archiveCommand("archive-list", [], root)
74
+ };
75
+ } catch (e) {
76
+ complete = false;
77
+ archive = {
78
+ state: "unavailable",
79
+ error: errorOf(e)
80
+ };
81
+ }
82
+ try {
83
+ const p = await pendingPublications(root);
84
+ publications = p;
85
+ if (p.pendingHasMore) complete = false;
86
+ } catch (e) {
87
+ complete = false;
88
+ publications = {
89
+ state: "unavailable",
90
+ error: errorOf(e)
91
+ };
92
+ }
93
+ if (remoteCheck) {
94
+ try {
95
+ remote = (await remoteCheck(root)).remote;
96
+ } catch (e) {
97
+ remote = {
98
+ state: "unavailable",
99
+ code: errorOf(e).code
100
+ };
101
+ }
102
+ if (remote.state !== "verified") complete = false;
103
+ }
104
+ } else if (remoteCheck) {
105
+ remote = {
106
+ state: "unavailable",
107
+ code: "NOT_INITIALIZED"
108
+ };
109
+ complete = false;
110
+ }
111
+ return {
112
+ complete,
113
+ root,
114
+ readiness: report,
115
+ changes,
116
+ pending: {
117
+ archive,
118
+ publications
119
+ },
120
+ remote,
121
+ next: [...report.next, "Use check <change> for validation, task status for task details, and explicit archive/publish status before any recovery"]
122
+ };
123
+ }
124
+ export { projectSummary };
@@ -0,0 +1 @@
1
+ export { t as artifactStatus } from "./status-DrNLYKef.mjs";
@@ -8,7 +8,7 @@ import { a as validateSource } from "./revisions-CZyZmV7P.mjs";
8
8
  import { c as digest, l as readSource, n as inspectStore, r as storeMigrations } from "./store-jFj2Dhgl.mjs";
9
9
  import { n as serverOrigin } from "./connection-DaxqQEdP.mjs";
10
10
  import { n as isPreparePublication, r as isPublicationReceipt, t as canonicalPublication } from "./publications-DaNXLqrj.mjs";
11
- import { r as readBinding } from "./project-Djy7qwQy.mjs";
11
+ import { r as readBinding } from "./project-Ru88VeXP.mjs";
12
12
  import { join } from "node:path";
13
13
  import { lstat } from "node:fs/promises";
14
14
  import Database from "better-sqlite3";
@@ -228,17 +228,10 @@ async function checkedAvailable(root, id, revisionId, recorded, manifestText, fi
228
228
  }
229
229
  return true;
230
230
  }
231
- async function artifactStatus(root, id, remote) {
232
- artifactId(id);
233
- if (!await requireCurrentDirectory(root)) throw new CoreError("NOT_INITIALIZED", "No Supekku directory");
234
- const observedAt = (/* @__PURE__ */ new Date()).toISOString();
235
- const { binding } = await readBinding(root);
236
- const local = await observeSource(root, id);
237
- const saved = await readStore(root, (db) => {
238
- const checked = db.prepare("SELECT a.current_revision AS revisionId,r.available,r.manifest,r.files FROM artifacts a LEFT JOIN revisions r ON r.artifact_id=a.id AND r.id=a.current_revision WHERE a.id=?").get(id);
239
- if (checked?.revisionId && (!hash.test(checked.revisionId) || ![0, 1].includes(checked.available))) throw corrupt();
240
- const rows = db.prepare("SELECT * FROM publication_operations WHERE state NOT IN ('committed','expired','failed') ORDER BY created_at,id LIMIT 101").all();
241
- const pendingOperations = rows.slice(0, 100).map((row) => {
231
+ function pending(db, binding) {
232
+ const rows = db.prepare("SELECT * FROM publication_operations WHERE state NOT IN ('committed','expired','failed') ORDER BY created_at,id LIMIT 101").all();
233
+ return {
234
+ pendingOperations: rows.slice(0, 100).map((row) => {
242
235
  const o = operation(row);
243
236
  return {
244
237
  operationId: row.id,
@@ -248,7 +241,29 @@ async function artifactStatus(root, id, remote) {
248
241
  bindingMatches: binding !== null && canonicalPublication(o.binding) === canonicalPublication(binding),
249
242
  createdAt: new Date(row.created_at).toISOString()
250
243
  };
251
- });
244
+ }),
245
+ pendingHasMore: rows.length > 100
246
+ };
247
+ }
248
+ async function pendingPublications(root) {
249
+ const { binding } = await readBinding(root);
250
+ const result = await readStore(root, (db) => pending(db, binding));
251
+ return {
252
+ store: result ? "available" : "absent",
253
+ pendingOperations: result?.pendingOperations ?? [],
254
+ pendingHasMore: result?.pendingHasMore ?? false
255
+ };
256
+ }
257
+ async function artifactStatus(root, id, remote) {
258
+ artifactId(id);
259
+ if (!await requireCurrentDirectory(root)) throw new CoreError("NOT_INITIALIZED", "No Supekku directory");
260
+ const observedAt = (/* @__PURE__ */ new Date()).toISOString();
261
+ const { binding } = await readBinding(root);
262
+ const local = await observeSource(root, id);
263
+ const saved = await readStore(root, (db) => {
264
+ const checked = db.prepare("SELECT a.current_revision AS revisionId,r.available,r.manifest,r.files FROM artifacts a LEFT JOIN revisions r ON r.artifact_id=a.id AND r.id=a.current_revision WHERE a.id=?").get(id);
265
+ if (checked?.revisionId && (!hash.test(checked.revisionId) || ![0, 1].includes(checked.available))) throw corrupt();
266
+ const { pendingOperations, pendingHasMore } = pending(db, binding);
252
267
  let lastPublication = null;
253
268
  if (binding) {
254
269
  const row = db.prepare("SELECT * FROM publication_operations WHERE state='committed' AND json_extract(input,'$.localArtifactId')=? AND json_extract(binding,'$.repositoryId')=? AND json_extract(binding,'$.remote.origin')=? AND json_extract(binding,'$.remote.projectId')=? ORDER BY created_at DESC,id DESC LIMIT 1").get(id, binding.repositoryId, binding.remote.origin, binding.remote.projectId);
@@ -266,7 +281,7 @@ async function artifactStatus(root, id, remote) {
266
281
  } : null,
267
282
  lastPublication,
268
283
  pendingOperations,
269
- pendingHasMore: rows.length > 100
284
+ pendingHasMore
270
285
  };
271
286
  });
272
287
  if (saved?.checked) saved.checked.available = await checkedAvailable(root, id, saved.checked.revisionId, saved.checked.available, saved.checkedData.manifest, saved.checkedData.files);
@@ -317,4 +332,4 @@ async function artifactStatus(root, id, remote) {
317
332
  remote: result
318
333
  };
319
334
  }
320
- export { artifactStatus };
335
+ export { pendingPublications as n, artifactStatus as t };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@kenkyou/supekku",
3
- "version": "0.1.0-alpha.0",
3
+ "version": "0.1.0-alpha.2",
4
4
  "bin": {
5
5
  "supekku": "dist/index.mjs"
6
6
  },
@@ -1,2 +0,0 @@
1
- import "./project-directory-w_ITkI7O.mjs";
2
- export { t as artifactCommand } from "./artifact-DFA13JnU.mjs";
@@ -1 +0,0 @@
1
- export { r as initializeProject, i as initializedProject, a as nativeProject } from "./project-YL4kEL7c.mjs";
@@ -1 +0,0 @@
1
- export { t as linkProject, n as projectStatus } from "./project-Djy7qwQy.mjs";
@@ -1 +0,0 @@
1
- export { n as installSkills, r as skillStatus } from "./skills-BmMLLF83.mjs";