iranti 0.2.5 → 0.2.7

package/README.md

@@ -305,6 +305,12 @@ iranti mcp
 
 Use it with a project-local `.mcp.json`, and optionally add `iranti claude-hook` for `SessionStart` and `UserPromptSubmit`.
 
+Fast path:
+
+```bash
+iranti claude-setup
+```
+
 Guide: [`docs/guides/claude-code.md`](docs/guides/claude-code.md)
 
 ### Codex via MCP
@@ -318,6 +324,12 @@ codex -C /path/to/your/project
 
 When `iranti codex-setup` is run from a project directory, it automatically captures that project's `.env.iranti` as `IRANTI_PROJECT_ENV` so Codex resolves the correct Iranti instance consistently.
 
+Alias:
+
+```bash
+iranti integrate codex
+```
+
 Guide: [`docs/guides/codex.md`](docs/guides/codex.md)
 
 ### Resolve Pending Escalations

package/dist/scripts/codex-setup.js

@@ -153,11 +153,19 @@ function canUseInstalledIranti(repoRoot) {
         return false;
     }
 }
+function ensureCodexInstalled(repoRoot) {
+    try {
+        run('codex', ['--version'], repoRoot);
+    }
+    catch {
+        throw new Error('Codex CLI is not installed or not on PATH. Install Codex first, confirm `codex --version` works, then rerun `iranti codex-setup`.');
+    }
+}
 function main() {
     const options = parseArgs(process.argv.slice(2));
     const repoRoot = findPackageRoot(__dirname);
     const mcpScript = node_path_1.default.join(repoRoot, 'dist', 'scripts', 'iranti-mcp.js');
-    run('codex', ['--version'], repoRoot);
+    ensureCodexInstalled(repoRoot);
     const useInstalled = !options.useLocalScript && canUseInstalledIranti(repoRoot);
     if (!useInstalled && !node_fs_1.default.existsSync(mcpScript)) {
         throw new Error(`Missing build artifact: ${mcpScript}. Run "npm run build" first, or install iranti globally and rerun without --local-script.`);

package/dist/scripts/iranti-cli.js

@@ -644,39 +644,95 @@ async function ensureInstanceConfigured(root, name, config) {
     });
     return { envFile, instanceDir, created };
 }
