npm package: @kansodata/openclaw-airflow-dag-git-plugin
Description: Native OpenClaw plugin to read and propose Airflow DAG changes via GitHub pull requests.
Latest version: 0.1.1

# @kansodata/openclaw-airflow-dag-git-plugin

Native OpenClaw plugin for controlled Airflow DAG `.py` operations through a GitHub pull-request workflow.

## Scope

### What it does

- Reads one allowlisted DAG file from GitHub (`airflow_dag_git_read_file`).
- Creates or updates one allowlisted DAG file through:
1. branch creation,
2. commit creation,
3. PR opening (`airflow_dag_git_open_pr`).

### What it does not do

- No direct writes to Airflow hosts.
- No auto-merge.
- No direct pushes to protected branches.
- No multi-file edits in V0.
- No delete/rename in V0.
- No CI workflow, secrets, or repo configuration edits.

## Why Git/PR instead of direct host writes

The plugin enforces controlled change management with:

- reviewable diffs,
- branch isolation,
- auditable history,
- standard GitHub rollback mechanics.

This reduces operational risk compared to direct host mutation.

## Architecture

```mermaid
flowchart LR
  U[User / Agent] --> H[OpenClaw Host]
  H --> P[airflow-dag-git plugin]
  P --> G[GitHub API]
  G --> R[(Target Repository)]
  R --> G
  G --> P
  P --> H
```

## Installation

```bash
openclaw plugins install @kansodata/openclaw-airflow-dag-git-plugin
```

## Configuration

Configure under `plugins.entries.airflow-dag-git.config`.

```json
{
  "plugins": {
    "entries": {
      "airflow-dag-git": {
        "enabled": true,
        "config": {
          "githubToken": "${secret:GITHUB_TOKEN}",
          "allowedOwners": ["kansodata"],
          "allowedRepos": ["airflow-dags"],
          "allowedDagPaths": ["dags/", "airflow/dags/"],
          "defaultBaseBranch": "main",
          "maxFileSizeBytes": 200000,
          "readOnly": false,
          "allowedNetworkHosts": ["internal-api.company.local"]
        }
      }
    }
  }
}
```

Also supported: `GITHUB_TOKEN` environment variable fallback.

## Tools

### `airflow_dag_git_read_file`

Input:

- `owner` (string)
- `repo` (string)
- `ref` (optional string)
- `path` (string)

Behavior:

- Validates owner/repo/path against allowlists.
- Requires `.py` under allowlisted DAG paths.
- Returns content, sha, resolved ref, and size.

### `airflow_dag_git_open_pr` (optional side effects)

Input:

- `owner` (string)
- `repo` (string)
- `baseBranch` (optional string)
- `targetPath` (string)
- `newContent` (string)
- `commitMessage` (string)
- `prTitle` (string)
- `prBody` (optional string)
- `branchName` (optional string)

Behavior (fail-closed):

- Validates owner/repo/path against allowlists.
- Accepts only `.py` under allowlisted DAG prefixes.
- Rejects traversal and absolute paths.
- Enforces max file size.
- Requires DAG marker (`DAG(` or `@dag`).
- Blocks dangerous patterns (`subprocess`, `os.system`, `eval(`, `exec(`).
- Blocks external `requests.*` unless host is allowlisted.
- Reads current file (if present), creates branch, writes one file, opens PR.
- Returns PR URL, PR number, created branch, commit sha, and short diff summary.

## Tool selection guidance

- Use `airflow_dag_git_open_pr` when proposing a DAG change. This is the primary action path.
- Use `airflow_dag_git_read_file` only when explicit repository inspection is needed.
- Prefer `open_pr` for change proposals, because it preserves review and rollback controls.
- Avoid routine pre-reads when the caller already has authoritative DAG content and only needs to propose an update.

## Smoke test evidence

The plugin has been validated end-to-end in a sandbox repository with successful PR creation through `airflow_dag_git_open_pr`. This confirms the branch, commit, and PR path under the current V0 scope.

## V0 limitations

- Single-file change only.
- No delete/rename.
- No auto-merge.
- No direct host writes.
- No CI workflow edits.

## Release readiness notes

Validated:

- Tool contract wiring and schema checks.
- Guardrails for allowlists, path controls, DAG markers, and blocked patterns.
- End-to-end PR workflow in sandbox (branch + commit + PR creation).

Out of scope:

- Multi-file edits.
- Delete/rename operations.
- Direct Airflow host mutations.
- Auto-merge or direct branch pushes bypassing PR review.

Recommended checks before publishing to npm / ClawHub:

1. Run `npm run lint`, `npm run typecheck`, and `npm test`.
2. Confirm `openclaw.plugin.json` metadata matches published package metadata.
3. Verify final package contents with `npm pack --dry-run`.

## Rollback flow

1. Close the PR if not merged.
2. Delete the created branch.
3. If merged, revert the merge commit through standard GitHub process.

## Development

```bash
npm install
npm run lint
npm run typecheck
npm test
```