create-zapwebp 1.0.0 → 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/README.md CHANGED
@@ -1,38 +1,107 @@
1
- # `create-zapwebp`
1
+ # create-zapwebp
2
2
 
3
- Scaffold production-ready Zapwebp plugins, storage adapters, custom transformations, and metadata handlers in seconds.
3
+ Scaffold agent-native Zapwebp plugins, storage adapters, custom transforms, and metadata handlers in seconds.
4
4
 
5
- ## Quick Start
5
+ Covers: Scaffolding agent-native plugins, format handlers, storage adapters, transforms, and metadata plugins with `AGENTS.md`, `SKILLS.md`, and CI workflows.
6
+
7
+ Does not cover: Runtime image conversions, build packaging, or publishing to npm.
8
+
9
+ Applies to: `create-zapwebp` v1.0.0 and later, Node.js >=22.0.0.
10
+
11
+ ## Quick start
6
12
 
7
13
  ```bash
8
- npm create zapwebp@latest
9
- # or
10
14
  pnpm create zapwebp
15
+ # or
16
+ npm create zapwebp@latest
11
17
  ```
12
18
 
13
- Or specify template and name non-interactively:
19
+ Or scaffold non-interactively:
14
20
 
15
21
  ```bash
16
- pnpm create zapwebp my-plugin --type format
22
+ pnpm create zapwebp my-zapwebp-plugin --type format --author "Jane Doe" --github janedoe --pm pnpm
17
23
  ```
18
24
 
25
+ ## What it does
26
+
27
+ `create-zapwebp` generates **context, not boilerplate**. It provides a working project skeleton, empty-but-structured `AGENTS.md` and `SKILLS.md` files, and a first-run prompt that tells your AI coding agent (Antigravity, Cursor, Claude) to define your project intent before writing code:
28
+ - **6 Archetype Templates**: Formats, storage adapters, pixel transforms, metadata strippers, build plugins, and custom extensions.
29
+ - **Agent Governance Ready**: Pre-scaffolds `AGENTS.md`, `SKILLS.md`, and `agent.json` discovery manifests.
30
+ - **Zero Config CI**: Includes pre-wired GitHub Actions workflows for tests and automated npm releases.
31
+
19
32
  ## Available Archetype Templates
20
33
 
21
34
  | Archetype | Flag | Description |
22
35
  |---|---|---|
23
- | `format` | `--type format` | Community format expansion handler (`zapwebp-format-*`) with sniffer, decoder, and alpha validation. |
24
- | `storage` | `--type storage` | Cloud storage upload adapter (`@zapwebp/storage-*`) with pre-upload conversion and cascade deletion. |
25
- | `transform` | `--type transform` | Image manipulation plugin (`@zapwebp/transform-*`) operating on raw in-memory RGBA pixel buffers. |
26
- | `meta` | `--type meta` | Custom metadata sanitizer (`zapwebp-meta-*`) with chunk extraction and preservation predicates. |
36
+ | `format` | `--type format` | Input/output format decoder & encoder (`FormatHandler`) with sniffer and alpha safety. |
37
+ | `storage` | `--type storage` | Cloud storage adapter (`StorageAdapter`) with pre-upload conversion and cascade deletion. |
38
+ | `transform` | `--type transform` | In-memory raw RGBA pixel transformer (`TransformStep`) for cropping, filtering, and effects. |
39
+ | `metadata` | `--type metadata` | Custom metadata inspector and stripper (`MetadataHandler`) with chunk manipulation. |
40
+ | `build` | `--type build` | Build tool integration plugin (`ZapPlugin`) for Vite, Next.js, Webpack, or Rollup. |
41
+ | `custom` | `--type custom` | General lifecycle plugin (`ZapPlugin`) starting from scratch. |
42
+
43
+ ## Generated Project Structure
44
+
45
+ ```
46
+ my-zapwebp-plugin/
47
+ ├── .github/
48
+ │ ├── workflows/
49
+ │ │ ├── test.yml # CI test runner
50
+ │ │ └── release.yml # Automated npm publish on release tag
51
+ │ ├── ISSUE_TEMPLATE/
52
+ │ └── PULL_REQUEST_TEMPLATE.md
53
+ ├── src/
54
+ │ ├── index.ts # Typed plugin implementation stub
55
+ │ └── types.ts # Re-exported types from @zapwebp/plugin-sdk
56
+ ├── test/
57
+ │ ├── fixtures/ # Sample asset fixtures directory
58
+ │ └── index.test.ts # Initial passing test proving harness works
59
+ ├── AGENTS.md # Structured context contract for AI coding agents
60
+ ├── SKILLS.md # Agent skill definition (Antigravity, Cursor, Claude)
61
+ ├── agent.json # Machine-readable discovery manifest
62
+ ├── .zapwebp-scaffold.json # Template and version metadata for automated upgrades
63
+ ├── README.md # Installation, usage, and security docs
64
+ ├── CHANGELOG.md # Keep a Changelog format
65
+ ├── CONTRIBUTING.md # Open source contribution guide
66
+ ├── CODE_OF_CONDUCT.md # Contributor Code of Conduct
67
+ ├── LICENSE # MIT License
68
+ ├── tsconfig.json # Strict TypeScript configuration
69
+ ├── tsup.config.ts # Dual ESM/CJS bundler configuration
70
+ └── vitest.config.ts # Unit test configuration
71
+ ```
72
+
73
+ ## The First-Run Workflow
74
+
75
+ 1. Scaffold your project with `pnpm create zapwebp`.
76
+ 2. Open the directory in your IDE or AI assistant.
77
+ 3. Review `AGENTS.md` and `SKILLS.md`.
78
+ 4. Prompt your AI assistant: *"Read AGENTS.md and SKILLS.md. Help me fill them in for my plugin, then write the implementation."*
79
+ 5. Run `pnpm test` and `pnpm run build`.
80
+
81
+ ## Errors
82
+
83
+ | Code | Cause | Fix |
84
+ |---|---|---|
85
+ | `E_TARGET_EXISTS` | Destination directory already exists and is non-empty | Choose another directory name or empty the folder |
86
+ | `E_INVALID_ARCHETYPE` | Requested archetype does not match supported templates | Use one of `format`, `storage`, `transform`, `metadata`, `build`, `custom` |
87
+ | `E_MISSING_NAME` | Project name argument missing in non-interactive mode | Provide target folder name as positional argument |
27
88
 
28
- ## What's Included in Generated Projects
89
+ ## For agents
29
90
 
30
- - Dual CommonJS and ESM packaging (`tsup` / Node.js native).
31
- - Integration test harnesses using `@zapwebp/plugin-sdk`.
32
- - Complete TypeScript declaration definitions (`.d.ts`).
33
- - Ready-to-publish `.npmignore`, `README.md`, and GitHub Actions CI workflow.
91
+ ```json
92
+ {
93
+ "tool": "create-zapwebp",
94
+ "archetypes": ["format", "storage", "transform", "metadata", "build", "custom"],
95
+ "flags": ["--type", "--author", "--github", "--pm"]
96
+ }
97
+ ```
34
98
 
35
- ## License
99
+ ## Related
36
100
 
