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 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
- # Temporary Holding Version
1
+ # Ansensational CLI
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ [![npm version](https://img.shields.io/npm/v/ansensational.svg)](https://www.npmjs.com/package/ansensational)
4
+ [![npm downloads](https://img.shields.io/npm/dm/ansensational.svg)](https://www.npmjs.com/package/ansensational)
5
+ [![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
6
+ [![Node.js](https://img.shields.io/node/v/ansensational.svg)](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
@@ -0,0 +1 @@
1
+ #!/usr/bin/env node