Skip to content

Commit 8ec6650

Browse files
chrisbbreuerchrisbbreuer
committed
chore: wip
chore: wip chore: wip chore: wip chore: wip chore: wip chore: wip chore: wip chore: wip chore: wip
1 parent 2136d67 commit 8ec6650

29 files changed

+2764
-261
lines changed

‎.gitignore

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,3 +10,4 @@ logs
1010
node_modules
1111
temp
1212
docs/.vitepress/cache
13+
/test/.tmp

‎.vscode/dictionary.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ commitlint
1212
commitlintrc
1313
composables
1414
davidanson
15+
defu
1516
degit
1617
deps
1718
destructurable

‎README.md

Lines changed: 44 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -8,46 +8,65 @@
88

99
# gitit
1010

11-
This is an opinionated TypeScript Starter kit to help kick-start development of your next Bun package.
11+
A powerful template and project scaffolding tool to help kick-start development of your next project.
1212

1313
## Features
1414

15-
This Starter Kit comes pre-configured with the following:
15+
Gitit comes with the following features:
1616

17-
- 🛠️ [Powerful Build Process](https://github.com/oven-sh/bun) - via Bun
18-
- 💪🏽 [Fully Typed APIs](https://www.typescriptlang.org/) - via TypeScript
19-
- 📚 [Documentation-ready](https://vitepress.dev/) - via VitePress
20-
- ⌘ [CLI & Binary](https://www.npmjs.com/package/bunx) - via Bun & CAC
21-
- 🧪 [Built With Testing In Mind](https://bun.sh/docs/cli/test) - pre-configured unit-testing powered by [Bun](https://bun.sh/docs/cli/test)
22-
- 🤖 [Renovate](https://renovatebot.com/) - optimized & automated PR dependency updates
23-
- 🎨 [ESLint](https://eslint.org/) - for code linting _(and formatting)_
24-
- 📦️ [pkg.pr.new](https://pkg.pr.new) - Continuous (Preview) Releases for your libraries
25-
- 🐙 [GitHub Actions](https://github.com/features/actions) - runs your CI _(fixes code style issues, tags releases & creates its changelogs, runs the test suite, etc.)_
17+
- 🚀 **Fast Template Cloning** _Clone templates from GitHub, GitLab, Bitbucket, and more_
18+
- 💪 **Fully Typed APIs** _Written in TypeScript for a great developer experience_
19+
- 📦 **Zero Configuration** _Works out of the box with sensible defaults_
20+
- 🔄 **Offline Support** _Use cached templates when offline_
21+
- 🛠️ **Customizable** _Configure templates with various options_
22+
- 🧩 **Post-Installation Commands** _Run custom commands after cloning_
23+
- 🔑 **Private Repository Support** _Authentication for private templates_
24+
- 🖥️ **Interactive Shell** _Open a shell in your newly created project_
2625

2726
## Get Started
2827

29-
It's rather simple to get your package development started:
30-
3128
```bash
32-
# you may use this GitHub template or the following command:
33-
bunx degit stacksjs/gitit my-pkg
34-
cd my-pkg
35-
36-
bun i # install all deps
37-
bun run build # builds the library for production-ready use
29+
# Install globally
30+
bun install -g @stacksjs/gitit
3831

39-
# after you have successfully committed, you may create a "release"
40-
bun run release # automates git commits, versioning, and changelog generations
32+
# or use directly with bunx
33+
bunx @stacksjs/gitit template github:user/repo my-project
4134
```
4235

43-
_Check out the package.json scripts for more commands._
44-
45-
## Testing
36+
## Usage
4637

4738
```bash
48-
bun test
39+
# Basic usage
40+
gitit template github:user/repo my-project
41+
42+
# With options
43+
gitit template github:user/repo my-project --install --shell
44+
45+
# Clone with custom command
46+
gitit template github:user/repo my-project --command "npm run dev"
47+
48+
# Use offline cached template
49+
gitit template github:user/repo my-project --offline
50+
51+
# Clone to a specific directory
52+
gitit template github:user/repo ./path/to/project
4953
```
5054

55+
## Available Options
56+
57+
| Option | Description |
58+
|--------|-------------|
59+
| `--force` | Clone to existing directory even if it exists |
60+
| `--force-clean` | Remove any existing directory or file recursively before cloning |
61+
| `--shell` | Open a new shell with current working directory |
62+
| `--install` | Install dependencies after cloning |
63+
| `--verbose` | Show verbose debugging info |
64+
| `--command` | Custom command to run after template is cloned |
65+
| `--auth` | Custom Authorization token for private repositories |
66+
| `--cwd` | Set current working directory to resolve dirs relative to it |
67+
| `--offline` | Do not attempt to download and use cached version |
68+
| `--prefer-offline` | Use cache if exists otherwise try to download |
69+
5170
## Changelog
5271

5372
Please see our [releases](https://github.com/stackjs/gitit/releases) page for more information on what has changed recently.

‎docs/.vitepress/config.ts

Lines changed: 35 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,4 @@
11
import type { HeadConfig } from 'vitepress'
2-
import { transformerTwoslash } from '@shikijs/vitepress-twoslash'
32
import { withPwa } from '@vite-pwa/vitepress'
43
import { defineConfig } from 'vitepress'
54

@@ -22,7 +21,7 @@ const nav = [
2221
{ text: 'News', link: 'https://stacksjs.org/news' },
2322
{
2423
text: 'Changelog',
25-
link: 'https://github.com/stacksjs/ts-starter/blob/main/CHANGELOG.md',
24+
link: 'https://github.com/stacksjs/gitit/blob/main/CHANGELOG.md',
2625
},
2726
// { text: 'Blog', link: 'https://updates.ow3.org' },
2827
{
@@ -60,15 +59,37 @@ const sidebar = [
6059
{ text: 'Config', link: '/config' },
6160
],
6261
},
62+
{
63+
text: 'Features',
64+
items: [
65+
{ text: 'Template Sources', link: '/features/template-sources' },
66+
{ text: 'Repository Support', link: '/features/repository-support' },
67+
{ text: 'Offline Mode', link: '/features/offline-mode' },
68+
{ text: 'Post-Install Commands', link: '/features/post-install-commands' },
69+
{ text: 'Interactive Shell', link: '/features/interactive-shell' },
70+
],
71+
},
72+
{
73+
text: 'Advanced',
74+
items: [
75+
{ text: 'Custom Templates', link: '/advanced/custom-templates' },
76+
{ text: 'Authentication', link: '/advanced/authentication' },
77+
{ text: 'GitHub Private Repos', link: '/advanced/github-private-repos' },
78+
{ text: 'Bitbucket Private Repos', link: '/advanced/bitbucket-private-repos' },
79+
{ text: 'Plugins', link: '/advanced/plugins' },
80+
{ text: 'Hooks', link: '/advanced/hooks' },
81+
],
82+
},
83+
{ text: 'API Reference', link: '/api-reference' },
6384
{ text: 'Showcase', link: '/Showcase' },
6485
]
65-
const description = 'A TypeScript Starter Kit. For a better Development Experience.'
66-
const title = 'ts-starter | A TypeScript Starter Kit. For a better Development Experience.'
86+
const description = 'A powerful template and project scaffolding tool to help kick-start development of your next project.'
87+
const title = 'gitit | A powerful template and project scaffolding tool'
6788

6889
export default withPwa(
6990
defineConfig({
7091
lang: 'en-US',
71-
title: 'ts-starter',
92+
title: 'gitit',
7293
description,
7394
metaChunk: true,
7495
cleanUrls: true,
@@ -83,17 +104,17 @@ export default withPwa(
83104
['meta', { name: 'author', content: 'Stacks.js, Inc.' }],
84105
['meta', {
85106
name: 'tags',
86-
content: 'ts-starter, stacksjs, reverse proxy, modern, lightweight, zero-config, local development',
107+
content: 'gitit, stacksjs, template, scaffolding, project generator, modern, lightweight, zero-config',
87108
}],
88109

89110
['meta', { property: 'og:type', content: 'website' }],
90111
['meta', { property: 'og:locale', content: 'en' }],
91112
['meta', { property: 'og:title', content: title }],
92113
['meta', { property: 'og:description', content: description }],
93114

94-
['meta', { property: 'og:site_name', content: 'ts-starter' }],
115+
['meta', { property: 'og:site_name', content: 'gitit' }],
95116
['meta', { property: 'og:image', content: './images/og-image.jpg' }],
96-
['meta', { property: 'og:url', content: 'https://reverse-proxy.sh/' }],
117+
['meta', { property: 'og:url', content: 'https://gitit.sh/' }],
97118
// ['script', { 'src': 'https://cdn.usefathom.com/script.js', 'data-site': '', 'data-spa': 'auto', 'defer': '' }],
98119
...analyticsHead,
99120
],
@@ -111,7 +132,7 @@ export default withPwa(
111132
sidebar,
112133

113134
editLink: {
114-
pattern: 'https://github.com/stacksjs/stacks/edit/main/docs/docs/:path',
135+
pattern: 'https://github.com/stacksjs/gitit/edit/main/docs/:path',
115136
text: 'Edit this page on GitHub',
116137
},
117138

@@ -123,7 +144,7 @@ export default withPwa(
123144
socialLinks: [
124145
{ icon: 'twitter', link: 'https://twitter.com/stacksjs' },
125146
{ icon: 'bluesky', link: 'https://bsky.app/profile/chrisbreuer.dev' },
126-
{ icon: 'github', link: 'https://github.com/stacksjs/ts-starter' },
147+
{ icon: 'github', link: 'https://github.com/stacksjs/gitit' },
127148
{ icon: 'discord', link: 'https://discord.gg/stacksjs' },
128149
],
129150

@@ -147,9 +168,10 @@ export default withPwa(
147168
dark: 'github-dark',
148169
},
149170

150-
codeTransformers: [
151-
transformerTwoslash(),
152-
],
171+
// Disabling the transformer due to type errors
172+
// codeTransformers: [
173+
// transformerTwoslash(),
174+
// ],
153175
},
154176

155177
vite: viteConfig,

‎docs/advanced/authentication.md

Lines changed: 150 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,150 @@
1+
# Authentication
2+
3+
Gitit supports authentication for private repositories across different providers. This page covers advanced authentication techniques and best practices.
4+
5+
## Authentication Methods
6+
7+
### Access Tokens
8+
9+
The most common authentication method is using personal access tokens:
10+
11+
```bash
12+
gitit template github:user/private-repo my-project --auth "your-access-token"
13+
```
14+
15+
You can also provide authentication via environment variables:
16+
17+
```bash
18+
export GITIT_AUTH="your-access-token"
19+
gitit template github:user/private-repo my-project
20+
```
21+
22+
The environment variable `GITIT_AUTH` is checked by default if no `--auth` parameter is provided.
23+
24+
## Provider-Specific Authentication
25+
26+
Each provider has its own authentication mechanism, but Gitit handles them all using the Bearer token method:
27+
28+
```
29+
Authorization: Bearer your-access-token
30+
```
31+
32+
### GitHub
33+
34+
For GitHub, you need a [Personal Access Token (PAT)](https://github.com/settings/tokens):
35+
36+
```bash
37+
gitit template github:user/private-repo my-project --auth "ghp_xxxxxxxxxxxxxxx"
38+
```
39+
40+
GitHub API calls use the following headers:
41+
42+
```
43+
Authorization: Bearer your-access-token
44+
Accept: application/vnd.github+json
45+
X-GitHub-Api-Version: 2022-11-28
46+
```
47+
48+
### GitLab
49+
50+
For GitLab, you need a [Personal Access Token](https://gitlab.com/-/profile/personal_access_tokens):
51+
52+
```bash
53+
gitit template gitlab:user/private-repo my-project --auth "glpat-xxxxxxxxxxxxxxx"
54+
```
55+
56+
### Bitbucket
57+
58+
For Bitbucket, you need an [App Password](https://bitbucket.org/account/settings/app-passwords/):
59+
60+
```bash
61+
gitit template bitbucket:user/private-repo my-project --auth "your-app-password"
62+
```
63+
64+
### SourceHut
65+
66+
For SourceHut, use your [OAuth token](https://meta.sr.ht/oauth):
67+
68+
```bash
69+
gitit template sourcehut:user/private-repo my-project --auth "your-oauth-token"
70+
```
71+
72+
## Custom GitHub or GitLab Instances
73+
74+
If you're using a GitHub Enterprise or custom GitLab instance, you can set the API URL using environment variables:
75+
76+
```bash
77+
# For GitHub Enterprise
78+
export GITIT_GITHUB_URL="https://github.your-company.com/api/v3"
79+
gitit template github:user/private-repo my-project
80+
81+
# For GitLab self-hosted
82+
export GITIT_GITLAB_URL="https://gitlab.your-company.com"
83+
gitit template gitlab:user/private-repo my-project
84+
```
85+
86+
## Secure Authentication Practices
87+
88+
### Environment Variables
89+
90+
Using environment variables is more secure than passing tokens directly in commands:
91+
92+
```bash
93+
# Add to your .bashrc, .zshrc, etc.
94+
export GITIT_AUTH="your-access-token"
95+
```
96+
97+
### Configuration File
98+
99+
You can store your authentication token in your `gitit.config.ts` file (but be careful not to commit this file):
100+
101+
```typescript
102+
// gitit.config.ts
103+
export default {
104+
auth: process.env.GITIT_AUTH || 'your-access-token',
105+
// other options...
106+
}
107+
```
108+
109+
### CI/CD Integration
110+
111+
When using Gitit in CI/CD pipelines, set up secrets in your CI environment:
112+
113+
```yaml
114+
# GitHub Actions example
115+
jobs:
116+
build:
117+
runs-on: ubuntu-latest
118+
steps:
119+
- uses: actions/checkout@v3
120+
- name: Clone template
121+
run: gitit template github:user/private-repo my-project
122+
env:
123+
GITIT_AUTH: ${{ secrets.GITHUB_TOKEN }}
124+
```
125+
126+
## How Authentication Works in Gitit
127+
128+
When you provide an authentication token, Gitit:
129+
130+
1. Adds it to the HTTP request headers when downloading the template
131+
2. Uses the Bearer authentication method (`Authorization: Bearer your-token`)
132+
3. Passes the appropriate headers specific to each provider
133+
4. The download is performed using the authenticated request
134+
5. If the token has sufficient permissions, the private repository will be accessible
135+
136+
## Troubleshooting Authentication Issues
137+
138+
### Common Problems
139+
140+
1. **Expired tokens**: Most tokens expire after a certain period
141+
2. **Insufficient permissions**: Ensure your token has the required scopes
142+
3. **Rate limiting**: Too many requests can lead to rate limiting
143+
4. **Organization restrictions**: Some organizations restrict token usage
144+
145+
### Solutions
146+
147+
1. Generate a new token with appropriate scopes
148+
2. Check if the repository exists and you have access to it
149+
3. Ensure your token is formatted correctly
150+
4. Contact your organization administrator for access issues

0 commit comments

Comments
 (0)