diff --git a/.claude/settings.json b/.claude/settings.json index da5fed5..3636c13 100644 --- a/.claude/settings.json +++ b/.claude/settings.json @@ -1,10 +1,11 @@ { + "$schema": "https://json.schemastore.org/claude-code-settings.json", "permissions": { "allow": [ - "Read", - "Grep", + "Bash", "Glob", - "Bash" + "Grep", + "Read" ], "_comment": "Committed baseline is deliberately conservative: broad reads (Read/Grep/Glob) plus a scoped, mostly-read-only Bash allowlist. Unscoped Write/Edit/Bash are intentionally NOT granted here so they prompt by default in every clone. Broader per-user permissions (git commit/push, gh pr create/merge, unscoped Write/Edit/Bash, etc.) belong in the gitignored .claude/settings.local.json -- never widen this committed file to grant them repo-wide." }, diff --git a/.codex/rules/rulesync.rules b/.codex/rules/rulesync.rules new file mode 100644 index 0000000..60d79b2 --- /dev/null +++ b/.codex/rules/rulesync.rules @@ -0,0 +1,9 @@ +# Generated by Rulesync from .rulesync/permissions.jsonc (permission.bash) +# https://developers.openai.com/codex/rules + +# * +prefix_rule( + pattern = ["*"], + decision = "allow", + justification = "Generated from Rulesync permission.bash: *", +) diff --git a/.envrc b/.envrc new file mode 100644 index 0000000..43edf50 --- /dev/null +++ b/.envrc @@ -0,0 +1,2 @@ +source_up_if_exists +dotenv_if_exists diff --git a/.gitignore b/.gitignore index 70c8d4e..187cc99 100644 --- a/.gitignore +++ b/.gitignore @@ -12,6 +12,9 @@ dist/ PROMPT.md graphify-out/ +# Project secrets loaded by direnv; never commit. +.env + artifacts/ # Vendored external API docs — local-only research anchor (regenerate via scripts/fetch_docs.py). diff --git a/.rulesync/mcp.jsonc b/.rulesync/mcp.jsonc new file mode 100644 index 0000000..60047a8 --- /dev/null +++ b/.rulesync/mcp.jsonc @@ -0,0 +1,14 @@ +{ + "$schema": "https://github.com/dyoshikawa/rulesync/releases/latest/download/mcp-schema.json", + "mcpServers": { + "graphify": { + "type": "stdio", + "command": "graphify-mcp", + "args": [ + "--transport", + "stdio", + "/home/sava/git/bim-ba/refract/graphify-out/graph.json" + ] + } + } +} diff --git a/.rulesync/permissions.jsonc b/.rulesync/permissions.jsonc new file mode 100644 index 0000000..9457e2e --- /dev/null +++ b/.rulesync/permissions.jsonc @@ -0,0 +1,63 @@ +{ + "permission": { + "read": { + "*": "allow" + }, + "grep": { + "*": "allow" + }, + "glob": { + "*": "allow" + }, + "bash": { + "*": "allow" + } + }, + "claudecode": { + "permissions": { + "_comment": "Committed baseline is deliberately conservative: broad reads (Read/Grep/Glob) plus a scoped, mostly-read-only Bash allowlist. Unscoped Write/Edit/Bash are intentionally NOT granted here so they prompt by default in every clone. Broader per-user permissions (git commit/push, gh pr create/merge, unscoped Write/Edit/Bash, etc.) belong in the gitignored .claude/settings.local.json -- never widen this committed file to grant them repo-wide." + }, + "enabledPlugins": { + "browsing@bim-ba": true, + "claude-md-management@claude-plugins-official": false, + "clickhouse@bim-ba": false, + "context7@context7-marketplace": false, + "core@bim-ba": true, + "documenting@bim-ba": true, + "drifts@bim-ba": true, + "plugin-dev@claude-plugins-official": false, + "skill-creator@claude-plugins-official": false, + "superpowers@claude-plugins-official": true + }, + "extraKnownMarketplaces": { + "claude-plugins-official": { + "source": { + "source": "github", + "repo": "anthropics/claude-plugins-official" + }, + "autoUpdate": true + }, + "superpowers-marketplace": { + "source": { + "source": "github", + "repo": "obra/superpowers-marketplace" + }, + "autoUpdate": true + }, + "context7-marketplace": { + "source": { + "source": "github", + "repo": "upstash/context7" + }, + "autoUpdate": true + }, + "bim-ba": { + "source": { + "source": "github", + "repo": "bim-ba/ai" + }, + "autoUpdate": true + } + } + } +} diff --git a/.rulesync/rules/overview.md b/.rulesync/rules/overview.md new file mode 100644 index 0000000..e97b975 --- /dev/null +++ b/.rulesync/rules/overview.md @@ -0,0 +1,41 @@ +--- +root: true +targets: + - '*' +globs: + - '**/*' +--- +# CLAUDE.md - refract + +refract compiles one neutral YAML API spec (`resource.yaml` + `client.yaml`) into a typed Python SDK, CLI, FastMCP server, models and tests. It is alpha: one target language (Python) and one proving ground, the `examples/ycli-tracker` golden oracle, whose checked-in `out/` the generator must reproduce byte for byte. + +Baseline agent discipline comes from the `core` and `drifts` plugins of the `bim-ba` marketplace; voice, tooling, Git and research defaults come from the personal layer in `~/.claude/CLAUDE.md`. This file carries only what is specific to this repository. + +## Layout + +| Path | Role | +|---|---| +| `src/refract/cli.py`, `generation.py` | the `refract` Typer entry point and the render driver | +| `src/refract/spec/` | `resource.yaml` / `client.yaml` loading and validation | +| `src/refract/ir/` | the typed intermediate representation | +| `src/refract/emitters/` | `ports.py` backend seam, `registry.py`, and `python/`, the one implemented backend | +| `src/refract/runtime/` | what generated code imports at run time (auth, base, request, session) | +| `tests/` | mirrors `src/refract/`; `tests/behavioral/` imports and runs emitted code | +| `examples/ycli-tracker/` | the golden-oracle spec plus its checked-in `out/` | +| `docs/design.md`, `docs/roadmap.md` | the full design and roadmap, ahead of the code in places | + +## Conventions + +- Python >= 3.12; `uv` only (`uv sync`, `uv run`), with `uv.lock` and the `dev` dependency group in `pyproject.toml`. +- ruff is both linter and formatter (`line-length = 100`, an explicit `select` list); `ty` is the type checker, configured with `error-on-warning = true`. +- `examples/` is excluded from ruff and from ty on purpose: it is external source used as a byte-equality target, so linting or reformatting it defeats the test it exists for. +- pytest runs with `--cov-fail-under=100` and `-m 'not behavioral'`; run the slow tests explicitly with `uv run pytest -m behavioral`. +- Versioning and releases are automated by release-please (`release-please-config.json`, `.github/workflows/release-please.yml`) — do not hand-edit the version. + +## Verification + +```sh +uv run ruff format --check . && uv run ruff check . && uv run ty check && uv run pytest +``` + +The same four steps `.github/workflows/ci.yml` runs. `uv run refract generate --check` is the separate drift gate: it renders in memory and fails if `examples/ycli-tracker/out/` has gone stale. diff --git a/AGENTS.md b/AGENTS.md deleted file mode 120000 index 681311e..0000000 --- a/AGENTS.md +++ /dev/null @@ -1 +0,0 @@ -CLAUDE.md \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..79a04b3 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,34 @@ +# CLAUDE.md - refract + +refract compiles one neutral YAML API spec (`resource.yaml` + `client.yaml`) into a typed Python SDK, CLI, FastMCP server, models and tests. It is alpha: one target language (Python) and one proving ground, the `examples/ycli-tracker` golden oracle, whose checked-in `out/` the generator must reproduce byte for byte. + +Baseline agent discipline comes from the `core` and `drifts` plugins of the `bim-ba` marketplace; voice, tooling, Git and research defaults come from the personal layer in `~/.claude/CLAUDE.md`. This file carries only what is specific to this repository. + +## Layout + +| Path | Role | +|---|---| +| `src/refract/cli.py`, `generation.py` | the `refract` Typer entry point and the render driver | +| `src/refract/spec/` | `resource.yaml` / `client.yaml` loading and validation | +| `src/refract/ir/` | the typed intermediate representation | +| `src/refract/emitters/` | `ports.py` backend seam, `registry.py`, and `python/`, the one implemented backend | +| `src/refract/runtime/` | what generated code imports at run time (auth, base, request, session) | +| `tests/` | mirrors `src/refract/`; `tests/behavioral/` imports and runs emitted code | +| `examples/ycli-tracker/` | the golden-oracle spec plus its checked-in `out/` | +| `docs/design.md`, `docs/roadmap.md` | the full design and roadmap, ahead of the code in places | + +## Conventions + +- Python >= 3.12; `uv` only (`uv sync`, `uv run`), with `uv.lock` and the `dev` dependency group in `pyproject.toml`. +- ruff is both linter and formatter (`line-length = 100`, an explicit `select` list); `ty` is the type checker, configured with `error-on-warning = true`. +- `examples/` is excluded from ruff and from ty on purpose: it is external source used as a byte-equality target, so linting or reformatting it defeats the test it exists for. +- pytest runs with `--cov-fail-under=100` and `-m 'not behavioral'`; run the slow tests explicitly with `uv run pytest -m behavioral`. +- Versioning and releases are automated by release-please (`release-please-config.json`, `.github/workflows/release-please.yml`) — do not hand-edit the version. + +## Verification + +```sh +uv run ruff format --check . && uv run ruff check . && uv run ty check && uv run pytest +``` + +The same four steps `.github/workflows/ci.yml` runs. `uv run refract generate --check` is the separate drift gate: it renders in memory and fails if `examples/ycli-tracker/out/` has gone stale. diff --git a/opencode.jsonc b/opencode.jsonc new file mode 100644 index 0000000..2f536ce --- /dev/null +++ b/opencode.jsonc @@ -0,0 +1,28 @@ +{ + "mcp": { + "graphify": { + "type": "local", + "command": [ + "graphify-mcp", + "--transport", + "stdio", + "/home/sava/git/bim-ba/refract/graphify-out/graph.json" + ], + "enabled": true + } + }, + "permission": { + "read": { + "*": "allow" + }, + "grep": { + "*": "allow" + }, + "glob": { + "*": "allow" + }, + "bash": { + "*": "allow" + } + } +} diff --git a/rulesync.jsonc b/rulesync.jsonc new file mode 100644 index 0000000..8a5e9eb --- /dev/null +++ b/rulesync.jsonc @@ -0,0 +1,6 @@ +{ + "$schema": "https://github.com/dyoshikawa/rulesync/releases/latest/download/config-schema.json", + "targets": ["claudecode", "codexcli", "opencode"], + "features": ["rules", "mcp", "commands", "subagents", "skills", "permissions"], + "delete": false +}