dsh-project-flow-explainer 0.0.0-stage → 0.6.0

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.
@@ -0,0 +1,158 @@
1
+ /**
2
+ * Input validation for the knowledge tools.
3
+ *
4
+ * The runtime validates the JSON schema before execute(); these checks are the
5
+ * second line of defence for a direct `execute()` call (tests, another plugin,
6
+ * a future caller). Every rejection carries a stable code and a hint, and none
7
+ * of them can surface a raw TypeError.
8
+ */
9
+ import { InputError } from './paths.js'
10
+
11
+ export function assertObject(args, toolName) {
12
+ if (args === undefined || args === null) {
13
+ throw new InputError('invalid_arguments',
14
+ `${toolName}: thiếu tham số (nhận được ${args === null ? 'null' : 'undefined'}).`,
15
+ 'Truyền object có repository_path và các trường bắt buộc.')
16
+ }
17
+ if (typeof args !== 'object' || Array.isArray(args)) {
18
+ throw new InputError('invalid_arguments',
19
+ `${toolName}: tham số phải là object, nhận được ${Array.isArray(args) ? 'array' : typeof args}.`,
20
+ 'Truyền object JSON.')
21
+ }
22
+ return args
23
+ }
24
+
25
+ /**
26
+ * Reject keys the tool does not declare.
27
+ *
28
+ * `ToolsService.register()` does not validate arguments, so the declared
29
+ * `additionalProperties: false` is not enforced by the runtime — only a caller
30
+ * built on `defineTool` gets that for free. This plugin builds its definitions
31
+ * by hand, so it enforces the same rule here. Unknown keys are a silent
32
+ * misconfiguration (a typo like `repositry_path` otherwise looks like a missing
33
+ * argument), so fail loudly with a stable code.
34
+ * @param {object} args - already asserted object.
35
+ * @param {string[]} allowed - declared parameter names.
36
+ * @param {string} toolName - tool name for the message.
37
+ * @returns {object} the same object.
38
+ */
39
+ export function rejectUnknownKeys(args, allowed, toolName) {
40
+ const unknown = Object.keys(args).filter((key) => !allowed.includes(key))
41
+ if (unknown.length > 0) {
42
+ throw new InputError('unknown_arguments',
43
+ `${toolName}: tham số không được khai báo: ${unknown.join(', ')}.`,
44
+ `Tham số hợp lệ: ${allowed.join(', ')}.`)
45
+ }
46
+ return args
47
+ }
48
+
49
+ export function requiredString(args, key, toolName, { allowEmpty = false } = {}) {
50
+ const value = args[key]
51
+ if (value === undefined || value === null) {
52
+ throw new InputError(`${key}_missing`, `${toolName}: thiếu ${key}.`,
53
+ `Truyền ${key} dạng chuỗi.`)
54
+ }
55
+ if (typeof value !== 'string') {
56
+ throw new InputError(`${key}_invalid_type`,
57
+ `${toolName}: ${key} phải là chuỗi, nhận được ${typeof value}.`,
58
+ `Truyền ${key} dạng chuỗi.`)
59
+ }
60
+ const trimmed = value.trim()
61
+ if (!allowEmpty && trimmed === '') {
62
+ throw new InputError(`${key}_missing`, `${toolName}: ${key} rỗng.`,
63
+ `Mô tả rõ nội dung cho ${key}.`)
64
+ }
65
+ return trimmed
66
+ }
67
+
68
+ export function optionalString(args, key, toolName) {
69
+ const value = args[key]
70
+ if (value === undefined || value === null) return undefined
71
+ if (typeof value !== 'string') {
72
+ throw new InputError(`${key}_invalid_type`,
73
+ `${toolName}: ${key} phải là chuỗi, nhận được ${typeof value}.`,
74
+ `Bỏ trống hoặc truyền ${key} dạng chuỗi.`)
75
+ }
76
+ return value
77
+ }
78
+
79
+ export function integerInRange(args, key, toolName, { min, max, fallback }) {
80
+ const value = args[key]
81
+ if (value === undefined || value === null) return fallback
82
+ if (typeof value !== 'number' || !Number.isFinite(value) || !Number.isInteger(value)) {
83
+ throw new InputError(`${key}_invalid_type`,
84
+ `${toolName}: ${key} phải là số nguyên, nhận được ${typeof value}.`,
85
+ `Truyền ${key} trong khoảng ${min}..${max}.`)
86
+ }
87
+ if (value < min || value > max) {
88
+ throw new InputError(`${key}_out_of_range`,
89
+ `${toolName}: ${key} phải trong khoảng ${min}..${max}, nhận được ${value}.`,
90
+ `Dùng giá trị trong khoảng ${min}..${max}.`)
91
+ }
92
+ return value
93
+ }
94
+
95
+ export function booleanFlag(args, key, toolName, fallback = false) {
96
+ const value = args[key]
97
+ if (value === undefined || value === null) return fallback
98
+ if (typeof value !== 'boolean') {
99
+ throw new InputError(`${key}_invalid_type`,
100
+ `${toolName}: ${key} phải là boolean, nhận được ${typeof value}.`,
101
+ `Truyền ${key} là true hoặc false.`)
102
+ }
103
+ return value
104
+ }
105
+
106
+ export function stringArray(args, key, toolName, { max = 200 } = {}) {
107
+ const value = args[key]
108
+ if (value === undefined || value === null) return []
109
+ if (!Array.isArray(value)) {
110
+ throw new InputError(`${key}_invalid_type`,
111
+ `${toolName}: ${key} phải là mảng chuỗi, nhận được ${typeof value}.`,
112
+ `Truyền ${key} là mảng đường dẫn tương đối.`)
113
+ }
114
+ if (value.length > max) {
115
+ throw new InputError(`${key}_too_many`,
116
+ `${toolName}: ${key} có ${value.length} phần tử, tối đa ${max}.`,
117
+ 'Chia nhỏ lần phân tích.')
118
+ }
119
+ return value.map((item) => {
120
+ if (typeof item !== 'string') {
121
+ throw new InputError(`${key}_invalid_type`,
122
+ `${toolName}: phần tử của ${key} phải là chuỗi.`,
123
+ 'Truyền đường dẫn tương đối trong repository.')
124
+ }
125
+ return item.trim()
126
+ }).filter(Boolean)
127
+ }
128
+
129
+ export function enumValue(args, key, toolName, allowed, fallback) {
130
+ const value = args[key]
131
+ if (value === undefined || value === null) return fallback
132
+ if (typeof value !== 'string' || !allowed.includes(value)) {
133
+ throw new InputError(`${key}_invalid`,
134
+ `${toolName}: ${key} phải là một trong ${allowed.join('|')}, nhận được ${String(value)}.`,
135
+ `Chọn ${allowed.join(' hoặc ')}.`)
136
+ }
137
+ return value
138
+ }
139
+
140
+ export function filtersObject(args, toolName) {
141
+ const value = args.filters
142
+ if (value === undefined || value === null) return {}
143
+ if (typeof value !== 'object' || Array.isArray(value)) {
144
+ throw new InputError('filters_invalid_type',
145
+ `${toolName}: filters phải là object.`,
146
+ 'Truyền filters: { language, kind, flow_id }.')
147
+ }
148
+ const output = {}
149
+ for (const key of ['language', 'kind', 'flow_id']) {
150
+ if (value[key] === undefined || value[key] === null) continue
151
+ if (typeof value[key] !== 'string') {
152
+ throw new InputError('filters_invalid_type',
153
+ `${toolName}: filters.${key} phải là chuỗi.`, 'Truyền chuỗi.')
154
+ }
155
+ output[key] = value[key]
156
+ }
157
+ return output
158
+ }
package/package.json CHANGED
@@ -1,6 +1,73 @@
1
1
  {
2
2
  "name": "dsh-project-flow-explainer",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.6.0",
4
+ "type": "module",
5
+ "description": "DSH adapter: expose the Project Flow Explainer core (scripts/build_flow.py + template) as one DSH tool. Ships the core under vendor/core so a packed install works without the checkout.",
6
+ "license": "MIT",
7
+ "author": "Hieupt1904",
8
+ "repository": {
9
+ "type": "git",
10
+ "url": "git+https://github.com/Hieupt1904/project-flow-explainer.git",
11
+ "directory": "dsh-plugin"
12
+ },
13
+ "homepage": "https://github.com/Hieupt1904/project-flow-explainer",
14
+ "bugs": {
15
+ "url": "https://github.com/Hieupt1904/project-flow-explainer/issues"
16
+ },
17
+ "keywords": [
18
+ "deepseek",
19
+ "harness",
20
+ "dsh",
21
+ "dsh-plugin",
22
+ "code-analysis",
23
+ "flow-diagram",
24
+ "codebase",
25
+ "offline-html",
26
+ "agent-tool"
27
+ ],
28
+ "main": "./index.js",
29
+ "exports": {
30
+ ".": "./index.js",
31
+ "./client": "./client.js",
32
+ "./package.json": "./package.json"
33
+ },
34
+ "files": [
35
+ "client.js",
36
+ "index.js",
37
+ "lib/",
38
+ "cordis.patch.yml",
39
+ "README.md",
40
+ "vendor/core/scripts/build_flow.py",
41
+ "vendor/core/scripts/render_flow.py",
42
+ "vendor/core/assets/workflow_template.html",
43
+ "vendor/core/tools/pfe_cli.py",
44
+ "vendor/core/pfe/"
45
+ ],
46
+ "engines": {
47
+ "node": ">=20",
48
+ "dsh": "0.2.2-rc.2"
49
+ },
50
+ "peerDependencies": {
51
+ "@deepseek-ai/schemastery": ">=3.18.5 <4"
52
+ },
53
+ "peerDependenciesMeta": {
54
+ "@deepseek-ai/schemastery": {
55
+ "optional": true
56
+ }
57
+ },
58
+ "dsh": {
59
+ "client": {
60
+ "platform": "web",
61
+ "inject": [
62
+ "@deepseek-ai/dsh-client-ui-slots"
63
+ ]
64
+ },
65
+ "bundle": {
66
+ "patch": "./cordis.patch.yml"
67
+ }
68
+ },
69
+ "scripts": {
70
+ "test": "node --test tests/plugin.test.mjs",
71
+ "pack:bundle": "node scripts/pack.mjs"
72
+ }
73
+ }