mia-code 0.2.0 → 0.3.0

package/rispecs/borrowed_from_opencode/066-config-env-variables.rispec.md

@@ -0,0 +1,153 @@
+# RISE-066: Config Environment Variable Substitution
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/066-config-env-variables.rispec.md
+
+## Creative Intent
+
+mia-code configuration files can reference environment variables using `${VAR_NAME}` syntax, keeping secrets out of config files and enabling environment-specific configuration without file duplication. A developer commits their config to git with `"apiKey": "${ANTHROPIC_API_KEY}"` and secrets never touch version control. Different machines, CI environments, and deployment contexts each provide their own values through the environment — same config file, different behavior.
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- API keys and secrets must be hardcoded in `~/.mia-code.json` or passed via environment variables that bypass the config system entirely
+- Config files containing secrets cannot be committed to version control or shared across machines
+- There is no way to reference dynamic values (like the current user's home directory) in config files
+- Different environments (development, CI, staging) require separate config files with identical structure but different values
+- The `MIA_CODE_*` environment variable prefix (RISE-064) handles top-level overrides but not substitution within complex nested values
+
+**Desired State:**
+- Any string value in a config file can contain `${VAR_NAME}` which is replaced with the environment variable's value at load time
+- Secrets live in the environment (`.env` files, shell profiles, CI secrets) while config structure lives in files
+- Config files are safe to commit because they contain references, not values
+- Missing variable behavior is configurable: error (fail fast) or empty string (permissive)
+- Special variables like `${HOME}`, `${PWD}`, and `${USER}` are always available regardless of environment
+
+## Desired Outcome Definition
+
+When mia-code loads a config file, all `${VAR_NAME}` patterns in string values are replaced with the corresponding environment variable values. Missing variables either cause an error or resolve to empty string based on configuration. Config files with variable references can be safely committed to version control.
+
+## Natural Language Functional Description
+
+### Substitution Syntax
+
+The pattern `${VAR_NAME}` within any string value in a config file is replaced with the value of the environment variable `VAR_NAME`:
+
+```jsonc
+{
+  "provider": {
+    "anthropic": {
+      "apiKey": "${ANTHROPIC_API_KEY}"  // Replaced at load time
+    },
+    "openai": {
+      "apiKey": "${OPENAI_API_KEY}"
+    }
+  },
+  "logDir": "${HOME}/.mia-code/logs"  // e.g., /home/dev/.mia-code/logs
+}
+```
+
+### Substitution Rules
+
+1. **Pattern matching**: Only `${...}` is recognized. `$VAR` without braces is not substituted (treated as literal).
+2. **String values only**: Substitution occurs only in JSON string values, not in keys, numbers, booleans, or null.
+3. **Partial substitution**: A string can contain multiple variables and literal text: `"${HOME}/projects/${PROJECT_NAME}/config"`.
+4. **No nested substitution**: The result of a substitution is not re-scanned for further `${...}` patterns. This prevents injection and keeps behavior predictable.
+5. **Escape sequence**: `\${VAR}` is treated as the literal string `${VAR}` (the backslash is consumed).
+
+### Missing Variable Handling
+
+When a `${VAR_NAME}` references an undefined environment variable:
+
+- **Default behavior (strict)**: Emit a warning and leave the pattern unreplaced. The literal string `${VAR_NAME}` remains in the config value, which will likely cause a downstream error (e.g., invalid API key).
+- **Permissive mode**: `{"config": {"envSubstitution": "permissive"}}` — replace missing variables with empty string `""`.
+- **Error mode**: `{"config": {"envSubstitution": "error"}}` — throw a config loading error that prevents startup.
+
+The mode is configured via the built-in defaults or a higher-precedence config level that has already been loaded.
+
+### Special Variables
+
+These variables are always available, even if not set in the environment:
+
+| Variable | Value | Example |
+|----------|-------|---------|
+| `${HOME}` | User's home directory | `/home/developer` |
+| `${PWD}` | Current working directory | `/projects/myapp` |
+| `${USER}` | Current username | `developer` |
+| `${HOSTNAME}` | Machine hostname | `dev-laptop` |
+| `${MIA_CODE_VERSION}` | Current mia-code version | `1.2.3` |
+
+If these conflict with actual environment variables, the environment variable value takes precedence.
+
+### Substitution Timing
+
+Variable substitution occurs at config load time, after JSONC parsing and before deep merging:
+
+1. Parse JSONC → raw config object
+2. Walk all string values and apply `${...}` substitution
+3. Merge with other config levels (RISE-064)
+4. Validate the merged result
+
+This means the same `${VAR}` in different config levels resolves to the same value (they share the same environment).
+
+### Security Considerations
+
+- Config files with `${...}` references are safe to commit because they contain no actual secrets
+- The `/config` command masks resolved secret values (API keys, tokens) in its display: `apiKey: sk-****`
+- Environment variable values are never logged at info level; debug logging masks them
+- Substitution does not apply to values in non-config contexts (session data, message content)
+
+### Error Reporting
+
+When substitution encounters issues:
+
+```
+Config warning: Undefined environment variable in ~/.config/mia-code/config.json:
+  Line 5: "apiKey": "${ANTHROPIC_API_KEY}"
+  Variable ANTHROPIC_API_KEY is not set.
+  
+  Tip: Set it in your shell profile or .env file:
+    export ANTHROPIC_API_KEY=your-key-here
+```
+
+Warnings include the file, line number, variable name, and a helpful suggestion.
+
+### Integration with .env Files
+
+mia-code optionally loads `.env` files before config substitution:
+1. Check for `.env` in the project root
+2. Check for `.env.local` in the project root (higher precedence)
+3. Parse key=value pairs and add them to the substitution environment
+4. `.env` values do not override actual environment variables
+
+This is opt-in via config: `{"config": {"loadDotEnv": true}}` (default: false).
+
+### Config Display
+
+The `/config` command shows both the template value and the resolved value for substituted settings:
+
+```
+provider.anthropic.apiKey: ${ANTHROPIC_API_KEY} → sk-**** [global config]
+logDir: ${HOME}/.mia-code/logs → /home/dev/.mia-code/logs [global config]
+```
+
+## Supporting Structures
+
+- **JSONC Config (RISE-065)** parses config files before substitution is applied
+- **Multi-Level Config (RISE-064)** defines when in the loading pipeline substitution occurs
+- **Config Deep Merging (RISE-067)** merges config after substitution resolves values
+- **Managed Config Directory (RISE-070)** uses the same substitution system for enterprise config
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — Git-Safe Config:**
+A team commits `./mia-code.json` to their repository: `{"provider": {"anthropic": {"apiKey": "${ANTHROPIC_API_KEY}"}}}`. Each developer has `ANTHROPIC_API_KEY` in their shell profile. The config is shared, the secrets are not. New team members clone the repo, set their key, and start working.
+
+**Scenario 2 — CI/CD Pipeline:**
+A GitHub Actions workflow sets `ANTHROPIC_API_KEY` as a repository secret. The mia-code config file in the repo references `${ANTHROPIC_API_KEY}`. The CI runner resolves it at runtime. No config file changes needed between local development and CI.
+
+**Scenario 3 — Multi-Environment Config:**
+A developer works on two projects: one using Anthropic, one using OpenAI. Both config files reference `${ANTHROPIC_API_KEY}` and `${OPENAI_API_KEY}` respectively. The developer's shell profile exports both. Each project resolves only the key it needs.
+
+**Scenario 4 — Dynamic Paths:**
+A developer's config uses `"logDir": "${HOME}/.mia-code/logs"`. On their Linux workstation, logs go to `/home/dev/.mia-code/logs`. On their Mac, logs go to `/Users/dev/.mia-code/logs`. Same config file, platform-appropriate paths.

package/rispecs/borrowed_from_opencode/067-config-deep-merging.rispec.md

@@ -0,0 +1,178 @@
+# RISE-067: Config Deep Merging
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/067-config-deep-merging.rispec.md
+
+## Creative Intent
+
+mia-code assembles its final configuration by intelligently merging contributions from multiple sources — not by crude overwriting but by recursive deep merging that preserves structure, combines collections, and applies targeted overrides. A global config provides the foundation, a project config adjusts specific settings, and the result is a coherent whole where each source contributes its piece without destroying the others' contributions.
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- mia-code loads config from a single source (`~/.mia-code.json`) so no merging is needed
+- If multi-source loading were added naively, a project config with one key would erase all global settings (shallow replace)
+- There is no defined behavior for merging arrays — should a project's plugin list replace or extend the global list?
+- Nested objects (like provider configurations with multiple sub-providers) would be lost if any level provides a partial override
+- No mechanism exists to intentionally remove a setting from a lower level (e.g., disable a globally enabled plugin for one project)
+- The relationship between "combine" and "override" is ambiguous without explicit rules
+
+**Desired State:**
+- Objects merge recursively: project config sets `provider.anthropic.model` without erasing `provider.openai`
+- Arrays concatenate by default: project plugins add to global plugins
+- Scalars replace: last source wins for simple values
+- Explicit removal: setting a key to `null` removes it from the merged result
+- Explicit array replacement: empty array `[]` replaces rather than concatenating
+- Merge order follows the precedence hierarchy from RISE-064
+
+## Desired Outcome Definition
+
+A deep merge function combines configuration objects from multiple sources following deterministic rules. Objects merge recursively, arrays concatenate, scalars replace. Special sentinels (null, empty array) provide escape hatches for removal and replacement. The merge produces a single resolved config object.
+
+## Natural Language Functional Description
+
+### Merge Algorithm
+
+The deep merge processes two config objects (base and override) recursively:
+
+```
+function deepMerge(base, override):
+  for each key in override:
+    if override[key] is null:
+      delete result[key]                    // null removes
+    else if override[key] is object AND base[key] is object:
+      result[key] = deepMerge(base[key], override[key])  // recurse
+    else if override[key] is array AND base[key] is array:
+      if override[key] is empty:
+        result[key] = []                    // empty array replaces
+      else:
+        result[key] = base[key].concat(override[key])    // concatenate
+    else:
+      result[key] = override[key]           // scalar replace
+  for each key in base not in override:
+    result[key] = base[key]                 // preserve base values
+  return result
+```
+
+### Merge Rules by Type
+
+**Objects → Recursive Merge:**
+Each key in the override object is merged with the corresponding key in the base object. Keys present only in the base are preserved. Keys present only in the override are added.
+
+```
+Base:     {"provider": {"openai": {"apiKey": "sk-1"}, "model": "gpt-4"}}
+Override: {"provider": {"anthropic": {"apiKey": "sk-2"}}}
+Result:   {"provider": {"openai": {"apiKey": "sk-1"}, "model": "gpt-4", "anthropic": {"apiKey": "sk-2"}}}
+```
+
+**Scalars → Replace:**
+When the override provides a scalar value (string, number, boolean) for a key, it replaces the base value entirely, regardless of the base value's type.
+
+```
+Base:     {"model": "gemini-2.5-pro", "verbose": false}
+Override: {"model": "claude-sonnet-4", "verbose": true}
+Result:   {"model": "claude-sonnet-4", "verbose": true}
+```
+
+**Arrays → Concatenate:**
+When both base and override have arrays for the same key, the arrays are concatenated (base first, then override).
+
+```
+Base:     {"plugins": ["plugin-a", "plugin-b"]}
+Override: {"plugins": ["plugin-c"]}
+Result:   {"plugins": ["plugin-a", "plugin-b", "plugin-c"]}
+```
+
+Deduplication is not performed automatically — if both lists contain `"plugin-a"`, it appears twice. Consumers should handle deduplication if needed.
+
+**Null → Remove Key:**
+Setting a key to `null` in the override removes it from the merged result entirely. This is an explicit removal signal.
+
+```
+Base:     {"provider": {"openai": {"apiKey": "sk-1"}, "anthropic": {"apiKey": "sk-2"}}}
+Override: {"provider": {"openai": null}}
+Result:   {"provider": {"anthropic": {"apiKey": "sk-2"}}}
+```
+
+**Empty Array → Replace:**
+An empty array `[]` in the override replaces the base array entirely (does not concatenate). This allows a project to clear a global list.
+
+```
+Base:     {"plugins": ["plugin-a", "plugin-b"]}
+Override: {"plugins": []}
+Result:   {"plugins": []}
+```
+
+### Multi-Level Merge
+
+When merging more than two levels, the merge is applied sequentially from lowest to highest precedence:
+
+```
+result = defaults
+result = deepMerge(result, globalConfig)
+result = deepMerge(result, envVars)
+result = deepMerge(result, projectConfig)
+result = deepMerge(result, cliFlags)
+result = deepMerge(result, inlineConfig)
+```
+
+Each merge produces an intermediate result that becomes the base for the next level.
+
+### Type Coercion at Merge Boundaries
+
+When base and override have different types for the same key:
+- **Object vs. scalar**: override wins (scalar replaces object or vice versa)
+- **Array vs. scalar**: override wins
+- **Array vs. object**: override wins
+- A warning is emitted when types conflict, as this usually indicates a config error
+
+### Merge Source Tracking
+
+During merging, each resolved value is annotated with its source level:
+
+```typescript
+interface ResolvedValue {
+  value: any;
+  source: "default" | "global" | "env" | "project" | "cli" | "inline" | "managed";
+  filePath?: string;  // for file-based sources
+}
+```
+
+These annotations power the `/config` display (RISE-064) that shows where each value came from.
+
+### Permission Ruleset Merging
+
+Permission rulesets (RISE-011) receive special merge treatment:
+- Permission rules from all levels are combined
+- Agent-specific permission overrides take precedence over general rules
+- Deny rules from any level cannot be overridden by allow rules from a lower-precedence level
+- Managed config (RISE-070) deny rules cannot be overridden at all
+
+### Edge Cases
+
+- **Circular references**: not possible in JSON — not a concern
+- **Very deep nesting** (>10 levels): supported but a warning is emitted as this likely indicates a config error
+- **Large arrays** (>1000 elements): concatenation proceeds but a performance warning is emitted
+- **Undefined vs. missing**: a key absent from the override is different from a key set to `undefined`. Only `null` triggers removal.
+
+## Supporting Structures
+
+- **Multi-Level Config (RISE-064)** defines the precedence order and invokes deep merge at each level
+- **JSONC Config (RISE-065)** provides the parsed objects that are inputs to the merge
+- **Config Environment Variables (RISE-066)** resolves variable references before objects enter the merge
+- **Managed Config Directory (RISE-070)** provides the highest-precedence config object for merging
+- **Agent Permission Rulesets (RISE-011)** defines special merging rules for permission config
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — Additive Provider Configuration:**
+A developer's global config sets up OpenAI: `{"provider": {"openai": {"apiKey": "sk-1"}}}`. Their project config adds Anthropic: `{"provider": {"anthropic": {"apiKey": "sk-2"}}}`. After deep merge, both providers are available. Neither config file needs to know about the other's providers.
+
+**Scenario 2 — Disabling a Global Plugin:**
+A developer's global config includes `{"plugins": ["linter", "formatter"]}`. A specific project doesn't want any plugins: `{"plugins": []}`. The empty array replaces the global list. No plugins load for that project.
+
+**Scenario 3 — Removing a Provider:**
+A developer's global config has three providers. A project should only use Anthropic, so its config sets: `{"provider": {"openai": null, "google": null}}`. After merge, only Anthropic remains from the global config.
+
+**Scenario 4 — Combined Permission Rules:**
+Global config allows `git *` commands. Project config allows `npm *` additionally. After merge, both `git *` and `npm *` are allowed — the project inherits global permissions and adds its own.

package/rispecs/borrowed_from_opencode/068-remote-org-config.rispec.md

@@ -0,0 +1,183 @@
+# RISE-068: Remote Organization Config
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/068-remote-org-config.rispec.md
+
+## Creative Intent
+
+mia-code fetches organization-wide configuration defaults from a remote endpoint, enabling enterprise teams to share consistent settings without manual distribution. When a developer clones a company repository and runs mia-code, the tool automatically discovers the organization's default models, allowed providers, security policies, and standard agents — creating alignment across hundreds of developers with zero individual setup. The organization speaks once, and every developer's mia-code listens.
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- There is no mechanism for an organization to distribute mia-code configuration to its developers
+- Each developer must manually configure their own `~/.mia-code.json` independently
+- Organizational policies (which models are allowed, which tools are restricted) must be communicated out-of-band (Slack, wiki, onboarding docs)
+- There is no enforcement of consistent agent behavior across a team
+- New team members spend time configuring mia-code instead of coding
+- Policy changes (e.g., "switch to Claude for all projects") require manual updates on every developer's machine
+
+**Desired State:**
+- Organizations publish config at a well-known URL: `https://company.com/.well-known/mia-code.json`
+- mia-code discovers the organization from the git remote URL and fetches the org config
+- Org config provides defaults: models, providers, permissions, agents, plugins
+- Org config has low precedence — overridden by global, project, and CLI config
+- Config is cached locally with a 24-hour TTL to avoid network dependency
+- If the fetch fails, cached config is used; if no cache exists, the level is skipped gracefully
+
+## Desired Outcome Definition
+
+When a developer runs mia-code in a project with a git remote pointing to an organization's domain, the tool fetches org-wide config defaults from `https://<domain>/.well-known/mia-code.json`. This config is merged into the config hierarchy at the lowest file-based precedence level (below global config). The config is cached for offline use.
+
+## Natural Language Functional Description
+
+### Organization Discovery
+
+When mia-code initializes in a project directory:
+1. Check for a git repository (look for `.git` directory)
+2. Read the `origin` remote URL: `git remote get-url origin`
+3. Extract the hostname from the remote URL (e.g., `github.com/acme-corp/project` → `github.com`)
+4. For known hosting platforms (GitHub, GitLab, Bitbucket), extract the organization: `acme-corp`
+5. Construct the config URL: `https://github.com/acme-corp/.well-known/mia-code.json` or check org-level metadata
+
+For self-hosted git servers, the hostname itself is used: `https://git.acme.com/.well-known/mia-code.json`
+
+### Config Endpoint
+
+Organizations publish their config as a JSON (or JSONC) file at a well-known path:
+
+```
+https://<domain>/.well-known/mia-code.json
+```
+
+The file follows the standard mia-code config schema:
+
+```jsonc
+{
+  // Acme Corp mia-code defaults
+  "orgName": "Acme Corp",
+  "policyVersion": "2025-01-15",
+
+  "model": "claude-sonnet-4",
+  "engine": "claude",
+
+  "provider": {
+    "anthropic": {
+      // Org-provisioned API endpoint
+      "baseUrl": "https://api.acme-internal.com/claude/v1"
+    }
+  },
+
+  // Restrict to approved providers only
+  "allowedProviders": ["anthropic", "google"],
+  "blockedProviders": ["openai"],
+
+  // Default permission policy
+  "permissions": {
+    "bash": "ask",
+    "file_write": "ask",
+    "file_read": "allow"
+  },
+
+  // Standard agents for the organization
+  "agents": [
+    {
+      "name": "acme-reviewer",
+      "prompt": "Review code following Acme Corp coding standards..."
+    }
+  ]
+}
+```
+
+### Precedence
+
+Org config sits at the lowest file-based level, below global config:
+
+```
+Built-in defaults (lowest)
+  ↓
+Remote org config          ← this level
+  ↓
+Global config (~/.config/mia-code/config.json)
+  ↓
+Environment variables
+  ↓
+Project config (./mia-code.json)
+  ↓
+CLI flags
+  ↓
+Inline config
+  ↓
+Managed config (highest)
+```
+
+This means individual developers can always override org defaults with their personal preferences or project-specific settings.
+
+### Caching
+
+Fetched org config is cached locally:
+- Cache location: `~/.cache/mia-code/org-config/<domain-hash>.json`
+- Cache TTL: 24 hours (configurable via `{"config": {"orgConfigTTL": 86400}}`)
+- Cache metadata: includes fetch timestamp, ETag/Last-Modified headers for conditional requests
+- On cache hit: use cached config without network request
+- On cache expired: attempt fetch; if successful, update cache; if failed, use stale cache with a warning
+- Cache can be forced-refreshed: `/config refresh-org`
+
+### Fetch Behavior
+
+The config fetch is designed to be non-blocking and fault-tolerant:
+1. Fetch timeout: 5 seconds (org config should not delay startup significantly)
+2. On network error: warn and skip (use cache if available)
+3. On 404: assume no org config exists; do not retry for 7 days
+4. On 5xx: use cache if available; retry on next startup
+5. Fetch happens in parallel with other initialization — does not block the agent from starting
+6. If config arrives after the agent has started, a config reload is triggered
+
+### Security
+
+- Org config is fetched over HTTPS only (HTTP URLs are rejected)
+- Config content is validated against the expected schema before use
+- Org config cannot set API keys or secrets (these fields are ignored if present)
+- A warning is shown on first fetch: "Loading organization config from https://... [y to accept / n to skip]"
+- Accepted organizations are remembered: `~/.config/mia-code/trusted-orgs.json`
+- Org config modifications are logged for auditability
+
+### GitHub Integration
+
+For GitHub-hosted organizations, mia-code can alternatively fetch org config from:
+1. A `.mia-code` repository in the organization (e.g., `github.com/acme-corp/.mia-code`)
+2. The `mia-code.json` file in the organization's `.github` repository
+3. Organization-level metadata (if accessible via GitHub API)
+
+The priority: `.well-known` endpoint > `.mia-code` repo > `.github` repo.
+
+### Config Display
+
+The `/config` command annotates org-sourced values:
+
+```
+model: claude-sonnet-4    [org: Acme Corp (policy v2025-01-15)]
+engine: claude             [org: Acme Corp (policy v2025-01-15)]
+theme: monokai             [global: ~/.config/mia-code/config.json]
+```
+
+## Supporting Structures
+
+- **Multi-Level Config (RISE-064)** defines where org config sits in the precedence hierarchy
+- **Config Deep Merging (RISE-067)** merges org config with other levels
+- **JSONC Config (RISE-065)** parses the org config file (may contain comments)
+- **Managed Config Directory (RISE-070)** provides an even higher-precedence enterprise override
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — Seamless Team Onboarding:**
+A new developer joins Acme Corp, clones a project, and runs `mia-code`. The tool detects the `acme-corp` GitHub organization, fetches org config, and automatically uses the company's preferred model and API endpoint. The developer starts coding immediately — no config setup needed.
+
+**Scenario 2 — Organization Policy Update:**
+Acme Corp decides to switch from Gemini to Claude for all agent interactions. They update `/.well-known/mia-code.json` on their domain. Over the next 24 hours (as caches expire), every developer's mia-code picks up the change automatically.
+
+**Scenario 3 — Provider Restriction:**
+An enterprise blocks OpenAI for compliance reasons. Their org config includes `"blockedProviders": ["openai"]`. Even if a developer has an OpenAI API key in their global config, mia-code will not use it in projects under this organization.
+
+**Scenario 4 — Offline Development:**
+A developer works on a plane without internet. mia-code attempts to fetch org config, fails, and falls back to the cached version from yesterday. Everything works as expected. When they reconnect, the cache refreshes automatically on next startup.