@devness/useai 0.3.6 → 0.3.8

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 useai.dev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.js

@@ -264,7 +264,8 @@ function createTool(def) {
     remove: () => {
       handler.remove(def.configPath);
       if (def.instructions) removeInstructions(def.instructions);
-    }
+    },
+    getManualHint: () => def.instructions ? null : def.manualHint ?? null
   };
 }
 function matchesTool(tool, query) {
@@ -288,10 +289,16 @@ function resolveTools(names) {
   }
   return { matched, unmatched };
 }
-var MCP_ENTRY, home, INSTRUCTIONS_START, INSTRUCTIONS_END, USEAI_INSTRUCTIONS, USEAI_INSTRUCTIONS_BLOCK, formatHandlers, appSupport, AI_TOOLS;
+var USEAI_INSTRUCTIONS_TEXT, MCP_ENTRY, home, INSTRUCTIONS_START, INSTRUCTIONS_END, USEAI_INSTRUCTIONS, USEAI_INSTRUCTIONS_BLOCK, formatHandlers, appSupport, AI_TOOLS;
 var init_tools = __esm({
   "src/tools.ts"() {
     "use strict";
+    USEAI_INSTRUCTIONS_TEXT = [
+      "## UseAI Session Tracking",
+      "- At the START of every conversation, call `useai_session_start` with the appropriate task_type.",
+      "- For LONG sessions (15+ min), call `useai_heartbeat` periodically.",
+      "- At the END of every conversation, call `useai_session_end` with languages used, files_touched_count, and milestones (generic descriptions only \u2014 no project names, file paths, or company names)."
+    ].join("\n");
     MCP_ENTRY = {
       command: "npx",
       args: ["-y", "@devness/useai"]
@@ -330,7 +337,8 @@ ${INSTRUCTIONS_END}`;
         name: "Cursor",
         configFormat: "standard",
         configPath: join3(home, ".cursor", "mcp.json"),
-        detect: () => existsSync3(join3(home, ".cursor"))
+        detect: () => existsSync3(join3(home, ".cursor")),
+        manualHint: "Open Cursor Settings \u2192 Rules \u2192 User Rules and paste the instructions below."
       }),
       createTool({
         id: "windsurf",
@@ -369,7 +377,8 @@ ${INSTRUCTIONS_END}`;
         name: "Zed",
         configFormat: "zed",
         configPath: join3(appSupport, "Zed", "settings.json"),
-        detect: () => existsSync3(join3(appSupport, "Zed"))
+        detect: () => existsSync3(join3(appSupport, "Zed")),
+        manualHint: "Open Rules Library (\u2318\u2325L) \u2192 click + \u2192 paste the instructions below."
       }),
       createTool({
         id: "cline",
@@ -412,14 +421,16 @@ ${INSTRUCTIONS_END}`;
         name: "Amazon Q CLI",
         configFormat: "standard",
         configPath: join3(home, ".aws", "amazonq", "mcp.json"),
-        detect: () => hasBinary("q") || existsSync3(join3(home, ".aws", "amazonq"))
+        detect: () => hasBinary("q") || existsSync3(join3(home, ".aws", "amazonq")),
+        manualHint: "Create .amazonq/rules/useai.md in your project root with the instructions below."
       }),
       createTool({
         id: "amazon-q-ide",
         name: "Amazon Q IDE",
         configFormat: "standard",
         configPath: join3(home, ".aws", "amazonq", "default.json"),
-        detect: () => existsSync3(join3(home, ".amazonq")) || existsSync3(join3(home, ".aws", "amazonq"))
+        detect: () => existsSync3(join3(home, ".amazonq")) || existsSync3(join3(home, ".aws", "amazonq")),
+        manualHint: "Create .amazonq/rules/useai.md in your project root with the instructions below."
       }),
       createTool({
         id: "codex",
@@ -450,7 +461,8 @@ ${INSTRUCTIONS_END}`;
         name: "Junie",
         configFormat: "standard",
         configPath: join3(home, ".junie", "mcp", "mcp.json"),
-        detect: () => existsSync3(join3(home, ".junie"))
+        detect: () => existsSync3(join3(home, ".junie")),
+        manualHint: "Add the instructions below to .junie/guidelines.md in your project root."
       })
     ];
   }
@@ -481,6 +493,21 @@ function err(text) {
 function dim(text) {
   return chalk.dim(`  ${text}`);
 }
+function showManualHints(installedTools) {
+  const hints = installedTools.map((t) => ({ name: t.name, hint: t.getManualHint() })).filter((h) => h.hint !== null);
+  if (hints.length === 0) return;
+  console.log(chalk.yellow(`
+  \u26A0 Manual setup needed for ${hints.length} tool${hints.length === 1 ? "" : "s"}:
+`));
+  for (const { name, hint } of hints) {
+    console.log(`  ${chalk.bold(name)}: ${hint}`);
+  }
+  console.log(chalk.dim("\n  \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510"));
+  for (const line of USEAI_INSTRUCTIONS_TEXT.split("\n")) {
+    console.log(chalk.dim("  \u2502 ") + line);
+  }
+  console.log(chalk.dim("  \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n"));
+}
 function showStatus(tools) {
   console.log(header("AI Tool MCP Status"));
   const rows = [];
@@ -520,6 +547,7 @@ async function installFlow(tools, autoYes, explicit) {
         console.log(err(`\u2717 ${tool.name.padEnd(18)} \u2014 ${e.message}`));
       }
     }
+    showManualHints(tools);
     console.log();
     return;
   }
