@foggy-projects/deepseek-harness-plugin 0.4.2-rc.5 → 0.4.4-rc.1

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 (52) hide show
  1. package/README.md +222 -185
  2. package/THIRD-PARTY-RUNTIME-NOTICES.md +16 -16
  3. package/cordis.patch.yml +6 -6
  4. package/docs/COMMUNITY-MARKETPLACES.md +64 -64
  5. package/docs/PUBLIC-BETA-READINESS.md +109 -109
  6. package/docs/RELEASE-CANDIDATE-0.4.0-RC.2.md +38 -38
  7. package/docs/RELEASE-CANDIDATE-0.4.0-RC.3.md +18 -18
  8. package/docs/RELEASE-CANDIDATE-0.4.1-DSH-0.1.5-RC.1.md +60 -60
  9. package/docs/RELEASE-CANDIDATE-0.4.2-DSH-0.1.7-RC.1.md +62 -62
  10. package/docs/RELEASE-CANDIDATE-0.4.2-DSH-0.1.7-RC.2.md +50 -50
  11. package/docs/RELEASE-CANDIDATE-0.4.2-DSH-0.1.7-RC.3.md +34 -34
  12. package/docs/RELEASE-CANDIDATE-0.4.2-DSH-0.1.7-RC.4.md +32 -32
  13. package/docs/RELEASE-CANDIDATE-0.4.2-DSH-0.1.7-RC.5.md +27 -27
  14. package/docs/RELEASE-CANDIDATE-0.4.3-DSH-0.2.0-RC.1.md +96 -0
  15. package/docs/RELEASE-CANDIDATE-0.4.4-DSH-0.2.1-RC.1.md +135 -0
  16. package/docs/WINDOWS-BETA-ACCEPTANCE.md +113 -113
  17. package/experience/linux/README.md +53 -53
  18. package/experience/linux/prepare.sh +2 -2
  19. package/lib/atomic-json.js +41 -41
  20. package/lib/client.js +1222 -1031
  21. package/lib/component-manager.js +164 -0
  22. package/lib/component-releases.js +363 -0
  23. package/lib/diagnostics.js +86 -86
  24. package/lib/index.js +764 -698
  25. package/lib/operation-lock.js +139 -0
  26. package/lib/python-runtime.js +339 -339
  27. package/lib/query-tool.js +134 -131
  28. package/lib/remote-descriptor.js +74 -59
  29. package/lib/remote.js +8 -8
  30. package/lib/runtime-settings.js +89 -89
  31. package/lib/skill-provider.js +116 -116
  32. package/lib/typert.js +9 -9
  33. package/lib/version.js +20 -20
  34. package/lib/viewer-preview.js +44 -27
  35. package/package.json +19 -16
  36. package/skills/foggy-deepseek-onboarding/SKILL.md +149 -143
  37. package/skills/foggy-deepseek-onboarding/assets/connection.schema.json +48 -48
  38. package/skills/foggy-deepseek-onboarding/assets/datasource.example.json +14 -14
  39. package/skills/foggy-deepseek-onboarding/assets/env.example +14 -14
  40. package/skills/foggy-deepseek-onboarding/assets/onboarding-state.schema.json +71 -71
  41. package/skills/foggy-deepseek-onboarding/assets/semantic-plan.example.json +8 -8
  42. package/skills/foggy-deepseek-onboarding/assets/semantic-plan.schema.json +21 -21
  43. package/skills/foggy-deepseek-onboarding/assets/versions.json +23 -23
  44. package/skills/foggy-deepseek-onboarding/references/onboarding-workflow.md +168 -168
  45. package/skills/foggy-deepseek-onboarding/scripts/doctor.ps1 +4 -4
  46. package/skills/foggy-deepseek-onboarding/scripts/install.ps1 +4 -4
  47. package/skills/foggy-deepseek-onboarding/scripts/invoke-onboarding.ps1 +32 -32
  48. package/skills/foggy-deepseek-onboarding/scripts/onboard.ps1 +4 -4
  49. package/skills/foggy-deepseek-onboarding/scripts/onboarding.py +3721 -3697
  50. package/skills/foggy-deepseek-onboarding/scripts/runtime-start.ps1 +4 -4
  51. package/skills/foggy-deepseek-onboarding/scripts/runtime-stop.ps1 +4 -4
  52. package/skills/foggy-deepseek-onboarding/scripts/uninstall.ps1 +4 -4
