@foggy-projects/deepseek-harness-plugin 0.4.0-beta.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.
- package/LICENSE +201 -0
- package/README.md +34 -0
- package/cordis.patch.yml +6 -0
- package/experience/linux/README.md +54 -0
- package/experience/linux/prepare.sh +190 -0
- package/lib/client.js +254 -0
- package/lib/index.js +259 -0
- package/lib/remote-descriptor.js +29 -0
- package/lib/remote.js +8 -0
- package/lib/typert.js +9 -0
- package/lib/version.js +15 -0
- package/package.json +59 -0
- package/skills/foggy-deepseek-onboarding/SKILL.md +83 -0
- package/skills/foggy-deepseek-onboarding/assets/connection.schema.json +50 -0
- package/skills/foggy-deepseek-onboarding/assets/datasource.example.json +13 -0
- package/skills/foggy-deepseek-onboarding/assets/env.example +14 -0
- package/skills/foggy-deepseek-onboarding/assets/onboarding-state.schema.json +22 -0
- package/skills/foggy-deepseek-onboarding/assets/semantic-plan.example.json +8 -0
- package/skills/foggy-deepseek-onboarding/assets/semantic-plan.schema.json +21 -0
- package/skills/foggy-deepseek-onboarding/assets/versions.json +93 -0
- package/skills/foggy-deepseek-onboarding/references/onboarding-workflow.md +120 -0
- package/skills/foggy-deepseek-onboarding/scripts/doctor.ps1 +4 -0
- package/skills/foggy-deepseek-onboarding/scripts/doctor.sh +5 -0
- package/skills/foggy-deepseek-onboarding/scripts/install.ps1 +4 -0
- package/skills/foggy-deepseek-onboarding/scripts/install.sh +5 -0
- package/skills/foggy-deepseek-onboarding/scripts/onboard.ps1 +4 -0
- package/skills/foggy-deepseek-onboarding/scripts/onboard.sh +5 -0
- package/skills/foggy-deepseek-onboarding/scripts/onboarding.py +2113 -0
- package/skills/foggy-deepseek-onboarding/scripts/runtime-start.ps1 +4 -0
- package/skills/foggy-deepseek-onboarding/scripts/runtime-start.sh +5 -0
- package/skills/foggy-deepseek-onboarding/scripts/runtime-stop.ps1 +4 -0
- package/skills/foggy-deepseek-onboarding/scripts/runtime-stop.sh +5 -0
- package/skills/foggy-deepseek-onboarding/scripts/uninstall.ps1 +4 -0
- package/skills/foggy-deepseek-onboarding/scripts/uninstall.sh +5 -0
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: foggy-deepseek-onboarding
|
|
3
|
+
description: Install and operate a pinned Foggy CLI-first dev/test environment from DeepSeek Harness, including opaque datasource profiles, resumable verification, and schema discovery before semantic authoring. Use for initial Foggy setup or local Runtime onboarding; do not use for production deployment or MCP configuration.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Foggy DeepSeek onboarding
|
|
7
|
+
|
|
8
|
+
Set up Foggy through shell and `foggy-runtime` CLI. Do not configure Foggy MCP for this local workflow.
|
|
9
|
+
|
|
10
|
+
## Mandatory orchestration boundary
|
|
11
|
+
|
|
12
|
+
For every new-database onboarding session, this Skill is the orchestration authority until
|
|
13
|
+
`onboard-status` reports `next.status=completed`:
|
|
14
|
+
|
|
15
|
+
- Invoke datasource, schema, semantic, bundle, and query operations only through this Skill's
|
|
16
|
+
`scripts/onboard.ps1` or `scripts/onboard.sh`. Do not call `foggy-runtime` directly for those
|
|
17
|
+
operations, even if another loaded Skill documents equivalent CLI commands.
|
|
18
|
+
- Use `foggy-ai-analysis` only to author TM/QM draft content. Its general direct-CLI workflow does not
|
|
19
|
+
supersede this Skill's state machine, approval gates, names, paths, query limit, or evidence rules.
|
|
20
|
+
- Use the exact profile, datasource, namespace, bundle, model names, paths, fields, and query limit
|
|
21
|
+
supplied or confirmed by the user. Do not replace them with examples or inferred alternatives.
|
|
22
|
+
- Do not use raw SQL to sample business rows during onboarding. `schema-discover` is the metadata gate;
|
|
23
|
+
any later SQL probe requires separate explicit approval and must be bounded and read-only.
|
|
24
|
+
- Never use `--replace`, `--replace-bundle`, `--prune`, `--watch`, or `--execute` unless that exact
|
|
25
|
+
mutation was explicitly approved. Approval for adding a new resource is not approval to replace one.
|
|
26
|
+
- Save each wrapper result as the single JSON object returned on stdout when the user requests evidence.
|
|
27
|
+
Do not claim completion when required evidence is missing or the persisted status is incomplete.
|
|
28
|
+
- Never read query-execution evidence back into the conversation. Report only validation state,
|
|
29
|
+
execution state, row count, and evidence path; do not report row values or generated SQL containing
|
|
30
|
+
business literals.
|
|
31
|
+
|
|
32
|
+
## Boundaries
|
|
33
|
+
|
|
34
|
+
- Treat the bundled Launcher as local dev/test only. Its expected security mode is
|
|
35
|
+
`none-dev-test-only`; never expose it to a network.
|
|
36
|
+
- Do not print, persist, or request secrets in chat. Use named environment variables or a private env
|
|
37
|
+
file outside the Skill and evidence directories.
|
|
38
|
+
- Do not modify Foggy engine or CLI source. If setup cannot continue without such a change, stop and
|
|
39
|
+
ask the user for explicit authorization.
|
|
40
|
+
- Before downloads, installs, replacement, Runtime start/stop, or removal, state the concrete action
|
|
41
|
+
and obtain any authorization required by the host.
|
|
42
|
+
|
|
43
|
+
## Workflow
|
|
44
|
+
|
|
45
|
+
1. Run `scripts/doctor.ps1 --project-root <root>` on Windows or
|
|
46
|
+
`bash scripts/doctor.sh --project-root <root>` on Linux.
|
|
47
|
+
2. If the pinned CLI, Launcher, or analysis Skill is missing, run the matching `install` script. Use
|
|
48
|
+
`--dry-run` first when paths or permissions are uncertain.
|
|
49
|
+
3. Run `runtime-start` and require successful `wait-ready` plus `capabilities`. Record engine,
|
|
50
|
+
Runtime API version, schema version, security mode, URL, namespace, PID, and evidence path.
|
|
51
|
+
4. Confirm the project contains `.agents/skills/foggy-ai-analysis/SKILL.md`.
|
|
52
|
+
5. For a new business database, read [references/onboarding-workflow.md](references/onboarding-workflow.md)
|
|
53
|
+
and prefer its two composite `onboard-datasource-run` / `onboard-semantic-run` commands. Require the
|
|
54
|
+
trusted operator to create the private CLI profile outside Harness. Accept only the opaque profile
|
|
55
|
+
ID, exact revision, datasource name/type, and namespace; never request JDBC URL, username,
|
|
56
|
+
password, or password environment-variable name in Harness.
|
|
57
|
+
6. After schema discovery, use `foggy-ai-analysis` only to author TM/QM files in a separate project-local
|
|
58
|
+
draft directory. Register, validate, publish, and verify them through this Skill's wrapper using the deterministic commands in
|
|
59
|
+
[references/onboarding-workflow.md](references/onboarding-workflow.md). Do not publish, prune, replace
|
|
60
|
+
a bundle, or execute a business-data query without the matching explicit flag and user approval.
|
|
61
|
+
7. Stop only the Runtime PID recorded by this package. Preserve Runtime data unless the user explicitly
|
|
62
|
+
requests purge.
|
|
63
|
+
|
|
64
|
+
## Command contract
|
|
65
|
+
|
|
66
|
+
All package scripts return one JSON object on stdout. Treat `success=false` or a nonzero exit code as a
|
|
67
|
+
failure. Do not infer readiness from a fixed sleep; require CLI `wait-ready` and `capabilities`.
|
|
68
|
+
|
|
69
|
+
Use this analysis order after setup:
|
|
70
|
+
|
|
71
|
+
```text
|
|
72
|
+
datasource test -> bind -> diagnostics
|
|
73
|
+
tables list -> inspect -> optional bounded read-only SQL
|
|
74
|
+
models validate -> bundles add/update -> models refresh -> models describe
|
|
75
|
+
query validate -> query execute -> interpretation
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
In DeepSeek Harness, do not expand the composite onboarding commands back into these individual CLI
|
|
79
|
+
operations. This order documents what the wrapper enforces internally and becomes a direct CLI workflow
|
|
80
|
+
only after onboarding is complete.
|
|
81
|
+
|
|
82
|
+
Keep user business data separate from the sales-drop SQLite demo. Prefer a read-only database account,
|
|
83
|
+
opaque CLI profile references, and bounded query limits.
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
{
|
|
2
|
+
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
|
3
|
+
"$id": "https://foggy-projects.dev/schemas/deepseek-harness/connection.schema.json",
|
|
4
|
+
"title": "Foggy DeepSeek Harness connection plan",
|
|
5
|
+
"type": "object",
|
|
6
|
+
"additionalProperties": false,
|
|
7
|
+
"required": ["schemaVersion", "name", "type", "namespace"],
|
|
8
|
+
"properties": {
|
|
9
|
+
"schemaVersion": {"const": "foggy-deepseek-connection/v1"},
|
|
10
|
+
"profile": {"type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*$"},
|
|
11
|
+
"name": {"type": "string", "minLength": 1},
|
|
12
|
+
"type": {"enum": ["sqlite", "mysql", "postgres", "postgresql"]},
|
|
13
|
+
"jdbcUrl": {"type": "string", "minLength": 1},
|
|
14
|
+
"username": {"type": "string"},
|
|
15
|
+
"passwordEnv": {"type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"},
|
|
16
|
+
"opaqueProfileId": {"type": "string", "pattern": "^fop_[a-f0-9]{32}$"},
|
|
17
|
+
"opaqueRevision": {"type": "string", "pattern": "^sha256:[a-f0-9]{64}$"},
|
|
18
|
+
"namespace": {"type": "string", "minLength": 1},
|
|
19
|
+
"schemas": {"type": "array", "items": {"type": "string", "minLength": 1}, "uniqueItems": true},
|
|
20
|
+
"modelsDir": {"type": "string", "minLength": 1, "default": "models"},
|
|
21
|
+
"evidenceDir": {"type": "string", "minLength": 1},
|
|
22
|
+
"readOnlyRecommended": {"type": "boolean", "default": true}
|
|
23
|
+
},
|
|
24
|
+
"oneOf": [
|
|
25
|
+
{
|
|
26
|
+
"required": ["opaqueProfileId", "opaqueRevision"],
|
|
27
|
+
"not": {"anyOf": [
|
|
28
|
+
{"required": ["jdbcUrl"]},
|
|
29
|
+
{"required": ["username"]},
|
|
30
|
+
{"required": ["passwordEnv"]}
|
|
31
|
+
]}
|
|
32
|
+
},
|
|
33
|
+
{
|
|
34
|
+
"required": ["jdbcUrl"],
|
|
35
|
+
"not": {"anyOf": [
|
|
36
|
+
{"required": ["opaqueProfileId"]},
|
|
37
|
+
{"required": ["opaqueRevision"]}
|
|
38
|
+
]}
|
|
39
|
+
}
|
|
40
|
+
],
|
|
41
|
+
"allOf": [
|
|
42
|
+
{
|
|
43
|
+
"if": {
|
|
44
|
+
"required": ["jdbcUrl"],
|
|
45
|
+
"properties": {"type": {"not": {"const": "sqlite"}}}
|
|
46
|
+
},
|
|
47
|
+
"then": {"required": ["passwordEnv"]}
|
|
48
|
+
}
|
|
49
|
+
]
|
|
50
|
+
}
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
{
|
|
2
|
+
"schemaVersion": "foggy-deepseek-connection/v1",
|
|
3
|
+
"profile": "business",
|
|
4
|
+
"name": "business-db",
|
|
5
|
+
"type": "mysql",
|
|
6
|
+
"opaqueProfileId": "fop_0123456789abcdef0123456789abcdef",
|
|
7
|
+
"opaqueRevision": "sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
|
|
8
|
+
"namespace": "business",
|
|
9
|
+
"schemas": ["public"],
|
|
10
|
+
"modelsDir": "models",
|
|
11
|
+
"evidenceDir": ".foggy/onboarding-command-evidence/business",
|
|
12
|
+
"readOnlyRecommended": true
|
|
13
|
+
}
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
# Copy only the variables you need into a private, gitignored env file.
|
|
2
|
+
# Never put provider keys or database passwords in DSH settings, Skill files, or evidence.
|
|
3
|
+
|
|
4
|
+
FOGGY_RUNTIME_API_URL=http://127.0.0.1:18066
|
|
5
|
+
FOGGY_NAMESPACE=default
|
|
6
|
+
|
|
7
|
+
# Optional when Runtime reports securityMode=auth-code.
|
|
8
|
+
# FOGGY_RUNTIME_API_AUTH_CODE=
|
|
9
|
+
|
|
10
|
+
# Optional data-plane authorization value.
|
|
11
|
+
# FOGGY_RUNTIME_AUTHORIZATION=
|
|
12
|
+
|
|
13
|
+
# Example datasource password reference. Use a datasource-specific variable name.
|
|
14
|
+
# FOGGY_DATASOURCE_PASSWORD=
|
|
@@ -0,0 +1,22 @@
|
|
|
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
|
+
"runtime": {"type": "object"},
|
|
17
|
+
"connection": {"$ref": "connection.schema.json"},
|
|
18
|
+
"semantic": {"type": "object"},
|
|
19
|
+
"steps": {"type": "object"},
|
|
20
|
+
"artifacts": {"type": "object"}
|
|
21
|
+
}
|
|
22
|
+
}
|
|
@@ -0,0 +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
|
+
}
|
|
@@ -0,0 +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
|
+
}
|
|
@@ -0,0 +1,93 @@
|
|
|
1
|
+
{
|
|
2
|
+
"schemaVersion": "foggy-deepseek-onboarding-versions/v1",
|
|
3
|
+
"packageVersion": "0.4.0-beta.2",
|
|
4
|
+
"validatedAt": "2026-08-28",
|
|
5
|
+
"components": {
|
|
6
|
+
"deepseekHarness": {
|
|
7
|
+
"version": "0.1.1-rc.2",
|
|
8
|
+
"minimumNodeVersion": "22.19.0"
|
|
9
|
+
},
|
|
10
|
+
"cli": {
|
|
11
|
+
"version": "0.1.23",
|
|
12
|
+
"minimumPythonVersion": "3.11.0",
|
|
13
|
+
"wheel": {
|
|
14
|
+
"file": "foggy_runtime_cli-0.1.23-py3-none-any.whl",
|
|
15
|
+
"url": "https://github.com/foggy-projects/foggy-runtime-cli/releases/download/v0.1.23/foggy_runtime_cli-0.1.23-py3-none-any.whl",
|
|
16
|
+
"sha256": "db428812039e5961db93b5c0dc35b53a21d5c349428e6830c96fbf3218cf8a45"
|
|
17
|
+
},
|
|
18
|
+
"checksums": {
|
|
19
|
+
"file": "SHA256SUMS",
|
|
20
|
+
"url": "https://github.com/foggy-projects/foggy-runtime-cli/releases/download/v0.1.23/SHA256SUMS",
|
|
21
|
+
"sha256": "1494d7f13af18bef321995509058a1ab43b1d0b2e9f9ea08230dd78028090221"
|
|
22
|
+
}
|
|
23
|
+
},
|
|
24
|
+
"launcher": {
|
|
25
|
+
"version": "0.1.18",
|
|
26
|
+
"minimumJavaVersion": "17.0.0",
|
|
27
|
+
"runtimeApiContract": "foggy-runtime-api/v1",
|
|
28
|
+
"assets": [
|
|
29
|
+
{
|
|
30
|
+
"file": "foggy-runtime-launcher-0.1.18.jar",
|
|
31
|
+
"url": "https://github.com/foggy-projects/foggy-data-mcp-bridge/releases/download/foggy-runtime-launcher-v0.1.18/foggy-runtime-launcher-0.1.18.jar",
|
|
32
|
+
"sha256": "2953d2fab39208b3fffefed033b34ec6f59da851920b533047a1d0909a1de049"
|
|
33
|
+
},
|
|
34
|
+
{
|
|
35
|
+
"file": "start-foggy-runtime.ps1",
|
|
36
|
+
"url": "https://github.com/foggy-projects/foggy-data-mcp-bridge/releases/download/foggy-runtime-launcher-v0.1.18/start-foggy-runtime.ps1",
|
|
37
|
+
"sha256": "b54f2f144cfdc38afcc3e9167d0700248f476c93adb3e9d95431490430f7b549"
|
|
38
|
+
},
|
|
39
|
+
{
|
|
40
|
+
"file": "start-foggy-runtime.sh",
|
|
41
|
+
"url": "https://github.com/foggy-projects/foggy-data-mcp-bridge/releases/download/foggy-runtime-launcher-v0.1.18/start-foggy-runtime.sh",
|
|
42
|
+
"sha256": "e801cc340bf0842e29045e5e24798921864114846b0e1aaff30640845c8f37d0"
|
|
43
|
+
},
|
|
44
|
+
{
|
|
45
|
+
"file": "README-foggy-runtime-launcher.md",
|
|
46
|
+
"url": "https://github.com/foggy-projects/foggy-data-mcp-bridge/releases/download/foggy-runtime-launcher-v0.1.18/README-foggy-runtime-launcher.md",
|
|
47
|
+
"sha256": "0202546c5221cbb9343cf7367ceb20bff785fd85c2ba77cd0dac5395f6362674"
|
|
48
|
+
},
|
|
49
|
+
{
|
|
50
|
+
"file": "runtime-launcher-manifest.json",
|
|
51
|
+
"url": "https://github.com/foggy-projects/foggy-data-mcp-bridge/releases/download/foggy-runtime-launcher-v0.1.18/runtime-launcher-manifest.json",
|
|
52
|
+
"sha256": "0065de9c516471b936927a0b13ed1b9380c484437352b2e589c5171932427326"
|
|
53
|
+
},
|
|
54
|
+
{
|
|
55
|
+
"file": "SHA256SUMS",
|
|
56
|
+
"url": "https://github.com/foggy-projects/foggy-data-mcp-bridge/releases/download/foggy-runtime-launcher-v0.1.18/SHA256SUMS",
|
|
57
|
+
"sha256": "26f65a7112c115ccd19c6f80336b4335ab7773d54841376aa81504d1c3fcd21f"
|
|
58
|
+
}
|
|
59
|
+
]
|
|
60
|
+
},
|
|
61
|
+
"analysisSkill": {
|
|
62
|
+
"name": "foggy-ai-analysis",
|
|
63
|
+
"version": "0.1.17",
|
|
64
|
+
"minimumCliVersion": "0.1.21",
|
|
65
|
+
"assets": [
|
|
66
|
+
{
|
|
67
|
+
"role": "zip",
|
|
68
|
+
"file": "foggy-ai-analysis-skill-0.1.17.zip",
|
|
69
|
+
"url": "https://github.com/foggy-projects/foggy-ai-analysis/releases/download/v0.1.17/foggy-ai-analysis-skill-0.1.17.zip",
|
|
70
|
+
"sha256": "2c5a10090befc38dd2cf8c3de5121d19c28682ca9c0fe72daf778d315c56c7ff"
|
|
71
|
+
},
|
|
72
|
+
{
|
|
73
|
+
"role": "manifest",
|
|
74
|
+
"file": "foggy-ai-analysis-skill-0.1.17-manifest.json",
|
|
75
|
+
"url": "https://github.com/foggy-projects/foggy-ai-analysis/releases/download/v0.1.17/foggy-ai-analysis-skill-0.1.17-manifest.json",
|
|
76
|
+
"sha256": "094b1401ff384f011ef80446dd639d8afb2585aa01d7a7ba49d39cb2968ae8bf"
|
|
77
|
+
},
|
|
78
|
+
{
|
|
79
|
+
"role": "checksums",
|
|
80
|
+
"file": "foggy-ai-analysis-skill-0.1.17-SHA256SUMS",
|
|
81
|
+
"url": "https://github.com/foggy-projects/foggy-ai-analysis/releases/download/v0.1.17/foggy-ai-analysis-skill-0.1.17-SHA256SUMS",
|
|
82
|
+
"sha256": "18804088cd7da7af6bbf70d658cb0d6a5a31e765470ed673dfd274f1789db240"
|
|
83
|
+
}
|
|
84
|
+
]
|
|
85
|
+
}
|
|
86
|
+
},
|
|
87
|
+
"defaults": {
|
|
88
|
+
"port": 18066,
|
|
89
|
+
"namespace": "default",
|
|
90
|
+
"readinessTimeoutSeconds": 180,
|
|
91
|
+
"securityMode": "none-dev-test-only"
|
|
92
|
+
}
|
|
93
|
+
}
|
|
@@ -0,0 +1,120 @@
|
|
|
1
|
+
# Resumable database onboarding
|
|
2
|
+
|
|
3
|
+
Use the thin `scripts/onboard.ps1` or `scripts/onboard.sh` entrypoint. Every command emits one JSON
|
|
4
|
+
object. Preserve the returned `next` instruction and use `onboard-status` or `onboard-resume` after an
|
|
5
|
+
interruption.
|
|
6
|
+
|
|
7
|
+
The wrapper is mandatory for the entire sequence below. Until `onboard-status` returns
|
|
8
|
+
`next.status=completed`, do not substitute direct `foggy-runtime datasources`, `tables`, `sql`, `models`,
|
|
9
|
+
`bundles`, or `query` calls. A second Skill may help write draft TM/QM files, but must not take over
|
|
10
|
+
orchestration. Do not inspect sample rows to author the semantic layer; use schema metadata plus the
|
|
11
|
+
business definitions confirmed by the user.
|
|
12
|
+
|
|
13
|
+
## Conversation contract
|
|
14
|
+
|
|
15
|
+
Collect these non-secret values before creating a plan:
|
|
16
|
+
|
|
17
|
+
1. an opaque Foggy profile ID and its exact reviewed revision;
|
|
18
|
+
2. datasource name, database type, and namespace from the CLI's public profile summary;
|
|
19
|
+
3. optional schemas, the project-relative semantic model directory, and a project-relative evidence directory.
|
|
20
|
+
|
|
21
|
+
Create the private profile in a trusted operator session outside DeepSeek Harness. Do not ask the user
|
|
22
|
+
to paste a password and do not put a JDBC URL, username, password environment-variable name, or password in the JSON plan, command
|
|
23
|
+
line, logs, or evidence. For non-SQLite databases, ask the user to set the named environment variable
|
|
24
|
+
before Runtime starts so the Java process inherits it. Recommend a read-only database account.
|
|
25
|
+
|
|
26
|
+
Treat every user-supplied identifier and bound as immutable input: profile, datasource, namespace,
|
|
27
|
+
models directory, bundle name, TM/QM name, query fields, and limit. Do not swap in demo names, add
|
|
28
|
+
fields, raise the limit, or introduce replacement flags. If one of these inputs is missing, pause for
|
|
29
|
+
that input rather than inventing it.
|
|
30
|
+
|
|
31
|
+
For composite Harness execution, persist `profile` and `evidenceDir` inside both approved contract
|
|
32
|
+
files. The wrapper derives them from the files and rejects conflicting command-line values. Present the
|
|
33
|
+
normalized contracts to the user before accepting mutation approvals; do not combine contract drafting
|
|
34
|
+
and approval into an unseen one-turn mutation.
|
|
35
|
+
|
|
36
|
+
Write the non-secret input using `assets/connection.schema.json`; `assets/datasource.example.json` is a
|
|
37
|
+
template. Then execute the sequence below.
|
|
38
|
+
|
|
39
|
+
## Deterministic sequence
|
|
40
|
+
|
|
41
|
+
For Harness-driven onboarding, use the two composite commands below. Each writes the numbered JSON
|
|
42
|
+
evidence internally and refuses to cross an unapproved mutation gate:
|
|
43
|
+
|
|
44
|
+
```text
|
|
45
|
+
onboard-datasource-run --connection-file <approved-json> \
|
|
46
|
+
--approve-configure --approve-bind --include-indexes
|
|
47
|
+
|
|
48
|
+
# After authoring the registered TM/QM draft from schema metadata:
|
|
49
|
+
onboard-semantic-run --semantic-plan <approved-json> --query-payload <approved-json> \
|
|
50
|
+
--approve-validate --approve-publish --approve-execute
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
Include an approval flag only after the user approves that exact action. Without it, the composite
|
|
54
|
+
command stops after the corresponding dry-run and returns `phaseStatus=awaiting-...-approval`.
|
|
55
|
+
|
|
56
|
+
The granular commands below remain available for manual troubleshooting and resumption. Do not expand
|
|
57
|
+
the composite commands into this list during a normal Harness turn.
|
|
58
|
+
|
|
59
|
+
```text
|
|
60
|
+
onboard-plan --connection-file <json> --profile <profile>
|
|
61
|
+
datasource-configure --profile <profile>
|
|
62
|
+
datasource-configure --profile <profile> --apply
|
|
63
|
+
datasource-verify --profile <profile>
|
|
64
|
+
datasource-verify --profile <profile> --bind
|
|
65
|
+
schema-discover --profile <profile> --include-indexes
|
|
66
|
+
semantic-draft --profile <profile> --semantic-plan <json>
|
|
67
|
+
semantic-validate --profile <profile>
|
|
68
|
+
semantic-validate --profile <profile> --apply
|
|
69
|
+
semantic-publish --profile <profile>
|
|
70
|
+
semantic-publish --profile <profile> --apply
|
|
71
|
+
semantic-verify --profile <profile> --query-payload <json>
|
|
72
|
+
semantic-verify --profile <profile> --query-payload <json> --execute
|
|
73
|
+
onboard-status --profile <profile>
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
The first `datasource-configure` call is a dry run. Explain the concrete datasource mutation and get
|
|
77
|
+
approval before adding `--apply`. `datasource-verify` tests connectivity without binding; explain the
|
|
78
|
+
namespace binding mutation and get approval before adding `--bind`. Add `--replace` only when the user
|
|
79
|
+
explicitly approves replacing an existing datasource definition.
|
|
80
|
+
|
|
81
|
+
Schema discovery is metadata-only and inspects at most 25 tables by default. Use repeated `--schema` or
|
|
82
|
+
`--table` arguments to narrow scope, `--list-only` for inventory only, and raise `--max-tables` only when
|
|
83
|
+
the user needs broader inspection. The resulting evidence remains under the private Runtime data root.
|
|
84
|
+
|
|
85
|
+
## Semantic authoring and publishing
|
|
86
|
+
|
|
87
|
+
After `schemaDiscovered=completed`, review table names, columns, keys, and relationships with the user.
|
|
88
|
+
Use `foggy-ai-analysis` for TM/QM authoring in a separate project-local draft directory. Do not invent
|
|
89
|
+
business definitions, joins, units, enum meanings, or date semantics. Create a plan using
|
|
90
|
+
`assets/semantic-plan.schema.json`; its declared query-model names must exist in the draft `.qm` files.
|
|
91
|
+
|
|
92
|
+
`semantic-draft` records TM/QM hashes. Any later file change invalidates the recorded validation and must
|
|
93
|
+
be registered and validated again. `semantic-validate` is a dry run until `--apply`; applying it may
|
|
94
|
+
replace the Runtime validation catalog, so explain that mutation before approval.
|
|
95
|
+
|
|
96
|
+
`semantic-publish` shows added, updated, unchanged, preserved, and optionally removed files. Applying it:
|
|
97
|
+
|
|
98
|
+
1. backs up every overwritten or pruned project model file;
|
|
99
|
+
2. copies the registered draft;
|
|
100
|
+
3. validates the published directory;
|
|
101
|
+
4. registers the bundle;
|
|
102
|
+
5. refreshes only the declared query models.
|
|
103
|
+
|
|
104
|
+
Use `--prune` only when the user approves removing target-only TM/QM files. Use `--replace-bundle` only
|
|
105
|
+
when the user approves replacing an existing Runtime bundle, and `--watch` only when file watching is
|
|
106
|
+
desired. A failure before refresh restores project files; a refresh failure is reported as a partial
|
|
107
|
+
Runtime publication and must be diagnosed before retrying.
|
|
108
|
+
|
|
109
|
+
For verification, build a project-local query payload only from `models describe` field names. The helper
|
|
110
|
+
requires an integer `limit` from 1 through 100. The first `semantic-verify` call lists/describes models and
|
|
111
|
+
validates the query; only `--execute` reads business data. Full results stay in evidence and the command
|
|
112
|
+
returns only counts and paths.
|
|
113
|
+
|
|
114
|
+
Do not open, summarize, or quote `query-execute.json` or the Runtime's generated SQL after execution.
|
|
115
|
+
The conversational result may contain only `queryValidated`, `queryExecuted`, `rowCount`, the model
|
|
116
|
+
name, and the evidence path. A successful direct CLI command is not proof that onboarding completed;
|
|
117
|
+
only the wrapper's persisted state with all steps `completed` is authoritative.
|
|
118
|
+
|
|
119
|
+
Do not bypass a failed step. If a command fails, report its structured error, fix only the relevant input
|
|
120
|
+
or environment, and run `onboard-resume` to continue from the first incomplete step.
|