-async function writeClaudeCodeProjectFiles(projectPath) {
+function makeIrantiMcpServerConfig() {
+    return {
+        command: 'iranti',
+        args: ['mcp'],
+    };
+}
+function makeClaudeHookSettings(projectEnvPath) {
+    const hookArgs = (event) => {
+        const args = ['claude-hook', '--event', event];
+        if (projectEnvPath) {
+            args.push('--project-env', projectEnvPath);
+        }
+        return args;
+    };
+    return {
+        hooks: {
+            SessionStart: [
+                {
+                    command: 'iranti',
+                    args: hookArgs('SessionStart'),
+                },
+            ],
+            UserPromptSubmit: [
+                {
+                    command: 'iranti',
+                    args: hookArgs('UserPromptSubmit'),
+                },
+            ],
+        },
+    };
+}
+async function writeClaudeCodeProjectFiles(projectPath, projectEnvPath, force = false) {
     const mcpFile = path_1.default.join(projectPath, '.mcp.json');
+    let mcpStatus = 'unchanged';
+    const irantiMcpServer = makeIrantiMcpServerConfig();
     if (!fs_1.default.existsSync(mcpFile)) {
         await writeText(mcpFile, `${JSON.stringify({
             mcpServers: {
-                iranti: {
-                    command: 'iranti',
-                    args: ['mcp'],
-                },
+                iranti: irantiMcpServer,
             },
         }, null, 2)}\n`);
+        mcpStatus = 'created';
+    }
+    else {
+        const existing = readJsonFile(mcpFile);
+        if (!existing || typeof existing !== 'object' || Array.isArray(existing)) {
+            if (!force) {
+                throw new Error(`Existing .mcp.json is not valid JSON. Re-run with --force to overwrite it: ${mcpFile}`);
+            }
+            await writeText(mcpFile, `${JSON.stringify({
+                mcpServers: {
+                    iranti: irantiMcpServer,
+                },
+            }, null, 2)}\n`);
+            mcpStatus = 'updated';
+        }
+        else {
+            const existingServers = existing.mcpServers && typeof existing.mcpServers === 'object' && !Array.isArray(existing.mcpServers)
+                ? existing.mcpServers
+                : {};
+            const hasIranti = Object.prototype.hasOwnProperty.call(existingServers, 'iranti');
+            if (!hasIranti || force) {
+                await writeText(mcpFile, `${JSON.stringify({
+                    ...existing,
+                    mcpServers: {
+                        ...existingServers,
+                        iranti: irantiMcpServer,
+                    },
+                }, null, 2)}\n`);
+                mcpStatus = 'updated';
+            }
+        }
     }
     const claudeDir = path_1.default.join(projectPath, '.claude');
     await ensureDir(claudeDir);
     const settingsFile = path_1.default.join(claudeDir, 'settings.local.json');
+    let settingsStatus = 'unchanged';
     if (!fs_1.default.existsSync(settingsFile)) {
-        await writeText(settingsFile, `${JSON.stringify({
-            hooks: {
-                SessionStart: [
-                    {
-                        command: 'iranti',
-                        args: ['claude-hook', '--event', 'SessionStart'],
-                    },
-                ],
-                UserPromptSubmit: [
-                    {
-                        command: 'iranti',
-                        args: ['claude-hook', '--event', 'UserPromptSubmit'],
-                    },
-                ],
-            },
-        }, null, 2)}\n`);
+        await writeText(settingsFile, `${JSON.stringify(makeClaudeHookSettings(projectEnvPath), null, 2)}\n`);
+        settingsStatus = 'created';
+    }
+    else if (force) {
+        await writeText(settingsFile, `${JSON.stringify(makeClaudeHookSettings(projectEnvPath), null, 2)}\n`);
+        settingsStatus = 'updated';
     }
+    return {
+        mcp: mcpStatus,
+        settings: settingsStatus,
+    };
 }
 function hasCodexInstalled() {
     try {
@@ -1133,21 +1189,29 @@ function isPathInside(parentDir, childDir) {
     const child = normalizePathForCompare(childDir);
     return child === parent || child.startsWith(`${parent}/`);
 }
-function resolveSpawnExecutable(executable) {
-    if (process.platform !== 'win32')
-        return executable;
-    if (executable === 'npm')
-        return 'npm.cmd';
-    if (executable === 'npx')
-        return 'npx.cmd';
-    return executable;
+function quoteForCmd(arg) {
+    if (arg.length === 0)
+        return '""';
+    if (!/[ \t"&()<>|^]/.test(arg))
+        return arg;
+    return `"${arg.replace(/"/g, '\\"')}"`;
 }
 function runCommandCapture(executable, args, cwd) {
-    const proc = (0, child_process_1.spawnSync)(resolveSpawnExecutable(executable), args, {
-        cwd,
-        encoding: 'utf8',
-        stdio: ['ignore', 'pipe', 'pipe'],
-    });
+    const proc = process.platform === 'win32'
+        ? (0, child_process_1.spawnSync)(process.env.ComSpec ?? 'cmd.exe', [
+            '/d',
+            '/c',
+            [executable, ...args].map(quoteForCmd).join(' '),
+        ], {
+            cwd,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'pipe'],
+        })
+        : (0, child_process_1.spawnSync)(executable, args, {
+            cwd,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
     return {
         status: proc.status,
         stdout: proc.stdout ?? '',
@@ -1155,10 +1219,19 @@ function runCommandCapture(executable, args, cwd) {
     };
 }
 function runCommandInteractive(step) {
-    const proc = (0, child_process_1.spawnSync)(resolveSpawnExecutable(step.executable), step.args, {
-        cwd: step.cwd,
-        stdio: 'inherit',
-    });
+    const proc = process.platform === 'win32'
+        ? (0, child_process_1.spawnSync)(process.env.ComSpec ?? 'cmd.exe', [
+            '/d',
+            '/c',
+            [step.executable, ...step.args].map(quoteForCmd).join(' '),
+        ], {
+            cwd: step.cwd,
+            stdio: 'inherit',
+        })
+        : (0, child_process_1.spawnSync)(step.executable, step.args, {
+            cwd: step.cwd,
+            stdio: 'inherit',
+        });
     return proc.status;
 }
 function detectPythonLauncher() {
@@ -1294,8 +1367,8 @@ function detectUpgradeContext(args) {
     const repoCheckout = fs_1.default.existsSync(path_1.default.join(packageRootPath, '.git'));
     const repoDirty = repoCheckout ? repoIsDirty(packageRootPath) : false;
     const globalNpmRoot = detectGlobalNpmRoot();
-    const globalNpmInstall = globalNpmRoot !== null && isPathInside(globalNpmRoot, packageRootPath);
-    const globalNpmVersion = globalNpmInstall ? detectGlobalNpmInstalledVersion() : null;
+    const globalNpmVersion = detectGlobalNpmInstalledVersion();
+    const globalNpmInstall = globalNpmVersion !== null;
     const python = detectPythonLauncher();
     const pythonVersion = detectPythonInstalledVersion(python);
     const availableTargets = [];
@@ -1384,16 +1457,16 @@ function describeUpgradeTarget(target) {
     const latest = target.latestVersion ?? 'unknown';
     if (target.target === 'npm-repo') {
         return target.blockedReason
-            ? `repo checkout (${current}) — ${target.blockedReason}`
-            : `repo checkout (${current}) — refresh local checkout and rebuild`;
+            ? `repo checkout (${current}) — ${target.blockedReason}`
+            : `repo checkout (${current}) — refresh local checkout and rebuild`;
     }
     if (target.upToDate === true) {
-        return `${target.target} (${current}) — already at latest ${latest}`;
+        return `${target.target} (${current}) — already at latest ${latest}`;
     }
     if (target.blockedReason) {
-        return `${target.target} (${current}) — ${target.blockedReason}`;
+        return `${target.target} (${current}) — ${target.blockedReason}`;
     }
-    return `${target.target} (${current}) — latest ${latest}`;
+    return `${target.target} (${current}) — latest ${latest}`;
 }
 async function chooseInteractiveUpgradeTargets(statuses) {
     const selected = [];
@@ -2063,7 +2136,7 @@ async function doctorCommand(args) {
             : check.status === 'warn'
                 ? warnLabel('WARN')
                 : failLabel('FAIL');
-        console.log(`${marker} ${check.name} — ${check.detail}`);
+        console.log(`${marker} ${check.name} — ${check.detail}`);
     }
     if (result.remediations.length > 0) {
         console.log('');
@@ -2736,6 +2809,151 @@ async function resolveCommand(args) {
     const escalationDir = explicitDir ? path_1.default.resolve(explicitDir) : (0, escalationPaths_1.getEscalationPaths)().root;
     await (0, resolutionist_1.resolveInteractive)(escalationDir);
 }
+function printClaudeSetupHelp() {
+    console.log([
+        'Scaffold Claude Code MCP and hook files for the current project.',
+        '',
+        'Usage:',
+        '  iranti claude-setup [path] [--project-env <path>] [--force]',
+        '  iranti claude-setup --scan <dir> [--recursive] [--force]',
+        '  iranti integrate claude [path] [--project-env <path>] [--force]',
+        '  iranti integrate claude --scan <dir> [--recursive] [--force]',
+        '',
+        'Notes:',
+        '  - Expects a project binding at .env.iranti unless --project-env is supplied.',
+        '  - Writes .mcp.json and .claude/settings.local.json.',
+        '  - Adds the Iranti MCP server to existing .mcp.json files without removing other servers.',
+        '  - Leaves existing Claude hook files untouched unless --force is supplied.',
+        '',
+        'Scan mode (--scan):',
+        '  - Scans immediate subdirectories of the given dir by default.',
+        '  - Add --recursive to scan nested project trees too.',
+        '  - Only scaffolds projects that already have a .claude subfolder.',
+        '  - No .env.iranti required - skips the per-project binding check.',
+        '  - Scan mode adds or merges .mcp.json and only creates hook settings when missing.',
+    ].join('\n'));
+}
+function shouldSkipRecursiveClaudeScanDir(name) {
+    if (name.startsWith('.'))
+        return true;
+    return [
+        'node_modules',
+        'dist',
+        'build',
+        'out',
+        'coverage',
+        '.next',
+        '.turbo',
+        '.cache',
+    ].includes(name);
+}
+function findClaudeProjects(scanDir, recursive) {
+    if (!recursive) {
+        return fs_1.default.readdirSync(scanDir, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => path_1.default.join(scanDir, entry.name))
+            .filter((candidate) => fs_1.default.existsSync(path_1.default.join(candidate, '.claude')));
+    }
+    const found = new Set();
+    const queue = [scanDir];
+    while (queue.length > 0) {
+        const current = queue.shift();
+        let entries = [];
+        try {
+            entries = fs_1.default.readdirSync(current, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        if (fs_1.default.existsSync(path_1.default.join(current, '.claude'))) {
+            found.add(current);
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            if (shouldSkipRecursiveClaudeScanDir(entry.name))
+                continue;
+            queue.push(path_1.default.join(current, entry.name));
+        }
+    }
+    found.delete(scanDir);
+    return Array.from(found).sort((a, b) => a.localeCompare(b));
+}
+async function claudeSetupCommand(args) {
+    if (hasFlag(args, 'help')) {
+        printClaudeSetupHelp();
+        return;
+    }
+    const force = hasFlag(args, 'force');
+    if (args.flags.has('scan')) {
+        const recursive = hasFlag(args, 'recursive');
+        const dirArg = getFlag(args, 'scan')
+            ?? args.positionals[0]
+            ?? (args.command === 'claude-setup' ? args.subcommand ?? undefined : undefined);
+        const scanDir = path_1.default.resolve(dirArg ?? process.cwd());
+        if (!fs_1.default.existsSync(scanDir)) {
+            throw new Error(`Scan directory not found: ${scanDir}`);
+        }
+        const candidates = findClaudeProjects(scanDir, recursive);
+        if (candidates.length === 0) {
+            console.log(`${infoLabel()} No ${recursive ? 'nested project directories' : 'subdirectories'} with a .claude folder found in ${scanDir}`);
+            return;
+        }
+        console.log(`${okLabel()} Scanning ${scanDir} - found ${candidates.length} project(s) with .claude${recursive ? ' (recursive)' : ''}`);
+        let createdMcp = 0;
+        let updatedMcp = 0;
+        let createdSettings = 0;
+        let updatedSettings = 0;
+        let unchanged = 0;
+        for (const projectPath of candidates) {
+            const result = await writeClaudeCodeProjectFiles(projectPath, undefined, force);
+            if (result.mcp === 'created')
+                createdMcp += 1;
+            if (result.mcp === 'updated')
+                updatedMcp += 1;
+            if (result.settings === 'created')
+                createdSettings += 1;
+            if (result.settings === 'updated')
+                updatedSettings += 1;
+            if (result.mcp === 'unchanged' && result.settings === 'unchanged')
+                unchanged += 1;
+            console.log(`  ${projectPath}`);
+            console.log(`    mcp       ${result.mcp}`);
+            console.log(`    settings  ${result.settings}`);
+        }
+        console.log('');
+        console.log('Summary:');
+        console.log(`  projects          ${candidates.length}`);
+        console.log(`  mcp created       ${createdMcp}`);
+        console.log(`  mcp updated       ${updatedMcp}`);
+        console.log(`  settings created  ${createdSettings}`);
+        console.log(`  settings updated  ${updatedSettings}`);
+        console.log(`  unchanged         ${unchanged}`);
+        console.log(`${infoLabel()} Done. Open each project in Claude Code to verify Iranti tools are available.`);
+        return;
+    }
+    const projectArg = args.positionals[0] ?? (args.command === 'claude-setup' ? args.subcommand ?? undefined : undefined);
+    const projectPath = path_1.default.resolve(projectArg ?? process.cwd());
+    const explicitProjectEnv = getFlag(args, 'project-env');
+    const projectEnvPath = explicitProjectEnv
+        ? path_1.default.resolve(explicitProjectEnv)
+        : path_1.default.join(projectPath, '.env.iranti');
+    if (!fs_1.default.existsSync(projectPath)) {
+        throw new Error(`Project path not found: ${projectPath}`);
+    }
+    if (!fs_1.default.existsSync(projectEnvPath)) {
+        throw new Error(`Project binding not found at ${projectEnvPath}. Run \`iranti project init\` or \`iranti configure project\` first.`);
+    }
+    const result = await writeClaudeCodeProjectFiles(projectPath, projectEnvPath, force);
+    console.log(`${okLabel()} Claude Code integration scaffolded`);
+    console.log(`  project   ${projectPath}`);
+    console.log(`  binding   ${projectEnvPath}`);
+    console.log(`  mcp       ${path_1.default.join(projectPath, '.mcp.json')}`);
+    console.log(`  settings  ${path_1.default.join(projectPath, '.claude', 'settings.local.json')}`);
+    console.log(`  mcp status      ${result.mcp}`);
+    console.log(`  settings status ${result.settings}`);
+    console.log(`${infoLabel()} Next: open Claude Code in this project and verify Iranti tools are available.`);
+}
 async function chatCommand(args) {
     const provider = normalizeProvider(getFlag(args, 'provider'));
     if (provider && !isSupportedProvider(provider)) {
@@ -2788,8 +3006,13 @@ Project-level:
 
 Integrations:
   iranti mcp [--help]
+  iranti claude-setup [path] [--project-env <path>] [--force]
+  iranti claude-setup --scan <dir> [--force]
   iranti claude-hook --event SessionStart|UserPromptSubmit [--project-env <path>] [--instance-env <path>] [--env-file <path>]
   iranti codex-setup [--name iranti] [--agent codex_code] [--source Codex] [--provider openai] [--project-env <path>] [--local-script]
+  iranti integrate claude [path] [--project-env <path>] [--force]
+  iranti integrate claude --scan <dir> [--force]
+  iranti integrate codex [--name iranti] [--agent codex_code] [--source Codex] [--provider openai] [--project-env <path>] [--local-script]
   `);
 }
 async function main() {
@@ -2895,6 +3118,10 @@ async function main() {
         await handoffToScript('iranti-mcp', process.argv.slice(3));
         return;
     }
+    if (args.command === 'claude-setup') {
+        await claudeSetupCommand(args);
+        return;
+    }
     if (args.command === 'claude-hook') {
         await handoffToScript('claude-code-memory-hook', process.argv.slice(3));
         return;
@@ -2903,6 +3130,17 @@ async function main() {
         await handoffToScript('codex-setup', process.argv.slice(3));
         return;
     }
+    if (args.command === 'integrate') {
+        if (args.subcommand === 'claude') {
+            await claudeSetupCommand(args);
+            return;
+        }
+        if (args.subcommand === 'codex') {
+            await handoffToScript('codex-setup', process.argv.slice(4));
+            return;
+        }
+        throw new Error(`Unknown integrate target '${args.subcommand ?? ''}'. Use 'claude' or 'codex'.`);
+    }
     throw new Error(`Unknown command '${args.command}'. Run: iranti help`);
 }
 main().catch((err) => {

package/dist/scripts/iranti-mcp.js

@@ -144,7 +144,7 @@ async function main() {
     await ensureDefaultAgent(iranti);
     const server = new mcp_js_1.McpServer({
         name: 'iranti-mcp',
-        version: '0.2.5',
+        version: '0.2.7',
     });
     server.registerTool('iranti_handshake', {
         description: `Initialize or refresh an agent's working-memory brief for the current task.

package/dist/scripts/seed.js

@@ -15,7 +15,7 @@ const STAFF_ENTRIES = [
         entityId: 'librarian',
         key: 'operating_rules',
         valueRaw: {
-            version: '0.2.5',
+            version: '0.2.7',
             rules: [
                 'All writes from external agents go through the Librarian — never directly to the database',
                 'Check for existing entries before every write',
@@ -39,7 +39,7 @@ const STAFF_ENTRIES = [
         entityId: 'attendant',
         key: 'operating_rules',
         valueRaw: {
-            version: '0.2.5',
+            version: '0.2.7',
             rules: [
                 'Assigned one-per-external-agent — serve the agent, not the user',
                 'On handshake: read AGENTS.md and MCP config, query Librarian for relevant rules and task context',
@@ -61,7 +61,7 @@ const STAFF_ENTRIES = [
         entityId: 'archivist',
         key: 'operating_rules',
         valueRaw: {
-            version: '0.2.5',
+            version: '0.2.7',
             rules: [
                 'Run on schedule or when conflict flags exceed threshold — not on every write',
                 'Scan for expired, low-confidence, flagged, and duplicate entries',
@@ -82,7 +82,7 @@ const STAFF_ENTRIES = [
         entityType: 'system',
         entityId: 'library',
         key: 'schema_version',
-        valueRaw: { version: '0.2.5' },
+        valueRaw: { version: '0.2.7' },
         valueSummary: 'Current Library schema version.',
         confidence: 100,
         source: 'seed',
@@ -95,7 +95,7 @@ const STAFF_ENTRIES = [
         key: 'initialization_log',
         valueRaw: {
             initializedAt: new Date().toISOString(),
-            seedVersion: '0.2.5',
+            seedVersion: '0.2.7',
         },
         valueSummary: 'Record of when and how this Library was initialized.',
         confidence: 100,
@@ -108,7 +108,7 @@ const STAFF_ENTRIES = [
         entityId: 'ontology',
         key: 'core_schema',
         valueRaw: {
-            version: '0.2.5',
+            version: '0.2.7',
             states: ['candidate', 'provisional', 'canonical'],
             coreEntityTypes: [
                 'person',
@@ -156,7 +156,7 @@ const STAFF_ENTRIES = [
         entityId: 'ontology',
         key: 'extension_registry',
         valueRaw: {
-            version: '0.2.5',
+            version: '0.2.7',
             namespaces: {
                 education: {
                     status: 'provisional',
@@ -187,7 +187,7 @@ const STAFF_ENTRIES = [
         entityId: 'ontology',
         key: 'candidate_terms',
         valueRaw: {
-            version: '0.2.5',
+            version: '0.2.7',
             terms: [],
         },
         valueSummary: 'Staging area for ontology terms detected repeatedly but not yet promoted.',
@@ -201,7 +201,7 @@ const STAFF_ENTRIES = [
         entityId: 'ontology',
         key: 'promotion_policy',
         valueRaw: {
-            version: '0.2.5',
+            version: '0.2.7',
             candidateToProvisional: {
                 minSeenCount: 3,
                 minDistinctAgents: 2,
@@ -237,7 +237,7 @@ const STAFF_ENTRIES = [
         entityId: 'ontology',
         key: 'change_log',
         valueRaw: {
-            version: '0.2.5',
+            version: '0.2.7',
             events: [
                 {
                     at: new Date().toISOString(),

package/dist/src/api/server.js

@@ -69,7 +69,7 @@ app.use(express_1.default.json({ limit: process.env.IRANTI_MAX_BODY_BYTES ?? '25
 app.get(ROUTES.health, (_req, res) => {
     res.json({
         status: 'ok',
-        version: '0.2.5',
+        version: '0.2.7',
         provider: process.env.LLM_PROVIDER ?? 'mock',
     });
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "iranti",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "description": "Memory infrastructure for multi-agent AI systems",
   "main": "dist/src/sdk/index.js",
   "files": [