pikakit 1.0.0

package/lib/agentskillskit-cli/ag-smart.js

@@ -0,0 +1,158 @@
+#!/usr/bin/env node
+/**
+ * Smart Agent CLI - ESM Version (Production-Ready)
+ * 
+ * The main interface for humans to interact with the Smart Agent Skills system.
+ * 
+ * Commands:
+ *   learn          Add new lessons to memory
+ *   recall         Check files against memory
+ *   audit          Full compliance audit
+ *   watch          Real-time file monitoring
+ *   stats          Knowledge base statistics
+ *   install-hooks  Install git pre-commit hook
+ *   lint-learn     Auto-learn from ESLint output
+ */
+
+import { spawn } from "child_process";
+import path from "path";
+import { fileURLToPath } from "url";
+import { VERSION } from "../lib/config.js";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ARGS = process.argv.slice(2);
+const COMMAND = ARGS[0];
+const SCRIPTS_DIR = path.join(__dirname, "..", "lib");
+const HOOKS_DIR = path.join(SCRIPTS_DIR, "hooks");
+
+/**
+ * Run a script with given arguments
+ * @param {string} script - Script filename (relative to lib/)
+ * @param {string[]} args - Arguments to pass
+ * @param {string} baseDir - Base directory for script
+ */
+function run(script, args = [], baseDir = SCRIPTS_DIR) {
+    const scriptPath = path.join(baseDir, script);
+    const child = spawn("node", [scriptPath, ...args], {
+        stdio: "inherit",
+        shell: true
+    });
+
+    child.on("close", (code) => {
+        process.exit(code || 0);
+    });
+
+    child.on("error", (err) => {
+        console.error(`❌ Failed to run ${script}:`, err.message);
+        process.exit(1);
+    });
+}
+
+function printHelp() {
+    console.log(`
+🤖 Agent Skill Kit CLI v${VERSION}
+
+Usage: agent <command> [options]
+
+${"─".repeat(50)}
+
+📚 CORE COMMANDS:
+
+  learn          Teach a new lesson to the memory
+                 agent learn --add --pattern "var " --message "Use let/const"
+                 agent learn --list
+                 agent learn --remove LEARN-001
+
+  recall         Check file(s) against learned patterns
+                 agent recall src/app.js
+                 agent recall ./src
+
+  audit          Run full compliance audit
+                 agent audit [directory]
+
+${"─".repeat(50)}
+
+🚀 PRODUCTION FEATURES:
+
+  watch          Real-time file monitoring
+                 agent watch [directory]
+
+  stats          Knowledge base statistics
+                 agent stats
+
+  install-hooks  Install git pre-commit hook
+                 agent install-hooks
+                 agent install-hooks --remove
+
+  lint-learn     Auto-learn from ESLint JSON output
+                 npx eslint . --format json | agent lint-learn
+
+  fix            🆕 Auto-fix violations
+                 agent fix <file|dir> [--mode safe|aggressive]
+
+  sync-skills    🆕 Sync hot patterns to SKILL.md
+                 agent sync-skills
+
+${"─".repeat(50)}
+
+📖 HELP:
+
+  help, --help   Show this help message
+  --version      Show version number
+
+💡 Docs: https://github.com/agentskillkit/agent-skills
+`);
+}
+
+// Command routing
+switch (COMMAND) {
+    // Core commands (v2 versions)
+    case "learn":
+        run("learn.js", ARGS.slice(1));
+        break;
+    case "recall":
+        run("recall.js", ARGS.slice(1));
+        break;
+    case "audit":
+        run("audit.js", ARGS.slice(1));
+        break;
+
+    // Production features
+    case "watch":
+        run("watcher.js", ARGS.slice(1));
+        break;
+    case "stats":
+        run("stats.js", ARGS.slice(1));
+        break;
+    case "install-hooks":
+        run("install-hooks.js", ARGS.slice(1), HOOKS_DIR);
+        break;
+    case "lint-learn":
+        run("lint-learn.js", ARGS.slice(1), HOOKS_DIR);
+        break;
+    case "fix":
+        run("fix.js", ARGS.slice(1));
+        break;
+    case "sync-skills":
+        run("skill-learn.js", ARGS.slice(1));
+        break;
+
+    // Meta
+    case "--version":
+    case "-v":
+        console.log(VERSION);
+        break;
+    case "help":
+    case "--help":
+    case "-h":
+        printHelp();
+        break;
+    case undefined:
+        // No command = show interactive Clack menu
+        import("../lib/ui/index.js").then(m => m.showMainMenu()).catch(console.error);
+        break;
+    default:
+        console.log(`❌ Unknown command: ${COMMAND}`);
+        console.log("   Run 'agent help' for available commands.\n");
+        process.exit(1);
+}

