tangled-sync
[READ-ONLY] Mirror of https://github.com/ewanc26/tangled-sync. Move from GitHub to Tangled.org docs.ewancroft.uk/projects/tangled-sync
Star
Fork
Watch
tangled-sync AGENTS.md
3.2 kB · 24 lines
Markdown
at main

AGENTS.md #

Guidance for agents working on the archived tangled-sync repository. The maintained implementation is pkgs/packages/tangled-sync; do not resume feature development here unless the requested scope explicitly includes the tombstone.

Historical implementation #

  • src/index.ts loads src/.env, fetches one public GitHub user-repository page, clones missing directories, adds/pushes a tangled remote, may edit/commit/push README files to GitHub, and writes sh.tangled.repo records.
  • src/check.ts performs live configuration, AT Protocol login/read, Tangled SSH, GitHub API, and dependency checks. src/test-atproto.ts also logs in and reads records; neither is an isolated unit test.
  • src/lib/ holds configuration checks, shell execution, AT Protocol login, TID generation, and health probes.
  • README.md correctly marks the repository archived. SETUP.md and USAGE.md are historical and include stale descriptions: USAGE.md names missing src/validate-config.ts, which package.json still exposes as npm run validate.

Mutation hazards and current limitations #

  • Normal sync skips repositories whose AT Protocol record already exists; force mode processes all, but record creation still checks for an existing record. Neither mode is a dry run.
  • GitHub discovery uses /users/<name>/repos, does not paginate beyond its single request, and does not filter forks or archived repositories. It excludes only a repository whose name equals the username. Do not use this code for an owned/non-fork-only migration without fixing and testing selection.
  • Failure to push to Tangled is swallowed as a warning; the code then continues to mutate the README and create an AT Protocol record, so a record is not proof that the mirror push succeeded.
  • updateReadme runs git add <README>, git commit, and git push origin main. A commit includes any changes already staged in that worktree, and branch/remote assumptions are hard-coded. Never run it against valuable dirty repositories.
  • Repository names, usernames, paths, and URLs are interpolated into shell command strings through execSync. Validate or replace these calls with argument arrays before accepting untrusted values.
  • The custom TID uses millisecond time shifted to simulated microseconds plus a random clock ID; it is not the reference monotonic TID implementation. Remote URLs, the knot hostname, collection name, main branch, and GitHub source URLs are hard-coded.
  • Keep app passwords, tokens, SSH keys, .env, and session output out of Git and logs. Never force-push or delete remote records/content from this tombstone.

Validation #

For an explicitly requested archival fix, use npm install and npx tsc --noEmit; repair the missing validation entry point or script before claiming npm run validate works. Treat npm run check and npm run test-atproto as live network/auth probes, not tests, and do not run npm run sync or sync:force for routine validation. Exercise selection, shell argument handling, dirty-worktree refusal, push failure, README commits, pagination, and AT Protocol writes with mocked clients and disposable repositories. Implement the maintained correction in pkgs first when applicable.