codepen-demokit 0.0.0-stage → 1.0.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/README.md CHANGED
@@ -1,3 +1,230 @@
1
- # Temporary Holding Version
1
+ # `codepen-demokit`
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
+ A zero-config npm framework for organizing, previewing, statically deploying, and syncing collections of self-contained web demos with **CodePen 2.0**.
4
+
5
+ Powered by [CodePen Commander](https://www.npmjs.com/package/codepen-commander) (`cdpn`) under the hood, `codepen-demokit` lets you keep your demos in their own Git repository while getting an automatically generated demo index, a local dev server with live manifest rebuilding, static `dist/` builds, bulk CodePen syncing, and clean one-command framework upgrades (`npm update codepen-demokit`).
6
+
7
+ ## Features
8
+
9
+ - **Core CodePen 2.0 Sync**: Built-in bulk `sync`, `push`, `pull`, and `delete` (with `--keep-info`) commands scoped to all of `src/`, a topic group/subgroup, or a single demo—backed by CodePen Commander (`codepen-commander` is included as a direct dependency).
10
+ - **Auto-Generated Demo Index**: Recursively scans `src/` subfolders for demos (standalone, grouped, and arbitrarily nested subgroups), reading each demo's `<title>`, optional `<meta name="description">`, and `.cdpn.json` CodePen link.
11
+ - **Updatable Index UI Shell**: Ships a modern, accessible light/dark index page (`shell/`) that updates automatically when you upgrade `codepen-demokit`—and can be customized via `config.json` or overridden selectively in `src/`.
12
+ - **Zero-Config Local Dev Server**: `start` builds `dist/demos.json`, watches `src/` to rebuild it on the fly, serves demos directly from `src/`, and lets you preview a single demo subfolder as root.
13
+ - **Static Deployment Ready**: `build` outputs a self-contained `dist/` folder ready for GitHub Pages, Netlify, Cloudflare Pages, Vercel, or any static host (stripping `.cdpn.json` and dotfiles automatically).
14
+ - **Separate Git Repos**: Your demos live in their own clean Git repo and depend on `codepen-demokit` via `package.json`.
15
+
16
+ ---
17
+
18
+ ## Getting Started (New Demos Repo)
19
+
20
+ Requires **Node.js 20+**.
21
+
22
+ ### 1. Scaffold a new demos repository
23
+
24
+ ```sh
25
+ npx codepen-demokit init
26
+ ```
27
+
28
+ The interactive initializer prompts for:
29
+
30
+ 1. **Project name** (default: `"My CodePen Demos"`)
31
+ 2. **Directory** (defaults to the slugified project name, e.g. `my-codepen-demos`)
32
+ 3. **CodePen username** (optional, stored in `config.json`)
33
+ 4. **Default Pen visibility** (`Private`, `Public`, `Protected`, or `Collaborators`; default: `Private`)
34
+
35
+ After creating the files, if you entered a CodePen username that isn't configured in `~/.cdpn` yet, `init` offers to run `cdpn auth login <username>` right away.
36
+
37
+ Then enter the created folder, initialize Git, and install dependencies:
38
+
39
+ ```sh
40
+ cd my-codepen-demos
41
+ git init
42
+ npm install
43
+ ```
44
+
45
+ This creates a clean consumer repository:
46
+
47
+ ```text
48
+ my-codepen-demos/
49
+ ├── src/ # Put your self-contained demo folders here
50
+ ├── config.json # Site title/subtitle + CodePen profile & default visibility
51
+ ├── config.json.example # Example configuration
52
+ ├── AGENTS.md # Demo-authoring agent instructions
53
+ ├── .gitignore # Ignores node_modules/, dist/, .cdpn
54
+ ├── package.json # Depends on codepen-demokit + wires up npm scripts
55
+ └── README.md
56
+ ```
57
+
58
+ ### 2. Review `config.json` and authenticate with CodePen
59
+
60
+ `init` populates `config.json` from your answers—you can edit it anytime to adjust your index metadata or CodePen profile:
61
+
62
+ ```json
63
+ {
64
+ "site": {
65
+ "title": "My CodePen Demos",
66
+ "subtitle": "A collection of self-contained web demos.",
67
+ "footer": "Powered by codepen-demokit."
68
+ },
69
+ "codepen": {
70
+ "user": "your-codepen-username",
71
+ "defaultVisibility": "Private"
72
+ }
73
+ }
74
+ ```
75
+
76
+ Then save your CodePen API v2 key to `~/.cdpn` (never committed to your repository) using CodePen Commander:
77
+
78
+ ```sh
79
+ npx cdpn auth login your-codepen-username
80
+ npx cdpn auth status
81
+ ```
82
+
83
+ ### 3. Add demos under `src/` and start developing
84
+
85
+ Each demo lives in its own self-contained `kebab-case` folder inside `src/`—either standalone, inside a topic group, or inside nested subgroups:
86
+
87
+ ```text
88
+ src/
89
+ ├── popover-menu/ # Standalone demo
90
+ │ ├── index.html
91
+ │ └── styles.css
92
+ ├── scroll-driven-animations/ # Topic group
93
+ │ └── coverflow/
94
+ │ ├── index.html
95
+ │ ├── styles.css
96
+ │ └── .cdpn.json # Committed CodePen sync metadata
97
+ └── view-transitions/ # Nested topic groups
98
+ ├── cross-document/
99
+ │ └── off-the-beaten-path/
100
+ │ └── index.html
101
+ └── same-document/
102
+ └── sortable/
103
+ └── index.html
104
+ ```
105
+
106
+ Start the dev server:
107
+
108
+ ```sh
109
+ # Build dist/demos.json, watch src/, and serve the full demo index at http://127.0.0.1:3000
110
+ npm start
111
+
112
+ # Serve a single demo folder directly as root
113
+ npm start "view-transitions/same-document/sortable"
114
+
115
+ # Use a custom port
116
+ PORT=8080 npm start
117
+ ```
118
+
119
+ ---
120
+
121
+ ## Syncing with CodePen
122
+
123
+ CodePen syncing is a core feature of `codepen-demokit` and uses [CodePen Commander](https://www.npmjs.com/package/codepen-commander) (`cdpn`) under the hood. All bulk commands read `codepen.user` and `codepen.defaultVisibility` from `config.json` (and exit with a warning if `config.json` or required CodePen settings are missing).
124
+
125
+ ```sh
126
+ # Two-way sync across all demos in src/ (creates unlinked Pens, pushes local edits, pulls remote updates)
127
+ npm run cdpn:sync
128
+
129
+ # Push local changes and create new Pens for unlinked demos
130
+ npm run cdpn:push
131
+
132
+ # Pull remote updates from CodePen for linked demos
133
+ npm run cdpn:pull
134
+
135
+ # Delete all linked Pens on CodePen (passes --keep-info to retain Pen metadata in .cdpn.json for the next push)
136
+ npm run cdpn:delete
137
+
138
+ # Clone an existing CodePen Pen into src/ (forwards arguments & flags to `cdpn clone`)
139
+ npm run cdpn:clone -- https://codepen.io/username/pen/slug
140
+ npm run cdpn:clone -- https://codepen.io/username/pen/slug group/my-demo
141
+ ```
142
+
143
+ ### Scoping & Flags
144
+
145
+ Pass an optional relative folder inside `src/` (a group, subgroup, or single demo) and/or flags through `--`:
146
+
147
+ ```sh
148
+ # Scope any bulk sync command to a group, subgroup, or single demo
149
+ npm run cdpn:push -- scroll-driven-animations
150
+ npm run cdpn:delete -- view-transitions/same-document
151
+ npm run cdpn:pull -- view-transitions/same-document/sortable
152
+
153
+ # Preview without modifying anything on CodePen or disk
154
+ npm run cdpn:sync -- --dry-run
155
+ npm run cdpn:push -- scroll-driven-animations --dry-run
156
+ npm run cdpn:delete -- view-transitions/same-document --dry-run
157
+
158
+ # Force-pull all linked demos (overwrites local changes and refreshes .cdpn.json)
159
+ npm run cdpn:pull -- --force
160
+
161
+ # Forward any `cdpn clone` options (such as --force, --json, or --help)
162
+ npm run cdpn:clone -- --force https://codepen.io/username/pen/slug my-demo
163
+ ```
164
+
165
+ `cdpn:clone` runs `cdpn clone` inside `src/` using your `codepen.user` profile from `config.json` (when configured) and forwards all arguments and options directly to CodePen Commander.
166
+
167
+ Each synced demo stores non-secret sync metadata in `.cdpn.json` (plus optional `.codepen/pen.config.json`). Keep `.cdpn.json` committed in your demos repo so sync state persists across machines. Add an optional `.cdpnignore` file inside a demo folder to exclude local-only files from syncing.
168
+
169
+ Because `codepen-demokit init` also adds `codepen-commander` directly to your repo's `devDependencies`, `cdpn` is directly available via `npx cdpn` (from the repo root or inside any `src/<demo>/` folder) and `npm run cdpn -- <command>` across npm, pnpm, yarn, and bun—no global install required. If you prefer running bare `cdpn` without `npx` anywhere in your terminal, you can optionally install it globally (`npm install -g codepen-commander`).
170
+
171
+ ---
172
+
173
+ ## Static Builds & Deployment
174
+
175
+ Generate a completely static, self-contained build in `dist/`:
176
+
177
+ ```sh
178
+ npm run build
179
+ # or rebuild continuously on src/ and config.json changes:
180
+ npm run build:watch
181
+ ```
182
+
183
+ `build` copies all non-hidden demo files from `src/` into `dist/` (automatically excluding `.cdpn.json`, `.cdpnignore`, `.codepen/`, `.DS_Store`, and other dotfiles), layers the framework's default index shell (`index.html`, `styles.css`, `scripts.js`) with your `config.json` `site` metadata, and generates `dist/demos.json`.
184
+
185
+ Deploy the `dist/` directory to any static host (GitHub Pages, Netlify, Cloudflare Pages, Vercel, etc.) with `npm run build` as your build command.
186
+
187
+ ---
188
+
189
+ ## Customizing the Index Page
190
+
191
+ - **Title, subtitle, and footer**: Set `site.title`, `site.subtitle`, and `site.footer` in `config.json`.
192
+ - **Full UI overrides**: If you want custom markup, styling, or scripts for the index page, create `src/index.html`, `src/styles.css`, and/or `src/scripts.js`. Any file placed at `src/` root automatically overrides the corresponding framework shell file in both `start` and `build`, while non-overridden files continue receiving framework updates.
193
+
194
+ ---
195
+
196
+ ## Configuration Reference (`config.json`)
197
+
198
+ | Key | Required | Description |
199
+ | :--- | :---: | :--- |
200
+ | `site.title` | No | Page `<title>` and `<h1>` heading (default: `"My CodePen Demos"`). |
201
+ | `site.subtitle` | No | Intro subtitle shown under the heading. |
202
+ | `site.footer` | No | Footer text shown at the bottom of the index page. |
203
+ | `codepen.user` | For `cdpn:*` | CodePen Commander profile name (`npx cdpn auth login <user>`). |
204
+ | `codepen.defaultVisibility` | For `cdpn:*` | Default `--access` for newly created Pens: `Public`, `Private`, `Protected`, or `Collaborators`. |
205
+
206
+ ---
207
+
208
+ ## CLI Reference
209
+
210
+ You can invoke the CLI directly via `npx codepen-demokit <command>` or through your project's `npm` scripts:
211
+
212
+ | Command | Description |
213
+ | :--- | :--- |
214
+ | `codepen-demokit init` | Interactively prompt for project & CodePen details and scaffold a new demos repository without overwriting existing files. |
215
+ | `codepen-demokit start [folder] [--port <port>]` | Build `dist/demos.json`, watch `src/`, and start the local static dev server (alias: `dev`). |
216
+ | `codepen-demokit build [--watch]` | Build the static deployable site into `dist/` (optionally watching `src/` and `config.json`). |
217
+ | `codepen-demokit cdpn <sync\|pull\|push\|delete> [folder] [--dry-run] [--force]` | Bulk sync demos with CodePen via CodePen Commander. |
218
+ | `codepen-demokit cdpn clone [options] <url> [folder]` | Clone a CodePen Pen into `src/` via `cdpn clone` (passing through arguments & options). |
219
+
220
+ ---
221
+
222
+ ## Upgrading `codepen-demokit`
223
+
224
+ In your demos repository, update the framework dependency like any npm package to get CLI fixes, new CodePen Commander integrations, and index shell improvements:
225
+
226
+ ```sh
227
+ npm update codepen-demokit
228
+ # or pin to the latest major/minor release:
229
+ npm install -D codepen-demokit@latest
230
+ ```
package/bin/cli.mjs ADDED
@@ -0,0 +1,154 @@
1
+ #!/usr/bin/env node
2
+
3
+ import fs from 'node:fs/promises';
4
+ import path from 'node:path';
5
+ import { PACKAGE_DIR, buildSite, watchSite } from '../lib/build-site.mjs';
6
+ import { InitCancelledError, initProject } from '../lib/init.mjs';
7
+ import { startServer } from '../lib/serve.mjs';
8
+ import { runCodePenSync } from '../lib/sync-codepen.mjs';
9
+
10
+ async function getVersion() {
11
+ const pkgPath = path.join(PACKAGE_DIR, 'package.json');
12
+ const pkg = JSON.parse(await fs.readFile(pkgPath, 'utf8'));
13
+ return pkg.version || '0.0.0';
14
+ }
15
+
16
+ function printHelp() {
17
+ console.log(`Usage: codepen-demokit <command> [options]
18
+
19
+ Commands:
20
+ init Interactively scaffold a new demos repository
21
+ start [folder-in-src] [--port <port>] Build demos.json, watch src/, and start local dev server
22
+ dev [folder-in-src] [--port <port>] Alias for start
23
+ build [--watch] Build static deployable site into dist/
24
+ cdpn <sync|pull|push|delete> [folder] [flags] Bulk sync demos with CodePen via CodePen Commander
25
+ cdpn clone [options] <url> [folder] Clone a CodePen Pen into src/ via CodePen Commander
26
+
27
+ Options:
28
+ -h, --help Show this help message
29
+ -v, --version Show version number`);
30
+ }
31
+
32
+ function parseStartArgs(argv) {
33
+ let targetFolder = null;
34
+ let port = process.env.PORT;
35
+
36
+ for (let i = 0; i < argv.length; i++) {
37
+ const arg = argv[i];
38
+ if (arg === '-h' || arg === '--help') {
39
+ console.log('Usage: codepen-demokit start [folder-in-src] [--port <port>]');
40
+ process.exit(0);
41
+ } else if (arg === '--port' || arg === '-p') {
42
+ const next = argv[i + 1];
43
+ if (!next || next.startsWith('-')) {
44
+ throw new Error('Missing value for --port.');
45
+ }
46
+ port = next;
47
+ i++;
48
+ } else if (arg.startsWith('--port=')) {
49
+ port = arg.slice('--port='.length);
50
+ } else if (arg.startsWith('-')) {
51
+ throw new Error(`Unknown option '${arg}'.`);
52
+ } else {
53
+ if (targetFolder !== null) {
54
+ throw new Error(`Multiple target folders specified ('${targetFolder}' and '${arg}').`);
55
+ }
56
+ targetFolder = arg;
57
+ }
58
+ }
59
+
60
+ return { targetFolder, port };
61
+ }
62
+
63
+ function parseBuildArgs(argv) {
64
+ let watchMode = false;
65
+
66
+ for (const arg of argv) {
67
+ if (arg === '-h' || arg === '--help') {
68
+ console.log('Usage: codepen-demokit build [--watch]');
69
+ process.exit(0);
70
+ } else if (arg === '--watch' || arg === '-w') {
71
+ watchMode = true;
72
+ } else {
73
+ throw new Error(`Unknown option '${arg}'.`);
74
+ }
75
+ }
76
+
77
+ return { watchMode };
78
+ }
79
+
80
+ function parseInitArgs(argv) {
81
+ for (const arg of argv) {
82
+ if (arg === '-h' || arg === '--help') {
83
+ console.log(`Usage: codepen-demokit init
84
+
85
+ Interactively prompts for project name, directory, and CodePen details.`);
86
+ process.exit(0);
87
+ } else if (arg.startsWith('-')) {
88
+ throw new Error(`Unknown option '${arg}'.`);
89
+ } else {
90
+ throw new Error(
91
+ `Unexpected argument '${arg}'. Run 'codepen-demokit init' without arguments; it will prompt for the project name and directory.`,
92
+ );
93
+ }
94
+ }
95
+ }
96
+
97
+ const [command, ...rest] = process.argv.slice(2);
98
+
99
+ if (!command || command === '-h' || command === '--help') {
100
+ printHelp();
101
+ process.exit(0);
102
+ }
103
+
104
+ if (command === '-v' || command === '--version') {
105
+ console.log(await getVersion());
106
+ process.exit(0);
107
+ }
108
+
109
+ try {
110
+ if (command === 'init') {
111
+ parseInitArgs(rest);
112
+ await initProject({ cwd: process.cwd() });
113
+ } else if (command === 'start' || command === 'dev') {
114
+ const { targetFolder, port } = parseStartArgs(rest);
115
+ await startServer({ projectDir: process.cwd(), targetFolder, port });
116
+ } else if (command === 'build') {
117
+ const { watchMode } = parseBuildArgs(rest);
118
+ const { demoCount } = await buildSite({ projectDir: process.cwd() });
119
+ console.log(`Built dist/ (${demoCount} ${demoCount === 1 ? 'demo' : 'demos'})`);
120
+
121
+ if (watchMode) {
122
+ console.log('Watching src/ and config.json for changes…');
123
+ const handle = watchSite({
124
+ projectDir: process.cwd(),
125
+ onRebuild({ demoCount: updatedCount }) {
126
+ console.log(`Rebuilt dist/ (${updatedCount} ${updatedCount === 1 ? 'demo' : 'demos'})`);
127
+ },
128
+ onError(error) {
129
+ console.error(`Error rebuilding dist/: ${error.message}`);
130
+ },
131
+ });
132
+
133
+ const shutdown = () => {
134
+ handle.close();
135
+ process.exit(0);
136
+ };
137
+ process.on('SIGINT', shutdown);
138
+ process.on('SIGTERM', shutdown);
139
+ }
140
+ } else if (command === 'cdpn') {
141
+ runCodePenSync(rest, { projectDir: process.cwd() });
142
+ } else {
143
+ console.error(`Error: Unknown command '${command}'.\n`);
144
+ printHelp();
145
+ process.exit(1);
146
+ }
147
+ } catch (error) {
148
+ if (error instanceof InitCancelledError) {
149
+ console.error('Init cancelled.');
150
+ process.exit(130);
151
+ }
152
+ console.error(`Error: ${error.message}`);
153
+ process.exit(1);
154
+ }