package/lib/agentskillskit-cli/package.json

@@ -0,0 +1,51 @@
+{
+    "name": "agentskillskit-cli",
+    "version": "3.2.0",
+    "description": "CLI for Agent Skill Kit",
+    "type": "module",
+    "main": "lib/config.js",
+    "bin": {
+        "agent": "bin/agent.js",
+        "agent": "bin/agent.js",
+        "agent-skills-kit": "bin/agent.js"
+    },
+    "scripts": {
+        "test": "vitest run",
+        "test:watch": "vitest"
+    },
+    "dependencies": {
+        "@clack/core": "^0.5.0",
+        "@clack/prompts": "^0.11.0",
+        "boxen": "^8.0.1",
+        "clipboardy": "^5.1.0",
+        "js-yaml": "^4.1.0",
+        "ora": "^9.1.0",
+        "picocolors": "^1.1.1"
+    },
+    "devDependencies": {
+        "vitest": "^1.6.0"
+    },
+    "author": "Agent Skill Kit Authors",
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/agentskillkit/agent-skills.git",
+        "directory": "packages/cli"
+    },
+    "keywords": [
+        "agent",
+        "ai",
+        "skills",
+        "cli",
+        "tooling",
+        "antigravity"
+    ],
+    "files": [
+        "bin",
+        "lib",
+        "README.md"
+    ],
+    "publishConfig": {
+        "access": "public"
+    }
+}

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "pikakit",
+  "version": "1.0.0",
+  "description": "Enterprise-grade Agent Skill Manager with Antigravity Skills support, Progressive Disclosure detection, and semantic routing validation",
+  "license": "MIT",
+  "author": "agentskillkit <agentskillkit@gmail.com>",
+  "homepage": "https://github.com/agentskillkit/pikakit",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/agentskillkit/pikakit.git"
+  },
+  "bugs": {
+    "url": "https://github.com/agentskillkit/pikakit/issues"
+  },
+  "type": "module",
+  "bin": {
+    "pikakit": "./bin/cli.mjs",
+    "kit": "./bin/cli.mjs",
+    "agent": "./lib/agent-cli/bin/agent.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "specs/",
+    "README.md",
+    "LICENSE"
+  ],
+  "types": "./lib/agent-cli/types/index.d.ts",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "agent",
+    "ai",
+    "skills",
+    "cli",
+    "tooling",
+    "registry",
+    "security",
+    "devops",
+    "automation",
+    "antigravity"
+  ],
+  "scripts": {
+    "lint": "eslint bin/",
+    "lint:fix": "eslint bin/ --fix",
+    "format": "prettier --write bin/",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "ci": "npm run lint && npm test && node bin/kit.js verify --strict && node bin/kit.js doctor --strict",
+    "agent": "agent"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@clack/core": "^0.5.0",
+    "@clack/prompts": "^0.11.0",
+    "@google/generative-ai": "^0.21.0",
+    "boxen": "^8.0.1",
+    "chalk": "^5.4.1",
+    "clipboardy": "^5.1.0",
+    "csv-parse": "^6.1.0",
+    "css-tree": "^3.1.0",
+    "dotenv": "^16.4.5",
+    "gradient-string": "^2.0.2",
+    "js-yaml": "^4.1.0",
+    "kleur": "^4.1.5",
+    "ora": "^9.1.0",
+    "picocolors": "^1.1.1",
+    "prompts": "^2.4.2"
+  },
+  "devDependencies": {
+    "agentskillskit-cli": "^3.2.0",
+    "eslint": "^8.57.0",
+    "prettier": "^3.2.5",
+    "vitest": "^4.0.18"
+  }
+}

