zeocore 0.1.0__tar.gz

zeocore-0.1.0/.gitattributes

@@ -0,0 +1,16 @@
+# Normalize line endings to LF for all text files, regardless of the
+# contributor's platform (Windows checkouts default to CRLF otherwise,
+# which causes noisy whole-file diffs on every edit).
+* text=auto eol=lf
+
+# Treat these as binary — never line-ending-normalize, never diff as text.
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.ico binary
+*.whl binary
+*.tar.gz binary
+
+# Collapse generated/vendored files out of GitHub's diff view by default.
+uv.lock -diff linguist-generated=true

zeocore-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,26 @@
+---
+name: Bug report
+about: Something isn't working as expected
+title: ""
+labels: bug
+---
+
+**What happened?**
+
+<!-- A clear description of the bug. -->
+
+**What did you expect to happen?**
+
+**How to reproduce**
+
+<!-- Minimal steps or code snippet to reproduce the issue. -->
+
+**Environment**
+
+- zeocore version:
+- Python version:
+- OS:
+
+**Anything else?**
+
+<!-- Logs, stack traces, screenshots -- whatever's useful. -->

zeocore-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,18 @@
+---
+name: Feature request
+about: Suggest an idea or improvement
+title: ""
+labels: enhancement
+---
+
+**What problem does this solve?**
+
+<!-- What are you trying to do that zeocore doesn't support well today? -->
+
+**Proposed solution**
+
+<!-- What would you like to see? A rough API sketch is welcome. -->
+
+**Alternatives considered**
+
+<!-- Any workarounds you're using now, or other approaches you considered. -->

zeocore-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,11 @@
+## What does this PR do?
+
+<!-- A short description of the change and why it's needed. -->
+
+## Checklist
+
+- [ ] I've made the change, with tests
+- [ ] `make verify` passes locally (format-check, lint, mypy strict, arch-check,
+      hygiene-check, hygiene-secrets, plugin-boundary, tests + coverage --
+      see [CONTRIBUTING.md](../CONTRIBUTING.md))
+- [ ] This PR describes what changed and why

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

