okstra 0.231.1 → 0.233.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.
Files changed (265) hide show
  1. package/README.md +19 -271
  2. package/dist/cli-registry.mjs +14 -1
  3. package/dist/cli-registry.mjs.map +1 -1
  4. package/dist/commands/execute/render-bundle.d.mts +6 -1
  5. package/dist/commands/execute/render-bundle.mjs +139 -32
  6. package/dist/commands/execute/render-bundle.mjs.map +1 -1
  7. package/dist/commands/lifecycle/config.mjs +6 -74
  8. package/dist/commands/lifecycle/config.mjs.map +1 -1
  9. package/dist/commands/memory/memory.mjs +9 -55
  10. package/dist/commands/memory/memory.mjs.map +1 -1
  11. package/dist/commands/trace/capacity.d.mts +12 -0
  12. package/dist/commands/trace/capacity.mjs +21 -0
  13. package/dist/commands/trace/capacity.mjs.map +1 -0
  14. package/dist/commands/trace/model.d.mts +89 -0
  15. package/dist/commands/trace/model.mjs +251 -0
  16. package/dist/commands/trace/model.mjs.map +1 -0
  17. package/dist/commands/trace/progression.d.mts +11 -0
  18. package/dist/commands/trace/progression.mjs +194 -0
  19. package/dist/commands/trace/progression.mjs.map +1 -0
  20. package/dist/commands/trace/review.d.mts +7 -0
  21. package/dist/commands/trace/review.mjs +51 -0
  22. package/dist/commands/trace/review.mjs.map +1 -0
  23. package/dist/commands/trace/task-link.d.mts +18 -0
  24. package/dist/commands/trace/task-link.mjs +72 -0
  25. package/dist/commands/trace/task-link.mjs.map +1 -0
  26. package/dist/commands/trace/trace.d.mts +1 -0
  27. package/dist/commands/trace/trace.mjs +293 -0
  28. package/dist/commands/trace/trace.mjs.map +1 -0
  29. package/dist/lib/bounded-file.d.mts +1 -0
  30. package/dist/lib/bounded-file.mjs +36 -0
  31. package/dist/lib/bounded-file.mjs.map +1 -0
  32. package/dist/lib/config-store.d.mts +34 -0
  33. package/dist/lib/config-store.mjs +70 -0
  34. package/dist/lib/config-store.mjs.map +1 -0
  35. package/dist/lib/file-lock.mjs +4 -5
  36. package/dist/lib/file-lock.mjs.map +1 -1
  37. package/dist/lib/input-limit.d.mts +4 -0
  38. package/dist/lib/input-limit.mjs +8 -0
  39. package/dist/lib/input-limit.mjs.map +1 -0
  40. package/dist/lib/memory-auto-register.d.mts +1 -0
  41. package/dist/lib/memory-auto-register.mjs +98 -0
  42. package/dist/lib/memory-auto-register.mjs.map +1 -0
  43. package/dist/lib/memory-entry-contract.d.mts +12 -0
  44. package/dist/lib/memory-entry-contract.mjs +46 -0
  45. package/dist/lib/memory-entry-contract.mjs.map +1 -0
  46. package/dist/lib/python-helper.d.mts +1 -1
  47. package/dist/lib/python-helper.mjs +3 -2
  48. package/dist/lib/python-helper.mjs.map +1 -1
  49. package/dist/lib/record-secrets.d.mts +1 -0
  50. package/dist/lib/record-secrets.mjs +28 -0
  51. package/dist/lib/record-secrets.mjs.map +1 -0
  52. package/dist/lib/report-language-tag.d.mts +1 -0
  53. package/dist/lib/report-language-tag.mjs +4 -0
  54. package/dist/lib/report-language-tag.mjs.map +1 -0
  55. package/dist/lib/report-language.d.mts +1 -0
  56. package/dist/lib/report-language.mjs +50 -0
  57. package/dist/lib/report-language.mjs.map +1 -0
  58. package/dist/lib/skill-catalog.mjs +3 -0
  59. package/dist/lib/skill-catalog.mjs.map +1 -1
  60. package/dist/lib/types.d.mts +2 -1
  61. package/docs/architecture/storage-model.md +163 -5
  62. package/docs/architecture.md +17 -4
  63. package/docs/cli.md +511 -0
  64. package/docs/contributor-change-matrix.md +1 -2
  65. package/docs/project-structure-overview.md +33 -42
  66. package/package.json +1 -1
  67. package/runtime/BUILD.json +2 -2
  68. package/runtime/agents/common.json +8 -8
  69. package/runtime/agents/operations/trace-interface-review.json +6 -0
  70. package/runtime/agents/operations/trace-scope-review.json +6 -0
  71. package/runtime/agents/roles/verifier.json +2 -4
  72. package/runtime/bin/okstra-provider-exec.py +10 -4
  73. package/runtime/prompts/coding-preflight/architectures/hexagonal.md +23 -30
  74. package/runtime/prompts/coding-preflight/authoring-checks.md +17 -0
  75. package/runtime/prompts/coding-preflight/clean-code.md +88 -286
  76. package/runtime/prompts/coding-preflight/frameworks/node-server.md +2 -3
  77. package/runtime/prompts/coding-preflight/languages/java.md +3 -5
  78. package/runtime/prompts/coding-preflight/languages/javascript-typescript.md +5 -12
  79. package/runtime/prompts/coding-preflight/languages/kotlin.md +2 -4
  80. package/runtime/prompts/coding-preflight/languages/python.md +2 -7
  81. package/runtime/prompts/coding-preflight/languages/rust.md +2 -8
  82. package/runtime/prompts/coding-preflight/languages/sql.md +2 -4
  83. package/runtime/prompts/coding-preflight/overview.md +25 -38
  84. package/runtime/prompts/coding-preflight/review-rules.json +30 -0
  85. package/runtime/prompts/duties/code-reviewer.json +15 -18
  86. package/runtime/prompts/duties/implementation-verifier.json +1 -0
  87. package/runtime/prompts/duties/interface-reviewer.json +32 -0
  88. package/runtime/prompts/host-orchestration/README.md +18 -9
  89. package/runtime/prompts/launch.template.md +3 -2
  90. package/runtime/prompts/lead/context-loader.md +2 -0
  91. package/runtime/prompts/lead/okstra-lead-contract.md +7 -7
  92. package/runtime/prompts/lead/report-writer.md +6 -6
  93. package/runtime/prompts/profiles/_coding-conventions-preflight.md +41 -6
  94. package/runtime/prompts/profiles/_common-contract.md +1 -1
  95. package/runtime/python/okstra_ctl/agent/invocation.py +122 -36
  96. package/runtime/python/okstra_ctl/agent/prompt_cli/cli.py +72 -26
  97. package/runtime/python/okstra_ctl/agent/prompt_cli/corrections.py +23 -8
  98. package/runtime/python/okstra_ctl/agent/prompt_cli/materialize.py +58 -14
  99. package/runtime/python/okstra_ctl/agent/prompt_cli/results.py +8 -11
  100. package/runtime/python/okstra_ctl/agent/standalone.py +15 -0
  101. package/runtime/python/okstra_ctl/analysis_packet.py +24 -30
  102. package/runtime/python/okstra_ctl/attempt_evidence.py +10 -0
  103. package/runtime/python/okstra_ctl/code_review_census.py +162 -7
  104. package/runtime/python/okstra_ctl/code_review_coverage.py +4 -274
  105. package/runtime/python/okstra_ctl/code_review_integrity.py +154 -0
  106. package/runtime/python/okstra_ctl/code_review_invocation.py +212 -0
  107. package/runtime/python/okstra_ctl/code_review_prepare.py +381 -0
  108. package/runtime/python/okstra_ctl/code_review_run.py +384 -0
  109. package/runtime/python/okstra_ctl/code_review_scope.py +49 -9
  110. package/runtime/python/okstra_ctl/code_review_supervisor.py +41 -0
  111. package/runtime/python/okstra_ctl/code_review_target.py +212 -13
  112. package/runtime/python/okstra_ctl/consumers.py +12 -9
  113. package/runtime/python/okstra_ctl/coverage_census.py +11 -2
  114. package/runtime/python/okstra_ctl/design_review.py +207 -0
  115. package/runtime/python/okstra_ctl/design_review_evidence.py +297 -0
  116. package/runtime/python/okstra_ctl/design_snapshot.py +16 -9
  117. package/runtime/python/okstra_ctl/direct_work.py +45 -3
  118. package/runtime/python/okstra_ctl/dispatch_core.py +31 -15
  119. package/runtime/python/okstra_ctl/dispatch_state.py +9 -2
  120. package/runtime/python/okstra_ctl/doctor.py +8 -25
  121. package/runtime/python/okstra_ctl/domain/role.py +1 -0
  122. package/runtime/python/okstra_ctl/doyouknow/__init__.py +9 -0
  123. package/runtime/python/okstra_ctl/doyouknow/cli.py +91 -0
  124. package/runtime/python/okstra_ctl/doyouknow/config.py +58 -0
  125. package/runtime/python/okstra_ctl/doyouknow/contracts.py +184 -0
  126. package/runtime/python/okstra_ctl/doyouknow/identity.py +22 -0
  127. package/runtime/python/okstra_ctl/doyouknow/paths.py +22 -0
  128. package/runtime/python/okstra_ctl/doyouknow/pending.py +72 -0
  129. package/runtime/python/okstra_ctl/doyouknow/registration.py +260 -0
  130. package/runtime/python/okstra_ctl/doyouknow/source_contracts.py +128 -0
  131. package/runtime/python/okstra_ctl/doyouknow/source_store.py +172 -0
  132. package/runtime/python/okstra_ctl/doyouknow/sources/io.py +36 -0
  133. package/runtime/python/okstra_ctl/doyouknow/sources/manager.py +300 -0
  134. package/runtime/python/okstra_ctl/doyouknow/sources/memory.py +179 -0
  135. package/runtime/python/okstra_ctl/doyouknow/sources/task.py +95 -0
  136. package/runtime/python/okstra_ctl/doyouknow/store.py +260 -0
  137. package/runtime/python/okstra_ctl/doyouknow/sync.py +58 -0
  138. package/runtime/python/okstra_ctl/execution_mutation_audit.py +18 -2
  139. package/runtime/python/okstra_ctl/file_size_cap.py +3 -4
  140. package/runtime/python/okstra_ctl/final_report_schema.py +37 -34
  141. package/runtime/python/okstra_ctl/incremental_carry.py +6 -7
  142. package/runtime/python/okstra_ctl/initial_prompt_materialization.py +9 -2
  143. package/runtime/python/okstra_ctl/json_boundary.py +51 -5
  144. package/runtime/python/okstra_ctl/jsonl.py +21 -0
  145. package/runtime/python/okstra_ctl/manager_cli.py +148 -1
  146. package/runtime/python/okstra_ctl/manager_journal.py +126 -0
  147. package/runtime/python/okstra_ctl/manager_launch.py +3 -3
  148. package/runtime/python/okstra_ctl/manager_log.py +221 -0
  149. package/runtime/python/okstra_ctl/manager_paths.py +8 -0
  150. package/runtime/python/okstra_ctl/manager_registration.py +29 -0
  151. package/runtime/python/okstra_ctl/manager_resume.py +59 -0
  152. package/runtime/python/okstra_ctl/manager_split.py +2 -2
  153. package/runtime/python/okstra_ctl/manager_store.py +116 -17
  154. package/runtime/python/okstra_ctl/manager_sync.py +45 -25
  155. package/runtime/python/okstra_ctl/manager_view.py +35 -2
  156. package/runtime/python/okstra_ctl/material.py +2 -0
  157. package/runtime/python/okstra_ctl/model_cli.py +64 -14
  158. package/runtime/python/okstra_ctl/model_defaults.py +22 -0
  159. package/runtime/python/okstra_ctl/model_io/renderers.py +16 -2
  160. package/runtime/python/okstra_ctl/model_io_cli.py +7 -1
  161. package/runtime/python/okstra_ctl/operation_invocation.py +207 -28
  162. package/runtime/python/okstra_ctl/path_hints.py +14 -3
  163. package/runtime/python/okstra_ctl/paths.py +6 -1
  164. package/runtime/python/okstra_ctl/phases/catalog.py +24 -7
  165. package/runtime/python/okstra_ctl/phases/final_verification/validation.py +20 -0
  166. package/runtime/python/okstra_ctl/phases/implementation/host-rules.md +3 -3
  167. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-deliverable.md +10 -0
  168. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-diff-review.md +23 -8
  169. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-self-check.md +6 -4
  170. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md +38 -10
  171. package/runtime/python/okstra_ctl/phases/implementation/report_assets/implementation.template.html +13 -0
  172. package/runtime/python/okstra_ctl/phases/implementation/spec.md +25 -0
  173. package/runtime/python/okstra_ctl/phases/implementation/validation.py +6 -0
  174. package/runtime/python/okstra_ctl/phases/implementation_option_selection/profile.md +1 -1
  175. package/runtime/python/okstra_ctl/phases/implementation_option_selection/votes.py +11 -11
  176. package/runtime/python/okstra_ctl/phases/implementation_planning/authoring.py +16 -9
  177. package/runtime/python/okstra_ctl/phases/implementation_planning/host-rules.md +3 -6
  178. package/runtime/python/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md +12 -10
  179. package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +6 -6
  180. package/runtime/python/okstra_ctl/phases/improvement_discovery/lenses.py +12 -0
  181. package/runtime/python/okstra_ctl/phases/improvement_discovery/profile.md +7 -6
  182. package/runtime/python/okstra_ctl/phases/improvement_discovery/resolved_census.py +159 -0
  183. package/runtime/python/okstra_ctl/phases/improvement_discovery/spec.md +5 -2
  184. package/runtime/python/okstra_ctl/phases/improvement_discovery/validation.py +21 -7
  185. package/runtime/python/okstra_ctl/phases/release_handoff/boundary.json +1 -1
  186. package/runtime/python/okstra_ctl/phases/release_handoff/profile.md +4 -1
  187. package/runtime/python/okstra_ctl/plan_verify_cli.py +6 -4
  188. package/runtime/python/okstra_ctl/render.py +28 -2
  189. package/runtime/python/okstra_ctl/report_assembly.py +53 -11
  190. package/runtime/python/okstra_ctl/report_contract.py +26 -0
  191. package/runtime/python/okstra_ctl/report_corrections.py +36 -20
  192. package/runtime/python/okstra_ctl/report_inputs.py +1 -0
  193. package/runtime/python/okstra_ctl/report_language.py +4 -1
  194. package/runtime/python/okstra_ctl/report_narrative.py +182 -7
  195. package/runtime/python/okstra_ctl/report_projections.py +64 -18
  196. package/runtime/python/okstra_ctl/report_synthesis_packet.py +97 -38
  197. package/runtime/python/okstra_ctl/review_policy.py +359 -0
  198. package/runtime/python/okstra_ctl/review_verdicts.py +291 -0
  199. package/runtime/python/okstra_ctl/run.py +67 -36
  200. package/runtime/python/okstra_ctl/run_context.py +10 -1
  201. package/runtime/python/okstra_ctl/set_work_status.py +4 -15
  202. package/runtime/python/okstra_ctl/stage_done.py +11 -0
  203. package/runtime/python/okstra_ctl/standalone_review_audit.py +28 -0
  204. package/runtime/python/okstra_ctl/task_list_cli.py +34 -8
  205. package/runtime/python/okstra_ctl/task_query.py +239 -0
  206. package/runtime/python/okstra_ctl/trace_review.py +264 -0
  207. package/runtime/python/okstra_ctl/trace_tasks.py +197 -0
  208. package/runtime/python/okstra_ctl/user_authorization.py +14 -0
  209. package/runtime/python/okstra_ctl/verification_generation.py +23 -1
  210. package/runtime/python/okstra_ctl/verification_input_types.py +15 -1
  211. package/runtime/python/okstra_ctl/verification_inputs.py +28 -6
  212. package/runtime/python/okstra_ctl/verification_invocation.py +7 -1
  213. package/runtime/python/okstra_ctl/verification_target.py +2 -0
  214. package/runtime/python/okstra_ctl/wizard/confirmation.py +7 -3
  215. package/runtime/python/okstra_ctl/wizard/launch.py +52 -0
  216. package/runtime/python/okstra_ctl/wizard/launch_cli.py +39 -0
  217. package/runtime/python/okstra_ctl/wizard/outcome.py +17 -16
  218. package/runtime/python/okstra_ctl/wizard/registry.py +1 -1
  219. package/runtime/python/okstra_ctl/wizard/render.py +8 -0
  220. package/runtime/python/okstra_ctl/wizard/state.py +2 -1
  221. package/runtime/python/okstra_ctl/worker_prompt_headers.py +24 -9
  222. package/runtime/python/okstra_ctl/worker_runner.py +66 -10
  223. package/runtime/python/okstra_ctl/write_policy.py +34 -1
  224. package/runtime/python/okstra_project/__init__.py +2 -0
  225. package/runtime/python/okstra_project/dirs.py +18 -0
  226. package/runtime/python/okstra_project/state.py +45 -20
  227. package/runtime/python/okstra_token_usage/blocks.py +74 -0
  228. package/runtime/python/okstra_token_usage/cli.py +23 -10
  229. package/runtime/python/okstra_token_usage/collect.py +25 -22
  230. package/runtime/python/okstra_token_usage/policy.py +193 -0
  231. package/runtime/schemas/doyouknow-config-v1.schema.json +20 -0
  232. package/runtime/schemas/doyouknow-v1.schema.json +65 -0
  233. package/runtime/schemas/final-report-v2.0.schema.json +157 -0
  234. package/runtime/schemas/final-report-v3.0.schema.json +157 -0
  235. package/runtime/schemas/memory-entry-contract-v1.json +11 -0
  236. package/runtime/schemas/record-secret-patterns.json +41 -0
  237. package/runtime/schemas/report-synthesis-packet-v1.0.schema.json +1 -1
  238. package/runtime/skills/_fragments/wizard-confirm-step.md +1 -1
  239. package/runtime/skills/_fragments/wizard-preflight.md +1 -1
  240. package/runtime/skills/_fragments/wizard-prompt-loop.md +3 -5
  241. package/runtime/skills/_fragments/wizard-relay-protocol.md +1 -1
  242. package/runtime/skills/_fragments/wizard-render-bundle.md +15 -29
  243. package/runtime/skills/okstra-brief-gen/SKILL.md +7 -7
  244. package/runtime/skills/okstra-brief-gen/references/tracker-recursion.md +1 -1
  245. package/runtime/skills/okstra-code-review/SKILL.md +92 -136
  246. package/runtime/skills/okstra-code-review/references/census-rules.md +29 -105
  247. package/runtime/skills/okstra-code-review/references/review-calibration.md +37 -61
  248. package/runtime/skills/okstra-discussion/SKILL.md +22 -38
  249. package/runtime/skills/okstra-explain-flow/SKILL.md +6 -2
  250. package/runtime/skills/okstra-manager/SKILL.md +31 -0
  251. package/runtime/skills/okstra-memory/SKILL.md +8 -1
  252. package/runtime/skills/okstra-pr-gen/SKILL.md +1 -1
  253. package/runtime/skills/okstra-run/SKILL.md +55 -183
  254. package/runtime/skills/okstra-schedule-gen/SKILL.md +9 -13
  255. package/runtime/skills/okstra-setup/SKILL.md +3 -2
  256. package/runtime/skills/okstra-setup/references/project-config.md +2 -4
  257. package/runtime/skills/okstra-tdd/SKILL.md +187 -0
  258. package/runtime/skills/okstra-user-response/SKILL.md +4 -2
  259. package/runtime/templates/implementation-worker-preamble.md +4 -9
  260. package/runtime/templates/manager/view.template.html +4 -0
  261. package/runtime/templates/report-writer-prompt-preamble.md +15 -3
  262. package/runtime/templates/trace/trace.template.md +42 -0
  263. package/runtime/templates/worker-prompt-preamble.md +4 -12
  264. package/runtime/validators/checks/fixtures-02.py +25 -33
  265. package/runtime/validators/validate-run.py +107 -38
