markbennett.ca
WIP: A simple cli for daily tangled use cases and AI integration. This is for my personal use right now, but happy if others get mileage from it! :)
Updates and clarifications.
+6
-58
+6
-58
README.md
+6
-58
README.md
···
67
67
68
68
LLMs can't read error messages buried in HTML or long stack traces. Provide a `--no-input` flag that forces the CLI to error if it can't resolve context or if required flags are missing.
69
69
70
-
## 6. Implementation Roadmap
71
-
72
-
### Phase 1: Context & Auth (The "Plumbing")
73
-
74
-
1. **Auth Storage:** Store the AT Proto session in conf.
75
-
2. **Context Resolver:**
76
-
- Implement a helper getRepoFromContext().
77
-
- It calls git remote get-url origin.
78
-
- Regex matches the Tangled DID from the URL.
79
-
- Returns the repo param required by XRPC.
80
-
81
-
### Phase 2: CRUD Commands (The "Porcelain")
82
-
83
-
1. **repo create:**
84
-
- Creates record via XRPC.
85
-
- **Auto-config:** Runs git init and git remote add if local dir is empty.
86
-
2. **issue list/create:**
87
-
- Uses getRepoFromContext() so the user just types tangled issue create.
88
-
89
-
### Phase 3: The "Machine" View
90
-
91
-
1. Implement a generic Formatter class.
92
-
- Formatter.render(data, { json: true, fields: \['id', 'name'\] })
93
-
- If json: pick fields, JSON.stringify.
94
-
- If human: use cli-table3.
95
-
96
-
## 7. Example: The Context Pattern
97
-
98
-
This is how we solve the usability problem (and the LLM hallucination problem).
99
-
100
-
`// src/lib/context.ts`
101
-
`import simpleGit from 'simple-git';`
102
-
103
-
`export async function resolveRepoContext(explicitFlag?: string): Promise<string> {`
104
-
`// 1. If user passed --repo flag, use it`
105
-
`if (explicitFlag) return explicitFlag;`
106
-
107
-
`// 2. Try to infer from local git config`
108
-
`const git = simpleGit();`
109
-
`const isRepo = await git.checkIsRepo();`
110
-
111
-
`if (isRepo) {`
112
-
`const remotes = await git.getRemotes(true);`
113
-
`const tangledRemote = remotes.find(r => r.name === 'tangled' || r.name === 'origin');`
114
-
115
-
`if (tangledRemote) {`
116
-
`// Logic to extract DID from URL (e.g., [https://tangled.sh/did:plc:123/repo](https://tangled.sh/did:plc:123/repo))`
117
-
`const did = extractDidFromUrl(tangledRemote.refs.fetch);`
118
-
`if (did) return did;`
119
-
`}`
120
-
121
-
`}`
122
-
123
-
`throw new Error("Could not infer repository context. Please use --repo <did> or run this inside a Tangled repository.");`
124
-
`}`
125
-
126
70
### Summary of Improvements
127
71
128
72
- **Context Inference:** This is the "killer feature" of gh that we are copying. It makes the tool usable for humans and safer for LLMs (less typing \= fewer errors).
···
132
76
### Examples Tangled CLI Usage
133
77
134
78
```bash
135
-
tangled auth login
79
+
tangled auth login (opens a browser for auth)
136
80
tangled repo create my-new-repo
137
81
cd my-new-repo
138
82
tangled issue create "Bug: Something is broken"
139
83
tangled issue list --json "id,title"
140
84
```
141
85
86
+
### Task Management
87
+
88
+
We're bootstrapping task tracking with TODO.md, but will migrate all tasks into Tangled issues and dog food the product as soon as we have basic issue creation and listing working.
89
+
142
90
### Outstanding Issues
143
91
144
92
1. Can we allow auth through the web browser, rather than just CLI username/password? This would be more secure and user-friendly.
145
93
2. The GitHub CLI manages the private keys allowing you to authenticate git operations. Can we do something similar, or will users have to manage SSH keys separately? Currently, I store my SSH keys in 1Password which signs requests for me. It would be great if tangled CLI could detect this and use it seamlessly, itentifying the user by the signed ssh key.
146
-
3. How should we handle storing the AT Proto session securely? The GitHub CLI uses the OS keychain. We could do something similar.
94
+
3. How should we handle storing the AT Proto session securely? The GitHub CLI uses the OS keychain. We could do something similar. How does this work across different platforms (Windows, macOS, Linux)? We want to avoid storing sensitive tokens in plaintext files.
147
95
4. How are settings resolved (e.g. local config file, home folder, command-line flags)? We should define a clear precedence order.