package/specs/ADD_SKILL_SPEC.md

@@ -0,0 +1,333 @@
+# ADD_SKILL_SPEC.md  
+## Enterprise Agent Skill Specification
+
+**Status:** Stable  
+**Version:** 1.0  
+**Applies to:** `@dataguruin/add-skill >= 1.0`  
+**Audience:** Tool authors, skill publishers, platform engineers, AI agents
+
+---
+
+## 1. Purpose & Scope
+
+`@dataguruin/add-skill` defines a **deterministic, secure, and auditable system** for managing **Agent Skills**.
+
+A **Skill** is a **versioned, verifiable intelligence artifact** that extends an agent’s capabilities without executing code or mutating the host environment.
+
+This specification is **normative** and defines:
+
+- Skill format and lifecycle
+- Deterministic installation and locking
+- Security and trust guarantees
+- CLI behavior and invariants
+- Explicitly forbidden practices
+
+Any implementation that violates this specification is considered **non-compliant**.
+
+---
+
+## 2. Terminology
+
+| Term | Definition |
+|---|---|
+| Skill | A folder containing agent instructions and static resources |
+| Publisher | Entity that authors and optionally signs a skill |
+| Skill Source | Git repository + immutable ref |
+| Workspace Scope | `.agent/skills` |
+| Global Scope | `~/.gemini/antigravity/skills` |
+| Lock File | `skill-lock.json`, ensures deterministic environments |
+| Deterministic | Same inputs always produce the same skill environment |
+
+---
+
+## 3. Skill Format (MANDATORY)
+
+### 3.1 Required Files
+
+Every skill **MUST** contain the following files:
+
+```
+
+<skill-name>/
+├─ SKILL.md               # Human- and agent-readable instructions
+├─ .skill-source.json     # Auto-generated metadata (DO NOT EDIT)
+
+```
+
+If any required file is missing:
+
+- `add-skill install` → **FAIL**
+- `add-skill doctor` → **ERROR**
+
+---
+
+### 3.2 Optional Files
+
+```
+
+├─ README.md
+├─ assets/
+├─ examples/
+├─ docs/
+
+````
+
+Optional files **MUST NOT**:
+
+- Execute automatically
+- Mutate the system environment
+- Perform network calls
+- Contain secrets or credentials
+
+All optional content must be **inert by default**.
+
+---
+
+## 4. SKILL.md Rules (NON-NEGOTIABLE)
+
+`SKILL.md`:
+
+- MUST be plain Markdown
+- MUST contain instructions only
+- MUST NOT contain:
+  - secrets or credentials
+  - API keys
+  - executable code
+  - shell commands that mutate the system
+
+**Design Rule:**
+
+> A skill must be safe to read, safe to load, and safe to reason about.
+
+---
+
+## 5. Skill Metadata — `.skill-source.json`
+
+Generated automatically at install time by `add-skill`.
+
+### Schema (v1)
+
+```json
+{
+  "repo": "org/repo",
+  "skill": "skill-name",
+  "ref": "v1.2.3",
+  "checksum": "sha256:…",
+  "publisher": "org",
+  "installedAt": "ISO-8601"
+}
+````
+
+### Rules
+
+* MUST NOT be manually edited
+* `checksum` is a Merkle SHA-256 hash of the entire skill directory
+* Any checksum drift is an **integrity violation**
+
+---
+
+## 6. Skill Lifecycle
+
+### 6.1 Install
+
+```bash
+add-skill install org/repo#skill@ref
+```
+
+**Guarantees:**
+
+* Skill content matches the declared source
+* Checksum is computed and recorded
+* Scope resolution is deterministic
+
+---
+
+### 6.2 Verify
+
+```bash
+add-skill verify
+add-skill verify --strict
+```
+
+**Verification checks:**
+
+* Directory integrity
+* Checksum validity
+* Metadata presence
+
+In `--strict` mode, **any violation results in failure**.
+
+---
+
+### 6.3 Upgrade
+
+```bash
+add-skill upgrade-all
+```
+
+or
+
+```bash
+add-skill install org/repo#skill@new-ref --upgrade
+```
+
+**Rules:**
+
+* Upgrades must be explicit
+* Silent or implicit upgrades are forbidden
+* Lock file must be regenerated after upgrades
+
+---
+
+### 6.4 Lock (Deterministic Environments)
+
+```bash
+add-skill lock
+```
+
+Generates:
+
+```
+.agent/skill-lock.json
+```
+
+**Purpose:**
+
+> Ensure identical skill environments across machines, CI pipelines, and production agents.
+
+---
+
+### 6.5 Locked Install (CI / Production Mode)
+
+```bash
+add-skill install --locked
+```
+
+**Rules:**
+
+* Only skills listed in `skill-lock.json` are allowed
+* Ref overrides are forbidden
+* Any checksum mismatch results in immediate failure
+
+---
+
+## 7. Security Model
+
+### 7.1 Integrity
+
+* Merkle SHA-256 hashing
+* Directory-wide and order-independent
+* Any file modification invalidates the checksum
+
+---
+
+### 7.2 Trust Model
+
+* Skills are verified locally
+* Registries and publishers may provide signatures
+* Trust is **explicit**, never implicit
+
+---
+
+### 7.3 Execution Model
+
+* Skills MUST NOT execute code
+* No scripts are run during install
+* No network calls are allowed during install or verification
+
+---
+
+## 8. add-skill doctor (Audit & Repair)
+
+```bash
+add-skill doctor
+add-skill doctor --fix
+add-skill doctor --strict
+```
+
+**Doctor checks:**
+
+* Missing required files
+* Checksum drift
+* Lock mismatches
+* Orphaned cache entries
+
+**Guarantee:**
+
+> No mutation occurs unless `--fix` is explicitly provided.
+
+---
+
+## 9. CLI Contract (STABILITY GUARANTEE)
+
+The following flags have **guaranteed semantics**:
+
+| Flag        | Meaning                          |
+| ----------- | -------------------------------- |
+| `--verify`  | Read-only integrity verification |
+| `--strict`  | Fail on any violation            |
+| `--locked`  | Enforce deterministic lock       |
+| `--dry-run` | No filesystem changes            |
+| `--fix`     | Apply safe, explicit repairs     |
+
+Breaking changes require:
+
+* Major version bump
+* Specification update
+
+---
+
+## 10. CI/CD Integration (RECOMMENDED)
+
+```yaml
+- name: Install skills
+  run: add-skill install --locked
+
+- name: Verify skills
+  run: add-skill verify --strict
+
+- name: Audit environment
+  run: add-skill doctor --strict
+```
+
+---
+
+## 11. Forbidden Practices (HARD FAIL)
+
+The following practices are explicitly forbidden:
+
+* ❌ Auto-updating skills
+* ❌ Executable scripts inside skills
+* ❌ Mutable skills without checksum update
+* ❌ Network calls during install
+* ❌ Hidden side effects
+* ❌ Silent security bypass
+
+Violation results in failure by design.
+
+---
+
+## 12. Design Philosophy
+
+Skills are **intelligence artifacts**, not scripts.
+Trust must be explicit.
+Reproducibility is mandatory.
+Silence is a bug.
+
+`@dataguruin/add-skill` treats agent skills with the same rigor as binaries, containers, or infrastructure code.
+
+---
+
+## 13. Forward Compatibility
+
+This specification is designed to be compatible with:
+
+* Signed skill registries
+* Organization-level registries
+* Policy enforcement engines
+* Paid and licensed skills
+* Enterprise governance systems
+
+---
+
+**END OF SPEC**