@howlil/ez-agents 3.4.2 → 3.5.0

package/ez-agents/workflows/hotfix.md

@@ -0,0 +1,291 @@
+<purpose>
+Manage hotfix branches: create from main, complete by merging atomically to main (and develop for GitFlow), tag the release, and sync without polluting in-progress work.
+</purpose>
+
+<process>
+
+## 1. Parse Arguments
+
+Extract from $ARGUMENTS:
+- Subcommand: `start` or `complete`
+- Name: slug for the hotfix (e.g., `critical-bug`, `gmail-login-fix`)
+- Version (for `complete` only): semver string
+
+**If missing subcommand:**
+```
+Usage:
+  /ez:hotfix start <name>
+  /ez:hotfix complete <name> <version>
+```
+Exit.
+
+## 2. Handle "start" Subcommand
+
+### 2a. Load current state
+
+```bash
+# Current branch
+CURRENT_BRANCH=$(git branch --show-current)
+
+# Current version
+CURRENT_VERSION=$(node -e "console.log(require('./package.json').version)" 2>/dev/null || echo "0.0.0")
+
+# Load tier from config
+TIER=$(node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" config-get release.tier 2>/dev/null || echo "mvp")
+
+# Last tag
+LAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "none")
+```
+
+### 2b. Check for uncommitted changes
+
+```bash
+git status --short
+```
+
+**If uncommitted changes:** Error — "Stash or commit current work before creating a hotfix"
+
+### 2c. Create hotfix branch
+
+```bash
+# Get hotfix branch name
+HOTFIX_BRANCH=$(node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" hotfix-branch-name "${NAME}")
+# Returns: hotfix/{name-slug}
+
+# Branch from main (or last release tag if available)
+SOURCE=$(git rev-parse --verify "${LAST_TAG}" 2>/dev/null && echo "${LAST_TAG}" || echo "main")
+
+git checkout "${SOURCE}"
+git checkout -b "${HOTFIX_BRANCH}"
+```
+
+### 2d. Report to user
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ EZ ► HOTFIX STARTED: {HOTFIX_BRANCH}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Branch:   {HOTFIX_BRANCH}
+From:     {SOURCE} ({CURRENT_VERSION})
+Tier:     {TIER}
+
+Make your fix, commit it, then complete:
+/ez:hotfix complete {NAME} {NEXT_PATCH_VERSION}
+
+Example:
+  Current: {CURRENT_VERSION}
+  Next:    {NEXT_PATCH_SUGGESTION}
+```
+
+Suggest next patch version: increment patch number (1.2.3 → 1.2.4).
+
+**STOP here for `start` subcommand.**
+
+---
+
+## 3. Handle "complete" Subcommand
+
+### 3a. Validate state
+
+```bash
+# Confirm on hotfix branch
+CURRENT_BRANCH=$(git branch --show-current)
+EXPECTED_BRANCH=$(node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" hotfix-branch-name "${NAME}")
+
+if [ "$CURRENT_BRANCH" != "$EXPECTED_BRANCH" ]; then
+  echo "ERROR: Not on hotfix branch. Expected: ${EXPECTED_BRANCH}, got: ${CURRENT_BRANCH}"
+  exit 1
+fi
+
+# Check for uncommitted changes
+git status --short
+```
+
+**If uncommitted changes:** Error — "Commit your fix before completing the hotfix"
+
+### 3b. Validate version is semver
+
+```bash
+echo "${VERSION}" | grep -E "^[0-9]+\.[0-9]+\.[0-9]+$"
+```
+
+**If invalid:** Error — "Version must be semver (X.Y.Z)"
+
+### 3c. Run security gates
+
+```bash
+node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" release security-gates
+```
+
+**If secrets found:** Error — "Remove secrets before completing hotfix"
+**If critical vulns:** Warning (not hard block for hotfix — speed matters)
+
+### 3d. Run tests
+
+```bash
+npm test 2>/dev/null || yarn test 2>/dev/null || echo "WARNING: No test command found"
+```
+
+**If tests fail:** Warning — "Tests failing. Hotfix will be tagged but verify before pushing."
+
+### 3e. Load tier and git strategy
+
+```bash
+TIER=$(node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" config-get release.tier 2>/dev/null || echo "mvp")
+```
+
+Determine sync target:
+- MVP/Medium: No sync needed (just main)
+- Enterprise: Also sync to develop
+
+### 3f. Generate changelog entry
+
+```bash
+LAST_TAG=$(git describe --tags --abbrev=0 main 2>/dev/null || echo "")
+if [ -n "$LAST_TAG" ]; then
+  COMMITS=$(git log ${LAST_TAG}..HEAD --oneline --no-merges)
+fi
+```
+
+Format entry for CHANGELOG.md:
+```markdown
+## [{VERSION}] — {date} (hotfix)
+
+### Bug Fixes
+- {fix commit message(s)}
+```
+
+### 3g. Merge to main
+
+```bash
+git checkout main
+git merge --no-ff "${HOTFIX_BRANCH}" -m "hotfix(release): merge ${HOTFIX_BRANCH} for v${VERSION}"
+```
+
+**If merge conflict:**
+```
+MERGE CONFLICT during hotfix merge.
+Resolve conflicts in: {conflicting files}
+Then run: git commit && /ez:hotfix complete {NAME} {VERSION}
+```
+STOP.
+
+### 3h. Bump version and update changelog
+
+```bash
+# Bump version in package.json
+node -e "
+  const pkg = JSON.parse(require('fs').readFileSync('package.json'));
+  pkg.version = '${VERSION}';
+  require('fs').writeFileSync('package.json', JSON.stringify(pkg, null, 2) + '\n');
+"
+
+# Update CHANGELOG.md (prepend entry)
+```
+
+### 3i. Create rollback plan
+
+Write to `.planning/releases/v${VERSION}-ROLLBACK-PLAN.md` using rollback-plan template.
+
+### 3j. Commit and tag
+
+```bash
+git add CHANGELOG.md package.json .planning/releases/
+git commit -m "chore(hotfix): v${VERSION} — ${NAME}
+
+Hotfix: ${NAME}
+Previous: v${PREVIOUS_VERSION}"
+
+git tag -a "v${VERSION}" -m "Hotfix v${VERSION}: ${NAME}"
+```
+
+### 3k. Sync to develop (Enterprise tier only)
+
+```bash
+if [ "$TIER" = "enterprise" ]; then
+  # Check if develop exists
+  git rev-parse --verify develop 2>/dev/null
+  if [ $? -eq 0 ]; then
+    git checkout develop
+  fi
+fi
+```
+
+### Enterprise: Sync hotfix ke develop
+
+1. Cek apakah sync akan conflict:
+   ```
+   git merge-base --is-ancestor v{version} develop
+   ```
+
+2. Jika tidak conflict → `git merge v{version} --no-ff -m "chore: sync hotfix v{version} to develop"`
+
+3. **Jika CONFLICT terdeteksi:**
+   - Jangan auto-merge. Beri instruksi eksplisit:
+   ```
+   ⚠️ MERGE CONFLICT: Hotfix sync ke develop memerlukan manual resolution.
+
+   Langkah:
+   a. git checkout develop
+   b. git merge v{version}
+   c. Resolve conflicts di file yang di-list git
+   d. git add . && git merge --continue
+   e. git push origin develop
+
+   PENTING: Hotfix SUDAH di production (main + tag).
+   Develop conflict tidak memblokir hotfix — selesaikan setelah production stabil.
+   ```
+
+### 3l. Clean up hotfix branch (optional)
+
+```bash
+git branch -d "${HOTFIX_BRANCH}"
+```
+
+### 3m. Report completion
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ EZ ► HOTFIX COMPLETE: v{VERSION} ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Hotfix:   {NAME}
+Version:  v{VERSION}
+Tag:      v{VERSION}
+Changelog: Updated
+Rollback:  .planning/releases/v{VERSION}-ROLLBACK-PLAN.md
+
+{If enterprise:}
+Synced to develop: ✓
+
+### To Ship
+git push origin main && git push origin v{VERSION}
+
+{If enterprise:}
+git push origin develop
+```
+
+</process>
+
+<success_criteria>
+
+### start
+- [ ] Uncommitted changes check passed
+- [ ] Hotfix branch created from main (or last tag)
+- [ ] User sees branch name and complete instructions
+
+### complete
+- [ ] On correct hotfix branch
+- [ ] Security gates run
+- [ ] Tests run (warn if fail, don't block)
+- [ ] Changelog entry generated
+- [ ] Merged to main with no-ff
+- [ ] Version bumped in package.json
+- [ ] Rollback plan created
+- [ ] Release tagged
+- [ ] Develop synced (enterprise tier only)
+- [ ] Hotfix branch cleaned up
+- [ ] User sees push instructions
+
+</success_criteria>

package/ez-agents/workflows/import-session.md

@@ -0,0 +1,303 @@
+# Workflow: import-session
+
+**Purpose:** Import session data from exported file
+
+**Related Commands:** `/ez:import-session`
+
+---
+
+## Workflow Steps
+
+### 1. Parameters
+
+```
+file_path: string (required)
+source_model: string (optional) - For model-specific adapters
+```
+
+### 2. Validate Input
+
+```
+// Check file exists
+if (!fs.existsSync(file_path)) {
+  throw error(`File not found: ${file_path}`);
+}
+
+// Check file is .json
+if (!file_path.endsWith('.json')) {
+  throw error("Import file must be .json format");
+}
+
+// Try to parse JSON
+try {
+  content = fs.readFileSync(file_path, 'utf-8');
+  importedData = JSON.parse(content);
+} catch (err) {
+  throw error(`Invalid JSON: ${err.message}`);
+}
+```
+
+### 3. Import Session
+
+```
+SessionManager mgr = new SessionManager();
+SessionImport importer = new SessionImport(mgr);
+
+const options = {};
+if (source_model) {
+  options.sourceModel = source_model;
+}
+
+try {
+  result = importer.import(file_path, options);
+} catch (SessionImportError err) {
+  logger.error('Import failed', { file: file_path, error: err.message });
+  
+  // Display user-friendly error
+  output(`Import failed: ${err.message}`);
+  
+  if (err.validationErrors && err.validationErrors.length > 0) {
+    output("\nValidation errors:");
+    for (error of err.validationErrors) {
+      output(`  - ${error}`);
+    }
+  }
+  
+  output("\nSuggested fix:");
+  output("  Ensure the file is a valid session export from /ez:export-session");
+  
+  throw error;
+}
+```
+
+### 4. Validate Imported Session
+
+```
+// Check required fields
+session = importedData.session || importedData;
+
+requiredFields = ['metadata', 'context'];
+missingFields = [];
+
+for (field of requiredFields) {
+  if (!session[field]) {
+    missingFields.push(field);
+  }
+}
+
+if (missingFields.length > 0) {
+  warnings.push(`Missing optional fields: ${missingFields.join(', ')}`);
+}
+
+// Check session_chain integrity
+if (session.metadata?.session_chain) {
+  for (chainId of session.metadata.session_chain) {
+    linkedSession = mgr.loadSession(chainId);
+    if (!linkedSession) {
+      warnings.push(`Missing linked session: ${chainId}`);
+    }
+  }
+}
+```
+
+### 5. Create or Update Session
+
+```
+// Check if session_id already exists
+existingSession = mgr.loadSession(result.sessionId);
+
+if (existingSession) {
+  // Generate new session_id with timestamp suffix
+  timestamp = Date.now();
+  newSessionId = `${result.sessionId}-imported-${timestamp}`;
+  
+  // Create new session with modified ID
+  mgr.createSession({
+    model: session.metadata?.model,
+    phase: session.metadata?.phase,
+    plan: session.metadata?.plan
+  });
+  
+  // Update with imported data
+  mgr.updateSession(newSessionId, {
+    context: session.context,
+    state: session.state,
+    metadata: {
+      ...session.metadata,
+      session_id: newSessionId,
+      session_chain: [...(session.metadata?.session_chain || []), result.sessionId]
+    }
+  });
+  
+  result.sessionId = newSessionId;
+  logger.info('Session imported with new ID', { 
+    original: result.sessionId, 
+    new: newSessionId 
+  });
+} else {
+  // Update existing session created by importer
+  mgr.updateSession(result.sessionId, {
+    context: session.context,
+    state: session.state
+  });
+}
+```
+
+### 6. Log Success
+
+```
+logger.info('Session imported', { 
+  new_session_id: result.sessionId, 
+  source_file: file_path 
+});
+```
+
+### 7. Return Result
+
+```
+return {
+  success: true,
+  session_id: result.sessionId,
+  warnings: warnings || []
+};
+```
+
+---
+
+## Import Confirmation Display
+
+```
+Session imported successfully!
+
+Session ID: {sessionId}
+Source: {file_path}
+Original model: {model}
+Original phase: {phase}
+Original plan: {plan}
+
+{warnings.length > 0 ? `Warnings:\n  - ${warnings.join('\n  - ')}` : ''}
+```
+
+---
+
+## Session Summary Display
+
+```
+Session Summary:
+
+Tasks Completed: {completedTasks.length}
+Tasks Incomplete: {incompleteTasks.length}
+Key Decisions: {decisions.length}
+File Changes: {fileChanges.length}
+
+Incomplete Tasks:
+{incompleteTasks.map(t => `  - ${t}`).join('\n')}
+
+Recommended Next Action:
+  {nextAction}
+```
+
+---
+
+## Follow-up Actions
+
+```
+What would you like to do?
+
+1. Resume this session
+2. View session chain
+3. Return to current session
+4. Export this session
+```
+
+---
+
+## Error Handling
+
+### File Not Found
+```
+if (!fs.existsSync(file_path)) {
+  throw error(`File not found: ${file_path}`);
+}
+```
+
+### Invalid JSON
+```
+try {
+  importedData = JSON.parse(content);
+} catch (err) {
+  throw error(`Invalid JSON format: ${err.message}`);
+}
+```
+
+### Missing Required Fields
+```
+if (!session.metadata || !session.context) {
+  throw error("Invalid session format: Missing metadata or context");
+}
+```
+
+### Circular Chain Reference
+```
+if (session.metadata?.session_chain?.includes(session.metadata.session_id)) {
+  throw error("Invalid session chain: Circular reference detected");
+}
+```
+
+---
+
+## Model-Specific Adapters
+
+### Claude Format
+```javascript
+_adaptClaudeFormat(data) {
+  // Claude may export with different structure
+  // Adapt to standard session format
+  return {
+    metadata: {
+      session_id: data.id || data.session_id,
+      model: 'claude',
+      ...data.metadata
+    },
+    context: data.context || data.conversation,
+    state: data.state || {}
+  };
+}
+```
+
+### Qwen Format
+```javascript
+_adaptQwenFormat(data) {
+  // Qwen standard format (already compatible)
+  return data;
+}
+```
+
+### OpenAI Format
+```javascript
+_adaptOpenAIFormat(data) {
+  // OpenAI may use different field names
+  return {
+    metadata: data.metadata || data.session_metadata,
+    context: data.context || data.messages,
+    state: data.state || {}
+  };
+}
+```
+
+### Kimi Format
+```javascript
+_adaptKimiFormat(data) {
+  // Kimi standard format (already compatible)
+  return data;
+}
+```
+
+---
+
+## Related Files
+
+- `ez-agents/bin/lib/session-manager.cjs` - Session creation
+- `ez-agents/bin/lib/session-import.cjs` - Import logic
+- `ez-agents/bin/lib/session-errors.cjs` - Error classes
+- `.planning/sessions/` - Session storage directory