0
# Core Publishing Workflow
1

2
The core publishing functionality that orchestrates the complete npm publishing pipeline with automated version bumping, testing, git operations, and registry publishing.
3

4
## Capabilities
5

6
### Main Publishing Function
7

8
The primary entry point for all publishing operations, handling the complete workflow from validation to publication.
9

10
```javascript { .api }
11
/**
12
 * Main publishing function that handles the complete npm publishing workflow
13
 * @param input - Version increment ('patch'|'minor'|'major'|'prerelease'|'prepatch'|'preminor'|'premajor') or specific version string (default: 'patch')
14
 * @param options - Publishing configuration options
15
 * @param context - Package metadata and root directory context
16
 * @returns Promise resolving to updated package.json data
17
 */
18
function np(
19
  input?: string,
20
  options?: Options,
21
  context?: {
22
    package_: NormalizedPackageJson;
23
    rootDirectory: string;
24
  }
25
): Promise<NormalizedPackageJson>;
26
```
27

28
**Usage Examples:**
29

30
```javascript
31
import np from "np";
32

33
// Basic patch release
34
const result = await np("patch", {
35
  cleanup: true,
36
  tests: true,
37
  publish: true
38
}, {
39
  package_: require('./package.json'),
40
  rootDirectory: process.cwd()
41
});
42

43
// Prerelease with custom tag
44
const prerelease = await np("prerelease", {
45
  tag: "beta",
46
  message: "Beta release v%s",
47
  releaseDraft: false
48
}, context);
49

50
// Preview mode (dry run)
51
const preview = await np("minor", {
52
  preview: true,
53
  packageManager: "pnpm"
54
}, context);
55

56
// Skip tests and cleanup (YOLO mode)
57
const quick = await np("patch", {
58
  yolo: true,
59
  publish: true
60
}, context);
61
```
62

63
### CLI Implementation
64

65
CLI implementation with argument parsing and interactive prompts.
66

67
```javascript { .api }
68
/**
69
 * Get parsed CLI options and configuration
70
 * @returns Promise resolving to options, package context, and root directory
71
 */
72
function getOptions(): Promise<{
73
  options: Options;
74
  rootDirectory: string;
75
  package_: NormalizedPackageJson;
76
}>;
77
```
78

79
### Task Execution Pipeline
80

81
The publishing workflow consists of sequential tasks executed using Listr:
82

83
1. **Prerequisite Check** - Validate environment and requirements
84
2. **Git Operations** - Branch validation, clean working tree verification
85
3. **Cleanup** - Optional node_modules cleanup
86
4. **Dependencies** - Reinstall dependencies if cleanup enabled
87
5. **Testing** - Run test suite if enabled
88
6. **Version Bump** - Update package version and create git tag
89
7. **Publishing** - Publish to npm registry
90
8. **2FA Setup** - Enable 2FA on new packages if enabled
91
9. **Git Push** - Push commits and tags to remote
92
10. **Release Draft** - Create GitHub release draft if enabled
93

94
### Error Handling and Rollback
95

96
Automatic rollback functionality in case of publishing failures.
97

98
```javascript { .api }
99
/**
100
 * Rollback function that reverts changes on publish failure
101
 * Removes the latest git tag and commit if version was bumped
102
 */
103
const rollback: () => Promise<void>;
104
```
105

106
**Rollback Process:**
107
- Detects if package version was bumped
108
- Removes the latest git tag
109
- Removes the latest commit
110
- Provides status feedback
111

112
### Preview Mode
113

114
Dry-run functionality that shows what commands would be executed without making changes.
115

116
```javascript { .api }
117
interface PreviewOptions extends Options {
118
  preview: true;
119
}
120
```
121

122
**Preview Features:**
123
- Shows all commands that would be executed
124
- Validates configuration without making changes  
125
- Displays version bump without committing
126
- Shows publish command without uploading
127
- Previews git operations without pushing
128

129
### Release Draft Only Mode
130

131
Mode for creating GitHub release drafts for already published versions.
132

133
```javascript { .api }
134
interface ReleaseDraftOptions extends Options {
135
  releaseDraftOnly: true;
136
}
137
```
138

139
## Publishing Workflow Details
140

141
### Version Input Handling
142

143
The `input` parameter accepts:
144

145
- **Semver increments**: `patch`, `minor`, `major`, `prepatch`, `preminor`, `premajor`, `prerelease`
146
- **Specific versions**: `1.2.3`, `2.0.0-beta.1`, `1.0.0-alpha.2`
147
- **Default**: `patch` if no input provided
148

149
### Context Requirements
150

151
The `context` parameter must provide:
152

153
```javascript { .api }
154
interface PublishContext {
155
  package_: NormalizedPackageJson;  // Parsed package.json
156
  rootDirectory: string;           // Absolute path to project root
157
}
158
```
159

160
### Options Processing
161

162
Options are merged from multiple sources in priority order:
163

164
1. CLI flags (highest priority)
165
2. Configuration files (`.np-config.json`, `.np-config.js`, etc.)
166
3. Default values (lowest priority)
167

168
### Private Package Handling
169

170
Private packages (with `"private": true` in package.json) are handled specially:
171

172
- Publishing to npm is automatically disabled
173
- Version bumping and git operations still proceed
174
- Release drafts can still be created
175
- All other validation steps are performed
176

177
### External Registry Support
178

179
Limited support for external npm registries:
180

181
- Some package managers throw errors with external registries
182
- 2FA setup is disabled for external registries
183
- Package name availability checks may not work
184
- Publishing commands are adjusted for registry URL
185

186
## Error Conditions
187

188
Common error scenarios and their handling:
189

190
### Publishing Errors
191
- **Network failures**: Automatic retry with OTP prompt for 2FA
192
- **Permission errors**: Clear error messages with suggestions
193
- **Registry errors**: Detailed npm error output with context
194
- **Validation failures**: Early exit with specific validation messages
195

196
### Git Errors
197
- **Dirty working tree**: Clear error with uncommitted changes list
198
- **Remote out of sync**: Automatic fetch with conflict resolution guidance
199
- **No upstream**: Warning with option to skip push
200
- **Tag conflicts**: Validation against remote tags before creation
201

202
### Environment Errors
203
- **Missing dependencies**: Clear requirements list (Node.js, npm, git versions)
204
- **Package manager issues**: Detection and switching guidance
205
- **Permission issues**: File system and registry permission guidance