feat: initial release of opendoc

Author: Taozizz

.claude-plugin/marketplace.json

@@ -0,0 +1,19 @@
+{
+  "name": "arcships",
+  "owner": {
+    "name": "arcships"
+  },
+  "metadata": {
+    "description": "arcships' Claude Code plugins."
+  },
+  "plugins": [
+    {
+      "name": "opendoc",
+      "source": "./skill",
+      "description": "Local knowledge base: one-way mirror of authorized Notion/Feishu docs into a local read-only Markdown tree the agent searches directly with Grep/Glob/Read. The binary is not committed — on first use the skill offers a one-time, checksum-verified download of the build for this platform.",
+      "author": {
+        "name": "arcships"
+      }
+    }
+  ]
+}

.github/workflows/ci.yml

@@ -0,0 +1,56 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+# Read-only token: CI builds and tests, it never writes to the repo.
+permissions:
+  contents: read
+
+# A newer push to the same branch/PR cancels the in-flight run.
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-go@v5
+        with:
+          # Single source of truth for the Go version: go.mod's `go` directive.
+          go-version-file: go.mod
+          cache: true
+
+      - name: gofmt
+        run: |
+          unformatted="$(gofmt -l . | grep -v '^skill/bin/' || true)"
+          if [ -n "$unformatted" ]; then
+            echo "These files are not gofmt-ed:"
+            echo "$unformatted"
+            exit 1
+          fi
+
+      - name: go vet
+        run: go vet ./...
+
+      - name: staticcheck
+        uses: dominikh/staticcheck-action@v1
+        with:
+          version: latest
+          install-go: false
+
+      - name: build
+        run: go build ./...
+
+      - name: test (race + coverage)
+        run: go test -race -covermode=atomic ./...
+
+      # The delivery unit is a static, CGO-free single binary.
+      # Guard that the packaging build still works, not just `go build ./...`.
+      - name: delivery build (static skill binary)
+        run: CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" -o skill/bin/opendoc ./cmd/opendoc

.github/workflows/release.yml

@@ -0,0 +1,47 @@
+name: release
+
+# Tag-triggered. Pushing a tag like v0.1.0 cross-compiles the engine for
+# every supported platform, generates sha256 checksums, and publishes them
+# as a GitHub Release. The download script (skill/scripts/download-binary.sh)
+# consumes these assets. Keep the tag in sync with skill/.claude-plugin/plugin.json.
+on:
+  push:
+    tags: ['v*']
+
+# gh release create needs write access to create the release and upload assets.
+permissions:
+  contents: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+
+      # Cross-compile all targets in one job — pure-Go, CGO-free, so a single
+      # Linux runner produces every platform binary in seconds. Flags match
+      # scripts/build-skill.sh (CGO_ENABLED=0, -trimpath) for reproducibility.
+      - name: cross-compile
+        run: |
+          mkdir -p dist
+          for target in darwin/arm64 darwin/amd64 linux/amd64 linux/arm64; do
+            os="${target%/*}"; arch="${target#*/}"
+            out="dist/opendoc-${os}-${arch}"
+            echo "building $out"
+            CGO_ENABLED=0 GOOS="$os" GOARCH="$arch" go build -trimpath -ldflags="-s -w" -o "$out" ./cmd/opendoc
+          done
+          ( cd dist && sha256sum opendoc-* > checksums.txt && cat checksums.txt )
+
+      - name: publish release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh release create "$GITHUB_REF_NAME" \
+            --repo "$GITHUB_REPOSITORY" \
+            --title "$GITHUB_REF_NAME" \
+            --generate-notes \
+            dist/opendoc-* dist/checksums.txt

.gitignore

@@ -0,0 +1,4 @@
+.DS_Store
+
+# built skill binary (produced by scripts/build-skill.sh)
+skill/bin/opendoc

AGENTS.md

