@pingvinen/donna-assistant 0.5.0 → 0.6.0

package/README.md

@@ -123,6 +123,8 @@ Most commands are safe to run again. Want to update your role? Run `/donna:set-r
 | `/donna:add-tool` | Register an external CLI tool |
 | `/donna:run-tools` | Refresh tool data mid-day |
 | `/donna:relearn-tools` | Update tool knowledge after upgrades |
+| `/donna:help` | Conversational troubleshooting for config, storage, or skill issues |
+| `/donna:contribute-idea` | Submit a feature idea or bug report via GitHub Issues |
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pingvinen/donna-assistant",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Donna - your AI powered personal assistant",
   "bin": {
     "donna-assistant": "./bin/donna-assistant"

package/src/changelog.cjs

@@ -0,0 +1,70 @@
+"use strict";
+
+const output = require("./output.cjs");
+
+/**
+ * Changelog data keyed by version string.
+ * Each entry has categories as keys and arrays of change descriptions as values.
+ */
+const CHANGELOG = {
+    "0.5.0": {
+        "New skills": [
+            "donna:help — conversational troubleshooting and diagnostics",
+            "donna:contribute-idea — submit feature ideas via GitHub Issues",
+        ],
+        Improvements: [
+            "CONTRIBUTING.md developer guide added",
+            "Upgrade changelog shown during version bumps",
+        ],
+    },
+};
+
+/**
+ * Compare two semver strings. Returns true if a > b.
+ *
+ * @param {string} a - First version string
+ * @param {string} b - Second version string
+ * @returns {boolean}
+ */
+function semverGt(a, b) {
+    const pa = a.split(".").map(Number);
+    const pb = b.split(".").map(Number);
+    for (let i = 0; i < 3; i++) {
+        if (pa[i] > pb[i]) return true;
+        if (pa[i] < pb[i]) return false;
+    }
+    return false;
+}
+
+/**
+ * Display changelog entries for versions between fromVersion (exclusive)
+ * and toVersion (inclusive).
+ *
+ * @param {string} fromVersion - Previous version (exclusive)
+ * @param {string} toVersion - New version (inclusive)
+ */
+function displayChangelog(fromVersion, toVersion) {
+    const versionsToShow = Object.keys(CHANGELOG)
+        .filter((v) => semverGt(v, fromVersion) && !semverGt(v, toVersion))
+        .sort((a, b) => (semverGt(a, b) ? 1 : -1));
+
+    if (versionsToShow.length === 0) return;
+
+    console.log("");
+    output.info("What's new:");
+
+    for (const ver of versionsToShow) {
+        const entry = CHANGELOG[ver];
+        for (const [category, items] of Object.entries(entry)) {
+            output.info(`  ${category}:`);
+            for (const item of items) {
+                const prefix = category.toLowerCase().includes("new") ? "+" : "\u00b7";
+                output.info(`    ${prefix} ${item}`);
+            }
+        }
+    }
+
+    console.log("");
+}
+
+module.exports = { CHANGELOG, displayChangelog, semverGt };

package/src/installer.cjs

@@ -8,6 +8,7 @@ const output = require("./output.cjs");
 const version = require("./version.cjs");
 const migrator = require("./migrator.cjs");
 const providers = require("./providers/index.cjs");
+const changelog = require("./changelog.cjs");
 
 /**
  * Main installer orchestration.
@@ -50,6 +51,7 @@ async function run(options = {}) {
     // If upgrading (current version exists but differs)
     if (currentVersion && currentVersion !== packageVersion) {
         output.upgradeHeader(currentVersion, packageVersion);
+        changelog.displayChangelog(currentVersion, packageVersion);
     }
 
     // Run migrations
@@ -77,7 +79,7 @@ async function run(options = {}) {
         for (const provider of detected) {
             fs.cpSync(provider.stubSource, provider.stubTarget, { recursive: true });
             output.success(
-                `Copied donna skills (setup, add-task, done, set-role, begin-the-day, add-tool, relearn-tools, run-tools) to ${provider.stubTarget}`,
+                `Copied donna skills (setup, add-task, done, set-role, begin-the-day, add-tool, relearn-tools, run-tools, help, contribute-idea) to ${provider.stubTarget}`,
             );
         }
     } else {

package/src/output.cjs

@@ -26,4 +26,9 @@ function migrationLine(desc) {
     console.log(`  \u2713 ${desc}`);
 }
 
-module.exports = { banner, success, fail, info, upgradeHeader, migrationLine };
+function changelogHeader() {
+    console.log("");
+    console.log("  What's new:");
+}
+
+module.exports = { banner, success, fail, info, upgradeHeader, migrationLine, changelogHeader };

package/stubs/claude-code/donna/contribute-idea.md

@@ -0,0 +1,16 @@
+---
+name: donna:contribute-idea
+description: Submit a feature idea or bug report — checks for duplicates, then creates a GitHub Issue
+allowed-tools:
+  - Read
+  - Bash
+  - AskUserQuestion
+---
+
+<objective>
+Run the Donna contribute-idea workflow. This command helps users submit feature ideas or bug reports by checking for duplicates against existing GitHub Issues and the project's pending todos, then creating a new issue if the idea is novel.
+</objective>
+
+<execution_context>
+@~/.donna/workflows/contribute-idea.md
+</execution_context>

package/stubs/claude-code/donna/help.md

@@ -0,0 +1,16 @@
+---
+name: donna:help
+description: Conversational troubleshooting — diagnose issues with Donna's config, storage, skills, or tools
+allowed-tools:
+  - Read
+  - Bash
+  - AskUserQuestion
+---
+
+<objective>
+Run the Donna help workflow. This command provides interactive troubleshooting by inspecting Donna's state and guiding the user through diagnosing and resolving issues.
+</objective>
+
+<execution_context>
+@~/.donna/workflows/help.md
+</execution_context>

package/workflows/contribute-idea.md

@@ -0,0 +1,128 @@
+# Donna Contribute Idea Workflow
+
+<objective>
+Help users submit feature ideas or bug reports by checking for duplicates against existing GitHub Issues and the project's pending todos, then creating a new issue if the idea is novel.
+</objective>
+
+<step name="banner">
+Print the Donna banner:
+```
+━━━ Donna ▸ Contribute Idea ━━━
+```
+</step>
+
+<step name="check-gh-auth">
+Run via Bash:
+```bash
+gh auth status 2>&1
+```
+
+If the exit code is non-zero, print:
+```
+✗ The gh CLI is not authenticated. Run 'gh auth login' first, then re-run /donna:contribute-idea.
+```
+Stop.
+</step>
+
+<step name="ask-idea">
+Use AskUserQuestion:
+
+```
+What's your idea or bug report?
+
+Describe it in a few sentences — I'll check if something similar already exists before creating an issue.
+```
+
+Store the response as `<user_idea>`.
+</step>
+
+<step name="check-duplicates">
+Check two sources for potential duplicates.
+
+**Source 1: GitHub Issues**
+
+Run via Bash:
+```bash
+gh issue list --repo pingvinen/donna --state open --json number,title,url --limit 100
+```
+
+Parse the JSON output. Compare each issue title against `<user_idea>` using semantic similarity — judge whether the idea meaningfully overlaps with an existing issue. Do not use brittle substring matching.
+
+**Source 2: GSD pending todos from STATE.md on GitHub**
+
+Run via Bash:
+```bash
+gh api repos/pingvinen/donna/contents/.planning/STATE.md --jq '.content | @base64d'
+```
+
+Parse the `### Pending Todos` section from the decoded content. Each bullet is a pending todo. Compare each todo against `<user_idea>` using semantic similarity.
+
+**If either source has a potential match**, present the match(es) to the user:
+
+```
+I found something similar:
+
+[For GitHub Issue match:]
+→ Issue #<number>: <title>
+  <url>
+  You can upvote or comment on this issue instead of creating a new one.
+
+[For pending todo match:]
+→ Pending todo: "<todo text>"
+  This is already tracked internally.
+```
+
+Then use AskUserQuestion:
+```
+Would you like to:
+1. Create a new issue anyway (it's different enough)
+2. Skip — the existing one covers my idea
+```
+
+If the user chooses option 2, print:
+```
+✓ Thanks for checking! The existing item covers this.
+```
+Stop.
+
+If no duplicates are found, proceed to the create-issue step.
+</step>
+
+<step name="create-issue">
+Help the user create a well-formed GitHub Issue.
+
+Draft a suggested title and body based on `<user_idea>`. Use AskUserQuestion:
+
+```
+Let me help you write up the issue. Here's what I've drafted based on your idea:
+
+Title: <suggested title based on user_idea>
+
+Body:
+<suggested body with description, context, and expected behavior>
+
+Would you like to:
+1. Submit as-is
+2. Edit the title or body first
+3. Cancel
+```
+
+Handle each option:
+
+- **Option 1 (submit as-is):** Run via Bash:
+  ```bash
+  gh issue create --repo pingvinen/donna --title "<title>" --body "<body>"
+  ```
+  Print the resulting issue URL with a success message:
+  ```
+  ✓ Issue created: <url>
+  ```
+
+- **Option 2 (edit):** Use AskUserQuestion to collect edits from the user. Re-present the updated draft and repeat until the user chooses to submit or cancel.
+
+- **Option 3 (cancel):** Print:
+  ```
+  Issue cancelled.
+  ```
+  Stop.
+</step>

