From d4ab2df9de5dce180460d6cf26183671ea2f959d Mon Sep 17 00:00:00 2001 From: Mykhailo Chalyi Date: Sun, 26 Jul 2026 05:22:24 +0000 Subject: [PATCH] chore(knowledge): group concepts into domain subfolders MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The bundle root held 29 concepts in one flat list. Groups them into foundations/, security/, runtimes/, integrations/ and operations/, mirroring the sections the root index already used, each with its own index.md. The root index now enumerates only its own contents plus subdirectories, which is what OKF §8 progressive disclosure asks for. Frontmatter types are unchanged: directory conveys domain, type conveys kind. Rewrites all 155 references from outside the bundle and the intra-bundle links. crates/bashkit/tests/integration/limitations_doc_tests.rs reads limitations.md at runtime, so that path move is covered by cargo test. check_okf.py now rejects dangling bundle-relative links, ignoring code spans and fenced blocks — a bulk path rewrite silently corrupted a threat-model regex payload and a changelog placeholder before this check existed. --- .agents/skills/process-issues/SKILL.md | 4 +- .agents/skills/ship/SKILL.md | 10 +-- .claude/commands/maintain.md | 8 +-- .github/workflows/apidocs-drift.yml | 2 +- .github/workflows/ci.yml | 2 +- .github/workflows/coreutils-args-drift.yml | 4 +- .github/workflows/publish-python.yml | 8 +-- .github/workflows/python.yml | 6 +- AGENTS.md | 70 +++++++++---------- CHANGELOG.md | 2 +- CONTRIBUTING.md | 2 +- Cargo.toml | 4 +- README.md | 6 +- SECURITY.md | 2 +- crates/bashkit-bench/README.md | 2 +- crates/bashkit-cli/src/interactive.rs | 2 +- crates/bashkit-cli/src/main.rs | 2 +- crates/bashkit-coreutils-port/Cargo.toml | 2 +- crates/bashkit-coreutils-port/src/main.rs | 2 +- crates/bashkit-eval/Cargo.toml | 2 +- crates/bashkit-eval/README.md | 2 +- crates/bashkit-eval/src/checks.rs | 2 +- crates/bashkit-eval/src/dataset.rs | 2 +- crates/bashkit-eval/src/lib.rs | 2 +- crates/bashkit-eval/src/main.rs | 2 +- crates/bashkit-eval/src/mira_study.rs | 2 +- crates/bashkit-eval/src/snapshot.rs | 2 +- crates/bashkit-js/__test__/security.spec.ts | 2 +- crates/bashkit-python/Cargo.toml | 4 +- crates/bashkit-python/src/lib.rs | 24 +++---- crates/bashkit-python/tests/_security_core.py | 2 +- crates/bashkit-python/tests/test_security.py | 2 +- crates/bashkit-wasm/Cargo.toml | 2 +- .../__test__/bashkit-wasm.test.mjs | 2 +- crates/bashkit-wasm/src/lib.rs | 2 +- crates/bashkit/Cargo.toml | 8 +-- crates/bashkit/benches/sqlite.rs | 2 +- crates/bashkit/docs/compatibility.md | 6 +- crates/bashkit/docs/credential-injection.md | 2 +- crates/bashkit/docs/live_mounts.md | 2 +- crates/bashkit/docs/namespace_filesystems.md | 2 +- crates/bashkit/docs/python.md | 4 +- crates/bashkit/docs/sqlite.md | 2 +- crates/bashkit/docs/ssh.md | 4 +- crates/bashkit/docs/threat-model.md | 6 +- crates/bashkit/docs/typescript.md | 4 +- crates/bashkit/fuzz/Cargo.toml | 2 +- crates/bashkit/src/builtins/git/cmd.rs | 2 +- crates/bashkit/src/builtins/git/config.rs | 2 +- crates/bashkit/src/builtins/git/mod.rs | 2 +- crates/bashkit/src/builtins/path.rs | 2 +- crates/bashkit/src/builtins/pipeline.rs | 2 +- crates/bashkit/src/builtins/sleep.rs | 2 +- crates/bashkit/src/builtins/sqlite/engine.rs | 2 +- crates/bashkit/src/builtins/sqlite/mod.rs | 2 +- crates/bashkit/src/builtins/sqlite/tests.rs | 2 +- crates/bashkit/src/builtins/ssh/mod.rs | 2 +- crates/bashkit/src/credential.rs | 2 +- crates/bashkit/src/fs/limits.rs | 2 +- crates/bashkit/src/fs/memory.rs | 2 +- crates/bashkit/src/interpreter/mod.rs | 2 +- crates/bashkit/src/lib.rs | 4 +- crates/bashkit/src/limits.rs | 2 +- crates/bashkit/src/network/allowlist.rs | 2 +- crates/bashkit/src/network/client.rs | 2 +- crates/bashkit/src/network/transport.rs | 2 +- crates/bashkit/src/testing.rs | 2 +- crates/bashkit/src/tool.rs | 2 +- .../coreutils_differential_tests.rs | 2 +- .../integration/credential_injection_tests.rs | 2 +- .../integration/git_remote_security_tests.rs | 2 +- .../tests/integration/git_security_tests.rs | 2 +- .../integration/limitations_doc_tests.rs | 7 +- .../integration/limitations_evidence_tests.rs | 2 +- crates/bashkit/tests/integration/main.rs | 2 +- .../integration/network_security_tests.rs | 2 +- .../integration/parallel_sessions_tests.rs | 2 +- .../tests/integration/sqlite_compat_tests.rs | 2 +- .../integration/sqlite_integration_tests.rs | 2 +- .../integration/sqlite_security_tests.rs | 2 +- .../integration/threat_model_doc_tests.rs | 16 ++--- .../tests/integration/threat_model_tests.rs | 2 +- .../integration/unicode_security_tests.rs | 2 +- .../bashkit/tests/logging_security_tests.rs | 2 +- docs/builtin_typescript.md | 2 +- docs/filesystem.md | 2 +- docs/git.md | 2 +- docs/request-signing.md | 2 +- docs/scripted-tools.md | 2 +- docs/security.md | 6 +- examples/browser/.gitignore | 2 +- examples/browser/README.md | 2 +- justfile | 6 +- knowledge/{ => foundations}/architecture.md | 0 knowledge/{ => foundations}/builtins.md | 0 knowledge/foundations/index.md | 7 ++ .../{ => foundations}/parallel-execution.md | 0 knowledge/{ => foundations}/parser.md | 0 knowledge/{ => foundations}/vfs.md | 0 knowledge/index.md | 51 ++------------ knowledge/{ => integrations}/git-support.md | 0 knowledge/integrations/index.md | 7 ++ .../{ => integrations}/interactive-shell.md | 0 .../scripted-tool-orchestration.md | 2 +- knowledge/{ => integrations}/ssh-support.md | 0 knowledge/{ => integrations}/tool-contract.md | 0 knowledge/knowledge-contract.md | 21 ++++++ knowledge/log.md | 3 + knowledge/{ => operations}/documentation.md | 0 knowledge/{ => operations}/eval.md | 0 knowledge/operations/index.md | 9 +++ knowledge/{ => operations}/limitations.md | 6 +- knowledge/{ => operations}/maintenance.md | 0 .../{ => operations}/performance-results.md | 0 knowledge/{ => operations}/release-process.md | 0 knowledge/{ => operations}/testing.md | 0 knowledge/{ => runtimes}/browser-package.md | 0 .../{ => runtimes}/coreutils-args-port.md | 0 knowledge/{ => runtimes}/emscripten-wheels.md | 0 knowledge/runtimes/index.md | 9 +++ knowledge/{ => runtimes}/python-builtin.md | 0 knowledge/{ => runtimes}/python-package.md | 0 knowledge/{ => runtimes}/sqlite-builtin.md | 0 knowledge/{ => runtimes}/zapcode-runtime.md | 0 .../{ => security}/credential-injection.md | 0 knowledge/{ => security}/http-transport.md | 0 knowledge/security/index.md | 7 ++ knowledge/{ => security}/request-signing.md | 0 knowledge/{ => security}/security-testing.md | 0 knowledge/{ => security}/threat-model.md | 0 knowledge/status/builtin-inventory.md | 2 +- mira.toml | 2 +- scripts/check_okf.py | 26 ++++++- scripts/gen_python_apidocs.py | 2 +- scripts/tests/test_check_okf.py | 23 ++++++ site/README.md | 2 +- site/src/content.config.ts | 2 +- site/src/content/home.ts | 4 +- site/src/pages/api/_meta.ts | 2 +- site/src/pages/builtins.astro | 2 +- site/src/pages/index.astro | 2 +- 141 files changed, 312 insertions(+), 240 deletions(-) rename knowledge/{ => foundations}/architecture.md (100%) rename knowledge/{ => foundations}/builtins.md (100%) create mode 100644 knowledge/foundations/index.md rename knowledge/{ => foundations}/parallel-execution.md (100%) rename knowledge/{ => foundations}/parser.md (100%) rename knowledge/{ => foundations}/vfs.md (100%) rename knowledge/{ => integrations}/git-support.md (100%) create mode 100644 knowledge/integrations/index.md rename knowledge/{ => integrations}/interactive-shell.md (100%) rename knowledge/{ => integrations}/scripted-tool-orchestration.md (98%) rename knowledge/{ => integrations}/ssh-support.md (100%) rename knowledge/{ => integrations}/tool-contract.md (100%) rename knowledge/{ => operations}/documentation.md (100%) rename knowledge/{ => operations}/eval.md (100%) create mode 100644 knowledge/operations/index.md rename knowledge/{ => operations}/limitations.md (97%) rename knowledge/{ => operations}/maintenance.md (100%) rename knowledge/{ => operations}/performance-results.md (100%) rename knowledge/{ => operations}/release-process.md (100%) rename knowledge/{ => operations}/testing.md (100%) rename knowledge/{ => runtimes}/browser-package.md (100%) rename knowledge/{ => runtimes}/coreutils-args-port.md (100%) rename knowledge/{ => runtimes}/emscripten-wheels.md (100%) create mode 100644 knowledge/runtimes/index.md rename knowledge/{ => runtimes}/python-builtin.md (100%) rename knowledge/{ => runtimes}/python-package.md (100%) rename knowledge/{ => runtimes}/sqlite-builtin.md (100%) rename knowledge/{ => runtimes}/zapcode-runtime.md (100%) rename knowledge/{ => security}/credential-injection.md (100%) rename knowledge/{ => security}/http-transport.md (100%) create mode 100644 knowledge/security/index.md rename knowledge/{ => security}/request-signing.md (100%) rename knowledge/{ => security}/security-testing.md (100%) rename knowledge/{ => security}/threat-model.md (100%) diff --git a/.agents/skills/process-issues/SKILL.md b/.agents/skills/process-issues/SKILL.md index 72e32913..1201f1e9 100644 --- a/.agents/skills/process-issues/SKILL.md +++ b/.agents/skills/process-issues/SKILL.md @@ -43,8 +43,8 @@ For each qualifying issue (ordered by issue number), achieve ALL of these before - Minimal, focused changes - Positive and negative tests pass -- Security tests added if change touches parser, interpreter, VFS, network, git, or user input (per `knowledge/security-testing.md`) -- Threat model updated if new attack surface (per `knowledge/threat-model.md`) +- Security tests added if change touches parser, interpreter, VFS, network, git, or user input (per `knowledge/security/security-testing.md`) +- Threat model updated if new attack surface (per `knowledge/security/threat-model.md`) ### 4. Ship via `/ship` diff --git a/.agents/skills/ship/SKILL.md b/.agents/skills/ship/SKILL.md index e040e54e..c1fb7995 100644 --- a/.agents/skills/ship/SKILL.md +++ b/.agents/skills/ship/SKILL.md @@ -33,7 +33,7 @@ Review the changes on this branch (use `git diff origin/main...HEAD` and `git lo 3. **Write missing tests** for any uncovered code paths: - **Positive tests**: happy path, valid inputs, expected state transitions - **Negative tests**: invalid inputs, error conditions, boundary cases, permission failures, missing resources - - **Security tests**: if change touches parser, interpreter, VFS, network, git, or user input — add tests per `knowledge/security-testing.md` + - **Security tests**: if change touches parser, interpreter, VFS, network, git, or user input — add tests per `knowledge/security/security-testing.md` - **Compatibility tests**: if change affects Bash behavior parity — add differential tests comparing against real Bash 4. **Run all tests** to confirm green: `just test` 5. If any test fails, fix the code or test until green @@ -43,9 +43,9 @@ Review the changes on this branch (use `git diff origin/main...HEAD` and `git lo Review the changes and update project artifacts where applicable. Skip items that aren't affected. 1. **Knowledge** (`knowledge/`): if the change affects durable behavior, decisions, constraints, threats, tests, or operations, update the relevant OKF knowledge in the same change -2. **Threat model** (`knowledge/threat-model.md`): if the change introduces new attack surfaces, external inputs, authentication/authorization changes, or data handling — add or update threat entries using the `TM--` format and add `// THREAT[TM-XXX-NNN]` code comments at mitigation points +2. **Threat model** (`knowledge/security/threat-model.md`): if the change introduces new attack surfaces, external inputs, authentication/authorization changes, or data handling — add or update threat entries using the `TM--` format and add `// THREAT[TM-XXX-NNN]` code comments at mitigation points 3. **AGENTS.md**: if the change adds new knowledge, commands, or modifies development workflows — update the relevant section -4. **Limitations** (`knowledge/limitations.md`): if a limitation was added or lifted, update the table; if builtins changed, run `just regen-builtins` and commit the JSON +4. **Limitations** (`knowledge/operations/limitations.md`): if a limitation was added or lifted, update the table; if builtins changed, run `just regen-builtins` and commit the JSON 5. **Documentation** (`crates/bashkit/docs/`): if the change affects public APIs, tools, or features — update the relevant guide markdown files ### Phase 3b: Code Simplification @@ -66,12 +66,12 @@ Analyze all changed code for security vulnerabilities: 1. **Input validation** — check that user-supplied data (script input, file paths, environment variables, command arguments) is validated before use 2. **Injection risks** — look for command injection, path traversal, environment variable injection, or shell metacharacter issues -3. **Sandbox escapes** — if changes touch VFS, builtins, or process execution, verify they cannot escape the sandbox (see `knowledge/threat-model.md`) +3. **Sandbox escapes** — if changes touch VFS, builtins, or process execution, verify they cannot escape the sandbox (see `knowledge/security/threat-model.md`) 4. **Resource exhaustion** — check for unbounded loops, unbounded allocations, or missing limits on user-controlled sizes 5. **Error handling** — ensure errors don't leak internal state, file paths, or sensitive information 6. **Unsafe code** — review any `unsafe` blocks for soundness; prefer safe alternatives -If security issues are found, fix them, add regression tests, and update `knowledge/threat-model.md` if a new threat category is identified. +If security issues are found, fix them, add regression tests, and update `knowledge/security/threat-model.md` if a new threat category is identified. ### Phase 3d: Design Quality Review diff --git a/.claude/commands/maintain.md b/.claude/commands/maintain.md index bfc024ad..3f714315 100644 --- a/.claude/commands/maintain.md +++ b/.claude/commands/maintain.md @@ -1,4 +1,4 @@ -Run the pre-release maintenance checklist from `knowledge/maintenance.md`. Find and fix all issues before reporting. +Run the pre-release maintenance checklist from `knowledge/operations/maintenance.md`. Find and fix all issues before reporting. ## Arguments @@ -28,7 +28,7 @@ Key tools: `cargo update`, `cargo outdated`, `cargo audit`, `cargo deny check`, Ensure the threat model covers all features, security tests exist for all mitigated threats, and no OWASP-style issues exist in the codebase. -Key references: `knowledge/threat-model.md`, `knowledge/security-testing.md`, `crates/bashkit/docs/threat-model.md` +Key references: `knowledge/security/threat-model.md`, `knowledge/security/security-testing.md`, `crates/bashkit/docs/threat-model.md` ### 3. Tests are comprehensive and green @@ -94,7 +94,7 @@ Key tools: - `gh run list --workflow=fuzz.yml --limit 7` (fuzz) - `gh api repos/OWNER/REPO/actions/runs/RUN_ID/jobs` (inspect failed jobs) -If failures persist >2 days, escalate per `knowledge/maintenance.md`. +If failures persist >2 days, escalate per `knowledge/operations/maintenance.md`. If the agent cannot fix a failure, it MUST open a GitHub issue and report the pass as blocked — never silently skip. @@ -108,6 +108,6 @@ pass as blocked — never silently skip. ## Notes -- This is a goal-based checklist. The spec (`knowledge/maintenance.md`) defines *what* must be true. This skill defines *how* to verify and fix. +- This is a goal-based checklist. The spec (`knowledge/operations/maintenance.md`) defines *what* must be true. This skill defines *how* to verify and fix. - Use parallel agents for independent sections when possible. - For scoped runs, still verify that fixes don't break other areas (`just test` at minimum). diff --git a/.github/workflows/apidocs-drift.yml b/.github/workflows/apidocs-drift.yml index a82ae654..887ccfa8 100644 --- a/.github/workflows/apidocs-drift.yml +++ b/.github/workflows/apidocs-drift.yml @@ -5,7 +5,7 @@ name: API Reference Drift # site/src/content/apidocs/*.md and feeds the /api/{python,typescript} pages; # the node-only site build just renders it, so it must be regenerated and # committed on release — fix drift by running `just apidocs` and committing. -# See knowledge/documentation.md ("API reference hosting"). +# See knowledge/operations/documentation.md ("API reference hosting"). # # Per AGENTS.md commit-attribution rules this workflow never auto-commits; it # only fails so a human regenerates and commits under a real identity. diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 54237c77..ba271a20 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -84,7 +84,7 @@ jobs: # Build the browser package (@everruns/bashkit-wasm) and run its headless # integration tests, proving the single-threaded bundle loads with no # COOP/COEP headers and that sync + async execution both work. See - # knowledge/browser-package.md. Keep wasm-bindgen-cli in lockstep with the + # knowledge/runtimes/browser-package.md. Keep wasm-bindgen-cli in lockstep with the # wasm-bindgen version in Cargo.lock. name: WASM web package runs-on: ubuntu-latest diff --git a/.github/workflows/coreutils-args-drift.yml b/.github/workflows/coreutils-args-drift.yml index 79f24210..fd24d4cd 100644 --- a/.github/workflows/coreutils-args-drift.yml +++ b/.github/workflows/coreutils-args-drift.yml @@ -2,7 +2,7 @@ name: Coreutils Args Drift # Detects upstream uutils/coreutils argument-surface AND vendored-module # drift, and proposes both as a single PR. See -# knowledge/coreutils-args-port.md for the design (args mode + module mode). +# knowledge/runtimes/coreutils-args-port.md for the design (args mode + module mode). # # Module set is read from `crates/bashkit-coreutils-port/vendored.toml`; # adding a vendored module is one TOML stanza there and the drift run @@ -324,7 +324,7 @@ jobs: correctly per \`AGENTS.md\`. Intermediate bot commits in this PR are discarded by squash. - Design: [\`knowledge/coreutils-args-port.md\`](../tree/main/knowledge/coreutils-args-port.md). + Design: [\`knowledge/runtimes/coreutils-args-port.md\`](../tree/main/knowledge/runtimes/coreutils-args-port.md). EOF if gh pr view "$branch" --repo "$GITHUB_REPOSITORY" >/dev/null 2>&1; then diff --git a/.github/workflows/publish-python.yml b/.github/workflows/publish-python.yml index c2d3dc24..7db67b49 100644 --- a/.github/workflows/publish-python.yml +++ b/.github/workflows/publish-python.yml @@ -21,7 +21,7 @@ env: CARGO_TERM_COLOR: always # abi3 (stable ABI): one interpreter builds a single cp39-abi3 wheel per # platform that runs on Python 3.9+. No per-minor-version matrix. See - # knowledge/python-package.md § abi3. + # knowledge/runtimes/python-package.md § abi3. BUILD_PYTHON: "3.12" jobs: @@ -119,14 +119,14 @@ jobs: # Reduced-feature Pyodide/Emscripten wheel (browser / JupyterLite). # Separate job: distinct toolchain (nightly Rust + emsdk + pyodide-build) and a # single Python version dictated by the pyodide-build ABI lockstep. - # See knowledge/emscripten-wheels.md. + # See knowledge/runtimes/emscripten-wheels.md. build-emscripten: name: Build wheel - emscripten (Pyodide) runs-on: ubuntu-latest env: # Keep in lockstep with the `wasm` job in python.yml: the nightly's LLVM, # pyodide-build's Emscripten/binaryen, and Pyodide's EH ABI must agree. - # See knowledge/emscripten-wheels.md "version triangle". Bump together. + # See knowledge/runtimes/emscripten-wheels.md "version triangle". Bump together. RUST_NIGHTLY: "nightly-2026-05-29" PYODIDE_BUILD_VERSION: "0.34.4" steps: @@ -134,7 +134,7 @@ jobs: # Python 3.13 -> pyodide-build's modern config (Pyodide 0.29.x, Emscripten # 4.0.9), whose binaryen understands modern LLVM's wasm target-features and - # whose runtime supports wasm exception handling. See knowledge/emscripten-wheels.md. + # whose runtime supports wasm exception handling. See knowledge/runtimes/emscripten-wheels.md. - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0 with: python-version: "3.13" diff --git a/.github/workflows/python.yml b/.github/workflows/python.yml index a88e2170..a3cbf34a 100644 --- a/.github/workflows/python.yml +++ b/.github/workflows/python.yml @@ -193,14 +193,14 @@ jobs: retention-days: 5 # Build the reduced-feature Pyodide/Emscripten wheel and smoke-test it in a - # Pyodide venv. See knowledge/emscripten-wheels.md for the feature matrix and the + # Pyodide venv. See knowledge/runtimes/emscripten-wheels.md for the feature matrix and the # pyodide-build <-> Emscripten <-> Python <-> Rust version lockstep. wasm: name: Build wheel (Pyodide/Emscripten) runs-on: ubuntu-latest env: # Pinned for reproducibility: this trio must stay aligned on the wasm - # feature set + exception-handling ABI (see knowledge/emscripten-wheels.md + # feature set + exception-handling ABI (see knowledge/runtimes/emscripten-wheels.md # "version triangle"). pyodide-build 0.34.x (under Python 3.13) selects # Pyodide 0.29.x / Emscripten 4.0.9; the nightly's LLVM must match that # binaryen. Bump all three together and re-verify the wheel imports. @@ -220,7 +220,7 @@ jobs: # must satisfy our deps' MSRV (monty needs rustc 1.95) and edition 2024, # so it has to be recent; its LLVM (19+) matches Emscripten 4.0.9's # binaryen, which is what avoids the wasm-opt target-feature skew that - # older Emscripten (3.1.x) hit. See knowledge/emscripten-wheels.md. + # older Emscripten (3.1.x) hit. See knowledge/runtimes/emscripten-wheels.md. - name: Install nightly Rust with the Emscripten target # @nightly matches the repo's other nightly jobs (fuzz.yml, nightly.yml, # ci.yml); the exact nightly is pinned via the toolchain: input below. diff --git a/AGENTS.md b/AGENTS.md index 9ff09f9b..881df1b9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -24,41 +24,41 @@ Fix root cause. Unsure: read more code; if stuck, ask w/ short options. Unrecogn | Knowledge | Description | |------|-------------| | knowledge-contract | Knowledge maintenance rules + OKF v0.2 conformance rules | -| architecture | Core interpreter architecture, module structure | -| parser | Bash syntax parser design | -| vfs | Virtual filesystem abstraction | -| testing | Testing strategy and patterns | -| builtins | Builtin command design (trait, ShellRef, ExecutionPlan) | -| security-testing | Fail-point injection for security testing | -| threat-model | Security threats and mitigations | -| parallel-execution | Threading model, Arc usage | -| documentation | Rustdoc guides, embedded markdown | -| release-process | Version tagging, crates.io + PyPI + npm publishing | -| limitations | Negative spec: intentional gaps (L-* IDs), partial features, POSIX stance | -| tool-contract | Public LLM Tool trait contract | -| git-support | Sandboxed git operations on VFS | -| python-builtin | Embedded Python via Monty, security, resource limits | -| eval | LLM eval study on the mira framework, dataset format, scoring | -| maintenance | Pre-release maintenance requirements | -| python-package | Python package, PyPI wheels, platform matrix | -| scripted-tool-orchestration | Compose ToolDef+callback pairs into OrchestratorTool via bash scripts | -| ssh-support | Sandboxed SSH/SCP/SFTP operations | -| zapcode-runtime | Embedded TypeScript via ZapCode, VFS bridging, resource limits | -| request-signing | Transparent Ed25519 request signing (bot-auth) per RFC 9421 | -| interactive-shell | Interactive REPL mode with rustyline line editing | -| sqlite-builtin | Embedded SQLite via Turso (MemoryIO + VfsIO backends, dot-commands) | -| coreutils-args-port | Codegen port of uutils clap definitions + uucore modules | -| credential-injection | Per-host HTTP credential injection without exposing secrets | -| http-transport | Pluggable HTTP transport: route curl/wget via host egress boundary | -| performance-results | Benchmark/eval result locations and `/benches` site aggregation contract | -| emscripten-wheels | Reduced-feature Pyodide/Emscripten Python wheel | -| browser-package | Slim single-threaded wasm package (`@everruns/bashkit-wasm`) for browsers + JS runtimes, no COOP/COEP | +| foundations/architecture | Core interpreter architecture, module structure | +| foundations/parser | Bash syntax parser design | +| foundations/vfs | Virtual filesystem abstraction | +| operations/testing | Testing strategy and patterns | +| foundations/builtins | Builtin command design (trait, ShellRef, ExecutionPlan) | +| security/security-testing | Fail-point injection for security testing | +| security/threat-model | Security threats and mitigations | +| foundations/parallel-execution | Threading model, Arc usage | +| operations/documentation | Rustdoc guides, embedded markdown | +| operations/release-process | Version tagging, crates.io + PyPI + npm publishing | +| operations/limitations | Negative spec: intentional gaps (L-* IDs), partial features, POSIX stance | +| integrations/tool-contract | Public LLM Tool trait contract | +| integrations/git-support | Sandboxed git operations on VFS | +| runtimes/python-builtin | Embedded Python via Monty, security, resource limits | +| operations/eval | LLM eval study on the mira framework, dataset format, scoring | +| operations/maintenance | Pre-release maintenance requirements | +| runtimes/python-package | Python package, PyPI wheels, platform matrix | +| integrations/scripted-tool-orchestration | Compose ToolDef+callback pairs into OrchestratorTool via bash scripts | +| integrations/ssh-support | Sandboxed SSH/SCP/SFTP operations | +| runtimes/zapcode-runtime | Embedded TypeScript via ZapCode, VFS bridging, resource limits | +| security/request-signing | Transparent Ed25519 request signing (bot-auth) per RFC 9421 | +| integrations/interactive-shell | Interactive REPL mode with rustyline line editing | +| runtimes/sqlite-builtin | Embedded SQLite via Turso (MemoryIO + VfsIO backends, dot-commands) | +| runtimes/coreutils-args-port | Codegen port of uutils clap definitions + uucore modules | +| security/credential-injection | Per-host HTTP credential injection without exposing secrets | +| security/http-transport | Pluggable HTTP transport: route curl/wget via host egress boundary | +| operations/performance-results | Benchmark/eval result locations and `/benches` site aggregation contract | +| runtimes/emscripten-wheels | Reduced-feature Pyodide/Emscripten Python wheel | +| runtimes/browser-package | Slim single-threaded wasm package (`@everruns/bashkit-wasm`) for browsers + JS runtimes, no COOP/COEP | ### Documentation - **Public docs** live in `docs/` — user-facing articles (security, guides, etc.) - **Rustdoc guides** live in `crates/bashkit/docs/` as markdown files -- Rustdoc guides embedded via `include_str!` (see `knowledge/documentation.md`) +- Rustdoc guides embedded via `include_str!` (see `knowledge/operations/documentation.md`) - Edit `crates/bashkit/docs/*.md`, not the doc modules in `lib.rs` - Add "See also" cross-links when creating new guides - Run `cargo doc --open` to preview rustdoc changes @@ -131,7 +131,7 @@ and are aggregated by `crates/bashkit/tests/integration/main.rs` into a single b New behavioral tests go there. A small number of files stay as top-level `tests/*.rs` because they need their own binary (process-global env mutation, `--test-threads=1`, ssh-only feature isolation) — the list and -criteria live in `knowledge/testing.md`. +criteria live in `knowledge/operations/testing.md`. ### Rust @@ -143,7 +143,7 @@ criteria live in `knowledge/testing.md`. ### Stderr from builtins must not leak internal Debug shapes -**TM-INF-022** in `knowledge/threat-model.md`. No `{:?}`/`{:#?}` in +**TM-INF-022** in `knowledge/security/threat-model.md`. No `{:?}`/`{:#?}` in `crates/bashkit/src/builtins/`; use `Display` or a domain formatter (reference: `format_compile_errors` in `builtins/jq/errors.rs`); cap diagnostics ≤ 1 KB; test-only Debug needs `// debug-ok: `. @@ -185,14 +185,14 @@ Do not mix criterion `.md` files into `crates/bashkit-bench/results/`. 3. `cargo clippy --all-targets --all-features -- -D warnings` 4. `just test` (feature-sliced; never `cargo test --all-features` in one invocation — see Local Dev) 5. Unit tests cover both positive (expected behavior) and negative (error handling, edge cases) scenarios -6. Security tests if change touches user input, parsing, sandboxing, or permissions (see `knowledge/security-testing.md`) +6. Security tests if change touches user input, parsing, sandboxing, or permissions (see `knowledge/security/security-testing.md`) 7. Compatibility/differential tests if change affects Bash behavior parity (compare against real Bash) 8. Rebase on main: `git fetch origin main && git rebase origin/main` (for worktrees: verify the worktree `HEAD` is on latest `origin/main` before editing) 9. Update knowledge if behavior or durable project facts change 10. CI green before merge 11. Resolve all PR comments -12. `cargo bench --bench parallel_execution` if touching Arc/async/Interpreter/builtins (see `knowledge/parallel-execution.md`) -13. `just bench-sqlite` if touching the sqlite builtin or its VFS/IO bridge (see `knowledge/sqlite-builtin.md`) +12. `cargo bench --bench parallel_execution` if touching Arc/async/Interpreter/builtins (see `knowledge/foundations/parallel-execution.md`) +13. `just bench-sqlite` if touching the sqlite builtin or its VFS/IO bridge (see `knowledge/runtimes/sqlite-builtin.md`) 14. `just bench` if changes might impact performance (interpreter, builtins, tools) 15. `ruff check crates/bashkit-python && ruff format --check crates/bashkit-python` if touching Python code diff --git a/CHANGELOG.md b/CHANGELOG.md index 8d7d6c5c..0b33956e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -122,7 +122,7 @@ addresses, and the response size cap, and returns typed errors (`Denied`/`Timeout`/`TooLarge`/`Transport`) that map onto curl exit codes (7/28/63/1). Mirrors fetchkit's transport injection so one host egress - implementation can back both libraries. See `knowledge/http-transport.md` + implementation can back both libraries. See `knowledge/security/http-transport.md` ([#2147](https://github.com/everruns/bashkit/pull/2147)). - **`xargs -P` parallel execution** — `-P/--max-procs` runs command batches concurrently, with `--process-slot-var` exposing the slot index to each child diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7e61ad21..4d186896 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -67,7 +67,7 @@ test: add array edge case tests 2. Add spec tests in `crates/bashkit/tests/spec_cases/` 3. Implement the feature 4. Update `crates/bashkit/docs/compatibility.md` if applicable -5. Update `knowledge/limitations.md` if removing a limitation +5. Update `knowledge/operations/limitations.md` if removing a limitation ## Spec Test Format diff --git a/Cargo.toml b/Cargo.toml index 4dc989c4..7076714a 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -110,7 +110,7 @@ tower = { version = "0.5", features = ["util"] } # SSH client (for ssh/scp/sftp builtins) russh = "0.62" # Embedded SQLite engine (Turso, pure Rust). Upstream is BETA — gated behind -# the `sqlite` feature and disabled by default; see knowledge/sqlite-builtin.md. +# the `sqlite` feature and disabled by default; see knowledge/runtimes/sqlite-builtin.md. turso_core = "0.8.0-pre.1" # Serial test execution @@ -122,7 +122,7 @@ serial_test = "3" # separate binary per minor version. Collapses the 6-version × 7-platform matrix # (42 native wheels/release, ~12 MB each) to 7, and future Python releases need # no rebuild. `generate-import-lib` kept for the Windows abi3 import lib. -# See knowledge/python-package.md § abi3. +# See knowledge/runtimes/python-package.md § abi3. pyo3 = { version = "0.29", features = ["extension-module", "generate-import-lib", "abi3-py39"] } pyo3-async-runtimes = { version = "0.29", features = ["tokio-runtime"] } diff --git a/README.md b/README.md index 59237128..3c8e1708 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ Homepage: [bashkit.sh](https://bashkit.sh) ## Features -- **Secure by default** - No process spawning, no filesystem access, no network access unless explicitly enabled. [280+ threats](knowledge/threat-model.md) analyzed and mitigated +- **Secure by default** - No process spawning, no filesystem access, no network access unless explicitly enabled. [280+ threats](knowledge/security/threat-model.md) analyzed and mitigated - **POSIX compliant** - Substantial IEEE 1003.1-2024 Shell Command Language compliance - **Sandboxed, in-process execution** - All 164 commands reimplemented in Rust, no `fork`/`exec` - **Virtual filesystem** - InMemoryFs, OverlayFs, MountableFs with optional RealFs backend (`realfs` feature) @@ -318,7 +318,7 @@ let mut bash = Bash::builder() // Remote operations: remote add/remove, clone/push/pull/fetch (virtual mode) ``` -See [knowledge/git-support.md](knowledge/git-support.md) for the full specification. +See [knowledge/integrations/git-support.md](knowledge/integrations/git-support.md) for the full specification. ## Experimental: Python Support @@ -581,7 +581,7 @@ Bashkit is built for running untrusted scripts from AI agents and users. Securit 280+ identified threats across 17 categories (DoS, sandbox escape, info disclosure, injection, network, isolation, internal errors, git, SSH, logging, crypto, Python, TypeScript, SQLite, Unicode, filesystem, snapshots) — each with a stable ID, mitigation status, and test coverage. -See the [threat model](knowledge/threat-model.md) for the full analysis and [security policy](SECURITY.md) for reporting vulnerabilities. +See the [threat model](knowledge/security/threat-model.md) for the full analysis and [security policy](SECURITY.md) for reporting vulnerabilities. ## Other Virtual Bash Implementations diff --git a/SECURITY.md b/SECURITY.md index d4635d60..25413ed4 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -40,7 +40,7 @@ Bashkit is designed as a virtual interpreter. Key security boundaries: ### Known Limitations -See [knowledge/limitations.md](knowledge/limitations.md) for documented gaps and limitations. +See [knowledge/operations/limitations.md](knowledge/operations/limitations.md) for documented gaps and limitations. ## Supported Versions diff --git a/crates/bashkit-bench/README.md b/crates/bashkit-bench/README.md index 5061ab52..101d0699 100644 --- a/crates/bashkit-bench/README.md +++ b/crates/bashkit-bench/README.md @@ -128,7 +128,7 @@ cargo run -p bashkit-bench --release -- --list | `--list` | List available benchmarks | Saved JSON/Markdown reports in `crates/bashkit-bench/results/` feed the site -`/benches` page. See `knowledge/performance-results.md` for the aggregation +`/benches` page. See `knowledge/operations/performance-results.md` for the aggregation contract. ## Prerequisites diff --git a/crates/bashkit-cli/src/interactive.rs b/crates/bashkit-cli/src/interactive.rs index 513011ad..e38a0d3e 100644 --- a/crates/bashkit-cli/src/interactive.rs +++ b/crates/bashkit-cli/src/interactive.rs @@ -6,7 +6,7 @@ // Decision: PS1 prompt with bash-compatible escapes (\u, \h, \w, \$). // Decision: exit via ExitSignal event fired by the interpreter — REPL polls // the signal after each exec() call. -// See knowledge/interactive-shell.md +// See knowledge/integrations/interactive-shell.md use anyhow::Result; use rustyline::completion::Completer; diff --git a/crates/bashkit-cli/src/main.rs b/crates/bashkit-cli/src/main.rs index 7ed5310a..84c2afc3 100644 --- a/crates/bashkit-cli/src/main.rs +++ b/crates/bashkit-cli/src/main.rs @@ -8,7 +8,7 @@ // by flags to avoid unbounded hangs for wrapper/automation usage. // Decision: interactive mode uses rustyline for line editing — lightweight, MIT, // no heavy deps (no SQLite, no crossterm). Multiline via parse error detection. -// See knowledge/interactive-shell.md +// See knowledge/integrations/interactive-shell.md // Decision: CLI enables embedded Python by default when compiled in. This is an // explicit CLI builder opt-in, not ambient process environment inheritance. diff --git a/crates/bashkit-coreutils-port/Cargo.toml b/crates/bashkit-coreutils-port/Cargo.toml index c66d97dd..dfdacd9a 100644 --- a/crates/bashkit-coreutils-port/Cargo.toml +++ b/crates/bashkit-coreutils-port/Cargo.toml @@ -8,7 +8,7 @@ # manifest (`vendored.toml`) declaring per-import substitution policy. # # Run manually when bumping the pinned uutils revision; output is committed. -# See knowledge/coreutils-args-port.md for both modes. +# See knowledge/runtimes/coreutils-args-port.md for both modes. [package] name = "bashkit-coreutils-port" diff --git a/crates/bashkit-coreutils-port/src/main.rs b/crates/bashkit-coreutils-port/src/main.rs index 8acd7872..57f6fc64 100644 --- a/crates/bashkit-coreutils-port/src/main.rs +++ b/crates/bashkit-coreutils-port/src/main.rs @@ -33,7 +33,7 @@ //! command + MIT attribution). //! //! Run manually when bumping the pinned uutils revision; output is -//! committed. See `knowledge/coreutils-args-port.md`. +//! committed. See `knowledge/runtimes/coreutils-args-port.md`. use std::path::PathBuf; use std::process::ExitCode; diff --git a/crates/bashkit-eval/Cargo.toml b/crates/bashkit-eval/Cargo.toml index 7500dac2..acbc007f 100644 --- a/crates/bashkit-eval/Cargo.toml +++ b/crates/bashkit-eval/Cargo.toml @@ -4,7 +4,7 @@ # bashkit drives the agent loop as a mira `Subject`; tasks are mira `Sample`s; # the bashkit expectation checks run as a mira `Scorer`. The `mira` CLI hosts # this binary over stdio and owns the model matrix, scheduling, and reporting. -# See knowledge/eval.md for design decisions. +# See knowledge/operations/eval.md for design decisions. [package] name = "bashkit-eval" diff --git a/crates/bashkit-eval/README.md b/crates/bashkit-eval/README.md index f1e65228..86d13e34 100644 --- a/crates/bashkit-eval/README.md +++ b/crates/bashkit-eval/README.md @@ -6,7 +6,7 @@ Measures how well models use bashkit's bash tool in agentic workloads. bashkit-eval is a **study binary** the `mira` host CLI spawns over stdio; mira owns the model matrix, scheduling, retries, resume, and reporting. bashkit supplies the subject (its agent loop over a persistent VFS) and the scorer (the -deterministic expectation checks). See [`knowledge/eval.md`](../../knowledge/eval.md). +deterministic expectation checks). See [`knowledge/operations/eval.md`](../../knowledge/operations/eval.md). ## Usage diff --git a/crates/bashkit-eval/src/checks.rs b/crates/bashkit-eval/src/checks.rs index cb36fca5..823b27f0 100644 --- a/crates/bashkit-eval/src/checks.rs +++ b/crates/bashkit-eval/src/checks.rs @@ -6,7 +6,7 @@ // `AgentTrace` + `&dyn FileSystem`. This keeps scoring synchronous and lets it // run inside a mira `Scorer`, which only sees `&Sample` + `&Transcript`. // -// Check reference (see knowledge/eval.md): +// Check reference (see knowledge/operations/eval.md): // exit_code:N stdout_contains:text stdout_regex:pattern // stderr_empty file_exists:/path dir_exists:/path // file_contains:/path:text file_line_regex:/path:pattern llm_judge:prompt diff --git a/crates/bashkit-eval/src/dataset.rs b/crates/bashkit-eval/src/dataset.rs index cd67b5c4..0427e816 100644 --- a/crates/bashkit-eval/src/dataset.rs +++ b/crates/bashkit-eval/src/dataset.rs @@ -1,6 +1,6 @@ // Dataset types and JSONL loader // Each line in the JSONL file is one EvalTask -// See knowledge/eval.md for format specification +// See knowledge/operations/eval.md for format specification use anyhow::{Context, Result}; use serde::{Deserialize, Serialize}; diff --git a/crates/bashkit-eval/src/lib.rs b/crates/bashkit-eval/src/lib.rs index 5b4b35f6..a9cce8d3 100644 --- a/crates/bashkit-eval/src/lib.rs +++ b/crates/bashkit-eval/src/lib.rs @@ -1,5 +1,5 @@ // bashkit-eval: a mira eval study for bashkit tool usage. -// See knowledge/eval.md for design decisions. +// See knowledge/operations/eval.md for design decisions. // // The transport + execution layer (providers, agent loops, dataset types) is // reused as-is; the mira integration (samples, subjects, scorer, eval builders) diff --git a/crates/bashkit-eval/src/main.rs b/crates/bashkit-eval/src/main.rs index 2651d03a..55e933b2 100644 --- a/crates/bashkit-eval/src/main.rs +++ b/crates/bashkit-eval/src/main.rs @@ -9,7 +9,7 @@ // // The `#[eval]` wrappers live here (in the bin crate) so their inventory // registrations are guaranteed to link into this binary; the heavy lifting is -// in `bashkit_eval::mira_study`. See knowledge/eval.md. +// in `bashkit_eval::mira_study`. See knowledge/operations/eval.md. use bashkit_eval::mira_study; use mira::{Eval, eval}; diff --git a/crates/bashkit-eval/src/mira_study.rs b/crates/bashkit-eval/src/mira_study.rs index ec92bbb8..3c54745f 100644 --- a/crates/bashkit-eval/src/mira_study.rs +++ b/crates/bashkit-eval/src/mira_study.rs @@ -14,7 +14,7 @@ // old `TaskScore::all_passed`); the score value is the weighted pass rate. // // The model matrix, scheduling, retries, and reporting are owned by the `mira` -// host CLI. See knowledge/eval.md. +// host CLI. See knowledge/operations/eval.md. use mira::subject::{Subject, subject_fn}; use mira::{Eval, Sample, Score, Target, Transcript}; diff --git a/crates/bashkit-eval/src/snapshot.rs b/crates/bashkit-eval/src/snapshot.rs index d1aecc5f..5ac66936 100644 --- a/crates/bashkit-eval/src/snapshot.rs +++ b/crates/bashkit-eval/src/snapshot.rs @@ -8,7 +8,7 @@ // `transcript.metadata["bashkit"]` as this `Snapshot` (kept out of `files` // so the file map stays a clean view of the workspace). // -// See knowledge/eval.md ("Scoring") for why the snapshot, not a live filesystem +// See knowledge/operations/eval.md ("Scoring") for why the snapshot, not a live filesystem // handle, is the scoring substrate. use std::collections::{BTreeMap, BTreeSet}; diff --git a/crates/bashkit-js/__test__/security.spec.ts b/crates/bashkit-js/__test__/security.spec.ts index 372db609..015f6270 100644 --- a/crates/bashkit-js/__test__/security.spec.ts +++ b/crates/bashkit-js/__test__/security.spec.ts @@ -5,7 +5,7 @@ * error sanitization) and black-box tests (adversarial inputs an attacker * would try without source knowledge). * - * Threat-model IDs reference knowledge/threat-model.md. + * Threat-model IDs reference knowledge/security/threat-model.md. * * Run: pnpm exec ava __test__/security.spec.ts */ diff --git a/crates/bashkit-python/Cargo.toml b/crates/bashkit-python/Cargo.toml index 5adbba9a..751cb129 100644 --- a/crates/bashkit-python/Cargo.toml +++ b/crates/bashkit-python/Cargo.toml @@ -33,7 +33,7 @@ num-bigint = "^0.4.6" # realfs: always-on so Python callers can use mount_real_* APIs. # http_client/sqlite/interop pull mio/tokio-net/rt-multi-thread/tokio::fs, # none of which compile on wasm32-unknown-emscripten — see the wasm block -# below and knowledge/emscripten-wheels.md. +# below and knowledge/runtimes/emscripten-wheels.md. [target.'cfg(not(target_arch = "wasm32"))'.dependencies] bashkit = { path = "../bashkit", features = ["scripted_tool", "python", "realfs", "jq", "interop", "http_client", "sqlite"] } tokio = { workspace = true, features = ["rt-multi-thread"] } @@ -47,7 +47,7 @@ pyo3-async-runtimes = { workspace = true } # or host filesystem access that Pyodide does not provide. Keeps the in-VFS # shell plus the embedded jq and Monty Python interpreters. tokio stays on its # wasm-safe base features (sync, macros, io-util, rt, time) — current-thread -# runtime only. See knowledge/emscripten-wheels.md. +# runtime only. See knowledge/runtimes/emscripten-wheels.md. [target.'cfg(target_arch = "wasm32")'.dependencies] bashkit = { path = "../bashkit", features = ["scripted_tool", "python", "jq"] } tokio = { workspace = true } diff --git a/crates/bashkit-python/src/lib.rs b/crates/bashkit-python/src/lib.rs index fbf20347..b4d0c949 100644 --- a/crates/bashkit-python/src/lib.rs +++ b/crates/bashkit-python/src/lib.rs @@ -8,7 +8,7 @@ // The WebAssembly (Pyodide/Emscripten) build is a reduced-feature variant: the // async `execute()` family, network/credential config, host-FS mounts, the capsule // interop bridge, sqlite, and external_handler are all native-only (they need -// threads, sockets, or host FS that Pyodide lacks — see knowledge/emscripten-wheels.md). +// threads, sockets, or host FS that Pyodide lacks — see knowledge/runtimes/emscripten-wheels.md). // That leaves a handful of imports and helper functions referenced only from the // native-gated code paths; silence the resulting dead-code/unused-import lints on // wasm rather than scattering per-item cfgs through shared conversion helpers. @@ -16,7 +16,7 @@ // interop (capsule FS handoff), realfs (host mounts) and the credential-injection // network config require threads / host FS / sockets that wasm32-unknown-emscripten -// (Pyodide) does not provide — see knowledge/emscripten-wheels.md. They are native-only. +// (Pyodide) does not provide — see knowledge/runtimes/emscripten-wheels.md. They are native-only. #[cfg(not(target_arch = "wasm32"))] use bashkit::interop::fs::{BashkitFsAbiOwnedHandleV1, export_filesystem, import_owned_filesystem}; use bashkit::tool::VERSION; @@ -41,7 +41,7 @@ use pyo3::types::{ // pyo3-async-runtimes bridges Rust futures to a Python asyncio loop; it hard-pulls // multi-threaded tokio + mio sockets, which do not build on wasm. The async // `execute()` family and caller-loop callback scheduling are therefore native-only; -// wasm exposes the blocking `execute_sync()` API. See knowledge/emscripten-wheels.md. +// wasm exposes the blocking `execute_sync()` API. See knowledge/runtimes/emscripten-wheels.md. #[cfg(not(target_arch = "wasm32"))] use pyo3_async_runtimes::TaskLocals; #[cfg(not(target_arch = "wasm32"))] @@ -390,7 +390,7 @@ impl PyNetworkConfig { /// default. Unknown keys raise `ValueError` so typos surface immediately. // The Pyodide/Emscripten build has no outbound HTTP client (no sockets in the // browser sandbox), so accepting a network allowlist would silently do nothing. -// Fail loudly instead. See knowledge/emscripten-wheels.md. +// Fail loudly instead. See knowledge/runtimes/emscripten-wheels.md. #[cfg(target_arch = "wasm32")] fn parse_network_config(network: Option<&Bound<'_, PyDict>>) -> PyResult> { if network.is_some() { @@ -985,7 +985,7 @@ fn apply_fs_config( // Host-directory mounts require the `realfs` backend (tokio::fs), unavailable // on wasm. `parse_mounts` already rejects a non-empty `mounts` list on wasm, - // so this loop is native-only. See knowledge/emscripten-wheels.md. + // so this loop is native-only. See knowledge/runtimes/emscripten-wheels.md. #[cfg(not(target_arch = "wasm32"))] for mount in real_mounts { builder = match (mount.writable, &mount.vfs_mount) { @@ -1749,7 +1749,7 @@ impl PyFileSystem { // `FileSystem.real()` needs the realfs backend (host FS), and the capsule // bridge (`from_capsule`/`to_capsule`) needs the `interop` ABI — both pull // threads/host-FS deps absent on wasm, so these constructors are native-only. - // See knowledge/emscripten-wheels.md. + // See knowledge/runtimes/emscripten-wheels.md. #[cfg(not(target_arch = "wasm32"))] #[staticmethod] #[pyo3(signature = (host_path, writable=false))] @@ -3650,7 +3650,7 @@ fn apply_sqlite_config( ) -> PyResult { // The embedded SQLite (Turso) backend needs the multi-threaded tokio runtime to // bridge its sync IO trait back to the async VFS, so the core `sqlite` feature is - // off on wasm. Reject `sqlite=True` loudly there. See knowledge/emscripten-wheels.md. + // off on wasm. Reject `sqlite=True` loudly there. See knowledge/runtimes/emscripten-wheels.md. #[cfg(target_arch = "wasm32")] { let _ = (timeout_seconds, max_memory); @@ -3802,7 +3802,7 @@ impl PyBash { ); builder = apply_sqlite_config(builder, self.sqlite, self.timeout_seconds, self.max_memory)?; // network (http_client) and allowed_mount_paths (realfs) are native-only; - // both kwargs are rejected at construction on wasm. See knowledge/emscripten-wheels.md. + // both kwargs are rejected at construction on wasm. See knowledge/runtimes/emscripten-wheels.md. #[cfg(not(target_arch = "wasm32"))] { if let Some(ref net) = self.network { @@ -3948,7 +3948,7 @@ impl PyBash { ); builder = apply_sqlite_config(builder, sqlite, timeout_seconds, max_memory)?; // network (http_client) and allowed_mount_paths (realfs) are native-only; - // both kwargs are rejected at construction on wasm. See knowledge/emscripten-wheels.md. + // both kwargs are rejected at construction on wasm. See knowledge/runtimes/emscripten-wheels.md. #[cfg(not(target_arch = "wasm32"))] { if let Some(ref net) = network { @@ -4029,7 +4029,7 @@ impl PyBash { /// /// Native-only: the async API bridges to a Python asyncio loop via /// pyo3-async-runtimes, which the WebAssembly (Pyodide) build omits. On wasm, - /// use `execute_sync()`. See knowledge/emscripten-wheels.md. + /// use `execute_sync()`. See knowledge/runtimes/emscripten-wheels.md. #[cfg(not(target_arch = "wasm32"))] #[pyo3(signature = (commands, on_output=None))] fn execute<'py>( @@ -4682,7 +4682,7 @@ impl BashTool { } // network (http_client) and allowed_mount_paths (realfs) are native-only; - // both kwargs are rejected at construction on wasm. See knowledge/emscripten-wheels.md. + // both kwargs are rejected at construction on wasm. See knowledge/runtimes/emscripten-wheels.md. #[cfg(not(target_arch = "wasm32"))] { if let Some(ref net) = self.network { @@ -4823,7 +4823,7 @@ impl BashTool { let custom_builtins = parse_custom_builtins(py, custom_builtins)?; let network = parse_network_config(network)?; // network (http_client) and allowed_mount_paths (realfs) are native-only; - // both kwargs are rejected at construction on wasm. See knowledge/emscripten-wheels.md. + // both kwargs are rejected at construction on wasm. See knowledge/runtimes/emscripten-wheels.md. #[cfg(not(target_arch = "wasm32"))] { if let Some(ref net) = network { diff --git a/crates/bashkit-python/tests/_security_core.py b/crates/bashkit-python/tests/_security_core.py index 6b2c62de..03cbc2b5 100644 --- a/crates/bashkit-python/tests/_security_core.py +++ b/crates/bashkit-python/tests/_security_core.py @@ -13,7 +13,7 @@ # Decision: keep the issue-1264 parity cases in this hidden core module while # the public `test_security.py` module re-exports the merged security suite. # New threat-model-traceable cases use `test_tm_*` names so they can map back -# to `knowledge/threat-model.md`. +# to `knowledge/security/threat-model.md`. def _assert_sanitized_error(text: str) -> None: diff --git a/crates/bashkit-python/tests/test_security.py b/crates/bashkit-python/tests/test_security.py index d33292e6..cf53d8df 100644 --- a/crates/bashkit-python/tests/test_security.py +++ b/crates/bashkit-python/tests/test_security.py @@ -4,7 +4,7 @@ # file layout matches the JS parity target while keeping the original white-box # and black-box implementations readable in hidden source modules. # Naming: `test_tm___` maps directly to -# `knowledge/threat-model.md` so grepable Python test names line up with the +# `knowledge/security/threat-model.md` so grepable Python test names line up with the # documented threat model. import sys diff --git a/crates/bashkit-wasm/Cargo.toml b/crates/bashkit-wasm/Cargo.toml index ff133576..f6fe53f3 100644 --- a/crates/bashkit-wasm/Cargo.toml +++ b/crates/bashkit-wasm/Cargo.toml @@ -5,7 +5,7 @@ # `wasm32-unknown-unknown` (pure wasm-bindgen, no WASI, no threads), so it needs # NO `SharedArrayBuffer` and NO cross-origin isolation (COOP/COEP) headers — # unlike the wasm32-wasip1-threads example. That makes it drop-in for any web -# app, including embedded/iframe contexts. See knowledge/browser-package.md. +# app, including embedded/iframe contexts. See knowledge/runtimes/browser-package.md. # # Feature surface mirrors the `wasm` CI job (scripted_tool + jq). http_client, # ssh, sqlite, python, realfs, and interop are intentionally excluded: they need diff --git a/crates/bashkit-wasm/__test__/bashkit-wasm.test.mjs b/crates/bashkit-wasm/__test__/bashkit-wasm.test.mjs index 4143c87b..c6082649 100644 --- a/crates/bashkit-wasm/__test__/bashkit-wasm.test.mjs +++ b/crates/bashkit-wasm/__test__/bashkit-wasm.test.mjs @@ -103,7 +103,7 @@ test("child shell: piping a script into bash", async () => { // Each of these used to panic and poison the whole module on wasm32: they // reached for a tokio timer (sleep/timeout), tokio::spawn (background jobs), or // std::thread::spawn (awk file redirects). On single-threaded wasm they must -// run inline instead. See knowledge/browser-package.md. +// run inline instead. See knowledge/runtimes/browser-package.md. test("sleep returns immediately (no timer driver on wasm)", async () => { const bash = new Bash(); diff --git a/crates/bashkit-wasm/src/lib.rs b/crates/bashkit-wasm/src/lib.rs index 70d6fe1e..ee49a0d1 100644 --- a/crates/bashkit-wasm/src/lib.rs +++ b/crates/bashkit-wasm/src/lib.rs @@ -1,7 +1,7 @@ //! Browser (WebAssembly) bindings for the Bashkit sandboxed bash interpreter. //! //! Important decisions (see also the crate-level notes in `Cargo.toml` and -//! `knowledge/browser-package.md`): +//! `knowledge/runtimes/browser-package.md`): //! //! - **Single-threaded, no cross-origin isolation.** Target is //! `wasm32-unknown-unknown`. There is no `SharedArrayBuffer`, no thread pool, diff --git a/crates/bashkit/Cargo.toml b/crates/bashkit/Cargo.toml index 3ce1f13d..58904c04 100644 --- a/crates/bashkit/Cargo.toml +++ b/crates/bashkit/Cargo.toml @@ -87,7 +87,7 @@ hmac = "0.13" tracing = { workspace = true, optional = true } # CLI-style argument parsing for custom builtins and ported coreutils -# argument surfaces. Always on — see knowledge/coreutils-args-port.md. +# argument surfaces. Always on — see knowledge/runtimes/coreutils-args-port.md. clap = { workspace = true } # Pinned to uutils' workspace versions. Used by the vendored @@ -155,7 +155,7 @@ typescript = ["dep:zapcode-core"] # engine). Phase 1 uses turso's `MemoryIO` with a load/flush against the VFS # at command boundaries; Phase 2 plugs the bashkit VFS in via a custom `IO` # implementation. Both paths share the same builtin and dot-command surface. -# See knowledge/sqlite-builtin.md. +# See knowledge/runtimes/sqlite-builtin.md. # # Turso is BETA upstream — keep this off by default and document the risk. # Requires the multi-threaded tokio runtime so the sync `IO` trait can bridge @@ -189,7 +189,7 @@ serial_test = { workspace = true } # This single `[[test]]` rolls them up. Tests that need their own binary # (process-global env mutation, `--test-threads=1`, ssh-only feature # isolation) remain as siblings at `tests/.rs`. See -# `knowledge/testing.md` for the convention. +# `knowledge/operations/testing.md` for the convention. [[test]] name = "integration" path = "tests/integration/main.rs" @@ -278,6 +278,6 @@ web-time = { workspace = true } # the port tool hard-errors on Fluent/translate imports — so this feature # is never defined here and the gated branch is always compiled out. Declare # it as a known cfg so `unexpected_cfgs` (denied via -D warnings in CI) does -# not flag the vendored code. See knowledge/coreutils-args-port.md. +# not flag the vendored code. See knowledge/runtimes/coreutils-args-port.md. [lints.rust] unexpected_cfgs = { level = "warn", check-cfg = ['cfg(feature, values("i18n-decimal"))'] } diff --git a/crates/bashkit/benches/sqlite.rs b/crates/bashkit/benches/sqlite.rs index cf97faf5..b841e27d 100644 --- a/crates/bashkit/benches/sqlite.rs +++ b/crates/bashkit/benches/sqlite.rs @@ -161,7 +161,7 @@ async fn bench_in_memory_only(n: usize) { async fn bench_parallel_sessions(sessions: usize, rows: usize, backend: SqliteBackend) { // Shared VFS, distinct DB file per session — tests the cooperative-IO // path without contending on a single sqlite file (which the builtin - // doesn't try to coordinate; see `knowledge/sqlite-builtin.md`). + // doesn't try to coordinate; see `knowledge/runtimes/sqlite-builtin.md`). let fs: Arc = Arc::new(InMemoryFs::new()); let handles: Vec<_> = (0..sessions) .map(|i| { diff --git a/crates/bashkit/docs/compatibility.md b/crates/bashkit/docs/compatibility.md index e9d892e0..a4c3072e 100644 --- a/crates/bashkit/docs/compatibility.md +++ b/crates/bashkit/docs/compatibility.md @@ -12,7 +12,7 @@ ## POSIX Shell Compliance Bashkit provides substantial compliance with IEEE Std 1003.1-2024 (POSIX.1-2024) -Shell Command Language. See [knowledge/limitations.md](../../../knowledge/limitations.md) +Shell Command Language. See [knowledge/operations/limitations.md](../../../knowledge/operations/limitations.md) for detailed compliance status. | POSIX Category | Status | @@ -396,7 +396,7 @@ let bash = Bash::builder() .build(); ``` -See [knowledge/threat-model.md](../../../knowledge/threat-model.md) for HTTP security details. +See [knowledge/security/threat-model.md](../../../knowledge/security/threat-model.md) for HTTP security details. --- @@ -479,5 +479,5 @@ Identified from eval analysis — all items now implemented: ## See Also -- [knowledge/limitations.md](../../../knowledge/limitations.md) - Intentional gaps and partial features +- [knowledge/operations/limitations.md](../../../knowledge/operations/limitations.md) - Intentional gaps and partial features - [Bashkit knowledge](../../../knowledge/) - Persistent design and engineering knowledge diff --git a/crates/bashkit/docs/credential-injection.md b/crates/bashkit/docs/credential-injection.md index d368e5a6..be92998c 100644 --- a/crates/bashkit/docs/credential-injection.md +++ b/crates/bashkit/docs/credential-injection.md @@ -7,7 +7,7 @@ real credentials, preventing exfiltration. **See also:** - [Threat Model](./threat-model.md) - Security properties - [Custom Builtins](./custom_builtins.md) - Extending the shell -- [Credential Injection Spec](https://github.com/everruns/bashkit/blob/main/knowledge/credential-injection.md) - Design decisions +- [Credential Injection Spec](https://github.com/everruns/bashkit/blob/main/knowledge/security/credential-injection.md) - Design decisions ## Two Modes diff --git a/crates/bashkit/docs/live_mounts.md b/crates/bashkit/docs/live_mounts.md index dda6a3b5..5d2e9d90 100644 --- a/crates/bashkit/docs/live_mounts.md +++ b/crates/bashkit/docs/live_mounts.md @@ -200,4 +200,4 @@ assert_eq!(result.stdout, "2.0"); - [`BashBuilder::readonly_filesystem`] — deny all VFS mutations after setup - [`BashBuilder::fs`] — custom filesystem injection - [`Bash::fs`] — direct filesystem access -- [VFS specification](https://github.com/everruns/bashkit/blob/main/knowledge/vfs.md) +- [VFS specification](https://github.com/everruns/bashkit/blob/main/knowledge/foundations/vfs.md) diff --git a/crates/bashkit/docs/namespace_filesystems.md b/crates/bashkit/docs/namespace_filesystems.md index 1648f535..98e9ec0c 100644 --- a/crates/bashkit/docs/namespace_filesystems.md +++ b/crates/bashkit/docs/namespace_filesystems.md @@ -86,4 +86,4 @@ access. - [`MountableFs`] — dynamic live mounts with a fallback root filesystem. - [`ReadOnlyFs`] — deny mutations for an entire filesystem. - [Live mounts](live-mounts.md) — attach and detach filesystems after build. -- [VFS specification](https://github.com/everruns/bashkit/blob/main/knowledge/vfs.md). +- [VFS specification](https://github.com/everruns/bashkit/blob/main/knowledge/foundations/vfs.md). diff --git a/crates/bashkit/docs/python.md b/crates/bashkit/docs/python.md index 4e6477ab..3b43249a 100644 --- a/crates/bashkit/docs/python.md +++ b/crates/bashkit/docs/python.md @@ -12,7 +12,7 @@ configurable resource limits and no host access. - [Threat Model](./threat-model.md) - Security considerations (TM-PY-*) - [Custom Builtins](./custom_builtins.md) - Writing your own builtins - [Compatibility Reference](./compatibility.md) - Bash feature support -- [`knowledge/python-builtin.md`][spec] - Full specification +- [`knowledge/runtimes/python-builtin.md`][spec] - Full specification ## Quick Start @@ -211,4 +211,4 @@ All Python execution runs in a virtual environment: See threat IDs TM-PY-001 through TM-PY-029 in the [threat model](./threat-model.md). -[spec]: https://github.com/everruns/bashkit/blob/main/knowledge/python-builtin.md +[spec]: https://github.com/everruns/bashkit/blob/main/knowledge/runtimes/python-builtin.md diff --git a/crates/bashkit/docs/sqlite.md b/crates/bashkit/docs/sqlite.md index 22dd0478..df967269 100644 --- a/crates/bashkit/docs/sqlite.md +++ b/crates/bashkit/docs/sqlite.md @@ -132,7 +132,7 @@ Tune per workload via `SqliteLimits::default().max_*(...)`. ## Security -See `knowledge/sqlite-builtin.md` § "Trust Model & Threats" for the full +See `knowledge/runtimes/sqlite-builtin.md` § "Trust Model & Threats" for the full threat table. Highlights: - **No host filesystem access.** All paths resolve through the bashkit diff --git a/crates/bashkit/docs/ssh.md b/crates/bashkit/docs/ssh.md index 9630dcf4..8368e450 100644 --- a/crates/bashkit/docs/ssh.md +++ b/crates/bashkit/docs/ssh.md @@ -3,7 +3,7 @@ Bashkit provides `ssh`, `scp`, and `sftp` builtins for remote command execution and file transfer over SSH. The default transport uses [russh](https://crates.io/crates/russh). -**See also:** [`knowledge/ssh-support.md`][spec] +**See also:** [`knowledge/integrations/ssh-support.md`][spec] ## Quick Start @@ -74,4 +74,4 @@ Tried in order: none (public services) → public key (`-i` flag or `default_pri - Remote paths shell-escaped (TM-SSH-008) - Response size and session count limits -[spec]: https://github.com/everruns/bashkit/blob/main/knowledge/ssh-support.md +[spec]: https://github.com/everruns/bashkit/blob/main/knowledge/integrations/ssh-support.md diff --git a/crates/bashkit/docs/threat-model.md b/crates/bashkit/docs/threat-model.md index 4bc70773..08c0da51 100644 --- a/crates/bashkit/docs/threat-model.md +++ b/crates/bashkit/docs/threat-model.md @@ -348,7 +348,7 @@ Network access is disabled by default. When enabled, strict controls apply. **Credential Injection (TM-NET-024–027):** Per-host HTTP credentials injected by the embedding host without exposing the -secret to the script (see `knowledge/credential-injection.md`). +secret to the script (see `knowledge/security/credential-injection.md`). | Threat | Attack Example | Mitigation | Status | |--------|---------------|------------|--------| @@ -945,7 +945,7 @@ All threats use stable IDs in the format `TM--`: | TM-FS | RealFs Mount Security | | TM-UNI | Unicode Security | -Full threat analysis: [`knowledge/threat-model.md`][spec] +Full threat analysis: [`knowledge/security/threat-model.md`][spec] [limits]: https://docs.rs/bashkit/latest/bashkit/struct.ExecutionLimits.html [fslimits]: https://docs.rs/bashkit/latest/bashkit/struct.FsLimits.html @@ -957,7 +957,7 @@ Full threat analysis: [`knowledge/threat-model.md`][spec] [failpoint_tests]: https://github.com/everruns/bashkit/blob/main/crates/bashkit/tests/security_failpoint_tests.rs [network_tests]: https://github.com/everruns/bashkit/blob/main/crates/bashkit/tests/network_security_tests.rs [fuzz]: https://github.com/everruns/bashkit/tree/main/crates/bashkit/fuzz -[spec]: https://github.com/everruns/bashkit/blob/main/knowledge/threat-model.md +[spec]: https://github.com/everruns/bashkit/blob/main/knowledge/security/threat-model.md [parser]: https://github.com/everruns/bashkit/blob/main/crates/bashkit/src/parser/mod.rs [interp]: https://github.com/everruns/bashkit/blob/main/crates/bashkit/src/interpreter/mod.rs [date]: https://github.com/everruns/bashkit/blob/main/crates/bashkit/src/builtins/date.rs diff --git a/crates/bashkit/docs/typescript.md b/crates/bashkit/docs/typescript.md index b3a1d456..5f256e18 100644 --- a/crates/bashkit/docs/typescript.md +++ b/crates/bashkit/docs/typescript.md @@ -13,7 +13,7 @@ resource limits and no host access. - [Threat Model](./threat-model.md) - Security considerations (TM-TS-*) - [Custom Builtins](./custom_builtins.md) - Writing your own builtins - [Compatibility Reference](./compatibility.md) - Bash feature support -- [`knowledge/zapcode-runtime.md`][spec] - Full specification +- [`knowledge/runtimes/zapcode-runtime.md`][spec] - Full specification ## Quick Start @@ -259,4 +259,4 @@ All TypeScript execution runs in a virtual environment: See threat IDs TM-TS-001 through TM-TS-023 in the [threat model](./threat-model.md). -[spec]: https://github.com/everruns/bashkit/blob/main/knowledge/zapcode-runtime.md +[spec]: https://github.com/everruns/bashkit/blob/main/knowledge/runtimes/zapcode-runtime.md diff --git a/crates/bashkit/fuzz/Cargo.toml b/crates/bashkit/fuzz/Cargo.toml index 53e1fbcd..9a6fa038 100644 --- a/crates/bashkit/fuzz/Cargo.toml +++ b/crates/bashkit/fuzz/Cargo.toml @@ -1,6 +1,6 @@ # Fuzz testing for Bashkit parser # Run with: cargo +nightly fuzz run parser_fuzz -# See knowledge/threat-model.md for security context +# See knowledge/security/threat-model.md for security context [package] name = "bashkit-fuzz" diff --git a/crates/bashkit/src/builtins/git/cmd.rs b/crates/bashkit/src/builtins/git/cmd.rs index d703f878..8a9747d2 100644 --- a/crates/bashkit/src/builtins/git/cmd.rs +++ b/crates/bashkit/src/builtins/git/cmd.rs @@ -14,7 +14,7 @@ //! # Security //! //! All operations are confined to the virtual filesystem and use -//! the configured author identity. See `knowledge/threat-model.md` +//! the configured author identity. See `knowledge/security/threat-model.md` //! Section 9: Git Security (TM-GIT-*). //! //! # Example diff --git a/crates/bashkit/src/builtins/git/config.rs b/crates/bashkit/src/builtins/git/config.rs index 1d929cc4..c45a1aee 100644 --- a/crates/bashkit/src/builtins/git/config.rs +++ b/crates/bashkit/src/builtins/git/config.rs @@ -2,7 +2,7 @@ //! //! # Security Mitigations //! -//! This module mitigates the following threats (see `knowledge/threat-model.md`): +//! This module mitigates the following threats (see `knowledge/security/threat-model.md`): //! //! - **TM-GIT-001**: Unauthorized clone → remote URL allowlist (Phase 2) //! - **TM-GIT-002**: Host identity leak → configurable virtual identity diff --git a/crates/bashkit/src/builtins/git/mod.rs b/crates/bashkit/src/builtins/git/mod.rs index 21efbc53..5c85fec0 100644 --- a/crates/bashkit/src/builtins/git/mod.rs +++ b/crates/bashkit/src/builtins/git/mod.rs @@ -42,7 +42,7 @@ //! //! # Security Threats //! -//! See `knowledge/threat-model.md` Section 9: Git Security (TM-GIT-*) +//! See `knowledge/security/threat-model.md` Section 9: Git Security (TM-GIT-*) mod config; diff --git a/crates/bashkit/src/builtins/path.rs b/crates/bashkit/src/builtins/path.rs index c7f5bc0d..8bb814b7 100644 --- a/crates/bashkit/src/builtins/path.rs +++ b/crates/bashkit/src/builtins/path.rs @@ -139,7 +139,7 @@ impl Builtin for Dirname { /// `generated/realpath_args.rs`. Behaviour is implemented locally /// against the bashkit VFS. /// -/// Symlink resolution stays disabled per L-FS-001 in `knowledge/limitations.md`'s +/// Symlink resolution stays disabled per L-FS-001 in `knowledge/operations/limitations.md`'s /// "Intentionally Unimplemented" entry: bashkit's VFS does not model /// symlinks, so `-e`/`-m` only differ on existence checks, and /// `-L`/`-P`/`--strip` collapse to the same lexical canonicalisation. diff --git a/crates/bashkit/src/builtins/pipeline.rs b/crates/bashkit/src/builtins/pipeline.rs index f0f8cc57..9b7bd8f0 100644 --- a/crates/bashkit/src/builtins/pipeline.rs +++ b/crates/bashkit/src/builtins/pipeline.rs @@ -21,7 +21,7 @@ use crate::interpreter::ExecResult; /// /// Important decision (parallelism): bashkit runs a single `Bash` interpreter /// sequentially — even background `&` jobs execute synchronously for -/// deterministic output (see `knowledge/parallel-execution.md` and +/// deterministic output (see `knowledge/foundations/parallel-execution.md` and /// `interpreter/jobs.rs`). So `-P N` does NOT spawn N OS processes for /// wall-clock speedup; instead it allocates N round-robin *slots*, and the /// commands still run in order. The slot index is exposed via diff --git a/crates/bashkit/src/builtins/sleep.rs b/crates/bashkit/src/builtins/sleep.rs index 5b2df73e..68e6b6dd 100644 --- a/crates/bashkit/src/builtins/sleep.rs +++ b/crates/bashkit/src/builtins/sleep.rs @@ -54,7 +54,7 @@ impl Builtin for Sleep { if seconds > 0.0 { // wasm32-unknown-unknown has no timer driver, so tokio::time::sleep // panics ("time not implemented"). The single-threaded sandbox has - // no wall-clock semantics anyway (see knowledge/browser-package.md), so + // no wall-clock semantics anyway (see knowledge/runtimes/browser-package.md), so // on wasm the sleep elapses instantly. #[cfg(not(target_family = "wasm"))] tokio::time::sleep(Duration::from_secs_f64(seconds)).await; diff --git a/crates/bashkit/src/builtins/sqlite/engine.rs b/crates/bashkit/src/builtins/sqlite/engine.rs index e1aea2de..8ef1d4db 100644 --- a/crates/bashkit/src/builtins/sqlite/engine.rs +++ b/crates/bashkit/src/builtins/sqlite/engine.rs @@ -1,7 +1,7 @@ //! Thin wrapper around `turso_core` that hides the choice of `IO` backend. //! //! The two backends correspond to the two phases described in -//! `knowledge/sqlite-builtin.md`: +//! `knowledge/runtimes/sqlite-builtin.md`: //! //! - **Phase 1** ([`Backend::Memory`]): use turso's `MemoryIO` and snapshot the //! raw database bytes for caller-driven persistence. This is what the diff --git a/crates/bashkit/src/builtins/sqlite/mod.rs b/crates/bashkit/src/builtins/sqlite/mod.rs index 1e9afb19..4ec01ccc 100644 --- a/crates/bashkit/src/builtins/sqlite/mod.rs +++ b/crates/bashkit/src/builtins/sqlite/mod.rs @@ -1,6 +1,6 @@ //! `sqlite` / `sqlite3` builtin — embedded SQLite via [`turso_core`]. //! -//! See `knowledge/sqlite-builtin.md` for the design rationale, threat model, and +//! See `knowledge/runtimes/sqlite-builtin.md` for the design rationale, threat model, and //! test plan. At a glance: //! //! - A single invocation opens a fresh database connection, runs every SQL diff --git a/crates/bashkit/src/builtins/sqlite/tests.rs b/crates/bashkit/src/builtins/sqlite/tests.rs index a998e65e..7d85f151 100644 --- a/crates/bashkit/src/builtins/sqlite/tests.rs +++ b/crates/bashkit/src/builtins/sqlite/tests.rs @@ -1,6 +1,6 @@ //! Unit tests for the `sqlite` builtin. //! -//! Coverage matrix (mirrors `knowledge/sqlite-builtin.md` § Test plan): +//! Coverage matrix (mirrors `knowledge/runtimes/sqlite-builtin.md` § Test plan): //! //! - **Positive** — basic CRUD, transactions, dot-commands, output modes, //! `:memory:`, persistence to VFS, `--version`/`--help`. diff --git a/crates/bashkit/src/builtins/ssh/mod.rs b/crates/bashkit/src/builtins/ssh/mod.rs index 258b64b4..d00e757a 100644 --- a/crates/bashkit/src/builtins/ssh/mod.rs +++ b/crates/bashkit/src/builtins/ssh/mod.rs @@ -26,7 +26,7 @@ //! //! # Security Threats //! -//! See `knowledge/ssh-support.md` and `knowledge/threat-model.md` (TM-SSH-*) +//! See `knowledge/integrations/ssh-support.md` and `knowledge/security/threat-model.md` (TM-SSH-*) mod allowlist; mod config; diff --git a/crates/bashkit/src/credential.rs b/crates/bashkit/src/credential.rs index 2a33f486..64f81df2 100644 --- a/crates/bashkit/src/credential.rs +++ b/crates/bashkit/src/credential.rs @@ -3,7 +3,7 @@ // Decision: Overwrite semantics — injected headers replace existing headers with same name. // Decision: Non-blocking — injection failures don't block the request. // Decision: Built on before_http hooks — no new interception points. -// See knowledge/credential-injection.md +// See knowledge/security/credential-injection.md //! Generic credential injection for outbound HTTP requests. //! diff --git a/crates/bashkit/src/fs/limits.rs b/crates/bashkit/src/fs/limits.rs index a5695dd7..8a81acaf 100644 --- a/crates/bashkit/src/fs/limits.rs +++ b/crates/bashkit/src/fs/limits.rs @@ -4,7 +4,7 @@ //! //! # Security Mitigations //! -//! This module mitigates the following threats (see `knowledge/threat-model.md`): +//! This module mitigates the following threats (see `knowledge/security/threat-model.md`): //! //! - **TM-DOS-005**: Large file creation → `max_file_size` //! - **TM-DOS-006**: Many small files → `max_file_count` diff --git a/crates/bashkit/src/fs/memory.rs b/crates/bashkit/src/fs/memory.rs index 6a8a0b2c..16152c08 100644 --- a/crates/bashkit/src/fs/memory.rs +++ b/crates/bashkit/src/fs/memory.rs @@ -5,7 +5,7 @@ //! //! # Security Mitigations //! -//! This module mitigates the following threats (see `knowledge/threat-model.md`): +//! This module mitigates the following threats (see `knowledge/security/threat-model.md`): //! //! - **TM-ESC-001**: Path traversal → `normalize_path()` collapses `..` safely //! - **TM-ESC-002**: Symlink escape → symlinks stored but not followed diff --git a/crates/bashkit/src/interpreter/mod.rs b/crates/bashkit/src/interpreter/mod.rs index 5c5c4a13..8dfa99b0 100644 --- a/crates/bashkit/src/interpreter/mod.rs +++ b/crates/bashkit/src/interpreter/mod.rs @@ -8132,7 +8132,7 @@ impl Interpreter { // panics ("time not implemented"). Run the command without wall-clock // enforcement — the parser fuel budget, maxCommands and // maxLoopIterations still bound runaway work. This matches the - // "no preemptive timeout" stance in knowledge/browser-package.md. + // "no preemptive timeout" stance in knowledge/runtimes/browser-package.md. #[cfg(target_family = "wasm")] let outcome = { let _ = (duration, preserve_status); diff --git a/crates/bashkit/src/lib.rs b/crates/bashkit/src/lib.rs index dce4ad66..86b0836b 100644 --- a/crates/bashkit/src/lib.rs +++ b/crates/bashkit/src/lib.rs @@ -439,7 +439,7 @@ pub mod scripted_tool; mod snapshot; /// Test-only helpers shared between internal `#[cfg(test)]` modules, /// integration tests in `tests/*.rs`, and cargo-fuzz targets in -/// `fuzz/fuzz_targets/*.rs`. See `knowledge/threat-model.md` for the +/// `fuzz/fuzz_targets/*.rs`. See `knowledge/security/threat-model.md` for the /// invariants enforced (TM-INF-013, TM-INF-016, TM-INF-022). #[doc(hidden)] pub mod testing; @@ -3153,7 +3153,7 @@ impl BashBuilder { // ============================================================================= // These modules embed external markdown guides into rustdoc. // Source files live in crates/bashkit/docs/ - edit there, not here. -// See knowledge/documentation.md for the documentation approach. +// See knowledge/operations/documentation.md for the documentation approach. /// Guide for transparent credential injection in outbound HTTP requests. /// diff --git a/crates/bashkit/src/limits.rs b/crates/bashkit/src/limits.rs index 64b72891..1e0e52a0 100644 --- a/crates/bashkit/src/limits.rs +++ b/crates/bashkit/src/limits.rs @@ -4,7 +4,7 @@ //! //! # Security Mitigations //! -//! This module mitigates the following threats (see `knowledge/threat-model.md`): +//! This module mitigates the following threats (see `knowledge/security/threat-model.md`): //! //! - **TM-DOS-001**: Large script input → `max_input_bytes` //! - **TM-DOS-002, TM-DOS-004, TM-DOS-019**: Command flooding → `max_commands` diff --git a/crates/bashkit/src/network/allowlist.rs b/crates/bashkit/src/network/allowlist.rs index 0f27291b..01af49b5 100644 --- a/crates/bashkit/src/network/allowlist.rs +++ b/crates/bashkit/src/network/allowlist.rs @@ -4,7 +4,7 @@ //! //! # Security Mitigations //! -//! This module mitigates the following threats (see `knowledge/threat-model.md`): +//! This module mitigates the following threats (see `knowledge/security/threat-model.md`): //! //! - **TM-NET-001**: DNS spoofing → literal host matching, no DNS resolution //! - **TM-NET-002**: DNS rebinding → allowlist uses literal strings; the diff --git a/crates/bashkit/src/network/client.rs b/crates/bashkit/src/network/client.rs index 78c834a9..91202eaf 100644 --- a/crates/bashkit/src/network/client.rs +++ b/crates/bashkit/src/network/client.rs @@ -5,7 +5,7 @@ //! //! # Security Mitigations //! -//! This module mitigates the following threats (see `knowledge/threat-model.md`): +//! This module mitigates the following threats (see `knowledge/security/threat-model.md`): //! //! - **TM-NET-008**: Large response DoS → `max_response_bytes` limit (10MB default) //! - **TM-NET-009**: Connection hang → connect timeout (10s) diff --git a/crates/bashkit/src/network/transport.rs b/crates/bashkit/src/network/transport.rs index bc90a9b9..e93eb6e5 100644 --- a/crates/bashkit/src/network/transport.rs +++ b/crates/bashkit/src/network/transport.rs @@ -1,6 +1,6 @@ //! Pluggable HTTP transport for the curl/wget/http builtins. //! -//! Design decision (see `knowledge/http-transport.md`): bashkit owns HTTP +//! Design decision (see `knowledge/security/http-transport.md`): bashkit owns HTTP //! *policy* — URL allowlist, DNS/private-IP SSRF precheck, `before_http` / //! `after_http` hooks, credential injection, bot-auth signing, and response //! size caps — while an injected [`HttpTransport`] owns *connectivity*. diff --git a/crates/bashkit/src/testing.rs b/crates/bashkit/src/testing.rs index bc6a76e2..f6ec1bf7 100644 --- a/crates/bashkit/src/testing.rs +++ b/crates/bashkit/src/testing.rs @@ -6,7 +6,7 @@ //! cross-tool invariants as the inline `#[cfg(test)]` modules without us //! duplicating the banned-substring list and the canary plumbing. //! -//! The invariants enforced here are documented in `knowledge/threat-model.md`: +//! The invariants enforced here are documented in `knowledge/security/threat-model.md`: //! - **TM-INF-022** — no Rust Debug shapes in stderr //! - **TM-INF-016** — no host paths (`/rustc/`, `~/.cargo/registry/`, //! `target/debug/deps/`) in stderr diff --git a/crates/bashkit/src/tool.rs b/crates/bashkit/src/tool.rs index 3a65a129..ec6233d0 100644 --- a/crates/bashkit/src/tool.rs +++ b/crates/bashkit/src/tool.rs @@ -489,7 +489,7 @@ impl ToolStatus { /// # Public Contract /// /// This trait is a **public library contract**. Breaking changes require a major version bump. -/// See `knowledge/tool-contract.md` for the full specification. +/// See `knowledge/integrations/tool-contract.md` for the full specification. /// /// All tools must implement this trait to be usable by LLMs and agents. /// The trait provides introspection (schemas, docs) and execution methods. diff --git a/crates/bashkit/tests/integration/coreutils_differential_tests.rs b/crates/bashkit/tests/integration/coreutils_differential_tests.rs index 77965772..6d6e3321 100644 --- a/crates/bashkit/tests/integration/coreutils_differential_tests.rs +++ b/crates/bashkit/tests/integration/coreutils_differential_tests.rs @@ -7,7 +7,7 @@ //! the args workflow only sees flag-signature changes; semantic //! divergence inside `cat.rs` / `textrev.rs` is invisible to it. //! -//! See `knowledge/coreutils-args-port.md` § Verification — Differential tests. +//! See `knowledge/runtimes/coreutils-args-port.md` § Verification — Differential tests. //! //! Currently ported utils covered: //! - cat: flags `-n`, `-b`, `-E`, `-A`, `-T`, `-v`, `-s`, `-ns`, `-bs`, diff --git a/crates/bashkit/tests/integration/credential_injection_tests.rs b/crates/bashkit/tests/integration/credential_injection_tests.rs index 946e7307..088903e3 100644 --- a/crates/bashkit/tests/integration/credential_injection_tests.rs +++ b/crates/bashkit/tests/integration/credential_injection_tests.rs @@ -1,6 +1,6 @@ //! Credential Injection Integration Tests //! -//! Tests for generic credential injection (knowledge/credential-injection.md). +//! Tests for generic credential injection (knowledge/security/credential-injection.md). //! //! Tests verify: //! - Injection mode: headers added transparently diff --git a/crates/bashkit/tests/integration/git_remote_security_tests.rs b/crates/bashkit/tests/integration/git_remote_security_tests.rs index a2070800..801cc89c 100644 --- a/crates/bashkit/tests/integration/git_remote_security_tests.rs +++ b/crates/bashkit/tests/integration/git_remote_security_tests.rs @@ -1,6 +1,6 @@ //! Git Remote Security Tests //! -//! Tests for git remote-related threats documented in knowledge/threat-model.md +//! Tests for git remote-related threats documented in knowledge/security/threat-model.md //! Section 8: Git Security (TM-GIT-010 through TM-GIT-013) #![cfg(feature = "git")] diff --git a/crates/bashkit/tests/integration/git_security_tests.rs b/crates/bashkit/tests/integration/git_security_tests.rs index 15ee2f1d..f22212a5 100644 --- a/crates/bashkit/tests/integration/git_security_tests.rs +++ b/crates/bashkit/tests/integration/git_security_tests.rs @@ -1,6 +1,6 @@ //! Git Security Tests //! -//! Tests for git-related threats documented in knowledge/threat-model.md +//! Tests for git-related threats documented in knowledge/security/threat-model.md //! Section 8: Git Security (TM-GIT-*) #![cfg(feature = "git")] diff --git a/crates/bashkit/tests/integration/limitations_doc_tests.rs b/crates/bashkit/tests/integration/limitations_doc_tests.rs index 099732cd..8e57eb51 100644 --- a/crates/bashkit/tests/integration/limitations_doc_tests.rs +++ b/crates/bashkit/tests/integration/limitations_doc_tests.rs @@ -1,4 +1,4 @@ -//! Lint for `knowledge/limitations.md` — the negative spec. +//! Lint for `knowledge/operations/limitations.md` — the negative spec. //! //! Limitations record absences, which no code-level test can witness //! directly; the next-best enforcement is keeping the document machine @@ -10,7 +10,8 @@ use std::collections::HashSet; use std::path::Path; fn limitations_doc() -> String { - let path = Path::new(env!("CARGO_MANIFEST_DIR")).join("../../knowledge/limitations.md"); + let path = + Path::new(env!("CARGO_MANIFEST_DIR")).join("../../knowledge/operations/limitations.md"); std::fs::read_to_string(&path).unwrap_or_else(|e| panic!("read {}: {e}", path.display())) } @@ -129,7 +130,7 @@ fn limitation_ids_referenced_from_code_exist_in_doc() { for id in &cited { assert!( ids.contains(id), - "{id} cited in source but missing from knowledge/limitations.md" + "{id} cited in source but missing from knowledge/operations/limitations.md" ); } } diff --git a/crates/bashkit/tests/integration/limitations_evidence_tests.rs b/crates/bashkit/tests/integration/limitations_evidence_tests.rs index f4ea96a3..e43da542 100644 --- a/crates/bashkit/tests/integration/limitations_evidence_tests.rs +++ b/crates/bashkit/tests/integration/limitations_evidence_tests.rs @@ -1,4 +1,4 @@ -//! Evidence tests for `knowledge/limitations.md`. +//! Evidence tests for `knowledge/operations/limitations.md`. //! //! Each test demonstrates one intentional limitation (L-* row) so the //! negative spec stays executable: if a limitation is ever lifted, the diff --git a/crates/bashkit/tests/integration/main.rs b/crates/bashkit/tests/integration/main.rs index 1a65a3e1..ab50693e 100644 --- a/crates/bashkit/tests/integration/main.rs +++ b/crates/bashkit/tests/integration/main.rs @@ -6,7 +6,7 @@ //! step alone blew out CI disk on the hosted runner (`rustc-LLVM ERROR: IO //! failure on output stream: No space left on device`). //! -//! Per `knowledge/testing.md`, default integration tests live as `mod`s under +//! Per `knowledge/operations/testing.md`, default integration tests live as `mod`s under //! `tests/integration/`, declared here. Tests that genuinely need their own //! binary (process-global env mutation, `--test-threads=1`, feature-isolation //! sweeps) stay as siblings at `tests/.rs`. diff --git a/crates/bashkit/tests/integration/network_security_tests.rs b/crates/bashkit/tests/integration/network_security_tests.rs index ad64d762..c6c1e0d7 100644 --- a/crates/bashkit/tests/integration/network_security_tests.rs +++ b/crates/bashkit/tests/integration/network_security_tests.rs @@ -1,6 +1,6 @@ //! Network Security Tests //! -//! Tests for HTTP-related security threats documented in knowledge/threat-model.md +//! Tests for HTTP-related security threats documented in knowledge/security/threat-model.md //! Section 5.3: HTTP Attack Vectors //! //! These tests verify: diff --git a/crates/bashkit/tests/integration/parallel_sessions_tests.rs b/crates/bashkit/tests/integration/parallel_sessions_tests.rs index e8a69589..36f6a9af 100644 --- a/crates/bashkit/tests/integration/parallel_sessions_tests.rs +++ b/crates/bashkit/tests/integration/parallel_sessions_tests.rs @@ -1,7 +1,7 @@ //! Large parallel fan-out tests. //! //! A bashkit session is a plain heap object + tokio task — no per-session OS -//! process or thread (see `knowledge/parallel-execution.md`, L-PROC-003). These +//! process or thread (see `knowledge/foundations/parallel-execution.md`, L-PROC-003). These //! tests confirm a large fan-out (1000 sessions) actually does real work and //! produces correct output, rather than spawning and returning instantly //! because every session errored out (e.g. hit a limit). The timing of this diff --git a/crates/bashkit/tests/integration/sqlite_compat_tests.rs b/crates/bashkit/tests/integration/sqlite_compat_tests.rs index 2a2f1e91..9ef45198 100644 --- a/crates/bashkit/tests/integration/sqlite_compat_tests.rs +++ b/crates/bashkit/tests/integration/sqlite_compat_tests.rs @@ -15,7 +15,7 @@ //! - `ORDER BY` / `LIMIT` / `OFFSET` syntax accepted. //! //! These are NOT exhaustive sqlite parity tests — they pin the shapes that -//! drive day-to-day usage. Add a row to `knowledge/sqlite-builtin.md` if you +//! drive day-to-day usage. Add a row to `knowledge/runtimes/sqlite-builtin.md` if you //! intentionally diverge from sqlite3 here. #![cfg(feature = "sqlite")] diff --git a/crates/bashkit/tests/integration/sqlite_integration_tests.rs b/crates/bashkit/tests/integration/sqlite_integration_tests.rs index 5bf30b1d..898dfea7 100644 --- a/crates/bashkit/tests/integration/sqlite_integration_tests.rs +++ b/crates/bashkit/tests/integration/sqlite_integration_tests.rs @@ -16,7 +16,7 @@ //! - JSON/CSV/markdown formatting //! - `:memory:` round-trip in a single invocation //! -//! See `knowledge/sqlite-builtin.md` for the test plan. +//! See `knowledge/runtimes/sqlite-builtin.md` for the test plan. #![cfg(feature = "sqlite")] diff --git a/crates/bashkit/tests/integration/sqlite_security_tests.rs b/crates/bashkit/tests/integration/sqlite_security_tests.rs index 99809824..c16a4bca 100644 --- a/crates/bashkit/tests/integration/sqlite_security_tests.rs +++ b/crates/bashkit/tests/integration/sqlite_security_tests.rs @@ -1,7 +1,7 @@ //! Threat-model tests for the `sqlite` builtin. //! //! Each `#[test]` here covers a distinct adversarial scenario from -//! `knowledge/threat-model.md` (or the new entries in `knowledge/sqlite-builtin.md`). +//! `knowledge/security/threat-model.md` (or the new entries in `knowledge/runtimes/sqlite-builtin.md`). //! Aside from confirming current mitigations, these tests act as //! regression guards: a future change that re-introduces an attack must //! flip a test red. diff --git a/crates/bashkit/tests/integration/threat_model_doc_tests.rs b/crates/bashkit/tests/integration/threat_model_doc_tests.rs index e49649bf..5efe5af3 100644 --- a/crates/bashkit/tests/integration/threat_model_doc_tests.rs +++ b/crates/bashkit/tests/integration/threat_model_doc_tests.rs @@ -2,14 +2,14 @@ //! //! Every `TM--` ID cited anywhere in this crate's source or //! tests (typically `// THREAT[TM-...]` mitigation anchors and threat-test -//! doc comments) must have an entry in `knowledge/threat-model.md`. This is the +//! doc comments) must have an entry in `knowledge/security/threat-model.md`. This is the //! same enforcement direction as `limitations_doc_tests`: code may not cite //! a ledger entry that does not exist, so restructuring the ledger can never //! silently orphan a mitigation anchor. //! //! A second test keeps the user-facing threat model //! (`crates/bashkit/docs/threat-model.md`) in one-to-one sync with the -//! canonical ledger (`knowledge/threat-model.md`): every spec threat must be +//! canonical ledger (`knowledge/security/threat-model.md`): every spec threat must be //! documented publicly, and the public doc may not invent IDs the ledger //! lacks. This closes the drift tracked in #2155. @@ -71,7 +71,7 @@ fn walk_rs_files(root: &Path, out: &mut Vec) { #[test] fn threat_ids_cited_in_code_exist_in_threat_model_doc() { let manifest = Path::new(env!("CARGO_MANIFEST_DIR")); - let doc_path = manifest.join("../../knowledge/threat-model.md"); + let doc_path = manifest.join("../../knowledge/security/threat-model.md"); let doc = std::fs::read_to_string(&doc_path) .unwrap_or_else(|e| panic!("read {}: {e}", doc_path.display())); @@ -105,7 +105,7 @@ fn threat_ids_cited_in_code_exist_in_threat_model_doc() { .collect(); assert!( missing.is_empty(), - "TM IDs cited in code but missing from knowledge/threat-model.md:\n{}", + "TM IDs cited in code but missing from knowledge/security/threat-model.md:\n{}", missing.join("\n") ); } @@ -113,7 +113,7 @@ fn threat_ids_cited_in_code_exist_in_threat_model_doc() { #[test] fn public_threat_model_doc_covers_every_spec_threat_id() { let manifest = Path::new(env!("CARGO_MANIFEST_DIR")); - let spec_path = manifest.join("../../knowledge/threat-model.md"); + let spec_path = manifest.join("../../knowledge/security/threat-model.md"); let public_path = manifest.join("docs/threat-model.md"); let spec = std::fs::read_to_string(&spec_path) .unwrap_or_else(|e| panic!("read {}: {e}", spec_path.display())); @@ -127,7 +127,7 @@ fn public_threat_model_doc_covers_every_spec_threat_id() { assert!( spec_ids.len() > 100, - "suspiciously few TM IDs in knowledge/threat-model.md ({}) — parsing broken?", + "suspiciously few TM IDs in knowledge/security/threat-model.md ({}) — parsing broken?", spec_ids.len() ); @@ -139,7 +139,7 @@ fn public_threat_model_doc_covers_every_spec_threat_id() { missing.sort_unstable(); assert!( missing.is_empty(), - "{} TM ID(s) in knowledge/threat-model.md but missing from \ + "{} TM ID(s) in knowledge/security/threat-model.md but missing from \ crates/bashkit/docs/threat-model.md — port them (see #2155):\n{}", missing.len(), missing.join("\n") @@ -154,7 +154,7 @@ fn public_threat_model_doc_covers_every_spec_threat_id() { assert!( stray.is_empty(), "{} TM ID(s) in crates/bashkit/docs/threat-model.md but absent from \ - knowledge/threat-model.md — fix the ID or add the ledger entry:\n{}", + knowledge/security/threat-model.md — fix the ID or add the ledger entry:\n{}", stray.len(), stray.join("\n") ); diff --git a/crates/bashkit/tests/integration/threat_model_tests.rs b/crates/bashkit/tests/integration/threat_model_tests.rs index 3b8ac879..a35f22f2 100644 --- a/crates/bashkit/tests/integration/threat_model_tests.rs +++ b/crates/bashkit/tests/integration/threat_model_tests.rs @@ -1,6 +1,6 @@ //! Threat Model Security Tests //! -//! Tests for threats identified in knowledge/threat-model.md +//! Tests for threats identified in knowledge/security/threat-model.md //! Each test category maps to a threat category in the threat model. //! //! Run with: `cargo test threat_` diff --git a/crates/bashkit/tests/integration/unicode_security_tests.rs b/crates/bashkit/tests/integration/unicode_security_tests.rs index 91bdd5dd..746a9975 100644 --- a/crates/bashkit/tests/integration/unicode_security_tests.rs +++ b/crates/bashkit/tests/integration/unicode_security_tests.rs @@ -1,6 +1,6 @@ //! Unicode Security Tests (TM-UNI-*) //! -//! Tests for Unicode-specific threats identified in knowledge/threat-model.md. +//! Tests for Unicode-specific threats identified in knowledge/security/threat-model.md. //! Covers byte-boundary safety, invisible characters, homoglyphs, normalization, //! and bidi attacks across parser, builtins, and VFS. //! diff --git a/crates/bashkit/tests/logging_security_tests.rs b/crates/bashkit/tests/logging_security_tests.rs index c0deec36..845ca9cb 100644 --- a/crates/bashkit/tests/logging_security_tests.rs +++ b/crates/bashkit/tests/logging_security_tests.rs @@ -3,7 +3,7 @@ //! Tests for TM-LOG-* threats to ensure sensitive data is properly redacted //! and log injection attacks are prevented. //! -//! These tests verify the security properties documented in knowledge/threat-model.md +//! These tests verify the security properties documented in knowledge/security/threat-model.md //! section 7 "Logging Security". #![cfg(feature = "logging")] diff --git a/docs/builtin_typescript.md b/docs/builtin_typescript.md index b4f01dac..f4e26f5c 100644 --- a/docs/builtin_typescript.md +++ b/docs/builtin_typescript.md @@ -260,4 +260,4 @@ TypeScript execution is fully sandboxed: - Opt-in only: requires both `typescript` Cargo feature AND `.typescript()` builder call - Path traversal (`../../../etc/passwd`) is blocked by VFS normalization -See [TM-TS threat entries](../knowledge/threat-model.md) for the full security analysis. +See [TM-TS threat entries](../knowledge/security/threat-model.md) for the full security analysis. diff --git a/docs/filesystem.md b/docs/filesystem.md index 04c9eefa..0111c43b 100644 --- a/docs/filesystem.md +++ b/docs/filesystem.md @@ -153,4 +153,4 @@ readonly_filesystem: bool # deny all VFS mutations after s - [Live mounts](live-mounts.md) — attach and detach filesystems at runtime. - [Filesystem namespaces](https://docs.rs/bashkit/latest/bashkit/namespace_filesystems_guide/) — compose and rebase static mount trees. - [Snapshotting](snapshotting.md) — serialise and restore VFS + shell state. -- Spec: [`knowledge/vfs.md`](https://github.com/everruns/bashkit/blob/main/knowledge/vfs.md). +- Spec: [`knowledge/foundations/vfs.md`](https://github.com/everruns/bashkit/blob/main/knowledge/foundations/vfs.md). diff --git a/docs/git.md b/docs/git.md index d3fe4b9c..33dc88c1 100644 --- a/docs/git.md +++ b/docs/git.md @@ -94,4 +94,4 @@ every builtin. - [Virtual filesystem](filesystem.md) — where the repository lives. - [Security](security.md) — sandbox boundaries and the `TM-GIT-*` threats. -- Spec: [`knowledge/git-support.md`](https://github.com/everruns/bashkit/blob/main/knowledge/git-support.md). +- Spec: [`knowledge/integrations/git-support.md`](https://github.com/everruns/bashkit/blob/main/knowledge/integrations/git-support.md). diff --git a/docs/request-signing.md b/docs/request-signing.md index 69ad0041..4a8f330e 100644 --- a/docs/request-signing.md +++ b/docs/request-signing.md @@ -117,7 +117,7 @@ The nonce defends against replay; the expiry window bounds signature validity. - [Networking & HTTP](networking.md) — the allowlist that gates every request. - [Credential injection](credential-injection.md) — attach bearer tokens without exposing them to scripts. -- Spec: [`knowledge/request-signing.md`](https://github.com/everruns/bashkit/blob/main/knowledge/request-signing.md). +- Spec: [`knowledge/security/request-signing.md`](https://github.com/everruns/bashkit/blob/main/knowledge/security/request-signing.md). - [RFC 9421](https://www.rfc-editor.org/rfc/rfc9421) · [RFC 7638](https://www.rfc-editor.org/rfc/rfc7638) · [web-bot-auth architecture](https://datatracker.ietf.org/doc/html/draft-meunier-web-bot-auth-architecture). diff --git a/docs/scripted-tools.md b/docs/scripted-tools.md index ff4c1995..cc5b944d 100644 --- a/docs/scripted-tools.md +++ b/docs/scripted-tools.md @@ -135,4 +135,4 @@ stack traces never reach script-visible stderr. - [Bashkit as an LLM tool](llm-tools.md) — the filesystem-backed `BashTool`. - [Virtual filesystem](filesystem.md) — why logic mode disables file access. -- Spec: [`knowledge/scripted-tool-orchestration.md`](https://github.com/everruns/bashkit/blob/main/knowledge/scripted-tool-orchestration.md). +- Spec: [`knowledge/integrations/scripted-tool-orchestration.md`](https://github.com/everruns/bashkit/blob/main/knowledge/integrations/scripted-tool-orchestration.md). diff --git a/docs/security.md b/docs/security.md index 26c91864..7f1b1706 100644 --- a/docs/security.md +++ b/docs/security.md @@ -20,7 +20,7 @@ individual threat IDs and mitigation status, see the ## Threat model -Bashkit maintains a living threat model in [`knowledge/threat-model.md`](../knowledge/threat-model.md) +Bashkit maintains a living threat model in [`knowledge/security/threat-model.md`](../knowledge/security/threat-model.md) with stable threat IDs across these categories: | Category | ID prefix | Examples | @@ -50,7 +50,7 @@ the sandbox. Key exclusions: - **`trap`** — conflicts with the stateless execution model - **Real process spawning** — all subprocess commands stay within the virtual interpreter (`TM-ESC-015`) -These decisions are documented in [`knowledge/limitations.md`](../knowledge/limitations.md). +These decisions are documented in [`knowledge/operations/limitations.md`](../knowledge/operations/limitations.md). ## Security testing @@ -60,7 +60,7 @@ Bashkit uses multiple layers of security testing: validate mitigations against documented threat IDs. Each test maps to a specific `TM-*` threat. -**Fail-point injection** — A framework defined in [`knowledge/security-testing.md`](../knowledge/security-testing.md) +**Fail-point injection** — A framework defined in [`knowledge/security/security-testing.md`](../knowledge/security/security-testing.md) that injects failures at specific points to verify the interpreter handles them safely. 14+ tests in `security_failpoint_tests.rs`. diff --git a/examples/browser/.gitignore b/examples/browser/.gitignore index 6128dcff..845fb26f 100644 --- a/examples/browser/.gitignore +++ b/examples/browser/.gitignore @@ -1,5 +1,5 @@ node_modules/ dist/ # Relaxed on purpose: no committed lockfile, so `pnpm install` always resolves -# the latest published @everruns/bashkit-wasm (see knowledge/maintenance.md). +# the latest published @everruns/bashkit-wasm (see knowledge/operations/maintenance.md). pnpm-lock.yaml diff --git a/examples/browser/README.md b/examples/browser/README.md index dedc11ee..ad75365a 100644 --- a/examples/browser/README.md +++ b/examples/browser/README.md @@ -38,7 +38,7 @@ Present: full bash syntax, the text-tool builtins (`grep`, `sed`, `awk`, `find`, Absent (need sockets, threads, or a host FS the browser sandbox lacks): `http_client` (`curl`/`wget`), `ssh`, `sqlite`, embedded `python`, `realfs` mounts. Reach the network from a custom builtin that calls the app's own -`fetch`. See `crates/bashkit-wasm/` and `knowledge/browser-package.md` for details. +`fetch`. See `crates/bashkit-wasm/` and `knowledge/runtimes/browser-package.md` for details. ## Scripts diff --git a/justfile b/justfile index 6dd53fa6..7db09934 100644 --- a/justfile +++ b/justfile @@ -104,14 +104,14 @@ clean: # Regenerate the self-hosted Python API reference (docs.rs analog for PyPI). # Output committed at site/src/content/apidocs/python.md; refresh on release. -# Needs griffe: pip install griffe. See knowledge/documentation.md. +# Needs griffe: pip install griffe. See knowledge/operations/documentation.md. apidocs-python: python3 scripts/gen_python_apidocs.py # Regenerate the self-hosted TypeScript API reference (docs.rs analog for npm). # Output committed at site/src/content/apidocs/typescript.md; refresh on release. # Requires `napi build` first (generates index.d.ts the .ts wrappers import). -# Needs network for `npx typedoc`. See knowledge/documentation.md. +# Needs network for `npx typedoc`. See knowledge/operations/documentation.md. apidocs-ts: cd crates/bashkit-js && pnpm exec napi build --platform cd crates/bashkit-js && pnpm run build:cjs @@ -231,7 +231,7 @@ bench-sqlite: # matrix, scheduling, and reporting. Install the host once: # cargo install mira-cli # provides the `mira` binary # Targets are gated on ANTHROPIC_API_KEY / OPENAI_API_KEY — set the keys for -# the models you want to run; unkeyed targets are skipped. See knowledge/eval.md. +# the models you want to run; unkeyed targets are skipped. See knowledge/operations/eval.md. # List advertised evals, samples, scorers, and targets eval-list: diff --git a/knowledge/architecture.md b/knowledge/foundations/architecture.md similarity index 100% rename from knowledge/architecture.md rename to knowledge/foundations/architecture.md diff --git a/knowledge/builtins.md b/knowledge/foundations/builtins.md similarity index 100% rename from knowledge/builtins.md rename to knowledge/foundations/builtins.md diff --git a/knowledge/foundations/index.md b/knowledge/foundations/index.md new file mode 100644 index 00000000..1e1723f9 --- /dev/null +++ b/knowledge/foundations/index.md @@ -0,0 +1,7 @@ +# Foundations + +* [Bashkit Architecture](architecture.md) - Core interpreter architecture, module boundaries, execution flow, and design principles. +* [Parser](parser.md) - Bash syntax parser and lexer architecture and compatibility decisions. +* [Virtual Filesystem](vfs.md) - Filesystem abstraction, path safety, implementations, and sandbox invariants. +* [Builtin Commands](builtins.md) - Builtin command trait, execution planning, registration, and implementation conventions. +* [Parallel Execution](parallel-execution.md) - Threading model, shared ownership, and concurrency safety requirements. diff --git a/knowledge/parallel-execution.md b/knowledge/foundations/parallel-execution.md similarity index 100% rename from knowledge/parallel-execution.md rename to knowledge/foundations/parallel-execution.md diff --git a/knowledge/parser.md b/knowledge/foundations/parser.md similarity index 100% rename from knowledge/parser.md rename to knowledge/foundations/parser.md diff --git a/knowledge/vfs.md b/knowledge/foundations/vfs.md similarity index 100% rename from knowledge/vfs.md rename to knowledge/foundations/vfs.md diff --git a/knowledge/index.md b/knowledge/index.md index 4395f576..d28d2fbf 100644 --- a/knowledge/index.md +++ b/knowledge/index.md @@ -7,50 +7,11 @@ okf_version: "0.2" * [Knowledge Maintenance Contract](knowledge-contract.md) - Rules for maintaining the Bashkit knowledge bundle and its OKF conformance. * [Update Log](log.md) - Chronological history of changes to this bundle. -# Foundations - -* [Bashkit Architecture](architecture.md) - Core interpreter architecture, module boundaries, execution flow, and design principles. -* [Parser](parser.md) - Bash syntax parser and lexer architecture and compatibility decisions. -* [Virtual Filesystem](vfs.md) - Filesystem abstraction, path safety, implementations, and sandbox invariants. -* [Builtin Commands](builtins.md) - Builtin command trait, execution planning, registration, and implementation conventions. -* [Parallel Execution](parallel-execution.md) - Threading model, shared ownership, and concurrency safety requirements. - -# Security - -* [Threat Model](threat-model.md) - Bashkit assets, trust boundaries, threats, mitigations, and stable threat identifiers. -* [Security Testing](security-testing.md) - Fail-point injection and layered security regression testing strategy. -* [Credential Injection](credential-injection.md) - Per-host HTTP credential injection without exposing secret values to sandboxed scripts. -* [Request Signing](request-signing.md) - Transparent Ed25519 HTTP message signing according to RFC 9421. -* [HTTP Transport](http-transport.md) - Pluggable host-controlled HTTP transport for curl and wget. - -# Runtimes and packages - -* [Python Builtin](python-builtin.md) - Embedded Python execution through Monty with security and resource controls. -* [ZapCode Runtime](zapcode-runtime.md) - Embedded TypeScript runtime, external functions, VFS bridging, and resource limits. -* [SQLite Builtin](sqlite-builtin.md) - Embedded SQLite through Turso with memory and virtual filesystem backends. -* [Coreutils Argument Port](coreutils-args-port.md) - Code generation design for porting uutils clap arguments and uucore modules. -* [Python Package](python-package.md) - Python bindings, PyPI wheels, ABI strategy, and platform build matrix. -* [Emscripten Wheels](emscripten-wheels.md) - Reduced-feature Pyodide and Emscripten Python wheel design and build constraints. -* [Browser Package](browser-package.md) - Slim single-threaded WebAssembly package design for browsers and JavaScript runtimes. - -# Integrations - -* [Tool Contract](tool-contract.md) - Public LLM tool trait behavior, schemas, callbacks, and error semantics. -* [Scripted Tool Orchestration](scripted-tool-orchestration.md) - Composition of tool definitions and callbacks into Bash-scripted orchestrators. -* [Git Support](git-support.md) - Sandboxed Git operations over the virtual filesystem. -* [SSH Support](ssh-support.md) - Sandboxed SSH, SCP, and SFTP operations and security boundaries. -* [Interactive Shell](interactive-shell.md) - Interactive REPL design with rustyline-based line editing. - -# Quality and operations - -* [Testing Strategy](testing.md) - Test organization, patterns, fixtures, differential testing, and CI expectations. -* [Known Limitations](limitations.md) - Intentional gaps, partial features, and Bash and POSIX compatibility stance. -* [Documentation Architecture](documentation.md) - User documentation and Rustdoc guide organization, embedding, and maintenance. -* [Maintenance](maintenance.md) - Pre-release dependency, security, compatibility, and artifact maintenance requirements. -* [Release Process](release-process.md) - Versioning, validation, tagging, and publication to crates.io, PyPI, and npm. -* [Performance Results](performance-results.md) - Benchmark harnesses, result locations, naming, and publication contract. -* [Evaluation Framework](eval.md) - LLM evaluation study design, dataset format, execution, and scoring. - -# Subdirectories +# Domains +* [foundations/](foundations/) - Core interpreter architecture, parser, filesystem, builtins, and concurrency. +* [security/](security/) - Threat model, security testing, and the credential, signing, and HTTP boundaries. +* [runtimes/](runtimes/) - Embedded language runtimes and the published language packages. +* [integrations/](integrations/) - Public tool contract and the sandboxed Git, SSH, and interactive surfaces. +* [operations/](operations/) - Testing, limitations, documentation, maintenance, release, benchmarks, and eval. * [status/](status/) - Machine-generated inventories that capture the current Bashkit implementation state. diff --git a/knowledge/git-support.md b/knowledge/integrations/git-support.md similarity index 100% rename from knowledge/git-support.md rename to knowledge/integrations/git-support.md diff --git a/knowledge/integrations/index.md b/knowledge/integrations/index.md new file mode 100644 index 00000000..1ecb43b0 --- /dev/null +++ b/knowledge/integrations/index.md @@ -0,0 +1,7 @@ +# Integrations + +* [Tool Contract](tool-contract.md) - Public LLM tool trait behavior, schemas, callbacks, and error semantics. +* [Scripted Tool Orchestration](scripted-tool-orchestration.md) - Composition of tool definitions and callbacks into Bash-scripted orchestrators. +* [Git Support](git-support.md) - Sandboxed Git operations over the virtual filesystem. +* [SSH Support](ssh-support.md) - Sandboxed SSH, SCP, and SFTP operations and security boundaries. +* [Interactive Shell](interactive-shell.md) - Interactive REPL design with rustyline-based line editing. diff --git a/knowledge/interactive-shell.md b/knowledge/integrations/interactive-shell.md similarity index 100% rename from knowledge/interactive-shell.md rename to knowledge/integrations/interactive-shell.md diff --git a/knowledge/scripted-tool-orchestration.md b/knowledge/integrations/scripted-tool-orchestration.md similarity index 98% rename from knowledge/scripted-tool-orchestration.md rename to knowledge/integrations/scripted-tool-orchestration.md index 6603cf34..3c99c1d2 100644 --- a/knowledge/scripted-tool-orchestration.md +++ b/knowledge/integrations/scripted-tool-orchestration.md @@ -20,7 +20,7 @@ Compose tool definitions (`ToolDef`) + execution callbacks into a single `Script `ScriptedTool` always runs in code/logic mode: bash is the control-flow and data-transformation language, not a VFS shell — filesystem primitives, path script execution, file redirection, and process substitution are unavailable. -`ScriptedToolBuilder` and `ScriptingToolSetBuilder` also implement the shared toolkit-library contract from [the tool contract](./tool-contract.md): locale-aware metadata, `build_service()`, `build_tool_definition()`, `build_input_schema()`, `build_output_schema()`, single-use `ToolExecution`. +`ScriptedToolBuilder` and `ScriptingToolSetBuilder` also implement the shared toolkit-library contract from [the tool contract](tool-contract.md): locale-aware metadata, `build_service()`, `build_tool_definition()`, `build_input_schema()`, `build_output_schema()`, single-use `ToolExecution`. ## Feature flag diff --git a/knowledge/ssh-support.md b/knowledge/integrations/ssh-support.md similarity index 100% rename from knowledge/ssh-support.md rename to knowledge/integrations/ssh-support.md diff --git a/knowledge/tool-contract.md b/knowledge/integrations/tool-contract.md similarity index 100% rename from knowledge/tool-contract.md rename to knowledge/integrations/tool-contract.md diff --git a/knowledge/knowledge-contract.md b/knowledge/knowledge-contract.md index 1937c839..ce6ed691 100644 --- a/knowledge/knowledge-contract.md +++ b/knowledge/knowledge-contract.md @@ -32,8 +32,29 @@ The bundle targets OKF v0.2, declared as `okf_version: "0.2"` in the bundle-root - `title`, `description`, and `tags` are recommended and used throughout this bundle; `description` is a single sentence that index entries reuse verbatim. - `index.md` files carry **no** frontmatter, except the bundle-root `index.md`, which may carry only `okf_version`. - `index.md` bodies are link lists grouped under headings: `* [Title](path) - description`. +- Every `index.md` enumerates **its own directory**: the concepts beside it and the subdirectories under it, nothing deeper. - `log.md` bodies are date-grouped entries (`## YYYY-MM-DD`), newest first. - Prose that is not a directory listing belongs in a concept document, not in an `index.md`. +- Links between concepts are relative and must resolve; links inside code spans and fenced blocks are text, not links. + +## Layout + +Concepts are grouped into domain subdirectories, each with its own `index.md`: + +| Directory | Holds | +|---|---| +| [`foundations/`](foundations/) | Interpreter architecture, parser, VFS, builtins, concurrency | +| [`security/`](security/) | Threat model, security testing, credential/signing/HTTP boundaries | +| [`runtimes/`](runtimes/) | Embedded language runtimes and the published language packages | +| [`integrations/`](integrations/) | Tool contract, Git, SSH, interactive shell | +| [`operations/`](operations/) | Testing, limitations, docs, maintenance, release, benchmarks, eval | +| [`status/`](status/) | Machine-generated inventories | + +Only this contract and `log.md` sit at the bundle root. A doc's directory conveys +its domain; its `type` conveys its kind — the two are independent, so a +`Subsystem Design` in `security/` and one in `runtimes/` share a type and differ +in placement. When adding a concept, put it in the matching domain, add it to that +directory's `index.md`, and prefer moving over duplicating if the domain changes. Type values are producer-defined. This bundle uses: `Architecture`, `Subsystem Design`, `Interface Contract`, `Package Design`, `Threat Model`, `Test Strategy`, `Limitations`, diff --git a/knowledge/log.md b/knowledge/log.md index bfd10c13..993b9c92 100644 --- a/knowledge/log.md +++ b/knowledge/log.md @@ -2,6 +2,9 @@ ## 2026-07-26 +* **Restructure**: Grouped the 29 domain concepts into `foundations/`, `security/`, `runtimes/`, `integrations/`, and `operations/`, each with its own `index.md`; the root index now enumerates root concepts and subdirectories only. Frontmatter `type` values are unchanged — directory conveys domain, `type` conveys kind. +* **Enforcement**: `scripts/check_okf.py` now rejects dangling bundle-relative links, ignoring code spans and fenced blocks. + * **Decision**: Evaluated four OKF implementations and adopted [`okf-lint`](https://github.com/rpmoore/okf-lint) as the upstream spec gate alongside `scripts/check_okf.py`, which covers the bundle-local conventions it does not enforce. Rationale and coverage tables in [Knowledge Maintenance Contract](knowledge-contract.md). ## 2026-07-25 diff --git a/knowledge/documentation.md b/knowledge/operations/documentation.md similarity index 100% rename from knowledge/documentation.md rename to knowledge/operations/documentation.md diff --git a/knowledge/eval.md b/knowledge/operations/eval.md similarity index 100% rename from knowledge/eval.md rename to knowledge/operations/eval.md diff --git a/knowledge/operations/index.md b/knowledge/operations/index.md new file mode 100644 index 00000000..1478b524 --- /dev/null +++ b/knowledge/operations/index.md @@ -0,0 +1,9 @@ +# Quality and operations + +* [Testing Strategy](testing.md) - Test organization, patterns, fixtures, differential testing, and CI expectations. +* [Known Limitations](limitations.md) - Intentional gaps, partial features, and Bash and POSIX compatibility stance. +* [Documentation Architecture](documentation.md) - User documentation and Rustdoc guide organization, embedding, and maintenance. +* [Maintenance](maintenance.md) - Pre-release dependency, security, compatibility, and artifact maintenance requirements. +* [Release Process](release-process.md) - Versioning, validation, tagging, and publication to crates.io, PyPI, and npm. +* [Performance Results](performance-results.md) - Benchmark harnesses, result locations, naming, and publication contract. +* [Evaluation Framework](eval.md) - LLM evaluation study design, dataset format, execution, and scoring. diff --git a/knowledge/limitations.md b/knowledge/operations/limitations.md similarity index 97% rename from knowledge/limitations.md rename to knowledge/operations/limitations.md index a78ac95f..6c637754 100644 --- a/knowledge/limitations.md +++ b/knowledge/operations/limitations.md @@ -66,7 +66,7 @@ supported within an exec call.) `bash -n` re-enter the Bashkit interpreter — same virtual environment, shared state and limits, never an external process. `bash --version` reports Bashkit. Security analysis: TM-ESC-015 in -[threat-model.md](threat-model.md). +[threat-model.md](../security/threat-model.md). ## POSIX Compliance Stance @@ -101,8 +101,8 @@ Target: IEEE 1003.1-2024 Shell Command Language. ## Builtins -Inventory is generated — see [status/builtins.json](status/builtins.json) -and the [builtins spec](builtins.md). No unimplemented builtins currently +Inventory is generated — see [status/builtins.json](../status/builtins.json) +and the [builtins spec](../foundations/builtins.md). No unimplemented builtins currently tracked. ## Text Processing diff --git a/knowledge/maintenance.md b/knowledge/operations/maintenance.md similarity index 100% rename from knowledge/maintenance.md rename to knowledge/operations/maintenance.md diff --git a/knowledge/performance-results.md b/knowledge/operations/performance-results.md similarity index 100% rename from knowledge/performance-results.md rename to knowledge/operations/performance-results.md diff --git a/knowledge/release-process.md b/knowledge/operations/release-process.md similarity index 100% rename from knowledge/release-process.md rename to knowledge/operations/release-process.md diff --git a/knowledge/testing.md b/knowledge/operations/testing.md similarity index 100% rename from knowledge/testing.md rename to knowledge/operations/testing.md diff --git a/knowledge/browser-package.md b/knowledge/runtimes/browser-package.md similarity index 100% rename from knowledge/browser-package.md rename to knowledge/runtimes/browser-package.md diff --git a/knowledge/coreutils-args-port.md b/knowledge/runtimes/coreutils-args-port.md similarity index 100% rename from knowledge/coreutils-args-port.md rename to knowledge/runtimes/coreutils-args-port.md diff --git a/knowledge/emscripten-wheels.md b/knowledge/runtimes/emscripten-wheels.md similarity index 100% rename from knowledge/emscripten-wheels.md rename to knowledge/runtimes/emscripten-wheels.md diff --git a/knowledge/runtimes/index.md b/knowledge/runtimes/index.md new file mode 100644 index 00000000..56b89f36 --- /dev/null +++ b/knowledge/runtimes/index.md @@ -0,0 +1,9 @@ +# Runtimes and packages + +* [Python Builtin](python-builtin.md) - Embedded Python execution through Monty with security and resource controls. +* [ZapCode Runtime](zapcode-runtime.md) - Embedded TypeScript runtime, external functions, VFS bridging, and resource limits. +* [SQLite Builtin](sqlite-builtin.md) - Embedded SQLite through Turso with memory and virtual filesystem backends. +* [Coreutils Argument Port](coreutils-args-port.md) - Code generation design for porting uutils clap arguments and uucore modules. +* [Python Package](python-package.md) - Python bindings, PyPI wheels, ABI strategy, and platform build matrix. +* [Emscripten Wheels](emscripten-wheels.md) - Reduced-feature Pyodide and Emscripten Python wheel design and build constraints. +* [Browser Package](browser-package.md) - Slim single-threaded WebAssembly package design for browsers and JavaScript runtimes. diff --git a/knowledge/python-builtin.md b/knowledge/runtimes/python-builtin.md similarity index 100% rename from knowledge/python-builtin.md rename to knowledge/runtimes/python-builtin.md diff --git a/knowledge/python-package.md b/knowledge/runtimes/python-package.md similarity index 100% rename from knowledge/python-package.md rename to knowledge/runtimes/python-package.md diff --git a/knowledge/sqlite-builtin.md b/knowledge/runtimes/sqlite-builtin.md similarity index 100% rename from knowledge/sqlite-builtin.md rename to knowledge/runtimes/sqlite-builtin.md diff --git a/knowledge/zapcode-runtime.md b/knowledge/runtimes/zapcode-runtime.md similarity index 100% rename from knowledge/zapcode-runtime.md rename to knowledge/runtimes/zapcode-runtime.md diff --git a/knowledge/credential-injection.md b/knowledge/security/credential-injection.md similarity index 100% rename from knowledge/credential-injection.md rename to knowledge/security/credential-injection.md diff --git a/knowledge/http-transport.md b/knowledge/security/http-transport.md similarity index 100% rename from knowledge/http-transport.md rename to knowledge/security/http-transport.md diff --git a/knowledge/security/index.md b/knowledge/security/index.md new file mode 100644 index 00000000..754a5098 --- /dev/null +++ b/knowledge/security/index.md @@ -0,0 +1,7 @@ +# Security + +* [Threat Model](threat-model.md) - Bashkit assets, trust boundaries, threats, mitigations, and stable threat identifiers. +* [Security Testing](security-testing.md) - Fail-point injection and layered security regression testing strategy. +* [Credential Injection](credential-injection.md) - Per-host HTTP credential injection without exposing secret values to sandboxed scripts. +* [Request Signing](request-signing.md) - Transparent Ed25519 HTTP message signing according to RFC 9421. +* [HTTP Transport](http-transport.md) - Pluggable host-controlled HTTP transport for curl and wget. diff --git a/knowledge/request-signing.md b/knowledge/security/request-signing.md similarity index 100% rename from knowledge/request-signing.md rename to knowledge/security/request-signing.md diff --git a/knowledge/security-testing.md b/knowledge/security/security-testing.md similarity index 100% rename from knowledge/security-testing.md rename to knowledge/security/security-testing.md diff --git a/knowledge/threat-model.md b/knowledge/security/threat-model.md similarity index 100% rename from knowledge/threat-model.md rename to knowledge/security/threat-model.md diff --git a/knowledge/status/builtin-inventory.md b/knowledge/status/builtin-inventory.md index 0c8213d0..b9ded6e4 100644 --- a/knowledge/status/builtin-inventory.md +++ b/knowledge/status/builtin-inventory.md @@ -25,4 +25,4 @@ $ just regen-builtins `builtins-drift.yml` fails CI when the committed file no longer matches what the code registers. Design for the builtins themselves lives in -[builtins](../builtins.md); known gaps in [limitations](../limitations.md). +[builtins](../foundations/builtins.md); known gaps in [limitations](../operations/limitations.md). diff --git a/mira.toml b/mira.toml index 08b6a705..da4621e6 100644 --- a/mira.toml +++ b/mira.toml @@ -1,6 +1,6 @@ # mira host config for the bashkit-eval study. # Saved run folders (/ with per-case results) land here so they live -# with the repo and can be resumed / re-reported. See knowledge/eval.md. +# with the repo and can be resumed / re-reported. See knowledge/operations/eval.md. [results] dir = "crates/bashkit-eval/results/mira" diff --git a/scripts/check_okf.py b/scripts/check_okf.py index fbe8d089..a5767726 100644 --- a/scripts/check_okf.py +++ b/scripts/check_okf.py @@ -30,6 +30,16 @@ RESERVED = ("index.md", "log.md") DATE_HEADING = re.compile(r"^## \d{4}-\d{2}-\d{2}\s*$") LINK = re.compile(r"\[[^\]]*\]\(([^)]+)\)") +EXTERNAL = re.compile(r"\A(?:[a-z][a-z0-9+.-]*:|//|#)") +# Fenced blocks first, then inline spans: prose about markdown (and shell +# examples containing `](`) must not be read as links. Missing this is how a +# bulk path rewrite silently corrupted a threat-model regex payload. +CODE = re.compile(r"^```.*?^```|``.*?``|`[^`\n]*`", re.DOTALL | re.MULTILINE) + + +def strip_code(text: str) -> str: + """Blank out fenced and inline code so link scanning ignores it.""" + return CODE.sub(lambda m: "\n" * m.group(0).count("\n"), text) def split_frontmatter(text: str) -> tuple[str | None, str]: @@ -81,7 +91,20 @@ def index_targets(path: pathlib.Path) -> set[str]: if not path.exists(): return set() _, body = split_frontmatter(path.read_text()) - return {t.split("#", 1)[0].rstrip("/") for t in LINK.findall(body)} + return {t.split("#", 1)[0].rstrip("/") for t in LINK.findall(strip_code(body))} + + +def check_links(path: pathlib.Path, rel: str, errors: list[str]) -> None: + """Every bundle-relative link must resolve to a file that exists.""" + _, body = split_frontmatter(path.read_text()) + for target in LINK.findall(strip_code(body)): + if EXTERNAL.match(target): + continue + resolved = target.split("#", 1)[0] + if not resolved: + continue + if not (path.parent / resolved).exists(): + errors.append(f"{rel}: link target does not exist: {target}") def check_concept(path: pathlib.Path, rel: str, errors: list[str]) -> None: @@ -164,6 +187,7 @@ def check_bundle(root: pathlib.Path) -> tuple[list[str], dict[str, int]]: else: counts["concepts"] += 1 check_concept(path, rel, errors) + check_links(path, rel, errors) except ValueError as exc: errors.append(f"{rel}: {exc}") diff --git a/scripts/gen_python_apidocs.py b/scripts/gen_python_apidocs.py index e8ebda3f..08b4c6fe 100644 --- a/scripts/gen_python_apidocs.py +++ b/scripts/gen_python_apidocs.py @@ -11,7 +11,7 @@ statically parse them (no compiled extension or third-party deps required, `allow_inspection=False`), then render markdown. Latest-only: regenerated on release, output committed to the repo so the node-only site build just renders -it. See knowledge/documentation.md ("API reference hosting"). +it. See knowledge/operations/documentation.md ("API reference hosting"). Usage: python3 scripts/gen_python_apidocs.py """ diff --git a/scripts/tests/test_check_okf.py b/scripts/tests/test_check_okf.py index 21bc325d..718fb654 100644 --- a/scripts/tests/test_check_okf.py +++ b/scripts/tests/test_check_okf.py @@ -107,6 +107,29 @@ def test_log_heading_format_enforced(self) -> None: self.assertEqual(result.returncode, 1) self.assertIn("is not '## YYYY-MM-DD'", result.stderr) + def test_dangling_link_rejected(self) -> None: + (self.bundle / "widget.md").write_text(CONCEPT + "\nSee [gone](gone.md).\n") + result = run(self.bundle) + self.assertEqual(result.returncode, 1) + self.assertIn("link target does not exist: gone.md", result.stderr) + + def test_links_inside_code_are_not_links(self) -> None: + """Prose about markdown, and shell examples containing `](`, are not links.""" + (self.bundle / "widget.md").write_text( + CONCEPT + + "\nFormat entries as `* [Title](path) - description`.\n" + + '\n```console\n$ grep "a](*b)*c" file\n```\n' + ) + result = run(self.bundle) + self.assertEqual(result.returncode, 0, result.stderr) + + def test_external_links_not_checked(self) -> None: + (self.bundle / "widget.md").write_text( + CONCEPT + "\n[spec](https://example.com/a.md) and [anchor](#widget).\n" + ) + result = run(self.bundle) + self.assertEqual(result.returncode, 0, result.stderr) + def test_unlisted_concept_rejected(self) -> None: (self.bundle / "orphan.md").write_text(CONCEPT) result = run(self.bundle) diff --git a/site/README.md b/site/README.md index 948345fa..45c47502 100644 --- a/site/README.md +++ b/site/README.md @@ -20,7 +20,7 @@ pnpm run preview # serve dist/ via wrangler `pnpm run build` regenerates `src/data/performance-timeline.json` from saved benchmark and eval artifacts before Astro builds. The `/benches` page contract is -specified in `../knowledge/performance-results.md`. +specified in `../knowledge/operations/performance-results.md`. ## Deploy diff --git a/site/src/content.config.ts b/site/src/content.config.ts index e122f2ab..bc0f4f1e 100644 --- a/site/src/content.config.ts +++ b/site/src/content.config.ts @@ -14,7 +14,7 @@ const rustdocs = defineCollection({ // API references for the PyPI/npm packages — the self-hosted analog to docs.rs // for Rust. Generated markdown (committed, regenerated on release) so the site -// build stays node-only. See knowledge/documentation.md ("API reference hosting"). +// build stays node-only. See knowledge/operations/documentation.md ("API reference hosting"). const apidocs = defineCollection({ loader: glob({ pattern: "*.md", base: "./src/content/apidocs" }), }); diff --git a/site/src/content/home.ts b/site/src/content/home.ts index 19c780ef..7d25ef6f 100644 --- a/site/src/content/home.ts +++ b/site/src/content/home.ts @@ -70,7 +70,7 @@ export const heroStats = [ { label: "Threats mitigated", value: "250+", - href: "https://github.com/everruns/bashkit/blob/main/knowledge/threat-model.md", + href: "https://github.com/everruns/bashkit/blob/main/knowledge/security/threat-model.md", external: true, }, { @@ -305,7 +305,7 @@ export const resources = [ { title: "Threat model", detail: "268 documented threat cases across parser, VFS, network, and runtimes.", - href: "https://github.com/everruns/bashkit/blob/main/knowledge/threat-model.md", + href: "https://github.com/everruns/bashkit/blob/main/knowledge/security/threat-model.md", cta: "Security spec", }, { diff --git a/site/src/pages/api/_meta.ts b/site/src/pages/api/_meta.ts index 6f338924..88c2f275 100644 --- a/site/src/pages/api/_meta.ts +++ b/site/src/pages/api/_meta.ts @@ -1,7 +1,7 @@ // Registry for the self-hosted package API references — the docs.rs analog for // the PyPI and npm packages. Rust keeps using docs.rs (external); Python and // TypeScript render generated markdown from the `apidocs` content collection -// through the same branded DocsLayout. See knowledge/documentation.md. +// through the same branded DocsLayout. See knowledge/operations/documentation.md. export type ApiRef = { // Matches the `apidocs` collection entry id and the /api/ route. diff --git a/site/src/pages/builtins.astro b/site/src/pages/builtins.astro index bf0bbaa3..5c3115f0 100644 --- a/site/src/pages/builtins.astro +++ b/site/src/pages/builtins.astro @@ -59,7 +59,7 @@ const groupedBuiltins = Object.entries( ).sort(([left], [right]) => left.localeCompare(right)); const builtinsSpecHref = - "https://github.com/everruns/bashkit/blob/main/knowledge/builtins.md"; + "https://github.com/everruns/bashkit/blob/main/knowledge/foundations/builtins.md"; const builtinsJsonHref = "https://github.com/everruns/bashkit/blob/main/knowledge/status/builtins.json"; --- diff --git a/site/src/pages/index.astro b/site/src/pages/index.astro index 6fc5560a..c6b23987 100644 --- a/site/src/pages/index.astro +++ b/site/src/pages/index.astro @@ -270,7 +270,7 @@ import { Defense in depth across every layer — process, filesystem, network, parser, and runtime. See the full threat model for 250+ mitigations.