37
- MIT © Zapwebp
101
+ - [Scaffolding Guide](https://zapwebp-docs.vercel.app/scaffolding): Complete plugin developer tutorial.
102
+ - [Plugin SDK](https://zapwebp-docs.vercel.app/sdk/plugin): Core interfaces implemented by scaffolded projects.
103
+ - [Contributing](https://zapwebp-docs.vercel.app/contributing): Submitting plugins to the ecosystem directory.
104
+
105
+ ## License
38
106
 
107
+ MIT © [Zapwebp](https://zapwebp.vercel.app/)
@@ -3,41 +3,157 @@
3
3
 
4
4
  const readline = require('node:readline/promises');
5
5
  const { stdin: input, stdout: output } = require('node:process');
6
- const { scaffoldProject, ARCHETYPES } = require('../src');
6
+ const path = require('node:path');
7
+ const { scaffoldProject } = require('../src');
7
8
 
8
- async function main() {
9
- const args = process.argv.slice(2);
10
- let archetype = args[0];
11
- let name = args[1];
12
-
13
- if (!archetype || !name) {
14
- const rl = readline.createInterface({ input, output });
15
- try {
16
- if (!archetype) {
17
- output.write('⚡ Welcome to create-zapwebp!\n');
18
- output.write(`Available archetypes: ${ARCHETYPES.join(', ')}\n`);
19
- archetype = (await rl.question('? What do you want to build? (format|storage|plugin|cli|metadata): ')).trim();
20
- }
21
- if (!name) {
22
- name = (await rl.question('? What is the plugin or format name?: ')).trim();
23
- }
24
- } finally {
25
- rl.close();
9
+ function parseArgs(argv) {
10
+ const options = {
11
+ name: undefined,
12
+ archetype: undefined,
13
+ author: undefined,
14
+ githubUser: undefined,
15
+ packageManager: undefined,
16
+ };
17
+
18
+ const positional = [];
19
+ for (let i = 0; i < argv.length; i++) {
20
+ const arg = argv[i];
21
+ if (arg === '--type' || arg === '-t') {
22
+ options.archetype = argv[++i];
23
+ } else if (arg === '--author' || arg === '-a') {
24
+ options.author = argv[++i];
25
+ } else if (arg === '--github' || arg === '-g') {
26
+ options.githubUser = argv[++i];
27
+ } else if (arg === '--pm' || arg === '--package-manager') {
28
+ options.packageManager = argv[++i];
29
+ } else if (arg.startsWith('--type=')) {
30
+ options.archetype = arg.slice(7);
31
+ } else if (arg.startsWith('--author=')) {
32
+ options.author = arg.slice(9);
33
+ } else if (arg.startsWith('--github=')) {
34
+ options.githubUser = arg.slice(9);
35
+ } else if (arg.startsWith('--pm=')) {
36
+ options.packageManager = arg.slice(5);
37
+ } else if (!arg.startsWith('-')) {
38
+ positional.push(arg);
26
39
  }
27
40
  }
28
41
 
29
- if (!archetype || !name) {
30
- console.error('Error: Archetype and name are required.');
31
- process.exit(1);
42
+ if (positional.length === 1) {
43
+ if (['format', 'storage', 'transform', 'metadata', 'build', 'custom', 'plugin', 'meta', 'cli'].includes(positional[0])) {
44
+ options.archetype = options.archetype || positional[0];
45
+ } else {
46
+ options.name = options.name || positional[0];
47
+ }
48
+ } else if (positional.length >= 2) {
49
+ if (['format', 'storage', 'transform', 'metadata', 'build', 'custom', 'plugin', 'meta', 'cli'].includes(positional[0])) {
50
+ options.archetype = options.archetype || positional[0];
51
+ options.name = options.name || positional[1];
52
+ } else {
53
+ options.name = options.name || positional[0];
54
+ options.archetype = options.archetype || positional[1];
55
+ }
32
56
  }
33
57
 
58
+ return options;
59
+ }
60
+
61
+ async function promptUser(defaults) {
62
+ const rl = readline.createInterface({ input, output });
63
+
34
64
  try {
35
- const result = await scaffoldProject({ archetype, name, targetDir: process.cwd() });
36
- console.log(`\n✅ Successfully scaffolded project at ${result.targetDir}`);
37
- console.log(`Generated ${result.files.length} files:\n ${result.files.join('\n ')}\n`);
38
- console.log('Next steps:');
39
- console.log(` cd zapwebp-${archetype}-${name}`);
40
- console.log(' pnpm install && pnpm test\n');
65
+ output.write('\n⚡ Welcome to create-zapwebp!\n');
66
+ output.write('Scaffold an agent-native Zapwebp plugin skeleton.\n\n');
67
+
68
+ let archetype = defaults.archetype;
69
+ if (!archetype) {
70
+ output.write('? What do you want to build?\n');
71
+ output.write(' 1) Format plugin (add input/output format support)\n');
72
+ output.write(' 2) Storage adapter (add cloud storage integration)\n');
73
+ output.write(' 3) Transform plugin (crop, filter, resize, etc.)\n');
74
+ output.write(' 4) Metadata plugin (strip, extract, or modify metadata)\n');
75
+ output.write(' 5) Build tool plugin (Vite, Next, Webpack integration)\n');
76
+ output.write(' 6) Custom plugin (start from scratch)\n');
77
+
78
+ const ans = (await rl.question(' Select archetype [1-6] (default: 1): ')).trim();
79
+ if (ans === '2' || ans.toLowerCase() === 'storage') archetype = 'storage';
80
+ else if (ans === '3' || ans.toLowerCase() === 'transform') archetype = 'transform';
81
+ else if (ans === '4' || ans.toLowerCase() === 'metadata' || ans.toLowerCase() === 'meta') archetype = 'metadata';
82
+ else if (ans === '5' || ans.toLowerCase() === 'build') archetype = 'build';
83
+ else if (ans === '6' || ans.toLowerCase() === 'custom' || ans.toLowerCase() === 'plugin') archetype = 'custom';
84
+ else archetype = 'format';
85
+ }
86
+
87
+ let name = defaults.name;
88
+ if (!name) {
89
+ name = (await rl.question('? Plugin name (default: my-zapwebp-plugin): ')).trim() || 'my-zapwebp-plugin';
90
+ }
91
+
92
+ let author = defaults.author;
93
+ if (!author) {
94
+ author = (await rl.question('? Your name (for LICENSE, package.json author) [Jane Doe]: ')).trim() || 'Jane Doe';
95
+ }
96
+
97
+ let githubUser = defaults.githubUser;
98
+ if (!githubUser) {
99
+ githubUser = (await rl.question('? GitHub username [janedoe]: ')).trim() || 'janedoe';
100
+ }
101
+
102
+ let packageManager = defaults.packageManager;
103
+ if (!packageManager) {
104
+ const pmAns = (await rl.question('? Which package manager? (pnpm/npm/yarn/bun) [pnpm]: ')).trim().toLowerCase();
105
+ packageManager = ['npm', 'yarn', 'bun'].includes(pmAns) ? pmAns : 'pnpm';
106
+ }
107
+
108
+ return { archetype, name, author, githubUser, packageManager };
109
+ } finally {
110
+ rl.close();
111
+ }
112
+ }
113
+
114
+ async function main() {
115
+ const parsed = parseArgs(process.argv.slice(2));
116
+
117
+ let config;
118
+ const isInteractive = process.stdin.isTTY && (!parsed.name || !parsed.archetype);
119
+
120
+ if (isInteractive) {
121
+ config = await promptUser(parsed);
122
+ } else {
123
+ config = {
124
+ archetype: parsed.archetype || 'format',
125
+ name: parsed.name || 'my-zapwebp-plugin',
126
+ author: parsed.author || 'Jane Doe',
127
+ githubUser: parsed.githubUser || 'janedoe',
128
+ packageManager: parsed.packageManager || 'pnpm',
129
+ };
130
+ }
131
+
132
+ try {
133
+ const result = await scaffoldProject({
134
+ targetDir: process.cwd(),
135
+ ...config,
136
+ });
137
+
138
+ const relPath = path.relative(process.cwd(), result.targetDir) || result.pluginName;
139
+ const pm = config.packageManager || 'pnpm';
140
+
141
+ console.log(`\n✅ Scaffolded ${result.pluginName}\n`);
142
+ console.log(`Your new plugin is at ./${relPath}/\n`);
143
+ console.log('Before you start writing code:\n');
144
+ console.log(' 1. Open this folder in your editor (VS Code, Cursor, Antigravity, etc.)');
145
+ console.log(' 2. Read AGENTS.md — it tells the AI agent what you want to build');
146
+ console.log(' 3. Read SKILLS.md — it tells the AI agent how to build it');
147
+ console.log(' 4. If you\'re using an AI agent, ask it to fill in AGENTS.md and SKILLS.md');
148
+ console.log(' based on what you want to build. Then ask it to start.\n');
149
+ console.log('The scaffolder left AGENTS.md, SKILLS.md, and agent.json empty on purpose.');
150
+ console.log('They are yours, not ours.\n');
151
+ console.log('Quick reference:');
152
+ console.log(` cd ${relPath}`);
153
+ console.log(` ${pm} install`);
154
+ console.log(` ${pm} test — run tests`);
155
+ console.log(` ${pm} run build — build the plugin`);
156
+ console.log(` ${pm} changeset — create a release note\n`);
41
157
  } catch (err) {
42
158
  console.error(`\n❌ Scaffolding failed: ${err.message}\n`);
43
159
  process.exit(1);
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "create-zapwebp",
3
- "version": "1.0.0",
4
- "description": "Scaffold working Zapwebp format plugins, storage adapters, build plugins, and custom CLIs.",
3
+ "version": "1.1.0",
4
+ "description": "Scaffold agent-native Zapwebp plugins with structured AGENTS.md, SKILLS.md, and TypeScript tooling.",
5
5
  "bin": {
6
6
  "create-zapwebp": "bin/create-zapwebp.js"
7
7
  },
package/src/index.js CHANGED
@@ -3,194 +3,762 @@
3
3
  const fs = require('node:fs/promises');
4
4
  const path = require('node:path');
5
5
 
6
- const ARCHETYPES = ['format', 'storage', 'plugin', 'cli', 'metadata', 'transform'];
6
+ const ARCHETYPES = ['format', 'storage', 'transform', 'metadata', 'build', 'custom'];
7
7
 
8
8
  /**
9
- * Generates scaffolding for a Zapwebp ecosystem project.
9
+ * Generates scaffolding for an agent-native Zapwebp ecosystem project.
10
+ *
10
11
  * @param {object} options
11
- * @param {string} options.targetDir
12
- * @param {'format'|'storage'|'plugin'|'cli'|'metadata'} options.archetype
13
- * @param {string} options.name
14
- * @param {string} [options.author='Zapwebp Developer']
15
- * @returns {Promise<{ targetDir: string, files: string[] }>}
12
+ * @param {string} [options.targetDir] - Destination root directory
13
+ * @param {'format'|'storage'|'transform'|'metadata'|'build'|'custom'} options.archetype - Plugin archetype
14
+ * @param {string} options.name - Plugin or format name
15
+ * @param {string} [options.author='Jane Doe'] - Author name
16
+ * @param {string} [options.githubUser='janedoe'] - GitHub username
17
+ * @param {'pnpm'|'npm'|'yarn'|'bun'} [options.packageManager='pnpm'] - Preferred package manager
18
+ * @returns {Promise<{ targetDir: string, pluginName: string, files: string[] }>}
16
19
  */
17
20
  async function scaffoldProject(options) {
18
- const { targetDir, archetype, name, author = 'Zapwebp Developer' } = options;
19
- if (!name || typeof name !== 'string') {
21
+ const {
22
+ targetDir = process.cwd(),
23
+ archetype = 'format',
24
+ name,
25
+ author = 'Jane Doe',
26
+ githubUser = 'janedoe',
27
+ packageManager = 'pnpm',
28
+ } = options;
29
+
30
+ const cleanName = String(name || '').trim();
31
+ if (!cleanName) {
20
32
  throw new Error('Project name is required.');
21
33
  }
22
- if (!ARCHETYPES.includes(archetype)) {
34
+
35
+ const rawArch = String(archetype || '').toLowerCase();
36
+ const normalizedArch =
37
+ rawArch === 'plugin' || rawArch === 'cli'
38
+ ? 'custom'
39
+ : rawArch === 'meta'
40
+ ? 'metadata'
41
+ : rawArch;
42
+
43
+ if (!ARCHETYPES.includes(normalizedArch)) {
23
44
  throw new Error(`Invalid archetype "${archetype}". Supported: ${ARCHETYPES.join(', ')}`);
24
45
  }
25
46
 
26
- const resolvedDir = path.resolve(targetDir || process.cwd(), `zapwebp-${archetype}-${name}`);
47
+ const pluginName = cleanName.startsWith('zapwebp-')
48
+ ? cleanName
49
+ : cleanName.includes('-')
50
+ ? cleanName
51
+ : `zapwebp-${normalizedArch}-${cleanName}`;
52
+
53
+ const resolvedDir = path.resolve(targetDir, pluginName);
54
+
27
55
  await fs.mkdir(resolvedDir, { recursive: true });
28
56
  await fs.mkdir(path.join(resolvedDir, 'src'), { recursive: true });
29
- await fs.mkdir(path.join(resolvedDir, 'test'), { recursive: true });
57
+ await fs.mkdir(path.join(resolvedDir, 'test', 'fixtures'), { recursive: true });
30
58
  await fs.mkdir(path.join(resolvedDir, '.github', 'workflows'), { recursive: true });
59
+ await fs.mkdir(path.join(resolvedDir, '.github', 'ISSUE_TEMPLATE'), { recursive: true });
31
60
 
32
61
  const files = [];
33
62
 
34
63
  // 1. package.json
35
64
  const pkgJson = {
36
- name: `zapwebp-${archetype}-${name}`,
37
- version: '1.0.0',
38
- description: `Zapwebp ${archetype} plugin for ${name}.`,
39
- main: 'src/index.js',
65
+ name: pluginName,
66
+ version: '0.1.0',
67
+ description: `Zapwebp ${normalizedArch} plugin for ${cleanName}`,
68
+ author,
69
+ license: 'MIT',
70
+ type: 'module',
71
+ main: './dist/index.cjs',
72
+ module: './dist/index.js',
73
+ types: './dist/index.d.ts',
74
+ exports: {
75
+ '.': {
76
+ import: {
77
+ types: './dist/index.d.ts',
78
+ default: './dist/index.js',
79
+ },
80
+ require: {
81
+ types: './dist/index.d.ts',
82
+ default: './dist/index.cjs',
83
+ },
84
+ },
85
+ },
86
+ files: ['dist', 'agent.json', 'README.md', 'LICENSE'],
40
87
  scripts: {
41
- test: 'node --test',
88
+ build: 'tsup',
89
+ dev: 'tsup --watch',
90
+ test: 'vitest run',
91
+ 'test:watch': 'vitest',
92
+ lint: 'eslint src test --ext .ts',
93
+ format: 'prettier --write "src/**/*.ts" "test/**/*.ts"',
42
94
  },
43
95
  dependencies: {
44
96
  '@zapwebp/plugin-sdk': '^1.1.0',
45
97
  },
46
- engines: {
47
- node: '>=20',
98
+ devDependencies: {
99
+ '@typescript-eslint/eslint-plugin': '^7.0.0',
100
+ '@typescript-eslint/parser': '^7.0.0',
101
+ eslint: '^8.57.0',
102
+ prettier: '^3.2.5',
103
+ tsup: '^8.0.2',
104
+ typescript: '^5.4.0',
105
+ vitest: '^1.4.0',
106
+ },
107
+ zapwebp: {
108
+ permissions: normalizedArch === 'storage' ? ['network'] : [],
48
109
  },
49
110
  };
50
111
  await fs.writeFile(path.join(resolvedDir, 'package.json'), JSON.stringify(pkgJson, null, 2) + '\n');
51
112
  files.push('package.json');
52
113
 
53
- // 2. src/index.js
54
- let srcContent = '';
55
- if (archetype === 'format') {
56
- srcContent = `'use strict';
57
-
58
- const { safeDecode, createMockRawImage } = require('@zapwebp/plugin-sdk');
114
+ // 2. tsconfig.json
115
+ const tsconfig = {
116
+ compilerOptions: {
117
+ target: 'ES2022',
118
+ module: 'NodeNext',
119
+ moduleResolution: 'NodeNext',
120
+ esModuleInterop: true,
121
+ strict: true,
122
+ skipLibCheck: true,
123
+ declaration: true,
124
+ outDir: './dist',
125
+ rootDir: './src',
126
+ },
127
+ include: ['src/**/*'],
128
+ exclude: ['node_modules', 'dist', 'test'],
129
+ };
130
+ await fs.writeFile(path.join(resolvedDir, 'tsconfig.json'), JSON.stringify(tsconfig, null, 2) + '\n');
131
+ files.push('tsconfig.json');
132
+
133
+ // 3. tsup.config.ts
134
+ const tsupConfig = `import { defineConfig } from 'tsup';
135
+
136
+ export default defineConfig({
137
+ entry: ['src/index.ts'],
138
+ format: ['cjs', 'esm'],
139
+ dts: true,
140
+ clean: true,
141
+ sourcemap: true,
142
+ splitting: false,
143
+ });
144
+ `;
145
+ await fs.writeFile(path.join(resolvedDir, 'tsup.config.ts'), tsupConfig);
146
+ files.push('tsup.config.ts');
59
147
 
60
- /** @type {import('@zapwebp/plugin-sdk').FormatHandler} */
61
- const handler = {
62
- name: '${name}',
63
- mimeTypes: Object.freeze(['image/${name}']),
64
- extensions: Object.freeze(['.${name}']),
65
- supportsAlpha: true,
148
+ // 4. vitest.config.ts
149
+ const vitestConfig = `import { defineConfig } from 'vitest/config';
66
150
 
67
- detect(bytes) {
68
- if (!bytes || bytes.length < 4) return false;
69
- return true; // Match header signature
151
+ export default defineConfig({
152
+ test: {
153
+ globals: true,
154
+ environment: 'node',
70
155
  },
156
+ });
157
+ `;
158
+ await fs.writeFile(path.join(resolvedDir, 'vitest.config.ts'), vitestConfig);
159
+ files.push('vitest.config.ts');
160
+
161
+ // 5. .eslintrc.json
162
+ const eslintrc = {
163
+ root: true,
164
+ parser: '@typescript-eslint/parser',
165
+ plugins: ['@typescript-eslint'],
166
+ extends: ['eslint:recommended', 'plugin:@typescript-eslint/recommended'],
167
+ rules: {
168
+ 'no-console': 'warn',
169
+ '@typescript-eslint/no-explicit-any': 'error',
170
+ '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
171
+ },
172
+ };
173
+ await fs.writeFile(path.join(resolvedDir, '.eslintrc.json'), JSON.stringify(eslintrc, null, 2) + '\n');
174
+ files.push('.eslintrc.json');
175
+
176
+ // 6. .prettierrc
177
+ const prettierrc = {
178
+ semi: true,
179
+ singleQuote: true,
180
+ trailingComma: 'all',
181
+ printWidth: 100,
182
+ tabWidth: 2,
183
+ };
184
+ await fs.writeFile(path.join(resolvedDir, '.prettierrc'), JSON.stringify(prettierrc, null, 2) + '\n');
185
+ files.push('.prettierrc');
186
+
187
+ // 7. .gitignore
188
+ const gitignore = `node_modules
189
+ dist
190
+ .zapwebp
191
+ coverage
192
+ *.log
193
+ .DS_Store
194
+ *.tgz
195
+ `;
196
+ await fs.writeFile(path.join(resolvedDir, '.gitignore'), gitignore);
197
+ files.push('.gitignore');
198
+
199
+ // 8. LICENSE
200
+ const licenseContent = `MIT License
201
+
202
+ Copyright (c) ${new Date().getFullYear()} ${author}
203
+
204
+ Permission is hereby granted, free of charge, to any person obtaining a copy
205
+ of this software and associated documentation files (the "Software"), to deal
206
+ in the Software without restriction, including without limitation the rights
207
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
208
+ copies of the Software, and to permit persons to whom the Software is
209
+ furnished to do so, subject to the following conditions:
210
+
211
+ The above copyright notice and this permission notice shall be included in all
212
+ copies or substantial portions of the Software.
213
+
214
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
215
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
216
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
217
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
218
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
219
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
220
+ SOFTWARE.
221
+ `;
222
+ await fs.writeFile(path.join(resolvedDir, 'LICENSE'), licenseContent);
223
+ files.push('LICENSE');
71
224
 
72
- async decode(bytes) {
73
- // Decodes bytes to RGBA RawImage
74
- return createMockRawImage(100, 100);
75
- },
225
+ // 9. src/types.ts
226
+ const typesContent = `/**
227
+ * Re-exported types from @zapwebp/plugin-sdk for convenience.
228
+ */
229
+ export type {
230
+ FormatHandler,
231
+ StorageAdapter,
232
+ TransformStep,
233
+ MetadataHandler,
234
+ MetadataField,
235
+ RawImage,
236
+ ZapPlugin,
237
+ ZapPluginHooks,
238
+ ZapPluginAgentMetadata,
239
+ ConvertContext,
240
+ ConvertOutput,
241
+ } from '@zapwebp/plugin-sdk';
242
+ `;
243
+ await fs.writeFile(path.join(resolvedDir, 'src', 'types.ts'), typesContent);
244
+ files.push('src/types.ts');
245
+
246
+ // 10. src/index.ts (Per archetype)
247
+ let indexTsContent = '';
248
+ if (normalizedArch === 'format') {
249
+ indexTsContent = `import type { FormatHandler } from './types';
250
+
251
+ // TODO: Implement your format plugin.
252
+ // See AGENTS.md for what this plugin should do.
253
+ // See SKILLS.md for how AI agents should work on it.
254
+
255
+ export const handler: FormatHandler = {
256
+ name: '${cleanName}',
257
+ extensions: ['.${cleanName}'],
258
+ mimeTypes: ['image/${cleanName}'],
259
+ supportsAlpha: true,
76
260
 
77
- async encode(image, options) {
78
- return Buffer.alloc(0);
261
+ detect: (_bytes) => false,
262
+ decode: async () => {
263
+ throw new Error('Not implemented');
264
+ },
265
+ encode: async () => {
266
+ throw new Error('Not implemented');
79
267
  },
80
268
  };
81
269
 
82
- module.exports = handler;
270
+ export default handler;
83
271
  `;
84
- } else if (archetype === 'storage') {
85
- srcContent = `'use strict';
272
+ } else if (normalizedArch === 'storage') {
273
+ indexTsContent = `import type { StorageAdapter } from './types';
274
+
275
+ // TODO: Implement your storage adapter.
276
+ // See AGENTS.md for what this adapter should do.
277
+ // See SKILLS.md for how AI agents should work on it.
86
278
 
87
- const { validateStorageWrite } = require('@zapwebp/plugin-sdk');
279
+ export class Adapter implements StorageAdapter {
280
+ name: string;
281
+ config: Record<string, any>;
88
282
 
89
- class StorageAdapter {
90
- constructor(config = {}) {
91
- this.name = '${name}';
283
+ constructor(config: Record<string, any> = {}) {
284
+ this.name = '${cleanName}';
92
285
  this.config = config;
93
286
  }
94
287
 
95
- async read(sourcePath) {
96
- return Buffer.alloc(0);
288
+ async read(_sourcePath: string): Promise<Buffer> {
289
+ throw new Error('Not implemented');
97
290
  }
98
291
 
99
- async write(destinationPath, data) {
100
- validateStorageWrite(destinationPath, data);
292
+ async write(_destinationPath: string, _data: Buffer): Promise<void> {
293
+ throw new Error('Not implemented');
101
294
  }
102
295
 
103
- async delete(destinationPath) {
104
- // Delete implementation
296
+ async delete(_destinationPath: string): Promise<void> {
297
+ throw new Error('Not implemented');
105
298
  }
106
299
  }
107
300
 
108
- module.exports = { StorageAdapter };
301
+ export const adapter = (config?: Record<string, any>) => new Adapter(config);
302
+ export default adapter;
109
303
  `;
110
- } else if (archetype === 'metadata') {
111
- srcContent = `'use strict';
304
+ } else if (normalizedArch === 'transform') {
305
+ indexTsContent = `import type { RawImage, TransformStep } from './types';
112
306
 
113
- /** @type {import('@zapwebp/plugin-sdk').MetadataHandler} */
114
- const handler = {
115
- name: '${name}',
116
- async inspect(bytes) {
307
+ // TODO: Implement your transform plugin.
308
+ // See AGENTS.md for what this transform should do.
309
+ // See SKILLS.md for how AI agents should work on it.
310
+
311
+ export interface TransformOptions {
312
+ [key: string]: any;
313
+ }
314
+
315
+ export function transform(options: TransformOptions = {}): TransformStep {
316
+ return {
317
+ name: '${cleanName}',
318
+ metadata: options,
319
+ async apply(image: RawImage): Promise<RawImage> {
320
+ // Return transformed RawImage
321
+ return image;
322
+ },
323
+ };
324
+ }
325
+
326
+ export default transform;
327
+ `;
328
+ } else if (normalizedArch === 'metadata') {
329
+ indexTsContent = `import type { MetadataHandler, MetadataField } from './types';
330
+
331
+ // TODO: Implement your metadata handler.
332
+ // See AGENTS.md for what this handler should do.
333
+ // See SKILLS.md for how AI agents should work on it.
334
+
335
+ export const handler: MetadataHandler = {
336
+ name: '${cleanName}',
337
+
338
+ async inspect(_bytes: Uint8Array | Buffer): Promise<MetadataField[]> {
117
339
  return [];
118
340
  },
119
- async strip(bytes) {
341
+
342
+ async strip(bytes: Uint8Array | Buffer): Promise<Uint8Array | Buffer> {
120
343
  return bytes;
121
344
  },
122
345
  };
123
346
 
124
- module.exports = handler;
347
+ export default handler;
125
348
  `;
126
- } else if (archetype === 'transform') {
127
- srcContent = `'use strict';
349
+ } else if (normalizedArch === 'build') {
350
+ indexTsContent = `import type { ZapPlugin } from './types';
128
351
 
129
- const { defineTransform } = require('@zapwebp/plugin-sdk');
352
+ // TODO: Implement your build tool plugin.
353
+ // See AGENTS.md for what this build plugin should do.
354
+ // See SKILLS.md for how AI agents should work on it.
130
355
 
131
- /**
132
- * Creates a ${name} TransformStep.
133
- * @param {object} [options]
134
- * @returns {import('@zapwebp/plugin-sdk').TransformStep}
135
- */
136
- function ${name}Transform(options = {}) {
137
- return defineTransform({
138
- name: '${name}',
139
- metadata: options,
140
- async apply(image) {
141
- // image is a RawImage: { data: Uint8ClampedArray, width: number, height: number }
142
- // Return a transformed RawImage
143
- return image;
356
+ export interface BuildPluginOptions {
357
+ [key: string]: any;
358
+ }
359
+
360
+ export function plugin(_options: BuildPluginOptions = {}): ZapPlugin {
361
+ return {
362
+ name: '${pluginName}',
363
+ version: '0.1.0',
364
+ description: '',
365
+ hooks: {
366
+ beforeConvert: (ctx) => ctx,
367
+ afterConvert: (_ctx, outputs) => outputs,
144
368
  },
145
- });
369
+ };
146
370
  }
147
371
 
148
- module.exports = {
149
- ${name}Transform,
150
- };
372
+ export default plugin;
151
373
  `;
152
374
  } else {
153
- srcContent = `'use strict';
375
+ indexTsContent = `import type { ZapPlugin } from './types';
154
376
 
155
- const { definePlugin } = require('@zapwebp/plugin-sdk');
377
+ // TODO: Implement your custom Zapwebp plugin.
378
+ // See AGENTS.md for what this plugin should do.
379
+ // See SKILLS.md for how AI agents should work on it.
156
380
 
157
- const plugin = definePlugin({
158
- name: 'zapwebp-${archetype}-${name}',
159
- version: '1.0.0',
381
+ export const plugin: ZapPlugin = {
382
+ name: '${pluginName}',
383
+ version: '0.1.0',
384
+ description: '',
160
385
  hooks: {
161
- beforeConvert(ctx) {
162
- return ctx;
163
- },
164
- afterConvert(ctx, outputs) {
165
- return outputs;
166
- },
386
+ beforeConvert: (ctx) => ctx,
387
+ afterConvert: (_ctx, outputs) => outputs,
167
388
  },
389
+ };
390
+
391
+ export default plugin;
392
+ `;
393
+ }
394
+ await fs.writeFile(path.join(resolvedDir, 'src', 'index.ts'), indexTsContent);
395
+ files.push('src/index.ts');
396
+
397
+ // 11. test/fixtures/README.md
398
+ const fixturesReadme = `# Test Fixtures
399
+
400
+ Place sample images, vectors, and test files in this directory.
401
+ Use small, copyright-free fixtures for unit and integration testing.
402
+ `;
403
+ await fs.writeFile(path.join(resolvedDir, 'test', 'fixtures', 'README.md'), fixturesReadme);
404
+ files.push('test/fixtures/README.md');
405
+
406
+ // 12. test/index.test.ts
407
+ const testContent = `import { describe, it, expect } from 'vitest';
408
+ import * as plugin from '../src/index';
409
+
410
+ describe('${pluginName}', () => {
411
+ it('exports at least one thing', () => {
412
+ expect(Object.keys(plugin).length).toBeGreaterThan(0);
413
+ });
168
414
  });
415
+ `;
416
+ await fs.writeFile(path.join(resolvedDir, 'test', 'index.test.ts'), testContent);
417
+ files.push('test/index.test.ts');
418
+
419
+ // 13. AGENTS.md
420
+ let agentsExampleComment = '<!-- Example: Describe what this plugin does in one paragraph. -->';
421
+ if (normalizedArch === 'format') {
422
+ agentsExampleComment = '<!-- Example: This plugin adds HEIC input support to Zapwebp via libheif WASM. -->';
423
+ } else if (normalizedArch === 'storage') {
424
+ agentsExampleComment = '<!-- Example: This adapter uploads converted images to Cloudflare R2. -->';
425
+ } else if (normalizedArch === 'transform') {
426
+ agentsExampleComment = '<!-- Example: This transform crops images based on face coordinates. -->';
427
+ } else if (normalizedArch === 'build') {
428
+ agentsExampleComment = '<!-- Example: This plugin integrates Zapwebp into Vite build pipeline. -->';
429
+ } else if (normalizedArch === 'metadata') {
430
+ agentsExampleComment = '<!-- Example: This plugin extracts and strips proprietary EXIF tags. -->';
431
+ }
169
432
 
170
- module.exports = plugin;
433
+ const agentsMd = `# AGENTS.md — Project Context
434
+
435
+ This file tells AI coding agents what this plugin does and how to work on it.
436
+ **Fill this in before writing any code.**
437
+ The scaffolder left this empty on purpose — it is your project, not ours.
438
+
439
+ ---
440
+
441
+ ## What this plugin does
442
+ <!-- One paragraph. What problem does it solve? Who is it for? -->
443
+ ${agentsExampleComment}
444
+
445
+ ## Who it is for
446
+ <!-- Be specific. "Developers converting HEIC to WebP on macOS" is good. "Everyone" is not. -->
447
+
448
+ ## What it does NOT do
449
+ <!-- List the things you deliberately excluded. This prevents scope creep. -->
450
+
451
+ ## Key decisions
452
+ <!--
453
+ Any non-obvious choice made in this plugin. Each entry should be:
454
+ - What we chose
455
+ - Why we chose it
456
+ - What we gave up
457
+ Example:
458
+ - **We use libheif via WASM** — runs in browsers without native dependencies
459
+ - Gave up: ~2.5MB bundle size
460
+ -->
461
+
462
+ ## How to work on this plugin
463
+ <!--
464
+ Tell future contributors (and agents) how to run the tests, build, and publish.
465
+ Example:
466
+ - \`${packageManager} test\` — runs unit tests
467
+ - \`${packageManager} build\` — produces \`dist/\`
468
+ - \`${packageManager} changeset\` — create a release note
469
+ -->
470
+
471
+ ## Edge cases we care about
472
+ <!--
473
+ List the specific edge cases this plugin must handle correctly.
474
+ Example:
475
+ - HEIC files with multiple images (return first)
476
+ - HEIC files with alpha channel
477
+ - HEIC files larger than 50 MB (reject before decode)
478
+ -->
479
+
480
+ ## Edge cases we do NOT care about
481
+ <!--
482
+ List what's out of scope.
483
+ Example:
484
+ - HEIC encoding (we only decode)
485
+ - HEIC sequences (single image only)
486
+ -->
487
+
488
+ ## External resources
489
+ <!-- Links to specs, docs, or issues that are essential to understand this plugin -->
171
490
  `;
491
+ await fs.writeFile(path.join(resolvedDir, 'AGENTS.md'), agentsMd);
492
+ files.push('AGENTS.md');
493
+
494
+ // 14. SKILLS.md
495
+ let howToInvokeCode = `import { registerFormat } from '@zapwebp/core';\nimport { handler } from '${pluginName}';\nregisterFormat(handler);`;
496
+ if (normalizedArch === 'storage') {
497
+ howToInvokeCode = `import { withZapwebp } from '@zapwebp/storage';\nimport { adapter } from '${pluginName}';\nconst zap = withZapwebp(adapter(config), { to: 'webp' });`;
498
+ } else if (normalizedArch === 'transform') {
499
+ howToInvokeCode = `import { convert } from '@zapwebp/core';\nimport { transform } from '${pluginName}';\nconst output = await convert(bytes, { transforms: [transform()] });`;
500
+ } else if (normalizedArch === 'metadata') {
501
+ howToInvokeCode = `import { registerMetadataHandler } from '@zapwebp/core';\nimport { handler } from '${pluginName}';\nregisterMetadataHandler(handler);`;
502
+ } else if (normalizedArch === 'build') {
503
+ howToInvokeCode = `import { defineConfig } from 'vite';\nimport { plugin } from '${pluginName}';\nexport default defineConfig({ plugins: [plugin()] });`;
172
504
  }
173
- await fs.writeFile(path.join(resolvedDir, 'src', 'index.js'), srcContent);
174
- files.push('src/index.js');
175
505
 
176
- // 3. test/index.test.js
177
- const testContent = `'use strict';
506
+ const skillsMd = `# SKILLS.md — Agent Skills for This Plugin
507
+
508
+ This file teaches AI agents how to work on this specific plugin.
509
+ It is used by:
510
+ - Antigravity (as a skill definition)
511
+ - Cursor (as a \`.cursorrules\` fallback)
512
+ - Claude Desktop (as additional context)
513
+
514
+ **Fill this in before starting development.**
515
+ The scaffolder left this empty on purpose.
516
+
517
+ ---
518
+
519
+ ## Skill: \`${pluginName}\`
520
+
521
+ ### When to use this skill
522
+ <!--
523
+ Describe the user requests that should trigger this skill.
524
+ Example:
525
+ - "Convert HEIC files to WebP"
526
+ - "Handle iPhone photos in the asset pipeline"
527
+ - "Add HEIC support to my build"
528
+ -->
529
+
530
+ ### What this plugin provides
531
+ <!--
532
+ List the functions, tools, or hooks this plugin exposes.
533
+ Example:
534
+ - \`heicHandler\`: A \`FormatHandler\` for HEIC input
535
+ - \`heicDecode(bytes)\`: Low-level decoder
536
+ -->
537
+
538
+ ### How to invoke it
539
+ <!--
540
+ Show the exact import and usage for a developer.
541
+ Example:
542
+ \`\`\`typescript
543
+ ${howToInvokeCode}
544
+ \`\`\`
545
+ -->
546
+
547
+ ### Common patterns
548
+ <!--
549
+ Show how to use this plugin for common tasks.
550
+ Example:
551
+ \`\`\`typescript
552
+ const webp = await convert(bytes, { to: 'webp' });
553
+ \`\`\`
554
+ -->
555
+
556
+ ### Errors you might see
557
+ <!--
558
+ List the errors this plugin can throw, and what they mean.
559
+ Example:
560
+ - \`E_HEIC_CORRUPT\`: The HEIC file is corrupted or truncated
561
+ - \`E_HEIC_UNSUPPORTED\`: The HEIC variant is not supported
562
+ -->
563
+
564
+ ### How to debug
565
+ <!--
566
+ Describe how to diagnose issues.
567
+ Example:
568
+ - Set \`DEBUG=zapwebp:${cleanName}\` before running
569
+ - Check \`test/fixtures/\` for known-working samples
570
+ -->
571
+
572
+ ### Agent workflow for this plugin
573
+
574
+ When a user asks you (the agent) to work on this plugin, follow these steps:
575
+
576
+ 1. Read AGENTS.md to understand the project context.
577
+ 2. Read this SKILLS.md to understand the capabilities.
578
+ 3. Read src/index.ts to understand the current implementation.
579
+ 4. If adding a feature, update AGENTS.md first.
580
+ 5. If adding a capability, update this SKILLS.md first.
581
+ 6. Write tests in test/.
582
+ 7. Run ${packageManager} test before submitting.
583
+ `;
584
+ await fs.writeFile(path.join(resolvedDir, 'SKILLS.md'), skillsMd);
585
+ files.push('SKILLS.md');
586
+
587
+ // 15. agent.json
588
+ const agentJson = {
589
+ name: pluginName,
590
+ version: '0.1.0',
591
+ description: '',
592
+ capabilities: [],
593
+ functions: [],
594
+ errors: {},
595
+ examples: [],
596
+ docs: '',
597
+ };
598
+ await fs.writeFile(path.join(resolvedDir, 'agent.json'), JSON.stringify(agentJson, null, 2) + '\n');
599
+ files.push('agent.json');
600
+
601
+ // 16. .zapwebp-scaffold.json
602
+ const scaffoldMetadata = {
603
+ scaffolderVersion: '1.1.0',
604
+ pluginType: normalizedArch,
605
+ templateVersion: '1',
606
+ generatedAt: new Date().toISOString(),
607
+ pluginName,
608
+ authorName: author,
609
+ githubUser,
610
+ };
611
+ await fs.writeFile(path.join(resolvedDir, '.zapwebp-scaffold.json'), JSON.stringify(scaffoldMetadata, null, 2) + '\n');
612
+ files.push('.zapwebp-scaffold.json');
613
+
614
+ // 17. README.md
615
+ let readmeUsageSnippet = '';
616
+ if (normalizedArch === 'format') {
617
+ readmeUsageSnippet = `import { registerFormat } from '@zapwebp/core';
618
+ import { handler } from '${pluginName}';
178
619
 
179
- const test = require('node:test');
180
- const assert = require('node:assert/strict');
181
- const mod = require('../src');
620
+ registerFormat(handler);
621
+ `;
622
+ } else if (normalizedArch === 'storage') {
623
+ readmeUsageSnippet = `import { withZapwebp } from '@zapwebp/storage';
624
+ import { adapter } from '${pluginName}';
625
+
626
+ const zap = withZapwebp(adapter(config), { to: 'webp' });
627
+ `;
628
+ } else if (normalizedArch === 'transform') {
629
+ readmeUsageSnippet = `import { convert } from '@zapwebp/core';
630
+ import { transform } from '${pluginName}';
182
631
 
183
- test('Scaffolded module loads and exports expected API', () => {
184
- assert.ok(mod);
632
+ const output = await convert(input, {
633
+ transforms: [transform({ /* options */ })],
185
634
  });
186
635
  `;
187
- await fs.writeFile(path.join(resolvedDir, 'test', 'index.test.js'), testContent);
188
- files.push('test/index.test.js');
636
+ } else if (normalizedArch === 'metadata') {
637
+ readmeUsageSnippet = `import { registerMetadataHandler } from '@zapwebp/core';
638
+ import { handler } from '${pluginName}';
639
+
640
+ registerMetadataHandler(handler);
641
+ `;
642
+ } else if (normalizedArch === 'build') {
643
+ readmeUsageSnippet = `import { defineConfig } from 'vite';
644
+ import { plugin } from '${pluginName}';
645
+
646
+ export default defineConfig({
647
+ plugins: [plugin({ /* options */ })],
648
+ });
649
+ `;
650
+ } else {
651
+ readmeUsageSnippet = `import { definePlugin } from '@zapwebp/plugin-sdk';
652
+ import { plugin } from '${pluginName}';
653
+ `;
654
+ }
655
+
656
+ const readmeContent = `# ${pluginName}
657
+
658
+ A Zapwebp ${normalizedArch} plugin for \`${cleanName}\` by ${author}.
659
+
660
+ ## Install
661
+
662
+ \`\`\`bash
663
+ ${packageManager} add ${pluginName}
664
+ \`\`\`
665
+
666
+ ## Usage
667
+
668
+ \`\`\`typescript
669
+ ${readmeUsageSnippet}\`\`\`
670
+
671
+ ## Implementation Notes
672
+
673
+ Fill in \`AGENTS.md\` and \`SKILLS.md\` before writing code. They guide human contributors and autonomous AI agents.
674
+
675
+ ## Security & Sandbox Model
676
+
677
+ Zapwebp executes plugins in an isolated capability-based sandbox.
678
+ - **Bytes in, bytes out**: Your plugin receives byte buffers and returns byte buffers.
679
+ - **No filesystem/process access**: Direct access to \`node:fs\` or \`node:child_process\` is forbidden and rejected with \`E_PLUGIN_SANDBOX_VIOLATION\`.
680
+ ${normalizedArch === 'storage' ? '- **Network permissions**: As a storage adapter, network capability is declared in `package.json` under `zapwebp.permissions: ["network"]` and requires user consent.' : '- **Zero network access**: Format, transform, and metadata plugins run offline with no network capabilities.'}
681
+
682
+ ## Testing & Verification
683
+
684
+ \`\`\`bash
685
+ ${packageManager} test
686
+ ${packageManager} run build
687
+ \`\`\`
688
+
689
+ ## License
690
+
691
+ MIT © [${author}](https://github.com/${githubUser})
692
+ `;
693
+ await fs.writeFile(path.join(resolvedDir, 'README.md'), readmeContent);
694
+ files.push('README.md');
695
+
696
+ // 18. CHANGELOG.md
697
+ const today = new Date().toISOString().split('T')[0];
698
+ const changelogContent = `# Changelog
699
+
700
+ All notable changes to this project will be documented in this file.
701
+
702
+ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
703
+ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
189
704
 
190
- // 4. .github/workflows/test.yml
191
- const ciContent = `name: Test
705
+ ## [Unreleased]
192
706
 
193
- on: [push, pull_request]
707
+ ## [0.1.0] - ${today}
708
+
709
+ ### Added
710
+ - Initial project skeleton scaffolded via \`create-zapwebp\`.
711
+ - Initial structured \`AGENTS.md\` and \`SKILLS.md\` context files.
712
+ - Test harness and build configuration.
713
+ `;
714
+ await fs.writeFile(path.join(resolvedDir, 'CHANGELOG.md'), changelogContent);
715
+ files.push('CHANGELOG.md');
716
+
717
+ // 19. CONTRIBUTING.md
718
+ const contributingContent = `# Contributing to ${pluginName}
719
+
720
+ Thank you for your interest in contributing!
721
+
722
+ ## Workflow
723
+
724
+ 1. **Check the context first**: Read \`AGENTS.md\` and \`SKILLS.md\` to understand the project goals and constraints.
725
+ 2. **Branching**: Create a topic branch from \`main\`.
726
+ 3. **Tests**: Add unit tests in \`test/\` for any new logic or bug fixes.
727
+ 4. **Code style**: Run \`${packageManager} run lint\` and \`${packageManager} run format\` before opening a pull request.
728
+ 5. **Pull Request**: Open a PR with a clear description linking relevant issues.
729
+ `;
730
+ await fs.writeFile(path.join(resolvedDir, 'CONTRIBUTING.md'), contributingContent);
731
+ files.push('CONTRIBUTING.md');
732
+
733
+ // 20. CODE_OF_CONDUCT.md
734
+ const cocContent = `# Contributor Code of Conduct
735
+
736
+ ## Our Pledge
737
+ We pledge to make participation in this project a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
738
+
739
+ ## Standards
740
+ - Demonstrate empathy and kindness toward others
741
+ - Be respectful of differing opinions, viewpoints, and experiences
742
+ - Give and gracefully accept constructive feedback
743
+ - Accept responsibility and apologize to those affected by our mistakes
744
+
745
+ ## Scope
746
+ This Code of Conduct applies within all project spaces, and also applies when an individual is officially representing the project in public spaces.
747
+
748
+ ## Enforcement
749
+ Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the project maintainers.
750
+ `;
751
+ await fs.writeFile(path.join(resolvedDir, 'CODE_OF_CONDUCT.md'), cocContent);
752
+ files.push('CODE_OF_CONDUCT.md');
753
+
754
+ // 21. .github/workflows/test.yml
755
+ const ciTestContent = `name: Test
756
+
757
+ on:
758
+ push:
759
+ branches: [main]
760
+ pull_request:
761
+ branches: [main]
194
762
 
195
763
  jobs:
196
764
  test:
@@ -200,33 +768,125 @@ jobs:
200
768
  - uses: actions/setup-node@v4
201
769
  with:
202
770
  node-version: 22
203
- - run: npm install
204
- - run: npm test
771
+ - run: npm install -g ${packageManager === 'bun' ? 'bun' : 'pnpm'}
772
+ - run: ${packageManager} install
773
+ - run: ${packageManager} run lint
774
+ - run: ${packageManager} run build
775
+ - run: ${packageManager} test
205
776
  `;
206
- await fs.writeFile(path.join(resolvedDir, '.github', 'workflows', 'test.yml'), ciContent);
777
+ await fs.writeFile(path.join(resolvedDir, '.github', 'workflows', 'test.yml'), ciTestContent);
207
778
  files.push('.github/workflows/test.yml');
208
779
 
209
- // 5. README.md
210
- const readmeContent = `# zapwebp-${archetype}-${name}
211
-
212
- > Zapwebp ${archetype} plugin for ${name} by ${author}.
213
-
214
- ## Installation
780
+ // 22. .github/workflows/release.yml
781
+ const ciReleaseContent = `name: Release
215
782
 
216
- \`\`\`bash
217
- npm install zapwebp-${archetype}-${name}
218
- \`\`\`
219
-
220
- ## Testing
783
+ on:
784
+ push:
785
+ tags:
786
+ - 'v*'
221
787
 
222
- \`\`\`bash
223
- npm test
224
- \`\`\`
788
+ jobs:
789
+ release:
790
+ runs-on: ubuntu-latest
791
+ steps:
792
+ - uses: actions/checkout@v4
793
+ - uses: actions/setup-node@v4
794
+ with:
795
+ node-version: 22
796
+ registry-url: 'https://registry.npmjs.org'
797
+ - run: npm install -g ${packageManager === 'bun' ? 'bun' : 'pnpm'}
798
+ - run: ${packageManager} install
799
+ - run: ${packageManager} run build
800
+ - run: ${packageManager} test
801
+ - run: ${packageManager} publish --no-git-checks
802
+ env:
803
+ NODE_AUTH_TOKEN: \${{ secrets.NPM_TOKEN }}
225
804
  `;
226
- await fs.writeFile(path.join(resolvedDir, 'README.md'), readmeContent);
227
- files.push('README.md');
805
+ await fs.writeFile(path.join(resolvedDir, '.github', 'workflows', 'release.yml'), ciReleaseContent);
806
+ files.push('.github/workflows/release.yml');
807
+
808
+ // 23. .github/ISSUE_TEMPLATE/bug_report.yml
809
+ const bugReportContent = `name: Bug Report
810
+ description: File a bug report to help improve this plugin
811
+ title: "[Bug]: "
812
+ labels: ["bug"]
813
+ body:
814
+ - type: markdown
815
+ attributes:
816
+ value: Thanks for taking the time to report an issue!
817
+ - type: textarea
818
+ id: description
819
+ attributes:
820
+ label: Describe the bug
821
+ description: A clear and concise description of what the bug is.
822
+ validations:
823
+ required: true
824
+ - type: textarea
825
+ id: reproduction
826
+ attributes:
827
+ label: Steps to Reproduce
828
+ description: Steps to reproduce the behavior.
829
+ placeholder: |
830
+ 1. Convert image with options...
831
+ 2. Inspect output...
832
+ validations:
833
+ required: true
834
+ - type: textarea
835
+ id: expected
836
+ attributes:
837
+ label: Expected Behavior
838
+ description: A clear and concise description of what you expected to happen.
839
+ validations:
840
+ required: true
841
+ `;
842
+ await fs.writeFile(path.join(resolvedDir, '.github', 'ISSUE_TEMPLATE', 'bug_report.yml'), bugReportContent);
843
+ files.push('.github/ISSUE_TEMPLATE/bug_report.yml');
844
+
845
+ // 24. .github/ISSUE_TEMPLATE/feature_request.yml
846
+ const featureRequestContent = `name: Feature Request
847
+ description: Suggest an idea or enhancement for this plugin
848
+ title: "[Feature]: "
849
+ labels: ["enhancement"]
850
+ body:
851
+ - type: markdown
852
+ attributes:
853
+ value: Share your ideas for new capabilities or improvements.
854
+ - type: textarea
855
+ id: problem
856
+ attributes:
857
+ label: Is your feature request related to a problem?
858
+ description: A clear and concise description of what the problem is.
859
+ validations:
860
+ required: true
861
+ - type: textarea
862
+ id: solution
863
+ attributes:
864
+ label: Describe the solution you'd like
865
+ description: A clear and concise description of what you want to happen.
866
+ validations:
867
+ required: true
868
+ `;
869
+ await fs.writeFile(path.join(resolvedDir, '.github', 'ISSUE_TEMPLATE', 'feature_request.yml'), featureRequestContent);
870
+ files.push('.github/ISSUE_TEMPLATE/feature_request.yml');
871
+
872
+ // 25. .github/PULL_REQUEST_TEMPLATE.md
873
+ const prTemplateContent = `## Description
874
+ <!-- Describe what this PR does and why it was needed. -->
875
+
876
+ ## Related AGENTS.md / Issue
877
+ <!-- Link to the issue or AGENTS.md scope decision. -->
878
+
879
+ ## Checklist
880
+ - [ ] Read AGENTS.md and verified changes match project scope
881
+ - [ ] Tests added/updated in \`test/\`
882
+ - [ ] All tests pass (\`${packageManager} test\`)
883
+ - [ ] Built successfully (\`${packageManager} run build\`)
884
+ - [ ] Lint passed (\`${packageManager} run lint\`)
885
+ `;
886
+ await fs.writeFile(path.join(resolvedDir, '.github', 'PULL_REQUEST_TEMPLATE.md'), prTemplateContent);
887
+ files.push('.github/PULL_REQUEST_TEMPLATE.md');
228
888
 
229
- return { targetDir: resolvedDir, files };
889
+ return { targetDir: resolvedDir, pluginName, files };
230
890
  }
231
891
 
232
892
  module.exports = {