code-foundry 0.1.0

package/.editorconfig

@@ -0,0 +1,18 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+indent_style = space
+indent_size = 2
+trim_trailing_whitespace = true
+
+[*.py]
+indent_size = 4
+
+[*.rs]
+indent_size = 4
+
+[Makefile]
+indent_style = tab

package/.env.example

@@ -0,0 +1,3 @@
+# Copy this file to .env.local or the project-specific environment file.
+# Add only non-secret, repository-specific variable names here.
+# Never commit credentials, tokens, private keys, or production values.

package/.gitattributes

@@ -0,0 +1,9 @@
+# Normalize text files to LF and keep binary assets untouched.
+* text=auto eol=lf
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.webp binary
+*.ico binary
+*.pdf binary

package/.githooks/pre-commit

@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+git diff --cached --check
+changed=$(git diff --cached --name-only)
+
+has_script() {
+  [ -f package.json ] && node -e 'const p=require("./package.json"); process.exit(p.scripts?.[process.argv[1]] ? 0 : 1)' "$1"
+}
+
+package_manager() {
+  if [ -f bun.lock ] || [ -f bun.lockb ]; then echo bun
+  elif [ -f pnpm-lock.yaml ]; then echo pnpm
+  elif [ -f yarn.lock ]; then echo yarn
+  else echo npm
+  fi
+}
+
+run_lint_staged() {
+  if ! has_script lint-staged; then return 1; fi
+  case "$(package_manager)" in
+    bun) bun run lint-staged ;;
+    pnpm) corepack pnpm run lint-staged ;;
+    yarn) corepack yarn run lint-staged ;;
+    npm) npm run lint-staged ;;
+  esac
+}
+
+if printf '%s\n' "$changed" | grep -Eq '\.(js|jsx|ts|tsx|json|md|mdx|yml|yaml)$'; then
+  if ! run_lint_staged; then
+    bash .github/scripts/ci.sh format
+    bash .github/scripts/ci.sh lint
+  fi
+fi
+
+if printf '%s\n' "$changed" | grep -Eq '\.rs$|(^|/)Cargo\.toml$'; then
+  cargo fmt --check
+  cargo clippy --all-targets -- -D warnings
+fi
+
+if printf '%s\n' "$changed" | grep -Eq '\.py$|(^|/)(pyproject\.toml|requirements(-dev)?\.txt)$'; then
+  if [ -x .venv/bin/ruff ]; then
+    .venv/bin/ruff format --check .
+    .venv/bin/ruff check .
+  elif command -v ruff >/dev/null 2>&1; then
+    ruff format --check .
+    ruff check .
+  else
+    echo "Python files changed but Ruff is not installed; run the template setup first." >&2
+    exit 1
+  fi
+fi

package/.github/CODEOWNERS

@@ -0,0 +1,2 @@
+# Default owner for all repository files.
+* @0xPlayerOne

package/.github/CODE_OF_CONDUCT.md

@@ -0,0 +1,41 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Demonstrating empathy and kindness toward other people
+- Respecting differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by mistakes
+- Focusing on what is best for the overall community
+
+Examples of unacceptable behavior:
+
+- Sexualized language or imagery, and sexual attention or advances
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing another person's private information without explicit permission
+- Other conduct that could reasonably be considered inappropriate in a professional setting
+
+## Enforcement Responsibilities
+
+Project maintainers are responsible for clarifying and enforcing these standards. They may remove, edit, or reject comments, commits, code, issues, and other contributions that do not align with this Code of Conduct.
+
+## Scope
+
+This Code of Conduct applies within all community spaces and also applies when an individual is officially representing the project in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported privately to the project maintainers using the contact method documented in [SECURITY.md](SECURITY.md). Reports will be reviewed and investigated promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1.

package/.github/CONTRIBUTING.md