@@ -1,71 +1,71 @@
1
- {
2
- "$schema": "https://json-schema.org/draft/2020-12/schema",
3
- "$id": "https://foggy-projects.dev/schemas/deepseek-harness/onboarding-state.schema.json",
4
- "title": "Foggy DeepSeek Harness resumable onboarding state",
5
- "type": "object",
6
- "additionalProperties": false,
7
- "required": ["schemaVersion", "profile", "installRoot", "dataRoot", "projectRoot", "connection", "semantic", "steps", "artifacts"],
8
- "properties": {
9
- "schemaVersion": {"const": "foggy-deepseek-onboarding-state/v1"},
10
- "profile": {"type": "string", "pattern": "^[a-z0-9][a-z0-9._-]{0,62}$"},
11
- "createdAt": {"type": "string", "format": "date-time"},
12
- "updatedAt": {"type": "string", "format": "date-time"},
13
- "installRoot": {"type": "string"},
14
- "dataRoot": {"type": "string"},
15
- "projectRoot": {"type": "string"},
16
- "workspaceBindings": {
17
- "type": "array",
18
- "items": {"type": "string"},
19
- "uniqueItems": true
20
- },
21
- "workspaceVerifications": {
22
- "type": "array",
23
- "items": {
24
- "type": "object",
25
- "required": ["projectRoot", "queryModel", "queryPayloadDigest", "verifiedAt"],
26
- "properties": {
27
- "projectRoot": {"type": "string"},
28
- "queryModel": {"type": "string"},
29
- "queryPayloadDigest": {"type": "string", "pattern": "^[a-f0-9]{64}$"},
30
- "rowCount": {"type": ["integer", "null"], "minimum": 0},
31
- "warningCount": {"type": "integer", "minimum": 0},
32
- "warningCodes": {
33
- "type": "array",
34
- "items": {"type": "string"},
35
- "uniqueItems": true
36
- },
37
- "warningEvidence": {"type": ["string", "null"]},
38
- "verifiedAt": {"type": "string", "format": "date-time"}
39
- },
40
- "additionalProperties": false
41
- }
42
- },
43
- "runtime": {"type": "object"},
44
- "connection": {
45
- "type": "object",
46
- "additionalProperties": false,
47
- "required": ["schemaVersion", "connectionMode", "name", "type", "namespace"],
48
- "properties": {
49
- "schemaVersion": {"const": "foggy-deepseek-connection/v1"},
50
- "connectionMode": {"enum": ["legacy-inline", "opaque-profile"]},
51
- "credentialMode": {"enum": ["inline-development", "agent-environment", "opaque-profile", "none"]},
52
- "name": {"type": "string"},
53
- "type": {"type": "string"},
54
- "jdbcUrl": {"type": ["string", "null"]},
55
- "username": {"type": ["string", "null"]},
56
- "passwordEnv": {"type": ["string", "null"]},
57
- "opaqueProfileId": {"type": "string"},
58
- "opaqueRevision": {"type": "string"},
59
- "namespace": {"type": "string"},
60
- "schemas": {"type": "array", "items": {"type": "string"}},
61
- "modelsDir": {"type": "string"},
62
- "readOnlyRecommended": {"type": "boolean"},
63
- "profile": {"type": "string"},
64
- "evidenceDir": {"type": "string"}
65
- }
66
- },
67
- "semantic": {"type": "object"},
68
- "steps": {"type": "object"},
69
- "artifacts": {"type": "object"}
70
- }
71
- }
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "https://foggy-projects.dev/schemas/deepseek-harness/onboarding-state.schema.json",
4
+ "title": "Foggy DeepSeek Harness resumable onboarding state",
5
+ "type": "object",
6
+ "additionalProperties": false,
7
+ "required": ["schemaVersion", "profile", "installRoot", "dataRoot", "projectRoot", "connection", "semantic", "steps", "artifacts"],
8
+ "properties": {
9
+ "schemaVersion": {"const": "foggy-deepseek-onboarding-state/v1"},
10
+ "profile": {"type": "string", "pattern": "^[a-z0-9][a-z0-9._-]{0,62}$"},
11
+ "createdAt": {"type": "string", "format": "date-time"},
12
+ "updatedAt": {"type": "string", "format": "date-time"},
13
+ "installRoot": {"type": "string"},
14
+ "dataRoot": {"type": "string"},
15
+ "projectRoot": {"type": "string"},
16
+ "workspaceBindings": {
17
+ "type": "array",
18
+ "items": {"type": "string"},
19
+ "uniqueItems": true
20
+ },
21
+ "workspaceVerifications": {
22
+ "type": "array",
23
+ "items": {
24
+ "type": "object",
25
+ "required": ["projectRoot", "queryModel", "queryPayloadDigest", "verifiedAt"],
26
+ "properties": {
27
+ "projectRoot": {"type": "string"},
28
+ "queryModel": {"type": "string"},
29
+ "queryPayloadDigest": {"type": "string", "pattern": "^[a-f0-9]{64}$"},
30
+ "rowCount": {"type": ["integer", "null"], "minimum": 0},
31
+ "warningCount": {"type": "integer", "minimum": 0},
32
+ "warningCodes": {
33
+ "type": "array",
34
+ "items": {"type": "string"},
35
+ "uniqueItems": true
36
+ },
37
+ "warningEvidence": {"type": ["string", "null"]},
38
+ "verifiedAt": {"type": "string", "format": "date-time"}
39
+ },
40
+ "additionalProperties": false
41
+ }
42
+ },
43
+ "runtime": {"type": "object"},
44
+ "connection": {
45
+ "type": "object",
46
+ "additionalProperties": false,
47
+ "required": ["schemaVersion", "connectionMode", "name", "type", "namespace"],
48
+ "properties": {
49
+ "schemaVersion": {"const": "foggy-deepseek-connection/v1"},
50
+ "connectionMode": {"enum": ["legacy-inline", "opaque-profile"]},
51
+ "credentialMode": {"enum": ["inline-development", "agent-environment", "opaque-profile", "none"]},
52
+ "name": {"type": "string"},
53
+ "type": {"type": "string"},
54
+ "jdbcUrl": {"type": ["string", "null"]},
55
+ "username": {"type": ["string", "null"]},
56
+ "passwordEnv": {"type": ["string", "null"]},
57
+ "opaqueProfileId": {"type": "string"},
58
+ "opaqueRevision": {"type": "string"},
59
+ "namespace": {"type": "string"},
60
+ "schemas": {"type": "array", "items": {"type": "string"}},
61
+ "modelsDir": {"type": "string"},
62
+ "readOnlyRecommended": {"type": "boolean"},
63
+ "profile": {"type": "string"},
64
+ "evidenceDir": {"type": "string"}
65
+ }
66
+ },
67
+ "semantic": {"type": "object"},
68
+ "steps": {"type": "object"},
69
+ "artifacts": {"type": "object"}
70
+ }
71
+ }
@@ -1,8 +1,8 @@
1
- {
2
- "schemaVersion": "foggy-deepseek-semantic-plan/v1",
3
- "profile": "business",
4
- "draftDir": ".foggy/onboarding-drafts/business",
5
- "bundleName": "business-semantic",
6
- "evidenceDir": ".foggy/onboarding-command-evidence/business",
7
- "queryModels": ["FactOrderQueryModel"]
8
- }
1
+ {
2
+ "schemaVersion": "foggy-deepseek-semantic-plan/v1",
3
+ "profile": "business",
4
+ "draftDir": ".foggy/onboarding-drafts/business",
5
+ "bundleName": "business-semantic",
6
+ "evidenceDir": ".foggy/onboarding-command-evidence/business",
7
+ "queryModels": ["FactOrderQueryModel"]
8
+ }
@@ -1,21 +1,21 @@
1
- {
2
- "$schema": "https://json-schema.org/draft/2020-12/schema",
3
- "$id": "https://foggy-projects.dev/schemas/deepseek-harness/semantic-plan.schema.json",
4
- "title": "Foggy DeepSeek Harness semantic draft plan",
5
- "type": "object",
6
- "additionalProperties": false,
7
- "required": ["schemaVersion", "draftDir", "bundleName", "queryModels"],
8
- "properties": {
9
- "schemaVersion": {"const": "foggy-deepseek-semantic-plan/v1"},
10
- "profile": {"type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*$"},
11
- "draftDir": {"type": "string", "minLength": 1},
12
- "bundleName": {"type": "string", "minLength": 1},
13
- "evidenceDir": {"type": "string", "minLength": 1},
14
- "queryModels": {
15
- "type": "array",
16
- "minItems": 1,
17
- "uniqueItems": true,
18
- "items": {"type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]{0,127}$"}
19
- }
20
- }
21
- }
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "https://foggy-projects.dev/schemas/deepseek-harness/semantic-plan.schema.json",
4
+ "title": "Foggy DeepSeek Harness semantic draft plan",
5
+ "type": "object",
6
+ "additionalProperties": false,
7
+ "required": ["schemaVersion", "draftDir", "bundleName", "queryModels"],
8
+ "properties": {
9
+ "schemaVersion": {"const": "foggy-deepseek-semantic-plan/v1"},
10
+ "profile": {"type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*$"},
11
+ "draftDir": {"type": "string", "minLength": 1},
12
+ "bundleName": {"type": "string", "minLength": 1},
13
+ "evidenceDir": {"type": "string", "minLength": 1},
14
+ "queryModels": {
15
+ "type": "array",
16
+ "minItems": 1,
17
+ "uniqueItems": true,
18
+ "items": {"type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]{0,127}$"}
19
+ }
20
+ }
21
+ }
@@ -1,10 +1,10 @@
1
1
  {
2
2
  "schemaVersion": "foggy-deepseek-onboarding-versions/v1",
3
- "packageVersion": "0.4.2-rc.5",
4
- "validatedAt": "2026-09-28",
3
+ "packageVersion": "0.4.4-rc.1",
4
+ "validatedAt": "2026-10-27",
5
5
  "components": {
6
6
  "deepseekHarness": {
7
- "version": "0.1.7-rc.2",
7
+ "version": "0.2.1-rc.2",
8
8
  "minimumNodeVersion": "24.0.0"
9
9
  },
10
10
  "python": {
@@ -52,53 +52,53 @@
52
52
  }
53
53
  },
54
54
  "cli": {
55
- "version": "0.1.23",
55
+ "version": "0.1.25",
56
56
  "minimumPythonVersion": "3.11.0",
57
57
  "wheel": {
58
- "file": "foggy_runtime_cli-0.1.23-py3-none-any.whl",
59
- "url": "https://github.com/foggy-projects/foggy-runtime-cli/releases/download/v0.1.23/foggy_runtime_cli-0.1.23-py3-none-any.whl",
60
- "sha256": "db428812039e5961db93b5c0dc35b53a21d5c349428e6830c96fbf3218cf8a45"
58
+ "file": "foggy_runtime_cli-0.1.25-py3-none-any.whl",
59
+ "url": "https://github.com/foggy-projects/foggy-runtime-cli/releases/download/v0.1.25/foggy_runtime_cli-0.1.25-py3-none-any.whl",
60
+ "sha256": "162a0b50d2035132bf679b262fcf5f33ba7b50a462bda28a7def7705323ee0ac"
61
61
  },
62
62
  "checksums": {
63
63
  "file": "SHA256SUMS",
64
- "url": "https://github.com/foggy-projects/foggy-runtime-cli/releases/download/v0.1.23/SHA256SUMS",
65
- "sha256": "1494d7f13af18bef321995509058a1ab43b1d0b2e9f9ea08230dd78028090221"
64
+ "url": "https://github.com/foggy-projects/foggy-runtime-cli/releases/download/v0.1.25/SHA256SUMS",
65
+ "sha256": "cdf5230dd3c6ed6a1cf14b0a8fcbd3a2e004bc305fb6aeb596a16ff970b6b6ac"
66
66
  }
67
67
  },
68
68
  "launcher": {
69
- "version": "0.1.23",
69
+ "version": "0.1.46",
70
70
  "minimumJavaVersion": "17.0.0",
71
71
  "runtimeApiContract": "foggy-runtime-api/v1",
72
72
  "assets": [
73
73
  {
74
- "file": "foggy-runtime-launcher-0.1.23.jar",
75
- "url": "https://github.com/foggy-projects/foggy-data-mcp-bridge/releases/download/foggy-runtime-launcher-v0.1.23/foggy-runtime-launcher-0.1.23.jar",
76
- "sha256": "e3575c51e457d6b88740ef5949d7e206d5d6046d960fc8ef0884765bf3be8c66"
74
+ "file": "foggy-runtime-launcher-0.1.46.jar",
75
+ "url": "https://github.com/foggy-projects/foggy-data-mcp-bridge/releases/download/foggy-runtime-launcher-v0.1.46/foggy-runtime-launcher-0.1.46.jar",
76
+ "sha256": "f85e56115621cd73ac554e963b00fa46f4ebb30b9b4f5f7de9f56307f1d13ce8"
77
77
  },
78
78
  {
79
79
  "file": "start-foggy-runtime.ps1",
80
- "url": "https://github.com/foggy-projects/foggy-data-mcp-bridge/releases/download/foggy-runtime-launcher-v0.1.23/start-foggy-runtime.ps1",
81
- "sha256": "e6e2ac995a2a84c3de53878e8e0db4d701eab8b3a7ca6dbe9d4fb4ad15b00ae4"
80
+ "url": "https://github.com/foggy-projects/foggy-data-mcp-bridge/releases/download/foggy-runtime-launcher-v0.1.46/start-foggy-runtime.ps1",
81
+ "sha256": "f3fc068c8a630864f0b0e7c2f79d485511d35420c6bde9983b5dfacfe664da71"
82
82
  },
83
83
  {
84
84
  "file": "start-foggy-runtime.sh",
85
- "url": "https://github.com/foggy-projects/foggy-data-mcp-bridge/releases/download/foggy-runtime-launcher-v0.1.23/start-foggy-runtime.sh",
86
- "sha256": "562ef5614e02c4635c21d5fa9d6c2edc0dfb69d8da0ae57c4247c0c8202d50ae"
85
+ "url": "https://github.com/foggy-projects/foggy-data-mcp-bridge/releases/download/foggy-runtime-launcher-v0.1.46/start-foggy-runtime.sh",
86
+ "sha256": "6b171f29b24b3d767cc7b7f8dcd46fa28a9539a535ad6122edbf08692f6faf20"
87
87
  },
88
88
  {
89
89
  "file": "README-foggy-runtime-launcher.md",
90
- "url": "https://github.com/foggy-projects/foggy-data-mcp-bridge/releases/download/foggy-runtime-launcher-v0.1.23/README-foggy-runtime-launcher.md",
91
- "sha256": "759e3be46eb97a8f62b7ffb1dc5a977c52d0b91d1d31860e4e799125ce25e376"
90
+ "url": "https://github.com/foggy-projects/foggy-data-mcp-bridge/releases/download/foggy-runtime-launcher-v0.1.46/README-foggy-runtime-launcher.md",
91
+ "sha256": "f6be4d2d68da99bbc6c48f6487c0a242a986ec93525e937b5a589f59a7946155"
92
92
  },
93
93
  {
94
94
  "file": "runtime-launcher-manifest.json",
95
- "url": "https://github.com/foggy-projects/foggy-data-mcp-bridge/releases/download/foggy-runtime-launcher-v0.1.23/runtime-launcher-manifest.json",
96
- "sha256": "d25a9a0026495fd47e6ca03c957bf9999df9cffe73c6d6b0fc5c7dfc3931d317"
95
+ "url": "https://github.com/foggy-projects/foggy-data-mcp-bridge/releases/download/foggy-runtime-launcher-v0.1.46/runtime-launcher-manifest.json",
96
+ "sha256": "5cbc9dc1db51c707b5df2a5db59298ae1382d6626cbfb4af069c1874d6d70ba7"
97
97
  },
98
98
  {
99
99
  "file": "SHA256SUMS",
100
- "url": "https://github.com/foggy-projects/foggy-data-mcp-bridge/releases/download/foggy-runtime-launcher-v0.1.23/SHA256SUMS",
101
- "sha256": "49354e281c9f854651074b292aa003710334ae2f5494b3c07eafddf1d08a7dac"
100
+ "url": "https://github.com/foggy-projects/foggy-data-mcp-bridge/releases/download/foggy-runtime-launcher-v0.1.46/SHA256SUMS",
101
+ "sha256": "e4969a9d47b1a6791def06e0818ec2a92810323b76ad8e9da1cd4d844513016d"
102
102
  }
103
103
  ]
104
104
  },
@@ -1,168 +1,168 @@
1
- # Development datasource and semantic-model workflow
2
-
3
- Use this workflow after the Foggy plugin is initialized. It is designed for local experience and
4
- model development in DeepSeek Harness, not for production deployment.
5
-
6
- ## Connection input
7
-
8
- The simplest local connection contract may contain a direct password:
9
-
10
- ```json
11
- {
12
- "schemaVersion": "foggy-deepseek-connection/v1",
13
- "profile": "business",
14
- "name": "business-db",
15
- "type": "mysql",
16
- "jdbcUrl": "jdbc:mysql://127.0.0.1:3306/business",
17
- "username": "business_dev",
18
- "password": "local-development-password",
19
- "namespace": "business",
20
- "modelsDir": "models",
21
- "evidenceDir": ".foggy/onboarding-command-evidence/business"
22
- }
23
- ```
24
-
25
- The wrapper uses the direct password only while submitting the datasource to the public Runtime API.
26
- It does not copy it into onboarding state, command evidence, TM/QM files, or conversational output.
27
- The source connection file is user-managed; do not commit it. The local Runtime currently stores a
28
- direct password in its private datasource registry, so use `passwordRef`-style production credential
29
- management when moving beyond local development.
30
-
31
- An environment variable is an optional alternative:
32
-
33
- ```json
34
- {
35
- "schemaVersion": "foggy-deepseek-connection/v1",
36
- "profile": "business",
37
- "name": "business-db",
38
- "type": "mysql",
39
- "jdbcUrl": "jdbc:mysql://127.0.0.1:3306/business",
40
- "username": "business_dev",
41
- "passwordEnv": "FOGGY_BUSINESS_DB_PASSWORD",
42
- "namespace": "business",
43
- "modelsDir": "models"
44
- }
45
- ```
46
-
47
- Here `passwordEnv` is read by the onboarding wrapper and submitted online to the already-running
48
- Runtime. Do not restart Runtime merely to make the variable part of the Java process environment.
49
- Opaque CLI profiles remain supported for users who already prefer them, but are not required for a
50
- normal DSH experience.
51
-
52
- ## Normal sequence
53
-
54
- Run the platform-specific wrapper from this Skill directory. `onboard-datasource-run` performs the
55
- online datasource setup, namespace binding, and schema discovery against the healthy Runtime:
56
-
57
- ```text
58
- onboard-datasource-run --project-root <current-workspace> \
59
- --connection-file <connection-json> \
60
- --approve-configure --approve-bind --include-indexes
61
- ```
62
-
63
- If the user already requested the complete connection experience, include both approval flags in the
64
- first call. They refer only to adding the named development datasource and binding the requested
65
- namespace. Do not add `--replace` unless replacement was explicitly requested.
66
-
67
- The command performs:
68
-
69
- ```text
70
- datasource add -> datasource test -> namespace bind -> diagnostics
71
- tables list -> bounded schema inspection
72
- ```
73
-
74
- It does not stop or restart Runtime. Repeated calls reuse completed checkpoints when the public
75
- connection contract is unchanged. Before reusing a datasource checkpoint, the wrapper verifies that
76
- the named datasource still exists with the expected public type in the live Runtime. If it was
77
- removed outside the wrapper, datasource configuration, verification, and schema discovery resume
78
- automatically from the first affected step. Inline password values are excluded from the comparison.
79
- Transient connection-pool readiness timeouts are retried a small, bounded number of times; invalid
80
- credentials, invalid URLs, and other configuration errors fail immediately.
81
-
82
- When the user's request clearly identifies a business subject or likely tables, add `--pattern` or
83
- one or more `--table` arguments so discovery remains focused. Do not enumerate CLI help, inspect the
84
- wrapper source, load unrelated examples, or fetch online documentation on the successful normal path.
85
- Keep full command payloads in the numbered evidence files and use only their concise result fields in
86
- the conversation.
87
-
88
- After discovery, use `foggy-ai-analysis` to create TM/QM drafts from actual tables, columns, keys,
89
- small read-only samples when useful, and the user's business questions. Keep the files in the current
90
- workspace, normally:
91
-
92
- ```text
93
- models/
94
- model/
95
- <Name>.tm
96
- query/
97
- <Name>QueryModel.qm
98
- ```
99
-
100
- Then run the semantic composite:
101
-
102
- ```text
103
- onboard-semantic-run --project-root <current-workspace> \
104
- --semantic-plan <semantic-json> \
105
- --query-payload <bounded-query-json> \
106
- --approve-validate --approve-publish --approve-execute
107
- ```
108
-
109
- For an explicitly requested end-to-end local experience, these flags may be used together. The command
110
- validates the model files, copies them to the approved model directory when needed, registers or
111
- updates the local Runtime Bundle, refreshes/describes the declared QueryModels, validates the bounded
112
- query, and executes it. It never means production publication.
113
-
114
- The composite result keeps `success=true` when the Runtime safely continues with warnings and exposes
115
- `warningCount`, `warningCodes`, and `warnings` to the Agent. The full Runtime responses remain in
116
- `query-validate.json` and `query-execute.json`. Read the structured warning facts rather than relying
117
- on free-text remediation alone: compare `path`, `suggestedNextAction`, `safeToAutoRepair`,
118
- `normalizedFragment`, `docsRef`, and `details.allowedProperties` with the described
119
- model, correct and revalidate when an equivalent supported query preserves the user's intent, or
120
- clearly report the degraded interpretation. The wrapper accepts Runtime 0.1.21
121
- `queryInputWarnings` and legacy `warnings` as separate warning kinds. In `IGNORE`, ordinary unknown
122
- properties continue without `queryInputWarnings`; in `STRICT`, the Runtime rejects the query with the
123
- complete violations. Protected and governance fields remain fail-closed in every mode.
124
-
125
- Use `--watch` only when the user wants the local Runtime to follow model-file edits. Use `--prune` or
126
- bundle replacement only when the user clearly asks for those changes.
127
-
128
- ## Iteration and troubleshooting
129
-
130
- The granular commands remain available when a specific stage needs repair:
131
-
132
- ```text
133
- onboard-plan --connection-file <json> --profile <profile>
134
- datasource-configure --profile <profile> [--apply]
135
- datasource-verify --profile <profile> [--bind]
136
- schema-discover --profile <profile> [--include-indexes]
137
- semantic-draft --profile <profile> --semantic-plan <json>
138
- semantic-validate --profile <profile> [--apply]
139
- semantic-publish --profile <profile> [--apply]
140
- semantic-verify --profile <profile> --query-payload <json> [--execute]
141
- onboard-status --profile <profile>
142
- onboard-resume --profile <profile>
143
- ```
144
-
145
- A standalone `datasource-configure --apply` can resolve `passwordEnv` from its current Agent process.
146
- For a direct `password`, use the composite datasource command with the original connection file so the
147
- secret stays ephemeral to that invocation.
148
-
149
- When a failure occurs, repair only the failed input and rerun the same composite command. Do not remove
150
- a successfully registered Bundle merely because later query validation failed. Keep SQL samples small,
151
- read-only, and relevant to semantic authoring.
152
-
153
- ## Git handoff
154
-
155
- When validation and representative questions pass, recommend placing the model directory under the
156
- user's existing Git repository. Git is the source of truth for model history; Runtime Bundle
157
- registration only makes a selected local directory active. Do not create commits, remotes, tags, or
158
- pushes without the user's request.
159
-
160
- ## Production handoff
161
-
162
- Stop the local onboarding flow when the user asks to publish or update a formal environment. A separate
163
- manual or dedicated deployment workflow should collect the exact target, Launcher version, model Git
164
- commit/tag, namespace, production datasource procedure, access credentials, verification plan, and
165
- rollback point. It should then install/start Runtime if needed, prepare the target datasource, register
166
- the versioned model directory, refresh, and run a narrow smoke check.
167
-
168
- Local onboarding credentials and approvals do not authorize production access or publication.
1
+ # Development datasource and semantic-model workflow
2
+
3
+ Use this workflow after the Foggy plugin is initialized. It is designed for local experience and
4
+ model development in DeepSeek Harness, not for production deployment.
5
+
6
+ ## Connection input
7
+
8
+ The simplest local connection contract may contain a direct password:
9
+
10
+ ```json
11
+ {
12
+ "schemaVersion": "foggy-deepseek-connection/v1",
13
+ "profile": "business",
14
+ "name": "business-db",
15
+ "type": "mysql",
16
+ "jdbcUrl": "jdbc:mysql://127.0.0.1:3306/business",
17
+ "username": "business_dev",
18
+ "password": "local-development-password",
19
+ "namespace": "business",
20
+ "modelsDir": "models",
21
+ "evidenceDir": ".foggy/onboarding-command-evidence/business"
22
+ }
23
+ ```
24
+
25
+ The wrapper uses the direct password only while submitting the datasource to the public Runtime API.
26
+ It does not copy it into onboarding state, command evidence, TM/QM files, or conversational output.
27
+ The source connection file is user-managed; do not commit it. The local Runtime currently stores a
28
+ direct password in its private datasource registry, so use `passwordRef`-style production credential
29
+ management when moving beyond local development.
30
+
31
+ An environment variable is an optional alternative:
32
+
33
+ ```json
34
+ {
35
+ "schemaVersion": "foggy-deepseek-connection/v1",
36
+ "profile": "business",
37
+ "name": "business-db",
38
+ "type": "mysql",
39
+ "jdbcUrl": "jdbc:mysql://127.0.0.1:3306/business",
40
+ "username": "business_dev",
41
+ "passwordEnv": "FOGGY_BUSINESS_DB_PASSWORD",
42
+ "namespace": "business",
43
+ "modelsDir": "models"
44
+ }
45
+ ```
46
+
47
+ Here `passwordEnv` is read by the onboarding wrapper and submitted online to the already-running
48
+ Runtime. Do not restart Runtime merely to make the variable part of the Java process environment.
49
+ Opaque CLI profiles remain supported for users who already prefer them, but are not required for a
50
+ normal DSH experience.
51
+
52
+ ## Normal sequence
53
+
54
+ Run the platform-specific wrapper from this Skill directory. `onboard-datasource-run` performs the
55
+ online datasource setup, namespace binding, and schema discovery against the healthy Runtime:
56
+
57
+ ```text
58
+ onboard-datasource-run --project-root <current-workspace> \
59
+ --connection-file <connection-json> \
60
+ --approve-configure --approve-bind --include-indexes
61
+ ```
62
+
63
+ If the user already requested the complete connection experience, include both approval flags in the
64
+ first call. They refer only to adding the named development datasource and binding the requested
65
+ namespace. Do not add `--replace` unless replacement was explicitly requested.
66
+
67
+ The command performs:
68
+
69
+ ```text
70
+ datasource add -> datasource test -> namespace bind -> diagnostics
71
+ tables list -> bounded schema inspection
72
+ ```
73
+
74
+ It does not stop or restart Runtime. Repeated calls reuse completed checkpoints when the public
75
+ connection contract is unchanged. Before reusing a datasource checkpoint, the wrapper verifies that
76
+ the named datasource still exists with the expected public type in the live Runtime. If it was
77
+ removed outside the wrapper, datasource configuration, verification, and schema discovery resume
78
+ automatically from the first affected step. Inline password values are excluded from the comparison.
79
+ Transient connection-pool readiness timeouts are retried a small, bounded number of times; invalid
80
+ credentials, invalid URLs, and other configuration errors fail immediately.
81
+
82
+ When the user's request clearly identifies a business subject or likely tables, add `--pattern` or
83
+ one or more `--table` arguments so discovery remains focused. Do not enumerate CLI help, inspect the
84
+ wrapper source, load unrelated examples, or fetch online documentation on the successful normal path.
85
+ Keep full command payloads in the numbered evidence files and use only their concise result fields in
86
+ the conversation.
87
+
88
+ After discovery, use `foggy-ai-analysis` to create TM/QM drafts from actual tables, columns, keys,
89
+ small read-only samples when useful, and the user's business questions. Keep the files in the current
90
+ workspace, normally:
91
+
92
+ ```text
93
+ models/
94
+ model/
95
+ <Name>.tm
96
+ query/
97
+ <Name>QueryModel.qm
98
+ ```
99
+
100
+ Then run the semantic composite:
101
+
102
+ ```text
103
+ onboard-semantic-run --project-root <current-workspace> \
104
+ --semantic-plan <semantic-json> \
105
+ --query-payload <bounded-query-json> \
106
+ --approve-validate --approve-publish --approve-execute
107
+ ```
108
+
109
+ For an explicitly requested end-to-end local experience, these flags may be used together. The command
110
+ validates the model files, copies them to the approved model directory when needed, registers or
111
+ updates the local Runtime Bundle, refreshes/describes the declared QueryModels, validates the bounded
112
+ query, and executes it. It never means production publication.
113
+
114
+ The composite result keeps `success=true` when the Runtime safely continues with warnings and exposes
115
+ `warningCount`, `warningCodes`, and `warnings` to the Agent. The full Runtime responses remain in
116
+ `query-validate.json` and `query-execute.json`. Read the structured warning facts rather than relying
117
+ on free-text remediation alone: compare `path`, `suggestedNextAction`, `safeToAutoRepair`,
118
+ `normalizedFragment`, `docsRef`, and `details.allowedProperties` with the described
119
+ model, correct and revalidate when an equivalent supported query preserves the user's intent, or
120
+ clearly report the degraded interpretation. The wrapper accepts Runtime 0.1.21
121
+ `queryInputWarnings` and legacy `warnings` as separate warning kinds. In `IGNORE`, ordinary unknown
122
+ properties continue without `queryInputWarnings`; in `STRICT`, the Runtime rejects the query with the
123
+ complete violations. Protected and governance fields remain fail-closed in every mode.
124
+
125
+ Use `--watch` only when the user wants the local Runtime to follow model-file edits. Use `--prune` or
126
+ bundle replacement only when the user clearly asks for those changes.
127
+
128
+ ## Iteration and troubleshooting
129
+
130
+ The granular commands remain available when a specific stage needs repair:
131
+
132
+ ```text
133
+ onboard-plan --connection-file <json> --profile <profile>
134
+ datasource-configure --profile <profile> [--apply]
135
+ datasource-verify --profile <profile> [--bind]
136
+ schema-discover --profile <profile> [--include-indexes]
137
+ semantic-draft --profile <profile> --semantic-plan <json>
138
+ semantic-validate --profile <profile> [--apply]
139
+ semantic-publish --profile <profile> [--apply]
140
+ semantic-verify --profile <profile> --query-payload <json> [--execute]
141
+ onboard-status --profile <profile>
142
+ onboard-resume --profile <profile>
143
+ ```
144
+
145
+ A standalone `datasource-configure --apply` can resolve `passwordEnv` from its current Agent process.
146
+ For a direct `password`, use the composite datasource command with the original connection file so the
147
+ secret stays ephemeral to that invocation.
148
+
149
+ When a failure occurs, repair only the failed input and rerun the same composite command. Do not remove
150
+ a successfully registered Bundle merely because later query validation failed. Keep SQL samples small,
151
+ read-only, and relevant to semantic authoring.
152
+
153
+ ## Git handoff
154
+
155
+ When validation and representative questions pass, recommend placing the model directory under the
156
+ user's existing Git repository. Git is the source of truth for model history; Runtime Bundle
157
+ registration only makes a selected local directory active. Do not create commits, remotes, tags, or
158
+ pushes without the user's request.
159
+
160
+ ## Production handoff
161
+
162
+ Stop the local onboarding flow when the user asks to publish or update a formal environment. A separate
163
+ manual or dedicated deployment workflow should collect the exact target, Launcher version, model Git
164
+ commit/tag, namespace, production datasource procedure, access credentials, verification plan, and
165
+ rollback point. It should then install/start Runtime if needed, prepare the target datasource, register
166
+ the versioned model directory, refresh, and run a narrow smoke check.
167
+
168
+ Local onboarding credentials and approvals do not authorize production access or publication.