@@ -0,0 +1,44 @@
+name: CI
+
+# The doctrine gate, run in CI the same way contributors run it locally:
+# `make verify` (see CONTRIBUTING.md / Makefile). We shell out to the same
+# `make` targets rather than reimplementing each tool invocation in YAML,
+# so local and CI behavior cannot drift apart. The only per-job deviation is
+# selecting the matrix Python version, which has to happen before `make setup`
+# creates the venv -- done via `PYTHON_VERSION=<matrix version>` on the make
+# command line, which overrides the Makefile's own `PYTHON_VERSION := 3.13`
+# default (make command-line assignments win over `:=` in the makefile).
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  verify:
+    name: verify (py${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+          cache-dependency-glob: "pyproject.toml"
+
+      - name: make setup (env + install-all + install-dev + install-lint)
+        run: make setup PYTHON_VERSION=${{ matrix.python-version }}
+
+      - name: make verify (format-check, lint, mypy strict, arch-check, hygiene-check, hygiene-secrets, plugin-boundary, tests+coverage)
+        run: make verify

zeocore-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,206 @@
+name: Publish
+
+# Two ways to trigger:
+#   1. Push a version tag (`v0.1.0`, matching pyproject.toml's `version`) --
+#      publishes straight to real PyPI. This is the release path.
+#   2. Manual dispatch (Actions tab -> Run workflow) with a `target` choice
+#      of testpypi / pypi / both -- lets a human stage a real publish
+#      attempt against TestPyPI (a real, separate package index with its
+#      own trusted-publisher binding) without cutting a tag, and is the
+#      right way to first verify PyPI's trusted-publisher link is actually
+#      configured correctly before it matters on a real release.
+#
+# Runs the full `make verify` gate first so a broken build can never reach
+# either index even if someone tags/dispatches by mistake, then builds
+# sdist+wheel once and publishes via PyPI Trusted Publishing (OIDC) to
+# whichever index(es) were requested -- no API token stored as a repo
+# secret for either index.
+#
+# One-time setup required on each index's own web UI before this workflow
+# can publish there (not done by this workflow, and not something a CI
+# session has credentials for):
+#   - PyPI:     https://pypi.org/manage/account/publishing/
+#   - TestPyPI: https://test.pypi.org/manage/account/publishing/
+# For each, register a trusted publisher with EXACTLY:
+#   - repository owner: zeroemployeeorg
+#   - repository name:  zeocore
+#   - workflow filename: publish.yml  (not the full path, just the filename)
+#   - environment name: pypi (for the pypi.org publisher) or
+#                        testpypi (for the test.pypi.org publisher)
+# All four fields are baked into the OIDC token's claims and must match
+# byte-for-byte on PyPI's side -- a mismatch fails with
+# "invalid-publisher: valid token, but no corresponding publisher", which
+# gives no further detail about WHICH field is wrong, so get all four
+# exactly right rather than guessing from the error alone.
+# See https://docs.pypi.org/trusted-publishers/.
+
+on:
+  workflow_dispatch:
+    inputs:
+      target:
+        description: "Where to publish"
+        required: true
+        type: choice
+        options:
+          - testpypi
+          - pypi
+          - both
+        default: testpypi
+  push:
+    tags:
+      - "v*.*.*"
+
+permissions:
+  contents: read
+
+jobs:
+  verify:
+    name: verify before publish
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+          cache-dependency-glob: "pyproject.toml"
+
+      - name: make setup
+        run: make setup
+
+      - name: make verify (the doctrine gate -- must pass before publish)
+        run: make verify
+
+  build:
+    name: build sdist + wheel
+    needs: verify
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+          cache-dependency-glob: "pyproject.toml"
+
+      - name: make setup
+        run: make setup
+
+      - name: make build (python -m build -> sdist + wheel in dist/)
+        run: make build
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  publish-testpypi:
+    name: publish to TestPyPI (trusted publishing)
+    needs: build
+    if: >-
+      (github.event_name == 'workflow_dispatch' &&
+       (github.event.inputs.target == 'testpypi' || github.event.inputs.target == 'both'))
+    runs-on: ubuntu-latest
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/project/zeocore/
+    permissions:
+      id-token: write
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+          verbose: true
+          print-hash: true
+
+  publish-pypi:
+    name: publish to PyPI (trusted publishing)
+    needs: build
+    if: >-
+      (github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')) ||
+      (github.event_name == 'workflow_dispatch' &&
+       (github.event.inputs.target == 'pypi' || github.event.inputs.target == 'both'))
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/zeocore/
+    permissions:
+      # id-token: write is what makes OIDC / trusted publishing work --
+      # no PYPI_API_TOKEN secret needed or wanted.
+      id-token: write
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          verbose: true
+          print-hash: true
+
+  smoke-test:
+    name: smoke-test the published package
+    needs: [publish-testpypi, publish-pypi]
+    # Runs if EITHER publish job ran and succeeded; skipped entirely (not
+    # failed) if a given publish job didn't run because its target wasn't
+    # selected -- `always()` plus explicit result checks, since `needs`
+    # results for a skipped job read as "success" by default, which would
+    # otherwise let this step silently no-op instead of actually verifying
+    # anything on a testpypi-only or pypi-only run.
+    if: |
+      always() &&
+      (needs.publish-testpypi.result == 'success' || needs.publish-pypi.result == 'success')
+    runs-on: ubuntu-latest
+    steps:
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+
+      - name: Wait for index propagation
+        run: sleep 30
+
+      - name: Install from PyPI and smoke-test
+        if: needs.publish-pypi.result == 'success'
+        run: |
+          uv venv /tmp/smoke-pypi
+          uv pip install --python /tmp/smoke-pypi/bin/python zeocore=="${GITHUB_REF_NAME#v}"
+          /tmp/smoke-pypi/bin/python -c "
+          import zeo_core
+          print('installed version:', zeo_core.__version__)
+          from zeo_core.tools import BaseZeoTool, ToolContext
+          from zeo_core.contracts import CapabilityResult
+          print('import OK: BaseZeoTool, ToolContext, CapabilityResult')
+          "
+        env:
+          GITHUB_REF_NAME: ${{ github.ref_name }}
+
+      - name: Install from TestPyPI and smoke-test
+        if: needs.publish-testpypi.result == 'success' && needs.publish-pypi.result != 'success'
+        run: |
+          uv venv /tmp/smoke-testpypi
+          uv pip install --python /tmp/smoke-testpypi/bin/python \
+            --index-url https://test.pypi.org/simple/ \
+            --extra-index-url https://pypi.org/simple/ \
+            zeocore
+          /tmp/smoke-testpypi/bin/python -c "
+          import zeo_core
+          print('installed version:', zeo_core.__version__)
+          from zeo_core.tools import BaseZeoTool, ToolContext
+          from zeo_core.contracts import CapabilityResult
+          print('import OK: BaseZeoTool, ToolContext, CapabilityResult')
+          "

zeocore-0.1.0/.gitignore

@@ -0,0 +1,47 @@
+# Byte-compiled / cache
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+*.egg
+wheels/
+pip-wheel-metadata/
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# Test / coverage / type-check caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.hypothesis/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+
+# Runtime scratch dirs created by zeo_core's fs service
+.zeo/
+
+# Editors / OS
+.idea/
+.vscode/
+*.swp
+.DS_Store
+
+# Secrets
+.env
+.env.*
+!.env.example
+*.pem
+*.key
+
+# Jupyter
+.ipynb_checkpoints/

zeocore-0.1.0/.importlinter

@@ -0,0 +1,54 @@
+# .importlinter — Tier-1 directional import contracts (Track C)
+# Enforced via `lint-imports` inside `make verify` (wired next). Every contract
+# below targets a REAL module path verified by recon (C-RECON-06..08), not the
+# strategy-doc's vocabulary — e.g. Capability lives at zeo_core.contracts.capabilities,
+# NOT zeo_core.capabilities; a contract against the doc name would resolve to
+# nothing and never fire.
+#
+# Deliberately OMITTED here, recorded for Master (Rev 4):
+#   - producer->consumer (zeocore/zeointegrations/zeoplugins): cross-PACKAGE,
+#     not resolvable inside the zeocore-only work_repo. Belongs to a monorepo
+#     linter, outside Track C's single-work_repo scope (§15).
+#   - Plugin -> Tool/Cap: `plugin.py` is a per-subsystem MODULE (core/paths, core/fs,
+#     config, prompt), not a package — no import-linter target. Handled as a
+#     plugin.py grep-ban instead.
+#   - "nothing imports a Tool" as a GLOBAL rule: tools legitimately import their own
+#     submodules, so a blanket forbidden would fire on legitimate internal imports.
+#     The enforceable core (non-tool layers not importing tools) is expressed below;
+#     the broad form needs an allowlist/independence design — Master's call.
+
+[importlinter]
+root_package = zeo_core
+
+[importlinter:contract:capabilities-not-import-tools]
+name = Capabilities must not import Tools
+type = forbidden
+source_modules =
+    zeo_core.contracts.capabilities
+forbidden_modules =
+    zeo_core.tools
+
+[importlinter:contract:integrations-are-leaves]
+name = Integrations are leaves (no Capability/Tool imports)
+type = forbidden
+source_modules =
+    zeo_core.integrations
+forbidden_modules =
+    zeo_core.tools
+    zeo_core.contracts.capabilities
+
+[importlinter:contract:fs-internal-not-import-service]
+name = fs _internal must not import service
+type = forbidden
+source_modules =
+    zeo_core.core.fs._internal
+forbidden_modules =
+    zeo_core.core.fs.service
+
+[importlinter:contract:fs-ops-not-import-results]
+name = fs _ops must not import Result types
+type = forbidden
+source_modules =
+    zeo_core.core.fs._ops
+forbidden_modules =
+    zeo_core.core.fs.results

zeocore-0.1.0/CHANGELOG.md

@@ -0,0 +1,77 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-08-17
+
+Initial extraction from the quackverse monorepo as a standalone,
+MIT-licensed package.
+
+### Added
+
+- `zeo_core.tools`: a capability-authoring framework (`BaseZeoTool`,
+  `ToolContext`, `ZeoToolProtocol`) with optional mixins
+  (`IntegrationEnabledMixin`, `LifecycleMixin`, `ToolEnvInitializerMixin`)
+  for writing doctrine-compliant tools.
+- `zeo_core.contracts`: typed data contracts (`CapabilityResult`, artifact
+  and manifest models, common enums and IDs).
+- `zeo_core.core`: filesystem operations (`core.fs`), path resolution
+  (`core.paths`), a typed error hierarchy (`core.errors`), MIME detection,
+  serialization helpers, logging, and an operation registry.
+- `zeo_core.config`: YAML/environment-variable configuration loading and
+  per-tool configuration models.
+- `zeo_core.integrations`: adapters for GitHub, Google Drive, Gmail, LLM
+  providers (OpenAI, Anthropic), Notion, and Pandoc.
+- `zeo_core.modules`: plugin discovery and explicit-loading registry.
+- `zeo_core.prompt`: prompt template selection and enhancement utilities.
+- `zeo_core.adapters`: an optional FastAPI-based HTTP adapter for exposing
+  tools over a REST API.
+- `examples/`: runnable, verified example scripts (`toolkit_usage.py`,
+  `minimal_tool.py`, `error_handling.py`).
+- `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md` (Contributor Covenant v2.1).
+
+### Changed
+
+- Full mechanical rename from the monorepo's `quack_core` package to
+  `zeo_core` (PyPI distribution name: `zeocore`), including class names
+  (`Quack*` -> `Zeo*`), environment variable prefixes, and config file
+  keys.
+- Fixed a broken version-sourcing path and a production test-detection bug
+  found during the extraction (see git history for detail).
+
+### Fixed
+
+- CI now runs the full test suite on every supported Python version
+  (3.10-3.13) on real GitHub Actions infrastructure. That surfaced three
+  real, previously-invisible cross-version bugs (this package's own
+  pre-release local development only ever ran on 3.13), all fixed and
+  independently verified across every supported version before release:
+  - A `pathlib.Path.__init__`/`__new__` split changed in CPython 3.12;
+    an autouse test fixture that monkeypatched `Path.__init__` only was
+    crashing the entire test suite on 3.10/3.11 with an `INTERNALERROR`.
+    Fixed by coercing on both `__new__` and `__init__`, matching whichever
+    one actually does the real work on a given Python version.
+  - `unittest.mock`'s dotted-string `@patch(...)` target resolution
+    changed in 3.11 (`pkgutil.resolve_name` instead of an eager
+    `getattr`-walk). Three call sites depended on the newer resolution
+    semantics to reach their intended target; on 3.10 they silently
+    patched the wrong object, cascading into shared-state pollution across
+    unrelated test files.
+  - `typing.Protocol.__instancecheck__`'s structural-membership check
+    changed in 3.12 (from plain `hasattr` to `inspect.getattr_static`,
+    which does not trigger `MagicMock`'s attribute auto-fabrication).
+    Five tests asserting that a bare, unconfigured `MagicMock()` does
+    *not* satisfy a runtime-checkable protocol passed on 3.12/3.13 but
+    failed on 3.10/3.11. Fixed by constructing the mocks with an explicit
+    `spec=`, which is version-stable and expresses the real test intent.
+
+### Removed
+
+- The `BaseZeoToolPlugin` back-compat alias -- unused outside this repo's
+  own test suite, and this package has never had a public release, so no
+  back-compat was owed for it.
+
+[0.1.0]: https://github.com/zeroemployeeorg/zeocore/releases/tag/v0.1.0

zeocore-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,134 @@
+# 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, 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 for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political
+  attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards
+of acceptable behavior and will take appropriate and fair corrective action
+in response to any behavior that they deem inappropriate, threatening,
+offensive, or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, and will communicate reasons
+for moderation decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies
+when an individual is officially representing the community in public
+spaces. Examples of representing our community include using an official
+e-mail address, posting via an official social media account, or acting as
+an appointed representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement by opening a
+GitHub issue or contacting the maintainers directly. All complaints will be
+reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of
+the reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in
+determining the consequences for any action they deem in violation of this
+Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders,
+providing clarity around the nature of the violation and an explanation of
+why the behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external
+channels like social media. Violating these terms may lead to a temporary or
+permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public
+or private interaction with the people involved, including unsolicited
+interaction with those enforcing the Code of Conduct, is allowed during this
+period. Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within
+the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available
+at [https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations