docs(self-packaging #50): architecture / decisions / security / CLI#60
Merged
Conversation
Part of #40. Closes #50. Captures the rationale, mechanism, and operational surface of self-packaging (#41-#49) in the locations operators and future maintainers actually look. - docs/spec/ARCHITECTURE.md * New "Self-Packaging (optional)" subsection under Key Components, naming archive_io / selfpath / bundle_locator / macho_bundle / EmbeddedArchiveFileProvider / EmbeddedFileSystem / pack with file paths. * New "Self-Packaging Bootstrap" data-flow block that traces the sequence from main() through detectAndRegisterEmbeddedBundle to FileProviderFactory dispatch to RegisterEmbeddedFileSystem. - docs/spec/DESIGN_DECISIONS.md * New §9 "Self-Packaging via Appended ZIP" with four sub-decisions: 9a. ZIP appended after the executable -- why-not tar / 7z / custom container; the `bytes_in_last_block(1)` spike gotcha. 9b. Reuse IFileProvider -- why-not extract-to-tmpdir. 9c. embed:// DuckDB FileSystem -- why-not force everything through IFileProvider (streaming); the Glob / SeekPosition spike-runtime catch. 9d. macOS reserved-segment + re-codesign -- why-not append-and- ad-hoc-sign (notarisation). * Each item lists Decision / Rationale / Why-not alternatives / Tradeoffs, matching the file's existing structure. * Summary updated to add "Deployability" as the sixth design goal that §9 serves. - docs/spec/components/security.md * New "Secrets and the bundle" section covering the two enforcement mechanisms (pack-time deny list and runtime env-var contract). Lists every credential env var with its scope. * Cross-reference to DESIGN_DECISIONS §9 and CONFIG_REFERENCE §1.4. * Best-practices list grows an 8th item ("never bundle secrets") with a forward pointer to the section. * Source-files table grows `src/pack.cpp (IsSecretExcluded)`. - docs/CLI_REFERENCE.md * New "## 3. Self-Packaging Subcommands" section with full reference for `pack`, `info`, `unpack`, plus a macOS subsection covering the reserved-segment + codesign flow and the --macos-append legacy escape hatch. * Sections 4-7 renumbered (Environment Variables / Usage Examples / Signal Handling / Exit Codes); TOC updated to match. * Environment-variables table grows FLAPI_CONFIG, FLAPI_LOG_LEVEL, SOURCE_DATE_EPOCH, CODESIGN_IDENTITY entries. - AGENTS.md (target of the CLAUDE.md symlink) * New "6. Self-Packaging" entry under Core Concepts -- short operator-style overview, command examples, mechanism, secrets invariant, reproducibility note. Forward links to DESIGN_DECISIONS §9 and CLI_REFERENCE §3 for depth.
jrosskopf
force-pushed
the
feature/gh-50-self-packaging-docs
branch
from
dcdbbae to
d19d226
Compare
10 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Part of epic #40. Stacked on #59 -> #58 -> #57 -> #56 -> #55 -> #54 -> #53 -> #52 -> #51.
Summary
Captures the rationale, mechanism, and operational surface of
self-packaging (#41-#49) where operators and future maintainers will
actually look.
docs/spec/ARCHITECTURE.mddocs/spec/DESIGN_DECISIONS.mddocs/spec/components/security.mddocs/CLI_REFERENCE.mdAGENTS.md(target of CLAUDE.md symlink)Notable bits
DESIGN_DECISIONS.md §9 is the load-bearing document. Six months
from now, when someone asks why ZIP and not 7z, why IFileProvider
reuse and not extract-to-tmpdir, why embed:// is its own filesystem
and not a code-path forced through IFileProvider, why macOS gets a
different layout -- this section answers all four with the spike's
catches encoded inline.
security.md "Secrets and the bundle" says explicitly: if a
bundled binary contains a password, it is a secret. The single
artifact value disappears the moment the artifact is sensitive. Lists
the two mechanisms that keep it that way (pack-time deny list + the
env-var contract).
CLI_REFERENCE §3 is one operator's-view-of-the-feature place. Has
shell-able examples (`scp flapi-prod user@host` etc.), the secret
deny list, the reproducibility recipe, and the macOS notarisation
flow including the `--macos-append` escape hatch with its
"Not notarisable" warning.
What's NOT in this PR
renumbers TOC where required.
precedence under `--config` / `--log-level`) are unchanged.
Closes #50. Closes the epic #40. Stacked on #59.