diff --git a/README.md b/README.md index 1f4960174..3c941c8ab 100644 --- a/README.md +++ b/README.md @@ -1,198 +1,67 @@ -![GitHub1s](https://raw.githubusercontent.com/conwnet/github1s/master/resources/images/logo.svg) +![GitHub1s](resources/images/logo.svg) -# github1s +# GitHub1s -One second to read GitHub code with VS Code. +GitHub1s is a browser-based code explorer built on VS Code. Browse files, search code, and review changes without cloning a repository. Connect your preferred model to the built-in AI chat for help understanding the code. -## Usage +**[๐ŸŒ Try it now](https://github1s.com/conwnet/github1s)** ยท [๐Ÿ“– Usage guide](docs/usage.md) ยท [๐Ÿ”ฎ AI setup](docs/ai.md#configure-a-model) -Just add `1s` after `github` and press `Enter` in the browser address bar for any repository you want to read. +## ๐Ÿš€ Quick start -For example, try it on the VS Code repo: +Add **`1s` after `github`** in a repository URL: -[https://github1s.com/microsoft/vscode](https://github1s.com/microsoft/vscode) - -![VS Code - GitHub1s](https://raw.githubusercontent.com/conwnet/github1s/master/resources/images/vs-code-github1s.png) - -You can also use [https://gitlab1s.com](https://gitlab1s.com) or [https://npmjs1s.com](https://npmjs1s.com) in the same way. - -For browser extensions, see [Third-party Related Projects](https://github.com/conwnet/github1s#third-party-related-projects). - -Or save the following code snippet as a bookmarklet, you can use it to quickly switch between github.com and github1s.com (GitHub markdown doesn't allow js links, so just copy it into a bookmark). - -``` -javascript: window.location.href = window.location.href.replace(/github(1s)?.com/, function(match, p1) { return p1 ? 'github.com' : 'github1s.com' }) +```text +https://github.com/microsoft/vscode + โ†“ +https://github1s.com/microsoft/vscode ``` -### Develop in the cloud - -To edit files, run Docker containers, create pull requests and more, click the "Develop your project on [Gitpod](https://www.gitpod.io)" button in the status bar. You can also open the Command Palette (default shortcut `Ctrl+Shift+P`) and choose `GitHub1s: Edit files in Gitpod`. - -![Gitpod Status Bar](https://raw.githubusercontent.com/conwnet/github1s/master/resources/images/gitpod-statusbar.png) - -## Documentation - -- [How it works](https://github.com/conwnet/github1s/blob/master/docs/guide.md) -- [Roadmap](https://github.com/conwnet/github1s/projects/1) - -## Enabling Private Repositories - -If you want to view non-public repositories, you need to add an OAuth token. The token is stored only in your browser, and only send to GitHub when fetching your repository's files. Click on the icon near the bottom of the left-hand row of icons, and the dialog box will prompt you for it, and even take you to your GitHub settings page to generate one, if needed. - - - -## Screenshots - -![VS Code - GitHub1s](https://raw.githubusercontent.com/conwnet/github1s/master/resources/images/GitHub1sDemo1.gif) - -![VS Code - GitHub1s](https://raw.githubusercontent.com/conwnet/github1s/master/resources/images/demo.png) - -## Development - -### Cloud-based development - -You can start an online development environment with [Gitpod](https://www.gitpod.io) by clicking the following button: - -[![Gitpod ready-to-code](https://img.shields.io/badge/Gitpod-ready--to--code-blue?logo=gitpod)](https://gitpod.io/#https://github.com/conwnet/github1s) - -### Local development - -```bash -git clone git@github.com:conwnet/github1s.git -cd github1s -npm install -npm run watch -# The cli will automatically open http://localhost:8080 once the build is completed. -# You can visit http://localhost:8080/conwnet/github1s if it doesn't. -``` - -#### Local development with full VS Code build - -You need [these prerequisites (the same ones as for VS Code)](https://github.com/microsoft/vscode/wiki/How-to-Contribute#prerequisites) for development with full VS Code build. -Please make sure you could build VS Code locally before the watch mode. - -To verify the build: - -```bash -cd github1s -npm run build:vscode -``` - -After the initial successful build, you could use the watch mode: - -```bash -cd github1s -npm install -npm run watch-with-vscode -# The cli will automatically open http://localhost:8080 once the build is completed. -# You can visit http://localhost:8080/conwnet/github1s if it doesn't. -``` - -### ... or ... VS Code + Docker Development - -You can use the VS Code plugin [Remote-Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) `Dev Container` to use a Docker container as a development environment. - -1. Install the Remote-Containers plugin in VS Code & Docker -2. Open the Command Palette (default shortcut `Ctrl+Shift+P`) and choose `Remote-Containers: Clone Repository in Container Volume...` -3. Enter the repo, in this case `https://github.com/conwnet/github1s.git` or your forked repo -4. Pick either, `Create a unique volume` or `Create a new volume` - - - Now VS Code will create the docker container and connect to the new container so you can use this as a fully setup environment! - -5. Open a new VS Code Terminal, then you can run the `npm install` commands listed above. - -```bash -npm install -npm run watch -# The cli will automatically open http://localhost:8080 once the build is completed. -# You can visit http://localhost:8080/conwnet/github1s if it doesn't. -``` - -### Format all codes - -```bash -npm run format -``` - -It uses `prettier` to format all possible codes. - -## Build - -```bash -npm install -npm run build -``` - -## Feedback - -- If something is not working, [create an issue](https://github.com/conwnet/github1s/issues/new) - -## Sponsors - -The continued development and maintenance of GitHub1s is made possible by these generous sponsors: +Public repositories can be browsed **without signing in**, subject to the upstream services' access and rate limits. - - -
- -
+![A repository open in GitHub1s, with the file explorer and README preview](resources/images/demo.png) -## Partners +You can also browse GitLab repositories at [gitlab1s.com](https://gitlab1s.com) and published npm packages at [npmjs1s.com](https://npmjs1s.com). See the [usage guide](docs/usage.md) for URL formats, authentication, and navigation. -We are partnered with [OSS Insight](https://ossinsight.io/?utm_source=github1s&utm_medium=github&utm_campaign=ghtrending) to get the Trending Repositories & some more Interesting Analytics. [OSS Insight](https://ossinsight.io/?utm_source=github1s&utm_medium=github&utm_campaign=ghtrending) provides deep insights into GitHub repos, developers, and curated repo lists from billions of GitHub events. Itโ€™s built with [TiDB Cloud](https://www.pingcap.com/tidb-cloud/?utm_source=github1s&utm_medium=github&utm_campaign=ghtrending). +## โœจ Features - - -
- -
+- **Explore a project.** Browse directories, find files, and search code in a familiar VS Code interface. +- **Trace a change.** Switch branches or tags, inspect commits and file history, and review pull or merge request diffs on GitHub and GitLab. +- **Understand complex code.** Ask GitHub1s AI about a file or selection, then follow up on implementation details. +- **Access private repositories.** Connect your GitHub or GitLab account, or supply an access token with the necessary permissions. -## Maintainers! :blush: +Remote repositories are **read-only**. Search and code navigation depend on the repository platform and available upstream services; see [capabilities and limits](docs/usage.md#capabilities-and-limits). - - - - - - -

netcon
๐Ÿ’ป ๐Ÿ–‹
xcv58
๐Ÿ’ป ๐Ÿ–‹
Siddhant Khare
๐Ÿ’ป ๐Ÿ–‹
+## ๐Ÿค– GitHub1s AI -## Stargazers over time +Get a repository overview, explain a file or selection, and ask follow-up questions. The assistant can look up relevant code as you chat. -[![Stargazers over time](https://api.star-history.com/svg?repos=conwnet/github1s&type=Date)](https://star-history.com/#conwnet/github1s&Date) +Click **Toggle Secondary Side Bar** in the layout controls at the top of GitHub1s to open the AI panel. -
-Third-party Related Projects -
+Use a **model endpoint that accepts browser requests**. Messages and code context are sent to the selected endpoint. See the [AI guide](docs/ai.md) for configuration and data handling. -### Chrome Extensions +## ๐Ÿ“š Documentation -- [Repositree](https://chrome.google.com/webstore/detail/repositree/lafjldoccjnjlcmdhmniholdpjkbgajo) ([chouglesaud/repositree](https://github.com/chouglesaud/repositree)) -- [github-code-viewer](https://chrome.google.com/webstore/detail/github-code-viewer/ecddapgifccgblebfibdgkagfbdagjfn) ([febaoshan/edge-extensions-github-code-viewer](https://github.com/febaoshan/edge-extensions-github-code-viewer)) -- Github1s Extension ([Darkempire78/GitHub1s-Extension](https://github.com/Darkempire78/GitHub1s-Extension)) -- [Github Web IDE](https://chrome.google.com/webstore/detail/adjiklnjodbiaioggfpbpkhbfcnhgkfe) ([zvizvi/Github-Web-IDE](https://github.com/zvizvi/Github-Web-IDE)) -- [shortcut to github1s](https://chrome.google.com/webstore/detail/shortcut-to-github1s/gfcdbodapcbfckbfpmgeldfkkgjknceo) ([katsuhisa91/github1s-shortcut](https://github.com/katsuhisa91/github1s-shortcut)) -- [Github1s Shortut - Open source](https://github.com/Fauzdar1/Github1s) -- [โšก๏ธ 1s to GitHub1s!](https://github.com/holazz/webext-github1s) -- [github1s Google Chrome Extensions](https://github.com/Lonely-Mr-zhang/github_1s_vscode) +| Guide | What you will find | +| ------------------------------------ | ------------------------------------------------------- | +| [Using GitHub1s](docs/usage.md) | Navigation, authentication, search, and troubleshooting | +| [GitHub1s AI](docs/ai.md) | Model setup, context, tools, and data handling | +| [Development](docs/development.md) | Local setup, builds, and checks | +| [Architecture](docs/architecture.md) | Components, data flow, and source layout | +| [Deployment](docs/deployment.md) | Hosting, OAuth, and service configuration | +| [Community](docs/community.md) | Third-party extensions and star history | -### Firefox Extensions +## ๐Ÿค Contributing -- [Repositree](https://addons.mozilla.org/en-US/firefox/addon/repositree/) ([chouglesaud/repositree](https://github.com/chouglesaud/repositree)) -- [Github1s Extension](https://addons.mozilla.org/firefox/addon/github1s-extension) ([Darkempire78/GitHub1s-Extension](https://github.com/Darkempire78/GitHub1s-Extension)) -- [Github1s](https://addons.mozilla.org/firefox/addon/github1s/) ([mcherifi/github1s-firefox-addon](https://github.com/mcherifi/github1s-firefox-addon)) -- [Github Web IDE](https://addons.mozilla.org/firefox/addon/github-web-ide/) ([zvizvi/Github-Web-IDE](https://github.com/zvizvi/Github-Web-IDE)) +See the [development guide](docs/development.md) to run GitHub1s locally. Report bugs and suggest improvements through [GitHub Issues](https://github.com/conwnet/github1s/issues). -### Microsoft Edge Extensions +## ๐Ÿ‘ฅ Maintainers -- [github-code-viewer](https://microsoftedge.microsoft.com/addons/detail/githubcodeviewer/jaaaapanahkknbgdbglnlchbjfhhjlpi) ([febaoshan/edge-extensions-github-code-viewer](https://github.com/febaoshan/edge-extensions-github-code-viewer)) -- [Github Web IDE](https://microsoftedge.microsoft.com/addons/detail/akjbkjciknacicbnkfjbnlaeednpadcf) ([zvizvi/Github-Web-IDE](https://github.com/zvizvi/Github-Web-IDE)) +[conwnet](https://github.com/conwnet) ยท [xcv58](https://github.com/xcv58) ยท [Siddhant Khare](https://github.com/Siddhant-K-code) -### Safari Extension +## ๐Ÿ’– Acknowledgments -- [GitHub1s-For-Safari-Extension](https://apps.apple.com/us/app/readcodeonline/id1569026520?mt=12) ([code4you2021/GitHub1s-For-Safari-Extension](https://github.com/code4you2021/GitHub1s-For-Safari-Extension)) +Thanks to everyone who has contributed to GitHub1s, and to [Sourcegraph](https://sourcegraph.com/), [searchcode](https://searchcode.com/), and [OSS Insight](https://ossinsight.io/) for their support of the project. -### Tampermonkey scripts +## ๐Ÿ“„ License -- [Mr-B0b/TamperMonkeyScripts/vscode.js](https://github.com/Mr-B0b/TamperMonkeyScripts/blob/main/vscode.js) -
+[MIT](LICENSE) diff --git a/docs/ai.md b/docs/ai.md new file mode 100644 index 000000000..6220819df --- /dev/null +++ b/docs/ai.md @@ -0,0 +1,116 @@ +# GitHub1s AI + +[Documentation](guide.md) ยท [Using GitHub1s](usage.md) + +GitHub1s AI is the built-in assistant for asking questions about a repository. It can explain attached files or selections and use repository tools to find relevant code. You configure the model endpoint and API key used for each conversation. + +## Configure a model + +1. Click **Toggle Secondary Side Bar** in the layout controls at the top of GitHub1s to open the AI panel. +2. Click the gear icon at the top of the AI panel, then select **Models โ†’ Add model**. +3. Enter a **Name**, choose a **Provider** and, where available, a **Protocol**. +4. Set the **Base URL**, **API key**, and **Model ID** for an endpoint you can access from your browser. +5. Select **Save Model**, then click **Back to chat**. + +You can also open the Command Palette (`F1`) and run **GitHub1s AI: Open Chat** or **GitHub1s AI: Open AI Settings**. + +The first saved model is selected automatically. With multiple configurations, use the model selector in the chat composer to choose one. + +### Providers and protocols + +| Provider | Default protocol | Other supported protocols | Default base URL | +| --------- | ----------------------- | ------------------------------------ | ------------------------------ | +| Custom | OpenAI Chat Completions | OpenAI Responses, Anthropic Messages | Supply your endpoint | +| OpenAI | OpenAI Responses | OpenAI Chat Completions | `https://api.openai.com/v1` | +| Anthropic | Anthropic Messages | โ€” | `https://api.anthropic.com/v1` | + +Use the API base URL, such as `https://api.example.com/v1`, rather than a complete generation-request URL. The URL must use HTTP or HTTPS and cannot contain credentials, a query string, or a fragment. Use a model ID available through your endpoint. + +### Browser access + +Model requests originate in your browser. The endpoint must support browser requests, including the necessary cross-origin resource sharing (CORS) headers. An endpoint that works from a server-side script may still reject a browser request. Local endpoints can also be affected by the browser's HTTPS and local-network access rules. + +## Ask questions with context + +Start with **Repository overview**, **Explain current file**, or **Explain selection**, or type a question in the chat composer. + +Use the composer toolbar's **Add fileโ€ฆ**, **Attach current file**, or **Attach current selection** buttons. The editor action **Add to GitHub1s AI Chat** attaches the selection when one exists, or the current file otherwise. + +Attached content is read when you send the message. Remove a pending attachment with its remove button before sending. Click an attachment chip to open its source file or selection. + +**Include recent files** is enabled by default. It adds up to five recently viewed file paths to the model's context; the assistant can then read those files with its tools. Turn it off in the composer when those paths are not relevant to the question. + +**New Chat** starts a separate conversation and clears pending attachments. Previous conversations remain available through **GitHub1s AI: Show History**. + +### Customize responses + +In **AI Settings โ†’ Prompts**, add preferences such as the response language under **User Rules**, then select **Save prompts**. **Instructions** replaces the default assistant instructions, and **Quick Actions** customizes the starter questions. Leave instruction or quick-action fields empty to use their defaults. **Reset** updates the form; select **Save prompts** to save the reset values. + +## Repository tools + +The assistant has four built-in tools: + +| Tool | Purpose | +| -------- | ------------------------------------ | +| `read` | Read a text file or a range of lines | +| `ls` | List a directory | +| `glob` | Find files by a path pattern | +| `search` | Search text in files | + +These tools read within the open workspace. Results are bounded: for example, `read` accepts files up to 5 MiB and returns at most 2,000 lines per call. Long lines and tool output can be truncated, and searches depend on the workspace's search provider. These are tool limits; attached files use a separate context-loading path. + +For a large repository, ask about a specific directory, file, or symbol so the assistant can retrieve focused context. + +## Connect MCP servers + +Model Context Protocol (MCP) servers add tools to the chat. Open **GitHub1s AI: Open AI Settings**, select **MCP**, and enter a configuration such as: + +```json +{ + "mcpServers": { + "example": { + "type": "http", + "url": "https://example.com/mcp", + "headers": { + "Authorization": "Bearer YOUR_TOKEN" + } + } + } +} +``` + +Replace the example URL and token, then select **Save MCP settings**. Changes apply to the next response. Supported transports are `http` and `sse`; local `stdio` servers are unavailable in the browser. Headers are optional, and the server must allow browser access. + +Configured MCP tools become available to the assistant. Their capabilities determine which external actions it can perform; they are not restricted by the built-in repository tools' read-only behavior. Connect servers whose tools you intend the assistant to use. + +Save `{ "mcpServers": {} }` to remove all configured MCP connections. + +## Data and storage + +| Data | Where it goes | +| ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | +| Model configuration, including API keys | Saved in browser-backed VS Code extension global state; the selected credentials are used for model requests | +| Messages, attached code, recent file paths, and retrieved tool results | Included in requests to the configured model endpoint as conversation context | +| Conversation history | Saved in browser-backed extension storage, separated by workspace | +| MCP configuration and credentials | Saved in extension global state; used to connect to the configured servers | +| MCP tool calls | Sent to the corresponding server; their results become available to the model | + +The model and MCP services receive the data sent to them under their own service policies. Select endpoints appropriate for the repository content you plan to discuss. + +### Manage saved data + +- **Delete one conversation:** open **Show History**, use its delete action, and confirm **Delete**. +- **Export conversations:** in AI Settings, open **General โ†’ Export history โ†’ Export**. The JSON contains conversation data for the current workspace, including stored message and tool content. +- **Reset AI data:** in **General**, select **Clear all data** and confirm. This removes local AI conversations across all workspaces, model settings and API keys, MCP settings, and prompt settings. + +## Troubleshooting + +| Message or symptom | What to check | +| ------------------------------------------ | ----------------------------------------------------------------------------------- | +| `Select a model before sending a message.` | Add a model and select it in the composer | +| Authentication failure | Check the API key and the endpoint account's access | +| Endpoint or model not found | Check the base URL, protocol, and model ID | +| Unable to reach the endpoint | Check network access, CORS, and browser restrictions on the endpoint | +| Rate limit reached | Follow the model service's retry guidance | +| Missing repository context | Attach the relevant file or selection; check whether repository search is available | +| Unable to load MCP tools | Check the server URL, credentials, CORS support, and tool-name conflicts | diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 000000000..08628c81f --- /dev/null +++ b/docs/architecture.md @@ -0,0 +1,74 @@ +# Architecture + +[Documentation](guide.md) ยท [Development](development.md) ยท [Deployment](deployment.md) + +GitHub1s combines a browser build of VS Code with extensions that expose remote repositories as read-only workspaces. The browser loads files on demand through platform APIs and external code services. Pages Functions handle OAuth callbacks and a GitHub code-search proxy; a separate Worker supplies repository discovery snapshots. + +## Components + +| Component | Responsibility | Source | +| -------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------- | +| Web application | Select the platform and workspace, load VS Code, and bridge browser authentication | [`src/`](../src/) | +| VS Code web package | Build and package VS Code with GitHub1s-specific source overlays | [`vscode-web/`](../vscode-web/) | +| Repository extension | Route repository URLs, provide files and search, and display history and diffs | [`extensions/github1s/`](../extensions/github1s/) | +| AI extension | Manage chat, model connections, repository context, and optional MCP tools | [`extensions/github1s-ai/`](../extensions/github1s-ai/) | +| Pages Functions | Exchange OAuth authorization codes and proxy GitHub REST code search | [`functions/`](../functions/) | +| Discovery Worker | Collect public repositories and publish scheduled snapshots | [`workers/discovery/`](../workers/discovery/) | + +The root `src/` directory is the application entry point. VS Code source overlays live under `vscode-web/src/`. + +## Opening a repository + +1. [`src/index.ts`](../src/index.ts) selects a platform from the hostname and extracts the repository or package from the path. +2. [`src/config.ts`](../src/config.ts) creates the workspace configuration. GitHub, GitLab, and npm use different URI schemes; the GitHub home page opens Discovery. +3. The [repository extension](../extensions/github1s/src/extension.ts) registers adapters and VS Code providers. +4. A platform adapter parses the URL and supplies a data source. VS Code requests files, directory listings, or search results through the corresponding provider. +5. The extension fetches data and presents it in the editor, Explorer, or source control views. + +The file system providers are registered as read-only. The separate `/editor` entry opens an editor workspace without mounting a remote repository. + +```mermaid +flowchart TD + Browser[Browser application] --> Workbench[VS Code workbench] + Workbench --> Repository[Repository extension] + Workbench --> AI[AI extension] + Repository --> APIs[GitHub / GitLab / npm data services] + Repository --> Search[Sourcegraph / searchcode] + Repository --> Proxy[Pages Function: code search] + Proxy --> GitHub[GitHub REST API] + Browser --> OAuth[Pages Functions: OAuth callbacks] + OAuth --> Identity[GitHub / GitLab OAuth] + Repository --> Snapshot[Discovery snapshot endpoint] + AI --> Context[Workspace files and search] + Context --> Repository + AI --> Model[Configured model endpoint] + AI --> MCP[Configured MCP servers] +``` + +## Repository adapters and search + +Adapters separate platform behavior from VS Code providers. Each adapter supplies URL parsing, data access, and the views supported by that platform. Start with the [adapter types](../extensions/github1s/src/adapters/types.ts) and [adapter registration](../extensions/github1s/src/adapters/index.ts) when changing a platform integration. + +GitHub data access uses REST and GraphQL. When **Prefer to use Sourcegraph API** is enabled, supported operations try Sourcegraph first. GitHub text search then falls back to searchcode, followed by GitHub REST code search through the same-origin `/api/github/search/code` proxy. Definition, reference, and hover results use Sourcegraph separately. + +These services have different indexing, authentication, and query capabilities. The [usage guide](usage.md#search-and-code-navigation) describes the user-visible limitations. The current GitHub fallback sequence is implemented in [`data-source.ts`](../extensions/github1s/src/adapters/github1s/data-source.ts). + +## Authentication and data flow + +Repository tokens are persisted through VS Code extension global state in the browser. Direct authenticated repository API requests include the relevant token. The GitHub search fallback also sends the authorization header to the same-origin Pages Function, which forwards it to GitHub. + +OAuth uses a popup and a server-side callback. The callback exchanges the authorization code for a token, then returns the result to the browser. OAuth application secrets belong to the callback runtime. See [deployment configuration](deployment.md#configure-oauth) and [user authentication](usage.md#authentication-and-private-repositories). + +The AI extension has a separate model configuration and conversation store. It sends conversation context and tool results to the selected model endpoint and can connect to user-configured MCP servers. See [AI data handling](ai.md#data-and-storage) for the boundaries users need to understand. + +## Repository discovery + +The Discovery Worker runs GitHub Search queries on a schedule, combines their results into a snapshot, and stores it in Workers KV. The browser's Discovery adapter reads the public snapshot endpoint and renders repository collections as a virtual workspace. + +This service is separate from repository file access. Its configuration, collection rules, and refresh behavior are documented in the [Discovery Worker README](../workers/discovery/README.md). + +## Builds and source overlays + +The normal application build uses the published `@github1s/vscode-web` package, compiles the local extensions, and bundles the web entry with webpack. Output goes to `dist/`, with assets grouped under a directory derived from the Git commit. + +The `vscode-web/` build clones the revision recorded in [`.VERSION`](../vscode-web/.VERSION), applies source overlays, and packages the result. Keeping that build separate lets most changes use the prebuilt editor. Changes to VS Code itself use the [full VS Code development workflow](development.md#develop-with-a-local-vs-code-build). diff --git a/docs/community.md b/docs/community.md new file mode 100644 index 000000000..e719ec029 --- /dev/null +++ b/docs/community.md @@ -0,0 +1,51 @@ +# Community + +[Documentation](guide.md) ยท [GitHub1s](../README.md) + +## Contributing and feedback + +Report problems or propose improvements in the [issue tracker](https://github.com/conwnet/github1s/issues). +For a bug report, include the repository URL, steps to reproduce it, browser version, and the error message. +Remove tokens and other credentials from logs and screenshots before sharing them. + +To work on the project, start with the [development guide](development.md). + +## Third-party projects + +These independently maintained browser extensions and scripts offer shortcuts to GitHub1s. +See each project's documentation for installation and support. + +### Chrome extensions + +- [Repositree](https://chrome.google.com/webstore/detail/repositree/lafjldoccjnjlcmdhmniholdpjkbgajo) ([chouglesaud/repositree](https://github.com/chouglesaud/repositree)) +- [github-code-viewer](https://chrome.google.com/webstore/detail/github-code-viewer/ecddapgifccgblebfibdgkagfbdagjfn) ([febaoshan/edge-extensions-github-code-viewer](https://github.com/febaoshan/edge-extensions-github-code-viewer)) +- Github1s Extension ([Darkempire78/GitHub1s-Extension](https://github.com/Darkempire78/GitHub1s-Extension)) +- [Github Web IDE](https://chrome.google.com/webstore/detail/adjiklnjodbiaioggfpbpkhbfcnhgkfe) ([zvizvi/Github-Web-IDE](https://github.com/zvizvi/Github-Web-IDE)) +- [shortcut to github1s](https://chrome.google.com/webstore/detail/shortcut-to-github1s/gfcdbodapcbfckbfpmgeldfkkgjknceo) ([katsuhisa91/github1s-shortcut](https://github.com/katsuhisa91/github1s-shortcut)) +- [Github1s Shortcut - Open source](https://github.com/Fauzdar1/Github1s) +- [โšก๏ธ 1s to GitHub1s!](https://github.com/holazz/webext-github1s) +- [github1s Google Chrome Extensions](https://github.com/Lonely-Mr-zhang/github_1s_vscode) + +### Firefox extensions + +- [Repositree](https://addons.mozilla.org/en-US/firefox/addon/repositree/) ([chouglesaud/repositree](https://github.com/chouglesaud/repositree)) +- [Github1s Extension](https://addons.mozilla.org/firefox/addon/github1s-extension) ([Darkempire78/GitHub1s-Extension](https://github.com/Darkempire78/GitHub1s-Extension)) +- [Github1s](https://addons.mozilla.org/firefox/addon/github1s/) ([mcherifi/github1s-firefox-addon](https://github.com/mcherifi/github1s-firefox-addon)) +- [Github Web IDE](https://addons.mozilla.org/firefox/addon/github-web-ide/) ([zvizvi/Github-Web-IDE](https://github.com/zvizvi/Github-Web-IDE)) + +### Microsoft Edge extensions + +- [github-code-viewer](https://microsoftedge.microsoft.com/addons/detail/githubcodeviewer/jaaaapanahkknbgdbglnlchbjfhhjlpi) ([febaoshan/edge-extensions-github-code-viewer](https://github.com/febaoshan/edge-extensions-github-code-viewer)) +- [Github Web IDE](https://microsoftedge.microsoft.com/addons/detail/akjbkjciknacicbnkfjbnlaeednpadcf) ([zvizvi/Github-Web-IDE](https://github.com/zvizvi/Github-Web-IDE)) + +### Safari extension + +- [GitHub1s-For-Safari-Extension](https://apps.apple.com/us/app/readcodeonline/id1569026520?mt=12) ([code4you2021/GitHub1s-For-Safari-Extension](https://github.com/code4you2021/GitHub1s-For-Safari-Extension)) + +### Tampermonkey scripts + +- [Mr-B0b/TamperMonkeyScripts/vscode.js](https://github.com/Mr-B0b/TamperMonkeyScripts/blob/main/vscode.js) + +## Star history + +[![Stargazers over time](https://api.star-history.com/svg?repos=conwnet/github1s&type=Date)](https://star-history.com/#conwnet/github1s&Date) diff --git a/docs/deployment.md b/docs/deployment.md new file mode 100644 index 000000000..0f74e4b4f --- /dev/null +++ b/docs/deployment.md @@ -0,0 +1,121 @@ +# Deployment + +[Documentation](guide.md) ยท [Development](development.md) ยท [Architecture](architecture.md) + +A GitHub1s deployment consists of static application assets and, for OAuth and the GitHub REST search fallback, server-side Functions. Cloudflare Pages can host both. Repository discovery uses a separate Worker. + +## Deployment layout + +| Part | Location | Purpose | +| ------------------ | ----------------------- | --------------------------------------------------------------- | +| Application assets | Build output in `dist/` | VS Code, extensions, and the web entry | +| Pages Functions | Source in `functions/` | OAuth callbacks and GitHub code-search proxy | +| Discovery Worker | `workers/discovery/` | Scheduled repository collections and their public JSON endpoint | + +Serve the application at the root of an origin, such as `https://code.example.com`. Asset paths are absolute; deployment under a subdirectory requires code changes. + +Custom hostnames select the GitHub platform by default. GitLab and npm selection currently depends on the hostname rules in [`src/index.ts`](../src/index.ts); adapt those rules when hosting either platform on your own domain. + +## Configure OAuth + +OAuth configuration is needed for the **Connect to GitHub** and **Connect to GitLab** buttons. Users can also supply repository tokens manually. + +Create the corresponding OAuth application at the repository provider and register the callback on the same origin as GitHub1s: + +| Provider | Callback URL | +| -------- | --------------------------------------------------- | +| GitHub | `https://code.example.com/api/github-auth-callback` | +| GitLab | `https://code.example.com/api/gitlab-auth-callback` | + +Replace the origin with your deployment's origin. Set the following variables for each provider you enable: + +| Variable | Stage | Value | +| -------------------------- | --------------------------- | ---------------------------------------- | +| `GITHUB_OAUTH_ID` | Build and Functions runtime | GitHub OAuth application's client ID | +| `GITHUB_OAUTH_SECRET` | Functions runtime | GitHub OAuth application's client secret | +| `GITHUB1S_ALLOWED_ORIGINS` | Functions runtime | Comma-separated allowed origins | +| `GITLAB_OAUTH_ID` | Build and Functions runtime | GitLab application's client ID | +| `GITLAB_OAUTH_SECRET` | Functions runtime | GitLab application's client secret | +| `GITLAB1S_ALLOWED_ORIGINS` | Functions runtime | Comma-separated allowed origins | + +Use the same client ID at build time and runtime. Allowed origins include the scheme and any port, with no path or trailing slash, for example `https://code.example.com,http://localhost:8788`. The callback checks its own request origin against this list and returns authorization to the browser on that origin. + +Set client IDs in the environment before building; webpack does not load them from `.dev.vars` or `.env` automatically. Configure runtime values in the Pages project's variables and secrets for the target environment. Keep OAuth application secrets in the Functions runtime. See [Cloudflare's Functions bindings guide](https://developers.cloudflare.com/pages/functions/bindings/#secrets) for runtime secrets. + +The repository also reads `GITHUB_DOMAIN`, `GITHUB_API_PREFIX`, `GITLAB_DOMAIN`, and `GITLAB_API_PREFIX` during builds. These customize some upstream URLs, but OAuth endpoints and the GitHub search proxy still target github.com and gitlab.com. Supporting an enterprise or self-managed provider requires reviewing those paths as well as platform selection. + +## Build and deploy to Pages + +Use the [development prerequisites](development.md#prerequisites). From the repository root, install dependencies and build with the client IDs for the providers you enabled: + +```bash +npm install +export GITHUB_OAUTH_ID='your-github-client-id' +npm run build +``` + +Omit the export for a deployment without GitHub OAuth; set `GITLAB_OAUTH_ID` as well when enabling GitLab OAuth. + +For a CLI deployment, authenticate with Cloudflare and create a Pages project if needed: + +```bash +npx wrangler login +npx wrangler pages project create +``` + +Configure the project's runtime variables and secrets, then deploy: + +```bash +npx wrangler pages deploy dist --project-name your-pages-project +``` + +Run this command from the repository root so Wrangler also compiles and uploads `functions/`. Uploading only `dist/` through the dashboard does not include these Functions. See [Pages Direct Upload](https://developers.cloudflare.com/pages/get-started/direct-upload/#functions). + +With Pages Git integration, use the repository root as the build root, `npm run build` as the build command, and `dist` as the output directory. Set the Node version to the CI baseline documented in the development guide. + +## Preview Pages Functions locally + +Wrangler can run the built assets and Functions together. Prepare OAuth configuration before building or starting it if you want to test authentication. + +For OAuth, provide the runtime variables in a root `.dev.vars` file. Before creating it, add `.dev.vars*` to your local `.git/info/exclude`; the repository's `.gitignore` does not currently cover it. An example for GitHub is: + +```dotenv +GITHUB_OAUTH_ID=your-github-client-id +GITHUB_OAUTH_SECRET=your-github-client-secret +GITHUB1S_ALLOWED_ORIGINS=http://localhost:8788 +``` + +Register `http://localhost:8788/api/github-auth-callback` with the OAuth application used for local testing. Then, from the repository root, export that application's client ID, rebuild, and start the preview: + +```bash +export GITHUB_OAUTH_ID='your-github-client-id' +npm run build +npx wrangler pages dev dist +``` + +Omit the OAuth configuration and export for a preview without GitHub OAuth. Open `http://localhost:8788/conwnet/github1s`. This differs from `npm run watch`, whose webpack server runs on port `8080` and only proxies GitHub code search. See [Pages local development](https://developers.cloudflare.com/pages/functions/local-development/) and [local secrets](https://developers.cloudflare.com/pages/functions/bindings/#local-development-with-secrets). + +## Other static hosts + +To serve the application assets on another host: + +- Publish `dist/` at the origin root. +- Serve `index.html` for application routes such as `/owner/repo/blob/ref/path`, while serving real assets directly. +- Apply the response headers from [`public/_headers`](../public/_headers): `Cross-Origin-Opener-Policy: same-origin` and `Cross-Origin-Embedder-Policy: credentialless`. +- Provide equivalent server routes for OAuth callbacks and `/api/github/search/code` if those features are required. + +Pages supplies an [SPA fallback](https://developers.cloudflare.com/pages/configuration/serving-pages/#single-page-application-spa-rendering) when no top-level `404.html` exists. Its [`_headers` rules](https://developers.cloudflare.com/pages/configuration/headers/) apply to static assets; Functions manage their own responses. + +## Discovery service + +The application reads Discovery from a URL defined in [`extensions/github1s/src/adapters/discovery/data-source.ts`](../extensions/github1s/src/adapters/discovery/data-source.ts). To use your own service, deploy the [Discovery Worker](../workers/discovery/README.md), update that URL, and rebuild the application. + +## Verify the deployment + +1. Open a public repository and read a file. +2. Reload a deep file URL to verify route fallback and asset paths. +3. If OAuth is enabled, connect an account and validate its token in Settings. +4. Check the `/api/github/search/code` route. Successful search through another service alone does not verify the GitHub fallback. +5. Open the home page and confirm Discovery loads from the intended endpoint. + +AI model and MCP requests originate in the browser. Their connectivity depends on the endpoints configured by each user; see the [AI guide](ai.md). diff --git a/docs/development.md b/docs/development.md new file mode 100644 index 000000000..b66663f99 --- /dev/null +++ b/docs/development.md @@ -0,0 +1,119 @@ +# Development + +[Documentation](guide.md) ยท [Architecture](architecture.md) ยท [Deployment](deployment.md) + +Most changes to GitHub1s use the published VS Code web package. Build VS Code locally when changing the editor source overlays under `vscode-web/`. + +## Prerequisites + +- Git and npm. +- Node.js 24, matching the repository's CI configuration. +- A browser for testing the application. + +The commands below assume a Unix-compatible shell. Run them from the repository root unless a different working directory is shown. + +## Run locally + +```bash +git clone https://github.com/conwnet/github1s.git +cd github1s +npm install +npm run watch +``` + +The install step also installs dependencies for the local extensions. Watch mode starts webpack's development server and the repository and AI extension watchers. + +Wait for the application and both extensions to finish compiling, then open [localhost:8080/conwnet/github1s](http://localhost:8080/conwnet/github1s). The development server uses port `8080` and writes generated assets to `dist/`. + +GitHub code search is proxied by the development server. OAuth callback Functions are not run by `npm run watch`; use a manually supplied token for repository authentication or follow the [Pages development instructions](deployment.md#preview-pages-functions-locally). + +## Build the application + +```bash +npm run build +``` + +This compiles the local extensions and produces the application in `dist/`. See the [deployment guide](deployment.md) for hosting the assets and enabling the accompanying Functions. + +## Check changes + +Choose checks for the part of the project you changed: + +| Command | Coverage | +| --------------------------------------------------- | ----------------------------------------------- | +| `npm run eslint:check` | Repository lint checks, without automatic fixes | +| `npm run typecheck` | Root application and Pages Functions | +| `npm --prefix extensions/github1s run test` | Repository extension tests | +| `npm --prefix extensions/github1s-ai run typecheck` | AI extension and webview types | +| `npm --prefix extensions/github1s-ai run test` | AI extension tests | +| `npm run build` | Production compilation and packaging | + +For browser integration tests, build the application first, stop any server already using port `8080`, then run: + +```bash +npm run build +npm run test:ci +``` + +The test command starts the development server, installs the test dependencies and Playwright browsers, and runs the Jest browser suite. The existing tests launch Chromium, exercise repository loading and navigation, and depend on external repository services. + +`npm run format` formats the whole repository, and `npm run eslint` applies lint fixes. To format only a documentation change, pass the changed files to Prettier: + +```bash +npx prettier --write README.md docs/usage.md +``` + +## Develop with a local VS Code build + +This workflow requires the native build tools used by the pinned VS Code revision. Follow the [VS Code package guide](../vscode-web/README.md) for upstream prerequisites and overlay maintenance. + +Install and build the companion package: + +```bash +npm install +cd vscode-web +npm install +npm run build +cd .. +npm run link +``` + +The package build clones VS Code and its localization repository, applies the overlays, compiles the editor, and writes `vscode-web/dist/`. The link command makes the root application use that package. + +Run the VS Code watchers in one terminal: + +```bash +cd vscode-web +npm run watch +``` + +Run the application and extension watchers from the repository root in another terminal: + +```bash +npm run watch-with-vscode +``` + +Wait for both terminals to finish their initial compilation, then open the same local application URL. In this mode, the development server serves editor assets from `vscode-web/lib/vscode/`. + +To test a production build using the locally built package, run `npm run build` from the repository root after building and linking `vscode-web`. + +## Where to make changes + +| Change | Location | +| ---------------------------------------------------------- | ------------------------------- | +| Application startup, workspace selection, or browser OAuth | `src/` | +| Repository access, routing, history, or search | `extensions/github1s/src/` | +| AI chat, model connections, context, or tools | `extensions/github1s-ai/src/` | +| VS Code behavior modified by GitHub1s | `vscode-web/src/` | +| OAuth callback or GitHub search proxy | `functions/` | +| Repository discovery collections or snapshots | `workers/discovery/` | +| Build and packaging behavior | `scripts/`, `webpack.config.js` | + +See the [architecture guide](architecture.md) for how these components fit together. + +## Troubleshooting + +- **Missing files during startup:** check that both extension watchers and webpack have completed compilation, then reload the browser. +- **OAuth fails locally:** the webpack server does not host the OAuth callbacks. Use a token or the Pages preview workflow. +- **Changes to VS Code do not appear:** use the two-terminal workflow above and edit the overlays under `vscode-web/src/`. +- **A root type check passes but AI code fails:** the AI extension has its own type checks; run its `typecheck` script. diff --git a/docs/guide.md b/docs/guide.md index 4c30e8934..d8c06cf84 100644 --- a/docs/guide.md +++ b/docs/guide.md @@ -1,86 +1,18 @@ -# How it works +# Documentation -GitHub1s is based on [VS Code 1.66.2](https://github.com/microsoft/vscode/tree/1.66.2) now. VS Code can be built for a browser version officially. I also used the code and got inspired by [Code Server](https://github.com/cdr/code-server). +[GitHub1s](../README.md) -Thanks to the very powerful and flexible extensibility of VS Code, we can easily implement a VS Code extension that provides the custom File IO ability using [FileSystemProvider API](https://code.visualstudio.com/api/references/vscode-api#FileSystemProvider). There is an official demo named [vscode-web-playground](https://github.com/microsoft/vscode-web-playground) which shows how it is used. +The original guide has been reorganized into focused documents: -On the other hand, GitHub provides the powerful [REST API](https://docs.github.com/en/rest) that can be used for a variety of tasks which includes reading directories and files for sure. +- [Using GitHub1s](usage.md): repository navigation, authentication, search, and troubleshooting. +- [GitHub1s AI](ai.md): configure a model, add context, connect tools, and manage stored data. +- [Development](development.md): run the application, build it, and check changes. +- [Architecture](architecture.md): understand the components and their data flow. +- [Deployment](deployment.md): host the application and configure its services. +- [Community](community.md): find third-party extensions and view star history. -According to the above, obviously, the core concept of GitHub1s is to implement a VS Code Extension (includes FileSystemProvider) using GitHub REST API. +## Component documentation -_We may switch to the GitHub GraphQL API for more friendly user experience in the future, thanks to @xcv58 and @kanhegaonkarsaurabh. See details at [Issue 12](https://github.com/conwnet/github1s/issues/12)._ - -~~GitHub1s is a purely static web app (because it really doesn't need a backend service, does it?). So we just deploy it on [GitHub Pages](https://pages.github.com/) now (the `gh-pages` branch of this repository), and it is free. The service of GitHub1s could be reliable (GitHub is very reliable) because nobody needs to pay the web hosting bills.~~ - -We deploy GitHub1s on [Cloudflare Pages](https://cloudflare.com/) now for minimize delays in loading and better developer experience. Thanks for the wonderful service provide by Cloudflare. - -# Rate Limit - -Another thing that needs attention is [Rate Limit](https://docs.github.com/en/rest/reference/rate-limit): - -> For unauthenticated requests, the rate limit allows for up to 60 requests per hour. Unauthenticated requests are associated with the originating IP address, and not the user making requests. - -> For API requests using Basic Authentication or OAuth, you can make up to 5,000 requests per hour. - -So, if you meet some problems when you use GitHub1s, even if you are using newer browsers, you could try to set a [GitHub OAuth Token](https://docs.github.com/en/rest/overview/resources-in-the-rest-api#oauth2-token-sent-in-a-header). Don't worry, we cannot see your token. It is only stored in your browser [IndexedDB](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API) with [VS Code Extension globalState API](https://code.visualstudio.com/api/references/vscode-api#ExtensionContext) (Actually we don't have a server, do we?). - -But this does not mean the token is absolutely safe, **don't forget to clean it while you are using a device that doesn't belong to you**. - -# Sourcegraph API - -Due to the potential RateLimit of the GitHub API, we will prioritize the use of the [Sourcegraph API](https://sourcegraph.com/docs) for public repositories, with the exception of the Read interface, the code search capability is also provided by the Sourcegraph API. - -By default, GitHub1s will only try to use the GitHub API when the Sourcegraph API request fails, and you can adjust this option in the settings. - -# Development - -As you see, running GitHub1s locally is not difficult. After cloning the repository, just run these commands: - -```shell -$ npm install -$ npm run watch -``` - -Then, there will be a new directory named `dist` generated in the project root. The `npm run watch:dev-server` (part of `npm run watch` command) will automatically open http://localhost:8080 in the browser. - -If you get a 404 error for some static files, please wait a minute for the building to complete. - -## Watch Mode - -What happens after you run `npm run watch-with-vscode`? - -1. Copy some necessary resources (`index.html`, `favicons.ico`, etc.) to the `dist` directory. - -2. This command will compile the codes in `src` and generate application entry script (see `webpack.config.js`). This command also compile the custom extensions (for example `github1s`) in `extensions` directory. - -3. Redirect vscode-web static requests (vscode, extensisions, dependencies) to `vscode-web/lib/vscode` which should be generated by vscode compile process. - -You should also compile the vscode manually in another terminal. - -1. Go to `vscode-web` and run `npm install && npm run watch` (the native watch of vscode), it will trigger a new build if something in it has been changed. - -2. This command will alose watch the `vscode-web/src` and `vscode-web/extensions` directory, merge it in to `vscode-web/lib/vscode` if something in it has been changed. (When a new file is merged into `lib/vscode`, it will trigger the watcher that is described in Step 3) - -Note that since we have modified the source code of VS Code, it may get into trouble when merging a newer version VS Code. - -It is a little laborious to complete the watch process, but I didn't think of a better solution. - -What happens after you run `npm run watch`? - -It's the same procedure as `` without the step 3. Instead of the local VS Code, it uses the prebuilt [@github1s/vscode-web](https://www.npmjs.com/package/@github1s/vscode-web) version. - -## Build mode - -Put simply, we build the necessary code and do a minify. The minify script is modified from [Code Server](https://github.com/cdr/code-server). - -## Directory Structure - -- `extensions` - custom VS Code extensions that don't come with VS Code natively. - -- `src` - the code in here will be patched into VS Code source. - -- `vscode-web` - This contains the code to patch VS Code. - -- `scripts` - some scripts for build, watch, package, etc. - -- `resources` - some resource files such as templates, pictures, configuration files, etc. +- [GitHub1s AI extension](../extensions/github1s-ai/README.md) +- [VS Code web package](../vscode-web/README.md) +- [Discovery Worker](../workers/discovery/README.md) diff --git a/docs/usage.md b/docs/usage.md new file mode 100644 index 000000000..b487229c6 --- /dev/null +++ b/docs/usage.md @@ -0,0 +1,116 @@ +# Using GitHub1s + +[Documentation](guide.md) ยท [AI guide](ai.md) + +GitHub1s opens remote repositories in a VS Code interface in your browser. Public repositories can be browsed without signing in, subject to the upstream services' access and rate limits. + +## Open a repository or package + +For GitHub, add `1s` after `github` in the address bar. For GitLab or npm, add `1s` after `gitlab` or `npmjs`. + +| Source | Example | +| ----------------- | ---------------------------------------- | +| GitHub repository | `https://github1s.com/microsoft/vscode` | +| GitLab repository | `https://gitlab1s.com/gitlab-org/gitlab` | +| npm package | `https://npmjs1s.com/package/lodash` | + +Opening [GitHub1s without a repository path](https://github1s.com) displays repository collections from GitHub Discovery. Within a repository, use **GitHub1s: Open Repository...** in the Command Palette and enter a repository name such as `owner/repo` for the current platform. Use the browser address bar for a complete URL. + +### Links to files and changes + +GitHub1s recognizes common repository URLs. Replace the placeholders below with a repository, branch, tag, commit, or request number: + +| View | URL pattern | +| ------------------------------ | ------------------------------------------------------------ | +| GitHub branch or directory | `https://github1s.com/owner/repo/tree/ref/path` | +| GitHub file and selected lines | `https://github1s.com/owner/repo/blob/ref/path#L10-L20` | +| GitHub commit | `https://github1s.com/owner/repo/commit/sha` | +| GitHub pull request | `https://github1s.com/owner/repo/pull/number` | +| GitLab file | `https://gitlab1s.com/group/project/-/blob/ref/path` | +| GitLab merge request | `https://gitlab1s.com/group/project/-/merge_requests/number` | + +For branches or tags, you can also run **GitHub1s: Checkout to...**. Its **Checkout detached** option accepts a ref directly. This changes the revision being browsed. + +## Navigate code and history + +- Use **Explorer** to browse files and directories, or **Go to File** to find a file by name. +- Use **Search** for text across the repository and the editor's **Find** action for the open file. +- Open **Source Control** to inspect **Commits**, **File History**, and **Code Reviews** where the platform supports them. +- Select a commit or pull/merge request to inspect its changed files and diffs. +- Run **GitHub1s: Toggle File Blame** to display revision information beside file lines where available. + +Open the Command Palette with `F1`, `Ctrl+Shift+P`, or `Cmd+Shift+P` on macOS. Browser and operating-system shortcuts can take precedence. + +For questions about the code, click **Toggle Secondary Side Bar** in the layout controls at the top of GitHub1s to open the AI panel, then follow the [AI setup guide](ai.md#configure-a-model). + +## Authentication and private repositories + +Use authentication to access private repositories or make authenticated API requests. The account or token must have access to the repository you want to open. + +1. Open **Settings** in the left activity bar. +2. Choose **Connect to GitHub** or **Connect to GitLab**, then complete the authorization flow in the popup. +3. Alternatively, enter a token in **Manual Input AccessToken** and select **Submit**. **Create New AccessToken** opens the corresponding provider's token creation page. +4. After connecting, use **Validate** to check the token and reopen the repository if necessary. + +### Token storage and requests + +GitHub and GitLab tokens are stored separately in the browser's VS Code extension state. Authenticated repository requests send the relevant token to the repository provider. Two additional paths matter: + +- OAuth callbacks exchange authorization codes for tokens on the site's server-side Functions. +- GitHub's REST code-search fallback sends the authorization header through the site's same-origin search proxy, which forwards it to GitHub. +- The above features are all Cloudflare Functions now, which you can review in the [functions](../functions/) directory + +To remove a saved token, choose **Clear**, then **Confirm**, in Settings. This removes the browser's saved token. Revoke the token or application authorization in GitHub if you also want to withdraw its access at the provider. + +## Search and code navigation + +Repository-wide search relies on external services. For GitHub, **Prefer to use Sourcegraph API** in Settings enables an initial [Sourcegraph](https://sourcegraph.com/) attempt. Search then falls back to [searchcode](https://searchcode.com/) and, if needed, the [GitHub REST API](https://docs.github.com/en/rest/search/search#search-code) through the site's proxy. + +Results depend on the service's repository coverage, indexed revision, permissions, and rate limits. In particular: + +- The GitHub REST fallback uses default-branch search results; they can differ from the ref currently open in the editor. +- That fallback does not support regular-expression or multiline searches, and result positions derived from snippets can be approximate. +- GitHub definition, reference, and hover results depend on Sourcegraph availability and coverage. +- Successful file browsing does not guarantee that repository-wide search or symbol navigation is available, especially for private repositories. + +Authentication can help with API access and rate limits, but each provider and endpoint applies its own limits. Follow the error's retry guidance rather than assuming a single request quota covers every feature. + +## Capabilities and limits + +| Area | Scope | +| ------------------------- | ------------------------------------------------------------------------------------------ | +| GitHub and GitLab | Read repository files and inspect supported history and code-review views | +| AI | Requires a configured model and API key; see [AI setup](ai.md) | +| npm | Browse published package files and versions | +| Remote repository changes | Read-only; use the repository host or a development environment to edit and submit changes | +| Extensions | Browser-compatible extensions; availability differs from desktop VS Code | + +## Troubleshooting + +| Symptom | What to check | +| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | +| A private repository does not open | Validate the token, check repository access, and confirm the URL works on the provider's site | +| Requests are rate limited | Authenticate if appropriate, inspect the reported limit, and wait for the retry time | +| Search is empty or fails while files load | Try a simple text query; check the selected ref and the service limitations above | +| OAuth does not complete | Allow the authentication popup; on a self-hosted instance, check [OAuth configuration](deployment.md#configure-oauth) | +| AI cannot connect | Check the endpoint, model ID, API key, and browser access requirements in the [AI guide](ai.md#troubleshooting) | + +For an unresolved problem, [open an issue](https://github.com/conwnet/github1s/issues) with the repository URL, browser version, and steps to reproduce it. Remove credentials from any logs or screenshots you include. + +## Browser shortcuts + +The [community directory](community.md#third-party-projects) lists browser extensions and scripts. You can also save this JavaScript as a bookmark's URL to switch between GitHub and GitHub1s while preserving the repository path: + +```javascript +javascript: (() => { + const url = new URL(window.location.href); + if (url.hostname === 'github.com') { + url.hostname = 'github1s.com'; + } else if (url.hostname === 'github1s.com') { + url.hostname = 'github.com'; + } else { + return; + } + window.location.href = url.href; +})(); +``` diff --git a/extensions/github1s-ai/README.md b/extensions/github1s-ai/README.md index 6e9ab75a7..9dbb95171 100644 --- a/extensions/github1s-ai/README.md +++ b/extensions/github1s-ai/README.md @@ -1,3 +1,13 @@ # GitHub1s AI -GitHub1s AI is a lightweight, built-in chat view for asking LLM about a repository. +GitHub1s AI is the built-in assistant for exploring code in GitHub1s. It combines chat, file and selection attachments, repository tools, and optional MCP connections with a user-configured model endpoint. + +## Use the assistant + +Open **GitHub1s AI: Open AI Settings** from the Command Palette to add a model, then run **GitHub1s AI: Open Chat**. + +See the [AI guide](https://github.com/conwnet/github1s/blob/master/docs/ai.md) for model configuration, context, tools, and data handling. + +## Development + +The extension requires GitHub1s's browser workbench and repository providers. See the [development guide](https://github.com/conwnet/github1s/blob/master/docs/development.md) for running the complete application. diff --git a/resources/images/demo.png b/resources/images/demo.png index 0f148ad6a..d88d994ea 100644 Binary files a/resources/images/demo.png and b/resources/images/demo.png differ diff --git a/resources/images/gitpod-statusbar.png b/resources/images/gitpod-statusbar.png deleted file mode 100644 index 6b90bc61b..000000000 Binary files a/resources/images/gitpod-statusbar.png and /dev/null differ diff --git a/resources/images/logo.png b/resources/images/logo.png deleted file mode 100644 index 56af2635e..000000000 Binary files a/resources/images/logo.png and /dev/null differ diff --git a/resources/images/ossinsight-brand-dark.png b/resources/images/ossinsight-brand-dark.png deleted file mode 100644 index 820291a21..000000000 Binary files a/resources/images/ossinsight-brand-dark.png and /dev/null differ diff --git a/resources/images/sourcegraph-logo.svg b/resources/images/sourcegraph-logo.svg deleted file mode 100644 index 6bc102b3a..000000000 --- a/resources/images/sourcegraph-logo.svg +++ /dev/null @@ -1,79 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/resources/images/vercel-logo.svg b/resources/images/vercel-logo.svg deleted file mode 100644 index 6ed36d3b7..000000000 --- a/resources/images/vercel-logo.svg +++ /dev/null @@ -1,6 +0,0 @@ - - - - - - diff --git a/workers/discovery/README.md b/workers/discovery/README.md index a108bc4e0..cd74271de 100644 --- a/workers/discovery/README.md +++ b/workers/discovery/README.md @@ -1,3 +1,15 @@ # Repository Discovery Snapshots This Worker collects public repositories from GitHub Search on a schedule, stores complete JSON snapshots in Workers KV, and exposes a public endpoint for reading the latest snapshot. + +## Preview collection locally + +From the repository root, provide `GITHUB_TOKEN` in the process environment and run: + +```bash +npm run discovery +``` + +The command writes `out/discovery/github/latest.json` using the same collection logic as the Worker. It does not publish to KV. It accepts no command-line arguments; edit [`src/collections.ts`](src/collections.ts) to change queries. + +The collections cover new projects, recently updated projects with fewer stars, highly starred projects, and selected topics. Queries and per-collection limits are defined in that file; the collection names describe those filters rather than a measure of recent star growth.