ansensational 0.0.0-stage → 1.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +31 -0
- package/README.md +214 -2
- package/dist/index.d.ts +1 -0
- package/dist/index.js +1252 -0
- package/package.json +85 -4
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## 1.1.0
|
|
4
|
+
|
|
5
|
+
### Added
|
|
6
|
+
|
|
7
|
+
- `scaffold` command (also the default command) with non-interactive flags:
|
|
8
|
+
`--git`, `--pm`, `--force`, and `--yes`.
|
|
9
|
+
- `--json` output for `list` and `search`.
|
|
10
|
+
- Support for GitHub/GitLab tree URLs that point at a subdirectory.
|
|
11
|
+
- Automatic recovery when the local registry is corrupt (the bad file is
|
|
12
|
+
backed up and a clear warning is printed).
|
|
13
|
+
- Sync now preserves locally added templates under `@local`.
|
|
14
|
+
- Release workflow, package metadata, and LICENSE file for npm.
|
|
15
|
+
|
|
16
|
+
### Fixed
|
|
17
|
+
|
|
18
|
+
- `ansensational` with no arguments now prints help instead of failing with a
|
|
19
|
+
missing argument error.
|
|
20
|
+
- `--version` now reads the version from `package.json`.
|
|
21
|
+
- Invalid templates can no longer corrupt the local registry.
|
|
22
|
+
- Author filters work with both registry usernames and GitHub handles.
|
|
23
|
+
- Package manager switching now removes the correct lockfile and handles
|
|
24
|
+
`bun.lock` as well as `bun.lockb`.
|
|
25
|
+
- Failed clones clean up temporary directories and do not leave partial
|
|
26
|
+
projects behind.
|
|
27
|
+
- Non-interactive runs no longer hang on prompts.
|
|
28
|
+
- Tree/subdirectory template URLs are supported instead of being passed to
|
|
29
|
+
`git clone` unchanged.
|
|
30
|
+
- Scaffolding into an existing empty directory works; `--force` is required
|
|
31
|
+
for non-empty directories.
|
package/README.md
CHANGED
|
@@ -1,3 +1,215 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Ansensational CLI
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://www.npmjs.com/package/ansensational)
|
|
4
|
+
[](https://www.npmjs.com/package/ansensational)
|
|
5
|
+
[](https://opensource.org/licenses/Apache-2.0)
|
|
6
|
+
[](https://nodejs.org/)
|
|
7
|
+
|
|
8
|
+
**Scaffold new projects from GitHub or GitLab templates with a single command.**
|
|
9
|
+
|
|
10
|
+
Ansensational is a community-driven template registry and CLI. Discover a
|
|
11
|
+
template, clone it into a clean project, choose how git and your package
|
|
12
|
+
manager should be handled, and start building.
|
|
13
|
+
|
|
14
|
+
## Features
|
|
15
|
+
|
|
16
|
+
- **One-command scaffolding** — `ansensational @author/template my-app`
|
|
17
|
+
- **GitHub, GitLab, and custom Git hosts** — including URLs that point at a
|
|
18
|
+
branch or subdirectory.
|
|
19
|
+
- **Clean starts** — keep the original history, create a fresh repository, or
|
|
20
|
+
remove git entirely.
|
|
21
|
+
- **Package manager aware** — detects npm, pnpm, yarn, and bun, and can switch
|
|
22
|
+
the template to your preferred manager.
|
|
23
|
+
- **Community registry** — search and list curated templates, with a local
|
|
24
|
+
cache for offline use.
|
|
25
|
+
- **Private/local templates** — add your own templates under `@local` and keep
|
|
26
|
+
them across registry syncs.
|
|
27
|
+
- **Scriptable** — `--json` output, non-interactive flags, and no prompts in CI.
|
|
28
|
+
|
|
29
|
+
## Installation
|
|
30
|
+
|
|
31
|
+
```bash
|
|
32
|
+
# npm
|
|
33
|
+
npm install -g ansensational
|
|
34
|
+
|
|
35
|
+
# pnpm
|
|
36
|
+
pnpm add -g ansensational
|
|
37
|
+
|
|
38
|
+
# yarn
|
|
39
|
+
yarn global add ansensational
|
|
40
|
+
|
|
41
|
+
# bun
|
|
42
|
+
bun add -g ansensational
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
Requires Node.js 18 or newer. No installation is required to try it:
|
|
46
|
+
|
|
47
|
+
```bash
|
|
48
|
+
npx ansensational list --remote
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
## Quick start
|
|
52
|
+
|
|
53
|
+
```bash
|
|
54
|
+
# Refresh the community registry (optional; commands can fetch remotely)
|
|
55
|
+
ansensational sync
|
|
56
|
+
|
|
57
|
+
# Browse templates
|
|
58
|
+
ansensational list --remote
|
|
59
|
+
|
|
60
|
+
# Scaffold one
|
|
61
|
+
ansensational @andi-nugroho/nest-backend my-app
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
## Commands
|
|
65
|
+
|
|
66
|
+
| Command | Description |
|
|
67
|
+
| --------------------------------------- | ----------------------------------------------- |
|
|
68
|
+
| `ansensational <slug> [dest]` | Scaffold a template (default command) |
|
|
69
|
+
| `ansensational scaffold <slug> [dest]` | Explicit form of the same command |
|
|
70
|
+
| `ansensational list` | List templates in the local cache |
|
|
71
|
+
| `ansensational search <query>` | Search local and remote templates |
|
|
72
|
+
| `ansensational sync` | Download the latest community registry |
|
|
73
|
+
| `ansensational add <slug> <url>` | Add or update a template in your local registry |
|
|
74
|
+
|
|
75
|
+
Templates can be referenced as `@author/slug`, `author/slug`, or a bare `slug`
|
|
76
|
+
when the slug is unique.
|
|
77
|
+
|
|
78
|
+
### Scaffold options
|
|
79
|
+
|
|
80
|
+
| Option | Description |
|
|
81
|
+
| ---------------------- | ------------------------------------------------------------ |
|
|
82
|
+
| `-g, --git <strategy>` | `keep` original history, `fresh` repository, or `remove` git |
|
|
83
|
+
| `-p, --pm <manager>` | `npm`, `pnpm`, `yarn`, or `bun` |
|
|
84
|
+
| `-f, --force` | Allow writing into a non-empty destination |
|
|
85
|
+
| `-y, --yes` | Skip prompts and use defaults |
|
|
86
|
+
|
|
87
|
+
```bash
|
|
88
|
+
# Non-interactive setup for CI or scripts
|
|
89
|
+
ansensational @andi-nugroho/backend my-api --git fresh --pm pnpm --yes
|
|
90
|
+
|
|
91
|
+
# Scaffold into the current (empty) directory
|
|
92
|
+
ansensational @andi-nugroho/webapp .
|
|
93
|
+
|
|
94
|
+
# Add files to an existing directory (explicit opt-in)
|
|
95
|
+
ansensational @andi-nugroho/webapp ./existing --force
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
Without `--git`, the CLI prompts when running in a terminal and uses `fresh`
|
|
99
|
+
when it is not interactive.
|
|
100
|
+
|
|
101
|
+
### List and search
|
|
102
|
+
|
|
103
|
+
```bash
|
|
104
|
+
# Local cache only
|
|
105
|
+
ansensational list
|
|
106
|
+
|
|
107
|
+
# Include the remote registry
|
|
108
|
+
ansensational list --remote
|
|
109
|
+
|
|
110
|
+
# Filter by type, framework, or author
|
|
111
|
+
ansensational list --type backend --framework nestjs
|
|
112
|
+
ansensational list --author andi-nugroho
|
|
113
|
+
ansensational list --author @andi-nugroho
|
|
114
|
+
|
|
115
|
+
# Search names, descriptions, tags, features, and authors
|
|
116
|
+
ansensational search postgres
|
|
117
|
+
ansensational search nextjs --type fullstack
|
|
118
|
+
|
|
119
|
+
# Machine-readable output
|
|
120
|
+
ansensational list --remote --json
|
|
121
|
+
ansensational search hono --json
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
`--author` accepts both the registry username (for example `andi-nugroho`) and
|
|
125
|
+
the author's GitHub handle (for example `andi-nugroho`).
|
|
126
|
+
|
|
127
|
+
### Add a local template
|
|
128
|
+
|
|
129
|
+
```bash
|
|
130
|
+
ansensational add my-private-kit https://github.com/me/private-kit \
|
|
131
|
+
--type fullstack \
|
|
132
|
+
--framework nextjs \
|
|
133
|
+
--description "Internal starter" \
|
|
134
|
+
--tags "typescript,auth,drizzle" \
|
|
135
|
+
--features "rbac,data-tables"
|
|
136
|
+
|
|
137
|
+
# Local templates are stored under @local
|
|
138
|
+
ansensational @local/my-private-kit ./my-app
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
Local templates survive `ansensational sync`. Invalid slugs, URLs, types, and
|
|
142
|
+
frameworks are rejected before anything is written, so a typo cannot corrupt
|
|
143
|
+
your registry.
|
|
144
|
+
|
|
145
|
+
### Sync
|
|
146
|
+
|
|
147
|
+
```bash
|
|
148
|
+
ansensational sync
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
Sync replaces the cached community templates with the latest remote registry
|
|
152
|
+
and preserves templates you added under `@local`. If the local registry file
|
|
153
|
+
is ever corrupt, Ansensational backs it up and starts from a clean registry
|
|
154
|
+
instead of crashing.
|
|
155
|
+
|
|
156
|
+
## Template URL formats
|
|
157
|
+
|
|
158
|
+
```text
|
|
159
|
+
https://github.com/owner/repo
|
|
160
|
+
https://github.com/owner/repo/tree/main
|
|
161
|
+
https://github.com/owner/repo/tree/main/apps/web
|
|
162
|
+
https://gitlab.com/group/subgroup/repo
|
|
163
|
+
https://gitlab.com/group/subgroup/repo/-/tree/main/packages/app
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
`git@github.com:owner/repo.git` and `ssh://git@github.com/owner/repo.git` are
|
|
167
|
+
accepted by `add` and normalised to HTTPS. `file://` URLs are supported for
|
|
168
|
+
local testing and private offline repositories.
|
|
169
|
+
|
|
170
|
+
## Environment variables
|
|
171
|
+
|
|
172
|
+
| Variable | Purpose |
|
|
173
|
+
| --------------------------------- | --------------------------------------------------------------- |
|
|
174
|
+
| `ANSENSATIONAL_HOME` | Override the local data directory (default `~/.ansensational`) |
|
|
175
|
+
| `ANSENSATIONAL_REGISTRY_URL` | Use a custom registry JSON URL |
|
|
176
|
+
| `ANSENSATIONAL_REGISTRY_TIMEOUT` | Registry request timeout in milliseconds (default `15000`) |
|
|
177
|
+
| `ANSENSATIONAL_DEBUG` | Print stack traces for unexpected errors |
|
|
178
|
+
|
|
179
|
+
## Troubleshooting
|
|
180
|
+
|
|
181
|
+
**The registry is empty.** Run `ansensational sync` or use
|
|
182
|
+
`ansensational list --remote`.
|
|
183
|
+
|
|
184
|
+
**A template is not found.** Run `ansensational search <query>` or use the full
|
|
185
|
+
`@author/slug` form. Use `ansensational list --remote -a <author>` to list an
|
|
186
|
+
author's templates.
|
|
187
|
+
|
|
188
|
+
**Cloning fails with an authentication error.** The template repository is
|
|
189
|
+
private or has been moved. Make sure your local git credentials can clone the
|
|
190
|
+
URL directly.
|
|
191
|
+
|
|
192
|
+
**The local registry was invalid.** Ansensational prints the backup path and
|
|
193
|
+
starts with an empty registry. Running `ansensational sync` restores the community
|
|
194
|
+
templates.
|
|
195
|
+
|
|
196
|
+
**Prompts are skipped.** Prompts only run in an interactive terminal. Use
|
|
197
|
+
`--git` and `--pm` to set values explicitly in CI.
|
|
198
|
+
|
|
199
|
+
## Contributing templates
|
|
200
|
+
|
|
201
|
+
The community registry lives in
|
|
202
|
+
[`content/templates`](https://github.com/andi-nugroho/ansensational/tree/main/content/templates).
|
|
203
|
+
Add your template's JSON file and open a pull request. See the
|
|
204
|
+
[template contribution guide](https://github.com/andi-nugroho/ansensational/blob/main/content/templates/CONTRIBUTING.md).
|
|
205
|
+
|
|
206
|
+
## Links
|
|
207
|
+
|
|
208
|
+
- [Website and template directory](https://ansensational.vercel.app)
|
|
209
|
+
- [Source code](https://github.com/andi-nugroho/ansensational)
|
|
210
|
+
- [Issues](https://github.com/andi-nugroho/ansensational/issues)
|
|
211
|
+
- [Changelog](./CHANGELOG.md)
|
|
212
|
+
|
|
213
|
+
## License
|
|
214
|
+
|
|
215
|
+
MIT © ANSensational Contributors
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
#!/usr/bin/env node
|