package/workflows/help.md

@@ -0,0 +1,155 @@
+# Donna Help Workflow
+
+<objective>
+Provide interactive troubleshooting by inspecting Donna's state and guiding the user through diagnosing and resolving issues.
+</objective>
+
+<step name="banner">
+Print the Donna banner:
+```
+━━━ Donna ▸ Help ━━━
+```
+</step>
+
+<step name="read-config">
+Read `~/.config/donna/config.md`.
+
+If the file does not exist, print:
+```
+✗ Donna is not configured. Run /donna:setup first.
+```
+Stop.
+
+Extract the `storage_repo`, `daily_folder` (default: `daily`), and `auto_push` (default: false) fields from the YAML frontmatter.
+</step>
+
+<step name="ask-problem">
+Use AskUserQuestion:
+
+```
+What do you need help with?
+
+Some things I can help diagnose:
+- Configuration issues
+- Storage repo problems
+- Skills not working
+- Tool integration issues
+- General questions about how Donna works
+
+Describe what's going on:
+```
+
+Store the response as `<user_problem>`.
+</step>
+
+<step name="diagnose">
+Based on `<user_problem>`, inspect relevant state using keyword matching to determine the category and run the appropriate checks.
+
+**Config issues** (keywords: config, setup, configure, path):
+
+Run via Bash:
+```bash
+test -d <storage_repo> && echo "EXISTS" || echo "MISSING"
+```
+```bash
+git -C <storage_repo> status 2>&1 | head -1
+```
+
+Display the contents of `~/.config/donna/config.md`. Report:
+- Whether the storage_repo path exists
+- Whether it is a valid git repository
+
+**Storage issues** (keywords: storage, repo, git, daily, file, missing):
+
+Run via Bash:
+```bash
+test -d <storage_repo> && echo "EXISTS" || echo "MISSING"
+```
+```bash
+git -C <storage_repo> status 2>&1 | head -1
+```
+```bash
+ls <storage_repo>/donna/ 2>/dev/null
+```
+```bash
+ls <storage_repo>/<daily_folder>/ 2>/dev/null | tail -5
+```
+```bash
+git -C <storage_repo> status --short 2>/dev/null
+```
+
+Report whether the storage repo exists and is a git repo, whether the donna/ subfolder is present, the most recent daily files, and any uncommitted changes.
+
+**Skill issues** (keywords: skill, command, slash, workflow, not working, error):
+
+Run via Bash:
+```bash
+ls ~/.claude/commands/donna/ 2>/dev/null
+```
+```bash
+ls ~/.donna/workflows/ 2>/dev/null
+```
+
+Read `~/.donna/version.md` with the Read tool (if it exists).
+
+Report the installed stubs and workflows, compare their counts, and print the Donna version.
+
+**Tool issues** (keywords: tool, gh, jira, integration, pull, refresh):
+
+Read `<storage_repo>/donna/tools.md` with the Read tool if it exists.
+
+For each tool found in tools.md, run via Bash:
+```bash
+which <tool_name> 2>/dev/null
+```
+
+If `gh` is a configured tool, also run:
+```bash
+gh auth status 2>&1
+```
+
+Report which tools are installed and authenticated.
+
+**General / no clear category** (catch-all when no keyword matches):
+
+Run all checks from the above categories and present a full health summary. Include:
+- Donna version (from `~/.donna/version.md`)
+- Config status (file exists, storage_repo path valid)
+- Storage status (git repo exists, donna/ and daily/ present, uncommitted changes)
+- Installed skills count (stubs in `~/.claude/commands/donna/`, workflows in `~/.donna/workflows/`)
+- Configured tools (from `<storage_repo>/donna/tools.md`)
+
+After running diagnostics, present findings clearly:
+- Use `✓` for things that look good
+- Use `✗` for things that look broken
+- Provide specific fix suggestions for each `✗` item
+</step>
+
+<step name="follow-up">
+Use AskUserQuestion:
+
+```
+Did that help? You can:
+1. Ask about something else
+2. Submit a bug report or feature idea (I'll point you to /donna:contribute-idea)
+3. Done — I'm all set
+
+What would you like to do?
+```
+
+Handle each option:
+
+- **Option 1:** Ask the user for a new description of their issue. Loop back to the diagnose step with the new question.
+
+- **Option 2:** Print:
+  ```
+  Tip: Run /donna:contribute-idea to submit ideas or bug reports via GitHub Issues.
+  ```
+  Stop.
+
+- **Option 3:** Print:
+  ```
+  ✓ Glad I could help!
+  ```
+  Stop.
+</step>