codepen-commander 1.1.0 → 1.2.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
@@ -80,10 +80,23 @@ Every synced Pen folder contains a `.cdpn.json` file at its root:
80
80
  "url": "https://codepen.io/username/pen/abcde",
81
81
  "pen_id": "01a08738-73f0-7847-b6a8-5789d289c158",
82
82
  "profile": "username",
83
- "last_synced_version_id": "01a08738-73f0-7848-b8bf-e8e7e91b1ae2"
83
+ "last_synced_version_id": "01a08738-73f0-7848-b8bf-e8e7e91b1ae2",
84
+ "last_synced_info_hash": "a1b2c3d4...",
85
+ "editor": "V2",
86
+ "info": {
87
+ "title": "My Awesome Pen",
88
+ "description": "A short description of the Pen",
89
+ "tags": ["css", "demo"],
90
+ "access": "Public",
91
+ "template": false
92
+ }
84
93
  }
85
94
  ```
86
95
 
96
+ The `info` section tracks the Pen’s editable metadata (`title`, `description`, `tags`, `access`, and `template`) and syncs automatically with `cdpn status`, `cdpn push`, `cdpn pull`, `cdpn info`, and `cdpn privacy`. Edit `info.title`, `info.tags`, etc. directly in `.cdpn.json` and run `cdpn push` to update them on CodePen (passwords for `Protected` Pens are never stored in `.cdpn.json`; use `cdpn privacy protected` or `cdpn info --access Protected --password ...` instead).
97
+
98
+ Older `.cdpn.json` files created without an `info` section remain fully supported: `cdpn` will never overwrite remote metadata when `info` is absent, and will seamlessly populate `info` on your next `cdpn pull` or `cdpn push`.
99
+
87
100
  > **Why `.cdpn.json` instead of `.codepen`?**
88
101
  > CodePen 2.0 Pens already contain a `.codepen/` directory (housing `.codepen/pen.config.json`). Using `.cdpn.json` avoids filesystem collisions while allowing `.codepen/pen.config.json` to sync cleanly with CodePen.
89
102
 
@@ -124,9 +137,9 @@ All commands accept the global `--profile <name>` flag to override the active pr
124
137
  | `cdpn new [folder] [--template <id\|url\|title>] [--as-template] [--json]` | Scaffold a brand-new 2.0 Pen from a CodePen Template (or CodePen default starter) into a new or empty folder |
125
138
  | `cdpn fork <url> [folder] [--title ...] [--access ...] [--json]` | Fork one of your own 2.0 Pens into a local folder (for other users' Pens, offers to open in browser to fork and clone back) |
126
139
  | `cdpn clone <url> [folder] [--force] [--json]` | Clone a CodePen Pen into a local folder (auto-matches stored profile by URL owner; offers to convert Classic Pens or clone them unlinked; offers browser fork-and-clone fallback for unowned Pens) |
127
- | `cdpn pull [--force] [--json]` | Pull latest remote changes into an existing cloned folder (requires `.cdpn.json`) |
128
- | `cdpn status [--json]` | Show active profile, file diffs (added/modified/deleted), remote head, build & deployment status |
129
- | `cdpn push [-m <label>] [--force] [--dry-run] [--no-wait] [--json]` | Push local changes (text & binary + deletions), or push an unlinked local demo folder as a new Pen (checks `index.html`, asks account, title, and visibility) |
140
+ | `cdpn pull [--force] [--json]` | Pull latest remote file and Pen info changes into an existing cloned folder (requires `.cdpn.json`) |
141
+ | `cdpn status [--json]` | Show active profile, file and Pen info diffs, remote head, build & deployment status |
142
+ | `cdpn push [-m <label>] [--force] [--dry-run] [--no-wait] [--json]` | Push local file and `.cdpn.json` Pen info changes (text & binary + deletions), or push an unlinked local demo folder as a new Pen (checks `index.html`, asks account, title, and visibility) |
130
143
  | `cdpn deploy [--no-push] [--version <id>] [--force] [--json]` | Push local changes (creating a Pen first if unlinked) and deploy to CodePen Hosting |
131
144
  | `cdpn undeploy [--yes] [--json]` | Take down the live deployment (Pen & versions remain intact) |
132
145
  | `cdpn domains [list] [--json]` | Show the default deployed URL, custom domains, verification status, and required DNS records |
package/commands/clone.js CHANGED
@@ -5,6 +5,7 @@ import { CodePenApiError } from '../api/errors.js';
5
5
  import { DEFAULT_PROFILE_NAME, findMatchingProfile } from '../config/auth.js';
6
6
  import { buildSyncedFileMap, extractCodePenOwnerFromUrl, hasProjectConfigInDir, normalizePenReference, PROJECT_CONFIG_FILENAME, suggestFolderName, writeProjectConfig, } from '../config/project.js';
7
7
  import { isDirectoryNonEmpty } from '../sync/fs.js';
8
+ import { buildPenInfoConfigFields } from '../sync/info.js';
8
9
  import { syncRemoteFilesToDisk } from '../sync/materialize.js';
9
10
  import { openBrowser, validateBrowserUrl } from '../utils/browser.js';
10
11
  import { fmt, shortId } from '../utils/format.js';
@@ -539,6 +540,7 @@ export async function clonePenCommand(options) {
539
540
  ...(auth.profile ? { profile: auth.profile } : {}),
540
541
  last_synced_version_id: pen.saved_version?.id ?? null,
541
542
  editor: pen.editor,
543
+ ...buildPenInfoConfigFields(pen),
542
544
  files: syncedFiles,
543
545
  };
544
546
  const configPath = await writeProjectConfig(targetDir, config);
@@ -3,6 +3,7 @@ import path from 'node:path';
3
3
  import { CodePenClient } from '../api/client.js';
4
4
  import { buildSyncedFileMap, hasProjectConfigInDir, PROJECT_CONFIG_FILENAME, writeProjectConfig, } from '../config/project.js';
5
5
  import { scanLocalFiles } from '../sync/fs.js';
6
+ import { buildPenInfoConfigFields } from '../sync/info.js';
6
7
  import { syncRemoteFilesToDisk } from '../sync/materialize.js';
7
8
  import { fmt, printBuildSummary, shortId } from '../utils/format.js';
8
9
  import { extractHtmlTitle } from '../utils/html.js';
@@ -213,6 +214,7 @@ export async function createPenFromDirectory(options) {
213
214
  ...(auth.profile ? { profile: auth.profile } : {}),
214
215
  last_synced_version_id: finalVersionId,
215
216
  editor: created.editor,
217
+ ...buildPenInfoConfigFields(created),
216
218
  files: buildSyncedFileMap(remoteFiles, materialized.localSha256ByPath),
217
219
  };
218
220
  const configPath = await writeProjectConfig(targetDir, config);
package/commands/fork.js CHANGED
@@ -4,6 +4,7 @@ import { CodePenClient } from '../api/client.js';
4
4
  import { CodePenApiError } from '../api/errors.js';
5
5
  import { buildSyncedFileMap, hasProjectConfigInDir, normalizePenReference, slugifyTitle, suggestFolderName, writeProjectConfig, } from '../config/project.js';
6
6
  import { isDirectoryNonEmpty } from '../sync/fs.js';
7
+ import { buildPenInfoConfigFields } from '../sync/info.js';
7
8
  import { syncRemoteFilesToDisk } from '../sync/materialize.js';
8
9
  import { fmt, printBuildSummary, shortId } from '../utils/format.js';
9
10
  import { CliError, printJsonResponse } from '../utils/json.js';
@@ -252,6 +253,7 @@ export async function forkPenCommand(options) {
252
253
  ...(auth.profile ? { profile: auth.profile } : {}),
253
254
  last_synced_version_id: finalVersionId,
254
255
  editor: forked.editor,
256
+ ...buildPenInfoConfigFields(forked),
255
257
  files: buildSyncedFileMap(remoteFiles, materialized.localSha256ByPath),
256
258
  };
257
259
  const configPath = await writeProjectConfig(targetDir, config);
package/commands/meta.js CHANGED
@@ -1,5 +1,6 @@
1
1
  import { CodePenClient } from '../api/client.js';
2
- import { requireProject } from '../config/project.js';
2
+ import { requireProject, writeProjectConfig } from '../config/project.js';
3
+ import { mergeUpdatedPenInfoIntoConfig } from '../sync/info.js';
3
4
  import { fmt, formatDate, shortId } from '../utils/format.js';
4
5
  import { CliError, printJsonResponse } from '../utils/json.js';
5
6
  import { getGlobalProfileOption, resolveCommandAuth } from './auth-context.js';
@@ -46,6 +47,68 @@ function renderPenSettings(settings) {
46
47
  console.log(`indent_with: ${fmt.cyan(settings.indent_with)}`);
47
48
  console.log(`tab_size: ${fmt.cyan(String(settings.tab_size))}`);
48
49
  }
50
+ export async function infoPenCommand(options = {}) {
51
+ const project = await requireProject(options.cwd ?? process.cwd());
52
+ const auth = await resolveCommandAuth({
53
+ explicitProfile: options.explicitProfile,
54
+ project,
55
+ interactive: options.json ? false : options.interactive,
56
+ persistProfileToProject: !options.json,
57
+ env: options.env,
58
+ homeDir: options.homeDir,
59
+ selectProfile: options.selectProfile,
60
+ });
61
+ const client = new CodePenClient({ apiKey: auth.apiKey, baseUrl: options.baseUrl });
62
+ const patch = {};
63
+ if (options.title !== undefined)
64
+ patch.title = options.title;
65
+ if (options.description !== undefined)
66
+ patch.description = options.description;
67
+ if (options.tags !== undefined) {
68
+ const parsedTags = options.tags
69
+ .split(',')
70
+ .map((t) => t.trim())
71
+ .filter(Boolean);
72
+ if (parsedTags.length > 5) {
73
+ throw new CliError(400, 'CodePen allows at most 5 tags per Pen.');
74
+ }
75
+ patch.tags = parsedTags;
76
+ }
77
+ if (options.access !== undefined) {
78
+ const lower = options.access.trim().toLowerCase();
79
+ if (!VALID_ACCESS.has(lower)) {
80
+ throw new CliError(400, `Invalid --access "${options.access}". Use: Public, Private, Protected, or Collaborators.`);
81
+ }
82
+ patch.access = (lower[0].toUpperCase() + lower.slice(1));
83
+ }
84
+ if (options.password !== undefined) {
85
+ if (options.password.length < 8) {
86
+ throw new CliError(400, 'Password must be at least 8 characters.');
87
+ }
88
+ patch.password = options.password;
89
+ }
90
+ if (options.template !== undefined) {
91
+ patch.template = parseBooleanOption(options.template, '--template');
92
+ }
93
+ const hasUpdates = Object.keys(patch).length > 0;
94
+ const pen = hasUpdates
95
+ ? await client.updatePen(project.config.pen_id, patch)
96
+ : await client.getPen(project.config.pen_id);
97
+ if (hasUpdates) {
98
+ const nextConfig = mergeUpdatedPenInfoIntoConfig(project.config, pen, patch);
99
+ await writeProjectConfig(project.rootDir, nextConfig);
100
+ project.config = nextConfig;
101
+ }
102
+ if (options.json) {
103
+ printJsonResponse(200, hasUpdates ? 'Updated Pen metadata.' : 'Fetched Pen metadata.', pen);
104
+ return { pen, updated: hasUpdates, auth, project };
105
+ }
106
+ if (hasUpdates) {
107
+ console.log(`${fmt.green('✓')} Updated Pen metadata.\n`);
108
+ }
109
+ renderPenInfo(pen, auth.profile);
110
+ return { pen, updated: hasUpdates, auth, project };
111
+ }
49
112
  export function registerMetaCommands(program) {
50
113
  program
51
114
  .command('info')
@@ -58,53 +121,10 @@ export function registerMetaCommands(program) {
58
121
  .option('--template <bool>', 'Set template flag (true/false)')
59
122
  .option('--json', 'Output Pen metadata as JSON')
60
123
  .action(async (options, command) => {
61
- const project = await requireProject();
62
- const auth = await resolveCommandAuth({
124
+ await infoPenCommand({
125
+ ...options,
63
126
  explicitProfile: getGlobalProfileOption(command),
64
- project,
65
- interactive: options.json ? false : undefined,
66
- persistProfileToProject: !options.json,
67
127
  });
68
- const client = new CodePenClient({ apiKey: auth.apiKey });
69
- const patch = {};
70
- if (options.title !== undefined)
71
- patch.title = options.title;
72
- if (options.description !== undefined)
73
- patch.description = options.description;
74
- if (options.tags !== undefined) {
75
- patch.tags = options.tags
76
- .split(',')
77
- .map((t) => t.trim())
78
- .filter(Boolean);
79
- }
80
- if (options.access !== undefined) {
81
- const lower = options.access.trim().toLowerCase();
82
- if (!VALID_ACCESS.has(lower)) {
83
- throw new CliError(400, `Invalid --access "${options.access}". Use: Public, Private, Protected, or Collaborators.`);
84
- }
85
- patch.access = (lower[0].toUpperCase() + lower.slice(1));
86
- }
87
- if (options.password !== undefined) {
88
- if (options.password.length < 8) {
89
- throw new CliError(400, 'Password must be at least 8 characters.');
90
- }
91
- patch.password = options.password;
92
- }
93
- if (options.template !== undefined) {
94
- patch.template = parseBooleanOption(options.template, '--template');
95
- }
96
- const hasUpdates = Object.keys(patch).length > 0;
97
- const pen = hasUpdates
98
- ? await client.updatePen(project.config.pen_id, patch)
99
- : await client.getPen(project.config.pen_id);
100
- if (options.json) {
101
- printJsonResponse(200, hasUpdates ? 'Updated Pen metadata.' : 'Fetched Pen metadata.', pen);
102
- return;
103
- }
104
- if (hasUpdates) {
105
- console.log(`${fmt.green('✓')} Updated Pen metadata.\n`);
106
- }
107
- renderPenInfo(pen, auth.profile);
108
128
  });
109
129
  program
110
130
  .command('settings')
package/commands/new.js CHANGED
@@ -3,6 +3,7 @@ import path from 'node:path';
3
3
  import { CodePenClient } from '../api/client.js';
4
4
  import { buildSyncedFileMap, slugifyTitle, writeProjectConfig, } from '../config/project.js';
5
5
  import { isDirectoryNonEmpty } from '../sync/fs.js';
6
+ import { buildPenInfoConfigFields } from '../sync/info.js';
6
7
  import { syncRemoteFilesToDisk } from '../sync/materialize.js';
7
8
  import { fmt, formatDate, printBuildSummary, shortId } from '../utils/format.js';
8
9
  import { CliError, printJsonResponse } from '../utils/json.js';
@@ -202,6 +203,7 @@ export async function scaffoldNewPen(options = {}) {
202
203
  ...(auth.profile ? { profile: auth.profile } : {}),
203
204
  last_synced_version_id: finalVersionId,
204
205
  editor: created.editor,
206
+ ...buildPenInfoConfigFields(created),
205
207
  files: buildSyncedFileMap(remoteFiles, materialized.localSha256ByPath),
206
208
  };
207
209
  const configPath = await writeProjectConfig(targetDir, config);
@@ -1,5 +1,6 @@
1
1
  import { CodePenClient } from '../api/client.js';
2
- import { requireProjectInDir } from '../config/project.js';
2
+ import { requireProjectInDir, writeProjectConfig } from '../config/project.js';
3
+ import { mergeUpdatedPenInfoIntoConfig } from '../sync/info.js';
3
4
  import { fmt } from '../utils/format.js';
4
5
  import { CliError, printJsonResponse } from '../utils/json.js';
5
6
  import { isInteractive, promptConfirm, promptSecret, promptSelect, } from '../utils/prompts.js';
@@ -177,6 +178,9 @@ export async function managePenPrivacy(options = {}) {
177
178
  };
178
179
  }
179
180
  const updatedPen = await client.updatePen(project.config.pen_id, patch);
181
+ const nextConfig = mergeUpdatedPenInfoIntoConfig(project.config, updatedPen, patch);
182
+ await writeProjectConfig(project.rootDir, nextConfig);
183
+ project.config = nextConfig;
180
184
  if (options.json) {
181
185
  const message = previousAccess === updatedPen.access && passwordUpdated
182
186
  ? 'Updated password for Protected Pen.'
package/commands/pull.js CHANGED
@@ -1,14 +1,16 @@
1
1
  import { CodePenClient } from '../api/client.js';
2
- import { buildSyncedFileMap, requireProject, writeProjectConfig, } from '../config/project.js';
2
+ import { buildSyncedFileMap, PROJECT_CONFIG_FILENAME, requireProject, writeProjectConfig, } from '../config/project.js';
3
3
  import { detectLocalChangesFromBaseline } from '../sync/diff.js';
4
4
  import { scanLocalFiles } from '../sync/fs.js';
5
+ import { analyzeInfoSync, buildPenInfoConfigFields, hasAnyPenInfoFields, isLocalInfoDirty, } from '../sync/info.js';
5
6
  import { syncRemoteFilesToDisk } from '../sync/materialize.js';
6
7
  import { fmt, shortId } from '../utils/format.js';
7
8
  import { CliError, printJsonResponse } from '../utils/json.js';
8
9
  import { isInteractive, promptConfirm, promptSelect, } from '../utils/prompts.js';
9
10
  import { getGlobalProfileOption, resolveCommandAuth } from './auth-context.js';
10
11
  /**
11
- * Pulls the latest remote files from CodePen into an existing cloned folder containing `.cdpn.json`.
12
+ * Pulls the latest remote files and Pen metadata from CodePen into an existing cloned folder
13
+ * containing `.cdpn.json`.
12
14
  * Returns `null` if the user cancels interactively when uncommitted local changes are present.
13
15
  */
14
16
  export async function pullPenCommand(options = {}) {
@@ -36,7 +38,8 @@ export async function pullPenCommand(options = {}) {
36
38
  const localFiles = await scanLocalFiles(rootDir);
37
39
  const localDirty = detectLocalChangesFromBaseline(localFiles, config.files);
38
40
  const dirtyCount = localDirty.added.length + localDirty.modified.length + localDirty.deleted.length;
39
- if (dirtyCount > 0 && !force) {
41
+ const localInfoDirty = isLocalInfoDirty(config.info, config.last_synced_info_hash);
42
+ if ((dirtyCount > 0 || localInfoDirty) && !force) {
40
43
  if (!jsonMode) {
41
44
  console.log(fmt.yellow('\nWarning: You have uncommitted local changes that will be overwritten:'));
42
45
  for (const p of localDirty.added)
@@ -45,9 +48,15 @@ export async function pullPenCommand(options = {}) {
45
48
  console.log(` ${fmt.yellow('~')} ${p} ${fmt.dim('(will be overwritten)')}`);
46
49
  for (const p of localDirty.deleted)
47
50
  console.log(` ${fmt.red('-')} ${p} ${fmt.dim('(will be restored)')}`);
51
+ if (localInfoDirty) {
52
+ console.log(` ${fmt.yellow('~')} ${PROJECT_CONFIG_FILENAME} (info) ${fmt.dim('(will be overwritten)')}`);
53
+ }
48
54
  }
49
55
  if (!interactive) {
50
- throw new CliError(409, 'Local changes detected. Commit/push them first, or re-run with --force.', { dirty_files: localDirty });
56
+ throw new CliError(409, 'Local changes detected. Commit/push them first, or re-run with --force.', {
57
+ dirty_files: localDirty,
58
+ ...(localInfoDirty ? { dirty_info: true } : {}),
59
+ });
51
60
  }
52
61
  const ok = await confirmImpl('\nOverwrite local changes with remote version?', false);
53
62
  if (!ok) {
@@ -59,6 +68,8 @@ export async function pullPenCommand(options = {}) {
59
68
  client.getPen(config.pen_id),
60
69
  client.getPenFiles(config.pen_id),
61
70
  ]);
71
+ const hadInfoBefore = hasAnyPenInfoFields(config.info);
72
+ const infoAnalysis = analyzeInfoSync(config.info, config.last_synced_info_hash, pen);
62
73
  const result = await syncRemoteFilesToDisk({
63
74
  client,
64
75
  rootDir,
@@ -74,6 +85,7 @@ export async function pullPenCommand(options = {}) {
74
85
  ...(profileToPersist ? { profile: profileToPersist } : {}),
75
86
  last_synced_version_id: pen.saved_version?.id ?? null,
76
87
  editor: pen.editor,
88
+ ...buildPenInfoConfigFields(pen),
77
89
  files: syncedFiles,
78
90
  };
79
91
  const configPath = await writeProjectConfig(rootDir, nextConfig);
@@ -95,6 +107,12 @@ export async function pullPenCommand(options = {}) {
95
107
  }
96
108
  console.log(` Updated: ${result.writtenPaths.length} file(s)` +
97
109
  (result.deletedPaths.length > 0 ? `, removed ${result.deletedPaths.length} deleted file(s)` : ''));
110
+ if (!hadInfoBefore) {
111
+ console.log(` Info: ${fmt.dim(`added to ${PROJECT_CONFIG_FILENAME}`)}`);
112
+ }
113
+ else if (infoAnalysis.changes.length > 0) {
114
+ console.log(` Info: ${fmt.dim(`updated ${infoAnalysis.changes.map((c) => c.field).join(', ')} in ${PROJECT_CONFIG_FILENAME}`)}`);
115
+ }
98
116
  if (pen.saved_version) {
99
117
  console.log(` Version: ${fmt.dim(shortId(pen.saved_version.id))}`);
100
118
  }