@dzhechkov/harness-core 0.3.10 → 0.3.12

package/dist/index.d.ts

@@ -18,6 +18,8 @@ export { benchmarkSkill, benchmarkSkills, compareSkills } from './benchmark.js';
 export { buildRegistry, searchRegistry, filterByCategory } from './registry.js';
 export { recommend } from './recommend.js';
 export { pretrain } from './pretrain.js';
+export { runSetup } from './setup.js';
+export type { SetupOptions, SetupResult, SetupStep } from './setup.js';
 export type { PretrainResult, DetectedTech } from './pretrain.js';
 export type { RecommendationReport, SkillRecommendation } from './recommend.js';
 export { discoverPackages, publishPackages } from './publish.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,yDAAyD;AACzD,eAAO,MAAM,oBAAoB,UAAU,CAAC;AAE5C,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,YAAY,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAC/E,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAClH,YAAY,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AACtH,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAChF,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAChF,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,YAAY,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAClE,YAAY,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAChF,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AACjE,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACnD,YAAY,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACxE,OAAO,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAChE,YAAY,EAAE,cAAc,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAChF,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AACjE,YAAY,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC7D,YAAY,EAAE,cAAc,EAAE,cAAc,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,yDAAyD;AACzD,eAAO,MAAM,oBAAoB,UAAU,CAAC;AAE5C,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,YAAY,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAC/E,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAClH,YAAY,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AACtH,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAChF,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAChF,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvE,YAAY,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAClE,YAAY,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAChF,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AACjE,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACnD,YAAY,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACxE,OAAO,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAChE,YAAY,EAAE,cAAc,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAChF,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AACjE,YAAY,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC7D,YAAY,EAAE,cAAc,EAAE,cAAc,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -16,6 +16,7 @@ export { benchmarkSkill, benchmarkSkills, compareSkills } from './benchmark.js';
 export { buildRegistry, searchRegistry, filterByCategory } from './registry.js';
 export { recommend } from './recommend.js';
 export { pretrain } from './pretrain.js';
+export { runSetup } from './setup.js';
 export { discoverPackages, publishPackages } from './publish.js';
 export { fetchAllDownloads } from './downloads.js';
 export { discoverInstalled, checkUpgrades } from './upgrade.js';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,yDAAyD;AACzD,MAAM,CAAC,MAAM,oBAAoB,GAAG,OAAO,CAAC;AAE5C,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhD,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAElH,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAChF,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAChF,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAGzC,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AACjE,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAEnD,OAAO,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,yDAAyD;AACzD,MAAM,CAAC,MAAM,oBAAoB,GAAG,OAAO,CAAC;AAE5C,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhD,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAElH,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAChF,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAChF,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAItC,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AACjE,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAEnD,OAAO,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC"}

package/dist/setup.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Full environment setup — skills + hooks + memory + pretrain.
+ *
+ * Unlike `dz init` (skills only), `dz setup` configures the complete
+ * self-learning environment:
+ * 1. Skills installation (via init)
+ * 2. Claude Code hooks (session-start/end for memory)
+ * 3. Memory database initialization (.dz/memory.db)
+ * 4. Pretrain (project analysis → auto-recommend)
+ *
+ * All operations are additive — never overwrites existing files.
+ *
+ * @packageDocumentation
+ */
+/** Memory backend type. */
+export type MemoryBackend = 'jsonl' | 'agentdb';
+/** Setup options. */
+export interface SetupOptions {
+    readonly projectRoot: string;
+    readonly target: string;
+    readonly preset?: string | undefined;
+    readonly memory?: MemoryBackend | undefined;
+    readonly noHooks?: boolean | undefined;
+    readonly noMemory?: boolean | undefined;
+    readonly noPretrain?: boolean | undefined;
+    readonly force?: boolean | undefined;
+}
+/** Setup result. */
+export interface SetupResult {
+    readonly steps: readonly SetupStep[];
+    readonly totalSteps: number;
+    readonly completed: number;
+    readonly skipped: number;
+}
+/** A single setup step. */
+export interface SetupStep {
+    readonly name: string;
+    readonly status: 'done' | 'skipped' | 'error';
+    readonly detail: string;
+}
+/** Run full environment setup. */
+export declare function runSetup(opts: SetupOptions): SetupResult;
+//# sourceMappingURL=setup.d.ts.map