@@ -0,0 +1,194 @@
+# Contributing
+
+This guide is the operating contract for humans and automation contributing to this repository.
+
+It applies to TypeScript, Rust, Python, and mixed-language projects using this template.
+
+Quick links: [Code of Conduct](./CODE_OF_CONDUCT.md) · [Security Policy](./SECURITY.md) · [Pull Request Template](./PULL_REQUEST_TEMPLATE.md)
+
+### Contents
+
+[Agent contract](#agent-operating-contract) · [Branches](#branching-model) · [Setup](#before-you-start) · [Validation](#local-validation) · [Internal](#internal-contribution-workflow) · [External](#external-contribution-workflow) · [Pull requests](#pull-request-standards) · [Reviews](#review-and-merge-protocol) · [Security](#security-and-emergencies)
+
+## Agent operating contract
+
+Agents must follow these rules before changing code:
+
+1. Read this file, `AGENTS.md`, and the relevant project documentation.
+2. Inspect the current branch, worktree, remotes, and existing changes before editing.
+3. Preserve user-owned changes. Never discard or overwrite unrelated work.
+4. Branch from `staging` and target pull requests at `staging`; do not work directly on `main`.
+5. Keep the change focused. Do not expand scope without documenting why.
+6. Run the applicable format, lint, type-check, build, unit, integration, E2E, smoke, and security checks.
+7. Report exact validation results, skipped checks, known limitations, and remaining risks.
+8. Never commit secrets, credentials, local environment files, generated artifacts, or machine-specific paths.
+
+Agents must not:
+
+- Use destructive Git operations, force pushes, or history rewriting without explicit authorization.
+- Bypass hooks or required checks to hide a failure.
+- Change branch protections, secrets, deployments, or external systems unless that action is explicitly in scope.
+- Claim completion when tests, deployment checks, or required reviews are still pending.
+
+## Branching model
+
+```text
+                                      release PR
+                                   ┌──────────────┐
+                                   │              ▼
+feat/*  fix/*  chore/*  ──PR──▶  staging  ──PR──▶  main
+docs/*  test/*  refactor/*         │              │
+                                   │              └── protected release branch
+                                   └── integration branch
+```
+
+| Branch                                                         | Purpose                  | Contribution rule                                                         |
+| -------------------------------------------------------------- | ------------------------ | ------------------------------------------------------------------------- |
+| `main`                                                         | Protected release branch | Merge through the `staging` → `main` release PR. No direct pushes.        |
+| `staging`                                                      | Integration branch       | Target normal pull requests here. Required checks must pass before merge. |
+| `feat/*`, `fix/*`, `chore/*`, `refactor/*`, `docs/*`, `test/*` | Focused work             | Branch from `staging`; keep changes small and reviewable.                 |
+
+Use squash merges unless the repository documents another strategy. Re-align `staging` with `main` after a release when needed.
+
+## Before you start
+
+### Toolchain
+
+1. Install [mise](https://mise.jdx.dev/).
+2. Run `bash .github/scripts/bootstrap.sh` to install the pinned toolchain, enable hooks, and validate the checkout.
+3. Use `bash .github/scripts/doctor.sh` when setup, lockfiles, or hooks appear out of sync.
+4. Use the repository's existing package manager and lockfile. Do not introduce a second package manager.
+5. Copy `.env.example` to the appropriate local environment file when provided. Never commit the copy.
+
+### Worktree and branch
+
+```sh
+git status --short --branch
+git fetch origin
+git switch staging
+git pull --ff-only origin staging
+git switch -c feat/short-description
+```
+
+If the worktree is dirty, stop and understand the existing changes before switching branches or editing overlapping files.
+
+## Local validation
+
+The template scripts detect supported tools and skip checks that do not apply:
+
+```sh
+bash .github/scripts/ci.sh format
+bash .github/scripts/ci.sh lint
+bash .github/scripts/ci.sh type_check
+bash .github/scripts/ci.sh build
+bash .github/scripts/ci.sh unit
+bash .github/scripts/ci.sh integration
+bash .github/scripts/ci.sh e2e
+bash .github/scripts/ci.sh smoke
+bash .github/scripts/security.sh
+```
+
+Run the checks relevant to the change. For a release or security-sensitive change, run the complete set. Record the commands and results in the pull request.
+
+## Internal contribution workflow
+
+For maintainers, trusted contributors, and automation agents:
+
+1. Start from an up-to-date `staging` branch.
+2. Create a focused branch with a descriptive prefix.
+3. Inspect the relevant code and tests before making changes.
+4. Implement the smallest complete change.
+5. Add or update tests, documentation, configuration, and migration notes as needed.
+6. Run local validation and inspect the final diff.
+7. Commit with a clear message, preferably using Conventional Commits:
+
+   ```text
+   feat(auth): add passkey recovery
+   fix(api): handle expired session tokens
+   chore(ci): cache Rust dependencies
+   ```
+
+8. Push the branch and open a pull request into `staging`.
+9. Address review feedback and failed checks on the same branch.
+10. Squash-merge only after required checks pass and the change is ready.
+
+### Internal agent handoff
+
+Every agent handoff should state:
+
+```text
+Summary: what changed and why
+Files: important files changed
+Validation: exact commands and pass/fail results
+Skipped: checks skipped and why
+Risks: known limitations or follow-up work
+Branch/PR: branch name and pull request link
+```
+
+## External contribution workflow
+
+For contributors who do not have direct write access:
+
+1. Fork the repository on GitHub.
+2. Add the upstream repository as `upstream`.
+3. Branch from the upstream `staging` branch.
+4. Make a focused change and follow the local setup instructions.
+5. Add tests and documentation for behavior changes.
+6. Run all applicable checks locally.
+7. Push to the fork and open a pull request targeting `staging`.
+8. Explain the problem, proposed solution, validation, compatibility, and rollout impact.
+9. Address maintainer feedback without rewriting unrelated history or scope.
+
+External contributors should never need repository secrets or production access to validate a normal change.
+
+## Pull request standards
+
+Every pull request should make these questions easy to answer:
+
+- What changed?
+- Why was it needed?
+- How was it tested?
+- What could break?
+- Does it require migration, deployment, configuration, or rollback work?
+- Which files or areas deserve focused review?
+
+Keep pull requests focused and reviewable. Include screenshots or recordings for user-facing changes. Link related issues and use `Closes #123` when appropriate. Complete the [pull request template](./PULL_REQUEST_TEMPLATE.md).
+
+## Workflow and check behavior
+
+| Event                            | Expected automation                      |
+| -------------------------------- | ---------------------------------------- |
+| Push to `main` or `staging`      | CI, Test, Security, and CodeQL workflows |
+| Pull request targeting `staging` | CI, Test, Security, and CodeQL workflows |
+| Push to a working branch         | Draft PR workflow                        |
+| Push to `staging`                | Release PR workflow                      |
+| Version tag such as `v1.2.3`     | Release workflow                         |
+
+The workflows use separate concurrency groups. A newer run for the same branch or pull request cancels its older run, while independent CI, test, security, and CodeQL workflows continue in parallel.
+
+Required checks are enforced by branch protection. Do not duplicate their checklists in the pull request description; document validation commands and results instead.
+
+Security checks can be skipped when repository visibility or the GitHub plan does not support a feature. A skipped optional check must not be configured as a required status check.
+
+## Review and merge protocol
+
+| Change            | Target    | Merge gate                                                |
+| ----------------- | --------- | --------------------------------------------------------- |
+| Working branch    | `staging` | All applicable required checks pass                       |
+| `staging` release | `main`    | Current staging checks, release review, and rollout notes |
+
+Reviewers focus on correctness, security, maintainability, test coverage, operational impact, and compatibility. Authors remain responsible for responding to feedback and verifying the final commit.
+
+## Security and emergencies
+
+Report vulnerabilities privately using [SECURITY.md](./SECURITY.md), never in a public issue or pull request.
+
+For an urgent production or security issue:
+
+1. Create a focused branch from `staging`.
+2. Document the urgency and affected systems without exposing secrets.
+3. Open a pull request and run the narrowest complete validation available.
+4. Request the appropriate maintainer review.
+5. Record follow-up work, remediation, and rollback information.
+
+CI bypasses are for documented infrastructure emergencies only and require a follow-up fix. Never use a bypass to hide a code or test failure.

package/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,56 @@
+name: Bug report
+description: Report a reproducible problem or unexpected behavior
+title: '[bug] '
+labels: [bug]
+body:
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: Include the commit, branch, runtime/tool versions, operating system, and affected app or package.
+      placeholder: |
+        Commit:
+        Branch:
+        Runtime/tool versions:
+        OS:
+        App/package:
+    validations:
+      required: true
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: Explain what happened, what you expected, and what actually occurred.
+    validations:
+      required: true
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Steps to reproduce
+      description: Provide the smallest reliable reproduction.
+      placeholder: |
+        1.
+        2.
+        3.
+    validations:
+      required: true
+  - type: textarea
+    id: diagnostics
+    attributes:
+      label: Error output and diagnostics
+      description: Include relevant logs, stack traces, CI run links, dependency changes, or screenshots. Remove secrets first.
+  - type: checkboxes
+    id: impact
+    attributes:
+      label: Impact
+      options:
+        - label: Blocks a deployment or pull request.
+        - label: Security or privacy impact is suspected; I will report details privately.
+        - label: Low priority or cosmetic.
+  - type: checkboxes
+    id: checks
+    attributes:
+      label: Checks
+      options:
+        - label: I searched existing issues and found no duplicate.
+          required: true

package/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security vulnerability reporting
+    url: https://docs.github.com/en/code-security/security-advisories/working-with-repository-security-advisories/creating-a-repository-security-advisory
+    about: Use this repository's Security tab to report vulnerabilities privately; do not open a public issue.

package/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,38 @@
+name: Feature request
+description: Suggest an idea or improvement
+title: '[feat] '
+labels: [enhancement]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What problem would this feature solve? Be specific.
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+      description: Describe the desired behavior and relevant technical details.
+    validations:
+      required: true
+  - type: checkboxes
+    id: impact
+    attributes:
+      label: Impact
+      options:
+        - label: Breaking change
+        - label: New dependency required
+        - label: Changes CI, security, deployment, or configuration
+        - label: Low risk or additive only
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives
+      description: What alternatives have you considered?
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional context
+      description: Add screenshots, mockups, links, acceptance criteria, or related issues.

package/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,29 @@
+## Summary
+
+<!-- What changed, why was it needed, and which issue or requirement does it address? -->
+
+## Validation
+
+<!-- List the commands, local checks, CI links, screenshots, or recordings used to validate this change. Required repository checks are enforced automatically. -->
+
+- Commands run:
+- CI or deployment links:
+- Screenshots/recordings, when applicable:
+
+## Impact and rollout
+
+- [ ] No migration or rollout action is required
+- [ ] Migration or rollout steps are documented below
+- [ ] Environment or secret changes are documented below
+- [ ] Security, privacy, compatibility, or performance impact is documented below
+- [ ] Rollback or follow-up work is documented below
+
+<!-- Add the relevant details here. -->
+
+## Review notes
+
+<!-- Call out tradeoffs, known limitations, generated files, dependency changes, or areas that need focused review. -->
+
+## Related issue
+
+<!-- Use `Closes #123` when applicable. -->

package/.github/SECURITY.md

@@ -0,0 +1,23 @@
+# Security Policy
+
+## Supported Versions
+
+The latest commit on `staging` receives security patches. Patches are promoted to `main` through the next release cycle.
+
+| Branch           | Supported |
+| ---------------- | --------- |
+| `staging`        | ✅        |
+| `main`           | ✅        |
+| Feature branches | ❌        |
+
+## Reporting a Vulnerability
+
+Do not open a public GitHub issue for a security vulnerability. Report it privately through the repository's Security tab, GitHub security advisory flow, or the private contact method listed on the repository page.
+
+Include the affected version or commit, impact, reproduction steps, relevant logs, and suggested mitigation when possible.
+
+Maintainers will acknowledge receipt, provide an assessment timeline, coordinate a fix, and agree with the reporter on responsible disclosure. Public disclosure should occur only after a fix or mitigation is available.
+
+## Scope
+
+This policy covers the code, configuration, dependencies, workflows, and generated artifacts maintained in this repository. Review `Security / Dependency Audit` results for supported ecosystems. Never commit credentials, tokens, private keys, or sensitive environment files. Report accidental secret exposure privately and rotate the credential immediately.

package/.github/actions/setup/action.yml

@@ -0,0 +1,20 @@
+name: Repository Setup
+description: Install the pinned mise toolchain and optionally project dependencies.
+
+inputs:
+  install:
+    description: Install dependencies for the detected project ecosystems.
+    required: false
+    default: 'false'
+
+runs:
+  using: composite
+  steps:
+    - name: Setup
+      uses: jdx/mise-action@v4
+      with:
+        cache: true
+    - name: Install
+      if: inputs.install == 'true'
+      shell: bash
+      run: bash .github/scripts/ci.sh install

package/.github/dependabot.yml

@@ -0,0 +1,42 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    target-branch: staging
+    schedule:
+      interval: weekly
+      day: sunday
+    open-pull-requests-limit: 99
+    groups:
+      github-actions:
+        patterns: ['*']
+  - package-ecosystem: npm
+    directory: /
+    target-branch: staging
+    schedule:
+      interval: weekly
+      day: sunday
+    open-pull-requests-limit: 99
+    groups:
+      npm-dependencies:
+        patterns: ['*']
+  - package-ecosystem: cargo
+    directory: /
+    target-branch: staging
+    schedule:
+      interval: weekly
+      day: sunday
+    open-pull-requests-limit: 99
+    groups:
+      cargo-dependencies:
+        patterns: ['*']
+  - package-ecosystem: pip
+    directory: /
+    target-branch: staging
+    schedule:
+      interval: weekly
+      day: sunday
+    open-pull-requests-limit: 99
+    groups:
+      python-dependencies:
+        patterns: ['*']

package/.github/scripts/bootstrap.sh

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+git config core.hooksPath .githooks
+
+if command -v mise >/dev/null 2>&1; then
+  mise install
+else
+  printf '%s\n' "mise is not installed; install it from https://mise.jdx.dev/ and rerun this script." >&2
+  exit 1
+fi
+
+bash .github/scripts/doctor.sh