@xirang-ai/dsh-teamflow 0.1.1 → 0.1.3
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.
- package/README.en.md +15 -11
- package/README.md +15 -11
- package/RELEASE.md +6 -6
- package/cordis.patch.yml +6 -3
- package/lib/client.js +196 -39
- package/lib/index.d.ts +7 -1
- package/lib/index.js +10 -4
- package/lib/remote/contract.d.ts +34 -1
- package/lib/remote/contract.js +16 -0
- package/lib/remote/service.d.ts +15 -2
- package/lib/remote/service.js +49 -6
- package/lib/requirement-discussion.d.ts +23 -0
- package/lib/requirement-discussion.js +26 -0
- package/lib/store/db.d.ts +8 -3
- package/lib/store/db.js +34 -2
- package/lib/store/docs.d.ts +9 -11
- package/lib/store/docs.js +25 -52
- package/lib/store/model.d.ts +32 -5
- package/lib/store/model.js +9 -4
- package/lib/store/paths.d.ts +20 -0
- package/lib/store/paths.js +54 -1
- package/lib/store/schema.js +71 -14
- package/lib/store/workflow.d.ts +50 -25
- package/lib/store/workflow.js +275 -100
- package/lib/tools/delete-design-doc.d.ts +24 -0
- package/lib/tools/delete-design-doc.js +109 -0
- package/lib/tools/get-bug.js +1 -1
- package/lib/tools/get-design-doc.js +1 -1
- package/lib/tools/get-requirement.js +1 -1
- package/lib/tools/get-story.js +1 -1
- package/lib/tools/index.d.ts +1 -1
- package/lib/tools/index.js +12 -1
- package/lib/tools/link-session.d.ts +3 -0
- package/lib/tools/link-session.js +87 -0
- package/locale/en.json +3 -0
- package/locale/zh.json +3 -0
- package/package.json +1 -1
package/lib/remote/service.js
CHANGED
|
@@ -12,10 +12,22 @@ import { NAMESPACE, SERVICE_KEY } from "./contract.js";
|
|
|
12
12
|
* `WorkflowStore.readContent` returns `null` for a missing file, `''` for an
|
|
13
13
|
* empty one, and throws for any other I/O failure.
|
|
14
14
|
*/
|
|
15
|
-
function readBody(workflow,
|
|
16
|
-
const body = workflow.readContent(
|
|
15
|
+
function readBody(workflow, path) {
|
|
16
|
+
const body = workflow.readContent(path);
|
|
17
17
|
return body === null ? { body: '', bodyMissing: true } : { body, bodyMissing: false };
|
|
18
18
|
}
|
|
19
|
+
/** Confirmed discussions of one story or defect, newest first. */
|
|
20
|
+
function discussionsFor(rows, subjectType, subjectId) {
|
|
21
|
+
return rows
|
|
22
|
+
.filter((row) => row.subjectType === subjectType && row.subjectId === subjectId)
|
|
23
|
+
.map((row) => ({
|
|
24
|
+
sessionId: row.sessionId,
|
|
25
|
+
kind: row.kind,
|
|
26
|
+
preparedAt: row.preparedAt,
|
|
27
|
+
linkedAt: row.linkedAt,
|
|
28
|
+
createdAt: row.createdAt,
|
|
29
|
+
}));
|
|
30
|
+
}
|
|
19
31
|
/**
|
|
20
32
|
* Rebuild a failure in the caller's language.
|
|
21
33
|
*
|
|
@@ -84,7 +96,7 @@ export class WorkbenchService extends TypertRemoteService {
|
|
|
84
96
|
status: requirement.status,
|
|
85
97
|
updatedAt: requirement.updatedAt,
|
|
86
98
|
path: requirement.contentPath,
|
|
87
|
-
...readBody(this.workflow, requirement.
|
|
99
|
+
...readBody(this.workflow, requirement.contentPath),
|
|
88
100
|
completedAt: requirement.completedAt,
|
|
89
101
|
})),
|
|
90
102
|
stories: rows.stories.map((story) => ({
|
|
@@ -98,10 +110,11 @@ export class WorkbenchService extends TypertRemoteService {
|
|
|
98
110
|
createdAt: story.createdAt,
|
|
99
111
|
updatedAt: story.updatedAt,
|
|
100
112
|
path: story.contentPath,
|
|
101
|
-
...readBody(this.workflow, story.
|
|
113
|
+
...readBody(this.workflow, story.contentPath),
|
|
102
114
|
doneAt: story.doneAt,
|
|
103
115
|
completedAt: story.completedAt,
|
|
104
116
|
createSessionId: story.createSessionId,
|
|
117
|
+
sessions: discussionsFor(rows.discussionSessions, 'story', story.id),
|
|
105
118
|
})),
|
|
106
119
|
docs: rows.docs.map((doc) => ({
|
|
107
120
|
id: doc.id,
|
|
@@ -122,10 +135,11 @@ export class WorkbenchService extends TypertRemoteService {
|
|
|
122
135
|
status: bug.status,
|
|
123
136
|
resolution: bug.resolution,
|
|
124
137
|
updatedAt: bug.updatedAt,
|
|
125
|
-
...readBody(this.workflow, bug.
|
|
138
|
+
...readBody(this.workflow, bug.contentPath),
|
|
126
139
|
fixedAt: bug.fixedAt,
|
|
127
140
|
completedAt: bug.completedAt,
|
|
128
141
|
createSessionId: bug.createSessionId,
|
|
142
|
+
sessions: discussionsFor(rows.discussionSessions, 'bug', bug.id),
|
|
129
143
|
})),
|
|
130
144
|
runs: rows.runs.map((run) => ({
|
|
131
145
|
id: run.id,
|
|
@@ -400,6 +414,35 @@ export class WorkbenchService extends TypertRemoteService {
|
|
|
400
414
|
throw localizedFailure(error, locale);
|
|
401
415
|
}
|
|
402
416
|
}
|
|
417
|
+
/**
|
|
418
|
+
* Register a newly created conversation as a pending discussion of any subject.
|
|
419
|
+
*
|
|
420
|
+
* Same two-phase contract as {@link prepareRequirementSession}: the Agent
|
|
421
|
+
* confirms with `teamflow_link_session`, and this method never writes the
|
|
422
|
+
* confirmation time itself.
|
|
423
|
+
* @param subjectType - requirement, story or bug.
|
|
424
|
+
* @param subjectId - record the discussion belongs to.
|
|
425
|
+
* @param sessionId - session created by the browser for this discussion.
|
|
426
|
+
* @param kind - `discuss` for stories and defects; requirement kinds otherwise.
|
|
427
|
+
* @returns the stored pending row.
|
|
428
|
+
*/
|
|
429
|
+
prepareDiscussionSession(subjectType, subjectId, sessionId, kind, locale) {
|
|
430
|
+
try {
|
|
431
|
+
const row = this.workflow.prepareDiscussionSession(subjectType, subjectId, sessionId, kind);
|
|
432
|
+
return {
|
|
433
|
+
subjectType: row.subjectType,
|
|
434
|
+
subjectId: row.subjectId,
|
|
435
|
+
sessionId: row.sessionId,
|
|
436
|
+
kind: row.kind,
|
|
437
|
+
preparedAt: row.preparedAt,
|
|
438
|
+
linkedAt: row.linkedAt,
|
|
439
|
+
createdAt: row.createdAt,
|
|
440
|
+
};
|
|
441
|
+
}
|
|
442
|
+
catch (error) {
|
|
443
|
+
throw localizedFailure(error, locale);
|
|
444
|
+
}
|
|
445
|
+
}
|
|
403
446
|
/**
|
|
404
447
|
* Compute deletion impact without writing anything.
|
|
405
448
|
* @param targets - records the user selected in the panel.
|
|
@@ -459,7 +502,7 @@ export class WorkbenchService extends TypertRemoteService {
|
|
|
459
502
|
return {
|
|
460
503
|
id: doc.id,
|
|
461
504
|
title: doc.title,
|
|
462
|
-
...readBody(this.workflow,
|
|
505
|
+
...readBody(this.workflow, doc.contentPath),
|
|
463
506
|
};
|
|
464
507
|
}
|
|
465
508
|
catch (error) {
|
|
@@ -42,3 +42,26 @@ export declare function presetForRequirementDiscussion(kind: RequirementDiscussi
|
|
|
42
42
|
* @returns the first message of the discussion, carrying the supplement slot.
|
|
43
43
|
*/
|
|
44
44
|
export declare function buildRequirementDiscussionPrompt(kind?: RequirementDiscussionKind): string;
|
|
45
|
+
/** Preset for a story discussion (reuses the standalone story agent). */
|
|
46
|
+
export declare const STORY_DISCUSSION_PRESET = "xirang-story";
|
|
47
|
+
/** Preset for a defect discussion. */
|
|
48
|
+
export declare const BUG_DISCUSSION_PRESET = "xirang-bug";
|
|
49
|
+
/** A record kind whose detail page can start a discussion. */
|
|
50
|
+
export type RecordDiscussionKind = 'story' | 'bug';
|
|
51
|
+
/**
|
|
52
|
+
* Pick the preset a story or defect discussion runs under.
|
|
53
|
+
* @param kind - `story` or `bug`.
|
|
54
|
+
* @returns the preset id declared in `cordis.patch.yml`.
|
|
55
|
+
*/
|
|
56
|
+
export declare function presetForRecordDiscussion(kind: RecordDiscussionKind): string;
|
|
57
|
+
/**
|
|
58
|
+
* Build the prompt sent when the user starts a discussion from a story or defect page.
|
|
59
|
+
*
|
|
60
|
+
* The title travels in the prompt because it is what the reader recognises;
|
|
61
|
+
* the id stays out of it, just like requirement discussions: the tools resolve
|
|
62
|
+
* the record through the session binding.
|
|
63
|
+
* @param kind - `story` or `bug`.
|
|
64
|
+
* @param title - story or defect title shown to the reader.
|
|
65
|
+
* @returns the first message of the discussion, carrying the supplement slot.
|
|
66
|
+
*/
|
|
67
|
+
export declare function buildRecordDiscussionPrompt(kind: RecordDiscussionKind, title: string): string;
|
|
@@ -58,3 +58,29 @@ export function buildRequirementDiscussionPrompt(kind = 'design') {
|
|
|
58
58
|
}
|
|
59
59
|
return ['【继续讨论需求与概要设计】', '', '我的补充:'].join('\n');
|
|
60
60
|
}
|
|
61
|
+
/** Preset for a story discussion (reuses the standalone story agent). */
|
|
62
|
+
export const STORY_DISCUSSION_PRESET = 'xirang-story';
|
|
63
|
+
/** Preset for a defect discussion. */
|
|
64
|
+
export const BUG_DISCUSSION_PRESET = 'xirang-bug';
|
|
65
|
+
/**
|
|
66
|
+
* Pick the preset a story or defect discussion runs under.
|
|
67
|
+
* @param kind - `story` or `bug`.
|
|
68
|
+
* @returns the preset id declared in `cordis.patch.yml`.
|
|
69
|
+
*/
|
|
70
|
+
export function presetForRecordDiscussion(kind) {
|
|
71
|
+
return kind === 'bug' ? BUG_DISCUSSION_PRESET : STORY_DISCUSSION_PRESET;
|
|
72
|
+
}
|
|
73
|
+
/**
|
|
74
|
+
* Build the prompt sent when the user starts a discussion from a story or defect page.
|
|
75
|
+
*
|
|
76
|
+
* The title travels in the prompt because it is what the reader recognises;
|
|
77
|
+
* the id stays out of it, just like requirement discussions: the tools resolve
|
|
78
|
+
* the record through the session binding.
|
|
79
|
+
* @param kind - `story` or `bug`.
|
|
80
|
+
* @param title - story or defect title shown to the reader.
|
|
81
|
+
* @returns the first message of the discussion, carrying the supplement slot.
|
|
82
|
+
*/
|
|
83
|
+
export function buildRecordDiscussionPrompt(kind, title) {
|
|
84
|
+
const heading = kind === 'bug' ? '【继续讨论缺陷】' : '【继续讨论故事】';
|
|
85
|
+
return [heading, title, '', '我的补充:'].join('\n');
|
|
86
|
+
}
|
package/lib/store/db.d.ts
CHANGED
|
@@ -43,6 +43,10 @@ export interface StartupReport {
|
|
|
43
43
|
readonly file: string;
|
|
44
44
|
/** Database file rendered for logs (`$DSH_HOME/...`). */
|
|
45
45
|
readonly displayFile: string;
|
|
46
|
+
/** Absolute document root that holds `requirements/`, `stories/` and `bugs/`. */
|
|
47
|
+
readonly docsDir: string;
|
|
48
|
+
/** Document root rendered for logs (`$DSH_HOME/...`). */
|
|
49
|
+
readonly displayDocsDir: string;
|
|
46
50
|
/** Version stored before this start, `null` on the first start. */
|
|
47
51
|
readonly fromVersion: string | null;
|
|
48
52
|
/** Version now running. */
|
|
@@ -89,10 +93,11 @@ export interface OpenDatabaseOptions {
|
|
|
89
93
|
/** `Config.dataDir` override; empty uses the plugin home below `$DSH_HOME`. */
|
|
90
94
|
readonly dataDir?: string;
|
|
91
95
|
/**
|
|
92
|
-
*
|
|
93
|
-
*
|
|
96
|
+
* `Config.docsDir` override for the document root; empty uses `<dataDir>/docs`.
|
|
97
|
+
* Relative paths and `~/` resolve like {@link resolveDataDir}; an invalid value
|
|
98
|
+
* throws instead of falling back to the default.
|
|
94
99
|
*/
|
|
95
|
-
readonly
|
|
100
|
+
readonly docsDir?: string;
|
|
96
101
|
/** Resolver consulted before the registry, for the Host's live workspace list. */
|
|
97
102
|
readonly workspaceRoot?: (workspaceId: string) => string | undefined;
|
|
98
103
|
/** SQLite busy timeout in milliseconds. */
|
package/lib/store/db.js
CHANGED
|
@@ -11,7 +11,7 @@
|
|
|
11
11
|
import { DatabaseSync } from 'node:sqlite';
|
|
12
12
|
import { contextualError, describeError } from "../errors.js";
|
|
13
13
|
import { readPluginVersion } from "../version.js";
|
|
14
|
-
import { DATABASE_FILENAME, databaseFile, ensureDataDir, resolveDataDir, toDisplayPath, } from "./paths.js";
|
|
14
|
+
import { DATABASE_FILENAME, databaseFile, ensureDataDir, ensureDocsDir, resolveDataDir, resolveDocsDir, toDisplayPath, } from "./paths.js";
|
|
15
15
|
import { BUILTIN_ROLES, MIGRATIONS, TARGET_SCHEMA_VERSION, syncSchemaComments, } from "./schema.js";
|
|
16
16
|
import { withTransaction } from "./transaction.js";
|
|
17
17
|
import { runUpgrades } from "./upgrades.js";
|
|
@@ -36,6 +36,31 @@ export const META_KEYS = {
|
|
|
36
36
|
/** Schema version, mirrored from `PRAGMA user_version` for inspection. */
|
|
37
37
|
schemaVersion: 'schema_version',
|
|
38
38
|
};
|
|
39
|
+
/** Prefix of legacy content paths, which were relative to a workspace root. */
|
|
40
|
+
const LEGACY_DOC_PREFIX = '.xirang-ai/dsh-teamflow/';
|
|
41
|
+
/**
|
|
42
|
+
* Rewrite legacy workspace-relative `content_path` values onto the document
|
|
43
|
+
* root. Idempotent: rows already on the new basis do not match the prefix, so
|
|
44
|
+
* a restart after a partial failure simply finishes the job.
|
|
45
|
+
*
|
|
46
|
+
* This is a data-basis normalization, not a schema migration: the table layout
|
|
47
|
+
* and `user_version` stay untouched.
|
|
48
|
+
*
|
|
49
|
+
* @returns how many rows were rewritten.
|
|
50
|
+
*/
|
|
51
|
+
function normalizeContentPaths(db) {
|
|
52
|
+
const tables = ['requirements', 'design_docs', 'stories', 'bugs'];
|
|
53
|
+
return withTransaction(db, () => {
|
|
54
|
+
let changed = 0;
|
|
55
|
+
for (const table of tables) {
|
|
56
|
+
const result = db
|
|
57
|
+
.prepare(`UPDATE ${table} SET content_path = substr(content_path, ?) WHERE content_path LIKE ?`)
|
|
58
|
+
.run(LEGACY_DOC_PREFIX.length + 1, `${LEGACY_DOC_PREFIX}%`);
|
|
59
|
+
changed += Number(result.changes);
|
|
60
|
+
}
|
|
61
|
+
return changed;
|
|
62
|
+
});
|
|
63
|
+
}
|
|
39
64
|
function configure(db, busyTimeoutMs) {
|
|
40
65
|
const timeout = Number.isFinite(busyTimeoutMs) ? Math.max(0, Math.trunc(busyTimeoutMs)) : 0;
|
|
41
66
|
// WAL keeps readers unblocked while a writer holds the lock; NORMAL is the
|
|
@@ -175,6 +200,7 @@ export function openTeamflowDatabase(options = {}) {
|
|
|
175
200
|
const log = options.log ?? SILENT_LOGGER;
|
|
176
201
|
const version = options.version ?? readPluginVersion();
|
|
177
202
|
const dataDir = resolveDataDir(options.dataDir);
|
|
203
|
+
const docsDir = ensureDocsDir(resolveDocsDir(options.docsDir, dataDir));
|
|
178
204
|
const file = databaseFile(dataDir);
|
|
179
205
|
try {
|
|
180
206
|
ensureDataDir(dataDir);
|
|
@@ -194,10 +220,16 @@ export function openTeamflowDatabase(options = {}) {
|
|
|
194
220
|
const appliedMigrations = migrate(db, log);
|
|
195
221
|
syncSchemaComments(db);
|
|
196
222
|
seedBuiltinRoles(db);
|
|
223
|
+
const normalizedPaths = normalizeContentPaths(db);
|
|
224
|
+
if (normalizedPaths > 0) {
|
|
225
|
+
log.info(`normalized ${normalizedPaths} document path(s) onto the document root ${toDisplayPath(docsDir)}`);
|
|
226
|
+
}
|
|
197
227
|
const reconciliation = reconcileVersion(db, version, log);
|
|
198
228
|
const report = {
|
|
199
229
|
file,
|
|
200
230
|
displayFile: toDisplayPath(file),
|
|
231
|
+
docsDir,
|
|
232
|
+
displayDocsDir: toDisplayPath(docsDir),
|
|
201
233
|
fromVersion: reconciliation.fromVersion,
|
|
202
234
|
toVersion: version,
|
|
203
235
|
outcome: reconciliation.outcome,
|
|
@@ -225,7 +257,7 @@ export function openTeamflowDatabase(options = {}) {
|
|
|
225
257
|
db,
|
|
226
258
|
report,
|
|
227
259
|
workflow: new WorkflowStore(db, {
|
|
228
|
-
docsRoot:
|
|
260
|
+
docsRoot: docsDir,
|
|
229
261
|
workspaceRoot: options.workspaceRoot,
|
|
230
262
|
warn: (message) => log.warn(message),
|
|
231
263
|
}),
|
package/lib/store/docs.d.ts
CHANGED
|
@@ -1,9 +1,7 @@
|
|
|
1
|
-
/** 文档根目录名,工作区内的隐藏目录。 */
|
|
2
|
-
export declare const DOC_ROOT = ".xirang-ai/dsh-teamflow";
|
|
3
1
|
/** 文档种类:决定落盘路径。 */
|
|
4
2
|
export type DocKind = 'requirement' | 'designDoc' | 'story' | 'bug';
|
|
5
3
|
/**
|
|
6
|
-
*
|
|
4
|
+
* 计算一份文档在文档根内的相对路径。
|
|
7
5
|
*
|
|
8
6
|
* @param kind - 文档种类
|
|
9
7
|
* @param ids - 该种类需要的标识(designDoc 需要需求 id 与文档 id)
|
|
@@ -14,19 +12,19 @@ export declare function docPath(kind: DocKind, ids: {
|
|
|
14
12
|
requirementId?: string;
|
|
15
13
|
}): string;
|
|
16
14
|
/**
|
|
17
|
-
*
|
|
15
|
+
* 把相对路径拼到文档根上;只接受插件自己生成的、以 `/` 分隔的文档相对路径。
|
|
18
16
|
*
|
|
19
17
|
* 拒绝 POSIX 绝对路径、Windows 盘符/UNC/反斜杠路径与任何 `..`,最后再做一次
|
|
20
18
|
* 词法 containment 校验,确保结果仍落在 `root` 之内。
|
|
21
19
|
*/
|
|
22
20
|
export declare function resolveDocPath(root: string, relative: string): string;
|
|
23
|
-
/**
|
|
21
|
+
/** 文档相对路径的展示形式(日志与工具结果用,始终 `/`)。 */
|
|
24
22
|
export declare function displayPath(relative: string): string;
|
|
25
23
|
/**
|
|
26
|
-
*
|
|
27
|
-
*
|
|
24
|
+
* 首次为文档根准备共享目录:只建 `requirements/`、`stories/`、`bugs/`,
|
|
25
|
+
* 不碰工作区,也不写 `.gitignore`。
|
|
28
26
|
*
|
|
29
|
-
* @param root -
|
|
27
|
+
* @param root - 文档根目录(绝对路径)
|
|
30
28
|
* @returns 实际创建的目录(相对路径),便于工具结果里说明
|
|
31
29
|
*/
|
|
32
30
|
export declare function ensureDocTree(root: string): string[];
|
|
@@ -46,7 +44,7 @@ export declare function writeDoc(root: string, relative: string, body: string):
|
|
|
46
44
|
export declare function removeDoc(root: string, relative: string): void;
|
|
47
45
|
/** 已挪出正式路径、等待随数据库事务一起确认删除的文档。 */
|
|
48
46
|
export interface StagedDoc {
|
|
49
|
-
/**
|
|
47
|
+
/** 原来的文档相对路径;事务失败时据此还原。 */
|
|
50
48
|
readonly relative: string;
|
|
51
49
|
/** 临时绝对路径,与正式文件同目录,保证 rename 是原子的。 */
|
|
52
50
|
readonly staged: string;
|
|
@@ -58,8 +56,8 @@ export interface StagedDoc {
|
|
|
58
56
|
* 到临时名,再在 SQLite 事务里删记录:事务失败就把文件改回来,事务成功才真正
|
|
59
57
|
* `unlink`。这样任何时刻都不会出现「记录已经没了、正式路径上的文件还在」的悬挂态。
|
|
60
58
|
*
|
|
61
|
-
* @param root -
|
|
62
|
-
* @param relative -
|
|
59
|
+
* @param root - 文档根目录
|
|
60
|
+
* @param relative - 文档相对路径
|
|
63
61
|
* @returns 暂存信息;文件本来就不存在时返回 `null`
|
|
64
62
|
*/
|
|
65
63
|
export declare function stageDocDeletion(root: string, relative: string): StagedDoc | null;
|
package/lib/store/docs.js
CHANGED
|
@@ -1,23 +1,20 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* 文档落盘:正文不进 SQLite
|
|
2
|
+
* 文档落盘:正文不进 SQLite,只记文档根内的相对路径。
|
|
3
3
|
*
|
|
4
|
-
*
|
|
4
|
+
* 目录结构(相对文档根,默认 `$DSH_HOME/xirang-ai/dsh-teamflow/docs`):
|
|
5
5
|
*
|
|
6
|
-
* .
|
|
7
|
-
*
|
|
8
|
-
*
|
|
9
|
-
*
|
|
10
|
-
* bugs/<bug_id>/bug.md 缺陷正文(描述、复现、期望、实际、环境)
|
|
6
|
+
* requirements/<req_id>/requirement.md 需求 + 概要设计正文
|
|
7
|
+
* requirements/<req_id>/docs/<doc_id>.md 详细设计文档(一份需求可以有很多份)
|
|
8
|
+
* stories/<sty_id>/story.md 故事说明 + 验收标准
|
|
9
|
+
* bugs/<bug_id>/bug.md 缺陷正文(描述、复现、期望、实际、环境)
|
|
11
10
|
*
|
|
12
11
|
* 所有写操作走「临时文件 + rename」,避免中途崩溃留下半截文档。
|
|
13
12
|
*/
|
|
14
13
|
import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmdirSync, rmSync, writeFileSync, } from 'node:fs';
|
|
15
|
-
import { dirname, isAbsolute,
|
|
14
|
+
import { dirname, isAbsolute, posix, resolve, sep, win32 } from 'node:path';
|
|
16
15
|
import { describeError } from "../errors.js";
|
|
17
|
-
/** 文档根目录名,工作区内的隐藏目录。 */
|
|
18
|
-
export const DOC_ROOT = '.xirang-ai/dsh-teamflow';
|
|
19
16
|
/**
|
|
20
|
-
*
|
|
17
|
+
* 计算一份文档在文档根内的相对路径。
|
|
21
18
|
*
|
|
22
19
|
* @param kind - 文档种类
|
|
23
20
|
* @param ids - 该种类需要的标识(designDoc 需要需求 id 与文档 id)
|
|
@@ -27,17 +24,17 @@ export function docPath(kind, ids) {
|
|
|
27
24
|
const id = requireId(ids.id);
|
|
28
25
|
switch (kind) {
|
|
29
26
|
case 'requirement':
|
|
30
|
-
return
|
|
27
|
+
return `requirements/${id}/requirement.md`;
|
|
31
28
|
case 'story':
|
|
32
|
-
return
|
|
29
|
+
return `stories/${id}/story.md`;
|
|
33
30
|
case 'bug':
|
|
34
|
-
return
|
|
31
|
+
return `bugs/${id}/bug.md`;
|
|
35
32
|
case 'designDoc':
|
|
36
|
-
return
|
|
33
|
+
return `requirements/${requireId(ids.requirementId)}/docs/${id}.md`;
|
|
37
34
|
}
|
|
38
35
|
}
|
|
39
36
|
/**
|
|
40
|
-
*
|
|
37
|
+
* 把相对路径拼到文档根上;只接受插件自己生成的、以 `/` 分隔的文档相对路径。
|
|
41
38
|
*
|
|
42
39
|
* 拒绝 POSIX 绝对路径、Windows 盘符/UNC/反斜杠路径与任何 `..`,最后再做一次
|
|
43
40
|
* 词法 containment 校验,确保结果仍落在 `root` 之内。
|
|
@@ -46,10 +43,10 @@ export function resolveDocPath(root, relative) {
|
|
|
46
43
|
if (relative.length === 0)
|
|
47
44
|
throw new Error('teamflow: document path is empty');
|
|
48
45
|
if (relative.includes('\0') || relative.includes('\\')) {
|
|
49
|
-
throw new Error(`teamflow: document path must be
|
|
46
|
+
throw new Error(`teamflow: document path must be relative to the document root, got "${relative}"`);
|
|
50
47
|
}
|
|
51
48
|
if (isAbsolute(relative) || win32.isAbsolute(relative) || /^[A-Za-z]:/.test(relative)) {
|
|
52
|
-
throw new Error(`teamflow: document path must be
|
|
49
|
+
throw new Error(`teamflow: document path must be relative to the document root, got "${relative}"`);
|
|
53
50
|
}
|
|
54
51
|
const segments = relative.split('/');
|
|
55
52
|
if (segments.some((part) => part === '..' || part === '.' || part.length === 0)) {
|
|
@@ -58,27 +55,23 @@ export function resolveDocPath(root, relative) {
|
|
|
58
55
|
const base = resolve(root);
|
|
59
56
|
const absolute = resolve(base, ...segments);
|
|
60
57
|
if (absolute !== base && !absolute.startsWith(`${base}${sep}`)) {
|
|
61
|
-
throw new Error(`teamflow: document path escapes the
|
|
58
|
+
throw new Error(`teamflow: document path escapes the document root, got "${relative}"`);
|
|
62
59
|
}
|
|
63
60
|
return absolute;
|
|
64
61
|
}
|
|
65
|
-
/**
|
|
62
|
+
/** 文档相对路径的展示形式(日志与工具结果用,始终 `/`)。 */
|
|
66
63
|
export function displayPath(relative) {
|
|
67
64
|
return relative.split(sep).join(posix.sep);
|
|
68
65
|
}
|
|
69
66
|
/**
|
|
70
|
-
*
|
|
71
|
-
*
|
|
67
|
+
* 首次为文档根准备共享目录:只建 `requirements/`、`stories/`、`bugs/`,
|
|
68
|
+
* 不碰工作区,也不写 `.gitignore`。
|
|
72
69
|
*
|
|
73
|
-
* @param root -
|
|
70
|
+
* @param root - 文档根目录(绝对路径)
|
|
74
71
|
* @returns 实际创建的目录(相对路径),便于工具结果里说明
|
|
75
72
|
*/
|
|
76
73
|
export function ensureDocTree(root) {
|
|
77
|
-
const dirs = [
|
|
78
|
-
`${DOC_ROOT}/requirements`,
|
|
79
|
-
`${DOC_ROOT}/stories`,
|
|
80
|
-
`${DOC_ROOT}/bugs`,
|
|
81
|
-
];
|
|
74
|
+
const dirs = ['requirements', 'stories', 'bugs'];
|
|
82
75
|
const created = [];
|
|
83
76
|
for (const dir of dirs) {
|
|
84
77
|
const absolute = resolveDocPath(root, dir);
|
|
@@ -87,11 +80,6 @@ export function ensureDocTree(root) {
|
|
|
87
80
|
created.push(dir);
|
|
88
81
|
}
|
|
89
82
|
}
|
|
90
|
-
const localIgnore = resolveDocPath(root, `${DOC_ROOT}/.gitignore`);
|
|
91
|
-
if (!existsSync(localIgnore)) {
|
|
92
|
-
writeFileSync(localIgnore, '*\n', 'utf8');
|
|
93
|
-
}
|
|
94
|
-
appendWorkspaceGitignore(root);
|
|
95
83
|
return created;
|
|
96
84
|
}
|
|
97
85
|
/**
|
|
@@ -144,8 +132,8 @@ let stagedSequence = 0;
|
|
|
144
132
|
* 到临时名,再在 SQLite 事务里删记录:事务失败就把文件改回来,事务成功才真正
|
|
145
133
|
* `unlink`。这样任何时刻都不会出现「记录已经没了、正式路径上的文件还在」的悬挂态。
|
|
146
134
|
*
|
|
147
|
-
* @param root -
|
|
148
|
-
* @param relative -
|
|
135
|
+
* @param root - 文档根目录
|
|
136
|
+
* @param relative - 文档相对路径
|
|
149
137
|
* @returns 暂存信息;文件本来就不存在时返回 `null`
|
|
150
138
|
*/
|
|
151
139
|
export function stageDocDeletion(root, relative) {
|
|
@@ -182,10 +170,10 @@ export function dropStagedDoc(staged) {
|
|
|
182
170
|
* 只删空目录:目录里还有别的东西时立刻停下,避免误删用户手工放进来的文件。
|
|
183
171
|
*/
|
|
184
172
|
export function pruneEmptyDirectories(root, relative) {
|
|
185
|
-
const boundary =
|
|
173
|
+
const boundary = resolve(root);
|
|
186
174
|
let directory = dirname(resolveDocPath(root, relative));
|
|
187
175
|
// Stop before the shared `requirements/`, `stories/`, `bugs/` roots: those
|
|
188
|
-
// belong to the
|
|
176
|
+
// belong to the document tree, not to the record being deleted.
|
|
189
177
|
while (directory !== boundary && dirname(directory) !== boundary && directory.startsWith(`${boundary}${sep}`)) {
|
|
190
178
|
try {
|
|
191
179
|
if (readdirSync(directory).length > 0)
|
|
@@ -211,18 +199,3 @@ function requireId(id) {
|
|
|
211
199
|
}
|
|
212
200
|
return id;
|
|
213
201
|
}
|
|
214
|
-
/** 把 `.xirang-ai/` 追加到工作区 `.gitignore`;没有该文件就创建一个只含这一行的。 */
|
|
215
|
-
function appendWorkspaceGitignore(root) {
|
|
216
|
-
const ignore = join(root, '.gitignore');
|
|
217
|
-
const entry = '.xirang-ai/';
|
|
218
|
-
if (!existsSync(ignore)) {
|
|
219
|
-
writeFileSync(ignore, `${entry}\n`, 'utf8');
|
|
220
|
-
return;
|
|
221
|
-
}
|
|
222
|
-
const current = readFileSync(ignore, 'utf8');
|
|
223
|
-
const lines = current.split('\n').map((line) => line.trim());
|
|
224
|
-
if (lines.includes(entry) || lines.includes('.xirang-ai'))
|
|
225
|
-
return;
|
|
226
|
-
const suffix = current.endsWith('\n') || current.length === 0 ? '' : '\n';
|
|
227
|
-
writeFileSync(ignore, `${current}${suffix}${entry}\n`, 'utf8');
|
|
228
|
-
}
|
package/lib/store/model.d.ts
CHANGED
|
@@ -198,6 +198,27 @@ export interface RequirementSession {
|
|
|
198
198
|
readonly linkedAt: string | null;
|
|
199
199
|
readonly createdAt: string;
|
|
200
200
|
}
|
|
201
|
+
/** Which kind of record a discussion conversation belongs to. */
|
|
202
|
+
export declare const DISCUSSION_SUBJECT_TYPES: readonly ["requirement", "story", "bug"];
|
|
203
|
+
export type DiscussionSubjectType = (typeof DISCUSSION_SUBJECT_TYPES)[number];
|
|
204
|
+
/** Discussion kind used by stories and defects; requirements keep their own kinds. */
|
|
205
|
+
export declare const GENERAL_DISCUSSION_KIND = "discuss";
|
|
206
|
+
/**
|
|
207
|
+
* One conversation registered against a requirement, story or defect.
|
|
208
|
+
*
|
|
209
|
+
* Rows start unconfirmed (`linkedAt` null) when the browser prepares a
|
|
210
|
+
* discussion and become visible once the Agent confirms with `linkedAt`.
|
|
211
|
+
*/
|
|
212
|
+
export interface DiscussionSession {
|
|
213
|
+
readonly subjectType: DiscussionSubjectType;
|
|
214
|
+
readonly subjectId: string;
|
|
215
|
+
readonly sessionId: string;
|
|
216
|
+
/** `create` / `design` / `detail` / `split` for requirements, `discuss` otherwise. */
|
|
217
|
+
readonly kind: string;
|
|
218
|
+
readonly preparedAt: string | null;
|
|
219
|
+
readonly linkedAt: string | null;
|
|
220
|
+
readonly createdAt: string;
|
|
221
|
+
}
|
|
201
222
|
/**
|
|
202
223
|
* One consistent read of every table the workbench renders.
|
|
203
224
|
*
|
|
@@ -214,6 +235,8 @@ export interface BoardRows {
|
|
|
214
235
|
readonly docStories: readonly DocStoryLink[];
|
|
215
236
|
/** Requirement conversations, newest first; design rows may still be unconfirmed. */
|
|
216
237
|
readonly requirementSessions: readonly RequirementSession[];
|
|
238
|
+
/** Confirmed story and defect discussions, newest first. */
|
|
239
|
+
readonly discussionSessions: readonly DiscussionSession[];
|
|
217
240
|
}
|
|
218
241
|
/** Input for {@link WorkflowStore.createDesignDoc}. */
|
|
219
242
|
export interface CreateDesignDocInput {
|
|
@@ -348,18 +371,19 @@ export interface RunFilter {
|
|
|
348
371
|
/**
|
|
349
372
|
* Record types the workbench can physically delete.
|
|
350
373
|
*
|
|
351
|
-
*
|
|
352
|
-
*
|
|
353
|
-
*
|
|
374
|
+
* A detailed-design document (`design_doc`) is deletable on its own as well as
|
|
375
|
+
* through its requirement: rewriting a document from scratch starts by removing
|
|
376
|
+
* the old one, and only then does a fresh document make sense. Deleting one
|
|
377
|
+
* removes its `design_doc_stories` coverage links with it.
|
|
354
378
|
*/
|
|
355
|
-
export declare const DELETABLE_KINDS: readonly ["bug", "story", "requirement"];
|
|
379
|
+
export declare const DELETABLE_KINDS: readonly ["bug", "story", "requirement", "design_doc"];
|
|
356
380
|
export type DeletableKind = (typeof DELETABLE_KINDS)[number];
|
|
357
381
|
/** One record the user asked to delete. */
|
|
358
382
|
export interface DeleteTarget {
|
|
359
383
|
readonly kind: DeletableKind;
|
|
360
384
|
readonly id: string;
|
|
361
385
|
}
|
|
362
|
-
/** A detailed-design document that will be deleted
|
|
386
|
+
/** A detailed-design document that will be deleted with its requirement. */
|
|
363
387
|
export interface DeleteDocRef {
|
|
364
388
|
readonly id: string;
|
|
365
389
|
readonly title: string;
|
|
@@ -383,6 +407,7 @@ export interface DeletePreviewItem {
|
|
|
383
407
|
readonly id: string;
|
|
384
408
|
readonly found: boolean;
|
|
385
409
|
readonly title: string;
|
|
410
|
+
/** Record status; a detailed design reports the status of its requirement. */
|
|
386
411
|
readonly status: string;
|
|
387
412
|
readonly workspaceId: string;
|
|
388
413
|
readonly deletable: boolean;
|
|
@@ -416,6 +441,8 @@ export interface DeleteOutcome {
|
|
|
416
441
|
readonly title: string;
|
|
417
442
|
readonly ok: boolean;
|
|
418
443
|
readonly removedDocs: number;
|
|
444
|
+
/** `design_doc_stories` links removed with a detailed design; 0 otherwise. */
|
|
445
|
+
readonly removedLinks: number;
|
|
419
446
|
readonly removedRuns: number;
|
|
420
447
|
readonly error: {
|
|
421
448
|
readonly code: string;
|
package/lib/store/model.js
CHANGED
|
@@ -41,6 +41,10 @@ export const BUG_SEVERITIES = ['blocker', 'critical', 'major', 'minor', 'trivial
|
|
|
41
41
|
export const DOC_KINDS = ['flow', 'data', 'interface', 'page', 'rule'];
|
|
42
42
|
/** Why a requirement is linked to a conversation. */
|
|
43
43
|
export const REQUIREMENT_SESSION_KINDS = ['create', 'design', 'detail', 'split'];
|
|
44
|
+
/** Which kind of record a discussion conversation belongs to. */
|
|
45
|
+
export const DISCUSSION_SUBJECT_TYPES = ['requirement', 'story', 'bug'];
|
|
46
|
+
/** Discussion kind used by stories and defects; requirements keep their own kinds. */
|
|
47
|
+
export const GENERAL_DISCUSSION_KIND = 'discuss';
|
|
44
48
|
/** A rejected domain operation, separate from SQLite or Host failures. */
|
|
45
49
|
export class WorkflowError extends Error {
|
|
46
50
|
/** Machine-readable reason for tools and the Web UI. */
|
|
@@ -59,8 +63,9 @@ export class WorkflowError extends Error {
|
|
|
59
63
|
/**
|
|
60
64
|
* Record types the workbench can physically delete.
|
|
61
65
|
*
|
|
62
|
-
*
|
|
63
|
-
*
|
|
64
|
-
*
|
|
66
|
+
* A detailed-design document (`design_doc`) is deletable on its own as well as
|
|
67
|
+
* through its requirement: rewriting a document from scratch starts by removing
|
|
68
|
+
* the old one, and only then does a fresh document make sense. Deleting one
|
|
69
|
+
* removes its `design_doc_stories` coverage links with it.
|
|
65
70
|
*/
|
|
66
|
-
export const DELETABLE_KINDS = ['bug', 'story', 'requirement'];
|
|
71
|
+
export const DELETABLE_KINDS = ['bug', 'story', 'requirement', 'design_doc'];
|
package/lib/store/paths.d.ts
CHANGED
|
@@ -2,6 +2,8 @@
|
|
|
2
2
|
export declare const PLUGIN_HOME_SEGMENTS: readonly ["xirang-ai", "dsh-teamflow"];
|
|
3
3
|
/** Database file name inside the plugin data directory. */
|
|
4
4
|
export declare const DATABASE_FILENAME = "teamflow.sqlite";
|
|
5
|
+
/** Directory name of the markdown documents below the plugin data directory. */
|
|
6
|
+
export declare const DOCS_DIRNAME = "docs";
|
|
5
7
|
/** Human-readable directory of the durable data, e.g. `$DSH_HOME/xirang-ai/dsh-teamflow`. */
|
|
6
8
|
export declare function defaultDataDir(): string;
|
|
7
9
|
/**
|
|
@@ -13,6 +15,24 @@ export declare function defaultDataDir(): string;
|
|
|
13
15
|
* @returns the absolute data directory.
|
|
14
16
|
*/
|
|
15
17
|
export declare function resolveDataDir(configured?: string): string;
|
|
18
|
+
/** Default document root: `<dataDir>/docs`, next to the database. */
|
|
19
|
+
export declare function defaultDocsDir(dataDir: string): string;
|
|
20
|
+
/**
|
|
21
|
+
* Resolve the document root: an explicit `Config.docsDir` wins, otherwise
|
|
22
|
+
* `<dataDir>/docs`. Relative overrides resolve against the process working
|
|
23
|
+
* directory and `~/` is expanded, mirroring {@link resolveDataDir}.
|
|
24
|
+
*
|
|
25
|
+
* Validation is loud on purpose: a malformed override or a path that is
|
|
26
|
+
* already a file fails plugin load with the field name and the accepted forms
|
|
27
|
+
* instead of silently falling back to the default directory.
|
|
28
|
+
*
|
|
29
|
+
* @param configured - `Config.docsDir`, possibly empty.
|
|
30
|
+
* @param dataDir - the resolved data directory.
|
|
31
|
+
* @returns the absolute document root.
|
|
32
|
+
*/
|
|
33
|
+
export declare function resolveDocsDir(configured: string | undefined, dataDir: string): string;
|
|
34
|
+
/** Create the document root (owner-only) and return it. */
|
|
35
|
+
export declare function ensureDocsDir(docsDir: string): string;
|
|
16
36
|
/** Absolute database file path for a resolved data directory. */
|
|
17
37
|
export declare function databaseFile(dataDir: string): string;
|
|
18
38
|
/** Create the data directory (owner-only) and return it. */
|