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.
- package/README.md +19 -271
- package/dist/cli-registry.mjs +14 -1
- package/dist/cli-registry.mjs.map +1 -1
- package/dist/commands/execute/render-bundle.d.mts +6 -1
- package/dist/commands/execute/render-bundle.mjs +139 -32
- package/dist/commands/execute/render-bundle.mjs.map +1 -1
- package/dist/commands/lifecycle/config.mjs +6 -74
- package/dist/commands/lifecycle/config.mjs.map +1 -1
- package/dist/commands/memory/memory.mjs +9 -55
- package/dist/commands/memory/memory.mjs.map +1 -1
- package/dist/commands/trace/capacity.d.mts +12 -0
- package/dist/commands/trace/capacity.mjs +21 -0
- package/dist/commands/trace/capacity.mjs.map +1 -0
- package/dist/commands/trace/model.d.mts +89 -0
- package/dist/commands/trace/model.mjs +251 -0
- package/dist/commands/trace/model.mjs.map +1 -0
- package/dist/commands/trace/progression.d.mts +11 -0
- package/dist/commands/trace/progression.mjs +194 -0
- package/dist/commands/trace/progression.mjs.map +1 -0
- package/dist/commands/trace/review.d.mts +7 -0
- package/dist/commands/trace/review.mjs +51 -0
- package/dist/commands/trace/review.mjs.map +1 -0
- package/dist/commands/trace/task-link.d.mts +18 -0
- package/dist/commands/trace/task-link.mjs +72 -0
- package/dist/commands/trace/task-link.mjs.map +1 -0
- package/dist/commands/trace/trace.d.mts +1 -0
- package/dist/commands/trace/trace.mjs +293 -0
- package/dist/commands/trace/trace.mjs.map +1 -0
- package/dist/lib/bounded-file.d.mts +1 -0
- package/dist/lib/bounded-file.mjs +36 -0
- package/dist/lib/bounded-file.mjs.map +1 -0
- package/dist/lib/config-store.d.mts +34 -0
- package/dist/lib/config-store.mjs +70 -0
- package/dist/lib/config-store.mjs.map +1 -0
- package/dist/lib/file-lock.mjs +4 -5
- package/dist/lib/file-lock.mjs.map +1 -1
- package/dist/lib/input-limit.d.mts +4 -0
- package/dist/lib/input-limit.mjs +8 -0
- package/dist/lib/input-limit.mjs.map +1 -0
- package/dist/lib/memory-auto-register.d.mts +1 -0
- package/dist/lib/memory-auto-register.mjs +98 -0
- package/dist/lib/memory-auto-register.mjs.map +1 -0
- package/dist/lib/memory-entry-contract.d.mts +12 -0
- package/dist/lib/memory-entry-contract.mjs +46 -0
- package/dist/lib/memory-entry-contract.mjs.map +1 -0
- package/dist/lib/python-helper.d.mts +1 -1
- package/dist/lib/python-helper.mjs +3 -2
- package/dist/lib/python-helper.mjs.map +1 -1
- package/dist/lib/record-secrets.d.mts +1 -0
- package/dist/lib/record-secrets.mjs +28 -0
- package/dist/lib/record-secrets.mjs.map +1 -0
- package/dist/lib/report-language-tag.d.mts +1 -0
- package/dist/lib/report-language-tag.mjs +4 -0
- package/dist/lib/report-language-tag.mjs.map +1 -0
- package/dist/lib/report-language.d.mts +1 -0
- package/dist/lib/report-language.mjs +50 -0
- package/dist/lib/report-language.mjs.map +1 -0
- package/dist/lib/skill-catalog.mjs +3 -0
- package/dist/lib/skill-catalog.mjs.map +1 -1
- package/dist/lib/types.d.mts +2 -1
- package/docs/architecture/storage-model.md +163 -5
- package/docs/architecture.md +17 -4
- package/docs/cli.md +511 -0
- package/docs/contributor-change-matrix.md +1 -2
- package/docs/project-structure-overview.md +33 -42
- package/package.json +1 -1
- package/runtime/BUILD.json +2 -2
- package/runtime/agents/common.json +8 -8
- package/runtime/agents/operations/trace-interface-review.json +6 -0
- package/runtime/agents/operations/trace-scope-review.json +6 -0
- package/runtime/agents/roles/verifier.json +2 -4
- package/runtime/bin/okstra-provider-exec.py +10 -4
- package/runtime/prompts/coding-preflight/architectures/hexagonal.md +23 -30
- package/runtime/prompts/coding-preflight/authoring-checks.md +17 -0
- package/runtime/prompts/coding-preflight/clean-code.md +88 -286
- package/runtime/prompts/coding-preflight/frameworks/node-server.md +2 -3
- package/runtime/prompts/coding-preflight/languages/java.md +3 -5
- package/runtime/prompts/coding-preflight/languages/javascript-typescript.md +5 -12
- package/runtime/prompts/coding-preflight/languages/kotlin.md +2 -4
- package/runtime/prompts/coding-preflight/languages/python.md +2 -7
- package/runtime/prompts/coding-preflight/languages/rust.md +2 -8
- package/runtime/prompts/coding-preflight/languages/sql.md +2 -4
- package/runtime/prompts/coding-preflight/overview.md +25 -38
- package/runtime/prompts/coding-preflight/review-rules.json +30 -0
- package/runtime/prompts/duties/code-reviewer.json +15 -18
- package/runtime/prompts/duties/implementation-verifier.json +1 -0
- package/runtime/prompts/duties/interface-reviewer.json +32 -0
- package/runtime/prompts/host-orchestration/README.md +18 -9
- package/runtime/prompts/launch.template.md +3 -2
- package/runtime/prompts/lead/context-loader.md +2 -0
- package/runtime/prompts/lead/okstra-lead-contract.md +7 -7
- package/runtime/prompts/lead/report-writer.md +6 -6
- package/runtime/prompts/profiles/_coding-conventions-preflight.md +41 -6
- package/runtime/prompts/profiles/_common-contract.md +1 -1
- package/runtime/python/okstra_ctl/agent/invocation.py +122 -36
- package/runtime/python/okstra_ctl/agent/prompt_cli/cli.py +72 -26
- package/runtime/python/okstra_ctl/agent/prompt_cli/corrections.py +23 -8
- package/runtime/python/okstra_ctl/agent/prompt_cli/materialize.py +58 -14
- package/runtime/python/okstra_ctl/agent/prompt_cli/results.py +8 -11
- package/runtime/python/okstra_ctl/agent/standalone.py +15 -0
- package/runtime/python/okstra_ctl/analysis_packet.py +24 -30
- package/runtime/python/okstra_ctl/attempt_evidence.py +10 -0
- package/runtime/python/okstra_ctl/code_review_census.py +162 -7
- package/runtime/python/okstra_ctl/code_review_coverage.py +4 -274
- package/runtime/python/okstra_ctl/code_review_integrity.py +154 -0
- package/runtime/python/okstra_ctl/code_review_invocation.py +212 -0
- package/runtime/python/okstra_ctl/code_review_prepare.py +381 -0
- package/runtime/python/okstra_ctl/code_review_run.py +384 -0
- package/runtime/python/okstra_ctl/code_review_scope.py +49 -9
- package/runtime/python/okstra_ctl/code_review_supervisor.py +41 -0
- package/runtime/python/okstra_ctl/code_review_target.py +212 -13
- package/runtime/python/okstra_ctl/consumers.py +12 -9
- package/runtime/python/okstra_ctl/coverage_census.py +11 -2
- package/runtime/python/okstra_ctl/design_review.py +207 -0
- package/runtime/python/okstra_ctl/design_review_evidence.py +297 -0
- package/runtime/python/okstra_ctl/design_snapshot.py +16 -9
- package/runtime/python/okstra_ctl/direct_work.py +45 -3
- package/runtime/python/okstra_ctl/dispatch_core.py +31 -15
- package/runtime/python/okstra_ctl/dispatch_state.py +9 -2
- package/runtime/python/okstra_ctl/doctor.py +8 -25
- package/runtime/python/okstra_ctl/domain/role.py +1 -0
- package/runtime/python/okstra_ctl/doyouknow/__init__.py +9 -0
- package/runtime/python/okstra_ctl/doyouknow/cli.py +91 -0
- package/runtime/python/okstra_ctl/doyouknow/config.py +58 -0
- package/runtime/python/okstra_ctl/doyouknow/contracts.py +184 -0
- package/runtime/python/okstra_ctl/doyouknow/identity.py +22 -0
- package/runtime/python/okstra_ctl/doyouknow/paths.py +22 -0
- package/runtime/python/okstra_ctl/doyouknow/pending.py +72 -0
- package/runtime/python/okstra_ctl/doyouknow/registration.py +260 -0
- package/runtime/python/okstra_ctl/doyouknow/source_contracts.py +128 -0
- package/runtime/python/okstra_ctl/doyouknow/source_store.py +172 -0
- package/runtime/python/okstra_ctl/doyouknow/sources/io.py +36 -0
- package/runtime/python/okstra_ctl/doyouknow/sources/manager.py +300 -0
- package/runtime/python/okstra_ctl/doyouknow/sources/memory.py +179 -0
- package/runtime/python/okstra_ctl/doyouknow/sources/task.py +95 -0
- package/runtime/python/okstra_ctl/doyouknow/store.py +260 -0
- package/runtime/python/okstra_ctl/doyouknow/sync.py +58 -0
- package/runtime/python/okstra_ctl/execution_mutation_audit.py +18 -2
- package/runtime/python/okstra_ctl/file_size_cap.py +3 -4
- package/runtime/python/okstra_ctl/final_report_schema.py +37 -34
- package/runtime/python/okstra_ctl/incremental_carry.py +6 -7
- package/runtime/python/okstra_ctl/initial_prompt_materialization.py +9 -2
- package/runtime/python/okstra_ctl/json_boundary.py +51 -5
- package/runtime/python/okstra_ctl/jsonl.py +21 -0
- package/runtime/python/okstra_ctl/manager_cli.py +148 -1
- package/runtime/python/okstra_ctl/manager_journal.py +126 -0
- package/runtime/python/okstra_ctl/manager_launch.py +3 -3
- package/runtime/python/okstra_ctl/manager_log.py +221 -0
- package/runtime/python/okstra_ctl/manager_paths.py +8 -0
- package/runtime/python/okstra_ctl/manager_registration.py +29 -0
- package/runtime/python/okstra_ctl/manager_resume.py +59 -0
- package/runtime/python/okstra_ctl/manager_split.py +2 -2
- package/runtime/python/okstra_ctl/manager_store.py +116 -17
- package/runtime/python/okstra_ctl/manager_sync.py +45 -25
- package/runtime/python/okstra_ctl/manager_view.py +35 -2
- package/runtime/python/okstra_ctl/material.py +2 -0
- package/runtime/python/okstra_ctl/model_cli.py +64 -14
- package/runtime/python/okstra_ctl/model_defaults.py +22 -0
- package/runtime/python/okstra_ctl/model_io/renderers.py +16 -2
- package/runtime/python/okstra_ctl/model_io_cli.py +7 -1
- package/runtime/python/okstra_ctl/operation_invocation.py +207 -28
- package/runtime/python/okstra_ctl/path_hints.py +14 -3
- package/runtime/python/okstra_ctl/paths.py +6 -1
- package/runtime/python/okstra_ctl/phases/catalog.py +24 -7
- package/runtime/python/okstra_ctl/phases/final_verification/validation.py +20 -0
- package/runtime/python/okstra_ctl/phases/implementation/host-rules.md +3 -3
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-deliverable.md +10 -0
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-diff-review.md +23 -8
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-self-check.md +6 -4
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md +38 -10
- package/runtime/python/okstra_ctl/phases/implementation/report_assets/implementation.template.html +13 -0
- package/runtime/python/okstra_ctl/phases/implementation/spec.md +25 -0
- package/runtime/python/okstra_ctl/phases/implementation/validation.py +6 -0
- package/runtime/python/okstra_ctl/phases/implementation_option_selection/profile.md +1 -1
- package/runtime/python/okstra_ctl/phases/implementation_option_selection/votes.py +11 -11
- package/runtime/python/okstra_ctl/phases/implementation_planning/authoring.py +16 -9
- package/runtime/python/okstra_ctl/phases/implementation_planning/host-rules.md +3 -6
- package/runtime/python/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md +12 -10
- package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +6 -6
- package/runtime/python/okstra_ctl/phases/improvement_discovery/lenses.py +12 -0
- package/runtime/python/okstra_ctl/phases/improvement_discovery/profile.md +7 -6
- package/runtime/python/okstra_ctl/phases/improvement_discovery/resolved_census.py +159 -0
- package/runtime/python/okstra_ctl/phases/improvement_discovery/spec.md +5 -2
- package/runtime/python/okstra_ctl/phases/improvement_discovery/validation.py +21 -7
- package/runtime/python/okstra_ctl/phases/release_handoff/boundary.json +1 -1
- package/runtime/python/okstra_ctl/phases/release_handoff/profile.md +4 -1
- package/runtime/python/okstra_ctl/plan_verify_cli.py +6 -4
- package/runtime/python/okstra_ctl/render.py +28 -2
- package/runtime/python/okstra_ctl/report_assembly.py +53 -11
- package/runtime/python/okstra_ctl/report_contract.py +26 -0
- package/runtime/python/okstra_ctl/report_corrections.py +36 -20
- package/runtime/python/okstra_ctl/report_inputs.py +1 -0
- package/runtime/python/okstra_ctl/report_language.py +4 -1
- package/runtime/python/okstra_ctl/report_narrative.py +182 -7
- package/runtime/python/okstra_ctl/report_projections.py +64 -18
- package/runtime/python/okstra_ctl/report_synthesis_packet.py +97 -38
- package/runtime/python/okstra_ctl/review_policy.py +359 -0
- package/runtime/python/okstra_ctl/review_verdicts.py +291 -0
- package/runtime/python/okstra_ctl/run.py +67 -36
- package/runtime/python/okstra_ctl/run_context.py +10 -1
- package/runtime/python/okstra_ctl/set_work_status.py +4 -15
- package/runtime/python/okstra_ctl/stage_done.py +11 -0
- package/runtime/python/okstra_ctl/standalone_review_audit.py +28 -0
- package/runtime/python/okstra_ctl/task_list_cli.py +34 -8
- package/runtime/python/okstra_ctl/task_query.py +239 -0
- package/runtime/python/okstra_ctl/trace_review.py +264 -0
- package/runtime/python/okstra_ctl/trace_tasks.py +197 -0
- package/runtime/python/okstra_ctl/user_authorization.py +14 -0
- package/runtime/python/okstra_ctl/verification_generation.py +23 -1
- package/runtime/python/okstra_ctl/verification_input_types.py +15 -1
- package/runtime/python/okstra_ctl/verification_inputs.py +28 -6
- package/runtime/python/okstra_ctl/verification_invocation.py +7 -1
- package/runtime/python/okstra_ctl/verification_target.py +2 -0
- package/runtime/python/okstra_ctl/wizard/confirmation.py +7 -3
- package/runtime/python/okstra_ctl/wizard/launch.py +52 -0
- package/runtime/python/okstra_ctl/wizard/launch_cli.py +39 -0
- package/runtime/python/okstra_ctl/wizard/outcome.py +17 -16
- package/runtime/python/okstra_ctl/wizard/registry.py +1 -1
- package/runtime/python/okstra_ctl/wizard/render.py +8 -0
- package/runtime/python/okstra_ctl/wizard/state.py +2 -1
- package/runtime/python/okstra_ctl/worker_prompt_headers.py +24 -9
- package/runtime/python/okstra_ctl/worker_runner.py +66 -10
- package/runtime/python/okstra_ctl/write_policy.py +34 -1
- package/runtime/python/okstra_project/__init__.py +2 -0
- package/runtime/python/okstra_project/dirs.py +18 -0
- package/runtime/python/okstra_project/state.py +45 -20
- package/runtime/python/okstra_token_usage/blocks.py +74 -0
- package/runtime/python/okstra_token_usage/cli.py +23 -10
- package/runtime/python/okstra_token_usage/collect.py +25 -22
- package/runtime/python/okstra_token_usage/policy.py +193 -0
- package/runtime/schemas/doyouknow-config-v1.schema.json +20 -0
- package/runtime/schemas/doyouknow-v1.schema.json +65 -0
- package/runtime/schemas/final-report-v2.0.schema.json +157 -0
- package/runtime/schemas/final-report-v3.0.schema.json +157 -0
- package/runtime/schemas/memory-entry-contract-v1.json +11 -0
- package/runtime/schemas/record-secret-patterns.json +41 -0
- package/runtime/schemas/report-synthesis-packet-v1.0.schema.json +1 -1
- package/runtime/skills/_fragments/wizard-confirm-step.md +1 -1
- package/runtime/skills/_fragments/wizard-preflight.md +1 -1
- package/runtime/skills/_fragments/wizard-prompt-loop.md +3 -5
- package/runtime/skills/_fragments/wizard-relay-protocol.md +1 -1
- package/runtime/skills/_fragments/wizard-render-bundle.md +15 -29
- package/runtime/skills/okstra-brief-gen/SKILL.md +7 -7
- package/runtime/skills/okstra-brief-gen/references/tracker-recursion.md +1 -1
- package/runtime/skills/okstra-code-review/SKILL.md +92 -136
- package/runtime/skills/okstra-code-review/references/census-rules.md +29 -105
- package/runtime/skills/okstra-code-review/references/review-calibration.md +37 -61
- package/runtime/skills/okstra-discussion/SKILL.md +22 -38
- package/runtime/skills/okstra-explain-flow/SKILL.md +6 -2
- package/runtime/skills/okstra-manager/SKILL.md +31 -0
- package/runtime/skills/okstra-memory/SKILL.md +8 -1
- package/runtime/skills/okstra-pr-gen/SKILL.md +1 -1
- package/runtime/skills/okstra-run/SKILL.md +55 -183
- package/runtime/skills/okstra-schedule-gen/SKILL.md +9 -13
- package/runtime/skills/okstra-setup/SKILL.md +3 -2
- package/runtime/skills/okstra-setup/references/project-config.md +2 -4
- package/runtime/skills/okstra-tdd/SKILL.md +187 -0
- package/runtime/skills/okstra-user-response/SKILL.md +4 -2
- package/runtime/templates/implementation-worker-preamble.md +4 -9
- package/runtime/templates/manager/view.template.html +4 -0
- package/runtime/templates/report-writer-prompt-preamble.md +15 -3
- package/runtime/templates/trace/trace.template.md +42 -0
- package/runtime/templates/worker-prompt-preamble.md +4 -12
- package/runtime/validators/checks/fixtures-02.py +25 -33
- 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
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
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:
|
|
@@ -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))
|