@@ -0,0 +1,60 @@
+# AGENTS.md
+
+## What opendoc is
+
+opendoc is a one-way sync engine that mirrors documents you've authorized in
+Notion and Feishu into a local, read-only Markdown tree. It never writes
+back to the source platform. The mirror is meant to be consumed directly by
+coding agents with Grep/Glob/Read — no API calls, no credentials, no network
+access needed at read time. A companion Claude Code plugin (`skill/`) wraps
+the `opendoc` binary and exposes it to agents as a skill.
+
+## Repo layout
+
+- `cmd/opendoc` — CLI entrypoint (`main.go`), wires subcommands to `internal/cli`.
+- `internal/adapter` — platform-agnostic contract between the engine and a
+  concrete source (Notion, Feishu, ...); the engine only depends on this interface.
+- `internal/cli` — subcommand dispatch and flag parsing (init, sync, status,
+  doctor, resolve, schedule).
+- `internal/config` — on-disk mirror configuration (`.internal/config.toml`)
+  and its readers/writers.
+- `internal/engine` — the sync pipeline: fetch, diff, write, index, manifest bookkeeping.
+- `internal/feishu` — Feishu/Lark adapter (bitable, doc fetch, metadata).
+- `internal/frontmatter` — deterministic YAML frontmatter rendering for mirrored files.
+- `internal/layout` — mirror-root resolution and on-disk directory layout.
+- `internal/manifest` — `manifest.sqlite`, the sync engine's bookkeeping ledger.
+- `internal/naming` — filesystem-safe path/file naming and collision rules.
+- `internal/notion` — Notion adapter (query, fetch, properties→frontmatter mapping).
+- `internal/ratelimit` — token bucket + backoff helpers for platform QPS limits.
+
+## Build & test
+
+```
+go build ./...
+go test ./...
+./scripts/build-skill.sh   # builds the binary into skill/bin/opendoc and symlinks it into ~/.claude/skills/opendoc
+```
+
+## Key invariants
+
+- **Fidelity-first**: never silently drop content. Anything that can't be
+  rendered faithfully gets a placeholder tag, and the loss is counted in the
+  sync report — not swallowed.
+- **Mirror is read-only**: nothing in the mirrored tree is ever written back
+  to Notion or Feishu.
+- **Manifest keys are platform-native IDs**: the sync ledger is keyed by the
+  source platform's own document/page/row IDs, not derived or local ones.
+- **content_hash is computed before link rewriting**: the hash that drives
+  change detection reflects the fetched content, not the post-processed
+  (link-rewritten) output.
+- **Doctor codes are stable identifiers**: probe/failure codes (e.g. `F1`,
+  `F2-NOAUTH`, `N2-INVALID`, `N3-EMPTY`, `G2-QUOTA-LOW`) and exit codes (e.g.
+  `3` = `ExitNotInitialized`) are part of the tool's contract. Don't rename
+  or renumber them — scripts and docs key off the literal strings.
+
+## `skill/SKILL.md`
+
+This file is runtime instructions read by coding agents, not just
+documentation. Its semantics (what it tells an agent to do, and when) must
+not drift casually — treat behavioral changes there with the same care as a
+CLI flag change.

CHANGELOG.md

@@ -0,0 +1,24 @@
+# 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).
+
+## [Unreleased]
+
+### Added
+
+- Initial release of opendoc: one-way mirroring of authorized Notion and
+  Feishu/Lark documents into a local, read-only Markdown tree.
+  - Incremental sync with full-reconciliation rounds, delete/move tracking,
+    and a permission-flap guard.
+  - Content-addressed asset pool, two-phase internal-link rewriting, and an
+    auto-generated `INDEX.md` library map.
+  - Embedded Feishu engine (no external CLI or Node runtime required);
+    Notion via the official API with a read-only integration token.
+  - Agent-first CLI: `init` / `sync` / `status` / `doctor` / `resolve` /
+    `schedule`, with structured `--json` output, deterministic exit codes,
+    and stable doctor failure codes.
+  - Claude Code plugin (`skill/`) that wraps the engine and teaches agents
+    how to retrieve from the mirror.