@@ -9,7 +9,6 @@ from pathlib import Path
9
9
  from typing import Iterable
10
10
 
11
11
  from okstra_project import ResolverError, project_json_path, resolve_project_root
12
- from okstra_project.resolver import resolve_review_rule_packs
13
12
 
14
13
  from . import worktree_registry
15
14
  from .phases.improvement_discovery import lenses as improvement_lenses
@@ -18,6 +17,7 @@ from .phases.catalog import PhaseAssetError, UnknownTaskType, profile_markdown
18
17
  from .role_requirements import RoleProfileError, load_role_profile
19
18
  from .worktree import is_git_work_tree, main_worktree_path
20
19
  from .json_boundary import JsonBoundaryError, load_owned_object
20
+ from .review_policy import capture_review_policy
21
21
 
22
22
  SUPPORTED_PHASES: tuple[str, ...] = (
23
23
  "implementation",
@@ -182,30 +182,13 @@ def _architecture_declaration_check(project_root: Path) -> DoctorCheck | None:
182
182
 
183
183
 
184
184
  def _review_rule_pack_check(project_root: Path) -> DoctorCheck | None:
185
- """Report a declared review rule pack that no worker will be able to open.
186
-
187
- `reviewRulePacks` is what makes a project's own review standard apply
188
- without every brief citing it, so a stale path costs the whole pack in
189
- silence: the phase records `project-review-rules: declared <path>
190
- unreadable` at best, and a run that reviewed against nothing still passes.
191
- Absent declaration stays quiet — brief-cited packs remain the other, equally
192
- valid, channel.
193
-
194
- What this cannot check is whether a pack that does resolve was actually read
195
- and applied; that stays the worker's own `project-review-rules:` record.
196
- """
197
- declared = resolve_review_rule_packs(project_root)
198
- if not declared:
199
- return None
200
- missing = [path for path in declared if not Path(path).is_file()]
201
- if not missing:
202
- return _ok("review rule packs", f"{len(declared)} declared, all readable")
203
- return _fail(
204
- "review rule packs",
205
- f"declared but not readable: {', '.join(missing)} — phases skip a pack "
206
- "they cannot open, so the run reviews against fewer rules than declared. "
207
- f"Fix the path in {project_json_path(project_root)} or drop the entry.",
208
- )
185
+ try:
186
+ config = load_owned_object(project_json_path(project_root), artifact="project config")
187
+ policy = capture_review_policy(project_root, config)
188
+ except (OSError, ValueError) as exc:
189
+ return _fail("review policy", str(exc))
190
+ return _ok("review policy", f"architecture: {policy['architecture']}; "
191
+ f"{len(policy['sources'])} readable rule sources")
209
192
 
210
193
 
211
194
  def _profile_check(workspace: Path, phase: str) -> DoctorCheck:
@@ -54,6 +54,7 @@ DUTY_ROLE_IDS = {
54
54
  "reverification-worker": "verifier",
55
55
  "code-reviewer": "verifier",
56
56
  "schedule-verifier": "verifier",
57
+ "interface-reviewer": "verifier",
57
58
  "business-flow-investigator": "analyser",
58
59
  "report-writer": "report-writer",
59
60
  }
@@ -0,0 +1,9 @@
1
+ __all__ = ["capture_record", "ingest_source", "show_record"]
2
+
3
+
4
+ def __getattr__(name: str):
5
+ if name in __all__:
6
+ from . import store
7
+
8
+ return getattr(store, name)
9
+ raise AttributeError(name)
@@ -0,0 +1,91 @@
1
+ from __future__ import annotations
2
+
3
+ import argparse
4
+ import json
5
+ from pathlib import Path
6
+ from typing import get_args
7
+
8
+ from ..fixed_text import line, value_lines
9
+ from ..json_boundary import JsonBoundaryError, external_user_json_source, load_external_json
10
+ from .config import load_config, save_config
11
+ from .contracts import DoyouknowError, MAX_INPUT_BYTES, read_envelope
12
+ from .registration import register_ticket, retry_pending
13
+ from .source_contracts import SourceKind
14
+
15
+
16
+ def _parser() -> argparse.ArgumentParser:
17
+ parser = argparse.ArgumentParser(prog="okstra doyouknow", description="Store linked work records without starting a run.")
18
+ commands = parser.add_subparsers(dest="command", required=True)
19
+ for name in ("capture", "ingest", "show", "sync", "list", "config", "register", "retry"):
20
+ command = commands.add_parser(name)
21
+ if name == "show":
22
+ command.add_argument("record_id")
23
+ elif name in ("capture", "ingest"):
24
+ command.add_argument("--file", required=True, type=Path, help="normalized doyouknow input JSON")
25
+ elif name == "config":
26
+ command.add_argument("--file", type=Path, help="replace source settings from JSON")
27
+ elif name == "register":
28
+ command.add_argument("--ticket", required=True, help="pending registration UUID")
29
+ if name in ("sync", "list", "retry"):
30
+ command.add_argument("--source", choices=get_args(SourceKind))
31
+ if name == "retry":
32
+ command.add_argument("--limit", type=int, default=100)
33
+ if name == "list":
34
+ command.add_argument("--scope")
35
+ command.add_argument("--limit", type=int, default=100)
36
+ command.add_argument("--after", help="source ID returned as nextCursor")
37
+ output = command.add_mutually_exclusive_group()
38
+ output.add_argument("--json", action="store_true", help="emit JSON (default)")
39
+ output.add_argument("--text", action="store_true", help="emit fixed text fields")
40
+ return parser
41
+
42
+
43
+ def _emit(payload: dict, *, text: bool) -> None:
44
+ if not text:
45
+ print(json.dumps(payload, ensure_ascii=False, allow_nan=False))
46
+ return
47
+ rows = ["Okstra doyouknow\n", line("OK", payload["ok"])]
48
+ rows.extend(value_lines("Result", payload))
49
+ print("".join(rows), end="")
50
+
51
+
52
+ def main(argv: list[str] | None = None) -> int:
53
+ args = _parser().parse_args(argv)
54
+ try:
55
+ if args.command == "show":
56
+ from .store import show_record
57
+
58
+ result = show_record(args.record_id)
59
+ elif args.command == "sync":
60
+ from .sync import sync_sources
61
+
62
+ result = sync_sources(source=args.source)
63
+ elif args.command == "register":
64
+ result = register_ticket(args.ticket)
65
+ elif args.command == "retry":
66
+ result = retry_pending(source=args.source, limit=args.limit)
67
+ elif args.command == "list":
68
+ from .source_store import list_sources
69
+
70
+ result = list_sources(scope=args.scope, kind=args.source, limit=args.limit, after=args.after)
71
+ elif args.command == "config":
72
+ settings = load_external_json(external_user_json_source(args.file), artifact="source settings", max_bytes=MAX_INPUT_BYTES) if args.file else None
73
+ result = {"ok": True, "config": save_config(settings) if args.file else load_config()}
74
+ else:
75
+ from .store import capture_record, ingest_source
76
+
77
+ envelope = read_envelope(args.file)
78
+ write = capture_record if args.command == "capture" else ingest_source
79
+ result = write(envelope)
80
+ except ImportError:
81
+ _emit({"ok": False, "reason": "doyouknow storage dependency is unavailable"}, text=args.text)
82
+ return 1
83
+ except (DoyouknowError, JsonBoundaryError, OSError) as exc:
84
+ _emit({"ok": False, "reason": str(exc)}, text=args.text)
85
+ return 1
86
+ _emit(result, text=args.text)
87
+ return 0 if result["ok"] else 1
88
+
89
+
90
+ if __name__ == "__main__":
91
+ raise SystemExit(main())
@@ -0,0 +1,58 @@
1
+ from __future__ import annotations
2
+
3
+ from pathlib import Path
4
+ from typing import TypedDict
5
+
6
+ from ..json_boundary import load_owned_object, serialize_owned_object, write_owned_object_atomic
7
+ from ..run_context import dir_flock
8
+ from .contracts import MAX_INPUT_BYTES, asset_object
9
+ from .source_contracts import validate_source_value
10
+ from .paths import database_path, ensure_storage_root, require_database_location as _require_database_location
11
+
12
+
13
+ class SourceConfig(TypedDict):
14
+ schemaVersion: int
15
+ autoRegister: bool
16
+ scope: str | None
17
+ sources: list[str]
18
+ includeProjects: list[str]
19
+ excludeProjects: list[str]
20
+ includeGroups: list[str]
21
+ excludeGroups: list[str]
22
+
23
+
24
+ def load_config(*, home: Path | None = None) -> SourceConfig:
25
+ path = database_path(home).parent / "config.json"
26
+ _require_database_location(path)
27
+ if not path.exists():
28
+ return {"schemaVersion": 1, "autoRegister": True, "scope": None,
29
+ "sources": ["memory", "manager", "task"], "includeProjects": [],
30
+ "excludeProjects": [], "includeGroups": [], "excludeGroups": []}
31
+ payload = load_owned_object(path, artifact="doyouknow config", max_bytes=MAX_INPUT_BYTES)
32
+ validate_source_value(payload)
33
+ serialize_owned_object(path, payload, artifact="doyouknow config", schema=asset_object("doyouknow-config-v1.schema.json"))
34
+ return payload
35
+
36
+
37
+ def save_config(payload: SourceConfig, *, home: Path | None = None) -> SourceConfig:
38
+ validate_source_value(payload)
39
+ path = database_path(home).parent / "config.json"
40
+ _require_database_location(path)
41
+ schema = asset_object("doyouknow-config-v1.schema.json")
42
+ serialize_owned_object(path, payload, artifact="doyouknow config", schema=schema)
43
+ ensure_storage_root(path.parent)
44
+ with dir_flock(path.parent, ".config.lock"):
45
+ write_owned_object_atomic(path, payload, artifact="doyouknow config", schema=schema)
46
+ return payload
47
+
48
+
49
+ def includes_project(settings: SourceConfig, project_id: str) -> bool:
50
+ return _included(project_id, settings["includeProjects"], settings["excludeProjects"])
51
+
52
+
53
+ def includes_group(settings: SourceConfig, group: str) -> bool:
54
+ return _included(group, settings["includeGroups"], settings["excludeGroups"])
55
+
56
+
57
+ def _included(value: str, included: list[str], excluded: list[str]) -> bool:
58
+ return value not in excluded and (not included or value in included)
@@ -0,0 +1,184 @@
1
+ from __future__ import annotations
2
+
3
+ import hashlib
4
+ import json
5
+ import re
6
+ from collections.abc import Iterator
7
+ from pathlib import Path
8
+ from typing import Literal, NotRequired, TypedDict
9
+
10
+ from ..json_boundary import (
11
+ external_user_json_source,
12
+ load_external_json,
13
+ load_owned_object,
14
+ serialize_owned_object,
15
+ )
16
+ from ..paths import find_asset_root
17
+
18
+
19
+ class DoyouknowError(ValueError):
20
+ pass
21
+
22
+
23
+ class SecretRefusal(DoyouknowError):
24
+ pass
25
+
26
+
27
+ MAX_INPUT_BYTES = 2_000_000
28
+ MAX_INPUT_DEPTH = 32
29
+
30
+
31
+ class Source(TypedDict):
32
+ kind: str
33
+ id: str
34
+ revision: str
35
+ locator: str
36
+
37
+
38
+ class Record(TypedDict):
39
+ title: str
40
+ summary: str
41
+ body: NotRequired[str]
42
+ type: NotRequired[str]
43
+
44
+
45
+ class Node(TypedDict):
46
+ key: str
47
+ ref: NotRequired[str]
48
+ kind: str
49
+ scope: str
50
+ title: str
51
+
52
+
53
+ Relation = TypedDict("Relation", {
54
+ "from": str,
55
+ "to": str,
56
+ "kind": str,
57
+ "reason": str,
58
+ "evidence": list[str],
59
+ "standing": Literal["observed", "user-stated", "candidate"],
60
+ })
61
+
62
+
63
+ class Envelope(TypedDict):
64
+ schemaVersion: int
65
+ scope: str
66
+ recordKey: str
67
+ requestId: str
68
+ expectedPreviousRevision: str | None
69
+ source: Source
70
+ record: Record
71
+ nodes: list[Node]
72
+ relations: list[Relation]
73
+
74
+
75
+ def asset_object(filename: str) -> dict:
76
+ relative = ("schemas", filename)
77
+ root = find_asset_root(relative)
78
+ if root is None:
79
+ raise DoyouknowError(f"required schema asset is unavailable: {filename}")
80
+ return load_owned_object(root.joinpath(*relative), artifact="doyouknow schema")
81
+
82
+
83
+ def canonical_json(value: object) -> str:
84
+ return json.dumps(value, sort_keys=True, ensure_ascii=False, allow_nan=False)
85
+
86
+
87
+ def _unique_json_object(pairs: list[tuple[str, object]]) -> dict[str, object]:
88
+ result = {}
89
+ for key, value in pairs:
90
+ if key in result:
91
+ raise DoyouknowError("duplicate JSON object key")
92
+ result[key] = value
93
+ return result
94
+
95
+
96
+ def read_envelope(path: Path) -> Envelope:
97
+ try:
98
+ value = load_external_json(
99
+ external_user_json_source(path), artifact="doyouknow input",
100
+ object_pairs_hook=_unique_json_object, max_bytes=MAX_INPUT_BYTES,
101
+ )
102
+ except RecursionError as exc:
103
+ raise DoyouknowError("doyouknow input nesting is too deep") from exc
104
+ return validate_envelope(value)
105
+
106
+
107
+ def validate_envelope(value: object) -> Envelope:
108
+ _check_input_depth(value)
109
+ try:
110
+ encoded = canonical_json(value)
111
+ except (TypeError, ValueError) as exc:
112
+ raise DoyouknowError("doyouknow input is not a JSON value") from exc
113
+ if len(encoded.encode("utf-8")) > MAX_INPUT_BYTES:
114
+ raise DoyouknowError("doyouknow input exceeds 2000000 bytes")
115
+ reject_secrets("\n".join(_decoded_strings(value)))
116
+ serialized = serialize_owned_object(
117
+ Path("doyouknow-input.json"), value, artifact="doyouknow input",
118
+ schema=asset_object("doyouknow-v1.schema.json"),
119
+ )
120
+ envelope = json.loads(serialized)
121
+ _validate_node_references(envelope)
122
+ return envelope
123
+
124
+
125
+ def _decoded_strings(value: object) -> Iterator[str]:
126
+ pending = [value]
127
+ while pending:
128
+ item = pending.pop()
129
+ if isinstance(item, str):
130
+ yield item
131
+ elif isinstance(item, dict):
132
+ pending.extend(item.keys())
133
+ pending.extend(item.values())
134
+ elif isinstance(item, list):
135
+ pending.extend(item)
136
+
137
+
138
+ def _check_input_depth(value: object) -> None:
139
+ pending = [(value, 0)]
140
+ while pending:
141
+ item, depth = pending.pop()
142
+ if depth > MAX_INPUT_DEPTH:
143
+ raise DoyouknowError("doyouknow input nesting is too deep")
144
+ if isinstance(item, dict):
145
+ pending.extend((child, depth + 1) for child in item.values())
146
+ elif isinstance(item, list):
147
+ pending.extend((child, depth + 1) for child in item)
148
+
149
+
150
+ def _validate_node_references(envelope: Envelope) -> None:
151
+ keys = [node.get("ref", node["key"]) for node in envelope["nodes"]]
152
+ if "$record" in keys or len(keys) != len(set(keys)):
153
+ raise DoyouknowError("node references must be unique and cannot be $record")
154
+ identities = [(node["kind"], node["scope"], node["key"]) for node in envelope["nodes"]]
155
+ if len(identities) != len(set(identities)):
156
+ raise DoyouknowError("canonical node identities must be unique in one input")
157
+ allowed = {"$record", *keys}
158
+ for relation in envelope["relations"]:
159
+ if relation["from"] not in allowed or relation["to"] not in allowed:
160
+ raise DoyouknowError("relation endpoint is not in this input")
161
+
162
+
163
+ def load_record_secret_policy() -> dict:
164
+ policy = asset_object("record-secret-patterns.json")
165
+ try:
166
+ if policy["schemaVersion"] != 1:
167
+ raise DoyouknowError("unsupported record secret policy version")
168
+ except (KeyError, TypeError) as exc:
169
+ raise DoyouknowError("record secret policy is invalid") from exc
170
+ return policy
171
+
172
+
173
+ def record_secret_policy_digest() -> str:
174
+ return hashlib.sha256(canonical_json(load_record_secret_policy()).encode("utf-8")).hexdigest()
175
+
176
+
177
+ def reject_secrets(text: str) -> None:
178
+ policy = load_record_secret_policy()
179
+ try:
180
+ hits = [row["label"] for row in policy["patterns"] if re.search(row["pattern"], text, re.ASCII)]
181
+ except (KeyError, TypeError, re.error) as exc:
182
+ raise DoyouknowError("record secret policy is invalid") from exc
183
+ if hits:
184
+ raise SecretRefusal("refusing likely secret(s): " + ", ".join(dict.fromkeys(hits)))
@@ -0,0 +1,22 @@
1
+ from __future__ import annotations
2
+
3
+ import hashlib
4
+ from typing import TYPE_CHECKING
5
+
6
+ from .contracts import Node, canonical_json
7
+
8
+ if TYPE_CHECKING:
9
+ from .source_contracts import SourceRef
10
+
11
+
12
+ def stable_id(kind: str, *parts: str) -> str:
13
+ digest = hashlib.sha256(canonical_json([kind, *parts]).encode("utf-8")).hexdigest()
14
+ return f"{kind}-{digest}"
15
+
16
+
17
+ def node_id(node: Node) -> str:
18
+ return stable_id(node["kind"], node["scope"], node["key"])
19
+
20
+
21
+ def source_id(ref: SourceRef) -> str:
22
+ return stable_id("source", ref.kind, ref.owner_id, ref.native_id)
@@ -0,0 +1,22 @@
1
+ from __future__ import annotations
2
+
3
+ from pathlib import Path
4
+
5
+ from okstra_project.dirs import okstra_home
6
+
7
+ from .contracts import DoyouknowError
8
+
9
+
10
+ def database_path(home: Path | None = None) -> Path:
11
+ root = home if home is not None else okstra_home()
12
+ return root.expanduser().resolve() / "doyouknow" / "graph.sqlite3"
13
+
14
+
15
+ def require_database_location(path: Path) -> None:
16
+ if path.is_symlink() or path.parent.is_symlink():
17
+ raise DoyouknowError("doyouknow storage cannot use a symlink")
18
+
19
+
20
+ def ensure_storage_root(root: Path) -> None:
21
+ require_database_location(root / "graph.sqlite3")
22
+ root.mkdir(parents=True, exist_ok=True, mode=0o700)
@@ -0,0 +1,72 @@
1
+ from __future__ import annotations
2
+
3
+ import json
4
+ import os
5
+ import tempfile
6
+ from pathlib import Path
7
+ from uuid import UUID, uuid4
8
+
9
+ from ..json_boundary import load_owned_object
10
+ from .contracts import DoyouknowError
11
+ from .paths import database_path, ensure_storage_root, require_database_location
12
+ from .source_contracts import SourceRef, validate_source_value
13
+
14
+ MAX_TICKET_BYTES = 16_384
15
+
16
+
17
+ def pending_path(ticket: str, *, home: Path | None = None) -> Path:
18
+ try:
19
+ if str(UUID(ticket)) != ticket:
20
+ raise ValueError
21
+ except (ValueError, TypeError, AttributeError) as exc:
22
+ raise DoyouknowError("invalid registration ticket") from exc
23
+ database = database_path(home)
24
+ require_database_location(database)
25
+ path = database.parent / "pending" / f"{ticket}.json"
26
+ require_database_location(path)
27
+ return path
28
+
29
+
30
+ def _ticket_ref(payload: dict) -> SourceRef:
31
+ try:
32
+ validate_source_value(payload)
33
+ raw = payload["sourceRef"]
34
+ if set(payload) != {"schemaVersion", "sourceRef"} or type(payload["schemaVersion"]) is not int or payload["schemaVersion"] != 1:
35
+ raise ValueError
36
+ if not isinstance(raw, dict) or set(raw) != {"kind", "owner_id", "native_id"}:
37
+ raise ValueError
38
+ if raw["kind"] not in ("memory", "manager", "task"):
39
+ raise ValueError
40
+ if any(not isinstance(value, str) or not value.strip() or len(value) > 4096 for value in raw.values()):
41
+ raise ValueError
42
+ return SourceRef(raw["kind"], raw["owner_id"], raw["native_id"])
43
+ except (KeyError, ValueError, TypeError) as exc:
44
+ raise DoyouknowError("invalid registration reference") from exc
45
+
46
+
47
+ def enqueue_source(ref: SourceRef, *, home: Path | None = None) -> str:
48
+ payload = {"schemaVersion": 1, "sourceRef": {"kind": ref.kind, "owner_id": ref.owner_id, "native_id": ref.native_id}}
49
+ _ticket_ref(payload)
50
+ encoded = json.dumps(payload, ensure_ascii=False).encode("utf-8")
51
+ if len(encoded) > MAX_TICKET_BYTES:
52
+ raise DoyouknowError("registration reference exceeds input limit")
53
+ ticket = str(uuid4())
54
+ path = pending_path(ticket, home=home)
55
+ ensure_storage_root(path.parent.parent)
56
+ path.parent.mkdir(exist_ok=True, mode=0o700)
57
+ descriptor, name = tempfile.mkstemp(prefix=".ticket-", dir=path.parent)
58
+ temporary = Path(name)
59
+ try:
60
+ with os.fdopen(descriptor, "wb") as handle:
61
+ handle.write(encoded)
62
+ handle.flush()
63
+ os.fsync(handle.fileno())
64
+ os.link(temporary, path)
65
+ finally:
66
+ temporary.unlink(missing_ok=True)
67
+ return ticket
68
+
69
+
70
+ def read_ticket(ticket: str, *, home: Path | None = None) -> SourceRef:
71
+ path = pending_path(ticket, home=home)
72
+ return _ticket_ref(load_owned_object(path, artifact="registration ticket", max_bytes=MAX_TICKET_BYTES))