Skip to content

🚀[Feature]: Module Contexts and User Contexts #104

@MariusStorhaug

Description

@MariusStorhaug

Description

Introduce a new context architecture for modules that cleanly separates module-level configuration (system contexts) from user-level data (user contexts). This design ensures predictable defaults, persistence of active selections, and minimal ceremony for module authors. For each module's vault, this architecture also defines a clear directory structure separating system context storage from user context storage.

Problem / Motivation

  • Need a clean separation between module configuration (system context) and user data (user context).

  • Each module should be able to:

    • Resolve a canonical default system context (default).
    • Maintain additional system contexts as selectable modes.
    • Persist the last selected system context and automatically restore it when the module loads.

Solution Summary

  • Every module gets a built-in default system context named default.

  • Modules can define and use multiple system contexts (same schema) as selectable modes (e.g., default, experimental, staging).

  • The active system context name is stored in a separate file:

    • Stores only the name of the active context (string).
    • Read automatically on module load to determine which system context to open.
    • No file locking on read (safe for concurrent module loads).
    • Independent from actual system context files (which remain self-contained).
  • User contexts are kept separate:

    • Store per-user data (accounts, tokens, preferences).
    • Not affected by which system context is active.
  • Vault directory segregation: Each module's context vault is organized into distinct folders for system contexts and user contexts.

    • System context files reside under a dedicated module/ subfolder within the vault.
    • User context files reside under a dedicated user/ subfolder.
    • The active context name metadata file is stored in the module/ folder and kept unencrypted (plaintext).

File Layout (Vault Example)

$HOME/.contextvaults/
└── <VaultName>/
    ├── module/                     # System contexts (shared module configuration)
    │   ├── active-context           # Active system context name (plaintext, not encrypted)
    │   ├── default.json             # Default system context (always present, encrypted)
    │   ├── experimental.json        # Optional alternative context (encrypted)
    │   └── staging.json             # Optional alternative context (encrypted)
    │
    ├── user/                       # User contexts (per-user data)
    │   ├── marius.json              # Example user context (encrypted)
    │   └── sigrid.json              # Example user context (encrypted)
    │
    ├── shard                        # Vault encryption key
    └── config.json                  # Vault metadata/config

Goals

  • Provide a first-class system context type for module configuration.
  • Guarantee existence of a default system context per module.
  • Support multiple system-level configurations (same schema, selectable modes).
  • Keep user contexts distinct from system contexts.
  • Persist and recall active system context in a dedicated metadata file.
  • Ensure fallback to default if metadata is missing or invalid.
  • Minimize complexity for module authors.

Acceptance Criteria

  • ✅ On module load, the active system context is read from the metadata file.
  • ✅ Metadata file contains only the active context name.
  • ✅ Metadata file is separate from context data files.
  • ✅ Metadata file is stored as plaintext (not encrypted).
  • ✅ Reads do not lock the file.
  • ✅ Missing/invalid metadata triggers fallback to default.
  • ✅ System and user context files are stored in separate module/ and user/ subdirectories for each vault.
  • ✅ Users can explicitly access either system or user contexts via the Context commands (default behavior remains user contexts).
  • ✅ Documentation updated to reflect new architecture.

Alternatives Considered

  • Embed active context name inside each context file

    • ❌ Risk of format drift, unnecessary coupling.
  • Use registry or environment variables

    • ❌ Risk of platform dependence, loss of portability.

Risks / Considerations

  • Possible stale reads if context switching happens outside managed APIs.
  • Need graceful handling for missing or corrupted metadata file (fallback to default).
  • Backward compatibility: Existing vaults should be seamlessly migrated to the new folder structure (e.g. move legacy context files into user/ subdirectory) to avoid breaking current contexts.

Additional Context

  • System context files remain self-contained and interchangeable.

  • Context selection metadata remains separate.

  • Clear boundary:

    • System contexts → Module-level configuration (shared).
    • User contexts → Per-user accounts/data.

Code-Level Changes

  • Extend Get-Context to support a new parameter -Type:

    • Default value: 'User'.

    • Allowed values: 'User', 'Module'.

    • Example:

      Get-Context -Vault MyVault -Id default -Type Module
  • Ensure that context creation, switching, and persistence APIs respect the new folder structure.

  • Add migration logic for existing vaults to move old contexts into user/ by default.

  • Update documentation, examples, and Pester tests.

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions