@nolrm/contextkit 0.14.1 → 0.15.1

package/README.md

@@ -90,7 +90,7 @@ Each platform generates bridge files that the AI tool auto-reads. If a bridge fi
 
 - Reads `glossary.md` → `checkout` = checkout process; `customer` = customer account
 - Applies `code-style.md` → strict TS, functional components
-- Follows `testing.md` → numbered test cases
+- Follows `testing.md` → testing levels, change-driven test selection, numbered test cases
 
 **Result (diff)**
 
@@ -161,7 +161,7 @@ ContextKit installs reusable slash commands for supported platforms:
 | `/squad`               | Kick off a squad task — one task or many (auto-detects batch mode). Pushes back with clarifying questions if the task is vague. |
 | `/squad-architect`     | Design the technical plan from the PO spec                                                                                      |
 | `/squad-dev`           | Implement code following the architect plan                                                                                     |
-| `/squad-test`          | Write and run tests against acceptance criteria                                                                                 |
+| `/squad-test`          | Classify test levels, write and run tests against acceptance criteria                                                           |
 | `/squad-review`        | Review the full pipeline and give a verdict                                                                                     |
 | `/squad-doc`           | Create companion `.md` files for new/modified code after review passes                                                          |
 | `/squad-auto`          | Auto-run the full pipeline after kickoff (recommended, sequential)                                                              |

package/lib/commands/install.js

@@ -69,6 +69,7 @@ class InstallCommand {
       console.log(chalk.blue(`🔧 Adding ${requestedPlatform} integration...`));
       console.log('');
       await this.installPlatformIntegration(requestedPlatform);
+      await this.addContextKitGitignoreEntries();
       return;
     }
 
@@ -153,6 +154,9 @@ class InstallCommand {
       await this.installPlatformIntegration(chosenPlatform);
     }
 
+    // Add ephemeral ContextKit entries to .gitignore
+    await this.addContextKitGitignoreEntries();
+
     // Success message
     this.showSuccessMessage(hookChoices, chosenPlatform, projectType, packageManager);
   }
@@ -184,6 +188,31 @@ class InstallCommand {
     }
   }
 
+  async addContextKitGitignoreEntries() {
+    if (!(await fs.pathExists('.gitignore'))) return;
+
+    const entries = [
+      '.contextkit/status.json',
+      '.contextkit/status.yml',
+      '.contextkit/context.md',
+      '.contextkit/squad/',
+      '.contextkit/squad-done-*/',
+    ];
+
+    try {
+      const content = await fs.readFile('.gitignore', 'utf-8');
+      const missing = entries.filter((e) => !content.includes(e));
+      if (missing.length === 0) return;
+
+      const hasHeader = content.includes('# ContextKit');
+      const header = hasHeader ? '' : '\n# ContextKit\n';
+      const separator = content.endsWith('\n') ? '' : '\n';
+      await fs.appendFile('.gitignore', `${separator}${header}${missing.join('\n')}\n`);
+    } catch (error) {
+      console.log(chalk.yellow('⚠️  Could not update .gitignore:'), error.message);
+    }
+  }
+
   showPlatformUsage(platform) {
     const { getIntegration } = require('../integrations');
     const integration = getIntegration(platform);
@@ -422,6 +451,38 @@ Your testing standards will be automatically generated based on your existing te
 
 Run \`/analyze\` to generate this content.
 
+## Testing Levels
+
+Follow the **Testing Trophy** philosophy: integration tests are the sweet spot — they give the most confidence per test written. Unit tests cover isolated logic. E2E covers critical user paths only.
+
+> Default bias: when in doubt, write an integration test, not a unit test.
+
+### The Three Levels
+
+| Level | What it tests | Typical tools |
+|-------|--------------|--------------|
+| **Unit** | A single function, class, or component in isolation — dependencies mocked | Jest, testing-library (component only) |
+| **Integration / Page** | A full page or feature rendered with its real component tree — only external APIs/services mocked | Jest + testing-library, Supertest |
+| **E2E** | A complete user flow in a real browser or process | Playwright, Cypress |
+
+### Change-Driven Decision Table
+
+Before writing any tests, classify what changed and apply the required level(s):
+
+| What changed | Unit | Integration / Page | E2E |
+|---|:---:|:---:|:---:|
+| Pure function or utility | ✅ | — | — |
+| New CLI command or module | ✅ | ✅ (cross-command) | — |
+| UI component (used in 1 place) | ✅ | — | — |
+| UI component (used in 2+ contexts: edit/view/create/…) | ✅ | ✅ one per context | — |
+| New page or route | — | ✅ | — |
+| Multi-step user flow | — | — | ✅ |
+| Bug fix | At the level the bug was visible | | |
+
+### Context Coverage Rule
+
+If a component is rendered in **two or more contexts** (e.g. Edit page, View page, Create page), each context requires its own integration test. A single unit test is not sufficient — it cannot catch wiring bugs that only appear in context.
+
 ## ⭐ REQUIRED: Numbered Test Cases
 
 **All test cases MUST use numbered descriptions for easy tracking and debugging:**

package/lib/commands/update.js

@@ -86,7 +86,11 @@ class UpdateCommand {
       await this.refreshIntegrations();
 
       // Update version in config
-      await this.updateConfigVersion(updateInfo.latestVersion || '1.0.0');
+      await this.updateConfigVersion(
+        updateInfo.latestVersion && updateInfo.latestVersion !== 'unknown'
+          ? updateInfo.latestVersion
+          : require('../../package.json').version
+      );
 
       console.log(chalk.green('✅ ContextKit updated successfully!'));
     } catch (error) {
@@ -102,16 +106,15 @@ class UpdateCommand {
   }
 
   async checkForUpdates() {
+    const pkg = require('../../package.json');
     try {
       const axios = require('axios');
       const response = await axios.get(
-        'https://api.github.com/repos/nolrm/contextkit/releases/latest',
-        {
-          timeout: 5000,
-        }
+        `https://registry.npmjs.org/${pkg.name}/latest`,
+        { timeout: 5000 }
       );
 
-      const latestVersion = response.data.tag_name.replace('v', '');
+      const latestVersion = response.data.version;
       const currentVersion = await this.getCurrentVersion();
       const hasUpdate = this.isNewerVersion(latestVersion, currentVersion);
 
@@ -121,10 +124,11 @@ class UpdateCommand {
         latestVersion,
       };
     } catch (error) {
+      // Can't reach npm registry — skip update rather than blindly running
       return {
-        hasUpdate: true, // Assume update available if we can't check
+        hasUpdate: false,
         currentVersion: await this.getCurrentVersion(),
-        latestVersion: 'latest',
+        latestVersion: 'unknown',
         error: error.message,
       };
     }
@@ -133,9 +137,9 @@ class UpdateCommand {
   async getCurrentVersion() {
     try {
       const config = await this.parseConfig();
-      return config.version || '1.0.0';
+      return config.version || require('../../package.json').version;
     } catch {
-      return '1.0.0';
+      return require('../../package.json').version;
     }
   }
 

package/lib/integrations/cursor-integration.js

@@ -132,8 +132,8 @@ Reference: @.contextkit/standards/code-style.md
 
 ## Commands
 
-- @.contextkit/commands/create-component.md — Create component workflow
-- @.contextkit/commands/spec.md — Write a component spec before coding
+- @.contextkit/commands/dev/create-component.md — Create component workflow
+- @.contextkit/commands/dev/spec.md — Write a component spec before coding
 `;
     await this.writeGeneratedFile('.cursor/rules/contextkit-components.mdc', componentsRule);
 
@@ -154,7 +154,7 @@ Reference: @.contextkit/standards/architecture.md
 
 ## Commands
 
-- @.contextkit/commands/create-feature.md — Create feature workflow
+- @.contextkit/commands/dev/create-feature.md — Create feature workflow
 `;
     await this.writeGeneratedFile('.cursor/rules/contextkit-api.mdc', apiRule);
 
@@ -163,7 +163,7 @@ Reference: @.contextkit/standards/architecture.md
       '.cursor/prompts/analyze.md',
       `# Analyze Project
 
-Read \`.contextkit/commands/analyze.md\` and execute the analysis workflow for this project.
+Read \`.contextkit/commands/dev/analyze.md\` and execute the analysis workflow for this project.
 
 Scan the codebase structure, detect frameworks and patterns, then generate customized standards files in \`.contextkit/standards/\`.
 `
@@ -173,7 +173,7 @@ Scan the codebase structure, detect frameworks and patterns, then generate custo
       '.cursor/prompts/review.md',
       `# Code Review
 
-Read \`.contextkit/commands/review.md\` and execute the review workflow.
+Read \`.contextkit/commands/dev/review.md\` and execute the review workflow.
 
 Review current changes for correctness, standards compliance, and potential issues. Flag bugs, security concerns, and standards violations.
 `
@@ -183,7 +183,7 @@ Review current changes for correctness, standards compliance, and potential issu
       '.cursor/prompts/fix.md',
       `# Fix Bug
 
-Read \`.contextkit/commands/fix.md\` and execute the bug fix workflow.
+Read \`.contextkit/commands/dev/fix.md\` and execute the bug fix workflow.
 
 Diagnose the root cause, implement the minimal fix, and add a regression test.
 `
@@ -193,7 +193,7 @@ Diagnose the root cause, implement the minimal fix, and add a regression test.
       '.cursor/prompts/refactor.md',
       `# Refactor
 
-Read \`.contextkit/commands/refactor.md\` and execute the refactoring workflow.
+Read \`.contextkit/commands/dev/refactor.md\` and execute the refactoring workflow.
 
 Improve code structure without changing behavior, keeping tests green at every step.
 `
@@ -203,7 +203,7 @@ Improve code structure without changing behavior, keeping tests green at every s
       '.cursor/prompts/test.md',
       `# Run Tests
 
-Read \`.contextkit/commands/run-tests.md\` and execute the testing workflow.
+Read \`.contextkit/commands/dev/run-tests.md\` and execute the testing workflow.
 
 Generate or run tests for the specified code, covering happy paths, edge cases, and errors.
 `
@@ -213,7 +213,7 @@ Generate or run tests for the specified code, covering happy paths, edge cases,
       '.cursor/prompts/doc.md',
       `# Add Documentation
 
-Read \`.contextkit/commands/add-documentation.md\` and execute the documentation workflow.
+Read \`.contextkit/commands/docs/add-documentation.md\` and execute the documentation workflow.
 
 Add inline docs, README sections, and usage examples for the specified code.
 `
@@ -224,7 +224,7 @@ Add inline docs, README sections, and usage examples for the specified code.
       '.cursor/prompts/squad.md',
       `# Squad — Kickoff
 
-Read \`.contextkit/commands/squad.md\` and execute the squad kickoff workflow.
+Read \`.contextkit/commands/squad/squad.md\` and execute the squad kickoff workflow.
 
 Create the handoff file and write the PO spec for the given task. Pass the user's task description as the input.
 `
@@ -234,7 +234,7 @@ Create the handoff file and write the PO spec for the given task. Pass the user'
       '.cursor/prompts/squad-architect.md',
       `# Squad — Architect
 
-Read \`.contextkit/commands/squad-architect.md\` and execute the architect workflow.
+Read \`.contextkit/commands/squad/squad-architect.md\` and execute the architect workflow.
 
 Read the PO spec from the handoff file, design the technical approach, and write the implementation plan.
 `
@@ -244,7 +244,7 @@ Read the PO spec from the handoff file, design the technical approach, and write
       '.cursor/prompts/squad-dev.md',
       `# Squad — Dev
 
-Read \`.contextkit/commands/squad-dev.md\` and execute the dev workflow.
+Read \`.contextkit/commands/squad/squad-dev.md\` and execute the dev workflow.
 
 Follow the architect's plan to implement the code changes.
 `
@@ -254,7 +254,7 @@ Follow the architect's plan to implement the code changes.
       '.cursor/prompts/squad-test.md',
       `# Squad — Test
 
-Read \`.contextkit/commands/squad-test.md\` and execute the test workflow.
+Read \`.contextkit/commands/squad/squad-test.md\` and execute the test workflow.
 
 Write and run tests against the PO's acceptance criteria.
 `
@@ -264,7 +264,7 @@ Write and run tests against the PO's acceptance criteria.
       '.cursor/prompts/squad-review.md',
       `# Squad — Review
 
-Read \`.contextkit/commands/squad-review.md\` and execute the review workflow.
+Read \`.contextkit/commands/squad/squad-review.md\` and execute the review workflow.
 
 Review the full handoff (spec, plan, implementation, tests) and write the final verdict.
 `
@@ -274,7 +274,7 @@ Review the full handoff (spec, plan, implementation, tests) and write the final
       '.cursor/prompts/squad-auto.md',
       `# Squad Auto — Full Pipeline (recommended)
 
-Read \`.contextkit/commands/squad-auto.md\` and execute the pipeline runner workflow.
+Read \`.contextkit/commands/squad/squad-auto.md\` and execute the pipeline runner workflow.
 
 Run after kickoff. Automatically runs architect → dev → test → review for all tasks sequentially, hands-free.
 `
@@ -284,7 +284,7 @@ Run after kickoff. Automatically runs architect → dev → test → review for
       '.cursor/prompts/spec.md',
       `# Spec
 
-Read \`.contextkit/commands/spec.md\` and execute the spec workflow.
+Read \`.contextkit/commands/dev/spec.md\` and execute the spec workflow.
 
 Write a component spec (MD-first) before any code is created. Scaffold the spec file colocated with the component and wait for review before coding begins.
 `
@@ -294,7 +294,7 @@ Write a component spec (MD-first) before any code is created. Scaffold the spec
       '.cursor/prompts/ck.md',
       `# ContextKit Health Check
 
-Read \`.contextkit/commands/health-check.md\` and execute the health check workflow.
+Read \`.contextkit/commands/dev/health-check.md\` and execute the health check workflow.
 
 Check project setup, standards status, and integrations. Report what needs attention.
 `

package/lib/utils/migrations.js

@@ -11,7 +11,10 @@ class MigrationRunner {
    * @param {string} configPath - path to config.yml
    */
   async run(currentVersion, configPath) {
-    const from = currentVersion === undefined || currentVersion === null ? 0 : currentVersion;
+    const from =
+      currentVersion === undefined || currentVersion === null || Number.isNaN(currentVersion)
+        ? 0
+        : currentVersion;
 
     if (from > CURRENT_FORMAT_VERSION) {
       console.log(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nolrm/contextkit",
-  "version": "0.14.1",
+  "version": "0.15.1",
   "description": "ContextKit - Context Engineering for AI Development. Provide rich context to AI through structured MD files with standards, code guides, and documentation. Works with Cursor, Claude, Aider, VS Code Copilot, and more.",
   "main": "lib/index.js",
   "bin": {