milknado 0.1.0__tar.gz

milknado-0.1.0/.agents/plugins/marketplace.json

@@ -0,0 +1,18 @@
+{
+  "interface": {
+    "displayName": "milknado"
+  },
+  "plugins": [
+    {
+      "source": {
+        "source": "local",
+        "path": "./plugins/milknado"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "developer-tools"
+    }
+  ]
+}

milknado-0.1.0/.claude-plugin/marketplace.json

@@ -0,0 +1,12 @@
+{
+  "name": "milknado",
+  "owner": {
+    "name": "paulnsorensen"
+  },
+  "plugins": [
+    {
+      "name": "milknado",
+      "source": "./plugins/milknado"
+    }
+  ]
+}

milknado-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,70 @@
+name: Bug report
+description: Something is broken or behaves incorrectly
+labels: [bug]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to file a bug. Please fill out the fields
+        below — the more concrete the repro, the faster the fix.
+
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened?
+      description: A clear description of the bug.
+      placeholder: When I run X, Y happens instead of Z.
+    validations:
+      required: true
+
+  - type: textarea
+    id: repro
+    attributes:
+      label: Steps to reproduce
+      description: Minimal, copy-pasteable steps.
+      placeholder: |
+        1. ...
+        2. ...
+        3. ...
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behaviour
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: Version / commit
+      description: Output of `milknado --version` or the commit SHA.
+    validations:
+      required: true
+
+  - type: input
+    id: environment
+    attributes:
+      label: OS / runtime
+      description: e.g. macOS 14.5, Ubuntu 24.04, Python 3.12
+    validations:
+      required: false
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Logs / output
+      description: Paste relevant log output. Will be auto-formatted as code.
+      render: shell
+
+  - type: checkboxes
+    id: checks
+    attributes:
+      label: Pre-flight
+      options:
+        - label: I searched existing issues and this is not a duplicate
+          required: true
+        - label: I am running the latest released version
+          required: false

milknado-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Question or support
+    url: https://github.com/paulnsorensen/milknado/issues
+    about: Search existing issues or open a new one if none fit.
+  - name: Security vulnerability
+    url: https://github.com/paulnsorensen/milknado/security/advisories/new
+    about: Report a vulnerability privately via a draft security advisory.

milknado-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,39 @@
+name: Feature request
+description: Suggest an enhancement or new capability
+labels: [enhancement]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: What problem does this solve?
+      description: Describe the user-facing pain, not the implementation.
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+      description: What would you like to see happen?
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Other approaches you weighed and why they did not fit.
+
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional context
+      description: Links, screenshots, prior art.
+
+  - type: checkboxes
+    id: checks
+    attributes:
+      label: Pre-flight
+      options:
+        - label: I searched existing issues and this is not a duplicate
+          required: true

milknado-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,29 @@
+<!-- markdownlint-disable-file MD041 -->
+<!--
+Thanks for opening a PR. Please fill out the sections below — short is fine,
+but blank is not. The reviewer should be able to understand intent and risk
+from the description alone.
+-->
+
+## What changed
+
+<!-- One or two sentences. The "what". -->
+
+## Why
+
+<!-- The motivation. Link any tracking issue: `Fixes #123`. -->
+
+## How to verify
+
+<!-- Commands the reviewer can run, or what to click in the UI. -->
+
+## Risk / rollout notes
+
+<!-- Anything reviewers should pay extra attention to. Write "none" if there is none. -->
+
+## Checklist
+
+- [ ] Conventional Commits PR title (`feat:`, `fix:`, `chore:`, `docs:`, ...)
+- [ ] Tests added or updated (or N/A)
+- [ ] Documentation updated (or N/A)
+- [ ] No secrets or credentials added

milknado-0.1.0/.github/copilot-instructions.md

@@ -0,0 +1,72 @@
+# Copilot Instructions
+
+## Engineering Principles
+
+1. **Input Validation** - Trust nothing from external sources. Validate at system boundaries (user input, external APIs, file I/O). Internal code trusts internal code.
+2. **Fail Fast and Loud** - Handle errors where they occur. No silent failures, no swallowed exceptions, no empty catch blocks. If something fails, the caller should know immediately.
+3. **Loose Coupling** - Separate business logic from infrastructure. Core models and domain logic must not import HTTP frameworks, ORMs, or I/O libraries. Use dependency injection or protocols/interfaces at boundaries.
+4. **YAGNI** - Build only what is needed now. No abstract base classes with one implementation, no plugin systems with one plugin, no configuration options that are never varied. If it is needed later, it can be written later.
+5. **Real-World Models** - Name things after business concepts, not technical abstractions. `Order`, not `DataProcessor`. `PricingRule`, not `StrategyHandler`.
+6. **Immutable Patterns** - Minimize state mutation. Prefer pure functions, return new values instead of mutating arguments, use immutable data structures where the language supports them.
+
+## Complexity Budget
+
+- **Functions**: Maximum 40 lines
+- **Files**: Maximum 300 lines
+- **Parameters**: Maximum 4 per function
+- **Nesting**: Maximum 3 levels deep
+
+If a function or file exceeds these limits, decompose it.
+
+## Code Style
+
+- **Classes**: PascalCase
+- **Functions**: snake_case
+- **Constants**: SCREAMING_SNAKE_CASE
+- **Files**: kebab-case (or snake_case for Python modules, matching the existing tree)
+- **Commits**: Conventional Commits format (`feat:`, `fix:`, `chore:`, etc.)
+
+## Architecture
+
+Follow vertical slice architecture:
+
+- Each domain concept gets its own module/directory (see `src/milknado/domains/`)
+- Public API is exposed through an `__init__.py` barrel file only
+- Do not reach into another slice's internals — import from its public API
+- Core models stay pure: no ORM decorators, no framework imports, no I/O
+- `common/` is a leaf — it imports nothing from sibling domains
+- One-directional dependencies only; cross-slice translation lives in an explicit bridge module (e.g. `domains/planning/batching_bridge.py`), never inside the pure slice
+
+**Growth pattern:**
+
+1. Start with one file per concept
+2. Extract a sibling file when the original gets crowded
+3. When a file needs helpers, it becomes a facade with a subdirectory
+
+## What NOT to Do
+
+- Do not add docstrings to private methods or small helpers with clear names
+- Do not create abstract base classes, factories, or registries unless there are multiple concrete implementations today
+- Do not add error handling for conditions that cannot occur in the current system
+- Do not add backwards-compatibility shims — change the code directly
+- Do not wrap functions that add no logic — call the original directly
+- Do not add type annotations to every local variable — annotate function signatures and let inference handle the rest
+
+## Tech Stack
+
+- **Language**: Python (`requires-python >= 3.11`)
+- **Package/Env manager**: `uv` (lockfile: `uv.lock`)
+- **Test framework**: pytest (with `pytest-cov`)
+- **Lint + format**: Ruff (`--preview`)
+- **Task runner**: `just`
+- **Key libraries**: fastmcp, ortools (CP-SAT), typer, tiktoken, pyyaml, rich, code-review-graph
+- **Shape**: MCP server (`src/milknado/mcp_server.py`) over domain slices under `src/milknado/domains/`
+
+## Build, Test, and Lint Commands
+
+- Full build (autofix → test → coverage gate): `just build`
+- CI build (lint check, no autofix): `just build-ci`
+- Lint (check only): `just lint`
+- Lint (autofix + format): `just lint-fix`
+- Tests: `just test` (or `just test-file <path>`)
+- Coverage report: `just test-coverage` (threshold-gated by `just coverage-check`, min 90%)

milknado-0.1.0/.github/dependabot.yml

@@ -0,0 +1,21 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+    groups:
+      github-actions:
+        patterns:
+          - "*"
+
+  - package-ecosystem: pip
+    directory: /
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 10
+    groups:
+      python-dependencies:
+        patterns:
+          - "*"

milknado-0.1.0/.github/instructions/code-review.instructions.md

@@ -0,0 +1,31 @@
+---
+applyTo: "**"
+excludeAgent: "coding-agent"
+---
+
+## Code Review Focus
+
+Focus reviews on these categories, in priority order:
+
+1. **Security** - Flag hardcoded secrets, SQL injection, XSS, command injection, path traversal, and insecure deserialization
+2. **Silent failures** - Flag empty catch blocks, swallowed errors, missing error propagation, or functions that return `None`/null/undefined on failure without signaling
+3. **Coupling violations** - Flag domain/model code that imports infrastructure (HTTP, DB, file I/O, framework decorators)
+4. **Complexity violations** - Flag functions over 40 lines, files over 300 lines, functions with more than 4 parameters, nesting deeper than 3 levels
+5. **Architectural violations** - Flag cross-slice internal imports, mutable shared state, God classes/modules
+6. **Weak tests** - Flag tests that prove nothing: no assertions, `is_ok()`/`is_some()` without checking inner values, tautological assertions, mirror-implementation tests that re-derive expected values from the same logic, mock echo tests, `.len()`-only collection checks, assertions gated behind conditional branches that silently pass, and happy-path-only coverage with no error/boundary tests
+
+## What NOT to Comment On
+
+- Linting — handled by Ruff in CI
+- Formatting and whitespace — handled by `ruff format` in CI
+- Import ordering — handled by tooling
+- Missing docstrings on internal or private functions
+- Style preferences that are consistent with the rest of the codebase
+- Nitpicks with no functional impact
+
+## Review Style
+
+- Only comment when confidence is high
+- If a pattern is used consistently elsewhere in the codebase, do not flag it as wrong
+- Suggest specific fixes, not vague improvements
+- One comment per issue — do not repeat the same feedback on multiple occurrences

milknado-0.1.0/.github/instructions/coding-agent.instructions.md

@@ -0,0 +1,26 @@
+---
+applyTo: "**"
+excludeAgent: "code-review"
+---
+
+## Coding Agent Guidelines
+
+When implementing changes:
+
+- Read existing code before modifying it — understand the patterns in use
+- Follow the existing code style of the file you are editing
+- Keep changes minimal and focused on the issue at hand
+- Do not refactor surrounding code unless the issue requires it
+- Do not add docstrings to helper functions or private methods with clear names
+- Do not introduce new dependencies without explicit approval
+- Write tests for new functionality — match the existing test patterns in `tests/`
+- Prefer editing existing files over creating new ones
+- Run `just build` before opening a PR — it must pass (lint, tests, and the 90% coverage gate)
+
+## Architecture Rules
+
+- New domain concepts go in their own module under `src/milknado/domains/`
+- Public API is exposed through `__init__.py` barrel files only
+- Do not create abstract classes, interfaces, or factories unless there are 2+ concrete implementations
+- Core models must not import infrastructure code
+- Cross-slice translation belongs in an explicit bridge module, not inside the pure slice

milknado-0.1.0/.github/instructions/python.instructions.md

@@ -0,0 +1,10 @@
+---
+applyTo: "**/*.py"
+---
+- Use type hints on all function signatures and return types
+- Use `uv` for dependency management, not pip directly
+- Use pytest for tests, not unittest
+- Use Ruff for linting and formatting (`just lint-fix`)
+- Prefer frozen dataclasses over raw dicts for structured data
+- Use `from __future__ import annotations` for forward references
+- Raise specific exceptions; avoid `raise Exception`, and use bare `raise` only to re-raise the active exception

milknado-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,54 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        with:
+          enable-cache: true
+
+      - name: Install just
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y just
+
+      - name: Run full build (lint → test → coverage)
+        run: just build-ci
+
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f # v6
+        if: matrix.python-version == '3.11'
+        with:
+          files: ./coverage.xml
+          flags: unittests
+          fail_ci_if_error: false
+          use_oidc: true

milknado-0.1.0/.github/workflows/codeql.yml

@@ -0,0 +1,42 @@
+name: codeql
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  schedule:
+    - cron: "26 4 * * 1"
+
+permissions:
+  contents: read
+
+jobs:
+  analyze:
+    name: analyze (${{ matrix.language }})
+    runs-on: ubuntu-latest
+    permissions:
+      security-events: write
+      packages: read
+      actions: read
+      contents: read
+    strategy:
+      fail-fast: false
+      matrix:
+        language: [python]
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
+        with:
+          python-version: "3.12"
+      - uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        with:
+          enable-cache: true
+      - uses: github/codeql-action/init@8aad20d150bbac5944a9f9d289da16a4b0d87c1e # v4.36.2
+        with:
+          languages: ${{ matrix.language }}
+          queries: security-and-quality
+      - run: uv sync --locked
+      - uses: github/codeql-action/analyze@8aad20d150bbac5944a9f9d289da16a4b0d87c1e # v4.36.2
+        with:
+          category: "/language:${{ matrix.language }}"

milknado-0.1.0/.github/workflows/dependency-review.yml

@@ -0,0 +1,18 @@
+name: dependency review
+
+on:
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  review:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+      - uses: actions/dependency-review-action@a1d282b36b6f3519aa1f3fc636f609c47dddb294 # v5
+        with:
+          fail-on-severity: moderate
+          comment-summary-in-pr: on-failure

milknado-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,39 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  build-and-publish:
+    name: Build and publish to PyPI
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      contents: read
+      id-token: write  # required for OIDC trusted publishing
+
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+
+      - name: Assert tag matches pyproject.toml version
+        run: |
+          pkg_version=$(python3 -c "import tomllib; d=tomllib.load(open('pyproject.toml','rb')); print(d['project']['version'])")
+          tag_version="${GITHUB_REF_NAME#v}"
+          if [ "$pkg_version" != "$tag_version" ]; then
+            echo "Version mismatch: tag is v$tag_version but pyproject.toml has $pkg_version"
+            exit 1
+          fi
+
+      - name: Build sdist and wheel
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@76f52bc884231f62b9a034ebfe128415bbaabdfc # v1.12.4

milknado-0.1.0/.github/workflows/scorecard.yml

@@ -0,0 +1,40 @@
+name: scorecard
+
+on:
+  branch_protection_rule:
+  schedule:
+    - cron: "26 4 * * 1"
+  push:
+    branches: [main]
+
+permissions: read-all
+
+jobs:
+  analysis:
+    name: scorecard analysis
+    runs-on: ubuntu-latest
+    permissions:
+      security-events: write
+      id-token: write
+      contents: read
+      actions: read
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        with:
+          persist-credentials: false
+
+      - uses: ossf/scorecard-action@4eaacf0543bb3f2c246792bd56e8cdeffafb205a # v2.4.3
+        with:
+          results_file: results.sarif
+          results_format: sarif
+          publish_results: true
+
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: SARIF file
+          path: results.sarif
+          retention-days: 5
+
+      - uses: github/codeql-action/upload-sarif@8aad20d150bbac5944a9f9d289da16a4b0d87c1e # v4.36.2
+        with:
+          sarif_file: results.sarif