@@ -585,6 +613,7 @@ async function installFlow(tools, autoYes, explicit) {
     } catch {
     }
   }
+  showManualHints([...toInstall, ...alreadyConfigured]);
   console.log(`
   Done! UseAI MCP server configured in ${chalk.bold(String(toInstall.length))} tool${toInstall.length === 1 ? "" : "s"}.
 `);
@@ -1049,7 +1078,7 @@ var server = new McpServer({
 });
 server.tool(
   "useai_session_start",
-  "Start tracking an AI coding session. Call this at the beginning of a conversation. Records which AI tool and task type \u2014 stored LOCALLY at ~/.useai/. No data is sent anywhere. No code, prompts, or private data is captured.",
+  "Start tracking an AI coding session. Call this at the beginning of a conversation.",
   {
     task_type: z2.enum(["coding", "debugging", "testing", "planning", "reviewing", "documenting", "learning", "other"]).optional().describe("What kind of task is the developer working on?")
   },
@@ -1067,8 +1096,7 @@ server.tool(
         {
           type: "text",
           text: `useai session started \u2014 tracking ${sessionTaskType} session on ${clientName}.
-Session: ${sessionId.slice(0, 8)} \xB7 Chain: ${record.hash.slice(0, 12)} (${signingAvailable ? "signed" : "unsigned"})
-All data stored locally at ${USEAI_DIR}. No network calls made.`
+Session: ${sessionId.slice(0, 8)} \xB7 Chain: ${record.hash.slice(0, 12)} (${signingAvailable ? "signed" : "unsigned"})`
         }
       ]
     };
@@ -1076,7 +1104,7 @@ All data stored locally at ${USEAI_DIR}. No network calls made.`
 );
 server.tool(
   "useai_heartbeat",
-  "Record a heartbeat for the current AI coding session. Call this periodically during long conversations (every 10-15 minutes). Only records a timestamp \u2014 stored locally, never sent anywhere.",
+  "Record a heartbeat for the current AI coding session. Call this periodically during long conversations (every 10-15 minutes).",
   {},
   async () => {
     incrementHeartbeat();
@@ -1088,7 +1116,7 @@ server.tool(
       content: [
         {
           type: "text",
-          text: `Heartbeat recorded locally. Session active for ${formatDuration(getSessionDuration())}.`
+          text: `Heartbeat recorded. Session active for ${formatDuration(getSessionDuration())}.`
         }
       ]
     };
@@ -1096,7 +1124,7 @@ server.tool(
 );
 server.tool(
   "useai_session_end",
-  "End the current AI coding session. Creates a cryptographically sealed session record and optionally records milestones \u2014 what was accomplished. Stats auto-sync to useai.dev daily. To publish milestones: run `useai publish` from the CLI. IMPORTANT: Milestone descriptions must be GENERIC. Do not include project names, file names, file paths, API endpoints, database names, company names, or any project-specific information. Use general terms like 'authentication system', 'data validation layer', 'responsive dashboard'. Think: would this description reveal what company or project this is for? If yes, make it more generic.",
+  "End the current AI coding session and record milestones. IMPORTANT: Milestone descriptions must be GENERIC \u2014 no project names, file names, file paths, or company names. Use general terms like 'authentication system', 'data validation layer', 'responsive dashboard'.",
   {
     task_type: z2.enum(["coding", "debugging", "testing", "planning", "reviewing", "documenting", "learning", "other"]).optional().describe("What kind of task was the developer working on?"),
     languages: z2.array(z2.string()).optional().describe("Programming languages used (e.g. ['typescript', 'python'])"),
@@ -1207,11 +1235,7 @@ server.tool(
       content: [
         {
           type: "text",
-          text: `Session sealed: ${durationStr} ${finalTaskType} on ${clientName}${langStr}
-${sessionRecordCount} chain records \xB7 ${signingAvailable ? "Ed25519 signed" : "unsigned"}${milestoneStr}
-Stored at: ${sealedPath}
-
-To publish: run \`useai sync\` from your terminal.`
+          text: `Session ended: ${durationStr} ${finalTaskType}${langStr}${milestoneStr}`
         }
       ]
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devness/useai",
-  "version": "0.3.6",
+  "version": "0.3.8",
   "description": "Track your AI-assisted development workflow. MCP server that records usage metrics across all your AI tools.",
   "keywords": [
     "mcp",
@@ -28,14 +28,6 @@
     "README.md",
     "LICENSE"
   ],
-  "scripts": {
-    "build": "tsc -p tsconfig.build.json",
-    "dev": "tsc --watch",
-    "bundle": "tsup src/index.ts --format esm --target node18 --no-splitting",
-    "prepublishOnly": "pnpm run bundle",
-    "typecheck": "tsc --noEmit",
-    "clean": "rm -rf dist"
-  },
   "dependencies": {
     "@inquirer/prompts": "^8.2.1",
     "@modelcontextprotocol/sdk": "^1.12.1",
@@ -46,9 +38,9 @@
   },
   "devDependencies": {
     "@types/node": "^22.13.4",
-    "@useai/shared": "workspace:*",
     "tsup": "^8.0.0",
-    "typescript": "^5.7.3"
+    "typescript": "^5.7.3",
+    "@useai/shared": "0.2.0"
   },
   "repository": {
     "type": "git",
@@ -57,5 +49,12 @@
   "homepage": "https://useai.dev",
   "engines": {
     "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "dev": "tsc --watch",
+    "bundle": "tsup src/index.ts --format esm --target node18 --no-splitting",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
   }
-}
+}