From 528ca06e1144a2baaeb8682eb68a054c83a86c67 Mon Sep 17 00:00:00 2001 From: Piotr Durlej Date: Sun, 7 Jun 2026 16:48:02 +0200 Subject: [PATCH] docs: improve repo presentation --- .github/ISSUE_TEMPLATE/bug_report.yml | 61 ++++++++++++++++++++++ .github/ISSUE_TEMPLATE/config.yml | 5 ++ .github/ISSUE_TEMPLATE/feature_request.yml | 32 ++++++++++++ .github/pull_request_template.md | 13 +++++ .github/workflows/go.yml | 30 ++++++----- .gitignore | 1 + CONTRIBUTING.md | 43 +++++++++++++++ README.md | 46 ++++++++++------ SECURITY.md | 30 +++++++++++ 9 files changed, 231 insertions(+), 30 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.yml create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/feature_request.yml create mode 100644 .github/pull_request_template.md create mode 100644 CONTRIBUTING.md create mode 100644 SECURITY.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..32d514b --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,61 @@ +name: Bug report +description: Report a Things Cloud SDK, CLI, MCP, or sync bug. +title: "bug: " +labels: ["bug"] +body: + - type: markdown + attributes: + value: | + Do not paste Things credentials, tokens, HAR captures, or private task data. + - type: textarea + id: summary + attributes: + label: Summary + description: What broke? + validations: + required: true + - type: dropdown + id: surface + attributes: + label: Surface + options: + - SDK + - things-cloud-cli + - things-mcp + - sync engine + - local SQLite reader + - documentation + - other + validations: + required: true + - type: textarea + id: repro + attributes: + label: Reproduction + description: Include sanitized commands, inputs, or dry-run JSON when possible. + placeholder: | + 1. Run ... + 2. Expected ... + 3. Actual ... + validations: + required: true + - type: textarea + id: environment + attributes: + label: Environment + description: OS, Go version, Things Cloud SDK version/tag, Things app version if relevant. + placeholder: | + OS: + Go: + SDK tag: + Things app: + validations: + required: false + - type: textarea + id: logs + attributes: + label: Logs or output + description: Paste sanitized output only. + render: shell + validations: + required: false diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..8fc18c8 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,5 @@ +blank_issues_enabled: true +contact_links: + - name: Things app support + url: https://culturedcode.com/things/support/ + about: Contact Cultured Code for official Things app support. diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..faad626 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,32 @@ +name: Feature request +description: Suggest a new SDK, CLI, MCP, sync, or agent workflow capability. +title: "feature: " +labels: ["enhancement"] +body: + - type: textarea + id: problem + attributes: + label: Problem + description: What workflow are you trying to support? + validations: + required: true + - type: textarea + id: proposal + attributes: + label: Proposed solution + description: Describe the API, CLI command, MCP tool, or behavior you want. + validations: + required: true + - type: textarea + id: agent_contract + attributes: + label: Agent or JSON contract impact + description: If this affects agents, describe the expected stable input/output shape. + validations: + required: false + - type: textarea + id: alternatives + attributes: + label: Alternatives considered + validations: + required: false diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..ca8a11a --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,13 @@ +## Summary + +- + +## Verification + +- [ ] `go test ./...` + +## Notes + +- CLI/MCP JSON contract changed: no +- Raw Things Cloud write payload changed: no +- Docs updated: no diff --git a/.github/workflows/go.yml b/.github/workflows/go.yml index 9dd1bce..5e46e28 100644 --- a/.github/workflows/go.yml +++ b/.github/workflows/go.yml @@ -1,27 +1,29 @@ - -name: Go +name: CI on: push: pull_request: -jobs: +permissions: + contents: read +jobs: build: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@v4 - - name: Set up Go - uses: actions/setup-go@v4 - with: - go-version: '1.23' + - name: Set up Go + uses: actions/setup-go@v5 + with: + go-version-file: go.mod + cache: true - - name: Build - run: go build -v ./... + - name: Build + run: go build -v ./... - - name: Test - run: go test -v ./... + - name: Test + run: go test -v ./... - - name: Test Coverage - run: go test -cover ./... \ No newline at end of file + - name: Test Coverage + run: go test -cover ./... diff --git a/.gitignore b/.gitignore index cca5ce8..ebad101 100644 --- a/.gitignore +++ b/.gitignore @@ -22,6 +22,7 @@ *.env /tmp/ .env +.serena/ # HAR files (may contain credentials) *.har diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..2abcc85 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,43 @@ +# Contributing + +Thanks for improving this maintained Things Cloud SDK fork. + +This project is focused on safe automation around Things Cloud: + +- stable CLI and MCP JSON contracts +- dry-run behavior for agent-generated writes +- typed sync changes and persistent sync state +- read-only local Things SQLite inspection +- careful Things Cloud wire-format compatibility + +## Before Opening a PR + +Run: + +```bash +go test ./... +``` + +For CLI write changes, also verify at least one `--dry-run` command and include +the sanitized output shape in the PR description. + +Before changing raw write payloads, read `docs/client-side-bugs.md`. Small +wire-format changes can break Things.app sync behavior. + +## Pull Request Notes + +Good PR descriptions include: + +- the user-facing behavior changed +- CLI or MCP command examples, when relevant +- whether JSON output contracts changed +- the tests or smoke checks that ran + +Avoid unrelated refactors in behavior PRs. This repo is small enough that scoped +changes are easier to review and safer to ship. + +## Secrets + +Do not commit credentials, Things Cloud tokens, HAR captures, or local Things +database files. If a repro needs sensitive data, reduce it to sanitized JSON or +describe the relevant fields. diff --git a/README.md b/README.md index f5e4060..1a7209e 100644 --- a/README.md +++ b/README.md @@ -1,25 +1,46 @@ # Things Cloud SDK -[![Go](https://github.com/pdurlej/things-cloud-sdk/actions/workflows/go.yml/badge.svg)](https://github.com/pdurlej/things-cloud-sdk/actions/workflows/go.yml) +[![CI](https://github.com/pdurlej/things-cloud-sdk/actions/workflows/go.yml/badge.svg)](https://github.com/pdurlej/things-cloud-sdk/actions/workflows/go.yml) +[![Latest release](https://img.shields.io/github/v/release/pdurlej/things-cloud-sdk)](https://github.com/pdurlej/things-cloud-sdk/releases) +[![Go Reference](https://pkg.go.dev/badge/github.com/pdurlej/things-cloud-sdk.svg)](https://pkg.go.dev/github.com/pdurlej/things-cloud-sdk) +[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) -Unofficial Go SDK, CLI, and MCP server for the Things Cloud sync API used by -[Things](https://culturedcode.com/things/). +Maintained Go SDK, CLI, and MCP server for automating +[Things](https://culturedcode.com/things/) through the Things Cloud sync API. -This maintained fork is optimized for automation and agent workflows, especially -OpenClaw-style integrations that need predictable reads, safe writes, compact -JSON, and a stable Things Cloud module path. +Use it when you want Things automation that is cross-platform, scriptable, and +agent-friendly without writing directly to the local Things SQLite database. ```text Go module: github.com/pdurlej/things-cloud-sdk Preferred CLI: things-cloud-cli Compat CLI: things-cli MCP server: things-mcp -Current use: cloud API reads/writes, persistent sync, local read-only SQLite +Latest release: v0.2.3 +Focus: safe writes, stable JSON, MCP tools, persistent sync Maintainer: https://github.com/pdurlej ``` -The API is reverse engineered. Treat write paths carefully, use dry runs for -agent-generated changes, and pin release tags in production agent environments. +## What You Can Do + +- Read Things tasks from Inbox, Today, Anytime, Someday, Upcoming, projects, + areas, tags, search results, and completed/logbook history. +- Create, edit, complete, trash, move, and batch-update tasks from a CLI or MCP + host. +- Preview write payloads with `--dry-run` before touching Things Cloud. +- Run a persistent sync cache with typed change events for services, + dashboards, and feedback loops. +- Inspect local macOS Things data through a read-only SQLite adapter. + +## Project Status + +This is a maintained, unofficial fork focused on reliable automation and agent +integrations. It is not affiliated with Cultured Code, and the Things Cloud API +is reverse engineered. + +Production agents should pin release tags, use `--dry-run` for generated +writes, and avoid writing to the local Things SQLite database. The local reader +is intentionally read-only. ## LLM Integration Summary @@ -584,10 +605,3 @@ go build -o things-mcp ./cmd/things-mcp Before changing write payloads, read `docs/client-side-bugs.md` and add focused tests. Small-looking wire-format changes can break Things.app sync behavior. - -## Project Status - -This is not an official Cultured Code API. All requests and payloads are based on -reverse engineering. Contributions should preserve the automation-friendly -contract: stable JSON, safe dry-run behavior, typed sync changes, and explicit -separation between Cloud writes and local read-only inspection. diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..742ff8e --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,30 @@ +# Security Policy + +This is an unofficial, reverse-engineered Things Cloud SDK. It may handle Things +Cloud credentials, local cache files, and task data. + +## Supported Versions + +Security fixes target the latest tagged release and `main`. + +## Reporting a Vulnerability + +Do not paste credentials, tokens, HAR captures, or private task data into a +public issue. + +If GitHub private vulnerability reporting is available for this repository, use +it. Otherwise, open a minimal public issue without secrets and ask for a private +contact path. + +If a credential may have been exposed, rotate or revoke it before debugging. + +## Handling Sensitive Repros + +Preferred repro formats: + +- sanitized CLI commands +- sanitized dry-run JSON +- minimal redacted snippets from Things Cloud payloads +- clear expected vs actual behavior + +Avoid attaching full local Things databases or network captures.