package/dist/setup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../src/setup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAKH,2BAA2B;AAC3B,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,SAAS,CAAC;AAEhD,qBAAqB;AACrB,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,QAAQ,CAAC,MAAM,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC;IAC5C,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACxC,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC1C,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CACtC;AAED,oBAAoB;AACpB,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,EAAE,SAAS,SAAS,EAAE,CAAC;IACrC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,2BAA2B;AAC3B,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC;IAC9C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AA6ED,kCAAkC;AAClC,wBAAgB,QAAQ,CAAC,IAAI,EAAE,YAAY,GAAG,WAAW,CAwJxD"}

package/dist/setup.js

@@ -0,0 +1,249 @@
+/**
+ * Full environment setup — skills + hooks + memory + pretrain.
+ *
+ * Unlike `dz init` (skills only), `dz setup` configures the complete
+ * self-learning environment:
+ * 1. Skills installation (via init)
+ * 2. Claude Code hooks (session-start/end for memory)
+ * 3. Memory database initialization (.dz/memory.db)
+ * 4. Pretrain (project analysis → auto-recommend)
+ *
+ * All operations are additive — never overwrites existing files.
+ *
+ * @packageDocumentation
+ */
+import { existsSync, mkdirSync, writeFileSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+/** Generate Claude Code hooks configuration for self-learning. */
+function generateHooksConfig(projectRoot, backend) {
+    const dzDir = join(projectRoot, '.dz');
+    if (backend === 'agentdb') {
+        // agentdb backend: hooks use agentdb CLI to store patterns
+        const rvfPath = join(dzDir, 'memory.rvf');
+        return JSON.stringify({
+            hooks: {
+                SessionStart: [{
+                        type: 'command',
+                        command: `node -e "const fs=require('fs');const d=new Date().toISOString();try{require('child_process').execSync('npx agentdb add \\'${rvfPath}\\' \\'session-start: '+d+'\\'',{stdio:'pipe'})}catch{fs.appendFileSync('${dzDir}/sessions.jsonl',JSON.stringify({event:'start',ts:d,backend:'agentdb'})+'\\n')}"`,
+                    }],
+                SessionEnd: [{
+                        type: 'command',
+                        command: `node -e "const fs=require('fs');const d=new Date().toISOString();try{require('child_process').execSync('npx agentdb add \\'${rvfPath}\\' \\'session-end: '+d+'\\'',{stdio:'pipe'})}catch{fs.appendFileSync('${dzDir}/sessions.jsonl',JSON.stringify({event:'end',ts:d,backend:'agentdb'})+'\\n')}"`,
+                    }],
+            },
+        }, null, 2);
+    }
+    // JSONL backend (default)
+    return JSON.stringify({
+        hooks: {
+            SessionStart: [{
+                    type: 'command',
+                    command: `node -e "const fs=require('fs');const d=new Date().toISOString();fs.appendFileSync('${dzDir}/sessions.jsonl',JSON.stringify({event:'start',ts:d})+'\\n')"`,
+                }],
+            SessionEnd: [{
+                    type: 'command',
+                    command: `node -e "const fs=require('fs');const d=new Date().toISOString();fs.appendFileSync('${dzDir}/sessions.jsonl',JSON.stringify({event:'end',ts:d})+'\\n')"`,
+                }],
+        },
+    }, null, 2);
+}
+/** Generate .dz/config.json with learning settings. */
+function generateDzConfig(target, preset, backend) {
+    return JSON.stringify({
+        version: '1.0.0',
+        target,
+        preset: preset ?? null,
+        learning: {
+            enabled: true,
+            sessionTracking: true,
+            patternConsolidation: true,
+            retentionDays: 90,
+        },
+        memory: {
+            backend,
+            path: backend === 'agentdb' ? '.dz/memory.rvf' : '.dz/sessions.jsonl',
+            maxSizeMb: backend === 'agentdb' ? 100 : 10,
+            agentdb: backend === 'agentdb' ? {
+                learning: true,
+                vectorDim: 384,
+                mcpServer: 'agentdb',
+            } : undefined,
+        },
+        hooks: {
+            sessionStart: true,
+            sessionEnd: true,
+        },
+    }, null, 2);
+}
+/** Check if agentdb is available. */
+function isAgentdbAvailable() {
+    try {
+        require('child_process').execSync('npx agentdb --version', { stdio: 'pipe', timeout: 10000 });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Run full environment setup. */
+export function runSetup(opts) {
+    const steps = [];
+    const dzDir = join(opts.projectRoot, '.dz');
+    const backend = opts.memory ?? 'jsonl';
+    // Step 0: Check agentdb availability if requested
+    if (backend === 'agentdb') {
+        const available = isAgentdbAvailable();
+        if (available) {
+            steps.push({ name: 'AgentDB check', status: 'done', detail: 'agentdb available' });
+        }
+        else {
+            steps.push({ name: 'AgentDB check', status: 'error', detail: 'not found — install: npm i -g agentdb' });
+            // Fall through — will still create config, hooks will fallback to JSONL
+        }
+    }
+    // Step 1: Create .dz directory
+    if (!existsSync(dzDir)) {
+        mkdirSync(dzDir, { recursive: true });
+        steps.push({ name: 'Create .dz directory', status: 'done', detail: dzDir });
+    }
+    else {
+        steps.push({ name: 'Create .dz directory', status: 'skipped', detail: 'already exists' });
+    }
+    // Step 2: Write .dz/config.json
+    const configPath = join(dzDir, 'config.json');
+    if (!existsSync(configPath) || opts.force) {
+        writeFileSync(configPath, generateDzConfig(opts.target, opts.preset, backend));
+        steps.push({ name: 'Write .dz/config.json', status: 'done', detail: `${backend} backend` });
+    }
+    else {
+        steps.push({ name: 'Write .dz/config.json', status: 'skipped', detail: 'already exists (use --force)' });
+    }
+    // Step 3: Initialize session log
+    const sessionsPath = join(dzDir, 'sessions.jsonl');
+    if (!existsSync(sessionsPath)) {
+        writeFileSync(sessionsPath, '');
+        steps.push({ name: 'Initialize sessions.jsonl', status: 'done', detail: 'session tracking ready' });
+    }
+    else {
+        steps.push({ name: 'Initialize sessions.jsonl', status: 'skipped', detail: 'already exists' });
+    }
+    // Step 4: Initialize memory store
+    if (backend === 'agentdb') {
+        // Initialize .rvf via agentdb CLI
+        const rvfPath = join(dzDir, 'memory.rvf');
+        if (!existsSync(rvfPath)) {
+            try {
+                const { execSync } = require('child_process');
+                execSync(`npx agentdb init "${rvfPath}"`, { stdio: 'pipe', timeout: 30000 });
+                steps.push({ name: 'Initialize memory.rvf', status: 'done', detail: 'agentdb vector memory' });
+            }
+            catch {
+                // Fallback: create empty file, agentdb will init on first use
+                writeFileSync(rvfPath, '');
+                steps.push({ name: 'Initialize memory.rvf', status: 'done', detail: 'placeholder (agentdb will init on first use)' });
+            }
+        }
+        else {
+            steps.push({ name: 'Initialize memory.rvf', status: 'skipped', detail: 'already exists' });
+        }
+        // Also create JSONL fallback
+        const sessionsPath = join(dzDir, 'sessions.jsonl');
+        if (!existsSync(sessionsPath))
+            writeFileSync(sessionsPath, '');
+    }
+    else {
+        // JSONL backend
+        const sessionsPath = join(dzDir, 'sessions.jsonl');
+        if (!existsSync(sessionsPath)) {
+            writeFileSync(sessionsPath, '');
+            steps.push({ name: 'Initialize sessions.jsonl', status: 'done', detail: 'session tracking ready' });
+        }
+        else {
+            steps.push({ name: 'Initialize sessions.jsonl', status: 'skipped', detail: 'already exists' });
+        }
+        const patternsPath = join(dzDir, 'patterns.jsonl');
+        if (!existsSync(patternsPath)) {
+            writeFileSync(patternsPath, '');
+            steps.push({ name: 'Initialize patterns.jsonl', status: 'done', detail: 'pattern learning ready' });
+        }
+        else {
+            steps.push({ name: 'Initialize patterns.jsonl', status: 'skipped', detail: 'already exists' });
+        }
+    }
+    // Step 5: Configure hooks (write to .claude/settings.json)
+    if (!opts.noHooks) {
+        const settingsDir = join(opts.projectRoot, '.claude');
+        const settingsPath = join(settingsDir, 'settings.json');
+        if (!existsSync(settingsPath) || opts.force) {
+            mkdirSync(settingsDir, { recursive: true });
+            writeFileSync(settingsPath, generateHooksConfig(opts.projectRoot, backend));
+            steps.push({ name: 'Configure hooks', status: 'done', detail: `${backend} session hooks` });
+        }
+        else {
+            try {
+                const existing = JSON.parse(readFileSync(settingsPath, 'utf-8'));
+                if (!existing['hooks']) {
+                    const hooks = JSON.parse(generateHooksConfig(opts.projectRoot, backend));
+                    existing['hooks'] = hooks.hooks;
+                    writeFileSync(settingsPath, JSON.stringify(existing, null, 2));
+                    steps.push({ name: 'Configure hooks', status: 'done', detail: `merged ${backend} hooks` });
+                }
+                else {
+                    steps.push({ name: 'Configure hooks', status: 'skipped', detail: 'hooks already configured' });
+                }
+            }
+            catch {
+                steps.push({ name: 'Configure hooks', status: 'skipped', detail: 'could not parse existing settings' });
+            }
+        }
+    }
+    else {
+        steps.push({ name: 'Configure hooks', status: 'skipped', detail: '--no-hooks' });
+    }
+    // Step 5.5: Register agentdb MCP server (if agentdb backend)
+    if (backend === 'agentdb') {
+        const mcpConfigPath = join(opts.projectRoot, '.claude', 'mcp.json');
+        if (!existsSync(mcpConfigPath) || opts.force) {
+            const mcpConfig = {
+                mcpServers: {
+                    agentdb: {
+                        command: 'npx',
+                        args: ['agentdb@latest', 'mcp', 'start'],
+                    },
+                },
+            };
+            mkdirSync(join(opts.projectRoot, '.claude'), { recursive: true });
+            writeFileSync(mcpConfigPath, JSON.stringify(mcpConfig, null, 2));
+            steps.push({ name: 'Register agentdb MCP', status: 'done', detail: '41 tools available' });
+        }
+        else {
+            steps.push({ name: 'Register agentdb MCP', status: 'skipped', detail: 'mcp.json already exists' });
+        }
+    }
+    // Step 6: Update .gitignore
+    const gitignorePath = join(opts.projectRoot, '.gitignore');
+    const dzIgnoreEntry = backend === 'agentdb'
+        ? '\n# DZ Harness learning data\n.dz/memory.rvf\n.dz/sessions.jsonl\n'
+        : '\n# DZ Harness learning data\n.dz/sessions.jsonl\n.dz/patterns.jsonl\n';
+    if (existsSync(gitignorePath)) {
+        const content = readFileSync(gitignorePath, 'utf-8');
+        if (!content.includes('.dz/sessions.jsonl')) {
+            writeFileSync(gitignorePath, content + dzIgnoreEntry);
+            steps.push({ name: 'Update .gitignore', status: 'done', detail: 'added .dz/sessions.jsonl + patterns.jsonl' });
+        }
+        else {
+            steps.push({ name: 'Update .gitignore', status: 'skipped', detail: 'already ignoring .dz data' });
+        }
+    }
+    else {
+        writeFileSync(gitignorePath, dzIgnoreEntry);
+        steps.push({ name: 'Create .gitignore', status: 'done', detail: 'with .dz entries' });
+    }
+    return {
+        steps,
+        totalSteps: steps.length,
+        completed: steps.filter((s) => s.status === 'done').length,
+        skipped: steps.filter((s) => s.status === 'skipped').length,
+    };
+}
+//# sourceMappingURL=setup.js.map

package/dist/setup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup.js","sourceRoot":"","sources":["../src/setup.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dzhechkov/harness-core",
-  "version": "0.3.10",
+  "version": "0.3.12",
   "description": "Shared harness logic - skill loading, additive apply, and the init/sync/verify/doctor operations.",
   "type": "module",
   "license": "MIT",
@@ -28,9 +28,9 @@
     "@dzhechkov/adapter-claude": "0.2.0",
     "@dzhechkov/adapter-openclaude": "0.1.0",
     "@dzhechkov/adapter-opencode": "0.2.0",
-    "@dzhechkov/adapter-hermes": "0.2.0",
     "@dzhechkov/core": "0.2.0",
-    "@dzhechkov/adapter-codex": "0.2.0"
+    "@dzhechkov/adapter-codex": "0.2.0",
+    "@dzhechkov/adapter-hermes": "0.2.0"
   },
   "devDependencies": {
     "@types/node": "^25.6.0",

package/src/index.ts

@@ -20,6 +20,8 @@ export { benchmarkSkill, benchmarkSkills, compareSkills } from './benchmark.js';
 export { buildRegistry, searchRegistry, filterByCategory } from './registry.js';
 export { recommend } from './recommend.js';
 export { pretrain } from './pretrain.js';
+export { runSetup } from './setup.js';
+export type { SetupOptions, SetupResult, SetupStep } from './setup.js';
 export type { PretrainResult, DetectedTech } from './pretrain.js';
 export type { RecommendationReport, SkillRecommendation } from './recommend.js';
 export { discoverPackages, publishPackages } from './publish.js';

package/src/setup.ts

@@ -0,0 +1,277 @@
+/**
+ * Full environment setup — skills + hooks + memory + pretrain.
+ *
+ * Unlike `dz init` (skills only), `dz setup` configures the complete
+ * self-learning environment:
+ * 1. Skills installation (via init)
+ * 2. Claude Code hooks (session-start/end for memory)
+ * 3. Memory database initialization (.dz/memory.db)
+ * 4. Pretrain (project analysis → auto-recommend)
+ *
+ * All operations are additive — never overwrites existing files.
+ *
+ * @packageDocumentation
+ */
+
+import { existsSync, mkdirSync, writeFileSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/** Memory backend type. */
+export type MemoryBackend = 'jsonl' | 'agentdb';
+
+/** Setup options. */
+export interface SetupOptions {
+  readonly projectRoot: string;
+  readonly target: string;
+  readonly preset?: string | undefined;
+  readonly memory?: MemoryBackend | undefined;
+  readonly noHooks?: boolean | undefined;
+  readonly noMemory?: boolean | undefined;
+  readonly noPretrain?: boolean | undefined;
+  readonly force?: boolean | undefined;
+}
+
+/** Setup result. */
+export interface SetupResult {
+  readonly steps: readonly SetupStep[];
+  readonly totalSteps: number;
+  readonly completed: number;
+  readonly skipped: number;
+}
+
+/** A single setup step. */
+export interface SetupStep {
+  readonly name: string;
+  readonly status: 'done' | 'skipped' | 'error';
+  readonly detail: string;
+}
+
+/** Generate Claude Code hooks configuration for self-learning. */
+function generateHooksConfig(projectRoot: string, backend: MemoryBackend): string {
+  const dzDir = join(projectRoot, '.dz');
+
+  if (backend === 'agentdb') {
+    // agentdb backend: hooks use agentdb CLI to store patterns
+    const rvfPath = join(dzDir, 'memory.rvf');
+    return JSON.stringify({
+      hooks: {
+        SessionStart: [{
+          type: 'command',
+          command: `node -e "const fs=require('fs');const d=new Date().toISOString();try{require('child_process').execSync('npx agentdb add \\'${rvfPath}\\' \\'session-start: '+d+'\\'',{stdio:'pipe'})}catch{fs.appendFileSync('${dzDir}/sessions.jsonl',JSON.stringify({event:'start',ts:d,backend:'agentdb'})+'\\n')}"`,
+        }],
+        SessionEnd: [{
+          type: 'command',
+          command: `node -e "const fs=require('fs');const d=new Date().toISOString();try{require('child_process').execSync('npx agentdb add \\'${rvfPath}\\' \\'session-end: '+d+'\\'',{stdio:'pipe'})}catch{fs.appendFileSync('${dzDir}/sessions.jsonl',JSON.stringify({event:'end',ts:d,backend:'agentdb'})+'\\n')}"`,
+        }],
+      },
+    }, null, 2);
+  }
+
+  // JSONL backend (default)
+  return JSON.stringify({
+    hooks: {
+      SessionStart: [{
+        type: 'command',
+        command: `node -e "const fs=require('fs');const d=new Date().toISOString();fs.appendFileSync('${dzDir}/sessions.jsonl',JSON.stringify({event:'start',ts:d})+'\\n')"`,
+      }],
+      SessionEnd: [{
+        type: 'command',
+        command: `node -e "const fs=require('fs');const d=new Date().toISOString();fs.appendFileSync('${dzDir}/sessions.jsonl',JSON.stringify({event:'end',ts:d})+'\\n')"`,
+      }],
+    },
+  }, null, 2);
+}
+
+/** Generate .dz/config.json with learning settings. */
+function generateDzConfig(target: string, preset: string | undefined, backend: MemoryBackend): string {
+  return JSON.stringify({
+    version: '1.0.0',
+    target,
+    preset: preset ?? null,
+    learning: {
+      enabled: true,
+      sessionTracking: true,
+      patternConsolidation: true,
+      retentionDays: 90,
+    },
+    memory: {
+      backend,
+      path: backend === 'agentdb' ? '.dz/memory.rvf' : '.dz/sessions.jsonl',
+      maxSizeMb: backend === 'agentdb' ? 100 : 10,
+      agentdb: backend === 'agentdb' ? {
+        learning: true,
+        vectorDim: 384,
+        mcpServer: 'agentdb',
+      } : undefined,
+    },
+    hooks: {
+      sessionStart: true,
+      sessionEnd: true,
+    },
+  }, null, 2);
+}
+
+/** Check if agentdb is available. */
+function isAgentdbAvailable(): boolean {
+  try {
+    require('child_process').execSync('npx agentdb --version', { stdio: 'pipe', timeout: 10000 });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Run full environment setup. */
+export function runSetup(opts: SetupOptions): SetupResult {
+  const steps: SetupStep[] = [];
+  const dzDir = join(opts.projectRoot, '.dz');
+  const backend: MemoryBackend = opts.memory ?? 'jsonl';
+
+  // Step 0: Check agentdb availability if requested
+  if (backend === 'agentdb') {
+    const available = isAgentdbAvailable();
+    if (available) {
+      steps.push({ name: 'AgentDB check', status: 'done', detail: 'agentdb available' });
+    } else {
+      steps.push({ name: 'AgentDB check', status: 'error', detail: 'not found — install: npm i -g agentdb' });
+      // Fall through — will still create config, hooks will fallback to JSONL
+    }
+  }
+
+  // Step 1: Create .dz directory
+  if (!existsSync(dzDir)) {
+    mkdirSync(dzDir, { recursive: true });
+    steps.push({ name: 'Create .dz directory', status: 'done', detail: dzDir });
+  } else {
+    steps.push({ name: 'Create .dz directory', status: 'skipped', detail: 'already exists' });
+  }
+
+  // Step 2: Write .dz/config.json
+  const configPath = join(dzDir, 'config.json');
+  if (!existsSync(configPath) || opts.force) {
+    writeFileSync(configPath, generateDzConfig(opts.target, opts.preset, backend));
+    steps.push({ name: 'Write .dz/config.json', status: 'done', detail: `${backend} backend` });
+  } else {
+    steps.push({ name: 'Write .dz/config.json', status: 'skipped', detail: 'already exists (use --force)' });
+  }
+
+  // Step 3: Initialize session log
+  const sessionsPath = join(dzDir, 'sessions.jsonl');
+  if (!existsSync(sessionsPath)) {
+    writeFileSync(sessionsPath, '');
+    steps.push({ name: 'Initialize sessions.jsonl', status: 'done', detail: 'session tracking ready' });
+  } else {
+    steps.push({ name: 'Initialize sessions.jsonl', status: 'skipped', detail: 'already exists' });
+  }
+
+  // Step 4: Initialize memory store
+  if (backend === 'agentdb') {
+    // Initialize .rvf via agentdb CLI
+    const rvfPath = join(dzDir, 'memory.rvf');
+    if (!existsSync(rvfPath)) {
+      try {
+        const { execSync } = require('child_process') as typeof import('child_process');
+        execSync(`npx agentdb init "${rvfPath}"`, { stdio: 'pipe', timeout: 30000 });
+        steps.push({ name: 'Initialize memory.rvf', status: 'done', detail: 'agentdb vector memory' });
+      } catch {
+        // Fallback: create empty file, agentdb will init on first use
+        writeFileSync(rvfPath, '');
+        steps.push({ name: 'Initialize memory.rvf', status: 'done', detail: 'placeholder (agentdb will init on first use)' });
+      }
+    } else {
+      steps.push({ name: 'Initialize memory.rvf', status: 'skipped', detail: 'already exists' });
+    }
+    // Also create JSONL fallback
+    const sessionsPath = join(dzDir, 'sessions.jsonl');
+    if (!existsSync(sessionsPath)) writeFileSync(sessionsPath, '');
+  } else {
+    // JSONL backend
+    const sessionsPath = join(dzDir, 'sessions.jsonl');
+    if (!existsSync(sessionsPath)) {
+      writeFileSync(sessionsPath, '');
+      steps.push({ name: 'Initialize sessions.jsonl', status: 'done', detail: 'session tracking ready' });
+    } else {
+      steps.push({ name: 'Initialize sessions.jsonl', status: 'skipped', detail: 'already exists' });
+    }
+    const patternsPath = join(dzDir, 'patterns.jsonl');
+    if (!existsSync(patternsPath)) {
+      writeFileSync(patternsPath, '');
+      steps.push({ name: 'Initialize patterns.jsonl', status: 'done', detail: 'pattern learning ready' });
+    } else {
+      steps.push({ name: 'Initialize patterns.jsonl', status: 'skipped', detail: 'already exists' });
+    }
+  }
+
+  // Step 5: Configure hooks (write to .claude/settings.json)
+  if (!opts.noHooks) {
+    const settingsDir = join(opts.projectRoot, '.claude');
+    const settingsPath = join(settingsDir, 'settings.json');
+
+    if (!existsSync(settingsPath) || opts.force) {
+      mkdirSync(settingsDir, { recursive: true });
+      writeFileSync(settingsPath, generateHooksConfig(opts.projectRoot, backend));
+      steps.push({ name: 'Configure hooks', status: 'done', detail: `${backend} session hooks` });
+    } else {
+      try {
+        const existing = JSON.parse(readFileSync(settingsPath, 'utf-8')) as Record<string, unknown>;
+        if (!existing['hooks']) {
+          const hooks = JSON.parse(generateHooksConfig(opts.projectRoot, backend));
+          existing['hooks'] = hooks.hooks;
+          writeFileSync(settingsPath, JSON.stringify(existing, null, 2));
+          steps.push({ name: 'Configure hooks', status: 'done', detail: `merged ${backend} hooks` });
+        } else {
+          steps.push({ name: 'Configure hooks', status: 'skipped', detail: 'hooks already configured' });
+        }
+      } catch {
+        steps.push({ name: 'Configure hooks', status: 'skipped', detail: 'could not parse existing settings' });
+      }
+    }
+  } else {
+    steps.push({ name: 'Configure hooks', status: 'skipped', detail: '--no-hooks' });
+  }
+
+  // Step 5.5: Register agentdb MCP server (if agentdb backend)
+  if (backend === 'agentdb') {
+    const mcpConfigPath = join(opts.projectRoot, '.claude', 'mcp.json');
+    if (!existsSync(mcpConfigPath) || opts.force) {
+      const mcpConfig = {
+        mcpServers: {
+          agentdb: {
+            command: 'npx',
+            args: ['agentdb@latest', 'mcp', 'start'],
+          },
+        },
+      };
+      mkdirSync(join(opts.projectRoot, '.claude'), { recursive: true });
+      writeFileSync(mcpConfigPath, JSON.stringify(mcpConfig, null, 2));
+      steps.push({ name: 'Register agentdb MCP', status: 'done', detail: '41 tools available' });
+    } else {
+      steps.push({ name: 'Register agentdb MCP', status: 'skipped', detail: 'mcp.json already exists' });
+    }
+  }
+
+  // Step 6: Update .gitignore
+  const gitignorePath = join(opts.projectRoot, '.gitignore');
+  const dzIgnoreEntry = backend === 'agentdb'
+    ? '\n# DZ Harness learning data\n.dz/memory.rvf\n.dz/sessions.jsonl\n'
+    : '\n# DZ Harness learning data\n.dz/sessions.jsonl\n.dz/patterns.jsonl\n';
+  if (existsSync(gitignorePath)) {
+    const content = readFileSync(gitignorePath, 'utf-8');
+    if (!content.includes('.dz/sessions.jsonl')) {
+      writeFileSync(gitignorePath, content + dzIgnoreEntry);
+      steps.push({ name: 'Update .gitignore', status: 'done', detail: 'added .dz/sessions.jsonl + patterns.jsonl' });
+    } else {
+      steps.push({ name: 'Update .gitignore', status: 'skipped', detail: 'already ignoring .dz data' });
+    }
+  } else {
+    writeFileSync(gitignorePath, dzIgnoreEntry);
+    steps.push({ name: 'Create .gitignore', status: 'done', detail: 'with .dz entries' });
+  }
+
+  return {
+    steps,
+    totalSteps: steps.length,
+    completed: steps.filter((s) => s.status === 'done').length,
+    skipped: steps.filter((s) => s.status === 'skipped').length,
+  };
+}